diff --git a/LICENSE b/LICENSE index 55c2b5d52..9915daf4e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2014 jeaye +Copyright (c) 2014 Jesse 'Jeaye' Wilkerson Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. diff --git a/Makefile.in b/Makefile.in index 568f31ffe..de92e7e9c 100644 --- a/Makefile.in +++ b/Makefile.in @@ -32,6 +32,9 @@ CXX_FLAGS=-std=c++11 $(CXX_WARN) $(CXX_NOWARN) $(CXX_OPT) $(CXX_INCLUDE) $(CXX_P LD_PLATFORM_LIBS=%LD_PLATFORM_LIBS% LD_LIBS=-lcurl $(LD_PLATFORM_LIBS) +STDMAN_VERSION=$(shell date +"%Y.%m.%d") +CXX_FLAGS:=$(CXX_FLAGS) -DSTDMAN_VERSION=$(STDMAN_VERSION) + .PHONY: all setup clean stdman stdman_setup stdman_link generate install .SILENT: @@ -73,5 +76,5 @@ generate: stdman install: export tmp_man=$(TMP_MAN) &&\ export reference=$(REFERENCE) &&\ - export mandir=$(DESTDIR)/$(MANDIR) &&\ + export mandir=$(DESTDIR)$(MANDIR) &&\ ./do_install diff --git a/README.md b/README.md index 33edfeb4c..47830ced4 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ make generate # will build stdman and generate man pages **NOTE**: `make generate` expects sources will be in the `./reference/en/cpp` directory by default. See `./configure --help` to modify this. ### Compilation/Generation Dependencies -* C++11 (recommended GCC 4.8 or clang 3.4 or greater) +* C++11 (recommended GCC 4.9 or clang 3.4 or greater) * elinks (recommended 0.12pre6 or greater) * gzip (recommended 1.3.12 or greater) diff --git a/configure b/configure index 601a544c6..30c203e48 100755 --- a/configure +++ b/configure @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # # Copyright © 2014 Jesse 'Jeaye' Wilkerson # See licensing in LICENSE file, or at: @@ -11,7 +11,7 @@ # and keep the output at bay. if [ "$1" != "quiet" ]; then - $0 "quiet" $@ > /dev/null + "$0" "quiet" "$@" > /dev/null exit $? fi shift @@ -23,7 +23,8 @@ set -o nounset UNAME_LINUX=0 UNAME_CYGWIN=0 UNAME_OSX=0 -UNAME=$(uname) +UNAME_FREEBSD=0 +UNAME="$(uname)" if [ "$UNAME" = "Linux" ]; then UNAME_LINUX=1 @@ -33,23 +34,26 @@ then elif [ "$(uname -o)" = "Cygwin" ]; then UNAME_CYGWIN=1 +elif [ "$UNAME" = "FreeBSD" ]; +then + UNAME_FREEBSD=1 else echo "Invalid uname ($UNAME): Unsuppported platform" 1>&2 exit 1 fi log() { echo "$@" 1>&2; } -log_start() { printf "$@" 1>&2; } -log_end() { echo "$@" 1>&2; } PROJECT=stdman log "Configuring ${PROJECT}" +PROJECTDIR="${BASH_SOURCE[0]%/*}" +REAL_PROJECTDIR="$(cd "$PROJECTDIR" && pwd)" PREFIX=/usr/local -DATAROOTDIR=$PREFIX/share -MANDIR=$DATAROOTDIR/man -REFERENCE=./reference/en/cpp -TMP_MAN=./man +DATAROOTDIR="$PREFIX/share" +MANDIR="$DATAROOTDIR/man" +REFERENCE=$REAL_PROJECTDIR/reference/en/cpp +TMP_MAN=$REAL_PROJECTDIR/man THREADS=8 CXX_PLATFORM_FLAGS= LD_PLATFORM_LIBS= @@ -64,35 +68,40 @@ then elif [ "1" -eq "$UNAME_CYGWIN" ]; then log "Platform: Cygwin (NOT TESTED)" +elif [ "1" -eq "$UNAME_FREEBSD" ]; +then + log "Platform: FreeBSD" + CXX_PLATFORM_FLAGS="-I/usr/local/include" + LD_PLATFORM_LIBS="-L/usr/local/lib" fi # Parse params for i in "$@" do - case $i in + case "$i" in --prefix) shift PREFIX="$1" - DATAROOTDIR=$PREFIX/share - MANDIR=$DATAROOTDIR/man + DATAROOTDIR="$PREFIX/share" + MANDIR="$DATAROOTDIR/man" shift ;; --prefix=*) PREFIX="${i#*=}" - DATAROOTDIR=$PREFIX/share - MANDIR=$DATAROOTDIR/man + DATAROOTDIR="$PREFIX/share" + MANDIR="$DATAROOTDIR/man" shift ;; --datarootdir) shift DATAROOTDIR="$1" - MANDIR=$DATAROOTDIR/man + MANDIR="$DATAROOTDIR/man" shift ;; --datarootdir=*) DATAROOTDIR="${i#*=}" - MANDIR=$DATAROOTDIR/man + MANDIR="$DATAROOTDIR/man" shift ;; @@ -128,11 +137,11 @@ do --threads) shift - THREADS=$1 + THREADS="$1" shift ;; --threads=*) - THREADS=${i#*=} + THREADS="${i#*=}" shift ;; @@ -141,8 +150,8 @@ do log log " --help Show this help message" log " --prefix=[/usr/local] Set installation prefix" - log " --datarootdir=[/usr/local/share] Set data root prefix" - log " --mandir=[/usr/local/share/man] Set man prefix" + log " --datarootdir=[/share] Set data root prefix" + log " --mandir=[/share/man] Set man prefix" log " --reference=[./reference/en/cpp] Set input prefix" log " --tmp-man=[./man] Set temporary output prefix" log " --threads=[8] Set number of threads to use" @@ -167,16 +176,22 @@ log # Configure the makefile log "Populating Makefile" -rm -f Makefile -sed "s#%CXX_PLATFORM_FLAGS%#${CXX_PLATFORM_FLAGS}#" ./Makefile.in |\ +rm -f $PROJECTDIR/Makefile +sed "s#%CXX_PLATFORM_FLAGS%#${CXX_PLATFORM_FLAGS}#" "$PROJECTDIR/Makefile.in" |\ sed "s#%LD_PLATFORM_LIBS%#${LD_PLATFORM_LIBS}#" |\ sed "s#%PREFIX%#${PREFIX}#" |\ sed "s#%DATAROOTDIR%#${DATAROOTDIR}#" |\ sed "s#%MANDIR%#${MANDIR}#" |\ sed "s#%REFERENCE%#${REFERENCE}#" |\ sed "s#%TMP_MAN%#${TMP_MAN}#" |\ -sed "s#%THREADS%#${THREADS}#" > Makefile +sed "s#%THREADS%#${THREADS}#" > "$PROJECTDIR/Makefile" + +MAKE_C= +if [[ "$PROJECTDIR" != . ]]; +then + MAKE_C=" -C ${PROJECTDIR/#$HOME/~}" +fi log "Done configuring ${PROJECT}" log -log "To install, use \`make install\` with the appropriate permissions for your prefix" +log "To install, use \`make$MAKE_C install\` with the appropriate permissions for your prefix" diff --git a/do_generate b/do_generate index 481fb37f4..232f8a7b8 100755 --- a/do_generate +++ b/do_generate @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # # Copyright © 2014 Jesse 'Jeaye' Wilkerson # See licensing in LICENSE file, or at: diff --git a/do_install b/do_install index 698be562a..1cf4668ca 100755 --- a/do_install +++ b/do_install @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # # Copyright © 2014 Jesse 'Jeaye' Wilkerson # See licensing in LICENSE file, or at: @@ -14,8 +14,8 @@ set -o nounset echo "Installing from $tmp_man to $mandir/man3" mkdir -p $mandir/man3 for file in "$tmp_man"/*.3 ; do - out=$mandir/man3/$(basename "$file"); - install -m 0644 "$file" "$out"; + out=$mandir/man3/${file##*/}; + install -p -m 0644 "$file" "$out"; gzip -f "$out"; done -echo "Done" +echo "Done; it's advised to run 'sudo mandb' (GNU) or 'sudo makewhatis' (BSD) now." diff --git a/do_link b/do_link index 6f76bb7b4..459baca92 100755 --- a/do_link +++ b/do_link @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # # Copyright © 2014 Jesse 'Jeaye' Wilkerson # See licensing in LICENSE file, or at: @@ -16,7 +16,7 @@ tmp_man=$1 # Map basic types to their common typedefs and create links # for each of the occurring patterns in the man pages. # NOTE: There is likely a better way to do this. I realize. -declare -a typedefs=('basic_string'\ +declare -a typedefs=('basic_string' 'basic_string_view'\ 'basic_istringstream' 'basic_ostringstream' 'basic_stringstream'\ 'basic_istream' 'basic_ostream' 'basic_iostream'\ 'basic_ifstream' 'basic_ofstream' 'basic_fstream'\ @@ -24,6 +24,7 @@ declare -a typedefs=('basic_string'\ 'basic_filebuf' 'basic_regex' ) declare -a alias_basic_string=('string' 'wstring' 'u16string' 'u32string') +declare -a alias_basic_string_view=('string_view' 'wstring_view' 'u16string_view' 'u32string_view') declare -a alias_basic_stringstream=('stringstream' 'wstringstream') declare -a alias_basic_istringstream=('istringstream' 'wistringstream') declare -a alias_basic_ostringstream=('ostringstream' 'wostringstream') diff --git a/man/Deductionguidesforstd::chrono::zoned_time.3 b/man/Deductionguidesforstd::chrono::zoned_time.3 new file mode 100644 index 000000000..d9e546ba7 --- /dev/null +++ b/man/Deductionguidesforstd::chrono::zoned_time.3 @@ -0,0 +1,46 @@ +.TH Deductionguidesforstd::chrono::zoned_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +Deductionguidesforstd::chrono::zoned_time \- Deductionguidesforstd::chrono::zoned_time + +.SH Synopsis + zoned_time() -> zoned_time; \fB(1)\fP \fI(since C++20)\fP + template< class Duration > + + zoned_time( std::chrono::sys_time ) \fB(2)\fP \fI(since C++20)\fP + + -> zoned_time>; + template< class TimeZonePtrOrName > + zoned_time( TimeZonePtrOrName&& ) -> \fB(3)\fP \fI(since C++20)\fP + zoned_time; + template< class TimeZonePtrOrName, class Duration > + + zoned_time( TimeZonePtrOrName&&, std::chrono::sys_time ) \fB(4)\fP \fI(since C++20)\fP + + -> zoned_time, /* see below */>; + template< class TimeZonePtrOrName, class Duration > + + zoned_time( TimeZonePtrOrName&&, + std::chrono::local_time, \fB(5)\fP \fI(since C++20)\fP + std::chrono::choose = std::chrono::choose::earliest ) + + -> zoned_time, /* see below */>; + template< class TimeZonePtrOrName, class Duration, class + TimeZonePtr2 > + + zoned_time( TimeZonePtrOrName&&, std::chrono::zoned_time, \fB(6)\fP \fI(since C++20)\fP + std::chrono::choose = std::chrono::choose::earliest ) + + -> zoned_time, /* see below */>; + + These deduction guides normalize Duration to a minimum resolution of + std::chrono::seconds, and provide correct handling for time zone names specified + using types convertible to std::string_view. + + 3-6) If std::is_convertible_v is true, the + deduced second template argument is const std::chrono::time_zone*. Otherwise it is + std::remove_cvref_t. diff --git a/man/deductionguidesforstd::array.3 b/man/deductionguidesforstd::array.3 new file mode 100644 index 000000000..083712329 --- /dev/null +++ b/man/deductionguidesforstd::array.3 @@ -0,0 +1,39 @@ +.TH deductionguidesforstd::array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::array \- deductionguidesforstd::array + +.SH Synopsis + Defined in header + template< class T, class... U > + + array( T, U... ) \fI(since C++17)\fP + + -> array; + + One deduction guide is provided for std::array to provide an equivalent of + std::experimental::make_array for construction of std::array from a variadic + parameter pack. + + The program is ill-formed if (std::is_same_v && ...) is not true. Note that + (std::is_same_v && ...) is true when sizeof...(U) is zero. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int const x = 10; + std::array a{1, 2, 3, 5, x}; // OK, creates std::array + assert(a.back() == x); + + // std::array b{1, 2u}; // Error, all arguments must have the same type + + // std::array c{3, 2, 1}; // Error, wrong number of template args + std::array c(std::to_array({3, 2, 1})); // C++20 alternative, + // creates std::array + } diff --git a/man/deductionguidesforstd::basic_regex.3 b/man/deductionguidesforstd::basic_regex.3 new file mode 100644 index 000000000..a73046964 --- /dev/null +++ b/man/deductionguidesforstd::basic_regex.3 @@ -0,0 +1,30 @@ +.TH deductionguidesforstd::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::basic_regex \- deductionguidesforstd::basic_regex + +.SH Synopsis + Defined in header + template< class ForwardIt > + + basic_regex( ForwardIt, ForwardIt, + std::regex_constants::syntax_option_type = \fI(since C++17)\fP + std::regex_constants::ECMAScript ) + + -> basic_regex::value_type>; + + This deduction guide is provided for std::basic_regex to allow deduction from an + iterator range. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::vector v = {'a', 'b', 'c'}; + std::basic_regex re(v.begin(), v.end()); // uses explicit deduction guide + } diff --git a/man/deductionguidesforstd::basic_string.3 b/man/deductionguidesforstd::basic_string.3 new file mode 100644 index 000000000..a617c72d3 --- /dev/null +++ b/man/deductionguidesforstd::basic_string.3 @@ -0,0 +1,104 @@ +.TH deductionguidesforstd::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::basic_string \- deductionguidesforstd::basic_string + +.SH Synopsis + Defined in header + template< class InputIt, class Alloc = std::allocator< + + typename + std::iterator_traits::value_type> > + basic_string( InputIt, InputIt, Alloc = Alloc() ) + -> basic_string::value_type, + std::char_traits< + + typename + std::iterator_traits::value_type>, Alloc>; + template< class CharT, + + class Traits, + class Alloc = std::allocator > \fB(2)\fP \fI(since C++17)\fP + explicit basic_string( std::basic_string_view, + const Alloc& = Alloc() ) + + -> basic_string; + template< class CharT, + + class Traits, + class Alloc = std::allocator> > + basic_string( std::basic_string_view, \fB(3)\fP \fI(since C++17)\fP + typename /* see below */::size_type, + typename /* see below */::size_type, + const Alloc& = Alloc() ) + + -> basic_string; + template< ranges::input_range R, + + class Alloc = std::allocator> > + basic_string( std::from_range_t, R&&, Alloc = Alloc() ) \fB(4)\fP (since C++23) + -> basic_string, + + std::char_traits>, + Alloc>; + + 1) This deduction guide is provided for std::basic_string to allow deduction from an + iterator range. This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator and Alloc satisfies Allocator. + 2,3) These deduction guides are provided for std::basic_string to allow deduction + from a std::basic_string_view. The size_type parameter type in \fB(3)\fP refers to the + size_type member type of the type deduced by the deduction guide. These overloads + participate in overload resolution only if Alloc satisfies Allocator. + 4) This deduction guide is provided for std::basic_string to allow deduction from a + std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Guides (2,3) are needed because the std::basic_string constructors for + std::basic_string_views are made templates to avoid causing ambiguities in existing + code, and those templates do not support class template argument deduction. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(4)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v = {'a', 'b', 'c'}; + std::basic_string s1(v.begin(), v.end()); // uses deduction guide (1) + assert(s1 == "abc"); + + #if __cpp_lib_containers_ranges >= 202202L + std::vector v4{0x43, 43, 053, 0x32, 0x33}; + std::basic_string s4(std::from_range, v4); // uses deduction guide (4) + assert(s4 == L"C++23"); + #endif + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3075 C++17 deduction from basic_string_view was deduction guides + unsupported (exacerbated by LWG issue 2946) added diff --git a/man/deductionguidesforstd::basic_string_view.3 b/man/deductionguidesforstd::basic_string_view.3 new file mode 100644 index 000000000..49cdd1261 --- /dev/null +++ b/man/deductionguidesforstd::basic_string_view.3 @@ -0,0 +1,54 @@ +.TH deductionguidesforstd::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::basic_string_view \- deductionguidesforstd::basic_string_view + +.SH Synopsis + Defined in header + template< class It, class End > + basic_string_view( It, End ) -> \fB(1)\fP \fI(since C++20)\fP + basic_string_view>; + template< class R > + basic_string_view( R&& ) -> \fB(2)\fP (since C++23) + basic_string_view>; + + These deduction guides are provided for std::basic_string_view. + + 1) This deduction guide allow the character type to be deduced from the + iterator-sentinel pair. This overload participates in overload resolution only if It + satisfies contiguous_iterator and End satisfies sized_sentinel_for for It. + 2) This deduction guide allow the character type to be deduced from the range. This + overload participates in overload resolution only if R satisfies contiguous_range. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::array a1{'n', 'u', 'c', 'l', 'e', 'o', 'n', 's', ':', '\\n'}; + std::basic_string_view s1(a1.cbegin(), a1.cend()); // deduction: CharT -> char + static_assert(std::is_same_v); + std::cout << s1; + + std::array a2{L'p', L'r', L'o', L't', L'o', L'n', L's', L'\\n'}; + std::basic_string_view s2(a2.cbegin(), a2.cend()); // deduction: CharT -> wchar_t + static_assert(std::is_same_v); + std::wcout << s2; + + std::array a3{'n', 'e', 'u', 't', 'r', 'o', 'n', 's', '\\n'}; + std::basic_string_view s3(a3.cbegin(), a3.cend()); // deduction: CharT -> long + static_assert(std::is_same_v); + for (const auto e : s3) + std::cout << static_cast(e); + } + +.SH Output: + + nucleons: + protons + neutrons diff --git a/man/deductionguidesforstd::deque.3 b/man/deductionguidesforstd::deque.3 new file mode 100644 index 000000000..0861b5dbd --- /dev/null +++ b/man/deductionguidesforstd::deque.3 @@ -0,0 +1,63 @@ +.TH deductionguidesforstd::deque 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::deque \- deductionguidesforstd::deque + +.SH Synopsis + Defined in header + template< class InputIt, + + class Alloc = std::allocator< + typename std::iterator_traits::value_type> + > \fB(1)\fP \fI(since C++17)\fP + deque( InputIt, InputIt, Alloc = Alloc() ) + + -> deque::value_type, + Alloc>; + template< ranges::input_range R, + + class Alloc = std::allocator> > \fB(2)\fP (since C++23) + deque( std::from_range_t, R&&, Alloc = Alloc() ) + + -> deque, Alloc>; + + 1) This deduction guide is provided for deque to allow deduction from an iterator + range. This overload participates in overload resolution only if InputIt satisfies + LegacyInputIterator and Alloc satisfies Allocator. + 2) This deduction guide is provided for deque to allow deduction from a + std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::vector v = {1, 2, 3, 4}; + + // uses explicit deduction guide to deduce std::deque + std::deque x(v.begin(), v.end()); + + // deduces std::deque::iterator> + // first phase of overload resolution for list-initialization selects the candidate + // synthesized from the initializer-list constructor; second phase is not performed + // and deduction guide has no effect + std::deque y{v.begin(), v.end()}; + } diff --git a/man/deductionguidesforstd::experimental::scope_exit.3 b/man/deductionguidesforstd::experimental::scope_exit.3 new file mode 100644 index 000000000..4113f06cf --- /dev/null +++ b/man/deductionguidesforstd::experimental::scope_exit.3 @@ -0,0 +1,22 @@ +.TH deductionguidesforstd::experimental::scope_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::experimental::scope_exit \- deductionguidesforstd::experimental::scope_exit + +.SH Synopsis + Defined in header + template< class EF > (library fundamentals TS v3) + scope_exit(EF) -> scope_exit; + + One deduction guide is provided for std::experimental::scope_exit to permit + deduction from an argument of function or function object type. + + The argument (after function-to-pointer decay, if any) is copied or moved into the + constructed scope_exit. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::experimental::scope_fail.3 b/man/deductionguidesforstd::experimental::scope_fail.3 new file mode 100644 index 000000000..1e425f367 --- /dev/null +++ b/man/deductionguidesforstd::experimental::scope_fail.3 @@ -0,0 +1,22 @@ +.TH deductionguidesforstd::experimental::scope_fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::experimental::scope_fail \- deductionguidesforstd::experimental::scope_fail + +.SH Synopsis + Defined in header + template< class EF > (library fundamentals TS v3) + scope_fail(EF) -> scope_fail; + + One deduction guide is provided for std::experimental::scope_fail to permit + deduction from an argument of function or function object type. + + The argument (after function-to-pointer decay, if any) is copied or moved into the + constructed scope_fail. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::experimental::scope_success.3 b/man/deductionguidesforstd::experimental::scope_success.3 new file mode 100644 index 000000000..d49b661f4 --- /dev/null +++ b/man/deductionguidesforstd::experimental::scope_success.3 @@ -0,0 +1,22 @@ +.TH deductionguidesforstd::experimental::scope_success 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::experimental::scope_success \- deductionguidesforstd::experimental::scope_success + +.SH Synopsis + Defined in header + template< class EF > (library fundamentals TS v3) + scope_success(EF) -> scope_success; + + One deduction guide is provided for std::experimental::scope_success to permit + deduction from an argument of function or function object type. + + The argument (after function-to-pointer decay, if any) is copied or moved into the + constructed scope_success. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::experimental::unique_resource.3 b/man/deductionguidesforstd::experimental::unique_resource.3 new file mode 100644 index 000000000..854fd3fa4 --- /dev/null +++ b/man/deductionguidesforstd::experimental::unique_resource.3 @@ -0,0 +1,22 @@ +.TH deductionguidesforstd::experimental::unique_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::experimental::unique_resource \- deductionguidesforstd::experimental::unique_resource + +.SH Synopsis + Defined in header + template< class R, class D > (library fundamentals TS v3) + unique_resource( R, D ) -> unique_resource; + + One deduction guide is provided for std::experimental::unique_resource to permit + deduction from given resource handle and deleter. + + The arguments (after array-to-pointer and function-to-pointer decay, if any) are + copied or moved into the constructed unique_resource. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::extents.3 b/man/deductionguidesforstd::extents.3 new file mode 100644 index 000000000..1f9da0b64 --- /dev/null +++ b/man/deductionguidesforstd::extents.3 @@ -0,0 +1,32 @@ +.TH deductionguidesforstd::extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::extents \- deductionguidesforstd::extents + +.SH Synopsis + Defined in header + template< class... Integrals > (since C++23) + explicit extents( Integrals... ) -> /* see below */; + + A deduction guide is provided for std::extents to allow deduction from integral + arguments. + + The deduced type is equivalent to + + std::dextents (until C++26) + std::extents...> (since C++26) + + This overload participates in overload resolution only if + (std::is_convertible_v && ...) is true. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs an extents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::flat_map.3 b/man/deductionguidesforstd::flat_map.3 new file mode 100644 index 000000000..324318af7 --- /dev/null +++ b/man/deductionguidesforstd::flat_map.3 @@ -0,0 +1,159 @@ +.TH deductionguidesforstd::flat_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::flat_map \- deductionguidesforstd::flat_map + +.SH Synopsis + Defined in header + template< class KeyContainer, class MappedContainer, + + class Compare = std::less > + flat_map( KeyContainer, MappedContainer, Compare = Compare() ) \fB(1)\fP (since C++23) + -> flat_map; + template< class KeyContainer, class MappedContainer, class + Allocator > + + flat_map( KeyContainer, MappedContainer, Allocator ) + -> flat_map, + + KeyContainer, MappedContainer>; + template< class KeyContainer, class MappedContainer, + + class Compare, class Allocator > + flat_map( KeyContainer, MappedContainer, Compare, Allocator ) \fB(3)\fP (since C++23) + -> flat_map; + template< class KeyContainer, class MappedContainer, + + class Compare = std::less > + flat_map( std::sorted_unique_t, KeyContainer, MappedContainer, \fB(4)\fP (since C++23) + Compare = Compare() ) + -> flat_map; + template< class KeyContainer, class MappedContainer, class + Allocator > + + flat_map( std::sorted_unique_t, KeyContainer, MappedContainer, + Allocator ) \fB(5)\fP (since C++23) + -> flat_map, + + KeyContainer, MappedContainer>; + template< class KeyContainer, class MappedContainer, + + class Compare, class Allocator> + flat_map( std::sorted_unique_t, KeyContainer, MappedContainer, + Compare, Allocator ) \fB(6)\fP (since C++23) + -> flat_map; + template< class InputIter, + + class Compare = std::less> + > \fB(7)\fP (since C++23) + flat_map( InputIter, InputIter, Compare = Compare() ) + -> flat_map, + + /*iter-mapped-type*/, Compare>; + template< class InputIter, + + class Compare = std::less> + > + flat_map( std::sorted_unique_t, InputIter, InputIter, \fB(8)\fP (since C++23) + Compare = Compare() ) + -> flat_map, + + /*iter-mapped-type*/, Compare>; + template< ranges::input_range R, + + class Compare = std::less>, + class Allocator = allocator > + flat_map( std::from_range_t, R&&, Compare = Compare(), + Allocator = Allocator() ) + -> flat_map, /*range-mapped-type*/, + Compare, + std::vector, \fB(9)\fP (since C++23) + /*alloc-rebind*/>>, + std::vector, + /*alloc-rebind*/>>>; + template< ranges::input_range R, class Allocator > + + flat_map( std::from_range_t, R&&, Allocator ) + -> flat_map, /*range-mapped-type*/, + std::less>, + std::vector, + /*alloc-rebind*/>>, + std::vector, + /*alloc-rebind*/>>>; + template< class Key, class T, class Compare = std::less > + + flat_map( std::initializer_list>, Compare = \fB(11)\fP (since C++23) + Compare() ) + + -> flat_map; + template< class Key, class T, class Compare = std::less > + + flat_map( std::sorted_unique_t, std::initializer_list>, \fB(12)\fP (since C++23) + Compare = Compare() ) + + -> flat_map; + + These deduction guides are provided for to allow deduction from: + + 1) A key-container, a mapped-container and a comparator. + 2) A key-container, a mapped-container and an allocator. + 3) A key-container, a mapped-container, a comparator and an allocator. + 4) The std::sorted_unique_t tag, a key-container, a mapped-container and a + comparator. + 5) The std::sorted_unique_t tag, a key-container, a mapped-container and an + allocator. + 6) The std::sorted_unique_t tag, a key-container, a mapped-container, a comparator + and an allocator. + 7) An iterator range and a comparator. + 8) The std::sorted_unique_t tag, an iterator range and a comparator. + 9) The std::from_range_t tag, an input_range range, a comparator and an allocator. + 10) The std::from_range_t tag, an input_range range and an allocator. + 11) The std::initializer_list and a comparator. + 12) The std::sorted_unique_t tag, the std::initializer_list and a comparator. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::flat_multimap.3 b/man/deductionguidesforstd::flat_multimap.3 new file mode 100644 index 000000000..2b893817b --- /dev/null +++ b/man/deductionguidesforstd::flat_multimap.3 @@ -0,0 +1,167 @@ +.TH deductionguidesforstd::flat_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::flat_multimap \- deductionguidesforstd::flat_multimap + +.SH Synopsis + Defined in header + template< class KeyContainer, class MappedContainer, + + class Compare = std::less > + flat_multimap( KeyContainer, MappedContainer, Compare = Compare() \fB(1)\fP (since C++23) + ) + -> flat_multimap; + template< class KeyContainer, class MappedContainer, class + Allocator > + + flat_multimap( KeyContainer, MappedContainer, Allocator ) + -> flat_multimap, + + KeyContainer, MappedContainer>; + template< class KeyContainer, class MappedContainer, + + class Compare, class Allocator > + flat_multimap( KeyContainer, MappedContainer, Compare, Allocator + ) \fB(3)\fP (since C++23) + -> flat_multimap; + template< class KeyContainer, class MappedContainer, + + class Compare = std::less > + flat_multimap( std::sorted_equivalent_t, KeyContainer, + MappedContainer, \fB(4)\fP (since C++23) + Compare = Compare() ) + -> flat_multimap; + template< class KeyContainer, class MappedContainer, class + Allocator > + + flat_multimap( std::sorted_equivalent_t, KeyContainer, + MappedContainer, + Allocator ) \fB(5)\fP (since C++23) + -> flat_multimap, + + KeyContainer, MappedContainer>; + template< class KeyContainer, class MappedContainer, + + class Compare, class Allocator> + flat_multimap( std::sorted_equivalent_t, KeyContainer, + MappedContainer, \fB(6)\fP (since C++23) + Compare, Allocator ) + -> flat_multimap; + template< class InputIter, + + class Compare = std::less> + > \fB(7)\fP (since C++23) + flat_multimap( InputIter, InputIter, Compare = Compare() ) + -> flat_multimap, + + /*iter-mapped-type*/, Compare>; + template< class InputIter, + + class Compare = std::less> + > + flat_multimap( std::sorted_equivalent_t, InputIter, InputIter, \fB(8)\fP (since C++23) + Compare = Compare() ) + -> flat_multimap, + + /*iter-mapped-type*/, Compare>; + template< ranges::input_range R, + + class Compare = std::less>, + class Allocator = allocator > + flat_multimap( std::from_range_t, R&&, Compare = Compare(), + Allocator = Allocator() ) + -> flat_multimap, + /*range-mapped-type*/, Compare, + std::vector, \fB(9)\fP (since C++23) + /*alloc-rebind*/>>, + std::vector, + /*alloc-rebind*/>>>; + template< ranges::input_range R, class Allocator > + + flat_multimap( std::from_range_t, R&&, Allocator ) + -> flat_multimap, + /*range-mapped-type*/, + std::less>, + std::vector, + /*alloc-rebind*/>>, + std::vector, + /*alloc-rebind*/>>>; + template< class Key, class T, class Compare = std::less > + + flat_multimap( std::initializer_list>, Compare = \fB(11)\fP (since C++23) + Compare() ) + + -> flat_multimap; + template< class Key, class T, class Compare = std::less > + + flat_multimap( std::sorted_equivalent_t, + std::initializer_list>, \fB(12)\fP (since C++23) + Compare = Compare() ) + + -> flat_multimap; + + These deduction guides are provided for to allow deduction from: + + 1) A key-container, a mapped-container and a comparator. + 2) A key-container, a mapped-container and an allocator. + 3) A key-container, a mapped-container, a comparator and an allocator. + 4) The std::sorted_equivalent_t tag, a key-container, a mapped-container and a + comparator. + 5) The std::sorted_equivalent_t tag, a key-container, a mapped-container and an + allocator. + 6) The std::sorted_equivalent_t tag, a key-container, a mapped-container, a + comparator and an allocator. + 7) An iterator range and a comparator. + 8) The std::sorted_equivalent_t tag, an iterator range and a comparator. + 9) The std::from_range_t tag, an input_range range, a comparator and an allocator. + 10) The std::from_range_t tag, an input_range range and an allocator. + 11) The std::initializer_list and a comparator. + 12) The std::sorted_equivalent_t tag, the std::initializer_list and a comparator. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::flat_multiset.3 b/man/deductionguidesforstd::flat_multiset.3 new file mode 100644 index 000000000..874e160dc --- /dev/null +++ b/man/deductionguidesforstd::flat_multiset.3 @@ -0,0 +1,132 @@ +.TH deductionguidesforstd::flat_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::flat_multiset \- deductionguidesforstd::flat_multiset + +.SH Synopsis + Defined in header + template< class KeyContainer, + + class Compare = std::less > \fB(1)\fP (since C++23) + flat_multiset( KeyContainer, Compare = Compare() ) + + -> flat_multiset; + template< class KeyContainer, class Allocator > + + flat_multiset( KeyContainer, Allocator ) + -> flat_multiset, KeyContainer>; + template< class KeyContainer, class Compare, class Allocator > + + flat_multiset( KeyContainer, Compare, Allocator ) \fB(3)\fP (since C++23) + + -> flat_multiset; + template< class KeyContainer, + + class Compare = std::less > + flat_multiset( std::sorted_equivalent_t, KeyContainer, Compare = \fB(4)\fP (since C++23) + Compare() ) + + -> flat_multiset; + template< class KeyContainer, class Allocator > + + flat_multiset( std::sorted_equivalent_t, KeyContainer, Allocator + ) \fB(5)\fP (since C++23) + -> flat_multiset, KeyContainer>; + template< class KeyContainer, class Compare, class Allocator > + + flat_multiset( std::sorted_equivalent_t, KeyContainer, Compare, + Allocator ) \fB(6)\fP (since C++23) + + -> flat_multiset; + template< class InputIter, + + class Compare = + std::less> > \fB(7)\fP (since C++23) + flat_multiset( InputIter, InputIter, Compare = Compare() ) + + -> flat_multiset, Compare>; + template< class InputIter, + + class Compare = + std::less> > \fB(8)\fP (since C++23) + flat_multiset( std::sorted_equivalent_t, InputIter, InputIter, + Compare = Compare() ) + + -> flat_multiset, Compare>; + template< ranges::input_range R, + + class Compare = std::less>, + class Allocator = + std::allocator> > + flat_multiset( std::from_range_t, R&&, Compare = Compare(), \fB(9)\fP (since C++23) + Allocator = Allocator() ) + -> flat_multiset, Compare, + std::vector, + + /*alloc-rebind*/>>>; + template< ranges::input_range R, class Allocator > + + flat_multiset( std::from_range_t, R&&, Allocator ) + -> flat_multiset, + std::less>, \fB(10)\fP (since C++23) + std::vector, + + /*alloc-rebind*/>>>; + template< class Key, class Compare = std::less > + + flat_multiset( std::initializer_list, Compare = Compare() ) \fB(11)\fP (since C++23) + + -> flat_multiset; + template< class Key, class Compare = std::less > + + flat_multiset( std::sorted_equivalent_t, \fB(12)\fP (since C++23) + std::initializer_list, Compare = Compare() ) + + -> flat_multiset; + + These deduction guides are provided for to allow deduction from: + + 1) A container and a comparator. + 2) A container and an allocator. + 3) A container, a comparator and an allocator. + 4) The std::sorted_equivalent_t tag, a container and a comparator. + 5) The std::sorted_equivalent_t tag, a container and an allocator. + 6) The std::sorted_equivalent_t tag, a container, a comparator and an allocator. + 7) An iterator range and a comparator. + 8) The std::sorted_equivalent_t tag, an iterator range and a comparator. + 9) The std::from_range_t tag, an input_range range, a comparator and an allocator. + 10) The std::from_range_t tag, an input_range range and an allocator. + 11) The std::initializer_list and a comparator. + 12) The std::sorted_equivalent_t tag, the std::initializer_list and a comparator. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::flat_set.3 b/man/deductionguidesforstd::flat_set.3 new file mode 100644 index 000000000..29e32e4f1 --- /dev/null +++ b/man/deductionguidesforstd::flat_set.3 @@ -0,0 +1,131 @@ +.TH deductionguidesforstd::flat_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::flat_set \- deductionguidesforstd::flat_set + +.SH Synopsis + Defined in header + template< class KeyContainer, + + class Compare = std::less > \fB(1)\fP (since C++23) + flat_set( KeyContainer, Compare = Compare() ) + + -> flat_set; + template< class KeyContainer, class Allocator > + + flat_set( KeyContainer, Allocator ) + -> flat_set, + KeyContainer>; + template< class KeyContainer, class Compare, class Allocator > + + flat_set( KeyContainer, Compare, Allocator ) \fB(3)\fP (since C++23) + + -> flat_set; + template< class KeyContainer, + + class Compare = std::less > + flat_set( std::sorted_unique_t, KeyContainer, Compare = Compare() \fB(4)\fP (since C++23) + ) + + -> flat_set; + template< class KeyContainer, class Allocator > + + flat_set( std::sorted_unique_t, KeyContainer, Allocator ) + -> flat_set, + KeyContainer>; + template< class KeyContainer, class Compare, class Allocator > + + flat_set( std::sorted_unique_t, KeyContainer, Compare, Allocator + ) \fB(6)\fP (since C++23) + + -> flat_set; + template< class InputIter, + + class Compare = + std::less> > \fB(7)\fP (since C++23) + flat_set( InputIter, InputIter, Compare = Compare() ) + + -> flat_set, Compare>; + template< class InputIter, + + class Compare = + std::less> > \fB(8)\fP (since C++23) + flat_set( std::sorted_unique_t, InputIter, InputIter, Compare = + Compare() ) + + -> flat_set, Compare>; + template< ranges::input_range R, + + class Compare = std::less>, + class Allocator = + std::allocator> > + flat_set( std::from_range_t, R&&, Compare = Compare(), Allocator \fB(9)\fP (since C++23) + = Allocator() ) + -> flat_set, Compare, + std::vector, + + /*alloc-rebind*/>>>; + template< ranges::input_range R, class Allocator > + + flat_set( std::from_range_t, R&&, Allocator ) + -> flat_set, + std::less>, \fB(10)\fP (since C++23) + std::vector, + + /*alloc-rebind*/>>>; + template< class Key, class Compare = std::less > + + flat_set( std::initializer_list, Compare = Compare() ) \fB(11)\fP (since C++23) + + -> flat_set; + template< class Key, class Compare = std::less > + + flat_set( std::sorted_unique_t, \fB(12)\fP (since C++23) + std::initializer_list, Compare = Compare() ) + + -> flat_set; + + These deduction guides are provided for to allow deduction from: + + 1) A container and a comparator. + 2) A container and an allocator. + 3) A container, a comparator and an allocator. + 4) The std::sorted_unique_t tag, a container and a comparator. + 5) The std::sorted_unique_t tag, a container and an allocator. + 6) The std::sorted_unique_t tag, a container, a comparator and an allocator. + 7) An iterator range and a comparator. + 8) The std::sorted_unique_t tag, an iterator range and a comparator. + 9) The std::from_range_t tag, an input_range range, a comparator and an allocator. + 10) The std::from_range_t tag, an input_range range and an allocator. + 11) The std::initializer_list and a comparator. + 12) The std::sorted_unique_t tag, the std::initializer_list and a comparator. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::forward_list.3 b/man/deductionguidesforstd::forward_list.3 new file mode 100644 index 000000000..3a4bb56df --- /dev/null +++ b/man/deductionguidesforstd::forward_list.3 @@ -0,0 +1,63 @@ +.TH deductionguidesforstd::forward_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::forward_list \- deductionguidesforstd::forward_list + +.SH Synopsis + Defined in header + template< class InputIt, + + class Alloc = std::allocator< + typename std::iterator_traits::value_type> + > \fB(1)\fP \fI(since C++17)\fP + forward_list( InputIt, InputIt, Alloc = Alloc() ) + + -> forward_list::value_type, Alloc>; + template< ranges::input_range R, + + class Alloc = std::allocator> > \fB(2)\fP (since C++23) + forward_list( std::from_range_t, R&&, Alloc = Alloc() ) + + -> forward_list, Alloc>; + + 1) This deduction guide is provided for forward_list to allow deduction from an + iterator range. This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator and Alloc satisfies Allocator. + 2) This deduction guide is provided for forward_list to allow deduction from a + std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::vector v = {1, 2, 3, 4}; + + // uses explicit deduction guide to deduce std::forward_list + std::forward_list x(v.begin(), v.end()); + + // deduces std::forward_list::iterator> + // first phase of overload resolution for list-initialization selects the candidate + // synthesized from the initializer-list constructor; second phase is not performed + // and deduction guide has no effect + std::forward_list y{v.begin(), v.end()}; + } diff --git a/man/deductionguidesforstd::function.3 b/man/deductionguidesforstd::function.3 new file mode 100644 index 000000000..e4ea2158a --- /dev/null +++ b/man/deductionguidesforstd::function.3 @@ -0,0 +1,61 @@ +.TH deductionguidesforstd::function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::function \- deductionguidesforstd::function + +.SH Synopsis + Defined in header + template< class R, class... ArgTypes > \fB(1)\fP \fI(since C++17)\fP + function( R(*)(ArgTypes...) ) -> function; + template< class F > \fB(2)\fP \fI(since C++17)\fP + function( F ) -> function; + template< class F > \fB(3)\fP (since C++23) + function( F ) -> function; + template< class F > \fB(4)\fP (since C++23) + function( F ) -> function; + + 1) This deduction guide is provided for std::function to allow deduction from + functions. + 2) This overload participates in overload resolution only if &F::operator() is + well-formed when treated as an unevaluated operand and decltype(&F::operator()) is + of the form R(G::*)(A...) (optionally cv-qualified, optionally noexcept, optionally + lvalue reference qualified). The deduced type is std::function. + 3) This overload participates in overload resolution only if &F::operator() is + well-formed when treated as an unevaluated operand and F::operator() is an explicit + object parameter function whose type is of form R(G, A...) or R(G, A...) noexcept. + The deduced type is std::function. + 4) This overload participates in overload resolution only if &F::operator() is + well-formed when treated as an unevaluated operand and F::operator() is a static + member function whose type is of form R(A...) or R(A...) noexcept. The deduced type + is std::function. + +.SH Notes + + These deduction guides do not allow deduction from a function with ellipsis + parameter, and the ... in the types is always treated as a pack expansion. + + The type deduced by these deduction guides may change in a later standard revision + (in particular, this might happen if noexcept support is added to std::function in a + later standard). + +.SH Example + + +// Run this code + + #include + int func(double) { return 0; } + int main() { + std::function f{func}; // guide #1 deduces function + int i = 5; + std::function g = [&](double) { return i; }; // guide #2 deduces function + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + behavior of (2) was unclear clarified to be excluded from + LWG 3238 C++17 when overload resolution + F::operator() is &&-qualified diff --git a/man/deductionguidesforstd::function_ref.3 b/man/deductionguidesforstd::function_ref.3 new file mode 100644 index 000000000..038cfd91c --- /dev/null +++ b/man/deductionguidesforstd::function_ref.3 @@ -0,0 +1,36 @@ +.TH deductionguidesforstd::function_ref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::function_ref \- deductionguidesforstd::function_ref + +.SH Synopsis + Defined in header + template< class F > \fB(1)\fP (since C++26) + function_ref( F* ) -> function_ref; + template< auto f > \fB(2)\fP (since C++26) + function_ref( std::nontype_t ) -> function_ref; + template< auto f, class T > + function_ref( std::nontype_t, T&& ) -> function_ref; + + 1) This overload participates in overload resolution only if std::is_function_v + is true. + 2) Let type F be std::remove_pointer_t. This overload participates in + overload resolution only if std::is_function_v is true. The deduced type is + std::function_ref. + 3) Let type F be decltype(f). This overload participates in overload resolution only + if : + * F is of the form R(G::*)(A...) noexcept(E) (optionally cv-qualified, optionally + noexcept, optionally lvalue reference qualified) for a type G, or + * F is of the form M G::* for a type G and an object type M, in which case let R + be std::invoke_result_t, A... be an empty pack, and E be false, or + * F is of the form R(*)(G, A...) noexcept(E) for a type G. + + The deduced type is std::function_ref. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::list.3 b/man/deductionguidesforstd::list.3 new file mode 100644 index 000000000..988d46423 --- /dev/null +++ b/man/deductionguidesforstd::list.3 @@ -0,0 +1,63 @@ +.TH deductionguidesforstd::list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::list \- deductionguidesforstd::list + +.SH Synopsis + Defined in header + template< class InputIt, + + class Alloc = std::allocator< + typename std::iterator_traits::value_type> + > \fB(1)\fP \fI(since C++17)\fP + list( InputIt, InputIt, Alloc = Alloc() ) + + -> list::value_type, + Alloc>; + template< ranges::input_range R, + + class Alloc = std::allocator> > \fB(2)\fP (since C++23) + list( std::from_range_t, R&&, Alloc = Alloc() ) + + -> list, Alloc>; + + 1) This deduction guide is provided for list to allow deduction from an iterator + range. This overload participates in overload resolution only if InputIt satisfies + LegacyInputIterator and Alloc satisfies Allocator. + 2) This deduction guide is provided for list to allow deduction from a + std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::vector v = {1, 2, 3, 4}; + + // uses explicit deduction guide to deduce std::list + std::list x(v.begin(), v.end()); + + // deduces std::list::iterator> + // first phase of overload resolution for list-initialization selects the candidate + // synthesized from the initializer-list constructor; second phase is not performed + // and deduction guide has no effect + std::list y{v.begin(), v.end()}; + } diff --git a/man/deductionguidesforstd::map.3 b/man/deductionguidesforstd::map.3 new file mode 100644 index 000000000..d5765f99a --- /dev/null +++ b/man/deductionguidesforstd::map.3 @@ -0,0 +1,143 @@ +.TH deductionguidesforstd::map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::map \- deductionguidesforstd::map + +.SH Synopsis + Defined in header + template< class InputIt, + + class Comp = std::less>, + class Alloc = + std::allocator> > \fB(1)\fP \fI(since C++17)\fP + map( InputIt, InputIt, Comp = Comp(), Alloc = Alloc() ) + + -> map, iter_val_t, Comp, + Alloc>; + template< class Key, + + class T, + class Comp = std::less, + class Alloc = std::allocator> > + map( std::initializer_list>, Comp = Comp(), + Alloc = Alloc() ) + + -> map; + template< class InputIt, class Alloc > + + map( InputIt, InputIt, Alloc ) \fB(3)\fP \fI(since C++17)\fP + -> map, iter_val_t, + + std::less>, Alloc>; + template< class Key, class T, class Alloc > + + map( std::initializer_list>, Alloc ) \fB(4)\fP \fI(since C++17)\fP + + -> map, Alloc>; + template< ranges::input_range R, class Compare = + std::less, + + class Alloc = std::allocator> > + map( std::from_range_t, R&&, Compare = Compare(), Alloc = \fB(5)\fP (since C++23) + Alloc() ) + + -> map, range_mapped_t, Compare, + Alloc>; + template< ranges::input_range R, class Alloc > + + map( std::from_range_t, R&&, Alloc ) \fB(6)\fP (since C++23) + + -> map, range_mapped_t, + std::less>, Alloc>; + Exposition-only helper type aliases + template< class InputIter > + + using iter_val_t = (exposition only*) + + typename std::iterator_traits::value_type; + template< class InputIter > + + using iter_key_t = (exposition only*) + + std::remove_const_t< std::tuple_element_t<0, + iter_val_t>>; + template< class InputIter > + + using iter_mapped_t = (exposition only*) + + std::tuple_element_t<1, iter_val_t>; + template< class InputIter > + + using iter_to_alloc_t = + std::pair>>, + + std::tuple_element_t<1, + iter_val_t>>; + template< ranges::input_range Range > + + using range_key_t = (since C++23) + (exposition only*) + std::remove_const_t::first_type>; + template< ranges::input_range Range > + (since C++23) + using range_mapped_t = (exposition only*) + + typename ranges::range_value_t::second_type; + template< ranges::input_range Range > + + using range_to_alloc_t = + std::pair::first_type>, (exposition only*) + + typename + ranges::range_value_t::second_type>; + + 1-4) These deduction guides are provided for map to allow deduction from an iterator + range (overloads (1,3)) and std::initializer_list (overloads (2,4)). + 5,6) These deduction guides are provided for map to allow deduction from a + std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload (5,6) + +.SH Example + + +// Run this code + + #include + + int main() + { + // std::map m1 = {{"foo", 1}, {"bar", 2}}; + // Error: braced-init-list has no type; cannot deduce + // pair from {"foo", 1} or {"bar", 2} + + std::map m1 = {std::pair{"foo", 2}, {"bar", 3}}; // guide #2 + std::map m2(m1.begin(), m1.end()); // guide #1 + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3025 C++17 initializer-list guides take use std::pair + std::pair diff --git a/man/deductionguidesforstd::mdspan.3 b/man/deductionguidesforstd::mdspan.3 new file mode 100644 index 000000000..9b9770e95 --- /dev/null +++ b/man/deductionguidesforstd::mdspan.3 @@ -0,0 +1,73 @@ +.TH deductionguidesforstd::mdspan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::mdspan \- deductionguidesforstd::mdspan + +.SH Synopsis + Defined in header + template< class CArray > + + requires(std::is_array_v && std::rank_v == 1) (since + mdspan( CArray& ) \fB(1)\fP C++23) + -> mdspan, + + std::extents>>; + template< class Pointer > + + requires(std::is_pointer_v>) + mdspan( Pointer&& ) \fB(2)\fP (since + -> C++23) + mdspan>, + + std::extents>; + template< class ElementType, class... Integrals > + + requires((std::is_convertible_v && ...) && + sizeof...(Integrals) > 0) \fB(3)\fP (since + explicit mdspan( ElementType*, Integrals... ) C++23) + + -> mdspan>; + template< class ElementType, class OtherIndexType, std::size_t N > + (since + mdspan( ElementType*, std::span ) \fB(4)\fP C++23) + + -> mdspan>; + template< class ElementType, class OtherIndexType, std::size_t N > + (since + mdspan( ElementType*, const std::array& ) \fB(5)\fP C++23) + + -> mdspan>; + template< class ElementType, class IndexType, std::size_t... ExtentsPack + > + (since + mdspan( ElementType*, const std::extents& \fB(6)\fP C++23) + ) + + -> mdspan>; + template< class ElementType, class MappingType > + + mdspan( ElementType*, const MappingType& ) \fB(7)\fP (since + -> mdspan; + template< class MappingType, class AccessorType > + + mdspan( const typename AccessorType::data_handle_type&, const + MappingType&, (since + const AccessorType& ) \fB(8)\fP C++23) + -> mdspan; + + This section is incomplete + Reason: explanation + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/deductionguidesforstd::multimap.3 b/man/deductionguidesforstd::multimap.3 new file mode 100644 index 000000000..7ce9e7708 --- /dev/null +++ b/man/deductionguidesforstd::multimap.3 @@ -0,0 +1,143 @@ +.TH deductionguidesforstd::multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::multimap \- deductionguidesforstd::multimap + +.SH Synopsis + Defined in header + template< class InputIt, + + class Comp = std::less>, + class Alloc = + std::allocator> > \fB(1)\fP \fI(since C++17)\fP + multimap( InputIt, InputIt, Comp = Comp(), Alloc = Alloc() ) + + -> multimap, iter_val_t, + Comp, Alloc>; + template< class Key, + + class T, + class Comp = std::less, + class Alloc = std::allocator> > + multimap( std::initializer_list>, Comp = + Comp(), Alloc = Alloc() ) + + -> multimap; + template< class InputIt, class Alloc > + + multimap( InputIt, InputIt, Alloc ) \fB(3)\fP \fI(since C++17)\fP + -> multimap, iter_val_t, + + std::less>, Alloc>; + template< class Key, class T, class Alloc > + + multimap( std::initializer_list>, Alloc ) \fB(4)\fP \fI(since C++17)\fP + + -> multimap, Alloc>; + template< ranges::input_range R, class Compare = + std::less, + + class Alloc = std::allocator> > + multimap( std::from_range_t, R&&, Compare = Compare(), Alloc \fB(5)\fP (since C++23) + = Alloc() ) + + -> multimap, range_mapped_t, Compare, + Alloc>; + template< ranges::input_range R, class Alloc > + + multimap( std::from_range_t, R&&, Alloc ) \fB(6)\fP (since C++23) + + -> multimap, range_mapped_t, + std::less>, Alloc>; + Exposition-only helper type aliases + template< class InputIter > + + using iter_val_t = (exposition only*) + + typename std::iterator_traits::value_type; + template< class InputIter > + + using iter_key_t = (exposition only*) + + std::remove_const_t< std::tuple_element_t<0, + iter_val_t>>; + template< class InputIter > + + using iter_mapped_t = (exposition only*) + + std::tuple_element_t<1, iter_val_t>; + template< class InputIter > + + using iter_to_alloc_t = + std::pair>>, + + std::tuple_element_t<1, + iter_val_t>>; + template< ranges::input_range Range > + + using range_key_t = (since C++23) + (exposition only*) + std::remove_const_t::first_type>; + template< ranges::input_range Range > + (since C++23) + using range_mapped_t = (exposition only*) + + typename ranges::range_value_t::second_type; + template< ranges::input_range Range > + + using range_to_alloc_t = + std::pair::first_type>, (exposition only*) + + typename + ranges::range_value_t::second_type>; + + 1-4) These deduction guides are provided for multimap to allow deduction from an + iterator range (overloads (1,3)) and std::initializer_list (overloads (2,4)). + 5,6) These deduction guides are provided for multimap to allow deduction from a + std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload (5,6) + +.SH Example + + +// Run this code + + #include + + int main() + { + // std::multimap m1 = {{"foo", 1}, {"bar", 2}}; + // Error: braced-init-list has no type; cannot deduce + // pair from {"foo", 1} or {"bar", 2} + + std::multimap m1 = {std::pair{"foo", 2}, {"bar", 3}}; // guide #2 + std::multimap m2(m1.begin(), m1.end()); // guide #1 + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3025 C++17 initializer-list guides take use std::pair + std::pair diff --git a/man/deductionguidesforstd::multiset.3 b/man/deductionguidesforstd::multiset.3 new file mode 100644 index 000000000..219818063 --- /dev/null +++ b/man/deductionguidesforstd::multiset.3 @@ -0,0 +1,90 @@ +.TH deductionguidesforstd::multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::multiset \- deductionguidesforstd::multiset + +.SH Synopsis + Defined in header + template< + + class InputIt, + class Comp = std::less::value_type>, + class Alloc = std::allocator::value_type>> + multiset( InputIt, InputIt, Comp = Comp(), Alloc = Alloc() ) + + -> multiset::value_type, Comp, Alloc>; + template< + + class Key, class Comp = std::less, + class Alloc = std::allocator > \fB(2)\fP \fI(since C++17)\fP + multiset( std::initializer_list, Comp = Comp(), Alloc = + Alloc() ) + + -> multiset; + template< class InputIt, class Alloc > + + multiset( InputIt, InputIt, Alloc ) + -> multiset::value_type, + + std::less::value_type>, Alloc>; + template< class Key, class Alloc > + + multiset( std::initializer_list, Alloc ) \fB(4)\fP \fI(since C++17)\fP + + -> multiset, Alloc>; + template< ranges::input_range R, class Compare = + less>, + + class Alloc = std::allocator> > \fB(5)\fP (since C++23) + multiset( std::from_range_t, R&&, Compare = Compare(), Alloc = + Alloc() ) + + -> multiset, Compare, Alloc>; + template< ranges::input_range R, class Alloc > + + multiset( std::from_range_t, R&&, Alloc ) \fB(6)\fP (since C++23) + + -> multiset, + std::less>, Alloc>; + + 1-4) These deduction guides are provided for multiset to allow deduction from an + iterator range (overloads (1,3)) and std::initializer_list (overloads (2,4)). + 5,6) These deduction guides are provided for multiset to allow deduction from a + std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload (5,6) + +.SH Example + + +// Run this code + + #include + + int main() + { + // guide #2 deduces std::multiset + std::multiset s = {1, 2, 3, 4}; + + // guide #1 deduces std::multiset + std::multiset s2(s.begin(), s.end()); + } diff --git a/man/deductionguidesforstd::optional.3 b/man/deductionguidesforstd::optional.3 new file mode 100644 index 000000000..2b3265700 --- /dev/null +++ b/man/deductionguidesforstd::optional.3 @@ -0,0 +1,27 @@ +.TH deductionguidesforstd::optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::optional \- deductionguidesforstd::optional + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + optional(T) -> optional; + + One deduction guide is provided for std::optional to account for the edge cases + missed by the implicit deduction guides, in particular, non-copyable arguments and + array to pointer conversion. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int a[2]; + std::optional oa{a}; // uses explicit deduction guide + static_assert(std::is_same_v> == true); + } diff --git a/man/deductionguidesforstd::packaged_task.3 b/man/deductionguidesforstd::packaged_task.3 new file mode 100644 index 000000000..5ed429554 --- /dev/null +++ b/man/deductionguidesforstd::packaged_task.3 @@ -0,0 +1,51 @@ +.TH deductionguidesforstd::packaged_task 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::packaged_task \- deductionguidesforstd::packaged_task + +.SH Synopsis + Defined in header + template< class R, class... Args > \fB(1)\fP \fI(since C++17)\fP + packaged_task( R(*)(Args...) ) -> packaged_task; + template< class F > \fB(2)\fP \fI(since C++17)\fP + packaged_task( F ) -> packaged_task; + template< class F > \fB(3)\fP (since C++23) + packaged_task( F ) -> packaged_task; + template< class F > \fB(4)\fP (since C++23) + packaged_task( F ) -> packaged_task; + + 1) This deduction guide is provided for std::packaged_task to allow deduction from + functions. + 2) This overload participates in overload resolution only if &F::operator() is + well-formed when treated as an unevaluated operand and decltype(&F::operator()) is + of the form R(G::*)(A...) (optionally cv-qualified, optionally noexcept, optionally + lvalue reference qualified). The deduced type is std::packaged_task. + 3) This overload participates in overload resolution only if &F::operator() is + well-formed when treated as an unevaluated operand and F::operator() is an explicit + object parameter function whose type is of form R(G, A...) or R(G, A...) noexcept. + The deduced type is std::packaged_task. + 4) This overload participates in overload resolution only if &F::operator() is + well-formed when treated as an unevaluated operand and F::operator() is a static + member function whose type is of form R(A...) or R(A...) noexcept. The deduced type + is std::packaged_task. + +.SH Notes + + These deduction guides do not allow deduction from a function with ellipsis + parameter, and the ... in the types is always treated as a pack expansion. + +.SH Example + + +// Run this code + + #include + + int func(double) { return 0; } + + int main() + { + std::packaged_task f{func}; // deduces packaged_task + + int i = 5; + std::packaged_task g = [&](double) { return i; }; // => packaged_task + } diff --git a/man/deductionguidesforstd::pair.3 b/man/deductionguidesforstd::pair.3 new file mode 100644 index 000000000..e9bcba095 --- /dev/null +++ b/man/deductionguidesforstd::pair.3 @@ -0,0 +1,25 @@ +.TH deductionguidesforstd::pair 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::pair \- deductionguidesforstd::pair + +.SH Synopsis + Defined in header + template \fI(since C++17)\fP + pair(T1, T2) -> pair; + + One deduction guide is provided for std::pair to account for the edge cases missed + by the implicit deduction guides, in particular, non-copyable arguments and array to + pointer conversion. + +.SH Example + + +// Run this code + + #include + + int main() + { + int a[2], b[3]; + std::pair p{a, b}; // explicit deduction guide is used in this case + } diff --git a/man/deductionguidesforstd::priority_queue.3 b/man/deductionguidesforstd::priority_queue.3 new file mode 100644 index 000000000..9bc154e63 --- /dev/null +++ b/man/deductionguidesforstd::priority_queue.3 @@ -0,0 +1,143 @@ +.TH deductionguidesforstd::priority_queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::priority_queue \- deductionguidesforstd::priority_queue + +.SH Synopsis + Defined in header + template< class Comp, class Container > + + priority_queue( Comp, Container ) \fB(1)\fP \fI(since C++17)\fP + + -> priority_queue; + template< class InputIt, + + class Comp = std::less>, + class Container = + std::vector > \fB(2)\fP \fI(since C++17)\fP + priority_queue( InputIt, InputIt, Comp = Comp(), Container = + Container() ) + + -> priority_queue, Container, + Comp>; + template< class Comp, class Container, class Alloc > + + priority_queue( Comp, Container, Alloc ) \fB(3)\fP \fI(since C++17)\fP + + -> priority_queue; + template< class InputIt, class Alloc > + + priority_queue( InputIt, InputIt, Alloc ) + -> priority_queue, \fB(4)\fP \fI(since C++17)\fP + std::vector, + Alloc>, + + std::less>>; + template< class InputIt, class Comp, class Alloc > + + priority_queue( InputIt, InputIt, Comp, Alloc ) + -> priority_queue, \fB(5)\fP \fI(since C++17)\fP + + std::vector, + Alloc>, Comp>; + template< class InputIt, class Comp, class Container, class Alloc + > + + priority_queue( InputIt, InputIt, Comp, Container, Alloc ) \fB(6)\fP \fI(since C++17)\fP + + -> priority_queue; + template< ranges::input_range R, + + class Comp = std::less> > + priority_queue( std::from_range_t, R&&, Comp = Comp() ) \fB(7)\fP (since C++23) + -> priority_queue, + + std::vector>, + Comp>; + template< ranges::input_range R, class Comp, class Alloc > + + priority_queue( std::from_range_t, R&&, Comp, Alloc ) + -> priority_queue, \fB(8)\fP (since C++23) + + std::vector, + Alloc>, Comp>; + template< ranges::input_range R, class Alloc > + + priority_queue( std::from_range_t, R&&, Alloc ) + -> priority_queue, \fB(9)\fP (since C++23) + + std::vector, + Alloc>>; + + The following deduction guides are provided for std::priority_queue: + + 1-6) Allow deduction from underlying container type and from an iterator range. + /*iter-value-type*/ denotes typename std::iterator_traits::value_type for + any type It. + 7-9) Allow deduction from a std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if + + * InputIt satisfies LegacyInputIterator, + * Comp does not satisfy Allocator, + * Container does not satisfy Allocator, + * for overloads (4,5), + (since C++23) Alloc satisfies Allocator, and + * for overloads (3,6), std::uses_allocator_v is true. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (7-9) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::vector v = {1, 2, 3, 4}; + std::priority_queue pq1{std::greater{}, v}; // deduces std::priority_queue< + // int, std::vector, + // std::greater> + for (; !pq1.empty(); pq1.pop()) + std::cout << pq1.top() << ' '; + std::cout << '\\n'; + + std::priority_queue pq2{v.begin(), v.end()}; // deduces std::priority_queue + + for (; !pq2.empty(); pq2.pop()) + std::cout << pq2.top() << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 + 4 3 2 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3506 C++17 deduction guides from iterator and allocator added + were missing diff --git a/man/deductionguidesforstd::queue.3 b/man/deductionguidesforstd::queue.3 new file mode 100644 index 000000000..c1bf8a758 --- /dev/null +++ b/man/deductionguidesforstd::queue.3 @@ -0,0 +1,97 @@ +.TH deductionguidesforstd::queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::queue \- deductionguidesforstd::queue + +.SH Synopsis + Defined in header + template< class Container > + + queue( Container ) \fB(1)\fP \fI(since C++17)\fP + + -> queue; + template< class Container, class Alloc > + + queue( Container, Alloc ) \fB(2)\fP \fI(since C++17)\fP + + -> queue; + template< class InputIt > + + queue( InputIt, InputIt ) \fB(3)\fP (since C++23) + + -> queue::value_type>; + template< class InputIt, class Alloc > + + queue( InputIt, InputIt, Alloc ) + -> queue::value_type, \fB(4)\fP (since C++23) + + std::deque::value_type, Alloc>>; + template< ranges::input_range R > + + queue( std::from_range_t, R&& ) \fB(5)\fP (since C++23) + + -> queue>; + template< ranges::input_range R, class Allocator > + + queue( std::from_range_t, R&&, Allocator ) \fB(6)\fP (since C++23) + -> queue, + + std::deque, Allocator>>; + + These deduction guides are provided for queue to allow deduction from underlying + container type. + + 1) Deduces underlying container type from the argument. + 2) Same as \fB(1)\fP, except that the allocator is provided. + 3) Deduces the element type from the iterator, using std::deque::value_type> as the underlying container type. + 4) Same as \fB(3)\fP, except that the allocator is provided. + 5) Deduces the element type from a std::from_range_t tag and an input_range. + 6) Same as \fB(5)\fP, except that the allocator is provided. + + These overloads participate in overload resolution only if + + * InputIt (if exists) satisfies LegacyInputIterator, + * Container (if exists) does not satisfy Allocator, + * for + \fB(3)\fP + (until C++23) + \fB(4)\fP + (since C++23), Alloc satisfies Allocator, and + * std::uses_allocator_v is true if both Container and Alloc + exist. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + Iterator pair + constructors for + __cpp_lib_adaptor_iterator_pair_constructor 202106L (C++23) std::queue and + std::stack; overloads + \fB(2)\fP and \fB(4)\fP + Ranges-aware + __cpp_lib_containers_ranges 202202L (C++23) construction and + insertion; overloads \fB(5)\fP + and \fB(6)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::vector v = {1, 2, 3, 4}; + std::queue s{v}; // guide #1 deduces std::queue> + } diff --git a/man/deductionguidesforstd::ranges::cartesian_product_view.3 b/man/deductionguidesforstd::ranges::cartesian_product_view.3 new file mode 100644 index 000000000..17fbe3b9d --- /dev/null +++ b/man/deductionguidesforstd::ranges::cartesian_product_view.3 @@ -0,0 +1,22 @@ +.TH deductionguidesforstd::ranges::cartesian_product_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::cartesian_product_view \- deductionguidesforstd::ranges::cartesian_product_view + +.SH Synopsis + Defined in header + template< class... Rs > + + cartesian_product_view( Rs&&... ) -> (since C++23) + + cartesian_product_view...>; + + The deduction guide is provided for std::ranges::cartesian_product_view to allow + deduction from ranges. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::chunk_by_view.3 b/man/deductionguidesforstd::ranges::chunk_by_view.3 new file mode 100644 index 000000000..e116ecce1 --- /dev/null +++ b/man/deductionguidesforstd::ranges::chunk_by_view.3 @@ -0,0 +1,18 @@ +.TH deductionguidesforstd::ranges::chunk_by_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::chunk_by_view \- deductionguidesforstd::ranges::chunk_by_view + +.SH Synopsis + template< class R, class Pred > (since C++23) + chunk_by_view( R&&, Pred ) -> chunk_by_view, Pred>; + + The deduction guide is provided for std::ranges::chunk_by_view to allow deduction + from range and predicate function. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::chunk_view.3 b/man/deductionguidesforstd::ranges::chunk_view.3 new file mode 100644 index 000000000..118a3e856 --- /dev/null +++ b/man/deductionguidesforstd::ranges::chunk_view.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::ranges::chunk_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::chunk_view \- deductionguidesforstd::ranges::chunk_view + +.SH Synopsis + Defined in header + template< class R > + chunk_view( R&&, ranges::range_difference_t ) -> (since C++23) + chunk_view>; + + The deduction guide is provided for ranges::chunk_view only if V models the + input_range. This guide allows deduction from range and number of elements. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::common_view.3 b/man/deductionguidesforstd::ranges::common_view.3 new file mode 100644 index 000000000..66d284802 --- /dev/null +++ b/man/deductionguidesforstd::ranges::common_view.3 @@ -0,0 +1,19 @@ +.TH deductionguidesforstd::ranges::common_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::common_view \- deductionguidesforstd::ranges::common_view + +.SH Synopsis + Defined in header + template< class R > \fI(since C++20)\fP + common_view( R&& ) -> common_view>; + + The deduction guide is provided for std::ranges::common_view to allow deduction from + range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::drop_view.3 b/man/deductionguidesforstd::ranges::drop_view.3 new file mode 100644 index 000000000..768530cde --- /dev/null +++ b/man/deductionguidesforstd::ranges::drop_view.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::ranges::drop_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::drop_view \- deductionguidesforstd::ranges::drop_view + +.SH Synopsis + Defined in header + template< class R > + drop_view( R&&, ranges::range_difference_t ) -> \fI(since C++20)\fP + drop_view>; + + The deduction guide is provided for std::ranges::drop_view to allow deduction from + range and number of elements. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::drop_while_view.3 b/man/deductionguidesforstd::ranges::drop_while_view.3 new file mode 100644 index 000000000..2f708d5fc --- /dev/null +++ b/man/deductionguidesforstd::ranges::drop_while_view.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::ranges::drop_while_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::drop_while_view \- deductionguidesforstd::ranges::drop_while_view + +.SH Synopsis + Defined in header + template< class R, class Pred > + drop_while_view( R&&, Pred ) -> drop_while_view, \fI(since C++20)\fP + Pred>; + + The deduction guide is provided for std::ranges::drop_while_view to allow deduction + from range and predicate. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::enumerate_view.3 b/man/deductionguidesforstd::ranges::enumerate_view.3 new file mode 100644 index 000000000..fbd13aafc --- /dev/null +++ b/man/deductionguidesforstd::ranges::enumerate_view.3 @@ -0,0 +1,19 @@ +.TH deductionguidesforstd::ranges::enumerate_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::enumerate_view \- deductionguidesforstd::ranges::enumerate_view + +.SH Synopsis + Defined in header + template< class R > (since C++23) + enumerate_view( R&& ) -> enumerate_view>; + + The deduction guide is provided for std::ranges::enumerate_view to allow deduction + from range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::join_view.3 b/man/deductionguidesforstd::ranges::join_view.3 new file mode 100644 index 000000000..ffe1e0404 --- /dev/null +++ b/man/deductionguidesforstd::ranges::join_view.3 @@ -0,0 +1,18 @@ +.TH deductionguidesforstd::ranges::join_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::join_view \- deductionguidesforstd::ranges::join_view + +.SH Synopsis + template \fI(since C++20)\fP + explicit join_view(R&&) -> join_view>; + + The deduction guide is provided for std::ranges::join_view to allow deduction from + range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::join_with_view.3 b/man/deductionguidesforstd::ranges::join_with_view.3 new file mode 100644 index 000000000..fe6eb3147 --- /dev/null +++ b/man/deductionguidesforstd::ranges::join_with_view.3 @@ -0,0 +1,32 @@ +.TH deductionguidesforstd::ranges::join_with_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::join_with_view \- deductionguidesforstd::ranges::join_with_view + +.SH Synopsis + Defined in header + template< class R, class P > (since + join_with_view( R&&, P&& ) -> join_with_view, \fB(1)\fP C++23) + views::all_t

>; + template< class R > + + join_with_view( R&&, ranges::range_value_t> + ) (since + -> join_with_view, \fB(2)\fP C++23) + ranges::single_view< + + + ranges::range_value_t>>; + + These deduction guides are provided for join_with_view to allow deduction from a + range and a delimiter. + + 1) The delimiter is a range of elements. + 2) The delimiter is a single element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::lazy_split_view.3 b/man/deductionguidesforstd::ranges::lazy_split_view.3 new file mode 100644 index 000000000..18711c194 --- /dev/null +++ b/man/deductionguidesforstd::ranges::lazy_split_view.3 @@ -0,0 +1,52 @@ +.TH deductionguidesforstd::ranges::lazy_split_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::lazy_split_view \- deductionguidesforstd::ranges::lazy_split_view + +.SH Synopsis + template< class R, class P > + + lazy_split_view( R&&, P&& ) \fB(1)\fP \fI(since C++20)\fP + + -> lazy_split_view, views::all_t

>; + template< ranges::input_range R > + + lazy_split_view( R&&, ranges::range_value_t ) + -> lazy_split_view, \fB(2)\fP \fI(since C++20)\fP + + + ranges::single_view>>; + + These deduction guides are provided for lazy_split_view to allow deduction from a + range and a delimiter. + + 1) The delimiter is a range of elements. + 2) The delimiter is a single element. + +.SH Example + + +// Run this code + + #include + #include + #include + using std::operator""sv; + + int main() + { + std::ranges::lazy_split_view w1{"a::b::c"sv, "::"sv}; + // type of w1 is lazy_split_view: + static_assert(std::is_same_v< + decltype(w1), + std::ranges::lazy_split_view< + std::basic_string_view>, + std::basic_string_view>>>); + + std::ranges::lazy_split_view w2{"x,y,z"sv, ','}; + // type of w2 is lazy_split_view>: + static_assert(std::is_same_v< + decltype(w2), + std::ranges::lazy_split_view< + std::basic_string_view>, + std::ranges::single_view>>); + } diff --git a/man/deductionguidesforstd::ranges::slide_view.3 b/man/deductionguidesforstd::ranges::slide_view.3 new file mode 100644 index 000000000..e72534ca6 --- /dev/null +++ b/man/deductionguidesforstd::ranges::slide_view.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::ranges::slide_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::slide_view \- deductionguidesforstd::ranges::slide_view + +.SH Synopsis + Defined in header + template< class R > + slide_view( R&&, ranges::range_difference_t ) -> (since C++23) + slide_view>; + + The deduction guide is provided for std::ranges::slide_view to allow deduction from + range and number of elements. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::split_view.3 b/man/deductionguidesforstd::ranges::split_view.3 new file mode 100644 index 000000000..2e7d5c885 --- /dev/null +++ b/man/deductionguidesforstd::ranges::split_view.3 @@ -0,0 +1,44 @@ +.TH deductionguidesforstd::ranges::split_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::split_view \- deductionguidesforstd::ranges::split_view + +.SH Synopsis + template< class R, class P > + + split_view( R&&, P&& ) \fB(1)\fP \fI(since C++20)\fP + + -> split_view, views::all_t

>; + template< ranges::input_range R > + + split_view( R&&, ranges::range_value_t ) \fB(2)\fP \fI(since C++20)\fP + + -> split_view, + ranges::single_view>>; + + These deduction guides are provided for split_view to allow deduction from a range + and a delimiter. + + 1) The delimiter is a range of elements. + 2) The delimiter is a single element. + +.SH Example + + +// Run this code + + #include + #include + #include + using std::operator""sv; + + int main() { + std::ranges::split_view w1{"a::b::c"sv, "::"sv}; + static_assert(std::is_same_v< + decltype(w1), + std::ranges::split_view>); + + std::ranges::split_view w2{"x,y,z"sv, ','}; + static_assert(std::is_same_v< + decltype(w2), + std::ranges::split_view>>); + } diff --git a/man/deductionguidesforstd::ranges::stride_view.3 b/man/deductionguidesforstd::ranges::stride_view.3 new file mode 100644 index 000000000..bdd3d0745 --- /dev/null +++ b/man/deductionguidesforstd::ranges::stride_view.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::ranges::stride_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::stride_view \- deductionguidesforstd::ranges::stride_view + +.SH Synopsis + Defined in header + template< class R > + stride_view( R&&, ranges::range_difference_t ) -> (since C++23) + stride_view>; + + The deduction guide is provided for std::ranges::stride_view to allow deduction from + range and number of elements. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::subrange.3 b/man/deductionguidesforstd::ranges::subrange.3 new file mode 100644 index 000000000..8f2360914 --- /dev/null +++ b/man/deductionguidesforstd::ranges::subrange.3 @@ -0,0 +1,71 @@ +.TH deductionguidesforstd::ranges::subrange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::subrange \- deductionguidesforstd::ranges::subrange + +.SH Synopsis + Defined in header + template< std::input_or_output_iterator I, std::sentinel_for S > \fB(1)\fP (since + subrange(I, S) -> subrange; C++20) + template< std::input_or_output_iterator I, std::sentinel_for S > + (since + subrange(I, S, /*make-unsigned-like-t*/>) -> \fB(2)\fP C++20) + + subrange; + template< ranges::borrowed_range > + + subrange(R&&) -> + subrange, ranges::sentinel_t, + (ranges::sized_range || \fB(3)\fP (since + std::sized_sentinel_for, C++20) + ranges::iterator_t>) ? + + ranges::subrange_kind::sized : + ranges::subrange_kind::unsized>; + template< ranges::borrowed_range > + + subrange(R&&, /*make-unsigned-like-t*/>) (since + -> \fB(4)\fP C++20) + subrange, ranges::sentinel_t, + + ranges::subrange_kind::sized>; + + These deduction guides are provided for std::ranges::subrange. + + 1) Deduces the template arguments from the type of iterator and sentinel. The + subrange is sized if std::sized_sentinel_for is satisfied, as determined by + the default template argument. + 2) Deduces the template arguments from the type of iterator and sentinel, while the + size of range is specified. The subrange is always sized. + 3) Deduces the template arguments from the type of range. The subrange is sized if + the size can be obtained from the range or its iterator and sentinel. + 4) Deduces the template arguments from the type of range, while the size of range is + specified. The subrange is always sized. + + The exposition-only alias template make-unsigned-like-t maps each integer-like type + to its corresponding unsigned version. + +.SH Notes + + While constructing the subrange object, + + * for (1,2), the behavior is undefined if the iterator-sentinel pair does not + denote a valid range, + * for (2,4), the behavior is undefined if the given size is not equal to the size + of the range. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3404 C++20 meaningless deduction guides from pair-like removed + types were provided + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::take_view.3 b/man/deductionguidesforstd::ranges::take_view.3 new file mode 100644 index 000000000..acbb263fa --- /dev/null +++ b/man/deductionguidesforstd::ranges::take_view.3 @@ -0,0 +1,30 @@ +.TH deductionguidesforstd::ranges::take_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::take_view \- deductionguidesforstd::ranges::take_view + +.SH Synopsis + Defined in header + template< class R > + take_view( R&&, ranges::range_difference_t ) -> \fI(since C++20)\fP + take_view>; + + The deduction guide is provided for std::ranges::take_view to allow deduction from + range and number of elements. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the template parameter R is R is unconstrained + LWG 3447 C++20 constrained with range (but range_difference_t requires + range) + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::take_while_view.3 b/man/deductionguidesforstd::ranges::take_while_view.3 new file mode 100644 index 000000000..b8eb552ff --- /dev/null +++ b/man/deductionguidesforstd::ranges::take_while_view.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::ranges::take_while_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::take_while_view \- deductionguidesforstd::ranges::take_while_view + +.SH Synopsis + Defined in header + template< class R, class Pred > + take_while_view( R&&, Pred ) -> take_while_view, \fI(since C++20)\fP + Pred>; + + The deduction guide is provided for std::ranges::take_while_view to allow deduction + from range and predicate. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::transform_view.3 b/man/deductionguidesforstd::ranges::transform_view.3 new file mode 100644 index 000000000..36ba00683 --- /dev/null +++ b/man/deductionguidesforstd::ranges::transform_view.3 @@ -0,0 +1,18 @@ +.TH deductionguidesforstd::ranges::transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::transform_view \- deductionguidesforstd::ranges::transform_view + +.SH Synopsis + template< class R, class F > \fI(since C++20)\fP + transform_view( R&&, F ) -> transform_view, F>; + + The deduction guide is provided for std::ranges::transform_view to allow deduction + from range and transformation function. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::ranges::zip_transform_view.3 b/man/deductionguidesforstd::ranges::zip_transform_view.3 new file mode 100644 index 000000000..590e2f792 --- /dev/null +++ b/man/deductionguidesforstd::ranges::zip_transform_view.3 @@ -0,0 +1,19 @@ +.TH deductionguidesforstd::ranges::zip_transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::zip_transform_view \- deductionguidesforstd::ranges::zip_transform_view + +.SH Synopsis + template< class F, class... Rs > + zip_transform_view( F, Rs&&... ) -> zip_transform_view...>; + + The deduction guide is provided for std::ranges::zip_transform_view to allow + deduction from transformation function and ranges. + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/deductionguidesforstd::ranges::zip_view.3 b/man/deductionguidesforstd::ranges::zip_view.3 new file mode 100644 index 000000000..0f2d36a47 --- /dev/null +++ b/man/deductionguidesforstd::ranges::zip_view.3 @@ -0,0 +1,18 @@ +.TH deductionguidesforstd::ranges::zip_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::ranges::zip_view \- deductionguidesforstd::ranges::zip_view + +.SH Synopsis + template< class... Rs > (since C++23) + zip_view( Rs&&... ) -> zip_view...>; + + The deduction guide is provided for std::ranges::zip_view to allow deduction from + ranges. + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/deductionguidesforstd::reference_wrapper.3 b/man/deductionguidesforstd::reference_wrapper.3 new file mode 100644 index 000000000..97ec85069 --- /dev/null +++ b/man/deductionguidesforstd::reference_wrapper.3 @@ -0,0 +1,30 @@ +.TH deductionguidesforstd::reference_wrapper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::reference_wrapper \- deductionguidesforstd::reference_wrapper + +.SH Synopsis + Defined in header + template< typename T > \fI(since C++17)\fP + reference_wrapper( T& ) -> reference_wrapper; + + One deduction guide is provided for std::reference_wrapper to support deduction of + the sole class template parameter. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2981 C++17 a redundant deduction guide from removed + reference_wrapper was provided + LWG 2993 C++17 defect resolution removed a constructor added deduction guide + used for class template argument deduction to compensate + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::scoped_allocator_adaptor.3 b/man/deductionguidesforstd::scoped_allocator_adaptor.3 new file mode 100644 index 000000000..c1e2159ae --- /dev/null +++ b/man/deductionguidesforstd::scoped_allocator_adaptor.3 @@ -0,0 +1,22 @@ +.TH deductionguidesforstd::scoped_allocator_adaptor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::scoped_allocator_adaptor \- deductionguidesforstd::scoped_allocator_adaptor + +.SH Synopsis + Defined in header + template< class OuterAlloc, class... InnerAllocs > + + scoped_allocator_adaptor( OuterAlloc, InnerAllocs... ) \fI(since C++17)\fP + + -> scoped_allocator_adaptor; + + One deduction guide is provided for std::scoped_allocator_adaptor to make it + possible to deduce its outer allocator. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::set.3 b/man/deductionguidesforstd::set.3 new file mode 100644 index 000000000..7f3fdf3f9 --- /dev/null +++ b/man/deductionguidesforstd::set.3 @@ -0,0 +1,88 @@ +.TH deductionguidesforstd::set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::set \- deductionguidesforstd::set + +.SH Synopsis + Defined in header + template< + + class InputIt, + class Comp = std::less::value_type>, + class Alloc = std::allocator::value_type>> + set( InputIt, InputIt, Comp = Comp(), Alloc = Alloc() ) + + -> set::value_type, + Comp, Alloc>; + template< + + class Key, class Comp = std::less, + class Alloc = std::allocator > \fB(2)\fP \fI(since C++17)\fP + set( std::initializer_list, Comp = Comp(), Alloc = Alloc() ) + + -> set; + template< class InputIt, class Alloc > + + set( InputIt, InputIt, Alloc ) + -> set::value_type, \fB(3)\fP \fI(since C++17)\fP + + std::less::value_type>, Alloc>; + template< class Key, class Alloc > + + set( std::initializer_list, Alloc ) \fB(4)\fP \fI(since C++17)\fP + + -> set, Alloc>; + template< ranges::input_range R, class Compare = + less>, + + class Alloc = std::allocator> > \fB(5)\fP (since C++23) + set( std::from_range_t, R&&, Compare = Compare(), Alloc = Alloc() + ) + + -> set, Compare, Alloc>; + template< ranges::input_range R, class Alloc > + + set( std::from_range_t, R&&, Alloc ) \fB(6)\fP (since C++23) + + -> set, + std::less>, Alloc>; + + 1-4) These deduction guides are provided for set to allow deduction from an iterator + range (overloads (1,3)) and std::initializer_list (overloads (2,4)). + 5,6) These deduction guides are provided for set to allow deduction from a + std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, and Comp does not satisfy Allocator. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload (5,6) + +.SH Example + + +// Run this code + + #include + + int main() + { + // guide #2 deduces std::set + std::set s = {1, 2, 3, 4}; + + // guide #1 deduces std::set + std::set s2(s.begin(), s.end()); + } diff --git a/man/deductionguidesforstd::shared_ptr.3 b/man/deductionguidesforstd::shared_ptr.3 new file mode 100644 index 000000000..52f28292b --- /dev/null +++ b/man/deductionguidesforstd::shared_ptr.3 @@ -0,0 +1,31 @@ +.TH deductionguidesforstd::shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::shared_ptr \- deductionguidesforstd::shared_ptr + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++17)\fP + shared_ptr( std::weak_ptr ) -> shared_ptr; + template< class T, class D > \fB(2)\fP \fI(since C++17)\fP + shared_ptr( std::unique_ptr ) -> shared_ptr; + + These deduction guides are provided for std::shared_ptr to account for the edge + cases missed by the implicit deduction guides. + + Note that there is no class template argument deduction from pointer types because + it is impossible to distinguish pointers obtained from array and non-array forms of + new. + +.SH Example + + +// Run this code + + #include + + int main() + { + auto p = std::make_shared(42); + std::weak_ptr w{p}; // explicit deduction guide is used in this case + std::shared_ptr p2{w}; // explicit deduction guide is used in this case + } diff --git a/man/deductionguidesforstd::span.3 b/man/deductionguidesforstd::span.3 new file mode 100644 index 000000000..ae73372ba --- /dev/null +++ b/man/deductionguidesforstd::span.3 @@ -0,0 +1,115 @@ +.TH deductionguidesforstd::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::span \- deductionguidesforstd::span + +.SH Synopsis + Defined in header + template< class It, class EndOrSize > (since + span( It, EndOrSize ) -> C++20) + span>>; (until + C++26) + template< class It, class EndOrSize > + + span( It, EndOrSize ) -> (since + span>, C++26) + + /*maybe-static-ext*/>; \fB(1)\fP + template< class T, std::size_t N > \fB(2)\fP (since + span( T (&)[N] ) -> span; C++20) + template< class T, std::size_t N > \fB(3)\fP (since + span( std::array& ) -> span; C++20) + template< class T, std::size_t N > \fB(4)\fP (since + span( const std::array& ) -> span; C++20) + template< class R > (since + span( R&& ) -> \fB(5)\fP C++20) + span>>; + + The following deduction guides are provided for span. + + 1) Allows the element type to be deduced from the iterator-sentinel pair. + It also allows the static extent to be deduced if EndOrSize satisfies + integral-constant-like. + (since C++26). This overload participates in overload resolution only if It + satisfies contiguous_iterator. + 2-4) Allows the static extent to be deduced from built-in arrays and std::array. + 5) Allows the element type to be deduced from ranges. This overload participates in + overload resolution only if R satisfies contiguous_range. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(std::string_view rem = "", std::size_t size_of = 0, std::size_t extent = 0) + { + if (rem.empty()) + { + std::cout << "name │ sizeof │ extent\\n" + "─────┼────────┼────────\\n"; + return; + } + std::cout << std::setw(4) << rem << " │ " << std::setw(6) << size_of << " │ "; + if (extent == std::dynamic_extent) + std::cout << "dynamic"; + else + std::cout << extent; + std::cout << '\\n'; + } + + int main() + { + int a[]{1, 2, 3, 4, 5}; + + print(); + std::span s1{std::begin(a), std::end(a)}; // guide (1) + print("s1", sizeof s1, s1.extent); + + std::span s2{std::begin(a), 3}; // guide (1) + print("s2", sizeof s2, s2.extent); + + #if __cplusplus > 202302L + std::span s3{std::begin(a), std::integral_constant{}}; // guide (1) + print("s3", sizeof s3, s3.extent); + #endif // C++26 + + std::span s4{a}; // guide (2) + print("s4", sizeof s4, s4.extent); + + std::span s5{a}; // does not use a guide, makes a dynamic span + print("s5", sizeof s5, s5.extent); + + std::array arr{6, 7, 8}; + std::span s6{arr}; // guide (3) + print("s6", sizeof s6, s6.extent); + s6[0] = 42; // OK, element_type is 'int' + + const std::array arr2{9, 10, 11}; + std::span s7{arr2}; // guide (4) + print("s7", sizeof s7, s7.extent); + // s7[0] = 42; // Error: element_type is 'const int' + + std::vector v{66, 69, 99}; + std::span s8{v}; // guide (5) + print("s8", sizeof s8, s8.extent); + } + +.SH Possible output: + + name │ sizeof │ extent + ─────┼────────┼──────── + s1 │ 16 │ dynamic + s2 │ 16 │ dynamic + s3 │ 8 │ 2 + s4 │ 8 │ 5 + s5 │ 16 │ dynamic + s6 │ 8 │ 3 + s7 │ 8 │ 3 + s8 │ 16 │ dynamic diff --git a/man/deductionguidesforstd::stack.3 b/man/deductionguidesforstd::stack.3 new file mode 100644 index 000000000..7e178d43f --- /dev/null +++ b/man/deductionguidesforstd::stack.3 @@ -0,0 +1,97 @@ +.TH deductionguidesforstd::stack 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::stack \- deductionguidesforstd::stack + +.SH Synopsis + Defined in header + template< class Container > + + stack( Container ) \fB(1)\fP \fI(since C++17)\fP + + -> stack; + template< class Container, class Alloc > + + stack( Container, Alloc ) \fB(2)\fP \fI(since C++17)\fP + + -> stack; + template< class InputIt > + + stack( InputIt, InputIt ) \fB(3)\fP (since C++23) + + -> stack::value_type>; + template< class InputIt, class Alloc > + + stack( InputIt, InputIt, Alloc ) + -> stack::value_type, \fB(4)\fP (since C++23) + + std::deque::value_type, Alloc>>; + template< ranges::input_range R > + + stack( std::from_range_t, R&& ) \fB(5)\fP (since C++23) + + -> stack>; + template< ranges::input_range R, class Allocator > + + stack( std::from_range_t, R&&, Allocator ) \fB(6)\fP (since C++23) + -> stack, + + std::deque, Allocator>>; + + These deduction guides are provided for stack to allow deduction from underlying + container type. + + 1) Deduces underlying container type from the argument. + 2) Same as \fB(1)\fP, except that the allocator is provided. + 3) Deduces the element type from the iterator, using std::deque::value_type> as the underlying container type. + 4) Same as \fB(3)\fP, except that the allocator is provided. + 5) Deduces the element type from a std::from_range_t tag and an input_range. + 6) Same as \fB(5)\fP, except that the allocator is provided. + + These overloads participate in overload resolution only if + + * InputIt (if exists) satisfies LegacyInputIterator, + * Container (if exists) does not satisfy Allocator, + * for + \fB(3)\fP + (until C++23) + \fB(4)\fP + (since C++23), Alloc satisfies Allocator, and + * std::uses_allocator_v is true if both Container and Alloc + exist. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + Iterator pair + constructors for + __cpp_lib_adaptor_iterator_pair_constructor 202106L (C++23) std::queue and + std::stack; overloads + \fB(2)\fP and \fB(4)\fP + Ranges-aware + __cpp_lib_containers_ranges 202202L (C++23) construction and + insertion; overloads \fB(5)\fP + and \fB(6)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::vector v = {1, 2, 3, 4}; + std::stack s{v}; // guide #1 deduces std::stack> + } diff --git a/man/deductionguidesforstd::stop_callback.3 b/man/deductionguidesforstd::stop_callback.3 new file mode 100644 index 000000000..a4bc91f92 --- /dev/null +++ b/man/deductionguidesforstd::stop_callback.3 @@ -0,0 +1,20 @@ +.TH deductionguidesforstd::stop_callback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::stop_callback \- deductionguidesforstd::stop_callback + +.SH Synopsis + Defined in header + template< class Callback > + stop_callback( std::stop_token, Callback ) -> \fI(since C++20)\fP + stop_callback; + + One deduction guide is provided for std::stop_callback to permit deduction from + argument of invocable types. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/deductionguidesforstd::tuple.3 b/man/deductionguidesforstd::tuple.3 new file mode 100644 index 000000000..251bf4279 --- /dev/null +++ b/man/deductionguidesforstd::tuple.3 @@ -0,0 +1,34 @@ +.TH deductionguidesforstd::tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::tuple \- deductionguidesforstd::tuple + +.SH Synopsis + Defined in header + template \fB(1)\fP \fI(since C++17)\fP + tuple(UTypes...) -> tuple; + template \fB(2)\fP \fI(since C++17)\fP + tuple(std::pair) -> tuple; + template \fB(3)\fP \fI(since C++17)\fP + tuple(std::allocator_arg_t, Alloc, UTypes...) -> tuple; + template + tuple(std::allocator_arg_t, Alloc, std::pair) -> tuple; + template + tuple(std::allocator_arg_t, Alloc, tuple) -> \fB(5)\fP \fI(since C++17)\fP + tuple; + + These deduction guides are provided for std::tuple to account for the edge cases + missed by the implicit deduction guides, in particular, non-copyable arguments and + array to pointer conversion. + +.SH Example + + +// Run this code + + #include + int main() + { + int a[2], b[3], c[4]; + std::tuple t1{a, b, c}; // explicit deduction guide is used in this case + } diff --git a/man/deductionguidesforstd::unordered_map.3 b/man/deductionguidesforstd::unordered_map.3 new file mode 100644 index 000000000..6c94b357b --- /dev/null +++ b/man/deductionguidesforstd::unordered_map.3 @@ -0,0 +1,218 @@ +.TH deductionguidesforstd::unordered_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::unordered_map \- deductionguidesforstd::unordered_map + +.SH Synopsis + Defined in header + template< class InputIt, + + class Hash = std::hash>, + class Pred = std::equal_to>, + class Alloc = + std::allocator> > + unordered_map( InputIt, InputIt, + typename /*see below*/::size_type = /*see \fB(1)\fP \fI(since C++17)\fP + below*/, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() + ) + -> unordered_map, + iter_val_t, + + Hash, Pred, Alloc>; + template< class Key, class T, class Hash = std::hash, + + class Pred = std::equal_to, + class Alloc = std::allocator> > + unordered_map( std::initializer_list>, \fB(2)\fP \fI(since C++17)\fP + typename /*see below*/::size_type = /*see + below*/, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() + ) + + -> unordered_map; + template< class InputIt, class Alloc > + + unordered_map( InputIt, InputIt, typename /*see + below*/::size_type, Alloc ) + -> unordered_map, \fB(3)\fP \fI(since C++17)\fP + iter_val_t, + std::hash>, + + std::equal_to>, + Alloc>; + template< class InputIt, class Alloc > + + unordered_map( InputIt, InputIt, Alloc ) + -> unordered_map, + iter_val_t, \fB(4)\fP \fI(since C++17)\fP + std::hash>, + + std::equal_to>, + Alloc>; + template< class InputIt, class Hash, class Alloc > + + unordered_map( InputIt, InputIt, typename /*see + below*/::size_type, Hash, Alloc ) + -> unordered_map, \fB(5)\fP \fI(since C++17)\fP + iter_val_t, Hash, + + std::equal_to>, + Alloc>; + template< class Key, class T, typename Alloc > + + unordered_map( std::initializer_list>, + typename /*see below*/::size_type, Alloc ) \fB(6)\fP \fI(since C++17)\fP + + -> unordered_map, + std::equal_to, Alloc>; + template< class Key, class T, typename Alloc > + + unordered_map( std::initializer_list>, + Alloc ) \fB(7)\fP \fI(since C++17)\fP + + -> unordered_map, + std::equal_to, Alloc>; + template< class Key, class T, class Hash, class Alloc > + + unordered_map( std::initializer_list>, + typename /*see below*/::size_type, Hash, \fB(8)\fP \fI(since C++17)\fP + Alloc ) + + -> unordered_map, + Alloc>; + template< ranges::input_range R, + + class Hash = std::hash>, + class Pred = std::equal_to>, + class Alloc = std::allocator> + > + unordered_map( std::from_range_t, R&&, \fB(9)\fP (since C++23) + typename /* see description */::size_type = + /* see description */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() + ) + -> unordered_map, range_mapped_t, + + Hash, Pred, Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_map( std::from_range_t, R&&, + typename /* see description */::size_type, + Alloc ) \fB(10)\fP (since C++23) + -> unordered_map, range_mapped_t, + std::hash>, + + std::equal_to>, Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_map( std::from_range_t, R&&, Alloc ) + -> unordered_map, range_mapped_t, \fB(11)\fP (since C++23) + std::hash>, + + std::equal_to>, Alloc>; + template< ranges::input_range R, class Hash, class Alloc > + + unordered_map( std::from_range_t, R&&, typename /* see + description */::size_type, + Hash, Alloc ) \fB(12)\fP (since C++23) + -> unordered_map, range_mapped_t, + Hash, + + std::equal_to>, Alloc>; + Exposition-only helper type aliases + template< class InputIter > + + using iter_val_t = (exposition only*) + + typename std::iterator_traits::value_type; + template< class InputIter > + + using iter_key_t = (exposition only*) + + std::remove_const_t< std::tuple_element_t<0, + iter_val_t>>; + template< class InputIter > + + using iter_mapped_t = (exposition only*) + + std::tuple_element_t<1, iter_val_t>; + template< class InputIter > + + using iter_to_alloc_t = + std::pair>>, + + std::tuple_element_t<1, + iter_val_t>>; + template< ranges::input_range Range > + + using range_key_t = (since C++23) + (exposition only*) + std::remove_const_t::first_type>; + template< ranges::input_range Range > + (since C++23) + using range_mapped_t = (exposition only*) + + typename ranges::range_value_t::second_type; + template< ranges::input_range Range > + + using range_to_alloc_t = + std::pair::first_type>, (exposition only*) + + typename + ranges::range_value_t::second_type>; + + 1-8) These deduction guide are provided for unordered_map to allow deduction from an + iterator range (overloads (1,3-5)) and std::initializer_list (overloads (2,6-8)). + 9-12) These deduction guides are provided for unordered_map to allow deduction from + a std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, neither Hash nor Pred satisfy + Allocator, and Hash is not an integral type. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + + The size_type parameter type in these guides in an refers to the size_type member + type of the type deduced by the deduction guide. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (9-12) + +.SH Example + + +// Run this code + + #include + + int main() + { + // std::unordered_map m1 = {{"foo", 1}, {"bar", 2}}; + // Error: braced-init-list has no type cannot + // deduce pair from {"foo", 1} or {"bar", 2} + + std::unordered_map m1 = {std::pair{"foo", 2}, {"bar", 3}}; // guide #2 + std::unordered_map m2(m1.begin(), m1.end()); // guide #1 + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3025 C++17 initializer-list guides take use std::pair + std::pair diff --git a/man/deductionguidesforstd::unordered_multimap.3 b/man/deductionguidesforstd::unordered_multimap.3 new file mode 100644 index 000000000..aaa424824 --- /dev/null +++ b/man/deductionguidesforstd::unordered_multimap.3 @@ -0,0 +1,226 @@ +.TH deductionguidesforstd::unordered_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::unordered_multimap \- deductionguidesforstd::unordered_multimap + +.SH Synopsis + Defined in header + template< class InputIt, + + class Hash = std::hash>, + class Pred = std::equal_to>, + class Alloc = + std::allocator> > + unordered_multimap( InputIt, InputIt, + typename /*see below*/::size_type = \fB(1)\fP \fI(since C++17)\fP + /*see below*/, + Hash = Hash(), Pred = Pred(), Alloc = + Alloc() ) + -> unordered_multimap, + iter_val_t, + + Hash, Pred, Alloc>; + template< class Key, class T, class Hash = std::hash, + + class Pred = std::equal_to, + class Alloc = std::allocator> > + unordered_multimap( std::initializer_list>, \fB(2)\fP \fI(since C++17)\fP + typename /*see below*/::size_type = + /*see below*/, + Hash = Hash(), Pred = Pred(), Alloc = + Alloc() ) + + -> unordered_multimap; + template< class InputIt, class Alloc > + + unordered_multimap( InputIt, InputIt, typename /*see + below*/::size_type, Alloc ) + -> unordered_multimap, \fB(3)\fP \fI(since C++17)\fP + iter_val_t, + std::hash>, + + + std::equal_to>, Alloc>; + template< class InputIt, class Alloc > + + unordered_multimap( InputIt, InputIt, Alloc ) + -> unordered_multimap, + iter_val_t, \fB(4)\fP \fI(since C++17)\fP + std::hash>, + + + std::equal_to>, Alloc>; + template< class InputIt, class Hash, class Alloc > + + unordered_multimap( InputIt, InputIt, typename /*see + below*/::size_type, Hash, Alloc ) + -> unordered_multimap, \fB(5)\fP \fI(since C++17)\fP + iter_val_t, Hash, + + + std::equal_to>, Alloc>; + template< class Key, class T, typename Alloc > + + unordered_multimap( std::initializer_list>, + typename /*see below*/::size_type, Alloc \fB(6)\fP \fI(since C++17)\fP + ) + + -> unordered_multimap, + std::equal_to, Alloc>; + template< class Key, class T, typename Alloc > + + unordered_multimap( std::initializer_list>, Alloc ) \fB(7)\fP \fI(since C++17)\fP + + -> unordered_multimap, + std::equal_to, Alloc>; + template< class Key, class T, class Hash, class Alloc > + + unordered_multimap( std::initializer_list>, + typename /*see below*/::size_type, Hash, \fB(8)\fP \fI(since C++17)\fP + Alloc ) + + -> unordered_multimap, + Alloc>; + template< ranges::input_range R, + + class Hash = std::hash>, + class Pred = std::equal_to>, + class Alloc = std::allocator> + > + unordered_multimap( std::from_range_t, R&&, \fB(9)\fP (since C++23) + typename /* see description + */::size_type = /* see description */, + Hash = Hash(), Pred = Pred(), Alloc = + Alloc() ) + -> unordered_multimap, range_mapped_t, + + Hash, Pred, Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_multimap( std::from_range_t, R&&, + typename /* see description + */::size_type, Alloc ) \fB(10)\fP (since C++23) + -> unordered_multimap, range_mapped_t, + std::hash>, + + std::equal_to>, + Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_multimap( std::from_range_t, R&&, Alloc ) + -> unordered_multimap, range_mapped_t, \fB(11)\fP (since C++23) + std::hash>, + + std::equal_to>, + Alloc>; + template< ranges::input_range R, class Hash, class Alloc > + + unordered_multimap( std::from_range_t, R&&, typename /* see + description */::size_type, + Hash, Alloc ) \fB(12)\fP (since C++23) + -> unordered_multimap, range_mapped_t, + Hash, + + std::equal_to>, + Alloc>; + Exposition-only helper type aliases + template< class InputIter > + + using iter_val_t = (exposition only*) + + typename std::iterator_traits::value_type; + template< class InputIter > + + using iter_key_t = (exposition only*) + + std::remove_const_t< std::tuple_element_t<0, + iter_val_t>>; + template< class InputIter > + + using iter_mapped_t = (exposition only*) + + std::tuple_element_t<1, iter_val_t>; + template< class InputIter > + + using iter_to_alloc_t = + std::pair>>, + + std::tuple_element_t<1, + iter_val_t>>; + template< ranges::input_range Range > + + using range_key_t = (since C++23) + (exposition only*) + std::remove_const_t::first_type>; + template< ranges::input_range Range > + (since C++23) + using range_mapped_t = (exposition only*) + + typename ranges::range_value_t::second_type; + template< ranges::input_range Range > + + using range_to_alloc_t = + std::pair::first_type>, (exposition only*) + + typename + ranges::range_value_t::second_type>; + + 1-8) These deduction guide are provided for unordered_multimap to allow deduction + from an iterator range (overloads (1,3-5)) and std::initializer_list (overloads + (2,6-8)). + 9-12) These deduction guides are provided for unordered_multimap to allow deduction + from a std::from_range_t tag and an input_range. + + These overloads participate in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, neither Hash nor Pred satisfy + Allocator, and Hash is not an integral type. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + + The size_type parameter type in these guides in an refers to the size_type member + type of the type deduced by the deduction guide. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (9-12) + +.SH Example + + +// Run this code + + #include + + int main() + { + // std::unordered_multimap m1 = {{"foo", 1}, {"bar", 2}}; + // Error: braced-init-list has no type cannot + // deduce pair from {"foo", 1} or {"bar", 2} + + std::unordered_multimap m1 = {std::pair{"foo", 2}, {"bar", 3}}; // guide #2 + std::unordered_multimap m2(m1.begin(), m1.end()); // guide #1 + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3025 C++17 initializer-list guides take use std::pair + std::pair diff --git a/man/deductionguidesforstd::unordered_multiset.3 b/man/deductionguidesforstd::unordered_multiset.3 new file mode 100644 index 000000000..cec2ea375 --- /dev/null +++ b/man/deductionguidesforstd::unordered_multiset.3 @@ -0,0 +1,153 @@ +.TH deductionguidesforstd::unordered_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::unordered_multiset \- deductionguidesforstd::unordered_multiset + +.SH Synopsis + Defined in header + template< + + class InputIt, + class Hash = std::hash::value_type>, + class Pred = std::equal_to::value_type>, + class Alloc = std::allocator::value_type> > \fB(1)\fP \fI(since C++17)\fP + unordered_multiset( InputIt, InputIt, + typename /* see below */::size_type = /* see + below */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() + ) + -> unordered_multiset::value_type, + + Hash, Pred, Alloc>; + template< class T, + + class Hash = std::hash, + class Pred = std::equal_to, + class Alloc = std::allocator > + unordered_multiset( std::initializer_list, \fB(2)\fP \fI(since C++17)\fP + typename /* see below */::size_type = /* see + below */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() + ) + + -> unordered_multiset; + template< class InputIt, class Alloc > + + unordered_multiset( InputIt, InputIt, typename /* see below + */::size_type, Alloc ) + -> unordered_multiset::value_type, \fB(3)\fP \fI(since C++17)\fP + std::hash::value_type>, + std::equal_to::value_type>, + + Alloc>; + template< class InputIt, class Hash, class Alloc > + + unordered_multiset( InputIt, InputIt, typename /* see below + */::size_type, Hash, Alloc ) + -> unordered_multiset::value_type, Hash, + std::equal_to::value_type>, + + Alloc>; + template< class T, class Alloc > + + unordered_multiset( std::initializer_list, typename /* see + below */::size_type, Alloc ) \fB(5)\fP \fI(since C++17)\fP + + -> unordered_multiset, std::equal_to, + Alloc>; + template< class T, class Hash, class Alloc > + + unordered_multiset( std::initializer_list, typename /* see + below */::size_type, \fB(6)\fP \fI(since C++17)\fP + Hash, Alloc ) + + -> unordered_multiset, Alloc>; + template< ranges::input_range R, + + class Hash = std::hash>, + class Pred = std::equal_to>, + class Alloc = std::allocator> + > + unordered_multiset( std::from_range_t, R&&, \fB(7)\fP (since C++23) + typename /* see below */::size_type = /* see + below */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() + ) + + -> unordered_multiset, Hash, Pred, + Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_multiset( std::from_range_t, R&&, + typename /* see below */::size_type, Alloc ) + -> unordered_multiset, \fB(8)\fP (since C++23) + hash>, + + + std::equal_to>, Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_multiset( std::from_range_t, R&&, Alloc ) + -> unordered_multiset, \fB(9)\fP (since C++23) + hash>, + + + std::equal_to>, Alloc>; + template< ranges::input_range R, class Hash, class Alloc > + + unordered_multiset( std::from_range_t, R&&, + typename /* see below */::size_type, Hash, + Alloc ) \fB(10)\fP (since C++23) + -> unordered_multiset, Hash, + + + std::equal_to>, Alloc>; + + 1-6) These deduction guides are provided for unordered_multiset to allow deduction + from an iterator range (overloads (1,3,4)) and std::initializer_list (overloads + (2,5,6)). This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator, Alloc satisfies Allocator, neither Hash nor Pred + satisfy Allocator, Hash is not an integral type. + 7-10) These deduction guides are provided for unordered_multiset to allow deduction + from a std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + + The size_type parameter type in these guides refers to the size_type member type of + the type deduced by the deduction guide. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (7-10) + +.SH Example + + +// Run this code + + #include + + int main() + { + // guide #2 deduces std::unordered_multiset + std::unordered_multiset s = {1, 2, 3, 4}; + + // guide #1 deduces std::unordered_multiset + std::unordered_multiset s2(s.begin(), s.end()); + } diff --git a/man/deductionguidesforstd::unordered_set.3 b/man/deductionguidesforstd::unordered_set.3 new file mode 100644 index 000000000..087daedcf --- /dev/null +++ b/man/deductionguidesforstd::unordered_set.3 @@ -0,0 +1,148 @@ +.TH deductionguidesforstd::unordered_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::unordered_set \- deductionguidesforstd::unordered_set + +.SH Synopsis + Defined in header + template< + + class InputIt, + class Hash = std::hash::value_type>, + class Pred = std::equal_to::value_type>, + class Alloc = std::allocator::value_type> > \fB(1)\fP \fI(since C++17)\fP + unordered_set( InputIt, InputIt, + typename /* see below */::size_type = /* see below + */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() ) + -> unordered_set::value_type, + + Hash, Pred, Alloc>; + template< class T, + + class Hash = std::hash, + class Pred = std::equal_to, + class Alloc = std::allocator > + unordered_set( std::initializer_list, \fB(2)\fP \fI(since C++17)\fP + typename /* see below */::size_type = /* see below + */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() ) + + -> unordered_set; + template< class InputIt, class Alloc > + + unordered_set( InputIt, InputIt, typename /* see below + */::size_type, Alloc ) + -> unordered_set::value_type, \fB(3)\fP \fI(since C++17)\fP + std::hash::value_type>, + std::equal_to::value_type>, + + Alloc>; + template< class InputIt, class Hash, class Alloc > + + unordered_set( InputIt, InputIt, typename /* see below + */::size_type, Hash, Alloc ) + -> unordered_set::value_type, Hash, + std::equal_to::value_type>, + + Alloc>; + template< class T, class Alloc > + + unordered_set( std::initializer_list, typename /* see below \fB(5)\fP \fI(since C++17)\fP + */::size_type, Alloc ) + + -> unordered_set, std::equal_to, Alloc>; + template< class T, class Hash, class Alloc > + + unordered_set( std::initializer_list, typename /* see below + */::size_type, \fB(6)\fP \fI(since C++17)\fP + Hash, Alloc ) + + -> unordered_set, Alloc>; + template< ranges::input_range R, + + class Hash = std::hash>, + class Pred = std::equal_to>, + class Alloc = std::allocator> + > + unordered_set( std::from_range_t, R&&, \fB(7)\fP (since C++23) + typename /* see below */::size_type = /* see below + */, + Hash = Hash(), Pred = Pred(), Alloc = Alloc() ) + + -> unordered_set, Hash, Pred, + Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_set( std::from_range_t, R&&, + typename /* see below */::size_type, Alloc ) + -> unordered_set, \fB(8)\fP (since C++23) + hash>, + + std::equal_to>, + Alloc>; + template< ranges::input_range R, class Alloc > + + unordered_set( std::from_range_t, R&&, Alloc ) + -> unordered_set, \fB(9)\fP (since C++23) + hash>, + + std::equal_to>, + Alloc>; + template< ranges::input_range R, class Hash, class Alloc > + + unordered_set( std::from_range_t, R&&, + typename /* see below */::size_type, Hash, Alloc ) \fB(10)\fP (since C++23) + -> unordered_set, Hash, + + std::equal_to>, + Alloc>; + + 1-6) These deduction guides are provided for unordered_set to allow deduction from + an iterator range (overloads (1,3,4)) and std::initializer_list (overloads (2,5,6)). + This overload participates in overload resolution only if InputIt satisfies + LegacyInputIterator, Alloc satisfies Allocator, neither Hash nor Pred satisfy + Allocator, Hash is not an integral type. + 7-10) These deduction guides are provided for unordered_set to allow deduction from + a std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + + The size_type parameter type in these guides refers to the size_type member type of + the type deduced by the deduction guide. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (7-10) + +.SH Example + + +// Run this code + + #include + + int main() + { + // guide #2 deduces std::unordered_set + std::unordered_set s = {1, 2, 3, 4}; + + // guide #1 deduces std::unordered_set + std::unordered_set s2(s.begin(), s.end()); + } diff --git a/man/deductionguidesforstd::valarray.3 b/man/deductionguidesforstd::valarray.3 new file mode 100644 index 000000000..c9d6d655c --- /dev/null +++ b/man/deductionguidesforstd::valarray.3 @@ -0,0 +1,32 @@ +.TH deductionguidesforstd::valarray 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::valarray \- deductionguidesforstd::valarray + +.SH Synopsis + Defined in header + template< typename T, std::size_t cnt > \fI(since C++17)\fP + valarray( const T(&)[cnt], std::size_t ) -> valarray; + + This deduction guide is provided for std::valarray to allow deduction from array and + size (note that deduction from pointer and size is covered by the implicit guides). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int a[] = {1, 2, 3, 4}; + std::valarray va(a, 3); // uses explicit deduction guide + for (int x : va) + std::cout << x << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 diff --git a/man/deductionguidesforstd::vector.3 b/man/deductionguidesforstd::vector.3 new file mode 100644 index 000000000..780d50d12 --- /dev/null +++ b/man/deductionguidesforstd::vector.3 @@ -0,0 +1,62 @@ +.TH deductionguidesforstd::vector 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::vector \- deductionguidesforstd::vector + +.SH Synopsis + Defined in header + template< class InputIt, + + class Alloc = std::allocator< + typename std::iterator_traits::value_type> + > \fB(1)\fP \fI(since C++17)\fP + vector( InputIt, InputIt, Alloc = Alloc() ) + + -> vector::value_type, + Alloc>; + template< ranges::input_range R, + + class Alloc = std::allocator> > \fB(2)\fP (since C++23) + vector( std::from_range_t, R&&, Alloc = Alloc() ) + + -> vector, Alloc>; + + 1) This deduction guide is provided for vector to allow deduction from an iterator + range. This overload participates in overload resolution only if InputIt satisfies + LegacyInputIterator and Alloc satisfies Allocator. + 2) This deduction guide is provided for vector to allow deduction from a + std::from_range_t tag and an input_range. + + Note: the extent to which the library determines that a type does not satisfy + LegacyInputIterator is unspecified, except that as a minimum integral types do not + qualify as input iterators. Likewise, the extent to which it determines that a type + does not satisfy Allocator is unspecified, except that as a minimum the member type + Alloc::value_type must exist and the expression + std::declval().allocate(std::size_t{}) must be well-formed when treated as + an unevaluated operand. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + + int main() + { + std::vector v = {1, 2, 3, 4}; + + // uses explicit deduction guide to deduce std::vector + std::vector x(v.begin(), v.end()); + + // deduces std::vector::iterator> + // first phase of overload resolution for list-initialization selects the candidate + // synthesized from the initializer-list constructor; second phase is not performed + // and deduction guide has no effect + std::vector y{v.begin(), v.end()}; + } diff --git a/man/deductionguidesforstd::weak_ptr.3 b/man/deductionguidesforstd::weak_ptr.3 new file mode 100644 index 000000000..d589e8b82 --- /dev/null +++ b/man/deductionguidesforstd::weak_ptr.3 @@ -0,0 +1,24 @@ +.TH deductionguidesforstd::weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +deductionguidesforstd::weak_ptr \- deductionguidesforstd::weak_ptr + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + weak_ptr( std::shared_ptr ) -> weak_ptr; + + One deduction guide is provided for std::weak_ptr to account for the edge case + missed by the implicit deduction guides. + +.SH Example + + +// Run this code + + #include + + int main() + { + auto p = std::make_shared(42); + std::weak_ptr w{p}; // explicit deduction guide is used in this case + } diff --git a/man/iter_move(std::basic_const_iterator).3 b/man/iter_move(std::basic_const_iterator).3 new file mode 100644 index 000000000..d131b6592 --- /dev/null +++ b/man/iter_move(std::basic_const_iterator).3 @@ -0,0 +1,45 @@ +.TH iter_move(std::basic_const_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_move(std::basic_const_iterator) \- iter_move(std::basic_const_iterator) + +.SH Synopsis + friend constexpr /*rvalue-reference*/ + iter_move( const basic_const_iterator& i ) noexcept(/* see below (since C++23) + */); + + Casts the result of dereferencing the underlying iterator to its associated const + rvalue reference type. + + The return type /*rvalue-reference*/ is std::common_reference_t&&, std::iter_rvalue_reference_t>. + + The function body is equivalent to + return static_cast(std::ranges::iter_move(i.base()));. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::basic_const_iterator is + an associated class of the arguments. + +.SH Return value + + An rvalue reference to const, or a prvalue. + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(static_cast(std::ranges::iter_move(i.base())))) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + iter_move casts the result of dereferencing an object to its associated rvalue + (C++20) reference type + (customization point object) + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/iter_move(std::common_iterator).3 b/man/iter_move(std::common_iterator).3 new file mode 100644 index 000000000..14ffbc448 --- /dev/null +++ b/man/iter_move(std::common_iterator).3 @@ -0,0 +1,107 @@ +.TH iter_move(std::common_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_move(std::common_iterator) \- iter_move(std::common_iterator) + +.SH Synopsis + friend constexpr decltype(auto) iter_move( const std::common_iterator& + i ) + (since + noexcept(noexcept(ranges::iter_move(std::declval())) C++20) + + requires std::input_iterator; + + Casts the result of dereferencing the underlying iterator to its associated rvalue + reference type. + + The function body is equivalent to: return + std::ranges::iter_move(std::get(i.var));. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::common_iterator is an + associated class of the arguments. + + If i.var does not hold an I object (i.e. an iterator), the behavior is undefined. + +.SH Parameters + + i - a source iterator adaptor + +.SH Return value + + An rvalue reference or a prvalue temporary. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto const& rem, auto const& v) + { + std::cout << rem << '[' << size(v) << "] { "; + for (int o{}; auto const& s : v) + std::cout << (o++ ? ", " : "") << std::quoted(s); + std::cout << " }\\n"; + } + + int main() + { + std::vector p{"Andromeda", "Cassiopeia", "Phoenix"}, q; + print("p", p); + print("q", q); + + using CTI = std::counted_iterator::iterator>; + using CI = std::common_iterator; + CI last{std::default_sentinel}; + + for (CI first{{p.begin(), 2}}; first != last; ++first) + q.emplace_back(/* ADL */ iter_move(first)); + + print("p", p); + print("q", q); + } + +.SH Possible output: + + p[3] { "Andromeda", "Cassiopeia", "Phoenix" } + q[0] { } + p[3] { "", "", "Phoenix" } + q[2] { "Andromeda", "Cassiopeia" } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3953 C++20 the return type was changed to + std::iter_rvalue_reference_t decltype(auto) + +.SH See also + + iter_move casts the result of dereferencing an object to its associated + (C++20) rvalue reference type + (customization point object) + iter_move casts the result of dereferencing the underlying iterator to + (C++20) its associated rvalue reference type + \fI(function)\fP + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP + move_if_noexcept obtains an rvalue reference if the move constructor does not + \fI(C++11)\fP throw + \fI(function template)\fP + forward forwards a function argument + \fI(C++11)\fP \fI(function template)\fP + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) diff --git a/man/iter_move(std::counted_iterator).3 b/man/iter_move(std::counted_iterator).3 new file mode 100644 index 000000000..0c587b336 --- /dev/null +++ b/man/iter_move(std::counted_iterator).3 @@ -0,0 +1,103 @@ +.TH iter_move(std::counted_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_move(std::counted_iterator) \- iter_move(std::counted_iterator) + +.SH Synopsis + friend constexpr decltype(auto) iter_move( const + std::counted_iterator& i ) + \fI(since C++20)\fP + noexcept(noexcept(ranges::iter_move(i.base()))) + + requires std::input_iterator; + + Casts the result of dereferencing the underlying iterator to its associated rvalue + reference type. + + The function body is equivalent to return ranges::iter_move(i.base());. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::counted_iterator is an + associated class of the arguments. + + If i.count() is equal to 0, the behavior is undefined. + +.SH Parameters + + i - a source iterator adaptor + +.SH Return value + + An rvalue reference or a prvalue temporary. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto const& rem, auto const& v) + { + std::cout << rem << '[' << size(v) << "] {"; + for (char comma[]{0, ' ', 0}; auto const& s : v) + std::cout << comma << std::quoted(s), *comma = ','; + std::cout << "}\\n"; + } + + int main() + { + std::vector p{"Alpha", "Bravo", "Charlie"}, q; + print("p", p); + print("q", q); + + using RI = std::counted_iterator::iterator>; + + for (RI iter{p.begin(), 2}; iter != std::default_sentinel; ++iter) + q.emplace_back(/* ADL */ iter_move(iter)); + + print("p", p); + print("q", q); + } + +.SH Possible output: + + p[3] {"Alpha", "Bravo", "Charlie"} + q[0] {} + p[3] {"", "", "Charlie"} + q[2] {"Alpha", "Bravo"} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3953 C++20 the return type was changed to + std::iter_rvalue_reference_t decltype(auto) + +.SH See also + + iter_move casts the result of dereferencing an object to its associated + (C++20) rvalue reference type + (customization point object) + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function template)\fP + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP + move_if_noexcept obtains an rvalue reference if the move constructor does not + \fI(C++11)\fP throw + \fI(function template)\fP + forward forwards a function argument + \fI(C++11)\fP \fI(function template)\fP + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) diff --git a/man/iter_move(std::move_iterator).3 b/man/iter_move(std::move_iterator).3 new file mode 100644 index 000000000..087d120d7 --- /dev/null +++ b/man/iter_move(std::move_iterator).3 @@ -0,0 +1,97 @@ +.TH iter_move(std::move_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_move(std::move_iterator) \- iter_move(std::move_iterator) + +.SH Synopsis + friend constexpr std::iter_rvalue_reference_t + iter_move( const std::move_iterator& i ) noexcept(/* see below \fI(since C++20)\fP + */); + + Casts the result of dereferencing the underlying iterator to its associated rvalue + reference type. + + The function body is equivalent to: return std::ranges::iter_move(i.base());. + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::move_iterator is + an associated class of the arguments. + +.SH Parameters + + i - a source move iterator + +.SH Return value + + An rvalue reference or a prvalue temporary. + +.SH Complexity + + Constant. + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(ranges::iter_move(i.base()))) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto const& rem, auto const& v) + { + std::cout << rem << '[' << size(v) << "] { "; + for (char comma[]{0, ' ', 0}; auto const& s : v) + std::cout << comma << std::quoted(s), comma[0] = ','; + std::cout << " }\\n"; + } + + int main() + { + std::vector p{"Andromeda", "Cassiopeia", "Phoenix"}, q; + + print("p", p), print("q", q); + + using MI = std::move_iterator::iterator>; + + for (MI first{p.begin()}, last{p.end()}; first != last; ++first) + q.emplace_back(/* ADL */ iter_move(first)); + + print("p", p), print("q", q); + } + +.SH Possible output: + + p[3] { "Andromeda", "Cassiopeia", "Phoenix" } + q[0] { } + p[3] { "", "", "" } + q[3] { "Andromeda", "Cassiopeia", "Phoenix" } + +.SH See also + + iter_move casts the result of dereferencing an object to its associated + (C++20) rvalue reference type + (customization point object) + iter_move casts the result of dereferencing the adjusted underlying + (C++20) iterator to its associated rvalue reference type + \fI(function)\fP + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP + move_if_noexcept obtains an rvalue reference if the move constructor does not + \fI(C++11)\fP throw + \fI(function template)\fP + forward forwards a function argument + \fI(C++11)\fP \fI(function template)\fP + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) + +.SH Category: + * conditionally noexcept diff --git a/man/iter_swap(std::common_iterator).3 b/man/iter_swap(std::common_iterator).3 new file mode 100644 index 000000000..81a3e2dd7 --- /dev/null +++ b/man/iter_swap(std::common_iterator).3 @@ -0,0 +1,117 @@ +.TH iter_swap(std::common_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_swap(std::common_iterator) \- iter_swap(std::common_iterator) + +.SH Synopsis + template< std::indirectly_swappable I2, class S2 > + + friend constexpr void + iter_swap( const common_iterator& x, \fI(since C++20)\fP + + const std::common_iterator& y ) noexcept(/*see + below*/); + + Swaps the objects pointed to by two underlying iterators. The behavior is undefined + if x does not hold an I object or y does not hold an I2 object (i.e. at least one of + x and y does not hold an iterator). + + The function body is equivalent to ranges::iter_swap(std::get(x.var), + std::get(y.var)). + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::common_iterator is + an associated class of the arguments. + +.SH Parameters + + x, y - the iterators to the elements to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(ranges::iter_swap(std::declval(), std::declval()))) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector v1{"1", "2", "3", "4", "5"}, + v2{"α", "β", "γ", "δ", "ε"}; + + using CI = std::common_iterator< + std::counted_iterator::iterator>, + std::default_sentinel_t + >; + + CI first1{std::counted_iterator{v1.begin(), 3}}; + CI first2{std::counted_iterator{v2.begin(), 4}}; + CI last{std::default_sentinel}; + + auto print = [&](auto rem) + { + std::cout << rem << "v1 = "; + std::ranges::copy(v1, std::ostream_iterator{std::cout, " "}); + std::cout << "\\nv2 = "; + std::ranges::copy(v2, std::ostream_iterator{std::cout, " "}); + std::cout << '\\n'; + }; + + print("Before iter_swap:\\n"); + + for (; first1 != last && first2 != last; ++first1, ++first2) + iter_swap(first1, first2); // ADL + + print("After iter_swap:\\n"); + } + +.SH Output: + + Before iter_swap: + v1 = 1 2 3 4 5 + v2 = α β γ δ ε + After iter_swap: + v1 = α β γ 4 5 + v2 = 1 2 3 δ ε + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3574 C++20 variant was fully constexpr (P2231R1) but also made constexpr + common_iterator was not + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/iter_swap(std::counted_iterator).3 b/man/iter_swap(std::counted_iterator).3 new file mode 100644 index 000000000..e5731b64c --- /dev/null +++ b/man/iter_swap(std::counted_iterator).3 @@ -0,0 +1,80 @@ +.TH iter_swap(std::counted_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_swap(std::counted_iterator) \- iter_swap(std::counted_iterator) + +.SH Synopsis + template< std::indirectly_swappable I2 > + + friend constexpr void + iter_swap( const counted_iterator& x, const \fI(since C++20)\fP + std::counted_iterator& y ) + + noexcept(noexcept(ranges::iter_swap(x.base(), + y.base()))); + + Swaps the objects pointed to by two underlying iterators. The behavior is undefined + if either x.count() or y.count() is equal to 0. + + The function body is equivalent to: ranges::iter_swap(x.base(), y.base());. + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::counted_iterator is + an associated class of the arguments. + +.SH Parameters + + x, y - iterator adaptors to the elements to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector p{1, 2, 3, 4}, + q{5, 6, 7, 8}; + + std::counted_iterator::iterator> ip{p.begin(), 2}; + std::counted_iterator::iterator> iq{q.begin(), 3}; + + std::cout << *ip << ' ' << *iq << '\\n'; + iter_swap(ip, iq); // ADL + std::cout << *ip << ' ' << *iq << '\\n'; + + std::list x{0, 1, 3}; + std::counted_iterator::iterator> ix{x.begin(), 2}; + // iter_swap(ip, ix); // error: not indirectly swappable + } + +.SH Output: + + 1 5 + 5 1 + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) + iter_move casts the result of dereferencing the underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP diff --git a/man/iter_swap(std::move_iterator).3 b/man/iter_swap(std::move_iterator).3 new file mode 100644 index 000000000..c76a7f690 --- /dev/null +++ b/man/iter_swap(std::move_iterator).3 @@ -0,0 +1,83 @@ +.TH iter_swap(std::move_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +iter_swap(std::move_iterator) \- iter_swap(std::move_iterator) + +.SH Synopsis + template< std::indirectly_swappable Iter2 > + + friend constexpr void + iter_swap( const move_iterator& x, const \fI(since C++20)\fP + std::move_iterator& y ) + + noexcept(/*see below*/); + + Swaps the objects pointed to by two underlying iterators. The function body is + equivalent to ranges::iter_swap(x.base(), y.base());. + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::move_iterator is + an associated class of the arguments. + +.SH Parameters + + x, y - move iterators to the elements to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(ranges::iter_swap(x.base(), y.base()))) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector p{"AA", "EE"}, + q{"ⱯⱯ", "ƎƎ"}; + + std::move_iterator::iterator> + x = std::make_move_iterator(p.begin()), + y = std::make_move_iterator(q.begin()); + + std::cout << *x << ' ' << *y << '\\n'; + + iter_swap(x, y); // ADL + + std::cout << *x << ' ' << *y << '\\n'; + } + +.SH Output: + + AA ⱯⱯ + ⱯⱯ AA + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) + iter_swap swaps the objects pointed to by two adjusted underlying iterators + (C++20) \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::FILE.3 b/man/std::FILE.3 new file mode 100644 index 000000000..b0e5037d1 --- /dev/null +++ b/man/std::FILE.3 @@ -0,0 +1,43 @@ +.TH std::FILE 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::FILE \- std::FILE + +.SH Synopsis + Defined in header + typedef /* unspecified */ FILE; + + Each std::FILE object denotes a C stream. + + C standard (referenced by C++ standard) does not specify whether std::FILE is a + complete object type. While it may be possible to copy a valid std::FILE, using a + pointer to such a copy as an argument for an I/O function invokes unspecified + behavior. In other words, std::FILE may be semantically non-copyable. + + I/O streams can be used for both unformatted and formatted input and output. + Furthermore, the functions that handle input and output can also be + locale-sensitive, such that wide/multibyte conversions are performed as necessary. + +.SH Notes + + POSIX explicitly requires that the LC_CTYPE facet of the currently installed C + locale be stored within the FILE object the moment the stream's orientation becomes + wide; POSIX requires that this LC_CTYPE facet be used for all future I/O on this + stream until the orientation is changed, regardless of any subsequent call to + std::setlocale. + + It is intended that each line of text be composed of data that are essentially + human-readable. POSIX implementations do not distinguish between text and binary + streams (there is no special mapping for '\\n' or any other characters). + +.SH See also + + basic_streambuf abstracts a raw device + \fI(class template)\fP + basic_filebuf implements raw file device + \fI(class template)\fP + stdin expression of type FILE* associated with the input stream + stdout expression of type FILE* associated with the output stream + stderr expression of type FILE* associated with the error output stream + (macro constant) + C documentation for + FILE diff --git a/man/std::_Exit.3 b/man/std::_Exit.3 index 454b8753f..2df23b55b 100644 --- a/man/std::_Exit.3 +++ b/man/std::_Exit.3 @@ -1,7 +1,10 @@ -.TH std::_Exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::_Exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::_Exit \- std::_Exit + .SH Synopsis Defined in header - [[noreturn]] void _Exit( int exit_code ); \fI(since C++11)\fP + [[noreturn]] void _Exit( int exit_code ) noexcept; \fI(since C++11)\fP Causes normal program termination to occur without completely cleaning the resources. @@ -9,9 +12,11 @@ Destructors of variables with automatic, thread local and static storage durations are not called. Functions passed to std::at_quick_exit() or std::atexit() are not called. Whether open resources such as files are closed is implementation defined. - If exit_code is EXIT_FAILURE, an implementation-defined status, indicating - unsuccessful termination, is returned. In other cases implementation-defined status - value is returned. + + If exit_code is 0 or EXIT_SUCCESS, an implementation-defined status indicating + successful termination is returned to the host environment. If exit_code is + EXIT_FAILURE, an implementation-defined status, indicating unsuccessful termination, + is returned. In other cases implementation-defined status value is returned. .SH Parameters @@ -21,55 +26,51 @@ \fI(none)\fP -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Example - + // Run this code #include - - class Static { + + class Static + { public: ~Static() { std::cout << "Static dtor\\n"; } }; - - class Local { + + class Local + { public: ~Local() { std::cout << "Local dtor\\n"; } }; - + Static static_variable; // dtor of this object will *not* be called - + void atexit_handler() { std::cout << "atexit handler\\n"; } - + int main() { Local local_variable; // dtor of this object will *not* be called - + // handler will *not* be called const int result = std::atexit(atexit_handler); - - if (result != 0) { + + if (result != 0) + { std::cerr << "atexit registration failed\\n"; return EXIT_FAILURE; } - + std::cout << "test" << std::endl; // flush from std::endl // needs to be here, otherwise nothing will be printed std::_Exit(EXIT_FAILURE); @@ -82,8 +83,8 @@ .SH See also abort causes abnormal program termination (without cleaning up) - \fI(function)\fP + \fI(function)\fP exit causes normal program termination with cleaning up - \fI(function)\fP + \fI(function)\fP C documentation for _Exit diff --git a/man/std::abort.3 b/man/std::abort.3 index 3281c6a53..91f3c9546 100644 --- a/man/std::abort.3 +++ b/man/std::abort.3 @@ -1,16 +1,23 @@ -.TH std::abort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::abort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::abort \- std::abort + .SH Synopsis Defined in header - void abort(); \fI(until C++11)\fP - [[noreturn]] void abort(); \fI(since C++11)\fP + void abort(); \fI(until C++11)\fP + [[noreturn]] void abort() noexcept; \fI(since C++11)\fP Causes abnormal program termination unless SIGABRT is being caught by a signal - handler passed to signal and the handler does not return. + handler passed to std::signal and the handler does not return. - Destructors of variables with automatic, thread local and static storage durations - are not called. Functions passed to std::atexit() are also not called. Whether open - resources such as files are closed is implementation defined. Implementation defined - status is returned to the host environment that indicates unsuccessful execution. + Destructors of variables with automatic + , thread local + \fI(since C++11)\fP and static storage durations are not called. Functions registered with + std::atexit() + and std::at_quick_exit + \fI(since C++11)\fP are also not called. Whether open resources such as files are closed + is implementation defined. An implementation defined status is returned to the host + environment that indicates unsuccessful execution. .SH Parameters @@ -18,82 +25,83 @@ .SH Return value - \fI(none)\fP + None because it does not return. .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Throws nothing. + +.SH Notes + + POSIX specifies that the abort() function overrides blocking or ignoring the SIGABRT + signal. + + Some compiler intrinsics, e.g. __builtin_trap (gcc, clang, and icc) or + __fastfail/__debugbreak (msvc), can be used to terminate the program as fast as + possible. .SH Example - + // Run this code - #include // assert - #include // std::signal - #include // std::cout - - class Tester { - public: - Tester() { - std::cout << "Tester ctor\\n"; - } - - ~Tester() { - std::cout << "Tester dtor\\n"; - } + #include + #include + #include + + class Tester + { + public: + Tester() { std::cout << "Tester ctor\\n"; } + ~Tester() { std::cout << "Tester dtor\\n"; } }; - - // Destructor not called - Tester static_tester; - - void signal_handler(int signal) { - if (signal == SIGABRT) { - std::cerr << "SIGABRT received\\n"; - } - else { - std::cerr << "Unexpected signal " << signal << " received\\n"; - } - std::_Exit(EXIT_FAILURE); + + Tester static_tester; // Destructor not called + + void signal_handler(int signal) + { + if (signal == SIGABRT) + std::cerr << "SIGABRT received\\n"; + else + std::cerr << "Unexpected signal " << signal << " received\\n"; + std::_Exit(EXIT_FAILURE); } - - int main() { - // Destructor not called - Tester automatic_tester; - - // Setup handler - const auto previous_handler = std::signal(SIGABRT, signal_handler); - if (previous_handler == SIG_ERR) { - std::cerr << "Setup failed\\n"; - return EXIT_FAILURE; - } - - // Raise SIGABRT - assert(false); - - std::cout << "This code is unreachable\\n"; - return EXIT_SUCCESS; + + int main() + { + Tester automatic_tester; // Destructor not called + + // Setup handler + auto previous_handler = std::signal(SIGABRT, signal_handler); + if (previous_handler == SIG_ERR) + { + std::cerr << "Setup failed\\n"; + return EXIT_FAILURE; + } + + std::abort(); // Raise SIGABRT + std::cout << "This code is unreachable\\n"; } .SH Output: Tester ctor Tester ctor - Assertion failed: (false), function main, file ..., line 41. SIGABRT received .SH See also - exit causes normal program termination with cleaning up - \fI(function)\fP - atexit registers a function to be called on std::exit() invocation - \fI(function)\fP - quick_exit causes normal program termination without completely cleaning up - \fI(C++11)\fP \fI(function)\fP - signal sets a signal handler for particular signal - \fI(function)\fP + exit causes normal program termination with cleaning up + \fI(function)\fP + atexit registers a function to be called on std::exit() invocation + \fI(function)\fP + quick_exit causes quick program termination without completely cleaning up + \fI(C++11)\fP \fI(function)\fP + at_quick_exit registers a function to be called on std::quick_exit invocation + \fI(C++11)\fP \fI(function)\fP + signal sets a signal handler for particular signal + \fI(function)\fP + terminate function called when exception handling fails + \fI(function)\fP C documentation for abort diff --git a/man/std::abs(float),std::fabs,std::fabsf,std::fabsl.3 b/man/std::abs(float),std::fabs,std::fabsf,std::fabsl.3 new file mode 100644 index 000000000..5db46f6ec --- /dev/null +++ b/man/std::abs(float),std::fabs,std::fabsf,std::fabsl.3 @@ -0,0 +1,133 @@ +.TH std::abs(float),std::fabs,std::fabsf,std::fabsl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::abs(float),std::fabs,std::fabsf,std::fabsl \- std::abs(float),std::fabs,std::fabsf,std::fabsl + +.SH Synopsis + Defined in header + Defined in header + float abs( float num ); + + double abs( double num ); (until C++23) + + long double abs( long double num ); + constexpr /* floating-point-type */ + abs( /* floating-point-type */ (since C++23) + num ); + Defined in header + float fabs ( float num ); + + double fabs ( double num ); (until C++23) + + long double fabs ( long double num ); \fB(1)\fP + constexpr /* floating-point-type */ + fabs ( /* floating-point-type */ (since C++23) + num ); + \fI(since C++11)\fP + float fabsf( float num ); \fB(2)\fP \fB(3)\fP (constexpr since + C++23) + \fI(since C++11)\fP + long double fabsl( long double num ); \fB(4)\fP (constexpr since + C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > \fI(since C++11)\fP + double fabs ( Integer num ); (A) (constexpr since + C++23) + + 1-4) Computes the absolute value of the floating-point value num. + The library provides overloads of std::abs and std::fabs for all cv-unqualified + floating-point types as the type of the parameter num. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + + For integral arguments, the integral overloads of std::abs are likely better + matches. If std::abs is called with an unsigned integral argument that cannot be + converted to int by integral promotion, the program is ill-formed. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If successful, returns the absolute value of arg (|arg|). The value returned is + exact and does not depend on any rounding modes. + +.SH Error handling + + This function is not subject to any of the error conditions specified in + math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, +0 is returned. + * If the argument is ±∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::fabs(num) has the same effect as std::fabs(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "abs(+3.0) = " << std::abs(+3.0) << '\\n' + << "abs(-3.0) = " << std::abs(-3.0) << '\\n'; + + // special values + std::cout << "abs(-0.0) = " << std::abs(-0.0) << '\\n' + << "abs(-Inf) = " << std::abs(-INFINITY) << '\\n' + << "abs(-NaN) = " << std::abs(-NAN) << '\\n'; + } + +.SH Possible output: + + abs(+3.0) = 3 + abs(-3.0) = 3 + abs(-0.0) = 0 + abs(-Inf) = inf + abs(-NaN) = nan + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2192 C++98 overloads of std::abs were declared these overloads + inconsistently declared in two headers in both headers + overloads of std::abs for integer types + LWG 2735 C++11 returning double was erroneously removed the requirement + required + +.SH See also + + abs(int) + labs computes absolute value of an integral value (\\(\\small{|x|}\\)|x|) + llabs \fI(function)\fP + \fI(C++11)\fP + copysign + copysignf + copysignl copies the sign of a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + signbit checks if the given number is negative + \fI(C++11)\fP \fI(function)\fP + abs(std::complex) returns the magnitude of a complex number + \fI(function template)\fP + abs(std::valarray) applies the function abs to each element of valarray + \fI(function template)\fP + C documentation for + fabs diff --git a/man/std::abs(float),std::fabs.3 b/man/std::abs(float),std::fabs.3 deleted file mode 100644 index b5a0a68b1..000000000 --- a/man/std::abs(float),std::fabs.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH std::abs(float),std::fabs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float abs( float arg ); - double abs( double arg ); - long double abs( long double arg ); - float fabs( float arg ); - double fabs( double arg ); - long double fabs( long double arg ); - double fabs( Integral arg ); \fI(since C++11)\fP - - Computes the absolute value of a floating point value arg. - -.SH Parameters - - arg - Value of a floating-point or Integral type - -.SH Return value - - The absolute value of arg (|arg|). - -.SH See also - - abs(int) - labs computes absolute value of an integral value (|x|) - llabs \fI(function)\fP - imaxabs - \fI(C++11)\fP - signbit checks if the given number is negative - \fI(C++11)\fP \fI(function)\fP - abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP - abs(std::valarray) applies the function std::abs to each element of valarray - \fI(function template)\fP - C documentation for - fabs diff --git a/man/std::abs(int),std::labs,std::llabs,std::imaxabs.3 b/man/std::abs(int),std::labs,std::llabs,std::imaxabs.3 deleted file mode 100644 index a93634745..000000000 --- a/man/std::abs(int),std::labs,std::llabs,std::imaxabs.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::abs(int),std::labs,std::llabs,std::imaxabs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - int abs( int n ); - long abs( long n ); - long long abs( long long n ); \fI(since C++11)\fP - long labs( long n ); - long long llabs( long long n ); \fI(since C++11)\fP - Defined in header - std::intmax_t abs( std::intmax_t n ); \fI(since C++11)\fP - std::intmax_t imaxabs( std::intmax_t n ); \fI(since C++11)\fP - - Computes the absolute value of an integer number. - -.SH Parameters - - n - integer value - -.SH Return value - - The absolute value of n (i.e. |n|). - -.SH See also - - abs(float) absolute value of a floating point value (|x|) - fabs \fI(function)\fP - abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP - abs(std::valarray) applies the function std::abs to each element of valarray - \fI(function template)\fP - C documentation for - abs, - labs, - llabs diff --git a/man/std::abs(std::complex).3 b/man/std::abs(std::complex).3 index daf8c5db9..50a27c193 100644 --- a/man/std::abs(std::complex).3 +++ b/man/std::abs(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::abs(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::abs(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::abs(std::complex) \- std::abs(std::complex) + .SH Synopsis Defined in header template< class T > @@ -12,9 +15,63 @@ .SH Return value - the magnitude of z + If no errors occur, returns the absolute value (also known as norm, modulus, or + magnitude) of z. + + Errors and special cases are handled as if the function is implemented as + std::hypot(std::real(z), std::imag(z)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::complex z(1, 1); + std::cout << z << " cartesian is rho = " << std::abs(z) + << " theta = " << std::arg(z) << " polar\\n"; + } + +.SH Output: + + (1,1) cartesian is rho = 1.41421 theta = 0.785398 polar .SH See also - arg returns the phase angle - \fI(function template)\fP + arg returns the phase angle + \fI(function template)\fP + polar constructs a complex number from magnitude and phase angle + \fI(function template)\fP + abs(int) + labs computes absolute value of an integral value (\\(\\small{|x|}\\)|x|) + llabs \fI(function)\fP + \fI(C++11)\fP + abs(float) + fabs + fabsf absolute value of a floating point value (\\(\\small{|x|}\\)|x|) + fabsl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes square root of the sum of the squares of two + or three + \fI(since C++17)\fP given numbers (\\(\\scriptsize{\\sqrt{x^2+y^2}}\\) + √ + hypot x2 + hypotf +y2 + hypotl ) + \fI(C++11)\fP , (\\(\\scriptsize{\\sqrt{x^2+y^2+z^2}}\\) + \fI(C++11)\fP √ + \fI(C++11)\fP x2 + +y2 + +z2 + ) + \fI(since C++17)\fP + \fI(function)\fP + abs(std::valarray) applies the function abs to each element of valarray + \fI(function template)\fP + C documentation for + cabs diff --git a/man/std::abs(std::valarray).3 b/man/std::abs(std::valarray).3 index 0368bd2aa..aaa3a1d33 100644 --- a/man/std::abs(std::valarray).3 +++ b/man/std::abs(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::abs(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::abs(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::abs(std::valarray) \- std::abs(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (abs) is used to perform the computation. If such function is - not available, std::abs is used due to argument dependent lookup. + not available, std::abs is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,40 +28,41 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Possible implementation - template< class T > - valarray abs( const valarray& va ) + template + valarray abs(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = abs(i); - } + return other; // proxy object may be returned } .SH Example - + // Run this code - #include #include - + #include + int main() { std::valarray v{1, -2, 3, -4, 5, -6, 7, -8}; std::valarray v2 = std::abs(v); - for(auto n : v2) { + for (auto n : v2) std::cout << n << ' '; - } std::cout << '\\n'; } @@ -68,9 +72,18 @@ .SH See also - abs(int) computes absolute value of an integral value (|x|) - \fI(function)\fP - abs(float) absolute value of a floating point value (|x|) - \fI(function)\fP + abs(int) + labs computes absolute value of an integral value (\\(\\small{|x|}\\)|x|) + llabs \fI(function)\fP + \fI(C++11)\fP + abs(float) + fabs + fabsf absolute value of a floating point value (\\(\\small{|x|}\\)|x|) + fabsl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::abs,std::labs,std::llabs,std::imaxabs.3 b/man/std::abs,std::labs,std::llabs,std::imaxabs.3 new file mode 100644 index 000000000..38967ff92 --- /dev/null +++ b/man/std::abs,std::labs,std::llabs,std::imaxabs.3 @@ -0,0 +1,92 @@ +.TH std::abs,std::labs,std::llabs,std::imaxabs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::abs,std::labs,std::llabs,std::imaxabs \- std::abs,std::labs,std::llabs,std::imaxabs + +.SH Synopsis + Defined in header + Defined in header + int abs( int num ); \fB(1)\fP (constexpr since C++23) + long abs( long num ); \fB(2)\fP (constexpr since C++23) + long long abs( long long num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Defined in header + long labs( long num ); \fB(4)\fP (constexpr since C++23) + long long llabs( long long num ); \fB(5)\fP \fI(since C++11)\fP + (constexpr since C++23) + Defined in header + std::intmax_t abs( std::intmax_t num ); \fB(6)\fP \fI(since C++11)\fP + (constexpr since C++23) + std::intmax_t imaxabs( std::intmax_t num ); \fB(7)\fP \fI(since C++11)\fP + (constexpr since C++23) + + Computes the absolute value of the integer number num. The behavior is undefined if + the result cannot be represented by the return type. + + If std::abs is called with an unsigned integral argument that cannot be converted to + int by integral promotion, the program is ill-formed. + + Overload \fB(6)\fP of std::abs for std::intmax_t is provided in \fI(since C++11)\fP + if and only if std::intmax_t is an extended integer type. + +.SH Parameters + + num - integer value + +.SH Return value + + The absolute value of num (i.e. |num|), if it is representable. + +.SH Notes + + In 2's complement systems, the absolute value of the most-negative value is out of + range, e.g. for 32-bit 2's complement type int, INT_MIN is -2147483648, but the + would-be result 2147483648 is greater than INT_MAX, which is 2147483647. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::showpos + << "abs(+3) = " << std::abs(3) << '\\n' + << "abs(-3) = " << std::abs(-3) << '\\n'; + + // std::cout << std::abs(INT_MIN); // undefined behavior on 2's complement systems + } + +.SH Output: + + abs(+3) = +3 + abs(-3) = +3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2192 C++98 overloads of std::abs were declared these overloads + inconsistently declared in two headers in both headers + +.SH See also + + abs(float) + fabs + fabsf absolute value of a floating point value (\\(\\small{|x|}\\)|x|) + fabsl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + abs(std::complex) returns the magnitude of a complex number + \fI(function template)\fP + abs(std::valarray) applies the function abs to each element of valarray + \fI(function template)\fP + C documentation for + abs, + labs, + llabs diff --git a/man/std::accumulate.3 b/man/std::accumulate.3 index 703d8af72..55404b89b 100644 --- a/man/std::accumulate.3 +++ b/man/std::accumulate.3 @@ -1,21 +1,37 @@ -.TH std::accumulate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::accumulate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::accumulate \- std::accumulate + .SH Synopsis Defined in header - template< class InputIt, class T > \fB(1)\fP + template< class InputIt, class T > \fB(1)\fP (constexpr since C++20) T accumulate( InputIt first, InputIt last, T init ); - template< class InputIt, class T, class BinaryOperation > - - T accumulate( InputIt first, InputIt last, T init, \fB(2)\fP - - BinaryOperation op ); - - Computes the sum of the given value init and the elements in the range [first, - last). The first version uses operator+ to sum up the elements, the second version - uses the given binary function op. - - op must not have side effects. \fI(until C++11)\fP - op must not invalidate any iterators, including the end iterators, or \fI(since C++11)\fP - modify any elements of the range involved. + template< class InputIt, class T, class BinaryOp > + T accumulate( InputIt first, InputIt last, T init, \fB(2)\fP (constexpr since C++20) + BinaryOp op ); + + Computes the sum of the given value init and the elements in the range + [first, last). + + 1) Initializes the accumulator acc (of type T) with the initial value init and then + modifies it with + acc = acc + *i + \fI(until C++20)\fP + acc = std::move(acc) + *i + \fI(since C++20)\fP for every iterator i in the range [first, last) in order. + 2) Initializes the accumulator acc (of type T) with the initial value init and then + modifies it with + acc = op(acc, *i) + \fI(until C++20)\fP + acc = op(std::move(acc), *i) + \fI(since C++20)\fP for every iterator i in the range [first, last) in order. + + If any of the following conditions is satisfied, the behavior is undefined: + + * T is not CopyConstructible. + * T is not CopyAssignable. + * op modifies any element of [first, last). + * op invalidates any iterator or subrange in [first, last]. .SH Parameters @@ -28,88 +44,118 @@ Ret fun(const Type1 &a, const Type2 &b); op - The signature does not need to have const &. - The type Type1 must be such that an object of type T can be implicitly - converted to Type1. The type Type2 must be such that an object of type - InputIt can be dereferenced and then implicitly converted to Type2. - The type Ret must be such that an object of type T can be assigned a - value of type Ret. + The type Type1 must be such that an object of type T can be + implicitly converted to Type1. The type Type2 must be such that an + object of type InputIt can be dereferenced and then implicitly + converted to Type2. The type Ret must be such that an object of type + T can be assigned a value of type Ret. .SH Type requirements - - InputIt must meet the requirements of InputIterator. - - - T must meet the requirements of CopyAssignable and CopyConstructible. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - The sum of the given value and elements in the given range. + acc after all modifications. .SH Possible implementation -.SH First version + accumulate \fB(1)\fP template + constexpr // since C++20 T accumulate(InputIt first, InputIt last, T init) { - for (; first != last; ++first) { - init = init + *first; - } + for (; first != last; ++first) + init = std::move(init) + *first; // std::move since C++20 + return init; } -.SH Second version + accumulate \fB(2)\fP template - T accumulate(InputIt first, InputIt last, T init, - BinaryOperation op) + constexpr // since C++20 + T accumulate(InputIt first, InputIt last, T init, BinaryOperation op) { - for (; first != last; ++first) { - init = op(init, *first); - } + for (; first != last; ++first) + init = op(std::move(init), *first); // std::move since C++20 + return init; } +.SH Notes + + std::accumulate performs a left fold. In order to perform a right fold, one must + reverse the order of the arguments to the binary operator, and use reverse + iterators. + + If left to type inference, op operates on values of the same type as init which can + result in unwanted casting of the iterator elements. For example, + std::accumulate(v.begin(), v.end(), 0) likely does not give the result one wishes + for when v is of type std::vector. + .SH Example - + // Run this code + #include #include - #include #include #include - - int multiply(int x, int y) - { - return x*y; - } - - std::string magic_function(std::string res, int x) - { - return res += (x > 5) ? "b" : "s"; - } - + #include + int main() { std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; - + int sum = std::accumulate(v.begin(), v.end(), 0); - int product = std::accumulate(v.begin(), v.end(), 1, multiply); - std::string magic = std::accumulate(v.begin(), v.end(), std::string(), - magic_function); - - std::cout << sum << '\\n' - << product << '\\n' - << magic << '\\n'; + int product = std::accumulate(v.begin(), v.end(), 1, std::multiplies()); + + auto dash_fold = [](std::string a, int b) + { + return std::move(a) + '-' + std::to_string(b); + }; + + std::string s = std::accumulate(std::next(v.begin()), v.end(), + std::to_string(v[0]), // start with first element + dash_fold); + + // Right fold using reverse iterators + std::string rs = std::accumulate(std::next(v.rbegin()), v.rend(), + std::to_string(v.back()), // start with last element + dash_fold); + + std::cout << "sum: " << sum << '\\n' + << "product: " << product << '\\n' + << "dash-separated string: " << s << '\\n' + << "dash-separated string (right-folded): " << rs << '\\n'; } .SH Output: - 55 - 3628800 - sssssbbbbb + sum: 55 + product: 3628800 + dash-separated string: 1-2-3-4-5-6-7-8-9-10 + dash-separated string (right-folded): 10-9-8-7-6-5-4-3-2-1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 242 C++98 op could not have side effects it cannot modify the ranges + involved + LWG 2055 C++20 acc was not moved while being it is moved + (P0616R0) accumulated .SH See also adjacent_difference computes the differences between adjacent elements in a range - \fI(function template)\fP + \fI(function template)\fP inner_product computes the inner product of two ranges of elements - \fI(function template)\fP + \fI(function template)\fP partial_sum computes the partial sum of a range of elements - \fI(function template)\fP + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) diff --git a/man/std::acos(std::complex).3 b/man/std::acos(std::complex).3 index 38e6fbc15..0e61b6804 100644 --- a/man/std::acos(std::complex).3 +++ b/man/std::acos(std::complex).3 @@ -1,11 +1,14 @@ -.TH std::acos(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::acos(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::acos(std::complex) \- std::acos(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP complex acos( const complex& z ); - Computes complex arc cosine of a complex value z. Branch cut exists outside the - interval [−1 ; +1] along the real axis. + Computes complex arc cosine of a complex value z. Branch cuts exist outside the + interval [−1, +1] along the real axis. .SH Parameters @@ -13,12 +16,97 @@ .SH Return value - Complex arc cosine of z in the range [0 ; ∞) along the real axis and in the range - [−iπ ; iπ] along the imaginary axis. + If no errors occur, complex arc cosine of z is returned, in the range of a strip + unbounded along the imaginary axis and in the interval [0, +π] along the real axis. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::acos(std::conj(z)) == std::conj(std::acos(z)) + * If z is (±0,+0), the result is (π/2,-0) + * If z is (±0,NaN), the result is (π/2,NaN) + * If z is (x,+∞) (for any finite x), the result is (π/2,-∞) + * If z is (x,NaN) (for any nonzero finite x), the result is (NaN,NaN) and + FE_INVALID may be raised. + * If z is (-∞,y) (for any positive finite y), the result is (π,-∞) + * If z is (+∞,y) (for any positive finite y), the result is (+0,-∞) + * If z is (-∞,+∞), the result is (3π/4,-∞) + * If z is (+∞,+∞), the result is (π/4,-∞) + * If z is (±∞,NaN), the result is (NaN,±∞) (the sign of the imaginary part is + unspecified) + * If z is (NaN,y) (for any finite y), the result is (NaN,NaN) and FE_INVALID may + be raised + * If z is (NaN,+∞), the result is (NaN,-∞) + * If z is (NaN,NaN), the result is (NaN,NaN) + +.SH Notes + + Inverse cosine (or arc cosine) is a multivalued function and requires a branch cut + on the complex plane. The branch cut is conventionally placed at the line segments + (-∞,-1) and (1,∞) of the real axis. + + The mathematical definition of the principal value of arc cosine is acos z = + + 1 + 2 + + π + iln(iz + + √ + 1-z2 + ). + + For any z, acos(z) = π - acos(-z). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z1(-2.0, 0.0); + std::cout << "acos" << z1 << " = " << std::acos(z1) << '\\n'; + + std::complex z2(-2.0, -0.0); + std::cout << "acos" << z2 << " (the other side of the cut) = " + << std::acos(z2) << '\\n'; + + // for any z, acos(z) = pi - acos(-z) + const double pi = std::acos(-1); + std::complex z3 = pi - std::acos(z2); + std::cout << "cos(pi - acos" << z2 << ") = " << std::cos(z3) << '\\n'; + } + +.SH Output: + + acos(-2.000000,0.000000) = (3.141593,-1.316958) + acos(-2.000000,-0.000000) (the other side of the cut) = (3.141593,1.316958) + cos(pi - acos(-2.000000,-0.000000)) = (2.000000,0.000000) .SH See also - asin(std::complex) computes arc sine of a complex number (arcsin(z)) - \fI(C++11)\fP \fI(function template)\fP - atan(std::complex) computes arc tangent of a complex number (arctan(z)) - \fI(C++11)\fP \fI(function template)\fP + asin(std::complex) computes arc sine of a complex number + \fI(C++11)\fP (\\({\\small\\arcsin{z}}\\)arcsin(z)) + \fI(function template)\fP + atan(std::complex) computes arc tangent of a complex number + \fI(C++11)\fP (\\({\\small\\arctan{z}}\\)arctan(z)) + \fI(function template)\fP + cos(std::complex) computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z)) + \fI(function template)\fP + acos + acosf computes arc cosine (\\({\\small\\arccos{x}}\\)arccos(x)) + acosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acos(std::valarray) applies the function std::acos to each element of valarray + \fI(function template)\fP + C documentation for + cacos diff --git a/man/std::acos(std::valarray).3 b/man/std::acos(std::valarray).3 index 3f2512dba..4f5037a7a 100644 --- a/man/std::acos(std::valarray).3 +++ b/man/std::acos(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::acos(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::acos(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::acos(std::valarray) \- std::acos(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (acos) is used to perform the computation. If such function is - not available, std::acos is used due to argument dependent lookup. + not available, std::acos is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,16 +43,57 @@ valarray acos(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = acos(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + #include + + int main() + { + // take common x-values from unit circle + const double s32 = std::sqrt(3.0) / 2.0; + const double s22 = std::sqrt(2.0) / 2.0; + std::valarray v1 = {-1.0, -s32, -s22, -0.5, 0.0, 0.5, s22, s32, 1.0}; + std::valarray v2 = std::acos(v1) * 180.0 / std::numbers::pi; + + for (double n : v2) + std::cout << n << "° "; + std::cout << '\\n'; + } + +.SH Output: + + 180° 150° 135° 120° 90° 60° 45° 30° 0° + +.SH See also + + asin(std::valarray) applies the function std::asin to each element of valarray + \fI(function template)\fP + atan(std::valarray) applies the function std::atan to each element of valarray + \fI(function template)\fP + atan2(std::valarray) applies the function std::atan2 to a valarray and a value + \fI(function template)\fP + cos(std::valarray) applies the function std::cos to each element of valarray + \fI(function template)\fP + acos + acosf computes arc cosine (\\({\\small\\arccos{x}}\\)arccos(x)) + acosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::acos,std::acosf,std::acosl.3 b/man/std::acos,std::acosf,std::acosl.3 new file mode 100644 index 000000000..bdefc391b --- /dev/null +++ b/man/std::acos,std::acosf,std::acosl.3 @@ -0,0 +1,138 @@ +.TH std::acos,std::acosf,std::acosl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::acos,std::acosf,std::acosl \- std::acos,std::acosf,std::acosl + +.SH Synopsis + Defined in header + float acos ( float num ); + + double acos ( double num ); (until C++23) + + long double acos ( long double num ); + /* floating-point-type */ (since C++23) + acos ( /* floating-point-type */ num ); (constexpr since C++26) + float acosf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double acosl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double acos ( Integer num ); + + 1-3) Computes the principal value of the arc cosine of num. + The library provides overloads of std::acos for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the arc cosine of num (arccos(num)) in the range [0, π], is + returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is outside the range [-1.0, 1.0]. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is +1, the value +0 is returned. + * If |num| > 1, a domain error occurs and NaN is returned. + * if the argument is NaN, NaN is returned. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::acos(num) has the same effect as std::acos(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "acos(-1) = " << std::acos(-1) << '\\n' + << "acos(0.0) = " << std::acos(0.0) << '\\n' + << "2*acos(0.0) = " << 2 * std::acos(0) << '\\n' + << "acos(0.5) = " << std::acos(0.5) << '\\n' + << "3*acos(0.5) = " << 3 * std::acos(0.5) << '\\n' + << "acos(1) = " << std::acos(1) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "acos(1.1) = " << std::acos(1.1) << '\\n'; + + if (errno == EDOM) + std::cout << " errno == EDOM: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised" << '\\n'; + } + +.SH Output: + + acos(-1) = 3.14159 + acos(0.0) = 1.5708 + 2*acos(0.0) = 3.14159 + acos(0.5) = 1.0472 + 3*acos(0.5) = 3.14159 + acos\fB(1)\fP = 0 + acos(1.1) = nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised + +.SH See also + + asin + asinf computes arc sine (\\({\\small\\arcsin{x}}\\)arcsin(x)) + asinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan + atanf computes arc tangent (\\({\\small\\arctan{x}}\\)arctan(x)) + atanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan2 + atan2f arc tangent, using signs to determine quadrants + atan2l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cos + cosf computes cosine (\\({\\small\\cos{x}}\\)cos(x)) + cosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP + acos(std::valarray) applies the function std::acos to each element of valarray + \fI(function template)\fP + C documentation for + acos diff --git a/man/std::acos.3 b/man/std::acos.3 deleted file mode 100644 index 1a465e993..000000000 --- a/man/std::acos.3 +++ /dev/null @@ -1,56 +0,0 @@ -.TH std::acos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float acos( float arg ); - double acos( double arg ); - long double acos( long double arg ); - double acos( Integral arg ); \fI(since C++11)\fP - - Computes arc cosine of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Arc cosine of arg in radians in the range of [0; π] radians. - - Domain error occurs if arg is outside the range [-1.0; 1.0]. NaN is returned in that - case and FE_INVALID is raised. - - std::acos\fB(1)\fP returns +0. - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::cout << "The number pi is " << std::acos(-1) << '\\n'; - } - -.SH Output: - - The number pi is 3.14159 - -.SH See also - - asin computes arc sine (arcsin(x)) - \fI(function)\fP - atan computes arc tangent (arctan(x)) - \fI(function)\fP - atan2 arc tangent, using signs to determine quadrants - \fI(function)\fP - cos computes cosine (cos(x)) - \fI(function)\fP - acos(std::complex) computes arc cosine of a complex number (arccos(z)) - \fI(C++11)\fP \fI(function template)\fP - acos(std::valarray) applies the function std::acos to each element of valarray - \fI(function template)\fP - C documentation for - acos diff --git a/man/std::acosh(std::complex).3 b/man/std::acosh(std::complex).3 index a11e7b055..149412182 100644 --- a/man/std::acosh(std::complex).3 +++ b/man/std::acosh(std::complex).3 @@ -1,10 +1,14 @@ -.TH std::acosh(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::acosh(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::acosh(std::complex) \- std::acosh(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP complex acosh( const complex& z ); - Computes complex area hyperbolic cosine of a complex value z. + Computes complex arc hyperbolic cosine of a complex value z with branch cut at + values less than 1 along the real axis. .SH Parameters @@ -12,13 +16,109 @@ .SH Return value - Complex area hyperbolic cosine of z + If no errors occur, the complex arc hyperbolic cosine of z is returned, in the range + of a half-strip of nonnegative values along the real axis and in the interval [−iπ; + +iπ] along the imaginary axis. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::acosh(std::conj(z)) == std::conj(std::acosh(z)). + * If z is (±0,+0), the result is (+0,π/2). + * If z is (x,+∞) (for any finite x), the result is (+∞,π/2). + * If z is (x,NaN) (for any^[1] finite x), the result is (NaN,NaN) and FE_INVALID + may be raised. + * If z is (-∞,y) (for any positive finite y), the result is (+∞,π). + * If z is (+∞,y) (for any positive finite y), the result is (+∞,+0). + * If z is (-∞,+∞), the result is (+∞,3π/4). + * If z is (±∞,NaN), the result is (+∞,NaN). + * If z is (NaN,y) (for any finite y), the result is (NaN,NaN) and FE_INVALID may + be raised. + * If z is (NaN,+∞), the result is (+∞,NaN). + * If z is (NaN,NaN), the result is (NaN,NaN). + 1. ↑ per C11 DR471, this holds for non-zero x only. If z is (0,NaN), the result + should be (NaN,π/2). + +.SH Notes + + Although the C++ standard names this function "complex arc hyperbolic cosine", the + inverse functions of the hyperbolic functions are the area functions. Their argument + is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse + hyperbolic cosine", and, less common, "complex area hyperbolic cosine". + + Inverse hyperbolic cosine is a multivalued function and requires a branch cut on the + complex plane. The branch cut is conventionally placed at the line segment (-∞,+1) + of the real axis. + + The mathematical definition of the principal value of the inverse hyperbolic cosine + is acosh z = ln(z + + √ + z+1 + √ + z-1). + + For any z, acosh(z) = + + √ + z-1 + √ + 1-z + + acos(z), or simply i acos(z) in the upper half of the complex plane. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z1(0.5, 0); + std::cout << "acosh" << z1 << " = " << std::acosh(z1) << '\\n'; + + std::complex z2(0.5, -0.0); + std::cout << "acosh" << z2 << " (the other side of the cut) = " + << std::acosh(z2) << '\\n'; + + // in upper half-plane, acosh = i acos + std::complex z3(1, 1), i(0, 1); + std::cout << "acosh" << z3 << " = " << std::acosh(z3) << '\\n' + << "i*acos" << z3 << " = " << i*std::acos(z3) << '\\n'; + } + +.SH Output: + + acosh(0.500000,0.000000) = (0.000000,-1.047198) + acosh(0.500000,-0.000000) (the other side of the cut) = (0.000000,1.047198) + acosh(1.000000,1.000000) = (1.061275,0.904557) + i*acos(1.000000,1.000000) = (1.061275,0.904557) .SH See also - cos(std::complex) computes cosine of a complex number (cos(z)) - \fI(function template)\fP - cosh(std::complex) computes hyperbolic cosine of a complex number (ch(z)) - \fI(function template)\fP - acos(std::complex) computes arc cosine of a complex number (arccos(z)) - \fI(C++11)\fP \fI(function template)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP + asinh(std::complex) computes area hyperbolic sine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arsinh}{z}}\\)arsinh(z)) + \fI(function template)\fP + atanh(std::complex) computes area hyperbolic tangent of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{artanh}{z}}\\)artanh(z)) + \fI(function template)\fP + computes hyperbolic cosine of a complex number + cosh(std::complex) (\\({\\small\\cosh{z}}\\)cosh(z)) + \fI(function template)\fP + acosh + acoshf computes the inverse hyperbolic cosine + acoshl (\\({\\small\\operatorname{arcosh}{x}}\\)arcosh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + cacosh diff --git a/man/std::acosh,std::acoshf,std::acoshl.3 b/man/std::acosh,std::acoshf,std::acoshl.3 new file mode 100644 index 000000000..35a45c6cb --- /dev/null +++ b/man/std::acosh,std::acoshf,std::acoshl.3 @@ -0,0 +1,139 @@ +.TH std::acosh,std::acoshf,std::acoshl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::acosh,std::acoshf,std::acoshl \- std::acosh,std::acoshf,std::acoshl + +.SH Synopsis + Defined in header + float acosh ( float num ); + + double acosh ( double num ); (until C++23) + + long double acosh ( long double num ); + /* floating-point-type */ (since C++23) + acosh ( /* floating-point-type */ num ); (constexpr since C++26) + float acoshf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double acoshl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double acosh ( Integer num ); + + 1-3) Computes the inverse hyperbolic cosine of num. + The library provides overloads of std::acosh for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the inverse hyperbolic cosine of num (cosh-1 + (num), or arcosh(num)) on the interval [0, +∞], is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the argument is less than 1, a domain error occurs. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is less than 1, FE_INVALID is raised an NaN is returned. + * if the argument is 1, +0 is returned. + * if the argument is +∞, +∞ is returned. + * if the argument is NaN, NaN is returned. + +.SH Notes + + Although the C standard (to which C++ refers for this function) names this function + "arc hyperbolic cosine", the inverse functions of the hyperbolic functions are the + area functions. Their argument is the area of a hyperbolic sector, not an arc. The + correct name is "inverse hyperbolic cosine" (used by POSIX) or "area hyperbolic + cosine". + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::acosh(num) has the same effect as std::acosh(static_cast(num)). + +.SH Examples + + +// Run this code + + #include + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "acosh(1) = " << std::acosh(1) << '\\n' + << "acosh(10) = " << std::acosh(10) << '\\n' + << "acosh(DBL_MAX) = " << std::acosh(DBL_MAX) << '\\n' + << "acosh(Inf) = " << std::acosh(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "acosh(0.5) = " << std::acosh(0.5) << '\\n'; + + if (errno == EDOM) + std::cout << " errno == EDOM: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + acosh\fB(1)\fP = 0 + acosh\fB(10)\fP = 2.99322 + acosh(DBL_MAX) = 710.476 + acosh(Inf) = inf + acosh(0.5) = -nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised + +.SH See also + + asinh + asinhf computes the inverse hyperbolic sine + asinhl (\\({\\small\\operatorname{arsinh}{x}}\\)arsinh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atanh + atanhf computes the inverse hyperbolic tangent + atanhl (\\({\\small\\operatorname{artanh}{x}}\\)artanh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cosh + coshf computes hyperbolic cosine (\\({\\small\\cosh{x}}\\)cosh(x)) + coshl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acosh(std::complex) computes area hyperbolic cosine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arcosh}{z}}\\)arcosh(z)) + \fI(function template)\fP + C documentation for + acosh + +.SH External links + + Weisstein, Eric W. "Inverse Hyperbolic Cosine." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::acosh.3 b/man/std::acosh.3 deleted file mode 100644 index 268b4b61e..000000000 --- a/man/std::acosh.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::acosh 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float acosh( float arg ); \fI(since C++11)\fP - double acosh( double arg ); \fI(since C++11)\fP - long double acosh( long double arg ); \fI(since C++11)\fP - double acosh( Integral arg ); \fI(since C++11)\fP - - Computes area hyperbolic cosine of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Inverse hyperbolic cosine of arg. - -.SH See also - - asinh area hyperbolic sine - \fI(C++11)\fP \fI(function)\fP - atanh area hyperbolic tangent - \fI(C++11)\fP \fI(function)\fP - cosh computes hyperbolic cosine (ch(x)) - \fI(function)\fP - acosh(std::complex) computes area hyperbolic cosine of a complex number - \fI(C++11)\fP \fI(function template)\fP - C documentation for - acosh - -.SH External links - - Weisstein, Eric W. "Inverse Hyperbolic Cosine." From MathWorld--A Wolfram Web - Resource. diff --git a/man/std::add_cv,std::add_const,std::add_volatile.3 b/man/std::add_cv,std::add_const,std::add_volatile.3 index 88e58a2b3..b1d15cd13 100644 --- a/man/std::add_cv,std::add_const,std::add_volatile.3 +++ b/man/std::add_cv,std::add_const,std::add_volatile.3 @@ -1,4 +1,7 @@ -.TH std::add_cv,std::add_const,std::add_volatile 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::add_cv,std::add_const,std::add_volatile 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::add_cv,std::add_const,std::add_volatile \- std::add_cv,std::add_const,std::add_volatile + .SH Synopsis Defined in header template< class T > \fB(1)\fP \fI(since C++11)\fP @@ -13,11 +16,12 @@ cv-qualifier) 1) adds both const and volatile - 2) adds const - 3) adds volatile + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + .SH Member types Name Definition @@ -34,55 +38,68 @@ .SH Possible implementation - template< class T > - struct add_cv { - typedef typename std::add_volatile::type>::type type; - }; - - template< class T> struct add_const { typedef const T type; }; - - template< class T> struct add_volatile { typedef volatile T type; }; + template struct add_cv { typedef const volatile T type; }; + + template struct add_const { typedef const T type; }; + + template struct add_volatile { typedef volatile T type; }; + +.SH Notes + + These transformation traits can be used to establish non-deduced contexts in + template argument deduction: + + template + void f(const T&, const T&); + + template + void g(const T&, std::add_const_t&); + + f(4.2, 0); // error, deduced conflicting types for 'T' + g(4.2, 0); // OK, calls g .SH Example - + // Run this code #include #include - + struct foo { void m() { std::cout << "Non-cv\\n"; } void m() const { std::cout << "Const\\n"; } + void m() volatile { std::cout << "Volatile\\n"; } + void m() const volatile { std::cout << "Const-volatile\\n"; } }; - - template - void call_m() - { - T().m(); - } - + int main() { - call_m(); - call_m::type>(); + foo{}.m(); + std::add_const::type{}.m(); + std::add_volatile::type{}.m(); + std::add_cv::type{}.m(); } .SH Output: Non-cv Const + Volatile + Const-volatile .SH See also is_const checks if a type is const-qualified - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_volatile checks if a type is volatile-qualified - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_cv remove_const - remove_volatile removes const or/and volatile specifiers from the given type - \fI(C++11)\fP \fI(class template)\fP + remove_volatile removes const and/or volatile specifiers from the given type + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP + as_const obtains a reference to const to its argument + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::add_lvalue_reference,std::add_rvalue_reference.3 b/man/std::add_lvalue_reference,std::add_rvalue_reference.3 index 2a6e0bac8..40443a031 100644 --- a/man/std::add_lvalue_reference,std::add_rvalue_reference.3 +++ b/man/std::add_lvalue_reference,std::add_rvalue_reference.3 @@ -1,4 +1,7 @@ -.TH std::add_lvalue_reference,std::add_rvalue_reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::add_lvalue_reference,std::add_rvalue_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::add_lvalue_reference,std::add_rvalue_reference \- std::add_lvalue_reference,std::add_rvalue_reference + .SH Synopsis Defined in header template< class T > \fB(1)\fP \fI(since C++11)\fP @@ -6,17 +9,20 @@ template< class T > \fB(2)\fP \fI(since C++11)\fP struct add_rvalue_reference; - Creates a lvalue or rvalue reference type of T. + Creates an lvalue or rvalue reference type of T. - 1) If T is an object or function, provides a member typedef type which is T&. If T - is an rvalue reference to some type U, then type is U&. Otherwise, type is T. - 2) If T is an object or function, provides a member typedef type which is T&&, - otherwise type is T. + Type trait The type referred by the nested type type + T is a referenceable type T is not a referenceable type + \fB(1)\fP T&^[1] T + \fB(2)\fP T&&^[2] -.SH Member types + 1. ↑ This rule reflects the semantics of reference collapsing. + 2. ↑ This rule reflects the semantics of reference collapsing. Note that + std::add_rvalue_reference::type is T&, which is not an rvalue reference + type. - Name Definition - type reference to T, or T if not allowed + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Helper types @@ -29,41 +35,71 @@ .SH Notes - These type transformations honor reference collapse rules: + The major difference to directly using T& or T&& is that T can be a + non-referenceable type. For example, std::add_lvalue_reference::type is void, + while void& leads to a compilation error. + +.SH Possible implementation + + namespace detail + { + template + struct type_identity { using type = T; }; // or use std::type_identity \fI(since C++20)\fP + + template // Note that “cv void&” is a substitution failure + auto try_add_lvalue_reference(int) -> type_identity; + template // Handle T = cv void case + auto try_add_lvalue_reference(...) -> type_identity; - std::add_lvalue_reference::type is T& - std::add_lvalue_reference::type is T& - std::add_rvalue_reference::type is T& - std::add_rvalue_reference::type is T&& + template + auto try_add_rvalue_reference(int) -> type_identity; + template + auto try_add_rvalue_reference(...) -> type_identity; + } // namespace detail + + template + struct add_lvalue_reference + : decltype(detail::try_add_lvalue_reference\fB(0)\fP) {}; + + template + struct add_rvalue_reference + : decltype(detail::try_add_rvalue_reference\fB(0)\fP) {}; .SH Example - + // Run this code - #include #include - - int main() { - using nonref = int; - using lref = typename std::add_lvalue_reference::type; - using rref = typename std::add_rvalue_reference::type; - - std::cout << std::boolalpha; - std::cout << std::is_lvalue_reference::value << '\\n'; - std::cout << std::is_lvalue_reference::value << '\\n'; - std::cout << std::is_rvalue_reference::value << '\\n'; - } - -.SH Output: - - false - true - true + + using non_ref = int; + static_assert(std::is_lvalue_reference_v == false); + + using l_ref = std::add_lvalue_reference_t; + static_assert(std::is_lvalue_reference_v == true); + + using r_ref = std::add_rvalue_reference_t; + static_assert(std::is_rvalue_reference_v == true); + + using void_ref = std::add_lvalue_reference_t; + static_assert(std::is_reference_v == false); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2101 C++11 the program was ill-formed if T is a the type produced is T in + function type with cv or ref this case .SH See also - is_reference checks if a type is either lvalue reference or rvalue reference - \fI(C++11)\fP \fI(class template)\fP - remove_reference removes reference from the given type - \fI(C++11)\fP \fI(class template)\fP + is_reference checks if a type is either an lvalue reference or rvalue reference + \fI(C++11)\fP \fI(class template)\fP + remove_reference removes a reference from the given type + \fI(C++11)\fP \fI(class template)\fP + remove_cvref combines std::remove_cv and std::remove_reference + (C++20) \fI(class template)\fP diff --git a/man/std::add_pointer.3 b/man/std::add_pointer.3 index 0ddc37f22..05de47c5b 100644 --- a/man/std::add_pointer.3 +++ b/man/std::add_pointer.3 @@ -1,16 +1,18 @@ -.TH std::add_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::add_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::add_pointer \- std::add_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct add_pointer; - Provides the member typedef type which is the type T*. If T is a reference type, - then type is a pointer to the referred type. + If T is a referenceable type or (possibly cv-qualified) void, the member typedef + type provided is typename std::remove_reference::type*. -.SH Member types + Otherwise, the member typedef type provided is T. - Name Definition - type pointer to T or to the type referenced by T + If the program adds specializations for std::add_pointer, the behavior is undefined. .SH Helper types @@ -19,23 +21,88 @@ .SH Possible implementation - template< class T > - struct add_pointer { - typedef typename std::remove_reference::type* type; - }; + namespace detail + { + template + struct type_identity { using type = T; }; // or use std::type_identity \fI(since C++20)\fP + + template + auto try_add_pointer(int) + -> type_identity::type*>; // usual case + + template + auto try_add_pointer(...) + -> type_identity; // unusual case (cannot form std::remove_reference::type*) + } // namespace detail + + template + struct add_pointer : decltype(detail::try_add_pointer\fB(0)\fP) {}; .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP - remove_pointer removes pointer from the given type - \fI(C++11)\fP \fI(class template)\fP + #include + #include + + template + void ptr_to_member_func_cvref_test(F Class::*) + { + // F is an “abominable function type” + using FF = std::add_pointer_t; + static_assert(std::is_same_v, "FF should be precisely F"); + } + + struct S + { + void f_ref() & {} + void f_const() const {} + }; + + int main() + { + int i = 123; + int& ri = i; + typedef std::add_pointer::type IntPtr; + typedef std::add_pointer::type IntPtr2; + IntPtr pi = &i; + std::cout << "i = " << i << '\\n'; + std::cout << "*pi = " << *pi << '\\n'; + + static_assert(std::is_pointer_v, "IntPtr should be a pointer"); + static_assert(std::is_same_v, "IntPtr should be a pointer to int"); + static_assert(std::is_same_v, "IntPtr2 should be equal to IntPtr"); -.SH Category: + typedef std::remove_pointer::type IntAgain; + IntAgain j = i; + std::cout << "j = " << j << '\\n'; - * Todo no example + static_assert(!std::is_pointer_v, "IntAgain should not be a pointer"); + static_assert(std::is_same_v, "IntAgain should be equal to int"); + + ptr_to_member_func_cvref_test(&S::f_ref); + ptr_to_member_func_cvref_test(&S::f_const); + } + +.SH Output: + + i = 123 + *pi = 123 + j = 123 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2101 C++11 the program was ill-formed if T is a the type produced is T in + function type with cv or ref this case + +.SH See also + + is_pointer checks if a type is a pointer type + \fI(C++11)\fP \fI(class template)\fP + remove_pointer removes a pointer from the given type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::add_sat.3 b/man/std::add_sat.3 new file mode 100644 index 000000000..4753865d2 --- /dev/null +++ b/man/std::add_sat.3 @@ -0,0 +1,117 @@ +.TH std::add_sat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::add_sat \- std::add_sat + +.SH Synopsis + Defined in header + template< class T > (since C++26) + constexpr T add_sat( T x, T y ) noexcept; + + Computes the saturating addition x + y. This operation (unlike built-in arithmetic + operations on integers) behaves as-if it is a mathematical operation with an + infinite range. Let q denote the result of such operation. Returns: + + * q, if q is representable as a value of type T. Otherwise, + * the largest or smallest value of type T, whichever is closer to the q. + + This overload participates in overload resolution only if T is an integer type, that + is: signed char, short, int, long, long long, an extended signed integer type, or an + unsigned version of such types. In particular, T must not be (possibly cv-qualified) + bool, char, wchar_t, char8_t, char16_t, and char32_t, as these types are not + intended for arithmetic. + +.SH Parameters + + x, y - integer values + +.SH Return value + + Saturated x + y. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Unlike the built-in arithmetic operators on integers, the integral promotion does + not apply to the x and y arguments. + + If two arguments of different type are passed, the call fails to compile, i.e. the + behavior relative to template argument deduction is the same as for std::min or + std::max. + + Most modern hardware architectures have efficient support for saturation arithmetic + on SIMD vectors, including SSE2 for x86 and NEON for ARM. + + Feature-test macro Value Std Feature + __cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic + +.SH Possible implementation + + See libstdc++ (gcc). + +.SH Example + + Can be previewed on Compiler Explorer. + + +// Run this code + + #include + #include + #include + + static_assert(CHAR_BIT == 8); + static_assert(UCHAR_MAX == 255); + + int main() + { + constexpr int a = std::add_sat(3, 4); // no saturation occurs, T = int + static_assert(a == 7); + + constexpr unsigned char b = std::add_sat(UCHAR_MAX, 4); // saturated + static_assert(b == UCHAR_MAX); + + constexpr unsigned char c = std::add_sat(UCHAR_MAX, 4); // not saturated, T = int + // add_sat(int, int) returns int tmp == 259, + // then assignment truncates 259 % 256 == 3 + static_assert(c == 3); + + // unsigned char d = std::add_sat(252, c); // Error: inconsistent deductions for T + + constexpr unsigned char e = std::add_sat(251, a); // saturated + static_assert(e == UCHAR_MAX); + // 251 is of type T = unsigned char, `a` is converted to unsigned char value; + // might yield an int -> unsigned char conversion warning for `a` + + constexpr signed char f = std::add_sat(-123, -3); // not saturated + static_assert(f == -126); + + constexpr signed char g = std::add_sat(-123, -13); // saturated + static_assert(g == std::numeric_limits::min()); // g == -128 + } + +.SH See also + + sub_sat saturating subtraction operation on two integers + (C++26) \fI(function template)\fP + mul_sat saturating multiplication operation on two integers + (C++26) \fI(function template)\fP + div_sat saturating division operation on two integers + (C++26) \fI(function template)\fP + saturate_cast returns an integer value clamped to the range of a another integer + (C++26) type + \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP + min returns the smallest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + max returns the largest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + +.SH External links + + 1. A branch-free implementation of saturation arithmetic — Locklessinc.com, 2012 diff --git a/man/std::addressof.3 b/man/std::addressof.3 index df700b685..bc24ca9bd 100644 --- a/man/std::addressof.3 +++ b/man/std::addressof.3 @@ -1,11 +1,20 @@ -.TH std::addressof 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::addressof 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::addressof \- std::addressof + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - T* addressof(T& arg); + template< class T > \fB(1)\fP \fI(since C++11)\fP + T* addressof( T& arg ) noexcept; (constexpr since C++17) + template< class T > \fB(2)\fP \fI(since C++11)\fP + const T* addressof( const T&& ) = delete; + + 1) Obtains the actual address of the object or function arg, even in presence of + overloaded operator&. + 2) Rvalue overload is deleted to prevent taking the address of const rvalues. - Obtains the actual address of the object or function arg, even in presence of - overloaded operator& + The expression std::addressof(e) is a constant subexpression, if e is \fI(since C++17)\fP + an lvalue constant subexpression. .SH Parameters @@ -15,64 +24,77 @@ Pointer to arg. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Possible implementation - template< class T > - T* addressof(T& arg) + The implementation below is not constexpr, because reinterpret_cast is not usable in + a constant expression. Compiler support is needed (see below). + + template + typename std::enable_if::value, T*>::type addressof(T& arg) noexcept { return reinterpret_cast( &const_cast( - reinterpret_cast(arg))); + reinterpret_cast(arg))); } - Note: the above implementation is oversimplified + template + typename std::enable_if::value, T*>::type addressof(T& arg) noexcept + { + return &arg; + } + + Correct implementation of this function requires compiler support: GNU libstdc++, + LLVM libc++, Microsoft STL. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_addressof_constexpr 201603L \fI(C++17)\fP constexpr std::addressof + + constexpr for addressof is added by LWG2296, and MSVC STL applies the change to + C++14 mode as a defect report. .SH Example operator& may be overloaded for a pointer wrapper class to obtain a pointer to pointer: - + // Run this code #include #include - + template - struct Ptr { + struct Ptr + { T* pad; // add pad to show difference between 'this' and 'data' T* data; Ptr(T* arg) : pad(nullptr), data(arg) { - std::cout << "Ctor this = " << this << std::endl; + std::cout << "Ctor this = " << this << '\\n'; } - + ~Ptr() { delete data; } T** operator&() { return &data; } }; - + template void f(Ptr* p) { std::cout << "Ptr overload called with p = " << p << '\\n'; } - + void f(int** p) { std::cout << "int** overload called with p = " << p << '\\n'; } - + int main() { Ptr p(new int(42)); - f(&p); // calls int** overload - f(std::addressof(p)); // calls Ptr* overload, (= this) + f(&p); // calls int** overload + f(std::addressof(p)); // calls Ptr* overload, (= this) } .SH Possible output: @@ -81,9 +103,18 @@ int** overload called with p = 0x7fff59ae6e90 Ptr overload called with p = 0x7fff59ae6e88 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2598 C++11 std::addressof could take disallowed by a deleted + address of rvalues overload + .SH See also - allocator the default allocator - \fI(class template)\fP - pointer_traits provides information about pointer-like types - \fI(C++11)\fP \fI(class template)\fP + allocator the default allocator + \fI(class template)\fP + pointer_to obtains a dereferenceable pointer to its argument + \fB[static]\fP \fI(public static member function of std::pointer_traits)\fP diff --git a/man/std::adjacent_difference.3 b/man/std::adjacent_difference.3 index 973fa20df..0b12491d4 100644 --- a/man/std::adjacent_difference.3 +++ b/man/std::adjacent_difference.3 @@ -1,40 +1,111 @@ -.TH std::adjacent_difference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::adjacent_difference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::adjacent_difference \- std::adjacent_difference + .SH Synopsis Defined in header template< class InputIt, class OutputIt > - OutputIt adjacent_difference( InputIt first, InputIt last, \fB(1)\fP + OutputIt adjacent_difference( InputIt first, InputIt \fB(1)\fP (constexpr since C++20) + last, + + OutputIt d_first ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + ForwardIt2 adjacent_difference( ExecutionPolicy&& + policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, + ForwardIt1 last, + + ForwardIt2 d_first ); + template< class InputIt, class OutputIt, class BinaryOp + > + + OutputIt adjacent_difference( InputIt first, InputIt \fB(3)\fP (constexpr since C++20) + last, + + OutputIt d_first, BinaryOp + op ); + template< class ExecutionPolicy, - OutputIt d_first ); - template< class InputIt, class OutputIt, class BinaryOperation > + class ForwardIt1, class ForwardIt2, class + BinaryOp > + ForwardIt2 adjacent_difference( ExecutionPolicy&& + policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first, + ForwardIt1 last, - OutputIt adjacent_difference( InputIt first, InputIt last, \fB(2)\fP - OutputIt d_first, + ForwardIt2 d_first, + BinaryOp op ); - BinaryOperation op ); + 1) If [first, last) is empty, does nothing. + Otherwise, performs the following operations in order: + 1. Creates an accumulator acc of type T, and initializes it with *first. + 2. Assigns acc to *d_first. + 3. For each iterator iter in [++first, last) in order, performs the following + operations in order: + a) Creates an object val of type T, and initializes it with *iter. + b) Computes + val - acc + \fI(until C++11)\fP + val - std::move(acc) + \fI(since C++11)\fP. + c) Assigns the result to *++d_first. + d) + Copy + \fI(until C++11)\fP + Move + \fI(since C++11)\fP assigns from val to acc. + 2) If [first, last) is empty, does nothing. + Otherwise, performs the following operations in order: + 1. Assigns *first to *d_first. + 2. For each integer i in [1, std::distance(first, last)), performs the following + operations in order: + a) Computes curr - prev, where curr is the next i + th iterator of first, and prev is the next i - 1 + th iterator of first. + b) Assigns the result to *dest, where dest is the next i + th iterator of d_first. + 3) Same as \fB(1)\fP, but computes + op(val, acc) + \fI(until C++11)\fP + op(val, std::move(acc)) + \fI(since C++11)\fP instead. + 4) Same as \fB(2)\fP, but computes op(curr, prev) instead. - Computes the differences between the second and the first of each adjacent pair of - elements of the range [first, last) and writes them to the range beginning at - d_first + 1. Unmodified copy of first is written to d_first. The first version uses - operator- to calculate the differences, the second version uses the given binary - function op. + Given binary_op as the actual binary operation: - Equivalent operation: + * If any of the following conditions is satisfied, the program is ill-formed: - *(d_first) = *first; - *(d_first+1) = (*first+1) - *(first); - *(d_first+2) = (*first+2) - *(first+1); - *(d_first+3) = (*first+3) - *(first+2); - ... + * For overloads (1,3): - op must not have side effects. \fI(until C++11)\fP - op must not invalidate any iterators, including the end iterators, or \fI(since C++11)\fP - modify any elements of the ranges involved. + * T is not constructible from *first. + * acc is not writable to d_first. + * The result of + binary_op(val, acc) + \fI(until C++11)\fP + binary_op(val, std::move(acc)) + \fI(since C++11)\fP is not writable to d_first. + * For overloads (2,4): + + * *first is not writable to d_first. + * The result of binary_op(*first, *first) is not writable to d_first. + * Given d_last as the iterator to be returned, if any of the following conditions + is satisfied, the behavior is undefined: + + * For overloads (1,3), T is not MoveAssignable. \fI(since C++11)\fP + + * For overloads (2,4), [first, last) and [d_first, d_last) overlaps. + * binary_op modifies any element of [first, last) or [d_first, d_last). + * binary_op invalidates any iterator or subrange in [first, last] or + [d_first, d_last]. .SH Parameters first, last - the range of elements d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for details. binary operation function object that will be applied. The signature of the function should be equivalent to the following: @@ -42,101 +113,180 @@ Ret fun(const Type1 &a, const Type2 &b); op - The signature does not need to have const &. - The types Type1 and Type2 must be such that an object of type + The types Type1 and Type2 must be such that an object of type iterator_traits::value_type can be implicitly converted to both of them. The type Ret must be such that an object of type - OutputIt can be dereferenced and assigned a value of type Ret. + OutputIt can be dereferenced and assigned a value of type Ret. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value - It to the element past the last element written. + Iterator to the element past the last element written, or d_first if [first, last) + is empty. .SH Complexity - Exactly (last - first) - 1 applications of the binary operation + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize N-1\\)N-1 applications of operator-. + 3,4) Exactly \\(\\scriptsize N-1\\)N-1 applications of the binary function op. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + adjacent_difference \fB(1)\fP template - OutputIt adjacent_difference(InputIt first, InputIt last, - OutputIt d_first) + constexpr // since C++20 + OutputIt adjacent_difference(InputIt first, InputIt last, OutputIt d_first) { - if (first == last) return d_first; - + if (first == last) + return d_first; + typedef typename std::iterator_traits::value_type value_t; value_t acc = *first; *d_first = acc; - while (++first != last) { + + while (++first != last) + { value_t val = *first; - *++d_first = val - acc; + *++d_first = val - std::move(acc); // std::move since C++11 acc = std::move(val); } + return ++d_first; } -.SH Second version - template + adjacent_difference \fB(3)\fP + template + constexpr // since C++20 OutputIt adjacent_difference(InputIt first, InputIt last, - OutputIt d_first, BinaryOperation op) + OutputIt d_first, BinaryOp op) { - if (first == last) return d_first; - + if (first == last) + return d_first; + typedef typename std::iterator_traits::value_type value_t; value_t acc = *first; *d_first = acc; - while (++first != last) { + + while (++first != last) + { value_t val = *first; - *++d_first = op(val, acc); + *++d_first = op(val, std::move(acc)); // std::move since C++11 acc = std::move(val); } + return ++d_first; } +.SH Notes + + acc was introduced because of the resolution of LWG issue 539. The reason of using + acc rather than directly calculating the differences is because the semantic of the + latter is confusing if the following types mismatch: + + * the value type of InputIt + * the writable type(s) of OutputIt + * the types of the parameters of operator- or op + * the return type of operator- or op + + acc serves as the intermediate object to cache values of the iterated elements: + + * its type is the value type of InputIt + * the value written to d_first (which is the return value of operator- or op) is + assigned to it + * its value is passed to operator- or op + + char i_array[4] = {100, 100, 100, 100}; + int o_array[4]; + + // OK: performs conversions when needed + // 1. creates “acc” of type char (the value type) + // 2. “acc” is assigned to the first element of “o_array” + // 3. the char arguments are used for long multiplication (char -> long) + // 4. the long product is assigned to the output range (long -> int) + // 5. the next value of “i_array” is assigned to “acc” + // 6. go back to step 3 to process the remaining elements in the input range + std::adjacent_difference(i_array, i_array + 4, o_array, std::multiplies{}); + .SH Example - The following code converts a sequence of even numbers to repetitions of the number - 2 and converts a sequence of ones to a sequence of Fibonacci numbers. - // Run this code + #include + #include + #include + #include #include #include - #include - #include - - int main() + + void println(auto comment, const auto& sequence) { - std::vector v{2, 4, 6, 8, 10, 12, 14, 16, 18, 20}; - std::adjacent_difference(v.begin(), v.end(), v.begin()); - - for (auto n : v) { - std::cout << n << ' '; - } - std::cout << '\\n'; - - v = {1, 1, 1, 1, 1, 1, 1, 1, 1, 1}; - std::adjacent_difference(v.begin(), v.end() - 1, v.begin() + 1, std::plus()); - - for (auto n : v) { + std::cout << comment; + for (const auto& n : sequence) std::cout << n << ' '; - } std::cout << '\\n'; + }; + + int main() + { + // Default implementation - the difference between two adjacent items + std::vector v{4, 6, 9, 13, 18, 19, 19, 15, 10}; + println("Initially, v = ", v); + std::adjacent_difference(v.begin(), v.end(), v.begin()); + println("Modified v = ", v); + + // Fibonacci + std::array a {1}; + std::adjacent_difference(std::begin(a), std::prev(std::end(a)), + std::next(std::begin(a)), std::plus<>{}); + println("Fibonacci, a = ", a); } .SH Output: - 2 2 2 2 2 2 2 2 2 2 - 1 1 2 3 5 8 13 21 34 55 + Initially, v = 4 6 9 13 18 19 19 15 10 + Modified v = 4 2 3 4 5 1 0 -4 -5 + Fibonacci, a = 1 1 2 3 5 8 13 21 34 55 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 242 C++98 op could not have side effects it cannot modify + the ranges involved + the type requirements needed for the result + LWG 539 C++98 evaluations and assignments to be valid added + were missing + LWG 2055 C++11 acc was not moved while being accumulated it is moved + (P0616R0) + for overloads (2,4), the result of each + invocation assign the results + LWG 3058 C++17 of operator- or op was assigned to a to the output + temporary range directly + object, and that object is assigned to the + output range .SH See also partial_sum computes the partial sum of a range of elements - \fI(function template)\fP - accumulate sums up a range of elements - \fI(function template)\fP + \fI(function template)\fP + accumulate sums up or folds a range of elements + \fI(function template)\fP diff --git a/man/std::adjacent_find.3 b/man/std::adjacent_find.3 index a86e384ab..4400439a1 100644 --- a/man/std::adjacent_find.3 +++ b/man/std::adjacent_find.3 @@ -1,18 +1,49 @@ -.TH std::adjacent_find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::adjacent_find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::adjacent_find \- std::adjacent_find + .SH Synopsis Defined in header - template< class ForwardIt > \fB(1)\fP - ForwardIt adjacent_find( ForwardIt first, ForwardIt last ); - template< class ForwardIt, BinaryPredicate p > \fB(2)\fP - ForwardIt adjacent_find( ForwardIt first, ForwardIt last, BinaryPredicate p ); + template< class ForwardIt > + ForwardIt adjacent_find( ForwardIt first, ForwardIt last \fB(1)\fP (constexpr since C++20) + ); + template< class ExecutionPolicy, class ForwardIt > + + ForwardIt adjacent_find( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last + ); + template< class ForwardIt, class BinaryPred > + + ForwardIt adjacent_find( ForwardIt first, ForwardIt \fB(3)\fP (constexpr since C++20) + last, + + BinaryPred p ); + template< class ExecutionPolicy, class ForwardIt, class + BinaryPred > + + ForwardIt adjacent_find( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt + last, + + BinaryPred p ); + + Searches the range [first, last) for two consecutive equal elements. - Searches the range [first, last) for two consecutive identical elements. The first - version uses operator== to compare the elements, the second version uses the given - binary predicate p. + 1) Elements are compared using operator==. + 3) Elements are compared using the given binary predicate p. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -20,100 +51,137 @@ following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must not - modify the objects passed to it. + + p - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of them. - - .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + BinaryPred must meet the requirements of BinaryPredicate. .SH Return value - an iterator to the first of the identical elements. If no such elements are found, - last is returned + An iterator to the first of the first pair of identical elements, that is, the first + iterator it such that *it == *(it + 1) for (1,2) or p(*it, *(it + 1)) != false for + (3,4). + + If no such elements are found, last is returned. .SH Complexity - Exactly the smaller of (result - first) + 1 and (last - first) - 1 applications of - the predicate where result is the return value. + Given result as the return value of adjacent_find, \\(\\scriptsize M\\)M as + std::distance(first, result) and \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) Exactly \\(\\scriptsize \\min(M+1,N-1)\\)min(M+1,N-1) comparisons using operator==. + 2) \\(\\scriptsize O(N)\\)O(N) comparisons using operator==. + 3) Exactly \\(\\scriptsize \\min(M+1,N-1)\\)min(M+1,N-1) applications of the predicate + p. + 4) \\(\\scriptsize O(N)\\)O(N) applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + adjacent_find \fB(1)\fP template ForwardIt adjacent_find(ForwardIt first, ForwardIt last) { - if (first == last) { + if (first == last) return last; - } + ForwardIt next = first; ++next; - for (; next != last; ++next, ++first) { - if (*first == *next) { + + for (; next != last; ++next, ++first) + if (*first == *next) return first; - } - } + return last; } -.SH Second version - template - ForwardIt adjacent_find(ForwardIt first, ForwardIt last, - BinaryPredicate p) + adjacent_find \fB(3)\fP + template + ForwardIt adjacent_find(ForwardIt first, ForwardIt last, BinaryPred p) { - if (first == last) { + if (first == last) return last; - } + ForwardIt next = first; ++next; - for (; next != last; ++next, ++first) { - if (p(*first, *next)) { + + for (; next != last; ++next, ++first) + if (p(*first, *next)) return first; - } - } + return last; } .SH Example - + // Run this code #include + #include #include - + #include + int main() { std::vector v1{0, 1, 2, 3, 40, 40, 41, 41, 5}; - + auto i1 = std::adjacent_find(v1.begin(), v1.end()); - - if (i1 == v1.end()) { - std::cout << "no matching adjacent elements\\n"; - } else { - std::cout << "the first adjacent pair of equal elements at: " - << std::distance(v1.begin(), i1) << '\\n'; - } - + + if (i1 == v1.end()) + std::cout << "No matching adjacent elements\\n"; + else + std::cout << "The first adjacent pair of equal elements is at " + << std::distance(v1.begin(), i1) << ", *i1 = " + << *i1 << '\\n'; + auto i2 = std::adjacent_find(v1.begin(), v1.end(), std::greater()); - if (i2 == v1.end()) { + if (i2 == v1.end()) std::cout << "The entire vector is sorted in ascending order\\n"; - } else { - std::cout << "The last element in the non-decreasing subsequence is at: " - << std::distance(v1.begin(), i2) << '\\n'; - } + else + std::cout << "The last element in the non-decreasing subsequence is at " + << std::distance(v1.begin(), i2) << ", *i2 = " << *i2 << '\\n'; } .SH Output: - The first adjacent pair of equal elements at: 4 - The last element in the non-decreasing subsequence is at: 7 + The first adjacent pair of equal elements is at 4, *i1 = 40 + The last element in the non-decreasing subsequence is at 7, *i2 = 41 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the predicate was applied std::find applied std::min( + LWG 240 C++98 (first, last, value) - first times (result - first) + 1, + for (1,3), where value was never (last - first) - 1) times + defined .SH See also - unique removes consecutive duplicate elements in a range - \fI(function template)\fP + unique removes consecutive duplicate elements in a range + \fI(function template)\fP + ranges::adjacent_find finds the first two adjacent items that are equal (or satisfy + (C++20) a given predicate) + (niebloid) diff --git a/man/std::advance.3 b/man/std::advance.3 index 2f7c3e3c2..9711394ca 100644 --- a/man/std::advance.3 +++ b/man/std::advance.3 @@ -1,21 +1,26 @@ -.TH std::advance 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::advance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::advance \- std::advance + .SH Synopsis Defined in header - template< class InputIt, class Distance > + template< class InputIt, class Distance > \fI(until C++17)\fP void advance( InputIt& it, Distance n ); + template< class InputIt, class Distance > \fI(since C++17)\fP + constexpr void advance( InputIt& it, Distance n ); Increments given iterator it by n elements. If n is negative, the iterator is decremented. In this case, InputIt must meet the - requirements of BidirectionalIterator, otherwise the behavior is undefined. + requirements of LegacyBidirectionalIterator, otherwise the behavior is undefined. .SH Parameters - it - iterator to be advanced - n - number of elements it should be advanced + it - iterator to be advanced + n - number of elements it should be advanced .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value @@ -25,34 +30,123 @@ Linear. - However, if InputIt additionally meets the requirements of RandomAccessIterator, - complexity is constant. + However, if InputIt additionally meets the requirements of + LegacyRandomAccessIterator, complexity is constant. + +.SH Notes + + The behavior is undefined if the specified sequence of increments or decrements + would require that a non-incrementable iterator (such as the past-the-end iterator) + is incremented, or that a non-decrementable iterator (such as the front iterator or + the singular iterator) is decremented. + +.SH Possible implementation + + See also the implementations in libstdc++ and libc++. + + Non-constexpr version + namespace detail + { + template + void do_advance(It& it, typename std::iterator_traits::difference_type n, + std::input_iterator_tag) + { + while (n > 0) + { + --n; + ++it; + } + } + + template + void do_advance(It& it, typename std::iterator_traits::difference_type n, + std::bidirectional_iterator_tag) + { + while (n > 0) + { + --n; + ++it; + } + while (n < 0) + { + ++n; + --it; + } + } + + template + void do_advance(It& it, typename std::iterator_traits::difference_type n, + std::random_access_iterator_tag) + { + it += n; + } + } // namespace detail + + template + void advance(It& it, Distance n) + { + detail::do_advance(it, typename std::iterator_traits::difference_type(n), + typename std::iterator_traits::iterator_category()); + } + constexpr version + template + constexpr void advance(It& it, Distance n) + { + using category = typename std::iterator_traits::iterator_category; + static_assert(std::is_base_of_v); + + auto dist = typename std::iterator_traits::difference_type(n); + if constexpr (std::is_base_of_v) + it += dist; + else + { + while (dist > 0) + { + --dist; + ++it; + } + if constexpr (std::is_base_of_v) + while (dist < 0) + { + ++dist; + --it; + } + } + } .SH Example - + // Run this code #include #include #include - + int main() { - std::vector v{ 3, 1, 4 }; - + std::vector v{3, 1, 4}; + auto vi = v.begin(); - std::advance(vi, 2); - + std::cout << *vi << ' '; + + vi = v.end(); + std::advance(vi, -2); std::cout << *vi << '\\n'; } .SH Output: - 4 + 4 1 .SH See also - distance returns the distance between two iterators - \fI(function)\fP + next increment an iterator + \fI(C++11)\fP \fI(function template)\fP + prev decrement an iterator + \fI(C++11)\fP \fI(function template)\fP + distance returns the distance between two iterators + \fI(function template)\fP + ranges::advance advances an iterator by given distance or to a given bound + (C++20) (niebloid) diff --git a/man/std::align.3 b/man/std::align.3 index 64db45af0..37eb5ce74 100644 --- a/man/std::align.3 +++ b/man/std::align.3 @@ -1,4 +1,7 @@ -.TH std::align 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::align 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::align \- std::align + .SH Synopsis Defined in header void* align( std::size_t alignment, @@ -8,17 +11,21 @@ std::size_t& space ); - If it is possible to fit size bytes of storage aligned by alignment into the buffer - pointed to by ptr with length space, the function modifies ptr to point to the first - possible address of such aligned storage and decreases space by the number of bytes - used for alignment. If it is impossible (the buffer is too small), align does - nothing. + Given a pointer ptr to a buffer of size space, returns a pointer aligned by the + specified alignment for size number of bytes and decreases space argument by the + number of bytes used for alignment. The first aligned address is returned. + + The function modifies the pointer only if it would be possible to fit the wanted + number of bytes aligned by the given alignment into the buffer. If the buffer is too + small, the function does nothing and returns nullptr. + + The behavior is undefined if alignment is not a power of two. .SH Parameters alignment - the desired alignment size - the size of the storage to be aligned - ptr - pointer to contiguous storage of at least space bytes + ptr - pointer to contiguous storage (a buffer) of at least space bytes space - the size of the buffer in which to operate .SH Return value @@ -27,22 +34,22 @@ .SH Example - demonstrates the use of std::align to place objects of different type in memory + Demonstrates the use of std::align to place objects of different type in memory. + - // Run this code #include #include - - template + + template struct MyAllocator { char data[N]; void* p; std::size_t sz; MyAllocator() : p(data), sz(N) {} - template + template T* aligned_alloc(std::size_t a = alignof(T)) { if (std::align(a, sizeof(T), p, sz)) @@ -55,41 +62,58 @@ return nullptr; } }; - + int main() { MyAllocator<64> a; - + std::cout << "allocated a.data at " << (void*)a.data + << " (" << sizeof a.data << " bytes)\\n"; + // allocate a char - char* p1 = a.aligned_alloc(); - if (p1) - *p1 = 'a'; - std::cout << "allocated a char at " << (void*)p1 << '\\n'; - + if (char* p = a.aligned_alloc()) + { + *p = 'a'; + std::cout << "allocated a char at " << (void*)p << '\\n'; + } + // allocate an int - int* p2 = a.aligned_alloc(); - if (p2) - *p2 = 1; - std::cout << "allocated an int at " << (void*)p2 << '\\n'; - + if (int* p = a.aligned_alloc()) + { + *p = 1; + std::cout << "allocated an int at " << (void*)p << '\\n'; + } + // allocate an int, aligned at 32-byte boundary - int* p3 = a.aligned_alloc(32); - if (p3) - *p3 = 2; - std::cout << "allocated an int at " << (void*)p3 << " (32 byte alignment)\\n"; + if (int* p = a.aligned_alloc(32)) + { + *p = 2; + std::cout << "allocated an int at " << (void*)p << " (32 byte alignment)\\n"; + } } .SH Possible output: - allocated a char at 0x2ff21a08 - allocated an int at 0x2ff21a0c - allocated an int at 0x2ff21a20 (32 byte alignment) + allocated a.data at 0x7ffd0b331f80 (64 bytes) + allocated a char at 0x7ffd0b331f80 + allocated an int at 0x7ffd0b331f84 + allocated an int at 0x7ffd0b331fa0 (32 byte alignment) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2377 C++11 alignment required to be a fundamental only need to be a power + or supported extended alignment value of two .SH See also - alignof operator queries alignment requirements of a type \fI(since C++11)\fP - alignas specifier specifies that the storage for the variable should be aligned by - specific amount \fI(C++11)\fP - aligned_storage defines the type suitable for use as uninitialized storage for - \fI(C++11)\fP types of given size - \fI(class template)\fP + alignof operator\fI(C++11)\fP queries alignment requirements of a type + alignas specifier\fI(C++11)\fP specifies that the storage for the variable should be + aligned by specific amount + aligned_storage defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for types of given size + \fI(class template)\fP + assume_aligned informs the compiler that a pointer is aligned + (C++20) \fI(function template)\fP diff --git a/man/std::align_val_t.3 b/man/std::align_val_t.3 new file mode 100644 index 000000000..3a12c93ec --- /dev/null +++ b/man/std::align_val_t.3 @@ -0,0 +1,28 @@ +.TH std::align_val_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::align_val_t \- std::align_val_t + +.SH Synopsis + Defined in header + enum class align_val_t : std::size_t {}; \fI(since C++17)\fP + + Both new-expression and delete-expression, when used with objects whose alignment + requirement is greater than __STDCPP_DEFAULT_NEW_ALIGNMENT__, pass that alignment + requirement as an argument of type std::align_val_t to the selected + allocation/deallocation function. + +.SH Notes + + Alignment (as obtained by alignof) has the type std::size_t, but placement forms of + allocation and deallocation functions that take std::size_t as an additional + parameter are already in use, so this type is used instead. + + Feature-test macro Value Std Feature + __cpp_aligned_new 201606L \fI(C++17)\fP Dynamic memory allocation for over-aligned data + +.SH See also + + operator new allocation functions + operator new[] \fI(function)\fP + operator delete deallocation functions + operator delete[] \fI(function)\fP diff --git a/man/std::aligned_alloc.3 b/man/std::aligned_alloc.3 new file mode 100644 index 000000000..9d78423f2 --- /dev/null +++ b/man/std::aligned_alloc.3 @@ -0,0 +1,90 @@ +.TH std::aligned_alloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::aligned_alloc \- std::aligned_alloc + +.SH Synopsis + Defined in header + void* aligned_alloc( std::size_t alignment, std::size_t size ); \fI(since C++17)\fP + + Allocate size bytes of uninitialized storage whose alignment is specified by + alignment (implicitly creating objects in the destination area). The size parameter + must be an integral multiple of alignment. + + The following functions are required to be thread-safe: + + * The library versions of operator new and operator delete + * User replacement versions of global operator new and operator delete + * std::calloc, std::malloc, std::realloc, std::aligned_alloc, std::free + + Calls to these functions that allocate or deallocate a particular unit of storage + occur in a single total order, and each such deallocation call happens-before the + next allocation (if any) in this order. + +.SH Parameters + + alignment - specifies the alignment. Must be a valid alignment supported by the + implementation. + size - number of bytes to allocate. An integral multiple of alignment. + +.SH Return value + + On success, returns the pointer to the beginning of newly allocated memory. To avoid + a memory leak, the returned pointer must be deallocated with std::free or + std::realloc. + + On failure, returns a null pointer. + +.SH Notes + + Passing a size which is not an integral multiple of alignment or an alignment which + is not valid or not supported by the implementation causes the function to fail and + return a null pointer (C11, as published, specified undefined behavior in this case, + this was corrected by DR460). + + As an example of the "supported by the implementation" requirement, POSIX function + posix_memalign accepts any alignment that is a power of two and a multiple of + sizeof(void*), and POSIX-based implementations of aligned_alloc inherit this + requirements. + + Fundamental alignments are always supported. If alignment is a power of two and not + greater than alignof(std::max_align_t), aligned_alloc may simply call std::malloc. + + Regular std::malloc aligns memory suitable for any object type with a fundamental + alignment. This function is useful for over-aligned allocations, such as to SSE, + cache line, or VM page boundary. + + This function is not supported in Microsoft C Runtime library because its + implementation of std::free is unable to handle aligned allocations of any kind. + Instead, MS CRT provides _aligned_malloc (to be freed with _aligned_free). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int* p1 = static_cast(std::malloc(10 * sizeof *p1)); + std::printf("default-aligned address: %p\\n", static_cast(p1)); + std::free(p1); + + int* p2 = static_cast(std::aligned_alloc(1024, 1024)); + std::printf("1024-byte aligned address: %p\\n", static_cast(p2)); + std::free(p2); + } + +.SH Possible output: + + default-aligned address: 0x2221c20 + 1024-byte aligned address: 0x2222400 + +.SH See also + + aligned_storage defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for types of given size + \fI(class template)\fP + C documentation for + aligned_alloc diff --git a/man/std::aligned_storage.3 b/man/std::aligned_storage.3 index 643148e0e..ffc55dd33 100644 --- a/man/std::aligned_storage.3 +++ b/man/std::aligned_storage.3 @@ -1,39 +1,60 @@ -.TH std::aligned_storage 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::aligned_storage 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::aligned_storage \- std::aligned_storage + .SH Synopsis Defined in header - template< std::size_t Len, std::size_t Align = /*default-alignment*/ - > \fI(since C++11)\fP + template< std::size_t Len, std::size_t Align = /* \fI(since C++11)\fP + default-alignment */ > (deprecated in C++23) struct aligned_storage; - Provides the member typedef type, which is a POD type suitable for use as - uninitialized storage for any object whose size is at most Len and whose alignment - requirement is a divisor of Align. The default value of Align is the most stringent - (the largest) alignment requirement for any object whose size is at most Len. + Provides the nested type type, which satisfies TrivialType and StandardLayoutType + and suitable for use as uninitialized storage for any object whose size is at most + Len and whose alignment requirement is a divisor of Align. + + The default value of Align is the most stringent (the largest) alignment requirement + for any object whose size is at most Len. If the default value is not used, Align + must be the value of alignof(T) for some type T, or the behavior is undefined. + + The behavior is undefined if Len == 0. + + It is implementation-defined whether any extended alignment is supported. + + If the program adds specializations for std::aligned_storage, the behavior is + undefined. .SH Member types Name Definition - type the POD type of at least size Len with alignment requirement Align + type a trivial and standard-layout type of at least size Len with alignment + requirement Align .SH Helper types - template< std::size_t Len, std::size_t Align = /*default-alignment*/ - > \fI(since C++14)\fP - using aligned_storage_t = typename aligned_storage::type; + template< std::size_t Len, std::size_t Align = /* + default-alignment */ > \fI(since C++14)\fP + using aligned_storage_t = typename aligned_storage::type; .SH Notes - The type defined by std::aligned_storage can be used to create uninitialized memory - blocks suitable to hold the objects of given type, optionally aligned stricter than - necessary, for example on a cache or page boundary. + The type defined by std::aligned_storage<>::type can be used to create uninitialized + memory blocks suitable to hold the objects of given type, optionally aligned + stricter than their natural alignment requirement, for example on a cache or page + boundary. + + As with any other uninitialized storage, the objects are created using placement new + and destroyed with explicit destructor calls. .SH Possible implementation Except for default argument, aligned_storage is expressible in terms of alignas: - template - struct aligned_storage { - struct type { + template + struct aligned_storage + { + struct type + { alignas(Align) unsigned char data[Len]; }; }; @@ -41,45 +62,52 @@ .SH Example A primitive static vector class, demonstrating creation, access, and destruction of - objects in aligned storage + objects in aligned storage. + - // Run this code + #include #include - #include + #include #include - + #include + template class static_vector { - // properly aligned uninitialized storage for N T's - typename std::aligned_storage::value>::type data[N]; - std::size_t m_size; + // Properly aligned uninitialized storage for N T's + std::aligned_storage_t data[N]; + std::size_t m_size = 0; + public: - - static_vector() : m_size(0) {}; // Create an object in aligned storage template void emplace_back(Args&&... args) { - new(data+m_size) T(std::forward(args)...); - m_size++; // bounds check omitted + if (m_size >= N) // Possible error handling + throw std::bad_alloc{}; + + // Construct value in memory of aligned storage using inplace operator new + ::new(&data[m_size]) T(std::forward(args)...); + ++m_size; } - + // Access an object in aligned storage - const T& operator[](size_t pos) const + const T& operator[](std::size_t pos) const { - return *static_cast(static_cast(&data[pos])); + // Note: std::launder is needed after the change of object model in P0137R1 + return *std::launder(reinterpret_cast(&data[pos])); } - // Delete objects from aligned storage + + // Destroy objects from aligned storage ~static_vector() { - for(std::size_t pos = 0; pos < m_size; ++pos) { - static_cast(static_cast(data+pos))->~T(); - } + for (std::size_t pos = 0; pos < m_size; ++pos) + // Note: std::launder is needed after the change of object model in P0137R1 + std::destroy_at(std::launder(reinterpret_cast(&data[pos]))); } }; - + int main() { static_vector v1; @@ -95,13 +123,17 @@ .SH See also - alignas specifier specifies that the storage for the variable should be aligned by - specific amount \fI(C++11)\fP - alignment_of obtains the type's alignment requirements - \fI(C++11)\fP \fI(class template)\fP - aligned_union defines the type suitable for use as uninitialized storage for all - \fI(C++11)\fP given types - \fI(class template)\fP - max_align_t POD type with alignment requirement as great as any other scalar - \fI(C++11)\fP type - \fI(typedef)\fP + alignas specifier\fI(C++11)\fP specifies that the storage for the variable should be + aligned by specific amount + alignment_of obtains the type's alignment requirements + \fI(C++11)\fP \fI(class template)\fP + aligned_alloc allocates aligned memory + \fI(C++17)\fP \fI(function)\fP + aligned_union defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for all given types + \fI(class template)\fP + max_align_t trivial type with alignment requirement as great as any + \fI(C++11)\fP other scalar type + \fI(typedef)\fP + launder pointer optimization barrier + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::aligned_union.3 b/man/std::aligned_union.3 index d5d1f0c78..cb99f68c4 100644 --- a/man/std::aligned_union.3 +++ b/man/std::aligned_union.3 @@ -1,43 +1,112 @@ -.TH std::aligned_union 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::aligned_union 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::aligned_union \- std::aligned_union + .SH Synopsis Defined in header template< std::size_t Len, class... Types > \fI(since C++11)\fP - struct aligned_union; + struct aligned_union; (deprecated in C++23) + + Provides the nested type type, which is a trivial standard-layout type of a size and + alignment suitable for use as uninitialized storage for an object of any of the + types listed in Types. The size of the storage is at least Len. std::aligned_union + also determines the strictest (largest) alignment requirement among all Types and + makes it available as the constant alignment_value. + + If sizeof...(Types) == 0 or if any of the types in Types is not a complete object + type, the behavior is undefined. - Provides the member typedef type, which is a POD type of a size and alignment - suitable for use as uninitialized storage for an object of any of the types listed - in Types. The size of the storage is at least Len. std::aligned_union also - determines the strictest (largest) alignment requirement among all Types and makes - it available as the constant alignment_value. + It is implementation-defined whether any extended alignment is supported. + + If the program adds specializations for std::aligned_union, the behavior is + undefined. .SH Member types Name Definition - type the POD type suitable for storage of any type from Types + type a trivial and standard-layout type suitable for storage of any type from Types .SH Helper types - template< std::size_t Len, class... Types > \fI(since C++14)\fP - using aligned_union_t = typename aligned_union::type; + template< std::size_t Len, class... Types > \fI(since C++14)\fP + using aligned_union_t = typename (deprecated in C++23) + aligned_union::type; .SH Member constants alignment_value the strictest alignment requirement of all Types \fB[static]\fP \fI(public static member constant)\fP +.SH Possible implementation + + #include + + template + struct aligned_union + { + static constexpr std::size_t alignment_value = std::max({alignof(Types)...}); + + struct type + { + alignas(alignment_value) char _s[std::max({Len, sizeof(Types)...})]; + }; + }; + .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include - alignment_of obtains the type's alignment requirements - \fI(C++11)\fP \fI(class template)\fP - aligned_storage defines the type suitable for use as uninitialized storage for types - \fI(C++11)\fP of given size - \fI(class template)\fP + int main() + { + std::cout << sizeof(std::aligned_union_t<0, char>) << ' ' // 1 + << sizeof(std::aligned_union_t<2, char>) << ' ' // 2 + << sizeof(std::aligned_union_t<2, char[3]>) << ' ' // 3 (!) + << sizeof(std::aligned_union_t<3, char[4]>) << ' ' // 4 + << sizeof(std::aligned_union_t<1, char, int, double>) << ' ' // 8 + << sizeof(std::aligned_union_t<12, char, int, double>) << '\\n'; // 16 (!) -.SH Category: + using var_t = std::aligned_union<16, int, std::string>; + + std::cout << "var_t::alignment_value = " << var_t::alignment_value << '\\n' + << "sizeof(var_t::type) = " << sizeof(var_t::type) << '\\n'; + + var_t::type aligned_storage; + int* int_ptr = new(&aligned_storage) int(42); // placement new + std::cout << "*int_ptr = " << *int_ptr << '\\n'; + + std::string* string_ptr = new(&aligned_storage) std::string("bar"); + std::cout << "*string_ptr = " << *string_ptr << '\\n'; + *string_ptr = "baz"; + std::cout << "*string_ptr = " << *string_ptr << '\\n'; + string_ptr->~basic_string(); + } + +.SH Possible output: + + 1 2 3 4 8 16 + var_t::alignment_value = 8 + sizeof(var_t::type) = 32 + *int_ptr = 42 + *string_ptr = bar + *string_ptr = baz + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2979 C++11 complete type was not required requires complete types + +.SH See also - * Todo no example + alignment_of obtains the type's alignment requirements + \fI(C++11)\fP \fI(class template)\fP + aligned_storage defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for types of given size + \fI(class template)\fP diff --git a/man/std::alignment_of.3 b/man/std::alignment_of.3 index 4add6c503..64398763f 100644 --- a/man/std::alignment_of.3 +++ b/man/std::alignment_of.3 @@ -1,4 +1,7 @@ -.TH std::alignment_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::alignment_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::alignment_of \- std::alignment_of + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -6,17 +9,26 @@ Provides the member constant value equal to the alignment requirement of the type T, as if obtained by an alignof expression. If T is an array type, returns the - alignment requirements of the element type. + alignment requirements of the element type. If T is a reference type, returns the + alignment requirements of the type referred to. + + If alignof(T) is not a valid expression, the behavior is undefined. + + If the program adds specializations for std::alignment_of + or std::alignment_of_v + \fI(since C++17)\fP, the behavior is undefined. .SH Member constants - value alignof(typename std::remove_all_extents::type) + value alignof(T) \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator std::size_t converts the object to std::size_t, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,11 +38,8 @@ .SH Possible implementation - template< class T > - struct alignment_of : std::integral_constant< - std::size_t, - alignof(typename std::remove_all_extents::type) - > {}; + template + struct alignment_of : std::integral_constant {}; .SH Notes @@ -39,36 +48,43 @@ .SH Example - + // Run this code + #include #include #include - - class A {}; - + + struct A {}; + struct B + { + std::int8_t p; + std::int16_t q; + }; + int main() { - std::cout << std::alignment_of::value << '\\n'; - std::cout << std::alignment_of::value << '\\n'; - std::cout << std::alignment_of::value << '\\n'; + std::cout << std::alignment_of::value << ' '; + std::cout << std::alignment_of::value << ' '; + std::cout << std::alignment_of() << ' '; // alt syntax + std::cout << std::alignment_of_v << '\\n'; // c++17 alt syntax } -.SH Output: +.SH Possible output: - 1 - 4 - 8 + 1 2 4 8 .SH See also - alignof operator queries alignment requirements of a type \fI(since C++11)\fP - aligned_storage defines the type suitable for use as uninitialized storage for - \fI(C++11)\fP types of given size - \fI(class template)\fP - aligned_union defines the type suitable for use as uninitialized storage for all - \fI(C++11)\fP given types - \fI(class template)\fP - max_align_t POD type with alignment requirement as great as any other scalar - \fI(C++11)\fP type - \fI(typedef)\fP + alignof operator\fI(C++11)\fP queries alignment requirements of a type + alignas specifier\fI(C++11)\fP specifies that the storage for the variable should be + aligned by specific amount + aligned_storage defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for types of given size + \fI(class template)\fP + aligned_union defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for all given types + \fI(class template)\fP + max_align_t trivial type with alignment requirement as great as any + \fI(C++11)\fP other scalar type + \fI(typedef)\fP diff --git a/man/std::all_of,std::any_of,std::none_of.3 b/man/std::all_of,std::any_of,std::none_of.3 index ebbe6584a..ec51ecaae 100644 --- a/man/std::all_of,std::any_of,std::none_of.3 +++ b/man/std::all_of,std::any_of,std::none_of.3 @@ -1,86 +1,133 @@ -.TH std::all_of,std::any_of,std::none_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::all_of,std::any_of,std::none_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::all_of,std::any_of,std::none_of \- std::all_of,std::any_of,std::none_of + .SH Synopsis Defined in header - template< class InputIt, class UnaryPredicate > \fB(1)\fP \fI(since C++11)\fP - bool all_of( InputIt first, InputIt last, UnaryPredicate p ); - template< class InputIt, class UnaryPredicate > \fB(2)\fP \fI(since C++11)\fP - bool any_of( InputIt first, InputIt last, UnaryPredicate p ); - template< class InputIt, class UnaryPredicate > \fB(3)\fP \fI(since C++11)\fP - bool none_of( InputIt first, InputIt last, UnaryPredicate p ); - - 1) Checks if unary predicate p returns true for all elements in the range [first, - last). - 2) Checks if unary predicate p returns true for at least one element in the range + template< class InputIt, class UnaryPred > \fB(1)\fP \fI(since C++11)\fP + bool all_of( InputIt first, InputIt last, UnaryPred p ); (constexpr since C++20) + template< class ExecutionPolicy, class ForwardIt, class + UnaryPred > + + bool all_of( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, UnaryPred + p ); + template< class InputIt, class UnaryPred > \fB(3)\fP \fI(since C++11)\fP + bool any_of( InputIt first, InputIt last, UnaryPred p ); (constexpr since C++20) + template< class ExecutionPolicy, class ForwardIt, class + UnaryPred > + + bool any_of( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, UnaryPred + p ); + template< class InputIt, class UnaryPred > \fI(since C++11)\fP + bool none_of( InputIt first, InputIt last, UnaryPred p \fB(5)\fP (constexpr since C++20) + ); + template< class ExecutionPolicy, class ForwardIt, class + UnaryPred > + + bool none_of( ExecutionPolicy&& policy, \fB(6)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, UnaryPred + p ); + + 1) Checks if unary predicate p returns true for all elements in the range + [first, last). + 3) Checks if unary predicate p returns true for at least one element in the range [first, last). - 3) Checks if unary predicate p returns true for no elements in the range [first, - last). + 5) Checks if unary predicate p returns true for no elements in the range + [first, last). + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine + policy - the execution policy to use. See execution policy for details. unary predicate . - The signature of the predicate function should be equivalent to the - following: - - p - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value - 1) true if unary predicate returns true for all elements in the range, false - otherwise. Returns true if the range is empty. - 2) true if unary predicate returns true for at least one element in the range, false - otherwise. Returns false if the range is empty. - 3) true if unary predicate returns true for no elements in the range, false - otherwise. Returns true if the range is empty. + Has true element Yes No + Has false element Yes No Yes No + all_of false true false true + any_of true true false false + none_of false false true true .SH Complexity - At most last - first applications of the predicate + 1-6) At most std::distance(first, last) applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template< class InputIt, class UnaryPredicate > - bool all_of(InputIt first, InputIt last, UnaryPredicate p) + See also the implementations of + + * all_of in libstdc++ and libc++. + * any_of in libstdc++ and libc++. + * none_of in libstdc++ and libc++. + + all_of + template + constexpr bool all_of(InputIt first, InputIt last, UnaryPred p) { return std::find_if_not(first, last, p) == last; } -.SH Second version - template< class InputIt, class UnaryPredicate > - bool any_of(InputIt first, InputIt last, UnaryPredicate p) + any_of + template + constexpr bool any_of(InputIt first, InputIt last, UnaryPred p) { return std::find_if(first, last, p) != last; } - Third version - template< class InputIt, class UnaryPredicate > - bool none_of(InputIt first, InputIt last, UnaryPredicate p) + none_of + template + constexpr bool none_of(InputIt first, InputIt last, UnaryPred p) { return std::find_if(first, last, p) == last; } .SH Example - + // Run this code - #include - #include #include - #include - #include #include - + #include + #include + #include + #include + int main() { std::vector v(10, 2); @@ -88,24 +135,23 @@ std::cout << "Among the numbers: "; std::copy(v.cbegin(), v.cend(), std::ostream_iterator(std::cout, " ")); std::cout << '\\n'; - - if (std::all_of(v.cbegin(), v.cend(), [](int i){ return i % 2 == 0; })) { + + if (std::all_of(v.cbegin(), v.cend(), [](int i) { return i % 2 == 0; })) std::cout << "All numbers are even\\n"; - } - if (std::none_of(v.cbegin(), v.cend(), std::bind(std::modulus(), - std::placeholders::_1, 2))) { + + if (std::none_of(v.cbegin(), v.cend(), std::bind(std::modulus<>(), + std::placeholders::_1, 2))) std::cout << "None of them are odd\\n"; - } + struct DivisibleBy { const int d; DivisibleBy(int n) : d(n) {} bool operator()(int n) const { return n % d == 0; } }; - - if (std::any_of(v.cbegin(), v.cend(), DivisibleBy(7))) { + + if (std::any_of(v.cbegin(), v.cend(), DivisibleBy(7))) std::cout << "At least one number is divisible by 7\\n"; - } } .SH Output: @@ -114,3 +160,12 @@ All numbers are even None of them are odd At least one number is divisible by 7 + +.SH See also + + ranges::all_of + ranges::any_of checks if a predicate is true for all, any or none of the elements + ranges::none_of in a range + (C++20) (niebloid) + (C++20) + (C++20) diff --git a/man/std::allocate_shared,std::allocate_shared_for_overwrite.3 b/man/std::allocate_shared,std::allocate_shared_for_overwrite.3 new file mode 100644 index 000000000..82fe46e6f --- /dev/null +++ b/man/std::allocate_shared,std::allocate_shared_for_overwrite.3 @@ -0,0 +1,159 @@ +.TH std::allocate_shared,std::allocate_shared_for_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocate_shared,std::allocate_shared_for_overwrite \- std::allocate_shared,std::allocate_shared_for_overwrite + +.SH Synopsis + Defined in header + template< class T, class Alloc, class... Args > \fI(since C++11)\fP + shared_ptr allocate_shared( const Alloc& alloc, Args&&... \fB(1)\fP (T is non-array) + args ); + template< class T, class Alloc > \fI(since C++20)\fP + shared_ptr allocate_shared( const Alloc& alloc, std::size_t \fB(2)\fP (T is U[]) + N ); + template< class T, class Alloc > \fB(3)\fP \fI(since C++20)\fP + shared_ptr allocate_shared( const Alloc& alloc ); (T is U[N]) + template< class T, class Alloc > + + shared_ptr allocate_shared( const Alloc& alloc, std::size_t \fI(since C++20)\fP + N, \fB(4)\fP (T is U[]) + + const std::remove_extent_t& u + ); + template< class T, class Alloc > + + shared_ptr allocate_shared( const Alloc& alloc, \fB(5)\fP \fI(since C++20)\fP + (T is U[N]) + const std::remove_extent_t& u + ); + template< class T, class Alloc > \fI(since C++20)\fP + shared_ptr allocate_shared_for_overwrite( const Alloc& alloc \fB(6)\fP (T is not U[]) + ); + template< class T, class Alloc > \fI(since C++20)\fP + shared_ptr allocate_shared_for_overwrite( const Alloc& \fB(7)\fP (T is U[]) + alloc, std::size_t N ); + + 1) Constructs an object of type T and wraps it in a std::shared_ptr using args as + the parameter list for the constructor of T. The object is constructed as if by the + expression + ::new (pv) T(v) + \fI(until C++20)\fP + std::allocator_traits::construct(a, pv, v) + \fI(since C++20)\fP, where pv is an internal void* pointer to storage suitable to hold an + object of type T and a is a copy of the allocator rebound to std::remove_cv_t. + The storage is typically larger than sizeof(T) in order to use one allocation for + both the control block of the shared pointer and the T object. The std::shared_ptr + constructor called by this function enables shared_from_this with a pointer to the + newly constructed object of type T. All memory allocation is done using a copy of + alloc, which must satisfy the Allocator requirements. This overload participates in + overload resolution only if T is not an array type. + 2,3) Same as \fB(1)\fP, but the object constructed is a possibly-multidimensional array + whose every non-array element is initialized as if by the expression + std::allocator_traits::construct(a2, pv) where a2 of type A2 is the copy of the + allocator rebound to manage objects of type + std::remove_cv_t>. The overload \fB(2)\fP creates an array of + size N along its first dimension. The array elements are initialized in ascending + order of their addresses, and when their lifetime ends are destroyed in the reverse + order of their original construction. + 4,5) Same as (2,3), but the elements of the array are initialized from the default + value u. If std::remove_extent_t is not itself an array type, then this is + performed as if by the same allocator expression as in \fB(1)\fP, except that the + allocator is rebound to the std::remove_cv_t>. + Otherwise, this is performed as if by initializing every non-array element of the + (possibly multidimensional) array with the corresponding element from u using the + same allocator expression as in \fB(1)\fP, except that the allocator is rebound to the + type std::remove_cv_t>. The overload \fB(4)\fP creates an + array of size N along the first dimension. The array elements are initialized in + ascending order of their addresses, and when their lifetime ends are destroyed in + the reverse order of their original construction. + 6) Same as \fB(1)\fP if T is not an array type and \fB(3)\fP if T is U[N], except that the + created object is default-initialized. + 7) Same as \fB(2)\fP, except that the individual array elements are default-initialized. + + For allocate_shared, the object + (or the individual array elements for (2-5)) + \fI(since C++20)\fP are destroyed via the expression std::allocator_traits::destroy(a, + p), where p is a pointer to the object and a is a copy of the allocator passed to + allocate_shared, rebound to the type of the object being destroyed. + + For allocate_shared_for_overwrite, the object (or individual elements + if T is an array type) will be destroyed by p->~X(), where p is a \fI(since C++20)\fP + pointer to the object and X is its type. + +.SH Parameters + + alloc - the Allocator to use + args... - list of arguments with which an instance of T will be constructed + N - array size to use + u - the initial value to initialize every element of the array + +.SH Return value + + std::shared_ptr of an instance of type T. + +.SH Exceptions + + Can throw the exceptions thrown from Alloc::allocate() or from the constructor of T. + If an exception is thrown, \fB(1)\fP has no effect. + If an exception is thrown during the construction of the array, already-initialized + elements are destroyed in reverse order + \fI(since C++20)\fP. + +.SH Notes + + Like std::make_shared, this function typically performs only one allocation, and + places both the T object and the control block in the allocated memory block (the + standard recommends but does not require this, all known implementations do this). A + copy of alloc is stored as part of the control block so that it can be used to + deallocate it once both shared and weak reference counts reach zero. + + Unlike the std::shared_ptr constructors, std::allocate_shared does not accept a + separate custom deleter: the supplied allocator is used for destruction of the + control block and the T object, and for deallocation of their shared memory block. + + std::shared_ptr supports array types (as of C++17), but + std::allocate_shared does not. This functionality is supported by \fI(until C++20)\fP + boost::allocate_shared. + + A constructor enables shared_from_this with a pointer ptr of type U* means that it + determines if U has an + unambiguous and accessible + \fI(since C++17)\fP base class that is a specialization of std::enable_shared_from_this, + and if so, the constructor evaluates the statement: + + if (ptr != nullptr && ptr->weak_this.expired()) + ptr->weak_this = std::shared_ptr>( + *this, const_cast*>(ptr)); + + Where weak_this is the hidden mutable std::weak_ptr member of + std::enable_shared_from_this. The assignment to the weak_this member is not atomic + and conflicts with any potentially concurrent access to the same object. This + ensures that future calls to shared_from_this() would share ownership with the + std::shared_ptr created by this raw pointer constructor. + + The test ptr->weak_this.expired() in the exposition code above makes sure that + weak_this is not reassigned if it already indicates an owner. This test is required + as of C++17. + + Feature-test macro Value Std Feature + Smart pointer creation with default + initialization + __cpp_lib_smart_ptr_for_overwrite 202002L (C++20) (std::allocate_shared_for_overwrite, + std::make_shared_for_overwrite, + std::make_unique_for_overwrite); + overloads (6,7) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs new shared_ptr + \fI(public member function)\fP + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::allocate_shared.3 b/man/std::allocate_shared.3 deleted file mode 100644 index 1d0cd437f..000000000 --- a/man/std::allocate_shared.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH std::allocate_shared 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T, class Alloc, class... Args > - shared_ptr allocate_shared( const Alloc& alloc, Args... args ); - - Constructs an object of type T and wraps it in a std::shared_ptr using args as the - parameter list for the constructor of T. - - All memory allocation is done using a copy of alloc, which satisfies the Allocator - requirements. The copy constructor and the destructor of Alloc must not throw - exceptions. - -.SH Parameters - - alloc - The Allocator to use. - args... - list of arguments with which an instance of T will be constructed. - -.SH Return value - - std::shared_ptr of an instance of type T. - -.SH Exceptions - - Can throw the exceptions thrown from Alloc::allocate() or from the constructor of T. - If an exception is thrown, this function has no effect. - -.SH Notes - - This function typically allocates memory for the T object and for the shared_ptr's - control block with a single memory allocation (it is a non-binding requirement in - the Standard). In contrast, the declaration std::shared_ptr p(new T(Args...)) - performs at least two memory allocations, which may incur unnecessary overhead. - - A copy of alloc is stored as part of the control block so that it can be used to - deallocate it once both shared and weak reference counts reach zero. - -.SH See also - - constructor constructs new shared_ptr - \fI(public member function)\fP - make_shared creates a shared pointer that manages a new object - \fI(function template)\fP diff --git a/man/std::allocation_result.3 b/man/std::allocation_result.3 new file mode 100644 index 000000000..24646d71b --- /dev/null +++ b/man/std::allocation_result.3 @@ -0,0 +1,60 @@ +.TH std::allocation_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocation_result \- std::allocation_result + +.SH Synopsis + Defined in header + template< class Pointer, class SizeType = std::size_t > (since C++23) + struct allocation_result; + + allocation_result specializations are returned from the allocate_at_least member + function of appropriate Allocator types (e.g. std::allocator::allocate_at_least) and + std::allocator_traits::allocate_at_least. + + Every specialization of allocation_result has no base classes or declared members + other than ptr and count, thus it is suitable for aggregate initialization and + structured binding. + +.SH Template parameters + + Pointer - typically std::allocator_traits::pointer, where Alloc is an + Allocator type + SizeType - typically std::allocator_traits::size_type, where Alloc is an + Allocator type + + Data members + + Member name Definition + a pointer of type Pointer which is typically used for the address of the + ptr first element in the storage allocated by allocate_at_least + \fI(public member object)\fP + a value of type SizeType which is typically used for the actual number + count of elements in the storage allocated by allocate_at_least + \fI(public member object)\fP + +.SH Notes + + Pointer and SizeType are a pointer to an object type and + std::make_unsigned_t (which is almost always same as std::size_t) by + default. + + Feature-test macro Value Std Feature + __cpp_lib_allocate_at_least 202302L (C++23) Size-feedback in the Allocator interface + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + allocate_at_least allocates uninitialized storage at least as large as requested + (C++23) size + \fI(public member function of std::allocator)\fP + allocates storage at least as large as the requested size via an + allocate_at_least allocator + \fB[static]\fP (C++23) \fI(public static member function of std::allocator_traits)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::allocator.3 b/man/std::allocator.3 index 766172c0e..7affb2abe 100644 --- a/man/std::allocator.3 +++ b/man/std::allocator.3 @@ -1,10 +1,13 @@ -.TH std::allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator \- std::allocator + .SH Synopsis Defined in header template< class T > \fB(1)\fP struct allocator; - template<> \fB(2)\fP - struct allocator; + template<> \fB(2)\fP (deprecated in C++17) + struct allocator; (removed in C++20) The std::allocator class template is the default Allocator used by all standard library containers if no user-specified allocator is provided. The default allocator @@ -12,103 +15,121 @@ compare equal and can deallocate memory allocated by any other instance of the same allocator type. - Specialization for void lacks the member typedefs reference, const_reference, - size_type and difference_type. This specialization declares no member functions. + The explicit specialization for void lacks the member typedefs + reference, const_reference, size_type and difference_type. This \fI(until C++20)\fP + specialization declares no member functions. - All custom allocators also must be stateless. \fI(until C++11)\fP - Custom allocators may contain state. Each container or another - allocator-aware object stores an instance of the supplied allocator \fI(since C++11)\fP - and controls allocator replacement through std::allocator_traits. + The default allocator satisfies allocator completeness requirements. \fI(since C++17)\fP .SH Member types - Type Definition - value_type T - pointer T* - const_pointer const T* - reference T& - const_reference const T& - size_type std::size_t - difference_type std::ptrdiff_t - propagate_on_container_move_assignment\fI(C++14)\fP std::true_type - rebind template< class U > struct rebind { - typedef allocator other; }; + Type Definition + value_type T + pointer (deprecated in C++17)(removed in C++20) T* + const_pointer (deprecated in C++17)(removed in C++20) const T* + reference (deprecated in C++17)(removed in C++20) T& + const_reference (deprecated in C++17)(removed in C++20) const T& + size_type std::size_t + difference_type std::ptrdiff_t + propagate_on_container_move_assignment \fI(C++11)\fP std::true_type + template< class U > + + struct rebind + rebind (deprecated in C++17)(removed in C++20) { + typedef allocator + other; + }; + is_always_equal \fI(C++11)\fP(deprecated in C++23)(removed in std::true_type + C++26) .SH Member functions - constructor creates a new allocator instance - \fI(public member function)\fP - destructor destructs an allocator instance - \fI(public member function)\fP - address obtains the address of an object, even if operator& is overloaded - \fI(public member function)\fP - allocate allocates uninitialized storage - \fI(public member function)\fP - deallocate deallocates storage - \fI(public member function)\fP - max_size returns the largest supported allocation size - \fI(public member function)\fP - construct constructs an object in allocated storage - \fI(public member function)\fP - destroy destructs an object in allocated storage - \fI(public member function)\fP + constructor creates a new allocator instance + \fI(public member function)\fP + destructor destructs an allocator instance + \fI(public member function)\fP + address obtains the address of an object, even if operator& is overloaded + \fI(until C++20)\fP \fI(public member function)\fP + allocate allocates uninitialized storage + \fI(public member function)\fP + allocate_at_least allocates uninitialized storage at least as large as requested + (C++23) size + \fI(public member function)\fP + deallocate deallocates storage + \fI(public member function)\fP + max_size returns the largest supported allocation size + \fI(until C++20)\fP \fI(public member function)\fP + construct constructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function)\fP + destroy destructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two allocator instances - operator!= \fI(public member function)\fP + operator== compares two allocator instances + operator!= \fI(public member function)\fP + (removed in C++20) .SH Notes The member template class rebind provides a way to obtain an allocator for a - different type. For example, - - std::list allocates nodes of some internal type Node, using \fI(until C++11)\fP - the allocator A::rebind>::other - std::list allocates nodes of some internal type Node, using - the allocator std::allocator_traits::rebind_alloc>, which \fI(since C++11)\fP - is implemented in terms of A::rebind>::other if A is an - std::allocator + different type. For example, std::list allocates nodes of some internal type + Node, using the allocator + A::rebind>::other + \fI(until C++11)\fP + std::allocator_traits::rebind_alloc>, which is implemented in terms of + A::rebind>::other if A is an std::allocator + \fI(since C++11)\fP. + + Member type is_always_equal is deprecated via LWG issue 3170, because it makes + custom allocators derived from std::allocator treated as always equal by default. + std::allocator_traits>::is_always_equal is not deprecated and its + member constant value is true for any T. .SH Example - + // Run this code - #include #include + #include #include - + int main() { - std::allocator a1; // default allocator for ints - int* a = a1.allocate(10); // space for 10 ints - - a[9] = 7; - - std::cout << a[9] << '\\n'; - - a1.deallocate(a, 10); - + // default allocator for ints + std::allocator alloc1; + + // demonstrating the few directly usable members + static_assert(std::is_same_v); + int* p1 = alloc1.allocate(1); // space for one int + alloc1.deallocate(p1, 1); // and it is gone + + // Even those can be used through traits though, so no need + using traits_t1 = std::allocator_traits; // The matching trait + p1 = traits_t1::allocate(alloc1, 1); + traits_t1::construct(alloc1, p1, 7); // construct the int + std::cout << *p1 << '\\n'; + traits_t1::deallocate(alloc1, p1, 1); // deallocate space for one int + // default allocator for strings - // std::allocator a2; - - // same, but obtained by rebinding from the type of a1 - // decltype(a1)::rebind::other a2; - - // same, but obtained by rebinding from the type of a1 via allocator_traits - std::allocator_traits::rebind_alloc a2; - - std::string* s = a2.allocate(2); // space for 2 string - - a2.construct(s, "foo"); - a2.construct(s + 1, "bar"); - - std::cout << s[0] << ' ' << s[1] << '\\n'; - - a2.destroy(s); - a2.destroy(s + 1); - a2.deallocate(s, 2); + std::allocator alloc2; + // matching traits + using traits_t2 = std::allocator_traits; + + // Rebinding the allocator using the trait for strings gets the same type + traits_t2::rebind_alloc alloc_ = alloc2; + + std::string* p2 = traits_t2::allocate(alloc2, 2); // space for 2 strings + + traits_t2::construct(alloc2, p2, "foo"); + traits_t2::construct(alloc2, p2 + 1, "bar"); + + std::cout << p2[0] << ' ' << p2[1] << '\\n'; + + traits_t2::destroy(alloc2, p2 + 1); + traits_t2::destroy(alloc2, p2); + traits_t2::deallocate(alloc2, p2, 2); } .SH Output: @@ -116,12 +137,24 @@ 7 foo bar + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + redundant comparison propagate_on_container_move_assignment + LWG 2103 C++11 between allocator might provided + be required + LWG 2108 C++11 there was no way to show is_always_equal provided + allocator is stateless + .SH See also allocator_traits provides information about allocator types - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP scoped_allocator_adaptor implements multi-level allocator for multi-level containers - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP uses_allocator checks if the specified type supports uses-allocator \fI(C++11)\fP construction - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::allocator::address.3 b/man/std::allocator::address.3 index d5cb8be97..4b586224d 100644 --- a/man/std::allocator::address.3 +++ b/man/std::allocator::address.3 @@ -1,7 +1,19 @@ -.TH std::allocator::address 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::address 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::address \- std::allocator::address + .SH Synopsis - pointer address( reference x ) const; - const_pointer address( const_reference x ) const; + pointer address( reference x ) \fI(until C++11)\fP + const; + pointer address( reference x ) \fI(since C++11)\fP + const noexcept; (deprecated in C++17) + (removed in C++20) + const_pointer address( \fB(1)\fP \fI(until C++11)\fP + const_reference x ) const; + const_pointer address( \fB(2)\fP \fI(since C++11)\fP + const_reference x ) const (deprecated in + noexcept; C++17) + (removed in C++20) Returns the actual address of x even in presence of overloaded operator&. @@ -13,9 +25,12 @@ The actual address of x. -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + DR Applied to Behavior as published Correct behavior + LWG 634 the return value is &x returns the actual address + (N2436) C++98 (which is affected by overloaded of x + operator&) diff --git a/man/std::allocator::allocate.3 b/man/std::allocator::allocate.3 index 38af5dfb1..c82180661 100644 --- a/man/std::allocator::allocate.3 +++ b/man/std::allocator::allocate.3 @@ -1,13 +1,35 @@ -.TH std::allocator::allocate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::allocate \- std::allocator::allocate + .SH Synopsis - pointer allocate( size_type n, std::allocator::const_pointer hint = 0 ); + pointer allocate( size_type n, const void* \fI(until C++17)\fP + hint = 0 ); + T* allocate( std::size_t n, const void* \fI(since C++17)\fP + hint ); \fB(deprecated)\fP + \fB(1)\fP (removed in C++20) + T* allocate( std::size_t n ); \fI(since C++17)\fP + \fB(2)\fP \fI(until C++20)\fP + [[nodiscard]] constexpr T* allocate( \fI(since C++20)\fP + std::size_t n ); Allocates n * sizeof(T) bytes of uninitialized storage by calling ::operator - new(std::size_t), but it is unspecified when and how this function is called. The + new(std::size_t) + or ::operator new(std::size_t, std::align_val_t) + \fI(since C++17)\fP, but it is unspecified when and how this function is called. The pointer hint may be used to provide locality of reference: the allocator, if supported by the implementation, will attempt to allocate the new memory block as close as possible to hint. + Then, this function creates an array of type T[n] in the storage and starts its + lifetime, but does not start lifetime of any of its elements. + + Use of this function is ill-formed if T is an incomplete type. + + In order to use this function in a constant expression, the allocated + storage must be deallocated within the evaluation of the same \fI(since C++20)\fP + expression. + .SH Parameters n - the number of objects to allocate storage for @@ -15,14 +37,43 @@ .SH Return value - Pointer to the first byte of a memory block suitably aligned and sufficient to hold - an array of n objects of type T. + Pointer to the first element of an array of n objects of type T whose elements have + not been constructed yet. .SH Exceptions + Throws std::bad_array_new_length if \fI(since C++11)\fP + std::numeric_limits::max() / sizeof(T) < n. + Throws std::bad_alloc if allocation fails. +.SH Notes + + The "unspecified when and how" wording makes it possible to combine or optimize away + heap allocations made by the standard library containers, even though such + optimizations are disallowed for direct calls to ::operator new. For example, this + is implemented by libc++ ([1] and [2]). + + After calling allocate() and before construction of elements, pointer arithmetic of + T* is well-defined within the allocated array, but the behavior is undefined if + elements are accessed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + hint was required to be either + 0 or a + LWG 578 C++98 pointer previously returned not required + from allocate() + and not yet passed to + deallocate() + LWG 3190 C++11 allocate() might allocate throws std::bad_array_new_length + storage of wrong size instead + .SH See also allocate allocates uninitialized storage using the allocator - \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP diff --git a/man/std::allocator::allocate_at_least.3 b/man/std::allocator::allocate_at_least.3 new file mode 100644 index 000000000..2e6a40351 --- /dev/null +++ b/man/std::allocator::allocate_at_least.3 @@ -0,0 +1,90 @@ +.TH std::allocator::allocate_at_least 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::allocate_at_least \- std::allocator::allocate_at_least + +.SH Synopsis + [[nodiscard]] constexpr std::allocation_result (since C++23) + allocate_at_least( std::size_t n ); + + Allocates count * sizeof(T) bytes of uninitialized storage, where count is an + unspecified integer value not less than n, by calling ::operator new (an additional + std::align_val_t argument might be provided), but it is unspecified when and how + this function is called. + + Then, this function creates an array of type T[count] in the storage and starts its + lifetime, but does not start lifetime of any of its elements. + + In order to use this function in a constant expression, the allocated storage must + be deallocated within the evaluation of the same expression. + + Use of this function is ill-formed if T is an incomplete type. + +.SH Parameters + + n - the lower bound of number of objects to allocate storage for + +.SH Return value + + std::allocation_result{p, count}, where p points to the first element of an + array of count objects of type T whose elements have not been constructed yet. + +.SH Exceptions + + Throws std::bad_array_new_length if std::numeric_limits::max() / + sizeof(T) < n, or std::bad_alloc if allocation fails. + +.SH Notes + + allocate_at_least is mainly provided for contiguous containers, e.g. std::vector and + std::basic_string, in order to reduce reallocation by making their capacity match + the actually allocated size when possible. + + The "unspecified when and how" wording makes it possible to combine or optimize away + heap allocations made by the standard library containers, even though such + optimizations are disallowed for direct calls to ::operator new. For example, this + is implemented by libc++ ([1] and [2]). + + After calling allocate_at_least and before construction of elements, pointer + arithmetic of T* is well-defined within the allocated array, but the behavior is + undefined if elements are accessed. + + Feature-test macro Value Std Feature + __cpp_lib_allocate_at_least 202302L (C++23) allocate_at_least etc. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::size_t count{69}; + std::allocator alloc; + std::allocation_result res{alloc.allocate_at_least(count)}; + std::print("count: {}\\n" + "res.ptr: {}\\n" + "res.count: {}\\n", count, res.ptr, res.count); + + /* construct, use, then destroy elements */ + + alloc.deallocate(res.ptr, res.count); + } + +.SH Possible output: + + count: 69 + res.ptr: 0x555a486a0960 + res.count: 96 + +.SH See also + + allocation_result records the address and the actual size of storage allocated by + (C++23) allocate_at_least + \fI(class template)\fP + allocates storage at least as large as the requested size via an + allocate_at_least allocator + \fB[static]\fP (C++23) \fI(public static member function of std::allocator_traits)\fP + diff --git a/man/std::allocator::allocator.3 b/man/std::allocator::allocator.3 index 4da3d3ac1..217d7e8e3 100644 --- a/man/std::allocator::allocator.3 +++ b/man/std::allocator::allocator.3 @@ -1,9 +1,27 @@ -.TH std::allocator::allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::allocator \- std::allocator::allocator + .SH Synopsis - allocator(); \fB(1)\fP - allocator( const allocator& other ); \fB(2)\fP - template< class U > \fB(3)\fP - allocator( const allocator& other ); + allocator() throw(); \fI(until C++11)\fP + allocator() noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + constexpr allocator() noexcept; \fI(since C++20)\fP + allocator( const allocator& other \fI(until C++11)\fP + ) throw(); + allocator( const allocator& other \fI(since C++11)\fP + ) noexcept; \fI(until C++20)\fP + constexpr allocator( const \fI(since C++20)\fP + allocator& other ) noexcept; \fB(1)\fP + template< class U > + allocator( const allocator& \fB(2)\fP \fI(until C++11)\fP + other ) throw(); + template< class U > \fI(since C++11)\fP + allocator( const allocator& \fB(3)\fP \fI(until C++20)\fP + other ) noexcept; + template< class U > + constexpr allocator( const \fI(since C++20)\fP + allocator& other ) noexcept; Constructs the default allocator. Since the default allocator is stateless, the constructors have no visible effect. diff --git a/man/std::allocator::construct.3 b/man/std::allocator::construct.3 index e631491ed..cf0fa2ec7 100644 --- a/man/std::allocator::construct.3 +++ b/man/std::allocator::construct.3 @@ -1,16 +1,19 @@ -.TH std::allocator::construct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::construct \- std::allocator::construct + .SH Synopsis Defined in header - void construct( pointer p, const_reference val ); \fI(until C++11)\fP - template< class U, class... Args > \fI(since C++11)\fP - void construct( U* p, Args&&... args ); + void construct( pointer p, const_reference val ); \fB(1)\fP \fI(until C++11)\fP + template< class U, class... Args > \fI(since C++11)\fP + void construct( U* p, Args&&... args ); \fB(2)\fP (deprecated in C++17) + (removed in C++20) Constructs an object of type T in allocated uninitialized storage pointed to by p, - using placement-new - - 1) Calls new((void *)p) T(val) + using global placement-new. - 2) Calls ::new((void *)p) U(std::forward(args)...) + 1) Calls ::new((void*)p) T(val). + 2) Calls ::new((void*)p) U(std::forward(args)...). .SH Parameters @@ -22,9 +25,20 @@ \fI(none)\fP + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 402 C++98 if T::operator new exists, the uses global replacement-new + program might be ill-formed instead + .SH See also construct constructs an object in the allocated storage - \fB[static]\fP \fI(function template)\fP + \fB[static]\fP \fI(function template)\fP + construct_at creates an object at a given address + (C++20) \fI(function template)\fP operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP diff --git a/man/std::allocator::deallocate.3 b/man/std::allocator::deallocate.3 index f4a89f6f4..642d55ea6 100644 --- a/man/std::allocator::deallocate.3 +++ b/man/std::allocator::deallocate.3 @@ -1,26 +1,106 @@ -.TH std::allocator::deallocate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::deallocate \- std::allocator::deallocate + .SH Synopsis - Defined in header - void deallocate( pointer p, size_type n ); + void deallocate( T* p, std::size_t n ); (constexpr since C++20) Deallocates the storage referenced by the pointer p, which must be a pointer - obtained by an earlier call to allocate(). The argument n must be equal to the first - argument of the call to allocate() that originally produced p. + obtained by an earlier call to allocate() + or allocate_at_least() + (since C++23). + + The argument n must be equal to the first argument of the call to allocate() that + originally produced p + , or in the range [m, count] if p is obtained from a call to allocate_at_least(m) + which returned {p, count} + (since C++23); otherwise, the behavior is undefined. + + Calls ::operator delete(void*) + or ::operator delete(void*, std::align_val_t) + \fI(since C++17)\fP, but it is unspecified when and how it is called. - Calls ::operator delete(void*), but it is unspecified when and how it is called. + In evaluation of a constant expression, this function must deallocate \fI(since C++20)\fP + storage allocated within the evaluation of the same expression. .SH Parameters - p - pointer obtained from allocate() - n - number of objects earlier passed to allocate() + pointer obtained from allocate() + p - or allocate_at_least() + (since C++23) + number of objects earlier passed to allocate() + n - , or a number between requested and actually allocated number of objects via + allocate_at_least() (may be equal to either bound) + (since C++23) .SH Return value \fI(none)\fP +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + class S + { + inline static int n{1}; + int m{}; + void pre() const { std::cout << "#" << m << std::string(m, ' '); } + public: + S(int x) : m{n++} { pre(); std::cout << "S::S(" << x << ");\\n"; } + ~S() { pre(); std::cout << "S::~S();\\n"; } + void id() const { pre(); std::cout << "S::id();\\n"; } + }; + + int main() + { + constexpr std::size_t n{4}; + std::allocator allocator; + try + { + S* s = allocator.allocate(n); // may throw + for (std::size_t i{}; i != n; ++i) + { + // allocator.construct(&s[i], i + 42); // removed in C++20 + std::construct_at(&s[i], i + 42); // since C++20 + } + std::for_each_n(s, n, [](const auto& e) { e.id(); }); + std::destroy_n(s, n); + allocator.deallocate(s, n); + } + catch (std::bad_array_new_length const& ex) { std::cout << ex.what() << '\\n'; } + catch (std::bad_alloc const& ex) { std::cout << ex.what() << '\\n'; } + } + +.SH Output: + + #1 S::S\fB(42)\fP; + #2 S::S(43); + #3 S::S(44); + #4 S::S(45); + #1 S::id(); + #2 S::id(); + #3 S::id(); + #4 S::id(); + #1 S::~S(); + #2 S::~S(); + #3 S::~S(); + #4 S::~S(); + .SH See also - allocate allocates uninitialized storage - \fI(public member function)\fP - deallocate deallocates storage using the allocator - \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + allocate allocates uninitialized storage + \fI(public member function)\fP + allocate_at_least allocates uninitialized storage at least as large as requested + (C++23) size + \fI(public member function)\fP + deallocate deallocates storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + diff --git a/man/std::allocator::destroy.3 b/man/std::allocator::destroy.3 index bf868521b..b2cca8733 100644 --- a/man/std::allocator::destroy.3 +++ b/man/std::allocator::destroy.3 @@ -1,14 +1,18 @@ -.TH std::allocator::destroy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::destroy \- std::allocator::destroy + .SH Synopsis Defined in header - void destroy( pointer p ); \fI(until C++11)\fP - template< class U > \fI(since C++11)\fP - void destroy( U* p ); + void destroy( pointer p ); \fB(1)\fP \fI(until C++11)\fP + template< class U > \fI(since C++11)\fP + void destroy( U* p ); \fB(2)\fP (deprecated in C++17) + (removed in C++20) - Calls the destructor of the object pointed to by p + Calls the destructor of the object pointed to by p. - 1) Calls ((T*)p)->~T() - 2) Calls p->~U() + 1) Calls p->~T(). + 2) Calls p->~U(). .SH Parameters @@ -18,7 +22,16 @@ \fI(none)\fP + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 400 C++98 p was cast to T*, which is the type of removed the redundant cast + p + .SH See also destroy destructs an object stored in the allocated storage - \fB[static]\fP \fI(function template)\fP + \fB[static]\fP \fI(function template)\fP diff --git a/man/std::allocator::max_size.3 b/man/std::allocator::max_size.3 index 24453f4eb..c1a0285d4 100644 --- a/man/std::allocator::max_size.3 +++ b/man/std::allocator::max_size.3 @@ -1,12 +1,18 @@ -.TH std::allocator::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::max_size \- std::allocator::max_size + .SH Synopsis - Defined in header - size_type max_size() const + size_type max_size() const throw(); \fI(until C++11)\fP + \fI(since C++11)\fP + size_type max_size() const noexcept; (deprecated in C++17) + (removed in C++20) Returns the maximum theoretically possible value of n, for which the call allocate(n, 0) could succeed. - In most implementations, this returns std::numeric_limits::max(). + In most implementations, this returns std::numeric_limits::max() / + sizeof(value_type). .SH Parameters @@ -14,16 +20,9 @@ .SH Return value - The maximum supported allocation size - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + The maximum supported allocation size. .SH See also max_size returns the maximum object size supported by the allocator - \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP diff --git a/man/std::allocator::~allocator.3 b/man/std::allocator::~allocator.3 index d316838ff..73737722b 100644 --- a/man/std::allocator::~allocator.3 +++ b/man/std::allocator::~allocator.3 @@ -1,5 +1,9 @@ -.TH std::allocator::~allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator::~allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator::~allocator \- std::allocator::~allocator + .SH Synopsis - ~allocator(); + ~allocator(); \fI(until C++20)\fP + constexpr ~allocator(); \fI(since C++20)\fP Destroys the default allocator. diff --git a/man/std::allocator_arg.3 b/man/std::allocator_arg.3 index 430ba67a1..30f8c6419 100644 --- a/man/std::allocator_arg.3 +++ b/man/std::allocator_arg.3 @@ -1,17 +1,30 @@ -.TH std::allocator_arg 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_arg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_arg \- std::allocator_arg + .SH Synopsis Defined in header + struct allocator_arg_t { explicit allocator_arg_t() = default; }; \fI(since C++11)\fP constexpr std::allocator_arg_t allocator_arg = \fI(since C++11)\fP + std::allocator_arg_t(); \fI(until C++17)\fP + inline constexpr std::allocator_arg_t allocator_arg = \fI(since C++17)\fP std::allocator_arg_t(); - std::allocator_arg is a constant of type std::allocator_arg_t used to disambiguate, - at call site, the overloads of the constructors and member functions of - allocator-aware objects, such as std::tuple, std::function, std::promise, and - std::packaged_task. + std::allocator_arg_t is an empty class type used to disambiguate the overloads of + constructors and member functions of allocator-aware objects, including std::tuple + , std::function, std::packaged_task, + \fI(until C++17)\fP and std::promise. std::allocator_arg is a constant of it. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2510 C++11 the default constructor was non-explicit, which made explicit + could lead to ambiguity .SH See also - allocator_arg_t tag type used to select allocator-aware constructor overloads - \fI(C++11)\fP \fI(class)\fP - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::allocator_arg_t.3 b/man/std::allocator_arg_t.3 deleted file mode 100644 index 8886ac716..000000000 --- a/man/std::allocator_arg_t.3 +++ /dev/null @@ -1,16 +0,0 @@ -.TH std::allocator_arg_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - struct allocator_arg_t {}; \fI(since C++11)\fP - - std::allocator_arg_t is an empty class type used to disambiguate the overloads of - constructors and member functions of allocator-aware objects, including std::tuple, - std::function, std::promise, and std::packaged_task. - -.SH See also - - allocator_arg an object of type std::allocator_arg_t used to select allocator-aware - \fI(C++11)\fP constructors - (constant) - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::allocator_traits.3 b/man/std::allocator_traits.3 index 8ea49a3c0..6fc0484fb 100644 --- a/man/std::allocator_traits.3 +++ b/man/std::allocator_traits.3 @@ -1,16 +1,22 @@ -.TH std::allocator_traits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits \- std::allocator_traits + .SH Synopsis Defined in header template< class Alloc > \fI(since C++11)\fP struct allocator_traits; The allocator_traits class template provides the standardized way to access various - properties of allocators. The standard containers and other standard library + properties of Allocators. The standard containers and other standard library components access allocators through this template, which makes it possible to use any class type as an allocator, as long as the user-provided specialization of - allocator_traits implements all required functionality. + std::allocator_traits implements all required functionality. + + A program that declares an explicit or partial specialization of (since C++23) + std::allocator_traits is ill-formed, no diagnostic required. - The default, non-specialized, allocator_traits contains the following members: + The default, non-specialized, std::allocator_traits contains the following members: .SH Member types @@ -38,38 +44,56 @@ if present, otherwise std::false_type propagate_on_container_swap Alloc::propagate_on_container_swap if present, otherwise std::false_type + is_always_equal Alloc::is_always_equal if present, otherwise + std::is_empty::type .SH Member alias templates Type Definition - rebind_alloc Alloc::rebind::other if present, otherwise Alloc if - this Alloc is Alloc + Alloc::rebind::other if present, otherwise SomeAllocator Args> if this Alloc is of the form SomeAllocator, where + Args is zero or more type arguments rebind_traits std::allocator_traits> .SH Member functions allocate allocates uninitialized storage using the \fB[static]\fP allocator - \fI(public static member function)\fP + \fI(public static member function)\fP + allocate_at_least allocates storage at least as large as the + \fB[static]\fP (C++23) requested size via an allocator + \fI(public static member function)\fP deallocate deallocates storage using the allocator - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP construct constructs an object in the allocated storage - \fB[static]\fP \fI(function template)\fP + \fB[static]\fP \fI(function template)\fP destroy destructs an object stored in the allocated \fB[static]\fP storage - \fI(function template)\fP + \fI(function template)\fP max_size returns the maximum object size supported by \fB[static]\fP the allocator - \fI(public static member function)\fP + \fI(public static member function)\fP select_on_container_copy_construction obtains the allocator to use after copying a \fB[static]\fP standard container - \fI(public static member function)\fP + \fI(public static member function)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2108 C++11 there was no way to show an allocator is_always_equal provided + is stateless .SH See also + AllocatorAwareContainer container using allocator; associated traits (e.g. + \fI(C++11)\fP propagate_on_container_swap) usage + (named requirement) allocator the default allocator - \fI(class template)\fP + \fI(class template)\fP scoped_allocator_adaptor implements multi-level allocator for multi-level containers - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP pointer_traits provides information about pointer-like types - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::allocator_traits::allocate.3 b/man/std::allocator_traits::allocate.3 index 80f5abf8a..d826e64c6 100644 --- a/man/std::allocator_traits::allocate.3 +++ b/man/std::allocator_traits::allocate.3 @@ -1,17 +1,29 @@ -.TH std::allocator_traits::allocate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::allocate \- std::allocator_traits::allocate + .SH Synopsis Defined in header - static pointer allocate( Alloc& a, size_type n ); \fB(1)\fP \fI(since C++11)\fP - static pointer allocate( Alloc& a, size_type n, const_void_pointer \fB(2)\fP \fI(since C++11)\fP - hint ); - - Uses the allocator a to allocate n*sizeof(Alloc::value_type) bytes of uninitialized - storage. - - 1) Calls a.allocate(n) + static pointer allocate( Alloc& a, size_type n \fI(since C++11)\fP + ); \fI(until C++20)\fP + [[nodiscard]] static constexpr pointer allocate( \fI(since C++20)\fP + Alloc& a, size_type n ); + static pointer allocate( Alloc& a, size_type n, \fI(since C++11)\fP + const_void_pointer hint \fB(1)\fP \fI(until C++20)\fP + ); + [[nodiscard]] static constexpr pointer allocate( \fB(2)\fP + Alloc& a, size_type n, \fI(since C++20)\fP + + const_void_pointer hint ); + + Uses the allocator a to allocate n * sizeof(Alloc::value_type) bytes of + uninitialized storage. An array of type Alloc::value_type[n] is created in the + storage, but none of its elements are constructed. + + 1) Calls a.allocate(n). 2) Additionally passes memory locality hint hint. Calls a.allocate(n, hint) if - possible. If not possible (e.g. a has no two-argument member function allocate()), - calls a.allocate(n) + possible. If not possible (e.g. a has no two-argument member function allocate), + calls a.allocate(n). .SH Parameters @@ -21,9 +33,27 @@ .SH Return value - The pointer returned by the call to a.allocate(n) + The pointer returned by the call to a.allocate(n). + +.SH Notes + + Alloc::allocate was not required to create array object until P0593R6, which made + using non-default allocator for std::vector and some other containers not + well-defined according to a strict reading of the core language specification. + + After calling allocate and before construction of elements, pointer arithmetic of + Alloc::value_type* is well-defined within the allocated array, but the behavior is + undefined if elements are accessed. + +.SH Example + + This section is incomplete + Reason: no example .SH See also allocate allocates uninitialized storage - \fI(public member function of std::allocator)\fP + \fI(public member function of std::allocator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::allocator_traits::allocate_at_least.3 b/man/std::allocator_traits::allocate_at_least.3 new file mode 100644 index 000000000..39432b3e3 --- /dev/null +++ b/man/std::allocator_traits::allocate_at_least.3 @@ -0,0 +1,65 @@ +.TH std::allocator_traits::allocate_at_least 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::allocate_at_least \- std::allocator_traits::allocate_at_least + +.SH Synopsis + [[nodiscard]] static constexpr std::allocation_result (since C++23) + allocate_at_least( Alloc& a, size_type n ); + + allocate_at_least calls a.allocate_at_least(n) and returns its result if the call is + well-formed, otherwise, it is equivalent to return {a.allocate(n), n};. + + allocator_at_least tries to allocate a storage for at least n value_type objects, + and provides a fallback mechanism that allocates a storage for exact n objects. + +.SH Parameters + + a - an allocator used for allocating storage + n - the lower bound of number of objects to allocate storage for + +.SH Return value + + a.allocate_at_least(n) if it is well-formed. + + Otherwise, std::allocation_result{a.allocate(n), n}. + +.SH Exceptions + + Throws what and when the selected allocation function throws. + +.SH Notes + + The allocate_at_least member function of Allocator types are mainly provided for + contiguous containers, e.g. std::vector and std::basic_string, in order to reduce + reallocation by making their capacity match the actually allocated size when + possible. Because allocate_at_least provides a fallback mechanism, it can be + directly used where appropriate. + + Given an allocator object a of type Alloc, let result denote the value returned from + std::allocator_traits::allocate_at_least(a, n), the storage should be + deallocated by a.deallocate(result.ptr, m) (typically called via + std::allocator_traits::deallocate(a, result.ptr, m)) in order to avoid memory + leak. + + The argument m used in deallocation must be not less than n and not greater than + result.count, otherwise, the behavior is undefined. Note that n is always equal to + result.count if the allocator does not provide allocate_at_least, which means that m + is required to be equal to n. + + Feature-test macro Value Std Feature + __cpp_lib_allocate_at_least 202302L (C++23) allocate_at_least etc. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + allocate_at_least allocates uninitialized storage at least as large as requested + (C++23) size + \fI(public member function of std::allocator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::allocator_traits::construct.3 b/man/std::allocator_traits::construct.3 index ea028299f..63897803b 100644 --- a/man/std::allocator_traits::construct.3 +++ b/man/std::allocator_traits::construct.3 @@ -1,23 +1,33 @@ -.TH std::allocator_traits::construct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits::construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::construct \- std::allocator_traits::construct + .SH Synopsis Defined in header - template< class T, class... Args > \fI(since C++11)\fP - static void construct( Alloc& a, T* p, Args&&... args ); + template< class T, class... Args > \fI(since C++11)\fP + static void construct( Alloc& a, T* p, Args&&... args ); \fI(until C++20)\fP + template< class T, class... Args > \fI(since C++20)\fP + static constexpr void construct( Alloc& a, T* p, Args&&... args ); If possible, constructs an object of type T in allocated uninitialized storage - pointed to by p, by calling - - a.construct(p, std::forward(args)...) + pointed to by p, by calling a.construct(p, std::forward(args)...). - If the above is not possible (e.g. a does not have the member function - construct(),), then calls placement-new as + If the above is not possible (e.g. Alloc does not have the member function + construct()), then calls - ::new (static_cast(p)) T(std::forward(args)...) + ::new (static_cast(p)) T(std::forward(args)...) \fI(until C++20)\fP + std::construct_at(p, std::forward(args)...) \fI(since C++20)\fP .SH Parameters a - allocator to use for construction - args... - the constructor arguments to pass to a.construct() or to placement-new + p - pointer to the uninitialized storage on which a T object will be + constructed + the constructor arguments to pass to a.construct() or to + placement-new + args... - \fI(until C++20)\fP + std::construct_at() + \fI(since C++20)\fP .SH Return value @@ -34,6 +44,8 @@ .SH See also operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP construct constructs an object in allocated storage - \fI(public member function of std::allocator)\fP + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP + construct_at creates an object at a given address + (C++20) \fI(function template)\fP diff --git a/man/std::allocator_traits::deallocate.3 b/man/std::allocator_traits::deallocate.3 index b53b7414b..0bcf08130 100644 --- a/man/std::allocator_traits::deallocate.3 +++ b/man/std::allocator_traits::deallocate.3 @@ -1,10 +1,15 @@ -.TH std::allocator_traits::deallocate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::deallocate \- std::allocator_traits::deallocate + .SH Synopsis Defined in header - static void deallocate( Alloc& a, pointer p, size_type n ); \fI(since C++11)\fP + static void deallocate( Alloc& a, pointer p, size_type n ); \fI(since C++11)\fP + \fI(until C++20)\fP + static constexpr void deallocate( Alloc& a, pointer p, size_type n ); \fI(since C++20)\fP Uses the allocator a to deallocate the storage referenced by p, by calling - a.deallocate(p, n) + a.deallocate(p, n). .SH Parameters @@ -16,9 +21,17 @@ \fI(none)\fP +.SH Example + + This section is incomplete + Reason: no example + .SH See also allocate allocates uninitialized storage using the allocator - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP deallocate deallocates storage - \fI(public member function of std::allocator)\fP + \fI(public member function of std::allocator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::allocator_traits::destroy.3 b/man/std::allocator_traits::destroy.3 index b2b30ab04..8d6f5e969 100644 --- a/man/std::allocator_traits::destroy.3 +++ b/man/std::allocator_traits::destroy.3 @@ -1,12 +1,21 @@ -.TH std::allocator_traits::destroy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::destroy \- std::allocator_traits::destroy + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - static void destroy( Alloc& a, T* p ); + template< class T > \fI(since C++11)\fP + static void destroy( Alloc& a, T* p ); \fI(until C++20)\fP + template< class T > \fI(since C++20)\fP + static constexpr void destroy( Alloc& a, T* p ); Calls the destructor of the object pointed to by p. If possible, does so by calling - a.destroy(p). If not possible (e.g. a does not have the member function destroy(), - then calls the destructor of *p directly, as p->~T(). + a.destroy(p). If not possible (e.g. Alloc does not have the member function + destroy()), then calls + the destructor of *p directly, as p->~T() + \fI(until C++20)\fP + std::destroy_at(p) + \fI(since C++20)\fP. .SH Parameters @@ -23,7 +32,15 @@ destructor, the member function destroy() is an optional Allocator requirement since C++11. +.SH Example + + This section is incomplete + Reason: no example + .SH See also - destroy destructs an object in allocated storage - \fI(public member function of std::allocator)\fP + destroy destructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::allocator_traits::max_size.3 b/man/std::allocator_traits::max_size.3 index 442717242..6754ff51c 100644 --- a/man/std::allocator_traits::max_size.3 +++ b/man/std::allocator_traits::max_size.3 @@ -1,33 +1,39 @@ -.TH std::allocator_traits::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::max_size \- std::allocator_traits::max_size + .SH Synopsis Defined in header - static size_type max_size( const Alloc& a ) \fI(since C++11)\fP + static size_type max_size( const Alloc& a ) noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + static constexpr size_type max_size( const Alloc& a ) noexcept; \fI(since C++20)\fP If possible, obtains the maximum theoretically possible allocation size from the - allocator a, by calling - - a.max_size() + allocator a, by calling a.max_size(). - If the above is not possible (e.g. a does not have the member function max_size(),), - then returns - - std::numeric_limits::max() + If the above is not possible (e.g. Alloc does not have the member function + max_size()), then returns std::numeric_limits::max() / + sizeof(value_type). .SH Parameters - \fI(none)\fP + a - allocator to detect .SH Return value - Theoretical maximum allocation size + Theoretical maximum allocation size. + + Defect reports -.SH Exceptions + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + LWG 2162 C++11 max_size was not requied to be noexcept required + LWG 2466 C++11 theoretical maximum allocation size in bytes size in elements is + was returned as fallback returned .SH See also - max_size returns the largest supported allocation size - \fI(public member function of std::allocator)\fP + max_size returns the largest supported allocation size + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP diff --git a/man/std::allocator_traits::select_on_container_copy_construction.3 b/man/std::allocator_traits::select_on_container_copy_construction.3 index d3911bb55..dd7d380a4 100644 --- a/man/std::allocator_traits::select_on_container_copy_construction.3 +++ b/man/std::allocator_traits::select_on_container_copy_construction.3 @@ -1,12 +1,18 @@ -.TH std::allocator_traits::select_on_container_copy_construction 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::allocator_traits::select_on_container_copy_construction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::allocator_traits::select_on_container_copy_construction \- std::allocator_traits::select_on_container_copy_construction + .SH Synopsis Defined in header - static Alloc select_on_container_copy_construction( const Alloc& a ) \fI(since C++11)\fP + static Alloc select_on_container_copy_construction( const Alloc& a ); \fI(since C++11)\fP + \fI(until C++20)\fP + static constexpr Alloc select_on_container_copy_construction( const \fI(since C++20)\fP + Alloc& a ); If possible, obtains the copy-constructed version of the allocator a, by calling - a.select_on_container_copy_construction(). If the above is not possible (e.g. a does - not have the member function select_on_container_copy_construction(), then returns - a, unmodified. + a.select_on_container_copy_construction(). If the above is not possible (e.g. Alloc + does not have the member function select_on_container_copy_construction()), then + returns a, unmodified. This function is called by the copy constructors of all standard library containers. It allows the allocator used by the constructor's argument to become aware that the @@ -23,7 +29,8 @@ .SH See also - copies the state of scoped_allocator_adaptor - select_on_container_copy_construction and all its allocators - \fI\fI(public member\fP function of\fP - std::scoped_allocator_adaptor) + copies the state of scoped_allocator_adaptor and all its + allocators +select_on_container_copy_construction \fI\fI(public member\fP function of\fP + std::scoped_allocator_adaptor) + diff --git a/man/std::any.3 b/man/std::any.3 new file mode 100644 index 000000000..3e9a77dc8 --- /dev/null +++ b/man/std::any.3 @@ -0,0 +1,133 @@ +.TH std::any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any \- std::any + +.SH Synopsis + Defined in header + class any; \fI(since C++17)\fP + + The class any describes a type-safe container for single values of any copy + constructible type. + + 1) An object of class any stores an instance of any type that satisfies the + constructor requirements or is empty, and this is referred to as the state of the + class any object. The stored instance is called the contained object. Two states are + equivalent if they are either both empty or if both are not empty and if the + contained objects are equivalent. + 2) The non-member any_cast functions provide type-safe access to the contained + object. + + Implementations are encouraged to avoid dynamic allocations for small objects, but + such an optimization may only be applied to types for which + std::is_nothrow_move_constructible returns true. + +.SH Member functions + + constructor constructs an any object + \fI(public member function)\fP + operator= assigns an any object + \fI(public member function)\fP + destructor destroys an any object + \fI(public member function)\fP +.SH Modifiers + emplace change the contained object, constructing the new object directly + \fI(public member function)\fP + reset destroys contained object + \fI(public member function)\fP + swap swaps two any objects + \fI(public member function)\fP +.SH Observers + has_value checks if object holds a value + \fI(public member function)\fP + type returns the typeid of the contained value + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::any) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function)\fP + any_cast type-safe access to the contained object + \fI(C++17)\fP \fI(function template)\fP + make_any creates an any object + \fI(C++17)\fP \fI(function template)\fP + +.SH Helper classes + + bad_any_cast exception thrown by the value-returning forms of any_cast on a type + \fI(C++17)\fP mismatch + \fI(class)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_any 201606L \fI(C++17)\fP std::any + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + // any type + std::any a = 1; + std::cout << a.type().name() << ": " << std::any_cast(a) << '\\n'; + a = 3.14; + std::cout << a.type().name() << ": " << std::any_cast(a) << '\\n'; + a = true; + std::cout << a.type().name() << ": " << std::any_cast(a) << '\\n'; + + // bad cast + try + { + a = 1; + std::cout << std::any_cast(a) << '\\n'; + } + catch (const std::bad_any_cast& e) + { + std::cout << e.what() << '\\n'; + } + + // has value + a = 2; + if (a.has_value()) + std::cout << a.type().name() << ": " << std::any_cast(a) << '\\n'; + + // reset + a.reset(); + if (!a.has_value()) + std::cout << "no value\\n"; + + // pointer to contained data + a = 3; + int* i = std::any_cast(&a); + std::cout << *i << '\\n'; + } + +.SH Possible output: + + int: 1 + double: 3.14 + bool: true + bad any_cast + int: 2 + no value + 3 + +.SH See also + + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + variant a type-safe discriminated union + \fI(C++17)\fP \fI(class template)\fP + optional a wrapper that may or may not hold an object + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::any::any.3 b/man/std::any::any.3 new file mode 100644 index 000000000..3d90b9bbf --- /dev/null +++ b/man/std::any::any.3 @@ -0,0 +1,143 @@ +.TH std::any::any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::any \- std::any::any + +.SH Synopsis + constexpr any() noexcept; \fB(1)\fP \fI(since C++17)\fP + any( const any& other ); \fB(2)\fP \fI(since C++17)\fP + any( any&& other ) noexcept; \fB(3)\fP \fI(since C++17)\fP + template< class ValueType > \fB(4)\fP \fI(since C++17)\fP + any( ValueType&& value ); + template< class ValueType, class... Args > \fB(5)\fP \fI(since C++17)\fP + explicit any( std::in_place_type_t, Args&&... args ); + template< class ValueType, class U, class... Args > + + explicit any( std::in_place_type_t, \fB(6)\fP \fI(since C++17)\fP + std::initializer_list il, + + Args&&... args ); + + Constructs a new any object. + + 1) Constructs an empty object. + 2,3) Copies \fB(2)\fP or moves \fB(3)\fP content of other into a new instance, so that any + content is equivalent in both type and value to those of other prior to the + constructor call, or empty if other is empty. Formally, + 2) If other is empty, the constructed object is empty. Otherwise, equivalent to + any(std::in_place_type, std::any_cast(other)), where T is the type of + the object contained in other. + 3) If other is empty, the constructed object is empty. Otherwise, the constructed + object contains either the object contained in other, or an object of the same type + constructed from the object contained in other, considering that object as an +.SH rvalue. + 4) Constructs an object with initial content an object of type + std::decay_t, direct-initialized from std::forward(value). + * This overload participates in overload resolution only if + std::decay_t is not the same type as any nor a specialization of + std::in_place_type_t, and std::is_copy_constructible_v> + is true. + 5) Constructs an object with initial content an object of type + std::decay_t, direct-non-list-initialized from + std::forward(args).... + * This overload participates in overload resolution only if + std::is_constructible_v, Args...> and + std::is_copy_constructible_v> are both true. + 6) Constructs an object with initial content an object of type + std::decay_t, direct-non-list-initialized from il, + std::forward(args).... + * This overload participates in overload resolution only if + std::is_constructible_v, std::initializer_list&, + Args...> and std::is_copy_constructible_v> are both + true. + +.SH Template parameters + + ValueType - contained value type +.SH Type requirements + - + std::decay_t must meet the requirements of CopyConstructible. + +.SH Parameters + + other - another any object to copy or move from + value - value to initialize the contained value with + il, args - arguments to be passed to the constructor of the contained object + +.SH Exceptions + + 2,4-6) Throws any exception thrown by the constructor of the contained type. + +.SH Notes + + Because the default constructor is constexpr, static std::anys are initialized as + part of static non-local initialization, before any dynamic non-local initialization + begins. This makes it safe to use an object of type std::any in a constructor of any + static object. + +.SH Example + + +// Run this code + + #include + + #include + #include + #include + #include + #include + #include + #include + + struct A + { + int age; + std::string name; + double salary; + + #if __cpp_aggregate_paren_init < 201902L + // Required before C++20 for in-place construction + A(int age, std::string name, double salary) + : age(age), name(std::move(name)), salary(salary) {} + #endif + }; + + // Using abi demangle to print nice type name of instance of any holding + void printType(const std::any& a) + { + std::cout << boost::core::demangle(a.type().name()) << '\\n'; + } + + int main() + { + // Constructor #4: std::any holding int + std::any a1{7}; + + // Constructor #5: std::any holding A, constructed in place + std::any a2(std::in_place_type, 30, "Ada", 1000.25); + + // Constructor #6: std::any holding a set of A with custom comparison + auto lambda = [](auto&& l, auto&& r){ return l.age < r.age; }; + std::any a3( + std::in_place_type>, + { + A{39, std::string{"Ada"}, 100.25}, + A{20, std::string{"Bob"}, 75.5} + }, + lambda); + + printType(a1); + printType(a2); + printType(a3); + } + +.SH Possible output: + + int + A + std::set > + +.SH See also + + operator= assigns an any object + \fI(public member function)\fP diff --git a/man/std::any::emplace.3 b/man/std::any::emplace.3 new file mode 100644 index 000000000..64d7f86a2 --- /dev/null +++ b/man/std::any::emplace.3 @@ -0,0 +1,103 @@ +.TH std::any::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::emplace \- std::any::emplace + +.SH Synopsis + template< class ValueType, class... Args > \fB(1)\fP \fI(since C++17)\fP + std::decay_t& emplace( Args&&... args ); + template< class ValueType, class U, class... Args > + std::decay_t& emplace( std::initializer_list il, \fB(2)\fP \fI(since C++17)\fP + Args&&... args ); + + Changes the contained object to one of type std::decay_t constructed from + the arguments. + + First destroys the current contained object (if any) by reset(), then: + + 1) constructs an object of type std::decay_t, direct-non-list-initialized + from std::forward(args)..., as the contained object. + * This overload participates in overload resolution only if + std::is_constructible_v, Args...> and + std::is_copy_constructible_v> are both true. + 2) constructs an object of type std::decay_t, direct-non-list-initialized + from il, std::forward(args)..., as the contained object. + * This overload participates in overload resolution only if + std::is_constructible_v, std::initializer_list&, + Args...> and std::is_copy_constructible_v> are both + true. + +.SH Template parameters + + ValueType - contained value type +.SH Type requirements + - + std::decay_t must meet the requirements of CopyConstructible. + +.SH Return value + + A reference to the new contained object. + +.SH Exceptions + + Throws any exception thrown by T's constructor. If an exception is thrown, the + previously contained object (if any) has been destroyed, and *this does not contain + a value. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + class Star + { + std::string name; + int id; + + public: + Star(std::string name, int id) : name{name}, id{id} + { + std::cout << "Star::Star(string, int)\\n"; + } + + void print() const + { + std::cout << "Star{\\"" << name << "\\" : " << id << "};\\n"; + } + }; + + int main() + { + std::any celestial; + // (1) emplace(Args&&... args); + celestial.emplace("Procyon", 2943); + const auto* star = std::any_cast(&celestial); + star->print(); + + std::any av; + // (2) emplace(std::initializer_list il, Args&&... args); + av.emplace>({'C', '+', '+', '1', '7'} /* no args */); + std::cout << av.type().name() << '\\n'; + const auto* va = std::any_cast>(&av); + std::for_each(va->cbegin(), va->cend(), [](char const& c) { std::cout << c; }); + std::cout << '\\n'; + } + +.SH Possible output: + + Star::Star(string, int) + Star{"Procyon" : 2943}; + St6vectorIcSaIcEE + C++17 + +.SH See also + + constructor constructs an any object + \fI(public member function)\fP + reset destroys contained object + \fI(public member function)\fP diff --git a/man/std::any::has_value.3 b/man/std::any::has_value.3 new file mode 100644 index 000000000..0498955f1 --- /dev/null +++ b/man/std::any::has_value.3 @@ -0,0 +1,60 @@ +.TH std::any::has_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::has_value \- std::any::has_value + +.SH Synopsis + bool has_value() const noexcept; \fI(since C++17)\fP + + Checks whether the object contains a value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if instance contains a value, otherwise false. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::boolalpha(std::cout); + + std::any a0; + std::cout << "a0.has_value(): " << a0.has_value() << '\\n'; + + std::any a1 = 42; + std::cout << "a1.has_value(): " << a1.has_value() << '\\n'; + std::cout << "a1 = " << std::any_cast(a1) << '\\n'; + a1.reset(); + std::cout << "a1.has_value(): " << a1.has_value() << '\\n'; + + auto a2 = std::make_any("Milky Way"); + std::cout << "a2.has_value(): " << a2.has_value() << '\\n'; + std::cout << "a2 = \\"" << std::any_cast(a2) << "\\"\\n"; + a2.reset(); + std::cout << "a2.has_value(): " << a2.has_value() << '\\n'; + } + +.SH Output: + + a0.has_value(): false + a1.has_value(): true + a1 = 42 + a1.has_value(): false + a2.has_value(): true + a2 = "Milky Way" + a2.has_value(): false + +.SH See also + + reset destroys contained object + \fI(public member function)\fP diff --git a/man/std::any::operator=.3 b/man/std::any::operator=.3 new file mode 100644 index 000000000..344b95dd8 --- /dev/null +++ b/man/std::any::operator=.3 @@ -0,0 +1,53 @@ +.TH std::any::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::operator= \- std::any::operator= + +.SH Synopsis + any& operator=( const any& rhs ); \fB(1)\fP \fI(since C++17)\fP + any& operator=( any&& rhs ) noexcept; \fB(2)\fP \fI(since C++17)\fP + template< typename ValueType > \fB(3)\fP \fI(since C++17)\fP + any& operator=( ValueType&& rhs ); + + Assigns contents to the contained value. + + 1) Assigns by copying the state of rhs, as if by any(rhs).swap(*this). + 2) Assigns by moving the state of rhs, as if by any(std::move(rhs)).swap(*this). rhs + is left in a valid but unspecified state after the assignment. + 3) Assigns the type and value of rhs, as if by + any(std::forward(rhs)).swap(*this). This overload participates in + overload resolution only if std::decay_t is not the same type as any and + std::is_copy_constructible_v> is true. + +.SH Template parameters + + ValueType - contained value type +.SH Type requirements + - + std::decay_t must meet the requirements of CopyConstructible. + +.SH Parameters + + rhs - object whose contained value to assign + +.SH Return value + + *this + +.SH Exceptions + + 1,3) Throws std::bad_alloc or any exception thrown by the constructor of the + contained type. If an exception is thrown, there are no effects (strong exception + guarantee). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs an any object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::any::reset.3 b/man/std::any::reset.3 new file mode 100644 index 000000000..b29dc58d5 --- /dev/null +++ b/man/std::any::reset.3 @@ -0,0 +1,21 @@ +.TH std::any::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::reset \- std::any::reset + +.SH Synopsis + void reset() noexcept; \fI(since C++17)\fP + + If not empty, destroys the contained object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH See also + + has_value checks if object holds a value + \fI(public member function)\fP diff --git a/man/std::any::swap.3 b/man/std::any::swap.3 new file mode 100644 index 000000000..6fcabb74f --- /dev/null +++ b/man/std::any::swap.3 @@ -0,0 +1,16 @@ +.TH std::any::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::swap \- std::any::swap + +.SH Synopsis + void swap( any& other ) noexcept; \fI(since C++17)\fP + + Swaps the content of two any objects. + +.SH Parameters + + other - object to swap with + +.SH Return value + + \fI(none)\fP diff --git a/man/std::any::type.3 b/man/std::any::type.3 new file mode 100644 index 000000000..b5d7ac18e --- /dev/null +++ b/man/std::any::type.3 @@ -0,0 +1,118 @@ +.TH std::any::type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::type \- std::any::type + +.SH Synopsis + const std::type_info& type() const noexcept; \fI(since C++17)\fP + + Queries the contained type. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The typeid of the contained value if instance is non-empty, otherwise typeid(void). + +.SH Example + + The example demonstrates std::any visitor idiom with ability to register new + visitors at compile- and run-time. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + template + inline std::pair> + to_any_visitor(F const& f) + { + return + { + std::type_index(typeid(T)), + [g = f](std::any const& a) + { + if constexpr (std::is_void_v) + g(); + else + g(std::any_cast(a)); + } + }; + } + + static std::unordered_map> + any_visitor + { + to_any_visitor([] { std::cout << "{}"; }), + to_any_visitor([](int x) { std::cout << x; }), + to_any_visitor([](unsigned x) { std::cout << x; }), + to_any_visitor([](float x) { std::cout << x; }), + to_any_visitor([](double x) { std::cout << x; }), + to_any_visitor([](char const* s) + { std::cout << std::quoted(s); }), + // ... add more handlers for your types ... + }; + + inline void process(const std::any& a) + { + if (const auto it = any_visitor.find(std::type_index(a.type())); + it != any_visitor.cend()) + it->second(a); + else + std::cout << "Unregistered type "<< std::quoted(a.type().name()); + } + + template + inline void register_any_visitor(F const& f) + { + std::cout << "Register visitor for type " + << std::quoted(typeid(T).name()) << '\\n'; + any_visitor.insert(to_any_visitor(f)); + } + + int main() + { + std::vector va{{}, 42, 123u, 3.14159f, 2.71828, "C++17"}; + + std::cout << "{ "; + for (const std::any& a : va) + { + process(a); + std::cout << ", "; + } + std::cout << "}\\n"; + + process(std::any(0xFULL)); //< Unregistered type "y" (unsigned long long) + std::cout << '\\n'; + + register_any_visitor([](auto x) + { + std::cout << std::hex << std::showbase << x; + }); + + process(std::any(0xFULL)); //< OK: 0xf + std::cout << '\\n'; + } + +.SH Possible output: + + { {}, 42, 123, 3.14159, 2.71828, "C++17", } + Unregistered type "y" + Register visitor for type "y" + 0xf + +.SH See also + + type_index wrapper around a type_info object, that can be used as index in + \fI(C++11)\fP associative and unordered associative containers + \fI(class)\fP diff --git a/man/std::any::~any.3 b/man/std::any::~any.3 new file mode 100644 index 000000000..3e02572d5 --- /dev/null +++ b/man/std::any::~any.3 @@ -0,0 +1,13 @@ +.TH std::any::~any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any::~any \- std::any::~any + +.SH Synopsis + ~any(); \fI(since C++17)\fP + + Destroys the contained object, if any, as if by a call to reset(). + +.SH See also + + reset destroys contained object + \fI(public member function)\fP diff --git a/man/std::any_cast.3 b/man/std::any_cast.3 new file mode 100644 index 000000000..1c6d2f31a --- /dev/null +++ b/man/std::any_cast.3 @@ -0,0 +1,113 @@ +.TH std::any_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::any_cast \- std::any_cast + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++17)\fP + T any_cast( const any& operand ); + template< class T > \fB(2)\fP \fI(since C++17)\fP + T any_cast( any& operand ); + template< class T > \fB(3)\fP \fI(since C++17)\fP + T any_cast( any&& operand ); + template< class T > \fB(4)\fP \fI(since C++17)\fP + const T* any_cast( const any* operand ) noexcept; + template< class T > \fB(5)\fP \fI(since C++17)\fP + T* any_cast( any* operand ) noexcept; + + Performs type-safe access to the contained object. + + Let U be std::remove_cv_t>. + + 1) The program is ill-formed if std::is_constructible_v is false. + 2) The program is ill-formed if std::is_constructible_v is false. + 3) The program is ill-formed if std::is_constructible_v is false. + 4,5) The program is ill-formed if std::is_void_v is true. + +.SH Parameters + + operand - target any object + +.SH Return value + + 1,2) Returns static_cast(*std::any_cast(&operand)). + 3) Returns static_cast(std::move(*std::any_cast(&operand))). + 4,5) If operand is not a null pointer, and the typeid of the requested T matches + that of the contents of operand, a pointer to the value contained by operand, + otherwise a null pointer. + +.SH Exceptions + + 1-3) Throws std::bad_any_cast if the typeid of the requested T does not match that + of the contents of operand. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + // Simple example + auto a1 = std::any(12); + std::cout << "1) a1 is int: " << std::any_cast(a1) << '\\n'; + + try + { + auto s = std::any_cast(a1); // throws + } + catch (const std::bad_any_cast& e) + { + std::cout << "2) " << e.what() << '\\n'; + } + + // Pointer example + if (int* i = std::any_cast(&a1)) + std::cout << "3) a1 is int: " << *i << '\\n'; + else if (std::string* s = std::any_cast(&a1)) + std::cout << "3) a1 is std::string: " << *s << '\\n'; + else + std::cout << "3) a1 is another type or unset\\n"; + + // Advanced example + a1 = std::string("hello"); + auto& ra = std::any_cast(a1); //< reference + ra[1] = 'o'; + + std::cout << "4) a1 is string: " + << std::any_cast(a1) << '\\n'; //< const reference + + auto s1 = std::any_cast(std::move(a1)); //< rvalue reference + // Note: “s1” is a move-constructed std::string: + static_assert(std::is_same_v); + + // Note: the std::string in “a1” is left in valid but unspecified state + std::cout << "5) a1.size(): " + << std::any_cast(&a1)->size() //< pointer + << '\\n' + << "6) s1: " << s1 << '\\n'; + } + +.SH Possible output: + + 1) a1 is int: 12 + 2) bad any_cast + 3) a1 is int: 12 + 4) a1 is string: hollo + 5) a1.size(): 0 + 6) s1: hollo + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3305 C++17 the behavior of overloads (4,5) was the program ill-formed in + unclear if T is void this case diff --git a/man/std::apply.3 b/man/std::apply.3 new file mode 100644 index 000000000..7a53eee9e --- /dev/null +++ b/man/std::apply.3 @@ -0,0 +1,133 @@ +.TH std::apply 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::apply \- std::apply + +.SH Synopsis + Defined in header + template< class F, class Tuple > \fI(since C++17)\fP + constexpr decltype(auto) apply( F&& f, Tuple&& t ); (until C++23) + template< class F, tuple-like Tuple > + constexpr decltype(auto) apply( F&& f, Tuple&& t ) noexcept(/* see (since C++23) + below */); + + Invoke the Callable object f with the elements of t as arguments. + + Given the exposition-only function apply-impl defined as follows: template + constexpr decltype(auto) + apply-impl(F&& f, Tuple&& t, std::index_sequence) // exposition only + { + return INVOKE(std::forward(f), std::get(std::forward(t))...); + } + + The effect is equivalent to return apply-impl(std::forward(f), + std::forward(t), + std::make_index_sequence< + std::tuple_size_v>>{}); . + +.SH Parameters + + f - Callable object to be invoked + t - tuple whose elements to be used as arguments to f + +.SH Return value + + The value returned by f. + +.SH Exceptions + + \fI(none)\fP (until + C++23) + noexcept specification: + noexcept( + + noexcept(std::invoke(std::forward(f), + std::get(std::forward(t))...)) (since + C++23) + ) + + where Is... denotes the parameter pack: + + * 0, 1, ..., std::tuple_size_v> - 1. + +.SH Notes + + Tuple need not be std::tuple, and instead may be anything that + supports std::get and std::tuple_size; in particular, std::array and (until C++23) + std::pair may be used. + Tuple is constrained to be tuple-like, i.e. each type therein is + required to be a specialization of std::tuple or another type (such as (since C++23) + std::array and std::pair) that models tuple-like. + + Feature-test macro Value Std Feature + __cpp_lib_apply 201603L \fI(C++17)\fP std::apply + +.SH Example + + +// Run this code + + #include + #include + #include + + int add(int first, int second) { return first + second; } + + template + T add_generic(T first, T second) { return first + second; } + + auto add_lambda = [](auto first, auto second) { return first + second; }; + + template + std::ostream& operator<<(std::ostream& os, std::tuple const& theTuple) + { + std::apply + ( + [&os](Ts const&... tupleArgs) + { + os << '['; + std::size_t n{0}; + ((os << tupleArgs << (++n != sizeof...(Ts) ? ", " : "")), ...); + os << ']'; + }, theTuple + ); + return os; + } + + int main() + { + // OK + std::cout << std::apply(add, std::pair(1, 2)) << '\\n'; + + // Error: can't deduce the function type + // std::cout << std::apply(add_generic, std::make_pair(2.0f, 3.0f)) << '\\n'; + + // OK + std::cout << std::apply(add_lambda, std::pair(2.0f, 3.0f)) << '\\n'; + + // advanced example + std::tuple myTuple{25, "Hello", 9.31f, 'c'}; + std::cout << myTuple << '\\n'; + } + +.SH Output: + + 3 + 5 + [25, Hello, 9.31, c] + +.SH See also + + make_tuple creates a tuple object of the type defined by the argument types + \fI(C++11)\fP \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP + make_from_tuple construct an object with a tuple of arguments + \fI(C++17)\fP \fI(function template)\fP + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::arg(std::complex).3 b/man/std::arg(std::complex).3 index b330f7b4c..13e68bece 100644 --- a/man/std::arg(std::complex).3 +++ b/man/std::arg(std::complex).3 @@ -1,33 +1,108 @@ -.TH std::arg(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::arg(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::arg(std::complex) \- std::arg(std::complex) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP - T arg( const complex& z ); - long double arg( long double z ); \fB(2)\fP \fI(since C++11)\fP - template< class DoubleOrIngeter > \fB(3)\fP \fI(since C++11)\fP - double arg( DoubleOrInteger z ); - float arg( float z ); \fB(4)\fP \fI(since C++11)\fP + template< class T > \fB(1)\fP + T arg( const std::complex& z ); + Additional overloads \fI(since C++11)\fP + Defined in header + float arg( float f ); + + double arg( double f ); (until C++23) + + long double arg( long double f ); + template< class FloatingPoint > (A) + + FloatingPoint (since C++23) - Returns the phase angle (in radians) of the complex number z, i.e. - atan2(std::imag(z), std::real(z)). + arg( FloatingPoint f ); + template< class Integer > (B) + double arg( Integer i ); - \fI(since C++11)\fPAdditional overloads are provided for float, double, long double, and - all integer types, which are treated as complex numbers with zero imaginary - component. + 1) Calculates the phase angle (in radians) of the complex number z. + + A,B) Additional overloads are provided for all integer and + floating-point types, which are treated as complex numbers with zero \fI(since C++11)\fP + imaginary component. .SH Parameters z - complex value + f - floating-point value + i - integer value .SH Return value - the phase angle of z + 1) std::atan2(std::imag(z), std::real(z)). If no errors occur, this is the phase + angle of z in the interval [−π; π]. + A) Zero if f is positive or +0, π if f is negative or -0, NaN otherwise. + B) Zero if i is non-negative, π if it is negative. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num: + + * If num has a + standard + (until C++23) floating-point type T, then std::arg(num) has the same effect as + std::arg(std::complex(num)). + * Otherwise, if num has an integer type, then std::arg(num) has the same effect as + std::arg(std::complex(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::complex z1(1, 0); + std::complex z2(0, 0); + std::complex z3(0, 1); + std::complex z4(-1, 0); + std::complex z5(-1, -0.0); + double f = 1.; + int i = -1; + + std::cout << "phase angle of " << z1 << " is " << std::arg(z1) << '\\n' + << "phase angle of " << z2 << " is " << std::arg(z2) << '\\n' + << "phase angle of " << z3 << " is " << std::arg(z3) << '\\n' + << "phase angle of " << z4 << " is " << std::arg(z4) << '\\n' + << "phase angle of " << z5 << " is " << std::arg(z5) << " " + "(the other side of the cut)\\n" + << "phase angle of " << f << " is " << std::arg(f) << '\\n' + << "phase angle of " << i << " is " << std::arg(i) << '\\n'; + + } + +.SH Output: + + phase angle of (1,0) is 0 + phase angle of (0,0) is 0 + phase angle of (0,1) is 1.5708 + phase angle of (-1,0) is 3.14159 + phase angle of (-1,-0) is -3.14159 (the other side of the cut) + phase angle of 1 is 0 + phase angle of -1 is 3.14159 .SH See also - norm returns the squared magnitude - \fI(function template)\fP - conj returns the complex conjugate - \fI(function template)\fP - polar constructs a complex number from magnitude and phase angle - \fI(function template)\fP + abs(std::complex) returns the magnitude of a complex number + \fI(function template)\fP + polar constructs a complex number from magnitude and phase angle + \fI(function template)\fP + atan2 + atan2f arc tangent, using signs to determine quadrants + atan2l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan2(std::valarray) applies the function std::atan2 to a valarray and a value + \fI(function template)\fP + C documentation for + carg diff --git a/man/std::array.3 b/man/std::array.3 index 841518776..5cd839ae0 100644 --- a/man/std::array.3 +++ b/man/std::array.3 @@ -1,4 +1,7 @@ -.TH std::array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array \- std::array + .SH Synopsis Defined in header template< @@ -8,43 +11,77 @@ > struct array; - std::array is a container that encapsulates constant size arrays. + std::array is a container that encapsulates fixed size arrays. This container is an aggregate type with the same semantics as a struct holding a - C-style array T[N] as its only non-static data member. It can be initialized with - aggregate-initialization, given at most N initializers that are convertible to T: - std::array a = {1,2,3}; + C-style array T[N] as its only non-static data member. Unlike a C-style array, it + doesn't decay to T* automatically. As an aggregate type, it can be initialized with + aggregate-initialization given at most N initializers that are convertible to T: + std::array a = {1, 2, 3};. The struct combines the performance and accessibility of a C-style array with the benefits of a standard container, such as knowing its own size, supporting assignment, random access iterators, etc. + std::array satisfies the requirements of Container and ReversibleContainer except + that default-constructed array is not empty and that the complexity of swapping is + linear, + satisfies the requirements of ContiguousContainer, + \fI(since C++17)\fP and partially satisfies the requirements of SequenceContainer. + There is a special case for a zero-length array (N == 0). In that case, array.begin() == array.end(), which is some unique value. The effect of calling front() or back() on a zero-sized array is undefined. An array can also be used as a tuple of N elements of the same type. +.SH Template parameters + + T - element type Must be MoveConstructible and MoveAssignable. + N - the number of elements in the array or 0. + + This section is incomplete + Reason: Complete the descriptions of template parameters. + .SH Member types Member type Definition - value_type T - size_type std::size_t - difference_type std::ptrdiff_t - reference value_type& - const_reference const value_type& + value_type T + size_type std::size_t + difference_type std::ptrdiff_t + reference value_type& + const_reference const value_type& pointer value_type* const_pointer const value_type* - iterator RandomAccessIterator - const_iterator Constant random access iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + LegacyRandomAccessIterator and \fI(until C++17)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator and \fI(since C++17)\fP + LegacyContiguousIterator that is a LiteralType \fI(until C++20)\fP + iterator to value_type + LegacyRandomAccessIterator, + contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++17)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator and \fI(since C++17)\fP + LegacyContiguousIterator that is a LiteralType \fI(until C++20)\fP + const_iterator to const value_type + LegacyRandomAccessIterator, + contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator .SH Member functions .SH Implicitly-defined member functions - constructor default-constructs or copy-constructs every element of the - (implicitly declared) array + initializes the array following the rules of aggregate + constructor initialization (note that default initialization may result in + (implicitly declared) indeterminate values for non-class T) \fI(public member function)\fP destructor destroys every element of the array (implicitly declared) \fI(public member function)\fP @@ -53,88 +90,122 @@ \fI(public member function)\fP .SH Element access at access specified element with bounds checking - \fI(public member function)\fP + \fI(public member function)\fP operator[] access specified element - \fI(public member function)\fP + \fI(public member function)\fP front access the first element - \fI(public member function)\fP + \fI(public member function)\fP back access the last element - \fI(public member function)\fP - data direct access to the underlying array - \fI(public member function)\fP + \fI(public member function)\fP + data direct access to the underlying contiguous storage + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Operations fill fill the container with specified value - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the array - operator<= \fI(function template)\fP + operator< + operator<= operator> operator>= - std::get(std::array) accesses an element of an array - \fI(function template)\fP - std::swap(std::array) specializes the std::swap algorithm - \fI(function template)\fP + operator<=> lexicographically compares the values of two arrays + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + (C++20) + get(std::array) accesses an element of an array + \fI(C++11)\fP \fI(function template)\fP + std::swap(std::array) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + to_array creates a std::array object from a built-in array + (C++20) \fI(function template)\fP .SH Helper classes std::tuple_size obtains the size of an array - \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP std::tuple_element obtains the type of the elements of array - \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP .SH Example - + // Run this code - #include - #include - #include #include #include - + #include + #include + #include + int main() { - // construction uses aggregate initialization - std::array a1{ {1,2,3} }; // double-braces required - std::array a2 = {1, 2, 3}; // except after = - std::array a3 = { {std::string("a"), "b"} }; - - // container operations are supported + // Construction uses aggregate initialization + std::array a1{{1, 2, 3}}; // Double-braces required in C++11 prior to + // the CWG 1270 revision (not needed in C++11 + // after the revision and in C++14 and beyond) + + std::array a2 = {1, 2, 3}; // Double braces never required after = + + // Container operations are supported std::sort(a1.begin(), a1.end()); - std::reverse_copy(a2.begin(), a2.end(), - std::ostream_iterator(std::cout, " ")); - + std::ranges::reverse_copy(a2, std::ostream_iterator(std::cout, " ")); std::cout << '\\n'; - - // ranged for loop is supported - for(auto& s: a3) + + // Ranged for loop is supported + std::array a3{"E", "\\u018E"}; + for (const auto& s : a3) std::cout << s << ' '; + std::cout << '\\n'; + + // Deduction guide for array creation \fI(since C++17)\fP + [[maybe_unused]] std::array a4{3.0, 1.0, 4.0}; // std::array + + // Behavior of unspecified elements is the same as with built-in arrays + [[maybe_unused]] std::array a5; // No list init, a5[0] and a5[1] + // are default initialized + [[maybe_unused]] std::array a6{}; // List init, both elements are value + // initialized, a6[0] = a6[1] = 0 + [[maybe_unused]] std::array a7{1}; // List init, unspecified element is value + // initialized, a7[0] = 1, a7[1] = 0 } .SH Output: 3 2 1 - a b + E Ǝ + +.SH See also + + make_array creates a std::array object whose size and optionally + (library fundamentals TS v2) element type are deduced from the arguments + \fI(function template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::array::at.3 b/man/std::array::at.3 index 8457b6bd6..26b120670 100644 --- a/man/std::array::at.3 +++ b/man/std::array::at.3 @@ -1,14 +1,17 @@ -.TH std::array::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::at \- std::array::at + .SH Synopsis - reference at( size_type pos ); \fI(since C++11)\fP - const_reference at( size_type pos ) const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr const_reference at( size_type pos ) const; \fI(since C++14)\fP + reference at( size_type pos ); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reference at( size_type pos ) const; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++14) Returns a reference to the element at specified location pos, with bounds checking. - If pos not within the range of the container, an exception of type std::out_of_range - is thrown. + If pos is not within the range of the container, an exception of type + std::out_of_range is thrown. .SH Parameters @@ -20,13 +23,66 @@ .SH Exceptions - std::out_of_range if !(pos < size()). + std::out_of_range if pos >= size(). .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + #ifdef __GNUG__ + [[gnu::noinline]] + #endif + unsigned int runtime_six() // Emulate runtime input + { + return 6u; + } + + int main() + { + std::array data = {1, 2, 4, 5, 5, 6}; + + // Set element 1 + data.at(1) = 88; + + // Read element 2 + std::cout << "Element at index 2 has value " << data.at(2) << '\\n'; + + std::cout << "data size = " << data.size() << '\\n'; + + try + { + // Set element 6, where the index is determined at runtime + data.at(runtime_six()) = 666; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + + // Print final values + std::cout << "data:"; + for (int elem : data) + std::cout << ' ' << elem; + std::cout << '\\n'; + } + +.SH Possible output: + + Element at index 2 has value 4 + data size = 6 + array::at: __n (which is 6) >= _Nm (which is 6) + data: 1 88 4 5 5 6 + .SH See also operator[] access specified element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::array::back.3 b/man/std::array::back.3 index d6c43edc8..b07e05ddd 100644 --- a/man/std::array::back.3 +++ b/man/std::array::back.3 @@ -1,13 +1,16 @@ -.TH std::array::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::back \- std::array::back + .SH Synopsis - reference back(); \fI(since C++11)\fP - const_reference back() const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr const_reference back() const; \fI(since C++14)\fP + reference back(); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reference back() const; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++14) - Returns reference to the last element in the container. + Returns a reference to the last element in the container. - Calling back on an empty container is undefined. + Calling back on an empty container causes undefined behavior. .SH Parameters @@ -23,32 +26,32 @@ .SH Notes - For a container c, the expression return c.back(); is equivalent to { auto tmp = - c.end(); --tmp; return *tmp; } + For a non-empty container c, the expression c.back() is equivalent to + *std::prev(c.end()). .SH Example The following code uses back to display the last element of a std::array: - + // Run this code #include #include - + int main() { - std::array letters {'o', 'm', 'g', 'w', 't', 'f'}; - if (!letters.empty()) { - std::cout << "The last character is: " << letters.back() << '\\n'; - } + std::array letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The last character is '" << letters.back() << "'.\\n"; } .SH Output: - The last character is f + The last character is 'f'. .SH See also front access the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::array::begin,std::array::cbegin.3 b/man/std::array::begin,std::array::cbegin.3 index 48136cdf0..84dc247c5 100644 --- a/man/std::array::begin,std::array::cbegin.3 +++ b/man/std::array::begin,std::array::cbegin.3 @@ -1,12 +1,18 @@ -.TH std::array::begin,std::array::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::begin,std::array::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::begin,std::array::cbegin \- std::array::begin,std::array::cbegin + .SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin() noexcept; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_iterator begin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++17) - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the array. - If the container is empty, the returned iterator will be equal to end(). + If the array is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,19 +22,76 @@ .SH Return value - Iterator to the first element + Iterator to the first element. + +.SH Complexity -.SH Exceptions + Constant. - noexcept specification: - noexcept - +.SH Example -.SH Complexity - Constant +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::array empty; + std::cout << "1) " + << (empty.begin() == empty.end()) << ' ' // true + << (empty.cbegin() == empty.cend()) << '\\n'; // true + // *(empty.begin()) = 42; // => undefined behavior at run-time + + + std::array numbers{5, 2, 3, 4}; + std::cout << "2) " + << (numbers.begin() == numbers.end()) << ' ' // false + << (numbers.cbegin() == numbers.cend()) << '\\n' // false + << "3) " + << *(numbers.begin()) << ' ' // 5 + << *(numbers.cbegin()) << '\\n'; // 5 + + *numbers.begin() = 1; + std::cout << "4) " << *(numbers.begin()) << '\\n'; // 1 + // *(numbers.cbegin()) = 42; // compile-time error: + // read-only variable is not assignable + + // print out all elements + std::cout << "5) "; + std::for_each(numbers.cbegin(), numbers.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + + constexpr std::array constants{'A', 'B', 'C'}; + static_assert(constants.begin() != constants.end()); // OK + static_assert(constants.cbegin() != constants.cend()); // OK + static_assert(*constants.begin() == 'A'); // OK + static_assert(*constants.cbegin() == 'A'); // OK + // *constants.begin() = 'Z'; // compile-time error: + // read-only variable is not assignable + } + +.SH Output: + + 1) true true + 2) false false + 3) 5 5 + 4) 1 + 5) 1 2 3 4 .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::array::data.3 b/man/std::array::data.3 index 258a80453..e5ab0f797 100644 --- a/man/std::array::data.3 +++ b/man/std::array::data.3 @@ -1,11 +1,16 @@ -.TH std::array::data 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::data \- std::array::data + .SH Synopsis - T* data(); \fI(since C++11)\fP - const T* data() const; \fI(since C++11)\fP + T* data() noexcept; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const T* data() const noexcept; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++14) Returns pointer to the underlying array serving as element storage. The pointer is - such that range [data(); data() + size()) is always a valid range, even if the - container is empty. + such that range [data(), data() + size()) is always a valid range, even if the + container is empty (data() is not dereferenceable in that case). .SH Parameters @@ -13,22 +18,68 @@ .SH Return value - Pointer to the underlying element storage. For non-empty containers, returns - &front() + Pointer to the underlying element storage. For non-empty containers, the returned + pointer compares equal to the address of the first element. .SH Complexity Constant. -.SH Exceptions +.SH Notes + + If size() is 0, data() may or may not return a null pointer. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void pointer_func(const int* p, std::size_t size) + { + std::cout << "data = "; + for (std::size_t i = 0; i < size; ++i) + std::cout << p[i] << ' '; + std::cout << '\\n'; + } + + void span_func(std::span data) // since C++20 + { + std::cout << "data = "; + for (const int e : data) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + std::array container{1, 2, 3, 4}; + + // Prefer container.data() over &container[0] + pointer_func(container.data(), container.size()); + + // std::span (C++20) is a safer alternative to separated pointer/size. + span_func({container.data(), container.size()}); + } + +.SH Output: - noexcept specification: - noexcept - + data = 1 2 3 4 + data = 1 2 3 4 .SH See also - front access the first element - \fI(public member function)\fP - back access the last element - \fI(public member function)\fP + front access the first element + \fI(public member function)\fP + back access the last element + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::array::empty.3 b/man/std::array::empty.3 index a2c7603c2..87f7b3b59 100644 --- a/man/std::array::empty.3 +++ b/man/std::array::empty.3 @@ -1,8 +1,11 @@ -.TH std::array::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::empty \- std::array::empty + .SH Synopsis - constexpr bool empty(); \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr bool empty() const; \fI(since C++14)\fP + constexpr bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -12,13 +15,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the container is empty, false otherwise. .SH Complexity @@ -26,31 +23,34 @@ .SH Example - + The following code uses empty to check if a std::array contains any elements: - + // Run this code #include #include - + int main() { - std::array numbers {3, 1, 4, 1}; + std::array numbers{3, 1, 4, 1}; std::array no_numbers; - + + std::cout << std::boolalpha; std::cout << "numbers.empty(): " << numbers.empty() << '\\n'; std::cout << "no_numbers.empty(): " << no_numbers.empty() << '\\n'; } .SH Output: - numbers.empty(): 0 - no_numbers.empty(): 1 + numbers.empty(): false + no_numbers.empty(): true .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::array::end,std::array::cend.3 b/man/std::array::end,std::array::cend.3 index 78d1eebfa..96b1184e1 100644 --- a/man/std::array::end,std::array::cend.3 +++ b/man/std::array::end,std::array::cend.3 @@ -1,10 +1,16 @@ -.TH std::array::end,std::array::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::end,std::array::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::end,std::array::cend \- std::array::end,std::array::cend + .SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP + iterator end() noexcept; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_iterator end() const noexcept; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++17) - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the array. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,17 +25,74 @@ Iterator to the element following the last element. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::array empty; + std::cout << "1) " + << (empty.begin() == empty.end()) << ' ' // true + << (empty.cbegin() == empty.cend()) << '\\n'; // true + // *(empty.begin()) = 42; // => undefined behavior at run-time + + + std::array numbers{5, 2, 3, 4}; + std::cout << "2) " + << (numbers.begin() == numbers.end()) << ' ' // false + << (numbers.cbegin() == numbers.cend()) << '\\n' // false + << "3) " + << *(numbers.begin()) << ' ' // 5 + << *(numbers.cbegin()) << '\\n'; // 5 + + *numbers.begin() = 1; + std::cout << "4) " << *(numbers.begin()) << '\\n'; // 1 + // *(numbers.cbegin()) = 42; // compile-time error: + // read-only variable is not assignable + + // print out all elements + std::cout << "5) "; + std::for_each(numbers.cbegin(), numbers.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + + constexpr std::array constants{'A', 'B', 'C'}; + static_assert(constants.begin() != constants.end()); // OK + static_assert(constants.cbegin() != constants.cend()); // OK + static_assert(*constants.begin() == 'A'); // OK + static_assert(*constants.cbegin() == 'A'); // OK + // *constants.begin() = 'Z'; // compile-time error: + // read-only variable is not assignable + } + +.SH Output: + + 1) true true + 2) false false + 3) 5 5 + 4) 1 + 5) 1 2 3 4 + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::array::fill.3 b/man/std::array::fill.3 index ce5e609e0..9aa14ad3b 100644 --- a/man/std::array::fill.3 +++ b/man/std::array::fill.3 @@ -1,8 +1,12 @@ -.TH std::array::fill 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::fill \- std::array::fill + .SH Synopsis void fill( const T& value ); \fI(since C++11)\fP + (constexpr since C++20) - Assigns the given value value to all elements in the container. + Assigns the value to all elements in the container. .SH Parameters @@ -14,4 +18,43 @@ .SH Complexity - Linear in the size of the container + Linear in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::size_t xy = 4; + + using Cell = std::array; + + std::array board; + + board.fill({0xE2, 0x96, 0x84, 0xE2, 0x96, 0x80, 0, 0}); // "▄▀"; + + for (std::size_t count{}; Cell c : board) + std::cout << c.data() << ((++count % xy) ? "" : "\\n"); + } + +.SH Possible output: + + ▄▀▄▀▄▀▄▀ + ▄▀▄▀▄▀▄▀ + ▄▀▄▀▄▀▄▀ + ▄▀▄▀▄▀▄▀ + +.SH See also + + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + fill_n copy-assigns the given value to N elements in a range + \fI(function template)\fP + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) diff --git a/man/std::array::front.3 b/man/std::array::front.3 index db02cb89d..5558c4388 100644 --- a/man/std::array::front.3 +++ b/man/std::array::front.3 @@ -1,13 +1,16 @@ -.TH std::array::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::front \- std::array::front + .SH Synopsis - reference front(); \fI(since C++11)\fP - const_reference front() const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr const_reference front() const; \fI(since C++14)\fP + reference front(); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reference front() const; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++14) Returns a reference to the first element in the container. - Calling front on an empty container is undefined. + Calling front on an empty container causes undefined behavior. .SH Parameters @@ -15,11 +18,11 @@ .SH Return value - reference to the first element + Reference to the first element. .SH Complexity - Constant + Constant. .SH Notes @@ -27,28 +30,27 @@ .SH Example - The following code uses front to display the first element of a std::array: + The following code uses front to display the first element of a std::array: + - // Run this code #include #include - + int main() { - std::array letters {'o', 'm', 'g', 'w', 't', 'f'}; - - if (!letters.empty()) { - std::cout << "The first character is: " << letters.front() << '\\n'; - } + std::array letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The first character is '" << letters.front() << "'.\\n"; } .SH Output: - The first character is o + The first character is 'a'. .SH See also back access the last element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::array::max_size.3 b/man/std::array::max_size.3 index b0b5e7a97..b8c64646a 100644 --- a/man/std::array::max_size.3 +++ b/man/std::array::max_size.3 @@ -1,8 +1,9 @@ -.TH std::array::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::max_size \- std::array::max_size + .SH Synopsis - constexpr size_type max_size(); \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr size_type max_size() const; \fI(since C++14)\fP + constexpr size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -16,24 +17,43 @@ Maximum number of elements. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the - container may be limited to a value smaller than max_size() by the amount of RAM - available. + Because each std::array is a fixed-size container, the value returned by + max_size equals N (which is also the value returned by size). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::array p; + std::array q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Output: + + 10 = 0xA + 10 = 0xA .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::array::operator[].3 b/man/std::array::operator[].3 index bdc108889..faa0a9d10 100644 --- a/man/std::array::operator[].3 +++ b/man/std::array::operator[].3 @@ -1,9 +1,12 @@ -.TH std::array::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::operator[] \- std::array::operator[] + .SH Synopsis - reference operator[]( size_type pos ); \fI(since C++11)\fP - const_reference operator[]( size_type pos ) const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr const_reference operator[]( size_type pos ) const; \fI(since C++14)\fP + reference operator[]( size_type pos ); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reference operator[]( size_type pos ) const; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++14) Returns a reference to the element at specified location pos. No bounds checking is performed. @@ -20,28 +23,33 @@ Constant. +.SH Notes + + Unlike std::map::operator[], this operator never inserts a new element into the + container. Accessing a nonexistent element through this operator is undefined + behavior. + .SH Example - The following code uses operator[] read from and write to a std::array: + The following code uses operator[] to read from and write to a std::array: + - // Run this code #include #include - + int main() { - std::array numbers {2, 4, 6, 8}; - + std::array numbers{2, 4, 6, 8}; + std::cout << "Second element: " << numbers[1] << '\\n'; - + numbers[0] = 5; - + std::cout << "All numbers:"; - for (auto i : numbers) { + for (auto i : numbers) std::cout << ' ' << i; - } std::cout << '\\n'; } @@ -53,4 +61,4 @@ .SH See also at access specified element with bounds checking - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::array::rbegin,std::array::crbegin.3 b/man/std::array::rbegin,std::array::crbegin.3 index 8d3e55b7e..96d92232c 100644 --- a/man/std::array::rbegin,std::array::crbegin.3 +++ b/man/std::array::rbegin,std::array::crbegin.3 @@ -1,11 +1,18 @@ -.TH std::array::rbegin,std::array::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::rbegin,std::array::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::rbegin,std::array::crbegin \- std::array::rbegin,std::array::crbegin + .SH Synopsis - reverse_iterator rbegin(); \fI(since C++11)\fP - const_reverse_iterator rbegin() const; \fI(since C++11)\fP - const_reverse_iterator crbegin() const; \fI(since C++11)\fP + reverse_iterator rbegin() noexcept; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reverse_iterator rbegin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++17) - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. + Returns a reverse iterator to the first element of the reversed array. It + corresponds to the last element of the non-reversed array. If the array is empty, + the returned iterator is equal to rend(). range-rbegin-rend.svg @@ -17,17 +24,56 @@ Reverse iterator to the first element. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::array data = {"▁","▂","▃","▄","▅","▆","▇","█"}; + + std::array arr; + + std::copy(data.cbegin(), data.cend(), arr.begin()); + // ^ ^ ^ + + auto print = [](const std::string_view s) { std::cout << s << ' '; }; + + print("Print 'arr' in direct order using [cbegin, cend):\\t"); + std::for_each(arr.cbegin(), arr.cend(), print); + // ^ ^ + print("\\n\\nPrint 'arr' in reverse order using [crbegin, crend):\\t"); + std::for_each(arr.crbegin(), arr.crend(), print); + // ^^ ^^ + print("\\n"); + } + +.SH Output: + + Print 'arr' in direct order using [cbegin, cend): ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ + + Print 'arr' in reverse order using [crbegin, crend): █ ▇ ▆ ▅ ▄ ▃ ▂ ▁ + .SH See also - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::array::rend,std::array::crend.3 b/man/std::array::rend,std::array::crend.3 index 0d7fdf7ff..d36051606 100644 --- a/man/std::array::rend,std::array::crend.3 +++ b/man/std::array::rend,std::array::crend.3 @@ -1,13 +1,19 @@ -.TH std::array::rend,std::array::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::rend,std::array::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::rend,std::array::crend \- std::array::rend,std::array::crend + .SH Synopsis - reverse_iterator rend(); \fI(since C++11)\fP - const_reverse_iterator rend() const; \fI(since C++11)\fP - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend() noexcept; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reverse_iterator rend() const noexcept; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++17) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++17) Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. + array. It corresponds to the element preceding the first element of the non-reversed + array. This element acts as a placeholder, attempting to access it results in + undefined behavior. range-rbegin-rend.svg @@ -19,17 +25,47 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::array a{1, 11, 11, 35, 0, 12, 79, 76, 76, 69, 40}; + + // print elements of array in reverse order using const_reverse_iterator`s + std::for_each(a.crbegin(), a.crend(), [](int e){ std::cout << e << ' '; }); + // ^^ ^^ + std::cout << '\\n'; + + // modify each element of array using non-const reverse_iterator`s + std::for_each(a.rbegin(), a.rend(), [](int& e){ e += 32; }); + // ^ ^ ^ + + // print elements as chars in reverse order using const_reverse_iterator`s + std::for_each(a.crbegin(), a.crend(), [](char e){ std::cout << e; }); + // ^^ ^^ ^^^^ + std::cout << '\\n'; + } + +.SH Output: + + 40 69 76 76 79 12 0 35 11 11 1 + Hello, C++! + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::array::size.3 b/man/std::array::size.3 index bba87b722..a77a74fd2 100644 --- a/man/std::array::size.3 +++ b/man/std::array::size.3 @@ -1,8 +1,9 @@ -.TH std::array::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::size \- std::array::size + .SH Synopsis - constexpr size_type size(); \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr size_type size() const; \fI(since C++14)\fP + constexpr size_type size() const noexcept; \fI(since C++11)\fP Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -14,30 +15,26 @@ The number of elements in the container. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Example + + The following code uses size to display the number of elements in a std::array: - + // Run this code #include #include - + int main() { - std::array nums {1, 3, 5, 7}; - + std::array nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -48,6 +45,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::array::swap.3 b/man/std::array::swap.3 index dd4db1d58..9596a96e9 100644 --- a/man/std::array::swap.3 +++ b/man/std::array::swap.3 @@ -1,6 +1,10 @@ -.TH std::array::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::array::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::array::swap \- std::array::swap + .SH Synopsis - void swap( array& other ); \fI(since C++11)\fP + void swap( array& other ) noexcept(/* see below */); \fI(since C++11)\fP + (constexpr since C++20) Exchanges the contents of the container with those of other. Does not cause iterators and references to associate with the other container. @@ -15,17 +19,74 @@ .SH Exceptions - noexcept specification: \fI(since C++11)\fP - noexcept(noexcept(std::swap(declval(), declval()))) + noexcept specification: + noexcept(noexcept(swap(std::declval(), std::declval()))) + \fI(until C++17)\fP + In the expression above, the identifier swap is looked up in the same + manner as the one used by the C++17 std::is_nothrow_swappable trait. + noexcept specification: \fI(since C++17)\fP + noexcept(std::is_nothrow_swappable_v) + For zero-sized arrays, - noexcept specification: \fI(since C++11)\fP - noexcept(noexcept(true)) + noexcept specification: + noexcept + .SH Complexity Linear in size of the container. +.SH Example + + +// Run this code + + #include + #include + + template Os& operator<<(Os& os, const V& v) + { + os << '{'; + for (auto i : v) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::array a1{1, 2, 3}, a2{4, 5, 6}; + + auto it1 = a1.begin(); + auto it2 = a2.begin(); + int& ref1 = a1[1]; + int& ref2 = a2[1]; + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that after swap iterators and references stay associated with their original + // array, e.g. `it1` still points to element a1[0], `ref1` still refers to a1[1]. + } + +.SH Output: + + { 1 2 3 } { 4 5 6 } 1 4 2 5 + { 4 5 6 } { 1 2 3 } 4 1 5 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2456 C++11 the noexcept specification is ill-formed made to work + .SH See also std::swap(std::array) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Categories: + * conditionally noexcept + * unconditionally noexcept diff --git a/man/std::as_bytes,std::as_writable_bytes.3 b/man/std::as_bytes,std::as_writable_bytes.3 new file mode 100644 index 000000000..78aa2e3d5 --- /dev/null +++ b/man/std::as_bytes,std::as_writable_bytes.3 @@ -0,0 +1,78 @@ +.TH std::as_bytes,std::as_writable_bytes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::as_bytes,std::as_writable_bytes \- std::as_bytes,std::as_writable_bytes + +.SH Synopsis + Defined in header + template< class T, std::size_t N > + + std::span \fB(1)\fP \fI(since C++20)\fP + + as_bytes( std::span s ) noexcept; + template< class T, std::size_t N > + + std::span \fB(2)\fP \fI(since C++20)\fP + + as_writable_bytes( std::span s ) noexcept; + + Obtains a view to the object representation of the elements of the span s. + + If N is std::dynamic_extent, the extent of the returned span S is also + std::dynamic_extent; otherwise it is sizeof(T) * N. + + as_writable_bytes only participates in overload resolution if std::is_const_v is + false. + +.SH Return value + + 1) A span constructed with {reinterpret_cast(s.data()), + s.size_bytes()}. + 2) A span constructed with {reinterpret_cast(s.data()), s.size_bytes()}. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(float const x, std::span const bytes) + { + std::cout << std::setprecision(6) << std::setw(8) << x << " = { " + << std::hex << std::uppercase << std::setfill('0'); + for (auto const b : bytes) + std::cout << std::setw(2) << std::to_integer(b) << ' '; + std::cout << std::dec << "}\\n"; + } + + int main() + { + /* mutable */ float data[1]{3.141592f}; + + auto const const_bytes = std::as_bytes(std::span{data}); + + print(data[0], const_bytes); + + auto const writable_bytes = std::as_writable_bytes(std::span{data}); + + // Change the sign bit that is the MSB (IEEE 754 Floating-Point Standard). + writable_bytes[3] |= std::byte{0B1000'0000}; + + print(data[0], const_bytes); + } + +.SH Possible output: + + 3.14159 = { D8 0F 49 40 } + -3.14159 = { D8 0F 49 C0 } + +.SH See also + + start_lifetime_as implicitly creates objects in given storage with the object + start_lifetime_as_array representation reused + (C++23) \fI(function template)\fP + byte the byte type + \fI(C++17)\fP \fI(enum)\fP diff --git a/man/std::as_const.3 b/man/std::as_const.3 new file mode 100644 index 000000000..01aa4d161 --- /dev/null +++ b/man/std::as_const.3 @@ -0,0 +1,76 @@ +.TH std::as_const 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::as_const \- std::as_const + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++17)\fP + constexpr std::add_const_t& as_const( T& t ) noexcept; + template< class T > \fB(2)\fP \fI(since C++17)\fP + void as_const( const T&& ) = delete; + + 1) Forms lvalue reference to const type of t. + 2) const rvalue reference overload is deleted to disallow rvalue arguments. + +.SH Possible implementation + + template + constexpr std::add_const_t& as_const(T& t) noexcept + { + return t; + } + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_as_const 201510L \fI(C++17)\fP std::as_const + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string mutableString = "Hello World!"; + auto&& constRef = std::as_const(mutableString); + + mutableString.clear(); // OK + // constRef.clear(); // Error: 'constRef' is 'const' qualified, + // but 'clear' is not marked const + + assert(&constRef == &mutableString); + assert(&std::as_const(mutableString) == &mutableString); + + using ExprType = std::remove_reference_t; + + static_assert(std::is_same_v, std::string>, + "ExprType should be some kind of string."); + static_assert(!std::is_same_v, + "ExprType shouldn't be a mutable string."); + } + +.SH See also + + is_const checks if a type is const-qualified + \fI(C++11)\fP \fI(class template)\fP + add_cv + add_const + add_volatile adds const and/or volatile specifiers to the given type + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remove_cv + remove_const + remove_volatile removes const and/or volatile specifiers from the given type + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ranges::as_const_view converts a view into a constant_range + views::as_const \fI(class template)\fP (range adaptor object) + (C++23) diff --git a/man/std::asctime.3 b/man/std::asctime.3 index 228b06f57..42b058215 100644 --- a/man/std::asctime.3 +++ b/man/std::asctime.3 @@ -1,23 +1,35 @@ -.TH std::asctime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::asctime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::asctime \- std::asctime + .SH Synopsis Defined in header char* asctime( const std::tm* time_ptr ); - Converts given calendar time std::tm to a textual representation. The resulting - string has the following format: + Converts given calendar time std::tm to a textual representation of the following + fixed 25-character form: Www Mmm dd hh:mm:ss yyyy\\n. + + * Www - three-letter English abbreviated day of the week from time_ptr->tm_wday, + one of Mon, Tue, Wed, Thu, Fri, Sat, Sun. + * Mmm - three-letter English abbreviated month name from time_ptr->tm_mon, one of + Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. + * dd - 2-digit day of the month from timeptr->tm_mday as if printed by sprintf + using %2d. + * hh - 2-digit hour from timeptr->tm_hour as if printed by sprintf using %.2d. + * mm - 2-digit minute from timeptr->tm_min as if printed by sprintf using %.2d. + * ss - 2-digit second from timeptr->tm_sec as if printed by sprintf using %.2d. + * yyyy - 4-digit year from timeptr->tm_year + 1900 as if printed by sprintf using + %4d. - Www Mmm dd hh:mm:ss yyyy + The behavior is undefined if any member of *time_ptr is outside its normal range. - * Www - the day of the week (one of Mon, Tue, Wed, Thu, Fri, Sat, Sun). - * Mmm - the month (one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, - Dec). - * dd - the day of the month - * hh - hours - * mm - minutes - * ss - seconds - * yyyy - years + The behavior is undefined if the calendar year indicated by time_ptr->tm_year has + more than 4 digits or is less than the year 1000. - The function does not support localization. + The function does not support localization, and the newline character cannot be + removed. + + The function modifies static storage and is not thread-safe. .SH Parameters @@ -32,40 +44,79 @@ .SH Notes This function returns a pointer to static data and is not thread-safe. POSIX marks - this function obsolete and recommends std::strftime instead. + this function obsolete and recommends locale-dependent std::strftime instead. In + std::locale("C") the std::strftime format string "%c\\n" will be an exact match to + std::asctime output, while in other locales the format string + "%a %b %e %H:%M:%S %Y\\n" will be a potentially closer but not always exact match. - The behavior is undefined if the output string would be longer than 25 characters, - if timeptr->tm_wday or timeptr->tm_mon are not within the expected ranges, or if - timeptr->tm_year exceeds INT_MAX-1990. + POSIX limits undefined behaviors only to the cases when the output string would be + longer than 25 characters, when timeptr->tm_wday or timeptr->tm_mon are not within + the expected ranges, or when timeptr->tm_year exceeds INT_MAX-1990. - Some implementations handle timeptr->tm_mday==0 as meaning the last day of the + Some implementations handle timeptr->tm_mday == 0 as meaning the last day of the preceding month. .SH Example - + // Run this code #include + #include #include - + int main() { - std::time_t result = std::time(NULL); - std::cout << std::asctime(std::localtime(&result)); + const std::time_t now = std::time(nullptr); + + for (const char* localeName : {"C", "en_US.utf8", "de_DE.utf8", "ja_JP.utf8"}) + { + std::cout << "locale " << localeName << ":\\n" << std::left; + std::locale::global(std::locale(localeName)); + + std::cout << std::setw(40) << " asctime" << std::asctime(std::localtime(&now)); + + // strftime output for comparison: + char buf[64]; + if (strftime(buf, sizeof buf, "%c\\n", std::localtime(&now))) + std::cout << std::setw(40) << " strftime %c" << buf; + + if (strftime(buf, sizeof buf, "%a %b %e %H:%M:%S %Y\\n", std::localtime(&now))) + std::cout << std::setw(40) << " strftime %a %b %e %H:%M:%S %Y" << buf; + + std::cout << '\\n'; + } } -.SH Output: +.SH Possible output: + + locale C: + asctime Wed Nov 4 00:45:01 2020 + strftime %c Wed Nov 4 00:45:01 2020 + strftime %a %b %e %H:%M:%S %Y Wed Nov 4 00:45:01 2020 + + locale en_US.utf8: + asctime Wed Nov 4 00:45:01 2020 + strftime %c Wed 04 Nov 2020 12:45:01 AM UTC + strftime %a %b %e %H:%M:%S %Y Wed Nov 4 00:45:01 2020 + + locale de_DE.utf8: + asctime Wed Nov 4 00:45:01 2020 + strftime %c Mi 04 Nov 2020 00:45:01 UTC + strftime %a %b %e %H:%M:%S %Y Mi Nov 4 00:45:01 2020 - Tue Dec 27 16:45:52 2011 + locale ja_JP.utf8: + asctime Wed Nov 4 00:45:01 2020 + strftime %c 2020年11月04日 00時45分01秒 + strftime %a %b %e %H:%M:%S %Y 水 11月 4 00:45:01 2020 .SH See also - ctime converts a time_t object to a textual representation - \fI(function)\fP - strftime converts a tm object to custom textual representation - \fI(function)\fP + ctime converts a std::time_t object to a textual representation + \fI(function)\fP + strftime converts a std::tm object to custom textual representation + \fI(function)\fP put_time formats and outputs a date/time value according to the specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP C documentation for asctime diff --git a/man/std::asin(std::complex).3 b/man/std::asin(std::complex).3 index c897055f3..625b06416 100644 --- a/man/std::asin(std::complex).3 +++ b/man/std::asin(std::complex).3 @@ -1,11 +1,14 @@ -.TH std::asin(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::asin(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::asin(std::complex) \- std::asin(std::complex) + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - complex asin( const complex& z ); + template< class T > \fI(since C++11)\fP + std::complex asin( const std::complex& z ); Computes complex arc sine of a complex value z. Branch cut exists outside the - interval [−1 ; +1] along the real axis. + interval [−1, +1] along the real axis. .SH Parameters @@ -13,11 +16,80 @@ .SH Return value - Complex arc sine of z in the range [0 ; π) along the real axis. + If no errors occur, complex arc sine of z is returned, in the range of a strip + unbounded along the imaginary axis and in the interval [−π/2, +π/2] along the real + axis. + + Errors and special cases are handled as if the operation is implemented by -i * + std::asinh(i * z), where i is the imaginary unit. + +.SH Notes + + Inverse sine (or arc sine) is a multivalued function and requires a branch cut on + the complex plane. The branch cut is conventionally placed at the line segments + (-∞,-1) and (1,∞) of the real axis. + + The mathematical definition of the principal value of arc sine is \\(\\small \\arcsin z + = -{\\rm i}\\ln({\\rm i}z+\\sqrt{1-z^2})\\)arcsin z = -iln(iz + + √ + 1-z2 + ). + + For any z, \\(\\small{ \\arcsin(z) = \\arccos(-z) - \\frac{\\pi}{2} }\\)asin(z) = acos(-z) + - + + π + 2 + + . + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z1(-2.0, 0.0); + std::cout << "asin" << z1 << " = " << std::asin(z1) << '\\n'; + + std::complex z2(-2.0, -0.0); + std::cout << "asin" << z2 << " (the other side of the cut) = " + << std::asin(z2) << '\\n'; + + // for any z, asin(z) = acos(−z) − pi / 2 + const double pi = std::acos(-1); + std::complex z3 = std::acos(z2) - pi / 2; + std::cout << "sin(acos" << z2 << " - pi / 2) = " << std::sin(z3) << '\\n'; + } + +.SH Output: + + asin(-2.000000,0.000000) = (-1.570796,1.316958) + asin(-2.000000,-0.000000) (the other side of the cut) = (-1.570796,-1.316958) + sin(acos(-2.000000,-0.000000) - pi / 2) = (2.000000,0.000000) .SH See also - acos(std::complex) computes arc cosine of a complex number (arccos(z)) - \fI(C++11)\fP \fI(function template)\fP - atan(std::complex) computes arc tangent of a complex number (arctan(z)) - \fI(C++11)\fP \fI(function template)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP + atan(std::complex) computes arc tangent of a complex number + \fI(C++11)\fP (\\({\\small\\arctan{z}}\\)arctan(z)) + \fI(function template)\fP + sin(std::complex) computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z)) + \fI(function template)\fP + asin + asinf computes arc sine (\\({\\small\\arcsin{x}}\\)arcsin(x)) + asinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + asin(std::valarray) applies the function std::asin to each element of valarray + \fI(function template)\fP + C documentation for + casin diff --git a/man/std::asin(std::valarray).3 b/man/std::asin(std::valarray).3 index 234548d47..eac65cc2b 100644 --- a/man/std::asin(std::valarray).3 +++ b/man/std::asin(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::asin(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::asin(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::asin(std::valarray) \- std::asin(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (asin) is used to perform the computation. If such function is - not available, std::asin is used due to argument dependent lookup. + not available, std::asin is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,16 +43,61 @@ valarray asin(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = asin(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + #include + + int main() + { + // take common y-values from unit circle + const double s22 = std::sqrt(2.0) / 2.0; + const double s32 = std::sqrt(3.0) / 2.0; + const std::valarray v1 = + {-1.0, -s32, -s22, -0.5, 0.0, 0.5, s22, s32, 1.0}; + + // fill with results of radians to degrees conversion + const std::valarray v2 = + std::asin(v1) * 180.0 / std::numbers::pi; + + for (std::cout << std::showpos; double n : v2) + std::cout << n << "° "; + std::cout << '\\n'; + } + +.SH Output: + + -90° -60° -45° -30° +0° +30° +45° +60° +90° + +.SH See also + + acos(std::valarray) applies the function std::acos to each element of valarray + \fI(function template)\fP + atan(std::valarray) applies the function std::atan to each element of valarray + \fI(function template)\fP + atan2(std::valarray) applies the function std::atan2 to a valarray and a value + \fI(function template)\fP + sin(std::valarray) applies the function std::sin to each element of valarray + \fI(function template)\fP + asin + asinf computes arc sine (\\({\\small\\arcsin{x}}\\)arcsin(x)) + asinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + asin(std::complex) computes arc sine of a complex number + \fI(C++11)\fP (\\({\\small\\arcsin{z}}\\)arcsin(z)) + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::asin,std::asinf,std::asinl.3 b/man/std::asin,std::asinf,std::asinl.3 new file mode 100644 index 000000000..0ebc5f044 --- /dev/null +++ b/man/std::asin,std::asinf,std::asinl.3 @@ -0,0 +1,147 @@ +.TH std::asin,std::asinf,std::asinl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::asin,std::asinf,std::asinl \- std::asin,std::asinf,std::asinl + +.SH Synopsis + Defined in header + float asin ( float num ); + + double asin ( double num ); (until C++23) + + long double asin ( long double num ); + /* floating-point-type */ (since C++23) + asin ( /* floating-point-type */ num ); (constexpr since C++26) + float asinf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double asinl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double asin ( Integer num ); + + 1-3) Computes the principal value of the arc sine of num. + The library provides overloads of std::asin for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the arc sine of num (arcsin(num)) in the range [- + + π + 2 + + , + + + π + 2 + + ], is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is outside the range [-1.0, 1.0]. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, it is returned unmodified. + * If |num| > 1, a domain error occurs and NaN is returned. + * if the argument is NaN, NaN is returned. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::asin(num) has the same effect as std::asin(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "asin(1.0) = " << asin(1) << '\\n' + << "2*asin(1.0) = " << 2 * asin(1) << '\\n' + << "asin(-0.5) = " << asin(-0.5) << '\\n' + << "6*asin(-0.5) =" << 6 * asin(-0.5) << '\\n'; + + // special values + std::cout << "asin(0.0) = " << asin(0) << " asin(-0.0)=" << asin(-0.0) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "asin(1.1) = " << asin(1.1) << '\\n'; + + if (errno == EDOM) + std::cout << " errno == EDOM: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised" << '\\n'; + } + +.SH Possible output: + + asin(1.0) = 1.5708 + 2*asin(1.0) = 3.14159 + asin(-0.5) = -0.523599 + 6*asin(-0.5) = -3.14159 + asin(0.0) = 0 asin(-0.0)=-0 + asin(1.1) = nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised + +.SH See also + + acos + acosf computes arc cosine (\\({\\small\\arccos{x}}\\)arccos(x)) + acosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan + atanf computes arc tangent (\\({\\small\\arctan{x}}\\)arctan(x)) + atanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan2 + atan2f arc tangent, using signs to determine quadrants + atan2l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sin + sinf computes sine (\\({\\small\\sin{x}}\\)sin(x)) + sinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + asin(std::complex) computes arc sine of a complex number + \fI(C++11)\fP (\\({\\small\\arcsin{z}}\\)arcsin(z)) + \fI(function template)\fP + asin(std::valarray) applies the function std::asin to each element of valarray + \fI(function template)\fP + C documentation for + asin diff --git a/man/std::asin.3 b/man/std::asin.3 deleted file mode 100644 index b7f0950da..000000000 --- a/man/std::asin.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH std::asin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float asin( float arg ); - double asin( double arg ); - long double asin( long double arg ); - double asin( Integral arg ); \fI(since C++11)\fP - - Computes arc sine of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Arc sine of arg in radians in the range of [-π/2; π/2] radians. - - Domain error occurs if arg is outside the range [-1.0; 1.0]. NaN is returned in that - case and FE_INVALID is raised. - - std::asin(+0) returns +0. std::asin(-0) returns -0. - -.SH See also - - acos computes arc cosine (arccos(x)) - \fI(function)\fP - atan computes arc tangent (arctan(x)) - \fI(function)\fP - atan2 arc tangent, using signs to determine quadrants - \fI(function)\fP - sin computes sine (sin(x)) - \fI(function)\fP - asin(std::complex) computes arc sine of a complex number (arcsin(z)) - \fI(C++11)\fP \fI(function template)\fP - asin(std::valarray) applies the function std::asin to each element of valarray - \fI(function template)\fP - C documentation for - asin diff --git a/man/std::asinh(std::complex).3 b/man/std::asinh(std::complex).3 index 4ce77eb89..9d9e3c812 100644 --- a/man/std::asinh(std::complex).3 +++ b/man/std::asinh(std::complex).3 @@ -1,10 +1,14 @@ -.TH std::asinh(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::asinh(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::asinh(std::complex) \- std::asinh(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP complex asinh( const complex& z ); - Computes complex area hyperbolic sine of a complex value z. + Computes complex arc hyperbolic sine of a complex value z with branch cuts outside + the interval [−i; +i] along the imaginary axis. .SH Parameters @@ -12,13 +16,104 @@ .SH Return value - Complex area hyperbolic sine of z + If no errors occur, the complex arc hyperbolic sine of z is returned, in the range + of a strip mathematically unbounded along the real axis and in the interval [−iπ/2; + +iπ/2] along the imaginary axis. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::asinh(std::conj(z)) == std::conj(std::asinh(z)) + * std::asinh(-z) == -std::asinh(z) + * If z is (+0,+0), the result is (+0,+0) + * If z is (x,+∞) (for any positive finite x), the result is (+∞,π/2) + * If z is (x,NaN) (for any finite x), the result is (NaN,NaN) and FE_INVALID may + be raised + * If z is (+∞,y) (for any positive finite y), the result is (+∞,+0) + * If z is (+∞,+∞), the result is (+∞,π/4) + * If z is (+∞,NaN), the result is (+∞,NaN) + * If z is (NaN,+0), the result is (NaN,+0) + * If z is (NaN,y) (for any finite nonzero y), the result is (NaN,NaN) and + FE_INVALID may be raised + * If z is (NaN,+∞), the result is (±∞,NaN) (the sign of the real part is + unspecified) + * If z is (NaN,NaN), the result is (NaN,NaN) + +.SH Notes + + Although the C++ standard names this function "complex arc hyperbolic sine", the + inverse functions of the hyperbolic functions are the area functions. Their argument + is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse + hyperbolic sine", and, less common, "complex area hyperbolic sine". + + Inverse hyperbolic sine is a multivalued function and requires a branch cut on the + complex plane. The branch cut is conventionally placed at the line segments (-i∞,-i) + and (i,i∞) of the imaginary axis. + + The mathematical definition of the principal value of the inverse hyperbolic sine is + asinh z = ln(z + + √ + 1+z2 + ). + + For any z, asinh(z) = + + asin(iz) + i + + . + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z1(0.0, -2.0); + std::cout << "asinh" << z1 << " = " << std::asinh(z1) << '\\n'; + + std::complex z2(-0.0, -2); + std::cout << "asinh" << z2 << " (the other side of the cut) = " + << std::asinh(z2) << '\\n'; + + // for any z, asinh(z) = asin(iz) / i + std::complex z3(1.0, 2.0); + std::complex i(0.0, 1.0); + std::cout << "asinh" << z3 << " = " << std::asinh(z3) << '\\n' + << "asin" << z3 * i << " / i = " << std::asin(z3 * i) / i << '\\n'; + } + +.SH Output: + + asinh(0.000000,-2.000000) = (1.316958,-1.570796) + asinh(-0.000000,-2.000000) (the other side of the cut) = (-1.316958,-1.570796) + asinh(1.000000,2.000000) = (1.469352,1.063440) + asin(-2.000000,1.000000) / i = (1.469352,1.063440) .SH See also - sin(std::complex) computes sine of a complex number (sin(z)) - \fI(function template)\fP - sinh(std::complex) computes hyperbolic sine of a complex number (sh(z)) - \fI(function template)\fP - asin(std::complex) computes arc sine of a complex number (arcsin(z)) - \fI(C++11)\fP \fI(function template)\fP + acosh(std::complex) computes area hyperbolic cosine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arcosh}{z}}\\)arcosh(z)) + \fI(function template)\fP + atanh(std::complex) computes area hyperbolic tangent of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{artanh}{z}}\\)artanh(z)) + \fI(function template)\fP + computes hyperbolic sine of a complex number + sinh(std::complex) (\\({\\small\\sinh{z}}\\)sinh(z)) + \fI(function template)\fP + asinh + asinhf computes the inverse hyperbolic sine + asinhl (\\({\\small\\operatorname{arsinh}{x}}\\)arsinh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + casinh diff --git a/man/std::asinh,std::asinhf,std::asinhl.3 b/man/std::asinh,std::asinhf,std::asinhl.3 new file mode 100644 index 000000000..813d9fdc4 --- /dev/null +++ b/man/std::asinh,std::asinhf,std::asinhl.3 @@ -0,0 +1,116 @@ +.TH std::asinh,std::asinhf,std::asinhl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::asinh,std::asinhf,std::asinhl \- std::asinh,std::asinhf,std::asinhl + +.SH Synopsis + Defined in header + float asinh ( float num ); + + double asinh ( double num ); (until C++23) + + long double asinh ( long double num ); + /* floating-point-type */ (since C++23) + asinh ( /* floating-point-type */ num ); (constexpr since C++26) + float asinhf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double asinhl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double asinh ( Integer num ); + + 1-3) Computes the inverse hyperbolic sine of num. + The library provides overloads of std::asinh for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the inverse hyperbolic sine of num (sinh-1 + (num), or arsinh(num)), is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0 or ±∞, it is returned unmodified. + * if the argument is NaN, NaN is returned. + +.SH Notes + + Although the C standard (to which C++ refers for this function) names this function + "arc hyperbolic sine", the inverse functions of the hyperbolic functions are the + area functions. Their argument is the area of a hyperbolic sector, not an arc. The + correct name is "inverse hyperbolic sine" (used by POSIX) or "area hyperbolic sine". + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::asinh(num) has the same effect as std::asinh(static_cast(num)). + +.SH Examples + + +// Run this code + + #include + #include + + int main() + { + std::cout << "asinh(1) = " << std::asinh(1) << '\\n' + << "asinh(-1) = " << std::asinh(-1) << '\\n'; + + // special values + std::cout << "asinh(+0) = " << std::asinh(+0.0) << '\\n' + << "asinh(-0) = " << std::asinh(-0.0) << '\\n'; + } + +.SH Output: + + asinh\fB(1)\fP = 0.881374 + asinh(-1) = -0.881374 + asinh(+0) = 0 + asinh(-0) = -0 + +.SH See also + + acosh + acoshf computes the inverse hyperbolic cosine + acoshl (\\({\\small\\operatorname{arcosh}{x}}\\)arcosh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atanh + atanhf computes the inverse hyperbolic tangent + atanhl (\\({\\small\\operatorname{artanh}{x}}\\)artanh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sinh + sinhf computes hyperbolic sine (\\({\\small\\sinh{x}}\\)sinh(x)) + sinhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + asinh(std::complex) computes area hyperbolic sine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arsinh}{z}}\\)arsinh(z)) + \fI(function template)\fP + C documentation for + asinh + +.SH External links + + Weisstein, Eric W. "Inverse Hyperbolic Sine." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::asinh.3 b/man/std::asinh.3 deleted file mode 100644 index 907fda180..000000000 --- a/man/std::asinh.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::asinh 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float asinh( float arg ); \fI(since C++11)\fP - double asinh( double arg ); \fI(since C++11)\fP - long double asinh( long double arg ); \fI(since C++11)\fP - double asinh( Integral arg ); \fI(since C++11)\fP - - Computes area hyperbolic sine of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Inverse hyperbolic sine of arg. - -.SH See also - - acosh area hyperbolic cosine - \fI(C++11)\fP \fI(function)\fP - atanh area hyperbolic tangent - \fI(C++11)\fP \fI(function)\fP - sinh computes hyperbolic sine (sh(x)) - \fI(function)\fP - asinh(std::complex) computes area hyperbolic sine of a complex number - \fI(C++11)\fP \fI(function template)\fP - C documentation for - asinh - -.SH External links - - Weisstein, Eric W. "Inverse Hyperbolic Sine." From MathWorld--A Wolfram Web - Resource. diff --git a/man/std::assignable_from.3 b/man/std::assignable_from.3 new file mode 100644 index 000000000..5bc4ba28e --- /dev/null +++ b/man/std::assignable_from.3 @@ -0,0 +1,38 @@ +.TH std::assignable_from 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::assignable_from \- std::assignable_from + +.SH Synopsis + Defined in header + template< class LHS, class RHS > + + concept assignable_from = + std::is_lvalue_reference_v && + std::common_reference_with< + const std::remove_reference_t&, \fI(since C++20)\fP + const std::remove_reference_t&> && + requires(LHS lhs, RHS&& rhs) { + { lhs = std::forward(rhs) } -> std::same_as; + + }; + + The concept assignable_from specifies that an expression of the type and + value category specified by RHS can be assigned to an lvalue expression whose type + is specified by LHS. + +.SH Notes + + Assignment need not be a total function. In particular, if assigning to some object + x can cause some other object y to be modified, then x = y is likely not in the + domain of =. This typically happens if the right operand is owned directly or + indirectly by the left operand (e.g., with smart pointers to nodes in a node-based + data structure, or with something like std::vector). + +.SH See also + + is_assignable + is_trivially_assignable checks if a type has an assignment operator for a specific + is_nothrow_assignable argument + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::assoc_laguerre,std::assoc_laguerref,std::assoc_laguerrel.3 b/man/std::assoc_laguerre,std::assoc_laguerref,std::assoc_laguerrel.3 new file mode 100644 index 000000000..1db2943ee --- /dev/null +++ b/man/std::assoc_laguerre,std::assoc_laguerref,std::assoc_laguerrel.3 @@ -0,0 +1,122 @@ +.TH std::assoc_laguerre,std::assoc_laguerref,std::assoc_laguerrel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::assoc_laguerre,std::assoc_laguerref,std::assoc_laguerrel \- std::assoc_laguerre,std::assoc_laguerref,std::assoc_laguerrel + +.SH Synopsis + double assoc_laguerre ( unsigned int n, unsigned int m, double x ); + + double assoc_laguerre ( unsigned int n, unsigned int m, float x ); + double assoc_laguerre ( unsigned int n, unsigned int m, long double x ); \fB(1)\fP + float assoc_laguerref( unsigned int n, unsigned int m, float x ); + + long double assoc_laguerrel( unsigned int n, unsigned int m, long double x ); + double assoc_laguerre ( unsigned int n, unsigned int m, IntegralType x ); \fB(2)\fP + + 1) Computes the associated Laguerre polynomials of the degree n, order m, and + argument x. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, assoc_laguerre is only guaranteed to be available in + if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at + least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + +.SH Parameters + + n - the degree of the polynomial, a value of unsigned integer type + m - the order of the polynomial, a value of unsigned integer type + x - the argument, a value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the associated Laguerre polynomial of x, that is (-1)m + + dm + dxm + + L + n + m(x), is returned (where L + n + m(x) is the unassociated Laguerre polynomial, std::laguerre(n + m, x)). + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If x is negative, a domain error may occur. + * If n or m is greater or equal to 128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The associated Laguerre polynomials are the polynomial solutions of the equation + xy,, + + (m + 1 - x)y, + + ny = 0. + + The first few are: + + * assoc_laguerre(0, m, x) = 1. + * assoc_laguerre(1, m, x) = -x + m + 1. + * assoc_laguerre(2, m, x) = + + 1 + 2 + + [x2 + - 2(m + 2)x + (m + 1)(m + 2)]. + * assoc_laguerre(3, m, x) = + + 1 + 6 + + [-x3 + - 3(m + 3)x2 + - 3(m + 2)(m + 3)x + (m + 1)(m + 2)(m + 3)]. + +.SH Example + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + double L1(unsigned m, double x) + { + return -x + m + 1; + } + + double L2(unsigned m, double x) + { + return 0.5 * (x * x - 2 * (m + 2) * x + (m + 1) * (m + 2)); + } + + int main() + { + // spot-checks + std::cout << std::assoc_laguerre(1, 10, 0.5) << '=' << L1(10, 0.5) << '\\n' + << std::assoc_laguerre(2, 10, 0.5) << '=' << L2(10, 0.5) << '\\n'; + } + +.SH Output: + + 10.5=10.5 + 60.125=60.125 + +.SH See also + + laguerre Laguerre polynomials + laguerref \fI(function)\fP + laguerrel + +.SH External links + + Weisstein, Eric W. "Associated Laguerre Polynomial." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::assoc_legendre,std::assoc_legendref,std::assoc_legendrel.3 b/man/std::assoc_legendre,std::assoc_legendref,std::assoc_legendrel.3 new file mode 100644 index 000000000..7b592bdd0 --- /dev/null +++ b/man/std::assoc_legendre,std::assoc_legendref,std::assoc_legendrel.3 @@ -0,0 +1,128 @@ +.TH std::assoc_legendre,std::assoc_legendref,std::assoc_legendrel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::assoc_legendre,std::assoc_legendref,std::assoc_legendrel \- std::assoc_legendre,std::assoc_legendref,std::assoc_legendrel + +.SH Synopsis + double assoc_legendre( unsigned int n, unsigned int m, double x ); + + double assoc_legendre( unsigned int n, unsigned int m, float x ); + double assoc_legendre( unsigned int n, unsigned int m, long double x ); \fB(1)\fP + float assoc_legendref( unsigned int n, unsigned int m, float x ); + + long double assoc_legendrel( unsigned int n, unsigned int m, long double x ); + double assoc_legendre( unsigned int n, unsigned int m, IntegralType x ); \fB(2)\fP + + 1) Computes the associated Legendre polynomials of the degree n, order m, and + argument x. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, assoc_legendre is only guaranteed to be available in + if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at + least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + +.SH Parameters + + n - the degree of the polynomial, a value of unsigned integer type + m - the order of the polynomial, a value of unsigned integer type + x - the argument, a value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the associated Legendre polynomial Pm + n of x, that is (1 - x2 + )m/2 + + dm + dxm + + P + n(x), is returned (where P + n(x) is the unassociated Legendre polynomial, std::legendre(n, x)). + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If |x| > 1, a domain error may occur. + * If n is greater or equal to 128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The first few associated Legendre polynomials are: + + * assoc_legendre(0, 0, x) = 1. + * assoc_legendre(1, 0, x) = x. + * assoc_legendre(1, 1, x) = -(1 - x2 + )1/2 + . + * assoc_legendre(2, 0, x) = + + 1 + 2 + + (3x2 + - 1). + * assoc_legendre(2, 1, x) = -3x(1 - x2 + )1/2 + . + * assoc_legendre(2, 2, x) = 3(1 - x2 + ). + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + double P20(double x) + { + return 0.5 * (3 * x * x - 1); + } + + double P21(double x) + { + return -3.0 * x * std::sqrt(1 - x * x); + } + + double P22(double x) + { + return 3 * (1 - x * x); + } + + int main() + { + // spot-checks + std::cout << std::assoc_legendre(2, 0, 0.5) << '=' << P20(0.5) << '\\n' + << std::assoc_legendre(2, 1, 0.5) << '=' << P21(0.5) << '\\n' + << std::assoc_legendre(2, 2, 0.5) << '=' << P22(0.5) << '\\n'; + } + +.SH Output: + + -0.125=-0.125 + -1.29904=-1.29904 + 2.25=2.25 + +.SH See also + + legendre Legendre polynomials + legendref \fI(function)\fP + legendrel + +.SH External links + + Weisstein, Eric W. "Associated Legendre Polynomial." From MathWorld--A Wolfram Web + Resource. diff --git a/man/std::assume_aligned.3 b/man/std::assume_aligned.3 new file mode 100644 index 000000000..2b299c44a --- /dev/null +++ b/man/std::assume_aligned.3 @@ -0,0 +1,66 @@ +.TH std::assume_aligned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::assume_aligned \- std::assume_aligned + +.SH Synopsis + Defined in header + template< std::size_t N, class T > \fI(since C++20)\fP + [[nodiscard]] constexpr T* assume_aligned( T* ptr ); + + Informs the implementation that the object ptr points to is aligned to at least N. + The implementation may use this information to generate more efficient code, but it + might only make this assumption if the object is accessed via the return value of + assume_aligned. + + N must be a power of 2. The behavior is undefined if ptr does not point to an object + of type T (ignoring cv-qualification at every level), or if the object's alignment + is not at least N. + +.SH Return value + + ptr. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + To ensure that the program benefits from the optimizations enabled by + assume_aligned, it is important to access the object via its return value: + + void f(int* p) + { + int* p1 = std::assume_aligned<256>(p); + // Use p1, not p, to ensure benefit from the alignment assumption. + // However, the program has undefined behavior if p is not aligned + // regardless of whether p1 is used. + } + + It is up to the program to ensure that the alignment assumption actually holds. A + call to assume_aligned does not cause the compiler to verify or enforce this. + + Feature-test macro Value Std Feature + __cpp_lib_assume_aligned 201811L (C++20) std::assume_aligned + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + alignof operator\fI(C++11)\fP queries alignment requirements of a type + alignas specifier\fI(C++11)\fP specifies that the storage for the variable should be + aligned by specific amount + aligned_storage defines the type suitable for use as uninitialized + \fI(C++11)\fP(deprecated in C++23) storage for types of given size + \fI(class template)\fP + align aligns a pointer in a buffer + \fI(C++11)\fP \fI(function)\fP + specifies that the expression will always evaluate to + [[assume(expression)]](C++23) true at a given point + (attribute specifier) + +.SH Category: + * Todo no example diff --git a/man/std::async.3 b/man/std::async.3 index c3bb3abd3..bdb3f6709 100644 --- a/man/std::async.3 +++ b/man/std::async.3 @@ -1,122 +1,307 @@ -.TH std::async 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::async 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::async \- std::async + .SH Synopsis Defined in header - template< class Function, class... Args> + template< class F, class... Args > + (since + std::future::type( (until + typename std::decay::type...)>::type> C++17) + + async( F&& f, Args&&... args ); + template< class F, class... Args > + (since + std::future, C++17) + std::decay_t...>> (until + C++20) + async( F&& f, Args&&... args ); + template< class F, class... Args > - std::future::type> \fB(1)\fP \fI(since C++11)\fP + [[nodiscard]] + std::future, (since + C++20) + std::decay_t...>> - async( Function&& f, Args&&... args ); - template< class Function, class... Args > + async( F&& f, Args&&... args ); \fB(1)\fP + template< class F, class... Args > + (since + std::future::type( (until + typename std::decay::type...)>::type> C++17) - std::future::type> \fB(2)\fP \fI(since C++11)\fP + async( std::launch policy, F&& f, Args&&... args ); + template< class F, class... Args > + (since + std::future, C++17) + std::decay_t...>> \fB(2)\fP (until + C++20) + async( std::launch policy, F&& f, Args&&... args ); + template< class F, class... Args > - async( std::launch policy, Function&& f, Args&&... args ); + [[nodiscard]] + std::future, (since + C++20) + std::decay_t...>> - The template function async runs the function f asynchronously (potentially in a - separate thread) and returns a std::future that will eventually hold the result of - that function call. + async( std::launch policy, F&& f, Args&&... args ); - 1) Behaves the same as async(std::launch::async | std::launch::deferred, f, - args...). In other words, f may be executed in another thread or it may be run - synchronously when the resulting std::future is queried for a value. + The function template std::async runs the function f asynchronously (potentially in + a separate thread which might be a part of a thread pool) and returns a std::future + that will eventually hold the result of that function call. + 1) Behaves as if \fB(2)\fP is called with policy being std::launch::async | + std::launch::deferred. 2) Calls a function f with arguments args according to a specific launch policy - policy: + policy (see below). - * If the async flag is set (i.e. policy & std::launch::async != 0), then async - executes the function f on a separate thread of execution as if spawned by - std::thread(f, args...), except that if the function f returns a value or throws - an exception, it is stored in the shared state accessible through the - std::future that async returns to the caller. + If any of the following conditions is satisfied, the program is + ill-formed: - * If the deferred flag is set (i.e. policy & std::launch::deferred != 0), then - async converts args... the same way as by std::thread constructor, but does not - spawn a new thread of execution. Instead, lazy evaluation is performed: the - first call to a non-timed wait function on the std::future that async returned - to the caller will cause f(args...) to be executed in the current thread. All - further accesses to the same std::future will return the result immediately. + * F is not MoveConstructible. \fI(until C++20)\fP + * Any type in Args is not MoveConstructible. + * INVOKE(decay-copy(std::forward(f)), + decay-copy(std::forward(args))...) is not a valid + expression. + If any of the following is false, the program is ill-formed: - * If both the std::launch::async and std::launch::deferred flags are set in - policy, it is up to the implementation whether to perform asynchronous execution - or lazy evaluation. + * std::is_constructible_v, F> \fI(since C++20)\fP + * (std::is_constructible_v, Args> && ...) + * std::is_invocable_v, std::decay_t...> - * \fI(C++14)\fP If neither std::launch::async nor std::launch::deferred, nor any - implementation-defined policy flag is set in policy, the behavior is undefined. + The call to std::async synchronizes with the call to f, and the completion of f is + sequenced before making the shared state ready. .SH Parameters - f - Callable object to call - args... - parameters to pass to f - bitmask value, where individual bits control the allowed methods of - execution - policy - - Bit Explanation - std::launch::async enable asynchronous evaluation - std::launch::deferred enable lazy evaluation + f - Callable object to call + args - parameters to pass to f + policy - bitmask value, where individual bits control the allowed methods of + execution .SH Return value - std::future referring to the return value of the function. + std::future referring to the shared state created by this call to std::async. + + Launch policies + + Async invocation + + If the async flag is set (i.e. (policy & std::launch::async) != 0), then + + std::async calls INVOKE(decay-copy(std::forward(f)), + decay-copy(std::forward(args))...) as if in a new thread (until C++23) + of execution represented by a std::thread object. + std::async calls std::invoke(auto(std::forward(f)), + auto(std::forward(args))...) as if in a new thread (since C++23) + of execution represented by a std::thread object. + + The calls of decay-copy are evaluated + (until C++23) + The values produced by auto are materialized + (since C++23) in the current thread. If the function f returns a value or throws an + exception, it is stored in the shared state accessible through the std::future that + std::async returns to the caller. + + Deferred invocation + + If the deferred flag is set (i.e. (policy & std::launch::deferred) != 0), then + std::async stores + decay-copy(std::forward(f)) and decay-copy(std::forward(args))... + (until C++23) + auto(std::forward(f)) and auto(std::forward(args))... + (since C++23) in the shared state. + + Lazy evaluation is performed: + + * The first call to a non-timed wait function on the std::future that std::async + returned to the caller will evaluate INVOKE(std::move(g), std::move(xyz)) in the + current thread (which does not have to be the thread that originally called + std::async), where + + * g is the stored value of + decay-copy(std::forward(f)) + (until C++23) + auto(std::forward(f)) + (since C++23) and + * xyz is the stored copy of + decay-copy(std::forward(args))... + (until C++23) + auto(std::forward(args))... + (since C++23). + * The result or exception is placed in the shared state associated with the + returned std::future and only then it is made ready. All further accesses to the + same std::future will return the result immediately. + + Other policies + + If neither std::launch::async nor std::launch::deferred, nor any + implementation-defined policy flag is set in policy, the behavior is undefined. + + Policy selection + + If more than one flag is set, it is implementation-defined which policy is selected. + For the default (both the std::launch::async and std::launch::deferred flags are set + in policy), standard recommends (but does not require) utilizing available + concurrency, and deferring any additional tasks. + + If the std::launch::async policy is chosen, + + * a call to a waiting function on an asynchronous return object that shares the + shared state created by this std::async call blocks until the associated thread + has completed, as if joined, or else time out; and + * the associated thread completion synchronizes-with the successful return from + the first function that is waiting on the shared state, or with the return of + the last function that releases the shared state, whichever comes first. .SH Exceptions - Throws std::system_error with error condition - std::errc::resource_unavailable_try_again if the launch policy is std::launch::async - and the implementation is unable to start a new thread. + Throws + + * std::bad_alloc, if the memory for the internal data structures cannot be + allocated, or + * std::system_error with error condition + std::errc::resource_unavailable_try_again, if policy == std::launch::async and + the implementation is unable to start a new thread. + * If policy is std::launch::async | std::launch::deferred or has additional + bits set, it will fall back to deferred invocation or the + implementation-defined policies in this case. .SH Notes The implementation may extend the behavior of the first overload of std::async by enabling additional (implementation-defined) bits in the default launch policy. - One drawback with the current definition of std::async is that the associated state - of an operation launched by std::async can cause the returned std::future's - destructor to block until the operation is complete. This can limit composability - and result in code that appears to run in parallel but in reality runs sequentially. - For example: + Examples of implementation-defined launch policies are the sync policy (execute + immediately, within the std::async call) and the task policy (similar to std::async, + but thread-locals are not cleared) - -// Run this code + If the std::future obtained from std::async is not moved from or bound to a + reference, the destructor of the std::future will block at the end of the full + expression until the asynchronous operation completes, essentially making code such + as the following synchronous: - { - std::async(std::launch::async, []{ f(); }); - std::async(std::launch::async, []{ g(); }); // does not run until f() completes - } + std::async(std::launch::async, []{ f(); }); // temporary's dtor waits for f() + std::async(std::launch::async, []{ g(); }); // does not start until f() completes - In the above code, f() and g() run sequentially because the destruction of the - returned future blocks until each operation has finished. + Note that the destructors of std::futures obtained by means other than a call to + std::async never block. .SH Example - + // Run this code - #include - #include #include - #include #include - - template - int parallel_sum(RAIter beg, RAIter end) + #include + #include + #include + #include + #include + + std::mutex m; + + struct X + { + void foo(int i, const std::string& str) + { + std::lock_guard lk(m); + std::cout << str << ' ' << i << '\\n'; + } + + void bar(const std::string& str) + { + std::lock_guard lk(m); + std::cout << str << '\\n'; + } + + int operator()(int i) + { + std::lock_guard lk(m); + std::cout << i << '\\n'; + return i + 10; + } + }; + + template + int parallel_sum(RandomIt beg, RandomIt end) { - typename RAIter::difference_type len = end-beg; - if(len < 1000) + auto len = end - beg; + if (len < 1000) return std::accumulate(beg, end, 0); - - RAIter mid = beg + len/2; + + RandomIt mid = beg + len / 2; auto handle = std::async(std::launch::async, - parallel_sum, mid, end); + parallel_sum, mid, end); int sum = parallel_sum(beg, mid); return sum + handle.get(); } - + int main() { std::vector v(10000, 1); std::cout << "The sum is " << parallel_sum(v.begin(), v.end()) << '\\n'; - } -.SH Output: + X x; + // Calls (&x)->foo(42, "Hello") with default policy: + // may print "Hello 42" concurrently or defer execution + auto a1 = std::async(&X::foo, &x, 42, "Hello"); + // Calls x.bar("world!") with deferred policy + // prints "world!" when a2.get() or a2.wait() is called + auto a2 = std::async(std::launch::deferred, &X::bar, x, "world!"); + // Calls X()(43); with async policy + // prints "43" concurrently + auto a3 = std::async(std::launch::async, X(), 43); + a2.wait(); // prints "world!" + std::cout << a3.get() << '\\n'; // prints "53" + } // if a1 is not done at this point, destructor of a1 prints "Hello 42" here + +.SH Possible output: The sum is 10000 + 43 + world! + 53 + Hello 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + return type incorrect and value corrected return type and + LWG 2021 C++11 category clarified that rvalues are + of arguments unclear in the deferred used + case + it was unclear whether + std::system_error can only be thrown if + LWG 2078 C++11 may be thrown if policy specifies policy == + other std::launch::async + launch policies besides + std::launch::async + timed waiting functions could not + LWG 2100 C++11 timeout allowed + if std::launch::async policy is used + the behavior was unclear if no + LWG 2120 C++11 standard the behavior is + or implementation-defined policy is undefined in this case + set + std::async might not throw + LWG 2752 C++11 std::bad_alloc if the throws + memory for the internal data + structures cannot be allocated + (the decayed types of) F and the + LWG 3476 C++20 argument types removed these + were directly required to be move requirements^[1] + constructible + + 1. ↑ The move-constructibility is already indirectly required by + std::is_constructible_v. + +.SH See also + + future waits for a value that is set asynchronously + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::at_quick_exit.3 b/man/std::at_quick_exit.3 index 38143b90e..9a7f773c3 100644 --- a/man/std::at_quick_exit.3 +++ b/man/std::at_quick_exit.3 @@ -1,42 +1,83 @@ -.TH std::at_quick_exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::at_quick_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::at_quick_exit \- std::at_quick_exit + .SH Synopsis Defined in header - extern "C" int at_quick_exit( void (*func)() ); - extern "C++" int at_quick_exit( void (*func)() ); + int at_quick_exit( /*atexit-handler*/* func ) noexcept; \fB(1)\fP \fI(since C++11)\fP + int at_quick_exit( /*c-atexit-handler*/* func ) noexcept; + extern "C++" using /*atexit-handler*/ = void(); \fB(2)\fP (exposition only*) + extern "C" using /*c-atexit-handler*/ = void(); Registers the function pointed to by func to be called on quick program termination (via std::quick_exit). Calling the function from several threads does not induce a data race. The - implementation shall support the registration of at least 32 functions. + implementation is guaranteed to support the registration of at least 32 functions. + The exact limit is implementation-defined. + + The registered functions will not be called on normal program termination. If a + function need to be called in that case, std::atexit must be used. .SH Parameters - func - pointer to a function to be called on normal program termination + func - pointer to a function to be called on quick program termination .SH Return value 0 if the registration succeeds, nonzero value otherwise. -.SH Exceptions +.SH Notes - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + The two overloads are distinct because the types of the parameter func are distinct + (language linkage is part of its type). .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + void f1() + { + std::cout << "pushed first" << std::endl; // flush is intentional + } + + extern "C" void f2() + { + std::cout << "pushed second\\n"; + } + + int main() + { + auto f3 = [] + { + std::cout << "pushed third\\n"; + }; + + std::at_quick_exit(f1); + std::at_quick_exit(f2); + std::at_quick_exit(f3); + std::quick_exit(0); + } + +.SH Output: + + pushed third + pushed second + pushed first .SH See also - atexit registers a function to be called on std::exit() invocation - \fI(function)\fP + abort causes abnormal program termination (without cleaning up) + \fI(function)\fP + exit causes normal program termination with cleaning up + \fI(function)\fP + atexit registers a function to be called on std::exit() invocation + \fI(function)\fP + quick_exit causes quick program termination without completely cleaning up + \fI(C++11)\fP \fI(function)\fP C documentation for at_quick_exit - -.SH Category: - - * Todo no example diff --git a/man/std::atan(std::complex).3 b/man/std::atan(std::complex).3 index 78c9efc7e..f992b6284 100644 --- a/man/std::atan(std::complex).3 +++ b/man/std::atan(std::complex).3 @@ -1,11 +1,14 @@ -.TH std::atan(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atan(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atan(std::complex) \- std::atan(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP complex atan( const complex& z ); Computes complex arc tangent of a complex value z. Branch cut exists outside the - interval [−i ; +i] along the imaginary axis. + interval [−i, +i] along the imaginary axis. .SH Parameters @@ -13,11 +16,71 @@ .SH Return value - Complex arc tangent of z in the range [−iπ/2 ; +iπ/2] along the imaginary axis. + If no errors occur, complex arc tangent of z is returned, in the range of a strip + unbounded along the imaginary axis and in the interval [−π/2, +π/2] along the real + axis. + + Errors and special cases are handled as if the operation is implemented by -i + * std::atanh(i * z), where i is the imaginary unit. + +.SH Notes + + Inverse tangent (or arc tangent) is a multivalued function and requires a branch cut + on the complex plane. The branch cut is conventionally placed at the line segments + (-∞i,-i) and (+i,+∞i) of the imaginary axis. + + The mathematical definition of the principal value of inverse tangent is atan z = - + + 1 + 2 + + i [ln(1 - iz) - ln (1 + iz)]. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z1(0.0, 2.0); + std::cout << "atan" << z1 << " = " << std::atan(z1) << '\\n'; + + std::complex z2(-0.0, 2.0); + std::cout << "atan" << z2 << " (the other side of the cut) = " + << std::atan(z2) << '\\n'; + + std::complex z3(0.0, INFINITY); + std::cout << "2 * atan" << z3 << " = " << 2.0 * std::atan(z3) << '\\n'; + } + +.SH Output: + + atan(0.000000,2.000000) = (1.570796,0.549306) + atan(-0.000000,2.000000) (the other side of the cut) = (-1.570796,0.549306) + 2 * atan(0.000000,inf) = (3.141593,0.000000) .SH See also - asin(std::complex) computes arc sine of a complex number (arcsin(z)) - \fI(C++11)\fP \fI(function template)\fP - acos(std::complex) computes arc cosine of a complex number (arccos(z)) - \fI(C++11)\fP \fI(function template)\fP + asin(std::complex) computes arc sine of a complex number + \fI(C++11)\fP (\\({\\small\\arcsin{z}}\\)arcsin(z)) + \fI(function template)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP + tan(std::complex) computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z)) + \fI(function template)\fP + atan + atanf computes arc tangent (\\({\\small\\arctan{x}}\\)arctan(x)) + atanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan(std::valarray) applies the function std::atan to each element of valarray + \fI(function template)\fP + C documentation for + catan diff --git a/man/std::atan(std::valarray).3 b/man/std::atan(std::valarray).3 index a115e9faa..9aeedc914 100644 --- a/man/std::atan(std::valarray).3 +++ b/man/std::atan(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::atan(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atan(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atan(std::valarray) \- std::atan(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (atan) is used to perform the computation. If such function is - not available, std::atan is used due to argument dependent lookup. + not available, std::atan is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,16 +43,65 @@ valarray atan(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = atan(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + #include + + auto show = [](char const* title, const std::valarray& va) + { + std::cout << title << " :"; + std::for_each(std::begin(va), std::end(va), + [](const float x) { std::cout << " " << std::fixed << x; }); + std::cout << '\\n'; + }; + + int main() + { + const std::valarray x = {.1f, .3f, .6f, .9f}; + const std::valarray f = std::atan(x); + const std::valarray g = std::tan(f); + + show("x ", x); + show("f = atan(x)", f); + show("g = tan(f) ", g); + } + +.SH Output: + + x : 0.100000 0.300000 0.600000 0.900000 + f = atan(x) : 0.099669 0.291457 0.540420 0.732815 + g = tan(f) : 0.100000 0.300000 0.600000 0.900000 + +.SH See also + + asin(std::valarray) applies the function std::asin to each element of valarray + \fI(function template)\fP + acos(std::valarray) applies the function std::acos to each element of valarray + \fI(function template)\fP + atan2(std::valarray) applies the function std::atan2 to a valarray and a value + \fI(function template)\fP + tan(std::valarray) applies the function std::tan to each element of valarray + \fI(function template)\fP + atan + atanf computes arc tangent (\\({\\small\\arctan{x}}\\)arctan(x)) + atanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan(std::complex) computes arc tangent of a complex number + \fI(C++11)\fP (\\({\\small\\arctan{z}}\\)arctan(z)) + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::atan,std::atanf,std::atanl.3 b/man/std::atan,std::atanf,std::atanl.3 new file mode 100644 index 000000000..53a389a08 --- /dev/null +++ b/man/std::atan,std::atanf,std::atanl.3 @@ -0,0 +1,130 @@ +.TH std::atan,std::atanf,std::atanl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atan,std::atanf,std::atanl \- std::atan,std::atanf,std::atanl + +.SH Synopsis + Defined in header + float atan ( float num ); + + double atan ( double num ); (until C++23) + + long double atan ( long double num ); + /* floating-point-type */ (since C++23) + atan ( /* floating-point-type */ num ); (constexpr since C++26) + float atanf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double atanl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double atan ( Integer num ); + + 1-3) Computes the principal value of the arc tangent of num. + The library provides overloads of std::atan for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the arc tangent of num (arctan(num)) in the range [- + + π + 2 + + , + + + π + 2 + + ] radians, is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, it is returned unmodified. + * If the argument is +∞, +π/2 is returned. + * If the argument is -∞, -π/2 is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + POSIX specifies that in case of underflow, num is returned unmodified, and if that + is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, + and LDBL_MIN is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::atan(num) has the same effect as std::atan(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "atan(1) = " << std::atan(1) << '\\n' + << "4*atan(1) = " << 4 * std::atan(1) << '\\n'; + + // special values + std::cout << "atan(Inf) = " << std::atan(INFINITY) << '\\n' + << "2*atan(Inf) = " << 2 * std::atan(INFINITY) << '\\n' + << "atan(-0.0) = " << std::atan(-0.0) << '\\n' + << "atan(+0.0) = " << std::atan(0) << '\\n'; + } + +.SH Output: + + atan\fB(1)\fP = 0.785398 + 4*atan\fB(1)\fP = 3.14159 + atan(Inf) = 1.5708 + 2*atan(Inf) = 3.14159 + atan(-0.0) = -0 + atan(+0.0) = 0 + +.SH See also + + asin + asinf computes arc sine (\\({\\small\\arcsin{x}}\\)arcsin(x)) + asinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acos + acosf computes arc cosine (\\({\\small\\arccos{x}}\\)arccos(x)) + acosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan2 + atan2f arc tangent, using signs to determine quadrants + atan2l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tan + tanf computes tangent (\\({\\small\\tan{x}}\\)tan(x)) + tanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan(std::complex) computes arc tangent of a complex number + \fI(C++11)\fP (\\({\\small\\arctan{z}}\\)arctan(z)) + \fI(function template)\fP + atan(std::valarray) applies the function std::atan to each element of valarray + \fI(function template)\fP + C documentation for + atan diff --git a/man/std::atan.3 b/man/std::atan.3 deleted file mode 100644 index 6745cd028..000000000 --- a/man/std::atan.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::atan 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float atan( float arg ); - double atan( double arg ); - long double atan( long double arg ); - double atan( Integral arg ); \fI(since C++11)\fP - - Computes arc tangent of arg - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Arc tangent of arg in radians in the range of [-π/2; π/2] radians. - - std::atan(+0) returns +0. std::atan(-0) returns -0 - - std::atan(+∞) returns +π/2. std::atan(-∞) returns -π/2 - -.SH See also - - atan2 arc tangent, using signs to determine quadrants - \fI(function)\fP - asin computes arc sine (arcsin(x)) - \fI(function)\fP - acos computes arc cosine (arccos(x)) - \fI(function)\fP - tan computes tangent (tan(x)) - \fI(function)\fP - atan(std::complex) computes arc tangent of a complex number (arctan(z)) - \fI(C++11)\fP \fI(function template)\fP - atan(std::valarray) applies the function std::atan to each element of valarray - \fI(function template)\fP - C documentation for - atan diff --git a/man/std::atan2(std::valarray).3 b/man/std::atan2(std::valarray).3 index 2b40cdbe8..47cdaff5e 100644 --- a/man/std::atan2(std::valarray).3 +++ b/man/std::atan2(std::valarray).3 @@ -1,14 +1,23 @@ -.TH std::atan2(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atan2(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atan2(std::valarray) \- std::atan2(std::valarray) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP - valarray atan2( const valarray& y, const valarray& x ); - template< class T > \fB(2)\fP - valarray atan2( const valarray& y, const T& vx ); - template< class T > \fB(3)\fP - valarray atan2( const T& vy, const valarray& x ); - - Computes the inverse tangent of y/x using the signs of arguments to correctly + template< class T > \fB(1)\fP + std::valarray atan2( const std::valarray& y, const std::valarray& x ); + template< class T > + + std::valarray atan2( const std::valarray& y, \fB(2)\fP + + const typename std::valarray::value_type& vx ); + template< class T > + + std::valarray atan2( const typename std::valarray::value_type& vy, \fB(3)\fP + + const std::valarray& x ); + + Computes the inverse tangent of y / x using the signs of arguments to correctly determine quadrant. 1) Computes the inverse tangent of each pair of corresponding values from y and x. @@ -30,7 +39,7 @@ .SH Notes Unqualified function (atan2) is used to perform the computation. If such function is - not available, std::atan2 is used due to argument dependent lookup. + not available, std::atan2 is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -38,23 +47,85 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include + #include + + void show(char const* title, const std::valarray& va) + { + std::cout << title << ' '; + std::for_each(std::begin(va), std::end(va), [](const double x) + { + std::cout << ' ' << std::right << std::setw(4) << x << "°"; + }); + std::cout << '\\n'; + } + + const double pi = std::acos(-1.0); // C++20: std::numbers::pi - atan2 arc tangent, using signs to determine quadrants - \fI(function)\fP + int main() + { + auto degrees_to_radians = [](double const& x) { return (pi * x / 180); }; + auto radians_to_degrees = [](double const& x) { return (180 * x / pi); }; -.SH Category: + const std::valarray degrees{-90, -60, -45, -30, 0, 30, 45, 60, 90}; + const std::valarray radians = degrees.apply(degrees_to_radians); + + const auto sin = std::sin(radians); + const auto cos = std::cos(radians); + + show("(1)", std::atan2(sin, cos).apply(radians_to_degrees)); + show("(2)", std::atan2(sin/cos, 1.0).apply(radians_to_degrees)); + show("(3)", std::atan2(1.0, cos/sin).apply(radians_to_degrees)); + } + +.SH Output: + + \fB(1)\fP -90° -60° -45° -30° 0° 30° 45° 60° 90° + \fB(2)\fP -90° -60° -45° -30° 0° 30° 45° 60° 90° + \fB(3)\fP 90° 120° 135° 150° 0° 30° 45° 60° 90° + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T is deduced from both the scalar and the only deduce T from the + LWG 3074 C++98 valarray for (2,3), disallowing valarray + mixed-type calls + +.SH See also - * Todo no example + asin(std::valarray) applies the function std::asin to each element of valarray + \fI(function template)\fP + acos(std::valarray) applies the function std::acos to each element of valarray + \fI(function template)\fP + atan(std::valarray) applies the function std::atan to each element of valarray + \fI(function template)\fP + atan2 + atan2f arc tangent, using signs to determine quadrants + atan2l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + arg returns the phase angle + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::atan2,std::atan2f,std::atan2l.3 b/man/std::atan2,std::atan2f,std::atan2l.3 new file mode 100644 index 000000000..b662409f6 --- /dev/null +++ b/man/std::atan2,std::atan2f,std::atan2l.3 @@ -0,0 +1,184 @@ +.TH std::atan2,std::atan2f,std::atan2l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atan2,std::atan2f,std::atan2l \- std::atan2,std::atan2f,std::atan2l + +.SH Synopsis + Defined in header + float atan2 ( float y, float x ); + + double atan2 ( double y, double x ); (until C++23) + + long double atan2 ( long double y, long double x ); + /* floating-point-type */ + (since C++23) + atan2 ( /* floating-point-type */ y, (constexpr since C++26) + \fB(1)\fP + /* floating-point-type */ x ); + float atan2f( float y, float x ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double atan2l( long double y, long double x ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double atan2 ( Integer y, Integer x ); + + 1-3) Computes the arc tangent of y / x using the signs of arguments to determine the + correct quadrant. + The library provides overloads of std::atan2 for all cv-unqualified floating-point + types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + y, x - floating-point or integer values + +.SH Return value + + If no errors occur, the arc tangent of y / x (arctan( + + y + x + + )) in the range [-π, +π] radians, is returned. + y argument +.SH Return value + math-atan2.png + x argument + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error may occur if x and y are both zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If x and y are both zero, domain error does not occur. + * If x and y are both zero, range error does not occur either. + * If y is zero, pole error does not occur. + * If y is ±0 and x is negative or -0, ±π is returned. + * If y is ±0 and x is positive or +0, ±0 is returned. + * If y is ±∞ and x is finite, ±π/2 is returned. + * If y is ±∞ and x is -∞, ±3π/4 is returned. + * If y is ±∞ and x is +∞, ±π/4 is returned. + * If x is ±0 and y is negative, -π/2 is returned. + * If x is ±0 and y is positive, +π/2 is returned. + * If x is -∞ and y is finite and positive, +π is returned. + * If x is -∞ and y is finite and negative, -π is returned. + * If x is +∞ and y is finite and positive, +0 is returned. + * If x is +∞ and y is finite and negative, -0 is returned. + * If either x is NaN or y is NaN, NaN is returned. + +.SH Notes + + std::atan2(y, x) is equivalent to + std::arg(std::complex>(x, y)). + + POSIX specifies that in case of underflow, the value y / x is returned, and if that + is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, + and LDBL_MIN is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::atan2(num1, num2) + has the same effect as std::atan2(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::atan2(num1, num2) has the same effect as (until C++23) + std::atan2(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::atan2(num1, + num2) has the same effect as std::atan2(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::atan2(num1, num2) + has the same effect as std::atan2(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + void print_coordinates(int x, int y) + { + std::cout << std::showpos + << "(x:" << x << ", y:" << y << ") cartesian is " + << "(r:" << std::hypot(x, y) + << ", phi:" << std::atan2(y, x) << ") polar\\n"; + } + + int main() + { + // normal usage: the signs of the two arguments determine the quadrant + print_coordinates(+1, +1); // atan2( 1, 1) = +pi/4, Quad I + print_coordinates(-1, +1); // atan2( 1, -1) = +3pi/4, Quad II + print_coordinates(-1, -1); // atan2(-1, -1) = -3pi/4, Quad III + print_coordinates(+1, -1); // atan2(-1, 1) = -pi/4, Quad IV + + // special values + std::cout << std::noshowpos + << "atan2(0, 0) = " << atan2(0, 0) << '\\n' + << "atan2(0,-0) = " << atan2(0, -0.0) << '\\n' + << "atan2(7, 0) = " << atan2(7, 0) << '\\n' + << "atan2(7,-0) = " << atan2(7, -0.0) << '\\n'; + } + +.SH Output: + + (x:+1, y:+1) cartesian is (r:1.41421, phi:0.785398) polar + (x:-1, y:+1) cartesian is (r:1.41421, phi:2.35619) polar + (x:-1, y:-1) cartesian is (r:1.41421, phi:-2.35619) polar + (x:+1, y:-1) cartesian is (r:1.41421, phi:-0.785398) polar + atan2(0, 0) = 0 + atan2(0,-0) = 3.14159 + atan2(7, 0) = 1.5708 + atan2(7,-0) = 1.5708 + +.SH See also + + asin + asinf computes arc sine (\\({\\small\\arcsin{x}}\\)arcsin(x)) + asinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acos + acosf computes arc cosine (\\({\\small\\arccos{x}}\\)arccos(x)) + acosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan + atanf computes arc tangent (\\({\\small\\arctan{x}}\\)arctan(x)) + atanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + arg returns the phase angle + \fI(function template)\fP + atan2(std::valarray) applies the function std::atan2 to a valarray and a value + \fI(function template)\fP + C documentation for + atan2 diff --git a/man/std::atan2.3 b/man/std::atan2.3 deleted file mode 100644 index 8ff618a49..000000000 --- a/man/std::atan2.3 +++ /dev/null @@ -1,84 +0,0 @@ -.TH std::atan2 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float atan2( float y, float x ); \fB(1)\fP - double atan2( double y, double x ); \fB(2)\fP - long double atan2( long double y, long double x ); \fB(3)\fP - Promoted atan2( Arithmetic1 y, Arithmetic2 x ); \fB(4)\fP \fI(since C++11)\fP - - Computes the inverse tangent of y/x using the signs of arguments to correctly - determine quadrant. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - -.SH Parameters - - x, y - values of floating-point or integral types - -.SH Return value - - Arc tangent of y/x in radians in the range of [-π; π] radians. - - Y argument -.SH Return value - math-atan2.png - X argument - - std::atan2(+0, -0) return +π. std::atan2(-0, -0) return -π - - std::atan2(+0, +0) return +0. std::atan2(-0, +0) return -0 - - std::atan2(+0, x) return +π if x<0 and +0 if x>0. - - std::atan2(-0, x) return -π if x<0 and -0 if x>0. - - std::atan2(y, 0) return -π/2 if y<0 and +π/2 if y>0. - - std::atan2(y, -∞) returns +π if y>0 and -π if y<0 - - std::atan2(y, +∞) returns +0 if y>0 and -0 if y<0 - - std::atan2(+∞, x) returns +π/2. std::atan2(-∞, x) returns -π/2. - - std::atan2(+∞, -∞) returns +3π/4. std::atan2(-∞, -∞) returns -3π/4. - - std::atan2(+∞, +∞) returns +π/4. std::atan2(-∞, +∞) returns -π/4. - -.SH Example - - -// Run this code - - #include - #include - #include - - std::pair cartesian_to_polar(double x, double y) - { - return {std::hypot(x, y), std::atan2(y,x)}; - } - - int main() - { - std::pair polar = cartesian_to_polar(1, 1); - std::cout << "(1,1) cartesian is (" << polar.first - << "," << polar.second<< ") polar\\n"; - } - -.SH Output: - - (1,1) cartesian is (1.41421,0.785398) polar - -.SH See also - - atan computes arc tangent (arctan(x)) - \fI(function)\fP - asin computes arc sine (arcsin(x)) - \fI(function)\fP - acos computes arc cosine (arccos(x)) - \fI(function)\fP - tan computes tangent (tan(x)) - \fI(function)\fP - C documentation for - atan2 diff --git a/man/std::atanh(std::complex).3 b/man/std::atanh(std::complex).3 index e4ccf450b..b9bed2ef9 100644 --- a/man/std::atanh(std::complex).3 +++ b/man/std::atanh(std::complex).3 @@ -1,10 +1,14 @@ -.TH std::atanh(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atanh(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atanh(std::complex) \- std::atanh(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP complex atanh( const complex& z ); - Computes complex area hyperbolic tangent of a complex value z. + Computes the complex arc hyperbolic tangent of z with branch cuts outside the + interval [−1; +1] along the real axis. .SH Parameters @@ -12,13 +16,106 @@ .SH Return value - Complex area hyperbolic tangent of z + If no errors occur, the complex arc hyperbolic tangent of z is returned, in the + range of a half-strip mathematically unbounded along the real axis and in the + interval [−iπ/2; +iπ/2] along the imaginary axis. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::atanh(std::conj(z)) == std::conj(std::atanh(z)) + * std::atanh(-z) == -std::atanh(z) + * If z is (+0,+0), the result is (+0,+0) + * If z is (+0,NaN), the result is (+0,NaN) + * If z is (+1,+0), the result is (+∞,+0) and FE_DIVBYZERO is raised + * If z is (x,+∞) (for any finite positive x), the result is (+0,π/2) + * If z is (x,NaN) (for any finite nonzero x), the result is (NaN,NaN) and + FE_INVALID may be raised + * If z is (+∞,y) (for any finite positive y), the result is (+0,π/2) + * If z is (+∞,+∞), the result is (+0,π/2) + * If z is (+∞,NaN), the result is (+0,NaN) + * If z is (NaN,y) (for any finite y), the result is (NaN,NaN) and FE_INVALID may + be raised + * If z is (NaN,+∞), the result is (±0,π/2) (the sign of the real part is + unspecified) + * If z is (NaN,NaN), the result is (NaN,NaN) + +.SH Notes + + Although the C++ standard names this function "complex arc hyperbolic tangent", the + inverse functions of the hyperbolic functions are the area functions. Their argument + is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse + hyperbolic tangent", and, less common, "complex area hyperbolic tangent". + + Inverse hyperbolic tangent is a multivalued function and requires a branch cut on + the complex plane. The branch cut is conventionally placed at the line segments + (-∞,-1] and [+1,+∞) of the real axis. + + The mathematical definition of the principal value of the inverse hyperbolic tangent + is atanh z = + + ln(1+z) - ln(1-z) + 2 + + . + For any z, atanh(z) = + + atan(iz) + i + + . + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z1(2.0, 0.0); + std::cout << "atanh" << z1 << " = " << std::atanh(z1) << '\\n'; + + std::complex z2(2.0, -0.0); + std::cout << "atanh" << z2 << " (the other side of the cut) = " + << std::atanh(z2) << '\\n'; + + // for any z, atanh(z) = atanh(iz) / i + std::complex z3(1.0, 2.0); + std::complex i(0.0, 1.0); + std::cout << "atanh" << z3 << " = " << std::atanh(z3) << '\\n' + << "atan" << z3 * i << " / i = " << std::atan(z3 * i) / i << '\\n'; + } + +.SH Output: + + atanh(2.000000,0.000000) = (0.549306,1.570796) + atanh(2.000000,-0.000000) (the other side of the cut) = (0.549306,-1.570796) + atanh(1.000000,2.000000) = (0.173287,1.178097) + atan(-2.000000,1.000000) / i = (0.173287,1.178097) .SH See also - tan(std::complex) computes tangent of a complex number (tan(z)) - \fI(function template)\fP - tanh(std::complex) computes hyperbolic tangent of a complex number - \fI(function template)\fP - atan(std::complex) computes arc tangent of a complex number (arctan(z)) - \fI(C++11)\fP \fI(function template)\fP + asinh(std::complex) computes area hyperbolic sine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arsinh}{z}}\\)arsinh(z)) + \fI(function template)\fP + acosh(std::complex) computes area hyperbolic cosine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arcosh}{z}}\\)arcosh(z)) + \fI(function template)\fP + computes hyperbolic tangent of a complex number + tanh(std::complex) (\\({\\small\\tanh{z}}\\)tanh(z)) + \fI(function template)\fP + atanh + atanhf computes the inverse hyperbolic tangent + atanhl (\\({\\small\\operatorname{artanh}{x}}\\)artanh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + catanh diff --git a/man/std::atanh,std::atanhf,std::atanhl.3 b/man/std::atanh,std::atanhf,std::atanhl.3 new file mode 100644 index 000000000..2eb5c512b --- /dev/null +++ b/man/std::atanh,std::atanhf,std::atanhl.3 @@ -0,0 +1,148 @@ +.TH std::atanh,std::atanhf,std::atanhl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atanh,std::atanhf,std::atanhl \- std::atanh,std::atanhf,std::atanhl + +.SH Synopsis + Defined in header + float atanh ( float num ); + + double atanh ( double num ); (until C++23) + + long double atanh ( long double num ); + /* floating-point-type */ (since C++23) + atanh ( /* floating-point-type */ num ); (constexpr since C++26) + float atanhf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double atanhl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double atanh ( Integer num ); + + 1-3) Computes the inverse hyperbolic tangent of num. + The library provides overloads of std::atanh for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the inverse hyperbolic tangent of num (tanh-1 + (num), or artanh(num)), is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a pole error occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned (with the + correct sign). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the argument is not on the interval [-1, +1], a range error occurs. + + If the argument is ±1, a pole error occurs. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0, it is returned unmodified. + * if the argument is ±1, ±∞ is returned and FE_DIVBYZERO is raised. + * if |num|>1, NaN is returned and FE_INVALID is raised. + * if the argument is NaN, NaN is returned. + +.SH Notes + + Although the C standard (to which C++ refers for this function) names this function + "arc hyperbolic tangent", the inverse functions of the hyperbolic functions are the + area functions. Their argument is the area of a hyperbolic sector, not an arc. The + correct name is "inverse hyperbolic tangent" (used by POSIX) or "area hyperbolic + tangent". + + POSIX specifies that in case of underflow, num is returned unmodified, and if that + is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, + and LDBL_MIN is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::atanh(num) has the same effect as std::atanh(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "atanh(0) = " << std::atanh(0) << '\\n' + << "atanh(-0) = " << std::atanh(-0.0) << '\\n' + << "atanh(0.9) = " << std::atanh(0.9) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "atanh(-1) = " << std::atanh(-1) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + atanh\fB(0)\fP = 0 + atanh(-0) = -0 + atanh(0.9) = 1.47222 + atanh(-1) = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised + +.SH See also + + asinh + asinhf computes the inverse hyperbolic sine + asinhl (\\({\\small\\operatorname{arsinh}{x}}\\)arsinh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acosh + acoshf computes the inverse hyperbolic cosine + acoshl (\\({\\small\\operatorname{arcosh}{x}}\\)arcosh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tanh + tanhf computes hyperbolic tangent (\\({\\small\\tanh{x}}\\)tanh(x)) + tanhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atanh(std::complex) computes area hyperbolic tangent of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{artanh}{z}}\\)artanh(z)) + \fI(function template)\fP + C documentation for + atanh + +.SH External links + + Weisstein, Eric W. "Inverse Hyperbolic Tangent." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::atanh.3 b/man/std::atanh.3 deleted file mode 100644 index 51af5befa..000000000 --- a/man/std::atanh.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::atanh 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float atanh( float arg ); \fI(since C++11)\fP - double atanh( double arg ); \fI(since C++11)\fP - long double atanh( long double arg ); \fI(since C++11)\fP - double atanh( Integral arg ); \fI(since C++11)\fP - - Computes hyperbolic area tangent of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Inverse hyperbolic tangent of arg. - -.SH See also - - asinh area hyperbolic sine - \fI(C++11)\fP \fI(function)\fP - acosh area hyperbolic cosine - \fI(C++11)\fP \fI(function)\fP - tanh hyperbolic tangent - \fI(function)\fP - atanh(std::complex) computes area hyperbolic tangent of a complex number - \fI(C++11)\fP \fI(function template)\fP - C documentation for - atanh - -.SH External links - - Weisstein, Eric W. "Inverse Hyperbolic Tangent." From MathWorld--A Wolfram Web - Resource. diff --git a/man/std::atexit.3 b/man/std::atexit.3 index 0f42d9f37..e35ffa42f 100644 --- a/man/std::atexit.3 +++ b/man/std::atexit.3 @@ -1,23 +1,30 @@ -.TH std::atexit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atexit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atexit \- std::atexit + .SH Synopsis Defined in header - extern "C" int atexit( void (*func)() ); - extern "C++" int atexit( void (*func)() ); + int atexit( /* c-atexit-handler */* func ); \fI(until C++11)\fP + int atexit( /* atexit-handler */* func ); + int atexit( /* c-atexit-handler */* func ) noexcept; \fB(1)\fP \fI(since C++11)\fP + int atexit( /* atexit-handler */* func ) noexcept; + extern "C" using /* c-atexit-handler */ = void(); \fB(2)\fP (exposition only*) + extern "C++" using /* atexit-handler */ = void(); Registers the function pointed to by func to be called on normal program termination - (via std::exit() or returning from the cpp/language/main function) + (via std::exit() or returning from the main function) The functions will be called during the destruction of the static objects, in reverse order: if A was registered before B, then the call to B is made before the call to A. Same applies to the ordering \fI(until C++11)\fP between static object constructors and the calls to atexit: see - std::exit + std::exit. The functions may be called concurrently with the destruction of the objects with static storage duration and with each other, maintaining the guarantee that if registration of A was sequenced-before the \fI(since C++11)\fP registration of B, then the call to B is sequenced-before the call to A, same applies to the sequencing between static object constructors - and calls to atexit: see std::exit + and calls to atexit: see std::exit. The same function may be registered more than once. @@ -37,54 +44,59 @@ 0 if the registration succeeds, nonzero value otherwise. -.SH Exceptions +.SH Notes - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + The two overloads are distinct because the types of the parameter func are distinct + (language linkage is part of its type). .SH Example - + // Run this code - #include #include - + #include + void atexit_handler_1() { - std::cout << "at exit #1\\n"; + std::cout << "At exit #1\\n"; } - + void atexit_handler_2() { - std::cout << "at exit #2\\n"; + std::cout << "At exit #2\\n"; } - + int main() { const int result_1 = std::atexit(atexit_handler_1); const int result_2 = std::atexit(atexit_handler_2); - - if ((result_1 != 0) or (result_2 != 0)) { - std::cerr << "Registration failed\\n"; + + if (result_1 || result_2) + { + std::cerr << "Registration failed!\\n"; return EXIT_FAILURE; } - - std::cout << "returning from main\\n"; + + std::cout << "Returning from main...\\n"; return EXIT_SUCCESS; } .SH Output: - returning from main - at exit #2 - at exit #1 + Returning from main... + At exit #2 + At exit #1 .SH See also - at_quick_exit registers a function to be called on quick_exit invocation - \fI(C++11)\fP \fI(function)\fP + abort causes abnormal program termination (without cleaning up) + \fI(function)\fP + exit causes normal program termination with cleaning up + \fI(function)\fP + quick_exit causes quick program termination without completely cleaning up + \fI(C++11)\fP \fI(function)\fP + at_quick_exit registers a function to be called on std::quick_exit invocation + \fI(C++11)\fP \fI(function)\fP C documentation for atexit diff --git a/man/std::atof.3 b/man/std::atof.3 index 0bce1bc27..4abb40743 100644 --- a/man/std::atof.3 +++ b/man/std::atof.3 @@ -1,42 +1,48 @@ -.TH std::atof 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atof 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atof \- std::atof + .SH Synopsis Defined in header - double atof( const char *str ); + double atof( const char* str ); - Interprets an floating point value in a byte string pointed to by str. + Interprets a floating point value in a byte string pointed to by str. - Function discards any whitespace characters (as determined by std::isspace()) until + Function discards any whitespace characters (as determined by std::isspace) until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid floating point representation and converts them to floating - point value. The valid floating point value can be one of the following: + possible to form a valid floating-point representation and converts them to a + floating-point value. The valid floating-point value can be one of the following: - * decimal floating point expression. It consists of the following parts: + * decimal floating-point expression. It consists of the following parts: * (optional) plus or minus sign - * nonempty sequence of decimal digits optionally containing a decimal point - character (defines significand) + * nonempty sequence of decimal digits optionally containing decimal-point + character (as determined by the current C locale) (defines significand) * (optional) e or E followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) + sequence of decimal digits (defines exponent to base 10) - * binary floating point expression. It consists of the following parts: + * hexadecimal floating-point expression. It consists of the + following parts: * (optional) plus or minus sign * 0x or 0X - * nonempty sequence of hexadecimal digits optionally containing a decimal point - character (defines significand) - * (optional) p or P followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) - + * nonempty sequence of hexadecimal digits optionally containing a + decimal-point character (as determined by the current C locale) + (defines significand) + * (optional) p or P followed with optional minus or plus sign and + nonempty sequence of decimal digits (defines exponent to base 2) \fI(since C++11)\fP * infinity expression. It consists of the following parts: * (optional) plus or minus sign * INF or INFINITY ignoring case - * not-a-number expression. It consists of the following parts: * (optional) plus or minus sign - * NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only - contain alphanumeric characters. The result is a quiet NaN floating point value. + * NAN or NAN(char_sequence) ignoring case of the NAN part. + char_sequence can only contain digits, Latin letters, and + underscores. The result is a quiet NaN floating-point value. + + * any other expression that may be accepted by the currently installed C locale .SH Parameters @@ -50,20 +56,21 @@ .SH Example - + // Run this code #include #include - + int main() { - std::cout << std::atof("0.0000000123") << "\\n" - << std::atof("0.012") << "\\n" - << std::atof("15e16") << "\\n" - << std::atof("-0x1afp-2") << "\\n" - << std::atof("inF") << "\\n" - << std::atof("Nan") << "\\n"; + std::cout << std::atof("0.0000000123") << '\\n' + << std::atof("0.012") << '\\n' + << std::atof("15e16") << '\\n' + << std::atof("-0x1afp-2") << '\\n' + << std::atof("inF") << '\\n' + << std::atof("Nan") << '\\n' + << std::atof("invalid") << '\\n'; } .SH Output: @@ -74,11 +81,24 @@ -107.75 inf nan + 0 .SH See also - strtof converts a byte string to a floating point value - strtod \fI(function)\fP + stof + stod + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + strtof converts a byte string to a floating-point value + strtod \fI(function)\fP strtold + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + atoi + atol converts a byte string to an integer value + atoll \fI(function)\fP + \fI(C++11)\fP C documentation for atof diff --git a/man/std::atoi,std::atol,std::atoll.3 b/man/std::atoi,std::atol,std::atoll.3 index 1e1e0e950..89d537190 100644 --- a/man/std::atoi,std::atol,std::atoll.3 +++ b/man/std::atoi,std::atol,std::atoll.3 @@ -1,75 +1,150 @@ -.TH std::atoi,std::atol,std::atoll 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atoi,std::atol,std::atoll 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atoi,std::atol,std::atoll \- std::atoi,std::atol,std::atoll + .SH Synopsis Defined in header - int atoi( const char *str ); - long atol( const char *str ); - long long atoll( const char *str ); \fI(since C++11)\fP + int atoi( const char* str ); \fB(1)\fP + long atol( const char* str ); \fB(2)\fP + long long atoll( const char* str ); \fB(3)\fP \fI(since C++11)\fP - Interprets an integer value in a byte string pointed to by str. + Interprets an integer value in a byte string pointed to by str. The implied radix is + always 10. - Function discards any whitespace characters until first non-whitespace character is - found. Then it takes as many characters as possible to form a valid integer number - representation and converts them to integer value. The valid integer value consists - of the following parts: + Discards any whitespace characters until the first non-whitespace character is + found, then takes as many characters as possible to form a valid integer number + representation and converts them to an integer value. The valid integer value + consists of the following parts: * (optional) plus or minus sign * numeric digits + If the value of the result cannot be represented, i.e. the converted value falls out + of range of the corresponding return type, the behavior is undefined. + .SH Parameters str - pointer to the null-terminated byte string to be interpreted .SH Return value - Integer value corresponding to the contents of str on success. If the converted - value falls out of range of corresponding return type, the return value is - undefined. If no conversion can be performed, 0 is returned. + Integer value corresponding to the contents of str on success. + + If no conversion can be performed, 0 is returned. + +.SH Possible implementation + + template + T atoi_impl(const char* str) + { + while (std::isspace(static_cast(*str))) + ++str; + + bool negative = false; + + if (*str == '+') + ++str; + else if (*str == '-') + { + ++str; + negative = true; + } + + T result = 0; + for (; std::isdigit(static_cast(*str)); ++str) + { + int digit = *str - '0'; + result *= 10; + result -= digit; // calculate in negatives to support INT_MIN, LONG_MIN,.. + } + + return negative ? result : -result; + } + + int atoi(const char* str) + { + return atoi_impl(str); + } + + long atol(const char* str) + { + return atoi_impl(str); + } + + long long atoll(const char* str) + { + return atoi_impl(str); + } + + Actual C++ library implementations fall back to C library implementations of atoi, + atoil, and atoll, which either implement it directly (as in MUSL libc) or delegate + to strtol/strtoll (as in GNU libc). .SH Example - + // Run this code - #include #include - + #include + int main() { - const char *str1 = "42"; - const char *str2 = "3.14159"; - const char *str3 = "31337 with words"; - const char *str4 = "words and 2"; - - int num1 = std::atoi(str1); - int num2 = std::atoi(str2); - int num3 = std::atoi(str3); - int num4 = std::atoi(str4); - - std::cout << "std::atoi(\\"" << str1 << "\\") is " << num1 << '\\n'; - std::cout << "std::atoi(\\"" << str2 << "\\") is " << num2 << '\\n'; - std::cout << "std::atoi(\\"" << str3 << "\\") is " << num3 << '\\n'; - std::cout << "std::atoi(\\"" << str4 << "\\") is " << num4 << '\\n'; + const auto data = + { + "42", + "0x2A", // treated as "0" and junk "x2A", not as hexadecimal + "3.14159", + "31337 with words", + "words and 2", + "-012345", + "10000000000" // note: out of int32_t range + }; + + for (const char* s : data) + { + const int i{std::atoi(s)}; + std::cout << "std::atoi('" << s << "') is " << i << '\\n'; + if (const long long ll{std::atoll(s)}; i != ll) + std::cout << "std::atoll('" << s << "') is " << ll << '\\n'; + } } -.SH Output: +.SH Possible output: - std::atoi("42") is 42 - std::atoi("3.14159") is 3 - std::atoi("31337 with words") is 31337 - std::atoi("words and 2") is 0 + std::atoi('42') is 42 + std::atoi('0x2A') is 0 + std::atoi('3.14159') is 3 + std::atoi('31337 with words') is 31337 + std::atoi('words and 2') is 0 + std::atoi('-012345') is -12345 + std::atoi('10000000000') is 1410065408 + std::atoll('10000000000') is 10000000000 .SH See also stoi stol - stoll converts a string to a signed integer - \fI(C++11)\fP \fI(function)\fP + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + strtol converts a byte string to an integer value + strtoll \fI(function)\fP + \fI(C++11)\fP + strtoul converts a byte string to an unsigned integer value + strtoull \fI(function)\fP \fI(C++11)\fP + strtoimax + strtoumax converts a byte string to std::intmax_t or std::uintmax_t + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP - strtol converts a byte string to an integer value - strtoll \fI(function)\fP - strtoul converts a byte string to an unsigned integer value - strtoull \fI(function)\fP + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP C documentation for atoi, atol, diff --git a/man/std::atomic.3 b/man/std::atomic.3 index 8830b4538..09cd10244 100644 --- a/man/std::atomic.3 +++ b/man/std::atomic.3 @@ -1,139 +1,223 @@ -.TH std::atomic 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic \- std::atomic + .SH Synopsis - Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - struct atomic; - template<> \fB(2)\fP \fI(since C++11)\fP - struct atomic; - template< class T > \fB(3)\fP \fI(since C++11)\fP - struct atomic; - - Each instantiation and full specialization of the std::atomic template defines an - atomic type. Objects of atomic types are the only C++ objects that are free from - data races; that is, if one thread writes to an atomic object while another thread - reads from it, the behavior is well-defined. - - In addition, accesses to atomic objects may establish inter-thread synchronization - and order non-atomic memory accesses as specified by std::memory_order. - - The standard library provides specializations of the std::atomic template for the - following types: - - 1) One full specialization for the type bool and its typedef name is defined that is - treated as a non-specialized std::atomic except that it has standard layout, - trivial default constructor, trivial destructors, and supports aggregate - initialization syntax: - - Typedef name Full specialization - std::atomic_bool std::atomic - - 2) Full specializations and typedefs for integral types, as follows: - - Typedef name Full specialization - std::atomic_char std::atomic - std::atomic_schar std::atomic - std::atomic_uchar std::atomic - std::atomic_short std::atomic - std::atomic_ushort std::atomic - std::atomic_int std::atomic - std::atomic_uint std::atomic - std::atomic_long std::atomic - std::atomic_ulong std::atomic - std::atomic_llong std::atomic - std::atomic_ullong std::atomic - std::atomic_char16_t std::atomic - std::atomic_char32_t std::atomic - std::atomic_wchar_t std::atomic - std::atomic_int_least8_t std::atomic - std::atomic_uint_least8_t std::atomic - std::atomic_int_least16_t std::atomic - std::atomic_uint_least16_t std::atomic - std::atomic_int_least32_t std::atomic - std::atomic_uint_least32_t std::atomic - std::atomic_int_least64_t std::atomic - std::atomic_uint_least64_t std::atomic - std::atomic_int_fast8_t std::atomic - std::atomic_uint_fast8_t std::atomic - std::atomic_int_fast16_t std::atomic - std::atomic_uint_fast16_t std::atomic - std::atomic_int_fast32_t std::atomic - std::atomic_uint_fast32_t std::atomic - std::atomic_int_fast64_t std::atomic - std::atomic_uint_fast64_t std::atomic - std::atomic_intptr_t std::atomic - std::atomic_uintptr_t std::atomic - std::atomic_size_t std::atomic - std::atomic_ptrdiff_t std::atomic - std::atomic_intmax_t std::atomic - std::atomic_uintmax_t std::atomic - - These specializations have standard layout, trivial default constructors, and - trivial destructors. They support aggregate initialization syntax. - - 3) Partial specializations std::atomic for all pointer types. These - specializations have standard layout, trivial default constructors, and trivial - destructors. They support aggregate initialization syntax. - - In addition, std::atomic may be instantiated with any TriviallyCopyable type T. + Defined in header + template< class T > \fI(since C++20)\fP + struct std::atomic>; + + The partial template specialization of std::atomic for std::shared_ptr allows + users to manipulate shared_ptr objects atomically. + + If multiple threads of execution access the same std::shared_ptr object without + synchronization and any of those accesses uses a non-const member function of + shared_ptr then a data race will occur unless all such access is performed through + an instance of std::atomic (or, deprecated as of C++20, through the + standalone functions for atomic access to std::shared_ptr). + + Associated use_count increments are guaranteed to be part of the atomic operation. + Associated use_count decrements are sequenced after the atomic operation, but are + not required to be part of it, except for the use_count change when overriding + expected in a failed CAS. Any associated deletion and deallocation are sequenced + after the atomic update step and are not part of the atomic operation. + + Note that the control block of a shared_ptr is thread-safe: different non-atomic + std::shared_ptr objects can be accessed using mutable operations, such as operator= + or reset, simultaneously by multiple threads, even when these instances are copies, + and share the same control block internally. + + The type T may be an incomplete type. + +.SH Member types + + Member type Definition + value_type std::shared_ptr .SH Member functions - constructor constructs an atomic object - \fI(public member function)\fP - operator= stores a value into an atomic object - \fI(public member function)\fP - is_lock_free checks if the atomic object is lock-free - \fI(public member function)\fP - store atomically replaces the value of the atomic object with a - \fI(C++11)\fP non-atomic argument - \fI(public member function)\fP - load atomically obtains the value of the atomic object - \fI(C++11)\fP \fI(public member function)\fP - operator T loads a value from an atomic object - \fI(public member function)\fP - exchange atomically replaces the value of the atomic object and - \fI(C++11)\fP obtains the value held previously - \fI(public member function)\fP - atomically compares the value of the atomic object with - compare_exchange_weak non-atomic argument and performs atomic exchange if equal or - compare_exchange_strong atomic load if not - \fI(public member function)\fP - -.SH Specialized member functions - - fetch_add atomically adds the argument to the value stored in the atomic - \fI(C++11)\fP object and obtains the value held previously - \fI(public member function)\fP - fetch_sub atomically subtracts the argument from the value stored in the - \fI(C++11)\fP atomic object and obtains the value held previously - \fI(public member function)\fP - fetch_and atomically performs bitwise AND between the argument and the value - \fI(C++11)\fP of the atomic object and obtains the value held previously - \fI(public member function)\fP - fetch_or atomically performs bitwise OR between the argument and the value of - \fI(C++11)\fP the atomic object and obtains the value held previously - \fI(public member function)\fP - fetch_xor atomically performs bitwise XOR between the argument and the value - \fI(C++11)\fP of the atomic object and obtains the value held previously - \fI(public member function)\fP - operator++ - operator++(int) increments or decrements the atomic value by one - operator-- \fI(public member function)\fP - operator--(int) - operator+= - operator-= adds, subtracts, or performs bitwise AND, OR, XOR with the atomic - operator&= value - operator|= \fI(public member function)\fP - operator^= + All non-specialized std::atomic functions are also provided by this specialization, + and no additional member functions. + +atomic>::atomic + + constexpr atomic() noexcept = default; \fB(1)\fP + constexpr atomic( std::nullptr_t ) noexcept : atomic() {} \fB(2)\fP + atomic( std::shared_ptr desired ) noexcept; \fB(3)\fP + atomic( const atomic& ) = delete; \fB(4)\fP + + 1,2) Initializes the underlying shared_ptr to the null value. + 3) Initializes the underlying shared_ptr to a copy of desired. As with any + std::atomic type, initialization is not an atomic operation. + 4) Atomic types are not copy/move constructible. + +atomic>::operator= + + void operator=( const atomic& ) = delete; \fB(1)\fP + void operator=( std::shared_ptr desired ) noexcept; \fB(2)\fP + void operator=( std::nullptr_t ) noexcept; \fB(3)\fP + + 1) Atomic types are not copy/move assignable. + 2) Value assignment, equivalent to store(desired). + 3) Resets the atomic shared pointer to null pointer value. Equivalent to + store(nullptr);. + +atomic>::is_lock_free + + bool is_lock_free() const noexcept; + + Returns true if the atomic operations on all objects of this type are lock-free, + false otherwise. + +atomic>::store + + void store( std::shared_ptr desired, + std::memory_order order = std::memory_order_seq_cst ) noexcept; + + Atomically replaces the value of *this with the value of desired as if by + p.swap(desired) where p is the underlying std::shared_ptr. Memory is ordered + according to order. The behavior is undefined if order is std::memory_order_consume, + std::memory_order_acquire, or std::memory_order_acq_rel. + +atomic>::load + + std::shared_ptr load( std::memory_order order = std::memory_order_seq_cst ) + const noexcept; + + Atomically returns a copy of the underlying shared pointer. Memory is ordered + according to order. The behavior is undefined if order is std::memory_order_release + or std::memory_order_acq_rel. + +atomic>::operator std::shared_ptr + + operator std::shared_ptr() const noexcept; + + Equivalent to return load();. + +atomic>::exchange + + std::shared_ptr exchange( std::shared_ptr desired, + std::memory_order order = std::memory_order_seq_cst ) + noexcept; + + Atomically replaces the underlying std::shared_ptr with desired as if by + p.swap(desired) where p is the underlying std::shared_ptr and returns a copy of + the value that p had immediately before the swap. Memory is ordered according to + order. This is an atomic read-modify-write operation. + +atomic>::compare_exchange_weak, compare_exchange_strong + + bool compare_exchange_strong( std::shared_ptr& expected, std::shared_ptr + desired, \fB(1)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_weak( std::shared_ptr& expected, std::shared_ptr + desired, \fB(2)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_strong( std::shared_ptr& expected, std::shared_ptr + desired, \fB(3)\fP + std::memory_order order = + std::memory_order_seq_cst ) noexcept; + bool compare_exchange_weak( std::shared_ptr& expected, std::shared_ptr + desired, \fB(4)\fP + std::memory_order order = std::memory_order_seq_cst + ) noexcept; + + 1) If the underlying std::shared_ptr stores the same T* as expected and shares + ownership with it, or if both underlying and expected are empty, assigns from + desired to the underlying std::shared_ptr, returns true, and orders memory + according to success, otherwise assigns from the underlying std::shared_ptr to + expected, returns false, and orders memory according to failure. The behavior is + undefined if failure is std::memory_order_release or std::memory_order_acq_rel. On + success, the operation is an atomic read-modify-write operation on *this and + expected is not accessed after the atomic update. On failure, the operation is an + atomic load operation on *this and expected is updated with the existing value read + from the atomic object. This update to expected's use_count is part of this atomic + operation, although the write itself (and any subsequent deallocation/destruction) + is not required to be. + 2) Same as \fB(1)\fP, but may also fail spuriously. + 3) Equivalent to: return compare_exchange_strong(expected, desired, order, + fail_order);, where fail_order is the same as order except that + std::memory_order_acq_rel is replaced by std::memory_order_acquire and + std::memory_order_release is replaced by std::memory_order_relaxed. + 4) Equivalent to: return compare_exchange_weak(expected, desired, order, + fail_order);, where fail_order is the same as order except that + std::memory_order_acq_rel is replaced by std::memory_order_acquire and + std::memory_order_release is replaced by std::memory_order_relaxed. + +atomic>::wait + + void wait( std::shared_ptr old, + std::memory_order order = std::memory_order_seq_cst ) const noexcept; + + Performs an atomic waiting operation. + + Compares load(order) with old and if they are equivalent then blocks until *this is + notified by notify_one() or notify_all(). This is repeated until load(order) + changes. This function is guaranteed to return only if value has changed, even if + underlying implementation unblocks spuriously. + + Memory is ordered according to order. The behavior is undefined if order is + std::memory_order_release or std::memory_order_acq_rel. + + Notes: two shared_ptrs are equivalent if they store the same pointer and either + share ownership or are both empty. + +atomic>::notify_one + + void notify_one() noexcept; + + Performs an atomic notifying operation. + + If there is a thread blocked in atomic waiting operations (i.e. wait()) on *this, + then unblocks at least one such thread; otherwise does nothing. + +atomic>::notify_all + + void notify_all() noexcept; + + Performs an atomic notifying operation. + + Unblocks all threads blocked in atomic waiting operations (i.e. wait()) on *this, if + there are any; otherwise does nothing. + +.SH Member constants + + The only standard std::atomic member constant is_always_lock_free is also provided + by this specialization. + +atomic>::is_always_lock_free + + static constexpr bool is_always_lock_free = /*implementation-defined*/; .SH Notes - There are non-member function template equivalents for all member functions of - std::atomic. Those non-member functions may be additionally overloaded for types - that are not specializations of std::atomic, but are able to guarantee atomicity. - The only such type in the standard library is std::shared_ptr. + Feature-test macro Value Std Feature + __cpp_lib_atomic_shared_ptr 201711L (C++20) std::atomic + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3661 C++20 atomic> was not made constant-initializable + constant-initializable from nullptr + LWG 3893 C++20 LWG3661 made atomic> assignability restored + not assignable from nullptr_t .SH See also - atomic_flag the lock-free boolean atomic type - \fI(C++11)\fP \fI(class)\fP + atomic class template and specializations for bool, integral, + atomic floating-point, + \fI(C++11)\fP \fI(since C++20)\fP and pointer types + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic::atomic.3 b/man/std::atomic::atomic.3 index 101d6e0c2..ef2da285c 100644 --- a/man/std::atomic::atomic.3 +++ b/man/std::atomic::atomic.3 @@ -1,25 +1,38 @@ -.TH std::atomic::atomic 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bool is_lock_free() const; \fI(since C++11)\fP - bool is_lock_free() const volatile; +.TH std::atomic::atomic 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::atomic \- std::atomic::atomic - Checks whether the atomic operations on the object are lock-free. +.SH Synopsis + (since + atomic() noexcept = default; C++11) + (until + C++20) + constexpr atomic() \fB(1)\fP (since + noexcept(std::is_nothrow_default_constructible_v); C++20) + constexpr atomic( T desired ) noexcept; \fB(2)\fP (since + C++11) + atomic( const atomic& ) = delete; \fB(3)\fP (since + C++11) + + Constructs a new atomic variable. + + 1) The default constructor is trivial: no initialization takes place + other than zero initialization of static and thread-local objects. \fI(until C++20)\fP + std::atomic_init may be used to complete initialization. + 1) Value-initializes the underlying object (i.e. with T()). The + initialization is not atomic. \fI(since C++20)\fP + The program is ill-formed if std::is_default_constructible_v is + false. + + 2) Initializes the underlying object with desired. The initialization is not atomic. + 3) Atomic variables are not CopyConstructible. .SH Parameters - \fI(none)\fP - -.SH Return value - - true if the atomic operations on the object are lock-free, false otherwise. - -.SH Exceptions - - noexcept specification: - noexcept - + desired - value to initialize with -.SH See also +.SH Notes - atomic_is_lock_free checks if the atomic type's operations are lock-free - \fI(C++11)\fP \fI(function template)\fP + The default-initialized std::atomic does not contain a T object, + and its only valid uses are destruction and initialization by \fI(until C++20)\fP + std::atomic_init, see LWG issue 2334. diff --git a/man/std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong.3 b/man/std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong.3 index 3d731d484..1daa0df4a 100644 --- a/man/std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong.3 +++ b/man/std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong.3 @@ -1,123 +1,130 @@ -.TH std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong \- std::atomic::compare_exchange_weak,std::atomic::compare_exchange_strong + .SH Synopsis - Defined in header - bool compare_exchange_weak( T& - expected, T desired, - - - std::memory_order success, - - - std::memory_order failure ); - bool compare_exchange_weak( T& - expected, T desired, - - - std::memory_order success, - - - std::memory_order failure ) - volatile; - bool compare_exchange_weak( T& - expected, T desired, - - - std::memory_order order = - - - std::memory_order_seq_cst ); - bool compare_exchange_weak( T& - expected, T desired, - - - std::memory_order order = - - - std::memory_order_seq_cst ) - volatile; \fB(1)\fP (since - bool compare_exchange_strong( T& C++11) - expected, T desired, - - - std::memory_order success, - - - std::memory_order failure ); (since - bool compare_exchange_strong( T& \fB(2)\fP C++11) - expected, T desired, - - - std::memory_order success, - - - std::memory_order failure ) - volatile; \fB(3)\fP (since - bool compare_exchange_strong( T& C++11) - expected, T desired, - - - std::memory_order order = - - - std::memory_order_seq_cst ); (since - bool compare_exchange_strong( T& \fB(4)\fP C++11) - expected, T desired, - - - std::memory_order order = - - - std::memory_order_seq_cst ) - volatile; - - Atomically compares the value stored in *this with the value of expected, and if - those are equal, replaces the former with desired (performs read-modify-write - operation). Otherwise, loads the actual value stored in *this into expected - (performs load operation). - - The memory models for the read-modify-write and load operations are success and - failure respectively. In the \fB(2)\fP and \fB(4)\fP versions order is used for both - read-modify-write and load operations, except that std::memory_order_acquire and - std::memory_order_relaxed are used for the load operation if order == - std::memory_order_acq_rel, or order == std::memory_order_release respectively. - - The weak forms (1-2) of the functions are allowed to fail spuriously, that is, act - as if *this != expected even if they are equal. When a compare-and-exchange is in a - loop, the weak version will yield better performance on some platforms. When a weak - compare-and-exchange would require a loop and a strong one would not, the strong one - is preferable. + bool compare_exchange_weak( T& expected, T desired, + + std::memory_order success, \fB(1)\fP \fI(since C++11)\fP + + std::memory_order failure ) noexcept; + bool compare_exchange_weak( T& expected, T desired, + + std::memory_order success, \fB(2)\fP \fI(since C++11)\fP + + std::memory_order failure ) volatile + noexcept; + bool compare_exchange_weak( T& expected, T desired, + + std::memory_order order = \fB(3)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) + noexcept; + bool compare_exchange_weak( T& expected, T desired, + + std::memory_order order = \fB(4)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) + volatile noexcept; + bool compare_exchange_strong( T& expected, T desired, + + std::memory_order success, \fB(5)\fP \fI(since C++11)\fP + + std::memory_order failure ) + noexcept; + bool compare_exchange_strong( T& expected, T desired, + + std::memory_order success, \fB(6)\fP \fI(since C++11)\fP + + std::memory_order failure ) volatile + noexcept; + bool compare_exchange_strong( T& expected, T desired, + + std::memory_order order = \fB(7)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) + noexcept; + bool compare_exchange_strong + + ( T& expected, T desired, \fB(8)\fP \fI(since C++11)\fP + + std::memory_order order = std::memory_order_seq_cst ) + volatile noexcept; + + Atomically compares the + object representation + \fI(until C++20)\fP + value representation + \fI(since C++20)\fP of *this with that of expected. If those are bitwise-equal, replaces + the former with desired (performs read-modify-write operation). Otherwise, loads the + actual value stored in *this into expected (performs load operation). + + Overloads Memory model for + read‑modify‑write operation load operation + (1,2,5,6) success failure + * std::memory_order_acquire if + order is std::memory_order_acq_rel + (3,4,7,8) order * std::memory_order_relaxed if + order is std::memory_order_release + * otherwise order + + If failure + is stronger than success or + \fI(until C++17)\fP is one of std::memory_order_release and std::memory_order_acq_rel, the + behavior is undefined. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + any volatile overload participates in overload resolution. .SH Parameters expected - reference to the value expected to be found in the atomic object desired - the value to store in the atomic object if it is as expected success - the memory synchronization ordering for the read-modify-write operation - if the comparison succeeds. All values are permitted. - the memory synchronization ordering for the load operation if the - failure - comparison fails. Cannot be std::memory_order_release or - std::memory_order_acq_rel and cannot specify stronger ordering than - success + if the comparison succeeds + failure - the memory synchronization ordering for the load operation if the + comparison fails order - the memory synchronization ordering for both operations .SH Return value - true if the underlying atomic value was changed, false otherwise. + true if the underlying atomic value was successfully changed, false otherwise. -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + The comparison and copying are bitwise (similar to std::memcmp and std::memcpy); no + constructor, assignment operator, or comparison operator are used. + + compare_exchange_weak is allowed to fail spuriously, that is, acts as if *this != + expected even if they are equal. When a compare-and-exchange is in a loop, + compare_exchange_weak will yield better performance on some platforms. + + When compare_exchange_weak would require a loop and compare_exchange_strong would + not, compare_exchange_strong is preferable unless the object representation of T may + include + padding bits, + \fI(until C++20)\fP trap bits, or offers multiple object representations for the same + value (e.g. floating-point NaN). In those cases, compare_exchange_weak typically + works because it quickly converges on some stable object representation. + + For a union with bits that participate in the value representations of some members + but not the others, compare-and-exchange might always fail because such padding bits + have indeterminate values when they do not participate in the value representation + of the active member. + + Padding bits that never participate in an object's value \fI(since C++20)\fP + representation are ignored. .SH Example - compare and exchange operations are often used as basic building blocks of lockfree - data structures + Compare-and-exchange operations are often used as basic building blocks of lock-free + data structures. + - // Run this code #include + template struct node { @@ -125,39 +132,42 @@ node* next; node(const T& data) : data(data), next(nullptr) {} }; - + template class stack { std::atomic*> head; - public: + public: void push(const T& data) { node* new_node = new node(data); - - // // put the current value of head into new_node->next - // new_node->next = head.load(std::memory_order_relaxed); - // - // // now make new_node the new head, but if the head - // // is no longer what's stored in new_node->next - // // (some other thread must have inserted a node just now) - // // then put that new head into new_node->next and try again - // while(!head.compare_exchange_weak(new_node->next, new_node, - // std::memory_order_release, - // std::memory_order_relaxed)) - // ; // the body of the loop is empty - // + + // put the current value of head into new_node->next + new_node->next = head.load(std::memory_order_relaxed); + + // now make new_node the new head, but if the head + // is no longer what's stored in new_node->next + // (some other thread must have inserted a node just now) + // then put that new head into new_node->next and try again + while (!head.compare_exchange_weak(new_node->next, new_node, + std::memory_order_release, + std::memory_order_relaxed)) + ; // the body of the loop is empty + // Note: the above use is not thread-safe in at least - // GCC prior to 4.8.3 (bug 60272), clang (bug 18899), MSVC (bug 819819). - // The following is a workaround: - node* old_head = head.load(std::memory_order_relaxed); - do { - new_node->next = old_head; - } while(!head.compare_exchange_weak(old_head, new_node, - std::memory_order_release, - std::memory_order_relaxed)); + // GCC prior to 4.8.3 (bug 60272), clang prior to 2014-05-05 (bug 18899) + // MSVC prior to 2014-03-17 (bug 819819). The following is a workaround: + // node* old_head = head.load(std::memory_order_relaxed); + // do + // { + // new_node->next = old_head; + // } + // while (!head.compare_exchange_weak(old_head, new_node, + // std::memory_order_release, + // std::memory_order_relaxed)); } }; + int main() { stack s; @@ -166,51 +176,53 @@ s.push(3); } - Demonstrates how compare_exchange_strong either changes the value of the atomic + Demonstrates how std::compare_exchange_strong either changes the value of the atomic variable or the variable used for comparison. - + This section is incomplete + Reason: more practical use of the strong CAS would be nice, such as where + Concurrency in Action uses it + + // Run this code #include #include - - std::atomic ai; - - int tst_val= 4; - int new_val= 5; - bool exchanged= false; - + + std::atomic ai; + + int tst_val = 4; + int new_val = 5; + bool exchanged = false; + void valsout() { - std::cout << "ai= " << ai - << " tst_val= " << tst_val - << " new_val= " << new_val - << " exchanged= " << std::boolalpha << exchanged - << "\\n"; + std::cout << "ai = " << ai + << " tst_val = " << tst_val + << " new_val = " << new_val + << " exchanged = " << std::boolalpha << exchanged + << '\\n'; } - + int main() { - ai= 3; + ai = 3; valsout(); - + // tst_val != ai ==> tst_val is modified - exchanged= ai.compare_exchange_strong( tst_val, new_val ); + exchanged = ai.compare_exchange_strong(tst_val, new_val); valsout(); - + // tst_val == ai ==> ai is modified - exchanged= ai.compare_exchange_strong( tst_val, new_val ); + exchanged = ai.compare_exchange_strong(tst_val, new_val); valsout(); - - return 0; } .SH Output: - ai= 3 tst_val= 4 new_val= 5 exchanged= false - ai= 3 tst_val= 3 new_val= 5 exchanged= false - ai= 5 tst_val= 3 new_val= 5 exchanged= true + ai = 3 tst_val = 4 new_val = 5 exchanged = false + ai = 3 tst_val = 3 new_val = 5 exchanged = false + ai = 5 tst_val = 3 new_val = 5 exchanged = true .SH See also @@ -219,6 +231,9 @@ atomic_compare_exchange_strong object with non-atomic argument and performs atomic_compare_exchange_strong_explicit atomic exchange if equal or atomic load if \fI(C++11)\fP not - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP \fI(C++11)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::atomic::exchange.3 b/man/std::atomic::exchange.3 index ebb4b3e0e..6bc5cb832 100644 --- a/man/std::atomic::exchange.3 +++ b/man/std::atomic::exchange.3 @@ -1,31 +1,107 @@ -.TH std::atomic::exchange 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::exchange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::exchange \- std::atomic::exchange + .SH Synopsis - T exchange( T desired, memory_order = std::memory_order_seq_cst ); - T exchange( T desired, memory_order = std::memory_order_seq_cst ) \fI(since C++11)\fP - volatile; + T exchange( T desired, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + T exchange( T desired, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; + + Atomically replaces the underlying value with desired (a read-modify-write + operation). Memory is affected according to the value of order. - Atomically replaces the underlying value with desired. The operation is - read-modify-write operation. Memory is affected according to the value of - memory_order. + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. .SH Parameters - desired - value to assign - memory_order - memory order constraints to enforce + desired - value to assign + order - memory order constraints to enforce .SH Return value The value of the atomic variable before the call. -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + constexpr int thread_count{5}; + constexpr int sum{5}; + + std::atomic atom{0}; + std::atomic counter{0}; + + auto increment_to_sum = [&](const int id) + { + for (int next = 0; next < sum;) + { + // each thread is writing a value from its own knowledge + const int current = atom.exchange(next); + counter++; + // sync writing to prevent from interrupting by other threads + std::osyncstream(std::cout) + << "Thread #" << id << " (id=" << std::this_thread::get_id() + << ") wrote " << next << " replacing the old value " + << current << ".\\n"; + next = std::max(current, next) + 1; + } + }; + + std::vector v; + for (std::size_t i = 0; i < thread_count; ++i) + v.emplace_back(increment_to_sum, i); + + for (auto& tr : v) + tr.join(); + + std::cout << thread_count << " threads take " + << counter << " times in total to " + << "increment 0 to " << sum << ".\\n"; + } + +.SH Possible output: - noexcept specification: - noexcept - + Thread #1 (id=139722332333824) wrote 0 replacing the old value 0. + Thread #2 (id=139722323941120) wrote 0 replacing the old value 0. + Thread #1 (id=139722332333824) wrote 1 replacing the old value 0. + Thread #1 (id=139722332333824) wrote 2 replacing the old value 1. + Thread #1 (id=139722332333824) wrote 3 replacing the old value 2. + Thread #1 (id=139722332333824) wrote 4 replacing the old value 3. + Thread #0 (id=139722340726528) wrote 0 replacing the old value 0. + Thread #3 (id=139722315548416) wrote 0 replacing the old value 0. + Thread #3 (id=139722315548416) wrote 1 replacing the old value 4. + Thread #0 (id=139722340726528) wrote 1 replacing the old value 1. + Thread #4 (id=139722307155712) wrote 0 replacing the old value 1. + Thread #4 (id=139722307155712) wrote 2 replacing the old value 2. + Thread #4 (id=139722307155712) wrote 3 replacing the old value 2. + Thread #4 (id=139722307155712) wrote 4 replacing the old value 3. + Thread #2 (id=139722323941120) wrote 1 replacing the old value 0. + Thread #0 (id=139722340726528) wrote 2 replacing the old value 1. + Thread #2 (id=139722323941120) wrote 2 replacing the old value 4. + Thread #0 (id=139722340726528) wrote 3 replacing the old value 2. + Thread #0 (id=139722340726528) wrote 4 replacing the old value 3. + 5 threads take 19 times in total to increment 0 to 5. .SH See also atomic_exchange atomically replaces the value of the atomic object with atomic_exchange_explicit non-atomic argument and returns the old value of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP + exchange replaces the argument with a new value and returns its + \fI(C++14)\fP previous value + \fI(function template)\fP diff --git a/man/std::atomic::fetch_add.3 b/man/std::atomic::fetch_add.3 index 683c0b9e4..18bbd4587 100644 --- a/man/std::atomic::fetch_add.3 +++ b/man/std::atomic::fetch_add.3 @@ -1,44 +1,119 @@ -.TH std::atomic::fetch_add 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::fetch_add 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_add \- std::atomic::fetch_add + .SH Synopsis - T fetch_add( T arg, - memory_order = - std::memory_order_seq_cst ); - T fetch_add( T arg, \fI(since C++11)\fP - memory_order = (member only of - std::memory_order_seq_cst ) volatile; \fB(1)\fP atomic - T* fetch_add( std::ptrdiff_t arg, template \fI(since C++11)\fP - memory_order = specialization) (member only of - std::memory_order_seq_cst ); \fB(2)\fP atomic - T* fetch_add( std::ptrdiff_t arg, template - memory_order = specialization) - std::memory_order_seq_cst ) volatile; + member only of atomic specializations + and atomic specializations + \fI(since C++20)\fP + T fetch_add( T arg, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + T fetch_add( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; + member only of atomic partial specialization + T* fetch_add( std::ptrdiff_t arg, + + std::memory_order order = \fB(3)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) noexcept; + T* fetch_add( std::ptrdiff_t arg, + + std::memory_order order = \fB(4)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) volatile noexcept; Atomically replaces the current value with the result of arithmetic addition of the - value and arg. The operation is read-modify-write operation. Memory is affected - according to the value of memory_order. + value and arg. That is, it performs atomic post-increment. The operation is a + read-modify-write operation. Memory is affected according to the value of order. - For signed Integral types, arithmetic is defined to use two’s complement - representation. There are no undefined results. For T* types, the result may be an - undefined address, but the operations otherwise have no undefined behavior. + 1,2) For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + + For floating-point types, the floating-point environment in effect may + be different from the calling thread's floating-point environment. The + operation need not conform to the corresponding std::numeric_limits \fI(since C++20)\fP + traits but is encouraged to do so. If the result is not a + representable value for its type, the result is unspecified but the + operation otherwise has no undefined behavior. + + 3,4) The result may be an undefined address, but the operation otherwise has no + undefined behavior. + If T is not a complete object type, the program is ill-formed. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP or \fB(4)\fP participates in overload resolution. .SH Parameters - arg - the other argument of arithmetic addition - memory_order - memory order constraints to enforce + arg - the other argument of arithmetic addition + order - memory order constraints to enforce .SH Return value - The value of the atomic variable before the call. + The value immediately preceding the effects of this function in the modification + order of *this. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + std::atomic data{10}; + std::array return_values{}; + + void do_work(int thread_num) + { + long long val = data.fetch_add(1, std::memory_order_relaxed); + return_values[thread_num] = val; + } + + int main() + { + { + std::jthread th0{do_work, 0}; + std::jthread th1{do_work, 1}; + std::jthread th2{do_work, 2}; + std::jthread th3{do_work, 3}; + std::jthread th4{do_work, 4}; + } + + std::cout << "Result : " << data << '\\n'; + + for (long long val : return_values) + std::cout << "Seen return value : " << val << std::endl; + } + +.SH Possible output: + + Result : 15 + Seen return value : 11 + Seen return value : 10 + Seen return value : 14 + Seen return value : 12 + Seen return value : 13 + + Defect reports -.SH Exceptions + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 arithmetic permitted on pointers to (possibly made ill-formed + cv-qualified) void or function .SH See also atomic_fetch_add adds a non-atomic value to an atomic object and obtains atomic_fetch_add_explicit the previous value of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP + operator++ + operator++(int) increments or decrements the atomic value by one + operator-- \fI(public member function)\fP + operator--(int) diff --git a/man/std::atomic::fetch_and.3 b/man/std::atomic::fetch_and.3 index 6db8b3830..fb60f417e 100644 --- a/man/std::atomic::fetch_and.3 +++ b/man/std::atomic::fetch_and.3 @@ -1,34 +1,35 @@ -.TH std::atomic::fetch_and 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::fetch_and 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_and \- std::atomic::fetch_and + .SH Synopsis - T fetch_and( T arg, - memory_order = \fI(since C++11)\fP - std::memory_order_seq_cst ); (member only of atomic - T fetch_and( T arg, template specialization) - memory_order = - std::memory_order_seq_cst ) volatile; + member only of atomic specializations + T fetch_and( T arg, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + T fetch_and( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; Atomically replaces the current value with the result of bitwise AND of the value and arg. The operation is read-modify-write operation. Memory is affected according - to the value of memory_order. + to the value of order. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. .SH Parameters - arg - the other argument of bitwise AND - memory_order - memory order constraints to enforce + arg - the other argument of bitwise AND + order - memory order constraints to enforce .SH Return value - The value of the atomic variable before the call. - -.SH Exceptions - - noexcept specification: - noexcept - + The value immediately preceding the effects of this function in the modification + order of *this. .SH See also - atomic_fetch_and replaces the atomic object with the result of logical AND + atomic_fetch_and replaces the atomic object with the result of bitwise AND atomic_fetch_and_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::atomic::fetch_max.3 b/man/std::atomic::fetch_max.3 new file mode 100644 index 000000000..705d6ce15 --- /dev/null +++ b/man/std::atomic::fetch_max.3 @@ -0,0 +1,50 @@ +.TH std::atomic::fetch_max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_max \- std::atomic::fetch_max + +.SH Synopsis + member only of atomic specializations + T fetch_max( T arg, std::memory_order order = \fB(1)\fP (since C++26) + std::memory_order_seq_cst ) noexcept; + T fetch_max( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP (since C++26) + noexcept; + member only of atomic partial specialization + T* fetch_max( T* arg, std::memory_order order = \fB(3)\fP (since C++26) + std::memory_order_seq_cst ) noexcept; + T* fetch_max( T* arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(4)\fP (since C++26) + noexcept; + + Atomically replaces the current value with the result of std::max of the value and + arg. That is, it performs atomic maximum operation. The operation is a + read-modify-write operation. Memory is affected according to the value of order. + + 3,4) If the pointers point to different complete objects (or subobjects thereof), + pointer comparison does not establish a strict weak ordering. + + It is deprecated if std::atomic::is_always_lock_free is false and overload \fB(2)\fP or + \fB(4)\fP participates in overload resolution. + +.SH Parameters + + arg - the other argument of std::max + order - memory order constraints to enforce + +.SH Return value + + The value immediately preceding the effects of this function in the modification + order of *this. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_min_max 202403L (C++26) Atomic minimum/maximum + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic::fetch_min.3 b/man/std::atomic::fetch_min.3 new file mode 100644 index 000000000..dbb01edb8 --- /dev/null +++ b/man/std::atomic::fetch_min.3 @@ -0,0 +1,50 @@ +.TH std::atomic::fetch_min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_min \- std::atomic::fetch_min + +.SH Synopsis + member only of atomic specializations + T fetch_min( T arg, std::memory_order order = \fB(1)\fP (since C++26) + std::memory_order_seq_cst ) noexcept; + T fetch_min( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP (since C++26) + noexcept; + member only of atomic partial specialization + T* fetch_min( T* arg, std::memory_order order = \fB(3)\fP (since C++26) + std::memory_order_seq_cst ) noexcept; + T* fetch_min( T* arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(4)\fP (since C++26) + noexcept; + + Atomically replaces the current value with the result of std::min of the value and + arg. That is, it performs atomic minimum operation. The operation is a + read-modify-write operation. Memory is affected according to the value of order. + + 3,4) If the pointers point to different complete objects (or subobjects thereof), + pointer comparison does not establish a strict weak ordering. + + It is deprecated if std::atomic::is_always_lock_free is false and overload \fB(2)\fP or + \fB(4)\fP participates in overload resolution. + +.SH Parameters + + arg - the other argument of std::min + order - memory order constraints to enforce + +.SH Return value + + The value immediately preceding the effects of this function in the modification + order of *this. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_min_max 202403L (C++26) Atomic minimum/maximum + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic::fetch_or.3 b/man/std::atomic::fetch_or.3 index b1349b703..79b769a12 100644 --- a/man/std::atomic::fetch_or.3 +++ b/man/std::atomic::fetch_or.3 @@ -1,34 +1,35 @@ -.TH std::atomic::fetch_or 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::fetch_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_or \- std::atomic::fetch_or + .SH Synopsis - T fetch_or( T arg, - memory_order = \fI(since C++11)\fP - std::memory_order_seq_cst ); (member only of atomic - T fetch_or( T arg, template specialization) - memory_order = - std::memory_order_seq_cst ) volatile; + member only of atomic specializations + T fetch_or( T arg, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + T fetch_or( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; Atomically replaces the current value with the result of bitwise OR of the value and arg. The operation is read-modify-write operation. Memory is affected according to - the value of memory_order. + the value of order. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. .SH Parameters - arg - the other argument of bitwise OR - memory_order - memory order constraints to enforce + arg - the other argument of bitwise OR + order - memory order constraints to enforce .SH Return value - The value of the atomic variable before the call. - -.SH Exceptions - - noexcept specification: - noexcept - + The value immediately preceding the effects of this function in the modification + order of *this. .SH See also - atomic_fetch_or replaces the atomic object with the result of logical OR + atomic_fetch_or replaces the atomic object with the result of bitwise OR atomic_fetch_or_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::atomic::fetch_sub.3 b/man/std::atomic::fetch_sub.3 index a2643141d..30466e0b4 100644 --- a/man/std::atomic::fetch_sub.3 +++ b/man/std::atomic::fetch_sub.3 @@ -1,44 +1,75 @@ -.TH std::atomic::fetch_sub 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::fetch_sub 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_sub \- std::atomic::fetch_sub + .SH Synopsis - T fetch_sub( T arg, - memory_order = - std::memory_order_seq_cst ); - T fetch_sub( T arg, \fI(since C++11)\fP - memory_order = (member only of - std::memory_order_seq_cst ) volatile; atomic - T* fetch_sub( std::ptrdiff_t arg, template - memory_order = specialization) \fI(since C++11)\fP - std::memory_order_seq_cst ); (member only of - T* fetch_sub( std::ptrdiff_t arg, atomic template - memory_order = specialization) - std::memory_order_seq_cst ) volatile; + member only of atomic specializations + and atomic specializations + \fI(since C++20)\fP + T fetch_sub( T arg, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + T fetch_sub( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; + member only of atomic partial specialization + T* fetch_sub( std::ptrdiff_t arg, + + std::memory_order order = \fB(3)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) noexcept; + T* fetch_sub( std::ptrdiff_t arg, + + std::memory_order order = \fB(4)\fP \fI(since C++11)\fP + + std::memory_order_seq_cst ) volatile noexcept; Atomically replaces the current value with the result of arithmetic subtraction of - the value and arg. The operation is read-modify-write operation. Memory is affected - according to the value of memory_order. + the value and arg. That is, it performs atomic post-decrement. The operation is + read-modify-write operation. Memory is affected according to the value of order. - For signed Integral types, arithmetic is defined to use two’s complement - representation. There are no undefined results. For T* types, the result may be an - undefined address, but the operations otherwise have no undefined behavior. + 1,2) For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + + For floating-point types, the floating-point environment in effect may + be different from the calling thread's floating-point environment. The + operation need not be conform to the corresponding std::numeric_limits \fI(since C++20)\fP + traits but is encouraged to do so. If the result is not a + representable value for its type, the result is unspecified but the + operation otherwise has no undefined behavior. + + 3,4) The result may be an undefined address, but the operation otherwise has no + undefined behavior. + If T is not a complete object type, the program is ill-formed. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP or \fB(4)\fP participates in overload resolution. .SH Parameters - arg - the other argument of arithmetic subtraction - memory_order - memory order constraints to enforce + arg - the other argument of arithmetic subtraction + order - memory order constraints to enforce .SH Return value - The value of the atomic variable before the call. + The value immediately preceding the effects of this function in the modification + order of *this. + + Defect reports -.SH Exceptions + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 arithmetic permitted on pointers to (possibly made ill-formed + cv-qualified) void or function .SH See also atomic_fetch_sub subtracts a non-atomic value from an atomic object and atomic_fetch_sub_explicit obtains the previous value of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP + operator++ + operator++(int) increments or decrements the atomic value by one + operator-- \fI(public member function)\fP + operator--(int) diff --git a/man/std::atomic::fetch_xor.3 b/man/std::atomic::fetch_xor.3 index 1a169dc39..2a850bc15 100644 --- a/man/std::atomic::fetch_xor.3 +++ b/man/std::atomic::fetch_xor.3 @@ -1,34 +1,35 @@ -.TH std::atomic::fetch_xor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::fetch_xor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::fetch_xor \- std::atomic::fetch_xor + .SH Synopsis - T fetch_xor( T arg, - memory_order = \fI(since C++11)\fP - std::memory_order_seq_cst ); (member only of atomic - T fetch_xor( T arg, template specialization) - memory_order = - std::memory_order_seq_cst ) volatile; + member only of atomic specializations + T fetch_xor( T arg, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + T fetch_xor( T arg, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; Atomically replaces the current value with the result of bitwise XOR of the value and arg. The operation is read-modify-write operation. Memory is affected according - to the value of memory_order. + to the value of order. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. .SH Parameters - arg - the other argument of bitwise XOR - memory_order - memory order constraints to enforce + arg - the other argument of bitwise XOR + order - memory order constraints to enforce .SH Return value - The value of the atomic variable before the call. - -.SH Exceptions - - noexcept specification: - noexcept - + The value immediately preceding the effects of this function in the modification + order of *this. .SH See also - atomic_fetch_xor replaces the atomic object with the result of logical XOR + atomic_fetch_xor replaces the atomic object with the result of bitwise XOR atomic_fetch_xor_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::atomic::is_always_lock_free.3 b/man/std::atomic::is_always_lock_free.3 new file mode 100644 index 000000000..a24db8a3f --- /dev/null +++ b/man/std::atomic::is_always_lock_free.3 @@ -0,0 +1,31 @@ +.TH std::atomic::is_always_lock_free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::is_always_lock_free \- std::atomic::is_always_lock_free + +.SH Synopsis + static constexpr bool is_always_lock_free = \fI(since C++17)\fP + /*implementation-defined*/; + + Equals true if this atomic type is always lock-free and false if it is never or + sometimes lock-free. + + The value of this constant is consistent with both the macro ATOMIC_xxx_LOCK_FREE, + where defined, with the member function is_lock_free and non-member function + std::atomic_is_lock_free. + +.SH Notes + + There is no non-member function equivalent of this static member constant because + non-member functions take pointers to atomic types, and therefore aren't as useful + in constant expressions. + + Feature-test macro Value Std Feature + __cpp_lib_atomic_is_always_lock_free 201603L \fI(C++17)\fP constexpr + atomic::is_always_lock_free + +.SH See also + + is_lock_free checks if the atomic object is lock-free + \fI(public member function)\fP + atomic_is_lock_free checks if the atomic type's operations are lock-free + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::atomic::is_lock_free.3 b/man/std::atomic::is_lock_free.3 new file mode 100644 index 000000000..39698c219 --- /dev/null +++ b/man/std::atomic::is_lock_free.3 @@ -0,0 +1,67 @@ +.TH std::atomic::is_lock_free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::is_lock_free \- std::atomic::is_lock_free + +.SH Synopsis + bool is_lock_free() const noexcept; \fB(1)\fP \fI(since C++11)\fP + bool is_lock_free() const volatile noexcept; \fB(2)\fP \fI(since C++11)\fP + + Checks whether the atomic operations on all objects of this type are lock-free. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the atomic operations on the objects of this type are lock-free, false + otherwise. + +.SH Notes + + All atomic types except for std::atomic_flag may be implemented using mutexes or + other locking operations, rather than using the lock-free atomic CPU instructions. + Atomic types are also allowed to be sometimes lock-free, e.g. if only aligned memory + accesses are naturally atomic on a given architecture, misaligned objects of the + same type have to use locks. + + The C++ standard recommends (but does not require) that lock-free atomic operations + are also address-free, that is, suitable for communication between processes using + shared memory. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct A { int a[100]; }; + struct B { int x, y; }; + + int main() + { + std::cout << std::boolalpha + << "std::atomic is lock free? " + << std::atomic{}.is_lock_free() << '\\n' + << "std::atomic is lock free? " + << std::atomic{}.is_lock_free() << '\\n'; + } + +.SH Possible output: + + std::atomic is lock free? false + std::atomic is lock free? true + +.SH See also + + atomic_is_lock_free checks if the atomic type's operations are + \fI(C++11)\fP lock-free + \fI(function template)\fP + specializes atomic operations for + atomic_is_lock_free(std::shared_ptr) std::shared_ptr + \fI(function template)\fP + is_always_lock_free indicates that the type is always lock-free + \fB[static]\fP \fI(C++17)\fP \fI(public static member constant)\fP diff --git a/man/std::atomic::load.3 b/man/std::atomic::load.3 index 36d3206e2..7374000e3 100644 --- a/man/std::atomic::load.3 +++ b/man/std::atomic::load.3 @@ -1,34 +1,35 @@ -.TH std::atomic::load 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::load 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::load \- std::atomic::load + .SH Synopsis - T load( memory_order = std::memory_order_seq_cst ) const; \fI(since C++11)\fP - T load( memory_order = std::memory_order_seq_cst ) const volatile; + T load( std::memory_order order \fB(1)\fP \fI(since C++11)\fP + = std::memory_order_seq_cst ) const noexcept; + T load( std::memory_order order \fB(2)\fP \fI(since C++11)\fP + = std::memory_order_seq_cst ) const volatile noexcept; Atomically loads and returns the current value of the atomic variable. Memory is - affected according to the value of memory_order. + affected according to the value of order. + + If order is one of std::memory_order_release and std::memory_order_acq_rel, the + behavior is undefined. - memory_order must be one of std::memory_order_relaxed, std::memory_order_consume, - std::memory_order_acquire or std::memory_order_seq_cst. Otherwise the behavior is - undefined. + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. .SH Parameters - memory_order - memory order constraints to enforce + order - memory order constraints to enforce .SH Return value The current value of the atomic variable. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also operator T loads a value from an atomic object - \fI(public member function)\fP + \fI(public member function)\fP atomic_load atomic_load_explicit atomically obtains the value stored in an atomic object - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP diff --git a/man/std::atomic::notify_all.3 b/man/std::atomic::notify_all.3 new file mode 100644 index 000000000..244e43441 --- /dev/null +++ b/man/std::atomic::notify_all.3 @@ -0,0 +1,40 @@ +.TH std::atomic::notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::notify_all \- std::atomic::notify_all + +.SH Synopsis + void notify_all() noexcept; \fB(1)\fP \fI(since C++20)\fP + void notify_all() volatile noexcept; \fB(2)\fP \fI(since C++20)\fP + + Performs atomic notifying operations. + + Unblocks all threads blocked in atomic waiting operations (i.e. wait()) on *this, if + there are any; otherwise does nothing. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value changes + (C++20) \fI(public member function)\fP + atomic_wait + atomic_wait_explicit blocks the thread until notified and the atomic value changes + (C++20) \fI(function template)\fP + (C++20) + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic::notify_one.3 b/man/std::atomic::notify_one.3 new file mode 100644 index 000000000..388acf237 --- /dev/null +++ b/man/std::atomic::notify_one.3 @@ -0,0 +1,40 @@ +.TH std::atomic::notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::notify_one \- std::atomic::notify_one + +.SH Synopsis + void notify_one() noexcept; \fB(1)\fP \fI(since C++20)\fP + void notify_one() volatile noexcept; \fB(2)\fP \fI(since C++20)\fP + + Performs atomic notifying operations. + + If there is a thread blocked in atomic waiting operation (i.e. wait()) on *this, + then unblocks at least one such thread; otherwise does nothing. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value changes + (C++20) \fI(public member function)\fP + atomic_wait + atomic_wait_explicit blocks the thread until notified and the atomic value changes + (C++20) \fI(function template)\fP + (C++20) + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic::operator&=,|=,^=.3 b/man/std::atomic::operator&=,|=,^=.3 new file mode 100644 index 000000000..f7eec69cc --- /dev/null +++ b/man/std::atomic::operator&=,|=,^=.3 @@ -0,0 +1,59 @@ +.TH std::atomic::operator&=,|=,^= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::operator&=,|=,^= \- std::atomic::operator&=,|=,^= + +.SH Synopsis + member only of atomic specializations + T operator&=( T arg ) noexcept; \fB(1)\fP \fI(since C++11)\fP + T operator&=( T arg ) volatile noexcept; \fB(2)\fP \fI(since C++11)\fP + T operator|=( T arg ) noexcept; \fB(3)\fP \fI(since C++11)\fP + T operator|=( T arg ) volatile noexcept; \fB(4)\fP \fI(since C++11)\fP + T operator^=( T arg ) noexcept; \fB(5)\fP \fI(since C++11)\fP + T operator^=( T arg ) volatile noexcept; \fB(6)\fP \fI(since C++11)\fP + + Atomically replaces the current value with the result of computation involving the + previous value and arg. The operation is read-modify-write operation. + + * operator&= performs atomic bitwise and. Equivalent to return fetch_and(arg) & + arg;. + * operator|= performs atomic bitwise or. Equivalent to return fetch_or(arg) | + arg;. + * operator^= performs atomic bitwise exclusive or. Equivalent to return + fetch_xor(arg) ^ arg;. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + any volatile overload participates in overload resolution. + +.SH Parameters + + arg - the argument for the arithmetic operation + +.SH Return value + + The resulting value (that is, the result of applying the corresponding binary + operator to the value immediately preceding the effects of the corresponding member + function in the modification order of *this). + +.SH Notes + + Unlike most compound assignment operators, the compound assignment operators for + atomic types do not return a reference to their left-hand arguments. They return a + copy of the stored value instead. + +.SH See also + + atomically performs bitwise AND between the argument and the value + fetch_and of the atomic object and obtains the value held previously + \fI(public member function)\fP + atomically performs bitwise OR between the argument and the value of + fetch_or the atomic object and obtains the value held previously + \fI(public member function)\fP + atomically performs bitwise XOR between the argument and the value + fetch_xor of the atomic object and obtains the value held previously + \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the atomic value by one + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds to or subtracts from the atomic value + operator-= \fI(public member function)\fP diff --git a/man/std::atomic::operator++,++(int),--,--(int).3 b/man/std::atomic::operator++,++(int),--,--(int).3 index 920573904..1ef5db810 100644 --- a/man/std::atomic::operator++,++(int),--,--(int).3 +++ b/man/std::atomic::operator++,++(int),--,--(int).3 @@ -1,56 +1,57 @@ -.TH std::atomic::operator++,++(int),--,--(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::operator++,++(int),--,--(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::operator++,++(int),--,--(int) \- std::atomic::operator++,++(int),--,--(int) + .SH Synopsis - T operator++(); (member only of atomic template - T operator++() volatile; \fB(1)\fP specialization) - \fI(since C++11)\fP - T* operator++(); (member only of atomic template - T* operator++() volatile; \fB(1)\fP specialization) - \fI(since C++11)\fP - T operator++( int ); (member only of atomic template - T operator++( int ) volatile; \fB(2)\fP specialization) - \fI(since C++11)\fP - T* operator++( int ); (member only of atomic template - T* operator++( int ) volatile; \fB(2)\fP specialization) - \fI(since C++11)\fP - T operator--(); (member only of atomic template - T operator--() volatile; \fB(3)\fP specialization) - \fI(since C++11)\fP - T* operator--(); (member only of atomic template - T* operator--() volatile; \fB(3)\fP specialization) - \fI(since C++11)\fP - T operator--( int ); (member only of atomic template - T operator--( int ) volatile; \fB(4)\fP specialization) - \fI(since C++11)\fP - T* operator--( int ); (member only of atomic template - T* operator--( int ) volatile; \fB(4)\fP specialization) - \fI(since C++11)\fP + member only of atomic specializations + T operator++() noexcept; \fB(1)\fP \fI(since C++11)\fP + T operator++() volatile noexcept; \fB(2)\fP \fI(since C++11)\fP + T operator++( int ) noexcept; \fB(3)\fP \fI(since C++11)\fP + T operator++( int ) volatile noexcept; \fB(4)\fP \fI(since C++11)\fP + T operator--() noexcept; \fB(5)\fP \fI(since C++11)\fP + T operator--() volatile noexcept; \fB(6)\fP \fI(since C++11)\fP + T operator--( int ) noexcept; \fB(7)\fP \fI(since C++11)\fP + T operator--( int ) volatile noexcept; \fB(8)\fP \fI(since C++11)\fP + member only of atomic partial specialization + T* operator++() noexcept; \fB(9)\fP \fI(since C++11)\fP + T* operator++() volatile noexcept; \fB(10)\fP \fI(since C++11)\fP + T* operator++( int ) noexcept; \fB(11)\fP \fI(since C++11)\fP + T* operator++( int ) volatile noexcept; \fB(12)\fP \fI(since C++11)\fP + T* operator--() noexcept; \fB(13)\fP \fI(since C++11)\fP + T* operator--() volatile noexcept; \fB(14)\fP \fI(since C++11)\fP + T* operator--( int ) noexcept; \fB(15)\fP \fI(since C++11)\fP + T* operator--( int ) volatile noexcept; \fB(16)\fP \fI(since C++11)\fP Atomically increments or decrements the current value. The operation is read-modify-write operation. - 1) Performs atomic pre-increment. Equivalent to fetch_add\fB(1)\fP+1. - 2) Performs atomic post-increment. Equivalent to fetch_add\fB(1)\fP. - 3) Performs atomic pre-decrement. Equivalent to fetch_sub\fB(1)\fP-1 - 4) Performs atomic post-decrement. Equivalent to fetch_sub\fB(1)\fP. - - For signed Integral types, arithmetic is defined to use two’s complement - representation. There are no undefined results. For T* types, the result may be an - undefined address, but the operations otherwise have no undefined behavior. - -.SH Parameters + * operator++() performs atomic pre-increment. Equivalent to return fetch_add\fB(1)\fP + + 1;. + * operator++(int) performs atomic post-increment. Equivalent to return + fetch_add\fB(1)\fP;. + * operator--() performs atomic pre-decrement. Equivalent to return fetch_sub\fB(1)\fP - + 1;. + * operator--(int) performs atomic post-decrement. Equivalent to return + fetch_sub\fB(1)\fP;. + 1-8) For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + 9-16) The result may be an undefined address, but the operations otherwise have no + undefined behavior. + If T is not a complete object type, the program is ill-formed. - \fI(none)\fP + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + any volatile overload participates in overload resolution. .SH Return value - 1,3) The value of the atomic variable after the modification. - 2,4) The value of the atomic variable before the modification. + operator++() and operator--() return the value of the atomic variable after the + modification. Formally, the result of incrementing/decrementing the value + immediately preceding the effects of this function in the modification order of + *this. -.SH Exceptions - - noexcept specification: - noexcept - + operator++(int) and operator--(int) return the value of the atomic variable before + the modification. Formally, the value immediately preceding the effects of this + function in the modification order of *this. .SH Notes @@ -58,16 +59,95 @@ pre-decrement operators for atomic types do not return a reference to the modified object. They return a copy of the stored value instead. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + std::atomic atomic_count{0}; + + std::mutex cout_mutex; + int completed_writes{0}; + + constexpr int global_max_count{72}; + constexpr int writes_per_line{8}; + constexpr int max_delay{100}; + + template + int random_value() + { + static std::uniform_int_distribution distr{1, Max}; + static std::random_device engine; + static std::mt19937 noise{engine()}; + static std::mutex rand_mutex; + std::lock_guard lock{rand_mutex}; + return distr(noise); + } + + int main() + { + auto work = [](const std::string id) + { + for (int count{}; (count = ++atomic_count) <= global_max_count;) + { + std::this_thread::sleep_for( + std::chrono::milliseconds(random_value())); + + // print thread `id` and `count` value + { + std::lock_guard lock{cout_mutex}; + + const bool new_line = ++completed_writes % writes_per_line == 0; + + std::cout << id << std::setw(3) << count << " " + << (new_line ? "\\n" : "") << std::flush; + } + } + }; + + std::jthread j1(work, "░"), j2(work, "▒"), j3(work, "▓"), j4(work, "█"); + } + +.SH Possible output: + + ▒ 2 ░ 1 ▒ 5 ▒ 7 █ 4 ░ 6 ▓ 3 ▒ 8 + ▓ 11 █ 9 ▓ 13 ░ 10 █ 14 ▒ 12 ░ 16 ░ 19 + ▓ 15 ▒ 18 ▓ 21 ▒ 22 █ 17 █ 25 ▒ 24 █ 26 + ░ 20 ░ 29 ▒ 27 ▓ 23 ▒ 31 ▒ 33 ▓ 32 █ 28 + ░ 30 ░ 37 ▒ 34 ▓ 35 █ 36 █ 41 ▓ 40 ▒ 39 + ░ 38 ▓ 43 █ 42 ▓ 46 ▓ 48 █ 47 █ 50 ░ 45 + ▒ 44 ▒ 53 ▒ 54 ▓ 49 ▒ 55 █ 51 ▒ 57 █ 58 + ░ 52 ▓ 56 ░ 61 ▒ 59 █ 60 ▓ 62 ▒ 64 ░ 63 + ░ 68 ▓ 66 █ 65 █ 71 ▒ 67 ▓ 70 ░ 69 █ 72 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 arithmetic permitted on pointers to (possibly made ill-formed + cv-qualified) void or function + .SH See also - fetch_add atomically adds the argument to the value stored in the atomic object and - \fI(C++11)\fP obtains the value held previously - \fI(public member function)\fP - fetch_sub atomically subtracts the argument from the value stored in the atomic - \fI(C++11)\fP object and obtains the value held previously - \fI(public member function)\fP - operator+= - operator-= adds, subtracts, or performs bitwise AND, OR, XOR with the atomic value - operator&= \fI(public member function)\fP - operator|= + atomically adds the argument to the value stored in the atomic object and + fetch_add obtains the value held previously + \fI(public member function)\fP + atomically subtracts the argument from the value stored in the atomic + fetch_sub object and obtains the value held previously + \fI(public member function)\fP + operator+= adds to or subtracts from the atomic value + operator-= \fI(public member function)\fP + operator&= performs bitwise AND, OR, XOR with the atomic value + operator|= \fI(public member function)\fP operator^= diff --git a/man/std::atomic::operator+=,-=,&=,|=,^=.3 b/man/std::atomic::operator+=,-=,&=,|=,^=.3 deleted file mode 100644 index 31fd4bf8c..000000000 --- a/man/std::atomic::operator+=,-=,&=,|=,^=.3 +++ /dev/null @@ -1,81 +0,0 @@ -.TH std::atomic::operator+=,-=,&=,|=,^= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis -T operator+=( -T arg ); -T operator+=( -T arg ) -volatile; -T* operator+=( -std::ptrdiff_t -arg ); -T* operator+=( -std::ptrdiff_t -arg ) -volatile; -T operator-=( -T arg ); -T operator-=( -T arg ) -volatile; -T* operator-=( \fI(since C++11)\fP -std::ptrdiff_t (member only of -arg ); \fB(1)\fP atomic \fI(since C++11)\fP -T* operator-=( template (member only of -std::ptrdiff_t specialization) \fB(1)\fP atomic -arg ) template -volatile; specialization) \fI(since C++11)\fP -T operator&=( (member only of -T arg ); \fB(2)\fP atomic \fI(since C++11)\fP -T operator&=( template (member only of -T arg ) specialization) \fB(2)\fP atomic -volatile; template -T operator|=( specialization) \fI(since C++11)\fP -T arg ); (member only of -T operator|=( \fB(3)\fP atomic \fI(since C++11)\fP -T arg ) template (member only of -volatile; specialization) \fB(4)\fP atomic -T operator^=( template \fI(since C++11)\fP -T arg ); specialization) (member only of -T operator^=( \fB(5)\fP atomic -T arg ) template -volatile; specialization) - - Atomically replaces the current value with the result of computation involving the - previous value and arg. The operation is read-modify-write operation. - - 1) Performs atomic addition. Equivalent to fetch_add(arg) + arg. - 2) Performs atomic subtraction. Equivalent to fetch_sub(arg) - arg. - 3) Performs atomic bitwise and. Equivalent to fetch_and(arg) & arg. - 4) Performs atomic bitwise or. Equivalent to fetch_or(arg) | arg. - 5) Performs atomic bitwise exclusive or. Equivalent to fetch_xor(arg) ^ arg. - - For signed Integral types, arithmetic is defined to use two’s complement - representation. There are no undefined results. For T* types, the result may be an - undefined address, but the operations otherwise have no undefined behavior. - -.SH Parameters - - arg - the argument for the arithmetic operation - -.SH Return value - - The resulting value. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Notes - - Unlike most compound assignment operators, the compound assignment operators for - atomic types do not return a reference to their left-hand arguments. They return a - copy of the stored value instead. - -.SH See also - - operator++ - operator++(int) increments or decrements the atomic value by one - operator-- \fI(public member function)\fP - operator--(int) diff --git a/man/std::atomic::operator+=,-=.3 b/man/std::atomic::operator+=,-=.3 new file mode 100644 index 000000000..4c9be0dea --- /dev/null +++ b/man/std::atomic::operator+=,-=.3 @@ -0,0 +1,81 @@ +.TH std::atomic::operator+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::operator+=,-= \- std::atomic::operator+=,-= + +.SH Synopsis + member only of atomic specializations + and atomic specializations + \fI(since C++20)\fP + T operator+=( T arg ) noexcept; \fB(1)\fP \fI(since C++11)\fP + T operator+=( T arg ) volatile noexcept; \fB(2)\fP \fI(since C++11)\fP + T operator-=( T arg ) noexcept; \fB(3)\fP \fI(since C++11)\fP + T operator-=( T arg ) volatile noexcept; \fB(4)\fP \fI(since C++11)\fP + member only of atomic partial specialization + T* operator+=( std::ptrdiff_t arg ) noexcept; \fB(5)\fP \fI(since C++11)\fP + T* operator+=( std::ptrdiff_t arg ) volatile noexcept; \fB(6)\fP \fI(since C++11)\fP + T* operator-=( std::ptrdiff_t arg ) noexcept; \fB(7)\fP \fI(since C++11)\fP + T* operator-=( std::ptrdiff_t arg ) volatile noexcept; \fB(8)\fP \fI(since C++11)\fP + + Atomically replaces the current value with the result of computation involving the + previous value and arg. The operation is read-modify-write operation. + + * operator+= performs atomic addition. Equivalent to return fetch_add(arg) + arg;. + * operator-= performs atomic subtraction. Equivalent to return fetch_sub(arg) - + arg;. + 1-4) For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + + For floating-point types, the floating-point environment in effect may + be different from the calling thread's floating-point environment. The + operation need not be conform to the corresponding std::numeric_limits \fI(since C++20)\fP + traits but is encouraged to do so. If the result is not a + representable value for its type, the result is unspecified but the + operation otherwise has no undefined behavior. + + 5-8) The result may be an undefined address, but the operations otherwise have no + undefined behavior. + If T is not a complete object type, the program is ill-formed. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + any volatile overload participates in overload resolution. + +.SH Parameters + + arg - the argument for the arithmetic operation + +.SH Return value + + The resulting value (that is, the result of applying the corresponding binary + operator to the value immediately preceding the effects of the corresponding member + function in the modification order of *this). + +.SH Notes + + Unlike most compound assignment operators, the compound assignment operators for + atomic types do not return a reference to their left-hand arguments. They return a + copy of the stored value instead. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 arithmetic permitted on pointers to (possibly made ill-formed + cv-qualified) void or function + +.SH See also + + atomically adds the argument to the value stored in the atomic + fetch_add object and obtains the value held previously + \fI(public member function)\fP + atomically subtracts the argument from the value stored in the + fetch_sub atomic object and obtains the value held previously + \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the atomic value by one + operator-- \fI(public member function)\fP + operator--(int) + operator&= performs bitwise AND, OR, XOR with the atomic value + operator|= \fI(public member function)\fP + operator^= diff --git a/man/std::atomic::operator=.3 b/man/std::atomic::operator=.3 index 54b0f48d7..da5124d89 100644 --- a/man/std::atomic::operator=.3 +++ b/man/std::atomic::operator=.3 @@ -1,14 +1,20 @@ -.TH std::atomic::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::operator= \- std::atomic::operator= + .SH Synopsis - T operator=( T desired ); - T operator=( T desired ) volatile; \fB(1)\fP \fI(since C++11)\fP - atomic& operator=( const atomic& ) = delete; \fB(1)\fP \fI(since C++11)\fP - atomic& operator=( const atomic& ) volatile = \fB(2)\fP \fI(since C++11)\fP - delete; + T operator=( T desired ) noexcept; \fB(1)\fP \fI(since C++11)\fP + T operator=( T desired ) volatile noexcept; \fB(2)\fP \fI(since C++11)\fP + atomic& operator=( const atomic& ) = delete; \fB(3)\fP \fI(since C++11)\fP + atomic& operator=( const atomic& ) volatile = delete; \fB(4)\fP \fI(since C++11)\fP - 1) Atomically assigns a value t to the atomic variable. Equivalent to + 1,2) Atomically assigns desired to the atomic variable. Equivalent to store(desired). - 2) Atomic variables are not CopyAssignable. + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. + + 3,4) Atomic variables are not CopyAssignable. .SH Parameters @@ -16,13 +22,7 @@ .SH Return value - desired. - -.SH Exceptions - - noexcept specification: - noexcept - + 1,2) desired .SH Notes @@ -33,4 +33,4 @@ .SH See also constructor constructs an atomic object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::atomic::operatorT().3 b/man/std::atomic::operatorT().3 deleted file mode 100644 index fd246fdb8..000000000 --- a/man/std::atomic::operatorT().3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::atomic::operatorT() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - operator T() const; \fI(since C++11)\fP - operator T() const volatile; - - Atomically loads and returns the current value of the atomic variable. Equivalent to - load(). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The current value of the atomic variable. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - load atomically obtains the value of the atomic object - \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::atomic::operatorT.3 b/man/std::atomic::operatorT.3 new file mode 100644 index 000000000..feb956d1c --- /dev/null +++ b/man/std::atomic::operatorT.3 @@ -0,0 +1,26 @@ +.TH std::atomic::operatorT 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::operatorT \- std::atomic::operatorT + +.SH Synopsis + operator T() const noexcept; \fB(1)\fP \fI(since C++11)\fP + operator T() const volatile noexcept; \fB(2)\fP \fI(since C++11)\fP + + Atomically loads and returns the current value of the atomic variable. Equivalent to + load(). + + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current value of the atomic variable. + +.SH See also + + load atomically obtains the value of the atomic object + \fI(public member function)\fP diff --git a/man/std::atomic::store.3 b/man/std::atomic::store.3 index dcdb9237e..6d13d719a 100644 --- a/man/std::atomic::store.3 +++ b/man/std::atomic::store.3 @@ -1,35 +1,37 @@ -.TH std::atomic::store 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic::store 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::store \- std::atomic::store + .SH Synopsis - void store( T desired, memory_order = std::memory_order_seq_cst ); - void store( T desired, memory_order = std::memory_order_seq_cst ) \fI(since C++11)\fP - volatile; + void store( T desired, std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; + void store( T desired, std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(2)\fP \fI(since C++11)\fP + noexcept; Atomically replaces the current value with desired. Memory is affected according to - the value of memory_order. + the value of order. + + If order is one of std::memory_order_consume, std::memory_order_acquire and + std::memory_order_acq_rel, the behavior is undefined. - memory_order must be one of std::memory_order_relaxed, std::memory_order_release or - std::memory_order_seq_cst. Otherwise the behavior is undefined. + It is deprecated if std::atomic::is_always_lock_free is false and \fI(since C++20)\fP + overload \fB(2)\fP participates in overload resolution. .SH Parameters - desired - the value to store into the atomic variable - memory_order - memory order constraints to enforce + desired - the value to store into the atomic variable + order - memory order constraints to enforce .SH Return value \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also operator= stores a value into an atomic object - \fI(public member function)\fP + \fI(public member function)\fP atomic_store atomically replaces the value of the atomic object with a atomic_store_explicit non-atomic argument - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP diff --git a/man/std::atomic::wait.3 b/man/std::atomic::wait.3 new file mode 100644 index 000000000..37da6e10a --- /dev/null +++ b/man/std::atomic::wait.3 @@ -0,0 +1,104 @@ +.TH std::atomic::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic::wait \- std::atomic::wait + +.SH Synopsis + void wait( T old, std::memory_order order = \fB(1)\fP \fI(since C++20)\fP + std::memory_order::seq_cst ) const noexcept; + void wait( T old, std::memory_order order = + std::memory_order::seq_cst ) const volatile \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Performs atomic waiting operations. Behaves as if it repeatedly performs the + following steps: + + * Compare the value representation of this->load(order) with that of old. + * If those are equal, then blocks until *this is notified by notify_one() or + notify_all(), or the thread is unblocked spuriously. + * Otherwise, returns. + + These functions are guaranteed to return only if value has changed, even if + underlying implementation unblocks spuriously. + + If order is one of std::memory_order::release and std::memory_order::acq_rel, the + behavior is undefined. + +.SH Parameters + + old - the value to check the atomic's object no longer contains + order - memory order constraints to enforce + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + + Due to the ABA problem, transient changes from old to another value and back to old + might be missed, and not unblock. + + The comparison is bitwise (similar to std::memcmp); no comparison operator is used. + Padding bits that never participate in an object's value representation are ignored. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::literals; + + int main() + { + std::atomic all_tasks_completed{false}; + std::atomic completion_count{}; + std::future task_futures[16]; + std::atomic outstanding_task_count{16}; + + // Spawn several tasks which take different amounts of + // time, then decrement the outstanding task count. + for (std::future& task_future : task_futures) + task_future = std::async([&] + { + // This sleep represents doing real work... + std::this_thread::sleep_for(50ms); + + ++completion_count; + --outstanding_task_count; + + // When the task count falls to zero, notify + // the waiter (main thread in this case). + if (outstanding_task_count.load() == 0) + { + all_tasks_completed = true; + all_tasks_completed.notify_one(); + } + }); + + all_tasks_completed.wait(false); + + std::cout << "Tasks completed = " << completion_count.load() << '\\n'; + } + +.SH Output: + + Tasks completed = 16 + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function)\fP + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + atomic_notify_all notifies all threads blocked in atomic_wait + (C++20) \fI(function template)\fP diff --git a/man/std::atomic_....3 b/man/std::atomic_....3 new file mode 100644 index 000000000..f4d1e565e --- /dev/null +++ b/man/std::atomic_....3 @@ -0,0 +1,191 @@ +.TH std::atomic_... 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_... \- std::atomic_... + +.SH Synopsis + Defined in header + \fI(since C++11)\fP + template< class T > \fB(1)\fP (deprecated in + bool atomic_is_lock_free( const std::shared_ptr* p ); C++20) + (removed in C++26) + template< class T > \fI(since C++11)\fP + std::shared_ptr atomic_load( const std::shared_ptr* p \fB(2)\fP (deprecated in + ); C++20) + (removed in C++26) + template< class T > \fI(since C++11)\fP + (deprecated in + std::shared_ptr atomic_load_explicit \fB(3)\fP C++20) + (removed in C++26) + ( const std::shared_ptr* p, std::memory_order mo ); + template< class T > \fI(since C++11)\fP + void atomic_store( std::shared_ptr* p, \fB(4)\fP (deprecated in + std::shared_ptr r ); C++20) + (removed in C++26) + template< class T > + \fI(since C++11)\fP + void atomic_store_explicit \fB(5)\fP (deprecated in + ( std::shared_ptr* p, std::shared_ptr r, C++20) + (removed in C++26) + std::memory_order mo ); + template< class T > \fI(since C++11)\fP + (deprecated in + std::shared_ptr atomic_exchange \fB(6)\fP C++20) + (removed in C++26) + ( std::shared_ptr* p, std::shared_ptr r ); + template< class T > + \fI(since C++11)\fP + std::shared_ptr atomic_exchange_explicit \fB(7)\fP (deprecated in + ( std::shared_ptr* p, std::shared_ptr r, C++20) + (removed in C++26) + std::memory_order mo ); + template< class T > + \fI(since C++11)\fP + bool atomic_compare_exchange_weak \fB(8)\fP (deprecated in + ( std::shared_ptr* p, std::shared_ptr* expected, C++20) + (removed in C++26) + std::shared_ptr desired ); + template< class T > + \fI(since C++11)\fP + bool atomic_compare_exchange_strong \fB(9)\fP (deprecated in + ( std::shared_ptr* p, std::shared_ptr* expected, C++20) + (removed in C++26) + std::shared_ptr desired ); + template< class T > + + bool atomic_compare_exchange_strong_explicit \fI(since C++11)\fP + ( std::shared_ptr* p, std::shared_ptr* expected, \fB(10)\fP (deprecated in + std::shared_ptr desired, C++20) + (removed in C++26) + std::memory_order success, std::memory_order failure + ); + template< class T > + + bool atomic_compare_exchange_weak_explicit \fI(since C++11)\fP + ( std::shared_ptr* p, std::shared_ptr* expected, \fB(11)\fP (deprecated in + std::shared_ptr desired, C++20) + (removed in C++26) + std::memory_order success, std::memory_order failure + ); + + If multiple threads of execution access the same std::shared_ptr object without + synchronization and any of those accesses uses a non-const member function of + shared_ptr then a data race will occur unless all such access is performed through + these functions, which are overloads of the corresponding atomic access functions + (std::atomic_load, std::atomic_store, etc.). + + Note that the control block of a shared_ptr is thread-safe: different + std::shared_ptr objects can be accessed using mutable operations, such as operator= + or reset, simultaneously by multiple threads, even when these instances are copies, + and share the same control block internally. + + 1) Determines whether atomic access to the shared pointer pointed-to by p is + lock-free. + 2) Equivalent to atomic_load_explicit(p, std::memory_order_seq_cst). + 3) Returns the shared pointer pointed-to by p. + As with the non-specialized std::atomic_load_explicit, if mo is + std::memory_order_release or std::memory_order_acq_rel, the behavior is undefined. + 4) Equivalent to atomic_store_explicit(p, r, std::memory_order_seq_cst). + 5) Stores the shared pointer r in the shared pointer pointed-to by p atomically, + equivalent to p->swap(r). + As with the non-specialized std::atomic_store_explicit, if mo is + std::memory_order_release or std::memory_order_acq_rel, the behavior is undefined. + 6) Equivalent to atomic_exchange_explicit(p, r, std::memory_order_seq_cst). + 7) Stores the shared pointer r in the shared pointer pointed to by p and returns the + value formerly pointed-to by p, atomically. Equivalent to p->swap(r) and returns a + copy of r after the swap. + 8) Equivalent to + atomic_compare_exchange_weak_explicit + (p, expected, desired, std::memory_order_seq_cst, + std::memory_order_seq_cst). + 9) Equivalent to + atomic_compare_exchange_strong_explicit + (p, expected, desired, std::memory_order_seq_cst, + std::memory_order_seq_cst). + 10,11) Compares the shared pointers pointed-to by p and expected. + * If they are equivalent (store the same pointer value, and either share ownership + of the same object or are both empty), assigns desired into *p using the memory + ordering constraints specified by success and returns true. + * If they are not equivalent, assigns *p into *expected using the memory ordering + constraints specified by failure and returns false. + atomic_compare_exchange_weak_explicit may fail spuriously. + If expected is a null pointer, or failure is std::memory_order_release or + std::memory_order_acq_rel, the behavior is undefined. + + If p is a null pointer, the behaviors of these functions are all undefined. + +.SH Parameters + + p, expected - a pointer to a std::shared_ptr + r, desired - a std::shared_ptr + mo, success, failure - memory ordering selectors of type std::memory_order + +.SH Exceptions + + These functions do not throw exceptions. + +.SH Return value + + 1) true if atomic access is implemented using lock-free instructions. + 2,3) A copy of the pointed-to shared pointer. + 4,5) \fI(none)\fP + 6,7) A copy of the formerly pointed-to shared pointer. + 8-11) true if the shared pointers were equivalent and the exchange was performed, + false otherwise. + +.SH Notes + + These functions are typically implemented using mutexes, stored in a global hash + table where the pointer value is used as the key. + + The Concurrency TS offers atomic smart pointer classes atomic_shared_ptr and + atomic_weak_ptr as a replacement for the use of these functions. + + These functions were deprecated in favor of the specializations of the \fI(since C++20)\fP + std::atomic template: std::atomic and (until C++26) + std::atomic. + These functions were removed in favor of the specializations of the + std::atomic template: std::atomic and (since C++26) + std::atomic. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2980 C++11 empty shared_ptrs are never equivalent if they store the same + equivalent pointer value + +.SH See also + + atomic_is_lock_free checks if the atomic type's operations are + \fI(C++11)\fP lock-free + \fI(function template)\fP + atomic_store atomically replaces the value of the atomic + atomic_store_explicit object with a non-atomic argument + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP + atomic_load atomically obtains the value stored in an + atomic_load_explicit atomic object + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP + atomic_exchange atomically replaces the value of the atomic + atomic_exchange_explicit object with non-atomic argument and returns + \fI(C++11)\fP the old value of the atomic + \fI(C++11)\fP \fI(function template)\fP + atomic_compare_exchange_weak + atomic_compare_exchange_weak_explicit atomically compares the value of the atomic + atomic_compare_exchange_strong object with non-atomic argument and performs + atomic_compare_exchange_strong_explicit atomic exchange if equal or atomic load if + \fI(C++11)\fP not + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_....3 b/man/std::atomic_....3 deleted file mode 100644 index 0be3b2bed..000000000 --- a/man/std::atomic_....3 +++ /dev/null @@ -1,165 +0,0 @@ -.TH std::atomic_... 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class T > \fB(1)\fP \fI(since C++11)\fP - bool atomic_is_lock_free( const std::shared_ptr* p ); - template< class T > \fB(2)\fP \fI(since C++11)\fP - std::shared_ptr atomic_load( const std::shared_ptr* p ); - template< class T > - - std::shared_ptr atomic_load_explicit( const shared_ptr* p, \fB(3)\fP \fI(since C++11)\fP - - std::memory_order mo ); - template< class T > - - void atomic_store( std::shared_ptr* p, \fB(4)\fP \fI(since C++11)\fP - - std::shared_ptr r ); - template< class T > - - void atomic_store_explicit( std::shared_ptr* p, \fB(5)\fP \fI(since C++11)\fP - shared_ptr r, - - std::memory_order mo); - template< class T > - - std::shared_ptr atomic_exchange( std::shared_ptr* p, \fB(6)\fP \fI(since C++11)\fP - - std::shared_ptr r); - template - - std::shared_ptr atomic_exchange_explicit( std::shared_ptr* - p, - std::shared_ptr \fB(7)\fP \fI(since C++11)\fP - r, - - std::memory_order - mo); - template< class T > - - bool atomic_compare_exchange_weak( std::shared_ptr* p, \fB(8)\fP \fI(since C++11)\fP - std::shared_ptr* expected, - - std::shared_ptr desired); - template - - bool atomic_compare_exchange_strong( std::shared_ptr* p, - std::shared_ptr* \fB(9)\fP \fI(since C++11)\fP - expected, - - std::shared_ptr desired); - template< class T > - - bool atomic_compare_exchange_strong_explicit( std::shared_ptr* - p, - std::shared_ptr* - expected, - std::shared_ptr \fB(10)\fP \fI(since C++11)\fP - desired, - std::memory_order - success, - - std::memory_order - failure); - template< class T > - - bool atomic_compare_exchange_weak_explicit( std::shared_ptr* - p, - std::shared_ptr* - expected, - std::shared_ptr \fB(11)\fP \fI(since C++11)\fP - desired, - std::memory_order - success, - - std::memory_order - failure); - - If multiple threads of execution access the object referenced by the same - std::shared_ptr without synchronization, a data race may occur, unless all such - access is performed through these functions, which are overloads of the - corresponding atomic access functions (std::atomic_load, std::atomic_store, etc) - - Note that the control block of a shared_ptr is thread-safe: different - std::shared_ptr objects can be accessed using mutable operations, such as operator= - or reset, simultaneously by multiple threads, even when these instances are copies, - and share the same control block internally. - - 1) Determines whether atomic access to the shared pointer pointed-to by p is - lock-free. - 2) Equivalent to atomic_load_explicit(p, std::memory_order_seq_cst) - 3) Returns the shared pointer pointed-to by p. As with the non-specialized - std::atomic_load_explicit, mo cannot be std::memory_order_release or - std::memory_order_acq_rel - 4) Equivalent to atomic_store_explicit(p, r, memory_order_seq_cst) - 5) Swaps the shared pointers p and r, effectively executing p->swap(r). As with the - non-specialized std::atomic_store_explicit, mo cannot be std::memory_order_acquire - or std::memory_order_acq_rel - 6) Equivalent to atomic_exchange_explicit(p, r, memory_order_seq_cst) - 7) Swaps the shared pointers p and r, effectively executing p->swap(r) and returns a - copy of the shared pointer formerly pointed-to by p - 8) Equivalent to atomic_compare_exchange_weak_explicit(p, expected, desired, - std::memory_order_seq_cst, std::memory_order_seq_cst) - 9) Equivalent to atomic_compare_exchange_strong_explicit(p, expected, desired, - std::memory_order_seq_cst, std::memory_order_seq_cst) - 10) Compares the shared pointers pointed-to by p and expected. If they are - equivalent (share ownership of the same pointer and refer to the same pointer), - assigns desired into *p using the memory ordering constraints specified by success - and returns true. If they are not equivalent, assigns *p into *expected using the - memory ordering constraints specified by failure and returns false. - 11) Same as 10), but may fail spuriously. - - All these functions invoke undefined behavior if p is a null pointer. - -.SH Parameters - - p, expected - a pointer to a std::shared_ptr - r, desired - a std::shared_ptr - mo, success, failure - memory ordering selectors of type std::memory_order - -.SH Exceptions - - These functions do not throw exceptions. - -.SH Return value - - 1) true if atomic access is implemented using lock-free instructions - 2,3) A copy of the pointed-to shared pointer. - 4,5) \fI(none)\fP - 6,7) A copy of the formerly pointed-to shared pointer - 8,9,10,11) true if the shared pointers were equivalent and the exchange was - performed, false otherwise. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - atomic_is_lock_free checks if the atomic type's operations are - \fI(C++11)\fP lock-free - \fI(function template)\fP - atomic_store atomically replaces the value of the atomic - atomic_store_explicit object with a non-atomic argument - \fI(C++11)\fP \fI(function template)\fP - \fI(C++11)\fP - atomic_load atomically obtains the value stored in an - atomic_load_explicit atomic object - \fI(C++11)\fP \fI(function template)\fP - \fI(C++11)\fP - atomic_exchange atomically replaces the value of the atomic - atomic_exchange_explicit object with non-atomic argument and returns - \fI(C++11)\fP the old value of the atomic - \fI(C++11)\fP \fI(function template)\fP - atomic_compare_exchange_weak - atomic_compare_exchange_weak_explicit atomically compares the value of the atomic - atomic_compare_exchange_strong object with non-atomic argument and performs - atomic_compare_exchange_strong_explicit atomic exchange if equal or atomic load if - \fI(C++11)\fP not - \fI(C++11)\fP \fI(function template)\fP - \fI(C++11)\fP - \fI(C++11)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong,.3 b/man/std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong,.3 index b6baea5ab..e9525dc3d 100644 --- a/man/std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong,.3 +++ b/man/std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong,.3 @@ -1,136 +1,147 @@ -.TH std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong, \- std::atomic_compare_exchange_weak,std::atomic_compare_exchange_strong, + .SH Synopsis Defined in header template< class T > - bool atomic_compare_exchange_weak( - std::atomic* obj, + bool atomic_compare_exchange_weak + ( std::atomic* obj, typename std::atomic::value_type* \fB(1)\fP \fI(since C++11)\fP + expected, - T* - expected, T desired ); + typename std::atomic::value_type desired ) noexcept; template< class T > - bool atomic_compare_exchange_weak( - volatile std::atomic* obj, + bool atomic_compare_exchange_weak + ( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + typename std::atomic::value_type* expected, - T* - expected, T desired ); + typename std::atomic::value_type desired ) noexcept; template< class T > - bool atomic_compare_exchange_strong( - std::atomic* obj, + bool atomic_compare_exchange_strong + ( std::atomic* obj, typename std::atomic::value_type* \fB(3)\fP \fI(since C++11)\fP + expected, - T* - expected, T desired ); + typename std::atomic::value_type desired ) noexcept; template< class T > - bool atomic_compare_exchange_strong( - volatile std::atomic* obj, + bool atomic_compare_exchange_strong + ( volatile std::atomic* obj, \fB(4)\fP \fI(since C++11)\fP + typename std::atomic::value_type* expected, - T* - expected, T desired ); + typename std::atomic::value_type desired ) noexcept; template< class T > - bool - atomic_compare_exchange_weak_explicit( - std::atomic* obj, - - T* expected, T desired, - - std::memory_order succ, - \fB(1)\fP (since - C++11) - std::memory_order fail ); + bool atomic_compare_exchange_weak_explicit + ( std::atomic* obj, typename std::atomic::value_type* + expected, \fB(5)\fP \fI(since C++11)\fP + typename std::atomic::value_type desired, + + std::memory_order success, std::memory_order failure ) + noexcept; template< class T > - bool - atomic_compare_exchange_weak_explicit( - volatile std::atomic* obj, \fB(2)\fP (since - C++11) - T* expected, T desired, - - std::memory_order succ, - - - std::memory_order fail ); \fB(3)\fP (since - template< class T > C++11) - - bool - atomic_compare_exchange_strong_explicit( - std::atomic* obj, - - T* expected, T desired, - - std::memory_order succ, - - - std::memory_order fail ); \fB(4)\fP (since - template< class T > C++11) - - bool - atomic_compare_exchange_strong_explicit( - volatile std::atomic* obj, - - T* expected, T desired, - - std::memory_order succ, - - - std::memory_order fail ); - - Atomically compares the value pointed to by obj with the value pointed to by - expected, and if those are equal, replaces the former with desired (performs + bool atomic_compare_exchange_weak_explicit + ( volatile std::atomic* obj, + typename std::atomic::value_type* expected, \fB(6)\fP \fI(since C++11)\fP + typename std::atomic::value_type desired, + + std::memory_order success, std::memory_order failure ) + noexcept; + template< class T > + + bool atomic_compare_exchange_strong_explicit + ( std::atomic* obj, typename std::atomic::value_type* + expected, \fB(7)\fP \fI(since C++11)\fP + typename std::atomic::value_type desired, + + std::memory_order success, std::memory_order failure ) + noexcept; + template< class T > + + bool atomic_compare_exchange_strong_explicit + ( volatile std::atomic* obj, + typename std::atomic::value_type* expected, \fB(8)\fP \fI(since C++11)\fP + typename std::atomic::value_type desired, + + std::memory_order success, std::memory_order failure ) + noexcept; + + Atomically compares the + object representation + \fI(until C++20)\fP + value representation + \fI(since C++20)\fP of the object pointed to by obj with that of the object pointed to by + expected, and if those are bitwise-equal, replaces the former with desired (performs read-modify-write operation). Otherwise, loads the actual value pointed to by obj into *expected (performs load operation). - The memory models for the read-modify-write and load operations are succ and fail - respectively. The (1-2) versions use std::memory_order_seq_cst by default. - - The weak forms (\fB(1)\fP and \fB(3)\fP) of the functions are allowed to fail spuriously, that - is, act as if *obj != *expected even if they are equal. When a compare-and-exchange - is in a loop, the weak version will yield better performance on some platforms. When - a weak compare-and-exchange would require a loop and a strong one would not, the - strong one is preferable. + Overloads Memory model for + read‑modify‑write operation load operation + (1-4) std::memory_order_seq_cst std::memory_order_seq_cst + (5-8) success failure These functions are defined in terms of member functions of std::atomic: - 1) obj->compare_exchange_weak(*expected, desired) - 2) obj->compare_exchange_strong(*expected, desired) - 3) obj->compare_exchange_weak(*expected, desired, succ, fail) - 4) obj->compare_exchange_strong(*expected, desired, succ, fail) + 1,2) obj->compare_exchange_weak(*expected, desired) + 3,4) obj->compare_exchange_strong(*expected, desired) + 5,6) obj->compare_exchange_weak(*expected, desired, success, failure) + 7,8) obj->compare_exchange_strong(*expected, desired, success, failure) + + If failure + is stronger than success or + \fI(until C++17)\fP is one of std::memory_order_release and std::memory_order_acq_rel, the + behavior is undefined. .SH Parameters obj - pointer to the atomic object to test and modify expected - pointer to the value expected to be found in the atomic object desired - the value to store in the atomic object if it is as expected - succ - the memory synchronization ordering for the read-modify-write operation - if the comparison succeeds. All values are permitted. - the memory synchronization ordering for the load operation if the - fail - comparison fails. Cannot be std::memory_order_release or - std::memory_order_acq_rel and cannot specify stronger ordering than succ + success - the memory synchronization ordering for the read-modify-write operation + if the comparison succeeds + failure - the memory synchronization ordering for the load operation if the + comparison fails .SH Return value - The result of the comparison: true if *obj was equal to *exp, false otherwise. + The result of the comparison: true if *obj was equal to *expected, false otherwise. + +.SH Notes -.SH Exceptions + std::atomic_compare_exchange_weak and std::atomic_compare_exchange_weak_explicit + (the weak versions) are allowed to fail spuriously, that is, act as if *obj != + *expected even if they are equal. When a compare-and-exchange is in a loop, they + will yield better performance on some platforms. - noexcept specification: - noexcept - + When a weak compare-and-exchange would require a loop and a strong one would not, + the strong one is preferable unless the object representation of T may include + padding bits, + \fI(until C++20)\fP trap bits, or offers multiple object representations for the same + value (e.g. floating-point NaN). In those cases, weak compare-and-exchange typically + works because it quickly converges on some stable object representation. + + For a union with bits that participate in the value representations of some members + but not the others, compare-and-exchange might always fail because such padding bits + have indeterminate values when they do not participate in the value representation + of the active member. + + Padding bits that never participate in an object's value \fI(since C++20)\fP + representation are ignored. .SH Example - compare and exchange operations are often used as basic building blocks of lockfree - data structures + Compare and exchange operations are often used as basic building blocks of lockfree + data structures. + - // Run this code #include - + template struct node { @@ -138,34 +149,33 @@ node* next; node(const T& data) : data(data), next(nullptr) {} }; - + template class stack { std::atomic*> head; - public: + public: void push(const T& data) { node* new_node = new node(data); - + // put the current value of head into new_node->next - node* old_head = (new_node->next = head.load(std::memory_order_relaxed)); - + new_node->next = head.load(std::memory_order_relaxed); + // now make new_node the new head, but if the head // is no longer what's stored in new_node->next // (some other thread must have inserted a node just now) // then put that new head into new_node->next and try again - while(!std::atomic_compare_exchange_weak_explicit( &head - , &old_head - , new_node - , std::memory_order_release - , std::memory_order_relaxed)) - { - new_node->next = old_head; - } + while (!std::atomic_compare_exchange_weak_explicit( + &head, &new_node->next, new_node, + std::memory_order_release, std::memory_order_relaxed)) + ; // the body of the loop is empty + // note: the above loop is not thread-safe in at least + // GCC prior to 4.8.3 (bug 60272), clang prior to 2014-05-05 (bug 18899) + // MSVC prior to 2014-03-17 (bug 819819). See member function version for workaround } }; - + int main() { stack s; @@ -174,23 +184,30 @@ s.push(3); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj + .SH See also - atomically compares the value - of the atomic object with - compare_exchange_weak non-atomic argument and - compare_exchange_strong performs atomic exchange if - equal or atomic load if not - \fI\fI(public member\fP function of\fP - std::atomic) - atomic_exchange atomically replaces the value - atomic_exchange_explicit of the atomic object with - \fI(C++11)\fP non-atomic argument and returns - \fI(C++11)\fP the old value of the atomic - \fI(function template)\fP + atomically compares the value of the atomic object with + compare_exchange_weak non-atomic argument and performs atomic exchange if equal + compare_exchange_strong or atomic load if not + \fI(public member function of std::atomic)\fP + atomic_exchange atomically replaces the value of the atomic object with + atomic_exchange_explicit non-atomic argument and returns the old value of the atomic + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP + std::atomic_compare_exchange_weak(std::shared_ptr) specializes atomic operations std::atomic_compare_exchange_strong(std::shared_ptr) for std::shared_ptr - \fI(function template)\fP + (deprecated in C++20) \fI(function template)\fP + (removed in C++26) C documentation for atomic_compare_exchange, atomic_compare_exchange_explicit diff --git a/man/std::atomic_exchange,std::atomic_exchange_explicit.3 b/man/std::atomic_exchange,std::atomic_exchange_explicit.3 index 905740bba..6512fc2d2 100644 --- a/man/std::atomic_exchange,std::atomic_exchange_explicit.3 +++ b/man/std::atomic_exchange,std::atomic_exchange_explicit.3 @@ -1,110 +1,130 @@ -.TH std::atomic_exchange,std::atomic_exchange_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_exchange,std::atomic_exchange_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_exchange,std::atomic_exchange_explicit \- std::atomic_exchange,std::atomic_exchange_explicit + .SH Synopsis Defined in header template< class T > - T atomic_exchange( std::atomic* obj, T desr - ); + + T atomic_exchange( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::value_type desired ) + noexcept; template< class T > - T atomic_exchange( volatile std::atomic* - obj, T desr ); + + T atomic_exchange( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + + typename std::atomic::value_type desired ) + noexcept; template< class T > - T atomic_exchange_explicit( std::atomic* - obj, T desr, \fB(1)\fP \fI(since C++11)\fP + T atomic_exchange_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP \fI(since C++11)\fP + desired, - std::memory_order - order ); \fB(2)\fP \fI(since C++11)\fP + std::memory_order order ) noexcept; template< class T > - T atomic_exchange_explicit( volatile - std::atomic* obj, T desr, + T atomic_exchange_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP \fI(since C++11)\fP + desired, - std::memory_order - order ); + std::memory_order order ) noexcept; - 1) Atomically replaces the value pointed to by obj with the value of desr and - returns the value obj held previously, as if by obj->exchange(desr) - 2) Atomically replaces the value pointed to by obj with the value of desr and - returns the value obj held previously, as if by obj->exchange(desr, order) + 1,2) Atomically replaces the value pointed to by obj with the value of desired and + returns the value obj held previously, as if by obj->exchange(desired). + 3,4) Atomically replaces the value pointed to by obj with the value of desired and + returns the value obj held previously, as if by obj->exchange(desired, order). .SH Parameters - obj - pointer to the atomic object to modify - desr - the value to store in the atomic object - order - the memory synchronization ordering for this operation: all values are - permitted. + obj - pointer to the atomic object to modify + desired - the value to store in the atomic object + order - the memory synchronization ordering .SH Return value - The value held previously by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - + The value held previously by the atomic object pointed to by obj. .SH Example A spinlock mutex can be implemented in userspace using an atomic exchange operation, similar to std::atomic_flag_test_and_set: - + // Run this code + #include + #include #include #include - #include - #include - + std::atomic lock(false); // holds true when locked // holds false when unlocked - + + int new_line{1}; // the access is synchronized via atomic lock variable + void f(int n) { - for (int cnt = 0; cnt < 100; ++cnt) { - while(std::atomic_exchange_explicit(&lock, true, std::memory_order_acquire)) - ; // spin until acquired - std::cout << "Output from thread " << n << '\\n'; + for (int cnt = 0; cnt < 100; ++cnt) + { + while (std::atomic_exchange_explicit(&lock, true, std::memory_order_acquire)) + ; // spin until acquired + std::cout << n << (new_line++ % 80 ? "" : "\\n"); std::atomic_store_explicit(&lock, false, std::memory_order_release); } } + int main() { std::vector v; - for (int n = 0; n < 10; ++n) { + for (int n = 0; n < 8; ++n) v.emplace_back(f, n); - } - for (auto& t : v) { + for (auto& t : v) t.join(); - } } -.SH Output: +.SH Possible output: - Output from thread 2 - Output from thread 6 - Output from thread 7 - ...... + 02222222222222222222222002222222222222222222222222222222222222222222222222222222 + 22222222200022222222202222211111111111110000011111111100000000000000110001111111 + 00011111000001111110000011111100000111000000001111111111111110000010000001001111 + 11011111111011111011000000000000111100000000000001111000011133333333333333333333 + 33333333333333333333333333333333333333333333333333333333333333333333333333333333 + 44444444444444444444444444444444444444444444444444444444444444444444444444444444 + 44444444444444444444555555555555555555555555555555555555555555555555555555555555 + 55555555555555555555555555555555555555556666666666666666666666666666666666666666 + 66666666666666666666666666666666666666666666666666666666666677777777777777777777 + 77777777777777777777777777777777777777777777777777777777777777777777777777777777 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj .SH See also - atomically replaces the value of the - exchange atomic object and obtains the value - \fI(C++11)\fP held previously - \fI\fI(public member\fP function of\fP - std::atomic) + atomically replaces the value of the atomic + exchange object and obtains the value held previously + \fI(public member function of std::atomic)\fP + atomic_compare_exchange_weak - atomic_compare_exchange_weak_explicit atomically compares the value of the - atomic_compare_exchange_strong atomic object with non-atomic - atomic_compare_exchange_strong_explicit argument and performs atomic exchange - \fI(C++11)\fP if equal or atomic load if not - \fI(C++11)\fP \fI(function template)\fP + atomic_compare_exchange_weak_explicit atomically compares the value of the atomic + atomic_compare_exchange_strong object with non-atomic argument and performs + atomic_compare_exchange_strong_explicit atomic exchange if equal or atomic load if + \fI(C++11)\fP not + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP \fI(C++11)\fP + std::atomic_exchange(std::shared_ptr) specializes atomic operations for std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr - \fI(function template)\fP + (deprecated in C++20) \fI(function template)\fP + (removed in C++26) C documentation for atomic_exchange, atomic_exchange_explicit diff --git a/man/std::atomic_fetch_add,std::atomic_fetch_add_explicit.3 b/man/std::atomic_fetch_add,std::atomic_fetch_add_explicit.3 index 5425c56ee..e6d27d80a 100644 --- a/man/std::atomic_fetch_add,std::atomic_fetch_add_explicit.3 +++ b/man/std::atomic_fetch_add,std::atomic_fetch_add_explicit.3 @@ -1,195 +1,167 @@ -.TH std::atomic_fetch_add,std::atomic_fetch_add_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_fetch_add,std::atomic_fetch_add_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_add,std::atomic_fetch_add_explicit \- std::atomic_fetch_add,std::atomic_fetch_add_explicit + .SH Synopsis Defined in header - template< class Integral > - Integral atomic_fetch_add( - std::atomic* obj, - Integral arg ); - template< class Integral > - Integral atomic_fetch_add( - volatile std::atomic* - obj, Integral arg ); - template< class Integral > - - Integral - atomic_fetch_add_explicit( - std::atomic* obj, - Integral arg, - - - std::memory_order order ); - template< class Integral > - - Integral - atomic_fetch_add_explicit( - volatile std::atomic* - obj, Integral arg, - - \fB(1)\fP (since - std::memory_order order ); C++11) template< class T > - T* atomic_fetch_add( - std::atomic* obj, \fB(2)\fP (since - std::ptrdiff_t arg ); C++11) + + T atomic_fetch_add( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::difference_type arg ) + noexcept; template< class T > - T* atomic_fetch_add( volatile - std::atomic* obj, - std::ptrdiff_t arg ); + + T atomic_fetch_add( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + + typename std::atomic::difference_type arg ) + noexcept; template< class T > - T* atomic_fetch_add_explicit( - std::atomic* obj, \fB(3)\fP (since - std::ptrdiff_t arg, C++11) + T atomic_fetch_add_explicit( std::atomic* obj, + typename \fB(3)\fP \fI(since C++11)\fP + std::atomic::difference_type arg, - - std::memory_order order ); \fB(4)\fP (since - template< class T > C++11) + std::memory_order order ) noexcept; + template< class T > + + T atomic_fetch_add_explicit( volatile std::atomic* obj, + typename \fB(4)\fP \fI(since C++11)\fP + std::atomic::difference_type arg, - T* atomic_fetch_add_explicit( - volatile std::atomic* obj, - std::ptrdiff_t arg, + std::memory_order order ) noexcept; - - std::memory_order order ); + Performs atomic addition. Atomically adds arg to the value pointed to by obj and + returns the value obj held previously. The operation is performed as if the + following was executed: - Performs atomic addition. + 1,2) obj->fetch_add(arg) + 3,4) obj->fetch_add(arg, order) - 1-2) Atomically adds arg to the value pointed to by obj and returns the value obj - held previously. The operation is performed as if the following was executed: - 1) obj->fetch_add(arg) - 2) obj->fetch_add(arg, order) - 3-4) Atomically increments the pointer value, pointed to by obj, by arg, and returns - the value obj held previously. The operation is performed as if the following was - executed: - 3) obj->fetch_add(arg) - 4) obj->fetch_add(arg, order) + If std::atomic has no fetch_add member (this member is only provided for integral + , floating-point + \fI(since C++20)\fP and pointer types except bool), the program is ill-formed. .SH Parameters obj - pointer to the atomic object to modify arg - the value to add to the value stored in the atomic object - order - the memory sycnhronization ordering for this operation: all values are - permitted. + order - the memory synchronization ordering .SH Return value - The value held previously by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Possible implementation - -.SH First version -template< class T > -typename std::enable_if::value && !std::is_same::value, T>::type -atomic_fetch_add( std::atomic* obj, T arg ); -{ - return obj->fetch_add(arg); -} -.SH Second version -template< class T > -T* atomic_fetch_add( std::atomic* obj, std::ptrdiff_t arg) -{ - return obj->fetch_add(arg); -} + The value immediately preceding the effects of this function in the modification + order of *obj. .SH Example - Single-writer/multiple-reader lock can be made with fetch_add. Note that this - simplistic implementation is not lockout-free + Single-writer/multiple-reader lock can be made with std::atomic_fetch_add. Note that + this simplistic implementation is not lockout-free. + - // Run this code + #include + #include + #include #include #include #include - #include - #include - #include - + + using namespace std::chrono_literals; + // meaning of cnt: - // 10: there are no active readers or writers. - // 1...9: there are 9...1 readers active, The writer is blocked - // 0: temporary value between fetch_sub and fetch_add in reader lock - // -1: there is a writer active. The readers are blocked. - const int N = 10; // nine concurrent readers are allowed - std::atomic cnt = ATOMIC_VAR_INIT(N); - + // 5: readers and writer are in race. There are no active readers or writers. + // 4...0: there are 1...5 active readers, The writer is blocked. + // -1: writer won the race and readers are blocked. + + const int N = 5; // four concurrent readers are allowed + std::atomic cnt(N); + std::vector data; - + void reader(int id) { - for(;;) + for (;;) { // lock - while(std::atomic_fetch_sub(&cnt, 1) <= 0) + while (std::atomic_fetch_sub(&cnt, 1) <= 0) std::atomic_fetch_add(&cnt, 1); + // read - if(!data.empty()) - std::cout << ( "reader " + std::to_string(id) - + " sees " + std::to_string(*data.rbegin()) + '\\n'); - if(data.size() == 100) + if (!data.empty()) + std::cout << ("reader " + std::to_string(id) + + " sees " + std::to_string(*data.rbegin()) + '\\n'); + if (data.size() == 25) break; + // unlock std::atomic_fetch_add(&cnt, 1); + // pause - std::this_thread::sleep_for(std::chrono::milliseconds(1)); + std::this_thread::sleep_for(1ms); } } - + void writer() { - for(int n = 0; n < 100; ++n) + for (int n = 0; n < 25; ++n) { // lock - while(std::atomic_fetch_sub(&cnt, N+1) != N) - std::atomic_fetch_add(&cnt, N+1); + while (std::atomic_fetch_sub(&cnt, N + 1) != N) + std::atomic_fetch_add(&cnt, N + 1); + // write data.push_back(n); std::cout << "writer pushed back " << n << '\\n'; + // unlock - std::atomic_fetch_add(&cnt, N+1); + std::atomic_fetch_add(&cnt, N + 1); + // pause - std::this_thread::sleep_for(std::chrono::milliseconds(1)); + std::this_thread::sleep_for(1ms); } } - + int main() { std::vector v; - for (int n = 0; n < N; ++n) { + for (int n = 0; n < N; ++n) v.emplace_back(reader, n); - } v.emplace_back(writer); - for (auto& t : v) { + + for (auto& t : v) t.join(); - } } .SH Output: writer pushed back 0 - reader 8 sees 0 + reader 2 sees 0 reader 3 sees 0 reader 1 sees 0 <...> - reader 2 sees 99 - reader 6 sees 99 - reader 1 sees 99 + reader 2 sees 24 + reader 4 sees 24 + reader 1 sees 24 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj .SH See also - fetch_add atomically adds the argument to the value stored in the - \fI(C++11)\fP atomic object and obtains the value held previously - \fI(public member function of std::atomic)\fP + atomically adds the argument to the value stored in the + fetch_add atomic object and obtains the value held previously + \fI(public member function of std::atomic)\fP atomic_fetch_sub subtracts a non-atomic value from an atomic object and atomic_fetch_sub_explicit obtains the previous value of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP C documentation for atomic_fetch_add, diff --git a/man/std::atomic_fetch_and,std::atomic_fetch_and_explicit.3 b/man/std::atomic_fetch_and,std::atomic_fetch_and_explicit.3 index ed7795bf1..335d5e997 100644 --- a/man/std::atomic_fetch_and,std::atomic_fetch_and_explicit.3 +++ b/man/std::atomic_fetch_and,std::atomic_fetch_and_explicit.3 @@ -1,84 +1,77 @@ -.TH std::atomic_fetch_and,std::atomic_fetch_and_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_fetch_and,std::atomic_fetch_and_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_and,std::atomic_fetch_and_explicit \- std::atomic_fetch_and,std::atomic_fetch_and_explicit + .SH Synopsis Defined in header - template< class Integral > - Integral atomic_fetch_and( - std::atomic* obj, Integral arg ); - template< class Integral > - Integral atomic_fetch_and( volatile - std::atomic* obj, Integral arg ); - template< class Integral > - - Integral atomic_fetch_and_explicit( - std::atomic* obj, - Integral - arg, \fB(1)\fP \fI(since C++11)\fP - - - std::memory_order order); \fB(2)\fP \fI(since C++11)\fP - template< class Integral > - - Integral atomic_fetch_and_explicit( volatile - std::atomic* obj, - Integral + template< class T > + + T atomic_fetch_and( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_and( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_and_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP \fI(since C++11)\fP + arg, + + std::memory_order order ) noexcept; + template< class T > + + T atomic_fetch_and_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP \fI(since C++11)\fP arg, - - std::memory_order order); + std::memory_order order ) noexcept; - Atomically replaces the value pointed by arg with the result of bitwise AND between + Atomically replaces the value pointed by obj with the result of bitwise AND between the old value of obj and arg. Returns the value obj held previously. The operation is performed as if the following is executed: - 1) obj->fetch_and(arg) - 2) obj->fetch_and(arg, order) + 1,2) obj->fetch_and(arg) + 3,4) obj->fetch_and(arg, order) + + If std::atomic has no fetch_and member (this member is only provided for integral + types except bool), the program is ill-formed. .SH Parameters - obj - pointer to the atomic object to modify. bool is not an Integral type for the - purposes of the atomic operations. + obj - pointer to the atomic object to modify arg - the value to bitwise AND to the value stored in the atomic object - order - the memory synchronization ordering for this operation: all values are - permitted. + order - the memory synchronization ordering .SH Return value - The value held previously by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - + The value immediately preceding the effects of this function in the modification + order of *obj. -.SH Possible implementation +.SH Example -template< class T > -typename std::enable_if::value && !std::is_same::value, T>::type - atomic_fetch_and(std::atomic* obj, T arg); -{ - return obj->fetch_and(arg); -} -.SH Example - - // Run this code - #include #include - #include #include #include - - // Binary semaphore for demonstrative purposes only + #include + #include + + // Binary semaphore for demonstrative purposes only. // This is a simple yet meaningful example: atomic operations // are unnecessary without threads. - class Semaphore { + class Semaphore + { std::atomic_char m_signaled; - public: + public: Semaphore(bool initial = false) { m_signaled = initial; @@ -86,50 +79,55 @@ typename std::enable_if::value && !std::is_same::va // Block until semaphore is signaled void take() { - while (!std::atomic_fetch_and(&m_signaled, false)) { + while (!std::atomic_fetch_and(&m_signaled, false)) + { std::this_thread::sleep_for(std::chrono::milliseconds(10)); } } - + void put() { std::atomic_fetch_or(&m_signaled, true); } }; - - class ThreadedCounter { + + class ThreadedCounter + { static const int N = 100; static const int REPORT_INTERVAL = 10; int m_count; bool m_done; Semaphore m_count_sem; Semaphore m_print_sem; - + void count_up() { - for (m_count = 1; m_count <= N; m_count++) { - if (m_count % REPORT_INTERVAL == 0) { - if (m_count == N) m_done = true; + for (m_count = 1; m_count <= N; ++m_count) + if (m_count % REPORT_INTERVAL == 0) + { + if (m_count == N) + m_done = true; m_print_sem.put(); // signal printing to occur m_count_sem.take(); // wait until printing is complete proceeding } - } std::cout << "count_up() done\\n"; m_done = true; m_print_sem.put(); } - + void print_count() { - do { + do + { m_print_sem.take(); std::cout << m_count << '\\n'; m_count_sem.put(); - } while (!m_done); + } + while (!m_done); std::cout << "print_count() done\\n"; } - - public: + + public: ThreadedCounter() : m_done(false) {} void run() { @@ -139,7 +137,7 @@ typename std::enable_if::value && !std::is_same::va count_thread.join(); } }; - + int main() { ThreadedCounter m_counter; @@ -161,20 +159,29 @@ typename std::enable_if::value && !std::is_same::va print_count() done count_up() done + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj + .SH See also atomically performs bitwise AND between the argument and fetch_and the value of the atomic object and obtains the value held - \fI(C++11)\fP previously - \fI(public member function of std::atomic)\fP - atomic_fetch_or replaces the atomic object with the result of logical OR + previously + \fI(public member function of std::atomic)\fP + atomic_fetch_or replaces the atomic object with the result of bitwise OR atomic_fetch_or_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP - atomic_fetch_xor replaces the atomic object with the result of logical XOR + \fI(C++11)\fP \fI(function template)\fP + atomic_fetch_xor replaces the atomic object with the result of bitwise XOR atomic_fetch_xor_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP C documentation for atomic_fetch_and, atomic_fetch_and_explicit diff --git a/man/std::atomic_fetch_max,std::atomic_fetch_max_explicit.3 b/man/std::atomic_fetch_max,std::atomic_fetch_max_explicit.3 new file mode 100644 index 000000000..bbe68f0fc --- /dev/null +++ b/man/std::atomic_fetch_max,std::atomic_fetch_max_explicit.3 @@ -0,0 +1,77 @@ +.TH std::atomic_fetch_max,std::atomic_fetch_max_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_max,std::atomic_fetch_max_explicit \- std::atomic_fetch_max,std::atomic_fetch_max_explicit + +.SH Synopsis + Defined in header + template< class T > + + T atomic_fetch_max( std::atomic* obj, \fB(1)\fP (since C++26) + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_max( volatile std::atomic* obj, \fB(2)\fP (since C++26) + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_max_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP (since C++26) + arg, + + std::memory_order order ) noexcept; + template< class T > + + T atomic_fetch_max_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP (since C++26) + arg, + + std::memory_order order ) noexcept; + + Atomically replaces the value pointed by obj with the result of std::max between the + old value of obj and arg. Returns the value obj held previously. The operation is + performed as if the following was executed: + + 1,2) obj->fetch_max(arg) + 3,4) obj->fetch_max(arg, order) + + If std::atomic has no fetch_max member (this member is only provided for integral + and pointer types except bool), the program is ill-formed. + +.SH Parameters + + obj - pointer to the atomic object to modify + arg - the value to std::max with the value stored in the atomic object + order - the memory synchronization ordering + +.SH Return value + + The value immediately preceding the effects of this function in the modification + order of *obj. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_min_max 202403L (C++26) Atomic minimum/maximum + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + atomically performs std::max between the argument and the + fetch_max value of the atomic object and obtains the value held + (C++26) previously + \fI(public member function of std::atomic)\fP + atomic_fetch_min replaces the atomic object with the result of std::min + atomic_fetch_min_explicit with a non-atomic argument and obtains the previous value + (C++26) of the atomic + (C++26) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_fetch_min,std::atomic_fetch_min_explicit.3 b/man/std::atomic_fetch_min,std::atomic_fetch_min_explicit.3 new file mode 100644 index 000000000..4983a94a6 --- /dev/null +++ b/man/std::atomic_fetch_min,std::atomic_fetch_min_explicit.3 @@ -0,0 +1,77 @@ +.TH std::atomic_fetch_min,std::atomic_fetch_min_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_min,std::atomic_fetch_min_explicit \- std::atomic_fetch_min,std::atomic_fetch_min_explicit + +.SH Synopsis + Defined in header + template< class T > + + T atomic_fetch_min( std::atomic* obj, \fB(1)\fP (since C++26) + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_min( volatile std::atomic* obj, \fB(2)\fP (since C++26) + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_min_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP (since C++26) + arg, + + std::memory_order order ) noexcept; + template< class T > + + T atomic_fetch_min_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP (since C++26) + arg, + + std::memory_order order ) noexcept; + + Atomically replaces the value pointed by obj with the result of std::min between the + old value of obj and arg. Returns the value obj held previously. The operation is + performed as if the following was executed: + + 1,2) obj->fetch_min(arg) + 3,4) obj->fetch_min(arg, order) + + If std::atomic has no fetch_min member (this member is only provided for integral + and pointer types except bool), the program is ill-formed. + +.SH Parameters + + obj - pointer to the atomic object to modify + arg - the value to std::min with the value stored in the atomic object + order - the memory synchronization ordering + +.SH Return value + + The value immediately preceding the effects of this function in the modification + order of *obj. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_min_max 202403L (C++26) Atomic minimum/maximum + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + atomically performs std::min between the argument and the + fetch_min value of the atomic object and obtains the value held + (C++26) previously + \fI(public member function of std::atomic)\fP + atomic_fetch_max replaces the atomic object with the result of std::max + atomic_fetch_max_explicit with a non-atomic argument and obtains the previous value + (C++26) of the atomic + (C++26) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_fetch_or,std::atomic_fetch_or_explicit.3 b/man/std::atomic_fetch_or,std::atomic_fetch_or_explicit.3 index 0aab2c0c5..6e5c50b9d 100644 --- a/man/std::atomic_fetch_or,std::atomic_fetch_or_explicit.3 +++ b/man/std::atomic_fetch_or,std::atomic_fetch_or_explicit.3 @@ -1,83 +1,77 @@ -.TH std::atomic_fetch_or,std::atomic_fetch_or_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_fetch_or,std::atomic_fetch_or_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_or,std::atomic_fetch_or_explicit \- std::atomic_fetch_or,std::atomic_fetch_or_explicit + .SH Synopsis Defined in header - template< class Integral > - Integral atomic_fetch_or( - std::atomic* obj, Integral arg ); - template< class Integral > - Integral atomic_fetch_or( volatile - std::atomic* obj, Integral arg ); - template< class Integral > - - Integral atomic_fetch_or_explicit( - std::atomic* obj, - Integral - arg, \fB(1)\fP \fI(since C++11)\fP - - - std::memory_order order ); \fB(2)\fP \fI(since C++11)\fP - template< class Integral > - - Integral atomic_fetch_or_explicit( volatile - std::atomic* obj, - Integral + template< class T > + + T atomic_fetch_or( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_or( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_or_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP \fI(since C++11)\fP + arg, + + std::memory_order order ) noexcept; + template< class T > + + T atomic_fetch_or_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP \fI(since C++11)\fP arg, - - std::memory_order order ); + std::memory_order order ) noexcept; - Atomically replaces the value pointed by arg with the result of bitwise OR between + Atomically replaces the value pointed by obj with the result of bitwise OR between the old value of obj and arg. Returns the value obj held previously. The operation is performed as if the following is executed: - 1) obj->fetch_or(arg) - 2) obj->fetch_or(arg, order) + 1,2) obj->fetch_or(arg) + 3,4) obj->fetch_or(arg, order) + + If std::atomic has no fetch_or member (this member is only provided for integral + types except bool), the program is ill-formed. .SH Parameters obj - pointer to the atomic object to modify arg - the value to bitwise OR to the value stored in the atomic object - order - the memory sycnhronization ordering for this operation: all values are - permitted. + order - the memory synchronization ordering .SH Return value - The value held previously by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - + The value immediately preceding the effects of this function in the modification + order of *obj. -.SH Possible implementation +.SH Example -template< class T > -typename std::enable_if::value && !std::is_same::value, T>::type -atomic_fetch_or( std::atomic* obj, T arg ); -{ - return obj->fetch_or(arg); -} -.SH Example - - // Run this code - #include #include - #include #include #include - - // Binary semaphore for demonstrative purposes only + #include + #include + + // Binary semaphore for demonstrative purposes only. // This is a simple yet meaningful example: atomic operations // are unnecessary without threads. - class Semaphore { + class Semaphore + { std::atomic_char m_signaled; - public: + public: Semaphore(bool initial = false) { m_signaled = initial; @@ -85,50 +79,55 @@ atomic_fetch_or( std::atomic* obj, T arg ); // Block until semaphore is signaled void take() { - while (!std::atomic_fetch_and(&m_signaled, false)) { + while (!std::atomic_fetch_and(&m_signaled, false)) + { std::this_thread::sleep_for(std::chrono::milliseconds(10)); } } - + void put() { std::atomic_fetch_or(&m_signaled, true); } }; - - class ThreadedCounter { + + class ThreadedCounter + { static const int N = 100; static const int REPORT_INTERVAL = 10; int m_count; bool m_done; Semaphore m_count_sem; Semaphore m_print_sem; - + void count_up() { - for (m_count = 1; m_count <= N; m_count++) { - if (m_count % REPORT_INTERVAL == 0) { - if (m_count == N) m_done = true; + for (m_count = 1; m_count <= N; ++m_count) + if (m_count % REPORT_INTERVAL == 0) + { + if (m_count == N) + m_done = true; m_print_sem.put(); // signal printing to occur m_count_sem.take(); // wait until printing is complete proceeding } - } std::cout << "count_up() done\\n"; m_done = true; m_print_sem.put(); } - + void print_count() { - do { + do + { m_print_sem.take(); std::cout << m_count << '\\n'; m_count_sem.put(); - } while (!m_done); + } + while (!m_done); std::cout << "print_count() done\\n"; } - - public: + + public: ThreadedCounter() : m_done(false) {} void run() { @@ -138,7 +137,7 @@ atomic_fetch_or( std::atomic* obj, T arg ); count_thread.join(); } }; - + int main() { ThreadedCounter m_counter; @@ -160,20 +159,29 @@ atomic_fetch_or( std::atomic* obj, T arg ); print_count() done count_up() done + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj + .SH See also atomically performs bitwise OR between the argument and fetch_or the value of the atomic object and obtains the value held - \fI(C++11)\fP previously - \fI(public member function of std::atomic)\fP - atomic_fetch_and replaces the atomic object with the result of logical AND + previously + \fI(public member function of std::atomic)\fP + atomic_fetch_and replaces the atomic object with the result of bitwise AND atomic_fetch_and_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP - atomic_fetch_xor replaces the atomic object with the result of logical XOR + \fI(C++11)\fP \fI(function template)\fP + atomic_fetch_xor replaces the atomic object with the result of bitwise XOR atomic_fetch_xor_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP C documentation for atomic_fetch_or, atomic_fetch_or_explicit diff --git a/man/std::atomic_fetch_sub,std::atomic_fetch_sub_explicit.3 b/man/std::atomic_fetch_sub,std::atomic_fetch_sub_explicit.3 index ed58b655e..0cf1a940a 100644 --- a/man/std::atomic_fetch_sub,std::atomic_fetch_sub_explicit.3 +++ b/man/std::atomic_fetch_sub,std::atomic_fetch_sub_explicit.3 @@ -1,168 +1,132 @@ -.TH std::atomic_fetch_sub,std::atomic_fetch_sub_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_fetch_sub,std::atomic_fetch_sub_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_sub,std::atomic_fetch_sub_explicit \- std::atomic_fetch_sub,std::atomic_fetch_sub_explicit + .SH Synopsis Defined in header - template< class Integral > - Integral atomic_fetch_sub( - std::atomic* obj, - Integral arg ); - template< class Integral > - Integral atomic_fetch_sub( - volatile std::atomic* - obj, Integral arg ); - template< class Integral > - - Integral - atomic_fetch_sub_explicit( - std::atomic* obj, - Integral arg, - - - std::memory_order order ); - template< class Integral > - - Integral - atomic_fetch_sub_explicit( - volatile std::atomic* - obj, Integral arg, - - \fB(1)\fP (since - std::memory_order order); C++11) template< class T > - T* atomic_fetch_sub( - std::atomic* obj, \fB(2)\fP (since - std::ptrdiff_t arg ); C++11) + + T atomic_fetch_sub( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::difference_type arg ) + noexcept; template< class T > - T* atomic_fetch_sub( volatile - std::atomic* obj, - std::ptrdiff_t arg ); + + T atomic_fetch_sub( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + + typename std::atomic::difference_type arg ) + noexcept; template< class T > - T* atomic_fetch_sub_explicit( - std::atomic* obj, \fB(3)\fP (since - std::ptrdiff_t arg, C++11) + T atomic_fetch_sub_explicit( std::atomic* obj, + typename \fB(3)\fP \fI(since C++11)\fP + std::atomic::difference_type arg, + + std::memory_order order ) noexcept; + template< class T > - - std::memory_order order ); \fB(4)\fP (since - template< class T > C++11) + T atomic_fetch_sub_explicit( volatile std::atomic* obj, + typename \fB(4)\fP \fI(since C++11)\fP + std::atomic::difference_type arg, - T* atomic_fetch_sub_explicit( - volatile std::atomic* obj, - std::ptrdiff_t arg, + std::memory_order order ) noexcept; - - std::memory_order order ); + Performs atomic subtraction. Atomically subtracts arg from the value pointed to by + obj and returns the value obj held previously. The operation is performed as if the + following was executed: - Performs atomic subtraction. + 1,2) obj->fetch_sub(arg) + 3,4) obj->fetch_sub(arg, order) - 1-2) Atomically subtracts arg from the value pointed to by obj and returns the value - obj held previously. The operation is performed as if the following was executed: - 1) obj->fetch_sub(arg) - 2) obj->fetch_sub(arg, order) - 3-4) Atomically decrements the pointer value, pointed to by obj, by arg, and returns - the value obj held previously. The operation is performed as if the following was - executed: - 3) obj->fetch_sub(arg) - 4) obj->fetch_sub(arg, order) + If std::atomic has no fetch_sub member (this member is only provided for integral + , floating-point + \fI(since C++20)\fP and pointer types except bool), the program is ill-formed. .SH Parameters obj - pointer to the atomic object to modify arg - the value to subtract from the value stored in the atomic object - order - the memory sycnhronization ordering for this operation: all values are - permitted. + order - the memory synchronization ordering .SH Return value - The value held previously by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Possible implementation - -.SH First version -template< class T > -typename std::enable_if::value && !std::is_same::value, T>::type -atomic_fetch_sub( std::atomic* obj, T arg ); -{ - return obj->fetch_sub(arg); -} -.SH Second version -template< class T > -T* atomic_fetch_sub( std::atomic* obj, std::ptrdiff_t arg) -{ - return obj->fetch_sub(arg); -} + The value immediately preceding the effects of this function in the modification + order of *obj. .SH Example - Multiple threads may use fetch_sub to concurrently process an indexed container + Multiple threads may use std::atomic_fetch_sub to concurrently process an indexed + container. + - // Run this code + #include + #include + #include #include #include #include - #include - #include - #include - - const int N = 10000; + + const int N = 50; std::atomic cnt; std::vector data(N); - + void reader(int id) { - for (;;) { + for (;;) + { int idx = atomic_fetch_sub_explicit(&cnt, 1, std::memory_order_relaxed); - if (idx >= 0) { + if (idx >= 0) std::cout << "reader " << std::to_string(id) << " processed item " << std::to_string(data[idx]) << '\\n'; - } else { + else + { std::cout << "reader " << std::to_string(id) << " done\\n"; break; } } } - + int main() { std::iota(data.begin(), data.end(), 1); cnt = data.size() - 1; - + std::vector v; - for (int n = 0; n < 10; ++n) { + for (int n = 0; n < 5; ++n) v.emplace_back(reader, n); - } - for (auto& t : v) { + for (auto& t : v) t.join(); - } } .SH Output: - reader 2 processed item 10000 - reader 6 processed item 9994 - reader 4 processed item 9996 - reader 6 processed item 9992 + reader 2 processed item 50 + reader 1 processed item 44 + reader 4 processed item 46 <....> reader 0 done - reader 5 done + reader 4 done reader 3 done - reader 9 done + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj .SH See also - fetch_sub atomically subtracts the argument from the value stored in - \fI(C++11)\fP the atomic object and obtains the value held previously - \fI(public member function of std::atomic)\fP + atomically subtracts the argument from the value stored in + fetch_sub the atomic object and obtains the value held previously + \fI(public member function of std::atomic)\fP atomic_fetch_add adds a non-atomic value to an atomic object and obtains atomic_fetch_add_explicit the previous value of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP C documentation for atomic_fetch_sub, diff --git a/man/std::atomic_fetch_xor,std::atomic_fetch_xor_explicit.3 b/man/std::atomic_fetch_xor,std::atomic_fetch_xor_explicit.3 index e6dd05aa8..256054243 100644 --- a/man/std::atomic_fetch_xor,std::atomic_fetch_xor_explicit.3 +++ b/man/std::atomic_fetch_xor,std::atomic_fetch_xor_explicit.3 @@ -1,84 +1,89 @@ -.TH std::atomic_fetch_xor,std::atomic_fetch_xor_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_fetch_xor,std::atomic_fetch_xor_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_fetch_xor,std::atomic_fetch_xor_explicit \- std::atomic_fetch_xor,std::atomic_fetch_xor_explicit + .SH Synopsis Defined in header - template< class Integral > - Integral atomic_fetch_xor( - std::atomic* obj, Integral arg ); - template< class Integral > - Integral atomic_fetch_xor( volatile - std::atomic* obj, Integral arg ); - template< class Integral > + template< class T > + + T atomic_fetch_xor( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::value_type arg ) + noexcept; + template< class T > + + T atomic_fetch_xor( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP - Integral atomic_fetch_xor_explicit( - std::atomic* obj, Integral arg, \fB(1)\fP \fI(since C++11)\fP + typename std::atomic::value_type arg ) + noexcept; + template< class T > - - std::memory_order order ); \fB(2)\fP \fI(since C++11)\fP - template< class Integral > + T atomic_fetch_xor_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP \fI(since C++11)\fP + arg, - Integral atomic_fetch_xor_explicit( volatile - std::atomic* obj, Integral arg, + std::memory_order order) noexcept; + template< class T > - - std::memory_order order ); + T atomic_fetch_xor_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP \fI(since C++11)\fP + arg, - Atomically replaces the value pointed by arg with the result of bitwise XOR between + std::memory_order order) noexcept; + + Atomically replaces the value pointed by obj with the result of bitwise XOR between the old value of obj and arg. Returns the value obj held previously. The operation is performed as if the following is executed: - 1) obj->fetch_xor(arg) - 2) obj->fetch_xor(arg, order) + 1,2) obj->fetch_xor(arg) + 3,4) obj->fetch_xor(arg, order) + + If std::atomic has no fetch_xor member (this member is only provided for integral + types except bool), the program is ill-formed. .SH Parameters obj - pointer to the atomic object to modify arg - the value to bitwise XOR to the value stored in the atomic object - order - the memory sycnhronization ordering for this operation: all values are - permitted. + order - the memory synchronization ordering .SH Return value - The value held previously by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Possible implementation - -template< class T > -typename std::enable_if::value && !std::is_same::value, T>::type -atomic_fetch_xor( std::atomic* obj, T arg ); -{ - return obj->fetch_xor(arg); -} + The value immediately preceding the effects of this function in the modification + order of *obj. .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj + .SH See also atomically performs bitwise XOR between the argument and fetch_xor the value of the atomic object and obtains the value held - \fI(C++11)\fP previously - \fI(public member function of std::atomic)\fP - atomic_fetch_or replaces the atomic object with the result of logical OR + previously + \fI(public member function of std::atomic)\fP + atomic_fetch_or replaces the atomic object with the result of bitwise OR atomic_fetch_or_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP - atomic_fetch_and replaces the atomic object with the result of logical AND + \fI(C++11)\fP \fI(function template)\fP + atomic_fetch_and replaces the atomic object with the result of bitwise AND atomic_fetch_and_explicit with a non-atomic argument and obtains the previous value \fI(C++11)\fP of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP C documentation for atomic_fetch_xor, atomic_fetch_xor_explicit .SH Category: - * Todo no example diff --git a/man/std::atomic_flag.3 b/man/std::atomic_flag.3 index 047ac34f6..c04039dd1 100644 --- a/man/std::atomic_flag.3 +++ b/man/std::atomic_flag.3 @@ -1,4 +1,7 @@ -.TH std::atomic_flag 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag \- std::atomic_flag + .SH Synopsis Defined in header class atomic_flag; \fI(since C++11)\fP @@ -11,66 +14,97 @@ constructor constructs an atomic_flag \fI(public member function)\fP - operator= the assignment operator - \fI(public member function)\fP + operator= the assignment operator (deleted) + [deleted] \fI(public member function)\fP clear atomically sets flag to false - \fI(public member function)\fP + \fI(public member function)\fP test_and_set atomically sets the flag to true and obtains its previous value - \fI(public member function)\fP + \fI(public member function)\fP + test atomically returns the value of the flag + (C++20) \fI(public member function)\fP + wait blocks the thread until notified and the atomic value changes + (C++20) \fI(public member function)\fP + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function)\fP .SH Example - A spinlock mutex can be implemented in userspace using an atomic_flag + A spinlock mutex demo can be implemented in userspace using an atomic_flag. Do note + that spinlock mutexes are extremely dubious in practice. + - // Run this code + #include + #include #include #include - #include - #include - + std::atomic_flag lock = ATOMIC_FLAG_INIT; - + void f(int n) { - for (int cnt = 0; cnt < 100; ++cnt) { - while (lock.test_and_set(std::memory_order_acquire)) // acquire lock - ; // spin - std::cout << "Output from thread " << n << '\\n'; - lock.clear(std::memory_order_release); // release lock + for (int cnt = 0; cnt < 40; ++cnt) + { + while (lock.test_and_set(std::memory_order_acquire)) // acquire lock + { + // Since C++20, it is possible to update atomic_flag's + // value only when there is a chance to acquire the lock. + // See also: https://stackoverflow.com/questions/62318642 + #if defined(__cpp_lib_atomic_flag_test) + while (lock.test(std::memory_order_relaxed)) // test lock + #endif + ; // spin + } + static int out{}; + std::cout << n << ((++out % 40) == 0 ? '\\n' : ' '); + lock.clear(std::memory_order_release); // release lock } } - + int main() { std::vector v; - for (int n = 0; n < 10; ++n) { + for (int n = 0; n < 10; ++n) v.emplace_back(f, n); - } - for (auto& t : v) { + for (auto& t : v) t.join(); - } } -.SH Output: +.SH Possible output: - Output from thread 2 - Output from thread 6 - Output from thread 7 - ...... + 0 1 1 2 0 1 3 2 3 2 0 1 2 3 2 3 0 1 3 2 0 1 2 3 2 3 0 3 2 3 2 3 2 3 1 2 3 0 1 3 + 2 3 2 0 1 2 3 0 1 2 3 2 0 1 2 3 0 1 2 3 2 3 2 3 2 0 1 2 3 2 3 0 1 3 2 3 0 2 1 1 + 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 3 2 0 2 3 2 3 2 3 2 3 2 3 0 3 + 2 3 0 3 0 3 2 3 0 3 2 3 2 3 0 2 3 0 3 2 0 2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 + 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 + 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 + 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 + 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 + 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 + 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 .SH See also atomic_flag_test_and_set atomically sets the flag to true and returns its atomic_flag_test_and_set_explicit previous value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP atomic_flag_clear atomic_flag_clear_explicit atomically sets the value of the flag to false - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP + atomic_flag_wait blocks the thread until notified and the flag + atomic_flag_wait_explicit changes + (C++20) \fI(function)\fP + (C++20) + atomic_flag_notify_one notifies a thread blocked in atomic_flag_wait + (C++20) \fI(function)\fP + atomic_flag_notify_all notifies all threads blocked in atomic_flag_wait + (C++20) \fI(function)\fP ATOMIC_FLAG_INIT initializes an std::atomic_flag to false - \fI(C++11)\fP (macro constant) + \fI(C++11)\fP (macro constant) C documentation for atomic_flag diff --git a/man/std::atomic_flag::atomic_flag.3 b/man/std::atomic_flag::atomic_flag.3 index 8421f8c8e..37f4c4e75 100644 --- a/man/std::atomic_flag::atomic_flag.3 +++ b/man/std::atomic_flag::atomic_flag.3 @@ -1,32 +1,28 @@ -.TH std::atomic_flag::atomic_flag 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag::atomic_flag 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::atomic_flag \- std::atomic_flag::atomic_flag + .SH Synopsis Defined in header - atomic_flag(); \fB(1)\fP \fI(since C++11)\fP - atomic_flag( const atomic_flag& ) = delete; \fB(2)\fP \fI(since C++11)\fP + atomic_flag() noexcept = default; \fI(since C++11)\fP + \fB(1)\fP \fI(until C++20)\fP + constexpr atomic_flag() noexcept; \fI(since C++20)\fP + atomic_flag( const atomic_flag& ) = delete; \fB(2)\fP \fI(since C++11)\fP Constructs a new std::atomic_flag. - 1) Trivial default constructor, initializes std::atomic_flag to unspecified state. + 1) Trivial default constructor, initializes std::atomic_flag to \fI(until C++20)\fP + unspecified state. + 1) Initializes std::atomic_flag to clear state. \fI(since C++20)\fP 2) The copy constructor is deleted; std::atomic_flag is not copyable. In addition, std::atomic_flag can be value-initialized to clear state with the expression ATOMIC_FLAG_INIT. For an atomic_flag with static storage duration, this - guarantees that the values of this flag is known before any constructors are run for - static objects. - -.SH Parameters - - arg - the result of ATOMIC_FLAG_INIT - -.SH Exceptions - - 1) - noexcept specification: - noexcept - + guarantees static initialization: the flag can be used in constructors of static + objects. .SH See also ATOMIC_FLAG_INIT initializes an std::atomic_flag to false - \fI(C++11)\fP (macro constant) + \fI(C++11)\fP (macro constant) diff --git a/man/std::atomic_flag::clear.3 b/man/std::atomic_flag::clear.3 index f651b8cd1..7bc68f244 100644 --- a/man/std::atomic_flag::clear.3 +++ b/man/std::atomic_flag::clear.3 @@ -1,33 +1,41 @@ -.TH std::atomic_flag::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::clear \- std::atomic_flag::clear + .SH Synopsis Defined in header - void clear( std::memory_order order = std::memory_order_seq_cst ) \fB(1)\fP \fI(since C++11)\fP - volatile; - void clear( std::memory_order order = std::memory_order_seq_cst ); \fB(2)\fP \fI(since C++11)\fP + void clear( std::memory_order order = \fB(1)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) volatile noexcept; + void clear( std::memory_order order = \fB(2)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; Atomically changes the state of a std::atomic_flag to clear (false). + If order is one of std::memory_order_consume, std::memory_order_acquire and + std::memory_order_acq_rel, the behavior is undefined. + .SH Parameters - the memory sycnhronization ordering for this operation (cannot be - order - std::memory_order_consume, std::memory_order_acquire, or - std::memory_order_acq_rel) + order - the memory synchronization ordering + + Defect reports -.SH Exceptions + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + LWG 2138 C++11 order could be std::memory_order_consume the behavior is + undefined in this case .SH See also atomically sets the flag to true and obtains its previous test_and_set value - \fI(public member function)\fP + \fI(public member function)\fP atomic_flag_clear atomic_flag_clear_explicit atomically sets the value of the flag to false - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP memory_order defines memory ordering constraints for the given atomic \fI(C++11)\fP operation - \fI(typedef)\fP + \fI(enum)\fP diff --git a/man/std::atomic_flag::notify_all.3 b/man/std::atomic_flag::notify_all.3 new file mode 100644 index 000000000..b3f7063f8 --- /dev/null +++ b/man/std::atomic_flag::notify_all.3 @@ -0,0 +1,41 @@ +.TH std::atomic_flag::notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::notify_all \- std::atomic_flag::notify_all + +.SH Synopsis + void notify_all() noexcept; \fB(1)\fP \fI(since C++20)\fP + void notify_all() volatile noexcept; \fB(2)\fP \fI(since C++20)\fP + + Performs atomic notifying operations. + + Unblocks all threads blocked in atomic waiting operations (i.e. wait()) on *this, if + there are any; otherwise does nothing. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value + (C++20) changes + \fI(public member function)\fP + atomic_flag_wait + atomic_flag_wait_explicit blocks the thread until notified and the flag changes + (C++20) \fI(function)\fP + (C++20) + atomic_flag_notify_one notifies a thread blocked in atomic_flag_wait + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag::notify_one.3 b/man/std::atomic_flag::notify_one.3 new file mode 100644 index 000000000..171b38b3b --- /dev/null +++ b/man/std::atomic_flag::notify_one.3 @@ -0,0 +1,41 @@ +.TH std::atomic_flag::notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::notify_one \- std::atomic_flag::notify_one + +.SH Synopsis + void notify_one() noexcept; \fB(1)\fP \fI(since C++20)\fP + void notify_one() volatile noexcept; \fB(2)\fP \fI(since C++20)\fP + + Performs atomic notifying operations. + + If there is a thread blocked in atomic waiting operation (i.e. wait()) on *this, + then unblocks at least one such thread; otherwise does nothing. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value + (C++20) changes + \fI(public member function)\fP + atomic_flag_wait + atomic_flag_wait_explicit blocks the thread until notified and the flag changes + (C++20) \fI(function)\fP + (C++20) + atomic_flag_notify_one notifies a thread blocked in atomic_flag_wait + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag::operator=.3 b/man/std::atomic_flag::operator=.3 index 86f2861a0..78a21d6d4 100644 --- a/man/std::atomic_flag::operator=.3 +++ b/man/std::atomic_flag::operator=.3 @@ -1,4 +1,7 @@ -.TH std::atomic_flag::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::operator= \- std::atomic_flag::operator= + .SH Synopsis Defined in header atomic_flag& operator=( const atomic_flag& ) = delete; \fB(1)\fP \fI(since C++11)\fP diff --git a/man/std::atomic_flag::test.3 b/man/std::atomic_flag::test.3 new file mode 100644 index 000000000..5486de287 --- /dev/null +++ b/man/std::atomic_flag::test.3 @@ -0,0 +1,38 @@ +.TH std::atomic_flag::test 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::test \- std::atomic_flag::test + +.SH Synopsis + bool test( std::memory_order order = + std::memory_order_seq_cst ) const volatile \fB(1)\fP \fI(since C++20)\fP + noexcept; + bool test( std::memory_order order = \fB(2)\fP \fI(since C++20)\fP + std::memory_order_seq_cst ) const noexcept; + + Atomically reads the value of the *this and returns the value. + + If order is one of std::memory_order_release and std::memory_order_acq_rel, the + behavior is undefined. + +.SH Parameters + + order - the memory synchronization ordering + +.SH Return value + + The value atomically read. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + atomic_flag_test + atomic_flag_test_explicit atomically returns the value of the flag + (C++20) \fI(function)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag::test_and_set.3 b/man/std::atomic_flag::test_and_set.3 index 85a7109e6..93b44ab05 100644 --- a/man/std::atomic_flag::test_and_set.3 +++ b/man/std::atomic_flag::test_and_set.3 @@ -1,32 +1,30 @@ -.TH std::atomic_flag::test_and_set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag::test_and_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::test_and_set \- std::atomic_flag::test_and_set + .SH Synopsis Defined in header - bool test_and_set(std::memory_order order = \fB(1)\fP \fI(since C++11)\fP - std::memory_order_seq_cst) volatile; - bool test_and_set(std::memory_order order = \fB(2)\fP \fI(since C++11)\fP - std::memory_order_seq_cst); + bool test_and_set( std::memory_order order = + std::memory_order_seq_cst ) volatile \fB(1)\fP \fI(since C++11)\fP + noexcept; + bool test_and_set( std::memory_order order = \fB(2)\fP \fI(since C++11)\fP + std::memory_order_seq_cst ) noexcept; Atomically changes the state of a std::atomic_flag to set (true) and returns the value it held before. .SH Parameters - order - the memory synchronization ordering for this operation - -.SH Exceptions - - noexcept specification: - noexcept - + order - the memory synchronization order .SH See also clear atomically sets flag to false - \fI(public member function)\fP + \fI(public member function)\fP atomic_flag_test_and_set atomically sets the flag to true and returns its atomic_flag_test_and_set_explicit previous value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP memory_order defines memory ordering constraints for the given \fI(C++11)\fP atomic operation - \fI(typedef)\fP + \fI(enum)\fP diff --git a/man/std::atomic_flag::wait.3 b/man/std::atomic_flag::wait.3 new file mode 100644 index 000000000..4ecd8d792 --- /dev/null +++ b/man/std::atomic_flag::wait.3 @@ -0,0 +1,61 @@ +.TH std::atomic_flag::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag::wait \- std::atomic_flag::wait + +.SH Synopsis + void wait( bool old, std::memory_order order = + std::memory_order::seq_cst ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + void wait( bool old, std::memory_order order = + std::memory_order::seq_cst ) const \fB(2)\fP \fI(since C++20)\fP + volatile noexcept; + + Performs atomic waiting operations. Behaves as if it repeatedly performs the + following steps: + + * Compare this->test(order) with that of old. + * If those are equal, then blocks until *this is notified by notify_one() or + notify_all(), or the thread is unblocked spuriously. + * Otherwise, returns. + + These functions are guaranteed to return only if value has changed, even if + underlying implementation unblocks spuriously. + + If order is one of std::memory_order::release and std::memory_order::acq_rel, the + behavior is undefined. + +.SH Parameters + + old - the value to check the atomic_flag's object no longer contains + order - memory order constraints to enforce + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + + Due to the ABA problem, transient changes from old to another value and back to old + might be missed, and not unblock. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function)\fP + atomic_flag_notify_one notifies a thread blocked in atomic_flag_wait + (C++20) \fI(function)\fP + atomic_flag_notify_all notifies all threads blocked in atomic_flag_wait + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag_clear,std::atomic_flag_clear_explicit.3 b/man/std::atomic_flag_clear,std::atomic_flag_clear_explicit.3 index 748d5e16b..9464b1fc6 100644 --- a/man/std::atomic_flag_clear,std::atomic_flag_clear_explicit.3 +++ b/man/std::atomic_flag_clear,std::atomic_flag_clear_explicit.3 @@ -1,73 +1,56 @@ -.TH std::atomic_flag_clear,std::atomic_flag_clear_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag_clear,std::atomic_flag_clear_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag_clear,std::atomic_flag_clear_explicit \- std::atomic_flag_clear,std::atomic_flag_clear_explicit + .SH Synopsis Defined in header - void atomic_flag_clear( volatile - std::atomic_flag* p ); - void atomic_flag_clear( std::atomic_flag* p ); - void atomic_flag_clear_explicit( volatile - std::atomic_flag* p, - \fB(1)\fP \fI(since C++11)\fP - std::memory_order order ) \fB(2)\fP \fI(since C++11)\fP - void atomic_flag_clear_explicit( - std::atomic_flag* p, - - std::memory_order order ) - - Atomically changes the state of a std::atomic_flag pointed to by p to clear (false). + void atomic_flag_clear( volatile std::atomic_flag* obj ) noexcept; \fB(1)\fP \fI(since C++11)\fP + void atomic_flag_clear( std::atomic_flag* obj ) noexcept; \fB(2)\fP \fI(since C++11)\fP + void atomic_flag_clear_explicit( volatile std::atomic_flag* obj, + std::memory_order order ) \fB(3)\fP \fI(since C++11)\fP + noexcept; + void atomic_flag_clear_explicit( std::atomic_flag* obj, + std::memory_order order ) \fB(4)\fP \fI(since C++11)\fP + noexcept; + + Atomically changes the state of the std::atomic_flag pointed to by obj to clear + (false). + + 1,2) The memory synchronization ordering is std::memory_order_seq_cst. + 3,4) The memory synchronization ordering is order. + If order is one of std::memory_order_consume, std::memory_order_acquire and + std::memory_order_acq_rel, the behavior is undefined. .SH Parameters - p - pointer to std::atomic_flag to access - the memory sycnhronization ordering for this operation: only - order - std::memory_order_relaxed, std::memory_order_acquire, or - std::memory_order_seq_cst are permitted. - -.SH Return value + obj - pointer to std::atomic_flag to access + order - the memory synchronization ordering - none. +.SH Notes -.SH Exceptions + std::atomic_flag_clear and std::atomic_flag_clear_explicit can be implemented as + obj->clear() and obj->clear(order) respectively. - noexcept specification: - noexcept - + Defect reports -.SH Possible implementation + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH First version - void atomic_flag_clear(volatile std::atomic_flag* p) - { - p->clear(); - } -.SH Second version - void atomic_flag_clear(std::atomic_flag* p) - { - p->clear(); - } - Third version - void atomic_flag_clear_explicit(volatile std::atomic_flag* p, - std::memory_order order) - { - p->clear(order); - } - Fourth version - void atomic_flag_clear_explicit(std::atomic_flag* p, - std::memory_order order) - { - p->clear(order); - } + DR Applied to Behavior as published Correct behavior + LWG 2138 C++11 order could be std::memory_order_consume the behavior is + undefined in this case .SH See also atomic_flag the lock-free boolean atomic type - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP atomic_flag_test_and_set atomically sets the flag to true and returns its atomic_flag_test_and_set_explicit previous value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP memory_order defines memory ordering constraints for the given \fI(C++11)\fP atomic operation - \fI(typedef)\fP + \fI(enum)\fP C documentation for atomic_flag_clear, atomic_flag_clear_explicit diff --git a/man/std::atomic_flag_notify_all.3 b/man/std::atomic_flag_notify_all.3 new file mode 100644 index 000000000..60c17553d --- /dev/null +++ b/man/std::atomic_flag_notify_all.3 @@ -0,0 +1,51 @@ +.TH std::atomic_flag_notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag_notify_all \- std::atomic_flag_notify_all + +.SH Synopsis + Defined in header + void atomic_flag_notify_all( std::atomic_flag* object ) noexcept; \fB(1)\fP \fI(since C++20)\fP + void atomic_flag_notify_all( volatile std::atomic_flag* object ) \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Performs atomic notifying operations. + + Unblocks all threads blocked in atomic waiting operations (i.e. + std::atomic_flag_wait(), std::atomic_flag_wait_explicit(), or + std::atomic_flag::wait()) on *object, if there are any; otherwise does nothing. + + Equivalent to object->notify_all(). + +.SH Parameters + + object - pointer to the atomic_flag object to notify + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function of std::atomic_flag)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function of std::atomic_flag)\fP + atomic_flag_wait + atomic_flag_wait_explicit blocks the thread until notified and the flag changes + (C++20) \fI(function)\fP + (C++20) + atomic_flag_notify_one notifies a thread blocked in atomic_flag_wait + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag_notify_one.3 b/man/std::atomic_flag_notify_one.3 new file mode 100644 index 000000000..adc90a7f7 --- /dev/null +++ b/man/std::atomic_flag_notify_one.3 @@ -0,0 +1,48 @@ +.TH std::atomic_flag_notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag_notify_one \- std::atomic_flag_notify_one + +.SH Synopsis + Defined in header + void atomic_flag_notify_one( std::atomic_flag* object ) noexcept; \fB(1)\fP \fI(since C++20)\fP + void atomic_flag_notify_one( volatile std::atomic_flag* object ) \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Performs atomic notifying operations. + + If there is a thread blocked in an atomic waiting operation (i.e. + std::atomic_flag_wait(), std::atomic_flag_wait_explicit(), or + std::atomic_flag::wait()) on *object, then unblocks at least one such thread; + otherwise does nothing. + + Equivalent to object->notify_one(). + +.SH Parameters + + object - pointer to the atomic_flag object to notify + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function of std::atomic_flag)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function of std::atomic_flag)\fP + atomic_flag_notify_all notifies all threads blocked in atomic_flag_wait + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag_test,std::atomic_flag_test_explicit.3 b/man/std::atomic_flag_test,std::atomic_flag_test_explicit.3 new file mode 100644 index 000000000..eca754327 --- /dev/null +++ b/man/std::atomic_flag_test,std::atomic_flag_test_explicit.3 @@ -0,0 +1,50 @@ +.TH std::atomic_flag_test,std::atomic_flag_test_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag_test,std::atomic_flag_test_explicit \- std::atomic_flag_test,std::atomic_flag_test_explicit + +.SH Synopsis + Defined in header + bool atomic_flag_test( const volatile std::atomic_flag* object ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + bool atomic_flag_test( const std::atomic_flag* object ) noexcept; \fB(2)\fP \fI(since C++20)\fP + bool atomic_flag_test_explicit( const volatile std::atomic_flag* + object, \fB(3)\fP \fI(since C++20)\fP + std::memory_order order ) + noexcept; + bool atomic_flag_test_explicit( const std::atomic_flag* object, + std::memory_order order ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + + Atomically reads the value of the *object and returns the value. + + 1,2) The memory synchronization order is std::memory_order_seq_cst. + 3,4) The memory synchronization order is order. + If order is one of std::memory_order::release and std::memory_order::acq_rel, the + behavior is undefined. + +.SH Parameters + + object - pointer to the atomic_flag object to read + order - the memory synchronization ordering + +.SH Return value + + The value atomically read. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_flag_test 201907L (C++20) std::atomic_flag::test + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + test atomically returns the value of the flag + (C++20) \fI(public member function of std::atomic_flag)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit.3 b/man/std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit.3 index 1cea39837..5393a21f5 100644 --- a/man/std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit.3 +++ b/man/std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit.3 @@ -1,94 +1,72 @@ -.TH std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit \- std::atomic_flag_test_and_set,std::atomic_flag_test_and_set_explicit + .SH Synopsis Defined in header - bool atomic_flag_test_and_set( volatile std::atomic_flag* - p ); - bool atomic_flag_test_and_set( std::atomic_flag* p ); - bool atomic_flag_test_and_set_explicit( volatile - std::atomic_flag* p, (since - std::memory_order \fB(1)\fP C++11) - order ); \fB(2)\fP (since - bool atomic_flag_test_and_set_explicit( std::atomic_flag* C++11) - p, - std::memory_order - order ); - - Atomically changes the state of a std::atomic_flag pointed to by p to set (true) and - returns the value it held before. + bool atomic_flag_test_and_set( volatile std::atomic_flag* obj ) \fB(1)\fP \fI(since C++11)\fP + noexcept; + bool atomic_flag_test_and_set( std::atomic_flag* obj ) noexcept; \fB(2)\fP \fI(since C++11)\fP + bool atomic_flag_test_and_set_explicit( volatile std::atomic_flag* + obj, \fB(3)\fP \fI(since C++11)\fP + std::memory_order order ) + noexcept; + bool atomic_flag_test_and_set_explicit( std::atomic_flag* obj, + std::memory_order order ) \fB(4)\fP \fI(since C++11)\fP + noexcept; + + Atomically changes the state of a std::atomic_flag pointed to by obj to set (true) + and returns the value it held before. + + 1,2) The memory synchronization order is std::memory_order_seq_cst. + 3,4) The memory synchronization order is order. .SH Parameters - p - pointer to std::atomic_flag to access - order - the memory synchronization order for this operation + obj - pointer to std::atomic_flag to access + order - the memory synchronization order .SH Return value - The value previously held by the flag pointed to by p - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Possible implementation - -.SH First version - bool atomic_flag_test_and_set(volatile std::atomic_flag* p) - { - return p->test_and_set(); - } -.SH Second version - bool atomic_flag_test_and_set(std::atomic_flag* p) - { - return p->test_and_set(); - } - Third version - bool atomic_flag_test_and_set_explicit(volatile std::atomic_flag* p, - std::memory_order order) - { - return p->test_and_set(order); - } - Fourth version - bool atomic_flag_test_and_set_explicit(std::atomic_flag* p, - std::memory_order order) - { - return p->test_and_set(order); - } + The value previously held by the flag pointed to by obj. + +.SH Notes + + std::atomic_flag_test_and_set and std::atomic_flag_test_and_set_explicit can be + implemented as obj->test_and_set() and obj->test_and_set(order) respectively. .SH Example - A spinlock mutex can be implemented in userspace using an atomic_flag + A spinlock mutex can be implemented in userspace using an std::atomic_flag. + - // Run this code + #include + #include #include #include - #include - #include - + std::atomic_flag lock = ATOMIC_FLAG_INIT; - + void f(int n) { - for (int cnt = 0; cnt < 100; ++cnt) { - while(std::atomic_flag_test_and_set_explicit(&lock, std::memory_order_acquire)) - ; // spin until the lock is acquired + for (int cnt = 0; cnt < 100; ++cnt) + { + while (std::atomic_flag_test_and_set_explicit(&lock, std::memory_order_acquire)) + ; // spin until the lock is acquired std::cout << "Output from thread " << n << '\\n'; std::atomic_flag_clear_explicit(&lock, std::memory_order_release); } } - + int main() { std::vector v; - for (int n = 0; n < 10; ++n) { + for (int n = 0; n < 10; ++n) v.emplace_back(f, n); - } - for (auto& t : v) { + for (auto& t : v) t.join(); - } } .SH Output: @@ -101,14 +79,14 @@ .SH See also atomic_flag the lock-free boolean atomic type - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP atomic_flag_clear atomic_flag_clear_explicit atomically sets the value of the flag to false - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP memory_order defines memory ordering constraints for the given atomic \fI(C++11)\fP operation - \fI(typedef)\fP + \fI(enum)\fP C documentation for atomic_flag_test_and_set, atomic_flag_test_and_set_explicit diff --git a/man/std::atomic_flag_wait,std::atomic_flag_wait_explicit.3 b/man/std::atomic_flag_wait,std::atomic_flag_wait_explicit.3 new file mode 100644 index 000000000..ac9a71fa8 --- /dev/null +++ b/man/std::atomic_flag_wait,std::atomic_flag_wait_explicit.3 @@ -0,0 +1,69 @@ +.TH std::atomic_flag_wait,std::atomic_flag_wait_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_flag_wait,std::atomic_flag_wait_explicit \- std::atomic_flag_wait,std::atomic_flag_wait_explicit + +.SH Synopsis + Defined in header + void atomic_flag_wait( const atomic_flag* object, bool old ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + void atomic_flag_wait( const volatile atomic_flag* object, \fB(2)\fP \fI(since C++20)\fP + bool old ) noexcept; + void atomic_flag_wait_explicit( const atomic_flag* object, + bool old, std::memory_order order \fB(3)\fP \fI(since C++20)\fP + ) noexcept; + void atomic_flag_wait_explicit( const volatile atomic_flag* + object, \fB(4)\fP \fI(since C++20)\fP + bool old, std::memory_order order + ) noexcept; + + Performs atomic waiting operations. + + Compares object->test(std::memory_order_seq_cst) or object->test(order) with old, + and if they are equal then blocks until *object is notified by + std::atomic_flag::notify_one() or std::atomic_flag::notify_all() (or the thread is + unblocked spuriously). This is repeated until the values compare unequal. + + 1,2) The memory synchronization order is std::memory_order_seq_cst. + 3,4) The memory synchronization order is order. + If order is one of std::memory_order_release and std::memory_order_acq_rel, the + behavior is undefined. + + These functions are guaranteed to return only if value has changed, even if + underlying implementation unblocks spuriously. + +.SH Parameters + + object - pointer to the atomic flag to check and wait on + old - the value to check the atomic flag no longer contains + order - the memory synchronization ordering + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + + Due to the ABA problem, transient changes from old to another value and back to old + might be missed, and not unblock. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function of std::atomic_flag)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function of std::atomic_flag)\fP + atomic_flag_notify_one notifies a thread blocked in atomic_flag_wait + (C++20) \fI(function)\fP + atomic_flag_notify_all notifies all threads blocked in atomic_flag_wait + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_init.3 b/man/std::atomic_init.3 index 7cd4dd2c2..081229d4c 100644 --- a/man/std::atomic_init.3 +++ b/man/std::atomic_init.3 @@ -1,18 +1,30 @@ -.TH std::atomic_init 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_init 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_init \- std::atomic_init + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - void atomic_init( std::atomic* obj, T desired ); - template< class T > \fI(since C++11)\fP - void atomic_init( volatile std::atomic* obj, T desired ); + template< class T > + + void atomic_init \fI(since C++11)\fP + ( std::atomic* obj, \fB(1)\fP (deprecated in C++20) + + typename std::atomic::value_type desired ) + noexcept; + template< class T > - Initializes the default-constructed atomic object object with the value desired. The + void atomic_init \fI(since C++11)\fP + ( volatile std::atomic* obj, \fB(2)\fP (deprecated in C++20) + + typename std::atomic::value_type desired ) + noexcept; + + Initializes the default-constructed atomic object obj with the value desired. The function is not atomic: concurrent access from another thread, even through an atomic operation, is a data race. - If obj was not default-constructed, the behavior is undefined. - - If this function is called twice on the same obj, the behavior is undefined. + If obj was not default-constructed, or this function is called twice on the same + obj, the behavior is undefined. .SH Parameters @@ -23,12 +35,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes This function is provided for compatibility with C. If the compatibility is not @@ -39,16 +45,24 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj + .SH See also - ATOMIC_VAR_INIT constant initialization of an atomic variable of static storage - \fI(C++11)\fP duration - \fI(function macro)\fP - constructor constructs an atomic object - \fI(public member function of std::atomic)\fP + ATOMIC_VAR_INIT constant initialization of an atomic variable of static + \fI(C++11)\fP(deprecated in C++20) storage duration + \fI(function macro)\fP + constructor constructs an atomic object + \fI(public member function of std::atomic)\fP C documentation for atomic_init .SH Category: - * Todo no example diff --git a/man/std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE.3 b/man/std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE.3 index 18669b1a4..806f5861d 100644 --- a/man/std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE.3 +++ b/man/std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE.3 @@ -1,38 +1,35 @@ -.TH std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE \- std::atomic_is_lock_free,ATOMIC_xxx_LOCK_FREE + .SH Synopsis Defined in header - template< class Atomic > - bool atomic_is_lock_free( const volatile Atomic* - obj ) - template< class Atomic > - bool atomic_is_lock_free( const Atomic* obj ) - #define ATOMIC_CHAR_LOCK_FREE /* unspecified - */ - - #define ATOMIC_CHAR16_T_LOCK_FREE /* unspecified - */ - #define ATOMIC_CHAR32_T_LOCK_FREE /* unspecified - */ - #define ATOMIC_WCHAR_T_LOCK_FREE /* unspecified \fB(1)\fP \fI(since C++11)\fP - */ - #define ATOMIC_SHORT_LOCK_FREE /* unspecified \fB(2)\fP \fI(since C++11)\fP - */ - #define ATOMIC_INT_LOCK_FREE /* unspecified - */ - #define ATOMIC_LONG_LOCK_FREE /* unspecified - */ - #define ATOMIC_LLONG_LOCK_FREE /* unspecified - */ - - #define ATOMIC_POINTER_LOCK_FREE /* unspecified - */ - - 1) Determines if the atomic object pointed to by obj is implemented lock-free, as if - by calling obj->is_lock_free() - 2) Expands to an integer constant expression with value 0 for the built-in atomic - types that are never lock-free, to 1 for the built-in atomic types that are - sometimes lock-free, and to 2 for the built-in atomic types that are always - lock-free. + template< class T > + bool atomic_is_lock_free( const volatile std::atomic* obj ) \fB(1)\fP \fI(since C++11)\fP + noexcept; + template< class T > \fB(2)\fP \fI(since C++11)\fP + bool atomic_is_lock_free( const std::atomic* obj ) noexcept; + #define ATOMIC_BOOL_LOCK_FREE /* unspecified */ + + #define ATOMIC_CHAR_LOCK_FREE /* unspecified */ + #define ATOMIC_CHAR16_T_LOCK_FREE /* unspecified */ + #define ATOMIC_CHAR32_T_LOCK_FREE /* unspecified */ + #define ATOMIC_WCHAR_T_LOCK_FREE /* unspecified */ \fB(3)\fP \fI(since C++11)\fP + #define ATOMIC_SHORT_LOCK_FREE /* unspecified */ + #define ATOMIC_INT_LOCK_FREE /* unspecified */ + #define ATOMIC_LONG_LOCK_FREE /* unspecified */ + #define ATOMIC_LLONG_LOCK_FREE /* unspecified */ + + #define ATOMIC_POINTER_LOCK_FREE /* unspecified */ + #define ATOMIC_CHAR8_T_LOCK_FREE /* unspecified */ \fB(4)\fP \fI(since C++20)\fP + + 1,2) Determines if the atomic object pointed to by obj is implemented lock-free, as + if by calling obj->is_lock_free(). In any given program execution, the result of the + lock-free query is the same for all atomic objects of the same type. + 3,4) Expands to an integer constant expression with value + * 0 for the built-in atomic types that are never lock-free, + * 1 for the built-in atomic types that are sometimes lock-free, + * 2 for the built-in atomic types that are always lock-free. .SH Parameters @@ -42,38 +39,71 @@ true if *obj is a lock-free atomic, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes All atomic types except for std::atomic_flag may be implemented using mutexes or other locking operations, rather than using the lock-free atomic CPU instructions. - Atomic types are also allowed to be sometimes lock-free, e.g. if only aligned memory - accesses are naturally atomic on a given architecture, misaligned objects of the - same type have to use locks. If the type is sometimes lock-free, then the function - \fB(1)\fP or its member function equivalent has to be used to determine if the particular - instance is lock-free. + Atomic types are also allowed to be sometimes lock-free: for example, if only some + subarchitectures support lock-free atomic access for a given type (such as the + CMPXCHG16B instruction on x86-64), whether atomics are lock-free may not be known + until runtime. + + The C++ standard recommends (but does not require) that lock-free atomic operations + are also address-free, that is, suitable for communication between processes using + shared memory. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + + struct A { int a[100]; }; + struct B { int x, y; }; - checks if the atomic object is lock-free - is_lock_free \fI(public member function of std::atomic)\fP - - specializes atomic operations for - std::atomic_is_lock_free(std::shared_ptr) std::shared_ptr - \fI(function template)\fP - atomic_flag the lock-free boolean atomic type - \fI(C++11)\fP \fI(class)\fP + int main() + { + std::atomic a; + std::atomic b; + std::cout << std::boolalpha + << "std::atomic is lock free? " + << std::atomic_is_lock_free(&a) << '\\n' + << "std::atomic is lock free? " + << std::atomic_is_lock_free(&b) << '\\n'; + } -.SH Category: +.SH Possible output: + + std::atomic is lock free? false + std::atomic is lock free? true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + atomic_is_lock_free was specified via pointers, + LWG 3249 C++11 which specified via + was ambiguous and might accept invalid pointer atomic objects + values + +.SH See also - * Todo no example + is_lock_free checks if the atomic object is lock-free + \fI(public member function of std::atomic)\fP + atomic_flag the lock-free boolean atomic type + \fI(C++11)\fP \fI(class)\fP + is_always_lock_free indicates that the type is always lock-free + \fB[static]\fP \fI(C++17)\fP \fI(public static member constant of std::atomic)\fP + + std::atomic_is_lock_free(std::shared_ptr) specializes atomic operations for + (deprecated in C++20) std::shared_ptr + (removed in C++26) \fI(function template)\fP + C documentation for + atomic_is_lock_free + C documentation for + ATOMIC_*_LOCK_FREE diff --git a/man/std::atomic_load,std::atomic_load_explicit.3 b/man/std::atomic_load,std::atomic_load_explicit.3 index 85b7142f7..47ec21039 100644 --- a/man/std::atomic_load,std::atomic_load_explicit.3 +++ b/man/std::atomic_load,std::atomic_load_explicit.3 @@ -1,62 +1,54 @@ -.TH std::atomic_load,std::atomic_load_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_load,std::atomic_load_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_load,std::atomic_load_explicit \- std::atomic_load,std::atomic_load_explicit + .SH Synopsis Defined in header + template< class T > \fB(1)\fP \fI(since C++11)\fP + T atomic_load( const std::atomic* obj ) noexcept; + template< class T > \fB(2)\fP \fI(since C++11)\fP + T atomic_load( const volatile std::atomic* obj ) noexcept; template< class T > - T atomic_load( const std::atomic* obj ); - template< class T > - T atomic_load( const volatile std::atomic* - obj ); - template< class T > - T atomic_load_explicit( const std::atomic* - obj, - \fB(1)\fP \fI(since C++11)\fP - std::memory_order - order ); \fB(2)\fP \fI(since C++11)\fP + T atomic_load_explicit( const std::atomic* obj, \fB(3)\fP \fI(since C++11)\fP + + std::memory_order order ) noexcept; template< class T > - T atomic_load_explicit( const volatile - std::atomic* obj, + T atomic_load_explicit( const volatile std::atomic* obj, \fB(4)\fP \fI(since C++11)\fP - std::memory_order - order ); + std::memory_order order ) noexcept; - 1) Atomically obtains the value pointed to by obj as if by obj->load() - 2) Atomically obtains the value pointed to by obj as if by obj->load(order) + 1,2) Atomically obtains the value pointed to by obj as if by obj->load(). + 3,4) Atomically obtains the value pointed to by obj as if by obj->load(order). + If order is one of std::memory_order_release and std::memory_order_acq_rel, the + behavior is undefined. .SH Parameters obj - pointer to the atomic object to modify - the memory sycnhronization ordering for this operation: only - order - std::memory_order_relaxed, std::memory_order_consume, - std::memory_order_acquire and std::memory_order_seq_cst are permitted. + order - the memory synchronization ordering for this operation .SH Return value - The value that is held by the atomic object pointed to by obj - -.SH Exceptions - - noexcept specification: - noexcept - + The value that is held by the atomic object pointed to by obj. .SH See also - atomically obtains the value of the - load atomic object - \fI(C++11)\fP \fI(public member function of std::atomic)\fP - - atomic_store atomically replaces the value of the - atomic_store_explicit atomic object with a non-atomic argument - \fI(C++11)\fP \fI(function template)\fP + load atomically obtains the value of the atomic object + \fI(public member function of std::atomic)\fP + atomic_store atomically replaces the value of the atomic object with a + atomic_store_explicit non-atomic argument + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP - memory_order defines memory ordering constraints for - \fI(C++11)\fP the given atomic operation - \fI(typedef)\fP + memory_order defines memory ordering constraints for the given atomic + \fI(C++11)\fP operation + \fI(enum)\fP + std::atomic_load(std::shared_ptr) specializes atomic operations for std::atomic_load_explicit(std::shared_ptr) std::shared_ptr - \fI(function template)\fP + (deprecated in C++20) \fI(function template)\fP + (removed in C++26) C documentation for atomic_load, atomic_load_explicit diff --git a/man/std::atomic_notify_all.3 b/man/std::atomic_notify_all.3 new file mode 100644 index 000000000..d9ea8241a --- /dev/null +++ b/man/std::atomic_notify_all.3 @@ -0,0 +1,52 @@ +.TH std::atomic_notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_notify_all \- std::atomic_notify_all + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++20)\fP + void atomic_notify_all( std::atomic* object ); + template< class T > \fB(2)\fP \fI(since C++20)\fP + void atomic_notify_all( volatile std::atomic* object ); + + Performs atomic notifying operations. + + Unblocks all threads blocked in atomic waiting operations (i.e. std::atomic_wait(), + std::atomic_wait_explicit(), or std::atomic::wait()) on *object, if there are any; + otherwise does nothing. + + Equivalent to object->notify_all(). + +.SH Parameters + + object - pointer to the atomic object to notify + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function of std::atomic)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function of std::atomic)\fP + atomic_wait + atomic_wait_explicit blocks the thread until notified and the atomic value changes + (C++20) \fI(function template)\fP + (C++20) + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_notify_one.3 b/man/std::atomic_notify_one.3 new file mode 100644 index 000000000..855542ca2 --- /dev/null +++ b/man/std::atomic_notify_one.3 @@ -0,0 +1,52 @@ +.TH std::atomic_notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_notify_one \- std::atomic_notify_one + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++20)\fP + void atomic_notify_one( std::atomic* object ); + template< class T > \fB(2)\fP \fI(since C++20)\fP + void atomic_notify_one( volatile std::atomic* object ); + + Performs atomic notifying operations. + + If there is a thread blocked in atomic waiting operation (i.e. std::atomic_wait(), + std::atomic_wait_explicit(), or std::atomic::wait()) on *object, then unblocks at + least one such thread; otherwise does nothing. + + Equivalent to object->notify_one(). + +.SH Parameters + + object - pointer to the atomic object to notify + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function of std::atomic)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function of std::atomic)\fP + atomic_notify_all notifies all threads blocked in atomic_wait + (C++20) \fI(function template)\fP + atomic_wait + atomic_wait_explicit blocks the thread until notified and the atomic value changes + (C++20) \fI(function template)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref.3 b/man/std::atomic_ref.3 new file mode 100644 index 000000000..d77a9b669 --- /dev/null +++ b/man/std::atomic_ref.3 @@ -0,0 +1,176 @@ +.TH std::atomic_ref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref \- std::atomic_ref + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++20)\fP + struct atomic_ref; + template< class T > \fB(2)\fP \fI(since C++20)\fP + struct atomic_ref; + + The std::atomic_ref class template applies atomic operations to the object it + references. For the lifetime of the std::atomic_ref object, the object it references + is considered an atomic object. If one thread writes to an atomic object while + another thread reads from it, the behavior is well-defined (see memory model for + details on data races). In addition, accesses to atomic objects may establish + inter-thread synchronization and order non-atomic memory accesses as specified by + std::memory_order. + + The lifetime of an object must exceed the lifetime of all std::atomic_refs that + references the object. While any std::atomic_ref instance referencing an object + exists, the object must be exclusively accessed through these std::atomic_ref + instances. No subobject of an object referenced by an std::atomic_ref object may be + concurrently referenced by any other std::atomic_ref object. + + Atomic operations applied to an object through an std::atomic_ref are atomic with + respect to atomic operations applied through any other std::atomic_ref referencing + the same object. + + std::atomic_ref is CopyConstructible. + + Like language references, constness is shallow for std::atomic_ref - it is possible + to modify the referenced value through a const std::atomic_ref object. + +.SH Specializations + + Primary template + + The primary std::atomic_ref template may be instantiated with any TriviallyCopyable + type T (including bool): + + struct Counters { int a; int b; }; // user-defined trivially-copyable type + alignas(std::atomic_ref::required_alignment) Counters counter; + std::atomic_ref cnt(counter); // specialization for the user-defined type + + Partial specialization for pointer types + + The standard library provides partial specializations of the std::atomic_ref + template for all pointer types. In addition to the operations provided for all + atomic types, these specializations additionally support atomic arithmetic + operations appropriate to pointer types, such as fetch_add, fetch_sub. + + Specializations for integral types + + When instantiated with one of the following integral types, std::atomic_ref provides + additional atomic operations appropriate to integral types such as fetch_add, + fetch_sub, fetch_and, fetch_or, fetch_xor: + + * The character types char, char8_t, char16_t, char32_t, and wchar_t; + * The standard signed integer types: signed char, short, int, long, and long long; + * The standard unsigned integer types: unsigned char, unsigned short, unsigned + int, unsigned long, and unsigned long long; + * Any additional integral types needed by the typedefs in the header . + + Signed integer arithmetic is defined to use two's complement; there are no undefined + results. + + Specializations for floating-point types + + When instantiated with one of the cv-unqualified floating-point types (float, + double, long double + and cv-unqualified extended floating-point types + (since C++23)), std::atomic_ref provides additional atomic operations appropriate to + floating-point types such as fetch_add and fetch_sub. + + No operations result in undefined behavior even if the result is not representable + in the floating-point type. The floating-point environment in effect may be + different from the calling thread's floating-point environment. + +.SH Member types + + Member type Definition + value_type see below + value_type (only for atomic_ref and atomic_ref + difference_type specializations) + std::ptrdiff_t (only for std::atomic_ref specializations) + + For every std::atomic_ref (whether or not specialized), + std::atomic_ref::value_type is X. + + difference_type is not defined in the primary atomic_ref template. + +.SH Member functions + + constructor constructs an atomic_ref object + \fI(public member function)\fP + stores a value into the object referenced by an atomic_ref + operator= object + \fI(public member function)\fP + is_lock_free checks if the atomic_ref object is lock-free + \fI(public member function)\fP + atomically replaces the value of the referenced object with + store a non-atomic argument + \fI(public member function)\fP + load atomically obtains the value of the referenced object + \fI(public member function)\fP + operator T loads a value from the referenced object + \fI(public member function)\fP + atomically replaces the value of the referenced object and + exchange obtains the value held previously + \fI(public member function)\fP + atomically compares the value of the referenced object with + compare_exchange_weak non-atomic argument and performs atomic exchange if equal or + compare_exchange_strong atomic load if not + \fI(public member function)\fP + blocks the thread until notified and the atomic value + wait changes + \fI(public member function)\fP + notify_one notifies at least one thread waiting on the atomic object + \fI(public member function)\fP + notify_all notifies all threads blocked waiting on the atomic object + \fI(public member function)\fP +.SH Constants + is_always_lock_free indicates that the type is always lock-free + \fB[static]\fP \fI(public static member constant)\fP + required_alignment indicates the required alignment of an object to be + \fB[static]\fP referenced by atomic_ref + \fI(public static member constant)\fP + +.SH Specialized member functions + + Specialized for integral, floating-point and pointer types + atomically adds the argument to the value stored in the referenced + fetch_add object and obtains the value held previously + \fI(public member function)\fP + atomically subtracts the argument from the value stored in the + fetch_sub referenced object and obtains the value held previously + \fI(public member function)\fP + operator+= atomically adds to or subtracts from the referenced value + operator-= \fI(public member function)\fP + Specialized for integral and pointer types only + fetch_max atomically performs std::max between the argument and the value of + (C++26) the referenced object and obtains the value held previously + \fI(public member function)\fP + fetch_min atomically performs std::min between the argument and the value of + (C++26) the referenced object and obtains the value held previously + \fI(public member function)\fP + operator++ + operator++(int) atomically increments or decrements the referenced object by one + operator-- \fI(public member function)\fP + operator--(int) + Specialized for integral types only + atomically performs bitwise AND between the argument and the value + fetch_and of the referenced object and obtains the value held previously + \fI(public member function)\fP + atomically performs bitwise OR between the argument and the value of + fetch_or the referenced object and obtains the value held previously + \fI(public member function)\fP + atomically performs bitwise XOR between the argument and the value + fetch_xor of the referenced object and obtains the value held previously + \fI(public member function)\fP + operator&= atomically performs bitwise AND, OR, XOR with the referenced value + operator|= \fI(public member function)\fP + operator^= + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_ref 201806L (C++20) std::atomic_ref + +.SH See also + + atomic class template and specializations for bool, integral, + atomic floating-point, + \fI(C++11)\fP \fI(since C++20)\fP and pointer types + \fI(class template)\fP diff --git a/man/std::atomic_ref::atomic_ref.3 b/man/std::atomic_ref::atomic_ref.3 new file mode 100644 index 000000000..2eaa0c1e7 --- /dev/null +++ b/man/std::atomic_ref::atomic_ref.3 @@ -0,0 +1,73 @@ +.TH std::atomic_ref::atomic_ref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::atomic_ref \- std::atomic_ref::atomic_ref + +.SH Synopsis + explicit atomic_ref( T& obj ); \fB(1)\fP \fI(since C++20)\fP + atomic_ref( const atomic_ref& ref ) noexcept; \fB(2)\fP \fI(since C++20)\fP + + Constructs a new atomic_ref object. + + 1) Constructs an atomic_ref object referencing the object obj. The behavior is + undefined if obj is not aligned to required_alignment. + 2) Constructs an atomic_ref object referencing the object referenced by ref. + +.SH Parameters + + obj - object to reference + ref - another atomic_ref object to copy from + +.SH Example + + The program increments the values in a container using several threads. Then the + final sum is printed. Non-atomic access may "loss" the results of some operations + due to data-races. + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using Data = std::vector; + + auto inc_atomically = [](Data& data) + { + for (Data::value_type& x : data) + { + auto xx = std::atomic_ref(x); + ++xx; // atomic read-modify-write + } + }; + + auto inc_directly = [](Data& data) + { + for (Data::value_type& x : data) + ++x; + }; + + auto test_run = [](const auto Fun) + { + Data data(10'000'000); + { + std::jthread j1{Fun, std::ref(data)}; + std::jthread j2{Fun, std::ref(data)}; + std::jthread j3{Fun, std::ref(data)}; + std::jthread j4{Fun, std::ref(data)}; + } + std::cout << "sum = " << std::accumulate(cbegin(data), cend(data), 0) << '\\n'; + }; + + test_run(inc_atomically); + test_run(inc_directly); + } + +.SH Possible output: + + sum = 40000000 + sum = 39994973 diff --git a/man/std::atomic_ref::compare_exchange_weak,std::atomic_ref::compare_exchange_strong.3 b/man/std::atomic_ref::compare_exchange_weak,std::atomic_ref::compare_exchange_strong.3 new file mode 100644 index 000000000..2ca8d5bab --- /dev/null +++ b/man/std::atomic_ref::compare_exchange_weak,std::atomic_ref::compare_exchange_strong.3 @@ -0,0 +1,86 @@ +.TH std::atomic_ref::compare_exchange_weak,std::atomic_ref::compare_exchange_strong 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::compare_exchange_weak,std::atomic_ref::compare_exchange_strong \- std::atomic_ref::compare_exchange_weak,std::atomic_ref::compare_exchange_strong + +.SH Synopsis + bool compare_exchange_weak( T& expected, T desired, + + std::memory_order success, \fB(1)\fP \fI(since C++20)\fP + + std::memory_order failure ) const + noexcept; + bool compare_exchange_weak( T& expected, T desired, + + std::memory_order order = \fB(2)\fP \fI(since C++20)\fP + + std::memory_order_seq_cst ) const + noexcept; + bool compare_exchange_strong( T& expected, T desired, + + std::memory_order success, \fB(3)\fP \fI(since C++20)\fP + + std::memory_order failure ) const + noexcept; + bool compare_exchange_strong( T& expected, T desired, + + std::memory_order order = \fB(4)\fP \fI(since C++20)\fP + + std::memory_order_seq_cst ) + const noexcept; + + Atomically compares the value representation of the referenced object with that of + expected, and if those are bitwise-equal, replaces the former with desired (performs + a read-modify-write operation). Otherwise, loads the actual value stored in the + referenced object into expected (performs a load operation). + + The memory models for the read-modify-write and load operations are success and + failure respectively. In the \fB(2)\fP and \fB(4)\fP versions order is used for both + read-modify-write and load operations, except that std::memory_order_acquire and + std::memory_order_relaxed are used for the load operation if order == + std::memory_order_acq_rel, or order == std::memory_order_release respectively. + +.SH Parameters + + expected - reference to the value expected to be found in the object referenced by + the atomic_ref object + desired - the value to store in the referenced object if it is as expected + success - the memory synchronization ordering for the read-modify-write operation + if the comparison succeeds. All values are permitted + the memory synchronization ordering for the load operation if the + failure - comparison fails. Cannot be std::memory_order_release or + std::memory_order_acq_rel + order - the memory synchronization ordering for both operations + +.SH Return value + + true if the referenced object was successfully changed, false otherwise. + +.SH Notes + + The comparison and copying are bitwise (similar to std::memcmp and std::memcpy); no + constructor, assignment operator, or comparison operator are used. + + The weak forms (1,2) of the functions are allowed to fail spuriously, that is, act + as if *this != expected even if they are equal. When a compare-and-exchange is in a + loop, the weak version will yield better performance on some platforms. + + When a weak compare-and-exchange would require a loop and a strong one would not, + the strong one is preferable unless the object representation of T may include trap + bits, or offers multiple object representations for the same value (e.g. + floating-point NaN). In those cases, weak compare-and-exchange typically works + because it quickly converges on some stable object representation. + + For a union with bits that participate in the value representations of some members + but not the others, compare-and-exchange might always fail because such padding bits + have indeterminate values when they do not participate in the value representation + of the active member. + + Padding bits that never participate in an object's value representation are ignored. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::exchange.3 b/man/std::atomic_ref::exchange.3 new file mode 100644 index 000000000..f656d661b --- /dev/null +++ b/man/std::atomic_ref::exchange.3 @@ -0,0 +1,20 @@ +.TH std::atomic_ref::exchange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::exchange \- std::atomic_ref::exchange + +.SH Synopsis + T exchange( T desired, std::memory_order order = \fI(since C++20)\fP + std::memory_order_seq_cst ) const noexcept; + + Atomically replaces the value of the referenced object with desired. The operation + is a read-modify-write operation. Memory is affected according to the value of + order. + +.SH Parameters + + desired - value to assign + order - memory order constraints to enforce + +.SH Return value + + The value of the referenced object before the call. diff --git a/man/std::atomic_ref::fetch_add.3 b/man/std::atomic_ref::fetch_add.3 new file mode 100644 index 000000000..d5ca5094f --- /dev/null +++ b/man/std::atomic_ref::fetch_add.3 @@ -0,0 +1,48 @@ +.TH std::atomic_ref::fetch_add 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_add \- std::atomic_ref::fetch_add + +.SH Synopsis + member only of atomic_ref and atomic_ref + template specializations + T fetch_add( T arg, + std::memory_order order = std::memory_order_seq_cst ) \fB(1)\fP \fI(since C++20)\fP + const noexcept; + member only of atomic_ref template specialization + T* fetch_add( std::ptrdiff_t arg, + std::memory_order order = std::memory_order_seq_cst \fB(2)\fP \fI(since C++20)\fP + ) const noexcept; + + Atomically replaces the current value of the referenced object with the result of + arithmetic addition of the value and arg. This operation is a read-modify-write + operation. Memory is affected according to the value of order. + + For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + + For floating-point types, the floating-point environment in effect may be different + from the calling thread's floating-point environment. The operation need not be + conform to the corresponding std::numeric_limits traits but is encouraged to do so. + If the result is not a representable value for its type, the result is unspecified + but the operation otherwise has no undefined behavior. + + For T* types, the result may be an undefined address, but the operation otherwise + has no undefined behavior. The program is ill-formed if T is not an object type. + +.SH Parameters + + arg - the other argument of arithmetic addition + order - memory order constraints to enforce + +.SH Return value + + The value of the referenced object, immediately preceding the effects of this + function. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::fetch_and.3 b/man/std::atomic_ref::fetch_and.3 new file mode 100644 index 000000000..161f1b78e --- /dev/null +++ b/man/std::atomic_ref::fetch_and.3 @@ -0,0 +1,23 @@ +.TH std::atomic_ref::fetch_and 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_and \- std::atomic_ref::fetch_and + +.SH Synopsis + member only of atomic_ref specializations + T fetch_and( T arg, + std::memory_order order = std::memory_order_seq_cst ) \fI(since C++20)\fP + const noexcept; + + Atomically replaces the current value of the referenced object with the result of + bitwise AND of the value and arg. This operation is a read-modify-write operation. + Memory is affected according to the value of order. + +.SH Parameters + + arg - the other argument of bitwise AND + order - memory order constraints to enforce + +.SH Return value + + The value of the referenced object, immediately preceding the effects of this + function. diff --git a/man/std::atomic_ref::fetch_max.3 b/man/std::atomic_ref::fetch_max.3 new file mode 100644 index 000000000..34cec0959 --- /dev/null +++ b/man/std::atomic_ref::fetch_max.3 @@ -0,0 +1,44 @@ +.TH std::atomic_ref::fetch_max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_max \- std::atomic_ref::fetch_max + +.SH Synopsis + member only of atomic_ref specializations + T fetch_max( T arg, std::memory_order order = + std::memory_order_seq_cst ) const \fB(1)\fP (since C++26) + noexcept; + member only of atomic_ref partial specialization + T* fetch_max( T* arg, std::memory_order order = + std::memory_order_seq_cst ) const \fB(2)\fP (since C++26) + noexcept; + + Atomically replaces the current value of the referenced object with the result of + std::max of the value and arg. That is, it performs atomic maximum operation. The + operation is a read-modify-write operation. Memory is affected according to the + value of order. + + 2) If the pointers point to different complete objects (or subobjects thereof), + pointer comparison does not establish a strict weak ordering. + +.SH Parameters + + arg - the other argument of std::max + order - memory order constraints to enforce + +.SH Return value + + The value immediately preceding the effects of this function in the modification + order of *this. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_min_max 202403L (C++26) Atomic minimum/maximum + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::fetch_min.3 b/man/std::atomic_ref::fetch_min.3 new file mode 100644 index 000000000..aba2f5e06 --- /dev/null +++ b/man/std::atomic_ref::fetch_min.3 @@ -0,0 +1,44 @@ +.TH std::atomic_ref::fetch_min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_min \- std::atomic_ref::fetch_min + +.SH Synopsis + member only of atomic_ref specializations + T fetch_min( T arg, std::memory_order order = + std::memory_order_seq_cst ) const \fB(1)\fP (since C++26) + noexcept; + member only of atomic_ref partial specialization + T* fetch_min( T* arg, std::memory_order order = + std::memory_order_seq_cst ) const \fB(2)\fP (since C++26) + noexcept; + + Atomically replaces the current value of the referenced object with the result of + std::min of the value and arg. That is, it performs atomic minimum operation. The + operation is a read-modify-write operation. Memory is affected according to the + value of order. + + 2) If the pointers point to different complete objects (or subobjects thereof), + pointer comparison does not establish a strict weak ordering. + +.SH Parameters + + arg - the other argument of std::min + order - memory order constraints to enforce + +.SH Return value + + The value immediately preceding the effects of this function in the modification + order of *this. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_atomic_min_max 202403L (C++26) Atomic minimum/maximum + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::fetch_or.3 b/man/std::atomic_ref::fetch_or.3 new file mode 100644 index 000000000..f24a8e6b7 --- /dev/null +++ b/man/std::atomic_ref::fetch_or.3 @@ -0,0 +1,23 @@ +.TH std::atomic_ref::fetch_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_or \- std::atomic_ref::fetch_or + +.SH Synopsis + member only of atomic_ref specializations + T fetch_or( T arg, + std::memory_order order = std::memory_order_seq_cst ) \fI(since C++20)\fP + const noexcept; + + Atomically replaces the current value of the referenced object with the result of + bitwise OR of the value and arg. This operation is a read-modify-write operation. + Memory is affected according to the value of order. + +.SH Parameters + + arg - the other argument of bitwise OR + order - memory order constraints to enforce + +.SH Return value + + The value of the referenced object, immediately preceding the effects of this + function. diff --git a/man/std::atomic_ref::fetch_sub.3 b/man/std::atomic_ref::fetch_sub.3 new file mode 100644 index 000000000..5ea8ebf09 --- /dev/null +++ b/man/std::atomic_ref::fetch_sub.3 @@ -0,0 +1,48 @@ +.TH std::atomic_ref::fetch_sub 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_sub \- std::atomic_ref::fetch_sub + +.SH Synopsis + member only of atomic_ref and atomic_ref + template specializations + T fetch_sub( T arg, + std::memory_order order = std::memory_order_seq_cst ) \fB(1)\fP \fI(since C++20)\fP + const noexcept; + member only of atomic_ref template specialization + T* fetch_sub( std::ptrdiff_t arg, + std::memory_order order = std::memory_order_seq_cst \fB(2)\fP \fI(since C++20)\fP + ) const noexcept; + + Atomically replaces the current value of the referenced object with the result of + arithmetic subtraction of the value and arg. This operation is a read-modify-write + operation. Memory is affected according to the value of order. + + For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + + For floating-point types, the floating-point environment in effect may be different + from the calling thread's floating-point environment. The operation need not be + conform to the corresponding std::numeric_limits traits but is encouraged to do so. + If the result is not a representable value for its type, the result is unspecified + but the operation otherwise has no undefined behavior. + + For T* types, the result may be an undefined address, but the operation otherwise + has no undefined behavior. The program is ill-formed if T is not an object type. + +.SH Parameters + + arg - the other argument of arithmetic subtraction + order - memory order constraints to enforce + +.SH Return value + + The value of the referenced object, immediately preceding the effects of this + function. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::fetch_xor.3 b/man/std::atomic_ref::fetch_xor.3 new file mode 100644 index 000000000..e76673bfe --- /dev/null +++ b/man/std::atomic_ref::fetch_xor.3 @@ -0,0 +1,23 @@ +.TH std::atomic_ref::fetch_xor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::fetch_xor \- std::atomic_ref::fetch_xor + +.SH Synopsis + member only of atomic_ref specializations + T fetch_xor( T arg, + std::memory_order order = std::memory_order_seq_cst ) \fI(since C++20)\fP + const noexcept; + + Atomically replaces the current value of the referenced object with the result of + bitwise XOR of the value and arg. This operation is a read-modify-write operation. + Memory is affected according to the value of order. + +.SH Parameters + + arg - the other argument of bitwise XOR + order - memory order constraints to enforce + +.SH Return value + + The value of the referenced object, immediately preceding the effects of this + function. diff --git a/man/std::atomic_ref::is_always_lock_free.3 b/man/std::atomic_ref::is_always_lock_free.3 new file mode 100644 index 000000000..86c85f249 --- /dev/null +++ b/man/std::atomic_ref::is_always_lock_free.3 @@ -0,0 +1,18 @@ +.TH std::atomic_ref::is_always_lock_free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::is_always_lock_free \- std::atomic_ref::is_always_lock_free + +.SH Synopsis + static constexpr bool is_always_lock_free = \fI(since C++20)\fP + /*implementation-defined*/; + + Equals true if the operations on this atomic_ref type is always lock-free and false + if it is never or sometimes lock-free. + + The value of this constant is consistent with the result of member function + is_lock_free. + +.SH See also + + is_lock_free checks if the atomic_ref object is lock-free + \fI(public member function)\fP diff --git a/man/std::atomic_ref::is_lock_free.3 b/man/std::atomic_ref::is_lock_free.3 new file mode 100644 index 000000000..c62b28400 --- /dev/null +++ b/man/std::atomic_ref::is_lock_free.3 @@ -0,0 +1,41 @@ +.TH std::atomic_ref::is_lock_free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::is_lock_free \- std::atomic_ref::is_lock_free + +.SH Synopsis + bool is_lock_free() const noexcept; \fI(since C++20)\fP + + Checks whether the atomic operations on this object are lock-free. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the atomic operations on this object are lock-free, false otherwise. + +.SH Notes + + All atomic types except for std::atomic_flag may be implemented using mutexes or + other locking operations, rather than using the lock-free atomic CPU instructions. + Atomic types are also allowed to be sometimes lock-free, e.g. if only aligned memory + accesses are naturally atomic on a given architecture, misaligned objects of the + same type have to use locks. + + The C++ standard recommends (but does not require) that lock-free atomic operations + are also address-free, that is, suitable for communication between processes using + shared memory. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_always_lock_free indicates that the type is always lock-free + \fB[static]\fP \fI(public static member constant)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::load.3 b/man/std::atomic_ref::load.3 new file mode 100644 index 000000000..cbc01b925 --- /dev/null +++ b/man/std::atomic_ref::load.3 @@ -0,0 +1,27 @@ +.TH std::atomic_ref::load 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::load \- std::atomic_ref::load + +.SH Synopsis + T load( std::memory_order order = std::memory_order_seq_cst ) const \fI(since C++20)\fP + noexcept; + + Atomically loads and returns the current value of the referenced object. Memory is + affected according to the value of order. + + order must be one of std::memory_order_relaxed, std::memory_order_consume, + std::memory_order_acquire or std::memory_order_seq_cst. Otherwise the behavior is + undefined. + +.SH Parameters + + order - memory order constraints to enforce + +.SH Return value + + The current value of the referenced object. + +.SH See also + + operator T loads a value from the referenced object + \fI(public member function)\fP diff --git a/man/std::atomic_ref::notify_all.3 b/man/std::atomic_ref::notify_all.3 new file mode 100644 index 000000000..b8559c30b --- /dev/null +++ b/man/std::atomic_ref::notify_all.3 @@ -0,0 +1,40 @@ +.TH std::atomic_ref::notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::notify_all \- std::atomic_ref::notify_all + +.SH Synopsis + void notify_all() const noexcept; \fB(1)\fP \fI(since C++20)\fP + void notify_all() const volatile noexcept; \fB(2)\fP \fI(since C++20)\fP + + Performs atomic notifying operations. + + Unblocks all threads blocked in atomic waiting operations (i.e. wait()) on *this, if + there are any; otherwise does nothing. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value changes + \fI(public member function)\fP + atomic_wait + atomic_wait_explicit blocks the thread until notified and the atomic value changes + (C++20) \fI(function template)\fP + (C++20) + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::notify_one.3 b/man/std::atomic_ref::notify_one.3 new file mode 100644 index 000000000..d9c0a677d --- /dev/null +++ b/man/std::atomic_ref::notify_one.3 @@ -0,0 +1,40 @@ +.TH std::atomic_ref::notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::notify_one \- std::atomic_ref::notify_one + +.SH Synopsis + void notify_one() const noexcept; \fB(1)\fP \fI(since C++20)\fP + void notify_one() const volatile noexcept; \fB(2)\fP \fI(since C++20)\fP + + Performs atomic notifying operations. + + If there is a thread blocked in atomic waiting operation (i.e. wait()) on *this, + then unblocks at least one such thread; otherwise does nothing. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value changes + \fI(public member function)\fP + atomic_wait + atomic_wait_explicit blocks the thread until notified and the atomic value changes + (C++20) \fI(function template)\fP + (C++20) + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::operator&=,|=,^=.3 b/man/std::atomic_ref::operator&=,|=,^=.3 new file mode 100644 index 000000000..9a51fa82a --- /dev/null +++ b/man/std::atomic_ref::operator&=,|=,^=.3 @@ -0,0 +1,62 @@ +.TH std::atomic_ref::operator&=,|=,^= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::operator&=,|=,^= \- std::atomic_ref::operator&=,|=,^= + +.SH Synopsis + member only of atomic_ref specializations + T operator&=( T arg ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + T operator|=( T arg ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + T operator^=( T arg ) const noexcept; \fB(3)\fP \fI(since C++20)\fP + + Atomically replaces the current value of the referenced object with the result of + computation involving the previous value and arg. These operations are + read-modify-write operations. + + * operator&= performs atomic bitwise AND. Equivalent to return fetch_and(arg) & + arg;. + * operator!= performs atomic bitwise OR. Equivalent to return fetch_or(arg) | + arg;. + * operator^= performs atomic bitwise XOR. Equivalent to return fetch_xor(arg) ^ + arg;. + +.SH Parameters + + arg - the argument for the arithmetic operation + +.SH Return value + + The resulting value (that is, the result of applying the corresponding binary + operator to the value immediately preceding the effects of the corresponding member + function). + +.SH Notes + + Unlike most compound assignment operators, the compound assignment operators for + atomic_ref do not return a reference to their left-hand arguments. They return a + copy of the stored value instead. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + atomically performs bitwise AND between the argument and the value + fetch_and of the referenced object and obtains the value held previously + \fI(public member function)\fP + atomically performs bitwise OR between the argument and the value of + fetch_or the referenced object and obtains the value held previously + \fI(public member function)\fP + atomically performs bitwise XOR between the argument and the value + fetch_xor of the referenced object and obtains the value held previously + \fI(public member function)\fP + operator++ + operator++(int) atomically increments or decrements the referenced object by one + operator-- \fI(public member function)\fP + operator--(int) + operator+= atomically adds to or subtracts from the referenced value + operator-= \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::operator++,++(int),--,--(int).3 b/man/std::atomic_ref::operator++,++(int),--,--(int).3 new file mode 100644 index 000000000..aa5c446f4 --- /dev/null +++ b/man/std::atomic_ref::operator++,++(int),--,--(int).3 @@ -0,0 +1,50 @@ +.TH std::atomic_ref::operator++,++(int),--,--(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::operator++,++(int),--,--(int) \- std::atomic_ref::operator++,++(int),--,--(int) + +.SH Synopsis + member of atomic_ref specializations + and atomic_ref partial specialization + value_type operator++() const noexcept; \fB(1)\fP \fI(since C++20)\fP + value_type operator++( int ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + value_type operator--() const noexcept; \fB(3)\fP \fI(since C++20)\fP + value_type operator--( int ) const noexcept; \fB(4)\fP \fI(since C++20)\fP + + Atomically increments or decrements the current value of the referenced object. + These operations are read-modify-write operations. + + 1) Performs atomic pre-increment. Equivalent to return fetch_add\fB(1)\fP + 1;. + 2) Performs atomic post-increment. Equivalent to return fetch_add\fB(1)\fP;. + 3) Performs atomic pre-decrement. Equivalent to return fetch_sub\fB(1)\fP - 1; + 4) Performs atomic post-decrement. Equivalent to return fetch_sub\fB(1)\fP;. + + For signed Integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + + For T* types, the result may be an undefined address, but the operations otherwise + have no undefined behavior. The program is ill-formed if T is not an object type. + +.SH Return value + + 1,3) The value of the referenced object after the modification. + 2,4) The value of the referenced object before the modification. + +.SH Notes + + Unlike most pre-increment and pre-decrement operators, the pre-increment and + pre-decrement operators for atomic_ref do not return a reference to the modified + object. They return a copy of the stored value instead. + +.SH See also + + atomically adds the argument to the value stored in the referenced object + fetch_add and obtains the value held previously + \fI(public member function)\fP + atomically subtracts the argument from the value stored in the referenced + fetch_sub object and obtains the value held previously + \fI(public member function)\fP + operator+= atomically adds to or subtracts from the referenced value + operator-= \fI(public member function)\fP + operator&= atomically performs bitwise AND, OR, XOR with the referenced value + operator|= \fI(public member function)\fP + operator^= diff --git a/man/std::atomic_ref::operator+=,-=.3 b/man/std::atomic_ref::operator+=,-=.3 new file mode 100644 index 000000000..94eb02773 --- /dev/null +++ b/man/std::atomic_ref::operator+=,-=.3 @@ -0,0 +1,69 @@ +.TH std::atomic_ref::operator+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::operator+=,-= \- std::atomic_ref::operator+=,-= + +.SH Synopsis + member only of atomic_ref and atomic_ref + specializations + T operator+=( T arg ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + T operator-=( T arg ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + member only of atomic_ref partial specialization + T* operator+=( std::ptrdiff_t arg ) const noexcept; \fB(3)\fP \fI(since C++20)\fP + T* operator-=( std::ptrdiff_t arg ) const noexcept; \fB(4)\fP \fI(since C++20)\fP + + Atomically replaces the current value of the referenced object with the result of + computation involving the previous value and arg. These operations are + read-modify-write operations. + + * operator+= performs atomic addition. Equivalent to return fetch_add(arg) + arg;. + * operator-= performs atomic subtraction. Equivalent to return fetch_sub(arg) - + arg;. + 1,2) For signed integral types, arithmetic is defined to use two’s complement + representation. There are no undefined results. + For floating-point types, the floating-point environment in effect may be different + from the calling thread's floating-point environment. The operation need not be + conform to the corresponding std::numeric_limits traits but is encouraged to do so. + If the result is not a representable value for its type, the result is unspecified + but the operation otherwise has no undefined behavior. + 3,4) The result may be an undefined address, but the operations otherwise have no + undefined behavior. The program is ill-formed if T is not an object type. + +.SH Parameters + + arg - the argument for the arithmetic operation + +.SH Return value + + The resulting value (that is, the result of applying the corresponding binary + operator to the value immediately preceding the effects of the corresponding member + function). + +.SH Notes + + Unlike most compound assignment operators, the compound assignment operators for + atomic_ref do not return a reference to their left-hand arguments. They return a + copy of the stored value instead. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + atomically adds the argument to the value stored in the referenced + fetch_add object and obtains the value held previously + \fI(public member function)\fP + atomically subtracts the argument from the value stored in the + fetch_sub referenced object and obtains the value held previously + \fI(public member function)\fP + operator++ + operator++(int) atomically increments or decrements the referenced object by one + operator-- \fI(public member function)\fP + operator--(int) + operator&= atomically performs bitwise AND, OR, XOR with the referenced value + operator|= \fI(public member function)\fP + operator^= + +.SH Category: + * Todo no example diff --git a/man/std::atomic_ref::operator=.3 b/man/std::atomic_ref::operator=.3 new file mode 100644 index 000000000..0d31ac374 --- /dev/null +++ b/man/std::atomic_ref::operator=.3 @@ -0,0 +1,30 @@ +.TH std::atomic_ref::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::operator= \- std::atomic_ref::operator= + +.SH Synopsis + T operator=( T desired ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + atomic_ref& operator=( const atomic_ref& ) = delete; \fB(2)\fP \fI(since C++20)\fP + + 1) Atomically assigns a value desired to the referenced object. Equivalent to + store(desired). + 2) atomic_ref is not CopyAssignable. + +.SH Parameters + + desired - value to assign + +.SH Return value + + desired + +.SH Notes + + Unlike most assignment operators, the assignment operator for atomic_ref does not + return a reference to its left-hand argument. It returns a copy of the stored value + instead. + +.SH See also + + constructor constructs an atomic_ref object + \fI(public member function)\fP diff --git a/man/std::atomic_ref::operatorT.3 b/man/std::atomic_ref::operatorT.3 new file mode 100644 index 000000000..f92c0ca91 --- /dev/null +++ b/man/std::atomic_ref::operatorT.3 @@ -0,0 +1,22 @@ +.TH std::atomic_ref::operatorT 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::operatorT \- std::atomic_ref::operatorT + +.SH Synopsis + operator T() const noexcept; \fI(since C++20)\fP + + Atomically loads and returns the current value of the referenced object. Equivalent + to load(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current value of the referenced object. + +.SH See also + + load atomically obtains the value of the referenced object + \fI(public member function)\fP diff --git a/man/std::atomic_ref::required_alignment.3 b/man/std::atomic_ref::required_alignment.3 new file mode 100644 index 000000000..a86f0af67 --- /dev/null +++ b/man/std::atomic_ref::required_alignment.3 @@ -0,0 +1,16 @@ +.TH std::atomic_ref::required_alignment 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::required_alignment \- std::atomic_ref::required_alignment + +.SH Synopsis + static constexpr std::size_t required_alignment = \fI(since C++20)\fP + /*implementation-defined*/; + + The value of required_alignment is the required alignment for an object to be + referenced by an atomic reference, which is at least alignof(T). + +.SH Notes + + Hardware could require that an object to be referenced by an atomic_ref have + stricter alignment than other T objects, and whether operations on an atomic_ref are + lock-free can depend on the alignment of the referenced object. diff --git a/man/std::atomic_ref::store.3 b/man/std::atomic_ref::store.3 new file mode 100644 index 000000000..e1f3bb9cf --- /dev/null +++ b/man/std::atomic_ref::store.3 @@ -0,0 +1,27 @@ +.TH std::atomic_ref::store 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::store \- std::atomic_ref::store + +.SH Synopsis + void store( T desired, std::memory_order order = \fI(since C++20)\fP + std::memory_order_seq_cst ) const noexcept; + + Atomically replaces the current value of the referenced object with desired. Memory + is affected according to the value of order. + + order must be one of std::memory_order_relaxed, std::memory_order_release or + std::memory_order_seq_cst. Otherwise the behavior is undefined. + +.SH Parameters + + desired - the value to store into the referenced object + order - memory order constraints to enforce + +.SH Return value + + \fI(none)\fP + +.SH See also + + operator= stores a value into the object referenced by an atomic_ref object + \fI(public member function)\fP diff --git a/man/std::atomic_ref::wait.3 b/man/std::atomic_ref::wait.3 new file mode 100644 index 000000000..8e7315dcf --- /dev/null +++ b/man/std::atomic_ref::wait.3 @@ -0,0 +1,63 @@ +.TH std::atomic_ref::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_ref::wait \- std::atomic_ref::wait + +.SH Synopsis + void wait( T old, std::memory_order order = \fB(1)\fP \fI(since C++20)\fP + std::memory_order::seq_cst ) const noexcept; + void wait( T old, std::memory_order order = + std::memory_order::seq_cst ) const volatile \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Performs atomic waiting operations. Behaves as if it repeatedly performs the + following steps: + + * Compare the value representation of this->load(order) with that of old. + * If those are equal, then blocks until *this is notified by notify_one() or + notify_all(), or the thread is unblocked spuriously. + * Otherwise, returns. + + These functions are guaranteed to return only if value has changed, even if + underlying implementation unblocks spuriously. + + If order is one of std::memory_order::release and std::memory_order::acq_rel, the + behavior is undefined. + +.SH Parameters + + old - the value to check the atomic_ref's object no longer contains + order - memory order constraints to enforce + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + + Due to the ABA problem, transient changes from old to another value and back to old + might be missed, and not unblock. + + The comparison is bitwise (similar to std::memcmp); no comparison operator is used. + Padding bits that never participate in an object's value representation are ignored. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + notify_one notifies at least one thread waiting on the atomic object + \fI(public member function)\fP + notify_all notifies all threads blocked waiting on the atomic object + \fI(public member function)\fP + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + atomic_notify_all notifies all threads blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::atomic_signal_fence.3 b/man/std::atomic_signal_fence.3 index 230cf9d31..4538eecaf 100644 --- a/man/std::atomic_signal_fence.3 +++ b/man/std::atomic_signal_fence.3 @@ -1,15 +1,20 @@ -.TH std::atomic_signal_fence 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_signal_fence 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_signal_fence \- std::atomic_signal_fence + .SH Synopsis Defined in header - extern "C" void atomic_signal_fence( std::memory_order order ); \fI(since C++11)\fP + extern "C" void atomic_signal_fence( std::memory_order order ) \fI(since C++11)\fP + noexcept; Establishes memory synchronization ordering of non-atomic and relaxed atomic accesses, as instructed by order, between a thread and a signal handler executed on the same thread. This is equivalent to std::atomic_thread_fence, except no CPU instructions for memory ordering are issued. Only reordering of the instructions by - the compiler is suppressed as order instructs. For example, writes cannot be moved - past a fence with release semantics and reads cannot be moved ahead of a fence with - acquire semantics. + the compiler is suppressed as order instructs. For example, a fence with release + semantics prevents reads or writes from being moved past subsequent writes and a + fence with acquire semantics prevents reads or writes from being moved ahead of + preceding reads. .SH Parameters @@ -19,12 +24,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -34,12 +33,11 @@ memory_order defines memory ordering constraints for the given atomic \fI(C++11)\fP operation - \fI(typedef)\fP + \fI(enum)\fP atomic_thread_fence generic memory order-dependent fence synchronization primitive - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP C documentation for atomic_signal_fence .SH Category: - * Todo no example diff --git a/man/std::atomic_store,std::atomic_store_explicit.3 b/man/std::atomic_store,std::atomic_store_explicit.3 index 31f518e85..04395a6e4 100644 --- a/man/std::atomic_store,std::atomic_store_explicit.3 +++ b/man/std::atomic_store,std::atomic_store_explicit.3 @@ -1,66 +1,79 @@ -.TH std::atomic_store,std::atomic_store_explicit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_store,std::atomic_store_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_store,std::atomic_store_explicit \- std::atomic_store,std::atomic_store_explicit + .SH Synopsis Defined in header template< class T > - void atomic_store( std::atomic* obj, T desr - ); + + void atomic_store( std::atomic* obj, \fB(1)\fP \fI(since C++11)\fP + + typename std::atomic::value_type desired ) + noexcept; template< class T > - void atomic_store( volatile std::atomic* - obj, T desr ); + + void atomic_store( volatile std::atomic* obj, \fB(2)\fP \fI(since C++11)\fP + + typename std::atomic::value_type desired ) + noexcept; template< class T > - void atomic_store_explicit( std::atomic* - obj, T desr, \fB(1)\fP \fI(since C++11)\fP + void atomic_store_explicit( std::atomic* obj, + typename std::atomic::value_type \fB(3)\fP \fI(since C++11)\fP + desired, - std::memory_order - order); \fB(2)\fP \fI(since C++11)\fP + std::memory_order order) noexcept; template< class T > - void atomic_store_explicit( volatile - std::atomic* obj, T desr, + void atomic_store_explicit( volatile std::atomic* obj, + typename std::atomic::value_type \fB(4)\fP \fI(since C++11)\fP + desired, - std::memory_order - order); + std::memory_order order) noexcept; - 1) Atomically replaces the value pointed to by obj with the value of desr as if by - obj->store(desr) - 2) Atomically replaces the value pointed to by obj with the value of desr as if by - obj->store(desr, order) + 1,2) Atomically replaces the value pointed to by obj with the value of desired as if + by obj->store(desired). + 3,4) Atomically replaces the value pointed to by obj with the value of desired as if + by obj->store(desired, order). + If order is one of std::memory_order_consume, std::memory_order_acquire and + std::memory_order_acq_rel, the behavior is undefined. .SH Parameters - obj - pointer to the atomic object to modify - desr - the value to store in the atomic object - the memory synchronization ordering for this operation: only - order - std::memory_order_relaxed, std::memory_order_release and - std::memory_order_seq_cst are permitted. + obj - pointer to the atomic object to modify + desired - the value to store in the atomic object + order - the memory synchronization ordering .SH Return value - none. + \fI(none)\fP + + Defect reports -.SH Exceptions + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + P0558R1 C++11 exact type match was required because T is only deduced + T was deduced from multiple arguments from obj .SH See also - atomically replaces the value of the - store atomic object with a non-atomic argument - \fI(C++11)\fP \fI(public member function of std::atomic)\fP - - atomic_load atomically obtains the value stored in - atomic_load_explicit an atomic object - \fI(C++11)\fP \fI(function template)\fP + atomically replaces the value of the atomic object with a + store non-atomic argument + \fI(public member function of std::atomic)\fP + atomic_load + atomic_load_explicit atomically obtains the value stored in an atomic object + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP - memory_order defines memory ordering constraints for - \fI(C++11)\fP the given atomic operation - \fI(typedef)\fP + memory_order defines memory ordering constraints for the given atomic + \fI(C++11)\fP operation + \fI(enum)\fP + std::atomic_store(std::shared_ptr) specializes atomic operations for std::atomic_store_explicit(std::shared_ptr) std::shared_ptr - \fI(function template)\fP + (deprecated in C++20) \fI(function template)\fP + (removed in C++26) C documentation for atomic_store, atomic_store_explicit diff --git a/man/std::atomic_thread_fence.3 b/man/std::atomic_thread_fence.3 index 6b4a22bcf..9dfeb8ebf 100644 --- a/man/std::atomic_thread_fence.3 +++ b/man/std::atomic_thread_fence.3 @@ -1,14 +1,16 @@ -.TH std::atomic_thread_fence 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::atomic_thread_fence 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_thread_fence \- std::atomic_thread_fence + .SH Synopsis Defined in header - extern "C" void atomic_thread_fence( std::memory_order order ); \fI(since C++11)\fP + extern "C" void atomic_thread_fence( std::memory_order order ) \fI(since C++11)\fP + noexcept; Establishes memory synchronization ordering of non-atomic and relaxed atomic - accesses, as instructed by order, without an associated atomic operation. For - example, all non-atomic and relaxed atomic stores that happen before a - std::memory_order_release fence in thread A will be synchronized with non-atomic and - relaxed atomic loads from the same locations made in thread B after an - std::memory_order_acquire fence. + accesses, as instructed by order, without an associated atomic operation. Note + however, that at least one atomic operation is required to set up the + synchronization, as described below. .SH Parameters @@ -18,50 +20,91 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes + On x86 (including x86-64), atomic_thread_fence functions issue no CPU instructions + and only affect compile-time code motion, except for + std::atomic_thread_fence(std::memory_order::seq_cst). + atomic_thread_fence imposes stronger synchronization constraints than an atomic store operation with the same std::memory_order. While an atomic store-release - operation prevents all preceding writes from moving past the store-release, an - atomic_thread_fence with memory_order_release ordering prevents all preceding writes - from moving past all subsequent stores. + operation prevents all preceding reads and writes from moving past the + store-release, an atomic_thread_fence with memory_order_release ordering prevents + all preceding reads and writes from moving past all subsequent stores. -.SH Examples + Fence-fence synchronization can be used to add synchronization to a sequence of + several relaxed atomic operations, for example: - Scan an array of mailboxes, and process only the ones intended for us, without - unnecessary synchronization. + // Global + std::string computation(int); + void print(std::string); + + std::atomic arr[3] = {-1, -1, -1}; + std::string data[1000]; //non-atomic data - -// Run this code + // Thread A, compute 3 values. + void ThreadA(int v0, int v1, int v2) + { + // assert(0 <= v0, v1, v2 < 1000); + data[v0] = computation(v0); + data[v1] = computation(v1); + data[v2] = computation(v2); + std::atomic_thread_fence(std::memory_order_release); + std::atomic_store_explicit(&arr[0], v0, std::memory_order_relaxed); + std::atomic_store_explicit(&arr[1], v1, std::memory_order_relaxed); + std::atomic_store_explicit(&arr[2], v2, std::memory_order_relaxed); + } + + // Thread B, prints between 0 and 3 values already computed. + void ThreadB() + { + int v0 = std::atomic_load_explicit(&arr[0], std::memory_order_relaxed); + int v1 = std::atomic_load_explicit(&arr[1], std::memory_order_relaxed); + int v2 = std::atomic_load_explicit(&arr[2], std::memory_order_relaxed); + std::atomic_thread_fence(std::memory_order_acquire); + // v0, v1, v2 might turn out to be -1, some or all of them. + // Otherwise it is safe to read the non-atomic data because of the fences: + if (v0 != -1) + print(data[v0]); + if (v1 != -1) + print(data[v1]); + if (v2 != -1) + print(data[v2]); + } + +.SH Example + + Scan an array of mailboxes, and process only the ones intended for us, without + unnecessary synchronization. This example uses atomic-fence synchronization. const int num_mailboxes = 32; - std::atomic mailbox[num_mailboxes]; - - // The writer threads update non-atomic shared data and then update mailbox[i] as follows - std::atomic_store_explicit(&mailbox[i], std::memory_order_release); - - // Reader thread needs to check all mailbox[i], but only needs to sync with one - for (int i = 0; i < num_mailboxes; ++i) { - if (std::atomic_load_explicit(&mailbox[i], std::memory_order_relaxed) == my_id) { - std::atomic_thread_fence(std::memory_order_acquire); // synchronize with just one writer - do_work(i); // guaranteed to observe everything done in the writer thread before - // the atomic_store_explicit() + std::atomic mailbox_receiver[num_mailboxes]; + std::string mailbox_data[num_mailboxes]; + + // The writer threads update non-atomic shared data + // and then update mailbox_receiver[i] as follows: + mailbox_data[i] = ...; + std::atomic_store_explicit(&mailbox_receiver[i], receiver_id, std::memory_order_release); + + // Reader thread needs to check all mailbox[i], but only needs to sync with one. + for (int i = 0; i < num_mailboxes; ++i) + if (std::atomic_load_explicit(&mailbox_receiver[i], + std::memory_order_relaxed) == my_id) + { + // synchronize with just one writer + std::atomic_thread_fence(std::memory_order_acquire); + // guaranteed to observe everything done in the writer thread + // before the atomic_store_explicit() + do_work(mailbox_data[i]); } - } .SH See also memory_order defines memory ordering constraints for the given atomic \fI(C++11)\fP operation - \fI(typedef)\fP + \fI(enum)\fP atomic_signal_fence fence between a thread and a signal handler executed in the same \fI(C++11)\fP thread - \fI(function)\fP + \fI(function)\fP C documentation for atomic_thread_fence diff --git a/man/std::atomic_wait,std::atomic_wait_explicit.3 b/man/std::atomic_wait,std::atomic_wait_explicit.3 new file mode 100644 index 000000000..823ffc226 --- /dev/null +++ b/man/std::atomic_wait,std::atomic_wait_explicit.3 @@ -0,0 +1,89 @@ +.TH std::atomic_wait,std::atomic_wait_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::atomic_wait,std::atomic_wait_explicit \- std::atomic_wait,std::atomic_wait_explicit + +.SH Synopsis + template< class T > + + void atomic_wait( const std::atomic* object, \fB(1)\fP \fI(since C++20)\fP + + typename std::atomic::value_type old ); + template< class T > + + void atomic_wait( const volatile std::atomic* object, \fB(2)\fP \fI(since C++20)\fP + + typename std::atomic::value_type old ); + template< class T > + + void atomic_wait_explicit( const std::atomic* object, + typename std::atomic::value_type \fB(3)\fP \fI(since C++20)\fP + old, + + std::memory_order order ); + template< class T > + + void atomic_wait_explicit( const volatile std::atomic* object, + typename std::atomic::value_type \fB(4)\fP \fI(since C++20)\fP + old, + + std::memory_order order ); + + Performs atomic waiting operations. Behaves as if it repeatedly performs the + following steps: + + * Compare the value representation of object->load() (for overloads (1,2)) or + object->load(order) (for overloads (3,4)) with that of old. + * If those are bitwise equal, then blocks until *object is notified by + std::atomic::notify_one() or std::atomic::notify_all(), or the thread is + unblocked spuriously. + * Otherwise, returns. + + These functions are guaranteed to return only if value has changed, even if the + underlying implementation unblocks spuriously. + + 1,2) Equivalent to object->wait(old). + 3,4) Equivalent to object->wait(old, order). + If order is one of std::memory_order::release and std::memory_order::acq_rel, the + behavior is undefined. + +.SH Parameters + + object - pointer to the atomic object to check and wait on + old - the value to check the atomic object no longer contains + order - the memory synchronization ordering + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This form of change-detection is often more efficient than simple polling or pure + spinlocks. + + Due to the ABA problem, transient changes from old to another value and back to old + might be missed, and not unblock. + + The comparison is bitwise (similar to std::memcmp); no comparison operator is used. + Padding bits that never participate in an object's value representation are ignored. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wait blocks the thread until notified and the atomic value changes + (C++20) \fI(public member function of std::atomic)\fP + notify_one notifies at least one thread waiting on the atomic object + (C++20) \fI(public member function of std::atomic)\fP + notify_all notifies all threads blocked waiting on the atomic object + (C++20) \fI(public member function of std::atomic)\fP + atomic_notify_one notifies a thread blocked in atomic_wait + (C++20) \fI(function template)\fP + atomic_notify_all notifies all threads blocked in atomic_wait + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::auto_ptr.3 b/man/std::auto_ptr.3 index 227ff352b..fb57251c9 100644 --- a/man/std::auto_ptr.3 +++ b/man/std::auto_ptr.3 @@ -1,20 +1,26 @@ -.TH std::auto_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr \- std::auto_ptr + .SH Synopsis Defined in header - template< class T > class auto_ptr; \fB(1)\fP \fB(deprecated)\fP - template<> class auto_ptr \fB(2)\fP \fB(deprecated)\fP + template< class T > class auto_ptr; \fB(1)\fP (deprecated in C++11) + (removed in C++17) + template<> class auto_ptr; \fB(2)\fP (deprecated in C++11) + (removed in C++17) - auto_ptr is a smart pointer that manages an object obtained via new and deletes that - object when auto_ptr itself is destroyed. It may be used to provide exception safety - for dynamically-allocated objects, for passing ownership of dynamically-allocated - objects into functions and for returning dynamically-allocated objects from - functions. + auto_ptr is a smart pointer that manages an object obtained via new expression and + deletes that object when auto_ptr itself is destroyed. It may be used to provide + exception safety for dynamically allocated objects, for passing ownership of + dynamically allocated objects into functions and for returning dynamically allocated + objects from functions. Copying an auto_ptr copies the pointer and transfers ownership to the destination: - both copy construction and copy assignment of auto_ptr modify their right hand + both copy construction and copy assignment of auto_ptr modify their right-hand arguments, and the "copy" is not equal to the original. Because of these unusual - copy semantics, auto_ptr may not be placed in standard containers. std::unique_ptr - is preferred for this and other uses. + copy semantics, auto_ptr may not be placed in standard containers. + std::unique_ptr is preferred for this and other uses. + \fI(since C++11)\fP 2) Specialization for type void is provided, it declares the typedef element_type, but no member functions. @@ -32,21 +38,21 @@ .SH Member functions - constructor creates a new auto_ptr - \fI(public member function)\fP - destructor destroys an auto_ptr and the managed object - \fI(public member function)\fP - operator= transfers ownership from another auto_ptr - \fI(public member function)\fP - operator auto_ptr converts the managed pointer to a pointer to different type - \fI(public member function)\fP + constructor creates a new auto_ptr + \fI(public member function)\fP + destructor destroys an auto_ptr and the managed object + \fI(public member function)\fP + operator= transfers ownership from another auto_ptr + \fI(public member function)\fP + operator auto_ptr converts the managed pointer to a pointer to different type + operator auto_ptr_ref \fI(public member function)\fP .SH Observers - get obtains a pointer to the managed object - \fI(public member function)\fP - operator* accesses the managed object - operator-> \fI(public member function)\fP + get returns a pointer to the managed object + \fI(public member function)\fP + operator* accesses the managed object + operator-> \fI(public member function)\fP .SH Modifiers - reset destroys the managed object - \fI(public member function)\fP - release releases ownership of the managed object - \fI(public member function)\fP + reset replaces the managed object + \fI(public member function)\fP + release releases ownership of the managed object + \fI(public member function)\fP diff --git a/man/std::auto_ptr::auto_ptr.3 b/man/std::auto_ptr::auto_ptr.3 index c6f8e829e..5c00c15e6 100644 --- a/man/std::auto_ptr::auto_ptr.3 +++ b/man/std::auto_ptr::auto_ptr.3 @@ -1,11 +1,16 @@ -.TH std::auto_ptr::auto_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::auto_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::auto_ptr \- std::auto_ptr::auto_ptr + .SH Synopsis - explicit auto_ptr( X* p = 0 ); \fB(1)\fP \fB(deprecated)\fP - auto_ptr( auto_ptr& r ); \fB(2)\fP \fB(deprecated)\fP - template< class Y > \fB(3)\fP \fB(deprecated)\fP - auto_ptr( auto_ptr& r ); - template< class Y > \fB(3)\fP \fB(deprecated)\fP - auto_ptr( auto_ptr_ref m ); + explicit auto_ptr( X* p = 0 ) throw(); \fB(1)\fP (deprecated in C++11) + (removed in C++17) + auto_ptr( auto_ptr& r ) throw(); \fB(2)\fP (deprecated in C++11) + (removed in C++17) + template< class Y > \fB(3)\fP (deprecated in C++11) + auto_ptr( auto_ptr& r ) throw(); (removed in C++17) + auto_ptr( auto_ptr_ref m ) throw(); \fB(4)\fP (deprecated in C++11) + (removed in C++17) Constructs the auto_ptr from a pointer that refers to the object to manage. @@ -17,8 +22,9 @@ to by m. p.release() is called for the auto_ptr p that m holds to acquire the ownership of the object. auto_ptr_ref is an implementation-defined type that holds a reference to auto_ptr. - The implementation is allowed to provide the template with a different name or - implement equivalent functionality in other ways. + std::auto_ptr is implicitly convertible to and assignable from this type. The + implementation is allowed to provide the template with a different name or implement + equivalent functionality in other ways. .SH Parameters @@ -26,6 +32,12 @@ r - another auto_ptr to transfer the ownership of the object from m - an implementation-defined type that holds a reference to auto_ptr -.SH Exceptions +.SH Notes - \fI(none)\fP + The constructor and the copy assignment operator from auto_ptr_ref is provided to + allow copy-constructing and assigning std::auto_ptr from nameless temporaries. Since + its copy constructor and copy assignment operator take the argument as non-const + reference, they cannot bind rvalue arguments directly. However, a user-defined + conversion can be executed (which releases the original auto_ptr), followed by a + call to the constructor or copy-assignment operator that take auto_ptr_ref by value. + This is an early implementation of move semantics. diff --git a/man/std::auto_ptr::get.3 b/man/std::auto_ptr::get.3 index e60c8b3a2..32138027d 100644 --- a/man/std::auto_ptr::get.3 +++ b/man/std::auto_ptr::get.3 @@ -1,6 +1,10 @@ -.TH std::auto_ptr::get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::get \- std::auto_ptr::get + .SH Synopsis - T* get() const; \fB(deprecated)\fP + T* get() const throw(); (deprecated in C++11) + (removed in C++17) Returns the pointer that is held by *this. @@ -12,11 +16,7 @@ The pointer held by *this. -.SH Exceptions - - \fI(none)\fP - .SH See also operator* accesses the managed object - operator-> \fI(public member function)\fP + operator-> \fI(public member function)\fP diff --git a/man/std::auto_ptr::operator*,std::auto_ptr::operator->.3 b/man/std::auto_ptr::operator*,std::auto_ptr::operator->.3 index e52529229..abc1ab50f 100644 --- a/man/std::auto_ptr::operator*,std::auto_ptr::operator->.3 +++ b/man/std::auto_ptr::operator*,std::auto_ptr::operator->.3 @@ -1,7 +1,12 @@ -.TH std::auto_ptr::operator*,std::auto_ptr::operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::operator*,std::auto_ptr::operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::operator*,std::auto_ptr::operator-> \- std::auto_ptr::operator*,std::auto_ptr::operator-> + .SH Synopsis - T& operator*() const; \fB(1)\fP \fB(deprecated)\fP - T* operator->() const; \fB(2)\fP \fB(deprecated)\fP + T& operator*() const throw(); \fB(1)\fP (deprecated in C++11) + (removed in C++17) + T* operator->() const throw(); \fB(2)\fP (deprecated in C++11) + (removed in C++17) Dereferences a pointer to the managed object. The first version requires get() != 0. @@ -14,11 +19,7 @@ 1) *get(). 2) get(). -.SH Exceptions - - \fI(none)\fP - .SH See also - get obtains a pointer to the managed object - \fI(public member function)\fP + get returns a pointer to the managed object + \fI(public member function)\fP diff --git a/man/std::auto_ptr::operator=.3 b/man/std::auto_ptr::operator=.3 index 843cc07ab..5f924f684 100644 --- a/man/std::auto_ptr::operator=.3 +++ b/man/std::auto_ptr::operator=.3 @@ -1,28 +1,47 @@ -.TH std::auto_ptr::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::operator= \- std::auto_ptr::operator= + .SH Synopsis - auto_ptr& operator=( auto_ptr& r ); \fB(1)\fP \fB(deprecated)\fP - template< class Y > \fB(2)\fP \fB(deprecated)\fP - auto_ptr& operator=( auto_ptr& r ); - auto_ptr& operator=( auto_ptr_ref m ); \fB(3)\fP \fB(deprecated)\fP + auto_ptr& operator=( auto_ptr& r ) throw(); \fB(1)\fP (deprecated in C++11) + (removed in C++17) + template< class Y > \fB(2)\fP (deprecated in C++11) + auto_ptr& operator=( auto_ptr& r ) throw(); (removed in C++17) + auto_ptr& operator=( auto_ptr_ref m ) throw(); \fB(3)\fP (deprecated in C++11) + (removed in C++17) - Replaces the managed object with the one managed by r. + Replaces the managed object with the one managed by r or m. 1) Effectively calls reset(r.release()). 2) Effectively calls reset(r.release()). Y* must be implicitly convertible to T*. 3) Effectively calls reset(m.release()). auto_ptr_ref is an implementation-defined - type that holds a reference to auto_ptr. The implementation is allowed to provide - the template with a different name or implement equivalent functionality in other - ways. + type that holds a reference to auto_ptr. std::auto_ptr is implicitly convertible to + and from this type. The implementation is allowed to provide the template with a + different name or implement equivalent functionality in other ways. .SH Parameters r - another auto_ptr to transfer the ownership of the object from - m - an implementation-defined type that holds a reference to auto_ptr + m - an object of implementation-defined type that holds a reference to auto_ptr .SH Return value *this. -.SH Exceptions +.SH Notes + + The constructor and the copy assignment operator from auto_ptr_ref is provided to + allow copy-constructing and assigning std::auto_ptr from nameless temporaries. Since + its copy constructor and copy assignment operator take the argument as non-const + reference, they cannot bind rvalue arguments directly. However, a user-defined + conversion can be executed (which releases the original auto_ptr), followed by a + call to the constructor or copy-assignment operator that take auto_ptr_ref by value. + This is an early implementation of move semantics. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP + DR Applied to Behavior as published Correct behavior + LWG 127 C++98 auto_ptr was not assignable from auto_ptr_ref added overload \fB(3)\fP diff --git a/man/std::auto_ptr::operatorauto_ptr.3 b/man/std::auto_ptr::operatorauto_ptr.3 new file mode 100644 index 000000000..a76e72b5e --- /dev/null +++ b/man/std::auto_ptr::operatorauto_ptr.3 @@ -0,0 +1,36 @@ +.TH std::auto_ptr::operatorauto_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::operatorauto_ptr \- std::auto_ptr::operatorauto_ptr + +.SH Synopsis + template< class Y > \fB(1)\fP (deprecated in C++11) + operator auto_ptr_ref() throw(); (removed in C++17) + template< class Y > \fB(2)\fP (deprecated in C++11) + operator auto_ptr() throw(); (removed in C++17) + + Converts *this to an auto_ptr for a different type Y. + + 1) Returns an implementation-defined type that holds a reference to *this. + std::auto_ptr is convertible and assignable from this template. The implementation + is allowed to provide the template with a different name or implement equivalent + functionality in other ways. + 2) Constructs a new auto_ptr with a pointer obtained by calling release(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) An implementation-defined type that holds a reference to *this. + 2) An auto_ptr with a pointer obtained by calling release(). + +.SH Notes + + The constructor and the copy assignment operator from auto_ptr_ref is provided to + allow copy-constructing and assigning std::auto_ptr from nameless temporaries. Since + its copy constructor and copy assignment operator take the argument as non-const + reference, they cannot bind rvalue arguments directly. However, a user-defined + conversion \fB(1)\fP or \fB(2)\fP can be executed (which releases the original auto_ptr), + followed by a call to the constructor or copy-assignment operator that take + auto_ptr_ref by value. This is an early implementation of move semantics. diff --git a/man/std::auto_ptr::operatorauto_ptr.3 b/man/std::auto_ptr::operatorauto_ptr.3 deleted file mode 100644 index ebe7c6e47..000000000 --- a/man/std::auto_ptr::operatorauto_ptr.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::auto_ptr::operatorauto_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class Y > \fB(1)\fP \fB(deprecated)\fP - operator auto_ptr_ref(); - template< class Y > \fB(2)\fP \fB(deprecated)\fP - operator auto_ptr(); - - Converts *this to an auto_ptr for a different type Y. - - 1) Returns an implementation-defined type that holds a reference to *this. The - implementation is allowed to provide the template with a different name or implement - equivalent functionality in other ways. - 2) Constructs a new auto_ptr with a pointer obtained by calling release(). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - 1) An implementation-defined type that holds a reference to *this - 2) A auto_ptr with a pointer obtained by calling release(). - -.SH Exceptions - - \fI(none)\fP diff --git a/man/std::auto_ptr::release.3 b/man/std::auto_ptr::release.3 index 81eef17bf..cbf2e5e4f 100644 --- a/man/std::auto_ptr::release.3 +++ b/man/std::auto_ptr::release.3 @@ -1,6 +1,10 @@ -.TH std::auto_ptr::release 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::release \- std::auto_ptr::release + .SH Synopsis - T* release(); \fB(deprecated)\fP + T* release() throw(); (deprecated in C++11) + (removed in C++17) Releases the held pointer. After the call *this holds the null pointer. @@ -12,11 +16,7 @@ get(). -.SH Exceptions - - \fI(none)\fP - .SH See also - reset destroys the managed object - \fI(public member function)\fP + reset replaces the managed object + \fI(public member function)\fP diff --git a/man/std::auto_ptr::reset.3 b/man/std::auto_ptr::reset.3 index d68f7ed50..87f399b07 100644 --- a/man/std::auto_ptr::reset.3 +++ b/man/std::auto_ptr::reset.3 @@ -1,6 +1,10 @@ -.TH std::auto_ptr::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::reset \- std::auto_ptr::reset + .SH Synopsis - void reset( T* p = 0 ); \fB(deprecated)\fP + void reset( T* p = 0 ) throw(); (deprecated in C++11) + (removed in C++17) Replaces the held pointer by p. If the currently held pointer is not null pointer, delete get() is called. @@ -13,11 +17,7 @@ \fI(none)\fP -.SH Exceptions - - \fI(none)\fP - .SH See also release releases ownership of the managed object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::auto_ptr::~auto_ptr.3 b/man/std::auto_ptr::~auto_ptr.3 index 1e51cbf1b..e11efc139 100644 --- a/man/std::auto_ptr::~auto_ptr.3 +++ b/man/std::auto_ptr::~auto_ptr.3 @@ -1,5 +1,9 @@ -.TH std::auto_ptr::~auto_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::auto_ptr::~auto_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::auto_ptr::~auto_ptr \- std::auto_ptr::~auto_ptr + .SH Synopsis - ~auto_ptr() \fB(deprecated)\fP + ~auto_ptr() throw(); (deprecated in C++11) + (removed in C++17) Destroys the managed object. Calls delete get(). diff --git a/man/std::back_insert_iterator.3 b/man/std::back_insert_iterator.3 index 2a905c439..5be623620 100644 --- a/man/std::back_insert_iterator.3 +++ b/man/std::back_insert_iterator.3 @@ -1,64 +1,76 @@ -.TH std::back_insert_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::back_insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::back_insert_iterator \- std::back_insert_iterator + .SH Synopsis Defined in header template< class Container > - class back_insert_iterator : public std::iterator< std::output_iterator_tag, + class back_insert_iterator \fI(until C++17)\fP - void, void, void, void > + : public std::iterator + template< class Container > \fI(since C++17)\fP + class back_insert_iterator; - std::back_insert_iterator is an OutputIterator that appends to a container for which - it was constructed. The container's push_back() member function is called whenever - the iterator (whether dereferenced or not) is assigned to. Incrementing the - std::back_insert_iterator is a no-op. + std::back_insert_iterator is a LegacyOutputIterator that appends elements to a + container for which it was constructed. The container's push_back() member function + is called whenever the iterator (whether dereferenced or not) is assigned to. + Incrementing the std::back_insert_iterator is a no-op. .SH Member types - Member type Definition - container_type Container + Member type Definition + iterator_category std::output_iterator_tag + value_type void + difference_type void \fI(until C++20)\fP + std::ptrdiff_t \fI(since C++20)\fP + pointer void + reference void + container_type Container + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. .SH Member functions constructor constructs a new back_insert_iterator - \fI(public member function)\fP + \fI(public member function)\fP operator= inserts an object into the associated container - \fI(public member function)\fP + \fI(public member function)\fP operator* no-op - \fI(public member function)\fP + \fI(public member function)\fP operator++ no-op - operator++(int) \fI(public member function)\fP + operator++(int) \fI(public member function)\fP .SH Member objects Member name Definition container (protected) a pointer of type Container* -Inherited from std::iterator - -.SH Member types - - Member type Definition - value_type void - difference_type void - pointer void - reference void - iterator_category std::output_iterator_tag - .SH Example - + // Run this code + #include #include #include - #include - #include - + #include + int main() { std::vector v; - std::generate_n(std::back_insert_iterator>(v), // can be simplified - 10, [](){ return std::rand() % 10; }); // with std::back_inserter + + std::generate_n( + std::back_insert_iterator>(v), + // Or use std::back_inserter helper + // Or use std::back_insert_iterator(v) C++17's syntax + 10, + [n = 0]() mutable { return ++n; } + ); + for (int n : v) std::cout << n << ' '; std::cout << '\\n'; @@ -66,14 +78,14 @@ Inherited from std::iterator .SH Output: - 3 6 7 5 3 5 6 2 9 1 + 1 2 3 4 5 6 7 8 9 10 .SH See also creates a std::back_insert_iterator of type inferred from the back_inserter argument - \fI(function template)\fP + \fI(function template)\fP front_insert_iterator iterator adaptor for insertion at the front of a container - \fI(class template)\fP + \fI(class template)\fP insert_iterator iterator adaptor for insertion into a container - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::back_insert_iterator::back_insert_iterator.3 b/man/std::back_insert_iterator::back_insert_iterator.3 index e3a16f408..7e1260221 100644 --- a/man/std::back_insert_iterator::back_insert_iterator.3 +++ b/man/std::back_insert_iterator::back_insert_iterator.3 @@ -1,9 +1,23 @@ -.TH std::back_insert_iterator::back_insert_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::back_insert_iterator::back_insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::back_insert_iterator::back_insert_iterator \- std::back_insert_iterator::back_insert_iterator + .SH Synopsis - explicit back_insert_iterator( Container& c ); + explicit back_insert_iterator( Container& c ); \fI(until C++20)\fP + constexpr explicit back_insert_iterator( Container& c ); \fI(since C++20)\fP - Initializes the underlying pointer to the container to &c . + Initializes the underlying pointer to the container to std::addressof(c). .SH Parameters c - container to initialize the inserter with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + default constructor was provided as removed along with the + P2325R3 C++20 C++20 requirement + iterators must be default_initializable diff --git a/man/std::back_insert_iterator::operator*.3 b/man/std::back_insert_iterator::operator*.3 index 5b6858e1c..948ca1db9 100644 --- a/man/std::back_insert_iterator::operator*.3 +++ b/man/std::back_insert_iterator::operator*.3 @@ -1,9 +1,13 @@ -.TH std::back_insert_iterator::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::back_insert_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::back_insert_iterator::operator* \- std::back_insert_iterator::operator* + .SH Synopsis - back_insert_iterator& operator*(); + back_insert_iterator& operator*(); \fI(until C++20)\fP + constexpr back_insert_iterator& operator*(); \fI(since C++20)\fP Does nothing, this member function is provided to satisfy the requirements of - OutputIterator. + LegacyOutputIterator. It returns the iterator itself, which makes it possible to use code such as *iter = value to output (insert) the value into the underlying container. diff --git a/man/std::back_insert_iterator::operator++.3 b/man/std::back_insert_iterator::operator++.3 index 374fdc45b..834ac2e80 100644 --- a/man/std::back_insert_iterator::operator++.3 +++ b/man/std::back_insert_iterator::operator++.3 @@ -1,10 +1,15 @@ -.TH std::back_insert_iterator::operator++ 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::back_insert_iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::back_insert_iterator::operator++ \- std::back_insert_iterator::operator++ + .SH Synopsis - back_insert_iterator& operator++(); - back_insert_iterator& operator++( int ); + back_insert_iterator& operator++(); \fI(until C++20)\fP + constexpr back_insert_iterator& operator++(); \fI(since C++20)\fP + back_insert_iterator operator++( int ); \fI(until C++20)\fP + constexpr back_insert_iterator operator++( int ); \fI(since C++20)\fP Does nothing. These operator overloads are provided to satisfy the requirements of - OutputIterator. They make it possible for the expressions *iter++=value and + LegacyOutputIterator. They make it possible for the expressions *iter++=value and *++iter=value to be used to output (insert) a value into the underlying container. .SH Parameters diff --git a/man/std::back_insert_iterator::operator=.3 b/man/std::back_insert_iterator::operator=.3 index 0f5ab1cd2..16ff51262 100644 --- a/man/std::back_insert_iterator::operator=.3 +++ b/man/std::back_insert_iterator::operator=.3 @@ -1,14 +1,28 @@ -.TH std::back_insert_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::back_insert_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::back_insert_iterator::operator= \- std::back_insert_iterator::operator= + .SH Synopsis - back_insert_iterator& \fB(1)\fP - operator=( const typename Container::value_type& value ); - back_insert_iterator& \fB(2)\fP - operator=( typename Container::value_type&& value ); + back_insert_iterator& + operator=( typename \fI(until C++11)\fP + Container::const_reference value ); + back_insert_iterator& \fI(since C++11)\fP + operator=( const typename \fI(until C++20)\fP + Container::value_type& value ); + constexpr back_insert_iterator& + operator=( const typename \fB(1)\fP \fI(since C++20)\fP + Container::value_type& value ); + back_insert_iterator& \fI(since C++11)\fP + operator=( typename Container::value_type&& \fI(until C++20)\fP + value ); \fB(2)\fP + constexpr back_insert_iterator& + operator=( typename Container::value_type&& \fI(since C++20)\fP + value ); Inserts the given value value to the container. - 1) Results in container->push_back(value) - 2) Results in container->push_back(std::move(value)) + 1) Results in container->push_back(value). + 2) Results in container->push_back(std::move(value)). .SH Parameters @@ -20,8 +34,26 @@ .SH Example - This section is incomplete -.SH Category: +// Run this code + + #include + #include + #include + + int main() + { + std::deque q; + std::back_insert_iterator> it(q); + + for (int i = 0; i < 10; ++i) + it = i; // calls q.push_back(i) + + for (auto& elem : q) + std::cout << elem << ' '; + std::cout << '\\n'; + } + +.SH Output: - * Todo without reason + 0 1 2 3 4 5 6 7 8 9 diff --git a/man/std::back_inserter.3 b/man/std::back_inserter.3 index 84db81030..113a32d3c 100644 --- a/man/std::back_inserter.3 +++ b/man/std::back_inserter.3 @@ -1,8 +1,12 @@ -.TH std::back_inserter 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::back_inserter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::back_inserter \- std::back_inserter + .SH Synopsis Defined in header - template< class Container > - std::back_insert_iterator back_inserter( Container& c ); + template< class Container > (constexpr since + std::back_insert_iterator back_inserter( Container& c C++20) + ); back_inserter is a convenience function template that constructs a std::back_insert_iterator for the container c with the type deduced from the type of @@ -15,32 +19,33 @@ .SH Return value A std::back_insert_iterator which can be used to add elements to the end of the - container c + container c. .SH Possible implementation - template< class Container > - std::back_insert_iterator back_inserter( Container& c ) + template + std::back_insert_iterator back_inserter(Container& c) { return std::back_insert_iterator(c); } .SH Example - + // Run this code - #include - #include #include + #include #include - + #include + int main() { std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; std::fill_n(std::back_inserter(v), 3, -1); for (int n : v) std::cout << n << ' '; + std::cout << '\\n'; } .SH Output: @@ -50,10 +55,10 @@ .SH See also back_insert_iterator iterator adaptor for insertion at the end of a container - \fI(class template)\fP + \fI(class template)\fP creates a std::front_insert_iterator of type inferred from the front_inserter argument - \fI(function template)\fP + \fI(function template)\fP creates a std::insert_iterator of type inferred from the inserter argument - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::bad_alloc.3 b/man/std::bad_alloc.3 index dc1f198de..f39710850 100644 --- a/man/std::bad_alloc.3 +++ b/man/std::bad_alloc.3 @@ -1,67 +1,69 @@ -.TH std::bad_alloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_alloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_alloc \- std::bad_alloc + .SH Synopsis Defined in header - class bad_alloc : public std::exception; + class bad_alloc; std::bad_alloc is the type of the object thrown as exceptions by the allocation functions to report failure to allocate storage. std-bad alloc-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the bad_alloc object + constructor constructs a new bad_alloc object \fI(public member function)\fP - operator= replaces a bad_alloc object + operator= replaces the bad_alloc object \fI(public member function)\fP - what returns explanatory string + what returns the explanatory string \fI(public member function)\fP - std::bad_alloc::bad_alloc +std::bad_alloc::bad_alloc - bad_alloc(); + bad_alloc() throw(); \fI(until C++11)\fP + bad_alloc() noexcept; \fB(1)\fP \fI(since C++11)\fP + bad_alloc( const bad_alloc& other ) throw(); \fB(2)\fP \fI(until C++11)\fP + bad_alloc( const bad_alloc& other ) noexcept; \fI(since C++11)\fP - Constructs new bad_alloc object with an implementation-defined null-terminated byte - string which is accessible through what(). + Constructs a new bad_alloc object with an implementation-defined null-terminated + byte string which is accessible through what(). -.SH Parameters + 1) Default constructor. + 2) Copy constructor. + If *this and other both have dynamic type std::bad_alloc then std::strcmp(what(), + other.what()) == 0. + \fI(since C++11)\fP - \fI(none)\fP - -.SH Exceptions +.SH Parameters - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + other - another exception object to copy - std::bad_alloc::operator= +std::bad_alloc::operator= - bad_alloc& operator=( const bad_alloc& other ); + bad_alloc& operator=( const bad_alloc& other ) throw(); \fI(until C++11)\fP + bad_alloc& operator=( const bad_alloc& other ) noexcept; \fI(since C++11)\fP - Assigns the contents of other. + Assigns the contents with those of other. + If *this and other both have dynamic type std::bad_alloc then std::strcmp(what(), + other.what()) == 0 after assignment. + \fI(since C++11)\fP .SH Parameters - other - another exception object to assign + other - another exception object to assign with .SH Return value *this -.SH Exceptions +std::bad_alloc::what - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - std::bad_alloc::what - - virtual const char* what() const; + virtual const char* what() const throw(); \fI(until C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP Returns the explanatory string. @@ -71,39 +73,44 @@ .SH Return value - Pointer to a null-terminated string with explanatory information. + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. -.SH Exceptions +.SH Notes - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Implementations are allowed but not required to override what(). Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code #include #include - + int main() { - try { - while (true) { + try + { + while (true) + { new int[100000000ul]; } - } catch (const std::bad_alloc& e) { + } + catch (const std::bad_alloc& e) + { std::cout << "Allocation failed: " << e.what() << '\\n'; } } @@ -115,4 +122,4 @@ Inherited from std::exception .SH See also operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP diff --git a/man/std::bad_any_cast.3 b/man/std::bad_any_cast.3 new file mode 100644 index 000000000..29eacb55b --- /dev/null +++ b/man/std::bad_any_cast.3 @@ -0,0 +1,83 @@ +.TH std::bad_any_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_any_cast \- std::bad_any_cast + +.SH Synopsis + Defined in header + class bad_any_cast : public std::bad_cast; \fI(since C++17)\fP + + Defines a type of object to be thrown by the value-returning forms of std::any_cast + on failure. + +.SH Member functions + + constructor constructs a new bad_any_cast object + \fI(public member function)\fP + operator= replaces the bad_any_cast object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_any_cast::bad_any_cast + + bad_any_cast() noexcept; \fB(1)\fP \fI(since C++17)\fP + bad_any_cast( const bad_any_cast& other ) noexcept; \fB(2)\fP \fI(since C++17)\fP + + Constructs a new bad_any_cast object with an implementation-defined null-terminated + byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type std::bad_any_cast + then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::bad_any_cast::operator= + + bad_any_cast& operator=( const bad_any_cast& other ) noexcept; \fI(since C++17)\fP + + Assigns the contents with those of other. If *this and other both have dynamic type + std::bad_any_cast then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_any_cast::what + + virtual const char* what() const noexcept; \fI(since C++17)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + +Inherited from std::bad_cast + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP diff --git a/man/std::bad_array_length.3 b/man/std::bad_array_length.3 deleted file mode 100644 index eb61893fe..000000000 --- a/man/std::bad_array_length.3 +++ /dev/null @@ -1,67 +0,0 @@ -.TH std::bad_array_length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - class bad_array_length : public std::bad_alloc; \fI(since C++14)\fP - - std::bad_array_length is the type of the object thrown as exceptions by the - constructors of arrays of runtime bound and objects of type std::dynarray to report - invalid array lengths if - - 1) array length is negative or equal to zero (for arrays of runtime bound) - 2) total size of the new array would exceed implementation-defined maximum value - (for both arrays of runtime bound and std::dynarray) - - This section is incomplete - Reason: inheritance diagram - -.SH Member functions - - constructor constructs the bad_array_length object - \fI(public member function)\fP - - std::bad_array_length::bad_array_length - - bad_array_length(); \fI(since C++14)\fP - - Constructs new exception object. - -.SH Parameters - - \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - - -Inherited from std::bad_alloc - -Inherited from std::exception - -.SH Member functions - - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP - what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP - -.SH Notes - - The override for the virtual member function what() may by provided, but is not - required. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - bad_array_new_length exception thrown on allocation of array with invalid length - \fI(C++11)\fP \fI(class)\fP - - Categories: - - * Todo with reason - * Todo no example diff --git a/man/std::bad_array_new_length.3 b/man/std::bad_array_new_length.3 index d20ce65ef..04dbfe0e1 100644 --- a/man/std::bad_array_new_length.3 +++ b/man/std::bad_array_new_length.3 @@ -1,4 +1,7 @@ -.TH std::bad_array_new_length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_array_new_length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_array_new_length \- std::bad_array_new_length + .SH Synopsis Defined in header class bad_array_new_length; \fI(since C++11)\fP @@ -6,24 +9,81 @@ std::bad_array_new_length is the type of the object thrown as exceptions by the new-expressions to report invalid array lengths if - 1) array length is negative - - 2) total size of the new array would exceed implementation-defined maximum value - - 3) the number of initializer-clauses exceeds the number of elements to initialize + 1. Array length is negative, + 2. Total size of the new array would exceed implementation-defined maximum value, + 3. The number of initializer-clauses exceeds the number of elements to initialize. Only the first array dimension may generate this exception; dimensions other than the first are constant expressions and are checked at compile time. std-bad array new length-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the bad_array_new_length object + constructor constructs a new bad_array_new_length object \fI(public member function)\fP + operator= replaces the bad_array_new_length object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_array_new_length::bad_array_new_length + + bad_array_new_length() noexcept; \fB(1)\fP \fI(since C++11)\fP + bad_array_new_length( const bad_array_new_length& other ) \fB(2)\fP \fI(since C++11)\fP + noexcept; + + Constructs a new bad_array_new_length object with an implementation-defined + null-terminated byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type + std::bad_array_new_length then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::bad_array_new_length::operator= + + bad_array_new_length& operator=( const bad_array_new_length& other ) \fI(since C++11)\fP + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::bad_array_new_length then std::strcmp(what(), other.what()) == 0 after + assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_array_new_length::what + + virtual const char* what() const noexcept; \fI(since C++11)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). Inherited from std::bad_alloc @@ -31,44 +91,67 @@ Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP - -.SH Notes - - The override for the virtual member function what() may by provided, but is not - required. + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example Three conditions where std::bad_array_new_length should be thrown: - + // Run this code + #include #include #include - #include - + int main() { - int negative = -1; - int small = 1; - int large = INT_MAX; - try { - new int[negative]; // negative size - new int[small]{1,2,3}; // too many initializers - new int[large][1000000]; // too large - } catch(const std::bad_array_new_length &e) { - std::cout << e.what() << '\\n'; + try + { + int negative = -1; + new int[negative]; + } + catch (const std::bad_array_new_length& e) + { + std::cout << "1) " << e.what() << ": negative size\\n"; + } + + try + { + int small = 1; + new int[small]{1,2,3}; + } + catch (const std::bad_array_new_length& e) + { + std::cout << "2) " << e.what() << ": too many initializers\\n"; } + + try + { + long large = LONG_MAX; + new int[large][1000]; + } + catch (const std::bad_array_new_length& e) + { + std::cout << "3) " << e.what() << ": too large\\n"; + } + + std::cout << "End\\n"; } +.SH Possible output: + + 1) std::bad_array_new_length: negative size + 2) std::bad_array_new_length: too many initializers + 3) std::bad_array_new_length: too large + End + .SH See also operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP bad_alloc exception thrown when memory allocation fails - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::bad_array_new_length::bad_array_new_length.3 b/man/std::bad_array_new_length::bad_array_new_length.3 deleted file mode 100644 index cf6448559..000000000 --- a/man/std::bad_array_new_length::bad_array_new_length.3 +++ /dev/null @@ -1,16 +0,0 @@ -.TH std::bad_array_new_length::bad_array_new_length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bad_array_new_length(); \fI(since C++11)\fP - - Constructs new bad_array_new_length object with in implementation-defined - null-terminated byte string which is accessible through what(). - -.SH Parameters - - \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::bad_cast.3 b/man/std::bad_cast.3 index ff992dee1..14f126cce 100644 --- a/man/std::bad_cast.3 +++ b/man/std::bad_cast.3 @@ -1,13 +1,16 @@ -.TH std::bad_cast 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_cast \- std::bad_cast + .SH Synopsis Defined in header class bad_cast : public std::exception; An exception of this type is thrown when a dynamic_cast to a reference type fails - the run-time check (e.g. because the types are not related by inheritance). + the run-time check (e.g. because the types are not related by inheritance), and also + from std::use_facet if the requested facet does not exist in the locale. std-bad cast-inheritance.svg - About this image Inheritance diagram @@ -15,38 +18,112 @@ constructor constructs a new bad_cast object \fI(public member function)\fP + operator= replaces the bad_cast object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_cast::bad_cast + + bad_cast() throw(); \fI(until C++11)\fP + bad_cast() noexcept; \fB(1)\fP \fI(since C++11)\fP + bad_cast( const bad_cast& other ) throw(); \fB(2)\fP \fI(until C++11)\fP + bad_cast( const bad_cast& other ) noexcept; \fI(since C++11)\fP + + Constructs a new bad_cast object with an implementation-defined null-terminated byte + string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. + If *this and other both have dynamic type std::bad_cast then std::strcmp(what(), + other.what()) == 0. + \fI(since C++11)\fP + +.SH Parameters + + other - another exception object to copy + +std::bad_cast::operator= + + bad_cast& operator=( const bad_cast& other ) throw(); \fI(until C++11)\fP + bad_cast& operator=( const bad_cast& other ) noexcept; \fI(since C++11)\fP + + Assigns the contents with those of other. + If *this and other both have dynamic type std::bad_cast then std::strcmp(what(), + other.what()) == 0 after assignment. + \fI(since C++11)\fP + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_cast::what + + virtual const char* what() const throw(); \fI(until C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code #include #include - + struct Foo { virtual ~Foo() {} }; - struct Bar { virtual ~Bar() {} }; - + struct Bar { virtual ~Bar() { std::cout << "~Bar\\n"; } }; + struct Pub : Bar { ~Pub() override { std::cout << "~Pub\\n"; } }; + int main() { - Bar b; - try { - Foo& f = dynamic_cast(b); - } catch(const std::bad_cast& e) + Pub pub; + try + { + [[maybe_unused]] + Bar& r1 = dynamic_cast(pub); // OK, upcast + + [[maybe_unused]] + Foo& r2 = dynamic_cast(pub); // throws + } + catch (const std::bad_cast& e) { - std::cout << e.what() << '\\n'; + std::cout << "e.what(): " << e.what() << '\\n'; } } -.SH Output: +.SH Possible output: - Bad dynamic_cast! + e.what(): std::bad_cast + ~Pub + ~Bar diff --git a/man/std::bad_cast::bad_cast.3 b/man/std::bad_cast::bad_cast.3 deleted file mode 100644 index 0367404ec..000000000 --- a/man/std::bad_cast::bad_cast.3 +++ /dev/null @@ -1,17 +0,0 @@ -.TH std::bad_cast::bad_cast 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bad_cast(); - - Constructs new std::bad_cast object. The contents of the byte string returned by - what() are implementation defined. - -.SH Parameters - - \fI(none)\fP - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - diff --git a/man/std::bad_exception.3 b/man/std::bad_exception.3 index efff0a0c2..2df66e296 100644 --- a/man/std::bad_exception.3 +++ b/man/std::bad_exception.3 @@ -1,4 +1,7 @@ -.TH std::bad_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_exception \- std::bad_exception + .SH Synopsis Defined in header class bad_exception; @@ -6,14 +9,17 @@ std::bad_exception is the type of the exception thrown by the C++ runtime in the following situations: - 1) If a dynamic exception specification is violated and std::unexpected throws or - rethrows an exception that still violates the exception specification, but the - exception specification allows std::bad_exception, std::bad_exception is thrown. - 2) If std::exception_ptr stores a copy of the caught exception and if the copy - constructor of the exception object caught by current_exception throws an exception, - the captured exception is an instance of std::bad_exception. + * If std::exception_ptr stores a copy of the caught exception and if + the copy constructor of the exception object caught by \fI(since C++11)\fP + std::current_exception throws an exception, the captured exception + is an instance of std::bad_exception. + * If a dynamic exception specification is violated and + std::unexpected throws or rethrows an exception that still + violates the exception specification, but the exception \fI(until C++17)\fP + specification allows std::bad_exception, std::bad_exception is + thrown. + std-bad exception-inheritance.svg - About this image Inheritance diagram @@ -30,38 +36,48 @@ Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + Compiles only in C++14 (or earlier) mode. + + // Run this code - #include #include + #include #include - - void my_unexp() { throw; } - - void test() throw(std::bad_exception) + + void my_unexp() + { + throw; + } + + void test() + throw(std::bad_exception) // Dynamic exception specifications + // are deprecated in C++11 { throw std::runtime_error("test"); } - + int main() { - std::set_unexpected(my_unexp); - try { - test(); - } catch(const std::bad_exception& e) + std::set_unexpected(my_unexp); // Deprecated in C++11, removed in C++17 + + try + { + test(); + } + catch (const std::bad_exception& e) { std::cerr << "Caught " << e.what() << '\\n'; } } -.SH Output: +.SH Possible output: Caught std::bad_exception diff --git a/man/std::bad_exception::bad_exception.3 b/man/std::bad_exception::bad_exception.3 index bfdb1d9cf..3ea65b72a 100644 --- a/man/std::bad_exception::bad_exception.3 +++ b/man/std::bad_exception::bad_exception.3 @@ -1,19 +1,23 @@ -.TH std::bad_exception::bad_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_exception::bad_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_exception::bad_exception \- std::bad_exception::bad_exception + .SH Synopsis - bad_exception(); \fI(since C++11)\fP - bad_exception( const bad_exception& other ); \fI(since C++11)\fP + bad_exception() throw(); \fI(until C++11)\fP + bad_exception() noexcept; \fI(since C++11)\fP + bad_exception( const bad_exception& other ) \fB(1)\fP \fI(until C++11)\fP + throw(); \fB(2)\fP + bad_exception( const bad_exception& other ) \fI(since C++11)\fP + noexcept; Constructs new bad_exception object. - 1) Default constructor. + 1) Default constructor. what() returns an implementation-defined string. 2) Copy constructor. Initializes the object with the contents of other. + If *this and other both have dynamic type std::bad_exception then + std::strcmp(what(), other.what()) == 0. + \fI(since C++11)\fP .SH Parameters other - bad_exception object to initialize with - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::bad_exception::operator=.3 b/man/std::bad_exception::operator=.3 index 98fe835fb..8d9ff9a14 100644 --- a/man/std::bad_exception::operator=.3 +++ b/man/std::bad_exception::operator=.3 @@ -1,8 +1,15 @@ -.TH std::bad_exception::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_exception::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_exception::operator= \- std::bad_exception::operator= + .SH Synopsis - bad_exception& operator=( const bad_exception& other ); \fI(since C++11)\fP + bad_exception& operator=( const bad_exception& other ) throw(); \fI(until C++11)\fP + bad_exception& operator=( const bad_exception& other ) noexcept; \fI(since C++11)\fP Assigns the contents of other. + If *this and other both have dynamic type std::exception then std::strcmp(what(), + other.what()) == 0 after assignment. + \fI(since C++11)\fP .SH Parameters @@ -11,9 +18,3 @@ .SH Return value *this. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::bad_exception::what.3 b/man/std::bad_exception::what.3 index 403bbe24f..f157313e0 100644 --- a/man/std::bad_exception::what.3 +++ b/man/std::bad_exception::what.3 @@ -1,6 +1,9 @@ -.TH std::bad_exception::what 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_exception::what 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_exception::what \- std::bad_exception::what + .SH Synopsis - virtual const char* what() const; \fI(since C++11)\fP + virtual const char* what() const noexcept; Returns the explanatory string. @@ -11,9 +14,3 @@ .SH Return value Pointer to a null-terminated string with explanatory information. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::bad_expected_access.3 b/man/std::bad_expected_access.3 new file mode 100644 index 000000000..120ee83b6 --- /dev/null +++ b/man/std::bad_expected_access.3 @@ -0,0 +1,58 @@ +.TH std::bad_expected_access 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_expected_access \- std::bad_expected_access + +.SH Synopsis + Defined in header + template< class E > \fB(1)\fP (since C++23) + class bad_expected_access : public std::bad_expected_access + template<> \fB(2)\fP (since C++23) + class bad_expected_access : public std::exception + + 1) Defines a type of object to be thrown by std::expected::value when accessing an + expected object that contains an unexpected value. bad_expected_access stores a + copy of the unexpected value. + 2) bad_expected_access is the base class of all other bad_expected_access + specializations. + + This section is incomplete + Reason: inheritance diagram + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + + Members of the bad_expected_access specialization + + constructor constructs a bad_expected_access object + \fI(protected member function)\fP + destructor destroys the bad_expected_access object + \fI(protected member function)\fP + operator= replaces the bad_expected_access object + \fI(protected member function)\fP + what returns the explanatory string + \fI(public member function)\fP + + Special member functions of bad_expected_access are protected. They can only + be called by derived classes. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::bad_function_call.3 b/man/std::bad_function_call.3 index 495a7ce65..6e1bef48f 100644 --- a/man/std::bad_function_call.3 +++ b/man/std::bad_function_call.3 @@ -1,4 +1,7 @@ -.TH std::bad_function_call 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_function_call 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_function_call \- std::bad_function_call + .SH Synopsis Defined in header class bad_function_call; \fI(since C++11)\fP @@ -7,63 +10,108 @@ std::function::operator() if the function wrapper has no target. std-bad function call-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor bad_function_call() + constructor constructs a new bad_function_call object + \fI(public member function)\fP + operator= replaces the bad_function_call object \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_function_call::bad_function_call - std::bad_function_call::bad_function_call() + bad_function_call() noexcept; \fB(1)\fP \fI(since C++11)\fP + bad_function_call( const bad_function_call& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP - bad_function_call(); + Constructs a new bad_function_call object with an implementation-defined + null-terminated byte string which is accessible through what(). - Constructs a new instance of std::bad_function_call. + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type + std::bad_function_call then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::bad_function_call::operator= + + bad_function_call& operator=( const bad_function_call& other ) \fI(since C++11)\fP + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::bad_function_call then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_function_call::what + + virtual const char* what() const noexcept; \fI(since C++11)\fP + + Returns the explanatory string. .SH Parameters \fI(none)\fP -.SH Exceptions +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. - noexcept specification: - noexcept - +.SH Notes + + Implementations are allowed but not required to override what(). Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code - #include #include - + #include + int main() { std::function f = nullptr; - try { + try + { f(); - } catch(const std::bad_function_call& e) { + } + catch (const std::bad_function_call& e) + { std::cout << e.what() << '\\n'; } } -.SH Output: +.SH Possible output: bad function call .SH See also - function wraps callable object of any type with specified function call signature - \fI(C++11)\fP \fI(class template)\fP + function wraps callable object of any copy constructible type with specified + \fI(C++11)\fP function call signature + \fI(class template)\fP diff --git a/man/std::bad_optional_access.3 b/man/std::bad_optional_access.3 index 99caf56f4..1cf5db766 100644 --- a/man/std::bad_optional_access.3 +++ b/man/std::bad_optional_access.3 @@ -1,43 +1,87 @@ -.TH std::bad_optional_access 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_optional_access 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_optional_access \- std::bad_optional_access + .SH Synopsis Defined in header - class bad_optional_access; (library fundamentals TS) + class bad_optional_access; \fI(since C++17)\fP - Defines a type of object to be thrown as exception when accessing a - std::experimental::optional object with uninitialized state. + Defines a type of object to be thrown by std::optional::value when accessing an + optional object that does not contain a value. - std-bad optional access-inheritance.svg - About this image + std-bad optional access-inheritance-lwg2806.svg Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP + constructor constructs a new bad_optional_access object + \fI(public member function)\fP + operator= replaces the bad_optional_access object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_optional_access::bad_optional_access - std::bad_optional_access::bad_optional_access + bad_optional_access() noexcept; \fB(1)\fP \fI(since C++17)\fP + bad_optional_access( const bad_optional_access& other ) noexcept; \fB(2)\fP \fI(since C++17)\fP - explicit bad_optional_access( const std::string& \fB(1)\fP (library fundamentals TS) - what_arg ); - explicit bad_optional_access( const char* what_arg ); \fB(2)\fP (library fundamentals TS) + Constructs a new bad_optional_access object with an implementation-defined + null-terminated byte string which is accessible through what(). - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type + std::bad_optional_access then std::strcmp(what(), other.what()) == 0. .SH Parameters - what_arg - explanatory string + other - another exception object to copy + +std::bad_optional_access::operator= + + bad_optional_access& operator=( const bad_optional_access& other ) \fI(since C++17)\fP + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::bad_optional_access then std::strcmp(what(), other.what()) == 0 after + assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value -.SH Exceptions + *this + +std::bad_optional_access::what + + virtual const char* what() const noexcept; \fI(since C++17)\fP + + Returns the explanatory string. + +.SH Parameters \fI(none)\fP +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP diff --git a/man/std::bad_typeid.3 b/man/std::bad_typeid.3 index b9ceb8d47..211a62b47 100644 --- a/man/std::bad_typeid.3 +++ b/man/std::bad_typeid.3 @@ -1,4 +1,7 @@ -.TH std::bad_typeid 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_typeid 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_typeid \- std::bad_typeid + .SH Synopsis Defined in header class bad_typeid : public std::exception; @@ -7,7 +10,6 @@ dereferenced null pointer value of a polymorphic type. std-bad typeid-inheritance.svg - About this image Inheritance diagram @@ -15,38 +17,107 @@ constructor constructs a new bad_typeid object \fI(public member function)\fP + operator= replaces the bad_typeid object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_typeid::bad_typeid + + bad_typeid() throw(); \fI(until C++11)\fP + bad_typeid() noexcept; \fB(1)\fP \fI(since C++11)\fP + bad_typeid( const bad_typeid& other ) throw(); \fB(2)\fP \fI(until C++11)\fP + bad_typeid( const bad_typeid& other ) noexcept; \fI(since C++11)\fP + + Constructs a new bad_typeid object with an implementation-defined null-terminated + byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. + If *this and other both have dynamic type std::bad_typeid then std::strcmp(what(), + other.what()) == 0. + \fI(since C++11)\fP + +.SH Parameters + + other - another exception object to copy + +std::bad_typeid::operator= + + bad_typeid& operator=( const bad_typeid& other ) throw(); \fI(until C++11)\fP + bad_typeid& operator=( const bad_typeid& other ) noexcept; \fI(since C++11)\fP + + Assigns the contents with those of other. + If *this and other both have dynamic type std::bad_typeid then std::strcmp(what(), + other.what()) == 0 after assignment. + \fI(since C++11)\fP + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_typeid::what + + virtual const char* what() const throw(); \fI(until C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code #include #include - - struct S { // The type has to be polymorphic + + struct S // The type has to be polymorphic + { virtual void f(); }; - + int main() { S* p = nullptr; - try { + try + { std::cout << typeid(*p).name() << '\\n'; - } catch(const std::bad_typeid& e) { + } + catch (const std::bad_typeid& e) + { std::cout << e.what() << '\\n'; } } -.SH Output: +.SH Possible output: Attempted a typeid of NULL pointer! diff --git a/man/std::bad_typeid::bad_typeid.3 b/man/std::bad_typeid::bad_typeid.3 deleted file mode 100644 index 76af511f9..000000000 --- a/man/std::bad_typeid::bad_typeid.3 +++ /dev/null @@ -1,17 +0,0 @@ -.TH std::bad_typeid::bad_typeid 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bad_typeid(); - - Constructs new std::bad_typeid object. The contents of the byte string returned by - what() are implementation defined. - -.SH Parameters - - \fI(none)\fP - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - diff --git a/man/std::bad_variant_access.3 b/man/std::bad_variant_access.3 new file mode 100644 index 000000000..6f9c876fd --- /dev/null +++ b/man/std::bad_variant_access.3 @@ -0,0 +1,122 @@ +.TH std::bad_variant_access 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_variant_access \- std::bad_variant_access + +.SH Synopsis + Defined in header + class bad_variant_access : public std::exception \fI(since C++17)\fP + + std::bad_variant_access is the type of the exception thrown in the following + situations: + + * std::get(std::variant) called with an index or type that does not match the + currently active alternative. + * std::visit called to visit a variant that is valueless_by_exception. + +.SH Member functions + + constructor constructs a new bad_variant_access object + \fI(public member function)\fP + operator= replaces the bad_variant_access object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::bad_variant_access::bad_variant_access + + bad_variant_access() noexcept; \fB(1)\fP \fI(since C++17)\fP + bad_variant_access( const bad_variant_access& other ) noexcept; \fB(2)\fP \fI(since C++17)\fP + + Constructs a new bad_variant_access object with an implementation-defined + null-terminated byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type + std::bad_variant_access then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::bad_variant_access::operator= + + bad_variant_access& operator=( const bad_variant_access& other ) \fI(since C++17)\fP + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::bad_variant_access then std::strcmp(what(), other.what()) == 0 after + assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_variant_access::what + + virtual const char* what() const noexcept; \fI(since C++17)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::variant v; + v = 12; + try + { + std::get(v); + } + catch (const std::bad_variant_access& e) + { + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + bad_variant_access + +.SH See also + + get(std::variant) reads the value of the variant given the index or the type (if the + \fI(C++17)\fP type is unique), throws on error + \fI(function template)\fP + visit calls the provided functor with the arguments held by one or more + \fI(C++17)\fP variants + \fI(function template)\fP diff --git a/man/std::bad_weak_ptr.3 b/man/std::bad_weak_ptr.3 index 225c505c6..299e76c05 100644 --- a/man/std::bad_weak_ptr.3 +++ b/man/std::bad_weak_ptr.3 @@ -1,4 +1,7 @@ -.TH std::bad_weak_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bad_weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bad_weak_ptr \- std::bad_weak_ptr + .SH Synopsis Defined in header class bad_weak_ptr; \fI(since C++11)\fP @@ -8,50 +11,120 @@ refers to an already deleted object. std-bad weak ptr-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the bad_weak_ptr object + constructor constructs a new bad_weak_ptr object + \fI(public member function)\fP + operator= replaces the bad_weak_ptr object + \fI(public member function)\fP + what returns the explanatory string \fI(public member function)\fP +std::bad_weak_ptr::bad_weak_ptr + + bad_weak_ptr() noexcept; \fB(1)\fP \fI(since C++11)\fP + bad_weak_ptr( const bad_weak_ptr& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + + Constructs a new bad_weak_ptr object with an implementation-defined null-terminated + byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type std::bad_weak_ptr + then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::bad_weak_ptr::operator= + + bad_weak_ptr& operator=( const bad_weak_ptr& other ) noexcept; \fI(since C++11)\fP + + Assigns the contents with those of other. If *this and other both have dynamic type + std::bad_weak_ptr then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::bad_weak_ptr::what + + virtual const char* what() const noexcept; \fI(since C++11)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code - #include #include + #include + int main() { std::shared_ptr p1(new int(42)); std::weak_ptr wp(p1); p1.reset(); - try { + try + { std::shared_ptr p2(wp); - } catch(const std::bad_weak_ptr& e) { + } + catch (const std::bad_weak_ptr& e) + { std::cout << e.what() << '\\n'; } } -.SH Output: +.SH Possible output: std::bad_weak_ptr + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + calling what on a default-constructed the return value is + LWG 2376 C++11 bad_weak_ptr was required to return implementation-defined + "bad_weak_ptr" + .SH See also shared_ptr smart pointer with shared object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP weak_ptr weak reference to an object managed by std::shared_ptr - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::bad_weak_ptr::bad_weak_ptr.3 b/man/std::bad_weak_ptr::bad_weak_ptr.3 deleted file mode 100644 index 06de4ed76..000000000 --- a/man/std::bad_weak_ptr::bad_weak_ptr.3 +++ /dev/null @@ -1,16 +0,0 @@ -.TH std::bad_weak_ptr::bad_weak_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bad_weak_ptr(); - - Constructs new bad_weak_ptr object. what() returns "bad_weak_ptr" afterwards. - -.SH Parameters - - \fI(none)\fP - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - diff --git a/man/std::barrier.3 b/man/std::barrier.3 new file mode 100644 index 000000000..f5368f7bf --- /dev/null +++ b/man/std::barrier.3 @@ -0,0 +1,163 @@ +.TH std::barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier \- std::barrier + +.SH Synopsis + Defined in header + template< class CompletionFunction = /* see below */ > \fI(since C++20)\fP + class barrier; + + The class template std::barrier provides a thread-coordination mechanism that blocks + a group of threads of known size until all threads in that group have reached the + barrier. Unlike std::latch, barriers are reusable: once a group of arriving threads + are unblocked, the barrier can be reused. Unlike std::latch, barriers execute a + possibly empty callable before unblocking threads. + + A barrier object's lifetime consists of one or more phases. Each phase defines a + phase synchronization point where waiting threads block. Threads can arrive at the + barrier, but defer waiting on the phase synchronization point by calling arrive. + Such threads can later block on the phase synchronization point by calling wait. + + A barrier phase consists of the following steps: + + 1. The expected count is decremented by each call to arrive or arrive_and_drop. + 2. When the expected count reaches zero, the phase completion step is run, meaning + that the completion is invoked, and all threads blocked on the phase + synchronization point are unblocked. The end of the completion step strongly + happens-before all calls that were unblocked by the completion step return. + Exactly once after the expected count reaches zero, a thread executes the + completion step during its call to arrive, arrive_and_drop, or wait, except that + it is implementation-defined whether the step executes if no thread calls wait. + 3. When the completion step finishes, the expected count is reset to the value + specified at construction less the number of calls to arrive_and_drop since, and + the next barrier phase begins. + + Concurrent invocations of the member functions of barrier, except for the + destructor, do not introduce data races. + +.SH Template parameters + + CompletionFunction - a function object type + - + CompletionFunction must meet the requirements of MoveConstructible and Destructible. + std::is_nothrow_invocable_v must be true. + + The default template argument of CompletionFunction is an unspecified function + object type that additionally meets the requirements of DefaultConstructible. + Calling an lvalue of it with no arguments has no effects. + +.SH Member objects + + Name Definition + A completion function object of type CompletionFunction which + completion (private) is called on every phase completion step. + (exposition-only member object*) + +.SH Member types + + Name Definition + arrival_token an unspecified object type meeting requirements of MoveConstructible, + MoveAssignable and Destructible + +.SH Member functions + + constructor constructs a barrier + \fI(public member function)\fP + destructor destroys the barrier + \fI(public member function)\fP + operator= barrier is not assignable + [deleted] \fI(public member function)\fP + arrive arrives at barrier and decrements the expected count + \fI(public member function)\fP + blocks at the phase synchronization point until its phase completion + wait step is run + \fI(public member function)\fP + arrives at barrier and decrements the expected count by one, then + arrive_and_wait blocks until current phase completes + \fI(public member function)\fP + decrements both the initial expected count for subsequent phases and + arrive_and_drop the expected count for current phase by one + \fI(public member function)\fP +.SH Constants + max the maximum value of expected count supported by the implementation + \fB[static]\fP \fI(public static member function)\fP + +.SH Notes + + Feature-test macro Value Std Feature + 201907L (C++20) std::barrier + __cpp_lib_barrier 202302L (C++20) Relaxed guarantees for phase completion + (DR) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + const auto workers = {"Anil", "Busara", "Carl"}; + + auto on_completion = []() noexcept + { + // locking not needed here + static auto phase = + "... done\\n" + "Cleaning up...\\n"; + std::cout << phase; + phase = "... done\\n"; + }; + + std::barrier sync_point(std::ssize(workers), on_completion); + + auto work = [&](std::string name) + { + std::string product = " " + name + " worked\\n"; + std::osyncstream(std::cout) << product; // ok, op<< call is atomic + sync_point.arrive_and_wait(); + + product = " " + name + " cleaned\\n"; + std::osyncstream(std::cout) << product; + sync_point.arrive_and_wait(); + }; + + std::cout << "Starting...\\n"; + std::vector threads; + threads.reserve(std::size(workers)); + for (auto const& worker : workers) + threads.emplace_back(work, worker); + } + +.SH Possible output: + + Starting... + Anil worked + Carl worked + Busara worked + ... done + Cleaning up... + Busara cleaned + Carl cleaned + Anil cleaned + ... done + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2588R3 C++20 old phase completion guarantees might prevent relaxed + hardware acceleration + +.SH See also + + latch single-use thread barrier + (C++20) \fI(class)\fP diff --git a/man/std::barrier::arrive.3 b/man/std::barrier::arrive.3 new file mode 100644 index 000000000..36de3ef44 --- /dev/null +++ b/man/std::barrier::arrive.3 @@ -0,0 +1,45 @@ +.TH std::barrier::arrive 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::arrive \- std::barrier::arrive + +.SH Synopsis + [[nodiscard]] arrival_token arrive( std::ptrdiff_t n = 1 ); \fI(since C++20)\fP + + Constructs an arrival_token object associated with the phase synchronization point + for the current phase. Then, decrements the expected count by n. + + This function executes atomically. The call to this function strongly happens-before + the start of the phase completion step for the current phase. + + The behavior is undefined if n is less than or equal to 0 or greater than the + expected count for the current barrier phase. + +.SH Parameters + + n - the value by which the expected count is decreased + +.SH Return value + + The constructed arrival_token object. + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. + +.SH Notes + + This function can cause the completion step for the current phase to start. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + blocks at the phase synchronization point until its phase completion step is + wait run + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::barrier::arrive_and_drop.3 b/man/std::barrier::arrive_and_drop.3 new file mode 100644 index 000000000..41c0236ce --- /dev/null +++ b/man/std::barrier::arrive_and_drop.3 @@ -0,0 +1,42 @@ +.TH std::barrier::arrive_and_drop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::arrive_and_drop \- std::barrier::arrive_and_drop + +.SH Synopsis + void arrive_and_drop(); \fI(since C++20)\fP + + Decrements the initial expected count for all subsequent phases by one, and then + decrements the expected count for the current phase by one. + + This function is executed atomically. The call to this function strongly + happens-before the start of the phase completion step for the current phase. + + The behavior is undefined if the expected count for the current phase is zero. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. + +.SH Notes + + This function can cause the completion step for the current phase to start. + + If the current expected count is zero before calling this function, the initial + expected count for all subsequent phases is also zero, which means the barrier + cannot be reused. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::barrier::arrive_and_wait.3 b/man/std::barrier::arrive_and_wait.3 new file mode 100644 index 000000000..78050130f --- /dev/null +++ b/man/std::barrier::arrive_and_wait.3 @@ -0,0 +1,41 @@ +.TH std::barrier::arrive_and_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::arrive_and_wait \- std::barrier::arrive_and_wait + +.SH Synopsis + void arrive_and_wait(); \fI(since C++20)\fP + + Atomically decrements the expected count by 1, then blocks at the synchronization + point for the current phase until the phase completion step of the current phase is + run. Equivalent to wait(arrive());. + + The behavior is undefined if the expected count for the current phase is zero. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. + +.SH Notes + + If the current expected count is decremented to zero in the call to this function, + the phase completion step is run and this function does not block. + + If the current expected count is zero before calling this function, the initial + expected count for all subsequent phases is also zero, which means the barrier + cannot be reused. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::barrier::barrier.3 b/man/std::barrier::barrier.3 new file mode 100644 index 000000000..7c38128ff --- /dev/null +++ b/man/std::barrier::barrier.3 @@ -0,0 +1,30 @@ +.TH std::barrier::barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::barrier \- std::barrier::barrier + +.SH Synopsis + constexpr explicit barrier( std::ptrdiff_t expected, + CompletionFunction f = \fB(1)\fP \fI(since C++20)\fP + CompletionFunction()); + barrier( const barrier& ) = delete; \fB(2)\fP \fI(since C++20)\fP + + 1) Sets the both initial expected count for each phase and the current expected + count for the first phase to expected, initializes the completion function object + with std::move(f), and then starts the first phase. The behavior is undefined if + expected is negative or greater than max(). + 2) Copy constructor is deleted. barrier is neither copyable nor movable. + +.SH Parameters + + expected - initial value of the expected count + f - completion function object to be called on phase completion step + +.SH Exceptions + + 1) Any exception thrown by CompletionFunction's move constructor. + +.SH Notes + + expected is permitted to be zero. However, calling any non-static member function + other than the destructor on such barrier results in undefined behavior. In other + words, such barrier can only be destroyed. diff --git a/man/std::barrier::max.3 b/man/std::barrier::max.3 new file mode 100644 index 000000000..f9a5674b1 --- /dev/null +++ b/man/std::barrier::max.3 @@ -0,0 +1,16 @@ +.TH std::barrier::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::max \- std::barrier::max + +.SH Synopsis + static constexpr std::ptrdiff_t max() noexcept; \fI(since C++20)\fP + + Returns the maximum value of the expected count supported by the implementation. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The maximum value of the expected count supported by the implementation. diff --git a/man/std::barrier::wait.3 b/man/std::barrier::wait.3 new file mode 100644 index 000000000..561a658ee --- /dev/null +++ b/man/std::barrier::wait.3 @@ -0,0 +1,42 @@ +.TH std::barrier::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::wait \- std::barrier::wait + +.SH Synopsis + void wait( arrival_token&& arrival ) const; \fI(since C++20)\fP + + If arrival is associated with the phase synchronization point for the current phase + of *this, blocks at the synchronization point associated with arrival until the + phase completion step of the synchronization point's phase is run. + + Otherwise, if arrival is associated with the phase synchronization point for the + immediately preceding phase of *this, returns immediately. + + Otherwise, i.e. if arrival is associated with the phase synchronization point for an + earlier phase of *this or any phase of a barrier object other than *this, the + behavior is undefined. + +.SH Parameters + + arrival - an arrival_token obtained by a previous call to arrive on the same barrier + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + arrive arrives at barrier and decrements the expected count + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::barrier::~barrier.3 b/man/std::barrier::~barrier.3 new file mode 100644 index 000000000..3ee8ccac8 --- /dev/null +++ b/man/std::barrier::~barrier.3 @@ -0,0 +1,13 @@ +.TH std::barrier::~barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::barrier::~barrier \- std::barrier::~barrier + +.SH Synopsis + ~barrier(); \fI(since C++20)\fP + + Destroys the barrier. + +.SH Notes + + The behavior is undefined if any thread is concurrently calling a member function of + the barrier. diff --git a/man/std::basic_common_reference.3 b/man/std::basic_common_reference.3 new file mode 100644 index 000000000..f2790773a --- /dev/null +++ b/man/std::basic_common_reference.3 @@ -0,0 +1,47 @@ +.TH std::basic_common_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_common_reference \- std::basic_common_reference + +.SH Synopsis + Defined in header + template< class T1, class T2, class U1, class U2, + + template class TQual, template class UQual > + requires requires { typename + std::pair, UQual>, (since C++23) + + std::common_reference_t, UQual>>; } + + struct basic_common_reference, std::pair, + TQual, UQual>; + + The common reference type of two pairs is a pair of both common reference types of + corresponding element types of both pairs, where the cv and reference qualifiers on + the pairs are applied to their element types. + + The common reference type is defined only if both pairs of corresponding element + types have common reference types. + +.SH Member types + + Member type Definition + std::pair, UQual>, + type + std::common_reference_t, UQual>> + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + common_reference determines the common reference type of a + basic_common_reference group of types + (C++20) \fI(class template)\fP + std::basic_common_reference determines the common reference type of a + (C++23) tuple and a tuple-like type + \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_const_iterator.3 b/man/std::basic_const_iterator.3 new file mode 100644 index 000000000..5d82bf211 --- /dev/null +++ b/man/std::basic_const_iterator.3 @@ -0,0 +1,156 @@ +.TH std::basic_const_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator \- std::basic_const_iterator + +.SH Synopsis + Defined in header + template< std::input_iterator Iter > (since C++23) + class basic_const_iterator; + + std::basic_const_iterator is an iterator adaptor which behaves exactly like the + underlying iterator (which must be at least an LegacyInputIterator or model + input_iterator), except that dereferencing converts the value returned by the + underlying iterator as immutable. Specializations of std::basic_const_iterator are + constant iterators, that is, the iterator can never be used as an output iterator + because modifying elements is not allowed. + +.SH Member types + + Member type Definition + If Iter models forward_iterator: + + iterator_category * member iterator_category is the same type as + std::iterator_traits::iterator_category. + + Otherwise, there is no member iterator_category. + * std::contiguous_iterator_tag, if Iter models + contiguous_iterator; + * std::random_access_iterator_tag, if Iter models + iterator_concept random_access_iterator; + * std::bidirectional_iterator_tag, if Iter models + bidirectional_iterator; + * std::forward_iterator_tag, if Iter models forward_iterator; + * std::input_iterator_tag otherwise. + value_type std::iter_value_t + difference_type std::iter_difference_t + reference (private) std::iter_const_reference_t + (exposition-only member type*) + +.SH Member objects + + Member name Definition + current (private) the underlying iterator from which base() copies or moves + (exposition-only member object*) + +.SH Member functions + + constructor constructs a new iterator adaptor + \fI(public member function)\fP + base accesses the underlying iterator + \fI(public member function)\fP + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + operator[] accesses an element by index + \fI(public member function)\fP + operator++ + operator++(int) + operator+= advances or decrements the iterator + operator-- \fI(public member function)\fP + operator--(int) + operator-= + converts into any constant iterator to which an + operator constant-iterator underlying iterator can be convertible + \fI(public member function)\fP + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(public member function)\fP + operator>= + operator<=> + +.SH Non-member functions + + operator< + operator> + operator<= compares basic_const_iterator with non-basic_const_iterator + operator>= \fI(function template)\fP + operator<=> + (C++23) + operator+ advances or decrements the iterator + operator- \fI(function template)\fP + (C++23) + operator- computes the distance between two iterator adaptors + (C++23) \fI(function template)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + +.SH Helper classes + + determines the common type of an + std::common_type iterator and an adapted + (C++23) basic_const_iterator type + \fI(class template specialization)\fP + + Helper alias templates + + template< std::input_iterator I > (since C++23) + using const_iterator = /* see description */; + + If I models constant-iterator (an exposition-only concept), then const_iterator + denotes a type I. Otherwise, basic_const_iterator. + + template< std::semiregular S > (since C++23) + using const_sentinel = /* see description */; + + If S models input_iterator, then const_sentinel denotes a type const_iterator. + Otherwise, S. + + Helper function templates + + template< std::input_iterator T > + constexpr const_iterator make_const_iterator( I it ) { return it; (since C++23) + } + template< std::semiregular S > (since C++23) + constexpr const_sentinel make_const_sentinel( S s ) { return s; } + +.SH Notes + + Feature-test macro Value Std Feature + 202207L (C++23) std::basic_const_iterator + __cpp_lib_ranges_as_const 202311L (C++23) std::basic_const_iterator should follow + (DR) its underlying type's convertibility + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v{1, 2, 3}; + std::vector::iterator i = v.begin(); + *i = 4; // OK, v[0] == 4 now + i[1] = 4; // OK, the same as *(i + 1) = 4; + + auto ci = std::make_const_iterator(i); + assert(*ci == 4); // OK, can read the underlying object + assert(ci[0] == 4); // OK, ditto + // *ci = 13; // Error: location is read-only + // ci[0] = 13; // Error: ditto + ci.base()[0] = 42; // OK, underlying iterator is writable + assert(*ci == 42); // OK, underlying location v[0] was modified + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2836R1 C++23 basic_const_iterator doesn't follow its conversion operator + underlying type's convertibility provided diff --git a/man/std::basic_const_iterator::base.3 b/man/std::basic_const_iterator::base.3 new file mode 100644 index 000000000..55c6e4373 --- /dev/null +++ b/man/std::basic_const_iterator::base.3 @@ -0,0 +1,34 @@ +.TH std::basic_const_iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::base \- std::basic_const_iterator::base + +.SH Synopsis + constexpr const Iter& base() const& noexcept; \fB(1)\fP (since C++23) + constexpr Iter base() &&; \fB(2)\fP (since C++23) + + Returns the underlying base iterator. + + 1) Returns a reference to the underlying iterator. + 2) Move constructs the return value from the underlying iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A reference to the underlying iterator. + 2) An iterator move constructed from the underlying iterator. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_const_iterator::basic_const_iterator.3 b/man/std::basic_const_iterator::basic_const_iterator.3 new file mode 100644 index 000000000..7a6d7df22 --- /dev/null +++ b/man/std::basic_const_iterator::basic_const_iterator.3 @@ -0,0 +1,40 @@ +.TH std::basic_const_iterator::basic_const_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::basic_const_iterator \- std::basic_const_iterator::basic_const_iterator + +.SH Synopsis + basic_const_iterator() requires std::default_initializable = \fB(1)\fP (since C++23) + default; + constexpr basic_const_iterator( Iter x ); \fB(2)\fP (since C++23) + template< std::convertible_to U > \fB(3)\fP (since C++23) + constexpr basic_const_iterator( basic_const_iterator other ); + template< /*different-from*/ T > + + requires std::convertible_to \fB(4)\fP (since C++23) + + constexpr basic_const_iterator( T&& x ); + + Constructs a new iterator adaptor. + + 1) Default constructor. The underlying iterator is value-initialized. + 2) The underlying iterator is initialized with std::move(x). + 3) The underlying iterator is initialized with that of other. + 4) The underlying iterator is initialized with std::forward(x). + +.SH Parameters + + x - iterator to adapt + other - iterator adaptor to copy + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns another iterator adaptor + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_const_iterator::operator*.3 b/man/std::basic_const_iterator::operator*.3 new file mode 100644 index 000000000..9549dcff3 --- /dev/null +++ b/man/std::basic_const_iterator::operator*.3 @@ -0,0 +1,44 @@ +.TH std::basic_const_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::operator* \- std::basic_const_iterator::operator* + +.SH Synopsis + constexpr std::iter_const_reference_t operator*() const; \fB(1)\fP (since + C++23) + constexpr const auto* operator->() const + + requires std::is_lvalue_reference_v> + && \fB(2)\fP (since + C++23) + std::same_as>, + + value_type>; + + Returns a reference or pointer to the const version of the current element. + + 1) Returns static_cast>(*base()). + 2) If Iter models contiguous_iterator, returns std::to_address(base()); otherwise, + returns std::addressof(*base()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Reference-to-const that refers to the current element. The result may be a + prvalue (e.g. if *base() is a prvalue). + 2) Pointer-to-const that points to the current element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] accesses an element by index + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_const_iterator::operator++,--,+=,-=.3 b/man/std::basic_const_iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..92199539e --- /dev/null +++ b/man/std::basic_const_iterator::operator++,--,+=,-=.3 @@ -0,0 +1,50 @@ +.TH std::basic_const_iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::operator++,--,+=,-= \- std::basic_const_iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr basic_const_iterator& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++(int); \fB(2)\fP (since C++23) + constexpr basic_const_iterator operator++(int) \fB(3)\fP (since C++23) + requires std::forward_iterator; + constexpr basic_const_iterator& operator--() \fB(4)\fP (since C++23) + requires std::bidirectional_iterator; + constexpr basic_const_iterator operator--(int) \fB(5)\fP (since C++23) + requires std::bidirectional_iterator; + constexpr basic_const_iterator& operator+=( difference_type n ) \fB(6)\fP (since C++23) + requires std::random_access_iterator; + constexpr basic_const_iterator& operator-=( difference_type n ) \fB(7)\fP (since C++23) + requires std::random_access_iterator; + + Increments or decrements the iterator, by applying the corresponding operation on + the underlying iterator. + + 1-3) Increments by one. + 4,5) Decrements by one. + 6,7) Advances the iterator by n or -n positions respectively. + +.SH Return value + + 1,4,6,7) *this + 3,5) A copy of *this that was made before the change + 2) \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator++ + operator++(int) + operator+= + operator+ advances or decrements the iterator + operator-- \fI(public member function of std::move_iterator)\fP + operator--(int) + operator-= + operator- + \fI(C++11)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_const_iterator::operator==,,>=,.3 b/man/std::basic_const_iterator::operator==,,>=,.3 new file mode 100644 index 000000000..5ca91c359 --- /dev/null +++ b/man/std::basic_const_iterator::operator==,,>=,.3 @@ -0,0 +1,97 @@ +.TH std::basic_const_iterator::operator==,,>=, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::operator==,,>=, \- std::basic_const_iterator::operator==,,>=, + +.SH Synopsis + Equality comparison + template< std::sentinel_for S > \fB(1)\fP (since C++23) + constexpr bool operator==( const S& s ) const; + Relational comparisons between two basic_const_iterators + constexpr bool operator<( const basic_const_iterator& y ) const \fB(2)\fP (since C++23) + requires std::random_access_iterator; + constexpr bool operator>( const basic_const_iterator& y ) const \fB(3)\fP (since C++23) + requires std::random_access_iterator; + constexpr bool operator<=( const basic_const_iterator& y ) const \fB(4)\fP (since C++23) + requires std::random_access_iterator; + constexpr bool operator>=( const basic_const_iterator& y ) const \fB(5)\fP (since C++23) + requires std::random_access_iterator; + constexpr auto operator<=>( const basic_const_iterator& y ) const + requires std::random_access_iterator && \fB(6)\fP (since C++23) + std::three_way_comparable; + Relational comparisons between basic_const_iterator and another + type + template< /*different-from*/ I > + + constexpr bool operator<( const I& y ) const \fB(7)\fP (since C++23) + + requires std::random_access_iterator && + std::totally_ordered_with; + template< /*different-from*/ I > + + constexpr bool operator>( const I& y ) const \fB(8)\fP (since C++23) + + requires std::random_access_iterator && + std::totally_ordered_with; + template< /*different-from*/ I > + + constexpr bool operator<=( const I& y ) const \fB(9)\fP (since C++23) + + requires std::random_access_iterator && + std::totally_ordered_with; + template< /*different-from*/ I > + + constexpr bool operator>=( const I& y ) const \fB(10)\fP (since C++23) + + requires std::random_access_iterator && + std::totally_ordered_with; + template< /*different-from*/ I > + + constexpr auto operator<=>( const I& y ) const + requires std::random_access_iterator && \fB(11)\fP (since C++23) + std::totally_ordered_with && + + std::three_way_comparable_with; + + Compares a basic_const_iterator with another value. + + The != operator is synthesized from operator==. + + I satisfies /*different-from*/ if std::same_as> is false. + +.SH Parameters + + s - a sentinel for Iter + y - a value to compare with + +.SH Return value + + 1) base() == s + 2) base() < y.base() + 3) base() > y.base() + 4) base() <= y.base() + 5) base() >= y.base() + 6) base() <=> y.base() + 7) base() < y + 8) base() > y + 9) base() <= y + 10) base() >= y + 11) base() <=> y + +.SH Notes + + Overload \fB(1)\fP can be used to compare two basic_const_iterator values if Iter + models sentinel_for. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::basic_const_iterator::operator[].3 b/man/std::basic_const_iterator::operator[].3 new file mode 100644 index 000000000..310c26d7a --- /dev/null +++ b/man/std::basic_const_iterator::operator[].3 @@ -0,0 +1,32 @@ +.TH std::basic_const_iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::operator[] \- std::basic_const_iterator::operator[] + +.SH Synopsis + constexpr std::iter_const_reference_t operator[]( + difference_type n ) const (since C++23) + requires std::random_access_iterator; + + Returns a reference to the element at specified relative location. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + A reference-to-const to the element at relative location, that is, + static_cast>(base()[n]). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_const_iterator::operatorconstant-iterator.3 b/man/std::basic_const_iterator::operatorconstant-iterator.3 new file mode 100644 index 000000000..7ccaa7013 --- /dev/null +++ b/man/std::basic_const_iterator::operatorconstant-iterator.3 @@ -0,0 +1,45 @@ +.TH std::basic_const_iterator::operatorconstant-iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_const_iterator::operatorconstant-iterator \- std::basic_const_iterator::operatorconstant-iterator + +.SH Synopsis + template< /*not-a-const-iterator*/ CI > + + requires /*constant-iterator*/ && \fB(1)\fP (since C++23) + std::convertible_to + + constexpr operator CI() const &; + template< /*not-a-const-iterator*/ CI > + + requires /*constant-iterator*/ && \fB(2)\fP (since C++23) + std::convertible_to + + constexpr operator CI() &&; + + Returns the converted constant iterator to which an underlying iterator current can + be explicitly or implicitly convertible. + + CI satisfies the exposition-only concept /*not-a-const-iterator*/ if and only if + it's not a specialization of basic_const_iterator. + +.SH Return value + + 1) current + 2) std::move(current) + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2836R1 C++23 basic_const_iterator doesn't follow its conversion operator + underlying type's convertibility provided + +.SH Category: + * Todo no example diff --git a/man/std::basic_filebuf.3 b/man/std::basic_filebuf.3 index 8d36acd0d..b456ca49a 100644 --- a/man/std::basic_filebuf.3 +++ b/man/std::basic_filebuf.3 @@ -1,85 +1,95 @@ -.TH std::basic_filebuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf \- std::basic_filebuf + .SH Synopsis Defined in header template< - class charT, - class Traits = std::char_traits, - class Allocator = std::allocator + class CharT, + class Traits = std::char_traits > class basic_filebuf : public std::basic_streambuf std::basic_filebuf is a std::basic_streambuf whose associated character sequence is a file. Both the input sequence and the output sequence are associated with the same - file, and a joint file position is maintained for both operations. + file, and a joint file position is maintained for both operations. The restrictions + on reading and writing a sequence with std::basic_filebuf are the same as + std::FILEs. - The functions underflow() and overflow()/sync() perform the actual I/O between the + The functions underflow() and overflow() / sync() perform the actual I/O between the file and the get and put areas of the buffer. When CharT is not char, most implementations store multibyte characters in the file and a std::codecvt facet is used to perform wide/multibyte character conversion. - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - filebuf basic_filebuf - wfilebuf basic_filebuf + Type Definition + std::filebuf std::basic_filebuf + std::wfilebuf std::basic_filebuf .SH Member types - Member type Definition - char_type CharT - traits_type Traits - int_type Traits::int_type - pos_type Traits::pos_type which is required to be std::fpos - off_type Traits::off_type + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type which is required to be + std::fpos + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular .SH Member functions .SH Public member functions constructor constructs a basic_filebuf object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns a basic_filebuf object - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_filebuf objects - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP destructor destructs a basic_filebuf object and closes the file if it is open - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP is_open checks if the associated file is open - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function)\fP + \fI(public member function)\fP close flushes the put area buffer and closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP .SH Protected member functions showmanyc optionally provides the number of characters available for input from \fB[virtual]\fP the file - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP uflow reads from the associated file and advances the next pointer in the \fB[virtual]\fP get area - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP pbackfail backs out the input sequence to unget a character, not affecting the \fB[virtual]\fP associated file - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP overflow writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP setbuf provides user-supplied buffer or turns this filebuf unbuffered - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP seekoff repositions the file position, using relative addressing - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP seekpos repositions the file position, using absolute addressing - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP sync writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP imbue changes the associated locale - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Non-member functions std::swap(std::basic_filebuf) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_streambuf @@ -87,111 +97,151 @@ Inherited from std::basic_streambuf Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type .SH Member functions - destructor destructs the basic_streambuf object - \fB[virtual]\fP \fI(virtual public member function of std::basic_streambuf)\fP + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) .SH Locales - pubimbue invokes imbue() - \fI(public member function of std::basic_streambuf)\fP - getloc obtains a copy of the associated locale - \fI(public member function of std::basic_streambuf)\fP + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + .SH Positioning - pubsetbuf invokes setbuf() - \fI(public member function of std::basic_streambuf)\fP - pubseekoff invokes seekoff() - \fI(public member function of std::basic_streambuf)\fP - pubseekpos invokes seekpos() - \fI(public member function of std::basic_streambuf)\fP - pubsync invokes sync() - \fI(public member function of std::basic_streambuf)\fP + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + .SH Get area - in_avail obtains the number of characters immediately available in the get area - \fI(public member function of std::basic_streambuf)\fP - advances the input sequence, then reads one character without advancing - snextc again - \fI(public member function of std::basic_streambuf)\fP - sbumpc reads one character from the input sequence and advances the sequence - \fI(public member function of std::basic_streambuf)\fP - stossc advances the input sequence as if by calling sbumpc() and discarding - \fB(deprecated)\fP the result - \fI(public member function)\fP - reads one character from the input sequence without advancing the - sgetc sequence - \fI(public member function of std::basic_streambuf)\fP - sgetn invokes xsgetn() - \fI(public member function of std::basic_streambuf)\fP + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + .SH Put area - sputc writes one character to the put area and advances the next pointer - \fI(public member function of std::basic_streambuf)\fP - sputn invokes xsputn() - \fI(public member function of std::basic_streambuf)\fP + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + .SH Putback - sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP - sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + .SH Protected member functions constructor constructs a basic_streambuf object - \fI(protected member function)\fP + \fI(protected member function)\fP operator= replaces a basic_streambuf object - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP swap swaps two basic_streambuf objects - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP .SH Locales imbue changes the associated locale - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) .SH Positioning setbuf replaces the buffer with user-defined array, if permitted - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both, using relative addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekpos repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both using absolute addressing - \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) sync synchronizes the buffers with the associated character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) .SH Get area - showmanyc obtains the number of characters available for input in the associated - \fB[virtual]\fP input sequence, if known - \fI(virtual protected member function of std::basic_streambuf)\fP + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP - uflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP and advances the next pointer - \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) xsgetn reads multiple characters from the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) eback returns a pointer to the beginning, current character and the end of gptr the get area - egptr \fI(protected member function)\fP + egptr \fI(protected member function)\fP gbump advances the next pointer in the input sequence - \fI(protected member function)\fP + \fI(protected member function)\fP repositions the beginning, next, and end pointers of the input setg sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Put area xsputn writes multiple characters to the output sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) pbase returns a pointer to the beginning, current character and the end of pptr the put area - epptr \fI(protected member function)\fP + epptr \fI(protected member function)\fP pbump advances the next pointer of the output sequence - \fI(protected member function)\fP + \fI(protected member function)\fP repositions the beginning, next, and end pointers of the output setp sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Putback - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function of std::basic_streambuf)\fP + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH See also + + object type, capable of holding all information needed to control a C I/O + FILE stream + \fI(typedef)\fP diff --git a/man/std::basic_filebuf::basic_filebuf.3 b/man/std::basic_filebuf::basic_filebuf.3 index 1a11218d8..1c84686c4 100644 --- a/man/std::basic_filebuf::basic_filebuf.3 +++ b/man/std::basic_filebuf::basic_filebuf.3 @@ -1,21 +1,24 @@ -.TH std::basic_filebuf::basic_filebuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::basic_filebuf \- std::basic_filebuf::basic_filebuf + .SH Synopsis basic_filebuf(); \fB(1)\fP basic_filebuf( const std::basic_filebuf& rhs ) = delete; \fB(2)\fP \fI(since C++11)\fP basic_filebuf( std::basic_filebuf&& rhs ); \fB(3)\fP \fI(since C++11)\fP - Contructs new std::basic_filebuf object. + Constructs new std::basic_filebuf object. 1) Constructs a std::basic_filebuf object, initializing the base class by calling the default constructor of std::basic_streambuf. The created basic_filebuf is not associated with a file, and is_open() returns false. - 2) The copy constructor is deleted; std::basic_filebuf is not CopyConstructible + 2) The copy constructor is deleted; std::basic_filebuf is not CopyConstructible. 3) Move-constructs a std::basic_filebuf object by moving all contents from another std::basic_filebuf object rhs, including the buffers, the associated file, the locale, the openmode, the is_open variable, and all other state. After move, rhs is - not associated with a file and rhs.is_open()==false. The member pointers of the base - class std::basic_streambuf of rhs and of the base class of *this are guaranteed to - point to different buffers (unless null). + not associated with a file and rhs.is_open() == false. The member pointers of the + base class std::basic_streambuf of rhs and of the base class of *this are guaranteed + to point to different buffers (unless null). .SH Parameters @@ -33,10 +36,9 @@ .SH See also operator= assigns a basic_filebuf object - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP destructor destructs a basic_filebuf object and closes the file if it is open - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::close.3 b/man/std::basic_filebuf::close.3 index 68c97bb21..7126ff40d 100644 --- a/man/std::basic_filebuf::close.3 +++ b/man/std::basic_filebuf::close.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::close 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::close \- std::basic_filebuf::close + .SH Synopsis std::basic_filebuf* close(); @@ -16,7 +19,7 @@ If any of the function calls made, including the call to std::fclose(), fails, returns a null pointer. If any of the function calls made throws an exception, the - exception is caught and rethrown after calling std::fclose(). If the file is already + exception is caught and rethrown after closing the file. If the file is already closed, returns a null pointer right away. In any case, updates the private member variable that is accessed by is_open(). @@ -27,7 +30,7 @@ .SH Return value - *this on success, a null pointer on failure. + this on success, a null pointer on failure. .SH Notes @@ -39,13 +42,25 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 443 C++98 the file was written using changed to overflow(Traits::eof()) + overflow(EOF) + it was unclear how to handle + LWG 622 C++98 the it is rethrown after closing the + exception thrown during file + closing + .SH See also is_open checks if the associated file is open - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs a basic_filebuf object and closes the file if it is open - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::imbue.3 b/man/std::basic_filebuf::imbue.3 index e94894316..d0aad8e7b 100644 --- a/man/std::basic_filebuf::imbue.3 +++ b/man/std::basic_filebuf::imbue.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::imbue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::imbue \- std::basic_filebuf::imbue + .SH Synopsis protected: virtual void imbue( const std::locale& loc ) @@ -27,10 +30,10 @@ .SH See also imbue changes the associated locale - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + imbue sets the locale - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::is_open.3 b/man/std::basic_filebuf::is_open.3 index 81e139d81..e8cefa70c 100644 --- a/man/std::basic_filebuf::is_open.3 +++ b/man/std::basic_filebuf::is_open.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::is_open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::is_open \- std::basic_filebuf::is_open + .SH Synopsis bool is_open() const; @@ -19,12 +22,12 @@ .SH Example - + // Run this code #include #include - + int main() { std::ifstream fs("test.txt"); @@ -45,6 +48,6 @@ .SH See also open opens a file and configures it as the associated character sequence - \fI(public member function)\fP + \fI(public member function)\fP close flushes the put area buffer and closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_filebuf::native_handle.3 b/man/std::basic_filebuf::native_handle.3 new file mode 100644 index 000000000..43544dbf7 --- /dev/null +++ b/man/std::basic_filebuf::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_filebuf::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::native_handle \- std::basic_filebuf::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with *this. The + behavior is undefined if is_open() is false. + +.SH Return value + + implementation defined handle. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::basic_filebuf::open.3 b/man/std::basic_filebuf::open.3 index 8c68459ff..384c0b7ed 100644 --- a/man/std::basic_filebuf::open.3 +++ b/man/std::basic_filebuf::open.3 @@ -1,42 +1,70 @@ -.TH std::basic_filebuf::open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::open \- std::basic_filebuf::open + .SH Synopsis - std::basic_filebuf* open( const char* s, \fB(1)\fP - std::ios_base::openmode mode ) - std::basic_filebuf* open( const std::string& str, \fB(2)\fP \fI(since C++11)\fP - std::ios_base::openmode mode ) - - Opens the file with the given name - either s or str.c_str(). - - The file is opened as if by calling std::fopen(s, modestring), where modestring is - determined as follows: - - modestring openmode & ~ate - "r" in - "w" out, out|trunc - "a" app, out|app - "r+" out|in - "w+" out|in|trunc - "a+" out|in|app, in|app - "rb" binary|in - "wb" binary|out, binary|out|trunc - "ab" binary|app, binary|out|app - "r+b" binary|out|in - "w+b" binary|out|in|trunc - "a+b" binary|out|in|app, binary|in|app - - If openmode is not one of the modes listed, the open() fails. - - If the open operation succeeds and openmode & std::ios_base::ate != 0 (the ate bit + basic_filebuf* open( const char* s, std::ios_base::openmode mode \fB(1)\fP + ); + basic_filebuf* open( const std::string& str, \fB(2)\fP \fI(since C++11)\fP + std::ios_base::openmode mode ); + basic_filebuf* open( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode ); + basic_filebuf* open( const std::filesystem::path::value_type* s, \fB(4)\fP \fI(since C++17)\fP + std::ios_base::openmode mode ); + + If the associated file was already open (is_open() != false), returns a null pointer + right away. + + Otherwise, opens the file with the given name (s + , p.c_str() + \fI(since C++17)\fP or str.c_str(), depending on the overload). std::ios_base::openmode + values may be written as, e.g., std::ios_base::out | std::ios_base::app. + + Overload \fB(4)\fP is only provided if std::filesystem::path::value_type is \fI(since C++17)\fP + not char. + + The file is opened as if by calling std::fopen with the second argument (file access + mode) determined by the result of mode & ~std::ios_base::ate as follows, open() + fails if the result is not some combination of flags shown in the table: + + mode & ~std::ios_base::ate  std::fopen  Action if file Action if file + binary in out trunc app noreplace access already exists does not exist + (since C++23) mode + - + - - - - "r" Failure to + + + - - - - "rb" Read from start open + - + + - - - "r+" Error + + + + - - - "r+b" + - - + - - - "w" + - - + + - - + + - + - - - "wb" Destroy contents Create new + + - + + - - + - + + + - - "w+" + + + + + - - "w+b" + - - + - - + "wx" + - - + + - + + + - + - - + "wbx" Failure to open Create new + + - + + - + + - + + + - + "w+x" + + + + + - + "w+bx" + - - + - + - "a" + - - - - + - + + - + - + - "ab" + + - - - + - Write to end Create new + - + + - + - "a+" + - + - - + - + + + + - + - "a+b" + + + - - + - + + If the open operation succeeds and (openmode & std::ios_base::ate) != 0 (the ate bit is set), repositions the file position to the end of file, as if by calling - std::fseek(file, 0, SEEK_END). If the repositioning fails, calls close() and returns - a null pointer to indicate failure. - - If the associated file was already open, returns a null pointer right away. + std::fseek(file, 0, SEEK_END), where file is the pointer returned by calling + std::fopen. If the repositioning fails, calls close() and returns a null pointer to + indicate failure. .SH Parameters - s, str - the file name to open - openmode - the file opening mode, a binary OR of the std::ios_base modes + s, str, p - the file name to open; s must point to a null-terminated string + openmode - the file opening mode, a binary OR of the std::ios_base::openmode modes .SH Return value @@ -49,16 +77,58 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + std::string filename = "Test.b"; + std::filebuf fb; + + // prepare a file to read + double d = 3.14; + if (!fb.open(filename, std::ios::binary | std::ios::out)) + { + std::cout << "Open file " << filename << " for write failed\\n"; + return 1; + } + fb.sputn(reinterpret_cast(&d), sizeof d); + fb.close(); + + // open file for reading + double d2 = 0.0; + if (!fb.open(filename, std::ios::binary | std::ios::in)) + { + std::cout << "Open file " << filename << " for read failed\\n"; + return 1; + } + + auto got = fb.sgetn(reinterpret_cast(&d2), sizeof d2); + if (sizeof(d2) != got) + std::cout << "Read of " << filename << " failed\\n"; + else + std::cout << "Read back from file: " << d2 << '\\n'; + } + +.SH Output: + + Read back from file: 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 596 C++98 open() could not open files in append can open in append mode + mode .SH See also is_open checks if the associated file is open - \fI(public member function)\fP + \fI(public member function)\fP close flushes the put area buffer and closes the associated file - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::basic_filebuf::operator=.3 b/man/std::basic_filebuf::operator=.3 index b12111e48..a0532ed24 100644 --- a/man/std::basic_filebuf::operator=.3 +++ b/man/std::basic_filebuf::operator=.3 @@ -1,7 +1,10 @@ -.TH std::basic_filebuf::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::operator= \- std::basic_filebuf::operator= + .SH Synopsis - std::basic_filebuf& operator=( std::basic_filebuf&& rhs ); \fI(since C++11)\fP - std::basic_filebuf& operator=( const std::basic_filebuf& rhs ) = + std::basic_filebuf& operator=( std::basic_filebuf&& rhs ); \fB(1)\fP \fI(since C++11)\fP + std::basic_filebuf& operator=( const std::basic_filebuf& rhs ) = \fB(2)\fP delete; Assigns another basic_filebuf object. @@ -22,35 +25,40 @@ .SH Example - + // Run this code + #include #include - #include #include - + #include + int main() { - - std::ifstream fin("test.in"); // read-only - std::ofstream fout("test.out"); // write-only - + std::ofstream{"test.in"} << "test\\n"; // writes via a temporary object + std::ifstream fin("test.in"); // read-only stream + std::ofstream fout("test.out"); // write-only stream + std::string s; - getline(fin, s); - std::cout << s << '\\n'; // output - + std::getline(fin, s); + std::cout << "s = [" << s << "]\\n"; // s contains "test" + + assert(fout.is_open()); *fin.rdbuf() = std::move(*fout.rdbuf()); - - getline(fin, s); - std::cout << s << '\\n'; // empty line - - std::cout << std::boolalpha << fout.is_open() << '\\n'; // prints "false" - + assert(!fout.is_open()); + + std::getline(fin, s); + std::cout << "s = [" << s << "]\\n"; // s is empty input } +.SH Output: + + s = [test] + s = [] + .SH See also constructor constructs a basic_filebuf object - \fI(public member function)\fP + \fI(public member function)\fP swap swaps two basic_filebuf objects - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::basic_filebuf::overflow.3 b/man/std::basic_filebuf::overflow.3 index 7ccf6aee5..4136ce654 100644 --- a/man/std::basic_filebuf::overflow.3 +++ b/man/std::basic_filebuf::overflow.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::overflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::overflow \- std::basic_filebuf::overflow + .SH Synopsis protected: virtual int_type overflow ( int_type c = Traits::eof() ); @@ -7,11 +10,14 @@ file). Behaves like the base class std::basic_streambuf::overflow, except that to write the - data, first uses codecvt::out() of the imbued locale to convert the characters into - external (possibly multibyte) representation, stored in a temporary buffer + data, first uses std::codecvt::out of the imbued locale to convert the characters + into external (possibly multibyte) representation, stored in a temporary buffer (allocated as large as necessary), then uses file I/O to copy all fully-converted bytes into the file. + If std::codecvt::always_noconv is true, the call to std::codecvt::out may be + skipped. + If the conversion fails with std::codecvt_base::error, returns Traits::eof() without attempting any output. @@ -34,10 +40,10 @@ .SH See also overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::pbackfail.3 b/man/std::basic_filebuf::pbackfail.3 index 563967fb1..6fde947cd 100644 --- a/man/std::basic_filebuf::pbackfail.3 +++ b/man/std::basic_filebuf::pbackfail.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::pbackfail 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::pbackfail \- std::basic_filebuf::pbackfail + .SH Synopsis protected: virtual int_type pbackfail( int_type c = Traits::eof() ) @@ -47,18 +50,18 @@ .SH See also - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function of std::basic_streambuf)\fP + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::seekoff.3 b/man/std::basic_filebuf::seekoff.3 index 2b3eb7c84..2ce6f772b 100644 --- a/man/std::basic_filebuf::seekoff.3 +++ b/man/std::basic_filebuf::seekoff.3 @@ -1,39 +1,42 @@ -.TH std::basic_filebuf::seekoff 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::seekoff \- std::basic_filebuf::seekoff + .SH Synopsis protected: virtual pos_type seekoff( off_type off, - std::ios_base::seekdir way, + std::ios_base::seekdir dir, std::ios_base::openmode which = std::ios_base::in | std::ios_base::out ); Repositions the file pointer, if possible, to the position that corresponds to exactly off characters from beginning, end, or current position of the file - (depending on the value of way. + (depending on the value of dir). - If the associated file is not open (is_open()==false, fails immediately. + If the associated file is not open (is_open() == false), fails immediately. If the multibyte character encoding is state-dependent (codecvt::encoding() returned - -1) or variable-length (codecvt::encoding() returned 0) and the offset off is not - 0, fails immediately: this function cannot determine the number of bytes that + -1) or variable-length (codecvt::encoding() returned 0) and the offset off is not 0, + fails immediately: this function cannot determine the number of bytes that correspond to off characters. - If way is not std::basic_ios::cur or the offset off is not 0, and the most resent + If dir is not std::basic_ios::cur or the offset off is not 0, and the most recent operation done on this filebuf object was output (that is, either the put buffer is not empty, or the most recently called function was overflow()), then calls std::codecvt::unshift to determine the unshift sequence necessary, and writes that sequence to the file by calling overflow(). - Then converts the argument way to a value whence of type int as follows: + Then converts the argument dir to a value whence of type int as follows: - value of way value of whence + value of dir value of whence std::basic_ios::beg SEEK_SET std::basic_ios::end SEEK_END std::basic_ios::cur SEEK_CUR Then, if the character encoding is fixed-width (codecvt::encoding() returns some - positive number width, moves the file pointer as if by std::fseek(file, width*off, + positive number width), moves the file pointer as if by std::fseek(file, width*off, whence). Otherwise, moves the file pointer as if by std::fseek(file, 0, whence). @@ -43,7 +46,7 @@ .SH Parameters - off - relative position to set the position indicator to. + off - relative position to set the position indicator to defines base position to apply the relative offset to. It can be one of the following constants: @@ -67,37 +70,47 @@ seekoff() is called by std::basic_streambuf::pubseekoff, which is called by std::basic_istream::seekg, std::basic_ostream::seekp, std::basic_istream::tellg, and - std::basic_ostream::tellp + std::basic_ostream::tellp. .SH Example - + // Run this code - #include #include + #include #include + + template + int get_encoding(const std::basic_istream& stream) + { + using Facet = std::codecvt; + return std::use_facet(stream.getloc()).encoding(); + } + int main() { - // prepare a 10-byte file holding 4 characters in UTF8 - std::ofstream("text.txt") << u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; - + // prepare a 10-byte file holding 4 characters ("zß水𝄋") in UTF-8 + std::ofstream("text.txt") << "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + // open using a non-converting encoding std::ifstream f1("text.txt"); std::cout << "f1's locale's encoding() returns " - << std::use_facet>(f1.getloc()).encoding() << '\\n' - << "pubseekoff(3, beg) returns " << f1.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' - << "pubseekoff(0, end) returns " << f1.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n';; - + << get_encoding(f1) << '\\n' + << "pubseekoff(3, beg) returns " + << f1.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' + << "pubseekoff(0, end) returns " + << f1.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; + // open using UTF-8 std::wifstream f2("text.txt"); f2.imbue(std::locale("en_US.UTF-8")); std::cout << "f2's locale's encoding() returns " - << std::use_facet>(f2.getloc()).encoding() << '\\n' - << "pubseekoff(3, beg) returns " << f2.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' - << "pubseekoff(0, end) returns " << f2.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; - + << get_encoding(f2) << '\\n' + << "pubseekoff(3, beg) returns " + << f2.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' + << "pubseekoff(0, end) returns " + << f2.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; } .SH Output: @@ -109,11 +122,20 @@ pubseekoff(3, beg) returns -1 pubseekoff(0, end) returns 10 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + .SH See also pubseekoff invokes seekoff() - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP seekpos repositions the file position, using absolute addressing - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP fseek moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_filebuf::seekpos.3 b/man/std::basic_filebuf::seekpos.3 index 7e76514d5..8996817bc 100644 --- a/man/std::basic_filebuf::seekpos.3 +++ b/man/std::basic_filebuf::seekpos.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::seekpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::seekpos \- std::basic_filebuf::seekpos + .SH Synopsis protected: @@ -7,16 +10,15 @@ std::ios_base::openmode which = std::ios_base::in | std::ios_base::out ); - Repositions the file pointer, if possible, to the position indicated by sp. - - If the associated file is not open (is_open()==false), fails immediately. - - If the file is open for writing, first writes the put area and any unshift sequences - required by the currently imbued locale, using overflow() + Repositions the file pointer, if possible, to the position indicated by sp. If the + associated file is not open (is_open() == false), fails immediately. - Then repositions the file pointer, as by calling std::fseek() + Reposition performs as follows: - If the file is open for reading, updates the get area if necessary. + 1) If the file is open for writing, writes the put area and any unshift sequences + required by the currently imbued locale, using overflow(). + 2) Repositions the file pointer, as if by calling std::fsetpos(). + 3) If the file is open for reading, updates the get area if necessary. If sp was not obtained by calling seekoff() or seekpos() on the same file, the behavior is undefined. @@ -40,42 +42,46 @@ seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the single-argument versions of std::basic_istream::seekg() and - std::basic_ostream::seekp() + std::basic_ostream::seekp(). Many implementations do not update the get area in seekpos(), delegating to - underflow() that is called by the nest sgetc() + underflow() that is called by the next sgetc(). .SH Example - on some implementations, the get area is emptied by seekpos() and the second - underflow() is necessary to observe the effects + On some implementations, the get area is emptied by seekpos() and the second + underflow() is necessary to observe the effects. + - // Run this code #include #include - + struct mybuf : std::filebuf { - pos_type seekpos(pos_type sp, std::ios_base::openmode which) { - std::cout << "Before seekpos(" << sp << "), size of the get area is " - << egptr()-eback() << " with " - << egptr()-gptr() << " read positions available\\n"; - pos_type rc = std::filebuf::seekpos(sp, which); - std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " - << "size of the get area is " - << egptr()-eback() << " with " - << egptr()-gptr() << " read positions available\\n"; + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::filebuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; // uncomment if get area is emptied by seekpos() - // std::filebuf::underflow(); - // std::cout << "after forced underflow(), size of the get area is " - // << egptr()-eback() << " with " - // << egptr()-gptr() << " read positions available\\n"; + // std::filebuf::underflow(); + // std::cout << "after forced underflow(), size of the get area is " + // << egptr() - eback() << " with " + // << egptr() - gptr() << " read positions available.\\n"; + return rc; } }; - + int main() { mybuf buf; @@ -87,15 +93,26 @@ .SH Possible output: - Before seekpos\fB(2)\fP, size of the get area is 110 with 109 read positions available + Before seekpos\fB(2)\fP, size of the get area is 110 with 109 read positions available. seekpos() returns 2. - After the call, size of the get area is 110 with 108 read positions available + After the call, size of the get area is 110 with 108 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekpos returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + LWG 171 C++98 the sequence of the operations of made clear + reposition was not clear .SH See also pubseekpos invokes seekpos() - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP seekoff repositions the file position, using relative addressing - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP fseek moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_filebuf::setbuf.3 b/man/std::basic_filebuf::setbuf.3 index 32a6648c7..1f795b151 100644 --- a/man/std::basic_filebuf::setbuf.3 +++ b/man/std::basic_filebuf::setbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::setbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::setbuf \- std::basic_filebuf::setbuf + .SH Synopsis protected: virtual std::basic_streambuf* setbuf( char_type* s, std::streamsize @@ -17,12 +20,12 @@ .SH Parameters - s - pointer to the first byte in the user-provided buffer or null - n - the number of bytes in the user-provided buffer or zero + s - pointer to the first CharT in the user-provided buffer or null + n - the number of CharT elements in the user-provided buffer or zero .SH Return value - *this, cast to the base class std::basic_streambuf. + this .SH Notes @@ -34,13 +37,11 @@ setbuf() may only be called when the std::basic_filebuf is not associated with a file (has no effect otherwise). With a user-provided buffer, reading from file reads n-1 bytes at a time. - * Clang++3.0 libc++ setbuf() may be called after opening the file, but before any I/O (may crash otherwise). With a user-provided buffer, reading from file reads largest multiples of 4096 that fit in the buffer. - * Visual Studio 2010 setbuf() may be called at any time, even after some I/O took place. Current contents @@ -51,33 +52,46 @@ .SH Example - provide a 10k buffer for reading. On linux, the strace utility may be used to - observe the actual number of bytes read + Provides a 10k buffer for reading. On linux, the strace utility may be used to + observe the actual number of bytes read. + - // Run this code #include #include #include - + int main() { - int cnt = 0; - std::ifstream file; - char buf[10241]; - - file.rdbuf()->pubsetbuf(buf, sizeof buf); - file.open("/usr/share/dict/words"); - - for (std::string line; getline(file, line); ) - ++cnt; - std::cout << cnt << '\\n'; + int cnt = 0; + std::ifstream file; + char buf[10241]; + + file.rdbuf()->pubsetbuf(buf, sizeof buf); + file.open("/usr/share/dict/words"); + + for (std::string line; getline(file, line);) + ++cnt; + std::cout << cnt << '\\n'; } +.SH Possible output: + + 356010 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 173 C++98 the type of n was misspecified as corrected to std::streamsize + int + .SH See also pubsetbuf invokes setbuf() - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP setvbuf sets the buffer and its size for a file stream - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_filebuf::showmanyc.3 b/man/std::basic_filebuf::showmanyc.3 index 5ada06043..5bee45bae 100644 --- a/man/std::basic_filebuf::showmanyc.3 +++ b/man/std::basic_filebuf::showmanyc.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::showmanyc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::showmanyc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::showmanyc \- std::basic_filebuf::showmanyc + .SH Synopsis protected: virtual std::streamsize showmanyc() @@ -22,35 +25,38 @@ Whether implemented or not, this function is normally called by std::basic_streambuf::in_avail if the get area is empty. + The name of this function stands for "stream: how many characters?", so it is + pronounced "S how many C", rather than "show many C" + .SH Example implementation test to see if showmanyc() is implemented for filebuf - + // Run this code #include #include - + struct mybuf : std::filebuf { using std::filebuf::showmanyc; }; - + int main() { mybuf fin; - fin.open("test.in", std::ios_base::in); + fin.open("main.cpp", std::ios_base::in); std::cout << "showmanyc() returns " << fin.showmanyc() << '\\n'; } -.SH Output: +.SH Possible output: - showmanyc() returns 6626 + showmanyc() returns 267 .SH See also in_avail obtains the number of characters immediately available in the get area - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_filebuf::swap.3 b/man/std::basic_filebuf::swap.3 index 6af0bc95f..cae59ea19 100644 --- a/man/std::basic_filebuf::swap.3 +++ b/man/std::basic_filebuf::swap.3 @@ -1,6 +1,9 @@ -.TH std::basic_filebuf::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::swap \- std::basic_filebuf::swap + .SH Synopsis - void swap( std::basic_filebuf& rhs ) \fI(since C++11)\fP + void swap( std::basic_filebuf& rhs ); \fI(since C++11)\fP Swaps the state and the contents of *this and rhs. @@ -19,24 +22,24 @@ .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::ifstream fin("test.in"); // read-only std::ofstream fout("test.out"); // write-only - + std::string s; getline(fin, s); std::cout << s << '\\n'; // outputs the first line of test.in - + fin.rdbuf()->swap(*fout.rdbuf()); //swap the underlying buffers - + getline(fin, s); // fails: cannot read from a write-only filebuf std::cout << s << '\\n'; // prints empty line } @@ -44,8 +47,9 @@ .SH See also operator= assigns a basic_filebuf object - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP std::swap(std::basic_filebuf) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP swap swaps two file streams - \fI(C++11)\fP \fI(public member function of std::basic_fstream)\fP + \fI(C++11)\fP \fI\fI(public member\fP function of\fP + std::basic_fstream) diff --git a/man/std::basic_filebuf::sync.3 b/man/std::basic_filebuf::sync.3 index 7f6d4a189..f32ce2eaf 100644 --- a/man/std::basic_filebuf::sync.3 +++ b/man/std::basic_filebuf::sync.3 @@ -1,10 +1,14 @@ -.TH std::basic_filebuf::sync 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::sync \- std::basic_filebuf::sync + .SH Synopsis protected: virtual int sync() If a put area exists (e.g. the file was opened for writing), calls overflow() to - write all pending output to the file. + write all pending output to the file, then flushes the file as if by calling + std::fflush. If a get area exists (e.g. the file was opened for reading), the effect is implementation-defined. Typical implementation may empty out the get area and move @@ -20,8 +24,8 @@ .SH Notes - sync() or its equivalent is implicitly called by close(), seekoff(), and seekpos() - and explicitly called by std::basic_streambuf::pubsync() + sync() or its equivalent is implicitly called for output streams by close(), + seekoff(), and seekpos() and explicitly called by std::basic_streambuf::pubsync() .SH Example @@ -31,10 +35,9 @@ .SH See also pubsync invokes sync() - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP fflush synchronizes an output stream with the actual file - \fI(function)\fP + \fI(function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::uflow.3 b/man/std::basic_filebuf::uflow.3 index 6694a89ef..299084c3e 100644 --- a/man/std::basic_filebuf::uflow.3 +++ b/man/std::basic_filebuf::uflow.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::uflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::uflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::uflow \- std::basic_filebuf::uflow + .SH Synopsis protected: virtual int_type uflow() @@ -23,14 +26,14 @@ .SH See also - uflow reads characters from the associated input sequence to the get area and - \fB[virtual]\fP advances the next pointer - \fI(virtual protected member function of std::basic_streambuf)\fP + reads characters from the associated input sequence to the get area and + uflow advances the next pointer + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP overflow writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_filebuf::underflow.3 b/man/std::basic_filebuf::underflow.3 index 2b44086c0..7dc11e56a 100644 --- a/man/std::basic_filebuf::underflow.3 +++ b/man/std::basic_filebuf::underflow.3 @@ -1,4 +1,7 @@ -.TH std::basic_filebuf::underflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::underflow \- std::basic_filebuf::underflow + .SH Synopsis protected: virtual int_type underflow() @@ -11,7 +14,7 @@ necessary), then uses std::codecvt::in of the imbued locale to convert the external (typically, multibyte) representation to the internal form which is then used to populate the get area. The conversion may be skipped if the locale's - std::codecvt::always_noconv returns true + std::codecvt::always_noconv returns true. .SH Parameters @@ -24,15 +27,16 @@ .SH Example - + // Run this code #include #include - + struct mybuf : std::filebuf { - int underflow() { + int underflow() + { std::cout << "Before underflow(): size of the get area is " << egptr()-eback() << " with " << egptr()-gptr() << " read positions available\\n"; @@ -44,13 +48,13 @@ return rc; } }; - + int main() { mybuf buf; buf.open("test.txt", std::ios_base::in); std::istream stream(&buf); - while(stream.get()) ; + while (stream.get()) ; } .SH Possible output: @@ -65,16 +69,18 @@ .SH See also underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + underflow returns the next character available in the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) underflow reads a character from the input sequence without advancing the next \fB[virtual]\fP pointer - \fI(virtual protected member function of std::strstreambuf)\fP + \fI(virtual protected member function of std::strstreambuf)\fP uflow reads from the associated file and advances the next pointer in the get \fB[virtual]\fP area - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP overflow writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP sgetc reads one character from the input sequence without advancing the sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::basic_filebuf::~basic_filebuf.3 b/man/std::basic_filebuf::~basic_filebuf.3 index 3ce77fbe2..788f635a4 100644 --- a/man/std::basic_filebuf::~basic_filebuf.3 +++ b/man/std::basic_filebuf::~basic_filebuf.3 @@ -1,10 +1,14 @@ -.TH std::basic_filebuf::~basic_filebuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_filebuf::~basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::~basic_filebuf \- std::basic_filebuf::~basic_filebuf + .SH Synopsis - virtual ~basic_filebuf(); + virtual ~basic_filebuf(); Calls close() to close the associated file and destructs all other members of - basic_filebuf. If an exception is thrown by close(), it is caught and not rethrown. + basic_filebuf. If an exception occurs during the destruction of the object, + including the call to close(), it is caught and not rethrown. .SH Parameters @@ -23,13 +27,21 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 622 C++98 it was unclear how to handle the exception it is caught but not + thrown during destruction rethrown + .SH See also constructor constructs a basic_filebuf object - \fI(public member function)\fP + \fI(public member function)\fP close flushes the put area buffer and closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_format_arg.3 b/man/std::basic_format_arg.3 new file mode 100644 index 000000000..1adf1ddcb --- /dev/null +++ b/man/std::basic_format_arg.3 @@ -0,0 +1,111 @@ +.TH std::basic_format_arg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_format_arg \- std::basic_format_arg + +.SH Synopsis + Defined in header + template< class Context > \fI(since C++20)\fP + class basic_format_arg; + + Provides access to a formatting argument. + + basic_format_arg objects are typically created by std::make_format_args and accessed + through std::visit_format_arg + or the visit member functions + (since C++26). + + A basic_format_arg object behaves as if it stores a std::variant of the following + types: + + * std::monostate (only if the object was default-constructed) + * bool + * Context::char_type + * int + * unsigned int + * long long int + * unsigned long long int + * float + * double + * long double + * const Context::char_type* + * std::basic_string_view + * const void* + * basic_format_arg::handle + +.SH Member classes + + handle type-erased wrapper that allows formatting an object of user-defined type + (C++20) \fI(public member class)\fP + +.SH Member functions + + constructor constructs a std::basic_format_arg + (C++20) \fI(public member function)\fP + operator bool checks if the current object holds a formatting argument + (C++20) \fI(public member function)\fP + visit visit the stored formatting argument + (C++26) \fI(public member function)\fP + +.SH Non-member functions + + visit_format_arg argument visitation interface for user-defined + (C++20) (deprecated in C++26) formatters + \fI(function template)\fP + +std::basic_format_arg::basic_format_arg + + basic_format_arg() noexcept; \fI(since C++20)\fP + + Default constructor. Constructs a basic_format_arg that does not hold a formatting + argument. The stored object has type std::monostate. + + To create a basic_format_arg that holds a formatting argument, std::make_format_args + has to be used. + +std::basic_format_arg::operator bool + + explicit operator bool() const noexcept; \fI(since C++20)\fP + + Checks whether *this holds a formatting argument. + + Returns true if *this holds a formatting argument (i.e. the stored object does not + have type std::monostate), false otherwise. + +std::basic_format_arg::visit + + template< class Visitor > \fB(1)\fP (since C++26) + decltype(auto) visit( this basic_format_arg arg, Visitor&& vis ); + template< class R, class Visitor > \fB(2)\fP (since C++26) + R visit( this basic_format_arg arg, Visitor&& vis ); + + Applies the visitor vis to the object contained in arg. + + The visit functions do not modify the basic_format_arg object on which it is called + because a copy of the object is used when calling vis. + + 1) Equivalent to return std::visit(std::forward(vis), v);, where v is the + std::variant stored in arg. + 2) Equivalent to return std::visit(std::forward(vis), v);, where v is + the std::variant stored in arg. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_format 202306L (C++26) Member visit + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + basic_format_args + format_args + wformat_args class that provides access to all formatting arguments + (C++20) \fI(class template)\fP + (C++20) + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::basic_format_arg::handle.3 b/man/std::basic_format_arg::handle.3 new file mode 100644 index 000000000..e89b41123 --- /dev/null +++ b/man/std::basic_format_arg::handle.3 @@ -0,0 +1,55 @@ +.TH std::basic_format_arg::handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_format_arg::handle \- std::basic_format_arg::handle + +.SH Synopsis + Defined in header + template< class Context > \fI(since C++20)\fP + class basic_format_arg::handle; + + A type-erased wrapper that allows formatting an object of a user-defined type. + + handle objects are typically created by std::make_format_args and accessed through + std::visit_format_arg + or the visit member functions of std::basic_format_arg + (since C++26). + +.SH Member functions + + format formats the referenced object with the given contexts + (C++20) \fI(public member function)\fP + +std::basic_format_arg::handle::format + + void format( std::basic_format_parse_context& (since + parse_ctx, C++20) + Context& format_ctx ) const; + + Let + + * T be the type of the formatting argument, + * TD be std::remove_const_t, + * TQ be const TD if const TD satisfies __formattable_with or TD + otherwise, and + * ref be a reference to the formatting argument. + + Equivalent to: typename Context::template formatter_type f; + parse_ctx.advance_to(f.parse(parse_ctx)); + format_ctx.advance_to(f.format(const_cast(static_cast(ref)), + format_ctx)); + +.SH Notes + + A handle has reference semantics for the formatted argument and does not extend its + lifetime. It is the programmer's responsibility to ensure that the argument outlives + the handle. Usually, a handle is only used within formatting functions. + +.SH See also + + basic_format_arg class template that provides access to a formatting argument for + (C++20) user-defined formatters + \fI(class template)\fP + make_format_args creates a type-erased object referencing all formatting arguments, + make_wformat_args convertible to format_args + (C++20) \fI(function template)\fP + (C++20) diff --git a/man/std::basic_format_args.3 b/man/std::basic_format_args.3 new file mode 100644 index 000000000..5143ba3b9 --- /dev/null +++ b/man/std::basic_format_args.3 @@ -0,0 +1,75 @@ +.TH std::basic_format_args 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_format_args \- std::basic_format_args + +.SH Synopsis + Defined in header + template< class Context > \fB(1)\fP \fI(since C++20)\fP + class basic_format_args; + using format_args = basic_format_args; \fB(2)\fP \fI(since C++20)\fP + using wformat_args = basic_format_args; \fB(3)\fP \fI(since C++20)\fP + + Provides access to formatting arguments. + +.SH Member functions + + constructor constructs a basic_format_args object + \fI(public member function)\fP + get returns formatting argument at the given index + \fI(public member function)\fP + +std::basic_format_args::basic_format_args + + basic_format_args() noexcept; \fB(1)\fP + template< class... Args > + basic_format_args( const /*format-arg-store*/& store ) \fB(2)\fP + noexcept; + + 1) Constructs a basic_format_args object that does not hold any formatting argument. + 2) Constructs a basic_format_args object from the result of a call to + std::make_format_args or std::make_wformat_args. + + std::basic_format_args has reference semantics. It is the programmer's + responsibility to ensure that *this does not outlive store (which, in turn, should + not outlive the arguments to std::make_format_args or std::make_wformat_args). + +std::basic_format_args::get + + std::basic_format_arg get( std::size_t i ) const noexcept; + + Returns a std::basic_format_arg holding the i-th argument in args, where args is the + parameter pack passed to std::make_format_args or std::make_wformat_args. + + If there's no such formatting argument (i.e. *this was default-constructed or i is + not less than the number of formatting arguments), returns a default-constructed + std::basic_format_arg (holding a std::monostate object). + + Deduction guides + + template< class Context, class... Args > + basic_format_args( /*format-arg-store*/ ) -> \fI(since C++20)\fP + basic_format_args; + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2216R3 C++20 format_args_t was provided due to removed + overparameterization of vformat_to + LWG3810 C++20 basic_format_args has no deduction guide added + +.SH See also + + basic_format_arg class template that provides access to a formatting argument for + (C++20) user-defined formatters + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_format_context.3 b/man/std::basic_format_context.3 new file mode 100644 index 000000000..013550a4e --- /dev/null +++ b/man/std::basic_format_context.3 @@ -0,0 +1,102 @@ +.TH std::basic_format_context 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_format_context \- std::basic_format_context + +.SH Synopsis + Defined in header + template< class OutputIt, class CharT > \fB(1)\fP \fI(since C++20)\fP + class basic_format_context; + using format_context = basic_format_context; + using wformat_context = basic_format_context; + + Provides access to formatting state consisting of the formatting arguments and the + output iterator. + + 2) The unspecified template argument is an output iterator that appends to + std::string, such as std::back_insert_iterator. Implementations + typically use an iterator to type-erased buffer type that supports appending to any + contiguous and resizable container. + 3) The unspecified template argument is an output iterator that appends to + std::wstring. + + The behavior is undefined if OutputIt does not model std::output_iterator. + + A program that declares an explicit or partial specialization of + std::basic_format_context is ill-formed, no diagnostic required. + +.SH Member types + + Type Definition + iterator OutputIt + char_type CharT + +.SH Member alias templates + + Type Definition + formatter_type std::formatter + +.SH Member functions + + arg returns the argument at the given index + \fI(public member function)\fP + locale returns the locale used for locale-specific formatting + \fI(public member function)\fP + out returns the iterator to output buffer + \fI(public member function)\fP + advance_to advances the output iterator to the given position + \fI(public member function)\fP + +std::basic_format_context::arg + + std::basic_format_arg arg( std::size_t id ) const; + + Returns a std::basic_format_arg holding the id-th argument in args, where args is + the parameter pack or std::basic_format_args object passed to the formatting + function. + + If id is not less than the number of formatting arguments, returns a + default-constructed std::basic_format_arg (holding a std::monostate object). + +std::basic_format_context::locale + + std::locale locale(); + + Returns the locale passed to the formatting function, or a default-constructed + std::locale if the formatting function does not take a locale. + +std::basic_format_context::out + + iterator out(); + + Returns the iterator to the output buffer. The result is move-constructed from the + stored iterator. + +std::basic_format_context::advance_to + + void advance_to( iterator it ); + + Move assigns it to the stored output iterator. After a call to advance_to, the next + call to out() will return an iterator with the value that it had before the + assignment. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3567 C++20 basic_format_context does not work move-only made to move + iterator types iterators + LWG 3975 C++20 user specialization of basic_format_context disallowed + was allowed + +.SH Category: + * Todo no example diff --git a/man/std::basic_format_parse_context.3 b/man/std::basic_format_parse_context.3 new file mode 100644 index 000000000..650c1f819 --- /dev/null +++ b/man/std::basic_format_parse_context.3 @@ -0,0 +1,186 @@ +.TH std::basic_format_parse_context 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_format_parse_context \- std::basic_format_parse_context + +.SH Synopsis + Defined in header + template< class CharT > \fI(since C++20)\fP + class basic_format_parse_context; + + Provides access to the format string parsing state consisting of the format string + range being parsed and the argument counter for automatic indexing. + + A std::basic_format_parse_context instance is passed to Formatter when parsing the + format specification. + + A program that declares an explicit or partial specialization of + std::basic_format_parse_context is ill-formed, no diagnostic required. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::format_parse_context std::basic_format_parse_context + std::wformat_parse_context std::basic_format_parse_context + +.SH Member types + + Type Definition + char_type CharT + iterator std::basic_string_view::const_iterator + const_iterator std::basic_string_view::const_iterator + +.SH Member functions + + constructs a std::basic_format_parse_context instance + constructor from format string and argument count + \fI(public member function)\fP + operator= std::basic_format_parse_context is not copyable + [deleted] \fI(public member function)\fP + returns an iterator to the beginning of the format + begin string range + \fI(public member function)\fP + returns an iterator to the end of the format string + end range + \fI(public member function)\fP + advance_to advances the begin iterator to the given position + \fI(public member function)\fP + enters automatic indexing mode, and returns the next + next_arg_id argument index + \fI(public member function)\fP + enters manual indexing mode, checks if the given + check_arg_id argument index is in range + \fI(public member function)\fP + checks if the type of the corresponding format argument + check_dynamic_spec with the given argument index is in the given type + (C++26) template arguments + \fI(public member function)\fP + check_dynamic_spec_integral checks if the type of the corresponding format argument + (C++26) with the given argument index is an integral type + \fI(public member function)\fP + check_dynamic_spec_string checks if the type of the corresponding format argument + (C++26) with the given argument index is a string type + \fI(public member function)\fP + +std::basic_format_parse_context::basic_format_parse_context + + constexpr explicit + + basic_format_parse_context( std::basic_string_view fmt, (until C++26) + + std::size_t num_args = 0 ) + noexcept; \fB(1)\fP + constexpr explicit + basic_format_parse_context( std::basic_string_view fmt (since C++26) + ) noexcept; + basic_format_parse_context( const basic_format_parse_context& \fB(2)\fP + ) = delete; + + 1) Constructs a std::basic_format_parse_context instance. Initializes the format + string range to [fmt.begin(), fmt.end()), and the argument count to + num_args + (until C++26) + 0 + (since C++26). + + Any call to next_arg_id, check_arg_id, or check_dynamic_spec on an + instance of std::basic_format_parse_context initialized using this (since C++26) + constructor is not a core constant expression. + + 2) The copy constructor is deleted. std::basic_format_parse_context is not copyable. + +std::basic_format_parse_context::begin + + constexpr const_iterator begin() const noexcept; + + Returns an iterator to the beginning of the format string range. + +std::basic_format_parse_context::end + + constexpr const_iterator end() const noexcept; + + Returns an iterator to the end of the format string range. + +std::basic_format_parse_context::advance_to + + constexpr void advance_to( const_iterator it ); + + Sets the beginning of the format string range to it. After a call to advance_to(), + subsequent calls to begin() will return a copy of it. + + The behavior is undefined if end() is not reachable from it. + +std::basic_format_parse_context::next_arg_id + + constexpr std::size_t next_arg_id(); + + Enters automatic argument indexing mode, and returns the next argument index, + starting from 0. + + If *this has already entered manual argument indexing mode, throws + std::format_error. + + If the next argument index is larger than or equal to the num_args provided in the + constructor, the call is not a core constant expression. + +std::basic_format_parse_context::check_arg_id + + constexpr void check_arg_id( std::size_t id ); + + Enters manual argument indexing mode. + + If *this has already entered automatic argument indexing mode, throws + std::format_error. + + If id is larger than or equal to the num_args provided in the constructor, the call + is not a core constant expression. + +std::basic_format_parse_context::check_dynamic_spec + + template< class... Ts > (since C++26) + constexpr void check_dynamic_spec( std::size_t id ) noexcept; + + If id is larger than or equal to the num_args provided in the constructor or the + type of the corresponding format argument (after conversion to + std::basic_format_arg) is not one of the types in Ts..., the call is not a core + constant expression. A call to check_dynamic_spec has no effect at runtime. + + * This overload participates in overload resolution only if the types in Ts... are + unique and each type is one of bool, char_type, int, unsigned int, long long + int, unsigned long long int, float, double, long double, const char_type*, + std::basic_string_view, or const void*. + +std::basic_format_parse_context::check_dynamic_spec_integral + + constexpr void check_dynamic_spec_integral( std::size_t id ) (since C++26) + noexcept; + + Equivalent to call check_dynamic_spec(id). A call to check_dynamic_spec_integral has no effect at runtime. + +std::basic_format_parse_context::check_dynamic_spec_string + + constexpr void check_dynamic_spec_string( std::size_t id ) noexcept; (since C++26) + + Equivalent to call check_dynamic_spec>(id). A call to check_dynamic_spec_string has no + effect at runtime. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3825 C++20 check_arg_id has a compile-time argument added + id check, but next_arg_id did not have + LWG 3975 C++20 user specialization of disallowed + basic_format_parse_context was allowed + +.SH Category: + * Todo no example diff --git a/man/std::basic_format_string,std::format_string,std::wformat_string.3 b/man/std::basic_format_string,std::format_string,std::wformat_string.3 new file mode 100644 index 000000000..733e7d339 --- /dev/null +++ b/man/std::basic_format_string,std::format_string,std::wformat_string.3 @@ -0,0 +1,133 @@ +.TH std::basic_format_string,std::format_string,std::wformat_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_format_string,std::format_string,std::wformat_string \- std::basic_format_string,std::format_string,std::wformat_string + +.SH Synopsis + Defined in header + template< class CharT, class... Args > \fB(1)\fP \fI(since C++20)\fP + struct basic_format_string; + template< class... Args > + + using format_string = \fB(2)\fP \fI(since C++20)\fP + + basic_format_string...>; + template< class... Args > + + using wformat_string = \fB(3)\fP \fI(since C++20)\fP + + basic_format_string...>; + + Class template std::basic_format_string wraps a std::basic_string_view that will be + used by formatting functions. + + The constructor of std::basic_format_string performs compile-time format string + checks + unless the constructor argument is returned by std::runtime_format + (since C++26). + +.SH Member functions + + constructs a basic_format_string, raising compile error if the + constructor argument is not a format string + \fI(public member function)\fP + get returns the wrapped string + \fI(public member function)\fP + +std::basic_format_string::basic_format_string + + template< class T > \fB(1)\fP + consteval basic_format_string( const T& s ); + basic_format_string( /* runtime-format-string */ s ) \fB(2)\fP (since C++26) + noexcept; + + 1) Constructs a basic_format_string object that stores a view of string s. If the + argument is not a compile-time constant, or if it cannot be parsed as a format + string for the formatting argument types Args, the construction is ill-formed. + This overload participates in overload resolution only if const T& models + std::convertible_to>. + 2) Constructs a basic_format_string object that stores a view of string s as + returned by std::runtime_format. It does not perform format string checks upon + construction. + +.SH Parameters + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } respectively in + the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to be + used for formatting; if it is omitted, the arguments are used in + arg-id - order. + + The arg-id s in a format string must all be present or all be + omitted. Mixing manual and automatic indexing is an error. + s - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start with + }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono format + specification. + + * For range types, the format specification is interpreted as + range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. (since C++23) + * For std::thread::id and std::stacktrace_entry, see thread id + format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + +std::basic_format_string::get + + constexpr std::basic_string_view get() const noexcept; + + Returns the stored string view. + +.SH Notes + + The alias templates format_string and wformat_string use std::type_identity_t to + inhibit template argument deduction. Typically, when they appear as a function + parameter, their template arguments are deduced from other function arguments. + + template + std::string format(std::format_string fmt, Args&&... args); + + auto s = format("{} {}", 1.0, 2); + // Calls format. Args are deduced from 1.0, 2 + // Due to the use of type_identity_t in format_string, template argument deduction + // does not consider the type of the format string. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2508R1 C++20 there's no user-visible name for the name basic_format_string is + this facility exposed + +.SH Category: + * Todo no example diff --git a/man/std::basic_fstream.3 b/man/std::basic_fstream.3 index 9046a6474..1cf5a4b01 100644 --- a/man/std::basic_fstream.3 +++ b/man/std::basic_fstream.3 @@ -1,4 +1,7 @@ -.TH std::basic_fstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream \- std::basic_fstream + .SH Synopsis Defined in header template< @@ -16,51 +19,55 @@ member: an instance of std::basic_filebuf. std-basic fstream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - fstream basic_fstream - wfstream basic_fstream + Type Definition + std::fstream std::basic_fstream + std::wfstream std::basic_fstream .SH Member types - Member type Definition - char_type CharT - traits_type Traits - int_type Traits::int_type - pos_type Traits::pos_type - off_type Traits::off_type + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular .SH Member functions constructor constructs the file stream - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the basic_fstream and the associated \fB[virtual]\fP (implicitly declared) buffer, closes the file - \fI(virtual public member function)\fP + \fI(virtual public member function)\fP operator= moves the file stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP rdbuf returns the underlying raw file device object - \fI(public member function)\fP + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP .SH File operations is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::basic_fstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_istream @@ -68,66 +75,66 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -140,45 +147,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -186,40 +193,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -227,76 +234,133 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename{"test.bin"}; + std::fstream s{filename, s.binary | s.trunc | s.in | s.out}; + + if (!s.is_open()) + std::cout << "failed to open " << filename << '\\n'; + else + { + // write + double d{3.14}; + s.write(reinterpret_cast(&d), sizeof d); // binary output + s << 123 << "abc"; // text output + + // for fstream, this moves the file position pointer (both put and get) + s.seekp(0); + + // read + d = 2.71828; + s.read(reinterpret_cast(&d), sizeof d); // binary input + int n; + std::string str; + if (s >> n >> str) // text input + std::cout << "read back from file: " << d << ' ' << n << ' ' << str << '\\n'; + } + } + +.SH Output: + + read back from file: 3.14 123 abc + +.SH See also + + getline read data from an I/O stream into a string + \fI(function template)\fP diff --git a/man/std::basic_fstream::basic_fstream.3 b/man/std::basic_fstream::basic_fstream.3 index c511d3aed..d3641c529 100644 --- a/man/std::basic_fstream::basic_fstream.3 +++ b/man/std::basic_fstream::basic_fstream.3 @@ -1,70 +1,111 @@ -.TH std::basic_fstream::basic_fstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::basic_fstream \- std::basic_fstream::basic_fstream + .SH Synopsis basic_fstream(); \fB(1)\fP explicit basic_fstream( const char* filename, - ios_base::openmode mode = \fB(2)\fP - ios_base::in|ios_base::out ); - explicit basic_fstream( const string& filename, - \fB(3)\fP \fI(since C++11)\fP - ios_base::openmode mode = - ios_base::in|ios_base::out ); - basic_fstream( basic_fstream&& other ); \fB(4)\fP \fI(since C++11)\fP - basic_fstream( const basic_fstream& rhs) = delete; \fB(5)\fP \fI(since C++11)\fP + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::filesystem::path::value_type* + filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in | + std::ios_base::out ); + template< class FsPath > + + explicit basic_fstream( const FsPath& filename, + std::ios_base::openmode mode \fB(5)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + basic_fstream( basic_fstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_fstream( const basic_fstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP Constructs new file stream. 1) Default constructor: constructs a stream that is not associated with a file: default-constructs the std::basic_filebuf and constructs the base with the pointer to this default-constructed std::basic_filebuf member. - 2) First, performs the same steps as the default constructor, then asssociates the - stream with a file by calling rdbuf()->open(filename, mode).. If the open() call - returns a null pointer, sets setstate(failbit). - 3) Same as basic_fstream(filename.c_str(), mode). - 4) Move constructor. First, move-constructs the base class from other (which does + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_fstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer in the base class. - 5) The copy-constructor is deleted: this class is not copyable. + 7) The copy-constructor is deleted: this class is not copyable. .SH Parameters filename - the name of the file to be opened - specifies stream open mode. It is bitmask type, the following constants - are defined: - - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode other - another file stream to use as source .SH Example - + // Run this code #include - #include #include + #include + int main() { - std::fstream f0; + std::fstream f0; std::fstream f1("test.bin", std::ios::binary); std::string name = "example.txt"; std::fstream f2(name); std::fstream f3(std::move(f1)); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default argument of mode in overload + LWG 460 C++98 (2) added + was missing (it is present in the synopsis) + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + .SH See also open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP set_rdbuf replaces the rdbuf without clearing its error state - \fI(protected member function)\fP + \fI(protected member function)\fP constructor constructs the object - \fI(public member function of std::basic_iostream)\fP + \fI(public member function of std::basic_iostream)\fP diff --git a/man/std::basic_fstream::close.3 b/man/std::basic_fstream::close.3 index af3d68483..8b47101e3 100644 --- a/man/std::basic_fstream::close.3 +++ b/man/std::basic_fstream::close.3 @@ -1,4 +1,7 @@ -.TH std::basic_fstream::close 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::close \- std::basic_fstream::close + .SH Synopsis void close(); @@ -15,29 +18,34 @@ \fI(none)\fP +.SH Notes + + This function is called by the destructor of basic_fstream when the stream object + goes out of scope and is not usually invoked directly. + .SH Example - + // Run this code - #include #include #include - + #include + int main() { std::fstream f1("example1", std::ios::out), f2("example2", std::ios::out), f3("example3", std::ios::out); - + std::cout << std::boolalpha << f1.is_open() << '\\n' << f2.is_open() << '\\n' << f3.is_open() << '\\n'; - + f1.close(); f2.close(); - + std::cout << f1.is_open() << '\\n' << f2.is_open() << '\\n' << f3.is_open() << '\\n'; @@ -55,6 +63,8 @@ .SH See also is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::basic_fstream::is_open.3 b/man/std::basic_fstream::is_open.3 index 8ee2da3f2..39cb27b98 100644 --- a/man/std::basic_fstream::is_open.3 +++ b/man/std::basic_fstream::is_open.3 @@ -1,7 +1,9 @@ -.TH std::basic_fstream::is_open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::is_open \- std::basic_fstream::is_open + .SH Synopsis - bool is_open(); \fI(until C++11)\fP - bool is_open() const; \fI(since C++11)\fP + bool is_open() const; Checks if the file stream has an associated file. @@ -13,31 +15,31 @@ .SH Return value - true if the file stream has an associated file, false otherwise + true if the file stream has an associated file, false otherwise. .SH Example - + // Run this code - #include #include #include - + #include + int main() { std::string filename = "some_file"; - + std::fstream fs(filename, std::ios::in); - + std::cout << std::boolalpha; std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; - - if(!fs.is_open()) + + if (!fs.is_open()) { - fs.clear(); - fs.open(filename, std::ios::out); - std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + fs.clear(); + fs.open(filename, std::ios::out); + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; } } @@ -46,9 +48,18 @@ fs.is_open() = false fs.is_open() = true + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + .SH See also open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_fstream::native_handle.3 b/man/std::basic_fstream::native_handle.3 new file mode 100644 index 000000000..48601a86f --- /dev/null +++ b/man/std::basic_fstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_fstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::native_handle \- std::basic_fstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::basic_fstream::open.3 b/man/std::basic_fstream::open.3 index fb456bdba..ada1a2dfe 100644 --- a/man/std::basic_fstream::open.3 +++ b/man/std::basic_fstream::open.3 @@ -1,34 +1,53 @@ -.TH std::basic_fstream::open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::open \- std::basic_fstream::open + .SH Synopsis - void open( const char *filename, - ios_base::openmode mode = ios_base::in|ios_base::out ); - void open( const std::string &filename, - \fI(since C++11)\fP - ios_base::openmode mode = ios_base::in|ios_base::out ); + void open( const char* filename, - Opens and associates the file with name filename with the file stream. + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::string& filename, - Calls setstate(failbit) on failure. + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP - Calls clear() on success. \fI(since C++11)\fP + = std::ios_base::in | std::ios_base::out ); + void open( const std::filesystem::path& filename, - The first version effectively calls rdbuf()->open(filename, mode). + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP - The second version effectively calls open(filename.c_str(), mode). + = std::ios_base::in | std::ios_base::out ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode) (see std::basic_filebuf::open + for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). .SH Parameters filename - the name of the file to be opened - specifies stream open mode. It is bitmask type, the following constants + specifies stream open mode. It is a BitmaskType, the following constants are defined: - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Return value @@ -36,39 +55,53 @@ .SH Example - + // Run this code - #include #include #include - + #include + int main() { std::string filename = "example.123"; - + std::fstream fs; - fs.open(filename); - - if(!fs.is_open()) + + if (!fs.is_open()) { - fs.clear(); - fs.open(filename, std::ios::out); //Create file. - fs.close(); - fs.open(filename); + fs.clear(); + fs.open(filename, std::ios::out); // create file + fs.close(); + fs.open(filename); } - + std::cout << std::boolalpha; std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; std::cout << "fs.good() = " << fs.good() << '\\n'; } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + LWG 460 C++98 the default argument of mode in overload (1) added + was missing (it is present in the synopsis) + + 1. ↑ The resolution of LWG issue #22 is overriden. + .SH See also is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::basic_fstream::operator=.3 b/man/std::basic_fstream::operator=.3 index 62eab0823..31af32e71 100644 --- a/man/std::basic_fstream::operator=.3 +++ b/man/std::basic_fstream::operator=.3 @@ -1,13 +1,19 @@ -.TH std::basic_fstream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::operator= \- std::basic_fstream::operator= + .SH Synopsis basic_fstream& operator=( basic_fstream&& other ); \fI(since C++11)\fP - Moves the file stream. The source stream becomes of invalid state after the - operation. + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_iostream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. .SH Parameters - other - file stream to move. other becomes of invalid state after the operation. + other - file stream to move .SH Return value @@ -20,9 +26,12 @@ .SH See also - swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_fstream::rdbuf.3 b/man/std::basic_fstream::rdbuf.3 index d4073b9a6..50d1692f2 100644 --- a/man/std::basic_fstream::rdbuf.3 +++ b/man/std::basic_fstream::rdbuf.3 @@ -1,6 +1,9 @@ -.TH std::basic_fstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::rdbuf \- std::basic_fstream::rdbuf + .SH Synopsis - basic_filebuf* rdbuf() const; \fI(since C++11)\fP + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP Returns pointer to the underlying raw file device object. @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_fstream::swap.3 b/man/std::basic_fstream::swap.3 index 21d64a781..2051eb906 100644 --- a/man/std::basic_fstream::swap.3 +++ b/man/std::basic_fstream::swap.3 @@ -1,4 +1,7 @@ -.TH std::basic_fstream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_fstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::swap \- std::basic_fstream::swap + .SH Synopsis void swap( basic_fstream& other ); \fI(since C++11)\fP @@ -15,18 +18,64 @@ \fI(none)\fP +.SH Exceptions + + May throw implementation-defined exceptions. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" .SH See also operator= moves the file stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_filebuf objects - \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::basic_ifstream.3 b/man/std::basic_ifstream.3 index a886adf3a..b1ae2381b 100644 --- a/man/std::basic_ifstream.3 +++ b/man/std::basic_ifstream.3 @@ -1,4 +1,7 @@ -.TH std::basic_ifstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream \- std::basic_ifstream + .SH Synopsis Defined in header template< @@ -8,59 +11,63 @@ > class basic_ifstream : public std::basic_istream - The class template basic_ifstream implements high-level input operations on file - based streams. It interfaces a file-based streambuffer (std::basic_filebuf) with the - high-level interface of (std::basic_istream). + The class template basic_ifstream implements high-level input operations on + file-based streams. It interfaces a file-based streambuffer (std::basic_filebuf) + with the high-level interface of (std::basic_istream). A typical implementation of std::basic_ifstream holds only one non-derived data member: an instance of std::basic_filebuf. std-basic ifstream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - ifstream basic_ifstream - wifstream basic_ifstream + Type Definition + std::ifstream std::basic_ifstream + std::wifstream std::basic_ifstream .SH Member types - Member type Definition - char_type CharT - traits_type Traits - int_type Traits::int_type - pos_type Traits::pos_type - off_type Traits::off_type + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular .SH Member functions constructor constructs the file stream - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the basic_ifstream and the associated \fB[virtual]\fP (implicitly declared) buffer, closes the file - \fI(virtual public member function)\fP + \fI(virtual public member function)\fP operator= moves the file stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP rdbuf returns the underlying raw file device object - \fI(public member function)\fP + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP .SH File operations is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::basic_ifstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_istream @@ -68,40 +75,40 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ios @@ -114,45 +121,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -160,40 +167,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -201,76 +208,125 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "Test.b"; + + // prepare a file to read + double d = 3.14; + std::ofstream(filename, std::ios::binary) + .write(reinterpret_cast(&d), sizeof d) << 123 << "abc"; + + // open file for reading + std::ifstream istrm(filename, std::ios::binary); + if (!istrm.is_open()) + std::cout << "failed to open " << filename << '\\n'; + else + { + double d; + istrm.read(reinterpret_cast(&d), sizeof d); // binary input + int n; + std::string s; + if (istrm >> n >> s) // text input + std::cout << "read back from file: " << d << ' ' << n << ' ' << s << '\\n'; + } + } + +.SH Output: + + read back from file: 3.14 123 abc diff --git a/man/std::basic_ifstream::basic_ifstream.3 b/man/std::basic_ifstream::basic_ifstream.3 index b2114adb1..f8e14c230 100644 --- a/man/std::basic_ifstream::basic_ifstream.3 +++ b/man/std::basic_ifstream::basic_ifstream.3 @@ -1,68 +1,104 @@ -.TH std::basic_ifstream::basic_ifstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::basic_ifstream \- std::basic_ifstream::basic_ifstream + .SH Synopsis basic_ifstream(); \fB(1)\fP - explicit basic_ifstream( const char* filename, \fB(2)\fP - ios_base::openmode mode = ios_base::in ); - explicit basic_ifstream( const string& filename, - \fB(3)\fP \fI(since C++11)\fP - ios_base::openmode mode = ios_base::in ); - basic_ifstream( basic_ifstream&& other ); \fB(4)\fP \fI(since C++11)\fP - basic_ifstream( const basic_ifstream& rhs) = delete; \fB(5)\fP \fI(since C++11)\fP + explicit basic_ifstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in ); + explicit basic_ifstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + explicit basic_ifstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + template< class FsPath > + + explicit basic_ifstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + basic_ifstream( basic_ifstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ifstream( const basic_ifstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP Constructs new file stream. 1) Default constructor: constructs a stream that is not associated with a file: default-constructs the std::basic_filebuf and constructs the base with the pointer to this default-constructed std::basic_filebuf member. - 2) First, performs the same steps as the default constructor, then asssociates the - stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::in).. If - the open() call returns a null pointer, sets setstate(failbit). - 3) Same as basic_ifstream(filename.c_str(), mode). - 4) Move constructor. First, move-constructs the base class from other (which does + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ifstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer in the base class. - 5) The copy-constructor is deleted: this class is not copyable. + 7) The copy-constructor is deleted: this class is not copyable. .SH Parameters filename - the name of the file to be opened - specifies stream open mode. It is bitmask type, the following constants - are defined: - - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode other - another file stream to use as source .SH Example - + // Run this code #include - #include #include + #include + int main() { - std::ifstream f0; + std::ifstream f0; std::ifstream f1("test.bin", std::ios::binary); std::string name = "example.txt"; std::ifstream f2(name); std::ifstream f3(std::move(f1)); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + .SH See also open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP set_rdbuf replaces the rdbuf without clearing its error state - \fI(protected member function)\fP + \fI(protected member function)\fP constructor constructs the object - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_ifstream::close.3 b/man/std::basic_ifstream::close.3 index f081dfa26..c0db90cca 100644 --- a/man/std::basic_ifstream::close.3 +++ b/man/std::basic_ifstream::close.3 @@ -1,4 +1,7 @@ -.TH std::basic_ifstream::close 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::close \- std::basic_ifstream::close + .SH Synopsis void close(); @@ -15,6 +18,11 @@ \fI(none)\fP +.SH Notes + + This function is called by the destructor of basic_ifstream when the stream object + goes out of scope and is not usually invoked directly. + .SH Example This section is incomplete @@ -23,10 +31,11 @@ .SH See also is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ifstream::is_open.3 b/man/std::basic_ifstream::is_open.3 index b58644c0d..180030db6 100644 --- a/man/std::basic_ifstream::is_open.3 +++ b/man/std::basic_ifstream::is_open.3 @@ -1,7 +1,9 @@ -.TH std::basic_ifstream::is_open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::is_open \- std::basic_ifstream::is_open + .SH Synopsis - bool is_open(); \fI(until C++11)\fP - bool is_open() const; \fI(since C++11)\fP + bool is_open() const; Checks if the file stream has an associated file. @@ -13,29 +15,30 @@ .SH Return value - true if the file stream has an associated file, false otherwise + true if the file stream has an associated file, false otherwise. .SH Example - + // Run this code - #include #include #include - //this file is called main.cpp - + #include + + // this file is called main.cpp + bool file_exists(const std::string& str) { - std::ifstream fs(str); - return fs.is_open(); + std::ifstream fs(str); + return fs.is_open(); } - + int main() { - std::boolalpha(std::cout); - std::cout << file_exists("main.cpp") << '\\n' - << file_exists("strange_file") << '\\n'; + std::boolalpha(std::cout); + std::cout << file_exists("main.cpp") << '\\n' + << file_exists("strange_file") << '\\n'; } .SH Possible output: @@ -43,9 +46,18 @@ true false + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + .SH See also open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_ifstream::native_handle.3 b/man/std::basic_ifstream::native_handle.3 new file mode 100644 index 000000000..264f88e20 --- /dev/null +++ b/man/std::basic_ifstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_ifstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::native_handle \- std::basic_ifstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::basic_ifstream::open.3 b/man/std::basic_ifstream::open.3 index 598d8c854..4b1131d62 100644 --- a/man/std::basic_ifstream::open.3 +++ b/man/std::basic_ifstream::open.3 @@ -1,34 +1,53 @@ -.TH std::basic_ifstream::open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::open \- std::basic_ifstream::open + .SH Synopsis - void open( const char *filename, - ios_base::openmode mode = ios_base::in ); - void open( const std::string &filename, - \fI(since C++11)\fP - ios_base::openmode mode = ios_base::in ); + void open( const char* filename, - Opens and associates the file with name filename with the file stream. + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::in ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::in ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + void open( const std::filesystem::path& filename, - Calls setstate(failbit) on failure. + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP - Calls clear() on success. \fI(since C++11)\fP + = std::ios_base::in ); - The first version effectively calls rdbuf()->open(filename, mode | ios_base::in). + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. - The second version effectively calls open(filename.c_str(), mode). + 1,2) Effectively calls rdbuf()->open(filename, mode | ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). .SH Parameters filename - the name of the file to be opened - specifies stream open mode. It is bitmask type, the following constants + specifies stream open mode. It is a BitmaskType, the following constants are defined: - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Return value @@ -39,15 +58,27 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + + 1. ↑ The resolution of LWG issue #22 is overriden. + .SH See also is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ifstream::operator=.3 b/man/std::basic_ifstream::operator=.3 index 905715e34..149d17ae4 100644 --- a/man/std::basic_ifstream::operator=.3 +++ b/man/std::basic_ifstream::operator=.3 @@ -1,13 +1,19 @@ -.TH std::basic_ifstream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::operator= \- std::basic_ifstream::operator= + .SH Synopsis basic_ifstream& operator=( basic_ifstream&& other ); \fI(since C++11)\fP - Moves the file stream. The source stream becomes of invalid state after the - operation. + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_istream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. .SH Parameters - other - file stream to move. other becomes of invalid state after the operation. + other - file stream to move .SH Return value @@ -20,9 +26,12 @@ .SH See also - swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ifstream::rdbuf.3 b/man/std::basic_ifstream::rdbuf.3 index 13343b008..cb59a8031 100644 --- a/man/std::basic_ifstream::rdbuf.3 +++ b/man/std::basic_ifstream::rdbuf.3 @@ -1,6 +1,9 @@ -.TH std::basic_ifstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::rdbuf \- std::basic_ifstream::rdbuf + .SH Synopsis - basic_filebuf* rdbuf() const; \fI(since C++11)\fP + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP Returns pointer to the underlying raw file device object. @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_ifstream::swap.3 b/man/std::basic_ifstream::swap.3 index 24317cc59..25e3093f1 100644 --- a/man/std::basic_ifstream::swap.3 +++ b/man/std::basic_ifstream::swap.3 @@ -1,4 +1,7 @@ -.TH std::basic_ifstream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ifstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::swap \- std::basic_ifstream::swap + .SH Synopsis void swap( basic_ifstream& other ); \fI(since C++11)\fP @@ -15,18 +18,64 @@ \fI(none)\fP +.SH Exceptions + + May throw implementation-defined exceptions. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" .SH See also operator= moves the file stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_filebuf objects - \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::basic_ios.3 b/man/std::basic_ios.3 index 3004b93a2..53f70e4db 100644 --- a/man/std::basic_ios.3 +++ b/man/std::basic_ios.3 @@ -1,96 +1,98 @@ -.TH std::basic_ios 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios \- std::basic_ios + .SH Synopsis Defined in header template< class CharT, class Traits = std::char_traits + > class basic_ios - > class basic_ios : public ios_base + : public std::ios_base The class std::basic_ios provides facilities for interfacing with objects that have std::basic_streambuf interface. Several std::basic_ios objects can refer to one - actual std::basic_streambuf object. Character type dependent formatting flags and - error state is stored in std::basic_ios class. + actual std::basic_streambuf object. std-basic ios-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also provided: + Several typedefs for common character types are provided: - Type Definition - ios basic_ios - wios basic_ios + Defined in header + Type Definition + std::ios std::basic_ios + std::wios std::basic_ios .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type .SH Public member functions - constructor constructs the object - \fI(public member function)\fP - destructor destructs the object - \fB[virtual]\fP \fI(virtual public member function)\fP - operator= the copy assignment operator is deleted - \fI(public member function)\fP + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= the copy assignment operator is deleted + \fI(public member function)\fP .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function)\fP - eof checks if end-of-file has been reached - \fI(public member function)\fP - fail checks if a recoverable error has occurred - \fI(public member function)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function)\fP - setstate sets state flags - \fI(public member function)\fP - clear clears error and eof flags - \fI(public member function)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function)\fP + eof checks if end-of-file has been reached + \fI(public member function)\fP + fail checks if an error has occurred + \fI(public member function)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function)\fP + rdstate returns state flags + \fI(public member function)\fP + setstate sets state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function)\fP - fill manages the fill character - \fI(public member function)\fP + copyfmt copies formatting information + \fI(public member function)\fP + fill manages the fill character + \fI(public member function)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function)\fP - imbue sets the locale - \fI(public member function)\fP - rdbuf manages associated stream buffer - \fI(public member function)\fP - tie manages tied stream - \fI(public member function)\fP - narrow narrows characters - \fI(public member function)\fP - widen widens characters - \fI(public member function)\fP + exceptions manages exception mask + \fI(public member function)\fP + imbue sets the locale + \fI(public member function)\fP + rdbuf manages associated stream buffer + \fI(public member function)\fP + tie manages tied stream + \fI(public member function)\fP + narrow narrows characters + \fI(public member function)\fP + widen widens characters + \fI(public member function)\fP .SH Protected member functions init initializes a default-constructed std::basic_ios - \fI(protected member function)\fP + \fI(protected member function)\fP move moves from another std::basic_ios except for rdbuf - \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP swap swaps with another std::basic_ios except for rdbuf - \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP set_rdbuf replaces the rdbuf without clearing its error state - \fI(protected member function)\fP + \fI(protected member function)\fP Inherited from std::ios_base @@ -98,40 +100,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -139,76 +141,103 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP + +.SH Notes + + Straightforward implementation of std::basic_ios stores only the following members + (which all depend on the template parameters and thus cannot be part of + std::ios_base): + + * the fill character (see fill()) + * the tied stream pointer (see tie()) + * the associated stream buffer pointer (see rdbuf()). + + Actual implementations vary: + + Microsoft Visual Studio stores just those three members. + + LLVM libc++ stores 1 less member: it maintains the rdbuf pointer as a void* member + of ios_base. + + GNU libstdc++ stores 4 additional members: three cached facets and a flag to + indicate that fill was initialized. diff --git a/man/std::basic_ios::bad.3 b/man/std::basic_ios::bad.3 index fa5cc163b..dab780437 100644 --- a/man/std::basic_ios::bad.3 +++ b/man/std::basic_ios::bad.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::bad 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::bad 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::bad \- std::basic_ios::bad + .SH Synopsis bool bad() const; @@ -17,28 +20,28 @@ .SH Example - + // Run this code - #include - #include #include + #include + #include + int main() { std::ifstream file("test.txt"); - if(!file) // operator! is used here + if (!file) // operator! is used here { std::cout << "File opening failed\\n"; return EXIT_FAILURE; } - + // typical C++ I/O loop uses the return value of the I/O function // as the loop controlling condition, operator bool() is used here - for(int n; file >> n; ) { + for (int n; file >> n;) std::cout << n << ' '; - } std::cout << '\\n'; - + if (file.bad()) std::cout << "I/O error while reading\\n"; else if (file.eof()) diff --git a/man/std::basic_ios::basic_ios.3 b/man/std::basic_ios::basic_ios.3 index 089961521..4695bdf9d 100644 --- a/man/std::basic_ios::basic_ios.3 +++ b/man/std::basic_ios::basic_ios.3 @@ -1,24 +1,39 @@ -.TH std::basic_ios::basic_ios 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::basic_ios \- std::basic_ios::basic_ios + .SH Synopsis - protected: \fB(1)\fP + protected: \fB(1)\fP basic_ios(); - public: \fB(2)\fP - explicit basic_ios( std::basic_streambuf* sb ); - private: \fI(until C++11)\fP - basic_ios(const basic_ios&); \fB(3)\fP - public: \fI(since C++11)\fP - basic_ios(const basic_ios& ) = delete; + public: \fB(2)\fP + explicit basic_ios( std::basic_streambuf* sb ); + private: \fI(until C++11)\fP + basic_ios( const basic_ios& ); \fB(3)\fP + public: \fI(since C++11)\fP + basic_ios( const basic_ios& ) = delete; - Constructs new basic_ios object. + Constructs a new std::basic_ios object. 1) Default constructor. The internal state is not initialized. init() must be called before the first use of the object or before destructor, otherwise the behavior is undefined. 2) Initializes the internal state by calling init(sb). The associated stream buffer is set to sb. - 3) The copy constructor was declared private: and not defined until C++11 and is - declared as deleted in C++11: I/O streams are not CopyConstructible. + 3) The copy constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: I/O streams are not CopyConstructible. .SH Parameters sb - stream buffer to associate to + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1249 C++98 internal state did not need to be initialized also needs to be + before first use initialized diff --git a/man/std::basic_ios::clear.3 b/man/std::basic_ios::clear.3 index 68c991232..808ca3227 100644 --- a/man/std::basic_ios::clear.3 +++ b/man/std::basic_ios::clear.3 @@ -1,9 +1,16 @@ -.TH std::basic_ios::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::clear \- std::basic_ios::clear + .SH Synopsis void clear( std::ios_base::iostate state = std::ios_base::goodbit ); - Clears the stream error state flags by assigning them the value of state. If rdbuf() - == 0 then state | badbit is assigned. May throw an exception. + Sets the stream error state flags by assigning them the value of state. By default, + assigns std::ios_base::goodbit which has the effect of clearing all error state + flags. + + If rdbuf() is a null pointer (i.e. there is no associated stream buffer), then state + | std::ios_base::badbit is assigned. .SH Parameters @@ -20,33 +27,59 @@ \fI(none)\fP +.SH Exceptions + + If the new error state includes a bit that is also included in the exceptions() + mask, throws an exception of type failure. + .SH Example - clear() without arguments can be used to unset the failbit after unexpected input + clear() without arguments can be used to unset the failbit after unexpected input; + for std::cin.putback(c) see ungetc. + - // Run this code #include #include - + int main() { + for (char c : {'\\n', '4', '1', '.', '3', '\\n', 'Z', 'Y', 'X'}) + std::cin.putback(c); // emulate user's input (not portable: see ungetc Notes) + double n; - while( std::cout << "Please, enter a number\\n" - && ! (std::cin >> n) ) + while (std::cout << "Please, enter a number: " && !(std::cin >> n)) { std::cin.clear(); std::string line; std::getline(std::cin, line); - std::cout << "I am sorry, but '" << line << "' is not a number\\n"; + std::cout << line << "\\nI am sorry, but '" << line << "' is not a number\\n"; } - std::cout << "Thank you for entering the number " << n << '\\n'; + std::cout << n << "\\nThank you for entering the number " << n << '\\n'; } +.SH Output: + + Please, enter a number: XYZ + I am sorry, but 'XYZ' is not a number + Please, enter a number: 3.14 + Thank you for entering the number 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + an excption would be thrown if the current + LWG 412 C++98 error state checks the new + includes a bit that is also included in the error state instead + exceptions() mask + .SH See also setstate sets state flags - \fI(public member function)\fP + \fI(public member function)\fP rdstate returns state flags - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_ios::copyfmt.3 b/man/std::basic_ios::copyfmt.3 index a03787d36..775df7d97 100644 --- a/man/std::basic_ios::copyfmt.3 +++ b/man/std::basic_ios::copyfmt.3 @@ -1,20 +1,23 @@ -.TH std::basic_ios::copyfmt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::copyfmt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::copyfmt \- std::basic_ios::copyfmt + .SH Synopsis - basic_ios& copyfmt(const basic_ios& other); + basic_ios& copyfmt( const basic_ios& other ); - Copies the state of the stream other into *this. This is done in the following - sequence: + If other refers to the same object as *this, has no effects. Otherwise, copies the + state of the stream other into *this. This is done in the following sequence: 1) Calls every callback registered by register_callback() passing erase_event as - parameter + parameter. 2) Copies all member objects from other to *this except for rdstate(), the exception mask, and rdbuf(). In particular, makes copies of the locale, the formatting flags, the contents of the arrays std::ios_base::iword and std::ios_base::pword (but not the iword and pword pointers themselves), the callbacks, and the tied stream. 3) Calls every callback registered by register_callback() passing copyfmt_event as - parameter + parameter. 4) Copies the exception mask from other to *this as if by calling - exceptions(other.exceptions()) + exceptions(other.exceptions()). .SH Parameters @@ -27,33 +30,65 @@ .SH Notes The second pass through the callbacks may be used to deep-copy the user-defined - objects pointed to by the pointers in std::ios_base::pword + objects pointed to by the pointers in std::ios_base::pword. copyfmt() may be used to save and restore the state of a stream. Boost provides a - more fine-grained IO state savers library for the same purpose. + more fine-grained I/O state savers library for the same purpose. .SH Example - makes the ofstream object "out" behave exactly like std::cout, including formatting, - tie() to std::cin, etc. + Makes the std::ofstream object "out" behave exactly like std::cout, including + formatting, tie() to std::cin, etc. + - // Run this code - #include + #include + #include #include - + #include + int main() { std::ofstream out; - + out.copyfmt(std::cout); // copy everything except rdstate and rdbuf out.clear(std::cout.rdstate()); // copy rdstate out.basic_ios::rdbuf(std::cout.rdbuf()); // share the buffer - + out << "Hello, world\\n"; + + auto bin = [](std::ios_base::fmtflags f) + { + return std::bitset + { static_cast(f) }; + }; + std::ofstream out2; + std::cout << "1) out2.flags(): " << bin(out2.flags()) << '\\n'; + std::cout << "2) cout.flags(): " << bin(std::cout.flags()) << '\\n'; + std::cout.setf(std::ios::hex | std::ios::fixed | std::ios::boolalpha); + std::cout << "3) cout.flags(): " << bin(std::cout.flags()) << '\\n'; + out2.copyfmt(std::cout); // copy everything except rdstate and rdbuf + std::cout << "4) out2.flags(): " << bin(out2.flags()) << '\\n'; } -.SH Output: +.SH Possible output: Hello, world + 1) out2.flags(): 00000000000000000001000000000010 + 2) cout.flags(): 00000000000000000001000000000010 + 3) cout.flags(): 00000000000000000001000000001111 + 4) out2.flags(): 00000000000000000001000000001111 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 256 C++98 step 3 called the registered callbacks with the corrected to + event type copy_event, which is not defined copyfmt_event + if other refers to the same object as *this, the + LWG 292 C++98 member objects do nothing + were still copied and the registered callbacks in this case + were still called diff --git a/man/std::basic_ios::eof.3 b/man/std::basic_ios::eof.3 index 20216de5b..2eeb9f530 100644 --- a/man/std::basic_ios::eof.3 +++ b/man/std::basic_ios::eof.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::eof 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::eof 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::eof \- std::basic_ios::eof + .SH Synopsis bool eof() const; @@ -17,38 +20,38 @@ .SH Notes - This function only reports the stream state as set by the most recent I/O operation, + This function only reports the stream state as set by the most recent I/O operation; it does not examine the associated data source. For example, if the most recent I/O - was a get(), which returned the last byte of a file, eof() returns false. The next - get() fails to read anything and sets the eofbit. Only then eof() returns true. + was a get() which returned the last byte of a file, eof() returns false. The next + get() fails to read anything and sets the eofbit. Only then does eof() return true. - In typical usage, input stream processing stops on any error; eof() and fail() are - then used to distinguish between different error conditions. + In typical usage, input stream processing stops on any error. eof() and fail() can + then be used to distinguish between different error conditions. .SH Example - + // Run this code - #include - #include #include + #include + #include + int main() { std::ifstream file("test.txt"); - if(!file) // operator! is used here + if (!file) // operator! is used here { std::cout << "File opening failed\\n"; return EXIT_FAILURE; } - + // typical C++ I/O loop uses the return value of the I/O function // as the loop controlling condition, operator bool() is used here - for(int n; file >> n; ) { + for (int n; file >> n;) std::cout << n << ' '; - } std::cout << '\\n'; - + if (file.bad()) std::cout << "I/O error while reading\\n"; else if (file.eof()) @@ -74,4 +77,4 @@ true true true false true true true false true feof checks for the end-of-file - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_ios::exceptions.3 b/man/std::basic_ios::exceptions.3 index 57e6e1137..56dd00a97 100644 --- a/man/std::basic_ios::exceptions.3 +++ b/man/std::basic_ios::exceptions.3 @@ -1,13 +1,17 @@ -.TH std::basic_ios::exceptions 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::exceptions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::exceptions \- std::basic_ios::exceptions + .SH Synopsis std::ios_base::iostate exceptions() const; \fB(1)\fP void exceptions( std::ios_base::iostate except ); \fB(2)\fP - Gets and sets the exception mask of the stream. The exception mask determines the - error states, on occurrence of which the stream throws exception of type failure. + Gets and sets the exception mask of the stream. The exception mask determines which + error states trigger exceptions of type failure. 1) Returns the exception mask. - 2) Sets the exception mask to except. + 2) Sets the exception mask to except. If the stream has an error state covered by + the exception mask when called, an exception is immediately triggered. .SH Parameters @@ -18,22 +22,41 @@ 1) The current exception mask. 2) \fI(none)\fP +.SH Notes + + This section is incomplete + Reason: discuss LWG2349 and link from ios_base::clear, and from + (un)formatted(i/o)utputfunction requirement pages (or perhaps the behavior should + be fully elaborated on the requirement pages and linked from here). See also + stackoverflow.com/a/35089910 + .SH Example - + // Run this code - #include #include - + #include + int main() { int ivalue; - try { + try + { std::ifstream in("in.txt"); - in.exceptions(std::ifstream::failbit); - in >> ivalue; - } catch (std::ios_base::failure &fail) { + in.exceptions(std::ifstream::failbit); // may throw + in >> ivalue; // may throw + } + catch (const std::ios_base::failure& fail) + { // handle exception here + std::cout << fail.what() << '\\n'; } } + +.SH Possible output: + + basic_ios::clear: iostream error + +.SH Category: + * Todo with reason diff --git a/man/std::basic_ios::fail.3 b/man/std::basic_ios::fail.3 index f5e0aaa34..f5d71a0d6 100644 --- a/man/std::basic_ios::fail.3 +++ b/man/std::basic_ios::fail.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::fail 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::fail \- std::basic_ios::fail + .SH Synopsis bool fail() const; @@ -17,28 +20,28 @@ .SH Example - + // Run this code - #include - #include #include + #include + #include + int main() { std::ifstream file("test.txt"); - if(!file) // operator! is used here + if (!file) // operator! is used here { std::cout << "File opening failed\\n"; return EXIT_FAILURE; } - + // typical C++ I/O loop uses the return value of the I/O function // as the loop controlling condition, operator bool() is used here - for(int n; file >> n; ) { + for (int n; file >> n;) std::cout << n << ' '; - } std::cout << '\\n'; - + if (file.bad()) std::cout << "I/O error while reading\\n"; else if (file.eof()) @@ -64,4 +67,4 @@ true true true false true true true false true ferror checks for a file error - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_ios::fill.3 b/man/std::basic_ios::fill.3 index 0ca822814..cc61848b0 100644 --- a/man/std::basic_ios::fill.3 +++ b/man/std::basic_ios::fill.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::fill 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::fill \- std::basic_ios::fill + .SH Synopsis CharT fill() const; \fB(1)\fP CharT fill( CharT ch ); \fB(2)\fP @@ -6,9 +9,8 @@ Manages the fill character used to pad the output conversions to the specified field width. - 1) returns the current fill character - - 2) sets the fill character to ch, returns previous value of the fill character + 1) Returns the current fill character. + 2) Sets the fill character to ch, returns previous value of the fill character. .SH Parameters @@ -16,13 +18,30 @@ .SH Return value - the fill character before the call to the function. + The fill character before the call to the function. .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + + int main () + { + std::cout << "With default setting : [" << std::setw(10) << 40 << "]\\n"; + char prev = std::cout.fill('x'); + std::cout << "Replaced '" << prev << "' with '" + << std::cout.fill() << "': [" << std::setw(10) << 40 << "]\\n"; + } + +.SH Output: + + With default setting : [ 40] + Replaced ' ' with 'x': [xxxxxxxx40] + +.SH See also - * Todo no example + setfill changes the fill character + \fI(function template)\fP diff --git a/man/std::basic_ios::good.3 b/man/std::basic_ios::good.3 index a45621da4..55892fb7c 100644 --- a/man/std::basic_ios::good.3 +++ b/man/std::basic_ios::good.3 @@ -1,9 +1,12 @@ -.TH std::basic_ios::good 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::good 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::good \- std::basic_ios::good + .SH Synopsis bool good() const; - Returns true if the the most recent I/O operation on the stream completed - successfully. Specifically, returns result of rdstate() == 0. + Returns true if the most recent I/O operation on the stream completed successfully. + Specifically, returns result of rdstate() == 0. See ios_base::iostate for the list of conditions that set the stream status bits. @@ -13,12 +16,54 @@ .SH Return value - true if the stream has no errors occurred, false otherwise. + true if the stream error flags are all false, false otherwise. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + const char* fname = "/tmp/test.txt"; + std::ofstream ofile{fname}; + ofile << "10 " << "11 " << "12 " << "non-int"; + ofile.close(); + + std::ifstream file{fname}; + if (!file.good()) + { + std::cout << "#1. Opening file test.txt failed - " + "one of the error flags is true\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + { + std::cout << "#2. I/O error while reading - badbit is true\\n"; + return EXIT_FAILURE; + } + else if (file.eof()) + std::cout << "#3. End of file reached successfully - eofbit is true\\n" + "This is fine even though file.good() is false\\n"; + else if (file.fail()) + std::cout << "#4. Non-integer data encountered - failbit is true\\n"; + } + +.SH Possible output: + + 10 11 12 + #4. Non-integer data encountered - failbit is true .SH See also @@ -35,7 +80,3 @@ true false true false true true true false true true true false false true false true false true true true true false true true true false true - -.SH Category: - - * Todo no example diff --git a/man/std::basic_ios::imbue.3 b/man/std::basic_ios::imbue.3 index dbb78eb7f..065831d53 100644 --- a/man/std::basic_ios::imbue.3 +++ b/man/std::basic_ios::imbue.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::imbue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::imbue \- std::basic_ios::imbue + .SH Synopsis std::locale imbue( const std::locale& loc ); @@ -15,24 +18,24 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::istringstream iss; iss.imbue(std::locale("en_US.UTF8")); - + std::cout << "Current locale: " << iss.getloc().name() << '\\n'; - + iss.imbue(std::locale()); std::cout << "Global locale : " << iss.getloc().name() << '\\n'; } diff --git a/man/std::basic_ios::init.3 b/man/std::basic_ios::init.3 index 15505bbec..18affa265 100644 --- a/man/std::basic_ios::init.3 +++ b/man/std::basic_ios::init.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::init 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::init 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::init \- std::basic_ios::init + .SH Synopsis protected: void init( std::basic_streambuf* sb ); @@ -7,10 +10,10 @@ The postconditions are as follows: - Element Value + Element Value rdbuf() sb - tie() NULL - rdstate() goodbit if sb is not NULL, otherwise badbit + tie() null pointer + rdstate() goodbit if sb is not a null pointer, otherwise badbit exceptions() goodbit flags() skipws | dec width() 0 @@ -20,11 +23,11 @@ This member function is protected: it is called by the constructors of the derived stream classes std::basic_istream and std::basic_ostream once the associated stream - buffer is known. Until this function is called, every member function (other than - the destructor) of the default-constructed std::basic_ios invokes undefined - behavior. Note that basic_ios is a virtual base class, and therefore its constructor - is not called by the constructors of those directly derived classes, which is why - two-stage initialization is necessary. + buffer is known. Until this function is called, every member function (including the + destructor) of the default-constructed std::basic_ios invokes undefined behavior. + Note that basic_ios is a virtual base class, and therefore its constructor is not + called by the constructors of those directly derived classes, which is why two-stage + initialization is necessary. .SH Parameters @@ -33,4 +36,4 @@ .SH See also constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_ios::move.3 b/man/std::basic_ios::move.3 index a2e074b14..00e50ed27 100644 --- a/man/std::basic_ios::move.3 +++ b/man/std::basic_ios::move.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::move 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::move 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::move \- std::basic_ios::move + .SH Synopsis protected: \fI(since C++11)\fP void move( basic_ios& other ); @@ -7,8 +10,8 @@ Replaces the current state with that of other, except for the associated rdbuf. other is in valid, but unspecified state after the call. After the call to this - function, rdbuf() returns NULL, and other.rdbuf() returns the same value as before - the call. + function, rdbuf() returns a null pointer, other.rdbuf() returns the same value as + before the call, and other.tie() returns a null pointer. This member function is protected: it is called by the protected move constructors of the derived stream classes std::basic_ostream and std::basic_istream, which, in @@ -26,5 +29,5 @@ .SH See also - swap swaps with another std::basic_ios except for rdbuf - \fI(protected member function)\fP + swap swaps with another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::basic_ios::narrow.3 b/man/std::basic_ios::narrow.3 index 0052df299..b498eaa0c 100644 --- a/man/std::basic_ios::narrow.3 +++ b/man/std::basic_ios::narrow.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::narrow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::narrow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::narrow \- std::basic_ios::narrow + .SH Synopsis char narrow( char_type c, char dfault ) const; @@ -22,8 +25,8 @@ .SH See also widen widens characters - \fI(public member function)\fP + \fI(public member function)\fP narrow invokes do_narrow - \fI(public member function of std::ctype)\fP + \fI(public member function of std::ctype)\fP wctob narrows a wide character to a single-byte narrow character, if possible - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_ios::operator!.3 b/man/std::basic_ios::operator!.3 index 6932722ee..07ac029c2 100644 --- a/man/std::basic_ios::operator!.3 +++ b/man/std::basic_ios::operator!.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::operator! 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::operator! 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::operator! \- std::basic_ios::operator! + .SH Synopsis bool operator!() const; @@ -15,28 +18,28 @@ .SH Example - + // Run this code - #include - #include #include + #include + #include + int main() { std::ifstream file("test.txt"); - if(!file) // operator! is used here + if (!file) // operator! is used here { std::cout << "File opening failed\\n"; return EXIT_FAILURE; } - + // typical C++ I/O loop uses the return value of the I/O function // as the loop controlling condition, operator bool() is used here - for(int n; file >> n; ) { + for (int n; file >> n;) std::cout << n << ' '; - } std::cout << '\\n'; - + if (file.bad()) std::cout << "I/O error while reading\\n"; else if (file.eof()) diff --git a/man/std::basic_ios::operatorbool.3 b/man/std::basic_ios::operatorbool.3 index ae8b8d916..40c8dc683 100644 --- a/man/std::basic_ios::operatorbool.3 +++ b/man/std::basic_ios::operatorbool.3 @@ -1,20 +1,22 @@ -.TH std::basic_ios::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::operatorbool \- std::basic_ios::operatorbool + .SH Synopsis - operator void*() const; \fB(1)\fP \fI(until C++11)\fP - explicit operator bool() const; \fB(2)\fP \fI(since C++11)\fP + operator /* unspecified-boolean-type */() const; \fB(1)\fP \fI(until C++11)\fP + explicit operator bool() const; \fB(2)\fP \fI(since C++11)\fP Checks whether the stream has no errors. - 1) Returns a null pointer if fail() returns true, otherwise returns a non-null - pointer. This pointer is implicitly convertible to bool and may be used in boolean - contexts. + 1) Returns a value that evaluates to false in a boolean context if fail() returns + true, otherwise returns a value that evaluates to true in a boolean context. 2) Returns true if the stream has no errors and is ready for I/O operations. Specifically, returns !fail(). This operator makes it possible to use streams and functions that return references to streams as loop conditions, resulting in the idiomatic C++ input loops such as - while(stream >> value) {...} or while(getline(stream, string)){...}. Such loops - execute the loop's body only if the input operation succeeded. + while (stream >> value) {...} or while (std::getline(stream, string)) {...}. Such + loops execute the loop's body only if the input operation succeeded. .SH Parameters @@ -22,34 +24,59 @@ .SH Return value - true if the stream has no errors, false otherwise. + 1) A value that evaluates to true in a boolean context if the stream has no errors, + a value that evaluates to false in a boolean context otherwise. + 2) true if the stream has no errors, false otherwise. + +.SH Notes + + This conversion can be used in contexts where a bool is expected (e.g. an if + condition). However, implicit conversions (e.g. to int) that can occur with bool are + not allowed. + + In C++98, operator bool could not be provided directly due to the safe bool problem. + The initial solution in C++98 is to provide operator void*, which returns a null + pointer if fail() returns true or a non-null pointer otherwise. It is replaced by + the resolution of LWG issue 468, which allows Safe Bool idiom to be applied. + + Since C++11, conversion functions can be explicit. The resolution of LWG issue 1094 + introduced the explicit operator bool and the boolean conversion is now safe. .SH Example - + // Run this code #include #include - + int main() { std::istringstream s("1 2 3 error"); int n; - std::cout << std::boolalpha << "(bool)s is " << (bool)s << '\\n'; - while (s >> n) { + + std::cout << std::boolalpha << "s is " << static_cast(s) << '\\n'; + while (s >> n) std::cout << n << '\\n'; - } - std::cout << std::boolalpha << "(bool)s is " << (bool)s << '\\n'; + std::cout << "s is " << static_cast(s) << '\\n'; } .SH Output: - (bool)s is true + s is true 1 2 3 - (bool)s is false + s is false + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 468 C++98 operator void* was a conversion function to an unspecified + provided boolean type is provided instead .SH See also diff --git a/man/std::basic_ios::rdbuf.3 b/man/std::basic_ios::rdbuf.3 index 39c5cca56..490355c23 100644 --- a/man/std::basic_ios::rdbuf.3 +++ b/man/std::basic_ios::rdbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::rdbuf \- std::basic_ios::rdbuf + .SH Synopsis std::basic_streambuf* rdbuf() const; \fB(1)\fP std::basic_streambuf* rdbuf( std::basic_streambuf #include - + int main() { std::ostringstream local; auto cout_buff = std::cout.rdbuf(); // save pointer to std::cout buffer - + std::cout.rdbuf(local.rdbuf()); // substitute internal std::cout buffer with // buffer of 'local' object - + // now std::cout work with 'local' buffer // you don't see this message std::cout << "some message"; - + // go back to old buffer std::cout.rdbuf(cout_buff); - + // you will see this message std::cout << "back to default buffer\\n"; - + // print 'local' content std::cout << "local content: " << local.str() << "\\n"; } @@ -62,4 +66,4 @@ .SH See also set_rdbuf replaces the rdbuf without clearing its error state - \fI(protected member function)\fP + \fI(protected member function)\fP diff --git a/man/std::basic_ios::rdstate.3 b/man/std::basic_ios::rdstate.3 index fa1c4d019..934207b16 100644 --- a/man/std::basic_ios::rdstate.3 +++ b/man/std::basic_ios::rdstate.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::rdstate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::rdstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::rdstate \- std::basic_ios::rdstate + .SH Synopsis iostate rdstate() const; @@ -21,26 +24,24 @@ .SH Example - + // Run this code #include #include - + int main() { - std::ostringstream stream; - - if (stream.rdstate() == std::ios_base::goodbit) { - std::cout << "stream state is goodbit\\n"; - } - - stream.setstate(std::ios_base::eofbit); - - // check state is exactly eofbit (no failbit and no badbit) - if (stream.rdstate() == std::ios_base::eofbit) { - std::cout << "stream state is eofbit\\n"; - } + std::ostringstream stream; + + if (stream.rdstate() == std::ios_base::goodbit) + std::cout << "stream state is goodbit\\n"; + + stream.setstate(std::ios_base::eofbit); + + // check state is exactly eofbit (no failbit and no badbit) + if (stream.rdstate() == std::ios_base::eofbit) + std::cout << "stream state is eofbit\\n"; } .SH Output: @@ -51,6 +52,6 @@ .SH See also setstate sets state flags - \fI(public member function)\fP - clear clears error and eof flags - \fI(public member function)\fP + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP diff --git a/man/std::basic_ios::set_rdbuf.3 b/man/std::basic_ios::set_rdbuf.3 index 0adcf99f4..02b9f3f7f 100644 --- a/man/std::basic_ios::set_rdbuf.3 +++ b/man/std::basic_ios::set_rdbuf.3 @@ -1,6 +1,9 @@ -.TH std::basic_ios::set_rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::set_rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::set_rdbuf \- std::basic_ios::set_rdbuf + .SH Synopsis - protected: + protected: \fI(since C++11)\fP void set_rdbuf( std::basic_streambuf* sb ); Sets the associated stream buffer to sb without clearing the error state. @@ -22,7 +25,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example @@ -32,8 +35,7 @@ .SH See also rdbuf manages associated stream buffer - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ios::setstate.3 b/man/std::basic_ios::setstate.3 index 55e8caed0..378a09c28 100644 --- a/man/std::basic_ios::setstate.3 +++ b/man/std::basic_ios::setstate.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::setstate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::setstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::setstate \- std::basic_ios::setstate + .SH Synopsis void setstate( iostate state ); @@ -22,29 +25,26 @@ .SH Example - + // Run this code #include #include - + int main() { std::ostringstream stream; - - if (!stream.fail()) { + + if (!stream.fail()) std::cout << "stream is not fail\\n"; - } - + stream.setstate(std::ios_base::failbit); - - if (stream.fail()) { + + if (stream.fail()) std::cout << "now stream is fail\\n"; - } - - if (!stream.good()) { + + if (!stream.good()) std::cout << "and stream is not good\\n"; - } } .SH Output: @@ -56,6 +56,6 @@ .SH See also rdstate returns state flags - \fI(public member function)\fP - clear clears error and eof flags - \fI(public member function)\fP + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP diff --git a/man/std::basic_ios::swap.3 b/man/std::basic_ios::swap.3 index bfe9f86d9..f22600bac 100644 --- a/man/std::basic_ios::swap.3 +++ b/man/std::basic_ios::swap.3 @@ -1,7 +1,10 @@ -.TH std::basic_ios::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::swap \- std::basic_ios::swap + .SH Synopsis - protected: \fI(since C++11)\fP - void swap( basic_ios& other ); + protected: \fI(since C++11)\fP + void swap( basic_ios& other ) noexcept; Exchanges the states of *this and other, except for the associated rdbuf objects. rdbuf() and other.rdbuf() returns the same values as before the call. @@ -18,13 +21,7 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also - move moves from another std::basic_ios except for rdbuf - \fI(protected member function)\fP + move moves from another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::basic_ios::tie.3 b/man/std::basic_ios::tie.3 index 237b6e90a..3dba24394 100644 --- a/man/std::basic_ios::tie.3 +++ b/man/std::basic_ios::tie.3 @@ -1,15 +1,22 @@ -.TH std::basic_ios::tie 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::tie 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::tie \- std::basic_ios::tie + .SH Synopsis - std::basic_ostream* tie() const; \fB(1)\fP - std::basic_ostream* tie( std::basic_ostream* str ); \fB(2)\fP + std::basic_ostream* tie() const; \fB(1)\fP + std::basic_ostream* tie( std::basic_ostream* str \fB(2)\fP + ); Manages the tied stream. A tied stream is an output stream which is synchronized with the sequence controlled by the stream buffer (rdbuf()), that is, flush() is called on the tied stream before any input/output operation on *this. - 1) Returns the current tied stream. If there is no tied stream, NULL is returned. + 1) Returns the current tied stream. If there is no tied stream, a null pointer is + returned. 2) Sets the current tied stream to str. Returns the tied stream before the - operation. If there is no tied stream, NULL is returned. + operation. If there is no tied stream, a null pointer is returned. If str is not + null and tie() is reachable by traversing the linked list of tied stream objects + starting from str->tie(), the behavior is undefined. .SH Parameters @@ -17,45 +24,66 @@ .SH Return value - The tied stream, or NULL if there was no tied stream. + The tied stream, or a null pointer if there was no tied stream. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes - By default, the standard streams cin, cerr and clog are tied to cout. Similarly, - their wide counterparts wcin, wcerr and wclog are tied to wcout. + By default, the standard stream std::cout is tied to std::cin and std::cerr. + Similarly, its wide counterpart std::wcout is tied to std::wcin and std::wcerr. .SH Example - + // Run this code - #include #include + #include + #include #include - + int main() { std::ofstream os("test.txt"); std::ifstream is("test.txt"); std::string value("0"); - + os << "Hello"; is >> value; - - std::cout << "Result before tie(): \\"" << value << "\\"\\n"; + + std::cout << "Result before tie(): " << std::quoted(value) << "\\n"; is.clear(); is.tie(&os); - + is >> value; - - std::cout << "Result after tie(): \\"" << value << "\\"\\n"; + + std::cout << "Result after tie(): " << std::quoted(value) << "\\n"; } .SH Output: Result before tie(): "0" Result after tie(): "Hello" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + two streams could be tied to each + LWG 835 C++98 other^[1] the behavior is undefined + (either directly or through another in this case + intermediate stream object) + + 1. ↑ std::basic_ostream::flush() is an UnformattedOutputFunction, so it creates a + sentry object while being called. When flush() is called on a stream object, the + constructor of the sentry object will call flush() on its tied stream, and that + flush() will construct another sentry object and its constructor will call + flush() on the tied stream of that stream and so on. Therefore, if streams a and + b are (directly or indirectly) tied to each other, calling a.flush() will + eventually call b.flush(), which will eventually call a.flush(), and will result + in an infinite loop. diff --git a/man/std::basic_ios::widen.3 b/man/std::basic_ios::widen.3 index c02e686b2..f7d5906f7 100644 --- a/man/std::basic_ios::widen.3 +++ b/man/std::basic_ios::widen.3 @@ -1,4 +1,7 @@ -.TH std::basic_ios::widen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::widen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::widen \- std::basic_ios::widen + .SH Synopsis char_type widen( char c ) const; @@ -18,8 +21,8 @@ .SH See also narrow narrows characters - \fI(public member function)\fP - widen converts a character or characters from char to charT - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + \fI(public member function)\fP + do_widen converts a character or characters from char to CharT + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP btowc widens a single-byte narrow character to wide character, if possible - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_ios::~basic_ios.3 b/man/std::basic_ios::~basic_ios.3 index b0401c454..4b2204a05 100644 --- a/man/std::basic_ios::~basic_ios.3 +++ b/man/std::basic_ios::~basic_ios.3 @@ -1,11 +1,21 @@ -.TH std::basic_ios::~basic_ios 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ios::~basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::~basic_ios \- std::basic_ios::~basic_ios + .SH Synopsis virtual ~basic_ios(); - Destroys the basic_ios object. No operations on rdbuf are performed, it is not - destroyed. + Destroys the basic_ios object. rdbuf is not destroyed. .SH Notes This destructor is virtual because the base class destructor, ios_base::~ios_base is virtual. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 53 C++98 it was unspecified whether rdbuf is destroyed it is not destroyed diff --git a/man/std::basic_iostream.3 b/man/std::basic_iostream.3 index 5660d02d0..0a46e3225 100644 --- a/man/std::basic_iostream.3 +++ b/man/std::basic_iostream.3 @@ -1,35 +1,41 @@ -.TH std::basic_iostream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream \- std::basic_iostream + .SH Synopsis Defined in header template< class CharT, class Traits = std::char_traits + > class basic_iostream : + public basic_istream, - > class basic_iostream; + public basic_ostream The class template basic_iostream provides support for high level input/output operations on streams. The supported operations include sequential reading or - writing and formatting. This functionality is implemented over the interface, - provided by the basic_streambuf class. It is accessed through basic_ios class. + writing and formatting. This functionality is implemented over the interface + provided by the std::basic_streambuf class. It is accessed through std::basic_ios + class. std-basic iostream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - iostream basic_iostream - wiostream basic_iostream + Type Definition + std::iostream std::basic_iostream + std::wiostream std::basic_iostream .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type @@ -37,16 +43,16 @@ .SH Member functions constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP .SH Protected member functions operator= move-assigns another basic_iostream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP swap exchanges the state with another basic_iostream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP Inherited from std::basic_istream @@ -54,66 +60,66 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -126,45 +132,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -172,40 +178,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -213,76 +219,98 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the member types char_type, traits_type, + LWG 271 C++98 int_type, pos_type and off_type were not defined define + (std::basic_istream and std::basic_ostream both these types + define these types, resulted in ambiguity) + +.SH See also + + * Input/output manipulators diff --git a/man/std::basic_iostream::basic_iostream.3 b/man/std::basic_iostream::basic_iostream.3 index 70c4dcac2..f7d884fef 100644 --- a/man/std::basic_iostream::basic_iostream.3 +++ b/man/std::basic_iostream::basic_iostream.3 @@ -1,4 +1,7 @@ -.TH std::basic_iostream::basic_iostream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_iostream::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::basic_iostream \- std::basic_iostream::basic_iostream + .SH Synopsis explicit basic_iostream( std::basic_streambuf* sb ); \fB(1)\fP basic_iostream( const basic_iostream& other ) = delete; \fB(2)\fP \fI(since C++11)\fP @@ -28,4 +31,4 @@ .SH See also operator= move-assigns another basic_iostream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::basic_iostream::operator=.3 b/man/std::basic_iostream::operator=.3 index d3dae2ce3..7259ac957 100644 --- a/man/std::basic_iostream::operator=.3 +++ b/man/std::basic_iostream::operator=.3 @@ -1,4 +1,7 @@ -.TH std::basic_iostream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_iostream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::operator= \- std::basic_iostream::operator= + .SH Synopsis basic_iostream& operator=( const basic_iostream& other ) = delete; \fB(1)\fP protected: \fB(2)\fP \fI(since C++11)\fP @@ -23,4 +26,4 @@ .SH See also constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_iostream::swap.3 b/man/std::basic_iostream::swap.3 index 36a16e3de..38aeb007c 100644 --- a/man/std::basic_iostream::swap.3 +++ b/man/std::basic_iostream::swap.3 @@ -1,4 +1,7 @@ -.TH std::basic_iostream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_iostream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::swap \- std::basic_iostream::swap + .SH Synopsis protected: \fI(since C++11)\fP void swap( basic_iostream& other ); diff --git a/man/std::basic_iostream::~basic_iostream.3 b/man/std::basic_iostream::~basic_iostream.3 index c35fcbe21..026cd1c6b 100644 --- a/man/std::basic_iostream::~basic_iostream.3 +++ b/man/std::basic_iostream::~basic_iostream.3 @@ -1,4 +1,7 @@ -.TH std::basic_iostream::~basic_iostream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_iostream::~basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::~basic_iostream \- std::basic_iostream::~basic_iostream + .SH Synopsis virtual ~basic_iostream(); diff --git a/man/std::basic_ispanstream.3 b/man/std::basic_ispanstream.3 new file mode 100644 index 000000000..705c6f321 --- /dev/null +++ b/man/std::basic_ispanstream.3 @@ -0,0 +1,294 @@ +.TH std::basic_ispanstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ispanstream \- std::basic_ispanstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits (since C++23) + > class basic_ispanstream + + : public basic_istream + + The class template std::basic_ispanstream implements input operations on streams + based on fixed buffers. + + At the low level, the class essentially wraps a raw device implementation of + std::basic_spanbuf into a higher-level interface of std::basic_istream. The complete + interface to unique std::basic_spanbuf members is provided. + + std-basic ispanstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ispanstream std::basic_ispanstream + std::wispanstream std::basic_ispanstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + + Data members + + Member object Definition + sb (private) The wrapped std::basic_spanbuf. + (exposition-only member object*) + +.SH Member functions + + constructor constructs the basic_ispanstream + (C++23) \fI(public member function)\fP + destructor destroys the basic_ispanstream + \fB[virtual]\fP (C++23) \fI(virtual public member function)\fP + operator= move-assignments the basic_ispanstream + (C++23) \fI(public member function)\fP + swap swaps two basic_ispanstream objects + (C++23) \fI(public member function)\fP + rdbuf obtains the address of the wrapped raw span device object + (C++23) \fI(public member function)\fP + Underlying buffer operations + span gets or sets the underlying buffer of the wrapped span device + (C++23) object + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ispanstream) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_spanstream 202106L (C++23) std::spanbuf, std::spanstream diff --git a/man/std::basic_ispanstream::basic_ispanstream.3 b/man/std::basic_ispanstream::basic_ispanstream.3 new file mode 100644 index 000000000..3bbcd2a1b --- /dev/null +++ b/man/std::basic_ispanstream::basic_ispanstream.3 @@ -0,0 +1,63 @@ +.TH std::basic_ispanstream::basic_ispanstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ispanstream::basic_ispanstream \- std::basic_ispanstream::basic_ispanstream + +.SH Synopsis + explicit basic_ispanstream( std::span s, + std::ios_base::openmode mode = \fB(1)\fP (since C++23) + std::ios_base::in ); + template< class ROS > \fB(2)\fP (since C++23) + explicit basic_ispanstream( ROS&& r ); + basic_ispanstream( basic_ispanstream&& rhs ); \fB(3)\fP (since C++23) + basic_ispanstream( const basic_ispanstream& ) = delete; \fB(4)\fP (since C++23) + + Constructs a new basic_ispanstream. + + 1) Uses the storage referenced by s as initial underlying buffer of the wrapped + std::basic_spanbuf device. The wrapped std::basic_spanbuf object is constructed as + basic_spanbuf(s, mode | std::ios_base::in). + 2) Uses the storage referenced by r after converted to std::span as + initial underlying buffer of the wrapped std::basic_spanbuf device. The wrapped + std::basic_spanbuf object is opened in mode std::ios_base::in. This overload + participates in overload resolution only if ROS models borrowed_range, + std::convertible_to> is false, and std::convertible_to> is true. + 3) Move constructor. Move constructs the std::basic_istream base subobject and the + wrapped std::basic_spanbuf from those of rhs, and then calls set_rdbuf with the + address of the wrapped std::basic_spanbuf in *this to install it. + 4) Copy constructor is deleted. basic_ispanstream is not copyable. + +.SH Parameters + + s - std::span referencing the storage to be use as initial underlying buffer of + stream + r - borrowed_range to be use as initial underlying buffer of stream + specifies stream open mode. Following constants and bit-wise OR between them + may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another basic_ispanstream to be moved from + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_spanbuf object + (C++23) \fI(public member function of std::basic_spanbuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ispanstream::operator=.3 b/man/std::basic_ispanstream::operator=.3 new file mode 100644 index 000000000..aec9893d7 --- /dev/null +++ b/man/std::basic_ispanstream::operator=.3 @@ -0,0 +1,44 @@ +.TH std::basic_ispanstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ispanstream::operator= \- std::basic_ispanstream::operator= + +.SH Synopsis + basic_ispanstream& operator=( basic_ispanstream&& other ); \fB(1)\fP (since C++23) + basic_ispanstream& operator=( const basic_ispanstream& ) = delete; \fB(2)\fP (since C++23) + + 1) Move assigns the other to *this, effectively move-assigning both the + std::basic_istream base class subobject and the wrapped std::basic_spanbuf. + 2) Copy assignment operator is deleted. basic_ispanstream is not copy assignable. + + Note that move assignment operator of the base class swaps all stream state + variables (except for rdbuf()) between *this and other. + + It is implementation-defined whether the std::basic_spanbuf wrapped in other still + holds an underlying buffer after the move assignment. + +.SH Parameters + + other - another stream to move from + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_spanbuf object + (C++23) \fI(public member function of std::basic_spanbuf)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ispanstream::rdbuf.3 b/man/std::basic_ispanstream::rdbuf.3 new file mode 100644 index 000000000..56bac9d0d --- /dev/null +++ b/man/std::basic_ispanstream::rdbuf.3 @@ -0,0 +1,29 @@ +.TH std::basic_ispanstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ispanstream::rdbuf \- std::basic_ispanstream::rdbuf + +.SH Synopsis + std::basic_spanbuf* rdbuf() const noexcept; (since C++23) + + Returns pointer to the wrapped raw device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the wrapped raw device object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ispanstream::span.3 b/man/std::basic_ispanstream::span.3 new file mode 100644 index 000000000..9adc6d1e6 --- /dev/null +++ b/man/std::basic_ispanstream::span.3 @@ -0,0 +1,83 @@ +.TH std::basic_ispanstream::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ispanstream::span \- std::basic_ispanstream::span + +.SH Synopsis + std::span span() const noexcept; \fB(1)\fP (since C++23) + void span( std::span s ) noexcept; \fB(2)\fP (since C++23) + template< class SpanLike > \fB(3)\fP (since C++23) + void span( SpanLike&& r ) noexcept; + + 1) Gets a span referencing the written area if std::ios_base::out is set in the open + mode of the wrapped std::basic_spanbuf, or a span referencing the underlying buffer + otherwise. + 2) Makes the wrapped std::basic_spanbuf perform I/O on the buffer referenced by s. + 3) Same as \fB(2)\fP, except that s is obtained as if by + std::span cs{std::forward(r)}; + std::span s{const_cast(cs.data()), cs.size()}; + . This overload participates in overload resolution only if SpanLike models + borrowed_range, std::convertible_to> is false, and + std::convertible_to> is true. + +.SH Parameters + + s - std::span referencing the storage to be use as the new underlying buffer of + stream + r - borrowed_range to be use as the new underlying buffer of stream + +.SH Return value + + 1) A std::span referencing the underlying buffer or written area, depending on the + open mode of the wrapped std::basic_spanbuf. + 2,3) \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + char out_buf[16]; + std::ospanstream ost{std::span{out_buf}}; + ost << "C++" << ' ' << 23 << '\\0'; // note explicit null-termination + auto sp = ost.span(); + assert( + sp[0] == 'C' && sp[1] == '+' && sp[2] == '+' && + sp[3] == ' ' && sp[4] == '2' && sp[5] == '3' && + sp[6] == '\\0' + ); + std::cout << "sp.data(): [" << sp.data() << "]\\n"; + std::cout << "out_buf: [" << out_buf << "]\\n"; + // spanstream uses out_buf as internal storage, no allocations + assert(static_cast(out_buf) == sp.data()); + + const char in_buf[] = "X Y 42"; + std::ispanstream ist{std::span{in_buf}}; + assert(static_cast(in_buf) == ist.span().data()); + char c; + ist >> c; + assert(c == 'X'); + ist >> c; + assert(c == 'Y'); + int i; + ist >> i; + assert(i == 42); + ist >> i; // buffer is exhausted + assert(!ist); + } + +.SH Output: + + sp.data(): [C++ 23] + out_buf: [C++ 23] + +.SH See also + + span obtains or initializes an underlying buffer according to mode + (C++23) \fI(public member function of std::basic_spanbuf)\fP diff --git a/man/std::basic_ispanstream::swap.3 b/man/std::basic_ispanstream::swap.3 new file mode 100644 index 000000000..c43ec8471 --- /dev/null +++ b/man/std::basic_ispanstream::swap.3 @@ -0,0 +1,36 @@ +.TH std::basic_ispanstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ispanstream::swap \- std::basic_ispanstream::swap + +.SH Synopsis + void swap( basic_ispanstream& other ); (since C++23) + + Exchanges the state of the stream with those of other. + + This is done by calling std::basic_istream::swap(other) and swapping + the wrapped std::basic_spanbuf objects (accessible through *rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_spanbuf objects + (C++23) \fI(public member function of std::basic_spanbuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_istream.3 b/man/std::basic_istream.3 index fd5c15321..1212d3f28 100644 --- a/man/std::basic_istream.3 +++ b/man/std::basic_istream.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream \- std::basic_istream + .SH Synopsis Defined in header template< @@ -18,16 +21,15 @@ basic_istream::gcount(). std-basic istream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - istream basic_istream - wistream basic_istream + Type Definition + std::istream std::basic_istream + std::wistream std::basic_istream .SH Global objects @@ -35,13 +37,14 @@ Defined in header cin reads from the standard C input stream stdin - wcin (global object) + wcin (global object) .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type @@ -49,54 +52,54 @@ .SH Member functions constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fB[virtual]\fP \fI(virtual public member function)\fP - operator= replaces the buffer object - \fI(C++11)\fP \fI(protected member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP .SH Formatted input operator>> extracts formatted data - \fI(public member function)\fP + \fI(public member function)\fP .SH Unformatted input get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP peek reads the next character without extracting it - \fI(public member function)\fP + \fI(public member function)\fP unget unextracts a character - \fI(public member function)\fP - putback puts character into input stream - \fI(public member function)\fP + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function)\fP getline extracts characters until the given character is found - \fI(public member function)\fP + \fI(public member function)\fP ignore extracts and discards characters until the given character is found - \fI(public member function)\fP + \fI(public member function)\fP read extracts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP readsome extracts already available blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function)\fP + \fI(public member function)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function)\fP + \fI(public member function)\fP seekg sets the input position indicator - \fI(public member function)\fP + \fI(public member function)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function)\fP + \fI(public member function)\fP swap swaps stream objects, except for the associated buffer - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class)\fP + \fI(public member class)\fP .SH Non-member functions operator>>(std::basic_istream) extracts characters and character arrays - \fI(function template)\fP + \fI(function template)\fP Inherited from std::basic_ios @@ -109,45 +112,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -155,40 +158,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -196,76 +199,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::basic_istream::basic_istream.3 b/man/std::basic_istream::basic_istream.3 index aa90ea147..102f3fc85 100644 --- a/man/std::basic_istream::basic_istream.3 +++ b/man/std::basic_istream::basic_istream.3 @@ -1,9 +1,12 @@ -.TH std::basic_istream::basic_istream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::basic_istream \- std::basic_istream::basic_istream + .SH Synopsis - explicit basic_istream( std::basic_streambuf* sb); \fB(1)\fP - protected: \fB(2)\fP \fI(since C++11)\fP + explicit basic_istream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP basic_istream( const basic_istream& rhs ) = delete; - protected: \fB(3)\fP \fI(since C++11)\fP + protected: \fB(3)\fP \fI(since C++11)\fP basic_istream( basic_istream&& rhs ); 1) Constructs the basic_istream object, assigning initial values to the base class @@ -13,7 +16,7 @@ copyable. 3) The move constructor copies the value of gcount() from rhs, sets the gcount() - value of rhs to zero, and uses basic_ios::move(rhs) to move all + value of rhs to zero, and uses basic_ios::move(rhs) to move all basic_ios members, except for the rdbuf(), from rhs into *this. This move constructor is protected: it is called by the move constructors of movable input stream classes std::basic_ifstream and std::basic_istringstream, which know how to @@ -25,21 +28,22 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::istringstream s1("hello"); - std::istream s2(s1.rdbuf()); // OK: s2 shares the buffer with s1 - - // std::istream s3(std::istringstream("test")); // ERROR: move constructor is protected - // std::istream s4(s2); // ERROR: copy constructor is deleted - std::istringstream s5(std::istringstream("world")); // OK: move ctor called by derived class - + std::istream s2(s1.rdbuf()); // OK: s2 shares the buffer with s1 + + // std::istream s3(std::istringstream("test")); // ERROR: move constructor is protected + // std::istream s4(s2); // ERROR: copy constructor is deleted + std::istringstream s5(std::istringstream("world")); // OK: move ctor called + // by derived class + std::cout << s2.rdbuf() << ' ' << s5.rdbuf() << '\\n'; } diff --git a/man/std::basic_istream::gcount.3 b/man/std::basic_istream::gcount.3 index 34fcd0cc6..434789c51 100644 --- a/man/std::basic_istream::gcount.3 +++ b/man/std::basic_istream::gcount.3 @@ -1,8 +1,13 @@ -.TH std::basic_istream::gcount 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::gcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::gcount \- std::basic_istream::gcount + .SH Synopsis std::streamsize gcount() const; - Returns the number of characters extracted by the last unformatted input operation. + Returns the number of characters extracted by the last unformatted input operation, + or the maximum representable value of std::streamsize if the number is not + representable. The following member functions of basic_istream change the value of subsequent gcount() calls: @@ -29,21 +34,22 @@ .SH Return value - The number of characters extracted by the last unformatted input operation + The number of characters extracted by the last unformatted input operation, or the + maximum representable value of std::streamsize if the number is not representable. .SH Example - + // Run this code #include #include - + int main() { char x[20]; std::istringstream stream("Hello World"); - + stream.read(x, sizeof x); std::cout << "Characters extracted: " << stream.gcount(); } @@ -52,10 +58,11 @@ Characters extracted: 11 -.SH See also - - This section is incomplete + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo without reason + DR Applied to Behavior as published Correct behavior + LWG 3464 C++98 the return value was unspecified when the returns the maximum + result overflows value diff --git a/man/std::basic_istream::get.3 b/man/std::basic_istream::get.3 index e44f63f2b..fca8f370b 100644 --- a/man/std::basic_istream::get.3 +++ b/man/std::basic_istream::get.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::get \- std::basic_istream::get + .SH Synopsis int_type get(); \fB(1)\fP basic_istream& get( char_type& ch ); \fB(2)\fP @@ -18,37 +21,29 @@ unmodified and sets failbit and eofbit. Note that this function is not overloaded on the types signed char and unsigned char, unlike the formatted character input operator>>. - 3) Same as get(s, count, widen('\\n')), that is, reads at most count-1 characters and - stores them into character string pointed to by s until '\\n' is found. + 3) Same as get(s, count, widen('\\n')), that is, reads at most std::max(0, count - 1) + characters and stores them into character string pointed to by s until '\\n' is + found. 4) Reads characters and stores them into the successive locations of the character array whose first element is pointed to by s. Characters are extracted and stored until any of the following occurs: - - * n-1 characters have been stored - - * end of file condition occurs in the input sequence (setstate(eofbit) is called) - + * count is less than 1 or count - 1 characters have been stored. + * end of file condition occurs in the input sequence (setstate(eofbit) is called). * the next available input character c equals delim, as determined by - Traits::eq(c, delim). This character is not extracted (unlike - basic_istream::getline()) - - If no characters were extracted, calls setstate(failbit). In any case, if count>0, a - null character (CharT() is stored in the next successive location of the array. - 5) same as get(strbuf, widen('\\n')), that is, reads available characters and inserts + Traits::eq(c, delim). This character is not extracted (unlike getline()). + In any case, if count > 0, a null character (CharT() is stored in the next + successive location of the array. + 5) Same as get(strbuf, widen('\\n')), that is, reads available characters and inserts them to the given basic_streambuf object until '\\n' is found. - 6) reads characters and inserts them to the output sequence controlled by the given + 6) Reads characters and inserts them to the output sequence controlled by the given basic_streambuf object. Characters are extracted and inserted into strbuf until any of the following occurs: - - * end of file condition occurs in the input sequence - - * insert into the output sequence fails (in which case the character that could - not be inserted, is not extracted) - + * end of file condition occurs in the input sequence. + * inserting into the output sequence fails (in which case the character that could + not be inserted, is not extracted). * the next available input character c equals delim, as determined by Traits::eq(c, delim). This character is not extracted. - - * an exception occurs (in which case the exception is caught and not rethrown) + * an exception occurs (in which case the exception is caught and not rethrown). If no characters were extracted, calls setstate(failbit). @@ -60,17 +55,17 @@ s - pointer to the character string to store the characters to count - size of character string pointed to by s delim - delimiting character to stop the extraction at. It is not extracted and not - stored. + stored strbuf - stream buffer to read the content to .SH Return value - 1) the extracted character or Traits::eof() + 1) The extracted character or Traits::eof(). 2-6) *this .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -79,22 +74,24 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::istringstream s1("Hello, world."); char c1 = s1.get(); // reads 'H' std::cout << "after reading " << c1 << ", gcount() == " << s1.gcount() << '\\n'; + char c2; s1.get(c2); // reads 'e' char str[5]; s1.get(str, 5); // reads "llo," std::cout << "after reading " << str << ", gcount() == " << s1.gcount() << '\\n'; + std::cout << c1 << c2 << str; s1.get(*std::cout.rdbuf()); // reads the rest, not including '\\n' std::cout << "\\nAfter the last get(), gcount() == " << s1.gcount() << '\\n'; @@ -107,11 +104,23 @@ Hello, world. After the last get(), gcount() == 7 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the effect of overload \fB(5)\fP was get(s, corrected to + LWG 370 C++98 count, widen('\\n')), get(strbuf, widen('\\n')) + which is the effect of overload \fB(3)\fP + LWG 531 C++98 overloads (3,4) could not handle the no character is + case where count is non-positive extracted in this case + .SH See also read extracts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP operator>> extracts formatted data - \fI(public member function)\fP + \fI(public member function)\fP operator>>(std::basic_istream) extracts characters and character arrays - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::basic_istream::getline.3 b/man/std::basic_istream::getline.3 index 2b69556d7..f5d702dd1 100644 --- a/man/std::basic_istream::getline.3 +++ b/man/std::basic_istream::getline.3 @@ -1,31 +1,31 @@ -.TH std::basic_istream::getline 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::getline 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::getline \- std::basic_istream::getline + .SH Synopsis basic_istream& getline( char_type* s, std::streamsize count ); \fB(1)\fP basic_istream& getline( char_type* s, std::streamsize count, char_type delim ); \fB(2)\fP Extracts characters from stream until end of line or the specified delimiter delim. - The first version is equivalent to getline(s, count, widen(’\\n’)). + The first overload is equivalent to getline(s, count, widen('\\n')). Behaves as UnformattedInputFunction. After constructing and checking the sentry - object, extracts characters from *this and stored them in successive locations of - the array whose first element is pointed to by s until any of the following occurs: - (tested in the order shown) - - * end of file condition occurs in the input sequence (in which case - setstate(eofbit) is executed) + object, extracts characters from *this and stores them in successive locations of + the array whose first element is pointed to by s, until any of the following occurs + (tested in the order shown): - * the next available character c is the delimiter, as determined by Traits::eq(c, + 1. end of file condition occurs in the input sequence. + 2. the next available character c is the delimiter, as determined by Traits::eq(c, delim). The delimiter is extracted (unlike basic_istream::get()) and counted towards gcount(), but is not stored. + 3. count is non-positive, or count - 1 characters have been extracted + (setstate(failbit) is called in this case). - * count-1 characters have been extracted (in which case setstate(failbit) is - executed). + If the function extracts no characters, failbit is set in the local error state + before setstate() is called. - If the function extracts no characters (e.g. if count < 1), setstate(failbit) is - executed. - - In any case, if count>0, it then stores a null character CharT() into the next + In any case, if count > 0, it then stores a null character CharT() into the next successive location of the array and updates gcount(). .SH Notes @@ -49,7 +49,7 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -58,28 +58,26 @@ .SH Example - + // Run this code + #include #include #include #include - #include - + int main() { std::istringstream input("abc|def|gh"); std::vector> v; - + // note: the following loop terminates when std::ios_base::operator bool() // on the stream returned from getline() returns false - for (std::array a; input.getline(&a[0], 4, '|'); ) { + for (std::array a; input.getline(&a[0], 4, '|');) v.push_back(a); - } - - for (auto& a : v) { + + for (auto& a : v) std::cout << &a[0] << '\\n'; - } } .SH Output: @@ -88,13 +86,22 @@ def gh + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 531 C++98 std::getline could not handle the no character is + case where count is non-positive extracted in this case + .SH See also getline read data from an I/O stream into a string - \fI(function)\fP + \fI(function template)\fP operator>> extracts formatted data - \fI(public member function)\fP + \fI(public member function)\fP get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP read extracts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_istream::ignore.3 b/man/std::basic_istream::ignore.3 index bca9a2d5d..3ebb6f3a3 100644 --- a/man/std::basic_istream::ignore.3 +++ b/man/std::basic_istream::ignore.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::ignore 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::ignore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::ignore \- std::basic_istream::ignore + .SH Synopsis basic_istream& ignore( std::streamsize count = 1, int_type delim = Traits::eof() ); @@ -6,23 +9,21 @@ Extracts and discards characters from the input stream until and including delim. ignore behaves as an UnformattedInputFunction. After constructing and checking the - sentry object, it extracts characters from the stream and discards them until any - one of the following conditions occurs: + sentry object, it extracts characters from the stream and discards them until any of + the following conditions occurs: * count characters were extracted. This test is disabled in the special case when - count equals std::numeric_limits::max() - + count equals std::numeric_limits::max(). * end of file conditions occurs in the input sequence, in which case the function - calls setstate(eofbit) - + calls setstate(eofbit). * the next available character c in the input sequence is delim, as determined by Traits::eq_int_type(Traits::to_int_type(c), delim). The delimiter character is - extracted and discarded. This test is disabled if delim is Traits::eof() + extracted and discarded. This test is disabled if delim is Traits::eof(). .SH Parameters count - number of characters to extract - delim - delimiting character to stop the extraction at. It is also extracted. + delim - delimiting character to stop the extraction at. It is also extracted .SH Return value @@ -30,7 +31,7 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -41,30 +42,34 @@ The following example uses ignore to skip over non-numeric input: - + // Run this code #include - #include #include - + #include + + constexpr auto max_size = std::numeric_limits::max(); + int main() { std::istringstream input("1\\n" "some non-numeric input\\n" "2\\n"); - for(;;) { + for (;;) + { int n; input >> n; - - if (input.eof() || input.bad()) { + + if (input.eof() || input.bad()) break; - } else if (input.fail()) { + else if (input.fail()) + { input.clear(); // unset failbit - input.ignore(std::numeric_limits::max(), '\\n'); // skip bad input - } else { - std::cout << n << '\\n'; + input.ignore(max_size, '\\n'); // skip bad input } + else + std::cout << n << '\\n'; } } @@ -73,9 +78,18 @@ 1 2 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 172 C++98 the type of count was misspecified corrected to std::streamsize + as int + .SH See also get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP getline extracts characters until the given character is found - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_istream::operator=.3 b/man/std::basic_istream::operator=.3 index 1c1a960a7..52893b371 100644 --- a/man/std::basic_istream::operator=.3 +++ b/man/std::basic_istream::operator=.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::operator= \- std::basic_istream::operator= + .SH Synopsis protected: \fB(1)\fP basic_istream& operator=( const basic_istream& rhs ) = delete; @@ -7,7 +10,6 @@ 1) The copy assignment operator is protected, and is deleted. Input streams are not CopyAssignable. - 2) The move assignment operator exchanges the gcount() values and all data members of the base class, except for rdbuf(), with rhs, as if by calling swap(*rhs). This move assignment operator is protected: it is only called by the move assignment @@ -21,16 +23,16 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::istringstream s1; s1 = std::istringstream("test"); // OK - - std::cin = std::istringstream("test"); // ERROR: 'operator=' is protected + + // std::cin = std::istringstream("test"); // ERROR: 'operator=' is protected } diff --git a/man/std::basic_istream::operator>>.3 b/man/std::basic_istream::operator>>.3 index 8391075d3..f4a11f8af 100644 --- a/man/std::basic_istream::operator>>.3 +++ b/man/std::basic_istream::operator>>.3 @@ -1,107 +1,145 @@ -.TH std::basic_istream::operator>> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::operator>> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::operator>> \- std::basic_istream::operator>> + .SH Synopsis - basic_istream& operator>>( short& value ); \fB(1)\fP - basic_istream& operator>>( unsigned short& value ); - basic_istream& operator>>( int& value ); \fB(2)\fP - basic_istream& operator>>( unsigned int& value ); - basic_istream& operator>>( long& value ); \fB(3)\fP - basic_istream& operator>>( unsigned long& value ); - basic_istream& operator>>( long long& value ); \fB(4)\fP \fI(since C++11)\fP - basic_istream& operator>>( unsigned long long& value ); - basic_istream& operator>>( float& value ); - - basic_istream& operator>>( double& value ); \fB(5)\fP - - basic_istream& operator>>( long double& value ); - basic_istream& operator>>( bool& value ); \fB(6)\fP - basic_istream& operator>>( void*& value ); \fB(7)\fP - basic_istream& operator>>( basic_istream& st, - - std::ios_base& (*func)(std::ios_base&) + basic_istream& operator>>( unsigned short& value ); \fB(1)\fP + basic_istream& operator>>( unsigned int& value ); \fB(2)\fP + basic_istream& operator>>( long& value ); \fB(3)\fP + basic_istream& operator>>( unsigned long& value ); \fB(4)\fP + basic_istream& operator>>( long long& value ); \fB(5)\fP \fI(since C++11)\fP + basic_istream& operator>>( unsigned long long& value ); \fB(6)\fP \fI(since C++11)\fP + basic_istream& operator>>( float& value ); \fB(7)\fP + basic_istream& operator>>( double& value ); \fB(8)\fP + basic_istream& operator>>( long double& value ); \fB(9)\fP + basic_istream& operator>>( bool& value ); \fB(10)\fP + basic_istream& operator>>( void*& value ); \fB(11)\fP + basic_istream& operator>>( short& value ); \fB(12)\fP + basic_istream& operator>>( int& value ); \fB(13)\fP + basic_istream& operator>>( /* extended-floating-point-type */& \fB(14)\fP (since C++23) + value ); + basic_istream& operator>>( std::ios_base& (*func)(std::ios_base&) \fB(15)\fP ); - basic_istream& operator>>( basic_istream& st, - std::basic_ios& \fB(8)\fP - (*func)(std::basic_ios&) ); - basic_istream& operator>>( basic_istream& st, - - std::basic_istream& - (*func)(std::basic_istream&) ); - basic_istream& operator>>( basic_istream& st, - std::basic_streambuf* sb \fB(9)\fP + basic_istream& operator>>( std::basic_ios& + (*func)(std::basic_ios&) ); + basic_istream& operator>>( basic_istream& (*func)(basic_istream&) \fB(17)\fP ); - - 1-4) Behaves as an FormattedInputFunction. After constructing and checking the - sentry object, which may skip leading whitespace, extracts an integer value by - calling std::num_get::get() - - 5) Behaves as an FormattedInputFunction. After constructing and checking the sentry - object, which may skip leading whitespace, extracts a floating point value by - calling std::num_get::get() - - 6) Behaves as an FormattedInputFunction. After constructing and checking the sentry - object, which may skip leading whitespace, extracts bool value by calling - std::num_get::get() - - 7) Behaves as an FormattedInputFunction. After constructing and checking the sentry - object, which may skip leading whitespace, extracts a generic pointer value by - calling std::num_get::get() - - 8) Calls func(*this);, where func is an I/O manipulator. - - 9) Behaves as an UnformattedInputFunction. After constructing and checking the - sentry object, extracts all data from the input stream and stores it to sb. The - extraction stops if one of the following conditions are met: + basic_istream& operator>>( std::basic_streambuf* \fB(18)\fP + sb ); + + Extracts values from an input stream. + + 1-11) Extracts a value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a value by calling + std::num_get::get(). + 12) Extracts a short value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a long value lval by + calling std::num_get::get(). After that: + * If lval < std::numeric_limits::min(), sets failbit and stores + std::numeric_limits::min() to val. + * Otherwise, if std::numeric_limits::max() < lval, sets failbit and stores + std::numeric_limits::max() to val. + * Otherwise, stores static_cast(lval) to val. + 13) Extracts an int value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a long value lval by + calling std::num_get::get(). After that: + * If lval < std::numeric_limits::min(), sets failbit and stores + std::numeric_limits::min() to val. + * Otherwise, if std::numeric_limits::max() < lval, sets failbit and stores + std::numeric_limits::max() to val. + * Otherwise, stores static_cast(lval) to val. + 14) Extracts an extended floating-point value potentially skipping preceding + whitespace. The value is stored to a given reference value. The library provides + overloads for all cv-unqualified extended floating-point types as the referenced + type of the parameter value. + Determines the standard floating-point type FP as follows: + * If the floating-point conversion rank of /* extended-floating-point-type */ is + less than or equal to that of float, then FP is float. + * Otherwise, if the floating-point conversion rank of /* + extended-floating-point-type */ is less than or equal to that of double, then FP + is double. + * Otherwise, FP is long double. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts an FP value fval by + calling std::num_get::get(). After that: + * If fval < -std::numeric_limits::max(), sets + failbit and stores -std::numeric_limits::max() to val. + * Otherwise, if std::numeric_limits::max() < + fval, sets failbit and stores std::numeric_limits::max() to val. + * Otherwise, stores static_cast(fval) to val. + 15-17) Calls func(*this), where func is an I/O manipulator. + 18) Behaves as an UnformattedInputFunction. After constructing and checking the + sentry object, extracts all data from *this and stores it to sb. The extraction + stops if one of the following conditions are met: * end-of-file occurs on the input sequence; * inserting in the output sequence fails (in which case the character to be inserted is not extracted); - * an exception occurs (in which case the exception is caught, and only rethrown - exceptions on failbit are enabled). - + * an exception occurs (in which case the exception is caught, and only rethrown if + it inserted no characters and failbit is enabled in exceptions()). In either case, stores the number of characters extracted in the member variable accessed by subsequent calls to gcount(). If sb is a null pointer or if no - characters are inserted into sb, sets eofbit. + characters were inserted into sb, calls setstate(failbit) (which may throw + std::ios_base::failure if enabled). - If extraction fails (e.g. if a letter was entered where a digit is \fI(until C++11)\fP - expected), value is left unmodified and failbit is set. - If extraction fails, zero is written to value and failbit is set. If - extraction results in the value too large or too small to fit in \fI(since C++11)\fP - value, std::numeric_limits::max() or std::numeric_limits::min() - is written and failbit flag is set. + If extraction fails (e.g. if a letter was entered where a digit is expected), zero + is written to value and failbit is set. For signed integers, if extraction results + in the value too large or too small to fit in value, std::numeric_limits::max() + or std::numeric_limits::min() (respectively) is written and failbit flag is set. + For unsigned integers, if extraction results in the value too large or too small to + fit in value, std::numeric_limits::max() is written and failbit flag is set. .SH Parameters value - reference to an integer or floating-point value to store the extracted value to func - pointer to I/O manipulator function - sb - pointer to the streambuffer to write all the data to + sb - pointer to the stream buffer to write all the data to .SH Return value - *this + 1-16,18) *this + 17) func(*this) + +.SH Notes + + For overload \fB(14)\fP, when the extended floating-point type has a floating-point + conversion rank that is not equal to the rank of any standard floating-point type, + then double rounding during the conversion can result in inaccurate results. + std::from_chars() can be used in situations where maximum accuracy is important. .SH Example - + // Run this code - #include #include + #include #include - + int main() { std::string input = "41 3.14 false hello world"; std::istringstream stream(input); + int n; double f; bool b; - + stream >> n >> f >> std::boolalpha >> b; std::cout << "n = " << n << '\\n' << "f = " << f << '\\n' << "b = " << std::boolalpha << b << '\\n'; - + // extract the rest using the streambuf overload stream >> std::cout.rdbuf(); std::cout << '\\n'; @@ -114,28 +152,60 @@ b = false hello world + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether overload \fB(18)\fP + LWG 64 C++98 can only rethrow the all exceptions caught + std::ios_base::failure thrown by can be rethrown + calling setstate(failbit) + overload (12,13) delegated the + LWG 118 C++98 extraction to num_get::get, a long value is extracted + but it does not have overloads for instead of short or int + short and int + overload \fB(18)\fP only rethrew exceptions + LWG 413 C++98 thrown while extracting corrected sb to *this + characters from sb, but characters are + extracted from *this + overload \fB(18)\fP behaved as a + LWG 567 C++98 FormattedInputFunction it behaves as an + because of the resolution of LWG issue UnformattedInputFunction + 60 + overloads (12,13) did not store the + LWG 661 C++98 extracted number stores the number if + to value due to the resolution of LWG no overflow occurs + issue 118 + LWG 696 C++98 value was unchanged on extraction set to zero or minimum/ + failure maximum values + .SH See also operator>>(std::basic_istream) extracts characters and character arrays - \fI(function template)\fP + \fI(function template)\fP operator<< performs stream input and output on strings - operator>> \fI(function template)\fP + operator>> \fI(function template)\fP operator<< performs stream input and output of bitsets - operator>> \fI(function)\fP + operator>> \fI(function template)\fP operator<< serializes and deserializes a complex number - operator>> \fI(function template)\fP + operator>> \fI(function template)\fP operator<< performs stream input and output on pseudo-random operator>> number engine - \fI(function)\fP + \fI(C++11)\fP \fI(function template)\fP operator<< performs stream input and output on pseudo-random operator>> number distribution - \fI(function)\fP + \fI(C++11)\fP \fI(function template)\fP read extracts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP readsome extracts already available blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP extracts characters until the given character is getline found - \fI(public member function)\fP + \fI(public member function)\fP + from_chars converts a character sequence to an integer or + \fI(C++17)\fP floating-point value + \fI(function)\fP diff --git a/man/std::basic_istream::peek.3 b/man/std::basic_istream::peek.3 index bda42c3a5..64eb5921a 100644 --- a/man/std::basic_istream::peek.3 +++ b/man/std::basic_istream::peek.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::peek 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::peek 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::peek \- std::basic_istream::peek + .SH Synopsis int_type peek(); @@ -11,13 +14,13 @@ .SH Return value - If good() == true, returns the next character as obtained by rdbuf()->sgetc() + If good() == true, returns the next character as obtained by rdbuf()->sgetc(). Otherwise, returns Traits::eof(). .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -26,11 +29,12 @@ .SH Example - + // Run this code - #include #include + #include + int main() { std::istringstream s1("Hello, world."); @@ -46,8 +50,8 @@ .SH See also sgetc reads one character from the input sequence without advancing the sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP unget unextracts a character - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_istream::putback.3 b/man/std::basic_istream::putback.3 index 57eb5d5f9..6fa8681e7 100644 --- a/man/std::basic_istream::putback.3 +++ b/man/std::basic_istream::putback.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::putback 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::putback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::putback \- std::basic_istream::putback + .SH Synopsis basic_istream& putback( char_type ch ); @@ -17,7 +20,7 @@ .SH Parameters - \fI(none)\fP + ch - character to put into input stream .SH Return value @@ -25,7 +28,7 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -34,14 +37,14 @@ .SH Example - demonstrates the difference between modifying and non-modifying putback() + Demonstrates the difference between modifying and non-modifying putback(). + - // Run this code - #include #include - + #include + int main() { std::stringstream s1("Hello, world"); // IO stream @@ -50,15 +53,19 @@ std::cout << s1.rdbuf() << '\\n'; else std::cout << "putback failed\\n"; - + + std::cout << "--\\n"; + std::istringstream s2("Hello, world"); // input-only stream s2.get(); if (s2.putback('Y')) // cannot modify input-only buffer std::cout << s2.rdbuf() << '\\n'; else std::cout << "putback failed\\n"; - s2.clear(); + + std::cout << "--\\n"; + if (s2.putback('H')) // non-modifying putback std::cout << s2.rdbuf() << '\\n'; else @@ -68,14 +75,16 @@ .SH Output: Yello, world + -- putback failed + -- Hello, world .SH See also sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP unget unextracts a character - \fI(public member function)\fP + \fI(public member function)\fP peek reads the next character without extracting it - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_istream::read.3 b/man/std::basic_istream::read.3 index 2755481b7..50d124360 100644 --- a/man/std::basic_istream::read.3 +++ b/man/std::basic_istream::read.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::read 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::read 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::read \- std::basic_istream::read + .SH Synopsis basic_istream& read( char_type* s, std::streamsize count ); @@ -9,10 +12,9 @@ character array whose first element is pointed to by s. Characters are extracted and stored until any of the following conditions occurs: - * count characters were extracted and stored - + * count characters were extracted and stored. * end of file condition occurs on the input sequence (in which case, - setstate(failbit|eofbit) is called. The number of successfully extracted + setstate(failbit|eofbit) is called). The number of successfully extracted characters can be queried using gcount(). .SH Parameters @@ -26,86 +28,71 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. If an internal operation throws an exception, it is caught and badbit is set. If exceptions() is set for badbit, the exception is rethrown. +.SH Notes + + When using a non-converting locale (the default locale is non-converting), the + overrider of this function in std::basic_ifstream may be optimized for zero-copy + bulk I/O (by means of overriding std::streambuf::xsgetn). + .SH Example - + // Run this code - #include + #include #include + #include #include #include - #include - + int main() { // read() is often used for binary I/O std::string bin = {'\\x12', '\\x12', '\\x12', '\\x12'}; std::istringstream raw(bin); std::uint32_t n; - raw.read(reinterpret_cast(&n), sizeof n); - std::cout << std::hex << std::showbase << n << '\\n'; - + if (raw.read(reinterpret_cast(&n), sizeof n)) + std::cout << std::hex << std::showbase << n << '\\n'; + // prepare file for next snippet - std::ofstream os("test.txt", std::ofstream::binary); - for (unsigned i = 0; i < 10; i++) { // prepare stream - os << "abcd" << i << "\\n"; - } - os.close(); - + std::ofstream("test.txt", std::ios::binary) << "abcd1\\nabcd2\\nabcd3"; + // read entire file into string - std::ifstream is("test.txt", std::ifstream::binary); - if (is) { - // get length of file: - is.seekg(0, is.end); - int length = is.tellg(); - is.seekg(0, is.beg); - - std::string str; - str.resize(length, ' '); // reserve space - char* begin = &*str.begin(); - - is.read(begin, length); - is.close(); - - std::cout << str << "\\n"; - } else { - std::cout << "Could not open test.txt\\n"; + if (std::ifstream is{"test.txt", std::ios::binary | std::ios::ate}) + { + auto size = is.tellg(); + std::string str(size, '\\0'); // construct string to stream size + is.seekg(0); + if (is.read(&str[0], size)) + std::cout << str << '\\n'; } } .SH Output: 0x12121212 - abcd0 abcd1 abcd2 abcd3 - abcd4 - abcd5 - abcd6 - abcd7 - abcd8 - abcd9 .SH See also write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP operator>> extracts formatted data - \fI(public member function)\fP + \fI(public member function)\fP readsome extracts already available blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP getline extracts characters until the given character is found - \fI(public member function)\fP + \fI(public member function)\fP fread reads from a file - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_istream::readsome.3 b/man/std::basic_istream::readsome.3 index 12f32178c..88305a46e 100644 --- a/man/std::basic_istream::readsome.3 +++ b/man/std::basic_istream::readsome.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::readsome 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::readsome 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::readsome \- std::basic_istream::readsome + .SH Synopsis std::streamsize readsome( char_type* s, std::streamsize count ); @@ -9,11 +12,9 @@ object, * If rdbuf()->in_avail() == -1, calls setstate(eofbit) and extracts no characters. - * If rdbuf()->in_avail() == 0, extracts no characters. - * If rdbuf()->in_avail() > 0, extracts std::min(rdbuf()->in_avail(), count) - characters and stores them into successive locations of the characater array + characters and stores them into successive locations of the character array whose first element is pointed to by s. .SH Parameters @@ -27,7 +28,7 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -47,16 +48,30 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + char c[10] = {}; + std::istringstream input("This is sample text."); // std::stringbuf makes its entire + // buffer available for + // unblocking read + input.readsome(c, 5); // reads 'This ' and stores in c[0] .. c[4] + input.readsome(c, 9); // reads 'is sample' and stores in c[0] .. c[8] + std::cout << c << '\\n'; + } + +.SH Output: + + is sample .SH See also read extracts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP in_avail obtains the number of characters immediately available in the get area - \fI(public member function of std::basic_streambuf)\fP - -.SH Category: - - * Todo no example + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::basic_istream::seekg.3 b/man/std::basic_istream::seekg.3 index fff801263..a468b667d 100644 --- a/man/std::basic_istream::seekg.3 +++ b/man/std::basic_istream::seekg.3 @@ -1,25 +1,32 @@ -.TH std::basic_istream::seekg 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::seekg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::seekg \- std::basic_istream::seekg + .SH Synopsis - basic_istream& seekg( pos_type pos ); - basic_istream& seekg( off_type off, std::ios_base::seekdir dir); + basic_istream& seekg( pos_type pos ); \fB(1)\fP + basic_istream& seekg( off_type off, std::ios_base::seekdir dir ); \fB(2)\fP - Sets input position indicator of the current associated streambuf object. In case of - failure, calls setstate(std::ios_base::failbit). + Sets input position indicator of the current associated streambuf object. Before doing anything else, seekg clears eofbit. \fI(since C++11)\fP seekg behaves as UnformattedInputFunction, except that gcount() is not affected. After constructing and checking the sentry object, - 1) sets the input position indicator to absolute (relative to the beginning of the - file) value pos. Specifically, executes rdbuf()->pubseekpos(pos, std::ios_base::in). - 2) sets the input position indicator to position off, relative to position, defined - by dir. Specifically, executes rdbuf()->pubseekoff(off, dir, std::ios_base::in). + 1) if fail() != true, sets the input position indicator to absolute (relative to the + beginning of the file) value pos. Specifically, executes rdbuf()->pubseekpos(pos, + std::ios_base::in) (pubseekpos, in turn, calls seekpos of the specific buffer, such + as basic_filebuf::seekpos, basic_stringbuf::seekpos, or strstreambuf::seekpos). In + case of failure, calls setstate(std::ios_base::failbit). + 2) if fail() != true, sets the input position indicator to position off, relative to + position, defined by dir. Specifically, executes rdbuf()->pubseekoff(off, dir, + std::ios_base::in). In case of failure, calls setstate(std::ios_base::failbit). .SH Parameters - pos - absolute position to set the input position indicator to. - off - relative position to set the input position indicator to. + pos - absolute position to set the input position indicator to + off - relative position (positive or negative) to set the input position indicator + to defines base position to apply the relative offset to. It can be one of the following constants: @@ -34,32 +41,37 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. If an internal operation throws an exception, it is caught and badbit is set. If exceptions() is set for badbit, the exception is rethrown. +.SH Notes + + seekg(n) is not necessarily equivalent to seekg(n, ios::beg). std::basic_ifstream, + for example, requires the absolute position n to come from tellg(). + .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::string str = "Hello, world"; std::istringstream in(str); std::string word1, word2; - + in >> word1; in.seekg(0); // rewind in >> word2; - + std::cout << "word1 = " << word1 << '\\n' << "word2 = " << word2 << '\\n'; } @@ -69,11 +81,45 @@ word1 = Hello, word2 = Hello, + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 129 C++98 there was no way to indicate a failure sets failbit on failure + LWG 136 C++98 seekg could set the output stream only sets the input stream + LWG 537 C++98 the type of off was off_type& corrected to off_type + .SH See also - tellg returns the input position indicator - \fI(public member function)\fP - tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP - seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + tellg returns the input position indicator + \fI(public member function)\fP + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::basic_istream::sentry.3 b/man/std::basic_istream::sentry.3 index fa5f20f6e..57fab4d3d 100644 --- a/man/std::basic_istream::sentry.3 +++ b/man/std::basic_istream::sentry.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::sentry 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::sentry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::sentry \- std::basic_istream::sentry + .SH Synopsis class sentry; @@ -6,9 +9,10 @@ beginning of each member function of std::basic_istream that performs input (both formatted and unformatted). Its constructor prepares the input stream: checks if the stream is already in a failed state, flushes the tie()'d output streams, skips - leading whitespace if skipws flag is set, and performs other implementation-defined - tasks if necessary. All cleanup, if necessary, is performed in the destructor, so - that it is guaranteed to happen if exceptions are thrown during input. + leading whitespace unless noskipws flag is set, and performs other + implementation-defined tasks if necessary. All cleanup, if necessary, is performed + in the destructor, so that it is guaranteed to happen if exceptions are thrown + during input. .SH Member types @@ -17,36 +21,37 @@ .SH Member functions constructor constructs the sentry object. All the preparation tasks are done here - \fI(public member function)\fP + \fI(public member function)\fP finalizes the stream object after formatted input or after exception, destructor if necessary - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy assignable [deleted] \fI(public member function)\fP operator bool checks if the preparation of the stream object was successful - \fI(public member function)\fP + \fI(public member function)\fP - std::basic_istream::sentry::sentry +std::basic_istream::sentry::sentry - explicit sentry(std::basic_istream& is, bool noskipws = false); + explicit sentry( std::basic_istream& is, bool noskipws = false ); Prepares the stream for formatted input. - If is.good() is false, calls is.setstate(failbit)(since c++11) and returns. + If is.good() is false, calls is.setstate(std::ios_base::failbit) and returns. Otherwise, if is.tie() is not a null pointer, calls is.tie()->flush() to synchronize the output sequence with external streams. This call can be suppressed if the put - area of is.tie() is empty. The implementation may defer the call to flush until a + area of is.tie() is empty. The implementation may defer the call to flush() until a call of is.rdbuf()->underflow() occurs. If no such call occurs before the sentry object is destroyed, it may be eliminated entirely. - If noskipws is zero and is.flags() & ios_base::skipws is nonzero, the function + If noskipws is zero and is.flags() & std::ios_base::skipws is nonzero, the function extracts and discards all whitespace characters until the next available character is not a whitespace character (as determined by the currently imbued locale in is). If is.rdbuf()->sbumpc() or is.rdbuf()->sgetc() returns traits::eof(), the function - calls setstate(failbit | eofbit) (which may throw std::ios_base::failure). + calls setstate(std::ios_base::failbit | std::ios_base::eofbit) (which may throw + std::ios_base::failure). Additional implementation-defined preparation may take place, which may call - setstate(failbit) (which may throw std::ios_base::failure). + setstate(std::ios_base::failbit) (which may throw std::ios_base::failure). If after preparation is completed, is.good() == true, then any subsequent calls to operator bool will return true. @@ -60,13 +65,13 @@ std::ios_base::failure if the end of file condition occurs when skipping whitespace. - std::basic_istream::sentry::~sentry +std::basic_istream::sentry::~sentry ~sentry(); Does nothing. - std::basic_istream::sentry::operator bool +std::basic_istream::sentry::operator bool explicit operator bool() const; @@ -82,17 +87,17 @@ .SH Example - + // Run this code #include #include - + struct Foo { - char n[5]; + char n[5]; }; - + std::istream& operator>>(std::istream& is, Foo& f) { std::istream::sentry s(is); @@ -100,7 +105,7 @@ is.read(f.n, 5); return is; } - + int main() { std::string input = " abcde"; @@ -115,9 +120,20 @@ abcde + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 195 C++98 it was unclear whether the constructor made clear + would set eofbit + LWG 419 C++98 the constructor did not set failbit if sets failbit in this case + eofbit has been set + .SH See also operator>> extracts formatted data - \fI(public member function)\fP + \fI(public member function)\fP operator>>(std::basic_istream) extracts characters and character arrays - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::basic_istream::swap.3 b/man/std::basic_istream::swap.3 index 4e497b4b4..baeb989c7 100644 --- a/man/std::basic_istream::swap.3 +++ b/man/std::basic_istream::swap.3 @@ -1,7 +1,10 @@ -.TH std::basic_istream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::swap \- std::basic_istream::swap + .SH Synopsis - protected: \fI(since C++11)\fP - void swap(basic_istream& rhs); + protected: \fI(since C++11)\fP + void swap( basic_istream& rhs ); Calls basic_ios::swap(rhs) to swap all data members of the base class except for rdbuf(), and swaps the values of the gcount() counters between *this and rhs. This @@ -15,22 +18,23 @@ .SH Example - + // Run this code - #include #include + #include #include + int main() { std::istringstream s1("hello"); std::istringstream s2("bye"); - + s1.swap(s2); // OK, istringstream has a public swap() std::swap(s1, s2); // OK, calls s1.swap(s2) // std::cin.swap(s2); // ERROR: swap is a protected member - - std::cout << s1.rdbuf(); + + std::cout << s1.rdbuf() << '\\n'; } .SH Output: diff --git a/man/std::basic_istream::sync.3 b/man/std::basic_istream::sync.3 index 4460cd94f..3bba89af5 100644 --- a/man/std::basic_istream::sync.3 +++ b/man/std::basic_istream::sync.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::sync 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::sync \- std::basic_istream::sync + .SH Synopsis int sync(); @@ -7,7 +10,7 @@ Behaves as UnformattedInputFunction, except that gcount() is not affected. After constructing and checking the sentry object, - if rdbuf() is a null pointer, returns -1 + If rdbuf() is a null pointer, returns -1. Otherwise, calls rdbuf()->pubsync(). If that function returns -1, calls setstate(badbit) and returns -1. Otherwise, returns 0. @@ -33,47 +36,54 @@ .SH Example - Demonstrates the use of input stream sync() with file input, as implemented on some - platforms. + Demonstrates the use of input stream sync() with file input. Note that output here + is implementation-defined, since calls to std::basic_filebuf::sync are + implementation-defined for reads. + - // Run this code - #include #include - + #include + void file_abc() { std::ofstream f("test.txt"); f << "abc\\n"; } - + void file_123() { std::ofstream f("test.txt"); f << "123\\n"; } - + int main() { file_abc(); // file now contains "abc" std::ifstream f("test.txt"); std::cout << "Reading from the file\\n"; char c; - f >> c; std::cout << c; + f >> c; + std::cout << c; file_123(); // file now contains "123" - f >> c; std::cout << c; - f >> c; std::cout << c << '\\n'; + f >> c; + std::cout << c; + f >> c; + std::cout << c << '\\n'; f.close(); - + file_abc(); // file now contains "abc" f.open("test.txt"); std::cout << "Reading from the file, with sync()\\n"; - f >> c; std::cout << c; + f >> c; + std::cout << c; file_123(); // file now contains "123" f.sync(); - f >> c; std::cout << c; - f >> c; std::cout << c << '\\n'; + f >> c; + std::cout << c; + f >> c; + std::cout << c << '\\n'; } .SH Possible output: @@ -83,9 +93,19 @@ Reading from the file, with sync() a23 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 62 C++98 sync() returned traits::eof() if returns -1 in this + rdbuf()->pubsync() returns -1 case + .SH See also sync synchronizes the buffers with the associated character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::basic_istream::tellg.3 b/man/std::basic_istream::tellg.3 index b0b2d29d0..54a391297 100644 --- a/man/std::basic_istream::tellg.3 +++ b/man/std::basic_istream::tellg.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::tellg 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::tellg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::tellg \- std::basic_istream::tellg + .SH Synopsis pos_type tellg(); @@ -15,11 +18,11 @@ .SH Return value - The current position of the get pointer on success, pos_type(-1) on failure + The current position of the get pointer on success, pos_type(-1) on failure. .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -28,13 +31,13 @@ .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::string str = "Hello, world"; @@ -51,9 +54,19 @@ .SH See also - seekg sets the input position indicator - \fI(public member function)\fP - tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP - seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + seekg sets the input position indicator + \fI(public member function)\fP + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::basic_istream::unget.3 b/man/std::basic_istream::unget.3 index 066da455c..020541534 100644 --- a/man/std::basic_istream::unget.3 +++ b/man/std::basic_istream::unget.3 @@ -1,12 +1,14 @@ -.TH std::basic_istream::unget 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::unget 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::unget \- std::basic_istream::unget + .SH Synopsis basic_istream& unget(); Makes the most recently extracted character available again. - First clears eofbit. \fI(since C++11)\fP - - Then the function behaves as UnformattedInputFunction. After constructing and + First, clears eofbit. Then, + \fI(since C++11)\fP unget behaves as UnformattedInputFunction. After constructing and checking the sentry object, if any ios_base::iostate flags are set, the function sets failbit and returns. Otherwise, calls rdbuf()->sungetc(). @@ -24,7 +26,7 @@ .SH Exceptions - + failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state. @@ -33,12 +35,12 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::istringstream s1("Hello, world."); @@ -46,21 +48,21 @@ if (s1.unget()) { char c2 = s1.get(); - std::cout << "Got: " << c1 << " got again: " << c2 << '\\n'; + std::cout << "Got: '" << c1 << "'. Got again: '" << c2 << "'.\\n"; } } .SH Output: - Got: H got again: H + Got: 'H'. Got again: 'H'. .SH See also sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP get extracts characters - \fI(public member function)\fP + \fI(public member function)\fP peek reads the next character without extracting it - \fI(public member function)\fP - putback puts character into input stream - \fI(public member function)\fP + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function)\fP diff --git a/man/std::basic_istream::~basic_istream.3 b/man/std::basic_istream::~basic_istream.3 index b16e3b763..132879f14 100644 --- a/man/std::basic_istream::~basic_istream.3 +++ b/man/std::basic_istream::~basic_istream.3 @@ -1,4 +1,7 @@ -.TH std::basic_istream::~basic_istream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istream::~basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::~basic_istream \- std::basic_istream::~basic_istream + .SH Synopsis virtual ~basic_istream(); @@ -13,12 +16,12 @@ .SH Example - + // Run this code - #include #include - + #include + void print_stringbuf(std::streambuf* p) { std::istream buf(p); // buf shares the buffer with s1 @@ -26,7 +29,7 @@ buf >> n; std::cout << n; } // calls the destructor of buf. p remains unaffected - + int main() { std::istringstream s1("10 20"); diff --git a/man/std::basic_istringstream.3 b/man/std::basic_istringstream.3 index 3d2cc64a6..ec453448b 100644 --- a/man/std::basic_istringstream.3 +++ b/man/std::basic_istringstream.3 @@ -1,66 +1,74 @@ -.TH std::basic_istringstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream \- std::basic_istringstream + .SH Synopsis Defined in header - template< - - class CharT, \fI(until C++11)\fP - class Traits = std::char_traits - - > class basic_istringstream; template< class CharT, - class Traits = std::char_traits, \fI(since C++11)\fP + class Traits = std::char_traits, class Allocator = std::allocator - > class basic_istringstream; + > class basic_istringstream : public basic_istream; + + The class template std::basic_istringstream implements input operations on string + based streams. It effectively stores an instance of std::basic_string and performs + input operations on it. - The class template std::basic_istringstream implements input operations on memory - (std::basic_string) based streams. It essentially wraps a raw string device - implementation (std::basic_stringbuf) into a higher-level interface - (std::basic_istream). The complete interface to unique std::basic_stringbuf members - is provided. + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_istream. The + complete interface to unique std::basic_stringbuf members is provided. std-basic istringstream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - istringstream basic_istringstream - wistringstream basic_istringstream + Type Definition + std::istringstream std::basic_istringstream + std::wistringstream std::basic_istringstream .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type - allocator_type Allocator \fI(since C++11)\fP + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) .SH Member functions constructor constructs the string stream - \fI(public member function)\fP + \fI(public member function)\fP operator= moves the string stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP rdbuf returns the underlying raw string device object - \fI(public member function)\fP + \fI(public member function)\fP .SH String operations str gets or sets the contents of underlying string device object - \fI(public member function)\fP + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP .SH Non-member functions std::swap(std::basic_istringstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_istream @@ -68,40 +76,40 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ios @@ -114,45 +122,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -160,40 +168,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -201,76 +209,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::basic_istringstream::basic_istringstream.3 b/man/std::basic_istringstream::basic_istringstream.3 index 94aca3a0b..f9d4b1964 100644 --- a/man/std::basic_istringstream::basic_istringstream.3 +++ b/man/std::basic_istringstream::basic_istringstream.3 @@ -1,46 +1,144 @@ -.TH std::basic_istringstream::basic_istringstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istringstream::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::basic_istringstream \- std::basic_istringstream::basic_istringstream + .SH Synopsis - explicit basic_istringstream( ios_base::openmode mode = \fB(1)\fP - ios_base::in ); - explicit basic_istringstream( const - std::basic_string& str, \fB(2)\fP - ios_base::openmode mode = ios_base::in ); - basic_istringstream( basic_istringstream&& other ); \fB(3)\fP \fI(since C++11)\fP + explicit basic_istringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::in ); + explicit basic_istringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_istringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_istringstream(std::ios_base::in) {} + explicit basic_istringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + explicit basic_istringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + basic_istringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_istringstream(str, std::ios_base::in, a) {} + template< class SAlloc > + + explicit basic_istringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + explicit basic_istringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + basic_istringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_istringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_istringstream( basic_istringstream&& other ); \fB(12)\fP \fI(since C++11)\fP Constructs new string stream. - 1) Constructs new underlying string device. The underlying basic_stringbuf object is - constructed as basic_stringbuf(mode | ios_base::in). + Given + + * base_type as std::basic_istream, and + * buf_type as std::basic_stringbuf, - 2) Uses a copy of str as initial contents of the underlying string device. The - underlying basic_stringbuf object is constructed as - basic_stringbuf(str, mode | ios_base::in). + the std::basic_istream base and the exposition-only data member sb are initialized + as follows. - 3) Move constructor. Constructs the file stream with the state of other using move - semantics. + Over std::basic_istream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::in) + \fB(2)\fP buf_type(std::ios_base::in) + \fB(3)\fP buf_type(str, mode | + std::ios_base::in) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::in) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::in, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::in, a) + \fB(7)\fP buf_type(str, std::ios_base::in, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::in) + \fB(9)\fP {t, mode | std::ios_base::in, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::in, a} + \fB(11)\fP {t, std::ios_base::in, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_istream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. .SH Parameters str - string to use as initial contents of the string stream - specifies stream open mode. It is bitmask type, the following constants are + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are defined: - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode other - another string stream to use as source +.SH Notes + + Construction of one-off basic_istringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + .SH Example - + // Run this code #include #include + int main() { // default constructor (input/output stream) @@ -49,12 +147,12 @@ int n = 0; buf1 >> n; std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; - + // input stream std::istringstream inbuf("-10"); inbuf >> n; std::cout << "n = " << n << '\\n'; - + // output stream in append mode \fI(C++11)\fP std::ostringstream buf2("test", std::ios_base::ate); buf2 << '1'; @@ -67,9 +165,18 @@ n = -10 test1 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + .SH See also str gets or sets the contents of underlying string device object - \fI(public member function)\fP - constructor constructs a basic_stringbuf object - \fI(public member function of std::basic_stringbuf)\fP + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::basic_istringstream::operator=.3 b/man/std::basic_istringstream::operator=.3 index 5c8875331..dcd3081c3 100644 --- a/man/std::basic_istringstream::operator=.3 +++ b/man/std::basic_istringstream::operator=.3 @@ -1,13 +1,19 @@ -.TH std::basic_istringstream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::operator= \- std::basic_istringstream::operator= + .SH Synopsis basic_istringstream& operator=( basic_istringstream&& other ); \fI(since C++11)\fP - Moves the string stream. The source stream becomes of invalid state after the - operation. + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_istream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. .SH Parameters - other - string stream to move. other becomes of invalid state after the operation. + other - string stream to move from .SH Return value @@ -20,9 +26,13 @@ .SH See also - swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP -.SH Category: + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Category: * Todo no example diff --git a/man/std::basic_istringstream::rdbuf.3 b/man/std::basic_istringstream::rdbuf.3 index fc9a4423d..2718198e0 100644 --- a/man/std::basic_istringstream::rdbuf.3 +++ b/man/std::basic_istringstream::rdbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_istringstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::rdbuf \- std::basic_istringstream::rdbuf + .SH Synopsis std::basic_stringbuf* rdbuf() const; @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_istringstream::str.3 b/man/std::basic_istringstream::str.3 index a53e82c57..3c092e8bd 100644 --- a/man/std::basic_istringstream::str.3 +++ b/man/std::basic_istringstream::str.3 @@ -1,24 +1,48 @@ -.TH std::basic_istringstream::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::str \- std::basic_istringstream::str + .SH Synopsis - std::basic_string str() const; \fB(1)\fP - void str(const std::basic_string& new_str); \fB(2)\fP + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); Manages the contents of the underlying string object. - 1) Returns a copy of the underlying string as if by calling rdbuf()->str(). - - 2) Replaces the contents of the underlying string as if by calling - rdbuf()->str(new_str). + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. .SH Parameters - new_str - new contents of the underlying string + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string .SH Return value - 1) a copy of the underlying string object. - - 2) \fI(none)\fP + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP .SH Notes @@ -27,41 +51,49 @@ of str() (for example in auto *ptr = out.str().c_str();) results in a dangling pointer. + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + .SH Example - + // Run this code - #include #include + #include + int main() { int n; - - std::istringstream in; // could also use in("1 2") + + std::istringstream in; // could also use in("1 2") in.str("1 2"); in >> n; - std::cout << "after reading the first int from \\"1 2\\", the int is " + std::cout << "After reading the first int from \\"1 2\\", the int is " << n << ", str() = \\"" << in.str() << "\\"\\n"; - + std::ostringstream out("1 2"); out << 3; - std::cout << "after writing the int '3' to output stream \\"1 2\\"" + std::cout << "After writing the int '3' to output stream \\"1 2\\"" << ", str() = \\"" << out.str() << "\\"\\n"; - + std::ostringstream ate("1 2", std::ios_base::ate); ate << 3; - std::cout << "after writing the int '3' to append stream \\"1 2\\"" + std::cout << "After writing the int '3' to append stream \\"1 2\\"" << ", str() = \\"" << ate.str() << "\\"\\n"; } .SH Output: - after reading the first int from "1 2", the int is 1, str() = "1 2" - after writing the int '3' to output stream "1 2", str() = "3 2" - after writing the int '3' to append stream "1 2", str() = "1 23" + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" .SH See also - str replaces or obtains a copy of the associated character string - \fI(public member function of std::basic_stringbuf)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::basic_istringstream::swap.3 b/man/std::basic_istringstream::swap.3 index bbcd77091..c7cccfc1e 100644 --- a/man/std::basic_istringstream::swap.3 +++ b/man/std::basic_istringstream::swap.3 @@ -1,11 +1,14 @@ -.TH std::basic_istringstream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_istringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::swap \- std::basic_istringstream::swap + .SH Synopsis void swap( basic_istringstream& other ); \fI(since C++11)\fP Exchanges the state of the stream with those of other. This is done by calling basic_istream::swap(other) and - rdbuf->swap(other->rdbuf). + rdbuf()->swap(*other.rdbuf()). .SH Parameters @@ -15,6 +18,10 @@ \fI(none)\fP +.SH Exceptions + + May throw implementation-defined exceptions. + .SH Example This section is incomplete @@ -23,10 +30,10 @@ .SH See also operator= moves the string stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_stringbuf objects - \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP -.SH Category: +.SH Category: * Todo no example diff --git a/man/std::basic_istringstream::view.3 b/man/std::basic_istringstream::view.3 new file mode 100644 index 000000000..06eecf651 --- /dev/null +++ b/man/std::basic_istringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_istringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::view \- std::basic_istringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::basic_ofstream.3 b/man/std::basic_ofstream.3 index 5acb2f287..110ede1ad 100644 --- a/man/std::basic_ofstream.3 +++ b/man/std::basic_ofstream.3 @@ -1,4 +1,7 @@ -.TH std::basic_ofstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream \- std::basic_ofstream + .SH Synopsis Defined in header template< @@ -16,77 +19,81 @@ member: an instance of std::basic_filebuf. std-basic ofstream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - ofstream basic_ofstream - wofstream basic_ofstream + Type Definition + std::ofstream std::basic_ofstream + std::wofstream std::basic_ofstream .SH Member types - Member type Definition - char_type CharT - traits_type Traits - int_type Traits::int_type - pos_type Traits::pos_type - off_type Traits::off_type + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular .SH Member functions constructor constructs the file stream - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the basic_ofstream and the associated \fB[virtual]\fP (implicitly declared) buffer, closes the file - \fI(virtual public member function)\fP + \fI(virtual public member function)\fP operator= moves the file stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP rdbuf returns the underlying raw file device object - \fI(public member function)\fP + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP .SH File operations is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::basic_ofstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -99,45 +106,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -145,40 +152,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -186,76 +193,121 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "Test.b"; + { + std::ofstream ostrm(filename, std::ios::binary); + double d = 3.14; + ostrm.write(reinterpret_cast(&d), sizeof d); // binary output + ostrm << 123 << "abc" << '\\n'; // text output + } + + // read back + std::ifstream istrm(filename, std::ios::binary); + double d; + istrm.read(reinterpret_cast(&d), sizeof d); + int n; + std::string s; + istrm >> n >> s; + std::cout << " read back: " << d << ' ' << n << ' ' << s << '\\n'; + } + +.SH Output: + + read back: 3.14 123 abc diff --git a/man/std::basic_ofstream::basic_ofstream.3 b/man/std::basic_ofstream::basic_ofstream.3 index 42b10617f..da7885226 100644 --- a/man/std::basic_ofstream::basic_ofstream.3 +++ b/man/std::basic_ofstream::basic_ofstream.3 @@ -1,68 +1,105 @@ -.TH std::basic_ofstream::basic_ofstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::basic_ofstream \- std::basic_ofstream::basic_ofstream + .SH Synopsis basic_ofstream(); \fB(1)\fP - explicit basic_ofstream( const char* filename, \fB(2)\fP - ios_base::openmode mode = ios_base::out ); - explicit basic_ofstream( const string& filename, - \fB(3)\fP \fI(since C++11)\fP - ios_base::openmode mode = ios_base::out ); - basic_ofstream( basic_ofstream&& other ); \fB(4)\fP \fI(since C++11)\fP - basic_ofstream( const basic_ofstream& rhs) = delete; \fB(5)\fP \fI(since C++11)\fP + explicit basic_ofstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::out ); + explicit basic_ofstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + explicit basic_ofstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + template< class FsPath > + + explicit basic_ofstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + basic_ofstream( basic_ofstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ofstream( const basic_ofstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP Constructs new file stream. 1) Default constructor: constructs a stream that is not associated with a file: default-constructs the std::basic_filebuf and constructs the base with the pointer to this default-constructed std::basic_filebuf member. - 2) First, performs the same steps as the default constructor, then asssociates the - stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out).. - If the open() call returns a null pointer, sets setstate(failbit). - 3) Same as basic_ofstream(filename.c_str(), mode). - 4) Move constructor. First, move-constructs the base class from other (which does + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out) + (see std::basic_filebuf::open for the details on the effects of that call). If the + open() call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ofstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP Note that despite the default mode being out, the effects are + identical to the effects of out | trunc as described in std::filebuf::open + 6) Move constructor. First, move-constructs the base class from other (which does not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer in the base class. - 5) The copy-constructor is deleted: this class is not copyable. + 7) The copy-constructor is deleted: this class is not copyable. .SH Parameters filename - the name of the file to be opened - specifies stream open mode. It is bitmask type, the following constants - are defined: - - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode other - another file stream to use as source .SH Example - + // Run this code #include - #include #include + #include + int main() { - std::basic_ofstream f0; + std::ofstream f0; std::ofstream f1("test.bin", std::ios::binary); std::string name = "example.txt"; std::ofstream f2(name); std::ofstream f3(std::move(f1)); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + .SH See also open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP set_rdbuf replaces the rdbuf without clearing its error state - \fI(protected member function)\fP + \fI(protected member function)\fP constructor constructs the object - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::basic_ofstream::close.3 b/man/std::basic_ofstream::close.3 index 35b2e5c27..10d285365 100644 --- a/man/std::basic_ofstream::close.3 +++ b/man/std::basic_ofstream::close.3 @@ -1,4 +1,7 @@ -.TH std::basic_ofstream::close 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::close \- std::basic_ofstream::close + .SH Synopsis void close(); @@ -15,6 +18,11 @@ \fI(none)\fP +.SH Notes + + This function is called by the destructor of basic_ofstream when the stream object + goes out of scope and is not usually invoked directly. + .SH Example This section is incomplete @@ -23,10 +31,11 @@ .SH See also is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ofstream::is_open.3 b/man/std::basic_ofstream::is_open.3 index f8394acfe..5a01690a2 100644 --- a/man/std::basic_ofstream::is_open.3 +++ b/man/std::basic_ofstream::is_open.3 @@ -1,7 +1,9 @@ -.TH std::basic_ofstream::is_open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::is_open \- std::basic_ofstream::is_open + .SH Synopsis - bool is_open(); \fI(until C++11)\fP - bool is_open() const; \fI(since C++11)\fP + bool is_open() const; Checks if the file stream has an associated file. @@ -13,20 +15,28 @@ .SH Return value - true if the file stream has an associated file, false otherwise + true if the file stream has an associated file, false otherwise. .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + .SH See also open opens a file and associates it with the stream - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ofstream::native_handle.3 b/man/std::basic_ofstream::native_handle.3 new file mode 100644 index 000000000..12d8567f1 --- /dev/null +++ b/man/std::basic_ofstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_ofstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::native_handle \- std::basic_ofstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::basic_ofstream::open.3 b/man/std::basic_ofstream::open.3 index 78afdb889..6a9ce65d0 100644 --- a/man/std::basic_ofstream::open.3 +++ b/man/std::basic_ofstream::open.3 @@ -1,34 +1,53 @@ -.TH std::basic_ofstream::open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::open \- std::basic_ofstream::open + .SH Synopsis - void open( const char *filename, - ios_base::openmode mode = ios_base::out ); - void open( const std::string &filename, - \fI(since C++11)\fP - ios_base::openmode mode = ios_base::out ); + void open( const char* filename, - Opens and associates the file with name filename with the file stream. + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::out ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::out ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + void open( const std::filesystem::path& filename, - Calls setstate(failbit) on failure. + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP - Calls clear() on success. \fI(since C++11)\fP + = std::ios_base::out ); - The first version effectively calls rdbuf()->open(filename, mode | ios_base::out). + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. - The second version effectively calls open(filename.c_str(), mode). + 1,2) Effectively calls rdbuf()->open(filename, mode | ios_base::out) (see + std::basic_filebuf::open for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). .SH Parameters filename - the name of the file to be opened - specifies stream open mode. It is bitmask type, the following constants + specifies stream open mode. It is a BitmaskType, the following constants are defined: - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Return value @@ -39,15 +58,27 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + + 1. ↑ The resolution of LWG issue #22 is overriden. + .SH See also is_open checks if the stream has an associated file - \fI(public member function)\fP + \fI(public member function)\fP close closes the associated file - \fI(public member function)\fP + \fI(public member function)\fP open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ofstream::operator=.3 b/man/std::basic_ofstream::operator=.3 index 3311d1259..ca3f0660e 100644 --- a/man/std::basic_ofstream::operator=.3 +++ b/man/std::basic_ofstream::operator=.3 @@ -1,13 +1,19 @@ -.TH std::basic_ofstream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::operator= \- std::basic_ofstream::operator= + .SH Synopsis basic_ofstream& operator=( basic_ofstream&& other ); \fI(since C++11)\fP - Moves the file stream. The source stream becomes of invalid state after the - operation. + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_ostream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. .SH Parameters - other - file stream to move. other becomes of invalid state after the operation. + other - file stream to move .SH Return value @@ -20,9 +26,12 @@ .SH See also - swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_ofstream::rdbuf.3 b/man/std::basic_ofstream::rdbuf.3 index 6c276cd31..e03acd59c 100644 --- a/man/std::basic_ofstream::rdbuf.3 +++ b/man/std::basic_ofstream::rdbuf.3 @@ -1,6 +1,9 @@ -.TH std::basic_ofstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::rdbuf \- std::basic_ofstream::rdbuf + .SH Synopsis - basic_filebuf* rdbuf() const; \fI(since C++11)\fP + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP Returns pointer to the underlying raw file device object. @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_ofstream::swap.3 b/man/std::basic_ofstream::swap.3 index f834ecfae..14bbf7c8d 100644 --- a/man/std::basic_ofstream::swap.3 +++ b/man/std::basic_ofstream::swap.3 @@ -1,4 +1,7 @@ -.TH std::basic_ofstream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ofstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::swap \- std::basic_ofstream::swap + .SH Synopsis void swap( basic_ofstream& other ); \fI(since C++11)\fP @@ -15,18 +18,64 @@ \fI(none)\fP +.SH Exceptions + + May throw implementation-defined exceptions. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" .SH See also operator= moves the file stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_filebuf objects - \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::basic_ospanstream.3 b/man/std::basic_ospanstream.3 new file mode 100644 index 000000000..0d83c693f --- /dev/null +++ b/man/std::basic_ospanstream.3 @@ -0,0 +1,279 @@ +.TH std::basic_ospanstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ospanstream \- std::basic_ospanstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits (since C++23) + > class basic_ospanstream + + : public basic_ostream + + The class template std::basic_ospanstream implements output operations on streams + based on fixed buffers. + + At the low level, the class essentially wraps a raw device implementation of + std::basic_spanbuf into a higher-level interface of std::basic_ostream. The complete + interface to unique std::basic_spanbuf members is provided. + + std-basic ospanstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ospanstream std::basic_ospanstream + std::wospanstream std::basic_ospanstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + + Data members + + Member object Definition + sb (private) The wrapped std::basic_spanbuf. + (exposition-only member object*) + +.SH Member functions + + constructor constructs the basic_ospanstream + (C++23) \fI(public member function)\fP + destructor destroys the basic_ospanstream + \fB[virtual]\fP (C++23) \fI(virtual public member function)\fP + operator= move-assignments the basic_ospanstream + (C++23) \fI(public member function)\fP + swap swaps two basic_ospanstream objects + (C++23) \fI(public member function)\fP + rdbuf obtains the address of the wrapped raw span device object + (C++23) \fI(public member function)\fP + Underlying buffer operations + span gets or sets the underlying buffer of the wrapped span device + (C++23) object + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ospanstream) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_spanstream 202106L (C++23) std::spanbuf, std::spanstream diff --git a/man/std::basic_ospanstream::basic_ospanstream.3 b/man/std::basic_ospanstream::basic_ospanstream.3 new file mode 100644 index 000000000..65eb36b87 --- /dev/null +++ b/man/std::basic_ospanstream::basic_ospanstream.3 @@ -0,0 +1,54 @@ +.TH std::basic_ospanstream::basic_ospanstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ospanstream::basic_ospanstream \- std::basic_ospanstream::basic_ospanstream + +.SH Synopsis + explicit basic_ospanstream( std::span s, + std::ios_base::openmode mode = \fB(1)\fP (since C++23) + std::ios_base::out ); + basic_ospanstream( basic_ospanstream&& rhs ); \fB(2)\fP (since C++23) + basic_ospanstream( const basic_ospanstream& ) = delete; \fB(3)\fP (since C++23) + + Constructs a new basic_ospanstream. + + 1) Uses the storage referenced by s as initial underlying buffer of the wrapped + std::basic_spanbuf device. The wrapped std::basic_spanbuf object is constructed as + basic_spanbuf(s, mode | std::ios_base::out). + 2) Move constructor. Move constructs the std::basic_ostream base subobject and the + wrapped std::basic_spanbuf from those of rhs, and then calls set_rdbuf with the + address of the wrapped std::basic_spanbuf in *this to install it. + 3) Copy constructor is deleted. basic_ospanstream is not copyable. + +.SH Parameters + + s - std::span referencing the storage to be use as initial underlying buffer of + stream + specifies stream open mode. Following constants and bit-wise OR between them + may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another basic_ospanstream to be moved from + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_spanbuf object + (C++23) \fI(public member function of std::basic_spanbuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ospanstream::operator=.3 b/man/std::basic_ospanstream::operator=.3 new file mode 100644 index 000000000..5b9f0a18e --- /dev/null +++ b/man/std::basic_ospanstream::operator=.3 @@ -0,0 +1,44 @@ +.TH std::basic_ospanstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ospanstream::operator= \- std::basic_ospanstream::operator= + +.SH Synopsis + basic_ospanstream& operator=( basic_ospanstream&& other ); \fB(1)\fP (since C++23) + basic_ospanstream& operator=( const basic_ospanstream& ) = delete; \fB(2)\fP (since C++23) + + 1) Move assigns the other to *this, effectively move-assigning both the + std::basic_ostream base class subobject and the wrapped std::basic_spanbuf. + 2) Copy assignment operator is deleted. basic_ospanstream is not copy assignable. + + Note that move assignment operator of the base class swaps all stream state + variables (except for rdbuf()) between *this and other. + + It is implementation-defined whether the std::basic_spanbuf wrapped in other still + holds an underlying buffer after the move assignment. + +.SH Parameters + + other - another stream to move from + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_spanbuf object + (C++23) \fI(public member function of std::basic_spanbuf)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ospanstream::rdbuf.3 b/man/std::basic_ospanstream::rdbuf.3 new file mode 100644 index 000000000..2bf08c821 --- /dev/null +++ b/man/std::basic_ospanstream::rdbuf.3 @@ -0,0 +1,29 @@ +.TH std::basic_ospanstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ospanstream::rdbuf \- std::basic_ospanstream::rdbuf + +.SH Synopsis + std::basic_spanbuf* rdbuf() const noexcept; (since C++23) + + Returns pointer to the wrapped raw device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the wrapped raw device object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ospanstream::span.3 b/man/std::basic_ospanstream::span.3 new file mode 100644 index 000000000..9dafee862 --- /dev/null +++ b/man/std::basic_ospanstream::span.3 @@ -0,0 +1,74 @@ +.TH std::basic_ospanstream::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ospanstream::span \- std::basic_ospanstream::span + +.SH Synopsis + std::span span() const noexcept; \fB(1)\fP (since C++23) + void span( std::span s ) noexcept; \fB(2)\fP (since C++23) + + 1) Gets a span referencing the written area if std::ios_base::out is set in the open + mode of the wrapped std::basic_spanbuf, or a span referencing the underlying buffer + otherwise. + 2) Makes the wrapped std::basic_spanbuf perform I/O on the buffer referenced by s. + +.SH Parameters + + s - std::span referencing the storage to be use as the new underlying buffer of + stream + +.SH Return value + + 1) A std::span referencing the underlying buffer or written area, depending on the + open mode of the wrapped std::basic_spanbuf. + 2) \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + char out_buf[16]; + std::ospanstream ost{std::span{out_buf}}; + ost << "C++" << ' ' << 23 << '\\0'; // note explicit null-termination + auto sp = ost.span(); + assert( + sp[0] == 'C' && sp[1] == '+' && sp[2] == '+' && + sp[3] == ' ' && sp[4] == '2' && sp[5] == '3' && + sp[6] == '\\0' + ); + std::cout << "sp.data(): [" << sp.data() << "]\\n"; + std::cout << "out_buf: [" << out_buf << "]\\n"; + // spanstream uses out_buf as internal storage, no allocations + assert(static_cast(out_buf) == sp.data()); + + const char in_buf[] = "X Y 42"; + std::ispanstream ist{std::span{in_buf}}; + assert(static_cast(in_buf) == ist.span().data()); + char c; + ist >> c; + assert(c == 'X'); + ist >> c; + assert(c == 'Y'); + int i; + ist >> i; + assert(i == 42); + ist >> i; // buffer is exhausted + assert(!ist); + } + +.SH Output: + + sp.data(): [C++ 23] + out_buf: [C++ 23] + +.SH See also + + span obtains or initializes an underlying buffer according to mode + (C++23) \fI(public member function of std::basic_spanbuf)\fP diff --git a/man/std::basic_ospanstream::swap.3 b/man/std::basic_ospanstream::swap.3 new file mode 100644 index 000000000..36f4b32bb --- /dev/null +++ b/man/std::basic_ospanstream::swap.3 @@ -0,0 +1,36 @@ +.TH std::basic_ospanstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ospanstream::swap \- std::basic_ospanstream::swap + +.SH Synopsis + void swap( basic_ospanstream& other ); (since C++23) + + Exchanges the state of the stream with those of other. + + This is done by calling std::basic_ostream::swap(other) and swapping + the wrapped std::basic_spanbuf objects (accessible through *rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_spanbuf objects + (C++23) \fI(public member function of std::basic_spanbuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_ostream.3 b/man/std::basic_ostream.3 index 8d55fb783..c912c374e 100644 --- a/man/std::basic_ostream.3 +++ b/man/std::basic_ostream.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream \- std::basic_ostream + .SH Synopsis Defined in header template< @@ -16,34 +19,34 @@ implementations, basic_ostream has no non-inherited data members. std-basic ostream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - ostream basic_ostream - wostream basic_ostream + Type Definition + std::ostream std::basic_ostream + std::wostream std::basic_ostream .SH Global objects - Six global basic_ostream objects are provided by the standard library. + Six global basic_ostream objects are provided by the standard library: Defined in header cout writes to the standard C output stream stdout - wcout (global object) + wcout (global object) cerr writes to the standard C error stream stderr, unbuffered - wcerr (global object) + wcerr (global object) clog writes to the standard C error stream stderr - wclog (global object) + wclog (global object) .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type @@ -51,39 +54,50 @@ .SH Member functions constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fB[virtual]\fP \fI(virtual public member function)\fP - operator= replaces the buffer object - \fI(C++11)\fP \fI(protected member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP .SH Formatted output operator<< inserts formatted data - \fI(public member function)\fP + \fI(public member function)\fP .SH Unformatted output put inserts a character - \fI(public member function)\fP + \fI(public member function)\fP write inserts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function)\fP + \fI(public member function)\fP seekp sets the output position indicator - \fI(public member function)\fP + \fI(public member function)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function)\fP + \fI(public member function)\fP swap swaps stream objects, except for the associated buffer - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class)\fP + \fI(public member class)\fP .SH Non-member functions - operator<<(std::basic_ostream) inserts character data - \fI(function)\fP + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + println(std::ostream) outputs formatted representation of the arguments + (C++23) with appended '\\n' + \fI(function template)\fP + vprint_unicode(std::ostream) performs Unicode aware output using type-erased + (C++23) argument representation + \fI(function)\fP + vprint_nonunicode(std::ostream) outputs character data using type-erased argument + (C++23) representation + \fI(function)\fP Inherited from std::basic_ios @@ -96,45 +110,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -142,40 +156,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -183,76 +197,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::basic_ostream::basic_ostream.3 b/man/std::basic_ostream::basic_ostream.3 index d20949928..2cd517ab4 100644 --- a/man/std::basic_ostream::basic_ostream.3 +++ b/man/std::basic_ostream::basic_ostream.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostream::basic_ostream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::basic_ostream \- std::basic_ostream::basic_ostream + .SH Synopsis explicit basic_ostream( std::basic_streambuf* sb ); \fB(1)\fP protected: \fB(2)\fP \fI(since C++11)\fP @@ -8,10 +11,8 @@ 1) Constructs the basic_ostream object, assigning initial values to the base class by calling basic_ios::init(sb). - 2) The copy constructor is protected, and is deleted. Output streams are not copyable. - 3) The move constructor uses basic_ios::move(rhs) to move all basic_ios members, except for the rdbuf(), from rhs into *this. This move constructor is protected: it is called by the move constructors of movable output @@ -23,29 +24,38 @@ sb - streambuffer to use as output sequence rhs - basic_ostream to initialize from +.SH Notes + + Because basic_ios::init(sb) sets badbit when sb is a null pointer, and because + basic_ostream::sentry does nothing if the stream is already in a failed state, + writing to a stream constructed from a null pointer sb is a no-op. + .SH Example - + // Run this code + #include #include #include - #include - + int main() { // ERROR: copy ctor is deleted // std::ostream myout(std::cout); - + // OK: shares buffer with cout std::ostream myout(std::cout.rdbuf()); - + // ERROR: move constructor is protected // std::ostream s2(std::move(std::ostringstream() << 7.1)); - + // OK: move ctor called through the derived class - std::ostringstream s2(std::move(std::ostringstream() << 7.1)); + std::ostringstream s2(std::ostringstream() << 7.1); myout << s2.str() << '\\n'; + + std::ostream dev_null{nullptr}; // see Notes above + dev_null << "no-op"; } .SH Output: diff --git a/man/std::basic_ostream::flush.3 b/man/std::basic_ostream::flush.3 index f4a45e610..642eeceeb 100644 --- a/man/std::basic_ostream::flush.3 +++ b/man/std::basic_ostream::flush.3 @@ -1,14 +1,17 @@ -.TH std::basic_ostream::flush 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::flush 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::flush \- std::basic_ostream::flush + .SH Synopsis basic_ostream& flush(); - Writes uncommitted changes to the underlying output sequence. + Writes uncommitted changes to the underlying output sequence. Behaves as an + UnformattedOutputFunction. - If rdbuf() is a null pointer, does nothing + If rdbuf() is a null pointer, the sentry object is not constructed. - Otherwise, behaves as an UnformattedOutputFunction \fI(since C++11)\fP. After constructing - and checking the sentry object, calls rdbuf()->pubsync(). If the call returns -1, - calls setstate(badbit). + Otherwise, after constructing and checking the sentry object, calls + rdbuf()->pubsync(). If the call returns -1, calls setstate(badbit). .SH Parameters @@ -20,42 +23,69 @@ .SH Exceptions - May throw std::ios_base::failure if exceptions()&badbit!=0. + May throw std::ios_base::failure if (exceptions() & badbit) != 0. .SH Example - + // Run this code - #include - #include #include + #include + #include + + using namespace std::chrono_literals; + void f() { - std::cout << "Output from thread..."; - std::this_thread::sleep_for(std::chrono::seconds(2)); - std::cout << "...thread calls flush()\\n"; - std::cout.flush(); + std::cout << "Output from thread... "; + for (int i{1}; i != 10; ++i) + { + std::this_thread::sleep_for(250ms); + std::cout << i << ' '; + + // output three numbers at once; + // the effect is observable only in real-time + if (0 == (i % 3)) + std::cout.flush(); + } + std::cout << std::endl; // flushes as well } - + int main() { - std::thread t1(f); - std::this_thread::sleep_for(std::chrono::seconds(1)); + std::thread tr{f}; + std::this_thread::sleep_for(150ms); std::clog << "Output from main\\n"; - t1.join(); + tr.join(); } .SH Output: Output from main - Output from thread.....thread calls flush() + Output from thread... 1 2 3 4 5 6 7 8 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + flush() did not behave as an + LWG 581 C++98 UnformattedOutputFunction behaves as an + because of the resolution of LWG issue UnformattedOutputFunction + 60 .SH See also - sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP - flush flushes the output stream - \fI(function template)\fP - endl outputs '\\n' and flushes the output stream - \fI(function template)\fP + pubsync invokes sync() + \fI(public member function of std::basic_streambuf)\fP + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + flush flushes the output stream + \fI(function template)\fP + endl outputs '\\n' and flushes the output stream + \fI(function template)\fP + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_ostream::operator<<.3 b/man/std::basic_ostream::operator<<.3 index cbfc80ce4..7a68deebf 100644 --- a/man/std::basic_ostream::operator<<.3 +++ b/man/std::basic_ostream::operator<<.3 @@ -1,117 +1,208 @@ -.TH std::basic_ostream::operator<< 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::operator<< 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::operator<< \- std::basic_ostream::operator<< + .SH Synopsis - basic_ostream& operator<<( short value ); \fB(1)\fP - basic_ostream& operator<<( unsigned short value ); - basic_ostream& operator<<( int value ); \fB(2)\fP - basic_ostream& operator<<( unsigned int value ); - basic_ostream& operator<<( long value ); \fB(3)\fP - basic_ostream& operator<<( unsigned long value ); - basic_ostream& operator<<( long long value ); \fB(4)\fP \fI(since C++11)\fP - basic_ostream& operator<<( unsigned long long value ); - basic_ostream& operator<<( float value ); - - basic_ostream& operator<<( double value ); \fB(5)\fP - - basic_ostream& operator<<( long double value ); - basic_ostream& operator<<( bool value ); \fB(6)\fP - basic_ostream& operator<<( const void* value ); \fB(7)\fP - basic_ostream& operator<<( std::basic_streambuf* \fB(8)\fP - sb); - basic_ostream& operator<<( std::ios_base& (*func)(std::ios_base&) - ); - basic_ostream& operator<<( std::basic_ios& \fB(9)\fP - (*func)(std::basic_ios&) ); - basic_ostream& operator<<( std::basic_ostream& - (*func)(std::basic_ostream&) ); + basic_ostream& operator<<( bool value ); \fB(1)\fP + basic_ostream& operator<<( long value ); \fB(2)\fP + basic_ostream& operator<<( unsigned long value ); \fB(3)\fP + basic_ostream& operator<<( long long value ); \fB(4)\fP \fI(since C++11)\fP + basic_ostream& operator<<( unsigned long long value ); \fB(5)\fP \fI(since C++11)\fP + basic_ostream& operator<<( double value ); \fB(6)\fP + basic_ostream& operator<<( long double value ); \fB(7)\fP + basic_ostream& operator<<( const void* value ); \fB(8)\fP + basic_ostream& operator<<( const volatile void* value ); \fB(9)\fP (since C++23) + basic_ostream& operator<<( std::nullptr_t ); \fB(10)\fP \fI(since C++17)\fP + basic_ostream& operator<<( short value ); \fB(11)\fP + basic_ostream& operator<<( int value ); \fB(12)\fP + basic_ostream& operator<<( unsigned short value ); \fB(13)\fP + basic_ostream& operator<<( unsigned int value ); \fB(14)\fP + basic_ostream& operator<<( float value ); \fB(15)\fP + basic_ostream& operator<<( /* extended-floating-point-type */ \fB(16)\fP (since C++23) + value ); + basic_ostream& operator<<( std::basic_streambuf* \fB(17)\fP + sb ); + basic_ostream& operator<<( \fB(18)\fP + std::ios_base& (*func)(std::ios_base&) ); + basic_ostream& operator<<( + std::basic_ios& (*func)(std::basic_ios&) ); + basic_ostream& operator<<( + + std::basic_ostream& (*func) \fB(20)\fP + + (std::basic_ostream&) ); Inserts data into the stream. - 1-2) Behaves as an FormattedOutputFunction. After constructing and checking the - sentry object, if value is short or int, then casts it to unsigned short or unsigned - int if ios_base::flags() & ios_base::basefield is ios_base::oct or ios_base::hex. - After that, casts to long in any case and outputs as in \fB(3)\fP. If value is unsigned - short or unsigned int, casts to unsigned long and outputs as in \fB(3)\fP. - 3-7) Behaves as an FormattedOutputFunction. After constructing and checking the - sentry object, inserts an integer, floating point, boolean or generic pointer value - by calling num_put::put(). If the end of file condition was encountered during - output (put().failed() == true), sets ios::badbit. - 8) Behaves as an UnformattedOutputFunction. After constructing and checking the - sentry object, checks if sb is a null pointer. If it is, executes setstate(badbit) - and exits. Otherwise, extracts characters from the input sequence controlled by sb - and inserts them into *this until one of the following conditions are met: + 1-8) Inserts value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a value by calling std::num_put::put(). If the end of + file condition was encountered during output (put().failed() == true), sets badbit. + 9) Equivalent to return operator<<(const_cast(p));. + 10) Equivalent to return *this << s;, where s is an implementation-defined + null-terminated character type string. + 11) Inserts a value from short value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is + * static_cast(static_cast(value)), if flags() & + std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or + * static_cast(value) otheriwse. + 12) Inserts a value from int value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is + * static_cast(static_cast(value)), if flags() & + std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or + * static_cast(value) otheriwse. + 13,14) Inserts a value from unsigned short or unsigned int value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts static_cast(value) as in \fB(3)\fP. + 15) Inserts a value from float value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts static_cast(value) as in \fB(6)\fP. + 16) Inserts a value from value. The library provides overloads for all + cv-unqualified extended floating-point types as the type of the parameter value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, checks the floating-point conversion rank of /* + extended-floating-point-type */: + * If the rank is less than or equal to that of double, inserts + static_cast(value) as in \fB(6)\fP. + * Otherwise, if the rank is less than or equal to that of long double, inserts + static_cast(value) as in \fB(7)\fP. + * Otherwise, an invocation of this overload is conditionally supported with + implementation-defined semantics. + 17) This function behaves as an UnformattedOutputFunction. After constructing and + checking the sentry object, checks if sb is a null pointer. If it is, executes + setstate(badbit) and exits. Otherwise, extracts characters from the input sequence + controlled by sb and inserts them into *this until one of the following conditions + are met: * end-of-file occurs on the input sequence; * inserting in the output sequence fails (in which case the character to be inserted is not extracted); * an exception occurs (in which case the exception is caught). - - If no characters were inserted, executes setstate(badbit). If an exception was - thrown while extracting, sets failbit - 9) Calls func(*this);. This overload is used to implement output I/O manipulators - such as std::endl. + If no characters were inserted, executes setstate(failbit). If an exception was + thrown while extracting, sets failbit and, if failbit is set in exceptions(), + rethrows the exception. + 18-20) Calls func(*this). These overloads are used to implement output I/O + manipulators such as std::endl. .SH Parameters value - integer, floating-point, boolean, or pointer value to insert func - function to call - sb - pointer to the streambuffer to read the data from + sb - pointer to the stream buffer to read the data from .SH Return value - *this + 1-19) *this + 20) func(*this) .SH Notes - There are no overload for pointers to volatile or function pointers (other than the - ones with signatures accepted by the \fB(9)\fP overload). Attempting to output such - objects invokes implicit conversion to bool, and, for any non-null pointer value, - the value 1 is printed (unless boolalpha was set). + There are no overloads for pointers to non-static members + , pointers to volatiles, + (until C++23) or function pointers (other than the ones with signatures accepted by + the (18-20) overloads). + + * Attempting to output such objects invokes implicit conversion to bool, and, for + any non-null pointer value, the value 1 is printed (unless boolalpha was set, in + which case true is printed). + + Character and character string arguments (e.g., of type char or const char*) are + handled by the non-member overloads of operator<<. + + * Attempting to output a character using the member function call syntax (e.g., + std::cout.operator<<('c');) will call one of the overloads in (2-5) or (11-14) + and output the numerical value. + * Attempting to output a character string using the member function call syntax + will call overload \fB(8)\fP and print the pointer value instead. .SH Example - + // Run this code - #include #include + #include #include + + int fun() { return 42; } + int main() { std::istringstream input(" \\"Some text.\\" "); - volatile int n = 42; double f = 3.14; - bool b = true;; - std::cout << n // int overload - << ' ' // non-member overload - << std::boolalpha << b // bool overload - << " " // non-member overload - << std::fixed << f // double overload - << input.rdbuf() // streambuf overload - << &n // bool overload - << std::endl; // function overload + bool b = true; + + std::cout + << fun() // int overload (12) + << ' ' // non-member overload + << std::boolalpha // function overload (18) + << b // bool overload (1) + << " " // non-member overload + << std::fixed // function overload (18) again + << f // double overload (6) + << input.rdbuf() // streambuf overload + << fun // bool overload (1): there's no overload for int(*)() + << std::endl; // function overload (18) again + + int x = 0; + int* p1 = &x; + volatile int* p2 = &x; + std::cout + << "p1: " << p1 << '\\n' // `const void*` overload, prints address + << "p2: " << p2 << '\\n'; // before C++23 (P1147): bool overload :), because + // operator<<(const void*) is not a match, as it discards the `volatile` + // qualifier. To fix this, C++23 adds `const volatile void*` overload (9), + // that prints the address as expected. } -.SH Output: +.SH Possible output: 42 true 3.140000 "Some text." true + p1: 0x7ffcea766600 + p2: 0x7ffcea766600 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overloads (1-8,11-15) delegated the + insertion to they are converted + LWG 117 C++98 num_put::put, but it does not have before being passed + overloads for short, to num_put::put + unsigned short, int, unsigned int, and + float + overload \fB(17)\fP behaved as a + LWG 567 C++98 FormattedOutputFunction it behaves as an + because of the resolution of LWG issue UnformattedOutputFunction + 60 .SH See also - operator<<(std::basic_ostream) inserts character data - \fI(function)\fP - operator<< performs stream I/O of strings + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + operator<< performs stream input and output on strings operator>> \fI(function template)\fP + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP operator<< performs stream input and output of bitsets - operator>> \fI(function)\fP + operator>> \fI(function template)\fP operator<< serializes and deserializes a complex number operator>> \fI(function template)\fP operator<< performs stream input and output on pseudo-random operator>> number engine - \fI(function)\fP + \fI(C++11)\fP \fI(function template)\fP operator<< performs stream input and output on pseudo-random operator>> number distribution - \fI(function)\fP + \fI(C++11)\fP \fI(function template)\fP put inserts a character - \fI(public member function)\fP + \fI(public member function)\fP write inserts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP + to_chars converts an integer or floating-point value to a + \fI(C++17)\fP character sequence + \fI(function)\fP diff --git a/man/std::basic_ostream::operator=.3 b/man/std::basic_ostream::operator=.3 index aaf1c5bad..051bc3209 100644 --- a/man/std::basic_ostream::operator=.3 +++ b/man/std::basic_ostream::operator=.3 @@ -1,13 +1,15 @@ -.TH std::basic_ostream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::operator= \- std::basic_ostream::operator= + .SH Synopsis protected: \fB(1)\fP - basic_istream& operator=( const basic_ostream& rhs ) = delete; + basic_ostream& operator=( const basic_ostream& rhs ) = delete; protected: \fB(2)\fP \fI(since C++11)\fP basic_ostream& operator=( basic_ostream&& rhs ); 1) The copy assignment operator is protected, and is deleted. Output streams are not CopyAssignable. - 2) The move assignment operator exchanges all data members of the base class, except for rdbuf(), with rhs, as if by calling swap(*rhs). This move assignment operator is protected: it is only called by the move assignment operators of the derived movable @@ -20,17 +22,18 @@ .SH Example - + // Run this code + #include #include #include - #include + int main() { std::ostringstream s; - // std::cout = s; // ERROR: copy assignment operator is deleted - // std::cout = std::move(s); // ERROR: move assignment operator is protected + // std::cout = s; // ERROR: copy assignment operator is deleted + // std::cout = std::move(s); // ERROR: move assignment operator is protected s = std::move(std::ostringstream() << 42); // OK, moved through derived std::cout << s.str() << '\\n'; } @@ -38,3 +41,14 @@ .SH Output: 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the parameter type of overload \fB(1)\fP was + LWG 2067 C++11 basic_ostream& 1. added const + 2. the parameter type of overload \fB(2)\fP was const 2. removed const + basic_ostream&& diff --git a/man/std::basic_ostream::put.3 b/man/std::basic_ostream::put.3 index b8ebc8e82..5a34117a4 100644 --- a/man/std::basic_ostream::put.3 +++ b/man/std::basic_ostream::put.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostream::put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::put \- std::basic_ostream::put + .SH Synopsis basic_ostream& put( char_type ch ); @@ -18,24 +21,24 @@ .SH Notes This function is not overloaded for the types signed char or unsigned char, unlike - the formatted operator<< + the formatted operator<<. Unlike formatted output functions, this function does not set the failbit if the output fails. .SH Example - + // Run this code #include #include - + int main() { std::cout.put('a'); // normal usage std::cout.put('\\n'); - + std::ofstream s("/does/not/exist/"); s.clear(); // pretend the stream is good std::cout << "Unformatted output: "; @@ -57,7 +60,7 @@ .SH See also - operator<<(std::basic_ostream) inserts character data - \fI(function)\fP + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP write inserts blocks of characters - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_ostream::seekp.3 b/man/std::basic_ostream::seekp.3 index 76a201440..19e584dc9 100644 --- a/man/std::basic_ostream::seekp.3 +++ b/man/std::basic_ostream::seekp.3 @@ -1,24 +1,28 @@ -.TH std::basic_ostream::seekp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::seekp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::seekp \- std::basic_ostream::seekp + .SH Synopsis - basic_ostream& seekp( pos_type pos ); \fB(1)\fP - basic_ostream& seekp( off_type off, std::ios_base::seekdir dir); \fB(2)\fP + basic_ostream& seekp( pos_type pos ); \fB(1)\fP + basic_ostream& seekp( off_type off, std::ios_base::seekdir dir ); \fB(2)\fP Sets the output position indicator of the current associated streambuf object. Behaves as UnformattedOutputFunction (except without actually \fI(since C++11)\fP performing output). After constructing and checking the sentry object, - 1) sets the output position indicator to absolute (relative to the beginning of the - file) value pos by calling rdbuf()->pubseekpos(pos, std::ios_base::out). If the call - returns (pos_type)-1, executes setstate(failbit). - - 2) sets the output position indicator to offset off relative to dir by calling - rdbuf()->pubseekoff(off, dir, std::ios_base::out). Does not report errors. + 1) if fail() != true, sets the output position indicator to absolute (relative to + the beginning of the file) value pos by calling rdbuf()->pubseekpos(pos, + std::ios_base::out). In case of failure, calls setstate(std::ios_base::failbit). + 2) if fail() != true, sets the output position indicator to offset off relative to + dir by calling rdbuf()->pubseekoff(off, dir, std::ios_base::out). In case of + failure, calls setstate(std::ios_base::failbit). .SH Parameters - pos - absolute position to set the output position indicator to. - off - relative position to set the output position indicator to. + pos - absolute position to set the output position indicator to + off - relative position (positive or negative) to set the output position indicator + to defines base position to apply the relative offset to. It can be one of the following constants: @@ -33,19 +37,17 @@ .SH Exceptions - 1) May throw std::ios_base::failure in case of failure, if exceptions() & failbit != - 0. - - 2) Does not throw unless rdbuf()->pubseekoff() throws + 1,2) May throw std::ios_base::failure in case of failure, if exceptions() & failbit + != 0. .SH Example - + // Run this code - #include #include - + #include + int main() { std::ostringstream os("hello, world"); @@ -62,11 +64,25 @@ Hello, World! + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 129 C++98 there was no way to indicate a failure sets failbit on failure + LWG 136 C++98 seekp could set the input stream only sets the output + stream + LWG 537 C++98 1. the type of pos was pos_type& 1. corrected to pos_type + 2. the type of off was off_type& 2. corrected to off_type + LWG 2341 C++98 the resolution of LWG issue 129 for restored + overload \fB(2)\fP was removed + .SH See also tellp returns the output position indicator - \fI(public member function)\fP + \fI(public member function)\fP tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_ostream::sentry.3 b/man/std::basic_ostream::sentry.3 index 03ad3d52a..6001be802 100644 --- a/man/std::basic_ostream::sentry.3 +++ b/man/std::basic_ostream::sentry.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostream::sentry 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::sentry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::sentry \- std::basic_ostream::sentry + .SH Synopsis class sentry; @@ -14,18 +17,18 @@ .SH Member functions constructor constructs the sentry object. All the preparation tasks are done here - \fI(public member function)\fP + \fI(public member function)\fP finalizes the stream object after formatted output or after exception, destructor if necessary \fI(public member function)\fP operator= the assignment operator is deleted \fI(public member function)\fP operator bool checks if the preparation of the stream object was successful - \fI(public member function)\fP + \fI(public member function)\fP - std::basic_ostream::sentry::sentry +std::basic_ostream::sentry::sentry - explicit sentry( std::basic_ostream& os ); + explicit sentry( std::basic_ostream& os ); Prepares the stream for formatted output. @@ -34,7 +37,7 @@ preparation, the constructor may call setstate(failbit) (which may throw std::ios_base::failure). - If after preparation is completed, is.good() == true, then any subsequent calls to + If after preparation is completed, os.good() == true, then any subsequent calls to operator bool will return true. .SH Parameters @@ -45,7 +48,7 @@ std::ios_base::failure if the end of file condition occurs. - std::basic_ostream::sentry::~sentry +std::basic_ostream::sentry::~sentry ~sentry(); @@ -53,7 +56,7 @@ is true, calls os.rdbuf()->pubsync(). If that function returns -1, sets badbit in os.rdstate() without propagating an exception. - std::basic_ostream::sentry::operator bool +std::basic_ostream::sentry::operator bool explicit operator bool() const; @@ -69,29 +72,28 @@ .SH Example - + // Run this code #include #include - + struct Foo { char n[6]; }; - - std::ostream& operator<<(std::ostream& is, Foo& f) + + std::ostream& operator<<(std::ostream& os, Foo& f) { - std::ostream::sentry s(is); - if (s) { - is.write(f.n, 5); - } - return is; + std::ostream::sentry s(os); + if (s) + os.write(f.n, 5); + return os; } - + int main() { - Foo f = { "abcde" }; + Foo f = {"abcde"}; std::cout << f << '\\n'; } @@ -99,7 +101,24 @@ abcde + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 397 C++98 the destructor might call os.flush(), which the exception is not + may throw exceptions propagated + LWG 442 C++98 operator bool was not declared const (it is added const + const in the synopsis) + if os sets unitbuf, the destructor would + call os.flush(), which calls + LWG 835 C++98 is an UnformattedOutputFunction and creates os.rdbuf()->pubsync() + another sentry object in this case instead + (whose destructor then creates another + sentry object and so on) + .SH See also operator<< inserts formatted data - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_ostream::swap.3 b/man/std::basic_ostream::swap.3 index d122e9089..2b0d09268 100644 --- a/man/std::basic_ostream::swap.3 +++ b/man/std::basic_ostream::swap.3 @@ -1,7 +1,10 @@ -.TH std::basic_ostream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::swap \- std::basic_ostream::swap + .SH Synopsis - protected: \fI(since C++11)\fP - void swap(basic_ostream& rhs); + protected: \fI(since C++11)\fP + void swap( basic_ostream& rhs ); Calls basic_ios::swap(rhs) to swap all data members of the base class, except for rdbuf(), between *this and rhs. This swap function is protected: it is called by the @@ -15,22 +18,23 @@ .SH Example - + // Run this code - #include #include + #include #include + int main() { std::ostringstream s1("hello"); std::ostringstream s2("bye"); - + s1.swap(s2); // OK, ostringstream has a public swap() std::swap(s1, s2); // OK, calls s1.swap(s2) - + // std::cout.swap(s2); // ERROR: swap is a protected member - + std::cout << s1.str() << '\\n'; } diff --git a/man/std::basic_ostream::tellp.3 b/man/std::basic_ostream::tellp.3 index 0c4c51141..73acfb3df 100644 --- a/man/std::basic_ostream::tellp.3 +++ b/man/std::basic_ostream::tellp.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostream::tellp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::tellp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::tellp \- std::basic_ostream::tellp + .SH Synopsis pos_type tellp(); @@ -20,7 +23,7 @@ .SH Example - + // Run this code #include @@ -48,8 +51,8 @@ .SH See also seekp sets the output position indicator - \fI(public member function)\fP + \fI(public member function)\fP tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_ostream::write.3 b/man/std::basic_ostream::write.3 index ab9ff5faf..d4244b94e 100644 --- a/man/std::basic_ostream::write.3 +++ b/man/std::basic_ostream::write.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostream::write 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::write 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::write \- std::basic_ostream::write + .SH Synopsis basic_ostream& write( const char_type* s, std::streamsize count ); @@ -9,7 +12,7 @@ * exactly count characters are inserted * inserting into the output sequence fails (in which case setstate(badbit) is - called) + called). .SH Parameters @@ -20,43 +23,53 @@ *this +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + .SH Notes This function is not overloaded for the types signed char or unsigned char, unlike - the formatted operator<< + the formatted operator<<. Also, unlike the formatted output functions, this function does not set the failbit on failure. -.SH Exceptions - - If an exception occurs during output and exceptions() & badbit != 0, rethrows that - exception. - - If output fails and exceptions() & badbit != 0, throws ios_base::failure. + When using a non-converting locale (the default locale is non-converting), the + overrider of this function in std::basic_ofstream may be optimized for zero-copy + bulk I/O (by means of overriding std::streambuf::xsputn). .SH Example This function may be used to output object representations, i.e. binary output - + // Run this code #include - + int main() { int n = 0x41424344; std::cout.write(reinterpret_cast(&n), sizeof n) << '\\n'; + + char c[] = "This is sample text."; + std::cout.write(c, 4).write("!\\n", 2); } -.SH Output: +.SH Possible output: DCBA + This! .SH See also - operator<<(std::basic_ostream) inserts character data - \fI(function)\fP + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP put inserts a character - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_ostream::~basic_ostream.3 b/man/std::basic_ostream::~basic_ostream.3 index b1265831c..56d90cf52 100644 --- a/man/std::basic_ostream::~basic_ostream.3 +++ b/man/std::basic_ostream::~basic_ostream.3 @@ -1,24 +1,29 @@ -.TH std::basic_ostream::~basic_ostream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostream::~basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::~basic_ostream \- std::basic_ostream::~basic_ostream + .SH Synopsis virtual ~basic_ostream(); Destroys the basic_ostream object. This destructor does not perform any operation on the underlying streambuffer (rdbuf()): the destructors of the derived output streams such as std::basic_ofstream and std::basic_ostringstream are responsible for calling - the destructors of the streambuffers. + the destructors of the stream buffers. .SH Example - + // Run this code - #include #include + #include + void add_words(std::streambuf* p) { std::ostream buf(p); // buf shares the buffer with s buf << " is the answer"; } // calls the destructor of buf. p remains unaffected + int main() { std::ostringstream s; diff --git a/man/std::basic_ostringstream.3 b/man/std::basic_ostringstream.3 index ea7311455..476ad8c39 100644 --- a/man/std::basic_ostringstream.3 +++ b/man/std::basic_ostringstream.3 @@ -1,92 +1,101 @@ -.TH std::basic_ostringstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream \- std::basic_ostringstream + .SH Synopsis Defined in header - template< - - class CharT, \fI(until C++11)\fP - class Traits = std::char_traits - - > class basic_ostringstream; template< class CharT, - class Traits = std::char_traits, \fI(since C++11)\fP + class Traits = std::char_traits, class Allocator = std::allocator + > class basic_ostringstream + + : public basic_ostream; - > class basic_ostringstream; + The class template std::basic_ostringstream implements output operations on string + based streams. It effectively stores an instance of std::basic_string and performs + output operations to it. - The class template std::basic_ostringstream implements output operations on memory - (std::basic_string) based streams. It essentially wraps a raw string device - implementation (std::basic_stringbuf) into a higher-level interface - (std::basic_ostream). The complete interface to unique std::basic_stringbuf members - is provided. + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_ostream. The + complete interface to unique std::basic_stringbuf members is provided. std-basic ostringstream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - ostringstream basic_ostringstream - wostringstream basic_ostringstream + Type Definition + std::ostringstream std::basic_ostringstream + std::wostringstream std::basic_ostringstream .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type - allocator_type Allocator \fI(since C++11)\fP + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) .SH Member functions constructor constructs the string stream - \fI(public member function)\fP + \fI(public member function)\fP operator= moves the string stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP rdbuf returns the underlying raw string device object - \fI(public member function)\fP + \fI(public member function)\fP .SH String operations str gets or sets the contents of underlying string device object - \fI(public member function)\fP + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP .SH Non-member functions - std::swap(std::basic_istringstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + std::swap(std::basic_ostringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -99,45 +108,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -145,40 +154,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -186,76 +195,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::basic_ostringstream::basic_ostringstream.3 b/man/std::basic_ostringstream::basic_ostringstream.3 index c36fcc0ce..17a9cb9e1 100644 --- a/man/std::basic_ostringstream::basic_ostringstream.3 +++ b/man/std::basic_ostringstream::basic_ostringstream.3 @@ -1,46 +1,144 @@ -.TH std::basic_ostringstream::basic_ostringstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostringstream::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::basic_ostringstream \- std::basic_ostringstream::basic_ostringstream + .SH Synopsis - explicit basic_ostringstream( ios_base::openmode mode = \fB(1)\fP - ios_base::out ); - explicit basic_ostringstream( const - std::basic_string& str, \fB(2)\fP - ios_base::openmode mode = ios_base::out ); - basic_ostringstream( basic_ostringstream&& other ); \fB(3)\fP \fI(since C++11)\fP + explicit basic_ostringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_ostringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_ostringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_ostringstream(std::ios_base::out) {} + explicit basic_ostringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + explicit basic_ostringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + basic_ostringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_ostringstream(str, std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_ostringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + explicit basic_ostringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + basic_ostringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_ostringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_ostringstream( basic_ostringstream&& other ); \fB(12)\fP \fI(since C++11)\fP Constructs new string stream. - 1) Constructs new underlying string device. The underlying basic_stringbuf object is - constructed as basic_stringbuf(mode | ios_base::out). + Given + + * base_type as std::basic_ostream, and + * buf_type as std::basic_stringbuf, - 2) Uses a copy of str as initial contents of the underlying string device. The - underlying basic_stringbuf object is constructed as - basic_stringbuf(str, mode | ios_base::out). + the std::basic_ostream base and the exposition-only data member sb are initialized + as follows. - 3) Move constructor. Constructs the file stream with the state of other using move - semantics. + Over std::basic_ostream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::out) + \fB(2)\fP buf_type(std::ios_base::out) + \fB(3)\fP buf_type(str, mode | + std::ios_base::out) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::out) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::out, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::out, a) + \fB(7)\fP buf_type(str, std::ios_base::out, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::out) + \fB(9)\fP {t, mode | std::ios_base::out, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::out, a} + \fB(11)\fP {t, std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_ostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. .SH Parameters str - string to use as initial contents of the string stream - specifies stream open mode. It is bitmask type, the following constants are + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are defined: - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode other - another string stream to use as source +.SH Notes + + Construction of one-off basic_ostringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + .SH Example - + // Run this code #include #include + int main() { // default constructor (input/output stream) @@ -49,12 +147,12 @@ int n = 0; buf1 >> n; std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; - + // input stream std::istringstream inbuf("-10"); inbuf >> n; std::cout << "n = " << n << '\\n'; - + // output stream in append mode \fI(C++11)\fP std::ostringstream buf2("test", std::ios_base::ate); buf2 << '1'; @@ -67,9 +165,18 @@ n = -10 test1 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + .SH See also str gets or sets the contents of underlying string device object - \fI(public member function)\fP - constructor constructs a basic_stringbuf object - \fI(public member function of std::basic_stringbuf)\fP + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::basic_ostringstream::operator=.3 b/man/std::basic_ostringstream::operator=.3 index db9383241..8c4a77624 100644 --- a/man/std::basic_ostringstream::operator=.3 +++ b/man/std::basic_ostringstream::operator=.3 @@ -1,13 +1,19 @@ -.TH std::basic_ostringstream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::operator= \- std::basic_ostringstream::operator= + .SH Synopsis basic_ostringstream& operator=( basic_ostringstream&& other ); \fI(since C++11)\fP - Moves the string stream. The source stream becomes of invalid state after the - operation. + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_ostream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. .SH Parameters - other - string stream to move. other becomes of invalid state after the operation. + other - string stream to move from .SH Return value @@ -20,9 +26,13 @@ .SH See also - swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP -.SH Category: + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Category: * Todo no example diff --git a/man/std::basic_ostringstream::rdbuf.3 b/man/std::basic_ostringstream::rdbuf.3 index 869ae699e..c81e2a3b3 100644 --- a/man/std::basic_ostringstream::rdbuf.3 +++ b/man/std::basic_ostringstream::rdbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_ostringstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::rdbuf \- std::basic_ostringstream::rdbuf + .SH Synopsis std::basic_stringbuf* rdbuf() const; @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_ostringstream::str.3 b/man/std::basic_ostringstream::str.3 index 903bfb655..dcc9f6094 100644 --- a/man/std::basic_ostringstream::str.3 +++ b/man/std::basic_ostringstream::str.3 @@ -1,24 +1,48 @@ -.TH std::basic_ostringstream::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::str \- std::basic_ostringstream::str + .SH Synopsis - std::basic_string str() const; \fB(1)\fP - void str(const std::basic_string& new_str); \fB(2)\fP + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); Manages the contents of the underlying string object. - 1) Returns a copy of the underlying string as if by calling rdbuf()->str(). - - 2) Replaces the contents of the underlying string as if by calling - rdbuf()->str(new_str). + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. .SH Parameters - new_str - new contents of the underlying string + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string .SH Return value - 1) a copy of the underlying string object. - - 2) \fI(none)\fP + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP .SH Notes @@ -27,41 +51,49 @@ of str() (for example in auto *ptr = out.str().c_str();) results in a dangling pointer. + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + .SH Example - + // Run this code - #include #include + #include + int main() { int n; - - std::istringstream in; // could also use in("1 2") + + std::istringstream in; // could also use in("1 2") in.str("1 2"); in >> n; - std::cout << "after reading the first int from \\"1 2\\", the int is " + std::cout << "After reading the first int from \\"1 2\\", the int is " << n << ", str() = \\"" << in.str() << "\\"\\n"; - + std::ostringstream out("1 2"); out << 3; - std::cout << "after writing the int '3' to output stream \\"1 2\\"" + std::cout << "After writing the int '3' to output stream \\"1 2\\"" << ", str() = \\"" << out.str() << "\\"\\n"; - + std::ostringstream ate("1 2", std::ios_base::ate); ate << 3; - std::cout << "after writing the int '3' to append stream \\"1 2\\"" + std::cout << "After writing the int '3' to append stream \\"1 2\\"" << ", str() = \\"" << ate.str() << "\\"\\n"; } .SH Output: - after reading the first int from "1 2", the int is 1, str() = "1 2" - after writing the int '3' to output stream "1 2", str() = "3 2" - after writing the int '3' to append stream "1 2", str() = "1 23" + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" .SH See also - str replaces or obtains a copy of the associated character string - \fI(public member function of std::basic_stringbuf)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::basic_ostringstream::swap.3 b/man/std::basic_ostringstream::swap.3 index 6411700cd..10baede6b 100644 --- a/man/std::basic_ostringstream::swap.3 +++ b/man/std::basic_ostringstream::swap.3 @@ -1,11 +1,14 @@ -.TH std::basic_ostringstream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_ostringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::swap \- std::basic_ostringstream::swap + .SH Synopsis void swap( basic_ostringstream& other ); \fI(since C++11)\fP Exchanges the state of the stream with those of other. - This is done by calling basic_istream::swap(other) and - rdbuf->swap(other->rdbuf). + This is done by calling basic_ostream::swap(other) and + rdbuf()->swap(*other.rdbuf()). .SH Parameters @@ -15,6 +18,10 @@ \fI(none)\fP +.SH Exceptions + + May throw implementation-defined exceptions. + .SH Example This section is incomplete @@ -23,10 +30,10 @@ .SH See also operator= moves the string stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_stringbuf objects - \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP -.SH Category: +.SH Category: * Todo no example diff --git a/man/std::basic_ostringstream::view.3 b/man/std::basic_ostringstream::view.3 new file mode 100644 index 000000000..a98e54d32 --- /dev/null +++ b/man/std::basic_ostringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_ostringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::view \- std::basic_ostringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::basic_osyncstream.3 b/man/std::basic_osyncstream.3 new file mode 100644 index 000000000..18b8109c0 --- /dev/null +++ b/man/std::basic_osyncstream.3 @@ -0,0 +1,290 @@ +.TH std::basic_osyncstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream \- std::basic_osyncstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, \fI(since C++20)\fP + class Allocator = std::allocator + + > class basic_osyncstream : public std::basic_ostream + + The class template std::basic_osyncstream is a convenience wrapper for + std::basic_syncbuf. It provides a mechanism to synchronize threads writing to the + same stream. + + It can be used with a named variable: + + { + std::osyncstream synced_out(std::cout); // synchronized wrapper for std::cout + synced_out << "Hello, "; + synced_out << "World!"; + synced_out << std::endl; // flush is noted, but not yet performed + synced_out << "and more!\\n"; + } // characters are transferred and std::cout is flushed + + as well as with a temporary: + + std::osyncstream(std::cout) << "Hello, " << "World!" << '\\n'; + + It provides the guarantee that all output made to the same final destination buffer + (std::cout in the examples above) will be free of data races and will not be + interleaved or garbled in any way, as long as every write to that final destination + buffer is made through (possibly different) instances of std::basic_osyncstream. + + Typical implementation of std::basic_osyncstream holds only one member: the wrapped + std::basic_syncbuf. + + std-basic osyncstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::osyncstream std::basic_osyncstream + std::wosyncstream std::basic_osyncstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + streambuf_type std::basic_streambuf + syncbuf_type std::basic_syncbuf + +.SH Member functions + + constructor constructs a basic_osyncstream object + \fI(public member function)\fP + operator= assigns a basic_osyncstream object + \fI(public member function)\fP + destructor destroys the basic_osyncstream and emits its internal buffer + \fI(public member function)\fP + rdbuf obtains a pointer to the underlying basic_syncbuf + \fI(public member function)\fP + get_wrapped obtains a pointer to the final destination stream buffer + \fI(public member function)\fP + calls emit() on the underlying basic_syncbuf to transmit its internal + emit data to the final destination + \fI(public member function)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_syncbuf 201803L (C++20) Synchronized buffered ostream (std::osyncstream, + std::syncbuf) and manipulators diff --git a/man/std::basic_osyncstream::basic_osyncstream.3 b/man/std::basic_osyncstream::basic_osyncstream.3 new file mode 100644 index 000000000..71430efb2 --- /dev/null +++ b/man/std::basic_osyncstream::basic_osyncstream.3 @@ -0,0 +1,102 @@ +.TH std::basic_osyncstream::basic_osyncstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream::basic_osyncstream \- std::basic_osyncstream::basic_osyncstream + +.SH Synopsis + basic_osyncstream( streambuf_type* buf, const Allocator& a ); \fB(1)\fP + explicit basic_osyncstream( streambuf_type* buf ); \fB(2)\fP + basic_osyncstream( std::basic_ostream& os, const Allocator& a ); \fB(3)\fP + explicit basic_osyncstream( std::basic_ostream& os ); \fB(4)\fP + basic_osyncstream( std::basic_osyncstream&& other ) noexcept; \fB(5)\fP + + Constructs new synchronized output stream. + + 1-4) Constructs the private member std::basic_syncbuf using the buffer and the + allocator provided, and initializes the base class with a pointer to the member + std::basic_streambuf. + 5) Move constructor. Move-constructs the std::basic_ostream base and the + std::basic_syncbuf member from the corresponding subobjects of other, then calls + set_rdbuf with the pointer to the newly-constructed underlying std::basic_syncbuf to + complete the initialization of the base. After this move constructor, + other.get_wrapped() returns nullptr and destruction of other produces no output. + +.SH Parameters + + buf - pointer to the std::basic_streambuf that will be wrapped + os - reference to a std::basic_ostream, whose rdbuf() will be wrapped + a - the allocator to pass to the constructor of the member std::basic_syncbuf + other - another osyncstream to move from + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void worker(const int id, std::ostream &os) + { + std::string_view block; + switch (id) + { + default: [[fallthrough]]; + case 0: block = "██"; + break; + case 1: block = "▓▓"; + break; + case 2: block = "▒▒"; + break; + case 3: block = "░░"; + break; + } + for (int i = 1; i <= 50; ++i) + os << block << std::flush; + os << std::endl; + } + + int main() + { + std::cout << "Synchronized output should not cause any interference:" << std::endl; + { + auto scout1 = std::osyncstream{std::cout}; + auto scout2 = std::osyncstream{std::cout}; + auto scout3 = std::osyncstream{std::cout}; + auto scout4 = std::osyncstream{std::cout}; + auto w1 = std::jthread{worker, 0, std::ref(scout1)}; + auto w2 = std::jthread{worker, 1, std::ref(scout2)}; + auto w3 = std::jthread{worker, 2, std::ref(scout3)}; + auto w4 = std::jthread{worker, 3, std::ref(scout4)}; + } + + std::cout << "\\nLack of synchronization may cause some interference on output:" + << std::endl; + { + auto w1 = std::jthread{worker, 0, std::ref(std::cout)}; + auto w2 = std::jthread{worker, 1, std::ref(std::cout)}; + auto w3 = std::jthread{worker, 2, std::ref(std::cout)}; + auto w4 = std::jthread{worker, 3, std::ref(std::cout)}; + } + } + +.SH Possible output: + + Synchronized output should not cause any interference: + ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ + ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ + ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ + ████████████████████████████████████████████████████████████████████████████████████████████████████ + + Lack of synchronization may cause some interference on output: + ████▓▓██▒▒▒▒▓▓██░░▒▒██░░▒▒░░░░▒▒░░▓▓▒▒██░░████████████▓▓██████▓▓▒▒▓▓██░░████▓▓▓▓██▒▒░░░░░░░░▓▓░░▓▓██▒▒▒▒▒▒▒▒▓▓██▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░▒▒▒▒░░▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒▒██░░░░░░░░▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓████████▓▓▓▓▓▓▓▓▓▓▓▓░░▓▓▓▓ + ▒▒▒▒██░░██████████████████████████░░░░░░░░░░░░░░██░░▒▒░░░░░░██████████████████ + ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒▒▒▒▒▒ + ░░░░░░ + +.SH See also + + constructs a basic_syncbuf object + constructor \fI(public member function of std::basic_syncbuf)\fP + diff --git a/man/std::basic_osyncstream::emit.3 b/man/std::basic_osyncstream::emit.3 new file mode 100644 index 000000000..e127f90b8 --- /dev/null +++ b/man/std::basic_osyncstream::emit.3 @@ -0,0 +1,61 @@ +.TH std::basic_osyncstream::emit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream::emit \- std::basic_osyncstream::emit + +.SH Synopsis + void emit(); + + Emits all buffered output and executes any pending flushes, by calling emit() on the + underlying std::basic_syncbuf. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + { + std::osyncstream bout(std::cout); + bout << "Hello," << '\\n'; // no flush + bout.emit(); // characters transferred; cout not flushed + bout << "World!" << std::endl; // flush noted; cout not flushed + bout.emit(); // characters transferred; cout flushed + bout << "Greetings." << '\\n'; // no flush + } // destructor calls emit(): characters transferred; cout not flushed + + // emit can be used for local exception-handling on the wrapped stream + std::osyncstream bout(std::cout); + bout << "Hello, " << "World!" << '\\n'; + try + { + bout.emit(); + } + catch (...) + { + // handle exceptions + } + } + +.SH Output: + + Hello, + World! + Greetings. + Hello, World! + +.SH See also + + destructor destroys the basic_osyncstream and emits its internal buffer + \fI(public member function)\fP + atomically transmits the entire internal buffer to the wrapped + emit streambuf + \fI(public member function of std::basic_syncbuf)\fP + diff --git a/man/std::basic_osyncstream::get_wrapped.3 b/man/std::basic_osyncstream::get_wrapped.3 new file mode 100644 index 000000000..5d0c531ed --- /dev/null +++ b/man/std::basic_osyncstream::get_wrapped.3 @@ -0,0 +1,47 @@ +.TH std::basic_osyncstream::get_wrapped 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream::get_wrapped \- std::basic_osyncstream::get_wrapped + +.SH Synopsis + streambuf_type* get_wrapped() const noexcept; + + Returns a pointer to the wrapped std::basic_streambuf, obtained by calling + get_wrapped() on the underlying std::basic_syncbuf. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + Wrapped buffer can be safely wrapped again in a different synchronized output + stream. + + +// Run this code + + #include + #include + + int main() + { + std::osyncstream bout1(std::cout); + bout1 << "Hello, "; + { + std::osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << '\\n'; + } // emits the contents of the temporary buffer + bout1 << "World!" << '\\n'; + } // emits the contents of bout1 + +.SH Output: + + Goodbye, Planet! + Hello, World! + +.SH See also + + destructor destroys the basic_osyncstream and emits its internal buffer + \fI(public member function)\fP + retrieves the wrapped streambuf pointer + get_wrapped \fI(public member function of std::basic_syncbuf)\fP + diff --git a/man/std::basic_osyncstream::operator=.3 b/man/std::basic_osyncstream::operator=.3 new file mode 100644 index 000000000..ee85db6a6 --- /dev/null +++ b/man/std::basic_osyncstream::operator=.3 @@ -0,0 +1,67 @@ +.TH std::basic_osyncstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream::operator= \- std::basic_osyncstream::operator= + +.SH Synopsis + basic_osyncstream& operator=( std::basic_osyncstream&& other ); \fI(since C++20)\fP + + Move-assigns a synchronized output stream: + + Move-assigns the wrapped std::basic_syncbuf from the corresponding member of other + (after this move-assignment, other.get_wrapped() returns a null pointer and + destruction of other produces no output; any pending buffered output will be + emitted) and move-assigns the base std::basic_ostream (this swaps all stream state + variables except for rdbuf between *this and other) + +.SH Parameters + + other - another synchronized output stream to move from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::osyncstream out(std::cout); + out << "test\\n"; + std::ostringstream str_out; + std::osyncstream{str_out} = std::move(out); // Note that out is emitted here + std::cout << "str_out = " << std::quoted(str_out.view()) << '\\n'; + } + +.SH Output: + + test + str_out = "" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the move assignment operator was noexcept, but + LWG 3867 C++20 std::basic_syncbuf's move assignment operator removed noexcept + is not + +.SH See also + + constructor constructs a basic_osyncstream object + \fI(public member function)\fP + destructor destroys the basic_osyncstream and emits its internal buffer + \fI(public member function)\fP + calls emit() on the underlying basic_syncbuf to transmit its internal + emit data to the final destination + \fI(public member function)\fP diff --git a/man/std::basic_osyncstream::rdbuf.3 b/man/std::basic_osyncstream::rdbuf.3 new file mode 100644 index 000000000..f6d516910 --- /dev/null +++ b/man/std::basic_osyncstream::rdbuf.3 @@ -0,0 +1,27 @@ +.TH std::basic_osyncstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream::rdbuf \- std::basic_osyncstream::rdbuf + +.SH Synopsis + syncbuf_type* rdbuf() const noexcept; + + Returns a pointer to the underlying std::basic_syncbuf. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get_wrapped obtains a pointer to the final destination stream buffer + \fI(public member function)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_osyncstream::~basic_osyncstream.3 b/man/std::basic_osyncstream::~basic_osyncstream.3 new file mode 100644 index 000000000..75f7d54a7 --- /dev/null +++ b/man/std::basic_osyncstream::~basic_osyncstream.3 @@ -0,0 +1,29 @@ +.TH std::basic_osyncstream::~basic_osyncstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_osyncstream::~basic_osyncstream \- std::basic_osyncstream::~basic_osyncstream + +.SH Synopsis + ~basic_osyncstream(); + + Destroys a synchronized output stream. + + The destruction of the member std::basic_syncbuf will emit any buffered output not + yet emitted. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + destroys the basic_syncbuf and emits its internal buffer + destructor \fI(public member function of std::basic_syncbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::basic_regex.3 b/man/std::basic_regex.3 index 0fa802e59..f9b104d69 100644 --- a/man/std::basic_regex.3 +++ b/man/std::basic_regex.3 @@ -1,9 +1,12 @@ -.TH std::basic_regex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex \- std::basic_regex + .SH Synopsis Defined in header - template < + template< - class CharT = char, \fI(since C++11)\fP + class CharT, \fI(since C++11)\fP class Traits = std::regex_traits > class basic_regex; @@ -11,12 +14,12 @@ The class template basic_regex provides a general framework for holding regular expressions. - Several specializations for common character types are provided: + Several typedefs for common character types are provided: Defined in header - Type Definition - regex basic_regex - wregex basic_regex + Type Definition + std::regex std::basic_regex + std::wregex std::basic_regex .SH Member types @@ -29,56 +32,70 @@ .SH Member functions - Value Effect(s) - icase Character matching should be performed without regard to case. - nosubs When performing matches, no sub-expression matches should be stored in - the supplied std::regex_match structure. - Instructs the regular expression engine to make matching faster, with the - optimize potential cost of making construction slower. For example, this might - mean converting a non-deterministic FSA to a deterministic FSA. - collate Character ranges of the form "[a-b]" will be locale sensitive. - ECMAScript Use the Modified ECMAScript regular expression grammar - basic Use the basic POSIX regular expression grammar (grammar documentation). - extended Use the extended POSIX regular expression grammar (grammar - documentation). - awk Use the regular expression grammar used by the awk utility in POSIX - (grammar documentation) - Use the regular expression grammar used by the grep utility in POSIX. - grep This is effectively the same as the basic option with the addition of - newline '\\n' as an alternation separator. - Use the regular expression grammar used by the grep utility, with the -E - egrep option, in POSIX. This is effectively the same as the extended option - with the addition of newline '\\n' as an alternation separator in addtion - to '|'. - constructor constructs the regex object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the regex object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP assign assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers returns the number of marked sub-expressions within the regular mark_count expression - \fI(public member function)\fP + \fI(public member function)\fP flags returns the syntax flags - \fI(public member function)\fP + \fI(public member function)\fP .SH Locale getloc get locale information - \fI(public member function)\fP + \fI(public member function)\fP imbue set locale information - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Constants + Grammar option Effect(s) + ECMAScript Use the Modified ECMAScript regular expression grammar. + basic Use the basic POSIX regular expression grammar (grammar + documentation). + extended Use the extended POSIX regular expression grammar (grammar + documentation). + awk Use the regular expression grammar used by the awk utility in + POSIX (grammar documentation). + Use the regular expression grammar used by the grep utility in + grep POSIX. This is effectively the same as the basic option with the + addition of newline '\\n' as an alternation separator. + Use the regular expression grammar used by the grep utility, with + egrep the -E option, in POSIX. This is effectively the same as the + extended option with the addition of newline '\\n' as an + alternation separator in addition to '|'. + Grammar variation Effect(s) + icase Character matching should be performed without regard to case. + When performing matches, all marked sub-expressions (expr) are + nosubs treated as non-marking sub-expressions (?:expr). No matches are + stored in the supplied std::regex_match structure and mark_count() + is zero. + Instructs the regular expression engine to make matching faster, + optimize with the potential cost of making construction slower. For + example, this might mean converting a non-deterministic FSA to a + deterministic FSA. + collate Character ranges of the form "[a-b]" will be locale sensitive. + multiline \fI(C++17)\fP Specifies that ^ shall match the beginning of a line and $ shall + match the end of a line, if the ECMAScript engine is selected. + + At most one grammar option can be chosen out of ECMAScript, basic, extended, awk, + grep, egrep. If no grammar is chosen, ECMAScript is assumed to be selected. The + other options serve as variations, such that std::regex("meow", std::regex::icase) + is equivalent to std::regex("meow", std::regex::ECMAScript|std::regex::icase). + The member constants in basic_regex are duplicates of the syntax_option_type constants defined in the namespace std::regex_constants. .SH Non-member functions std::swap(std::basic_regex) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + + Deduction guides\fI(since C++17)\fP diff --git a/man/std::basic_regex::assign.3 b/man/std::basic_regex::assign.3 index fabbac434..839482ea8 100644 --- a/man/std::basic_regex::assign.3 +++ b/man/std::basic_regex::assign.3 @@ -1,12 +1,16 @@ -.TH std::basic_regex::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::assign \- std::basic_regex::assign + .SH Synopsis basic_regex& assign( const basic_regex& other ); \fB(1)\fP \fI(since C++11)\fP - basic_regex& assign( basic_regex&& that ); \fB(2)\fP \fI(since C++11)\fP + basic_regex& assign( basic_regex&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP basic_regex& assign( const CharT* s, flag_type f = \fB(3)\fP \fI(since C++11)\fP std::regex_constants::ECMAScript ); - basic_regex& assign( const charT* ptr, size_t count, \fB(4)\fP \fI(since C++11)\fP - flag_type f = regex_constants::ECMAScript ); + basic_regex& assign( const CharT* ptr, std::size_t count, + flag_type f = \fB(4)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); template< class ST, class SA > basic_regex& assign( const std::basic_string& str, \fB(5)\fP \fI(since C++11)\fP @@ -48,7 +52,7 @@ ilist - initializer list containing characters to assign .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value @@ -56,11 +60,7 @@ .SH Exceptions - 1) \fI(none)\fP - 2) - noexcept specification: - noexcept - + 1) May throw implementation-defined exceptions. 3-7) std::regex_error if the supplied regular expression is not valid. The object is not modified in that case. @@ -72,8 +72,7 @@ .SH See also operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_regex::basic_regex.3 b/man/std::basic_regex::basic_regex.3 index 26974e720..79d139c71 100644 --- a/man/std::basic_regex::basic_regex.3 +++ b/man/std::basic_regex::basic_regex.3 @@ -1,4 +1,7 @@ -.TH std::basic_regex::basic_regex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::basic_regex \- std::basic_regex::basic_regex + .SH Synopsis basic_regex(); \fB(1)\fP \fI(since C++11)\fP explicit basic_regex( const CharT* s, @@ -7,7 +10,7 @@ basic_regex( const CharT* s, std::size_t count, \fB(3)\fP \fI(since C++11)\fP flag_type f = std::regex_constants::ECMAScript ); basic_regex( const basic_regex& other ); \fB(4)\fP \fI(since C++11)\fP - basic_regex( basic_regex&& other ); \fB(5)\fP \fI(since C++11)\fP + basic_regex( basic_regex&& other ) noexcept; \fB(5)\fP \fI(since C++11)\fP template< class ST, class SA > explicit basic_regex( const std::basic_string& str, \fB(6)\fP \fI(since C++11)\fP @@ -29,12 +32,12 @@ nothing. 2) Constructs a regex from a null-terminated string s. 3) Constructs a regex from a sequence of count characters, pointed to by s. - 4) Copy constructor. Constructs a regex by copying other - 5) Move constructor. Constructs a regex by with the contents of other using move + 4) Copy constructor. Constructs a regex by copying other. + 5) Move constructor. Constructs a regex with the contents of other using move semantics. 6) Constructs a regex from a string str. - 7) Range constructor. Constructs the string with the contents of the range [first, - last). + 7) Range constructor. Constructs the string with the contents of the range + [first, last). 8) Initializer list constructor. Constructs the string with the contents of the initializer list init. @@ -50,15 +53,120 @@ regular expression .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Exceptions - 1) \fI(none)\fP - 2-3) std::regex_error if the supplied regular expression is not valid. - 4) \fI(none)\fP - 5) - noexcept specification: - noexcept - - 5-8) std::regex_error if the supplied regular expression is not valid. + 1) May throw implementation-defined exceptions. + 2,3) std::regex_error if the supplied regular expression is not valid. + 4) May throw implementation-defined exceptions. + 6-8) std::regex_error if the supplied regular expression is not valid. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void match_and_print(const std::string& text, const std::regex& pattern) + { + std::sregex_iterator it(text.begin(), text.end(), pattern), it_end; + int count = 0; + for (; it != it_end; ++it) + { + const std::smatch& match = *it; + std::cout << ++count << ". " << std::quoted(match.str()) << '\\n'; + } + std::cout << (count ? "\\n" : "no match found\\n\\n"); + } + + int main() + { + const std::string text = "Hello, World! 12345"; + + // Matches one or more digits + std::string pattern_text = "\\\\d+"; + std::cout << "digits (" << pattern_text << "):\\n"; + auto pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[^\\\\s]+"; + std::cout << "words (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[a-zA-Z]+"; + std::cout << "words without symbols and digits (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one non digits, non alphabet + pattern_text = "[^0-9A-Za-z]"; + std::cout << "symbol (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase + pattern_text = "[a-z]+"; + std::cout << "lowercase (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase with std::regex::icase flag + pattern_text = "[a-z]+"; + std::cout << "lowercase with ignore case flag (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::icase); + match_and_print(text, pattern); + + // Matches basic POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "basic POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::basic); + match_and_print(text, pattern); + + // Matches extended POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "extended POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::extended); + match_and_print(text, pattern); + } + +.SH Output: + + digits (\\d+): + 1. "12345" + + words ([^\\s]+): + 1. "Hello," + 2. "World!" + 3. "12345" + + words without symbols and digits ([a-zA-Z]+): + 1. "Hello" + 2. "World" + + symbol ([^0-9A-Za-z]): + 1. "," + 2. " " + 3. "!" + 4. " " + + lowercase ([a-z]+): + 1. "ello" + 2. "orld" + + lowercase with ignore case flag ([a-z]+): + 1. "Hello" + 2. "World" + + basic POSIX regex ([[:digit:]]+): + no match found + + extended POSIX regex ([[:digit:]]+): + 1. "12345" diff --git a/man/std::basic_regex::flags.3 b/man/std::basic_regex::flags.3 index 87417d3a6..f8f95a215 100644 --- a/man/std::basic_regex::flags.3 +++ b/man/std::basic_regex::flags.3 @@ -1,4 +1,7 @@ -.TH std::basic_regex::flags 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::flags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::flags \- std::basic_regex::flags + .SH Synopsis flag_type flags() const; \fI(since C++11)\fP @@ -15,7 +18,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -23,5 +26,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_regex::getloc.3 b/man/std::basic_regex::getloc.3 index 2344492fa..360a83e07 100644 --- a/man/std::basic_regex::getloc.3 +++ b/man/std::basic_regex::getloc.3 @@ -1,4 +1,7 @@ -.TH std::basic_regex::getloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::getloc \- std::basic_regex::getloc + .SH Synopsis locale_type getloc() const; \fI(since C++11)\fP @@ -17,7 +20,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -27,8 +30,7 @@ .SH See also imbue set locale information - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_regex::imbue.3 b/man/std::basic_regex::imbue.3 index 8af97a83a..bf4ad79d2 100644 --- a/man/std::basic_regex::imbue.3 +++ b/man/std::basic_regex::imbue.3 @@ -1,4 +1,7 @@ -.TH std::basic_regex::imbue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::imbue \- std::basic_regex::imbue + .SH Synopsis locale_type imbue( locale_type loc ); \fI(since C++11)\fP @@ -19,7 +22,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -29,8 +32,7 @@ .SH See also getloc get locale information - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_regex::mark_count.3 b/man/std::basic_regex::mark_count.3 index dd6964688..20b3a9bf6 100644 --- a/man/std::basic_regex::mark_count.3 +++ b/man/std::basic_regex::mark_count.3 @@ -1,8 +1,12 @@ -.TH std::basic_regex::mark_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::mark_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::mark_count \- std::basic_regex::mark_count + .SH Synopsis unsigned mark_count() const; \fI(since C++11)\fP - Returns the number of marked sub-expressions within the regular expression. + Returns the number of marked sub-expressions (also known as capture groups) within + the regular expression. .SH Parameters @@ -14,13 +18,51 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + + int main() + { + std::regex r1{"abcde"}; + std::cout << "r1 has " << r1.mark_count() << " subexpressions" << '\\n'; + // Expected: 0 + + std::regex r2{"ab(c)de"}; + std::cout << "r2 has " << r2.mark_count() << " subexpressions" << '\\n'; + // Expected: 1 + + std::regex r3{"a(bc)d(e)"}; + std::cout << "r3 has " << r3.mark_count() << " subexpressions" << '\\n'; + // Expected: 2 + + // Nested sub-expressions + std::regex r4{"abc(de(fg))"}; + std::cout << "r4 has " << r4.mark_count() << " subexpressions" << '\\n'; + // Expected: 2 + + // Escaped parentheses + std::regex r5{"a(bc\\\\(\\\\)de)"}; + std::cout << "r5 has " << r5.mark_count() << " subexpressions" << '\\n'; + // Expected: 1 + + // Using nosubs flag + std::regex r6{"ab(c)de", std::regex_constants::nosubs}; + std::cout << "r6 has " << r6.mark_count() << " subexpressions" << '\\n'; + // Expected: 0 + } + +.SH Output: - * Todo no example + r1 has 0 subexpressions + r2 has 1 subexpressions + r3 has 2 subexpressions + r4 has 2 subexpressions + r5 has 1 subexpressions + r6 has 0 subexpressions diff --git a/man/std::basic_regex::operator=.3 b/man/std::basic_regex::operator=.3 index da7570b37..160225b20 100644 --- a/man/std::basic_regex::operator=.3 +++ b/man/std::basic_regex::operator=.3 @@ -1,8 +1,11 @@ -.TH std::basic_regex::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::operator= \- std::basic_regex::operator= + .SH Synopsis Defined in header basic_regex& operator=( const basic_regex& other ); \fB(1)\fP \fI(since C++11)\fP - basic_regex& operator=( basic_regex&& other ); \fB(2)\fP \fI(since C++11)\fP + basic_regex& operator=( basic_regex&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP basic_regex& operator=( const CharT* ptr ); \fB(3)\fP \fI(since C++11)\fP basic_regex& operator=( std::initializer_list il ); \fB(4)\fP \fI(since C++11)\fP template< class ST, class SA > \fB(5)\fP \fI(since C++11)\fP @@ -29,18 +32,15 @@ .SH Return value - *this. + *this .SH Exceptions - 1) \fI(none)\fP - 2) - noexcept specification: - noexcept - - 3-5) \fI(none)\fP + 1) May throw implementation-defined exceptions. + 3-5) std::regex_error if the supplied regular expression is not valid. The object is + not modified in that case. .SH See also assign assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_regex::swap.3 b/man/std::basic_regex::swap.3 index 57db017ad..7742099ee 100644 --- a/man/std::basic_regex::swap.3 +++ b/man/std::basic_regex::swap.3 @@ -1,6 +1,9 @@ -.TH std::basic_regex::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::swap \- std::basic_regex::swap + .SH Synopsis - void swap( basic_regex& other ); \fI(since C++11)\fP + void swap( basic_regex& other ) noexcept; \fI(since C++11)\fP Exchanges the contents of two regular expressions. @@ -12,12 +15,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -26,8 +23,7 @@ .SH See also std::swap(std::basic_regex) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_regex::~basic_regex.3 b/man/std::basic_regex::~basic_regex.3 index 1e5eba439..310ecee74 100644 --- a/man/std::basic_regex::~basic_regex.3 +++ b/man/std::basic_regex::~basic_regex.3 @@ -1,4 +1,7 @@ -.TH std::basic_regex::~basic_regex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regex::~basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::~basic_regex \- std::basic_regex::~basic_regex + .SH Synopsis ~basic_regex(); \fI(since C++11)\fP diff --git a/man/std::basic_regexconstants.3 b/man/std::basic_regexconstants.3 index ae60c168f..2e5fa379c 100644 --- a/man/std::basic_regexconstants.3 +++ b/man/std::basic_regexconstants.3 @@ -1,4 +1,7 @@ -.TH std::basic_regexconstants 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_regexconstants 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regexconstants \- std::basic_regexconstants + .SH Synopsis Defined in header static constexpr std::regex_constants::syntax_option_type icase = @@ -10,7 +13,8 @@ std::regex_constants::optimize; static constexpr std::regex_constants::syntax_option_type collate = std::regex_constants::collate; - static constexpr std::regex_constants::syntax_option_type ECMAScript = + static constexpr std::regex_constants::syntax_option_type ECMAScript + = std::regex_constants::ECMAScript; static constexpr std::regex_constants::syntax_option_type basic = std::regex_constants::basic; @@ -23,35 +27,49 @@ static constexpr std::regex_constants::syntax_option_type egrep = std::regex_constants::egrep; + static constexpr std::regex_constants::syntax_option_type multiline = \fI(since C++17)\fP + std::regex_constants::multiline; std::basic_regex defines several constants that govern general regex matching syntax. These constants are duplicated from std::regex_constants: - Value Effect(s) - icase Character matching should be performed without regard to case. - nosubs When performing matches, no sub-expression matches should be stored in - the supplied std::regex_match structure. - Instructs the regular expression engine to make matching faster, with the - optimize potential cost of making construction slower. For example, this might - mean converting a non-deterministic FSA to a deterministic FSA. - collate Character ranges of the form "[a-b]" will be locale sensitive. - ECMAScript Use the Modified ECMAScript regular expression grammar - basic Use the basic POSIX regular expression grammar (grammar documentation). - extended Use the extended POSIX regular expression grammar (grammar - documentation). - awk Use the regular expression grammar used by the awk utility in POSIX - (grammar documentation) - Use the regular expression grammar used by the grep utility in POSIX. - grep This is effectively the same as the basic option with the addition of - newline '\\n' as an alternation separator. - Use the regular expression grammar used by the grep utility, with the -E - egrep option, in POSIX. This is effectively the same as the extended option - with the addition of newline '\\n' as an alternation separator in addtion - to '|'. + Grammar option Effect(s) + ECMAScript Use the Modified ECMAScript regular expression grammar. + basic Use the basic POSIX regular expression grammar (grammar + documentation). + extended Use the extended POSIX regular expression grammar (grammar + documentation). + awk Use the regular expression grammar used by the awk utility in + POSIX (grammar documentation). + Use the regular expression grammar used by the grep utility in + grep POSIX. This is effectively the same as the basic option with the + addition of newline '\\n' as an alternation separator. + Use the regular expression grammar used by the grep utility, with + egrep the -E option, in POSIX. This is effectively the same as the + extended option with the addition of newline '\\n' as an + alternation separator in addition to '|'. + Grammar variation Effect(s) + icase Character matching should be performed without regard to case. + When performing matches, all marked sub-expressions (expr) are + nosubs treated as non-marking sub-expressions (?:expr). No matches are + stored in the supplied std::regex_match structure and mark_count() + is zero. + Instructs the regular expression engine to make matching faster, + optimize with the potential cost of making construction slower. For + example, this might mean converting a non-deterministic FSA to a + deterministic FSA. + collate Character ranges of the form "[a-b]" will be locale sensitive. + multiline \fI(C++17)\fP Specifies that ^ shall match the beginning of a line and $ shall + match the end of a line, if the ECMAScript engine is selected. + + At most one grammar option can be chosen out of ECMAScript, basic, extended, awk, + grep, egrep. If no grammar is chosen, ECMAScript is assumed to be selected. The + other options serve as variations, such that std::regex("meow", std::regex::icase) + is equivalent to std::regex("meow", std::regex::ECMAScript|std::regex::icase). .SH See also syntax_option_type general options controlling regex behavior - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP diff --git a/man/std::basic_spanbuf.3 b/man/std::basic_spanbuf.3 new file mode 100644 index 000000000..442a0244f --- /dev/null +++ b/man/std::basic_spanbuf.3 @@ -0,0 +1,238 @@ +.TH std::basic_spanbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf \- std::basic_spanbuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits (since C++23) + > class basic_spanbuf + + : public std::basic_streambuf + + std::basic_spanbuf is a std::basic_streambuf whose associated character sequence is + a memory-resident sequence of arbitrary characters, which can be initialized from or + made available as an instance of std::span. + + std::basic_spanbuf performs I/O on a fixed buffer, and therefore it does not attempt + to obtain a new buffer when the underlying buffer is exhausted. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::spanbuf std::basic_spanbuf + std::wspanbuf std::basic_spanbuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + + Data members + + Member name Definition + mod (private) A std::ios_base::openmode recording the open mode. + (exposition-only member object*) + buf (private) A std::span referencing the underlying buffer. + (exposition-only member object*) + +.SH Member functions + +.SH Public member functions + constructor constructs a basic_spanbuf object + (C++23) \fI(public member function)\fP + destructor destroys the basic_spanbuf object + \fB[virtual]\fP (C++23) \fI(virtual public member function)\fP + operator= assigns a basic_spanbuf object + (C++23) \fI(public member function)\fP + swap swaps two basic_spanbuf objects + (C++23) \fI(public member function)\fP + span obtains or initializes an underlying buffer according to mode + (C++23) \fI(public member function)\fP +.SH Protected member functions + setbuf attempts to replace the controlled character sequence with an + \fB[virtual]\fP (C++23) array + \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output + \fB[virtual]\fP (C++23) sequence, or both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output + \fB[virtual]\fP (C++23) sequence, or both using absolute addressing + \fI(virtual protected member function)\fP + +.SH Non-member functions + + std::swap(std::basic_spanbuf) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +Inherited from std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) +.SH Locales + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + +.SH Positioning + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + +.SH Putback + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + + +.SH Protected member functions + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Get area + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + eback returns a pointer to the beginning, current character and the end of + gptr the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + pbase returns a pointer to the beginning, current character and the end of + pptr the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + +.SH Notes + + std::basic_spanbuf does not own the underlying buffer. + + It is the responsibility of programmers to ensure the underlying buffer is in its + lifetime when used by a std::basic_spanbuf object. Additional synchronization may be + needed if more than one thread operates the same underlying buffer through different + std::basic_spanbuf objects. + + Feature-test macro Value Std Feature + __cpp_lib_spanstream 202106L (C++23) std::spanbuf, std::spanstream + +.SH See also + + basic_stringbuf implements raw string device + \fI(class template)\fP + strstreambuf implements raw character array device + (deprecated in C++98) \fI(class)\fP + (removed in C++26) diff --git a/man/std::basic_spanbuf::basic_spanbuf.3 b/man/std::basic_spanbuf::basic_spanbuf.3 new file mode 100644 index 000000000..adfd0c483 --- /dev/null +++ b/man/std::basic_spanbuf::basic_spanbuf.3 @@ -0,0 +1,82 @@ +.TH std::basic_spanbuf::basic_spanbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::basic_spanbuf \- std::basic_spanbuf::basic_spanbuf + +.SH Synopsis + basic_spanbuf() : basic_spanbuf(std::ios_base::in | \fB(1)\fP (since C++23) + std::ios_base::out) {} + explicit basic_spanbuf( std::ios_base::openmode which ) \fB(2)\fP (since C++23) + : basic_spanbuf(std::span{}, which) {} + explicit basic_spanbuf( std::span buf, + std::ios_base::openmode which = \fB(3)\fP (since C++23) + std::ios_base::in | std::ios_base::out + ); + basic_spanbuf( const basic_spanbuf& ) = delete; \fB(4)\fP (since C++23) + basic_spanbuf( basic_spanbuf&& rhs ); \fB(5)\fP (since C++23) + + 1) Default constructor. Creates a basic_spanbuf that has no underlying buffer and is + opened for both input and output. The pointers to get and put area are set to the + null pointer value. + 2) Same as \fB(1)\fP, except that the basic_spanbuf is opened in mode specified by which. + 3) Creates a basic_spanbuf that manages the underlying buffer referenced by buf (or + has no underlying buffer if buf is empty) and is opened in mode specified by which. + The pointers to get and put area are set as following, or to the null pointer value + if not mentioned in the table: + + Set bits in open mode Return value after setting + (affecting pointers to get area) eback() gptr() egptr() + std::ios_base::in s.data() s.data() s.data() + + s.size() + Set bits in open mode Return value after setting + (affecting pointers to put area) pbase() pptr() epptr() + std::ios_base::out && s.data() s.data() s.data() + + !std::ios_base::ate s.size() + std::ios_base::out && s.data() s.data() + s.data() + + std::ios_base::ate s.size() s.size() + + 4) Copy constructor is deleted. basic_spanbuf is not copyable. + 5) Move constructor. Move-constructs the std::basic_streambuf base subobject from + that of rhs. The pointers to get and put area, the open mode, and the underlying + buffer (if any) are identical to those in rhs before construction. + It is implementation-defined whether rhs still holds the underlying buffer after the + move-construction. + +.SH Parameters + + buf - a std::span referencing the underlying buffer + rhs - another basic_spanbuf + specifies stream open mode. It is bitmask type, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + which - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Notes + + These constructors are typically called by the constructors of + std::basic_ispanstream, std::basic_ospanstream, and std::basic_spanstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs the basic_ispanstream + (C++23) \fI(public member function of std::basic_ispanstream)\fP + + constructor constructs the basic_ospanstream + (C++23) \fI(public member function of std::basic_ospanstream)\fP + + constructor constructs the basic_spanstream + (C++23) \fI(public member function of std::basic_spanstream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanbuf::operator=.3 b/man/std::basic_spanbuf::operator=.3 new file mode 100644 index 000000000..23297a608 --- /dev/null +++ b/man/std::basic_spanbuf::operator=.3 @@ -0,0 +1,40 @@ +.TH std::basic_spanbuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::operator= \- std::basic_spanbuf::operator= + +.SH Synopsis + basic_spanbuf& operator=( basic_spanbuf&& rhs ); \fB(1)\fP (since C++23) + basic_spanbuf& operator( const basic_spanbuf& ) = delete; \fB(2)\fP (since C++23) + + 1) Move assignment operator. Equivalent to auto tmp{std::move(rhs)}; + this->swap(tmp); return *this;. After move assignment, *this holds the state rhs + held before move assignment. It is implementation-defined whether rhs still hold the + underlying buffer after move assignment. + 2) The copy assignment operator is deleted; basic_spanbuf is not CopyAssignable. + +.SH Parameters + + rhs - another basic_spanbuf that will be moved from + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_spanbuf object + (C++23) \fI(public member function)\fP + swap swaps two basic_spanbuf objects + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanbuf::seekoff.3 b/man/std::basic_spanbuf::seekoff.3 new file mode 100644 index 000000000..62da9e61b --- /dev/null +++ b/man/std::basic_spanbuf::seekoff.3 @@ -0,0 +1,82 @@ +.TH std::basic_spanbuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::seekoff \- std::basic_spanbuf::seekoff + +.SH Synopsis + protected: + + pos_type seekoff( off_type off, std::ios_base::seekdir dir, + std::ios_base::openmode which = (since C++23) + + std::ios_base::in | std::ios_base::out ) + override; + + Repositions the next pointer to get and/or put area, if possible, to the position + that corresponds to exactly off characters from beginning, end, or current position + of the get and/or put area of the buffer. + + Let n be the number of CharT elements in underlying buffer, or 0 when there is no + underlying buffer, this function fails if + + * the next pointer to the get and/or put area to reposition is null and the + computed newoff (see below) is not zero, which may occur if there is no + underlying buffer, or the *this is not opened in the mode required by which, or + * dir is std::ios_base::cur and both std::ios_base::in and std::ios_base::out are + set in which, or + * the computed newoff is not representable in off_type, less than zero, or greater + than n. + + newoff is computed as below: + + * If dir is std::ios_base::beg, newoff is off. + * If dir is std::ios_base::cur, newoff is + * pptr() - pbase() + off if std::ios_base::out is set in which, or + * gptr() - eback() + off if std::ios_base::in is set in which. + * If dir is std::ios_base::end, newoff is + * pptr() - pbase() + off if std::ios_base::out but not std::ios_base::in is + set in the open mode of *this, + * otherwise, off + n. + + This function repositions the next pointer to get and/or put area to pbuf + newoff + on success if std::ios_base::in and/or std::ios_base::out is correspondingly set in + which, where pbuf is the pointer to the beginning of the underlying buffer, or the + null pointer value if there is no underlying buffer. + +.SH Parameters + + off - relative position to set the next pointer(s) to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines whether the input sequences, the output sequence, or both are + affected. It can be one or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + pos_type(newoff) on success, pos_type(off_type(-1)) on failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanbuf::seekpos.3 b/man/std::basic_spanbuf::seekpos.3 new file mode 100644 index 000000000..68e561d2e --- /dev/null +++ b/man/std::basic_spanbuf::seekpos.3 @@ -0,0 +1,56 @@ +.TH std::basic_spanbuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::seekpos \- std::basic_spanbuf::seekpos + +.SH Synopsis + protected: + + pos_type seekpos( pos_type sp, std::ios_base::openmode which = (since C++23) + + std::ios_base::in | std::ios_base::out ) + override; + + Repositions the next pointer to the get and/or put area, if possible, to the + position indicated by sp. + + Equivalent to return seekoff(off_type(sp), std::ios_base::beg, which);. + +.SH Parameters + + sp - stream position, such as one obtained by seekoff() or seekpos() + defines whether the input sequences, the output sequence, or both are + affected. It can be one or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + sp on success or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the + single-argument versions of std::basic_istream::seekg() and + std::basic_ostream::seekp(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanbuf::setbuf.3 b/man/std::basic_spanbuf::setbuf.3 new file mode 100644 index 000000000..4aff160b3 --- /dev/null +++ b/man/std::basic_spanbuf::setbuf.3 @@ -0,0 +1,54 @@ +.TH std::basic_spanbuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::setbuf \- std::basic_spanbuf::setbuf + +.SH Synopsis + protected: + std::basic_streambuf* setbuf( CharT *s, (since C++23) + std::streamsize n ) override; + + Makes the basic_spanbuf perform I/O on the buffer [s, s + n). Equivalently calls + this->span(std::span(s, n)) and then returns this. + + Set bits in open mode Return value after setting + (affecting pointers to get area) eback() gptr() egptr() + std::ios_base::in s s s + n + Set bits in open mode Return value after setting + (affecting pointers to put area) pbase() pptr() epptr() + std::ios_base::out && !std::ios_base::ate s s s + n + std::ios_base::out && std::ios_base::ate s s + n s + n + + This function is protected virtual, it may only be called through pubsetbuf() or + from member functions of a user-defined class derived from std::basic_spanbuf. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer + n - the number of CharT elements in the user-provided buffer + +.SH Return value + + this + +.SH Notes + + The deprecated stream buffer std::strstreambuf or the boost.IOStreams device + boost::basic_array can also implement I/O buffering over a user-provided char array. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pubsetbuf invokes setbuf() + \fI(public member function of std::basic_streambuf)\fP + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanbuf::span.3 b/man/std::basic_spanbuf::span.3 new file mode 100644 index 000000000..49a3b7f4d --- /dev/null +++ b/man/std::basic_spanbuf::span.3 @@ -0,0 +1,53 @@ +.TH std::basic_spanbuf::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::span \- std::basic_spanbuf::span + +.SH Synopsis + std::span span() const noexcept; \fB(1)\fP (since C++23) + void span( std::span s ) noexcept; \fB(2)\fP (since C++23) + + 1) Gets a span referencing the written area if std::ios_base::out is set in the open + mode, or a span referencing the underlying buffer otherwise. + 2) Makes the basic_spanbuf perform I/O on the buffer referenced by s. Sets pointers + to get area, put area, or both. + + Set bits in open mode Return value after setting + (affecting pointers to get area) eback() gptr() egptr() + std::ios_base::in s.data() s.data() s.data() + + s.size() + Set bits in open mode Return value after setting + (affecting pointers to put area) pbase() pptr() epptr() + std::ios_base::out && s.data() s.data() s.data() + + !std::ios_base::ate s.size() + std::ios_base::out && s.data() s.data() + s.data() + + std::ios_base::ate s.size() s.size() + +.SH Parameters + + s - a std::span that references the user-provided buffer + +.SH Return value + + 1) std::span(pbase(), pptr()) if std::ios_base::out is set in the open mode, + or a std::span that references the whole underlying buffer otherwise. + 2) \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + + marks the buffer frozen and returns the beginning pointer of the input + str sequence + \fI(public member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanbuf::swap.3 b/man/std::basic_spanbuf::swap.3 new file mode 100644 index 000000000..d06a31435 --- /dev/null +++ b/man/std::basic_spanbuf::swap.3 @@ -0,0 +1,47 @@ +.TH std::basic_spanbuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanbuf::swap \- std::basic_spanbuf::swap + +.SH Synopsis + void swap( basic_spanbuf& rhs ); (since C++23) + + Swaps the state of *this and rhs. + + Calls std::basic_streambuf::swap(rhs), swaps the open mode of *this + and rhs, and then makes them use the underlying buffer of each other. + +.SH Parameters + + rhs - another basic_stringbuf + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + This function is called automatically when swapping stream objects, it is rarely + necessary to call it directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_spanbuf object + (C++23) \fI(public member function)\fP + swap swaps two basic_ispanstream objects + (C++23) \fI(public member function of std::basic_ispanstream)\fP + swap swaps two basic_ospanstream objects + (C++23) \fI(public member function of std::basic_ospanstream)\fP + swap swaps two basic_spanstream objects + (C++23) \fI(public member function of std::basic_spanstream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanstream.3 b/man/std::basic_spanstream.3 new file mode 100644 index 000000000..8edaee2fe --- /dev/null +++ b/man/std::basic_spanstream.3 @@ -0,0 +1,320 @@ +.TH std::basic_spanstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanstream \- std::basic_spanstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits (since C++23) + > class basic_spanstream + + : public basic_iostream + + The class template std::basic_spanstream implements input and output operations on + streams based on fixed buffers. + + At the low level, the class essentially wraps a raw device implementation of + std::basic_spanbuf into a higher-level interface of std::basic_iostream. The + complete interface to unique std::basic_spanbuf members is provided. + + std-basic spanstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::spanstream std::basic_spanstream + std::wspanstream std::basic_spanstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + + Data members + + Member name Definition + sb (private) The wrapped std::basic_spanbuf. + (exposition-only member object*) + +.SH Member functions + + constructor constructs the basic_spanstream + (C++23) \fI(public member function)\fP + destructor destroys the basic_spanstream + \fB[virtual]\fP (C++23) \fI(virtual public member function)\fP + operator= move-assignments the basic_spanstream + (C++23) \fI(public member function)\fP + swap swaps two basic_spanstream objects + (C++23) \fI(public member function)\fP + rdbuf obtains the address of the wrapped raw span device object + (C++23) \fI(public member function)\fP + Underlying buffer operations + span gets or sets the underlying buffer of the wrapped span device + (C++23) object + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_spanstream) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_spanstream 202106L (C++23) std::spanbuf, std::spanstream diff --git a/man/std::basic_spanstream::basic_spanstream.3 b/man/std::basic_spanstream::basic_spanstream.3 new file mode 100644 index 000000000..a7bad5456 --- /dev/null +++ b/man/std::basic_spanstream::basic_spanstream.3 @@ -0,0 +1,55 @@ +.TH std::basic_spanstream::basic_spanstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanstream::basic_spanstream \- std::basic_spanstream::basic_spanstream + +.SH Synopsis + explicit basic_spanstream( std::span s, + std::ios_base::openmode mode = \fB(1)\fP (since C++23) + std::ios_base::in | + std::ios_base::out ); + basic_spanstream( basic_spanstream&& rhs ); \fB(2)\fP (since C++23) + basic_spanstream( const basic_spanstream& ) = delete; \fB(3)\fP (since C++23) + + Constructs a new basic_spanstream. + + 1) Uses the storage referenced by s as initial underlying buffer of the wrapped + std::basic_spanbuf device. The wrapped std::basic_spanbuf object is constructed as + basic_spanbuf(s, mode). + 2) Move constructor. Move constructs the std::basic_iostream base subobject and the + wrapped std::basic_spanbuf from those of rhs, and then calls set_rdbuf with the + address of the wrapped std::basic_spanbuf in *this to install it. + 3) Copy constructor is deleted. basic_spanstream is not copyable. + +.SH Parameters + + s - std::span referencing the storage to be use as initial underlying buffer of + stream + specifies stream open mode. Following constants and bit-wise OR between them + may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another basic_spanstream to be moved from + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_spanbuf object + (C++23) \fI(public member function of std::basic_spanbuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanstream::operator=.3 b/man/std::basic_spanstream::operator=.3 new file mode 100644 index 000000000..7abec2137 --- /dev/null +++ b/man/std::basic_spanstream::operator=.3 @@ -0,0 +1,44 @@ +.TH std::basic_spanstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanstream::operator= \- std::basic_spanstream::operator= + +.SH Synopsis + basic_spanstream& operator=( basic_spanstream&& other ); \fB(1)\fP (since C++23) + basic_spanstream& operator=( const basic_spanstream& ) = delete; \fB(2)\fP (since C++23) + + 1) Move assigns the other to *this, effectively move-assigning both the + std::basic_iostream base class subobject and the wrapped std::basic_spanbuf. + 2) Copy assignment operator is deleted. basic_spanstream is not copy assignable. + + Note that move assignment operator of the base class swaps all stream state + variables (except for rdbuf()) between *this and other. + + It is implementation-defined whether the std::basic_spanbuf wrapped in other still + holds an underlying buffer after the move assignment. + +.SH Parameters + + other - another stream to move from + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_spanbuf object + (C++23) \fI(public member function of std::basic_spanbuf)\fP + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanstream::rdbuf.3 b/man/std::basic_spanstream::rdbuf.3 new file mode 100644 index 000000000..0c46df396 --- /dev/null +++ b/man/std::basic_spanstream::rdbuf.3 @@ -0,0 +1,29 @@ +.TH std::basic_spanstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanstream::rdbuf \- std::basic_spanstream::rdbuf + +.SH Synopsis + std::basic_spanbuf* rdbuf() const noexcept; (since C++23) + + Returns pointer to the wrapped raw device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the wrapped raw device object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_spanstream::span.3 b/man/std::basic_spanstream::span.3 new file mode 100644 index 000000000..fc2ca9597 --- /dev/null +++ b/man/std::basic_spanstream::span.3 @@ -0,0 +1,74 @@ +.TH std::basic_spanstream::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanstream::span \- std::basic_spanstream::span + +.SH Synopsis + std::span span() const noexcept; \fB(1)\fP (since C++23) + void span( std::span s ) noexcept; \fB(2)\fP (since C++23) + + 1) Gets a span referencing the written area if std::ios_base::out is set in the open + mode of the wrapped std::basic_spanbuf, or a span referencing the underlying buffer + otherwise. + 2) Makes the wrapped std::basic_spanbuf perform I/O on the buffer referenced by s. + +.SH Parameters + + s - std::span referencing the storage to be use as the new underlying buffer of + stream + +.SH Return value + + 1) A std::span referencing the underlying buffer or written area, depending on the + open mode of the wrapped std::basic_spanbuf. + 2) \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + char out_buf[16]; + std::ospanstream ost{std::span{out_buf}}; + ost << "C++" << ' ' << 23 << '\\0'; // note explicit null-termination + auto sp = ost.span(); + assert( + sp[0] == 'C' && sp[1] == '+' && sp[2] == '+' && + sp[3] == ' ' && sp[4] == '2' && sp[5] == '3' && + sp[6] == '\\0' + ); + std::cout << "sp.data(): [" << sp.data() << "]\\n"; + std::cout << "out_buf: [" << out_buf << "]\\n"; + // spanstream uses out_buf as internal storage, no allocations + assert(static_cast(out_buf) == sp.data()); + + const char in_buf[] = "X Y 42"; + std::ispanstream ist{std::span{in_buf}}; + assert(static_cast(in_buf) == ist.span().data()); + char c; + ist >> c; + assert(c == 'X'); + ist >> c; + assert(c == 'Y'); + int i; + ist >> i; + assert(i == 42); + ist >> i; // buffer is exhausted + assert(!ist); + } + +.SH Output: + + sp.data(): [C++ 23] + out_buf: [C++ 23] + +.SH See also + + span obtains or initializes an underlying buffer according to mode + (C++23) \fI(public member function of std::basic_spanbuf)\fP diff --git a/man/std::basic_spanstream::swap.3 b/man/std::basic_spanstream::swap.3 new file mode 100644 index 000000000..8cfc063c9 --- /dev/null +++ b/man/std::basic_spanstream::swap.3 @@ -0,0 +1,36 @@ +.TH std::basic_spanstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_spanstream::swap \- std::basic_spanstream::swap + +.SH Synopsis + void swap( basic_spanstream& other ); (since C++23) + + Exchanges the state of the stream with those of other. + + This is done by calling std::basic_iostream::swap(other) and swapping + the wrapped std::basic_spanbuf objects (accessible through *rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_spanbuf objects + (C++23) \fI(public member function of std::basic_spanbuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_stacktrace.3 b/man/std::basic_stacktrace.3 new file mode 100644 index 000000000..45d6f49bf --- /dev/null +++ b/man/std::basic_stacktrace.3 @@ -0,0 +1,189 @@ +.TH std::basic_stacktrace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace \- std::basic_stacktrace + +.SH Synopsis + Defined in header + template< class Allocator > \fB(1)\fP (since + class basic_stacktrace; C++23) + using stacktrace = \fB(2)\fP (since + std::basic_stacktrace>; C++23) + namespace pmr { + + using stacktrace = (since + \fB(3)\fP C++23) + std::basic_stacktrace>; + + } + + 1) The basic_stacktrace class template represents a snapshot of the whole stacktrace + or its given part. It satisfies the requirement of AllocatorAwareContainer, + SequenceContainer, and ReversibleContainer, except that only move, assignment, swap, + and operations for const-qualified sequence containers are supported, and the + semantics of comparison functions are different from those required for a container. + 2) Convenience type alias for the basic_stacktrace using the default std::allocator. + 3) Convenience type alias for the basic_stacktrace using the polymorphic allocator. + + The invocation sequence of the current evaluation \\(\\small{ {x}_{0} }\\)x[0] in the + current thread of execution is a sequence \\(\\small{ ({x}_{0}, \\dots, + {x}_{n})}\\)(x[0], ..., x[n]) of evaluations such that, for \\(\\small{i \\ge 0}\\)i≥0, + \\(\\small{ {x}_{i} }\\)x[i] is within the function invocation \\(\\small{ {x}_{i+1} + }\\)x[i+1]. + + A stacktrace is an approximate representation of an invocation sequence and consists + of stacktrace entries. + + A stacktrace entry represents an evaluation in a stacktrace. It is represented by + std::stacktrace_entry in the C++ standard library. + +.SH Template parameters + + An allocator that is used to acquire/release memory and to + Allocator - construct/destroy the elements in that memory. The type must meet the + requirements of Allocator. The program is ill-formed if + Allocator::value_type is not std::stacktrace_entry. + +.SH Member types + + Member type Definition + value_type std::stacktrace_entry + const_reference const value_type& + reference value_type& + const_iterator implementation-defined const LegacyRandomAccessIterator type + that models random_access_iterator + iterator const_iterator + reverse_iterator std::reverse_iterator + reverse_const_iterator std::reverse_iterator + difference_type implementation-defined signed integer type + size_type implementation-defined unsigned integer type + allocator_type Allocator + +.SH Member functions + + constructor creates a new basic_stacktrace + \fI(public member function)\fP + destructor destroys the basic_stacktrace + \fI(public member function)\fP + operator= assigns to the basic_stacktrace + \fI(public member function)\fP + current obtains the current stacktrace or its given part + \fB[static]\fP \fI(public static member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Capacity + empty checks whether the basic_stacktrace is empty + \fI(public member function)\fP + size returns the number of stacktrace entries + \fI(public member function)\fP + max_size returns the maximum possible number of stacktrace entries + \fI(public member function)\fP +.SH Element access + operator[] access specified stacktrace entry + \fI(public member function)\fP + at access specified stacktrace entry with bounds checking + \fI(public member function)\fP +.SH Modifiers + swap swaps the contents + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares the sizes and the contents of two + operator<=> basic_stacktrace values + (C++23) \fI(function template)\fP + std::swap(std::basic_stacktrace) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + to_string returns a string with a description of the + (C++23) basic_stacktrace + \fI(function template)\fP + operator<< performs stream output of basic_stracktrace + (C++23) \fI(function template)\fP + +.SH Helper classes + + std::hash hash support for std::basic_stacktrace + (C++23) \fI(class template specialization)\fP + std::formatter formatting support for basic_stacktrace + (C++23) \fI(class template specialization)\fP + +.SH Notes + + Support for custom allocators is provided for using basic_stacktrace on a hot path + or in embedded environments. Users can allocate stacktrace_entry objects on the + stack or in some other place, where appropriate. + + The sequence of std::stacktrace_entry objects owned by a std::basic_stacktrace is + immutable, and either is empty or represents a contiguous interval of the whole + stacktrace. + + boost::stacktrace::basic_stacktrace (available in Boost.Stacktrace) can be used + instead when std::basic_stacktrace is not available. + + Feature-test macro Value Std Feature + __cpp_lib_stacktrace 202011L (C++23) Stacktrace library + __cpp_lib_formatters 202302L (C++23) Formatting std::thread::id and std::stacktrace + +.SH Example + + The output obtained using Compiler Explorer: msvc and gcc. + + +// Run this code + + #include + #include + + int nested_func(int c) + { + std::cout << std::stacktrace::current() << '\\n'; + return c + 1; + } + + int func(int b) + { + return nested_func(b + 1); + } + + int main() + { + std::cout << func(777); + } + +.SH Possible output: + + // msvc output (the lines ending with '⤶' arrows are split to fit the width): + 0> C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\\compiler-explorer-compiler20221122-⤶ + 31624-2ja1sf.8ytzw\\example.cpp\fB(6)\fP: output_s!nested_func+0x1F + 1> C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\\compiler-explorer-compiler20221122-⤶ + 31624-2ja1sf.8ytzw\\example.cpp\fB(12)\fP: output_s!func+0x15 + 2> C:\\Users\\ContainerAdministrator\\AppData\\Local\\Temp\\compiler-explorer-compiler20221122-⤶ + 31624-2ja1sf.8ytzw\\example.cpp\fB(15)\fP: output_s!main+0xE + 3> D:\\a\\_work\\1\\s\\src\\vctools\\crt\\vcstartup\\src\\startup\\exe_common.inl(288): output_s!⤶ + __scrt_common_main_seh+0x10C + 4> KERNEL32!BaseThreadInitThunk+0x14 + 5> ntdll!RtlUserThreadStart+0x21 + 779 + + gcc output: + 0# nested_func(int) at /app/example.cpp:7 + 1# func(int) at /app/example.cpp:13 + 2# at /app/example.cpp:18 + 3# at :0 + 4# at :0 + 5# + + 779 + +.SH See also + + stacktrace_entry representation of an evaluation in a stacktrace + (C++23) \fI(class)\fP diff --git a/man/std::basic_stacktrace::at.3 b/man/std::basic_stacktrace::at.3 new file mode 100644 index 000000000..f841398be --- /dev/null +++ b/man/std::basic_stacktrace::at.3 @@ -0,0 +1,40 @@ +.TH std::basic_stacktrace::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::at \- std::basic_stacktrace::at + +.SH Synopsis + const_reference at( size_type pos ) const; (since C++23) + + Returns a reference to the entry at specified location pos, with bounds checking. + + If pos is not within the range of the stacktrace, an exception of type + std::out_of_range is thrown. + +.SH Parameters + + pos - position of the stacktrace entry to return + +.SH Return value + + Reference to the requested entry. + +.SH Exceptions + + std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] access specified stacktrace entry + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_stacktrace::basic_stacktrace.3 b/man/std::basic_stacktrace::basic_stacktrace.3 new file mode 100644 index 000000000..b32f61520 --- /dev/null +++ b/man/std::basic_stacktrace::basic_stacktrace.3 @@ -0,0 +1,77 @@ +.TH std::basic_stacktrace::basic_stacktrace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::basic_stacktrace \- std::basic_stacktrace::basic_stacktrace + +.SH Synopsis + basic_stacktrace() noexcept(/* see below */); \fB(1)\fP (since C++23) + explicit basic_stacktrace( const allocator_type& alloc ) noexcept; \fB(2)\fP (since C++23) + basic_stacktrace( const basic_stacktrace& other ); \fB(3)\fP (since C++23) + basic_stacktrace( basic_stacktrace&& other ) noexcept; \fB(4)\fP (since C++23) + basic_stacktrace( const basic_stacktrace& other, \fB(5)\fP (since C++23) + const allocator_type& alloc ); + basic_stacktrace( basic_stacktrace&& other, const allocator_type& \fB(6)\fP (since C++23) + alloc ); + + Constructs an empty basic_stacktrace, or copy/move from other. + + 1) Default constructor. Constructs an empty basic_stacktrace with a + default-constructed allocator. + 2) Constructs an empty basic_stacktrace using alloc as the allocator. + 3) Copy constructor. Constructs a basic_stacktrace with the copy of the contents of + other, the allocator is obtained as if by calling + std::allocator_traits::select_on_container_copy_construction(other.get_allocator()). + 4) Move constructor. Constructs a basic_stacktrace with the contents of other using + move semantics. Allocator is move-constructed from that of other. After + construction, other is left in a valid but unspecified state. + 5) Same as the copy constructor, except that alloc is used as the allocator. + 6) Behaves same as the move constructor if alloc == other.get_allocator(). + Otherwise, allocates memory with alloc and performs element-wise move. alloc is used + as the allocator. + + (3,5,6) may throw an exception or construct an empty basic_stacktrace on allocation + failure. + +.SH Parameters + + alloc - allocator to use for all memory allocations of the constructed + basic_stacktrace + other - another basic_stacktrace to copy/move from + +.SH Exceptions + + 1) + noexcept specification: + noexcept(std::is_nothrow_default_constructible_v) + 3,5,6) May propagate the exception thrown on allocation failure. + +.SH Complexity + + 1,2) Constant. + 3) Linear in size of other. + 4) Constant. + 5) Linear in size of other. + 6) Linear in size of other if alloc != other.get_allocator(), otherwise constant. + +.SH Notes + + After container move construction (overload \fB(4)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns to the basic_stacktrace + \fI(public member function)\fP + current obtains the current stacktrace or its given part + \fB[static]\fP \fI(public static member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::basic_stacktrace::begin,std::basic_stacktrace::cbegin.3 b/man/std::basic_stacktrace::begin,std::basic_stacktrace::cbegin.3 new file mode 100644 index 000000000..16d1d8e54 --- /dev/null +++ b/man/std::basic_stacktrace::begin,std::basic_stacktrace::cbegin.3 @@ -0,0 +1,59 @@ +.TH std::basic_stacktrace::begin,std::basic_stacktrace::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::begin,std::basic_stacktrace::cbegin \- std::basic_stacktrace::begin,std::basic_stacktrace::cbegin + +.SH Synopsis + const_iterator begin() const noexcept; \fB(1)\fP (since C++23) + const_iterator cbegin() const noexcept; \fB(2)\fP (since C++23) + + Returns an iterator to the first entry of the basic_stacktrace. + + If the basic_stacktrace is empty, the returned iterator is equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first entry. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto trace = std::stacktrace::current(); + auto empty_trace = std::stacktrace{}; + + // Print stacktrace. + std::for_each(trace.begin(), trace.end(), + [](const auto& f) { std::cout << f << '\\n'; }); + + if (empty_trace.begin() == empty_trace.end()) + std::cout << "stacktrace 'empty_trace' is indeed empty.\\n"; + } + +.SH Possible output: + + 0x0000000000402BA8 in ./prog.exe + __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 0x0000000000402A29 in ./prog.exe + stacktrace 'empty_trace' is indeed empty. + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::current.3 b/man/std::basic_stacktrace::current.3 new file mode 100644 index 000000000..cd7e2fbd1 --- /dev/null +++ b/man/std::basic_stacktrace::current.3 @@ -0,0 +1,60 @@ +.TH std::basic_stacktrace::current 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::current \- std::basic_stacktrace::current + +.SH Synopsis + static basic_stacktrace current( const allocator_type& alloc = \fB(1)\fP (since C++23) + allocator_type() ) noexcept; + static basic_stacktrace current( size_type skip, const + allocator_type& alloc = \fB(2)\fP (since C++23) + allocator_type() ) noexcept; + static basic_stacktrace current( size_type skip, size_type + max_depth, + \fB(3)\fP (since C++23) + const allocator_type& alloc = + + allocator_type() ) noexcept; + + Let s[i] (0 ≤ i < n) denote the (i+1)-th stacktrace entry in the stacktrace of the + current evaluation in the current thread of execution, where n is the count of the + stacktrace entries in the stackentry. + + 1) Attempts to create a basic_stacktrace consisting of s[0], s[1], ..., s[n - 1]. + 2) Attempts to create a basic_stacktrace consisting of s[m], s[m + 1], ..., s[n - + 1], where m is min(skip, n). + 3) Attempts to create a basic_stacktrace consisting of s[m], s[m + 1], ..., s[o - + 1], where m is min(skip, n) and o is min(skip + max_depth, n). The behavior is + undefined if the skip + max_depth < skip (i.e. the mathematical result of skip + + max_depth overflows). + + In all cases, alloc is stored into the created basic_stacktrace and used to allocate + the storage for stacktrace entries. + +.SH Parameters + + alloc - allocator to use for all memory allocations of the constructed + basic_stacktrace + skip - the number of stacktrace entries to skip + max_depth - the maximum depth of the stacktrace entries + +.SH Return value + + If the allocation succeeds, the basic_stacktrace described above. + + Otherwise, an empty basic_stacktrace. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor creates a new basic_stacktrace + \fI(public member function)\fP + current constructs a new source_location corresponding to the location of the + \fB[static]\fP call site + \fI(public static member function of std::source_location)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_stacktrace::empty.3 b/man/std::basic_stacktrace::empty.3 new file mode 100644 index 000000000..2cef56b3c --- /dev/null +++ b/man/std::basic_stacktrace::empty.3 @@ -0,0 +1,48 @@ +.TH std::basic_stacktrace::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::empty \- std::basic_stacktrace::empty + +.SH Synopsis + [[nodiscard]] bool empty() const noexcept; (since C++23) + + Checks if the stacktrace has no stacktrace entries. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stacktrace is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + std::stacktrace bktr; + std::cout << "Initially, bktr.empty(): " << bktr.empty() << '\\n'; + + bktr = std::stacktrace::current(); + std::cout << "After getting entries, bktr.empty(): " << bktr.empty() << '\\n'; + } + +.SH Possible output: + + Initially, bktr.empty(): true + After getting entries, bktr.empty(): false + +.SH See also + + size returns the number of stacktrace entries + \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::end,std::basic_stacktrace::cend.3 b/man/std::basic_stacktrace::end,std::basic_stacktrace::cend.3 new file mode 100644 index 000000000..6d1d122f7 --- /dev/null +++ b/man/std::basic_stacktrace::end,std::basic_stacktrace::cend.3 @@ -0,0 +1,60 @@ +.TH std::basic_stacktrace::end,std::basic_stacktrace::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::end,std::basic_stacktrace::cend \- std::basic_stacktrace::end,std::basic_stacktrace::cend + +.SH Synopsis + const_iterator end() const noexcept; \fB(1)\fP (since C++23) + const_iterator cend() const noexcept; \fB(2)\fP (since C++23) + + Returns the iterator pointing past the last entry of the basic_stacktrace. + + This iterator acts as a placeholder; attempting to dereference it results in + undefined behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The end iterator. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto trace = std::stacktrace::current(); + auto empty_trace = std::stacktrace{}; + + // Print stacktrace. + std::for_each(trace.begin(), trace.end(), + [](const auto& f) { std::cout << f << '\\n'; }); + + if (empty_trace.begin() == empty_trace.end()) + std::cout << "stacktrace 'empty_trace' is indeed empty.\\n"; + } + +.SH Possible output: + + 0x0000000000402BA8 in ./prog.exe + __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 0x0000000000402A29 in ./prog.exe + stacktrace 'empty_trace' is indeed empty. + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::get_allocator.3 b/man/std::basic_stacktrace::get_allocator.3 new file mode 100644 index 000000000..a45c37ff7 --- /dev/null +++ b/man/std::basic_stacktrace::get_allocator.3 @@ -0,0 +1,20 @@ +.TH std::basic_stacktrace::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::get_allocator \- std::basic_stacktrace::get_allocator + +.SH Synopsis + allocator_type get_allocator() const noexcept; (since C++23) + + Returns the allocator associated with the basic_stacktrace. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated allocator. + +.SH Complexity + + Constant. diff --git a/man/std::basic_stacktrace::max_size.3 b/man/std::basic_stacktrace::max_size.3 new file mode 100644 index 000000000..774cc4b7f --- /dev/null +++ b/man/std::basic_stacktrace::max_size.3 @@ -0,0 +1,52 @@ +.TH std::basic_stacktrace::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::max_size \- std::basic_stacktrace::max_size + +.SH Synopsis + size_type max_size() const noexcept; (since C++23) + + Returns the maximum number of elements the underlying container (typically a + std::vector) is able to hold due to system or library implementation limitations, + i.e. std::distance(begin(), end()) for the largest underlying container. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of elements. + +.SH Complexity + + Constant. + +.SH Notes + + This value typically reflects the theoretical limit on the size of the underlying + container, at most std::numeric_limits::max(). At runtime, the size + of the container may be limited to a value smaller than max_size() by the amount of + RAM available. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stacktrace trace; + std::cout << "Maximum size of a 'basic_stacktrace' is " << trace.max_size() << "\\n"; + } + +.SH Possible output: + + Maximum size of a 'basic_stacktrace' is 1152921504606846975 + +.SH See also + + size returns the number of stacktrace entries + \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::operator=.3 b/man/std::basic_stacktrace::operator=.3 new file mode 100644 index 000000000..a88b97586 --- /dev/null +++ b/man/std::basic_stacktrace::operator=.3 @@ -0,0 +1,80 @@ +.TH std::basic_stacktrace::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::operator= \- std::basic_stacktrace::operator= + +.SH Synopsis + basic_stacktrace& operator=( const basic_stacktrace& other ); \fB(1)\fP (since C++23) + basic_stacktrace& operator=( basic_stacktrace&& other ) \fB(2)\fP (since C++23) + noexcept(/* see below */); + + Replaces the contents of the basic_stacktrace. + + 1) Copy assignment operator. Replaces the contents with a copy of the contents of + other. + If + std::allocator_traits::propagate_on_container_copy_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If the + allocator of *this after assignment would compare unequal to its old value, the old + allocator is used to deallocate the memory, then the new allocator is used to + allocate it before copying the entries. Otherwise, the memory owned by *this may be + reused when possible. + 2) Move assignment operator. Replaces the contents with those of other using move + semantics (i.e. the data in other is moved from other into *this). other is in a + valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must assign each entries individually, + allocating additional memory using its own allocator as needed. + + In any case, the stacktrace entries originally belong to *this may be either + destroyed or replaced by element-wise assignment. + + *this may be set to empty on allocation failure if the implementation strengthens + the exception specification. + +.SH Parameters + + other - another basic_stacktrace to use as source + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 2) + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_move_assignment::value + || std::allocator_traits::is_always_equal::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor creates a new basic_stacktrace + \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::basic_stacktrace::operator[].3 b/man/std::basic_stacktrace::operator[].3 new file mode 100644 index 000000000..fb6759748 --- /dev/null +++ b/man/std::basic_stacktrace::operator[].3 @@ -0,0 +1,41 @@ +.TH std::basic_stacktrace::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::operator[] \- std::basic_stacktrace::operator[] + +.SH Synopsis + const_reference operator[]( size_type pos ) const; (since C++23) + + Returns a reference to the entry at specified location pos. No bounds checking is + performed. + + If pos is not within the range of the stacktrace, i.e. pos >= size(), the behavior + is undefined. + +.SH Parameters + + pos - position of the stacktrace entry to return + +.SH Return value + + Reference to the requested entry. + +.SH Exceptions + + Throws nothing. + +.SH Complexity + + Constant. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + at access specified stacktrace entry with bounds checking + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_stacktrace::rbegin,std::basic_stacktrace::crbegin.3 b/man/std::basic_stacktrace::rbegin,std::basic_stacktrace::crbegin.3 new file mode 100644 index 000000000..68029c0ee --- /dev/null +++ b/man/std::basic_stacktrace::rbegin,std::basic_stacktrace::crbegin.3 @@ -0,0 +1,59 @@ +.TH std::basic_stacktrace::rbegin,std::basic_stacktrace::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::rbegin,std::basic_stacktrace::crbegin \- std::basic_stacktrace::rbegin,std::basic_stacktrace::crbegin + +.SH Synopsis + const_reverse_iterator rbegin() const noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator crbegin() const noexcept; \fB(2)\fP (since C++23) + + Returns a reverse iterator to the first entry of the reversed basic_stacktrace. It + corresponds to the last entry of the original basic_stacktrace. If the + basic_stacktrace is empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first entry. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto trace = std::stacktrace::current(); + auto empty_trace = std::stacktrace{}; + + // Print stacktrace. + std::for_each(trace.rbegin(), trace.rend(), + [](const auto& f) { std::cout << f << '\\n'; }); + + if (empty_trace.rbegin() == empty_trace.rend()) + std::cout << "stacktrace 'empty_trace' is indeed empty.\\n"; + } + +.SH Possible output: + + 0x0000000000402A29 in ./prog.exe + __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 0x0000000000402BA5 in ./prog.exe + stacktrace 'empty_trace' is indeed empty. + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::rend,std::basic_stacktrace::crend.3 b/man/std::basic_stacktrace::rend,std::basic_stacktrace::crend.3 new file mode 100644 index 000000000..73715a7a6 --- /dev/null +++ b/man/std::basic_stacktrace::rend,std::basic_stacktrace::crend.3 @@ -0,0 +1,60 @@ +.TH std::basic_stacktrace::rend,std::basic_stacktrace::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::rend,std::basic_stacktrace::crend \- std::basic_stacktrace::rend,std::basic_stacktrace::crend + +.SH Synopsis + const_reverse_iterator rend() const noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator crend() const noexcept; \fB(2)\fP (since C++23) + + Returns a reverse iterator pointing past the last entry of the reversed + basic_stacktrace. It corresponds to the iterator preceding the first entry of the + original basic_stacktrace. This iterator acts as a placeholder, attempting to + dereference it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The end iterator of the reversed basic_stacktrace. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto trace = std::stacktrace::current(); + auto empty_trace = std::stacktrace{}; + + // Print stacktrace. + std::for_each(trace.rbegin(), trace.rend(), + [](const auto& f) { std::cout << f << '\\n'; }); + + if (empty_trace.rbegin() == empty_trace.rend()) + std::cout << "stacktrace 'empty_trace' is indeed empty.\\n"; + } + +.SH Possible output: + + 0x0000000000402A29 in ./prog.exe + __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 0x0000000000402BA5 in ./prog.exe + stacktrace 'empty_trace' is indeed empty. + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::size.3 b/man/std::basic_stacktrace::size.3 new file mode 100644 index 000000000..d18814cd2 --- /dev/null +++ b/man/std::basic_stacktrace::size.3 @@ -0,0 +1,49 @@ +.TH std::basic_stacktrace::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::size \- std::basic_stacktrace::size + +.SH Synopsis + size_type size() const noexcept; (since C++23) + + Returns the number of entries in the stacktrace. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of entries in the stacktrace. + +.SH Complexity + + Constant. + +.SH Example + + The following code uses size to display the number of entries in the current + stacktrace: + + +// Run this code + + #include + #include + + int main() + { + auto trace = std::stacktrace::current(); + + std::cout << "trace contains " << trace.size() << " entries.\\n"; + } + +.SH Possible output: + + trace contains 3 entries. + +.SH See also + + empty checks whether the basic_stacktrace is empty + \fI(public member function)\fP + max_size returns the maximum possible number of stacktrace entries + \fI(public member function)\fP diff --git a/man/std::basic_stacktrace::swap.3 b/man/std::basic_stacktrace::swap.3 new file mode 100644 index 000000000..aa3bf47c9 --- /dev/null +++ b/man/std::basic_stacktrace::swap.3 @@ -0,0 +1,48 @@ +.TH std::basic_stacktrace::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::swap \- std::basic_stacktrace::swap + +.SH Synopsis + void swap( basic_stacktrace& other ) noexcept(/* see below */); (since C++23) + + Exchanges the contents of the container with those of other. Does not invoke any + move, copy, or swap operations on individual stacktrace_entry objects. + + All iterators and references remain valid. The end() iterator is invalidated. + + If std::allocator_traits::propagate_on_container_swap::value is + true, then the allocators are exchanged using an unqualified call to non-member + swap. Otherwise, they are not swapped (and if get_allocator() != + other.get_allocator(), the behavior is undefined). + +.SH Parameters + + other - basic_stacktrace to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_swap::value + || std::allocator_traits::is_always_equal::value) + +.SH Complexity + + Constant. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::basic_stacktrace) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::basic_stacktrace::~basic_stacktrace.3 b/man/std::basic_stacktrace::~basic_stacktrace.3 new file mode 100644 index 000000000..34ea175f6 --- /dev/null +++ b/man/std::basic_stacktrace::~basic_stacktrace.3 @@ -0,0 +1,13 @@ +.TH std::basic_stacktrace::~basic_stacktrace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stacktrace::~basic_stacktrace \- std::basic_stacktrace::~basic_stacktrace + +.SH Synopsis + ~basic_stacktrace(); (since C++23) + + Destructs the basic_stacktrace. The destructors of the std::stacktrace_entry objects + it holds are called and the used storage is deallocated. + +.SH Complexity + + Linear in the size of the basic_stacktrace. diff --git a/man/std::basic_streambuf.3 b/man/std::basic_streambuf.3 index 11aa87140..9c01629e8 100644 --- a/man/std::basic_streambuf.3 +++ b/man/std::basic_streambuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf \- std::basic_streambuf + .SH Synopsis Defined in header template< @@ -11,13 +14,14 @@ The class basic_streambuf controls input and output to a character sequence. It includes and provides access to - 1) The controlled character sequence, also called the buffer, which may contain - input sequence (also called get area) for buffering the input operations and/or - output sequence (also called put area) for buffering the output operations. - 2) The associated character sequence, also called source (for input) or sink (for - output). This may be an entity that is accessed through OS API (file, TCP socket, - serial port, other character device), or it may be an object (std::vector, array, - string literal), that can be interpreted as a character source or sink. + 1. The controlled character sequence, also called the buffer, which may contain + input sequence (also called get area) for buffering the input operations and/or + output sequence (also called put area) for buffering the output operations. + 2. The associated character sequence, also called source (for input) or sink (for + output). This may be an entity that is accessed through OS API (file, TCP + socket, serial port, other character device), or it may be an object + (std::vector, array, string literal), that can be interpreted as a character + source or sink. The I/O stream objects std::basic_istream and std::basic_ostream, as well as all objects derived from them (std::ofstream, std::stringstream, etc), are implemented @@ -27,10 +31,10 @@ represents a subsequence, or a "window" into the associated character sequence. Its state is described by three pointers: - 1) The beginning pointer, always points at the lowest element of the buffer - 2) The next pointer, points at the element that is the next candidate for reading or - writing - 3) The end pointer, points one past the end of the buffer. + 1. The beginning pointer, always points at the lowest element of the buffer. + 2. The next pointer, points at the element that is the next candidate for reading + or writing. + 3. The end pointer, points one past the end of the buffer. A basic_streambuf object may support input (in which case the buffer described by the beginning, next, and end pointers is called get area), output (put area), or @@ -62,120 +66,129 @@ std-streambuf.svg - Two convenience typedefs are provided by the standard library + Several typedefs for common character types are provided: Defined in header - Type Definition - streambuf basic_streambuf - wstreambuf basic_streambuf + Type Definition + std::streambuf std::basic_streambuf + std::wstreambuf std::basic_streambuf .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type .SH Member functions - destructor destructs the basic_streambuf object - \fB[virtual]\fP \fI(virtual public member function)\fP + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI(virtual public member function)\fP .SH Locales - pubimbue invokes imbue() - \fI(public member function)\fP - getloc obtains a copy of the associated locale - \fI(public member function)\fP + pubimbue invokes imbue() + \fI(public member function)\fP + getloc obtains a copy of the associated locale + \fI(public member function)\fP .SH Positioning - pubsetbuf invokes setbuf() - \fI(public member function)\fP - pubseekoff invokes seekoff() - \fI(public member function)\fP - pubseekpos invokes seekpos() - \fI(public member function)\fP - pubsync invokes sync() - \fI(public member function)\fP + pubsetbuf invokes setbuf() + \fI(public member function)\fP + pubseekoff invokes seekoff() + \fI(public member function)\fP + pubseekpos invokes seekpos() + \fI(public member function)\fP + pubsync invokes sync() + \fI(public member function)\fP .SH Get area - in_avail obtains the number of characters immediately available in the get area - \fI(public member function)\fP - advances the input sequence, then reads one character without - snextc advancing again - \fI(public member function)\fP - sbumpc reads one character from the input sequence and advances the sequence - \fI(public member function)\fP - stossc advances the input sequence as if by calling sbumpc() and discarding - \fB(deprecated)\fP the result - \fI(public member function)\fP - reads one character from the input sequence without advancing the - sgetc sequence - \fI(public member function)\fP - sgetn invokes xsgetn() - \fI(public member function)\fP + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function)\fP + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function)\fP + sgetn invokes xsgetn() + \fI(public member function)\fP .SH Put area - sputc writes one character to the put area and advances the next pointer - \fI(public member function)\fP - sputn invokes xsputn() - \fI(public member function)\fP + writes one character to the put area and advances the next + sputc pointer + \fI(public member function)\fP + sputn invokes xsputn() + \fI(public member function)\fP .SH Putback - sputbackc puts one character back in the input sequence - \fI(public member function)\fP - sungetc moves the next pointer in the input sequence back by one - \fI(public member function)\fP + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP .SH Protected member functions - constructor constructs a basic_streambuf object - \fI(protected member function)\fP - operator= replaces a basic_streambuf object - \fI(C++11)\fP \fI(protected member function)\fP - swap swaps two basic_streambuf objects - \fI(C++11)\fP \fI(protected member function)\fP + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP .SH Locales - imbue changes the associated locale - \fB[virtual]\fP \fI(virtual protected member function)\fP + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Positioning - setbuf replaces the buffer with user-defined array, if permitted - \fB[virtual]\fP \fI(virtual protected member function)\fP - seekoff repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both, using relative addressing - \fI(virtual protected member function)\fP - seekpos repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both using absolute addressing - \fI(virtual protected member function)\fP - sync synchronizes the buffers with the associated character sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output + \fB[virtual]\fP sequence, or both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output + \fB[virtual]\fP sequence, or both using absolute addressing + \fI(virtual protected member function)\fP + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Get area - showmanyc obtains the number of characters available for input in the associated - \fB[virtual]\fP input sequence, if known - \fI(virtual protected member function)\fP - underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function)\fP - uflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP and advances the next pointer - \fI(virtual protected member function)\fP - xsgetn reads multiple characters from the input sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP - eback returns a pointer to the beginning, current character and the end of - gptr the get area - egptr \fI(protected member function)\fP - gbump advances the next pointer in the input sequence - \fI(protected member function)\fP - repositions the beginning, next, and end pointers of the input - setg sequence - \fI(protected member function)\fP + showmanyc obtains the number of characters available for input in the + \fB[virtual]\fP associated input sequence, if known + \fI(virtual protected member function)\fP + underflow reads characters from the associated input sequence to the get + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + uflow reads characters from the associated input sequence to the get + \fB[virtual]\fP area and advances the next pointer + \fI(virtual protected member function)\fP + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + eback returns a pointer to the beginning, current character and the end + gptr of the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP .SH Put area - xsputn writes multiple characters to the output sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP - overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP - pbase returns a pointer to the beginning, current character and the end of - pptr the put area - epptr \fI(protected member function)\fP - pbump advances the next pointer of the output sequence - \fI(protected member function)\fP - repositions the beginning, next, and end pointers of the output - setp sequence - \fI(protected member function)\fP + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + pbase returns a pointer to the beginning, current character and the end + pptr of the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP .SH Putback - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function)\fP + pbackfail puts a character back into the input sequence, possibly modifying + \fB[virtual]\fP the input sequence + \fI(virtual protected member function)\fP + +.SH See also + + object type, capable of holding all information needed to control a C I/O + FILE stream + \fI(typedef)\fP diff --git a/man/std::basic_streambuf::basic_streambuf.3 b/man/std::basic_streambuf::basic_streambuf.3 index d5d474e7e..caf4b3077 100644 --- a/man/std::basic_streambuf::basic_streambuf.3 +++ b/man/std::basic_streambuf::basic_streambuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::basic_streambuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::basic_streambuf \- std::basic_streambuf::basic_streambuf + .SH Synopsis protected: \fB(1)\fP basic_streambuf(); @@ -35,12 +38,12 @@ .SH See also constructor constructs a basic_filebuf object - \fI(public member function of std::basic_filebuf)\fP - constructor constructs a basic_stringbuf object - \fI(public member function of std::basic_stringbuf)\fP + \fI(public member function of std::basic_filebuf)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) constructor constructs a strstreambuf object - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::eback,gptr,egptr.3 b/man/std::basic_streambuf::eback,gptr,egptr.3 index b93e82355..f20ec2496 100644 --- a/man/std::basic_streambuf::eback,gptr,egptr.3 +++ b/man/std::basic_streambuf::eback,gptr,egptr.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::eback,gptr,egptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::eback,gptr,egptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::eback,gptr,egptr \- std::basic_streambuf::eback,gptr,egptr + .SH Synopsis char_type* eback() const; \fB(1)\fP char_type* gptr() const; \fB(2)\fP @@ -10,7 +13,7 @@ 2) Returns the pointer to the current character (get pointer) in the get area. - 3) Returns the pointer to the end of the get area. + 3) Returns the pointer one past the end of the get area. .SH Parameters @@ -22,7 +25,13 @@ 2) The pointer to the current character (get pointer) in the get area. - 3) The pointer to the end of the get area. + 3) The pointer one past the end of the get area. + +.SH Notes + + While the names "gptr" and "egptr" refer to the get area, the name "eback" refers to + the end of the putback area: stepping backwards from gptr, characters can be put + back until eback. .SH Example @@ -33,8 +42,7 @@ pbase returns a pointer to the beginning, current character and the end of the put pptr area - epptr \fI(protected member function)\fP + epptr \fI(protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::gbump.3 b/man/std::basic_streambuf::gbump.3 index ed829cc9e..232521c5f 100644 --- a/man/std::basic_streambuf::gbump.3 +++ b/man/std::basic_streambuf::gbump.3 @@ -1,9 +1,13 @@ -.TH std::basic_streambuf::gbump 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::gbump 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::gbump \- std::basic_streambuf::gbump + .SH Synopsis + protected: void gbump( int count ); - Skips count characters in the get area. This is done by advancing the get pointer by - count characters. No checks are done for underflow. + Skips count characters in the get area. This is done by adding count to the get + pointer. No checks are done for underflow. .SH Parameters @@ -13,16 +17,31 @@ \fI(none)\fP +.SH Notes + + Because this function takes an int, it cannot manipulate buffers larger than + std::numeric_limits::max() characters (LWG issue 255). + .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether gbump can be implemented + LWG 59 C++98 as only add count + calling sbumpc count times (which may check to the get pointer + underflow) + .SH See also pbump advances the next pointer of the output sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::getloc.3 b/man/std::basic_streambuf::getloc.3 index 38d5305e7..c8569e47a 100644 --- a/man/std::basic_streambuf::getloc.3 +++ b/man/std::basic_streambuf::getloc.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::getloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::getloc \- std::basic_streambuf::getloc + .SH Synopsis std::locale getloc() const; @@ -24,8 +27,7 @@ .SH See also pubimbue invokes imbue() - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::in_avail.3 b/man/std::basic_streambuf::in_avail.3 index ce0605a7a..48555272e 100644 --- a/man/std::basic_streambuf::in_avail.3 +++ b/man/std::basic_streambuf::in_avail.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::in_avail 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::in_avail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::in_avail \- std::basic_streambuf::in_avail + .SH Synopsis std::streamsize in_avail(); @@ -30,12 +33,12 @@ .SH See also - showmanyc optionally provides the number of characters available for input from the - \fB[virtual]\fP file - \fI(virtual protected member function of std::basic_filebuf)\fP + optionally provides the number of characters available for input from the + showmanyc file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::operator=.3 b/man/std::basic_streambuf::operator=.3 index 2f79a0ca2..948add624 100644 --- a/man/std::basic_streambuf::operator=.3 +++ b/man/std::basic_streambuf::operator=.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::operator= \- std::basic_streambuf::operator= + .SH Synopsis basic_streambuf& operator=( const basic_streambuf& other ); \fI(since C++11)\fP @@ -14,7 +17,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -22,5 +25,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::overflow.3 b/man/std::basic_streambuf::overflow.3 index 759b424f8..bf2dc6d77 100644 --- a/man/std::basic_streambuf::overflow.3 +++ b/man/std::basic_streambuf::overflow.3 @@ -1,14 +1,18 @@ -.TH std::basic_streambuf::overflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::overflow \- std::basic_streambuf::overflow + .SH Synopsis - virtual int_type overflow( int_type ch = traits::eof() ); + protected: + virtual int_type overflow( int_type ch = Traits::eof() ); Ensures that there is space at the put area for at least one character by saving some initial subsequence of characters starting at pbase() to the output sequence - and updating the pointers to the output area (if needed). If ch is not Traits::eof() - (i.e. Traits::eq_int_type(ch, Traits::eof()) != true), it is either put to the - output area or directly saved to the output sequence. + and updating the pointers to the put area (if needed). If ch is not Traits::eof() + (i.e. Traits::eq_int_type(ch, Traits::eof()) != true), it is either put to the put + area or directly saved to the output sequence. - The function may update pptr, epptr and pback pointers to define the location to + The function may update pptr, epptr and pbase pointers to define the location to write more data. On failure, the function ensures that either pptr() == nullptr or pptr() == epptr. @@ -33,77 +37,74 @@ .SH Example - + // Run this code - #include #include - + #include + #include + // Buffer for std::ostream implemented by std::array - template - class ArrayedStreamBuffer : public std::basic_streambuf { - public: - + template + struct ArrayedStreamBuffer : std::basic_streambuf + { using Base = std::basic_streambuf; using char_type = typename Base::char_type; using int_type = typename Base::int_type; - - ArrayedStreamBuffer() : buffer_{} // value-initialize buffer_ to all zeroes + + ArrayedStreamBuffer() { - Base::setp(buffer_.begin(), buffer_.end()); // set std::basic_streambuf - // put area pointers to work with 'buffer_' + // put area pointers to work with 'buffer' + Base::setp(buffer.data(), buffer.data() + size); } - + int_type overflow(int_type ch) { std::cout << "overflow\\n"; return Base::overflow(ch); } - + void print_buffer() { - for (const auto& i: buffer_) { - if (i == 0) { - std::cout << "NULL"; - } else { + for (char_type i : buffer) + { + if (i == 0) + std::cout << "\\\\0"; + else std::cout << i; - } - std::cout << " "; + std::cout << ' '; } - std::cout << "\\n"; + std::cout << '\\n'; } - + private: - std::array buffer_; + std::array buffer{}; // value-initialize buffer }; - + int main() { ArrayedStreamBuffer<10> streambuf; std::ostream stream(&streambuf); - + stream << "hello"; streambuf.print_buffer(); - if (stream.good()) { + if (stream.good()) std::cout << "stream is good\\n"; - } - + stream << "world"; streambuf.print_buffer(); - if (stream.good()) { + if (stream.good()) std::cout << "stream is good\\n"; - } - + stream << "!"; streambuf.print_buffer(); - if (!stream.good()) { + if (!stream.good()) std::cout << "stream is not good\\n"; - } } .SH Output: - h e l l o NULL NULL NULL NULL NULL + h e l l o \\0 \\0 \\0 \\0 \\0 stream is good h e l l o w o r l d stream is good @@ -115,13 +116,15 @@ uflow reads characters from the associated input sequence to the get area and \fB[virtual]\fP advances the next pointer - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP overflow writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + overflow appends a character to the output sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) overflow appends a character to the output sequence, may reallocate or initially \fB[virtual]\fP allocate the buffer if dynamic and not frozen - \fI(virtual protected member function of std::strstreambuf)\fP + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::basic_streambuf::pbackfail.3 b/man/std::basic_streambuf::pbackfail.3 index 4f84eb480..e44f8b8d1 100644 --- a/man/std::basic_streambuf::pbackfail.3 +++ b/man/std::basic_streambuf::pbackfail.3 @@ -1,11 +1,19 @@ -.TH std::basic_streambuf::pbackfail 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbackfail \- std::basic_streambuf::pbackfail + .SH Synopsis protected: virtual int_type pbackfail( int_type c = Traits::eof() ); - This protected virtual function is called by the public functions sungetc() and - sputbackc() (which, in turn, are called by basic_istream::unget and - basic_istream::putback) when either: + This function can only be called if any of the following condition is satisfied: + + * gptr() is null, + * gptr() == eback(), or + * traits::eq(traits::to_char_type(c), gptr()[-1]) returns false. + + This function is called by the public functions sungetc() and sputbackc() (which, in + turn, are called by basic_istream::unget and basic_istream::putback) when either: 1) There is no putback position in the get area (pbackfail() is called with no arguments). In this situation, the purpose of pbackfail() is to back up the get area @@ -20,9 +28,9 @@ backing up the get area as in the first variant. The default base class version of this function does nothing and returns - Traits::eof() in all situations. This function is overloaded by the derived classes: + Traits::eof() in all situations. This function is overridden by the derived classes: basic_stringbuf::pbackfail, basic_filebuf::pbackfail, strstreambuf::pbackfail, and - is expected to be overloaded by user-defined and third-party library stream classes. + is expected to be overridden by user-defined and third-party library stream classes. .SH Parameters @@ -38,20 +46,33 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct + behavior + the calling condition corrected to + LWG 32 C++98 'traits::eq(*gptr(),traits::to_char_type(c)) match + returns false' did not match the description of the + sputbackc() description + .SH See also - pbackfail backs out the input sequence to unget a character, not affecting the - \fB[virtual]\fP associated file - \fI(virtual protected member function of std::basic_filebuf)\fP + backs out the input sequence to unget a character, not affecting the + pbackfail associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + pbackfail puts a character back into the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) pbackfail backs out the input sequence to unget a character - \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP sungetc moves the next pointer in the input sequence back by one - \fI(public member function)\fP + \fI(public member function)\fP sputbackc puts one character back in the input sequence - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::pbase,std::basic_streambuf::pptr,.3 b/man/std::basic_streambuf::pbase,std::basic_streambuf::pptr,.3 new file mode 100644 index 000000000..16799c237 --- /dev/null +++ b/man/std::basic_streambuf::pbase,std::basic_streambuf::pptr,.3 @@ -0,0 +1,46 @@ +.TH std::basic_streambuf::pbase,std::basic_streambuf::pptr, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbase,std::basic_streambuf::pptr, \- std::basic_streambuf::pbase,std::basic_streambuf::pptr, + +.SH Synopsis + + protected: \fB(1)\fP + char_type* pbase() const; + protected: \fB(2)\fP + char_type* pptr() const; + protected: \fB(3)\fP + char_type* epptr() const; + + Returns pointers defining the put area. + + 1) Returns the pointer to the beginning ("base") of the put area. + + 2) Returns the pointer to the current character (put pointer) in the put area. + + 3) Returns the pointer one past the end of the put area. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The pointer to the beginning of the put area. + + 2) The pointer to the current character (put pointer) in the put area. + + 3) The pointer one past the end of the put area. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + eback returns a pointer to the beginning, current character and the end of the get + gptr area + egptr \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 b/man/std::basic_streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 deleted file mode 100644 index eebfcabcf..000000000 --- a/man/std::basic_streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH std::basic_streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - char_type* pbase() const; \fB(1)\fP - char_type* pptr() const; \fB(2)\fP - char_type* epptr() const; \fB(3)\fP - - Returns pointers defining the put area. - - 1) Returns the pointer to the beginning of the put area. - - 2) Returns the pointer to the current character (put pointer) in the put area. - - 3) Returns the pointer to the end of the put area. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - 1) The pointer to the beginning of the put area. - - 2) The pointer to the current character (put pointer) in the put area. - - 3) The pointer to the end of the put area. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - eback returns a pointer to the beginning, current character and the end of the get - gptr area - egptr \fI(protected member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::basic_streambuf::pbump.3 b/man/std::basic_streambuf::pbump.3 index 109c18d90..cc71e077b 100644 --- a/man/std::basic_streambuf::pbump.3 +++ b/man/std::basic_streambuf::pbump.3 @@ -1,5 +1,9 @@ -.TH std::basic_streambuf::pbump 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::pbump 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbump \- std::basic_streambuf::pbump + .SH Synopsis + protected: void pbump( int count ); Repositions the put pointer (pptr()) by count characters, where count may be @@ -18,23 +22,29 @@ \fI(none)\fP +.SH Notes + + Because this function takes an int, it cannot manipulate buffers larger than + std::numeric_limits::max() characters (LWG issue 255). + .SH Example - + // Run this code + #include #include #include - #include - + struct showput_streambuf : std::filebuf { using std::filebuf::pbump; // expose protected - std::string showput() const { + std::string showput() const + { return std::string(pbase(), pptr()); } }; - + int main() { showput_streambuf mybuf; @@ -54,4 +64,4 @@ .SH See also gbump advances the next pointer in the input sequence - \fI(protected member function)\fP + \fI(protected member function)\fP diff --git a/man/std::basic_streambuf::pubimbue,std::basic_streambuf::imbue.3 b/man/std::basic_streambuf::pubimbue,std::basic_streambuf::imbue.3 index 3d184ddee..c84c38d7a 100644 --- a/man/std::basic_streambuf::pubimbue,std::basic_streambuf::imbue.3 +++ b/man/std::basic_streambuf::pubimbue,std::basic_streambuf::imbue.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::pubimbue,std::basic_streambuf::imbue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::pubimbue,std::basic_streambuf::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubimbue,std::basic_streambuf::imbue \- std::basic_streambuf::pubimbue,std::basic_streambuf::imbue + .SH Synopsis std::locale pubimbue( const std::locale& loc ); \fB(1)\fP protected: \fB(2)\fP @@ -6,7 +9,7 @@ Changes the associated locale. - 1) Calls imbue(loc) of the most derived class + 1) Sets loc as the associated locale. Calls imbue(loc) of the most derived class 2) The base class version of this function has no effect. The derived classes may override this function in order to be informed about the changes of the locale. The @@ -28,8 +31,7 @@ .SH See also getloc obtains a copy of the associated locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::pubseekoff,.3 b/man/std::basic_streambuf::pubseekoff,.3 new file mode 100644 index 000000000..6fddf66cc --- /dev/null +++ b/man/std::basic_streambuf::pubseekoff,.3 @@ -0,0 +1,84 @@ +.TH std::basic_streambuf::pubseekoff, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubseekoff, \- std::basic_streambuf::pubseekoff, + +.SH Synopsis + + pos_type pubseekoff( off_type off, std::ios_base::seekdir dir, + std::ios_base::openmode which = ios_base::in | \fB(1)\fP + ios_base::out ); + protected: + + virtual pos_type seekoff( off_type off, std::ios_base::seekdir dir, \fB(2)\fP + + std::ios_base::openmode which = ios_base::in | + ios_base::out ); + + Sets the position indicator of the input and/or output sequence relative to some + other position. + + 1) Calls seekoff(off, dir, which) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow relative positioning of the position indicator. + +.SH Parameters + + off - relative position to set the position indicator to. + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Note + + Not all combinations of parameters may be valid, see the derived versions of seekoff + for details. + +.SH Return value + + 1) The return value of seekoff(off, dir, which) + 2) The resulting absolute position as defined by the position indicator. The base + class version returns pos_type(off_type(-1)). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the base class version of seekoff + LWG 55 C++98 returned returns pos_type(off_type(-1)) + an undefined invalid stream + position + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_streambuf::pubseekoff,std::basic_streambuf::seekoff.3 b/man/std::basic_streambuf::pubseekoff,std::basic_streambuf::seekoff.3 deleted file mode 100644 index 78e870e3a..000000000 --- a/man/std::basic_streambuf::pubseekoff,std::basic_streambuf::seekoff.3 +++ /dev/null @@ -1,63 +0,0 @@ -.TH std::basic_streambuf::pubseekoff,std::basic_streambuf::seekoff 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - pos_type pubseekoff( off_type off, ios_base::seekdir dir, \fB(1)\fP - ios_base::openmode which = ios_base::in | ios_base::out ); - protected: - - virtual pos_type seekoff( off_type off, ios_base::seekdir dir, \fB(2)\fP - - ios_base::openmode which = ios_base::in | - ios_base::out ); - - Sets the position indicator of the input and/or output sequence relative to some - other position. - - 1) Calls seekoff(off, dir, which) of the most derived class - - 2) The base class version of this function has no effect. The derived classes may - override this function to allow relative positioning of the position indicator. - -.SH Parameters - - off - relative position to set the position indicator to. - defines base position to apply the relative offset to. It can be one of the - following constants: - - dir - Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator - defines which of the input and/or output sequences to affect. It can be one - or a combination of the following constants: - which - - Constant Explanation - in affect the input sequence - out affect the output sequence - -.SH Note - - Not all combinations of parameters are valid. All the sequences denoted by which - must match the sequences denoted by the instantiation of the basic_streambuf. When - modifying both the input and output sequences together, dir may only be beg or end. - Otherwise, the positioning operation fails, and pos_type(off_type(-1)) is returned. - -.SH Return value - - 1) The return value of seekoff(off, dir, which) - - 2) The resulting absolute position as defined by the position indicator. The base - class version returns pos_type(off_type(-1)). - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - pubseekpos invokes seekpos() - \fI(public member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::basic_streambuf::pubseekpos,.3 b/man/std::basic_streambuf::pubseekpos,.3 new file mode 100644 index 000000000..ed46050b4 --- /dev/null +++ b/man/std::basic_streambuf::pubseekpos,.3 @@ -0,0 +1,72 @@ +.TH std::basic_streambuf::pubseekpos, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubseekpos, \- std::basic_streambuf::pubseekpos, + +.SH Synopsis + + pos_type pubseekpos( pos_type pos, + std::ios_base::openmode which = std::ios_base::in | \fB(1)\fP + std::ios_base::out ); + protected: + + virtual pos_type seekpos( pos_type pos, \fB(2)\fP + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Sets the position indicator of the input and/or output sequence to an absolute + position. + + 1) Calls seekpos(pos, which) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow absolute positioning of the position indicator. + +.SH Parameters + + pos - absolute position to set the position indicator to + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + 1) The return value of seekpos(pos, which). + 2) The resulting absolute position as defined by the position indicator. The base + class version returns pos_type(off_type(-1)). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the base class version of seekpos + LWG 55 C++98 returned returns pos_type(off_type(-1)) + an undefined invalid stream + position + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_streambuf::pubseekpos,std::basic_streambuf::seekpos.3 b/man/std::basic_streambuf::pubseekpos,std::basic_streambuf::seekpos.3 deleted file mode 100644 index 3e1188bd1..000000000 --- a/man/std::basic_streambuf::pubseekpos,std::basic_streambuf::seekpos.3 +++ /dev/null @@ -1,49 +0,0 @@ -.TH std::basic_streambuf::pubseekpos,std::basic_streambuf::seekpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - pos_type pubseekpos( pos_type pos, \fB(1)\fP - ios_base::openmode which = ios_base::in | ios_base::out ); - protected: - - virtual pos_type seekpos( pos_type pos, \fB(2)\fP - - ios_base::openmode which = ios_base::in | - ios_base::out); - - Sets the position indicator of the input and/or output sequence to an absolute - position. - - 1) Calls seekpos(pos, which) of the most derived class - - 2) The base class version of this function has no effect. The derived classes may - override this function to allow absolute positioning of the position indicator. - -.SH Parameters - - pos - absolute position to set the position indicator to. - defines which of the input and/or output sequences to affect. It can be one - or a combination of the following constants: - which - - Constant Explanation - in affect the input sequence - out affect the output sequence - -.SH Return value - - 1) The return value of seekpos(pos, which) - - 2) The resulting absolute position as defined by the position indicator. The base - class version returns pos_type(off_type(-1)). - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - pubseekoff invokes seekoff() - \fI(public member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 b/man/std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 index 7a10c5210..96e049f19 100644 --- a/man/std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 +++ b/man/std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 @@ -1,11 +1,15 @@ -.TH std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf \- std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf + .SH Synopsis - basic_streambuf* pubsetbuf( char_type* s, std::streamsize n ) \fB(1)\fP + public: \fB(1)\fP + basic_streambuf* pubsetbuf( char_type* s, std::streamsize n ) protected: virtual basic_streambuf* setbuf( char_type* s, std::streamsize n \fB(2)\fP ) - 1) Calls setbuf(s, n) of the most derived class + 1) Calls setbuf(s, n) of the most derived class. 2) The base class version of this function has no effect. The derived classes may override this function to allow removal or replacement of the controlled character sequence (the buffer) with a user-provided array, or for any other @@ -13,49 +17,65 @@ .SH Parameters - s - pointer to the first byte in the user-provided buffer - n - the number of bytes in the user-provided buffer + s - pointer to the first CharT in the user-provided buffer + n - the number of CharT elements in the user-provided buffer .SH Return value - *this + 1) The return value of setbuf(s, n). + 2) this .SH Example - provide a 10k buffer for reading. On linux, the strace utility may be used to - observe the actual number of bytes read + Provides a 10k buffer for reading. On linux, the strace utility may be used to + observe the actual number of bytes read. + - // Run this code #include #include #include - + int main() { int cnt = 0; std::ifstream file; - char buf[10241]; - + char buf[1024 * 10 + 1]; + file.rdbuf()->pubsetbuf(buf, sizeof buf); - + file.open("/usr/share/dict/words"); - - for (std::string line; getline(file, line);) { - cnt++; - } - + + for (std::string line; getline(file, line);) + ++cnt; + std::cout << cnt << '\\n'; } +.SH Possible output: + + 356010 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default behavior of setbuf was only specified as no-op + LWG 158 C++98 specified for all cases + if gptr() is not null and not equal to egptr() + .SH See also setbuf attempts to replace the controlled character sequence with an array - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) setbuf provides user-supplied buffer or turns this filebuf unbuffered - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + setbuf attempts to replace the controlled character sequence with an array - \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP setbuf sets the buffer for a file stream - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::basic_streambuf::pubsync,std::basic_streambuf::sync.3 b/man/std::basic_streambuf::pubsync,std::basic_streambuf::sync.3 index c846f7378..d35616600 100644 --- a/man/std::basic_streambuf::pubsync,std::basic_streambuf::sync.3 +++ b/man/std::basic_streambuf::pubsync,std::basic_streambuf::sync.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::pubsync,std::basic_streambuf::sync 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::pubsync,std::basic_streambuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubsync,std::basic_streambuf::sync \- std::basic_streambuf::pubsync,std::basic_streambuf::sync + .SH Synopsis int pubsync(); \fB(1)\fP protected: \fB(2)\fP @@ -37,10 +40,10 @@ .SH See also sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP sync writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP -.SH Category: +.SH Category: * Todo no example diff --git a/man/std::basic_streambuf::sbumpc,std::basic_streambuf::stossc.3 b/man/std::basic_streambuf::sbumpc,std::basic_streambuf::stossc.3 new file mode 100644 index 000000000..b93e84b61 --- /dev/null +++ b/man/std::basic_streambuf::sbumpc,std::basic_streambuf::stossc.3 @@ -0,0 +1,38 @@ +.TH std::basic_streambuf::sbumpc,std::basic_streambuf::stossc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sbumpc,std::basic_streambuf::stossc \- std::basic_streambuf::sbumpc,std::basic_streambuf::stossc + +.SH Synopsis + int_type sbumpc(); \fB(1)\fP + void stossc(); \fB(2)\fP (deprecated in C++98) + (removed in C++17) + + Reads one character and advances the input sequence by one character. + + 1) If the input sequence read position is not available, returns uflow(). Otherwise + returns Traits::to_int_type(*gptr()). + 2) Same as \fB(1)\fP, but discards the result. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The value of the character pointed to by the get pointer, or Traits::eof() if the + read position is not available. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function)\fP + snextc advances the input sequence, then reads one character without advancing again + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_streambuf::sbumpc.3 b/man/std::basic_streambuf::sbumpc.3 deleted file mode 100644 index e02f4cf1e..000000000 --- a/man/std::basic_streambuf::sbumpc.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::basic_streambuf::sbumpc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - int_type sbumpc(); - - Reads one character and advances the input sequence by one character. - - If the input sequence read position is not available, returns uflow(). Otherwise - returns Traits::to_int_type(*gptr()). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The value of the character pointed to by the get pointer, or Traits::eof() if the - read position is not available. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - sgetc reads one character from the input sequence without advancing the sequence - \fI(public member function)\fP - snextc advances the input sequence, then reads one character without advancing again - \fI(public member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::basic_streambuf::setg.3 b/man/std::basic_streambuf::setg.3 index 7b9bc990a..3d6119311 100644 --- a/man/std::basic_streambuf::setg.3 +++ b/man/std::basic_streambuf::setg.3 @@ -1,9 +1,13 @@ -.TH std::basic_streambuf::setg 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::setg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::setg \- std::basic_streambuf::setg + .SH Synopsis + protected: void setg( char_type* gbeg, char_type* gcurr, char_type* gend ); Sets the values of the pointers defining the get area. Specifically, after the call - eback() == gbeg, gptr() == gcurr, egptr() == gend + eback() == gbeg, gptr() == gcurr, egptr() == gend. .SH Parameters @@ -17,38 +21,47 @@ .SH Example - - + + // Run this code #include #include - - class null_filter_buf : public std::streambuf { + + class null_filter_buf : public std::streambuf + { std::streambuf* src; char ch; // single-byte buffer protected: - int underflow() { - while( (ch= src->sbumpc()) == '\\0') ; // skip zeroes - setg(&ch, &ch, &ch+1); // make one read position available - return ch; // may return EOF + int underflow() + { + traits_type::int_type i; + while ((i = src->sbumpc()) == '\\0') + ; // skip zeroes + if (!traits_type::eq_int_type(i, traits_type::eof())) + { + ch = traits_type::to_char_type(i); + setg(&ch, &ch, &ch+1); // make one read position available + } + return i; } public: - null_filter_buf(std::streambuf* buf) : src(buf) { - setg(&ch, &ch+1, &ch+1); // buffer is initially full + null_filter_buf(std::streambuf* buf) : src(buf) + { + setg(&ch, &ch + 1, &ch + 1); // buffer is initially full } }; - + void filtered_read(std::istream& in) { std::streambuf* orig = in.rdbuf(); null_filter_buf buf(orig); in.rdbuf(&buf); - for(char c; in.get(c); ) - std::cout << c; + for (char c; in.get(c);) + std::cout << c; in.rdbuf(orig); } - + int main() { char a[] = "This i\\0s \\0an e\\0\\0\\0xample"; @@ -63,4 +76,4 @@ .SH See also setp repositions the beginning, next, and end pointers of the output sequence - \fI(protected member function)\fP + \fI(protected member function)\fP diff --git a/man/std::basic_streambuf::setp.3 b/man/std::basic_streambuf::setp.3 index dd60739ea..e0abc3f69 100644 --- a/man/std::basic_streambuf::setp.3 +++ b/man/std::basic_streambuf::setp.3 @@ -1,9 +1,13 @@ -.TH std::basic_streambuf::setp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::setp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::setp \- std::basic_streambuf::setp + .SH Synopsis + protected: void setp( char_type* pbeg, char_type* pend ); Sets the values of the pointers defining the put area. Specifically, after the call - pbase() == pbeg, pptr() == pbeg, epptr() == pend + pbase() == pbeg, pptr() == pbeg, epptr() == pend. .SH Parameters @@ -16,59 +20,59 @@ .SH Example - + // Run this code - #include #include - + #include + #include + // Buffer for std::ostream implemented by std::array - template - class ArrayedStreamBuffer : public std::basic_streambuf + template + struct ArrayedStreamBuffer : std::basic_streambuf { - public: using Base = std::basic_streambuf; using char_type = typename Base::char_type; - - ArrayedStreamBuffer() : buffer_{} // value-initialize buffer_ to all zeroes + + ArrayedStreamBuffer() { - Base::setp(buffer_.begin(), buffer_.end()); // set std::basic_streambuf - // put area pointers to work with 'buffer_' + // put area pointers to work with 'buffer' + Base::setp(buffer.data(), buffer.data() + size); } - + void print_buffer() { - for (const auto& i: buffer_) { - if (i == 0) { - std::cout << "NULL"; - } else { + for (char_type i : buffer) + { + if (i == 0) + std::cout << "\\\\0"; + else std::cout << i; - } - std::cout << " "; + std::cout << ' '; } - std::cout << "\\n"; + std::cout << '\\n'; } - + private: - std::array buffer_; + std::array buffer{}; // value-initialize buffer }; - + int main() { ArrayedStreamBuffer<10> streambuf; std::ostream stream(&streambuf); - + stream << "hello"; stream << ","; - + streambuf.print_buffer(); } .SH Output: - h e l l o , NULL NULL NULL NULL + h e l l o , \\0 \\0 \\0 \\0 .SH See also setg repositions the beginning, next, and end pointers of the input sequence - \fI(protected member function)\fP + \fI(protected member function)\fP diff --git a/man/std::basic_streambuf::sgetc.3 b/man/std::basic_streambuf::sgetc.3 index 3df740ebf..d51db4251 100644 --- a/man/std::basic_streambuf::sgetc.3 +++ b/man/std::basic_streambuf::sgetc.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::sgetc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::sgetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sgetc \- std::basic_streambuf::sgetc + .SH Synopsis int_type sgetc(); @@ -17,18 +20,18 @@ .SH Example - + // Run this code #include #include - + int main() { std::stringstream stream("Hello, world"); - std::cout << "sgetc() returned '" << (char)stream.rdbuf()->sgetc() << "'\\n" - << "peek() returned '" << (char)stream.peek() << "'\\n" - << "get() returned '" << (char)stream.get() << "'\\n"; + std::cout << "sgetc() returned '" << (char)stream.rdbuf()->sgetc() << "'\\n"; + std::cout << "peek() returned '" << (char)stream.peek() << "'\\n"; + std::cout << "get() returned '" << (char)stream.get() << "'\\n"; } .SH Output: @@ -39,7 +42,9 @@ .SH See also - sbumpc reads one character from the input sequence and advances the sequence - \fI(public member function)\fP - snextc advances the input sequence, then reads one character without advancing again - \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function)\fP diff --git a/man/std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn.3 b/man/std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn.3 index b377361bd..4efc4c3c8 100644 --- a/man/std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn.3 +++ b/man/std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn \- std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn + .SH Synopsis std::streamsize sgetn( char_type* s, std::streamsize count ); \fB(1)\fP protected: \fB(2)\fP @@ -8,15 +11,25 @@ 2) Reads count characters from the input sequence and stores them into a character array pointed to by s. The characters are read as if by repeated calls to sbumpc(). That is, if less than count characters are immediately available, the function calls - uflow() to provide more until traits::eof() is returned. + uflow() to provide more until Traits::eof() is returned. + Classes derived from std::basic_streambuf are permitted to provide more efficient + implementations of this function. .SH Parameters - \fI(none)\fP + s - pointer to the beginning of a char_type array + count - maximum number of characters to read. .SH Return value - The number of characters successfully read. + The number of characters successfully read. If it is less than count the input + sequence has reached the end. + +.SH Notes + + The rule about "more efficient implementations" permits bulk I/O without + intermediate buffering: that's how std::ifstream::read simply passes the pointer to + the POSIX read() system call in some implementations of iostreams .SH Example @@ -26,8 +39,7 @@ .SH See also sputn invokes xsputn() - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::showmanyc.3 b/man/std::basic_streambuf::showmanyc.3 index a593a65c7..86c6f8ff7 100644 --- a/man/std::basic_streambuf::showmanyc.3 +++ b/man/std::basic_streambuf::showmanyc.3 @@ -1,11 +1,14 @@ -.TH std::basic_streambuf::showmanyc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::showmanyc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::showmanyc \- std::basic_streambuf::showmanyc + .SH Synopsis protected: virtual std::streamsize showmanyc(); Estimates the number of characters available for input in the associated character - sequence. underflow() is guaranteed not to return Traits::eof() until at least that - many characters are extracted. + sequence. underflow() is guaranteed not to return Traits::eof() or throw an + exception until at least that many characters are extracted. .SH Parameters @@ -16,24 +19,40 @@ The number of characters that are certainly available in the associated character sequence, or -1 if showmanyc can determine, without blocking, that no characters are available. If showmanyc returns -1, underflow() and uflow() will definitely return - Traits::eof. + Traits::eof or throw. The base class version returns 0, which has the meaning of "unsure if there are characters available in the associated sequence". +.SH Notes + + The name of this function stands for "stream: how many characters?", so it is + pronounced "S how many C", rather than "show many C". + .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + underflow() is guaranteed not to extended the guarantee to allow + LWG 159 C++98 fail until at least + at least showmanyc() characters showmanyc() characters to be + are supplied extracted + .SH See also in_avail obtains the number of characters immediately available in the get area - \fI(public member function)\fP - showmanyc optionally provides the number of characters available for input from the - \fB[virtual]\fP file - \fI(virtual protected member function of std::basic_filebuf)\fP + \fI(public member function)\fP + optionally provides the number of characters available for input from the + showmanyc file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP -.SH Category: +.SH Category: * Todo no example diff --git a/man/std::basic_streambuf::snextc.3 b/man/std::basic_streambuf::snextc.3 index 4ee7ca2c9..222009afc 100644 --- a/man/std::basic_streambuf::snextc.3 +++ b/man/std::basic_streambuf::snextc.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::snextc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::snextc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::snextc \- std::basic_streambuf::snextc + .SH Synopsis int_type snextc(); @@ -25,11 +28,12 @@ .SH See also - sgetc reads one character from the input sequence without advancing the sequence - \fI(public member function)\fP - sbumpc reads one character from the input sequence and advances the sequence - \fI(public member function)\fP + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::sputbackc.3 b/man/std::basic_streambuf::sputbackc.3 index 9c5d54453..f2e362010 100644 --- a/man/std::basic_streambuf::sputbackc.3 +++ b/man/std::basic_streambuf::sputbackc.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::sputbackc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::sputbackc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputbackc \- std::basic_streambuf::sputbackc + .SH Synopsis int_type sputbackc( char_type c ); @@ -17,7 +20,7 @@ .SH Parameters - \fI(none)\fP + c - character to put back .SH Return value @@ -30,25 +33,26 @@ .SH Example - + // Run this code #include #include - + int main() { - std::stringstream s("abcdef"); // gptr() poitns to 'a' + std::stringstream s("abcdef"); // gptr() points to 'a' in "abcdef" std::cout << "Before putback, string holds " << s.str() << '\\n'; - char c1 = s.get(); // c = 'a', gptr() now points to 'b' - char c2 = s.rdbuf()->sputbackc('z'); // same as s.putback('c') - // gptr() now points to 'z' + char c1 = s.get(); // c1 = 'a', gptr() now points to 'b' in "abcdef" + char c2 = s.rdbuf()->sputbackc('z'); // same as s.putback('z') + // gptr() now points to 'z' in "zbcdef" std::cout << "After putback, string holds " << s.str() << '\\n'; - char c3 = s.get(); // c3 = 'z', gptr() now points to 'b' - std::cout << c1 << c2 << c3 << '\\n'; - - s.rdbuf()->sputbackc('b'); // back to 'b' - s.rdbuf()->sputbackc('z'); // back to 'z' + char c3 = s.get(); // c3 = 'z', gptr() now points to 'b' in "zbcdef" + char c4 = s.get(); // c4 = 'b', gptr() now points to 'c' in "zbcdef" + std::cout << c1 << c2 << c3 << c4 << '\\n'; + + s.rdbuf()->sputbackc('b'); // gptr() now points to 'b' in "zbcdef" + s.rdbuf()->sputbackc('z'); // gptr() now points to 'z' in "zbcdef" int eof = s.rdbuf()->sputbackc('x'); // nothing to unget: pbackfail() fails if (eof == EOF) std::cout << "No room to putback after 'z'\\n"; @@ -58,12 +62,12 @@ Before putback, string holds abcdef After putback, string holds zbcdef - azz + azzb No room to putback after 'z' .SH See also sungetc moves the next pointer in the input sequence back by one - \fI(public member function)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_streambuf::sputc.3 b/man/std::basic_streambuf::sputc.3 index da22d99ba..dbfddb2b6 100644 --- a/man/std::basic_streambuf::sputc.3 +++ b/man/std::basic_streambuf::sputc.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::sputc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::sputc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputc \- std::basic_streambuf::sputc + .SH Synopsis int_type sputc( char_type ch ); @@ -13,19 +16,19 @@ .SH Return value - The written character, converted to int_type with Traits::to_int_type(ch). on + The written character, converted to int_type with Traits::to_int_type(ch) on success. Traits::eof() (as returned by overflow()) on failure. .SH Example - + // Run this code #include #include - + int main() { std::ostringstream s; @@ -40,4 +43,4 @@ .SH See also sputn invokes xsputn() - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_streambuf::sputn,std::basic_streambuf::xsputn.3 b/man/std::basic_streambuf::sputn,std::basic_streambuf::xsputn.3 index 791310d5d..fe40c149b 100644 --- a/man/std::basic_streambuf::sputn,std::basic_streambuf::xsputn.3 +++ b/man/std::basic_streambuf::sputn,std::basic_streambuf::xsputn.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::sputn,std::basic_streambuf::xsputn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::sputn,std::basic_streambuf::xsputn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputn,std::basic_streambuf::xsputn \- std::basic_streambuf::sputn,std::basic_streambuf::xsputn + .SH Synopsis std::streamsize sputn( const char_type* s, std::streamsize count ); \fB(1)\fP protected: \fB(2)\fP @@ -10,8 +13,8 @@ to sputc(). Writing stops when either count characters are written or a call to sputc() would have returned Traits::eof(). - If the put area becomes full (pptr() == epptr()), this function may call overflow(), - or achieve the effect of calling overflow() by some other, unspecified, means. + If the put area becomes full (pptr() == epptr()), it is unspecified whether + overflow() is actually called or its effect is achieved by other means. .SH Parameters @@ -21,14 +24,20 @@ The number of characters successfully written. +.SH Notes + + "achieved by other means" permits bulk I/O without intermediate buffering: that is + how std::ofstream::write() simply passes the pointer to the suitable system call in + some implementations. + .SH Example - + // Run this code #include #include - + int main() { std::ostringstream s1; @@ -36,7 +45,7 @@ s1 << '\\n'; std::cout << "The call to sputn() returned " << sz << '\\n' << "The output sequence contains " << s1.str(); - + std::istringstream s2; sz = s2.rdbuf()->sputn("This is a test", 14); std::cout << "The call to sputn() on an input stream returned " << sz << '\\n'; @@ -48,7 +57,16 @@ The output sequence contains This is a test The call to sputn() on an input stream returned 0 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 565 C++98 xsputn() always called overflow() if it does not actually need to + pptr() == epptr() be called + .SH See also sgetn invokes xsgetn() - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_streambuf::sungetc.3 b/man/std::basic_streambuf::sungetc.3 index c8aa09e68..c2e60e2b9 100644 --- a/man/std::basic_streambuf::sungetc.3 +++ b/man/std::basic_streambuf::sungetc.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::sungetc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::sungetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sungetc \- std::basic_streambuf::sungetc + .SH Synopsis int_type sungetc(); @@ -26,21 +29,21 @@ .SH Example - + // Run this code #include #include - + int main() { - std::stringstream s("abcdef"); // gptr() poitns to 'a' + std::stringstream s("abcdef"); // gptr() points to 'a' char c1 = s.get(); // c = 'a', gptr() now points to 'b' char c2 = s.rdbuf()->sungetc(); // same as s.unget(): gptr() points to 'a' again char c3 = s.get(); // c3 = 'a', gptr() now points to 'b' char c4 = s.get(); // c4 = 'b', gptr() now points to 'c' std::cout << c1 << c2 << c3 << c4 << '\\n'; - + s.rdbuf()->sungetc(); // back to 'b' s.rdbuf()->sungetc(); // back to 'a' int eof = s.rdbuf()->sungetc(); // nothing to unget: pbackfail() fails @@ -56,6 +59,6 @@ .SH See also sputbackc puts one character back in the input sequence - \fI(public member function)\fP + \fI(public member function)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::basic_streambuf::swap.3 b/man/std::basic_streambuf::swap.3 index c1fefe260..ff8261ca1 100644 --- a/man/std::basic_streambuf::swap.3 +++ b/man/std::basic_streambuf::swap.3 @@ -1,4 +1,7 @@ -.TH std::basic_streambuf::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::swap \- std::basic_streambuf::swap + .SH Synopsis void swap( basic_streambuf& other ); \fI(since C++11)\fP @@ -14,7 +17,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -22,5 +25,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::uflow.3 b/man/std::basic_streambuf::uflow.3 index 1e95a9e55..07f656738 100644 --- a/man/std::basic_streambuf::uflow.3 +++ b/man/std::basic_streambuf::uflow.3 @@ -1,5 +1,9 @@ -.TH std::basic_streambuf::uflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::uflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::uflow \- std::basic_streambuf::uflow + .SH Synopsis + protected: virtual int_type uflow(); Ensures that at least one character is available in the input area by updating the @@ -40,10 +44,9 @@ .SH See also underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_streambuf::underflow.3 b/man/std::basic_streambuf::underflow.3 index 525a9e88c..29e00974b 100644 --- a/man/std::basic_streambuf::underflow.3 +++ b/man/std::basic_streambuf::underflow.3 @@ -1,5 +1,9 @@ -.TH std::basic_streambuf::underflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::underflow \- std::basic_streambuf::underflow + .SH Synopsis + protected: virtual int_type underflow(); Ensures that at least one character is available in the input area by updating the @@ -32,38 +36,47 @@ .SH Example - - + + // Run this code #include #include - - class null_filter_buf : public std::streambuf { + + class null_filter_buf : public std::streambuf + { std::streambuf* src; char ch; // single-byte buffer protected: - int underflow() { - while( (ch= src->sbumpc()) == '\\0') ; // skip zeroes - setg(&ch, &ch, &ch+1); // make one read position available - return ch; // may return EOF + int underflow() + { + traits_type::int_type i; + while ((i = src->sbumpc()) == '\\0') + ; // skip zeroes + if (!traits_type::eq_int_type(i, traits_type::eof())) + { + ch = traits_type::to_char_type(i); + setg(&ch, &ch, &ch+1); // make one read position available + } + return i; } public: - null_filter_buf(std::streambuf* buf) : src(buf) { - setg(&ch, &ch+1, &ch+1); // buffer is initially full + null_filter_buf(std::streambuf* buf) : src(buf) + { + setg(&ch, &ch + 1, &ch + 1); // buffer is initially full } }; - + void filtered_read(std::istream& in) { std::streambuf* orig = in.rdbuf(); null_filter_buf buf(orig); in.rdbuf(&buf); - for(char c; in.get(c); ) - std::cout << c; + for (char c; in.get(c);) + std::cout << c; in.rdbuf(orig); } - + int main() { char a[] = "This i\\0s \\0an e\\0\\0\\0xample"; @@ -79,13 +92,15 @@ uflow reads characters from the associated input sequence to the get area and \fB[virtual]\fP advances the next pointer - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + underflow returns the next character available in the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) underflow reads a character from the input sequence without advancing the next \fB[virtual]\fP pointer - \fI(virtual protected member function of std::strstreambuf)\fP + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::basic_streambuf::~basic_streambuf.3 b/man/std::basic_streambuf::~basic_streambuf.3 index 707f6d92b..1e6a28839 100644 --- a/man/std::basic_streambuf::~basic_streambuf.3 +++ b/man/std::basic_streambuf::~basic_streambuf.3 @@ -1,9 +1,12 @@ -.TH std::basic_streambuf::~basic_streambuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_streambuf::~basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::~basic_streambuf \- std::basic_streambuf::~basic_streambuf + .SH Synopsis virtual ~basic_streambuf(); - This destruction is empty: the members of this basic_streambuf (the pointers and the - locale) are destructed in accordance with the usual object destruction sequence + This destructor has no effect: the members of this basic_streambuf (the pointers and + the locale) are destructed in accordance with the usual object destruction sequence after this destructor returns. However, since it is declared public virtual, it allows the objects that are derived from std::basic_streambuf to be deleted through a pointer to base class. @@ -14,19 +17,21 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::filebuf* fbp = new std::filebuf; fbp->open("test.txt", std::ios_base::out); fbp->sputn("Hello\\n", 6); + std::streambuf* sbp = fbp; delete sbp; // the file is closed, output flushed and written + std::ifstream f("test.txt"); std::cout << f.rdbuf(); // proof } @@ -35,7 +40,16 @@ Hello + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 54 C++98 the effect of the destructor was not specified as no effect + specified + .SH See also constructor constructs a basic_streambuf object - \fI(protected member function)\fP + \fI(protected member function)\fP diff --git a/man/std::basic_string.3 b/man/std::basic_string.3 index 999a53040..ba00dc78d 100644 --- a/man/std::basic_string.3 +++ b/man/std::basic_string.3 @@ -1,34 +1,74 @@ -.TH std::basic_string 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string \- std::basic_string + .SH Synopsis Defined in header template< class CharT, - class Traits = std::char_traits, + class Traits = std::char_traits, \fB(1)\fP class Allocator = std::allocator > class basic_string; + namespace pmr { + + template< + class CharT, + class Traits = std::char_traits \fB(2)\fP \fI(since C++17)\fP + > using basic_string = + std::basic_string>; + + } + + The class template basic_string stores and manipulates sequences of character-like + objects, which are non-array objects of TrivialType and StandardLayoutType. The + class is dependent neither on the character type nor on the nature of operations on + that type. The definitions of the operations are supplied via the Traits template + parameter - a specialization of std::char_traits or a compatible traits class. + + The elements of a basic_string are stored contiguously, that is, for a basic_string + s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()) + , and *(s.begin() + s.size()) has value CharT() (a null terminator) + \fI(since C++11)\fP; or, equivalently, a pointer to s[0] can be passed to functions that + expect a pointer to the first element of + an array + \fI(until C++11)\fP + a null-terminated array + \fI(since C++11)\fP of CharT. - The class template basic_string stores and manipulates sequences of char-like - objects. The class is dependent neither on the character type nor on the nature of - operations on that type. The definitions of the operations are supplied via the - Traits template parameter - a specialization of std::char_traits or a compatible - traits class. + std::basic_string satisfies the requirements of AllocatorAwareContainer (except that + customized construct/destroy are not used for construction/destruction of elements), + SequenceContainer + and ContiguousContainer + \fI(since C++17)\fP. - The elements of a basic_string are stored contiguously, that is, for a - basic_string s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, - s.size()), or, equivalently, a pointer to s[0] can be passed to \fI(since C++11)\fP - functions that expect a pointer to the first element of a CharT[] - array. + If any of Traits::char_type and Allocator::char_type is different from CharT, the + program is ill-formed. + + Member functions of std::basic_string are constexpr: it is possible to + create and use std::string objects in the evaluation of a constant + expression. + \fI(since C++20)\fP + However, std::string objects generally cannot be constexpr, because + any dynamically allocated storage must be released in the same + evaluation of constant expression. Several typedefs for common character types are provided: Defined in header - Type Definition - std::string std::basic_string - std::wstring std::basic_string - std::u16string \fI(C++11)\fP std::basic_string - std::u32string \fI(C++11)\fP std::basic_string + Type Definition + std::string std::basic_string + std::wstring std::basic_string + std::u8string (C++20) std::basic_string + std::u16string \fI(C++11)\fP std::basic_string + std::u32string \fI(C++11)\fP std::basic_string + std::pmr::string \fI(C++17)\fP std::pmr::basic_string + std::pmr::wstring \fI(C++17)\fP std::pmr::basic_string + std::pmr::u8string (C++20) std::pmr::basic_string + std::pmr::u16string \fI(C++17)\fP std::pmr::basic_string + std::pmr::u32string \fI(C++17)\fP std::pmr::basic_string .SH Template parameters @@ -40,172 +80,318 @@ Member type Definition traits_type Traits - value_type Traits::char_type - allocator_type Allocator - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP + value_type CharT + allocator_type Allocator + Allocator::size_type \fI(until C++11)\fP + size_type std::allocator_traits::size_type \fI(since C++11)\fP + + + Allocator::difference_type (until + C++11) + difference_type std::allocator_traits::difference_type (since + C++11) + + + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator RandomAccessIterator - const_iterator Constant random access iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator, + iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator, + const_iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator .SH Member functions - constructor constructs a basic_string - \fI(public member function)\fP - operator= assigns values to the string - \fI(public member function)\fP - assign assign characters to a string - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP + destroys the string, deallocating internal storage if + destructor used + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Element access - at access specified character with bounds checking - \fI(public member function)\fP - operator[] access specified character - \fI(public member function)\fP - front accesses the first character - \fI(C++11)\fP \fI(public member function)\fP - back accesses the last character - \fI(C++11)\fP \fI(public member function)\fP - data returns a pointer to the first character of a string - \fI(public member function)\fP - returns a non-modifiable standard C character array version of the - c_str string - \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP + returns a non-modifiable standard C character array + c_str version of the string + \fI(public member function)\fP + operator basic_string_view returns a non-modifiable string_view into the entire + \fI(C++17)\fP string + \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP \fI(C++11)\fP - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP \fI(C++11)\fP - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP \fI(C++11)\fP - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP \fI(C++11)\fP .SH Capacity - empty checks whether the string is empty - \fI(public member function)\fP - size returns the number of characters - length \fI(public member function)\fP - max_size returns the maximum number of characters - \fI(public member function)\fP - reserve reserves storage - \fI(public member function)\fP - returns the number of characters that can be held in currently - capacity allocated storage - \fI(public member function)\fP - shrink_to_fit reduces memory usage by freeing unused memory - \fI(C++11)\fP \fI(public member function)\fP -.SH Operations - clear clears the contents - \fI(public member function)\fP - insert inserts characters - \fI(public member function)\fP - erase removes characters - \fI(public member function)\fP - push_back appends a character to the end - \fI(public member function)\fP - pop_back removes the last character - \fI(C++11)\fP \fI(public member function)\fP - append appends characters to the end - \fI(public member function)\fP - operator+= appends characters to the end - \fI(public member function)\fP - compare compares two strings - \fI(public member function)\fP - replace replaces specified portion of a string - \fI(public member function)\fP - substr returns a substring - \fI(public member function)\fP - copy copies characters - \fI(public member function)\fP - resize changes the number of characters stored - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + empty checks whether the string is empty + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + returns the number of characters that can be held in + capacity currently allocated storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP +.SH Modifiers + clear clears the contents + \fI(public member function)\fP + insert inserts characters + \fI(public member function)\fP + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP + pop_back removes the last character + (DR*) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + replace replaces specified portion of a string + \fI(public member function)\fP + replace_with_range replaces specified portion of a string with a range of + (C++23) characters + \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP + changes the number of characters stored and possibly + resize_and_overwrite overwrites indeterminate contents via user-provided + (C++23) operation + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP .SH Search - find find characters in the string - \fI(public member function)\fP - rfind find the last occurrence of a substring - \fI(public member function)\fP - find_first_of find first occurrence of characters - \fI(public member function)\fP - find_first_not_of find first absence of characters - \fI(public member function)\fP - find_last_of find last occurrence of characters - \fI(public member function)\fP - find_last_not_of find last absence of characters - \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Operations + compare compares two strings + \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string contains the given substring or + (C++23) character + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP .SH Constants - npos special value. The exact meaning depends on the context - \fB[static]\fP \fI(public static member constant)\fP + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP .SH Non-member functions operator+ concatenates two strings or a string and a char - \fI(function template)\fP + \fI(function template)\fP operator== operator!= - operator< lexicographically compares two strings - operator> \fI(function template)\fP + operator< + operator> operator<= - operator>= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::basic_string) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase(std::basic_string) erases all elements satisfying specific criteria + erase_if(std::basic_string) \fI(function template)\fP + (C++20) .SH Input/output operator<< performs stream input and output on strings - operator>> \fI(function template)\fP + operator>> \fI(function template)\fP getline read data from an I/O stream into a string - \fI(function)\fP + \fI(function template)\fP .SH Numeric conversions stoi stol stoll converts a string to a signed integer - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP stoul stoull converts a string to an unsigned integer - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP stof stod stold converts a string to a floating point value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP - to_string converts an integral or floating point value to string - \fI(C++11)\fP \fI(function)\fP - to_wstring converts an integral or floating point value to wstring - \fI(C++11)\fP \fI(function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP .SH Literals Defined in inline namespace std::literals::string_literals - operator""s Converts a character array literal to basic_string - \fI(C++14)\fP \fI(function)\fP + operator""s converts a character array literal to basic_string + \fI(C++14)\fP \fI(function)\fP .SH Helper classes - std::hash - std::hash - std::hash - std::hash hash support for strings - \fI(C++11)\fP \fI(class template specialization)\fP - \fI(C++11)\fP - \fI(C++11)\fP - \fI(C++11)\fP + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Although it is required that customized construct or destroy is used when + constructing or destroying elements of std::basic_string until C++23, all + implementations only used the default mechanism. The requirement is corrected by + P1072R10 to match existing practice. + + Feature-test macro Value Std Feature + __cpp_lib_string_udls 201304L \fI(C++14)\fP User-defined literals for + string types + __cpp_lib_starts_ends_with 201711L (C++20) starts_with, ends_with + __cpp_lib_constexpr_string 201907L (C++20) Constexpr for + std::basic_string + __cpp_lib_char8_t 201907L (C++20) std::u8string + __cpp_lib_erase_if 202002L (C++20) erase, erase_if + __cpp_lib_string_contains 202011L (C++23) contains + __cpp_lib_string_resize_and_overwrite 202110L (C++23) resize_and_overwrite + Member functions for + __cpp_lib_containers_ranges 202202L (C++23) construction, insertion, and + replacement that accept + container compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + // Creating a string from const char* + std::string str1 = "hello"; + + // Creating a string using string literal + auto str2 = "world"s; + + // Concatenating strings + std::string str3 = str1 + " " + str2; + + // Print out the result + std::cout << str3 << '\\n'; + + std::string::size_type pos = str3.find(" "); + str1 = str3.substr(pos + 1); // the part after the space + str2 = str3.substr(0, pos); // the part till the space + + std::cout << str1 << ' ' << str2 << '\\n'; + + // Accessing an element using subscript operator[] + std::cout << str1[0] << '\\n'; + str1[0] = 'W'; + std::cout << str1 << '\\n'; + } + +.SH Output: + + hello world + world hello + w + World + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + contiguity of the storage for elements of + LWG 530 C++98 basic_string required again + was accidently made not required by LWG259 + the behavior is undefined if any of the program is + LWG 2994 C++98 Traits::char_type^[1] ill-formed in this + (P1148R0) and Allocator::char_type is different from case + CharT + + 1. ↑ The Traits::char_type case is fixed in P1148R0. + +.SH See also + + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP + +.SH External links + + C++ string handling + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::basic_string::append.3 b/man/std::basic_string::append.3 index 80a82a7b9..dfcb8cb7a 100644 --- a/man/std::basic_string::append.3 +++ b/man/std::basic_string::append.3 @@ -1,55 +1,88 @@ -.TH std::basic_string::append 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - basic_string& append( size_type count, CharT ch ); \fB(1)\fP - basic_string& append( const basic_string& str ); \fB(2)\fP - basic_string& append( const basic_string& str, - - size_type pos, \fI(until C++14)\fP +.TH std::basic_string::append 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append \- std::basic_string::append - size_type count ); +.SH Synopsis + basic_string& append( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& append( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) basic_string& append( const basic_string& str, - - size_type pos, \fB(3)\fP \fI(since C++14)\fP - - size_type count = npos); - basic_string& append( const CharT* s, \fB(4)\fP - size_type count ); - basic_string& append( const CharT* s ); \fB(5)\fP - template< class InputIt > \fB(6)\fP - basic_string& append( InputIt first, InputIt last ); - basic_string& append( std::initializer_list ilist ); \fB(7)\fP \fI(since C++11)\fP + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& append( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos ); C++20) + basic_string& append( const CharT* s, \fB(4)\fP (constexpr since + size_type count ); C++20) + basic_string& append( const CharT* s ); \fB(5)\fP (constexpr since + C++20) + template< class InputIt > (constexpr since + basic_string& append( InputIt first, InputIt \fB(6)\fP C++20) + last ); \fB(3)\fP + basic_string& append( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(7)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& append( const StringViewLike& t \fB(8)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& append( const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos ); Appends additional characters to the string. - 1) Appends count copies of character ch - - 2) Appends string str - - 3) Appends a substring [pos, pos+count) of str. If the requested substring lasts - past the end of the string, or if count == npos, the appended substring is [pos, - size()). If pos >= str.size(), std::out_of_range is thrown. - - 4) Appends the first count characters of character string pointed to by s. s can - contain null characters. - - 5) Appends the null-terminated character string pointed to by s. The length of the - string is determined by the first null character. - - 6) Appends characters in the range [first, last) - - 7) Appends characters in the initializer list ilist. + 1) Appends count copies of character ch. + 2) Appends string str. + 3) Appends a substring [pos, pos + count) of str. + * If the requested substring lasts past the end of the string, or if count == + npos, the appended substring is [pos, size()). + * If pos > str.size(), std::out_of_range is thrown. + 4) Appends characters in the range [s, s + count). This range can contain null + characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 5) Appends the null-terminated character string pointed to by s, as if by append(s, + Traits::length(s)). + 6) Appends characters in the range [first, last). + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload only participates in overload resolution if InputIt \fI(since C++11)\fP + qualifies as a LegacyInputIterator. + + 7) Appends characters from the initializer list ilist. + 8) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends all characters from sv as if by append(sv.data(), + sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends the characters from the subview [pos, pos + count) of + sv. + * If the requested subview extends past the end of sv, or if count == npos, the + appended subview is [pos, sv.size()). + * If pos >= sv.size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. .SH Parameters count - number of characters to append + pos - the index of the first character to append ch - character value to append first, last - range of characters to append str - string to append s - pointer to the character string to append ilist - initializer list with the characters to append -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. + t - object convertible to std::basic_string_view with the characters to + append .SH Return value @@ -57,69 +90,61 @@ .SH Complexity - 1) linear in count - - 2) linear in size of str - - 3-4) linear in count - - 5) linear in size of s - - 6) linear in distance between first and last - - 7) linear in size of ilist + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). .SH Exceptions - If an exception is thrown for any reason, this function has no effect (strong - exception guarantee). - \fI(since C++11)\fP - If the operation would result in size() > max_size(), throws std::length_error. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + .SH Example - + // Run this code - #include #include - - int main() { + #include + + int main() + { std::basic_string str = "string"; const char* cptr = "C-string"; const char carr[] = "Two and one"; - + std::string output; - - // 1) Repeat a char + + // 1) Append a char 3 times. + // Notice, this is the only overload accepting chars. output.append(3, '*'); - std::cout << "1) " << output << "\\n"; - - // 2) Append a whole string + std::cout << "1) " << output << '\\n'; + + // 2) Append a whole string output.append(str); - std::cout << "2) " << output << "\\n"; - + std::cout << "2) " << output << '\\n'; + // 3) Append part of a string (last 3 letters, in this case) output.append(str, 3, 3); - std::cout << "3) " << output << "\\n"; - + std::cout << "3) " << output << '\\n'; + // 4) Append part of a C-string // Notice, because `append` returns *this, we can chain calls together output.append(1, ' ').append(carr, 4); - std::cout << "4) " << output << "\\n"; - + std::cout << "4) " << output << '\\n'; + // 5) Append a whole C-string output.append(cptr); - std::cout << "5) " << output << "\\n"; - + std::cout << "5) " << output << '\\n'; + // 6) Append range output.append(&carr[3], std::end(carr)); - std::cout << "6) " << output << "\\n"; - + std::cout << "6) " << output << '\\n'; + // 7) Append initializer list - output.append({ ' ', 'l', 'i', 's', 't' }); - std::cout << "7) " << output << "\\n"; + output.append({' ', 'l', 'i', 's', 't'}); + std::cout << "7) " << output << '\\n'; } .SH Output: @@ -132,7 +157,29 @@ 6) ***stringing Two C-string and one 7) ***stringing Two C-string and one list + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(8)\fP causes ambiguity in avoided by making it a + some cases template + .SH See also - operator+= appends characters to the end - \fI(public member function)\fP + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + strcat concatenates two strings + \fI(function)\fP + strncat concatenates a certain amount of characters of two strings + \fI(function)\fP + wcscat appends a copy of one wide string to another + \fI(function)\fP + appends a certain amount of wide characters from one wide string to + wcsncat another + \fI(function)\fP diff --git a/man/std::basic_string::append_range.3 b/man/std::basic_string::append_range.3 new file mode 100644 index 000000000..ede115277 --- /dev/null +++ b/man/std::basic_string::append_range.3 @@ -0,0 +1,65 @@ +.TH std::basic_string::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append_range \- std::basic_string::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& append_range( R&& rg ); + + Appends all characters from the range rg. + + Equivalent to + + return append(std::basic_string( std::from_range, std::forward(rg), get_allocator())); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string head{"long long"}; + const auto tail = {' ', 'i', 'n', 't'}; + + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.append(tail.begin(), tail.end()); + #endif + + assert(head == "long long int"); + } + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::basic_string::assign.3 b/man/std::basic_string::assign.3 index c8989946e..afbe7a690 100644 --- a/man/std::basic_string::assign.3 +++ b/man/std::basic_string::assign.3 @@ -1,60 +1,95 @@ -.TH std::basic_string::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - basic_string& assign( size_type count, CharT ch ); \fB(1)\fP - basic_string& assign( const basic_string& str ); \fB(2)\fP - basic_string& assign( const basic_string& str, +.TH std::basic_string::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign \- std::basic_string::assign - size_type pos, \fI(until C++14)\fP - - size_type count ); +.SH Synopsis + basic_string& assign( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& assign( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) basic_string& assign( const basic_string& str, - - size_type pos, \fI(since C++14)\fP - \fB(3)\fP - size_type count = npos); - basic_string& assign( basic_string&& str ); \fB(4)\fP \fI(since C++11)\fP - basic_string& assign( const CharT* s, \fB(5)\fP - size_type count ); - basic_string& assign( const CharT* s ); \fB(6)\fP - template< class InputIt > \fB(7)\fP - basic_string& assign( InputIt first, InputIt last ); - basic_string& assign( std::initializer_list ilist ); \fB(8)\fP \fI(since C++11)\fP + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& assign( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos); C++20) + basic_string& assign( basic_string&& str ) \fI(since C++11)\fP + noexcept(/* see below */); \fB(4)\fP (constexpr since + C++20) + basic_string& assign( const CharT* s, \fB(5)\fP (constexpr since + size_type count ); C++20) + basic_string& assign( const CharT* s ); \fB(6)\fP (constexpr since + C++20) + template< class InputIt > \fB(3)\fP (constexpr since + basic_string& assign( InputIt first, InputIt \fB(7)\fP C++20) + last ); + basic_string& assign( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(8)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t \fB(9)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t, \fB(10)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos); Replaces the contents of the string. - 1) Replaces the contents with count copies of charactor ch - - 2) Replaces the contents with a copy of str - - 3) Replaces the contents with a substring [pos, pos+count) of str. If the requested - substring lasts past the end of the string, or if count == npos, the resulting - substring is [pos, size()). If pos >= str.size(), std::out_of_range is thrown. - - 4) Replaces the contents with those of str using move semantics. str is in undefined - state after the operation. - - 5) Replaces the contents with the first count characters of character string pointed - to by s. s can contain null characters. - + 1) Replaces the contents with count copies of character ch. + 2) Replaces the contents with a copy of str. Equivalent to *this = str;. + In particular, allocator propagation may take place. + \fI(since C++11)\fP + 3) Replaces the contents with a substring [pos, pos + count) of str. If the + requested substring lasts past the end of the string, or if count == npos, the + resulting substring is [pos, str.size()). If pos > str.size(), std::out_of_range is + thrown. + 4) Replaces the contents with those of str using move semantics. Equivalent to *this + = std::move(str). In particular, allocator propagation may take place. + 5) Replaces the contents with copies of the characters in the range [s, s + count). + This range can contain null characters. 6) Replaces the contents with those of null-terminated character string pointed to - by s. The length of the string is determined by the first null character. - - 7) Replaces the contents with copies of the characters in the range [first, last) - + by s. The length of the string is determined by the first null character using + Traits::length(s). + 7) Replaces the contents with copies of the characters in the range [first, last). + This overload does not participate in overload resolution if InputIt does not + satisfy LegacyInputIterator. + \fI(since C++11)\fP 8) Replaces the contents with those of the initializer list ilist. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of sv, as if by + assign(sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with the characters from the subview + [pos, pos + count) of sv. If the requested subview lasts past the end of sv, or if + count == npos, the resulting subview is [pos, sv.size()). If pos > sv.size(), + std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. .SH Parameters count - size of the resulting string + pos - index of the first character to take ch - value to initialize characters of the string with first, last - range to copy the characters from str - string to be used as source to initialize the characters with - s - pointer to a character string to use - as source to initialize the string with - init - initializer list to initialize the characters of the string with + s - pointer to a character string to use as source to initialize the + string with + ilist - std::initializer_list to initialize the characters of the string with + t - object (convertible to std::basic_string_view) to initialize the + characters of the string with .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value @@ -62,42 +97,114 @@ .SH Complexity - 1) linear in count - - 2) linear in size of str - - 3) linear in count + 1) Linear in count. + 2) Linear in size of str. + 3) Linear in count. + 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 5) Linear in count. + 6) Linear in size of s. + 7) Linear in distance between first and last. + 8) Linear in size of ilist. + 9) Linear in size of t. - 4) constant. If alloc is given and alloc != other.get_allocator(), then linear. - - 5) linear in count +.SH Exceptions - 6) linear in size of s + 4) + noexcept specification: + noexcept(std::allocator_traits:: - 7) linear in distance between first and last + propagate_on_container_move_assignment::value || - 8) linear in size of init + std::allocator_traits::is_always_equal::value) -.SH Exceptions + If the operation would result in size() > max_size(), throws std::length_error. If an exception is thrown for any reason, this function has no effect (strong - exception guarantee). - \fI(since C++11)\fP - - If the operation would result in size() > max_size(), throws std::length_error. + exception safety guarantee). .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + // assign(size_type count, CharT ch) + s.assign(4, '='); + std::cout << s << '\\n'; // "====" + + std::string const c("Exemplary"); + // assign(const basic_string& str) + s.assign(c); + std::cout << c << " == " << s << '\\n'; // "Exemplary == Exemplary" + + // assign(const basic_string& str, size_type pos, size_type count) + s.assign(c, 0, c.length() - 1); + std::cout << s << '\\n'; // "Exemplar"; + + // assign(basic_string&& str) + s.assign(std::string("C++ by ") + "example"); + std::cout << s << '\\n'; // "C++ by example" + + // assign(const CharT* s, size_type count) + s.assign("C-style string", 7); + std::cout << s << '\\n'; // "C-style" + + // assign(const CharT* s) + s.assign("C-style\\0string"); + std::cout << s << '\\n'; // "C-style" + + char mutable_c_str[] = "C-style string"; + // assign(InputIt first, InputIt last) + s.assign(std::begin(mutable_c_str), std::end(mutable_c_str) - 1); + std::cout << s << '\\n'; // "C-style string" + + // assign(std::initializer_list ilist) + s.assign({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << s << '\\n'; // "C-style" + } + +.SH Output: + + ==== + Exemplary == Exemplary + Exemplar + C++ by example +.SH C-style +.SH C-style + C-style string +.SH C-style + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + non-normative note stated that swap + LWG 2063 C++11 is corrected to require move + a valid implementation of assignment + move-assign + LWG 2579 C++11 assign(const basic_string&) made to propagate allocators + did not propagate allocators if needed + LWG 2946 C++17 overload \fB(9)\fP caused ambiguity in avoided by making it a + some cases template .SH See also + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP constructor constructs a basic_string - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the string - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - - * Todo no example + * conditionally noexcept diff --git a/man/std::basic_string::assign_range.3 b/man/std::basic_string::assign_range.3 new file mode 100644 index 000000000..7bfd17959 --- /dev/null +++ b/man/std::basic_string::assign_range.3 @@ -0,0 +1,74 @@ +.TH std::basic_string::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign_range \- std::basic_string::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& assign_range( R&& rg ); + + Replaces the contents of the string with the values in the range rg. + + Equivalent to + + return assign( + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto source = {'s', 'o', 'u', 'r', 'c', 'e'}; + std::string destination{"destination"}; + + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.begin(), source.end()); + #endif + + assert(destination == "source"); + } + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP diff --git a/man/std::basic_string::at.3 b/man/std::basic_string::at.3 index 070d2f8a4..36e5a7e1d 100644 --- a/man/std::basic_string::at.3 +++ b/man/std::basic_string::at.3 @@ -1,7 +1,10 @@ -.TH std::basic_string::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::at \- std::basic_string::at + .SH Synopsis - reference at( size_type pos ); - const_reference at( size_type pos ) const; + CharT& at( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& at( size_type pos ) const; \fB(2)\fP (constexpr since C++20) Returns a reference to the character at specified location pos. Bounds checking is performed, exception of type std::out_of_range will be thrown on invalid access. @@ -18,46 +21,63 @@ Throws std::out_of_range if pos >= size(). + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + .SH Complexity Constant. .SH Example - + // Run this code - #include #include - + #include + #include + int main() { std::string s("message"); // for capacity - + s = "abc"; - s.at(2) = 'x'; // ok + s.at(2) = 'x'; // OK std::cout << s << '\\n'; - + std::cout << "string size = " << s.size() << '\\n'; std::cout << "string capacity = " << s.capacity() << '\\n'; - - try { - // throw, even if capacity allowed to access element + + try + { + // This will throw since the requested offset is greater than the current size. s.at(3) = 'x'; } - catch (std::out_of_range& exc) { + catch (std::out_of_range const& exc) + { std::cout << exc.what() << '\\n'; } } -.SH Output: +.SH Possible output: abx string size = 3 string capacity = 7 basic_string::at + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + .SH See also - operator[] access specified character - \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::back.3 b/man/std::basic_string::back.3 index f6a3891ed..5dd0d47ca 100644 --- a/man/std::basic_string::back.3 +++ b/man/std::basic_string::back.3 @@ -1,9 +1,13 @@ -.TH std::basic_string::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::back \- std::basic_string::back + .SH Synopsis - CharT& back(); \fI(since C++11)\fP - const CharT& back() const; \fI(since C++11)\fP + CharT& back(); \fB(1)\fP (constexpr since C++20) + const CharT& back() const; \fB(2)\fP (constexpr since C++20) - Returns reference to the last character in the string. + Returns reference to the last character in the string. The behavior is undefined if + empty() is true. .SH Parameters @@ -11,17 +15,53 @@ .SH Return value - reference to the last character. + Reference to the last character, equivalent to operator[](size() - 1). .SH Complexity - Constant + Constant. .SH Notes - back requires that !empty() == true, otherwise the result is undefined. + In libstdc++, back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& back1 = s.back(); + back1 = 's'; + std::cout << s << '\\n'; // "Exemplars" + + std::string const c("Exemplary"); + char const& back2 = c.back(); + std::cout << back2 << '\\n'; // 'y' + } + +.SH Output: + + Exemplars + y + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function back() .SH See also - front accesses the first character - \fI(C++11)\fP \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::basic_string.3 b/man/std::basic_string::basic_string.3 index 45c1c8de3..431026f74 100644 --- a/man/std::basic_string::basic_string.3 +++ b/man/std::basic_string::basic_string.3 @@ -1,108 +1,317 @@ -.TH std::basic_string::basic_string 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - explicit basic_string( const Allocator& alloc = Allocator() ); \fI(until C++14)\fP - basic_string : basic_string(Allocator() {} \fI(since C++14)\fP - explicit basic_string( const Allocator& alloc ); - basic_string( size_type count, - - CharT ch, \fB(2)\fP +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string - const Allocator& alloc = Allocator() ); +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); basic_string( const basic_string& other, - size_type pos, \fB(3)\fP - size_type count = std::basic_string::npos, + size_type pos, size_type count, \fB(6)\fP (since C++23) const Allocator& alloc = Allocator() ); - basic_string( const CharT* s, + constexpr basic_string( basic_string&& other, - size_type count, \fB(1)\fP \fB(4)\fP + size_type pos, size_type count, \fB(7)\fP (since C++23) - const Allocator& alloc = Allocator() ); - basic_string( const CharT* s, \fB(5)\fP - const Allocator& alloc = Allocator() ); + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) template< class InputIt > - - basic_string( InputIt first, InputIt last, \fB(6)\fP + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) const Allocator& alloc = Allocator() ); - basic_string( const basic_string& other ); \fB(7)\fP - basic_string( const basic_string& other, const Allocator& \fB(7)\fP \fI(since C++11)\fP - alloc ); - basic_string( basic_string&& other ) \fB(8)\fP \fI(since C++11)\fP - basic_string( basic_string&& other, const Allocator& alloc ); \fB(8)\fP \fI(since C++11)\fP - basic_string( std::initializer_list init, \fB(9)\fP \fI(since C++11)\fP + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); Constructs new string from a variety of data sources and optionally using user supplied allocator alloc. - 1) Default constructor. Constructs empty string (zero size and unspecified capacity) - 2) Constructs the string with count copies of character ch. The behavior is - undefined if count >= npos - 3) Constructs the string with a substring [pos, pos+count) of other. If the - requested substring lasts past the end of the string, or if count == npos, the - resulting substring is [pos, size()). - 4) Constructs the string with the first count characters of character string pointed - to by s. s can contain null characters. The behavior is undefined if s does not - point at an array of at least count elements of CharT. - 5) Constructs the string with the contents initialized with a copy of the + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the null-terminated character string pointed to by s. The length of the string is - determined by the first null character. The behavior is undefined if s does not - point at an array of at least Traits::length(s)+1 elements of CharT. - 6) Constructs the string with the contents of the range [first, last). - 7) Copy constructor. Constructs the string with the copy of the contents of other. - 8) Move constructor. Constructs the string with the contents of other using move + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move semantics. other is left in valid, but unspecified state. - 9) Constructs the string with the contents of the initializer list init. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. .SH Parameters alloc - allocator to use for all memory allocations of this string count - size of the resulting string ch - value to initialize the string with + pos - position of the first character to include first, last - range to copy the characters from - s - pointer to a character string to use - as source to initialize the string with + s - pointer to an array of characters to use as source to initialize the + string with other - another string to use as source to initialize the string with - init - initializer list to initialize the string with -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range .SH Complexity - 1) constant + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. - 2-4) linear in count +.SH Exceptions - 5) linear in length of s + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. - 6) linear in distance between first and last + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. - 7) linear in size of other + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). - 8) constant. If alloc is given and alloc != other.get_allocator(), then linear. +.SH Notes - 9) linear in size of init + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: -.SH Exceptions + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" - 3) std::out_of_range if pos > other.size() - 8) Throws nothing if alloc == str.get_allocator() + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" - assign assign characters to a string - \fI(public member function)\fP - operator= assigns values to the string - \fI(public member function)\fP + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also -.SH Category: + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP - * Todo no example diff --git a/man/std::basic_string::begin,.3 b/man/std::basic_string::begin,.3 new file mode 100644 index 000000000..a9b49707a --- /dev/null +++ b/man/std::basic_string::begin,.3 @@ -0,0 +1,69 @@ +.TH std::basic_string::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::begin, \- std::basic_string::begin, + +.SH Synopsis + + iterator begin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the first character of the string. + + begin() returns a mutable or constant iterator, depending on the constness of *this. + + cbegin() always returns a constant iterator. It is equivalent to const_cast(*this).begin(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplar"); + *s.begin() = 'e'; + std::cout << s << '\\n'; + + auto i = s.cbegin(); + std::cout << *i << '\\n'; + // *i = 'E'; // error: i is a constant iterator + } + +.SH Output: + + exemplar + e + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::begin,std::basic_string::cbegin.3 b/man/std::basic_string::begin,std::basic_string::cbegin.3 deleted file mode 100644 index 36fb0c10c..000000000 --- a/man/std::basic_string::begin,std::basic_string::cbegin.3 +++ /dev/null @@ -1,25 +0,0 @@ -.TH std::basic_string::begin,std::basic_string::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP - - Returns an iterator to the first character of the string. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - iterator to the first character - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP - \fI(C++11)\fP diff --git a/man/std::basic_string::c_str.3 b/man/std::basic_string::c_str.3 index 3091bbbef..e1a3268f3 100644 --- a/man/std::basic_string::c_str.3 +++ b/man/std::basic_string::c_str.3 @@ -1,19 +1,25 @@ -.TH std::basic_string::c_str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::c_str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::c_str \- std::basic_string::c_str + .SH Synopsis - const CharT* c_str() const; + const CharT* c_str() const; (noexcept since C++11) + (constexpr since C++20) Returns a pointer to a null-terminated character array with data equivalent to those stored in the string. - The pointer is such that the range [c_str(); c_str() + size()] is valid and the + The pointer is such that the range [c_str(), c_str() + size()] is valid and the values in it correspond to the values stored in the string with an additional null character after the last position. The pointer obtained from c_str() may be invalidated by: * Passing a non-const reference to the string to any standard library function, or - * Calling non-const member functions on the string, excluding operator[], at(), - front(), back(), begin(), rbegin(), end() and rend(). + * Calling non-const member functions on the string + , excluding operator[], at(), front(), back(), begin(), rbegin(), end() and + rend() + \fI(since C++11)\fP. Writing to the character array accessed through c_str() is undefined behavior. @@ -27,31 +33,56 @@ Pointer to the underlying character storage. - data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP - data() + i == &operator[](i) for every i in [0, size()]. \fI(since C++11)\fP + c_str()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + c_str() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. .SH Complexity Constant. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Notes The pointer obtained from c_str() may only be treated as a pointer to a null-terminated character string if the string object does not contain other null characters. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + extern "C" void c_func(const char* c_str) + { + printf("c_func called with '%s'\\n", c_str); + } + + int main() + { + std::string const s("Emplary"); + const char* p = s.c_str(); + assert(s.size() == std::strlen(p)); + assert(std::equal(s.begin(), s.end(), p)); + assert(std::equal(p, p + s.size(), s.begin())); + assert('\\0' == *(p + s.size())); + + c_func(s.c_str()); + } + +.SH Output: + + c_func called with 'Emplary' + .SH See also - front accesses the first character - \fI(C++11)\fP \fI(public member function)\fP - back accesses the last character - \fI(C++11)\fP \fI(public member function)\fP - data returns a pointer to the first character of a string - \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP diff --git a/man/std::basic_string::capacity.3 b/man/std::basic_string::capacity.3 index f2c6d9274..32f50b319 100644 --- a/man/std::basic_string::capacity.3 +++ b/man/std::basic_string::capacity.3 @@ -1,6 +1,10 @@ -.TH std::basic_string::capacity 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::capacity \- std::basic_string::capacity + .SH Synopsis - size_type capacity() const; + size_type capacity() const; (noexcept since C++11) + (constexpr since C++20) Returns the number of characters that the string has currently allocated space for. @@ -10,22 +14,80 @@ .SH Return value - capacity of the currently allocated storage + Capacity of the currently allocated storage, i.e. the storage available for storing + elements. -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Constant. -.SH Complexity +.SH Notes + + Memory locations obtained from the allocator but not available for storing any + element are not counted in the allocated storage. Note that the null terminator is + not an element of the std::basic_string. + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_capacity(std::string const& s) + { + std::cout << std::quoted(s) << " has capacity " << s.capacity() << ".\\n"; + } + + int main() + { + std::string s{"Exemplar"}; + show_capacity(s); + + s += " is an example string."; + show_capacity(s); + + s.clear(); + show_capacity(s); + + std::cout << "\\nDemonstrate the capacity's growth policy." + "\\nSize: Capacity: Ratio:\\n" << std::left; + + std::string g; + auto old_cap{g.capacity()}; + + for (int mark{}; mark != 5; ++mark) + { + while (old_cap == g.capacity()) + g.push_back('.'); + + std::cout << std::setw( 7) << g.size() + << std::setw(11) << g.capacity() + << std::setw(10) << g.capacity() / static_cast(old_cap) << '\\n'; + + old_cap = g.capacity(); + } + } + +.SH Possible output: + + "Exemplar" has capacity 15. + "Exemplar is an example string." has capacity 30. + "" has capacity 30. - Constant + Demonstrate the capacity's growth policy. + Size: Capacity: Ratio: + 16 30 2 + 31 60 2 + 61 120 2 + 121 240 2 + 241 480 2 .SH See also size returns the number of characters - length \fI(public member function)\fP + length \fI(public member function)\fP reserve reserves storage - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_string::clear.3 b/man/std::basic_string::clear.3 index b1ee4150d..a1e021b20 100644 --- a/man/std::basic_string::clear.3 +++ b/man/std::basic_string::clear.3 @@ -1,10 +1,14 @@ -.TH std::basic_string::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::clear \- std::basic_string::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) + (constexpr since C++20) + + Removes all characters from the string as if by executing erase(begin(), end()). - Removes all characters from the string. The allocated memory will not be released, - effectively leaving the capacity of the string unchanged. The past-the-end iterators - are not invalidated. + All pointers, references, and iterators are invalidated. .SH Parameters @@ -14,18 +18,38 @@ \fI(none)\fP -.SH Exceptions +.SH Notes - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Unlike for std::vector::clear, the C++ standard does not explicitly require that + capacity is unchanged by this function, but existing implementations do not change + capacity. This means that they do not release the allocated memory (see also + shrink_to_fit). .SH Complexity - Linear in the size of the string. + Linear in the size of the string, although existing implementations operate in + constant time. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s{"Exemplar"}; + std::string::size_type const capacity = s.capacity(); + + s.clear(); + assert(s.capacity() == capacity); // <- not guaranteed + assert(s.empty()); + assert(s.size() == 0); + } .SH See also erase removes characters - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_string::compare.3 b/man/std::basic_string::compare.3 index 81c00495a..890b367f1 100644 --- a/man/std::basic_string::compare.3 +++ b/man/std::basic_string::compare.3 @@ -1,58 +1,103 @@ -.TH std::basic_string::compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::compare \- std::basic_string::compare + .SH Synopsis - int compare( const basic_string& str ) const; \fB(1)\fP - int compare( size_type pos1, size_type count1, \fB(2)\fP - const basic_string& str ) const; + (noexcept since + int compare( const basic_string& str ) const; \fB(1)\fP C++11) + (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(2)\fP (constexpr since + const basic_string& str ) const; C++20) int compare( size_type pos1, size_type count1, - const basic_string& str, \fI(until C++14)\fP + const basic_string& str, \fI(until C++14)\fP - size_type pos2, size_type count2 ) const; + size_type pos2, size_type count2 + ) const; int compare( size_type pos1, size_type count1, + \fI(since C++14)\fP + const basic_string& str, (constexpr since + C++20) + size_type pos2, size_type count2 + = npos ) const; + int compare( const CharT* s ) const; \fB(4)\fP (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(5)\fP (constexpr since + const CharT* s ) const; C++20) + int compare( size_type pos1, size_type count1, \fB(3)\fP (constexpr since + const CharT* s, size_type count2 \fB(6)\fP C++20) + ) const; + template< class StringViewLike > \fI(since C++17)\fP + int compare( const StringViewLike& t ) const \fB(7)\fP (constexpr since + noexcept(/* see below */); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + int compare( size_type pos1, size_type count1, \fB(8)\fP (constexpr since + C++20) + const StringViewLike& t ) const; + template< class StringViewLike > - const basic_string& str, \fB(3)\fP \fI(since C++14)\fP - - size_type pos2, size_type count2 = npos ) const; - int compare( const CharT* s ) const; \fB(4)\fP - int compare( size_type pos1, size_type count1, \fB(5)\fP - const CharT* s ) const; - int compare( size_type pos1, size_type count1, \fB(6)\fP - const CharT* s, size_type count2 ) const; + int compare( size_type pos1, size_type count1, \fI(since C++17)\fP + const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos2, size_type count2 + = npos) const; Compares two character sequences. - 1) Compares this string to str. First, calculates the number of characters to - compare, as if by size_type rlen = std::min(size(), str.size()). Then compares by - calling Traits::compare(data(), str.data(), rlen). For standard strings this - function performs character-by-character lexicographical comparison. If the result - is zero (the strings are equal so far), then their sizes are compared as follows: - - Condition Result Return value - Traits::compare(data, arg, rlen) < 0 data is less <0 - than arg - size(data) < data is less <0 - size(arg) than arg - Traits::compare(data, arg, rlen) size(data) == data is equal to 0 - == 0 size(arg) arg - size(data) > data is greater >0 - size(arg) than arg - Traits::compare(data, arg, rlen) > 0 data is greater >0 - than arg - - 2) Compares a [pos1, pos1+count1) substring of this string to str as if by - basic_string(*this, pos1, count1).compare(str) - 3) Compares a [pos1, pos1+count1) substring of this string to a substring [pos2, - pos2+count2) of str as if by basic_string(*this, pos1, - count1).compare(basic_string(str, pos2, count2)) + 1) Compares this string to str. + 2) Compares a [pos1, pos1 + count1) substring of this string to str. + * If count1 > size() - pos1, the substring is [pos1, size()). + 3) Compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of str. + * If count1 > size() - pos1, the first substring is [pos1, size()). + * If count2 > str.size() - pos2, the second substring is [pos2, str.size()). 4) Compares this string to the null-terminated character sequence beginning at the - character pointed to by s, as if by compare(basic_string(s)) - 5) Compares a [pos1, pos1+count1) substring of this string to the null-terminated - character sequence beginning at the character pointed to by s, as if by - basic_string(*this, pos, count1).compare(basic_string(s)) - 6) Compares a [pos1, pos1+count1) substring of this string to the first count2 - characters of the character array whose first character is pointed to by s, as if by - basic_string(*this, pos, count1).compare(basic_string(s, count2)). (Note: the - characters from s to s+count2 may include null characters)) + character pointed to by s with length Traits::length(s). + 5) Compares a [pos1, pos1 + count1) substring of this string to the null-terminated + character sequence beginning at the character pointed to by s with length + Traits::length(s). + * If count1 > size() - pos1, the substring is [pos1, size()). + 6) Compares a [pos1, pos1 + count1) substring of this string to the characters in + the range [s, s + count2). The characters in [s, s + count2) may include null + characters. + * If count1 > size() - pos1, the substring is [pos1, size()). + 7-9) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then + 7) compares this string to sv; + 8) compares a [pos1, pos1 + count1) substring of this string to sv, as if by + std::basic_string_view(*this).substr(pos1, count1).compare(sv); + 9) compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of sv, as if by std::basic_string_view(*this) + .substr(pos1, count1).compare(sv.substr(pos2, count2)). + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false.. + + A character sequence consisting of count1 characters starting at data1 is compared + to a character sequence consisting of count2 characters starting at data2 as + follows: + + * First, calculate the number of characters to compare, as if by size_type rlen = + std::min(count1, count2). + * Then compare the sequences by calling Traits::compare(data1, data2, rlen). For + standard strings this function performs character-by-character lexicographical + comparison. If the result is zero (the character sequences are equal so far), + then their sizes are compared as follows: + + Condition Result Return value + Traits::compare(data1, data2, rlen) < 0 data1 is less than <0 + data2 + size1 < size2 data1 is less than <0 + data2 + Traits::compare(data1, data2, rlen) == size1 == data1 is equal to 0 + 0 size2 data2 + size1 > size2 data1 is greater >0 + than data2 + Traits::compare(data1, data2, rlen) > 0 data1 is greater >0 + than data2 .SH Parameters @@ -62,72 +107,179 @@ pos1 - position of the first character in this string to compare count2 - number of characters of the given string to compare pos2 - position of the first character of the given string to compare + t - object (convertible to std::basic_string_view) to compare to .SH Return value - negative value if this string is less than the other character sequence, zero if the - both character sequences are equal, positive value if this string is greater than - the other character sequence. + * Negative value if *this appears before the character sequence specified by the + arguments, in lexicographical order. + * Zero if both character sequences compare equivalent. + * Positive value if *this appears after the character sequence specified by the + arguments, in lexicographical order. .SH Exceptions - 1) + The overloads taking parameters named pos1 or pos2 throws std::out_of_range if the + argument is out of range. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + 7) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + 8,9) Throws anything thrown by the conversion to std::basic_string_view. - 2-3) May throw the exceptions thrown by the corresponding basic_string constructors. - 4) + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +.SH Possible implementation - 5-6) May throw the exceptions thrown by the corresponding basic_string constructors. + overload \fB(1)\fP + template + int std::basic_string::compare + (const std::basic_string& s) const noexcept + { + size_type lhs_sz = size(); + size_type rhs_sz = s.size(); + int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz)); + if (result != 0) + return result; + if (lhs_sz < rhs_sz) + return -1; + if (lhs_sz > rhs_sz) + return 1; + return 0; + } -.SH Possible implementation +.SH Notes -template -int basic_string::compare(const std::basic_string& str) const noexcept -{ - size_type lhs_sz = size(); - size_type rhs_sz = str.size(); - int result = traits_type::compare(data(), str.data(), std::min(lhs_sz, rhs_sz)); - if (result != 0) - return result; - if (lhs_sz < rhs_sz) - return -1; - if (lhs_sz > rhs_sz) - return 1; - return 0; -} + For the situations when three-way comparison is not required, std::basic_string + provides the usual relational operators (<, <=, ==, >, etc). + + By default (with the default std::char_traits), this function is not + locale-sensitive. See std::collate::compare for locale-aware three-way string + comparison. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + void print_compare_result(std::string_view str1, + std::string_view str2, + int compare_result) + { + if (compare_result < 0) + std::cout << std::quoted(str1) << " comes before " + << std::quoted(str2) << ".\\n"; + else if (compare_result > 0) + std::cout << std::quoted(str2) << " comes before " + << std::quoted(str1) << ".\\n"; + else + std::cout << std::quoted(str1) << " and " + << std::quoted(str2) << " are the same.\\n"; + } + + int main() + { + std::string batman{"Batman"}; + std::string superman{"Superman"}; + int compare_result{0}; + + // 1) Compare with other string + compare_result = batman.compare(superman); + std::cout << "1) "; + print_compare_result("Batman", "Superman", compare_result); + + // 2) Compare substring with other string + compare_result = batman.compare(3, 3, superman); + std::cout << "2) "; + print_compare_result("man", "Superman", compare_result); + + // 3) Compare substring with other substring + compare_result = batman.compare(3, 3, superman, 5, 3); + std::cout << "3) "; + print_compare_result("man", "man", compare_result); + + // Compare substring with other substring + // defaulting to end of other string + assert(compare_result == batman.compare(3, 3, superman, 5)); + + // 4) Compare with char pointer + compare_result = batman.compare("Superman"); + std::cout << "4) "; + print_compare_result("Batman", "Superman", compare_result); + + // 5) Compare substring with char pointer + compare_result = batman.compare(3, 3, "Superman"); + std::cout << "5) "; + print_compare_result("man", "Superman", compare_result); + + // 6) Compare substring with char pointer substring + compare_result = batman.compare(0, 3, "Superman", 5); + std::cout << "6) "; + print_compare_result("Bat", "Super", compare_result); + } + +.SH Output: + + 1) "Batman" comes before "Superman". + 2) "Superman" comes before "man". + 3) "man" and "man" are the same. + 4) "Batman" comes before "Superman". + 5) "Superman" comes before "man". + 6) "Bat" comes before "Super". + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the parameter count2 of overload default argument removed, + LWG 5 C++98 \fB(6)\fP split to overloads \fB(5)\fP and + had a default argument npos \fB(6)\fP + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(7)\fP caused ambiguity in avoided by making it a + some cases template + noexcept for overload \fB(7)\fP was + P1148R0 C++17 accidentally restored + dropped by the resolution of + LWG2946 .SH See also operator== operator!= - operator< lexicographically compares two strings - operator> \fI(function template)\fP + operator< + operator> operator<= - operator>= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) substr returns a substring - \fI(public member function)\fP + \fI(public member function)\fP collate defines lexicographical comparison and hashing of strings - \fI(class template)\fP + \fI(class template)\fP strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP returns true if one range is lexicographically less than lexicographical_compare another - \fI(function template)\fP + \fI(function template)\fP + compares two views + compare \fI\fI(public member\fP function of\fP + std::basic_string_view) .SH Category: - - * Todo no example + * conditionally noexcept diff --git a/man/std::basic_string::contains.3 b/man/std::basic_string::contains.3 new file mode 100644 index 000000000..a6b202311 --- /dev/null +++ b/man/std::basic_string::contains.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::contains \- std::basic_string::contains + +.SH Synopsis + constexpr bool + contains( std::basic_string_view sv ) const \fB(1)\fP (since C++23) + noexcept; + constexpr bool \fB(2)\fP (since C++23) + contains( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP (since C++23) + contains( const CharT* s ) const; + + Checks if the string contains the given substring. The substring may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void test_substring(const std::string& str, SubstrType subs) + { + constexpr char delim = std::is_scalar_v ? '\\'' : '\\"'; + std::cout << std::quoted(str) + << (str.contains(subs) ? " contains " + : " does not contain ") + << std::quoted(std::string{subs}, delim) << '\\n'; + } + + int main() + { + using namespace std::literals; + + auto helloWorld = "hello world"s; + + test_substring(helloWorld, "hello"sv); + test_substring(helloWorld, "goodbye"sv); + test_substring(helloWorld, 'w'); + test_substring(helloWorld, 'x'); + } + +.SH Output: + + "hello world" contains "hello" + "hello world" does not contain "goodbye" + "hello world" contains 'w' + "hello world" does not contain 'x' + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::copy.3 b/man/std::basic_string::copy.3 index e789db1ae..5258bb301 100644 --- a/man/std::basic_string::copy.3 +++ b/man/std::basic_string::copy.3 @@ -1,46 +1,81 @@ -.TH std::basic_string::copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type copy( CharT* dest, - - size_type count, +.TH std::basic_string::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::copy \- std::basic_string::copy - size_type pos = 0) const; +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos (constexpr since C++20) + = 0 ) const; - Copies a substring [pos, pos+count) to character string pointed to by dest. If the + Copies a substring [pos, pos + count) to character string pointed to by dest. If the requested substring lasts past the end of the string, or if count == npos, the - copied substring is [pos, size()). The resulting character string is not - null-terminated. + copied substring is [pos, size()). - If pos >= size(), std::out_of_range is thrown. + The resulting character string is not null-terminated. .SH Parameters dest - pointer to the destination character string - pos - position of the first character to include count - length of the substring + pos - position of the first character to include .SH Return value - number of characters copied + Number of characters copied. .SH Exceptions - std::out_of_range if pos >= size(). + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity - linear in count + Linear in count. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + + int main() + { + std::string foo("WINE"); - substr returns a substring - \fI(public member function)\fP + // brace-initialization initializes all characters to 0, + // providing a null-terminator + char bar[4]{}; -.SH Category: + // do not copy the last char, to guarantee null-termination + foo.copy(bar, sizeof bar - 1); + + std::cout << bar << '\\n'; // requires bar to be null-terminated + } + +.SH Output: + + WIN + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also - * Todo no example + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string_view)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::basic_string::data.3 b/man/std::basic_string::data.3 index 87fb9e646..e081790d6 100644 --- a/man/std::basic_string::data.3 +++ b/man/std::basic_string::data.3 @@ -1,10 +1,20 @@ -.TH std::basic_string::data 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::data \- std::basic_string::data + .SH Synopsis - const CharT* data() const; + const CharT* data() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + CharT* data() noexcept; \fB(2)\fP \fI(since C++17)\fP + (constexpr since C++20) + + Returns a pointer to the underlying array serving as character storage. The pointer + is such that the range - Returns pointer to the underlying array serving as character storage. The pointer is - such that the range [data(); data() + size()) is valid and the values in it - correspond to the values stored in the string. + [data(), data() + size()) \fI(until C++11)\fP + [data(), data() + size()] \fI(since C++11)\fP + + is valid and the values in it correspond to the values stored in the string. The returned array is not required to be null-terminated. \fI(until C++11)\fP @@ -21,8 +31,10 @@ * Passing a non-const reference to the string to any standard library function, or * Calling non-const member functions on the string, excluding operator[](), at(), front(), back(), begin(), end(), rbegin(), rend(). - - Modifying the character array accessed through data is undefined behavior. + 1) Modifying the character array accessed through the const overload of data has + undefined behavior. + 2) Modifying the past-the-end null terminator stored at data() + size() to any value + other than CharT() has undefined behavior. .SH Parameters @@ -32,25 +44,40 @@ A pointer to the underlying character storage. - data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP - data() + i == &operator[](i) for every i in [0, size()]. \fI(since C++11)\fP + data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + data() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. .SH Complexity Constant. -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + #include - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + int main() + { + std::string const s("Emplary"); + assert(s.size() == std::strlen(s.data())); + assert(std::equal(s.begin(), s.end(), s.data())); + assert(std::equal(s.data(), s.data() + s.size(), s.begin())); + assert('\\0' == *(s.data() + s.size())); + } .SH See also - front accesses the first character - \fI(C++11)\fP \fI(public member function)\fP - back accesses the last character - \fI(C++11)\fP \fI(public member function)\fP - c_str returns a non-modifiable standard C character array version of the string - \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + c_str returns a non-modifiable standard C character array version of the string + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::empty.3 b/man/std::basic_string::empty.3 index 72f4d45ee..515c30654 100644 --- a/man/std::basic_string::empty.3 +++ b/man/std::basic_string::empty.3 @@ -1,6 +1,10 @@ -.TH std::basic_string::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::empty \- std::basic_string::empty + .SH Synopsis - bool empty() const; + bool empty() const; (noexcept since C++11) + (constexpr since C++20) Checks if the string has no characters, i.e. whether begin() == end(). @@ -12,18 +16,51 @@ true if the string is empty, false otherwise -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::boolalpha(std::cout); + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = "Exemplar"; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = ""; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + } + +.SH Output: + + s.empty():true s:'' + s.empty():false s:'Exemplar' + s.empty():true s:'' + .SH See also - size returns the number of characters - length \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + empty checks whether the view is empty + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::end,.3 b/man/std::basic_string::end,.3 new file mode 100644 index 000000000..a29f4fa07 --- /dev/null +++ b/man/std::basic_string::end,.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::end, \- std::basic_string::end, + +.SH Synopsis + + iterator end(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the character following the last character of the string. + This character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemparl"); + std::next_permutation(s.begin(), s.end()); + + std::string c; + std::copy(s.cbegin(), s.cend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "Exemplar" + } + +.SH Output: + + Exemplar + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::end,std::basic_string::cend.3 b/man/std::basic_string::end,std::basic_string::cend.3 deleted file mode 100644 index b0569159d..000000000 --- a/man/std::basic_string::end,std::basic_string::cend.3 +++ /dev/null @@ -1,27 +0,0 @@ -.TH std::basic_string::end,std::basic_string::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP - - Returns an iterator to the character following the last character of the string. - This character acts as a placeholder, attempting to access it results in undefined - behavior. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - iterator to the character following the last character - -.SH Complexity - - Constant - -.SH See also - - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - \fI(C++11)\fP diff --git a/man/std::basic_string::ends_with.3 b/man/std::basic_string::ends_with.3 new file mode 100644 index 000000000..daa271fc6 --- /dev/null +++ b/man/std::basic_string::ends_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::ends_with \- std::basic_string::ends_with + +.SH Synopsis + constexpr bool + ends_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + ends_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + ends_with( const CharT* s ) const; + + Checks if the string ends with the given suffix. The suffix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).ends_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.ends_with("C++20!"sv) // (1) + && !str.ends_with("c++20!"sv) // (1) + && str.ends_with("C++20!"s) // (1) implicit conversion string to string_view + && !str.ends_with("c++20!"s) // (1) implicit conversion string to string_view + && str.ends_with('!') // (2) + && !str.ends_with('?') // (2) + && str.ends_with("C++20!") // (3) + && !str.ends_with("c++20!") // (3) + ); + } + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::basic_string::erase.3 b/man/std::basic_string::erase.3 index ba64498a8..caa61fc84 100644 --- a/man/std::basic_string::erase.3 +++ b/man/std::basic_string::erase.3 @@ -1,18 +1,30 @@ -.TH std::basic_string::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::erase \- std::basic_string::erase + .SH Synopsis - basic_string& erase( size_type index = 0, \fB(1)\fP + basic_string& erase( (constexpr since + size_type index = 0, \fB(1)\fP C++20) size_type count = npos ); - iterator erase( iterator position ); \fI(until C++11)\fP - iterator erase( const_iterator position ); \fI(since C++11)\fP - iterator erase( iterator first, iterator last ); \fB(2)\fP \fI(until C++11)\fP - iterator erase( const_iterator first, \fB(3)\fP \fI(since C++11)\fP - const_iterator last ); + iterator erase( iterator \fI(until C++11)\fP + position ); + iterator erase( \fI(since C++11)\fP + const_iterator position ); (constexpr since + \fB(2)\fP C++20) + iterator erase( iterator \fI(until C++11)\fP + first, iterator last ); + iterator erase( \fB(3)\fP \fI(since C++11)\fP + const_iterator first, (constexpr since + const_iterator last ); C++20) Removes specified characters from the string. - 1) Removes min(count, size() - index) characters starting at index. + 1) Removes std::min(count, size() - index) characters starting at index. 2) Removes the character at position. - 3) Removes the character in the range [first; last). + If position is not a dereferenceable iterator on *this, the behavior is undefined. + 3) Removes the characters in the range [first, last). + If first or last is not a valid iterator on *this, or [first, last) is not a valid + range, the behavior is undefined. .SH Parameters @@ -24,48 +36,74 @@ .SH Return value 1) *this - 2-3) iterator following the last removed character. + 2) Iterator pointing to the character immediately following the character erased, or + end() if no such character exists. + 3) Iterator pointing to the character last pointed to before the erase, or end() if + no such character exists. .SH Exceptions 1) std::out_of_range if index > size(). - 2-3) \fI(none)\fP + 2,3) Throws nothing. - In any case, if an exception is thrown for any reason, this function has no effect - \fI(strong exception guarantee)\fP. - \fI(since C++11)\fP + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Example - + // Run this code - #include #include + #include + #include #include - int main () + + int main() { - std::string s = "This is an example"; - std::cout << s << '\\n'; - - s.erase(0, 5); // Erase "This " - std::cout << s << '\\n'; - - s.erase(std::find(s.begin(), s.end(), ' ')); // Erase ' ' - std::cout << s << '\\n'; - - s.erase(s.find(' ')); // Trim from ' ' to the end of the string - std::cout << s << '\\n'; + std::string s = "This Is An Example"; + std::cout << "1) " << s << '\\n'; + + s.erase(7, 3); // erases " An" using overload (1) + std::cout << "2) " << s << '\\n'; + + s.erase(std::find(s.begin(), s.end(), ' ')); // erases first ' '; overload (2) + std::cout << "3) " << s << '\\n'; + + s.erase(s.find(' ')); // trims from ' ' to the end of the string; overload (1) + std::cout << "4) " << s << '\\n'; + + auto it = std::next(s.begin(), s.find('s')); // obtains iterator to the first 's' + s.erase(it, std::next(it, 2)); // erases "sI"; overload (3) + std::cout << "5) " << s << '\\n'; } .SH Output: - This is an example - is an example - isan example - isan + 1) This Is An Example + 2) This Is Example + 3) ThisIs Example + 4) ThisIs + 5) This + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(3)\fP did not erase the character returns an iterator + LWG 27 C++98 last pointed to, but it returned pointing to that + the iterator pointing to the character character + immediately following that character + overload \fB(2)\fP explicitly required position + LWG 428 C++98 to be valid, but removed the + SequenceContainer requires it to be explicit requirement + dereferenceable (stricter) + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_string::find.3 b/man/std::basic_string::find.3 index a514b600d..6ae3d060f 100644 --- a/man/std::basic_string::find.3 +++ b/man/std::basic_string::find.3 @@ -1,31 +1,64 @@ -.TH std::basic_string::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find \- std::basic_string::find + .SH Synopsis - size_type find( const basic_string& str, size_type pos = 0 ) const; \fB(1)\fP - size_type find( const CharT* s, size_type pos, size_type count ) const; \fB(2)\fP - size_type find( const CharT* s, size_type pos = 0 ) const; \fB(3)\fP - size_type find( CharT ch, size_type pos = 0 ) const; \fB(4)\fP + size_type find( const basic_string& str, size_type pos = \fB(1)\fP (noexcept since C++11) + 0 ) const; (constexpr since C++20) + size_type find( const CharT* s, size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find( const CharT* s, size_type pos = 0 ) \fB(3)\fP (constexpr since C++20) + const; + size_type find( CharT ch, size_type pos = 0 ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type find( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = 0 ) const noexcept(/* + see below */); Finds the first substring equal to the given character sequence. Search begins at pos, i.e. the found substring must not begin in a position preceding pos. - 1) Finds the first substring equal to str. If str.size() is zero, returns pos. - 2) Finds the first substring equal to the first count characters of the character - string pointed to by s. s can include null characters. If count is zero, returns - pos. + 1) Finds the first substring equal to str. + 2) Finds the first substring equal to the range [s, s + count). This range may + contain null characters. + If [s, s + count) is not a valid range, the behavior is undefined. 3) Finds the first substring equal to the character string pointed to by s. The - length of the string is determined by the first null character. If the length of s - is zero, returns pos. - 4) Finds the first character ch. - - If pos >= size(), the function always returns npos. + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character ch (treated as a single-character substring by the + formal rules below). + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first substring equal to sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + Formally, a substring str is said to be found at position xpos if all of the + following are true: + + * xpos >= pos + * xpos + str.size() <= size() + * for all positions n in str, Traits::eq(at(xpos + n), str.at(n)). + + In particular, this implies that + + * a substring can be found only if pos <= size() - str.size() + * an empty substring is found at pos if and only if pos <= size() + * for a non-empty substring, if pos >= size(), the function always returns npos. .SH Parameters str - string to search for pos - position at which to start the search count - length of substring to search for - s - pointer to a character string to seach for + s - pointer to a character string to search for ch - character to search for + t - object (convertible to std::basic_string_view) to search for .SH Return value @@ -34,84 +67,105 @@ .SH Exceptions - 1-4) \fI(none)\fP \fI(until C++11)\fP - 1,4) - noexcept specification: \fI(since C++11)\fP - noexcept \fI(until C++14)\fP - - 2,3) \fI(none)\fP - 1) - noexcept specification: - noexcept \fI(since C++14)\fP - - 2,3,4) \fI(none)\fP + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Example - + // Run this code - #include + #include #include - - void print(std::string::size_type n, std::string const &s) + #include + + void print(int id, std::string::size_type n, std::string const& s) { - if (n == std::string::npos) { - std::cout << "not found\\n"; - } else { - std::cout << "found: " << s.substr(n) << '\\n'; - } + std::cout << id << ") "; + if (std::string::npos == n) + std::cout << "not found! n == npos\\n"; + else + std::cout << "found @ n = " << n << ", substr(" << n << ") = " + << std::quoted(s.substr(n)) << '\\n'; } - + int main() { std::string::size_type n; - std::string const s = "This is a string"; - + std::string const s = "This is a string"; /* + ^ ^ ^ + 1 2 3 */ + // search from beginning of string n = s.find("is"); - print(n, s); - + print(1, n, s); + // search from position 5 n = s.find("is", 5); - print(n, s); - + print(2, n, s); + // find a single character n = s.find('a'); - print(n, s); - + print(3, n, s); + // find a single character n = s.find('q'); - print(n, s); + print(4, n, s); } .SH Output: - found: is is a string - found: is a string - found: a string - not found + 1) found @ n = 2, substr\fB(2)\fP = "is is a string" + 2) found @ n = 5, substr\fB(5)\fP = "is a string" + 3) found @ n = 8, substr\fB(8)\fP = "a string" + 4) not found! n == npos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 .SH See also strstr finds the first occurrence of a substring of characters - \fI(function)\fP + \fI(function)\fP finds the first occurrence of a wide string within another wide wcsstr string - \fI(function)\fP + \fI(function)\fP strchr finds the first occurrence of a character - \fI(function)\fP + \fI(function)\fP wcschr finds the first occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP rfind find the last occurrence of a substring - \fI(public member function)\fP + \fI(public member function)\fP find_first_of find first occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_first_not_of find first absence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_of find last occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_not_of find last absence of characters - \fI(public member function)\fP + \fI(public member function)\fP + find characters in the view + find \fI(public member function of std::basic_string_view)\fP + search searches for a range of elements - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::find_first_not_of.3 b/man/std::basic_string::find_first_not_of.3 index c620ef804..795a2e7ce 100644 --- a/man/std::basic_string::find_first_not_of.3 +++ b/man/std::basic_string::find_first_not_of.3 @@ -1,71 +1,141 @@ -.TH std::basic_string::find_first_not_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_not_of \- std::basic_string::find_first_not_of + .SH Synopsis - size_type find_first_not_of( const basic_string& str, size_type pos = 0 ) \fB(1)\fP - const; - size_type find_first_not_of( const CharT* s, size_type pos, size_type count ) \fB(2)\fP - const; - size_type find_first_not_of( const CharT* s, size_type pos = 0 ) const; \fB(3)\fP - size_type find_first_not_of( CharT ch, size_type pos = 0 ) const; \fB(4)\fP + size_type find_first_not_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_first_not_of( const CharT* s, \fB(3)\fP (constexpr since C++20) + size_type pos = 0 ) const; + size_type find_first_not_of( CharT ch, size_type pos = 0 \fB(4)\fP (noexcept since C++11) + ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const + noexcept(/* see below */); Finds the first character equal to none of the characters in the given character - sequence. Search begins at pos, i.e. the found character must not be in position - preceding pos. + sequence. The search considers only the range [pos, size()). If all characters in + the range can be found in the given character sequence, npos will be returned. 1) Finds the first character equal to none of characters in str. - 2) Finds the first character equal to none of characters in the first count - characters of the character string pointed to by s. s can include null characters. + 2) Finds the first character equal to none of characters in range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. 3) Finds the first character equal to none of characters in character string pointed - to by s. The length of the string is determined by the first null character. + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. 4) Finds the first character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. .SH Parameters str - string identifying characters to search for - pos - position for the seach to start from + pos - position for the search to start from count - length of character string identifying characters to search for s - pointer to a character string identifying characters to search for ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for .SH Return value - Position of the found character or npos if no such character is found. + Position of the found character or std::string::npos if no such character is found. .SH Exceptions - 1-4) \fI(none)\fP \fI(until C++11)\fP - 1,4) - noexcept specification: \fI(since C++11)\fP - noexcept \fI(until C++14)\fP - - 2,3) \fI(none)\fP - 1) - noexcept specification: - noexcept \fI(since C++14)\fP - - 2,3,4) \fI(none)\fP - -.SH Notes + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) - These functions use traits::eq() to test the characters for equality. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + // Permit uppercase letters, lowercase letters and numbers in macro names + const char* pattern = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "abcdefghijklmnopqrstuvwxyz" + "0123456789"; + + std::string data = "1) %FIX, 2) %HACK, and 3) %TODO"; + const std::string replacement = "%DONE%"; + + std::cout << "Before: " << data << '\\n'; + + for (std::string::size_type first{}, last{}; + (first = data.find('%', first)) != std::string::npos; + first += replacement.size()) + { + last = data.find_first_not_of(pattern, first + 1); + if (last == std::string::npos) + last = data.length(); + + // Now first at '%' and last is one past end of the found substring + data.replace(first, last - first, replacement); + } + + std::cout << "After: " << data << '\\n'; + } + +.SH Output: + + Before: 1) %FIX, 2) %HACK, and 3) %TODO + After: 1) %DONE%, 2) %DONE%, and 3) %DONE% + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 .SH See also - find find characters in the string - \fI(public member function)\fP - rfind find the last occurrence of a substring - \fI(public member function)\fP - find_first_of find first occurrence of characters - \fI(public member function)\fP - find_last_of find last occurrence of characters - \fI(public member function)\fP - find_last_not_of find last absence of characters - \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI(public member function of std::basic_string_view)\fP -.SH Category: - * Todo no example +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::find_first_of.3 b/man/std::basic_string::find_first_of.3 index 729816a1c..e6263f90c 100644 --- a/man/std::basic_string::find_first_of.3 +++ b/man/std::basic_string::find_first_of.3 @@ -1,21 +1,46 @@ -.TH std::basic_string::find_first_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_of \- std::basic_string::find_first_of + .SH Synopsis - size_type find_first_of( const basic_string& str, size_type pos = 0 ) const; \fB(1)\fP - size_type find_first_of( const CharT* s, size_type pos, size_type count ) \fB(2)\fP - const; - size_type find_first_of( const CharT* s, size_type pos = 0 ) const; \fB(3)\fP - size_type find_first_of( CharT ch, size_type pos = 0 ) const; \fB(4)\fP - - Finds the first character equal to one of characters in the given character - sequence. Search begins at pos, i.e. the found character must not be in position - preceding pos. - - 1) Finds the first character equal to one of characters in str. - 2) Finds the first character equal to one of characters in the first count - characters of the character string pointed to by s. s can include null characters. - 3) Finds the first character equal to one of characters in character string pointed - to by s. The length of the string is determined by the first null character. + size_type find_first_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_of( const CharT* s, + size_type pos, size_type count \fB(2)\fP (constexpr since C++20) + ) const; + size_type find_first_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + 0 ) const; + size_type find_first_of( CharT ch, size_type pos = 0 ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first character equal to one of the characters in the given character + sequence. The search considers only the range [pos, size()). If none of the + characters in the given character sequence is present in the range, npos will be + returned. + + 1) Finds the first character equal to one of the characters in str. + 2) Finds the first character equal to one of the characters in the range [s, s + + count). This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to one of the characters in character string + pointed to by s. The length of the string is determined by the first null character + using Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. 4) Finds the first character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to one of the characters in + sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. .SH Parameters @@ -24,6 +49,8 @@ count - length of character string identifying characters to search for s - pointer to a character string identifying characters to search for ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for .SH Return value @@ -31,64 +58,106 @@ .SH Exceptions - 1-4) \fI(none)\fP \fI(until C++11)\fP - 1,4) - noexcept specification: \fI(since C++11)\fP - noexcept \fI(until C++14)\fP - - 2,3) \fI(none)\fP - 1) - noexcept specification: - noexcept \fI(since C++14)\fP - - 2-4) \fI(none)\fP + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Notes - traits::eq() is used to perform the comparison. + Traits::eq() is used to perform the comparison. .SH Example - + // Run this code + #include #include #include - + #include + int main() { - // the test string - std::string str = std::string("Hello World!"); - - // strings and chars to search for - std::string search_str = std::string("o"); - const char* search_cstr = "Good Bye!"; - - std::cout << str.find_first_of(search_str) << '\\n'; - std::cout << str.find_first_of(search_str, 5) << '\\n'; - std::cout << str.find_first_of(search_cstr) << '\\n'; - std::cout << str.find_first_of(search_cstr, 0, 4) << '\\n'; - // 'x' is not in "Hello World', thus it will return std::string::npos - std::cout << str.find_first_of('x') << '\\n'; + using namespace std::literals; + std::string::size_type sz; + + // (1) + sz = "alignas"s.find_first_of("klmn"s); + // └────────────────────────┘ + assert(sz == 1); + + sz = "alignof"s.find_first_of("wxyz"s); + // no match + assert(sz == std::string::npos); + + // (2) + sz = "consteval"s.find_first_of("xyzabc", 0, 3); + // no match (× are not targets) ××× + assert(sz == std::string::npos); + + sz = "consteval"s.find_first_of("xyzabc", 0, 6); + // └───────────────────────────────┘ + assert(sz == 0); + + // (3) + sz = "decltype"s.find_first_of("xyzabc"); + // └────────────────────────────┘ + assert(sz == 2); + + // (4) + sz = "co_await"s.find_first_of('a'); + // └──────────────────────┘ + assert(sz == 3); + + // (5) + sz = "constinit"s.find_first_of("int"sv); + // └─────────────────────────┘ + assert(sz == 2); + + std::cout << "All tests passed.\\n"; } -.SH Possible output: +.SH Output: + + All tests passed. - 4 - 7 - 1 - 4 - 18446744073709551615 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 .SH See also - find find characters in the string - \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP rfind find the last occurrence of a substring - \fI(public member function)\fP + \fI(public member function)\fP find_first_not_of find first absence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_of find last occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_not_of find last absence of characters - \fI(public member function)\fP + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI(public member function of std::basic_string_view)\fP + + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::find_last_not_of.3 b/man/std::basic_string::find_last_not_of.3 index ea23158b8..b325c1428 100644 --- a/man/std::basic_string::find_last_not_of.3 +++ b/man/std::basic_string::find_last_not_of.3 @@ -1,30 +1,57 @@ -.TH std::basic_string::find_last_not_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_not_of \- std::basic_string::find_last_not_of + .SH Synopsis - size_type find_last_not_of( const basic_string& str, size_type pos = npos ) \fB(1)\fP - const; - size_type find_last_not_of( const CharT* s, size_type pos, size_type count ) \fB(2)\fP + size_type find_last_not_of( const basic_string& str, (noexcept since C++11) + size_type pos = npos ) \fB(1)\fP (constexpr since C++20) const; - size_type find_last_not_of( const CharT* s, size_type pos = npos ) const; \fB(3)\fP - size_type find_last_not_of( CharT ch, size_type pos = npos ) const; \fB(4)\fP + size_type find_last_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_last_not_of( const CharT* s, size_type \fB(3)\fP (constexpr since C++20) + pos = npos ) const; + size_type find_last_not_of( CharT ch, size_type pos = \fB(4)\fP (noexcept since C++11) + npos ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); Finds the last character equal to none of the characters in the given character - sequence. Search begins at pos, i.e. only the substring [0, pos] is considered in - the search. If npos is passed as pos whole string will be searched. + sequence. The search considers only the range [0, pos]. If all characters in the + range can be found in the given character sequence, npos will be returned. 1) Finds the last character equal to none of characters in str. - 2) Finds the last character equal to none of characters in the first count - characters of the character string pointed to by s. s can include null characters. + 2) Finds the last character equal to none of characters in the range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. 3) Finds the last character equal to none of characters in character string pointed - to by s. The length of the string is determined by the first null character. + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. 4) Finds the last character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. .SH Parameters str - string identifying characters to search for - pos - position at which to begin searching + pos - position at which to end search count - length of character string identifying characters to search for - s - pointer to a character string identifying characters to search fo + s - pointer to a character string identifying characters to search for ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for .SH Return value @@ -32,36 +59,102 @@ .SH Exceptions - 1-4) \fI(none)\fP \fI(until C++11)\fP - 1,4) - noexcept specification: \fI(since C++11)\fP - noexcept \fI(until C++14)\fP - - 2,3) \fI(none)\fP - 1) - noexcept specification: - noexcept \fI(since C++14)\fP - - 2,3,4) \fI(none)\fP + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v< + const T&, std::basic_string_view>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + void show_pos(const std::string& str, std::string::size_type found) + { + if (found != std::string::npos) + std::cout << '[' << found << "] = \\'" << str[found] << "\\'\\n"; + else + std::cout << "not found\\n"; + } + + int main() + { + std::string str{"abc_123"}; + char const* skip_set{"0123456789"}; + std::string::size_type str_last_pos{std::string::npos}; + + show_pos(str, str.find_last_not_of(skip_set)); // [3] = '_' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of(skip_set, str_last_pos)); // [2] = 'c' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of('c', str_last_pos)); // [1] = 'b' + + const char arr[]{'3', '4', '5'}; + show_pos(str, str.find_last_not_of(arr)); // [5] = '2' + + str_last_pos = 2; + std::string::size_type skip_set_size{4}; + show_pos(str, str.find_last_not_of(skip_set, + str_last_pos, + skip_set_size)); // [2] = 'c' + + show_pos(str, str.find_last_not_of("abc")); // [6] = '3' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of("abc", str_last_pos)); // not found + } + +.SH Output: + + [3] = '_' + [2] = 'c' + [1] = 'b' + [5] = '2' + [2] = 'c' + [6] = '3' + not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 .SH See also - find find characters in the string - \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP rfind find the last occurrence of a substring - \fI(public member function)\fP + \fI(public member function)\fP find_first_of find first occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_first_not_of find first absence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_of find last occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI(public member function of std::basic_string_view)\fP -.SH Category: - * Todo no example +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::find_last_of.3 b/man/std::basic_string::find_last_of.3 index fcb214f0f..e3ff59859 100644 --- a/man/std::basic_string::find_last_of.3 +++ b/man/std::basic_string::find_last_of.3 @@ -1,28 +1,57 @@ -.TH std::basic_string::find_last_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_of \- std::basic_string::find_last_of + .SH Synopsis - size_type find_last_of( const basic_string& str, size_type pos = npos ) const; \fB(1)\fP - size_type find_last_of( const CharT* s, size_type pos, size_type count ) const; \fB(2)\fP - size_type find_last_of( const CharT* s, size_type pos = npos ) const; \fB(3)\fP - size_type find_last_of( CharT ch, size_type pos = npos ) const; \fB(4)\fP + size_type find_last_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = npos ) const; (constexpr since C++20) + size_type find_last_of( const CharT* s, + size_type pos, size_type count ) \fB(2)\fP (constexpr since C++20) + const; + size_type find_last_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + npos ) const; + size_type find_last_of( CharT ch, size_type pos = npos ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); Finds the last character equal to one of characters in the given character sequence. - Search begins at pos, i.e. only the substring [0, pos] is considered in the search. - If npos is passed as pos whole string will be searched. + The exact search algorithm is not specified. The search considers only the range + [0, pos]. If none of the characters in the given character sequence is present in + the range, npos will be returned. 1) Finds the last character equal to one of characters in str. - 2) Finds the last character equal to one of characters in the first count characters - of the character string pointed to by s. s can include null characters. + 2) Finds the last character equal to one of characters in range [s, s + count). This + range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. 3) Finds the last character equal to one of characters in character string pointed - to by s. The length of the string is determined by the first null character. + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to one of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. .SH Parameters str - string identifying characters to search for pos - position at which the search is to finish count - length of character string identifying characters to search for - s - pointer to a character string identifying characters to search fo + s - pointer to a character string identifying characters to search for ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for .SH Return value @@ -30,36 +59,68 @@ .SH Exceptions - 1-4) \fI(none)\fP \fI(until C++11)\fP - 1,4) - noexcept specification: \fI(since C++11)\fP - noexcept \fI(until C++14)\fP - - 2,3) \fI(none)\fP - 1) - noexcept specification: - noexcept \fI(since C++14)\fP - - 2,3,4) \fI(none)\fP + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + const std::string path = "/root/config"; + auto const pos = path.find_last_of('/'); + const auto leaf = path.substr(pos + 1); + + std::cout << leaf << '\\n'; + } + +.SH Output: + + config + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 .SH See also - find find characters in the string - \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP rfind find the last occurrence of a substring - \fI(public member function)\fP + \fI(public member function)\fP find_first_of find first occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_first_not_of find first absence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_not_of find last absence of characters - \fI(public member function)\fP + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI(public member function of std::basic_string_view)\fP -.SH Category: - * Todo no example +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::front.3 b/man/std::basic_string::front.3 index 1382a44b4..978ec6830 100644 --- a/man/std::basic_string::front.3 +++ b/man/std::basic_string::front.3 @@ -1,9 +1,13 @@ -.TH std::basic_string::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::front \- std::basic_string::front + .SH Synopsis - CharT& front(); \fI(since C++11)\fP - const CharT& front() const; \fI(since C++11)\fP + CharT& front(); \fB(1)\fP (constexpr since C++20) + const CharT& front() const; \fB(2)\fP (constexpr since C++20) - Returns reference to the first character in the string. + Returns reference to the first character in the string. The behavior is undefined if + empty() is true. .SH Parameters @@ -11,17 +15,53 @@ .SH Return value - reference to the first character. + Reference to the first character, equivalent to operator[]\fB(0)\fP. .SH Complexity - Constant + Constant. .SH Notes - front requires that !empty() == true, otherwise the result is undefined. + In libstdc++, front() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& f1 = s.front(); + f1 = 'e'; + std::cout << s << '\\n'; // "exemplary" + + std::string const c("Exemplary"); + char const& f2 = c.front(); + std::cout << &f2 << '\\n'; // "Exemplary" + } + +.SH Output: + + exemplary + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function front() .SH See also - back accesses the last character - \fI(C++11)\fP \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + front accesses the first character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::get_allocator.3 b/man/std::basic_string::get_allocator.3 index 0d2f212b1..52b590226 100644 --- a/man/std::basic_string::get_allocator.3 +++ b/man/std::basic_string::get_allocator.3 @@ -1,6 +1,10 @@ -.TH std::basic_string::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::get_allocator \- std::basic_string::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++20) + (constexpr since C++20) Returns the allocator associated with the string. @@ -10,16 +14,17 @@ .SH Return value - the associated allocator + The associated allocator. .SH Complexity - Constant + Constant. .SH See also - This section is incomplete - -.SH Category: - - * Todo without reason + allocator the default allocator + \fI(class template)\fP + allocator_traits provides information about allocator types + \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::basic_string::insert.3 b/man/std::basic_string::insert.3 index d6bb2a6bb..28be988e6 100644 --- a/man/std::basic_string::insert.3 +++ b/man/std::basic_string::insert.3 @@ -1,52 +1,116 @@ -.TH std::basic_string::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert \- std::basic_string::insert + .SH Synopsis - basic_string& insert( size_type index, \fB(1)\fP - size_type count, CharT ch ); - basic_string& insert( size_type index, const \fB(2)\fP - CharT* s ); - basic_string& insert( size_type index, const \fB(3)\fP - CharT* s, size_type count ); - basic_string& insert( size_type index, const \fB(4)\fP - basic_string& str ); - basic_string& insert( size_type index, const - basic_string& str, (until - size_type index_str, C++14) - size_type count ); - basic_string& insert( size_type index, const - basic_string& str, (since - size_type index_str, C++14) - size_type count = npos); - iterator insert( iterator pos, CharT ch ); (until - C++11) - iterator insert( const_iterator pos, CharT (since - ch ); \fB(5)\fP C++11) - void insert( iterator pos, size_type count, (until - CharT ch ); C++11) - iterator insert( const_iterator pos, (since - size_type count, CharT ch ); \fB(6)\fP C++11) - template< class InputIt > (until - void insert( iterator pos, InputIt first, \fB(7)\fP C++11) - InputIt last ); - template< class InputIt > \fB(8)\fP (since - iterator insert( const_iterator pos, InputIt C++11) - first, InputIt last ); - iterator insert( const_iterator pos, \fB(9)\fP (since - std::initializer_list ilist ); C++11) + basic_string& insert( (constexpr + size_type index, size_type \fB(1)\fP since + count, CharT ch ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(2)\fP since + CharT* s ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(3)\fP since + CharT* s, size_type count ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(4)\fP since + basic_string& str ); C++20) + basic_string& insert( + size_type index, const + basic_string& str, (until + C++14) + size_type s_index, size_type + count ); + basic_string& insert( (since + size_type index, const C++14) + basic_string& str, (constexpr + since + size_type s_index, size_type C++20) + count = npos ); + iterator insert( iterator (until + pos, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, CharT ch (constexpr + ); since + C++20) + void insert( iterator pos, (until + size_type count, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, (constexpr + size_type count, CharT ch ); since + C++20) + template< class InputIt > + void insert( iterator pos, \fB(5)\fP (until + InputIt first, InputIt last C++11) + ); + template< class InputIt > (since + iterator insert( C++11) + const_iterator pos, InputIt (constexpr + first, InputIt last ); \fB(6)\fP since + C++20) + iterator insert( (since + const_iterator pos, \fB(7)\fP C++11) + std::initializer_list \fB(9)\fP (constexpr + ilist ); since + C++20) + template< class \fB(8)\fP (since + StringViewLike > C++17) + basic_string& insert( \fB(10)\fP (constexpr + size_type index, const since + StringViewLike& t ); C++20) + template< class + StringViewLike > + (since + basic_string& insert( C++17) + size_type index, const \fB(11)\fP (constexpr + StringViewLike& t, since + C++20) + + size_type t_index, size_type + count = npos ); Inserts characters into the string. - 1) Inserts count copies of character ch at the position index + 1) Inserts count copies of character ch at the position index. 2) Inserts null-terminated character string pointed to by s at the position index. - The length of the string is determined by the first null character (effectively - calls Traits::length(s). - 3) Inserts the first count characters from the character string pointed to by s at - the position index. s can contain null characters. - 4) Inserts string str at the position index - 5) Inserts a string, obtained by str.substr(index_str, count) at the position index - 6) Inserts character ch before the character pointed by pos - 7) Inserts count copies of character ch before the element pointed by pos - 8) Inserts characters from the range [first, last) before the element pointed by pos - 9) Inserts elements from initializer list ilist before the element pointed by pos + The length of the string is determined by the first null character using + Traits::length(s). + 3) Inserts the characters in the range [s, s + count) at the position index. The + range can contain null characters. + 4) Inserts string str at the position index. + 5) Inserts a string, obtained by str.substr(s_index, count) at the position index. + 6) Inserts character ch before the character pointed by pos. + 7) Inserts count copies of character ch before the element (if any) pointed by pos. + 8) Inserts characters from the range [first, last) before the element (if any) + pointed by pos, as if by insert(pos - begin(), basic_string(first, last, + get_allocator())). + + This overload does not participate in overload resolution if InputIt \fI(since C++11)\fP + does not satisfy LegacyInputIterator. + + 9) Inserts elements from initializer list ilist before the element (if any) pointed + by pos. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts the elements from sv before the element (if any) + pointed by index, as if by insert(index, sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 11) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts, before the element (if any) pointed by index, the + characters from the subview [t_index, t_index + count) of sv. + * If the requested subview lasts past the end of sv, or if count == npos, the + resulting subview is [t_index, sv.size()). + * If t_index > sv.size(), or if index > size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If pos is not a valid iterator on *this, the behavior is undefined. .SH Parameters @@ -57,44 +121,108 @@ s - pointer to the character string to insert str - string to insert first, last - range defining characters to insert - index_str - position of the first character in the string str to insert - ilist - initializer list to insert the characters from + s_index - position of the first character in str to insert + ilist - std::initializer_list to insert the characters from + t - object (convertible to std::basic_string_view) to insert the + characters from + t_index - position of the first character in t to insert .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value 1-5) *this 6-9) An iterator which refers to the copy of the first inserted character or pos if - no characters were inserted (count==0 or first==last or ilist.size()==0) + no characters were inserted (count == 0 or first == last or ilist.size() == 0) + 10,11) *this .SH Exceptions - 1) std::out_of_range if index > size() and std::length_error if size() + count > - max_size(). - 2) std::out_of_range if index > size() and std::length_error if size() + - Traits::length(s) > max_size(). - 3) std::out_of_range if index > size() and std::length_error if size() + count > - max_size(). - 4) Throws exceptions on the following conditions: - a) std::out_of_range if index > size(). - b) std::length_error if size() + str.size() > max_size() where ins_count is the - number of characters that will be inserted. - 5) Throws exceptions on the following conditions: - a) std::out_of_range if index > size(). - b) std::out_of_range if index_str > str.size(). - c) std::length_error if size() + ins_count > max_size() where ins_count is the - number of characters that will be inserted. - 6-9) \fI(none)\fP - - In any case, if an exception is thrown for any reason, this function has no effect - \fI(strong exception guarantee)\fP. - \fI(since C++11)\fP + 1-4,10) Throws std::out_of_range if index > size(). + 5) Throws std::out_of_range if index > size() or if s_index > str.size(). + 11) Throws std::out_of_range if index > size() or if t_index > sv.size(). + + In all cases, throws std::length_error if size() + ins_count > max_size() where + ins_count is the number of characters that will be inserted. + + In all cases, if std::allocator_traits::allocate throws an \fI(since C++20)\fP + exception, it is rethrown. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::string_literals; + + int main() + { + std::string s = "xmplr"; + + // insert(size_type index, size_type count, char ch) + s.insert(0, 1, 'E'); + assert("Exmplr" == s); + + // insert(size_type index, const char* s) + s.insert(2, "e"); + assert("Exemplr" == s); + + // insert(size_type index, string const& str) + s.insert(6, "a"s); + assert("Exemplar" == s); + + // insert(size_type index, string const& str, + // size_type s_index, size_type count) + s.insert(8, " is an example string."s, 0, 14); + assert("Exemplar is an example" == s); + + // insert(const_iterator pos, char ch) + s.insert(s.cbegin() + s.find_first_of('n') + 1, ':'); + assert("Exemplar is an: example" == s); + + // insert(const_iterator pos, size_type count, char ch) + s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '='); + assert("Exemplar is an:== example" == s); + + // insert(const_iterator pos, InputIt first, InputIt last) + { + std::string seq = " string"; + s.insert(s.begin() + s.find_last_of('e') + 1, + std::begin(seq), std::end(seq)); + assert("Exemplar is an:== example string" == s); + } + + // insert(const_iterator pos, std::initializer_list) + s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'}); + assert("Exemplar is an:== example string." == s); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 7 C++98 overload (8) referred to a non-existing refers to overload (4) + overload correctly + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2946 C++17 overload (10) caused ambiguity in some avoided by making it a + cases template .SH See also - append appends characters to the end - \fI(public member function)\fP - push_back appends a character to the end - \fI(public member function)\fP + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP diff --git a/man/std::basic_string::insert_range.3 b/man/std::basic_string::insert_range.3 new file mode 100644 index 000000000..172031ebb --- /dev/null +++ b/man/std::basic_string::insert_range.3 @@ -0,0 +1,84 @@ +.TH std::basic_string::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert_range \- std::basic_string::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr iterator insert_range( const_iterator pos, R&& rg ); + + Inserts characters from the range rg before the element (if any) pointed by pos. + + Equivalent to + + return insert(pos - begin(), + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + pos - iterator before which the characters will be inserted + rg - a container compatible range + +.SH Return value + + An iterator which refers to the first inserted character, or pos if no characters + were inserted because rg was empty. + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If std::allocator_traits::allocate throws an exception, it is rethrown. + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto source = {'l', 'i', 'b', '_'}; + std::string target{"__cpp_containers_ranges"}; + // ^insertion will occur + // before this position + + const auto pos = target.find("container"); + assert(pos != target.npos); + auto iter = std::next(target.begin(), pos); + + #ifdef __cpp_lib_containers_ranges + target.insert_range(iter, source); + #else + target.insert(iter, source.begin(), source.end()); + #endif + + assert(target == "__cpp_lib_containers_ranges"); + // ^^^^ + } + +.SH See also + + insert inserts characters + \fI(public member function)\fP diff --git a/man/std::basic_string::max_size.3 b/man/std::basic_string::max_size.3 index 0c8643cce..806a1dd4a 100644 --- a/man/std::basic_string::max_size.3 +++ b/man/std::basic_string::max_size.3 @@ -1,6 +1,10 @@ -.TH std::basic_string::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::max_size \- std::basic_string::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) + (constexpr since C++20) Returns the maximum number of elements the string is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -12,20 +16,77 @@ .SH Return value - Maximum number of characters - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Maximum number of characters. .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + #include + + template + void print_basic_string_max_size() + { + std::basic_string s; + auto max_size = s.max_size(); + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "basic_string<" << boost::core::demangle(typeid(T).name()) + << ">:\\n\\t" << max_size << " = "; + std::cout << std::setprecision(3) << (double) max_size << " = "; + std::cout.imbue(std::locale("C")); + std::cout << std::hex << std::setfill('0') << "0x" + << std::setw(sizeof(typename decltype(s)::size_type) << 1) + << max_size << '\\n' << std::dec; + }; + + int main() + { + std::cout << "Pointer size: " << CHAR_BIT * sizeof(void*) << " bits\\n" + "Maximum sizes:\\n"; + + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + + using CharT = std::array; + print_basic_string_max_size(); + } + +.SH Possible output: + + Pointer size: 64 bits + Maximum sizes: + basic_string: + 9,223,372,036,854,775,807 = 9.22e+18 = 0x7fffffffffffffff + basic_string: + 4,611,686,018,427,387,903 = 4.61e+18 = 0x3fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 1,152,921,504,606,846,975 = 1.15e+18 = 0x0fffffffffffffff + basic_string>: + 13,848,906,962,244,407 = 1.38e+16 = 0x00313381ec031337 + .SH See also - size returns the number of characters - length \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::npos.3 b/man/std::basic_string::npos.3 index 3aed07258..cb8bcc779 100644 --- a/man/std::basic_string::npos.3 +++ b/man/std::basic_string::npos.3 @@ -1,4 +1,7 @@ -.TH std::basic_string::npos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::npos \- std::basic_string::npos + .SH Synopsis static const size_type npos = -1; @@ -7,27 +10,34 @@ end of string indicator by the functions that expect a string index or as the error indicator by the functions that return a string index. +.SH Note + + Although the definition uses -1, size_type is an unsigned integer type, and the + value of npos is the largest positive value it can hold, due to signed-to-unsigned + implicit conversion. This is a portable way to specify the largest value of any + unsigned type. + .SH Example - + // Run this code - #include #include + #include #include - + int main() { // string search functions return npos if nothing is found std::string s = "test"; - if(s.find('a') == std::string::npos) + if (s.find('a') == s.npos) std::cout << "no 'a' in 'test'\\n"; - + // functions that take string subsets as arguments // use npos as the "all the way to the end" indicator std::string s2(s, 2, std::string::npos); std::cout << s2 << '\\n'; - + std::bitset<5> b("aaabb", std::string::npos, 'a', 'b'); std::cout << b << '\\n'; } @@ -37,3 +47,9 @@ no 'a' in 'test' st 00011 + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant of std::basic_string_view)\fP + diff --git a/man/std::basic_string::operator+=.3 b/man/std::basic_string::operator+=.3 index d6ba70c1d..6f5ea9049 100644 --- a/man/std::basic_string::operator+=.3 +++ b/man/std::basic_string::operator+=.3 @@ -1,26 +1,36 @@ -.TH std::basic_string::operator+= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - basic_string& operator+=( const basic_string& str ); \fB(1)\fP - basic_string& operator+=( CharT ch ); \fB(2)\fP - basic_string& operator+=( const CharT* s ); \fB(3)\fP - basic_string& operator+=( std::initializer_list ilist ); \fB(4)\fP \fI(since C++11)\fP - - Appends addinional characters to the string. - - 1) Appends string str - - 2) Appends character ch +.TH std::basic_string::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator+= \- std::basic_string::operator+= +.SH Synopsis + basic_string& operator+=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator+=( CharT ch ); \fB(2)\fP (constexpr since C++20) + basic_string& operator+=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator+=( std::initializer_list \fB(4)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template< class StringViewLike > \fB(5)\fP \fI(since C++17)\fP + basic_string& operator+=( const StringViewLike& t ); (constexpr since C++20) + + Appends additional characters to the string. + + 1) Appends string str. + 2) Appends character ch. 3) Appends the null-terminated character string pointed to by s. - 4) Appends characters in the initializer list ilist. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends characters in the string view sv as if by append(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. .SH Parameters - ch - character value to append - str - string to append - s - pointer to a null-terminated character string to append - init - initializer list with the characters to append + str - string to append + ch - character value to append + s - pointer to a null-terminated character string to append + ilist - std::initializer_list with the characters to append + t - object (convertible to std::basic_string_view) with the characters to append .SH Return value @@ -28,57 +38,83 @@ .SH Complexity - 1) linear in size of str - - 2) constant - - 3) linear in size of s - - 4) linear in size of init + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). .SH Exceptions + If the operation would result in size() > max_size(), throws std::length_error. + If an exception is thrown for any reason, this function has no effect (strong - exception guarantee). - \fI(since C++11)\fP + exception safety guarantee). - If the operation would result in size() > max_size(), throws std::length_error. +.SH Notes + + Overload \fB(2)\fP can accept any types that are implicitly convertible to CharT. For + std::string, where CharT is char, the set of acceptable types includes all + arithmetic types. This may have unintended effects. .SH Example - + // Run this code + #include #include #include - + int main() { - std::string str; - str.reserve(50); //reserves sufficient storage space to avoid memory reallocation - std::cout << str << '\\n'; //empty string - - str += "This"; - std::cout << str << '\\n'; - - str += std::string(" is "); - std::cout << str << '\\n'; - - str += 'a'; - std::cout << str << '\\n'; - - str += {' ','s','t','r','i','n','g','.'}; - std::cout << str << '\\n'; + std::string str; + + // reserve sufficient storage space to avoid memory reallocation + str.reserve(50); + + std::cout << std::quoted(str) << '\\n'; // empty string + + str += "This"; + std::cout << std::quoted(str) << '\\n'; + + str += std::string(" is "); + std::cout << std::quoted(str) << '\\n'; + + str += 'a'; + std::cout << std::quoted(str) << '\\n'; + + str += {' ', 's', 't', 'r', 'i', 'n', 'g', '.'}; + std::cout << std::quoted(str) << '\\n'; + + str += 69.96; // Equivalent to str += static_cast(69.96); + // 'E' (ASCII code 69) is appended by overload (2), + // which might not be the intent. + + // To add a numeric value, consider std::to_string(): + str += std::to_string(1729); + + std::cout << std::quoted(str) << '\\n'; } .SH Output: - This - This is - This is a - This is a string. + "" + "This" + "This is " + "This is a" + "This is a string." + "This is a string.E1729" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template .SH See also - assign assign characters to a string - \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::basic_string::operator=.3 b/man/std::basic_string::operator=.3 index 0b9fd99d1..70b37150d 100644 --- a/man/std::basic_string::operator=.3 +++ b/man/std::basic_string::operator=.3 @@ -1,31 +1,49 @@ -.TH std::basic_string::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator= \- std::basic_string::operator= + .SH Synopsis - basic_string& operator=( const basic_string& str ); \fB(1)\fP - basic_string& operator=( basic_string&& str ); \fB(2)\fP \fI(since C++11)\fP - basic_string& operator=( const CharT* s ); \fB(3)\fP - basic_string& operator=( CharT ch ); \fB(4)\fP - basic_string& operator=( std::initializer_list ilist ); \fB(5)\fP \fI(since C++11)\fP + basic_string& operator=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator=( basic_string&& str ) \fB(2)\fP \fI(since C++11)\fP + noexcept(/* see below */); (constexpr since C++20) + basic_string& operator=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator=( CharT ch ); \fB(4)\fP (constexpr since C++20) + basic_string& operator=( std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template \fB(6)\fP \fI(since C++17)\fP + basic_string& operator=( const StringViewLike& t ); (constexpr since C++20) + basic_string& operator=( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) Replaces the contents of the string. 1) Replaces the contents with a copy of str. If *this and str are the same object, this function has no effect. - 2) Replaces the contents with those of str using move semantics. Leaves str in - valid, but inspecified state. The behavior is undefined if *this and str are the - same object. + 2) Replaces the contents with those of str using SequenceContainer's move assignment + semantics. + Unlike other sequence container move assignments, references, pointers, and + iterators to elements of str may be invalidated. 3) Replaces the contents with those of null-terminated character string pointed to - by s as if by *this = basic_string(s), which involves a call to Traits::length(s). - 4) Replaces the contents with character ch as if by *this = basic_string(1,c) - 5) Replaces the contents with those of the initializer list ilist as if by *this = - basic_string(ilist) + by s as if by assign(s, Traits::length(s)). + 4) Replaces the contents with character ch as if by assign(std::addressof(ch), 1). + 5) Replaces the contents with those of the initializer list ilist as if by + assign(ilist.begin(), ilist.size()). + 6) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of the sv as if by + assign(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 7) std::basic_string cannot be assigned from nullptr. .SH Parameters - ch - value to initialize characters of the string with - str - string to be used as source to initialize the string with - s - pointer to a null-terminated character string - to use as source to initialize the string with - init - initializer list to initialize the string with + ch - value to initialize characters of the string with + str - string to be used as source to initialize the string with + s - pointer to a null-terminated character string to use as source to initialize + the string with + ilist - std::initializer_list to initialize the string with + t - object convertible to std::basic_string_view to initialize the string with .SH Return value @@ -33,36 +51,103 @@ .SH Complexity - 1) linear in size of str + 1) Linear in size of str. + 2) Linear in the size of *this (formally, each CharT has to be destroyed). If + allocators do not compare equal and do not propagate, then also linear in the size + of str (copy must be made). + 3) Linear in size of s. + 4) Constant. + 5) Linear in size of ilist. + 6) Linear in size of t. - 2) constant. If alloc is given and alloc != other.get_allocator(), then linear. +.SH Exceptions - 3) linear in size of s + 2) + noexcept specification: + noexcept(std::allocator_traits:: - 4) constant. + propagate_on_container_move_assignment::value || - 5) linear in size of init + std::allocator_traits::is_always_equal::value) -.SH Exceptions + If the operation would result in size() > max_size(), throws std::length_error. If an exception is thrown for any reason, this function has no effect (strong - exception guarantee). - \fI(since C++11)\fP - - If the operation would result in size() > max_size(), throws std::length_error. + exception safety guarantee). .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + std::string str1; + std::string str2{"alpha"}; + + // (1) operator=(const basic_string&); + str1 = str2; + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "alpha" + + // (2) operator=(basic_string&&); + str1 = std::move(str2); + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "" or "alpha" (unspecified) + + // (3) operator=(const CharT*); + str1 = "beta"; + std::cout << std::quoted(str1) << '\\n'; // "beta" + + // (4) operator=(CharT); + str1 = '!'; + std::cout << std::quoted(str1) << '\\n'; // "!" + + // (5) operator=(std::initializer_list); + str1 = {'g', 'a', 'm', 'm', 'a'}; + std::cout << std::quoted(str1) << '\\n'; // "gamma" + + // (6) operator=(const T&); + str1 = 35U; // equivalent to str1 = static_cast(35U); + std::cout << std::quoted(str1) << '\\n'; // "#" (ASCII = 35) + } + +.SH Possible output: + + "alpha" "alpha" + "alpha" "" + "beta" + "!" + "gamma" + "#" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + the move assignment operator did not + LWG 2063 C++11 follow follows + SequenceContainer's semantic requirement + LWG 2946 C++17 overload \fB(6)\fP caused ambiguity in some avoided by making it a + cases template .SH See also constructor constructs a basic_string - \fI(public member function)\fP + \fI(public member function)\fP assign assign characters to a string - \fI(public member function)\fP + \fI(public member function)\fP + assigns a view + operator= \fI(public member function of std::basic_string_view)\fP -.SH Category: - * Todo no example +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::operator[].3 b/man/std::basic_string::operator[].3 index 0b8ac8c26..8fa941e51 100644 --- a/man/std::basic_string::operator[].3 +++ b/man/std::basic_string::operator[].3 @@ -1,19 +1,20 @@ -.TH std::basic_string::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator[] \- std::basic_string::operator[] + .SH Synopsis - reference operator[]( size_type pos ); - const_reference operator[]( size_type pos ) const; + CharT& operator[]( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& operator[]( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos if pos < size(), or a + reference to CharT() if pos == size(). No bounds checking is performed. - Returns a reference to the character at specified location pos. No bounds checking - is performed. + If pos > size(), the behavior is undefined. - 1) If pos == size(), the behavior is undefined. - 2) If pos == size(), a reference to the character with value CharT() \fI(until C++11)\fP - (the null character) is returned. - If pos == size(), a reference to the character with value CharT() (the - null character) is returned. - \fI(since C++11)\fP - For the first (non-const) version,the behavior is undefined if this - character is modified. + For overload \fB(1)\fP, if pos == size(), the behavior is undefined + if the object referred by the returned reference is modified to any value other than + CharT() + \fI(since C++11)\fP. .SH Parameters @@ -21,13 +22,62 @@ .SH Return value - Reference to the requested character. + *(begin() + pos) if pos < size(), or a reference to CharT() if pos == size(). .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string e("Exemplar"); + for (unsigned i = e.length() - 1; i != 0; i /= 2) + std::cout << e[i]; + std::cout << '\\n'; + + const char* c = &e[0]; + std::cout << c << '\\n'; // print as a C string + + // Change the last character of s into a 'y' + std::string s("Exemplar "); + s[s.size() - 1] = 'y'; // equivalent to s.back() = 'y'; + std::cout << s << '\\n'; + } + +.SH Output: + + rmx + Exemplar + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 259 C++98 non-const overload could return const lvalue changed to return + data()[pos], which was ill-formed *(begin() + pos) + if pos == size(), the behavior of modifying + LWG 2475 C++11 the well-defined if + object referred by the returned reference modified to CharT() + was undefined + .SH See also - at access specified character with bounds checking - \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::operatorbasic_string_view.3 b/man/std::basic_string::operatorbasic_string_view.3 new file mode 100644 index 000000000..7860d59f8 --- /dev/null +++ b/man/std::basic_string::operatorbasic_string_view.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::operatorbasic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operatorbasic_string_view \- std::basic_string::operatorbasic_string_view + +.SH Synopsis + operator std::basic_string_view() const \fI(since C++17)\fP + noexcept; (constexpr since C++20) + + Returns a std::basic_string_view, constructed as if by std::basic_string_view(data(), size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A string view representing the entire contents of the string. + +.SH Notes + + It is the programmer's responsibility to ensure that the resulting string view does + not outlive the string. + + std::string get_string(); + int f(std::string_view sv); + + int x = f(get_string()); // OK + std::string_view sv = get_string(); // Bad: holds a dangling pointer + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_wstring_size(std::wstring_view wcstr_v) + { + std::cout << wcstr_v.size() << " code points\\n"; + } + + int main() + { + std::string cppstr = "ラーメン"; // narrow string + std::wstring wcstr = L"ラーメン"; // wide string + + // Implicit conversion from string to string_view + // via std::string::operator string_view: + std::string_view cppstr_v = cppstr; + + std::cout << cppstr_v << '\\n' + << cppstr_v.size() << " code units\\n"; + + // Implicit conversion from wstring to wstring_view + // via std::wstring::operator wstring_view: + show_wstring_size(wcstr); + } + +.SH Output: + + ラーメン + 12 code units + 4 code points + +.SH See also + + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::basic_string::pop_back.3 b/man/std::basic_string::pop_back.3 index 2a2b7dd20..1ef904042 100644 --- a/man/std::basic_string::pop_back.3 +++ b/man/std::basic_string::pop_back.3 @@ -1,9 +1,14 @@ -.TH std::basic_string::pop_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::pop_back \- std::basic_string::pop_back + .SH Synopsis - void pop_back(); \fI(since C++11)\fP + void pop_back(); (constexpr since C++20) Removes the last character from the string. + Equivalent to erase(end() - 1). The behavior is undefined if the string is empty. + .SH Parameters \fI(none)\fP @@ -18,9 +23,53 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. + +.SH Notes + + In libstdc++, pop_back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string str("Short string!"); + std::cout << "before=" << std::quoted(str) << '\\n'; + assert(str.size() == 13); + + str.pop_back(); + std::cout << " after=" << std::quoted(str) << '\\n'; + assert(str.size() == 12); + + str.clear(); + // str.pop_back(); // undefined behavior + } + +.SH Output: + + before="Short string!" + after="Short string" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function pop_back() .SH See also push_back appends a character to the end - \fI(public member function)\fP + \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP diff --git a/man/std::basic_string::push_back.3 b/man/std::basic_string::push_back.3 index b25832daf..122b1e8fe 100644 --- a/man/std::basic_string::push_back.3 +++ b/man/std::basic_string::push_back.3 @@ -1,6 +1,9 @@ -.TH std::basic_string::push_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::push_back \- std::basic_string::push_back + .SH Synopsis - void push_back( CharT ch ); + void push_back( CharT ch ); (constexpr since C++20) Appends the given character ch to the end of the string. @@ -18,13 +21,48 @@ .SH Exceptions + If the operation would result in size() > max_size(), throws std::length_error. + If an exception is thrown for any reason, this function has no effect (strong - exception guarantee). - \fI(since C++11)\fP + exception safety guarantee). - If the operation would result in size() > max_size(), throws std::length_error. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str{"Short string"}; + std::cout << "1) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + + str.push_back('!'); + std::cout << "2) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + } + +.SH Output: + + 1) "Short string", size: 12 + 2) "Short string!", size: 13 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + \fB(1)\fP the description was missing in + LWG 7 C++98 the C++ standard \fB(1)\fP description added + \fB(2)\fP the parameter type was const (2) changed to CharT + CharT + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee .SH See also pop_back removes the last character - \fI(C++11)\fP \fI(public member function)\fP + (DR*) \fI(public member function)\fP diff --git a/man/std::basic_string::rbegin,.3 b/man/std::basic_string::rbegin,.3 new file mode 100644 index 000000000..eecaa5142 --- /dev/null +++ b/man/std::basic_string::rbegin,.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rbegin, \- std::basic_string::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the first character of the reversed string. It + corresponds to the last character of the non-reversed string. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemplar!"); + *s.rbegin() = 'y'; + std::cout << s << '\\n'; // "Exemplary" + + std::string c; + std::copy(s.crbegin(), s.crend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "yralpmexE" + } + +.SH Output: + + Exemplary + yralpmexE + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::rbegin,std::basic_string::crbegin.3 b/man/std::basic_string::rbegin,std::basic_string::crbegin.3 deleted file mode 100644 index d6f9254cb..000000000 --- a/man/std::basic_string::rbegin,std::basic_string::crbegin.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::basic_string::rbegin,std::basic_string::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP - - Returns a reverse iterator to the first character of the reversed string. It - corresponds to the last character of the non-reversed string. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - reverse iterator to the first character - -.SH Complexity - - Constant - -.SH See also - - rend returns a reverse iterator to the end - crend \fI(public member function)\fP - \fI(C++11)\fP diff --git a/man/std::basic_string::rend,.3 b/man/std::basic_string::rend,.3 new file mode 100644 index 000000000..c28ff3818 --- /dev/null +++ b/man/std::basic_string::rend,.3 @@ -0,0 +1,70 @@ +.TH std::basic_string::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rend, \- std::basic_string::rend, + +.SH Synopsis + + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the character following the last character of the + reversed string. It corresponds to the character preceding the first character of + the non-reversed string. This character acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string p("[A man, a plan, a canal: Panama]"); + std::string q; + + std::copy(p.crbegin(), p.crend(), std::back_inserter(q)); + std::cout << "q = " << q << '\\n'; + + std::copy(q.crbegin(), q.crend(), p.rbegin()); + std::cout << "p = " << p << '\\n'; + } + +.SH Output: + + q = ]amanaP :lanac a ,nalp a ,nam A[ + p = ]amanaP :lanac a ,nalp a ,nam A[ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::rend,std::basic_string::crend.3 b/man/std::basic_string::rend,std::basic_string::crend.3 deleted file mode 100644 index 76ad27369..000000000 --- a/man/std::basic_string::rend,std::basic_string::crend.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH std::basic_string::rend,std::basic_string::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP - - Returns a reverse iterator to the character following the last character of the - reversed string. It corresponds to the character preceding the first character of - the non-reversed string. This character acts as a placeholder, attempting to access - it results in undefined behavior. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - reverse iterator to the character following the last character - -.SH Complexity - - Constant - -.SH See also - - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP - \fI(C++11)\fP diff --git a/man/std::basic_string::replace.3 b/man/std::basic_string::replace.3 index 9074c0fa4..7b1e79fc7 100644 --- a/man/std::basic_string::replace.3 +++ b/man/std::basic_string::replace.3 @@ -1,64 +1,121 @@ -.TH std::basic_string::replace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - basic_string& replace( size_type pos, size_type count, - - const basic_string& str ); - \fB(1)\fP - basic_string& replace( const_iterator first, const_iterator - last, - - const basic_string& str ); - basic_string& replace( size_type pos, size_type count, - - const basic_string& str, \fI(until C++14)\fP - - size_type pos2, size_type count2 ); - basic_string& replace( size_type pos, size_type count, - - const basic_string& str, \fI(since C++14)\fP +.TH std::basic_string::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace \- std::basic_string::replace - size_type pos2, size_type count2 = npos +.SH Synopsis + basic_string& replace( size_type pos, + size_type count, \fB(1)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(2)\fP (constexpr since + const basic_string& str C++20) ); + basic_string& replace( size_type pos, + size_type count, + + const basic_string& \fI(until C++14)\fP + str, + + size_type pos2, + size_type count2 ); + basic_string& replace( size_type pos, + size_type count, + \fI(since C++14)\fP + const basic_string& (constexpr since + str, C++20) + + size_type pos2, + size_type count2 = npos ); + basic_string& replace( size_type pos, + size_type count, \fB(4)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(5)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( size_type pos, (constexpr since + size_type count, \fB(6)\fP C++20) + const CharT* cstr ); + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(7)\fP C++20) + const CharT* cstr ); + basic_string& replace( size_type pos, + size_type count, \fB(8)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(3)\fP \fB(9)\fP (constexpr since + size_type count2, CharT C++20) + ch ); template< class InputIt > - basic_string& replace( const_iterator first, const_iterator \fB(2)\fP - last, - - InputIt first2, InputIt last2 ); - basic_string& replace( size_type pos, size_type count, \fB(3)\fP - const CharT* cstr, size_type count2 ); \fB(2)\fP - basic_string& replace( const_iterator first, const_iterator - last, \fB(3)\fP - const CharT* cstr, size_type count2 ); - basic_string& replace( size_type pos, size_type count, - - const CharT* cstr ); - \fB(4)\fP - basic_string& replace( const_iterator first, const_iterator - last, + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(10)\fP C++20) + + InputIt first2, InputIt + last2 ); + basic_string& replace( const_iterator first, \fI(since C++11)\fP + const_iterator last, \fB(11)\fP (constexpr since + C++20) + std::initializer_list ilist ); + template< class StringViewLike > + + basic_string& replace( size_type pos, \fI(since C++17)\fP + size_type count, \fB(12)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > - const CharT* cstr ); - basic_string& replace( size_type pos, size_type count, \fB(5)\fP - size_type count2, CharT ch ); - basic_string& replace( const_iterator first, const_iterator - last, \fB(5)\fP - size_type count2, CharT ch ); - basic_string& replace( const_iterator first, const_iterator - last, \fB(6)\fP \fI(since C++11)\fP - std::initializer_list ilist ); - - Replaces the part of the string indicated by either [pos, pos + count) or [first, - last) with a new string. - - The new string can be one of: - - 1) string str; - 2) substring [pos2, pos2 + count2) of str or characters in the range [first2, - last2); - 3) first count2 charcters of the character string pointed to by cstr; - 4) null-terminated character string pointed to by cstr; - 5) count2 copies of character ch; - 6) characters in the initializer list ilist; + basic_string& replace( const_iterator first, \fI(since C++17)\fP + const_iterator last, \fB(13)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( size_type pos, + size_type count, \fI(since C++17)\fP + const StringViewLike& \fB(14)\fP (constexpr since + t, C++20) + + size_type pos2, + size_type count2 = npos ); + + Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count, + size())) or [first, last) with given characters. + + 1,2) Those characters are replaced with str. + 3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2, + str.size())) of str. + 4,5) Those characters are replaced with the characters in the range [cstr, cstr + + count2). + If [cstr, cstr + count2) is not a valid range, the behavior is undefined. + 6,7) Those characters are replaced with the characters in the range [cstr, cstr + + Traits::length(cstr)). + 8,9) Those characters are replaced with count2 copies of ch. + 10) Those characters are replaced with the characters in the range [first2, last2) + as if by replace(first, last, basic_string(first2, last2, get_allocator())). + 11) Those characters are replaced with the characters in ilist. + 12,13) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then those characters are replaced + with the characters from sv. + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 14) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then those characters are replaced with the characters from the + subview sv.substr(pos2, count2). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If [begin(), first) or [first, last) is not a valid range, the behavior is + undefined. .SH Parameters @@ -71,45 +128,57 @@ cstr - pointer to the character string to use for replacement ch - character value to use for replacement first2, last2 - range of characters to use for replacement - init - initializer list with the characters to use for replacement + ilist - initializer list with the characters to use for replacement + t - object (convertible to std::basic_string_view) with the characters + to use for replacement .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - *this + *this. .SH Exceptions - std::out_of_range if pos > length() or pos2 > str.length() + 1) Throws std::out_of_range if pos > size(). + 3) Throws std::out_of_range if pos > size() or pos2 > str.size(). + 4,6,8) Throws std::out_of_range if pos > size(). + 12,14) Throws std::out_of_range if pos > size(). - std::length_error if the resulting string will exceed maximum possible string length - (std::string::npos - 1) + If the operation would result in size() > max_size(), throws std::length_error. - In any case, if an exception is thrown for any reason, this function has no effect - \fI(strong exception guarantee)\fP. - \fI(since C++11)\fP + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). .SH Example - -// Run this code - - #include - #include - - int main() - { - std::string str("The quick brown fox jumps over the lazy dog."); - - str.replace(10, 5, "red"); // (4) - - str.replace(str.begin(), str.begin() + 3, 1, 'A'); // (5) - - std::cout << str << '\\n'; - } - -.SH Output: - - A quick red fox jumps over the lazy dog. + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 1323 C++98 the types of first and last changed to const_iterator + were iterator + LWG 2946 C++17 overloads (12,13) caused avoided by making them templates + ambiguity in some cases + +.SH See also + + replace_with_range replaces specified portion of a string with a range of characters + (C++23) \fI(public member function)\fP + regex_replace replaces occurrences of a regular expression with formatted + \fI(C++11)\fP replacement text + \fI(function template)\fP + replace replaces all values satisfying specific criteria with another + replace_if value + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_string::replace_with_range.3 b/man/std::basic_string::replace_with_range.3 new file mode 100644 index 000000000..a06106cbc --- /dev/null +++ b/man/std::basic_string::replace_with_range.3 @@ -0,0 +1,91 @@ +.TH std::basic_string::replace_with_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace_with_range \- std::basic_string::replace_with_range + +.SH Synopsis + template< container-compatible-range R > + + constexpr std::basic_string& replace_with_range( const_iterator + first, (since C++23) + const_iterator last, + + R&& rg ); + + Replaces the characters in the range [first, last) with the characters from the + range rg. + + Equivalent to + + return replace(first, + last, + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + first, last - range of characters that is going to be replaced + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + auto s{"Today is today!"s}; + constexpr auto today{"today"sv}; + constexpr auto tomorrow{"tomorrow's yesterday"sv}; + std::forward_list rg; + std::ranges::reverse_copy(tomorrow, std::front_inserter(rg)); + + const auto pos{s.rfind(today)}; + assert(pos != s.npos); + const auto first{std::next(s.begin(), pos)}; + const auto last{std::next(first, today.length())}; + + #ifdef __cpp_lib_containers_ranges + s.replace_range(first, last, rg); + #else + s.replace(first, last, rg.cbegin(), rg.cend()); + #endif + + assert("Today is tomorrow's yesterday!" == s); + } + +.SH See also + + replace replaces specified portion of a string + \fI(public member function)\fP diff --git a/man/std::basic_string::reserve.3 b/man/std::basic_string::reserve.3 index d7ff8e25e..3f0d1423a 100644 --- a/man/std::basic_string::reserve.3 +++ b/man/std::basic_string::reserve.3 @@ -1,14 +1,32 @@ -.TH std::basic_string::reserve 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::reserve \- std::basic_string::reserve + .SH Synopsis - void reserve( size_type new_cap ); + void reserve( size_type new_cap = 0 ); \fI(until C++20)\fP + constexpr void reserve( size_type new_cap ); \fI(since C++20)\fP + \fB(1)\fP \fI(since C++20)\fP + void reserve(); \fB(2)\fP (deprecated in C++20) + (removed in C++26) + + 1) Informs a std::basic_string object of a planned change in size, so that it can + manage the storage allocation appropriately. + * If new_cap is greater than the current capacity(), new storage is allocated, and + capacity() is made equal or greater than new_cap. - Increase the capacity of the string to a value that's greater or equal to new_cap. - If new_cap is greater than the current capacity(), new storage is allocated, - otherwise the method does nothing. + * If new_cap is less than the current capacity(), this is a + non-binding shrink request. + * If new_cap is less than the current size(), this is a non-binding \fI(until C++20)\fP + shrink-to-fit request + equivalent to shrink_to_fit() + \fI(since C++11)\fP. + * If new_cap is less than or equal to the current capacity(), there \fI(since C++20)\fP + is no effect. - If new_cap is greater than capacity(), all iterators and references, including the - past-the-end iterator, are invalidated. Otherwise, no iterators or references are - invalidated. + If a capacity change takes place, all iterators and references, including the + past-the-end iterator, are invalidated. + 2) A non-binding shrink-to-fit request. After this call, capacity() has an + unspecified value greater than or equal to size(). .SH Parameters @@ -18,17 +36,77 @@ \fI(none)\fP +.SH Exceptions + + Throws std::length_error if new_cap is greater than max_size(). + + May throw any exceptions thrown by std::allocator_traits::allocate(), + such as std::bad_alloc. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + .SH Complexity - At most linear in the size() of the string + At most linear in the size() of the string. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + std::cout << "1) Initially: " << s.capacity() << '\\n'; + + const std::string::size_type new_cap{101u}; + s.reserve(new_cap); + assert(s.capacity() >= new_cap); + std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\\n'; + + // observing the capacity growth factor + auto cap{s.capacity()}; + for (int check{}; check != 4; ++check) + { + while (cap == s.capacity()) + s += '$'; + cap = s.capacity(); + std::cout << (3) + check << ") Capacity: " << cap << '\\n'; + } + + // s.reserve(); // deprecated/removed in C++20/26, use: + s.shrink_to_fit(); + std::cout << "7) After shrink_to_fit: " << s.capacity() << '\\n'; + } + +.SH Possible output: + + 1) Initially: 15 + 2) After reserve(101): 101 + 3) Capacity: 202 + 4) Capacity: 404 + 5) Capacity: 808 + 6) Capacity: 1616 + 7) After shrink_to_fit: 809 + + Defect reports -.SH Notes + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - reserve() cannot be used to reduce the capacity of the container; to that end - shrink_to_fit() is provided. + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee .SH See also returns the number of characters that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::basic_string::resize.3 b/man/std::basic_string::resize.3 index ec5b21e51..3b4c7a8b6 100644 --- a/man/std::basic_string::resize.3 +++ b/man/std::basic_string::resize.3 @@ -1,18 +1,21 @@ -.TH std::basic_string::resize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize \- std::basic_string::resize + .SH Synopsis - void resize( size_type count ); \fB(1)\fP - void resize( size_type count, CharT ch ); \fB(2)\fP + void resize( size_type count ); \fB(1)\fP (constexpr since C++20) + void resize( size_type count, CharT ch ); \fB(2)\fP (constexpr since C++20) Resizes the string to contain count characters. - If the current size is less than count, additional characters are appended. + If the current size is less than count, additional characters are appended: + + 1) Initializes appended characters to CharT() ('\\0' if CharT is char). + 2) Initializes appended characters to ch. If the current size is greater than count, the string is reduced to its first count elements. - The first version initializes new characters to CharT(), the second version - initializes new characters to ch. - .SH Parameters count - new size of the string @@ -28,56 +31,110 @@ Allocator. If an exception is thrown for any reason, this function has no effect (strong - exception guarantee). - \fI(since C++11)\fP + exception safety guarantee). .SH Example - + // Run this code + #include #include #include - + int main() { + const unsigned desired_length{8}; + std::string long_string("Where is the end?"); + std::string short_string("H"); + + std::cout << "Basic functionality:\\n" + << "Shorten:\\n" + << "1. Before: " << std::quoted(long_string) << '\\n'; + long_string.resize(desired_length); + std::cout << "2. After: " << std::quoted(long_string) << '\\n'; + + std::cout << "Lengthen with a given value 'a':\\n" + << "3. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length, 'a'); + std::cout << "4. After: " << std::quoted(short_string) << '\\n'; + + std::cout << "Lengthen with char() == " << static_cast(char()) << '\\n' + << "5. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length + 3); + std::cout << "6. After: \\""; + for (char c : short_string) + std::cout << (c == char() ? '@' : c); + std::cout << "\\"\\n\\n"; + + std::cout << "Errors:\\n"; std::string s; - - try { + + try + { // size is OK, no length_error // (may throw bad_alloc) s.resize(s.max_size() - 1, 'x'); - } catch (std::bad_alloc&) { - std::cout << "1. bad alloc\\n"; } - - try { + catch (const std::bad_alloc& ex) + { + std::cout << "1. Exception: " << ex.what() << '\\n'; + } + + try + { // size is OK, no length_error // (may throw bad_alloc) s.resize(s.max_size(), 'x'); - } catch (std::bad_alloc& exc) { - std::cout << "2. bad alloc\\n"; } - - try { + catch (const std::bad_alloc& ex) + { + std::cout << "2. Exception: " << ex.what() << '\\n'; + } + + try + { // size is BAD, throw length_error s.resize(s.max_size() + 1, 'x'); - } catch (std::length_error&) { - std::cout << "3. length error\\n"; + } + catch (const std::length_error& ex) + { + std::cout << "3. Length error: " << ex.what() << '\\n'; } } .SH Possible output: - 1. bad alloc - 2. bad alloc - 3. length error + Basic functionality: + Shorten: + 1. Before: "Where is the end?" + 2. After: "Where is" + Lengthen with a given value 'a': + 3. Before: "H" + 4. After: "Haaaaaaa" + Lengthen with char() == 0 + 5. Before: "Haaaaaaa" + 6. After: "Haaaaaaa@@@" + + Errors: + 1. Exception: std::bad_alloc + 2. Exception: std::bad_alloc + 3. Length error: basic_string::_M_replace_aux + + Defect reports -.SH Complexity + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the string. + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee .SH See also - size returns the number of characters - length \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP diff --git a/man/std::basic_string::resize_and_overwrite.3 b/man/std::basic_string::resize_and_overwrite.3 new file mode 100644 index 000000000..192feef8a --- /dev/null +++ b/man/std::basic_string::resize_and_overwrite.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::resize_and_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize_and_overwrite \- std::basic_string::resize_and_overwrite + +.SH Synopsis + template< class Operation > (since C++23) + constexpr void resize_and_overwrite( size_type count, Operation op ); + + Resizes the string to contain at most count characters, using the user-provided + operation op to modify the possibly indeterminate contents and set the length. This + avoids the cost of initializing a suitably-sized std::string when it is intended to + be used as a char array to be populated by, e.g., a C API call. + + This function performs following steps: + + 1. Obtains contiguous storage that contains count + 1 characters, and makes its + first k characters equal to the first k characters of *this, where k is the + smaller of count and the result of this->size() before the call to + resize_and_overwrite. Let p denote the pointer to the first character in the + storage. + * The equality is determined as if by checking this->compare(0, k, p, k) == + 0. + * The characters in [p + k, p + count] may have indeterminate values. + 2. Evaluates std::move(op)(p, count). Let r be the return value of std::move(op)(p, + count). + 3. Replaces the contents of *this with [p, p + r) (which sets the length of *this + to r). Invalidates all pointers and references to the range [p, p + count]. + + The program is ill-formed if r does not have an integer-like type. The behavior is + undefined if std::move(op)(p, count) throws an exception or modifies p or count, r + is not in the range [0, count], or any character in range [p, p + r) has an + indeterminate value. + + Implementations are recommended to avoid unnecessary copies and allocations by, + e.g., making p equal to the pointer to beginning of storage of characters allocated + for *this after the call, which can be identical to the existing storage of *this if + count is less than or equal to this->capacity(). + +.SH Parameters + + count - the maximal possible new size of the string + op - the function object used for setting the new contents of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > this->max_size(). Any exceptions thrown by + corresponding Allocator. + + If an exception is thrown from std::move(op)(p, count), the behavior is undefined. + Otherwise, if an exception is thrown, this function has no effect. + +.SH Notes + + resize_and_overwrite invalidates all iterators, pointers, and references into *this, + regardless whether reallocation occurs. Implementations may assume that the contents + of the string are not aliased after the call to resize_and_overwrite. + + Feature-test macro Value Std Feature +__cpp_lib_string_resize_and_overwrite 202110L (C++23) std::basic_string::resize_and_overwrite + +.SH Example + + Link to test the example: compiler explorer. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + static_assert(__cpp_lib_string_resize_and_overwrite); + + constexpr std::string_view fruits[]{"apple", "banana", "coconut", "date", "elderberry"}; + + int main() + { + // A simple case, append only fruits[0]. The string size will be increased. + std::string s{"Food: "}; + s.resize_and_overwrite(16, [sz = s.size()](char* buf, std::size_t buf_size) noexcept + { + const auto to_copy = std::min(buf_size - sz, fruits[0].size()); + std::memcpy(buf + sz, fruits[0].data(), to_copy); + return sz + to_copy; + }); + std::cout << "1. " << std::quoted(s) << '\\n'; + + // The size shrinking case. Note, that the user's lambda is always invoked. + s.resize_and_overwrite(10, [](char* buf, int n) noexcept + { + return std::find(buf, buf + n, ':') - buf; + }); + std::cout << "2. " << std::quoted(s) << '\\n'; + + std::cout << "3. Copy data until the buffer is full. Print data and sizes.\\n"; + std::string food{"Food:"}; + const auto resize_to{27}; + std::cout << "Initially, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", resize_to: " << resize_to + << ", food: " << std::quoted(food) << '\\n'; + + food.resize_and_overwrite( + resize_to, + [food_size = food.size()](char* p, std::size_t n) noexcept -> std::size_t + { + // p[0]..p[n] is the assignable range + // p[0]..p[min(n, food_size) - 1] is the readable range + // (contents initially equal to the original string) + + // Debug print: + std::cout << "In Operation(); n: " << n << '\\n'; + + // Copy fruits to the buffer p while there is enough space. + char* first = p + food_size; + + for (char* const end = p + n; const std::string_view fruit : fruits) + { + char* last = first + fruit.size() + 1; + if (last > end) + break; + *first++ = ' '; + std::ranges::copy(fruit, first); + first = last; + } + + const auto final_size{static_cast(first - p)}; + + // Debug print: + std::cout << "In Operation(); final_size: " << final_size << '\\n'; + + assert(final_size <= n); + return final_size; // Return value is the actual new length + // of the string, must be in range 0..n + }); + + std::cout << "Finally, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", food: " << std::quoted(food) << '\\n'; + } + +.SH Possible output: + + 1. "Food: apple" + 2. "Food" + 3. Copy data until the buffer is full. Print data and sizes. + Initially, food.size: 5, food.capacity: 15, resize_to: 27, food: "Food:" + In Operation(); n: 27 + In Operation(); final_size: 26 + Finally, food.size: 26, food.capacity: 30, food: "Food: apple banana coconut" + +.SH See also + + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::basic_string::rfind.3 b/man/std::basic_string::rfind.3 index 5b7a300b7..6baebe7ca 100644 --- a/man/std::basic_string::rfind.3 +++ b/man/std::basic_string::rfind.3 @@ -1,105 +1,161 @@ -.TH std::basic_string::rfind 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rfind \- std::basic_string::rfind + .SH Synopsis - size_type rfind( const basic_string& str, size_type pos = npos ) const; \fB(1)\fP - size_type rfind( const CharT* s, size_type pos, size_type count ) const; \fB(2)\fP - size_type rfind( const CharT* s, size_type pos = npos ) const; \fB(3)\fP - size_type rfind( CharT ch, size_type pos = npos ) const; \fB(4)\fP - - Finds the last substring equal to the given character sequence. Search begins at - pos, i.e. the found substring must not begin in a position following pos. If npos or - any value not smaller than size() is passed as pos, whole string will be searched. - - 1) Finds the last substring equal to str. If str.size() is zero, returns pos or - size()-1, whichever is smaller. - 2) Finds the last substring equal to the first count characters of the character - string pointed to by s. s can include null characters. If count is zero, returns pos - or size()-1, whichever is smaller. + size_type rfind( const basic_string& str, size_type pos \fB(1)\fP (noexcept since C++11) + = npos ) const; (constexpr since C++20) + size_type rfind( const CharT* s, size_type pos, \fB(2)\fP (constexpr since C++20) + size_type count ) const; + size_type rfind( const CharT* s, size_type pos = npos ) \fB(3)\fP (constexpr since C++20) + const; + size_type rfind( CharT ch, size_type pos = npos ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type rfind( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last substring equal to str. + 2) Finds the last substring equal to the range [s, s + count). This range can + include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. 3) Finds the last substring equal to the character string pointed to by s. The - length of the string is determined by the first null character. If the length of s - is zero, returns pos or size()-1, whichever is smaller. - 4) Finds the last character ch. - - If size() is zero, npos is always returned. + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last substring equal to the contents of sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. .SH Parameters str - string to search for pos - position at which to begin searching count - length of substring to search for - s - pointer to a character string to seach for + s - pointer to a character string to search for ch - character to search for + t - object (convertible to std::basic_string_view) to search for .SH Return value Position of the first character of the found substring or npos if no such substring - is found. + is found. Note that this is an offset from the start of the string, not the end. + + If searching for an empty string (i.e., str.size(), count, or Traits::length(s) is + zero), the empty string is found immediately and rfind returns: + + * pos, if pos < size(); + * size() otherwise, including the case where pos == npos. + + Otherwise, if size() is zero, npos is always returned. .SH Exceptions - 1-4) \fI(none)\fP \fI(until C++11)\fP - 1,4) - noexcept specification: \fI(since C++11)\fP - noexcept \fI(until C++14)\fP - - 2,3) \fI(none)\fP - 1) - noexcept specification: - noexcept \fI(since C++14)\fP - - 2,3,4) \fI(none)\fP + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Example - + // Run this code - #include + #include #include - - void print(std::string::size_type n, std::string const &s) + #include + + void print(std::string::size_type n, + std::string::size_type len, + std::string const &s) { - if (n == std::string::npos) { + if (n == std::string::npos) std::cout << "not found\\n"; - } else { - std::cout << "found: " << s.substr(n) << '\\n'; - } + else + std::cout << "found: " << std::quoted(s.substr(n, len)) << " at " << n << '\\n'; } - + int main() { std::string::size_type n; std::string const s = "This is a string"; - + // search backwards from end of string n = s.rfind("is"); - print(n, s); + print(n, 2, s); + // search backwards from position 4 n = s.rfind("is", 4); - print(n, s); + print(n, 2, s); + // find a single character n = s.rfind('s'); - print(n, s); + print(n, 1, s); + // find a single character n = s.rfind('q'); - print(n, s); + print(n, 1, s); + + // find the prefix (see also s.starts_with("This")) + n = s.rfind("This", 0); + print(n, 4, s); } .SH Output: - found: is a string - found: is is a string - found: string + found: "is" at 5 + found: "is" at 2 + found: "s" at 10 not found + found: "This" at 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 .SH See also - find find characters in the string - \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP find_first_of find first occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_first_not_of find first absence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_of find last occurrence of characters - \fI(public member function)\fP + \fI(public member function)\fP find_last_not_of find last absence of characters - \fI(public member function)\fP + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::shrink_to_fit.3 b/man/std::basic_string::shrink_to_fit.3 index 9cbc5e214..506b08ea9 100644 --- a/man/std::basic_string::shrink_to_fit.3 +++ b/man/std::basic_string::shrink_to_fit.3 @@ -1,12 +1,18 @@ -.TH std::basic_string::shrink_to_fit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::shrink_to_fit \- std::basic_string::shrink_to_fit + .SH Synopsis - void shrink_to_fit(); \fI(since C++11)\fP + void shrink_to_fit(); (constexpr since C++20) Requests the removal of unused capacity. - It is a non-binding request to reduce capacity to size. It depends on the + It is a non-binding request to reduce capacity() to size(). It depends on the implementation if the request is fulfilled. + If (and only if) reallocation takes place, all pointers, references, and iterators + are invalidated. + .SH Parameters \fI(none)\fP @@ -17,39 +23,73 @@ .SH Complexity - Constant + (unspecified) \fI(until C++17)\fP + Linear in the size of the string. \fI(since C++17)\fP + +.SH Notes + + In libstdc++, shrink_to_fit() is not available in C++98 mode. .SH Example - + // Run this code #include #include - + int main() { std::string s; - std::cout << "Default-constructed capacity is " << s.capacity() << '\\n'; - s.resize(100); - std::cout << "Capacity of a 100-element string is " << s.capacity() << '\\n'; + std::cout << "Size of std::string is " << sizeof s << " bytes\\n" + << "Default-constructed capacity is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + for (int i = 0; i < 42; i++) + s.append(" 42 "); + std::cout << "Capacity after 42 appends is " << s.capacity() + << " and size is " << s.size() << '\\n'; + s.clear(); - std::cout << "Capacity after clear() is " << s.capacity() << '\\n'; + std::cout << "Capacity after clear() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + s.shrink_to_fit(); - std::cout << "Capacity after shrink_to_fit() is " << s.capacity() << '\\n'; + std::cout << "Capacity after shrink_to_fit() is " << s.capacity() + << " and size is " << s.size() << '\\n'; } -.SH Output: +.SH Possible output: + + GCC output: + Size of std::string is 32 bytes + Default-constructed capacity is 15 and size 0 + Capacity after 42 appends is 240 and size 168 + Capacity after clear() is 240 and size 0 + Capacity after shrink_to_fit() is 15 and size 0 + + clang output (with -stdlib=libc++): + Size of std::string is 24 bytes + Default-constructed capacity is 22 and size is 0 + Capacity after 42 appends is 191 and size is 168 + Capacity after clear() is 191 and size is 0 + Capacity after shrink_to_fit() is 22 and size is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Default-constructed capacity is 0 - Capacity of a 100-element string is 100 - Capacity after clear() is 100 - Capacity after shrink_to_fit() is 0 + DR Applied to Behavior as published Correct behavior + LWG 755 C++98 std::string lacked explicit shrink-to-fit provided + operations .SH See also size returns the number of characters - length \fI(public member function)\fP + length \fI(public member function)\fP returns the number of characters that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::basic_string::size,.3 b/man/std::basic_string::size,.3 new file mode 100644 index 000000000..46f96cd93 --- /dev/null +++ b/man/std::basic_string::size,.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::size, \- std::basic_string::size, + +.SH Synopsis + + size_type size() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + size_type length() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + + Returns the number of CharT elements in the string, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the string. + +.SH Complexity + + Unspecified \fI(until C++11)\fP + Constant \fI(since C++11)\fP + +.SH Notes + + For std::string, the elements are bytes (objects of type char), which are not the + same as characters if a multibyte encoding such as UTF-8 is used. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("Exemplar"); + assert(8 == s.size()); + assert(s.size() == s.length()); + assert(s.size() == static_cast( + std::distance(s.begin(), s.end()))); + + std::u32string a(U"ハロー・ワールド"); // 8 code points + assert(8 == a.size()); // 8 code units in UTF-32 + + std::u16string b(u"ハロー・ワールド"); // 8 code points + assert(8 == b.size()); // 8 code units in UTF-16 + + std::string c("ハロー・ワールド"); // 8 code points + assert(24 == c.size()); // 24 code units in UTF-8 + + #if __cplusplus >= 202002 + std::u8string d(u8"ハロー・ワールド"); // 8 code points + assert(24 == d.size()); // 24 code units in UTF-8 + #endif + } + +.SH See also + + empty checks whether the string is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::size,std::basic_string::length.3 b/man/std::basic_string::size,std::basic_string::length.3 deleted file mode 100644 index 68b2eccdb..000000000 --- a/man/std::basic_string::size,std::basic_string::length.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::basic_string::size,std::basic_string::length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type size() const; - size_type length() const; - - Returns the number of CharT elements in the string, i.e. std::distance(begin(), - end()). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The number of CharT elements in the string. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant - -.SH Notes - - For std::string, the elements are bytes (objects of type char), which are not the - same as characters if a multibyte encoding such as UTF-8 is used. - -.SH See also - - empty checks whether the string is empty - \fI(public member function)\fP - max_size returns the maximum number of characters - \fI(public member function)\fP diff --git a/man/std::basic_string::starts_with.3 b/man/std::basic_string::starts_with.3 new file mode 100644 index 000000000..54b219105 --- /dev/null +++ b/man/std::basic_string::starts_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::starts_with \- std::basic_string::starts_with + +.SH Synopsis + constexpr bool + starts_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + starts_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + starts_with( const CharT* s ) const; + + Checks if the string begins with the given prefix. The prefix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).starts_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.starts_with("He"sv) // (1) + && !str.starts_with("he"sv) // (1) + && str.starts_with("He"s) // (1) implicit conversion string to string_view + && !str.starts_with("he"s) // (1) implicit conversion string to string_view + && str.starts_with('H') // (2) + && !str.starts_with('h') // (2) + && str.starts_with("He") // (3) + && !str.starts_with("he") // (3) + ); + } + +.SH See also + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::basic_string::substr.3 b/man/std::basic_string::substr.3 index 2c405b8de..f263d4824 100644 --- a/man/std::basic_string::substr.3 +++ b/man/std::basic_string::substr.3 @@ -1,10 +1,22 @@ -.TH std::basic_string::substr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::substr \- std::basic_string::substr + .SH Synopsis - basic_string substr( size_type pos = 0, - size_type count = npos ) const; + basic_string substr( size_type pos = 0, size_type (until C++23) + count = npos ) const; (constexpr since C++20) + constexpr basic_string + substr( size_type pos = 0, size_type count = \fB(1)\fP (since C++23) + npos ) const&; + constexpr basic_string substr( size_type pos = 0, \fB(2)\fP (since C++23) + size_type count = npos ) &&; + + Returns a substring [pos, pos + count). If the requested substring extends past the + end of the string, i.e. the count is greater than size() - pos (e.g. if count == + npos), the returned substring is [pos, size()). - Returns a substring [pos, pos+count). If the requested substring extends past the - end of the string, or if count == npos, the returned substring is [pos, size()). + 1) Equivalent to return basic_string(*this, pos, count);. + 2) Equivalent to return basic_string(std::move(*this), pos, count);. .SH Parameters @@ -13,53 +25,89 @@ .SH Return value - String containing the substring [pos, pos+count). + String containing the substring [pos, pos + count) or [pos, size()). .SH Exceptions - std::out_of_range if pos > size() + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). .SH Complexity - Linear in count + Linear in count. + +.SH Notes + + The allocator of the returned string is default-constructed: the new allocator might + not be a copy of get_allocator(). .SH Example - + // Run this code - #include #include - + #include + int main() { std::string a = "0123456789abcdefghij"; - + + // count is npos, returns [pos, size()) std::string sub1 = a.substr(10); std::cout << sub1 << '\\n'; - + + // both pos and pos + count are within bounds, returns [pos, pos + count) std::string sub2 = a.substr(5, 3); std::cout << sub2 << '\\n'; - - std::string sub3 = a.substr(12, 100); - std::cout << sub3 << '\\n'; - - std::string sub4 = a.substr(a.size()-3, 50); + + // pos is within bounds, pos + count is not, returns [pos, size()) + std::string sub4 = a.substr(a.size() - 3, 50); + // this is effectively equivalent to + // std::string sub4 = a.substr(17, 3); + // since a.size() == 20, pos == a.size() - 3 == 17, and a.size() - pos == 3 + std::cout << sub4 << '\\n'; + + try + { + // pos is out of bounds, throws + std::string sub5 = a.substr(a.size() + 3, 50); + std::cout << sub5 << '\\n'; + } + catch (const std::out_of_range& ex) + { + std::cout << ex.what() << '\\n'; + } } -.SH Output: +.SH Possible output: abcdefghij 567 - cdefghij hij + basic_string::substr: __pos (which is 23) > this->size() (which is 20) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee .SH See also - copy copies characters - \fI(public member function)\fP - size returns the number of characters - length \fI(public member function)\fP - find find characters in the string - \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + substr returns a substring + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::basic_string::swap.3 b/man/std::basic_string::swap.3 index 7a1081b2c..07e64dbec 100644 --- a/man/std::basic_string::swap.3 +++ b/man/std::basic_string::swap.3 @@ -1,9 +1,17 @@ -.TH std::basic_string::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_string::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::swap \- std::basic_string::swap + .SH Synopsis - void swap( basic_string& other ); + void swap( basic_string& other ); \fI(until C++17)\fP + void swap( basic_string& other ) noexcept(/* see below */); \fI(since C++17)\fP + (constexpr since C++20) Exchanges the contents of the string with those of other. All iterators and - references remain valid. + references may be invalidated. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. .SH Parameters @@ -13,39 +21,76 @@ \fI(none)\fP +.SH Complexity + + Constant. + +.SH Exceptions + + No exception is thrown. \fI(until C++11)\fP + Exceptions can only be thrown in the case where the behavior is + undefined (see above). + \fI(since C++11)\fP + If an exception is thrown for any reason, this function has no effect + (strong exception safety guarantee). + + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_swap::value (since + || C++17) + std::allocator_traits::is_always_equal::value) + .SH Example - + // Run this code - #include #include - + #include + int main() { std::string a = "AAA"; - std::string b = "BBB"; - - std::cout << "before swap" << '\\n'; - std::cout << "a: " << a << '\\n'; - std::cout << "b: " << b << '\\n'; - + std::string b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + a.swap(b); - - std::cout << "after swap" << '\\n'; - std::cout << "a: " << a << '\\n'; - std::cout << "b: " << b << '\\n'; + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; } .SH Output: - before swap - a: AAA - b: BBB - after swap - a: BBB - b: AAA + Before swap: + a = AAA + b = BBBB -.SH Complexity + After swap: + a = BBBB + b = AAA - Constant. + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 403 C++98 swap() might throw an exception no exception is thrown + LWG 535 C++98 swapping strings did not preserve the orders are also preserved + character orders + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swap swaps the contents + \fI(public member function of std::basic_string_view)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_string::~basic_string.3 b/man/std::basic_string::~basic_string.3 new file mode 100644 index 000000000..631cdb44e --- /dev/null +++ b/man/std::basic_string::~basic_string.3 @@ -0,0 +1,13 @@ +.TH std::basic_string::~basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::~basic_string \- std::basic_string::~basic_string + +.SH Synopsis + ~basic_string(); (constexpr since C++20) + + Destructs the basic_string. The destructors of the elements are called and the used + storage is deallocated. + +.SH Complexity + + Typically constant (formally linear). diff --git a/man/std::basic_string_view.3 b/man/std::basic_string_view.3 new file mode 100644 index 000000000..df2b6eb62 --- /dev/null +++ b/man/std::basic_string_view.3 @@ -0,0 +1,277 @@ +.TH std::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view \- std::basic_string_view + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++17)\fP + class Traits = std::char_traits + + > class basic_string_view; + + The class template basic_string_view describes an object that can refer to a + constant contiguous sequence of CharT with the first element of the sequence at + position zero. + + For a basic_string_view str, pointers, iterators, and references to elements of str + are invalidated when an operation invalidates a pointer in the range + [str.data(), str.data() + str.size()). + + Every specialization of std::basic_string_view is a TriviallyCopyable (since C++23) + type. + + A typical implementation holds only two members: a pointer to constant CharT and a + size. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string_view \fI(C++17)\fP std::basic_string_view + std::wstring_view \fI(C++17)\fP std::basic_string_view + std::u8string_view (C++20) std::basic_string_view + std::u16string_view \fI(C++17)\fP std::basic_string_view + std::u32string_view \fI(C++17)\fP std::basic_string_view + +.SH Template parameters + + CharT - character type + CharTraits class specifying the operations on the character type. Like for + Traits - std::basic_string, Traits::char_type must name the same type as CharT or + the program is ill-formed. + + Nested types + + Nested type Definition + traits_type Traits + value_type CharT + pointer CharT* + const_pointer const CharT* + reference CharT& + const_reference const CharT& + implementation-defined constant LegacyRandomAccessIterator, + + const_iterator and LegacyContiguousIterator \fI(until C++20)\fP + ConstexprIterator, and contiguous_iterator \fI(since C++20)\fP + + whose value_type is CharT + iterator const_iterator + const_reverse_iterator std::reverse_iterator + reverse_iterator const_reverse_iterator + size_type std::size_t + difference_type std::ptrdiff_t + + Note: iterator and const_iterator are the same type because string views are views + into constant character sequences. + + All requirements on the iterator types of a Container applies to the iterator and + const_iterator types of basic_string_view as well. + +.SH Member functions + + Constructors and assignment + constructor constructs a basic_string_view + \fI(public member function)\fP + operator= assigns a view + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Element access + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function)\fP +.SH Capacity + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP +.SH Modifiers + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Operations + copy copies characters + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string view contains the given substring or + (C++23) character + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) +.SH Input/output + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_view_literals + operator""sv creates a string view of a character array literal + \fI(C++17)\fP \fI(function)\fP + +.SH Helper classes + + std::hash + std::hash + std::hash + std::hash + std::hash hash support for string views + \fI(C++17)\fP \fI(class template specialization)\fP + \fI(C++17)\fP + (C++20) + \fI(C++17)\fP + \fI(C++17)\fP + + Helper templates + + template< class CharT, class Traits > + + inline constexpr bool (since + C++20) + ranges::enable_borrowed_range> = + true; + + This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy + borrowed_range. + + template< class CharT, class Traits > + + inline constexpr bool \fI(since C++20)\fP + + ranges::enable_view> = + true; + + This specialization of ranges::enable_view makes basic_string_view satisfy view. + + Deduction guides \fI(since C++20)\fP + +.SH Notes + + It is the programmer's responsibility to ensure that std::string_view does not + outlive the pointed-to character array: + + std::string_view good{"a string literal"}; + // "Good" case: `good` points to a static array. + // String literals reside in persistent data storage. + + std::string_view bad{"a temporary string"s}; + // "Bad" case: `bad` holds a dangling pointer since the std::string temporary, + // created by std::operator""s, will be destroyed at the end of the statement. + + Specializations of std::basic_string_view are already trivially copyable types in + all existing implementations, even before the formal requirement introduced in + C++23. + + Feature-test macro Value Std Feature + __cpp_lib_string_view 201606L \fI(C++17)\fP std::string_view + 201803L (C++20) ConstexprIterator + __cpp_lib_string_contains 202011L (C++23) contains + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view unicode[]{"▀▄─", "▄▀─", "▀─▄", "▄─▀"}; + + for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4)) + { + for (int x{}; x != 16; ++x) + std::cout << unicode[p]; + std::cout << '\\n'; + } + } + +.SH Output: + + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ + ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀ + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + only pointers, iterators, and all pointers, iterators, and + references references + LWG 3203 C++17 returned from the member functions to elements of + of basic_string_view + basic_string_view might be may be invalidated + invalidated + +.SH See also + + basic_string stores and manipulates sequences of characters + \fI(class template)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + initializer_list creates a temporary array in list-initialization and then + \fI(C++11)\fP references it + \fI(class template)\fP diff --git a/man/std::basic_string_view::at.3 b/man/std::basic_string_view::at.3 new file mode 100644 index 000000000..65f8fa91d --- /dev/null +++ b/man/std::basic_string_view::at.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::at \- std::basic_string_view::at + +.SH Synopsis + constexpr const_reference at( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. Bounds + checking is performed, exception of type std::out_of_range will be thrown on invalid + access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string_view str_view("abcdef"); + + try + { + for (std::size_t i = 0; true; ++i) + std::cout << i << ": " << str_view.at(i) << '\\n'; + } + catch (const std::out_of_range& e) + { + std::cout << "Whooops. Index is out of range.\\n"; + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + 0: a + 1: b + 2: c + 3: d + 4: e + 5: f + 6: Whooops. Index is out of range. + basic_string_view::at: __pos (which is 6) >= this->size() (which is 6) + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + accesses the specified character with bounds checking + at \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::back.3 b/man/std::basic_string_view::back.3 new file mode 100644 index 000000000..7fd79d7b3 --- /dev/null +++ b/man/std::basic_string_view::back.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::back \- std::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; \fI(since C++17)\fP + + Returns reference to the last character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_suffix(1)) + std::cout << str.back() << ' ' << str << '\\n'; + } + +.SH Output: + + F ABCDEF + E ABCDE + D ABCD + C ABC + B AB + A A + +.SH See also + + front accesses the first character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::basic_string_view::basic_string_view.3 b/man/std::basic_string_view::basic_string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::basic_string_view::basic_string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::begin,std::basic_string_view::cbegin.3 b/man/std::basic_string_view::begin,std::basic_string_view::cbegin.3 new file mode 100644 index 000000000..83667f3e5 --- /dev/null +++ b/man/std::basic_string_view::begin,std::basic_string_view::cbegin.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::begin,std::basic_string_view::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::begin,std::basic_string_view::cbegin \- std::basic_string_view::begin,std::basic_string_view::cbegin + +.SH Synopsis + constexpr const_iterator begin() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cbegin() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + + constexpr auto begin = str_view.begin(); + constexpr auto cbegin = str_view.cbegin(); + static_assert( + *begin == 'a' and + *cbegin == 'a' and + *begin == *cbegin and + begin == cbegin and + std::same_as); + } + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::basic_string_view::compare.3 b/man/std::basic_string_view::compare.3 new file mode 100644 index 000000000..8087ec4ef --- /dev/null +++ b/man/std::basic_string_view::compare.3 @@ -0,0 +1,95 @@ +.TH std::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::compare \- std::basic_string_view::compare + +.SH Synopsis + constexpr int compare( basic_string_view v ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(2)\fP \fI(since C++17)\fP + basic_string_view v ) const; + constexpr int compare( size_type pos1, size_type count1, + basic_string_view v, \fB(3)\fP \fI(since C++17)\fP + size_type pos2, size_type count2 ) const; + constexpr int compare( const CharT* s ) const; \fB(4)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(5)\fP \fI(since C++17)\fP + const CharT* s ) const; + constexpr int compare( size_type pos1, size_type count1, \fB(6)\fP \fI(since C++17)\fP + const CharT* s, size_type count2 ) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less < 0 + than v + size() < this is less < 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater > 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater > 0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + Negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH Example + + +// Run this code + + #include + + int main() + { + using std::operator""sv; + static_assert("abc"sv.compare("abcd"sv) < 0); + static_assert("abcd"sv.compare("abc"sv) > 0); + static_assert("abc"sv.compare("abc"sv) == 0); + static_assert(""sv.compare(""sv) == 0); + } + +.SH See also + + compares two strings + compare \fI\fI(public member\fP function of\fP + std::basic_string) + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) diff --git a/man/std::basic_string_view::contains.3 b/man/std::basic_string_view::contains.3 new file mode 100644 index 000000000..8c655ade3 --- /dev/null +++ b/man/std::basic_string_view::contains.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::contains \- std::basic_string_view::contains + +.SH Synopsis + constexpr bool contains( basic_string_view sv ) const noexcept; \fB(1)\fP (since C++23) + constexpr bool contains( CharT c ) const noexcept; \fB(2)\fP (since C++23) + constexpr bool contains( const CharT* s ) const; \fB(3)\fP (since C++23) + + Checks if the string view contains the given substring, where + + 1) the substring is a string view. + 2) the substring is a single character. + 3) the substring is a null-terminated character string. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view + c - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + static_assert + ( + // bool contains(basic_string_view x) const noexcept; + "https://cppreference.com"sv.contains("cpp"sv) == true and + "https://cppreference.com"sv.contains("php"sv) == false and + + // bool contains(CharT x) const noexcept; + "C++23"sv.contains('+') == true and + "C++23"sv.contains('-') == false and + + // bool contains(const CharT* x) const; + std::string_view("basic_string_view").contains("string") == true and + std::string_view("basic_string_view").contains("String") == false + ); + + int main() {} + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::copy.3 b/man/std::basic_string_view::copy.3 new file mode 100644 index 000000000..50e77b7be --- /dev/null +++ b/man/std::basic_string_view::copy.3 @@ -0,0 +1,88 @@ +.TH std::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::copy \- std::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos \fI(since C++17)\fP + = 0 ) const; (constexpr since C++20) + + Copies the substring [pos, pos + rcount) to the character array pointed to by dest, + where rcount is the smaller of count and size() - pos. + + Equivalent to Traits::copy(dest, data() + pos, rcount). + +.SH Parameters + + dest - pointer to the destination character string + count - requested substring length + pos - position of the first character + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::basic_string_view source{"ABCDEF"}; + std::array dest; + std::size_t count{}, pos{}; + + dest.fill('\\0'); + source.copy(dest.data(), count = 4); // pos = 0 + std::cout << dest.data() << '\\n'; // ABCD + + dest.fill('\\0'); + source.copy(dest.data(), count = 4, pos = 1); + std::cout << dest.data() << '\\n'; // BCDE + + dest.fill('\\0'); + source.copy(dest.data(), count = 42, pos = 2); // ok, count -> 4 + std::cout << dest.data() << '\\n'; // CDEF + + try + { + source.copy(dest.data(), count = 1, pos = 666); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Output: + + ABCD + BCDE + CDEF + basic_string_view::copy: __pos (which is 666) > __size (which is 6) + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::basic_string_view::data.3 b/man/std::basic_string_view::data.3 new file mode 100644 index 000000000..29290d3ff --- /dev/null +++ b/man/std::basic_string_view::data.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::data \- std::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; \fI(since C++17)\fP + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::data() and string literals, std::basic_string_view::data() + returns a pointer to a buffer that is not necessarily null-terminated, for example a + substring view (e.g. from remove_suffix). Therefore, it is typically a mistake to + pass data() to a routine that takes just a const CharT* and expects a + null-terminated string. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::wstring_view wcstr_v = L"xyzzy"; + std::cout << std::wcslen(wcstr_v.data()) << '\\n'; + // OK: the underlying character array is null-terminated + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, sizeof array); + // std::cout << std::strlen(array_v.data()) << '\\n'; + // error: the underlying character array is not null-terminated + + std::string str(array_v.data(), array_v.size()); // OK + std::cout << std::strlen(str.data()) << '\\n'; + // OK: the underlying character array of a std::string is always null-terminated + } + +.SH Output: + + 5 + 3 + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function of std::basic_string)\fP diff --git a/man/std::basic_string_view::empty.3 b/man/std::basic_string_view::empty.3 new file mode 100644 index 000000000..185b498eb --- /dev/null +++ b/man/std::basic_string_view::empty.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::empty \- std::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + checks whether the string is empty + empty \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::end,std::basic_string_view::cend.3 b/man/std::basic_string_view::end,std::basic_string_view::cend.3 new file mode 100644 index 000000000..465ae8a3e --- /dev/null +++ b/man/std::basic_string_view::end,std::basic_string_view::cend.3 @@ -0,0 +1,54 @@ +.TH std::basic_string_view::end,std::basic_string_view::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::end,std::basic_string_view::cend \- std::basic_string_view::end,std::basic_string_view::cend + +.SH Synopsis + constexpr const_iterator end() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cend() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + constexpr auto end = str_view.end(); + constexpr auto cend = str_view.cend(); + + static_assert + ( + *std::prev(end) == 'd' && 'd' == *std::prev(cend) and end == cend + ); + } + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::basic_string_view::ends_with.3 b/man/std::basic_string_view::ends_with.3 new file mode 100644 index 000000000..ad6eecb60 --- /dev/null +++ b/man/std::basic_string_view::ends_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::ends_with \- std::basic_string_view::ends_with + +.SH Synopsis + constexpr bool ends_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool ends_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool ends_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view ends with the given suffix, where + + 1) the suffix is a string view. Effectively returns size() >= sv.size() && + compare(size() - sv.size(), npos, sv) == 0. + 2) the suffix is a single character. Effectively returns !empty() && + Traits::eq(back(), ch). + 3) the suffix is a null-terminated character string. Effectively returns + ends_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) ends_with( basic_string_view sv ) + && std::string_view("https://cppreference.com").ends_with(".com"sv) == true + && std::string_view("https://cppreference.com").ends_with(".org"sv) == false + + // (2) ends_with( CharT c ) + && std::string_view("C++20").ends_with('0') == true + && std::string_view("C++20").ends_with('3') == false + + // (3) ends_with( const CharT* s ) + && std::string_view("string_view").ends_with("view") == true + && std::string_view("string_view").ends_with("View") == false + ); + } + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::basic_string_view::find.3 b/man/std::basic_string_view::find.3 new file mode 100644 index 000000000..8882c44bb --- /dev/null +++ b/man/std::basic_string_view::find.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find \- std::basic_string_view::find + +.SH Synopsis + constexpr size_type find( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type find( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type find( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type find( const CharT* s, size_type pos = 0 ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + + constexpr auto str{" long long int;"sv}; + + static_assert( + 1 == str.find("long"sv) && "<- find(v , pos = 0)" && + 6 == str.find("long"sv, 2) && "<- find(v , pos = 2)" && + 0 == str.find(' ') && "<- find(ch, pos = 0)" && + 2 == str.find('o', 1) && "<- find(ch, pos = 1)" && + 2 == str.find("on") && "<- find(s , pos = 0)" && + 6 == str.find("long double", 5, 4) && "<- find(s , pos = 5, count = 4)" + ); + + static_assert(str.npos == str.find("float")); + } + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + finds the first occurrence of the given substring + find \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_string_view::find_first_not_of.3 b/man/std::basic_string_view::find_first_not_of.3 new file mode 100644 index 000000000..6ad069029 --- /dev/null +++ b/man/std::basic_string_view::find_first_not_of.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_not_of \- std::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type + find_first_not_of( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_first_not_of( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_first_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_not_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or std::string_view::npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + int main() + { + static_assert(2 == "BCDEF"sv.find_first_not_of("ABC")); + // ^ + static_assert(4 == "BCDEF"sv.find_first_not_of("ABC", 4)); + // ^ + static_assert(1 == "BCDEF"sv.find_first_not_of('B')); + // ^ + static_assert(3 == "BCDEF"sv.find_first_not_of('D', 2)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_string_view::find_first_of.3 b/man/std::basic_string_view::find_first_of.3 new file mode 100644 index 000000000..c6b35518c --- /dev/null +++ b/man/std::basic_string_view::find_first_of.3 @@ -0,0 +1,100 @@ +.TH std::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_of \- std::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type + find_first_of( basic_string_view v, size_type pos = 0 ) const \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_first_of( CharT ch, size_type pos = 0 ) const noexcept; + constexpr size_type + find_first_of( const CharT* s, size_type pos, size_type count \fB(3)\fP \fI(since C++17)\fP + ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurrence of any of the characters of v in this view, starting + at position pos. + 2) Equivalent to find_first_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + constexpr bool is_white_space(const char c) + { + return " \\t\\n\\f\\r\\v"sv.find_first_of(c) != N; + }; + + static_assert( + 1 == "alignas"sv.find_first_of("klmn"sv) && + // └─────────────────────────┘ + N == "alignof"sv.find_first_of("wxyz"sv) && + // + 3 == "concept"sv.find_first_of("bcde"sv, /* pos= */ 1) && + // └───────────────────────┘ + N == "consteval"sv.find_first_of("oxyz"sv, /* pos= */ 2) && + // + 6 == "constexpr"sv.find_first_of('x') && + // └─────────────────────┘ + N == "constinit"sv.find_first_of('x') && + // + 6 == "const_cast"sv.find_first_of('c', /* pos= */ 4) && + // └──────────────────────┘ + N == "continue"sv.find_first_of('c', /* pos= */ 42) && + // + 5 == "co_await"sv.find_first_of("cba", /* pos= */ 4) && + // └───────────────────────┘ + 7 == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 2) && + // └────────────────────┘ + N == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 1) && + // + is_white_space(' ') && is_white_space('\\r') && !is_white_space('\\a') + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_string_view::find_last_not_of.3 b/man/std::basic_string_view::find_last_not_of.3 new file mode 100644 index 000000000..1f593444d --- /dev/null +++ b/man/std::basic_string_view::find_last_not_of.3 @@ -0,0 +1,79 @@ +.TH std::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_not_of \- std::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type + find_last_not_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_last_not_of( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last character not equal to any of the characters in the given character + sequence. The search considers only the interval [0, pos]. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using std::operator""sv; + + int main() + { + static_assert(1 == "BCDEF"sv.find_last_not_of("DEF")); + // ^ + static_assert(2 == "BCDEFG"sv.find_last_not_of("EFG", 3)); + // ^ + static_assert(2 == "ABBA"sv.find_last_not_of('A')); + // ^ + static_assert(1 == "ABBA"sv.find_last_not_of('A', 1)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_string_view::find_last_of.3 b/man/std::basic_string_view::find_last_of.3 new file mode 100644 index 000000000..0203b94f0 --- /dev/null +++ b/man/std::basic_string_view::find_last_of.3 @@ -0,0 +1,92 @@ +.TH std::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_of \- std::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type + find_last_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_last_of( CharT ch, size_type pos = npos ) const noexcept; + constexpr size_type + find_last_of( const CharT* s, size_type pos, size_type count ) \fB(3)\fP \fI(since C++17)\fP + const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_last_of( const CharT* s, size_type pos = npos ) const; + + Finds the last character equal to one of characters in the given character sequence. + Exact search algorithm is not specified. The search considers only the interval + [0, pos]. If the character is not present in the interval, npos will be returned. + + 1) Finds the last occurence of any of the characters of v in this view, ending at + position pos. + 2) Equivalent to find_last_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which the search is to finish + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert( + 5 == "delete"sv.find_last_of("cdef"sv) && + // └────────────────────┘ + N == "double"sv.find_last_of("fghi"sv) && + // + 0 == "else"sv.find_last_of("bcde"sv, 2 /* pos [0..2]: "els" */) && + // └────────────────────────┘ + N == "explicit"sv.find_last_of("abcd"sv, 4 /* pos [0..4]: "expli" */) && + // + 3 == "extern"sv.find_last_of('e') && + // └────────────────────┘ + N == "false"sv.find_last_of('x') && + // + 0 == "inline"sv.find_last_of('i', 2 /* pos [0..2]: "inl" */) && + // └───────────────────────┘ + N == "mutable"sv.find_last_of('a', 2 /* pos [0..2]: "mut" */) && + // + 3 == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 3 /* "cde" */) && + // └─────────────────────────┘ + N == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 2 /* "cd" */) + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_string_view::front.3 b/man/std::basic_string_view::front.3 new file mode 100644 index 000000000..475c3cb67 --- /dev/null +++ b/man/std::basic_string_view::front.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::front \- std::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; \fI(since C++17)\fP + + Returns reference to the first character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_prefix(1)) + std::cout << str.front() << ' ' << str << '\\n'; + } + +.SH Output: + + A ABCDEF + B BCDEF + C CDEF + D DEF + E EF + F F + +.SH See also + + back accesses the last character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::basic_string_view::max_size.3 b/man/std::basic_string_view::max_size.3 new file mode 100644 index 000000000..c3f42d911 --- /dev/null +++ b/man/std::basic_string_view::max_size.3 @@ -0,0 +1,66 @@ +.TH std::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::max_size \- std::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; \fI(since C++17)\fP + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::numeric_limits::max() + << " <- numeric_limits::max()\\n" + << std::string_view{}.max_size() + << " <- string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::wstring_view{}.max_size() + << " <- wstring_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n"; + } + +.SH Possible output: + + 9223372036854775807 <- numeric_limits::max() + 4611686018427387899 <- string_view::max_size() + 4611686018427387899 <- basic_string_view::max_size() + 2305843009213693949 <- basic_string_view::max_size() + 1152921504606846974 <- wstring_view::max_size() + 1152921504606846974 <- basic_string_view::max_size() + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + returns the maximum number of characters + max_size \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::npos.3 b/man/std::basic_string_view::npos.3 new file mode 100644 index 000000000..c3ba3b575 --- /dev/null +++ b/man/std::basic_string_view::npos.3 @@ -0,0 +1,39 @@ +.TH std::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::npos \- std::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); \fI(since C++17)\fP + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Example + + +// Run this code + + #include + + constexpr bool + contains(std::string_view const what, std::string_view const where) noexcept + { + return std::string_view::npos != where.find(what); + } + + int main() + { + using namespace std::literals; + + static_assert(contains("water", "in a bottle of water")); + static_assert(!contains("wine", "in a bottle of champagne")); + static_assert(""sv.npos == "haystack"sv.find("needle")); + } + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI\fI(public static member\fP constant of\fP + std::basic_string) diff --git a/man/std::basic_string_view::operator=.3 b/man/std::basic_string_view::operator=.3 new file mode 100644 index 000000000..dba80aad4 --- /dev/null +++ b/man/std::basic_string_view::operator=.3 @@ -0,0 +1,48 @@ +.TH std::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator= \- std::basic_string_view::operator= + +.SH Synopsis + constexpr basic_string_view& operator=( const basic_string_view& view \fI(since C++17)\fP + ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + assigns values to the string + operator= \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::operator[].3 b/man/std::basic_string_view::operator[].3 new file mode 100644 index 000000000..c1d7e55fb --- /dev/null +++ b/man/std::basic_string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator[] \- std::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[]( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Does not throw. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], std::basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string str = "Exemplar"; + std::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + accesses the specified character + operator[] \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::rbegin,.3 b/man/std::basic_string_view::rbegin,.3 new file mode 100644 index 000000000..8f17b98bf --- /dev/null +++ b/man/std::basic_string_view::rbegin,.3 @@ -0,0 +1,60 @@ +.TH std::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rbegin, \- std::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crbegin() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), std::next(str_view.rbegin(), 3), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), std::next(str_view.crbegin(), 3), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fed + fed + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::basic_string_view::remove_prefix.3 b/man/std::basic_string_view::remove_prefix.3 new file mode 100644 index 000000000..31ef25b47 --- /dev/null +++ b/man/std::basic_string_view::remove_prefix.3 @@ -0,0 +1,74 @@ +.TH std::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_prefix \- std::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix( size_type n ); \fI(since C++17)\fP + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::literals; + + [[nodiscard("a pure function")]] + constexpr std::size_t count_substrings(std::string_view hive, std::string_view const bee) + { + if (hive.empty() || bee.empty()) + return 0U; + + std::size_t buzz{}; + while (bee.size() <= hive.size()) + { + const auto pos = hive.find(bee); + if (pos == hive.npos) + break; + ++buzz; + hive.remove_prefix(pos + bee.size()); + } + return buzz; + } + + int main() + { + std::string str = " trim me"; + std::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + + constexpr auto hive{"bee buzz bee buzz bee"}; + std::cout << "There are " << count_substrings(hive, "bee") << " bees in this hive.\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + There are 3 bees in this hive. + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP diff --git a/man/std::basic_string_view::remove_suffix.3 b/man/std::basic_string_view::remove_suffix.3 new file mode 100644 index 000000000..01bee81f3 --- /dev/null +++ b/man/std::basic_string_view::remove_suffix.3 @@ -0,0 +1,51 @@ +.TH std::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_suffix \- std::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); \fI(since C++17)\fP + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP diff --git a/man/std::basic_string_view::rend,std::basic_string_view::crend.3 b/man/std::basic_string_view::rend,std::basic_string_view::crend.3 new file mode 100644 index 000000000..5f201fac0 --- /dev/null +++ b/man/std::basic_string_view::rend,std::basic_string_view::crend.3 @@ -0,0 +1,61 @@ +.TH std::basic_string_view::rend,std::basic_string_view::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rend,std::basic_string_view::crend \- std::basic_string_view::rend,std::basic_string_view::crend + +.SH Synopsis + constexpr const_reverse_iterator rend() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crend() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), str_view.rend(), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), str_view.crend(), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fedcba + fedcba + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::basic_string_view::rfind.3 b/man/std::basic_string_view::rfind.3 new file mode 100644 index 000000000..684090010 --- /dev/null +++ b/man/std::basic_string_view::rfind.3 @@ -0,0 +1,81 @@ +.TH std::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rfind \- std::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind( basic_string_view v, size_type pos = \fB(1)\fP \fI(since C++17)\fP + npos ) const noexcept; + constexpr size_type rfind( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type rfind( const CharT* s, size_type pos, \fB(3)\fP \fI(since C++17)\fP + size_type count ) const; + constexpr size_type rfind( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last occurrence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert(true + && (6 == "AB AB AB"sv.rfind("AB")) + && (6 == "AB AB AB"sv.rfind("ABCD", N, 2)) + && (3 == "AB AB AB"sv.rfind("AB", 5)) + && (0 == "AB CD EF"sv.rfind("AB", 0)) + && (2 == "B AB AB "sv.rfind("AB", 2)) + && (N == "B AB AB "sv.rfind("AB", 1)) + && (5 == "B AB AB "sv.rfind('A')) + && (4 == "AB AB AB"sv.rfind('B', 4)) + && (N == "AB AB AB"sv.rfind('C')) + ); + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_string_view::size,std::basic_string_view::length.3 b/man/std::basic_string_view::size,std::basic_string_view::length.3 new file mode 100644 index 000000000..8f96ca90c --- /dev/null +++ b/man/std::basic_string_view::size,std::basic_string_view::length.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::size,std::basic_string_view::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::size,std::basic_string_view::length \- std::basic_string_view::size,std::basic_string_view::length + +.SH Synopsis + constexpr size_type size() const noexcept; \fI(since C++17)\fP + constexpr size_type length() const noexcept; \fI(since C++17)\fP + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_string_view::starts_with.3 b/man/std::basic_string_view::starts_with.3 new file mode 100644 index 000000000..9c8fd78c7 --- /dev/null +++ b/man/std::basic_string_view::starts_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::starts_with \- std::basic_string_view::starts_with + +.SH Synopsis + constexpr bool starts_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool starts_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool starts_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view begins with the given prefix, where + + 1) the prefix is a string view. Effectively returns basic_string_view(data(), + std::min(size(), sv.size())) == sv. + 2) the prefix is a single character. Effectively returns !empty() && + Traits::eq(front(), ch). + 3) the prefix is a null-terminated character string. Effectively returns + starts_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) starts_with( basic_string_view ) + && "https://cppreference.com"sv.starts_with("http"sv) == true + && "https://cppreference.com"sv.starts_with("ftp"sv) == false + + // (2) starts_with( CharT ) + && "C++20"sv.starts_with('C') == true + && "C++20"sv.starts_with('J') == false + + // (3) starts_with( const CharT* ) + && std::string_view("string_view").starts_with("string") == true + && std::string_view("string_view").starts_with("String") == false + ); + } + +.SH See also + + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::basic_string_view::substr.3 b/man/std::basic_string_view::substr.3 new file mode 100644 index 000000000..d7edf51b7 --- /dev/null +++ b/man/std::basic_string_view::substr.3 @@ -0,0 +1,76 @@ +.TH std::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::substr \- std::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view substr( size_type pos = 0, \fI(since C++17)\fP + size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rlen), where rlen is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rlen). + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + typedef std::size_t count_t, pos_t; + + constexpr std::string_view data{"ABCDEF"}; + + std::cout << data.substr() << '\\n'; // ABCDEF, i.e. data[0, 5] that is [0, 6) + std::cout << data.substr(pos_t(1)) << '\\n'; // BCDEF, i.e. [1, 6) + std::cout << data.substr(pos_t(2), count_t(3)) << '\\n'; // CDE, i.e. [2, 2 + 3) + std::cout << data.substr(pos_t(4), count_t(42)) << '\\n'; // EF, i.e. [4, 6) + + try + { + [[maybe_unused]] + auto sub = data.substr(pos_t(666), count_t(1)); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + ABCDEF + BCDEF + CDE + EF + basic_string_view::substr: __pos (which is 666) > __size (which is 6) + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function of std::basic_string)\fP diff --git a/man/std::basic_string_view::swap.3 b/man/std::basic_string_view::swap.3 new file mode 100644 index 000000000..c6b397cfe --- /dev/null +++ b/man/std::basic_string_view::swap.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::swap \- std::basic_string_view::swap + +.SH Synopsis + constexpr void swap( basic_string_view& v ) noexcept; \fI(since C++17)\fP + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view a = "AAA"; + std::string_view b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swaps the contents + swap \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_stringbuf.3 b/man/std::basic_stringbuf.3 index 969d923d8..2d38ec8f0 100644 --- a/man/std::basic_stringbuf.3 +++ b/man/std::basic_stringbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_stringbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf \- std::basic_stringbuf + .SH Synopsis Defined in header template< @@ -6,82 +9,99 @@ class CharT, class Traits = std::char_traits, class Allocator = std::allocator + > class basic_stringbuf - > class basic_stringbuf : public std::basic_streambuf + : public std::basic_streambuf std::basic_stringbuf is a std::basic_streambuf whose associated character sequence is a memory-resident sequence of arbitrary characters, which can be initialized from or made available as an instance of std::basic_string. Typical implementations of std::basic_stringbuf hold an object of type - std::basic_string or equivalent resizeable sequence container directly as a data + std::basic_string or equivalent resizable sequence container directly as a data member and use it as both the controlled character sequence (the array where the six pointers of std::basic_streambuf are pointing to) and as the associated character sequence (the source of characters for all input operations and the target for the output). In addition, a typical implementation holds a data member of type - std::ios_base::openmode to indicate the status of the stream (input-only, - output-only, input/output, at-end, etc). + std::ios_base::openmode to indicate the I/O mode of the associated stream + (input-only, output-only, input/output, at-end, etc). - if over-allocation strategy is used by overflow(), an additional + If over-allocation strategy is used by overflow(), an additional high-watermark pointer may be stored to track the last initialized \fI(since C++11)\fP - character + character. - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - stringbuf basic_stringbuf - wstringbuf basic_stringbuf + Type Definition + std::stringbuf std::basic_stringbuf + std::wstringbuf std::basic_stringbuf .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type - allocator_type Allocator \fI(since C++11)\fP + allocator_type Allocator -.SH Member functions + Exposition-only members + + the std::basic_string used as the underlying + buf buffer + (exposition-only member object*) + mode the std::ios_base::openmode of the associated stream + (exposition-only member object*) + init_buf_ptrs initializes the input and output sequences + (exposition-only member function*) .SH Public member functions + constructor constructs a basic_stringbuf object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns a basic_stringbuf object - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_stringbuf objects - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP destructor destructs a basic_stringbuf object and the string it \fB[virtual]\fP (implicitly declared) holds - \fI(virtual public member function)\fP + \fI(virtual public member function)\fP replaces or obtains a copy of the associated str character string - \fI(public member function)\fP + \fI(public member function)\fP + get_allocator obtains a copy of the allocator associated with the + (C++20) internal sequence container + \fI(public member function)\fP + view obtains a view over the underlying character + (C++20) sequence + \fI(public member function)\fP + .SH Protected member functions - underflow returns the next character available in the input - \fB[virtual]\fP sequence - \fI(virtual protected member function)\fP - pbackfail puts a character back into the input sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP - overflow appends a character to the output sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP - setbuf attempts to replace the controlled character - \fB[virtual]\fP sequence with an array - \fI(virtual protected member function)\fP - seekoff repositions the next pointer in the input sequence, - \fB[virtual]\fP output sequence, or both, using relative addressing - \fI(virtual protected member function)\fP - seekpos repositions the next pointer in the input sequence, - \fB[virtual]\fP output sequence, or both using absolute addressing - \fI(virtual protected member function)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + pbackfail puts a character back into the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow appends a character to the output sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function)\fP .SH Non-member functions std::swap(std::basic_stringbuf) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_streambuf @@ -89,111 +109,140 @@ Inherited from std::basic_streambuf Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type .SH Member functions - destructor destructs the basic_streambuf object - \fB[virtual]\fP \fI(virtual public member function of std::basic_streambuf)\fP + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) .SH Locales - pubimbue invokes imbue() - \fI(public member function of std::basic_streambuf)\fP - getloc obtains a copy of the associated locale - \fI(public member function of std::basic_streambuf)\fP + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + .SH Positioning - pubsetbuf invokes setbuf() - \fI(public member function of std::basic_streambuf)\fP - pubseekoff invokes seekoff() - \fI(public member function of std::basic_streambuf)\fP - pubseekpos invokes seekpos() - \fI(public member function of std::basic_streambuf)\fP - pubsync invokes sync() - \fI(public member function of std::basic_streambuf)\fP + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + .SH Get area - in_avail obtains the number of characters immediately available in the get area - \fI(public member function of std::basic_streambuf)\fP - advances the input sequence, then reads one character without advancing - snextc again - \fI(public member function of std::basic_streambuf)\fP - sbumpc reads one character from the input sequence and advances the sequence - \fI(public member function of std::basic_streambuf)\fP - stossc advances the input sequence as if by calling sbumpc() and discarding - \fB(deprecated)\fP the result - \fI(public member function)\fP - reads one character from the input sequence without advancing the - sgetc sequence - \fI(public member function of std::basic_streambuf)\fP - sgetn invokes xsgetn() - \fI(public member function of std::basic_streambuf)\fP + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + .SH Put area - sputc writes one character to the put area and advances the next pointer - \fI(public member function of std::basic_streambuf)\fP - sputn invokes xsputn() - \fI(public member function of std::basic_streambuf)\fP + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + .SH Putback - sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP - sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + .SH Protected member functions constructor constructs a basic_streambuf object - \fI(protected member function)\fP + \fI(protected member function)\fP operator= replaces a basic_streambuf object - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP swap swaps two basic_streambuf objects - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP .SH Locales imbue changes the associated locale - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) .SH Positioning setbuf replaces the buffer with user-defined array, if permitted - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both, using relative addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekpos repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both using absolute addressing - \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) sync synchronizes the buffers with the associated character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) .SH Get area - showmanyc obtains the number of characters available for input in the associated - \fB[virtual]\fP input sequence, if known - \fI(virtual protected member function of std::basic_streambuf)\fP + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP - uflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP and advances the next pointer - \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) xsgetn reads multiple characters from the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) eback returns a pointer to the beginning, current character and the end of gptr the get area - egptr \fI(protected member function)\fP + egptr \fI(protected member function)\fP gbump advances the next pointer in the input sequence - \fI(protected member function)\fP + \fI(protected member function)\fP repositions the beginning, next, and end pointers of the input setg sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Put area xsputn writes multiple characters to the output sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) pbase returns a pointer to the beginning, current character and the end of pptr the put area - epptr \fI(protected member function)\fP + epptr \fI(protected member function)\fP pbump advances the next pointer of the output sequence - \fI(protected member function)\fP + \fI(protected member function)\fP repositions the beginning, next, and end pointers of the output setp sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Putback - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function of std::basic_streambuf)\fP + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) diff --git a/man/std::basic_stringbuf::basic_stringbuf.3 b/man/std::basic_stringbuf::basic_stringbuf.3 index 0baa6bd92..496a0651e 100644 --- a/man/std::basic_stringbuf::basic_stringbuf.3 +++ b/man/std::basic_stringbuf::basic_stringbuf.3 @@ -1,47 +1,167 @@ -.TH std::basic_stringbuf::basic_stringbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::basic_stringbuf \- std::basic_stringbuf::basic_stringbuf + .SH Synopsis - explicit basic_stringbuf(std::ios_base::openmode which = - std::ios_base::in \fB(1)\fP - | - std::ios_base::out); - explicit basic_stringbuf (const std::basic_string& new_str, - - std::ios_base::openmode which = \fB(2)\fP - std::ios_base::in - - | - std::ios_base::out); - basic_stringbuf(const basic_stringbuf& rhs) = delete; \fB(3)\fP \fI(since C++11)\fP - basic_stringbuf(basic_stringbuf&& rhs); \fB(4)\fP \fI(since C++11)\fP - - 1) Constructs a std::basic_stringbuf object: initializes the base class by calling - the default constructor of std::basic_streambuf, initializes the character sequence - with an empty string, and sets the mode to which. - 2) Constructs a std::basic_stringbuf object by performing the same initialization as - 1), followed by initializing the associated character sequence as if by calling - str(new_str). - 3) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible - 4) Move-constructs a std::basic_stringbuf object by moving all state from another - std::basic_stringbuf object rhs, including the associated string, the open mode, the - locale, and all other state. After the move, the six pointers of - std::basic_streambuf in *this are guaranteed to be different from the corresponding - pointers in the moved-from rhs unless null. + explicit basic_stringbuf( std::ios_base::openmode which = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringbuf( std::ios_base::openmode which ); \fI(since C++11)\fP + basic_stringbuf() + : basic_stringbuf( std::ios_base::in | std::ios_base::out \fB(2)\fP \fI(since C++11)\fP + ) {} + explicit + + basic_stringbuf( const std::basic_string& s, \fB(3)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); + explicit basic_stringbuf( std::basic_string&& s, + + std::ios_base::openmode which = \fB(4)\fP \fI(since C++20)\fP + + std::ios_base::in | + std::ios_base::out ); + basic_stringbuf( std::ios_base::openmode which, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + explicit basic_stringbuf( const Allocator& a ) + : basic_stringbuf( std::ios_base::in | \fB(6)\fP \fI(since C++20)\fP + std::ios_base::out, a ) {} + template< class SAlloc > + + explicit basic_stringbuf( const std::basic_string& s, \fB(7)\fP \fI(since C++20)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); \fB(1)\fP + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(8)\fP \fI(since C++20)\fP + + std::ios_base::openmode which, const + Allocator& a ); + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(9)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringbuf( s, std::ios_base::in | + std::ios_base::out, a ) {} + template< class StringViewLike > + + explicit basic_stringbuf( const StringViewLike& t, + std::ios_base::openmode which = \fB(10)\fP (since C++26) + + std::ios_base::in | + std::ios_base::out ); + template< class StringViewLike > + + basic_stringbuf( const StringViewLike& t, \fB(11)\fP (since C++26) + + std::ios_base::openmode which, const + Allocator& a ); + template< class StringViewLike > + basic_stringbuf( const StringViewLike& t, const Allocator& a \fB(12)\fP (since C++26) + ); + basic_stringbuf( basic_stringbuf&& rhs ); \fB(13)\fP \fI(since C++11)\fP + basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a ); \fB(14)\fP \fI(since C++20)\fP + basic_stringbuf( const basic_stringbuf& rhs ) = delete; \fB(15)\fP \fI(since C++11)\fP + + The std::basic_streambuf base and the exposition-only data members buf and mode are + initialized as follows. + + After initializing these subobjects, overloads (3-12) initialize the input and + output sequences as if by calling init_buf_ptrs(). + + Overload std::basic_streambuf buf mode + base + \fB(1)\fP which + implementation-defined std::ios_base::in | + \fB(2)\fP (see below) + std::ios_base::out + \fB(3)\fP s + \fB(4)\fP std::move(s) which + \fB(5)\fP + a std::ios_base::in | + \fB(6)\fP + default-initialized std::ios_base::out + \fB(7)\fP s which + \fB(8)\fP + {s, a} std::ios_base::in | + \fB(9)\fP + std::ios_base::out + \fB(10)\fP {sv, Allocator()} which + \fB(11)\fP + {sv, a} std::ios_base::in | + \fB(12)\fP + std::ios_base::out + \fB(13)\fP rhs std::move(rhs).str() + \fB(14)\fP (copy constructed) {std::move(rhs).str(), rhs.mode + a} + + 1,2) Overload + \fB(1)\fP + \fI(until C++11)\fP + \fB(2)\fP + \fI(since C++11)\fP is the default constructor. It is implementation-defined whether the + sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are + initialized to null pointers. + 5,6) When the construction is complete, str.empty() is true. + 7) This overload participates in overload resolution only if std::is_same_v is false. + 10-12) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then it is used as above in the + table. + These overloads participate in overload resolution only if + std::is_convertible_v> is true. + 13,14) Overload \fB(13)\fP is the move constructor. It is implementation-defined whether + the six sequence pointers in *this obtain the values which rhs had. + When the construction is complete, rhs is empty but usable, and + * Let rhs_p refer to the state of rhs just prior to this construction, the + following expressions will evaluate to true: + + * str() == rhs_p.str() + * getloc() == rhs_p.getloc() + * gptr() - eback() == rhs_p.gptr() - rhs_p.eback() + * egptr() - eback() == rhs_p.egptr() - rhs_p.eback() + * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase() + * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase() + * Let rhs_a refer to the state of rhs just after this construction, the following + expressions will evaluate to true: + + * !eback() || eback() != rhs_a.eback() + * !gptr() || gptr() != rhs_a.gptr() + * !egptr() || egptr() != rhs_a.egptr() + * !pbase() || pbase() != rhs_a.pbase() + * !pptr() || pptr() != rhs_a.pptr() + * !epptr() || epptr() != rhs_a.epptr() + 15) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible. .SH Parameters - new_str - a basic_string used to initialize the buffer - rhs - another basic_stringbuf - specifies stream open mode. It is bitmask type, the following constants - are defined: - - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + s - a std::basic_string used to initialize the buffer + t - an object (convertible to std::basic_string_view) used to initialize the + buffer + a - another allocator used to construct the internal std::basic_string + rhs - another basic_stringbuf + specifies stream open mode. It is bitmask type, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + which - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Notes @@ -53,30 +173,34 @@ std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different effects on different implementations. + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + .SH Example - Demonstrates calling the constructor of basic_stringbuf directly. + Demonstrates calling the constructor of std::basic_stringbuf directly: + - // Run this code #include #include - + int main() { - // default constructor (mode = in|out) + // default constructor (mode = in | out) std::stringbuf buf1; buf1.sputc('1'); std::cout << &buf1 << '\\n'; - + // string constructor in at-end mode \fI(C++11)\fP std::stringbuf buf2("test", std::ios_base::in | std::ios_base::out | std::ios_base::ate); buf2.sputc('1'); std::cout << &buf2 << '\\n'; - + // append mode test (results differ among compilers) std::stringbuf buf3("test", std::ios_base::in | std::ios_base::out @@ -93,7 +217,24 @@ test1 est12 (Sun Studio) 2st1 (GCC) + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP allocated no array object 1. removed the + LWG 432 C++98 2. overload \fB(3)\fP did not specify how the limitation + input 2. specified + and output sequences are initialized + overload \fB(3)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(which & beyond that position + std::ios_base::out) == true + P0935R0 C++11 the default constructor was explicit made implicit + .SH See also - constructor constructs the string stream - \fI(public member function of std::basic_stringstream)\fP + constructs the string stream + constructor \fI\fI(public member\fP function of\fP + std::basic_stringstream) diff --git a/man/std::basic_stringbuf::get_allocator.3 b/man/std::basic_stringbuf::get_allocator.3 new file mode 100644 index 000000000..7857c70ac --- /dev/null +++ b/man/std::basic_stringbuf::get_allocator.3 @@ -0,0 +1,22 @@ +.TH std::basic_stringbuf::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::get_allocator \- std::basic_stringbuf::get_allocator + +.SH Synopsis + allocator_type get_allocator() const noexcept; \fI(since C++20)\fP + + Returns the allocator associated with the internal sequence container. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + the associated allocator + +.SH See also + + returns the associated allocator + get_allocator \fI(public member function of std::basic_string)\fP + diff --git a/man/std::basic_stringbuf::init_buf_ptrs.3 b/man/std::basic_stringbuf::init_buf_ptrs.3 new file mode 100644 index 000000000..40e0a6044 --- /dev/null +++ b/man/std::basic_stringbuf::init_buf_ptrs.3 @@ -0,0 +1,39 @@ +.TH std::basic_stringbuf::init_buf_ptrs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::init_buf_ptrs \- std::basic_stringbuf::init_buf_ptrs + +.SH Synopsis + void init_buf_ptrs(); (exposition only*) + + Initializes the input and output sequences from buf according to mode. buf and mode + are exposition-only data members of *this. + + Immediately after this function returns: + + * If std::ios_base::out is set in mode, pbase() points to buf.front() and epptr() + >= pbase() + buf.size() is true; + * in addition, if std::ios_base::ate is set in mode, pptr() == pbase() + + buf.size() is true, + * otherwise pptr() == pbase() is true. + * If std::ios_base::in is set in mode, eback() points to buf.front(), and gptr() + == eback() && egptr() == eback() + buf.size() is true. + +.SH Notes + + For efficiency reasons, stream buffer operations can violate invariants of buf while + it is held encapsulated in the std::basic_stringbuf, e.g., by writing to characters + in the range [buf.data() + buf.size(), buf.data() + buf.capacity()). + + All operations retrieving a std::basic_string from buf ensure that the + std::basic_string invariants hold on the returned value. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + calling init_buf_ptrs() made makes + LWG 1448 C++98 pptr() == pbase() + buf.data() pptr() == pbase() + + for streams that are both input and output buf.size() + streams for append streams diff --git a/man/std::basic_stringbuf::operator=.3 b/man/std::basic_stringbuf::operator=.3 index 5984e1cf3..2dedd1bb3 100644 --- a/man/std::basic_stringbuf::operator=.3 +++ b/man/std::basic_stringbuf::operator=.3 @@ -1,13 +1,17 @@ -.TH std::basic_stringbuf::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::operator= \- std::basic_stringbuf::operator= + .SH Synopsis std::basic_stringbuf& operator=( std::basic_stringbuf&& rhs ); \fB(1)\fP \fI(since C++11)\fP std::basic_stringbuf& operator=( const std::basic_stringbuf& rhs ) \fB(2)\fP = delete; 1) Move assignment operator: Moves the contents of rhs into *this. After the move, - lhs has the associated string, the open mode, the locale, and all other state - formerly held by rhs. The six pointers of std::basic_streambuf in lhs are guaranteed - to be different from the corresponding pointers in the moved-from rhs unless null. + *this has the associated string, the open mode, the locale, and all other state + formerly held by rhs. The six pointers of std::basic_streambuf in *this are + guaranteed to be different from the corresponding pointers in the moved-from rhs + unless null. 2) The copy assignment operator is deleted; basic_stringbuf is not CopyAssignable. .SH Parameters @@ -20,34 +24,33 @@ .SH Example - + // Run this code + #include #include #include - #include - + int main() { - std::istringstream one("one"); std::ostringstream two("two"); - + std::cout << "Before move, one = \\"" << one.str() << '"' << " two = \\"" << two.str() << "\\"\\n"; - + *one.rdbuf() = std::move(*two.rdbuf()); - - std::cout << "Before move, one = \\"" << one.str() << '"' + + std::cout << "After move, one = \\"" << one.str() << '"' << " two = \\"" << two.str() << "\\"\\n"; } .SH Output: Before move, one = "one" two = "two" - Before move, one = "two" two = "" + After move, one = "two" two = "" .SH See also constructor constructs a basic_stringbuf object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::basic_stringbuf::overflow.3 b/man/std::basic_stringbuf::overflow.3 index 08b0ee6dd..0f3394815 100644 --- a/man/std::basic_stringbuf::overflow.3 +++ b/man/std::basic_stringbuf::overflow.3 @@ -1,27 +1,30 @@ -.TH std::basic_stringbuf::overflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::overflow \- std::basic_stringbuf::overflow + .SH Synopsis protected: - virtual int_type overflow ( int_type c = Traits::eof() ); + virtual int_type overflow( int_type c = Traits::eof() ); Appends the character c to the output character sequence. - If c is the end-of-file indicator traits::eq_int_type(c,traits::eof()) == true, then - there is no character to append. The function does nothing and returns an + If c is the end-of-file indicator (traits::eq_int_type(c, traits::eof()) == true), + then there is no character to append. The function does nothing and returns an unspecified value other than traits::eof(). Otherwise, if the output sequence has a write position available or this function can successfully make a write position available, then calls sputc(c) and returns c. - This function can make a write position available if the stringbuf is open for - output (mode & ios_base::out) != 0): in this case, it reallocates (or initially + This function can make a write position available if the std::stringbuf is open for + output ((mode & ios_base::out) != 0): in this case, it reallocates (or initially allocates) the buffer big enough to hold the entire current buffer plus at least one - more character. If the stringbuf is also open for input ((mode & ios_base::in) != 0, - then overflow also increases the size of the get area by moving egptr() to point - just past the new write position. + more character. If the std::stringbuf is also open for input ((mode & ios_base::in) + != 0), then overflow also increases the size of the get area by moving egptr() to + point just past the new write position. .SH Parameters - \fI(none)\fP + c - the character to store in the put area .SH Return value @@ -36,33 +39,38 @@ .SH Example - In the implementation used to execute this example, overflow() over-allocates the - put area to 512 bytes: a call to str() would only return the four initialized bytes, - but the next 508 calls to sputc() would not require new calls to overflow() + In the implementation used to execute this example (e.g. GCC-4.9), overflow() + over-allocates the put area to 512 bytes: a call to str() would only return the four + initialized bytes, but the next 508 calls to sputc() would not require new calls to + overflow(). + - // Run this code #include #include - + struct mybuf : std::stringbuf { mybuf(const std::string& new_str, - std::ios_base::openmode which = std::ios_base::in|std::ios_base::out) - : std::stringbuf(new_str, which) {} + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out) + : std::stringbuf(new_str, which) {} + int_type overflow(int_type c = EOF) override { std::cout << "stringbuf::overflow('" << char(c) << "') called\\n" << "Before: size of get area: " << egptr() - eback() << '\\n' << " size of put area: " << epptr() - pbase() << '\\n'; + int_type ret = std::stringbuf::overflow(c); + std::cout << "After : size of get area: " << egptr() - eback() << '\\n' << " size of put area: " << epptr() - pbase() << '\\n'; + return ret; } }; - + int main() { std::cout << "read-write stream:\\n"; @@ -70,12 +78,12 @@ std::iostream stream(&sbuf); stream << 1234; std::cout << sbuf.str() << '\\n'; - + std::cout << "\\nread-only stream:\\n"; mybuf ro_buf(" ", std::ios_base::in); // read-only stream std::iostream ro_stream(&ro_buf); ro_stream << 1234; - + std::cout << "\\nwrite-only stream:\\n"; mybuf wr_buf(" ", std::ios_base::out); // write-only stream std::iostream wr_stream(&wr_buf); @@ -91,14 +99,14 @@ After : size of get area: 4 size of put area: 512 1234 - + read-only stream: stringbuf::overflow('1') called Before: size of get area: 3 size of put area: 0 After : size of get area: 3 size of put area: 0 - + write-only stream: stringbuf::overflow('4') called Before: size of get area: 0 @@ -106,9 +114,23 @@ After : size of get area: 0 size of put area: 512 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 169 C++98 the buffer (re)allocated could only hold one allows more extra + extra character characters + overflow moved epptr() to point just past the + LWG 432 C++98 new it is not moved + write position if the std::stringbuf is open + for input + .SH See also overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + underflow returns the next character available in the input sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::basic_stringbuf::pbackfail.3 b/man/std::basic_stringbuf::pbackfail.3 index 57cccbe71..c8b1ffd10 100644 --- a/man/std::basic_stringbuf::pbackfail.3 +++ b/man/std::basic_stringbuf::pbackfail.3 @@ -1,4 +1,7 @@ -.TH std::basic_stringbuf::pbackfail 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::pbackfail \- std::basic_stringbuf::pbackfail + .SH Synopsis protected: virtual int_type pbackfail( int_type c = Traits::eof() ) @@ -44,18 +47,18 @@ .SH See also - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function of std::basic_streambuf)\fP + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP .SH Category: - * Todo no example diff --git a/man/std::basic_stringbuf::seekoff.3 b/man/std::basic_stringbuf::seekoff.3 index 6087c4adf..a8a742258 100644 --- a/man/std::basic_stringbuf::seekoff.3 +++ b/man/std::basic_stringbuf::seekoff.3 @@ -1,45 +1,50 @@ -.TH std::basic_stringbuf::seekoff 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::seekoff \- std::basic_stringbuf::seekoff + .SH Synopsis protected: - virtual pos_type seekoff(off_type off, - ios_base::seekdir way, + virtual pos_type seekoff( off_type off, + std::ios_base::seekdir dir, - ios_base::openmode which = ios_base::in | ios_base::out); + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if possible, to the position that corresponds to exactly off characters from beginning, end, or current position of the get and/or put area of the buffer. - * If which includes ios_base::in and this buffer is open for reading (that is, if - ((which & ios_base::in) == ios_base::in), then repositions the read pointer - std::basic_streambuf::gptr inside the get area as described below - * If which includes ios_base::out and this buffer is open for writing (that is, - (which & ios_base::out) == ios_base::out), then repositions the write pointer - std::basic_streambuf::pptr inside the put area as described below - * If which includes both ios_base::in and ios_base::out and the buffer is open for - both reading and writing ((which & (ios_base::in|ios_base::out)) - ==(ios_base::in|ios_base::out)), and when is either ios_base::beg or - ios_base::end, then repositions both read and write pointers as described below. + * If which includes std::ios_base::in and this buffer is open for reading (that + is, if (which & std::ios_base::in) == std::ios_base::in), then repositions the + read pointer std::basic_streambuf::gptr inside the get area as described below + * If which includes std::ios_base::out and this buffer is open for writing (that + is, (which & std::ios_base::out) == std::ios_base::out), then repositions the + write pointer std::basic_streambuf::pptr inside the put area as described below + * If which includes both std::ios_base::in and std::ios_base::out and the buffer + is open for both reading and writing (that is, (which & (std::ios_base::in | + std::ios_base::out)) == (std::ios_base::in | std::ios_base::out)), and dir is + either std::ios_base::beg or std::ios_base::end, then repositions both read and + write pointers as described below. * Otherwise, this function fails. - If the pointer (either gptr or pptr or both) is repositioned, it is done as follows: + If gptr and/or pptr is repositioned, it is done as follows: - 1) If the pointer to be repositioned is a null pointer and the new offset newoff - would be non-zero, this function fails. - 2) The new pointer offset newoff of type off_type is determined - a) if way == ios_base::beg, then newoff is zero - b) if way == ios_base::cur, then newoff is the current position of the pointer - (gptr()-eback() or pptr()-pbase()) - c) if way == ios_base::end, then newoff is the length of the entire initialized part - of the buffer (if overallocation is used, the high watermark pointer minus the + 1) The new pointer offset newoff of type off_type is determined + a) if dir == std::ios_base::beg, then newoff is zero + b) if dir == std::ios_base::cur, then newoff is the current position of the pointer + (gptr() - eback() or pptr() - pbase()) + c) if dir == std::ios_base::end, then newoff is the length of the entire initialized + part of the buffer (if over-allocation is used, the high watermark pointer minus the beginning pointer) + 2) If the pointer to be repositioned is a null pointer and newoff would be non-zero, + this function fails. 3) If newoff + off < 0 (the repositioning would move the pointer to before the beginning of the buffer) or if newoff + off would point past the end of the buffer - (or past the last initialized character in the buffer if overallocation is used), - the function fails + (or past the last initialized character in the buffer if over-allocation is used), + the function fails. 4) Otherwise, the pointer is assigned as if by gptr() = eback() + newoff + off or - pptr() = pbase() + newoff + off + pptr() = pbase() + newoff + off. .SH Parameters @@ -60,42 +65,43 @@ .SH Return value - pos_type(newoff) on success, pos_type(off_type(-1)) on failure and if pos_type - cannot represent the resulting stream position. + pos_type(newoff) on success, pos_type(off_type(-1)) on failure or if pos_type cannot + represent the resulting stream position. .SH Example - + // Run this code #include #include - + int main() { std::stringstream ss("123"); // in/out std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + // absolute positioning both pointers ss.rdbuf()->pubseekoff(1, std::ios_base::beg); // move both 1 forward std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + // try to move both pointers 1 forward from current position - if(-1 == ss.rdbuf()->pubseekoff(1, std::ios_base::cur)) + if (-1 == ss.rdbuf()->pubseekoff(1, std::ios_base::cur)) std::cout << "moving both pointers from current position failed\\n"; std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + // move the write pointer 1 forward, but not the read pointer // can also be called as ss.seekp(1, std::ios_base::cur); ss.rdbuf()->pubseekoff(1, std::ios_base::cur, std::ios_base::out); std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + ss << 'a'; // write at put position std::cout << "Wrote 'a' at put position, the buffer is now " << ss.str() << '\\n'; + char ch; ss >> ch; std::cout << "reading at get position gives '" << ch << "'\\n"; @@ -111,13 +117,41 @@ Wrote 'a' at put position, the buffer is now 12a reading at get position gives '2' + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + static constant members of + LWG 375 C++98 std::ios_base were corrected + misspecified as members of + std::basic_ios + seekoff might succeed even if newoff + LWG 432 C++98 + off seekoff fails + would point past the last initialized in this case + character + repositioning null gptr() and/or null + LWG 453 C++98 pptr() it can succeed in this case + with a new offset of zero always + failed + the end pointer could not be used to + LWG 563 C++98 calculate newoff because it could use the high watermark + not be precisely controlled by the pointer instead + program after resolving LWG issue 432 + .SH See also - seekpos repositions the next pointer in the input sequence, output sequence, or - \fB[virtual]\fP both using absolute addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, or - \fB[virtual]\fP both, using relative addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the file position, using relative addressing - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::basic_stringbuf::seekpos.3 b/man/std::basic_stringbuf::seekpos.3 index 5db554063..2a5102900 100644 --- a/man/std::basic_stringbuf::seekpos.3 +++ b/man/std::basic_stringbuf::seekpos.3 @@ -1,16 +1,19 @@ -.TH std::basic_stringbuf::seekpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::seekpos \- std::basic_stringbuf::seekpos + .SH Synopsis protected: - virtual pos_type seekpos(pos_type sp, + virtual pos_type seekpos( pos_type sp, - std::ios_base::openmode which = std::ios_base::in | + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out ); Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if - possible, to the position indicated by sp + possible, to the position indicated by sp. - Effectively executes seekoff(off_type(sp), std::ios_base::beg, which) + Effectively executes seekoff(off_type(sp), std::ios_base::beg, which). .SH Parameters @@ -30,32 +33,37 @@ seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the single-argument versions of std::basic_istream::seekg() and - std::basic_ostream::seekp() + std::basic_ostream::seekp(). .SH Example - + // Run this code #include #include - + struct mybuf : std::stringbuf { mybuf(const std::string& str) : std::stringbuf(str) {} - pos_type seekpos(pos_type sp, std::ios_base::openmode which) { - std::cout << "Before seekpos(" << sp << "), size of the get area is " - << egptr()-eback() << " with " - << egptr()-gptr() << " read positions available\\n"; - pos_type rc = std::stringbuf::seekpos(sp, which); - std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " - << "size of the get area is " - << egptr()-eback() << " with " - << egptr()-gptr() << " read positions available\\n"; + + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::stringbuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + return rc; } }; - + int main() { mybuf buf("12345"); @@ -65,19 +73,33 @@ .SH Output: - Before seekpos\fB(2)\fP, size of the get area is 5 with 5 read positions available + Before seekpos\fB(2)\fP, size of the get area is 5 with 5 read positions available. seekpos() returns 2. - After the call, size of the get area is 5 with 3 read positions available + After the call, size of the get area is 5 with 3 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + static constant members of std::ios_base + LWG 375 C++98 were corrected + misspecified as members of + std::basic_ios + LWG 564 C++98 if was unclear how to reposition gptr they are repositioned by + and/or pptr seekoff() .SH See also pubseekpos invokes seekpos() - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP seekoff repositions the next pointer in the input sequence, output sequence, or \fB[virtual]\fP both, using relative addressing - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP seekpos repositions the file position, using absolute addressing - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or \fB[virtual]\fP both using absolute addressing - \fI(virtual protected member function of std::strstreambuf)\fP + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::basic_stringbuf::setbuf.3 b/man/std::basic_stringbuf::setbuf.3 index ff749e450..d311331a5 100644 --- a/man/std::basic_stringbuf::setbuf.3 +++ b/man/std::basic_stringbuf::setbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_stringbuf::setbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::setbuf \- std::basic_stringbuf::setbuf + .SH Synopsis protected: virtual std::basic_streambuf* setbuf( char_type* s, std::streamsize @@ -16,12 +19,12 @@ .SH Parameters - s - pointer to the first byte in the user-provided buffer or null - n - the number of bytes in the user-provided buffer or zero + s - pointer to the first CharT in the user-provided buffer or null + n - the number of CharT elements in the user-provided buffer or zero .SH Return value - *this, cast to the base class std::basic_streambuf. + this .SH Notes @@ -31,14 +34,14 @@ .SH Example - Test for the stringstream's setbuf functionality + Test for the stringstream's setbuf functionality. + - // Run this code #include #include - + int main() { std::ostringstream ss; @@ -56,4 +59,4 @@ .SH See also pubsetbuf invokes setbuf() - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::basic_stringbuf::str.3 b/man/std::basic_stringbuf::str.3 index 7d865ba34..ba2785791 100644 --- a/man/std::basic_stringbuf::str.3 +++ b/man/std::basic_stringbuf::str.3 @@ -1,78 +1,110 @@ -.TH std::basic_stringbuf::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::str \- std::basic_stringbuf::str + .SH Synopsis - std::basic_string str() const; \fB(1)\fP - void str( const std::basic_string& s); \fB(2)\fP + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); Gets and sets the underlying string. + In the descriptions below, buf and mode are exposition-only data members of *this. + 1) Creates and returns a std::basic_string object containing a copy of this std::basic_stringbuf's underlying character sequence. For input-only streams, the returned string contains the characters from the range [eback(), egptr()). For input/output or output-only streams, contains the characters from pbase() to the last character in the sequence regardless of egptr() and epptr(). - The member character sequence in a buffer open for writing can be - over-allocated for efficiency purposes. In that case, only the - initialized characters are returned: these characters are the ones - that were obtained from the string argument of the constructor, the - string argument of the most recent call to the second overload of \fI(since C++11)\fP - str(), or from an write operation. Typical implementation that uses - over-allocation maintains a high-watermark pointer to track the end of - the initialized part of the buffer and this overload returns the - characters from pbase() to the high-watermark pointer - - 2) Deletes the entire underlying character sequence of this std::basic_stringbuf and - then configures a new underlying character sequence containing a copy of the - contents of s. The pointers of std::basic_streambuf are initialized as follows: - - For input streams (mode & ios_base::in == true), eback() points at the first - character, gptr() == eback(), and egptr() == eback() + s.size(): the subsequent - input will read the first character copied from s. - For output streams (mode & ios_base::out == true), pbase() points at the first - character and epptr() >= pbase() + s.size() (epptr is allowed to point farther so - that the following sputc() wouldn't immediately call overflow()) - - For append streams (mode & ios_base::ate == true), pptr() == pbase() + s.size(), so - that subsequent output will be appended to the last character copied from s (since - C++11) - For no-appending output streams, pptr() == pbase(), so that subsequent output will - overwrite the characters copied from s. + The member character sequence in a buffer open for writing can be over-allocated for + efficiency purposes. In that case, only the initialized characters are returned: + these characters are the ones that were obtained from the string argument of the + constructor, the string argument of the most recent call to a setter overload of + str(), or from a write operation. A typical implementation that uses over-allocation + maintains a high-watermark pointer to track the end of the initialized part of the + buffer and this overload returns the characters from pbase() to the high-watermark + pointer. + + Equivalent to return std::basic_string(view(), get_allocator());. + + 2) Same as \fB(1)\fP, except that a is used to construct the returned std::basic_string. + Equivalent to return std::basic_string(view(), a);. + This overload participates in overload resolution only if SAlloc meets the + requirements of Allocator. + 3) Creates a std::basic_string object as if by move constructing it from *this's + underlying character sequence in buf. buf may need to be adjusted to contain the + same content as in \fB(1)\fP at first. After that, sets buf to empty and calls + init_buf_ptrs(), then returns the std::basic_string object. + 4) Replaces the underlying character sequence as if by buf = s, then calls + init_buf_ptrs(). + 5) Same as \fB(4)\fP, except the type of s's allocator is not Allocator. + This overload participates in overload resolution only if std::is_same_v is false. + 6) Replaces the underlying character sequence as if by buf = std::move(s), then + calls init_buf_ptrs(). + 7) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the underlying character sequence as if by buf = sv, + then calls init_buf_ptrs(). + This overload participates in overload resolution only if + std::is_convertible_v> is true. .SH Parameters - s - a string object holding the replacement character sequence + s - a std::basic_string object holding the replacement character sequence + t - an object (convertible to std::basic_string_view) holding the replacement + character sequence + a - allocator to use for all memory allocations of the returned std::basic_string .SH Return value - 1) A string object holding a copy of this buffer's underlying character sequence. - 2) \fI(none)\fP + 1-3) A std::basic_string object holding this buffer's underlying character sequence. + 4-7) \fI(none)\fP .SH Notes - This function is typically accessed through std::basic_stringstream::str(). + This function is typically accessed through std::basic_istringstream::str(), + std::basic_ostringstream::str(), or std::basic_stringstream::str(). + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view .SH Example - + // Run this code - #include #include + #include + int main() { int n; - + std::istringstream in; // could also use in("1 2") in.rdbuf()->str("1 2"); // set the get area in >> n; std::cout << "after reading the first int from \\"1 2\\", the int is " << n << ", str() = \\"" << in.rdbuf()->str() << "\\"\\n"; // or in.str() - + std::ostringstream out("1 2"); out << 3; std::cout << "after writing the int '3' to output stream \\"1 2\\"" << ", str() = \\"" << out.str() << "\\"\\n"; - + std::ostringstream ate("1 2", std::ios_base::ate); // C++11 ate << 3; std::cout << "after writing the int '3' to append stream \\"1 2\\"" @@ -85,7 +117,25 @@ after writing the int '3' to output stream "1 2", str() = "3 2" after writing the int '3' to append stream "1 2", str() = "1 23" + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP did not specify the content + LWG 432 C++98 of the underlying character sequence both specified + 2. overload \fB(4)\fP did not specify how the + input and output sequences are initialized + overload \fB(4)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(mode & std::ios_base::out) beyond that position + == true + .SH See also - str gets or sets the contents of underlying string device object - \fI(public member function of std::basic_stringstream)\fP + gets or sets the contents of underlying string device object + str \fI(public member function of std::basic_stringstream)\fP + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function)\fP diff --git a/man/std::basic_stringbuf::swap.3 b/man/std::basic_stringbuf::swap.3 index c15529c16..60e1e3222 100644 --- a/man/std::basic_stringbuf::swap.3 +++ b/man/std::basic_stringbuf::swap.3 @@ -1,9 +1,17 @@ -.TH std::basic_stringbuf::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::swap \- std::basic_stringbuf::swap + .SH Synopsis - void swap( std::basic_stringbuf& rhs ) \fI(since C++11)\fP + void swap( basic_stringbuf& rhs ); \fI(since C++11)\fP + \fI(until C++20)\fP + void swap( basic_stringbuf& rhs ) noexcept(/* see below */); \fI(since C++20)\fP Swaps the state and the contents of *this and rhs. + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + .SH Parameters rhs - another basic_stringbuf @@ -12,43 +20,57 @@ \fI(none)\fP +.SH Exceptions + + (since + May throw implementation-defined exceptions. C++11) + (until + C++20) + noexcept specification: (since + noexcept(std::allocator_traits::propagate_on_container_swap::value C++20) + || std::allocator_traits::is_always_equal::value) + .SH Notes - This function is called automatically when swapping std::stringstream objects, it is + This function is called automatically when swapping std::stringstream objects. It is rarely necessary to call it directly. .SH Example - + // Run this code + #include + #include #include #include - #include - + int main() { - std::istringstream one("one"); std::ostringstream two("two"); - - std::cout << "Before swap, one = \\"" << one.str() << '"' - << " two = \\"" << two.str() << "\\"\\n"; - - *one.rdbuf()->swap(*two.rdbuf()); - - std::cout << "Before swap, one = \\"" << one.str() << '"' - << " two = \\"" << two.str() << "\\"\\n"; + + std::cout << "Before swap: one = " << std::quoted(one.str()) + << ", two = " << std::quoted(two.str()) << ".\\n"; + + one.rdbuf()->swap(*two.rdbuf()); + + std::cout << "After swap: one = " << std::quoted(one.str()) + << ", two = " << std::quoted(two.str()) << ".\\n"; } .SH Output: - Before swap, one = "one" two = "two" - Before swap, one = "two" two = "one" + Before swap: one = "one", two = "two". + After swap: one = "two", two = "one". .SH See also constructor constructs a basic_stringbuf object - \fI(public member function)\fP + \fI(public member function)\fP swap swaps two string streams - \fI(C++11)\fP \fI(public member function of std::basic_stringstream)\fP + \fI(C++11)\fP \fI\fI(public member\fP function of\fP + std::basic_stringstream) + +.SH Category: + * conditionally noexcept diff --git a/man/std::basic_stringbuf::underflow.3 b/man/std::basic_stringbuf::underflow.3 index f564cefcc..e5d49cc92 100644 --- a/man/std::basic_stringbuf::underflow.3 +++ b/man/std::basic_stringbuf::underflow.3 @@ -1,4 +1,7 @@ -.TH std::basic_stringbuf::underflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringbuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::underflow \- std::basic_stringbuf::underflow + .SH Synopsis protected: virtual int_type underflow() @@ -30,41 +33,44 @@ .SH Example - + // Run this code - #include #include - + #include + struct mybuf : std::stringbuf { mybuf(const std::string& new_str, - std::ios_base::openmode which = std::ios_base::in|std::ios_base::out) - : std::stringbuf(new_str, which) {} - - int_type overflow(int_type c) { - std::cout << "Before overflow(): get area size is " << egptr()-eback() << ' ' - << " the put area size is " << epptr()-pbase() << '\\n'; + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out) + : std::stringbuf(new_str, which) {} + + int_type overflow(int_type c) + { + std::cout << "Before overflow(): get area size is " << egptr() - eback() + << ", the put area size is " << epptr() - pbase() << '\\n'; int_type rc = std::stringbuf::overflow(c); - std::cout << "After overflow(): get area size is " << egptr()-eback() << ' ' - << " put area size is " << epptr()-pbase() << '\\n'; + std::cout << "After overflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; return rc; } - - int_type underflow() { - std::cout << "Before underflow(): get area size is " << egptr()-eback() << ' ' - << " put area size is " << epptr()-pbase() << '\\n'; + + int_type underflow() + { + std::cout << "Before underflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; int_type ch = std::stringbuf::underflow(); - std::cout << "After underflow(): get area size is " << egptr()-eback() << ' ' - << " put area size is " << epptr()-pbase() << '\\n'; - if(ch == EOF) + std::cout << "After underflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + + if (ch == EOF) std::cout << "underflow() returns EOF\\n"; else std::cout << "underflow() returns '" << char(ch) << "'\\n"; return ch; } }; - + int main() { mybuf sbuf("123"); // read-write stream @@ -74,14 +80,15 @@ // three calls return the characters '1', '2', '3' // the fourth call, gptr() == egptr() and underflow() is called // underflow returns EOF - std::cout << n << '\\n'; + std::cout << "n = " << n << '\\n'; stream.clear(); // clear the eofbit - + stream << "123456"; // sputc() is called 6 times // first three calls store "123" in the existing buffer // 4th call finds that pptr() == epptr() and calls overflow() // overflow() grows the buffer and sets egptr() to 4 // 5th and 6th calls store '5' and '6', advancing pptr() + stream >> n; // calls sgetc() 4 times // 1st call returns the '4' that was made available by overflow() // on the 2nd call, egptr() == egptr() and underflow() is called @@ -89,33 +96,44 @@ // 3rd sgetc() returns '6' // 4th sgetc() finds gptr() == egptr(), calls underflow() // underflow() returns EOF - std::cout << n << '\\n'; + + std::cout << "n = " << n << '\\n'; } .SH Possible output: - Before underflow(): get area size is 3 put area size is 3 - After underflow(): get area size is 3 put area size is 3 + Before underflow(): get area size is 3, put area size is 15 + After underflow(): get area size is 3, put area size is 15 underflow() returns EOF - 123 - Before overflow(): get area size is 3 the put area size is 3 - After overflow(): get area size is 4 put area size is 35 - Before underflow(): get area size is 4 put area size is 35 - After underflow(): get area size is 6 put area size is 35 - underflow() returns '5' - Before underflow(): get area size is 6 put area size is 35 - After underflow(): get area size is 6 put area size is 35 + n = 123 + Before underflow(): get area size is 3, put area size is 15 + After underflow(): get area size is 6, put area size is 15 + underflow() returns '4' + Before underflow(): get area size is 6, put area size is 15 + After underflow(): get area size is 6, put area size is 15 underflow() returns EOF - 456 + n = 456 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether characters appended by + LWG 432 C++98 overflow() made clear + are considered to be part of the input sequence .SH See also underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + underflow reads a character from the input sequence without advancing the next \fB[virtual]\fP pointer - \fI(virtual protected member function of std::strstreambuf)\fP + \fI(virtual protected member function of std::strstreambuf)\fP sgetc reads one character from the input sequence without advancing the sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::basic_stringbuf::view.3 b/man/std::basic_stringbuf::view.3 new file mode 100644 index 000000000..eb1842d18 --- /dev/null +++ b/man/std::basic_stringbuf::view.3 @@ -0,0 +1,50 @@ +.TH std::basic_stringbuf::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::view \- std::basic_stringbuf::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Creates and returns a std::basic_string_view over the underlying character sequence. + + * For input-only streams, the returned view represents the range [eback(), + egptr()). + * For input/output or output-only streams, references the characters from pbase() + to the last character in the sequence regardless of egptr() and epptr(). + * If the stream is neither input nor output, returns std::basic_string_view{}. + + The member character sequence in a buffer open for writing can be over-allocated for + efficiency purposes. In that case, only the initialized characters are referenced: + these characters are the ones that were obtained from the string argument of the + constructor, the string argument used by the most recent call to a setter overload + of str(), or from a write operation. A typical implementation that uses + over-allocation maintains a high-watermark pointer to track the end of the + initialized part of the buffer and the returned view references the characters from + pbase() to the high-watermark pointer. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A view over the underlying character sequence. + +.SH Notes + + Using of the return value is undefined behavior if the underlying character sequence + is destroyed or invalidated, unless the return value is empty. + + This function is typically accessed through std::basic_istringstream::view(), + std::basic_ostringstream::view(), or std::basic_stringstream::view(). + +.SH See also + + replaces or obtains a copy of the associated character + str string + \fI(public member function)\fP + returns a non-modifiable string_view into the entire + operator basic_string_view string + \fI(C++17)\fP \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::basic_stringstream.3 b/man/std::basic_stringstream.3 index 9655dc5d4..1d773afdb 100644 --- a/man/std::basic_stringstream.3 +++ b/man/std::basic_stringstream.3 @@ -1,66 +1,75 @@ -.TH std::basic_stringstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream \- std::basic_stringstream + .SH Synopsis Defined in header - template< - - class CharT, \fI(until C++11)\fP - class Traits = std::char_traits - - > class basic_stringstream; template< class CharT, - class Traits = std::char_traits, \fI(since C++11)\fP + class Traits = std::char_traits, class Allocator = std::allocator + > class basic_stringstream + + : public basic_iostream; - > class basic_stringstream; + The class template std::basic_stringstream implements input and output operations on + string based streams. It effectively stores an instance of std::basic_string and + performs the input and output operations on it. - The class template std::basic_stringstream implements input/output operations on - memory (std::basic_string) based streams. It essentially wraps a raw string device - implementation (std::basic_stringbuf) into a higher-level interface - (std::basic_iostream). The complete interface to unique std::basic_stringbuf members - is provided. + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_iostream. The + complete interface to unique std::basic_stringbuf members is provided. std-basic stringstream-inheritance.svg - About this image Inheritance diagram - Two specializations for common character types are also defined: + Several typedefs for common character types are provided: Defined in header - Type Definition - stringstream basic_stringstream - wstringstream basic_stringstream + Type Definition + std::stringstream std::basic_stringstream + std::wstringstream std::basic_stringstream .SH Member types Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type - allocator_type Allocator \fI(since C++11)\fP + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) .SH Member functions constructor constructs the string stream - \fI(public member function)\fP + \fI(public member function)\fP operator= moves the string stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP rdbuf returns the underlying raw string device object - \fI(public member function)\fP + \fI(public member function)\fP .SH String operations str gets or sets the contents of underlying string device object - \fI(public member function)\fP + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP .SH Non-member functions std::swap(std::basic_istringstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP Inherited from std::basic_istream @@ -68,66 +77,66 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -140,45 +149,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -186,40 +195,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -227,76 +236,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::basic_stringstream::basic_stringstream.3 b/man/std::basic_stringstream::basic_stringstream.3 index c520b1a74..c017c138f 100644 --- a/man/std::basic_stringstream::basic_stringstream.3 +++ b/man/std::basic_stringstream::basic_stringstream.3 @@ -1,47 +1,143 @@ -.TH std::basic_stringstream::basic_stringstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringstream::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::basic_stringstream \- std::basic_stringstream::basic_stringstream + .SH Synopsis - explicit basic_stringstream( ios_base::openmode mode = \fB(1)\fP - ios_base::in|ios_base::out ); - explicit basic_stringstream( const - std::basic_string& str, \fB(2)\fP - ios_base::openmode mode = - ios_base::in|ios_base::out ); - basic_stringstream( basic_stringstream&& other ); \fB(3)\fP \fI(since C++11)\fP + explicit basic_stringstream( std::ios_base::openmode mode = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_stringstream() + : basic_stringstream(std::ios_base::in | \fB(2)\fP \fI(since C++11)\fP + std::ios_base::out) {} + explicit basic_stringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + explicit basic_stringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + basic_stringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_stringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + \fB(1)\fP + basic_stringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringstream(str, std::ios_base::in | + std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_stringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + explicit basic_stringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + basic_stringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_stringstream( const StringViewLike& t, const Allocator& \fB(11)\fP (since C++26) + a ); + basic_stringstream( basic_stringstream&& other ); \fB(12)\fP \fI(since C++11)\fP Constructs new string stream. - 1) Constructs new underlying string device. The underlying basic_stringbuf object is - constructed as basic_stringbuf(mode). + Given + + * base_type as std::basic_iostream, and + * buf_type as std::basic_stringbuf, - 2) Uses a copy of str as initial contents of the underlying string device. The - underlying basic_stringbuf object is constructed as - basic_stringbuf(str, mode). + the std::basic_iostream base and the exposition-only data member sb are initialized + as follows. - 3) Move constructor. Constructs the file stream with the state of other using move - semantics. + Over std::basic_iostream base sb + load + \fB(1)\fP buf_type(mode) + \fB(2)\fP buf_type(std::ios_base::in | + std::ios_base::out) + \fB(3)\fP buf_type(str, mode) + \fB(4)\fP base_type(std::addressof(sb))^[1] buf_type(std::move(str), mode) + \fB(5)\fP buf_type(mode, a) + \fB(6)\fP buf_type(str, mode, a) + \fB(7)\fP buf_type(str, std::ios_base::in | + std::ios_base::out, a) + \fB(8)\fP buf_type(str, mode) + \fB(9)\fP {t, mode, Allocator()} + \fB(10)\fP std::addressof(sb) {t, mode, a} + \fB(11)\fP {t, std::ios_base::in | + std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_iostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. .SH Parameters str - string to use as initial contents of the string stream - specifies stream open mode. It is bitmask type, the following constants are + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are defined: - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode other - another string stream to use as source +.SH Notes + + Construction of one-off basic_stringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + .SH Example - + // Run this code #include #include + int main() { // default constructor (input/output stream) @@ -50,12 +146,12 @@ int n = 0; buf1 >> n; std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; - + // input stream std::istringstream inbuf("-10"); inbuf >> n; std::cout << "n = " << n << '\\n'; - + // output stream in append mode \fI(C++11)\fP std::ostringstream buf2("test", std::ios_base::ate); buf2 << '1'; @@ -68,9 +164,18 @@ n = -10 test1 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + .SH See also str gets or sets the contents of underlying string device object - \fI(public member function)\fP - constructor constructs a basic_stringbuf object - \fI(public member function of std::basic_stringbuf)\fP + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::basic_stringstream::operator=.3 b/man/std::basic_stringstream::operator=.3 index 4b05b298f..11454b1f2 100644 --- a/man/std::basic_stringstream::operator=.3 +++ b/man/std::basic_stringstream::operator=.3 @@ -1,13 +1,19 @@ -.TH std::basic_stringstream::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::operator= \- std::basic_stringstream::operator= + .SH Synopsis basic_stringstream& operator=( basic_stringstream&& other ); \fI(since C++11)\fP - Moves the string stream. The source stream becomes of invalid state after the - operation. + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_iostream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. .SH Parameters - other - string stream to move. other becomes of invalid state after the operation. + other - string stream to move from .SH Return value @@ -20,9 +26,13 @@ .SH See also - swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP -.SH Category: + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Category: * Todo no example diff --git a/man/std::basic_stringstream::rdbuf.3 b/man/std::basic_stringstream::rdbuf.3 index 99792232c..f35cd4f29 100644 --- a/man/std::basic_stringstream::rdbuf.3 +++ b/man/std::basic_stringstream::rdbuf.3 @@ -1,4 +1,7 @@ -.TH std::basic_stringstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::rdbuf \- std::basic_stringstream::rdbuf + .SH Synopsis std::basic_stringbuf* rdbuf() const; @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::basic_stringstream::str.3 b/man/std::basic_stringstream::str.3 index 5b578e129..1202dfdad 100644 --- a/man/std::basic_stringstream::str.3 +++ b/man/std::basic_stringstream::str.3 @@ -1,24 +1,48 @@ -.TH std::basic_stringstream::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::str \- std::basic_stringstream::str + .SH Synopsis - std::basic_string str() const; \fB(1)\fP - void str(const std::basic_string& new_str); \fB(2)\fP + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); Manages the contents of the underlying string object. - 1) Returns a copy of the underlying string as if by calling rdbuf()->str(). - - 2) Replaces the contents of the underlying string as if by calling - rdbuf()->str(new_str). + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. .SH Parameters - new_str - new contents of the underlying string + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string .SH Return value - 1) a copy of the underlying string object. - - 2) \fI(none)\fP + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP .SH Notes @@ -27,41 +51,49 @@ of str() (for example in auto *ptr = out.str().c_str();) results in a dangling pointer. + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + .SH Example - + // Run this code - #include #include + #include + int main() { int n; - - std::istringstream in; // could also use in("1 2") + + std::istringstream in; // could also use in("1 2") in.str("1 2"); in >> n; - std::cout << "after reading the first int from \\"1 2\\", the int is " + std::cout << "After reading the first int from \\"1 2\\", the int is " << n << ", str() = \\"" << in.str() << "\\"\\n"; - + std::ostringstream out("1 2"); out << 3; - std::cout << "after writing the int '3' to output stream \\"1 2\\"" + std::cout << "After writing the int '3' to output stream \\"1 2\\"" << ", str() = \\"" << out.str() << "\\"\\n"; - + std::ostringstream ate("1 2", std::ios_base::ate); ate << 3; - std::cout << "after writing the int '3' to append stream \\"1 2\\"" + std::cout << "After writing the int '3' to append stream \\"1 2\\"" << ", str() = \\"" << ate.str() << "\\"\\n"; } .SH Output: - after reading the first int from "1 2", the int is 1, str() = "1 2" - after writing the int '3' to output stream "1 2", str() = "3 2" - after writing the int '3' to append stream "1 2", str() = "1 23" + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" .SH See also - str replaces or obtains a copy of the associated character string - \fI(public member function of std::basic_stringbuf)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::basic_stringstream::swap.3 b/man/std::basic_stringstream::swap.3 index 002f9b8a9..cbf486e13 100644 --- a/man/std::basic_stringstream::swap.3 +++ b/man/std::basic_stringstream::swap.3 @@ -1,11 +1,14 @@ -.TH std::basic_stringstream::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::basic_stringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::swap \- std::basic_stringstream::swap + .SH Synopsis void swap( basic_stringstream& other ); \fI(since C++11)\fP Exchanges the state of the stream with those of other. - This is done by calling basic_istream::swap(other) and - rdbuf->swap(other->rdbuf). + This is done by calling basic_iostream::swap(other) and + rdbuf()->swap(*other.rdbuf()). .SH Parameters @@ -15,6 +18,10 @@ \fI(none)\fP +.SH Exceptions + + May throw implementation-defined exceptions. + .SH Example This section is incomplete @@ -23,10 +30,10 @@ .SH See also operator= moves the string stream - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps two basic_stringbuf objects - \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP -.SH Category: +.SH Category: * Todo no example diff --git a/man/std::basic_stringstream::view.3 b/man/std::basic_stringstream::view.3 new file mode 100644 index 000000000..bb7272455 --- /dev/null +++ b/man/std::basic_stringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_stringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::view \- std::basic_stringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::basic_syncbuf.3 b/man/std::basic_syncbuf.3 new file mode 100644 index 000000000..3ab40109a --- /dev/null +++ b/man/std::basic_syncbuf.3 @@ -0,0 +1,231 @@ +.TH std::basic_syncbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf \- std::basic_syncbuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, \fI(since C++20)\fP + class Allocator = std::allocator + + > class basic_syncbuf : public std::basic_streambuf + + std::basic_syncbuf is a wrapper for a std::basic_streambuf (provided at construction + time as a pointer). It accumulates output in its own internal buffer, and atomically + transmits its entire contents to the wrapped buffer on destruction and when + explicitly requested, so that they appear as a contiguous sequence of characters. It + guarantees that there are no data races and no interleaving of characters sent to + the wrapped buffer as long as all other outputs made to the same buffer are made + through, possibly different, instances of std::basic_syncbuf. + + Typical implementation of std::basic_syncbuf holds a pointer to the wrapped + std::basic_streambuf, a boolean flag indicating whether the buffer will transmit its + contents to the wrapped buffer on sync (flush), a boolean flag indicating a pending + flush when the policy is to not emit on sync, an internal buffer that uses Allocator + (such as std::string), and a pointer to a mutex used to synchronize emit between + multiple threads accessing the same wrapped stream buffer (these mutexes may be in a + hash map with pointers to std::basic_streambuf objects used as keys). + + Like other streambuf classes, std::basic_syncbuf is normally only accessed through + the corresponding stream, std::osyncstream, not directly. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::syncbuf std::basic_syncbuf + std::wsyncbuf std::basic_syncbuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + streambuf_type std::basic_streambuf + +.SH Member functions + +.SH Public member functions + constructor constructs a basic_syncbuf object + \fI(public member function)\fP + operator= assigns a basic_syncbuf object + \fI(public member function)\fP + swap swaps two basic_syncbuf objects + \fI(public member function)\fP + destructor destroys the basic_syncbuf and emits its internal buffer + \fI(public member function)\fP + atomically transmits the entire internal buffer to the wrapped + emit streambuf + \fI(public member function)\fP + get_wrapped retrieves the wrapped streambuf pointer + \fI(public member function)\fP + get_allocator retrieves the allocator used by this basic_syncbuf + \fI(public member function)\fP + set_emit_on_sync changes the current emit-on-sync policy + \fI(public member function)\fP +.SH Protected member functions + either emits, or records a pending flush, depending on the current + sync emit-on-sync policy + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_syncbuf) specializes the std::swap algorithm + (C++20) \fI(function template)\fP + +Inherited from std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) +.SH Locales + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + +.SH Positioning + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + +.SH Putback + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + + +.SH Protected member functions + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Get area + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + eback returns a pointer to the beginning, current character and the end of + gptr the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + pbase returns a pointer to the beginning, current character and the end of + pptr the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_syncbuf 201803L (C++20) Synchronized buffered ostream (std::syncbuf, + std::osyncstream) and manipulators diff --git a/man/std::basic_syncbuf::basic_syncbuf.3 b/man/std::basic_syncbuf::basic_syncbuf.3 new file mode 100644 index 000000000..432c4bc6a --- /dev/null +++ b/man/std::basic_syncbuf::basic_syncbuf.3 @@ -0,0 +1,55 @@ +.TH std::basic_syncbuf::basic_syncbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::basic_syncbuf \- std::basic_syncbuf::basic_syncbuf + +.SH Synopsis + basic_syncbuf() \fB(1)\fP + : basic_syncbuf( nullptr ) + explicit basic_syncbuf( streambuf_type* obuf ) \fB(2)\fP + : basic_syncbuf( obuf, Allocator() ) {} + basic_syncbuf( streambuf_type* obuf, const Allocator& a ); \fB(3)\fP + basic_syncbuf( basic_syncbuf&& rhs ); \fB(4)\fP + + 1) Default constructor: creates an instance of std::basic_syncbuf with emit-on-sync + policy set to false, wrapped streambuffer set to nullptr, and using + default-constructed Allocator as the allocator for temporary storage. + 2,3) Creates an instance of std::basic_syncbuf with emit-on-sync policy set to + false, wrapped streambuffer set to obuf, and using a as the allocator for temporary + storage. + 4) Move constructor: move-constructs a std::basic_syncbuf object by moving all + contents from another std::basic_syncbuf object rhs, including the temporary + storage, the wrapped stream pointer, policy, and all other state (such as the mutex + pointer). After move, rhs is not associated with a stream, and rhs.get_wrapped() == + nullptr. The put area member pointers of the base class std::basic_streambuf of rhs + are guaranteed to be null. Destroying a moved-from rhs will not produce any output. + +.SH Parameters + + obuf - pointer to the std::basic_streambuf to wrap + a - the allocator to use for temporary storage + rhs - another std::basic_syncbuf to move from + +.SH Exceptions + + 2,3) May throw std::bad_alloc from the constructor of the internal temporary storage + or std::system_error from the mutex construction. + +.SH Notes + + Typically called by the appropriate constructors of std::basic_osyncstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + emit atomically transmits the entire internal buffer to the wrapped streambuf + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::emit.3 b/man/std::basic_syncbuf::emit.3 new file mode 100644 index 000000000..1635ba3f0 --- /dev/null +++ b/man/std::basic_syncbuf::emit.3 @@ -0,0 +1,59 @@ +.TH std::basic_syncbuf::emit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::emit \- std::basic_syncbuf::emit + +.SH Synopsis + bool emit(); + + Atomically transmits all pending output to the wrapped stream. + + All emit() calls transferring characters to the same wrapped stream buffer object + appear to execute in a total order, where each emit() call synchronizes-with + subsequent emit() calls in that total order, even if these calls are made through + difference instances of std::basic_syncbuf/std::basic_osyncstream. In practice, this + means that emit() takes a lock uniquely associated with the wrapped stream object: + for example, it could be held in a static hash map where the address of the wrapped + stream is used as the key. + + If a call had been made to sync since the last call to emit(), then also flushes the + wrapped stream by calling pubsync() on it. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if all of the following is true: + + * there is a wrapped stream (the wrapped streambuf pointer is not null) + * all characters from the temporary storage were successfully sent into the + wrapped stream + * the call to pubsync(), if requested, also completed successfully. + + Returns false otherwise. + +.SH Notes + + Normally called by the destructor or move assignment of the owning + std::basic_osyncstream, or by std::basic_osyncstream::emit. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + destroys the basic_osyncstream and emits its internal buffer + destructor \fI\fI(public member\fP function of\fP + std::basic_osyncstream) + calls emit() on the underlying basic_syncbuf to transmit its internal + emit data to the final destination + \fI\fI(public member\fP function of\fP + std::basic_osyncstream) + constructor constructs a basic_syncbuf object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::get_allocator.3 b/man/std::basic_syncbuf::get_allocator.3 new file mode 100644 index 000000000..99dcca6e9 --- /dev/null +++ b/man/std::basic_syncbuf::get_allocator.3 @@ -0,0 +1,28 @@ +.TH std::basic_syncbuf::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::get_allocator \- std::basic_syncbuf::get_allocator + +.SH Synopsis + allocator_type get_allocator() const noexcept; + + Returns a copy of the allocator that was passed in as the constructor argument or + replaced through the assignment operator. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_syncbuf object + \fI(public member function)\fP + operator= assigns a basic_syncbuf object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::get_wrapped.3 b/man/std::basic_syncbuf::get_wrapped.3 new file mode 100644 index 000000000..1d864e1d9 --- /dev/null +++ b/man/std::basic_syncbuf::get_wrapped.3 @@ -0,0 +1,31 @@ +.TH std::basic_syncbuf::get_wrapped 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::get_wrapped \- std::basic_syncbuf::get_wrapped + +.SH Synopsis + streambuf_type* get_wrapped() const noexcept; + + Returns a pointer to the wrapped std::basic_streambuf. + +.SH Parameters + + \fI(none)\fP + +.SH Notes + + This function is not expected to be called directly: it is called through + std::basic_osyncstream::get_wrapped. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + obtains a pointer to the final destination stream buffer + get_wrapped \fI\fI(public member\fP function of\fP + std::basic_osyncstream) + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::operator=.3 b/man/std::basic_syncbuf::operator=.3 new file mode 100644 index 000000000..e2174b8f0 --- /dev/null +++ b/man/std::basic_syncbuf::operator=.3 @@ -0,0 +1,49 @@ +.TH std::basic_syncbuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::operator= \- std::basic_syncbuf::operator= + +.SH Synopsis + basic_syncbuf& operator=( basic_syncbuf&& other ); + + First, calls emit() to transmit all pending output (and delayed flush, if any) to + the wrapped stream. + + Then performs move-assignment by moving all contents from other, including the + temporary storage, the wrapped stream pointer, policy, and all other state (such as + the mutex pointer). After move, other is not associated with a stream, and + other.get_wrapped() == nullptr. The put area member pointers of the base class + std::basic_streambuf of other are guaranteed to be null. Destroying a moved-from + other will not produce any output. + + If std::allocator_traits::propagate_on_container_move_assignment::value + is false, then the allocator is unchanged. Otherwise, after move-assignment, + get_allocator() equals other.get_allocator(). + +.SH Parameters + + other - another std::basic_syncbuf to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + assigns a basic_osyncstream object + operator= \fI\fI(public member\fP function of\fP + std::basic_osyncstream) + constructor constructs a basic_syncbuf object + \fI(public member function)\fP + atomically transmits the entire internal buffer to the wrapped + emit streambuf + \fI(public member function)\fP + swap swaps two basic_syncbuf objects + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::set_emit_on_sync.3 b/man/std::basic_syncbuf::set_emit_on_sync.3 new file mode 100644 index 000000000..3742facc5 --- /dev/null +++ b/man/std::basic_syncbuf::set_emit_on_sync.3 @@ -0,0 +1,37 @@ +.TH std::basic_syncbuf::set_emit_on_sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::set_emit_on_sync \- std::basic_syncbuf::set_emit_on_sync + +.SH Synopsis + void set_emit_on_sync( bool b ) noexcept; + + Changes the current emit-on-sync policy. + + The value false (the default) indicates that any flush will be postponed until a + call to emit. + + The value true makes flushes apply immediately. + +.SH Parameters + + b - new value for the emit-on-sync policy + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + atomically transmits the entire internal buffer to the wrapped + emit streambuf + \fI(public member function)\fP + emit_on_flush controls whether a stream's basic_syncbuf emits on flush + noemit_on_flush \fI(function template)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::swap.3 b/man/std::basic_syncbuf::swap.3 new file mode 100644 index 000000000..ff99d6ca9 --- /dev/null +++ b/man/std::basic_syncbuf::swap.3 @@ -0,0 +1,24 @@ +.TH std::basic_syncbuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::swap \- std::basic_syncbuf::swap + +.SH Synopsis + void swap( basic_syncbuf& other ); + + Exchanges the contents of the sync stream buffer with those of other. + +.SH Parameters + + other - sync stream buffer to exchange contents with + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::sync.3 b/man/std::basic_syncbuf::sync.3 new file mode 100644 index 000000000..2e9761ac8 --- /dev/null +++ b/man/std::basic_syncbuf::sync.3 @@ -0,0 +1,42 @@ +.TH std::basic_syncbuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::sync \- std::basic_syncbuf::sync + +.SH Synopsis + protected: + int sync() override; + + First, records that a flush is pending, by updating the appropriate private flag. + + Then, if the current emit-on-sync policy is true, makes a call to emit(). + + Otherwise (if the emit-on-sync policy is false, which is the default), the flush is + suspended until emit() is called, such as through std::basic_osyncstream::emit() or + std::basic_osyncstream::~basic_osyncstream + +.SH Parameters + + \fI(none)\fP + +.SH Notes + + sync() or its equivalent is implicitly called by close(), seekoff(), and seekpos() + and explicitly called by std::basic_streambuf::pubsync() + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + calls emit() on the underlying basic_syncbuf to transmit its internal data + emit to the final destination + \fI(public member function of std::basic_osyncstream)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::basic_syncbuf::~basic_syncbuf.3 b/man/std::basic_syncbuf::~basic_syncbuf.3 new file mode 100644 index 000000000..b235b9c83 --- /dev/null +++ b/man/std::basic_syncbuf::~basic_syncbuf.3 @@ -0,0 +1,33 @@ +.TH std::basic_syncbuf::~basic_syncbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_syncbuf::~basic_syncbuf \- std::basic_syncbuf::~basic_syncbuf + +.SH Synopsis + ~basic_syncbuf(); + + Calls emit() to transmit all pending output (and delayed flush, if any) to the + wrapped stream. If an exception is thrown by this call, it is caught and ignored. + +.SH Parameters + + \fI(none)\fP + +.SH Notes + + Normally called by the destructor of the owning std::basic_osyncstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + destroys the basic_osyncstream and emits its internal buffer + destructor \fI\fI(public member\fP function of\fP + std::basic_osyncstream) + constructor constructs a basic_syncbuf object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::begin(std::initializer_list).3 b/man/std::begin(std::initializer_list).3 index 7d8d27821..0bf6c14bd 100644 --- a/man/std::begin(std::initializer_list).3 +++ b/man/std::begin(std::initializer_list).3 @@ -1,11 +1,15 @@ -.TH std::begin(std::initializer_list) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::begin(std::initializer_list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::begin(std::initializer_list) \- std::begin(std::initializer_list) + .SH Synopsis - template< class E > \fI(since C++11)\fP - const E* begin( initializer_list il ); \fI(until C++14)\fP - template< class E > \fI(since C++14)\fP - constexpr const E* begin( initializer_list il ); + Defined in header + template< class E > \fI(since C++11)\fP + const E* begin( std::initializer_list il ) noexcept; \fI(until C++14)\fP + template< class E > \fI(since C++14)\fP + constexpr const E* begin( std::initializer_list il ) noexcept; - The specialization of std::begin for initializer_list returns a pointer to the first + The overload of std::begin for initializer_list returns a pointer to the first element of il. .SH Parameters @@ -16,26 +20,23 @@ il.begin() -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include - + #include + #include + #include + int main() { - // range-based for uses std::begin and std::end to iterate - // over a given range; in this case, it's an initializer list - for (int i : {3, 1, 4, 1}) { - std::cout << i << '\\n'; - } + std::initializer_list il = {3, 1, 4, 1}; + + std::copy(std::begin(il), + std::end(il), + std::ostream_iterator(std::cout, "\\n")); } .SH Output: @@ -47,5 +48,5 @@ .SH See also - begin returns a pointer the first element - \fI(public member function)\fP + begin returns a pointer to the first element + \fI(public member function)\fP diff --git a/man/std::begin(std::valarray).3 b/man/std::begin(std::valarray).3 index eb61ca8d6..2fefe7cb8 100644 --- a/man/std::begin(std::valarray).3 +++ b/man/std::begin(std::valarray).3 @@ -1,19 +1,33 @@ -.TH std::begin(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::begin(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::begin(std::valarray) \- std::begin(std::valarray) + .SH Synopsis - template< class T > \fB(1)\fP \fI(since C++11)\fP - /*unspecified1*/ begin( valarray& v ); - template< class T > \fB(2)\fP \fI(since C++11)\fP - /*unspecified2*/ begin( const valarray& v ); + template< class T > \fB(1)\fP \fI(since C++11)\fP + /* see below */ begin( valarray& v ); + template< class T > \fB(2)\fP \fI(since C++11)\fP + /* see below */ begin( const valarray& v ); + + The overload of std::begin for valarray returns an iterator of unspecified type + referring to the first element in the numeric array. + + 1) The return type must + * meet the requirements of mutable LegacyRandomAccessIterator, + + * model contiguous_iterator, \fI(since C++20)\fP + + * have a member type value_type, which is T, and + * have a member type reference, which is T&. + 2) The return type must + * meet the requirements of constant LegacyRandomAccessIterator, - The specialization of std::begin for valarray returns an iterator of unspecified - type referring to the first element in the numeric array. + * model contiguous_iterator, \fI(since C++20)\fP - 1) The return type meets the requirements of mutable RandomAccessIterator. - 2) The return type meets the requirements of constant RandomAccessIterator. + * have a member type value_type, which is T, and + * have a member type reference, which is const T&. - The iterator obtained from this function is invalidated when the member function - resize() is called on the array v or when the lifetime of v ends, whichever comes - first. + The iterator returned from this function is invalidated when the member function + resize() is called on v or when the lifetime of v ends, whichever comes first. .SH Parameters @@ -25,7 +39,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes @@ -39,14 +53,54 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - std::end(std::valarray) specializes std::end - \fI(C++11)\fP \fI(function template)\fP + #include + #include + #include + + void show(const std::valarray& v) + { + std::for_each(std::begin(v), std::end(v), [](int c) + { + std::cout << c << ' '; + }); + std::cout << '\\n'; + }; + + int main() + { + const std::valarray x{47, 70, 37, 52, 90, 23, 17, 33, 22, 16, 21, 4}; + const std::valarray y{25, 31, 71, 56, 21, 21, 15, 34, 21, 27, 12, 6}; + + show(x); + show(y); -.SH Category: + const std::valarray z{x + y}; - * Todo no example + for (char c : z) + std::cout << c; + } + +.SH Output: + + 47 70 37 52 90 23 17 33 22 16 21 4 + 25 31 71 56 21 21 15 34 21 27 12 6 + Hello, C++! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. begin() was required to support replacement + LWG 2058 C++11 types 1. not required + 2. it was unspecified when the returned 2. specified + iterators will be invalidated + +.SH See also + + std::end(std::valarray) specializes std::end + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::begin,std::cbegin.3 b/man/std::begin,std::cbegin.3 new file mode 100644 index 000000000..976fab9ac --- /dev/null +++ b/man/std::begin,std::cbegin.3 @@ -0,0 +1,164 @@ +.TH std::begin,std::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::begin,std::cbegin \- std::begin,std::cbegin + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + (since + template< class C > C++11) + auto begin( C& c ) -> decltype(c.begin()); (until + C++17) + template< class C > (since + constexpr auto begin( C& c ) -> decltype(c.begin()); C++17) + (since + template< class C > C++11) + auto begin( const C& c ) -> decltype(c.begin()); (until + C++17) + template< class C > (since + constexpr auto begin( const C& c ) -> C++17) + decltype(c.begin()); \fB(1)\fP + (since + template< class T, std::size_t N > C++11) + T* begin( T (&array)[N] ); \fB(2)\fP (until + C++14) + template< class T, std::size_t N > (since + constexpr T* begin( T (&array)[N] ) noexcept; \fB(3)\fP C++14) + template< class C > + + constexpr auto cbegin( const C& c ) noexcept(/* see \fB(4)\fP (since + below */) C++14) + + -> decltype(std::begin(c)); + + Returns an iterator to the beginning of the given range. + + 1,2) Returns c.begin(), which is typically an iterator to the beginning of the + sequence represented by c. + 1) If C is a standard Container, returns a C::iterator object. + 2) If C is a standard Container, returns a C::const_iterator object. + 3) Returns a pointer to the beginning of array. + 4) Returns std::begin(c), with c always treated as const-qualified. + If C is a standard Container, returns a C::const_iterator object. + + range-begin-end.svg + +.SH Parameters + + c - a container or view with a begin member function + array - an array of arbitrary type + +.SH Return value + + 1,2) c.begin() + 3) array + 4) c.begin() + +.SH Exceptions + + 4) + noexcept specification: + noexcept(noexcept(std::begin(c))) + + Overloads + + Custom overloads of begin may be provided for classes and enumerations that do not + expose a suitable begin() member function, yet can be iterated. The following + overloads are already provided by the standard library: + + std::begin(std::initializer_list) overloads std::begin + \fI(C++11)\fP \fI(function template)\fP + std::begin(std::valarray) overloads std::begin + \fI(C++11)\fP \fI(function template)\fP + begin(std::filesystem::directory_iterator) range-based for loop support + end(std::filesystem::directory_iterator) \fI(function)\fP + \fI(C++17)\fP + begin(std::filesystem::recursive_directory_iterator) range-based for loop support + end(std::filesystem::recursive_directory_iterator) \fI(function)\fP + + Similar to the use of swap (described in Swappable), typical use of the begin + function in generic context is an equivalent of using std::begin; begin(arg);, which + allows both the ADL-selected overloads for user-defined types and the standard + library function templates to appear in the same overload set. + + template + void for_each(Container&& cont, Function f) + { + using std::begin; + auto it = begin(cont); + using std::end; + auto end_it = end(cont); + while (it != end_it) + { + f(*it); + ++it; + } + } + + Overloads of begin found by argument-dependent lookup can be used to + customize the behavior of std::ranges::begin, std::ranges::cbegin, and \fI(since C++20)\fP + other customization pointer objects depending on std::ranges::begin. + +.SH Notes + + The non-array overloads exactly reflect the behavior of C::begin. Their effects may + be surprising if the member function does not have a reasonable implementation. + + std::cbegin is introduced for unification of member and non-member range accesses. + See also LWG issue 2128. + + If C is a shallow-const view, std::cbegin may return a mutable iterator. Such + behavior is unexpected for some users. See also P2276 and P2278. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v = {3, 1, 4}; + auto vi = std::begin(v); + std::cout << std::showpos << *vi << '\\n'; + + int a[] = {-5, 10, 15}; + auto ai = std::begin(a); + std::cout << *ai << '\\n'; + } + +.SH Output: + + +3 + -5 + +.SH See also + + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::cbegin returns an iterator to the beginning of a read-only range + (C++20) (customization point object) + +.SH Category: + * conditionally noexcept diff --git a/man/std::begin.3 b/man/std::begin.3 deleted file mode 100644 index f29d80758..000000000 --- a/man/std::begin.3 +++ /dev/null @@ -1,78 +0,0 @@ -.TH std::begin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class C > \fB(1)\fP \fI(since C++11)\fP - auto begin( C& c ) -> decltype(c.begin()); - template< class C > \fB(1)\fP \fI(since C++11)\fP - auto begin( const C& c ) -> decltype(c.begin()); - template< class T, size_t N > \fB(2)\fP \fI(since C++11)\fP - T* begin( T (&array)[N] ); - template< class C > \fB(3)\fP \fI(since C++14)\fP - auto cbegin( const C& c ) -> decltype(std::begin(c)); - - Returns an iterator to the beginning of the given container c or array array. - - 1) Returns a possibly const-qualified iterator to the beginning of the container c. - 2) Returns a pointer to the beginning of the array array. - 3) Returns a const-qualified iterator to the beginning of the container c. - - range-begin-end.svg - -.SH Parameters - - c - a container with a begin method - array - an array of arbitrary type - -.SH Return value - - An iterator to the beginning of c or array - -.SH Notes - - In addition to being included in , std::begin is guaranteed to become - available if any of the following headers are included: , , - , , , , , , , - , and . - -.SH Specializations - - Custom specializations of std::begin may be provided for classes that do not expose - a suitable begin() member function, yet can be iterated. The following - specializations are already provided by the standard library: - - std::begin(std::initializer_list) specializes std::begin - \fI(C++11)\fP \fI(function template)\fP - std::begin(std::valarray) specializes std::begin - \fI(C++11)\fP \fI(function template)\fP - -.SH Example - - -// Run this code - - #include - #include - #include - - int main() - { - std::vector v = { 3, 1, 4 }; - auto vi = std::begin(v); - std::cout << *vi << '\\n'; - - int a[] = { -5, 10, 15 }; - auto ai = std::begin(a); - std::cout << *ai << '\\n'; - } - -.SH Output: - - 3 - -5 - -.SH See also - - end - cend returns an iterator to the end of a container or array - \fI(C++11)\fP \fI(function)\fP - \fI(C++14)\fP diff --git a/man/std::bernoulli_distribution.3 b/man/std::bernoulli_distribution.3 index 71ae33351..0ea521d0d 100644 --- a/man/std::bernoulli_distribution.3 +++ b/man/std::bernoulli_distribution.3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution \- std::bernoulli_distribution + .SH Synopsis Defined in header class bernoulli_distribution; \fI(since C++11)\fP @@ -8,52 +11,57 @@ P(b|p) =⎧ ⎨ - ⎩p if b == true - 1 − p if b == false + ⎩p, if b is true + 1 − p, if b is false + + std::bernoulli_distribution satisfies RandomNumberDistribution. .SH Member types - Member type Definition - result_type bool - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP bool + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics p returns the p distribution parameter (probability of generating true) - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include #include - #include + #include #include #include - + #include + int main() { std::random_device rd; @@ -61,22 +69,23 @@ // give "true" 1/4 of the time // give "false" 3/4 of the time std::bernoulli_distribution d(0.25); - + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n = 0; n < 10000; ++n) ++hist[d(gen)]; - } - for(auto p : hist) { - std::cout << std::boolalpha << std::setw(5) << p.first - << ' ' << std::string(p.second/500, '*') << '\\n'; - } + + std::cout << std::boolalpha; + for (auto const& [key, value] : hist) + std::cout << std::setw(5) << key << ' ' + << std::string(value / 500, '*') << '\\n'; } -.SH Output: +.SH Possible output: false *************** true **** .SH External links - Weisstein, Eric W. "Bernoulli Distribution." From MathWorld--A Wolfram Web Resource. + Weisstein, Eric W. "Bernoulli Distribution." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::bernoulli_distribution::bernoulli_distribution.3 b/man/std::bernoulli_distribution::bernoulli_distribution.3 index bf73e5470..5f2553427 100644 --- a/man/std::bernoulli_distribution::bernoulli_distribution.3 +++ b/man/std::bernoulli_distribution::bernoulli_distribution.3 @@ -1,12 +1,26 @@ -.TH std::bernoulli_distribution::bernoulli_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::bernoulli_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::bernoulli_distribution \- std::bernoulli_distribution::bernoulli_distribution + .SH Synopsis - explicit bernoulli_distribution( double p = 0.5 ); \fB(1)\fP \fI(since C++11)\fP - explicit bernoulli_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + bernoulli_distribution() : bernoulli_distribution(0.5) { } \fB(1)\fP \fI(since C++11)\fP + explicit bernoulli_distribution( double p ); \fB(2)\fP \fI(since C++11)\fP + explicit bernoulli_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs new distribution object. - Constructs new distribution object. The first version uses p as the distribution - parameter, the second version uses params as the distribution parameter. + 2) Uses p as the distribution parameter. + 3) Uses params as the distribution parameter. .SH Parameters p - the p distribution parameter (probability of generating true) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::bernoulli_distribution::max.3 b/man/std::bernoulli_distribution::max.3 index 132c70f0d..0e007a868 100644 --- a/man/std::bernoulli_distribution::max.3 +++ b/man/std::bernoulli_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::max \- std::bernoulli_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::bernoulli_distribution::min.3 b/man/std::bernoulli_distribution::min.3 index ef1ec8915..cd8e5e29c 100644 --- a/man/std::bernoulli_distribution::min.3 +++ b/man/std::bernoulli_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::min \- std::bernoulli_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::bernoulli_distribution::operator().3 b/man/std::bernoulli_distribution::operator().3 index d2468b144..9e1bcfb5e 100644 --- a/man/std::bernoulli_distribution::operator().3 +++ b/man/std::bernoulli_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::operator() \- std::bernoulli_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::bernoulli_distribution::p.3 b/man/std::bernoulli_distribution::p.3 index 8dd023546..fa65f49dd 100644 --- a/man/std::bernoulli_distribution::p.3 +++ b/man/std::bernoulli_distribution::p.3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution::p 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::p 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::p \- std::bernoulli_distribution::p + .SH Synopsis double p() const; \fI(since C++11)\fP @@ -15,5 +18,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::bernoulli_distribution::param.3 b/man/std::bernoulli_distribution::param.3 index 1ac567bf4..6f9944d7b 100644 --- a/man/std::bernoulli_distribution::param.3 +++ b/man/std::bernoulli_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::param \- std::bernoulli_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::bernoulli_distribution::reset.3 b/man/std::bernoulli_distribution::reset.3 index cb147479c..e36c42588 100644 --- a/man/std::bernoulli_distribution::reset.3 +++ b/man/std::bernoulli_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::bernoulli_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bernoulli_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bernoulli_distribution::reset \- std::bernoulli_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::beta,std::betaf,std::betal.3 b/man/std::beta,std::betaf,std::betal.3 new file mode 100644 index 000000000..730cf1776 --- /dev/null +++ b/man/std::beta,std::betaf,std::betal.3 @@ -0,0 +1,130 @@ +.TH std::beta,std::betaf,std::betal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::beta,std::betaf,std::betal \- std::beta,std::betaf,std::betal + +.SH Synopsis + double beta( double x, double y ); + + float betaf( float x, float y ); \fB(1)\fP + + long double betal( long double x, long double y ); + Promoted beta( Arithmetic x, Arithmetic y ); \fB(2)\fP + + 1) Computes the beta function of x and y. + 2) A set of overloads or a function template for all combinations of arguments of + arithmetic type not covered by \fB(1)\fP. If any argument has integral type, it is cast to + double. If any argument is long double, then the return type Promoted is also long + double, otherwise the return type is always double. + + As all special functions, beta is only guaranteed to be available in if + __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least + 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any + standard library headers. + +.SH Parameters + + x, y - values of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the beta function of x and y, that is ∫1 + 0tx-1 + (1 - t)(y-1) + dt, or, equivalently, + + Γ(x)Γ(y) + Γ(x + y) + + is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If any argument is NaN, NaN is returned and domain error is not reported. + * The function is only required to be defined where both x and y are greater than + zero, and is allowed to report a domain error otherwise. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + beta(x, y) equals beta(y, x). + + When x and y are positive integers, beta(x, y) equals \\(\\frac{(x - 1)!(y - 1)!}{(x + + y - 1)!}\\) + + (x - 1)!(y - 1)! + (x + y - 1)! + + . Binomial coefficients can be expressed in terms of the beta function: + \\(\\binom{n}{k} = \\frac{1}{(n + 1)B(n - k + 1, k + 1)}\\)⎛ + ⎜ + ⎝n + k⎞ + ⎟ + ⎠= + + 1 + (n + 1)Β(n - k + 1, k + 1) + + . + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + #include + #include + + double binom(int n, int k) + { + return 1 / ((n + 1) * std::beta(n - k + 1, k + 1)); + } + + int main() + { + std::cout << "Pascal's triangle:\\n"; + for (int n = 1; n < 10; ++n) + { + std::cout << std::string(20 - n * 2, ' '); + for (int k = 1; k < n; ++k) + std::cout << std::setw(3) << binom(n, k) << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + Pascal's triangle: + + 2 + 3 3 + 4 6 4 + 5 10 10 5 + 6 15 20 15 6 + 7 21 35 35 21 7 + 8 28 56 70 56 28 8 + 9 36 84 126 126 84 36 9 + +.SH See also + + tgamma + tgammaf + tgammal gamma function + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + +.SH External links + + Weisstein, Eric W. "Beta Function." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::bidirectional_iterator.3 b/man/std::bidirectional_iterator.3 new file mode 100644 index 000000000..0c9987140 --- /dev/null +++ b/man/std::bidirectional_iterator.3 @@ -0,0 +1,72 @@ +.TH std::bidirectional_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bidirectional_iterator \- std::bidirectional_iterator + +.SH Synopsis + Defined in header + template< class I > + + concept bidirectional_iterator = + std::forward_iterator && + std::derived_from, + std::bidirectional_iterator_tag> && \fI(since C++20)\fP + requires(I i) { + { --i } -> std::same_as; + { i-- } -> std::same_as; + + }; + + The concept bidirectional_iterator refines forward_iterator by adding the ability to + move an iterator backward. + +.SH Notes + + Unlike the LegacyBidirectionalIterator requirements, the bidirectional_iterator + concept does not require dereference to return an lvalue. + +.SH Example + + A minimum bidirectional iterator. + + #include + #include + + struct SimpleBidiIterator + { + using difference_type = std::ptrdiff_t; + using value_type = int; + + int operator*() const; + + SimpleBidiIterator& operator++(); + + SimpleBidiIterator operator++(int) + { + auto tmp = *this; + ++*this; + return tmp; + } + + SimpleBidiIterator& operator--(); + + SimpleBidiIterator operator--(int) + { + auto tmp = *this; + --*this; + return tmp; + } + + bool operator==(const SimpleBidiIterator&) const; + }; + + static_assert(std::bidirectional_iterator); + +.SH See also + + forward_iterator specifies that an input_iterator is a forward iterator, + (C++20) supporting equality comparison and multi-pass + (concept) + specifies that a bidirectional_iterator is a random-access + random_access_iterator iterator, supporting advancement in constant time and + (C++20) subscripting + (concept) diff --git a/man/std::binary_function.3 b/man/std::binary_function.3 index 79fccf22c..b1b17724b 100644 --- a/man/std::binary_function.3 +++ b/man/std::binary_function.3 @@ -1,27 +1,32 @@ -.TH std::binary_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binary_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binary_function \- std::binary_function + .SH Synopsis Defined in header template< - class Arg1, - class Arg2, \fB(deprecated)\fP + class Arg1, (deprecated in C++11) + class Arg2, (removed in C++17) class Result > struct binary_function; - binary_function is a base class for creating function objects with two arguments. + std::binary_function is a base class for creating function objects with two + arguments. - binary_function does not define operator(); it is expected that derived classes will - define this. binary_function provides only three types - first_argument_type, - second_argument_type and result_type - defined by the template parameters. + std::binary_function does not define operator(); it is expected that derived classes + will define this. std::binary_function provides only three types - + first_argument_type, second_argument_type and result_type - defined by the template + parameters. Some standard library function object adaptors, such as std::not2, require the function objects they adapt to have certain types defined; std::not2 requires the function object being adapted to have two types named first_argument_type and second_argument_type. Deriving function objects that take two arguments from - binary_function is an easy way to make them compatible with those adaptors. + std::binary_function is an easy way to make them compatible with those adaptors. - binary_function is deprecated in C++11. + std::binary_function is deprecated in C++11 and removed in C++17. .SH Member types @@ -32,55 +37,54 @@ .SH Example - + // Run this code #include #include #include #include - + struct same : std::binary_function { bool operator()(int a, int b) const { return a == b; } }; - + int main() { - std::vector v1{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; - std::vector v2{10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 }; + std::vector v1{'A', 'B', 'C', 'D', 'E'}; + std::vector v2{'E', 'D', 'C', 'B', 'A'}; std::vector v3(v1.size()); - + std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), std::not2(same())); - + std::cout << std::boolalpha; for (std::size_t i = 0; i < v1.size(); ++i) - std::cout << v1[i] << ' ' << v2[i] << ' ' << v3[i] << '\\n'; + std::cout << v1[i] << " != " << v2[i] << " : " << v3[i] << '\\n'; } .SH Output: - 0 10 true - 1 9 true - 2 8 true - 3 7 true - 4 6 true - 5 5 false - 6 4 true - 7 3 true - 8 2 true - 9 1 true + A != E : true + B != D : true + C != C : false + D != B : true + E != A : true .SH See also - function wraps callable object of any type with specified function - \fI(C++11)\fP call signature - \fI(class template)\fP + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function + (C++23) call signature + \fI(class template)\fP ptr_fun creates an adaptor-compatible function object wrapper - \fB(deprecated)\fP from a pointer to function - \fI(function template)\fP + (deprecated in C++11) from a pointer to function + (removed in C++17) \fI(function template)\fP pointer_to_binary_function adaptor-compatible wrapper for a pointer to binary - \fB(deprecated)\fP function - \fI(class template)\fP + (deprecated in C++11) function + (removed in C++17) \fI(class template)\fP unary_function adaptor-compatible unary function base class - \fB(deprecated)\fP \fI(class template)\fP + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) diff --git a/man/std::binary_negate.3 b/man/std::binary_negate.3 index 3085ab2ca..41a082d88 100644 --- a/man/std::binary_negate.3 +++ b/man/std::binary_negate.3 @@ -1,20 +1,24 @@ -.TH std::binary_negate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binary_negate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binary_negate \- std::binary_negate + .SH Synopsis Defined in header template< class Predicate > - struct binary_negate : - public std::binary_function< + struct binary_negate + : public std::binary_function< Predicate::first_argument_type, \fI(until C++11)\fP Predicate::second_argument_type, bool >; template< class Predicate > \fI(since C++11)\fP - struct binary_negate; + struct binary_negate; (deprecated in C++17) + (removed in C++20) - binary_negate is a wrapper function object returning the complement of the binary - predicate it holds. + std::binary_negate is a wrapper function object returning the complement of the + binary predicate it holds. The binary predicate type must define two member types, first_argument_type and second_argument_type, that are convertible to the predicate's parameter types. The @@ -26,7 +30,7 @@ a call to std::not2 have these types defined, as are function objects derived from the deprecated std::binary_function. - binary_negate objects are easily constructed with helper function std::not2. + std::binary_negate objects are easily constructed with helper function std::not2. .SH Member types @@ -43,18 +47,18 @@ operator() predicate \fI(public member function)\fP - std::binary_negate::binary_negate +std::binary_negate::binary_negate explicit binary_negate( Predicate const& pred ); \fI(until C++14)\fP - explicit constexpr binary_negate( Predicate const& pred ); \fI(since C++14)\fP + constexpr explicit binary_negate( Predicate const& pred ); \fI(since C++14)\fP - Constructs a binary_negate function object with the stored predicate pred. + Constructs a std::binary_negate function object with the stored predicate pred. .SH Parameters pred - predicate function object - std::binary_negate::operator() +std::binary_negate::operator() bool operator()( first_argument_type const& x, \fI(until C++14)\fP second_argument_type const& y ) const; @@ -74,70 +78,71 @@ .SH Example - + // Run this code #include + #include #include #include #include - + struct same : std::binary_function { bool operator()(int a, int b) const { return a == b; } }; - + int main() { std::vector v1; - std::vector v2; - for (int i = 0; i < 10; ++i) v1.push_back(i); - for (int i = 0; i < 10; ++i) v2.push_back(10 - i); - + for (int i = 0; i < 7; ++i) + v1.push_back(i); + + std::vector v2(v1.size()); + std::reverse_copy(v1.begin(), v1.end(), v2.begin()); + std::vector v3(v1.size()); - + std::binary_negate not_same((same())); - + + // C++11 solution: + // std::function not_same = + // [](int x, int y) -> bool { return !same()(x, y); }; + std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), not_same); - - /* C++11 solution: - // Use std::function - std::function not_same = - [](int x, int y)->bool{ return !same()(x, y); }; - - std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), not_same); - */ - + std::cout.setf(std::ios_base::boolalpha); - for (int i = 0; i < 10; ++i) - std::cout << v1[i] << ' ' << v2[i] << ' ' << v3[i] << '\\n'; + for (std::size_t i = 0; i != v1.size(); ++i) + std::cout << v1[i] << " != " << v2[i] << " : " << v3[i] << '\\n'; } .SH Output: - 0 10 true - 1 9 true - 2 8 true - 3 7 true - 4 6 true - 5 5 false - 6 4 true - 7 3 true - 8 2 true - 9 1 true + 0 != 6 : true + 1 != 5 : true + 2 != 4 : true + 3 != 3 : false + 4 != 2 : true + 5 != 1 : true + 6 != 0 : true .SH See also - binary_function adaptor-compatible binary function base class - \fB(deprecated)\fP \fI(class template)\fP - function wraps callable object of any type with specified function call - \fI(C++11)\fP signature - \fI(class template)\fP - not2 constructs custom std::binary_negate object - \fI(function template)\fP - ptr_fun creates an adaptor-compatible function object wrapper from a pointer - \fB(deprecated)\fP to function - \fI(function template)\fP - wrapper function object returning the complement of the unary - unary_negate predicate it holds - \fI(class template)\fP + binary_function adaptor-compatible binary function base class + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + not2 constructs custom std::binary_negate object + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) + ptr_fun creates an adaptor-compatible function object wrapper from a + (deprecated in C++11) pointer to function + (removed in C++17) \fI(function template)\fP + unary_negate wrapper function object returning the complement of the unary + (deprecated in C++17) predicate it holds + (removed in C++20) \fI(class template)\fP diff --git a/man/std::binary_search.3 b/man/std::binary_search.3 index 6d69c1b7f..f216d3e76 100644 --- a/man/std::binary_search.3 +++ b/man/std::binary_search.3 @@ -1,106 +1,184 @@ -.TH std::binary_search 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binary_search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binary_search \- std::binary_search + .SH Synopsis Defined in header - template< class ForwardIt, class T > \fB(1)\fP - bool binary_search( ForwardIt first, ForwardIt last, const T& value ); - template< class ForwardIt, class T, class Compare > - bool binary_search( ForwardIt first, ForwardIt last, const T& value, Compare \fB(2)\fP - comp ); + template< class ForwardIt, class T > + (constexpr since + bool binary_search( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value ); + template< class ForwardIt, class T = + typename std::iterator_traits + + + ::value_type > (since C++26) + constexpr bool binary_search( ForwardIt + first, ForwardIt last, + + const T& + value ); + template< class ForwardIt, class T, class + Compare > \fB(1)\fP + (constexpr since + bool binary_search( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value, + Compare comp ); + template< class ForwardIt, class T = + typename std::iterator_traits \fB(2)\fP + + + ::value_type, + class Compare > (since C++26) + constexpr bool binary_search( ForwardIt + first, ForwardIt last, - Checks if an element equivalent to value appears within the range [first, last). + const T& + value, Compare comp ); - For std::binary_search to succeed, the range [first, last) must be at least - partially ordered, i.e. it must satisfy all of the following requirements: + Checks if an element equivalent to value appears within the partitioned range + [first, last). - * partitioned with respect to element < value or comp(element, value) - * partitioned with respect to !(value < element) or !comp(value, element) - * for all elements, if element < value or comp(element, value) is true then - !(value < element) or !comp(value, element) is also true + 1) The equivalence is checked using operator<: - A fully-sorted range meets these criteria, as does a range resulting from a call to - std::partition. + If !bool(*iter < value) && !bool(value < *iter) is true for some + iterator iter in [first, last), returns true. Otherwise returns false. - The first version uses operator< to compare the elements, the second version uses - the given comparison function comp. + If any of the following conditions is satisfied, the behavior is + undefined: \fI(until C++20)\fP + + * For any element elem of [first, last), bool(elem < value) does not + imply !bool(value < elem). + * The elements elem of [first, last) are not partitioned with + respect to expressions bool(elem < value) and !bool(value < elem). + Equivalent to std::binary_search(first, last, value, std::less{}). \fI(since C++20)\fP + + 2) The equivalence is checked using comp: + If !bool(comp(*iter, value)) && !bool(comp(value, *iter)) is true for some iterator + iter in [first, last), returns true. Otherwise returns false. + If any of the following conditions is satisfied, the behavior is undefined: + * For any element elem of [first, last), bool(comp(elem, value)) does not imply + !bool(comp(value, elem)). + * The elements elem of [first, last) are not partitioned with respect to + expressions bool(comp(elem, value)) and !bool(comp(value, elem)). .SH Parameters - first, last - the range of elements to examine + first, last - the partitioned range of elements to examine value - value to compare the elements to - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + binary predicate which returns true if the first argument is ordered + before the second. - The signature of the comparison function should be equivalent to the + The signature of the predicate function should be equivalent to the following: - bool cmp(const Type1 &a, const Type2 &b); - - The signature does not need to have const &, but the function object - comp - must not modify the objects passed to it. - The type Type1 must be such that an object of type T can be implicitly - converted to Type1. The type Type2 must be such that an object of type - ForwardIt can be dereferenced and then implicitly converted to Type2. - - - This section is incomplete - Reason: Update type requirements? The types Type1 and Type2 must be - such that an object of type T can be implicitly converted to either - type, and such that an object of type ForwardIt can be dereferenced - and then implicitly converted to either type. Generally Type1 and - Type2 will be the same type, although this is not required. + bool pred(const Type1 &a, const Type2 &b); + + comp - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type T can be + implicitly converted to both Type1 and Type2, and an object of type + ForwardIt can be dereferenced and then implicitly converted to both + Type1 and Type2. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of BinaryPredicate. It is not required to satisfy + Compare. .SH Return value - true if an element equal to value is found, false otherwise. + true if an element equivalent to value is found, false otherwise. .SH Complexity - The number of comparisons performed is logarithmic in the distance between first and - last + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) At most \\(\\scriptsize \\log_{2}(N)+O(1)\\)log + 2(N)+O(1) comparisons with value using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize \\log_{2}(N)+O(1)\\)log + 2(N)+O(1) applications of the comparator comp. + + However, if ForwardIt is not a LegacyRandomAccessIterator, the number of iterator + increments is linear in \\(\\scriptsize N\\)N. + +.SH Notes + + Although std::binary_search only requires [first, last) to be partitioned, this + algorithm is usually used in the case where [first, last) is sorted, so that the + binary search is valid for any value. + + std::binary_search only checks whether an equivalent element exists. To obtain an + iterator to that element (if exists), std::lower_bound should be used instead. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) .SH Possible implementation -.SH First version - template - bool binary_search(ForwardIt first, ForwardIt last, const T& value) - { - first = std::lower_bound(first, last, value); - return (!(first == last) && !(value < *first)); - } -.SH Second version - template - bool binary_search(ForwardIt first, ForwardIt last, const T& value, Compare comp) - { - first = std::lower_bound(first, last, value, comp); - return (!(first == last) && !(comp(value, *first))); - } + See also the implementations in libstdc++ and libc++. + + binary_search \fB(1)\fP + template::value_type> + bool binary_search(ForwardIt first, ForwardIt last, const T& value) + { + return std::binary_search(first, last, value, std::less{}); + } + binary_search \fB(2)\fP + template::value_type, + class Compare> + bool binary_search(ForwardIt first, ForwardIt last, const T& value, Compare comp) + { + first = std::lower_bound(first, last, value, comp); + return (!(first == last) and !(comp(value, *first))); + } .SH Example - + // Run this code - #include #include + #include + #include + #include #include - + int main() { - std::vector haystack {1, 3, 4, 5, 9}; - std::vector needles {1, 2, 3}; - - for (auto needle : needles) { + const auto haystack = {1, 3, 4, 5, 9}; + + for (const auto needle : {1, 2, 3}) + { std::cout << "Searching for " << needle << '\\n'; - if (std::binary_search(haystack.begin(), haystack.end(), needle)) { + if (std::binary_search(haystack.begin(), haystack.end(), needle)) std::cout << "Found " << needle << '\\n'; - } else { - std::cout << "no dice!\\n"; - } + else + std::cout << "No dice!\\n"; } + + using CD = std::complex; + std::vector nums{{1, 1}, {2, 3}, {4, 2}, {4, 3}}; + auto cmpz = [](CD x, CD y){ return abs(x) < abs(y); }; + #ifdef __cpp_lib_algorithm_default_value_type + assert(std::binary_search(nums.cbegin(), nums.cend(), {4, 2}, cmpz)); + #else + assert(std::binary_search(nums.cbegin(), nums.cend(), CD{4, 2}, cmpz)); + #endif } .SH Output: @@ -112,11 +190,29 @@ Searching for 3 Found 3 -.SH See also + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - equal_range returns range of elements matching a specific key - \fI(function template)\fP + DR Applied to Behavior as published Correct behavior + Compare was required to satisfy only a partitioning is required; + LWG 270 C++98 Compare and T was required heterogeneous comparisons + to be LessThanComparable (strict permitted + weak ordering required) + at most \\(\\scriptsize corrected to \\(\\scriptsize + LWG 787 C++98 \\log_{2}(N)+2\\)log \\log_{2}(N)+O(1)\\)log + 2(N)+2 comparisons were allowed 2(N)+O(1) -.SH Category: +.SH See also - * Todo with reason + equal_range returns range of elements matching a specific key + \fI(function template)\fP + returns an iterator to the first element not less than the + lower_bound given value + \fI(function template)\fP + returns an iterator to the first element greater than a + upper_bound certain value + \fI(function template)\fP + ranges::binary_search determines if an element exists in a partially-ordered range + (C++20) (niebloid) diff --git a/man/std::bind.3 b/man/std::bind.3 index fdee61db1..3f6e3e6e9 100644 --- a/man/std::bind.3 +++ b/man/std::bind.3 @@ -1,17 +1,29 @@ -.TH std::bind 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bind \- std::bind + .SH Synopsis Defined in header - template< class F, class... Args > \fB(1)\fP \fI(since C++11)\fP - /*unspecified*/ bind( F&& f, Args&&... args ); - template< class R, class F, class... Args > \fB(2)\fP \fI(since C++11)\fP - /*unspecified*/ bind( F&& f, Args&&... args ); + template< class F, class... Args > \fI(since C++11)\fP + /* unspecified */ bind( F&& f, Args&&... args ); \fI(until C++20)\fP + template< class F, class... Args > + constexpr /* unspecified */ bind( F&& f, \fI(since C++20)\fP + Args&&... args ); \fB(1)\fP + template< class R, class F, class... Args > \fI(since C++11)\fP + /* unspecified */ bind( F&& f, Args&&... args ); \fI(until C++20)\fP + template< class R, class F, class... Args > \fB(2)\fP + constexpr /* unspecified */ bind( F&& f, \fI(since C++20)\fP + Args&&... args ); - The function template bind generates a forwarding call wrapper for f. Calling this - wrapper is equivalent to invoking f with some of its arguments bound to args. + The function template std::bind generates a forwarding call wrapper for f. Calling + this wrapper is equivalent to invoking f with some of its arguments bound to args. - Internally, the wrapper holds a member object of type std::decay::type - constructed from std::forward(f), and one object per each of args..., of type - std::decay::type, similarly constructed from std::forward(arg_i). + If std::is_constructible::type, F>::value is false, or + std::is_constructible::type, Arg_i>::value is false for any type + Arg_i in Args, the program is ill-formed. + + If std::decay::type or any type in Args is not MoveConstructible or + Destructible, the behavior is undefined. .SH Parameters @@ -23,44 +35,98 @@ .SH Return value - A function object of unspecified type T, for which std::is_bind_expression::value - == true, and which can be stored in std::function. The object is movable if f and - all args are movable, and is copyable otherwise. The type defines the following - members: + A function object g of unspecified type T, for which + std::is_bind_expression::value is true. It has the following members: - std::bind return type +std::bind return type -.SH Member type result_type +.SH Member objects - 1) If F is a pointer to function or a pointer to member function, result_type is the - return type of F. If F is a class type with nested typedef result_type, then - result_type is F::result_type. Otherwise no result_type is defined. + The return type of std::bind holds a member object of type std::decay::type + constructed from std::forward(f), and one object per each of args..., of type + std::decay::type, similarly constructed from std::forward(arg_i). - 2) result_type is exactly R. + Constructors + + The return type of std::bind is CopyConstructible if all of its member objects + (specified above) are CopyConstructible, and is MoveConstructible otherwise. The + type defines the following members: + +.SH Member type result_type + + 1) (deprecated in C++17) If F is a pointer to function or a pointer to + member function, result_type is the return type of F. If F is a class \fI(until C++20)\fP + type with nested typedef result_type, then result_type is + F::result_type. Otherwise no result_type is defined. + 2) (deprecated in C++17) result_type is exactly R. .SH Member function operator() - Given an object g obtained from an earlier call to bind, when it is invoked in a - function call expression g(u1, u2, ... uM), an invocation of the stored object of - type std::decay::type takes place, with arguments defined as follows: - - * If the argument is of type std::reference_wrapper (e.g. std::ref or - std::cref) was used in the initial call to bind, then the reference T& stored in - the bound argument is passed to the invocable object. - * If std::is_bind_expression::value == true (i.e. another bind subexpression - was used as an argument in the initial call to bind), then that bind - subexpression is invoked immediately and its result is passed to the invocable - object. If the bind subexpression has any placeholder arguments, they are picked - from u1, u2, .... - * If std::is_placeholder::value != 0 (i.e., std::placeholders::_1, _2, _3, ... - was used as the argument to the initial call to bind), then the argument - indicated by the placeholder (u1 for _1, u2 for _2, etc) is passed to the - invocable object as std::forward(uj). - * Otherwise, the stored argument is passed to the invocable object as-is. + When g is invoked in a function call expression g(u1, u2, ... uM), an invocation of + the stored object takes place, as if by + + 1) INVOKE(fd, std::forward(v1), std::forward(v2), ..., + std::forward(vN)), or + 2) INVOKE(fd, std::forward(v1), std::forward(v2), ..., + std::forward(vN)), + + where fd is a value of type std::decay::type, the values and types of the bound + arguments v1, v2, ..., vN are determined as specified below. If some of the arguments that are supplied in the call to g() are not matched by any placeholders stored in g, the unused arguments are evaluated and discarded. + An invocation of operator() is non-throwing + or is a constant subexpression + \fI(since C++20)\fP if and only if so is the underlying INVOKE operation. operator() + participates in overload resolution only if the INVOKE operation is well-formed when + treated as an unevaluated operand. + + If g is volatile-qualified, the program is ill-formed. + + If INVOKE(fd, w1, w2, ..., wN) can never be a valid expression for any possible + values w1, w2, ..., wN, the behavior is undefined. + + Bound arguments + + For each stored argument arg_i, the corresponding bound argument v_i in the INVOKE + or INVOKE operation is determined as follows: + + Case 1: reference wrappers + + If arg_i is of type std::reference_wrapper (for example, std::ref or std::cref + was used in the initial call to std::bind), then v_i is arg_i.get() and its type V_i + is T&: the stored argument is passed by reference into the invoked function object. + + Case 2: bind expressions + + If arg_i is of type T for which std::is_bind_expression::value is true (for + example, another std::bind expression was passed directly into the initial call to + std::bind), then std::bind performs function composition: instead of passing the + function object that the bind subexpression would return, the subexpression is + invoked eagerly, and its return value is passed to the outer invokable object. If + the bind subexpression has any placeholder arguments, they are shared with the outer + bind (picked out of u1, u2, ...). Specifically, v_i is + arg_i(std::forward(uj)...) and its type V_i is + std::result_of::type&& + \fI(until C++17)\fP + std::invoke_result_t&& + \fI(since C++17)\fP (cv-qualification is the same as that of g). + + Case 3: placeholders + + If arg_i is of type T, for which std::is_placeholder::value is not 0 (meaning, a + placeholder such as std::placeholders::_1, _2, _3, ... was used as the argument to + the initial call to std::bind), then the argument indicated by the placeholder (u1 + for _1, u2 for _2, etc) is passed to the invokable object: v_i is + std::forward(uj) and its type V_i is Uj&&. + + Case 4: ordinary arguments + + Otherwise, arg_i is passed to the invokable object as lvalue argument: v_i is simply + arg_i and its type V_i is T cv &, where cv is the same cv-qualification as that of + g. + .SH Exceptions Only throws if construction of std::decay::type from std::forward(f) throws, @@ -70,6 +136,11 @@ .SH Notes + As described in Callable, when invoking a pointer to non-static member function or + pointer to non-static data member, the first argument has to be a reference or + pointer (including, possibly, smart pointer such as std::shared_ptr and + std::unique_ptr) to an object whose member will be accessed. + The arguments to bind are copied or moved, and are never passed by reference unless wrapped in std::ref or std::cref. @@ -79,76 +150,124 @@ .SH Example - + // Run this code - #include - #include #include - + #include + #include + #include + void f(int n1, int n2, int n3, const int& n4, int n5) { std::cout << n1 << ' ' << n2 << ' ' << n3 << ' ' << n4 << ' ' << n5 << '\\n'; } - + int g(int n1) { return n1; } - - struct Foo { + + struct Foo + { void print_sum(int n1, int n2) { - std::cout << n1+n2 << '\\n'; + std::cout << n1 + n2 << '\\n'; } + int data = 10; }; - + int main() { using namespace std::placeholders; // for _1, _2, _3... - - // demonstrates argument reordering and pass-by-reference + + std::cout << "1) argument reordering and pass-by-reference: "; int n = 7; // (_1 and _2 are from std::placeholders, and represent future // arguments that will be passed to f1) - auto f1 = std::bind(f, _2, _1, 42, std::cref(n), n); + auto f1 = std::bind(f, _2, 42, _1, std::cref(n), n); n = 10; f1(1, 2, 1001); // 1 is bound by _1, 2 is bound by _2, 1001 is unused - - // nested bind subexpressions share the placeholders + // makes a call to f(2, 42, 1, n, 7) + + std::cout << "2) achieving the same effect using a lambda: "; + n = 7; + auto lambda = [&ncref = n, n](auto a, auto b, auto /*unused*/) + { + f(b, 42, a, ncref, n); + }; + n = 10; + lambda(1, 2, 1001); // same as a call to f1(1, 2, 1001) + + std::cout << "3) nested bind subexpressions share the placeholders: "; auto f2 = std::bind(f, _3, std::bind(g, _3), _3, 4, 5); - f2(10, 11, 12); - - // common use case: binding a RNG with a distribution + f2(10, 11, 12); // makes a call to f(12, g(12), 12, 4, 5); + + std::cout << "4) bind a RNG with a distribution: "; std::default_random_engine e; std::uniform_int_distribution<> d(0, 10); - std::function rnd = std::bind(d, e); - for(int n=0; n<10; ++n) + auto rnd = std::bind(d, e); // a copy of e is stored in rnd + for (int n = 0; n < 10; ++n) std::cout << rnd() << ' '; std::cout << '\\n'; - - // bind to a member function + + std::cout << "5) bind to a pointer to member function: "; Foo foo; auto f3 = std::bind(&Foo::print_sum, &foo, 95, _1); f3(5); - - // bind to member data - auto f4 = std::bind(&Foo::data, _1); - std::cout << f4(foo) << '\\n'; + + std::cout << "6) bind to a mem_fn that is a pointer to member function: "; + auto ptr_to_print_sum = std::mem_fn(&Foo::print_sum); + auto f4 = std::bind(ptr_to_print_sum, &foo, 95, _1); + f4(5); + + std::cout << "7) bind to a pointer to data member: "; + auto f5 = std::bind(&Foo::data, _1); + std::cout << f5(foo) << '\\n'; + + std::cout << "8) bind to a mem_fn that is a pointer to data member: "; + auto ptr_to_data = std::mem_fn(&Foo::data); + auto f6 = std::bind(ptr_to_data, _1); + std::cout << f6(foo) << '\\n'; + + std::cout << "9) use smart pointers to call members of the referenced objects: "; + std::cout << f6(std::make_shared(foo)) << ' ' + << f6(std::make_unique(foo)) << '\\n'; } .SH Output: - 2 1 42 10 7 - 12 12 12 4 5 - 1 5 0 2 0 8 2 2 10 8 - 100 - 10 + 1) argument reordering and pass-by-reference: 2 42 1 10 7 + 2) achieving the same effect using a lambda: 2 42 1 10 7 + 3) nested bind subexpressions share the placeholders: 12 12 12 4 5 + 4) bind a RNG with a distribution: 0 1 8 5 5 2 0 7 7 10 + 5) bind to a pointer to member function: 100 + 6) bind to a mem_fn that is a pointer to member function: 100 + 7) bind to a pointer to data member: 10 + 8) bind to a mem_fn that is a pointer to data member: 10 + 9) use smart pointers to call members of the referenced objects: 10 10 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the bounded arguments + were not forwarded to fd 1. forwarded + LWG 2021 C++11 2. in case 2, the type of V_i 2. changed to + was std::result_of::type&& + cv (Uj...)>::type .SH See also + bind_front bind a variable number of arguments, in order, to a function + bind_back object + (C++20) \fI(function template)\fP + (C++23) _1, _2, _3, _4, ... placeholders for the unbound arguments in a std::bind expression - \fI(C++11)\fP (constant) + \fI(C++11)\fP (constant) mem_fn creates a function object out of a pointer to a member - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::bind1st,std::bind2nd.3 b/man/std::bind1st,std::bind2nd.3 index 90e125a0d..257912f66 100644 --- a/man/std::bind1st,std::bind2nd.3 +++ b/man/std::bind1st,std::bind2nd.3 @@ -1,9 +1,13 @@ -.TH std::bind1st,std::bind2nd 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bind1st,std::bind2nd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bind1st,std::bind2nd \- std::bind1st,std::bind2nd + .SH Synopsis - template< class F, class T > \fB(1)\fP \fB(deprecated)\fP - std::binder1st bind1st( const F& f, const T& x ); - template< class F, class T > \fB(2)\fP \fB(deprecated)\fP - std::binder2nd bind2nd( const F& f, const T& x ); + Defined in header + template< class F, class T > \fB(1)\fP (deprecated in C++11) + std::binder1st bind1st( const F& f, const T& x ); (removed in C++17) + template< class F, class T > \fB(2)\fP (deprecated in C++11) + std::binder2nd bind2nd( const F& f, const T& x ); (removed in C++17) Binds a given argument x to a first or second parameter of the given binary function object f. That is, stores x within the resulting wrapper, which, if called, passes x @@ -11,7 +15,6 @@ 1) Binds the first argument of f to x. Effectively calls std::binder1st(f, typename F::first_argument_type(x)). - 2) Binds the second argument of f to x. Effectively calls std::binder2nd(f, typename F::second_argument_type(x)). @@ -26,11 +29,52 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + std::vector a = {0, 30, 45, 60, 90, 180}; + std::vector r(a.size()); + const double pi = std::acos(-1); // since C++20 use std::numbers::pi + + std::transform(a.begin(), a.end(), r.begin(), + std::bind1st(std::multiplies(), pi / 180.0)); + // an equivalent lambda is: [pi](double a) { return a * pi / 180.0; }); + + for (std::size_t n = 0; n < a.size(); ++n) + std::cout << std::setw(3) << a[n] << "° = " << std::fixed << r[n] + << " rad\\n" << std::defaultfloat; + } + +.SH Output: + + 0° = 0.000000 rad + 30° = 0.523599 rad + 45° = 0.785398 rad + 60° = 1.047198 rad + 90° = 1.570796 rad + 180° = 3.141593 rad .SH See also - binder1st - binder2nd function object holding a binary function and one of its arguments - \fB(deprecated)\fP \fI(class template)\fP - \fB(deprecated)\fP + binder1st function object holding a binary function and one + binder2nd of its arguments + (deprecated in C++11)(removed in \fI(class template)\fP + C++17) + bind_front bind a variable number of arguments, in order, to a + bind_back function object + (C++20) \fI(function template)\fP + (C++23) diff --git a/man/std::bind_front,std::bind_back.3 b/man/std::bind_front,std::bind_back.3 new file mode 100644 index 000000000..4b5e596f1 --- /dev/null +++ b/man/std::bind_front,std::bind_back.3 @@ -0,0 +1,303 @@ +.TH std::bind_front,std::bind_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bind_front,std::bind_back \- std::bind_front,std::bind_back + +.SH Synopsis + Defined in header + template< class F, class... Args > \fB(1)\fP \fI(since C++20)\fP + constexpr /* unspecified */ bind_front( F&& f, Args&&... args ); + template< auto ConstFn, class... Args > \fB(2)\fP (since C++26) + constexpr /* unspecified */ bind_front( Args&&... args ); + template< class F, class... Args > \fB(3)\fP (since C++23) + constexpr /* unspecified */ bind_back( F&& f, Args&&... args ); + template< auto ConstFn, class... Args > \fB(4)\fP (since C++26) + constexpr /* unspecified */ bind_back( Args&&... args ); + + Function templates std::bind_front and std::bind_back generate a perfect forwarding + call wrapper which allows to invoke the callable target with its (1,2) first or + (3,4) last sizeof...(Args) parameters bound to args. + + 1,3) The call wrapper holds a copy of the target callable object f. + 2,4) The call wrapper does not hold a callable target (it is statically determined). + 1) std::bind_front(f, bound_args...)(call_args...) is expression-equivalent to + std::invoke(f, bound_args..., call_args...). + 2) std::bind_front(bound_args...)(call_args...) is expression-equivalent to + std::invoke(ConstFn, bound_args..., call_args...). + 3) std::bind_back(f, bound_args...)(call_args...) is expression-equivalent to + std::invoke(f, call_args..., bound_args...). + 4) std::bind_back(bound_args...)(call_args...) is expression-equivalent to + std::invoke(ConstFn, call_args..., bound_args...). + + The following conditions must be true, otherwise the program is ill-formed: + + * (1,3) std::is_constructible_v, F>, + * (1,3) std::is_move_constructible_v>, + * (2,4) If decltype(ConstFn) is a pointer or a pointer-to-member then ConstFn is + not a null pointer, + * (std::is_constructible_v, Args> && ...), + * (std::is_move_constructible_v> && ...). + +.SH Parameters + + Callable object \fI\fI(function\fP object, pointer to function, reference to function,\fP + f - pointer to member function, or pointer to data member) that will be bound to + some arguments + args - list of the arguments to bind to the (1,2) first or (3,4) last + sizeof...(Args) parameters of the callable target +.SH Type requirements + - + std::decay_t must meet the requirements of MoveConstructible. + - + std::decay_t... must meet the requirements of MoveConstructible. + - + decltype(ConstFn) must meet the requirements of Callable. + +.SH Return value + + A function object (the call wrapper) of type T that is unspecified, except that the + types of objects returned by two calls to std::bind_front or std::bind_back with the + same arguments are the same. + + Let bind-partial be either std::bind_front or std::bind_back. + + The returned object has the following properties: + +bind-partial return type + +.SH Member objects + + The returned object behaves as if it holds: + + 1,3) A member object fd of type std::decay_t direct-non-list-initialized from + std::forward(f), and + 1-4) An std::tuple object tup constructed with + std::tuple...>(std::forward(args)...), except that the + returned object's assignment behavior is unspecified and the names are for + exposition only. + + Constructors + + The return type of bind-partial behaves as if its copy/move constructors perform a + memberwise copy/move. It is CopyConstructible if all of its member objects + (specified above) are CopyConstructible, and is MoveConstructible otherwise. + +.SH Member function operator() + + Given an object G obtained from an earlier call to (1,3) bind-partial(f, args...) or + (2,4) bind-partial(args...), when a glvalue g designating G is invoked in a + function call expression g(call_args...), an invocation of the stored object takes + place, as if by: + + 1) std::invoke(g.fd, std::get(g.tup)..., call_args...), when bind-partial is + std::bind_front, + 2) std::invoke(ConstFn, std::get(g.tup)..., call_args...), when bind-partial is + std::bind_front, + 3) std::invoke(g.fd, call_args..., std::get(g.tup)...), when bind-partial is + std::bind_back, + 4) std::invoke(ConstFn, call_args..., std::get(g.tup)...), when bind-partial is + std::bind_back, + + where + + * Ns is an integer pack 0, 1, ..., (sizeof...(Args) - 1), + * g is an lvalue in the std::invoke expression if it is an lvalue in the call + expression, and is an rvalue otherwise. Thus std::move(g)(call_args...) can move + the bound arguments into the call, where g(call_args...) would copy. + + The program is ill-formed if g has volatile-qualified type. + + The member operator() is noexcept if the std::invoke expression it calls is noexcept + (in other words, it preserves the exception specification of the underlying call + operator). + +.SH Exceptions + + 1,3) Throw any exception thrown by calling the constructor of the stored function + object. + 1-4) Throw any exception thrown by calling the constructor of any of the bound + arguments. + +.SH Notes + + These function templates are intended to replace std::bind. Unlike std::bind, they + do not support arbitrary argument rearrangement and have no special treatment for + nested bind-expressions or std::reference_wrappers. On the other hand, they pay + attention to the value category of the call wrapper object and propagate exception + specification of the underlying call operator. + + As described in std::invoke, when invoking a pointer to non-static member function + or pointer to non-static data member, the first argument has to be a reference or + pointer (including, possibly, smart pointer such as std::shared_ptr and + std::unique_ptr) to an object whose member will be accessed. + + The arguments to std::bind_front or std::bind_back are copied or moved, and are + never passed by reference unless wrapped in std::ref or std::cref. + + Typically, binding arguments to a function or a member function using \fB(1)\fP + std::bind_front and \fB(3)\fP std::bind_back requires storing a function pointer along + with the arguments, even though the language knows precisely which function to call + without a need to dereference the pointer. To guarantee "zero cost" in those cases, + C++26 introduces the versions (2,4) (that accept the callable object as an argument + for non-type template parameter). + + Feature-test macro Value Std Feature + 201907L (C++20) std::bind_front, \fB(1)\fP + __cpp_lib_bind_front 202306L (C++26) Allow passing callable objects as non-type + template arguments to std::bind_front, \fB(2)\fP + 202202L (C++23) std::bind_back, \fB(3)\fP + __cpp_lib_bind_back 202306L (C++26) Allow passing callable objects as non-type + template arguments to std::bind_back, \fB(4)\fP + +.SH Possible implementation + + \fB(2)\fP bind_front + namespace detail + { + template + struct copy_const + : std::conditional, U const, U> {}; + + template, U>::type> + struct copy_value_category + : std::conditional, X&, X&&> {}; + + template + struct type_forward_like + : copy_value_category> {}; + + template + using type_forward_like_t = typename type_forward_like::type; + } + + template + constexpr auto bind_front(Args&&... args) + { + using F = decltype(ConstFn); + + if constexpr (std::is_pointer_v or std::is_member_pointer_v) + static_assert(ConstFn != nullptr); + + return + [... bound_args(std::forward(args))] + ( + this Self&&, T&&... call_args + ) + noexcept + ( + std::is_nothrow_invocable_v>..., T...> + ) + -> std::invoke_result_t>..., T...> + { + return std::invoke(ConstFn, std::forward_like(bound_args)..., + std::forward(call_args)...); + }; + } + \fB(4)\fP bind_back + namespace detail { /* is the same as above */ } + + template + constexpr auto bind_back(Args&&... args) + { + using F = decltype(ConstFn); + + if constexpr (std::is_pointer_v or std::is_member_pointer_v) + static_assert(ConstFn != nullptr); + + return + [... bound_args(std::forward(args))] + ( + this Self&&, T&&... call_args + ) + noexcept + ( + std::is_nothrow_invocable_v>...> + ) + -> std::invoke_result_t>...> + { + return std::invoke(ConstFn, std::forward(call_args)..., + std::forward_like(bound_args)...); + }; + } + +.SH Example + + +// Run this code + + #include + #include + + int minus(int a, int b) + { + return a - b; + } + + struct S + { + int val; + int minus(int arg) const noexcept { return val - arg; } + }; + + int main() + { + auto fifty_minus = std::bind_front(minus, 50); + assert(fifty_minus(3) == 47); // equivalent to: minus(50, 3) == 47 + + auto member_minus = std::bind_front(&S::minus, S{50}); + assert(member_minus(3) == 47); //: S tmp{50}; tmp.minus(3) == 47 + + // Noexcept-specification is preserved: + static_assert(!noexcept(fifty_minus(3))); + static_assert(noexcept(member_minus(3))); + + // Binding of a lambda: + auto plus = [](int a, int b) { return a + b; }; + auto forty_plus = std::bind_front(plus, 40); + assert(forty_plus(7) == 47); // equivalent to: plus(40, 7) == 47 + + #if __cpp_lib_bind_front >= 202306L + auto fifty_minus_cpp26 = std::bind_front(50); + assert(fifty_minus_cpp26(3) == 47); + + auto member_minus_cpp26 = std::bind_front<&S::minus>(S{50}); + assert(member_minus_cpp26(3) == 47); + + auto forty_plus_cpp26 = std::bind_front(40); + assert(forty_plus(7) == 47); + #endif + + #if __cpp_lib_bind_back >= 202202L + auto madd = [](int a, int b, int c) { return a * b + c; }; + auto mul_plus_seven = std::bind_back(madd, 7); + assert(mul_plus_seven(4, 10) == 47); //: madd(4, 10, 7) == 47 + #endif + + #if __cpp_lib_bind_back >= 202306L + auto mul_plus_seven_cpp26 = std::bind_back(7); + assert(mul_plus_seven_cpp26(4, 10) == 47); + #endif + } + +.SH References + + * C++26 standard (ISO/IEC 14882:2026): + + * TBD Function templates bind_front and bind_back [func.bind.partial] + * C++23 standard (ISO/IEC 14882:2023): + + * 22.10.14 Function templates bind_front and bind_back [func.bind.partial] + * C++20 standard (ISO/IEC 14882:2020): + + * 20.14.14 Function template bind_front [func.bind.front] + +.SH See also + + bind binds one or more arguments to a function object + \fI(C++11)\fP \fI(function template)\fP + mem_fn creates a function object out of a pointer to a member + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::binder1st,std::binder2nd.3 b/man/std::binder1st,std::binder2nd.3 index de49e59a8..9219c057a 100644 --- a/man/std::binder1st,std::binder2nd.3 +++ b/man/std::binder1st,std::binder2nd.3 @@ -1,47 +1,55 @@ -.TH std::binder1st,std::binder2nd 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binder1st,std::binder2nd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binder1st,std::binder2nd \- std::binder1st,std::binder2nd + .SH Synopsis + Defined in header template< class Fn > - class binder1st : public std::unary_function { + typename Fn::result_type> + { protected: - Fn op; typename Fn::first_argument_type value; - - public: \fB(1)\fP \fB(deprecated)\fP - - binder1st(const Fn& fn, - const typename Fn::first_argument_type& value); + public: + binder1st( const Fn& fn, \fB(1)\fP (deprecated in C++11) + const typename Fn::first_argument_type& (removed in C++17) + value ); typename Fn::result_type - operator()(const typename Fn::second_argument_type& x) - const; + operator()(const typename + Fn::second_argument_type& x) const; typename Fn::result_type - operator()(typename Fn::second_argument_type& x) const; + operator()(typename Fn::second_argument_type& x) + const; }; template< class Fn > - class binder2nd : public unary_function { + typename Fn::result_type> + { protected: Fn op; typename Fn::second_argument_type value; public: - binder2nd(const Fn& fn, \fB(2)\fP \fB(deprecated)\fP - const typename Fn::second_argument_type& value); + binder2nd( const Fn& fn, \fB(2)\fP (deprecated in C++11) + const typename Fn::second_argument_type& (removed in C++17) + value ); typename Fn::result_type - operator()(const typename Fn::first_argument_type& x) - const; + operator()(const typename Fn::first_argument_type& + x) const; typename Fn::result_type - operator()(typename Fn::first_argument_type& x) const; + operator()(typename Fn::first_argument_type& x) + const; }; @@ -50,16 +58,60 @@ The value of the parameter is passed to the object at the construction time and stored within the object. Whenever the function object is invoked though operator(), the stored value is passed as one of the arguments, the other argument is passed as - an argument of operator(). The resulting function object is an unary function. + an argument of operator(). The resulting function object is a unary function. 1) Binds the first parameter to the value value given at the construction of the object. 2) Binds the second parameter to the value value given at the construction of the object. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + const double pi = std::acos(-1); // use std::numbers::pi in C++20 + + int main() + { + // deprecated in C++11, removed in C++17 + auto f1 = std::bind1st(std::multiplies(), pi / 180.0); + + // C++11 replacement + auto f2 = [](double a) { return a * pi / 180.0; }; + + for (double n : {0, 30, 45, 60, 90, 180}) + std::cout << n << "°\\t" << std::fixed << "= " + << f1(n) << " rad (using binder)\\t= " + << f2(n) << " rad (using lambda)\\n" + << std::defaultfloat; + } + +.SH Output: + + 0° = 0.000000 rad (using binder) = 0.000000 rad (using lambda) + 30° = 0.523599 rad (using binder) = 0.523599 rad (using lambda) + 45° = 0.785398 rad (using binder) = 0.785398 rad (using lambda) + 60° = 1.047198 rad (using binder) = 1.047198 rad (using lambda) + 90° = 1.570796 rad (using binder) = 1.570796 rad (using lambda) + 180° = 3.141593 rad (using binder) = 3.141593 rad (using lambda) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 109 C++98 operator() could not modify to argument added overloads to handle + passed to it this + .SH See also - bind1st - bind2nd binds one argument to a binary function - \fB(deprecated)\fP \fI(function template)\fP - \fB(deprecated)\fP + bind1st binds one argument to a binary function + bind2nd \fI(function template)\fP + (deprecated in C++11)(removed in C++17) diff --git a/man/std::binomial_distribution.3 b/man/std::binomial_distribution.3 index c948fca53..59e2db827 100644 --- a/man/std::binomial_distribution.3 +++ b/man/std::binomial_distribution.3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution \- std::binomial_distribution + .SH Synopsis Defined in header template< class IntType = int > \fI(since C++11)\fP @@ -7,7 +10,7 @@ Produces random non-negative integer values i, distributed according to discrete probability function: - P(i|t,p) =⎛ + \\(P(i|t,p) = \\binom{t}{i} \\cdot p^i \\cdot (1-p)^{t-i}\\)P(i|t,p) =⎛ ⎜ ⎝t i⎞ @@ -18,68 +21,78 @@ The value obtained is the number of successes in a sequence of t yes/no experiments, each of which succeeds with probability p. + std::binomial_distribution satisfies RandomNumberDistribution. + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + IntType - this is not one of short, int, long, long long, unsigned short, unsigned + int, unsigned long, or unsigned long long. + .SH Member types - Member type Definition - result_type IntType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP IntType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics p returns the distribution parameters - t \fI(public member function)\fP + t \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example Plot of binomial distribution with probability of success of each trial exactly 0.5, illustrating the relationship with the pascal triangle (the probabilities that none, - 1, 2, 3, or all four of the 4 trials will be successful in this case are 1:4:6:4:1) + 1, 2, 3, or all four of the 4 trials will be successful in this case are 1:4:6:4:1). + - // Run this code - #include #include - #include + #include #include #include - + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); // perform 4 trials, each succeeds 1 in 2 times std::binomial_distribution<> d(4, 0.5); - + std::map hist; - for (int n = 0; n < 10000; ++n) { + for (int n = 0; n != 10000; ++n) ++hist[d(gen)]; - } - for (auto p : hist) { - std::cout << p.first << ' ' - << std::string(p.second/100, '*') << '\\n'; - } + + for (auto const& [x, y] : hist) + std::cout << x << ' ' << std::string(y / 100, '*') << '\\n'; } .SH Possible output: @@ -92,4 +105,4 @@ .SH External links - Weisstein, Eric W. "Binomial Distribution." From MathWorld--A Wolfram Web Resource. + Weisstein, Eric W. "Binomial Distribution." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::binomial_distribution::binomial_distribution.3 b/man/std::binomial_distribution::binomial_distribution.3 index c083632f8..34aa35069 100644 --- a/man/std::binomial_distribution::binomial_distribution.3 +++ b/man/std::binomial_distribution::binomial_distribution.3 @@ -1,11 +1,16 @@ -.TH std::binomial_distribution::binomial_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::binomial_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::binomial_distribution \- std::binomial_distribution::binomial_distribution + .SH Synopsis - explicit binomial_distribution( IntType t = 1, double p = 0.5 ); \fB(1)\fP \fI(since C++11)\fP - explicit binomial_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + binomial_distribution() : binomial_distribution\fB(1)\fP {} (1) \fI(since C++11)\fP + explicit binomial_distribution( IntType t, double p = 0.5 ); \fB(2)\fP \fI(since C++11)\fP + explicit binomial_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs new distribution object. The first version uses t and p as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses t and p as the distribution parameters. + 3) Uses params as the distribution parameter. .SH Parameters @@ -16,3 +21,11 @@ .SH Notes Requires that 0 ≤ p ≤ 1 and 0 ≤ t. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::binomial_distribution::max.3 b/man/std::binomial_distribution::max.3 index e5e607b92..f2033d638 100644 --- a/man/std::binomial_distribution::max.3 +++ b/man/std::binomial_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::max \- std::binomial_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::binomial_distribution::min.3 b/man/std::binomial_distribution::min.3 index d5a3849e3..e9ed0bd15 100644 --- a/man/std::binomial_distribution::min.3 +++ b/man/std::binomial_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::min \- std::binomial_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::binomial_distribution::operator().3 b/man/std::binomial_distribution::operator().3 index 53a446ac5..cfa65b0b0 100644 --- a/man/std::binomial_distribution::operator().3 +++ b/man/std::binomial_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::operator() \- std::binomial_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::binomial_distribution::p,t.3 b/man/std::binomial_distribution::p,t.3 index ec8b9b428..37bfe83ea 100644 --- a/man/std::binomial_distribution::p,t.3 +++ b/man/std::binomial_distribution::p,t.3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution::p,t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::p,t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::p,t \- std::binomial_distribution::p,t + .SH Synopsis double p() const; \fB(1)\fP \fI(since C++11)\fP IntType t() const; \fB(2)\fP \fI(since C++11)\fP @@ -21,5 +24,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::binomial_distribution::param.3 b/man/std::binomial_distribution::param.3 index dcead115a..189efa51d 100644 --- a/man/std::binomial_distribution::param.3 +++ b/man/std::binomial_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::param \- std::binomial_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity @@ -25,21 +26,21 @@ .SH Example - + // Run this code #include #include - + int main() { std::random_device rd; std::mt19937 gen(rd()); using BinomialDist = std::binomial_distribution<>; BinomialDist bino_dis(1, 0.5); - + std::cout << "A sample of Binomial( 1, 0.5): " << bino_dis(gen) << '\\n'; - + // Use another parameter set bino_dis.param(BinomialDist::param_type(100,0.9)); std::cout << "A sample of Binomial(100, 0.9): " << bino_dis(gen) << '\\n'; diff --git a/man/std::binomial_distribution::reset.3 b/man/std::binomial_distribution::reset.3 index e9d01d9b9..9bc392a9c 100644 --- a/man/std::binomial_distribution::reset.3 +++ b/man/std::binomial_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::binomial_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::binomial_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::binomial_distribution::reset \- std::binomial_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::bit_and.3 b/man/std::bit_and.3 index 8033ceab6..89b713370 100644 --- a/man/std::bit_and.3 +++ b/man/std::bit_and.3 @@ -1,57 +1,42 @@ -.TH std::bit_and 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bit_and 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_and \- std::bit_and + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct bit_and; - template< class T = void > \fI(since C++14)\fP - struct bit_and; - - Function object for performing bitwise AND. Effectively calls operator& on type T. - -.SH Specializations - - The standard library provides a specialization of std::bit_and when T - is not specified, which leaves the parameter types and return type to - be deduced. - \fI(since C++14)\fP - function object implementing x & y deducing argument and - bit_and return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class bit_and; -.SH Member types - - Type Definition - result_type T - first_argument_type T - second_argument_type T + std::bit_and is a specialization of std::bit_and with parameter and return + type deduced. .SH Member functions - operator() returns the result of bitwise AND of two arguments + operator() applies operator& to lhs and rhs \fI(public member function)\fP - std::bit_and::operator() +std::bit_and::operator() + + template< class T, class U > - T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const - Returns the result of bitwise AND of lhs and rhs. + -> decltype(std::forward(lhs) & std::forward(rhs)); + + Returns the result of std::forward(lhs) & std::forward(rhs). .SH Parameters - lhs, rhs - values to compute bitwise AND of + lhs, rhs - values to bitwise AND .SH Return value - The result of lhs & rhs. - -.SH Exceptions + std::forward(lhs) & std::forward(rhs). - \fI(none)\fP +.SH Example -.SH Possible implementation + This section is incomplete + Reason: no example - constexpr T operator()(const T &lhs, const T &rhs) const - { - return lhs & rhs; - } +.SH Category: + * Todo no example diff --git a/man/std::bit_and.3 b/man/std::bit_and.3 deleted file mode 100644 index d3dde3a0a..000000000 --- a/man/std::bit_and.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::bit_and 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class bit_and; - - std::bit_and<> is a specialization of std::bit_and with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() applies operator& to lhs and rhs - \fI(public member function)\fP - - std::bit_and<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) & std::forward(rhs)); - - Returns the result of lhs & rhs. - -.SH Parameters - - lhs, rhs - values to compute bitwise AND for - -.SH Return value - - The result of lhs & rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::bit_cast.3 b/man/std::bit_cast.3 new file mode 100644 index 000000000..37e449888 --- /dev/null +++ b/man/std::bit_cast.3 @@ -0,0 +1,149 @@ +.TH std::bit_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_cast \- std::bit_cast + +.SH Synopsis + Defined in header + template< class To, class From > \fI(since C++20)\fP + constexpr To bit_cast( const From& from ) noexcept; + + Obtain a value of type To by reinterpreting the object representation of From. Every + bit in the value representation of the returned To object is equal to the + corresponding bit in the object representation of from. The values of padding bits + in the returned To object are unspecified. + + If there is no value of type To corresponding to the value representation produced, + the behavior is undefined. If there are multiple such values, which value is + produced is unspecified. + + A bit in the value representation of the result is indeterminate if it + + * does not correspond to a bit in the value representation of From (i.e. it + corresponds to a padding bit), or + * corresponds to a bit + of an object that + (until C++26) + for which the smallest enclosing object + (since C++26) is not within its lifetime, or + * has an indeterminate value. + + A bit in the value representation of the result is erroneous if it + corresponds to a bit for which the smallest enclosing object has an (since C++26) + erroneous value. + + The result does not otherwise contain any indeterminate or erroneous values. + + For each bit in the value representation of the result that is + indeterminate, the smallest object containing that bit has an + indeterminate value; the behavior is undefined unless that object is (until C++26) + of an uninitialized-friendly type. + + The result does not otherwise contain any indeterminate values. + For each bit b in the value representation of the result that is + indeterminate or erroneous, let u be the smallest object enclosing b: + + * If u is of uninitialized-friendly type, u has an indeterminate + value if any of the bits in its value representation are (since C++26) + indeterminate, or otherwise has an erroneous value. + * Otherwise, if b is indeterminate, the behavior is undefined. + * Otherwise, the behavior is erroneous, and the result is as + specified above. + + This overload participates in overload resolution only if sizeof(To) == sizeof(From) + and both To and From are TriviallyCopyable types. + + This function template is constexpr if and only if each of To, From and the types of + all subobjects of To and From: + + * is not a union type; + * is not a pointer type; + * is not a pointer to member type; + * is not a volatile-qualified type; and + * has no non-static data member of reference type. + +.SH Parameters + + from - the source of bits for the return value + +.SH Return value + + An object of type To whose value representation is as described above. + +.SH Possible implementation + + To implement std::bit_cast, ignoring the fact that it's constexpr, std::memcpy can + be used, when it is needed, to interpret the object representation as one of another + type: + + template + std::enable_if_t< + sizeof(To) == sizeof(From) && + std::is_trivially_copyable_v && + std::is_trivially_copyable_v, + To> + // constexpr support needs compiler magic + bit_cast(const From& src) noexcept + { + static_assert(std::is_trivially_constructible_v, + "This implementation additionally requires " + "destination type to be trivially constructible"); + + To dst; + std::memcpy(&dst, &src, sizeof(To)); + return dst; + } + +.SH Notes + + reinterpret_cast (or equivalent explicit cast) between pointer or reference types + shall not be used to reinterpret object representation in most cases because of the + type aliasing rule. + + Feature-test macro Value Std Feature + __cpp_lib_bit_cast 201806L (C++20) std::bit_cast + +.SH Example + + +// Run this code + + #include + #include + #include + + constexpr double f64v = 19880124.0; + constexpr auto u64v = std::bit_cast(f64v); + static_assert(std::bit_cast(u64v) == f64v); // round-trip + + constexpr std::uint64_t u64v2 = 0x3fe9000000000000ull; + constexpr auto f64v2 = std::bit_cast(u64v2); + static_assert(std::bit_cast(f64v2) == u64v2); // round-trip + + int main() + { + std::cout + << "std::bit_cast(" << std::fixed << f64v << ") == 0x" + << std::hex << u64v << '\\n' + << "std::bit_cast(0x" << std::hex << u64v2 << ") == " + << std::fixed << f64v2 << '\\n'; + } + +.SH Possible output: + + std::bit_cast(19880124.000000) == 0x4172f58bc0000000 + std::bit_cast(0x3fe9000000000000) == 0.781250 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + CWG 2482 C++20 it was unspecified whether UB would occur when specified + (P1272R4) involving indeterminate bits + +.SH See also + + start_lifetime_as implicitly creates objects in given storage with the object + start_lifetime_as_array representation reused + (C++23) \fI(function template)\fP diff --git a/man/std::bit_ceil.3 b/man/std::bit_ceil.3 new file mode 100644 index 000000000..dc2be29e1 --- /dev/null +++ b/man/std::bit_ceil.3 @@ -0,0 +1,95 @@ +.TH std::bit_ceil 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_ceil \- std::bit_ceil + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr T bit_ceil( T x ); + + Calculates the smallest integral power of two that is not smaller than x. + + If that value is not representable in T, the behavior is undefined. Call to this + function is permitted in constant evaluation only if the undefined behavior does not + occur. + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + The smallest integral power of two that is not smaller than x. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_int_pow2 202002L (C++20) Integral power-of-2 operations + +.SH Possible implementation + + See possible implementations in libstdc++ (gcc) and libc++ (clang). + + template + requires !std::same_as && !std::same_as && + !std::same_as && !std::same_as && + !std::same_as && !std::same_as + constexpr T bit_ceil(T x) noexcept + { + if (x <= 1u) + return T\fB(1)\fP; + if constexpr (std::same_as) + return T\fB(1)\fP << std::bit_width(T(x - 1)); + else + { // for types subject to integral promotion + constexpr int offset_for_ub = + std::numeric_limits::digits - std::numeric_limits::digits; + return T(1u << (std::bit_width(T(x - 1)) + offset_for_ub) >> offset_for_ub); + } + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using bin = std::bitset<8>; + + for (unsigned x{0}; x != 10; ++x) + { + unsigned const z = std::bit_ceil(x); // `ceil2` before P1956R1 + std::cout << "bit_ceil( " << bin(x) << " ) = " << bin(z) << '\\n'; + } + } + +.SH Output: + + bit_ceil( 00000000 ) = 00000001 + bit_ceil( 00000001 ) = 00000001 + bit_ceil( 00000010 ) = 00000010 + bit_ceil( 00000011 ) = 00000100 + bit_ceil( 00000100 ) = 00000100 + bit_ceil( 00000101 ) = 00001000 + bit_ceil( 00000110 ) = 00001000 + bit_ceil( 00000111 ) = 00001000 + bit_ceil( 00001000 ) = 00001000 + bit_ceil( 00001001 ) = 00010000 + +.SH See also + + bit_floor finds the largest integral power of two not greater than the given value + (C++20) \fI(function template)\fP diff --git a/man/std::bit_floor.3 b/man/std::bit_floor.3 new file mode 100644 index 000000000..6a9c0fe81 --- /dev/null +++ b/man/std::bit_floor.3 @@ -0,0 +1,87 @@ +.TH std::bit_floor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_floor \- std::bit_floor + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr T bit_floor( T x ) noexcept; + + If x is not zero, calculates the largest integral power of two that is not greater + than x. If x is zero, returns zero. + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - unsigned integer value + +.SH Return value + + Zero if x is zero; otherwise, the largest integral power of two that is not greater + than x. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_int_pow2 202002L (C++20) Integral power-of-2 operations + +.SH Possible implementation + + template + requires !std::same_as && !std::same_as && + !std::same_as && !std::same_as && + !std::same_as && !std::same_as + constexpr T bit_floor(T x) noexcept + { + if (x != 0) + return T{1} << (std::bit_width(x) - 1); + return 0; + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using bin = std::bitset<8>; + + for (unsigned x = 0; x != 10; ++x) + { + auto const z = std::bit_floor(x); // `floor2` before P1956R1 + std::cout << "bit_floor( " << bin(x) << " ) = " << bin(z) << '\\n'; + } + } + +.SH Output: + + bit_floor( 00000000 ) = 00000000 + bit_floor( 00000001 ) = 00000001 + bit_floor( 00000010 ) = 00000010 + bit_floor( 00000011 ) = 00000010 + bit_floor( 00000100 ) = 00000100 + bit_floor( 00000101 ) = 00000100 + bit_floor( 00000110 ) = 00000100 + bit_floor( 00000111 ) = 00000100 + bit_floor( 00001000 ) = 00001000 + bit_floor( 00001001 ) = 00001000 + +.SH See also + + bit_ceil finds the smallest integral power of two not less than the given + (C++20) value + \fI(function template)\fP + rotr computes the result of bitwise right-rotation + (C++20) \fI(function template)\fP + bit_width finds the smallest number of bits needed to represent the given value + (C++20) \fI(function template)\fP + has_single_bit checks if a number is an integral power of 2 + (C++20) \fI(function template)\fP diff --git a/man/std::bit_not.3 b/man/std::bit_not.3 index c8d1f794a..00f553ced 100644 --- a/man/std::bit_not.3 +++ b/man/std::bit_not.3 @@ -1,4 +1,7 @@ -.TH std::bit_not 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bit_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_not \- std::bit_not + .SH Synopsis Defined in header template< class T = void > \fI(since C++14)\fP @@ -8,28 +11,26 @@ .SH Specializations - The standard library provides a specialization of std::bit_not when T - is not specified, which leaves the parameter types and return type to - be deduced. - \fI(since C++14)\fP - function object implementing ~x deducing argument and - bit_not return types - \fI(class template specialization)\fP + The standard library provides a specialization of std::bit_not when T is not + specified, which leaves the parameter types and return type to be deduced. + + bit_not function object implementing ~x deducing parameter and return types + \fI(C++14)\fP \fI(class template specialization)\fP .SH Member types - Type Definition - result_type T - argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) T + argument_type (deprecated in C++17)(removed in C++20) T .SH Member functions operator() returns the result of bitwise NOT of its argument - \fI(public member function)\fP + \fI(C++14)\fP \fI(public member function)\fP - std::bit_not::operator() +std::bit_not::operator() - constexpr T operator()( const T& arg ) const; + constexpr T operator()( const T& arg ) const; \fI(since C++14)\fP Returns the result of bitwise NOT of arg. @@ -43,7 +44,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation @@ -51,3 +52,10 @@ { return ~arg; } + +.SH Notes + + Although std::bit_not is added via post-C++11 proposal N3421, it is treated as a + part of the resolution for LWG issue 660 (except for its transparent specialization + std::bit_not<>) by common implementations, and thus available in their C++98/03 + mode. diff --git a/man/std::bit_not.3 b/man/std::bit_not.3 deleted file mode 100644 index 23cfca2f8..000000000 --- a/man/std::bit_not.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::bit_not 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class bit_not; - - std::bit_not<> is a specialization of std::bit_not with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() applies operator~ to its argument - \fI(public member function)\fP - - std::bit_not<>::operator() - - template< class T > - - constexpr auto operator()( T&& arg ) const - - -> decltype(~std::forward(lhs)); - - Returns the result of ~arg. - -.SH Parameters - - arg - value to apply bitwise NOT to - -.SH Return value - - The result of ~arg. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::bit_or.3 b/man/std::bit_or.3 index dbd8e7134..b3526be21 100644 --- a/man/std::bit_or.3 +++ b/man/std::bit_or.3 @@ -1,4 +1,7 @@ -.TH std::bit_or 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bit_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_or \- std::bit_or + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -14,23 +17,26 @@ is not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing x | y deducing argument and - bit_or return types - \fI(class template specialization)\fP + bit_or function object implementing x | y deducing parameter and + \fI(C++14)\fP return types + \fI(class template specialization)\fP .SH Member types - Type Definition - result_type T - first_argument_type T - second_argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) T + first_argument_type (deprecated in C++17)(removed in C++20) T + second_argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Member functions operator() returns the result of bitwise OR of two arguments \fI(public member function)\fP - std::bit_or::operator() +std::bit_or::operator() T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP @@ -47,11 +53,20 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr T operator()(const T &lhs, const T &rhs) const + constexpr T operator()(const T& lhs, const T& rhs) const { return lhs | rhs; } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 660 C++98 function objects for bitwise operations are added + missing diff --git a/man/std::bit_or.3 b/man/std::bit_or.3 deleted file mode 100644 index 72bd6ad9a..000000000 --- a/man/std::bit_or.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::bit_or 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class bit_or; - - std::bit_or<> is a specialization of std::bit_or with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() to lhs and rhs - \fI(public member function)\fP - - std::bit_or<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) | std::forward(rhs)); - - Returns the result of lhs | rhs. - -.SH Parameters - - lhs, rhs - values to compute bitwise OR for - -.SH Return value - - The result of lhs | rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::bit_width.3 b/man/std::bit_width.3 new file mode 100644 index 000000000..d30bafac8 --- /dev/null +++ b/man/std::bit_width.3 @@ -0,0 +1,79 @@ +.TH std::bit_width 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_width \- std::bit_width + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr int bit_width( T x ) noexcept; + + If x is not zero, calculates the number of bits needed to store the value x, that + is, \\(1 + \\lfloor \\log_2(x) \\rfloor\\)1 + floor(log + 2(x)). If x is zero, returns zero. + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - unsigned integer value + +.SH Return value + + Zero if x is zero; otherwise, one plus the base-2 logarithm of x, with any + fractional part discarded. + +.SH Notes + + This function is equivalent to return std::numeric_limits::digits - + std::countl_zero(x);. + + Feature-test macro Value Std Feature + __cpp_lib_int_pow2 202002L (C++20) Integral power-of-2 operations + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + for (unsigned x{0}; x != 8; ++x) + { + std::cout + << "bit_width( " + << std::bitset<4>{x} << " ) = " + << std::bit_width(x) << '\\n'; + } + } + +.SH Output: + + bit_width( 0000 ) = 0 + bit_width( 0001 ) = 1 + bit_width( 0010 ) = 2 + bit_width( 0011 ) = 2 + bit_width( 0100 ) = 3 + bit_width( 0101 ) = 3 + bit_width( 0110 ) = 3 + bit_width( 0111 ) = 3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3656 C++20 the return type of bit_width is the same as the made it int + type of its function argument + +.SH See also + + countl_zero counts the number of consecutive 0 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP diff --git a/man/std::bit_xor.3 b/man/std::bit_xor.3 index 5abd33ca4..c2e81e24f 100644 --- a/man/std::bit_xor.3 +++ b/man/std::bit_xor.3 @@ -1,4 +1,7 @@ -.TH std::bit_xor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bit_xor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bit_xor \- std::bit_xor + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -14,23 +17,26 @@ is not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing x ^ y deducing argument and - bit_xor return types - \fI(class template specialization)\fP + bit_xor function object implementing x ^ y deducing parameter + \fI(C++14)\fP and return types + \fI(class template specialization)\fP .SH Member types - Type Definition - result_type T - first_argument_type T - second_argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) T + first_argument_type (deprecated in C++17)(removed in C++20) T + second_argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Member functions operator() returns the result of bitwise XOR of two arguments \fI(public member function)\fP - std::bit_xor::operator() +std::bit_xor::operator() T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP @@ -47,11 +53,20 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr T operator()(const T &lhs, const T &rhs) const + constexpr T operator()(const T& lhs, const T& rhs) const { return lhs ^ rhs; } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 660 C++98 function objects for bitwise operations are added + missing diff --git a/man/std::bit_xor.3 b/man/std::bit_xor.3 deleted file mode 100644 index 9a7ec61b1..000000000 --- a/man/std::bit_xor.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::bit_xor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class bit_xor; - - std::bit_xor<> is a specialization of std::bit_xor with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() applies operator^ to lhs and rhs - \fI(public member function)\fP - - std::bit_xor<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) ^ std::forward(rhs)); - - Returns the result of lhs ^ rhs. - -.SH Parameters - - lhs, rhs - values to compute bitwise XOR for - -.SH Return value - - The result of lhs ^ rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::bitset.3 b/man/std::bitset.3 index 1bba9b19e..f9eab0ecd 100644 --- a/man/std::bitset.3 +++ b/man/std::bitset.3 @@ -1,4 +1,7 @@ -.TH std::bitset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset \- std::bitset + .SH Synopsis Defined in header template< std::size_t N > @@ -6,10 +9,16 @@ The class template bitset represents a fixed-size sequence of N bits. Bitsets can be manipulated by standard logic operators and converted to and from strings and - integers. + integers. For the purpose of the string representation and of naming directions for + shift operations, the sequence is thought of as having its lowest indexed elements + at the right, as in the binary representation of integers. bitset meets the requirements of CopyConstructible and CopyAssignable. + All member functions of std::bitset are constexpr: it is possible to + create and use std::bitset objects in the evaluation of a constant (since C++23) + expression. + .SH Template parameters N - the number of bits to allocate storage for @@ -21,63 +30,128 @@ .SH Member functions - constructor constructs the bitset - \fI(public member function)\fP - operator== compares the contents - operator!= \fI(public member function)\fP + constructor constructs the bitset + \fI(public member function)\fP + operator== compares the contents + operator!= \fI(public member function)\fP + (removed in C++20) .SH Element access - operator[] accesses specific bit - \fI(public member function)\fP - test accesses specific bit - \fI(public member function)\fP - all - any - none checks if all, any or none bits are set to true - \fI(C++11)\fP \fI(public member function)\fP - - - count returns the number of bits set to true - \fI(public member function)\fP + operator[] accesses specific bit + \fI(public member function)\fP + test accesses specific bit + \fI(public member function)\fP + all checks if all, any or none of the bits are set to true + any \fI(public member function)\fP + none + count returns the number of bits set to true + \fI(public member function)\fP .SH Capacity - size returns the size number of bits that the bitset can hold - \fI(public member function)\fP + size returns the number of bits that the bitset holds + \fI(public member function)\fP .SH Modifiers operator&= - operator|= performs binary AND, OR, XOR and NOT - operator^= \fI(public member function)\fP + operator|= performs binary AND, OR, XOR and NOT + operator^= \fI(public member function)\fP operator~ operator<<= - operator>>= performs binary shift left and shift right - operator<< \fI(public member function)\fP + operator>>= performs binary shift left and shift right + operator<< \fI(public member function)\fP operator>> - set sets bits to true or given value - \fI(public member function)\fP - reset sets bits to false - \fI(public member function)\fP - flip toggles the values of bits - \fI(public member function)\fP + set sets bits to true or given value + \fI(public member function)\fP + reset sets bits to false + \fI(public member function)\fP + flip toggles the values of bits + \fI(public member function)\fP .SH Conversions - to_string returns a string representation of the data - \fI(public member function)\fP - to_ulong returns an unsigned long integer representation of the data - \fI(public member function)\fP - to_ullong returns an unsigned long long integer representation of the data - \fI(C++11)\fP \fI(public member function)\fP + to_string returns a string representation of the data + \fI(public member function)\fP + to_ulong returns an unsigned long integer representation of the data + \fI(public member function)\fP + to_ullong returns an unsigned long long integer representation of the data + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions operator& performs binary logic operations on bitsets - operator| \fI(function)\fP + operator| \fI(function template)\fP operator^ operator<< performs stream input and output of bitsets - operator>> \fI(function)\fP + operator>> \fI(function template)\fP .SH Helper classes std::hash hash support for std::bitset - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP .SH Notes - If the size of the bitset is not known at compile time, std::vector or - boost::dynamic_bitset may be used. + If the size of a bit-set is not known at compile time, or it is necessary to change + its size at run-time, the dynamic types such as std::vector or + boost::dynamic_bitset<> may be used instead. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_bitset 202207L (C++23) A more constexpr std::bitset + __cpp_lib_bitset 202306L (C++26) Interfacing std::bitset with + std::string_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + typedef std::size_t length_t, position_t; // the hints + + // constructors: + constexpr std::bitset<4> b1; + constexpr std::bitset<4> b2{0xA}; // == 0B1010 + std::bitset<4> b3{"0011"}; // can also be constexpr since C++23 + std::bitset<8> b4{"ABBA", length_t(4), /*0:*/'A', /*1:*/'B'}; // == 0B0000'0110 + + // bitsets can be printed out to a stream: + std::cout << "b1:" << b1 << "; b2:" << b2 << "; b3:" << b3 << "; b4:" << b4 << '\\n'; + + // bitset supports bitwise operations: + b3 |= 0b0100; assert(b3 == 0b0111); + b3 &= 0b0011; assert(b3 == 0b0011); + b3 ^= std::bitset<4>{0b1100}; assert(b3 == 0b1111); + + // operations on the whole set: + b3.reset(); assert(b3 == 0); + b3.set(); assert(b3 == 0b1111); + assert(b3.all() && b3.any() && !b3.none()); + b3.flip(); assert(b3 == 0); + + // operations on individual bits: + b3.set(position_t(1), true); assert(b3 == 0b0010); + b3.set(position_t(1), false); assert(b3 == 0); + b3.flip(position_t(2)); assert(b3 == 0b0100); + b3.reset(position_t(2)); assert(b3 == 0); + + // subscript operator[] is supported: + b3[2] = true; assert(true == b3[2]); + + // other operations: + assert(b3.count() == 1); + assert(b3.size() == 4); + assert(b3.to_ullong() == 0b0100ULL); + assert(b3.to_string() == "0100"); + } + +.SH Output: + + b1:0000; b2:1010; b3:0011; b4:00000110 + +.SH See also + + vector space-efficient dynamic bitset + \fI(class template specialization)\fP + Bit manipulation (C++20) utilities to access, manipulate, and process individual + bits and bit sequences diff --git a/man/std::bitset::all,std::bitset::any,std::bitset::none.3 b/man/std::bitset::all,std::bitset::any,std::bitset::none.3 index 1e56dec41..ea2d9172b 100644 --- a/man/std::bitset::all,std::bitset::any,std::bitset::none.3 +++ b/man/std::bitset::all,std::bitset::any,std::bitset::none.3 @@ -1,16 +1,18 @@ -.TH std::bitset::all,std::bitset::any,std::bitset::none 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bool all() const; \fI(since C++11)\fP - bool any() const; - bool none() const; - - Checks if all, any or none of the bits are set to true. +.TH std::bitset::all,std::bitset::any,std::bitset::none 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::all,std::bitset::any,std::bitset::none \- std::bitset::all,std::bitset::any,std::bitset::none - 1) Checks if all bits are set to true - - 2) Checks if any bits are set to true +.SH Synopsis + bool all() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bool any() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++23) + bool none() const; \fB(3)\fP (noexcept since C++11) + (constexpr since C++23) - 3) Checks if none of the bits are set to true + 1) Checks if all bits are set to true. + 2) Checks if any bits are set to true. + 3) Checks if none of the bits are set to true. .SH Parameters @@ -18,35 +20,49 @@ .SH Return value - 1) true if all bits are set to true, otherwise false - - 2) true if any of the bits are set to true, otherwise false - - 3) true if none of the bits are set to true, otherwise false + 1) true if all bits are set to true, otherwise false. + 2) true if any of the bits are set to true, otherwise false. + 3) true if none of the bits are set to true, otherwise false. .SH Example - + // Run this code - #include #include - + #include + int main() { std::bitset<4> b1("0000"); std::bitset<4> b2("0101"); std::bitset<4> b3("1111"); - - std::cout << "bitset\\t" << "all\\t" << "any\\t" << "none\\n"; - std::cout << b1 << '\\t' << b1.all() << '\\t' << b1.any() << '\\t' << b1.none() << '\\n'; - std::cout << b2 << '\\t' << b2.all() << '\\t' << b2.any() << '\\t' << b2.none() << '\\n'; - std::cout << b3 << '\\t' << b3.all() << '\\t' << b3.any() << '\\t' << b3.none() << '\\n'; + + std::cout + << "bitset\\t" << "all\\t" << "any\\t" << "none\\n" + << b1 << '\\t' << b1.all() << '\\t' << b1.any() << '\\t' << b1.none() << '\\n' + << b2 << '\\t' << b2.all() << '\\t' << b2.any() << '\\t' << b2.none() << '\\n' + << b3 << '\\t' << b3.all() << '\\t' << b3.any() << '\\t' << b3.none() << '\\n'; } .SH Output: - bitset all any none - 0000 0 0 1 - 0101 0 1 0 - 1111 1 1 0 + bitset all any none + 0000 0 0 1 + 0101 0 1 0 + 1111 1 1 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 693 C++98 the member function all() was not provided provided + +.SH See also + + count returns the number of bits set to true + \fI(public member function)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP diff --git a/man/std::bitset::bitset.3 b/man/std::bitset::bitset.3 index 8d7a1bf5a..b9e97d51e 100644 --- a/man/std::bitset::bitset.3 +++ b/man/std::bitset::bitset.3 @@ -1,49 +1,80 @@ -.TH std::bitset::bitset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - constexpr bitset() noexcept; \fB(1)\fP - constexpr bitset( unsigned long long val ) noexcept; \fB(2)\fP - template< class CharT, class Traits, class Alloc > +.TH std::bitset::bitset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::bitset \- std::bitset::bitset - explicit bitset( const std::basic_string& str, - typename (until - std::basic_string::size_type pos = 0, C++11) - typename - std::basic_string::size_type n = - - std::basic_string::npos); +.SH Synopsis + bitset(); (until + C++11) + constexpr bitset() noexcept; (since + C++11) + bitset( unsigned long val ); \fI(until C++11)\fP + constexpr bitset( unsigned long long val ) \fI(since C++11)\fP + noexcept; template< class CharT, class Traits, class Alloc > - explicit bitset( const std::basic_string& str, - typename - std::basic_string::size_type pos = 0, \fB(3)\fP (since - typename C++11) - std::basic_string::size_type n = - std::basic_string::npos, - CharT zero = CharT(’0’), - - CharT one = CharT(’1’)); + explicit bitset( const std::basic_string& str, + typename std::basic_string::size_type + pos = 0, \fB(3)\fP (constexpr since + typename std::basic_string::size_type + n = std::basic_string::npos, + CharT zero = CharT('0'), + \fB(1)\fP + CharT one = CharT('1') ); + template< class CharT, class Traits > \fB(2)\fP + + constexpr explicit bitset( + std::basic_string_view str, + std::size_t pos = 0, + std::size_t n = \fB(4)\fP (since C++26) + std::size_t(-1), + CharT zero = CharT('0'), + + CharT one = CharT('1') + ); template< class CharT > - explicit bitset( const CharT* str, - typename std::basic_string::size_type n = \fB(4)\fP (since - std::basic_string::npos, C++11) - CharT zero = CharT(’0’), + explicit bitset( const CharT* str, \fI(since C++11)\fP + std::size_t n = std::size_t(-1), \fB(5)\fP (constexpr since + CharT zero = CharT('0'), C++23) - CharT one = CharT(’1’)); + CharT one = CharT('1') ); Constructs a new bitset from one of several optional data sources: 1) Default constructor. Constructs a bitset with all bits set to zero. - 2) Constructs a bitset using the bits in val. If N is the size of the bitset and M - is the number of set bits in val, then only min(N, M) bits will be included in the - bitset. + 2) Constructs a bitset, initializing the first (rightmost, least significant) M bit + positions to the corresponding bit values of val, where M is the smaller of + * N, and + + * the number of bits in the value representation of unsigned long. \fI(until C++11)\fP + For typical implementations, it is 32 or 64. + * the number of bits in the value representation of unsigned long \fI(since C++11)\fP + long. For typical implementations, it is 64. + + If M is less than N, the remaining bit positions are initialized to zeroes. 3) Constructs a bitset using the characters in the std::basic_string str. An optional starting position pos and length n can be provided, as well as characters - denoting alternate values for set (one) and unset (zero) bits. - The effective length of the initializing string is min(n, str.size() - pos). - If pos > str.size(), this constructor throws std::out_of_range. If any characters - examined in str are not zero or one, it throws std::invalid_argument. - 4) Similar to \fB(3)\fP, but uses a CharT* instead of a std::basic_string. + denoting alternate values for set (one) and unset (zero) bits. Traits::eq() is used + to compare the character values. + The effective length of the initializing string is std::min(n, str.size() - pos). + If pos > str.size(), this constructor throws std::out_of_range. If any character + examined in str is not zero or one, this constructor throws std::invalid_argument. + 4) Similar to \fB(3)\fP, but uses a std::basic_string_view instead of a std::basic_string. + 5) Similar to \fB(3)\fP, but uses a const CharT* instead of a std::basic_string. + Equivalent to + + bitset(n == std::size_t(-1) + ? basic_string(str) + : basic_string(str, n), 0, n, zero, one) + + This constructor may dynamically allocate memory, although (until C++26) + implementations generally avoid dynamic allocation. + This constructor does not dynamically allocate memory, as if only (since C++26) + std::basic_string_view is involved. .SH Parameters @@ -56,49 +87,89 @@ .SH Exceptions - 1. none - - 2. none + 3,4) std::out_of_range if pos > str.size(), std::invalid_argument if any character + is not one or zero. + 5) std::invalid_argument if any character is not one or zero. - 3. std::out_of_range if pos > str.size() +.SH Notes - 4. none + Feature-test macro Value Std Feature + __cpp_lib_constexpr_bitset 202207L (C++23) A more constexpr std::bitset, overloads + (3,5) + __cpp_lib_bitset 202306L (C++26) Interfacing std::bitset with + std::string_view, \fB(4)\fP .SH Example - + // Run this code #include + #include + #include #include - + int main() { - // empty constructor + // empty constructor (1) std::bitset<8> b1; // [0,0,0,0,0,0,0,0] - - // unsigned long long constructor - std::bitset<8> b2(42); // [0,0,1,0,1,0,1,0] - - // string constructor + + // unsigned long long constructor (2) + std::bitset<8> b2(42); // [0,0,1,0,1,0,1,0] + std::bitset<70> bl(ULLONG_MAX); // [0,0,0,0,0,0,1,1,1,...,1,1,1] in C++11 + std::bitset<8> bs(0xfff0); // [1,1,1,1,0,0,0,0] + + // string constructor (3) std::string bit_string = "110010"; std::bitset<8> b3(bit_string); // [0,0,1,1,0,0,1,0] std::bitset<8> b4(bit_string, 2); // [0,0,0,0,0,0,1,0] std::bitset<8> b5(bit_string, 2, 3); // [0,0,0,0,0,0,0,1] - - // string constructor using custom zero/one digits + + // string constructor using custom zero/one digits (3) std::string alpha_bit_string = "aBaaBBaB"; std::bitset<8> b6(alpha_bit_string, 0, alpha_bit_string.size(), 'a', 'B'); // [0,1,0,0,1,1,0,1] - - // char* constructor using custom digits + + // char* constructor using custom digits (5) std::bitset<8> b7("XXXXYYYY", 8, 'X', 'Y'); // [0,0,0,0,1,1,1,1] - return 0; + + std::cout << "b1: " << b1 << "\\nb2: " << b2 << "\\nbl: " << bl + << "\\nbs: " << bs << "\\nb3: " << b3 << "\\nb4: " << b4 + << "\\nb5: " << b5 << "\\nb6: " << b6 << "\\nb7: " << b7 << '\\n'; } +.SH Possible output: + + b1: 00000000 + b2: 00101010 + bl: 0000001111111111111111111111111111111111111111111111111111111111111111 + bs: 11110000 + b3: 00110010 + b4: 00000010 + b5: 00000001 + b6: 01001101 + b7: 00001111 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the values of the zero and one characters added parameters to + LWG 396 C++98 for overload \fB(3)\fP provide + were 0 and 1 (which do not correspond to values for these + '0' and '1') characters + M is the smaller of N and the value + CHAR_BIT * sizeof(unsigned long) consider the number + LWG 457 C++98 for overload \fB(2)\fP, but unsigned long is of bits of the value + not representation instead + guaranteed to use all its bits to + represent its value + .SH See also set sets bits to true or given value - \fI(public member function)\fP + \fI(public member function)\fP reset sets bits to false - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::count.3 b/man/std::bitset::count.3 index 5b87a1fb8..7e8f270f3 100644 --- a/man/std::bitset::count.3 +++ b/man/std::bitset::count.3 @@ -1,6 +1,10 @@ -.TH std::bitset::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::count \- std::bitset::count + .SH Synopsis - size_t count() const; + std::size_t count() const; (noexcept since C++11) + (constexpr since C++23) Returns the number of bits that are set to true. @@ -10,41 +14,46 @@ .SH Return value - number of bits that are set to true. + Number of bits that are set to true. .SH Example - + // Run this code - #include #include - + #include + int main() { std::bitset<8> b("00010010"); - std::cout << "initial value: " << b << '\\n'; - - // find the first unset bit - size_t idx = 0; - while (idx < b.size() && b.test(idx)) ++idx; - - // continue setting bits until half the bitset is filled - while (idx < b.size() && b.count() < b.size()/2) { + std::cout << "Initial value: " << b << '\\n'; + + // Find the first unset bit + std::size_t idx = 0; + while (idx < b.size() && b.test(idx)) + ++idx; + + // Continue setting bits until half the bitset is filled + while (idx < b.size() && b.count() < b.size() / 2) + { b.set(idx); - std::cout << "setting bit " << idx << ": " << b << '\\n'; - while (idx < b.size() && b.test(idx)) ++idx; + std::cout << "Setting bit " << idx << ": " << b << '\\n'; + while (idx < b.size() && b.test(idx)) + ++idx; } - + } .SH Output: - initial value: 00010010 - setting bit 0: 00010011 - setting bit 2: 00010111 + Initial value: 00010010 + Setting bit 0: 00010011 + Setting bit 2: 00010111 .SH See also - size returns the size number of bits that the bitset can hold - \fI(public member function)\fP + size returns the number of bits that the bitset holds + \fI(public member function)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP diff --git a/man/std::bitset::flip.3 b/man/std::bitset::flip.3 index 0495a8f43..f5375f93e 100644 --- a/man/std::bitset::flip.3 +++ b/man/std::bitset::flip.3 @@ -1,12 +1,16 @@ -.TH std::bitset::flip 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::flip 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::flip \- std::bitset::flip + .SH Synopsis - bitset& flip(); \fB(1)\fP - bitset& flip( size_t pos ); \fB(2)\fP + bitset& flip(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& flip( std::size_t pos ); \fB(2)\fP (constexpr since C++23) Flips bits, i.e. changes true values to false and false values to true. Equivalent to a logical NOT operation on part or all of the bitset. - 1) Flips all bits (equivalent to operator~) + 1) Flips all bits (like operator~, but in-place). 2) Flips the bit at the position pos. .SH Parameters @@ -19,32 +23,25 @@ .SH Exceptions - 1) - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - 2) throws std::out_of_range if pos does not correspond to a valid position within the bitset. .SH Example - + // Run this code - #include #include - + #include + int main() { - std::bitset<4> b; - - std::cout << b << "\\n"; - std::cout << b.flip(0) << '\\n'; - std::cout << b.flip(2) << '\\n'; - std::cout << b.flip() << '\\n'; + std::bitset<4> flops; + + std::cout << flops << '\\n' + << flops.flip(0) << '\\n' + << flops.flip(2) << '\\n' + << flops.flip() << '\\n'; } .SH Output: @@ -57,10 +54,12 @@ .SH See also set sets bits to true or given value - \fI(public member function)\fP + \fI(public member function)\fP reset sets bits to false - \fI(public member function)\fP + \fI(public member function)\fP operator&= operator|= performs binary AND, OR, XOR and NOT - operator^= \fI(public member function)\fP + operator^= \fI(public member function)\fP operator~ + flip flips all the bits + \fI(public member function of std::vector)\fP diff --git a/man/std::bitset::operator&=,|=,^=,~.3 b/man/std::bitset::operator&=,|=,^=,~.3 index 0319134c6..ce19e1c79 100644 --- a/man/std::bitset::operator&=,|=,^=,~.3 +++ b/man/std::bitset::operator&=,|=,^=,~.3 @@ -1,21 +1,25 @@ -.TH std::bitset::operator&=,|=,^=,~ 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::operator&=,|=,^=,~ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::operator&=,|=,^=,~ \- std::bitset::operator&=,|=,^=,~ + .SH Synopsis - bitset& operator&=( const bitset& other ); \fB(1)\fP - bitset& operator|=( const bitset& other ); \fB(2)\fP - bitset& operator^=( const bitset& other ); \fB(3)\fP - bitset operator~() const; \fB(4)\fP + bitset& operator&=( const bitset& other ); \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& operator|=( const bitset& other ); \fB(2)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& operator^=( const bitset& other ); \fB(3)\fP (noexcept since C++11) + (constexpr since C++23) + bitset operator~() const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++23) Performs binary AND, OR, XOR and NOT. 1) Sets the bits to the result of binary AND on corresponding pairs of bits of *this and other. - 2) Sets the bits to the result of binary OR on corresponding pairs of bits of *this and other. - 3) Sets the bits to the result of binary XOR on corresponding pairs of bits of *this and other. - 4) Returns a temporary copy of *this with all bits flipped (binary NOT). Note that &=, |=, and ^= are only defined for bitsets of the same size N. @@ -27,38 +31,44 @@ .SH Return value 1-3) *this - - 4) a bitset temporary with all bits flipped + 4) std::bitset(*this).flip() .SH Example - + // Run this code + #include + #include #include #include - #include - + int main() { - std::bitset<16> dest; - std::string pattern_str = "1001"; - std::bitset<16> pattern(pattern_str); - - for (size_t i = 0, ie = dest.size()/pattern_str.size(); i != ie; ++i) { + const std::string pattern_str{"1001"}; + std::bitset<16> pattern{pattern_str}, dest; + + for (std::size_t i = dest.size() / pattern_str.size(); i != 0; --i) + { dest <<= pattern_str.size(); dest |= pattern; + std::cout << dest << " (i = " << i << ")\\n"; } - std::cout << dest << '\\n'; + + std::cout << ~dest << " (~dest)\\n"; } .SH Output: - 1001100110011001 + 0000000000001001 (i = 4) + 0000000010011001 (i = 3) + 0000100110011001 (i = 2) + 1001100110011001 (i = 1) + 0110011001100110 (~dest) .SH See also operator<<= operator>>= performs binary shift left and shift right - operator<< \fI(public member function)\fP + operator<< \fI(public member function)\fP operator>> diff --git a/man/std::bitset::operator<<,<<=,>>,>>=.3 b/man/std::bitset::operator<<,<<=,>>,>>=.3 deleted file mode 100644 index c187b56b1..000000000 --- a/man/std::bitset::operator<<,<<=,>>,>>=.3 +++ /dev/null @@ -1,61 +0,0 @@ -.TH std::bitset::operator<<,<<=,>>,>>= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bitset operator<<( size_t pos ) const; \fB(1)\fP - bitset& operator<<=( size_t pos ); \fB(2)\fP - bitset operator>>( size_t pos ) const; \fB(3)\fP - bitset& operator>>=( size_t pos ); \fB(4)\fP - - Performs binary shift left and binary shift right. Zeroes are shifted in. - - 1-2) Performs binary shift left. The \fB(2)\fP version is destructive, i.e. performs the - shift to the current object. - - 3-4) Performs binary shift right. The \fB(4)\fP version is destructive, i.e. performs the - shift to the current object. - -.SH Parameters - - pos - number of positions to shift the bits - -.SH Return value - - 1,3) new bitset object containing the shifted bits - - 2,4) *this - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::bitset<8> b("01110010"); - std::cout << "initial value: " << b << '\\n'; - - while (b.any()) { - while (!b.test(0)) { - b >>= 1; - } - std::cout << b << '\\n'; - b >>= 1; - } - } - -.SH Output: - - initial value: 01110010 - 00111001 - 00000111 - 00000011 - 00000001 - -.SH See also - - operator&= - operator|= performs binary AND, OR, XOR and NOT - operator^= \fI(public member function)\fP - operator~ diff --git a/man/std::bitset::operator==,std::bitset::operator!=.3 b/man/std::bitset::operator==,std::bitset::operator!=.3 new file mode 100644 index 000000000..0992d7513 --- /dev/null +++ b/man/std::bitset::operator==,std::bitset::operator!=.3 @@ -0,0 +1,54 @@ +.TH std::bitset::operator==,std::bitset::operator!= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::operator==,std::bitset::operator!= \- std::bitset::operator==,std::bitset::operator!= + +.SH Synopsis + bool operator==( const bitset& rhs ) const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bool operator!=( const bitset& rhs ) const; \fB(2)\fP (noexcept since C++11) + \fI(until C++20)\fP + + 1) Returns true if all of the bits in *this and rhs are equal. + 2) Returns true if any of the bits in *this and rhs are not equal. + + The != operator is synthesized from operator==. \fI(since C++20)\fP + +.SH Parameters + + rhs - bitset to compare + +.SH Return value + + 1) true if the value of each bit in *this equals the value of the corresponding bit + in rhs, otherwise false. + 2) true if !(*this == rhs), otherwise false. + +.SH Example + + Compare given bitsets to determine if they are identical: + + +// Run this code + + #include + #include + + int main() + { + std::bitset<4> b1(0b0011); + std::bitset<4> b2(b1); + std::bitset<4> b3(0b0100); + + std::cout << std::boolalpha; + std::cout << "b1 == b2: " << (b1 == b2) << '\\n'; + std::cout << "b1 == b3: " << (b1 == b3) << '\\n'; + std::cout << "b1 != b3: " << (b1 != b3) << '\\n'; + + // b1 == std::bitset<3>{}; // compile-time error: incompatible types + } + +.SH Output: + + b1 == b2: true + b1 == b3: false + b1 != b3: true diff --git a/man/std::bitset::operator>,>>=.3 b/man/std::bitset::operator>,>>=.3 new file mode 100644 index 000000000..3211e627a --- /dev/null +++ b/man/std::bitset::operator>,>>=.3 @@ -0,0 +1,74 @@ +.TH std::bitset::operator>,>>= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::operator>,>>= \- std::bitset::operator>,>>= + +.SH Synopsis + bitset operator<<( std::size_t pos ) const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& operator<<=( std::size_t pos ); \fB(2)\fP (noexcept since C++11) + (constexpr since C++23) + bitset operator>>( std::size_t pos ) const; \fB(3)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& operator>>=( std::size_t pos ); \fB(4)\fP (noexcept since C++11) + (constexpr since C++23) + + Performs binary shift left (towards higher index positions) and binary shift right + (towards lower index positions). Zeroes are shifted in, and bits that would go to an + index out of range are dropped (ignored). + + 1,2) Performs binary shift left. The \fB(2)\fP version is destructive, i.e. performs the + shift to the current object. + 3,4) Performs binary shift right. The \fB(4)\fP version is destructive, i.e. performs the + shift to the current object. + +.SH Parameters + + pos - number of positions to shift the bits + +.SH Return value + + 1,3) New bitset object containing the shifted bits. + 2,4) *this + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::bitset<8> b{0b01110010}; + std::cout << b << " (initial value)\\n"; + + for (; b.any(); b >>= 1) + { + while (!b.test(0)) + b >>= 1; + std::cout << b << '\\n'; + } + + std::cout << b << " (final value)\\n"; + } + +.SH Output: + + 01110010 (initial value) + 00111001 + 00000111 + 00000011 + 00000001 + 00000000 (final value) + +.SH See also + + rotl computes the result of bitwise left-rotation + (C++20) \fI(function template)\fP + rotr computes the result of bitwise right-rotation + (C++20) \fI(function template)\fP + operator&= + operator|= performs binary AND, OR, XOR and NOT + operator^= \fI(public member function)\fP + operator~ diff --git a/man/std::bitset::operator[].3 b/man/std::bitset::operator[].3 index 4c4fed9b2..e4c4458bd 100644 --- a/man/std::bitset::operator[].3 +++ b/man/std::bitset::operator[].3 @@ -1,8 +1,10 @@ -.TH std::bitset::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::operator[] \- std::bitset::operator[] + .SH Synopsis - bool operator[]( std::size_t pos ) const; \fI(until C++11)\fP - constexpr bool operator[]( std::size_t pos ) const; \fB(1)\fP \fI(since C++11)\fP - reference operator[]( std::size_t pos ); \fB(2)\fP + bool operator[]( std::size_t pos ) const; \fB(1)\fP (constexpr since C++11) + reference operator[]( std::size_t pos ); \fB(2)\fP (constexpr since C++23) Accesses the bit at position pos. The first version returns the value of the bit, the second version returns an object of type std::bitset::reference that allows @@ -17,31 +19,32 @@ .SH Return value - 1) the value of the requested bit - - 2) an object of type std::bitset::reference, which allows writing to the requested + 1) The value of the requested bit. + 2) An object of type std::bitset::reference, which allows writing to the requested bit. .SH Exceptions - None + \fI(none)\fP .SH Example - + // Run this code - #include #include - + #include + #include + int main() { - std::bitset<8> b1(42); - for (std::size_t i = 0; i < b1.size(); ++i) { + std::bitset<8> b1{0b00101010}; // binary literal for 42 + + for (std::size_t i = 0; i < b1.size(); ++i) std::cout << "b1[" << i << "]: " << b1[i] << '\\n'; - } - b1[0] = true; // modifies the first bit through bitset::refence - std::cout << "After setting bit 0, the bitset holds " << b1 << '\\n'; + b1[0] = true; // modifies the first bit through bitset::reference + + std::cout << "After setting bit 0, b1 holds " << b1 << '\\n'; } .SH Output: @@ -54,9 +57,24 @@ b1[5]: 1 b1[6]: 0 b1[7]: 0 - After setting bit 0, the bitset holds 00101011 + After setting bit 0, b1 holds 00101011 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the description was missing in the + LWG 11 C++98 C++ standard 1. description added + 2. there was only the non-const 2. added the const overload + overload + the behavior of reading the bit at + LWG 907 C++98 pos was equivalent avoids mentioning test() + to that of test(pos), but test() may + throw exceptions .SH See also test accesses specific bit - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::reference.3 b/man/std::bitset::reference.3 index 23e80b13e..45067c98f 100644 --- a/man/std::bitset::reference.3 +++ b/man/std::bitset::reference.3 @@ -1,4 +1,7 @@ -.TH std::bitset::reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::reference \- std::bitset::reference + .SH Synopsis class reference; @@ -7,7 +10,7 @@ individual bits of a bitset, since standard C++ types (like references and pointers) are not built with enough precision to specify individual bits. - The primary use of std::bitset::reference is to provide an l-value that can be + The primary use of std::bitset::reference is to provide an lvalue that can be returned from operator[]. Any reads or writes to a bitset that happen via a std::bitset::reference potentially @@ -17,27 +20,34 @@ constructor constructs the reference. Accessible only to std::bitset itself (private member function) - destructor ~reference + destructor destroys the reference \fI(public member function)\fP operator= assigns a bool to the referenced bit \fI(public member function)\fP operator bool returns the referenced bit - \fI(public member function)\fP - operator ~ returns inverted referenced bit + \fI(public member function)\fP + operator~ returns inverted referenced bit \fI(public member function)\fP flip flips the referenced bit \fI(public member function)\fP - std::bitset::reference::~reference +std::bitset::reference::~reference - ~reference() + ~reference(); (constexpr since C++23) Destroys the reference. - std::bitset::reference::operator= +std::bitset::reference::operator= - reference& operator=( bool x ); - reference& operator=( const reference& x ); + reference& operator=( bool x ); \fI(until C++11)\fP + \fI(since C++11)\fP + reference& operator=( bool x ) noexcept; (constexpr since + C++23) + reference& operator=( const reference& x \fB(1)\fP \fI(until C++11)\fP + ); + reference& operator=( const reference& x ) \fB(2)\fP \fI(since C++11)\fP + noexcept; (constexpr since + C++23) Assigns a value to the referenced bit. @@ -49,16 +59,11 @@ *this -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +std::bitset::reference::operator bool - std::bitset::reference::operator bool - - operator bool() const; + operator bool() const; \fI(until C++11)\fP + operator bool() const noexcept; \fI(since C++11)\fP + (constexpr since C++23) Returns the value of the referenced bit. @@ -70,16 +75,11 @@ The referenced bit. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +std::bitset::reference::operator~ - std::bitset::reference::operator~ - - bool operator~() const; + bool operator~() const; \fI(until C++11)\fP + bool operator~() const noexcept; \fI(since C++11)\fP + (constexpr since C++23) Returns the inverse of the referenced bit. @@ -91,16 +91,11 @@ The inverse of the referenced bit. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +std::bitset::reference::flip - std::bitset::reference::flip - - reference& flip(); + reference& flip(); \fI(until C++11)\fP + reference& flip() noexcept; \fI(since C++11)\fP + (constexpr since C++23) Inverts the referenced bit. @@ -112,14 +107,48 @@ *this -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::bitset<4> bs{0b1110}; + + std::bitset<4>::reference ref = bs[2]; + + auto info = [&](int id) + { + std::cout << id << ") bs: " << bs << "; ref bit: " << ref << '\\n'; + }; + + info(1); + ref = false; + info(2); + ref = true; + info(3); + ref.flip(); + info(4); + ref = bs[1]; // operator=( const reference& x ) + info(5); + + std::cout << "6) ~ref bit: " << ~ref << '\\n'; + } + +.SH Output: - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + 1) bs: 1110; ref bit: 1 + 2) bs: 1010; ref bit: 0 + 3) bs: 1110; ref bit: 1 + 4) bs: 1010; ref bit: 0 + 5) bs: 1110; ref bit: 1 + 6) ~ref bit: 0 .SH See also operator[] accesses specific bit - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::reset.3 b/man/std::bitset::reset.3 index 5f37d7983..615cfe8a6 100644 --- a/man/std::bitset::reset.3 +++ b/man/std::bitset::reset.3 @@ -1,7 +1,11 @@ -.TH std::bitset::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::reset \- std::bitset::reset + .SH Synopsis - bitset& reset(); \fB(1)\fP - bitset& reset( size_t pos ); \fB(2)\fP + bitset& reset(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& reset( std::size_t pos ); \fB(2)\fP (constexpr since C++23) Sets bits to false. @@ -18,24 +22,17 @@ .SH Exceptions - 1) - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - 2) Throws std::out_of_range if pos does not correspond to a valid position within - the bitset + the bitset. .SH Example - + // Run this code - #include #include - + #include + int main() { std::bitset<8> b(42); @@ -55,6 +52,6 @@ .SH See also set sets bits to true or given value - \fI(public member function)\fP + \fI(public member function)\fP flip toggles the values of bits - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::set.3 b/man/std::bitset::set.3 index 36528a609..13b7a6b9b 100644 --- a/man/std::bitset::set.3 +++ b/man/std::bitset::set.3 @@ -1,16 +1,21 @@ -.TH std::bitset::set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::set \- std::bitset::set + .SH Synopsis - bitset& set(); \fB(1)\fP - bitset& set( size_t pos, bool value = true ); \fB(2)\fP + bitset& set(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++23) + bitset& set( std::size_t pos, bool value = true ); \fB(2)\fP (constexpr since C++23) - Sets all bits to true or to specified value. + Sets all bits to true or sets one bit to specified value. 1) Sets all bits to true. 2) Sets the bit at position pos to the value value. .SH Parameters - pos - the position of the bit to set + pos - the position (counting from 0, i.e. from least significant to most + significant) of the bit to set value - the value to set the bit to .SH Return value @@ -19,40 +24,49 @@ .SH Exceptions - 1) - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - 2) Throws std::out_of_range if pos does not correspond to a valid position within the bitset. .SH Example - + // Run this code - #include #include - + #include + #include + int main() { std::bitset<8> b; - for (size_t i = 1; i < b.size(); i += 2) { + std::cout << b << '\\n'; + std::cout << b.set() << '\\n'; + std::cout << b.reset() << '\\n'; + + for (std::size_t i = 1; i < b.size(); i += 2) b.set(i); - } + std::cout << b << '\\n'; } .SH Output: + 00000000 + 11111111 + 00000000 10101010 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 186 C++98 the type of value was int corrected to bool + .SH See also reset sets bits to false - \fI(public member function)\fP + \fI(public member function)\fP flip toggles the values of bits - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::size.3 b/man/std::bitset::size.3 index 5c01d39c5..f201fb893 100644 --- a/man/std::bitset::size.3 +++ b/man/std::bitset::size.3 @@ -1,11 +1,12 @@ -.TH std::bitset::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::size \- std::bitset::size + .SH Synopsis - std::size_t size() const; \fI(until C++11)\fP - constexpr std::size_t size(); \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr std::size_t size() const; \fI(since C++14)\fP + std::size_t size() const; (noexcept since C++11) + (constexpr since C++11) - Returns the number of bits that the bitset can hold. + Returns the number of bits that the bitset holds. .SH Parameters @@ -13,16 +14,26 @@ .SH Return value - number of bits that the bitset can hold, i.e. the template parameter N + number of bits that the bitset holds, i.e. the template parameter N. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::bitset<0x400>().size() << '\\n'; + } -.SH Exceptions +.SH Output: - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + 1024 .SH See also count returns the number of bits set to true - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::test.3 b/man/std::bitset::test.3 index 81c454cb3..04954dc00 100644 --- a/man/std::bitset::test.3 +++ b/man/std::bitset::test.3 @@ -1,15 +1,18 @@ -.TH std::bitset::test 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::test 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::test \- std::bitset::test + .SH Synopsis - bool test( size_t pos ) const; + bool test( std::size_t pos ) const; (constexpr since C++23) - Returns the value of the bit at the position pos. + Returns the value of the bit at the position pos (counting from 0). Unlike operator[], performs a bounds check and throws std::out_of_range if pos does not correspond to a valid position in the bitset. .SH Parameters - pos - position of the bit to return + pos - position of the bit to return (counting from 0) .SH Return value @@ -21,33 +24,52 @@ .SH Example - + // Run this code - #include + #include #include - + #include + #include + #include + int main() { std::bitset<10> b1("1111010000"); - - size_t idx = 0; - while (idx < b1.size() && !b1.test(idx)) { - ++idx; - } - - if (idx < b1.size()) { - std::cout << "lowest set bit at index " << idx << '\\n'; - } else { + + std::size_t idx = 0; + while (idx < b1.size() && !b1.test(idx)) + ++idx; + + assert(static_cast(idx) == std::countr_zero(b1.to_ulong())); + + if (idx < b1.size()) + std::cout << "The first set bit is at index " << idx << '\\n'; + else std::cout << "no set bits\\n"; + + try + { + std::bitset<0B10'1001'1010> bad; + if (bad.test(bad.size())) + std::cout << "Expect unexpected!\\n"; + } + catch (std::out_of_range const& ex) + { + std::cout << "Exception: " << ex.what() << '\\n'; } } -.SH Output: +.SH Possible output: - first set bit at index 4 + The first set bit is at index 4 + Exception: bitset::test: __position (which is 666) >= _Nb (which is 666) .SH See also - operator[] accesses specific bit - \fI(public member function)\fP + operator[] accesses specific bit + \fI(public member function)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP + has_single_bit checks if a number is an integral power of 2 + (C++20) \fI(function template)\fP diff --git a/man/std::bitset::to_string.3 b/man/std::bitset::to_string.3 index e371a273a..c1d968d8e 100644 --- a/man/std::bitset::to_string.3 +++ b/man/std::bitset::to_string.3 @@ -1,26 +1,56 @@ -.TH std::bitset::to_string 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::to_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::to_string \- std::bitset::to_string + .SH Synopsis - template< + template< class CharT, class Traits, class Allocator + > - class CharT, - class Traits, \fI(until C++11)\fP - class Alloc + std::basic_string \fI(until C++11)\fP + to_string( CharT zero = CharT('0'), - > std::basic_string to_string() const; + CharT one = CharT('1') ) const; template< class CharT = char, - class Traits = std::char_traits, \fI(since C++11)\fP - class Allocator = std::allocator - > std::basic_string + class Traits = std::char_traits, + class Allocator = std::allocator \fI(since C++11)\fP + > (constexpr since C++23) + std::basic_string + to_string( CharT zero = CharT('0'), + \fB(1)\fP + CharT one = CharT('1') ) const; + template< class CharT, class Traits > + + std::basic_string \fB(2)\fP \fI(until C++11)\fP + to_string( CharT zero = CharT('0'), + + CharT one = CharT('1') ) const; + template< class CharT > + + std::basic_string to_string( CharT zero = + CharT('0'), \fB(3)\fP \fI(until C++11)\fP - to_string(CharT zero = CharT(’0’), CharT one = CharT(’1’)) const; + CharT one = + CharT('1') ) const; + std::string to_string( char zero = '0', char one = \fB(4)\fP \fI(until C++11)\fP + '1' ) const; Converts the contents of the bitset to a string. Uses zero to represent bits with value of false and one to represent bits with value of true. The resulting string contains N characters with the first character corresponds to - the last (N-1th) bit and the last character corresponding to the first bit. + the last (N-1^th) bit and the last character corresponding to the first bit. + + All template type arguments need to be provided because function + templates cannot have default template arguments. Overloads (2-4) are + provided to simplify the invocations of to_string: + + 2) Uses the default allocator std::allocator. \fI(until C++11)\fP + 3) Uses the default character trait std::char_traits and the default + allocator std::allocator. + 4) Uses the default character type char, the default character trait + std::char_traits and the default allocator std::allocator. .SH Parameters @@ -29,18 +59,32 @@ .SH Return value - the converted string + 1) The converted string. + 2) to_string>(zero, one). + 3) to_string, std::allocator>(zero, one). + 4) to_string, std::allocator>(zero, one). + +.SH Exceptions + + May throw std::bad_alloc from the std::basic_string constructor. + +.SH Notes + + Since C++11, functions templates can have default template arguments. LWG issue 1113 + removed the helper overloads (2-4) and added the corresponding default template + arguments in \fB(1)\fP. .SH Example - + // Run this code - #include #include + #include + int main() { - std::bitset<8> b(42); + std::bitset<8> b{42}; std::cout << b.to_string() << '\\n' << b.to_string('*') << '\\n' << b.to_string('O', 'X') << '\\n'; @@ -52,9 +96,25 @@ **1*1*1* OOXOXOXO + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + zero and one bits were converted to + LWG 396 C++98 characters 0 added parameters to provide + and 1 (which do not correspond to '0' values for these characters + and '1') + LWG 434 C++98 all template arguments needed to be added overloads (2-4) + provided + overloads (2-4) did not have the + LWG 853 C++98 default also added + arguments added by LWG issue 396 + .SH See also to_ulong returns an unsigned long integer representation of the data - \fI(public member function)\fP + \fI(public member function)\fP to_ullong returns an unsigned long long integer representation of the data - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::bitset::to_ullong.3 b/man/std::bitset::to_ullong.3 index 054ad5e8b..a847a0bfd 100644 --- a/man/std::bitset::to_ullong.3 +++ b/man/std::bitset::to_ullong.3 @@ -1,6 +1,10 @@ -.TH std::bitset::to_ullong 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::to_ullong 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::to_ullong \- std::bitset::to_ullong + .SH Synopsis unsigned long long to_ullong() const \fI(since C++11)\fP + (constexpr since C++23) Converts the contents of the bitset to an unsigned long long integer. @@ -13,7 +17,7 @@ .SH Return value - the converted integer + The converted integer .SH Exceptions @@ -21,32 +25,44 @@ .SH Example - + // Run this code - #include #include + #include #include - + int main() { - std::bitset::digits> b( + std::bitset::digits> b + ( 0x123456789abcdef0LL ); - + std::cout << b << " " << std::hex << b.to_ullong() << '\\n'; b.flip(); std::cout << b << " " << b.to_ullong() << '\\n'; + + std::bitset::digits + 1> q{0}; + try + { + (~q).to_ullong(); // throws + } + catch (const std::overflow_error& ex) + { + std::cout << "ex: " << ex.what() << '\\n'; + } } .SH Output: 0001001000110100010101100111100010011010101111001101111011110000 123456789abcdef0 1110110111001011101010011000011101100101010000110010000100001111 edcba9876543210f + ex: _Base_bitset::_M_do_to_ullong .SH See also to_string returns a string representation of the data - \fI(public member function)\fP + \fI(public member function)\fP to_ulong returns an unsigned long integer representation of the data - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::bitset::to_ulong.3 b/man/std::bitset::to_ulong.3 index bf3c4f4ab..bcb89bf45 100644 --- a/man/std::bitset::to_ulong.3 +++ b/man/std::bitset::to_ulong.3 @@ -1,6 +1,9 @@ -.TH std::bitset::to_ulong 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bitset::to_ulong 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bitset::to_ulong \- std::bitset::to_ulong + .SH Synopsis - unsigned long to_ulong() const + unsigned long to_ulong() const (constexpr since C++23) Converts the contents of the bitset to an unsigned long integer. @@ -13,48 +16,65 @@ .SH Return value - the converted integer + The converted integer. .SH Exceptions - throws std::overflow_error if the value can not be represented in unsigned long. + Throws std::overflow_error if the value can not be represented in unsigned long. .SH Example - + // Run this code - #include #include - + #include + #include + int main() { - for (unsigned long i = 0; i < 10; ++i) { + for (unsigned long i = 0; i < 10; ++i) + { std::bitset<5> b(i); std::bitset<5> b_inverted = ~b; - std::cout << i << '\\t'; - std::cout << b << '\\t'; - std::cout << b_inverted << '\\t'; - std::cout << b_inverted.to_ulong() << '\\n'; + std::cout << i << '\\t' << b << '\\t' << b_inverted << '\\t' + << b_inverted.to_ulong() << '\\n'; + } + + std::cout << std::bitset<32>().to_string('-') << '\\n'; + + try + { + std::bitset<128> x(42); + std::cout << x.to_ulong() << '\\n'; + x.flip(); + std::cout << x.to_ulong() << '\\n'; // throws + } + catch (const std::overflow_error& ex) + { + std::cout << "ex: " << ex.what() << '\\n'; } } -.SH Output: +.SH Possible output: - 0 00000 11111 31 - 1 00001 11110 30 - 2 00010 11101 29 - 3 00011 11100 28 - 4 00100 11011 27 - 5 00101 11010 26 - 6 00110 11001 25 - 7 00111 11000 24 - 8 01000 10111 23 - 9 01001 10110 22 + 0 00000 11111 31 + 1 00001 11110 30 + 2 00010 11101 29 + 3 00011 11100 28 + 4 00100 11011 27 + 5 00101 11010 26 + 6 00110 11001 25 + 7 00111 11000 24 + 8 01000 10111 23 + 9 01001 10110 22 + -------------------------------- + 42 + ex: bitset to_ulong overflow error .SH See also to_string returns a string representation of the data - \fI(public member function)\fP + \fI(public member function)\fP to_ullong returns an unsigned long long integer representation of the data - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::boolalpha,std::noboolalpha.3 b/man/std::boolalpha,std::noboolalpha.3 index cc838d775..6e0730634 100644 --- a/man/std::boolalpha,std::noboolalpha.3 +++ b/man/std::boolalpha,std::noboolalpha.3 @@ -1,13 +1,16 @@ -.TH std::boolalpha,std::noboolalpha 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::boolalpha,std::noboolalpha 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::boolalpha,std::noboolalpha \- std::boolalpha,std::noboolalpha + .SH Synopsis Defined in header std::ios_base& boolalpha( std::ios_base& str ); \fB(1)\fP std::ios_base& noboolalpha( std::ios_base& str ); \fB(2)\fP 1) Enables the boolalpha flag in the stream str as if by calling - str.setf(std::ios_base::boolalpha) + str.setf(std::ios_base::boolalpha). 2) Disables the boolalpha flag in the stream str as if by calling - str.unsetf(std::ios_base::boolalpha) + str.unsetf(std::ios_base::boolalpha). std::boolalpha is an I/O manipulator, so it may be called with an expression such as out << std::boolalpha for any out of type std::basic_ostream or with an expression @@ -19,46 +22,53 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code - #include - #include #include + #include + int main() { // boolalpha output - std::cout << std::boolalpha + std::cout << "default true: " << true << '\\n' + << "default false: " << false << '\\n' + << std::boolalpha << "boolalpha true: " << true << '\\n' - << "boolalpha false: " << false << '\\n'; - std::cout << std::noboolalpha + << "boolalpha false: " << false << '\\n' + << std::noboolalpha << "noboolalpha true: " << true << '\\n' << "noboolalpha false: " << false << '\\n'; - // booalpha parse + + // boolalpha parse bool b1, b2; std::istringstream is("true false"); is >> std::boolalpha >> b1 >> b2; - std::cout << '\\"' << is.str() << "\\" parsed as " << b1 << ' ' << b2 << '\\n'; + + std::cout << '"' << is.str() << "\\" parsed as: " + << std::boolalpha << b1 << ' ' << b2 << '\\n'; } .SH Output: + default true: 1 + default false: 0 boolalpha true: true boolalpha false: false noboolalpha true: 1 noboolalpha false: 0 - "true false" parsed as 1 0 + "true false" parsed as: true false .SH See also resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP do_truename provides the string to use as the name of the boolean true and false - do_falsename \fI(virtual protected member function of std::numpunct)\fP + do_falsename \fI(virtual protected member function of std::numpunct)\fP \fB[virtual]\fP diff --git a/man/std::boyer_moore_horspool_searcher.3 b/man/std::boyer_moore_horspool_searcher.3 new file mode 100644 index 000000000..cbe97aeac --- /dev/null +++ b/man/std::boyer_moore_horspool_searcher.3 @@ -0,0 +1,129 @@ +.TH std::boyer_moore_horspool_searcher 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::boyer_moore_horspool_searcher \- std::boyer_moore_horspool_searcher + +.SH Synopsis + Defined in header + template< class RandomIt1, + + class Hash = std::hash::value_type>, \fI(since C++17)\fP + class BinaryPredicate = std::equal_to<> > + + class boyer_moore_horspool_searcher; + + A searcher suitable for use with the Searcher overload of std::search that + implements the Boyer-Moore-Horspool string searching algorithm. + + std::boyer_moore_horspool_searcher is CopyConstructible and CopyAssignable. + + RandomIt1 must meet the requirements of LegacyRandomAccessIterator. + +.SH Member functions + +std::boyer_moore_horspool_searcher::boyer_moore_horspool_searcher + + boyer_moore_horspool_searcher( RandomIt1 pat_first, + + RandomIt1 pat_last, + Hash hf = Hash(), + + BinaryPredicate pred = BinaryPredicate() ); + + Constructs a std::boyer_moore_horspool_searcher by storing copies of pat_first, + pat_last, hf, and pred, setting up any necessary internal data structures. + + The value type of RandomIt1 must be DefaultConstructible, CopyConstructible and + CopyAssignable. + + For any two values A and B of the type std::iterator_traits::value_type, + if pred(A, B) == true, then hf(A) == hf(B) shall be true. + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + hf - a callable object used to hash the elements of the string + pred - a callable object used to determine equality + +.SH Exceptions + + Any exceptions thrown by + + * the copy constructor of RandomIt1; + * the default constructor, copy constructor, or copy assignment operator of the + value type of RandomIt1; or + * the copy constructor or function call operator of BinaryPredicate or Hash. + + May also throw std::bad_alloc if additional memory required for internal data + structures cannot be allocated. + +std::boyer_moore_horspool_searcher::operator() + + template< class RandomIt2 > + std::pair operator()( RandomIt2 first, RandomIt2 last ) + const; + + The member function called by the Searcher overload of std::search to perform a + search with this searcher. RandomIt2 must meet the requirements of + LegacyRandomAccessIterator. + + RandomIt1 and RandomIt2 must have the same value type. + +.SH Parameters + + first, last - a pair of iterators designating the string to be examined + +.SH Return value + + If the pattern [pat_first, pat_last) is empty, returns std::make_pair(first, first). + + Otherwise, returns a pair of iterators to the first and one past last positions in + [first, last) where a subsequence that compares equal to [pat_first, pat_last) as + defined by pred is located, or std::make_pair(last, last) otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_boyer_moore_searcher 201603L \fI(C++17)\fP searchers + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::string_view in = + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed " + "do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + + const std::string_view needle{"pisci"}; + + auto it = std::search(in.begin(), in.end(), + std::boyer_moore_horspool_searcher( + needle.begin(), needle.end())); + if (it != in.end()) + std::cout << "The string " << std::quoted(needle) << " found at offset " + << it - in.begin() << '\\n'; + else + std::cout << "The string " << std::quoted(needle) << " not found\\n"; + } + +.SH Output: + + The string "pisci" found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + default_searcher standard C++ library search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP + boyer_moore_searcher Boyer-Moore search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::boyer_moore_searcher.3 b/man/std::boyer_moore_searcher.3 new file mode 100644 index 000000000..e24f604ab --- /dev/null +++ b/man/std::boyer_moore_searcher.3 @@ -0,0 +1,129 @@ +.TH std::boyer_moore_searcher 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::boyer_moore_searcher \- std::boyer_moore_searcher + +.SH Synopsis + Defined in header + template< class RandomIt1, + + class Hash = std::hash::value_type>, \fI(since C++17)\fP + class BinaryPredicate = std::equal_to<> > + + class boyer_moore_searcher; + + A searcher suitable for use with the Searcher overload of std::search that + implements the Boyer-Moore string searching algorithm. + + std::boyer_moore_searcher is CopyConstructible and CopyAssignable. + + RandomIt1 must meet the requirements of LegacyRandomAccessIterator. + +.SH Member functions + +std::boyer_moore_searcher::boyer_moore_searcher + + boyer_moore_searcher( RandomIt1 pat_first, + + RandomIt1 pat_last, + Hash hf = Hash(), + + BinaryPredicate pred = BinaryPredicate() ); + + Constructs a std::boyer_moore_searcher by storing copies of pat_first, pat_last, hf, + and pred, setting up any necessary internal data structures. + + The value type of RandomIt1 must be DefaultConstructible, CopyConstructible and + CopyAssignable. + + For any two values A and B of the type std::iterator_traits::value_type, + if pred(A, B) == true, then hf(A) == hf(B) shall be true. + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + hf - a callable object used to hash the elements of the string + pred - a callable object used to determine equality + +.SH Exceptions + + Any exceptions thrown by + + * the copy constructor of RandomIt1; + * the default constructor, copy constructor, and copy assignment operator of the + value type of RandomIt1; or + * the copy constructor and function call operator of BinaryPredicate or Hash. + + May also throw std::bad_alloc if additional memory required for internal data + structures cannot be allocated. + +std::boyer_moore_searcher::operator() + + template< class RandomIt2 > + std::pair operator()( RandomIt2 first, \fI(since C++17)\fP + RandomIt2 last ) const; + + The member function called by the Searcher overload of std::search to perform a + search with this searcher. RandomIt2 must meet the requirements of + LegacyRandomAccessIterator. + + RandomIt1 and RandomIt2 must have the same value type. + +.SH Parameters + + first, last - a pair of iterators designating the string to be examined + +.SH Return value + + If the pattern [pat_first, pat_last) is empty, returns std::make_pair(first, first). + + Otherwise, returns a pair of iterators to the first and one past last positions in + [first, last) where a subsequence that compares equal to [pat_first, pat_last) as + defined by pred is located, or std::make_pair(last, last) otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_boyer_moore_searcher 201603L \fI(C++17)\fP searchers + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::string_view haystack = + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed " + "do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + + const std::string_view needle{"pisci"}; + + if (const auto it = std::search(haystack.begin(), haystack.end(), + std::boyer_moore_searcher(needle.begin(), needle.end())); + it != haystack.end() + ) + std::cout << "The string " << std::quoted(needle) << " found at offset " + << it - haystack.begin() << '\\n'; + else + std::cout << "The string " << std::quoted(needle) << " not found\\n"; + } + +.SH Output: + + The string "pisci" found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + default_searcher standard C++ library search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP + boyer_moore_horspool_searcher Boyer-Moore-Horspool search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::breakpoint.3 b/man/std::breakpoint.3 new file mode 100644 index 000000000..971d838ee --- /dev/null +++ b/man/std::breakpoint.3 @@ -0,0 +1,59 @@ +.TH std::breakpoint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::breakpoint \- std::breakpoint + +.SH Synopsis + Defined in header + void breakpoint() noexcept; (since C++26) + + Unconditional breakpoint: attempts to temporarily halt the execution of the program + and transfer control to the debugger whether or not it's not possible to determine + if the debugger is present. + + Formally, the behavior of this function is completely implementation-defined. + +.SH Notes + + The intent of this function is allowing for runtime control of breakpoints beyond + what might be available from a debugger while not causing the program to exit. For + example, breaking when an infrequent non-critical condition is detected, allowing + programmatic control with complex runtime sensitive conditions, breaking on user + input to inspect context in interactive programs without needing to switch to the + debugger application, etc. + + This function standardizes many similar existing facilities: __builtin_debugtrap + from LLVM, __debugbreak from Win32 API, debugger_break from boost.test, + assert(false), _asm { int 3 } (MSVC) and asm("int3") (GCC/clang) for x86 targets, + etc. + + Feature-test macro Value Std Feature + __cpp_lib_debugging 202311L (C++26) Debugging support library + 202403L (C++26) Replaceable std::is_debugger_present + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_debugger_present checks whether a program is running under the control of a + (C++26) debugger + \fI(function)\fP + breakpoint_if_debugging calls std::breakpoint if std::is_debugger_present returns + (C++26) true + \fI(function)\fP + +.SH External links + + 1. armKEIL: __breakpoint intrinsic + 2. Portable Snippets: Debugging assertions and traps + 3. EASTL: EASTL_DEBUG_BREAK + 4. Catch2: CATCH_TRAP and CATCH_BREAK_INTO_DEBUGGER + 5. Unreal Engine: DebugBreak + 6. JUCE: JUCE_BREAK_IN_DEBUGGER + 7. Dear ImGui: IM_DEBUG_BREAK + 8. AWS C Common: aws_debug_break + +.SH Category: + * Todo no example diff --git a/man/std::breakpoint_if_debugging.3 b/man/std::breakpoint_if_debugging.3 new file mode 100644 index 000000000..f821bd624 --- /dev/null +++ b/man/std::breakpoint_if_debugging.3 @@ -0,0 +1,37 @@ +.TH std::breakpoint_if_debugging 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::breakpoint_if_debugging \- std::breakpoint_if_debugging + +.SH Synopsis + Defined in header + void breakpoint_if_debugging() noexcept; (since C++26) + + Conditional breakpoint: attempts to temporarily halt the execution of the program + and transfer control to the debugger if it were able to determine that the debugger + is present. Acts as a no-op otherwise. + + Formally, the behavior of this function is completely implementation-defined. + Equivalent to if (std::is_debugger_present()) + std::breakpoint();. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_debugging 202311L (C++26) Debugging support library + 202403L (C++26) Replaceable std::is_debugger_present + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_debugger_present checks whether a program is running under the control of a + (C++26) debugger + \fI(function)\fP + breakpoint pauses the running program when called + (C++26) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::bsearch.3 b/man/std::bsearch.3 index 0ff1a3b40..fde266713 100644 --- a/man/std::bsearch.3 +++ b/man/std::bsearch.3 @@ -1,20 +1,37 @@ -.TH std::bsearch 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::bsearch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::bsearch \- std::bsearch + .SH Synopsis Defined in header - void* bsearch( const void* key, const void* ptr, std::size_t count, std::size_t - size, - int (*comp)(const void*, const void*) ); - - Finds an element equal to element pointed to by key in a sorted array pointed to by - ptr. The array contains count elements of size bytes. The elements are compared - using function pointed to by comp. - - The behavior is undefined if the array is not already sorted in ascending order - according to the same criteria that comp uses. + void* bsearch( const void* key, const void* ptr, std::size_t + count, + + std::size_t size, /* c-compare-pred */* comp + ); \fB(1)\fP + void* bsearch( const void* key, const void* ptr, std::size_t + count, + + std::size_t size, /* compare-pred */* comp ); + extern "C" using /* c-compare-pred */ = int(const void*, + const void*); \fB(2)\fP (exposition only*) + extern "C++" using /* compare-pred */ = int(const void*, + const void*); + + Finds an element equal to element pointed to by key in an array pointed to by ptr. + The array contains count elements of size bytes each and must be partitioned with + respect to the object pointed to by key, that is, all the elements that compare less + than must appear before all the elements that compare equal to, and those must + appear before all the elements that compare greater than the key object. A fully + sorted array satisfies these requirements. The elements are compared using function + pointed to by comp. + + The behavior is undefined if the array is not already partitioned in ascending order + with respect to key, according to the same criterion that comp uses. If the array contains several elements that comp would indicate as equal to the - element searched for, then it is undefined which element the function will return as - the result. + element searched for, then it is unspecified which element the function will return + as the result. .SH Parameters @@ -23,74 +40,86 @@ count - number of element in the array size - size of each element in the array in bytes comparison function which returns a negative integer value if the first - argument is less than the second, + argument is less than the second, a positive integer value if the first + argument is greater than the second and zero if the arguments are + equivalent.key is passed as the first argument, an element from the array as + the second. - a positive integer value if the first argument is greater than the second - and zero if the arguments are equal. key is passed as the first argument, an - element from the array as the second. - comp - The signature of the comparison function should be equivalent to the - following: + The signature of the comparison function should be equivalent to the + comp - following: int cmp(const void *a, const void *b); - The function must not modify the objects passed to it. + The function must not modify the objects passed to it and must return + consistent results when called for the same objects, regardless of their + positions in the array. + - .SH Return value - Pointer to the found element or NULL if the element has not been found. + Pointer to the found element or null pointer if the element has not been found. + +.SH Notes + + Despite the name, neither C nor POSIX standards require this function to be + implemented using binary search or make any complexity guarantees. + + The two overloads provided by the C++ standard library are distinct because the + types of the parameter comp are distinct (language linkage is part of its type). .SH Example - + // Run this code + #include #include #include - - int compare(const void *ap, const void *bp) + + template + int compare(const void *a, const void *b) { - const int *a = (int *) ap; - const int *b = (int *) bp; - if(*a < *b) - return -1; - else if(*a > *b) - return 1; - else - return 0; + const auto &arg1 = *(static_cast(a)); + const auto &arg2 = *(static_cast(b)); + const auto cmp = arg1 <=> arg2; + return cmp < 0 ? -1 + : cmp > 0 ? +1 + : 0; } - - int main(int argc, char **argv) + + int main() { - const int ARR_SIZE = 8; - int arr[ARR_SIZE] = { 1, 2, 3, 4, 5, 6, 7, 8 }; - - int key1 = 4; - int *p1 = (int *) std::bsearch(&key1, arr, ARR_SIZE, sizeof(arr[0]), compare); - if(p1) - std::cout << "value " << key1 << " found at position " << (p1 - arr) << '\\n'; - else - std::cout << "value " << key1 << " not found\\n"; - - int key2 = 9; - int *p2 = (int *) std::bsearch(&key2, arr, ARR_SIZE, sizeof(arr[0]), compare); - if(p2) - std::cout << "value " << key2 << " found at position " << (p2 - arr) << '\\n'; - else - std::cout << "value " << key2 << " not found\\n"; + std::array arr{1, 2, 3, 4, 5, 6, 7, 8}; + + for (const int key : {4, 8, 9}) + { + const int* p = static_cast( + std::bsearch(&key, + arr.data(), + arr.size(), + sizeof(decltype(arr)::value_type), + compare)); + + std::cout << "value " << key; + if (p) + std::cout << " found at position " << (p - arr.data()) << '\\n' + else + std::cout << " not found\\n"; + } } .SH Output: value 4 found at position 3 + value 8 found at position 7 value 9 not found .SH See also qsort sorts a range of elements with unspecified type - \fI(function)\fP + \fI(function)\fP equal_range returns range of elements matching a specific key - \fI(function template)\fP + \fI(function template)\fP C documentation for bsearch diff --git a/man/std::btowc.3 b/man/std::btowc.3 index 451d82bd7..e8243e571 100644 --- a/man/std::btowc.3 +++ b/man/std::btowc.3 @@ -1,4 +1,7 @@ -.TH std::btowc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::btowc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::btowc \- std::btowc + .SH Synopsis Defined in header std::wint_t btowc( int c ); @@ -22,24 +25,24 @@ .SH Example - + // Run this code - #include - #include #include - + #include + #include + void try_widen(char c) { std::wint_t w = std::btowc(c); - if(w != WEOF) + if (w != WEOF) std::cout << "The single-byte character " << +(unsigned char)c << " widens to " << +w << '\\n'; else std::cout << "The single-byte character " << +(unsigned char)c << " failed to widen\\n"; } - + int main() { std::setlocale(LC_ALL, "lt_LT.iso88594"); @@ -47,7 +50,7 @@ try_widen('A'); try_widen('\\xdf'); // German letter ß (U+00df) in ISO-8859-4 try_widen('\\xf9'); // Lithuanian letter ų (U+0173) in ISO-8859-4 - + std::setlocale(LC_ALL, "lt_LT.utf8"); std::cout << "In Lithuanian UTF-8 locale:\\n"; try_widen('A'); @@ -55,7 +58,7 @@ try_widen('\\xf9'); } -.SH Output: +.SH Possible output: In Lithuanian ISO-8859-4 locale: The single-byte character 0x41 widens to 0x41 @@ -69,8 +72,8 @@ .SH See also wctob narrows a wide character to a single-byte narrow character, if possible - \fI(function)\fP - do_widen converts a character or characters from char to charT - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + \fI(function)\fP + do_widen converts a character or characters from char to CharT + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP C documentation for btowc diff --git a/man/std::byte.3 b/man/std::byte.3 new file mode 100644 index 000000000..35618e3e2 --- /dev/null +++ b/man/std::byte.3 @@ -0,0 +1,164 @@ +.TH std::byte 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::byte \- std::byte + +.SH Synopsis + Defined in header + enum class byte : unsigned char {}; \fI(since C++17)\fP + + std::byte is a distinct type that implements the concept of byte as specified in the + C++ language definition. + + Like unsigned char, it can be used to access raw memory occupied by other objects + (object representation), but unlike unsigned char, it is not a character type and is + not an arithmetic type. std::byte models a mere collection of bits, supporting only + bitshift operations with an integer, and bitwise and comparison operations with + another std::byte. + +.SH Non-member functions + +std::to_integer + + template \fI(since C++17)\fP + constexpr IntegerType to_integer( std::byte b ) noexcept; + + Equivalent to: return IntegerType(b); This overload participates in overload + resolution only if std::is_integral_v is true. + +std::operator<<=,operator>>= + + template + constexpr std::byte& operator<<=( std::byte& b, IntegerType shift \fB(1)\fP \fI(since C++17)\fP + ) noexcept; + template + constexpr std::byte& operator>>=( std::byte& b, IntegerType shift \fB(2)\fP \fI(since C++17)\fP + ) noexcept; + + 1) Equivalent to: return b = b << shift; This overload participates in overload + resolution only if std::is_integral_v is true. + 2) Equivalent to: return b = b >> shift; + + This overload participates in overload resolution only if + std::is_integral_v is true. + +std::operator<<,operator>> + + template + constexpr std::byte operator<<( std::byte b, IntegerType shift ) \fB(1)\fP \fI(since C++17)\fP + noexcept; + template + constexpr std::byte operator>>( std::byte b, IntegerType shift ) \fB(2)\fP \fI(since C++17)\fP + noexcept; + + 1) Equivalent to: return std::byte(static_cast(b) << shift); This + overload participates in overload resolution only if std::is_integral_v + is true. + 2) Equivalent to: return std::byte(static_cast(b) >> shift); + + This overload participates in overload resolution only if + std::is_integral_v is true. + +std::operator|=,operator&=,operator^= + + constexpr std::byte& operator|=( std::byte& l, std::byte r ) \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr std::byte& operator&=( std::byte& l, std::byte r ) \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr std::byte& operator^=( std::byte& l, std::byte r ) \fB(3)\fP \fI(since C++17)\fP + noexcept; + + 1) Equivalent to: return l = l | r;. + 2) Equivalent to: return l = l & r;. + 3) Equivalent to: return l = l ^ r;. + +std::operator|,operator&,operator^,operator~ + + constexpr std::byte operator|( std::byte l, std::byte r ) \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr std::byte operator&( std::byte l, std::byte r ) \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr std::byte operator^( std::byte l, std::byte r ) \fB(3)\fP \fI(since C++17)\fP + noexcept; + constexpr std::byte operator~( std::byte b ) noexcept; \fB(4)\fP \fI(since C++17)\fP + + 1) Equivalent to: return std::byte(static_cast(l) | + static_cast(r));. + 2) Equivalent to: return std::byte(static_cast(l) & + static_cast(r));. + 3) Equivalent to: return std::byte(static_cast(l) ^ + static_cast(r));. + 4) Equivalent to: return std::byte(~static_cast(b)); + +.SH Notes + + A numeric value n can be converted to a byte value using std::byte{n}, due to C++17 + relaxed enum class initialization rules. + + A byte can be converted to a numeric value (such as to produce an integer hash of an + object) the usual way with an explicit conversion or alternatively with + std::to_integer. + + Feature-test macro Value Std Feature + __cpp_lib_byte 201603L \fI(C++17)\fP std::byte + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + std::ostream& operator<<(std::ostream& os, std::byte b) + { + return os << std::bitset<8>(std::to_integer(b)); + } + + int main() + { + // std::byte y = 1; // Error: cannot convert int to byte. + std::byte y{1}; // OK + + // if (y == 13) {} // Error: cannot be compared. + if (y == std::byte{13}) {} // OK, bytes are comparable + + int arr[]{1, 2, 3}; + // int c = a[y]; // Error: array subscript is not an integer + [[maybe_unused]] int i = arr[std::to_integer(y)]; // OK + [[maybe_unused]] int j = arr[std::to_underlying(y)]; // OK + + std::byte b{42}; + std::cout << "1. " << b << '\\n'; + + // b *= 2; // Error: b is not of arithmetic type + b <<= 1; + std::cout << "2. " << b << '\\n'; + + b >>= 1; + std::cout << "3. " << b << '\\n'; + + std::cout << "4. " << (b << 1) << '\\n'; + std::cout << "5. " << (b >> 1) << '\\n'; + + b |= std::byte{0b11110000}; + std::cout << "6. " << b << '\\n'; + + b &= std::byte{0b11110000}; + std::cout << "7. " << b << '\\n'; + + b ^= std::byte{0b11111111}; + std::cout << "8. " << b << '\\n'; + } + +.SH Output: + + 1. 00101010 + 2. 01010100 + 3. 00101010 + 4. 01010100 + 5. 00010101 + 6. 11111010 + 7. 11110000 + 8. 00001111 diff --git a/man/std::byteswap.3 b/man/std::byteswap.3 new file mode 100644 index 000000000..76b8a8d29 --- /dev/null +++ b/man/std::byteswap.3 @@ -0,0 +1,105 @@ +.TH std::byteswap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::byteswap \- std::byteswap + +.SH Synopsis + Defined in header + template< class T > (since C++23) + constexpr T byteswap( T n ) noexcept; + + Reverses the bytes in the given integer value n. + + std::byteswap participates in overload resolution only if T satisfies integral, + i.e., T is an integer type. The program is ill-formed if T has padding bits. + +.SH Parameters + + n - integer value + +.SH Return value + + An integer value of type T whose object representation comprises the bytes of that + of n in reversed order. + +.SH Notes + + This function is useful for processing data of different endianness. + + Feature-test macro Value Std Feature + __cpp_lib_byteswap 202110L (C++23) std::byteswap + +.SH Possible implementation + + template + constexpr T byteswap(T value) noexcept + { + static_assert(std::has_unique_object_representations_v, + "T may not have padding bits"); + auto value_representation = std::bit_cast>(value); + std::ranges::reverse(value_representation); + return std::bit_cast(value_representation); + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void dump(T v, char term = '\\n') + { + std::cout << std::hex << std::uppercase << std::setfill('0') + << std::setw(sizeof(T) * 2) << v << " : "; + for (std::size_t i{}; i != sizeof(T); ++i, v >>= 8) + std::cout << std::setw(2) << static_cast(T(0xFF) & v) << ' '; + std::cout << std::dec << term; + } + + int main() + { + static_assert(std::byteswap('a') == 'a'); + + std::cout << "byteswap for U16:\\n"; + constexpr auto x = std::uint16_t(0xCAFE); + dump(x); + dump(std::byteswap(x)); + + std::cout << "\\nbyteswap for U32:\\n"; + constexpr auto y = std::uint32_t(0xDEADBEEFu); + dump(y); + dump(std::byteswap(y)); + + std::cout << "\\nbyteswap for U64:\\n"; + constexpr auto z = std::uint64_t{0x0123456789ABCDEFull}; + dump(z); + dump(std::byteswap(z)); + } + +.SH Possible output: + + byteswap for U16: + CAFE : FE CA + FECA : CA FE + + byteswap for U32: + DEADBEEF : EF BE AD DE + EFBEADDE : DE AD BE EF + + byteswap for U64: + 0123456789ABCDEF : EF CD AB 89 67 45 23 01 + EFCDAB8967452301 : 01 23 45 67 89 AB CD EF + +.SH See also + + endian indicates the endianness of scalar types + (C++20) \fI(enum)\fP + rotl computes the result of bitwise left-rotation + (C++20) \fI(function template)\fP + rotr computes the result of bitwise right-rotation + (C++20) \fI(function template)\fP diff --git a/man/std::c16rtomb.3 b/man/std::c16rtomb.3 index 23ab8fb40..cd7f64c50 100644 --- a/man/std::c16rtomb.3 +++ b/man/std::c16rtomb.3 @@ -1,26 +1,34 @@ -.TH std::c16rtomb 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::c16rtomb 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::c16rtomb \- std::c16rtomb + .SH Synopsis Defined in header std::size_t c16rtomb( char* s, char16_t c16, std::mbstate_t* ps ); \fI(since C++11)\fP - Converts a 16-bit wide character to narrow multibyte character. + Converts a single code point from variable-length 16-bit character representation + (typically, UTF-16) to a narrow multibyte character representation. - If s is not a null pointer, the function determines the number of bytes necessary to - store the multibyte character representation of c16 (including any shift sequences), - and stores the multibyte character representation in the character array whose first - element is pointed to by s. At most MB_CUR_MAX bytes can be written by this - function. + If s is not a null pointer and c16 is the last 16-bit code unit in a valid + variable-length encoding of a code point, the function determines the number of + bytes necessary to store the multibyte character representation of that code point + (including any shift sequences, and taking into account the current multibyte + conversion state *ps), and stores the multibyte character representation in the + character array whose first element is pointed to by s, updating *ps as necessary. + At most MB_CUR_MAX bytes can be written by this function. If s is a null pointer, the call is equivalent to std::c16rtomb(buf, u'\\0', ps) for some internal buffer buf. + If c16 is not the final code unit in a 16-bit representation of a wide character, it + does not write to the array pointed to by s, only *ps is updated. + If c16 is the null wide character u'\\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state. - If the macro __STDC_UTF_16__ is defined, the 16-bit encoding used by this function - is UTF-16, otherwise it is implementation-defined. In any case, the multibyte - encoding used by this function is specified by the currently active C locale. + The multibyte encoding used by this function is specified by the currently active C + locale. .SH Parameters @@ -38,11 +46,66 @@ On failure (if c16 is not a valid 16-bit character), returns -1, stores EILSEQ in errno, and leaves *ps in unspecified state. +.SH Notes + + The C++ standard defers to the C standard for the semantics of this function. In C11 + as published, unlike std::mbrtoc16, which converts variable-width multibyte (such as + UTF-8) to variable-width 16-bit (such as UTF-16) encoding, this function can only + convert single-unit 16-bit encoding, meaning it cannot convert UTF-16 to UTF-8 + despite that being the original intent of this function. This was corrected by the + post-C11 defect report DR488. + +.SH Example + + Note: this example assumes the fix for the defect report 488 is applied. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::u16string_view strv = u"zß水🍌"; // or z\\u00df\\u6c34\\U0001F34C + std::cout << "Processing " << strv.size() << " UTF-16 code units: [ "; + for (char16_t c : strv) + std::cout << std::showbase << std::hex << static_cast(c) << ' '; + std::cout << "]\\n"; + + std::mbstate_t state{}; + char out[MB_LEN_MAX]{}; + for (char16_t c : strv) + { + std::size_t rc = std::c16rtomb(out, c, &state); + std::cout << static_cast(c) << " converted to [ "; + if (rc != (std::size_t) - 1) + for (unsigned char c8 : std::string_view{out, rc}) + std::cout << +c8 << ' '; + std::cout << "]\\n"; + } + } + +.SH Output: + + Processing 5 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c ] + 0x7a converted to [ 0x7a ] + 0xdf converted to [ 0xc3 0x9f ] + 0x6c34 converted to [ 0xe6 0xb0 0xb4 ] + 0xd83c converted to [ ] + 0xdf4c converted to [ 0xf0 0x9f 0x8d 0x8c ] + .SH See also - mbrtoc16 generate the next 16-bit wide character from a narrow multibyte string - \fI(C++11)\fP \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + mbrtoc16 converts a narrow multibyte character to UTF-16 encoding + \fI(C++11)\fP \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for c16rtomb diff --git a/man/std::c32rtomb.3 b/man/std::c32rtomb.3 index f5daf240e..e43eff36a 100644 --- a/man/std::c32rtomb.3 +++ b/man/std::c32rtomb.3 @@ -1,15 +1,19 @@ -.TH std::c32rtomb 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::c32rtomb 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::c32rtomb \- std::c32rtomb + .SH Synopsis Defined in header std::size_t c32rtomb( char* s, char32_t c32, std::mbstate_t* ps ); \fI(since C++11)\fP - Converts a 32-bit wide character to its narrow multibyte representation. + Converts a UTF-32 character to its narrow multibyte representation. If s is not a null pointer, the function determines the number of bytes necessary to - store the multibyte character representation of c32 (including any shift sequences), - and stores the multibyte character representation in the character array whose first - element is pointed to by s. At most MB_CUR_MAX bytes can be written by this - function. + store the multibyte character representation of c32 (including any shift sequences, + and taking into account the current multibyte conversion state *ps), and stores the + multibyte character representation in the character array whose first element is + pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written + by this function. If s is a null pointer, the call is equivalent to std::c32rtomb(buf, U'\\0', ps) for some internal buffer buf. @@ -18,9 +22,8 @@ shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state. - If the macro __STDC_UTF_32__ is defined, the 32-bit encoding used by this function - is UTF-32, otherwise it is implementation-defined. In any case, the multibyte - encoding used by this function is specified by the currently active C locale. + The multibyte encoding used by this function is specified by the currently active C + locale. .SH Parameters @@ -39,11 +42,54 @@ On failure (if c32 is not a valid 32-bit character), returns -1, stores EILSEQ in errno, and leaves *ps in unspecified state. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::u32string_view strv = U"zß水🍌"; // or z\\u00df\\u6c34\\U0001F34C + std::cout << "Processing " << strv.size() << " UTF-32 code units: [ "; + for (char32_t c : strv) + std::cout << std::showbase << std::hex << static_cast(c) << ' '; + std::cout << "]\\n"; + + std::mbstate_t state{}; + char out[MB_LEN_MAX]{}; + for (char32_t c : strv) + { + std::size_t rc = std::c32rtomb(out, c, &state); + std::cout << static_cast(c) << " converted to [ "; + if (rc != (std::size_t) - 1) + for (unsigned char c8 : std::string_view{out, rc}) + std::cout << +c8 << ' '; + std::cout << "]\\n"; + } + } + +.SH Output: + + Processing 4 UTF-32 code units: [ 0x7a 0xdf 0x6c34 0x1f34c ] + 0x7a converted to [ 0x7a ] + 0xdf converted to [ 0xc3 0x9f ] + 0x6c34 converted to [ 0xe6 0xb0 0xb4 ] + 0x1f34c converted to [ 0xf0 0x9f 0x8d 0x8c ] + .SH See also - mbrtoc32 generate the next 32-bit wide character from a narrow multibyte string - \fI(C++11)\fP \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + mbrtoc32 converts a narrow multibyte character to UTF-32 encoding + \fI(C++11)\fP \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for c32rtomb diff --git a/man/std::c8rtomb.3 b/man/std::c8rtomb.3 new file mode 100644 index 000000000..1be0cc668 --- /dev/null +++ b/man/std::c8rtomb.3 @@ -0,0 +1,68 @@ +.TH std::c8rtomb 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::c8rtomb \- std::c8rtomb + +.SH Synopsis + Defined in header + std::size_t c8rtomb( char* s, char8_t c8, std::mbstate_t* ps ); \fI(since C++20)\fP + + Converts a single code point from UTF-8 to a narrow multibyte character + representation. + + If s is not a null pointer and c8 is the last code unit in a valid UTF-8 encoding of + a code point, the function determines the number of bytes necessary to store the + multibyte character representation of that code point (including any shift + sequences, and taking into account the current multibyte conversion state *ps), and + stores the multibyte character representation in the character array whose first + element is pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can + be written by this function. + + If c8 is not the final UTF-8 code unit in a representation of a code point, the + function does not write to the array pointed to by s, only *ps is updated. + + If s is a null pointer, the call is equivalent to std::c8rtomb(buf, u8'\\0', ps) for + some internal buffer buf. + + If c8 is the null character u8'\\0', a null byte is stored, preceded by any shift + sequence necessary to restore the initial shift state and the conversion state + parameter *ps is updated to represent the initial shift state. + + The multibyte encoding used by this function is specified by the currently active C + locale. + +.SH Parameters + + s - pointer to narrow character array where the multibyte character will be stored + c8 - the UTF-8 code unit to convert + ps - pointer to the conversion state object used when interpreting the multibyte + string + +.SH Return value + + The number of bytes stored in the array object (including any shift sequences). This + may be zero when c8 is not the final code unit in the UTF-8 representation of a code + point. + + If c8 is invalid (does not contribute to a sequence of char8_t corresponding to a + valid multibyte character), the value of the macro EILSEQ is stored in errno, + static_cast(-1) is returned, and the conversion state is unspecified. + +.SH Notes + + Calls to c8rtomb with a null pointer argument for s may introduce a data race with + other calls to c8rtomb with a null pointer argument for s. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + mbrtoc8 converts a narrow multibyte character to UTF-8 encoding + (C++20) \fI(function)\fP + C documentation for + c8rtomb + +.SH Category: + * Todo no example diff --git a/man/std::call_once.3 b/man/std::call_once.3 index cf529144b..d831e72b2 100644 --- a/man/std::call_once.3 +++ b/man/std::call_once.3 @@ -1,25 +1,41 @@ -.TH std::call_once 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::call_once 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::call_once \- std::call_once + .SH Synopsis Defined in header template< class Callable, class... Args > \fI(since C++11)\fP void call_once( std::once_flag& flag, Callable&& f, Args&&... args ); - Executes the Callable object f exactly once, even if called from several threads. + Executes the Callable object f exactly once, even if called concurrently from + several threads. + +.SH In detail: - Each group of call_once invocations that receives the same std::once_flag object - will meet the following requirements: + * If, by the time std::call_once is called, flag indicates that f was already + called, std::call_once returns right away (such a call to std::call_once is + known as passive). + * Otherwise, std::call_once calls INVOKE(std::forward(f), + std::forward(args)...). Unlike the std::thread constructor or std::async, + the arguments are not moved or copied because they do not need to be transferred + to another thread of execution (such a call to std::call_once is known as + active). - * Exactly one execution of exactly one of the functions (passed as f to the - invocations in the group) is performed. It is undefined which function will be - selected for execution. The selected function runs in the same thread as the - call_once invocation it was passed to. + * If that invocation throws an exception, it is propagated to the caller of + std::call_once, and flag is not flipped so that another call will be attempted + (such a call to std::call_once is known as exceptional ). + * If that invocation returns normally (such a call to std::call_once is known as + returning), flag is flipped, and all other calls to std::call_once with the same + flag are guaranteed to be passive. - * No invocation in the group returns before the abovementioned execution of the - selected function is completed successfully, that is, doesn't exit via an - exception. + All active calls on the same flag form a single total order consisting of zero or + more exceptional calls, followed by one returning call. The end of each active call + synchronizes-with the next active call in that order. - * If the selected function exits via exception, it is propagated to the caller. - Another function is then selected and executed. + The return from the returning call synchronizes-with the returns from all passive + calls on the same flag: this means that all concurrent calls to std::call_once are + guaranteed to observe any side-effects made by the active call, with no additional + synchronization. .SH Parameters @@ -33,83 +49,72 @@ .SH Exceptions - * std::system_error if any condition prevents calls to call_once from executing as - specified - * any exception thrown by f + * std::system_error if any condition prevents calls to std::call_once from + executing as specified. + * Any exception thrown by f. -.SH Example +.SH Notes - -// Run this code + If concurrent calls to std::call_once pass different functions f, it is unspecified + which f will be called. The selected function runs in the same thread as the + std::call_once invocation it was passed to. - #include - #include - #include - - std::once_flag flag; - - void do_once() - { - std::call_once(flag, [](){ std::cout << "Called once" << std::endl; }); - } - - int main() - { - std::thread t1(do_once); - std::thread t2(do_once); - std::thread t3(do_once); - std::thread t4(do_once); - - t1.join(); - t2.join(); - t3.join(); - t4.join(); - } + Initialization of function-local statics is guaranteed to occur only once even when + called from multiple threads, and may be more efficient than the equivalent code + using std::call_once. -.SH Output: - - Called once + The POSIX equivalent of this function is pthread_once. .SH Example - + // Run this code #include - #include #include - - std::once_flag flag; - - inline void may_throw_function(bool do_throw) + #include + + std::once_flag flag1, flag2; + + void simple_do_once() { - // only one instance of this function can be run simultaneously - if (do_throw) { - std::cout << "throw\\n"; // this message may be printed from 0 to 3 times - // if function exits via exception, another function selected - throw std::exception(); - } - - std::cout << "once\\n"; // printed exactly once, it's guaranteed that - // there are no messages after it + std::call_once(flag1, [](){ std::cout << "Simple example: called once\\n"; }); } - - inline void do_once(bool do_throw) + + void may_throw_function(bool do_throw) { - try { - std::call_once(flag, may_throw_function, do_throw); - } - catch (...) { - } + if (do_throw) + { + std::cout << "Throw: call_once will retry\\n"; // this may appear more than once + throw std::exception(); + } + std::cout << "Did not throw, call_once will not attempt again\\n"; // guaranteed once } - + + void do_once(bool do_throw) + { + try + { + std::call_once(flag2, may_throw_function, do_throw); + } + catch (...) {} + } + int main() { + std::thread st1(simple_do_once); + std::thread st2(simple_do_once); + std::thread st3(simple_do_once); + std::thread st4(simple_do_once); + st1.join(); + st2.join(); + st3.join(); + st4.join(); + std::thread t1(do_once, true); std::thread t2(do_once, true); std::thread t3(do_once, false); std::thread t4(do_once, true); - t1.join(); t2.join(); t3.join(); @@ -118,11 +123,28 @@ .SH Possible output: - throw - throw - once + Simple example: called once + Throw: call_once will retry + Throw: call_once will retry + Throw: call_once will retry + Did not throw, call_once will not attempt again + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::invalid_argument would be thrown if f + LWG 2080 C++11 is invalid, removed this error + but the scenario where f is invalidated is condition + not specified + LWG 2442 C++11 the arguments were copied and/or moved no copying/moving is + before invocation performed .SH See also once_flag helper object to ensure that call_once invokes the function only once - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP + C documentation for + call_once diff --git a/man/std::calloc.3 b/man/std::calloc.3 index 9e5067095..fba09d63f 100644 --- a/man/std::calloc.3 +++ b/man/std::calloc.3 @@ -1,16 +1,33 @@ -.TH std::calloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::calloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::calloc \- std::calloc + .SH Synopsis Defined in header void* calloc( std::size_t num, std::size_t size ); - Allocates memory for an array of num objects of size size and zero-initializes it. + Allocates memory for an array of num objects of size size, initializes it to all + bits zero (implicitly creating objects in the destination area). If allocation succeeds, returns a pointer to the lowest (first) byte in the allocated memory block that is suitably aligned for any object type. If size is zero, the behavior is implementation defined (null pointer may be returned, or some non-null pointer may be returned that may not be used to access - storage) + storage). + + The following functions are required to be thread-safe: + + * The library versions of operator new and operator delete + * User replacement versions of global operator new and operator + delete + * std::calloc, std::malloc, std::realloc \fI(since C++11)\fP + , std::aligned_alloc + \fI(since C++17)\fP, std::free + + Calls to these functions that allocate or deallocate a particular unit + of storage occur in a single total order, and each such deallocation + call happens-before the next allocation (if any) in this order. .SH Parameters @@ -19,24 +36,62 @@ .SH Return value - Pointer to the beginning of newly allocated memory or NULL if error has occurred. - The pointer must be deallocated with free(). + On success, returns the pointer to the beginning of newly allocated memory. To avoid + a memory leak, the returned pointer must be deallocated with std::free() or + std::realloc(). + + On failure, returns a null pointer. .SH Notes Due to the alignment requirements, the number of allocated bytes is not necessarily - equal to num*size. + equal to num * size. + + Initialization to all bits zero does not guarantee that a floating-point or a + pointer would be initialized to 0.0 and the null pointer value, respectively + (although that is true on all common platforms). + + Originally (in C89), support for zero size was added to accommodate code such as + + OBJ *p = calloc(0, sizeof(OBJ)); // "zero-length" placeholder + ... + while \fB(1)\fP + { + p = realloc(p, c * sizeof(OBJ)); // reallocations until size settles + ... // code that may change c or break out of loop + } .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + int* p1 = (int*)std::calloc(4, sizeof(int)); // allocate and zero out an array of 4 int + int* p2 = (int*)std::calloc(1, sizeof(int[4])); // same, naming the array type directly + int* p3 = (int*)std::calloc(4, sizeof *p3); // same, without repeating the type name + + if (p2) + for (int n = 0; n < 4; ++n) // print the array + std::cout << "p2[" << n << "] == " << p2[n] << '\\n'; + + std::free(p1); + std::free(p2); + std::free(p3); + } + +.SH Output: + + p2[0] == 0 + p2[1] == 0 + p2[2] == 0 + p2[3] == 0 .SH See also C documentation for calloc - -.SH Category: - - * Todo no example diff --git a/man/std::cauchy_distribution.3 b/man/std::cauchy_distribution.3 index ae41a47b0..e3d5ff12d 100644 --- a/man/std::cauchy_distribution.3 +++ b/man/std::cauchy_distribution.3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution \- std::cauchy_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -7,7 +10,7 @@ Produces random numbers according to a Cauchy distribution (also called Lorentz distribution): - f(x; a,b) = ⎛ + \\({\\small f(x;a,b)={(b\\pi{[1+{(\\frac{x-a}{b})}^{2}]} })}^{-1}\\)f(x; a,b) = ⎛ ⎜ ⎝bπ ⎡ ⎢ @@ -27,48 +30,151 @@ ⎟ ⎠-1 + std::cauchy_distribution satisfies all requirements of RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. + .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics a returns the distribution parameters - b \fI(public member function)\fP + b \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - This section is incomplete - Reason: no example -.SH External links - - Weisstein, Eric W. "Cauchy Distribution." From MathWorld--A Wolfram Web Resource. - Cauchy Distribution. From Wikipedia. +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + void draw_vbars(Seq&& s, const bool DrawMinMax = true) + { + static_assert(0 < Height and 0 < BarWidth and 0 <= Padding and 0 <= Offset); + + auto cout_n = [](auto&& v, int n = 1) + { + while (n-- > 0) + std::cout << v; + }; + + const auto [min, max] = std::minmax_element(std::cbegin(s), std::cend(s)); + + std::vector qr; + for (typedef decltype(*std::cbegin(s)) V; V e : s) + qr.push_back(std::div(std::lerp(V(0), 8 * Height, + (e - *min) / (*max - *min)), 8)); + + for (auto h{Height}; h-- > 0; cout_n('\\n')) + { + cout_n(' ', Offset); + + for (auto dv : qr) + { + const auto q{dv.quot}, r{dv.rem}; + unsigned char d[]{0xe2, 0x96, 0x88, 0}; // Full Block: '█' + q < h ? d[0] = ' ', d[1] = 0 : q == h ? d[2] -= (7 - r) : 0; + cout_n(d, BarWidth), cout_n(' ', Padding); + } + + if (DrawMinMax && Height > 1) + Height - 1 == h ? std::cout << "┬ " << *max: + h ? std::cout << "│ " + : std::cout << "┴ " << *min; + } + } + + int main() + { + std::random_device rd{}; + std::mt19937 gen{rd()}; + + auto cauchy = [&gen](const float x0, const float 𝛾) + { + std::cauchy_distribution d{x0 /* a */, 𝛾 /* b */}; + + const int norm = 1'00'00; + const float cutoff = 0.005f; + + std::map hist{}; + for (int n = 0; n != norm; ++n) + ++hist[std::round(d(gen))]; + + std::vector bars; + std::vector indices; + for (auto const& [n, p] : hist) + if (float x = p * (1.0 / norm); cutoff < x) + { + bars.push_back(x); + indices.push_back(n); + } + + std::cout << "x₀ = " << x0 << ", 𝛾 = " << 𝛾 << ":\\n"; + draw_vbars<4,3>(bars); + for (int n : indices) + std::cout << std::setw(2) << n << " "; + std::cout << "\\n\\n"; + }; + + cauchy(/* x₀ = */ -2.0f, /* 𝛾 = */ 0.50f); + cauchy(/* x₀ = */ +0.0f, /* 𝛾 = */ 1.25f); + } + +.SH Possible output: + + x₀ = -2, 𝛾 = 0.5: + ███ ┬ 0.5006 + ███ │ + ▂▂▂ ███ ▁▁▁ │ + ▁▁▁ ▁▁▁ ▁▁▁ ▃▃▃ ███ ███ ███ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0076 + -7 -6 -5 -4 -3 -2 -1 0 1 2 3 + + x₀ = 0, 𝛾 = 1.25: + ███ ┬ 0.2539 + ▅▅▅ ███ ▃▃▃ │ + ▁▁▁ ███ ███ ███ ▁▁▁ │ + ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▃▃▃ ▅▅▅ ███ ███ ███ ███ ███ ▅▅▅ ▃▃▃ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0058 + -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 9 -.SH Category: +.SH External links - * Todo no example + Weisstein, Eric W. "Cauchy Distribution." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::cauchy_distribution::a,b.3 b/man/std::cauchy_distribution::a,b.3 index 45ae3dd8c..f182be47f 100644 --- a/man/std::cauchy_distribution::a,b.3 +++ b/man/std::cauchy_distribution::a,b.3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution::a,b 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::a,b 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::a,b \- std::cauchy_distribution::a,b + .SH Synopsis RealType a() const; \fB(1)\fP \fI(since C++11)\fP RealType b() const; \fB(2)\fP \fI(since C++11)\fP @@ -21,10 +24,10 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP .SH External links - * Scale parameter. From Wikipedia. - * Location parameter. From Wikipedia. + 1. Scale parameter. From Wikipedia. + 2. Location parameter. From Wikipedia. diff --git a/man/std::cauchy_distribution::cauchy_distribution.3 b/man/std::cauchy_distribution::cauchy_distribution.3 index 419ad7540..a27044e73 100644 --- a/man/std::cauchy_distribution::cauchy_distribution.3 +++ b/man/std::cauchy_distribution::cauchy_distribution.3 @@ -1,15 +1,27 @@ -.TH std::cauchy_distribution::cauchy_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::cauchy_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::cauchy_distribution \- std::cauchy_distribution::cauchy_distribution + .SH Synopsis - explicit cauchy_distribution( RealType a = 0.0, RealType b = 1.0 \fB(1)\fP \fI(since C++11)\fP - ); - explicit cauchy_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + cauchy_distribution() : cauchy_distribution(0.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit cauchy_distribution( RealType a, RealType b = 1.0 ); \fB(2)\fP \fI(since C++11)\fP + explicit cauchy_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses a and b as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses a and b as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters a - the a distribution parameter (location) b - the b distribution parameter (scale) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::cauchy_distribution::max.3 b/man/std::cauchy_distribution::max.3 index fe71b998e..8cd9580dc 100644 --- a/man/std::cauchy_distribution::max.3 +++ b/man/std::cauchy_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::max \- std::cauchy_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::cauchy_distribution::min.3 b/man/std::cauchy_distribution::min.3 index 5219ff413..c0c2884f3 100644 --- a/man/std::cauchy_distribution::min.3 +++ b/man/std::cauchy_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::min \- std::cauchy_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::cauchy_distribution::operator().3 b/man/std::cauchy_distribution::operator().3 index be22fd562..88ebd2274 100644 --- a/man/std::cauchy_distribution::operator().3 +++ b/man/std::cauchy_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::operator() \- std::cauchy_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::cauchy_distribution::param.3 b/man/std::cauchy_distribution::param.3 index 989eae039..5cc5c6379 100644 --- a/man/std::cauchy_distribution::param.3 +++ b/man/std::cauchy_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::param \- std::cauchy_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::cauchy_distribution::reset.3 b/man/std::cauchy_distribution::reset.3 index bd854a067..d0e2fc34d 100644 --- a/man/std::cauchy_distribution::reset.3 +++ b/man/std::cauchy_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::cauchy_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cauchy_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cauchy_distribution::reset \- std::cauchy_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::cbrt,std::cbrtf,std::cbrtl.3 b/man/std::cbrt,std::cbrtf,std::cbrtl.3 new file mode 100644 index 000000000..ab290f11a --- /dev/null +++ b/man/std::cbrt,std::cbrtf,std::cbrtl.3 @@ -0,0 +1,139 @@ +.TH std::cbrt,std::cbrtf,std::cbrtl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cbrt,std::cbrtf,std::cbrtl \- std::cbrt,std::cbrtf,std::cbrtl + +.SH Synopsis + Defined in header + float cbrt ( float num ); + + double cbrt ( double num ); (until C++23) + + long double cbrt ( long double num ); + /* floating-point-type */ (since C++23) + cbrt ( /* floating-point-type */ num ); (constexpr since C++26) + float cbrtf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double cbrtl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double cbrt ( Integer num ); + + 1-3) Computes the cube root of num. + The library provides overloads of std::cbrt for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the cube root of num (\\(\\small{\\sqrt[3]{num} }\\) + 3 + √ + num), is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0 or ±∞, it is returned, unchanged. + * if the argument is NaN, NaN is returned. + +.SH Notes + + std::cbrt(num) is not equivalent to std::pow(num, 1.0 / 3) because the rational + number \\(\\small{\\frac1{3} }\\) + + 1 + 3 + + is typically not equal to 1.0 / 3 and std::pow cannot raise a negative base to a + fractional exponent. Moreover, std::cbrt(num) usually gives more accurate results + than std::pow(num, 1.0 / 3) (see example). + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::cbrt(num) has the same effect as std::cbrt(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout + << "Normal use:\\n" + << "cbrt(729) = " << std::cbrt(729) << '\\n' + << "cbrt(-0.125) = " << std::cbrt(-0.125) << '\\n' + << "Special values:\\n" + << "cbrt(-0) = " << std::cbrt(-0.0) << '\\n' + << "cbrt(+inf) = " << std::cbrt(INFINITY) << '\\n' + << "Accuracy and comparison with `pow`:\\n" + << std::setprecision(std::numeric_limits::max_digits10) + << "cbrt(343) = " << std::cbrt(343) << '\\n' + << "pow(343,1.0/3) = " << std::pow(343, 1.0 / 3) << '\\n' + << "cbrt(-343) = " << std::cbrt(-343) << '\\n' + << "pow(-343,1.0/3) = " << std::pow(-343, 1.0 / 3) << '\\n'; + } + +.SH Possible output: + + Normal use: + cbrt(729) = 9 + cbrt(-0.125) = -0.5 + Special values: + cbrt(-0) = -0 + cbrt(+inf) = inf + Accuracy and comparison with `pow`: + cbrt(343) = 7 + pow(343,1.0/3) = 6.9999999999999991 + cbrt(-343) = -7 + pow(-343,1.0/3) = -nan + +.SH See also + + pow + powf raises a number to the given power (\\(\\small{x^y}\\)x^y) + powl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sqrt computes square root (\\(\\small{\\sqrt{x}}\\) + sqrtf √ + sqrtl x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + computes square root of the sum of the squares of two + or three + \fI(since C++17)\fP given numbers (\\(\\scriptsize{\\sqrt{x^2+y^2}}\\) + √ + hypot x2 + hypotf +y2 + hypotl ) + \fI(C++11)\fP , (\\(\\scriptsize{\\sqrt{x^2+y^2+z^2}}\\) + \fI(C++11)\fP √ + \fI(C++11)\fP x2 + +y2 + +z2 + ) + \fI(since C++17)\fP + \fI(function)\fP + C documentation for + cbrt diff --git a/man/std::cbrt.3 b/man/std::cbrt.3 deleted file mode 100644 index 75bf49205..000000000 --- a/man/std::cbrt.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH std::cbrt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float cbrt( float arg ); \fI(since C++11)\fP - double cbrt( double arg ); \fI(since C++11)\fP - long double cbrt( long double arg ); \fI(since C++11)\fP - double cbrt( Integral arg ); \fI(since C++11)\fP - - Computes cubic root of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Cubic root of arg. - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::cout << std::fixed; - std::cout << std::cbrt(27.0) << '\\n'; - std::cout << std::cbrt(1.0) << '\\n'; - std::cout << std::cbrt(125.0) << '\\n'; - std::cout << std::cbrt(-0.125) << '\\n'; - } - -.SH Output: - - 3.000000 - 1.000000 - 5.000000 - -0.500000 - -.SH See also - - computes square root ( - sqrt √ - x) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - C documentation for - cbrt diff --git a/man/std::ceil,std::ceilf,std::ceill.3 b/man/std::ceil,std::ceilf,std::ceill.3 new file mode 100644 index 000000000..70831b319 --- /dev/null +++ b/man/std::ceil,std::ceilf,std::ceill.3 @@ -0,0 +1,170 @@ +.TH std::ceil,std::ceilf,std::ceill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ceil,std::ceilf,std::ceill \- std::ceil,std::ceilf,std::ceill + +.SH Synopsis + Defined in header + float ceil ( float num ); + + double ceil ( double num ); (until C++23) + + long double ceil ( long double num ); + constexpr /* floating-point-type */ (since C++23) + ceil ( /* floating-point-type */ num ); + float ceilf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double ceill( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double ceil ( Integer num ); + + 1-3) Computes the least integer value not less than num. + The library provides overloads of std::ceil for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating point or integer value + +.SH Return value + + If no errors occur, the smallest integer value not less than num, that is ⌈num⌉, is + returned. + +.SH Return value + math-ceil.svg + num + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * The current rounding mode has no effect. + * If num is ±∞, it is returned unmodified. + * If num is ±0, it is returned, unmodified. + * If num is NaN, NaN is returned. + +.SH Notes + + FE_INEXACT may be (but is not required to be) raised when rounding a non-integer + finite value. + + The largest representable floating-point values are exact integers in all standard + floating-point formats, so this function never overflows on its own; however the + result may overflow any integer type (including std::intmax_t), when stored in an + integer variable. It is for this reason that the return type is floating-point not + integral. + + This function (for double argument) behaves as if (except for the freedom to not + raise FE_INEXACT) implemented by the following code: + + #include + #include + #pragma STDC FENV_ACCESS ON + + double ceil(double x) + { + int save_round = std::fegetround(); + std::fesetround(FE_UPWARD); + double result = std::rint(x); // or std::nearbyint + std::fesetround(save_round); + return result; + } + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::ceil(num) has the same effect as std::ceil(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::fixed + << "ceil(+2.4) = " << std::ceil(+2.4) << '\\n' + << "ceil(-2.4) = " << std::ceil(-2.4) << '\\n' + << "ceil(-0.0) = " << std::ceil(-0.0) << '\\n' + << "ceil(-Inf) = " << std::ceil(-INFINITY) << '\\n'; + } + +.SH Output: + + ceil(+2.4) = 3.000000 + ceil(-2.4) = -2.000000 + ceil(-0.0) = -0.000000 + ceil(-Inf) = -inf + +.SH See also + + floor + floorf nearest integer not greater than the given value + floorl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + trunc + truncf + truncl nearest integer not greater in magnitude than the given value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + round + roundf + roundl + lround + lroundf + lroundl + llround + llroundf + llroundl nearest integer, rounding away from zero in halfway cases + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + nearbyint + nearbyintf + nearbyintl nearest integer using current rounding mode + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + rint + rintf + rintl + lrint + lrintf + lrintl + llrint + llrintf nearest integer using current rounding mode with + llrintl exception if the result differs + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + ceil + +.SH External links + + Fast ceiling of an integer division — StackOverflow diff --git a/man/std::ceil.3 b/man/std::ceil.3 deleted file mode 100644 index b32047a51..000000000 --- a/man/std::ceil.3 +++ /dev/null @@ -1,79 +0,0 @@ -.TH std::ceil 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float ceil( float arg ); - double ceil( double arg ); - long double ceil( long double arg ); - double ceil( Integral arg ); \fI(since C++11)\fP - - Computes nearest integer not less than arg. - -.SH Parameters - - arg - floating point value - -.SH Return value - - Nearest integer not less than arg - -.SH Return value - math-ceil.svg - Argument - -.SH Notes - - If the argument is infinity (positive or negative) or zero (positive or negative), - the return value is the same as the argument. - - The largest representable floating-point values are exact integers in all standard - floating-point formats, so this function never overflows. - - This function may, but is not required to, raise FE_INEXACT floating-point - exceptions for non-integer arguments. - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::cout << std::fixed; - std::cout << std::ceil(12.0) << '\\n'; - std::cout << std::ceil(12.1) << '\\n'; - std::cout << std::ceil(12.5) << '\\n'; - std::cout << std::ceil(12.9) << '\\n'; - std::cout << std::ceil(13.0) << '\\n'; - } - -.SH Output: - - 12.000000 - 13.000000 - 13.000000 - 13.000000 - 13.000000 - -.SH See also - - floor nearest integer not greater than the given value - \fI(function)\fP - trunc nearest integer not greater in magnitude than the given value - \fI(C++11)\fP \fI(function)\fP - round - lround - llround nearest integer, rounding away from zero in halfway cases - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP - rint - lrint nearest integer using current rounding mode with - llrint exception if the result differs - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP - nearbyint nearest integer using current rounding mode - \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::cerr,std::wcerr.3 b/man/std::cerr,std::wcerr.3 index 67d9c1929..a1aba7c42 100644 --- a/man/std::cerr,std::wcerr.3 +++ b/man/std::cerr,std::wcerr.3 @@ -1,4 +1,7 @@ -.TH std::cerr,std::wcerr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cerr,std::wcerr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cerr,std::wcerr \- std::cerr,std::wcerr + .SH Synopsis Defined in header extern std::ostream cerr; \fB(1)\fP @@ -10,57 +13,79 @@ These objects are guaranteed to be initialized during or before the first time an object of type std::ios_base::Init is constructed and are available for use in the - constructors and destructors of static objects (as long as is included). + constructors and destructors of static objects with ordered initialization (as long + as is included before the object is defined). - Unless sync_with_stdio(false) has been issued, it is safe to concurrently access - these objects from multiple threads for both formatted and unformatted output. + Unless std::ios_base::sync_with_stdio(false) has been issued, it is safe to + concurrently access these objects from multiple threads for both formatted and + unformatted output. - Once initialized, (std::cerr.flags() & unitbuf) != 0 (same for wcerr) meaning that - any output sent to these stream objects is immediately flushed to the OS (via + Once initialized, (std::cerr.flags() & unitbuf) != 0 (same for std::wcerr) meaning + that any output sent to these stream objects is immediately flushed to the OS (via std::basic_ostream::sentry's destructor). - In addition, std::cerr.tie() returns &std::cout (same for wcerr and wcout), meaning - that any output operation on std::cerr first executes std::cout.flush() (via - std::basic_ostream::sentry's constructor) \fI(since C++11)\fP + In addition, std::cerr.tie() returns &std::cout (same for std::wcerr and + std::wcout), meaning that any output operation on std::cerr first executes + std::cout.flush() (via std::basic_ostream::sentry's constructor). + +.SH Notes + + The 'c' in the name refers to "character" (stroustrup.com FAQ); cerr means + "character error (stream)" and wcerr means "wide character error (stream)". .SH Example - output to stderr via cerr flushes out the pending output on cout, while output to - stderr via clog does not + Output to stderr via std::cerr flushes out the pending output on std::cout, while + output to stderr via std::clog does not. + - // Run this code - #include - #include #include + #include + #include + using namespace std::chrono_literals; + void f() { std::cout << "Output from thread..."; - std::this_thread::sleep_for(std::chrono::seconds(2)); + std::this_thread::sleep_for(2s); std::cout << "...thread calls flush()" << std::endl; } - + int main() { - std::thread t1(f); - std::this_thread::sleep_for(std::chrono::seconds(1)); + std::jthread t1{f}; + std::this_thread::sleep_for(1000ms); std::clog << "This output from main is not tie()'d to cout\\n"; std::cerr << "This output is tie()'d to cout\\n"; - t1.join(); } -.SH Output: +.SH Possible output: This output from main is not tie()'d to cout Output from thread...This output is tie()'d to cout ...thread calls flush() + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::cerr.tie() and they return &std::cout and + LWG 455 C++98 std::wcerr.tie() returned null &std::wcout respectively + pointers + .SH See also - Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP - clog writes to the standard C error stream stderr - wclog (global object) - cout writes to the standard C output stream stdout - wcout (global object) + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + clog writes to the standard C error stream stderr + wclog (global object) + cout writes to the standard C output stream stdout + wcout (global object) + stdin expression of type FILE* associated with the input stream + stdout expression of type FILE* associated with the output stream + stderr expression of type FILE* associated with the error output stream + (macro constant) diff --git a/man/std::char_traits.3 b/man/std::char_traits.3 index 91be05b54..acf42c8ba 100644 --- a/man/std::char_traits.3 +++ b/man/std::char_traits.3 @@ -1,4 +1,7 @@ -.TH std::char_traits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::char_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits \- std::char_traits + .SH Synopsis Defined in header template< @@ -11,115 +14,152 @@ string operations for a given character type. The defined operation set is such that generic algorithms almost always can be implemented in terms of it. It is thus possible to use such algorithms with almost any possible character or string type, - just by supplying customized char_traits class. + just by supplying a customized char_traits class. The char_traits class template serves as a basis for explicit instantiations. The - user can provide a specialization for any custom character types. Several - specializations are defined for the standard character types. The values of the - member typedefs are as follows. + user can provide a specialization for any custom character types. Several explicit + specializations are provided for the standard character types (see below), other + specializations are not required to satisfy the requirements of CharTraits. + +.SH Specializations - Instantiation char_type int_type off_type pos_type state_type -char_traits char int std::streamoff std::streampos std::mbstate_t -char_traits wchar_t std::wint_t std::wstreamoff std::wstreampos std::mbstate_t -char_traits char16_t std::int_least16_t std::streamoff std::u16streampos std::mbstate_t -\fI(C++11)\fP -char_traits char32_t std::int_least32_t std::streamoff std::u32streampos std::mbstate_t -\fI(C++11)\fP + The standard library provides the following standard specializations: - The char_traits class template fulfills all requirements of Traits concept. + Defined in header + std::char_traits the standard character traits of char + std::char_traits the standard character traits of wchar_t + std::char_traits (C++20) the standard character traits of char8_t + std::char_traits \fI(C++11)\fP the standard character traits of char16_t + std::char_traits \fI(C++11)\fP the standard character traits of char32_t - This section is incomplete - Reason: simplify the description, emphasize that char_traits can be user defined + All these specializations satisfy the requirements of CharTraits. .SH Member types - Type Definition - char_type CharT - int_type an integer type that can hold all values of char_type plus EOF - off_type implementation-defined - pos_type implementation-defined - state_type implementation-defined + The standard specializations define the following member types required by + CharTraits: + + CharT Member type + char_type int_type off_type pos_type state_type +char char int std::streampos +wchar_t wchar_t std::wint_t std::wstreampos +char8_t char8_t unsigned int std::streamoff std::u8streampos std::mbstate_t + char16_t char16_t std::uint_least16_t std::u16streampos +char32_t char32_t std::uint_least32_t std::u32streampos + + On top of that, the standard specializations also define the member \fI(since C++20)\fP + type comparison_category as std::strong_ordering. .SH Member functions + The standard specializations define the following static member functions required + by CharTraits: + assign assigns a character - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP eq compares two characters - lt \fI(public static member function)\fP + lt \fI(public static member function)\fP \fB[static]\fP move moves one character sequence onto another - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP copy copies a character sequence - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP compare lexicographically compares two character sequences - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP length returns the length of a character sequence - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP find finds a character in a character sequence - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP to_char_type converts int_type to equivalent char_type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP to_int_type converts char_type to equivalent int_type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP eq_int_type compares two int_type values - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP eof returns an eof value - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP not_eof checks whether a character is eof value - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP + +.SH Notes + + CharTraits does not require defining the types and functions listed above as direct + members, it only requires types like X::type and expressions like X::func(args) are + valid and have the required semantics. Users-defined character traits can be derived + from other character traits classes and only override some of their members, see the + example below. .SH Example - User-defined character traits may be used to provide case-insensitive comparison + User-defined character traits may be used to provide case-insensitive comparison: + - // Run this code - #include - #include #include - - struct ci_char_traits : public std::char_traits { - static bool eq(char c1, char c2) { - return std::toupper(c1) == std::toupper(c2); - } - static bool ne(char c1, char c2) { - return std::toupper(c1) != std::toupper(c2); - } - static bool lt(char c1, char c2) { - return std::toupper(c1) < std::toupper(c2); + #include + #include + #include + + struct ci_char_traits : public std::char_traits + { + static char to_upper(char ch) + { + return std::toupper((unsigned char) ch); } - static int compare(const char* s1, const char* s2, size_t n) { - while ( n-- != 0 ) { - if ( std::toupper(*s1) < std::toupper(*s2) ) return -1; - if ( std::toupper(*s1) > std::toupper(*s2) ) return 1; - ++s1; ++s2; + + static bool eq(char c1, char c2) + { + return to_upper(c1) == to_upper(c2); + } + + static bool lt(char c1, char c2) + { + return to_upper(c1) < to_upper(c2); + } + + static int compare(const char* s1, const char* s2, std::size_t n) + { + while (n-- != 0) + { + if (to_upper(*s1) < to_upper(*s2)) + return -1; + if (to_upper(*s1) > to_upper(*s2)) + return 1; + ++s1; + ++s2; } return 0; } - static const char* find(const char* s, int n, char a) { - auto const ua (std::toupper(a)); - while ( n-- != 0 ) + + static const char* find(const char* s, std::size_t n, char a) + { + const auto ua{to_upper(a)}; + while (n-- != 0) { - if (std::toupper(*s) == ua) + if (to_upper(*s) == ua) return s; s++; } return nullptr; } }; - - typedef std::basic_string ci_string; - - std::ostream& operator<<(std::ostream& os, const ci_string& str) { - return os.write(str.data(), str.size()); + + template + constexpr std::basic_string_view + traits_cast(const std::basic_string_view src) noexcept + { + return {src.data(), src.size()}; } - + int main() { - ci_string s1 = "Hello"; - ci_string s2 = "heLLo"; - if (s1 == s2) + using namespace std::literals; + + constexpr auto s1 = "Hello"sv; + constexpr auto s2 = "heLLo"sv; + + if (traits_cast(s1) == traits_cast(s2)) std::cout << s1 << " and " << s2 << " are equal\\n"; } @@ -129,9 +169,15 @@ char_traits char32_t std::int_least32_t std::streamoff std::u32strea .SH See also - basic_string stores and manipulates sequences of characters - \fI(class template)\fP - -.SH Category: - - * Todo with reason + basic_string stores and manipulates sequences of characters + \fI(class template)\fP + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP + wraps a given abstract device (std::basic_streambuf) + basic_istream and provides high-level input interface + \fI(class template)\fP + wraps a given abstract device (std::basic_streambuf) + basic_ostream and provides high-level output interface + \fI(class template)\fP + basic_streambuf abstracts a raw device + \fI(class template)\fP diff --git a/man/std::char_traits::assign,std::char_traits::assign,.3 b/man/std::char_traits::assign,std::char_traits::assign,.3 new file mode 100644 index 000000000..8b9339b0e --- /dev/null +++ b/man/std::char_traits::assign,std::char_traits::assign,.3 @@ -0,0 +1,34 @@ +.TH std::char_traits::assign,std::char_traits::assign, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::assign,std::char_traits::assign, \- std::char_traits::assign,std::char_traits::assign, + +.SH Synopsis + std::char_traits::assign + + static void assign( char_type& c1, const char_type& c2 \fB(1)\fP (noexcept since C++11) + ); (constexpr since C++17) + static char_type* assign( char_type* ptr, std::size_t \fB(2)\fP (constexpr since C++20) + count, char_type c2 ); + + 1) Assigns c2 to c1, behaves identically to c1 = c2. + 2) Assigns c2 to each character in count characters in the character sequence + pointed to by ptr. + + See CharTraits for the general requirements on character traits for X::assign. + +.SH Parameters + + c1 - character to assign to + c2 - character value to assign + ptr - pointer to a character sequence to assign to + count - the length of the character sequence + +.SH Return value + + 1) \fI(none)\fP + 2) ptr + +.SH Complexity + + 1) Constant. + 2) Linear in count. diff --git a/man/std::char_traits::assign.3 b/man/std::char_traits::assign.3 deleted file mode 100644 index 4bba17d7e..000000000 --- a/man/std::char_traits::assign.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::char_traits::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static void assign( char_type& r, const char_type& a ); \fB(1)\fP - static char_type* assign( char_type* p, std::size_t count, char_type a ); \fB(2)\fP - - Assigns a character. - - 1) Assigns character a to character r. - 2) Assigns character a to each character in count characters in the character - sequence pointed to by p. - -.SH Parameters - - a - character value to assign - r - character to assign to - p - pointer to a character sequence to assign to - count - the length of the character sequence - -.SH Return value - - 1) \fI(none)\fP - 2) p - -.SH Exceptions - - 1) - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - 2) \fI(none)\fP - -.SH Complexity - - 1) Constant. - 2) Linear in count diff --git a/man/std::char_traits::compare,std::char_traits::compare,.3 b/man/std::char_traits::compare,std::char_traits::compare,.3 new file mode 100644 index 000000000..b7525a545 --- /dev/null +++ b/man/std::char_traits::compare,std::char_traits::compare,.3 @@ -0,0 +1,34 @@ +.TH std::char_traits::compare,std::char_traits::compare, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::compare,std::char_traits::compare, \- std::char_traits::compare,std::char_traits::compare, + +.SH Synopsis + std::char_traits::compare + + static int compare( const char_type* s1, const char_type* + s2, (constexpr since C++17) + std::size_t count ); + + Compares the first count characters of the character strings s1 and s2. The + comparison is done lexicographically. + + If count is zero, strings are considered equal. + + See CharTraits for the general requirements on character traits for X::compare. + +.SH Parameters + + s1, s2 - pointers to character strings to compare + count - the number of characters to compare from each character string + +.SH Return value + + Negative value if s1 is less than s2. + + 0 if s1 is equal to s2. + + Positive value if s1 is greater than s2. + +.SH Complexity + + Linear in count. diff --git a/man/std::char_traits::compare.3 b/man/std::char_traits::compare.3 deleted file mode 100644 index c9dfacd1a..000000000 --- a/man/std::char_traits::compare.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH std::char_traits::compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static int compare( const char_type* s1, const char_type* s2, std::size_t count ); - - Compares the first count characters of the character strings s1 and s2. The - comparison is done lexicographically. - - If count is zero, strings are considered equal. - -.SH Parameters - - s1, s2 - pointers to character strings to compare - count - the number of characters to compare from each character string - -.SH Return value - - Negative value if s1 is less than s2. - - 0 if s1 is equal to s2. - - Positive value if s1 is greater than s2. - -.SH Exceptions - - \fI(none)\fP - -.SH Complexity - - Linear in count. diff --git a/man/std::char_traits::copy,std::char_traits::copy,.3 b/man/std::char_traits::copy,std::char_traits::copy,.3 new file mode 100644 index 000000000..a275c95e9 --- /dev/null +++ b/man/std::char_traits::copy,std::char_traits::copy,.3 @@ -0,0 +1,40 @@ +.TH std::char_traits::copy,std::char_traits::copy, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::copy,std::char_traits::copy, \- std::char_traits::copy,std::char_traits::copy, + +.SH Synopsis + std::char_traits::copy + + static char_type* + copy( char_type* dest, const char_type* src, (constexpr since C++20) + std::size_t count ); + + Copies count characters from the character string pointed to by src to the character + string pointed to by dest. + + If [dest, dest + count) and [src, src + count) overlap, the behavior is undefined. + + See CharTraits for the general requirements on character traits for X::copy. + +.SH Parameters + + dest - pointer to a character string to copy to + src - pointer to a character string to copy from + count - the number of characters to copy + +.SH Return value + + dest + +.SH Exceptions + + Throws nothing. + +.SH Complexity + + Linear in count. + +.SH See also + + assign assigns a character + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::char_traits::copy.3 b/man/std::char_traits::copy.3 deleted file mode 100644 index 9a9b5b0fb..000000000 --- a/man/std::char_traits::copy.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH std::char_traits::copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static char_type* copy( char_type* dest, const char_type* src, std::size_t count - ); - - Copies count character from character string pointed to by src to character string - pointed to by dest. - - The behavior is undefined if copied character ranges overlap, i.e. src is in [dest, - dest + count). - -.SH Parameters - - dest - pointer to a character string to copy to - src - pointer to a character string to copy from - count - the number of characters to copy - -.SH Return value - - dest - -.SH Exceptions - - \fI(none)\fP - -.SH Complexity - - Linear. diff --git a/man/std::char_traits::eof,std::char_traits::eof,.3 b/man/std::char_traits::eof,std::char_traits::eof,.3 new file mode 100644 index 000000000..925474343 --- /dev/null +++ b/man/std::char_traits::eof,std::char_traits::eof,.3 @@ -0,0 +1,38 @@ +.TH std::char_traits::eof,std::char_traits::eof, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::eof,std::char_traits::eof, \- std::char_traits::eof,std::char_traits::eof, + +.SH Synopsis + std::char_traits::eof + + static int_type eof(); (constexpr since C++11) + (noexcept since C++11) + + Returns a value not equivalent to any valid value of type char_type. + + See CharTraits for the general requirements on character traits for X::eof. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + char_type eof() + char EOF + wchar_t WEOF + char8_t an implementation-defined constant that + cannot appear as a valid UTF-8 code unit + char16_t an implementation-defined constant that + cannot appear as a valid UTF-16 code unit + char32_t an implementation-defined constant that + cannot appear as a Unicode code point + +.SH Complexity + + Constant. + +.SH See also + + not_eof checks whether a character is eof value + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::char_traits::eof.3 b/man/std::char_traits::eof.3 deleted file mode 100644 index 7dc0907e8..000000000 --- a/man/std::char_traits::eof.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::char_traits::eof 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static int_type eof(); \fI(until C++11)\fP - static constexpr int_type eof(); \fI(since C++11)\fP - - Returns a value not equivalent to any value of type char_type. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - A value not equivalent to any value of type char_type. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. - -.SH See also - - not_eof checks whether a character is eof value - \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::char_traits::eq,std::char_traits::lt.3 b/man/std::char_traits::eq,std::char_traits::lt.3 deleted file mode 100644 index 3e5e9bb24..000000000 --- a/man/std::char_traits::eq,std::char_traits::lt.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH std::char_traits::eq,std::char_traits::lt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static bool eq( char_type a, char_type b ); \fI(until C++11)\fP - static constexpr bool eq( char_type a, char_type \fI(since C++11)\fP - b ); \fB(1)\fP - static bool lt( char_type a, char_type b ); \fI(until C++11)\fP - static constexpr bool lt( char_type a, char_type \fB(2)\fP \fI(since C++11)\fP - b ); - - Compares two characters. - - 1) Compares a and b for equality. - 2) Compares a and b in such a way that they are totally ordered. - - For the char specialization, eq and lt are defined identically to the \fI(since C++11)\fP - built-in operators == and < for type unsigned char (not char). - -.SH Parameters - - a, b - character values to compare - -.SH Return value - - 1) true if a and b are equal, false otherwise. - 2) true if a is less than b, false otherwise. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. diff --git a/man/std::char_traits::eq_int_type,std::char_traits::eq_int_type,.3 b/man/std::char_traits::eq_int_type,std::char_traits::eq_int_type,.3 new file mode 100644 index 000000000..fe13f7c5a --- /dev/null +++ b/man/std::char_traits::eq_int_type,std::char_traits::eq_int_type,.3 @@ -0,0 +1,25 @@ +.TH std::char_traits::eq_int_type,std::char_traits::eq_int_type, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::eq_int_type,std::char_traits::eq_int_type, \- std::char_traits::eq_int_type,std::char_traits::eq_int_type, + +.SH Synopsis + std::char_traits::eq_int_type + + static bool eq_int_type( int_type c1, int_type c2 ); (constexpr since C++11) + (noexcept since C++11) + + Checks whether two values of type int_type are equal. + + See CharTraits for the general requirements on character traits for X::eq_int_type. + +.SH Parameters + + c1, c2 - values to compare + +.SH Return value + + true if c1 is equal to c2, false otherwise. + +.SH Complexity + + Constant. diff --git a/man/std::char_traits::eq_int_type.3 b/man/std::char_traits::eq_int_type.3 deleted file mode 100644 index 11ef5fc50..000000000 --- a/man/std::char_traits::eq_int_type.3 +++ /dev/null @@ -1,25 +0,0 @@ -.TH std::char_traits::eq_int_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static bool eq_int_type( int_type c1, int_type c2 ); \fI(until C++11)\fP - static constexpr bool eq_int_type( int_type c1, int_type c2 ); \fI(since C++11)\fP - - Checks whether two values of type int_type are equal. - -.SH Parameters - - c1, c2 - values to compare - -.SH Return value - - true if c1 is equal to c2, false otherwise. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. diff --git a/man/std::char_traits::find,std::char_traits::find,.3 b/man/std::char_traits::find,std::char_traits::find,.3 new file mode 100644 index 000000000..406eef025 --- /dev/null +++ b/man/std::char_traits::find,std::char_traits::find,.3 @@ -0,0 +1,30 @@ +.TH std::char_traits::find,std::char_traits::find, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::find,std::char_traits::find, \- std::char_traits::find,std::char_traits::find, + +.SH Synopsis + std::char_traits::find + + static const char_type* + find( const char_type* ptr, std::size_t count, const (constexpr since C++17) + char_type& ch ); + + Searches for character ch within the first count characters of the sequence pointed + to by ptr. + + See CharTraits for the general requirements on character traits for X::find. + +.SH Parameters + + ptr - pointer to a character string to search + count - the number of characters to analyze + ch - the character to search for + +.SH Return value + + A pointer to the first character in the range specified by [ptr, ptr + count) that + compares equal to ch, or a null pointer if not found. + +.SH Complexity + + Linear in count. diff --git a/man/std::char_traits::find.3 b/man/std::char_traits::find.3 deleted file mode 100644 index 337291d38..000000000 --- a/man/std::char_traits::find.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::char_traits::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static const char_type* find( const char_type* p, std::size_t count, const - char_type& ch ); - - Searches for character ch within the first count characters of the sequence pointed - to by p. - -.SH Parameters - - p - pointer to a character string to search - count - the number of characters to analyze - ch - the character to search for - -.SH Return value - - A pointer to the first character in the range specified by [p, p + count) that - compares equal to ch, or NULL if not found. - -.SH Exceptions - - \fI(none)\fP - -.SH Complexity - - Linear in count. diff --git a/man/std::char_traits::length,std::char_traits::length,.3 b/man/std::char_traits::length,std::char_traits::length,.3 new file mode 100644 index 000000000..a72f50850 --- /dev/null +++ b/man/std::char_traits::length,std::char_traits::length,.3 @@ -0,0 +1,53 @@ +.TH std::char_traits::length,std::char_traits::length, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::length,std::char_traits::length, \- std::char_traits::length,std::char_traits::length, + +.SH Synopsis + std::char_traits::length + + static std::size_t length( const char_type* s ); (constexpr since C++17) + + Returns the length of the character sequence pointed to by s, that is, the position + of the terminating null character (char_type()). + + See CharTraits for the general requirements on character traits for X::length. + +.SH Parameters + + s - pointer to a character sequence to return length of + +.SH Return value + + The length of character sequence pointed to by s. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(const char* str) + { + std::cout << std::quoted(str) << " has length = " + << std::char_traits::length(str) << '\\n'; + } + + int main() + { + print("foo"); + + std::string s{"booo"}; + print(s.c_str()); + } + +.SH Output: + + "foo" has length = 3 + "booo" has length = 4 diff --git a/man/std::char_traits::length.3 b/man/std::char_traits::length.3 deleted file mode 100644 index 54aeaa1e4..000000000 --- a/man/std::char_traits::length.3 +++ /dev/null @@ -1,48 +0,0 @@ -.TH std::char_traits::length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static std::size_t length( const char_type* s ); - - Returns the length of the character sequence pointed to by s, that is, the position - of the terminating null character (CharT()). - -.SH Parameters - - s - pointer to a character sequence to return length of - -.SH Return value - - The length of character sequence pointed to by s. - -.SH Exceptions - - \fI(none)\fP - -.SH Complexity - - Linear. - -.SH Example - - -// Run this code - - #include - - void print(const char* str) - { - std::cout << "string '" << str << "' "; - std::cout << "length = " << std::char_traits::length(str) << '\\n'; - } - - int main() - { - print("foo"); - - std::string s("booo"); - print(s.c_str()); - } - -.SH Output: - - string 'foo' length = 3 - string 'booo' length = 4 diff --git a/man/std::char_traits::move,std::char_traits::move,.3 b/man/std::char_traits::move,std::char_traits::move,.3 new file mode 100644 index 000000000..bed64a65d --- /dev/null +++ b/man/std::char_traits::move,std::char_traits::move,.3 @@ -0,0 +1,46 @@ +.TH std::char_traits::move,std::char_traits::move, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::move,std::char_traits::move, \- std::char_traits::move,std::char_traits::move, + +.SH Synopsis + std::char_traits::move + + static char_type* + move( char_type* dest, const char_type* src, (constexpr since C++20) + std::size_t count ); + + Copies count characters from the character string pointed to by src to the character + string pointed to by dest. + + Performs correctly even if the ranges [src, src + count) and [dest, dest + count) + overlap. + + See CharTraits for the general requirements on character traits for X::move. + +.SH Parameters + + dest - pointer to a character string to copy to + src - pointer to a character string to copy from + count - the number of characters to copy + +.SH Return value + + dest + +.SH Exceptions + + Throws nothing. + +.SH Complexity + + Linear in count. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the copy was guaranteed to perform correctly if + LWG 7 C++98 src is in [dest, dest + count), but not the other also guaranteed + way round (i.e. dest is in [src, src + count)) diff --git a/man/std::char_traits::move.3 b/man/std::char_traits::move.3 deleted file mode 100644 index 9119edd83..000000000 --- a/man/std::char_traits::move.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH std::char_traits::move 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static char_type* move( char_type* dest, const char_type* src, std::size_t count - ); - - Copies count character from character string pointed to by src to character string - pointed to by dest. - - Performs correctly even if the copied character ranges overlap, i.e. src is in - [dest, dest + count). - -.SH Parameters - - dest - pointer to a character string to copy to - src - pointer to a character string to copy from - count - the number of characters to copy - -.SH Return value - - dest - -.SH Exceptions - - \fI(none)\fP - -.SH Complexity - - Linear. diff --git a/man/std::char_traits::not_eof,std::char_traits::not_eof,.3 b/man/std::char_traits::not_eof,std::char_traits::not_eof,.3 new file mode 100644 index 000000000..d159f4369 --- /dev/null +++ b/man/std::char_traits::not_eof,std::char_traits::not_eof,.3 @@ -0,0 +1,33 @@ +.TH std::char_traits::not_eof,std::char_traits::not_eof, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::not_eof,std::char_traits::not_eof, \- std::char_traits::not_eof,std::char_traits::not_eof, + +.SH Synopsis + std::char_traits::not_eof + + static int_type not_eof( int_type e ); (constexpr since C++11) + (noexcept since C++11) + + Given e, produces a suitable value that is not equivalent to eof. + + This function is typically used when a value other than eof needs to be returned, + such as in implementations of std::basic_streambuf::overflow(). + + See CharTraits for the general requirements on character traits for X::not_eof. + +.SH Parameters + + e - value to analyze + +.SH Return value + + e if e and eof value are not equivalent, or some other non-eof value otherwise. + +.SH Complexity + + Constant. + +.SH See also + + eof returns an eof value + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::char_traits::not_eof.3 b/man/std::char_traits::not_eof.3 deleted file mode 100644 index 1258aa9ed..000000000 --- a/man/std::char_traits::not_eof.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::char_traits::not_eof 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static int_type not_eof( int_type e ); \fI(until C++11)\fP - static constexpr int_type not_eof( int_type e ); \fI(since C++11)\fP - - Checks whether e is not equivalent to eof value. - -.SH Parameters - - e - value to analyze - -.SH Return value - - e if e and eof value are not equivalent, some other value otherwise. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. - -.SH See also - - eof returns an eof value - \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::char_traits::to_char_type,std::char_traits::to_char_type,.3 b/man/std::char_traits::to_char_type,std::char_traits::to_char_type,.3 new file mode 100644 index 000000000..4799f3479 --- /dev/null +++ b/man/std::char_traits::to_char_type,std::char_traits::to_char_type,.3 @@ -0,0 +1,26 @@ +.TH std::char_traits::to_char_type,std::char_traits::to_char_type, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::to_char_type,std::char_traits::to_char_type, \- std::char_traits::to_char_type,std::char_traits::to_char_type, + +.SH Synopsis + std::char_traits::to_char_type + + static char_type to_char_type( int_type c ); (constexpr since C++11) + (noexcept since C++11) + + Converts c to char_type. If there is no equivalent char_type value (such as when c + is a copy of the eof() value), the result is unspecified. + + See CharTraits for the general requirements on character traits for X::to_char_type. + +.SH Parameters + + c - value to convert + +.SH Return value + + A value equivalent to c. + +.SH Complexity + + Constant. diff --git a/man/std::char_traits::to_char_type.3 b/man/std::char_traits::to_char_type.3 deleted file mode 100644 index 12aa5cd1b..000000000 --- a/man/std::char_traits::to_char_type.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::char_traits::to_char_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static char_type to_char_type( int_type c ); \fI(until C++11)\fP - static constexpr char_type to_char_type( int_type c ); \fI(since C++11)\fP - - Converts a value of int_type to char_type. If there are no equivalent value, the - results are unspecified. - -.SH Parameters - - c - value to convert - -.SH Return value - - A value equivalent to c. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. diff --git a/man/std::char_traits::to_int_type,std::char_traits::to_int_type,.3 b/man/std::char_traits::to_int_type,std::char_traits::to_int_type,.3 new file mode 100644 index 000000000..5f3b01de6 --- /dev/null +++ b/man/std::char_traits::to_int_type,std::char_traits::to_int_type,.3 @@ -0,0 +1,30 @@ +.TH std::char_traits::to_int_type,std::char_traits::to_int_type, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::char_traits::to_int_type,std::char_traits::to_int_type, \- std::char_traits::to_int_type,std::char_traits::to_int_type, + +.SH Synopsis + std::char_traits::to_int_type + + static int_type to_int_type( char_type c ); (constexpr since C++11) + (noexcept since C++11) + + Converts c to int_type. + + See CharTraits for the general requirements on character traits for X::to_int_type. + +.SH Parameters + + c - value to convert + +.SH Return value + + A value equivalent to c. + +.SH Complexity + + Constant. + +.SH Notes + + For every valid value of char_type, there must be a unique value of int_type + distinct from eof(). diff --git a/man/std::char_traits::to_int_type.3 b/man/std::char_traits::to_int_type.3 deleted file mode 100644 index 56c7c5a8e..000000000 --- a/man/std::char_traits::to_int_type.3 +++ /dev/null @@ -1,25 +0,0 @@ -.TH std::char_traits::to_int_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - static int_type to_int_type( char_type c ); \fI(until C++11)\fP - static constexpr int_type to_int_type( char_type c ); \fI(since C++11)\fP - - Converts a value of char_type to int_type. - -.SH Parameters - - c - value to convert - -.SH Return value - - A value equivalent to c. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. diff --git a/man/std::chars_format.3 b/man/std::chars_format.3 new file mode 100644 index 000000000..fa8b66bae --- /dev/null +++ b/man/std::chars_format.3 @@ -0,0 +1,38 @@ +.TH std::chars_format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chars_format \- std::chars_format + +.SH Synopsis + Defined in header + enum class chars_format { + + scientific = /*unspecified*/, + fixed = /*unspecified*/, \fI(since C++17)\fP + hex = /*unspecified*/, + general = fixed | scientific + + }; + + A BitmaskType used to specify floating-point formatting for std::to_chars and + std::from_chars. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_to_chars 201611L \fI(C++17)\fP Elementary string conversions (std::to_chars, + std::from_chars) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + to_chars converts an integer or floating-point value to a character sequence + \fI(C++17)\fP \fI(function)\fP + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chi_squared_distribution.3 b/man/std::chi_squared_distribution.3 index 11babd713..2cbd461fe 100644 --- a/man/std::chi_squared_distribution.3 +++ b/man/std::chi_squared_distribution.3 @@ -1,64 +1,199 @@ -.TH std::chi_squared_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution \- std::chi_squared_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP class chi_squared_distribution; - The chi_squared_distribution produces random numbers x>0 according to the - Chi-squared distribution: + The chi_squared_distribution produces random numbers \\(\\small x>0\\)x>0 according to + the Chi-squared distribution: - f(x;n) = + \\({\\small f(x;n) = }\\frac{x^{(n/2)-1}\\exp{(-x/2)} }{\\Gamma{(n/2)}2^{n/2} }\\)f(x;n) = x(n/2)-1 e^-x/2 Γ(n/2) 2n/2 - Γ is the Gamma function (See also std::tgamma) and n are the degrees of freedom - (default 1). + \\(\\small\\Gamma\\)Γ is the Gamma function (See also std::tgamma) and \\(\\small n\\)n are + the degrees of freedom (default 1). + + std::chi_squared_distribution satisfies all requirements of + RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - n returns the degrees of freedom (n) distribution parameter - \fI(public member function)\fP + n returns the degrees of freedom (\\(\\small n\\)n) distribution parameter + \fI(C++11)\fP \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - This section is incomplete - Reason: no example -.SH External links - - * Weisstein, Eric W. "Chi-Squared Distribution." From MathWorld--A Wolfram Web - Resource. - * Chi-squared distribution. From Wikipedia. +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + void draw_vbars(Seq&& s, const bool DrawMinMax = true) + { + static_assert(0 < Height and 0 < BarWidth and 0 <= Padding and 0 <= Offset); + + auto cout_n = [](auto&& v, int n = 1) + { + while (n-- > 0) + std::cout << v; + }; + + const auto [min, max] = std::minmax_element(std::cbegin(s), std::cend(s)); + + std::vector qr; + for (typedef decltype(*std::cbegin(s)) V; V e : s) + qr.push_back(std::div(std::lerp(V(0), 8 * Height, + (e - *min) / (*max - *min)), 8)); + + for (auto h{Height}; h-- > 0; cout_n('\\n')) + { + cout_n(' ', Offset); + + for (auto dv : qr) + { + const auto q{dv.quot}, r{dv.rem}; + unsigned char d[]{0xe2, 0x96, 0x88, 0}; // Full Block: '█' + q < h ? d[0] = ' ', d[1] = 0 : q == h ? d[2] -= (7 - r) : 0; + cout_n(d, BarWidth), cout_n(' ', Padding); + } + + if (DrawMinMax && Height > 1) + Height - 1 == h ? std::cout << "┬ " << *max: + h ? std::cout << "│ " + : std::cout << "┴ " << *min; + } + } + + int main() + { + std::random_device rd{}; + std::mt19937 gen{rd()}; + + auto χ2 = [&gen](const float dof) + { + std::chi_squared_distribution d{dof /* n */}; + + const int norm = 1'00'00; + const float cutoff = 0.002f; + + std::map hist{}; + for (int n = 0; n != norm; ++n) + ++hist[std::round(d(gen))]; + + std::vector bars; + std::vector indices; + for (auto const& [n, p] : hist) + if (float x = p * (1.0 / norm); cutoff < x) + { + bars.push_back(x); + indices.push_back(n); + } + + std::cout << "dof = " << dof << ":\\n"; + + for (draw_vbars<4, 3>(bars); int n : indices) + std::cout << std::setw(2) << n << " "; + std::cout << "\\n\\n"; + }; + + for (float dof : {1.f, 2.f, 3.f, 4.f, 6.f, 9.f}) + χ2(dof); + } + +.SH Possible output: + + dof = 1: + ███ ┬ 0.5271 + ███ │ + ███ ███ │ + ███ ███ ▇▇▇ ▃▃▃ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.003 + 0 1 2 3 4 5 6 7 8 + + dof = 2: + ███ ┬ 0.3169 + ▆▆▆ ███ ▃▃▃ │ + ███ ███ ███ ▄▄▄ │ + ███ ███ ███ ███ ▇▇▇ ▄▄▄ ▃▃▃ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.004 + 0 1 2 3 4 5 6 7 8 9 10 + + dof = 3: + ███ ▃▃▃ ┬ 0.2439 + ███ ███ ▄▄▄ │ + ▃▃▃ ███ ███ ███ ▇▇▇ ▁▁▁ │ + ███ ███ ███ ███ ███ ███ ▆▆▆ ▄▄▄ ▃▃▃ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0033 + 0 1 2 3 4 5 6 7 8 9 10 11 12 + + dof = 4: + ▂▂▂ ███ ▃▃▃ ┬ 0.1864 + ███ ███ ███ ███ ▂▂▂ │ + ███ ███ ███ ███ ███ ▅▅▅ ▁▁▁ │ + ▅▅▅ ███ ███ ███ ███ ███ ███ ███ ▆▆▆ ▄▄▄ ▃▃▃ ▂▂▂ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0026 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 + + dof = 6: + ▅▅▅ ▇▇▇ ███ ▂▂▂ ┬ 0.1351 + ▅▅▅ ███ ███ ███ ███ ▇▇▇ ▁▁▁ │ + ▁▁▁ ███ ███ ███ ███ ███ ███ ███ ▅▅▅ ▂▂▂ │ + ▁▁▁ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ▅▅▅ ▄▄▄ ▃▃▃ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0031 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 + + dof = 9: + ▅▅▅ ▇▇▇ ███ ███ ▄▄▄ ▂▂▂ ┬ 0.1044 + ▃▃▃ ███ ███ ███ ███ ███ ███ ▅▅▅ ▁▁▁ │ + ▄▄▄ ███ ███ ███ ███ ███ ███ ███ ███ ███ ▆▆▆ ▃▃▃ │ + ▄▄▄ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ▆▆▆ ▄▄▄ ▃▃▃ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0034 + 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 -.SH Category: +.SH External links - * Todo no example + Weisstein, Eric W. "Chi-Squared Distribution." From MathWorld — A Wolfram Web + Resource. + Chi-squared distribution — From Wikipedia. diff --git a/man/std::chi_squared_distribution::chi_squared_distribution.3 b/man/std::chi_squared_distribution::chi_squared_distribution.3 index c089508d5..5874a3cf4 100644 --- a/man/std::chi_squared_distribution::chi_squared_distribution.3 +++ b/man/std::chi_squared_distribution::chi_squared_distribution.3 @@ -1,12 +1,26 @@ -.TH std::chi_squared_distribution::chi_squared_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::chi_squared_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::chi_squared_distribution \- std::chi_squared_distribution::chi_squared_distribution + .SH Synopsis - explicit chi_squared_distribution( RealType n = 1.0 ); \fB(1)\fP \fI(since C++11)\fP - explicit chi_squared_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + chi_squared_distribution() : chi_squared_distribution(1.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit chi_squared_distribution( RealType n ); \fB(2)\fP \fI(since C++11)\fP + explicit chi_squared_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs new distribution object. The first version uses n as the distribution - parameter, the second version uses params as the distribution parameter. + 2) Uses n as the distribution parameter. + 3) Uses params as the distribution parameter. .SH Parameters n - the n distribution parameter (degrees of freedom) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::chi_squared_distribution::max.3 b/man/std::chi_squared_distribution::max.3 index b463f77b9..018ad4f47 100644 --- a/man/std::chi_squared_distribution::max.3 +++ b/man/std::chi_squared_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::chi_squared_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::max \- std::chi_squared_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::chi_squared_distribution::min.3 b/man/std::chi_squared_distribution::min.3 index f0f49e6f0..ff4832124 100644 --- a/man/std::chi_squared_distribution::min.3 +++ b/man/std::chi_squared_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::chi_squared_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::min \- std::chi_squared_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::chi_squared_distribution::n.3 b/man/std::chi_squared_distribution::n.3 index f2b583fb7..c776c7f6f 100644 --- a/man/std::chi_squared_distribution::n.3 +++ b/man/std::chi_squared_distribution::n.3 @@ -1,4 +1,7 @@ -.TH std::chi_squared_distribution::n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::n \- std::chi_squared_distribution::n + .SH Synopsis RealType n() const; \fI(since C++11)\fP @@ -15,5 +18,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::chi_squared_distribution::operator().3 b/man/std::chi_squared_distribution::operator().3 index 2c3e9ca68..b6794a951 100644 --- a/man/std::chi_squared_distribution::operator().3 +++ b/man/std::chi_squared_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::chi_squared_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::operator() \- std::chi_squared_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::chi_squared_distribution::param.3 b/man/std::chi_squared_distribution::param.3 index d651eae7f..f7dd5abca 100644 --- a/man/std::chi_squared_distribution::param.3 +++ b/man/std::chi_squared_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::chi_squared_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::param \- std::chi_squared_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::chi_squared_distribution::reset.3 b/man/std::chi_squared_distribution::reset.3 index d55250798..e2595ff8c 100644 --- a/man/std::chi_squared_distribution::reset.3 +++ b/man/std::chi_squared_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::chi_squared_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chi_squared_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chi_squared_distribution::reset \- std::chi_squared_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::chrono::abs(std::chrono::duration).3 b/man/std::chrono::abs(std::chrono::duration).3 new file mode 100644 index 000000000..23adc8d2f --- /dev/null +++ b/man/std::chrono::abs(std::chrono::duration).3 @@ -0,0 +1,64 @@ +.TH std::chrono::abs(std::chrono::duration) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::abs(std::chrono::duration) \- std::chrono::abs(std::chrono::duration) + +.SH Synopsis + Defined in header + template< class Rep, class Period > + constexpr std::chrono::duration abs( \fI(since C++17)\fP + std::chrono::duration d ); + + Returns the absolute value of the duration d. Specifically, if d >= d.zero(), return + d, otherwise return -d. + + The function does not participate in the overload resolution unless + std::numeric_limits::is_signed is true. + +.SH Parameters + + d - duration + +.SH Return value + + Absolute value of d. + +.SH Possible implementation + + template::is_signed>> + constexpr std::chrono::duration abs(std::chrono::duration d) + { + return d >= d.zero() ? +d : -d; + } + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + + static_assert(abs(-42s) == std::chrono::abs(42s)); + + std::cout << "abs(+3min) = " << abs(3min).count() << '\\n' + << "abs(-3min) = " << abs(-3min).count() << '\\n'; + } + +.SH Output: + + abs(+3min) = 3 + abs(-3min) = 3 + +.SH See also + + operator+ implements unary + and unary - + operator- \fI(public member function)\fP + abs(int) + labs computes absolute value of an integral value (\\(\\small{|x|}\\)|x|) + llabs \fI(function)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::ambiguous_local_time.3 b/man/std::chrono::ambiguous_local_time.3 new file mode 100644 index 000000000..0293cdb56 --- /dev/null +++ b/man/std::chrono::ambiguous_local_time.3 @@ -0,0 +1,126 @@ +.TH std::chrono::ambiguous_local_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::ambiguous_local_time \- std::chrono::ambiguous_local_time + +.SH Synopsis + Defined in header + class ambiguous_local_time; \fI(since C++20)\fP + + Defines a type of object to be thrown as exception to report that an attempt was + made to convert an ambiguous std::chrono::local_time to a std::chrono::sys_time + without specifying a std::chrono::choose (such as choose::earliest or + choose::latest). + + This exception is thrown by std::chrono::time_zone::to_sys and functions that call + it (such as the constructors of std::chrono::zoned_time that take a + std::chrono::local_time). + + std-chrono-ambiguous local time-inheritance.svg + + Inheritance diagram + +.SH Member functions + + constructor constructs the exception object + \fI(public member function)\fP + operator= replaces the exception object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::chrono::ambiguous_local_time::ambiguous_local_time + + template< class Duration > + + ambiguous_local_time( const std::chrono::local_time& tp, \fB(1)\fP \fI(since C++20)\fP + + const std::chrono::local_info& i ); + ambiguous_local_time( const ambiguous_local_time& other ) \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Constructs the exception object. + + 1) The explanatory string returned by what() is equivalent to that produced by + os.str() after the following code: + + std::ostringstream os; + os << tp << " is ambiguous. It could be\\n" + << tp << ' ' << i.first.abbrev << " == " + << tp - i.first.offset << " UTC or\\n" + << tp << ' ' << i.second.abbrev << " == " + << tp - i.second.offset << " UTC"; + + The behavior is undefined if i.result != std::chrono::local_info::ambiguous. + 2) Copy constructor. If *this and other both have dynamic type + std::chrono::ambiguous_local_time then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + tp - the time point for which conversion was attempted + i - a std::chrono::local_info describing the result of the conversion attempt + other - another ambiguous_local_time to copy + +.SH Exceptions + + May throw std::bad_alloc + +.SH Notes + + Because copying a standard library class derived from std::exception is not + permitted to throw exceptions, this message is typically stored internally as a + separately-allocated reference-counted string. + +std::chrono::ambiguous_locale_time::operator= + + ambiguous_locale_time& operator=( const ambiguous_locale_time& other \fI(since C++20)\fP + ) noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::chrono::ambiguous_locale_time then std::strcmp(what(), other.what()) == 0 after + assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::chrono::ambiguous_locale_time::what + + virtual const char* what() const noexcept; \fI(since C++20)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + +Inherited from std::runtime_error + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH See also + + nonexistent_local_time exception thrown to report that a local time is nonexistent + (C++20) \fI(class)\fP diff --git a/man/std::chrono::ceil(std::chrono::duration).3 b/man/std::chrono::ceil(std::chrono::duration).3 new file mode 100644 index 000000000..71b2a6c44 --- /dev/null +++ b/man/std::chrono::ceil(std::chrono::duration).3 @@ -0,0 +1,86 @@ +.TH std::chrono::ceil(std::chrono::duration) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::ceil(std::chrono::duration) \- std::chrono::ceil(std::chrono::duration) + +.SH Synopsis + Defined in header + template< class ToDuration, class Rep, class Period > + constexpr ToDuration ceil( const std::chrono::duration& \fI(since C++17)\fP + d ); + + Returns the smallest duration t representable in ToDuration that is greater or equal + to d. + + The function does not participate in the overload resolution unless ToDuration is a + specialization of std::chrono::duration. + +.SH Parameters + + d - duration to convert + +.SH Return value + + d rounded up to a duration of type ToDuration. + +.SH Possible implementation + + namespace detail + { + template inline constexpr bool is_duration_v = false; + template inline constexpr bool is_duration_v< + std::chrono::duration> = true; + } + + template>> + constexpr To ceil(const std::chrono::duration& d) + { + To t = std::chrono::duration_cast(d); + if (t < d) + return t + To{1}; + return t; + } + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono_literals; + using Min = std::chrono::minutes; + + std::cout + << std::showpos + << "ceil(+2.4min) = " << std::chrono::ceil(+2.4min).count() << "min\\n" + << "ceil(-2.4min) = " << std::chrono::ceil(-2.4min).count() << "min\\n" + << "ceil(+0.0min) = " << std::chrono::ceil(+0.0min).count() << "min\\n"; + } + +.SH Output: + + ceil(+2.4min) = +3min + ceil(-2.4min) = -2min + ceil(+0.0min) = +0min + +.SH See also + + duration_cast converts a duration to another, with a different tick + \fI(C++11)\fP interval + \fI(function template)\fP + floor(std::chrono::duration) converts a duration to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::duration) converts a duration to another, rounding to nearest, + \fI(C++17)\fP ties to even + \fI(function template)\fP + ceil(std::chrono::time_point) converts a time_point to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + ceil + ceilf nearest integer not less than the given value + ceill \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::ceil(std::chrono::time_point).3 b/man/std::chrono::ceil(std::chrono::time_point).3 new file mode 100644 index 000000000..233241038 --- /dev/null +++ b/man/std::chrono::ceil(std::chrono::time_point).3 @@ -0,0 +1,105 @@ +.TH std::chrono::ceil(std::chrono::time_point) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::ceil(std::chrono::time_point) \- std::chrono::ceil(std::chrono::time_point) + +.SH Synopsis + Defined in header + template< class ToDuration, class Clock, class Duration > + + constexpr std::chrono::time_point \fI(since C++17)\fP + + ceil( const std::chrono::time_point& tp ); + + Returns the smallest time point t representable in ToDuration that is greater or + equal to tp. + + The function does not participate in the overload resolution unless ToDuration is a + specialization of std::chrono::duration. + +.SH Parameters + + tp - time point to round up + +.SH Return value + + tp rounded up to the next time point using duration of type ToDuration. + +.SH Possible implementation + + namespace detail + { + template inline constexpr bool is_duration_v = false; + template inline constexpr bool is_duration_v< + std::chrono::duration> = true; + } + + template>> + constexpr std::chrono::time_point + ceil(const std::chrono::time_point& tp) + { + return std::chrono::time_point{ + std::chrono::ceil(tp.time_since_epoch())}; + } + +.SH Example + + + +// Run this code + + #include + #include + #include + + template + std::string to_string(const TimePoint& time_point) + { + return std::to_string(time_point.time_since_epoch().count()); + } + + int main() + { + using namespace std::literals::chrono_literals; + using Sec = std::chrono::seconds; + + std::cout << "Time point\\t" "Cast\\t" "Floor\\t" "Round\\t" "Ceil\\n"; + std::cout << "(ms)\\t\\t" "(s)\\t" "(s)\\t" "(s)\\t" "(s)\\n"; + for (const auto value_ms : {5432ms, 5678ms}) + { + std::chrono::time_point + time_point_ms(value_ms); + + std::cout + << to_string(time_point_ms) << "\\t\\t" + << to_string(std::chrono::time_point_cast(time_point_ms)) << '\\t' + << to_string(std::chrono::floor(time_point_ms)) << '\\t' + << to_string(std::chrono::round(time_point_ms)) << '\\t' + << to_string(std::chrono::ceil(time_point_ms)) << '\\n'; + } + } + +.SH Output: + + Time point Cast Floor Round Ceil + (ms) (s) (s) (s) (s) + 5432 5 5 5 6 + 5678 5 5 6 6 + +.SH See also + + time_point_cast converts a time point to another time point on the + \fI(C++11)\fP same clock, with a different duration + \fI(function template)\fP + floor(std::chrono::time_point) converts a time_point to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::time_point) converts a time_point to another, rounding to + \fI(C++17)\fP nearest, ties to even + \fI(function template)\fP + ceil(std::chrono::duration) converts a duration to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + ceil + ceilf nearest integer not less than the given value + ceill \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::choose.3 b/man/std::chrono::choose.3 new file mode 100644 index 000000000..d27759865 --- /dev/null +++ b/man/std::chrono::choose.3 @@ -0,0 +1,31 @@ +.TH std::chrono::choose 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::choose \- std::chrono::choose + +.SH Synopsis + Defined in header + enum class choose { + + earliest, \fI(since C++20)\fP + latest + + }; + + The scoped enumeration choose can be passed to certain member functions of + std::chrono::time_zone and std::chrono::zoned_time to control how ambiguous or + nonexistent local times should be resolved. Passing choose::earliest causes the + earlier time point to be returned, while passing choose::latest causes the later + time point to be returned. (For nonexistent local times, these two time points are + identical.) + + If a choose is not passed and an ambiguous or nonexistent local time is encountered, + a std::chrono::ambiguous_local_time or std::chrono::nonexistent_local_time exception + (as applicable) will be thrown. + +.SH See also + + constructs a zoned_time + constructor \fI\fI(public member\fP function of\fP + std::chrono::zoned_time) + to_sys converts a local_time in this time zone to a sys_time + \fI(public member function of std::chrono::time_zone)\fP diff --git a/man/std::chrono::clock_cast.3 b/man/std::chrono::clock_cast.3 new file mode 100644 index 000000000..ca9ac2967 --- /dev/null +++ b/man/std::chrono::clock_cast.3 @@ -0,0 +1,65 @@ +.TH std::chrono::clock_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::clock_cast \- std::chrono::clock_cast + +.SH Synopsis + Defined in header + template< class Dest, class Source, class Duration > + auto clock_cast( const std::chrono::time_point& t \fI(since C++20)\fP + ); + + Converts the time point t of a clock Source to an equivalent time point of the clock + Dest, using std::chrono::system_clock and/or std::chrono::utc_clock as + intermediaries if necessary. + + * If the expression std::chrono::clock_time_conversion{}(t) is + well-formed, returns the result of that expression. + * Otherwise, if at least one of the following two expressions are well-formed, + then + + * If both expressions are well-formed, the conversion is ambiguous, and the + program is ill-formed. + * Otherwise, exactly one of the two expressions is well-formed; the result of that + expression is returned. + 1) std::chrono::clock_time_conversion{}( + std::chrono::clock_time_conversion{}(t)) + 2) std::chrono::clock_time_conversion{}( + std::chrono::clock_time_conversion{}(t)) + * Otherwise, if at least one of the following two expressions are well-formed, + then + + * If both expressions are well-formed, the conversion is ambiguous, and the + program is ill-formed. + * Otherwise, exactly one of the two expressions is well-formed; the result of that + expression is returned. + 1) std::chrono::clock_time_conversion{}( + + std::chrono::clock_time_conversion{}( + + std::chrono::clock_time_conversion{}(t))) + 2) std::chrono::clock_time_conversion{}( + + std::chrono::clock_time_conversion{}( + + std::chrono::clock_time_conversion{}(t))) + * Otherwise, this function does not participate in overload resolution. + +.SH Return value + + The result of the conversion, determined as described above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + clock_time_conversion traits class defining how to convert time points of one clock + (C++20) to another + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::clock_time_conversion.3 b/man/std::chrono::clock_time_conversion.3 new file mode 100644 index 000000000..dd4f15a66 --- /dev/null +++ b/man/std::chrono::clock_time_conversion.3 @@ -0,0 +1,161 @@ +.TH std::chrono::clock_time_conversion 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::clock_time_conversion \- std::chrono::clock_time_conversion + +.SH Synopsis + Defined in header + template< class Dest, class Source > \fI(since C++20)\fP + struct clock_time_conversion {}; + + std::chrono::clock_time_conversion is a trait that specifies how to convert a + std::chrono::time_point of the Source clock to that of the Dest clock. It does so by + providing a const-callable operator() that accepts an argument of type + std::chrono::time_point and returns a + std::chrono::time_point that represents an equivalent point in + time. The duration of the returned time point is computed from the source duration + in a manner that varies for each specialization. clock_time_conversion is normally + only used indirectly, via std::chrono::clock_cast. + + A program may specialize clock_time_conversion if at least one of the template + parameters is a user-defined clock type. + + The primary template is an empty struct. The standard defines the following + specializations: + + template< class Clock > \fB(1)\fP \fI(since C++20)\fP + struct clock_time_conversion; + template<> + struct clock_time_conversion; + template<> + struct clock_time_conversion; + template<> + struct clock_time_conversion; + template<> + struct clock_time_conversion; + template< class Clock > \fB(6)\fP \fI(since C++20)\fP + struct clock_time_conversion; + template< class Clock > \fB(7)\fP \fI(since C++20)\fP + struct clock_time_conversion; + template< class Clock > \fB(8)\fP \fI(since C++20)\fP + struct clock_time_conversion; + template< class Clock > \fB(9)\fP \fI(since C++20)\fP + struct clock_time_conversion; + + 1-3) Identity conversion: operator() returns a copy of the argument. + 4,5) Conversions between std::chrono::sys_time and std::chrono::utc_time: operator() + calls std::chrono::utc_clock::to_sys and std::chrono::utc_clock::from_sys, + respectively. + 6,7) Conversions to and from std::chrono::sys_time when Clock supports from_sys and + to_sys: operator() calls Clock::to_sys and Clock::from_sys, respectively. + 8,9) Conversions to and from std::chrono::utc_time when Clock supports from_utc and + to_utc: operator() calls Clock::to_utc and Clock::from_utc, respectively. + +.SH Member functions + + Each specialization has an implicitly-declared default constructor, copy + constructor, move constructor, copy assignment operator, move assignment operator, + and destructor. + +std::chrono::clock_time_conversion::operator() + + template< class Duration > + + std::chrono::time_point \fB(1)\fP (member of + specialization \fB(1)\fP) + operator()( const std::chrono::time_point& t ) const; + template< class Duration > + + std::chrono::sys_time \fB(2)\fP (member of + specialization \fB(2)\fP) + operator()( const std::chrono::sys_time & t ) + const; + template< class Duration > + + std::chrono::utc_time \fB(3)\fP (member of + specialization \fB(3)\fP) + operator()( const std::chrono::utc_time& t ) + const; + template< class Duration > + + std::chrono::sys_time \fB(4)\fP (member of + specialization \fB(4)\fP) + operator()( const std::chrono::utc_time& t ) + const; + template< class Duration > + + std::chrono::utc_time \fB(5)\fP (member of + specialization \fB(5)\fP) + operator()( const std::chrono::sys_time& t ) + const; + template< class Duration > + + auto operator()( const std::chrono::sys_time& t ) \fB(6)\fP (member of + const specialization \fB(6)\fP) + + -> decltype(Clock::from_sys(t)); + template< class Duration > + + auto operator()( const std::chrono::time_point& t ) const specialization \fB(7)\fP) + + -> decltype(Clock::to_sys(t)); + template< class Duration > + + auto operator()( const std::chrono::utc_time& t ) \fB(8)\fP (member of + const specialization \fB(8)\fP) + + -> decltype(Clock::from_utc(t)); + template< class Duration > + + auto operator()( const std::chrono::time_point& t ) const specialization \fB(9)\fP) + + -> decltype(Clock::to_utc(t)); + + Converts the argument std::chrono::time_point to the destination clock. + + 1-3) Identity conversion. Returns t unchanged. + 4) Returns std::chrono::utc_clock::to_sys(t). + 5) Returns std::chrono::utc_clock::from_sys(t). + 6) Returns Clock::from_sys(t). This overload participates in overload resolution + only if the expression Clock::from_sys(t) is well-formed. The program is ill-formed + if Clock::from_sys(t) does not return std::chrono::time_point where + Duration is some valid specialization of std::chrono::duration. + 7) Returns Clock::to_sys(t). This overload participates in overload resolution only + if the expression Clock::to_sys(t) is well-formed. The program is ill-formed if + Clock::to_sys(t) does not return std::chrono::sys_time where Duration is + some valid specialization of std::chrono::duration. + 8) Returns Clock::from_utc(t). This overload participates in overload resolution + only if the expression Clock::from_utc(t) is well-formed. The program is ill-formed + if Clock::from_utc(t) does not return std::chrono::time_point where + Duration is some valid specialization of std::chrono::duration. + 9) Returns Clock::to_utc(t). This overload participates in overload resolution only + if the expression Clock::to_utc(t) is well-formed. The program is ill-formed if + Clock::to_utc(t) does not return std::chrono::utc_time where Duration is + some valid specialization of std::chrono::duration. + +.SH Parameters + + t - time point to convert + +.SH Return value + + The result of the conversion as described above: + + 1-3) t. + 4) std::chrono::utc_clock::to_sys(t). + 5) std::chrono::utc_clock::from_sys(t). + 6) Clock::from_sys(t). + 7) Clock::to_sys(t). + 8) Clock::from_utc(t). + 9) Clock::to_utc(t). + +.SH See also + + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::current_zone.3 b/man/std::chrono::current_zone.3 new file mode 100644 index 000000000..6f11911cc --- /dev/null +++ b/man/std::chrono::current_zone.3 @@ -0,0 +1,48 @@ +.TH std::chrono::current_zone 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::current_zone \- std::chrono::current_zone + +.SH Synopsis + Defined in header + const std::chrono::time_zone* current_zone(); \fI(since C++20)\fP + + Convenience function for obtaining local time zone from the time zone database. + Equivalent to std::chrono::get_tzdb().current_zone(). + +.SH Exceptions + + std::runtime_error if this is the first reference to the time zone database and the + time zone database cannot be initialized. + +.SH Notes + + A call to this function that is the first reference to the time zone database will + cause it to be initialized. + +.SH Example + + +// Run this code + + #include + #include + + int main() { + const std::chrono::zoned_time cur_time{ std::chrono::current_zone(), + std::chrono::system_clock::now() }; + std::cout << cur_time << '\\n'; + } + +.SH Possible output: + + 2021-09-13 19:46:42.249182012 MAGT + +.SH See also + + current_zone return the local time zone + \fI(public member function of std::chrono::tzdb)\fP + get_tzdb + get_tzdb_list accesses and controls the global time zone database information + reload_tzdb \fI(function)\fP + remote_version + (C++20) diff --git a/man/std::chrono::day.3 b/man/std::chrono::day.3 new file mode 100644 index 000000000..a2873bf53 --- /dev/null +++ b/man/std::chrono::day.3 @@ -0,0 +1,53 @@ +.TH std::chrono::day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::day \- std::chrono::day + +.SH Synopsis + Defined in header + class day; \fI(since C++20)\fP + + The class day represents a day in a month. Its normal range is [1, 31], but it may + hold any number in [0, 255]. + + day is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a day + \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the day + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of days + operator-= \fI(public member function)\fP + operator unsigned retrieves the stored day value + \fI(public member function)\fP + ok checks if the stored day value is in the normal range + \fI(public member function)\fP + + Nonmember functions + + operator== compares two day values + operator<=> \fI(function)\fP + (C++20) + operator+ adds or subtracts a number of days and a day, or find the difference + operator- between two days + (C++20) \fI(function)\fP + operator<< outputs a day into a stream + (C++20) \fI(function template)\fP + from_stream parses a day from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for day + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::day + (C++26) \fI(class template specialization)\fP + +.SH Literals + + Defined in inline namespace std::literals::chrono_literals + operator""d a std::chrono::day literal representing a day of a month + (C++20) \fI(function)\fP diff --git a/man/std::chrono::day::day.3 b/man/std::chrono::day::day.3 new file mode 100644 index 000000000..e67645f18 --- /dev/null +++ b/man/std::chrono::day::day.3 @@ -0,0 +1,13 @@ +.TH std::chrono::day::day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::day::day \- std::chrono::day::day + +.SH Synopsis + day() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit day( unsigned d ) noexcept; \fB(2)\fP \fI(since C++20)\fP + + Constructs a day object. + + 1) Default constructor leaves the day value uninitialized. + 2) If d <= 255, constructs a day object holding the day value d. Otherwise the value + held is unspecified. diff --git a/man/std::chrono::day::ok.3 b/man/std::chrono::day::ok.3 new file mode 100644 index 000000000..565206468 --- /dev/null +++ b/man/std::chrono::day::ok.3 @@ -0,0 +1,38 @@ +.TH std::chrono::day::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::day::ok \- std::chrono::day::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the day value stored in *this is in the valid range, i.e., [1, 31]. + +.SH Return value + + true if the day value stored in *this is in the range [1, 31]. Otherwise false. + +.SH Example + + +// Run this code + + #include + using namespace std::chrono_literals; + + constexpr std::chrono::day d0{00}; + constexpr std::chrono::day d1{13}; + constexpr std::chrono::day d2{42}; + + static_assert + ( + d0 == 0d && !d0.ok() && + d1 == 13d && d1.ok() && + d2 == 42d && !d2.ok() + ); + + int main() {} + +.SH See also + + operator unsigned retrieves the stored day value + \fI(public member function)\fP diff --git a/man/std::chrono::day::operator++,std::chrono::day::operator--.3 b/man/std::chrono::day::operator++,std::chrono::day::operator--.3 new file mode 100644 index 000000000..739e70dcf --- /dev/null +++ b/man/std::chrono::day::operator++,std::chrono::day::operator--.3 @@ -0,0 +1,55 @@ +.TH std::chrono::day::operator++,std::chrono::day::operator-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::day::operator++,std::chrono::day::operator-- \- std::chrono::day::operator++,std::chrono::day::operator-- + +.SH Synopsis + constexpr std::chrono::day& operator++() noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::day operator++( int ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::day& operator--() noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr std::chrono::day operator--( int ) noexcept; \fB(4)\fP \fI(since C++20)\fP + + Adds or subtracts 1 from the day value. + + 1,2) Performs *this += std::chrono::days{1};. + 3,4) Performs *this -= std::chrono::days{1};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) A reference to this day after modification. + 2,4) A copy of the day made before modification. + +.SH Notes + + If the result would be outside the range [0, 255], the actual stored value is + unspecified. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::day d{15}; + + ++d; + assert(d == std::chrono::day(16)); + + --d; + assert(d == std::chrono::day(15)); + } + +.SH See also + + operator+= adds or subtracts a number of days + operator-= \fI(public member function)\fP + operator+ adds or subtracts a number of days and a day, or find the difference + operator- between two days + (C++20) \fI(function)\fP diff --git a/man/std::chrono::day::operator+=,std::chrono::day::operator-=.3 b/man/std::chrono::day::operator+=,std::chrono::day::operator-=.3 new file mode 100644 index 000000000..e2d03c686 --- /dev/null +++ b/man/std::chrono::day::operator+=,std::chrono::day::operator-=.3 @@ -0,0 +1,52 @@ +.TH std::chrono::day::operator+=,std::chrono::day::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::day::operator+=,std::chrono::day::operator-= \- std::chrono::day::operator+=,std::chrono::day::operator-= + +.SH Synopsis + constexpr std::chrono::day& operator+=( const std::chrono::days& d \fB(1)\fP \fI(since C++20)\fP + ) noexcept; + constexpr std::chrono::day& operator-=( const std::chrono::days& d \fB(2)\fP \fI(since C++20)\fP + ) noexcept; + + Adds or subtracts d.count() days from the day value. + + 1) Equivalent to *this = *this + d;. + 2) Equivalent to *this = *this - d;. + +.SH Return value + + A reference to this day after modification. + +.SH Notes + + If the result would be outside the range [0, 255], the actual stored value is + unspecified. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::day d{15}; + + d += std::chrono::days(2); + assert(d == std::chrono::day(17)); + + d -= std::chrono::days{3}; + assert(d == std::chrono::day(14)); + } + +.SH See also + + operator++ + operator++(int) increments or decrements the day + operator-- \fI(public member function)\fP + operator--(int) + operator+ adds or subtracts a number of days and a day, or find the difference + operator- between two days + (C++20) \fI(function)\fP diff --git a/man/std::chrono::day::operatorunsigned.3 b/man/std::chrono::day::operatorunsigned.3 new file mode 100644 index 000000000..5a0139e02 --- /dev/null +++ b/man/std::chrono::day::operatorunsigned.3 @@ -0,0 +1,31 @@ +.TH std::chrono::day::operatorunsigned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::day::operatorunsigned \- std::chrono::day::operatorunsigned + +.SH Synopsis + constexpr explicit operator unsigned() const noexcept; \fI(since C++20)\fP + + Returns the day value stored in *this. + +.SH Return value + + The day value stored in *this. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::day d{15}; + constexpr unsigned day = static_cast(d); + std::cout << "The day is: " << day << '\\n'; + } + +.SH Output: + + The day is: 15 diff --git a/man/std::chrono::duration.3 b/man/std::chrono::duration.3 index 9d59a780a..6979d3ce6 100644 --- a/man/std::chrono::duration.3 +++ b/man/std::chrono::duration.3 @@ -1,4 +1,7 @@ -.TH std::chrono::duration 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration \- std::chrono::duration + .SH Synopsis Defined in header template< @@ -11,7 +14,7 @@ Class template std::chrono::duration represents a time interval. It consists of a count of ticks of type Rep and a tick period, where the tick period - is a compile-time rational constant representing the number of seconds from one tick + is a compile-time rational fraction representing the time in seconds from one tick to the next. The only data stored in a duration is a tick count of type Rep. If Rep is floating @@ -23,128 +26,199 @@ Member type Definition rep Rep, an arithmetic type representing the number of ticks - period Period, a std::ratio representing the tick period (i.e. the number of - seconds per tick) + Period + \fI(until C++17)\fP + period typename Period::type + \fI(since C++17)\fP, a std::ratio representing the tick period (i.e. the + number of second's fractions per tick) .SH Member functions constructor constructs new duration - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP count returns the count of ticks - \fI(public member function)\fP + \fI(public member function)\fP zero returns the special duration value zero - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP min returns the special duration value min - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the special duration value max - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP operator+ implements unary + and unary - - operator- \fI(public member function)\fP + operator- \fI(public member function)\fP operator++ operator++(int) increments or decrements the tick count - operator-- \fI(public member function)\fP + operator-- \fI(public member function)\fP operator--(int) operator+= operator-= implements compound assignment between two durations - operator*= \fI(public member function)\fP + operator*= \fI(public member function)\fP operator/= operator%= .SH Non-member functions - std::common_type specializes the std::common_type trait - \fI(class template specialization)\fP operator+ - operator- implements arithmetic operations with - operator* durations as arguments - operator/ \fI(function template)\fP + operator- implements arithmetic operations with durations as + operator* arguments + operator/ \fI(function template)\fP operator% + \fI(C++11)\fP operator== operator!= - operator< compares two durations - operator<= \fI(function template)\fP + operator< + operator<= operator> operator>= - converts a duration to another, with a - duration_cast different tick interval - \fI(function template)\fP + operator<=> compares two durations + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + (C++20) + duration_cast converts a duration to another, with a different tick + \fI(C++11)\fP interval + \fI(function template)\fP + floor(std::chrono::duration) converts a duration to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + ceil(std::chrono::duration) converts a duration to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::duration) converts a duration to another, rounding to nearest, + \fI(C++17)\fP ties to even + \fI(function template)\fP + abs(std::chrono::duration) obtains the absolute value of the duration + \fI(C++17)\fP \fI(function template)\fP + operator<< performs stream output on a duration + (C++20) \fI(function template)\fP + from_stream parses a duration from a stream according to the + (C++20) provided format + \fI(function template)\fP .SH Helper types - Type Definition - std::chrono::nanoseconds duration - std::chrono::microseconds duration - std::chrono::milliseconds duration - std::chrono::seconds duration - std::chrono::minutes duration> - std::chrono::hours duration> + A type /* intXX */ used in the table below means a signed integer type of at least + XX bits. + + Type Definition + std::chrono::nanoseconds std::chrono::duration + std::chrono::microseconds std::chrono::duration + std::chrono::milliseconds std::chrono::duration + std::chrono::seconds std::chrono::duration + std::chrono::minutes std::chrono::duration> + std::chrono::hours std::chrono::duration> + std::chrono::days \fI(since C++20)\fP std::chrono::duration> + std::chrono::weeks \fI(since C++20)\fP std::chrono::duration> + std::chrono::months \fI(since C++20)\fP std::chrono::duration> + std::chrono::years \fI(since C++20)\fP std::chrono::duration> + + Note: each of the predefined duration types up to hours covers a range of at least + ±292 years. + + Each of the predefined duration types days, weeks, months and years + covers a range of at least ±40000 years. years is equal to 365.2425 \fI(since C++20)\fP + days (the average length of a Gregorian year). months is equal to + 30.436875 days (exactly 1/12 of years). .SH Helper classes - indicates that a duration is convertible to duration with - treat_as_floating_point different tick period - \fI(class template)\fP - constructs zero, min, and max values of a tick count of - duration_values given type - \fI(class template)\fP + std::common_type specializes the std::common_type trait + \fI(C++11)\fP \fI(class template specialization)\fP + treat_as_floating_point indicates that a duration is convertible to + \fI(C++11)\fP duration with different tick period + \fI(class template)\fP + duration_values constructs zero, min, and max values of a + \fI(C++11)\fP tick count of given type + \fI(class template)\fP + std::formatter formatting support for duration + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::duration + (C++26) \fI(class template specialization)\fP .SH Literals Defined in inline namespace std::literals::chrono_literals - operator""h A std::chrono::duration literal representing hours - \fI(C++14)\fP \fI(function)\fP - operator""min A std::chrono::duration literal representing minutes - \fI(C++14)\fP \fI(function)\fP - operator""s A std::chrono::duration literal representing seconds - \fI(C++14)\fP \fI(function)\fP - operator""ms A std::chrono::duration literal representing milliseconds - \fI(C++14)\fP \fI(function)\fP - operator""us A std::chrono::duration literal representing microseconds - \fI(C++14)\fP \fI(function)\fP - operator""ns A std::chrono::duration literal representing nanoseconds - \fI(C++14)\fP \fI(function)\fP + operator""h a std::chrono::duration literal representing hours + \fI(C++14)\fP \fI(function)\fP + operator""min a std::chrono::duration literal representing minutes + \fI(C++14)\fP \fI(function)\fP + operator""s a std::chrono::duration literal representing seconds + \fI(C++14)\fP \fI(function)\fP + operator""ms a std::chrono::duration literal representing milliseconds + \fI(C++14)\fP \fI(function)\fP + operator""us a std::chrono::duration literal representing microseconds + \fI(C++14)\fP \fI(function)\fP + operator""ns a std::chrono::duration literal representing nanoseconds + \fI(C++14)\fP \fI(function)\fP + + Note: the literal suffixes d and y do not refer to days and years but \fI(since C++20)\fP + to day and year, respectively. + +.SH Notes + + The actual time interval (in seconds) that is held by a duration object d is roughly + equal to d.count() * D::period::num / D::period::den, where D is of type + chrono::duration<> and d is an object of such type. + + Feature-test macro Value Std Feature + __cpp_lib_chrono_udls 201304L \fI(C++14)\fP User-defined literals for time types .SH Example This example shows how to define several custom duration types and convert between types: - + // Run this code - #include #include - + #include + + using namespace std::chrono_literals; + + template + using mul = std::ratio_multiply; + int main() { - typedef std::chrono::duration> shakes; - typedef std::chrono::duration jiffies; - typedef std::chrono::duration> microfortnights; - typedef std::chrono::duration> nanocenturies; - - std::chrono::seconds sec(1); - + using microfortnights = std::chrono::duration, std::chrono::weeks::period>, std::micro>>; + using nanocenturies = std::chrono::duration, std::nano>>; + using fps_24 = std::chrono::duration>; + std::cout << "1 second is:\\n"; - - std::cout << std::chrono::duration_cast(sec).count() - << " shakes\\n"; - std::cout << std::chrono::duration_cast(sec).count() - << " jiffies\\n"; - std::cout << microfortnights(sec).count() << " microfortnights\\n"; - std::cout << nanocenturies(sec).count() << " nanocenturies\\n"; + + // integer scale conversion with no precision loss: no cast + std::cout << std::chrono::milliseconds(1s).count() << " milliseconds\\n" + << std::chrono::microseconds(1s).count() << " microseconds\\n" + << std::chrono::nanoseconds(1s).count() << " nanoseconds\\n"; + + // integer scale conversion with precision loss: requires a cast + std::cout << std::chrono::duration_cast(1s).count() + << " minutes\\n"; + + // floating-point scale conversion: no cast + std::cout << microfortnights(1s).count() << " microfortnights\\n" + << nanocenturies(1s).count() << " nanocenturies\\n" + << fps_24(1s).count() << " frames at 24fps\\n"; } .SH Output: 1 second is: - 100000000 shakes - 100 jiffies + 1000 milliseconds + 1000000 microseconds + 1000000000 nanoseconds + 0 minutes 0.82672 microfortnights - 0.316957 nanocenturies + 0.316887 nanocenturies + 24 frames at 24fps diff --git a/man/std::chrono::duration::count.3 b/man/std::chrono::duration::count.3 index e29920551..751302e2f 100644 --- a/man/std::chrono::duration::count.3 +++ b/man/std::chrono::duration::count.3 @@ -1,6 +1,9 @@ -.TH std::chrono::duration::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::count \- std::chrono::duration::count + .SH Synopsis - constexpr rep count() const; + constexpr rep count() const; \fI(since C++11)\fP Returns the number of ticks for this duration. @@ -14,22 +17,23 @@ .SH Example - + // Run this code #include #include + int main() { std::chrono::milliseconds ms{3}; // 3 milliseconds // 6000 microseconds constructed from 3 milliseconds - std::chrono::microseconds us = 2*ms; + std::chrono::microseconds us = 2 * ms; // 30Hz clock using fractional ticks std::chrono::duration> hz30(3.5); - - std::cout << "3 ms duration has " << ms.count() << " ticks\\n" - << "6000 us duration has " << us.count() << " ticks\\n" - << "3.5 30Hz duration has " << hz30.count() << " ticks\\n"; + + std::cout << "3 ms duration has " << ms.count() << " ticks\\n" + << "6000 us duration has " << us.count() << " ticks\\n" + << "3.5 30Hz duration has " << hz30.count() << " ticks\\n"; } .SH Output: @@ -41,4 +45,4 @@ .SH See also duration_cast converts a duration to another, with a different tick interval - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::chrono::duration::duration.3 b/man/std::chrono::duration::duration.3 index 2a199b3f7..ef3ce0fba 100644 --- a/man/std::chrono::duration::duration.3 +++ b/man/std::chrono::duration::duration.3 @@ -1,40 +1,41 @@ -.TH std::chrono::duration::duration 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration::duration 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::duration \- std::chrono::duration::duration + .SH Synopsis - constexpr duration() = default; \fB(1)\fP \fI(since C++11)\fP - duration( const duration& ) = default; \fB(2)\fP \fI(since C++11)\fP - template< class Rep2 > \fB(3)\fP \fI(since C++11)\fP + constexpr duration() = default; \fB(1)\fP \fI(since C++11)\fP + duration( const duration& ) = default; \fB(2)\fP \fI(since C++11)\fP + template< class Rep2 > \fB(3)\fP \fI(since C++11)\fP constexpr explicit duration( const Rep2& r ); - template< class Rep2, class Period2 > \fB(4)\fP \fI(since C++11)\fP - constexpr duration( const duration& d ); + template< class Rep2, class Period2 > \fB(4)\fP \fI(since C++11)\fP + constexpr duration( const duration& d ); Constructs a new duration from one of several optional data sources. - 1) The default constructor is defaulted. - 2) The copy constructor is defaulted (makes a bitwise copy of the tick count). - 3) Constructs a duration with r ticks. Note that this constructor only participates - in overload resolution if Rep2 (the argument type) is implicitly convertible to rep - (the type of this duration's ticks) and + 1) The default constructor. + 2) The copy constructor. + 3) Constructs a duration with r ticks. + This overload participates in overload resolution only if all following conditions + are satisfied: + * is_convertible::value is true. + * Any of the following conditions is satisfied:^[1] - * std::chrono::treat_as_floating_point::value is true, or + * std::chrono::treat_as_floating_point::value is true. * std::chrono::treat_as_floating_point::value is false. - - (that is, a duration with an integer tick count cannot be constructed from a - floating-point value, but a duration with a floating-point tick count can be - constructed from an integer value) 4) Constructs a duration by converting d to an appropriate period and tick count, as - if by std::chrono::duration_cast(d).count(). In order to prevent - truncation during conversion, this constructor only participates in overload - resolution if no overflow is induced by conversion and: - - * std::chrono::treat_as_floating_point::value == true - - or both: + if by std::chrono::duration_cast(d).count(). + This overload participates in overload resolution only if no overflow is induced in + the conversion, and any of the following conditions is satisfied:^[2] + * std::chrono::treat_as_floating_point::value is true. + * All following conditions are satisfied: - * std::ratio_divide::den == 1, and - * std::chrono::treat_as_floating_point::value == false. - - (that is, either the duration uses floating-point ticks, or Period2 is exactly - divisible by period) + * std::ratio_divide::den is 1. + * std::chrono::treat_as_floating_point::value is false. + 1. ↑ That is, a duration with an integer tick count cannot be constructed from a + floating-point value, but a duration with a floating-point tick count can be + constructed from an integer value. + 2. ↑ That is, either the duration uses floating-point ticks, or Period2 is exactly + divisible by Period. .SH Parameters @@ -46,30 +47,47 @@ The following code shows several examples (both valid and invalid) of how to construct durations: - + // Run this code #include + int main() { std::chrono::hours h(1); // one hour std::chrono::milliseconds ms{3}; // 3 milliseconds std::chrono::duration ks(3); // 3000 seconds - + // error: treat_as_floating_point::value == false, // This duration allows whole tick counts only // std::chrono::duration d3(3.5); - + // 30Hz clock using fractional ticks std::chrono::duration> hz30(3.5); - + // 3000 microseconds constructed from 3 milliseconds std::chrono::microseconds us = ms; // error: 1/1000000 is not divisible by 1/1000 // std::chrono::milliseconds ms2 = us + std::chrono::duration ms2 = us; // 3.0 milliseconds } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload (4) does + for overload (4), std::ratio_divide::num participate in + might overflow when evaluating overload + std::ratio_divide::den resolution in this + case + LWG 3050 C++11 convertibility constraint used non-const use const lvalues + xvalue instead + .SH See also operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::chrono::duration::max.3 b/man/std::chrono::duration::max.3 index cc51fdedd..4ac258ae8 100644 --- a/man/std::chrono::duration::max.3 +++ b/man/std::chrono::duration::max.3 @@ -1,6 +1,10 @@ -.TH std::chrono::duration::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::max \- std::chrono::duration::max + .SH Synopsis - static constexpr duration max(); + static constexpr duration max(); \fI(until C++20)\fP + static constexpr duration max() noexcept; \fI(since C++20)\fP Returns a duration with the largest possible value. @@ -14,11 +18,57 @@ .SH Return value - returns std::chrono::duration(std::chrono::duration_values::max()) + duration(std::chrono::duration_values::max()) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr uint64_t chrono_years_max = std::chrono::years::max().count(); + constexpr uint64_t chrono_seconds_max = std::chrono::seconds::max().count(); + + constexpr uint64_t age_of_universe_in_years{13'787'000'000}; // Λ-CDM ≈ k₁/H₀ = k₂/42 + constexpr uint64_t seconds_per_year{365'25 * 24 * 36}; // 365¼ × 24 × 60 × 60 + constexpr uint64_t age_of_universe_in_seconds{age_of_universe_in_years * + seconds_per_year}; + std::cout + << std::scientific << std::setprecision(2) + << "The Age of the Universe is ≈ " + << static_cast(age_of_universe_in_years) << " years or " + << static_cast(age_of_universe_in_seconds) << " seconds.\\n\\n" + << "chrono::years::max() = " << chrono_years_max + << ", sizeof(chrono::years) = " + << sizeof(std::chrono::years) << " bytes.\\n" "chrono::years " + << (age_of_universe_in_years <= chrono_years_max ? "CAN" : "CANNOT") + << " keep the Age of the Universe in YEARS.\\n\\n" + << "chrono::seconds::max() = " << chrono_seconds_max + << ", sizeof(chrono::seconds) = " + << sizeof(std::chrono::seconds) << " bytes.\\n" "chrono::seconds " + << (age_of_universe_in_seconds <= chrono_seconds_max ? "CAN" : "CANNOT") + << " keep the Age of the Universe in SECONDS.\\n"; + } + +.SH Possible output: + + The Age of the Universe is ≈ 1.38e+10 years or 4.35e+17 seconds. + + chrono::years::max() = 2147483647, sizeof(chrono::years) = 4 bytes. + chrono::years CANNOT keep the Age of the Universe in YEARS. + + chrono::seconds::max() = 9223372036854775807, sizeof(chrono::seconds) = 8 bytes. + chrono::seconds CAN keep the Age of the Universe in SECONDS. .SH See also zero returns the special duration value zero - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP min returns the special duration value min - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::duration::min.3 b/man/std::chrono::duration::min.3 index 8b8930012..38eb3aecb 100644 --- a/man/std::chrono::duration::min.3 +++ b/man/std::chrono::duration::min.3 @@ -1,6 +1,10 @@ -.TH std::chrono::duration::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::min \- std::chrono::duration::min + .SH Synopsis - static constexpr duration min(); + static constexpr duration min(); \fI(until C++20)\fP + static constexpr duration min() noexcept; \fI(since C++20)\fP Returns a duration with the lowest possible value. @@ -14,11 +18,11 @@ .SH Return value - returns std::chrono::duration(std::chrono::duration_values::min()) + duration(std::chrono::duration_values::min()) .SH See also zero returns the special duration value zero - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the special duration value max - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::duration::operator+(unary),.3 b/man/std::chrono::duration::operator+(unary),.3 new file mode 100644 index 000000000..5b85edce8 --- /dev/null +++ b/man/std::chrono::duration::operator+(unary),.3 @@ -0,0 +1,62 @@ +.TH std::chrono::duration::operator+(unary), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::operator+(unary), \- std::chrono::duration::operator+(unary), + +.SH Synopsis + + constexpr duration operator+() const; \fI(until C++17)\fP + constexpr std::common_type_t \fI(since C++17)\fP + operator+() const; \fB(1)\fP + constexpr duration operator-() const; \fI(until C++17)\fP + constexpr std::common_type_t \fB(2)\fP \fI(since C++17)\fP + operator-() const; + + Implements unary plus and unary minus for the durations. + + If rep_ is a member variable holding the number of ticks in a duration object, and D + is the return type, + + 1) Equivalent to return D(*this);. + 2) Equivalent to return D(-rep_);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A copy of this duration object. + 2) A copy of this duration object, with the number of ticks negated. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::seconds s1(-052); + constexpr std::chrono::seconds s2 = -s1; + + std::cout << "Negated " << s1 << " are " << s2 << '\\n'; + } + +.SH Output: + + Negated -42s are 42s + +.SH See also + + operator++ + operator++(int) increments or decrements the tick count + operator-- \fI(public member function)\fP + operator--(int) + operator+ + operator- + operator* implements arithmetic operations with durations as arguments + operator/ \fI(function template)\fP + operator% + \fI(C++11)\fP diff --git a/man/std::chrono::duration::operator+(unary),std::chrono::duration::operator-(unary).3 b/man/std::chrono::duration::operator+(unary),std::chrono::duration::operator-(unary).3 deleted file mode 100644 index bf821a86e..000000000 --- a/man/std::chrono::duration::operator+(unary),std::chrono::duration::operator-(unary).3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH std::chrono::duration::operator+(unary),std::chrono::duration::operator-(unary) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - constexpr duration operator+() const; \fB(1)\fP - constexpr duration operator-() const; \fB(2)\fP - - Implements unary plus and unary minus for the durations. - - If rep_ is a member variable holding the number of ticks in a duration object, - - 1) Equivalent to return *this; - 2) Equivalent to return duration(-rep_); - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - 1) a copy of this duration object - 2) a copy of this duration object, with the number of ticks negated - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::chrono::seconds s1(10); - std::chrono::seconds s2 = -s1; - - std::cout << "negated 10 seconds are " << s2.count() << " seconds\\n"; - } - -.SH Output: - - negated 10 seconds are -10 seconds - -.SH See also - - operator++ - operator++(int) increments or decrements the tick count - operator-- \fI(public member function)\fP - operator--(int) - operator+ - operator- implements arithmetic operations with durations as arguments - operator* \fI(function template)\fP - operator/ - operator% diff --git a/man/std::chrono::duration::operator++,.3 b/man/std::chrono::duration::operator++,.3 new file mode 100644 index 000000000..ba0b446da --- /dev/null +++ b/man/std::chrono::duration::operator++,.3 @@ -0,0 +1,66 @@ +.TH std::chrono::duration::operator++, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::operator++, \- std::chrono::duration::operator++, + +.SH Synopsis + + duration& operator++(); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + duration operator++( int ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++17) + duration& operator--(); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++17) + duration operator--( int ); \fB(4)\fP \fI(since C++11)\fP + (constexpr since C++17) + + Increments or decrements the number of ticks for this duration. + + If rep_ is a member variable holding the number of ticks in a duration object, + + 1) Equivalent to ++rep_; return *this;. + 2) Equivalent to return duration(rep_++). + 3) Equivalent to --rep_; return *this;. + 4) Equivalent to return duration(rep_--);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) A reference to this duration after modification. + 2,4) A copy of the duration made before modification. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::hours h(1); + std::chrono::minutes m = ++h; + m--; + std::cout << m.count() << " minutes\\n"; + } + +.SH Output: + + 119 minutes + +.SH See also + + operator+= + operator-= implements compound assignment between two durations + operator*= \fI(public member function)\fP + operator/= + operator%= + operator+ + operator- + operator* implements arithmetic operations with durations as arguments + operator/ \fI(function template)\fP + operator% + \fI(C++11)\fP diff --git a/man/std::chrono::duration::operator++,std::chrono::duration::operator--.3 b/man/std::chrono::duration::operator++,std::chrono::duration::operator--.3 deleted file mode 100644 index 237feec51..000000000 --- a/man/std::chrono::duration::operator++,std::chrono::duration::operator--.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH std::chrono::duration::operator++,std::chrono::duration::operator-- 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - duration& operator++(); \fB(1)\fP - duration operator++(int); \fB(2)\fP - duration& operator--(); \fB(3)\fP - duration operator--(int); \fB(4)\fP - - Increments or decrements the number of ticks for this duration. - - If rep_ is a member variable holding the number of ticks in a duration object, - - 1) Equivalent to ++rep_; return *this; - 2) Equivalent to return duration(rep_++) - 3) Equivalent to --rep_; return *this; - 4) Equivalent to return duration(rep_--); - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - 1,3) a reference to this duration after modification - 2,4) a copy of the duration made before modification - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::chrono::hours h(1); - std::chrono::minutes m = ++h; - m--; - std::cout << m.count() << " minutes\\n"; - } - -.SH Output: - - 119 minutes - -.SH See also - - operator+= - operator-= implements compound assignment between two durations - operator*= \fI(public member function)\fP - operator/= - operator%= - operator+ - operator- implements arithmetic operations with durations as arguments - operator* \fI(function template)\fP - operator/ - operator% diff --git a/man/std::chrono::duration::operator=.3 b/man/std::chrono::duration::operator=.3 index 35fd6bf1d..6e5d38587 100644 --- a/man/std::chrono::duration::operator=.3 +++ b/man/std::chrono::duration::operator=.3 @@ -1,4 +1,7 @@ -.TH std::chrono::duration::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::operator= \- std::chrono::duration::operator= + .SH Synopsis duration& operator=( const duration &other ) = default; \fI(since C++11)\fP @@ -8,7 +11,59 @@ other - duration to copy from +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono_literals; + + std::chrono::hours z_hours{}; + std::chrono::seconds z_seconds{}; + + z_hours = 2h; // ok, no conversion needed + + z_seconds = z_hours; + // First, the converting ctor is used to create a temporary object of `lhs`s type. + // This ctor implicitly invokes the casting function + // chrono::duration_cast(z_hours). The resulting `rhs` rvalue + // has the same type as `lhs`, and the `operator=` finally performs the assignment. + + std::cout << "hours: " << z_hours.count() << '\\n'; + std::cout << "seconds: " << z_seconds.count() << '\\n'; + + z_seconds -= 42s; + + // z_hours = z_seconds; // compile-time error (which is good): incompatible types. + // The library avoids the implicit cast to prevent a potential precision loss. + + z_hours = std::chrono::duration_cast(z_seconds); // ok + z_hours = std::chrono::duration_cast(z_seconds); // ditto + + std::cout << "hours: " << z_hours.count() << '\\n'; + std::cout << "seconds: " << z_seconds.count() << '\\n'; + + std::chrono::duration> z2_hours{}; + + z2_hours = z_seconds; // ok, no truncation, implicit cast + + std::cout << "hours: " << z2_hours.count() << '\\n'; + } + +.SH Output: + + hours: 2 + seconds: 7200 + hours: 1 + seconds: 7158 + hours: 1.98833 + .SH See also constructor constructs new duration - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::chrono::duration::zero.3 b/man/std::chrono::duration::zero.3 index e8bf19249..7c2ba4445 100644 --- a/man/std::chrono::duration::zero.3 +++ b/man/std::chrono::duration::zero.3 @@ -1,6 +1,10 @@ -.TH std::chrono::duration::zero 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration::zero 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration::zero \- std::chrono::duration::zero + .SH Synopsis - static constexpr duration zero(); + static constexpr duration zero(); \fI(until C++20)\fP + static constexpr duration zero() noexcept; \fI(since C++20)\fP Returns a zero-length duration. @@ -14,11 +18,32 @@ .SH Return value - returns std::chrono::duration(std::chrono::duration_values::zero()) + Returns duration(std::chrono::duration_values::zero()). + +.SH Example + + +// Run this code + + #include + #include + + template + using dura = std::chrono::duration; + + static_assert + ( + (std::chrono::hours::zero() == std::chrono::nanoseconds::zero()) && + (dura::zero() == dura::zero()) && + (dura::zero() == dura::zero()) && + (dura::zero().count() == dura::zero().count()) + ); + + int main() {} .SH See also min returns the special duration value min - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the special duration value max - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::duration_cast.3 b/man/std::chrono::duration_cast.3 index 1e459cf3e..07d4d6a8c 100644 --- a/man/std::chrono::duration_cast.3 +++ b/man/std::chrono::duration_cast.3 @@ -1,14 +1,22 @@ -.TH std::chrono::duration_cast 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration_cast \- std::chrono::duration_cast + .SH Synopsis - template \fI(since C++11)\fP - constexpr ToDuration duration_cast(const duration& d); + Defined in header + template< class ToDuration, class Rep, class Period > + constexpr ToDuration duration_cast( const \fI(since C++11)\fP + std::chrono::duration& d ); Converts a std::chrono::duration to a duration of different type ToDuration. + The function does not participate in overload resolution unless ToDuration is a + specialization of std::chrono::duration. + No implicit conversions are used. Multiplications and divisions are avoided where possible, if it is known at compile time that one or more parameters are 1. - Computations are done in the widest type available and converted to the result type - only when finished. + Computations are done in the widest type available and converted, as if by + static_cast, to the result type only when finished. .SH Parameters @@ -20,39 +28,69 @@ .SH Notes - The function does not participate in the overload resolution unless ToDuration is an - instance of std::chrono::duration. + Casting between integer durations where the source period is exactly divisible by + the target period (e.g. hours to minutes) or between floating-point durations can be + performed with ordinary casts or implicitly via std::chrono::duration constructors, + no duration_cast is needed. - Casting between floating-point durations or between integer durations where the - source period is exactly divisible by the target period (e.g. hours to minutes) can - be performed implicitly, no duration_cast is needed. + Casting from a floating-point duration to an integer duration is subject to + undefined behavior when the floating-point value is NaN, infinity, or too large to + be representable by the target's integer type. Otherwise, casting to an integer + duration is subject to truncation as with any static_cast to an integer type. .SH Example - This example measures the execution time of a function + This example measures the execution time of a function. + - // Run this code - #include #include + #include + #include #include - + void f() { std::this_thread::sleep_for(std::chrono::seconds(1)); } - + int main() { - auto t1 = std::chrono::high_resolution_clock::now(); + const auto t1 = std::chrono::high_resolution_clock::now(); f(); - auto t2 = std::chrono::high_resolution_clock::now(); - std::cout << "f() took " - << std::chrono::duration_cast(t2 - t1).count() - << " milliseconds\\n"; + const auto t2 = std::chrono::high_resolution_clock::now(); + + // floating-point duration: no duration_cast needed + const std::chrono::duration fp_ms = t2 - t1; + + // integral duration: requires duration_cast + const auto int_ms = std::chrono::duration_cast(t2 - t1); + + // converting integral duration to integral duration of + // shorter divisible time unit: no duration_cast needed + const std::chrono::duration int_usec = int_ms; + + std::cout << "f() took " << fp_ms << ", or " + << int_ms << " (whole milliseconds), or " + << int_usec << " (whole microseconds)\\n"; } -.SH Output: +.SH Possible output: + + f() took 1000.14ms, or 1000ms (whole milliseconds), or 1000000us (whole microseconds) + +.SH See also - f() took 1000 milliseconds + duration a time interval + \fI(C++11)\fP \fI(class template)\fP + time_point_cast converts a time point to another time point on the same + \fI(C++11)\fP clock, with a different duration + \fI(function template)\fP + floor(std::chrono::duration) converts a duration to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + ceil(std::chrono::duration) converts a duration to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::duration) converts a duration to another, rounding to nearest, + \fI(C++17)\fP ties to even + \fI(function template)\fP diff --git a/man/std::chrono::duration_values.3 b/man/std::chrono::duration_values.3 index 1e80b27a1..c11441bd9 100644 --- a/man/std::chrono::duration_values.3 +++ b/man/std::chrono::duration_values.3 @@ -1,7 +1,10 @@ -.TH std::chrono::duration_values 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration_values 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration_values \- std::chrono::duration_values + .SH Synopsis Defined in header - template \fI(since C++11)\fP + template< class Rep > \fI(since C++11)\fP struct duration_values; The std::chrono::duration_values type defines three common durations: @@ -10,8 +13,8 @@ * std::chrono::duration_values::min * std::chrono::duration_values::max - The zero, min, and max methods in std::chrono::duration forward their work to these - methods. + The zero, min, and max static member functions in std::chrono::duration forward + their work to these functions. This type can be specialized if the representation Rep requires a specific implementation to return these duration objects. @@ -19,8 +22,8 @@ .SH Member functions zero returns a zero-length representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP min returns the smallest possible representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the largest possible representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::duration_values::max.3 b/man/std::chrono::duration_values::max.3 index b6a88462d..f93e23f05 100644 --- a/man/std::chrono::duration_values::max.3 +++ b/man/std::chrono::duration_values::max.3 @@ -1,6 +1,11 @@ -.TH std::chrono::duration_values::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration_values::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration_values::max \- std::chrono::duration_values::max + .SH Synopsis - static constexpr Rep max(); + static constexpr Rep max(); \fI(since C++11)\fP + \fI(until C++20)\fP + static constexpr Rep max() noexcept; \fI(since C++20)\fP Returns the largest possible representation. @@ -10,13 +15,13 @@ .SH Return value - returns std::numeric_limits::max() + std::numeric_limits::max() .SH See also max returns the special duration value max - \fB[static]\fP \fI(public static member function of std::chrono::duration)\fP + \fB[static]\fP \fI(public static member function of std::chrono::duration)\fP zero returns a zero-length representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP min returns the smallest possible representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::duration_values::min.3 b/man/std::chrono::duration_values::min.3 index 83d83a228..5aa984f33 100644 --- a/man/std::chrono::duration_values::min.3 +++ b/man/std::chrono::duration_values::min.3 @@ -1,6 +1,11 @@ -.TH std::chrono::duration_values::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration_values::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration_values::min \- std::chrono::duration_values::min + .SH Synopsis - static constexpr Rep min(); + static constexpr Rep min(); \fI(since C++11)\fP + \fI(until C++20)\fP + static constexpr Rep min() noexcept; \fI(since C++20)\fP Returns the lowest possible representation. @@ -10,13 +15,13 @@ .SH Return value - returns std::numeric_limits::lowest() + std::numeric_limits::lowest() .SH See also min returns the special duration value min - \fB[static]\fP \fI(public static member function of std::chrono::duration)\fP + \fB[static]\fP \fI(public static member function of std::chrono::duration)\fP zero returns a zero-length representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the largest possible representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::duration_values::zero.3 b/man/std::chrono::duration_values::zero.3 index 8b2b53ea1..c089ea4f3 100644 --- a/man/std::chrono::duration_values::zero.3 +++ b/man/std::chrono::duration_values::zero.3 @@ -1,6 +1,11 @@ -.TH std::chrono::duration_values::zero 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::duration_values::zero 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::duration_values::zero \- std::chrono::duration_values::zero + .SH Synopsis - static constexpr Rep zero(); + static constexpr Rep zero(); \fI(since C++11)\fP + \fI(until C++20)\fP + static constexpr Rep zero() noexcept; \fI(since C++20)\fP Returns a zero-length representation. @@ -10,13 +15,13 @@ .SH Return value - returns Rep\fB(0)\fP + Rep\fB(0)\fP .SH See also zero returns the special duration value zero - \fB[static]\fP \fI(public static member function of std::chrono::duration)\fP + \fB[static]\fP \fI(public static member function of std::chrono::duration)\fP min returns the smallest possible representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the largest possible representation - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::file_clock.3 b/man/std::chrono::file_clock.3 new file mode 100644 index 000000000..1f7b0d547 --- /dev/null +++ b/man/std::chrono::file_clock.3 @@ -0,0 +1,48 @@ +.TH std::chrono::file_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::file_clock \- std::chrono::file_clock + +.SH Synopsis + Defined in header + using file_clock = /* see below */; \fI(since C++20)\fP + + std::chrono::file_clock is an alias for the clock used for + std::filesystem::file_time_type. Its epoch is unspecified. + + file_clock meets the TrivialClock requirements. + +.SH Member types + + Member type Definition + rep signed arithmetic type representing the number of ticks in the clock's + duration + period a std::ratio type representing the tick period of the clock, in seconds + duration std::chrono::duration, capable of representing negative + durations + time_point std::chrono::time_point + +.SH Member constants + + true if the time between ticks is always constant, i.e. + constexpr bool is_steady calls to now() return values that increase monotonically + \fB[static]\fP even in case of some external clock adjustment, otherwise + false + \fI(public static member constant)\fP + +.SH Member functions + + file_clock provides exactly one of the following two pairs of static member + functions: + + * to_utc and from_utc; or + * to_sys and from_sys. + + now returns a std::chrono::time_point representing the current point + \fB[static]\fP in time + \fI(public static member function)\fP + to_utc converts between file_time and utc_time + from_utc \fI(public static member function)\fP + \fB[static]\fP (optional) + to_sys converts between file_time and sys_time + from_sys \fI(public static member function)\fP + \fB[static]\fP (optional) diff --git a/man/std::chrono::file_clock::now.3 b/man/std::chrono::file_clock::now.3 new file mode 100644 index 000000000..958c79c4d --- /dev/null +++ b/man/std::chrono::file_clock::now.3 @@ -0,0 +1,61 @@ +.TH std::chrono::file_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::file_clock::now \- std::chrono::file_clock::now + +.SH Synopsis + static std::chrono::time_point now() \fI(since C++20)\fP + noexcept; + + Returns a time point representing the current point in time. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A time point representing the current time. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + volatile int sink; + + void do_some_work(std::size_t size) + { + std::vector v(size, 42); + sink = std::accumulate(v.begin(), v.end(), 0); // make sure it is a side effect + } + + int main() + { + std::cout << std::fixed << std::setprecision(9) << std::left; + for (auto size{1ull}; size < 10'00'00'00'00ull; size *= 100) + { + const auto start = std::chrono::file_clock::now(); + do_some_work(size); + const auto end = std::chrono::file_clock::now(); + + const std::chrono::duration diff = end - start; + + std::cout << "Time to fill and iterate a vector of " << std::setw(9) + << size << " ints : " << diff << '\\n'; + } + } + +.SH Possible output: + + Time to fill and iterate a vector of 1 ints : 0.000006568s + Time to fill and iterate a vector of 100 ints : 0.000002854s + Time to fill and iterate a vector of 10000 ints : 0.000116290s + Time to fill and iterate a vector of 1000000 ints : 0.011742752s + Time to fill and iterate a vector of 100000000 ints : 0.505534949s diff --git a/man/std::chrono::file_clock::to_sys,std::chrono::file_clock::from_sys.3 b/man/std::chrono::file_clock::to_sys,std::chrono::file_clock::from_sys.3 new file mode 100644 index 000000000..189cb3ddd --- /dev/null +++ b/man/std::chrono::file_clock::to_sys,std::chrono::file_clock::from_sys.3 @@ -0,0 +1,50 @@ +.TH std::chrono::file_clock::to_sys,std::chrono::file_clock::from_sys 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::file_clock::to_sys,std::chrono::file_clock::from_sys \- std::chrono::file_clock::to_sys,std::chrono::file_clock::from_sys + +.SH Synopsis + template< class Duration > + \fI(since C++20)\fP + static std::chrono::sys_time \fB(1)\fP (optional) + + to_sys( const std::chrono::file_time& t ); + template< class Duration > + \fI(since C++20)\fP + static std::chrono::file_time \fB(2)\fP (optional) + + from_sys( const std::chrono::sys_time& t ); + + 1) Converts the file_time t to a sys_time representing the same point in time. + 2) Converts the sys_time t to a file_time representing the same point in time. + + The duration of the return type is computed from Duration in an unspecified manner. + + These function templates are optional: an implementation may choose to instead + provide to_utc and from_utc. + +.SH Return value + + 1) A sys_time representing the same point in time as the argument. + 2) A file_time representing the same point in time as the argument. + +.SH Notes + + User code should usually use std::chrono::clock_cast, which provides a generic + interface to convert time points between clocks, rather than call these functions + directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + to_utc converts between file_time and utc_time + from_utc \fI(public static member function)\fP + \fB[static]\fP (optional) + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::file_clock::to_utc,std::chrono::file_clock::from_utc.3 b/man/std::chrono::file_clock::to_utc,std::chrono::file_clock::from_utc.3 new file mode 100644 index 000000000..76f27e8c2 --- /dev/null +++ b/man/std::chrono::file_clock::to_utc,std::chrono::file_clock::from_utc.3 @@ -0,0 +1,50 @@ +.TH std::chrono::file_clock::to_utc,std::chrono::file_clock::from_utc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::file_clock::to_utc,std::chrono::file_clock::from_utc \- std::chrono::file_clock::to_utc,std::chrono::file_clock::from_utc + +.SH Synopsis + template< class Duration > + \fI(since C++20)\fP + static std::chrono::utc_time \fB(1)\fP (optional) + + to_utc( const std::chrono::file_time& t ); + template< class Duration > + \fI(since C++20)\fP + static std::chrono::file_time \fB(2)\fP (optional) + + from_utc( const std::chrono::utc_time& t ); + + 1) Converts the file_time t to a utc_time representing the same point in time. + 2) Converts the utc_time t to a file_time representing the same point in time. + + The duration of the return type is computed from Duration in an unspecified manner. + + These function templates are optional: an implementation may choose to instead + provide to_sys and from_sys. + +.SH Return value + + 1) A utc_time representing the same point in time as the argument. + 2) A file_time representing the same point in time as the argument. + +.SH Notes + + User code should usually use std::chrono::clock_cast, which provides a generic + interface to convert time points between clocks, rather than call these functions + directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + to_sys converts between file_time and sys_time + from_sys \fI(public static member function)\fP + \fB[static]\fP (optional) + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::floor(std::chrono::duration).3 b/man/std::chrono::floor(std::chrono::duration).3 new file mode 100644 index 000000000..525ab770d --- /dev/null +++ b/man/std::chrono::floor(std::chrono::duration).3 @@ -0,0 +1,98 @@ +.TH std::chrono::floor(std::chrono::duration) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::floor(std::chrono::duration) \- std::chrono::floor(std::chrono::duration) + +.SH Synopsis + Defined in header + template< class ToDuration, class Rep, class Period > + constexpr ToDuration floor( const std::chrono::duration& \fI(since C++17)\fP + d ); + + Returns the greatest duration t representable in ToDuration that is less or equal to + d. + + The function does not participate in the overload resolution unless ToDuration is a + specialization of std::chrono::duration. + +.SH Parameters + + d - duration to convert + +.SH Return value + + d rounded down to a duration of type ToDuration. + +.SH Possible implementation + + namespace detail + { + template inline constexpr bool is_duration_v = false; + template inline constexpr bool is_duration_v< + std::chrono::duration> = true; + } + + template>> + constexpr To floor(const duration& d) + { + To t = std::chrono::duration_cast(d); + if (t > d) + return t - To{1}; + return t; + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::chrono_literals; + std::cout << "Duration\\tFloor\\tRound\\tCeil\\n"; + for (using Sec = std::chrono::seconds; + auto const d : {+4999ms, +5000ms, +5001ms, +5499ms, +5500ms, +5999ms, + -4999ms, -5000ms, -5001ms, -5499ms, -5500ms, -5999ms}) + std::cout << std::showpos << d << "\\t\\t" + << std::chrono::floor(d) << '\\t' + << std::chrono::round(d) << '\\t' + << std::chrono::ceil (d) << '\\n'; + } + +.SH Output: + + Duration Floor Round Ceil + +4999ms +4s +5s +5s + +5000ms +5s +5s +5s + +5001ms +5s +5s +6s + +5499ms +5s +5s +6s + +5500ms +5s +6s +6s + +5999ms +5s +6s +6s + -4999ms -5s -5s -4s + -5000ms -5s -5s -5s + -5001ms -6s -5s -5s + -5499ms -6s -5s -5s + -5500ms -6s -6s -5s + -5999ms -6s -6s -5s + +.SH See also + + duration_cast converts a duration to another, with a different tick + \fI(C++11)\fP interval + \fI(function template)\fP + ceil(std::chrono::duration) converts a duration to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::duration) converts a duration to another, rounding to nearest, + \fI(C++17)\fP ties to even + \fI(function template)\fP + floor(std::chrono::time_point) converts a time_point to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + floor + floorf nearest integer not greater than the given value + floorl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::floor(std::chrono::time_point).3 b/man/std::chrono::floor(std::chrono::time_point).3 new file mode 100644 index 000000000..1b0a90442 --- /dev/null +++ b/man/std::chrono::floor(std::chrono::time_point).3 @@ -0,0 +1,105 @@ +.TH std::chrono::floor(std::chrono::time_point) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::floor(std::chrono::time_point) \- std::chrono::floor(std::chrono::time_point) + +.SH Synopsis + Defined in header + template< class ToDuration, class Clock, class Duration > + + constexpr std::chrono::time_point \fI(since C++17)\fP + + floor( const std::chrono::time_point& tp ); + + Returns the largest time point t representable in ToDuration that is smaller or + equal to tp. + + The function does not participate in the overload resolution unless ToDuration is a + specialization of std::chrono::duration. + +.SH Parameters + + tp - time point to round down + +.SH Return value + + tp rounded down to the next time point using duration of type ToDuration. + +.SH Possible implementation + + namespace detail + { + template inline constexpr bool is_duration_v = false; + template inline constexpr bool is_duration_v< + std::chrono::duration> = true; + } + + template>> + constexpr std::chrono::time_point + floor(const std::chrono::time_point& tp) + { + return std::chrono::time_point{ + std::chrono::floor(tp.time_since_epoch())}; + } + +.SH Example + + + +// Run this code + + #include + #include + #include + + template + std::string to_string(const TimePoint& time_point) + { + return std::to_string(time_point.time_since_epoch().count()); + } + + int main() + { + using namespace std::literals::chrono_literals; + using Sec = std::chrono::seconds; + + std::cout << "Time point\\t" "Cast\\t" "Floor\\t" "Round\\t" "Ceil\\n"; + std::cout << "(ms)\\t\\t" "(s)\\t" "(s)\\t" "(s)\\t" "(s)\\n"; + for (const auto value_ms : {5432ms, 5678ms}) + { + std::chrono::time_point + time_point_ms(value_ms); + + std::cout + << to_string(time_point_ms) << "\\t\\t" + << to_string(std::chrono::time_point_cast(time_point_ms)) << '\\t' + << to_string(std::chrono::floor(time_point_ms)) << '\\t' + << to_string(std::chrono::round(time_point_ms)) << '\\t' + << to_string(std::chrono::ceil(time_point_ms)) << '\\n'; + } + } + +.SH Output: + + Time point Cast Floor Round Ceil + (ms) (s) (s) (s) (s) + 5432 5 5 5 6 + 5678 5 5 6 6 + +.SH See also + + time_point_cast converts a time point to another time point on the + \fI(C++11)\fP same clock, with a different duration + \fI(function template)\fP + ceil(std::chrono::time_point) converts a time_point to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::time_point) converts a time_point to another, rounding to + \fI(C++17)\fP nearest, ties to even + \fI(function template)\fP + floor(std::chrono::duration) converts a duration to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + floor + floorf nearest integer not greater than the given value + floorl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::from_stream(std::chrono::day).3 b/man/std::chrono::from_stream(std::chrono::day).3 new file mode 100644 index 000000000..14a50cdca --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::day).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::day) \- std::chrono::from_stream(std::chrono::day) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::day& d, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::day d according to the + format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into d according to the format string fmt. If the parse fails to + decode a valid day, is.setstate(std::ios_base::failbit) is called and d is not + modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + d - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::duration).3 b/man/std::chrono::from_stream(std::chrono::duration).3 new file mode 100644 index 000000000..506afeb7f --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::duration).3 @@ -0,0 +1,250 @@ +.TH std::chrono::from_stream(std::chrono::duration) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::duration) \- std::chrono::from_stream(std::chrono::duration) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Rep, class Period, + + class Alloc = std::allocator > + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::duration& d, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::duration d, interpreted + as the time of day since midnight, according to the format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into d according to the format string fmt. If the parse fails to + decode a valid duration, is.setstate(std::ios_base::failbit) is called and d is not + modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + d - std::chrono::duration object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::istringstream is{"16:14:34"}; + is.imbue(std::locale("en_US.utf-8")); + std::chrono::hours hh; + is >> std::chrono::from_stream("%H:%M:%S", hh); + is.fail() ? std::cout << "Parse failed!\\n" : std::cout << hh.count() << '\\n'; + } + +.SH Possible output: + + 16 + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::file_time).3 b/man/std::chrono::from_stream(std::chrono::file_time).3 new file mode 100644 index 000000000..25ee8ee57 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::file_time).3 @@ -0,0 +1,239 @@ +.TH std::chrono::from_stream(std::chrono::file_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::file_time) \- std::chrono::from_stream(std::chrono::file_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::file_time& tp, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the time point tp according to the format + string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into tp according to the format string fmt. If the parse fails + to decode a valid time point, is.setstate(std::ios_base::failbit) is called and tp + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null, and the parsed offset will be subtracted from the parsed + timestamp before the difference is assigned to tp. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + tp - time point object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + number of characters to read. The default width is 2 if Duration is + convertible to std::chrono::seconds, otherwise it is determined by the + %S decimal precision of Duration and the field is interpreted as a long + %NS double in a fixed format, with the decimal point character determined by + %OS the locale (if encountered). Leading zeroes are permitted but not + required. + + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::from_stream(std::chrono::gps_time).3 b/man/std::chrono::from_stream(std::chrono::gps_time).3 new file mode 100644 index 000000000..c26f5dc09 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::gps_time).3 @@ -0,0 +1,239 @@ +.TH std::chrono::from_stream(std::chrono::gps_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::gps_time) \- std::chrono::from_stream(std::chrono::gps_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::gps_time& tp, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the time point tp according to the format + string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into tp according to the format string fmt. If the parse fails + to decode a valid time point, is.setstate(std::ios_base::failbit) is called and tp + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null, and the parsed offset will be subtracted from the parsed + timestamp before the difference is assigned to tp. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + tp - time point object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + number of characters to read. The default width is 2 if Duration is + convertible to std::chrono::seconds, otherwise it is determined by the + %S decimal precision of Duration and the field is interpreted as a long + %NS double in a fixed format, with the decimal point character determined by + %OS the locale (if encountered). Leading zeroes are permitted but not + required. + + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::from_stream(std::chrono::local_time).3 b/man/std::chrono::from_stream(std::chrono::local_time).3 new file mode 100644 index 000000000..c7e004047 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::local_time).3 @@ -0,0 +1,243 @@ +.TH std::chrono::from_stream(std::chrono::local_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::local_time) \- std::chrono::from_stream(std::chrono::local_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::local_time& tp, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the time point tp according to the format + string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into tp according to the format string fmt. If the parse fails + to decode a valid time point, is.setstate(std::ios_base::failbit) is called and tp + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + tp - time point object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + number of characters to read. The default width is 2 if Duration is + convertible to std::chrono::seconds, otherwise it is determined by the + %S decimal precision of Duration and the field is interpreted as a long + %NS double in a fixed format, with the decimal point character determined by + %OS the locale (if encountered). Leading zeroes are permitted but not + required. + + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Notes + + This overload does not subtract the parsed offset (if any) from the parsed + timestamp, unlike the from_stream overloads for the time_point of other clocks. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::from_stream(std::chrono::month).3 b/man/std::chrono::from_stream(std::chrono::month).3 new file mode 100644 index 000000000..f706eebd7 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::month).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::month) \- std::chrono::from_stream(std::chrono::month) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::month& m, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::month m according to the + format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into m according to the format string fmt. If the parse fails to + decode a valid month, is.setstate(std::ios_base::failbit) is called and m is not + modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + m - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::month_day).3 b/man/std::chrono::from_stream(std::chrono::month_day).3 new file mode 100644 index 000000000..d84b5ed41 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::month_day).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::month_day) \- std::chrono::from_stream(std::chrono::month_day) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::month_day& md, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::month_day md according + to the format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into md according to the format string fmt. If the parse fails + to decode a valid month_day, is.setstate(std::ios_base::failbit) is called and md is + not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + md - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::sys_time).3 b/man/std::chrono::from_stream(std::chrono::sys_time).3 new file mode 100644 index 000000000..a19de1672 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::sys_time).3 @@ -0,0 +1,239 @@ +.TH std::chrono::from_stream(std::chrono::sys_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::sys_time) \- std::chrono::from_stream(std::chrono::sys_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::sys_time& tp, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the time point tp according to the format + string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into tp according to the format string fmt. If the parse fails + to decode a valid time point, is.setstate(std::ios_base::failbit) is called and tp + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null, and the parsed offset will be subtracted from the parsed + timestamp before the difference is assigned to tp. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + tp - time point object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + number of characters to read. The default width is 2 if Duration is + convertible to std::chrono::seconds, otherwise it is determined by the + %S decimal precision of Duration and the field is interpreted as a long + %NS double in a fixed format, with the decimal point character determined by + %OS the locale (if encountered). Leading zeroes are permitted but not + required. + + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::from_stream(std::chrono::tai_time).3 b/man/std::chrono::from_stream(std::chrono::tai_time).3 new file mode 100644 index 000000000..ef9539233 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::tai_time).3 @@ -0,0 +1,239 @@ +.TH std::chrono::from_stream(std::chrono::tai_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::tai_time) \- std::chrono::from_stream(std::chrono::tai_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::tai_time& tp, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the time point tp according to the format + string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into tp according to the format string fmt. If the parse fails + to decode a valid time point, is.setstate(std::ios_base::failbit) is called and tp + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null, and the parsed offset will be subtracted from the parsed + timestamp before the difference is assigned to tp. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + tp - time point object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + number of characters to read. The default width is 2 if Duration is + convertible to std::chrono::seconds, otherwise it is determined by the + %S decimal precision of Duration and the field is interpreted as a long + %NS double in a fixed format, with the decimal point character determined by + %OS the locale (if encountered). Leading zeroes are permitted but not + required. + + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::from_stream(std::chrono::utc_time).3 b/man/std::chrono::from_stream(std::chrono::utc_time).3 new file mode 100644 index 000000000..9324bd39d --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::utc_time).3 @@ -0,0 +1,239 @@ +.TH std::chrono::from_stream(std::chrono::utc_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::utc_time) \- std::chrono::from_stream(std::chrono::utc_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::utc_time& tp, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the time point tp according to the format + string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into tp according to the format string fmt. If the parse fails + to decode a valid time point, is.setstate(std::ios_base::failbit) is called and tp + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null, and the parsed offset will be subtracted from the parsed + timestamp before the difference is assigned to tp. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + tp - time point object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + number of characters to read. The default width is 2 if Duration is + convertible to std::chrono::seconds, otherwise it is determined by the + %S decimal precision of Duration and the field is interpreted as a long + %NS double in a fixed format, with the decimal point character determined by + %OS the locale (if encountered). Leading zeroes are permitted but not + required. + + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::from_stream(std::chrono::weekday).3 b/man/std::chrono::from_stream(std::chrono::weekday).3 new file mode 100644 index 000000000..f4a0cea23 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::weekday).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::weekday) \- std::chrono::from_stream(std::chrono::weekday) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::weekday& wd, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::weekday wd according to + the format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into wd according to the format string fmt. If the parse fails + to decode a valid weekday, is.setstate(std::ios_base::failbit) is called and wd is + not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + wd - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::year).3 b/man/std::chrono::from_stream(std::chrono::year).3 new file mode 100644 index 000000000..e5f42946c --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::year).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::year) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::year) \- std::chrono::from_stream(std::chrono::year) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::year& y, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::year y according to the + format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into y according to the format string fmt. If the parse fails to + decode a valid year, is.setstate(std::ios_base::failbit) is called and y is not + modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + y - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::year_month).3 b/man/std::chrono::from_stream(std::chrono::year_month).3 new file mode 100644 index 000000000..6afad1947 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::year_month).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::year_month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::year_month) \- std::chrono::from_stream(std::chrono::year_month) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::year_month& ym, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::year_month ym according + to the format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into ym according to the format string fmt. If the parse fails + to decode a valid year_month, is.setstate(std::ios_base::failbit) is called and ym + is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + ym - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::from_stream(std::chrono::year_month_day).3 b/man/std::chrono::from_stream(std::chrono::year_month_day).3 new file mode 100644 index 000000000..c46eae808 --- /dev/null +++ b/man/std::chrono::from_stream(std::chrono::year_month_day).3 @@ -0,0 +1,227 @@ +.TH std::chrono::from_stream(std::chrono::year_month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::from_stream(std::chrono::year_month_day) \- std::chrono::from_stream(std::chrono::year_month_day) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc = + std::allocator > + + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* + fmt, \fI(since C++20)\fP + std::chrono::year_month_day& ymd, + std::basic_string* abbrev = + nullptr, + + std::chrono::minutes* offset = nullptr ); + + Attempts to parse the input stream is into the std::chrono::year_month_day ymd + according to the format string fmt. + + Behaves as an UnformattedInputFunction, except that it has an unspecified effect on + is.gcount(). After constructing and checking the sentry object, attempts to parse + the input stream is into ymd according to the format string fmt. If the parse fails + to decode a valid year_month_day, is.setstate(std::ios_base::failbit) is called and + ymd is not modified. + + If the format specifier %Z is used and successfully parsed, the parsed value is + assigned to *abbrev if abbrev is not null. If the format specifier %z or a modified + variant is used and successfully parsed, the parsed value is assigned to *offset if + offset is not null. + +.SH Parameters + + is - an input stream + fmt - a format string (see below) + ymd - object to hold the parse result + abbrev - if not null, pointer to an object that will hold the time zone abbreviation + or name corresponding to the %Z specifier + offset - if not null, pointer to an object that will hold the offset from UTC + corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Return value + + is + +.SH See also + + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::get_leap_second_info.3 b/man/std::chrono::get_leap_second_info.3 new file mode 100644 index 000000000..ab7bdc036 --- /dev/null +++ b/man/std::chrono::get_leap_second_info.3 @@ -0,0 +1,35 @@ +.TH std::chrono::get_leap_second_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::get_leap_second_info \- std::chrono::get_leap_second_info + +.SH Synopsis + Defined in header + template< class Duration > + + std::chrono::leap_second_info \fI(since C++20)\fP + + get_leap_second_info( const std::chrono::utc_time& ut + ); + + Obtains a std::chrono::leap_second_info whose is_leap_second and elapsed indicate + whether ut is during a positive leap second insertion and the sum of leap seconds + between 1 January 1970 and ut, respectively. + +.SH Parameters + + ut - UTC time to examine + +.SH Return value + + A leap_second_info value specified above. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH See also + + leap_second_info leap second insertion information + (C++20) \fI(class)\fP + leap_second contains information about a leap second insertion + (C++20) \fI(class)\fP diff --git a/man/std::chrono::get_tzdb_list,std::chrono::get_tzdb,std::chrono::remote_version,.3 b/man/std::chrono::get_tzdb_list,std::chrono::get_tzdb,std::chrono::remote_version,.3 new file mode 100644 index 000000000..f8f37042c --- /dev/null +++ b/man/std::chrono::get_tzdb_list,std::chrono::get_tzdb,std::chrono::remote_version,.3 @@ -0,0 +1,39 @@ +.TH std::chrono::get_tzdb_list,std::chrono::get_tzdb,std::chrono::remote_version, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::get_tzdb_list,std::chrono::get_tzdb,std::chrono::remote_version, \- std::chrono::get_tzdb_list,std::chrono::get_tzdb,std::chrono::remote_version, + +.SH Synopsis + + std::chrono::tzdb_list& get_tzdb_list(); \fB(1)\fP \fI(since C++20)\fP + const std::chrono::tzdb& get_tzdb(); \fB(2)\fP \fI(since C++20)\fP + std::string remote_version(); \fB(3)\fP \fI(since C++20)\fP + const std::chrono::tzdb& reload_tzdb(); \fB(4)\fP \fI(since C++20)\fP + + These functions provide access to the program-wide time zone database. + + 1) Returns a reference to the global std::chrono::tzdb_list singleton. If this is + the first access to the database, initialize the database. After the initialization, + the database will hold a single initialized std::chrono::tzdb object. This function + is thread-safe: concurrent calls to this function from multiple threads do not + introduce a data race. + 2) Returns a reference to the first std::chrono::tzdb object held by the tzdb_list + singleton. Equivalent to std::chrono::get_tzdb_list().front(). + 3) Returns a string containing the latest remote database version. + 4) If remote_version() != get_tzdb().version, pushes a new tzdb object representing + the remote database to the front of the tzdb_list singleton referenced by + get_tzdb_list(). Otherwise there are no effects. No references, pointers or + iterators are invalidated. Calling this function concurrently with + get_tzdb_list().front() or get_tzdb_list().erase_after() does not introduce a data + race. + +.SH Exceptions + + 1) std::runtime_error if for any reason a reference to a tzdb_list containing one or + more valid tzdb cannot be returned. + +.SH Return value + + 1) A reference to the global std::chrono::tzdb_list singleton. + 2) std::chrono::get_tzdb_list().front(). + 3) A string containing the latest remote database version. + 4) std::chrono::get_tzdb_list().front() (after any update made by this function). diff --git a/man/std::chrono::gps_clock.3 b/man/std::chrono::gps_clock.3 new file mode 100644 index 000000000..e0d2865e5 --- /dev/null +++ b/man/std::chrono::gps_clock.3 @@ -0,0 +1,47 @@ +.TH std::chrono::gps_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::gps_clock \- std::chrono::gps_clock + +.SH Synopsis + Defined in header + class gps_clock; \fI(since C++20)\fP + + The clock std::chrono::gps_clock is a Clock that represents Global Positioning + System (GPS) time. It measures time since 00:00:00, 6 January 1980 UTC. + + Leap seconds are not inserted into GPS. Thus, every time a leap second is inserted + into UTC, UTC falls another second behind GPS. As of December 2017, UTC is 18 + seconds behind GPS, reflecting the 18 leap seconds inserted between 1980 and 2017. + Thus, 2018-01-01 00:00:00 UTC is equivalent to 2018-01-01 00:00:18 GPS. GPS is a + constant 19 seconds behind TAI. + + gps_clock meets the Clock requirements. It does not meet the TrivialClock + requirements unless the implementation can guarantee that now() does not throw an + exception. + +.SH Member types + + Member type Definition + rep signed arithmetic type representing the number of ticks in the clock's + duration + period a std::ratio type representing the tick period of the clock, in seconds + duration std::chrono::duration, capable of representing negative + durations + time_point std::chrono::time_point + +.SH Member constants + + true if the time between ticks is always constant, i.e. + constexpr bool is_steady calls to now() return values that increase monotonically + \fB[static]\fP even in case of some external clock adjustment, otherwise + false + \fI(public static member constant)\fP + +.SH Member functions + + now returns a std::chrono::time_point representing the current point in time + \fB[static]\fP \fI(public static member function)\fP + to_utc converts a gps_time to utc_time + \fB[static]\fP \fI(public static member function)\fP + from_utc converts a utc_time to gps_time + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::gps_clock::from_utc.3 b/man/std::chrono::gps_clock::from_utc.3 new file mode 100644 index 000000000..208dc53fe --- /dev/null +++ b/man/std::chrono::gps_clock::from_utc.3 @@ -0,0 +1,35 @@ +.TH std::chrono::gps_clock::from_utc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::gps_clock::from_utc \- std::chrono::gps_clock::from_utc + +.SH Synopsis + template< class Duration > + + static std::chrono::gps_time> + + from_utc( const std::chrono::utc_time& ) noexcept; + + Converts the utc_time t to a gps_time representing the same point in time. + +.SH Return value + + A std::chrono::gps_time representing the same point in time as t, computed as if by + constructing a value of the return type from t.time_since_epoch() and subtracting + 315964809s (315964809 is the number of seconds between the epochs of the two clocks: + 1980-01-06 00:00:00 UTC for gps_clock and 1970-01-01 00:00:00 UTC for utc_clock). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + to_utc converts a gps_time to utc_time + \fB[static]\fP \fI(public static member function)\fP + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::gps_clock::now.3 b/man/std::chrono::gps_clock::now.3 new file mode 100644 index 000000000..19e57734a --- /dev/null +++ b/man/std::chrono::gps_clock::now.3 @@ -0,0 +1,62 @@ +.TH std::chrono::gps_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::gps_clock::now \- std::chrono::gps_clock::now + +.SH Synopsis + static std::chrono::time_point now(); \fI(since C++20)\fP + + Returns a time point representing the current point in time. The result is + calculated as if by std::chrono::gps_clock::from_utc(std::chrono::utc_clock::now()). + Implementations may use a more accurate value of GPS time. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A time point representing the current time. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + volatile int sink; + + void do_some_work(std::size_t size) + { + std::vector v(size, 42); + sink = std::accumulate(v.begin(), v.end(), 0); // make sure it is a side effect + } + + int main() + { + std::cout << std::fixed << std::setprecision(9) << std::left; + for (auto size{1ull}; size < 10'00'00'00'00ull; size *= 100) + { + const auto start = std::chrono::gps_clock::now(); + do_some_work(size); + const auto end = std::chrono::gps_clock::now(); + + const std::chrono::duration diff = end - start; + + std::cout << "Time to fill and iterate a vector of " << std::setw(9) + << size << " ints : " << diff << '\\n'; + } + } + +.SH Possible output: + + Time to fill and iterate a vector of 1 ints : 0.000006568s + Time to fill and iterate a vector of 100 ints : 0.000002854s + Time to fill and iterate a vector of 10000 ints : 0.000116290s + Time to fill and iterate a vector of 1000000 ints : 0.011742752s + Time to fill and iterate a vector of 100000000 ints : 0.505534949s diff --git a/man/std::chrono::gps_clock::to_utc.3 b/man/std::chrono::gps_clock::to_utc.3 new file mode 100644 index 000000000..a9e678807 --- /dev/null +++ b/man/std::chrono::gps_clock::to_utc.3 @@ -0,0 +1,35 @@ +.TH std::chrono::gps_clock::to_utc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::gps_clock::to_utc \- std::chrono::gps_clock::to_utc + +.SH Synopsis + template< class Duration > + + static std::chrono::utc_time> + + to_utc( const std::chrono::gps_time& t ) noexcept; + + Converts the gps_time t to a utc_time representing the same point in time. + +.SH Return value + + A std::chrono::utc_time representing the same point in time as t, computed as if by + constructing a value of the return type from t.time_since_epoch() and adding + 315964809s (315964809 is the number of seconds between the epochs of the two clocks: + 1980-01-06 00:00:00 UTC for gps_clock and 1970-01-01 00:00:00 UTC for utc_clock). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + from_utc converts a utc_time to gps_time + \fB[static]\fP \fI(public static member function)\fP + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::hh_mm_ss.3 b/man/std::chrono::hh_mm_ss.3 new file mode 100644 index 000000000..365829107 --- /dev/null +++ b/man/std::chrono::hh_mm_ss.3 @@ -0,0 +1,51 @@ +.TH std::chrono::hh_mm_ss 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::hh_mm_ss \- std::chrono::hh_mm_ss + +.SH Synopsis + Defined in header + template< class Duration > \fI(since C++20)\fP + class hh_mm_ss; + + The class template hh_mm_ss splits a std::chrono::duration into a "broken down" time + such as hours:minutes:seconds, with the precision of the split determined by the + Duration template parameter. It is primarily a formatting tool. + + Duration must be a specialization of std::chrono::duration, otherwise the program is + ill-formed. + +.SH Member constants + + constexpr unsigned the smallest possible integer in the range [0, 18] such that + fractional_width precision (see below) will exactly represent the value of + \fB[static]\fP Duration{1}, or 6 if there's no such integer + \fI(public static member constant)\fP + +.SH Member types + + Member type Definition + std::chrono::duration, std::ratio<1, + 10^fractional_width>> + +.SH Member functions + + constructor constructs a hh_mm_ss + \fI(public member function)\fP + is_negative + hours obtains components of the broken-down time + minutes \fI(public member function)\fP + seconds + subseconds + operator precision obtains the stored std::chrono::duration + to_duration \fI(public member function)\fP + +.SH Non-member functions + + operator<< outputs a hh_mm_ss into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for hh_mm_ss + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::hh_mm_ss::hh_mm_ss.3 b/man/std::chrono::hh_mm_ss::hh_mm_ss.3 new file mode 100644 index 000000000..bbc11b3a8 --- /dev/null +++ b/man/std::chrono::hh_mm_ss::hh_mm_ss.3 @@ -0,0 +1,48 @@ +.TH std::chrono::hh_mm_ss::hh_mm_ss 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::hh_mm_ss::hh_mm_ss \- std::chrono::hh_mm_ss::hh_mm_ss + +.SH Synopsis + constexpr hh_mm_ss() noexcept : hh_mm_ss{Duration::zero()} {} \fB(1)\fP + constexpr explicit hh_mm_ss( Duration d ); \fB(2)\fP + + Constructs a hh_mm_ss object. + + 1) Constructs a hh_mm_ss object corresponding to Duration::zero(). + 2) Constructs a hh_mm_ss object corresponding to d: + * is_negative() returns d < Duration::zero(). + * hours() returns std::chrono::duration_cast(abs(d)). + * minutes() returns std::chrono::duration_cast(abs(d) - + hours()). + * seconds() returns + std::chrono::duration_cast(abs(d) - hours() - minutes()). + * subseconds() returns abs(d) - hours() - minutes() - seconds() if + std::chrono::treat_as_floating_point_v is true; otherwise it + returns std::chrono::duration_cast(abs(d) - hours() - minutes() - + seconds()). + +.SH Parameters + + d - the duration to be broken down + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::println("Default constructor: {}", std::chrono::hh_mm_ss{}); + + std::chrono::time_point now = std::chrono::system_clock::now(); + std::chrono::hh_mm_ss time_of_day{now - std::chrono::floor(now)}; + std::println("The time of day is: {}", time_of_day); + } + +.SH Possible output: + + Default constructor: 00:00:00 + The time of day is: 12:13:14.151617189 diff --git a/man/std::chrono::hh_mm_ss::is_negative,std::chrono::hh_mm_ss::hours,.3 b/man/std::chrono::hh_mm_ss::is_negative,std::chrono::hh_mm_ss::hours,.3 new file mode 100644 index 000000000..3ccce562f --- /dev/null +++ b/man/std::chrono::hh_mm_ss::is_negative,std::chrono::hh_mm_ss::hours,.3 @@ -0,0 +1,34 @@ +.TH std::chrono::hh_mm_ss::is_negative,std::chrono::hh_mm_ss::hours, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::hh_mm_ss::is_negative,std::chrono::hh_mm_ss::hours, \- std::chrono::hh_mm_ss::is_negative,std::chrono::hh_mm_ss::hours, + +.SH Synopsis + std::chrono::hh_mm_ss::subseconds + + constexpr bool is_negative() const noexcept; \fB(1)\fP + constexpr std::chrono::hours hours() const noexcept; \fB(2)\fP + constexpr std::chrono::minutes minutes() const noexcept; \fB(3)\fP + constexpr std::chrono::seconds seconds() const noexcept; \fB(4)\fP + constexpr precision subseconds() const noexcept; \fB(5)\fP + + Obtains the components of the stored "broken down" time. + +.SH Return value + + Let d be the represented duration: + + 1) true if d is negative, false otherwise. + 2) std::chrono::duration_cast(abs(d)) + 3) std::chrono::duration_cast(abs(d) - hours()) + 4) std::chrono::duration_cast(abs(d) - hours() - minutes()) + 5) abs(d) - hours() - minutes() - seconds() if + std::chrono::treat_as_floating_point_v is true; otherwise + std::chrono::duration_cast(abs(d) - hours() - minutes() - seconds()). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::chrono::hh_mm_ss::operatorprecision,.3 b/man/std::chrono::hh_mm_ss::operatorprecision,.3 new file mode 100644 index 000000000..671c343b2 --- /dev/null +++ b/man/std::chrono::hh_mm_ss::operatorprecision,.3 @@ -0,0 +1,22 @@ +.TH std::chrono::hh_mm_ss::operatorprecision, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::hh_mm_ss::operatorprecision, \- std::chrono::hh_mm_ss::operatorprecision, + +.SH Synopsis + + constexpr explicit operator precision() const noexcept; \fB(1)\fP + constexpr precision to_duration() const noexcept; \fB(2)\fP + + Returns the represented duration. + +.SH Return value + + The represented duration. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::chrono::high_resolution_clock.3 b/man/std::chrono::high_resolution_clock.3 index 21f9eb94d..04dcce126 100644 --- a/man/std::chrono::high_resolution_clock.3 +++ b/man/std::chrono::high_resolution_clock.3 @@ -1,4 +1,7 @@ -.TH std::chrono::high_resolution_clock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::high_resolution_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::high_resolution_clock \- std::chrono::high_resolution_clock + .SH Synopsis Defined in header class high_resolution_clock; \fI(since C++11)\fP @@ -22,7 +25,8 @@ true if the time between ticks is always constant, i.e. constexpr bool is_steady calls to now() return values that increase monotonically - \fB[static]\fP even in case of some external clock adjustment + \fB[static]\fP even in case of some external clock adjustment, otherwise + false \fI(public static member constant)\fP .SH Member functions @@ -31,9 +35,39 @@ \fB[static]\fP clock \fI(public static member function)\fP +.SH Notes + + There has been some controversy around the use of high_resolution_clock. Howard + Hinnant, who claims to have introduced high_resolution_clock to the language, stated + in 2016 on the ISO C++ Standard - Discussion mailing list that he was in favor of + deprecating it. His rationale was that, because the standard allows for it to be an + alias for std::chrono::steady_clock or std::chrono::system_clock, its use adds + uncertainty to a program without benefit. However, other participants in the thread + spoke out its favor, for instance on the basis that, because neither + std::chrono::steady_clock nor std::chrono::system_clock come with any particular + resolution guarantees, high_resolution_clock serves a useful role by giving the + vendor an opportunity to supply the platform's highest-resolution clock, when + neither its std::chrono::steady_clock nor its std::chrono::system_clock would be + that. + + It is often just an alias for std::chrono::steady_clock or + std::chrono::system_clock, but which one it is depends on the library or + configuration. When it is a system_clock, it is not monotonic (e.g., the time can go + backwards). For example, as of 2023, libstdc++ has it aliased to system_clock "until + higher-than-nanosecond definitions become feasible"^[1], MSVC has it as + steady_clock^[2], and libc++ uses steady_clock when the C++ standard library + implementation supports a monotonic clock and system_clock otherwise^[3]. + .SH See also system_clock wall clock time from the system-wide realtime clock \fI(C++11)\fP \fI(class)\fP steady_clock monotonic clock that will never be adjusted \fI(C++11)\fP \fI(class)\fP + +.SH External links + + + 1. ↑ libstdc++ + 2. ↑ msvc high_resolution_clock + 3. ↑ libc++ diff --git a/man/std::chrono::high_resolution_clock::now.3 b/man/std::chrono::high_resolution_clock::now.3 index 43dddafa7..7d220bfa2 100644 --- a/man/std::chrono::high_resolution_clock::now.3 +++ b/man/std::chrono::high_resolution_clock::now.3 @@ -1,9 +1,12 @@ -.TH std::chrono::high_resolution_clock::now 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::high_resolution_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::high_resolution_clock::now \- std::chrono::high_resolution_clock::now + .SH Synopsis - static std::chrono::time_point (since - now(); C++11) + static std::chrono::time_point now() (since + noexcept; C++11) - Returns a time point representing with the current point in time. + Returns a time point representing the current point in time. .SH Parameters @@ -13,39 +16,46 @@ A time point representing the current time. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code + #include + #include + #include #include + #include #include - #include - + + volatile int sink; + + void do_some_work(std::size_t size) + { + std::vector v(size, 42); + sink = std::accumulate(v.begin(), v.end(), 0); // make sure it is a side effect + } + int main() { - for (unsigned long long size = 1; size < 10000000; size *= 10) { - auto start = std::chrono::high_resolution_clock::now(); - std::vector v(size, 42); - auto end = std::chrono::high_resolution_clock::now(); - - auto elapsed = end - start; - std::cout << size << ": " << elapsed.count() << '\\n'; + std::cout << std::fixed << std::setprecision(9) << std::left; + for (auto size{1ull}; size < 10'00'00'00'00ull; size *= 100) + { + const auto start = std::chrono::high_resolution_clock::now(); + do_some_work(size); + const auto end = std::chrono::high_resolution_clock::now(); + + const std::chrono::duration diff = end - start; + + std::cout << "Time to fill and iterate a vector of " << std::setw(9) + << size << " ints : " << diff << '\\n'; } } .SH Possible output: - 1: 1 - 10: 2 - 100: 3 - 1000: 6 - 10000: 47 - 100000: 507 - 1000000: 4822 + Time to fill and iterate a vector of 1 ints : 0.000006568s + Time to fill and iterate a vector of 100 ints : 0.000002854s + Time to fill and iterate a vector of 10000 ints : 0.000116290s + Time to fill and iterate a vector of 1000000 ints : 0.011742752s + Time to fill and iterate a vector of 100000000 ints : 0.505534949s diff --git a/man/std::chrono::is_am,std::chrono::is_pm,std::chrono::make12,std::chrono::make24.3 b/man/std::chrono::is_am,std::chrono::is_pm,std::chrono::make12,std::chrono::make24.3 new file mode 100644 index 000000000..4e513a8d3 --- /dev/null +++ b/man/std::chrono::is_am,std::chrono::is_pm,std::chrono::make12,std::chrono::make24.3 @@ -0,0 +1,93 @@ +.TH std::chrono::is_am,std::chrono::is_pm,std::chrono::make12,std::chrono::make24 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::is_am,std::chrono::is_pm,std::chrono::make12,std::chrono::make24 \- std::chrono::is_am,std::chrono::is_pm,std::chrono::make12,std::chrono::make24 + +.SH Synopsis + Defined in header + constexpr bool is_am( const std::chrono::hours& h ) noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool is_pm( const std::chrono::hours& h ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::hours make12( const std::chrono::hours& h ) \fB(3)\fP \fI(since C++20)\fP + noexcept; + constexpr std::chrono::hours make24( const std::chrono::hours& h, \fB(4)\fP \fI(since C++20)\fP + bool is_pm ) noexcept; + + These functions aid in translating between a 12-hour format time of day, and a + 24-hour format time of day. + + 1) Detects whether the 24-hour format time is a.m. (ante meridiem, before midday). + 2) Detects whether the 24-hour format time is p.m. (post meridiem, after midday). + 3) Returns the 12-hour equivalent of a 24-hour format time. + 4) Returns the 24-hour equivalent of a 12-hour format time h, where is_pm determines + whether the time is p.m. + +.SH Parameters + + h - 12-hour or 24-hour format time to detect + is_pm - whether the 12-hour format time is p.m. + +.SH Return value + + 1) 0h <= h && h <= 11h + 2) 12h <= h && h <= 23h + 3) If h is in range [0h, 23h], returns the 12-hour equivalent in range [1h, 12h]. + Otherwise, the return value is unspecified. + 4) If h is in range [1h, 12h], returns the 24-hour equivalent in range [0h, 11h] if + is_pm is false, or in range [12h, 23h] otherwise. Otherwise, the return value is + unspecified. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::chrono; + + static_assert( + is_am(10h) && is_am(11h) && !is_am(12h) && !is_am(23h) && + !is_pm(10h) && !is_pm(11h) && is_pm(12h) && is_pm(23h) + ); + + std::cout << "make12():\\n"; + + for (const hours hh : {0h, 1h, 11h, 12h, 13h, 23h}) + { + const hours am{make12(hh)}; + std::cout << std::setw(2) << hh.count() << "h == " + << std::setw(2) << am.count() << (is_am(hh) ? "h a.m.\\n" : "h p.m.\\n"); + } + + std::cout << "\\nmake24():\\n"; + + using p = std::pair; + + for (const auto& [hh, pm] : {p{1h, 0}, p{12h, 0}, p{1h, 1}, p{12h, 1}}) + { + std::cout << std::setw(2) << hh.count() + << (pm ? "h p.m." : "h a.m.") + << " == " << std::setw(2) + << make24(hh, pm).count() << "h\\n"; + } + } + +.SH Output: + + make12(): + 0h == 12h a.m. + 1h == 1h a.m. + 11h == 11h a.m. + 12h == 12h p.m. + 13h == 1h p.m. + 23h == 11h p.m. + + make24(): + 1h a.m. == 1h + 12h a.m. == 0h + 1h p.m. == 13h + 12h p.m. == 12h diff --git a/man/std::chrono::is_clock.3 b/man/std::chrono::is_clock.3 new file mode 100644 index 000000000..b59d98b04 --- /dev/null +++ b/man/std::chrono::is_clock.3 @@ -0,0 +1,97 @@ +.TH std::chrono::is_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::is_clock \- std::chrono::is_clock + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + struct is_clock; + + If T satisfies the Clock requirements, provides the member constant value equal + true. For any other type, value is false. + + For the purpose of this trait, the extent to which an implementation determines that + a type cannot meet the Clock requirements is unspecified, except that a minimum T + shall not qualify as a Clock unless it meets all following conditions: + + * Each of the following qualified identifiers is valid and denotes a type: + + * T::rep + * T::period + * T::duration + * T::time_point + * Each of the following expressions is well-formed when treated as an unevaluated + operand: + + * T::is_steady + * T::now() + + If the program adds specializations for std::is_clock or std::is_clock_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++20)\fP + inline constexpr bool is_clock_v = is_clock::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T satisfies the Clock requirements, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Possible implementation + + template + struct is_clock : std::false_type {}; + + template + requires + requires + { + typename T::rep; + typename T::period; + typename T::duration; + typename T::time_point; + T::is_steady; // not required to be bool + T::now(); // not required to be T::time_point + } + struct is_clock : std::true_type {}; + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + static_assert + ( + std::chrono::is_clock_v + and + not std::chrono::is_clock_v> + ); + } diff --git a/man/std::chrono::last_spec,std::chrono::last.3 b/man/std::chrono::last_spec,std::chrono::last.3 new file mode 100644 index 000000000..0489c9d1d --- /dev/null +++ b/man/std::chrono::last_spec,std::chrono::last.3 @@ -0,0 +1,38 @@ +.TH std::chrono::last_spec,std::chrono::last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::last_spec,std::chrono::last \- std::chrono::last_spec,std::chrono::last + +.SH Synopsis + Defined in header + struct last_spec + + { \fI(since C++20)\fP + explicit last_spec() = default; + + }; + inline constexpr last_spec last{}; \fI(since C++20)\fP + + last_spec is an empty tag type that is used in conjunction with other calendar types + to indicate the last thing in a sequence. Depending on context, it may indicate the + last day of a month (as in 2018y/February/last, for last day of February 2018, i.e., + 2018-02-28) or the last day of the week in a month (as in + 2018/February/Sunday[last], for last Sunday of February 2018, i.e., 2018-02-25). + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::chrono; + + constexpr auto mdl {June/last}; + static_assert(mdl == month_day_last(month(6))); + + constexpr auto ymwdl {year(2023)/December/Tuesday[last]}; + static_assert(ymwdl == + year_month_weekday_last(year(2023), month(12), weekday_last(Tuesday))); + } diff --git a/man/std::chrono::leap_second.3 b/man/std::chrono::leap_second.3 new file mode 100644 index 000000000..09671f970 --- /dev/null +++ b/man/std::chrono::leap_second.3 @@ -0,0 +1,36 @@ +.TH std::chrono::leap_second 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::leap_second \- std::chrono::leap_second + +.SH Synopsis + Defined in header + class leap_second; \fI(since C++20)\fP + + The class leap_second represents the date and time of a leap second insertion. + + Users cannot construct leap_second objects except by copying from existing + leap_second objects. The library implementation creates leap_second objects when it + initializes the time zone database and provides const access to these objects. + + leap_second has a defaulted copy constructor and a defaulted copy assignment + operator. + +.SH Member functions + + date obtains the time of leap second insertion + \fI(public member function)\fP + + Nonmember functions + + operator== + operator< + operator<= compares two leap_second values or a leap_second value and a sys_time + operator> \fI(function template)\fP + operator>= + operator<=> + (C++20) + +.SH Helper classes + + std::hash hash support for std::chrono::leap_second + (C++26) \fI(class template specialization)\fP diff --git a/man/std::chrono::leap_second::date.3 b/man/std::chrono::leap_second::date.3 new file mode 100644 index 000000000..6a2056f1d --- /dev/null +++ b/man/std::chrono::leap_second::date.3 @@ -0,0 +1,13 @@ +.TH std::chrono::leap_second::date 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::leap_second::date \- std::chrono::leap_second::date + +.SH Synopsis + constexpr std::chrono::sys_seconds date() const noexcept; + + Obtains the date and time of the leap second insertion. + +.SH Return value + + A std::chrono::sys_seconds representing the date and time at which the leap second + was inserted. diff --git a/man/std::chrono::leap_second_info.3 b/man/std::chrono::leap_second_info.3 new file mode 100644 index 000000000..078e5967b --- /dev/null +++ b/man/std::chrono::leap_second_info.3 @@ -0,0 +1,35 @@ +.TH std::chrono::leap_second_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::leap_second_info \- std::chrono::leap_second_info + +.SH Synopsis + Defined in header + struct leap_second_info { + + bool is_leap_second; \fI(since C++20)\fP + std::chrono::seconds elapsed; + + }; + + A leap_second_info indicates whether a UTC time is during a positive leap second + insertion and the total number of leap seconds between 1 January 1970 and the UTC + time. + + leap_second_info has no base classes or members other than is_leap_second, elapsed, + and implicitly declared special member functions. + +.SH Member objects + + is_leap_second whether the UTC time is during a positive leap second insertion + \fI(public member object)\fP + elapsed the sum of leap seconds between 1 January 1970 and the UTC time + \fI(public member object)\fP + +.SH Notes + + leap_second_info is typically obtained from std::chrono::get_leap_second_info. + +.SH See also + + leap_second contains information about a leap second insertion + (C++20) \fI(class)\fP diff --git a/man/std::chrono::local_info.3 b/man/std::chrono::local_info.3 new file mode 100644 index 000000000..2b47fd298 --- /dev/null +++ b/man/std::chrono::local_info.3 @@ -0,0 +1,51 @@ +.TH std::chrono::local_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::local_info \- std::chrono::local_info + +.SH Synopsis + Defined in header + struct local_info; \fI(since C++20)\fP + + The class local_info describes the result of converting a std::chrono::local_time to + a std::chrono::sys_time. + + * If the result of the conversion is unique, then result == local_info::unique, + first is filled out with the correct std::chrono::sys_info, and second is + zero-initialized. + * If the local_time is nonexistent, then result == local_info::nonexistent, first + is filled out with the std::chrono::sys_info that ends just prior to the + local_time, and second is filled out with the std::chrono::sys_info that begins + just after the local_time. + * If the local_time is ambiguous, then result == local_info::ambiguous, first is + filled out with the std::chrono::sys_info that ends just after the local_time, + and second is filled with the std::chrono::sys_info that starts just before the + local_time. + + This is a low-level data structure; typical conversions from local_time to sys_time + will use it implicitly rather than explicitly. + +.SH Member constants + + Name Value + constexpr int unique 0 + \fB[static]\fP \fI(public static member constant)\fP + constexpr int nonexistent 1 + \fB[static]\fP \fI(public static member constant)\fP + constexpr int ambiguous 2 + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member objects + + Member object Type + result int + first, second std::chrono::sys_info + + Nonmember functions + + operator<< outputs a local_info into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for local_info + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::local_t.3 b/man/std::chrono::local_t.3 new file mode 100644 index 000000000..11724925c --- /dev/null +++ b/man/std::chrono::local_t.3 @@ -0,0 +1,34 @@ +.TH std::chrono::local_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::local_t \- std::chrono::local_t + +.SH Synopsis + Defined in header + struct local_t {}; \fI(since C++20)\fP + + The class local_t is a pseudo-clock that is used as the first template argument to + std::chrono::time_point to indicate that the time point represents local time with + respect of a not-yet-specified time zone. local_time supports streaming and the full + set of time point arithmetic. + + Time point family + + Defined in namespace std::chrono + template + using local_time = std::chrono::time_point; + using local_seconds = local_time; \fI(since C++20)\fP + using local_days = local_time; \fI(since C++20)\fP + + operator<<(std::chrono::local_time) performs stream output on a local_time + (C++20) \fI(function template)\fP + from_stream(std::chrono::local_time) parses a local_time from a stream according + (C++20) to the provided format + \fI(function template)\fP + std::formatter formatting support for local_time + (C++20) \fI(class template specialization)\fP + +.SH See also + + zoned_time represents a time zone and a time point + (C++20) \fI(class)\fP diff --git a/man/std::chrono::locate_zone.3 b/man/std::chrono::locate_zone.3 new file mode 100644 index 000000000..fbff1ff5d --- /dev/null +++ b/man/std::chrono::locate_zone.3 @@ -0,0 +1,32 @@ +.TH std::chrono::locate_zone 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::locate_zone \- std::chrono::locate_zone + +.SH Synopsis + Defined in header + const std::chrono::time_zone* locate_zone( std::string_view tz_name \fI(since C++20)\fP + ); + + Convenience function for locating a time zone in the time zone database. Equivalent + to std::chrono::get_tzdb().locate_zone(tz_name). + +.SH Exceptions + + std::runtime_error if the specified time zone cannot be found, or if this is the + first reference to the time zone database and the time zone database cannot be + initialized. + +.SH Notes + + A call to this function that is the first reference to the time zone database will + cause it to be initialized. + +.SH See also + + locate_zone locate a time zone with the given name + \fI(public member function of std::chrono::tzdb)\fP + get_tzdb + get_tzdb_list accesses and controls the global time zone database information + reload_tzdb \fI(function)\fP + remote_version + (C++20) diff --git a/man/std::chrono::month.3 b/man/std::chrono::month.3 new file mode 100644 index 000000000..34e2faa2c --- /dev/null +++ b/man/std::chrono::month.3 @@ -0,0 +1,60 @@ +.TH std::chrono::month 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month \- std::chrono::month + +.SH Synopsis + Defined in header + class month; \fI(since C++20)\fP + inline constexpr std::chrono::month January{1}; \fI(since C++20)\fP + inline constexpr std::chrono::month February{2}; \fI(since C++20)\fP + inline constexpr std::chrono::month March{3}; \fI(since C++20)\fP + inline constexpr std::chrono::month April{4}; \fI(since C++20)\fP + inline constexpr std::chrono::month May{5}; \fI(since C++20)\fP + inline constexpr std::chrono::month June{6}; \fI(since C++20)\fP + inline constexpr std::chrono::month July{7}; \fI(since C++20)\fP + inline constexpr std::chrono::month August{8}; \fI(since C++20)\fP + inline constexpr std::chrono::month September{9}; \fI(since C++20)\fP + inline constexpr std::chrono::month October{10}; \fI(since C++20)\fP + inline constexpr std::chrono::month November{11}; \fI(since C++20)\fP + inline constexpr std::chrono::month December{12}; \fI(since C++20)\fP + + The class month represents a month in a year. Its normal range is [1, 12], but it + may hold any number in [0, 255]. Twelve named constants are predefined in the + std::chrono namespace for the twelve months of the year. + + month is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a month + \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the month + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of months + operator-= \fI(public member function)\fP + operator unsigned retrieves the stored month value + \fI(public member function)\fP + ok checks if the stored month value is in the normal range + \fI(public member function)\fP + + Nonmember functions + + operator== compares two month values + operator<=> \fI(function)\fP + (C++20) + operator+ performs arithmetic on months + operator- \fI(function)\fP + (C++20) + operator<< outputs a month into a stream + (C++20) \fI(function template)\fP + from_stream parses a month from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for month + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::month + (C++26) \fI(class template specialization)\fP diff --git a/man/std::chrono::month::month.3 b/man/std::chrono::month::month.3 new file mode 100644 index 000000000..f5c76b8cc --- /dev/null +++ b/man/std::chrono::month::month.3 @@ -0,0 +1,13 @@ +.TH std::chrono::month::month 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month::month \- std::chrono::month::month + +.SH Synopsis + month() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit month( unsigned m ) noexcept; \fB(2)\fP \fI(since C++20)\fP + + Constructs a month object. + + 1) Default constructor leaves the month value uninitialized. + 2) If m <= 255, constructs a month object holding the month value m. Otherwise the + value held is unspecified. diff --git a/man/std::chrono::month::ok.3 b/man/std::chrono::month::ok.3 new file mode 100644 index 000000000..f41945a62 --- /dev/null +++ b/man/std::chrono::month::ok.3 @@ -0,0 +1,37 @@ +.TH std::chrono::month::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month::ok \- std::chrono::month::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the month value stored in *this is in the valid range, i.e., [1, 12]. + +.SH Return value + + true if the month value stored in *this is in the range [1, 12]. Otherwise false. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (const unsigned mm : {6u, 0u, 16U}) + { + std::cout << mm << ": "; + const std::chrono::month m{mm}; + m.ok() ? std::cout << "month is valid\\n" + : std::cout << "month is invalid\\n"; + } + } + +.SH Output: + + 6: month is valid + 0: month is invalid + 16: month is invalid diff --git a/man/std::chrono::month::operator++,std::chrono::month::operator--.3 b/man/std::chrono::month::operator++,std::chrono::month::operator--.3 new file mode 100644 index 000000000..6bb12c299 --- /dev/null +++ b/man/std::chrono::month::operator++,std::chrono::month::operator--.3 @@ -0,0 +1,71 @@ +.TH std::chrono::month::operator++,std::chrono::month::operator-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month::operator++,std::chrono::month::operator-- \- std::chrono::month::operator++,std::chrono::month::operator-- + +.SH Synopsis + constexpr std::chrono::month& operator++() noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::month operator++( int ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::month& operator--() noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr std::chrono::month operator--( int ) noexcept; \fB(4)\fP \fI(since C++20)\fP + + Adds or subtracts 1 from the month value, reducing the result modulo 12 to an + integer in the range [1, 12]. + + 1,2) Performs *this += std::chrono::months{1};. + 3,4) Performs *this -= std::chrono::months{1};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) A reference to this month after modification. + 2,4) A copy of the month made before modification. + +.SH Notes + + After a call to one of these functions, ok() is always true. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::chrono::month m{6}; + + ++m; + assert(m == std::chrono::month(7)); + + --m; + assert(m == std::chrono::month(6)); + + m = std::chrono::December; + m++; // rounds up to January + assert(m.ok()); + std::cout << unsigned(m) << '\\n'; + + m = std::chrono::January; + m--; // rounds down to December + assert(m.ok()); + std::cout << unsigned(m) << '\\n'; + } + +.SH Output: + + 1 + 12 + +.SH See also + + operator+= adds or subtracts a number of months + operator-= \fI(public member function)\fP + operator+ performs arithmetic on months + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::month::operator+=,std::chrono::month::operator-=.3 b/man/std::chrono::month::operator+=,std::chrono::month::operator-=.3 new file mode 100644 index 000000000..200c99156 --- /dev/null +++ b/man/std::chrono::month::operator+=,std::chrono::month::operator-=.3 @@ -0,0 +1,68 @@ +.TH std::chrono::month::operator+=,std::chrono::month::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month::operator+=,std::chrono::month::operator-= \- std::chrono::month::operator+=,std::chrono::month::operator-= + +.SH Synopsis + constexpr std::chrono::month& operator+=( const \fB(1)\fP \fI(since C++20)\fP + std::chrono::months& m ) noexcept; + constexpr std::chrono::month& operator-=( const \fB(2)\fP \fI(since C++20)\fP + std::chrono::months& m ) noexcept; + + Adds or subtracts m.count() from the month value, reducing the result modulo 12 to + an integer in the range [1, 12]. + + 1) Performs *this = *this + m;. + 2) Performs *this = *this - m;. + +.SH Return value + + A reference to this month after modification. + +.SH Notes + + After a call to one of these functions, ok() is always true if no overflow occurred + during the operation. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::month m{6}; + m += std::chrono::months(2); + std::cout << (m == std::chrono::month(8)) << ' ' + << (m == std::chrono::August) << ' '; + + m -= std::chrono::months(3); + std::cout << (m == std::chrono::month(5)) << ' ' + << (m == std::chrono::May) << ' '; + + m = std::chrono::October; + m += std::chrono::months{8}; // ((10 += 8 == 18) % 12) == 6; + std::cout << (m == std::chrono::June) << ' '; + + m -= std::chrono::months{std::chrono::December - std::chrono::February}; // -= 10 + // (6 -= 10) == -4; -4 % 12 == (12 - 4) == 8 + std::cout << (m == std::chrono::August) << '\\n'; + } + +.SH Output: + + true true true true true true + +.SH See also + + operator++ + operator++(int) increments or decrements the month + operator-- \fI(public member function)\fP + operator--(int) + operator+ performs arithmetic on months + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::month::operatorunsigned.3 b/man/std::chrono::month::operatorunsigned.3 new file mode 100644 index 000000000..057218295 --- /dev/null +++ b/man/std::chrono::month::operatorunsigned.3 @@ -0,0 +1,34 @@ +.TH std::chrono::month::operatorunsigned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month::operatorunsigned \- std::chrono::month::operatorunsigned + +.SH Synopsis + constexpr explicit operator unsigned() const noexcept; \fI(since C++20)\fP + + Returns the month value stored in *this. + +.SH Return value + + The month value stored in *this. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::month m{6}; + constexpr unsigned p = static_cast(m); + constexpr unsigned q = static_cast(std::chrono::September); + std::cout << "The month is: " << p << '\\n' + << "September is: " << q << '\\n'; + } + +.SH Output: + + The month is: 6 + September is: 9 diff --git a/man/std::chrono::month_day.3 b/man/std::chrono::month_day.3 new file mode 100644 index 000000000..36a84e263 --- /dev/null +++ b/man/std::chrono::month_day.3 @@ -0,0 +1,38 @@ +.TH std::chrono::month_day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day \- std::chrono::month_day + +.SH Synopsis + Defined in header + class month_day; \fI(since C++20)\fP + + The class month_day represents a specific day of a specific month, of some yet to be + specified year. + + month_day is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a month_day + \fI(public member function)\fP + month retrieve the stored month and day values + day \fI(public member function)\fP + ok checks if the month_day is valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two month_day values + operator<=> \fI(function)\fP + (C++20) + operator<< outputs a month_day into a stream + (C++20) \fI(function template)\fP + from_stream parses a month_day from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for month_day + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::month_day + (C++26) \fI(class template specialization)\fP diff --git a/man/std::chrono::month_day::month,std::chrono::month_day::day.3 b/man/std::chrono::month_day::month,std::chrono::month_day::day.3 new file mode 100644 index 000000000..28ae3955b --- /dev/null +++ b/man/std::chrono::month_day::month,std::chrono::month_day::day.3 @@ -0,0 +1,28 @@ +.TH std::chrono::month_day::month,std::chrono::month_day::day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day::month,std::chrono::month_day::day \- std::chrono::month_day::month,std::chrono::month_day::day + +.SH Synopsis + constexpr std::chrono::month month() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::day day() const noexcept; \fB(1)\fP \fI(since C++20)\fP + + Retrieves the month and day values stored in this month_day object. + +.SH Return value + + 1) Returns the stored std::chrono::month value. + 2) Returns the stored std::chrono::day value. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr auto md{std::chrono::July/15}; + static_assert(md.month() == std::chrono::month(7)); + static_assert(md.day() == std::chrono::day(15)); + } diff --git a/man/std::chrono::month_day::month_day.3 b/man/std::chrono::month_day::month_day.3 new file mode 100644 index 000000000..27e937ab8 --- /dev/null +++ b/man/std::chrono::month_day::month_day.3 @@ -0,0 +1,43 @@ +.TH std::chrono::month_day::month_day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day::month_day \- std::chrono::month_day::month_day + +.SH Synopsis + month_day() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr month_day( const std::chrono::month& m, \fB(2)\fP \fI(since C++20)\fP + const std::chrono::day& d ) noexcept; + + Constructs a month_day. + + 1) Default constructor leaves the stored month and day values uninitialized. + 2) Constructs a month_day that stores the month m and the day d. + +.SH Notes + + A more convenient way to construct a month_day is with operator/, e.g., + std::chrono::April/1. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono_literals; + constexpr auto mo_da = std::chrono::month_day(std::chrono::February, 29d); + std::cout << static_cast(mo_da.day()) << '/' + << static_cast(mo_da.month()) << '\\n'; + } + +.SH Output: + + 29/2 + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::month_day::ok.3 b/man/std::chrono::month_day::ok.3 new file mode 100644 index 000000000..d90c52f8b --- /dev/null +++ b/man/std::chrono::month_day::ok.3 @@ -0,0 +1,40 @@ +.TH std::chrono::month_day::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day::ok \- std::chrono::month_day::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Determines whether this month_day stores a valid month-day combination. + + The combination is valid if month() represents a valid month (month().ok() == true), + unsigned{day()} >= 1, and unsigned{day()} <= D, where D is the number of days in the + month represented by month(). The number of days in February is considered to be 29. + +.SH Return value + + true if the month and day combination is valid, otherwise false. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + constexpr auto md1{std::chrono::July/15}; + std::cout << (md1.ok()) << ' '; + constexpr std::chrono::month_day md2{std::chrono::month(14), std::chrono::day(42)}; + std::cout << (md2.ok()) << ' '; + constexpr auto md3{std::chrono::February/29}; + std::cout << (md3.ok()) << '\\n'; + } + +.SH Output: + + true false true diff --git a/man/std::chrono::month_day_last.3 b/man/std::chrono::month_day_last.3 new file mode 100644 index 000000000..8e90c5bec --- /dev/null +++ b/man/std::chrono::month_day_last.3 @@ -0,0 +1,37 @@ +.TH std::chrono::month_day_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day_last \- std::chrono::month_day_last + +.SH Synopsis + Defined in header + class month_day_last; \fI(since C++20)\fP + + The class month_day_last represents the last day of a specific month, of some yet to + be specified year. + + month_day_last is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a month_day_last + \fI(public member function)\fP + month accesses the stored month + \fI(public member function)\fP + ok checks if the stored month is valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two month_day_last values + operator<=> \fI(function)\fP + (C++20) + operator<< outputs a month_day_last into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for month_day_last + (C++20) \fI(class template specialization)\fP + std::hash hash support for + (C++26) std::chrono::month_day_last + \fI(class template specialization)\fP diff --git a/man/std::chrono::month_day_last::month.3 b/man/std::chrono::month_day_last::month.3 new file mode 100644 index 000000000..62681c038 --- /dev/null +++ b/man/std::chrono::month_day_last::month.3 @@ -0,0 +1,39 @@ +.TH std::chrono::month_day_last::month 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day_last::month \- std::chrono::month_day_last::month + +.SH Synopsis + constexpr std::chrono::month month() const noexcept; \fI(since C++20)\fP + + Retrieves a copy of the std::chrono::month object stored in *this. + +.SH Return value + + A copy of the std::chrono::month object stored in *this. + +.SH Example + + +// Run this code + + #include + #include + + using namespace std::chrono; + + int main() + { + std::cout << std::boolalpha; + + auto mdl{February/last}; // Last day of a February + auto ymdl{year(2020) / mdl}; + std::cout << (year_month_day{ymdl} == year_month_day{February/29/2020}) << ' '; + + mdl = (mdl.month() + months(1)) / last; // Last day of the next month, in 2020 + ymdl = year(2020) / mdl; + std::cout << (year_month_day{ymdl} == year_month_day{March/31/2020}) << '\\n'; + } + +.SH Output: + + true true diff --git a/man/std::chrono::month_day_last::month_day_last.3 b/man/std::chrono::month_day_last::month_day_last.3 new file mode 100644 index 000000000..38ddf8868 --- /dev/null +++ b/man/std::chrono::month_day_last::month_day_last.3 @@ -0,0 +1,19 @@ +.TH std::chrono::month_day_last::month_day_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day_last::month_day_last \- std::chrono::month_day_last::month_day_last + +.SH Synopsis + constexpr explicit month_day_last( const std::chrono::month& m ) \fI(since C++20)\fP + noexcept; + + Constructs a month_day_last object that represents the last day of the month m. + +.SH Notes + + A more convenient way to construct a month_day_last is with operator/, e.g., + std::chrono::April/std::chrono::last. + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::month_day_last::ok.3 b/man/std::chrono::month_day_last::ok.3 new file mode 100644 index 000000000..1e3bfbde7 --- /dev/null +++ b/man/std::chrono::month_day_last::ok.3 @@ -0,0 +1,28 @@ +.TH std::chrono::month_day_last::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_day_last::ok \- std::chrono::month_day_last::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the month object stored in *this is valid. + +.SH Return value + + month().ok() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto mdl{std::chrono::February/std::chrono::last}; + assert(mdl.ok()); + mdl = {std::chrono::month(42)/std::chrono::last}; + assert(!mdl.ok()); + } diff --git a/man/std::chrono::month_weekday.3 b/man/std::chrono::month_weekday.3 new file mode 100644 index 000000000..23c6ffe06 --- /dev/null +++ b/man/std::chrono::month_weekday.3 @@ -0,0 +1,35 @@ +.TH std::chrono::month_weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday \- std::chrono::month_weekday + +.SH Synopsis + header \fI(since C++20)\fP + + The class month_weekday represents the n^th weekday of a specific month, of some yet + to be specified year. + + month_weekday is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a month_weekday + \fI(public member function)\fP + month retrieves the stored month and weekday_indexed values + weekday_indexed \fI(public member function)\fP + ok checks whether the contained month and weekday_indexed are valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two month_weekday values + (C++20) \fI(function)\fP + operator<< outputs a month_weekday into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for month_weekday + (C++20) \fI(class template specialization)\fP + std::hash hash support for + (C++26) std::chrono::month_weekday + \fI(class template specialization)\fP diff --git a/man/std::chrono::month_weekday::month,std::chrono::month_weekday::weekday_indexed.3 b/man/std::chrono::month_weekday::month,std::chrono::month_weekday::weekday_indexed.3 new file mode 100644 index 000000000..6822c06e4 --- /dev/null +++ b/man/std::chrono::month_weekday::month,std::chrono::month_weekday::weekday_indexed.3 @@ -0,0 +1,43 @@ +.TH std::chrono::month_weekday::month,std::chrono::month_weekday::weekday_indexed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday::month,std::chrono::month_weekday::weekday_indexed \- std::chrono::month_weekday::month,std::chrono::month_weekday::weekday_indexed + +.SH Synopsis + constexpr std::chrono::month month() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday_indexed weekday_indexed() const \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Retrieves a copy of the month and weekday_indexed objects stored in *this. + +.SH Return value + + 1) A copy of the std::chrono::month object stored in *this. + 2) A copy of the std::chrono::weekday_indexed object stored in *this. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + auto mwdi{std::chrono::March/std::chrono::Friday[1]}; // 1st Friday in a March + std::cout << (std::chrono::year_month_day{mwdi/2024} == + std::chrono::year_month_day{std::chrono::March/1/2024}) + << ' '; + auto index = mwdi.weekday_indexed().index(); + auto weekday = mwdi.weekday_indexed().weekday(); + mwdi = {mwdi.month(), weekday[index + 4]}; // 5th Friday in a March + std::cout << (std::chrono::year_month_day{mwdi/2024} == + std::chrono::year_month_day{std::chrono::March/29/2024}) + << '\\n'; + } + +.SH Output: + + true true diff --git a/man/std::chrono::month_weekday::month_weekday.3 b/man/std::chrono::month_weekday::month_weekday.3 new file mode 100644 index 000000000..c3bcc86a6 --- /dev/null +++ b/man/std::chrono::month_weekday::month_weekday.3 @@ -0,0 +1,21 @@ +.TH std::chrono::month_weekday::month_weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday::month_weekday \- std::chrono::month_weekday::month_weekday + +.SH Synopsis + constexpr month_weekday( const std::chrono::month& m, + const std::chrono::weekday_indexed& wdi ) \fI(since C++20)\fP + noexcept; + + Constructs a month_weekday object that stores the month m and the weekday_indexed + wdi. + +.SH Notes + + A more convenient way to construct a month_weekday is with operator/, e.g., + std::chrono::April/std::chrono::Sunday[2]. + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::month_weekday::ok.3 b/man/std::chrono::month_weekday::ok.3 new file mode 100644 index 000000000..e5de954a8 --- /dev/null +++ b/man/std::chrono::month_weekday::ok.3 @@ -0,0 +1,32 @@ +.TH std::chrono::month_weekday::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday::ok \- std::chrono::month_weekday::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the contained month and weekday_indexed objects are valid. + +.SH Return value + + month().ok() && weekday_indexed().ok() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto mwdi{std::chrono::March/std::chrono::Friday[1]}; + assert(mwdi.ok()); + + mwdi = {std::chrono::month(17)/std::chrono::Friday[1]}; + assert(not mwdi.ok()); + + mwdi = {std::chrono::March/std::chrono::Friday[-4]}; + assert(not mwdi.ok()); + } diff --git a/man/std::chrono::month_weekday_last.3 b/man/std::chrono::month_weekday_last.3 new file mode 100644 index 000000000..9c3330694 --- /dev/null +++ b/man/std::chrono::month_weekday_last.3 @@ -0,0 +1,38 @@ +.TH std::chrono::month_weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday_last \- std::chrono::month_weekday_last + +.SH Synopsis + Defined in header + class month_weekday_last; \fI(since C++20)\fP + + The class month_weekday_last represents the last weekday of a specific month, of + some yet to be specified year. + + month_weekday_last is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a month_weekday_last + \fI(public member function)\fP + month retrieves the stored month and weekday_last values + weekday_last \fI(public member function)\fP + ok checks whether the contained month and weekday_last are valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two month_weekday_last values + (C++20) \fI(function)\fP + operator<< outputs a month_weekday_last into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + formatting support for + std::formatter month_weekday_last + (C++20) \fI(class template specialization)\fP + + std::hash hash support for + (C++26) std::chrono::month_weekday_last + \fI(class template specialization)\fP diff --git a/man/std::chrono::month_weekday_last::month,std::chrono::month_weekday_last::weekday_last.3 b/man/std::chrono::month_weekday_last::month,std::chrono::month_weekday_last::weekday_last.3 new file mode 100644 index 000000000..c64b3bc78 --- /dev/null +++ b/man/std::chrono::month_weekday_last::month,std::chrono::month_weekday_last::weekday_last.3 @@ -0,0 +1,42 @@ +.TH std::chrono::month_weekday_last::month,std::chrono::month_weekday_last::weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday_last::month,std::chrono::month_weekday_last::weekday_last \- std::chrono::month_weekday_last::month,std::chrono::month_weekday_last::weekday_last + +.SH Synopsis + constexpr std::chrono::month month() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday_last weekday_last() const noexcept; \fB(2)\fP \fI(since C++20)\fP + + Retrieves a copy of the month and weekday_last objects stored in *this. + +.SH Return value + + 1) A copy of the std::chrono::month object stored in *this. + 2) A copy of the std::chrono::weekday_last object stored in *this. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + std::cout << std::boolalpha; + + auto mwdl{March/Friday[last]}; // Last Friday in a March + auto ywdl{year(2024)/mwdl}; + std::cout << (year_month_day{ywdl} == + year_month_day{March/29/2024}) << ' '; + // Last Friday of the next month, in 2024 + mwdl = {(mwdl.month() + months(1))/mwdl.weekday_last()}; + ywdl = {year(2024)/mwdl}; + std::cout << (year_month_day{ywdl} == + year_month_day{April/26/2024}) << '\\n'; + } + +.SH Output: + + true true diff --git a/man/std::chrono::month_weekday_last::month_weekday_last.3 b/man/std::chrono::month_weekday_last::month_weekday_last.3 new file mode 100644 index 000000000..bc6c6d956 --- /dev/null +++ b/man/std::chrono::month_weekday_last::month_weekday_last.3 @@ -0,0 +1,21 @@ +.TH std::chrono::month_weekday_last::month_weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday_last::month_weekday_last \- std::chrono::month_weekday_last::month_weekday_last + +.SH Synopsis + constexpr month_weekday_last( const std::chrono::month& m, + const std::chrono::weekday_last& wdl ) \fI(since C++20)\fP + noexcept; + + Constructs a month_weekday_last object that stores the month m and the weekday_last + wdl. + +.SH Notes + + A more convenient way to construct a month_weekday_last is with operator/, e.g., + std::chrono::April/std::chrono::Sunday[std::chrono::last]. + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::month_weekday_last::ok.3 b/man/std::chrono::month_weekday_last::ok.3 new file mode 100644 index 000000000..2ed2790fb --- /dev/null +++ b/man/std::chrono::month_weekday_last::ok.3 @@ -0,0 +1,34 @@ +.TH std::chrono::month_weekday_last::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::month_weekday_last::ok \- std::chrono::month_weekday_last::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the contained month and weekday_last objects are valid. + +.SH Return value + + month().ok() && weekday_last().ok() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + auto mwdl{std::chrono::March/std::chrono::Wednesday[std::chrono::last]}; + std::cout << (mwdl.ok()) << ' '; + mwdl = {std::chrono::month(3)/std::chrono::weekday(42)[std::chrono::last]}; + std::cout << (mwdl.ok()) << '\\n'; + } + +.SH Output: + + true false diff --git a/man/std::chrono::nonexistent_local_time.3 b/man/std::chrono::nonexistent_local_time.3 new file mode 100644 index 000000000..d46a15d0a --- /dev/null +++ b/man/std::chrono::nonexistent_local_time.3 @@ -0,0 +1,129 @@ +.TH std::chrono::nonexistent_local_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::nonexistent_local_time \- std::chrono::nonexistent_local_time + +.SH Synopsis + Defined in header + class nonexistent_local_time; \fI(since C++20)\fP + + Defines a type of object to be thrown as exception to report that an attempt was + made to convert a nonexistent std::chrono::local_time to a std::chrono::sys_time + without specifying a std::chrono::choose (such as choose::earliest or + choose::latest). + + This exception is thrown by std::chrono::time_zone::to_sys and functions that call + it (such as the constructors of std::chrono::zoned_time that take a + std::chrono::local_time). + + std-chrono-nonexistent local time-inheritance.svg + + Inheritance diagram + +.SH Member functions + + constructor constructs the exception object + \fI(public member function)\fP + operator= replaces the exception object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::chrono::nonexistent_local_time::nonexistent_local_time + + template< class Duration > + + nonexistent_local_time( const std::chrono::local_time& \fB(1)\fP \fI(since C++20)\fP + tp, + + const std::chrono::local_info& i ); + nonexistent_local_time( const nonexistent_local_time& other ) \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Constructs the exception object. + + 1) The explanatory string returned by what() is equivalent to that produced by + os.str() after the following code: + + std::ostringstream os; + os << tp << " is in a gap between\\n" + << std::chrono::local_seconds(i.first.end.time_since_epoch()) + i.first.offset + << ' ' << i.first.abbrev << " and\\n" + << std::chrono::local_seconds(i.second.begin.time_since_epoch()) + i.second.offset + << ' ' << i.second.abbrev + << " which are both equivalent to\\n" + << i.first.end << " UTC"; + + The behavior is undefined if i.result != std::chrono::local_info::nonexistent. + 2) Copy constructor. If *this and other both have dynamic type + std::chrono::nonexistent_local_time then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + tp - the time point for which conversion was attempted + i - a std::chrono::local_info describing the result of the conversion attempt + other - another nonexistent_local_time to copy + +.SH Exceptions + + May throw std::bad_alloc + +.SH Notes + + Because copying a standard library class derived from std::exception is not + permitted to throw exceptions, this message is typically stored internally as a + separately-allocated reference-counted string. + +std::chrono::nonexistent_locale_time::operator= + + nonexistent_locale_time& operator=( const nonexistent_locale_time& \fI(since C++20)\fP + other ) noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::chrono::nonexistent_locale_time then std::strcmp(what(), other.what()) == 0 + after assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::chrono::nonexistent_locale_time::what + + virtual const char* what() const noexcept; \fI(since C++20)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + +Inherited from std::runtime_error + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH See also + + ambiguous_local_time exception thrown to report that a local time is ambiguous + (C++20) \fI(class)\fP diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::day).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::day).3 new file mode 100644 index 000000000..557590f2a --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::day).3 @@ -0,0 +1,64 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::day) \- std::chrono::operator+,std::chrono::operator-(std::chrono::day) + +.SH Synopsis + Defined in header + constexpr std::chrono::day operator+( const std::chrono::day& d, + const std::chrono::days& ds \fB(1)\fP \fI(since C++20)\fP + ) noexcept; + constexpr std::chrono::day operator+( const std::chrono::days& ds, + const std::chrono::day& d ) \fB(2)\fP \fI(since C++20)\fP + noexcept; + constexpr std::chrono::day operator-( const std::chrono::day& d, + const std::chrono::days& ds \fB(3)\fP \fI(since C++20)\fP + ) noexcept; + constexpr std::chrono::days operator-( const std::chrono::day& x, + const std::chrono::day& y ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + + 1,2) Adds ds.count() days to d. + 3) Subtracts ds.count() days from d. + 4) Calculate the difference, in days, between two day x and y. + +.SH Return value + + 1,2) std::chrono::day(unsigned(d) + ds.count()) + 3) std::chrono::day(unsigned(d) - ds.count()) + 4) std::chrono::days(int(unsigned(x)) - int(unsigned(y))) + +.SH Notes + + 1-3) If the result would be outside the range [0, 255], the actual stored value is + unspecified. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::day d{15}; + + d = d + std::chrono::days(2); + assert(d == std::chrono::day(17)); + + d = d - std::chrono::days(3); + assert(d == std::chrono::day(14)); + + constexpr std::chrono::days ds = std::chrono::day(16) - std::chrono::day(14); + static_assert(ds == std::chrono::days(2)); + } + +.SH See also + + operator++ + operator++(int) increments or decrements the day + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of days + operator-= \fI(public member function)\fP diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::month).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::month).3 new file mode 100644 index 000000000..bc097b70e --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::month).3 @@ -0,0 +1,79 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::month) \- std::chrono::operator+,std::chrono::operator-(std::chrono::month) + +.SH Synopsis + Defined in header + constexpr std::chrono::month operator+( const std::chrono::month& + m, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::months& + ms ) noexcept; + constexpr std::chrono::month operator+( const std::chrono::months& + ms, \fB(2)\fP \fI(since C++20)\fP + const std::chrono::month& + m ) noexcept; + constexpr std::chrono::month operator-( const std::chrono::month& + m, \fB(3)\fP \fI(since C++20)\fP + const std::chrono::months& + ms ) noexcept; + constexpr std::chrono::months operator-( const std::chrono::month& + m1, \fB(4)\fP \fI(since C++20)\fP + const std::chrono::month& + m2 ) noexcept; + + 1,2) Adds ms.count() months to m. The month value held in the result is computed by + first evaluating static_cast(unsigned(m)) + (ms.count() - 1), reducing it + modulo 12 to an integer in the range [0, 11], and then adding 1. + 3) Subtracts ms.count() months from m and returns the result. Equivalent to return m + + -ms;. + 4) If m1.ok() and m2.ok() are both true, returns a std::chrono::months value m such + that m.count() is in the range [0, 11] and m2 + m == m1. Otherwise the returned + value is unspecified. + +.SH Return value + + 1-3) A std::chrono::month holding a month value calculated as described above. + 4) A std::chrono::months representing the distance between m1 and m2. + +.SH Notes + + As long as the computation doesn't overflow, (1-3) always return a valid month even + if m.ok() is false. + + The result of subtracting two month values is a duration of type + std::chrono::months. That duration unit represents the length of the average + Gregorian month, and the resulting duration bears no relationship to the number of + days in the particular months represented by the operands. For example, + std::chrono::seconds(std::chrono::April - std::chrono::March) is not the number of + seconds in March (2678400s), but 2629746s (30.436875 days). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::month m{6}; + + m = m + std::chrono::months(2); + assert(m == std::chrono::month(8)); + + m = m - std::chrono::months(3); + assert(m == std::chrono::month(5)); + + constexpr std::chrono::months ms = std::chrono::month(8) - std::chrono::month(6); + static_assert(ms == std::chrono::months(2)); + } + +.SH See also + + operator++ + operator++(int) increments or decrements the month + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of months + operator-= \fI(public member function)\fP diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::weekday).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::weekday).3 new file mode 100644 index 000000000..843113a74 --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::weekday).3 @@ -0,0 +1,82 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::weekday) \- std::chrono::operator+,std::chrono::operator-(std::chrono::weekday) + +.SH Synopsis + Defined in header + constexpr std::chrono::weekday operator+( const + std::chrono::weekday& wd, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::days& + d ) noexcept; + constexpr std::chrono::weekday operator+( const std::chrono::days& + d, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::weekday& wd ) noexcept; + constexpr std::chrono::weekday operator-( const + std::chrono::weekday& wd, \fB(3)\fP \fI(since C++20)\fP + const std::chrono::days& + d ) noexcept; + constexpr std::chrono::days operator-( const std::chrono::weekday& + wd1, \fB(4)\fP \fI(since C++20)\fP + const std::chrono::weekday& + wd2 ) noexcept; + + 1,2) Adds d.count() days to wd. The weekday value held in the result is computed by + first evaluating static_cast(wd.c_encoding()) + d.count() and reducing it + modulo 7 to an integer in the range [0, 6]. + 3) Subtracts d.count() days from wd. Equivalent to return wd + -d;. + 4) If wd1.ok() and wd2.ok() are both true, returns a std::chrono::days value d such + that d.count() is in the range [0, 6] and wd2 + d == wd1. Otherwise the returned + value is unspecified. + +.SH Return value + + 1-3) A std::chrono::weekday holding a weekday value calculated as described above. + 4) A std::chrono::days representing the distance between wd1 and wd2. + +.SH Notes + + As long as the computation doesn't overflow, (1-3) always return a valid weekday + even if wd.ok() is false. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::weekday wd{4}; + wd = wd + std::chrono::days(2); + std::cout << (wd == std::chrono::weekday(6)) << ' ' + << (wd == std::chrono::Saturday) << ' '; + + wd = wd - std::chrono::days(3); + std::cout << (wd == std::chrono::weekday(3)) << ' ' + << (wd == std::chrono::Wednesday) << ' '; + + wd = std::chrono::Tuesday; + wd = wd + std::chrono::days{8}; // (((2 + 8) == 10) % 7) == 3; + std::cout << (wd == std::chrono::Wednesday) << ' '; + + wd = wd + (std::chrono::Sunday - std::chrono::Thursday); // (3 + 3) == 6 + std::cout << (wd == std::chrono::Saturday) << '\\n'; + } + +.SH Output: + + true true true true true true + +.SH See also + + operator++ + operator++(int) increments or decrements the weekday + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of days + operator-= \fI(public member function)\fP diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year).3 new file mode 100644 index 000000000..f7b2395b9 --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year).3 @@ -0,0 +1,74 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::year) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::year) \- std::chrono::operator+,std::chrono::operator-(std::chrono::year) + +.SH Synopsis + constexpr std::chrono::year operator+( const std::chrono::year& y, + const std::chrono::years& \fB(1)\fP \fI(since C++20)\fP + ys ) noexcept; + constexpr std::chrono::year operator+( const std::chrono::years& + ys, \fB(2)\fP \fI(since C++20)\fP + const std::chrono::year& y + ) noexcept; + constexpr std::chrono::year operator-( const std::chrono::year& y, + const std::chrono::years& \fB(3)\fP \fI(since C++20)\fP + ys ) noexcept; + constexpr std::chrono::years operator-( const std::chrono::year& + y1, \fB(4)\fP \fI(since C++20)\fP + const std::chrono::year& + y2 ) noexcept; + + 1,2) Adds ys.count() years to y. + 3) Subtracts ys.count() years from y. + 4) Returns the difference in years between y1 and y2. + +.SH Return value + + 1,2) std::chrono::year(int(y) + ys.count()) + 3) std::chrono::year(int(y) - ys.count()) + 4) std::chrono::years(int(y1) - int(y2)) + +.SH Notes + + If the resulting year value for (1-3) is outside the range [-32767, 32767], the + actual value stored is unspecified. + + The result of subtracting two year values is a duration of type std::chrono::years. + This duration unit represents the length of the average Gregorian year, and the + resulting duration bears no relationship to the number of days in the particular + years represented by the operands. For example, the result of 2018y - 2017y is + std::chrono::years\fB(1)\fP, which represents 365.2425 days, not 365 days. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::year y{2020}; + + y = std::chrono::years(12) + y; // overload (2): duration + time point + assert(y == std::chrono::year(2032)); + + y = y - std::chrono::years(33); // overload (3): time point - duration + assert(y == std::chrono::year(1999)); + + // y = std::chrono::years(33) - y; // not supported: duration - time point + + using namespace std::chrono; + constexpr std::chrono::years ys = 2025y - 2020y; // overload (4) + static_assert(ys == std::chrono::years(5)); + } + +.SH See also + + operator++ + operator++(int) increments or decrements the month + operator-- \fI(public member function of std::chrono::month)\fP + operator--(int) + operator+= adds or subtracts a number of months + operator-= \fI(public member function of std::chrono::month)\fP diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month).3 new file mode 100644 index 000000000..5adf5d330 --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month).3 @@ -0,0 +1,93 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::year_month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::year_month) \- std::chrono::operator+,std::chrono::operator-(std::chrono::year_month) + +.SH Synopsis + constexpr std::chrono::year_month operator+( const + std::chrono::year_month& ym, \fB(1)\fP \fI(since C++20)\fP + const + std::chrono::years& dy ) noexcept; + constexpr std::chrono::year_month operator+( const + std::chrono::years& dy, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::year_month& ym ) noexcept; + constexpr std::chrono::year_month operator+( const + std::chrono::year_month& ym, \fB(3)\fP \fI(since C++20)\fP + const + std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month operator+( const + std::chrono::months& dm, \fB(4)\fP \fI(since C++20)\fP + const + std::chrono::year_month& ym ) noexcept; + constexpr std::chrono::year_month operator-( const + std::chrono::year_month& ym, \fB(5)\fP \fI(since C++20)\fP + const + std::chrono::years& dy ) noexcept; + constexpr std::chrono::year_month operator-( const + std::chrono::year_month& ym, \fB(6)\fP \fI(since C++20)\fP + const + std::chrono::months& dm ) noexcept; + constexpr std::chrono::months operator-( const + std::chrono::year_month& ym1, \fB(7)\fP \fI(since C++20)\fP + const + std::chrono::year_month& ym2 ) noexcept; + + 1,2) Adds dy.count() years to ym. + 3,4) Adds dm.count() months to ym. + 5) Subtracts dy.count() years from ym. + 6) Subtracts dm.count() months from ym. + 7) Returns the difference in months between the two time points represented by ym1 + and ym2. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (1,2,5) are preferred if the call would + otherwise be ambiguous. + +.SH Return value + + 1,2) std::chrono::year_month(ym.year() + dy, ym.month()) + 3,4) A year_month value z such that z - ym == dm and z.ok() == true. + 5) ym + -dy + 6) ym + -dm + 7) + ym1.year() - ym2.year() + std::chrono::months(int(unsigned(ym1.month())) - + int(unsigned(ym2.month()))) + +.SH Notes + + The result of subtracting two year_month values is a duration of type + std::chrono::months. This duration unit represents the length of the average + Gregorian month (30.436875 days), and the resulting duration bears no relationship + to the actual number of days in the time period at issue. For example, the result of + 2017y/3 - 2017y/2 is std::chrono::months\fB(1)\fP, even though February 2017 only contains + 28 days. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto ym{std::chrono::year(2021)/std::chrono::July}; + + ym = ym + std::chrono::months(14); + assert(ym.month() == std::chrono::September); + assert(ym.year() == std::chrono::year(2022)); + + ym = ym - std::chrono::years(3); + assert(ym.month() == std::chrono::month(9)); + assert(ym.year() == std::chrono::year(2019)); + + ym = ym + (std::chrono::September - std::chrono::month(2)); + assert(ym.month() == std::chrono::April); + assert(ym.year() == std::chrono::year(2020)); + } + +.SH See also + + operator+= modifies the year_month by some number of months or years + operator-= \fI(public member function)\fP diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day).3 new file mode 100644 index 000000000..761694c8e --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day).3 @@ -0,0 +1,94 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day) \- std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day) + +.SH Synopsis + Defined in header + constexpr std::chrono::year_month_day operator+( const + std::chrono::year_month_day& ymd, + + const \fI(since C++20)\fP + std::chrono::months& dm + + ) noexcept; + constexpr std::chrono::year_month_day operator+( const + std::chrono::months& dm, + + const \fI(since C++20)\fP + std::chrono::year_month_day& ymd + + ) noexcept; + constexpr std::chrono::year_month_day operator+( const + std::chrono::year_month_day& ymd, + + const \fI(since C++20)\fP + std::chrono::years& dy + + ) noexcept; + constexpr std::chrono::year_month_day operator+( const + std::chrono::years& dy, + + const \fI(since C++20)\fP + std::chrono::year_month_day& ymd + + ) noexcept; + constexpr std::chrono::year_month_day operator-( const + std::chrono::year_month_day& ymd, + + const \fI(since C++20)\fP + std::chrono::months& dm + + ) noexcept; + constexpr std::chrono::year_month_day operator-( const + std::chrono::year_month_day& ymd, + + const \fI(since C++20)\fP + std::chrono::years& dy + + ) noexcept; + + 1,2) Adds dm.count() months to the date represented by ymd. The result has the same + day() as ymd and the same year() and month() as std::chrono::year_month(ymd.year(), + ymd.month()) + dm. + 3,4) Adds dy.count() years to the date represented by ymd. The result is equivalent + to std::chrono::year_month_day(ymd.year() + dy, ymd.month(), ymd.day(). + 5) Subtracts dm.count() months from the date represented by ymd. Equivalent to ymd + + -dm. + 6) Subtracts dy.count() years from the date represented by ymd. Equivalent to ymd + + -dy. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (3,4,6) are preferred if the call would + otherwise be ambiguous. + +.SH Notes + + Even if ymd.ok() is true, the resulting year_month_day may not represent a valid + date if ymd.day() is 29, 30, or 31. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + auto ymd{std::chrono::day(1)/std::chrono::July/2021}; + + ymd = ymd + std::chrono::months(4); + std::cout << (ymd.month() == std::chrono::November) << ' ' + << (ymd.year() == std::chrono::year(2021)) << ' '; + + ymd = ymd - std::chrono::years(10); + std::cout << (ymd.month() == std::chrono::month(11)) << ' ' + << (ymd.year() == std::chrono::year(2011)) << '\\n'; + } + +.SH Output: + + true true true true diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day_last).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day_last).3 new file mode 100644 index 000000000..e58e5b4cc --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day_last).3 @@ -0,0 +1,84 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day_last) \- std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_day_last) + +.SH Synopsis + Defined in header + constexpr std::chrono::year_month_day_last + + operator+( const std::chrono::year_month_day_last& ymdl, \fI(since C++20)\fP + + const std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month_day_last + + operator+( const std::chrono::months& dm, \fI(since C++20)\fP + + const std::chrono::year_month_day_last& ymdl ) + noexcept; + constexpr std::chrono::year_month_day_last + + operator+( const std::chrono::year_month_day_last& ymdl, \fI(since C++20)\fP + + const std::chrono::years& dy ) noexcept; + constexpr std::chrono::year_month_day_last + + operator+( const std::chrono::years& dy, \fI(since C++20)\fP + + const std::chrono::year_month_day_last& ymdl ) + noexcept; + constexpr std::chrono::year_month_day_last + + operator-( const std::chrono::year_month_day_last& ymdl, \fI(since C++20)\fP + + const std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month_day_last + + operator-( const std::chrono::year_month_day_last& ymdl, \fI(since C++20)\fP + + const std::chrono::years& dy ) noexcept; + + 1,2) Adds dm.count() months to the date represented by ymdl. The result has the same + year() and month() as std::chrono::year_month(ymdl.year(), ymdl.month()) + dm. + 3,4) Adds dy.count() years to the date represented by ymdl. The result is equivalent + to std::chrono::year_month_day_last(ymdl.year() + dy, ymdl.month_day_last()). + 5) Subtracts dm.count() months from the date represented by ymdl. Equivalent to ymdl + + -dm. + 6) Subtracts dy.count() years from the date represented by ymdl. Equivalent to ymdl + + -dy. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (3,4,6) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto ymdl{11/std::chrono::last/2020}; + std::cout << ymdl << '\\n'; + + ymdl = std::chrono::years(10) + ymdl; + std::cout << ymdl << '\\n'; + assert(ymdl == std::chrono::day(30)/ + std::chrono::November/ + std::chrono::year(2030)); + + ymdl = ymdl - std::chrono::months(6); + std::cout << ymdl << '\\n'; + assert(ymdl == std::chrono::day(31)/ + std::chrono::May/ + std::chrono::year(2030)); + } + +.SH Output: + + 2020/Nov/last + 2030/Nov/last + 2030/May/last diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday).3 new file mode 100644 index 000000000..d635781e0 --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday).3 @@ -0,0 +1,90 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday) \- std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday) + +.SH Synopsis + constexpr std::chrono::year_month_weekday + + operator+( const std::chrono::year_month_weekday& ymwd, \fB(1)\fP \fI(since C++20)\fP + + const std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month_weekday + + operator+( const std::chrono::months& dm, \fB(2)\fP \fI(since C++20)\fP + + const std::chrono::year_month_weekday& ymwd ) + noexcept; + constexpr std::chrono::year_month_weekday + + operator+( const std::chrono::year_month_weekday& ymwd, \fB(3)\fP \fI(since C++20)\fP + + const std::chrono::years& dy ) noexcept; + constexpr std::chrono::year_month_weekday + + operator+( const std::chrono::years& dy, \fB(4)\fP \fI(since C++20)\fP + + const std::chrono::year_month_weekday& ymwd ) + noexcept; + constexpr std::chrono::year_month_weekday + + operator-( const std::chrono::year_month_weekday& ymwd, \fB(5)\fP \fI(since C++20)\fP + + const std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month_weekday + + operator-( const std::chrono::year_month_weekday& ymwd, \fB(6)\fP \fI(since C++20)\fP + + const std::chrono::years& dy ) noexcept; + + 1,2) Adds dm.count() months to the date represented by ymwd. The result has the same + year() and month() as std::chrono::year_month(ymwd.year(), ymwd.month()) + dm and + the same weekday() and index() as ymwd. + 3,4) Adds dy.count() years to the date represented by ymwd. The result is equivalent + to std::chrono::year_month_weekday(ymwd.year() + dy, ymwd.month(), + ymwd.weekday_indexed()). + 5) Subtracts dm.count() months from the date represented by ymwd. Equivalent to ymwd + + -dm. + 6) Subtracts dy.count() years from the date represented by ymwd. Equivalent to ymwd + + -dy. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (3,4,6) are preferred if the call would + otherwise be ambiguous. + +.SH Notes + + Even if ymwd.ok() is true, the resulting year_month_weekday may not represent a + valid date if ymwd.index() is 5. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto ymwdi{1/std::chrono::Wednesday[1]/2021}; + std::cout << ymwdi << '\\n'; + + ymwdi = std::chrono::years(5) + ymwdi; + // First Wednesday in January, 2026 + std::cout << ymwdi << '\\n'; + assert(static_cast(ymwdi) == + std::chrono::January/7/2026); + + ymwdi = ymwdi - std::chrono::months(6); + // First Wednesday in July, 2025 + std::cout << ymwdi << '\\n'; + assert(static_cast(ymwdi) == + std::chrono::July/2/2025); + } + +.SH Output: + + 2021/Jan/Wed[1] + 2026/Jan/Wed[1] + 2025/Jul/Wed[1] diff --git a/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday_last).3 b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday_last).3 new file mode 100644 index 000000000..f96e8d3e6 --- /dev/null +++ b/man/std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday_last).3 @@ -0,0 +1,70 @@ +.TH std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday_last) \- std::chrono::operator+,std::chrono::operator-(std::chrono::year_month_weekday_last) + +.SH Synopsis + constexpr std::chrono::year_month_weekday_last + + operator+( const std::chrono::year_month_weekday_last& ymwdl, \fI(since C++20)\fP + + const std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month_weekday_last + + operator+( const std::chrono::months& dm, \fI(since C++20)\fP + + const std::chrono::year_month_weekday_last& ymwdl ) + noexcept; + constexpr std::chrono::year_month_weekday_last + + operator+( const std::chrono::year_month_weekday_last& ymwdl, \fI(since C++20)\fP + + const std::chrono::years& dy ) noexcept; + constexpr std::chrono::year_month_weekday_last + + operator+( const std::chrono::years& dy, \fI(since C++20)\fP + + const std::chrono::year_month_weekday_last& ymwdl ) + noexcept; + constexpr std::chrono::year_month_weekday_last + + operator-( const std::chrono::year_month_weekday_last& ymwdl, \fI(since C++20)\fP + + const std::chrono::months& dm ) noexcept; + constexpr std::chrono::year_month_weekday_last + + operator-( const std::chrono::year_month_weekday_last& ymwdl, \fI(since C++20)\fP + + const std::chrono::years& dy ) noexcept; + + 1,2) Adds dm.count() months to the date represented by ymwdl. The result has the + same year() and month() as std::chrono::year_month(ymwdl.year(), ymwdl.month()) + dm + and the same weekday() as ymwdl. + 3,4) Adds dy.count() years to the date represented by ymwdl. The result is + equivalent to std::chrono::year_month_weekday_last(ymwdl.year() + dy, ymwdl.month(), + ymwd.weekday_last()). + 5) Subtracts dm.count() months from the date represented by ymwdl. Equivalent to + ymwdl + -dm. + 6) Subtracts dy.count() years from the date represented by ymwdl. Equivalent to + ymwdl + -dy. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (3,4,6) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto ymwdl1{Tuesday[last]/11/2021}; + auto ymwdl2 = ymwdl1; + ymwdl2 = std::chrono::months(12) + ymwdl2; + ymwdl2 = ymwdl2 - std::chrono::years(1); + assert(ymwdl1 == ymwdl2); + } diff --git a/man/std::chrono::operator<<(std::chrono::day).3 b/man/std::chrono::operator<<(std::chrono::day).3 new file mode 100644 index 000000000..cae725d7e --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::day).3 @@ -0,0 +1,62 @@ +.TH std::chrono::operator<<(std::chrono::day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::day) \- std::chrono::operator<<(std::chrono::day) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::day& d ); + + Forms a std::basic_string s consisting of the day value stored in d formatted + as a decimal number, with a leading zero if the result would otherwise be a single + decimal digit. Then, if !d.ok(), append " is not a valid day" to the formatted + string. Inserts that string into os. + + Equivalent to + + return os << (d.ok() ? + std::format(STATICALLY_WIDEN("{:%d}"), d) : + std::format(STATICALLY_WIDEN("{:%d} is not a valid day"), d)); + + where STATICALLY_WIDEN("...") is "..." if CharT is char, and L"..." if CharT + is wchar_t. + +.SH Return value + + os + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::day d1{31}, d2{7}, d3{42}, d4{}; + std::cout << d1 << '\\n' + << d2 << '\\n' + << d3 << '\\n' + << d4 << '\\n'; + } + +.SH Possible output: + + 31 + 07 + 42 is not a valid day + 00 is not a valid day + +.SH See also + + format stores formatted representation of the arguments in + (C++20) a new string + \fI(function template)\fP + std::formatter formatting support for day + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::duration).3 b/man/std::chrono::operator<<(std::chrono::duration).3 new file mode 100644 index 000000000..721671bf4 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::duration).3 @@ -0,0 +1,104 @@ +.TH std::chrono::operator<<(std::chrono::duration) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::duration) \- std::chrono::operator<<(std::chrono::duration) + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits, + class Rep, \fI(since C++20)\fP + class Period + > std::basic_ostream& + operator<<( std::basic_ostream& os, + + const std::chrono::duration& d ); + + Inserts a textual representation of d into os. + + Behaves as if it was implemented as + + std::basic_ostringstream s; + s.flags(os.flags()); + s.imbue(os.getloc()); + s.precision(os.precision()); + s << d.count() << units_suffix; // see below + return os << s.str(); + + In other words, the stream flags, locale, and precision are determined by the + stream, but any padding are determined using the entire output string. + + The units_suffix is determined based on Period::type according to the following + table. + + Period::type Suffix + std::atto as + std::femto fs + std::pico ps + std::nano ns + std::micro µs (U+00B5) or us, it is implementation-defined which one is + used + std::milli ms + std::centi cs + std::deci ds + std::ratio<1> s + std::deca das + std::hecto hs + std::kilo ks + std::mega Ms + std::giga Gs + std::tera Ts + std::peta Ps + std::exa Es + std::ratio<60> min + std::ratio<3600> h + std::ratio<86400> d + None of the above, and [num]s + Period::type::den == 1 + None of the above [num/den]s + + For the last two rows of the table, num and den in the suffix are Period::type::num + and Period::type::den formatted as a decimal number with no leading zeroes, + respectively. + +.SH Return value + + A reference to the stream, i.e., os. + +.SH Example + + This example shows the output of std::chrono::operator<< when given a duration: + + +// Run this code + + #include + #include + using namespace std::chrono_literals; + + int main() + { + constexpr auto duration = 123ms; + std::cout << duration << '\\n'; + } + +.SH Output: + + 123ms + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for duration + (C++20) \fI(class template specialization)\fP + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + to_string converts an integral or floating-point value + \fI(C++11)\fP to string + \fI(function)\fP + to_wstring converts an integral or floating-point value + \fI(C++11)\fP to wstring + \fI(function)\fP diff --git a/man/std::chrono::operator<<(std::chrono::file_time).3 b/man/std::chrono::operator<<(std::chrono::file_time).3 new file mode 100644 index 000000000..cf03f1cdf --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::file_time).3 @@ -0,0 +1,37 @@ +.TH std::chrono::operator<<(std::chrono::file_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::file_time) \- std::chrono::operator<<(std::chrono::file_time) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::file_time& tp ); + + Outputs tp into the stream os, as if by os << std::format(os.getloc(), + STATICALLY-WIDEN("{:L%F %T}"), tp), where STATICALLY_WIDEN("{:L%F %T}") is + "{:L%F %T}" if CharT is char, and L"{:L%F %T}" if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + std::formatter formatting support for file_time + (C++20) \fI(class template specialization)\fP + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP diff --git a/man/std::chrono::operator<<(std::chrono::gps_time).3 b/man/std::chrono::operator<<(std::chrono::gps_time).3 new file mode 100644 index 000000000..3e80770da --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::gps_time).3 @@ -0,0 +1,37 @@ +.TH std::chrono::operator<<(std::chrono::gps_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::gps_time) \- std::chrono::operator<<(std::chrono::gps_time) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::gps_time& tp ); + + Outputs tp into the stream os, as if by os << std::format(os.getloc(), + STATICALLY-WIDEN("{:L%F %T}"), tp), where STATICALLY_WIDEN("{:L%F %T}") is + "{:L%F %T}" if CharT is char, and L"{:L%F %T}" if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + std::formatter formatting support for gps_time + (C++20) \fI(class template specialization)\fP + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP diff --git a/man/std::chrono::operator<<(std::chrono::hh_mm_ss).3 b/man/std::chrono::operator<<(std::chrono::hh_mm_ss).3 new file mode 100644 index 000000000..138e3d18d --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::hh_mm_ss).3 @@ -0,0 +1,52 @@ +.TH std::chrono::operator<<(std::chrono::hh_mm_ss) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::hh_mm_ss) \- std::chrono::operator<<(std::chrono::hh_mm_ss) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::hh_mm_ss& t ); + + Outputs t into the stream os. + + Equivalent to return os << std::format(os.getloc(), + STATICALLY_WIDEN("{:L%T}"), hms); where STATICALLY_WIDEN("{:L%T}") is + "{:L%T}" if CharT is char, and L"{:L%T}" if CharT is wchar_t. + +.SH Parameters + + os - the output stream + t - the time of day to be output + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for hh_mm_ss + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::local_info).3 b/man/std::chrono::operator<<(std::chrono::local_info).3 new file mode 100644 index 000000000..c9a08ac27 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::local_info).3 @@ -0,0 +1,19 @@ +.TH std::chrono::operator<<(std::chrono::local_info) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::local_info) \- std::chrono::operator<<(std::chrono::local_info) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& operator<<( + std::basic_ostream& os, \fI(since C++20)\fP + + const + std::chrono::local_info& r ); + + Inserts a textual representation of r into os. The exact format is unspecified. + +.SH Return value + + os diff --git a/man/std::chrono::operator<<(std::chrono::local_time).3 b/man/std::chrono::operator<<(std::chrono::local_time).3 new file mode 100644 index 000000000..3bebbe4a7 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::local_time).3 @@ -0,0 +1,23 @@ +.TH std::chrono::operator<<(std::chrono::local_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::local_time) \- std::chrono::operator<<(std::chrono::local_time) + +.SH Synopsis + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::local_time& tp ); + + Outputs tp into the stream os, as if by os << + std::chrono::sys_time(tp.time_since_epoch());. + +.SH Return value + + os + +.SH See also + + operator<<(std::chrono::sys_time) performs stream output on a sys_time + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::operator<<(std::chrono::month).3 b/man/std::chrono::operator<<(std::chrono::month).3 new file mode 100644 index 000000000..6ed11762f --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::month).3 @@ -0,0 +1,53 @@ +.TH std::chrono::operator<<(std::chrono::month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::month) \- std::chrono::operator<<(std::chrono::month) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::month& m ); + + If !m.ok(), inserts unsigned(m) followed by " is not a valid month" to os. + Otherwise, forms a std::basic_string s consisting of the abbreviated month + name for the month represented by m, determined using the locale associated with os, + and inserts s into os. + + Equivalent to + + return os << (m.ok() ? + std::format(os.getloc(), STATICALLY_WIDEN("{:L%b}"), m) : + std::format(os.getloc(), STATICALLY_WIDEN("{} is not a valid month"), + unsigned(m))); + + where STATICALLY_WIDEN("...") is "..." if CharT is char, and L"..." if CharT + is wchar_t. + +.SH Return value + + os + +.SH Notes + + This operator<< is primarily intended for debugging use. For control over + formatting, use std::format. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the arguments + (C++20) in a new string + \fI(function template)\fP + std::formatter formatting support for month + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::month_day).3 b/man/std::chrono::operator<<(std::chrono::month_day).3 new file mode 100644 index 000000000..aa4b502aa --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::month_day).3 @@ -0,0 +1,49 @@ +.TH std::chrono::operator<<(std::chrono::month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::month_day) \- std::chrono::operator<<(std::chrono::month_day) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::month_day& md ); + + Outputs a textual representation of md into the stream os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}/{}"), md.month(), + md.day()) + + where STATICALLY_WIDEN("{:L}/{}") is "{:L}/{}" if CharT is char, and + L"{:L}/{}" if CharT is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for month_day + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::month_day_last).3 b/man/std::chrono::operator<<(std::chrono::month_day_last).3 new file mode 100644 index 000000000..e332fba61 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::month_day_last).3 @@ -0,0 +1,40 @@ +.TH std::chrono::operator<<(std::chrono::month_day_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::month_day_last) \- std::chrono::operator<<(std::chrono::month_day_last) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::month_day_last& mdl ); + + Outputs a textual representation of mdl into os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}/last"), mdl.month()); + + where STATICALLY_WIDEN("{:L}/last") is "{:L}/last" if CharT is char, and + L"{:L}/last" if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for month_day + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::month_weekday).3 b/man/std::chrono::operator<<(std::chrono::month_weekday).3 new file mode 100644 index 000000000..9f8567b1a --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::month_weekday).3 @@ -0,0 +1,49 @@ +.TH std::chrono::operator<<(std::chrono::month_weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::month_weekday) \- std::chrono::operator<<(std::chrono::month_weekday) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::month_weekday& mwd ); + + Outputs a textual representation of mwd into os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}/{:L}"), + mwd.month(), mwd.weekday_indexed()); + + where STATICALLY_WIDEN("{:L}/{:L}") is "{:L}/{:L}" if CharT is char, and + L"{:L}/{:L}" if CharT is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the arguments + (C++20) in a new string + \fI(function template)\fP + std::formatter formatting support for month + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::month_weekday_last).3 b/man/std::chrono::operator<<(std::chrono::month_weekday_last).3 new file mode 100644 index 000000000..30996d636 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::month_weekday_last).3 @@ -0,0 +1,49 @@ +.TH std::chrono::operator<<(std::chrono::month_weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::month_weekday_last) \- std::chrono::operator<<(std::chrono::month_weekday_last) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::month_weekday_last& mwdl ); + + Outputs a textual representation of mwdl into os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}/{:L}"), + mwdl.month(), mwdl.weekday_last()); + + where STATICALLY_WIDEN("{:L}/{:L}") is "{:L}/{:L}" if CharT is char, and + L"{:L}/{:L}" if CharT is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the arguments + (C++20) in a new string + \fI(function template)\fP + std::formatter formatting support for month + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::sys_info).3 b/man/std::chrono::operator<<(std::chrono::sys_info).3 new file mode 100644 index 000000000..aae941892 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::sys_info).3 @@ -0,0 +1,19 @@ +.TH std::chrono::operator<<(std::chrono::sys_info) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::sys_info) \- std::chrono::operator<<(std::chrono::sys_info) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& operator<<( + std::basic_ostream& os, \fI(since C++20)\fP + + const + std::chrono::sys_info& r ); + + Inserts a textual representation of r into os. The exact format is unspecified. + +.SH Return value + + os diff --git a/man/std::chrono::operator<<(std::chrono::sys_time).3 b/man/std::chrono::operator<<(std::chrono::sys_time).3 new file mode 100644 index 000000000..d72925a75 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::sys_time).3 @@ -0,0 +1,55 @@ +.TH std::chrono::operator<<(std::chrono::sys_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::sys_time) \- std::chrono::operator<<(std::chrono::sys_time) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fB(1)\fP \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::sys_time& tp ); + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fB(2)\fP \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::sys_days& tp ); + + Outputs tp into the stream os. + + 1) Equivalent to: + + return os << std::format(os.getloc(), STATICALLY-WIDEN("{:L%F %T}"), tp); + + where STATICALLY_WIDEN("{:L%F %T}") is "{:L%F %T}" if CharT is char, and + L"{:L%F %T}" if CharT is wchar_t. + + This overload participates in overload resolution only if + std::chrono::treat_as_floating_point_v is false and + Duration\fB(1)\fP < std::chrono::days(1). + 2) Equivalent to os << std::chrono::year_month_day(tp);. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + std::formatter formatting support for sys_time + (C++20) \fI(class template specialization)\fP + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + operator<< outputs a year_month_day into a stream + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::operator<<(std::chrono::tai_time).3 b/man/std::chrono::operator<<(std::chrono::tai_time).3 new file mode 100644 index 000000000..849f0ab94 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::tai_time).3 @@ -0,0 +1,37 @@ +.TH std::chrono::operator<<(std::chrono::tai_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::tai_time) \- std::chrono::operator<<(std::chrono::tai_time) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::tai_time& tp ); + + Outputs tp into the stream os, as if by os << std::format(os.getloc(), + STATICALLY-WIDEN("{:L%F %T}"), tp), where STATICALLY_WIDEN("{:L%F %T}") is + "{:L%F %T}" if CharT is char, and L"{:L%F %T}" if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + std::formatter formatting support for tai_time + (C++20) \fI(class template specialization)\fP + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP diff --git a/man/std::chrono::operator<<(std::chrono::utc_time).3 b/man/std::chrono::operator<<(std::chrono::utc_time).3 new file mode 100644 index 000000000..b65505c22 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::utc_time).3 @@ -0,0 +1,37 @@ +.TH std::chrono::operator<<(std::chrono::utc_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::utc_time) \- std::chrono::operator<<(std::chrono::utc_time) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::utc_time& tp ); + + Outputs tp into the stream os, as if by os << std::format(os.getloc(), + STATICALLY-WIDEN("{:L%F %T}"), tp), where STATICALLY_WIDEN("{:L%F %T}") is + "{:L%F %T}" if CharT is char, and L"{:L%F %T}" if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + std::formatter formatting support for utc_time + (C++20) \fI(class template specialization)\fP + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP diff --git a/man/std::chrono::operator<<(std::chrono::weekday).3 b/man/std::chrono::operator<<(std::chrono::weekday).3 new file mode 100644 index 000000000..ad0ffa711 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::weekday).3 @@ -0,0 +1,56 @@ +.TH std::chrono::operator<<(std::chrono::weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::weekday) \- std::chrono::operator<<(std::chrono::weekday) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::weekday& wd ); + + If !wd.ok(), inserts wd.c_encoding() followed by " is not a valid weekday" into os. + Otherwise, forms a std::basic_string s consisting of the abbreviated weekday + name for the weekday represented by wd, determined using the locale associated with + os, and inserts s into os. + + Equivalent to + + return os << (wd.ok() ? + std::format(os.getloc(), STATICALLY_WIDEN("{:L%a}"), wd) : + std::format(os.getloc(), STATICALLY_WIDEN("{} is not a valid weekday"), + wd.c_encoding())); + + where STATICALLY_WIDEN("...") is "..." if CharT is char, and L"..." if CharT + is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for weekday + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::weekday_indexed).3 b/man/std::chrono::operator<<(std::chrono::weekday_indexed).3 new file mode 100644 index 000000000..0a6e91af2 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::weekday_indexed).3 @@ -0,0 +1,46 @@ +.TH std::chrono::operator<<(std::chrono::weekday_indexed) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::weekday_indexed) \- std::chrono::operator<<(std::chrono::weekday_indexed) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::weekday_indexed& wdi ); + + Outputs a textual representation of wdi into the stream os, as if by: + + if (wdi.index() >=1 && wdi.index() <= 5) + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}[{}]"), + wdi.weekday(), wdi.index()); + else + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}[{} is not a valid + index]"), + wdi.weekday(), wdi.index()); + + where STATICALLY_WIDEN("...") is "..." if CharT is char, and L"..." if CharT + is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for weekday + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::weekday_last).3 b/man/std::chrono::operator<<(std::chrono::weekday_last).3 new file mode 100644 index 000000000..ac0b28404 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::weekday_last).3 @@ -0,0 +1,49 @@ +.TH std::chrono::operator<<(std::chrono::weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::weekday_last) \- std::chrono::operator<<(std::chrono::weekday_last) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::weekday_last& wdl ); + + Outputs a textual representation of wdl into the stream os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{:L}[last]"), + wdl.weekday()); + + where STATICALLY_WIDEN("{:L}[last]") is "{:L}[last]" if CharT is char, and + L"{:L}[last]" if CharT is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for weekday + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::year).3 b/man/std::chrono::operator<<(std::chrono::year).3 new file mode 100644 index 000000000..a0d0d5f80 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::year).3 @@ -0,0 +1,60 @@ +.TH std::chrono::operator<<(std::chrono::year) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::year) \- std::chrono::operator<<(std::chrono::year) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::year& y ); + + Forms a std::basic_string s consisting of the year value stored in y + formatted as a decimal number, left-padded with 0 to four digits if the result would + otherwise be less than four digits. Then, if !y.ok(), append " is not a valid year" + to the formatted string. Inserts that string into os. + + Equivalent to + + return os << (y.ok() ? + std::format(STATICALLY_WIDEN("{:%Y}"), y) : + std::format(STATICALLY_WIDEN("{:%Y} is not a valid year"), y)); + + where STATICALLY_WIDEN("...") is "..." if CharT is char, and L"..." if CharT + is wchar_t. + +.SH Return value + + os + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::year y1{2020}, y2{-020}, y3{98304}; + std::cout << y1 << '\\n' + << y2 << '\\n' + << y3 << '\\n'; + } + +.SH Possible output: + + 2020 + -0016 + -32768 is not a valid year + +.SH See also + + format stores formatted representation of the arguments + (C++20) in a new string + \fI(function template)\fP + std::formatter formatting support for year + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::year_month).3 b/man/std::chrono::operator<<(std::chrono::year_month).3 new file mode 100644 index 000000000..88cfea4c0 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::year_month).3 @@ -0,0 +1,49 @@ +.TH std::chrono::operator<<(std::chrono::year_month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::year_month) \- std::chrono::operator<<(std::chrono::year_month) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + + operator<<( std::basic_ostream& os, const + std::chrono::year_month& ym ); + + Outputs a textual representation of ym into the stream os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{}/{:L}"), ym.year(), + ym.month()) + + where STATICALLY_WIDEN("{}/{:L}") is "{}/{:L}" if CharT is char, and + L"{}/{:L}" if CharT is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for year_month + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::year_month_day).3 b/man/std::chrono::operator<<(std::chrono::year_month_day).3 new file mode 100644 index 000000000..1c4203ac7 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::year_month_day).3 @@ -0,0 +1,47 @@ +.TH std::chrono::operator<<(std::chrono::year_month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::year_month_day) \- std::chrono::operator<<(std::chrono::year_month_day) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::year_month_day& ymd ); + + Outputs a textual representation of ymd into the stream os. This first forms a + std::basic_string s consisting of a textual representation of the date in the + format yyyy-mm-dd (same as the one output by formatter with the %F specifier). Then, + if !ymd.ok(), appends " is not a valid date" to s. Inserts s into os. + + Equivalent to + + return os << (ymd.ok() ? + std::format(os.getloc(), STATICALLY_WIDEN("{:%F}"), ymd) : + std::format(os.getloc(), STATICALLY_WIDEN("{:%F} is not a valid date"), + ymd)); + + where STATICALLY_WIDEN("...") is "..." if CharT is char, and L"..." if CharT + is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for year_month_day + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::year_month_day_last).3 b/man/std::chrono::operator<<(std::chrono::year_month_day_last).3 new file mode 100644 index 000000000..a0af7694d --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::year_month_day_last).3 @@ -0,0 +1,49 @@ +.TH std::chrono::operator<<(std::chrono::year_month_day_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::year_month_day_last) \- std::chrono::operator<<(std::chrono::year_month_day_last) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::year_month_day_last& ymdl ); + + Outputs a textual representation of ymdl into os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{}/{:L}"), + ymdl.year(), ymdl.month_day_last()); + + where STATICALLY_WIDEN("{}/{:L}") is "{}/{:L}" if CharT is char, and + L"{}/{:L}" if CharT is wchar_t. + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for year_month_day + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator<<(std::chrono::year_month_weekday).3 b/man/std::chrono::operator<<(std::chrono::year_month_weekday).3 new file mode 100644 index 000000000..65f82e44d --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::year_month_weekday).3 @@ -0,0 +1,41 @@ +.TH std::chrono::operator<<(std::chrono::year_month_weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::year_month_weekday) \- std::chrono::operator<<(std::chrono::year_month_weekday) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::year_month_weekday& ymwd ); + + Outputs a textual representation of ymwd into os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{}/{:L}/{:L}"), + ymwd.year(), ymwd.month(), ymwd.weekday_indexed()); + + where STATICALLY_WIDEN("{}/{:L}/{:L}") is "{}/{:L}/{:L}" if CharT is char, + and L"{}/{:L}/{:L}" if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for year_month_day + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::year_month_weekday_last).3 b/man/std::chrono::operator<<(std::chrono::year_month_weekday_last).3 new file mode 100644 index 000000000..8ccb60ea3 --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::year_month_weekday_last).3 @@ -0,0 +1,41 @@ +.TH std::chrono::operator<<(std::chrono::year_month_weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::year_month_weekday_last) \- std::chrono::operator<<(std::chrono::year_month_weekday_last) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::year_month_weekday_last& ymwdl ); + + Outputs a textual representation of ymwdl into os, as if by + + os << std::format(os.getloc(), STATICALLY_WIDEN("{}/{:L}/{:L}"), + ymwdl.year(), ymwdl.month(), ymwdl.weekday_last()); + + where STATICALLY_WIDEN("{}/{:L}/{:L}") is "{}/{:L}/{:L}" if CharT is char, + and L"..." if CharT is wchar_t. + +.SH Return value + + os + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + format stores formatted representation of the + (C++20) arguments in a new string + \fI(function template)\fP + std::formatter formatting support for year_month_day + (C++20) \fI(class template specialization)\fP diff --git a/man/std::chrono::operator<<(std::chrono::zoned_time).3 b/man/std::chrono::operator<<(std::chrono::zoned_time).3 new file mode 100644 index 000000000..ffbe0a2be --- /dev/null +++ b/man/std::chrono::operator<<(std::chrono::zoned_time).3 @@ -0,0 +1,48 @@ +.TH std::chrono::operator<<(std::chrono::zoned_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator<<(std::chrono::zoned_time) \- std::chrono::operator<<(std::chrono::zoned_time) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Duration, class + TimeZonePtr > + + std::basic_ostream& \fI(since C++20)\fP + operator<<( std::basic_ostream& os, + + const std::chrono::zoned_time& + tp ); + + Outputs tp to the stream os, as if by std::format(os.getloc(), fmt, tp), where fmt + is "{:L%F %T %Z}" if CharT is char, or L"{:L%F %T %Z}" if CharT is wchar_t. + +.SH Parameters + + os - output stream + tp - zoned_time to output + +.SH Return value + + os + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2372R3 C++20 the given locale was used by default L is needed to use the given + locale + +.SH See also + + std::formatter formatting support for zoned_time + (C++20) \fI(class template specialization)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::operator==(std::chrono::month_weekday).3 b/man/std::chrono::operator==(std::chrono::month_weekday).3 new file mode 100644 index 000000000..a3ab7d5e1 --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::month_weekday).3 @@ -0,0 +1,39 @@ +.TH std::chrono::operator==(std::chrono::month_weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::month_weekday) \- std::chrono::operator==(std::chrono::month_weekday) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::month_weekday& x, + const std::chrono::month_weekday& y ) \fI(since C++20)\fP + noexcept; + + Compares the two month_weekday values x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.month() == y.month() && x.weekday_indexed() == y.weekday_indexed() + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr auto mwdi1{std::chrono::March/std::chrono::Friday[1]}; + + constexpr auto mwdi2 + { + std::chrono::month_weekday + { + std::chrono::month(3), std::chrono::weekday(5)[1] + } + }; + + static_assert(mwdi1 == mwdi2); + } diff --git a/man/std::chrono::operator==(std::chrono::month_weekday_last).3 b/man/std::chrono::operator==(std::chrono::month_weekday_last).3 new file mode 100644 index 000000000..5f001ca7d --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::month_weekday_last).3 @@ -0,0 +1,39 @@ +.TH std::chrono::operator==(std::chrono::month_weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::month_weekday_last) \- std::chrono::operator==(std::chrono::month_weekday_last) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::month_weekday_last& x, + const std::chrono::month_weekday_last& y ) \fI(since C++20)\fP + noexcept; + + Compares the two month_weekday_last values x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.month() == y.month() && x.weekday_last() == y.weekday_last() + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr std::chrono::month_weekday_last mwdl1 + { + std::chrono::March/std::chrono::Friday[std::chrono::last] + }; + + constexpr std::chrono::month_weekday_last mwdl2 + { + std::chrono::March, std::chrono::Friday[std::chrono::last] + }; + + static_assert(mwdl1 == mwdl2); + } diff --git a/man/std::chrono::operator==(std::chrono::weekday).3 b/man/std::chrono::operator==(std::chrono::weekday).3 new file mode 100644 index 000000000..308b52fbf --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::weekday).3 @@ -0,0 +1,41 @@ +.TH std::chrono::operator==(std::chrono::weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::weekday) \- std::chrono::operator==(std::chrono::weekday) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::weekday& x, \fI(since C++20)\fP + const std::chrono::weekday& y ) noexcept; + + Compare the two std::chrono::weekday x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.c_encoding() == y.c_encoding() + +.SH Notes + + weekday does not support the <, <=, > and >= operators because there is no universal + consensus on which day is the first day of the week. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + + constexpr std::chrono::weekday wd1{2}; + constexpr std::chrono::weekday wd2{std::chrono::Friday}; + static_assert(wd1 != wd2); + + // 13 January 1313 is a Friday + constexpr std::chrono::weekday wd3{1313y/1/13d}; + static_assert(wd2 == wd3); + } diff --git a/man/std::chrono::operator==(std::chrono::weekday_indexed).3 b/man/std::chrono::operator==(std::chrono::weekday_indexed).3 new file mode 100644 index 000000000..ea7f43114 --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::weekday_indexed).3 @@ -0,0 +1,31 @@ +.TH std::chrono::operator==(std::chrono::weekday_indexed) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::weekday_indexed) \- std::chrono::operator==(std::chrono::weekday_indexed) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::weekday_indexed& x, + const std::chrono::weekday_indexed& y ) \fI(since C++20)\fP + noexcept; + + Compares the two weekday_indexed x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.weekday() == y.weekday() && x.index() == y.index() + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr std::chrono::weekday_indexed wdi1{std::chrono::Wednesday[2]}; + constexpr std::chrono::weekday_indexed wdi2{std::chrono::weekday(3), 2}; + static_assert(wdi1 == wdi2); + } diff --git a/man/std::chrono::operator==(std::chrono::weekday_last).3 b/man/std::chrono::operator==(std::chrono::weekday_last).3 new file mode 100644 index 000000000..a43d9c93a --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::weekday_last).3 @@ -0,0 +1,38 @@ +.TH std::chrono::operator==(std::chrono::weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::weekday_last) \- std::chrono::operator==(std::chrono::weekday_last) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::weekday_last& x, + const std::chrono::weekday_last& y ) \fI(since C++20)\fP + noexcept; + + Compares the two weekday_last values x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.weekday() == y.weekday() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr auto wdl1{std::chrono::Tuesday[std::chrono::last]}; + constexpr std::chrono::weekday_last wdl2{std::chrono::weekday(2)}; + std::cout << std::boolalpha + << (wdl1 == wdl2) << ' ' + << (wdl1 == std::chrono::Wednesday[std::chrono::last]) << '\\n'; + } + +.SH Output: + + true false diff --git a/man/std::chrono::operator==(std::chrono::year_month_weekday).3 b/man/std::chrono::operator==(std::chrono::year_month_weekday).3 new file mode 100644 index 000000000..264f25b2f --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::year_month_weekday).3 @@ -0,0 +1,38 @@ +.TH std::chrono::operator==(std::chrono::year_month_weekday) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::year_month_weekday) \- std::chrono::operator==(std::chrono::year_month_weekday) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::year_month_weekday& x, + const std::chrono::year_month_weekday& y ) \fI(since C++20)\fP + noexcept; + + Compares the two year_month_weekday values x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.year() == y.year() && x.month() == y.month() && x.weekday_indexed() == + y.weekday_indexed() + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto ymwdi1{Wednesday[1]/January/2021}; + constexpr year_month_weekday ymwdi2{year(2021), month(1), weekday(3)[1]}; + std::cout << std::boolalpha << (ymwdi1 == ymwdi2) << '\\n'; + } + +.SH Output: + + true diff --git a/man/std::chrono::operator==(std::chrono::year_month_weekday_last).3 b/man/std::chrono::operator==(std::chrono::year_month_weekday_last).3 new file mode 100644 index 000000000..9d3b4fb0d --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::year_month_weekday_last).3 @@ -0,0 +1,39 @@ +.TH std::chrono::operator==(std::chrono::year_month_weekday_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::year_month_weekday_last) \- std::chrono::operator==(std::chrono::year_month_weekday_last) + +.SH Synopsis + Defined in header + constexpr bool operator==( const + std::chrono::year_month_weekday_last& x, \fI(since C++20)\fP + const + std::chrono::year_month_weekday_last& y ) noexcept; + + Compares the two year_month_weekday_last values x and y. + + The != operator is synthesized from operator==. + +.SH Return value + + x.year() == y.year() && x.month() == y.month() && x.weekday() == y.weekday() + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto ymwdl1{Tuesday[last]/11/2021}; + auto ymwdl2 = Tuesday[last]/11/2020; + ymwdl2 += months(12); + std::cout << std::boolalpha << (ymwdl1 == ymwdl2) << '\\n'; + } + +.SH Output: + + true diff --git a/man/std::chrono::operator==(std::chrono::zoned_time).3 b/man/std::chrono::operator==(std::chrono::zoned_time).3 new file mode 100644 index 000000000..16e9f8951 --- /dev/null +++ b/man/std::chrono::operator==(std::chrono::zoned_time).3 @@ -0,0 +1,24 @@ +.TH std::chrono::operator==(std::chrono::zoned_time) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==(std::chrono::zoned_time) \- std::chrono::operator==(std::chrono::zoned_time) + +.SH Synopsis + Defined in header + template< class Duration1, class Duration2, class TimeZonePtr > + + bool operator==( const std::chrono::zoned_time& x, \fI(since C++20)\fP + + const std::chrono::zoned_time& y ); + + Compares the two zoned_time values x and y. Two zoned_time objects compare equal if + their time points and time zone pointers both compare equal according to operator==. + + The != operator is synthesized from operator==. + +.SH Return value + + x.get_time_zone() == y.get_time_zone() && x.get_sys_time() == y.get_sys_time(), + except that the comparisons are performed on the nonstatic data members of x and y + directly and no copying is performed. diff --git a/man/std::chrono::operator==,(std::chrono::day).3 b/man/std::chrono::operator==,(std::chrono::day).3 new file mode 100644 index 000000000..e3874dcdb --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::day).3 @@ -0,0 +1,55 @@ +.TH std::chrono::operator==,(std::chrono::day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::day) \- std::chrono::operator==,(std::chrono::day) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::day& x, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::day& y ) noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::day& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::day& y ) noexcept; + + Compare the two std::chrono::day x and y. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) unsigned(x) == unsigned(y) + 2) unsigned(x) <=> unsigned(y) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::day x{13}, y{31}; + static_assert(x != y); + + if constexpr (constexpr auto res = x <=> y; res < 0) + std::cout << "x is less than y\\n"; + else if constexpr (res > 0) + std::cout << "x is greater than y\\n"; + else + std::cout << "x and y are equal\\n"; + + using namespace std::literals::chrono_literals; + + static_assert + ( + (6d < 9d) && (6d == 6d) && (6d <= 9d) && + (9d > 6d) && (9d != 6d) && (9d >= 6d) + ); + } + +.SH Output: + + x is less than y diff --git a/man/std::chrono::operator==,(std::chrono::month).3 b/man/std::chrono::operator==,(std::chrono::month).3 new file mode 100644 index 000000000..0c38b05a1 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::month).3 @@ -0,0 +1,41 @@ +.TH std::chrono::operator==,(std::chrono::month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::month) \- std::chrono::operator==,(std::chrono::month) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::month& x, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::month& y ) noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::month& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::month& y ) noexcept; + + Compare the two std::chrono::month x and y. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) unsigned(x) == unsigned(y) + 2) unsigned(x) <=> unsigned(y) + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr std::chrono::month m1{6}, m2{8}; + + static_assert + ( + m1 < m2 && m1 == m1 && m1 <= m2 && + m2 > m1 && m2 != m1 && m2 >= m1 && + m1 <=> m2 != 0 + ); + } diff --git a/man/std::chrono::operator==,(std::chrono::month_day).3 b/man/std::chrono::operator==,(std::chrono::month_day).3 new file mode 100644 index 000000000..6ff0bec53 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::month_day).3 @@ -0,0 +1,44 @@ +.TH std::chrono::operator==,(std::chrono::month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::month_day) \- std::chrono::operator==,(std::chrono::month_day) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::month_day& x, + const std::chrono::month_day& y ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::month_day& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::month_day& y ) noexcept; + + Compares two month_day values. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.month() == y.month() && x.day() == y.day() + 2) x.month() <=> y.month() != 0 ? x.month() <=> y.month() : x.day() <=> y.day() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr auto md1{std::chrono::August/15}; + constexpr auto md2{std::chrono::month(8)/std::chrono::day(15)}; + std::cout << std::boolalpha << (md1 == md2) << '\\n'; + + static_assert(md1 <= md2); + } + +.SH Output: + + true diff --git a/man/std::chrono::operator==,(std::chrono::month_day_last).3 b/man/std::chrono::operator==,(std::chrono::month_day_last).3 new file mode 100644 index 000000000..f3b4e8e59 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::month_day_last).3 @@ -0,0 +1,44 @@ +.TH std::chrono::operator==,(std::chrono::month_day_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::month_day_last) \- std::chrono::operator==,(std::chrono::month_day_last) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::month_day_last& x, + const std::chrono::month_day_last& y ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::month_day_last& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::month_day_last& y ) noexcept; + + Compares the two month_day_last values x and y. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.month() == y.month() + 2) x.month() <=> y.month() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr auto mdl1{std::chrono::February/std::chrono::last}; + constexpr std::chrono::month_day_last mdl2{std::chrono::month(2)}; + std::cout << std::boolalpha << (mdl1 == mdl2) << '\\n'; + + static_assert(mdl1 <= mdl2); + } + +.SH Output: + + true diff --git a/man/std::chrono::operator==,(std::chrono::time_zone).3 b/man/std::chrono::operator==,(std::chrono::time_zone).3 new file mode 100644 index 000000000..580b1d6d4 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::time_zone).3 @@ -0,0 +1,21 @@ +.TH std::chrono::operator==,(std::chrono::time_zone) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::time_zone) \- std::chrono::operator==,(std::chrono::time_zone) + +.SH Synopsis + Defined in header + bool operator==( const std::chrono::time_zone& x, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::time_zone& y ) noexcept; + std::strong_ordering operator<=>( const std::chrono::time_zone& x, + const std::chrono::time_zone& y \fB(2)\fP \fI(since C++20)\fP + ) noexcept; + + Compares the two time_zone values x and y by name. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.name() == y.name() + 2) x.name() <=> y.name() diff --git a/man/std::chrono::operator==,(std::chrono::time_zone_link).3 b/man/std::chrono::operator==,(std::chrono::time_zone_link).3 new file mode 100644 index 000000000..57efc7833 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::time_zone_link).3 @@ -0,0 +1,22 @@ +.TH std::chrono::operator==,(std::chrono::time_zone_link) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::time_zone_link) \- std::chrono::operator==,(std::chrono::time_zone_link) + +.SH Synopsis + Defined in header + bool operator==( const std::chrono::time_zone_link& x, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::time_zone_link& y ) noexcept; + std::strong_ordering operator<=>( const + std::chrono::time_zone_link& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::time_zone_link& y ) noexcept; + + Compares the two time_zone_link values x and y by name. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.name() == y.name() + 2) x.name() <=> y.name() diff --git a/man/std::chrono::operator==,(std::chrono::year).3 b/man/std::chrono::operator==,(std::chrono::year).3 new file mode 100644 index 000000000..ec236dfa4 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::year).3 @@ -0,0 +1,47 @@ +.TH std::chrono::operator==,(std::chrono::year) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::year) \- std::chrono::operator==,(std::chrono::year) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::year& x, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::year& y ) noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::year& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::year& y ) noexcept; + + Compare the two std::chrono::year x and y. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) int(x) == int(y) + 2) int(x) <=> int(y) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + + constexpr year y1{2020}; + constexpr year y2{2021}; + + std::cout << std::boolalpha << (y1 != y2) << '\\n'; + + static_assert((2020y < 2023y) && (2020y == 2020y) && (2020y <= 2023y) && + (2023y > 2020y) && (2023y != 2020y) && (2023y >= 2020y)); + } + +.SH Output: + + true diff --git a/man/std::chrono::operator==,(std::chrono::year_month).3 b/man/std::chrono::operator==,(std::chrono::year_month).3 new file mode 100644 index 000000000..7a8580953 --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::year_month).3 @@ -0,0 +1,48 @@ +.TH std::chrono::operator==,(std::chrono::year_month) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::year_month) \- std::chrono::operator==,(std::chrono::year_month) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::year_month& x, + const std::chrono::year_month& y ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::year_month& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::year_month& y ) noexcept; + + Compares the two year_month values x and y. + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.year() == y.year() && x.month() == y.month() + 2) x.year() <=> y.year() != 0 ? x.year() <=> y.year() : x.month() <=> y.month() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + + constexpr year_month ym1{year(2021), month(7)}; + constexpr year_month ym2{year(2021)/7}; + static_assert(ym1 == ym2); + std::cout << ym1 << '\\n'; + + static_assert((2020y/1 < 2020y/2) && (2020y/2 == 2020y/2) && (2020y/3 <= 2021y/3) && + (2023y/1 > 2020y/2) && (3020y/2 != 2020y/2) && (2020y/3 >= 2020y/3)); + } + +.SH Output: + + 2021/Jul diff --git a/man/std::chrono::operator==,(std::chrono::year_month_day).3 b/man/std::chrono::operator==,(std::chrono::year_month_day).3 new file mode 100644 index 000000000..0d66b83be --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::year_month_day).3 @@ -0,0 +1,48 @@ +.TH std::chrono::operator==,(std::chrono::year_month_day) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::year_month_day) \- std::chrono::operator==,(std::chrono::year_month_day) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::year_month_day& x, + const std::chrono::year_month_day& y ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr std::strong_ordering + + operator<=>( const std::chrono::year_month_day& x, \fB(2)\fP \fI(since C++20)\fP + + const std::chrono::year_month_day& y ) noexcept; + + Compares the two year_month_day values x and y. This is a lexicographical + comparison: the year() is compared first, then month(), then day(). + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.year() == y.year() && x.month() == y.month() && x.day() == y.day() + 2) If x.year() <=> y.year != 0, x.year() <=> y.year; otherwise if x.month() <=> + y.month() != 0, x.month() <=> y.month(); otherwise x.day() <=> y.day(). + +.SH Notes + + If both x and y represent valid dates (x.ok() && y.ok() == true), the result of the + lexicographical comparison is consistent with the calendar order. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr auto ymd1{std::chrono::day(13)/7/1337}; + constexpr auto ymd2{std::chrono::year(1337)/7/13}; + static_assert(ymd1 == ymd2); + static_assert(ymd1 <= ymd2); + static_assert(ymd1 >= ymd2); + static_assert(ymd1 <=> ymd2 == 0); + } diff --git a/man/std::chrono::operator==,(std::chrono::year_month_day_last).3 b/man/std::chrono::operator==,(std::chrono::year_month_day_last).3 new file mode 100644 index 000000000..296bf63dc --- /dev/null +++ b/man/std::chrono::operator==,(std::chrono::year_month_day_last).3 @@ -0,0 +1,53 @@ +.TH std::chrono::operator==,(std::chrono::year_month_day_last) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,(std::chrono::year_month_day_last) \- std::chrono::operator==,(std::chrono::year_month_day_last) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::year_month_day_last& + x, \fB(1)\fP \fI(since C++20)\fP + const std::chrono::year_month_day_last& + y ) noexcept; + constexpr std::strong_ordering + + operator<=>( const std::chrono::year_month_day_last& x, \fB(2)\fP \fI(since C++20)\fP + + const std::chrono::year_month_day_last& y ) + noexcept; + + Compares the two year_month_day_last values x and y. This is a lexicographical + comparison: the year() is compared first, then month(). + + The <, <=, >, >=, and != operators are synthesized from operator<=> and operator== + respectively. + +.SH Return value + + 1) x.year() == y.year() && x.month() == y.month() + 2) x.year() <=> y.year() != 0 ? x.year() <=> y.year() : x.month() <=> y.month() + +.SH Notes + + If both x and y represent valid dates (x.ok() && y.ok() == true), the result of the + lexicographical comparison is consistent with the calendar order. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto ymdl1{11/std::chrono::last/2020}; + auto mdl{std::chrono::last/std::chrono::November}; + auto ymdl2{mdl/2020}; + assert(ymdl1 == ymdl2); + + ymdl1 -= std::chrono::months{2}; + ymdl2 -= std::chrono::months{1}; + assert(ymdl1 < ymdl2); + } diff --git a/man/std::chrono::operator==,,>=,(std::chrono::leap_second).3 b/man/std::chrono::operator==,,>=,(std::chrono::leap_second).3 new file mode 100644 index 000000000..96cb09515 --- /dev/null +++ b/man/std::chrono::operator==,,>=,(std::chrono::leap_second).3 @@ -0,0 +1,102 @@ +.TH std::chrono::operator==,,>=,(std::chrono::leap_second) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::operator==,,>=,(std::chrono::leap_second) \- std::chrono::operator==,,>=,(std::chrono::leap_second) + +.SH Synopsis + Defined in header + constexpr bool operator==( const std::chrono::leap_second& x, + const std::chrono::leap_second& y ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr std::strong_ordering operator<=>( const + std::chrono::leap_second& x, \fB(2)\fP \fI(since C++20)\fP + const + std::chrono::leap_second& y ) noexcept; + template< class Duration > + + constexpr bool operator==( const std::chrono::leap_second& x, \fB(3)\fP \fI(since C++20)\fP + + const std::chrono::sys_time& + y ) noexcept; + template< class Duration > + + constexpr bool operator< ( const std::chrono::leap_second& x, \fB(4)\fP \fI(since C++20)\fP + + const std::chrono::sys_time& + y ) noexcept; + template< class Duration > + + constexpr bool operator< ( const std::chrono::sys_time& + x, \fB(5)\fP \fI(since C++20)\fP + + const std::chrono::leap_second& y ) + noexcept; + template< class Duration > + + constexpr bool operator> ( const std::chrono::leap_second& x, \fB(6)\fP \fI(since C++20)\fP + + const std::chrono::sys_time& + y ) noexcept; + template< class Duration > + + constexpr bool operator> ( const std::chrono::sys_time& + x, \fB(7)\fP \fI(since C++20)\fP + + const std::chrono::leap_second& y ) + noexcept; + template< class Duration > + + constexpr bool operator<=( const std::chrono::leap_second& x, \fB(8)\fP \fI(since C++20)\fP + + const std::chrono::sys_time& + y ) noexcept; + template< class Duration > + + constexpr bool operator<=( const std::chrono::sys_time& + x, \fB(9)\fP \fI(since C++20)\fP + + const std::chrono::leap_second& y ) + noexcept; + template< class Duration > + + constexpr bool operator>=( const std::chrono::leap_second& x, \fB(10)\fP \fI(since C++20)\fP + + const std::chrono::sys_time& + y ) noexcept; + template< class Duration > + + constexpr bool operator>=( const std::chrono::sys_time& + x, \fB(11)\fP \fI(since C++20)\fP + + const std::chrono::leap_second& y ) + noexcept; + template< class Duration > + + requires std::three_way_comparable_with< + std::chrono::sys_seconds, + std::chrono::sys_time> \fB(12)\fP \fI(since C++20)\fP + constexpr auto operator<=>( const std::chrono::leap_second& x, + + const + std::chrono::sys_time& y ) noexcept; + + Compares the date and time represented by the objects x and y. + + Return type of \fB(12)\fP is deduced from x.date() <=> y, and hence the three-way + comparison result type of std::chrono::seconds and Duration. + + The != operator is synthesized from operator==. + +.SH Return value + + 1) x.date() == y.date() + 2) x.date() <=> y.date() + 3) x.date() == y + 4) x.date() < y + 5) x < y.date() + 6) x.date() > y + 7) x > y.date() + 8) x.date() <= y + 9) x <= y.date() + 10) x.date() >= y + 11) x >= y.date() + 12) x.date() <=> y diff --git a/man/std::chrono::parse.3 b/man/std::chrono::parse.3 new file mode 100644 index 000000000..9723c4400 --- /dev/null +++ b/man/std::chrono::parse.3 @@ -0,0 +1,327 @@ +.TH std::chrono::parse 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::parse \- std::chrono::parse + +.SH Synopsis + Defined in header + template< class CharT, class Parsable > \fB(1)\fP \fI(since C++20)\fP + /* unspecified */ parse( const CharT* fmt, Parsable& tp ); + template< class CharT, class Traits, class Alloc, class Parsable > + + /* unspecified */ parse( const std::basic_string& fmt, + + Parsable& tp ); + template< class CharT, class Traits, class Alloc, class Parsable > + + /* unspecified */ parse( const CharT* fmt, Parsable& tp, \fB(3)\fP \fI(since C++20)\fP + + std::basic_string& + abbrev ); + template< class CharT, class Traits, class Alloc, class Parsable > + + /* unspecified */ parse( const std::basic_string& fmt, \fB(4)\fP \fI(since C++20)\fP + Parsable& tp, + + std::basic_string& + abbrev ); + template< class CharT, class Parsable > + + /* unspecified */ parse( const CharT* fmt, Parsable& tp, \fB(5)\fP \fI(since C++20)\fP + + std::chrono::minutes& offset ); + template< class CharT, class Traits, class Alloc, class Parsable > + + /* unspecified */ parse( const std::basic_string& fmt, \fB(6)\fP \fI(since C++20)\fP + + Parsable& tp, std::chrono::minutes& + offset ); + template< class CharT, class Traits, class Alloc, class Parsable > + + /* unspecified */ parse( const CharT* fmt, Parsable& tp, + std::basic_string& \fB(7)\fP \fI(since C++20)\fP + abbrev, + + std::chrono::minutes& offset ); + template< class CharT, class Traits, class Alloc, class Parsable > + + /* unspecified */ parse( const std::basic_string& fmt, + Parsable& tp, \fB(8)\fP \fI(since C++20)\fP + std::basic_string& + abbrev, + + std::chrono::minutes& offset ); + + Returns an object manip of unspecified type such that, given a + std::basic_istream object is, the expression is >> manip calls + from_stream (unqualified, to enable argument-dependent lookup) as follows: + + 1) from_stream(is, fmt, tp) + 2) from_stream(is, fmt.c_str(), tp) + 3) from_stream(is, fmt, tp, std::addressof(abbrev)) + 4) from_stream(is, fmt.c_str(), tp, std::addressof(abbrev)) + 5) from_stream(is, fmt, tp, + static_cast*>(nullptr), &offset) + 6) from_stream(is, fmt.c_str(), tp, + static_cast*>(nullptr), &offset) + 7) from_stream(is, fmt, tp, std::addressof(abbrev), &offset) + 8) from_stream(is, fmt.c_str(), tp, std::addressof(abbrev), &offset). + + The expression is >> manip is an lvalue of type std::basic_istream + with the value is. + + These overloads participate in overload resolution only if the corresponding + from_stream expression is well-formed. + + Implementations are recommended to make it difficult to use potentially dangling + references to the format string, e.g., by making return types non-movable and + preventing operator>> from accepting lvalues of return types. + +.SH Parameters + + fmt - a format string (see below) + tp - object to hold the parse result + abbrev - string to hold the time zone abbreviation or name corresponding to the %Z + specifier + offset - duration to represent the offset from UTC corresponding to the %z specifier + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters. Each ordinary character, excluding whitespace characters and the + terminating null character, matches one identical character from the input stream, + or causes the function to fail if the next character on the stream does not compare + equal. + + Each whitespace character matches zero or more whitespace characters in the input + stream. + + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Some conversion specifiers have a modified form in which a width + parameter given as a positive decimal integer (shown as N below) is inserted after + the % character. Each conversion specifier causes the matched characters to be + interpreted as parts of date and time types according to the table below. + + A character sequence in the format string that begins with a % but does not match + one of the conversion specifiers below is interpreted as ordinary characters. + + If from_stream fails to parse everything specified by the format string, or if + insufficient information is parsed to specify a complete result, or if parsing + discloses contradictory information, is.setstate(std::ios_base::failbit) is called. + + The following conversion specifiers are available: + + Conversion Explanation + specifier + %% Matches a literal % character. + %n Matches one whitespace character. + %t Matches zero or one whitespace character. + Year + Parses the century as a decimal number. The width N specifies the + %C maximum number of characters to read. The default width is 2. Leading + %NC zeroes are permitted but not required. + %EC + The modified command %EC interprets the locale's alternative + representation of the century. + Parses the last two decimal digits of the year. If the century is not + otherwise specified (e.g. with %C), values in the range [69, 99] are + %y presumed to refer to the years 1969 to 1999, and values in the range + %Ny [00, 68] are presumed to refer to the years 2000 to 2068. The width N + %Ey specifies the maximum number of characters to read. The default width is + %Oy 2. Leading zeroes are permitted but not required. + + The modified commands %Ey and %Oy interpret the locale's alternative + representation. + Parses the year as a decimal number. The width N specifies the maximum + %Y number of characters to read. The default width is 4. Leading zeroes are + %NY permitted but not required. + %EY + The modified command %EY interprets the locale's alternative + representation. + Month + %b + %B Parses the locale's full or abbreviated case-insensitive month name. + %h + Parses the month as a decimal number (January is 1). The width N + %m specifies the maximum number of characters to read. The default width is + %Nm 2. Leading zeroes are permitted but not required. + %Om + The modified command %Om interprets the locale's alternative + representation. + Day + %d Parses the day of month as a decimal number. The width N specifies the + %Nd maximum number of characters to read. The default width is 2. Leading + %Od zeroes are permitted but not required. + %e + %Ne The modified commands %Od and %Oe interpret the locale's alternative + %Oe representation. + Day of the week + %a Parses the locale's full or abbreviated case-insensitive weekday name. + %A + %u Parses the ISO weekday as a decimal number (1-7), where Monday is 1. The + %Nu width N specifies the maximum number of characters to read. The default + width is 1. Leading zeroes are permitted but not required. + Parses the weekday as a decimal number (0-6), where Sunday is 0. The + %w width N specifies the maximum number of characters to read. The default + %Nw width is 1. Leading zeroes are permitted but not required. + %Ow + The modified command %Ow interprets the locale's alternative + representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Parses the last two decimal digits of the ISO 8601 week-based year. The + %Ng width N specifies the maximum number of characters to read. The default + width is 2. Leading zeroes are permitted but not required. + %G Parses the ISO 8601 week-based year as a decimal number. The width N + %NG specifies the maximum number of characters to read. The default width is + 4. Leading zeroes are permitted but not required. + %V Parses the ISO 8601 week of the year as a decimal number. The width N + %NV specifies the maximum number of characters to read. The default width is + 2. Leading zeroes are permitted but not required. + Week/day of the year + %j Parses the day of the year as a decimal number (January 1 is 1). The + %Nj width N specifies the maximum number of characters to read. The default + width is 3. Leading zeroes are permitted but not required. + Parses the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. The width N specifies the maximum number of + %NU characters to read. The default width is 2. Leading zeroes are permitted + %OU but not required. + + The modified command %OU interprets the locale's alternative + representation. + Parses the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. The width N specifies the maximum number of + %NW characters to read. The default width is 2. Leading zeroes are permitted + %OW but not required. + + The modified command %OW interprets the locale's alternative + representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". If the width is specified, it is only applied + %NF to the %Y. + Parses the locale's date representation. + %x + %Ex The modified command %Ex interprets the locale's alternate date + representation. + Time of day + Parses the hour (24-hour clock) as a decimal number. The width N + %H specifies the maximum number of characters to read. The default width is + %NH 2. Leading zeroes are permitted but not required. + %OH + The modified command %OH interprets the locale's alternative + representation. + Parses the hour (12-hour clock) as a decimal number. The width N + %I specifies the maximum number of characters to read. The default width is + %NI 2. Leading zeroes are permitted but not required. + %OI + The modified command %OI interprets the locale's alternative + representation. + Parses the minute as a decimal number. The width N specifies the maximum + %M number of characters to read. The default width is 2. Leading zeroes are + %NM permitted but not required. + %OM + The modified command %OM interprets the locale's alternative + representation. + Parses the second as a decimal number. The width N specifies the maximum + %S number of characters to read. The default width is 2. Leading zeroes are + %NS permitted but not required. + %OS + The modified command %OS interprets the locale's alternative + representation. + %p Parses the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Parses the locale's 12-hour clock time. + Parses the locale's time representation. + %X + %EX The modified command %EX interprets the locale's alternate time + representation. +.SH Miscellaneous + Parses the locale's date and time representation. + %c + %Ec The modified command %Ec interprets the locale's alternative date and + time representation. + Parses the offset from UTC in the format [+|-]hh[mm]. For example -0430 + refers to 4 hours 30 minutes behind UTC and 04 refers to 4 hours ahead + %z of UTC. + %Ez + %Oz The modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] + (i.e., requiring a : between the hours and minutes and making the + leading zero for hour optional). + Parses the time zone abbreviation or name, taken as the longest sequence + %Z of characters that only contains the characters A through Z, a through + z, 0 through 9, -, +, _, and /. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3554 C++20 overloads for plain null-terminated character added + type sequences were missing + +.SH See also + + from_stream(std::chrono::sys_time) parses a sys_time from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream(std::chrono::utc_time) parses a utc_time from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream(std::chrono::tai_time) parses a tai_time from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream(std::chrono::gps_time) parses a gps_time from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream(std::chrono::file_time) parses a file_time from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream(std::chrono::local_time) parses a local_time from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream parses a year from a stream according to the + (C++20) provided format + \fI(function template)\fP + from_stream parses a month from a stream according to the + (C++20) provided format + \fI(function template)\fP + from_stream parses a day from a stream according to the + (C++20) provided format + \fI(function template)\fP + from_stream parses a weekday from a stream according to the + (C++20) provided format + \fI(function template)\fP + from_stream parses a month_day from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream parses a year_month from a stream according to + (C++20) the provided format + \fI(function template)\fP + from_stream parses a year_month_day from a stream according + (C++20) to the provided format + \fI(function template)\fP + get_time parses a date/time value of specified format + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::round(std::chrono::duration).3 b/man/std::chrono::round(std::chrono::duration).3 new file mode 100644 index 000000000..2adda7499 --- /dev/null +++ b/man/std::chrono::round(std::chrono::duration).3 @@ -0,0 +1,124 @@ +.TH std::chrono::round(std::chrono::duration) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::round(std::chrono::duration) \- std::chrono::round(std::chrono::duration) + +.SH Synopsis + Defined in header + template< class ToDuration, class Rep, class Period > + constexpr ToDuration round( const std::chrono::duration& \fI(since C++17)\fP + d ); + + Returns the value t representable in ToDuration that is the closest to d. If there + are two such values, returns the even value (that is, the value t such that t % 2 == + 0). + + The function does not participate in the overload resolution unless ToDuration is a + specialization of std::chrono::duration and + std::chrono::treat_as_floating_point_v is false. + +.SH Parameters + + d - duration to convert + +.SH Return value + + d rounded to the nearest duration of type ToDuration, rounding to even in halfway + cases. + +.SH Possible implementation + + namespace detail + { + template inline constexpr bool is_duration_v = false; + template inline constexpr bool is_duration_v< + std::chrono::duration> = true; + } + + template && + !std::chrono::treat_as_floating_point_v>> + constexpr To round(const std::chrono::duration& d) + { + To t0 = std::chrono::floor(d); + To t1 = t0 + To{1}; + auto diff0 = d - t0; + auto diff1 = t1 - d; + if (diff0 == diff1) + { + if (t0.count() & 1) + return t1; + return t0; + } + else if (diff0 < diff1) + return t0; + return t1; + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::chrono_literals; + std::cout << "Duration\\tFloor\\tRound\\tCeil\\n"; + for (using Sec = std::chrono::seconds; + auto const d : {+4999ms, +5000ms, +5001ms, +5499ms, +5500ms, +5999ms, + -4999ms, -5000ms, -5001ms, -5499ms, -5500ms, -5999ms}) + std::cout << std::showpos << d << "\\t\\t" + << std::chrono::floor(d) << '\\t' + << std::chrono::round(d) << '\\t' + << std::chrono::ceil (d) << '\\n'; + } + +.SH Output: + + Duration Floor Round Ceil + +4999ms +4s +5s +5s + +5000ms +5s +5s +5s + +5001ms +5s +5s +6s + +5499ms +5s +5s +6s + +5500ms +5s +6s +6s + +5999ms +5s +6s +6s + -4999ms -5s -5s -4s + -5000ms -5s -5s -5s + -5001ms -6s -5s -5s + -5499ms -6s -5s -5s + -5500ms -6s -6s -5s + -5999ms -6s -6s -5s + +.SH See also + + duration_cast converts a duration to another, with a different tick + \fI(C++11)\fP interval + \fI(function template)\fP + floor(std::chrono::duration) converts a duration to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + ceil(std::chrono::duration) converts a duration to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::time_point) converts a time_point to another, rounding to + \fI(C++17)\fP nearest, ties to even + \fI(function template)\fP + round + roundf + roundl + lround + lroundf + lroundl + llround + llroundf nearest integer, rounding away from zero in halfway + llroundl cases + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::round(std::chrono::time_point).3 b/man/std::chrono::round(std::chrono::time_point).3 new file mode 100644 index 000000000..abeef9808 --- /dev/null +++ b/man/std::chrono::round(std::chrono::time_point).3 @@ -0,0 +1,121 @@ +.TH std::chrono::round(std::chrono::time_point) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::round(std::chrono::time_point) \- std::chrono::round(std::chrono::time_point) + +.SH Synopsis + Defined in header + template< class ToDuration, class Clock, class Duration > + + constexpr std::chrono::time_point \fI(since C++17)\fP + + round( const std::chrono::time_point& tp ); + + Returns the nearest time point to tp representable in ToDuration, rounding to even + in halfway cases. + + The function does not participate in the overload resolution unless ToDuration is a + specialization of std::chrono::duration and + std::chrono::treat_as_floating_point_v is false. + +.SH Parameters + + tp - time point to round to nearest + +.SH Return value + + tp rounded to nearest time point using duration of type ToDuration, rounding to even + in halfway cases. + +.SH Possible implementation + + namespace detail + { + template inline constexpr bool is_duration_v = false; + template inline constexpr bool is_duration_v< + std::chrono::duration> = true; + } + + template && + !std::chrono::treat_as_floating_point_v>> + constexpr std::chrono::time_point round( + const std::chrono::time_point& tp) + { + return std::chrono::time_point{ + std::chrono::round(tp.time_since_epoch())}; + } + +.SH Example + + + +// Run this code + + #include + #include + #include + + template + std::string to_string(const TimePoint& time_point) + { + return std::to_string(time_point.time_since_epoch().count()); + } + + int main() + { + using namespace std::literals::chrono_literals; + using Sec = std::chrono::seconds; + + std::cout << "Time point\\t" "Cast\\t" "Floor\\t" "Round\\t" "Ceil\\n"; + std::cout << "(ms)\\t\\t" "(s)\\t" "(s)\\t" "(s)\\t" "(s)\\n"; + for (const auto value_ms : {5432ms, 5678ms}) + { + std::chrono::time_point + time_point_ms(value_ms); + + std::cout + << to_string(time_point_ms) << "\\t\\t" + << to_string(std::chrono::time_point_cast(time_point_ms)) << '\\t' + << to_string(std::chrono::floor(time_point_ms)) << '\\t' + << to_string(std::chrono::round(time_point_ms)) << '\\t' + << to_string(std::chrono::ceil(time_point_ms)) << '\\n'; + } + } + +.SH Output: + + Time point Cast Floor Round Ceil + (ms) (s) (s) (s) (s) + 5432 5 5 5 6 + 5678 5 5 6 6 + +.SH See also + + time_point_cast converts a time point to another time point on the + \fI(C++11)\fP same clock, with a different duration + \fI(function template)\fP + ceil(std::chrono::time_point) converts a time_point to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + floor(std::chrono::time_point) converts a time_point to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::duration) converts a duration to another, rounding to nearest, + \fI(C++17)\fP ties to even + \fI(function template)\fP + round + roundf + roundl + lround + lroundf + lroundl + llround + llroundf nearest integer, rounding away from zero in halfway + llroundl cases + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::chrono::steady_clock.3 b/man/std::chrono::steady_clock.3 index d8a2e67fd..c8efa43a3 100644 --- a/man/std::chrono::steady_clock.3 +++ b/man/std::chrono::steady_clock.3 @@ -1,11 +1,16 @@ -.TH std::chrono::steady_clock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::steady_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::steady_clock \- std::chrono::steady_clock + .SH Synopsis Defined in header class steady_clock; \fI(since C++11)\fP Class std::chrono::steady_clock represents a monotonic clock. The time points of - this clock cannot decrease as physical time moves forward. This clock is not related - to wall clock time, and is best suitable for measuring intervals. + this clock cannot decrease as physical time moves forward and the time between ticks + of this clock is constant. This clock is not related to wall clock time (for + example, it can be time since last reboot), and is most suitable for measuring + intervals. std::chrono::steady_clock meets the requirements of TrivialClock. diff --git a/man/std::chrono::steady_clock::now.3 b/man/std::chrono::steady_clock::now.3 index ca2cf8eaa..356dd15dd 100644 --- a/man/std::chrono::steady_clock::now.3 +++ b/man/std::chrono::steady_clock::now.3 @@ -1,8 +1,12 @@ -.TH std::chrono::steady_clock::now 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::steady_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::steady_clock::now \- std::chrono::steady_clock::now + .SH Synopsis - static std::chrono::time_point now(); \fI(since C++11)\fP + static std::chrono::time_point now() \fI(since C++11)\fP + noexcept; - Returns a time point representing with the current point in time. + Returns a time point representing the current point in time. .SH Parameters @@ -12,39 +16,46 @@ A time point representing the current time. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code + #include + #include + #include #include + #include #include - #include - + + volatile int sink; + + void do_some_work(std::size_t size) + { + std::vector v(size, 42); + sink = std::accumulate(v.begin(), v.end(), 0); // make sure it is a side effect + } + int main() { - for (unsigned long long size = 1; size < 10000000; size *= 10) { - auto start = std::chrono::steady_clock::now(); - std::vector v(size, 42); - auto end = std::chrono::steady_clock::now(); - - auto elapsed = end - start; - std::cout << size << ": " << elapsed.count() << '\\n'; + std::cout << std::fixed << std::setprecision(9) << std::left; + for (auto size{1ull}; size < 10'00'00'00'00ull; size *= 100) + { + const auto start = std::chrono::steady_clock::now(); + do_some_work(size); + const auto end = std::chrono::steady_clock::now(); + + const std::chrono::duration diff = end - start; + + std::cout << "Time to fill and iterate a vector of " << std::setw(9) + << size << " ints : " << diff << '\\n'; } } .SH Possible output: - 1: 1 - 10: 2 - 100: 3 - 1000: 6 - 10000: 47 - 100000: 507 - 1000000: 4822 + Time to fill and iterate a vector of 1 ints : 0.000006568s + Time to fill and iterate a vector of 100 ints : 0.000002854s + Time to fill and iterate a vector of 10000 ints : 0.000116290s + Time to fill and iterate a vector of 1000000 ints : 0.011742752s + Time to fill and iterate a vector of 100000000 ints : 0.505534949s diff --git a/man/std::chrono::sys_info.3 b/man/std::chrono::sys_info.3 new file mode 100644 index 000000000..35c90499a --- /dev/null +++ b/man/std::chrono::sys_info.3 @@ -0,0 +1,52 @@ +.TH std::chrono::sys_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::sys_info \- std::chrono::sys_info + +.SH Synopsis + Defined in header + struct sys_info; \fI(since C++20)\fP + + The class sys_info describes time zone information associated with a time zone at a + particular point in time (represented as either a std::chrono::sys_time or a + std::chrono::local_time). This is a low-level data structure typically not used + directly by user code. + +.SH Member objects + + Member object Type + begin, end std::chrono::sys_seconds + offset std::chrono::seconds + save std::chrono::minutes + abbrev std::string + + The begin and end data members indicate the range - [begin, end) - in which the + offset and abbrev are in effect for the time zone associated with this sys_info. + + The offset and abbrev data member indicate the UTC offset and time zone + abbreviation, respectively, in effect for the associated time zone and + std::chrono::time_point. Note that time zone abbreviations are not unique. + + The save data member, if nonzero, indicates that the time zone is on daylight saving + time at the specified time point. In this case, offset - save is a suggestion of + what offset this time zone might use if it were off daylight saving time. However, + this information is not authoritative: the only way to ascertain the actual offset + is to query the time zone with a time point that is actually off daylight savings + time (i.e. returns a sys_info such that save == 0min). + + Nonmember functions + + operator<< outputs a sys_info into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for sys_info + (C++20) \fI(class template specialization)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::chrono::system_clock.3 b/man/std::chrono::system_clock.3 index 98f456018..d75810269 100644 --- a/man/std::chrono::system_clock.3 +++ b/man/std::chrono::system_clock.3 @@ -1,4 +1,7 @@ -.TH std::chrono::system_clock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::system_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::system_clock \- std::chrono::system_clock + .SH Synopsis Defined in header class system_clock; \fI(since C++11)\fP @@ -7,16 +10,23 @@ It may not be monotonic: on most systems, the system time can be adjusted at any moment. It is the only C++ clock that has the ability to map its time points to - C-style time, and, therefore, to be displayed. + C-style time. std::chrono::system_clock meets the requirements of TrivialClock. + The epoch of system_clock is unspecified, but most implementations use + Unix Time (i.e., time since 00:00:00 Coordinated Universal Time (UTC), \fI(until C++20)\fP + Thursday, 1 January 1970, not counting leap seconds). + system_clock measures Unix Time (i.e., time since 00:00:00 Coordinated + Universal Time (UTC), Thursday, 1 January 1970, not counting leap \fI(since C++20)\fP + seconds). + .SH Member types Member type Definition rep signed arithmetic type representing the number of ticks in the clock's duration - period an std::ratio type representing the tick period of the clock, in seconds + period a std::ratio type representing the tick period of the clock, in seconds duration std::chrono::duration, capable of representing negative durations time_point std::chrono::time_point @@ -25,17 +35,25 @@ true if the time between ticks is always constant, i.e. constexpr bool is_steady calls to now() return values that increase monotonically - \fB[static]\fP even in case of some external clock adjustment + \fB[static]\fP even in case of some external clock adjustment, otherwise + false \fI(public static member constant)\fP .SH Member functions now returns a std::chrono::time_point representing the current point in time - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP to_time_t converts a system clock time point to std::time_t - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP from_time_t converts std::time_t to a system clock time point - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP + +.SH Notes + + The system_clock's time value can be internally adjusted at any time by the + operating system, for example due to NTP synchronization or the user changing the + system's clock. Daylight Saving Time and time zone changes, however, do not affect + it since it is based on the UTC time-zone. .SH See also diff --git a/man/std::chrono::system_clock::from_time_t.3 b/man/std::chrono::system_clock::from_time_t.3 index aee065687..c22d488ac 100644 --- a/man/std::chrono::system_clock::from_time_t.3 +++ b/man/std::chrono::system_clock::from_time_t.3 @@ -1,6 +1,10 @@ -.TH std::chrono::system_clock::from_time_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::system_clock::from_time_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::system_clock::from_time_t \- std::chrono::system_clock::from_time_t + .SH Synopsis - static std::chrono::time_point from_time_t( std::time_t t ); \fI(since C++11)\fP + static std::chrono::system_clock::time_point from_time_t( std::time_t \fI(since C++11)\fP + t ) noexcept; Converts t to a time point type, using the coarser precision of the two types. @@ -13,15 +17,40 @@ .SH Return value - A value of type std::chrono::time_point representing t. + A value of type std::chrono::system_clock::time_point representing t. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::chrono_literals; + + const std::time_t t = std::time(nullptr); // usually has "1 second" precision + + const auto from = std::chrono::system_clock::from_time_t(t); + + std::this_thread::sleep_for(500ms); + + const auto diff = std::chrono::system_clock::now() - from; + + std::cout << diff << " (" + << std::chrono::round(diff) + << ")\\n"; + } -.SH Exceptions +.SH Possible output: - noexcept specification: - noexcept - + 987654321ns (987ms) .SH See also to_time_t converts a system clock time point to std::time_t - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::system_clock::now.3 b/man/std::chrono::system_clock::now.3 index ce5fad658..135813b5c 100644 --- a/man/std::chrono::system_clock::now.3 +++ b/man/std::chrono::system_clock::now.3 @@ -1,8 +1,12 @@ -.TH std::chrono::system_clock::now 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::system_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::system_clock::now \- std::chrono::system_clock::now + .SH Synopsis - static std::chrono::time_point now(); \fI(since C++11)\fP + static std::chrono::time_point now() \fI(since C++11)\fP + noexcept; - Returns a time point representing with the current point in time. + Returns a time point representing the current point in time. .SH Parameters @@ -12,39 +16,21 @@ A time point representing the current time. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code - #include - #include #include - + #include + int main() { - for (unsigned long long size = 1; size < 10000000; size *= 10) { - auto start = std::chrono::system_clock::now(); - std::vector v(size, 42); - auto end = std::chrono::system_clock::now(); - - auto elapsed = end - start; - std::cout << size << ": " << elapsed.count() << '\\n'; - } + const auto now = std::chrono::system_clock::now(); + const std::time_t t_c = std::chrono::system_clock::to_time_t(now); + std::cout << "The system clock is currently at " << std::ctime(&t_c); } .SH Possible output: - 1: 1 - 10: 2 - 100: 3 - 1000: 6 - 10000: 47 - 100000: 507 - 1000000: 4822 + The system clock is currently at Thu Mar 30 13:28:27 2023 diff --git a/man/std::chrono::system_clock::to_time_t.3 b/man/std::chrono::system_clock::to_time_t.3 index cb715fdd1..9885712a7 100644 --- a/man/std::chrono::system_clock::to_time_t.3 +++ b/man/std::chrono::system_clock::to_time_t.3 @@ -1,6 +1,9 @@ -.TH std::chrono::system_clock::to_time_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::system_clock::to_time_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::system_clock::to_time_t \- std::chrono::system_clock::to_time_t + .SH Synopsis - static std::time_t to_time_t( const time_point& t ); \fI(since C++11)\fP + static std::time_t to_time_t( const time_point& t ) noexcept; \fI(since C++11)\fP Converts t to a std::time_t type. @@ -15,13 +18,38 @@ A std::time_t value representing t. -.SH Exceptions +.SH Example + + Get the current time as a std::time_t two ways. + + +// Run this code + + #include + #include + #include + #include + using namespace std::chrono_literals; + + int main() + { + // The old way + std::time_t oldt = std::time({}); + + std::this_thread::sleep_for(2700ms); + + // The new way + auto const now = std::chrono::system_clock::now(); + std::time_t newt = std::chrono::system_clock::to_time_t(now); + + std::cout << "newt - oldt == " << newt - oldt << " s\\n"; + } + +.SH Possible output: - noexcept specification: - noexcept - + newt - oldt == 3 s .SH See also from_time_t converts std::time_t to a system clock time point - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::tai_clock.3 b/man/std::chrono::tai_clock.3 new file mode 100644 index 000000000..ff9c2bcd9 --- /dev/null +++ b/man/std::chrono::tai_clock.3 @@ -0,0 +1,49 @@ +.TH std::chrono::tai_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tai_clock \- std::chrono::tai_clock + +.SH Synopsis + Defined in header + class tai_clock; \fI(since C++20)\fP + + The clock std::chrono::tai_clock is a Clock that represents International Atomic + Time (TAI). It measures time since 00:00:00, 1 January 1958, and is offset 10 + seconds ahead of UTC at that date (i.e., its epoch, 1958-01-01 00:00:00 TAI, is + 1957-12-31 23:59:50 UTC). + + Leap seconds are not inserted into TAI. Thus, every time a leap second is inserted + into UTC, UTC falls another second behind TAI. As of December 2017, UTC is 37 + seconds behind TAI, reflecting the 10-second initial offset and the 27 leap seconds + inserted between 1958 and 2017. Thus, 2018-01-01 00:00:00 UTC is equivalent to + 2018-01-01 00:00:37 TAI. + + tai_clock meets the Clock requirements. It does not meet the TrivialClock + requirements unless the implementation can guarantee that now() does not throw an + exception. + +.SH Member types + + Member type Definition + rep signed arithmetic type representing the number of ticks in the clock's + duration + period a std::ratio type representing the tick period of the clock, in seconds + duration std::chrono::duration, capable of representing negative + durations + time_point std::chrono::time_point + +.SH Member constants + + true if the time between ticks is always constant, i.e. + constexpr bool is_steady calls to now() return values that increase monotonically + \fB[static]\fP even in case of some external clock adjustment, otherwise + false + \fI(public static member constant)\fP + +.SH Member functions + + now returns a std::chrono::time_point representing the current point in time + \fB[static]\fP \fI(public static member function)\fP + to_utc converts tai_time to utc_time + \fB[static]\fP \fI(public static member function)\fP + from_utc converts utc_time to tai_time + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::chrono::tai_clock::from_utc.3 b/man/std::chrono::tai_clock::from_utc.3 new file mode 100644 index 000000000..233509dd6 --- /dev/null +++ b/man/std::chrono::tai_clock::from_utc.3 @@ -0,0 +1,27 @@ +.TH std::chrono::tai_clock::from_utc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tai_clock::from_utc \- std::chrono::tai_clock::from_utc + +.SH Synopsis + template< class Duration > + + static std::chrono::tai_time> + + from_utc( const std::chrono::utc_time& ) noexcept; + + Converts the utc_time t to a tai_time representing the same point in time. + +.SH Return value + + A std::chrono::tai_time representing the same point in time as t, computed as if by + constructing a value of the return type from t.time_since_epoch() and adding + 378691210s (378691210 is the number of seconds between the epochs of the two clocks: + 1958-01-01 00:00:00 TAI and 1970-01-01 00:00:00 UTC). + +.SH See also + + to_utc converts tai_time to utc_time + \fB[static]\fP \fI(public static member function)\fP + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::tai_clock::now.3 b/man/std::chrono::tai_clock::now.3 new file mode 100644 index 000000000..2e0007626 --- /dev/null +++ b/man/std::chrono::tai_clock::now.3 @@ -0,0 +1,62 @@ +.TH std::chrono::tai_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tai_clock::now \- std::chrono::tai_clock::now + +.SH Synopsis + static std::chrono::time_point now(); \fI(since C++20)\fP + + Returns a time point representing the current point in time. The result is + calculated as if by std::chrono::tai_clock::from_utc(std::chrono::utc_clock::now()). + Implementations may use a more accurate value of TAI time. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A time point representing the current time. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + volatile int sink; + + void do_some_work(std::size_t size) + { + std::vector v(size, 42); + sink = std::accumulate(v.begin(), v.end(), 0); // make sure it is a side effect + } + + int main() + { + std::cout << std::fixed << std::setprecision(9) << std::left; + for (auto size{1ull}; size < 10'00'00'00'00ull; size *= 100) + { + const auto start = std::chrono::tai_clock::now(); + do_some_work(size); + const auto end = std::chrono::tai_clock::now(); + + const std::chrono::duration diff = end - start; + + std::cout << "Time to fill and iterate a vector of " << std::setw(9) + << size << " ints : " << diff << '\\n'; + } + } + +.SH Possible output: + + Time to fill and iterate a vector of 1 ints : 0.000006568s + Time to fill and iterate a vector of 100 ints : 0.000002854s + Time to fill and iterate a vector of 10000 ints : 0.000116290s + Time to fill and iterate a vector of 1000000 ints : 0.011742752s + Time to fill and iterate a vector of 100000000 ints : 0.505534949s diff --git a/man/std::chrono::tai_clock::to_utc.3 b/man/std::chrono::tai_clock::to_utc.3 new file mode 100644 index 000000000..6fe7e6868 --- /dev/null +++ b/man/std::chrono::tai_clock::to_utc.3 @@ -0,0 +1,27 @@ +.TH std::chrono::tai_clock::to_utc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tai_clock::to_utc \- std::chrono::tai_clock::to_utc + +.SH Synopsis + template< class Duration > + + static std::chrono::utc_time> + + to_utc( const std::chrono::tai_time& t ) noexcept; + + Converts the tai_time t to a utc_time representing the same point in time. + +.SH Return value + + A std::chrono::utc_time representing the same point in time as t, computed as if by + constructing a value of the return type from t.time_since_epoch() and subtracting + 378691210s (378691210 is the number of seconds between the epochs of the two clocks: + 1958-01-01 00:00:00 TAI and 1970-01-01 00:00:00 UTC). + +.SH See also + + from_utc converts utc_time to tai_time + \fB[static]\fP \fI(public static member function)\fP + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::time_point.3 b/man/std::chrono::time_point.3 index 1fea8e4c7..2273ee60a 100644 --- a/man/std::chrono::time_point.3 +++ b/man/std::chrono::time_point.3 @@ -1,4 +1,7 @@ -.TH std::chrono::time_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::time_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point \- std::chrono::time_point + .SH Synopsis Defined in header template< @@ -12,6 +15,10 @@ as if it stores a value of type Duration indicating the time interval from the start of the Clock's epoch. + Clock must meet the requirements for Clock + or be std::chrono::local_t (until C++23) + \fI(since C++20)\fP. + .SH Member types Member type Definition @@ -24,91 +31,115 @@ .SH Member functions constructor constructs a new time point - \fI(public member function)\fP + \fI(public member function)\fP time_since_epoch returns the time point as duration since the start of its clock - \fI(public member function)\fP + \fI(public member function)\fP operator+= modifies the time point by the given duration - operator-= \fI(public member function)\fP + operator-= \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the duration + operator-- \fI(public member function)\fP + operator--(int) + (C++20) min returns the time point corresponding to the smallest duration - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP max returns the time point corresponding to the largest duration - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP .SH Non-member functions - std::common_type specializes the std::common_type trait - \fI(class template specialization)\fP - operator+ modifies the time point by the given - operator- duration - \fI(function template)\fP + operator+ performs add and subtract operations involving a time + operator- point + \fI(C++11)\fP \fI(function template)\fP operator== operator!= - operator< compares two time points - operator<= \fI(function template)\fP + operator< + operator<= operator> operator>= - converts a time point to another time - time_point_cast point on the same clock, with a different - duration - \fI(function template)\fP + operator<=> compares two time points + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + (C++20) + time_point_cast converts a time point to another time point on the + \fI(C++11)\fP same clock, with a different duration + \fI(function template)\fP + floor(std::chrono::time_point) converts a time_point to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + ceil(std::chrono::time_point) converts a time_point to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::time_point) converts a time_point to another, rounding to + \fI(C++17)\fP nearest, ties to even + \fI(function template)\fP + +.SH Helper classes + + std::common_type specializes the std::common_type trait + \fI(C++11)\fP \fI(class template specialization)\fP + std::hash hash support for std::chrono::time_point + (C++26) \fI(class template specialization)\fP .SH Example - This example prints the current time minus 24 hours: - // Run this code - #include - #include - #include + #include #include - - int main() + #include + #include + #include + + void slow_motion() { - - using namespace std::chrono; - - system_clock::time_point now = system_clock::now(); - std::time_t now_c = system_clock::to_time_t( - now - std::chrono::hours(24)); - std::cout << "One day ago, the time was " - << std::put_time(std::localtime(&now_c), "%F %T") << '\\n'; + static int a[]{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}; + // Generate Γ(13) == 12! permutations: + while (std::ranges::next_permutation(a).found) {} } -.SH Possible output: + int main() + { + using namespace std::literals; // enables literal suffixes, e.g. 24h, 1ms, 1s. - One day ago, the time was 2011-10-25 12:00:08 + const std::chrono::time_point now = + std::chrono::system_clock::now(); - This example prints the time it takes to print "Hello World": + const std::time_t t_c = std::chrono::system_clock::to_time_t(now - 24h); + std::cout << "24 hours ago, the time was " + << std::put_time(std::localtime(&t_c), "%F %T.\\n") << std::flush; - -// Run this code + const std::chrono::time_point start = + std::chrono::steady_clock::now(); - #include - #include - - using std::chrono::duration_cast; - using std::chrono::microseconds; - using std::chrono::steady_clock; - - int main() - { - steady_clock::time_point start = steady_clock::now(); - std::cout << "Hello World\\n"; - steady_clock::time_point end = steady_clock::now(); - std::cout << "Printing took " - // duration_cast is required to avoid accidentally losing precision. - << duration_cast(end - start).count() - << "us.\\n"; + std::cout << "Different clocks are not comparable: \\n" + " System time: " << now.time_since_epoch() << "\\n" + " Steady time: " << start.time_since_epoch() << '\\n'; + + slow_motion(); + + const auto end = std::chrono::steady_clock::now(); + std::cout + << "Slow calculations took " + << std::chrono::duration_cast(end - start) << " ≈ " + << (end - start) / 1ms << "ms ≈ " // almost equivalent form of the above, but + << (end - start) / 1s << "s.\\n"; // using milliseconds and seconds accordingly } .SH Possible output: - Hello World - Printing took 84us. + 24 hours ago, the time was 2021-02-15 18:28:52. + Different clocks are not comparable: + System time: 1666497022681282572ns + Steady time: 413668317434475ns + Slow calculations took 2090448µs ≈ 2090ms ≈ 2s. .SH See also - duration a time interval - \fI(C++11)\fP \fI(class template)\fP + duration a time interval + \fI(C++11)\fP \fI(class template)\fP + year_month_day represents a specific year, month, and day + (C++20) \fI(class)\fP diff --git a/man/std::chrono::time_point::max.3 b/man/std::chrono::time_point::max.3 index 43dd9486b..637f7c092 100644 --- a/man/std::chrono::time_point::max.3 +++ b/man/std::chrono::time_point::max.3 @@ -1,9 +1,13 @@ -.TH std::chrono::time_point::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::time_point::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point::max \- std::chrono::time_point::max + .SH Synopsis - static constexpr time_point max(); + static constexpr time_point max(); \fI(until C++20)\fP + static constexpr time_point max() noexcept; \fI(since C++20)\fP Returns a time_point with the largest possible duration, i.e. - std::chrono::time_point(std::chrono::duration::max()). + time_point(std::chrono::duration::max()). .SH Parameters @@ -11,38 +15,41 @@ .SH Return value - the largest possible time_point + The largest possible time_point. .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::chrono::time_point now = std::chrono::system_clock::now(); - std::vector> times { + std::vector> times + { now - std::chrono::hours(24), now - std::chrono::hours(48), - now + std::chrono::hours(24), + now + std::chrono::hours(24) }; - + std::chrono::time_point earliest = std::chrono::time_point::max(); - + std::cout << "all times:\\n"; - for (const auto &time : times) { + for (const auto& time : times) + { std::time_t t = std::chrono::system_clock::to_time_t(time); std::cout << std::ctime(&t); - - if (time < earliest) earliest = time; + + if (time < earliest) + earliest = time; } - + std::time_t t = std::chrono::system_clock::to_time_t(earliest); std::cout << "earliest:\\n" << std::ctime(&t); } diff --git a/man/std::chrono::time_point::min.3 b/man/std::chrono::time_point::min.3 index 2ff654eb0..ab487222d 100644 --- a/man/std::chrono::time_point::min.3 +++ b/man/std::chrono::time_point::min.3 @@ -1,9 +1,13 @@ -.TH std::chrono::time_point::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::time_point::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point::min \- std::chrono::time_point::min + .SH Synopsis - static constexpr time_point min(); + static constexpr time_point min(); \fI(until C++20)\fP + static constexpr time_point min() noexcept; \fI(since C++20)\fP Returns a time_point with the smallest possible duration, i.e. - std::chrono::time_point(std::chrono::duration::min()). + time_point(std::chrono::duration::min()). .SH Parameters @@ -11,13 +15,48 @@ .SH Return value - the smallest possible time_point + The smallest possible time_point. .SH Example - This section is incomplete - Reason: no example - -.SH Category: - * Todo no example +// Run this code + + #include + #include + #include + #include + #include + + constexpr auto steady_min = std::chrono::steady_clock::time_point::min(); + + void animate_frame_at_time_offset(double game_time) + { + std::cout << std::string(static_cast(game_time) % 10 + 1, '*') << '\\n'; + } + + int main() + { + auto last_frame = steady_min; + std::chrono::duration game_time{0.0}; + + for (int n = 0; n < 5; ++n) + { + const auto current_frame = std::chrono::steady_clock::now(); + // initialize timer if first frame ever: + if (last_frame == steady_min) + last_frame = current_frame; + game_time += current_frame - last_frame; + std::cout << "Drawing frame at " << std::setprecision(10) + << std::setw(8) << game_time.count() << " μs "; + animate_frame_at_time_offset(game_time.count()); + } + } + +.SH Possible output: + + Drawing frame at 0 μs * + Drawing frame at 134.499 μs ***** + Drawing frame at 274.337 μs ***** + Drawing frame at 416.571 μs ******* + Drawing frame at 561.124 μs ** diff --git a/man/std::chrono::time_point::operator++,.3 b/man/std::chrono::time_point::operator++,.3 new file mode 100644 index 000000000..d6d1a9ab8 --- /dev/null +++ b/man/std::chrono::time_point::operator++,.3 @@ -0,0 +1,49 @@ +.TH std::chrono::time_point::operator++, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point::operator++, \- std::chrono::time_point::operator++, + +.SH Synopsis + + constexpr time_point& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr time_point operator++( int ); \fB(2)\fP \fI(since C++20)\fP + constexpr time_point& operator--(); \fB(3)\fP \fI(since C++20)\fP + constexpr time_point operator--( int ); \fB(4)\fP \fI(since C++20)\fP + + Modifies the point in time *this represents by one tick of the duration. + + If d_ is a member variable holding the duration (i.e., time since epoch) of this + time_point object, + + 1) Equivalent to ++d_; return *this;. + 2) Equivalent to return time_point(d_++). + 3) Equivalent to --d_; return *this;. + 4) Equivalent to return time_point(d_--);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) A reference to this time_point after modification. + 2,4) A copy of the time_point made before modification. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator++ + operator++(int) increments or decrements the tick count + operator-- \fI(public member function of std::chrono::duration)\fP + operator--(int) + operator+= modifies the time point by the given duration + operator-= \fI(public member function)\fP + operator+ performs add and subtract operations involving a time point + operator- \fI(function template)\fP + \fI(C++11)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::time_point::operator+,operator-.3 b/man/std::chrono::time_point::operator+,operator-.3 deleted file mode 100644 index 29885b079..000000000 --- a/man/std::chrono::time_point::operator+,operator-.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH std::chrono::time_point::operator+,operator- 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - time_point& operator+=( const duration& d ); \fB(1)\fP \fI(since C++11)\fP - time_point& operator-=( const duration& d ); \fB(2)\fP \fI(since C++11)\fP - - Modifies the time point by the given duration. - - 1) Applies the offset d to pt. Effectively, d is added to the internally stored - duration d_ as d_ += d. - 2) Applies the offset d to pt in negative direction. Effectively, d is subtracted - from internally stored duration d_ as d_ -= d. - -.SH Parameters - - d - a time offset to apply - -.SH Return value - - *this. - -.SH Exceptions - - \fI(none)\fP - -.SH See also - - operator+ modifies the time point by the given duration - operator- \fI(function template)\fP diff --git a/man/std::chrono::time_point::operator+=,operator-=.3 b/man/std::chrono::time_point::operator+=,operator-=.3 new file mode 100644 index 000000000..30698ee61 --- /dev/null +++ b/man/std::chrono::time_point::operator+=,operator-=.3 @@ -0,0 +1,42 @@ +.TH std::chrono::time_point::operator+=,operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point::operator+=,operator-= \- std::chrono::time_point::operator+=,operator-= + +.SH Synopsis + time_point& operator+=( const duration& d ); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + time_point& operator-=( const duration& d ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++17) + + Modifies the time point by the given duration. + + 1) Applies the offset d to pt. Effectively, d is added to the internally stored + duration d_ as d_ += d. + 2) Applies the offset d to pt in negative direction. Effectively, d is subtracted + from internally stored duration d_ as d_ -= d. + +.SH Parameters + + d - a time offset to apply + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator+ performs add and subtract operations involving a time point + operator- \fI(function template)\fP + \fI(C++11)\fP + +.SH Category: + * Todo no example diff --git a/man/std::chrono::time_point::time_point.3 b/man/std::chrono::time_point::time_point.3 index 176cc5486..b8ee7a760 100644 --- a/man/std::chrono::time_point::time_point.3 +++ b/man/std::chrono::time_point::time_point.3 @@ -1,28 +1,23 @@ -.TH std::chrono::time_point::time_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::time_point::time_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point::time_point \- std::chrono::time_point::time_point + .SH Synopsis - (since - time_point(); C++11) - (until - C++14) - constexpr time_point(); (since - C++14) - (since - explicit time_point( const duration& d ); C++11) - (until - \fB(1)\fP C++14) - constexpr explicit time_point( const duration& d ); (since - C++14) - \fB(2)\fP (since - template< class Duration2 > C++11) - time_point( const time_point& t ); (until - \fB(3)\fP C++14) - template< class Duration2 > (since - constexpr time_point( const C++14) - time_point& t ); + \fI(since C++11)\fP + time_point(); (constexpr since + C++14) + explicit time_point( const \fI(since C++11)\fP + duration& d ); \fB(1)\fP (constexpr + since C++14) + template< class Duration2 > \fB(2)\fP \fI(since C++11)\fP + time_point( const \fB(3)\fP (constexpr + time_point& since C++14) + t ); Constructs a new time_point from one of several optional data sources. - 1) Default constructor, creates a time_point with a value of Clock's epoch. + 1) Default constructor, creates a time_point representing the Clock's epoch (i.e., + time_since_epoch() is zero). 2) Constructs a time_point at Clock's epoch plus d. 3) Constructs a time_point by converting t to duration. This constructor only participates in overload resolution if Duration2 is implicitly convertible to @@ -35,45 +30,45 @@ .SH Example - + // Run this code #include #include - - using Clock = std::chrono::high_resolution_clock; + + using Clock = std::chrono::steady_clock; using TimePoint = std::chrono::time_point; - + void print_ms(const TimePoint& point) { using Ms = std::chrono::milliseconds; const Clock::duration since_epoch = point.time_since_epoch(); - std::cout << std::chrono::duration_cast(since_epoch).count() << " ms\\n"; + std::cout << std::chrono::duration_cast(since_epoch) << '\\n'; } - + int main() { const TimePoint default_value = TimePoint(); // (1) - print_ms(default_value); // 0 ms - + print_ms(default_value); // 0ms + const Clock::duration duration_4_seconds = std::chrono::seconds(4); const TimePoint time_point_4_seconds(duration_4_seconds); // (2) - // 4 seconds from start of epoch - print_ms(time_point_4_seconds); // 4000 ms - + // 4 seconds from start of epoch + print_ms(time_point_4_seconds); // 4000ms + const TimePoint time_point_now = Clock::now(); // (3) - print_ms(time_point_now); // 43098276 ms + print_ms(time_point_now); // 212178842ms } .SH Possible output: - 0 ms - 4000 ms - 43098276 ms + 0ms + 4000ms + 212178842ms .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP duration_cast converts a duration to another, with a different tick interval - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::chrono::time_point::time_since_epoch.3 b/man/std::chrono::time_point::time_since_epoch.3 index 4a88f9a6b..8e0bc6ee2 100644 --- a/man/std::chrono::time_point::time_since_epoch.3 +++ b/man/std::chrono::time_point::time_since_epoch.3 @@ -1,8 +1,10 @@ -.TH std::chrono::time_point::time_since_epoch 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::time_point::time_since_epoch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point::time_since_epoch \- std::chrono::time_point::time_since_epoch + .SH Synopsis - duration time_since_epoch() const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr duration time_since_epoch() const; \fI(since C++14)\fP + duration time_since_epoch() const; \fI(since C++11)\fP + (constexpr since C++14) Returns a duration representing the amount of time between *this and the clock's epoch. @@ -13,42 +15,41 @@ .SH Return value - The amount of time between this time_point and the clock's epoch + The amount of time between this time_point and the clock's epoch. .SH Example - + // Run this code - #include #include #include - + #include + int main() { - std::chrono::time_point p1, p2, p3; - - p2 = std::chrono::system_clock::now(); - p3 = p2 - std::chrono::hours(24); - - std::time_t epoch_time = std::chrono::system_clock::to_time_t(p1); + const auto p0 = std::chrono::time_point{}; + const auto p1 = std::chrono::system_clock::now(); + const auto p2 = p1 - std::chrono::hours(24); + + std::time_t epoch_time = std::chrono::system_clock::to_time_t(p0); std::cout << "epoch: " << std::ctime(&epoch_time); - std::time_t today_time = std::chrono::system_clock::to_time_t(p2); + std::time_t today_time = std::chrono::system_clock::to_time_t(p1); std::cout << "today: " << std::ctime(&today_time); - + std::cout << "hours since epoch: " << std::chrono::duration_cast( - p2.time_since_epoch()).count() + p1.time_since_epoch()).count() << '\\n'; std::cout << "yesterday, hours since epoch: " << std::chrono::duration_cast( - p3.time_since_epoch()).count() + p2.time_since_epoch()).count() << '\\n'; } .SH Possible output: - epoch: Wed Dec 31 19:00:00 1969 - today: Tue Jun 19 12:05:37 2012 - hours since epoch: 372256 - yesterday, hours since epoch: 372232 + epoch: Thu Jan 1 00:00:00 1970 + today: Fri Jun 30 10:44:11 2017 + hours since epoch: 416338 + yesterday, hours since epoch: 416314 diff --git a/man/std::chrono::time_point_cast.3 b/man/std::chrono::time_point_cast.3 index 40f212184..f17d164ee 100644 --- a/man/std::chrono::time_point_cast.3 +++ b/man/std::chrono::time_point_cast.3 @@ -1,65 +1,69 @@ -.TH std::chrono::time_point_cast 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::time_point_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_point_cast \- std::chrono::time_point_cast + .SH Synopsis - template + Defined in header + template< class ToDuration, class Clock, class Duration > - time_point time_point_cast( \fI(since C++11)\fP + std::chrono::time_point \fI(since C++11)\fP \fI(until C++14)\fP - const time_point - &t); - template + time_point_cast( const std::chrono::time_point + &t ); + template< class ToDuration, class Clock, class Duration > - constexpr time_point time_point_cast( \fI(since C++14)\fP + constexpr std::chrono::time_point \fI(since C++14)\fP - const time_point - &t); + time_point_cast( const std::chrono::time_point + &t ); Converts a std::chrono::time_point from one duration to another. + time_point_cast participates in overload resolution only if ToDuration is a + specialization of std::chrono::duration. + .SH Parameters t - time_point to convert from .SH Return value - std::chrono::time_point(std::chrono::duration_cast(t.time_since_epoch())) - -.SH Notes - - time_point_cast will only participate in overload resolution if ToDuration is an - instantiation of duration. + std::chrono::time_point( + std::chrono::duration_cast(t.time_since_epoch())). .SH Example - + // Run this code - #include #include - + #include + using namespace std::chrono_literals; + using Clock = std::chrono::high_resolution_clock; using Ms = std::chrono::milliseconds; using Sec = std::chrono::seconds; - + template using TimePoint = std::chrono::time_point; - + inline void print_ms(const TimePoint& time_point) { std::cout << time_point.time_since_epoch().count() << " ms\\n"; } - + int main() { - TimePoint time_point_sec(Sec(4)); - + TimePoint time_point_sec{4s}; + // implicit cast, no precision loss - TimePoint time_point_ms(time_point_sec); + TimePoint time_point_ms{time_point_sec}; print_ms(time_point_ms); // 4000 ms - - time_point_ms = TimePoint(Ms(5756)); - - // explicit cast, need when precision loss may happens + + time_point_ms = TimePoint{5756ms}; + print_ms(time_point_ms); // 5756 ms + + // explicit cast, need when precision loss may happen // 5756 truncated to 5000 time_point_sec = std::chrono::time_point_cast(time_point_ms); print_ms(time_point_sec); // 5000 ms @@ -68,4 +72,18 @@ .SH Output: 4000 ms + 5756 ms 5000 ms + +.SH See also + + floor(std::chrono::time_point) converts a time_point to another, rounding down + \fI(C++17)\fP \fI(function template)\fP + ceil(std::chrono::time_point) converts a time_point to another, rounding up + \fI(C++17)\fP \fI(function template)\fP + round(std::chrono::time_point) converts a time_point to another, rounding to + \fI(C++17)\fP nearest, ties to even + \fI(function template)\fP + duration_cast converts a duration to another, with a different tick + \fI(C++11)\fP interval + \fI(function template)\fP diff --git a/man/std::chrono::time_zone.3 b/man/std::chrono::time_zone.3 new file mode 100644 index 000000000..9b9c3bd08 --- /dev/null +++ b/man/std::chrono::time_zone.3 @@ -0,0 +1,36 @@ +.TH std::chrono::time_zone 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone \- std::chrono::time_zone + +.SH Synopsis + Defined in header + class time_zone; \fI(since C++20)\fP + + The class time_zone represents all time zone transitions for a specific geographic + area. + + Users cannot construct time_zone objects. The library implementation creates + time_zone objects when it initializes the time zone database and provides const + access to these objects. + + time_zone is not copyable but does have a defaulted move constructor and a defaulted + move assignment operator. However, as users have only const access to time_zone + objects, these functions cannot be called in user code without invoking undefined + behavior. + +.SH Member functions + + name obtains the name of this time_zone + \fI(public member function)\fP + get_info obtain information associated with a sys_time or local_time + \fI(public member function)\fP + to_sys converts a local_time in this time zone to a sys_time + \fI(public member function)\fP + to_local converts a sys_time to a local_time in this time zone + \fI(public member function)\fP + + Nonmember functions + + operator== compares two time_zone objects + operator<=> \fI(function)\fP + (C++20) diff --git a/man/std::chrono::time_zone::get_info.3 b/man/std::chrono::time_zone::get_info.3 new file mode 100644 index 000000000..2916bcbe3 --- /dev/null +++ b/man/std::chrono::time_zone::get_info.3 @@ -0,0 +1,21 @@ +.TH std::chrono::time_zone::get_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone::get_info \- std::chrono::time_zone::get_info + +.SH Synopsis + template< class Duration > + std::chrono::sys_info get_info( const \fI(since C++20)\fP + std::chrono::sys_time& tp ) const; + template< class Duration > + std::chrono::local_info get_info( const \fI(since C++20)\fP + std::chrono::local_time& tp ) const; + + Obtains information about this time zone at the time point tp. + +.SH Return value + + 1) A std::chrono::sys_info structure i containing the time zone information in + effect for this time zone at the time point tp. tp will be in the range + [i.begin, i.end). + 2) A std::chrono::local_info structure containing information about the local time + tp in this time zone. diff --git a/man/std::chrono::time_zone::name.3 b/man/std::chrono::time_zone::name.3 new file mode 100644 index 000000000..d298ee9d3 --- /dev/null +++ b/man/std::chrono::time_zone::name.3 @@ -0,0 +1,12 @@ +.TH std::chrono::time_zone::name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone::name \- std::chrono::time_zone::name + +.SH Synopsis + std::string_view name() const noexcept; \fI(since C++20)\fP + + Obtains the name of this time zone. + +.SH Return value + + The name of this time zone (e.g., "America/New_York"). diff --git a/man/std::chrono::time_zone::to_local.3 b/man/std::chrono::time_zone::to_local.3 new file mode 100644 index 000000000..924bfde98 --- /dev/null +++ b/man/std::chrono::time_zone::to_local.3 @@ -0,0 +1,22 @@ +.TH std::chrono::time_zone::to_local 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone::to_local \- std::chrono::time_zone::to_local + +.SH Synopsis + template< class Duration > + + auto to_local( const std::chrono::sys_time& tp ) const (since + C++20) + -> std::chrono::local_time>; + + Converts the sys_time tp to the corresponding local_time in this time zone. + +.SH Return value + + The local_time associated with tp and this time zone. + +.SH Notes + + The precision of the result is at least std::chrono::seconds, and will be finer if + the argument has finer precision. diff --git a/man/std::chrono::time_zone::to_sys.3 b/man/std::chrono::time_zone::to_sys.3 new file mode 100644 index 000000000..35935143e --- /dev/null +++ b/man/std::chrono::time_zone::to_sys.3 @@ -0,0 +1,57 @@ +.TH std::chrono::time_zone::to_sys 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone::to_sys \- std::chrono::time_zone::to_sys + +.SH Synopsis + template< class Duration > + + auto to_sys( const std::chrono::local_time& tp ) const \fB(1)\fP (since + C++20) + -> std::chrono::sys_time>; + template< class Duration > + + auto to_sys( const std::chrono::local_time& tp, (since + std::chrono::choose z ) const \fB(2)\fP C++20) + + -> std::chrono::sys_time>; + + Converts the local_time tp in this time zone to the corresponding sys_time. + + 1) Throws an exception if the conversion is ambiguous or if tp represents a + nonexistent time. + 2) Resolves ambiguity according to the value of z: + * If z == std::chrono::choose::earliest, returns the earlier sys_time. + * If z == std::chrono::choose::latest, returns the later sys_time. + If tp represents a nonexistent time between two UTC time_points, those two + time_points will be the same, and that time_point will be returned. + +.SH Return value + + The UTC equivalent of tp according to the rules of this time zone. + +.SH Exceptions + + 1) Throws: + * std::chrono::ambiguous_local_time if the conversion is ambiguous, + * std::chrono::nonexistent_local_time if tp represents a nonexistent time. + +.SH Notes + + The precision of the result is at least std::chrono::seconds, and will be finer if + the argument has finer precision. + + Ambiguous and nonexistent local times can occur as a result of time zone transitions + (such as daylight saving time). For example, "2016-03-13 02:30:00" does not exist in + the "America/New_York" time zone, while "2016-11-06 01:30:00" in that time zone can + correspond to two UTC time points: 2016-11-06 05:30:00 UTC and 2016-11-06 06:30:00 + UTC. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::chrono::time_zone_link.3 b/man/std::chrono::time_zone_link.3 new file mode 100644 index 000000000..20e37491a --- /dev/null +++ b/man/std::chrono::time_zone_link.3 @@ -0,0 +1,29 @@ +.TH std::chrono::time_zone_link 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone_link \- std::chrono::time_zone_link + +.SH Synopsis + Defined in header + class time_zone_link; \fI(since C++20)\fP + + The class time_zone_link represents an alternative name for a time zone. + + Users cannot construct time_zone_link objects. The library implementation creates + time_zone_link objects when it initializes the time zone database and provides const + access to these objects. + + time_zone_link is not copyable but does have a defaulted move constructor and a + defaulted move assignment operator. However, as users have only const access to + time_zone_link objects, these functions cannot be called in user code without + invoking undefined behavior. + +.SH Member functions + + name accesses the name and target of this time_zone_link + target \fI(public member function)\fP + + Nonmember functions + + operator== compares two time_zone_link objects + operator<=> \fI(function)\fP + (C++20) diff --git a/man/std::chrono::time_zone_link::name,std::chrono::time_zone_link::target.3 b/man/std::chrono::time_zone_link::name,std::chrono::time_zone_link::target.3 new file mode 100644 index 000000000..dd2052d20 --- /dev/null +++ b/man/std::chrono::time_zone_link::name,std::chrono::time_zone_link::target.3 @@ -0,0 +1,15 @@ +.TH std::chrono::time_zone_link::name,std::chrono::time_zone_link::target 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::time_zone_link::name,std::chrono::time_zone_link::target \- std::chrono::time_zone_link::name,std::chrono::time_zone_link::target + +.SH Synopsis + std::string_view name() const noexcept; \fB(1)\fP + std::string_view target() const noexcept; \fB(2)\fP + + Accesses the name and target of this time_zone_link object. + +.SH Return value + + 1) The alternative name this time_zone_link object represents. + 2) The name of the std::chrono::time_zone for which this time_zone_link object + provides an alternative name. diff --git a/man/std::chrono::treat_as_floating_point.3 b/man/std::chrono::treat_as_floating_point.3 index daee98bba..cd052e80e 100644 --- a/man/std::chrono::treat_as_floating_point.3 +++ b/man/std::chrono::treat_as_floating_point.3 @@ -1,7 +1,10 @@ -.TH std::chrono::treat_as_floating_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::chrono::treat_as_floating_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::treat_as_floating_point \- std::chrono::treat_as_floating_point + .SH Synopsis Defined in header - template \fI(since C++11)\fP + template< class Rep > \fI(since C++11)\fP struct treat_as_floating_point : std::is_floating_point {}; The std::chrono::treat_as_floating_point trait helps determine if a duration can be @@ -11,50 +14,54 @@ the durations. However, implicit conversions can happen regardless of tick period if std::chrono::treat_as_floating_point::value == true. +.SH Specializations + + std::chrono::treat_as_floating_point may be specialized for program-defined types. + .SH Example - + // Run this code - #include #include + #include #include - + void timed_piece_of_code() { std::chrono::milliseconds simulated_work(2); std::this_thread::sleep_for(simulated_work); } - + int main() { auto start = std::chrono::high_resolution_clock::now(); - - std::cout << "Running some timed piece of code..." << '\\n'; + + std::cout << "Running some timed piece of code...\\n"; timed_piece_of_code(); - + auto stop = std::chrono::high_resolution_clock::now(); - + // A floating point milliseconds type using FpMilliseconds = std::chrono::duration; - + static_assert(std::chrono::treat_as_floating_point::value, "Rep required to be floating point"); - + // Note that implicit conversion is not allowed here auto i_ms = std::chrono::duration_cast(stop - start); - + // Note that implicit conversion is allowed here auto f_ms = FpMilliseconds(stop - start); - - std::cout << "Time in milliseconds, using default rep: " + + std::cout << "Timing stats:\\n"; + + std::cout << " Time in milliseconds, using default rep: " << i_ms.count() << '\\n'; - - - std::cout << "Time in milliseconds, using floating point rep: " + + std::cout << " Time in milliseconds, using floating point rep: " << f_ms.count() << '\\n'; - } .SH Possible output: @@ -63,3 +70,5 @@ Timing stats: Time in milliseconds, using default rep: 2 Time in milliseconds, using floating point rep: 2.57307 + +.SH See also diff --git a/man/std::chrono::tzdb.3 b/man/std::chrono::tzdb.3 new file mode 100644 index 000000000..57d356783 --- /dev/null +++ b/man/std::chrono::tzdb.3 @@ -0,0 +1,29 @@ +.TH std::chrono::tzdb 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb \- std::chrono::tzdb + +.SH Synopsis + Defined in header + struct tzdb; \fI(since C++20)\fP + + The class tzdb represents a copy of the IANA time zone database. Users cannot + construct a tzdb and can only obtain read-only access to one via the free functions + std::chrono::get_tzdb_list and std::chrono::get_tzdb. + +.SH Member objects + + Member object Description + version A std::string that contains the version of the database + zones A sorted std::vector containing description of + time zones + links A sorted std::vector containing + description of alternative names of time zones (links) + leap_seconds A sorted std::vector containing description + of leap seconds + +.SH Member functions + + locate_zone locate a time zone with the given name + \fI(public member function)\fP + current_zone return the local time zone + \fI(public member function)\fP diff --git a/man/std::chrono::tzdb::current_zone.3 b/man/std::chrono::tzdb::current_zone.3 new file mode 100644 index 000000000..3b4097ecb --- /dev/null +++ b/man/std::chrono::tzdb::current_zone.3 @@ -0,0 +1,14 @@ +.TH std::chrono::tzdb::current_zone 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb::current_zone \- std::chrono::tzdb::current_zone + +.SH Synopsis + const std::chrono::time_zone* current_zone() const; \fI(since C++20)\fP + + Obtains a pointer to a std::chrono::time_zone in this database that represents the + local time zone of the computer. + +.SH Return value + + A pointer to the std::chrono::time_zone in this database that represents the local + time zone of the computer. diff --git a/man/std::chrono::tzdb::locate_zone.3 b/man/std::chrono::tzdb::locate_zone.3 new file mode 100644 index 000000000..823d7774a --- /dev/null +++ b/man/std::chrono::tzdb::locate_zone.3 @@ -0,0 +1,29 @@ +.TH std::chrono::tzdb::locate_zone 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb::locate_zone \- std::chrono::tzdb::locate_zone + +.SH Synopsis + const std::chrono::time_zone* locate_zone( std::string_view tz_name ) \fI(since C++20)\fP + const; + + Obtains a pointer to a std::chrono::time_zone in this database that represents the + time zone designated by tz_name. If p is the returned pointer, then either p->name() + == tz_name or that there is a std::chrono::time_zone_link l in this database such + that p->name() == l.target() && l.name() == tz_name. + +.SH Return value + + A pointer to the std::chrono::time_zone in this database that represents the time + zone designated by tz_name. + +.SH Exceptions + + Throws std::runtime_error if no such time_zone can be found. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::chrono::tzdb_list.3 b/man/std::chrono::tzdb_list.3 new file mode 100644 index 000000000..0e99e48eb --- /dev/null +++ b/man/std::chrono::tzdb_list.3 @@ -0,0 +1,31 @@ +.TH std::chrono::tzdb_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb_list \- std::chrono::tzdb_list + +.SH Synopsis + Defined in header + class tzdb_list; \fI(since C++20)\fP + + tzdb_list is a singleton list of std::chrono::tzdbs, each of which represents a copy + of the IANA time zone database. Users cannot construct a tzdb_list and can only + obtain access to one via the std::chrono::get_tzdb_list free function. + +.SH Member types + + Member type Definition + const_iterator constant LegacyForwardIterator whose value type is std::chrono::tzdb + +.SH Member functions + + constructor copy constructor is defined as deleted + (deleted) \fI(public member function)\fP + operator= copy assignment operator is defined as deleted + (deleted) \fI(public member function)\fP + front access the first element + \fI(public member function)\fP + erase_after erases an element after an element + \fI(public member function)\fP + begin returns an iterator to the beginning of the list + cbegin \fI(public member function)\fP + end returns an iterator past the end of the list + cend \fI(public member function)\fP diff --git a/man/std::chrono::tzdb_list::begin.3 b/man/std::chrono::tzdb_list::begin.3 new file mode 100644 index 000000000..6b3e770d8 --- /dev/null +++ b/man/std::chrono::tzdb_list::begin.3 @@ -0,0 +1,13 @@ +.TH std::chrono::tzdb_list::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb_list::begin \- std::chrono::tzdb_list::begin + +.SH Synopsis + const_iterator begin() const noexcept; \fI(since C++20)\fP + const_iterator cbegin() const noexcept; \fI(since C++20)\fP + + Returns an iterator referring to the first std::chrono::tzdb in the container. + +.SH Return value + + An iterator referring to the first std::chrono::tzdb in the container. diff --git a/man/std::chrono::tzdb_list::end,std::chrono::tzdb_list::cend.3 b/man/std::chrono::tzdb_list::end,std::chrono::tzdb_list::cend.3 new file mode 100644 index 000000000..335a63ea7 --- /dev/null +++ b/man/std::chrono::tzdb_list::end,std::chrono::tzdb_list::cend.3 @@ -0,0 +1,14 @@ +.TH std::chrono::tzdb_list::end,std::chrono::tzdb_list::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb_list::end,std::chrono::tzdb_list::cend \- std::chrono::tzdb_list::end,std::chrono::tzdb_list::cend + +.SH Synopsis + const_iterator end() const noexcept; \fI(since C++20)\fP + const_iterator cend() const noexcept; \fI(since C++20)\fP + + Returns the past-the-end iterator of the tzdb_list. Attempting to dereference this + iterator results in undefined behavior. + +.SH Return value + + The past-the-end iterator. diff --git a/man/std::chrono::tzdb_list::erase_after.3 b/man/std::chrono::tzdb_list::erase_after.3 new file mode 100644 index 000000000..bbcd4e2f4 --- /dev/null +++ b/man/std::chrono::tzdb_list::erase_after.3 @@ -0,0 +1,21 @@ +.TH std::chrono::tzdb_list::erase_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb_list::erase_after \- std::chrono::tzdb_list::erase_after + +.SH Synopsis + const_iterator erase_after( const_iterator p ); \fI(since C++20)\fP + + Erases the std::chrono::tzdb referred to by the iterator following p. The behavior + is undefined if that iterator is not dereferenceable. No pointers, references, or + iterators are invalidated except for those referring to the erased element. + +.SH Return value + + An iterator pointing to the element following the erased element, or end() if no + such element exists. + +.SH Notes + + tzdb_list is intended to be implementable as a singly linked list, and its interface + resembles that of std::forward_list. It has no before_begin(), however, and so it is + not possible to erase the first element. diff --git a/man/std::chrono::tzdb_list::front.3 b/man/std::chrono::tzdb_list::front.3 new file mode 100644 index 000000000..3857cb834 --- /dev/null +++ b/man/std::chrono::tzdb_list::front.3 @@ -0,0 +1,13 @@ +.TH std::chrono::tzdb_list::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::tzdb_list::front \- std::chrono::tzdb_list::front + +.SH Synopsis + const std::chrono::tzdb& front() const noexcept; \fI(since C++20)\fP + + Obtains a reference to the first std::chrono::tzdb in the list. Simultaneous calls + to this function and std::chrono::reload_tzdb() does not introduce a data race. + +.SH Return value + + A reference to the first std::chrono::tzdb in the list. diff --git a/man/std::chrono::utc_clock.3 b/man/std::chrono::utc_clock.3 new file mode 100644 index 000000000..c19a8d742 --- /dev/null +++ b/man/std::chrono::utc_clock.3 @@ -0,0 +1,58 @@ +.TH std::chrono::utc_clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::utc_clock \- std::chrono::utc_clock + +.SH Synopsis + Defined in header + class utc_clock; \fI(since C++20)\fP + + The clock std::chrono::utc_clock is a Clock that represents Coordinated Universal + Time (UTC). It measures time since 00:00:00 UTC, Thursday, 1 January 1970, including + leap seconds. + + utc_clock meets the Clock requirements. It does not meet the TrivialClock + requirements unless the implementation can guarantee that now() does not throw an + exception. + +.SH Member types + + Member type Definition + rep signed arithmetic type representing the number of ticks in the clock's + duration + period a std::ratio type representing the tick period of the clock, in seconds + duration std::chrono::duration, capable of representing negative + durations + time_point std::chrono::time_point + +.SH Member constants + + true if the time between ticks is always constant, i.e. + constexpr bool is_steady calls to now() return values that increase monotonically + \fB[static]\fP even in case of some external clock adjustment, otherwise + false + \fI(public static member constant)\fP + +.SH Member functions + + now returns a std::chrono::time_point representing the current point in time + \fB[static]\fP \fI(public static member function)\fP + to_sys converts utc_time to sys_time + \fB[static]\fP \fI(public static member function)\fP + from_sys converts sys_time to utc_time + \fB[static]\fP \fI(public static member function)\fP + +.SH Non-member functions + + get_leap_second_info obtains leap second insertion information from a utc_time + (C++20) object + \fI(function template)\fP + +.SH Helper classes + + leap_second_info leap second insertion information + (C++20) \fI(class)\fP + +.SH Notes + + The official UTC epoch is 1 January 1972. utc_clock uses 1 January 1970 instead to + be consistent with std::chrono::system_clock. diff --git a/man/std::chrono::utc_clock::from_sys.3 b/man/std::chrono::utc_clock::from_sys.3 new file mode 100644 index 000000000..6ffd738e4 --- /dev/null +++ b/man/std::chrono::utc_clock::from_sys.3 @@ -0,0 +1,28 @@ +.TH std::chrono::utc_clock::from_sys 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::utc_clock::from_sys \- std::chrono::utc_clock::from_sys + +.SH Synopsis + template< class Duration > + + static std::chrono::utc_time> + + from_sys( const std::chrono::sys_time& t ); + + Converts a sys_time t to a utc_time u that represents the same point in time. + + u.time_since_epoch() - t.time_since_epoch() is equal to the number of leap seconds + that was inserted between t and 1 January 1970. If t is the exact date of a leap + second insertion, that leap second is counted as inserted. + +.SH Return value + + A utc_time representing the same point in time as t. + +.SH See also + + to_sys converts utc_time to sys_time + \fB[static]\fP \fI(public static member function)\fP + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::utc_clock::now.3 b/man/std::chrono::utc_clock::now.3 new file mode 100644 index 000000000..8d0543b1b --- /dev/null +++ b/man/std::chrono::utc_clock::now.3 @@ -0,0 +1,63 @@ +.TH std::chrono::utc_clock::now 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::utc_clock::now \- std::chrono::utc_clock::now + +.SH Synopsis + static std::chrono::time_point now(); \fI(since C++20)\fP + + Returns a time point representing the current point in time. The result is + calculated as if by + std::chrono::utc_clock::from_sys(std::chrono::system_clock::now()). Implementations + may use a more accurate value of UTC time. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A time point representing the current time. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + volatile int sink; + + void do_some_work(std::size_t size) + { + std::vector v(size, 42); + sink = std::accumulate(v.begin(), v.end(), 0); // make sure it is a side effect + } + + int main() + { + std::cout << std::fixed << std::setprecision(9) << std::left; + for (auto size{1ull}; size < 10'00'00'00'00ull; size *= 100) + { + const auto start = std::chrono::utc_clock::now(); + do_some_work(size); + const auto end = std::chrono::utc_clock::now(); + + const std::chrono::duration diff = end - start; + + std::cout << "Time to fill and iterate a vector of " << std::setw(9) + << size << " ints : " << diff << '\\n'; + } + } + +.SH Possible output: + + Time to fill and iterate a vector of 1 ints : 0.000006568s + Time to fill and iterate a vector of 100 ints : 0.000002854s + Time to fill and iterate a vector of 10000 ints : 0.000116290s + Time to fill and iterate a vector of 1000000 ints : 0.011742752s + Time to fill and iterate a vector of 100000000 ints : 0.505534949s diff --git a/man/std::chrono::utc_clock::to_sys.3 b/man/std::chrono::utc_clock::to_sys.3 new file mode 100644 index 000000000..f6feab833 --- /dev/null +++ b/man/std::chrono::utc_clock::to_sys.3 @@ -0,0 +1,31 @@ +.TH std::chrono::utc_clock::to_sys 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::utc_clock::to_sys \- std::chrono::utc_clock::to_sys + +.SH Synopsis + template< class Duration > + + static std::chrono::sys_time> + + to_sys( const std::chrono::utc_time& t ); + + Converts a utc_time t to a sys_time representing the same point in time (if + possible). + + If t represents a time point during a leap second insertion, the last representable + value of sys_time prior to the insertion of the leap second is returned. In all + other cases, utc_clock::from_sys(utc_clock::to_sys(t)) == t. + +.SH Return value + + A sys_time representing the same point in time as t, or the last representable value + prior to the insertion of the leap second if t represents a time point during a leap + second insertion. + +.SH See also + + from_sys converts sys_time to utc_time + \fB[static]\fP \fI(public static member function)\fP + clock_cast convert time points of one clock to another + (C++20) \fI(function template)\fP diff --git a/man/std::chrono::weekday.3 b/man/std::chrono::weekday.3 new file mode 100644 index 000000000..c3e08f3d2 --- /dev/null +++ b/man/std::chrono::weekday.3 @@ -0,0 +1,86 @@ +.TH std::chrono::weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday \- std::chrono::weekday + +.SH Synopsis + Defined in header + class weekday; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Sunday{0}; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Monday{1}; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Tuesday{2}; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Wednesday{3}; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Thursday{4}; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Friday{5}; \fI(since C++20)\fP + inline constexpr std::chrono::weekday Saturday{6}; \fI(since C++20)\fP + + The class weekday represent a day of the week in the proleptic Gregorian calendar. + Its normal range is [0, 6], for Sunday through Saturday, but it can hold any value + in the range [0, 255]. Seven named constants are predefined in the std::chrono + namespace for the seven days of the week. + + weekday is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a weekday + \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the weekday + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of days + operator-= \fI(public member function)\fP + c_encoding retrieves the stored weekday value + iso_encoding retrieves ISO 8601 weekday value + \fI(public member function)\fP + ok checks if the stored weekday value is valid + \fI(public member function)\fP + convenience syntax for constructing a weekday_indexed or + operator[] weekday_last from this weekday + \fI(public member function)\fP + + Nonmember functions + + operator== compares two weekday values + (C++20) \fI(function)\fP + operator+ performs arithmetic on weekdays + operator- \fI(function)\fP + (C++20) + operator<< outputs a weekday into a stream + (C++20) \fI(function template)\fP + from_stream parses a weekday from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for weekday + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::weekday + (C++26) \fI(class template specialization)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::chrono::weekday x{42 / 13}; + std::cout << x++ << '\\n'; + std::cout << x << '\\n'; + std::cout << ++x << '\\n'; + } + +.SH Output: + + Wed + Thu + Fri + +.SH See also + + weekday_indexed represents the n^th weekday of a month + (C++20) \fI(class)\fP diff --git a/man/std::chrono::weekday::c_encoding,std::chrono::weekday::iso_encoding.3 b/man/std::chrono::weekday::c_encoding,std::chrono::weekday::iso_encoding.3 new file mode 100644 index 000000000..66538cb6e --- /dev/null +++ b/man/std::chrono::weekday::c_encoding,std::chrono::weekday::iso_encoding.3 @@ -0,0 +1,50 @@ +.TH std::chrono::weekday::c_encoding,std::chrono::weekday::iso_encoding 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday::c_encoding,std::chrono::weekday::iso_encoding \- std::chrono::weekday::c_encoding,std::chrono::weekday::iso_encoding + +.SH Synopsis + constexpr unsigned c_encoding() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr unsigned iso_encoding() const noexcept; \fB(2)\fP \fI(since C++20)\fP + + 1) Returns the weekday value stored in *this. + 2) Returns the weekday value stored in *this, except that Sunday (stored as 0) is + interpreted as 7 according to ISO 8601. + +.SH Return value + + 1) The weekday value stored in *this. + 2) c_encoding() == 0u ? 7u : c_encoding() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "i: C: ISO: Weekday:\\n"; + + for (unsigned i{0}; i != 8; ++i) + { + const std::chrono::weekday w{i}; + std::cout << i << " " + << w.c_encoding() << " " + << w.iso_encoding() << " " + << w << '\\n'; + } + } + +.SH Output: + + i: C: ISO: Weekday: + 0 0 7 Sun + 1 1 1 Mon + 2 2 2 Tue + 3 3 3 Wed + 4 4 4 Thu + 5 5 5 Fri + 6 6 6 Sat + 7 0 7 Sun diff --git a/man/std::chrono::weekday::ok.3 b/man/std::chrono::weekday::ok.3 new file mode 100644 index 000000000..f3fc22526 --- /dev/null +++ b/man/std::chrono::weekday::ok.3 @@ -0,0 +1,56 @@ +.TH std::chrono::weekday::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday::ok \- std::chrono::weekday::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the weekday value stored in *this is in the valid range, i.e., [0, 6]. + +.SH Return value + + true if the weekday value stored in *this is in the range [0, 6]. Otherwise false. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct weekday_ok : std::numpunct + { + std::string do_truename() const override { return " (is valid weekday)"; } + std::string do_falsename() const override { return " (is not valid weekday)"; } + }; + + int main() + { + std::cout.imbue(std::locale(std::cout.getloc(), new weekday_ok)); + std::cout << std::boolalpha; + + for (const unsigned u : {0 /* Sun */, 1 /* Mon */, 6, 7 /* Sun */, 8, 9}) + { + const std::chrono::weekday wd{u}; + std::cout << "u: " << u << "; wd: " << wd.c_encoding() << wd.ok() << '\\n'; + } + } + +.SH Output: + + u: 0; wd: 0 (is valid weekday) + u: 1; wd: 1 (is valid weekday) + u: 6; wd: 6 (is valid weekday) + u: 7; wd: 0 (is valid weekday) + u: 8; wd: 8 (is not valid weekday) + u: 9; wd: 9 (is not valid weekday) + +.SH See also + + c_encoding retrieves the stored weekday value + iso_encoding retrieves ISO 8601 weekday value + \fI(public member function)\fP diff --git a/man/std::chrono::weekday::operator++,std::chrono::weekday::operator--.3 b/man/std::chrono::weekday::operator++,std::chrono::weekday::operator--.3 new file mode 100644 index 000000000..b05851fd8 --- /dev/null +++ b/man/std::chrono::weekday::operator++,std::chrono::weekday::operator--.3 @@ -0,0 +1,67 @@ +.TH std::chrono::weekday::operator++,std::chrono::weekday::operator-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday::operator++,std::chrono::weekday::operator-- \- std::chrono::weekday::operator++,std::chrono::weekday::operator-- + +.SH Synopsis + constexpr std::chrono::weekday& operator++() noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday operator++( int ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday& operator--() noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday operator--( int ) noexcept; \fB(4)\fP \fI(since C++20)\fP + + Adds or subtracts 1 from the weekday value, reducing the result modulo 7 to an + integer in the range [0, 6]. + + 1,2) Performs *this += std::chrono::days{1};. + 3,4) Performs *this -= std::chrono::days{1};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) A reference to this weekday after modification. + 2,4) A copy of the weekday made before modification. + +.SH Notes + + After a call to one of these functions, ok() is always true. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::weekday wd{0}; // Sunday is 0 or 7 + + --wd; + std::cout << (wd == std::chrono::Saturday) << ' '; + + ++wd; + std::cout << (wd == std::chrono::Sunday) << '\\n'; + + wd = std::chrono::weekday{13}; + assert(!wd.ok()); + wd++; + assert(wd.ok()); + } + +.SH Output: + + true true + +.SH See also + + operator+= adds or subtracts a number of days + operator-= \fI(public member function)\fP + operator+ performs arithmetic on weekdays + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::weekday::operator+=,std::chrono::weekday::operator-=.3 b/man/std::chrono::weekday::operator+=,std::chrono::weekday::operator-=.3 new file mode 100644 index 000000000..a17efa0f0 --- /dev/null +++ b/man/std::chrono::weekday::operator+=,std::chrono::weekday::operator-=.3 @@ -0,0 +1,68 @@ +.TH std::chrono::weekday::operator+=,std::chrono::weekday::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday::operator+=,std::chrono::weekday::operator-= \- std::chrono::weekday::operator+=,std::chrono::weekday::operator-= + +.SH Synopsis + constexpr std::chrono::weekday& operator+=( const \fB(1)\fP \fI(since C++20)\fP + std::chrono::days& d ) noexcept; + constexpr std::chrono::weekday& operator-=( const \fB(2)\fP \fI(since C++20)\fP + std::chrono::days& d ) noexcept; + + Adds or subtracts d.count() from the weekday value, reducing the result modulo 7 to + an integer in the range [0, 6]. + + 1) Performs *this = *this + d;. + 2) Performs *this = *this - d;. + +.SH Return value + + A reference to this weekday after modification. + +.SH Notes + + After a call to one of these functions, ok() is always true if no overflow occurred + during the operation. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::weekday wd{5}; // Friday is 5 + wd += std::chrono::days(2); + std::cout << (wd == std::chrono::weekday(0)) << ' ' + << (wd == std::chrono::Sunday) << ' '; + + wd -= std::chrono::days(3); + std::cout << (wd == std::chrono::weekday(4)) << ' ' + << (wd == std::chrono::Thursday) << ' '; + + wd = std::chrono::Wednesday; + wd += std::chrono::days{8}; // ((3 += 8 == 11) % 7) == 4; + std::cout << (wd == std::chrono::Thursday) << ' '; + + wd -= (std::chrono::Sunday - std::chrono::Tuesday); // -= -2 + // (4 -= -2) == 6 + std::cout << (wd == std::chrono::Saturday) << '\\n'; + } + +.SH Output: + + true true true true true true + +.SH See also + + operator++ + operator++(int) increments or decrements the weekday + operator-- \fI(public member function)\fP + operator--(int) + operator+ performs arithmetic on weekdays + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::weekday::operator[].3 b/man/std::chrono::weekday::operator[].3 new file mode 100644 index 000000000..094c86885 --- /dev/null +++ b/man/std::chrono::weekday::operator[].3 @@ -0,0 +1,47 @@ +.TH std::chrono::weekday::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday::operator[] \- std::chrono::weekday::operator[] + +.SH Synopsis + constexpr std::chrono::weekday_indexed \fB(1)\fP \fI(since C++20)\fP + operator[]( unsigned index ) const noexcept; + constexpr std::chrono::weekday_last \fB(2)\fP \fI(since C++20)\fP + operator[]( std::chrono::last_spec ) const noexcept; + + 1) Constructs a weekday_indexed from *this and index. The result represents the + index-th weekday in some yet-to-be-specified month. If index is not in the range + [0, 7] or if !ok() the values (an underlying weekday and an index) held in the + result are unspecified. + 2) Constructs a weekday_last from *this. The result represents the last weekday in + some yet-to-be-specified month. + +.SH Return value + + 1) std::chrono::weekday_indexed(*this, index) + 2) std::chrono::weekday_last(*this) + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto second_tuesday_in_October_2019 = + year_month_day{Tuesday[2] / October / 2019y}; + + constexpr auto last_tuesday_in_October_2019 = + year_month_day{Tuesday[last] / October / 2019y}; + + std::cout << second_tuesday_in_October_2019 << '\\n' + << last_tuesday_in_October_2019 << '\\n'; + } + +.SH Possible output: + + 2019-10-08 + 2019-10-29 diff --git a/man/std::chrono::weekday::weekday.3 b/man/std::chrono::weekday::weekday.3 new file mode 100644 index 000000000..c632c3dd3 --- /dev/null +++ b/man/std::chrono::weekday::weekday.3 @@ -0,0 +1,63 @@ +.TH std::chrono::weekday::weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday::weekday \- std::chrono::weekday::weekday + +.SH Synopsis + weekday() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit weekday( unsigned wd ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr weekday( const std::chrono::sys_days& sd ) noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr explicit weekday( const std::chrono::local_days& ld ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + + Constructs a weekday object. + + 1) Default constructor leaves the weekday value uninitialized. + 2) Constructs a weekday object holding the weekday value wd. If wd == 7, the value + held is 0. If wd > 255, the value held is unspecified. + 3) Constructs a weekday object representing the day of the week sd corresponds to. + This constructor defines an implicit conversion from std::chrono::sys_days to + weekday. + 4) Constructs a weekday object representing the day of the week ld corresponds to, + as if by weekday(std::chrono::sys_days(ld.time_since_epoch())). + +.SH Parameters + + wd - a weekday value + sd - a system days object + ld - a local days object + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::chrono::weekday friday{5}; // uses overload (2) + static_assert(friday == std::chrono::Friday); + + for (int y{2020}; y <= 2023; ++y) + { + const std::chrono::year cur_year{y}; + for (int cur_month{1}; cur_month != 13; ++cur_month) + { + const std::chrono::year_month_day ymd{cur_year/cur_month/13}; + const std::chrono::weekday cur_weekday{std::chrono::sys_days(ymd)}; // (3) + if (cur_weekday == friday) + std::cout << ymd << " is " << friday << '\\n'; + } + } + } + +.SH Output: + + 2020-03-13 is Fri + 2020-11-13 is Fri + 2021-08-13 is Fri + 2022-05-13 is Fri + 2023-01-13 is Fri + 2023-10-13 is Fri diff --git a/man/std::chrono::weekday_indexed.3 b/man/std::chrono::weekday_indexed.3 new file mode 100644 index 000000000..acd95537e --- /dev/null +++ b/man/std::chrono::weekday_indexed.3 @@ -0,0 +1,69 @@ +.TH std::chrono::weekday_indexed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_indexed \- std::chrono::weekday_indexed + +.SH Synopsis + Defined in header + class weekday_indexed; \fI(since C++20)\fP + + The class weekday_indexed combines a weekday, representing a day of the week in the + proleptic Gregorian calendar, with a small index n in the range [1, 5]. It + represents the first, second, third, fourth, or fifth weekday of some month. + + weekday_indexed is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a weekday_indexed + \fI(public member function)\fP + weekday access the stored weekday + \fI(public member function)\fP + index access the stored index + \fI(public member function)\fP + ok checks if the weekday and index are both valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two weekday_indexed values + (C++20) \fI(function)\fP + operator<< outputs a weekday_indexed into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for weekday_indexed + (C++20) \fI(class template specialization)\fP + std::hash hash support for + (C++26) std::chrono::weekday_indexed + \fI(class template specialization)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + + constexpr weekday_indexed wi = Friday[2]; + + // Indexed weekday can be used at any place where chrono::day can be used: + constexpr year_month_weekday ymwd = 2021y / August / wi; + static_assert(ymwd == August / wi / 2021y && + ymwd == wi / August / 2021y); + std::cout << ymwd << '\\n'; + + constexpr year_month_day ymd{ymwd}; // a conversion + static_assert(ymd == 2021y / 8 / 13); + std::cout << ymd << '\\n'; + } + +.SH Possible output: + + 2021/Aug/Fri[2] + 2021-08-13 diff --git a/man/std::chrono::weekday_indexed::index.3 b/man/std::chrono::weekday_indexed::index.3 new file mode 100644 index 000000000..2e383864d --- /dev/null +++ b/man/std::chrono::weekday_indexed::index.3 @@ -0,0 +1,37 @@ +.TH std::chrono::weekday_indexed::index 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_indexed::index \- std::chrono::weekday_indexed::index + +.SH Synopsis + constexpr unsigned index() const noexcept; \fI(since C++20)\fP + + Accesses the index stored in *this. + +.SH Return value + + The index stored in *this. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::weekday_indexed wdi {std::chrono::Tuesday[2]}; // 2nd Tuesday of a month + std::cout << (std::chrono::year_month_day{wdi/10/2019} == + std::chrono::year_month_day{std::chrono::October/8/2019}) << ' '; + + wdi = {wdi.weekday()[wdi.index() + 2]}; // 2nd Tuesday => 4th Tuesday + std::cout << (std::chrono::year_month_day{wdi/10/2019} == + std::chrono::year_month_day{std::chrono::October/22/2019}) << '\\n'; + } + +.SH Output: + + true true diff --git a/man/std::chrono::weekday_indexed::ok.3 b/man/std::chrono::weekday_indexed::ok.3 new file mode 100644 index 000000000..db5155d05 --- /dev/null +++ b/man/std::chrono::weekday_indexed::ok.3 @@ -0,0 +1,36 @@ +.TH std::chrono::weekday_indexed::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_indexed::ok \- std::chrono::weekday_indexed::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the weekday object and the index stored in *this are both valid. + +.SH Return value + + true if weekday().ok() == true and index() is in the range [1, 5]. Otherwise false. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::weekday_indexed wdi{std::chrono::Tuesday[2]}; + std::cout << (wdi.ok()) << ' '; + wdi = {std::chrono::weekday(42)[2]}; + std::cout << (wdi.ok()) << ' '; + wdi = {std::chrono::Tuesday[-4]}; + std::cout << (wdi.ok()) << '\\n'; + } + +.SH Output: + + true false false diff --git a/man/std::chrono::weekday_indexed::weekday.3 b/man/std::chrono::weekday_indexed::weekday.3 new file mode 100644 index 000000000..1e13d9523 --- /dev/null +++ b/man/std::chrono::weekday_indexed::weekday.3 @@ -0,0 +1,44 @@ +.TH std::chrono::weekday_indexed::weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_indexed::weekday \- std::chrono::weekday_indexed::weekday + +.SH Synopsis + constexpr std::chrono::weekday weekday() const noexcept; \fI(since C++20)\fP + + Retrieves a copy of the std::chrono::weekday object stored in *this. + +.SH Return value + + A copy of the std::chrono::weekday object stored in *this. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + // 2nd Tuesday of a month + std::chrono::weekday_indexed wdi{std::chrono::Tuesday[2]}; + std::cout << (std::chrono::year_month_day{wdi/10/2019} == + std::chrono::year_month_day{std::chrono::October/8/2019}) << ' '; + + // 2nd Tuesday => 2nd Thursday + wdi = {wdi.weekday() + std::chrono::days(2), wdi.index()}; + std::cout << (std::chrono::year_month_day{wdi/10/2019} == + std::chrono::year_month_day{std::chrono::October/10/2019}) << '\\n'; + } + +.SH Output: + + true true + +.SH See also + + index access the stored index + \fI(public member function)\fP diff --git a/man/std::chrono::weekday_indexed::weekday_indexed.3 b/man/std::chrono::weekday_indexed::weekday_indexed.3 new file mode 100644 index 000000000..e93aa5a5e --- /dev/null +++ b/man/std::chrono::weekday_indexed::weekday_indexed.3 @@ -0,0 +1,48 @@ +.TH std::chrono::weekday_indexed::weekday_indexed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_indexed::weekday_indexed \- std::chrono::weekday_indexed::weekday_indexed + +.SH Synopsis + weekday_indexed() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr weekday_indexed( const std::chrono::weekday& wd, \fB(2)\fP \fI(since C++20)\fP + unsigned index ) noexcept; + + Constructs a weekday_indexed. + + 1) Default constructor leaves both the std::chrono::weekday and the index value + uninitialized. + 2) Constructs a weekday_indexed storing the weekday wd and the index index. The + values held are unspecified if !wd.ok() || index > 7. + +.SH Notes + + A more convenient way to construct a weekday_indexed is with weekday's operator[], + i.e., wd[index]. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto third_friday = weekday_indexed(Friday, 3); // uses constructor (2) + static_assert(third_friday == Friday[3]); + + weekday_indexed wdi = Tuesday[2]; // represents the 2nd Tuesday + std::cout << year_month_day{ wdi / October / 2019y } << '\\n'; + } + +.SH Possible output: + + 2019-10-08 + +.SH See also + + convenience syntax for constructing a weekday_indexed or weekday_last + operator[] from this weekday + \fI(public member function of std::chrono::weekday)\fP diff --git a/man/std::chrono::weekday_last.3 b/man/std::chrono::weekday_last.3 new file mode 100644 index 000000000..89b9307ec --- /dev/null +++ b/man/std::chrono::weekday_last.3 @@ -0,0 +1,34 @@ +.TH std::chrono::weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_last \- std::chrono::weekday_last + +.SH Synopsis + Defined in header + class weekday_last; \fI(since C++20)\fP + + The class weekday_last represents the last weekday of some month. + + weekday_last is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a weekday_last object + \fI(public member function)\fP + weekday accesses the stored weekday + \fI(public member function)\fP + ok checks if the stored weekday is valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two weekday_last values + (C++20) \fI(function)\fP + operator<< outputs a weekday_last into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for weekday_last + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::weekday_last + (C++26) \fI(class template specialization)\fP diff --git a/man/std::chrono::weekday_last::ok.3 b/man/std::chrono::weekday_last::ok.3 new file mode 100644 index 000000000..4609ef68b --- /dev/null +++ b/man/std::chrono::weekday_last::ok.3 @@ -0,0 +1,35 @@ +.TH std::chrono::weekday_last::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_last::ok \- std::chrono::weekday_last::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the weekday object stored in *this is valid. + +.SH Return value + + weekday().ok() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + auto wdl{std::chrono::Tuesday[std::chrono::last]}; + std::cout << (wdl.ok()) << ' '; + + wdl = {std::chrono::weekday(42)[std::chrono::last]}; + std::cout << (wdl.ok()) << '\\n'; + } + +.SH Output: + + true false diff --git a/man/std::chrono::weekday_last::weekday.3 b/man/std::chrono::weekday_last::weekday.3 new file mode 100644 index 000000000..d52e13183 --- /dev/null +++ b/man/std::chrono::weekday_last::weekday.3 @@ -0,0 +1,38 @@ +.TH std::chrono::weekday_last::weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_last::weekday \- std::chrono::weekday_last::weekday + +.SH Synopsis + constexpr std::chrono::weekday weekday() const noexcept; \fI(since C++20)\fP + + Retrieves a copy of the std::chrono::weekday object stored in *this. + +.SH Return value + + A copy of the std::chrono::weekday object stored in *this. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + std::cout << std::boolalpha; + + auto wdl{Tuesday[last]}; // Last Tuesday of a month + std::cout << (year_month_day{wdl/10/2019} == + year_month_day{October/29/2019}) << ' '; + + wdl = {(wdl.weekday() + days(2))[last]}; // Last Tuesday is now last Thursday + std::cout << (year_month_day{wdl/10/2019} == + year_month_day{October/31/2019}) << '\\n'; + } + +.SH Output: + + true true diff --git a/man/std::chrono::weekday_last::weekday_last.3 b/man/std::chrono::weekday_last::weekday_last.3 new file mode 100644 index 000000000..f6f10f2d2 --- /dev/null +++ b/man/std::chrono::weekday_last::weekday_last.3 @@ -0,0 +1,39 @@ +.TH std::chrono::weekday_last::weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::weekday_last::weekday_last \- std::chrono::weekday_last::weekday_last + +.SH Synopsis + constexpr explicit weekday_last( const std::chrono::weekday& wd ) \fI(since C++20)\fP + noexcept; + + Constructs a weekday_last object storing the weekday wd. + +.SH Notes + + A more convenient way to construct a weekday_last is with weekday's operator[], + i.e., wd[std::chrono::last]. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + const year_month_day ymd{floor(system_clock::now())}; + const weekday_last wdl{Sunday[last]}; // A last Sunday of a month + const year_month_day last_sun{ymd.year() / ymd.month() / wdl}; + + std::cout << "The last Sunday of current month falls on " + << (int)last_sun.year() << '/' + << (unsigned)last_sun.month() << '/' + << (unsigned)last_sun.day() << '\\n'; + } + +.SH Possible output: + + The last Sunday of current month falls on 2021/9/26 diff --git a/man/std::chrono::year.3 b/man/std::chrono::year.3 new file mode 100644 index 000000000..efb39e567 --- /dev/null +++ b/man/std::chrono::year.3 @@ -0,0 +1,61 @@ +.TH std::chrono::year 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year \- std::chrono::year + +.SH Synopsis + Defined in header + class year; \fI(since C++20)\fP + + The class year represents a year in the proleptic Gregorian calendar. Its range is + [-32767, 32767]. + + year is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a year + \fI(public member function)\fP + operator++ + operator++(int) increments or decrements the year + operator-- \fI(public member function)\fP + operator--(int) + operator+= adds or subtracts a number of years from a year + operator-= \fI(public member function)\fP + operator+ applies unary operators to year + operator- \fI(public member function)\fP + is_leap determines if the year is a leap year + \fI(public member function)\fP + operator int retrieve the year value + \fI(public member function)\fP + ok checks if the stored year value is valid + \fI(public member function)\fP + min returns the smallest possible year value + \fB[static]\fP \fI(public static member function)\fP + max returns the largest possible year + \fB[static]\fP \fI(public static member function)\fP + +.SH Non-member functions + + operator== compares two year values + operator<=> \fI(function)\fP + (C++20) + operator+ performs arithmetic on years + operator- \fI(function)\fP + (C++20) + operator<< outputs a year into a stream + (C++20) \fI(function template)\fP + from_stream parses a year from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for year + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::year + (C++26) \fI(class template specialization)\fP + +.SH Literals + + Defined in inline namespace std::literals::chrono_literals + operator""y a std::chrono::year literal representing a particular year + (C++20) \fI(function)\fP diff --git a/man/std::chrono::year::is_leap.3 b/man/std::chrono::year::is_leap.3 new file mode 100644 index 000000000..0443bdeb7 --- /dev/null +++ b/man/std::chrono::year::is_leap.3 @@ -0,0 +1,45 @@ +.TH std::chrono::year::is_leap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::is_leap \- std::chrono::year::is_leap + +.SH Synopsis + constexpr bool is_leap() const noexcept; \fI(since C++20)\fP + + Determines if *this represents a leap year in the proleptic Gregorian calendar. + + *this represents a leap year if the stored year value + + * is divisible by 4 and not divisible by 100; or + * is divisible by 400. + +.SH Return value + + true if *this represents a leap year, otherwise false. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono_literals; + for (const std::chrono::year y : {2020y, 2021y, 2000y, 3000y}) + { + if (const int iy{static_cast(y)}; y.is_leap()) + std::cout << iy << " is a leap year because it is divisible by " + << (iy % 400 == 0 ? "400\\n" : "4 and not divisible by 100\\n"); + else + std::cout << iy << " is not a leap year\\n"; + } + } + +.SH Output: + + 2020 is a leap year because it is divisible by 4 and not divisible by 100 + 2021 is not a leap year + 2000 is a leap year because it is divisible by 400 + 3000 is not a leap year diff --git a/man/std::chrono::year::max.3 b/man/std::chrono::year::max.3 new file mode 100644 index 000000000..25f613fc8 --- /dev/null +++ b/man/std::chrono::year::max.3 @@ -0,0 +1,29 @@ +.TH std::chrono::year::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::max \- std::chrono::year::max + +.SH Synopsis + static constexpr year max() noexcept; \fI(since C++20)\fP + + Returns the largest possible year, that is, std::chrono::year(32767). + +.SH Return value + + std::chrono::year(32767) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "The maximum year is: " << (int)std::chrono::year::max() << '\\n'; + } + +.SH Output: + + The maximum year is: 32767 diff --git a/man/std::chrono::year::min.3 b/man/std::chrono::year::min.3 new file mode 100644 index 000000000..ab68140fa --- /dev/null +++ b/man/std::chrono::year::min.3 @@ -0,0 +1,29 @@ +.TH std::chrono::year::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::min \- std::chrono::year::min + +.SH Synopsis + static constexpr std::chrono::year min() noexcept; \fI(since C++20)\fP + + Returns the smallest possible year, that is, std::chrono::year(-32767). + +.SH Return value + + std::chrono::year(-32767) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "The minimum year is: " << (int)std::chrono::year::min() << '\\n'; + } + +.SH Output: + + The minimum year is: -32767 diff --git a/man/std::chrono::year::ok.3 b/man/std::chrono::year::ok.3 new file mode 100644 index 000000000..2a96d0e6d --- /dev/null +++ b/man/std::chrono::year::ok.3 @@ -0,0 +1,60 @@ +.TH std::chrono::year::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::ok \- std::chrono::year::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the year value stored in *this is in the valid range, i.e., + [-32767, 32767]. + +.SH Return value + + true if the year value stored in *this is in the range [-32767, 32767]. Otherwise + false. + +.SH Possible implementation + + See the implementations in libstdc++, libc++, and Howard Hinnant's date.h. + + class Year + { + short year_; // exposition-only + + public: + + bool ok() const noexcept { return year_ != std::numeric_limits::min(); } + + /*...*/ + }; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << "input year │ internal value │ ok()\\n" << std::boolalpha; + + for (const int i : {2020, 0x8000, 0x8001, 0xFFFF, 0x18000}) + { + const std::chrono::year y{i}; + std::cout << std::setw(10) << i << " │ " + << std::setw(14) << static_cast(y) << " │ " + << y.ok() << '\\n'; + } + } + +.SH Possible output: + + input year │ internal value │ ok() + 2020 │ 2020 │ true + 32768 │ -32768 │ false + 32769 │ -32767 │ true + 65535 │ -1 │ true + 98304 │ -32768 │ false diff --git a/man/std::chrono::year::operator++,std::chrono::year::operator--.3 b/man/std::chrono::year::operator++,std::chrono::year::operator--.3 new file mode 100644 index 000000000..e426edb29 --- /dev/null +++ b/man/std::chrono::year::operator++,std::chrono::year::operator--.3 @@ -0,0 +1,63 @@ +.TH std::chrono::year::operator++,std::chrono::year::operator-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::operator++,std::chrono::year::operator-- \- std::chrono::year::operator++,std::chrono::year::operator-- + +.SH Synopsis + constexpr std::chrono::year& operator++() noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::year operator++( int ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::year& operator--() noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr std::chrono::year operator--( int ) noexcept; \fB(4)\fP \fI(since C++20)\fP + + Adds or subtracts 1 from the year value. + + 1,2) Performs *this += std::chrono::years{1};. + 3,4) Performs *this -= std::chrono::years{1};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) A reference to this year after modification. + 2,4) A copy of the year made before modification. + +.SH Notes + + If the result would be outside the range [-32767, 32767], the actual stored value is + unspecified. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::chrono::year y{2020}; + std::cout << (++y == std::chrono::year(2021)) << ' '; + std::cout << (--y == std::chrono::year(2020)) << '\\n'; + + using namespace std::literals::chrono_literals; + y = 32767y; + y++; //← unspecified, see ↑ Notes ↑ + std::cout << static_cast(y) << '\\n'; + } + +.SH Possible output: + + true true + -32768 + +.SH See also + + operator+= adds or subtracts a number of years from a year + operator-= \fI(public member function)\fP + operator+ performs arithmetic on years + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::year::operator+,std::chrono::year::operator-.3 b/man/std::chrono::year::operator+,std::chrono::year::operator-.3 new file mode 100644 index 000000000..7e4a0a9c4 --- /dev/null +++ b/man/std::chrono::year::operator+,std::chrono::year::operator-.3 @@ -0,0 +1,36 @@ +.TH std::chrono::year::operator+,std::chrono::year::operator- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::operator+,std::chrono::year::operator- \- std::chrono::year::operator+,std::chrono::year::operator- + +.SH Synopsis + constexpr std::chrono::year operator+() noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::year operator-() noexcept; \fB(2)\fP \fI(since C++20)\fP + + Applies the unary operators to the year value. + + 1) Returns a copy of *this. + 2) Returns a year whose year value is the negation of that of *this. + +.SH Return value + + 1) *this + 2) std::chrono::year(-int(*this)) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::chrono::year y{2020}; + constexpr auto ny = -y; + std::cout << "The year " << (int)y << " negated is " << (int)ny << '\\n'; + } + +.SH Output: + + The year 2020 negated is -2020 diff --git a/man/std::chrono::year::operator+=,std::chrono::year::operator-=.3 b/man/std::chrono::year::operator+=,std::chrono::year::operator-=.3 new file mode 100644 index 000000000..e16971a55 --- /dev/null +++ b/man/std::chrono::year::operator+=,std::chrono::year::operator-=.3 @@ -0,0 +1,59 @@ +.TH std::chrono::year::operator+=,std::chrono::year::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::operator+=,std::chrono::year::operator-= \- std::chrono::year::operator+=,std::chrono::year::operator-= + +.SH Synopsis + constexpr std::chrono::year& operator+=( const std::chrono::years& \fB(1)\fP \fI(since C++20)\fP + y ) noexcept; + constexpr std::chrono::year& operator-=( const std::chrono::years& \fB(2)\fP \fI(since C++20)\fP + y ) noexcept; + + Adds or subtracts y.count() years from the year value. + + 1) Equivalent to *this = *this + y;. + 2) Equivalent to *this = *this - y;. + +.SH Return value + + A reference to this year after modification. + +.SH Notes + + If the result would be outside the range [-32767, 32767], the actual stored value is + unspecified. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals::chrono_literals; + std::cout << std::boolalpha; + + std::chrono::year y{2020}; + + y += std::chrono::years(12); + std::cout << (y == 2032y) << ' '; + + y -= std::chrono::years(33); + std::cout << (y == 1999y) << '\\n'; + } + +.SH Output: + + true true + +.SH See also + + operator++ + operator++(int) increments or decrements the year + operator-- \fI(public member function)\fP + operator--(int) + operator+ performs arithmetic on years + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::year::operatorint.3 b/man/std::chrono::year::operatorint.3 new file mode 100644 index 000000000..9f04ada1b --- /dev/null +++ b/man/std::chrono::year::operatorint.3 @@ -0,0 +1,36 @@ +.TH std::chrono::year::operatorint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::operatorint \- std::chrono::year::operatorint + +.SH Synopsis + constexpr explicit operator int() const noexcept; \fI(since C++20)\fP + + Returns the year value stored in *this. + +.SH Return value + + The year value stored in *this. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr std::chrono::year y{2020}; + std::cout << "The year is: " << static_cast(y) << '\\n'; + + const year_month_day ymd{floor(system_clock::now())}; + const std::chrono::year this_year{ymd.year()}; + std::cout << "This year is: " << int(this_year) << '\\n'; + } + +.SH Possible output: + + The year is: 2020 + This year is: 2023 diff --git a/man/std::chrono::year::year.3 b/man/std::chrono::year::year.3 new file mode 100644 index 000000000..219c18eb7 --- /dev/null +++ b/man/std::chrono::year::year.3 @@ -0,0 +1,44 @@ +.TH std::chrono::year::year 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year::year \- std::chrono::year::year + +.SH Synopsis + year() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit year( int y ) noexcept; \fB(2)\fP \fI(since C++20)\fP + + Constructs a year object. + + 1) Default constructor leaves the year value uninitialized. + 2) If y is in the range [-32767, 32767], constructs a year object holding the year + value y. Otherwise the value held is unspecified. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + + constexpr int leap_years = [] + { + int count{}; + for (int i{year::min()}; i <= int{year::max()}; ++i) + if (year{i}.is_leap()) // uses constructor (2) + ++count; + return count; + } (); + + static_assert(15891 == leap_years); + + std::cout << "There are " << leap_years << " leap years in the range [" + << int(year::min()) << ", " << int(year::max()) << "].\\n"; + } + +.SH Output: + + There are 15891 leap years in the range [-32767, 32767]. diff --git a/man/std::chrono::year_month.3 b/man/std::chrono::year_month.3 new file mode 100644 index 000000000..6cb0493a5 --- /dev/null +++ b/man/std::chrono::year_month.3 @@ -0,0 +1,44 @@ +.TH std::chrono::year_month 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month \- std::chrono::year_month + +.SH Synopsis + Defined in header + class year_month; \fI(since C++20)\fP + + The class year_month represents a specific month of a specific year, but with an + unspecified day. It is a field-based time point, with a resolution of + std::chrono::months. + + year_month is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a year_month + \fI(public member function)\fP + year accesses the stored year and month + month \fI(public member function)\fP + operator+= modifies the year_month by some number of months or years + operator-= \fI(public member function)\fP + ok checks if this year_month is valid + \fI(public member function)\fP + + Nonmember functions + + operator== compares two year_month values + operator<=> \fI(function)\fP + (C++20) + operator+ performs arithmetic on year_month + operator- \fI(function)\fP + (C++20) + operator<< outputs a year_month into a stream + (C++20) \fI(function template)\fP + from_stream parses a year_month from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for year_month + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::year_month + (C++26) \fI(class template specialization)\fP diff --git a/man/std::chrono::year_month::ok.3 b/man/std::chrono::year_month::ok.3 new file mode 100644 index 000000000..4d3bebf77 --- /dev/null +++ b/man/std::chrono::year_month::ok.3 @@ -0,0 +1,29 @@ +.TH std::chrono::year_month::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month::ok \- std::chrono::year_month::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if the year and month values stored in this object are valid. + +.SH Return value + + year().ok() && month().ok() + +.SH Example + + +// Run this code + + #include + using namespace std::chrono_literals; + + int main() + { + constexpr std::chrono::year_month ym1{3030y, std::chrono::July}; + static_assert(ym1.ok()); + + constexpr std::chrono::year_month ym2{std::chrono::year(2020)/16}; + static_assert(!ym2.ok()); + } diff --git a/man/std::chrono::year_month::operator+=,std::chrono::year_month::operator-=.3 b/man/std::chrono::year_month::operator+=,std::chrono::year_month::operator-=.3 new file mode 100644 index 000000000..41e6352e6 --- /dev/null +++ b/man/std::chrono::year_month::operator+=,std::chrono::year_month::operator-=.3 @@ -0,0 +1,51 @@ +.TH std::chrono::year_month::operator+=,std::chrono::year_month::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month::operator+=,std::chrono::year_month::operator-= \- std::chrono::year_month::operator+=,std::chrono::year_month::operator-= + +.SH Synopsis + constexpr std::chrono::year_month& \fB(1)\fP \fI(since C++20)\fP + operator+=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month& \fB(2)\fP \fI(since C++20)\fP + operator+=( const std::chrono::months& dm ) const noexcept; + constexpr std::chrono::year_month& \fB(3)\fP \fI(since C++20)\fP + operator-=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month& \fB(4)\fP \fI(since C++20)\fP + operator-=( const std::chrono::months& dm ) const noexcept; + + Modifies the time point *this represents by the duration dy or dm. + + 1) Equivalent to *this = *this + dy;. + 2) Equivalent to *this = *this + dm;. + 3) Equivalent to *this = *this - dy;. + 4) Equivalent to *this = *this - dm;. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (1,3) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto ym{std::chrono::day(1)/7/2023}; + + ym -= std::chrono::years{2}; + assert(ym.month() == std::chrono::July); + assert(ym.year() == std::chrono::year(2021)); + + ym += std::chrono::months{7}; + assert(ym.month() == std::chrono::month(2)); + assert(ym.year() == std::chrono::year(2022)); + } + +.SH See also + + operator+ performs arithmetic on year_month + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::year_month::year,std::chrono::year_month::month.3 b/man/std::chrono::year_month::year,std::chrono::year_month::month.3 new file mode 100644 index 000000000..e50ef305e --- /dev/null +++ b/man/std::chrono::year_month::year,std::chrono::year_month::month.3 @@ -0,0 +1,35 @@ +.TH std::chrono::year_month::year,std::chrono::year_month::month 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month::year,std::chrono::year_month::month \- std::chrono::year_month::year,std::chrono::year_month::month + +.SH Synopsis + constexpr std::chrono::year year() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::month month() const noexcept; \fB(2)\fP \fI(since C++20)\fP + + Retrieves the year and month values stored in this year_month object. + +.SH Return value + + 1) Returns the stored std::chrono::year value. + 2) Returns the stored std::chrono::month value. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + constexpr auto ym{std::chrono::year(2021)/std::chrono::July}; + std::cout << (ym.year() == std::chrono::year(2021)) << ' '; + std::cout << (ym.month() == std::chrono::month(7)) << '\\n'; + } + +.SH Output: + + true true diff --git a/man/std::chrono::year_month::year_month.3 b/man/std::chrono::year_month::year_month.3 new file mode 100644 index 000000000..dc84de08f --- /dev/null +++ b/man/std::chrono::year_month::year_month.3 @@ -0,0 +1,23 @@ +.TH std::chrono::year_month::year_month 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month::year_month \- std::chrono::year_month::year_month + +.SH Synopsis + year_month() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr year_month( const std::chrono::year& y, \fB(2)\fP \fI(since C++20)\fP + const std::chrono::month& m ) noexcept; + + Constructs a year_month object. + + 1) Default constructor leaves the year and month uninitialized. + 2) Constructs a year_month object storing the year y and the month m. + +.SH Notes + + A more convenient way to construct a year_month is with operator/, e.g., + 2007y/std::chrono::April. + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::year_month_day.3 b/man/std::chrono::year_month_day.3 new file mode 100644 index 000000000..968a5469f --- /dev/null +++ b/man/std::chrono::year_month_day.3 @@ -0,0 +1,75 @@ +.TH std::chrono::year_month_day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day \- std::chrono::year_month_day + +.SH Synopsis + Defined in header + class year_month_day; \fI(since C++20)\fP + + The class year_month_day represents a specific year, month, and day. It is a + field-based time point, with a resolution of std::chrono::days. std::chrono::years- + and std::chrono::months-oriented arithmetic are supported directly. An implicit + conversion to and from std::chrono::sys_days allows std::chrono::days-oriented + arithmetic to be performed efficiently. + + year_month_day is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a year_month_day + \fI(public member function)\fP + operator+= modifies the time point by some number of months or years + operator-= \fI(public member function)\fP + year accesses the year, month, and day stored in this object + month \fI(public member function)\fP + day + operator sys_days converts to a std::chrono::time_point + operator local_days \fI(public member function)\fP + ok checks if the year_month_day represents a valid date + \fI(public member function)\fP + + Nonmember functions + + operator== compares two year_month_day values + operator<=> \fI(function)\fP + (C++20) + operator+ adds or subtracts a year_month_day and some number of years or months + operator- \fI(function)\fP + (C++20) + operator<< outputs a year_month_day into a stream + (C++20) \fI(function template)\fP + from_stream parses a year_month_day from a stream according to the provided format + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for year_month_day + (C++20) \fI(class template specialization)\fP + std::hash hash support for + (C++26) std::chrono::year_month_day + \fI(class template specialization)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::chrono::time_point now{std::chrono::system_clock::now()}; + + const std::chrono::year_month_day ymd{std::chrono::floor(now)}; + + std::cout << "Current Year: " << static_cast(ymd.year()) << ", " + "Month: " << static_cast(ymd.month()) << ", " + "Day: " << static_cast(ymd.day()) << "\\n" + "ymd: " << ymd << '\\n'; + } + +.SH Possible output: + + Current Year: 2023, Month: 9, Day: 4 + ymd: 2023-09-04 diff --git a/man/std::chrono::year_month_day::ok.3 b/man/std::chrono::year_month_day::ok.3 new file mode 100644 index 000000000..e311d8382 --- /dev/null +++ b/man/std::chrono::year_month_day::ok.3 @@ -0,0 +1,59 @@ +.TH std::chrono::year_month_day::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day::ok \- std::chrono::year_month_day::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if this year_month_day object represents a valid calendar date. + +.SH Return value + + true if this year_month_day object represents a valid calendar date, that is, the + stored year, month, and day values are all valid and the stored day value is within + the number of days in the given year and month. Otherwise false. + +.SH Possible implementation + + constexpr bool std::chrono::year_month_day::ok() const noexcept + { + return year().ok() && month().ok() && day().ok() && + day() <= (year()/month()/std::chrono::last).day(); + } + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr auto ymd1 {std::chrono::day(1)/std::chrono::July/2020}; + static_assert(ymd1.ok()); + + constexpr auto ymd2 {std::chrono::year(2020)/7/42}; + static_assert(not ymd2.ok()); + + constexpr auto ymd3 {std::chrono::February/29/2020}; // ok, leap year + static_assert(ymd3.ok()); + + constexpr auto ymd4 = ymd3 + std::chrono::years{1}; // bad, not a leap year + static_assert(ymd4 == std::chrono::February/29/2021 and not ymd4.ok()); + + // to fix the bad date we may want to snap to the last day of the month: + if constexpr (!ymd4.ok()) + { + constexpr auto ymd = ymd4.year()/ymd4.month()/std::chrono::last; + static_assert(ymd == std::chrono::February/28/2021 and ymd.ok()); + } + + // or we may want to overflow to the next month: + if constexpr (!ymd4.ok()) + { + constexpr auto st = std::chrono::sys_time{ymd4}; + constexpr auto ymd = std::chrono::year_month_day{st}; + static_assert(ymd == std::chrono::March/1/2021 and ymd.ok()); + } + } diff --git a/man/std::chrono::year_month_day::operator+=,std::chrono::year_month_day::operator-=.3 b/man/std::chrono::year_month_day::operator+=,std::chrono::year_month_day::operator-=.3 new file mode 100644 index 000000000..0fbe185da --- /dev/null +++ b/man/std::chrono::year_month_day::operator+=,std::chrono::year_month_day::operator-=.3 @@ -0,0 +1,88 @@ +.TH std::chrono::year_month_day::operator+=,std::chrono::year_month_day::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day::operator+=,std::chrono::year_month_day::operator-= \- std::chrono::year_month_day::operator+=,std::chrono::year_month_day::operator-= + +.SH Synopsis + constexpr std::chrono::year_month_day& \fB(1)\fP \fI(since C++20)\fP + operator+=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_day& \fB(2)\fP \fI(since C++20)\fP + operator+=( const std::chrono::months& dm ) const noexcept; + constexpr std::chrono::year_month_day& \fB(3)\fP \fI(since C++20)\fP + operator-=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_day& \fB(4)\fP \fI(since C++20)\fP + operator-=( const std::chrono::months& dm ) const noexcept; + + Modifies the time point *this represents by the duration dy or dm. + + 1) Equivalent to *this = *this + dy;. + 2) Equivalent to *this = *this + dm;. + 3) Equivalent to *this = *this - dy;. + 4) Equivalent to *this = *this - dm;. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (1,3) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr auto monthsInYear{12}; + auto ymd{std::chrono::day(1)/std::chrono::July/2020}; + std::cout << "#1 " << ymd << '\\n'; + + ymd -= std::chrono::years(10); + std::cout << "#2 " << ymd << '\\n'; + assert(ymd.month() == std::chrono::July); + assert(ymd.year() == std::chrono::year(2010)); + + ymd += std::chrono::months(10 * monthsInYear + 11); + std::cout << "#3 " << ymd << '\\n'; + assert(ymd.month() == std::chrono::month(6)); + assert(ymd.year() == std::chrono::year(2021)); + + // Handling the ymd += months "overflow" case. + ymd = std::chrono::May/31/2021; // ok + std::cout << "#4 " << ymd << '\\n'; + assert(ymd.ok()); + + ymd += std::chrono::months{1}; // bad date: June has only 30 days + std::cout << "#5 " << ymd << '\\n'; + assert(not ymd.ok()); + assert(ymd == std::chrono::June/31/2021); + + // Snap to the last day of the month, June 30: + const auto ymd1 = ymd.year()/ymd.month()/std::chrono::last; + std::cout << "#6 " << ymd1 << '\\n'; + assert(ymd1.ok()); + assert(ymd1 == std::chrono::June/30/2021); + + // Overflow into the next month, July 1 (via converting to/from sys_days): + const std::chrono::year_month_day ymd2 = std::chrono::sys_days{ymd}; + std::cout << "#7 " << ymd2 << '\\n'; + assert(ymd2.ok()); + assert(ymd2 == std::chrono::July/1/2021); + } + +.SH Output: + + #1 2020-07-01 + #2 2010-07-01 + #3 2021-06-01 + #4 2021-05-31 + #5 2021-06-31 is not a valid date + #6 2021/Jun/last + #7 2021-07-01 + +.SH See also + + operator+ adds or subtracts a year_month_day and some number of years or months + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator.3 b/man/std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator.3 new file mode 100644 index 000000000..bbdc7e63e --- /dev/null +++ b/man/std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator.3 @@ -0,0 +1,74 @@ +.TH std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator \- std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator + +.SH Synopsis + + constexpr operator std::chrono::sys_days() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit operator std::chrono::local_days() const \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Converts *this to a std::chrono::time_point representing the same date as this + year_month_day. + + 1) If ok() is true, the return value holds a count of days from the + std::chrono::system_clock epoch (1970-01-01) to *this. The result is negative if + *this represent a date prior to it. + Otherwise, if the stored year and month are valid (year().ok() && month().ok() is + true), then the returned value is sys_days(year()/month()/1d) + (day() - 1d). + Otherwise (if year().ok() && month().ok() is false), the return value is + unspecified. + A std::chrono::sys_days in the range [std::chrono::days{-12687428}, + std::chrono::days{11248737}], when converted to year_month_day and back, yields the + same value. + 2) Same as \fB(1)\fP but returns local_days instead. Equivalent to return + local_days(sys_days(*this).time_since_epoch());. + +.SH Notes + + Converting to std::chrono::sys_days and back can be used to normalize a + year_month_day that contains an invalid day but a valid year and month: + + using namespace std::chrono; + auto ymd = 2017y/January/0; + ymd = sys_days{ymd}; + // ymd is now 2016y/December/31 + + Normalizing the year and month can be done by adding (or subtracting) zero + std::chrono::months: + + using namespace std::chrono; + constexpr year_month_day normalize(year_month_day ymd) + { + ymd += months{0}; // normalizes year and month + return sys_days{ymd}; // normalizes day + } + static_assert(normalize(2017y/33/59) == 2019y/10/29); + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + const auto today = sys_days{std::chrono::floor(system_clock::now())}; + for (const year_month_day ymd : {{November/15/2020}, {November/15/2120}, today}) + { + std::cout << ymd; + const auto delta = (sys_days{ymd} - today).count(); + (delta < 0) ? std::cout << " was " << -delta << " day(s) ago\\n" : + (delta > 0) ? std::cout << " is " << delta << " day(s) from now\\n" + : std::cout << " is today!\\n"; + } + } + +.SH Possible output: + + 2020-11-15 was 1014 day(s) ago + 2120-11-15 is 35510 day(s) from now + 2023-08-26 is today! diff --git a/man/std::chrono::year_month_day::year,std::chrono::year_month_day::month,.3 b/man/std::chrono::year_month_day::year,std::chrono::year_month_day::month,.3 new file mode 100644 index 000000000..4061d2582 --- /dev/null +++ b/man/std::chrono::year_month_day::year,std::chrono::year_month_day::month,.3 @@ -0,0 +1,33 @@ +.TH std::chrono::year_month_day::year,std::chrono::year_month_day::month, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day::year,std::chrono::year_month_day::month, \- std::chrono::year_month_day::year,std::chrono::year_month_day::month, + +.SH Synopsis + + constexpr std::chrono::year year() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::month month() const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::day day() const noexcept; \fB(3)\fP \fI(since C++20)\fP + + Retrieves the year, month and day values stored in this year_month_day object. + +.SH Return value + + 1) Returns the stored std::chrono::year value. + 2) Returns the stored std::chrono::month value. + 3) Returns the stored std::chrono::day value. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr std::chrono::year_month_day ymd{std::chrono::July/1/2021}; + + static_assert(ymd.year() == std::chrono::year(2021)); + static_assert(ymd.month() == std::chrono::month(7)); + static_assert(ymd.day() == std::chrono::day(1)); + } diff --git a/man/std::chrono::year_month_day::year_month_day.3 b/man/std::chrono::year_month_day::year_month_day.3 new file mode 100644 index 000000000..8012a31aa --- /dev/null +++ b/man/std::chrono::year_month_day::year_month_day.3 @@ -0,0 +1,80 @@ +.TH std::chrono::year_month_day::year_month_day 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day::year_month_day \- std::chrono::year_month_day::year_month_day + +.SH Synopsis + year_month_day() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr year_month_day( const std::chrono::year& y, + + const std::chrono::month& m, \fB(2)\fP \fI(since C++20)\fP + + const std::chrono::day& d ) noexcept; + constexpr year_month_day( const std::chrono::year_month_day_last& \fB(3)\fP \fI(since C++20)\fP + ymdl ) noexcept; + constexpr year_month_day( const std::chrono::sys_days& dp ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + constexpr explicit year_month_day( const std::chrono::local_days& \fB(5)\fP \fI(since C++20)\fP + dp ) noexcept; + + Constructs a year_month_day object. + + 1) Default constructor leaves the date uninitialized. + 2) Constructs a year_month_day object that stores the year y, month m and day d. + 3) Constructs a year_month_day object that stores the year ymdl.year(), month + ymdl.month() and day ymdl.day(). + 4) Constructs a year_month_day object that represent the same date as the one + represented by dp. + 5) Constructs a year_month_day object that represent the same date as the one + represented by dp, as if by year_month_day(sys_days(dp.time_since_epoch())). + + Constructors (3,4) define implicit conversions from std::chrono::year_month_day_last + and std::chrono::sys_days, respectively. + + For any year_month_day object ymd representing a valid date (ymd.ok() == true), + converting ymd to sys_days and back yields the same value. + +.SH Notes + + A year_month_day can also be created by combining one of the partial-date types + std::chrono::year_month and std::chrono::month_day with the missing component (day + and year, respectively) using operator/. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::chrono; + + constexpr auto ymd2 = std::chrono::year_month_day( + 2020y, std::chrono::January, 31d // overload (2) + ); + std::cout << "ymd2: " << ymd2 << '\\n'; + + constexpr auto ymd3 = std::chrono::year_month_day( + std::chrono::April / std::chrono::Monday[last] / 2023y // overload (3) + ); + std::cout << "ymd3: " << ymd3 << '\\n'; + + const auto now = std::chrono::system_clock::now(); + const auto ymd4 = std::chrono::year_month_day( + std::chrono::floor(now) // overload (4) + ); + std::cout << "ymd4: " << ymd4 << '\\n'; + } + +.SH Possible output: + + ymd2: 2020-01-31 + ymd3: 2023-04-24 + ymd4: 2023-08-30 + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::year_month_day_last.3 b/man/std::chrono::year_month_day_last.3 new file mode 100644 index 000000000..dcc427978 --- /dev/null +++ b/man/std::chrono::year_month_day_last.3 @@ -0,0 +1,94 @@ +.TH std::chrono::year_month_day_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day_last \- std::chrono::year_month_day_last + +.SH Synopsis + Defined in header + class year_month_day_last; \fI(since C++20)\fP + + The class year_month_day_last represents the last day of a specific year and month. + It is a field-based time point, with a resolution of std::chrono::days, subject to + the limit that it can only represent the last day of a month. + + std::chrono::years- and std::chrono::months-oriented arithmetic are supported + directly. An implicit conversion to std::chrono::sys_days allows + std::chrono::days-oriented arithmetic to be performed efficiently. + + year_month_day_last is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a year_month_day_last object + \fI(public member function)\fP + operator+= modifies the time point by some number of months or years + operator-= \fI(public member function)\fP + year + month accesses the fields of this object + day \fI(public member function)\fP + month_day_last + operator sys_days converts to a std::chrono::time_point + operator local_days \fI(public member function)\fP + ok checks whether this object represents a valid date + \fI(public member function)\fP + + Nonmember functions + + operator== compares two year_month_day_last values + operator<=> \fI(function)\fP + (C++20) + operator+ adds or subtracts a year_month_day_last and some number of years or + operator- months + (C++20) \fI(function)\fP + operator<< outputs a year_month_day_last into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + formatting support for + std::formatter year_month_day_last + (C++20) \fI(class template specialization)\fP + + std::hash hash support for + (C++26) std::chrono::year_month_day_last + \fI(class template specialization)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto ymd = std::chrono::year_month_day + { + std::chrono::floor(std::chrono::system_clock::now()) + }; + + const std::chrono::year_month_day_last ymdl + { + ymd.year(), ymd.month() / std::chrono::last + }; + + std::cout << "The last day of present month (" << ymdl << ") is: " + << std::chrono::year_month_day{ymdl}.day() << '\\n'; + + // The 'last' object can be placed wherever it is legal to place a 'day': + using namespace std::chrono; + constexpr std::chrono::year_month_day_last + ymdl1 = 2023y / February / last, + ymdl2 = last / February / 2023y, + ymdl3 = February / last / 2023y; + static_assert(ymdl1 == ymdl2 && ymdl2 == ymdl3); + } + +.SH Possible output: + + The last day of present month (2023/Aug/last) is: 31 + +.SH See also + + year_month_day represents a specific year, month, and day + (C++20) \fI(class)\fP diff --git a/man/std::chrono::year_month_day_last::ok.3 b/man/std::chrono::year_month_day_last::ok.3 new file mode 100644 index 000000000..0731f13a2 --- /dev/null +++ b/man/std::chrono::year_month_day_last::ok.3 @@ -0,0 +1,30 @@ +.TH std::chrono::year_month_day_last::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day_last::ok \- std::chrono::year_month_day_last::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if *this represents a valid date. Because a year_month_day_last represents + the last day of a particular month, it represents a valid date as long as the year + and month are valid. + +.SH Return value + + year().ok() && month().ok() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto ymdl{std::chrono::last/11/2020}; + assert(ymdl.ok()); + ymdl = std::chrono::year(2020)/std::chrono::month(13)/std::chrono::last; + assert(not ymdl.ok()); + } diff --git a/man/std::chrono::year_month_day_last::operator+=,std::chrono::year_month_day_last::operator-=.3 b/man/std::chrono::year_month_day_last::operator+=,std::chrono::year_month_day_last::operator-=.3 new file mode 100644 index 000000000..e7531b7d3 --- /dev/null +++ b/man/std::chrono::year_month_day_last::operator+=,std::chrono::year_month_day_last::operator-=.3 @@ -0,0 +1,53 @@ +.TH std::chrono::year_month_day_last::operator+=,std::chrono::year_month_day_last::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day_last::operator+=,std::chrono::year_month_day_last::operator-= \- std::chrono::year_month_day_last::operator+=,std::chrono::year_month_day_last::operator-= + +.SH Synopsis + constexpr std::chrono::year_month_day_last& \fB(1)\fP \fI(since C++20)\fP + operator+=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_day_last& \fB(2)\fP \fI(since C++20)\fP + operator+=( const std::chrono::months& dm ) const noexcept; + constexpr std::chrono::year_month_day_last& \fB(3)\fP \fI(since C++20)\fP + operator-=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_day_last& \fB(4)\fP \fI(since C++20)\fP + operator-=( const std::chrono::months& dm ) const noexcept; + + Modifies the time point *this represents by the duration dy or dm. + + 1) Equivalent to *this = *this + dy;. + 2) Equivalent to *this = *this + dm;. + 3) Equivalent to *this = *this - dy;. + 4) Equivalent to *this = *this - dm;. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (1,3) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto ymdl{11/std::chrono::last/2020}; + + ymdl += std::chrono::years(15); + assert(ymdl.day() == std::chrono::day(30)); + assert(ymdl.month() == std::chrono::November); + assert(ymdl.year() == std::chrono::year(2035)); + + ymdl -= std::chrono::months(6); + assert(ymdl.day() == std::chrono::day(31)); + assert(ymdl.month() == std::chrono::May); + assert(ymdl.year() == std::chrono::year(2035)); + } + +.SH See also + + operator+ adds or subtracts a year_month_day_last and some number of years or months + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::year_month_day_last::operatorsys_days,.3 b/man/std::chrono::year_month_day_last::operatorsys_days,.3 new file mode 100644 index 000000000..27bc02269 --- /dev/null +++ b/man/std::chrono::year_month_day_last::operatorsys_days,.3 @@ -0,0 +1,59 @@ +.TH std::chrono::year_month_day_last::operatorsys_days, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day_last::operatorsys_days, \- std::chrono::year_month_day_last::operatorsys_days, + +.SH Synopsis + + constexpr operator std::chrono::sys_days() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit operator std::chrono::local_days() const \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Converts *this to a std::chrono::time_point representing the same date as this + year_month_day_last. This is equivalent to composing a year_month_day from year(), + month() and day() and converting that year_month_day to the destination type. + + 1) Equivalent to std::chrono::sys_days(year()/month()/day()). + 2) Equivalent to std::chrono::local_days(year()/month()/day()). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + using namespace std::chrono; + using namespace std::literals; + + int main() + { + constexpr std::chrono::year y{2023y}; + constexpr std::array quarters{"1st"sv, "2nd"sv, "3rd"sv, "4th"sv}; + constexpr auto mq{12 / 4}; // months per quarter + + std::cout << "In year " << static_cast(y) << '\\n'; + for (auto q = 1; q < 5; ++q) + { + const auto ls = y / std::chrono::month(q * mq) / Sunday[last]; + const auto ld = y / std::chrono::month(q * mq) / last; + // subtract last Sunday from last day for day of week + const auto index = (sys_days(ld) - sys_days(ls)).count(); + std::cout << "The " << quarters[q - 1] << " quarter ends on a " + << std::chrono::weekday(index) << '\\n'; + } + } + +.SH Output: + + In year 2023 + The 1st quarter ends on a Fri + The 2nd quarter ends on a Fri + The 3rd quarter ends on a Sat + The 4th quarter ends on a Sun + +.SH See also + + operator sys_days converts to a std::chrono::time_point + operator local_days \fI(public member function of std::chrono::year_month_day)\fP diff --git a/man/std::chrono::year_month_day_last::year,std::chrono::year_month_day_last::month,.3 b/man/std::chrono::year_month_day_last::year,std::chrono::year_month_day_last::month,.3 new file mode 100644 index 000000000..f02155a82 --- /dev/null +++ b/man/std::chrono::year_month_day_last::year,std::chrono::year_month_day_last::month,.3 @@ -0,0 +1,40 @@ +.TH std::chrono::year_month_day_last::year,std::chrono::year_month_day_last::month, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day_last::year,std::chrono::year_month_day_last::month, \- std::chrono::year_month_day_last::year,std::chrono::year_month_day_last::month, + +.SH Synopsis + + constexpr std::chrono::year year() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::month month() const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::day day() const noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr std::chrono::month_day_last month_day_last() const \fB(4)\fP \fI(since C++20)\fP + noexcept; + + Retrieves the field values stored in this year_month_day_last object. + +.SH Return value + + 1) Returns the stored std::chrono::year value. + 2) Returns the stored std::chrono::month value. + 3) A std::chrono::day value corresponding to the last day of the stored year and + month. If this->ok() is false, the return value is unspecified. + 4) A std::chrono::month_day_last constructed from month(). + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr auto ymdl{std::chrono::last/11/2020}; + static_assert + ( + ymdl.day() == std::chrono::day(30) && + ymdl.month() == std::chrono::November && + ymdl.year() == std::chrono::year(2020) && + ymdl.month_day_last() == std::chrono::November/std::chrono::last + ); + } diff --git a/man/std::chrono::year_month_day_last::year_month_day_last.3 b/man/std::chrono::year_month_day_last::year_month_day_last.3 new file mode 100644 index 000000000..f837d50c6 --- /dev/null +++ b/man/std::chrono::year_month_day_last::year_month_day_last.3 @@ -0,0 +1,59 @@ +.TH std::chrono::year_month_day_last::year_month_day_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_day_last::year_month_day_last \- std::chrono::year_month_day_last::year_month_day_last + +.SH Synopsis + constexpr year_month_day_last( const std::chrono::year& y, + const std::chrono::month_day_last& mdl \fI(since C++20)\fP + ) noexcept; + + Constructs a year_month_day_last object storing the year y and the month + mdl.month(). The constructed object represents the last day of that year and month. + +.SH Notes + + A year_month_day_last can also be created by combining a std::chrono::year_month + with std::chrono::last using operator/. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "All last days of months of a given year:\\n"; + + constexpr std::chrono::year year{2021}; + + for (int i{1}; i <= 12; ++i) + { + const std::chrono::month_day_last mdl{std::chrono::month(i) / std::chrono::last}; + const std::chrono::year_month_day_last ymdl{year, mdl}; + std::cout << ymdl << " day: " << ymdl.day() << '\\n'; + } + } + +.SH Possible output: + + All last days of months of a given year: + 2021/Jan/last day: 31 + 2021/Feb/last day: 28 + 2021/Mar/last day: 31 + 2021/Apr/last day: 30 + 2021/May/last day: 31 + 2021/Jun/last day: 30 + 2021/Jul/last day: 31 + 2021/Aug/last day: 31 + 2021/Sep/last day: 30 + 2021/Oct/last day: 31 + 2021/Nov/last day: 30 + 2021/Dec/last day: 31 + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::year_month_weekday.3 b/man/std::chrono::year_month_weekday.3 new file mode 100644 index 000000000..483db29e4 --- /dev/null +++ b/man/std::chrono::year_month_weekday.3 @@ -0,0 +1,51 @@ +.TH std::chrono::year_month_weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday \- std::chrono::year_month_weekday + +.SH Synopsis + Defined in header + class year_month_weekday; \fI(since C++20)\fP + + The class year_month_weekday represents the n^th weekday of a specific year and + month. It is a field-based time point, with a resolution of std::chrono::days. + std::chrono::years- and std::chrono::months-oriented arithmetic are supported + directly. An implicit conversion to and from std::chrono::sys_days allows + std::chrono::days-oriented arithmetic to be performed efficiently. + + year_month_weekday is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a year_month_weekday + \fI(public member function)\fP + operator+= modifies the time point by some number of months or years + operator-= \fI(public member function)\fP + year + month accesses the fields of this object + weekday \fI(public member function)\fP + index + weekday_indexed + operator sys_days converts to a std::chrono::time_point + operator local_days \fI(public member function)\fP + ok checks whether this object represents a valid date + \fI(public member function)\fP + + Nonmember functions + + operator== compares two year_month_weekday values + (C++20) \fI(function)\fP + operator+ adds or subtracts a year_month_weekday and some number of years or months + operator- \fI(function)\fP + (C++20) + operator<< outputs a year_month_weekday into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + formatting support for + std::formatter year_month_weekday + (C++20) \fI(class template specialization)\fP + + std::hash hash support for + (C++26) std::chrono::year_month_weekday + \fI(class template specialization)\fP diff --git a/man/std::chrono::year_month_weekday::ok.3 b/man/std::chrono::year_month_weekday::ok.3 new file mode 100644 index 000000000..7e0ee7a25 --- /dev/null +++ b/man/std::chrono::year_month_weekday::ok.3 @@ -0,0 +1,30 @@ +.TH std::chrono::year_month_weekday::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday::ok \- std::chrono::year_month_weekday::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if this year_month_weekday object represents a valid date. + +.SH Return value + + true if this year_month_weekday object represents a valid date, that is, year().ok() + && month().ok() && weekday_indexed().ok() is true and there are at least index() + weekday()s in the specified year and month. Otherwise false. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto ymwdi{std::chrono::Wednesday[1]/1/2021}; + assert(ymwdi.ok()); + ymwdi = std::chrono::year(2021)/std::chrono::month(1)/std::chrono::Wednesday[42]; + assert(!ymwdi.ok()); + } diff --git a/man/std::chrono::year_month_weekday::operator+=,std::chrono::year_month_weekday::operator-=.3 b/man/std::chrono::year_month_weekday::operator+=,std::chrono::year_month_weekday::operator-=.3 new file mode 100644 index 000000000..81ad06cf4 --- /dev/null +++ b/man/std::chrono::year_month_weekday::operator+=,std::chrono::year_month_weekday::operator-=.3 @@ -0,0 +1,61 @@ +.TH std::chrono::year_month_weekday::operator+=,std::chrono::year_month_weekday::operator-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday::operator+=,std::chrono::year_month_weekday::operator-= \- std::chrono::year_month_weekday::operator+=,std::chrono::year_month_weekday::operator-= + +.SH Synopsis + constexpr std::chrono::year_month_weekday& \fB(1)\fP \fI(since C++20)\fP + operator+=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_weekday& \fB(2)\fP \fI(since C++20)\fP + operator+=( const std::chrono::months& dm ) const noexcept; + constexpr std::chrono::year_month_weekday& \fB(3)\fP \fI(since C++20)\fP + operator-=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_weekday& \fB(4)\fP \fI(since C++20)\fP + operator-=( const std::chrono::months& dm ) const noexcept; + + Modifies the time point *this represents by the duration dy or dm. + + 1) Equivalent to *this = *this + dy;. + 2) Equivalent to *this = *this + dm;. + 3) Equivalent to *this = *this - dy;. + 4) Equivalent to *this = *this - dm;. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (1,3) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto ymwi{1/std::chrono::Wednesday[2]/2021}; + std::cout << ymwi << '\\n'; + + ymwi += std::chrono::years(5); + std::cout << ymwi << '\\n'; + assert(static_cast(ymwi) == + std::chrono::year(2026)/1/14); + + ymwi -= std::chrono::months(1); + std::cout << ymwi << '\\n'; + assert(static_cast(ymwi) == + std::chrono::day(10)/12/2025); + } + +.SH Output: + + 2021/Jan/Wed[2] + 2026/Jan/Wed[2] + 2025/Dec/Wed[2] + +.SH See also + + operator+ adds or subtracts a year_month_weekday and some number of years or months + operator- \fI(function)\fP + (C++20) diff --git a/man/std::chrono::year_month_weekday::operatorsys_days,.3 b/man/std::chrono::year_month_weekday::operatorsys_days,.3 new file mode 100644 index 000000000..4c950e874 --- /dev/null +++ b/man/std::chrono::year_month_weekday::operatorsys_days,.3 @@ -0,0 +1,47 @@ +.TH std::chrono::year_month_weekday::operatorsys_days, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday::operatorsys_days, \- std::chrono::year_month_weekday::operatorsys_days, + +.SH Synopsis + + constexpr operator std::chrono::sys_days() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit operator std::chrono::local_days() const \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Converts *this to a std::chrono::time_point representing the same date as this + year_month_weekday. + + 1) If year().ok() && month().ok() && weekday().ok(): + + * If index() == 0, returns a sys_days that represents the date 7 days prior to the + first weekday() of the year and month. + * Else, returns a sys_days that represents the date (index() - 1) * 7 days after + the first weekday() of the year and month. + Otherwise, the returned value is unspecified. + 2) Same as \fB(1)\fP, but returns local_days instead of sys_days. Equivalent to + local_days(sys_days(*this).time_since_epoch()). + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto ymwd{Tuesday[2]/11/2021}; + std::cout << ymwd << '\\n'; + // convert from field-based to serial-based to add hours + constexpr auto sd = sys_days{ymwd} + 24h; + std::cout << sd << '\\n'; + constexpr auto ymd = floor(sd); + static_assert(ymd == November/10/2021); + } + +.SH Output: + + 2021/Nov/Tue[2] + 2021-11-10 00:00:00 diff --git a/man/std::chrono::year_month_weekday::year,std::chrono::year_month_weekday::month,.3 b/man/std::chrono::year_month_weekday::year,std::chrono::year_month_weekday::month,.3 new file mode 100644 index 000000000..3e2bb715d --- /dev/null +++ b/man/std::chrono::year_month_weekday::year,std::chrono::year_month_weekday::month,.3 @@ -0,0 +1,43 @@ +.TH std::chrono::year_month_weekday::year,std::chrono::year_month_weekday::month, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday::year,std::chrono::year_month_weekday::month, \- std::chrono::year_month_weekday::year,std::chrono::year_month_weekday::month, + +.SH Synopsis + std::chrono::year_month_weekday::weekday_indexed + + constexpr std::chrono::year year() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::month month() const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday weekday() const noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr unsigned index() const noexcept; \fB(4)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday_indexed weekday_indexed() const \fB(5)\fP \fI(since C++20)\fP + noexcept; + + Retrieves the field values stored in this year_month_weekday object. + +.SH Return value + + 1) Returns the stored std::chrono::year value. + 2) Returns the stored std::chrono::month value. + 3) Returns the stored std::chrono::weekday value. + 4) Returns the stored weekday index. + 5) weekday()[index()] + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr auto ym{std::chrono::year(2021)/std::chrono::January}; + constexpr auto wdi{std::chrono::Wednesday[1]}; + auto ymwdi{ym/wdi}; + const auto index{ymwdi.index() + 1}; + auto weekday{ymwdi.weekday() + std::chrono::days(1)}; + ymwdi = {ymwdi.year()/ymwdi.month()/weekday[index]}; + // Second Thursday in January, 2021 + assert(std::chrono::year_month_day{ymwdi} == std::chrono::January/14/2021); + } diff --git a/man/std::chrono::year_month_weekday::year_month_weekday.3 b/man/std::chrono::year_month_weekday::year_month_weekday.3 new file mode 100644 index 000000000..d8079d0dc --- /dev/null +++ b/man/std::chrono::year_month_weekday::year_month_weekday.3 @@ -0,0 +1,39 @@ +.TH std::chrono::year_month_weekday::year_month_weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday::year_month_weekday \- std::chrono::year_month_weekday::year_month_weekday + +.SH Synopsis + year_month_weekday() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr year_month_weekday( const std::chrono::year& y, + + const std::chrono::month& m, \fB(2)\fP \fI(since C++20)\fP + + const std::chrono::weekday_indexed& + wdi ) noexcept; + constexpr year_month_weekday( const std::chrono::sys_days& dp ) \fB(3)\fP \fI(since C++20)\fP + noexcept; + constexpr explicit year_month_weekday( const \fB(4)\fP \fI(since C++20)\fP + std::chrono::local_days& dp ) noexcept; + + Constructs a year_month_weekday object. + + 1) Default constructor leaves the fields uninitialized. + 2) Constructs a year_month_weekday object storing the year y, the month m, the + weekday wdi.weekday() and the weekday index wdi.index(). + 3) Constructs a year_month_weekday object corresponding to the date represented by + dp. For any year_month_weekday object storing a valid date, converting it to + sys_days and back yields the same value. This constructor defines an implicit + conversion from sys_days to year_month_weekday. + 4) Constructs a year_month_weekday object corresponding to the date represented by + dp. Equivalent to year_month_weekday(sys_days(dp.time_since_epoch())). + +.SH Notes + + A year_month_weekday can also be created by combining one of the partial-date types + std::chrono::year_month and std::chrono::month_weekday with the missing component + (indexed weekday and year, respectively) using operator/. + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::year_month_weekday_last.3 b/man/std::chrono::year_month_weekday_last.3 new file mode 100644 index 000000000..ca3faff84 --- /dev/null +++ b/man/std::chrono::year_month_weekday_last.3 @@ -0,0 +1,51 @@ +.TH std::chrono::year_month_weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday_last \- std::chrono::year_month_weekday_last + +.SH Synopsis + Defined in header + class year_month_weekday_last; \fI(since C++20)\fP + + The class year_month_weekday_last represents the last weekday of a specific year and + month. It is a field-based time point, with a resolution of std::chrono::days, + except that it is limited to pointing to the last weekday of a year and month. + std::chrono::years- and std::chrono::months-oriented arithmetic are supported + directly. An implicit conversion to std::chrono::sys_days allows + std::chrono::days-oriented arithmetic to be performed efficiently. + + year_month_weekday_last is a TriviallyCopyable StandardLayoutType. + +.SH Member functions + + constructor constructs a year_month_weekday_last + \fI(public member function)\fP + operator+= modifies the time point by some number of months or years + operator-= \fI(public member function)\fP + year + month accesses the fields of this object + weekday \fI(public member function)\fP + weekday_last + operator sys_days converts to a std::chrono::time_point + operator local_days \fI(public member function)\fP + ok checks whether this object represents a valid date + \fI(public member function)\fP + + Nonmember functions + + operator== compares two year_month_weekday_last values + (C++20) \fI(function)\fP + operator+ adds or subtracts a year_month_weekday_last and some number of years or + operator- months + (C++20) \fI(function)\fP + operator<< outputs a year_month_weekday_last into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + formatting support for + std::formatter year_month_weekday_last + (C++20) \fI(class template specialization)\fP + + std::hash hash support for + (C++26) std::chrono::year_month_weekday_last + \fI(class template specialization)\fP diff --git a/man/std::chrono::year_month_weekday_last::ok.3 b/man/std::chrono::year_month_weekday_last::ok.3 new file mode 100644 index 000000000..775562c76 --- /dev/null +++ b/man/std::chrono::year_month_weekday_last::ok.3 @@ -0,0 +1,33 @@ +.TH std::chrono::year_month_weekday_last::ok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday_last::ok \- std::chrono::year_month_weekday_last::ok + +.SH Synopsis + constexpr bool ok() const noexcept; \fI(since C++20)\fP + + Checks if this object represents a valid date. Since a year_month_weekday_last + represents the last weekday of a particular month, it is valid as long as the year, + month and weekday are valid. + +.SH Return value + + year().ok() && month().ok() && weekday().ok() + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + auto ymwdl{Tuesday[last]/11/2020}; + assert(ymwdl.ok()); + ymwdl = Tuesday[last]/-2/2021; + assert(!ymwdl.ok()); + ymwdl += months(0); // Normalize month + assert(ymwdl.ok()); + } diff --git a/man/std::chrono::year_month_weekday_last::operator+=,.3 b/man/std::chrono::year_month_weekday_last::operator+=,.3 new file mode 100644 index 000000000..97b23558d --- /dev/null +++ b/man/std::chrono::year_month_weekday_last::operator+=,.3 @@ -0,0 +1,56 @@ +.TH std::chrono::year_month_weekday_last::operator+=, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday_last::operator+=, \- std::chrono::year_month_weekday_last::operator+=, + +.SH Synopsis + + constexpr std::chrono::year_month_weekday_last& \fB(1)\fP \fI(since C++20)\fP + operator+=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_weekday_last& \fB(2)\fP \fI(since C++20)\fP + operator+=( const std::chrono::months& dm ) const noexcept; + constexpr std::chrono::year_month_weekday_last& \fB(3)\fP \fI(since C++20)\fP + operator-=( const std::chrono::years& dy ) const noexcept; + constexpr std::chrono::year_month_weekday_last& \fB(4)\fP \fI(since C++20)\fP + operator-=( const std::chrono::months& dm ) const noexcept; + + Modifies the time point *this represents by the duration dy or dm. + + 1) Equivalent to *this = *this + dy;. + 2) Equivalent to *this = *this + dm;. + 3) Equivalent to *this = *this - dy;. + 4) Equivalent to *this = *this - dm;. + + For durations that are convertible to both std::chrono::years and + std::chrono::months, the years overloads (1,3) are preferred if the call would + otherwise be ambiguous. + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + auto ymwdl{August/Friday[last]/2022}; + std::cout << year_month_day{ymwdl} << '\\n'; + ymwdl += months(2); + std::cout << year_month_day{ymwdl} << '\\n'; + ymwdl -= years(1); + std::cout << year_month_day{ymwdl} << '\\n'; + } + +.SH Output: + + 2022-08-26 + 2022-10-28 + 2021-10-29 + +.SH See also + + operator+ adds or subtracts a year_month_weekday_last and some number of years or + operator- months + (C++20) \fI(function)\fP diff --git a/man/std::chrono::year_month_weekday_last::operatorsys_days,.3 b/man/std::chrono::year_month_weekday_last::operatorsys_days,.3 new file mode 100644 index 000000000..eaf25d36a --- /dev/null +++ b/man/std::chrono::year_month_weekday_last::operatorsys_days,.3 @@ -0,0 +1,41 @@ +.TH std::chrono::year_month_weekday_last::operatorsys_days, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday_last::operatorsys_days, \- std::chrono::year_month_weekday_last::operatorsys_days, + +.SH Synopsis + + constexpr operator std::chrono::sys_days() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit operator std::chrono::local_days() const \fB(2)\fP \fI(since C++20)\fP + noexcept; + + Converts *this to a std::chrono::time_point representing the same date as this + year_month_weekday_last. + + 1) If ok() is true, returns a sys_days that represents the last weekday() of the + year() and month(). Otherwise, the returned value is unspecified. + 2) Same as \fB(1)\fP, but returns local_days instead of sys_days. Equivalent to + local_days(sys_days(*this).time_since_epoch()). + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + constexpr auto ymwdl{Tuesday[last]/11/2021}; + static_assert(static_cast(ymwdl) == + static_cast(November/30/2021)); + // convert from field-based to serial-based to add days + constexpr auto sd = static_cast(ymwdl); + constexpr year_month_day ymd{sd + days(42)}; + std::cout << ymd << '\\n'; + } + +.SH Output: + + 2022-01-11 diff --git a/man/std::chrono::year_month_weekday_last::year,std::chrono::year_month_weekday_last::month,.3 b/man/std::chrono::year_month_weekday_last::year,std::chrono::year_month_weekday_last::month,.3 new file mode 100644 index 000000000..6d15315f0 --- /dev/null +++ b/man/std::chrono::year_month_weekday_last::year,std::chrono::year_month_weekday_last::month,.3 @@ -0,0 +1,42 @@ +.TH std::chrono::year_month_weekday_last::year,std::chrono::year_month_weekday_last::month, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday_last::year,std::chrono::year_month_weekday_last::month, \- std::chrono::year_month_weekday_last::year,std::chrono::year_month_weekday_last::month, + +.SH Synopsis + std::chrono::year_month_weekday_last::weekday_last + + constexpr std::chrono::year year() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr std::chrono::month month() const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday weekday() const noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr std::chrono::weekday_last weekday_last() const noexcept; \fB(4)\fP \fI(since C++20)\fP + + Retrieves the field values stored in this year_month_weekday_last object. + +.SH Return value + + 1) Returns the stored std::chrono::year value. + 2) Returns the stored std::chrono::month value. + 3) Returns the stored std::chrono::weekday value. + 4) std::chrono::weekday_last(weekday()) + +.SH Example + + +// Run this code + + #include + #include + using namespace std::chrono; + + int main() + { + auto ymwdl{Tuesday[last]/November/2022}; + auto wdl = ymwdl.weekday_last(); + wdl = (wdl.weekday() + days(1))[last]; + ymwdl = {ymwdl.year() + years(1), ymwdl.month() - months(2), wdl}; + std::cout << year_month_day(ymwdl) << '\\n'; + } + +.SH Output: + + 2023-09-27 diff --git a/man/std::chrono::year_month_weekday_last::year_month_weekday_last.3 b/man/std::chrono::year_month_weekday_last::year_month_weekday_last.3 new file mode 100644 index 000000000..b90cf36b1 --- /dev/null +++ b/man/std::chrono::year_month_weekday_last::year_month_weekday_last.3 @@ -0,0 +1,27 @@ +.TH std::chrono::year_month_weekday_last::year_month_weekday_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::year_month_weekday_last::year_month_weekday_last \- std::chrono::year_month_weekday_last::year_month_weekday_last + +.SH Synopsis + constexpr + + year_month_weekday_last( const std::chrono::year& y, const + std::chrono::month& m, \fI(since C++20)\fP + + const std::chrono::weekday_last& wdl ) + noexcept; + + Constructs a year_month_weekday_last object storing the year y, the month m, and the + weekday wdl.weekday(). The constructed object represents the last weekday of that + year and month. + +.SH Notes + + A year_month_weekday_last can also be created by combining one of the partial-date + types std::chrono::year_month and std::chrono::month_weekday_last with the missing + component (weekday_last and year, respectively) using operator/. + +.SH See also + + operator/ conventional syntax for Gregorian calendar date creation + (C++20) \fI(function)\fP diff --git a/man/std::chrono::zoned_time.3 b/man/std::chrono::zoned_time.3 new file mode 100644 index 000000000..8f01b4e35 --- /dev/null +++ b/man/std::chrono::zoned_time.3 @@ -0,0 +1,139 @@ +.TH std::chrono::zoned_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time \- std::chrono::zoned_time + +.SH Synopsis + Defined in header + template< + + class Duration, \fI(since C++20)\fP + class TimeZonePtr = const std::chrono::time_zone* + + > class zoned_time; + using zoned_seconds = std::chrono::zoned_time; \fI(since C++20)\fP + + The class zoned_time represents a logical pairing of a time zone and a + std::chrono::time_point whose resolution is Duration. + + An invariant of zoned_time is that it always refers to a valid time zone and + represents an existing and unambiguous time point in that time zone. Consistent with + this invariant, zoned_time has no move constructor or move assignment operator; + attempts to move a zoned_time will perform a copy. + + The program is ill-formed if Duration is not a specialization of + std::chrono::duration. + + The template parameter TimeZonePtr allows users to supply their own time zone + pointer types and further customize the behavior of zoned_time via + std::chrono::zoned_traits. Custom time zone types need not support all the + operations supported by std::chrono::time_zone, only those used by the functions + actually called on the zoned_time. + + TimeZonePtr must be MoveConstructible. Move-only TimeZonePtrs are allowed but + difficult to use, as the zoned_time will be immovable and it is not possible to + access the stored TimeZonePtr. + +.SH Member types + + Member type Definition + duration std::common_type_t + +.SH Member functions + + constructor constructs a zoned_time + \fI(public member function)\fP + operator= assigns value to a zoned_time + \fI(public member function)\fP + get_time_zone obtains a copy of the time zone pointer + \fI(public member function)\fP + operator local_time obtains the stored time point as a local_time + get_local_time \fI(public member function)\fP + operator sys_time obtains the stored time point as a sys_time + get_sys_time \fI(public member function)\fP + get_info obtain information about the time zone at the stored time point + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares two zoned_time values + (C++20) \fI(function template)\fP + operator<< outputs a zoned_time into a stream + (C++20) \fI(function template)\fP + +.SH Helper classes + + std::formatter formatting support for zoned_time + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::chrono::zoned_time + (C++26) \fI(class template specialization)\fP + + Deduction guides + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + constexpr std::string_view locations[] = + { + "Africa/Casablanca", "America/Argentina/Buenos_Aires", + "America/Barbados", "America/Indiana/Petersburg", + "America/Tarasco_Bar", "Antarctica/Casey", + "Antarctica/Vostok", "Asia/Magadan", + "Asia/Manila", "Asia/Shanghai", + "Asia/Tokyo", "Atlantic/Bermuda", + "Australia/Darwin", "Europe/Isle_of_Man", + "Europe/Laputa", "Indian/Christmas", + "Indian/Cocos", "Pacific/Galapagos", + }; + + constexpr auto width = std::ranges::max_element(locations, {}, + [](const auto& s){ return s.length(); })->length(); + + for (const auto location : locations) + try + { + // may throw if 'location' is not in the time zone database + const std::chrono::zoned_time zt{location, std::chrono::system_clock::now()}; + std::cout << std::setw(width) << location << " - Zoned Time: " << zt << '\\n'; + } + catch (std::runtime_error& ex) + { + std::cout << "Error: " << ex.what() << '\\n'; + } + } + +.SH Possible output: + + Africa/Casablanca - Zoned Time: 2023-06-29 20:58:34.697449319 +01 + America/Argentina/Buenos_Aires - Zoned Time: 2023-06-29 16:58:34.709957354 -03 + America/Barbados - Zoned Time: 2023-06-29 15:58:34.709977888 AST + America/Indiana/Petersburg - Zoned Time: 2023-06-29 15:58:34.709998072 EDT + Error: tzdb: cannot locate zone: America/Tarasco_Bar + Antarctica/Casey - Zoned Time: 2023-06-30 06:58:34.710093685 +11 + Antarctica/Vostok - Zoned Time: 2023-06-30 01:58:34.710107932 +06 + Asia/Magadan - Zoned Time: 2023-06-30 06:58:34.710121831 +11 + Asia/Manila - Zoned Time: 2023-06-30 03:58:34.710134751 PST + Asia/Shanghai - Zoned Time: 2023-06-30 03:58:34.710153259 CST + Asia/Tokyo - Zoned Time: 2023-06-30 04:58:34.710172815 JST + Atlantic/Bermuda - Zoned Time: 2023-06-29 16:58:34.710191043 ADT + Australia/Darwin - Zoned Time: 2023-06-30 05:28:34.710236720 ACST + Europe/Isle_of_Man - Zoned Time: 2023-06-29 20:58:34.710256834 BST + Error: tzdb: cannot locate zone: Europe/Laputa + Indian/Christmas - Zoned Time: 2023-06-30 02:58:34.710360409 +07 + Indian/Cocos - Zoned Time: 2023-06-30 02:28:34.710377520 +0630 + Pacific/Galapagos - Zoned Time: 2023-06-29 13:58:34.710389952 -06 + +.SH See also + + time_zone represents a time zone + (C++20) \fI(class)\fP diff --git a/man/std::chrono::zoned_time::get_info.3 b/man/std::chrono::zoned_time::get_info.3 new file mode 100644 index 000000000..1d0778c9d --- /dev/null +++ b/man/std::chrono::zoned_time::get_info.3 @@ -0,0 +1,15 @@ +.TH std::chrono::zoned_time::get_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time::get_info \- std::chrono::zoned_time::get_info + +.SH Synopsis + std::chrono::sys_info get_info() const; \fI(since C++20)\fP + + Obtains the std::chrono::sys_info containing information about the time zone at the + time point stored in *this. + +.SH Return value + + zone->get_info(tp), where zone is the non-static data member holding the time zone + pointer, and tp is the non-static data member holding the stored time point (as a + std::chrono::sys_time). diff --git a/man/std::chrono::zoned_time::get_time_zone.3 b/man/std::chrono::zoned_time::get_time_zone.3 new file mode 100644 index 000000000..ffc57e6b3 --- /dev/null +++ b/man/std::chrono::zoned_time::get_time_zone.3 @@ -0,0 +1,16 @@ +.TH std::chrono::zoned_time::get_time_zone 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time::get_time_zone \- std::chrono::zoned_time::get_time_zone + +.SH Synopsis + TimeZonePtr get_time_zone() const; \fI(since C++20)\fP + + Retrieves the stored time zone pointer. + +.SH Return value + + A copy of the stored time zone pointer. + +.SH Notes + + There's no way to access the time zone pointer when TimeZonePtr is a move-only type. diff --git a/man/std::chrono::zoned_time::operator=.3 b/man/std::chrono::zoned_time::operator=.3 new file mode 100644 index 000000000..3759a33af --- /dev/null +++ b/man/std::chrono::zoned_time::operator=.3 @@ -0,0 +1,26 @@ +.TH std::chrono::zoned_time::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time::operator= \- std::chrono::zoned_time::operator= + +.SH Synopsis + zoned_time& operator=( const zoned_time& other ) = default; \fB(1)\fP \fI(since C++20)\fP + zoned_time& operator=( const std::chrono::sys_time& \fB(2)\fP \fI(since C++20)\fP + other ); + zoned_time& operator=( const std::chrono::local_time& \fB(3)\fP \fI(since C++20)\fP + other ); + + Assign the value of other to *this. + + 1) Defaulted copy assignment operator. Copy-assigns both the stored time point and + the stored time zone pointer. zoned_time has no move assignment operator; a move is + a copy. + 2) Assigns other to the stored time point. The time zone pointer is unchanged. After + this call, get_sys_time() == other. + 3) Converts other to a std::chrono::sys_time as if by zone->to_sys(other) (where + zone is the non-static data member holding the stored time zone pointer) and assigns + the result to the stored time point. The time zone pointer is unchanged. After this + call, get_local_time() == other. + +.SH Return value + + *this diff --git a/man/std::chrono::zoned_time::operatorlocal_time,.3 b/man/std::chrono::zoned_time::operatorlocal_time,.3 new file mode 100644 index 000000000..7c487f751 --- /dev/null +++ b/man/std::chrono::zoned_time::operatorlocal_time,.3 @@ -0,0 +1,17 @@ +.TH std::chrono::zoned_time::operatorlocal_time, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time::operatorlocal_time, \- std::chrono::zoned_time::operatorlocal_time, + +.SH Synopsis + + std::chrono::local_time get_local_time() const; \fI(since C++20)\fP + explicit operator std::chrono::local_time() const; \fI(since C++20)\fP + + Obtains a std::chrono::local_time representing the local time in the time + zone corresponding to the time point *this represents. + +.SH Return value + + A std::chrono::local_time computed as if by + zone->to_local(get_sys_time()), where zone is the non-static data member holding the + stored time zone pointer. diff --git a/man/std::chrono::zoned_time::operatorsys_time,.3 b/man/std::chrono::zoned_time::operatorsys_time,.3 new file mode 100644 index 000000000..abcc3fff4 --- /dev/null +++ b/man/std::chrono::zoned_time::operatorsys_time,.3 @@ -0,0 +1,15 @@ +.TH std::chrono::zoned_time::operatorsys_time, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time::operatorsys_time, \- std::chrono::zoned_time::operatorsys_time, + +.SH Synopsis + + operator std::chrono::sys_time() const; \fI(since C++20)\fP + std::chrono::sys_time get_sys_time() const; \fI(since C++20)\fP + + Obtains a std::chrono::sys_time representing the same point in time as + this zoned_time object. + +.SH Return value + + A std::chrono::sys_time representing the same point in time as *this. diff --git a/man/std::chrono::zoned_time::zoned_time.3 b/man/std::chrono::zoned_time::zoned_time.3 new file mode 100644 index 000000000..7adf95982 --- /dev/null +++ b/man/std::chrono::zoned_time::zoned_time.3 @@ -0,0 +1,154 @@ +.TH std::chrono::zoned_time::zoned_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_time::zoned_time \- std::chrono::zoned_time::zoned_time + +.SH Synopsis + zoned_time(); \fB(1)\fP \fI(since C++20)\fP + zoned_time( const std::chrono::sys_time& st ); \fB(2)\fP \fI(since C++20)\fP + zoned_time( const zoned_time& other ) = default; \fB(3)\fP \fI(since C++20)\fP + template< class Duration2 > + zoned_time( const std::chrono::zoned_time& other ); + explicit zoned_time( TimeZonePtr z ); \fB(5)\fP \fI(since C++20)\fP + explicit zoned_time( std::string_view name ); \fB(6)\fP \fI(since C++20)\fP + zoned_time( TimeZonePtr z, const std::chrono::sys_time& \fB(7)\fP \fI(since C++20)\fP + st ); + zoned_time( std::string_view name, const \fB(8)\fP \fI(since C++20)\fP + std::chrono::sys_time& st ); + zoned_time( TimeZonePtr z, const \fB(9)\fP \fI(since C++20)\fP + std::chrono::local_time& tp ); + zoned_time( std::string_view name, const \fB(10)\fP \fI(since C++20)\fP + std::chrono::local_time& tp ); + zoned_time( TimeZonePtr z, const + std::chrono::local_time& tp, \fB(11)\fP \fI(since C++20)\fP + std::chrono::choose c ); + zoned_time( std::string_view name, + const std::chrono::local_time& tp, \fB(12)\fP \fI(since C++20)\fP + std::chrono::choose c ); + template< class Duration2, class TimeZonePtr2 > + + zoned_time( TimeZonePtr z, \fB(13)\fP \fI(since C++20)\fP + + const std::chrono::zoned_time& zt ); + template< class Duration2, class TimeZonePtr2 > + + zoned_time( TimeZonePtr z, + const std::chrono::zoned_time& zt, + + std::chrono::choose ); + template< class Duration2, class TimeZonePtr2 > + + zoned_time( std::string_view name, \fB(15)\fP \fI(since C++20)\fP + + const std::chrono::zoned_time& zt ); + template< class Duration2, class TimeZonePtr2 > + + zoned_time( std::string_view name, + const std::chrono::zoned_time& zt, + + std::chrono::choose ); + + Constructs a zoned_time object, initializing the stored time zone pointer and time + point according to the following table, where traits is + std::chrono::zoned_traits: + + Overload Time zone pointer (denoted Time point (a Notes + zone) std::chrono::sys_time) + \fB(1)\fP traits::default_zone() default constructed (a) + \fB(2)\fP st + \fB(3)\fP other.get_time_zone() other.get_sys_time() (b) + \fB(4)\fP other.get_time_zone() other.get_sys_time() (e) + \fB(5)\fP std::move(z) default constructed + \fB(6)\fP traits::locate_zone(name) (c) + \fB(7)\fP std::move(z) st + \fB(8)\fP traits::locate_zone(name) (c) + \fB(9)\fP std::move(z) zone->to_sys(tp) (d) + \fB(10)\fP traits::locate_zone(name) (c,d) + \fB(11)\fP std::move(z) zone->to_sys(tp, c) (d) + \fB(12)\fP traits::locate_zone(name) (c,d) + (13,14) std::move(z) zt.get_sys_time() (e) + (15,16) traits::locate_zone(name) (c,e) + + a) Constructors specified to call traits::default_zone() (1,2) do not participate in + overload resolution if that expression is not well-formed. + b) The defaulted copy constructor \fB(3)\fP is defined as deleted if + std::is_copy_constructible_v is false. + c) Constructors with a std::string_view parameter name (6,8,10,12,15,16) do not + participate in overload resolution if traits::locate_zone(name) is not well-formed + or if that expression is not convertible to TimeZonePtr. + d) Constructors specified to call zone->to_sys (9-12) do not participate in overload + resolution if that call expression is not well-formed or if the result is not + convertible to std::chrono::sys_time. + e) Constructors with a template parameter Duration2 (4,13-16) do not participate in + overload resolution if Duration2 is not convertible to Duration. + + The behavior is undefined if the time zone pointer (initialized as described above) + does not refer to a time zone. + +.SH Notes + + zoned_time does not have a move constructor and attempting to move one will perform + a copy instead using the defaulted copy constructor \fB(3)\fP. Thus, when TimeZonePtr is a + move-only type, zoned_time is immovable: it can be neither moved nor copied. + + The constructors (14,16) accept a std::chrono::choose parameter, but that parameter + has no effect. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using std::chrono_literals::operator""y; + using std::operator""sv; + + std::cout << std::chrono::zoned_time{} << " : default\\n"; + + constexpr std::string_view location1{"America/Phoenix"sv}; + std::cout << std::chrono::zoned_time{location1} << " : " << location1 << '\\n'; + + const std::chrono::time_zone* timeZonePtr = std::chrono::locate_zone("UTC"); + std::cout << std::chrono::zoned_time{timeZonePtr} << " : UTC time zone\\n"; + + constexpr auto location2{"Europe/Rome"sv}; + std::cout << std::chrono::zoned_time{location2, std::chrono::local_days{2021y/12/31}} + << " : " << location2 << '\\n'; + + constexpr auto location3{"Europe/Rome"sv}; + constexpr auto some_date = std::chrono::sys_time{2021y/12/31}; + std::cout << std::chrono::zoned_time{location3, some_date} + << " : " << location3 << '\\n'; + + const auto now = + std::chrono::floor(std::chrono::system_clock::now()); + constexpr auto location4{"Europe/Rome"sv}; + std::cout << std::chrono::zoned_time{location4, now} << " : " << location4 << '\\n'; + + constexpr auto NewYork{"America/New_York"sv}; + constexpr auto Tokyo{"Asia/Tokyo"sv}; + const std::chrono::zoned_time tz_Tokyo{Tokyo, now}; + const std::chrono::zoned_time tz_NewYork{NewYork, now}; + std::cout << std::chrono::zoned_time{Tokyo, tz_NewYork} << " : " << Tokyo << '\\n'; + std::cout << std::chrono::zoned_time{NewYork, tz_Tokyo} << " : " << NewYork << '\\n'; + } + +.SH Possible output: + + 1970-01-01 00:00:00 UTC : default + 1969-12-31 17:00:00 MST : America/Phoenix + 1970-01-01 00:00:00 UTC : UTC time zone + 2021-12-31 00:00:00 CET : Europe/Rome + 2021-12-31 01:00:00 CET : Europe/Rome + 2021-09-20 23:04:00 CEST : Europe/Rome + 2021-09-21 06:04:00 JST : Asia/Tokyo + 2021-09-20 17:04:00 EDT : America/New_York diff --git a/man/std::chrono::zoned_traits.3 b/man/std::chrono::zoned_traits.3 new file mode 100644 index 000000000..f55f23292 --- /dev/null +++ b/man/std::chrono::zoned_traits.3 @@ -0,0 +1,42 @@ +.TH std::chrono::zoned_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::chrono::zoned_traits \- std::chrono::zoned_traits + +.SH Synopsis + Defined in header + template < class TimeZonePtr > \fB(1)\fP \fI(since C++20)\fP + struct zoned_traits { }; + template <> \fB(2)\fP \fI(since C++20)\fP + struct zoned_traits; + + The class zoned_traits provides a way to customize the behavior of the constructors + of std::chrono::zoned_time with custom time zone pointer types. In particular, it + allows such types to specify the default time zone to use and the mapping of a time + zone's name to the corresponding time zone pointer. It is acceptable for custom time + zone pointer types to not support either operation, in which case the corresponding + constructors of zoned_time will not participate in overload resolution. + + The primary template is empty. A specialization is provided for const + std::chrono::time_zone*, the default time zone pointer type. + +.SH Member functions + +std::chrono::zoned_traits::default_zone + + static const std::chrono::time_zone* default_zone(); + + Returns a time zone pointer for the default time zone (UTC). + +.SH Return value + + std::chrono::locate_zone("UTC"). + +std::chrono::zoned_traits::locate_zone + + static const std::chrono::time_zone* locate_zone(std::string_view name); + + Returns the time zone pointer for the time zone designated by name. + +.SH Return value + + std::chrono::locate_zone(name). diff --git a/man/std::cin,std::wcin.3 b/man/std::cin,std::wcin.3 index 35c2e6233..e50d42b6c 100644 --- a/man/std::cin,std::wcin.3 +++ b/man/std::cin,std::wcin.3 @@ -1,4 +1,7 @@ -.TH std::cin,std::wcin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cin,std::wcin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cin,std::wcin \- std::cin,std::wcin + .SH Synopsis Defined in header extern std::istream cin; \fB(1)\fP @@ -8,9 +11,10 @@ implementation-defined type (derived from std::streambuf), associated with the standard C input stream stdin. - These objects are guaranteed to be constructed before the first constructor of a - static object is called and they are guaranteed to outlive the last destructor of a - static object, so that it is always possible to read from std::cin in user code. + These objects are guaranteed to be initialized during or before the first time an + object of type std::ios_base::Init is constructed and are available for use in the + constructors and destructors of static objects with ordered initialization (as long + as is included before the object is defined). Unless sync_with_stdio(false) has been issued, it is safe to concurrently access these objects from multiple threads for both formatted and unformatted input. @@ -20,33 +24,47 @@ on std::cin forces a call to std::cout.flush() if any characters are pending for output. +.SH Notes + + The 'c' in the name refers to "character" (stroustrup.com FAQ); cin means "character + input" and wcin means "wide character input". + .SH Example - + // Run this code #include - struct Foo { + + struct Foo + { int n; - Foo() { - std::cout << "Enter n: "; // no flush needed - std::cin >> n; + Foo() + { + std::cout << "Enter n: "; // no flush needed + std::cin >> n; } }; + Foo f; // static object + int main() { std::cout << "f.n is " << f.n << '\\n'; } -.SH Output: +.SH Possible output: Enter n: 10 f.n is 10 .SH See also - Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP - cout writes to the standard C output stream stdout - wcout (global object) + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + cout writes to the standard C output stream stdout + wcout (global object) + stdin expression of type FILE* associated with the input stream + stdout expression of type FILE* associated with the output stream + stderr expression of type FILE* associated with the error output stream + (macro constant) diff --git a/man/std::clamp.3 b/man/std::clamp.3 new file mode 100644 index 000000000..d0fb24139 --- /dev/null +++ b/man/std::clamp.3 @@ -0,0 +1,139 @@ +.TH std::clamp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::clamp \- std::clamp + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++17)\fP + constexpr const T& clamp( const T& v, const T& lo, const T& hi ); + template< class T, class Compare > + + constexpr const T& clamp( const T& v, const T& lo, const T& hi, \fB(2)\fP \fI(since C++17)\fP + + Compare comp ); + + If the value of v is within [lo, hi], returns v; otherwise returns the nearest + boundary. + + 1) Uses + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP to compare the values. + If T is not LessThanComparable, the behavior is undefined.^[1] + 2) Uses the comparison function comp to compare the values. + + If lo is greater than hi, the behavior is undefined. + + 1. ↑ If NaN is avoided, T can be a floating-point type. + +.SH Parameters + + v - the value to clamp + lo, hi - the boundaries to clamp v to + comparison function object (i.e. an object that satisfies the requirements + of Compare) which returns true if the first argument is less than the + second. + + The signature of the comparison function should be equivalent to the + following: + + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type T can be + implicitly converted to both of them. + +.SH Return value + + Reference to lo if v is less than lo, reference to hi if hi is less than v, + otherwise reference to v. + +.SH Complexity + + 1) At most two comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most two applications of the comparison function comp. + +.SH Possible implementation + + clamp \fB(1)\fP + template + constexpr const T& clamp(const T& v, const T& lo, const T& hi) + { + return clamp(v, lo, hi, less{}); + } + clamp \fB(2)\fP + template + constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp) + { + return comp(v, lo) ? lo : comp(hi, v) ? hi : v; + } + +.SH Notes + + + Capturing the result of std::clamp by reference produces a dangling reference if one + of the parameters is a temporary and that parameter is returned: + + int n = -1; + const int& r = std::clamp(n, 0, 255); // r is dangling + + If v compares equivalent to either bound, returns a reference to v, not the bound. + + Feature-test macro Value Std Feature + __cpp_lib_clamp 201603L \fI(C++17)\fP std::clamp + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << "[raw] " + "[" << INT8_MIN << ',' << INT8_MAX << "] " + "[0," << UINT8_MAX << "]\\n"; + + for (const int v : {-129, -128, -1, 0, 42, 127, 128, 255, 256}) + std::cout << std::setw(4) << v + << std::setw(11) << std::clamp(v, INT8_MIN, INT8_MAX) + << std::setw(8) << std::clamp(v, 0, UINT8_MAX) << '\\n'; + } + +.SH Output: + + [raw] [-128,127] [0,255] + -129 -128 0 + -128 -128 0 + -1 -1 0 + 0 0 0 + 42 42 42 + 127 127 127 + 128 127 128 + 255 127 255 + 256 127 255 + +.SH See also + + min returns the smaller of the given values + \fI(function template)\fP + max returns the greater of the given values + \fI(function template)\fP + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP + ranges::clamp clamps a value between a pair of boundary values + (C++20) (niebloid) diff --git a/man/std::clearerr.3 b/man/std::clearerr.3 index 5667fe79c..9b8b20158 100644 --- a/man/std::clearerr.3 +++ b/man/std::clearerr.3 @@ -1,4 +1,7 @@ -.TH std::clearerr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::clearerr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::clearerr \- std::clearerr + .SH Synopsis Defined in header void clearerr( std::FILE* stream ); @@ -15,20 +18,42 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + std::FILE* tmpf = std::tmpfile(); + std::fputs("cppreference.com\\n", tmpf); + std::rewind(tmpf); + + for (int ch; (ch = std::fgetc(tmpf)) != EOF; std::putchar(ch)) { } + + assert(std::feof(tmpf)); // the loop is expected to terminate by EOF + std::puts("End of file reached"); + + std::clearerr(tmpf); // clear EOF + + std::puts(std::feof(tmpf) ? "EOF indicator set" + : "EOF indicator cleared"); + } + +.SH Output: + + cppreference.com + End of file reached + EOF indicator cleared .SH See also feof checks for the end-of-file - \fI(function)\fP + \fI(function)\fP perror displays a character string corresponding of the current error to stderr - \fI(function)\fP + \fI(function)\fP ferror checks for a file error - \fI(function)\fP + \fI(function)\fP C documentation for clearerr - -.SH Category: - - * Todo no example diff --git a/man/std::clock.3 b/man/std::clock.3 index c065bb67c..dc1d023ad 100644 --- a/man/std::clock.3 +++ b/man/std::clock.3 @@ -1,4 +1,7 @@ -.TH std::clock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::clock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::clock \- std::clock + .SH Synopsis Defined in header std::clock_t clock(); @@ -22,71 +25,75 @@ .SH Return value - Processor time used by the program so far or (clock_t)(-1) if that information is - unavailable. + Processor time used by the program so far or std::clock_t(-1) if that information is + unavailable or its value cannot be represented. .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes On POSIX-compatible systems, clock_gettime with clock id CLOCK_PROCESS_CPUTIME_ID offers better resolution. - The value returned by clock() may wrap around on some implementations. For example, - on a machine with 32-bit std::clock_t, it wraps after 2147 seconds or 36 minutes. + The value returned by clock() may wrap around on some non-conforming + implementations. For example, on such an implementation, if std::clock_t is a signed + 32-bit integer and CLOCKS_PER_SEC is 1'000'000, it will wrap after about 2147 + seconds (about 36 minutes). .SH Example - This example demonstrates the difference between clock() time and real time + This example demonstrates the difference between clock() time and real time. + - // Run this code - #include #include #include + #include + #include #include - - // the function f() does some time-consuming work + + // The function f() does some time-consuming work. void f() { - volatile double d; - for(int n=0; n<10000; ++n) - for(int m=0; m<10000; ++m) - d += d*n*m; + volatile double d = 0; + for (int n = 0; n < 10000; ++n) + for (int m = 0; m < 10000; ++m) + { + double diff = d * n * m; + d = diff + d; + } } - + int main() { - std::clock_t c_start = std::clock(); + const std::clock_t c_start = std::clock(); auto t_start = std::chrono::high_resolution_clock::now(); std::thread t1(f); std::thread t2(f); // f() is called on two threads t1.join(); t2.join(); - std::clock_t c_end = std::clock(); - auto t_end = std::chrono::high_resolution_clock::now(); - - std::cout << "CPU time used: " - << 1000.0 * (c_end-c_start) / CLOCKS_PER_SEC - << " ms\\n"; - std::cout << "Wall clock time passed: " - << std::chrono::duration_cast(t_end - t_start).count() - << " ms\\n"; + const std::clock_t c_end = std::clock(); + const auto t_end = std::chrono::high_resolution_clock::now(); + + std::cout << std::fixed << std::setprecision(2) << "CPU time used: " + << 1000.0 * (c_end - c_start) / CLOCKS_PER_SEC << "ms\\n" + << "Wall clock time passed: " + << std::chrono::duration(t_end - t_start) << '\\n'; } -.SH Output: +.SH Possible output: - CPU time used: 1520 ms - Wall clock time passed: 769 ms + CPU time used: 1590.00ms + Wall clock time passed: 808.23ms .SH See also - ctime converts a time_t object to a textual representation - \fI(function)\fP + ctime converts a std::time_t object to a textual representation + \fI(function)\fP time returns the current time of the system as time since epoch - \fI(function)\fP + \fI(function)\fP C documentation for clock diff --git a/man/std::clock_t.3 b/man/std::clock_t.3 index e85c6b117..1b15edac2 100644 --- a/man/std::clock_t.3 +++ b/man/std::clock_t.3 @@ -1,4 +1,7 @@ -.TH std::clock_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::clock_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::clock_t \- std::clock_t + .SH Synopsis Defined in header typedef /* unspecified */ clock_t; @@ -9,8 +12,8 @@ .SH See also clock returns raw processor clock time since the program is started - \fI(function)\fP + \fI(function)\fP CLOCKS_PER_SEC number of processor clock ticks per second - (macro constant) + (macro constant) C documentation for clock_t diff --git a/man/std::clog,std::wclog.3 b/man/std::clog,std::wclog.3 index cc90a916e..5b27a6496 100644 --- a/man/std::clog,std::wclog.3 +++ b/man/std::clog,std::wclog.3 @@ -1,4 +1,7 @@ -.TH std::clog,std::wclog 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::clog,std::wclog 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::clog,std::wclog \- std::clog,std::wclog + .SH Synopsis Defined in header extern std::ostream clog; \fB(1)\fP @@ -7,34 +10,44 @@ The global objects std::clog and std::wclog control output to a stream buffer of implementation-defined type (derived from std::streambuf), associated with the standard C output stream stderr, but, unlike std::cerr/std::wcerr, these streams are - not automatically flushed and not automatically tie()'d with cout. + not automatically flushed and cout is not automatically tie()'d with these streams. These objects are guaranteed to be initialized during or before the first time an object of type std::ios_base::Init is constructed and are available for use in the - constructors and destructors of static objects (as long as is included). + constructors and destructors of static objects with ordered initialization (as long + as is included before the object is defined). + + Unless std::ios_base::sync_with_stdio(false) has been issued, it is safe to + concurrently access these objects from multiple threads for both formatted and + unformatted output. - Unless sync_with_stdio(false) has been issued, it is safe to concurrently access - these objects from multiple threads for both formatted and unformatted output. +.SH Notes + + The 'c' in the name refers to "character" (stroustrup.com FAQ); clog means + "character log" and wclog means "wide character log". .SH Example - + // Run this code #include - - struct Foo { + + struct Foo + { int n; - Foo() { - std::clog << "static constructor\\n"; + Foo() + { + std::clog << "static constructor\\n"; } - ~Foo() { - std::clog << "static destructor\\n"; + ~Foo() + { + std::clog << "static destructor\\n"; } }; - + Foo f; // static object - + int main() { std::clog << "main function\\n"; @@ -48,9 +61,13 @@ .SH See also - Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP - cerr writes to the standard C error stream stderr, unbuffered - wcerr (global object) - cout writes to the standard C output stream stdout - wcout (global object) + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + cerr writes to the standard C error stream stderr, unbuffered + wcerr (global object) + cout writes to the standard C output stream stdout + wcout (global object) + stdin expression of type FILE* associated with the input stream + stdout expression of type FILE* associated with the output stream + stderr expression of type FILE* associated with the error output stream + (macro constant) diff --git a/man/std::cmp_equal,cmp_not_equal,cmp_less,cmp_greater,cmp_less_equal,cmp_greater_equal.3 b/man/std::cmp_equal,cmp_not_equal,cmp_less,cmp_greater,cmp_less_equal,cmp_greater_equal.3 new file mode 100644 index 000000000..200aff73f --- /dev/null +++ b/man/std::cmp_equal,cmp_not_equal,cmp_less,cmp_greater,cmp_less_equal,cmp_greater_equal.3 @@ -0,0 +1,169 @@ +.TH std::cmp_equal,cmp_not_equal,cmp_less,cmp_greater,cmp_less_equal,cmp_greater_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cmp_equal,cmp_not_equal,cmp_less,cmp_greater,cmp_less_equal,cmp_greater_equal \- std::cmp_equal,cmp_not_equal,cmp_less,cmp_greater,cmp_less_equal,cmp_greater_equal + +.SH Synopsis + Defined in header + template< class T, class U > \fB(1)\fP \fI(since C++20)\fP + constexpr bool cmp_equal( T t, U u ) noexcept; + template< class T, class U > \fB(2)\fP \fI(since C++20)\fP + constexpr bool cmp_not_equal( T t, U u ) noexcept; + template< class T, class U > \fB(3)\fP \fI(since C++20)\fP + constexpr bool cmp_less( T t, U u ) noexcept; + template< class T, class U > \fB(4)\fP \fI(since C++20)\fP + constexpr bool cmp_greater( T t, U u ) noexcept; + template< class T, class U > \fB(5)\fP \fI(since C++20)\fP + constexpr bool cmp_less_equal( T t, U u ) noexcept; + template< class T, class U > \fB(6)\fP \fI(since C++20)\fP + constexpr bool cmp_greater_equal( T t, U u ) noexcept; + + Compare the values of two integers t and u. Unlike builtin comparison operators, + negative signed integers always compare less than (and not equal to) unsigned + integers: the comparison is safe against non-value-preserving integer conversion. + + -1 > 0u; // true + std::cmp_greater(-1, 0u); // false + + It is a compile-time error if either T or U is a non-integer type, a character type, + or bool. + +.SH Parameters + + t - left-hand argument + u - right-hand argument + +.SH Return value + + 1) true if t is equal to u. + 2) true if t is not equal to u. + 3) true if t is less than u. + 4) true if t is greater than u. + 5) true if t is less or equal to u. + 6) true if t is greater or equal to u. + +.SH Possible implementation + + template + constexpr bool cmp_equal(T t, U u) noexcept + { + if constexpr (std::is_signed_v == std::is_signed_v) + return t == u; + else if constexpr (std::is_signed_v) + return t >= 0 && std::make_unsigned_t(t) == u; + else + return u >= 0 && std::make_unsigned_t(u) == t; + } + + template + constexpr bool cmp_not_equal(T t, U u) noexcept + { + return !cmp_equal(t, u); + } + + template + constexpr bool cmp_less(T t, U u) noexcept + { + if constexpr (std::is_signed_v == std::is_signed_v) + return t < u; + else if constexpr (std::is_signed_v) + return t < 0 || std::make_unsigned_t(t) < u; + else + return u >= 0 && t < std::make_unsigned_t(u); + } + + template + constexpr bool cmp_greater(T t, U u) noexcept + { + return cmp_less(u, t); + } + + template + constexpr bool cmp_less_equal(T t, U u) noexcept + { + return !cmp_less(u, t); + } + + template + constexpr bool cmp_greater_equal(T t, U u) noexcept + { + return !cmp_less(t, u); + } + +.SH Notes + + These functions cannot be used to compare enums (including std::byte), char, + char8_t, char16_t, char32_t, wchar_t and bool. + + Feature-test macro Value Std Feature + __cpp_lib_integer_comparison_functions 202002L (C++20) Integer comparison functions + +.SH Example + + The example below might produce different signedness comparison warning if compiled + without an appropriate warning suppression flag, e.g., -Wno-sign-compare (gcc/clang + with -Wall -Wextra, see also SO: disabling a specific warning). + + +// Run this code + + #include + + // Uncommenting the next line will disable "signed/unsigned comparison" warnings: + // #pragma GCC diagnostic ignored "-Wsign-compare" + + int main() + { + static_assert(sizeof(int) == 4); // precondition + + // Quite surprisingly + static_assert(-1 > 1U); //< warning: sign-unsign comparison + // because after implicit conversion of -1 to the RHS type (`unsigned int`) + // the expression is equivalent to: + static_assert(0xFFFFFFFFU > 1U); + static_assert(0xFFFFFFFFU == static_cast(-1)); + + // In contrast, the cmp_* family compares integers as most expected - + // negative signed integers always compare less than unsigned integers: + static_assert(std::cmp_less(-1, 1U)); + static_assert(std::cmp_less_equal(-1, 1U)); + static_assert(!std::cmp_greater(-1, 1U)); + static_assert(!std::cmp_greater_equal(-1, 1U)); + + static_assert(-1 == 0xFFFFFFFFU); //< warning: sign-unsign comparison + static_assert(std::cmp_not_equal(-1, 0xFFFFFFFFU)); + } + +.SH See also + + equal_to function object implementing x == y + \fI(class template)\fP + not_equal_to function object implementing x != y + \fI(class template)\fP + less function object implementing x < y + \fI(class template)\fP + greater function object implementing x > y + \fI(class template)\fP + less_equal function object implementing x <= y + \fI(class template)\fP + greater_equal function object implementing x >= y + \fI(class template)\fP + ranges::equal_to constrained function object implementing x == y + (C++20) \fI(class)\fP + ranges::not_equal_to constrained function object implementing x != y + (C++20) \fI(class)\fP + ranges::less constrained function object implementing x < y + (C++20) \fI(class)\fP + ranges::greater constrained function object implementing x > y + (C++20) \fI(class)\fP + ranges::less_equal constrained function object implementing x <= y + (C++20) \fI(class)\fP + ranges::greater_equal constrained function object implementing x >= y + (C++20) \fI(class)\fP + compare_three_way constrained function object implementing x <=> y + (C++20) \fI(class)\fP + in_range checks if an integer value is in the range of a given integer + (C++20) type + \fI(function template)\fP + provides an interface to query properties of all fundamental + numeric_limits numeric types + \fI(class template)\fP diff --git a/man/std::codecvt.3 b/man/std::codecvt.3 index 8cac50aca..2784e9e46 100644 --- a/man/std::codecvt.3 +++ b/man/std::codecvt.3 @@ -1,95 +1,105 @@ -.TH std::codecvt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt \- std::codecvt + .SH Synopsis Defined in header template< class InternT, class ExternT, - class State + class StateT > class codecvt; - Class std::codecvt encapsulates conversion of character strings, including wide and - multibyte, from one encoding to another. All file I/O operations performed through - std::basic_fstream use the std::codecvt facet of - the locale imbued in the stream. + Class template std::codecvt encapsulates conversion of character strings, including + wide and multibyte, from one encoding to another. All file I/O operations performed + through std::basic_fstream use the std::codecvt + facet of the locale imbued in the stream. std-codecvt-inheritance.svg - About this image Inheritance diagram - Four standalone (locale-independent) specializations are provided by the standard - library: +.SH Specializations - Defined in header - std::codecvt identity conversion - std::codecvt conversion between UTF-16 and UTF-8 - \fI(since C++11)\fP - std::codecvt conversion between UTF-32 and UTF-8 - \fI(since C++11)\fP - std::codecvt conversion between the system's native - wide and multibyte encodings + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these four specializations. + Defined in header + std::codecvt identity conversion + std::codecvt conversion between UTF-16 and UTF-8 + \fI(since C++11)\fP(deprecated in C++20) + std::codecvt conversion between UTF-16 and UTF-8 + \fI(since C++20)\fP + std::codecvt conversion between UTF-32 and UTF-8 + \fI(since C++11)\fP(deprecated in C++20) + std::codecvt conversion between UTF-32 and UTF-8 + \fI(since C++20)\fP + std::codecvt wide and the single-byte narrow character + sets .SH Member types - Member type Definition + Member name Definition intern_type InternT extern_type ExternT - state_type State + state_type StateT .SH Member functions constructor constructs a new codecvt facet \fI(public member function)\fP - destructor destructs a codecvt facet - \fI(protected member function)\fP out invokes do_out - \fI(public member function)\fP + \fI(public member function)\fP in invokes do_in - \fI(public member function)\fP + \fI(public member function)\fP unshift invokes do_unshift - \fI(public member function)\fP + \fI(public member function)\fP encoding invokes do_encoding - \fI(public member function)\fP + \fI(public member function)\fP always_noconv invokes do_always_noconv - \fI(public member function)\fP + \fI(public member function)\fP length invokes do_length - \fI(public member function)\fP + \fI(public member function)\fP max_length invokes do_max_length - \fI(public member function)\fP + \fI(public member function)\fP .SH Member objects - Member name Type - id (static) std::locale::id + static std::locale::id id id of the locale + \fI(public member object)\fP .SH Protected member functions - do_out converts a string from internT to externT, such as when writing to + destructor destructs a codecvt facet + \fI(protected member function)\fP + do_out converts a string from InternT to ExternT, such as when writing to \fB[virtual]\fP file - \fI(virtual protected member function)\fP - do_in converts a string from externT to internT, such as when reading + \fI(virtual protected member function)\fP + do_in converts a string from ExternT to InternT, such as when reading \fB[virtual]\fP from file - \fI(virtual protected member function)\fP - do_unshift generates the termination character sequence of externT characters + \fI(virtual protected member function)\fP + do_unshift generates the termination character sequence of ExternT characters \fB[virtual]\fP for incomplete conversion - \fI(virtual protected member function)\fP - do_encoding returns the number of externT characters necessary to produce one - \fB[virtual]\fP internT character, if constant - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP + do_encoding returns the number of ExternT characters necessary to produce one + \fB[virtual]\fP InternT character, if constant + \fI(virtual protected member function)\fP do_always_noconv tests if the facet encodes an identity conversion for all valid \fB[virtual]\fP argument values - \fI(virtual protected member function)\fP - do_length calculates the length of the externT string that would be consumed - \fB[virtual]\fP by conversion into given internT buffer - \fI(virtual protected member function)\fP - do_max_length returns the maximum number of externT characters that could be - \fB[virtual]\fP converted into a single internT character - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP + do_length calculates the length of the ExternT string that would be consumed + \fB[virtual]\fP by conversion into given InternT buffer + \fI(virtual protected member function)\fP + do_max_length returns the maximum number of ExternT characters that could be + \fB[virtual]\fP converted into a single InternT character + \fI(virtual protected member function)\fP Inherited from std::codecvt_base @@ -105,98 +115,102 @@ Inherited from std::codecvt_base .SH Example The following examples reads a UTF-8 file using a locale which implements UTF-8 - conversion in codecvt and converts a UTF-8 string to - UTF-16 using one of the standard specializations of std::codecvt + conversion in codecvt and converts a UTF-8 string to + UTF-16 using one of the standard specializations of std::codecvt. + - // Run this code - #include + #include + #include #include - #include - #include #include + #include + #include #include - #include - + // utility wrapper to adapt locale-bound facets for wstring/wbuffer convert template struct deletable_facet : Facet { - template - deletable_facet(Args&& ...args) : Facet(std::forward(args)...) {} + template + deletable_facet(Args&&... args) : Facet(std::forward(args)...) {} ~deletable_facet() {} }; - + int main() { // UTF-8 narrow multibyte encoding - std::string data = u8"z\\u00df\\u6c34\\U0001f34c"; - // or u8"zß水🍌" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c"; - + std::string data = reinterpret_cast(+u8"z\\u00df\\u6c34\\U0001f34c"); + // or reinterpret_cast(+u8"zß水🍌") + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c" + std::ofstream("text.txt") << data; - + // using system-supplied locale's codecvt facet std::wifstream fin("text.txt"); - // reading from wifstream willl use codecvt + // reading from wifstream will use codecvt // this locale's codecvt converts UTF-8 to UCS4 (on systems such as Linux) fin.imbue(std::locale("en_US.UTF-8")); - std::cout << "The UTF-8 file contains the following UCS4 code points: \\n"; - for (wchar_t c; fin >> c; ) - std::cout << "U+" << std::hex << std::setw(4) << std::setfill('0') << c << '\\n'; - + std::cout << "The UTF-8 file contains the following UCS4 code units:\\n" << std::hex; + for (wchar_t c; fin >> c;) + std::cout << "U+" << std::setw(4) << std::setfill('0') + << static_cast(c) << ' '; + // using standard (locale-independent) codecvt facet std::wstring_convert< deletable_facet>, char16_t> conv16; std::u16string str16 = conv16.from_bytes(data); - - std::cout << "The UTF-8 file contains the following UTF-16 code points: \\n"; + + std::cout << "\\n\\nThe UTF-8 file contains the following UTF-16 code units:\\n" + << std::hex; for (char16_t c : str16) - std::cout << "U+" << std::hex << std::setw(4) << std::setfill('0') << c << '\\n'; + std::cout << "U+" << std::setw(4) << std::setfill('0') + << static_cast(c) << ' '; + std::cout << '\\n'; } .SH Output: - The UTF-8 file contains the following UCS4 code points: - U+007a - U+00df - U+6c34 - U+1f34c - The UTF-8 file contains the following UTF-16 code points: - U+007a - U+00df - U+6c34 - U+d83c - U+df4c + The UTF-8 file contains the following UCS4 code units: + U+007a U+00df U+6c34 U+1f34c + + The UTF-8 file contains the following UTF-16 code units: + U+007a U+00df U+6c34 U+d83c U+df4c .SH See also - Character narrow multibyte UTF-8 UTF-16 - conversions (char) (char) (char16_t) - codecvt - UTF-16 c16rtomb codecvt_utf8_utf16 N/A - codecvt_utf8_utf16 - codecvt_utf8_utf16 - UCS2 No codecvt_utf8 codecvt_utf16 - UTF-32/UCS4 mbrtoc32 / codecvt codecvt_utf16 - codecvt_utf8 - UCS2/UCS4 No codecvt_utf8 codecvt_utf16 - (wchar_t) - codecvt No No - (wchar_t) mbsrtowcs / - wcsrtombs - - codecvt_base defines character conversion errors - \fI(class template)\fP - codecvt_byname creates a codecvt facet for the named locale - \fI(class template)\fP - codecvt_utf8 converts between UTF-8 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf16 converts between UTF-16 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8_utf16 converts between UTF-8 and UTF-16 - \fI(C++11)\fP \fI(class template)\fP + Character locale-defined multibyte UTF-8 UTF-16 + conversions (UTF-8, GB18030) + codecvt + UTF-16 mbrtoc16 / c16rtomb (with C11's codecvt_utf8_utf16 N/A + DR488) codecvt_utf8_utf16 + codecvt_utf8_utf16 + UCS-2 c16rtomb (without C11's DR488) codecvt_utf8 codecvt_utf16 + UTF-32 mbrtoc32 / c32rtomb codecvt codecvt_utf16 + codecvt_utf8 + system + wchar_t: + mbsrtowcs / wcsrtombs + UTF-32 use_facet codecvt_utf16 +(non-Windows) >(locale) + UCS-2 + (Windows) + + codecvt_base defines character conversion errors + \fI(class)\fP + represents the system-supplied std::codecvt for the named + codecvt_byname locale + \fI(class template)\fP + codecvt_utf8 + \fI(C++11)\fP converts between UTF-8 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf16 + \fI(C++11)\fP converts between UTF-16 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8_utf16 + \fI(C++11)\fP converts between UTF-8 and UTF-16 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::codecvt::always_noconv,do_always_noconv.3 b/man/std::codecvt::always_noconv,do_always_noconv.3 index 5452c839b..e1fc20f08 100644 --- a/man/std::codecvt::always_noconv,do_always_noconv.3 +++ b/man/std::codecvt::always_noconv,do_always_noconv.3 @@ -1,10 +1,17 @@ -.TH std::codecvt::always_noconv,do_always_noconv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::always_noconv,do_always_noconv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::always_noconv,do_always_noconv \- std::codecvt::always_noconv,do_always_noconv + .SH Synopsis Defined in header - public: \fB(1)\fP - bool always_noconv() const; - protected: \fB(2)\fP - bool do_always_noconv() const; + public: \fI(until C++11)\fP + bool always_noconv() const throw(); + public: \fI(since C++11)\fP + bool always_noconv() const noexcept; \fB(1)\fP + protected: \fI(until C++11)\fP + virtual bool do_always_noconv() const throw(); \fB(2)\fP + protected: \fI(since C++11)\fP + virtual bool do_always_noconv() const noexcept; 1) Public member function, calls the member function do_always_noconv of the most derived class. @@ -16,42 +23,34 @@ true if this conversion facet performs no conversions, false otherwise. The non-converting specialization std::codecvt returns - true + true. .SH Notes This function may be used e.g. in the implementation of - std::basic_filebuf::underflow to use bulk character copy instead of calling - std::codecvt::in if it is known that the locale imbued in the std::basic_filebuf - does not perform any conversions. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + std::basic_filebuf::underflow and std::basic_filebuf::overflow to use bulk character + copy instead of calling std::codecvt::in or std::codecvt::out if it is known that + the locale imbued in the std::basic_filebuf does not perform any conversions. .SH Example - + // Run this code - #include #include - + #include + int main() { std::cout << "The non-converting char<->char codecvt::always_noconv() returns " << std::boolalpha << std::use_facet>( std::locale() - ).always_noconv() << "\\n" + ).always_noconv() << '\\n' << "while wchar_t<->char codecvt::always_noconv() returns " << std::use_facet>( std::locale() - ).always_noconv() << "\\n"; - + ).always_noconv() << '\\n'; } .SH Output: diff --git a/man/std::codecvt::codecvt.3 b/man/std::codecvt::codecvt.3 index ecd900259..c55d567c8 100644 --- a/man/std::codecvt::codecvt.3 +++ b/man/std::codecvt::codecvt.3 @@ -1,10 +1,13 @@ -.TH std::codecvt::codecvt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::codecvt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::codecvt \- std::codecvt::codecvt + .SH Synopsis Defined in header explicit codecvt( std::size_t refs = 0 ); Creates a std::codecvt facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::codecvt::encoding,do_encoding.3 b/man/std::codecvt::encoding,do_encoding.3 index cd65aece1..f30dec060 100644 --- a/man/std::codecvt::encoding,do_encoding.3 +++ b/man/std::codecvt::encoding,do_encoding.3 @@ -1,14 +1,21 @@ -.TH std::codecvt::encoding,do_encoding 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::encoding,do_encoding 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::encoding,do_encoding \- std::codecvt::encoding,do_encoding + .SH Synopsis Defined in header - public: \fB(1)\fP - int encoding() const - protected: \fB(2)\fP - int do_encoding() const + public: \fI(until C++11)\fP + int encoding() const throw(); + public: \fI(since C++11)\fP + int encoding() const noexcept; \fB(1)\fP + protected: \fI(until C++11)\fP + virtual int do_encoding() const throw(); \fB(2)\fP + protected: \fI(since C++11)\fP + virtual int do_encoding() const noexcept; - 1) public member function, calls the member function do_encoding of the most derived + 1) Public member function, calls the member function do_encoding of the most derived class. - 2) if the encoding represented by this codecvt facet maps each internal character to + 2) If the encoding represented by this codecvt facet maps each internal character to the same, constant number of external characters, returns that number. If the encoding is variable-length (e.g. UTF-8 or UTF-16), returns 0. If the encoding is state-dependent, returns -1. @@ -18,52 +25,46 @@ The exact number of externT characters that correspond to one internT character, if constant. 0 if the number varies, -1 if the encoding is state-dependent. - The non-converting specialization std::codecvt returns 1 - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + The non-converting specialization std::codecvt returns + 1. .SH Example - + // Run this code - #include #include - + #include + int main() { std::cout << "en_US.utf8 is a variable-length encoding, encoding() returns " << std::use_facet>( - std::locale("en_US.utf8") - ).encoding() << '\\n'; - + std::locale("en_US.utf8") + ).encoding() << '\\n'; + std::cout << "zh_CN.gb18030 is also variable-length, encoding() == " << std::use_facet>( - std::locale("zh_CN.gb18030") - ).encoding() << '\\n'; - - std::cout << "ru_RU.koi8r is a single-byte encoding encoding() == " + std::locale("zh_CN.gb18030") + ).encoding() << '\\n'; + + std::cout << "ru_RU.koi8r is a single-byte encoding, encoding() == " << std::use_facet>( - std::locale("ru_RU.koi8r") - ).encoding() << '\\n'; + std::locale("ru_RU.koi8r") + ).encoding() << '\\n'; } .SH Output: en_US.utf8 is a variable-length encoding, encoding() returns 0 zh_CN.gb18030 is also variable-length, encoding() == 0 - ru_RU.koi8r is a single-byte encoding encoding() == 1 + ru_RU.koi8r is a single-byte encoding, encoding() == 1 .SH See also maximum number of bytes in a multibyte character in the current C MB_CUR_MAX locale - (macro variable) - do_max_length returns the maximum number of externT characters that could be - \fB[virtual]\fP converted into a single internT character - \fI(virtual protected member function)\fP + (macro variable) + do_max_length returns the maximum number of ExternT characters that could be + \fB[virtual]\fP converted into a single InternT character + \fI(virtual protected member function)\fP diff --git a/man/std::codecvt::in,std::codecvt::do_in.3 b/man/std::codecvt::in,std::codecvt::do_in.3 index 443ea1bea..c802c75f3 100644 --- a/man/std::codecvt::in,std::codecvt::do_in.3 +++ b/man/std::codecvt::in,std::codecvt::do_in.3 @@ -1,26 +1,29 @@ -.TH std::codecvt::in,std::codecvt::do_in 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::in,std::codecvt::do_in 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::in,std::codecvt::do_in \- std::codecvt::in,std::codecvt::do_in + .SH Synopsis Defined in header public: - result in( stateT& state, - const externT* from, - const externT* from_end, \fB(1)\fP - const externT*& from_next, - internT* to, - internT* to_end, + result in( StateT& state, + const ExternT* from, + const ExternT* from_end, \fB(1)\fP + const ExternT*& from_next, + InternT* to, + InternT* to_end, - internT*& to_next ) const; + InternT*& to_next ) const; protected: - result do_in( stateT& state, - const externT* from, - const externT* from_end, \fB(2)\fP - const externT*& from_next, - internT* to, - internT* to_end, + virtual result do_in( StateT& state, + const ExternT* from, + const ExternT* from_end, \fB(2)\fP + const ExternT*& from_next, + InternT* to, + InternT* to_end, - internT*& to_next ) const; + InternT*& to_next ) const; 1) Public member function, calls the member function do_in of the most derived class. @@ -34,6 +37,12 @@ to_next is set to be equal to to, state is unchanged, and std::codecvt_base::noconv is returned. + do_in(state, from, from_end, from_next, to, to + 1, to_next) must return ok if + + * this codecvt facet is used by basic_filebuf, and + * do_in(state, from, from_end, from_next, to, to_end, to_next) would return ok + where to != to_end. + .SH Return value A value of type std::codecvt_base::result, indicating the success status as follows: @@ -44,7 +53,7 @@ noconv this facet is non-converting, no output written The non-converting specialization std::codecvt always - returns std::codecvt_base::noconv + returns std::codecvt_base::noconv. .SH Notes @@ -60,20 +69,21 @@ .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::locale::global(std::locale("en_US.utf8")); - auto& f = std::use_facet>(std::locale()); - std::string external = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; - + auto const& f = std::use_facet> + (std::locale()); + std::string external = "z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b" + // note that the following can be done with wstring_convert std::mbstate_t mb = std::mbstate_t(); // initial shift state std::wstring internal(external.size(), '\\0'); @@ -83,7 +93,7 @@ &internal[0], &internal[internal.size()], to_next); // error checking skipped for brevity internal.resize(to_next - &internal[0]); - + std::wcout << L"The string in wide encoding: " << internal << '\\n'; } @@ -91,13 +101,26 @@ The string in wide encoding: zß水𝄋 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether the conversion is + LWG 76 C++98 required to only required if used + support producing one internal character at by basic_filebuf + a time + .SH See also underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP - from_bytes converts a byte string into a wide string - \fI(public member function of std::wstring_convert)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + converts a byte string into a wide string + from_bytes \fI\fI(public member\fP function of\fP + std::wstring_convert) mbsrtowcs converts a narrow multibyte character string to wide string, given state - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::codecvt::length,do_length.3 b/man/std::codecvt::length,do_length.3 index 70a96ecd0..ed6e4a890 100644 --- a/man/std::codecvt::length,do_length.3 +++ b/man/std::codecvt::length,do_length.3 @@ -1,58 +1,61 @@ -.TH std::codecvt::length,do_length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::length,do_length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::length,do_length \- std::codecvt::length,do_length + .SH Synopsis Defined in header public: - int length( StateT& state, - const ExternT* from, \fB(1)\fP - const ExternT* from_end, + int length( StateT& state, const ExternT* from, const ExternT* from_end, \fB(1)\fP - std::size_t max ) const + std::size_t max ) const; protected: - int do_length( StateT& state, - const ExternT* from, \fB(2)\fP - const ExternT* from_end, + virtual int do_length( StateT& state, const ExternT* from, const ExternT* \fB(2)\fP + from_end, - std::size_t max ) const + std::size_t max ) const; - 1) public member function, calls the member function do_length of the most derived + 1) Public member function, calls the member function do_length of the most derived class. - 2) attempts to convert the externT characters from the character array defined by - [from, from_end), given initial conversion state state, to at most max internT - characters, and returns the number of externT characters that such conversion would - consume. Modifies state as if by executing do_in(state, from, from_end, from, to, - to+max, to) for some imaginary [to, to+max) output buffer. + 2) Attempts to convert the ExternT characters from the character array defined by + [from, from_end), given initial conversion state state, to at most max InternT + characters, and returns the number of ExternT characters that such conversion would + consume. Modifies state as if by executing do_in(state, from, from_end, from, to, to + + max, to) for some imaginary [to, to + max) output buffer. .SH Return value - The number of externT characters that would be consumed if converted by do_in() - until either all from_end-from characters were consumed or max internT characters - were producer, or a conversion error occurred. + The number of ExternT characters that would be consumed if converted by do_in() + until either all from_end - from characters were consumed or max InternT characters + were produced, or a conversion error occurred. The non-converting specialization std::codecvt returns - std::min(max, from_end-from) + std::min(max, from_end - from). .SH Example - + // Run this code + #include #include #include - #include - + int main() { - // narrow multibyte encoding + using facet_type = std::codecvt; + + // narrow multibyte encoding std::string s = "z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b" + + std::setlocale(LC_ALL, "en_US.UTF-8"); + facet_type const& codecvt_facet = std::use_facet(std::locale()); std::mbstate_t mb = std::mbstate_t(); - std::cout << "Only the first " << - std::use_facet>( - std::locale("en_US.utf8") - ).length(mb, &s[0], &s[s.size()], 2) - << " bytes out of " << s.size() << " would be consumed " + std::cout << "Only the first " + << codecvt_facet.length(mb, s.data(), s.data() + s.size(), 2) + << " bytes out of " << s.size() << " would be consumed" " to produce the first 2 characters\\n"; } @@ -60,7 +63,19 @@ Only the first 3 bytes out of 10 would be consumed to produce the first 2 characters + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 75 C++98 the effect on state was not specified specified + std::codecvt::do_length not required + was required to return std::min(max, from_end - + from) + .SH See also - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::codecvt::max_length,do_max_length.3 b/man/std::codecvt::max_length,do_max_length.3 index bfdff50eb..23db4c88b 100644 --- a/man/std::codecvt::max_length,do_max_length.3 +++ b/man/std::codecvt::max_length,do_max_length.3 @@ -1,10 +1,17 @@ -.TH std::codecvt::max_length,do_max_length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::max_length,do_max_length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::max_length,do_max_length \- std::codecvt::max_length,do_max_length + .SH Synopsis Defined in header - public: \fB(1)\fP - int max_length() const - protected: \fB(2)\fP - int do_max_length() const + public: \fI(until C++11)\fP + int max_length() const throw(); + public: \fI(since C++11)\fP + int max_length() const noexcept; \fB(1)\fP + protected: \fI(until C++11)\fP + virtual int do_max_length() const throw(); \fB(2)\fP + protected: \fI(since C++11)\fP + virtual int do_max_length() const noexcept; 1) Public member function, calls the member function do_max_length of the most derived class. @@ -16,48 +23,42 @@ The maximum number of ExternT characters that could be consumed if converted by in() to produce one InternT character. - The non-converting specialization std::codecvt returns 1 + The non-converting specialization std::codecvt returns + 1. .SH Notes If the encoding is state-dependent (encoding() == -1), then more than max_length() - external characters may be consumed to produce one internal character - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + external characters may be consumed to produce one internal character. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { std::cout << "In codecvt_utf8, the longest multibyte character is " << std::codecvt_utf8().max_length() << " bytes long\\n"; - + std::cout << "In header-consuming codecvt_utf8, the longest multibyte character is " << std::codecvt_utf8().max_length() << " bytes long\\n"; - + std::cout << "In this system's en_US.utf8, the longest multibyte character is " << std::use_facet>( - std::locale("en_US.utf8") - ).max_length() << " bytes long\\n"; - + std::locale("en_US.utf8") + ).max_length() << " bytes long\\n"; + std::cout << "In this system's zh_CN.gb18030, the longest multibyte character is " << std::use_facet>( - std::locale("zh_CN.gb18030") - ).max_length() << " bytes long\\n"; + std::locale("zh_CN.gb18030") + ).max_length() << " bytes long\\n"; } .SH Output: @@ -70,7 +71,7 @@ .SH See also MB_CUR_MAX maximum number of bytes in a multibyte character in the current C locale - (macro variable) - do_encoding returns the number of externT characters necessary to produce one - \fB[virtual]\fP internT character, if constant - \fI(virtual protected member function)\fP + (macro variable) + do_encoding returns the number of ExternT characters necessary to produce one + \fB[virtual]\fP InternT character, if constant + \fI(virtual protected member function)\fP diff --git a/man/std::codecvt::out,do_out.3 b/man/std::codecvt::out,do_out.3 index 41d7e027a..e3d6f0d85 100644 --- a/man/std::codecvt::out,do_out.3 +++ b/man/std::codecvt::out,do_out.3 @@ -1,11 +1,14 @@ -.TH std::codecvt::out,do_out 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::out,do_out 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::out,do_out \- std::codecvt::out,do_out + .SH Synopsis Defined in header public: result out( StateT& state, const InternT* from, - const InternT* from_end, \fB(1)\fP + const InternT* from_end, \fB(1)\fP const InternT*& from_next, ExternT* to, ExternT* to_end, @@ -13,16 +16,16 @@ ExternT*& to_next ) const; protected: - result do_out( StateT& state, - const InternT* from, - const InternT* from_end, \fB(2)\fP - const InternT*& from_next, - ExternT* to, - ExternT* to_end, + virtual result do_out( StateT& state, + const InternT* from, + const InternT* from_end, \fB(2)\fP + const InternT*& from_next, + ExternT* to, + ExternT* to_end, - ExternT*& to_next ) const; + ExternT*& to_next ) const; - 1) public member function, calls the member function do_out of the most derived + 1) Public member function, calls the member function do_out of the most derived class. 2) If this codecvt facet defines a conversion, translates the internal characters from the source range [from, from_end) to external characters, placing the results @@ -34,6 +37,12 @@ to_next is set to be equal to to, state is unchanged, and std::codecvt_base::noconv is returned. + do_out(state, from, from + 1, from_next, to, to_end, to_next) must return ok if + + * this codecvt facet is used by basic_filebuf, and + * do_out(state, from, from_end, from_next, to, to_end, to_next) would return ok + where from != from_end. + .SH Return value A value of type std::codecvt_base::result, indicating the success status as follows: @@ -44,7 +53,7 @@ noconv this facet is non-converting, no output written The non-converting specialization std::codecvt always - returns std::codecvt_base::noconv + returns std::codecvt_base::noconv. .SH Notes @@ -71,21 +80,21 @@ .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::locale::global(std::locale("en_US.utf8")); auto& f = std::use_facet>(std::locale()); - std::wstring internal = L"z\\u00df\\u6c34\\U0001d10b"; // L"zß水𝄋" - + std::wstring internal = L"z\\u00df\\u6c34\\U0001f34c"; // L"zß水🍌" + // note that the following can be done with wstring_convert - std::mbstate_t mb = std::mbstate_t(); // initial shift state + std::mbstate_t mb{}; // initial shift state std::string external(internal.size() * f.max_length(), '\\0'); const wchar_t* from_next; char* to_next; @@ -93,21 +102,34 @@ &external[0], &external[external.size()], to_next); // error checking skipped for brevity external.resize(to_next - &external[0]); - + std::cout << "The string in narrow multibyte encoding: " << external << '\\n'; } .SH Output: - The string in narrow multibyte encoding: zß水𝄋 + The string in narrow multibyte encoding: zß水🍌 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether the conversion is + LWG 76 C++98 required only required if used + to support taking one internal character at by basic_filebuf + a time .SH See also overflow writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP - to_bytes converts a wide string into a byte string - \fI(public member function of std::wstring_convert)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + converts a wide string into a byte string + to_bytes \fI\fI(public member\fP function of\fP + std::wstring_convert) wcsrtombs converts a wide string to narrow multibyte character string, given state - \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::codecvt::unshift,do_unshift.3 b/man/std::codecvt::unshift,do_unshift.3 index e92e8403c..3f330da48 100644 --- a/man/std::codecvt::unshift,do_unshift.3 +++ b/man/std::codecvt::unshift,do_unshift.3 @@ -1,29 +1,28 @@ -.TH std::codecvt::unshift,do_unshift 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::unshift,do_unshift 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::unshift,do_unshift \- std::codecvt::unshift,do_unshift + .SH Synopsis Defined in header public: - result unshift( StateT& state, - ExternT* to, \fB(1)\fP - ExternT* to_end, + result unshift( StateT& state, ExternT* to, ExternT* to_end, \fB(1)\fP - ExternT*& to_next) const + ExternT*& to_next ) const; protected: - result do_unshift( StateT& state, - ExternT* to, \fB(2)\fP - ExternT* to_end, + virtual result do_unshift( StateT& state, ExternT* to, ExternT* to_end, \fB(2)\fP - ExternT*& to_next) const + ExternT*& to_next ) const; - 1) public member function, calls the member function do_unshift of the most derived + 1) Public member function, calls the member function do_unshift of the most derived class. - 2) if the encoding represented by this codecvt facet is state-dependent, and state + 2) If the encoding represented by this codecvt facet is state-dependent, and state represents a conversion state that is not the initial shift state, writes the characters necessary to return to the initial shift state. The characters are written to a character array whose first element is pointed to by to. No more than - to_end-to characters are written. The parameter to_next is updated to point one past - the last character written. + to_end - to characters are written. The parameter to_next is updated to point one + past the last character written. .SH Return value @@ -32,12 +31,9 @@ ok all necessary characters were written. state now represents initial shift state partial not enough space in the output buffer. to_next == to_end - error unspecified error occurred + error an unspecified error has occurred noconv the encoding is not state-dependent, no termination sequence necessary - The non-converting specialization std::codecvt always - returns std::codecvt_base::noconv - .SH Notes This function is called by std::basic_filebuf::close() and in other situations when @@ -48,13 +44,36 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::codecvt::do_unshift not required + was required not to write any character + the meaning of returning partial was 'more corrected to + LWG 380 C++98 characters need to indicating + be supplied to complete termination', but no insufficient buffer + character is supplied space + state is required to + LWG 381 C++98 state was not required to be valid, and be valid, and + error is returned if state is invalid returning error + indicates an error + std::codecvt::do_unshift not required + was required not to write any character + std::codecvt::do_unshift not required + was required to return noconv + .SH See also wcrtomb converts a wide character to its multibyte representation, given state - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Category: - * Todo no example diff --git a/man/std::codecvt::~codecvt.3 b/man/std::codecvt::~codecvt.3 index 7a8f1ee79..1fb4bdc83 100644 --- a/man/std::codecvt::~codecvt.3 +++ b/man/std::codecvt::~codecvt.3 @@ -1,4 +1,7 @@ -.TH std::codecvt::~codecvt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt::~codecvt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt::~codecvt \- std::codecvt::~codecvt + .SH Synopsis Defined in header protected: ~codecvt(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include - struct Destructible_codecvt : public std::codecvt + + struct Destructible_codecvt : public std::codecvt { Destructible_codecvt(std::size_t refs = 0) : codecvt(refs) {} - ~Destructible_codecvt() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_codecvt dc; - // std::codecvt c; // compile error: protected destructor + // std::codecvt c; // compile error: protected destructor } diff --git a/man/std::codecvt_base.3 b/man/std::codecvt_base.3 index 528b22926..79697b7ec 100644 --- a/man/std::codecvt_base.3 +++ b/man/std::codecvt_base.3 @@ -1,4 +1,7 @@ -.TH std::codecvt_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt_base \- std::codecvt_base + .SH Synopsis Defined in header class codecvt_base; @@ -26,4 +29,4 @@ .SH See also codecvt converts between character encodings, including UTF-8, UTF-16, UTF-32 - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::codecvt_byname.3 b/man/std::codecvt_byname.3 index 0d12eb71f..097e40d98 100644 --- a/man/std::codecvt_byname.3 +++ b/man/std::codecvt_byname.3 @@ -1,4 +1,7 @@ -.TH std::codecvt_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt_byname \- std::codecvt_byname + .SH Synopsis Defined in header template< class InternT, class ExternT, class State > @@ -7,28 +10,34 @@ std::codecvt_byname is a std::codecvt facet which encapsulates multibyte/wide character conversion rules of a locale specified at its construction. - Four specializations are provided by the standard library +.SH Specializations + + The standard library is guaranteed to provide the following specializations: Defined in header - std::codecvt_byname - std::codecvt_byname C++11) - std::codecvt_byname C++11) - std::codecvt_byname and narrow, possibly multibyte, string + std::codecvt_byname C++11)(deprecated in C++20) + std::codecvt_byname C++20) + std::codecvt_byname C++11)(deprecated in C++20) + std::codecvt_byname C++20) + std::codecvt_byname string and narrow character sets .SH Member functions constructor constructs a new codecvt_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a codecvt_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP + - - std::codecvt_byname::codecvt_byname +std::codecvt_byname::codecvt_byname explicit codecvt_byname( const char* name, std::size_t refs = 0 ); explicit codecvt_byname( const std::string& name, std::size_t refs = \fI(since C++11)\fP @@ -45,9 +54,9 @@ name - the name of the locale refs - the number of references that link to the facet - - std::codecvt_byname::~codecvt_byname + +std::codecvt_byname::~codecvt_byname protected: ~codecvt_byname(); @@ -58,7 +67,7 @@ Inherited from std::codecvt .SH Member types - Member type Definition + Member name Definition intern_type internT extern_type externT state_type stateT @@ -70,44 +79,58 @@ Inherited from std::codecvt .SH Member functions - out invokes do_out - \fI(public member function of std::codecvt)\fP - in invokes do_in - \fI(public member function of std::codecvt)\fP - unshift invokes do_unshift - \fI(public member function of std::codecvt)\fP - encoding invokes do_encoding - \fI(public member function of std::codecvt)\fP - always_noconv invokes do_always_noconv - \fI(public member function of std::codecvt)\fP - length invokes do_length - \fI(public member function of std::codecvt)\fP - max_length invokes do_max_length - \fI(public member function of std::codecvt)\fP + invokes do_out + out \fI(public member function of std::codecvt)\fP + + invokes do_in + in \fI(public member function of std::codecvt)\fP + + invokes do_unshift + unshift \fI(public member function of std::codecvt)\fP + + invokes do_encoding + encoding \fI(public member function of std::codecvt)\fP + + invokes do_always_noconv + always_noconv \fI(public member function of std::codecvt)\fP + + invokes do_length + length \fI(public member function of std::codecvt)\fP + + invokes do_max_length + max_length \fI(public member function of std::codecvt)\fP + .SH Protected member functions - do_out converts a string from internT to externT, such as when writing to - \fB[virtual]\fP file - \fI(virtual protected member function of std::codecvt)\fP - do_in converts a string from externT to internT, such as when reading - \fB[virtual]\fP from file - \fI(virtual protected member function of std::codecvt)\fP - do_unshift generates the termination character sequence of externT characters - \fB[virtual]\fP for incomplete conversion - \fI(virtual protected member function of std::codecvt)\fP - do_encoding returns the number of externT characters necessary to produce one - \fB[virtual]\fP internT character, if constant - \fI(virtual protected member function of std::codecvt)\fP - do_always_noconv tests if the facet encodes an identity conversion for all valid - \fB[virtual]\fP argument values - \fI(virtual protected member function of std::codecvt)\fP - do_length calculates the length of the externT string that would be consumed - \fB[virtual]\fP by conversion into given internT buffer - \fI(virtual protected member function of std::codecvt)\fP - do_max_length returns the maximum number of externT characters that could be - \fB[virtual]\fP converted into a single internT character - \fI(virtual protected member function of std::codecvt)\fP + converts a string from InternT to ExternT, such as when writing to + do_out file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + converts a string from ExternT to InternT, such as when reading + do_in from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + generates the termination character sequence of ExternT characters + do_unshift for incomplete conversion + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the number of ExternT characters necessary to produce one + do_encoding InternT character, if constant + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + tests if the facet encodes an identity conversion for all valid + do_always_noconv argument values + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + calculates the length of the ExternT string that would be consumed + do_length by conversion into given InternT buffer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the maximum number of ExternT characters that could be + do_max_length converted into a single InternT character + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) Inherited from std::codecvt_base @@ -123,16 +146,16 @@ Inherited from std::codecvt_base .SH Example This example demonstrates reading a GB18030-encoded file using the codecvt facet - from a GB18030-aware locale + from a GB18030-aware locale. + - // Run this code - #include #include - #include + #include #include - + #include + int main() { // GB18030 narrow multibyte encoding @@ -140,21 +163,33 @@ Inherited from std::codecvt_base "\\x81\\x30\\x89\\x38" // letter 'ß', U+00df "\\xcb\\xae" // CJK ideogram '水' (water), U+6c34 "\\x94\\x32\\xbc\\x35"; // musical sign '𝄋' (segno), U+1d10b + std::wifstream fin("text.txt"); fin.imbue(std::locale(fin.getloc(), new std::codecvt_byname("zh_CN.gb18030"))); - for (wchar_t c; fin.get(c); ) - std::cout << std::hex << std::showbase << c << '\\n'; + + for (wchar_t c; fin.get(c);) + std::cout << std::hex << std::showbase << static_cast(c) << '\\n'; } -.SH Output: +.SH Possible output: 0x7a 0xdf 0x6c34 0x1d10b + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the standard library did not need to two specializations are + LWG 21 C++98 provide required + any std::codecvt_byname specializations + .SH See also codecvt converts between character encodings, including UTF-8, UTF-16, UTF-32 - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::codecvt_mode.3 b/man/std::codecvt_mode.3 index 70ec09044..753468ce3 100644 --- a/man/std::codecvt_mode.3 +++ b/man/std::codecvt_mode.3 @@ -1,11 +1,14 @@ -.TH std::codecvt_mode 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt_mode 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt_mode \- std::codecvt_mode + .SH Synopsis - Defined in header + Defined in header enum codecvt_mode { - consume_header = 4, - generate_header = 2, - little_endian = 1 + consume_header = 4, \fI(since C++11)\fP + generate_header = 2, (deprecated in C++17) + little_endian = 1 (removed in C++26) }; @@ -36,27 +39,30 @@ .SH Example - The following example demonstrates consuming the UTF-8 BOM + The following example demonstrates consuming the UTF-8 BOM: + - // Run this code + #include + #include #include #include - #include #include - #include - + #include + int main() { // UTF-8 data with BOM - std::ofstream("text.txt") << u8"\\ufeffz\\u6c34\\U0001d10b"; - // read the UTF8 file, skipping the BOM - std::wifstream fin("text.txt"); + std::ofstream{"text.txt"} << "\\ufeffz\\u6c34\\U0001d10b"; + + // read the UTF-8 file, skipping the BOM + std::wifstream fin{"text.txt"}; fin.imbue(std::locale(fin.getloc(), new std::codecvt_utf8)); - for (wchar_t c; fin.get(c); ) - std::cout << std::hex << std::showbase << c << '\\n'; + + for (wchar_t c; fin.get(c);) + std::cout << std::hex << std::showbase << (std::wint_t)c << '\\n'; } .SH Output: @@ -67,12 +73,18 @@ .SH See also - converts between character encodings, including UTF-8, UTF-16, - codecvt UTF-32 - \fI(class template)\fP - codecvt_utf8 converts between UTF-8 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf16 converts between UTF-16 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8_utf16 converts between UTF-8 and UTF-16 - \fI(C++11)\fP \fI(class template)\fP + converts between character encodings, including UTF-8, UTF-16, + codecvt UTF-32 + \fI(class template)\fP + codecvt_utf8 + \fI(C++11)\fP converts between UTF-8 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf16 + \fI(C++11)\fP converts between UTF-16 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8_utf16 + \fI(C++11)\fP converts between UTF-8 and UTF-16 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::codecvt_utf16.3 b/man/std::codecvt_utf16.3 index c3b7cbc84..c0a14fa54 100644 --- a/man/std::codecvt_utf16.3 +++ b/man/std::codecvt_utf16.3 @@ -1,17 +1,25 @@ -.TH std::codecvt_utf16 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt_utf16 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt_utf16 \- std::codecvt_utf16 + .SH Synopsis Defined in header - template< class Elem, + template< - unsigned long Maxcode = 0x10ffff, - std::codecvt_mode Mode = (std::codecvt_mode)0 > + class Elem, \fI(since C++11)\fP + unsigned long Maxcode = 0x10ffff, (deprecated in C++17) + std::codecvt_mode Mode = (std::codecvt_mode)0 > (removed in C++26) + class codecvt_utf16 - class codecvt_utf16 : public std::codecvt;; + : public std::codecvt; std::codecvt_utf16 is a std::codecvt facet which encapsulates conversion between a - UTF-16 encoded byte string and UCS2 or UCS4 character string (depending on the type - of Elem). This codecvt facet can be used to read and write UTF-16 files in binary - mode. + UTF-16 encoded byte string and UCS-2 or UTF-32 character string (depending on the + type of Elem). This std::codecvt facet can be used to read and write UTF-16 files in + binary mode. + + UCS-2 is the same encoding as UTF-16, except that it encodes scalar (since C++23) + values in the range U+0000-U+FFFF (Basic Multilingual Plane) only. .SH Template Parameters @@ -26,7 +34,7 @@ destructor destroys a codecvt_utf16 facet \fI(public member function)\fP - std::codecvt_utf16::codecvt_utf16 +std::codecvt_utf16::codecvt_utf16 explicit codecvt_utf16( std::size_t refs = 0 ); @@ -37,7 +45,7 @@ refs - the number of references that link to the facet - std::codecvt_utf16::~codecvt_utf16 +std::codecvt_utf16::~codecvt_utf16 ~codecvt_utf16(); @@ -48,7 +56,7 @@ Inherited from std::codecvt .SH Member types - Member type Definition + Member name Definition intern_type internT extern_type externT state_type stateT @@ -60,44 +68,58 @@ Inherited from std::codecvt .SH Member functions - out invokes do_out - \fI(public member function of std::codecvt)\fP - in invokes do_in - \fI(public member function of std::codecvt)\fP - unshift invokes do_unshift - \fI(public member function of std::codecvt)\fP - encoding invokes do_encoding - \fI(public member function of std::codecvt)\fP - always_noconv invokes do_always_noconv - \fI(public member function of std::codecvt)\fP - length invokes do_length - \fI(public member function of std::codecvt)\fP - max_length invokes do_max_length - \fI(public member function of std::codecvt)\fP + invokes do_out + out \fI(public member function of std::codecvt)\fP + + invokes do_in + in \fI(public member function of std::codecvt)\fP + + invokes do_unshift + unshift \fI(public member function of std::codecvt)\fP + + invokes do_encoding + encoding \fI(public member function of std::codecvt)\fP + + invokes do_always_noconv + always_noconv \fI(public member function of std::codecvt)\fP + + invokes do_length + length \fI(public member function of std::codecvt)\fP + + invokes do_max_length + max_length \fI(public member function of std::codecvt)\fP + .SH Protected member functions - do_out converts a string from internT to externT, such as when writing to - \fB[virtual]\fP file - \fI(virtual protected member function of std::codecvt)\fP - do_in converts a string from externT to internT, such as when reading - \fB[virtual]\fP from file - \fI(virtual protected member function of std::codecvt)\fP - do_unshift generates the termination character sequence of externT characters - \fB[virtual]\fP for incomplete conversion - \fI(virtual protected member function of std::codecvt)\fP - do_encoding returns the number of externT characters necessary to produce one - \fB[virtual]\fP internT character, if constant - \fI(virtual protected member function of std::codecvt)\fP - do_always_noconv tests if the facet encodes an identity conversion for all valid - \fB[virtual]\fP argument values - \fI(virtual protected member function of std::codecvt)\fP - do_length calculates the length of the externT string that would be consumed - \fB[virtual]\fP by conversion into given internT buffer - \fI(virtual protected member function of std::codecvt)\fP - do_max_length returns the maximum number of externT characters that could be - \fB[virtual]\fP converted into a single internT character - \fI(virtual protected member function of std::codecvt)\fP + converts a string from InternT to ExternT, such as when writing to + do_out file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + converts a string from ExternT to InternT, such as when reading + do_in from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + generates the termination character sequence of ExternT characters + do_unshift for incomplete conversion + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the number of ExternT characters necessary to produce one + do_encoding InternT character, if constant + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + tests if the facet encodes an identity conversion for all valid + do_always_noconv argument values + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + calculates the length of the ExternT string that would be consumed + do_length by conversion into given InternT buffer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the maximum number of ExternT characters that could be + do_max_length converted into a single InternT character + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) Inherited from std::codecvt_base @@ -110,32 +132,43 @@ Inherited from std::codecvt_base error encountered an invalid character noconv no conversion required, input and output types are the same +.SH Notes + + Although the standard requires that this facet works with UCS-2 when the size of + Elem is 16 bits, some implementations use UTF-16 instead, making this a + non-converting locale. The term "UCS-2" was deprecated and removed from ISO 10646. + + Since C++23, UCS-2 does not refer to its original definition anymore. It becomes a + synonym of UTF-16, but with a smaller encoding range. + .SH Example The following example demonstrates decoding of UTF-16le file on a system with 32-bit wchar_t. On a system with 16-bit wchar_t, decoding of the third character will fail - because std::codecvt_utf16 produces UCS2, not UTF-16. + because std::codecvt_utf16 produces UCS-2, not UTF-16. + - // Run this code + #include + #include #include #include - #include #include - #include - + #include + void prepare_file() { // UTF-16le data (if host system is little-endian) - char16_t utf16le[4] ={0x007a, // latin small letter 'z' U+007a - 0x6c34, // CJK ideograph "water" U+6c34 - 0xd834, 0xdd0b}; // musical sign segno U+1d10b + char16_t utf16le[4] = {0x007a, // latin small letter 'z' U+007a + 0x6c34, // CJK ideograph "water" U+6c34 + 0xd834, 0xdd0b}; // musical sign segno U+1d10b + // store in a file std::ofstream fout("text.txt"); - fout.write( reinterpret_cast(utf16le), sizeof utf16le); + fout.write(reinterpret_cast(utf16le), sizeof utf16le); } - + int main() { prepare_file(); @@ -143,10 +176,11 @@ Inherited from std::codecvt_base std::wifstream fin("text.txt", std::ios::binary); // apply facet fin.imbue(std::locale(fin.getloc(), - new std::codecvt_utf16)); - - for (wchar_t c; fin.get(c); ) - std::cout << std::showbase << std::hex << c << '\\n'; + new std::codecvt_utf16)); + + wchar_t c = 0; + for (std::cout << std::showbase << std::hex; fin.get(c); + std::cout << static_cast(c) << '\\n'); } .SH Output: @@ -157,30 +191,35 @@ Inherited from std::codecvt_base .SH See also - Character narrow multibyte UTF-8 UTF-16 - conversions (char) (char) (char16_t) - codecvt - UTF-16 c16rtomb codecvt_utf8_utf16 N/A - codecvt_utf8_utf16 - codecvt_utf8_utf16 - UCS2 No codecvt_utf8 codecvt_utf16 - UTF-32/UCS4 mbrtoc32 / codecvt codecvt_utf16 - codecvt_utf8 - UCS2/UCS4 No codecvt_utf8 codecvt_utf16 - (wchar_t) - codecvt No No - (wchar_t) mbsrtowcs / - wcsrtombs - - converts between character encodings, including UTF-8, UTF-16, - codecvt UTF-32 - \fI(class template)\fP - codecvt_mode tags to alter behavior of the standard codecvt facets - \fI(C++11)\fP \fI(enum)\fP - codecvt_utf8 converts between UTF-8 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8_utf16 converts between UTF-8 and UTF-16 - \fI(C++11)\fP \fI(class template)\fP + Character locale-defined multibyte UTF-8 UTF-16 + conversions (UTF-8, GB18030) + codecvt + UTF-16 mbrtoc16 / c16rtomb (with C11's codecvt_utf8_utf16 N/A + DR488) codecvt_utf8_utf16 + codecvt_utf8_utf16 + UCS-2 c16rtomb (without C11's DR488) codecvt_utf8 codecvt_utf16 + UTF-32 mbrtoc32 / c32rtomb codecvt codecvt_utf16 + codecvt_utf8 + system + wchar_t: + mbsrtowcs / wcsrtombs + UTF-32 use_facet codecvt_utf16 +(non-Windows) >(locale) + UCS-2 + (Windows) + + converts between character encodings, including UTF-8, UTF-16, + codecvt UTF-32 + \fI(class template)\fP + codecvt_mode + \fI(C++11)\fP tags to alter behavior of the standard codecvt facets + (deprecated in C++17) \fI(enum)\fP + (removed in C++26) + codecvt_utf8 + \fI(C++11)\fP converts between UTF-8 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8_utf16 + \fI(C++11)\fP converts between UTF-8 and UTF-16 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::codecvt_utf8.3 b/man/std::codecvt_utf8.3 index 1b57a2b16..15def6761 100644 --- a/man/std::codecvt_utf8.3 +++ b/man/std::codecvt_utf8.3 @@ -1,18 +1,25 @@ -.TH std::codecvt_utf8 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt_utf8 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt_utf8 \- std::codecvt_utf8 + .SH Synopsis Defined in header template< - class Elem, - unsigned long Maxcode = 0x10ffff, - std::codecvt_mode Mode = (std::codecvt_mode)0 + class Elem, \fI(since C++11)\fP + unsigned long Maxcode = 0x10ffff, (deprecated in C++17) + std::codecvt_mode Mode = (std::codecvt_mode)0 > (removed in C++26) + class codecvt_utf8 - > class codecvt_utf8 : public std::codecvt; + : public std::codecvt; std::codecvt_utf8 is a std::codecvt facet which encapsulates conversion between a - UTF-8 encoded byte string and UCS2 or UCS4 character string (depending on the type - of Elem). This codecvt facet can be used to read and write UTF-8 files, both text - and binary. + UTF-8 encoded byte string and UCS-2 or UTF-32 character string (depending on the + type of Elem). This std::codecvt facet can be used to read and write UTF-8 files, + both text and binary. + + UCS-2 is the same encoding as UTF-16, except that it encodes scalar (since C++23) + values in the range U+0000-U+FFFF (Basic Multilingual Plane) only. .SH Template Parameters @@ -27,7 +34,7 @@ destructor destroys a codecvt_utf8 facet \fI(public member function)\fP - std::codecvt_utf8::codecvt_utf8 +std::codecvt_utf8::codecvt_utf8 explicit codecvt_utf8( std::size_t refs = 0 ); @@ -38,7 +45,7 @@ refs - the number of references that link to the facet - std::codecvt_utf8::~codecvt_utf8 +std::codecvt_utf8::~codecvt_utf8 ~codecvt_utf8(); @@ -49,7 +56,7 @@ Inherited from std::codecvt .SH Member types - Member type Definition + Member name Definition intern_type internT extern_type externT state_type stateT @@ -61,44 +68,58 @@ Inherited from std::codecvt .SH Member functions - out invokes do_out - \fI(public member function of std::codecvt)\fP - in invokes do_in - \fI(public member function of std::codecvt)\fP - unshift invokes do_unshift - \fI(public member function of std::codecvt)\fP - encoding invokes do_encoding - \fI(public member function of std::codecvt)\fP - always_noconv invokes do_always_noconv - \fI(public member function of std::codecvt)\fP - length invokes do_length - \fI(public member function of std::codecvt)\fP - max_length invokes do_max_length - \fI(public member function of std::codecvt)\fP + invokes do_out + out \fI(public member function of std::codecvt)\fP + + invokes do_in + in \fI(public member function of std::codecvt)\fP + + invokes do_unshift + unshift \fI(public member function of std::codecvt)\fP + + invokes do_encoding + encoding \fI(public member function of std::codecvt)\fP + + invokes do_always_noconv + always_noconv \fI(public member function of std::codecvt)\fP + + invokes do_length + length \fI(public member function of std::codecvt)\fP + + invokes do_max_length + max_length \fI(public member function of std::codecvt)\fP + .SH Protected member functions - do_out converts a string from internT to externT, such as when writing to - \fB[virtual]\fP file - \fI(virtual protected member function of std::codecvt)\fP - do_in converts a string from externT to internT, such as when reading - \fB[virtual]\fP from file - \fI(virtual protected member function of std::codecvt)\fP - do_unshift generates the termination character sequence of externT characters - \fB[virtual]\fP for incomplete conversion - \fI(virtual protected member function of std::codecvt)\fP - do_encoding returns the number of externT characters necessary to produce one - \fB[virtual]\fP internT character, if constant - \fI(virtual protected member function of std::codecvt)\fP - do_always_noconv tests if the facet encodes an identity conversion for all valid - \fB[virtual]\fP argument values - \fI(virtual protected member function of std::codecvt)\fP - do_length calculates the length of the externT string that would be consumed - \fB[virtual]\fP by conversion into given internT buffer - \fI(virtual protected member function of std::codecvt)\fP - do_max_length returns the maximum number of externT characters that could be - \fB[virtual]\fP converted into a single internT character - \fI(virtual protected member function of std::codecvt)\fP + converts a string from InternT to ExternT, such as when writing to + do_out file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + converts a string from ExternT to InternT, such as when reading + do_in from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + generates the termination character sequence of ExternT characters + do_unshift for incomplete conversion + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the number of ExternT characters necessary to produce one + do_encoding InternT character, if constant + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + tests if the facet encodes an identity conversion for all valid + do_always_noconv argument values + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + calculates the length of the ExternT string that would be consumed + do_length by conversion into given InternT buffer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the maximum number of ExternT characters that could be + do_max_length converted into a single InternT character + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) Inherited from std::codecvt_base @@ -111,81 +132,98 @@ Inherited from std::codecvt_base error encountered an invalid character noconv no conversion required, input and output types are the same +.SH Notes + + Although the standard requires that this facet works with UCS-2 when the size of + Elem is 16 bits, some implementations use UTF-16 instead. The term "UCS-2" was + deprecated and removed from ISO 10646. + + Since C++23, UCS-2 does not refer to its original definition anymore. It becomes a + synonym of UTF-16, but with a smaller encoding range. + .SH Example - The following example demonstrates the difference between UCS2/UTF-8 and - UTF-16/UTF-8 conversions: the third character in the string is not a valid UCS2 + The following example demonstrates the difference between UCS-2/UTF-8 and + UTF-16/UTF-8 conversions: the third character in the string is not a valid UCS-2 character. - + // Run this code + #include + #include #include - #include #include - #include - + #include + int main() { - // UTF-8 data. The character U+1d10b, musical sign segno, does not fit in UCS2 - std::string utf8 = u8"z\\u6c34\\U0001d10b"; - + // UTF-8 data. The character U+1d10b, musical sign segno, does not fit in UCS-2 + std::string utf8 = "z\\u6c34\\U0001d10b"; + // the UTF-8 / UTF-16 standard conversion facet std::wstring_convert, char16_t> utf16conv; std::u16string utf16 = utf16conv.from_bytes(utf8); - std::cout << "UTF16 conversion produced " << utf16.size() << " code points:\\n"; + std::cout << "UTF-16 conversion produced " << utf16.size() << " code units:\\n" + << std::showbase << std::hex; for (char16_t c : utf16) - std::cout << std::hex << std::showbase << c << '\\n'; - - // the UTF-8 / UCS2 standard conversion facet + std::cout << static_cast(c) << ' '; + + // the UTF-8 / UCS-2 standard conversion facet std::wstring_convert, char16_t> ucs2conv; - try { + try + { std::u16string ucs2 = ucs2conv.from_bytes(utf8); - } catch(const std::range_error& e) { + } + catch(const std::range_error& e) + { std::u16string ucs2 = ucs2conv.from_bytes(utf8.substr(0, ucs2conv.converted())); - std::cout << "UCS2 failed after producing " << std::dec << ucs2.size()<<" characters:\\n"; + std::cout << "\\nUCS-2 failed after producing " << std::dec << ucs2.size() + << " characters:\\n" << std::showbase << std::hex; for (char16_t c : ucs2) - std::cout << std::hex << std::showbase << c << '\\n'; + std::cout << static_cast(c) << ' '; + std::cout << '\\n'; } } .SH Output: - UTF16 conversion produced 4 code points: - 0x7a - 0x6c34 - 0xd834 - 0xdd0b - UCS2 failed after producing 2 characters: - 0x7a - 0x6c34 + UTF-16 conversion produced 4 code units: + 0x7a 0x6c34 0xd834 0xdd0b + UCS-2 failed after producing 2 characters: + 0x7a 0x6c34 .SH See also - Character narrow multibyte UTF-8 UTF-16 - conversions (char) (char) (char16_t) - codecvt - UTF-16 c16rtomb codecvt_utf8_utf16 N/A - codecvt_utf8_utf16 - codecvt_utf8_utf16 - UCS2 No codecvt_utf8 codecvt_utf16 - UTF-32/UCS4 mbrtoc32 / codecvt codecvt_utf16 - codecvt_utf8 - UCS2/UCS4 No codecvt_utf8 codecvt_utf16 - (wchar_t) - codecvt No No - (wchar_t) mbsrtowcs / - wcsrtombs - - converts between character encodings, including UTF-8, UTF-16, - codecvt UTF-32 - \fI(class template)\fP - codecvt_mode tags to alter behavior of the standard codecvt facets - \fI(C++11)\fP \fI(enum)\fP - codecvt_utf16 converts between UTF-16 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8_utf16 converts between UTF-8 and UTF-16 - \fI(C++11)\fP \fI(class template)\fP + Character locale-defined multibyte UTF-8 UTF-16 + conversions (UTF-8, GB18030) + codecvt + UTF-16 mbrtoc16 / c16rtomb (with C11's codecvt_utf8_utf16 N/A + DR488) codecvt_utf8_utf16 + codecvt_utf8_utf16 + UCS-2 c16rtomb (without C11's DR488) codecvt_utf8 codecvt_utf16 + UTF-32 mbrtoc32 / c32rtomb codecvt codecvt_utf16 + codecvt_utf8 + system + wchar_t: + mbsrtowcs / wcsrtombs + UTF-32 use_facet codecvt_utf16 +(non-Windows) >(locale) + UCS-2 + (Windows) + + converts between character encodings, including UTF-8, UTF-16, + codecvt UTF-32 + \fI(class template)\fP + codecvt_mode + \fI(C++11)\fP tags to alter behavior of the standard codecvt facets + (deprecated in C++17) \fI(enum)\fP + (removed in C++26) + codecvt_utf16 + \fI(C++11)\fP converts between UTF-16 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8_utf16 + \fI(C++11)\fP converts between UTF-8 and UTF-16 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::codecvt_utf8_utf16.3 b/man/std::codecvt_utf8_utf16.3 index 04f81b076..99b9f1d7e 100644 --- a/man/std::codecvt_utf8_utf16.3 +++ b/man/std::codecvt_utf8_utf16.3 @@ -1,18 +1,26 @@ -.TH std::codecvt_utf8_utf16 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::codecvt_utf8_utf16 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::codecvt_utf8_utf16 \- std::codecvt_utf8_utf16 + .SH Synopsis Defined in header - template< class Elem, + template< - unsigned long Maxcode = 0x10ffff, - std::codecvt_mode Mode = (std::codecvt_mode)0 > + class Elem, \fI(since C++11)\fP + unsigned long Maxcode = 0x10ffff, (deprecated in C++17) + std::codecvt_mode Mode = (std::codecvt_mode)0 > (removed in C++26) + class codecvt_utf8_utf16 - class codecvt_utf8_utf16 : public std::codecvt; + : public std::codecvt; std::codecvt_utf8_utf16 is a std::codecvt facet which encapsulates conversion between a UTF-8 encoded byte string and UTF-16 encoded character string. If Elem is - a 32-bit type, one UTF-16 codepoint will be stored in each 32-bit character of the - output sequence. This codecvt facet can be used to read and write UTF-8 files, both - text and binary. + a 32-bit type, one UTF-16 code unit will be stored in each 32-bit character of the + output sequence. + + This is an N:M conversion facet, and cannot be used with std::basic_filebuf (which + only permits 1:N conversions, such as UTF-32/UTF-8, between the internal and the + external encodings). This facet can be used with std::wstring_convert. .SH Template Parameters @@ -27,7 +35,7 @@ destructor destroys a codecvt_utf8_utf16 facet \fI(public member function)\fP - std::codecvt_utf8_utf16::codecvt_utf8_utf16 +std::codecvt_utf8_utf16::codecvt_utf8_utf16 explicit codecvt_utf8_utf16( std::size_t refs = 0 ); @@ -38,7 +46,7 @@ refs - the number of references that link to the facet - std::codecvt_utf8_utf16::~codecvt_utf8_utf16 +std::codecvt_utf8_utf16::~codecvt_utf8_utf16 ~codecvt_utf8_utf16(); @@ -49,7 +57,7 @@ Inherited from std::codecvt .SH Member types - Member type Definition + Member name Definition intern_type internT extern_type externT state_type stateT @@ -61,44 +69,58 @@ Inherited from std::codecvt .SH Member functions - out invokes do_out - \fI(public member function of std::codecvt)\fP - in invokes do_in - \fI(public member function of std::codecvt)\fP - unshift invokes do_unshift - \fI(public member function of std::codecvt)\fP - encoding invokes do_encoding - \fI(public member function of std::codecvt)\fP - always_noconv invokes do_always_noconv - \fI(public member function of std::codecvt)\fP - length invokes do_length - \fI(public member function of std::codecvt)\fP - max_length invokes do_max_length - \fI(public member function of std::codecvt)\fP + invokes do_out + out \fI(public member function of std::codecvt)\fP + + invokes do_in + in \fI(public member function of std::codecvt)\fP + + invokes do_unshift + unshift \fI(public member function of std::codecvt)\fP + + invokes do_encoding + encoding \fI(public member function of std::codecvt)\fP + + invokes do_always_noconv + always_noconv \fI(public member function of std::codecvt)\fP + + invokes do_length + length \fI(public member function of std::codecvt)\fP + + invokes do_max_length + max_length \fI(public member function of std::codecvt)\fP + .SH Protected member functions - do_out converts a string from internT to externT, such as when writing to - \fB[virtual]\fP file - \fI(virtual protected member function of std::codecvt)\fP - do_in converts a string from externT to internT, such as when reading - \fB[virtual]\fP from file - \fI(virtual protected member function of std::codecvt)\fP - do_unshift generates the termination character sequence of externT characters - \fB[virtual]\fP for incomplete conversion - \fI(virtual protected member function of std::codecvt)\fP - do_encoding returns the number of externT characters necessary to produce one - \fB[virtual]\fP internT character, if constant - \fI(virtual protected member function of std::codecvt)\fP - do_always_noconv tests if the facet encodes an identity conversion for all valid - \fB[virtual]\fP argument values - \fI(virtual protected member function of std::codecvt)\fP - do_length calculates the length of the externT string that would be consumed - \fB[virtual]\fP by conversion into given internT buffer - \fI(virtual protected member function of std::codecvt)\fP - do_max_length returns the maximum number of externT characters that could be - \fB[virtual]\fP converted into a single internT character - \fI(virtual protected member function of std::codecvt)\fP + converts a string from InternT to ExternT, such as when writing to + do_out file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + converts a string from ExternT to InternT, such as when reading + do_in from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + generates the termination character sequence of ExternT characters + do_unshift for incomplete conversion + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the number of ExternT characters necessary to produce one + do_encoding InternT character, if constant + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + tests if the facet encodes an identity conversion for all valid + do_always_noconv argument values + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + calculates the length of the ExternT string that would be consumed + do_length by conversion into given InternT buffer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) + returns the maximum number of ExternT characters that could be + do_max_length converted into a single InternT character + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) Inherited from std::codecvt_base @@ -113,72 +135,79 @@ Inherited from std::codecvt_base .SH Example - The following example demonstrates reading a UTF-8 file into a UTF-16 string on a - system with 32-bit wchar_t - // Run this code - #include + #include + #include + #include #include - #include #include - #include - + #include + int main() { - std::ofstream("text.txt") << u8"z\\u6c34\\U0001d10b"; - - std::wifstream file1("text.txt"); - file1.imbue(std::locale("en_US.UTF8")); - std::cout << "Normal read from file (using default UTF-8/UTF-32 codecvt)\\n"; - for (wchar_t c; file1 >> c; ) - std::cout << std::hex << std::showbase << c << '\\n'; - - std::wifstream file2("text.txt"); - file2.imbue(std::locale(file2.getloc(), new std::codecvt_utf8_utf16)); - std::cout << "UTF-16 read from the same file (using codecvt_utf8_utf16)\\n"; - for (wchar_t c; file2 >> c; ) - std::cout << std::hex << std::showbase << c << '\\n'; + std::string u8 = "z\\u00df\\u6c34\\U0001f34c"; + std::u16string u16 = u"z\\u00df\\u6c34\\U0001f34c"; + + // UTF-8 to UTF-16/char16_t + std::u16string u16_conv = std::wstring_convert< + std::codecvt_utf8_utf16, char16_t>{}.from_bytes(u8); + assert(u16 == u16_conv); + std::cout << "UTF-8 to UTF-16 conversion produced " << u16_conv.size() + << " code units:\\n" << std::showbase << std::hex; + for (char16_t c : u16_conv) + std::cout << static_cast(c) << ' '; + + // UTF-16/char16_t to UTF-8 + std::string u8_conv = std::wstring_convert< + std::codecvt_utf8_utf16, char16_t>{}.to_bytes(u16); + assert(u8 == u8_conv); + std::cout << "\\nUTF-16 to UTF-8 conversion produced " + << std::dec << u8_conv.size() << " bytes:\\n" << std::hex; + for (char c : u8_conv) + std::cout << +static_cast(c) << ' '; + std::cout << '\\n'; } .SH Output: - Normal read from file (using default UTF-8/UTF-32 codecvt) - 0x7a - 0x6c34 - 0x1d10b - UTF-16 read from the same file (using codecvt_utf8_utf16) - 0x7a - 0x6c34 - 0xd834 - 0xdd0b + UTF-8 to UTF-16 conversion produced 5 code units: + 0x7a 0xdf 0x6c34 0xd83c 0xdf4c + UTF-16 to UTF-8 conversion produced 10 bytes: + 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c .SH See also - Character narrow multibyte UTF-8 UTF-16 - conversions (char) (char) (char16_t) - codecvt - UTF-16 c16rtomb codecvt_utf8_utf16 N/A - codecvt_utf8_utf16 - codecvt_utf8_utf16 - UCS2 No codecvt_utf8 codecvt_utf16 - UTF-32/UCS4 mbrtoc32 / codecvt codecvt_utf16 - codecvt_utf8 - UCS2/UCS4 No codecvt_utf8 codecvt_utf16 - (wchar_t) - codecvt No No - (wchar_t) mbsrtowcs / - wcsrtombs - - codecvt converts between character encodings, including UTF-8, UTF-16, UTF-32 - \fI(class template)\fP - codecvt_mode tags to alter behavior of the standard codecvt facets - \fI(C++11)\fP \fI(enum)\fP - codecvt_utf8 converts between UTF-8 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf16 converts between UTF-16 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP + Character locale-defined multibyte UTF-8 UTF-16 + conversions (UTF-8, GB18030) + codecvt + UTF-16 mbrtoc16 / c16rtomb (with C11's codecvt_utf8_utf16 N/A + DR488) codecvt_utf8_utf16 + codecvt_utf8_utf16 + UCS-2 c16rtomb (without C11's DR488) codecvt_utf8 codecvt_utf16 + UTF-32 mbrtoc32 / c32rtomb codecvt codecvt_utf16 + codecvt_utf8 + system + wchar_t: + mbsrtowcs / wcsrtombs + UTF-32 use_facet codecvt_utf16 +(non-Windows) >(locale) + UCS-2 + (Windows) + + converts between character encodings, including UTF-8, UTF-16, + codecvt UTF-32 + \fI(class template)\fP + codecvt_mode + \fI(C++11)\fP tags to alter behavior of the standard codecvt facets + (deprecated in C++17) \fI(enum)\fP + (removed in C++26) + codecvt_utf8 + \fI(C++11)\fP converts between UTF-8 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf16 + \fI(C++11)\fP converts between UTF-16 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::collate.3 b/man/std::collate.3 index 26cfb2b3a..03360f1bf 100644 --- a/man/std::collate.3 +++ b/man/std::collate.3 @@ -1,4 +1,7 @@ -.TH std::collate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::collate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate \- std::collate + .SH Synopsis Defined in header template< class CharT > @@ -10,20 +13,18 @@ comparison predicate. std-collate-inheritance.svg - About this image Inheritance diagram - Two standalone (locale-independent) specializations are provided by the standard - library: +.SH Specializations + + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header std::collate implements lexicographical ordering of byte strings std::collate implements lexicographical ordering of wide strings - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. - .SH Member types Member type Definition @@ -37,11 +38,11 @@ destructor destructs a collate facet \fI(protected member function)\fP compare invokes do_compare - \fI(public member function)\fP + \fI(public member function)\fP transform invokes do_transform - \fI(public member function)\fP + \fI(public member function)\fP hash invokes do_hash - \fI(public member function)\fP + \fI(public member function)\fP .SH Member objects @@ -51,40 +52,49 @@ .SH Protected member functions do_compare compares two strings using this facet's collation rules - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_transform transforms a string so that collation can be replaced by comparison - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_hash generates an integer hash value using this facet's collation rules - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Example - + // Run this code - #include + #include #include + #include #include #include - #include - + int main() { + std::locale::global(std::locale("en_US.utf8")); std::wcout.imbue(std::locale("")); - std::vector v = {L"ar", L"zebra", L"\\u00f6grupp", L"Zebra", L"\\u00e4ngel", - L"\\u00e5r", L"f\\u00f6rnamn"}; - + std::vector v{ + L"ar", L"zebra", L"\\u00f6grupp", L"Zebra", + L"\\u00e4ngel",L"\\u00e5r", L"f\\u00f6rnamn" + }; + std::wcout << "Default locale collation order: "; std::sort(v.begin(), v.end()); - for (auto s : v) std::wcout << s << ' '; std::wcout << '\\n'; - + for (auto s : v) + std::wcout << s << ' '; + std::wcout << '\\n'; + std::wcout << "English locale collation order: "; std::sort(v.begin(), v.end(), std::locale("en_US.UTF-8")); - for (auto s : v) std::wcout << s << ' '; std::wcout << '\\n'; - + for (auto s : v) + std::wcout << s << ' '; + std::wcout << '\\n'; + std::wcout << "Swedish locale collation order: "; std::sort(v.begin(), v.end(), std::locale("sv_SE.UTF-8")); - for (auto s : v) std::wcout << s << ' '; std::wcout << '\\n'; + for (auto s : v) + std::wcout << s << ' '; + std::wcout << '\\n'; } .SH Output: @@ -97,6 +107,6 @@ lexicographically compares two strings using this locale's collate operator() facet - \fI(public member function of std::locale)\fP - collate_byname creates a collate facet for the named locale + \fI(public member function of std::locale)\fP + collate_byname represents the system-supplied std::collate for the named locale \fI(class template)\fP diff --git a/man/std::collate::collate.3 b/man/std::collate::collate.3 index a138cf23e..b31f0c7c2 100644 --- a/man/std::collate::collate.3 +++ b/man/std::collate::collate.3 @@ -1,10 +1,13 @@ -.TH std::collate::collate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::collate::collate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate::collate \- std::collate::collate + .SH Synopsis Defined in header explicit collate( std::size_t refs = 0 ); Creates a std::collate facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::collate::compare,std::collate::do_compare.3 b/man/std::collate::compare,std::collate::do_compare.3 index 476e35127..9ce529713 100644 --- a/man/std::collate::compare,std::collate::do_compare.3 +++ b/man/std::collate::compare,std::collate::do_compare.3 @@ -1,4 +1,7 @@ -.TH std::collate::compare,std::collate::do_compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::collate::compare,std::collate::do_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate::compare,std::collate::do_compare \- std::collate::compare,std::collate::do_compare + .SH Synopsis Defined in header public: @@ -14,10 +17,10 @@ 1) Public member function, calls the protected virtual member function do_compare of the most derived class. - 2) Compares the character sequence [low1, high1) to the character sequence [low2, - high2), using this locale's collation rules, and returns 1 if the first string - follows the second, -1 if the first string precedes the second, zero if the two - strings are equivalent. + 2) Compares the character sequence [low1, high1) to the character sequence + [low2, high2), using this locale's collation rules, and returns 1 if the first + string follows the second, -1 if the first string precedes the second, zero if the + two strings are equivalent. .SH Parameters @@ -34,6 +37,10 @@ .SH Notes + When three-way comparison is not required (such as when providing a Compare argument + to standard algorithms such as std::sort), std::locale::operator() may be more + appropriate. + Collation order is the dictionary order: the position of the letter in the national alphabet (its equivalence class) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase @@ -44,36 +51,36 @@ .SH Example - + // Run this code #include - #include #include - + #include + template void try_compare(const std::locale& l, const CharT* p1, const CharT* p2) { auto& f = std::use_facet>(l); - + std::basic_string s1(p1), s2(p2); - if(f.compare(&s1[0], &s1[0] + s1.size(), - &s2[0], &s2[0] + s2.size() ) < 0) - std::wcout << p1 << " before " << p2 << '\\n'; + if (f.compare(&s1[0], &s1[0] + s1.size(), + &s2[0], &s2[0] + s2.size()) < 0) + std::wcout << p1 << " before " << p2 << '\\n'; else - std::wcout << p2 << " before " << p1 << '\\n'; + std::wcout << p2 << " before " << p1 << '\\n'; } - + int main() { std::locale::global(std::locale("en_US.utf8")); std::wcout.imbue(std::locale()); - + std::wcout << "In the American locale: "; try_compare(std::locale(), "hrnec", "chrt"); std::wcout << "In the Czech locale: "; try_compare(std::locale("cs_CZ.utf8"), "hrnec", "chrt"); - + std::wcout << "In the American locale: "; try_compare(std::locale(), L"år", L"ängel"); std::wcout << "In the Swedish locale: "; @@ -90,8 +97,8 @@ .SH See also strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP wcscoll compares two wide strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP operator() lexicographically compares two strings using this locale's collate facet - \fI(public member function of std::locale)\fP + \fI(public member function of std::locale)\fP diff --git a/man/std::collate::hash,do_hash.3 b/man/std::collate::hash,do_hash.3 deleted file mode 100644 index 5b2f0bd9f..000000000 --- a/man/std::collate::hash,do_hash.3 +++ /dev/null @@ -1,91 +0,0 @@ -.TH std::collate::hash,do_hash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - public: \fB(1)\fP - long hash( const CharT* beg, const CharT* end ) const; - protected: \fB(2)\fP - virtual long do_hash( const CharT* beg, const CharT* end ) const; - - 1) Public member function, calls the protected virtual member function do_hash of - the most derived class. - 2) Converts the character sequence [beg, end) to an integer value that is equal to - the hash obtained for all strings that collate equivalent in this locale (compare() - returns 0). For two strings that do not collate equivalent, the probability that - their hashes are equal should be very small, approaching - 1.0/std::numeric_limits::max(). - -.SH Parameters - - beg - pointer to the first character in the sequence to hash - end - one past the end pointer for the sequence to hash - -.SH Return value - - The hash value that respects collation order - -.SH Note - - The system-supplied locales normally do not collate two strings as equivalent - (compare() does not return 0) if basic_string::operator== returns false, but a - user-installed std::collate facet may provide different collation rules, for - example, it may treat strings as equivalent if they have the same Unicode normalized - form. - -.SH Example - - Demonstrates a locale-aware unordered container - - -// Run this code - - #include - #include - #include - #include - - struct CollateHash { - template - std::size_t operator()(const std::basic_string& s) const - { - return std::use_facet>(std::locale()).hash( - &s[0], &s[0] + s.size() - ); - } - }; - struct CollateEq { - template - bool operator()(const std::basic_string& s1, - const std::basic_string& s2) const - { - return std::use_facet>(std::locale()).compare( - &s1[0], &s1[0] + s1.size(), - &s2[0], &s2[0] + s2.size() - ) == 0; - } - }; - - int main() - { - std::locale::global(std::locale("en_US.utf8")); - std::wcout.imbue(std::locale()); - - std::unordered_set s2 = {L"Foo", L"Bar"}; - for(auto& str: s2) - std::wcout << str << ' '; - std::cout << '\\n'; - } - -.SH Possible output: - - Bar Foo - -.SH See also - - std::hash - std::hash - std::hash - std::hash hash support for strings - \fI(C++11)\fP \fI(class template specialization)\fP - \fI(C++11)\fP - \fI(C++11)\fP - \fI(C++11)\fP diff --git a/man/std::collate::hash,std::collate::do_hash.3 b/man/std::collate::hash,std::collate::do_hash.3 new file mode 100644 index 000000000..51f213946 --- /dev/null +++ b/man/std::collate::hash,std::collate::do_hash.3 @@ -0,0 +1,90 @@ +.TH std::collate::hash,std::collate::do_hash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate::hash,std::collate::do_hash \- std::collate::hash,std::collate::do_hash + +.SH Synopsis + Defined in header + public: \fB(1)\fP + long hash( const CharT* beg, const CharT* end ) const; + protected: \fB(2)\fP + virtual long do_hash( const CharT* beg, const CharT* end ) const; + + 1) Public member function, calls the protected virtual member function do_hash of + the most derived class. + 2) Converts the character sequence [beg, end) to an integer value that is equal to + the hash obtained for all strings that collate equivalent in this locale (compare() + returns 0). For two strings that do not collate equivalent, the probability that + their hashes are equal should be very small, approaching 1.0 / + std::numeric_limits::max(). + +.SH Parameters + + beg - pointer to the first character in the sequence to hash + end - one past the end pointer for the sequence to hash + +.SH Return value + + The hash value that respects collation order. + +.SH Note + + The system-supplied locales normally do not collate two strings as equivalent + (compare() does not return 0) if basic_string::operator== returns false, but a + user-installed std::collate facet may provide different collation rules, for + example, it may treat strings as equivalent if they have the same Unicode normalized + form. + +.SH Example + + Demonstrates a locale-aware unordered container. + + +// Run this code + + #include + #include + #include + #include + + struct CollateHash + { + template + long operator()(const std::basic_string& s) const + { + return std::use_facet>(std::locale()).hash( + &s[0], &s[0] + s.size() + ); + } + }; + struct CollateEq + { + template + bool operator()(const std::basic_string& s1, + const std::basic_string& s2) const + { + return std::use_facet>(std::locale()).compare( + &s1[0], &s1[0] + s1.size(), + &s2[0], &s2[0] + s2.size() + ) == 0; + } + }; + + int main() + { + std::locale::global(std::locale("en_US.utf8")); + std::wcout.imbue(std::locale()); + + std::unordered_set s2 = {L"Foo", L"Bar"}; + for (auto& str : s2) + std::wcout << str << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + Bar Foo + +.SH See also + + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::collate::transform,do_transform.3 b/man/std::collate::transform,do_transform.3 index 904877f5a..69603da5f 100644 --- a/man/std::collate::transform,do_transform.3 +++ b/man/std::collate::transform,do_transform.3 @@ -1,4 +1,7 @@ -.TH std::collate::transform,do_transform 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::collate::transform,do_transform 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate::transform,do_transform \- std::collate::transform,do_transform + .SH Synopsis Defined in header public: \fB(1)\fP @@ -27,42 +30,41 @@ .SH Notes - In addition to the the use in collation, the implementation-specific format of the + In addition to the use in collation, the implementation-specific format of the transformed string is known to std::regex_traits<>::transform_primary, which is able to extract the equivalence class information. .SH Example - + // Run this code - #include #include + #include #include - + int main() { std::locale::global(std::locale("sv_SE.utf8")); auto& f = std::use_facet>(std::locale()); - + std::wstring in1 = L"\\u00e4ngel"; std::wstring in2 = L"\\u00e5r"; - + std::wstring out1 = f.transform(&in1[0], &in1[0] + in1.size()); std::wstring out2 = f.transform(&in2[0], &in2[0] + in2.size()); - + std::wcout << "In the Swedish locale: "; - if(out1 < out2) - std::wcout << in1 << " before " << in2 << '\\n'; + if (out1 < out2) + std::wcout << in1 << " before " << in2 << '\\n'; else - std::wcout << in2 << " before " << in1 << '\\n'; - + std::wcout << in2 << " before " << in1 << '\\n'; + std::wcout << "In lexicographic comparison: "; - if(in1 < in2) - std::wcout << in1 << " before " << in2 << '\\n'; + if (in1 < in2) + std::wcout << in1 << " before " << in2 << '\\n'; else - std::wcout << in2 << " before " << in1 << '\\n'; - + std::wcout << in2 << " before " << in1 << '\\n'; } .SH Output: @@ -73,7 +75,7 @@ .SH See also strxfrm transform a string so that strcmp would produce the same result as strcoll - \fI(function)\fP + \fI(function)\fP transform a wide string so that wcscmp would produce the same result as wcsxfrm wcscoll - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::collate::~collate.3 b/man/std::collate::~collate.3 index 1a9eafc2a..f622034bd 100644 --- a/man/std::collate::~collate.3 +++ b/man/std::collate::~collate.3 @@ -1,4 +1,7 @@ -.TH std::collate::~collate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::collate::~collate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate::~collate \- std::collate::~collate + .SH Synopsis Defined in header protected: ~collate(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_collate : public std::collate { Destructible_collate(std::size_t refs = 0) : collate(refs) {} - ~Destructible_collate() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_collate dc; - // std::collate c; // compile error: protected destructor + // std::collate c; // compile error: protected destructor } diff --git a/man/std::collate_byname.3 b/man/std::collate_byname.3 index 4d4a80d84..2e28015d5 100644 --- a/man/std::collate_byname.3 +++ b/man/std::collate_byname.3 @@ -1,4 +1,7 @@ -.TH std::collate_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::collate_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::collate_byname \- std::collate_byname + .SH Synopsis Defined in header template< class CharT > @@ -9,7 +12,9 @@ imbued in std::regex and applied, by means of std::locale::operator(), directly to all standard algorithms that expect a string comparison predicate. - Two specializations are provided by the standard library +.SH Specializations + + The standard library is guaranteed to provide the following specializations: Defined in header std::collate_byname locale-specific collation of multibyte strings @@ -18,13 +23,13 @@ .SH Member functions constructor constructs a new collate_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a collate_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP + - - std::collate_byname::collate_byname +std::collate_byname::collate_byname explicit collate_byname( const char* name, std::size_t refs = 0 ); explicit collate_byname( const std::string& name, std::size_t refs = \fI(since C++11)\fP @@ -41,9 +46,9 @@ name - the name of the locale refs - the number of references that link to the facet - - std::collate_byname::~collate_byname + +std::collate_byname::~collate_byname protected: ~collate_byname(); @@ -55,26 +60,26 @@ Inherited from std::collate .SH Member types Member type Definition - char_type charT - string_type std::basic_string + char_type CharT + string_type std::basic_string .SH Member functions compare invokes do_compare - \fI(public member function of std::collate)\fP + \fI(public member function of std::collate)\fP transform invokes do_transform - \fI(public member function of std::collate)\fP + \fI(public member function of std::collate)\fP hash invokes do_hash - \fI(public member function of std::collate)\fP + \fI(public member function of std::collate)\fP .SH Protected member functions do_compare compares two strings using this facet's collation rules - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP do_transform transforms a string so that collation can be replaced by comparison - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP do_hash generates an integer hash value using this facet's collation rules - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP .SH Notes @@ -94,14 +99,13 @@ Inherited from std::collate .SH See also collate defines lexicographical comparison and hashing of strings - \fI(class template)\fP + \fI(class template)\fP strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP wcscoll compares two wide strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP operator() lexicographically compares two strings using this locale's collate facet - \fI(public member function of std::locale)\fP + \fI(public member function of std::locale)\fP .SH Category: - * Todo no example diff --git a/man/std::common_comparison_category.3 b/man/std::common_comparison_category.3 new file mode 100644 index 000000000..ea6675790 --- /dev/null +++ b/man/std::common_comparison_category.3 @@ -0,0 +1,87 @@ +.TH std::common_comparison_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_comparison_category \- std::common_comparison_category + +.SH Synopsis + Defined in header + template< class... Ts > + + struct common_comparison_category + { \fI(since C++20)\fP + using type = /* see below */ ; + + }; + + The class template std::common_comparison_category provides an alias (as the member + typedef type) for the strongest comparison category to which all of the template + arguments Ts... can be converted. + + In detail, the common comparison type of a list of n types T[0]...T[n-1] is defined + as follows: + + * If any T[i] is not a comparison category type (std::partial_ordering, + std::weak_ordering, std::strong_ordering), U is void. + * Otherwise, if at least one T[i] is std::partial_ordering, U is + std::partial_ordering. + * Otherwise, if at least one T[i] is std::weak_ordering, U is std::weak_ordering. + * Otherwise (if every T[i] is std::strong_ordering, or if the list is empty), U is + std::strong_ordering. + +.SH Template parameters + + ...Ts - a possibly empty list of types + + Helper template + + template< class... Ts > + using common_comparison_category_t = \fI(since C++20)\fP + common_comparison_category::type; + +.SH Member types + + Member type Definition + type the strongest common comparison category (as defined above) + +.SH Possible implementation + + namespace detail + { + template + struct common_cmpcat_base { using type = void; }; + template<> + struct common_cmpcat_base<0u> { using type = std::strong_ordering; }; + template<> + struct common_cmpcat_base<2u> { using type = std::partial_ordering; }; + template<> + struct common_cmpcat_base<4u> { using type = std::weak_ordering; }; + template<> + struct common_cmpcat_base<6u> { using type = std::partial_ordering; }; + } // namespace detail + + template + struct common_comparison_category : + detail::common_cmpcat_base<(0u | ... | + (std::is_same_v ? 0u : + std::is_same_v ? 4u : + std::is_same_v ? 2u : 1u) + )> {}; + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + strong_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is substitutable + \fI(class)\fP + weak_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is not substitutable + \fI(class)\fP + partial_ordering the result type of 3-way comparison that supports all 6 operators, + (C++20) is not substitutable, and allows incomparable values + \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::common_iterator.3 b/man/std::common_iterator.3 new file mode 100644 index 000000000..e2ac6d043 --- /dev/null +++ b/man/std::common_iterator.3 @@ -0,0 +1,108 @@ +.TH std::common_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_iterator \- std::common_iterator + +.SH Synopsis + Defined in header + template< std::input_or_output_iterator I, std::sentinel_for S > + + requires ( !std::same_as && std::copyable ) \fI(since C++20)\fP + + class common_iterator; + + std::common_iterator is an iterator I / sentinel S adaptor that may represent a + non-common range (where the types of I and S differ) as a common_range, by + containing either an iterator or a sentinel, and defining the appropriate equality + comparison operators operator==. + + std::common_iterator can be used as a "bridge" between sequences represented by + iterator/sentinel pair and legacy functions that expect common_range-like sequences. + +.SH Member functions + + constructor constructs a new iterator adaptor + (C++20) \fI(public member function)\fP + operator= assigns another iterator adaptor + (C++20) \fI(public member function)\fP + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + (C++20) + operator++ advances the iterator adaptor + operator++(int) \fI(public member function)\fP + (C++20) + +.SH Non-member functions + + operator== compares the underlying iterators or sentinels + (C++20) \fI(function template)\fP + operator- computes the distance between two iterator adaptors + (C++20) \fI(function template)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function template)\fP + +.SH Helper classes + + computes the associated difference + std::incrementable_traits type of the std::common_iterator + (C++20) type + \fI(class template specialization)\fP + + provides uniform interface to the + std::iterator_traits properties of the + (C++20) std::common_iterator type + \fI(class template specialization)\fP + + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void fire(ForwardIter first, ForwardIter last) + { + std::copy(first, last, std::ostream_iterator{std::cout, " "}); + } + + int main() + { + std::list stars{"Pollux", "Arcturus", "Mira", "Aldebaran", "Sun"}; + + using IT = std::common_iterator< + std::counted_iterator::iterator>, + std::default_sentinel_t>; + + fire(IT(std::counted_iterator(stars.begin(), stars.size() - 1)), + IT(std::default_sentinel)); + } + +.SH Output: + + Pollux Arcturus Mira Aldebaran + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 23.5.5 Common iterators [iterators.common] + * C++20 standard (ISO/IEC 14882:2020): + + * 23.5.4 Common iterators [iterators.common] + +.SH See also + + ranges::common_range specifies that a range has identical iterator and sentinel + (C++20) types + (concept) + ranges::common_view converts a view into a common_range + views::common \fI(class template)\fP (range adaptor object) + (C++20) diff --git a/man/std::common_iterator::common_iterator.3 b/man/std::common_iterator::common_iterator.3 new file mode 100644 index 000000000..2c1056b74 --- /dev/null +++ b/man/std::common_iterator::common_iterator.3 @@ -0,0 +1,82 @@ +.TH std::common_iterator::common_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_iterator::common_iterator \- std::common_iterator::common_iterator + +.SH Synopsis + constexpr common_iterator() requires std::default_initializable \fB(1)\fP \fI(since C++20)\fP + = default; + constexpr common_iterator( I i ); \fB(2)\fP \fI(since C++20)\fP + constexpr common_iterator( S s ); \fB(3)\fP \fI(since C++20)\fP + template< class I2, class S2 > + + requires std::convertible_to && \fB(4)\fP \fI(since C++20)\fP + std::convertible_to + + constexpr common_iterator( const common_iterator& x ); + + Constructs a new iterator adaptor, effectively initializes the underlying + std::variant member object var to hold an I (iterator) or S (sentinel) object. + + 1) Default constructor. Default-initializes var. After construction, var holds a + value-initialized I object. Operations on the resulting iterator adaptor have + defined behavior if and only if the corresponding operations on a value-initialized + I also have defined behavior. + 2) After construction, var holds an I object move-constructed from i. + 3) After construction, var holds an S object move-constructed from s. + 4) After construction, var holds an I or S object initialized from the I2 or S2 held + by x.var, if x.var holds that alternative, respectively. The behavior is undefined + if x is in an invalid state, that is, x.var.valueless_by_exception() is equal to + true. + +.SH Parameters + + i - iterator to adapt + s - sentinel to adapt + x - iterator adaptor to copy + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector v{3, 1, 4, 1, 5, 9, 2}; + + using CI = std::common_iterator< + std::counted_iterator::iterator>, + std::default_sentinel_t>; + CI unused; // (1) + CI start{std::counted_iterator{std::next(begin(v)), ssize(v) - 2}}; // (2) + CI finish{std::default_sentinel}; // (3) + CI first{start}; // (4) + CI last{finish}; // (4) + + std::copy(first, last, std::ostream_iterator{std::cout, " "}); + std::cout << '\\n'; + + std::common_iterator< + std::counted_iterator< + std::ostream_iterator>, + std::default_sentinel_t> + beg{std::counted_iterator{std::ostream_iterator{std::cout,"; "}, 5}}, + end{std::default_sentinel}; + std::iota(beg, end, 3.1); + std::cout << '\\n'; + } + +.SH Output: + + 1 4 1 5 9 + 3.1; 4.1; 5.1; 6.1; 7.1; + +.SH See also + + operator= assigns another iterator adaptor + (C++20) \fI(public member function)\fP diff --git a/man/std::common_iterator::operator*,->.3 b/man/std::common_iterator::operator*,->.3 new file mode 100644 index 000000000..aae827eb9 --- /dev/null +++ b/man/std::common_iterator::operator*,->.3 @@ -0,0 +1,105 @@ +.TH std::common_iterator::operator*,-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_iterator::operator*,-> \- std::common_iterator::operator*,-> + +.SH Synopsis + constexpr decltype(auto) operator*(); \fB(1)\fP \fI(since C++20)\fP + constexpr decltype(auto) operator*() const \fB(2)\fP \fI(since C++20)\fP + requires /*dereferenceable*/; + constexpr auto operator->() const \fB(3)\fP \fI(since C++20)\fP + requires /* see description */; +.SH Helper types + class /*proxy*/ { + + std::iter_value_t keep_; + constexpr proxy(std::iter_reference_t&& x) + : keep_(std::move(x)) {} + public: \fB(4)\fP (exposition only*) + constexpr const std::iter_value_t* operator->() const + noexcept { + return std::addressof(keep_); + } + + }; + + Returns pointer or reference to the current element, or a proxy holding it. + + The behavior is undefined if the underlying std::variant member object var does not + hold an object of type I, i.e. std::holds_alternative(var) is equal to false. + + Let it denote the iterator of type I held by var, that is std::get(var). + + 1,2) Returns the result of dereferencing it. + 3) Returns a pointer or underlying iterator to the current element, or a proxy + holding it: + * Equivalent to return it;, if I is a pointer type or if the expression + it.operator->() is well-formed. + * Otherwise, equivalent to auto&& tmp = *it; return std::addressof(tmp);, if + std::iter_reference_t is a reference type. + * Otherwise, equivalent to return proxy(*it);, where proxy is an exposition only + class \fB(4)\fP. + The expression in the requires-clause is equivalent to + std::indirectly_readable && ( + + requires(const I& i) { i.operator->(); } || + std::is_reference_v> || + std::constructible_from, std::iter_reference_t> + + ). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,2) Reference to the current element, or prvalue temporary. Equivalent to *it. + 3) Pointer or iterator to the current element or proxy holding it as described + above. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + using std::complex_literals::operator""i; + + int main() + { + const auto il = {1i, 3.14 + 2i, 3i, 4i, 5i}; + + using CI = std::common_iterator< + std::counted_iterator, + std::default_sentinel_t>; + + CI ci{std::counted_iterator{std::next(begin(il), 1), std::ssize(il) - 1}}; + + std::cout << *ci << ' ' << ci->real() << '\\n'; + } + +.SH Output: + + (3.14,2) 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3574 C++20 variant was fully constexpr (P2231R1) but also made constexpr + common_iterator was not + LWG 3595 C++20 functions of the proxy type lacked added + constexpr and noexcept + LWG 3672 C++20 operator-> might return by reference in always returns by + usual cases value + +.SH See also + + constructor constructs a new iterator adaptor + (C++20) \fI(public member function)\fP diff --git a/man/std::common_iterator::operator++.3 b/man/std::common_iterator::operator++.3 new file mode 100644 index 000000000..fa47d2cf1 --- /dev/null +++ b/man/std::common_iterator::operator++.3 @@ -0,0 +1,103 @@ +.TH std::common_iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_iterator::operator++ \- std::common_iterator::operator++ + +.SH Synopsis + constexpr common_iterator& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr decltype(auto) operator++( int ); \fB(2)\fP \fI(since C++20)\fP +.SH Helper types + class /*postfix_proxy*/ { + + std::iter_value_t keep_; + constexpr postfix_proxy(std::iter_reference_t&& x) + : keep_(std::forward>(x)) {} + public: \fB(3)\fP (exposition + constexpr const std::iter_value_t& operator*() const only*) + noexcept { + return keep_; + } + + }; + + Increments the underlying iterator. + + The behavior is undefined if the underlying std::variant member object var does not + hold an object of type I, i.e. std::holds_alternative(var) is equal to false. + + Let it denote the iterator of type I held by var, that is std::get(var). + + 1) Pre-increments by one. Equivalent to ++it; return *this;. + 2) Post-increments by one: + * Equivalent to: auto tmp = *this; ++*this; return tmp;, if I models + forward_iterator. + * Equivalent to: return it++;, if the variable definition auto&& ref = *it++; is + well-formed, or either + + * std::indirectly_readable or + * std::constructible_from, std::iter_reference_t> or + * std::move_constructible> + + is false. + * Equivalent to: postfix_proxy p(**this); ++*this; return p; otherwise, where + postfix_proxy is an exposition only helper type \fB(3)\fP. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) *this + 2) A copy of *this that was made before the change, or a result of post-increment of + the underlying iterator, or a proxy keeping the value of the current element, as + described above. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto il = {1, 2, 3, 4, 5, 6}; + + using CI = std::common_iterator< + std::counted_iterator::iterator>, + std::default_sentinel_t + >; + + CI first{std::counted_iterator{std::begin(il), std::ssize(il) - 2}}; + + for (; first != std::default_sentinel; ++first) + std::cout << *first << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2259R1 C++20 post increment might discard its result a proxy class is used to + in more situations keep the result + LWG 3546 C++20 initialization of the proxy object was situation and definition + sometimes ill-formed adjusted + LWG 3574 C++20 variant was fully constexpr (P2231R1) also made constexpr + but common_iterator was not + LWG 3595 C++20 functions of the proxy type lacked added + constexpr and noexcept + +.SH See also + + operator- computes the distance between two iterator adaptors + \fI(function template)\fP diff --git a/man/std::common_iterator::operator=.3 b/man/std::common_iterator::operator=.3 new file mode 100644 index 000000000..9d8c51d19 --- /dev/null +++ b/man/std::common_iterator::operator=.3 @@ -0,0 +1,77 @@ +.TH std::common_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_iterator::operator= \- std::common_iterator::operator= + +.SH Synopsis + template< class I2, class S2 > + + requires std::convertible_to && + std::convertible_to && + std::assignable_from && \fI(since C++20)\fP + std::assignable_from + + constexpr common_iterator& operator=( const common_iterator& + x ); + + Assigns the underlying std::variant member object var from that of x. + + Let i is x.var.index(). Then, this assignment is equivalent to: + + * std::get(var) = std::get(x.var), if var.index() == i, + * var.emplace(std::get(x.var)) otherwise. + + The behavior is undefined if x is in an invalid state, that is, + x.var.valueless_by_exception() is equal to true. + +.SH Parameters + + x - iterator adaptor to assign from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto il = {1, 2, 3, 4, 5, 6}; + using CI = std::common_iterator< + std::counted_iterator::iterator>, + std::default_sentinel_t>; + CI first{std::counted_iterator{std::next(begin(il), 1), ssize(il) - 1}}; + const CI first2{std::counted_iterator{std::next(begin(il), 2), ssize(il) - 2}}; + const CI last{std::default_sentinel}; + std::copy(first, last, std::ostream_iterator{std::cout, " "}); + std::cout << '\\n'; + first = first2; + std::copy(first, last, std::ostream_iterator{std::cout, " "}); + std::cout << '\\n'; + } + +.SH Output: + + 2 3 4 5 6 + 3 4 5 6 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3574 C++20 variant was fully constexpr (P2231R1) but also made constexpr + common_iterator was not + +.SH See also + + constructor constructs a new iterator adaptor + (C++20) \fI(public member function)\fP diff --git a/man/std::common_reference.3 b/man/std::common_reference.3 new file mode 100644 index 000000000..965fe859f --- /dev/null +++ b/man/std::common_reference.3 @@ -0,0 +1,157 @@ +.TH std::common_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_reference \- std::common_reference + +.SH Synopsis + Defined in header + template< class... T > \fI(since C++20)\fP + struct common_reference; + + Determines the common reference type of the types T..., that is, the type to which + all the types in T... can be converted or bound. If such a type exists (as + determined according to the rules below), the member type names that type. + Otherwise, there is no member type. The behavior is undefined if any of the types in + T... is an incomplete type other than (possibly cv-qualified) void. + + When given reference types, common_reference attempts to find a reference type to + which the supplied reference types can all be bound, but may return a non-reference + type if it cannot find such a reference type. + + * If sizeof...(T) is zero, there is no member type. + * If sizeof...(T) is one (i.e., T... contains only one type T0), the member type + names the same type as T0. + * If sizeof...(T) is two (i.e., T... contains two types T1 and T2): + * Let type S be the simple common reference type of T1 and T2 (as defined + below). The member type type names S if all of the conditions below are + satisfied: + * T1 and T2 are both reference types + * S is well-formed + + * std::is_convertible_v, + std::add_pointer_t> and (since C++23) + std::is_convertible_v, + std::add_pointer_t> are true; + + * Otherwise, if std::basic_common_reference, + std::remove_cvref_t, T1Q, T2Q>::type exists, where TiQ is a unary alias + template such that TiQ is U with the addition of Ti's cv- and reference + qualifiers, then the member type type names that type; + * + * Otherwise, if decltype(false? val() : val()), where val is a + function template template T val();, is a valid type, then the + member type type names that type; + * Otherwise, if std::common_type_t is a valid type, then the member + type type names that type; + * Otherwise, there is no member type. + * If sizeof...(T) is greater than two (i.e., T... consists of the types T1, T2, + R...), then if std::common_reference_t exists, the member type denotes + std::common_reference_t, R...> if such a type + exists. In all other cases, there is no member type. + + The simple common reference type of two reference types T1 and T2 is defined as + follows: + + * If T1 is cv1 X& and T2 is cv2 Y& (i.e., both are lvalue reference types): their + simple common reference type is decltype(false? std::declval() : + std::declval()), where cv12 is the union of cv1 and cv2, if that type + exists and is a reference type; + * If T1 and T2 are both rvalue reference types: if the simple common reference + type of T1& and T2& (determined according to the previous bullet) exists, then + let C denote that type's corresponding rvalue reference type. If + std::is_convertible_v and std::is_convertible_v are both true, + then the simple common reference type of T1 and T2 is C; + * Otherwise, one of the two types must be an lvalue reference type A& and the + other must be an rvalue reference type B&& (A and B might be cv-qualified). Let + D denote the simple common reference type of A& and B const&, if any. If D + exists and std::is_convertible_v is true, then the simple common + reference type is D; + * Otherwise, there's no simple common reference type. + + See Conditional operator for the definition of the type of expression false ? X : Y + like the ones used above. + +.SH Member types + + Name Definition + type the common reference type for all T... + +.SH Helper types + + template< class... T > + using common_reference_t = std::common_reference::type; + template< class T, class U, template class TQual, template class + UQual > + struct basic_common_reference {}; + + The class template basic_common_reference is a customization point that allows users + to influence the result of common_reference for user-defined types (typically proxy + references). The primary template is empty. + +.SH Specializations + + A program may specialize std::basic_common_reference on the + first two parameters T and U if std::is_same_v> and + std::is_same_v> are both true and at least one of them depends on + a program-defined type. + + If such a specialization has a member named type, it must be a public and + unambiguous member that names a type to which both TQual and UQual are + convertible. Additionally, std::basic_common_reference::type and + std::basic_common_reference::type must denote the same type. + + A program may not specialize basic_common_reference on the third or fourth + parameters, nor may it specialize common_reference itself. A program that adds + specializations in violation of these rules has undefined behavior. + + The standard library provides following specializations of basic_common_reference: + + determines the common reference + std::basic_common_reference type of two pairs + (C++23) \fI(class template specialization)\fP + + determines the common reference + std::basic_common_reference type of a tuple and a tuple-like + (C++23) type + \fI(class template specialization)\fP + + determines the common reference + std::basic_common_reference type of reference_wrapper and + (C++23) non-reference_wrapper + \fI(class template specialization)\fP + + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_common_reference 202302L (C++23) Make std::common_reference_t of + std::reference_wrapper a reference type + +.SH Examples + + +// Run this code + + #include + #include + + static_assert( + std::same_as< + int&, + std::common_reference_t< + std::add_lvalue_reference_t, + std::add_lvalue_reference_t&, + std::add_lvalue_reference_t&&, + std::add_lvalue_reference_tconst, + std::add_lvalue_reference_tconst& + > + > + ); + + int main() {} + +.SH See also + + common_type determines the common type of a group of types + \fI(C++11)\fP \fI(class template)\fP + common_reference_with specifies that two types share a common reference type + (C++20) (concept) diff --git a/man/std::common_reference_with.3 b/man/std::common_reference_with.3 new file mode 100644 index 000000000..77a3f7e5f --- /dev/null +++ b/man/std::common_reference_with.3 @@ -0,0 +1,41 @@ +.TH std::common_reference_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_reference_with \- std::common_reference_with + +.SH Synopsis + Defined in header + template< class T, class U > + + concept common_reference_with = + std::same_as, \fI(since C++20)\fP + std::common_reference_t> && + std::convertible_to> && + + std::convertible_to>; + + The concept common_reference_with specifies that two types T and U share a + common reference type (as computed by std::common_reference_t) to which both can be + converted. + + Semantic requirements + + T and U model std::common_reference_with only if, given equality-preserving + expressions t1, t2, u1 and u2 such that decltype((t1)) and decltype((t2)) are both T + and decltype((u1)) and decltype((u2)) are both U, + + * std::common_reference_t(t1) equals std::common_reference_t(t2) if + and only if t1 equals t2; and + * std::common_reference_t(u1) equals std::common_reference_t(u2) if + and only if u1 equals u2. + + In other words, the conversion to the common reference type must preserve equality. + +.SH See also + + common_reference determines the common reference type of a group of types + basic_common_reference \fI(class template)\fP + (C++20) + common_with specifies that two types share a common type + (C++20) (concept) + common_type determines the common type of a group of types + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::common_type(std::chrono::duration).3 b/man/std::common_type(std::chrono::duration).3 deleted file mode 100644 index a52c59918..000000000 --- a/man/std::common_type(std::chrono::duration).3 +++ /dev/null @@ -1,61 +0,0 @@ -.TH std::common_type(std::chrono::duration) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template - - struct common_type, - std::chrono::duration> { - typedef std::chrono::duration< \fI(since C++11)\fP - typename std::common_type::type, /*see note*/> - type; - - }; - - Exposes the type named type, which is the common type of two std::chrono::durations. - -.SH Note - - The period of the resulting duration is the greatest common divisor of Period1 and - Period2. - - std::common_type<> is specialized for std::chrono::duration. - -.SH Example - - -// Run this code - - #include - #include - - // std::chrono already finds the greatest common divisor, - // likely using std::common_type<>. We make the type - // deduction externally. - - template - auto durationDiff(const T& t, const S& s) -> typename std::common_type::type - { - typedef typename std::common_type::type Common; - return Common(t) - Common(s); - } - - - int main() - { - typedef std::chrono::milliseconds milliseconds; - typedef std::chrono::microseconds microseconds; - - auto ms = milliseconds(30); - auto us = microseconds(1100); - - std::cout << ms.count() << "ms - " << us.count() << "us = " - << durationDiff(ms,us).count() << "\\n"; - } - -.SH Output: - - 30ms - 1100us = 28900 - -.SH See also - - common_type deduces the result type of a mixed-mode arithmetic expression - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::common_type(std::chrono::time_point).3 b/man/std::common_type(std::chrono::time_point).3 deleted file mode 100644 index fbd68b4d2..000000000 --- a/man/std::common_type(std::chrono::time_point).3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::common_type(std::chrono::time_point) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template - - struct common_type, - std::chrono::time_point> { - typedef std::chrono::time_point< \fI(since C++11)\fP - Clock, typename std::common_type::type> - type; - - }; - - Exposes the type named type, which is the common type of two - std::chrono::time_points. - -.SH Notes - - The common type of two std::chrono::time_point types is a std::chrono::time_point - with the same clock as the two types and the std::common_type of their durations. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - common_type deduces the result type of a mixed-mode arithmetic expression - \fI(C++11)\fP \fI(class template)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::common_type.3 b/man/std::common_type.3 index 29e2d70d3..c15b2d777 100644 --- a/man/std::common_type.3 +++ b/man/std::common_type.3 @@ -1,128 +1,46 @@ -.TH std::common_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::common_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_type \- std::common_type + .SH Synopsis - Defined in header - template< class... T > \fI(since C++11)\fP - struct common_type; - - Determines the common type among all types T..., that is the type all T... can be - implicitly converted to. - - * std::common_type may be specialized for custom types, e.g. - std::chrono::time_point. - * For non-specialized std::common_type, the rules for determining the common type - between every pair T1, T2 are exactly the rules for determining the return type - of the ternary conditional operator where T1 and T2 are the types of its second - and the third operands. - * For arithmetic types, the common type may also be viewed as the type of the - (possibly mixed-mode) arithmetic expression such as T0() + T1() + ... + Tn(). + Defined in header + template< class T, std::common_with U > + + requires std::input_iterator> \fB(1)\fP (since C++23) + + struct common_type, U>; + template< class T, std::common_with U > + + requires std::input_iterator> \fB(2)\fP (since C++23) + + struct common_type>; + template< class T, std::common_with U > + + requires std::input_iterator> \fB(3)\fP (since C++23) + struct common_type, + + std::basic_const_iterator>; + + The common type of two basic_const_iterators or a basic_const_iterator and another + iterator type is a basic_const_iterator of the common underlying type. + + The common type is defined only if T and U share a common type which models + input_iterator. .SH Member types - Name Definition - type the common type for all T... - -.SH Helper types - - template< class... T > \fI(since C++14)\fP - using common_type_t = typename common_type::type; - -.SH Specializations - - Custom specializations of the type trait std::common_type are allowed. The following - specializations are already provided by the standard library: - - std::common_type specializes the std::common_type trait - \fI(class template specialization)\fP - std::common_type specializes the std::common_type trait - \fI(class template specialization)\fP - -.SH Possible implementation - - template struct common_type; - - template - struct common_type { - typedef decay_t type; - }; - - template - struct common_type { - typedef decay_t() : declval())> type; - }; - - template - struct common_type { - typedef common_type_t, V...> type; - }; - -.SH Examples - - Demonstrates mixed-mode arithmetic on a user-defined class - - -// Run this code - - #include - #include - - template - struct Number { T n; }; - - template - Number::type> operator+(const Number& lhs, - const Number& rhs) - { - return {lhs.n + rhs.n}; - } - - int main() - { - Number i1 = {1}, i2 = {2}; - Number d1 = {2.3}, d2 = {3.5}; - std::cout << "i1i2: " << (i1 + i2).n << "\\ni1d2: " << (i1 + d2).n << '\\n' - << "d1i2: " << (d1 + i2).n << "\\nd1d2: " << (d1 + d2).n << '\\n'; - } - -.SH Output: - - i1i2: 3 - i1d2: 4.5 - d1i2: 4.3 - d1d2: 5.8 - - Demonstrates the use as the identity template - - -// Run this code - - #include - #include - #include - - template - void fun(const int (&a)[N]) - { - std::cout << "Array overload: "; - for (int n: a) - std::cout << n << ' '; - std::cout << '\\n'; - } - - void fun(const std::vector& v) - { - std::cout << "Vector overload: "; - for (int n: v) - std::cout << n << ' '; - std::cout << '\\n'; - } - - int main() - { - fun( {1, 2, 3} ); // calls the vector overload - fun( std::common_type::type {1, 2, 3} ); // calls the array overload - } - -.SH Output: - - Vector overload: 1 2 3 - Array overload: 1 2 3 + Member type Definition + type std::basic_const_iterator> (1-3) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + common_type determines the common type of a group of types + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::common_with.3 b/man/std::common_with.3 new file mode 100644 index 000000000..8b7a9da3d --- /dev/null +++ b/man/std::common_with.3 @@ -0,0 +1,55 @@ +.TH std::common_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::common_with \- std::common_with + +.SH Synopsis + Defined in header + template< class T, class U > + + concept common_with = + std::same_as, std::common_type_t> + && + requires { + static_cast>(std::declval()); + static_cast>(std::declval()); + } && \fI(since C++20)\fP + std::common_reference_with< + std::add_lvalue_reference_t, + std::add_lvalue_reference_t> && + std::common_reference_with< + std::add_lvalue_reference_t>, + std::common_reference_t< + std::add_lvalue_reference_t, + + std::add_lvalue_reference_t>>; + + The concept common_with specifies that two types T and U share a common type + (as computed by std::common_type_t) to which both can be converted. + + Semantic requirements + + T and U model std::common_with only if, given equality-preserving expressions + t1, t2, u1 and u2 such that decltype((t1)) and decltype((t2)) are both T and + decltype((u1)) and decltype((u2)) are both U, + + * std::common_type_t(t1) equals std::common_type_t(t2) if and only if + t1 equals t2; and + * std::common_type_t(u1) equals std::common_type_t(u2) if and only if + u1 equals u2. + + In other words, the conversion to the common type must preserve equality. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH See also + + common_type determines the common type of a group of types + \fI(C++11)\fP \fI(class template)\fP + common_reference determines the common reference type of a group of types + basic_common_reference \fI(class template)\fP + (C++20) + common_reference_with specifies that two types share a common reference type + (C++20) (concept) diff --git a/man/std::comp_ellint_1,std::comp_ellint_1f,std::comp_ellint_1l.3 b/man/std::comp_ellint_1,std::comp_ellint_1f,std::comp_ellint_1l.3 new file mode 100644 index 000000000..867b49493 --- /dev/null +++ b/man/std::comp_ellint_1,std::comp_ellint_1f,std::comp_ellint_1l.3 @@ -0,0 +1,83 @@ +.TH std::comp_ellint_1,std::comp_ellint_1f,std::comp_ellint_1l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::comp_ellint_1,std::comp_ellint_1f,std::comp_ellint_1l \- std::comp_ellint_1,std::comp_ellint_1f,std::comp_ellint_1l + +.SH Synopsis + double comp_ellint_1( double arg ); + + double comp_ellint_1( float arg ); + double comp_ellint_1( long double arg ); \fB(1)\fP + float comp_ellint_1f( float arg ); + + long double comp_ellint_1l( long double arg ); + double comp_ellint_1( IntegralType arg ); \fB(2)\fP + + 1) Computes the complete elliptic integral of the first kind of arg. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, comp_ellint_1 is only guaranteed to be available in + if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at + least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + +.SH Parameters + + arg - value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the complete elliptic integral of the first kind of + arg, that is ellint_1(arg, π/2), is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If |arg| > 1, a domain error may occur. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + int main() + { + double hpi = std::acos(-1) / 2; + std::cout << "K(0) = " << std::comp_ellint_1(0) << '\\n' + << "π/2 = " << hpi << '\\n' + << "K(0.5) = " << std::comp_ellint_1(0.5) << '\\n' + << "F(0.5, π/2) = " << std::ellint_1(0.5, hpi) << '\\n'; + } + +.SH Output: + + K\fB(0)\fP = 1.5708 + π/2 = 1.5708 + K(0.5) = 1.68575 + F(0.5, π/2) = 1.68575 + +.SH External links + + Weisstein, Eric W. "Complete Elliptic Integral of the First Kind." From MathWorld--A + Wolfram Web Resource. + +.SH See also + + ellint_1 (incomplete) elliptic integral of the first kind + ellint_1f \fI(function)\fP + ellint_1l diff --git a/man/std::comp_ellint_2,std::comp_ellint_2f,std::comp_ellint_2l.3 b/man/std::comp_ellint_2,std::comp_ellint_2f,std::comp_ellint_2l.3 new file mode 100644 index 000000000..27e400ad2 --- /dev/null +++ b/man/std::comp_ellint_2,std::comp_ellint_2f,std::comp_ellint_2l.3 @@ -0,0 +1,83 @@ +.TH std::comp_ellint_2,std::comp_ellint_2f,std::comp_ellint_2l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::comp_ellint_2,std::comp_ellint_2f,std::comp_ellint_2l \- std::comp_ellint_2,std::comp_ellint_2f,std::comp_ellint_2l + +.SH Synopsis + double comp_ellint_2( double arg ); + + double comp_ellint_2( float arg ); + double comp_ellint_2( long double arg ); \fB(1)\fP + float comp_ellint_2f( float arg ); + + long double comp_ellint_2l( long double arg ); + double comp_ellint_2( IntegralType arg ); \fB(2)\fP + + 1) Computes the complete elliptic integral of the second kind of arg. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, comp_ellint_2 is only guaranteed to be available in + if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at + least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + +.SH Parameters + + arg - value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the complete elliptic integral of the second kind of + arg, that is ellint_2(arg, π/2), is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If |arg| > 1, a domain error may occur. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + int main() + { + double hpi = std::acos(-1) / 2; + std::cout << "E(0) = " << std::comp_ellint_2(0) << '\\n' + << "π/2 = " << hpi << '\\n' + << "E(0.5) = " << std::comp_ellint_2(0.5) << '\\n' + << "E(0.5, π/2) = " << std::ellint_2(0.5, hpi) << '\\n'; + } + +.SH Output: + + E\fB(0)\fP = 1.5708 + π/2 = 1.5708 + E(0.5) = 1.46746 + E(0.5, π/2) = 1.46746 + +.SH External links + + Weisstein, Eric W. "Complete Elliptic Integral of the Second Kind." From + MathWorld--A Wolfram Web Resource. + +.SH See also + + ellint_2 (incomplete) elliptic integral of the second kind + ellint_2f \fI(function)\fP + ellint_2l diff --git a/man/std::comp_ellint_3,std::comp_ellint_3f,std::comp_ellint_3l.3 b/man/std::comp_ellint_3,std::comp_ellint_3f,std::comp_ellint_3l.3 new file mode 100644 index 000000000..483ea2f79 --- /dev/null +++ b/man/std::comp_ellint_3,std::comp_ellint_3f,std::comp_ellint_3l.3 @@ -0,0 +1,84 @@ +.TH std::comp_ellint_3,std::comp_ellint_3f,std::comp_ellint_3l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::comp_ellint_3,std::comp_ellint_3f,std::comp_ellint_3l \- std::comp_ellint_3,std::comp_ellint_3f,std::comp_ellint_3l + +.SH Synopsis + double comp_ellint_3( double k, double nu ); + + float comp_ellint_3( float k, float nu ); + long double comp_ellint_3( long double k, long double nu ); \fB(1)\fP + float comp_ellint_3f( float k, float nu ); + + long double comp_ellint_3l( long double k, long double nu ); + double comp_ellint_3( IntegralType k, IntegralType nu ); \fB(2)\fP + + 1) Computes the complete elliptic integral of the third kind of arg. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, comp_ellint_3 is only guaranteed to be available in + if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at + least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + +.SH Parameters + + nu - value of a floating-point or integral type + k - value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the complete elliptic integral of the second kind of + arg, that is ellint_3(k, nu, π/2), is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If either |k| > 1 or |nu| > 1, a domain error may occur. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + int main() + { + double hpi = std::acos(-1) / 2; + std::cout << "Π(0, 0.75) = " << std::comp_ellint_3(0, 0.75) << '\\n' + << "π/2 = " << hpi << '\\n' + << "Π(0.5, 0.75) = " << std::comp_ellint_3(0.5, 0.75) << '\\n' + << "Π(0.5, 0.75, π/2) = " << std::ellint_3(0.5, 0.75, hpi) << '\\n'; + } + +.SH Output: + + Π(0, 0.75) = 3.14159 + π/2 = 1.5708 + Π(0.5, 0.75) = 3.45372 + Π(0.5, 0.75, π/2) = 3.45372 + +.SH External links + + Weisstein, Eric W. "Complete Elliptic Integral of the Third Kind." From MathWorld--A + Wolfram Web Resource. + +.SH See also + + ellint_3 (incomplete) elliptic integral of the third kind + ellint_3f \fI(function)\fP + ellint_3l diff --git a/man/std::compare_partial_order_fallback.3 b/man/std::compare_partial_order_fallback.3 new file mode 100644 index 000000000..6b6a53c07 --- /dev/null +++ b/man/std::compare_partial_order_fallback.3 @@ -0,0 +1,65 @@ +.TH std::compare_partial_order_fallback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::compare_partial_order_fallback \- std::compare_partial_order_fallback + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ \fI(since C++20)\fP + compare_partial_order_fallback = /* unspecified */; + + } + Call signature + template< class T, class U > + + requires /* see below */ + constexpr std::partial_ordering \fI(since C++20)\fP + + compare_partial_order_fallback( T&& t, U&& u ) noexcept(/* see + below */); + + Performs three-way comparison on subexpressions t and u and produces a result of + type std::partial_ordering, even if the operator <=> is unavailable. + + If std::decay_t and std::decay_t> are the same type, + std::compare_partial_order_fallback(t, u) is expression-equivalent to: + + * std::partial_order(t, u), if it is a well-formed expression; + * otherwise, t == u ? std::partial_ordering::equivalent : + t < u ? std::partial_ordering::less : + u < t ? std::partial_ordering::greater : +          std::partial_ordering::unordered + + if the expressions t == u, t < u and u < t are all well-formed and each of + decltype(t == u) and decltype(t < u) models boolean-testable, except that t and u + are evaluated only once. + + In all other cases, std::compare_partial_order_fallback(t, u) is ill-formed, which + can result in substitution failure when it appears in the immediate context of a + template instantiation. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2114 C++20 the fallback mechanism only required constraints strengthened + (P2167R3) return types to be convertible to bool + LWG 3465 C++20 the fallback mechanism did not require required + u < t to be well-formed + +.SH See also + + partial_order performs 3-way comparison and produces a result of type + (C++20) std::partial_ordering + (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::compare_strong_order_fallback.3 b/man/std::compare_strong_order_fallback.3 new file mode 100644 index 000000000..4ec118fbe --- /dev/null +++ b/man/std::compare_strong_order_fallback.3 @@ -0,0 +1,62 @@ +.TH std::compare_strong_order_fallback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::compare_strong_order_fallback \- std::compare_strong_order_fallback + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ \fI(since C++20)\fP + compare_strong_order_fallback = /* unspecified */; + + } + Call signature + template< class T, class U > + + requires /* see below */ + constexpr std::strong_ordering \fI(since C++20)\fP + + compare_strong_order_fallback( T&& t, U&& u ) noexcept(/* see + below */); + + Performs three-way comparison on subexpressions t and u and produces a result of + type std::strong_ordering, even if the operator <=> is unavailable. + + If std::decay_t and std::decay_t are the same type, + std::compare_strong_order_fallback(t, u) is expression-equivalent to: + + * std::strong_order(t, u), if it is a well-formed expression; + * otherwise, t == u ? std::strong_ordering::equal : + t < u ? std::strong_ordering::less : +          std::strong_ordering::greater + + if the expressions t == u and t < u are both well-formed and each of decltype(t == + u) and decltype(t < u) models boolean-testable, except that t and u are evaluated + only once. + + In all other cases, std::compare_strong_order_fallback(t, u) is ill-formed, which + can result in substitution failure when it appears in the immediate context of a + template instantiation. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2114 C++20 the fallback mechanism only required constraints strengthened + (P2167R3) return types to be convertible to bool + +.SH See also + + strong_order performs 3-way comparison and produces a result of type + (C++20) std::strong_ordering + (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::compare_three_way.3 b/man/std::compare_three_way.3 new file mode 100644 index 000000000..0438d2c22 --- /dev/null +++ b/man/std::compare_three_way.3 @@ -0,0 +1,111 @@ +.TH std::compare_three_way 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::compare_three_way \- std::compare_three_way + +.SH Synopsis + Defined in header + Defined in header + struct compare_three_way; \fI(since C++20)\fP + + Function object for performing comparisons. Deduces the parameter types and the + return type of the function call operator. + +.SH Member functions + + operator() obtains the result of three-way comparison on both arguments + \fI(public member function)\fP + +std::compare_three_way::operator() + + template< class T, class U > + constexpr auto operator()( T&& t, U&& u ) const; + + Given the expression std::forward(t) <=> std::forward(u) as expr: + + * If expr results in a call to built-in operator<=> comparing pointers, given the + composite pointer type of t and u as P: + + * Compares the two converted pointers (of type P) in the implementation-defined + strict total order over pointers: + + * If t precedes u, returns std::strong_ordering::less. + * If u precedes t, returns std::strong_ordering::greater. + * Otherwise, returns std::strong_ordering::equal. + * If the conversion sequence from T to P or the conversion sequence from U to P is + not equality-preserving, the behavior is undefined. + * Otherwise: + + * Returns the result of expr. + * If std::three_way_comparable_with is not modeled, the behavior is + undefined. + + This overload participates in overload resolution only if + std::three_way_comparable_with is satisfied. + +.SH Example + + +// Run this code + + #include + #include + + struct Rational + { + int num; + int den; // > 0 + + // Although the comparison X <=> Y will work, a direct call + // to std::compare_three_way{}(X, Y) requires the operator== + // be defined, to satisfy the std::three_way_comparable_with. + constexpr bool operator==(Rational const&) const = default; + }; + + constexpr std::weak_ordering operator<=>(Rational lhs, Rational rhs) + { + return lhs.num * rhs.den <=> rhs.num * lhs.den; + } + + void print(std::weak_ordering value) + { + value < 0 ? std::cout << "less\\n" : + value > 0 ? std::cout << "greater\\n" : + std::cout << "equal\\n"; + } + + int main() + { + Rational a{6, 5}; + Rational b{8, 7}; + print(a <=> b); + print(std::compare_three_way{}(a, b)); + } + +.SH Output: + + greater + greater + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + ranges::equal_to constrained function object implementing x == y + (C++20) \fI(class)\fP + ranges::not_equal_to constrained function object implementing x != y + (C++20) \fI(class)\fP + ranges::less constrained function object implementing x < y + (C++20) \fI(class)\fP + ranges::greater constrained function object implementing x > y + (C++20) \fI(class)\fP + ranges::less_equal constrained function object implementing x <= y + (C++20) \fI(class)\fP + ranges::greater_equal constrained function object implementing x >= y + (C++20) \fI(class)\fP diff --git a/man/std::compare_three_way_result.3 b/man/std::compare_three_way_result.3 new file mode 100644 index 000000000..e599aa58f --- /dev/null +++ b/man/std::compare_three_way_result.3 @@ -0,0 +1,92 @@ +.TH std::compare_three_way_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::compare_three_way_result \- std::compare_three_way_result + +.SH Synopsis + Defined in header + template< class T, class U = T > \fI(since C++20)\fP + struct compare_three_way_result; + + Let t and u denote lvalue of const std::remove_reference_t and const + std::remove_reference_t respectively, if the expression t <=> u is well-formed, + provides the member typedef type equal to decltype(t <=> u), otherwise there is no + member type. + + If the program adds specializations for std::compare_three_way_result, the behavior + is undefined. + +.SH Member types + + Name Definition + type the result type of operator<=> on const-qualified lvalue of T and U + +.SH Helper types + + template< class T, class U = T > + using compare_three_way_result_t = compare_three_way_result::type; + +.SH Possible implementation + + // recommended by Casey Carter + // see also: https://github.com/microsoft/STL/pull/385#discussion_r357894054 + template + using compare_three_way_result_t = decltype( + std::declval&>() <=> + std::declval&>() + ); + + template + struct compare_three_way_result {}; + + template + requires requires { typename compare_three_way_result_t; } + struct compare_three_way_result + { + using type = compare_three_way_result_t; + }; + +.SH Example + + +// Run this code + + #include + #include + #include + + template + void print_cmp_type() + { + if constexpr (std::is_same_v) + std::cout << "strong ordering\\n"; + else if constexpr (std::is_same_v) + std::cout << "weak ordering\\n"; + else if constexpr (std::is_same_v) + std::cout << "partial ordering\\n"; + else + std::cout << "illegal comparison result type\\n"; + } + + int main() + { + print_cmp_type>(); + print_cmp_type>(); + } + +.SH Output: + + strong ordering + partial ordering + +.SH See also + + partial_ordering the result type of 3-way comparison that supports all 6 operators, + (C++20) is not substitutable, and allows incomparable values + \fI(class)\fP + weak_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is not substitutable + \fI(class)\fP + strong_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is substitutable + \fI(class)\fP diff --git a/man/std::compare_weak_order_fallback.3 b/man/std::compare_weak_order_fallback.3 new file mode 100644 index 000000000..b655ade4c --- /dev/null +++ b/man/std::compare_weak_order_fallback.3 @@ -0,0 +1,128 @@ +.TH std::compare_weak_order_fallback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::compare_weak_order_fallback \- std::compare_weak_order_fallback + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ \fI(since C++20)\fP + compare_weak_order_fallback = /* unspecified */; + + } + Call signature + template< class T, class U > + + requires /* see below */ + constexpr std::weak_ordering \fI(since C++20)\fP + + compare_weak_order_fallback( T&& t, U&& u ) noexcept(/* see below + */); + + Performs three-way comparison on subexpressions t and u and produces a result of + type std::weak_ordering, even if the operator <=> is unavailable. + + If std::decay_t and std::decay_t are the same type, + std::compare_weak_order_fallback(t, u) is expression-equivalent to: + + * std::weak_order(t, u), if it is a well-formed expression; otherwise, + * t == u ? std::weak_ordering::equivalent : + t < u ? std::weak_ordering::less : +          std::weak_ordering::greater, if the expressions t == u and t < u are + both well-formed and each of decltype(t == u) and decltype(t < u) models + boolean-testable, except that t and u are evaluated only once. + + In all other cases, std::compare_weak_order_fallback(t, u) is ill-formed, which can + result in substitution failure when it appears in the immediate context of a + template instantiation. + +.SH Example + + +// Run this code + + #include + #include + + // does not support <=> + struct Rational_1 + { + int num; + int den; // > 0 + }; + + inline constexpr bool operator<(Rational_1 lhs, Rational_1 rhs) + { + return lhs.num * rhs.den < rhs.num * lhs.den; + } + + inline constexpr bool operator==(Rational_1 lhs, Rational_1 rhs) + { + return lhs.num * rhs.den == rhs.num * lhs.den; + } + + // supports <=> + struct Rational_2 + { + int num; + int den; // > 0 + }; + + inline constexpr std::weak_ordering operator<=>(Rational_2 lhs, Rational_2 rhs) + { + return lhs.num * rhs.den <=> rhs.num * lhs.den; + } + + inline constexpr bool operator==(Rational_2 lhs, Rational_2 rhs) + { + return lhs <=> rhs == 0; + } + + void print(int id, std::weak_ordering value) + { + std::cout << id << ") "; + if (value == 0) + std::cout << "equal\\n"; + else if (value < 0) + std::cout << "less\\n"; + else + std::cout << "greater\\n"; + } + + int main() + { + Rational_1 a{1, 2}, b{3, 4}; + // print(0, a <=> b); // does not work + print(1, std::compare_weak_order_fallback(a, b)); // works, defaults to < and == + + Rational_2 c{6, 5}, d{8, 7}; + print(2, c <=> d); // works + print(3, std::compare_weak_order_fallback(c, d)); // works + + Rational_2 e{2, 3}, f{4, 6}; + print(4, e <=> f); // works + print(5, std::compare_weak_order_fallback(e, f)); // works + } + +.SH Output: + + 1) less + 2) greater + 3) greater + 4) equal + 5) equal + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2114 C++20 the fallback mechanism only required constraints strengthened + (P2167R3) return types to be convertible to bool + +.SH See also + + weak_order performs 3-way comparison and produces a result of type + (C++20) std::weak_ordering + (customization point object) diff --git a/man/std::complex.3 b/man/std::complex.3 index dc0483778..07231c69f 100644 --- a/man/std::complex.3 +++ b/man/std::complex.3 @@ -1,16 +1,27 @@ -.TH std::complex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::complex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::complex \- std::complex + .SH Synopsis Defined in header template< class T > \fB(1)\fP class complex; - template<> class complex; \fB(2)\fP - template<> class complex; \fB(3)\fP - template<> class complex; \fB(4)\fP + template<> class complex; \fB(2)\fP (until C++23) + template<> class complex; \fB(3)\fP (until C++23) + template<> class complex; \fB(4)\fP (until C++23) + + Specializations of std::complex for cv-unqualified + standard + (until C++23) floating-point types are + TriviallyCopyable + (since C++23) LiteralTypes for representing and manipulating complex number. - The specializations std::complex, std::complex, and std::complex are literal types for representing and manipulating complex numbers. +.SH Template parameters - The effect of instantiating the template complex for any other type is unspecified. + the type of the real and imaginary parts. The behavior is unspecified (and may + T - fail to compile) if T is not a cv-unqualified + standard + (until C++23) floating-point type and undefined if T is not NumericType. .SH Member types @@ -22,106 +33,202 @@ constructor constructs a complex number \fI(public member function)\fP operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP real accesses the real part of the complex number - \fI(public member function)\fP + \fI(public member function)\fP imag accesses the imaginary part of the complex number - \fI(public member function)\fP + \fI(public member function)\fP operator+= operator-= compound assignment of two complex numbers or a complex and a scalar - operator/= \fI(public member function)\fP - operator*= + operator*= \fI(public member function)\fP + operator/= .SH Non-member functions operator+ applies unary operators to complex numbers - operator- \fI(function template)\fP - operator+ performs complex number arithmetics on two complex values or a + operator- \fI(function template)\fP + operator+ performs complex number arithmetic on two complex values or a operator- complex and a scalar - operator* \fI(function template)\fP + operator* \fI(function template)\fP operator/ operator== compares two complex numbers or a complex and a scalar - operator!= \fI(function template)\fP + operator!= \fI(function template)\fP + (removed in C++20) operator<< serializes and deserializes a complex number - operator>> \fI(function template)\fP - real returns the real component - \fI(function template)\fP - imag returns the imaginary component - \fI(function template)\fP + operator>> \fI(function template)\fP + get(std::complex) obtains a reference to real or imaginary part from a + (C++26) std::complex + \fI(function template)\fP + real returns the real part + \fI(function template)\fP + imag returns the imaginary part + \fI(function template)\fP abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP + \fI(function template)\fP arg returns the phase angle - \fI(function template)\fP + \fI(function template)\fP norm returns the squared magnitude - \fI(function template)\fP + \fI(function template)\fP conj returns the complex conjugate - \fI(function template)\fP + \fI(function template)\fP proj returns the projection onto the Riemann sphere - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP polar constructs a complex number from magnitude and phase angle - \fI(function template)\fP + \fI(function template)\fP .SH Exponential functions exp(std::complex) complex base e exponential - \fI(function template)\fP + \fI(function template)\fP complex natural logarithm with the branch cuts along the log(std::complex) negative real axis - \fI(function template)\fP + \fI(function template)\fP complex common logarithm with the branch cuts along the negative log10(std::complex) real axis - \fI(function template)\fP + \fI(function template)\fP .SH Power functions pow(std::complex) complex power, one or both arguments may be a complex number - \fI(function template)\fP + \fI(function template)\fP sqrt(std::complex) complex square root in the range of the right half-plane - \fI(function template)\fP + \fI(function template)\fP .SH Trigonometric functions - sin(std::complex) computes sine of a complex number (sin(z)) - \fI(function template)\fP - cos(std::complex) computes cosine of a complex number (cos(z)) - \fI(function template)\fP - tan(std::complex) computes tangent of a complex number (tan(z)) - \fI(function template)\fP - asin(std::complex) computes arc sine of a complex number (arcsin(z)) - \fI(C++11)\fP \fI(function template)\fP - acos(std::complex) computes arc cosine of a complex number (arccos(z)) - \fI(C++11)\fP \fI(function template)\fP - atan(std::complex) computes arc tangent of a complex number (arctan(z)) - \fI(C++11)\fP \fI(function template)\fP + sin(std::complex) computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z)) + \fI(function template)\fP + cos(std::complex) computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z)) + \fI(function template)\fP + tan(std::complex) computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z)) + \fI(function template)\fP + asin(std::complex) computes arc sine of a complex number + \fI(C++11)\fP (\\({\\small\\arcsin{z}}\\)arcsin(z)) + \fI(function template)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP + atan(std::complex) computes arc tangent of a complex number + \fI(C++11)\fP (\\({\\small\\arctan{z}}\\)arctan(z)) + \fI(function template)\fP .SH Hyperbolic functions - sinh(std::complex) computes hyperbolic sine of a complex number (sh(z)) - \fI(function template)\fP - cosh(std::complex) computes hyperbolic cosine of a complex number (ch(z)) - \fI(function template)\fP - tanh(std::complex) computes hyperbolic tangent of a complex number - \fI(function template)\fP + computes hyperbolic sine of a complex number + sinh(std::complex) (\\({\\small\\sinh{z}}\\)sinh(z)) + \fI(function template)\fP + computes hyperbolic cosine of a complex number + cosh(std::complex) (\\({\\small\\cosh{z}}\\)cosh(z)) + \fI(function template)\fP + computes hyperbolic tangent of a complex number + tanh(std::complex) (\\({\\small\\tanh{z}}\\)tanh(z)) + \fI(function template)\fP asinh(std::complex) computes area hyperbolic sine of a complex number - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP (\\({\\small\\operatorname{arsinh}{z}}\\)arsinh(z)) + \fI(function template)\fP acosh(std::complex) computes area hyperbolic cosine of a complex number - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP (\\({\\small\\operatorname{arcosh}{z}}\\)arcosh(z)) + \fI(function template)\fP atanh(std::complex) computes area hyperbolic tangent of a complex number - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP (\\({\\small\\operatorname{artanh}{z}}\\)artanh(z)) + \fI(function template)\fP + +.SH Helper types + + std::tuple_size obtains the number of components of a std::complex + (C++26) \fI(class template specialization)\fP + std::tuple_element obtains the underlying real and imaginary number + (C++26) type of a std::complex + \fI(class template specialization)\fP + + Array-oriented access -.SH Non-static data members + For any object z of type std::complex, reinterpret_cast(z)[0] is the + real part of z and reinterpret_cast(z)[1] is the imaginary part of z. - For any object z of type complex, reinterpret_cast(z)[0] - is the real part of z and reinterpret_cast(z)[1] is the - imaginary part of z. + For any pointer to an element of an array of std::complex named p and any valid + array index i, reinterpret_cast(p)[2 * i] is the real part of the complex number + p[i], and reinterpret_cast(p)[2 * i + 1] is the imaginary part of the complex + number p[i]. - For any pointer to an element of an array of complex named p and - any valid array index i, reinterpret_cast(p)[2*i] is the real part - of the complex number p[i], and reinterpret_cast(p)[2*i + 1] is \fI(since C++11)\fP - the imaginary part of the complex number p[i] + The intent of this requirement is to preserve binary compatibility between the C++ + library complex number types and the C language complex number types (and arrays + thereof), which have an identical object representation requirement. - These requirements essentially limit implementation of each of the - three specializations of std::complex to declaring two and only two - non-static data members, of type value_type, with the same member - access, which hold the real and the imaginary components, - respectively. +.SH Implementation notes + + In order to satisfy the requirements of array-oriented access, an implementation is + constrained to store the real and imaginary parts of a std::complex specialization + in separate and adjacent memory locations. Possible declarations for its non-static + data members include: + + * an array of type value_type[2], with the first element holding the real part and + the second element holding the imaginary part (e.g. Microsoft Visual Studio); + * a single member of type value_type _Complex (encapsulating the corresponding C + language complex number type) (e.g. GNU libstdc++); + * two members of type value_type, with the same member access, holding the real + and the imaginary parts respectively (e.g. LLVM libc++). + + An implementation cannot declare additional non-static data members that would + occupy storage disjoint from the real and imaginary parts, and must ensure that the + class template specialization does not contain any padding bit. The implementation + must also ensure that optimizations to array access account for the possibility that + a pointer to value_type may be aliasing a std::complex specialization or array + thereof. .SH Literals Defined in inline namespace std::literals::complex_literals operator""if - operator""i A std::complex literal representing pure imaginary number - operator""il \fI(function)\fP + operator""i a std::complex literal representing purely imaginary number + operator""il \fI(function)\fP \fI(C++14)\fP + +.SH Notes + + Feature-test macro Value Std Feature + 201711L (C++20) Constexpr simple complex mathematical + __cpp_lib_constexpr_complex functions in + 202306L (C++26) More constexpr for + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::complex_literals; + std::cout << std::fixed << std::setprecision(1); + + std::complex z1 = 1i * 1i; // imaginary unit squared + std::cout << "i * i = " << z1 << '\\n'; + + std::complex z2 = std::pow(1i, 2); // imaginary unit squared + std::cout << "pow(i, 2) = " << z2 << '\\n'; + + const double PI = std::acos(-1); // or std::numbers::pi in C++20 + std::complex z3 = std::exp(1i * PI); // Euler's formula + std::cout << "exp(i * pi) = " << z3 << '\\n'; + + std::complex z4 = 1.0 + 2i, z5 = 1.0 - 2i; // conjugates + std::cout << "(1 + 2i) * (1 - 2i) = " << z4 * z5 << '\\n'; + } + +.SH Output: + + i * i = (-1.0,0.0) + pow(i, 2) = (-1.0,0.0) + exp(i * pi) = (-1.0,0.0) + (1 + 2i) * (1 - 2i) = (5.0,0.0) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 387 C++98 std::complex was not guaranteed to be guaranteed to be + compatible with C complex compatible + +.SH See also + + C documentation for + Complex number arithmetic diff --git a/man/std::complex::complex.3 b/man/std::complex::complex.3 index 93ad8e215..afb289716 100644 --- a/man/std::complex::complex.3 +++ b/man/std::complex::complex.3 @@ -1,51 +1,170 @@ -.TH std::complex::complex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::complex::complex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::complex::complex \- std::complex::complex + .SH Synopsis - primary template complex - complex( const T& re = T(), const T& im = T() ); \fB(1)\fP \fI(until C++14)\fP - constexpr complex( const T& re = T(), const T& im = T() ); \fB(1)\fP \fI(since C++14)\fP - complex( const complex& other ); \fB(2)\fP \fI(until C++14)\fP - constexpr complex( const complex& other ); \fB(2)\fP \fI(since C++14)\fP - template< class X > \fB(3)\fP \fI(until C++14)\fP - complex( const complex& other); - template< class X > \fB(3)\fP \fI(since C++14)\fP - constexpr complex( const complex& other); - specialization complex - complex(float re = 0.0f, float im = 0.0f); \fB(1)\fP \fI(until C++11)\fP - constexpr complex(float re = 0.0f, float im = 0.0f); \fB(1)\fP \fI(since C++11)\fP - explicit complex(const complex& other); \fB(3)\fP \fI(until C++11)\fP - explicit complex(const complex& other); - explicit constexpr complex(const complex& other); \fB(3)\fP \fI(since C++11)\fP - explicit constexpr complex(const complex& other); - specialization complex - complex(double re = 0.0, double im = 0.0); \fB(1)\fP \fI(until C++11)\fP - constexpr complex(double re = 0.0, double im = 0.0); \fB(1)\fP \fI(since C++11)\fP - complex(const complex& other); \fB(3)\fP \fI(until C++11)\fP - explicit complex(const complex& other); - constexpr complex(const complex& other); \fB(3)\fP \fI(since C++11)\fP - explicit constexpr complex(const complex& other); - specialization complex - complex(long double re = 0.0L, long double im = 0.0L); \fB(1)\fP \fI(until C++11)\fP - constexpr complex(long double re = 0.0L, long double im = 0.0L); \fB(1)\fP \fI(since C++11)\fP - complex(const complex& other); \fB(3)\fP \fI(until C++11)\fP - complex(const complex& other); - constexpr complex(const complex& other); \fB(3)\fP \fI(since C++11)\fP - constexpr complex(const complex& other); +Primary template +(std::complex) +complex( const T& re (until += T(), const T& im = C++14) +T() ); +constexpr complex( (since +const T& re = T(), C++14) +const T& im = T() ); +complex( const (until +complex& other ); C++14) +constexpr complex( (since +const complex& other C++14) +); (until + C++23) +constexpr complex( (since +const complex& other C++23) +) = default; +template< class X > (until +complex( const C++14) +complex& other ); +template< class X > (since +constexpr complex( C++14) +const complex& (until +other ); C++23) +template< class X > +constexpr +explicit(/* see (since +below */) complex( C++23) +const complex& +other ); +Standard explicit +specialization +std::complex +(until C++23) +complex( float re = (until +0.0f, float im = C++11) +0.0f ); +constexpr complex( (since +float re = 0.0f, C++11) +float im = 0.0f ); +constexpr complex( +const \fB(2)\fP (since +complex& C++20) +other ) = default; +explicit complex( +const +complex& (until +other ); C++11) +explicit complex( +const complex& other ); +constexpr explicit +complex( const +complex& +other ); (since +constexpr explicit C++11) +complex( const +complex& other ); +Standard explicit \fB(1)\fP +specialization +std::complex +(until C++23) \fB(2)\fP +complex( double re = (until +0.0, double im = 0.0 C++11) +); +constexpr complex( \fB(3)\fP (since +double re = 0.0, C++11) +double im = 0.0 ); +constexpr complex( +const \fB(2)\fP (since +complex& C++20) +other ) = default; +complex( const +complex& +other ); \fB(1)\fP (until +explicit complex( C++11) +const complex& other ); +constexpr complex( +const \fB(3)\fP +complex& +other ); (since +constexpr explicit C++11) +complex( const +complex& other ); +Standard explicit +specialization +std::complex (until +C++23) +complex( long double (until +re = 0.0L, long C++11) +double im = 0.0L ); \fB(3)\fP +constexpr complex( +long double re = (since +0.0L, long double im C++11) += 0.0L ); +constexpr complex( +const complex& other ) = C++20) +default; +complex( const +complex& \fB(1)\fP +other ); (until +complex( const C++11) +complex& +other ); +constexpr complex( \fB(3)\fP +const +complex& +other ); (since +constexpr complex( C++11) +const +complex& +other ); Constructs the std::complex object. + The standard explicit specializations (std::complex, std::complex and + std::complex) have different constructor declarations from the main + template. + (until C++23) - 1) Constructs the complex number from real and imaginary parts. + 1) Constructs the complex number from real part re and imaginary part im. 2) Copy constructor. Constructs the object with the copy of the contents of other. - The copy constructor is implicit in the standard specializations. + The copy constructors are implicitly declared in the standard explicit + specializations. + \fI(until C++20)\fP 3) Converting constructor. Constructs the object from a complex number of a different type. + The main template provides a converting constructor template, while + each standard explicit specialization provides two non-template + constructors for the two other standard explicit specializations. + (until C++23) + The non-template constructors are converting constructors (i.e. + non-explicit) if and only if the conversions of the real and imaginary + parts are not narrowing. + For the main template, the expression inside explicit evaluates to + false if and only if the floating-point conversion rank of T is (since C++23) + greater than or equal to the floating-point conversion rank of X. + .SH Parameters re - the real part im - the imaginary part - other - another complex to use as source + other - another complex number to use as source + +.SH Notes + + Since C++23, the copy constructor is required to be trivial in order to satisfy the + TriviallyCopyable requirement, but implementations generally make it trivial in all + modes. .SH See also - operator= assigns the contents - \fI(public member function)\fP + operator= assigns the contents + \fI(public member function)\fP + operator""if + operator""i a std::complex literal representing purely imaginary number + operator""il \fI(function)\fP + \fI(C++14)\fP + C documentation for + CMPLX diff --git a/man/std::complex::imag.3 b/man/std::complex::imag.3 index 254367d12..d68fa3d8f 100644 --- a/man/std::complex::imag.3 +++ b/man/std::complex::imag.3 @@ -1,27 +1,49 @@ -.TH std::complex::imag 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::complex::imag 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::complex::imag \- std::complex::imag + .SH Synopsis - primary template complex - T imag() const; \fB(1)\fP \fI(until C++14)\fP - constexpr T imag() const; \fB(1)\fP \fI(since C++14)\fP - void imag( T value ); \fB(2)\fP - specialization complex - float imag() const; \fB(1)\fP \fI(until C++11)\fP - constexpr float imag(); \fB(1)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr float imag() const; \fB(1)\fP \fI(since C++14)\fP - void imag( float value ); \fB(2)\fP - specialization complex - double imag() const; \fB(1)\fP \fI(until C++11)\fP - constexpr double imag(); \fB(1)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr double imag() const; \fB(1)\fP \fI(since C++14)\fP - void imag( double value ); \fB(2)\fP - specialization complex - long double imag() const; \fB(1)\fP \fI(until C++11)\fP - constexpr long double imag(); \fB(1)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr long double imag() const; \fB(1)\fP \fI(since C++14)\fP - void imag( long double value ); \fB(2)\fP + primary template + std::complex + T imag() const; (until + C++14) + constexpr T imag() (since + const; C++14) + void imag( T value (until + ); C++20) + constexpr void imag( (since + T value ); C++20) + specialization + std::complex + float imag() const; (until + C++11) + constexpr float (since + imag() const; C++11) + void imag( float (until + value ); C++20) + constexpr void imag( (since + float value ); C++20) + specialization + std::complex \fB(1)\fP + double imag() const; (until + \fB(2)\fP C++11) + constexpr double (since + imag() const; C++11) + void imag( double \fB(1)\fP (until + value ); C++20) + constexpr void imag( \fB(2)\fP (since + double value ); C++20) + specialization + std::complex + long double imag() \fB(2)\fP (until + const; C++11) + constexpr long (since + double imag() const; \fB(1)\fP C++11) + void imag( long (until + double value ); \fB(2)\fP C++20) + constexpr void imag( (since + long double value ); C++20) Accesses the imaginary part of the complex number. @@ -32,7 +54,29 @@ value - the value to set the imaginary part to +.SH Return value + + 1) The imaginary part of *this. + 2) \fI(none)\fP + +.SH Notes + + In C++11, overload \fB(1)\fP in std::complex specializations used to be specified without + const qualifier. However, in C++11, a constexpr specifier used in a non-static + member function implies const, and thus the behavior is as if const is specified. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 387 C++98 the imaginary part could not be set can be set directly via a new + directly imag overload + .SH See also + imag returns the imaginary part + \fI(function template)\fP real accesses the real part of the complex number - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::complex::operator+(unary),operator-(unary).3 b/man/std::complex::operator+(unary),operator-(unary).3 index fbef933b3..7bc2f6c55 100644 --- a/man/std::complex::operator+(unary),operator-(unary).3 +++ b/man/std::complex::operator+(unary),operator-(unary).3 @@ -1,9 +1,20 @@ -.TH std::complex::operator+(unary),operator-(unary) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::complex::operator+(unary),operator-(unary) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::complex::operator+(unary),operator-(unary) \- std::complex::operator+(unary),operator-(unary) + .SH Synopsis - template< class T > \fB(1)\fP - complex operator+( const complex& val ); - template< class T > \fB(2)\fP - complex operator-( const complex& val ); + template< class T > + std::complex operator+( const \fI(until C++20)\fP + std::complex& val ); + template< class T > + constexpr std::complex operator+( const \fI(since C++20)\fP + std::complex& val ); \fB(1)\fP + template< class T > + std::complex operator-( const \fI(until C++20)\fP + std::complex& val ); \fB(2)\fP + template< class T > + constexpr std::complex operator-( const \fI(since C++20)\fP + std::complex& val ); Implements the analogs of the unary arithmetic operators for complex numbers. @@ -16,12 +27,12 @@ .SH Return value - 1) a copy of the argument, complex(val) - 2) negated argument, complex(-val.real(), -val.imag()) + 1) a copy of the argument, std::complex(val) + 2) negated argument, std::complex(-val.real(), -val.imag()) .SH See also - operator+ performs complex number arithmetics on two complex values or a complex and + operator+ performs complex number arithmetic on two complex values or a complex and operator- a scalar - operator* \fI(function template)\fP + operator* \fI(function template)\fP operator/ diff --git a/man/std::complex::operator=.3 b/man/std::complex::operator=.3 index 64c89d27d..31425bc28 100644 --- a/man/std::complex::operator=.3 +++ b/man/std::complex::operator=.3 @@ -1,13 +1,40 @@ -.TH std::complex::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::complex::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::complex::operator= \- std::complex::operator= + .SH Synopsis - complex& operator=( const T& x ); \fB(1)\fP - complex& operator=( const complex& cx ); \fB(2)\fP + All specializations + complex& operator=( const complex& cx ); (until + C++20) + constexpr complex& operator=( const complex& (since + cx ); C++20) + template< class X > (until + complex& operator=( const std::complex& C++20) + cx ); + template< class X > (since + constexpr complex& operator=( const C++20) + std::complex& cx ); + Primary template complex + complex& operator=( const T& x ); \fB(1)\fP (until + C++20) + constexpr complex& operator=( const T& x ); \fB(2)\fP (since + C++20) + Specializations for standard floating-point + types complex (until C++23) \fB(3)\fP + complex& operator=( F x ); (until + C++20) + \fB(3)\fP (since + constexpr complex& operator=( F x ); C++20) + (until + C++23) Assigns new values to the contents. - 1) Assigns x to the real part of the complex number. Imaginary part is set to zero. - 2) Assigns cx.real() and cx.imag() to the real and the imaginary parts of the + 1,2) Assigns cx.real() and cx.imag() to the real and the imaginary parts of the complex number respectively. + The copy assignment operator \fB(1)\fP is trivial when T is a floating-point type. + (since C++23) + 3) Assigns x to the real part of the complex number. Imaginary part is set to zero. .SH Parameters @@ -17,3 +44,25 @@ .SH Return value *this + +.SH Notes + + The copy assignment operator is required to be trivial since C++23, but + implementations generally make it trivial in all modes. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3935 C++98 the description of overload \fB(2)\fP was missing added + +.SH See also + + constructor constructs a complex number + \fI(public member function)\fP + operator""if + operator""i a std::complex literal representing purely imaginary number + operator""il \fI(function)\fP + \fI(C++14)\fP diff --git a/man/std::complex::real.3 b/man/std::complex::real.3 index 1b7b73025..76b906287 100644 --- a/man/std::complex::real.3 +++ b/man/std::complex::real.3 @@ -1,27 +1,49 @@ -.TH std::complex::real 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::complex::real 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::complex::real \- std::complex::real + .SH Synopsis - primary template complex - T real() const; \fB(1)\fP \fI(until C++14)\fP - constexpr T real() const; \fB(1)\fP \fI(since C++14)\fP - void real( T value ); \fB(2)\fP - specialization complex - float real() const; \fB(1)\fP \fI(until C++11)\fP - constexpr float real(); \fB(1)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr float real() const; \fB(1)\fP \fI(since C++14)\fP - void real( float value ); \fB(2)\fP - specialization complex - double real() const; \fB(1)\fP \fI(until C++11)\fP - constexpr double real(); \fB(1)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr double real() const; \fB(1)\fP \fI(since C++14)\fP - void real( double value ); \fB(2)\fP - specialization complex - long double real() const; \fB(1)\fP \fI(until C++11)\fP - constexpr long double real(); \fB(1)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr long double real() const; \fB(1)\fP \fI(since C++14)\fP - void real( long double value ); \fB(2)\fP + primary template + std::complex + T real() const; (until + C++14) + constexpr T real() (since + const; C++14) + void real( T value (until + ); C++20) + constexpr void real( (since + T value ); C++20) + specialization + std::complex + float real() const; (until + C++11) + constexpr float (since + real() const; C++11) + void real( float (until + value ); C++20) + constexpr void real( (since + float value ); C++20) + specialization + std::complex \fB(1)\fP + double real() const; (until + \fB(2)\fP C++11) + constexpr double (since + real() const; C++11) + void real( double \fB(1)\fP (until + value ); C++20) + constexpr void real( \fB(2)\fP (since + double value ); C++20) + specialization + std::complex + long double real() \fB(2)\fP (until + const; C++11) + constexpr long (since + double real() const; \fB(1)\fP C++11) + void real( long (until + double value ); \fB(2)\fP C++20) + constexpr void real( (since + long double value ); C++20) Accesses the real part of the complex number. @@ -34,10 +56,27 @@ .SH Return value - 1) The real part. + 1) The real part of *this. 2) \fI(none)\fP +.SH Notes + + In C++11, overload \fB(1)\fP in std::complex specializations used to be specified without + const qualifier. However, in C++11, a constexpr specifier used in a non-static + member function implies const, and thus the behavior is as if const is specified. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 387 C++98 the real part could not be set can be set directly via a new real + directly overload + .SH See also + real returns the real part + \fI(function template)\fP imag accesses the imaginary part of the complex number - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::condition_variable.3 b/man/std::condition_variable.3 index 7b6a7b0e3..c4cf2830c 100644 --- a/man/std::condition_variable.3 +++ b/man/std::condition_variable.3 @@ -1,114 +1,139 @@ -.TH std::condition_variable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable \- std::condition_variable + .SH Synopsis Defined in header class condition_variable; \fI(since C++11)\fP - The condition_variable class is a synchronization primitive that can be used to - block a thread, or multiple threads at the same time, until: + std::condition_variable is a synchronization primitive used with a std::mutex to + block one or more threads until another thread both modifies a shared variable (the + condition) and notifies the std::condition_variable. - * a notification is received from another thread - * a timeout expires, or - * a spurious wakeup occurs + The thread that intends to modify the shared variable must: - Any thread that intends to wait on std::condition_variable has to acquire a - std::unique_lock first. The wait operations atomically release the mutex and suspend - the execution of the thread. When the condition variable is notified, the thread is - awakened, and the mutex is reacquired. + 1. Acquire a std::mutex (typically via std::lock_guard). + 2. Modify the shared variable while the lock is owned. + 3. Call notify_one or notify_all on the std::condition_variable (can be done after + releasing the lock). - The class std::condition_variable is a StandardLayoutType. It is not - CopyConstructible, MoveConstructible, CopyAssignable, MoveAssignable. + Even if the shared variable is atomic, it must be modified while owning the mutex to + correctly publish the modification to the waiting thread. + + Any thread that intends to wait on a std::condition_variable must: + + 1. Acquire a std::unique_lock on the mutex used to protect the shared + variable. + 2. Do one of the following: + + 1. Check the condition, in case it was already updated and notified. + 2. Call wait, wait_for, or wait_until on the std::condition_variable (atomically + releases the mutex and suspends thread execution until the condition variable is + notified, a timeout expires, or a spurious wakeup occurs, then atomically + acquires the mutex before returning). + 3. Check the condition and resume waiting if not satisfied. + + or: + 1. Use the predicated overload of wait, wait_for, and wait_until, which performs + the same three steps. -.SH Member types + std::condition_variable works only with std::unique_lock, which allows + for maximal efficiency on some platforms. std::condition_variable_any provides a + condition variable that works with any BasicLockable object, such as + std::shared_lock. - Member type Definition - native_handle_type implementation-defined + Condition variables permit concurrent invocation of the wait, wait_for, wait_until, + notify_one and notify_all member functions. + + The class std::condition_variable is a StandardLayoutType. It is not + CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable. .SH Member functions constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP .SH Notification notify_one notifies one waiting thread - \fI(public member function)\fP + \fI(public member function)\fP notify_all notifies all waiting threads - \fI(public member function)\fP + \fI(public member function)\fP .SH Waiting - wait blocks the current thread until the condition variable is woken up - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + wait blocks the current thread until the condition variable is awakened + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_for after the specified timeout duration - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP .SH Native handle native_handle returns the native handle - \fI(public member function)\fP + \fI(public member function)\fP .SH Example - condition_variable is typically used in combination with a std::mutex to facilitate - inter-thread communication + std::condition_variable is used in combination with a std::mutex to facilitate + inter-thread communication. + - // Run this code + #include #include + #include #include #include - #include - #include - + std::mutex m; std::condition_variable cv; std::string data; bool ready = false; bool processed = false; - + void worker_thread() { - // Wait until main() sends data - std::unique_lock lk(m); - cv.wait(lk, []{return ready;}); - - //after the wait, we own the lock. + // wait until main() sends data + std::unique_lock lk(m); + cv.wait(lk, []{ return ready; }); + + // after the wait, we own the lock std::cout << "Worker thread is processing data\\n"; data += " after processing"; - - // Send data back to main() + + // send data back to main() processed = true; std::cout << "Worker thread signals data processing completed\\n"; - - // Manual unlocking is done before notifying, to avoid - // that the waiting thread gets blocked again. + + // manual unlocking is done before notifying, to avoid waking up + // the waiting thread only to block again (see notify_one for details) lk.unlock(); cv.notify_one(); } - + int main() { std::thread worker(worker_thread); - + data = "Example data"; // send data to the worker thread { - std::lock_guard lk(m); + std::lock_guard lk(m); ready = true; std::cout << "main() signals data ready for processing\\n"; } cv.notify_one(); - + // wait for the worker { - std::unique_lock lk(m); - cv.wait(lk, []{return processed;}); + std::unique_lock lk(m); + cv.wait(lk, []{ return processed; }); } std::cout << "Back in main(), data = " << data << '\\n'; - + worker.join(); } @@ -118,3 +143,14 @@ Worker thread is processing data Worker thread signals data processing completed Back in main(), data = Example data after processing + +.SH See also + + condition_variable_any provides a condition variable associated with any lock type + \fI(C++11)\fP \fI(class)\fP + mutex provides basic mutual exclusion facility + \fI(C++11)\fP \fI(class)\fP + lock_guard implements a strictly scope-based mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + unique_lock implements movable mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::condition_variable::condition_variable.3 b/man/std::condition_variable::condition_variable.3 index 8e572f882..9d9405cf2 100644 --- a/man/std::condition_variable::condition_variable.3 +++ b/man/std::condition_variable::condition_variable.3 @@ -1,10 +1,12 @@ -.TH std::condition_variable::condition_variable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::condition_variable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::condition_variable \- std::condition_variable::condition_variable + .SH Synopsis - condition_variable(); \fB(1)\fP \fI(since C++11)\fP - condition_variable(const condition_variable&) = delete; \fB(2)\fP \fI(since C++11)\fP + condition_variable(); \fB(1)\fP \fI(since C++11)\fP + condition_variable( const condition_variable& ) = delete; \fB(2)\fP \fI(since C++11)\fP 1) Constructs an object of type std::condition_variable. - 2) Copy constructor is deleted. .SH Parameters @@ -14,4 +16,12 @@ .SH Exceptions 1) May throw std::system_error with std::error_condition equal to - std::errc::resource_unavailable_try_again or another implementation-defined value. + std::errc::operation_not_permitted if the thread has no privilege to create a + condition variable, std::errc::resource_unavailable_try_again if a non-memory + resource limitation prevents this initialization, or another implementation-defined + value. + +.SH See also + + C documentation for + cnd_init diff --git a/man/std::condition_variable::native_handle.3 b/man/std::condition_variable::native_handle.3 index 4e36c875b..7fec3ae81 100644 --- a/man/std::condition_variable::native_handle.3 +++ b/man/std::condition_variable::native_handle.3 @@ -1,4 +1,7 @@ -.TH std::condition_variable::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::native_handle \- std::condition_variable::native_handle + .SH Synopsis native_handle_type native_handle(); \fI(since C++11)\fP @@ -19,4 +22,6 @@ .SH See also native_handle returns the underlying implementation-defined thread handle - \fI(public member function of std::thread)\fP + \fI(public member function of std::thread)\fP + native_handle returns the underlying implementation-defined thread handle + \fI(public member function of std::jthread)\fP diff --git a/man/std::condition_variable::notify_all.3 b/man/std::condition_variable::notify_all.3 index 989a6ca04..ace19f2c5 100644 --- a/man/std::condition_variable::notify_all.3 +++ b/man/std::condition_variable::notify_all.3 @@ -1,6 +1,9 @@ -.TH std::condition_variable::notify_all 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::notify_all \- std::condition_variable::notify_all + .SH Synopsis - void notify_all(); \fI(since C++11)\fP + void notify_all() noexcept; \fI(since C++11)\fP Unblocks all threads currently waiting for *this. @@ -12,50 +15,47 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes - The effects of notify_one()/notify_all() and wait()/wait_for()/wait_until() take - place in a single total order, so it's impossible for notify_one() to, for example, - be delayed and unblock a thread that started waiting just after the call to - notify_one() was made. + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. The notifying thread does not need to hold the lock on the same mutex as the one - held by the waiting thread(s); in fact doing so is a pessimization, since the - notified thread would immediately block again, waiting for the notifying thread to - release the lock. + held by the waiting thread(s). Doing so may be a pessimization, since the notified + thread would immediately block again, waiting for the notifying thread to release + the lock, though some implementations recognize the pattern and do not attempt to + wake up the thread that is notified under lock. .SH Example - - + + // Run this code - #include + #include #include + #include #include - #include - + std::condition_variable cv; std::mutex cv_m; // This mutex is used for three purposes: // 1) to synchronize accesses to i // 2) to synchronize accesses to std::cerr // 3) for the condition variable cv int i = 0; - + void waits() { std::unique_lock lk(cv_m); std::cerr << "Waiting... \\n"; - cv.wait(lk, []{return i == 1;}); + cv.wait(lk, []{ return i == 1; }); std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { std::this_thread::sleep_for(std::chrono::seconds(1)); @@ -64,9 +64,9 @@ std::cerr << "Notifying...\\n"; } cv.notify_all(); - + std::this_thread::sleep_for(std::chrono::seconds(1)); - + { std::lock_guard lk(cv_m); i = 1; @@ -74,7 +74,7 @@ } cv.notify_all(); } - + int main() { std::thread t1(waits), t2(waits), t3(waits), t4(signals); @@ -98,4 +98,9 @@ .SH See also notify_one notifies one waiting thread - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + cnd_broadcast + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable::notify_one.3 b/man/std::condition_variable::notify_one.3 index 7e2d1c66b..224c95490 100644 --- a/man/std::condition_variable::notify_one.3 +++ b/man/std::condition_variable::notify_one.3 @@ -1,6 +1,9 @@ -.TH std::condition_variable::notify_one 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::notify_one \- std::condition_variable::notify_one + .SH Synopsis - void notify_one(); \fI(since C++11)\fP + void notify_one() noexcept; \fI(since C++11)\fP If any threads are waiting on *this, calling notify_one unblocks one of the waiting threads. @@ -13,67 +16,73 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes - The effects of notify_one()/notify_all() and wait()/wait_for()/wait_until() take - place in a single total order, so it's impossible for notify_one() to, for example, - be delayed and unblock a thread that started waiting just after the call to - notify_one() was made. + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. The notifying thread does not need to hold the lock on the same mutex as the one held by the waiting thread(s); in fact doing so is a pessimization, since the notified thread would immediately block again, waiting for the notifying thread to - release the lock. + release the lock. However, some implementations (in particular many implementations + of pthreads) recognize this situation and avoid this "hurry up and wait" scenario by + transferring the waiting thread from the condition variable's queue directly to the + queue of the mutex within the notify call, without waking it up. + + Notifying while under the lock may nevertheless be necessary when precise scheduling + of events is required, e.g. if the waiting thread would exit the program if the + condition is satisfied, causing destruction of the notifying thread's condition + variable. A spurious wakeup after mutex unlock but before notify would result in + notify called on a destroyed object. .SH Example - + // Run this code - #include + #include #include + #include #include - #include - + using namespace std::chrono_literals; + std::condition_variable cv; std::mutex cv_m; int i = 0; bool done = false; - + void waits() { std::unique_lock lk(cv_m); std::cout << "Waiting... \\n"; - cv.wait(lk, []{return i == 1;}); - std::cout << "...finished waiting. i == 1\\n"; + cv.wait(lk, []{ return i == 1; }); + std::cout << "...finished waiting; i == " << i << '\\n'; done = true; } - + void signals() { - std::this_thread::sleep_for(std::chrono::seconds(1)); + std::this_thread::sleep_for(200ms); std::cout << "Notifying falsely...\\n"; - cv.notify_one(); - //Most probably, the waiting thread is awaken unnecessarily. - + cv.notify_one(); // waiting thread is notified with i == 0. + // cv.wait wakes up, checks i, and goes back to waiting + std::unique_lock lk(cv_m); i = 1; while (!done) { std::cout << "Notifying true change...\\n"; - lk.unlock(); //It is a good idea unlock before notifying. - cv.notify_one(); - std::this_thread::sleep_for(std::chrono::seconds(1)); + lk.unlock(); + cv.notify_one(); // waiting thread is notified with i == 1, cv.wait returns + std::this_thread::sleep_for(300ms); lk.lock(); } } - + int main() { std::thread t1(waits), t2(signals); @@ -86,9 +95,14 @@ Waiting... Notifying falsely... Notifying true change... - ...finished waiting. i == 1 + ...finished waiting; i == 1 .SH See also notify_all notifies all waiting threads - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + cnd_signal + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable::wait.3 b/man/std::condition_variable::wait.3 index 414bd12e0..1b9357f1d 100644 --- a/man/std::condition_variable::wait.3 +++ b/man/std::condition_variable::wait.3 @@ -1,84 +1,90 @@ -.TH std::condition_variable::wait 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::wait \- std::condition_variable::wait + .SH Synopsis void wait( std::unique_lock& lock ); \fB(1)\fP \fI(since C++11)\fP template< class Predicate > \fB(2)\fP \fI(since C++11)\fP void wait( std::unique_lock& lock, Predicate pred ); wait causes the current thread to block until the condition variable is notified or - a spurious wakeup occurs, optionally looping until some predicate is satisfied. - - 1) Atomically releases lock, blocks the current executing thread, and adds it to the - list of threads waiting on *this. The thread will be unblocked when notify_all() or - notify_one() is executed. It may also be unblocked spuriously. When unblocked, - regardless of the reason, lock is reacquired and wait exits. If this function exits - via exception, lock is also reacquired. + a spurious wakeup occurs. pred can be optionally provided to detect spurious wakeup. + 1) Atomically calls lock.unlock() and blocks on *this. + The thread will be unblocked when notify_all() or notify_one() is executed. It may + also be unblocked spuriously. + When unblocked, calls lock.lock() (possibly blocking on the lock), then returns. 2) Equivalent to - - while (!pred()) { - wait(lock); - } - + while (!pred()) + wait(lock);. This overload may be used to ignore spurious awakenings while waiting for a specific - condition to become true. Note that before enter to this method lock must be - acquired, after wait(lock) exits it is also reacquired, i.e. lock can be used as a - guard to pred() access. + condition to become true. + If pred() is ill-formed, or + the return value of pred() is not convertible to bool + \fI(until C++20)\fP + decltype(pred()) does not model boolean-testable + \fI(since C++20)\fP, the program is ill-formed. + + Right after wait returns, lock.owns_lock() is true, and lock.mutex() is locked by + the calling thread. If these postconditions cannot be satisfied^[1], calls + std::terminate. + + If any of the following conditions is satisfied, the behavior is undefined: + + * lock.owns_lock() is false. + * lock.mutex() is not locked by the calling thread. + * If some other threads are also waiting on *this, lock.mutex() is different from + the mutex unlocked by the waiting functions (wait, wait_for and wait_until) + called on *this by those threads. + 1. ↑ This can happen if the re-locking of the mutex throws an exception. .SH Parameters - lock - an object of type std::unique_lock, which must be locked by the - current thread - predicate which returns false if the waiting should be continued. - - pred - The signature of the predicate function should be equivalent to the - following: - - bool pred(); - -.SH Return value - - \fI(none)\fP + lock - an lock which must be locked by the calling thread + pred - the predicate to check whether the waiting can be completed +.SH Type requirements + - + Predicate must meet the requirements of FunctionObject. .SH Exceptions - May throw std::system_error, may also propagate exceptions thrown by lock.lock() or - lock.unlock(). + 1) Throws nothing. + 2) Any exception thrown by pred. .SH Notes - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. - - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. .SH Example - - + // Run this code - #include + #include #include + #include #include - #include - + std::condition_variable cv; std::mutex cv_m; // This mutex is used for three purposes: // 1) to synchronize accesses to i // 2) to synchronize accesses to std::cerr // 3) for the condition variable cv int i = 0; - + void waits() { std::unique_lock lk(cv_m); std::cerr << "Waiting... \\n"; - cv.wait(lk, []{return i == 1;}); + cv.wait(lk, []{ return i == 1; }); std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { std::this_thread::sleep_for(std::chrono::seconds(1)); @@ -87,9 +93,9 @@ std::cerr << "Notifying...\\n"; } cv.notify_all(); - + std::this_thread::sleep_for(std::chrono::seconds(1)); - + { std::lock_guard lk(cv_m); i = 1; @@ -97,7 +103,7 @@ } cv.notify_all(); } - + int main() { std::thread t1(waits), t2(waits), t3(waits), t4(signals); @@ -118,11 +124,29 @@ ...finished waiting. i == 1 ...finished waiting. i == 1 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2135 C++11 the behavior was unclear if calls std::terminate in this + lock.lock() throws an exception case + .SH See also - blocks the current thread until the condition variable is woken up or + blocks the current thread until the condition variable is awakened or wait_for after the specified timeout duration - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + cnd_wait + +.SH External links + + 1. The Old New Thing article: Spurious wake-ups in Win32 condition variables. + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable::wait_for.3 b/man/std::condition_variable::wait_for.3 index f570f93b7..85f2526cc 100644 --- a/man/std::condition_variable::wait_for.3 +++ b/man/std::condition_variable::wait_for.3 @@ -1,115 +1,159 @@ -.TH std::condition_variable::wait_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::wait_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::wait_for \- std::condition_variable::wait_for + .SH Synopsis template< class Rep, class Period > std::cv_status wait_for( std::unique_lock& lock, \fB(1)\fP \fI(since C++11)\fP const std::chrono::duration& - rel_time); + rel_time ); template< class Rep, class Period, class Predicate > bool wait_for( std::unique_lock& lock, \fB(2)\fP \fI(since C++11)\fP const std::chrono::duration& rel_time, - Predicate pred); + Predicate pred ); + + wait_for causes the current thread to block until the condition variable is + notified, the given duration has been elapsed, or a spurious wakeup occurs. pred can + be optionally provided to detect spurious wakeup. - 1) Atomically releases lock, blocks the current executing thread, and adds it to the - list of threads waiting on *this. The thread will be unblocked when notify_all() or - notify_one() is executed, or when the relative timeout rel_time expires. It may also - be unblocked spuriously. When unblocked, regardless of the reason, lock is - reacquired and wait_for() exits. If this function exits via exception, lock is also - reacquired. + 1) Equivalent to return wait_until(lock, std::chrono::steady_clock::now() + + rel_time);. 2) Equivalent to return wait_until(lock, std::chrono::steady_clock::now() + - rel_time);. This overload may be used to ignore spurious awakenings. + rel_time, std::move(pred));. + This overload may be used to ignore spurious awakenings while waiting for a specific + condition to become true. - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + Right after wait_for returns, lock.owns_lock() is true, and lock.mutex() is locked + by the calling thread. If these postconditions cannot be satisfied^[1], calls + std::terminate. - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. + If any of the following conditions is satisfied, the behavior is undefined: - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + * lock.owns_lock() is false. + * lock.mutex() is not locked by the calling thread. + * If some other threads are also waiting on *this, lock.mutex() is different from + the mutex unlocked by the waiting functions (wait, wait_for and wait_until) + called on *this by those threads. + 1. ↑ This can happen if the re-locking of the mutex throws an exception. .SH Parameters - lock - an object of type std::unique_lock, which must be locked by - the current thread - rel_time - an object of type std::chrono::duration representing the maximum time to - spend waiting - predicate which returns false if the waiting should be continued. - - pred - The signature of the predicate function should be equivalent to the - following: - - bool pred(); + lock - an lock which must be locked by the calling thread + rel_time - the maximum duration to wait + pred - the predicate to check whether the waiting can be completed +.SH Type requirements + - + Predicate must meet the requirements of FunctionObject. .SH Return value - 1) std::cv_status::timeout if the relative timeout specified by rel_time expired, - std::cv_status::no_timeout overwise. - 2) false if the predicate pred still evaluates to false after the rel_time timeout - expired, otherwise true. + 1) std::cv_status::timeout if rel_time has been elapsed since the beginning of this + call, otherwise std::cv_status::no_timeout. + 2) The latest result of pred() before returning to the caller. .SH Exceptions - May throw std::system_error, may also propagate exceptions thrown by lock.lock() or - lock.unlock(). + 1) Timeout-related exceptions. + 2) Timeout-related exceptions, and any exception thrown by pred. + +.SH Notes + + Even if notified under lock, overload \fB(1)\fP makes no guarantees about the state of the + associated predicate when returning due to timeout. + + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. .SH Example - + // Run this code - #include - #include + #include #include + #include #include - #include - + std::condition_variable cv; - std::mutex cv_m; - std::atomic i{0}; - - void waits(int idx) + std::mutex cv_m; // This mutex is used for three purposes: + // 1) to synchronize accesses to i + // 2) to synchronize accesses to std::cerr + // 3) for the condition variable cv + int i = 0; + + void waits() { std::unique_lock lk(cv_m); - if(cv.wait_for(lk, std::chrono::milliseconds(idx*100), [](){return i == 1;})) - std::cerr << "Thread " << idx << " finished waiting. i == " << i << '\\n'; - else - std::cerr << "Thread " << idx << " timed out. i == " << i << '\\n'; + std::cerr << "Waiting... \\n"; + cv.wait(lk, []{ return i == 1; }); + std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { - std::this_thread::sleep_for(std::chrono::milliseconds(120)); - std::cerr << "Notifying...\\n"; + std::this_thread::sleep_for(std::chrono::seconds(1)); + { + std::lock_guard lk(cv_m); + std::cerr << "Notifying...\\n"; + } cv.notify_all(); - std::this_thread::sleep_for(std::chrono::milliseconds(100)); - i = 1; - std::cerr << "Notifying again...\\n"; + + std::this_thread::sleep_for(std::chrono::seconds(1)); + + { + std::lock_guard lk(cv_m); + i = 1; + std::cerr << "Notifying again...\\n"; + } cv.notify_all(); } - + int main() { - std::thread t1(waits, 1), t2(waits, 2), t3(waits, 3), t4(signals); - t1.join(); t2.join(), t3.join(), t4.join(); + std::thread t1(waits), t2(waits), t3(waits), t4(signals); + t1.join(); + t2.join(); + t3.join(); + t4.join(); } -.SH Output: +.SH Possible output: - Thread 1 timed out. i == 0 + Waiting... + Waiting... + Waiting... Notifying... - Thread 2 timed out. i == 0 Notifying again... - Thread 3 finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 timeout-related exceptions were mentions these exceptions + missing in the specification + LWG 2135 C++11 the behavior was unclear if calls std::terminate in + lock.lock() throws an exception this case .SH See also - wait blocks the current thread until the condition variable is woken up - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + wait blocks the current thread until the condition variable is awakened + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable::wait_until.3 b/man/std::condition_variable::wait_until.3 index 0cd4eee39..3232375b3 100644 --- a/man/std::condition_variable::wait_until.3 +++ b/man/std::condition_variable::wait_until.3 @@ -1,118 +1,144 @@ -.TH std::condition_variable::wait_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::wait_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::wait_until \- std::condition_variable::wait_until + .SH Synopsis template< class Clock, class Duration > - std::cv_status wait_until( std::unique_lock& lock, \fB(1)\fP \fI(since C++11)\fP + std::cv_status + wait_until( std::unique_lock& lock, \fB(1)\fP \fI(since C++11)\fP - const std::chrono::time_point& timeout_time ); + const std::chrono::time_point& + abs_time ); template< class Clock, class Duration, class Predicate > bool wait_until( std::unique_lock& lock, const std::chrono::time_point& \fB(2)\fP \fI(since C++11)\fP - timeout_time, + abs_time, Predicate pred ); wait_until causes the current thread to block until the condition variable is - notified, a specific time is reached, or a spurious wakeup occurs, optionally - looping until some predicate is satisfied. - - 1) Atomically releases lock, blocks the current executing thread, and adds it to the - list of threads waiting on *this. The thread will be unblocked when notify_all() or - notify_one() is executed, or when the absolute time point timeout_time is reached. - It may also be unblocked spuriously. When unblocked, regardless of the reason, lock - is reacquired and wait_until exits. If this function exits via exception, lock is - also reacquired. - 2) Equivalent to - - while (!pred()) { - if (wait_until(lock, abs_time) == std::cv_status::timeout) { - return pred(); - } - } - return true; - - This overload may be used to ignore spurious wakeups. + notified, the given time point has been reached, or a spurious wakeup occurs. pred + can be optionally provided to detect spurious wakeup. + + 1) Atomically calls lock.unlock() and blocks on *this. + The thread will be unblocked when notify_all() or notify_one() is executed, or + abs_time is reached. It may also be unblocked spuriously. + When unblocked, calls lock.lock() (possibly blocking on the lock), then returns. + 2) Equivalent to while (!pred()) + if (wait_until(lock, abs_time) == std::cv_status::timeout) + return pred(); + return true;. + This overload may be used to ignore spurious awakenings while waiting for a specific + condition to become true. + If pred() is ill-formed, or + the return value of pred() is not convertible to bool + \fI(until C++20)\fP + decltype(pred()) does not model boolean-testable + \fI(since C++20)\fP, the program is ill-formed. + + Right after wait_until returns, lock.owns_lock() is true, and lock.mutex() is locked + by the calling thread. If these postconditions cannot be satisfied^[1], calls + std::terminate. + + If any of the following conditions is satisfied, the behavior is undefined: + + * lock.owns_lock() is false. + * lock.mutex() is not locked by the calling thread. + * If some other threads are also waiting on *this, lock.mutex() is different from + the mutex unlocked by the waiting functions (wait, wait_for and wait_until) + called on *this by those threads. + 1. ↑ This can happen if the re-locking of the mutex throws an exception. - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might, but might - not, be less or more than timeout_time - Clock::now() at the time of the call, - depending on the direction of the adjustment. The function also may block for longer - than until after timeout_time has been reached due to scheduling or resource - contention delays. - - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. +.SH Parameters - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + lock - an lock which must be locked by the calling thread + abs_time - the time point where waiting expires + pred - the predicate to check whether the waiting can be completed +.SH Type requirements + - + Predicate must meet the requirements of FunctionObject. -.SH Parameters +.SH Return value - lock - an object of type std::unique_lock, which must be locked - by the current thread - timeout_time - an object of type std::chrono::time_point representing the time when - to stop waiting - predicate which returns false if the waiting should be continued. + 1) std::cv_status::timeout if abs_time has been reached, otherwise + std::cv_status::no_timeout. + 2) The latest result of pred() before returning to the caller. - pred - The signature of the predicate function should be equivalent to the - following: +.SH Exceptions - bool pred(); + 1) Timeout-related exceptions. + 2) Timeout-related exceptions, and any exception thrown by pred. -.SH Return value +.SH Notes - 1) std::cv_status::timeout if the absolute timeout specified by abs_time was - reached, std::cv_status::no_timeout overwise. - 2) false if the predicate pred still evaluates to false after the abs_time timeout - expired, otherwise true. + The standard recommends that the clock tied to abs_time be used to measure time; + that clock is not required to be a monotonic clock. There are no guarantees + regarding the behavior of this function if the clock is adjusted discontinuously, + but the existing implementations convert abs_time from Clock to + std::chrono::system_clock and delegate to POSIX pthread_cond_timedwait so that the + wait honors adjustments to the system clock, but not to the user-provided Clock. In + any case, the function also may wait for longer than until after abs_time has been + reached due to scheduling or resource contention delays. -.SH Exceptions + Even if the clock in use is std::chrono::steady_clock or another monotonic clock, a + system clock adjustment may induce a spurious wakeup. - May throw std::system_error, may also propagate exceptions thrown by lock.lock() or - lock.unlock(). + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. .SH Example - + // Run this code - #include - #include + #include #include + #include #include - #include - + std::condition_variable cv; - std::mutex cv_m; - std::atomic i = ATOMIC_VAR_INIT(0); - - void waits(int idx) + std::mutex cv_m; // This mutex is used for three purposes: + // 1) to synchronize accesses to i + // 2) to synchronize accesses to std::cerr + // 3) for the condition variable cv + int i = 0; + + void waits() { std::unique_lock lk(cv_m); - auto now = std::chrono::system_clock::now(); - if(cv.wait_until(lk, now + std::chrono::milliseconds(idx*100), [](){return i == 1;})) - std::cerr << "Thread " << idx << " finished waiting. i == " << i << '\\n'; - else - std::cerr << "Thread " << idx << " timed out. i == " << i << '\\n'; + std::cerr << "Waiting... \\n"; + cv.wait(lk, []{ return i == 1; }); + std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { - std::this_thread::sleep_for(std::chrono::milliseconds(120)); - std::cerr << "Notifying...\\n"; + std::this_thread::sleep_for(std::chrono::seconds(1)); + { + std::lock_guard lk(cv_m); + std::cerr << "Notifying...\\n"; + } cv.notify_all(); - std::this_thread::sleep_for(std::chrono::milliseconds(100)); - i = 1; - std::cerr << "Notifying again...\\n"; + + std::this_thread::sleep_for(std::chrono::seconds(1)); + + { + std::lock_guard lk(cv_m); + i = 1; + std::cerr << "Notifying again...\\n"; + } cv.notify_all(); } - + int main() { - std::thread t1(waits, 1), t2(waits, 2), t3(waits, 3), t4(signals); + std::thread t1(waits), t2(waits), t3(waits), t4(signals); t1.join(); t2.join(); t3.join(); @@ -121,16 +147,33 @@ .SH Possible output: - Thread 1 timed out. i == 0 + Waiting... + Waiting... + Waiting... Notifying... - Thread 2 timed out. i == 0 Notifying again... - Thread 3 finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 timeout-related exceptions were mentions these exceptions + missing in the specification + LWG 2135 C++11 the behavior was unclear if calls std::terminate in + lock.lock() throws an exception this case .SH See also - wait blocks the current thread until the condition variable is woken up - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or after + wait blocks the current thread until the condition variable is awakened + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or after wait_for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable::~condition_variable.3 b/man/std::condition_variable::~condition_variable.3 index 643db1042..7042145ee 100644 --- a/man/std::condition_variable::~condition_variable.3 +++ b/man/std::condition_variable::~condition_variable.3 @@ -1,8 +1,11 @@ -.TH std::condition_variable::~condition_variable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable::~condition_variable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable::~condition_variable \- std::condition_variable::~condition_variable + .SH Synopsis - ~condition_variable(); \fB(1)\fP \fI(since C++11)\fP + ~condition_variable(); \fI(since C++11)\fP - Destroys the object of type std::condition_variable + Destroys the object of type std::condition_variable. It is only safe to invoke the destructor if all threads have been notified. It is not required that they have exited their respective wait functions: some threads may @@ -14,6 +17,7 @@ wait functions in a loop or are using the overloads of the wait functions that take a predicate. -.SH Exceptions +.SH See also - \fI(none)\fP + C documentation for + cnd_destroy diff --git a/man/std::condition_variable_any.3 b/man/std::condition_variable_any.3 index 22fff1b6d..fdf4b8879 100644 --- a/man/std::condition_variable_any.3 +++ b/man/std::condition_variable_any.3 @@ -1,63 +1,64 @@ -.TH std::condition_variable_any 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any \- std::condition_variable_any + .SH Synopsis Defined in header class condition_variable_any; \fI(since C++11)\fP The condition_variable_any class is a generalization of std::condition_variable. Whereas std::condition_variable works only on std::unique_lock, - condition_variable_any can operate on any user-defined lock that meets the - BasicLockable requirements. - - condition_variable_any provides similar functionality to std::condition_variable. It - is a synchronization primitive that can be used to block some number of threads - until: - - * a notification is received from another thread - * a timeout expires, or - * a spurious wakeup occurs + condition_variable_any can operate on any lock that meets the BasicLockable + requirements. - Any thread that intends to wait on std::condition_variable_any has to acquire a lock - first. The wait operations atomically release the lock and suspend the execution of - the thread. When the condition variable is notified, the thread is awakened, and the - lock is reacquired. + See std::condition_variable for the description of the semantics of condition + variables. - The class std::condition_variable_any is a standard-layout class. It is not - copy-constructible, move-constructible, copy-assignable, or move-assignable. + The class std::condition_variable_any is a StandardLayoutType. It is not + CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable. - If the lock is std::unique_lock, std::condition_variable may provide better - performance. + If the lock is std::unique_lock, std::condition_variable may provide + better performance. .SH Member functions constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP .SH Notification notify_one notifies one waiting thread - \fI(public member function)\fP + \fI(public member function)\fP notify_all notifies all waiting threads - \fI(public member function)\fP + \fI(public member function)\fP .SH Waiting - wait blocks the current thread until the condition variable is woken up - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + wait blocks the current thread until the condition variable is awakened + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_for after the specified timeout duration - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP .SH Notes + std::condition_variable_any can be used with std::shared_lock in order to wait on a + std::shared_mutex in shared ownership mode. + A possible use for std::condition_variable_any with custom Lockable types is to provide convenient interruptible waits: the custom lock operation would both lock the associated mutex as expected, and also perform the necessary setup to notify this condition variable when the interrupting signal is received.^[1] -.SH References +.SH See also + + condition_variable provides a condition variable associated with a std::unique_lock + \fI(C++11)\fP \fI(class)\fP + +.SH External links - 1. ↑ A. Williams (2012), "C++ concurrency in action" 9.2.4 Interupting a wait on - std::condition_variable_any + 1. ↑ Anthony Williams (2012, 1st ed./ 2019, 2nd ed.), “C++ Concurrency in Action”, + 9.2.4 “Interrupting a wait on std::condition_variable_any”. diff --git a/man/std::condition_variable_any::condition_variable_any.3 b/man/std::condition_variable_any::condition_variable_any.3 index 222387e80..f7bde16a4 100644 --- a/man/std::condition_variable_any::condition_variable_any.3 +++ b/man/std::condition_variable_any::condition_variable_any.3 @@ -1,10 +1,12 @@ -.TH std::condition_variable_any::condition_variable_any 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::condition_variable_any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::condition_variable_any \- std::condition_variable_any::condition_variable_any + .SH Synopsis - condition_variable_any(); \fB(1)\fP \fI(since C++11)\fP - condition_variable_any(const condition_variable_any&) = delete; \fB(2)\fP \fI(since C++11)\fP + condition_variable_any(); \fB(1)\fP \fI(since C++11)\fP + condition_variable_any( const condition_variable_any& ) = delete; \fB(2)\fP \fI(since C++11)\fP 1) Constructs an object of type std::condition_variable_any. - 2) Copy constructor is deleted. .SH Parameters @@ -14,4 +16,21 @@ .SH Exceptions 1) May throw std::system_error with std::error_condition equal to - std::errc::resource_unavailable_try_again or another implementation-defined value. + std::errc::operation_not_permitted if the thread has no privilege to create a + condition variable, std::errc::resource_unavailable_try_again if a non-memory + resource limitation prevents this initialization, or another implementation-defined + value. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2092 C++11 the error condition for corrected + resource_unavailable_try_again was wrong + +.SH See also + + C documentation for + cnd_init diff --git a/man/std::condition_variable_any::native_handle.3 b/man/std::condition_variable_any::native_handle.3 deleted file mode 100644 index 3cb306cf1..000000000 --- a/man/std::condition_variable_any::native_handle.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH std::condition_variable_any::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - native_handle_type native_handle(); \fI(since C++11)\fP - - Accesses the native handle of *this. - - The meaning and the type of the result of this function is implementation-defined. - On a POSIX system, this may be a value of type pthread_cond_t*. On a Windows system, - this may be a PCONDITION_VARIABLE. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The native handle of this condition variable. - -.SH See also - - native_handle returns the underlying implementation-defined thread handle - \fI(public member function of std::thread)\fP diff --git a/man/std::condition_variable_any::notify_all.3 b/man/std::condition_variable_any::notify_all.3 index 0a2b2a703..f13f2eb6f 100644 --- a/man/std::condition_variable_any::notify_all.3 +++ b/man/std::condition_variable_any::notify_all.3 @@ -1,6 +1,9 @@ -.TH std::condition_variable_any::notify_all 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::notify_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::notify_all \- std::condition_variable_any::notify_all + .SH Synopsis - void notify_all(); \fI(since C++11)\fP + void notify_all() noexcept; \fI(since C++11)\fP Unblocks all threads currently waiting for *this. @@ -12,50 +15,47 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes - The effects of notify_one()/notify_all() and wait()/wait_for()/wait_until() take - place in a single total order, so it's impossible for notify_one() to, for example, - be delayed and unblock a thread that started waiting just after the call to - notify_one() was made. + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. The notifying thread does not need to hold the lock on the same mutex as the one - held by the waiting thread(s); in fact doing so is a pessimization, since the - notified thread would immediately block again, waiting for the notifying thread to - release the lock. + held by the waiting thread(s). Doing so may be a pessimization, since the notified + thread would immediately block again, waiting for the notifying thread to release + the lock, though some implementations recognize the pattern and do not attempt to + wake up the thread that is notified under lock. .SH Example - - + + // Run this code - #include + #include #include + #include #include - #include - + std::condition_variable_any cv; std::mutex cv_m; // This mutex is used for three purposes: // 1) to synchronize accesses to i // 2) to synchronize accesses to std::cerr // 3) for the condition variable cv int i = 0; - + void waits() { std::unique_lock lk(cv_m); std::cerr << "Waiting... \\n"; - cv.wait(lk, []{return i == 1;}); + cv.wait(lk, []{ return i == 1; }); std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { std::this_thread::sleep_for(std::chrono::seconds(1)); @@ -64,9 +64,9 @@ std::cerr << "Notifying...\\n"; } cv.notify_all(); - + std::this_thread::sleep_for(std::chrono::seconds(1)); - + { std::lock_guard lk(cv_m); i = 1; @@ -74,7 +74,7 @@ } cv.notify_all(); } - + int main() { std::thread t1(waits), t2(waits), t3(waits), t4(signals); @@ -98,4 +98,9 @@ .SH See also notify_one notifies one waiting thread - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + cnd_broadcast + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable_any::notify_one.3 b/man/std::condition_variable_any::notify_one.3 index 2494e530e..4e27687a2 100644 --- a/man/std::condition_variable_any::notify_one.3 +++ b/man/std::condition_variable_any::notify_one.3 @@ -1,6 +1,9 @@ -.TH std::condition_variable_any::notify_one 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::notify_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::notify_one \- std::condition_variable_any::notify_one + .SH Synopsis - void notify_one(); \fI(since C++11)\fP + void notify_one() noexcept; \fI(since C++11)\fP If any threads are waiting on *this, calling notify_one unblocks one of the waiting threads. @@ -13,67 +16,73 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes - The effects of notify_one()/notify_all() and wait()/wait_for()/wait_until() take - place in a single total order, so it's impossible for notify_one() to, for example, - be delayed and unblock a thread that started waiting just after the call to - notify_one() was made. + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. The notifying thread does not need to hold the lock on the same mutex as the one held by the waiting thread(s); in fact doing so is a pessimization, since the notified thread would immediately block again, waiting for the notifying thread to - release the lock. + release the lock. However, some implementations (in particular many implementations + of pthreads) recognize this situation and avoid this "hurry up and wait" scenario by + transferring the waiting thread from the condition variable's queue directly to the + queue of the mutex within the notify call, without waking it up. + + Notifying while under the lock may nevertheless be necessary when precise scheduling + of events is required, e.g. if the waiting thread would exit the program if the + condition is satisfied, causing destruction of the notifying thread's condition + variable. A spurious wakeup after mutex unlock but before notify would result in + notify called on a destroyed object. .SH Example - + // Run this code - #include + #include #include + #include #include - #include - + using namespace std::chrono_literals; + std::condition_variable_any cv; std::mutex cv_m; int i = 0; bool done = false; - + void waits() { std::unique_lock lk(cv_m); std::cout << "Waiting... \\n"; - cv.wait(lk, []{return i == 1;}); - std::cout << "...finished waiting. i == 1\\n"; + cv.wait(lk, []{ return i == 1; }); + std::cout << "...finished waiting; i == " << i << '\\n'; done = true; } - + void signals() { - std::this_thread::sleep_for(std::chrono::seconds(1)); + std::this_thread::sleep_for(200ms); std::cout << "Notifying falsely...\\n"; - cv.notify_one(); - //Most probably, the waiting thread is awaken unnecessarily. - + cv.notify_one(); // waiting thread is notified with i == 0. + // cv.wait wakes up, checks i, and goes back to waiting + std::unique_lock lk(cv_m); i = 1; while (!done) { std::cout << "Notifying true change...\\n"; - lk.unlock(); //It is a good idea unlock before notifying. - cv.notify_one(); - std::this_thread::sleep_for(std::chrono::seconds(1)); + lk.unlock(); + cv.notify_one(); // waiting thread is notified with i == 1, cv.wait returns + std::this_thread::sleep_for(300ms); lk.lock(); } } - + int main() { std::thread t1(waits), t2(signals); @@ -86,9 +95,14 @@ Waiting... Notifying falsely... Notifying true change... - ...finished waiting. i == 1 + ...finished waiting; i == 1 .SH See also notify_all notifies all waiting threads - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + cnd_signal + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable_any::wait.3 b/man/std::condition_variable_any::wait.3 index cea00c246..36907f243 100644 --- a/man/std::condition_variable_any::wait.3 +++ b/man/std::condition_variable_any::wait.3 @@ -1,85 +1,106 @@ -.TH std::condition_variable_any::wait 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::wait \- std::condition_variable_any::wait + .SH Synopsis - template< class Lock > \fB(1)\fP \fI(since C++11)\fP + template< class Lock > \fB(1)\fP \fI(since C++11)\fP void wait( Lock& lock ); - template< class Lock, class Predicate > \fB(2)\fP \fI(since C++11)\fP + template< class Lock, class Predicate > \fB(2)\fP \fI(since C++11)\fP void wait( Lock& lock, Predicate pred ); + template< class Lock, class Predicate > \fB(3)\fP \fI(since C++20)\fP + bool wait( Lock& lock, std::stop_token stoken, Predicate pred ); wait causes the current thread to block until the condition variable is notified or - a spurious wakeup occurs, optionally looping until some predicate is satisfied. - - 1) Atomically releases lock, blocks the current executing thread, and adds it to the - list of threads waiting on *this. The thread will be unblocked when notify_all() or - notify_one() is executed. It may also be unblocked spuriously. When unblocked, - regardless of the reason, lock is reacquired and wait exits. If this function exits - via exception, lock is also reacquired. - + a spurious wakeup occurs. pred can be optionally provided to detect spurious wakeup. + + 1) Atomically calls lock.unlock() and blocks on *this. + The thread will be unblocked when notify_all() or notify_one() is executed. It may + also be unblocked spuriously. + When unblocked, calls lock.lock() (possibly blocking on the lock), then returns. + 2,3) Waiting for a specific condition to become true, can be used to ignore spurious + awakenings. 2) Equivalent to - - while (!pred()) { - wait(lock); - } - - This overload may be used to ignore spurious awakenings while waiting for a specific - condition to become true. Note that before enter to this method lock must be - acquired, after wait(lock) exits it is also reacquired, i.e. lock can be used as a - guard to pred() access. + while (!pred()) + wait(lock); + 3) Registers *this for the duration of this call, to be notified if a stop request + is made on stoken's associated stop-state; it is then equivalent to + while (!stoken.stop_requested()) + { + if (pred()) + return true; + wait(lock); + } + return pred(); + If pred() is ill-formed, or + the return value of pred() is not convertible to bool + \fI(until C++20)\fP + decltype(pred()) does not model boolean-testable + \fI(since C++20)\fP, the program is ill-formed. + + Right after wait returns, lock is locked by the calling thread. If this + postcondition cannot be satisfied^[1], calls std::terminate. + + 1. ↑ This can happen if the re-locking of the mutex throws an exception. .SH Parameters - lock - an object of type Lock that meets the BasicLockable requirements, which must - be locked by the current thread - predicate which returns false if the waiting should be continued. - - pred - The signature of the predicate function should be equivalent to the - following: - - bool pred(); + lock - an lock which must be locked by the calling thread + stoken - a stop token to register interruption for + pred - the predicate to check whether the waiting can be completed +.SH Type requirements + - + Lock must meet the requirements of BasicLockable. + - + Predicate must meet the requirements of FunctionObject. .SH Return value - \fI(none)\fP + 1,2) \fI(none)\fP + 3) The latest result of pred() before returning to the caller. .SH Exceptions - May throw std::system_error, may also propagate exceptions thrown by lock.lock() or - lock.unlock(). + 1) Does not throw. + 2,3) Any exception thrown by pred. .SH Notes - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. + The returned value of overload \fB(3)\fP indicates whether pred evaluated to true, + regardless of whether there was a stop requested or not. - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. .SH Example - - + + // Run this code - #include + #include #include + #include #include - #include - + std::condition_variable_any cv; std::mutex cv_m; // This mutex is used for three purposes: // 1) to synchronize accesses to i // 2) to synchronize accesses to std::cerr // 3) for the condition variable cv int i = 0; - + void waits() { std::unique_lock lk(cv_m); std::cerr << "Waiting... \\n"; - cv.wait(lk, []{return i == 1;}); + cv.wait(lk, []{ return i == 1; }); std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { std::this_thread::sleep_for(std::chrono::seconds(1)); @@ -88,9 +109,9 @@ std::cerr << "Notifying...\\n"; } cv.notify_all(); - + std::this_thread::sleep_for(std::chrono::seconds(1)); - + { std::lock_guard lk(cv_m); i = 1; @@ -98,7 +119,7 @@ } cv.notify_all(); } - + int main() { std::thread t1(waits), t2(waits), t3(waits), t4(signals); @@ -119,11 +140,29 @@ ...finished waiting. i == 1 ...finished waiting. i == 1 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2135 C++11 the behavior was unclear if calls std::terminate in this + lock.lock() throws an exception case + .SH See also - blocks the current thread until the condition variable is woken up or + blocks the current thread until the condition variable is awakened or wait_for after the specified timeout duration - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + cnd_wait + +.SH External links + + 1. The Old New Thing article: Spurious wake-ups in Win32 condition variables. + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable_any::wait_for.3 b/man/std::condition_variable_any::wait_for.3 index bfde8300a..e4f29fcc4 100644 --- a/man/std::condition_variable_any::wait_for.3 +++ b/man/std::condition_variable_any::wait_for.3 @@ -1,115 +1,164 @@ -.TH std::condition_variable_any::wait_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::wait_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::wait_for \- std::condition_variable_any::wait_for + .SH Synopsis template< class Lock, class Rep, class Period > std::cv_status wait_for( Lock& lock, \fB(1)\fP \fI(since C++11)\fP const std::chrono::duration& - rel_time); + rel_time ); template< class Lock, class Rep, class Period, class Predicate > - bool wait_for( Lock& lock, \fB(2)\fP \fI(since C++11)\fP - const std::chrono::duration& rel_time, + bool wait_for( Lock& lock, const std::chrono::duration& rel_time, - Predicate pred); + Predicate pred ); + template< class Lock, class Rep, class Period, class Predicate > - 1) Atomically releases lock, blocks the current executing thread, and adds it to the - list of threads waiting on *this. The thread will be unblocked when notify_all() or - notify_one() is executed, or when the relative timeout rel_time expires. It may also - be unblocked spuriously. When unblocked, regardless of the reason, lock is - reacquired and wait_for() exits. If this function exits via exception, lock is also - reacquired. - 2) Equivalent to return wait_until(lock, std::chrono::steady_clock::now() + - rel_time);. This overload may be used to ignore spurious awakenings. + bool wait_for( Lock& lock, std::stop_token stoken, \fB(3)\fP \fI(since C++20)\fP + const std::chrono::duration& rel_time, - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + Predicate pred ); - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. + wait_for causes the current thread to block until the condition variable is + notified, the given duration has been elapsed, or a spurious wakeup occurs. pred can + be optionally provided to detect spurious wakeup. - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + 1) Equivalent to return wait_until(lock, std::chrono::steady_clock::now() + + rel_time);. + 2,3) Waiting for a specific condition to become true, can be used to ignore spurious + awakenings. + 2) Equivalent to return wait_until(lock, std::chrono::steady_clock::now() + + rel_time, std::move(pred));. + 3) Registers *this for the duration of this call, to be notified if a stop request + is made on stoken's associated stop-state; it is then equivalent to return + wait_until(lock, std::move(stoken), + std::chrono::steady_clock::now() + rel_time, std::move(pred));. -.SH Parameters + Right after wait_for returns, lock is locked by the calling thread. If this + postcondition cannot be satisfied^[1], calls std::terminate. - lock - an object of type Lock that meets the BasicLockable requirements, which - must be locked by the current thread - rel_time - an object of type std::chrono::duration representing the maximum time to - spend waiting - predicate which returns false if the waiting should be continued. + 1. ↑ This can happen if the re-locking of the mutex throws an exception. - pred - The signature of the predicate function should be equivalent to the - following: +.SH Parameters - bool pred(); + lock - an lock which must be locked by the calling thread + stoken - a stop token to register interruption for + rel_time - the maximum duration to wait + pred - the predicate to check whether the waiting can be completed +.SH Type requirements + - + Lock must meet the requirements of BasicLockable. + - + Predicate must meet the requirements of FunctionObject. .SH Return value - 1) std::cv_status::timeout if the relative timeout specified by rel_time expired, - std::cv_status::no_timeout overwise. - 2) false if the predicate pred still evaluates to false after the rel_time timeout - expired, otherwise true. + 1) std::cv_status::timeout if rel_time has been elapsed since the beginning of this + call, otherwise std::cv_status::no_timeout. + 2,3) The latest result of pred() before returning to the caller. .SH Exceptions - May throw std::system_error, may also propagate exceptions thrown by lock.lock() or - lock.unlock(). + 1) Timeout-related exceptions. + 2,3) Timeout-related exceptions, and any exception thrown by pred. + +.SH Notes + + Even if notified under lock, overload \fB(1)\fP makes no guarantees about the state of the + associated predicate when returning due to timeout. + + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. .SH Example - + // Run this code - #include - #include + #include #include + #include #include - #include - + std::condition_variable_any cv; - std::mutex cv_m; - std::atomic i{0}; - - void waits(int idx) + std::mutex cv_m; // This mutex is used for three purposes: + // 1) to synchronize accesses to i + // 2) to synchronize accesses to std::cerr + // 3) for the condition variable cv + int i = 0; + + void waits() { std::unique_lock lk(cv_m); - if(cv.wait_for(lk, std::chrono::milliseconds(idx*100), [](){return i == 1;})) - std::cerr << "Thread " << idx << " finished waiting. i == " << i << '\\n'; - else - std::cerr << "Thread " << idx << " timed out. i == " << i << '\\n'; + std::cerr << "Waiting... \\n"; + cv.wait(lk, []{ return i == 1; }); + std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { - std::this_thread::sleep_for(std::chrono::milliseconds(120)); - std::cerr << "Notifying...\\n"; + std::this_thread::sleep_for(std::chrono::seconds(1)); + { + std::lock_guard lk(cv_m); + std::cerr << "Notifying...\\n"; + } cv.notify_all(); - std::this_thread::sleep_for(std::chrono::milliseconds(100)); - i = 1; - std::cerr << "Notifying again...\\n"; + + std::this_thread::sleep_for(std::chrono::seconds(1)); + + { + std::lock_guard lk(cv_m); + i = 1; + std::cerr << "Notifying again...\\n"; + } cv.notify_all(); } - + int main() { - std::thread t1(waits, 1), t2(waits, 2), t3(waits, 3), t4(signals); - t1.join(); t2.join(), t3.join(), t4.join(); + std::thread t1(waits), t2(waits), t3(waits), t4(signals); + t1.join(); + t2.join(); + t3.join(); + t4.join(); } -.SH Output: +.SH Possible output: - Thread 1 timed out. i == 0 + Waiting... + Waiting... + Waiting... Notifying... - Thread 2 timed out. i == 0 Notifying again... - Thread 3 finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 timeout-related exceptions were mentions these exceptions + missing in the specification + LWG 2135 C++11 the behavior was unclear if calls std::terminate in + lock.lock() throws an exception this case .SH See also - wait blocks the current thread until the condition variable is woken up - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or + wait blocks the current thread until the condition variable is awakened + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable_any::wait_until.3 b/man/std::condition_variable_any::wait_until.3 index 87d05897f..83b7fd871 100644 --- a/man/std::condition_variable_any::wait_until.3 +++ b/man/std::condition_variable_any::wait_until.3 @@ -1,119 +1,153 @@ -.TH std::condition_variable_any::wait_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::wait_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::wait_until \- std::condition_variable_any::wait_until + .SH Synopsis template< class Lock, class Clock, class Duration > - std::cv_status wait_until( Lock& lock, \fB(1)\fP \fI(since C++11)\fP + std::cv_status + wait_until( Lock& lock, \fB(1)\fP \fI(since C++11)\fP - const std::chrono::time_point& timeout_time ); + const std::chrono::time_point& + abs_time ); template< class Lock, class Clock, class Duration, class Predicate > bool wait_until( Lock& lock, \fB(2)\fP \fI(since C++11)\fP const std::chrono::time_point& - timeout_time, + abs_time, Predicate pred ); + template< class Lock, class Clock, class Duration, class Predicate + > - wait_until causes the current thread to block until the condition variable is - notified, a specific time is reached, or a spurious wakeup occurs, optionally - looping until some predicate is satisfied. - - 1) Atomically releases lock, blocks the current executing thread, and adds it to the - list of threads waiting on *this. The thread will be unblocked when notify_all() or - notify_one() is executed, or when the absolute time point timeout_time is reached. - It may also be unblocked spuriously. When unblocked, regardless of the reason, lock - is reacquired and wait_until exits. If this function exits via exception, lock is - also reacquired. - 2) Equivalent to - - while (!pred()) { - if (wait_until(lock, abs_time) == std::cv_status::timeout) { - return pred(); - } - } - return true; + bool wait_until( Lock& lock, std::stop_token stoken, \fB(3)\fP \fI(since C++20)\fP + const std::chrono::time_point& + abs_time, - This overload may be used to ignore spurious wakeups. + Predicate pred ); - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might, but might - not, be less or more than timeout_time - Clock::now() at the time of the call, - depending on the direction of the adjustment. The function also may block for longer - than until after timeout_time has been reached due to scheduling or resource - contention delays. + wait_until causes the current thread to block until the condition variable is + notified, the given duration has been elapsed, or a spurious wakeup occurs. pred can + be optionally provided to detect spurious wakeup. + + 1) Atomically calls lock.unlock() and blocks on *this. + The thread will be unblocked when notify_all() or notify_one() is executed, or + abs_time is reached. It may also be unblocked spuriously. + When unblocked, calls lock.lock() (possibly blocking on the lock), then returns. + 2,3) Waiting for a specific condition to become true, can be used to ignore spurious + awakenings. + 2) Equivalent to while (!pred()) + if (wait_until(lock, abs_time) == std::cv_status::timeout) + return pred(); + return true;. + 3) Registers *this for the duration of this call, to be notified if a stop request + is made on stoken's associated stop-state; it is then equivalent to while + (!stoken.stop_requested()) + { + if (pred()) + return true; + if (wait_until(lock, abs_time) == std::cv_status::timeout) + return pred(); + } + return pred();. + + Right after wait_until returns, lock is locked by the calling thread. If this + postcondition cannot be satisfied^[1], calls std::terminate. + + 1. ↑ This can happen if the re-locking of the mutex throws an exception. - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. +.SH Parameters - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + lock - an lock which must be locked by the calling thread + stoken - a stop token to register interruption for + abs_time - the time point where waiting expires + pred - the predicate to check whether the waiting can be completed +.SH Type requirements + - + Lock must meet the requirements of BasicLockable. + - + Predicate must meet the requirements of FunctionObject. -.SH Parameters +.SH Return value - lock - an object of type Lock that meets the requirements of BasicLockable, - which must be locked by the current thread - timeout_time - an object of type std::chrono::time_point representing the time when - to stop waiting - predicate which returns false if the waiting should be continued. + 1) std::cv_status::timeout if abs_time has been reached, otherwise + std::cv_status::no_timeout. + 2,3) The latest result of pred() before returning to the caller. - pred - The signature of the predicate function should be equivalent to the - following: +.SH Exceptions - bool pred(); + 1) Timeout-related exceptions. + 2,3) Timeout-related exceptions, and any exception thrown by pred. -.SH Return value +.SH Notes - 1) std::cv_status::timeout if the absolute timeout specified by abs_time was - reached, std::cv_status::no_timeout overwise. - 2) false if the predicate pred still evaluates to false after the abs_time timeout - expired, otherwise true. + The standard recommends that the clock tied to abs_time be used to measure time; + that clock is not required to be a monotonic clock. There are no guarantees + regarding the behavior of this function if the clock is adjusted discontinuously, + but the existing implementations convert abs_time from Clock to + std::chrono::system_clock and delegate to POSIX pthread_cond_timedwait so that the + wait honors adjustments to the system clock, but not to the user-provided Clock. In + any case, the function also may wait for longer than until after abs_time has been + reached due to scheduling or resource contention delays. -.SH Exceptions + Even if the clock in use is std::chrono::steady_clock or another monotonic clock, a + system clock adjustment may induce a spurious wakeup. - May throw std::system_error, may also propagate exceptions thrown by lock.lock() or - lock.unlock(). + The effects of notify_one()/notify_all() and each of the three atomic parts of + wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a + single total order that can be viewed as modification order of an atomic variable: + the order is specific to this individual condition variable. This makes it + impossible for notify_one() to, for example, be delayed and unblock a thread that + started waiting just after the call to notify_one() was made. .SH Example - + // Run this code - #include - #include + #include #include + #include #include - #include - + std::condition_variable_any cv; - std::mutex cv_m; - std::atomic i = ATOMIC_VAR_INIT(0); - - void waits(int idx) + std::mutex cv_m; // This mutex is used for three purposes: + // 1) to synchronize accesses to i + // 2) to synchronize accesses to std::cerr + // 3) for the condition variable cv + int i = 0; + + void waits() { std::unique_lock lk(cv_m); - auto now = std::chrono::system_clock::now(); - if(cv.wait_until(lk, now + std::chrono::milliseconds(idx*100), [](){return i == 1;})) - std::cerr << "Thread " << idx << " finished waiting. i == " << i << '\\n'; - else - std::cerr << "Thread " << idx << " timed out. i == " << i << '\\n'; + std::cerr << "Waiting... \\n"; + cv.wait(lk, []{ return i == 1; }); + std::cerr << "...finished waiting. i == 1\\n"; } - + void signals() { - std::this_thread::sleep_for(std::chrono::milliseconds(120)); - std::cerr << "Notifying...\\n"; + std::this_thread::sleep_for(std::chrono::seconds(1)); + { + std::lock_guard lk(cv_m); + std::cerr << "Notifying...\\n"; + } cv.notify_all(); - std::this_thread::sleep_for(std::chrono::milliseconds(100)); - i = 1; - std::cerr << "Notifying again...\\n"; + + std::this_thread::sleep_for(std::chrono::seconds(1)); + + { + std::lock_guard lk(cv_m); + i = 1; + std::cerr << "Notifying again...\\n"; + } cv.notify_all(); } - + int main() { - std::thread t1(waits, 1), t2(waits, 2), t3(waits, 3), t4(signals); + std::thread t1(waits), t2(waits), t3(waits), t4(signals); t1.join(); t2.join(); t3.join(); @@ -122,16 +156,33 @@ .SH Possible output: - Thread 1 timed out. i == 0 + Waiting... + Waiting... + Waiting... Notifying... - Thread 2 timed out. i == 0 Notifying again... - Thread 3 finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + ...finished waiting. i == 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 timeout-related exceptions were mentions these exceptions + missing in the specification + LWG 2135 C++11 the behavior was unclear if calls std::terminate in + lock.lock() throws an exception this case .SH See also - wait blocks the current thread until the condition variable is woken up - \fI(public member function)\fP - blocks the current thread until the condition variable is woken up or after - wait_for the specified timeout duration - \fI(public member function)\fP + wait blocks the current thread until the condition variable is awakened + \fI(public member function)\fP + blocks the current thread until the condition variable is awakened or + wait_until until specified time point has been reached + \fI(public member function)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::condition_variable_any::~condition_variable_any.3 b/man/std::condition_variable_any::~condition_variable_any.3 index 0ea0c9815..233ebea7e 100644 --- a/man/std::condition_variable_any::~condition_variable_any.3 +++ b/man/std::condition_variable_any::~condition_variable_any.3 @@ -1,8 +1,11 @@ -.TH std::condition_variable_any::~condition_variable_any 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::condition_variable_any::~condition_variable_any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::condition_variable_any::~condition_variable_any \- std::condition_variable_any::~condition_variable_any + .SH Synopsis - ~condition_variable_any(); \fB(1)\fP \fI(since C++11)\fP + ~condition_variable_any(); \fI(since C++11)\fP - Destroys the object of type std::condition_variable_any + Destroys the object of type std::condition_variable_any. It is only safe to invoke the destructor if all threads have been notified. It is not required that they have exited their respective wait functions: some threads may @@ -14,6 +17,7 @@ wait functions in a loop or are using the overloads of the wait functions that take a predicate. -.SH Exceptions +.SH See also - \fI(none)\fP + C documentation for + cnd_destroy diff --git a/man/std::conditional.3 b/man/std::conditional.3 index 6190dfc75..51803ccd6 100644 --- a/man/std::conditional.3 +++ b/man/std::conditional.3 @@ -1,4 +1,7 @@ -.TH std::conditional 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::conditional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::conditional \- std::conditional + .SH Synopsis Defined in header template< bool B, class T, class F > \fI(since C++11)\fP @@ -7,6 +10,8 @@ Provides member typedef type, which is defined as T if B is true at compile time, or as F if B is false. + If the program adds specializations for std::conditional, the behavior is undefined. + .SH Member types Member type Definition @@ -20,39 +25,39 @@ .SH Possible implementation template - struct conditional { typedef T type; }; - + struct conditional { using type = T; }; + template - struct conditional { typedef F type; }; + struct conditional { using type = F; }; .SH Example - + // Run this code #include #include #include - + int main() { - typedef std::conditional::type Type1; - typedef std::conditional::type Type2; - typedef std::conditional= sizeof(double), int, double>::type Type3; - + using Type1 = std::conditional::type; + using Type2 = std::conditional::type; + using Type3 = std::conditional= sizeof(double), int, double>::type; + std::cout << typeid(Type1).name() << '\\n'; std::cout << typeid(Type2).name() << '\\n'; std::cout << typeid(Type3).name() << '\\n'; } -.SH Output: +.SH Possible output: - i - d - d + int + double + double .SH See also - enable_if hides a function overload or template specialization based on compile-time - \fI(C++11)\fP boolean - \fI(class template)\fP + enable_if conditionally removes a function overload or template specialization from + \fI(C++11)\fP overload resolution + \fI(class template)\fP diff --git a/man/std::conj(std::complex).3 b/man/std::conj(std::complex).3 index e2af48b2e..bf1876a3d 100644 --- a/man/std::conj(std::complex).3 +++ b/man/std::conj(std::complex).3 @@ -1,32 +1,93 @@ -.TH std::conj(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::conj(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::conj(std::complex) \- std::conj(std::complex) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP - complex conj( const complex& z ); - std::complex conj( long double z ); \fB(2)\fP \fI(since C++11)\fP - template< class DoubleOrIngeter > \fB(3)\fP \fI(since C++11)\fP - std::complex conj( DoubleOrInteger z ); - std::complex conj( float z ); \fB(4)\fP \fI(since C++11)\fP + template< class T > (until + std::complex conj( const std::complex& z ); C++20) + template< class T > (since + constexpr std::complex conj( const C++20) + std::complex& z ); + Additional overloads \fI(since C++11)\fP + Defined in header + std::complex conj( float f ); + (until + std::complex conj( double f ); C++20) - Returns the complex conjugate of the complex number z. + std::complex conj( long double f ); + constexpr std::complex conj( float f ); \fB(1)\fP + (since + constexpr std::complex conj( double f C++20) + ); (until + (A) C++23) + constexpr std::complex conj( long + double f ); + template< class FloatingPoint > (since + constexpr std::complex conj( C++23) + FloatingPoint f ); + template< class Integer > (until + constexpr std::complex conj( Integer i ); (B) C++20) + template< class Integer > (since + constexpr std::complex conj( Integer i ); C++20) - \fI(since C++11)\fPAdditional overloads are provided for float, double, long double, and - all integer types, which are treated as complex numbers with zero imaginary - component. + 1) Computes the complex conjugate of z by reversing the sign of the imaginary part. + + A,B) Additional overloads are provided for all integer and + floating-point types, which are treated as complex numbers with zero \fI(since C++11)\fP + imaginary component. .SH Parameters z - complex value + f - floating-point value + i - integer value .SH Return value - the complex conjugate of z + 1) The complex conjugate of z. + A) std::complex(f). + B) std::complex(i). + +.SH Notes + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num: + + * If num has a + standard + (until C++23) floating-point type T, then std::conj(num) has the same effect as + std::conj(std::complex(num)). + * Otherwise, if num has an integer type, then std::conj(num) has the same effect + as std::conj(std::complex(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::complex z(1.0, 2.0); + std::cout << "The conjugate of " << z << " is " << std::conj(z) << '\\n' + << "Their product is " << z * std::conj(z) << '\\n'; + } + +.SH Output: + + The conjugate of (1,2) is (1,-2) + Their product is (5,0) .SH See also abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP + \fI(function template)\fP norm returns the squared magnitude - \fI(function template)\fP + \fI(function template)\fP polar constructs a complex number from magnitude and phase angle - \fI(function template)\fP + \fI(function template)\fP + C documentation for + conj diff --git a/man/std::conjunction.3 b/man/std::conjunction.3 new file mode 100644 index 000000000..10bf3c54a --- /dev/null +++ b/man/std::conjunction.3 @@ -0,0 +1,111 @@ +.TH std::conjunction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::conjunction \- std::conjunction + +.SH Synopsis + Defined in header + template< class... B > \fI(since C++17)\fP + struct conjunction; + + Forms the logical conjunction of the type traits B..., effectively performing a + logical AND on the sequence of traits. + + The specialization std::conjunction has a public and unambiguous base + that is + + * if sizeof...(B) == 0, std::true_type; otherwise + * the first type Bi in B1, ..., BN for which bool(Bi::value) == false, or BN if + there is no such type. + + The member names of the base class, other than conjunction and operator=, are not + hidden and are unambiguously available in conjunction. + + Conjunction is short-circuiting: if there is a template type argument Bi with + bool(Bi::value) == false, then instantiating conjunction::value does + not require the instantiation of Bj::value for j > i. + + If the program adds specializations for std::conjunction or std::conjunction_v, the + behavior is undefined. + +.SH Template parameters + + B... - every template argument Bi for which Bi::value is instantiated must be usable + as a base class and define member value that is convertible to bool + + Helper variable template + + template< class... B > \fI(since C++17)\fP + inline constexpr bool conjunction_v = conjunction::value; + +.SH Possible implementation + + template struct conjunction : std::true_type {}; + template struct conjunction : B1 {}; + template + struct conjunction + : std::conditional_t, B1> {}; + +.SH Notes + + A specialization of conjunction does not necessarily inherit from either + std::true_type or std::false_type: it simply inherits from the first B whose + ::value, explicitly converted to bool, is false, or from the very last B when all of + them convert to true. For example, std::conjunction, + std::integral_constant>::value is 4. + + The short-circuit instantiation differentiates conjunction from fold expressions: a + fold expression, like (... && Bs::value), instantiates every B in Bs, while + std::conjunction_v stops instantiation once the value can be determined. This + is particularly useful if the later type is expensive to instantiate or can cause a + hard error when instantiated with the wrong type. + + Feature-test macro Value Std Feature + __cpp_lib_logical_traits 201510L \fI(C++17)\fP Logical operator type traits + +.SH Example + + +// Run this code + + #include + #include + + // func is enabled if all Ts... have the same type as T + template + std::enable_if_t...>> + func(T, Ts...) + { + std::cout << "all types in pack are T\\n"; + } + + // otherwise + template + std::enable_if_t...>> + func(T, Ts...) + { + std::cout << "not all types in pack are T\\n"; + } + + template + constexpr bool all_types_are_same = std::conjunction_v...>; + + static_assert(all_types_are_same); + static_assert(not all_types_are_same); + + int main() + { + func(1, 2, 3); + func(1, 2, "hello!"); + } + +.SH Output: + + all types in pack are T + not all types in pack are T + +.SH See also + + negation logical NOT metafunction + \fI(C++17)\fP \fI(class template)\fP + disjunction variadic logical OR metafunction + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::construct_at.3 b/man/std::construct_at.3 new file mode 100644 index 000000000..4c71339bd --- /dev/null +++ b/man/std::construct_at.3 @@ -0,0 +1,86 @@ +.TH std::construct_at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::construct_at \- std::construct_at + +.SH Synopsis + Defined in header + template< class T, class... Args > \fI(since C++20)\fP + constexpr T* construct_at( T* p, Args&&... args ); + + Creates a T object initialized with arguments args... at given address p. + Specialization of this function template participates in overload resolution only if + ::new(std::declval()) T(std::declval()...) is well-formed in an + unevaluated context. + + Equivalent to + + return ::new (static_cast(p)) T(std::forward(args)...); + + except that construct_at may be used in evaluation of constant expressions. + + When construct_at is called in the evaluation of some constant expression e, the + argument p must point to either storage obtained by std::allocator::allocate or + an object whose lifetime began within the evaluation of e. + +.SH Parameters + + p - pointer to the uninitialized storage on which a T object will be + constructed + args... - arguments used for initialization + +.SH Return value + + p + +.SH Example + + +// Run this code + + #include + #include + + class S + { + int x_; + float y_; + double z_; + public: + constexpr S(int x, float y, double z) : x_{x}, y_{y}, z_{z} {} + [[nodiscard("no side-effects!")]] + constexpr bool operator==(const S&) const noexcept = default; + }; + + consteval bool test() + { + alignas(S) unsigned char storage[sizeof(S)]{}; + S uninitialized = std::bit_cast(storage); + std::destroy_at(&uninitialized); + S* ptr = std::construct_at(std::addressof(uninitialized), 42, 2.71f, 3.14); + const bool res{*ptr == S{42, 2.71f, 3.14}}; + std::destroy_at(ptr); + return res; + } + static_assert(test()); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 construct_at could create objects only cv-unqualified types are + of a cv-qualified types permitted + +.SH See also + + allocate allocates uninitialized storage + \fI(public member function of std::allocator)\fP + construct constructs an object in the allocated storage + \fB[static]\fP \fI(function template)\fP + destroy_at destroys an object at a given address + \fI(C++17)\fP \fI(function template)\fP + ranges::construct_at creates an object at a given address + (C++20) (niebloid) diff --git a/man/std::constructible_from.3 b/man/std::constructible_from.3 new file mode 100644 index 000000000..ab614d0e3 --- /dev/null +++ b/man/std::constructible_from.3 @@ -0,0 +1,23 @@ +.TH std::constructible_from 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::constructible_from \- std::constructible_from + +.SH Synopsis + Defined in header + template< class T, class... Args > + + concept constructible_from = \fI(since C++20)\fP + + std::destructible && std::is_constructible_v; + + The constructible_from concept specifies that a variable of type T can be + initialized with the given set of argument types Args.... + +.SH See also + + is_constructible + is_trivially_constructible + is_nothrow_constructible checks if a type has a constructor for specific arguments + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::contiguous_iterator.3 b/man/std::contiguous_iterator.3 new file mode 100644 index 000000000..e6668846d --- /dev/null +++ b/man/std::contiguous_iterator.3 @@ -0,0 +1,40 @@ +.TH std::contiguous_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::contiguous_iterator \- std::contiguous_iterator + +.SH Synopsis + Defined in header + template< class I > + + concept contiguous_iterator = + std::random_access_iterator && + std::derived_from, + std::contiguous_iterator_tag> && + std::is_lvalue_reference_v> && + std::same_as< (since + std::iter_value_t, C++20) + std::remove_cvref_t> + > && + requires(const I& i) { + { std::to_address(i) } -> + std::same_as>>; + + }; + + The contiguous_iterator concept refines random_access_iterator by providing a + guarantee the denoted elements are stored contiguously in the memory. + +.SH Notes + + contiguous_iterator is modeled by every pointer type to complete object type. + + Iterator types in the standard library that are required to satisfy the + LegacyContiguousIterator requirements in C++17 are also required to model + contiguous_iterator in C++20. + +.SH See also + + specifies that a bidirectional_iterator is a random-access + random_access_iterator iterator, supporting advancement in constant time and + (C++20) subscripting + (concept) diff --git a/man/std::convertible_to.3 b/man/std::convertible_to.3 new file mode 100644 index 000000000..f99e0a714 --- /dev/null +++ b/man/std::convertible_to.3 @@ -0,0 +1,46 @@ +.TH std::convertible_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::convertible_to \- std::convertible_to + +.SH Synopsis + Defined in header + template< class From, class To > + + concept convertible_to = + std::is_convertible_v && \fI(since C++20)\fP + requires { + static_cast(std::declval()); + + }; + + The concept convertible_to specifies that an expression of the same type + and value category as those of std::declval() can be implicitly and explicitly + converted to the type To, and the two forms of conversion produce equal results. + + Semantic requirements + + convertible_to is modeled only if, given a function fun of type + std::add_rvalue_reference_t() such that the expression fun() is + equality-preserving, + + * Either + * To is neither an object type nor a reference-to-object type, or + * static_cast(fun()) is equal to []() -> To { return fun(); }(), and + * One of the following is true: + * std::add_rvalue_reference_t is not a reference-to-object type, or + * std::add_rvalue_reference_t is an rvalue reference to a + non-const-qualified type, and the resulting state of the object referenced + by fun() is valid but unspecified after either expression above; or + * the object referred to by fun() is not modified by either expression above. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH See also + + is_convertible + is_nothrow_convertible checks if a type can be converted to the other type + \fI(C++11)\fP \fI(class template)\fP + (C++20) diff --git a/man/std::copy,std::copy_if.3 b/man/std::copy,std::copy_if.3 index 656790532..833d46d9e 100644 --- a/man/std::copy,std::copy_if.3 +++ b/man/std::copy,std::copy_if.3 @@ -1,43 +1,87 @@ -.TH std::copy,std::copy_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::copy,std::copy_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copy,std::copy_if \- std::copy,std::copy_if + .SH Synopsis Defined in header - template< class InputIt, class OutputIt > \fB(1)\fP - OutputIt copy( InputIt first, InputIt last, OutputIt d_first ); - template< class InputIt, class OutputIt, class UnaryPredicate > + template< class InputIt, class OutputIt > + + OutputIt copy( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + + OutputIt d_first ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + ForwardIt2 copy( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + + ForwardIt2 d_first ); + template< class InputIt, class OutputIt, class UnaryPred + > + \fB(3)\fP \fI(since C++11)\fP + OutputIt copy_if( InputIt first, InputIt last, (constexpr since C++20) + + OutputIt d_first, UnaryPred pred ); + template< class ExecutionPolicy, - OutputIt copy_if( InputIt first, InputIt last, \fB(2)\fP \fI(since C++11)\fP - OutputIt d_first, + class ForwardIt1, class ForwardIt2, class + UnaryPred > + ForwardIt2 copy_if( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, - UnaryPredicate pred ); + ForwardIt2 d_first, UnaryPred pred + ); Copies the elements in the range, defined by [first, last), to another range - beginning at d_first. The second function only copies the elements for which the - predicate pred returns true. The order of the elements that are not removed is + beginning at d_first (copy destination range). + + 1) Copies all elements in the range [first, last) starting from first and proceeding + to last. + If d_first is in [first, last), the behavior is undefined. In this case, + std::copy_backward may be used instead. + 2) Copies the elements, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If [first, last) and the copy destination range overlaps, the behavior is undefined. + 3) Only copies the elements for which the predicate pred returns true. This copy + algorithm is stable: the relative order of the elements that are copied is preserved. + If [first, last) and the copy destination range overlaps, the behavior is undefined. + 4) Same as \fB(3)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to copy - d_first - the beginning of the destination range. If d_first is within [first, - last), std::copy_backward must be used instead of std::copy. + d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for details. unary predicate which returns true for the required elements. - The signature of the predicate function should be equivalent to the - following: - - pred - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression pred(v) must be convertible to bool for every argument + pred - v of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - UnaryPredicate must meet the requirements of Predicate. + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + UnaryPred must meet the requirements of Predicate. .SH Return value @@ -46,74 +90,82 @@ .SH Complexity - 1) Exactly last - first assignments + Given \\(\\scriptsize N\\)N as std::distance(first, last): - 2) Exactly last - first applications of the predicate + 1,2) Exactly \\(\\scriptsize N\\)N assignments. + 3,4) Exactly \\(\\scriptsize N\\)N applications of the predicate pred, and at most + \\(\\scriptsize N\\)N assignments. -.SH Notes + For the overloads with an ExecutionPolicy, there may be a performance cost if + ForwardIt1's value type is not MoveConstructible. - In practice, implementations of std::copy avoid multiple assignments and use bulk - copy functions such as std::memmove if the value type is TriviallyCopyable +.SH Exceptions - When copying overlapping ranges, std::copy is appropriate when copying to the left - (beginning of the destination range is outside the source range) while - std::copy_backward is appropriate when copying to the right (end of the destination - range is outside the source range). + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + copy \fB(1)\fP template OutputIt copy(InputIt first, InputIt last, OutputIt d_first) { - while (first != last) { - *d_first++ = *first++; - } + for (; first != last; (void)++first, (void)++d_first) + *d_first = *first; + return d_first; } -.SH Second version - template + copy_if \fB(3)\fP + template OutputIt copy_if(InputIt first, InputIt last, - OutputIt d_first, UnaryPredicate pred) + OutputIt d_first, UnaryPred pred) { - while (first != last) { + for (; first != last; ++first) if (pred(*first)) - *d_first++ = *first; - first++; - } + { + *d_first = *first; + ++d_first; + } + return d_first; } - If you do not have C++11, an equivalent to std::copy_if is to use - std::remove_copy_if with the negated predicate. +.SH Notes - template - OutputIt copy_if(InputIt first, InputIt last, - OutputIt d_first, UnaryPredicate pred) - { - return std::remove_copy_if(first, last, d_first, std::not1(pred)); - } + In practice, implementations of std::copy avoid multiple assignments and use bulk + copy functions such as std::memmove if the value type is TriviallyCopyable and the + iterator types satisfy LegacyContiguousIterator. + + When copying overlapping ranges, std::copy is appropriate when copying to the left + (beginning of the destination range is outside the source range) while + std::copy_backward is appropriate when copying to the right (end of the destination + range is outside the source range). .SH Example - The following code uses copy to both copy the contents of one vector to another and - to display the resulting vector: + The following code uses std::copy to both copy the contents of one std::vector to + another and to display the resulting std::vector. + - // Run this code #include #include - #include #include #include - + #include + int main() { std::vector from_vector(10); std::iota(from_vector.begin(), from_vector.end(), 0); - + std::vector to_vector; std::copy(from_vector.begin(), from_vector.end(), std::back_inserter(to_vector)); @@ -122,22 +174,62 @@ // std::copy(from_vector.begin(), from_vector.end(), to_vector.begin()); // either way is equivalent to // std::vector to_vector = from_vector; - + std::cout << "to_vector contains: "; - + std::copy(to_vector.begin(), to_vector.end(), std::ostream_iterator(std::cout, " ")); std::cout << '\\n'; + + std::cout << "odd numbers in to_vector are: "; + + std::copy_if(to_vector.begin(), to_vector.end(), + std::ostream_iterator(std::cout, " "), + [](int x) { return x % 2 != 0; }); + std::cout << '\\n'; + + std::cout << "to_vector contains these multiples of 3: "; + + to_vector.clear(); + std::copy_if(from_vector.begin(), from_vector.end(), + std::back_inserter(to_vector), + [](int x) { return x % 3 == 0; }); + + for (const int x : to_vector) + std::cout << x << ' '; + std::cout << '\\n'; } -.SH Output: +.SH Possible output: to_vector contains: 0 1 2 3 4 5 6 7 8 9 + odd numbers in to_vector are: 1 3 5 7 9 + to_vector contains these multiples of 3: 0 3 6 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2039 C++11 the return value of std::copy_if was not specified + specified + LWG 2044 C++11 the stability of std::copy_if was not defined defined .SH See also - copy_backward copies a range of elements in backwards order - \fI(function template)\fP - remove_copy copies a range of elements omitting those that satisfy specific - remove_copy_if criteria - \fI(function template)\fP + copy_backward copies a range of elements in backwards order + \fI(function template)\fP + reverse_copy creates a copy of a range that is reversed + \fI(function template)\fP + copy_n copies a number of elements to a new location + \fI(C++11)\fP \fI(function template)\fP + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + remove_copy copies a range of elements omitting those that satisfy specific + remove_copy_if criteria + \fI(function template)\fP + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) diff --git a/man/std::copy_backward.3 b/man/std::copy_backward.3 index 5a61024f6..20df92ecc 100644 --- a/man/std::copy_backward.3 +++ b/man/std::copy_backward.3 @@ -1,31 +1,35 @@ -.TH std::copy_backward 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::copy_backward 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copy_backward \- std::copy_backward + .SH Synopsis Defined in header template< class BidirIt1, class BidirIt2 > - BidirIt2 copy_backward( BidirIt1 first, BidirIt1 last, BidirIt2 d_last ); + BidirIt2 copy_backward( BidirIt1 first, BidirIt1 last, (constexpr since C++20) + BidirIt2 d_last ); - Copies the elements from the range, defined by [first, last), to another range - ending at d_last. The elements are copied in reverse order (the last element is - copied first), but their relative order is preserved. + Copies the elements from the range [first, last) to another range ending at d_last. + The elements are copied in reverse order (the last element is copied first), but + their relative order is preserved. The behavior is undefined if d_last is within (first, last]. std::copy must be used instead of std::copy_backward in that case. .SH Parameters - first, last - the range of the elements to copy - d_last - end of the destination range.. + first, last - the range of the elements to copy from + d_last - the end of the destination range .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Return value - iterator to the last element copied. + Iterator to the last element copied. .SH Complexity - Exactly last - first assignments. + Exactly std::distance(first, last) assignments. .SH Notes @@ -36,46 +40,58 @@ .SH Possible implementation - template< class BidirIt1, class BidirIt2 > + template BidirIt2 copy_backward(BidirIt1 first, BidirIt1 last, BidirIt2 d_last) { - while (first != last) { + while (first != last) *(--d_last) = *(--last); - } return d_last; } .SH Example - + // Run this code #include #include - + #include + #include + int main() { - std::vector from_vector; - for (int i = 0; i < 10; i++) { - from_vector.push_back(i); - } - - std::vector to_vector(15); - - std::copy_backward(from_vector.begin(), from_vector.end(), to_vector.end()); - - std::cout << "to_vector contains: "; - for (unsigned int i = 0; i < to_vector.size(); i++) { - std::cout << to_vector[i] << " "; - } - } + std::vector source(4); + std::iota(source.begin(), source.end(), 1); // fills with 1, 2, 3, 4 + + std::vector destination(6); + + std::copy_backward(source.begin(), source.end(), destination.end()); + + std::cout << "destination contains: "; + for (auto i: destination) + std::cout << i << ' '; + std::cout << '\\n'; + } .SH Output: - to_vector contains: 0 0 0 0 0 0 1 2 3 4 5 6 7 8 9 + destination contains: 0 0 1 2 3 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the behavior was well-defined if d_last + LWG 1206 C++98 == last 1. made undefined + 2. the behavior was undefined if d_last == 2. made well-defined + first .SH See also - copy copies a range of elements to a new location - copy_if \fI(function template)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP \fI(C++11)\fP + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) diff --git a/man/std::copy_constructible.3 b/man/std::copy_constructible.3 new file mode 100644 index 000000000..ac11319a9 --- /dev/null +++ b/man/std::copy_constructible.3 @@ -0,0 +1,42 @@ +.TH std::copy_constructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copy_constructible \- std::copy_constructible + +.SH Synopsis + Defined in header + template< class T > + + concept copy_constructible = + std::move_constructible && + std::constructible_from && std::convertible_to && \fI(since C++20)\fP + std::constructible_from && std::convertible_to && + + std::constructible_from && std::convertible_to; + + The concept copy_constructible is satisfied if T is an lvalue reference type, or if + it is a move_constructible object type where an object of that type can constructed + from a (possibly const) lvalue or const rvalue of that type in both direct- and + copy-initialization contexts with the usual semantics (a copy is constructed with + the source unchanged). + + Semantic requirements + + If T is an object type, then copy_constructible is modeled only if given + + * v, an lvalue of type (possibly const) T or an rvalue of type const T, + + the following are true: + + * After the definition T u = v;, u is equal to v and v is not modified; + * T(v) is equal to v and does not modify v. + +.SH See also + + is_copy_constructible + is_trivially_copy_constructible + is_nothrow_copy_constructible checks if a type has a copy constructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::copy_n.3 b/man/std::copy_n.3 index 56a0d9140..9d5e91ac8 100644 --- a/man/std::copy_n.3 +++ b/man/std::copy_n.3 @@ -1,71 +1,121 @@ -.TH std::copy_n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::copy_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copy_n \- std::copy_n + .SH Synopsis Defined in header - template< class InputIt, class Size, class OutputIt > - OutputIt copy_n( InputIt first, Size count, OutputIt result ); - - Copies exactly count values from the range beginning at first to the range beginning - at result, if count>0. Does nothing otherwise. + template< class InputIt, class Size, class OutputIt > \fI(since C++11)\fP + OutputIt copy_n( InputIt first, Size count, OutputIt \fB(1)\fP (constexpr since C++20) + result ); + template< class ExecutionPolicy, + + class ForwardIt1, class Size, class ForwardIt2 + > \fB(2)\fP \fI(since C++17)\fP + ForwardIt2 copy_n( ExecutionPolicy&& policy, + + ForwardIt1 first, Size count, + ForwardIt2 result ); + + 1) Copies exactly count values from the range beginning at first to the range + beginning at result. Formally, for each integer i in [0, count), performs *(result + + i) = *(first + i). + Overlap of ranges is formally permitted, but leads to unpredictable ordering of the + results. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first - the beginning of the range of elements to copy from - count - number of the elements to copy - result - the beginning of the destination range + first - the beginning of the range of elements to copy from + count - number of the elements to copy + result - the beginning of the destination range + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value - Iterator in the destination range, pointing past the last element copied if count>0 - or result otherwise. + Iterator in the destination range, pointing past the last element copied if count > + 0 or result otherwise. .SH Complexity - Exactly count assignments, if count>0. + Zero assignments if count < 0; count assignments otherwise. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template< class InputIt, class Size, class OutputIt> + template + constexpr //< since C++20 OutputIt copy_n(InputIt first, Size count, OutputIt result) { - if (count > 0) { - *result++ = *first; - for (Size i = 1; i < count; ++i) { - *result++ = *++first; - } + if (count > 0) + { + *result = *first; + ++result; + for (Size i = 1; i != count; ++i, ++result) + *result = *++first; } + return result; } .SH Example - + // Run this code - #include - #include #include + #include #include - + #include + #include + #include + int main() { - std::string in = "1234567890"; + std::string in {"1234567890"}; std::string out; - + std::copy_n(in.begin(), 4, std::back_inserter(out)); std::cout << out << '\\n'; + + std::vector v_in(128); + std::iota(v_in.begin(), v_in.end(), 1); + std::vector v_out(v_in.size()); + + std::copy_n(v_in.cbegin(), 100, v_out.begin()); + std::cout << std::accumulate(v_out.begin(), v_out.end(), 0) << '\\n'; } .SH Output: 1234 + 5050 .SH See also - copy copies a range of elements to a new location - copy_if \fI(function template)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP \fI(C++11)\fP + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) diff --git a/man/std::copyable.3 b/man/std::copyable.3 new file mode 100644 index 000000000..6f1bb7f45 --- /dev/null +++ b/man/std::copyable.3 @@ -0,0 +1,23 @@ +.TH std::copyable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copyable \- std::copyable + +.SH Synopsis + Defined in header + template< class T > + + concept copyable = + std::copy_constructible && + std::movable && \fI(since C++20)\fP + std::assignable_from && + std::assignable_from && + + std::assignable_from; + + The concept copyable specifies that T is a movable object type that can also be + copied (that is, it supports copy construction and copy assignment). + +.SH See also + + movable specifies that an object of a type can be moved and swapped + (C++20) (concept) diff --git a/man/std::copyable_function.3 b/man/std::copyable_function.3 new file mode 100644 index 000000000..6e8d17759 --- /dev/null +++ b/man/std::copyable_function.3 @@ -0,0 +1,106 @@ +.TH std::copyable_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copyable_function \- std::copyable_function + +.SH Synopsis + Defined in header + template< class... > \fB(1)\fP (since C++26) + class copyable_function; // not defined + template< class R, class... Args > + + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; \fB(2)\fP (since C++26) + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + class copyable_function; + template< class R, class... Args > + + class copyable_function; + + Class template std::copyable_function is a general-purpose polymorphic function + wrapper. std::copyable_function objects can store and invoke any CopyConstructible + Callable target — functions, lambda expressions, bind expressions, or other function + objects, as well as pointers to member functions and pointers to member objects. + + The stored callable object is called the target of std::copyable_function. If a + std::copyable_function contains no target, it is called empty. Unlike std::function, + invoking an empty std::copyable_function results in undefined behavior. + + std::copyable_functions supports every possible combination of cv-qualifiers, + ref-qualifiers, and noexcept-specifiers not including volatile provided in its + template parameter. These qualifiers and specifier (if any) are added to its + operator(). + + std::copyable_function satisfies the requirements of CopyConstructible and + CopyAssignable. + +.SH Member types + + Type Definition + result_type R + +.SH Member functions + + constructor constructs a new std::copyable_function object + (C++26) \fI(public member function)\fP + destructor destroys a std::copyable_function object + (C++26) \fI(public member function)\fP + operator= replaces or destroys the target + (C++26) \fI(public member function)\fP + swap swaps the targets of two std::copyable_function objects + (C++26) \fI(public member function)\fP + operator bool checks if the std::copyable_function has a target + (C++26) \fI(public member function)\fP + operator() invokes the target + (C++26) \fI(public member function)\fP + +.SH Non-member functions + + swap(std::copyable_function) overloads the std::swap algorithm + (C++26) \fI(function)\fP + operator== compares a std::copyable_function with nullptr + (C++26) \fI(function)\fP + +.SH Notes + + Implementations may store a callable object of small size within the + std::copyable_function object. Such small object optimization is effectively + required for function pointers and std::reference_wrapper specializations, and can + only be applied to types T for which std::is_nothrow_move_constructible_v is + true. + + Feature-test macro Value Std Feature + __cpp_lib_copyable_function 202306L (C++26) std::copyable_function + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::copysign,std::copysignf,std::copysignl.3 b/man/std::copysign,std::copysignf,std::copysignl.3 new file mode 100644 index 000000000..b923e23ed --- /dev/null +++ b/man/std::copysign,std::copysignf,std::copysignl.3 @@ -0,0 +1,130 @@ +.TH std::copysign,std::copysignf,std::copysignl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::copysign,std::copysignf,std::copysignl \- std::copysign,std::copysignf,std::copysignl + +.SH Synopsis + Defined in header + float copysign ( float mag, float sgn ); + + double copysign ( double mag, double sgn ); (until C++23) + + long double copysign ( long double mag, long double + sgn ); + constexpr /* floating-point-type */ + + copysign ( /* floating-point-type */ + mag, (since C++23) + \fB(1)\fP + /* floating-point-type */ sgn + ); + float copysignf( float mag, float sgn ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double copysignl( long double mag, long double \fB(3)\fP \fI(since C++11)\fP + sgn ); (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double copysign ( Integer mag, Integer sgn ); + + 1-3) Composes a floating point value with the magnitude of mag and the sign of sgn. + The library provides overloads of std::copysign for all cv-unqualified + floating-point types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + mag, sgn - floating-point or integer values + +.SH Return value + + If no errors occur, the floating point value with the magnitude of mag and the sign + of sgn is returned. + + If mag is NaN, then NaN with the sign of sgn is returned. + + If sgn is -0, the result is only negative if the implementation supports the signed + zero consistently in arithmetic operations. + +.SH Error handling + + This function is not subject to any errors specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * The returned value is exact (FE_INEXACT is never raised) and independent of the + current rounding mode. + +.SH Notes + + std::copysign is the only portable way to manipulate the sign of a NaN value (to + examine the sign of a NaN, std::signbit may also be used). + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::copysign(num1, + num2) has the same effect as std::copysign(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::copysign(num1, num2) has the same effect as (until C++23) + std::copysign(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::copysign(num1, num2) has the same effect as + std::copysign(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::copysign(num1, num2) + has the same effect as std::copysign(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::showpos + << "copysign(1.0,+2.0) = " << std::copysign(1.0, +2.0) << '\\n' + << "copysign(1.0,-2.0) = " << std::copysign(1.0, -2.0) << '\\n' + << "copysign(inf,-2.0) = " << std::copysign(INFINITY, -2.0) << '\\n' + << "copysign(NaN,-2.0) = " << std::copysign(NAN, -2.0) << '\\n'; + } + +.SH Output: + + copysign(1.0,+2.0) = +1 + copysign(1.0,-2.0) = -1 + copysign(inf,-2.0) = -inf + copysign(NaN,-2.0) = -nan + +.SH See also + + abs(float) + fabs + fabsf absolute value of a floating point value (\\(\\small{|x|}\\)|x|) + fabsl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + signbit checks if the given number is negative + \fI(C++11)\fP \fI(function)\fP + C documentation for + copysign diff --git a/man/std::copysign.3 b/man/std::copysign.3 deleted file mode 100644 index 307744b33..000000000 --- a/man/std::copysign.3 +++ /dev/null @@ -1,27 +0,0 @@ -.TH std::copysign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float copysign( float x, float y ); \fB(1)\fP \fI(since C++11)\fP - double copysign( double x, double y ); \fB(2)\fP \fI(since C++11)\fP - long double copysign( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP - Promoted copysign( Arithmetic1 x, Arithmetic2 y ); \fB(4)\fP \fI(since C++11)\fP - - Composes a floating point value with the magnitude of x and the sign of y. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - -.SH Parameters - - x, y - floating point values - -.SH Return value - - floating point value with the magnitude of x and the sign of y - -.SH See also - - abs(float) absolute value of a floating point value (|x|) - fabs \fI(function)\fP - signbit checks if the given number is negative - \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::coroutine_handle,std::noop_coroutine_handle.3 b/man/std::coroutine_handle,std::noop_coroutine_handle.3 new file mode 100644 index 000000000..c8c3343bf --- /dev/null +++ b/man/std::coroutine_handle,std::noop_coroutine_handle.3 @@ -0,0 +1,221 @@ +.TH std::coroutine_handle,std::noop_coroutine_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle,std::noop_coroutine_handle \- std::coroutine_handle,std::noop_coroutine_handle + +.SH Synopsis + Defined in header + template< class Promise = void > \fB(1)\fP \fI(since C++20)\fP + struct coroutine_handle; + template<> \fB(2)\fP \fI(since C++20)\fP + struct coroutine_handle; + template<> \fB(3)\fP \fI(since C++20)\fP + struct coroutine_handle; + using noop_coroutine_handle = \fB(4)\fP \fI(since C++20)\fP + std::coroutine_handle; + + The class template coroutine_handle can be used to refer to a suspended or executing + coroutine. Every specialization of coroutine_handle is a LiteralType. + + 1) Primary template, can be created from the promise object of type Promise. + 2) Specialization std::coroutine_handle erases the promise type. It is + convertible from other specializations. + 3) Specialization std::coroutine_handle refers to no-op + coroutines. It cannot be created from a promise object. + + On typical implementations, every specialization of std::coroutine_handle is + TriviallyCopyable. + + If the program adds specializations for std::coroutine_handle, the behavior is + undefined. + +.SH Member functions + + constructor constructs a coroutine_handle object + (C++20) \fI(public member function)\fP + operator= assigns the coroutine_handle object + (C++20) \fI(public member function)\fP + Conversion + operator coroutine_handle<> obtains a type-erased coroutine_handle + (C++20) \fI(public member function)\fP +.SH Observers + done checks if the coroutine has completed + (C++20) \fI(public member function)\fP + operator bool checks if the handle represents a coroutine + (C++20) \fI(public member function)\fP + Control + operator() resumes execution of the coroutine + resume \fI(public member function)\fP + (C++20) + destroy destroys a coroutine + (C++20) \fI(public member function)\fP + Promise Access + promise access the promise of a coroutine + (C++20) \fI(public member function)\fP + from_promise creates a coroutine_handle from the promise object of a + \fB[static]\fP (C++20) coroutine + \fI(public static member function)\fP + Export/Import + address exports the underlying address, i.e. the pointer backing + (C++20) the coroutine + \fI(public member function)\fP + from_address imports a coroutine from a pointer + \fB[static]\fP (C++20) \fI(public static member function)\fP + +.SH Non-member functions + + operator== compares two coroutine_handle objects + operator<=> \fI(function)\fP + (C++20) + +.SH Helper classes + + std::hash hash support for std::coroutine_handle + (C++20) \fI(class template specialization)\fP + +.SH Notes + + A coroutine_handle may be dangling, in which case the coroutine_handle must be used + carefully in order to avoid undefined behavior. + +.SH Example + + +// Run this code + + #include + #include + #include + + template + class Generator + { + public: + struct promise_type + { + Generator get_return_object() + { + return Generator{Handle::from_promise(*this)}; + } + static std::suspend_always initial_suspend() noexcept + { + return {}; + } + static std::suspend_always final_suspend() noexcept + { + return {}; + } + std::suspend_always yield_value(T value) noexcept + { + current_value = std::move(value); + return {}; + } + // Disallow co_await in generator coroutines. + void await_transform() = delete; + [[noreturn]] + static void unhandled_exception() { throw; } + + std::optional current_value; + }; + + using Handle = std::coroutine_handle; + + explicit Generator(const Handle coroutine) : + m_coroutine{coroutine} + {} + + Generator() = default; + ~Generator() + { + if (m_coroutine) + m_coroutine.destroy(); + } + + Generator(const Generator&) = delete; + Generator& operator=(const Generator&) = delete; + + Generator(Generator&& other) noexcept : + m_coroutine{other.m_coroutine} + { + other.m_coroutine = {}; + } + Generator& operator=(Generator&& other) noexcept + { + if (this != &other) + { + if (m_coroutine) + m_coroutine.destroy(); + m_coroutine = other.m_coroutine; + other.m_coroutine = {}; + } + return *this; + } + + // Range-based for loop support. + class Iter + { + public: + void operator++() + { + m_coroutine.resume(); + } + const T& operator*() const + { + return *m_coroutine.promise().current_value; + } + bool operator==(std::default_sentinel_t) const + { + return !m_coroutine || m_coroutine.done(); + } + + explicit Iter(const Handle coroutine) : + m_coroutine{coroutine} + {} + + private: + Handle m_coroutine; + }; + + Iter begin() + { + if (m_coroutine) + m_coroutine.resume(); + return Iter{m_coroutine}; + } + + std::default_sentinel_t end() { return {}; } + + private: + Handle m_coroutine; + }; + + template + Generator range(T first, const T last) + { + while (first < last) + co_yield first++; + } + + int main() + { + for (const char i : range(65, 91)) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Output: + + A B C D E F G H I J K L M N O P Q R S T U V W X Y Z + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3460 C++20 the public base class of coroutine_handle inheritance removed + could leave it in an undesired state + +.SH See also + + generator A view that represents synchronous coroutine generator + (C++23) \fI(class template)\fP diff --git a/man/std::coroutine_handle::address.3 b/man/std::coroutine_handle::address.3 new file mode 100644 index 000000000..0a0ff3815 --- /dev/null +++ b/man/std::coroutine_handle::address.3 @@ -0,0 +1,29 @@ +.TH std::coroutine_handle::address 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::address \- std::coroutine_handle::address + +.SH Synopsis + constexpr void* address() const noexcept; \fI(since C++20)\fP + + Returns the underlying address of the coroutine_handle. The return value is non-null + if and only if the current value of the coroutine_handle is obtained from a promise + object of a coroutine. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying address. + +.SH Notes + + The return value is non-null for specialization std::noop_coroutine_handle, because + a std::noop_coroutine_handle cannot be created without referring to a no-op + coroutine. + +.SH See also + + from_address imports a coroutine from a pointer + \fB[static]\fP (C++20) \fI(public static member function)\fP diff --git a/man/std::coroutine_handle::coroutine_handle.3 b/man/std::coroutine_handle::coroutine_handle.3 new file mode 100644 index 000000000..431b89d99 --- /dev/null +++ b/man/std::coroutine_handle::coroutine_handle.3 @@ -0,0 +1,42 @@ +.TH std::coroutine_handle::coroutine_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::coroutine_handle \- std::coroutine_handle::coroutine_handle + +.SH Synopsis + constexpr coroutine_handle() noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr coroutine_handle( std::nullptr_t ) noexcept; \fB(2)\fP \fI(since C++20)\fP + coroutine_handle( const coroutine_handle& other ) = default; \fB(3)\fP \fI(since C++20)\fP + coroutine_handle( coroutine_handle&& other ) = default; \fB(4)\fP \fI(since C++20)\fP + + Creates a coroutine_handle that does not refer a coroutine, or copies a + coroutine_handle. + + 1,2) Initializes the underlying address ptr to nullptr. After construction, + address() returns nullptr, and the coroutine_handle does not refer a coroutine. + These constructors are not declared for the specialization + std::coroutine_handle. + 3,4) Copies the underlying address. The copy constructor and move constructor are + equivalent to implicitly declared ones. + +.SH Parameters + + other - another coroutine_handle to copy + +.SH Notes + + std::coroutine_handle is neither default constructible + nor constructible from std::nullptr_t. std::noop_coroutine can be used to create a + new std::coroutine_handle. + + Static member functions from_promise and from_address can also create a + coroutine_handle. + +.SH See also + + from_promise creates a coroutine_handle from the promise object of a coroutine + \fB[static]\fP (C++20) \fI(public static member function)\fP + from_address imports a coroutine from a pointer + \fB[static]\fP (C++20) \fI(public static member function)\fP + noop_coroutine creates a coroutine handle that has no observable effects when + (C++20) resumed or destroyed + \fI(function)\fP diff --git a/man/std::coroutine_handle::destroy.3 b/man/std::coroutine_handle::destroy.3 new file mode 100644 index 000000000..f432abe17 --- /dev/null +++ b/man/std::coroutine_handle::destroy.3 @@ -0,0 +1,41 @@ +.TH std::coroutine_handle::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::destroy \- std::coroutine_handle::destroy + +.SH Synopsis + Member of other specializations + void destroy() const; \fB(1)\fP (since + C++20) + Member of specialization + std::coroutine_handle + constexpr void destroy() const noexcept; \fB(2)\fP (since + C++20) + + 1) Destroys the coroutine state of the coroutine to which *this refers, or does + nothing if the coroutine is a no-op coroutine. + 2) Does nothing. + + The behavior is undefined if destroying is needed and *this does not refer to a + suspended coroutine. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator() resumes execution of the coroutine + resume \fI(public member function)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::coroutine_handle::done.3 b/man/std::coroutine_handle::done.3 new file mode 100644 index 000000000..1feb2267c --- /dev/null +++ b/man/std::coroutine_handle::done.3 @@ -0,0 +1,41 @@ +.TH std::coroutine_handle::done 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::done \- std::coroutine_handle::done + +.SH Synopsis + Member of other specializations + bool done() const; \fB(1)\fP (since + C++20) + Member of specialization + std::coroutine_handle + constexpr bool done() const noexcept; \fB(2)\fP (since + C++20) + + Checks if a suspended coroutine is suspended at its final suspended point. + + 1) Returns true if the coroutine to which *this refers is suspended at its final + suspend point, or false if the coroutine is suspended at other suspend points. The + behavior is undefined if *this does not refer to a suspended coroutine. + 2) Always returns false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) true if the coroutine is suspended at its final suspend point, false if the + coroutine is suspended at other suspend points. + 2) false + +.SH Notes + + A no-op coroutine is always considered not suspended at its final suspended point. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::coroutine_handle::from_address.3 b/man/std::coroutine_handle::from_address.3 new file mode 100644 index 000000000..1cc9350c6 --- /dev/null +++ b/man/std::coroutine_handle::from_address.3 @@ -0,0 +1,48 @@ +.TH std::coroutine_handle::from_address 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::from_address \- std::coroutine_handle::from_address + +.SH Synopsis + static constexpr coroutine_handle from_address( void *addr ); \fI(since C++20)\fP + + Creates a coroutine_handle from a null pointer value or an underlying address of + another coroutine_handle. The underlying address of return value is addr. + + The behavior is undefined if addr is neither a null pointer value nor an underlying + address of a coroutine_handle. The behavior is also undefined if the addr is an + underlying address of a std::coroutine_handle, where both Promise and P1 are not + void, and P1 is different from Promise. + + This function is not declared for specialization + std::coroutine_handle. + +.SH Parameters + + addr - underlying address to import + +.SH Return value + + A std::coroutine_handle whose underlying address is addr. + +.SH Notes + + If addr is not a null pointer value, it must be obtained from a prior call to + address() on a coroutine_handle referring to some coroutine. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a coroutine_handle object + (C++20) \fI(public member function)\fP + from_promise creates a coroutine_handle from the promise object of a coroutine + \fB[static]\fP (C++20) \fI(public static member function)\fP + noop_coroutine creates a coroutine handle that has no observable effects when + (C++20) resumed or destroyed + \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::coroutine_handle::from_promise.3 b/man/std::coroutine_handle::from_promise.3 new file mode 100644 index 000000000..3811bc80c --- /dev/null +++ b/man/std::coroutine_handle::from_promise.3 @@ -0,0 +1,40 @@ +.TH std::coroutine_handle::from_promise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::from_promise \- std::coroutine_handle::from_promise + +.SH Synopsis + static coroutine_handle from_promise( Promise& p ); \fI(since C++20)\fP + + Creates a coroutine_handle from the promise object of a coroutine. The created + coroutine_handle refers the coroutine, and promise() returns a reference to p. + + The behavior is undefined if p is not a reference to a promise object. This function + is only provided for the primary template, i.e. specializations + std::coroutine_handle<> and std::coroutine_handle do + not have this function. + +.SH Parameters + + p - promise object of a coroutine to refer + +.SH Return value + + A coroutine_handle referring the given coroutine. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a coroutine_handle object + (C++20) \fI(public member function)\fP + from_address imports a coroutine from a pointer + \fB[static]\fP (C++20) \fI(public static member function)\fP + noop_coroutine creates a coroutine handle that has no observable effects when + (C++20) resumed or destroyed + \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::coroutine_handle::operator(),std::coroutine_handle::resume.3 b/man/std::coroutine_handle::operator(),std::coroutine_handle::resume.3 new file mode 100644 index 000000000..1a92a8395 --- /dev/null +++ b/man/std::coroutine_handle::operator(),std::coroutine_handle::resume.3 @@ -0,0 +1,59 @@ +.TH std::coroutine_handle::operator(),std::coroutine_handle::resume 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::operator(),std::coroutine_handle::resume \- std::coroutine_handle::operator(),std::coroutine_handle::resume + +.SH Synopsis + Member of other specializations + void operator()() const; \fB(1)\fP (since + void resume() const; C++20) + Member of specialization + std::coroutine_handle + constexpr void operator()() const noexcept; \fB(2)\fP (since + constexpr void resume() const noexcept; C++20) + + 1) Resumes the execution of the coroutine to which *this refers, or does nothing if + the coroutine is a no-op coroutine. + 2) Does nothing. + + The behavior is undefined if *this does not refer to suspended coroutine, or the + coroutine is not a no-op coroutine and suspended at its final suspend point. A + concurrent resumption of the coroutine may result in a data race. + + Resumption of a coroutine on an execution agent other than the one on which it was + suspended has implementation-defined behavior unless each execution agent either is + a thread represented by std::thread or std::jthread, or is the thread executing + main. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + If an exception is thrown from the execution of the coroutine, the exception is + caught and unhandled_exception is called on the coroutine's promise object. If the + call to unhandled_exception throws or rethrows an exception, that exception is + propagated. + +.SH Notes + + A coroutine that is resumed on a different execution agent should avoid relying on + consistent thread identity throughout, such as holding a mutex object across a + suspend point. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + destroy destroys a coroutine + (C++20) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::coroutine_handle::operator=.3 b/man/std::coroutine_handle::operator=.3 new file mode 100644 index 000000000..7855d0713 --- /dev/null +++ b/man/std::coroutine_handle::operator=.3 @@ -0,0 +1,25 @@ +.TH std::coroutine_handle::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::operator= \- std::coroutine_handle::operator= + +.SH Synopsis + coroutine_handle& operator=( std::nullptr_t ) noexcept; \fB(1)\fP \fI(since C++20)\fP + coroutine_handle& operator=( const coroutine_handle& other ) = \fB(2)\fP \fI(since C++20)\fP + default; + coroutine_handle& operator=( coroutine_handle&& other ) = default; \fB(3)\fP \fI(since C++20)\fP + + Replaces the underlying address. + + 1) Replaces the underlying address with a null pointer value. After assignment, + *this does not refer to a coroutine. This assignment operator is not declared for + specialization std::coroutine_handle. + 2,3) Replaces the underlying address with the one of other. Copy and move assignment + operators are equivalent to implicitly declared ones. + +.SH Parameters + + other - another coroutine_handle to assign from + +.SH Return value + + *this diff --git a/man/std::coroutine_handle::operatorbool.3 b/man/std::coroutine_handle::operatorbool.3 new file mode 100644 index 000000000..d76ddc114 --- /dev/null +++ b/man/std::coroutine_handle::operatorbool.3 @@ -0,0 +1,25 @@ +.TH std::coroutine_handle::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::operatorbool \- std::coroutine_handle::operatorbool + +.SH Synopsis + constexpr explicit operator bool() const noexcept; \fI(since C++20)\fP + + Checks whether *this is non-null, i.e. the value of *this is obtained from the + promise object of some coroutine. Equivalent to return bool(address());. + + If Promise is std::noop_coroutine_promise, this conversion function always returns + true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + bool(address()), or true if Promise is std::noop_coroutine_promise. + +.SH See also + + address exports the underlying address, i.e. the pointer backing the coroutine + (C++20) \fI(public member function)\fP diff --git a/man/std::coroutine_handle::operatorcoroutine_handle.3 b/man/std::coroutine_handle::operatorcoroutine_handle.3 new file mode 100644 index 000000000..ecabb81f8 --- /dev/null +++ b/man/std::coroutine_handle::operatorcoroutine_handle.3 @@ -0,0 +1,24 @@ +.TH std::coroutine_handle::operatorcoroutine_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::operatorcoroutine_handle \- std::coroutine_handle::operatorcoroutine_handle + +.SH Synopsis + constexpr operator coroutine_handle<>() const noexcept; \fI(since C++20)\fP + + This conversion function converts a std::coroutine_handle value to a + std::coroutine_handle<> holding the same underlying address. It effectively erases + the promise type. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + std::coroutine_handle<>::from_address(address()) + +.SH See also + + operator== compares two coroutine_handle objects + operator<=> \fI(function)\fP + (C++20) diff --git a/man/std::coroutine_handle::promise.3 b/man/std::coroutine_handle::promise.3 new file mode 100644 index 000000000..db95c8ebb --- /dev/null +++ b/man/std::coroutine_handle::promise.3 @@ -0,0 +1,35 @@ +.TH std::coroutine_handle::promise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_handle::promise \- std::coroutine_handle::promise + +.SH Synopsis + Member of the primary template + Promise& promise() const; \fI(since C++20)\fP + Member of specialization + std::coroutine_handle + std::noop_coroutine_promise& promise() const noexcept; \fI(since C++20)\fP + + Obtains a reference to the promise object. + + The behavior is undefined if *this does not refer to a coroutine whose promise + object has not been destroyed. + + This function is not provided for the specialization std::coroutine_handle<>. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the promise object. + +.SH Notes + + The promise object of a no-op coroutine is not destroyed as long as there is some + std::noop_coroutine_handle referring to the coroutine. + +.SH See also + + from_promise creates a coroutine_handle from the promise object of a coroutine + \fB[static]\fP (C++20) \fI(public static member function)\fP diff --git a/man/std::coroutine_traits.3 b/man/std::coroutine_traits.3 new file mode 100644 index 000000000..966e9bbfa --- /dev/null +++ b/man/std::coroutine_traits.3 @@ -0,0 +1,195 @@ +.TH std::coroutine_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::coroutine_traits \- std::coroutine_traits + +.SH Synopsis + Defined in header + template< class R, class... Args > \fI(since C++20)\fP + struct coroutine_traits; + + Determines the promise type from the return type and parameter types of a coroutine. + The standard library implementation provides a publicly accessible member type + promise_type same as R::promise_type if the qualified-id is valid and denotes a + type. Otherwise, it has no such member. + + Program-defined specializations of coroutine_traits must define a publicly + accessible nested type promise_type, otherwise the program is ill-formed. + +.SH Template parameters + + R - return type of the coroutine + Args - parameter types of the coroutine, including the implicit object parameter if + the coroutine is a non-static member function + + Nested types + + Name Definition + promise_type R::promise_type if it is valid, or provided by program-defined + specializations + +.SH Possible implementation + + namespace detail { + template + struct coroutine_traits_base {}; + + template + requires requires { typename R::promise_type; } + struct coroutine_traits_base + { + using promise_type = R::promise_type; + }; + } + + template + struct coroutine_traits : detail::coroutine_traits_base {}; + +.SH Notes + + If the coroutine is a non-static member function, then the first type in Args... is + the type of the implicit object parameter, and the rest are parameter types of the + function (if any). + + If std::coroutine_traits::promise_type does not exist or is not a class + type, the corresponding coroutine definition is ill-formed. + + Users may define explicit or partial specializations of coroutine_traits dependent + on program-defined types to avoid modification to return types. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + // A program-defined type on which the coroutine_traits specializations below depend + struct as_coroutine {}; + + // Enable the use of std::future as a coroutine type + // by using a std::promise as the promise type. + template + requires(!std::is_void_v && !std::is_reference_v) + struct std::coroutine_traits, as_coroutine, Args...> + { + struct promise_type : std::promise + { + std::future get_return_object() noexcept + { + return this->get_future(); + } + + std::suspend_never initial_suspend() const noexcept { return {}; } + std::suspend_never final_suspend() const noexcept { return {}; } + + void return_value(const T& value) + noexcept(std::is_nothrow_copy_constructible_v) + { + this->set_value(value); + } + + void return_value(T&& value) noexcept(std::is_nothrow_move_constructible_v) + { + this->set_value(std::move(value)); + } + + void unhandled_exception() noexcept + { + this->set_exception(std::current_exception()); + } + }; + }; + + // Same for std::future. + template + struct std::coroutine_traits, as_coroutine, Args...> + { + struct promise_type : std::promise + { + std::future get_return_object() noexcept + { + return this->get_future(); + } + + std::suspend_never initial_suspend() const noexcept { return {}; } + std::suspend_never final_suspend() const noexcept { return {}; } + + void return_void() noexcept + { + this->set_value(); + } + + void unhandled_exception() noexcept + { + this->set_exception(std::current_exception()); + } + }; + }; + + // Allow co_await'ing std::future and std::future + // by naively spawning a new thread for each co_await. + template + auto operator co_await(std::future future) noexcept + requires(!std::is_reference_v) + { + struct awaiter : std::future + { + bool await_ready() const noexcept + { + using namespace std::chrono_literals; + return this->wait_for(0s) != std::future_status::timeout; + } + + void await_suspend(std::coroutine_handle<> cont) const + { + std::thread([this, cont] + { + this->wait(); + cont(); + }).detach(); + } + + T await_resume() { return this->get(); } + }; + + return awaiter { std::move(future) }; + } + + // Utilize the infrastructure we have established. + std::future compute(as_coroutine) + { + int a = co_await std::async([] { return 6; }); + int b = co_await std::async([] { return 7; }); + co_return a * b; + } + + std::future fail(as_coroutine) + { + throw std::runtime_error("bleah"); + co_return; + } + + int main() + { + std::cout << compute({}).get() << '\\n'; + + try + { + fail({}).get(); + } + catch (const std::runtime_error& e) + { + std::cout << "error: " << e.what() << '\\n'; + } + } + +.SH Output: + + 42 + error: bleah diff --git a/man/std::cos(std::complex).3 b/man/std::cos(std::complex).3 index 148da01ec..489ad7ab5 100644 --- a/man/std::cos(std::complex).3 +++ b/man/std::cos(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::cos(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cos(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cos(std::complex) \- std::cos(std::complex) + .SH Synopsis Defined in header template< class T > @@ -12,11 +15,64 @@ .SH Return value - Complex cosine of z. + If no errors occur, the complex cosine of z is returned. + + Errors and special cases are handled as if the operation is implemented by + std::cosh(i * z), where i is the imaginary unit. + +.SH Notes + + The cosine is an entire function on the complex plane, and has no branch cuts. + + Mathematical definition of the cosine is cos z = + + eiz + +e-iz + 2 + + . + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z(1.0, 0.0); // behaves like real cosine along the real line + std::cout << "cos" << z << " = " << std::cos(z) + << " ( cos(1) = " << std::cos(1) << ")\\n"; + + std::complex z2(0.0, 1.0); // behaves like real cosh along the imaginary line + std::cout << "cos" << z2 << " = " << std::cos(z2) + << " (cosh(1) = " << std::cosh(1) << ")\\n"; + } + +.SH Output: + + cos(1.000000,0.000000) = (0.540302,-0.000000) ( cos\fB(1)\fP = 0.540302) + cos(0.000000,1.000000) = (1.543081,-0.000000) (cosh\fB(1)\fP = 1.543081) .SH See also - sin(std::complex) computes sine of a complex number (sin(z)) - \fI(function template)\fP - tan(std::complex) computes tangent of a complex number (tan(z)) - \fI(function template)\fP + sin(std::complex) computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z)) + \fI(function template)\fP + tan(std::complex) computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z)) + \fI(function template)\fP + acos(std::complex) computes arc cosine of a complex number + \fI(C++11)\fP (\\({\\small\\arccos{z}}\\)arccos(z)) + \fI(function template)\fP + cos + cosf computes cosine (\\({\\small\\cos{x}}\\)cos(x)) + cosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cos(std::valarray) applies the function std::cos to each element of valarray + \fI(function template)\fP + C documentation for + ccos diff --git a/man/std::cos(std::valarray).3 b/man/std::cos(std::valarray).3 index 2a3c58360..df4acaea9 100644 --- a/man/std::cos(std::valarray).3 +++ b/man/std::cos(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::cos(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cos(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cos(std::valarray) \- std::cos(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (cos) is used to perform the computation. If such function is - not available, std::cos is used due to argument dependent lookup. + not available, std::cos is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,16 +43,66 @@ valarray cos(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = cos(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + #include + + void show(const char* title, const std::valarray& data) + { + const int w{9}; + std::cout << std::setw(w) << title << " | "; + for (float x : data) + std::cout << std::setw(w) << x << " | "; + std::cout << '\\n'; + } + + int main() + { + const std::valarray x{.1, .2, .3, .4}; + const auto sin = std::sin(x); + const auto cos = std::cos(x); + const auto z = (sin * sin) + (cos * cos); + + show("x", x); + show("sin(x)", sin); + show("cos(x)", cos); + show("z", z); + } + +.SH Output: + + x | 0.1 | 0.2 | 0.3 | 0.4 | + sin(x) | 0.0998334 | 0.198669 | 0.29552 | 0.389418 | + cos(x) | 0.995004 | 0.980067 | 0.955337 | 0.921061 | + z | 1 | 1 | 1 | 1 | + +.SH See also + + sin(std::valarray) applies the function std::sin to each element of valarray + \fI(function template)\fP + tan(std::valarray) applies the function std::tan to each element of valarray + \fI(function template)\fP + acos(std::valarray) applies the function std::acos to each element of valarray + \fI(function template)\fP + cos + cosf computes cosine (\\({\\small\\cos{x}}\\)cos(x)) + cosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cos(std::complex) computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z)) + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::cos,std::cosf,std::cosl.3 b/man/std::cos,std::cosf,std::cosl.3 new file mode 100644 index 000000000..8b9655eb9 --- /dev/null +++ b/man/std::cos,std::cosf,std::cosl.3 @@ -0,0 +1,152 @@ +.TH std::cos,std::cosf,std::cosl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cos,std::cosf,std::cosl \- std::cos,std::cosf,std::cosl + +.SH Synopsis + Defined in header + float cos ( float num ); + + double cos ( double num ); (until C++23) + + long double cos ( long double num ); + /* floating-point-type */ (since C++23) + cos ( /* floating-point-type */ num ); (constexpr since C++26) + float cosf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double cosl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double cos ( Integer num ); + + 1-3) Computes the cosine of num (measured in radians). + The library provides overloads of std::cos for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value representing angle in radians + +.SH Return value + + If no errors occur, the cosine of num (cos(num)) in the range [-1.0, +1.0], is + returned. + + The result may have little or no significance if the magnitude of num \fI(until C++11)\fP + is large. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0, the result is 1.0. + * if the argument is ±∞, NaN is returned and FE_INVALID is raised. + * if the argument is NaN, NaN is returned. + +.SH Notes + + The case where the argument is infinite is not specified to be a domain error in C, + but it is defined as a domain error in POSIX. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::cos(num) has the same effect as std::cos(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + constexpr double pi = std::numbers::pi; // or std::acos(-1) before C++20 + + constexpr double your_cos(double x) + { + double cos{1}, pow{x}; + for (auto fac{1ull}, n{1ull}; n != 19; fac *= ++n, pow *= x) + if ((n & 1) == 0) + cos += (n & 2 ? -pow : pow) / fac; + return cos; + } + + int main() + { + std::cout << std::setprecision(10) << std::showpos + << "Typical usage:\\n" + << "std::cos(pi/3) = " << std::cos(pi / 3) << '\\n' + << "your cos(pi/3) = " << your_cos(pi / 3) << '\\n' + << "std::cos(pi/2) = " << std::cos(pi / 2) << '\\n' + << "your cos(pi/2) = " << your_cos(pi / 2) << '\\n' + << "std::cos(-3*pi/4) = " << std::cos(-3 * pi / 4) << '\\n' + << "your cos(-3*pi/4) = " << your_cos(-3 * pi / 4) << '\\n' + << "Special values:\\n" + << "std::cos(+0) = " << std::cos(0.0) << '\\n' + << "std::cos(-0) = " << std::cos(-0.0) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "cos(INFINITY) = " << std::cos(INFINITY) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + Typical usage: + std::cos(pi/3) = +0.5 + your cos(pi/3) = +0.5 + std::cos(pi/2) = +6.123233996e-17 + your cos(pi/2) = -3.373452105e-15 + std::cos(-3*pi/4) = -0.7071067812 + your cos(-3*pi/4) = -0.7071067812 + Special values: + std::cos(+0) = +1 + std::cos(-0) = +1 + cos(INFINITY) = -nan + FE_INVALID raised + +.SH See also + + sin + sinf computes sine (\\({\\small\\sin{x}}\\)sin(x)) + sinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tan + tanf computes tangent (\\({\\small\\tan{x}}\\)tan(x)) + tanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acos + acosf computes arc cosine (\\({\\small\\arccos{x}}\\)arccos(x)) + acosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cos(std::complex) computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z)) + \fI(function template)\fP + cos(std::valarray) applies the function std::cos to each element of valarray + \fI(function template)\fP + C documentation for + cos diff --git a/man/std::cos.3 b/man/std::cos.3 deleted file mode 100644 index 6c6fcdfaf..000000000 --- a/man/std::cos.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::cos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float cos( float arg ); - double cos( double arg ); - long double cos( long double arg ); - double cos( Integral arg ); \fI(since C++11)\fP - - Computes cosine of arg. - -.SH Parameters - - arg - value representing angle in radians, of a floating-point or Integral type - -.SH Return value - - Cosine of arg in the range [-1.0 ; 1.0]. - - Domain error occurs if arg is infinite. NAN is returned in that case. - -.SH See also - - sin computes sine (sin(x)) - \fI(function)\fP - tan computes tangent (tan(x)) - \fI(function)\fP - acos computes arc cosine (arccos(x)) - \fI(function)\fP - cos(std::complex) computes cosine of a complex number (cos(z)) - \fI(function template)\fP - cos(std::valarray) applies the function std::cos to each element of valarray - \fI(function template)\fP - C documentation for - cos diff --git a/man/std::cosh(std::complex).3 b/man/std::cosh(std::complex).3 index c1d07cb7b..8203b55d5 100644 --- a/man/std::cosh(std::complex).3 +++ b/man/std::cosh(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::cosh(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cosh(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cosh(std::complex) \- std::cosh(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -12,11 +15,94 @@ .SH Return value - Complex hyperbolic cosine of z + If no errors occur, complex hyperbolic cosine of z is returned. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::cosh(std::conj(z)) == std::conj(std::cosh(z)) + * std::cosh(z) == std::cosh(-z) + * If z is (+0,+0), the result is (1,+0) + * If z is (+0,+∞), the result is (NaN,±0) (the sign of the imaginary part is + unspecified) and FE_INVALID is raised + * If z is (+0,NaN), the result is (NaN,±0) (the sign of the imaginary part is + unspecified) + * If z is (x,+∞) (for any finite non-zero x), the result is (NaN,NaN) and + FE_INVALID is raised + * If z is (x,NaN) (for any finite non-zero x), the result is (NaN,NaN) and + FE_INVALID may be raised + * If z is (+∞,+0), the result is (+∞,+0) + * If z is (+∞,y) (for any finite non-zero y), the result is +∞cis(y) + * If z is (+∞,+∞), the result is (±∞,NaN) (the sign of the real part is + unspecified) and FE_INVALID is raised + * If z is (+∞,NaN), the result is (+∞,NaN) + * If z is (NaN,+0), the result is (NaN,±0) (the sign of the imaginary part is + unspecified) + * If z is (NaN,+y) (for any finite non-zero y), the result is (NaN,NaN) and + FE_INVALID may be raised + * If z is (NaN,NaN), the result is (NaN,NaN) + + where cis(y) is cos(y) + i sin(y). + +.SH Notes + + Mathematical definition of hyperbolic cosine is cosh z = + + ez + +e-z + 2 + + . + + Hyperbolic cosine is an entire function in the complex plane and has no branch cuts. + It is periodic with respect to the imaginary component, with period 2πi. + +.SH Examples + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z(1.0, 0.0); // behaves like real cosh along the real line + std::cout << "cosh" << z << " = " << std::cosh(z) + << " (cosh(1) = " << std::cosh(1) << ")\\n"; + + std::complex z2(0.0, 1.0); // behaves like real cosine along the imaginary line + std::cout << "cosh" << z2 << " = " << std::cosh(z2) + << " ( cos(1) = " << std::cos(1) << ")\\n"; + } + +.SH Output: + + cosh(1.000000,0.000000) = (1.543081,0.000000) (cosh\fB(1)\fP = 1.543081) + cosh(0.000000,1.000000) = (0.540302,0.000000) ( cos\fB(1)\fP = 0.540302) .SH See also - cos(std::complex) computes cosine of a complex number (cos(z)) - \fI(function template)\fP - acos(std::complex) computes arc cosine of a complex number (arccos(z)) - \fI(C++11)\fP \fI(function template)\fP + computes hyperbolic sine of a complex number + sinh(std::complex) (\\({\\small\\sinh{z}}\\)sinh(z)) + \fI(function template)\fP + computes hyperbolic tangent of a complex number + tanh(std::complex) (\\({\\small\\tanh{z}}\\)tanh(z)) + \fI(function template)\fP + acosh(std::complex) computes area hyperbolic cosine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arcosh}{z}}\\)arcosh(z)) + \fI(function template)\fP + cosh + coshf computes hyperbolic cosine (\\({\\small\\cosh{x}}\\)cosh(x)) + coshl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cosh(std::valarray) applies the function std::cosh to each element of valarray + \fI(function template)\fP + C documentation for + ccosh diff --git a/man/std::cosh(std::valarray).3 b/man/std::cosh(std::valarray).3 index 7d1034d58..0422840dd 100644 --- a/man/std::cosh(std::valarray).3 +++ b/man/std::cosh(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::cosh(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cosh(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cosh(std::valarray) \- std::cosh(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (cosh) is used to perform the computation. If such function is - not available, std::cosh is used due to argument dependent lookup. + not available, std::cosh is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,21 +43,65 @@ valarray cosh(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = cosh(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include + + void show(const char* title, const std::valarray& data) + { + const int w{9}; + std::cout << std::setw(w) << title << " | "; + for (float x : data) + std::cout << std::setw(w) << x << " | "; + std::cout << '\\n'; + } - cosh computes hyperbolic cosine (ch(x)) - \fI(function)\fP + int main() + { + const std::valarray x{.1, .2, .3, .4}; + const auto sinh = std::sinh(x); + const auto cosh = std::cosh(x); + const auto z = (cosh * cosh) - (sinh * sinh); -.SH Category: + show("x", x); + show("sinh(x)", sinh); + show("cosh(x)", cosh); + show("z", z); + } + +.SH Output: + + x | 0.1 | 0.2 | 0.3 | 0.4 | + sinh(x) | 0.100167 | 0.201336 | 0.30452 | 0.410752 | + cosh(x) | 1.005 | 1.02007 | 1.04534 | 1.08107 | + z | 1 | 1 | 1 | 1 | + +.SH See also - * Todo no example + sinh(std::valarray) applies the function std::sinh to each element of valarray + \fI(function template)\fP + tanh(std::valarray) applies the function std::tanh to each element of valarray + \fI(function template)\fP + cosh + coshf computes hyperbolic cosine (\\({\\small\\cosh{x}}\\)cosh(x)) + coshl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes hyperbolic cosine of a complex number + cosh(std::complex) (\\({\\small\\cosh{z}}\\)cosh(z)) + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::cosh,std::coshf,std::coshl.3 b/man/std::cosh,std::coshf,std::coshl.3 new file mode 100644 index 000000000..b83226a2a --- /dev/null +++ b/man/std::cosh,std::coshf,std::coshl.3 @@ -0,0 +1,139 @@ +.TH std::cosh,std::coshf,std::coshl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cosh,std::coshf,std::coshl \- std::cosh,std::coshf,std::coshl + +.SH Synopsis + Defined in header + float cosh ( float num ); + + double cosh ( double num ); (until C++23) + + long double cosh ( long double num ); + /* floating-point-type */ (since C++23) + cosh ( /* floating-point-type */ num ); (constexpr since C++26) + float coshf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double coshl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double cosh ( Integer num ); + + 1-3) Computes the hyperbolic cosine of num. + The library provides overloads of std::cosh for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the hyperbolic cosine of num (cosh(num), or + + enum + +e-num + 2 + + ) is returned. + + If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0, 1 is returned. + * If the argument is ±∞, +∞ is returned. + * if the argument is NaN, NaN is returned. + +.SH Notes + + For the IEEE-compatible type double, if |num| > 710.5, then std::cosh(num) + overflows. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::cosh(num) has the same effect as std::cosh(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + const double x = 42; + + std::cout << "cosh(1) = " << std::cosh(1) << '\\n' + << "cosh(-1) = " << std::cosh(-1) << '\\n' + << "log(sinh(" << x << ")+cosh(" << x << ")) = " + << std::log(std::sinh(x) + std::cosh(x)) << '\\n'; + + // special values + std::cout << "cosh(+0) = " << std::cosh(0.0) << '\\n' + << "cosh(-0) = " << std::cosh(-0.0) << '\\n'; + + // error handling + errno=0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "cosh(710.5) = " << std::cosh(710.5) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Possible output: + + cosh\fB(1)\fP = 1.54308 + cosh(-1) = 1.54308 + log(sinh\fB(42)\fP+cosh(42)) = 42 + cosh(+0) = 1 + cosh(-0) = 1 + cosh(710.5) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + sinh + sinhf computes hyperbolic sine (\\({\\small\\sinh{x}}\\)sinh(x)) + sinhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tanh + tanhf computes hyperbolic tangent (\\({\\small\\tanh{x}}\\)tanh(x)) + tanhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + acosh + acoshf computes the inverse hyperbolic cosine + acoshl (\\({\\small\\operatorname{arcosh}{x}}\\)arcosh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes hyperbolic cosine of a complex number + cosh(std::complex) (\\({\\small\\cosh{z}}\\)cosh(z)) + \fI(function template)\fP + cosh(std::valarray) applies the function std::cosh to each element of valarray + \fI(function template)\fP + C documentation for + cosh diff --git a/man/std::cosh.3 b/man/std::cosh.3 deleted file mode 100644 index e377bd863..000000000 --- a/man/std::cosh.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::cosh 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float cosh( float arg ); - double cosh( double arg ); - long double cosh( long double arg ); - double cosh( Integral arg ); \fI(since C++11)\fP - - Computes hyperbolic cosine of arg - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Hyperbolic cosine of arg. - -.SH See also - - sinh computes hyperbolic sine (sh(x)) - \fI(function)\fP - tanh hyperbolic tangent - \fI(function)\fP - acosh area hyperbolic cosine - \fI(C++11)\fP \fI(function)\fP - cosh(std::complex) computes hyperbolic cosine of a complex number (ch(z)) - \fI(function template)\fP - cosh(std::valarray) applies the function std::cosh to each element of valarray - \fI(function template)\fP - C documentation for - cosh diff --git a/man/std::count,std::count_if.3 b/man/std::count,std::count_if.3 index 4c4f72c14..b1b2e15c4 100644 --- a/man/std::count,std::count_if.3 +++ b/man/std::count,std::count_if.3 @@ -1,127 +1,231 @@ -.TH std::count,std::count_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::count,std::count_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::count,std::count_if \- std::count,std::count_if + .SH Synopsis Defined in header template< class InputIt, class T > + (constexpr + typename since C++20) + std::iterator_traits::difference_type (until + C++26) + count( InputIt first, InputIt last, const T& + value ); + template< class InputIt, class T = typename + std::iterator_traits + + + ::value_type > (since + constexpr typename C++26) + std::iterator_traits::difference_type + + count( InputIt first, InputIt last, const T& + value ); + template< class ExecutionPolicy, class ForwardIt, + class T > + (since + typename C++17) + std::iterator_traits::difference_type (until + count( ExecutionPolicy&& policy, C++26) + + ForwardIt first, ForwardIt last, const T& + value ); + template< class ExecutionPolicy, \fB(1)\fP + + class ForwardIt, class T = typename + std::iterator_traits + + ::value_type > (since + typename C++26) + std::iterator_traits::difference_type + count( ExecutionPolicy&& policy, + \fB(2)\fP + ForwardIt first, ForwardIt last, const T& + value ); + template< class InputIt, class UnaryPred > + + typename (constexpr + std::iterator_traits::difference_type \fB(3)\fP since + C++20) + count_if( InputIt first, InputIt last, UnaryPred + p ); + template< class ExecutionPolicy, class ForwardIt, + class UnaryPred > + + typename (since + std::iterator_traits::difference_type \fB(4)\fP C++17) + count_if( ExecutionPolicy&& policy, + + ForwardIt first, ForwardIt last, + UnaryPred p ); - typename iterator_traits::difference_type \fB(1)\fP - - count( InputIt first, InputIt last, const T &value ); - template< class InputIt, class UnaryPredicate > + Returns the number of elements in the range [first, last) satisfying specific + criteria. - typename iterator_traits::difference_type \fB(2)\fP + 1) Counts the elements that are equal to value (using operator==). + 3) Counts elements for which predicate p returns true. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if - count_if( InputIt first, InputIt last, UnaryPredicate p ); - - Returns the number of elements in the range [first, last) satisfying specific - criteria. The first version counts the elements that are equal to value, the second - version counts elements for which predicate p returns true. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine value - the value to search for + policy - the execution policy to use. See execution policy for details. unary predicate which returns true for the required elements. - The signature of the predicate function should be equivalent to the - following: - - p - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + UnaryPred must meet the requirements of Predicate. .SH Return value - number of elements satisfying the condition. + The number of iterators it in the range [first, last) satisfying the following + condition: + + 1,2) *it == value is true. + 3,4) p(*it) != false is true. .SH Complexity - exactly last - first comparisons / applications of the predicate + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize N\\)N comparisons with value using operator==. + 3,4) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + For the number of elements in the range [first, last) without any additional + criteria, see std::distance. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) .SH Possible implementation -.SH First version - template - typename iterator_traits::difference_type + See also the implementations of count in libstdc++ and libc++. + + See also the implementations of count_if in libstdc++ and libc++. + + count + template::value_type> + typename std::iterator_traits::difference_type count(InputIt first, InputIt last, const T& value) { - typename iterator_traits::difference_type ret = 0; - for (; first != last; ++first) { - if (*first == value) { - ret++; - } - } + typename std::iterator_traits::difference_type ret = 0; + for (; first != last; ++first) + if (*first == value) + ++ret; return ret; } -.SH Second version - template - typename iterator_traits::difference_type - count_if(InputIt first, InputIt last, UnaryPredicate p) + count_if + template + typename std::iterator_traits::difference_type + count_if(InputIt first, InputIt last, UnaryPred p) { - typename iterator_traits::difference_type ret = 0; - for (; first != last; ++first) { - if (p(*first)) { - ret++; - } - } + typename std::iterator_traits::difference_type ret = 0; + for (; first != last; ++first) + if (p(*first)) + ++ret; return ret; } .SH Example - The following code uses count to determine how many integers in a std::vector match - a target value. - // Run this code #include + #include + #include + #include #include - #include - + #include + int main() { - int data[] = { 1, 2, 3, 4, 4, 3, 7, 8, 9, 10 }; - std::vector v(data, data+10); - - int target1 = 3; - int target2 = 5; - int num_items1 = std::count(v.begin(), v.end(), target1); - int num_items2 = std::count(v.begin(), v.end(), target2); - - std::cout << "number: " << target1 << " count: " << num_items1 << '\\n'; - std::cout << "number: " << target2 << " count: " << num_items2 << '\\n'; + constexpr std::array v{1, 2, 3, 4, 4, 3, 7, 8, 9, 10}; + std::cout << "v: "; + std::copy(v.cbegin(), v.cend(), std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + + // Determine how many integers match a target value. + for (const int target : {3, 4, 5}) + { + const int num_items = std::count(v.cbegin(), v.cend(), target); + std::cout << "number: " << target << ", count: " << num_items << '\\n'; + } + + // Use a lambda expression to count elements divisible by 4. + int count_div4 = std::count_if(v.begin(), v.end(), [](int i) { return i % 4 == 0; }); + std::cout << "numbers divisible by four: " << count_div4 << '\\n'; + + // A simplified version of `distance` with O(N) complexity: + auto distance = [](auto first, auto last) + { + return std::count_if(first, last, [](auto) { return true; }); + }; + static_assert(distance(v.begin(), v.end()) == 10); + + std::array, 3> nums{{{4, 2}, {1, 3}, {4, 2}}}; + #ifdef __cpp_lib_algorithm_default_value_type + // T gets deduced making list-initialization possible + auto c = std::count(nums.cbegin(), nums.cend(), {4, 2}); + #else + auto c = std::count(nums.cbegin(), nums.cend(), std::complex{4, 2}); + #endif + assert(c == 2); } .SH Output: - number: 3 count: 2 - number: 5 count: 0 + v: 1 2 3 4 4 3 7 8 9 10 + number: 3, count: 2 + number: 4, count: 2 + number: 5, count: 0 + numbers divisible by four: 3 - This example uses a lambda expression to count elements divisible by 3. + Defect reports - -// Run this code + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - #include - #include - #include - - int main() - { - int data[] = { 1, 2, 3, 4, 4, 3, 7, 8, 9, 10 }; - std::vector v(data, data+10); - - int num_items1 = std::count_if(v.begin(), v.end(), [](int i) {return i % 3 == 0;}); - - std::cout << "number divisible by three: " << num_items1 << '\\n'; - } + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, + LWG 283 C++98 but removed the requirement + the value type of InputIt is not always T -.SH Output: +.SH See also - number divisible by three: 3 + distance returns the distance between two iterators + \fI(function template)\fP + ranges::count + ranges::count_if returns the number of elements satisfying specific criteria + (C++20) (niebloid) + (C++20) diff --git a/man/std::counted_iterator.3 b/man/std::counted_iterator.3 new file mode 100644 index 000000000..d1cf02a3b --- /dev/null +++ b/man/std::counted_iterator.3 @@ -0,0 +1,147 @@ +.TH std::counted_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator \- std::counted_iterator + +.SH Synopsis + Defined in header + template< std::input_or_output_iterator I > \fI(since C++20)\fP + class counted_iterator; + + std::counted_iterator is an iterator adaptor which behaves exactly like the + underlying iterator, except that it keeps track of the distance to the end of its + range. This iterator is equal to std::default_sentinel if and only if its count + reaches zero. + +.SH Member types + + Member type Definition + iterator_type I + value_type std::iter_value_t if I models indirectly_readable; otherwise, + not defined + difference_type std::iter_difference_t + iterator_concept I::iterator_concept if present; otherwise, not defined + iterator_category I::iterator_category if present; otherwise, not defined + +.SH Member objects + + Member name Definition + current (private) the underlying iterator which base() accesses + (exposition-only member object*) + the distance between the underlying iterator and the end of its + length (private) range + (exposition-only member object*) + +.SH Member functions + + constructor constructs a new iterator adaptor + (C++20) \fI(public member function)\fP + operator= assigns another iterator adaptor + (C++20) \fI(public member function)\fP + base accesses the underlying iterator + (C++20) \fI(public member function)\fP + count returns the distance to the end + (C++20) \fI(public member function)\fP + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + (C++20) + operator[] accesses an element by index + (C++20) \fI(public member function)\fP + operator++ + operator++(int) + operator+= + operator+ advances or decrements the iterator + operator-- \fI(public member function)\fP + operator--(int) + operator-= + operator- + (C++20) + +.SH Non-member functions + + operator== compares the distances to the end + operator<=> \fI(function template)\fP + (C++20) + operator==(std::default_sentinel) checks if the distance to the end is equal to 0 + (C++20) \fI(function template)\fP + operator+ advances the iterator + (C++20) \fI(function template)\fP + operator- computes the distance between two iterator + (C++20) adaptors + \fI(function template)\fP + operator-(std::default_sentinel_t) computes the signed distance to the end + (C++20) \fI(function template)\fP + iter_move casts the result of dereferencing the underlying + (C++20) iterator to its associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying + (C++20) iterators + \fI(function template)\fP + +.SH Helper classes + + provides uniform interface to the + std::iterator_traits properties of the std::counted_iterator + (C++20) type + \fI(class template specialization)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using std::operator""s; + + void print(auto const remark, auto const& v) + { + const auto size = std::ssize(v); + std::cout << remark << '[' << size << "] { "; + for (auto it = std::counted_iterator{std::cbegin(v), size}; + it != std::default_sentinel; ++it) + std::cout << *it << (it.count() > 1 ? ", " : " "); + std::cout << "}\\n"; + } + + int main() + { + const auto src = {"Arcturus"s, "Betelgeuse"s, "Canopus"s, "Deneb"s, "Elnath"s}; + print("src", src); + std::vector dst; + std::ranges::copy(std::counted_iterator{src.begin(), 3}, + std::default_sentinel, + std::back_inserter(dst)); + print("dst", dst); + } + +.SH Output: + + src[5] { Arcturus, Betelgeuse, Canopus, Deneb, Elnath } + dst[3] { Arcturus, Betelgeuse, Canopus } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + member typedefs are not provided member typedefs are added to + std::incrementable_traits account for iterator_traits fix + P2259R1 C++20 is specialized for redundant + counted_iterator std::incrementable_traits + specialization is removed + +.SH See also + + default_sentinel_t default sentinel for use with iterators that know the bound of + (C++20) their range + \fI(class)\fP + views::counted creates a subrange from an iterator and a count + (C++20) (customization point object) + ranges::take_view a view consisting of the first N elements of another view + views::take \fI(class template)\fP (range adaptor object) + (C++20) diff --git a/man/std::counted_iterator::base.3 b/man/std::counted_iterator::base.3 new file mode 100644 index 000000000..7d6220923 --- /dev/null +++ b/man/std::counted_iterator::base.3 @@ -0,0 +1,84 @@ +.TH std::counted_iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::base \- std::counted_iterator::base + +.SH Synopsis + constexpr const I& base() const& noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr I base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns the underlying base iterator. + + 1) Returns a reference to the underlying iterator. + 2) Move constructs the return value from the underlying iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A reference to the underlying iterator. + 2) An iterator move constructed from the underlying iterator. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector v{0, 1, 2, 3, 4}; + + std::reverse_iterator::iterator> reverse{v.rbegin()}; + + std::counted_iterator counted{reverse, 3}; + + static_assert(std::is_same< + decltype(counted.base()), + std::reverse_iterator::iterator> const& + >{}); + + std::cout << "Print with reverse_iterator: "; + for (auto r = counted.base(); r != v.rend(); ++r) + std::cout << *r << ' '; + std::cout << '\\n'; + + std::cout << "Print with counted_iterator: "; + for (; counted != std::default_sentinel; ++counted) + std::cout << counted[0] << ' '; + std::cout << '\\n'; + } + +.SH Output: + + Print with reverse_iterator: 4 3 2 1 0 + Print with counted_iterator: 4 3 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3391 C++20 the const version of base returns a copy of returns a reference + the underlying iterator + LWG 3593 C++20 the const version of base returns a made noexcept + reference but might not be noexcept + +.SH See also + + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + (C++20) + count returns the distance to the end + (C++20) \fI(public member function)\fP diff --git a/man/std::counted_iterator::count.3 b/man/std::counted_iterator::count.3 new file mode 100644 index 000000000..94442e036 --- /dev/null +++ b/man/std::counted_iterator::count.3 @@ -0,0 +1,47 @@ +.TH std::counted_iterator::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::count \- std::counted_iterator::count + +.SH Synopsis + constexpr std::iter_difference_t count() const noexcept; \fI(since C++20)\fP + + Returns the underlying length that is the distance to the end. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying length. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr static auto il = {1, 2, 3, 4, 5}; + constexpr std::counted_iterator i1{il.begin() + 1, 3}; + static_assert(i1.count() == 3); + auto i2{i1}; + for (; std::default_sentinel != i2; ++i2) + std::cout << "*i2: " << *i2 << ", count(): " << i2.count() << '\\n'; + assert(i2.count() == 0); + } + +.SH Output: + + *i2: 2, count(): 3 + *i2: 3, count(): 2 + *i2: 4, count(): 1 + +.SH See also + + base accesses the underlying iterator + (C++20) \fI(public member function)\fP diff --git a/man/std::counted_iterator::counted_iterator.3 b/man/std::counted_iterator::counted_iterator.3 new file mode 100644 index 000000000..b05358932 --- /dev/null +++ b/man/std::counted_iterator::counted_iterator.3 @@ -0,0 +1,72 @@ +.TH std::counted_iterator::counted_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::counted_iterator \- std::counted_iterator::counted_iterator + +.SH Synopsis + constexpr counted_iterator() requires \fB(1)\fP \fI(since C++20)\fP + std::default_initializable = default; + constexpr counted_iterator( I x, std::iter_difference_t n ); \fB(2)\fP \fI(since C++20)\fP + template< class I2 > + + requires std::convertible_to \fB(3)\fP \fI(since C++20)\fP + + constexpr counted_iterator( const counted_iterator& + other ); + + Constructs a new iterator adaptor. + + 1) Default constructor. Value-initializes the underlying iterator and initialized + the underlying length with 0. Operations on the resulting iterator have defined + behavior if and only if the corresponding operations on a value-initialized I also + have defined behavior. + 2) The underlying iterator is initialized with std::move(x) and the underlying + length is initialized with n. The behavior is undefined if n is negative. + 3) The underlying iterator and length are initialized with those of other. + +.SH Parameters + + x - iterator to adapt + n - distance to the end + other - iterator adaptor to convert + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + static constexpr auto pi = {3, 1, 4, 1, 5, 9, 2}; + + // (1) default constructor: + constexpr std::counted_iterator::iterator> i1{}; + static_assert(i1 == std::default_sentinel); + static_assert(i1.count() == 0); + + // (2) initializes the iterator and length respectively: + constexpr std::counted_iterator::iterator> i2{ + pi.begin(), pi.size() - 2 + }; + static_assert(i2.count() == 5); + static_assert(*i2 == 3 && i2[1] == 1); + + // (3) converting-constructor: + std::counted_iterator::iterator> i3{i2}; + + std::ranges::copy(i3, std::default_sentinel, + std::ostream_iterator{std::cout, " "}); + } + +.SH Output: + + 3 1 4 1 5 + +.SH See also + + operator= assigns another iterator adaptor + (C++20) \fI(public member function)\fP diff --git a/man/std::counted_iterator::operator*,->.3 b/man/std::counted_iterator::operator*,->.3 new file mode 100644 index 000000000..811ac7659 --- /dev/null +++ b/man/std::counted_iterator::operator*,->.3 @@ -0,0 +1,56 @@ +.TH std::counted_iterator::operator*,-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::operator*,-> \- std::counted_iterator::operator*,-> + +.SH Synopsis + constexpr decltype(auto) operator*(); \fB(1)\fP \fI(since C++20)\fP + constexpr decltype(auto) operator*() const \fB(2)\fP \fI(since C++20)\fP + requires /*dereferenceable*/; + constexpr auto operator->() const noexcept \fB(3)\fP \fI(since C++20)\fP + requires std::contiguous_iterator; + + 1,2) Returns a reference to the current element. The behavior is undefined if + this->count() <= 0. The function's body is equivalent to return *current;. + 3) Returns a pointer to the current element. The function's body is equivalent to + return std::to_address(current);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference or pointer to the current element. + +.SH Example + + +// Run this code + + #include + #include + #include + using std::operator""i; + + int main() + { + const auto il = {1.i, 2.i, 3.i, 4.i, 5.i}; + + for (std::counted_iterator i{il.begin() + 1, 3}; i != std::default_sentinel; ++i) + std::cout << *i << ' '; + std::cout << '\\n'; + + for (std::counted_iterator i{il.begin() + 1, 3}; i != std::default_sentinel; ++i) + std::cout << i->imag() << ' '; + std::cout << '\\n'; + } + +.SH Output: + + (0,2) (0,3) (0,4) + 2 3 4 + +.SH See also + + operator[] accesses an element by index + (C++20) \fI(public member function)\fP diff --git a/man/std::counted_iterator::operator++,+,+=,--,-,-=.3 b/man/std::counted_iterator::operator++,+,+=,--,-,-=.3 new file mode 100644 index 000000000..96231aaf8 --- /dev/null +++ b/man/std::counted_iterator::operator++,+,+=,--,-,-=.3 @@ -0,0 +1,94 @@ +.TH std::counted_iterator::operator++,+,+=,--,-,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::operator++,+,+=,--,-,-= \- std::counted_iterator::operator++,+,+=,--,-,-= + +.SH Synopsis + constexpr counted_iterator& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr decltype(auto) operator++( int ); \fB(2)\fP \fI(since C++20)\fP + constexpr counted_iterator operator++( int ) \fB(3)\fP \fI(since C++20)\fP + requires std::forward_iterator; + constexpr counted_iterator& operator--() \fB(4)\fP \fI(since C++20)\fP + requires std::bidirectional_iterator; + constexpr counted_iterator operator--( int ) \fB(5)\fP \fI(since C++20)\fP + requires std::bidirectional_iterator; + constexpr counted_iterator operator+( std::iter_difference_t n + ) const \fB(6)\fP \fI(since C++20)\fP + requires std::random_access_iterator; + constexpr counted_iterator& operator+=( std::iter_difference_t + n ) \fB(7)\fP \fI(since C++20)\fP + requires std::random_access_iterator; + constexpr counted_iterator operator-( std::iter_difference_t n + ) const \fB(8)\fP \fI(since C++20)\fP + requires std::random_access_iterator; + constexpr counted_iterator& operator-=( std::iter_difference_t + n ) \fB(9)\fP \fI(since C++20)\fP + requires std::random_access_iterator; + + Increments or decrements the underlying iterator current and the distance to the end + length. + + The behavior of these functions is undefined if the length would be set to a minus + value. + + 1) Pre-increments by one. Equivalent to ++current; --length; return *this;. + 2) Post-increments by one. Equivalent to --length; try { return current++; } + catch(...) { ++length; throw; }. + 3) Post-increments by one. Equivalent to counted_iterator temp{*this}; ++*this; + return temp;. + 4) Pre-decrements by one. Equivalent to --current; ++length; return *this;. + 5) Post-decrements by one. Equivalent to counted_iterator temp{*this}; --*this; + return temp;. + 6) Returns an iterator adaptor which is advanced by n. Equivalent to return + counted_iterator(current + n, length - n);. + 7) Advances the iterator adaptor by n. Equivalent to current += n; length -= n; + return *this;. + 8) Returns an iterator adaptor which is advanced by -n. Equivalent to return + counted_iterator(current - n, length + n);. + 9) Advances the iterator adaptor by -n. Equivalent to current -= n; length += n; + return *this;. + +.SH Parameters + + n - the number of positions to increment or decrement the iterator adaptor + +.SH Return value + + 1) *this + 2,3) A copy of *this that was made before the change. + 4) *this + 5) A copy of *this that was made before the change. + 6) An iterator adaptor which is advanced by n. + 7) *this + 8) An iterator adaptor which is advanced by -n. + 9) *this + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto v = {1, 2, 3, 4, 5, 6}; + std::counted_iterator::iterator> it1{v.begin(), 5}; + + ++it1; assert(*it1 == 2 && it1.count() == 4); // (1) + auto it2 = it1++; assert(*it2 == 2 && *it1 == 3); // (3) + --it1; assert(*it1 == 2 && it1.count() == 4); // (4) + auto it3 = it1--; assert(*it3 == 2 && *it1 == 1); // (5) + auto it4 = it1 + 3; assert(*it4 == 4 && it4.count() == 2); // (6) + auto it5 = it4 - 3; assert(*it5 == 1 && it5.count() == 5); // (8) + it1 += 3; assert(*it1 == 4 && it1.count() == 2); // (7) + it1 -= 3; assert(*it1 == 1 && it1.count() == 5); // (9) + } + +.SH See also + + operator+ advances the iterator + (C++20) \fI(function template)\fP + operator- computes the distance between two iterator adaptors + (C++20) \fI(function template)\fP diff --git a/man/std::counted_iterator::operator=.3 b/man/std::counted_iterator::operator=.3 new file mode 100644 index 000000000..759104c56 --- /dev/null +++ b/man/std::counted_iterator::operator=.3 @@ -0,0 +1,48 @@ +.TH std::counted_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::operator= \- std::counted_iterator::operator= + +.SH Synopsis + template< class I2 > + + requires std::assignable_from \fI(since C++20)\fP + + constexpr counted_iterator& operator=( const counted_iterator& + other ); + + The underlying iterator and length are assigned with those of other. + +.SH Parameters + + other - iterator adaptor to assign from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto a = {3, 1, 4, 1, 5, 9, 2}; + std::counted_iterator::iterator> p(begin(a), size(a) - 2); + std::counted_iterator::iterator> q; + assert(q.count() == 0); + assert(q.count() != p.count()); + q = p; + assert(q.count() == p.count()); + assert(std::ranges::equal(p, std::default_sentinel, q, std::default_sentinel)); + } + +.SH See also + + constructor constructs a new iterator adaptor + (C++20) \fI(public member function)\fP diff --git a/man/std::counted_iterator::operator[].3 b/man/std::counted_iterator::operator[].3 new file mode 100644 index 000000000..04f0976d7 --- /dev/null +++ b/man/std::counted_iterator::operator[].3 @@ -0,0 +1,64 @@ +.TH std::counted_iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counted_iterator::operator[] \- std::counted_iterator::operator[] + +.SH Synopsis + constexpr decltype(auto) operator[]( std::iter_difference_t n ) + const \fI(since C++20)\fP + requires std::random_access_iterator; + + Accesses the element at specified relative location. The behavior is undefined if n + is not less than the recorded distance to the end. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + this->base()[n] + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::array array{'A', 'B', 'C', 'D', 'E'}; + + std::counted_iterator it{array.begin() + 1, /*count:*/ 3}; + + for (int i{}; i != it.count(); ++i) + std::cout << it[i] << ' '; + std::cout << '\\n'; + + for (int i{}; i != it.count(); ++i) + it[i] += ('E' - 'A'); + + for (int i{}; i != it.count(); ++i) + std::cout << it[i] << ' '; + std::cout << '\\n'; + + std::list list{'X', 'Y', 'Z', 'W'}; + std::counted_iterator it2{list.begin(), 3}; + // char x = it2[0]; // Error: requirement `random_access_iterator` was not satisfied. + std::cout << *it2 << '\\n'; // OK + } + +.SH Output: + + B C D + F G H + X + +.SH See also + + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP + (C++20) diff --git a/man/std::counting_semaphore,std::binary_semaphore.3 b/man/std::counting_semaphore,std::binary_semaphore.3 new file mode 100644 index 000000000..b18a52b6f --- /dev/null +++ b/man/std::counting_semaphore,std::binary_semaphore.3 @@ -0,0 +1,141 @@ +.TH std::counting_semaphore,std::binary_semaphore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore,std::binary_semaphore \- std::counting_semaphore,std::binary_semaphore + +.SH Synopsis + Defined in header + template< std::ptrdiff_t LeastMaxValue = /* implementation-defined + */ > \fB(1)\fP \fI(since C++20)\fP + class counting_semaphore; + using binary_semaphore = std::counting_semaphore<1>; \fB(2)\fP \fI(since C++20)\fP + + 1) A counting_semaphore is a lightweight synchronization primitive that can control + access to a shared resource. Unlike a std::mutex, a counting_semaphore allows more + than one concurrent access to the same resource, for at least LeastMaxValue + concurrent accessors. The program is ill-formed if LeastMaxValue is negative. + 2) binary_semaphore is an alias for specialization of std::counting_semaphore with + LeastMaxValue being 1. Implementations may implement binary_semaphore more + efficiently than the default implementation of std::counting_semaphore. + + A counting_semaphore contains an internal counter initialized by the constructor. + This counter is decremented by calls to acquire() and related methods, and is + incremented by calls to release(). When the counter is zero, acquire() blocks until + the counter is incremented, but try_acquire() does not block; try_acquire_for() and + try_acquire_until() block until the counter is incremented or a timeout is reached. + + Similar to std::condition_variable::wait(), counting_semaphore's try_acquire() can + spuriously fail. + + Specializations of std::counting_semaphore are not DefaultConstructible, + CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable. + +.SH Member functions + + constructor constructs a counting_semaphore + \fI(public member function)\fP + destructor destructs the counting_semaphore + \fI(public member function)\fP + operator= counting_semaphore is not assignable + [deleted] \fI(public member function)\fP +.SH Operations + release increments the internal counter and unblocks acquirers + \fI(public member function)\fP + acquire decrements the internal counter or blocks until it can + \fI(public member function)\fP + try_acquire tries to decrement the internal counter without blocking + \fI(public member function)\fP + tries to decrement the internal counter, blocking for up to a + try_acquire_for duration time + \fI(public member function)\fP + tries to decrement the internal counter, blocking until a point in + try_acquire_until time + \fI(public member function)\fP +.SH Constants + max returns the maximum possible value of the internal counter + \fB[static]\fP \fI(public static member function)\fP + +.SH Notes + + As its name indicates, the LeastMaxValue is the minimum max value, not the actual + max value. Thus max() can yield a number larger than LeastMaxValue. + + Unlike std::mutex a counting_semaphore is not tied to threads of execution - + acquiring a semaphore can occur on a different thread than releasing the semaphore, + for example. All operations on counting_semaphore can be performed concurrently and + without any relation to specific threads of execution, with the exception of the + destructor which cannot be performed concurrently but can be performed on a + different thread. + + Semaphores are also often used for the semantics of signaling/notifying rather than + mutual exclusion, by initializing the semaphore with 0 and thus blocking the + receiver(s) that try to acquire(), until the notifier "signals" by invoking + release(n). In this respect semaphores can be considered alternatives to + std::condition_variables, often with better performance. + + Feature-test macro Value Std Feature + __cpp_lib_semaphore 201907L (C++20) std::counting_semaphore, std::binary_semaphore + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // global binary semaphore instances + // object counts are set to zero + // objects are in non-signaled state + std::binary_semaphore + smphSignalMainToThread{0}, + smphSignalThreadToMain{0}; + + void ThreadProc() + { + // wait for a signal from the main proc + // by attempting to decrement the semaphore + smphSignalMainToThread.acquire(); + + // this call blocks until the semaphore's count + // is increased from the main proc + + std::cout << "[thread] Got the signal\\n"; // response message + + // wait for 3 seconds to imitate some work + // being done by the thread + using namespace std::literals; + std::this_thread::sleep_for(3s); + + std::cout << "[thread] Send the signal\\n"; // message + + // signal the main proc back + smphSignalThreadToMain.release(); + } + + int main() + { + // create some worker thread + std::thread thrWorker(ThreadProc); + + std::cout << "[main] Send the signal\\n"; // message + + // signal the worker thread to start working + // by increasing the semaphore's count + smphSignalMainToThread.release(); + + // wait until the worker thread is done doing the work + // by attempting to decrement the semaphore's count + smphSignalThreadToMain.acquire(); + + std::cout << "[main] Got the signal\\n"; // response message + thrWorker.join(); + } + +.SH Output: + + [main] Send the signal + [thread] Got the signal + [thread] Send the signal + [main] Got the signal diff --git a/man/std::counting_semaphore::acquire.3 b/man/std::counting_semaphore::acquire.3 new file mode 100644 index 000000000..c93e5353e --- /dev/null +++ b/man/std::counting_semaphore::acquire.3 @@ -0,0 +1,186 @@ +.TH std::counting_semaphore::acquire 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::acquire \- std::counting_semaphore::acquire + +.SH Synopsis + void acquire(); \fI(since C++20)\fP + + Atomically decrements the internal counter by 1 if it is greater than 0; otherwise + blocks until it is greater than 0 and can successfully decrement the internal + counter. + +.SH Preconditions + + \fI(none)\fP + +.SH Parameters + + \fI(none)\fP + +.SH Exceptions + + May throw std::system_error. + +.SH Example + + The example visualizes a concurrent work of several randomized threads when no more + than N (N is the semaphore desired value) of the thread-functions are active, while + the other might wait on the semaphore. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + using namespace std::literals; + + constexpr std::size_t max_threads{10U}; // change and see the effect + constexpr std::ptrdiff_t max_sema_threads{3}; // {1} for binary semaphore + std::counting_semaphore semaphore{max_sema_threads}; + constexpr auto time_tick{10ms}; + + unsigned rnd() + { + static std::uniform_int_distribution distribution{2U, 9U}; // [delays] + static std::random_device engine; + static std::mt19937 noise{engine()}; + return distribution(noise); + } + + class alignas(std::hardware_destructive_interference_size) Guide + { + inline static std::mutex cout_mutex; + inline static std::chrono::time_point started_at; + unsigned delay{rnd()}, occupy{rnd()}, wait_on_sema{}; + + public: + static void start_time() { started_at = std::chrono::high_resolution_clock::now(); } + + void initial_delay() { std::this_thread::sleep_for(delay * time_tick); } + + void occupy_sema() + { + wait_on_sema = + static_cast(std::chrono::duration_cast( + std::chrono::high_resolution_clock::now() - started_at - + delay * time_tick).count() / time_tick.count()); + std::this_thread::sleep_for(occupy * time_tick); + } + + void visualize(unsigned id, unsigned x_scale = 2) const + { + auto cout_n = [=](auto str, unsigned n) + { + for (n *= x_scale; n-- > 0; std::cout << str) + ; + }; + std::lock_guard lk{cout_mutex}; + std::cout << '#' << std::setw(2) << id << ' '; + cout_n("░", delay); + cout_n("▒", wait_on_sema); + cout_n("█", occupy); + std::cout << '\\n'; + } + + static void show_info() + { + std::cout << "\\nThreads: " << max_threads << ", Throughput: " << max_sema_threads + << " │ Legend: initial delay ░░ │ wait state ▒▒ │ sema occupation ██ \\n" + << std::endl; + } + }; + + std::array guides; + + void workerThread(unsigned id) + { + guides[id].initial_delay(); // emulate some work before sema acquisition + semaphore.acquire(); // wait until a free sema slot is available + guides[id].occupy_sema(); // emulate some work while sema is acquired + semaphore.release(); + guides[id].visualize(id); + } + + int main() + { + std::vector threads; + threads.reserve(max_threads); + + Guide::show_info(); + Guide::start_time(); + + for (auto id{0U}; id != max_threads; ++id) + threads.push_back(std::jthread(workerThread, id)); + } + +.SH Possible output: + + Default case: max_threads{10U}, max_sema_threads{3} + + Threads: 10, Throughput: 3 │ Legend: initial delay ░░ │ wait state ▒▒ │ sema occupation ██ + + # 1 ░░░░██████ + # 2 ░░░░████████ + # 5 ░░░░░░██████████ + # 8 ░░░░░░░░░░░░████████████ + # 9 ░░░░░░░░░░░░██████████████ + # 7 ░░░░░░░░░░░░▒▒▒▒████████████████ + # 4 ░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒████████ + # 6 ░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒██████████████████ + # 3 ░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒████████████ + # 0 ░░░░░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒██████████████ + + ────────────────────────────────────────────────────────────────────────────────────────────────────────────── + "Enough for everyone" case (no wait states!): max_threads{10U}, max_sema_threads{10} + + Threads: 10, Throughput: 10 │ Legend: initial delay ░░ │ wait state ▒▒ │ sema occupation ██ + + # 4 ░░░░██████ + # 5 ░░░░░░████ + # 3 ░░░░██████████ + # 1 ░░░░██████████ + # 8 ░░░░░░░░████████████ + # 6 ░░░░░░░░░░░░░░░░██████ + # 7 ░░░░░░░░░░░░░░░░██████ + # 9 ░░░░░░░░░░░░░░░░██████████ + # 0 ░░░░░░░░░░░░██████████████████ + # 2 ░░░░░░░░░░░░░░░░░░████████████ + + ────────────────────────────────────────────────────────────────────────────────────────────────────────────── + Binary semaphore case: max_threads{10U}, max_sema_threads{1} + + Threads: 10, Throughput: 1 │ Legend: initial delay ░░ │ wait state ▒▒ │ sema occupation ██ + + # 6 ░░░░████ + # 5 ░░░░▒▒▒▒████ + # 4 ░░░░░░░░░░▒▒██████████ + # 7 ░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒████████████████ + # 2 ░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒██████ + # 3 ░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒████████████████ + # 0 ░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒████████████ + # 1 ░░░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒████████ + # 8 ░░░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒██████ + # 9 ░░░░░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒██████████████ + +.SH See also + + release increments the internal counter and unblocks acquirers + \fI(public member function)\fP + try_acquire tries to decrement the internal counter without blocking + \fI(public member function)\fP + tries to decrement the internal counter, blocking for up to a + try_acquire_for duration time + \fI(public member function)\fP + tries to decrement the internal counter, blocking until a point in + try_acquire_until time + \fI(public member function)\fP diff --git a/man/std::counting_semaphore::counting_semaphore.3 b/man/std::counting_semaphore::counting_semaphore.3 new file mode 100644 index 000000000..fe9346300 --- /dev/null +++ b/man/std::counting_semaphore::counting_semaphore.3 @@ -0,0 +1,23 @@ +.TH std::counting_semaphore::counting_semaphore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::counting_semaphore \- std::counting_semaphore::counting_semaphore + +.SH Synopsis + constexpr explicit counting_semaphore( std::ptrdiff_t desired ); \fB(1)\fP \fI(since C++20)\fP + counting_semaphore( const counting_semaphore& ) = delete; \fB(2)\fP \fI(since C++20)\fP + + 1) Constructs an object of type std::counting_semaphore with the internal counter + initialized to desired. + 2) Copy constructor is deleted. + +.SH Preconditions + + 1) Both desired >= 0 and desired <= max() are true. + +.SH Parameters + + desired - the value to initialize counting_semaphore's counter with + +.SH Exceptions + + Throws nothing. diff --git a/man/std::counting_semaphore::max.3 b/man/std::counting_semaphore::max.3 new file mode 100644 index 000000000..5d74c401f --- /dev/null +++ b/man/std::counting_semaphore::max.3 @@ -0,0 +1,20 @@ +.TH std::counting_semaphore::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::max \- std::counting_semaphore::max + +.SH Synopsis + constexpr std::ptrdiff_t max() noexcept; \fI(since C++20)\fP + + Returns the internal counter's maximum possible value, which is greater than or + equal to LeastMaxValue. + +.SH Return value + + The internal counter's maximum possible value, as a std::ptrdiff_t. + +.SH Notes + + For specialization binary_semaphore, LeastMaxValue is equal to 1. + + As its name indicates, the LeastMaxValue is the minimum max value, not the actual + max value. Thus max() can yield a number larger than LeastMaxValue. diff --git a/man/std::counting_semaphore::release.3 b/man/std::counting_semaphore::release.3 new file mode 100644 index 000000000..c5a59fe11 --- /dev/null +++ b/man/std::counting_semaphore::release.3 @@ -0,0 +1,36 @@ +.TH std::counting_semaphore::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::release \- std::counting_semaphore::release + +.SH Synopsis + void release( std::ptrdiff_t update = 1 ); \fI(since C++20)\fP + + Atomically increments the internal counter by the value of update. Any thread(s) + waiting for the counter to be greater than 0, such as due to being blocked in + acquire, will subsequently be unblocked. + +.SH Preconditions + + Both update >= 0 and update <= max() - counter are true, where counter is the value + of the internal counter. + +.SH Parameters + + update - the amount to increment the internal counter by + +.SH Exceptions + + May throw std::system_error. + +.SH See also + + acquire decrements the internal counter or blocks until it can + \fI(public member function)\fP + try_acquire tries to decrement the internal counter without blocking + \fI(public member function)\fP + tries to decrement the internal counter, blocking for up to a + try_acquire_for duration time + \fI(public member function)\fP + tries to decrement the internal counter, blocking until a point in + try_acquire_until time + \fI(public member function)\fP diff --git a/man/std::counting_semaphore::try_acquire.3 b/man/std::counting_semaphore::try_acquire.3 new file mode 100644 index 000000000..dbeec6aaf --- /dev/null +++ b/man/std::counting_semaphore::try_acquire.3 @@ -0,0 +1,31 @@ +.TH std::counting_semaphore::try_acquire 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::try_acquire \- std::counting_semaphore::try_acquire + +.SH Synopsis + bool try_acquire() noexcept; \fI(since C++20)\fP + + Tries to atomically decrement the internal counter by 1 if it is greater than 0; no + blocking occurs regardless. + +.SH Return value + + true if it decremented the internal counter, otherwise false. + +.SH Notes + + Implementations are allowed to fail to decrement the counter even if it was greater + than 0 - i.e., they are allowed to spuriously fail and return false. + +.SH See also + + release increments the internal counter and unblocks acquirers + \fI(public member function)\fP + acquire decrements the internal counter or blocks until it can + \fI(public member function)\fP + tries to decrement the internal counter, blocking for up to a + try_acquire_for duration time + \fI(public member function)\fP + tries to decrement the internal counter, blocking until a point in + try_acquire_until time + \fI(public member function)\fP diff --git a/man/std::counting_semaphore::try_acquire_for.3 b/man/std::counting_semaphore::try_acquire_for.3 new file mode 100644 index 000000000..8e3533046 --- /dev/null +++ b/man/std::counting_semaphore::try_acquire_for.3 @@ -0,0 +1,44 @@ +.TH std::counting_semaphore::try_acquire_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::try_acquire_for \- std::counting_semaphore::try_acquire_for + +.SH Synopsis + template< class Rep, class Period > + bool try_acquire_for( const std::chrono::duration& \fI(since C++20)\fP + rel_time ); + + Tries to atomically decrement the internal counter by 1 if it is greater than 0; + otherwise blocks until it is greater than 0 and can successfully decrement the + internal counter, or the rel_time duration has been exceeded. + +.SH Preconditions + + \fI(none)\fP + +.SH Parameters + + rel_time - the minimum duration the function must wait for it to fail + +.SH Return value + + true if it decremented the internal counter, otherwise false. + +.SH Exceptions + + May throw std::system_error or a timeout-related exception. + +.SH Notes + + In practice the function may take longer than rel_time to fail. + +.SH See also + + release increments the internal counter and unblocks acquirers + \fI(public member function)\fP + acquire decrements the internal counter or blocks until it can + \fI(public member function)\fP + try_acquire tries to decrement the internal counter without blocking + \fI(public member function)\fP + tries to decrement the internal counter, blocking until a point in + try_acquire_until time + \fI(public member function)\fP diff --git a/man/std::counting_semaphore::try_acquire_until.3 b/man/std::counting_semaphore::try_acquire_until.3 new file mode 100644 index 000000000..e9d824f47 --- /dev/null +++ b/man/std::counting_semaphore::try_acquire_until.3 @@ -0,0 +1,46 @@ +.TH std::counting_semaphore::try_acquire_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::try_acquire_until \- std::counting_semaphore::try_acquire_until + +.SH Synopsis + template< class Clock, class Duration > + bool try_acquire_until( const std::chrono::time_point& abs_time ); + + Tries to atomically decrement the internal counter by 1 if it is greater than 0; + otherwise blocks until it is greater than 0 and can successfully decrement the + internal counter, or the abs_time time point has been passed. + + The programs is ill-formed if std::chrono::is_clock_v is false. + +.SH Preconditions + + Clock meets the Clock requirements. + +.SH Parameters + + abs_time - the earliest time the function must wait until in order to fail + +.SH Return value + + true if it decremented the internal counter, otherwise false. + +.SH Exceptions + + May throw std::system_error or a timeout-related exception. + +.SH Notes + + In practice the function may take longer than abs_time to fail. + +.SH See also + + release increments the internal counter and unblocks acquirers + \fI(public member function)\fP + acquire decrements the internal counter or blocks until it can + \fI(public member function)\fP + try_acquire tries to decrement the internal counter without blocking + \fI(public member function)\fP + tries to decrement the internal counter, blocking for up to a + try_acquire_for duration time + \fI(public member function)\fP diff --git a/man/std::counting_semaphore::~counting_semaphore.3 b/man/std::counting_semaphore::~counting_semaphore.3 new file mode 100644 index 000000000..5b247d0e6 --- /dev/null +++ b/man/std::counting_semaphore::~counting_semaphore.3 @@ -0,0 +1,12 @@ +.TH std::counting_semaphore::~counting_semaphore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::counting_semaphore::~counting_semaphore \- std::counting_semaphore::~counting_semaphore + +.SH Synopsis + ~counting_semaphore(); \fI(since C++20)\fP + + Destroys the counting_semaphore object. + + The behavior is undefined if any thread is concurrently calling any other member + function on this semaphore. This includes threads blocked in acquire(), + try_acquire_for(), or try_acquire_until(). diff --git a/man/std::countl_one.3 b/man/std::countl_one.3 new file mode 100644 index 000000000..4f7658985 --- /dev/null +++ b/man/std::countl_one.3 @@ -0,0 +1,74 @@ +.TH std::countl_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::countl_one \- std::countl_one + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr int countl_one( T x ) noexcept; + + Returns the number of consecutive 1 ("one") bits in the value of x, starting from + the most significant bit ("left"). + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + The number of consecutive 1 bits in the value of x, starting from the most + significant bit. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + for (const std::uint8_t i : {0, 0b11111111, 0b01111111, 0b11100011}) + std::cout << "countl_one( " << std::bitset<8>(i) << " ) = " + << std::countl_one(i) << '\\n'; + } + +.SH Output: + + countl_one( 00000000 ) = 0 + countl_one( 11111111 ) = 8 + countl_one( 01111111 ) = 0 + countl_one( 11100011 ) = 3 + +.SH See also + + countl_zero counts the number of consecutive 0 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countr_zero counts the number of consecutive 0 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + countr_one counts the number of consecutive 1 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP + has_single_bit checks if a number is an integral power of 2 + (C++20) \fI(function template)\fP + count returns the number of bits set to true + \fI(public member function of std::bitset)\fP + all checks if all, any or none of the bits are set to true + any \fI(public member function of std::bitset)\fP + none diff --git a/man/std::countl_zero.3 b/man/std::countl_zero.3 new file mode 100644 index 000000000..d13fad4f9 --- /dev/null +++ b/man/std::countl_zero.3 @@ -0,0 +1,70 @@ +.TH std::countl_zero 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::countl_zero \- std::countl_zero + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr int countl_zero( T x ) noexcept; + + Returns the number of consecutive 0 bits in the value of x, starting from the most + significant bit ("left"). + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + The number of consecutive 0 bits in the value of x, starting from the most + significant bit. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + for (const std::uint8_t i : {0, 0b11111111, 0b11110000, 0b00011110}) + std::cout << "countl_zero( " << std::bitset<8>(i) << " ) = " + << std::countl_zero(i) << '\\n'; + } + +.SH Output: + + countl_zero( 00000000 ) = 8 + countl_zero( 11111111 ) = 0 + countl_zero( 11110000 ) = 0 + countl_zero( 00011110 ) = 3 + +.SH See also + + countl_one counts the number of consecutive 1 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countr_zero counts the number of consecutive 0 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + countr_one counts the number of consecutive 1 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP + all checks if all, any or none of the bits are set to true + any \fI(public member function of std::bitset)\fP + none diff --git a/man/std::countr_one.3 b/man/std::countr_one.3 new file mode 100644 index 000000000..765f55fec --- /dev/null +++ b/man/std::countr_one.3 @@ -0,0 +1,74 @@ +.TH std::countr_one 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::countr_one \- std::countr_one + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr int countr_one( T x ) noexcept; + + Returns the number of consecutive 1 bits in the value of x, starting from the least + significant bit ("right"). + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + The number of consecutive 1 bits in the value of x, starting from the least + significant bit. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + for (const std::uint8_t i : {0, 0b11111111, 0b11111110, 0b11100011}) + std::cout << "countr_one( " << std::bitset<8>(i) << " ) = " + << std::countr_one(i) << '\\n'; + } + +.SH Output: + + countr_one( 00000000 ) = 0 + countr_one( 11111111 ) = 8 + countr_one( 11111110 ) = 0 + countr_one( 11100011 ) = 2 + +.SH See also + + countl_zero counts the number of consecutive 0 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countl_one counts the number of consecutive 1 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countr_zero counts the number of consecutive 0 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP + has_single_bit checks if a number is an integral power of 2 + (C++20) \fI(function template)\fP + count returns the number of bits set to true + \fI(public member function of std::bitset)\fP + all checks if all, any or none of the bits are set to true + any \fI(public member function of std::bitset)\fP + none diff --git a/man/std::countr_zero.3 b/man/std::countr_zero.3 new file mode 100644 index 000000000..1e703b312 --- /dev/null +++ b/man/std::countr_zero.3 @@ -0,0 +1,70 @@ +.TH std::countr_zero 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::countr_zero \- std::countr_zero + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr int countr_zero( T x ) noexcept; + + Returns the number of consecutive 0 bits in the value of x, starting from the least + significant bit ("right"). + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + The number of consecutive 0 bits in the value of x, starting from the least + significant bit. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + for (const std::uint8_t i : {0, 0b11111111, 0b00011100, 0b00011101}) + std::cout << "countr_zero( " << std::bitset<8>(i) << " ) = " + << std::countr_zero(i) << '\\n'; + } + +.SH Output: + + countr_zero( 00000000 ) = 8 + countr_zero( 11111111 ) = 0 + countr_zero( 00011100 ) = 2 + countr_zero( 00011101 ) = 0 + +.SH See also + + countl_zero counts the number of consecutive 0 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countl_one counts the number of consecutive 1 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countr_one counts the number of consecutive 1 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP + all checks if all, any or none of the bits are set to true + any \fI(public member function of std::bitset)\fP + none diff --git a/man/std::cout,std::wcout.3 b/man/std::cout,std::wcout.3 index 4ae73109c..1ed0b503b 100644 --- a/man/std::cout,std::wcout.3 +++ b/man/std::cout,std::wcout.3 @@ -1,4 +1,7 @@ -.TH std::cout,std::wcout 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cout,std::wcout 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cout,std::wcout \- std::cout,std::wcout + .SH Synopsis Defined in header extern std::ostream cout; \fB(1)\fP @@ -10,35 +13,55 @@ These objects are guaranteed to be initialized during or before the first time an object of type std::ios_base::Init is constructed and are available for use in the - constructors and destructors of static objects (as long as is included). + constructors and destructors of static objects with ordered initialization (as long + as is included before the object is defined). + + Unless std::ios_base::sync_with_stdio(false) has been issued, it is safe to + concurrently access these objects from multiple threads for both formatted and + unformatted output. + + By specification of std::cin, std::cin.tie() returns &std::cout. This means that any + input operation on std::cin executes std::cout.flush() (via + std::basic_istream::sentry's constructor). Similarly, std::wcin.tie() returns + &std::wcout. - Unless sync_with_stdio(false) has been issued, it is safe to concurrently access - these objects from multiple threads for both formatted and unformatted output. + By specification of std::cerr, std::cerr.tie() returns &std::cout. This means that + any output operation on std::cerr executes std::cout.flush() (via + std::basic_ostream::sentry's constructor). Similarly, std::wcerr.tie() returns + &std::wcout. \fI(since C++11)\fP - Once initialized, std::cout is tie()'d to std::cin and std::wcout is tie()'d to - std::wcin, meaning that any input operation on std::cin executes std::cout.flush() - (via std::basic_istream::sentry's constructor). +.SH Notes - Once initialized, std::cout is also tie()'d to std::cerr and std::wcout is tie()'d - to std::wcerr, meaning that any output operation on std::cerr executes - std::cout.flush() (via std::basic_ostream::sentry's constructor) \fI(since C++11)\fP + The 'c' in the name refers to "character" (stroustrup.com FAQ); cout means + "character output" and wcout means "wide character output". + + Because dynamic initialization of templated variables are unordered, it is not + guaranteed that std::cout has been initialized to a usable state before the + initialization of such variables begins, unless an object of type + std::ios_base::Init has been constructed. .SH Example - + // Run this code #include - struct Foo { + + struct Foo + { int n; - Foo() { - std::cout << "static constructor\\n"; + Foo() + { + std::cout << "static constructor\\n"; } - ~Foo() { - std::cout << "static destructor\\n"; + ~Foo() + { + std::cout << "static destructor\\n"; } }; + Foo f; // static object + int main() { std::cout << "main function\\n"; @@ -52,9 +75,13 @@ .SH See also - Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP - clog writes to the standard C error stream stderr - wclog (global object) - cout writes to the standard C output stream stdout - wcout (global object) + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + cerr writes to the standard C error stream stderr, unbuffered + wcerr (global object) + clog writes to the standard C error stream stderr + wclog (global object) + stdin expression of type FILE* associated with the input stream + stdout expression of type FILE* associated with the output stream + stderr expression of type FILE* associated with the error output stream + (macro constant) diff --git a/man/std::ctime.3 b/man/std::ctime.3 index dc2ceadd6..2e04b8d63 100644 --- a/man/std::ctime.3 +++ b/man/std::ctime.3 @@ -1,4 +1,7 @@ -.TH std::ctime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctime \- std::ctime + .SH Synopsis Defined in header char* ctime( const std::time_t* time ); @@ -7,16 +10,16 @@ representation, as if by calling std::asctime(std::localtime(time)). The resulting string has the following format: - Www Mmm dd hh:mm:ss yyyy + Www Mmm dd hh:mm:ss yyyy\\n * Www - the day of the week (one of Mon, Tue, Wed, Thu, Fri, Sat, Sun). * Mmm - the month (one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec). - * dd - the day of the month - * hh - hours - * mm - minutes - * ss - seconds - * yyyy - years + * dd - the day of the month. + * hh - hours. + * mm - minutes. + * ss - seconds. + * yyyy - years. The function does not support localization. @@ -37,34 +40,42 @@ std::localtime. POSIX marks this function obsolete and recommends std::strftime instead. - The behavior may be undefined for the values of time_t that result in the string - longer than 25 characters (e.g. year 10000) + The behavior may be undefined for the values of std::time_t that result in the + string longer than 25 characters (e.g. year 10000). .SH Example - + // Run this code + #include + #include #include #include - + int main() { - std::time_t result = std::time(NULL); + std::time_t result = std::time(nullptr); std::cout << std::ctime(&result); + + char buffer[32]; + std::strncpy(buffer, std::ctime(&result), 26); + assert('\\n' == buffer[std::strlen(buffer) - 1]); + std::cout << buffer; } -.SH Output: +.SH Possible output: - Tue Dec 27 17:21:29 2011 + Mon Oct 11 17:10:55 2021 + Mon Oct 11 17:10:55 2021 .SH See also - asctime converts a tm object to a textual representation - \fI(function)\fP - strftime converts a tm object to custom textual representation - \fI(function)\fP + asctime converts a std::tm object to a textual representation + \fI(function)\fP + strftime converts a std::tm object to custom textual representation + \fI(function)\fP put_time formats and outputs a date/time value according to the specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP C documentation for ctime diff --git a/man/std::ctype.3 b/man/std::ctype.3 index 933f5ee98..435099d56 100644 --- a/man/std::ctype.3 +++ b/man/std::ctype.3 @@ -1,22 +1,26 @@ -.TH std::ctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype \- std::ctype + .SH Synopsis Defined in header template< class CharT > class ctype; Class ctype encapsulates character classification features. All stream input - operations performed through std::basic_istream use the std::ctype of + operations performed through std::basic_istream use the std::ctype of the locale imbued in the stream to identify whitespace characters for input - tokenization. Stream output operations apply std::ctype::widen() to + tokenization. Stream output operations apply std::ctype::widen() to narrow-character arguments prior to output. std-ctype-inheritance.svg - About this image Inheritance diagram - Two standalone (locale-independent) specializations are provided by the standard - library: +.SH Specializations + + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header provides narrow character equivalents of the minimal "C" locale @@ -25,9 +29,6 @@ std::ctype provides wide character classification appropriate to the native character set - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. - .SH Member types Member type Definition @@ -40,19 +41,19 @@ destructor destructs a ctype facet \fI(protected member function)\fP is invokes do_is - \fI(public member function)\fP + \fI(public member function)\fP scan_is invokes do_scan_is - \fI(public member function)\fP + \fI(public member function)\fP scan_not invokes do_scan_not - \fI(public member function)\fP + \fI(public member function)\fP toupper invokes do_toupper - \fI(public member function)\fP + \fI(public member function)\fP tolower invokes do_tolower - \fI(public member function)\fP + \fI(public member function)\fP widen invokes do_widen - \fI(public member function)\fP + \fI(public member function)\fP narrow invokes do_narrow - \fI(public member function)\fP + \fI(public member function)\fP .SH Member objects @@ -62,21 +63,21 @@ .SH Protected member functions do_is classifies a character or a character sequence - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_scan_is locates the first character in a sequence that conforms to given \fB[virtual]\fP classification - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP do_scan_not locates the first character in a sequence that fails given \fB[virtual]\fP classification - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP do_toupper converts a character or characters to uppercase - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_tolower converts a character or characters to lowercase - \fB[virtual]\fP \fI(virtual protected member function)\fP - do_widen converts a character or characters from char to charT - \fB[virtual]\fP \fI(virtual protected member function)\fP - do_narrow converts a character or characters from charT to char - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_widen converts a character or characters from char to CharT + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_narrow converts a character or characters from CharT to char + \fB[virtual]\fP \fI(virtual protected member function)\fP Inherited from std::ctype_base @@ -116,46 +117,45 @@ Inherited from std::ctype_base .SH Example The following example demonstrates modification of a ctype other than ctype to - tokenize a CSV file + tokenize a CSV file: + - // Run this code #include #include #include - + struct csv_whitespace : std::ctype { bool do_is(mask m, char_type c) const { - if ((m & space) && c == L' ') { + if ((m & space) && c == L' ') return false; // space will NOT be classified as whitespace - } - if ((m & space) && c == L',') { + + if ((m & space) && c == L',') return true; // comma will be classified as whitespace - } - return ctype::do_is(m, c); // leave the rest to the parent class + + return ctype::do_is(m, c); // leave the rest to the base class } }; - + int main() { std::wstring in = L"Column 1,Column 2,Column 3\\n123,456,789"; std::wstring token; - + std::wcout << "default locale:\\n"; std::wistringstream s1(in); - while (s1 >> token) { + while (s1 >> token) std::wcout << " " << token << '\\n'; - } - + std::wcout << "locale with modified ctype:\\n"; std::wistringstream s2(in); - s2.imbue(std::locale(s2.getloc(), new csv_whitespace())); - while (s2 >> token) { - std::wcout << " " << token<< '\\n'; - } + csv_whitespace* my_ws = new csv_whitespace; + s2.imbue(std::locale(s2.getloc(), my_ws)); + while (s2 >> token) + std::wcout << " " << token << '\\n'; } .SH Output: @@ -179,6 +179,6 @@ Inherited from std::ctype_base ctype specialization of std::ctype for type char \fI(class template specialization)\fP ctype_base defines character classification categories - \fI(class template)\fP - ctype_byname creates a ctype facet for the named locale + \fI(class)\fP + ctype_byname represents the system-supplied std::ctype for the named locale \fI(class template)\fP diff --git a/man/std::ctype::classic_table.3 b/man/std::ctype::classic_table.3 new file mode 100644 index 000000000..4f5b0bdcc --- /dev/null +++ b/man/std::ctype::classic_table.3 @@ -0,0 +1,32 @@ +.TH std::ctype::classic_table 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::classic_table \- std::ctype::classic_table + +.SH Synopsis + Defined in header + static const mask* classic_table() throw(); \fI(until C++11)\fP + static const mask* classic_table() noexcept; \fI(since C++11)\fP + + Returns the classification table that matches the classification used by the minimal + "C" locale. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the first element in the classification table (which is an array of + size std::ctype::table_size). + +.SH Notes + + Default-constructed std::ctype facets use this table for classification. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ctype::ctype.3 b/man/std::ctype::ctype.3 index eb6ae5941..162208f16 100644 --- a/man/std::ctype::ctype.3 +++ b/man/std::ctype::ctype.3 @@ -1,10 +1,13 @@ -.TH std::ctype::ctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::ctype 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::ctype \- std::ctype::ctype + .SH Synopsis Defined in header explicit ctype( std::size_t refs = 0 ); Creates a std::ctype facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::ctype::is,std::ctype::do_is.3 b/man/std::ctype::is,std::ctype::do_is.3 index 9976f758c..25adc4104 100644 --- a/man/std::ctype::is,std::ctype::do_is.3 +++ b/man/std::ctype::is,std::ctype::do_is.3 @@ -1,23 +1,26 @@ -.TH std::ctype::is,std::ctype::do_is 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::is,std::ctype::do_is 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::is,std::ctype::do_is \- std::ctype::is,std::ctype::do_is + .SH Synopsis Defined in header public: \fB(1)\fP - bool is(mask m, CharT c) const; + bool is( mask m, CharT c ) const; public: \fB(2)\fP - const CharT* is(const CharT* low, const CharT* high, mask* vec) const; + const CharT* is( const CharT* low, const CharT* high, mask* vec ) const; protected: \fB(3)\fP - virtual bool do_is(mask m, CharT c) const; + virtual bool do_is( mask m, CharT c ) const; protected: - virtual const CharT* do_is(const CharT* low, const CharT* high, mask* vec) \fB(4)\fP + virtual const CharT* do_is( const CharT* low, const CharT* high, mask* vec ) \fB(4)\fP const; - 1,2) public member function, calls the protected virtual member function do_is of + 1,2) Public member function, calls the protected virtual member function do_is of the most derived class. - 3) Checks if the character c is classified by the mask m + 3) Checks if the character c is classified by the mask m. 4) For every character in the character array [low, high), identifies the complete classification mask (e.g. digit|xdigit|alnum|print|graph for the digit '0' in the default locale), and stores the masks in the corresponding elements of the array - pointed to by vec + pointed to by vec. .SH Parameters @@ -29,19 +32,20 @@ .SH Return value - 1,3) true if c is classified by m + 1,3) true if c is classified by m. 2,4) high .SH Example - + // Run this code + #include + #include #include #include #include - #include - + // utility wrapper to make locale-bound facets destructible template struct deletable_facet : Facet @@ -50,42 +54,44 @@ deletable_facet(Args&& ...args) : Facet(std::forward(args)...) {} ~deletable_facet() {} }; - + int main() { // classify a single character using the default locale auto& f = std::use_facet>(std::locale()); char c = '0'; if (f.is(std::ctype_base::digit, c)) // or isdigit(c, locale()); - { - std::cout << "'" << c << "' is a digit\\n"; - } - + std::cout << '\\'' << c << "' is a digit\\n"; + // classify every character in a string using a named locale deletable_facet> f2("en_US.utf8"); std::wstring str = L"z\\u00df\\u6c34\\U0001d10b"; std::vector vec(str.size()); f2.is(&str[0], &str[0] + str.size(), &vec[0]); - - for (std::size_t n = 0; n < str.size(); ++n) { - std::cout << std::hex << "U+" << str[n] << " is: "; - if (vec[n] & std::ctype_base::alnum) - std::cout << " alnum "; - if (vec[n] & std::ctype_base::punct) - std::cout << " punct "; - std::cout << '\\n'; + + for (std::size_t n = 0; n < str.size(); ++n) + { + std::cout << std::hex << "U+" << static_cast(str[n]) << " is: "; + if (vec[n] & std::ctype_base::alnum) + std::cout << "alnum"; + if (vec[n] & std::ctype_base::punct) + std::cout << "punct"; + std::cout << '\\n'; } } .SH Output: '0' is a digit - U+7a is: alnum - U+df is: alnum - U+6c34 is: alnum - U+1d10b is: punct + U+7a is: alnum + U+df is: alnum + U+6c34 is: alnum + U+1d10b is: punct .SH See also + classifies a character or a character sequence, using the classification + is table + \fI(public member function of std::ctype)\fP iswctype classifies a wide character according to the specified LC_CTYPE category - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::ctype::is.3 b/man/std::ctype::is.3 new file mode 100644 index 000000000..8fbb62914 --- /dev/null +++ b/man/std::ctype::is.3 @@ -0,0 +1,63 @@ +.TH std::ctype::is 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::is \- std::ctype::is + +.SH Synopsis + Defined in header + bool is( mask m, char c ) const; \fB(1)\fP + const char* is( const char* low, const char* high, mask* vec ) const; \fB(2)\fP + + 1) Checks if the character c is classified by the mask m according to the + classification table returned by the member function table(). Effectively calculates + table()[(unsigned char)c] & m. + 2) For every character in the character array [low, high), reads its full + classification mask from the classification table returned by the member function + table() (that is, evaluates table()[(unsigned char)*p] and stores it in the + corresponding element of the array pointed to by vec. + + If (unsigned char)c >= std::ctype::table_size, then an implementation-defined + value is substituted instead of table()[(unsigned char)c], possibly different for + different values of c. + +.SH Parameters + + c - character to classify + m - mask to use for classifying a single character + low - pointer to the first character in an array of characters to classify + high - one past the end pointer for the array of characters to classify + vec - pointer to the first element of the array of masks to fill + +.SH Return value + + 1) true if c is classified by m in table(), false otherwise. + 2) high + +.SH Notes + + Unlike the primary template std::ctype, this specialization does not perform a + virtual function call when classifying characters. To customize the behavior, a + derived class may provide a non-default classification table to the base class + constructor. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload (2) copied the values from vec into + LWG 28 C++98 table(), corrected + which is the reverse of the intended behavior + +.SH See also + + do_is classifies a character or a character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ctype::narrow,do_narrow.3 b/man/std::ctype::narrow,do_narrow.3 index 45c482e59..762cdf25b 100644 --- a/man/std::ctype::narrow,do_narrow.3 +++ b/man/std::ctype::narrow,do_narrow.3 @@ -1,4 +1,7 @@ -.TH std::ctype::narrow,do_narrow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::narrow,do_narrow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::narrow,do_narrow \- std::ctype::narrow,do_narrow + .SH Synopsis Defined in header public: \fB(1)\fP @@ -16,8 +19,9 @@ char dflt, char* dst ) const; - 1,2) Public member function, calls the protected virtual member function do_narrow - of the most derived class. + 1,2) Public member function, calls the corresponding protected virtual member + function do_narrow overload of the most derived class. Overload \fB(1)\fP calls + do_narrow(c, dflt), overload \fB(2)\fP calls do_narrow(beg, end, dflt, dst). 3) Converts the (possibly wide) character c to multibyte representation if the character can be represented with a single byte (for example, ASCII characters in UTF-8 encoding are single bytes). Returns dflt if such conversion does not exist. @@ -26,47 +30,62 @@ array pointed to by dst. Narrowing is always successful and is always reversible (by calling widen()) for all - characters from the basic source character set (latin letters, digits, and - punctuations required to write a C++ program) + characters from the + basic source character set + (until C++23) + basic character set + (since C++23). + + * i.e. do_widen(do_narrow(c, 0)) == c always holds for any character c in the + basic source character set + (until C++23) + basic character set + (since C++23). Narrowing, if successful, preserves all character classification categories known to is(). + * i.e. is(m, c) || !ctc.is(m, do_narrow(c, dflt)) is always true for any named + ctype category with a ctype facet ctc and ctype_base::mask value m (unless + do_narrow returns dflt). + Narrowing of any digit character guarantees that if the result is subtracted from the character literal '0', the difference equals the digit value of the original character. + * i.e. for any digit character c, the expression (do_narrow(c, dflt) - '0') + evaluates to the digit value of the character. + .SH Parameters c - character to convert dflt - default value to produce if the conversion fails beg - pointer to the first character in an array of characters to convert end - one past the end pointer for the array of characters to convert - dst - pointer to the first element of the array of char to fill + dst - pointer to the first element of the array of characters to fill .SH Return value - 1,3) narrowed character or dflt if narrowing fails + 1,3) Narrowed character or dflt if narrowing fails. 2,4) end .SH Example - + // Run this code - #include #include - + #include + void try_narrow(const std::ctype& f, wchar_t c) { char n = f.narrow(c, 0); - if (n) { + if (n) std::wcout << '\\'' << c << "' narrowed to " << +(unsigned char)n << '\\n'; - } else { + else std::wcout << '\\'' << c << "' could not be narrowed\\n"; - } } - + int main() { std::locale::global(std::locale("en_US.utf8")); @@ -76,7 +95,7 @@ try_narrow(f, L'A'); try_narrow(f, L'Ａ'); try_narrow(f, L'ě'); - + std::locale::global(std::locale("cs_CZ.iso88592")); auto& f2 = std::use_facet>(std::locale()); std::wcout << "In Czech ISO-8859-2 locale:\\n"; @@ -85,7 +104,7 @@ try_narrow(f2, L'ě'); } -.SH Output: +.SH Possible output: In US English UTF-8 locale: 'A' narrowed to 0x41 @@ -96,11 +115,27 @@ 'Ａ' could not be narrowed 'ě' narrowed to 0xec + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the code representing reversibility + was + do_widen(do_narrow(c), 0) == c + LWG 126 C++98 2. the code representing category corrected both + preservation was + is(m, c) || !ctc.is(m, do_narrow(c), + dflt) + LWG 153 C++98 narrow always called overload \fB(4)\fP calls the corresponding + overload + .SH See also widen invokes do_widen - \fI(public member function)\fP + \fI(public member function)\fP narrow narrows characters - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP wctob narrows a wide character to a single-byte narrow character, if possible - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::ctype::scan_is,std::ctype::do_scan_is.3 b/man/std::ctype::scan_is,std::ctype::do_scan_is.3 index f45249e7d..b3f514f99 100644 --- a/man/std::ctype::scan_is,std::ctype::do_scan_is.3 +++ b/man/std::ctype::scan_is,std::ctype::do_scan_is.3 @@ -1,13 +1,16 @@ -.TH std::ctype::scan_is,std::ctype::do_scan_is 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::scan_is,std::ctype::do_scan_is 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::scan_is,std::ctype::do_scan_is \- std::ctype::scan_is,std::ctype::do_scan_is + .SH Synopsis Defined in header public: \fB(1)\fP const CharT* scan_is( mask m, const CharT* beg, const CharT* end ) const; protected: - virtual const CharT* do_scan_is( mask m, const CharT* beg, const CharT* end) \fB(2)\fP + virtual const CharT* do_scan_is( mask m, const CharT* beg, const CharT* end ) \fB(2)\fP const; - 1) public member function, calls the protected virtual member function do_scan_is of + 1) Public member function, calls the protected virtual member function do_scan_is of the most derived class. 2) Locates the first character in the character array [beg, end) that satisfies the classification mask m, that is, the first character c such that is(m, c) would @@ -26,35 +29,50 @@ .SH Example - + // Run this code - #include + #include #include #include - + #include + int main() { - auto& f = std::use_facet>(std::locale("")); - + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + auto& f = std::use_facet>(std::wcout.getloc()); + // skip until the first letter - char s1[] = " \\t\\t\\n Test"; - const char* p1 = f.scan_is(std::ctype_base::alpha, std::begin(s1), std::end(s1)); - std::cout << "'" << p1 << "'\\n"; - + wchar_t s1[] = L" \\t\\t\\n Кошка"; + const wchar_t* p1 = f.scan_is(std::ctype_base::alpha, std::begin(s1), std::end(s1)); + std::wcout << '\\'' << p1 << "'\\n"; + // skip until the first letter - char s2[] = "123456789abcd"; - const char* p2 = f.scan_is(std::ctype_base::alpha, std::begin(s2), std::end(s2)); - std::cout << "'" << p2 << "'\\n"; + wchar_t s2[] = L"123456789ネプネプ"; + const wchar_t* p2 = f.scan_is(std::ctype_base::alpha, std::begin(s2), std::end(s2)); + std::wcout << '\\'' << p2 << "'\\n"; } .SH Output: - 'Test' - 'abcd' + 'Кошка' + 'ネプネプ' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 152 C++98 the effect of do_scan_is mentioned is(m), corrected to is(m, c) + but is does not have such an overload .SH See also + locates the first character in a sequence that conforms to given + scan_is classification, using the classification table + \fI(public member function of std::ctype)\fP do_scan_not locates the first character in a sequence that fails given \fB[virtual]\fP classification - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP diff --git a/man/std::ctype::scan_is.3 b/man/std::ctype::scan_is.3 new file mode 100644 index 000000000..262946e70 --- /dev/null +++ b/man/std::ctype::scan_is.3 @@ -0,0 +1,72 @@ +.TH std::ctype::scan_is 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::scan_is \- std::ctype::scan_is + +.SH Synopsis + Defined in header + const char* scan_is( mask m, const char* beg, const char* end ) const; \fB(1)\fP + + Locates the first character in the character array [beg, end) that satisfies the + classification mask m, that is, the first character c such that table()[(unsigned + char) c] & m would return true. + + If (unsigned char)c >= std::ctype::table_size, then an implementation-defined + value is substituted instead of table()[(unsigned char)c], possibly different for + different values of c. + +.SH Parameters + + m - mask to search for + beg - pointer to the first character in an array of characters to search + end - one past the end pointer for the array of characters to search + +.SH Return value + + Pointer to the first character in [beg, end) that satisfies the mask, or end if no + such character was found. + +.SH Notes + + Unlike the primary template std::ctype, this specialization does not perform a + virtual function call when classifying characters. To customize the behavior, a + derived class may provide a non-default classification table to the base class + constructor. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::locale loc(""); + auto& f = std::use_facet>(loc); + + // skip until the first letter + char s1[] = " \\t\\t\\n Test"; + const char* p1 = f.scan_is(std::ctype_base::alpha, std::begin(s1), std::end(s1)); + std::cout << '\\'' << p1 << "'\\n"; + + // skip until the first letter + char s2[] = "123456789abcd"; + const char* p2 = f.scan_is(std::ctype_base::alpha, std::begin(s2), std::end(s2)); + std::cout << '\\'' << p2 << "'\\n"; + } + +.SH Output: + + 'Test' + 'abcd' + +.SH See also + + do_scan_is locates the first character in a sequence that conforms to given + \fB[virtual]\fP classification + \fI(virtual protected member function of std::ctype)\fP + locates the first character in a sequence that fails given + scan_not classification, using the classification table + \fI(public member function)\fP diff --git a/man/std::ctype::scan_not,std::ctype::do_scan_not.3 b/man/std::ctype::scan_not,std::ctype::do_scan_not.3 index 549522b4f..16901128e 100644 --- a/man/std::ctype::scan_not,std::ctype::do_scan_not.3 +++ b/man/std::ctype::scan_not,std::ctype::do_scan_not.3 @@ -1,13 +1,16 @@ -.TH std::ctype::scan_not,std::ctype::do_scan_not 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::scan_not,std::ctype::do_scan_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::scan_not,std::ctype::do_scan_not \- std::ctype::scan_not,std::ctype::do_scan_not + .SH Synopsis Defined in header public: \fB(1)\fP const CharT* scan_not( mask m, const CharT* beg, const CharT* end ) const; protected: - virtual const CharT* do_scan_not( mask m, const CharT* beg, const CharT* end) \fB(2)\fP + virtual const CharT* do_scan_not( mask m, const CharT* beg, const CharT* end ) \fB(2)\fP const; - 1) public member function, calls the protected virtual member function do_scan_not + 1) Public member function, calls the protected virtual member function do_scan_not of the most derived class. 2) Locates the first character in the character array [beg, end) that does not satisfy the classification mask m, that is, the first character c such that is(m, c) @@ -26,35 +29,41 @@ .SH Example - + // Run this code - #include + #include #include #include - + #include + int main() { - auto& f = std::use_facet>(std::locale("")); - + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + auto& f = std::use_facet>(std::wcout.getloc()); + // skip leading whitespace - char s1[] = " \\t\\t\\n Test"; - const char* p1 = f.scan_not(std::ctype_base::space, std::begin(s1), std::end(s1)); - std::cout << "'" << p1 << "'\\n"; - + wchar_t s1[] = L" \\t\\t\\n Кошка"; + const wchar_t* p1 = f.scan_not(std::ctype_base::space, std::begin(s1), std::end(s1)); + std::wcout << '\\'' << p1 << "'\\n"; + // skip leading digits - char s2[] = "123456789abcd"; - const char* p2 = f.scan_not(std::ctype_base::digit, std::begin(s2), std::end(s2)); - std::cout << "'" << p2 << "'\\n"; + wchar_t s2[] = L"123456789ネプネプ"; + const wchar_t* p2 = f.scan_not(std::ctype_base::digit, std::begin(s2), std::end(s2)); + std::wcout << '\\'' << p2 << "'\\n"; } .SH Output: - 'Test' - 'abcd' + 'Кошка' + 'ネプネプ' .SH See also + locates the first character in a sequence that fails given + scan_not classification, using the classification table + \fI(public member function of std::ctype)\fP do_scan_is locates the first character in a sequence that conforms to given \fB[virtual]\fP classification - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP diff --git a/man/std::ctype::scan_not.3 b/man/std::ctype::scan_not.3 new file mode 100644 index 000000000..5839caf94 --- /dev/null +++ b/man/std::ctype::scan_not.3 @@ -0,0 +1,71 @@ +.TH std::ctype::scan_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::scan_not \- std::ctype::scan_not + +.SH Synopsis + Defined in header + const char* scan_not( mask m, const char* beg, const char* end ) const; + + Locates the first character in the character array [beg, end) that does not satisfy + the classification mask m, that is, the first character c such that + table()[(unsigned char)c] & m would return false. + + If (unsigned char)c >= std::ctype::table_size, then an implementation-defined + value is substituted instead of table()[(unsigned char)c], possibly different for + different values of c. + +.SH Parameters + + m - mask to search for + beg - pointer to the first character in an array of characters to search + end - one past the end pointer for the array of characters to search + +.SH Return value + + Pointer to the first character in [beg, end) that does not satisfy the mask, or end + if no such character was found. + +.SH Notes + + Unlike the primary template std::ctype, this specialization does not perform a + virtual function call when classifying characters. To customize the behavior, a + derived class may provide a non-default classification table to the base class + constructor. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto& f = std::use_facet>(std::locale()); + + // skip leading whitespace + char s1[] = " \\t\\t\\n Test"; + const char* p1 = f.scan_not(std::ctype_base::space, std::begin(s1), std::end(s1)); + std::cout << '\\'' << p1 << "'\\n"; + + // skip leading digits + char s2[] = "123456789abcd"; + const char* p2 = f.scan_not(std::ctype_base::digit, std::begin(s2), std::end(s2)); + std::cout << '\\'' << p2 << "'\\n"; + } + +.SH Output: + + 'Test' + 'abcd' + +.SH See also + + do_scan_not locates the first character in a sequence that fails given + \fB[virtual]\fP classification + \fI(virtual protected member function of std::ctype)\fP + locates the first character in a sequence that conforms to given + scan_is classification, using the classification table + \fI(public member function)\fP diff --git a/man/std::ctype::table.3 b/man/std::ctype::table.3 new file mode 100644 index 000000000..d51362de2 --- /dev/null +++ b/man/std::ctype::table.3 @@ -0,0 +1,29 @@ +.TH std::ctype::table 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::table \- std::ctype::table + +.SH Synopsis + Defined in header + const mask* table() const throw(); \fI(until C++11)\fP + const mask* table() const noexcept; \fI(since C++11)\fP + + Returns the classification table that was provided in the constructor of this + instance of std::ctype, or returns a copy of classic_table() if none was + provided. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the first element in the classification table (which an array of size + std::ctype::table_size). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ctype::tolower,std::ctype::do_tolower.3 b/man/std::ctype::tolower,std::ctype::do_tolower.3 index d4a990704..05865bcb8 100644 --- a/man/std::ctype::tolower,std::ctype::do_tolower.3 +++ b/man/std::ctype::tolower,std::ctype::do_tolower.3 @@ -1,8 +1,11 @@ -.TH std::ctype::tolower,std::ctype::do_tolower 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::tolower,std::ctype::do_tolower 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::tolower,std::ctype::do_tolower \- std::ctype::tolower,std::ctype::do_tolower + .SH Synopsis Defined in header public: \fB(1)\fP - CharT tolower( CharT c) const; + CharT tolower( CharT c ) const; public: \fB(2)\fP const CharT* tolower( CharT* beg, const CharT* end ) const; protected: \fB(3)\fP @@ -10,7 +13,7 @@ protected: \fB(4)\fP virtual const CharT* do_tolower( CharT* beg, const CharT* end ) const; - 1,2) public member function, calls the protected virtual member function do_tolower + 1,2) Public member function, calls the protected virtual member function do_tolower of the most derived class. 3) Converts the character c to lower case if a lower case form is defined by this locale. @@ -25,8 +28,8 @@ .SH Return value - 1,3) lower case character or c if no lower case form is listed by this locale. - 2,4) end. + 1,3) Lower case character or c if no lower case form is listed by this locale. + 2,4) end .SH Notes @@ -37,22 +40,21 @@ .SH Example - + // Run this code - #include #include - + #include + void try_lower(const std::ctype& f, wchar_t c) { wchar_t up = f.tolower(c); - if (up != c) { + if (up != c) std::wcout << "Lower case form of \\'" << c << "' is " << up << '\\n'; - } else { + else std::wcout << '\\'' << c << "' has no lower case form\\n"; - } } - + int main() { std::locale::global(std::locale("en_US.utf8")); @@ -62,11 +64,11 @@ try_lower(f, L'Σ'); try_lower(f, L'Ɛ'); try_lower(f, L'Ａ'); - + std::wstring str = L"HELLo, wORLD!"; std::wcout << "Lowercase form of the string '" << str << "' is "; f.tolower(&str[0], &str[0] + str.size()); - std::wcout << "'" << str << "'\\n"; + std::wcout << '\\'' << str << "'\\n"; } .SH Output: @@ -80,8 +82,8 @@ .SH See also toupper invokes do_toupper - \fI(public member function)\fP + \fI(public member function)\fP tolower converts a character to lowercase - \fI(function)\fP + \fI(function)\fP towlower converts a wide character to lowercase - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::ctype::toupper,std::ctype::do_toupper.3 b/man/std::ctype::toupper,std::ctype::do_toupper.3 index dae4df91f..cf8af9cac 100644 --- a/man/std::ctype::toupper,std::ctype::do_toupper.3 +++ b/man/std::ctype::toupper,std::ctype::do_toupper.3 @@ -1,4 +1,7 @@ -.TH std::ctype::toupper,std::ctype::do_toupper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::toupper,std::ctype::do_toupper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::toupper,std::ctype::do_toupper \- std::ctype::toupper,std::ctype::do_toupper + .SH Synopsis Defined in header public: \fB(1)\fP @@ -10,7 +13,7 @@ protected: \fB(4)\fP virtual const CharT* do_toupper( CharT* beg, const CharT* end ) const; - 1,2) public member function, calls the protected virtual member function do_toupper + 1,2) Public member function, calls the protected virtual member function do_toupper of the most derived class. 3) Converts the character c to upper case if an upper case form is defined by this locale. @@ -25,33 +28,32 @@ .SH Return value - 1,3) upper case character or c if no upper case form is listed by this locale. - 2,4) end. + 1,3) Upper case character or c if no upper case form is listed by this locale. + 2,4) end .SH Notes Only 1:1 character mapping can be performed by this function, e.g. the uppercase - form of 'ß' is (with some exceptions) the two-character string "SS", which cannot be - obtained by do_toupper. + form of 'ß' is the two-character string "SS" (with some exceptions - see «Capital + ẞ»), which cannot be obtained by do_toupper. .SH Example - + // Run this code - #include #include - + #include + void try_upper(const std::ctype& f, wchar_t c) { wchar_t up = f.toupper(c); - if (up != c) { + if (up != c) std::wcout << "Upper case form of \\'" << c << "' is " << up << '\\n'; - } else { + else std::wcout << '\\'' << c << "' has no upper case form\\n"; - } } - + int main() { std::locale::global(std::locale("en_US.utf8")); @@ -60,12 +62,14 @@ auto& f = std::use_facet>(std::locale()); try_upper(f, L's'); try_upper(f, L'ſ'); + try_upper(f, L'δ'); + try_upper(f, L'ö'); try_upper(f, L'ß'); - + std::wstring str = L"Hello, World!"; std::wcout << "Uppercase form of the string '" << str << "' is "; f.toupper(&str[0], &str[0] + str.size()); - std::wcout << "'" << str << "'\\n"; + std::wcout << '\\'' << str << "'\\n"; } .SH Output: @@ -73,14 +77,16 @@ In US English UTF-8 locale: Upper case form of 's' is S Upper case form of 'ſ' is S + Upper case form of 'δ' is Δ + Upper case form of 'ö' is Ö 'ß' has no upper case form Uppercase form of the string 'Hello, World!' is 'HELLO, WORLD!' .SH See also tolower invokes do_tolower - \fI(public member function)\fP + \fI(public member function)\fP toupper converts a character to uppercase - \fI(function)\fP + \fI(function)\fP towupper converts a wide character to uppercase - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::ctype::widen,do_widen.3 b/man/std::ctype::widen,do_widen.3 index 0112d8409..3b7b5c378 100644 --- a/man/std::ctype::widen,do_widen.3 +++ b/man/std::ctype::widen,do_widen.3 @@ -1,4 +1,7 @@ -.TH std::ctype::widen,do_widen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::widen,do_widen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::widen,do_widen \- std::ctype::widen,do_widen + .SH Synopsis Defined in header public: \fB(1)\fP @@ -11,8 +14,9 @@ virtual const char* do_widen( const char* beg, const char* end, CharT* dst ) \fB(4)\fP const; - 1,2) public member function, calls the protected virtual member function do_widen of - the most derived class. + 1,2) Public member function, calls the corresponding protected virtual member + function do_widen overload of the most derived class. Overload \fB(1)\fP calls + do_widen(c), overload \fB(2)\fP calls do_widen(beg, end, dst). 3) Converts the single-byte character c to the corresponding wide character representation using the simplest reasonable transformation. Typically, this applies only to the characters whose multibyte encoding is a single byte (e.g. U+0000-U+007F @@ -21,13 +25,16 @@ widened character to the successive locations in the character array pointed to by dst. - Widening always returns a wide character, but only the characters from the basic - source character set (latin letters, digits, and punctuations required to write a - C++ program) are guaranteed to have a unique, well-defined, widening transformation, - which is also guaranteed to be reversible (by narrow()). In practice, all characters - whose multibyte representation is a single byte are usually widened to their wide - character counterparts, and the rest of the possible single-byte values are usually - mapped into the same placeholder value, typically CharT(-1). + Widening always returns a wide character, but only the characters from the + basic source character set + (until C++23) + basic character set + (since C++23) are guaranteed to have a unique, well-defined, widening + transformation, which is also guaranteed to be reversible (by narrow()). In + practice, all characters whose multibyte representation is a single byte are usually + widened to their wide character counterparts, and the rest of the possible + single-byte values are usually mapped into the same placeholder value, typically + CharT(-1). Widening, if successful, preserves all character classification categories known to is(). @@ -38,28 +45,28 @@ dflt - default value to produce if the conversion fails beg - pointer to the first character in an array of characters to convert end - one past the end pointer for the array of characters to convert - dst - pointer to the first element of the array of char to fill + dst - pointer to the first element of the array of characters to fill .SH Return value - 1,3) widened character + 1,3) Widened character. 2,4) end .SH Example - + // Run this code - #include #include - + #include + void try_widen(const std::ctype& f, char c) { wchar_t w = f.widen(c); std::cout << "The single-byte character " << +(unsigned char)c << " widens to " << +w << '\\n'; } - + int main() { std::locale::global(std::locale("cs_CZ.iso88592")); @@ -68,7 +75,7 @@ try_widen(f, 'a'); try_widen(f, '\\xdf'); // German letter ß (U+00df) in ISO-8859-2 try_widen(f, '\\xec'); // Czech letter ě (U+011b) in ISO-8859-2 - + std::locale::global(std::locale("cs_CZ.utf8")); auto& f2 = std::use_facet>(std::locale()); std::cout << "In Czech UTF-8 locale:\\n"; @@ -77,7 +84,7 @@ try_widen(f2, '\\xec'); } -.SH Output: +.SH Possible output: In Czech ISO-8859-2 locale: The single-byte character 0x61 widens to 0x61 @@ -88,11 +95,19 @@ The single-byte character 0xdf widens to 0xffffffff The single-byte character 0xec widens to 0xffffffff + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 153 C++98 widen always called overload \fB(4)\fP calls the corresponding overload + .SH See also narrow invokes do_narrow - \fI(public member function)\fP + \fI(public member function)\fP widen widens characters - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP btowc widens a single-byte narrow character to wide character, if possible - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::ctype::~ctype.3 b/man/std::ctype::~ctype.3 index 13fa44f94..4840f2fb6 100644 --- a/man/std::ctype::~ctype.3 +++ b/man/std::ctype::~ctype.3 @@ -1,4 +1,7 @@ -.TH std::ctype::~ctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype::~ctype 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype::~ctype \- std::ctype::~ctype + .SH Synopsis Defined in header protected: ~ctype(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_ctype : public std::ctype { Destructible_ctype(std::size_t refs = 0) : ctype(refs) {} - ~Destructible_ctype() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_ctype dc; - // std::ctype c; // compile error: protected destructor + // std::ctype c; // compile error: protected destructor } diff --git a/man/std::ctype.3 b/man/std::ctype.3 deleted file mode 100644 index 75bbd8d92..000000000 --- a/man/std::ctype.3 +++ /dev/null @@ -1,175 +0,0 @@ -.TH std::ctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> - class ctype; - - This specialization of std::ctype encapsulates character classification features for - type char. Unlike general-purpose std::ctype, which uses virtual functions, this - specialization uses table lookup to classify characters (which is generally faster). - - The base class std::ctype implements character classification equivalent to - the minimal "C" locale. The classification rules can be extended or modified if - constructed with a non-default classification table argument, if constructed as - std::ctype_byname or as a user-defined derived facet. All std::istream - formatted input functions are required to use std::ctype for character - classing during input parsing. - - std-ctype char-inheritance.svg - About this image - - Inheritance diagram - -.SH Member types - - Member type Definition - char_type char - -.SH Member functions - - constructor constructs a new std::ctype facet - \fI(public member function)\fP - destructor destructs a std::ctype facet - \fI(protected member function)\fP - table obtains the character classification table - \fI(public member function)\fP - classic_table obtains the "C" locale character classification table - \fB[static]\fP \fI(public static member function)\fP - classifies a character or a character sequence, using the - is classification table - \fI(public member function)\fP - locates the first character in a sequence that conforms to given - scan_is classification, using the classification table - \fI(public member function)\fP - locates the first character in a sequence that fails given - scan_not classification, using the classification table - \fI(public member function)\fP - toupper invokes do_toupper - \fI(public member function of std::ctype)\fP - tolower invokes do_tolower - \fI(public member function of std::ctype)\fP - widen invokes do_widen - \fI(public member function of std::ctype)\fP - narrow invokes do_narrow - \fI(public member function of std::ctype)\fP - -.SH Protected member functions - - do_toupper converts a character or characters to uppercase - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_tolower converts a character or characters to lowercase - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_widen converts a character or characters from char to charT - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_narrow converts a character or characters from charT to char - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - -.SH Member objects - - static std::locale::id id id of the locale - \fB[static]\fP \fI(public static member constant)\fP - static const std::size_t table_size size of the classification table, at least 256 - \fB[static]\fP \fI(public static member constant)\fP - -Inherited from std::ctype_base - -.SH Member types - - Type Definition - mask unspecified bitmask type (enumeration, integer type, or bitset) - -.SH Member constants - - space the value of mask identifying whitespace character classification - \fB[static]\fP \fI(public static member constant)\fP - print the value of mask identifying printable character classification - \fB[static]\fP \fI(public static member constant)\fP - cntrl the value of mask identifying control character classification - \fB[static]\fP \fI(public static member constant)\fP - upper the value of mask identifying uppercase character classification - \fB[static]\fP \fI(public static member constant)\fP - lower the value of mask identifying lowercase character classification - \fB[static]\fP \fI(public static member constant)\fP - alpha the value of mask identifying alphabetic character classification - \fB[static]\fP \fI(public static member constant)\fP - digit the value of mask identifying digit character classification - \fB[static]\fP \fI(public static member constant)\fP - punct the value of mask identifying punctuation character classification - \fB[static]\fP \fI(public static member constant)\fP - xdigit the value of mask identifying hexadecimal digit character - \fB[static]\fP classification - \fI(public static member constant)\fP - blank the value of mask identifying blank character classification - \fB[static]\fP \fI(C++11)\fP \fI(public static member constant)\fP - alnum alpha | digit - \fB[static]\fP \fI(public static member constant)\fP - graph alnum | punct - \fB[static]\fP \fI(public static member constant)\fP - -.SH Example - - The following example demonstrates modification of ctype to tokenize - comma-separated values - - -// Run this code - - #include - #include - #include - #include - - // This ctype facet classifies commas and endlines as whitespace - struct csv_whitespace : std::ctype { - static const mask* make_table() - { - // make a copy of the "C" locale table - static std::vector v(classic_table(), classic_table() + table_size); - v[','] |= space; // comma will be classified as whitespace - v[' '] &= ~space; // space will not be classified as whitespace - return &v[0]; - } - csv_whitespace(std::size_t refs = 0) : ctype(make_table(), false, refs) {} - }; - - int main() - { - std::string in = "Column 1,Column 2,Column 3\\n123,456,789"; - std::string token; - - std::cout << "default locale:\\n"; - std::istringstream s1(in); - while(s1 >> token) - std::cout << " " << token << '\\n'; - - std::cout << "locale with modified ctype:\\n"; - std::istringstream s2(in); - s2.imbue(std::locale(s2.getloc(), new csv_whitespace)); - while(s2 >> token) - std::cout << " " << token<< '\\n'; - } - -.SH Output: - - default locale: - Column - 1,Column - 2,Column - 3 - 123,456,789 - locale with modified ctype: - Column 1 - Column 2 - Column 3 - 123 - 456 - 789 - -.SH See also - - ctype defines character classification tables - \fI(class template)\fP - ctype_base defines character classification categories - \fI(class template)\fP - ctype_byname creates a ctype facet for the named locale - \fI(class template)\fP diff --git a/man/std::ctype::classic_table.3 b/man/std::ctype::classic_table.3 deleted file mode 100644 index 73ab41856..000000000 --- a/man/std::ctype::classic_table.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH std::ctype::classic_table 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - static const mask* classic_table(); - - Returns the classification table that matches the classification used by the minimal - "C" locale. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - A pointer to the first element in the classification table (which an array of size - std::ctype::table_size) - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Notes - - Default-constructed std::ctype facets use this table for classification. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::ctype::ctype.3 b/man/std::ctype::ctype.3 deleted file mode 100644 index 8b56c26d0..000000000 --- a/man/std::ctype::ctype.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::ctype::ctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - explicit ctype( const mask* tbl = 0, bool del = false, std::size_t refs = 0); - - Creates a std::ctype facet and forwards the starting reference count refs to - the base class constructor, locale::facet::facet(). - - If tbl is null, classic_table() is used by all classification member functions. - Otherwise, tbl must be a pointer to the first element of an array of masks, at least - std::ctype::table_size in size, and that array is used by all of this facet's - classification member functions. - - If del is true, it is assumed that the array was allocated with new[], and the - destructor of this facet will call delete[] tbl - -.SH Parameters - - tbl - classification table to use or a null pointer - del - indicator whether the table needs to be deleted. - refs - starting reference count - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::ctype::is.3 b/man/std::ctype::is.3 deleted file mode 100644 index 784bf6228..000000000 --- a/man/std::ctype::is.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH std::ctype::is 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - bool is(mask m, char c) const; \fB(1)\fP - const char* is(const char* low, const char* high, mask* vec) const; \fB(2)\fP - - 1) Checks if the character c is classified by the mask m according to the - classification table returned by the member function table(). Effectively calculates - table()[(unsigned char)c] & m - 2) For every character in the character array [low, high), reads its full - classification mask from the classification table returned by the member function - table() (that is, evaluates table()[ (unsigned char)*p] and stores it in the - corresponding element of the array pointed to by vec - - If (unsigned char)c >= std::ctype::table_size, then an implementation-defined - value is substituted instead of table()[(unsigned char)c], possibly different for - different values of c. - -.SH Parameters - - c - character to classify - m - mask to use for classifying a single character - low - pointer to the first character in an array of characters to classify - high - one past the end pointer for the array of characters to classify - vec - pointer to the first element of the array of masks to fill - -.SH Return value - - 1) true if c is classified by m in table() - 2) high - -.SH Notes - - Unlike the primary template std::ctype, this specialization does not perform a - virtual function call when classifying characters. To customize the behavior, a - derived class may provide a non-default classification table to the base class - constructor. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - do_is classifies a character or a character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::ctype::scan_is.3 b/man/std::ctype::scan_is.3 deleted file mode 100644 index 69fcdbad5..000000000 --- a/man/std::ctype::scan_is.3 +++ /dev/null @@ -1,68 +0,0 @@ -.TH std::ctype::scan_is 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - const char* scan_is (mask m, const char* beg, const char* end) const; \fB(1)\fP - - Locates the first character in the character array [beg, end) that satisfies the - classification mask m, that is, the first character c such that table()[(unsigned - char) c] & m would return true. - - If (unsigned char)c >= std::ctype::table_size, then an implementation-defined - value is substituted instead of table()[(unsigned char)c], possibly different for - different values of c. - -.SH Parameters - - m - mask to search for - beg - pointer to the first character in an array of characters to search - end - one past the end pointer for the array of characters to search - -.SH Return value - - Pointer to the first character in [beg, end) that satisfies the mask, or end if no - such character was found. - -.SH Notes - - Unlike the primary template std::ctype, this specialization does not perform a - virtual function call when classifying characters. To customize the behavior, a - derived class may provide a non-default classification table to the base class - constructor. - -.SH Example - - -// Run this code - - #include - #include - #include - - int main() - { - auto& f = std::use_facet>(std::locale("")); - - // skip until the first letter - char s1[] = " \\t\\t\\n Test"; - const char* p1 = f.scan_is(std::ctype_base::alpha, std::begin(s1), std::end(s1)); - std::cout << "'" << p1 << "'\\n"; - - // skip until the first letter - char s2[] = "123456789abcd"; - const char* p2 = f.scan_is(std::ctype_base::alpha, std::begin(s2), std::end(s2)); - std::cout << "'" << p2 << "'\\n"; - } - -.SH Output: - - 'Test' - 'abcd' - -.SH See also - - do_scan_is locates the first character in a sequence that conforms to given - \fB[virtual]\fP classification - \fI(virtual protected member function of std::ctype)\fP - locates the first character in a sequence that fails given - scan_not classification, using the classification table - \fI(public member function)\fP diff --git a/man/std::ctype::table.3 b/man/std::ctype::table.3 deleted file mode 100644 index 043c249b8..000000000 --- a/man/std::ctype::table.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::ctype::table 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - const mask* table() const; \fB(1)\fP - - Returns the classification table that was provided in the constructor of this - instance of std::ctype, or returns a copy of classic_table() if none was - provided. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - A pointer to the first element in the classification table (which an array of size - std::ctype::table_size). - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::ctype::~ctype.3 b/man/std::ctype::~ctype.3 deleted file mode 100644 index f3af89079..000000000 --- a/man/std::ctype::~ctype.3 +++ /dev/null @@ -1,14 +0,0 @@ -.TH std::ctype::~ctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - protected: ~ctype(); - - Destructs a std::ctype facet. This destructor is protected and virtual (due to - base class destructor being virtual). An object of type std::ctype, like most - facets, can only be destroyed when the last std::locale object that implements this - facet goes out of scope or if a user-defined class is derived from std::ctype - and implements a public destructor. - - If, when this instance of std::ctype was constructed, a custom classification - table was provided and the second argument to the constructor (the boolean del) was - true, then this destructor executes delete[] table(). diff --git a/man/std::ctype_base.3 b/man/std::ctype_base.3 index 790adc294..f8a6e3610 100644 --- a/man/std::ctype_base.3 +++ b/man/std::ctype_base.3 @@ -1,4 +1,7 @@ -.TH std::ctype_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype_base \- std::ctype_base + .SH Synopsis Defined in header class ctype_base; @@ -8,6 +11,7 @@ .SH Member types + mask unspecified BitmaskType (enumeration, integer type, or bitset) \fI(typedef)\fP @@ -42,8 +46,8 @@ .SH See also ctype defines character classification tables - \fI(class template)\fP + \fI(class template)\fP ctype specialization of std::ctype for type char - \fI(class template specialization)\fP + \fI(class template specialization)\fP ctype_byname represents the system-supplied std::ctype for the named locale - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::ctype_byname.3 b/man/std::ctype_byname.3 index 38778f76c..581b3e058 100644 --- a/man/std::ctype_byname.3 +++ b/man/std::ctype_byname.3 @@ -1,117 +1,75 @@ -.TH std::ctype_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ctype_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ctype_byname \- std::ctype_byname + .SH Synopsis Defined in header - template< class CharT > - class ctype_byname : public std::ctype; - - std::ctype_byname is a std::ctype facet which encapsulates character classification - rules of the locale specified at its construction. + template<> + class ctype_byname : public std::ctype; - Two specializations are provided by the standard library - - Defined in header - provides narrow character classification. This - std::ctype_byname specialization uses table lookup for character - classification - std::ctype_byname provides wide character classification + This specialization of std::ctype_byname encapsulates character classification + features for type char. Like its base class std::ctype and unlike + general-purpose std::ctype_byname, table lookup is used to classify characters .SH Member types Member type Definition - mask ctype::mask + mask ctype::mask .SH Member functions - constructor constructs a new ctype_byname facet - \fI(public member function)\fP - destructor destroys a ctype_byname facet - \fI(protected member function)\fP - - - - std::ctype_byname::ctype_byname - - explicit ctype_byname( const char* name, std::size_t refs = 0 ); - explicit ctype_byname( const std::string& name, std::size_t refs = 0 \fI(since C++11)\fP - ); - - Constructs a new std::ctype_byname facet for a locale with name. - - refs is used for resource management: if refs == 0, the implementation destroys the - facet, when the last std::locale object holding it is destroyed. Otherwise, the - object is not destroyed. - -.SH Parameters - - name - the name of the locale - refs - the number of references that link to the facet - - - - std::ctype_byname::~ctype_byname + constructor constructs a new ctype_byname facet + \fI(public member function)\fP + destructor destructs a ctype_byname facet + \fI(protected member function)\fP - protected: - ~ctype_byname(); - - Destroys the facet. - -Inherited from std::ctype +Inherited from std::ctype .SH Member types Member type Definition - char_type CharT + char_type char .SH Member objects - Member name Type - static std::locale::id id id of the locale - \fB[static]\fP \fI(public static member constant)\fP - if CharT is char, the following member of std::ctype is inherited - static const std::size_t table_size size of the classification table, at least 256 - \fB[static]\fP \fI(public static member constant)\fP + Member name Type + id (static) std::locale::id + table_size (static const) std::size_t size of the classification table, at least 256 .SH Member functions - is invokes do_is - \fI(public member function of std::ctype)\fP - scan_is invokes do_scan_is - \fI(public member function of std::ctype)\fP - scan_not invokes do_scan_not - \fI(public member function of std::ctype)\fP - toupper invokes do_toupper - \fI(public member function of std::ctype)\fP - tolower invokes do_tolower - \fI(public member function of std::ctype)\fP - widen invokes do_widen - \fI(public member function of std::ctype)\fP - narrow invokes do_narrow - \fI(public member function of std::ctype)\fP - if CharT is char, the following members of std::ctype are inherited - table obtains the character classification table - \fI(public member function of std::ctype)\fP - classic_table obtains the "C" locale character classification table - \fB[static]\fP \fI(public static member function of std::ctype)\fP + table obtains the character classification table + \fI(public member function of std::ctype)\fP + classic_table obtains the "C" locale character classification table + \fB[static]\fP \fI(public static member function of std::ctype)\fP + classifies a character or a character sequence, using the + is classification table + \fI(public member function of std::ctype)\fP + locates the first character in a sequence that conforms to given + scan_is classification, using the classification table + \fI(public member function of std::ctype)\fP + locates the first character in a sequence that fails given + scan_not classification, using the classification table + \fI(public member function of std::ctype)\fP + toupper invokes do_toupper + \fI(public member function of std::ctype)\fP + tolower invokes do_tolower + \fI(public member function of std::ctype)\fP + widen invokes do_widen + \fI(public member function of std::ctype)\fP + narrow invokes do_narrow + \fI(public member function of std::ctype)\fP .SH Protected member functions - do_toupper converts a character or characters to uppercase - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_tolower converts a character or characters to lowercase - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_widen converts a character or characters from char to charT - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_narrow converts a character or characters from charT to char - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - if CharT is char, the following members of std::ctype are NOT inherited - do_is classifies a character or a character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP - do_scan_is locates the first character in a sequence that conforms to given - \fB[virtual]\fP classification - \fI(virtual protected member function of std::ctype)\fP - do_scan_not locates the first character in a sequence that fails given - \fB[virtual]\fP classification - \fI(virtual protected member function of std::ctype)\fP + do_toupper converts a character or characters to uppercase + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + do_tolower converts a character or characters to lowercase + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + do_widen converts a character or characters from char to CharT + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + do_narrow converts a character or characters from CharT to char + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP Inherited from std::ctype_base @@ -148,43 +106,43 @@ Inherited from std::ctype_base graph alnum | punct \fB[static]\fP \fI(public static member constant)\fP -.SH Notes - - The explicit specialization std::ctype_byname was listed as a separate entry - in the header file until C++11. it was removed in C++11 as defect #1298, - but it remains a required specialization, just like std::ctype_byname. - .SH Example - + // Run this code #include #include - + int main() { - wchar_t c = L'\\u00de'; // capital letter thorn - + char c = '\\xde'; // capital letter thorn + std::locale loc("C"); - + std::cout << "isupper('Þ', C locale) returned " << std::boolalpha << std::isupper(c, loc) << '\\n'; - - loc = std::locale(loc, new std::ctype_byname("en_US.utf8")); - - std::cout << "isupper('Þ', C locale with Unicode ctype) returned " + + loc = std::locale(loc, new std::ctype_byname("en_US.utf8")); + + std::cout << "isupper('Þ', C locale with Unicode ctype) returned " + << std::boolalpha << std::isupper(c, loc) << '\\n'; + + loc = std::locale(loc, new std::ctype_byname("is_IS.iso88591")); + + std::cout << "isupper('Þ', C locale with Islandic ctype) returned " << std::boolalpha << std::isupper(c, loc) << '\\n'; } .SH Output: isupper('Þ', C locale) returned false - isupper('Þ', C locale with Unicode ctype) returned true + isupper('Þ', C locale with Unicode ctype) returned false + isupper('Þ', C locale with Islandic ctype) returned true .SH See also ctype defines character classification tables - \fI(class template)\fP + \fI(class template)\fP ctype specialization of std::ctype for type char - \fI(class template specialization)\fP + \fI(class template specialization)\fP diff --git a/man/std::current_exception.3 b/man/std::current_exception.3 index 1628076df..38753813d 100644 --- a/man/std::current_exception.3 +++ b/man/std::current_exception.3 @@ -1,17 +1,21 @@ -.TH std::current_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::current_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::current_exception \- std::current_exception + .SH Synopsis Defined in header - std::exception_ptr current_exception() \fI(since C++11)\fP + std::exception_ptr current_exception() noexcept; \fI(since C++11)\fP If called during exception handling (typically, in a catch clause), captures the current exception object and creates an std::exception_ptr that holds either a copy - or a reference to that exception object (it is implementation-defined if a copy is - made). + or a reference to that exception object (depending on the implementation). The + referenced object remains valid at least as long as there is an exception_ptr object + that refers to it. If the implementation of this function requires a call to new and the call fails, - the returned pointer will hold a reference to an instance of std::bad_alloc + the returned pointer will hold a reference to an instance of std::bad_alloc. - If the implementation of this function requires to copy the captured exception + If the implementation of this function requires copying the captured exception object and its copy constructor throws an exception, the returned pointer will hold a reference to the exception thrown. If the copy constructor of the thrown exception object also throws, the returned pointer may hold a reference to an instance of @@ -20,6 +24,9 @@ If the function is called when no exception is being handled, an empty std::exception_ptr is returned. + This function can be called in a std::terminate_handler to retrieve the exception + which has provoked the invocation of std::terminate. + .SH Parameters \fI(none)\fP @@ -30,54 +37,95 @@ copy of the exception object, or to an instance of std::bad_alloc or to an instance of std::bad_exception. -.SH Exceptions +.SH Notes + + On the implementations that follow Itanium C++ ABI (GCC, Clang, etc), exceptions are + allocated on the heap when thrown (except for std::bad_alloc in some cases), and + this function simply creates the smart pointer referencing the previously-allocated + object, On MSVC, exceptions are allocated on stack when thrown, and this function + performs the heap allocation and copies the exception object. + + On Windows in managed CLR environments [1], the implementation will store a + std::bad_exception when the current exception is a managed exception ([2]). Note + that catch(...) catches also managed exceptions: - noexcept specification: - noexcept - + #include + + int main() + { + try + { + throw gcnew System::Exception("Managed exception"); + } + catch (...) + { + std::exception_ptr ex = std::current_exception(); + try + { + std::rethrow_exception(ex); + } + catch (std::bad_exception const &) + { + // This will be printed. + std::cout << "Bad exception" << std::endl; + } + } + } .SH Example - - + + // Run this code - #include - #include #include + #include #include - + #include + void handle_eptr(std::exception_ptr eptr) // passing by value is ok { - try { - if (eptr != std::exception_ptr()) { + try + { + if (eptr) std::rethrow_exception(eptr); - } - } catch(const std::exception& e) { - std::cout << "Caught exception \\"" << e.what() << "\\"\\n"; + } + catch(const std::exception& e) + { + std::cout << "Caught exception: '" << e.what() << "'\\n"; } } - + int main() { std::exception_ptr eptr; - try { - std::string().at(1); // this generates an std::out_of_range - } catch(...) { + + try + { + std::string().at(1); // this generates a std::out_of_range + } + catch(...) + { eptr = std::current_exception(); // capture } + handle_eptr(eptr); + } // destructor for std::out_of_range called here, when the eptr is destructed -.SH Output: +.SH Possible output: - Caught exception "basic_string::at" + Caught exception: 'basic_string::at: __n (which is 1) >= this->size() (which is 0)' .SH See also - exception_ptr shared pointer type for handling exception objects - \fI(C++11)\fP \fI(typedef)\fP - rethrow_exception throws the exception from an std::exception_ptr - \fI(C++11)\fP \fI(function)\fP - make_exception_ptr creates an std::exception_ptr from an exception object - \fI(C++11)\fP \fI(function template)\fP + exception_ptr shared pointer type for handling exception objects + \fI(C++11)\fP \fI(typedef)\fP + rethrow_exception throws the exception from an std::exception_ptr + \fI(C++11)\fP \fI(function)\fP + make_exception_ptr creates an std::exception_ptr from an exception object + \fI(C++11)\fP \fI(function template)\fP + uncaught_exception + uncaught_exceptions checks if exception handling is currently in progress + (removed in C++20) \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::cv_status.3 b/man/std::cv_status.3 index 2b3fb72b7..881f38013 100644 --- a/man/std::cv_status.3 +++ b/man/std::cv_status.3 @@ -1,12 +1,20 @@ -.TH std::cv_status 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::cv_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cv_status \- std::cv_status + .SH Synopsis Defined in header - enum class cv_status; \fI(since C++11)\fP + enum class cv_status { + + no_timeout, \fI(since C++11)\fP + timeout + + }; The scoped enumeration std::cv_status describes whether a timed wait returned because of timeout or not. - std::cv_status is used by the wait_for and wait_until methods of + std::cv_status is used by the wait_for and wait_until member functions of std::condition_variable and std::condition_variable_any. .SH Member constants @@ -18,15 +26,15 @@ .SH See also - blocks the current thread until the condition variable is woken up or + blocks the current thread until the condition variable is awakened or wait_for after the specified timeout duration - \fI(public member function of std::condition_variable)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function of std::condition_variable)\fP + blocks the current thread until the condition variable is awakened or wait_for after the specified timeout duration - \fI(public member function of std::condition_variable_any)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function of std::condition_variable_any)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function of std::condition_variable)\fP - blocks the current thread until the condition variable is woken up or + \fI(public member function of std::condition_variable)\fP + blocks the current thread until the condition variable is awakened or wait_until until specified time point has been reached - \fI(public member function of std::condition_variable_any)\fP + \fI(public member function of std::condition_variable_any)\fP diff --git a/man/std::cyl_bessel_i,std::cyl_bessel_if,std::cyl_bessel_il.3 b/man/std::cyl_bessel_i,std::cyl_bessel_if,std::cyl_bessel_il.3 new file mode 100644 index 000000000..8003a806d --- /dev/null +++ b/man/std::cyl_bessel_i,std::cyl_bessel_if,std::cyl_bessel_il.3 @@ -0,0 +1,143 @@ +.TH std::cyl_bessel_i,std::cyl_bessel_if,std::cyl_bessel_il 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cyl_bessel_i,std::cyl_bessel_if,std::cyl_bessel_il \- std::cyl_bessel_i,std::cyl_bessel_if,std::cyl_bessel_il + +.SH Synopsis + Defined in header + float cyl_bessel_i ( float nu, float x ); + \fI(since C++17)\fP + double cyl_bessel_i ( double nu, double x ); (until C++23) + + long double cyl_bessel_i ( long double nu, long double x ); + /* floating-point-type */ cyl_bessel_i( /* floating-point-type + */ nu, (since C++23) + /* floating-point-type + */ x ); \fB(1)\fP + float cyl_bessel_if( float nu, float x ); \fB(2)\fP \fI(since C++17)\fP + long double cyl_bessel_il( long double nu, long double x ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + cyl_bessel_i( Arithmetic1 nu, Arithmetic2 x ); + + 1-3) Computes the regular modified cylindrical Bessel function of nu and x. + The library provides overloads of std::cyl_bessel_i for all cv-unqualified + floating-point types as the type of the parameters nu and x. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + nu - the order of the function + x - the argument of the function + +.SH Return value + + If no errors occur, value of the regular modified cylindrical Bessel function of nu + and x, that is I + nu(x) = Σ∞ + k=0 + + (x/2)nu+2k + k!Γ(nu+k+1) + + (for x≥0), is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If nu≥128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::cyl_bessel_i(num1, + num2) has the same effect as std::cyl_bessel_i(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::cyl_bessel_i(num1, num2) has the same effect as (until C++23) + std::cyl_bessel_i(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::cyl_bessel_i(num1, num2) has the same effect as + std::cyl_bessel_i(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::cyl_bessel_i(num1, + num2) has the same effect as std::cyl_bessel_i(static_cast(num1), + static_cast(num2)), where /* common-floating-point-type */ is the + floating-point type with the greatest floating-point conversion rank + and greatest floating-point conversion subrank between the types of (since C++23) + num1 and num2, arguments of integer type are considered to have the + same floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // spot check for nu == 0 + const double x = 1.2345; + std::cout << "I_0(" << x << ") = " << std::cyl_bessel_i(0, x) << '\\n'; + + // series expansion for I_0 + double fct = 1; + double sum = 0; + for (int k = 0; k < 5; fct *= ++k) + { + sum += std::pow(x / 2, 2 * k) / std::pow(fct, 2); + std::cout << "sum = " << sum << '\\n'; + } + } + +.SH Output: + + I_0(1.2345) = 1.41886 + sum = 1 + sum = 1.381 + sum = 1.41729 + sum = 1.41882 + sum = 1.41886 + +.SH See also + + cyl_bessel_j + cyl_bessel_jf + cyl_bessel_jl cylindrical Bessel functions (of the first kind) + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Modified Bessel Function of the First Kind." From MathWorld — A + Wolfram Web Resource. diff --git a/man/std::cyl_bessel_j,std::cyl_bessel_jf,std::cyl_bessel_jl.3 b/man/std::cyl_bessel_j,std::cyl_bessel_jf,std::cyl_bessel_jl.3 new file mode 100644 index 000000000..cb4ce7cb5 --- /dev/null +++ b/man/std::cyl_bessel_j,std::cyl_bessel_jf,std::cyl_bessel_jl.3 @@ -0,0 +1,145 @@ +.TH std::cyl_bessel_j,std::cyl_bessel_jf,std::cyl_bessel_jl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cyl_bessel_j,std::cyl_bessel_jf,std::cyl_bessel_jl \- std::cyl_bessel_j,std::cyl_bessel_jf,std::cyl_bessel_jl + +.SH Synopsis + Defined in header + float cyl_bessel_j ( float nu, float x ); + \fI(since C++17)\fP + double cyl_bessel_j ( double nu, double x ); (until C++23) + + long double cyl_bessel_j ( long double nu, long double x ); + /* floating-point-type */ cy_bessel_j( /* floating-point-type + */ nu, (since C++23) + /* floating-point-type + */ x ); \fB(1)\fP + float cyl_bessel_jf( float nu, float x ); \fB(2)\fP \fI(since C++17)\fP + long double cyl_bessel_jl( long double nu, long double x ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + cyl_bessel_j( Arithmetic1 nu, Arithmetic2 x ); + + 1) Computes the cylindrical Bessel function of the first kind of nu and x. + The library provides overloads of std::cyl_bessel_j for all cv-unqualified + floating-point types as the type of the parameters nu and x. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + nu - the order of the function + x - the argument of the function + +.SH Return value + + If no errors occur, value of the cylindrical Bessel function of the first kind of nu + and x, that is J + nu(x) = Σ∞ + k=0 + + (-1)k + (x/2)nu+2k + k!Γ(nu+k+1) + + (for x≥0), is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling: + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If nu≥128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::cyl_bessel_j(num1, + num2) has the same effect as std::cyl_bessel_j(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::cyl_bessel_j(num1, num2) has the same effect as (until C++23) + std::cyl_bessel_j(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::cyl_bessel_j(num1, num2) has the same effect as + std::cyl_bessel_j(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::cyl_bessel_j(num1, + num2) has the same effect as std::cyl_bessel_j(static_cast(num1), + static_cast(num2)), where /* common-floating-point-type */ is the + floating-point type with the greatest floating-point conversion rank + and greatest floating-point conversion subrank between the types of (since C++23) + num1 and num2, arguments of integer type are considered to have the + same floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // spot check for nu == 0 + const double x = 1.2345; + std::cout << "J_0(" << x << ") = " << std::cyl_bessel_j(0, x) << '\\n'; + + // series expansion for J_0 + double fct = 1; + double sum = 0; + for (int k = 0; k < 6; fct *= ++k) + { + sum += std::pow(-1, k) * std::pow(x / 2, 2 * k) / std::pow(fct, 2); + std::cout << "sum = " << sum << '\\n'; + } + } + +.SH Output: + + J_0(1.2345) = 0.653792 + sum = 1 + sum = 0.619002 + sum = 0.655292 + sum = 0.653756 + sum = 0.653793 + sum = 0.653792 + +.SH See also + + cyl_bessel_i + cyl_bessel_if + cyl_bessel_il regular modified cylindrical Bessel functions + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Bessel Function of the First Kind." From MathWorld — A Wolfram + Web Resource. diff --git a/man/std::cyl_bessel_k,std::cyl_bessel_kf,std::cyl_bessel_kl.3 b/man/std::cyl_bessel_k,std::cyl_bessel_kf,std::cyl_bessel_kl.3 new file mode 100644 index 000000000..0db2b0c7d --- /dev/null +++ b/man/std::cyl_bessel_k,std::cyl_bessel_kf,std::cyl_bessel_kl.3 @@ -0,0 +1,149 @@ +.TH std::cyl_bessel_k,std::cyl_bessel_kf,std::cyl_bessel_kl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cyl_bessel_k,std::cyl_bessel_kf,std::cyl_bessel_kl \- std::cyl_bessel_k,std::cyl_bessel_kf,std::cyl_bessel_kl + +.SH Synopsis + Defined in header + float cyl_bessel_k ( float nu, float x ); + \fI(since C++17)\fP + double cyl_bessel_k ( double nu, double x ); (until C++23) + + long double cyl_bessel_k ( long double nu, long double x ); + /* floating-point-type */ cyl_bessel_k( /* floating-point-type + */ nu, (since C++23) + /* floating-point-type + */ x ); \fB(1)\fP + float cyl_bessel_kf( float nu, float x ); \fB(2)\fP \fI(since C++17)\fP + long double cyl_bessel_kl( long double nu, long double x ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + cyl_bessel_k( Arithmetic1 nu, Arithmetic2 x ); + + 1-3) Computes the irregular modified cylindrical Bessel function (also known as + modified Bessel function of the second kind) of nu and x. + The library provides overloads of std::cyl_bessel_k for all cv-unqualified + floating-point types as the type of the parameters nu and x. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + nu - the order of the function + x - the argument of the function + +.SH Return value + + If no errors occur, value of the irregular modified cylindrical Bessel function + (modified Bessel function of the second kind) of nu and x, is returned, that is K + nu(x) = + + π + 2 + + I + -nu(x)-I + nu(x) + sin(nuπ) + + (where I + nu(x) is std::cyl_bessel_i(nu, x)) for x≥0 and non-integer nu; for integer nu a + limit is used. + +.SH Error handling + + Errors may be reported as specified in math_errhandling: + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If nu≥128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::cyl_bessel_k(num1, + num2) has the same effect as std::cyl_bessel_k(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::cyl_bessel_k(num1, num2) has the same effect as (until C++23) + std::cyl_bessel_k(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::cyl_bessel_k(num1, num2) has the same effect as + std::cyl_bessel_k(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::cyl_bessel_k(num1, + num2) has the same effect as std::cyl_bessel_k(static_cast(num1), + static_cast(num2)), where /* common-floating-point-type */ is the + floating-point type with the greatest floating-point conversion rank + and greatest floating-point conversion subrank between the types of (since C++23) + num1 and num2, arguments of integer type are considered to have the + same floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + double pi = std::numbers::pi; + const double x = 1.2345; + + // spot check for nu == 0.5 + std::cout << "K_.5(" << x << ") = " << std::cyl_bessel_k(.5, x) << '\\n' + << "calculated via I = " + << (pi / 2) * (std::cyl_bessel_i(-.5, x) + - std::cyl_bessel_i(.5, x)) / std::sin(.5 * pi) << '\\n'; + } + +.SH Output: + + K_.5(1.2345) = 0.32823 + calculated via I = 0.32823 + +.SH See also + + cyl_bessel_i + cyl_bessel_if + cyl_bessel_il regular modified cylindrical Bessel functions + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + cyl_bessel_j + cyl_bessel_jf + cyl_bessel_jl cylindrical Bessel functions (of the first kind) + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Modified Bessel Function of the Second Kind." From MathWorld — A + Wolfram Web Resource. diff --git a/man/std::cyl_neumann,std::cyl_neumannf,std::cyl_neumannl.3 b/man/std::cyl_neumann,std::cyl_neumannf,std::cyl_neumannl.3 new file mode 100644 index 000000000..8620f15d4 --- /dev/null +++ b/man/std::cyl_neumann,std::cyl_neumannf,std::cyl_neumannl.3 @@ -0,0 +1,183 @@ +.TH std::cyl_neumann,std::cyl_neumannf,std::cyl_neumannl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::cyl_neumann,std::cyl_neumannf,std::cyl_neumannl \- std::cyl_neumann,std::cyl_neumannf,std::cyl_neumannl + +.SH Synopsis + Defined in header + float cyl_neumann ( float nu, float x ); + \fI(since C++17)\fP + double cyl_neumann ( double nu, double x ); (until C++23) + + long double cyl_neumann ( long double nu, long double x ); + /* floating-point-type */ cyl_neumann( /* floating-point-type + */ nu, (since C++23) + /* floating-point-type + */ x ); \fB(1)\fP + float cyl_neumannf( float nu, float x ); \fB(2)\fP \fI(since C++17)\fP + long double cyl_neumannl( long double nu, long double x ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + cyl_neumann( Arithmetic1 nu, Arithmetic2 x ); + + 1-3) Computes the cylindrical Neumann function (also known as Bessel function of the + second kind or Weber function) of nu and x. + The library provides overloads of std::cyl_neumann for all cv-unqualified + floating-point types as the type of the parameters nu and x. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + nu - the order of the function + x - the argument of the function + +.SH Return value + + If no errors occur, value of the cylindrical Neumann function (Bessel function of + the second kind) of nu and x, is returned, that is N + nu(x) = + + J + nu(x)cos(nuπ)-J + -nu(x) + sin(nuπ) + + (where J + nu(x) is std::cyl_bessel_j(nu, x)) for x≥0 and non-integer nu; for integer nu a + limit is used. + +.SH Error handling + + Errors may be reported as specified in math_errhandling: + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If nu≥128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::cyl_neumann(num1, + num2) has the same effect as std::cyl_neumann(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::cyl_neumann(num1, num2) has the same effect as (until C++23) + std::cyl_neumann(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::cyl_neumann(num1, num2) has the same effect as + std::cyl_neumann(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::cyl_neumann(num1, + num2) has the same effect as std::cyl_neumann(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + const double π = std::numbers::pi; // or std::acos(-1) in pre C++20 + + // To calculate the cylindrical Neumann function via cylindrical Bessel function of the + // first kind we have to implement J, because the direct invocation of the + // std::cyl_bessel_j(nu, x), per formula above, + // for negative nu raises 'std::domain_error': Bad argument in __cyl_bessel_j. + + double J_neg(double nu, double x) + { + return std::cos(-nu * π) * std::cyl_bessel_j(-nu, x) + -std::sin(-nu * π) * std::cyl_neumann(-nu, x); + } + + double J_pos(double nu, double x) + { + return std::cyl_bessel_j(nu, x); + } + + double J(double nu, double x) + { + return nu < 0.0 ? J_neg(nu, x) : J_pos(nu, x); + } + + int main() + { + std::cout << "spot checks for nu == 0.5\\n" << std::fixed << std::showpos; + const double nu = 0.5; + for (double x = 0.0; x <= 2.0; x += 0.333) + { + const double n = std::cyl_neumann(nu, x); + const double j = (J(nu, x) * std::cos(nu * π) - J(-nu, x)) / std::sin(nu * π); + std::cout << "N_.5(" << x << ") = " << n << ", calculated via J = " << j << '\\n'; + assert(n == j); + } + } + +.SH Output: + + spot checks for nu == 0.5 + N_.5(+0.000000) = -inf, calculated via J = -inf + N_.5(+0.333000) = -1.306713, calculated via J = -1.306713 + N_.5(+0.666000) = -0.768760, calculated via J = -0.768760 + N_.5(+0.999000) = -0.431986, calculated via J = -0.431986 + N_.5(+1.332000) = -0.163524, calculated via J = -0.163524 + N_.5(+1.665000) = +0.058165, calculated via J = +0.058165 + N_.5(+1.998000) = +0.233876, calculated via J = +0.233876 + +.SH See also + + cyl_bessel_i + cyl_bessel_if + cyl_bessel_il regular modified cylindrical Bessel functions + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + cyl_bessel_j + cyl_bessel_jf + cyl_bessel_jl cylindrical Bessel functions (of the first kind) + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + cyl_bessel_k + cyl_bessel_kf + cyl_bessel_kl irregular modified cylindrical Bessel functions + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Bessel Function of the Second Kind." From MathWorld — A Wolfram + Web Resource. diff --git a/man/std::data.3 b/man/std::data.3 new file mode 100644 index 000000000..fdda1eae5 --- /dev/null +++ b/man/std::data.3 @@ -0,0 +1,118 @@ +.TH std::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::data \- std::data + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + template< class C > \fB(1)\fP \fI(since C++17)\fP + constexpr auto data( C& c ) -> decltype(c.data()); + template< class C > \fB(2)\fP \fI(since C++17)\fP + constexpr auto data( const C& c ) -> decltype(c.data()); + template< class T, std::size_t N > \fB(3)\fP \fI(since C++17)\fP + constexpr T* data( T (&array)[N] ) noexcept; + template< class E > \fB(4)\fP \fI(since C++17)\fP + constexpr const E* data( std::initializer_list il ) noexcept; + + Returns a pointer to the block of memory containing the elements of the range. + + 1,2) Returns c.data(). + 3) Returns array. + 4) Returns il.begin(). + +.SH Parameters + + c - a container or view with a data() member function + array - an array of arbitrary type + il - an std::initializer_list + +.SH Return value + + 1,2) c.data() + 3) array + 4) il.begin() + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + +.SH Notes + + The overload for std::initializer_list is necessary because it does not have a + member function data. + + Feature-test macro Value Std Feature + __cpp_lib_nonmember_container_access 201411L \fI(C++17)\fP std::size(), std::data(), and + std::empty() + +.SH Possible implementation + +.SH First version + template + constexpr auto data(C& c) -> decltype(c.data()) + { + return c.data(); + } +.SH Second version + template + constexpr auto data(const C& c) -> decltype(c.data()) + { + return c.data(); + } + Third version + template + constexpr T* data(T (&array)[N]) noexcept + { + return array; + } + Fourth version + template + constexpr const E* data(std::initializer_list il) noexcept + { + return il.begin(); + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s{"Hello world!\\n"}; + + char a[20]; // storage for a C-style string + std::strcpy(a, std::data(s)); + // [s.data(), s.data() + s.size()] is guaranteed to be an NTBS since C++11 + + std::cout << a; + } + +.SH Output: + + Hello world! + +.SH See also + + ranges::data obtains a pointer to the beginning of a contiguous range + (C++20) (customization point object) + ranges::cdata obtains a pointer to the beginning of a read-only contiguous range + (C++20) (customization point object) diff --git a/man/std::dec,std::hex,std::oct.3 b/man/std::dec,std::hex,std::oct.3 index 80566690a..ba8b156be 100644 --- a/man/std::dec,std::hex,std::oct.3 +++ b/man/std::dec,std::hex,std::oct.3 @@ -1,22 +1,23 @@ -.TH std::dec,std::hex,std::oct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::dec,std::hex,std::oct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::dec,std::hex,std::oct \- std::dec,std::hex,std::oct + .SH Synopsis Defined in header std::ios_base& dec( std::ios_base& str ); \fB(1)\fP std::ios_base& hex( std::ios_base& str ); \fB(2)\fP std::ios_base& oct( std::ios_base& str ); \fB(3)\fP - Modifies the default numeric base for integer I/O - - 1) sets the basefield of the stream str to dec as if by calling - str.setf(std::ios_base::dec, std::ios_base::basefield) - - 2) sets the basefield of the stream str to hex as if by calling - str.setf(std::ios_base::hex, std::ios_base::basefield) + Modifies the default numeric base for integer I/O. - 3) sets the basefield of the stream str to oct as if by calling - str.setf(std::ios_base::oct, std::ios_base::basefield) + 1) Sets the basefield of the stream str to dec as if by calling + str.setf(std::ios_base::dec, std::ios_base::basefield). + 2) Sets the basefield of the stream str to hex as if by calling + str.setf(std::ios_base::hex, std::ios_base::basefield). + 3) Sets the basefield of the stream str to oct as if by calling + str.setf(std::ios_base::oct, std::ios_base::basefield). - This is an I/O manipulator, it may be called with an expression such as out << + This is an I/O manipulator. It may be called with an expression such as out << std::hex for any out of type std::basic_ostream or with an expression such as in >> std::hex for any in of type std::basic_istream. @@ -26,15 +27,17 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code + #include #include #include + int main() { std::cout << "The number 42 in octal: " << std::oct << 42 << '\\n' @@ -43,6 +46,14 @@ int n; std::istringstream("2A") >> std::hex >> n; std::cout << std::dec << "Parsing \\"2A\\" as hex gives " << n << '\\n'; + // the output base is sticky until changed + std::cout << std::hex << "42 as hex gives " << 42 + << " and 21 as hex gives " << 21 << '\\n'; + + // Note: there is no I/O manipulator that sets up a stream to print out + // numbers in binary format (e.g. bin). If binary output is necessary + // the std::bitset trick can be used: + std::cout << "The number 42 in binary: " << std::bitset<8>{42} << '\\n'; } .SH Output: @@ -51,10 +62,12 @@ The number 42 in decimal: 42 The number 42 in hex: 2a Parsing "2A" as hex gives 42 + 42 as hex gives 2a and 21 as hex gives 15 + The number 42 in binary: 00101010 .SH See also setbase changes the base used for integer I/O - \fI(function)\fP + \fI(function)\fP showbase controls whether prefix is used to indicate numeric base - noshowbase \fI(function)\fP + noshowbase \fI(function)\fP diff --git a/man/std::decay.3 b/man/std::decay.3 index 95ac9cb72..82291f9a0 100644 --- a/man/std::decay.3 +++ b/man/std::decay.3 @@ -1,13 +1,22 @@ -.TH std::decay 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::decay 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::decay \- std::decay + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct decay; - Applies lvalue-to-rvalue, array-to-pointer, and function-to-pointer implicit - conversions to the type T, removes cv-qualifiers, and defines the resulting type as - the member typedef type. This is the type conversion applied to all function - arguments when passed by value. + Performs the type conversions equivalent to the ones performed when passing function + arguments by value. Formally: + + * If T is "array of U" or reference to it, the member typedef type is U*. + * Otherwise, if T is a function type F or reference to one, the member typedef + type is std::add_pointer::type. + * Otherwise, the member typedef type is + std::remove_cv::type>::type. + + If the program adds specializations for std::decay, the behavior is undefined. .SH Member types @@ -21,12 +30,15 @@ .SH Possible implementation - template< class T > - struct decay { + template + struct decay + { + private: typedef typename std::remove_reference::type U; + public: typedef typename std::conditional< std::is_array::value, - typename std::remove_extent::type*, + typename std::add_pointer::type>::type, typename std::conditional< std::is_function::value, typename std::add_pointer::type, @@ -37,38 +49,34 @@ .SH Example - + // Run this code - #include #include - - template - struct decay_equiv : - std::is_same::type>::type - {}; - + + template + constexpr bool is_decay_equ = std::is_same_v, U>; + int main() { - std::cout << std::boolalpha - << decay_equiv::value << '\\n' - << decay_equiv::value << '\\n' - << decay_equiv::value << '\\n' - << decay_equiv::value << '\\n' - << decay_equiv::value << '\\n' - << decay_equiv::value << '\\n'; + static_assert + ( + is_decay_equ && + ! is_decay_equ && + is_decay_equ && + is_decay_equ && + is_decay_equ && + is_decay_equ && + ! is_decay_equ && + ! is_decay_equ && + is_decay_equ && + is_decay_equ + ); } -.SH Output: - - true - true - true - true - true - true - .SH See also - implicit conversion array-to-pointer, function-to-pointer, rvalue-to-lvalue + remove_cvref combines std::remove_cv and std::remove_reference + (C++20) \fI(class template)\fP + implicit conversion array-to-pointer, function-to-pointer, lvalue-to-rvalue conversions diff --git a/man/std::declare_no_pointers.3 b/man/std::declare_no_pointers.3 index 80cd14806..f7e43bca5 100644 --- a/man/std::declare_no_pointers.3 +++ b/man/std::declare_no_pointers.3 @@ -1,7 +1,11 @@ -.TH std::declare_no_pointers 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::declare_no_pointers 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::declare_no_pointers \- std::declare_no_pointers + .SH Synopsis Defined in header - void declare_no_pointers( char *p, std::size_t n ) \fI(since C++11)\fP + void declare_no_pointers( char *p, std::size_t n ); \fI(since C++11)\fP + (removed in C++23) Informs the garbage collector or leak detector that the specified memory region (n bytes beginning at the byte pointed to by p) contains no traceable pointers. If any @@ -19,18 +23,10 @@ .SH Exceptions - None - -.SH Example - - This section is incomplete - Reason: no example + Throws nothing. .SH See also undeclare_no_pointers cancels the effect of std::declare_no_pointers - \fI(C++11)\fP \fI(function)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(function)\fP + (removed in C++23) diff --git a/man/std::declare_reachable.3 b/man/std::declare_reachable.3 index feba1bf70..23dde172b 100644 --- a/man/std::declare_reachable.3 +++ b/man/std::declare_reachable.3 @@ -1,7 +1,11 @@ -.TH std::declare_reachable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::declare_reachable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::declare_reachable \- std::declare_reachable + .SH Synopsis Defined in header - void declare_reachable( void* p ) \fI(since C++11)\fP + void declare_reachable( void* p ); \fI(since C++11)\fP + (removed in C++23) Declares the object referenced by the pointer p reachable. Reachable objects will not be deleted by the garbage collector or considered to be a leak by a leak @@ -23,16 +27,8 @@ May throw std::bad_alloc if the system cannot allocate memory required to track reachable objects. -.SH Example - - This section is incomplete - Reason: no example - .SH See also undeclare_reachable declares that an object can be recycled - \fI(C++11)\fP \fI(function template)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(function template)\fP + (removed in C++23) diff --git a/man/std::declval.3 b/man/std::declval.3 index ea77ecc2b..516f3710c 100644 --- a/man/std::declval.3 +++ b/man/std::declval.3 @@ -1,17 +1,23 @@ -.TH std::declval 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::declval 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::declval \- std::declval + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - typename std::add_rvalue_reference::type declval(); + template< class T > \fI(since C++11)\fP + typename std::add_rvalue_reference::type declval() noexcept; Converts any type T to a reference type, making it possible to use member functions - in decltype expressions without specifying constructors. + in the operand of the decltype specifier without the need to go through + constructors. + + std::declval is commonly used in templates where acceptable template parameters may + have no constructor in common, but have the same member function whose return type + is needed. - declval is commonly used in templates where acceptable template parameters may have - no constructor in common, but have the same member function whose return type is - needed. Note that because no definition exists for declval, it can only be used in - unevaluated contexts; it is an error to evaluate an expression that contains this - function. + Note that std::declval can only be used in unevaluated contexts and is not required + to be defined; it is an error to evaluate an expression that contains this function. + Formally, the program is ill-formed if this function is odr-used. .SH Parameters @@ -20,46 +26,53 @@ .SH Return value Cannot be called and thus never returns a value. The return type is T&& unless T is - an lvalue reference type, in which case the return type is T&. + (possibly cv-qualified) void, in which case the return type is T. -.SH Exceptions +.SH Possible implementation - noexcept specification: - noexcept - + template + typename std::add_rvalue_reference::type declval() noexcept + { + static_assert(false, "declval not allowed in an evaluated context"); + } .SH Example - + // Run this code - #include #include - - struct Default { - int foo() const {return 1;} + #include + + struct Default + { + int foo() const { return 1; } }; - - struct NonDefault { - NonDefault(const NonDefault&) {} - int foo() const {return 1;} + + struct NonDefault + { + NonDefault() = delete; + int foo() const { return 1; } }; - + int main() { - decltype(Default().foo()) n1 = 1; // int n1 - // decltype(NonDefault().foo()) n2 = n1; // will not compile - decltype(std::declval().foo()) n2 = n1; // int n2 - std::cout << "n2 = " << n2 << '\\n'; + decltype(Default().foo()) n1 = 1; // type of n1 is int + // decltype(NonDefault().foo()) n2 = n1; // error: no default constructor + decltype(std::declval().foo()) n2 = n1; // type of n2 is int + std::cout << "n1 = " << n1 << '\\n' + << "n2 = " << n2 << '\\n'; } .SH Output: + n1 = 1 n2 = 1 .SH See also - decltype specifier defines a type equivalent to the type of an expression \fI(C++11)\fP - - result_of deduces the return type of a function call expression - \fI(C++11)\fP \fI(class template)\fP + decltype specifier\fI(C++11)\fP obtains the type of an expression or an entity + result_of deduces the result type of invoking a callable object with + invoke_result a set of arguments + \fI(C++11)\fP(removed in C++20) \fI(class template)\fP + \fI(C++17)\fP diff --git a/man/std::default_accessor.3 b/man/std::default_accessor.3 new file mode 100644 index 000000000..7cce3e3f9 --- /dev/null +++ b/man/std::default_accessor.3 @@ -0,0 +1,68 @@ +.TH std::default_accessor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::default_accessor \- std::default_accessor + +.SH Synopsis + Defined in header + template< class ElementType > (since C++23) + class default_accessor; + + The std::default_accessor class template is the default AccessorPolicy used by + std::mdspan if no user-specified accessor policy is provided. + + Each specialization of default_accessor models semiregular and is TriviallyCopyable. + +.SH Template parameters + + the element type. Shall be a complete object type that is neither an + ElementType - abstract class type nor an array type. Otherwise, the program is + ill-formed + +.SH Member types + + Member type Definition + offset_policy default_accessor + element_type ElementType + reference ElementType& + data_handle_type ElementType* + +.SH Member functions + + constructor constructs a default_accessor + \fI(public member function)\fP + access returns a n^th element provided by arguments + \fI(public member function)\fP + offset returns a data handle that has an offset provided by arguments + \fI(public member function)\fP + +std::default_accessor::default_accessor + + constexpr default_accessor() noexcept = default; \fB(1)\fP + template< class OtherElementType > \fB(2)\fP + constexpr default_accessor( default_accessor ) noexcept {} + + 1) Default constructs a default_accessor. + 2) Constructs a default_accessor from default_accessor. The + constructor has no visible effect. This overload participates in overload resolution + only if std::is_convertible_v is true. + +std::default_accessor::access + + constexpr reference access( data_handle_type p, std::size_t i ) const noexcept; + + Equivalent to return p[i];. + +std::default_accessor::offset + + constexpr data_handle_type offset( data_handle_type p, std::size_t i ) const + noexcept; + + Equivalent to return p + i;. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::default_delete.3 b/man/std::default_delete.3 index aa5b9bed6..cb3bf8101 100644 --- a/man/std::default_delete.3 +++ b/man/std::default_delete.3 @@ -1,50 +1,70 @@ -.TH std::default_delete 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::default_delete 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::default_delete \- std::default_delete + .SH Synopsis Defined in header - template< class T > struct default_delete \fB(1)\fP \fI(since C++11)\fP - template< class T > struct default_delete \fB(2)\fP \fI(since C++11)\fP + template< class T > struct default_delete; \fB(1)\fP \fI(since C++11)\fP + template< class T > struct default_delete; \fB(2)\fP \fI(since C++11)\fP std::default_delete is the default destruction policy used by std::unique_ptr when - no deleter is specified. + no deleter is specified. Specializations of default_delete are empty classes on + typical implementations, and used in the empty base class optimization. 1) The non-specialized default_delete uses delete to deallocate memory for a single object. - 2) A partial specialization for array types that uses delete[] is also provided. .SH Member functions constructor constructs a default_delete object - \fI(public member function)\fP + \fI(public member function)\fP operator() deletes the object or array - \fI(public member function)\fP + \fI(public member function)\fP - std::default_delete::default_delete +std::default_delete::default_delete - constexpr default_delete = default; \fB(1)\fP \fI(since C++11)\fP - template \fB(2)\fP \fI(since C++11)\fP - default_delete( const default_delete& d ); + constexpr default_delete() noexcept = default; \fB(1)\fP + Primary template specializations + template< class U > \fB(2)\fP \fI(since C++11)\fP + default_delete( const default_delete& d ) noexcept; (constexpr since C++23) + Array specializations + template< class U > \fB(3)\fP \fI(since C++11)\fP + default_delete( const default_delete& d ) noexcept; (constexpr since C++23) 1) Constructs a std::default_delete object. - 2) Constructs a std::default_delete object from another std::default_delete object. - This constructor will only participate in overload resolution if U* is implicitly + 2) Constructs a std::default_delete object from another std::default_delete + object. + This overload participates in overload resolution only if U* is implicitly convertible to T*. + 3) Constructs a std::default_delete object from another + std::default_delete object. + This overload participates in overload resolution only if U(*)[] is implicitly + convertible to T(*)[]. .SH Parameters d - a deleter to copy from -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + The converting constructor template of std::default_delete makes possible the + implicit conversion from std::unique_ptr to std::unique_ptr. - std::default_delete::operator() +std::default_delete::operator() - void operator()(T *ptr) const; \fI(since C++11)\fP + Primary template specializations + void operator()( T* ptr ) const; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++23) + Array specializations + template< class U > \fB(2)\fP \fI(since C++11)\fP + void operator()( U* ptr ) const; (constexpr since C++23) - Calls either delete or delete[] on ptr. + 1) Calls delete on ptr. + 2) Calls delete[] on ptr. + This overload participates in overload resolution only if U(*)[] is implicitly + convertible to T(*)[]. + If U is an incomplete type, the program is ill-formed. .SH Parameters @@ -54,42 +74,64 @@ No exception guarantees. + Invoking over Incomplete Types + + At the point in the code the operator() is called, the type must be complete. In + some implementations a static_assert is used to make sure this is the case. The + reason for this requirement is that calling delete on an incomplete type is + undefined behavior in C++ if the complete class type has a nontrivial destructor or + a deallocation function, as the compiler has no way of knowing whether such + functions exist and must be invoked. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_memory 202202L (C++23) constexpr constructor and operator() + .SH Example - + // Run this code + #include #include #include - #include - + int main() { - // { - // std::shared_ptr shared_bad(new int[10]); - // } // the destructor calls delete, undefined behavior - + // { + // std::shared_ptr shared_bad(new int[10]); + // } // the destructor calls delete, undefined behavior + { - std::shared_ptr shared_good(new int[10], std::default_delete - ()); - } // the destructor calls delete[], ok - + std::shared_ptr shared_good(new int[10], std::default_delete()); + } // OK: the destructor calls delete[] + { std::unique_ptr ptr(new int(5)); } // unique_ptr uses default_delete - + { std::unique_ptr ptr(new int[10]); } // unique_ptr uses default_delete - - // default_delete can be used anywhere a delete functor is needed - std::vector v; - for(int n = 0; n < 100; ++n) - v.push_back(new int(n)); - std::for_each(v.begin(), v.end(), std::default_delete()); + + // default_delete can be used anywhere a delete functor is needed + std::vector v; + for (int n = 0; n < 100; ++n) + v.push_back(new int(n)); + std::for_each(v.begin(), v.end(), std::default_delete()); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2118 C++11 member functions of the array specializations accept + rejected qualification conversions + .SH See also unique_ptr smart pointer with unique object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::default_initializable.3 b/man/std::default_initializable.3 new file mode 100644 index 000000000..8f7d97a86 --- /dev/null +++ b/man/std::default_initializable.3 @@ -0,0 +1,42 @@ +.TH std::default_initializable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::default_initializable \- std::default_initializable + +.SH Synopsis + Defined in header + template< class T > + + concept default_initializable = std::constructible_from && \fI(since C++20)\fP + requires { T{}; } && + + /* T t; is well-formed, see below */; + + The default_initializable concept checks whether variables of type T can be + + * value-initialized (T() is well-formed); + * direct-list-initialized from an empty initializer list (T{} is well-formed); and + * default-initialized (T t; is well-formed). + + Access checking is performed as if in a context unrelated to T. Only the validity of + the immediate context of the variable initialization is considered. + +.SH Possible implementation + + template + concept default_initializable = + std::constructible_from && + requires { T{}; } && + requires { ::new T; }; + +.SH See also + + specifies that a variable of the type can be + constructible_from constructed from or bound to a set of argument + (C++20) types + (concept) + is_default_constructible + is_trivially_default_constructible + is_nothrow_default_constructible checks if a type has a default constructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::default_searcher.3 b/man/std::default_searcher.3 new file mode 100644 index 000000000..aa757bebf --- /dev/null +++ b/man/std::default_searcher.3 @@ -0,0 +1,113 @@ +.TH std::default_searcher 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::default_searcher \- std::default_searcher + +.SH Synopsis + Defined in header + template< class ForwardIt, class BinaryPredicate = std::equal_to<> > \fI(since C++17)\fP + class default_searcher; + + A class suitable for use with Searcher overload of std::search that delegates the + search operation to the pre-C++17 standard library's std::search. + + std::default_searcher is CopyConstructible and CopyAssignable. + +.SH Member functions + +std::default_searcher::default_searcher + + default_searcher( ForwardIt pat_first, + \fI(since C++17)\fP + ForwardIt pat_last, \fI(until C++20)\fP + + BinaryPredicate pred = BinaryPredicate() ); + constexpr default_searcher( ForwardIt pat_first, + + ForwardIt pat_last, \fI(since C++20)\fP + + BinaryPredicate pred = BinaryPredicate() + ); + + Constructs a std::default_searcher by storing copies of pat_first, pat_last, and + pred. + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + pred - a callable object used to determine equality + +.SH Exceptions + + Any exceptions thrown by the copy constructors of BinaryPredicate or ForwardIt. + +std::default_searcher::operator() + + template< class ForwardIt2 > + \fI(since C++17)\fP + std::pair \fI(until C++20)\fP + + operator()( ForwardIt2 first, ForwardIt2 last ) const; + template< class ForwardIt2 > + + constexpr std::pair \fI(since C++20)\fP + + operator()( ForwardIt2 first, ForwardIt2 last ) const; + + The member function called by the Searcher overload of std::search to perform a + search with this searcher. + + Returns a pair of iterators i, j, where i is std::search(first, last, pat_first, + pat_last, pred) and j is std::next(i, std::distance(pat_first, pat_last)) unless + std::search returned last (no match), in which case j equals last as well. + +.SH Parameters + + first, last - a pair of iterators designating the string to be examined + +.SH Return value + + A pair of iterators to the first and one past last positions in [first, last) where + a subsequence that compares equal to [pat_first, pat_last) as defined by pred is + located, or a pair of copies of last otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::string_view in = + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed " + "do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + + const std::string_view needle{"pisci"}; + + auto it = std::search(in.begin(), in.end(), + std::default_searcher( + needle.begin(), needle.end())); + if (it != in.end()) + std::cout << "The string " << std::quoted(needle) << " found at offset " + << it - in.begin() << '\\n'; + else + std::cout << "The string " << std::quoted(needle) << " not found\\n"; + } + +.SH Output: + + The string "pisci" found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + boyer_moore_searcher Boyer-Moore search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP + boyer_moore_horspool_searcher Boyer-Moore-Horspool search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::default_sentinel_t,std::default_sentinel.3 b/man/std::default_sentinel_t,std::default_sentinel.3 new file mode 100644 index 000000000..fe372b760 --- /dev/null +++ b/man/std::default_sentinel_t,std::default_sentinel.3 @@ -0,0 +1,46 @@ +.TH std::default_sentinel_t,std::default_sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::default_sentinel_t,std::default_sentinel \- std::default_sentinel_t,std::default_sentinel + +.SH Synopsis + Defined in header + struct default_sentinel_t {}; \fB(1)\fP \fI(since C++20)\fP + inline constexpr default_sentinel_t default_sentinel{}; \fB(2)\fP \fI(since C++20)\fP + + 1) default_sentinel_t is an empty class type used to denote the end of a range. It + can be used together with iterator types that know the bound of their range (e.g., + std::counted_iterator). + 2) default_sentinel is a constant of type default_sentinel_t. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::list l{3, 1, 4, 1, 5, 9, 2, 6}; + + std::ranges::copy(std::counted_iterator(std::begin(l), 4), + std::default_sentinel, std::ostream_iterator{std::cout, " "}); + std::cout << '\\n'; + } + +.SH Output: + + 3 1 4 1 + +.SH See also + + istream_iterator input iterator that reads from std::basic_istream + \fI(class template)\fP + istreambuf_iterator input iterator that reads from std::basic_streambuf + \fI(class template)\fP + counted_iterator iterator adaptor that tracks the distance to the end of the + (C++20) range + \fI(class template)\fP diff --git a/man/std::defer_lock,std::try_to_lock,std::adopt_lock.3 b/man/std::defer_lock,std::try_to_lock,std::adopt_lock.3 index e528c0de9..f6f0f3dd4 100644 --- a/man/std::defer_lock,std::try_to_lock,std::adopt_lock.3 +++ b/man/std::defer_lock,std::try_to_lock,std::adopt_lock.3 @@ -1,14 +1,24 @@ -.TH std::defer_lock,std::try_to_lock,std::adopt_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::defer_lock,std::try_to_lock,std::adopt_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::defer_lock,std::try_to_lock,std::adopt_lock \- std::defer_lock,std::try_to_lock,std::adopt_lock + .SH Synopsis - constexpr std::defer_lock_t defer_lock = std::defer_lock_t(); \fI(since C++11)\fP - constexpr std::try_to_lock_t try_to_lock = std::try_to_lock_t(); \fI(since C++11)\fP - constexpr std::adopt_lock_t adopt_lock = std::adopt_lock_t(); \fI(since C++11)\fP + Defined in header + constexpr std::defer_lock_t defer_lock {}; \fI(since C++11)\fP + \fI(until C++17)\fP + inline constexpr std::defer_lock_t defer_lock {}; \fI(since C++17)\fP + constexpr std::try_to_lock_t try_to_lock {}; \fI(since C++11)\fP + \fI(until C++17)\fP + inline constexpr std::try_to_lock_t try_to_lock {}; \fI(since C++17)\fP + constexpr std::adopt_lock_t adopt_lock {}; \fI(since C++11)\fP + \fI(until C++17)\fP + inline constexpr std::adopt_lock_t adopt_lock {}; \fI(since C++17)\fP std::defer_lock, std::try_to_lock and std::adopt_lock are instances of empty struct tag types std::defer_lock_t, std::try_to_lock_t and std::adopt_lock_t respectively. - They are used to specify locking strategies for std::lock_guard and - std::unique_lock. + They are used to specify locking strategies for std::lock_guard, std::unique_lock + and std::shared_lock. Type Effect(s) defer_lock_t do not acquire ownership of the mutex @@ -17,55 +27,71 @@ .SH Example - - + + // Run this code + #include #include #include - - struct bank_account { - explicit bank_account(int balance) : balance(balance) {} + + struct bank_account + { + explicit bank_account(int balance) : balance{balance} {} int balance; std::mutex m; }; - - void transfer(bank_account &from, bank_account &to, int amount) + + void transfer(bank_account& from, bank_account& to, int amount) { - // attempt to lock both mutexes without deadlock + if (&from == &to) // avoid deadlock in case of self transfer + return; + + // lock both mutexes without deadlock std::lock(from.m, to.m); - - // make sure both already-locked mutexes are unlocked when - // we're done; if we just used the lock_guard without std::lock - // and std::adopt_lock, we might deadlock with other calls to transfer - std::lock_guard lock1(from.m, std::adopt_lock); - std::lock_guard lock2(to.m, std::adopt_lock); - + // make sure both already-locked mutexes are unlocked at the end of scope + std::lock_guard lock1{from.m, std::adopt_lock}; + std::lock_guard lock2{to.m, std::adopt_lock}; + + // equivalent approach: + // std::unique_lock lock1{from.m, std::defer_lock}; + // std::unique_lock lock2{to.m, std::defer_lock}; + // std::lock(lock1, lock2); + from.balance -= amount; to.balance += amount; } - + int main() { - bank_account my_account(100); - bank_account your_account(50); - - std::thread t1(transfer, std::ref(my_account), std::ref(your_account), 10); - std::thread t2(transfer, std::ref(your_account), std::ref(my_account), 5); - + bank_account my_account{100}; + bank_account your_account{50}; + + std::thread t1{transfer, std::ref(my_account), std::ref(your_account), 10}; + std::thread t2{transfer, std::ref(your_account), std::ref(my_account), 5}; + t1.join(); t2.join(); + + std::cout << "my_account.balance = " << my_account.balance << "\\n" + "your_account.balance = " << your_account.balance << '\\n'; } +.SH Output: + + my_account.balance = 95 + your_account.balance = 55 + .SH See also defer_lock_t try_to_lock_t adopt_lock_t tag type used to specify locking strategy - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP \fI(C++11)\fP \fI(C++11)\fP constructor constructs a lock_guard, optionally locking the given mutex - \fI(public member function of std::lock_guard)\fP - constructor constructs a unique_lock, optionally locking the supplied mutex - \fI(public member function of std::unique_lock)\fP + \fI(public member function of std::lock_guard)\fP + constructs a unique_lock, optionally locking (i.e., taking ownership + constructor of) the supplied mutex + \fI(public member function of std::unique_lock)\fP diff --git a/man/std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t.3 b/man/std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t.3 index 18c05b395..f08680216 100644 --- a/man/std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t.3 +++ b/man/std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t.3 @@ -1,12 +1,17 @@ -.TH std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t \- std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t + .SH Synopsis - struct defer_lock_t { }; \fI(since C++11)\fP - struct try_to_lock_t { }; \fI(since C++11)\fP - struct adopt_lock_t { }; \fI(since C++11)\fP + Defined in header + struct defer_lock_t { explicit defer_lock_t() = default; }; + + struct try_to_lock_t { explicit try_to_lock_t() = default; }; \fI(since C++11)\fP + + struct adopt_lock_t { explicit adopt_lock_t() = default; }; - std::defer_lock_t, std::try_to_lock_t and std::adopt_lock_t are empty struct tag - types used to specify locking strategy for std::lock_guard, std::unique_lock and - std::shared_lock. + std::defer_lock_t, std::try_to_lock_t and std::adopt_lock_t are empty class tag + types used to specify locking strategy for std::unique_lock and std::shared_lock. Type Effect(s) defer_lock_t do not acquire ownership of the mutex @@ -15,55 +20,80 @@ .SH Example - - + + // Run this code + #include #include #include - - struct bank_account { - explicit bank_account(int balance) : balance(balance) {} + + struct bank_account + { + explicit bank_account(int balance) : balance{balance} {} int balance; std::mutex m; }; - - void transfer(bank_account &from, bank_account &to, int amount) + + void transfer(bank_account& from, bank_account& to, int amount) { - // attempt to lock both mutexes without deadlock + if (&from == &to) // avoid deadlock in case of self transfer + return; + + // lock both mutexes without deadlock std::lock(from.m, to.m); - - // make sure both already-locked mutexes are unlocked when - // we're done; if we just used the lock_guard without std::lock - // and std::adopt_lock, we might deadlock with other calls to transfer - std::lock_guard lock1(from.m, std::adopt_lock); - std::lock_guard lock2(to.m, std::adopt_lock); - + // make sure both already-locked mutexes are unlocked at the end of scope + std::lock_guard lock1{from.m, std::adopt_lock}; + std::lock_guard lock2{to.m, std::adopt_lock}; + + // equivalent approach: + // std::unique_lock lock1{from.m, std::defer_lock}; + // std::unique_lock lock2{to.m, std::defer_lock}; + // std::lock(lock1, lock2); + from.balance -= amount; to.balance += amount; } - + int main() { - bank_account my_account(100); - bank_account your_account(50); - - std::thread t1(transfer, std::ref(my_account), std::ref(your_account), 10); - std::thread t2(transfer, std::ref(your_account), std::ref(my_account), 5); - + bank_account my_account{100}; + bank_account your_account{50}; + + std::thread t1{transfer, std::ref(my_account), std::ref(your_account), 10}; + std::thread t2{transfer, std::ref(your_account), std::ref(my_account), 5}; + t1.join(); t2.join(); + + std::cout << "my_account.balance = " << my_account.balance << "\\n" + "your_account.balance = " << your_account.balance << '\\n'; } +.SH Output: + + my_account.balance = 95 + your_account.balance = 55 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2510 C++11 the default constructors were non-explicit, made explicit + which could lead to ambiguity + .SH See also defer_lock try_to_lock adopt_lock tag constants used to specify locking strategy - \fI(C++11)\fP (constant) + \fI(C++11)\fP (constant) \fI(C++11)\fP \fI(C++11)\fP constructor constructs a lock_guard, optionally locking the given mutex - \fI(public member function of std::lock_guard)\fP - constructor constructs a unique_lock, optionally locking the supplied mutex - \fI(public member function of std::unique_lock)\fP + \fI(public member function of std::lock_guard)\fP + constructs a unique_lock, optionally locking (i.e., taking ownership + constructor of) the supplied mutex + \fI(public member function of std::unique_lock)\fP diff --git a/man/std::deque.3 b/man/std::deque.3 index dda709487..0bdee36c4 100644 --- a/man/std::deque.3 +++ b/man/std::deque.3 @@ -1,12 +1,22 @@ -.TH std::deque 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque \- std::deque + .SH Synopsis Defined in header template< - class T, + class T, \fB(1)\fP class Allocator = std::allocator > class deque; + namespace pmr { + + template< class T > + using deque = std::deque>; + + } std::deque (double-ended queue) is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end. In addition, insertion and @@ -14,18 +24,23 @@ rest of the elements. As opposed to std::vector, the elements of a deque are not stored contiguously: - typical implementations use a sequence of individually allocated fixed-size arrays. + typical implementations use a sequence of individually allocated fixed-size arrays, + with additional bookkeeping, which means indexed access to deque must perform two + pointer dereferences, compared to vector's indexed access which performs only one. The storage of a deque is automatically expanded and contracted as needed. Expansion of a deque is cheaper than the expansion of a std::vector because it does not - involve copying of the existing elements to a new memory location. + involve copying of the existing elements to a new memory location. On the other + hand, deques typically have large minimal memory cost; a deque holding just one + element has to allocate its full internal array (e.g. 8 times the object size on + 64-bit libstdc++; 16 times the object size or 4096 bytes, whichever is larger, on + 64-bit libc++). The complexity (efficiency) of common operations on deques is as follows: - * Random access - constant O(1) - * Insertion or removal of elements at the end or beginning - amortized constant - O(1) - * Insertion or removal of elements - linear O(n) + * Random access - constant O(1). + * Insertion or removal of elements at the end or beginning - constant O(1). + * Insertion or removal of elements - linear O(n). std::deque meets the requirements of Container, AllocatorAwareContainer, SequenceContainer and ReversibleContainer. @@ -38,108 +53,245 @@ CopyConstructible. The requirements that are imposed on the elements depend T - on the actual operations performed on the container. - Generally, it is required that element type meets the \fI(since C++11)\fP - requirements of MoveConstructible and MoveAssignable, but - many member functions impose stricter requirements. + Generally, it is required that element type is a complete \fI(since C++11)\fP + type and meets the requirements of Erasable, but many + member functions impose stricter requirements. + + + An allocator that is used to acquire/release memory and to + construct/destroy the elements in that memory. The type must meet the + requirements of Allocator. + Allocator - The behavior is undefined + \fI(until C++20)\fP + The program is ill-formed + \fI(since C++20)\fP if Allocator::value_type is not the same as T. + + Iterator invalidation + + This section is incomplete + Reason: There are still a few inaccuracies in this section, refer to individual + member function pages for more detail + + Operations Invalidated + All read only operations. Never. + swap, std::swap The past-the-end iterator may be invalidated + (implementation defined). + shrink_to_fit, clear, insert, + emplace, push_front, Always. + push_back, emplace_front, + emplace_back + If erasing at begin - only erased elements. + + If erasing at end - only erased elements and the + past-the-end iterator. + Otherwise - all iterators are invalidated. - - Allocator - An allocator that is used to acquire memory to store the elements. The - type must meet the requirements of Allocator. + It is unspecified when the past-the-end iterator is + erase invalidated. + \fI(until C++11)\fP + + The past-the-end iterator is also invalidated unless + the erased + elements are at the beginning of the container and the + last element is not erased. + \fI(since C++11)\fP + If the new size is smaller than the old one - only + erased elements and the + past-the-end iterator. + resize + If the new size is bigger than the old one - all + iterators are invalidated. + Otherwise - none iterators are invalidated. + To the element erased. + + The past-the-end iterator + pop_front, pop_back may be invalidated (implementation defined) + \fI(until C++11)\fP + is also invalidated. + \fI(since C++11)\fP + + Invalidation notes + + * When inserting at either end of the deque, references are not invalidated by + insert and emplace. + * push_front, push_back, emplace_front and emplace_back do not invalidate any + references to elements of the deque. + * When erasing at either end of the deque, references to non-erased elements are + not invalidated by erase, pop_front and pop_back. + * A call to resize with a smaller size does not invalidate any references to + non-erased elements. + * A call to resize with a bigger size does not invalidate any references to + elements of the deque. .SH Member types Member type Definition - value_type T - allocator_type Allocator - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP + value_type T + allocator_type Allocator + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator RandomAccessIterator - const_iterator Constant random access iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + + + iterator LegacyRandomAccessIterator to value_type + const_iterator LegacyRandomAccessIterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator .SH Member functions constructor constructs the deque - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the deque - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + assign_range assigns a range of values to the container + (C++23) \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access at access specified element with bounds checking - \fI(public member function)\fP + \fI(public member function)\fP operator[] access specified element - \fI(public member function)\fP + \fI(public member function)\fP front access the first element - \fI(public member function)\fP + \fI(public member function)\fP back access the last element - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP + \fI(C++11)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + \fI(C++11)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP shrink_to_fit reduces memory usage by freeing unused memory - \fI(C++11)\fP \fI(public member function)\fP + (DR*) \fI(public member function)\fP .SH Modifiers clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP erase erases elements - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP - emplace_back constructs elements in-place at the end - \fI(C++11)\fP \fI(public member function)\fP + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP pop_back removes the last element - \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - emplace_front constructs elements in-place at the beginning - \fI(C++11)\fP \fI(public member function)\fP + \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(C++11)\fP \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP pop_front removes the first element - \fI(public member function)\fP + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the deque - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two deques + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::deque) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase(std::deque) erases all elements satisfying specific criteria + erase_if(std::deque) \fI(function template)\fP + (C++20) + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Create a deque containing integers + std::deque d = {7, 5, 16, 8}; + + // Add an integer to the beginning and end of the deque + d.push_front(13); + d.push_back(25); + + // Iterate and print values of deque + for (int n : d) + std::cout << n << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 13 7 5 16 8 25 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was not required to be CopyConstructible T is also required to + LWG 230 C++98 (an element of type T might not be able to be CopyConstructible + be constructed) + +.SH See also + + queue adapts a container to provide queue (FIFO data structure) + \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::deque::append_range.3 b/man/std::deque::append_range.3 new file mode 100644 index 000000000..dc0dfadb1 --- /dev/null +++ b/man/std::deque::append_range.3 @@ -0,0 +1,78 @@ +.TH std::deque::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::append_range \- std::deque::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void append_range( R&& rg ); + + Inserts copies of elements from the range rg before end(), in non-reversing order. + + All iterators (including the end() iterator) are invalidated. No references are + invalidated. + + Each iterator in rg is dereferenced exactly once. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into deque from *ranges::begin(rg). Otherwise, the + behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in size of rg. The number of calls to the constructor of T is exactly equal + to the std::ranges::size(rg)). + +.SH Exceptions + + If an exception is thrown other than by the copy constructor, move constructor, + assignment operator, or move assignment operator of T there are no effects. If an + exception is thrown while inserting a single element at either end, there are no + effects. Otherwise, if an exception is thrown by the move constructor of a + non-CopyInsertable T, the effects are unspecified. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto head = std::deque{1, 2, 3, 4}; + const auto tail = std::list{-5, -6, -7}; + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.insert(head.end(), tail.cbegin(), tail.cend()); + #endif + assert(std::ranges::equal(head, std::deque{1, 2, 3, 4, -5, -6, -7})); + } + +.SH See also + + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::deque::assign.3 b/man/std::deque::assign.3 index 1486e5300..9ad5d4bc3 100644 --- a/man/std::deque::assign.3 +++ b/man/std::deque::assign.3 @@ -1,4 +1,7 @@ -.TH std::deque::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::assign \- std::deque::assign + .SH Synopsis void assign( size_type count, const T& value ); \fB(1)\fP template< class InputIt > \fB(2)\fP @@ -7,58 +10,73 @@ Replaces the contents of the container. - 1) Replaces the contents with count copies of value value - 2) Replaces the contents with copies of those in the range [first, last) + 1) Replaces the contents with count copies of value value. + 2) Replaces the contents with copies of those in the range [first, last). The + behavior is undefined if either argument is an iterator into *this. + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + 3) Replaces the contents with the elements from the initializer list ilist. + All iterators, pointers and references to the elements of the container are + invalidated. The past-the-end iterator is also invalidated. + .SH Parameters count - the new size of the container value - the value to initialize elements of the container with first, last - the range to copy the elements from ilist - initializer list to copy the values from -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. .SH Complexity - 1) Linear in count - 2) Linear in distance between first and last - 3) Linear in ilist.size() + 1) Linear in count. + 2) Linear in distance between first and last. + 3) Linear in ilist.size(). .SH Example The following code uses assign to add several characters to a std::deque: - + // Run this code #include #include - + #include + int main() { std::deque characters; - + + auto print_deque = [&]() + { + for (char c : characters) + std::cout << c << ' '; + std::cout << '\\n'; + }; + characters.assign(5, 'a'); - - for (char c : characters) { - std::cout << c << '\\n'; - } - - return 0; + print_deque(); + + const std::string extra(6, 'b'); + characters.assign(extra.begin(), extra.end()); + print_deque(); + + characters.assign({'C', '+', '+', '1', '1'}); + print_deque(); } .SH Output: - a - a - a - a - a + a a a a a + b b b b b b + C + + 1 1 .SH See also constructor constructs the deque - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::assign_range.3 b/man/std::deque::assign_range.3 new file mode 100644 index 000000000..132ba8a31 --- /dev/null +++ b/man/std::deque::assign_range.3 @@ -0,0 +1,70 @@ +.TH std::deque::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::assign_range \- std::deque::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void assign_range( R&& rg ); + + Replaces elements in the container with a copy of each element in rg. + + All iterators (including the end() iterator) and all references to the elements are + invalidated. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + rg - an input_range with reference type convertible to the element type + of the container +.SH Type requirements + - + std::assignable_from> must be modeled. Otherwise, + the program is ill-formed. + - + T must be EmplaceConstructible into the container from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto source = std::list{2, 7, 1}; + auto destination = std::deque{3, 1, 4}; + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.cbegin(), source.cend()); + #endif + assert(std::ranges::equal(source, destination)); + } + +.SH See also + + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP + assign assigns values to the container + \fI(public member function)\fP diff --git a/man/std::deque::at.3 b/man/std::deque::at.3 index 1e398d274..ba5d7a0bf 100644 --- a/man/std::deque::at.3 +++ b/man/std::deque::at.3 @@ -1,12 +1,15 @@ -.TH std::deque::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::at \- std::deque::at + .SH Synopsis - reference at( size_type pos ); - const_reference at( size_type pos ) const; + reference at( size_type pos ); \fB(1)\fP + const_reference at( size_type pos ) const; \fB(2)\fP Returns a reference to the element at specified location pos, with bounds checking. - If pos not within the range of the container, an exception of type std::out_of_range - is thrown. + If pos is not within the range of the container, an exception of type + std::out_of_range is thrown. .SH Parameters @@ -18,13 +21,66 @@ .SH Exceptions - std::out_of_range if !(pos < size()). + std::out_of_range if pos >= size(). .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + #ifdef __GNUG__ + [[gnu::noinline]] + #endif + unsigned int runtime_six() // Emulate runtime input + { + return 6u; + } + + int main() + { + std::deque data = {1, 2, 4, 5, 5, 6}; + + // Set element 1 + data.at(1) = 88; + + // Read element 2 + std::cout << "Element at index 2 has value " << data.at(2) << '\\n'; + + std::cout << "data size = " << data.size() << '\\n'; + + try + { + // Set element 6, where the index is determined at runtime + data.at(runtime_six()) = 666; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + + // Print final values + std::cout << "data:"; + for (int elem : data) + std::cout << ' ' << elem; + std::cout << '\\n'; + } + +.SH Possible output: + + Element at index 2 has value 4 + data size = 6 + deque::_M_range_check: __n (which is 6)>= this->size() (which is 6) + data: 1 88 4 5 5 6 + .SH See also operator[] access specified element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::back.3 b/man/std::deque::back.3 index 50e1acd25..30e6d6ff0 100644 --- a/man/std::deque::back.3 +++ b/man/std::deque::back.3 @@ -1,11 +1,14 @@ -.TH std::deque::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::back \- std::deque::back + .SH Synopsis - reference back(); - const_reference back() const; + reference back(); \fB(1)\fP + const_reference back() const; \fB(2)\fP - Returns reference to the last element in the container. + Returns a reference to the last element in the container. - Calling back on an empty container is undefined. + Calling back on an empty container causes undefined behavior. .SH Parameters @@ -21,32 +24,32 @@ .SH Notes - For a container c, the expression return c.back(); is equivalent to { auto tmp = - c.end(); --tmp; return *tmp; } + For a non-empty container c, the expression c.back() is equivalent to + *std::prev(c.end()). .SH Example The following code uses back to display the last element of a std::deque: - + // Run this code #include #include - + int main() { - std::deque letters {'o', 'm', 'g', 'w', 't', 'f'}; - if (!letters.empty()) { - std::cout << "The last character is: " << letters.back() << '\\n'; - } + std::deque letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The last character is '" << letters.back() << "'.\\n"; } .SH Output: - The last character is f + The last character is 'f'. .SH See also front access the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::begin,std::deque::cbegin.3 b/man/std::deque::begin,std::deque::cbegin.3 index 335ed0211..48282cf83 100644 --- a/man/std::deque::begin,std::deque::cbegin.3 +++ b/man/std::deque::begin,std::deque::cbegin.3 @@ -1,12 +1,15 @@ -.TH std::deque::begin,std::deque::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::begin,std::deque::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::begin,std::deque::cbegin \- std::deque::begin,std::deque::cbegin + .SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin(); \fB(1)\fP (noexcept since C++11) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the deque. - If the container is empty, the returned iterator will be equal to end(). + If the deque is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,20 +19,62 @@ .SH Return value - Iterator to the first element + Iterator to the first element. + +.SH Complexity -.SH Exceptions + Constant. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +.SH Notes -.SH Complexity + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::deque nums{1, 2, 4, 8, 16}; + std::deque fruits{"orange", "apple", "raspberry"}; + std::deque empty; + + // Print deque. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the deque nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the deque fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "deque 'empty' is indeed empty.\\n"; + } + +.SH Output: - Constant + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + deque 'empty' is indeed empty. .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::deque::clear.3 b/man/std::deque::clear.3 index 3dd6add2e..ad3431550 100644 --- a/man/std::deque::clear.3 +++ b/man/std::deque::clear.3 @@ -1,11 +1,14 @@ -.TH std::deque::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::clear \- std::deque::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterators are also invalidated. .SH Parameters @@ -15,22 +18,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::deque& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::deque container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + + Defect reports - Linear in the size of the container. + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - clear is defined in terms of erase, which has linear complexity. \fI(until C++11)\fP - complexity of clear is omitted \fI(since C++11)\fP - clear has linear complexity for sequence containers. \fI(since C++14)\fP + DR Applied to Behavior as published Correct behavior + LWG 2231 C++11 complexity guarantee was mistakenly complexity reaffirmed as + omitted in C++11 linear .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::deque.3 b/man/std::deque::deque.3 index ebd4dd5ae..681c5f286 100644 --- a/man/std::deque::deque.3 +++ b/man/std::deque::deque.3 @@ -1,131 +1,203 @@ -.TH std::deque::deque 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::deque 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::deque \- std::deque::deque + .SH Synopsis - explicit deque( const Allocator& alloc = Allocator() (until - ); C++14) - deque : deque( Allocator() ) {} (since - explicit deque( const Allocator& alloc ); C++14) + deque(); \fB(1)\fP + explicit deque( const Allocator& alloc ); \fB(2)\fP explicit deque( size_type count, - const T& value = T(), (until - C++11) + const T& value = T(), \fI(until C++11)\fP + const Allocator& alloc = - Allocator()); + Allocator() ); deque( size_type count, - const T& value, (since - C++11) - const Allocator& alloc = - Allocator()); - (since - explicit deque( size_type count ); \fB(1)\fP C++11) - (until - \fB(2)\fP C++14) - explicit deque( size_type count, const Allocator& (since - alloc = Allocator() ); C++14) - template< class InputIt > - - deque( InputIt first, InputIt last, \fB(4)\fP - \fB(3)\fP + const T& value, \fI(since C++11)\fP + + const Allocator& alloc = Allocator() ); + explicit deque( size_type count ); \fI(since C++11)\fP + \fI(until C++14)\fP + explicit deque( size_type count, + const Allocator& alloc = \fI(since C++14)\fP + Allocator() ); + template< class InputIt > \fB(3)\fP + + deque( InputIt first, InputIt last, \fB(5)\fP + const Allocator& alloc = Allocator() ); - deque( const deque& other ); \fB(5)\fP - deque( const deque& other, const Allocator& alloc ); \fB(5)\fP (since - C++11) - deque( deque&& other ) \fB(6)\fP (since - C++11) - deque( deque&& other, const Allocator& alloc ); \fB(6)\fP (since - C++11) - deque( std::initializer_list init, \fB(7)\fP (since - const Allocator& alloc = Allocator() ); C++11) - - Constructs new container from a variety of data sources and optionally using user + deque( const deque& other ); \fB(4)\fP \fB(6)\fP + deque( const deque& other, const Allocator& \fB(7)\fP \fI(since C++11)\fP + alloc ); + deque( deque&& other ); \fB(8)\fP \fI(since C++11)\fP + deque( deque&& other, const Allocator& alloc ); \fB(9)\fP \fI(since C++11)\fP + deque( std::initializer_list init, \fB(10)\fP \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); + template< container-compatible-range R > + + deque( std::from_range_t, R&& rg, \fB(11)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + + Constructs a new container from a variety of data sources, optionally using a user supplied allocator alloc. - 1) Default constructor. Constructs empty container. - 2) Constructs the container with count copies of elements with value value. - 3) Constructs the container with count value-initialized (default constructed, for - classes) instances of T. No copies are made. - 4) Constructs the container with the contents of the range [first, last). - 5) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_container_copy_construction(other). - 6) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 7) Constructs the container with the contents of the initializer list init. + 1) Default constructor. Constructs an empty container with a default-constructed + allocator. + 2) Constructs an empty container with the given allocator alloc. + 3) Constructs the container with count copies of elements with value value. + 4) Constructs the container with count default-inserted instances of T. No copies + are made. + 5) Constructs the container with the contents of the range [first, last). + + This constructor has the same effect as + deque(static_cast(first), static_cast(last), a) \fI(until C++11)\fP + if InputIt is an integral type. + This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator, to avoid ambiguity with the overload \fI(since C++11)\fP + \fB(3)\fP. + + 6) Copy constructor. Constructs the container with the copy of the contents of + other. + + The allocator is obtained as if by calling (since + std::allocator_traits::select_on_container_copy_construction( C++11) + other.get_allocator()). + + 7) Constructs the container with the copy of the contents of other, using alloc as + the allocator. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 8) Move constructor. Constructs the container with the contents of other using move + semantics. Allocator is obtained by move-construction from the allocator belonging + to other. + 9) Allocator-extended move constructor. Using alloc as the allocator for the new + container, moving the contents from other; if alloc != other.get_allocator(), this + results in an element-wise move. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 10) Constructs the container with the contents of the initializer list init. + 11) Constructs the container with the contents of the range rg. .SH Parameters alloc - allocator to use for all memory allocations of this container count - the size of the container value - the value to initialize elements of the container with - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with -.SH Type requirements - - - Allocator must meet the requirements of Allocator. - - - InputIt must meet the requirements of InputIterator. + rg - a container compatible range, that is, an input_range whose elements + are convertible to T .SH Complexity - 1) Constant - 2-3) Linear in count - 4) Linear in distance between first and last - 5) Linear in size of other - 6) Constant. If alloc is given and alloc != other.get_allocator(), then linear. - 7) Linear in size of init + 1,2) Constant. + 3,4) Linear in count. + 5) Linear in distance between first and last. + 6,7) Linear in size of other. + 8) Constant. + 9) Linear if alloc != other.get_allocator(), otherwise constant. + 10) Linear in size of init. + 11) Linear in ranges::distance(rg). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload \fB(8)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(11)\fP .SH Example - + // Run this code - #include - #include #include - + #include + #include + template - std::ostream& operator<<(std::ostream& s, const std::deque& v) { - s.put('['); - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& e : v) { - s << comma << e; - comma[0] = ','; - } - return s << ']'; + std::ostream& operator<<(std::ostream& s, const std::deque& v) + { + s.put('{'); + for (char comma[]{'\\0', ' ', '\\0'}; const auto& e : v) + s << comma << e, comma[0] = ','; + return s << "}\\n"; } - + int main() { - // c++11 initializer list syntax: - std::deque words1 {"the", "frogurt", "is", "also", "cursed"}; - std::cout << "words1: " << words1 << '\\n'; - + // C++11 initializer list syntax: + std::deque words1{"the", "frogurt", "is", "also", "cursed"}; + std::cout << "1: " << words1; + // words2 == words1 std::deque words2(words1.begin(), words1.end()); - std::cout << "words2: " << words2 << '\\n'; - + std::cout << "2: " << words2; + // words3 == words1 std::deque words3(words1); - std::cout << "words3: " << words3 << '\\n'; - + std::cout << "3: " << words3; + // words4 is {"Mo", "Mo", "Mo", "Mo", "Mo"} std::deque words4(5, "Mo"); - std::cout << "words4: " << words4 << '\\n'; + std::cout << "4: " << words4; + + auto const rg = {"cat", "cow", "crow"}; + #ifdef __cpp_lib_containers_ranges + std::deque words5(std::from_range, rg); // overload (11) + #else + std::deque words5(rg.begin(), rg.end()); // overload (5) + #endif + std::cout << "5: " << words5; } .SH Output: - words1: [the, frogurt, is, also, cursed] - words2: [the, frogurt, is, also, cursed] - words3: [the, frogurt, is, also, cursed] - words4: [Mo, Mo, Mo, Mo, Mo] + 1: {the, frogurt, is, also, cursed} + 2: {the, frogurt, is, also, cursed} + 3: {the, frogurt, is, also, cursed} + 4: {Mo, Mo, Mo, Mo, Mo} + 5: {cat, cow, crow} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the complexity requirement of + LWG 144 C++98 overload \fB(5)\fP was the same changed to linear complexity + as that of the corresponding + overload of std::vector + the complexity requirement of changed to linear in + LWG 237 C++98 overload std::distance(first, last) + \fB(5)\fP was linear in first - last + for overload \fB(4)\fP, the elements in + LWG 868 C++98 the container were default they are value-initialized + constructed + LWG 2193 C++11 the default constructor is explicit made non-explicit .SH See also assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::emplace.3 b/man/std::deque::emplace.3 index cc1203064..a06db14a2 100644 --- a/man/std::deque::emplace.3 +++ b/man/std::deque::emplace.3 @@ -1,21 +1,35 @@ -.TH std::deque::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::emplace \- std::deque::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace( const_iterator pos, Args&&... args ); - Inserts a new element into the container directly before pos. The element is - constructed in-place, i.e. no copy or move operations are performed. The constructor - of the element is called with the arguments std::forward(args).... The element - type must be EmplaceConstructible, MoveInsertable and MoveAssignable. + Inserts a new element into the container directly before pos. + + The element is constructed through std::allocator_traits::construct, which typically + uses placement-new to construct the element in-place at a location provided by the + container. However, if the required location has been occupied by an existing + element, the inserted element is constructed at another location at first, and then + move assigned into the required location. - All iterators, including the past-the-end iterator, are invalidated. References are + The arguments args... are forwarded to the constructor as + std::forward(args).... args... may directly or indirectly refer to a value in + the container. + + All iterators (including the end() iterator) are invalidated. References are invalidated too, unless pos == begin() or pos == end(), in which case they are not invalidated. .SH Parameters - pos - iterator before which the new element will be constructed - args - arguments to forward to the constructor of the element + pos - iterator before which the new element will be constructed + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of MoveAssignable, + MoveInsertable and EmplaceConstructible. .SH Return value @@ -28,10 +42,96 @@ .SH Exceptions - If an exception is thrown (e.g. by the constructor), the container is left - unmodified, as if this function was never called \fI(strong exception guarantee)\fP. + If an exception is thrown other than by the copy constructor, move constructor, + assignment operator, or move assignment operator of the value type, or if an + exception is thrown while emplace is used to insert a single element at the either + end, there are no effects \fI(strong exception guarantee)\fP. + + Otherwise, the effects are unspecified. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct A + { + std::string s; + + A(std::string str) : s(std::move(str)) { std::cout << " constructed\\n"; } + + A(const A& o) : s(o.s) { std::cout << " copy constructed\\n"; } + + A(A&& o) : s(std::move(o.s)) { std::cout << " move constructed\\n"; } + + A& operator=(const A& other) + { + s = other.s; + std::cout << " copy assigned\\n"; + return *this; + } + + A& operator=(A&& other) + { + s = std::move(other.s); + std::cout << " move assigned\\n"; + return *this; + } + }; + + int main() + { + std::deque container; + + std::cout << "construct 2 times A:\\n"; + A two { "two" }; + A three { "three" }; + + std::cout << "emplace:\\n"; + container.emplace(container.end(), "one"); + + std::cout << "emplace with A&:\\n"; + container.emplace(container.end(), two); + + std::cout << "emplace with A&&:\\n"; + container.emplace(container.end(), std::move(three)); + + std::cout << "content:\\n"; + for (const auto& obj : container) + std::cout << ' ' << obj.s; + std::cout << '\\n'; + } + +.SH Output: + + construct 2 times A: + constructed + constructed + emplace: + constructed + emplace with A&: + copy constructed + emplace with A&&: + move constructed + content: + one two three + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2164 C++11 it was not clear whether the arguments can clarified + refer to the container .SH See also - insert inserts elements - \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::deque::emplace_back.3 b/man/std::deque::emplace_back.3 index 9c87d5b40..ca0693c3c 100644 --- a/man/std::deque::emplace_back.3 +++ b/man/std::deque::emplace_back.3 @@ -1,22 +1,32 @@ -.TH std::deque::emplace_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::emplace_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::emplace_back \- std::deque::emplace_back + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace_back( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace_back( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + reference emplace_back( Args&&... args ); Appends a new element to the end of the container. The element is constructed - in-place, i.e. no copy or move operations are performed. The constructor of the - element is called with exactly the same arguments that are supplied to the function. + through std::allocator_traits::construct, which typically uses placement-new to + construct the element in-place at the location provided by the container. The + arguments args... are forwarded to the constructor as std::forward(args).... - All iterators, including the past-the-end iterator, are invalidated. No references - are invalidated. + All iterators (including the end() iterator) are invalidated. No references are + invalidated. .SH Parameters - args - arguments to forward to the constructor of the element + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of EmplaceConstructible. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + A reference to the inserted element. \fI(since C++17)\fP .SH Complexity @@ -33,67 +43,72 @@ constructor and shows how using emplace_back avoids the extra copy or move operation required when using push_back. - + // Run this code #include - #include + #include #include - + #include + struct President { std::string name; std::string country; int year; - + President(std::string p_name, std::string p_country, int p_year) : name(std::move(p_name)), country(std::move(p_country)), year(p_year) { std::cout << "I am being constructed.\\n"; } + President(President&& other) : name(std::move(other.name)), country(std::move(other.country)), year(other.year) { std::cout << "I am being moved.\\n"; } + President& operator=(const President& other) = default; }; - + int main() { std::deque elections; std::cout << "emplace_back:\\n"; - elections.emplace_back("Nelson Mandela", "South Africa", 1994); - + auto& ref = elections.emplace_back("Nelson Mandela", "South Africa", 1994); + assert(ref.year == 1994 && "uses a reference to the created object \fI(C++17)\fP"); + std::deque reElections; std::cout << "\\npush_back:\\n"; reElections.push_back(President("Franklin Delano Roosevelt", "the USA", 1936)); - + std::cout << "\\nContents:\\n"; - for (President const& president: elections) { + for (President const& president: elections) std::cout << president.name << " was elected president of " << president.country << " in " << president.year << ".\\n"; - } - for (President const& president: reElections) { + + for (President const& president: reElections) std::cout << president.name << " was re-elected president of " << president.country << " in " << president.year << ".\\n"; - } } .SH Output: emplace_back: I am being constructed. - + push_back: I am being constructed. I am being moved. - + .SH Contents: Nelson Mandela was elected president of South Africa in 1994. Franklin Delano Roosevelt was re-elected president of the USA in 1936. .SH See also - push_back adds elements to the end - \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::deque::emplace_front.3 b/man/std::deque::emplace_front.3 index 0afeaa5b8..d2aa116f6 100644 --- a/man/std::deque::emplace_front.3 +++ b/man/std::deque::emplace_front.3 @@ -1,25 +1,43 @@ -.TH std::deque::emplace_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::emplace_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::emplace_front \- std::deque::emplace_front + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace_front( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace_front( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + reference emplace_front( Args&&... args ); Inserts a new element to the beginning of the container. The element is constructed - in-place, i.e. no copy or move operations are performed. The constructor of the - element is called with exactly the same arguments, as supplied to the function. + through std::allocator_traits::construct, which typically uses placement-new to + construct the element in-place at the location provided by the container. The + arguments args... are forwarded to the constructor as std::forward(args).... + + All iterators (including the end() iterator) are invalidated. No references are + invalidated. .SH Parameters - args - arguments to forward to the constructor of the element + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of EmplaceConstructible. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + A reference to the inserted element. \fI(since C++17)\fP .SH Complexity Constant. +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + .SH See also - push_front inserts elements to the beginning - \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP diff --git a/man/std::deque::empty.3 b/man/std::deque::empty.3 index d873f333d..74c63424d 100644 --- a/man/std::deque::empty.3 +++ b/man/std::deque::empty.3 @@ -1,6 +1,12 @@ -.TH std::deque::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::empty \- std::deque::empty + .SH Synopsis - bool empty() const; + bool empty() const; \fI(until C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +16,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,21 +24,22 @@ .SH Example - + The following code uses empty to check if a std::deque contains any elements: - + // Run this code #include #include - + int main() { std::deque numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.push_back(42); numbers.push_back(13317); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -47,10 +47,12 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::deque::end,std::deque::cend.3 b/man/std::deque::end,std::deque::cend.3 index fdcba1917..9c671f0c9 100644 --- a/man/std::deque::end,std::deque::cend.3 +++ b/man/std::deque::end,std::deque::cend.3 @@ -1,10 +1,13 @@ -.TH std::deque::end,std::deque::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::end,std::deque::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::end,std::deque::cend \- std::deque::end,std::deque::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fB(1)\fP (noexcept since C++11) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the deque. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +22,60 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::deque nums{1, 2, 4, 8, 16}; + std::deque fruits{"orange", "apple", "raspberry"}; + std::deque empty; + + // Print deque. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the deque nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the deque fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "deque 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + deque 'empty' is indeed empty. + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::deque::erase.3 b/man/std::deque::erase.3 index ba2ab255d..adc2b1533 100644 --- a/man/std::deque::erase.3 +++ b/man/std::deque::erase.3 @@ -1,4 +1,7 @@ -.TH std::deque::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::erase \- std::deque::erase + .SH Synopsis iterator erase( iterator pos ); \fI(until C++11)\fP iterator erase( const_iterator pos ); \fI(since C++11)\fP @@ -6,62 +9,95 @@ iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP const_iterator last ); - Removes specified elements from the container. + Erases the specified elements from the container. 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). + 2) Removes the elements in the range [first, last). All iterators and references are invalidated, unless the erased elements are at the - end or the beginning of the container, in which case only the iterators and - references to the erased elements are invalidated. - - It is unspecified when the past-the-end iterator is invalidated. \fI(until C++11)\fP - The past-the-end iterator is also invalidated unless the erased - elements are at the beginning of the container and the last element is \fI(since C++11)\fP - not erased. + end or at the beginning of the container, in which case only the iterators and + references to the erased elements are invalidated. The end() iterator is also + invalidated unless the erased elements are at the beginning of the container and the + last element is not erased. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. + + The iterator first does not need to be dereferenceable if first == last: erasing an + empty range is a no-op. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove +.SH Type requirements + - + T must meet the requirements of MoveAssignable. .SH Return value Iterator following the last removed element. + 1) If pos refers to the last element, then the end() iterator is returned. + 2) If last == end() prior to removal, then the updated end() iterator is returned. + If [first, last) is an empty range, then last is returned. + +.SH Exceptions + + Does not throw unless an exception is thrown by the assignment operator of T. + +.SH Complexity + + Linear: the number of calls to the destructor of T is the same as the number of + elements erased, the number of calls to the assignment operator of T is no more than + the lesser of the number of elements before the erased elements and the number of + elements after the erased elements. + +.SH Notes + + When container elements need to be erased based on a predicate, rather than + iterating the container and calling unary erase, the iterator range overload is + generally used with std::remove()/std::remove_if() to minimise the number of moves + of the remaining (non-removed) elements, this is the erase-remove idiom. + std::erase_if() replaces the erase-remove idiom. + \fI(since C++20)\fP + .SH Example - + // Run this code #include #include - - - int main( ) + + + void print_container(const std::deque& c) { - std::deque c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; - for (auto &i : c) { - std::cout << i << " "; - } + for (int i : c) + std::cout << i << ' '; std::cout << '\\n'; - + } + + int main() + { + std::deque c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + print_container(c); + c.erase(c.begin()); - - for (auto &i : c) { - std::cout << i << " "; - } - std::cout << '\\n'; - - c.erase(c.begin()+2, c.begin()+5); - - for (auto &i : c) { - std::cout << i << " "; + print_container(c); + + c.erase(c.begin() + 2, c.begin() + 5); + print_container(c); + + // Erase all even numbers + for (std::deque::iterator it = c.begin(); it != c.end();) + { + if (*it % 2 == 0) + it = c.erase(it); + else + ++it; } - std::cout << '\\n'; + print_container(c); } .SH Output: @@ -69,13 +105,27 @@ 0 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 1 2 6 7 8 9 + 1 7 9 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 1) Linear in the distance between position and last. - 2) Linear in distance between position and the end of the container. + DR Applied to Behavior as published Correct behavior + first was required to be + LWG 151 C++98 dereferenceable, which not required if + made the behavior of clearing an empty first == last + deque undefined + it is invalidated if the + LWG 638 C++98 the past-the-end iterator was not elements are + invalidated erased from the middle or + the end .SH See also - clear clears the contents - \fI(public member function)\fP + erase(std::deque) erases all elements satisfying specific criteria + erase_if(std::deque) \fI(function template)\fP + (C++20) + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::deque::front.3 b/man/std::deque::front.3 index 246ab412b..34ec35508 100644 --- a/man/std::deque::front.3 +++ b/man/std::deque::front.3 @@ -1,11 +1,14 @@ -.TH std::deque::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::front \- std::deque::front + .SH Synopsis - reference front(); - const_reference front() const; + reference front(); \fB(1)\fP + const_reference front() const; \fB(2)\fP Returns a reference to the first element in the container. - Calling front on an empty container is undefined. + Calling front on an empty container causes undefined behavior. .SH Parameters @@ -13,11 +16,11 @@ .SH Return value - reference to the first element + Reference to the first element. .SH Complexity - Constant + Constant. .SH Notes @@ -27,26 +30,25 @@ The following code uses front to display the first element of a std::deque: - + // Run this code #include #include - + int main() { - std::deque letters {'o', 'm', 'g', 'w', 't', 'f'}; - - if (!letters.empty()) { - std::cout << "The first character is: " << letters.front() << '\\n'; - } + std::deque letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The first character is '" << letters.front() << "'.\\n"; } .SH Output: - The first character is o + The first character is 'a'. .SH See also back access the last element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::get_allocator.3 b/man/std::deque::get_allocator.3 index 617eb334b..7556590fe 100644 --- a/man/std::deque::get_allocator.3 +++ b/man/std::deque::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::deque::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::get_allocator \- std::deque::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) Returns the allocator associated with the container. diff --git a/man/std::deque::insert.3 b/man/std::deque::insert.3 index 6f9fc4302..24e4f92e1 100644 --- a/man/std::deque::insert.3 +++ b/man/std::deque::insert.3 @@ -1,58 +1,73 @@ -.TH std::deque::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::insert \- std::deque::insert + .SH Synopsis - iterator insert( iterator pos, const T& value ); (until - C++11) - iterator insert( const_iterator pos, const T& value (since - ); C++11) - iterator insert( const_iterator pos, T&& value ); \fB(2)\fP (since - C++11) - void insert( iterator pos, size_type count, const T& (until - value ); C++11) - iterator insert( const_iterator pos, size_type \fB(1)\fP (since - count, const T& value ); C++11) - template< class InputIt > (until - void insert( iterator pos, InputIt first, InputIt \fB(3)\fP C++11) - last); - template< class InputIt > \fB(4)\fP (since - iterator insert( const_iterator pos, InputIt first, C++11) - InputIt last ); - iterator insert( const_iterator pos, \fB(5)\fP (since - std::initializer_list ilist ); C++11) - - Inserts elements at specified location in the container. - - 1-2) inserts value before the location pointed to by pos - 3) inserts count copies of the value before the location pointed to by pos - 4) inserts elements from range [first, last) before the location pointed to by pos. - The behavior is undefined if first and last are iterators into *this. - 5) inserts elements from initializer list ilist. - - All iterators, including the past-the-end iterator, are invalidated. References are + iterator insert( const_iterator pos, const T& value ); \fB(1)\fP + iterator insert( const_iterator pos, T&& value ); \fB(2)\fP \fI(since C++11)\fP + iterator insert( const_iterator pos, \fB(3)\fP + size_type count, const T& value ); + template< class InputIt > + iterator insert( const_iterator pos, InputIt first, InputIt last \fB(4)\fP + ); + iterator insert( const_iterator pos, std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); + + Inserts elements at the specified location in the container. + + 1,2) Inserts value before pos. + 3) Inserts count copies of the value before pos. + 4) Inserts elements from range [first, last) before pos. + + This overload has the same effect as overload \fB(3)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt + qualifies as LegacyInputIterator, to avoid ambiguity with the overload \fI(since C++11)\fP + \fB(3)\fP. + + If first and last are iterators into *this, the behavior is undefined. + 5) Inserts elements from initializer list ilist before pos. + + All iterators (including the end() iterator) are invalidated. References are invalidated too, unless pos == begin() or pos == end(), in which case they are not invalidated. .SH Parameters - pos - iterator to the location before which the content will be inserted. - pos may be the end() iterator - value - element value to insert - first, last - the range of elements to insert, can't be iterators into container for - which insert is called - ilist - initializer list to insert the values from + pos - iterator before which the content will be inserted + (pos may be the end() iterator) + value - element value to insert + count - number of elements to insert + first, last - the range of elements to insert, cannot be iterators + into container for which insert is called + ilist - initializer list to insert the values from .SH Type requirements - - InputIt must meet the requirements of InputIterator. + T must meet the requirements of CopyAssignable and CopyInsertable in order to use + overload \fB(1)\fP. + - + T must meet the requirements of MoveAssignable and MoveInsertable in order to use + overload \fB(2)\fP. + - + T must meet the requirements of CopyAssignable and CopyInsertable in order to use + overload \fB(3)\fP. + - + T must meet the requirements of EmplaceConstructible in order to use overloads + (4,5). + - + T must meet the requirements of Swappable, MoveAssignable, MoveConstructible and + MoveInsertable in order to use overloads (4,5). \fI(since C++17)\fP .SH Return value - 1-2) Iterator pointing to the inserted value - 3) Iterator pointing to the first element inserted, or pos if count==0. - 4) Iterator pointing to the first element inserted, or pos if first==last. + 1,2) Iterator pointing to the inserted value. + 3) Iterator pointing to the first element inserted, or pos if count == 0. + 4) Iterator pointing to the first element inserted, or pos if first == last. 5) Iterator pointing to the first element inserted, or pos if ilist is empty. .SH Complexity - 1-2) Constant plus linear in the lesser of the distances between pos and either of + 1,2) Constant plus linear in the lesser of the distances between pos and either of the ends of the container. 3) Linear in count plus linear in the lesser of the distances between pos and either of the ends of the container. @@ -61,11 +76,96 @@ 5) Linear in ilist.size() plus linear in the lesser of the distances between pos and either of the ends of the container. +.SH Exceptions + + If an exception is thrown other than by + + * the copy constructor of T, + + * the move constructor of T, \fI(since C++11)\fP + + * the copy assignment operator of T, + + * the move assignment operator of T, \fI(since C++11)\fP + + this function has no effect \fI(strong exception guarantee)\fP. + + If an exception is thrown when inserting a single element at either + end, this function has no effect \fI(strong exception guarantee)\fP. \fI(since C++11)\fP + Otherwise, if an exception is thrown by the move constructor of a + non-CopyInsertable T, the effects are unspecified. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(int id, const std::deque& container) + { + std::cout << id << ". "; + for (const int x : container) + std::cout << x << ' '; + std::cout << '\\n'; + } + + int main () + { + std::deque c1(3, 100); + print(1, c1); + + auto it = c1.begin(); + it = c1.insert(it, 200); + print(2, c1); + + c1.insert(it, 2, 300); + print(3, c1); + + // reset `it` to the begin: + it = c1.begin(); + + std::deque c2(2, 400); + c1.insert(std::next(it, 2), c2.begin(), c2.end()); + print(4, c1); + + int arr[] = {501, 502, 503}; + c1.insert(c1.begin(), arr, arr + std::size(arr)); + print(5, c1); + + c1.insert(c1.end(), {601, 602, 603}); + print(6, c1); + } + +.SH Output: + + 1. 100 100 100 + 2. 200 100 100 100 + 3. 300 300 200 100 100 100 + 4. 300 300 400 400 200 100 100 100 + 5. 501 502 503 300 300 400 400 200 100 100 100 + 6. 501 502 503 300 300 400 400 200 100 100 100 601 602 603 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 149 C++98 overloads \fB(3)\fP and \fB(4)\fP returned returns an iterator + nothing + LWG 247 C++98 the complexity was only specified also specified for inserting + for inserting a single element multiple elements + .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::deque::insert_range.3 b/man/std::deque::insert_range.3 new file mode 100644 index 000000000..736031748 --- /dev/null +++ b/man/std::deque::insert_range.3 @@ -0,0 +1,74 @@ +.TH std::deque::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::insert_range \- std::deque::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + iterator insert_range( const_iterator pos, R&& rg ); + + Inserts, in non-reversing order, copies of elements in rg before pos. + + All iterators (including the end() iterator) are invalidated. References are + invalidated too, unless pos == begin() or pos == end(), in which case they are not + invalidated. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + pos - iterator before which the content will be inserted + (pos may be the end() iterator) + rg - a container compatible range, that is, an input_range + whose elements are convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into deque from *ranges::begin(rg). Also, T must be + MoveInsertable into deque and T satisfies MoveConstructible, MoveAssignable, and + Swappable. Otherwise, the behavior is undefined. + +.SH Return value + + An iterator that points at the copy of the first element inserted into deque or at + pos if rg is empty. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto container = std::deque{1, 2, 3, 4}; + auto pos = std::next(container.begin(), 2); + assert(*pos == 3); + const auto rg = std::list{-1, -2, -3}; + + #ifdef __cpp_lib_containers_ranges + container.insert_range(pos, rg); + #else + container.insert(pos, rg.cbegin(), rg.cend()); + #endif + assert(std::ranges::equal(container, std::deque{1, 2, -1, -2, -3, 3, 4})); + } + +.SH See also + + insert inserts elements + \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP diff --git a/man/std::deque::max_size.3 b/man/std::deque::max_size.3 index 011e3f3da..74ca4fcdc 100644 --- a/man/std::deque::max_size.3 +++ b/man/std::deque::max_size.3 @@ -1,6 +1,9 @@ -.TH std::deque::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::max_size \- std::deque::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,25 +17,45 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::deque p; + std::deque q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 9,223,372,036,854,775,807 = 0x7,FFF,FFF,FFF,FFF,FFF + q.max_size() = 2,305,843,009,213,693,951 = 0x1,FFF,FFF,FFF,FFF,FFF + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::operator=.3 b/man/std::deque::operator=.3 index 7b247cd49..acf63105c 100644 --- a/man/std::deque::operator=.3 +++ b/man/std::deque::operator=.3 @@ -1,27 +1,39 @@ -.TH std::deque::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::operator= \- std::deque::operator= + .SH Synopsis - deque& operator=( const deque& other ); \fB(1)\fP - deque& operator=( deque&& other ); \fB(2)\fP \fI(since C++11)\fP - deque& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + deque& operator=( const deque& other ); \fB(1)\fP + deque& operator=( deque&& other ); \fI(since C++11)\fP + \fB(2)\fP \fI(until C++17)\fP + deque& operator=( deque&& other ) noexcept(/* see below */); \fI(since C++17)\fP + deque& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,68 +47,97 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) \fI(since C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::deque to another: - The following code uses to assign one std::deque to another: - // Run this code - #include + #include #include - - void display_sizes(const std::deque& nums1, - const std::deque& nums2, - const std::deque& nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::deque nums1 {3, 1, 4, 6, 5, 9}; - std::deque nums2; - std::deque nums3; - + std::deque x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 1, 2, 3 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 1, 2, 3 } + y = { 1, 2, 3 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 1, 2, 3 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 4, 5, 6, 7 } .SH See also constructor constructs the deque - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::deque::operator[].3 b/man/std::deque::operator[].3 index fa0da6e57..2c5073efb 100644 --- a/man/std::deque::operator[].3 +++ b/man/std::deque::operator[].3 @@ -1,8 +1,10 @@ -.TH std::deque::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::operator[] \- std::deque::operator[] + .SH Synopsis - reference operator[]( size_type pos ); - const_reference operator[]( size_type pos ) const; \fI(until C++14)\fP - constexpr const_reference operator[]( size_type pos ) const; \fI(since C++14)\fP + reference operator[]( size_type pos ); \fB(1)\fP + const_reference operator[]( size_type pos ) const; \fB(2)\fP Returns a reference to the element at specified location pos. No bounds checking is performed. @@ -19,28 +21,33 @@ Constant. +.SH Notes + + Unlike std::map::operator[], this operator never inserts a new element into the + container. Accessing a nonexistent element through this operator is undefined + behavior. + .SH Example - The following code uses operator[] read from and write to a std::deque: + The following code uses operator[] to read from and write to a std::deque: + - // Run this code #include #include - + int main() { - std::deque numbers {2, 4, 6, 8}; - + std::deque numbers{2, 4, 6, 8}; + std::cout << "Second element: " << numbers[1] << '\\n'; - + numbers[0] = 5; - + std::cout << "All numbers:"; - for (auto i : numbers) { + for (auto i : numbers) std::cout << ' ' << i; - } std::cout << '\\n'; } @@ -52,4 +59,4 @@ .SH See also at access specified element with bounds checking - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::pop_back.3 b/man/std::deque::pop_back.3 index 7d78d3688..a362cac07 100644 --- a/man/std::deque::pop_back.3 +++ b/man/std::deque::pop_back.3 @@ -1,15 +1,16 @@ -.TH std::deque::pop_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::pop_back \- std::deque::pop_back + .SH Synopsis void pop_back(); Removes the last element of the container. - Iterators and references to the erased element are invalidated. It is - unspecified whether the past-the-end iterator is invalidated. Other \fI(until C++11)\fP - references and iterators are not affected. - Iterators and references to the erased element are invalidated. The - past-the-end iterator is also invalidated. Other references and \fI(since C++11)\fP - iterators are not affected. + Calling pop_back on an empty container results in undefined behavior. + + Iterators and references to the erased element are invalidated. The end() iterator + is also invalidated. Other references and iterators are not affected. .SH Parameters @@ -23,9 +24,53 @@ Constant. +.SH Exceptions + + Throws nothing. + +.SH Example + + +// Run this code + + #include + #include + + template + void print(T const& xs) + { + std::cout << "[ "; + for (auto const& x : xs) + std::cout << x << ' '; + std::cout << "]\\n"; + } + + int main() + { + std::deque numbers; + + print(numbers); + + numbers.push_back(5); + numbers.push_back(3); + numbers.push_back(4); + + print(numbers); + + numbers.pop_back(); + + print(numbers); + } + +.SH Output: + + [ ] + [ 5 3 4 ] + [ 5 3 ] + .SH See also pop_front removes the first element - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP diff --git a/man/std::deque::pop_front.3 b/man/std::deque::pop_front.3 index 17606d623..dd7cd1b64 100644 --- a/man/std::deque::pop_front.3 +++ b/man/std::deque::pop_front.3 @@ -1,17 +1,16 @@ -.TH std::deque::pop_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::pop_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::pop_front \- std::deque::pop_front + .SH Synopsis void pop_front(); - Removes the first element of the container. + Removes the first element of the container. If there are no elements in the + container, the behavior is undefined. - Iterators and references to the erased element are invalidated. It is - unspecified whether the past-the-end iterator is invalidated if the \fI(since C++11)\fP - element is the last element in the container. Other references and - iterators are not affected. - Iterators and references to the erased element are invalidated. If the - element is the last element in the container, the past-the-end \fI(until C++11)\fP - iterator is also invalidated. Other references and iterators are not - affected. + Iterators and references to the erased element are invalidated. If the element is + the last element in the container, the end() iterator is also invalidated. Other + references and iterators are not affected. .SH Parameters @@ -25,9 +24,38 @@ Constant. +.SH Exceptions + + Does not throw. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::deque chars{'A', 'B', 'C', 'D'}; + + for (; !chars.empty(); chars.pop_front()) + std::cout << "chars.front(): '" << chars.front() << "'\\n"; + } + +.SH Output: + + chars.front(): 'A' + chars.front(): 'B' + chars.front(): 'C' + chars.front(): 'D' + .SH See also pop_back removes the last element - \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP + \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + front access the first element + \fI(public member function)\fP diff --git a/man/std::deque::prepend_range.3 b/man/std::deque::prepend_range.3 new file mode 100644 index 000000000..7a9a7ddff --- /dev/null +++ b/man/std::deque::prepend_range.3 @@ -0,0 +1,70 @@ +.TH std::deque::prepend_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::prepend_range \- std::deque::prepend_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void prepend_range( R&& rg ); + + Inserts, in non-reversing order, copies of elements in rg before begin(). Each + iterator in the range rg is dereferenced exactly once. + + All iterators (including the end() iterator) are invalidated. No references are + invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range + whose elements are convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into deque from *ranges::begin(rg). Also, T must be + MoveInsertable into deque and T satisfies MoveConstructible, MoveAssignable, and + Swappable. Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in size of rg. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto container = std::deque{0, 1, 2, 3}; + const auto rg = std::vector{-3, -2, -1}; + + #if __cpp_lib_containers_ranges + container.prepend_range(rg); + #else + container.insert(container.begin(), rg.cbegin(), rg.cend()); + #endif + assert(std::ranges::equal(container, std::deque{-3, -2, -1, 0, 1, 2, 3})); + } + +.SH See also + + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::deque::push_back.3 b/man/std::deque::push_back.3 index bde4e0b20..e80c4031f 100644 --- a/man/std::deque::push_back.3 +++ b/man/std::deque::push_back.3 @@ -1,4 +1,7 @@ -.TH std::deque::push_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::push_back \- std::deque::push_back + .SH Synopsis void push_back( const T& value ); \fB(1)\fP void push_back( T&& value ); \fB(2)\fP \fI(since C++11)\fP @@ -8,8 +11,8 @@ 1) The new element is initialized as a copy of value. 2) value is moved into the new element. - All iterators, including the past-the-end iterator, are invalidated. No references - are invalidated. + All iterators (including the end() iterator) are invalidated. No references are + invalidated. .SH Parameters @@ -30,42 +33,47 @@ .SH Exceptions - If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + If an exception is thrown (which can be due to Allocator::allocate() or element + copy/move constructor/assignment), this function has no effect (strong exception + guarantee). .SH Example - The following code uses push_back to add several integers to a std::deque: - // Run this code - #include + #include #include - + #include + #include + int main() { - std::deque numbers; - - numbers.push_back(42); - numbers.push_back(314159); - - for (int i : numbers) { // c++11 range-based for loop - std::cout << i << '\\n'; - } - - return 0; + std::deque letters; + + letters.push_back("abc"); + std::string s{"def"}; + letters.push_back(std::move(s)); + + std::cout << "std::deque letters holds: "; + for (auto&& e : letters) + std::cout << std::quoted(e) << ' '; + + std::cout << "\\nMoved-from string s holds: " << std::quoted(s) << '\\n'; } -.SH Output: +.SH Possible output: - 42 - 314159 + std::deque letters holds: "abc" "def" + Moved-from string s holds: "" .SH See also - emplace_back constructs elements in-place at the end - \fI(C++11)\fP \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - pop_back removes the last element - \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + pop_back removes the last element + \fI(public member function)\fP + back_inserter creates a std::back_insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::deque::push_front.3 b/man/std::deque::push_front.3 index a7df47fed..01a885054 100644 --- a/man/std::deque::push_front.3 +++ b/man/std::deque::push_front.3 @@ -1,12 +1,15 @@ -.TH std::deque::push_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::push_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::push_front \- std::deque::push_front + .SH Synopsis - void push_front( const T& value ); - void push_front( T&& value ); \fI(since C++11)\fP + void push_front( const T& value ); \fB(1)\fP + void push_front( T&& value ); \fB(2)\fP \fI(since C++11)\fP Prepends the given element value to the beginning of the container. - All iterators, including the past-the-end iterator, are invalidated. No references - are invalidated. + All iterators (including the end() iterator) are invalidated. No references are + invalidated. .SH Parameters @@ -22,13 +25,47 @@ .SH Exceptions - If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::deque letters; + + letters.push_front("abc"); + std::string s{"def"}; + letters.push_front(std::move(s)); + + std::cout << "std::deque letters holds: "; + for (auto&& e : letters) + std::cout << std::quoted(e) << ' '; + + std::cout << "\\nMoved-from string s holds: " << std::quoted(s) << '\\n'; + } + +.SH Possible output: + + std::deque letters holds: "def" "abc" + Moved-from string s holds: "" .SH See also - emplace_front constructs elements in-place at the beginning - \fI(C++11)\fP \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP - pop_front removes the first element - \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(C++11)\fP \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + pop_front removes the first element + \fI(public member function)\fP + creates a std::front_insert_iterator of type inferred from the + front_inserter argument + \fI(function template)\fP diff --git a/man/std::deque::rbegin,std::deque::crbegin.3 b/man/std::deque::rbegin,std::deque::crbegin.3 index d3c615c2a..0da74658c 100644 --- a/man/std::deque::rbegin,std::deque::crbegin.3 +++ b/man/std::deque::rbegin,std::deque::crbegin.3 @@ -1,11 +1,15 @@ -.TH std::deque::rbegin,std::deque::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::rbegin,std::deque::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::rbegin,std::deque::crbegin \- std::deque::rbegin,std::deque::crbegin + .SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. + Returns a reverse iterator to the first element of the reversed deque. It + corresponds to the last element of the non-reversed deque. If the deque is empty, + the returned iterator is equal to rend(). range-rbegin-rend.svg @@ -17,18 +21,62 @@ Reverse iterator to the first element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::deque nums{1, 2, 4, 8, 16}; + std::deque fruits{"orange", "apple", "raspberry"}; + std::deque empty; + + // Print deque. + std::for_each(nums.rbegin(), nums.rend(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the deque nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.rbegin(), nums.rend(), 0) << '\\n'; + + // Prints the first fruit in the deque fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.rbegin() << '\\n'; + + if (empty.rbegin() == empty.rend()) + std::cout << "deque 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 16 8 4 2 1 + Sum of nums: 31 + First fruit: raspberry + deque 'empty' is indeed empty. + .SH See also - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::deque::rend,std::deque::crend.3 b/man/std::deque::rend,std::deque::crend.3 index 54c863b16..36521a7d0 100644 --- a/man/std::deque::rend,std::deque::crend.3 +++ b/man/std::deque::rend,std::deque::crend.3 @@ -1,13 +1,16 @@ -.TH std::deque::rend,std::deque::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::rend,std::deque::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::rend,std::deque::crend \- std::deque::rend,std::deque::crend + .SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. + deque. It corresponds to the element preceding the first element of the non-reversed + deque. This element acts as a placeholder, attempting to access it results in + undefined behavior. range-rbegin-rend.svg @@ -19,18 +22,59 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::deque nums{1, 2, 4, 8, 16}; + std::deque fruits{"orange", "apple", "raspberry"}; + std::deque empty; + + // Print deque. + std::for_each(nums.rbegin(), nums.rend(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the deque nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.rbegin(), nums.rend(), 0) << '\\n'; + + // Prints the first fruit in the deque fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.rbegin() << '\\n'; + + if (empty.rbegin() == empty.rend()) + std::cout << "deque 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 16 8 4 2 1 + Sum of nums: 31 + First fruit: raspberry + deque 'empty' is indeed empty. + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::deque::resize.3 b/man/std::deque::resize.3 index ad92f9904..2d6e2b08b 100644 --- a/man/std::deque::resize.3 +++ b/man/std::deque::resize.3 @@ -1,30 +1,31 @@ -.TH std::deque::resize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::resize \- std::deque::resize + .SH Synopsis - void resize( size_type count, T value = T() ); \fI(until C++11)\fP - void resize( size_type count ); \fB(1)\fP \fI(since C++11)\fP - void resize( size_type count, const value_type& value); \fB(2)\fP \fI(since C++11)\fP + void resize( size_type count ); \fB(1)\fP + void resize( size_type count, const value_type& value ); \fB(2)\fP - Resizes the container to contain count elements. + Resizes the container to contain count elements, does nothing if count == size(). If the current size is greater than count, the container is reduced to its first - count elements as if by repeatedly calling pop_back() + count elements. - If the current size is less than count, additional elements are \fI(until C++11)\fP - appended and initialized with copies of value. If the current size is less than count, - \fI(since C++11)\fP - 1) additional value-initialized elements are appended - 2) additional copies of value are appended + + 1) additional default-inserted elements are appended. + 2) additional copies of value are appended. .SH Parameters - count - new size of the container - value - the value to initialize the new elements with + count - new size of the container + value - the value to initialize the new elements with .SH Type requirements - - 1) T must meet the requirements of DefaultConstructible and MoveInsertable. + T must meet the requirements of MoveInsertable and DefaultInsertable in order to use + overload \fB(1)\fP. - - 2) T must meet the requirements of CopyInsertable and MoveInsertable. + T must meet the requirements of CopyInsertable in order to use overload \fB(2)\fP. .SH Return value @@ -32,9 +33,70 @@ .SH Complexity - Linear in the size of the container + Linear in the difference between the current size and count. + +.SH Notes + + If value-initialization in overload \fB(1)\fP is undesirable, for example, if the elements + are of non-class type and zeroing out is not needed, it can be avoided by providing + a custom Allocator::construct. + +.SH Example + + +// Run this code + + #include + #include + + void print(auto rem, const std::deque& c) + { + for (std::cout << rem; const int el : c) + std::cout << el << ' '; + std::cout << '\\n'; + } + + int main() + { + std::deque c = {1, 2, 3}; + print("The deque holds: ", c); + + c.resize(5); + print("After resize up to 5: ", c); + + c.resize(2); + print("After resize down to 2: ", c); + + c.resize(6, 4); + print("After resize up to 6 (initializer = 4): ", c); + } + +.SH Output: + + The deque holds: 1 2 3 + After resize up to 5: 1 2 3 0 0 + After resize down to 2: 1 2 + After resize up to 6 (initializer = 4): 1 2 4 4 4 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 679 C++98 resize() passed value by value passes by const reference + LWG 1418 C++98 the behavior of resize(size()) was not specified + specified + 1. elements were removed by using + LWG 2033 C++11 erase() 1. uses pop_back() + 2. T was not required to be 2. required + MoveInsertable .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::deque::shrink_to_fit.3 b/man/std::deque::shrink_to_fit.3 index 7e0044d44..05ffc09ab 100644 --- a/man/std::deque::shrink_to_fit.3 +++ b/man/std::deque::shrink_to_fit.3 @@ -1,14 +1,16 @@ -.TH std::deque::shrink_to_fit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::shrink_to_fit \- std::deque::shrink_to_fit + .SH Synopsis - void shrink_to_fit(); \fI(since C++11)\fP + void shrink_to_fit(); Requests the removal of unused capacity. - It is a non-binding request to reduce capacity to size(). It depends on the - implementation if the request is fulfilled. + It is a non-binding request to reduce the memory usage without changing the size of + the sequence. It depends on the implementation whether the request is fulfilled. - All iterators and references are potentially invalidated. Past-the-end iterator is - also potentially invalidated. + All iterators (including the end() iterator) and references are invalidated. .SH Parameters @@ -16,7 +18,7 @@ .SH Type requirements - - T must meet the requirements of MoveInsertable. + T must meet the requirements of MoveInsertable into *this. \fI(since C++11)\fP .SH Return value @@ -24,29 +26,117 @@ .SH Complexity - Linear in the size of the container. + At most linear in the size of the container. + +.SH Exceptions + \fI(since C++11)\fP + If an exception is thrown other than by the move constructor of a + non-CopyInsertable T, there are no effects. + +.SH Notes + + In libstdc++, shrink_to_fit() is not available in C++98 mode. .SH Example - - + + // Run this code + #include #include - - int main() { - std::deque nums(1000, 42); - nums.push_front(1); - nums.pop_front(); - - nums.clear(); - - // nums now contains no items, but it may still be holding allocated memory. - // Calling shrink_to_fit will free any unused memory. - nums.shrink_to_fit(); + #include + #include + + // Minimal C++11 allocator with debug output. + template + struct NAlloc + { + typedef Tp value_type; + + NAlloc() = default; + + template NAlloc(const NAlloc&) {} + + Tp* allocate(std::size_t n) + { + n *= sizeof(Tp); + std::cout << "allocating " << n << " bytes\\n"; + return static_cast(::operator new(n)); + } + + void deallocate(Tp* p, std::size_t n) + { + std::cout << "deallocating " << n*sizeof*p << " bytes\\n"; + ::operator delete(p); + } + }; + template + bool operator==(const NAlloc&, const NAlloc&) { return true; } + template + bool operator!=(const NAlloc&, const NAlloc&) { return false; } + + int main() + { + // std::queue has no capacity() function (like std::vector). + // Because of this, we use a custom allocator to show the + // working of shrink_to_fit. + + std::cout << "Default-construct deque:\\n"; + std::deque> deq; + + std::cout << "\\nAdd 300 elements:\\n"; + for (int i = 1000; i < 1300; ++i) + deq.push_back(i); + + std::cout << "\\nPop 100 elements:\\n"; + for (int i = 0; i < 100; ++i) + deq.pop_front(); + + std::cout << "\\nRun shrink_to_fit:\\n"; + deq.shrink_to_fit(); + + std::cout << "\\nDestroy deque as it goes out of scope:\\n"; } +.SH Possible output: + + Default-construct deque: + allocating 64 bytes + allocating 512 bytes + + Add 300 elements: + allocating 512 bytes + allocating 512 bytes + + Pop 100 elements: + + Run shrink_to_fit: + allocating 64 bytes + allocating 512 bytes + allocating 512 bytes + deallocating 512 bytes + deallocating 512 bytes + deallocating 512 bytes + deallocating 64 bytes + + Destroy deque as it goes out of scope: + deallocating 512 bytes + deallocating 512 bytes + deallocating 64 bytes + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 850 C++98 std::deque lacked explicit shrink-to-fit provided + operations + LWG 2033 C++11 1. T was not required to be MoveInsertable 1. required + 2. the complexity requirement was missing 2. added + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::deque::size.3 b/man/std::deque::size.3 index 8efad1cd8..258bbfc2a 100644 --- a/man/std::deque::size.3 +++ b/man/std::deque::size.3 @@ -1,6 +1,9 @@ -.TH std::deque::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::size \- std::deque::size + .SH Synopsis - size_type size() const; + size_type size() const; (noexcept since C++11) Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,26 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::deque: - + // Run this code #include #include - + int main() { - std::deque nums {1, 3, 5, 7}; - + std::deque nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,8 +45,12 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::deque::swap.3 b/man/std::deque::swap.3 index b8de332cd..2988d01e9 100644 --- a/man/std::deque::swap.3 +++ b/man/std::deque::swap.3 @@ -1,17 +1,20 @@ -.TH std::deque::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::swap \- std::deque::swap + .SH Synopsis - void swap( deque& other ); + void swap( deque& other ); \fI(until C++17)\fP + void swap( deque& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -23,13 +26,59 @@ .SH Exceptions - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::deque a1{1, 2, 3}, a2{4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + int& ref1 = a1.front(); + int& ref2 = a2.front(); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that after swap the iterators and references stay associated with their + // original elements, e.g. it1 that pointed to an element in 'a1' with value 2 + // still points to the same element, though this element was moved into 'a2'. + } + +.SH Output: + + { 1 2 3 } { 4 5 } 2 5 1 4 + { 4 5 } { 1 2 3 } 2 5 1 4 + .SH See also std::swap(std::deque) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::deque::~deque.3 b/man/std::deque::~deque.3 index 8b0868a19..6b56a9cc0 100644 --- a/man/std::deque::~deque.3 +++ b/man/std::deque::~deque.3 @@ -1,11 +1,14 @@ -.TH std::deque::~deque 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::deque::~deque 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::deque::~deque \- std::deque::~deque + .SH Synopsis ~deque(); - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. + Destructs the deque. The destructors of the elements are called and the used storage + is deallocated. Note, that if the elements are pointers, the pointed-to objects are + not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the deque. diff --git a/man/std::derived_from.3 b/man/std::derived_from.3 new file mode 100644 index 000000000..4b51dfee2 --- /dev/null +++ b/man/std::derived_from.3 @@ -0,0 +1,56 @@ +.TH std::derived_from 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::derived_from \- std::derived_from + +.SH Synopsis + Defined in header + template< class Derived, class Base > + + concept derived_from = + std::is_base_of_v && \fI(since C++20)\fP + + std::is_convertible_v; + + The concept derived_from is satisfied if and only if Base is a class + type that is either Derived or a public and unambiguous base of Derived, ignoring + cv-qualifiers. + + Note that this behavior is different to std::is_base_of when Base is a private or + protected base of Derived. + +.SH Example + + +// Run this code + + #include + + class A {}; + + class B : public A {}; + + class C : private A {}; + + // std::derived_from == true only for public inheritance or exact same class + static_assert(std::derived_from == true); // same class: true + static_assert(std::derived_from == false); // same primitive type: false + static_assert(std::derived_from == true); // public inheritance: true + static_assert(std::derived_from == false); // private inheritance: false + + // std::is_base_of == true also for private inheritance + static_assert(std::is_base_of_v == true); // same class: true + static_assert(std::is_base_of_v == false); // same primitive type: false + static_assert(std::is_base_of_v == true); // public inheritance: true + static_assert(std::is_base_of_v == true); // private inheritance: true + + int main() {} + +.SH See also + + is_base_of checks if a type is derived from the other type + \fI(C++11)\fP \fI(class template)\fP + is_convertible + is_nothrow_convertible checks if a type can be converted to the other type + \fI(C++11)\fP \fI(class template)\fP + (C++20) diff --git a/man/std::destroy.3 b/man/std::destroy.3 new file mode 100644 index 000000000..46438cec4 --- /dev/null +++ b/man/std::destroy.3 @@ -0,0 +1,116 @@ +.TH std::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::destroy \- std::destroy + +.SH Synopsis + Defined in header + template< class ForwardIt > \fI(since C++17)\fP + void destroy( ForwardIt first, ForwardIt last ); \fI(until C++20)\fP + template< class ForwardIt > \fI(since C++20)\fP + constexpr void destroy( ForwardIt first, ForwardIt last ); \fB(1)\fP + template< class ExecutionPolicy, class ForwardIt > + void destroy( ExecutionPolicy&& policy, ForwardIt first, \fB(2)\fP \fI(since C++17)\fP + ForwardIt last ); + + 1) Destroys the objects in the range [first, last), as if by + + for (; first != last; ++first) + std::destroy_at(std::addressof(*first)); + + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of elements to destroy + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the distance between first and last. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + template + constexpr // since C++20 + void destroy(ForwardIt first, ForwardIt last) + { + for (; first != last; ++first) + std::destroy_at(std::addressof(*first)); + } + +.SH Example + + The following example demonstrates how to use destroy to destroy a contiguous + sequence of elements. + + +// Run this code + + #include + #include + #include + + struct Tracer + { + int value; + ~Tracer() { std::cout << value << " destructed\\n"; } + }; + + int main() + { + alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 8]; + + for (int i = 0; i < 8; ++i) + new(buffer + sizeof(Tracer) * i) Tracer{i}; //manually construct objects + + auto ptr = std::launder(reinterpret_cast(buffer)); + + std::destroy(ptr, ptr + 8); + } + +.SH Output: + + 0 destructed + 1 destructed + 2 destructed + 3 destructed + 4 destructed + 5 destructed + 6 destructed + 7 destructed + +.SH See also + + destroy_n destroys a number of objects in a range + \fI(C++17)\fP \fI(function template)\fP + destroy_at destroys an object at a given address + \fI(C++17)\fP \fI(function template)\fP + ranges::destroy destroys a range of objects + (C++20) (niebloid) diff --git a/man/std::destroy_at.3 b/man/std::destroy_at.3 new file mode 100644 index 000000000..ba559c9a5 --- /dev/null +++ b/man/std::destroy_at.3 @@ -0,0 +1,104 @@ +.TH std::destroy_at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::destroy_at \- std::destroy_at + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + void destroy_at( T* p ); \fI(until C++20)\fP + template< class T > \fI(since C++20)\fP + constexpr void destroy_at( T* p ); + + If T is not an array type, calls the destructor of the object pointed to by p, as if + by p->~T(). + + If T is an array type, + the program is ill-formed + \fI(until C++20)\fP + recursively destroys elements of *p in order, as if by calling + std::destroy(std::begin(*p), std::end(*p)) + \fI(since C++20)\fP. + +.SH Parameters + + p - a pointer to the object to be destroyed + +.SH Return value + + \fI(none)\fP + +.SH Possible implementation + + template + constexpr void destroy_at(T* p) + { + if constexpr (std::is_array_v) + for (auto &elem : *p) + (destroy_at)(std::addressof(elem)); + else + p->~T(); + } + // C++17 version: + // template void destroy_at(T* p) { p->~T(); } + +.SH Notes + + destroy_at deduces the type of object to be destroyed and hence avoids writing it + explicitly in the destructor call. + + When destroy_at is called in the evaluation of some constant + expression e, the argument p must point to an object whose lifetime \fI(since C++20)\fP + began within the evaluation of e. + +.SH Example + + The following example demonstrates how to use destroy_at to destroy a contiguous + sequence of elements. + + +// Run this code + + #include + #include + #include + + struct Tracer + { + int value; + ~Tracer() { std::cout << value << " destructed\\n"; } + }; + + int main() + { + alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 8]; + + for (int i = 0; i < 8; ++i) + new(buffer + sizeof(Tracer) * i) Tracer{i}; //manually construct objects + + auto ptr = std::launder(reinterpret_cast(buffer)); + + for (int i = 0; i < 8; ++i) + std::destroy_at(ptr + i); + } + +.SH Output: + + 0 destructed + 1 destructed + 2 destructed + 3 destructed + 4 destructed + 5 destructed + 6 destructed + 7 destructed + +.SH See also + + destroy destroys a range of objects + \fI(C++17)\fP \fI(function template)\fP + destroy_n destroys a number of objects in a range + \fI(C++17)\fP \fI(function template)\fP + construct_at creates an object at a given address + (C++20) \fI(function template)\fP + ranges::destroy_at destroys an object at a given address + (C++20) (niebloid) diff --git a/man/std::destroy_n.3 b/man/std::destroy_n.3 new file mode 100644 index 000000000..8c9b9e36c --- /dev/null +++ b/man/std::destroy_n.3 @@ -0,0 +1,118 @@ +.TH std::destroy_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::destroy_n \- std::destroy_n + +.SH Synopsis + Defined in header + template< class ForwardIt, class Size > \fI(since C++17)\fP + ForwardIt destroy_n( ForwardIt first, Size n ); \fI(until C++20)\fP + template< class ForwardIt, class Size > \fI(since C++20)\fP + constexpr ForwardIt destroy_n( ForwardIt first, Size n ); \fB(1)\fP + template< class ExecutionPolicy, class ForwardIt, class Size > + ForwardIt destroy_n( ExecutionPolicy&& policy, ForwardIt \fB(2)\fP \fI(since C++17)\fP + first, Size n ); + + 1) Destroys the n objects in the range starting at first, as if by + + for (; n > 0; (void) ++first, --n) + std::destroy_at(std::addressof(*first)); + + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first - the beginning of the range of elements to destroy + n - the number of elements to destroy + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + +.SH Return value + + The end of the range of objects that has been destroyed (i.e., std::next(first, n)). + +.SH Complexity + + Linear in n. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + template + constexpr // since C++20 + ForwardIt destroy_n(ForwardIt first, Size n) + { + for (; n > 0; (void) ++first, --n) + std::destroy_at(std::addressof(*first)); + return first; + } + +.SH Example + + The following example demonstrates how to use destroy_n to destroy a contiguous + sequence of elements. + + +// Run this code + + #include + #include + #include + + struct Tracer + { + int value; + ~Tracer() { std::cout << value << " destructed\\n"; } + }; + + int main() + { + alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 8]; + + for (int i = 0; i < 8; ++i) + new(buffer + sizeof(Tracer) * i) Tracer{i}; //manually construct objects + + auto ptr = std::launder(reinterpret_cast(buffer)); + + std::destroy_n(ptr, 8); + } + +.SH Output: + + 0 destructed + 1 destructed + 2 destructed + 3 destructed + 4 destructed + 5 destructed + 6 destructed + 7 destructed + +.SH See also + + destroy destroys a range of objects + \fI(C++17)\fP \fI(function template)\fP + destroy_at destroys an object at a given address + \fI(C++17)\fP \fI(function template)\fP + ranges::destroy_n destroys a number of objects in a range + (C++20) (niebloid) diff --git a/man/std::destroying_delete_t,std::destroying_delete.3 b/man/std::destroying_delete_t,std::destroying_delete.3 new file mode 100644 index 000000000..a3ff48ba3 --- /dev/null +++ b/man/std::destroying_delete_t,std::destroying_delete.3 @@ -0,0 +1,16 @@ +.TH std::destroying_delete_t,std::destroying_delete 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::destroying_delete_t,std::destroying_delete \- std::destroying_delete_t,std::destroying_delete + +.SH Synopsis + Defined in header + struct destroying_delete_t { explicit destroying_delete_t() = \fB(1)\fP \fI(since C++20)\fP + default; }; + inline constexpr destroying_delete_t destroying_delete{}; \fB(2)\fP \fI(since C++20)\fP + + Tag type used to identify the destroying delete form of operator delete. + +.SH See also + + operator delete deallocation functions + operator delete[] \fI(function)\fP diff --git a/man/std::destructible.3 b/man/std::destructible.3 new file mode 100644 index 000000000..5da2b1a79 --- /dev/null +++ b/man/std::destructible.3 @@ -0,0 +1,26 @@ +.TH std::destructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::destructible \- std::destructible + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + concept destructible = std::is_nothrow_destructible_v; + + The concept destructible specifies the concept of all types whose instances can + safely be destroyed at the end of their lifetime (including reference types). + +.SH Notes + + Unlike the Destructible named requirement, std::destructible requires the destructor + to be noexcept(true), not merely non-throwing when invoked, and allows reference + types and array types. + +.SH See also + + is_destructible + is_trivially_destructible + is_nothrow_destructible checks if a type has a non-deleted destructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::difftime.3 b/man/std::difftime.3 index 901323c09..b84126554 100644 --- a/man/std::difftime.3 +++ b/man/std::difftime.3 @@ -1,4 +1,7 @@ -.TH std::difftime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::difftime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::difftime \- std::difftime + .SH Synopsis Defined in header double difftime( std::time_t time_end, std::time_t time_beg ); @@ -22,35 +25,33 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { - std::time_t start = std::time(NULL); - volatile double d; - + std::time_t start = std::time(nullptr); + volatile double d = 1.0; + // some time-consuming operation - for (int n=0; n<10000; ++n) { - for (int m=0; m<100000; ++m) { - d += d*n*m; - } - } - + for (int p = 0; p < 10000; ++p) + for (int q = 0; q < 100000; ++q) + d = d + p * d * q + d; + std::cout << "Wall time passed: " - << std::difftime(std::time(NULL), start) << " s.\\n"; + << std::difftime(std::time(nullptr), start) << " s.\\n"; } -.SH Output: +.SH Possible output: - Wall time passed: 7 s. + Wall time passed: 9 s. .SH See also duration a time interval - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP C documentation for difftime diff --git a/man/std::discard_block_engine.3 b/man/std::discard_block_engine.3 index 86afca564..f1b2be199 100644 --- a/man/std::discard_block_engine.3 +++ b/man/std::discard_block_engine.3 @@ -1,64 +1,78 @@ -.TH std::discard_block_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine \- std::discard_block_engine + .SH Synopsis Defined in header template< - class Engine, \fI(since C++11)\fP - size_t P, size_t R + class Engine, \fI(since C++11)\fP + std::size_t P, std::size_t R > class discard_block_engine; - discard_block_engine is a pseudo-random number generator adapter that discards a + discard_block_engine is a pseudo-random number engine adaptor that discards a certain amount of data produced by the base engine. From each block of size P generated by the base engine, the adaptor keeps only R numbers, discarding the rest. .SH Template parameters - Engine - the type of the wrapped engine - P - the size of a block. Must be greater than 0. - R - the number of used numbers per block. Must be greater than 0 and not - greater than P + Engine - the type of the wrapped engine. + P - the size of a block. Expected that \\(\\small{P>0}\\)P > 0. + R - the number of used numbers per block. Expected that \\(\\small{0> \fI(function)\fP + operator== compares the internal states of the adaptors and + operator!= underlying engines + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> engine adaptor + \fI(C++11)\fP \fI(function)\fP -.SH Member objects +.SH Member constants constexpr size_t block_size the size of the block, P - \fB[static]\fP \fI(public static member constant)\fP - constexpr size_t used_size the number of used numbers per block, R - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(C++11)\fP \fI(public static member constant)\fP + constexpr size_t used_block the number of used numbers per block, R + \fB[static]\fP \fI(C++11)\fP \fI(public static member constant)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::discard_block_engine::base.3 b/man/std::discard_block_engine::base.3 index 9fdfffd8d..d3417e488 100644 --- a/man/std::discard_block_engine::base.3 +++ b/man/std::discard_block_engine::base.3 @@ -1,6 +1,9 @@ -.TH std::discard_block_engine::base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::base \- std::discard_block_engine::base + .SH Synopsis - const Engine& base() const; \fI(since C++11)\fP + const Engine& base() const noexcept; \fI(since C++11)\fP Returns the underlying engine. @@ -11,9 +14,3 @@ .SH Return value The underlying engine. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::discard_block_engine::discard.3 b/man/std::discard_block_engine::discard.3 index 9e825d766..02a0fe96e 100644 --- a/man/std::discard_block_engine::discard.3 +++ b/man/std::discard_block_engine::discard.3 @@ -1,4 +1,7 @@ -.TH std::discard_block_engine::discard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine::discard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::discard \- std::discard_block_engine::discard + .SH Synopsis void discard( unsigned long long z ); \fI(since C++11)\fP @@ -16,10 +19,10 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH See also - advances the state of the underlying engine and returns the generated - operator() value - \fI(public member function)\fP + operator() advances the state of the underlying engine and returns the generated + \fI(C++11)\fP value + \fI(public member function)\fP diff --git a/man/std::discard_block_engine::discard_block_engine.3 b/man/std::discard_block_engine::discard_block_engine.3 index e477034bd..475f1bb70 100644 --- a/man/std::discard_block_engine::discard_block_engine.3 +++ b/man/std::discard_block_engine::discard_block_engine.3 @@ -1,20 +1,31 @@ -.TH std::discard_block_engine::discard_block_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine::discard_block_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::discard_block_engine \- std::discard_block_engine::discard_block_engine + .SH Synopsis discard_block_engine(); \fB(1)\fP \fI(since C++11)\fP - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP + explicit discard_block_engine( result_type s ); \fB(2)\fP \fI(since C++11)\fP + template< class Sseq > \fB(3)\fP \fI(since C++11)\fP explicit discard_block_engine( Sseq& seq ); - explicit discard_block_engine( const Engine& e ); \fB(3)\fP \fI(since C++11)\fP - explicit discard_block_engine( Engine&& e ); \fB(4)\fP \fI(since C++11)\fP + explicit discard_block_engine( const Engine& e ); \fB(4)\fP \fI(since C++11)\fP + explicit discard_block_engine( Engine&& e ); \fB(5)\fP \fI(since C++11)\fP Constructs new pseudo-random engine adaptor. 1) Default constructor. The underlying engine is also default-constructed. - 2) Constructs the underlying engine with seed sequence seq. - 3) Constructs the underlying engine with a copy of e. - 4) Move-constructs the underlying engine with e. e holds unspecified, but valid + 2) Constructs the underlying engine with s. + 3) Constructs the underlying engine with seed sequence seq. This constructor only + participate in overload resolution if Sseq qualifies as a SeedSequence. In + particular, this constructor does not participate in overload resolution if Sseq is + implicitly convertible to result_type. + 4) Constructs the underlying engine with a copy of e. + 5) Move-constructs the underlying engine with e. e holds unspecified, but valid state afterwards. .SH Parameters + s - integer value to construct the underlying engine with seq - seed sequence to construct the underlying engine with e - pseudo-random number engine to initialize with + +.SH Example diff --git a/man/std::discard_block_engine::max.3 b/man/std::discard_block_engine::max.3 index 15d621e69..807c6f232 100644 --- a/man/std::discard_block_engine::max.3 +++ b/man/std::discard_block_engine::max.3 @@ -1,4 +1,7 @@ -.TH std::discard_block_engine::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::max \- std::discard_block_engine::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP @@ -15,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::discard_block_engine::min.3 b/man/std::discard_block_engine::min.3 index 7e3c334e3..46b661706 100644 --- a/man/std::discard_block_engine::min.3 +++ b/man/std::discard_block_engine::min.3 @@ -1,4 +1,7 @@ -.TH std::discard_block_engine::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::min \- std::discard_block_engine::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP @@ -15,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::discard_block_engine::operator().3 b/man/std::discard_block_engine::operator().3 new file mode 100644 index 000000000..ef7e9585d --- /dev/null +++ b/man/std::discard_block_engine::operator().3 @@ -0,0 +1,26 @@ +.TH std::discard_block_engine::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::operator() \- std::discard_block_engine::operator() + +.SH Synopsis + result_type operator()(); \fI(since C++11)\fP + + Generates a random value. The state of the underlying engine is advanced one or more + times. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pseudo-random number in [min(), max()]. + +.SH Exceptions + + Throws nothing. + +.SH See also + + discard advances the adaptor's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::discard_block_engine::seed.3 b/man/std::discard_block_engine::seed.3 index 6bc11af0a..22acdcdc8 100644 --- a/man/std::discard_block_engine::seed.3 +++ b/man/std::discard_block_engine::seed.3 @@ -1,4 +1,7 @@ -.TH std::discard_block_engine::seed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discard_block_engine::seed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discard_block_engine::seed \- std::discard_block_engine::seed + .SH Synopsis void seed(); \fB(1)\fP \fI(since C++11)\fP void seed( result_type value ); \fB(2)\fP \fI(since C++11)\fP @@ -12,7 +15,10 @@ 2) Seeds the underlying engine with the seed value s. Effectively calls e.seed(value), where e is the underlying engine. 3) Seeds the underlying engine with the seed sequence seq. Effectively calls - e.seed(seq), where e is the underlying engine. + e.seed(seq), where e is the underlying engine. This template only participate in + overload resolution if Sseq qualifies as a SeedSequence. In particular, this + template does not participate in overload resolution if Sseq is implicitly + convertible to result_type. .SH Parameters @@ -27,4 +33,4 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. diff --git a/man/std::discrete_distribution.3 b/man/std::discrete_distribution.3 index 12808ad78..062d3e2e1 100644 --- a/man/std::discrete_distribution.3 +++ b/man/std::discrete_distribution.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution \- std::discrete_distribution + .SH Synopsis Defined in header template< class IntType = int > \fI(since C++11)\fP @@ -8,64 +11,76 @@ the probability of each individual integer i is defined as w i/S, that is the weight of the ith integer divided by the sum of all n weights. + std::discrete_distribution satisfies all requirements of RandomNumberDistribution. + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + IntType - this is not one of short, int, long, long long, unsigned short, unsigned + int, unsigned long, or unsigned long long. + .SH Member types - Member type Definition - result_type IntType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP IntType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics probabilities obtains the list of probabilities - \fI(public member function)\fP + \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code + #include #include #include #include - + int main() { std::random_device rd; std::mt19937 gen(rd()); std::discrete_distribution<> d({40, 10, 10, 40}); - std::map m; - for(int n=0; n<10000; ++n) { - ++m[d(gen)]; - } - for(auto p : m) { - std::cout << p.first << " generated " << p.second << " times\\n"; - } + std::map map; + + for (int n = 0; n < 1e4; ++n) + ++map[d(gen)]; + + for (const auto& [num, count] : map) + std::cout << num << " generated " << std::setw(4) << count << " times\\n"; } -.SH Output: +.SH Possible output: - 0 generated 4028 times - 1 generated 978 times - 2 generated 1012 times - 3 generated 3982 times + 0 generated 4037 times + 1 generated 962 times + 2 generated 1030 times + 3 generated 3971 times diff --git a/man/std::discrete_distribution::discrete_distribution.3 b/man/std::discrete_distribution::discrete_distribution.3 index dc47de9c3..61d24f471 100644 --- a/man/std::discrete_distribution::discrete_distribution.3 +++ b/man/std::discrete_distribution::discrete_distribution.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::discrete_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::discrete_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::discrete_distribution \- std::discrete_distribution::discrete_distribution + .SH Synopsis discrete_distribution(); \fB(1)\fP \fI(since C++11)\fP template< class InputIt > \fB(2)\fP \fI(since C++11)\fP @@ -10,29 +13,25 @@ xmax, UnaryOperation unary_op ); - explicit discrete_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + explicit discrete_distribution( const param_type& params ); \fB(5)\fP \fI(since C++11)\fP Constructs a new distribution object. - 1) Default constructor. Constructs the distribution with weights . This distribution - will always generate 0. - + 1) Default constructor. Constructs the distribution with a single weight p = {1}. + This distribution will always generate 0. 2) Constructs the distribution with weights in the range [first, last). If first == last, the effects are the same as of the default constructor. - 3) Constructs the distribution with weights in weights. Effectively calls - discrete_distribution(weigths.begin(), weights.end()). - + discrete_distribution(weights.begin(), weights.end()). 4) Constructs the distribution with count weights that are generated using function unary_op. Each of the weights is equal to w - i = unary_op(xmin + δ/2 + i · δ), where δ = + i = unary_op(xmin + δ(i + 0.5)), where δ = (xmax − xmin) count - and i ∈ {0, ..., count−1}. xmin and xmax must be such that δ > 0. If count == 0 the - effects are the same as of the default constructor. - + and i ∈ {0, ..., count − 1}. xmin and xmax must be such that δ > 0. If count == 0 + the effects are the same as of the default constructor. 5) Constructs the distribution with params as the distribution parameters. .SH Parameters @@ -48,11 +47,11 @@ Ret fun(const Type &a); unary_op - The signature does not need to have const &. - The type Type must be such that an object of type double can be - dereferenced and then implicitly converted to Type. The type Ret must + The type Type must be such that an object of type double can be + dereferenced and then implicitly converted to Type. The type Ret must be such that an object of type double can be dereferenced and assigned - a value of type Ret. + a value of type Ret. params - the distribution parameter set .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. diff --git a/man/std::discrete_distribution::max.3 b/man/std::discrete_distribution::max.3 index fcf398b92..52ed7f2b7 100644 --- a/man/std::discrete_distribution::max.3 +++ b/man/std::discrete_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::max \- std::discrete_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::discrete_distribution::min.3 b/man/std::discrete_distribution::min.3 index c4236b307..1d1449412 100644 --- a/man/std::discrete_distribution::min.3 +++ b/man/std::discrete_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::min \- std::discrete_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::discrete_distribution::operator().3 b/man/std::discrete_distribution::operator().3 index bbab1c504..0c1ceaef5 100644 --- a/man/std::discrete_distribution::operator().3 +++ b/man/std::discrete_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::operator() \- std::discrete_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::discrete_distribution::param.3 b/man/std::discrete_distribution::param.3 index 7d1b476d5..6d18fb479 100644 --- a/man/std::discrete_distribution::param.3 +++ b/man/std::discrete_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::param \- std::discrete_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::discrete_distribution::probabilities.3 b/man/std::discrete_distribution::probabilities.3 index f5d3eb5f2..3c7c30881 100644 --- a/man/std::discrete_distribution::probabilities.3 +++ b/man/std::discrete_distribution::probabilities.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::probabilities 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::probabilities 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::probabilities \- std::discrete_distribution::probabilities + .SH Synopsis std::vector probabilities() const; \fI(since C++11)\fP @@ -11,21 +14,22 @@ .SH Return value - An object of type std::vector + An object of type std::vector. .SH Example - + // Run this code #include - #include #include + #include + int main() { std::discrete_distribution<> d({40, 10, 10, 40}); std::vector p = d.probabilities(); - for(auto n : p) + for (auto n : p) std::cout << n << ' '; std::cout << '\\n'; } diff --git a/man/std::discrete_distribution::reset.3 b/man/std::discrete_distribution::reset.3 index a00ea28bb..1e0ef7a43 100644 --- a/man/std::discrete_distribution::reset.3 +++ b/man/std::discrete_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::discrete_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::discrete_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::discrete_distribution::reset \- std::discrete_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::disjunction.3 b/man/std::disjunction.3 new file mode 100644 index 000000000..8b1e8bdd4 --- /dev/null +++ b/man/std::disjunction.3 @@ -0,0 +1,149 @@ +.TH std::disjunction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::disjunction \- std::disjunction + +.SH Synopsis + Defined in header + template< class... B > \fI(since C++17)\fP + struct disjunction; + + Forms the logical disjunction of the type traits B..., effectively performing a + logical OR on the sequence of traits. + + The specialization std::disjunction has a public and unambiguous base + that is + + * if sizeof...(B) == 0, std::false_type; otherwise + * the first type Bi in B1, ..., BN for which bool(Bi::value) == true, or BN if + there is no such type. + + The member names of the base class, other than disjunction and operator=, are not + hidden and are unambiguously available in disjunction. + + Disjunction is short-circuiting: if there is a template type argument Bi with + bool(Bi::value) != false, then instantiating disjunction::value does + not require the instantiation of Bj::value for j > i. + + If the program adds specializations for std::disjunction or std::disjunction_v, the + behavior is undefined. + +.SH Template parameters + + B... - every template argument Bi for which Bi::value is instantiated must be usable + as a base class and define member value that is convertible to bool + + Helper variable template + + template< class... B > \fI(since C++17)\fP + inline constexpr bool disjunction_v = disjunction::value; + +.SH Possible implementation + + template struct disjunction : std::false_type {}; + template struct disjunction : B1 {}; + template + struct disjunction + : std::conditional_t> {}; + +.SH Notes + + A specialization of disjunction does not necessarily inherit from of either + std::true_type or std::false_type: it simply inherits from the first B whose + ::value, explicitly converted to bool, is true, or from the very last B when all of + them convert to false. For example, std::disjunction, + std::integral_constant>::value is 2. + + The short-circuit instantiation differentiates disjunction from fold expressions: a + fold expression like (... || Bs::value) instantiates every B in Bs, while + std::disjunction_v stops instantiation once the value can be determined. This + is particularly useful if the later type is expensive to instantiate or can cause a + hard error when instantiated with the wrong type. + + Feature-test macro Value Std Feature + __cpp_lib_logical_traits 201510L \fI(C++17)\fP Logical operator type traits + +.SH Example + + +// Run this code + + #include + #include + #include + + // values_equal::value is true if and only if a == b. + template + struct values_equal : std::bool_constant + { + using type = T; + }; + + // default_type::value is always true + template + struct default_type : std::true_type + { + using type = T; + }; + + // Now we can use disjunction like a switch statement: + template + using int_of_size = typename std::disjunction< // + values_equal, // + values_equal, // + values_equal, // + values_equal, // + default_type // must be last! + >::type; + + static_assert(sizeof(int_of_size<1>) == 1); + static_assert(sizeof(int_of_size<2>) == 2); + static_assert(sizeof(int_of_size<4>) == 4); + static_assert(sizeof(int_of_size<8>) == 8); + static_assert(std::is_same_v, void>); + + // checking if Foo is constructible from double will cause a hard error + struct Foo + { + template + struct sfinae_unfriendly_check { static_assert(!std::is_same_v); }; + + template + Foo(T, sfinae_unfriendly_check = {}); + }; + + template + struct first_constructible + { + template + struct is_constructible_x : std::is_constructible + { + using type = T; + }; + struct fallback + { + static constexpr bool value = true; + using type = void; // type to return if nothing is found + }; + + template + using with = typename std::disjunction..., + fallback>::type; + }; + + // OK, is_constructible not instantiated + static_assert(std::is_same_v::with, + int>); + + static_assert(std::is_same_v::with<>, std::string>); + static_assert(std::is_same_v::with, + std::string>); + static_assert(std::is_same_v::with, void>); + + int main() {} + +.SH See also + + negation logical NOT metafunction + \fI(C++17)\fP \fI(class template)\fP + conjunction variadic logical AND metafunction + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::distance.3 b/man/std::distance.3 index 93e45096e..d1dcd4709 100644 --- a/man/std::distance.3 +++ b/man/std::distance.3 @@ -1,60 +1,151 @@ -.TH std::distance 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::distance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::distance \- std::distance + .SH Synopsis Defined in header template< class InputIt > - typename std::iterator_traits::difference_type + typename std::iterator_traits::difference_type (constexpr since C++17) distance( InputIt first, InputIt last ); - Returns the number of elements between first and last. + Returns the number of hops from first to last. + + If InputIt is not LegacyRandomAccessIterator, the behavior is undefined if last is + not reachable from first. - The behavior is undefined if last is not reachable from first by (possibly - repeatedly) incrementing first. + If InputIt is LegacyRandomAccessIterator, the behavior is undefined if first and + last are neither reachable from each other. .SH Parameters - first - iterator pointing to the first element - last - iterator pointing to the last element + first - iterator pointing to the first element + last - iterator pointing to the end of the range .SH Type requirements - - InputIt must meet the requirements of InputIterator. The operation is more efficient - if InputIt additionally meets the requirements of RandomAccessIterator + InputIt must meet the requirements of LegacyInputIterator. The operation is more + efficient if InputIt additionally meets the requirements of + LegacyRandomAccessIterator. .SH Return value - The number of elements between first and last. + The number of increments needed to go from first to last. + + The value may be negative if random-access iterators are used and \fI(since C++11)\fP + first is reachable from last. .SH Complexity Linear. - However, if InputIt additionally meets the requirements of RandomAccessIterator, - complexity is constant. + However, if InputIt additionally meets the requirements of + LegacyRandomAccessIterator, complexity is constant. + +.SH Possible implementation + + See also the implementations in libstdc++ and libc++. + + C++98 implementation via tag dispatch, with constexpr removed + namespace detail + { + template + constexpr // required since C++17 + typename std::iterator_traits::difference_type + do_distance(It first, It last, std::input_iterator_tag) + { + typename std::iterator_traits::difference_type result = 0; + while (first != last) + { + ++first; + ++result; + } + return result; + } + + template + constexpr // required since C++17 + typename std::iterator_traits::difference_type + do_distance(It first, It last, std::random_access_iterator_tag) + { + return last - first; + } + } // namespace detail + + template + constexpr // since C++17 + typename std::iterator_traits::difference_type + distance(It first, It last) + { + return detail::do_distance(first, last, + typename std::iterator_traits::iterator_category()); + } + C++17 implementation via if constexpr + template + constexpr typename std::iterator_traits::difference_type + distance(It first, It last) + { + using category = typename std::iterator_traits::iterator_category; + static_assert(std::is_base_of_v); + + if constexpr (std::is_base_of_v) + return last - first; + else + { + typename std::iterator_traits::difference_type result = 0; + while (first != last) + { + ++first; + ++result; + } + return result; + } + } .SH Example - + // Run this code #include #include #include - + int main() { - std::vector v{ 3, 1, 4 }; - - auto distance = std::distance(v.begin(), v.end()); - - std::cout << distance << '\\n'; + std::vector v{3, 1, 4}; + std::cout << "distance(first, last) = " + << std::distance(v.begin(), v.end()) << '\\n' + << "distance(last, first) = " + << std::distance(v.end(), v.begin()) << '\\n'; + // the behavior is undefined (until LWG940) + + static constexpr auto il = {3, 1, 4}; + // Since C++17 `distance` can be used in constexpr context. + static_assert(std::distance(il.begin(), il.end()) == 3); + static_assert(std::distance(il.end(), il.begin()) == -3); } .SH Output: - 3 + distance(first, last) = 3 + distance(last, first) = -3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 940 C++98 the wording was unclear for the case where first made clear + is reachable from last .SH See also - advance advances an iterator by given distance - \fI(function)\fP + advance advances an iterator by given distance + \fI(function template)\fP + count returns the number of elements satisfying specific criteria + count_if \fI(function template)\fP + ranges::distance returns the distance between an iterator and a sentinel, or between + (C++20) the beginning and end of a range + (niebloid) diff --git a/man/std::div,std::ldiv,std::lldiv,std::imaxdiv.3 b/man/std::div,std::ldiv,std::lldiv,std::imaxdiv.3 new file mode 100644 index 000000000..e0e33d0bc --- /dev/null +++ b/man/std::div,std::ldiv,std::lldiv,std::imaxdiv.3 @@ -0,0 +1,184 @@ +.TH std::div,std::ldiv,std::lldiv,std::imaxdiv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::div,std::ldiv,std::lldiv,std::imaxdiv \- std::div,std::ldiv,std::lldiv,std::imaxdiv + +.SH Synopsis + Defined in header + std::div_t div( int x, int y ); \fB(1)\fP (constexpr since C++23) + std::ldiv_t div( long x, long y ); \fB(2)\fP (constexpr since C++23) + std::lldiv_t div( long long x, long long y ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + std::ldiv_t ldiv( long x, long y ); \fB(4)\fP (constexpr since C++23) + std::lldiv_t lldiv( long long x, long long y ); \fB(5)\fP \fI(since C++11)\fP + (constexpr since C++23) + Defined in header + std::imaxdiv_t div( std::intmax_t x, std::intmax_t y ); \fB(6)\fP \fI(since C++11)\fP + (constexpr since C++23) + std::imaxdiv_t imaxdiv( std::intmax_t x, std::intmax_t y \fB(7)\fP \fI(since C++11)\fP + ); (constexpr since C++23) + + Computes both the quotient and the remainder of the division of the numerator x by + the denominator y. + + 6,7) Overload of std::div for std::intmax_t is provided in \fI(since C++11)\fP + if and only if std::intmax_t is an extended integer type. + + The quotient is the algebraic quotient with any fractional part + discarded (truncated towards zero). The remainder is such that quot * \fI(until C++11)\fP + y + rem == x. + The quotient is the result of the expression x / y. The remainder is \fI(since C++11)\fP + the result of the expression x % y. + +.SH Parameters + + x, y - integer values + +.SH Return value + + If both the remainder and the quotient can be represented as objects of the + corresponding type (int, long, long long, std::intmax_t, respectively), returns both + as an object of type std::div_t, std::ldiv_t, std::lldiv_t, std::imaxdiv_t defined + as follows: + +std::div_t + + struct div_t { int quot; int rem; }; + + or + + struct div_t { int rem; int quot; }; + +std::ldiv_t + + struct ldiv_t { long quot; long rem; }; + + or + + struct ldiv_t { long rem; long quot; }; + +std::lldiv_t + + struct lldiv_t { long long quot; long long rem; }; + + or + + struct lldiv_t { long long rem; long long quot; }; + +std::imaxdiv_t + + struct imaxdiv_t { std::intmax_t quot; std::intmax_t rem; }; + + or + + struct imaxdiv_t { std::intmax_t rem; std::intmax_t quot; }; + + If either the remainder or the quotient cannot be represented, the behavior is + undefined. + +.SH Notes + + Until CWG issue 614 was resolved (N2757), the rounding direction of the quotient and + the sign of the remainder in the built-in division and remainder operators was + implementation-defined if either of the operands was negative, but it was + well-defined in std::div. + + On many platforms, a single CPU instruction obtains both the quotient and the + remainder, and this function may leverage that, although compilers are generally + able to merge nearby / and % where suitable. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + std::string division_with_remainder_string(int dividend, int divisor) + { + auto dv = std::div(dividend, divisor); + assert(dividend == divisor * dv.quot + dv.rem); + assert(dv.quot == dividend / divisor); + assert(dv.rem == dividend % divisor); + + auto sign = [](int n){ return n > 0 ? 1 : n < 0 ? -1 : 0; }; + assert((dv.rem == 0) or (sign(dv.rem) == sign(dividend))); + + return (std::ostringstream() << std::showpos << dividend << " = " + << divisor << " * (" << dv.quot << ") " + << std::showpos << dv.rem).str(); + } + + std::string itoa(int n, int radix /*[2..16]*/) + { + std::string buf; + std::div_t dv{}; dv.quot = n; + + do + { + dv = std::div(dv.quot, radix); + buf += "0123456789abcdef"[std::abs(dv.rem)]; // string literals are arrays + } + while (dv.quot); + + if (n < 0) + buf += '-'; + + return {buf.rbegin(), buf.rend()}; + } + + int main() + { + std::cout << division_with_remainder_string(369, 10) << '\\n' + << division_with_remainder_string(369, -10) << '\\n' + << division_with_remainder_string(-369, 10) << '\\n' + << division_with_remainder_string(-369, -10) << "\\n\\n"; + + std::cout << itoa(12345, 10) << '\\n' + << itoa(-12345, 10) << '\\n' + << itoa(42, 2) << '\\n' + << itoa(65535, 16) << '\\n'; + } + +.SH Output: + + +369 = +10 * (+36) +9 + +369 = -10 * (-36) +9 + -369 = +10 * (-36) -9 + -369 = -10 * (+36) -9 + + 12345 + -12345 + 101010 + ffff + +.SH See also + + fmod + fmodf remainder of the floating point division operation + fmodl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remainder + remainderf + remainderl signed remainder of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remquo + remquof + remquol signed remainder as well as the three last bits of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + div + +.SH External links + + 1. Euclidean division — From Wikipedia. + 2. Modulo (and Truncated division) — From Wikipedia. diff --git a/man/std::div,std::ldiv,std::lldiv.3 b/man/std::div,std::ldiv,std::lldiv.3 deleted file mode 100644 index a649ad5be..000000000 --- a/man/std::div,std::ldiv,std::lldiv.3 +++ /dev/null @@ -1,60 +0,0 @@ -.TH std::div,std::ldiv,std::lldiv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - std::div_t div( int x, int y ); - std::ldiv_t div( long x, long y ); - std::lldiv_t div( long long x, long long y ); \fI(since C++11)\fP - std::ldiv_t ldiv( long x, long y ); - std::lldiv_t lldiv( long long x, long long y ); \fI(since C++11)\fP - Defined in header - std::imaxdiv_t div( std::intmax_t x, std::intmax_t y ); \fI(since C++11)\fP - std::imaxdiv_t imaxdiv( std::intmax_t x, std::intmax_t y ); \fI(since C++11)\fP - - Computes quotient and remainder simultaneously. - - The quotient is the algebraic quotient with any fractional part - discarded (truncated towards zero). The remainder is such that quot * \fI(until C++11)\fP - y + rem == x. - The quotient is the result of the expression x/y. The remainder is the \fI(since C++11)\fP - result of the expression x%y. - -.SH Parameters - - x, y - integer values - -.SH Return value - - Structure of type div_t, ldiv_t, ldiv_t, imaxdiv_t defined as: - - struct div_t { - int quot; // The quotient - int rem; // The remainder - }; - - struct ldiv_t { - long quot; // The quotient - long rem; // The remainder - }; - - struct lldiv_t { - long long quot; // The quotient - long long rem; // The remainder - }; - - struct imaxdiv_t { - std::intmax_t quot; // The quotient - std::intmax_t rem; // The remainder - }; - -.SH Notes - - Until C++11, the rounding direction of the quotient and the sign of the remainder in - the built-in division and remainder operators was implementation-defined if either - of the operands was negative, but it was well-defined in std::div. - -.SH See also - - fmod remainder of the floating point division operation - \fI(function)\fP - C documentation for - div diff --git a/man/std::div_sat.3 b/man/std::div_sat.3 new file mode 100644 index 000000000..660065bee --- /dev/null +++ b/man/std::div_sat.3 @@ -0,0 +1,114 @@ +.TH std::div_sat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::div_sat \- std::div_sat + +.SH Synopsis + Defined in header + template< class T > (since C++26) + constexpr T div_sat( T x, T y ) noexcept; + + Computes the saturating division x / y. If T is a signed integer type, x is the + smallest (most negative) value of T, and y == -1, returns the greatest value of T; + otherwise, returns x / y. + + y must not be 0, otherwise the behavior is undefined. The function call is not a + core constant expression if undefined behavior happens. + + This overload participates in overload resolution only if T is an integer type, that + is: signed char, short, int, long, long long, an extended signed integer type, or an + unsigned version of such types. In particular, T must not be (possibly cv-qualified) + bool, char, wchar_t, char8_t, char16_t, and char32_t, as these types are not + intended for arithmetic. + +.SH Parameters + + x, y - integer values + +.SH Return value + + Saturated x / y. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Unlike the built-in arithmetic operators on integers, the integral promotion does + not apply to the x and y arguments. + + If two arguments of different type are passed, the call fails to compile, i.e. the + behavior relative to template argument deduction is the same as for std::min or + std::max. + + Most modern hardware architectures have efficient support for saturation arithmetic + on SIMD vectors, including SSE2 for x86 and NEON for ARM. + + Feature-test macro Value Std Feature + __cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic + +.SH Possible implementation + + namespace detail { + template + concept standard_or_extended_integral = + std::is_integral_v && + !std::is_same_v, bool> && + !std::is_same_v, char> && + !std::is_same_v, char8_t> && + !std::is_same_v, char16_t> && + !std::is_same_v, char32_t> && + !std::is_same_v, wchar_t>; + } // namespace detail + + template + constexpr T div_sat( T x, T y ) noexcept + { + if constexpr (std::is_signed_v) + if (x == std::numeric_limits::min() && y == -1) + return std::numeric_limits::max(); + return x / y; + } + +.SH Example + + Can be previewed on Compiler Explorer. + + +// Run this code + + #include + #include + + static_assert + ("" + && (std::div_sat(6, 3) == 2) // not saturated + && (std::div_sat(INT_MIN, -1) == INT_MAX) // saturated + && (std::div_sat(6, 3) == 2) // not saturated + ); + + int main() {} + +.SH See also + + add_sat saturating addition operation on two integers + (C++26) \fI(function template)\fP + sub_sat saturating subtraction operation on two integers + (C++26) \fI(function template)\fP + mul_sat saturating multiplication operation on two integers + (C++26) \fI(function template)\fP + saturate_cast returns an integer value clamped to the range of a another integer + (C++26) type + \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP + min returns the smallest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + max returns the largest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + +.SH External links + + 1. A branch-free implementation of saturation arithmetic — Locklessinc.com, 2012 diff --git a/man/std::divides.3 b/man/std::divides.3 index e2552eb75..26b938a8a 100644 --- a/man/std::divides.3 +++ b/man/std::divides.3 @@ -1,4 +1,7 @@ -.TH std::divides 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::divides 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::divides \- std::divides + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -15,16 +18,19 @@ is not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing x / y deducing argument and - divides return types - \fI(class template specialization)\fP + divides function object implementing x / y deducing parameter + \fI(C++14)\fP and return types + \fI(class template specialization)\fP .SH Member types - Type Definition - result_type T - first_argument_type T - second_argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) T + first_argument_type (deprecated in C++17)(removed in C++20) T + second_argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Member functions @@ -32,7 +38,7 @@ operator() argument \fI(public member function)\fP - std::divides::operator() +std::divides::operator() T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP @@ -49,11 +55,11 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr T operator()(const T &lhs, const T &rhs) const + constexpr T operator()(const T& lhs, const T& rhs) const { return lhs / rhs; } diff --git a/man/std::divides.3 b/man/std::divides.3 deleted file mode 100644 index bf51d791f..000000000 --- a/man/std::divides.3 +++ /dev/null @@ -1,55 +0,0 @@ -.TH std::divides 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class divides; - - std::divides<> is a specialization of std::divides with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() returns the quotient of two arguments - \fI(public member function)\fP - - std::divides<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) / std::forward(rhs)); - - Returns the result of dividing lhs by rhs (or whatever operator/ is overloaded to - do) - -.SH Parameters - - lhs, rhs - values to divide - -.SH Return value - - The result of lhs / rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::domain_error.3 b/man/std::domain_error.3 index ce21e4bd1..68cdd8d84 100644 --- a/man/std::domain_error.3 +++ b/man/std::domain_error.3 @@ -1,45 +1,113 @@ -.TH std::domain_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::domain_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::domain_error \- std::domain_error + .SH Synopsis Defined in header class domain_error; - Defines a type of object to be thrown as exception. It reports errors that arise - because a mathematical function is not defined for the value of the argument (e.g. - std::sqrt(-1)). + Defines a type of object to be thrown as exception. It may be used by the + implementation to report domain errors, that is, situations where the inputs are + outside of the domain on which an operation is defined. + + The standard library components do not throw this exception (mathematical functions + report domain errors as specified in math_errhandling). Third-party libraries, + however, use this. For example, boost.math throws std::domain_error if + boost::math::policies::throw_on_error is enabled (the default setting). std-domain error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP - - + constructor constructs a new domain_error object with the given message + \fI(public member function)\fP + operator= replaces the domain_error object + \fI(public member function)\fP - std::domain_error::domain_error +std::domain_error::domain_error - explicit domain_error( const std::string& what_arg ); \fB(1)\fP - explicit domain_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP + domain_error( const std::string& what_arg ); \fB(1)\fP + domain_error( const char* what_arg ); \fB(2)\fP + domain_error( const domain_error& other ); \fB(3)\fP (noexcept since C++11) - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::domain_error + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::domain_error is not permitted to throw exceptions, this message + is typically stored internally as a separately-allocated reference-counted string. + This is also why there is no constructor taking std::string&&: it would have to copy + the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::domain_error::operator= + + domain_error& operator=( const domain_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::domain_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::logic_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const char* added + was missing + the explanatory strings of they are the same as that + LWG 471 C++98 std::domain_error's of the + copies were implementation-defined original std::domain_error + object diff --git a/man/std::dynamic_extent.3 b/man/std::dynamic_extent.3 new file mode 100644 index 000000000..c4f477937 --- /dev/null +++ b/man/std::dynamic_extent.3 @@ -0,0 +1,85 @@ +.TH std::dynamic_extent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::dynamic_extent \- std::dynamic_extent + +.SH Synopsis + Defined in header + inline constexpr std::size_t dynamic_extent = \fI(since C++20)\fP + std::numeric_limits::max(); + + std::dynamic_extent is a constant of type std::size_t that is generally used to + indicate that any type using std::dynamic_extent will dynamically store its value + (e.g., size) rather than having the value statically known in the type. + + It is being used in several contexts: + + * To differentiate std::span of static and dynamic extent. + + * To indicate that the extent at a certain rank index will be stored (since C++23) + dynamically in std::extents. + + * To indicate that the padded layouts for std::mdspan will (since C++26) + dynamically store its padding value. + +.SH Note + + Since std::size_t is an unsigned type, an equivalent definition is: + + inline constexpr std::size_t dynamic_extent = -1; + + See integral conversions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + auto print = [](std::string_view const name, std::size_t ex) + { + std::cout << name << ", "; + if (std::dynamic_extent == ex) + std::cout << "dynamic extent\\n"; + else + std::cout << "static extent = " << ex << '\\n'; + }; + + int a[]{1, 2, 3, 4, 5}; + + std::span span1{a}; + print("span1", span1.extent); + + std::span span2{a}; + print("span2", span2.extent); + + std::array ar{1, 2, 3, 4, 5}; + std::span span3{ar}; + print("span3", span3.extent); + + std::vector v{1, 2, 3, 4, 5}; + std::span span4{v}; + print("span4", span4.extent); + } + +.SH Output: + + span1, static extent = 5 + span2, dynamic extent + span3, static extent = 5 + span4, dynamic extent + +.SH See also + + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + extents a descriptor of a multidimensional index space of some rank + (C++23) \fI(class template)\fP diff --git a/man/std::dynarray.3 b/man/std::dynarray.3 deleted file mode 100644 index 825e84743..000000000 --- a/man/std::dynarray.3 +++ /dev/null @@ -1,98 +0,0 @@ -.TH std::dynarray 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< - - class T \fI(since C++14)\fP - - > class dynarray; - - std::dynarray is a sequence container that encapsulates arrays with a size that is - fixed at construction and does not change throughout the lifetime of the object. - - The elements are stored contiguously, which means that elements can be accessed not - only through iterators, but also using offsets on regular pointers to elements. This - means that a pointer to an element of a dynarray may be passed to any function that - expects a pointer to an element of an array. - - There is a special case for a zero-length array (the number of elements was - specified as zero during construction). In that case, array.begin() == array.end(), - which is some unique value. The effect of calling front() or back() on a zero-sized - dynarray is undefined. - -.SH Template parameters - - This section is incomplete - - -.SH Member types - - Member type Definition - value_type T - size_type std::size_t - difference_type std::ptrdiff_t - reference value_type& - const_reference const value_type& - pointer value_type* - const_pointer const value_type* - iterator RandomAccessIterator - const_iterator Constant random access iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator - -.SH Member functions - - constructor constructs the dynarray - \fI(public member function)\fP - destructor destructs the dynarray - \fI(public member function)\fP - operator= the container is neither copy-, nor move-assignable - [deleted] \fI(public member function)\fP -.SH Element access - at access specified element with bounds checking - \fI(public member function)\fP - operator[] access specified element - \fI(public member function)\fP - front access the first element - \fI(public member function)\fP - back access the last element - \fI(public member function)\fP - data direct access to the underlying array - \fI(public member function)\fP -.SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP - rend returns a reverse iterator to the end - crend \fI(public member function)\fP -.SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - size returns the number of elements - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP -.SH Modifiers - fill fill the container with specified value - \fI(public member function)\fP - -.SH Non-member functions - - operator== - operator!= - operator< lexicographically compares the values in the dynarray - operator<= \fI(function template)\fP - operator> - operator>= - -.SH Helper classes - - std::uses_allocator specializes the std::uses_allocator type trait - \fI(C++11)\fP \fI(function template)\fP - -.SH Category: - - * Todo without reason diff --git a/man/std::dynarray::at.3 b/man/std::dynarray::at.3 deleted file mode 100644 index 57eaa47a2..000000000 --- a/man/std::dynarray::at.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::dynarray::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reference at( size_type pos ); \fI(since C++14)\fP - const_reference at( size_type pos ) const; - - Returns a reference to the element at specified location pos, with bounds checking. - - If pos not within the range of the container, an exception of type std::out_of_range - is thrown. - -.SH Parameters - - pos - position of the element to return - -.SH Return value - - Reference to the requested element. - -.SH Exceptions - - std::out_of_range if !(pos < size()). - -.SH Complexity - - Constant. - -.SH See also - - operator[] access specified element - \fI(public member function)\fP diff --git a/man/std::dynarray::back.3 b/man/std::dynarray::back.3 deleted file mode 100644 index 6ad2e011f..000000000 --- a/man/std::dynarray::back.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH std::dynarray::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reference back(); \fI(since C++14)\fP - const_reference back() const; \fI(since C++14)\fP - - Returns reference to the last element in the container. - - Calling back on an empty container is undefined. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Reference to the last element. - -.SH Complexity - - Constant. - -.SH Notes - - For a container c, the expression return c.back(); is equivalent to { auto tmp = - c.end(); --tmp; return *tmp; } - -.SH Example - - The following code uses back to display the last element of a std::dynarray: - - -// Run this code - - #include - #include - - int main() - { - std::dynarray letters {'o', 'm', 'g', 'w', 't', 'f'}; - if (!letters.empty()) { - std::cout << "The last character is: " << letters.back() << '\\n'; - } - } - -.SH Output: - - The last character is f - -.SH See also - - front access the first element - \fI(public member function)\fP diff --git a/man/std::dynarray::begin,std::dynarray::cbegin.3 b/man/std::dynarray::begin,std::dynarray::cbegin.3 deleted file mode 100644 index b7ea4e6d1..000000000 --- a/man/std::dynarray::begin,std::dynarray::cbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::dynarray::begin,std::dynarray::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); \fI(since C++14)\fP - const_iterator begin() const; \fI(since C++14)\fP - const_iterator cbegin() const; \fI(since C++14)\fP - - Returns an iterator to the first element of the container. - - If the container is empty, the returned iterator will be equal to end(). - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP diff --git a/man/std::dynarray::data.3 b/man/std::dynarray::data.3 deleted file mode 100644 index d4a76067e..000000000 --- a/man/std::dynarray::data.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::dynarray::data 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - T* data(); \fI(since C++14)\fP - const T* data() const; \fI(since C++14)\fP - - Returns pointer to the underlying array serving as element storage. The pointer is - such that range [data(); data() + size()) is always a valid range, even if the - container is empty. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Pointer to the underlying element storage. For non-empty containers, returns - &front() - -.SH Complexity - - Constant. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - front access the first element - \fI(public member function)\fP - back access the last element - \fI(public member function)\fP diff --git a/man/std::dynarray::dynarray.3 b/man/std::dynarray::dynarray.3 deleted file mode 100644 index b0fbdfccd..000000000 --- a/man/std::dynarray::dynarray.3 +++ /dev/null @@ -1,61 +0,0 @@ -.TH std::dynarray::dynarray 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - explicit dynarray( size_type count ); \fB(1)\fP \fI(since C++14)\fP - template< class Alloc > \fB(2)\fP \fI(since C++14)\fP - dynarray( size_type count, const Alloc& alloc ); - dynarray( size_type count, const T& value ); \fB(3)\fP \fI(since C++14)\fP - template< class Alloc > \fB(4)\fP \fI(since C++14)\fP - dynarray( size_type count, const T& value, const Alloc& alloc ); - dynarray( const dynarray& other ); \fB(5)\fP \fI(since C++14)\fP - template< class Alloc > \fB(6)\fP \fI(since C++14)\fP - dynarray( const dynarray& other, const Alloc& alloc ); - dynarray( std::initializer_list init ); \fB(7)\fP \fI(since C++14)\fP - template< class Alloc > \fB(8)\fP \fI(since C++14)\fP - dynarray( std::initializer_list init, const Alloc& alloc ); - - Constructs a new container from a variety of data sources, optionally using user - supplied allocator alloc. If an allocator is provided, all memory allocations are - done though it. Otherwise, the memory is allocated from an unspecified source, which - may, or may not, invoke the global operator new. This way, additional optimization - opportunities are possible, for example, using stack-based allocation. - - 1-2) Constructs the container with count default-initialized (or constructed by - specified allocator) instances of T. No copies are made. - 3-4) Constructs the container with count copies of elements with value value. T must - meet the requirements of CopyConstructible. - 5-6) Copy-constructor. Constructs the container with the copy of the contents of - other. T must meet the requirements of CopyConstructible. - 7-8) Constructs the container with the contents of the initializer list init. - -.SH Parameters - - alloc - allocator to use for the memory allocations of this container - count - the size of the container - value - the value to initialize elements of the container with - other - another container to be used as source to initialize the elements of the - container with - init - initializer list to initialize the elements of the container with -.SH Type requirements - - - Alloc must meet the requirements of Allocator. - -.SH Complexity - - 1-4) Linear in count - 5-6) Linear in other.size() - 7-8) Linear in size of init - -.SH Exceptions - - 1-4) std::bad_alloc if there's insufficient memory. std::bad_array_length if count - is above the implementation-defined limits. - 5-8) std::bad_alloc if there's insufficient memory. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::dynarray::empty.3 b/man/std::dynarray::empty.3 deleted file mode 100644 index ceab0c2e9..000000000 --- a/man/std::dynarray::empty.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::dynarray::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bool empty() const; \fI(since C++14)\fP - - Checks if the container has no elements, i.e. whether begin() == end(). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH Example - - - Template:cpp/container/dynarray/example empty - -.SH See also - - size returns the number of elements - \fI(public member function)\fP diff --git a/man/std::dynarray::end,std::dynarray::cend.3 b/man/std::dynarray::end,std::dynarray::cend.3 deleted file mode 100644 index f6c77a33b..000000000 --- a/man/std::dynarray::end,std::dynarray::cend.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::dynarray::end,std::dynarray::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end(); \fI(since C++14)\fP - const_iterator end() const; \fI(since C++14)\fP - const_iterator cend() const; \fI(since C++14)\fP - - Returns an iterator to the element following the last element of the container. - - This element acts as a placeholder; attempting to access it results in undefined - behavior. - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the element following the last element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP diff --git a/man/std::dynarray::fill.3 b/man/std::dynarray::fill.3 deleted file mode 100644 index 47c9680b4..000000000 --- a/man/std::dynarray::fill.3 +++ /dev/null @@ -1,17 +0,0 @@ -.TH std::dynarray::fill 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - void fill( const T& value ); \fI(since C++14)\fP - - Assigns the given value value to all elements in the container. - -.SH Parameters - - value - the value to assign to the elements - -.SH Return value - - \fI(none)\fP - -.SH Complexity - - Linear in the size of the container diff --git a/man/std::dynarray::front.3 b/man/std::dynarray::front.3 deleted file mode 100644 index 2eae569de..000000000 --- a/man/std::dynarray::front.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH std::dynarray::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reference front(); \fI(since C++14)\fP - const_reference front() const; \fI(since C++14)\fP - - Returns a reference to the first element in the container. - - Calling front on an empty container is undefined. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - reference to the first element - -.SH Complexity - - Constant - -.SH Notes - - For a container c, the expression c.front() is equivalent to *c.begin(). - -.SH Example - - The following code uses front to display the first element of a std::dynarray: - - -// Run this code - - #include - #include - - int main() - { - std::dynarray letters {'o', 'm', 'g', 'w', 't', 'f'}; - - if (!letters.empty()) { - std::cout << "The first character is: " << letters.front() << '\\n'; - } - } - -.SH Output: - - The first character is o - -.SH See also - - back access the last element - \fI(public member function)\fP diff --git a/man/std::dynarray::max_size.3 b/man/std::dynarray::max_size.3 deleted file mode 100644 index 446dc9bc8..000000000 --- a/man/std::dynarray::max_size.3 +++ /dev/null @@ -1,37 +0,0 @@ -.TH std::dynarray::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type max_size() const; \fI(since C++14)\fP - - Returns the maximum number of elements the container is able to hold due to system - or library implementation limitations, i.e. std::distance(begin(), end()) for the - largest container. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Maximum number of elements. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH Notes - - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the - container may be limited to a value smaller than max_size() by the amount of RAM - available. - -.SH See also - - size returns the number of elements - \fI(public member function)\fP diff --git a/man/std::dynarray::operator[].3 b/man/std::dynarray::operator[].3 deleted file mode 100644 index 44fd9f611..000000000 --- a/man/std::dynarray::operator[].3 +++ /dev/null @@ -1,56 +0,0 @@ -.TH std::dynarray::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reference operator[]( size_type pos ); \fI(since C++14)\fP - const_reference operator[]( size_type pos ) const; \fI(since C++14)\fP - \fI(until C++14)\fP - constexpr const_reference operator[]( size_type pos ) const; \fI(since C++14)\fP - - Returns a reference to the element at specified location pos. No bounds checking is - performed. - -.SH Parameters - - pos - position of the element to return - -.SH Return value - - Reference to the requested element. - -.SH Complexity - - Constant. - -.SH Example - - The following code uses operator[] read from and write to a std::dynarray: - - -// Run this code - - #include - #include - - int main() - { - std::dynarray numbers {2, 4, 6, 8}; - - std::cout << "Second element: " << numbers[1] << '\\n'; - - numbers[0] = 5; - - std::cout << "All numbers:"; - for (auto i : numbers) { - std::cout << ' ' << i; - } - std::cout << '\\n'; - } - -.SH Output: - - Second element: 4 - All numbers: 5 4 6 8 - -.SH See also - - at access specified element with bounds checking - \fI(public member function)\fP diff --git a/man/std::dynarray::rbegin,std::dynarray::crbegin.3 b/man/std::dynarray::rbegin,std::dynarray::crbegin.3 deleted file mode 100644 index daf01f002..000000000 --- a/man/std::dynarray::rbegin,std::dynarray::crbegin.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::dynarray::rbegin,std::dynarray::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rbegin(); \fI(since C++14)\fP - const_reverse_iterator rbegin() const; \fI(since C++14)\fP - const_reverse_iterator crbegin() const; \fI(since C++14)\fP - - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. - - range-rbegin-rend.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Reverse iterator to the first element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - rend returns a reverse iterator to the end - crend \fI(public member function)\fP diff --git a/man/std::dynarray::rend,std::dynarray::crend.3 b/man/std::dynarray::rend,std::dynarray::crend.3 deleted file mode 100644 index 2b876f987..000000000 --- a/man/std::dynarray::rend,std::dynarray::crend.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::dynarray::rend,std::dynarray::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rend(); \fI(since C++14)\fP - const_reverse_iterator rend() const; \fI(since C++14)\fP - const_reverse_iterator crend() const; \fI(since C++14)\fP - - Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. - - range-rbegin-rend.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Reverse iterator to the element following the last element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP diff --git a/man/std::dynarray::size.3 b/man/std::dynarray::size.3 deleted file mode 100644 index f12c7abb1..000000000 --- a/man/std::dynarray::size.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::dynarray::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type size() const; \fI(since C++14)\fP - - Returns the number of elements in the container, i.e. std::distance(begin(), end()). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The number of elements in the container. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH Example - - - Template:cpp/container/dynarray/example size - -.SH See also - - empty checks whether the container is empty - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP diff --git a/man/std::dynarray::~dynarray.3 b/man/std::dynarray::~dynarray.3 deleted file mode 100644 index b5a34c3d4..000000000 --- a/man/std::dynarray::~dynarray.3 +++ /dev/null @@ -1,12 +0,0 @@ -.TH std::dynarray::~dynarray 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - ~dynarray(); \fI(since C++14)\fP - - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. The global operator delete is called only if the operator - new was called during construction - -.SH Complexity - - Linear in the size of the container. diff --git a/man/std::ellint_1,std::ellint_1f,std::ellint_1l.3 b/man/std::ellint_1,std::ellint_1f,std::ellint_1l.3 new file mode 100644 index 000000000..ffd7da8f2 --- /dev/null +++ b/man/std::ellint_1,std::ellint_1f,std::ellint_1l.3 @@ -0,0 +1,138 @@ +.TH std::ellint_1,std::ellint_1f,std::ellint_1l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ellint_1,std::ellint_1f,std::ellint_1l \- std::ellint_1,std::ellint_1f,std::ellint_1l + +.SH Synopsis + Defined in header + float ellint_1 ( float k, float phi ); + \fI(since C++17)\fP + double ellint_1 ( double k, double phi ); (until C++23) + + long double ellint_1 ( long double k, long double phi ); + /* floating-point-type */ ellint_1( /* floating-point-type */ + k, (since C++23) + /* floating-point-type */ + phi ); \fB(1)\fP + float ellint_1f( float k, float phi ); \fB(2)\fP \fI(since C++17)\fP + long double ellint_1l( long double k, long double phi ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + ellint_1( Arithmetic1 k, Arithmetic2 phi ); + + 1-3) Computes the incomplete elliptic integral of the first kind of k and phi. + The library provides overloads of std::ellint_1 for all cv-unqualified + floating-point types as the type of the parameters k and phi. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + k - elliptic modulus or eccentricity (a floating-point or integer value) + phi - Jacobi amplitude (a floating-point or integer value, measured in radians) + +.SH Return value + + If no errors occur, value of the incomplete elliptic integral of the first kind of k + and phi, that is ∫phi + 0 + + dθ + √ + 1-k2 + sin2 + θ + + , is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling: + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If |k|>1, a domain error may occur. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::ellint_1(num1, + num2) has the same effect as std::ellint_1(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::ellint_1(num1, num2) has the same effect as (until C++23) + std::ellint_1(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::ellint_1(num1, num2) has the same effect as + std::ellint_1(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::ellint_1(num1, num2) + has the same effect as std::ellint_1(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const double hpi = std::numbers::pi / 2.0; + + std::cout << "F(0,π/2) = " << std::ellint_1(0, hpi) << '\\n' + << "F(0,-π/2) = " << std::ellint_1(0, -hpi) << '\\n' + << "π/2 = " << hpi << '\\n' + << "F(0.7,0) = " << std::ellint_1(0.7, 0) << '\\n'; + } + +.SH Output: + + F(0,π/2) = 1.5708 + F(0,-π/2) = -1.5708 + π/2 = 1.5708 + F(0.7,0) = 0 + +.SH See also + + comp_ellint_1 + comp_ellint_1f + comp_ellint_1l (complete) elliptic integral of the first kind + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Elliptic Integral of the First Kind." From MathWorld — A Wolfram + Web Resource. diff --git a/man/std::ellint_2,std::ellint_2f,std::ellint_2l.3 b/man/std::ellint_2,std::ellint_2f,std::ellint_2l.3 new file mode 100644 index 000000000..1e8fd7609 --- /dev/null +++ b/man/std::ellint_2,std::ellint_2f,std::ellint_2l.3 @@ -0,0 +1,136 @@ +.TH std::ellint_2,std::ellint_2f,std::ellint_2l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ellint_2,std::ellint_2f,std::ellint_2l \- std::ellint_2,std::ellint_2f,std::ellint_2l + +.SH Synopsis + Defined in header + float ellint_2 ( float k, float phi ); + \fI(since C++17)\fP + double ellint_2 ( double k, double phi ); (until C++23) + + long double ellint_2 ( long double k, long double phi ); + /* floating-point-type */ ellint_2( /* floating-point-type */ + k, (since C++23) + /* floating-point-type */ + phi ); \fB(1)\fP + float ellint_2f( float k, float phi ); \fB(2)\fP \fI(since C++17)\fP + long double ellint_2l( long double k, long double phi ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + ellint_2( Arithmetic1 k, Arithmetic2 phi ); + + 1-3) Computes the incomplete elliptic integral of the second kind of k and phi. + The library provides overloads of std::ellint_2 for all cv-unqualified + floating-point types as the type of the parameters k and phi. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + k - elliptic modulus or eccentricity (a floating-point or integer value) + phi - Jacobi amplitude (a floating-point or integer value, measured in radians) + +.SH Return value + + If no errors occur, value of the incomplete elliptic integral of the second kind of + k and phi, that is ∫phi + 0 + √ + 1-k2 + sin2 + θdθ, is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling: + + * If the argument is NaN, NaN is returned and domain error is not reported + * If |k|>1, a domain error may occur + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::ellint2(num1, + num2) has the same effect as std::ellint2(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::ellint2(num1, num2) has the same effect as (until C++23) + std::ellint2(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::ellint2(num1, + num2) has the same effect as + std::ellint2(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::ellint2(num1, num2) + has the same effect as std::ellint2(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const double hpi = std::numbers::pi / 2.0; + + std::cout << "E(0,π/2) = " << std::ellint_2(0, hpi) << '\\n' + << "E(0,-π/2) = " << std::ellint_2(0, -hpi) << '\\n' + << "π/2 = " << hpi << '\\n' + << "E(0.7,0) = " << std::ellint_2(0.7, 0) << '\\n' + << "E(1,π/2) = " << std::ellint_2(1, hpi) << '\\n'; + } + +.SH Output: + + E(0,π/2) = 1.5708 + E(0,-π/2) = -1.5708 + π/2 = 1.5708 + E(0.7,0) = 0 + E(1,π/2) = 1 + +.SH See also + + comp_ellint_2 + comp_ellint_2f + comp_ellint_2l (complete) elliptic integral of the second kind + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Elliptic Integral of the Second Kind." From MathWorld — A + Wolfram Web Resource. diff --git a/man/std::ellint_3,std::ellint_3f,std::ellint_3l.3 b/man/std::ellint_3,std::ellint_3f,std::ellint_3l.3 new file mode 100644 index 000000000..3cdd9dd1c --- /dev/null +++ b/man/std::ellint_3,std::ellint_3f,std::ellint_3l.3 @@ -0,0 +1,156 @@ +.TH std::ellint_3,std::ellint_3f,std::ellint_3l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ellint_3,std::ellint_3f,std::ellint_3l \- std::ellint_3,std::ellint_3f,std::ellint_3l + +.SH Synopsis + Defined in header + float ellint_3 ( float k, float nu, float phi ); + + double ellint_3 ( double k, double nu, double phi ); \fI(since C++17)\fP + (until C++23) + long double ellint_3 ( long double k, long double nu, long + double phi ); + /* floating-point-type */ ellint_3( /* floating-point-type */ + k, + + /* floating-point-type */ (since C++23) + nu, + + /* floating-point-type */ \fB(1)\fP + phi ); + float ellint_3f( float k, float nu, float phi ); \fB(2)\fP \fI(since C++17)\fP + long double ellint_3l( long double k, long double nu, long \fB(3)\fP \fI(since C++17)\fP + double phi ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2, class + Arithmetic3 > + + /* common-floating-point-type */ (A) \fI(since C++17)\fP + + ellint_3( Arithmetic1 k, Arithmetic2 nu, Arithmetic3 phi + ); + + 1-3) Computes the incomplete elliptic integral of the third kind of k, nu, and phi. + The library provides overloads of std::ellint_3 for all cv-unqualified + floating-point types as the type of the parameters k, nu and phi. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + k - elliptic modulus or eccentricity (a floating-point or integer value) + nu - elliptic characteristic (a floating-point or integer value) + phi - Jacobi amplitude (a floating-point or integer value, measured in radians) + +.SH Return value + + If no errors occur, value of the incomplete elliptic integral of the third kind of + k, nu, and phi, that is ∫phi + 0 + + dθ + (1-nusin2 + θ) + √ + 1-k2 + sin2 + θ + + , is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling: + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If |k|>1, a domain error may occur. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1, second argument + num2 and third argument num3: + + * If num1, num2 or num3 has type long double, then + std::ellint_3(num1, num2, num3) has the same effect as + std::ellint_3(static_cast(num1), + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 and/or num3 has type double or an integer + type, then std::ellint_3(num1, num2, num3) has the same effect as + std::ellint_3(static_cast(num1), (until C++23) + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 or num3 has type float, then + std::ellint_3(num1, num2, num3) has the same effect as + std::ellint_3(static_cast(num1), + static_cast(num2), + static_cast(num3)). + If num1, num2 and num3 have arithmetic types, then std::ellint_3(num1, + num2, num3) has the same effect as std::ellint_3(static_cast(num1), + static_cast(num2), + static_cast(num3)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest (since C++23) + floating-point conversion subrank among the types of num1, num2 and + num3, arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const double hpi = std::numbers::pi / 2; + + std::cout << "Π(0,0,π/2) = " << std::ellint_3(0, 0, hpi) << '\\n' + << "π/2 = " << hpi << '\\n'; + } + +.SH Output: + + Π(0,0,π/2) = 1.5708 + π/2 = 1.5708 + + This section is incomplete + Reason: this and other elliptic integrals deserve better examples.. perhaps + calculate elliptic arc length? + +.SH See also + + comp_ellint_3 + comp_ellint_3f + comp_ellint_3l (complete) elliptic integral of the third kind + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Elliptic Integral of the Third Kind." From MathWorld — A Wolfram + Web Resource. + +.SH Category: + * Todo with reason diff --git a/man/std::emit_on_flush,std::noemit_on_flush.3 b/man/std::emit_on_flush,std::noemit_on_flush.3 new file mode 100644 index 000000000..1376d072a --- /dev/null +++ b/man/std::emit_on_flush,std::noemit_on_flush.3 @@ -0,0 +1,46 @@ +.TH std::emit_on_flush,std::noemit_on_flush 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::emit_on_flush,std::noemit_on_flush \- std::emit_on_flush,std::noemit_on_flush + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + std::basic_ostream& emit_on_flush( \fB(1)\fP \fI(since C++20)\fP + std::basic_ostream& os ); + template< class CharT, class Traits > + std::basic_ostream& noemit_on_flush( \fB(2)\fP \fI(since C++20)\fP + std::basic_ostream& os ); + + If os.rdbuf() actually points to a std::basic_syncbuf buf, + toggles whether it emits (i.e., transmits data to the underlying stream buffer) when + flushed: + + 1) calls buf.set_emit_on_sync(true) + 2) calls buf.set_emit_on_sync(false) + + Otherwise, these manipulators have no effect. + + This is an output-only I/O manipulator, it may be called with an expression such as + out << std::emit_on_flush for any out of type std::basic_ostream. + +.SH Parameters + + os - reference to output stream + +.SH Return value + + os (reference to the stream after manipulation) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + changes the current emit-on-sync policy + set_emit_on_sync \fI\fI(public member\fP function of\fP + std::basic_syncbuf) + +.SH Category: + * Todo no example diff --git a/man/std::empty.3 b/man/std::empty.3 new file mode 100644 index 000000000..511ddeda3 --- /dev/null +++ b/man/std::empty.3 @@ -0,0 +1,142 @@ +.TH std::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::empty \- std::empty + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + template< class C > (since + constexpr auto empty( const C& c ) -> C++17) + decltype(c.empty()); (until + C++20) + template< class C > (since + [[nodiscard]] constexpr auto empty( const C& c ) -> C++20) + decltype(c.empty()); + template< class T, std::size_t N > (since + constexpr bool empty( const T (&array)[N] ) C++17) + noexcept; (until + \fB(1)\fP C++20) + template< class T, std::size_t N > (since + [[nodiscard]] constexpr bool empty( const T C++20) + (&array)[N] ) noexcept; \fB(2)\fP + template< class E > (since + constexpr bool empty( std::initializer_list il ) C++17) + noexcept; (until + \fB(3)\fP C++20) + template< class E > (since + [[nodiscard]] constexpr bool empty( C++20) + std::initializer_list il ) noexcept; + + Returns whether the given range is empty. + + 1) Returns c.empty(). + 2) Returns false. + 3) Returns il.size() == 0. + +.SH Parameters + + c - a container or view with an empty member function + array - an array of arbitrary type + il - an std::initializer_list + +.SH Return value + + 1) c.empty() + 2) false + 3) il.size() == 0 + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + +.SH Notes + + The overload for std::initializer_list is necessary because it does not have a + member function empty. + + Feature-test macro Value Std Feature + __cpp_lib_nonmember_container_access 201411L \fI(C++17)\fP std::size(), std::data(), and + std::empty() + +.SH Possible implementation + +.SH First version + template + [[nodiscard]] constexpr auto empty(const C& c) -> decltype(c.empty()) + { + return c.empty(); + } +.SH Second version + template + [[nodiscard]] constexpr bool empty(const T (&array)[N]) noexcept + { + return false; + } + Third version + template + [[nodiscard]] constexpr bool empty(std::initializer_list il) noexcept + { + return il.size() == 0; + } + +.SH Example + + +// Run this code + + #include + #include + + template + void print(const T& container) + { + if (std::empty(container)) + std::cout << "Empty\\n"; + else + { + std::cout << "Elements:"; + for (const auto& element : container) + std::cout << ' ' << element; + std::cout << '\\n'; + } + } + + int main() + { + std::vector c = {1, 2, 3}; + print(c); + c.clear(); + print(c); + + int array[] = {4, 5, 6}; + print(array); + + auto il = {7, 8, 9}; + print(il); + } + +.SH Output: + + Elements: 1 2 3 + Empty + Elements: 4 5 6 + Elements: 7 8 9 + +.SH See also + + ranges::empty checks whether a range is empty + (C++20) (customization point object) diff --git a/man/std::enable_if.3 b/man/std::enable_if.3 index f52ba8530..d43ed3a40 100644 --- a/man/std::enable_if.3 +++ b/man/std::enable_if.3 @@ -1,4 +1,7 @@ -.TH std::enable_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::enable_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_if \- std::enable_if + .SH Synopsis Defined in header template< bool B, class T = void > \fI(since C++11)\fP @@ -7,12 +10,18 @@ If B is true, std::enable_if has a public member typedef type, equal to T; otherwise, there is no member typedef. - This metafunction is used to conditionally remove functions and classes from - overload resolution based on type traits and to provide separate function overloads - and specializations for different type traits. std::enable_if can be used as an - additional function argument (not applicable to operator overloads), as a return - type (not applicable to constructors and destructors), or as a class template or - function template parameter. + This metafunction is a convenient way to leverage SFINAE prior to C++20's concepts, + in particular for conditionally removing functions from the candidate set based on + type traits, allowing separate function overloads or specializations based on those + different type traits. + + std::enable_if can be used in many forms, including: + + * as an additional function argument (not applicable to most operator overloads), + * as a return type (not applicable to constructors and destructors), + * as a class template or function template parameter. + + If the program adds specializations for std::enable_if, the behavior is undefined. .SH Member types @@ -28,78 +37,197 @@ template struct enable_if {}; - + template struct enable_if { typedef T type; }; +.SH Notes + + A common mistake is to declare two function templates that differ only in their + default template arguments. This does not work because the declarations are treated + as redeclarations of the same function template (default template arguments are not + accounted for in function template equivalence). + + /* WRONG */ + + struct T + { + enum { int_t, float_t } type; + + template::value>> + T(Integer) : type(int_t) {} + + template::value>> + T(Floating) : type(float_t) {} // error: treated as redefinition + }; + + /* RIGHT */ + + struct T + { + enum { int_t, float_t } type; + + template::value, bool> = true> + T(Integer) : type(int_t) {} + + template::value, bool> = true> + T(Floating) : type(float_t) {} // OK + }; + + Care should be taken when using enable_if in the type of a template non-type + parameter of a namespace-scope function template. Some ABI specifications like the + Itanium ABI do not include the instantiation-dependent portions of non-type template + parameters in the mangling, meaning that specializations of two distinct function + templates might end up with the same mangled name and be erroneously linked + together. For example: + + // first translation unit + + struct X + { + enum { value1 = true, value2 = true }; + }; + + template = 0> + void func() {} // #1 + + template void func(); // #2 + + // second translation unit + + struct X + { + enum { value1 = true, value2 = true }; + }; + + template = 0> + void func() {} // #3 + + template void func(); // #4 + + The function templates #1 and #3 have different signatures and are distinct + templates. Nonetheless, #2 and #4, despite being instantiations of different + function templates, have the same mangled name in the Itanium C++ ABI + (_Z4funcI1XLi0EEvv), meaning that the linker will erroneously consider them to be + the same entity. + .SH Example - + // Run this code - #include #include - - // foo1 overloads are enabled via the return type + #include + #include + #include + + namespace detail + { + void* voidify(const volatile void* ptr) noexcept { return const_cast(ptr); } + } + + // #1, enabled via the return type template - typename std::enable_if::value, T>::type - foo1(T t) + typename std::enable_if::value>::type + construct(T*) { - std::cout << "foo1: float\\n"; - return t; + std::cout << "default constructing trivially default constructible T\\n"; } - + + // same as above template - std::enable_if_t::value, T> //Using helper type - foo1(T t) + typename std::enable_if::value>::type + construct(T* p) + { + std::cout << "default constructing non-trivially default constructible T\\n"; + ::new(detail::voidify(p)) T; + } + + // #2 + template + std::enable_if_t::value> // Using helper type + construct(T* p, Args&&... args) { - std::cout << "foo1: int\\n"; - return t; + std::cout << "constructing T with operation\\n"; + ::new(detail::voidify(p)) T(static_cast(args)...); } - - // foo2 overload is enabled via a parameter + + // #3, enabled via a parameter template - T foo2(T t, typename std::enable_if::value >::type* = 0) + void destroy( + T*, + typename std::enable_if< + std::is_trivially_destructible::value + >::type* = 0) { - return t; + std::cout << "destroying trivially destructible T\\n"; } - - // foo3 overload is enabled via a template parameter - template::value>::type > - T foo3(T t) // note, function signature is unmodified + + // #4, enabled via a non-type template parameter + template{} && + (std::is_class{} || std::is_union{}), + bool>::type = true> + void destroy(T* t) { - return t; + std::cout << "destroying non-trivially destructible T\\n"; + t->~T(); } - - // A is enabled via a template parameter + + // #5, enabled via a type template parameter + template::value>> + void destroy(T* t) // note: function signature is unmodified + { + for (std::size_t i = 0; i < std::extent::value; ++i) + destroy((*t)[i]); + } + + /* + template::value>> + void destroy(T* t) {} // error: has the same signature with #5 + */ + + // the partial specialization of A is enabled via a template parameter template - class A; // undefined - + class A {}; // primary template + template - class A::value >::type> { - }; - + class A::value>::type> + {}; // specialization for floating point types + int main() { - foo1(1.2); // OK, calls the first version of foo1() - foo1(10); // OK, calls the second version of foo1() - - // foo2(0.1); // compile-time error - foo2(7); // OK - - // foo3(1.2); // compile-time error - foo3(34); // OK - - // A a1; // compile-time error - A a1; // OK + union { int i; char s[sizeof(std::string)]; } u; + + construct(reinterpret_cast(&u)); + destroy(reinterpret_cast(&u)); + + construct(reinterpret_cast(&u), "Hello"); + destroy(reinterpret_cast(&u)); + + A{}; // OK: matches the primary template + A{}; // OK: matches the partial specialization } .SH Output: - foo1: float - foo1: int + default constructing trivially default constructible T + destroying trivially destructible T + constructing T with operation + destroying non-trivially destructible T .SH See also + void_t void variadic alias template + \fI(C++17)\fP (alias template) + * static_assert + * SFINAE + * Constraints and Concepts diff --git a/man/std::enable_nonlocking_formatter_optimization.3 b/man/std::enable_nonlocking_formatter_optimization.3 new file mode 100644 index 000000000..4ab7dcc89 --- /dev/null +++ b/man/std::enable_nonlocking_formatter_optimization.3 @@ -0,0 +1,75 @@ +.TH std::enable_nonlocking_formatter_optimization 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_nonlocking_formatter_optimization \- std::enable_nonlocking_formatter_optimization + +.SH Synopsis + Defined in header + template< class T > (since C++23) + constexpr bool enable_nonlocking_formatter_optimization = false; + + This template can be used by implementations to enable efficient implementations of + std::print and std::println. + + If std::enable_nonlocking_formatter_optimization is true, printing an argument of + type T can be performed in a more efficient way (see std::print for details). + std::enable_nonlocking_formatter_optimization specializations can be true in the + following cases: + + * T is one of the types where std::format is a basic standard + specialization (see below). + * A program may specialize this template for any cv-unqualified program-defined + type T. Such specializations must be usable in constant expressions and have + type const bool. + + Basic standard specializations + + In the following list, CharT is either char or wchar_t, ArithmeticT is any + cv-unqualified arithmetic type other than char, wchar_t, char8_t, char16_t, or + char32_t: + + Nonlocking flag for character formatters + template<> \fB(1)\fP + inline constexpr bool enable_nonlocking_formatter_optimization = true; + Nonlocking flag for string formatters + template<> \fB(2)\fP + inline constexpr bool enable_nonlocking_formatter_optimization = true; + template<> + inline constexpr bool enable_nonlocking_formatter_optimization = \fB(3)\fP + true; + template< std::size_t N > + inline constexpr bool enable_nonlocking_formatter_optimization = \fB(4)\fP + true; + template< class Traits, class Alloc > + + inline constexpr bool enable_nonlocking_formatter_optimization \fB(5)\fP + + > = true; + template< class Traits > + + inline constexpr bool enable_nonlocking_formatter_optimization \fB(6)\fP + + > = true; + Nonlocking flag for arithmetic formatters + template<> + inline constexpr bool enable_nonlocking_formatter_optimization = \fB(7)\fP + true; + Nonlocking flag for pointer formatters + template<> + inline constexpr bool enable_nonlocking_formatter_optimization \fB(8)\fP + = true; + template<> \fB(9)\fP + inline constexpr bool enable_nonlocking_formatter_optimization = true; + template<> + inline constexpr bool enable_nonlocking_formatter_optimization = \fB(10)\fP + true; + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP + print prints to stdout or a file stream using formatted representation of the + (C++23) arguments + \fI(function template)\fP + println same as std::print except that each print is terminated by additional new + (C++23) line + \fI(function template)\fP diff --git a/man/std::enable_shared_from_this.3 b/man/std::enable_shared_from_this.3 index 8c6aa147d..94ecf6020 100644 --- a/man/std::enable_shared_from_this.3 +++ b/man/std::enable_shared_from_this.3 @@ -1,4 +1,7 @@ -.TH std::enable_shared_from_this 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::enable_shared_from_this 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_shared_from_this \- std::enable_shared_from_this + .SH Synopsis Defined in header template< class T > class enable_shared_from_this; \fI(since C++11)\fP @@ -7,81 +10,173 @@ std::shared_ptr named pt to safely generate additional std::shared_ptr instances pt1, pt2, ... that all share ownership of t with pt. - Inheriting from std::enable_shared_from_this provides the type T with a member - function shared_from_this. If an object t of type T is managed by a + Publicly inheriting from std::enable_shared_from_this provides the type T with a + member function shared_from_this. If an object t of type T is managed by a std::shared_ptr named pt, then calling T::shared_from_this will return a new std::shared_ptr that shares ownership of t with pt. - Note that prior to calling shared_from_this on an object t, there must be a - std::shared_ptr that owns t. - - Also note that enable_shared_from_this provides an alternative to an expression like - std::shared_ptr(this), which is likely to result in this being destructed more - than once by multiple owners that are unaware of each other. - .SH Member functions - constructor constructs an enabled_shared_from_this object + constructor constructs an enable_shared_from_this object \fI(protected member function)\fP destructor destroys an enable_shared_from_this object \fI(protected member function)\fP - operator= returns a reference to this + operator= returns a reference to *this \fI(protected member function)\fP - shared_from_this returns a shared_ptr which shares ownership of *this + shared_from_this returns a std::shared_ptr which shares ownership of *this \fI(public member function)\fP + weak_from_this returns a std::weak_ptr which shares ownership of *this + \fI(C++17)\fP \fI(public member function)\fP + +.SH Member objects + + Member name Definition + weak-this (exposition only) std::weak_ptr object tracking the control block of the + first shared owner of *this. .SH Notes A common implementation for enable_shared_from_this is to hold a weak reference - (such as std::weak_ptr) to this. The constructors of std::shared_ptr can detect - presence of a enable_shared_from_this base and share ownership with the existing - std::shared_ptrs, instead of assuming the pointer is not managed by anyone else. + (such as std::weak_ptr) to *this. For the purpose of exposition, the weak reference + is called weak-this and considered as a mutable std::weak_ptr member. + + The constructors of std::shared_ptr detect the presence of an unambiguous and + accessible (i.e. public inheritance is mandatory) enable_shared_from_this base and + assign the newly created std::shared_ptr to weak-this if not already owned by a live + std::shared_ptr. Constructing a std::shared_ptr for an object that is already + managed by another std::shared_ptr will not consult weak-this and thus will lead to + undefined behavior. + + It is permitted to call shared_from_this only on a previously shared object, i.e. on + an object managed by std::shared_ptr. Otherwise, std::bad_weak_ptr is thrown (by + the shared_ptr constructor from a default-constructed weak-this). + + enable_shared_from_this provides the safe alternative to an expression like + std::shared_ptr(this), which is likely to result in this being destructed more + than once by multiple owners that are unaware of each other (see example below). .SH Example - + // Run this code - #include #include - - struct Good: std::enable_shared_from_this + #include + + class Good : public std::enable_shared_from_this { - std::shared_ptr getptr() { + public: + std::shared_ptr getptr() + { + return shared_from_this(); + } + }; + + class Best : public std::enable_shared_from_this + { + struct Private{ explicit Private() = default; }; + + public: + // Constructor is only usable by this class + Best(Private) {} + + // Everyone else has to use this factory function + // Hence all Best objects will be contained in shared_ptr + static std::shared_ptr create() + { + return std::make_shared(Private()); + } + + std::shared_ptr getptr() + { return shared_from_this(); } }; - + + struct Bad { - std::shared_ptr getptr() { + std::shared_ptr getptr() + { return std::shared_ptr(this); } ~Bad() { std::cout << "Bad::~Bad() called\\n"; } }; - - int main() + + void testGood() { // Good: the two shared_ptr's share the same object - std::shared_ptr gp1(new Good); - std::shared_ptr gp2 = gp1->getptr(); - std::cout << "gp2.use_count() = " << gp2.use_count() << '\\n'; - + std::shared_ptr good0 = std::make_shared(); + std::shared_ptr good1 = good0->getptr(); + std::cout << "good1.use_count() = " << good1.use_count() << '\\n'; + } + + void misuseGood() + { + // Bad: shared_from_this is called without having std::shared_ptr owning the caller + try + { + Good not_so_good; + std::shared_ptr gp1 = not_so_good.getptr(); + } + catch (std::bad_weak_ptr& e) + { + // undefined behavior \fI(until C++17)\fP and std::bad_weak_ptr thrown \fI(since C++17)\fP + std::cout << e.what() << '\\n'; + } + } + + void testBest() + { + // Best: Same but can't stack-allocate it: + std::shared_ptr best0 = Best::create(); + std::shared_ptr best1 = best0->getptr(); + std::cout << "best1.use_count() = " << best1.use_count() << '\\n'; + + // Best stackBest; // <- Will not compile because Best::Best() is private. + } + + void testBad() + { // Bad, each shared_ptr thinks it's the only owner of the object - std::shared_ptr bp1(new Bad); - std::shared_ptr bp2 = bp1->getptr(); - std::cout << "bp2.use_count() = " << bp2.use_count() << '\\n'; + std::shared_ptr bad0 = std::make_shared(); + std::shared_ptr bad1 = bad0->getptr(); + std::cout << "bad1.use_count() = " << bad1.use_count() << '\\n'; } // UB: double-delete of Bad -.SH Output: + int main() + { + testGood(); + misuseGood(); + + testBest(); - gp2.use_count() = 2 - bp2.use_count() = 1 + testBad(); + } + +.SH Possible output: + + good1.use_count() = 2 + bad_weak_ptr + best1.use_count() = 2 + bad1.use_count() = 1 Bad::~Bad() called Bad::~Bad() called *** glibc detected *** ./test: double free or corruption + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2529 C++11 specification for enable_shared_from_this was clarified and + unclear and maybe unimplementable fixed + .SH See also - shared_ptr smart pointer with shared object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + shared_ptr smart pointer with shared object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) diff --git a/man/std::enable_shared_from_this::enable_shared_from_this.3 b/man/std::enable_shared_from_this::enable_shared_from_this.3 index 372eedd77..31ee23ca6 100644 --- a/man/std::enable_shared_from_this::enable_shared_from_this.3 +++ b/man/std::enable_shared_from_this::enable_shared_from_this.3 @@ -1,38 +1,44 @@ -.TH std::enable_shared_from_this::enable_shared_from_this 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::enable_shared_from_this::enable_shared_from_this 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_shared_from_this::enable_shared_from_this \- std::enable_shared_from_this::enable_shared_from_this + .SH Synopsis - constexpr enable_shared_from_this(); \fB(1)\fP \fI(since C++11)\fP - enable_shared_from_this( const enable_shared_from_this&obj ); \fB(2)\fP \fI(since C++11)\fP + constexpr enable_shared_from_this() noexcept; \fB(1)\fP \fI(since C++11)\fP + enable_shared_from_this( const enable_shared_from_this& other ) \fB(2)\fP \fI(since C++11)\fP + noexcept; - Constructs new enable_shared_from_this object. + Constructs a new enable_shared_from_this object. The exposition only + std::weak_ptr member weak-this is value-initialized. .SH Parameters - obj - an enable_shared_from_this to copy + other - an enable_shared_from_this to copy -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + There is no move constructor: moving from an object derived from + enable_shared_from_this does not transfer its shared identity. .SH Example - + // Run this code #include - - struct Foo : public std::enable_shared_from_this { - Foo() {} // implicitly calls enable_shared_from_this constructor + + struct Foo : public std::enable_shared_from_this + { + Foo() {} // implicitly calls enable_shared_from_this constructor std::shared_ptr getFoo() { return shared_from_this(); } }; - - int main() { + + int main() + { std::shared_ptr pf1(new Foo); - auto pf2 = pf1->getFoo(); // shares ownership of object with pf1 + auto pf2 = pf1->getFoo(); // shares ownership of object with pf1 } .SH See also shared_ptr smart pointer with shared object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::enable_shared_from_this::operator=.3 b/man/std::enable_shared_from_this::operator=.3 index 15881a810..4c2e2da20 100644 --- a/man/std::enable_shared_from_this::operator=.3 +++ b/man/std::enable_shared_from_this::operator=.3 @@ -1,35 +1,37 @@ -.TH std::enable_shared_from_this::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::enable_shared_from_this::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_shared_from_this::operator= \- std::enable_shared_from_this::operator= + .SH Synopsis - enable_shared_from_this& operator=( const \fI(since C++11)\fP - enable_shared_from_this &obj ); + enable_shared_from_this& operator=( const enable_shared_from_this \fI(since C++11)\fP + &rhs ) noexcept; Does nothing; returns *this. .SH Parameters - obj - an enable_shared_from_this to assign to *this + rhs - another enable_shared_from_this to assign to *this .SH Return value *this -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + The exposition-only std::weak_ptr member weak-this is not affected by this + assignment operator. .SH Example Note: enable_shared_from_this::operator= is defined as protected in order to prevent accidental slicing but allow derived classes to have default assignment operators. - + // Run this code - #include #include - + #include + class SharedInt : public std::enable_shared_from_this { public: @@ -37,23 +39,24 @@ SharedInt(const SharedInt&) = default; SharedInt(SharedInt&&) = default; ~SharedInt() = default; - + // Both assignment operators use enable_shared_from_this::operator= SharedInt& operator=(const SharedInt&) = default; SharedInt& operator=(SharedInt&&) = default; - + int number() const { return mNumber; } - + private: int mNumber; }; - - int main() { + + int main() + { std::shared_ptr a = std::make_shared(2); std::shared_ptr b = std::make_shared(4); *a = *b; - - std::cout << a->number() << std::endl; + + std::cout << a->number() << '\\n'; } .SH Output: @@ -63,4 +66,4 @@ .SH See also shared_ptr smart pointer with shared object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::enable_shared_from_this::shared_from_this.3 b/man/std::enable_shared_from_this::shared_from_this.3 index 545385128..076e46997 100644 --- a/man/std::enable_shared_from_this::shared_from_this.3 +++ b/man/std::enable_shared_from_this::shared_from_this.3 @@ -1,44 +1,53 @@ -.TH std::enable_shared_from_this::shared_from_this 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::enable_shared_from_this::shared_from_this 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_shared_from_this::shared_from_this \- std::enable_shared_from_this::shared_from_this + .SH Synopsis - shared_ptr shared_from_this(); \fB(1)\fP - shared_ptr shared_from_this() const; \fB(2)\fP + std::shared_ptr shared_from_this(); \fB(1)\fP \fI(since C++11)\fP + std::shared_ptr shared_from_this() const; \fB(2)\fP \fI(since C++11)\fP Returns a std::shared_ptr that shares ownership of *this with all existing - std::shared_ptr that refer to *this. - -.SH Notes + std::shared_ptr that refer to *this. - Before calling shared_from_this, there should be at least one std::shared_ptr p - that owns *this. + Effectively executes std::shared_ptr(weak_this), where weak-this is the + exposition-only mutable std::weak_ptr member of enable_shared_from_this. .SH Return value std::shared_ptr that shares ownership of *this with pre-existing - std::shared_ptrs + std::shared_ptrs. + +.SH Exceptions + + If shared_from_this is called on an object that is not previously shared by + std::shared_ptr, std::bad_weak_ptr is thrown (by the shared_ptr constructor from a + default-constructed weak-this). .SH Example - + // Run this code #include #include - - struct Foo : public std::enable_shared_from_this { + + struct Foo : public std::enable_shared_from_this + { Foo() { std::cout << "Foo::Foo\\n"; } ~Foo() { std::cout << "Foo::~Foo\\n"; } std::shared_ptr getFoo() { return shared_from_this(); } }; - - int main() { + + int main() + { Foo *f = new Foo; std::shared_ptr pf1; - + { std::shared_ptr pf2(f); - pf1 = pf2->getFoo(); // shares ownership of object with pf2 + pf1 = pf2->getFoo(); // shares ownership of object with pf2 } - + std::cout << "pf2 is gone\\n"; } @@ -48,7 +57,17 @@ pf2 is gone Foo::~Foo + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + calling shared_from_this on an + LWG 2529 C++11 unshared object was undefined std::bad_weak_ptr is thrown + behavior + .SH See also shared_ptr smart pointer with shared object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::enable_shared_from_this::weak_from_this.3 b/man/std::enable_shared_from_this::weak_from_this.3 new file mode 100644 index 000000000..ff5d10fa9 --- /dev/null +++ b/man/std::enable_shared_from_this::weak_from_this.3 @@ -0,0 +1,35 @@ +.TH std::enable_shared_from_this::weak_from_this 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_shared_from_this::weak_from_this \- std::enable_shared_from_this::weak_from_this + +.SH Synopsis + std::weak_ptr weak_from_this() noexcept; \fB(1)\fP \fI(since C++17)\fP + std::weak_ptr weak_from_this() const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Returns a std::weak_ptr that tracks ownership of *this by all existing + std::shared_ptr that refer to *this. + +.SH Return value + + std::weak_ptr that shares ownership of *this with pre-existing std::shared_ptrs. + +.SH Notes + + weak_from_this copies the exposition only weak_ptr member that is part of + enable_shared_from_this. + + Feature-test macro Value Std Feature +__cpp_lib_enable_shared_from_this 201603L \fI(C++17)\fP std::enable_shared_from_this::weak_from_this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + shared_ptr smart pointer with shared object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::enable_shared_from_this::~enable_shared_from_this.3 b/man/std::enable_shared_from_this::~enable_shared_from_this.3 index 93490cfe6..31149ffe9 100644 --- a/man/std::enable_shared_from_this::~enable_shared_from_this.3 +++ b/man/std::enable_shared_from_this::~enable_shared_from_this.3 @@ -1,10 +1,13 @@ -.TH std::enable_shared_from_this::~enable_shared_from_this 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::enable_shared_from_this::~enable_shared_from_this 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::enable_shared_from_this::~enable_shared_from_this \- std::enable_shared_from_this::~enable_shared_from_this + .SH Synopsis - ~enable_shared_from_this(); + ~enable_shared_from_this(); \fI(since C++11)\fP Destroys *this. .SH See also shared_ptr smart pointer with shared object ownership semantics - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::end(std::initializer_list).3 b/man/std::end(std::initializer_list).3 index 5265dc2ac..5e2c95d62 100644 --- a/man/std::end(std::initializer_list).3 +++ b/man/std::end(std::initializer_list).3 @@ -1,12 +1,16 @@ -.TH std::end(std::initializer_list) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::end(std::initializer_list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::end(std::initializer_list) \- std::end(std::initializer_list) + .SH Synopsis - template< class E > \fI(since C++11)\fP - const E* end( initializer_list il ); - template< class E > \fI(since C++11)\fP - constexpr const E* end( initializer_list il ); \fI(until C++14)\fP + Defined in header + template< class E > \fI(since C++11)\fP + const E* end( std::initializer_list il ) noexcept; \fI(until C++14)\fP + template< class E > \fI(since C++14)\fP + constexpr const E* end( std::initializer_list il ) noexcept; - The specialization of std::end for initializer_list returns a pointer to one past - the last element of il. + The overload of std::end for initializer_list returns a pointer to one past the last + element of il. .SH Parameters @@ -16,36 +20,30 @@ il.end() -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include - + #include + #include + #include + int main() { - // range-based for uses std::begin and std::end to iterate - // over a given range; in this case, it's an initializer list - for (int i : {3, 1, 4, 1}) { - std::cout << i << '\\n'; - } + std::initializer_list il = {3, 1, 4, 1, 5, 9}; + + std::reverse_copy(std::begin(il), + std::end(il), + std::ostream_iterator(std::cout, " ")); } .SH Output: - 3 - 1 - 4 - 1 + 9 5 1 4 1 3 .SH See also end returns a pointer to one past the last element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::end(std::valarray).3 b/man/std::end(std::valarray).3 index 9bb61eff9..562316584 100644 --- a/man/std::end(std::valarray).3 +++ b/man/std::end(std::valarray).3 @@ -1,19 +1,33 @@ -.TH std::end(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::end(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::end(std::valarray) \- std::end(std::valarray) + .SH Synopsis - template< class T > \fB(1)\fP \fI(since C++11)\fP - /*unspecified1*/ end( valarray& v ); - template< class T > \fB(2)\fP \fI(since C++11)\fP - /*unspecified2*/ end( const valarray& v ); + template< class T > \fB(1)\fP \fI(since C++11)\fP + /* see below */ end( valarray& v ); + template< class T > \fB(2)\fP \fI(since C++11)\fP + /* see below */ end( const valarray& v ); + + The overload of std::end for valarray returns an iterator of unspecified type + referring to the one past the last element in the numeric array. + + 1) The return type must + * meet the requirements of mutable LegacyRandomAccessIterator, + + * model contiguous_iterator, \fI(since C++20)\fP - The specialization of std::begin for valarray returns an iterator of unspecified - type referring to the one past the last element in the numeric array. + * have a member type value_type, which is T, and + * have a member type reference, which is T&. + 2) The return type must + * meet the requirements of constant LegacyRandomAccessIterator, - 1) The return type meets the requirements of mutable RandomAccessIterator. - 2) The return type meets the requirements of constant RandomAccessIterator. + * model contiguous_iterator, \fI(since C++20)\fP - The iterator obtained from this function is invalidated when the member function - resize() is called on the array v or when the lifetime of v ends, whichever comes - first. + * have a member type value_type, which is T, and + * have a member type reference, which is const T&. + + The iterator returned from this function is invalidated when the member function + resize() is called on v or when the lifetime of v ends, whichever comes first. .SH Parameters @@ -25,7 +39,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes @@ -39,14 +53,42 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include - std::begin(std::valarray) specializes std::begin - \fI(C++11)\fP \fI(function template)\fP + int main() + { + const std::valarray va + { + 'H', 'e', 'l', 'l', 'o', + ',', ' ', + 'C', '+', '+', '!', '\\n' + }; -.SH Category: + std::for_each(std::begin(va), std::end(va), + [](char c){ std::cout << c; }); + } + +.SH Output: + + Hello, C++! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. end() was required to support replacement + LWG 2058 C++11 types 1. not required + 2. it was unspecified when the returned 2. specified + iterators will be invalidated + +.SH See also - * Todo no example + std::begin(std::valarray) overloads std::begin + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::end,std::cend.3 b/man/std::end,std::cend.3 new file mode 100644 index 000000000..a04c6189f --- /dev/null +++ b/man/std::end,std::cend.3 @@ -0,0 +1,153 @@ +.TH std::end,std::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::end,std::cend \- std::end,std::cend + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + template< class C > \fI(since C++11)\fP + auto end( C& c ) -> decltype(c.end()); \fB(1)\fP (constexpr since + C++17) + template< class C > \fI(since C++11)\fP + auto end( const C& c ) -> decltype(c.end()); \fB(2)\fP (constexpr since + C++17) + template< class T, std::size_t N > \fI(since C++11)\fP + T* end( T (&array)[N] ); \fI(until C++14)\fP + template< class T, std::size_t N > \fI(since C++14)\fP + constexpr T* end( T (&array)[N] ) noexcept; + template< class C > \fB(3)\fP + + constexpr auto cend( const C& c ) noexcept(/* see \fB(4)\fP \fI(since C++14)\fP + below */) + + -> decltype(std::end(c)); + + Returns an iterator to the end (i.e. the element after the last element) of the + given range. + + 1,2) Returns c.end(), which is typically an iterator one past the end of the + sequence represented by c. + 1) If C is a standard Container, returns a C::iterator object. + 2) If C is a standard Container, returns a C::const_iterator object. + 3) Returns a pointer to the end of array. + 4) Returns std::end(c), with c always treated as const-qualified. + If C is a standard Container, returns a C::const_iterator object. + + range-begin-end.svg + +.SH Parameters + + c - a container or view with an end member function + array - an array of arbitrary type + +.SH Return value + + 1,2) c.end() + 3) array + N + 4) c.end() + +.SH Exceptions + + 4) + noexcept specification: + noexcept(noexcept(std::end(c))) + + Overloads + + Custom overloads of end may be provided for classes and enumerations that do not + expose a suitable end() member function, yet can be iterated. The following + overloads are already provided by the standard library: + + std::end(std::initializer_list) specializes std::end + \fI(C++11)\fP \fI(function template)\fP + std::end(std::valarray) specializes std::end + \fI(C++11)\fP \fI(function template)\fP + begin(std::filesystem::directory_iterator) range-based for loop support + end(std::filesystem::directory_iterator) \fI(function)\fP + \fI(C++17)\fP + begin(std::filesystem::recursive_directory_iterator) range-based for loop support + end(std::filesystem::recursive_directory_iterator) \fI(function)\fP + + Similar to the use of swap (described in Swappable), typical use of the end function + in generic context is an equivalent of using std::end; end(arg);, which lets both + the ADL-selected overloads for user-defined types and the standard library function + templates to appear in the same overload set. + + template + void for_each(Container&& cont, Function f) + { + using std::begin; + auto it = begin(cont); + using std::end; + auto end_it = end(cont); + + for (; it != end_it; ++it) + f(*it); + } + + Overloads of end found by argument-dependent lookup can be used to + customize the behavior of std::ranges::end, std::ranges::cend, and \fI(since C++20)\fP + other customization pointer objects depending on std::ranges::end. + +.SH Notes + + The non-array overloads exactly reflect the behavior of C::end(). Their effects may + be surprising if the member function does not have a reasonable implementation. + + std::cend is introduced for unification of member and non-member range accesses. See + also LWG issue 2128. + + If C is a shallow-const view, std::cend may return a mutable iterator. Such behavior + is unexpected for some users. See also P2276 and P2278. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v = {3, 1, 4}; + if (std::find(std::begin(v), std::end(v), 5) != std::end(v)) + std::cout << "Found a 5 in vector v!\\n"; + + int w[] = {5, 10, 15}; + if (std::find(std::begin(w), std::end(w), 5) != std::end(w)) + std::cout << "Found a 5 in array w!\\n"; + } + +.SH Output: + + Found a 5 in array w! + +.SH See also + + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + ranges::cend returns a sentinel indicating the end of a read-only range + (C++20) (customization point object) + +.SH Category: + * conditionally noexcept diff --git a/man/std::end.3 b/man/std::end.3 deleted file mode 100644 index c617b2786..000000000 --- a/man/std::end.3 +++ /dev/null @@ -1,82 +0,0 @@ -.TH std::end 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class C > \fB(1)\fP \fI(since C++11)\fP - auto end( C& c ) -> decltype(c.end()); - template< class C > \fB(1)\fP \fI(since C++11)\fP - auto end( const C& c ) -> decltype(c.end()); - template< class T, size_t N > \fB(2)\fP \fI(since C++11)\fP - T* end( T (&array)[N] ); - template< class C > \fB(3)\fP \fI(since C++14)\fP - auto cend( const C& c ) -> decltype(std::end(c)); - - Returns an iterator to the end (i.e. the element after the last element) of the - given container c or array array. - - 1) Returns a possibly const-qualified iterator to the end of the container c. - 2) Returns a pointer to the end of the array array. - 3) Returns a const-qualified iterator to the end of the container c. - - range-begin-end.svg - -.SH Parameters - - c - a container with an end method - array - an array of arbitrary type - -.SH Return value - - An iterator to the end of c or array. Note that the end of a container or array is - defined as the element following the last valid element. - -.SH Notes - - In addition to being included in , std::end is guaranteed to become - available if any of the following headers are included: , , - , , , , , , , - , and . - -.SH Specializations - - Custom specializations of std::end may be provided for classes that do not expose a - suitable end() member function, yet can be iterated. The following specializations - are already provided by the standard library: - - std::end(std::initializer_list) specializes std::end - \fI(C++11)\fP \fI(function template)\fP - std::end(std::valarray) specializes std::end - \fI(C++11)\fP \fI(function template)\fP - -.SH Example - - -// Run this code - - #include - #include - #include - #include - - int main() - { - std::vector v = { 3, 1, 4 }; - if (std::find(std::begin(v), std::end(v), 5) != std::end(v)) { - std::cout << "found a 5 in vector v!\\n"; - } - - int a[] = { 5, 10, 15 }; - if (std::find(std::begin(a), std::end(a), 5) != std::end(a)) { - std::cout << "found a 5 in array a!\\n"; - } - } - -.SH Output: - - found a 5 in array a! - -.SH See also - - begin - cbegin returns an iterator to the beginning of a container or array - \fI(C++11)\fP \fI(function)\fP - \fI(C++14)\fP diff --git a/man/std::endian.3 b/man/std::endian.3 new file mode 100644 index 000000000..9dfde83ee --- /dev/null +++ b/man/std::endian.3 @@ -0,0 +1,75 @@ +.TH std::endian 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::endian \- std::endian + +.SH Synopsis + Defined in header + enum class endian + + { + little = /*implementation-defined*/, \fI(since C++20)\fP + big = /*implementation-defined*/, + native = /*implementation-defined*/, + + }; + + Indicates the endianness of all scalar types: + + * If all scalar types are little-endian, std::endian::native equals + std::endian::little. + * If all scalar types are big-endian, std::endian::native equals std::endian::big. + + Corner case platforms are also supported: + + * If all scalar types have sizeof equal to 1, endianness does not matter and all + three values, std::endian::little, std::endian::big, and std::endian::native are + the same. + * If the platform uses mixed endian, std::endian::native equals neither + std::endian::big nor std::endian::little. + +.SH Possible implementation + + enum class endian + { + #if defined(_MSC_VER) && !defined(__clang__) + little = 0, + big = 1, + native = little + #else + little = __ORDER_LITTLE_ENDIAN__, + big = __ORDER_BIG_ENDIAN__, + native = __BYTE_ORDER__ + #endif + }; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_endian 201907L (C++20) std::endian + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + if constexpr (std::endian::native == std::endian::big) + std::cout << "big-endian\\n"; + else if constexpr (std::endian::native == std::endian::little) + std::cout << "little-endian\\n"; + else + std::cout << "mixed-endian\\n"; + } + +.SH Possible output: + + mixed-endian + +.SH See also + + byteswap reverses the bytes in the given integer value + (C++23) \fI(function template)\fP diff --git a/man/std::endl.3 b/man/std::endl.3 index 29740623b..6d925ab03 100644 --- a/man/std::endl.3 +++ b/man/std::endl.3 @@ -1,10 +1,13 @@ -.TH std::endl 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::endl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::endl \- std::endl + .SH Synopsis Defined in header template< class CharT, class Traits > - std::basic_ostream& endl( std::basic_ostream& os ); + std::basic_ostream& endl( std::basic_ostream& os ); - Inserts a endline character into the output sequence os and flushes it as if by + Inserts a newline character into the output sequence os and flushes it as if by calling os.put(os.widen('\\n')) followed by os.flush(). This is an output-only I/O manipulator, it may be called with an expression such as @@ -16,19 +19,19 @@ displaying output from a long-running process, logging activity of multiple threads or logging activity of a program that may crash unexpectedly. An explicit flush of std::cout is also necessary before a call to std::system, if the spawned process - performs any screen I/O (a common example is std::system("pause") on Windows). In - most other usual interactive I/O scenarios, std::endl is redundant when used with - std::cout because any input from std::cin, output to std::cerr, or program - termination forces a call to std::cout.flush(). Use of std::endl in place of '\\n', - encouraged by some sources, may significantly degrade output performance. + performs any screen I/O. In most other usual interactive I/O scenarios, std::endl is + redundant when used with std::cout because any input from std::cin, output to + std::cerr, or program termination forces a call to std::cout.flush(). Use of + std::endl in place of '\\n', encouraged by some sources, may significantly degrade + output performance. In many implementations, standard output is line-buffered, and writing '\\n' causes a - flush anyway, unless std::cout.sync_with_stdio(false) was executed. In those + flush anyway, unless std::ios::sync_with_stdio(false) was executed. In those situations, unnecessary endl only degrades the performance of file output, not standard output. - The code samples on this wiki follow Bjarne Stroustrup in flushing the standard - output only where necessary. + The code samples on this wiki follow Bjarne Stroustrup and The C++ Core Guidelines + in flushing the standard output only where necessary. When an incomplete line of output needs to be flushed, the std::flush manipulator may be used. @@ -42,55 +45,54 @@ .SH Return value - os (reference to the stream after manipulation) + os (reference to the stream after manipulation). .SH Example - With \\n instead of endl, the output would be the same, but may not appear in real + With '\\n' instead of endl, the output would be the same, but may not appear in real time. - + // Run this code - #include #include - + #include + template void log_progress(Diff d) { - std::cout << std::chrono::duration_cast(d).count() - << " ms passed" << std::endl; + std::cout << std::chrono::duration_cast(d) + << " passed" << std::endl; } - + int main() { std::cout.sync_with_stdio(false); // on some platforms, stdout flushes on \\n - volatile int sink = 0; - - auto t1 = std::chrono::high_resolution_clock::now(); - for (int j=0; j<5; ++j) + + static volatile int sink{}; + const auto t1 = std::chrono::high_resolution_clock::now(); + for (int i = 0; i < 5; ++i) { - for (int n=0; n<10000; ++n) - for (int m=0; m<20000; ++m) - sink += m*n; // do some work - auto now = std::chrono::high_resolution_clock::now(); - log_progress(now - t1); + for (int j = 0; j < 10000; ++j) + for (int k = 0; k < 20000; ++k) + sink += i * j * k; // do some work + log_progress(std::chrono::high_resolution_clock::now() - t1); } } -.SH Output: +.SH Possible output: - 487 ms passed - 974 ms passed - 1470 ms passed - 1965 ms passed - 2455 ms passed + 566ms passed + 1133ms passed + 1699ms passed + 2262ms passed + 2829ms passed .SH See also unitbuf controls whether output is flushed after each operation - nounitbuf \fI(function)\fP + nounitbuf \fI(function)\fP flush flushes the output stream - \fI(function template)\fP + \fI(function template)\fP flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::ends.3 b/man/std::ends.3 index 272881d5c..0c1b24189 100644 --- a/man/std::ends.3 +++ b/man/std::ends.3 @@ -1,8 +1,11 @@ -.TH std::ends 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ends 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ends \- std::ends + .SH Synopsis Defined in header template< class CharT, class Traits > - std::basic_ostream& ends( std::basic_ostream& os ); + std::basic_ostream& ends( std::basic_ostream& os ); Inserts a null character into the output sequence os as if by calling os.put(CharT()). @@ -23,15 +26,16 @@ .SH Return value - os (reference to the stream after insertion of the null character) + os (reference to the stream after insertion of the null character). .SH Example - + // Run this code #include #include + int main() { std::ostrstream oss; @@ -46,5 +50,6 @@ .SH See also - ostrstream implements character array output operations - \fB(deprecated)\fP \fI(class)\fP + ostrstream implements character array output operations + (deprecated in C++98) \fI(class)\fP + (removed in C++26) diff --git a/man/std::equal.3 b/man/std::equal.3 index fe3a76b73..654907354 100644 --- a/man/std::equal.3 +++ b/man/std::equal.3 @@ -1,37 +1,83 @@ -.TH std::equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::equal \- std::equal + .SH Synopsis Defined in header template< class InputIt1, class InputIt2 > - bool equal( InputIt1 first1, InputIt1 last1, \fB(1)\fP + bool equal( InputIt1 first1, InputIt1 last1, \fB(1)\fP (constexpr since C++20) InputIt2 first2 ); - template< class InputIt1, class InputIt2, class BinaryPredicate > + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > - bool equal( InputIt1 first1, InputIt1 last1, \fB(2)\fP + bool equal( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, - InputIt2 first2, BinaryPredicate p ); - template< class InputIt1, class InputIt2 > + ForwardIt2 first2 ); + template< class InputIt1, class InputIt2, class + BinaryPred > + \fB(3)\fP (constexpr since C++20) + bool equal( InputIt1 first1, InputIt1 last1, + + InputIt2 first2, BinaryPred p ); + template< class ExecutionPolicy, - bool equal( InputIt1 first1, InputIt1 last1, \fB(3)\fP \fI(since C++14)\fP + class ForwardIt1, class ForwardIt2, class + BinaryPred > \fB(4)\fP \fI(since C++17)\fP + bool equal( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, + + ForwardIt2 first2, BinaryPred p ); + template< class InputIt1, class InputIt2 > + \fI(since C++14)\fP + bool equal( InputIt1 first1, InputIt1 last1, \fB(5)\fP (constexpr since C++20) InputIt2 first2, InputIt2 last2 ); - template< class InputIt1, class InputIt2, class BinaryPredicate > + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > + + bool equal( ExecutionPolicy&& policy, \fB(6)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, + + ForwardIt2 first2, ForwardIt2 last2 ); + template< class InputIt1, class InputIt2, class + BinaryPred > + \fI(since C++14)\fP + bool equal( InputIt1 first1, InputIt1 last1, \fB(7)\fP (constexpr since C++20) + + InputIt2 first2, InputIt2 last2, BinaryPred + p ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + BinaryPred > + bool equal( ExecutionPolicy&& policy, \fB(8)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, - bool equal( InputIt1 first1, InputIt1 last1, \fB(4)\fP \fI(since C++14)\fP - InputIt2 first2, InputIt2 last2, + ForwardIt2 first2, ForwardIt2 last2, + BinaryPred p ); - BinaryPredicate p ); + Checks whether [first1, last1) and a range starting from first2 are equal: - Returns true if the ranges [first1, last1) and [first2, last2) are considered equal, - where last2 denotes first2 + (last1 - first1) if it was not given. The overloads \fB(1)\fP - and \fB(3)\fP use operator== to compare the elements, whereas overloads \fB(2)\fP and \fB(4)\fP use - the given binary predicate p. + * For overloads (1-4), the second range has std::distance(first1, last1) elements. + * For overloads (5-8), the second range is [first2, last2). + 1,5) Elements are compared using operator==. + 3,7) Elements are compared using the given binary predicate p. + 2,4,6,8) Same as (1,3,5,7), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first1, last1 - the first range of the elements to compare first2, last2 - the second range of the elements to compare + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -39,88 +85,211 @@ following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must - not modify the objects passed to it. + + p - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. - - .SH Type requirements - - InputIt1, InputIt2 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + BinaryPred must meet the requirements of BinaryPredicate. .SH Return value - If last1 - first1 != last2 - first2, returns false + 1-4) If each corresponding elements in the two ranges are equal, returns true. + Otherwise returns false. + 5-8) If std::distance(first1, last1) and std::distance(first2, last2) are equal, and + each corresponding elements in the two ranges are equal, returns true. Otherwise + returns false. - Otherwise, if the elements in the two ranges are equal, returns true. +.SH Complexity - Otherwise returns false. + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1) At most \\(\\scriptsize N_1\\)N + 1 comparisons using operator==. + 2) \\(\\scriptsize O(N_1)\\)O(N + 1) comparisons using operator==. + 3) At most \\(\\scriptsize N_1\\)N + 1 applications of the predicate p. + 4) \\(\\scriptsize O(N_1)\\)O(N + 1) applications of the predicate p. + 5-8) If InputIt1 and InputIt2 are both LegacyRandomAccessIterator, and last1 - + first1 != last2 - first2 is true, no comparison will be made. + Otherwise, given \\(\\scriptsize N\\)N as \\(\\scriptsize \\min(N_1,N_2)\\)min(N + 1,N + 2): + 5) At most \\(\\scriptsize N\\)N comparisons using operator==. + 6) \\(\\scriptsize O(N)\\)O(N) comparisons using operator==. + 7) At most \\(\\scriptsize N\\)N applications of the predicate p. + 8) \\(\\scriptsize O(N)\\)O(N) applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. -.SH Notes +.SH Possible implementation - std::equal may not be used to compare the ranges formed by the iterators from - std::unordered_set, std::unordered_multiset, std::unordered_map, or - std::unordered_multimap because the order in which the elements are stored in those - containers may be different even if the two containers store the same elements. + equal \fB(1)\fP + template + constexpr //< since C++20 + bool equal(InputIt1 first1, InputIt1 last1, InputIt2 first2) + { + for (; first1 != last1; ++first1, ++first2) + if (!(*first1 == *first2)) + return false; - When comparing entire containers for equality, operator== is usually preferred. + return true; + } + equal \fB(3)\fP + template + constexpr //< since C++20 + bool equal(InputIt1 first1, InputIt1 last1, + InputIt2 first2, BinaryPred p) + { + for (; first1 != last1; ++first1, ++first2) + if (!p(*first1, *first2)) + return false; -.SH Complexity + return true; + } + equal \fB(5)\fP + namespace detail + { + // random-access iterator implementation (allows quick range size detection) + template + constexpr //< since C++20 + bool equal(RandomIt1 first1, RandomIt1 last1, RandomIt2 first2, RandomIt2 last2, + std::random_access_iterator_tag, std::random_access_iterator_tag) + { + if (last1 - first1 != last2 - first2) + return false; - At most min(last1 - first1, last2 - first2) applications of the predicate p. + for (; first1 != last1; ++first1, ++first2) + if (!(*first1 == *first2)) + return false; - However, if InputIt1 and InputIt2 meet the requirements of RandomAccessIterator and - last1 - first1 != last2 - first2 then no applications of the predicate p are made. + return true; + } -.SH Possible implementation + // input iterator implementation (needs to manually compare with “last2”) + template + constexpr //< since C++20 + bool equal(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, + std::input_iterator_tag, std::input_iterator_tag) + { + for (; first1 != last1 && first2 != last2; ++first1, ++first2) + if (!(*first1 == *first2)) + return false; + + return first1 == last1 && first2 == last2; + } + } -.SH First version template - bool equal(InputIt1 first1, InputIt1 last1, - InputIt2 first2) + constexpr //< since C++20 + bool equal(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2) + { + details::equal(first1, last1, first2, last2, + typename std::iterator_traits::iterator_category(), + typename std::iterator_traits::iterator_category()); + } + equal \fB(7)\fP + namespace detail { - for (; first1 != last1; ++first1, ++first2) { - if (!(*first1 == *first2)) { + // random-access iterator implementation (allows quick range size detection) + template + constexpr //< since C++20 + bool equal(RandomIt1 first1, RandomIt1 last1, + RandomIt2 first2, RandomIt2 last2, BinaryPred p, + std::random_access_iterator_tag, std::random_access_iterator_tag) + { + if (last1 - first1 != last2 - first2) return false; - } + + for (; first1 != last1; ++first1, ++first2) + if (!p(*first1, *first2)) + return false; + + return true; + } + + // input iterator implementation (needs to manually compare with “last2”) + template + constexpr //< since C++20 + bool equal(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, BinaryPred p, + std::input_iterator_tag, std::input_iterator_tag) + { + for (; first1 != last1 && first2 != last2; ++first1, ++first2) + if (!p(*first1, *first2)) + return false; + + return first1 == last1 && first2 == last2; } - return true; } -.SH Second version - template + + template + constexpr //< since C++20 bool equal(InputIt1 first1, InputIt1 last1, - InputIt2 first2, BinaryPredicate p) + InputIt2 first2, InputIt2 last2, BinaryPred p) { - for (; first1 != last1; ++first1, ++first2) { - if (!p(*first1, *first2)) { - return false; - } - } - return true; + details::equal(first1, last1, first2, last2, p, + typename std::iterator_traits::iterator_category(), + typename std::iterator_traits::iterator_category()); } +.SH Notes + + std::equal should not be used to compare the ranges formed by the iterators from + std::unordered_set, std::unordered_multiset, std::unordered_map, or + std::unordered_multimap because the order in which the elements are stored in those + containers may be different even if the two containers store the same elements. + + When comparing entire containers for equality, operator== for the corresponding + container are usually preferred. + .SH Example - The following code uses equal() to test if a string is a palindrome + The following code uses std::equal to test if a string is a palindrome. + - // Run this code - #include #include - #include - - void test(const std::string& s) + #include + #include + #include + + constexpr bool is_palindrome(const std::string_view& s) + { + return std::equal(s.cbegin(), s.cbegin() + s.size() / 2, s.crbegin()); + } + + void test(const std::string_view& s) { - if(std::equal(s.begin(), s.begin() + s.size()/2, s.rbegin())) { - std::cout << "\\"" << s << "\\" is a palindrome\\n"; - } else { - std::cout << "\\"" << s << "\\" is not palindrome\\n"; - } + std::cout << std::quoted(s) + << (is_palindrome(s) ? " is" : " is not") + << " a palindrome\\n"; } + int main() { test("radar"); @@ -130,16 +299,24 @@ .SH Output: "radar" is a palindrome - "hello" is not palindrome + "hello" is not a palindrome + +.SH See also find find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if_not \fI(function template)\fP \fI(C++11)\fP returns true if one range is lexicographically less than lexicographical_compare another - \fI(function template)\fP + \fI(function template)\fP mismatch finds the first position where two ranges differ - \fI(function template)\fP + \fI(function template)\fP search searches for a range of elements - \fI(function template)\fP + \fI(function template)\fP + ranges::equal determines if two sets of elements are the same + (C++20) (niebloid) + equal_to function object implementing x == y + \fI(class template)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::equal_range.3 b/man/std::equal_range.3 index add57bb55..c4172c65b 100644 --- a/man/std::equal_range.3 +++ b/man/std::equal_range.3 @@ -1,91 +1,163 @@ -.TH std::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::equal_range \- std::equal_range + .SH Synopsis Defined in header template< class ForwardIt, class T > - - std::pair \fB(1)\fP - equal_range( ForwardIt first, ForwardIt last, - - const T& value ); - template< class ForwardIt, class T, class Compare > - - std::pair \fB(2)\fP - equal_range( ForwardIt first, ForwardIt last, - - const T& value, Compare comp ); - - Returns a range containing all elements equivalent to value in the range [first, - last). - - The range [first, last) must be partitioned with respect to comparison with value, - i.e. it must satisfy all of the following requirements: - - * partitioned with respect to element < value or comp(element, value) - * partitioned with respect to !(value < element) or !comp(value, element) - * for all elements, if element < value or comp(element, value) is true then - !(value < element) or !comp(value, element) is also true - - A fully-sorted range meets these criteria, as does a range resulting from a call to - std::partition. - - The returned range is defined by two iterators, one pointing to the first element - that is not less than value and another pointing to the first element greater than - value. The first iterator may be alternatively obtained with std::lower_bound(), the - second - with std::upper_bound(). - - The first version uses operator< to compare the elements, the second version uses - the given comparison function comp. + (constexpr since + std::pair C++20) + (until C++26) + equal_range( ForwardIt first, + ForwardIt last, const T& value ); + template< class ForwardIt, class T = + typename std::iterator_traits + + + ::value_type > (since C++26) + constexpr std::pair + + equal_range( ForwardIt first, + ForwardIt last, const T& value ); + template< class ForwardIt, class T, class + Compare > + \fB(1)\fP + std::pair (constexpr since + equal_range( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value, Compare + comp ); + template< class ForwardIt, class T = + typename std::iterator_traits \fB(2)\fP + + + ::value_type, + class Compare > (since C++26) + constexpr std::pair + equal_range( ForwardIt first, + ForwardIt last, + + const T& value, Compare + comp ); + + Returns a range containing all elements equivalent to value in the partitioned range + [first, last). + + 1) The equivalence is checked using operator<: + + Returns the results of std::lower_bound(first, last, value) and + std::upper_bound(first, last, value). + + If any of the following conditions is satisfied, the behavior is + undefined: \fI(until C++20)\fP + + * For any element elem of [first, last), bool(elem < value) does not + imply !bool(value < elem). + * The elements elem of [first, last) are not partitioned with + respect to expressions bool(elem < value) and !bool(value < elem). + Equivalent to std::equal_range(first, last, value, std::less{}). \fI(since C++20)\fP + + 2) The equivalence is checked using comp: + Returns the results of std::lower_bound(first, last, value, comp) and + std::upper_bound(first, last, value, comp). + If any of the following conditions is satisfied, the behavior is undefined: + * For any element elem of [first, last), bool(comp(elem, value)) does not imply + !bool(comp(value, elem)). + * The elements elem of [first, last) are not partitioned with respect to + expressions bool(comp(elem, value)) and !bool(comp(value, elem)). .SH Parameters - first, last - the range of elements to examine + first, last - the partitioned range of elements to examine value - value to compare the elements to - comparison function which returns true if the first argument is less - than the second. + binary predicate which returns true if the first argument is ordered + before the second. - The signature of the comparison function should be equivalent to the + The signature of the predicate function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function must not - modify the objects passed to it. - cmp will be called as both cmp(value, *iterator) and cmp(*iterator, - value). + bool pred(const Type1 &a, const Type2 &b); + + comp - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type T can be + implicitly converted to both Type1 and Type2, and an object of type + ForwardIt can be dereferenced and then implicitly converted to both + Type1 and Type2. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of BinaryPredicate. It is not required to satisfy + Compare. .SH Return value - std::pair containing a pair of iterators defining the wanted range, the first - pointing to the first element that is not less than value and the second pointing to - the first element greater than value. + A std::pair containing a pair of iterators, where - If there are no elements not less than value, last is returned as the first element. - Similarly if there are no elements greater than value, last is returned as the - second element + * first is an iterator to the first element of the range [first, last) not ordered + before value (or last if no such element is found), and + * second is an iterator to the first element of the range [first, last) ordered + after value (or last if no such element is found). .SH Complexity - Logarithmic in the distance between first and last + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) At most \\(\\scriptsize 2\\log_{2}(N)+O(1)\\)2log + 2(N)+O(1) comparisons with value using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize 2\\log_{2}(N)+O(1)\\)2log + 2(N)+O(1) applications of the comparator comp. + + However, if ForwardIt is not a LegacyRandomAccessIterator, the number of iterator + increments is linear in \\(\\scriptsize N\\)N. Notably, std::set and std::multiset + iterators are not random access, and so their member functions std::set::equal_range + (resp. std::multiset::equal_range) should be preferred. + +.SH Notes + + Although std::equal_range only requires [first, last) to be partitioned, this + algorithm is usually used in the case where [first, last) is sorted, so that the + binary search is valid for any value. + + On top of the requirements of std::lower_bound and std::upper_bound, + std::equal_range also requires operator< or comp to be asymmetric (i.e., a < b and b + < a always have different results). + + Therefore, the intermediate results of binary search can be shared by + std::lower_bound and std::upper_bound. For example, the result of the + std::lower_bound call can be used as the argument of first in the std::upper_bound + call. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) .SH Possible implementation -.SH First version - template - std::pair - equal_range(ForwardIt first, ForwardIt last, - const T& value) + equal_range \fB(1)\fP + template::value_type> + constexpr std::pair + equal_range(ForwardIt first, ForwardIt last, const T& value) { - return std::make_pair(std::lower_bound(first, last, value), - std::upper_bound(first, last, value)); + return std::equal_range(first, last, value, std::less{}); } -.SH Second version - template - std::pair - equal_range(ForwardIt first, ForwardIt last, - const T& value, Compare comp); + equal_range \fB(2)\fP + template::value_type, + class Compare> + constexpr std::pair + equal_range(ForwardIt first, ForwardIt last, const T& value, Compare comp) { return std::make_pair(std::lower_bound(first, last, value, comp), std::upper_bound(first, last, value, comp)); @@ -93,107 +165,107 @@ .SH Example - -// Run this code - - #include - #include - #include - - struct S - { - int number; - char name; - - S ( int number, char name ) - : number ( number ), name ( name ) - {} - - // only the number is relevant with this comparison - bool operator< ( const S& s ) const - { - return number < s.number; - } - }; - - - int main() - { - // note: not ordered, only partitioned w.r.t. S defined below - std::vector vec = { {1,'A'}, {2,'B'}, {2,'C'}, {2,'D'}, {4,'G'}, {3,'F'} }; - - S value ( 2, '?' ); - - auto p = std::equal_range(vec.begin(),vec.end(),value); - - for ( auto i = p.first; i != p.second; ++i ) - std::cout << i->name << ' '; - } - -.SH Output: - B C D - -.SH Example With Comparator - - // Run this code #include - #include + #include #include - + #include + struct S { int number; char name; - - S ( int number, char name ) - : number ( number ), name ( name ) - {} - - // only the number is relevant with this comparison - bool operator< ( const S& s ) const - { - return number < s.number; - } + // note: name is ignored by this comparison operator + bool operator<(const S& s) const { return number < s.number; } }; - + struct Comp { - bool operator() ( const S& s, int i ) - { - return s.number < i; - } - - bool operator() ( int i, const S& s ) - { - return i < s.number; - } + bool operator()(const S& s, int i) const { return s.number < i; } + bool operator()(int i, const S& s) const { return i < s.number; } }; - + int main() { // note: not ordered, only partitioned w.r.t. S defined below - std::vector vec = { {1,'A'}, {2,'B'}, {2,'C'}, {2,'D'}, {4,'G'}, {3,'F'} }; - - auto p = std::equal_range(vec.begin(),vec.end(),2,Comp()); - - for ( auto i = p.first; i != p.second; ++i ) - std::cout << i->name << ' '; + const std::vector vec{{1, 'A'}, {2, 'B'}, {2, 'C'}, + {2, 'D'}, {4, 'G'}, {3, 'F'}}; + const S value{2, '?'}; + + std::cout << "Compare using S::operator<(): "; + const auto p = std::equal_range(vec.begin(), vec.end(), value); + + for (auto it = p.first; it != p.second; ++it) + std::cout << it->name << ' '; + std::cout << '\\n'; + + std::cout << "Using heterogeneous comparison: "; + const auto p2 = std::equal_range(vec.begin(), vec.end(), 2, Comp{}); + + for (auto it = p2.first; it != p2.second; ++it) + std::cout << it->name << ' '; + std::cout << '\\n'; + + using CD = std::complex; + std::vector nums{{1, 0}, {2, 2}, {2, 1}, {3, 0}, {3, 1}}; + auto cmpz = [](CD x, CD y) { return x.real() < y.real(); }; + #ifdef __cpp_lib_algorithm_default_value_type + auto p3 = std::equal_range(nums.cbegin(), nums.cend(), {2, 0}, cmpz); + #else + auto p3 = std::equal_range(nums.cbegin(), nums.cend(), CD{2, 0}, cmpz); + #endif + + for (auto it = p3.first; it != p3.second; ++it) + std::cout << *it << ' '; + std::cout << '\\n'; } .SH Output: - B C D + Compare using S::operator<(): B C D + Using heterogeneous comparison: B C D + (2,2) (2, 1) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + Compare was required to satisfy only a partitioning is required; + LWG 270 C++98 Compare and T was required heterogeneous comparisons + to be LessThanComparable (strict permitted + weak ordering required) + at most \\(\\scriptsize + 2\\log_{2}(N)+1\\)2log corrected to \\(\\scriptsize + LWG 384 C++98 2(N)+1 comparisons 2\\log_{2}(N)+O(1)\\)2log + were allowed, which is not 2(N)+O(1) + implementable^[1] + + 1. ↑ Applying equal_range to a single-element range requires 2 comparisons, but at + most 1 comparison is allowed by the complexity requirement. .SH See also - lower_bound returns an iterator to the first element not less than the given value - \fI(function template)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(function template)\fP - binary_search determines if an element exists in a certain range - \fI(function template)\fP - partition divides a range of elements into two groups - \fI(function template)\fP + returns an iterator to the first element not less than the given + lower_bound value + \fI(function template)\fP + returns an iterator to the first element greater than a certain + upper_bound value + \fI(function template)\fP + binary_search determines if an element exists in a partially-ordered range + \fI(function template)\fP + partition divides a range of elements into two groups + \fI(function template)\fP + equal determines if two sets of elements are the same + \fI(function template)\fP + returns range of elements matching a specific key + equal_range \fI(public member function of std::set)\fP + + returns range of elements matching a specific key + equal_range \fI(public member function of std::multiset)\fP + + ranges::equal_range returns range of elements matching a specific key + (C++20) (niebloid) diff --git a/man/std::equal_to,not_equal_to,less,greater,less_equal,.3 b/man/std::equal_to,not_equal_to,less,greater,less_equal,.3 new file mode 100644 index 000000000..c2b603528 --- /dev/null +++ b/man/std::equal_to,not_equal_to,less,greater,less_equal,.3 @@ -0,0 +1,74 @@ +.TH std::equal_to,not_equal_to,less,greater,less_equal, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::equal_to,not_equal_to,less,greater,less_equal, \- std::equal_to,not_equal_to,less,greater,less_equal, + +.SH Synopsis + + Defined in header + template< class T > struct (library + equal_to>; fundamentals TS + v2) + template< class T > struct (library + not_equal_to>; fundamentals TS + v2) + template< class T > struct (library + less>; fundamentals TS + v2) + template< class T > struct (library + greater>; fundamentals TS + v2) + template< class T > struct (library + less_equal>; fundamentals TS + v2) + template< class T > struct (library + greater_equal>; fundamentals TS + v2) + + The standard comparison function objects are partially specialized for + std::experimental::propagate_const. + + Let p.t_ denote the pointer-like object wrapped by a + std::experimental::propagate_const p, then given objects p and q of type + std::experimental::propagate_const, the following shall hold: + + * std::equal_to>()(p, q) == + std::equal_to()(p.t_, q.t_) + * std::not_equal_to>()(p, q) == + std::not_equal_to()(p.t_, q.t_) + * std::less>()(p, q) == std::less()(p.t_, + q.t_) + * std::greater>()(p, q) == + std::greater()(p.t_, q.t_) + * std::less_equal>()(p, q) == + std::less_equal()(p.t_, q.t_) + * std::greater_equal>()(p, q) == + std::greater_equal()(p.t_, q.t_) + +.SH Notes + + These specializations ensure that when T is a pointer type, specializations of these + class templates for std::experimental::propagate_const yield a total order, even + if the corresponding built-in operators do not. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_to function object implementing x == y + \fI(class template)\fP + not_equal_to function object implementing x != y + \fI(class template)\fP + less function object implementing x < y + \fI(class template)\fP + greater function object implementing x > y + \fI(class template)\fP + less_equal function object implementing x <= y + \fI(class template)\fP + greater_equal function object implementing x >= y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::equal_to.3 b/man/std::equal_to.3 index 5cff95ca0..0dc821c2d 100644 --- a/man/std::equal_to.3 +++ b/man/std::equal_to.3 @@ -1,42 +1,29 @@ -.TH std::equal_to 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::equal_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::equal_to \- std::equal_to + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct equal_to; - template< class T = void > \fI(since C++14)\fP - struct equal_to; - - Function object for performing comparisons. Unless specialised, invokes operator== - on type T. - -.SH Specializations - - The standard library provides a specialization of std::equal_to when T - is not specified, which leaves the parameter types and return type to - be deduced. - \fI(since C++14)\fP - function object implementing x == y deducing argument - equal_to and return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class equal_to; -.SH Member types - - type definition - result_type bool - first_argument_type T - second_argument_type T + std::equal_to is a specialization of std::equal_to with parameter and return + type deduced. .SH Member functions - operator() checks if the arguments are equal + operator() tests if the two arguments compare equal \fI(public member function)\fP - std::equal_to::operator() +std::equal_to::operator() + + template< class T, class U > - bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const - Checks whether lhs is equal to rhs. + -> decltype(std::forward(lhs) == std::forward(rhs)); + + Returns the result of equality comparison between lhs and rhs. .SH Parameters @@ -44,15 +31,19 @@ .SH Return value - true if lhs == rhs, false otherwise. + std::forward(lhs) == std::forward(rhs). + +.SH Example -.SH Exceptions - \fI(none)\fP +// Run this code -.SH Possible implementation + #include - constexpr bool operator()(const T &lhs, const T &rhs) const - { - return lhs == rhs; - } + int main() + { + constexpr int a = 0, b = 8; + std::equal_to<> equal{}; + static_assert(equal(a, a)); + static_assert(!equal(a, b)); + } diff --git a/man/std::equal_to.3 b/man/std::equal_to.3 deleted file mode 100644 index ade36cd28..000000000 --- a/man/std::equal_to.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::equal_to 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class equal_to; - - std::equal_to<> is a specialization of std::equal_to with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() tests if the two arguments compare equal - \fI(public member function)\fP - - std::equal_to<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) == std::forward(rhs)); - - Returns the result of equality comparison between lhs and rhs. - -.SH Parameters - - lhs, rhs - values to compare - -.SH Return value - - The result of lhs == rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::equality_comparable,std::equality_comparable_with.3 b/man/std::equality_comparable,std::equality_comparable_with.3 new file mode 100644 index 000000000..701c1ff74 --- /dev/null +++ b/man/std::equality_comparable,std::equality_comparable_with.3 @@ -0,0 +1,143 @@ +.TH std::equality_comparable,std::equality_comparable_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::equality_comparable,std::equality_comparable_with \- std::equality_comparable,std::equality_comparable_with + +.SH Synopsis + Defined in header + template< class T > (since + concept equality_comparable = \fB(1)\fP C++20) + __WeaklyEqualityComparableWith; + template< class T, class U > + + concept equality_comparable_with = + std::equality_comparable && + std::equality_comparable && + __ComparisonCommonTypeWith && \fB(2)\fP (since + std::equality_comparable< C++20) + std::common_reference_t< + const std::remove_reference_t&, + const std::remove_reference_t&>> && + + __WeaklyEqualityComparableWith; + template< class T, class U > + + concept __WeaklyEqualityComparableWith = + requires(const std::remove_reference_t& t, + const std::remove_reference_t& u) { (exposition + { t == u } -> boolean-testable; \fB(3)\fP only*) + { t != u } -> boolean-testable; + { u == t } -> boolean-testable; + { u != t } -> boolean-testable; + + }; + template< class T, class U > + (until + concept __ComparisonCommonTypeWith = C++23) + std::common_reference_with< (exposition + const std::remove_reference_t&, only*) + + const std::remove_reference_t&>; + template< class T, class U, class C = + std::common_reference_t > + + concept _ComparisonCommonTypeWithImpl = + std::same_as, + std::common_reference_t> && \fB(4)\fP + requires { + requires std::convertible_to (since + || C++23) + std::convertible_to; (exposition + requires std::convertible_to only*) + || + std::convertible_to; + }; + template< class T, class U > + concept __ComparisonCommonTypeWith = + + + _ComparisonCommonTypeWithImpl, + std::remove_cvref_t>; + + 1) The concept std::equality_comparable specifies that the comparison operators == + and != on T reflects equality: == yields true if and only if the operands are equal. + 2) The concept std::equality_comparable_with specifies that the comparison operators + == and != on (possibly mixed) T and U operands yield results consistent with + equality. Comparing mixed operands yields results equivalent to comparing the + operands converted to their common type. + 3) The exposition-only concept __WeaklyEqualityComparableWith specifies that an + object of type T and an object of type U can be compared for equality with each + other (in either order) using both == and !=, and the results of the comparisons are + consistent. + 4) The exposition-only concept __ComparisonCommonTypeWith specifies that two types + share a common type, and a const lvalue + or a non-const rvalue + (since C++23) of either type is convertible to that common type. + + Semantic requirements + + These concepts are modeled only if they are satisfied and all concepts they subsume + are modeled. + + In the following paragraphs, given an expression E and a type C, CONVERT_TO(E) is + defined as: + + * static_cast(std::as_const(E)). (until C++23) + * static_cast(std::as_const(E)) if that is a valid + expression, (since C++23) + * static_cast(std::move(E)) otherwise. + + 1) std::equality_comparable is modeled only if, given objects a and b of type T, + bool(a == b) is true if and only if a and b are equal. Together with the requirement + that a == b is equality-preserving, this implies that == is symmetric and + transitive, and further that == is reflexive for all objects a that are equal to at + least one other object. + 2) std::equality_comparable_with is modeled only if, let + * t and t2 be lvalues denoting distinct equal objects of types const + std::remove_reference_t and std::remove_cvref_t respectively, + * u and u2 be lvalues denoting distinct equal objects of types const + std::remove_reference_t and std::remove_cvref_t respectively, + * C be std::common_reference_t&, const + std::remove_reference_t&>, + + the following expression is true: + + * bool(t == u) == bool(CONVERT_TO(t2) == CONVERT_TO(u2)). + 3) __WeaklyEqualityComparableWith is modeled only if given + * t, an lvalue of type const std::remove_reference_t and + * u, an lvalue of type const std::remove_reference_t, + + the following are true: + + * t == u, u == t, t != u, u != t have the same domain; + * bool(u == t) == bool(t == u); + * bool(t != u) == !bool(t == u); and + * bool(u != t) == bool(t != u). + 4) __WeaklyEqualityComparableWith is modeled only if: + + The corresponding common_reference_with concept is modeled. (until C++23) + Let + + * C be std::common_reference_t, + * t1 and t2 be equality-preserving expressions that are lvalues of + type std::remove_cvref_t, + * u1 and u2 be equality-preserving expressions that are lvalues of + type std::remove_cvref_t, (since C++23) + + the following conditions hold: + + * CONVERT_TO(t1) equals CONVERT_TO(t2) if and only if t1 + equals t2; and + * CONVERT_TO(u1) equals CONVERT_TO(u2) if and only if u1 + equals u2. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + + Implicit expression variations + + A requires expression that uses an expression that is non-modifying for some + constant lvalue operand also requires implicit expression variations. diff --git a/man/std::equivalence_relation.3 b/man/std::equivalence_relation.3 new file mode 100644 index 000000000..8db7c27e9 --- /dev/null +++ b/man/std::equivalence_relation.3 @@ -0,0 +1,24 @@ +.TH std::equivalence_relation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::equivalence_relation \- std::equivalence_relation + +.SH Synopsis + Defined in header + template< class R, class T, class U > \fI(since C++20)\fP + concept equivalence_relation = std::relation; + + The concept equivalence_relation specifies that the relation R imposes an + equivalence relation on its arguments. + + Semantic requirements + + A relation r is an equivalence relation if + + * it is reflexive: for all x, r(x, x) is true; + * it is symmetric: for all a and b, r(a, b) is true if and only if r(b, a) is + true; + * it is transitive: r(a, b) && r(b, c) implies r(a, c). + +.SH Notes + + The distinction between relation and equivalence_relation is purely semantic. diff --git a/man/std::erase,std::erase_if(std::basic_string).3 b/man/std::erase,std::erase_if(std::basic_string).3 new file mode 100644 index 000000000..cb4325c72 --- /dev/null +++ b/man/std::erase,std::erase_if(std::basic_string).3 @@ -0,0 +1,104 @@ +.TH std::erase,std::erase_if(std::basic_string) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase,std::erase_if(std::basic_string) \- std::erase,std::erase_if(std::basic_string) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc, class U > + + constexpr std::basic_string::size_type \fI(since C++20)\fP + (until C++26) + erase( std::basic_string& c, const + U& value ); + template< class CharT, class Traits, class Alloc, class U = + CharT > + + constexpr std::basic_string::size_type \fB(1)\fP (since C++26) + + erase( std::basic_string& c, const + U& value ); + template< class CharT, class Traits, class Alloc, class Pred > + + constexpr std::basic_string::size_type \fB(2)\fP \fI(since C++20)\fP + + erase_if( std::basic_string& c, Pred + pred ); + + 1) Erases all elements that compare equal to value from the container. Equivalent to + + auto it = std::remove(c.begin(), c.end(), value); + auto r = c.end() - it; + c.erase(it, c.end()); + return r; + + 2) Erases all elements that satisfy the predicate pred from the container. + Equivalent to + + auto it = std::remove_if(c.begin(), c.end(), pred); + auto r = c.end() - it; + c.erase(it, c.end()); + return r; + +.SH Parameters + + c - container from which to erase + value - value to be removed + unary predicate which returns true if the element should be erased. + + The expression pred(v) must be convertible to bool for every argument v of + pred - type (possibly const) CharT, regardless of value category, and must not + modify v. Thus, a parameter type of CharT&is not allowed + , nor is CharT unless for CharT a move is equivalent to a copy + \fI(since C++11)\fP. + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithm \fB(1)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string word{"startling"}; + std::cout << "Initially, word = " << std::quoted(word) << '\\n'; + + std::erase(word, 'l'); + std::cout << "After erase 'l': " << std::quoted(word) << '\\n'; + + auto erased = std::erase_if(word, [](char x) + { + return x == 'a' or x == 'r' or x == 't'; + }); + + std::cout << "After erase all 'a', 'r', and 't': " << std::quoted(word) << '\\n'; + std::cout << "Erased symbols count: " << erased << '\\n'; + } + +.SH Output: + + Initially, word = "startling" + After erase 'l', word = "starting" + After erase all 'a', 'r', and 't': "sing" + Erased symbols count: 4 + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase,std::erase_if(std::deque).3 b/man/std::erase,std::erase_if(std::deque).3 new file mode 100644 index 000000000..e74d0ca3c --- /dev/null +++ b/man/std::erase,std::erase_if(std::deque).3 @@ -0,0 +1,116 @@ +.TH std::erase,std::erase_if(std::deque) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase,std::erase_if(std::deque) \- std::erase,std::erase_if(std::deque) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class U > + \fI(since C++20)\fP + std::deque::size_type (until C++26) + + erase( std::deque& c, const U& value ); + template< class T, class Alloc, class U = T > + + std::deque::size_type \fB(1)\fP (since C++26) + + erase( std::deque& c, const U& value ); + template< class T, class Alloc, class Pred > + + std::deque::size_type \fB(2)\fP \fI(since C++20)\fP + + erase_if( std::deque& c, Pred pred ); + + 1) Erases all elements that compare equal to value from the container. Equivalent to + + auto it = std::remove(c.begin(), c.end(), value); + auto r = c.end() - it; + c.erase(it, c.end()); + return r; + + 2) Erases all elements that satisfy the predicate pred from the container. + Equivalent to + + auto it = std::remove_if(c.begin(), c.end(), pred); + auto r = c.end() - it; + c.erase(it, c.end()); + return r; + +.SH Parameters + + c - container from which to erase + value - value to be removed + unary predicate which returns true if the element should be erased. + + The expression pred(v) must be convertible to bool for every argument v of + pred - type (possibly const) T, regardless of value category, and must not modify + v. Thus, a parameter type of T&is not allowed + , nor is T unless for T a move is equivalent to a copy + \fI(since C++11)\fP. + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithm \fB(1)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(std::string_view comment, const auto& c) + { + std::cout << comment << "{ "; + for (const auto& x : c) + std::cout << x << ' '; + std::cout << "}\\n"; + } + + int main() + { + std::deque cnt(10); + std::iota(cnt.begin(), cnt.end(), '0'); + println("Initially, cnt = ", cnt); + + std::erase(cnt, '3'); + println("After erase '3', cnt = ", cnt); + + auto erased = std::erase_if(cnt, [](char x) { return (x - '0') % 2 == 0; }); + println("After erase all even numbers, cnt = ", cnt); + std::cout << "Erased even numbers: " << erased << '\\n'; + + std::deque> nums{{2, 2}, {4, 2}, {4, 8}, {4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + std::erase(nums, {4, 2}); + #else + std::erase(nums, std::complex{4, 2}); + #endif + println("After erase {4, 2}, nums = ", nums); + } + +.SH Output: + + Initially, cnt = { 0 1 2 3 4 5 6 7 8 9 } + After erase '3', cnt = { 0 1 2 4 5 6 7 8 9 } + After erase all even numbers, cnt = { 1 5 7 9 } + Erased even numbers: 5 + After erase {4, 2}, nums = { (2,2) (4,8) } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase,std::erase_if(std::forward_list).3 b/man/std::erase,std::erase_if(std::forward_list).3 new file mode 100644 index 000000000..5b5ec9898 --- /dev/null +++ b/man/std::erase,std::erase_if(std::forward_list).3 @@ -0,0 +1,111 @@ +.TH std::erase,std::erase_if(std::forward_list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase,std::erase_if(std::forward_list) \- std::erase,std::erase_if(std::forward_list) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class U > + \fI(since C++20)\fP + std::forward_list::size_type (until C++26) + + erase( std::forward_list& c, const U& value ); + template< class T, class Alloc, class U = T > + + std::forward_list::size_type \fB(1)\fP (since C++26) + + erase( std::forward_list& c, const U& value ); + template< class T, class Alloc, class Pred > + + std::forward_list::size_type \fB(2)\fP \fI(since C++20)\fP + + erase_if( std::forward_list& c, Pred pred ); + + 1) Erases all elements that compare equal to value from the container. Equivalent to + return c.remove_if([&](auto& elem) { return elem == value; });. + 2) Erases all elements that satisfy the predicate pred from the container. + Equivalent to return c.remove_if(pred);. + +.SH Parameters + + c - container from which to erase + value - value to be removed + unary predicate which returns true if the element should be erased. + + The expression pred(v) must be convertible to bool for every argument v of + pred - type (possibly const) T, regardless of value category, and must not modify + v. Thus, a parameter type of T&is not allowed + , nor is T unless for T a move is equivalent to a copy + \fI(since C++11)\fP. + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Notes + + Unlike std::forward_list::remove, erase accepts heterogeneous types and does not + force a conversion to the container's value type before invoking the == operator. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithm \fB(1)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(std::string_view comment, const auto& c) + { + std::cout << comment << "{ "; + for (const auto& x : c) + std::cout << x << ' '; + std::cout << "}\\n"; + } + + int main() + { + std::forward_list cnt(10); + std::iota(cnt.begin(), cnt.end(), '0'); + println("Initially, cnt = ", cnt); + + std::erase(cnt, '3'); + println("After erase '3', cnt = ", cnt); + + auto erased = std::erase_if(cnt, [](char x) { return (x - '0') % 2 == 0; }); + println("After erase all even numbers, cnt = ", cnt); + std::cout << "Erased even numbers: " << erased << '\\n'; + + std::forward_list> nums{{2, 2}, {4, 2}, {4, 8}, {4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + std::erase(nums, {4, 2}); + #else + std::erase(nums, std::complex{4, 2}); + #endif + println("After erase {4, 2}, nums = ", nums); + } + +.SH Output: + + Initially, cnt = { 0 1 2 3 4 5 6 7 8 9 } + After erase '3', cnt = { 0 1 2 4 5 6 7 8 9 } + After erase all even numbers, cnt = { 1 5 7 9 } + Erased even numbers: 5 + After erase {4, 2}, nums = { (2,2) (4,8) } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(public member function)\fP diff --git a/man/std::erase,std::erase_if(std::list).3 b/man/std::erase,std::erase_if(std::list).3 new file mode 100644 index 000000000..18d166bf4 --- /dev/null +++ b/man/std::erase,std::erase_if(std::list).3 @@ -0,0 +1,111 @@ +.TH std::erase,std::erase_if(std::list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase,std::erase_if(std::list) \- std::erase,std::erase_if(std::list) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class U > + \fI(since C++20)\fP + std::list::size_type (until C++26) + + erase( std::list& c, const U& value ); + template< class T, class Alloc, class U = T > + + std::list::size_type \fB(1)\fP (since C++26) + + erase( std::list& c, const U& value ); + template< class T, class Alloc, class Pred > + + std::list::size_type \fB(2)\fP \fI(since C++20)\fP + + erase_if( std::list& c, Pred pred ); + + 1) Erases all elements that compare equal to value from the container. Equivalent to + return c.remove_if([&](auto& elem) { return elem == value; });. + 2) Erases all elements that satisfy the predicate pred from the container. + Equivalent to return c.remove_if(pred);. + +.SH Parameters + + c - container from which to erase + value - value to be removed + unary predicate which returns true if the element should be erased. + + The expression pred(v) must be convertible to bool for every argument v of + pred - type (possibly const) T, regardless of value category, and must not modify + v. Thus, a parameter type of T&is not allowed + , nor is T unless for T a move is equivalent to a copy + \fI(since C++11)\fP. + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Notes + + Unlike std::list::remove, erase accepts heterogeneous types and does not force a + conversion to the container's value type before invoking the == operator. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithm \fB(1)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(std::string_view comment, const auto& c) + { + std::cout << comment << "{ "; + for (const auto& x : c) + std::cout << x << ' '; + std::cout << "}\\n"; + } + + int main() + { + std::list cnt(10); + std::iota(cnt.begin(), cnt.end(), '0'); + println("Initially, cnt = ", cnt); + + std::erase(cnt, '3'); + println("After erase '3', cnt = ", cnt); + + auto erased = std::erase_if(cnt, [](char x) { return (x - '0') % 2 == 0; }); + println("After erase all even numbers, cnt = ", cnt); + std::cout << "Erased even numbers: " << erased << '\\n'; + + std::list> nums{{2, 2}, {4, 2}, {4, 8}, {4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + std::erase(nums, {4, 2}); + #else + std::erase(nums, std::complex{4, 2}); + #endif + println("After erase {4, 2}, nums = ", nums); + } + +.SH Output: + + Initially, cnt = { 0 1 2 3 4 5 6 7 8 9 } + After erase '3', cnt = { 0 1 2 4 5 6 7 8 9 } + After erase all even numbers, cnt = { 1 5 7 9 } + Erased even numbers: 5 + After erase {4, 2}, nums = { (2,2) (4,8) } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(public member function)\fP diff --git a/man/std::erase,std::erase_if(std::vector).3 b/man/std::erase,std::erase_if(std::vector).3 new file mode 100644 index 000000000..9b13ebaab --- /dev/null +++ b/man/std::erase,std::erase_if(std::vector).3 @@ -0,0 +1,116 @@ +.TH std::erase,std::erase_if(std::vector) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase,std::erase_if(std::vector) \- std::erase,std::erase_if(std::vector) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class U > + \fI(since C++20)\fP + constexpr std::vector::size_type (until C++26) + + erase( std::vector& c, const U& value ); + template< class T, class Alloc, class U = T > + + constexpr std::vector::size_type \fB(1)\fP (since C++26) + + erase( std::vector& c, const U& value ); + template< class T, class Alloc, class Pred > + + constexpr std::vector::size_type \fB(2)\fP \fI(since C++20)\fP + + erase_if( std::vector& c, Pred pred ); + + 1) Erases all elements that compare equal to value from the container. Equivalent to + + auto it = std::remove(c.begin(), c.end(), value); + auto r = c.end() - it; + c.erase(it, c.end()); + return r; + + 2) Erases all elements that satisfy the predicate pred from the container. + Equivalent to + + auto it = std::remove_if(c.begin(), c.end(), pred); + auto r = c.end() - it; + c.erase(it, c.end()); + return r; + +.SH Parameters + + c - container from which to erase + value - value to be removed + unary predicate which returns true if the element should be erased. + + The expression pred(v) must be convertible to bool for every argument v of + pred - type (possibly const) T, regardless of value category, and must not modify + v. Thus, a parameter type of T&is not allowed + , nor is T unless for T a move is equivalent to a copy + \fI(since C++11)\fP. + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithm \fB(1)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(std::string_view comment, const auto& c) + { + std::cout << comment << "{ "; + for (const auto& x : c) + std::cout << x << ' '; + std::cout << "}\\n"; + } + + int main() + { + std::vector cnt(10); + std::iota(cnt.begin(), cnt.end(), '0'); + println("Initially, cnt = ", cnt); + + std::erase(cnt, '3'); + println("After erase '3', cnt = ", cnt); + + auto erased = std::erase_if(cnt, [](char x) { return (x - '0') % 2 == 0; }); + println("After erase all even numbers, cnt = ", cnt); + std::cout << "Erased even numbers: " << erased << '\\n'; + + std::vector> nums{{2, 2}, {4, 2}, {4, 8}, {4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + std::erase(nums, {4, 2}); + #else + std::erase(nums, std::complex{4, 2}); + #endif + println("After erase {4, 2}, nums = ", nums); + } + +.SH Output: + + Initially, cnt = { 0 1 2 3 4 5 6 7 8 9 } + After erase '3', cnt = { 0 1 2 4 5 6 7 8 9 } + After erase all even numbers, cnt = { 1 5 7 9 } + Erased even numbers: 5 + After erase {4, 2}, nums = { (2,2) (4,8) } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::flat_map).3 b/man/std::erase_if(std::flat_map).3 new file mode 100644 index 000000000..2d19dfb34 --- /dev/null +++ b/man/std::erase_if(std::flat_map).3 @@ -0,0 +1,93 @@ +.TH std::erase_if(std::flat_map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::flat_map) \- std::erase_if(std::flat_map) + +.SH Synopsis + Defined in header + template< class Key, class T, class Compare, class KeyContainer, + class MappedContainer, + + class Pred > + std::flat_map::size_type + erase_if( std::flat_map& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + The predicate pred is satisfied if the expression bool(pred(std::pair(e))) is true, where e is some element in c. + + Key and T must be MoveAssignable. Otherwise, the behavior is undefined. + +.SH Parameters + + c - container adaptor from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Exactly c.size() applications of the predicate pred. + +.SH Exceptions + + If erase_if throws, c remains in valid but unspecified (maybe empty) state. + +.SH Notes + + The algorithm is stable, that is, the order of elements that are not deleted remains + unchanged. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& [key, value] : container) + std::cout << sep << '{' << key << ", " << value << '}', *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::flat_map data + { + {1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, + {5, 'e'}, {4, 'f'}, {5, 'g'}, {5, 'g'}, + }; + println("Original:\\n", data); + + const auto count = std::erase_if(data, [](const auto& item) + { + auto const& [key, value] = item; + return (key & 1) == 1; + }); + + println("Erase items with odd keys:\\n", data); + std::cout << count << " items removed.\\n"; + } + +.SH Output: + + Original: + {{1, a}, {2, b}, {3, c}, {4, d}, {5, e}} + Erase items with odd keys: + {{2, b}, {4, d}} + 3 items removed. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::flat_multimap).3 b/man/std::erase_if(std::flat_multimap).3 new file mode 100644 index 000000000..88e75da81 --- /dev/null +++ b/man/std::erase_if(std::flat_multimap).3 @@ -0,0 +1,93 @@ +.TH std::erase_if(std::flat_multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::flat_multimap) \- std::erase_if(std::flat_multimap) + +.SH Synopsis + Defined in header + template< class Key, class T, class Compare, class KeyContainer, + class MappedContainer, + + class Pred > + std::flat_multimap::size_type + erase_if( std::flat_multimap& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + The predicate pred is satisfied if the expression bool(pred(std::pair(e))) is true, where e is some element in c. + + Key and T must be MoveAssignable. Otherwise, the behavior is undefined. + +.SH Parameters + + c - container adaptor from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Exactly c.size() applications of the predicate pred. + +.SH Exceptions + + If erase_if throws, c remains in valid but unspecified (maybe empty) state. + +.SH Notes + + The algorithm is stable, that is, the order of elements that are not deleted remains + unchanged. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& [key, value] : container) + std::cout << sep << '{' << key << ", " << value << '}', *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::flat_multimap data + { + {1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, + {5, 'e'}, {4, 'f'}, {5, 'g'}, {5, 'g'}, + }; + println("Original:\\n", data); + + const auto count = std::erase_if(data, [](const auto& item) + { + auto const& [key, value] = item; + return (key & 1) == 1; + }); + + println("Erase items with odd keys:\\n", data); + std::cout << count << " items removed.\\n"; + } + +.SH Output: + + Original: + {{1, a}, {2, b}, {3, c}, {4, d}, {4, f}, {5, e}, {5, g}, {5, g}} + Erase items with odd keys: + {{2, b}, {4, d}, {4, f}} + 5 items removed. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::flat_multiset).3 b/man/std::erase_if(std::flat_multiset).3 new file mode 100644 index 000000000..acf7d62f8 --- /dev/null +++ b/man/std::erase_if(std::flat_multiset).3 @@ -0,0 +1,84 @@ +.TH std::erase_if(std::flat_multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::flat_multiset) \- std::erase_if(std::flat_multiset) + +.SH Synopsis + Defined in header + template< class Key, class Compare, class KeyContainer, + + class Pred > + std::flat_multiset::size_type (since C++23) + erase_if( std::flat_multiset& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + The predicate pred is satisfied if the expression bool(pred(std::as_const(e))) is + true, where e is some element in c. + + Key must be MoveAssignable. Otherwise, the behavior is undefined. + +.SH Parameters + + c - container adaptor from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Exactly c.size() applications of the predicate pred. + +.SH Exceptions + + If erase_if throws, c remains in valid but unspecified (maybe empty) state. + +.SH Notes + + The algorithm is stable, that is, the order of elements that are not deleted remains + unchanged. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& item : container) + std::cout << sep << item, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::flat_multiset data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + println("Original:\\n", data); + + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + + const auto count = std::erase_if(data, divisible_by_3); + + println("Erase all items divisible by 3:\\n", data); + std::cout << count << " items erased.\\n"; + } + +.SH Output: + + Original: + {0, 1, 2, 3, 3, 4, 5, 5, 6, 6, 7} + Erase all items divisible by 3: + {1, 2, 4, 5, 5, 7} + 5 items erased. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::flat_set).3 b/man/std::erase_if(std::flat_set).3 new file mode 100644 index 000000000..1ef467bf2 --- /dev/null +++ b/man/std::erase_if(std::flat_set).3 @@ -0,0 +1,84 @@ +.TH std::erase_if(std::flat_set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::flat_set) \- std::erase_if(std::flat_set) + +.SH Synopsis + Defined in header + template< class Key, class Compare, class KeyContainer, + + class Pred > + std::flat_set::size_type (since C++23) + erase_if( std::flat_set& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + The predicate pred is satisfied if the expression bool(pred(std::as_const(e))) is + true, where e is some element in c. + + Key must be MoveAssignable. Otherwise, the behavior is undefined. + +.SH Parameters + + c - container adaptor from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Exactly c.size() applications of the predicate pred. + +.SH Exceptions + + If erase_if throws, c remains in valid but unspecified (maybe empty) state. + +.SH Notes + + The algorithm is stable, that is, the order of elements that are not deleted remains + unchanged. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& item : container) + std::cout << sep << item, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::flat_set data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + println("Original:\\n", data); + + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + + const auto count = std::erase_if(data, divisible_by_3); + + println("Erase all items divisible by 3:\\n", data); + std::cout << count << " items erased.\\n"; + } + +.SH Output: + + Original: + {0, 1, 2, 3, 4, 5, 6, 7} + Erase all items divisible by 3: + {1, 2, 4, 5, 7} + 3 items erased. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::map).3 b/man/std::erase_if(std::map).3 new file mode 100644 index 000000000..738f24d0f --- /dev/null +++ b/man/std::erase_if(std::map).3 @@ -0,0 +1,88 @@ +.TH std::erase_if(std::map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::map) \- std::erase_if(std::map) + +.SH Synopsis + Defined in header + template< class Key, class T, class Compare, class Alloc, + + class Pred > + std::map::size_type \fI(since C++20)\fP + erase_if( std::map& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& [key, value] : container) + std::cout << sep << '{' << key << ", " << value << '}', *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::map data + { + {1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, + {5, 'e'}, {4, 'f'}, {5, 'g'}, {5, 'g'}, + }; + println("Original:\\n", data); + + const auto count = std::erase_if(data, [](const auto& item) + { + auto const& [key, value] = item; + return (key & 1) == 1; + }); + + println("Erase items with odd keys:\\n", data); + std::cout << count << " items removed.\\n"; + } + +.SH Output: + + Original: + {{1, a}, {2, b}, {3, c}, {4, d}, {5, e}} + Erase items with odd keys: + {{2, b}, {4, d}} + 3 items removed. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::multimap).3 b/man/std::erase_if(std::multimap).3 new file mode 100644 index 000000000..476811d7f --- /dev/null +++ b/man/std::erase_if(std::multimap).3 @@ -0,0 +1,88 @@ +.TH std::erase_if(std::multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::multimap) \- std::erase_if(std::multimap) + +.SH Synopsis + Defined in header + template< class Key, class T, class Compare, class Alloc, + + class Pred > + std::multimap::size_type \fI(since C++20)\fP + erase_if( std::multimap& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& [key, value] : container) + std::cout << sep << '{' << key << ", " << value << '}', *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::multimap data + { + {1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, + {5, 'e'}, {4, 'f'}, {5, 'g'}, {5, 'g'}, + }; + println("Original:\\n", data); + + const auto count = std::erase_if(data, [](const auto& item) + { + auto const& [key, value] = item; + return (key & 1) == 1; + }); + + println("Erase items with odd keys:\\n", data); + std::cout << count << " items removed.\\n"; + } + +.SH Output: + + Original: + {{1, a}, {2, b}, {3, c}, {4, d}, {4, f}, {5, e}, {5, g}, {5, g}} + Erase items with odd keys: + {{2, b}, {4, d}, {4, f}} + 5 items removed. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::multiset).3 b/man/std::erase_if(std::multiset).3 new file mode 100644 index 000000000..8991bdf2d --- /dev/null +++ b/man/std::erase_if(std::multiset).3 @@ -0,0 +1,82 @@ +.TH std::erase_if(std::multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::multiset) \- std::erase_if(std::multiset) + +.SH Synopsis + Defined in header + template< class Key, class Compare, class Alloc, + + class Pred > + std::multiset::size_type \fI(since C++20)\fP + erase_if( std::multiset& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& item : container) + std::cout << sep << item, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::multiset data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + println("Original:\\n", data); + + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + + const auto count = std::erase_if(data, divisible_by_3); + + println("Erase all items divisible by 3:\\n", data); + std::cout << count << " items erased.\\n"; + } + +.SH Output: + + Original: + {0, 1, 2, 3, 3, 4, 5, 5, 6, 6, 7} + Erase all items divisible by 3: + {1, 2, 4, 5, 5, 7} + 5 items erased. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::set).3 b/man/std::erase_if(std::set).3 new file mode 100644 index 000000000..059d624cf --- /dev/null +++ b/man/std::erase_if(std::set).3 @@ -0,0 +1,82 @@ +.TH std::erase_if(std::set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::set) \- std::erase_if(std::set) + +.SH Synopsis + Defined in header + template< class Key, class Compare, class Alloc, + + class Pred > + std::set::size_type \fI(since C++20)\fP + erase_if( std::set& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& item : container) + std::cout << sep << item, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::set data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + println("Original:\\n", data); + + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + + const auto count = std::erase_if(data, divisible_by_3); + + println("Erase all items divisible by 3:\\n", data); + std::cout << count << " items erased.\\n"; + } + +.SH Output: + + Original: + {0, 1, 2, 3, 4, 5, 6, 7} + Erase all items divisible by 3: + {1, 2, 4, 5, 7} + 3 items erased. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::unordered_map).3 b/man/std::erase_if(std::unordered_map).3 new file mode 100644 index 000000000..0c0d61bd4 --- /dev/null +++ b/man/std::erase_if(std::unordered_map).3 @@ -0,0 +1,89 @@ +.TH std::erase_if(std::unordered_map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::unordered_map) \- std::erase_if(std::unordered_map) + +.SH Synopsis + Defined in header + template< class Key, class T, class Hash, class KeyEqual, class + Alloc, + + class Pred > \fI(since C++20)\fP + std::unordered_map::size_type + erase_if( std::unordered_map& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& [key, value] : container) + std::cout << sep << '{' << key << ", " << value << '}', *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::unordered_map data + { + {1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, + {5, 'e'}, {4, 'f'}, {5, 'g'}, {5, 'g'}, + }; + println("Original:\\n", data); + + const auto count = std::erase_if(data, [](const auto& item) + { + auto const& [key, value] = item; + return (key & 1) == 1; + }); + + println("Erase items with odd keys:\\n", data); + std::cout << count << " items removed.\\n"; + } + +.SH Possible output: + + Original: + {{5, e}, {4, d}, {3, c}, {2, b}, {1, a}} + Erase items with odd keys: + {{4, d}, {2, b}} + 3 items removed. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::unordered_multimap).3 b/man/std::erase_if(std::unordered_multimap).3 new file mode 100644 index 000000000..f44da838a --- /dev/null +++ b/man/std::erase_if(std::unordered_multimap).3 @@ -0,0 +1,90 @@ +.TH std::erase_if(std::unordered_multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::unordered_multimap) \- std::erase_if(std::unordered_multimap) + +.SH Synopsis + Defined in header + template< class Key, class T, class Hash, class KeyEqual, class + Alloc, + + class Pred > + std::unordered_multimap::size_type \fI(since C++20)\fP + erase_if( std::unordered_multimap& + c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& [key, value] : container) + std::cout << sep << '{' << key << ", " << value << '}', *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::unordered_multimap data + { + {1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, + {5, 'e'}, {4, 'f'}, {5, 'g'}, {5, 'g'}, + }; + println("Original:\\n", data); + + const auto count = std::erase_if(data, [](const auto& item) + { + auto const& [key, value] = item; + return (key & 1) == 1; + }); + + println("Erase items with odd keys:\\n", data); + std::cout << count << " items removed.\\n"; + } + +.SH Possible output: + + Original: + {{5, g}, {5, g}, {5, e}, {4, f}, {4, d}, {3, c}, {2, b}, {1, a}} + Erase items with odd keys: + {{4, f}, {4, d}, {2, b}} + 5 items removed. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::unordered_multiset).3 b/man/std::erase_if(std::unordered_multiset).3 new file mode 100644 index 000000000..9c2ee7546 --- /dev/null +++ b/man/std::erase_if(std::unordered_multiset).3 @@ -0,0 +1,82 @@ +.TH std::erase_if(std::unordered_multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::unordered_multiset) \- std::erase_if(std::unordered_multiset) + +.SH Synopsis + Defined in header + template< class Key, class Hash, class KeyEqual, class Alloc, + + class Pred > + std::unordered_multiset::size_type \fI(since C++20)\fP + erase_if( std::unordered_multiset& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& item : container) + std::cout << sep << item, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::unordered_multiset data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + println("Original:\\n", data); + + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + + const auto count = std::erase_if(data, divisible_by_3); + + println("Erase all items divisible by 3:\\n", data); + std::cout << count << " items erased.\\n"; + } + +.SH Possible output: + + Original: + {0, 1, 2, 7, 6, 6, 5, 5, 4, 3, 3} + Erase all items divisible by 3: + {1, 2, 7, 5, 5, 4} + 5 items erased. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erase_if(std::unordered_set).3 b/man/std::erase_if(std::unordered_set).3 new file mode 100644 index 000000000..b7e365632 --- /dev/null +++ b/man/std::erase_if(std::unordered_set).3 @@ -0,0 +1,82 @@ +.TH std::erase_if(std::unordered_set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erase_if(std::unordered_set) \- std::erase_if(std::unordered_set) + +.SH Synopsis + Defined in header + template< class Key, class Hash, class KeyEqual, class Alloc, + + class Pred > + std::unordered_set::size_type \fI(since C++20)\fP + erase_if( std::unordered_set& c, + + Pred pred ); + + Erases all elements that satisfy the predicate pred from c. + + Equivalent to + + auto old_size = c.size(); + for (auto first = c.begin(), last = c.end(); first != last;) + { + if (pred(*first)) + first = c.erase(first); + else + ++first; + } + return old_size - c.size(); + +.SH Parameters + + c - container from which to erase + pred - predicate that returns true if the element should be erased + +.SH Return value + + The number of erased elements. + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto rem, auto const& container) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; const auto& item : container) + std::cout << sep << item, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::unordered_set data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + println("Original:\\n", data); + + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + + const auto count = std::erase_if(data, divisible_by_3); + + println("Erase all items divisible by 3:\\n", data); + std::cout << count << " items erased.\\n"; + } + +.SH Possible output: + + Original: + {0, 1, 2, 7, 6, 5, 4, 3} + Erase all items divisible by 3: + {1, 2, 7, 5, 4} + 3 items erased. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::erf,std::erff,std::erfl.3 b/man/std::erf,std::erff,std::erfl.3 new file mode 100644 index 000000000..f58223699 --- /dev/null +++ b/man/std::erf,std::erff,std::erfl.3 @@ -0,0 +1,144 @@ +.TH std::erf,std::erff,std::erfl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erf,std::erff,std::erfl \- std::erf,std::erff,std::erfl + +.SH Synopsis + Defined in header + float erf ( float num ); + + double erf ( double num ); (until C++23) + + long double erf ( long double num ); + /* floating-point-type */ (since C++23) + erf ( /* floating-point-type */ num ); (constexpr since C++26) + float erff( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double erfl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double erf ( Integer num ); + + 1-3) Computes the error function of num. + The library provides overloads of std::erf for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, value of the error function of num, that is + \\(\\frac{2}{\\sqrt{\\pi} }\\int_{0}^{num}{e^{-{t^2} }\\mathsf{d}t}\\) + + 2 + √ + π + + ∫num + 0e^-t2 + dt, is returned. + If a range error occurs due to underflow, the correct result (after rounding), that + is \\(\\frac{2\\cdot num}{\\sqrt{\\pi} }\\) + + 2*num + √ + π + + is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, ±0 is returned. + * If the argument is ±∞, ±1 is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + Underflow is guaranteed if |num| < DBL_MIN * (std::sqrt(π) / 2). + + \\(\\operatorname{erf}(\\frac{x}{\\sigma \\sqrt{2} })\\)erf( + + x + σ + √ + 2 + + ) is the probability that a measurement whose errors are subject to a normal + distribution with standard deviation \\(\\sigma\\)σ is less than \\(x\\)x away from the + mean value. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::erf(num) has the same effect as std::erf(static_cast(num)). + +.SH Example + + The following example calculates the probability that a normal variate is on the + interval (x1, x2): + + +// Run this code + + #include + #include + #include + + double phi(double x1, double x2) + { + return (std::erf(x2 / std::sqrt(2)) - std::erf(x1 / std::sqrt(2))) / 2; + } + + int main() + { + std::cout << "Normal variate probabilities:\\n" + << std::fixed << std::setprecision(2); + for (int n = -4; n < 4; ++n) + std::cout << '[' << std::setw(2) << n + << ':' << std::setw(2) << n + 1 << "]: " + << std::setw(5) << 100 * phi(n, n + 1) << "%\\n"; + + std::cout << "Special values:\\n" + << "erf(-0) = " << std::erf(-0.0) << '\\n' + << "erf(Inf) = " << std::erf(INFINITY) << '\\n'; + } + +.SH Output: + + Normal variate probabilities: + [-4:-3]: 0.13% + [-3:-2]: 2.14% + [-2:-1]: 13.59% + [-1: 0]: 34.13% + [ 0: 1]: 34.13% + [ 1: 2]: 13.59% + [ 2: 3]: 2.14% + [ 3: 4]: 0.13% + Special values: + erf(-0) = -0.00 + erf(Inf) = 1.00 + +.SH See also + + erfc + erfcf + erfcl complementary error function + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + erf + +.SH External links + + Weisstein, Eric W. "Erf." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::erf.3 b/man/std::erf.3 deleted file mode 100644 index 22cebb5f9..000000000 --- a/man/std::erf.3 +++ /dev/null @@ -1,70 +0,0 @@ -.TH std::erf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float erf( float arg ); \fI(since C++11)\fP - double erf( double arg ); \fI(since C++11)\fP - long double erf( long double arg ); \fI(since C++11)\fP - double erf( Integral arg ); \fI(since C++11)\fP - - Computes the error function of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - The value of the error function of arg, that is - - 2 - √ - π - - ∫arg - 0e^-t2 - dt. - -.SH Example - - The following example calculates the probability that a normal variate is on the - interval (x1, x2) - - -// Run this code - - #include - #include - #include - double phi(double x1, double x2) - { - return (std::erf(x2/std::sqrt(2)) - std::erf(x1/std::sqrt(2)))/2; - } - int main() - { - std::cout << "normal variate probabilities:\\n"; - for(int n=-4; n<4; ++n) - std::cout << "[" << std::setw(2) << n << ":" << std::setw(2) << n+1 << "]: " - << std::setw(5) << std::fixed << std::setprecision(2) - << 100*phi(n, n+1) << "%\\n"; - } - -.SH Output: - - normal variate probabilities: - [-4:-3]: 0.13% - [-3:-2]: 2.14% - [-2:-1]: 13.59% - [-1: 0]: 34.13% - [ 0: 1]: 34.13% - [ 1: 2]: 13.59% - [ 2: 3]: 2.14% - [ 3: 4]: 0.13% - -.SH See also - - erfc complementary error function - \fI(C++11)\fP \fI(function)\fP - -.SH External links - - Weisstein, Eric W. "Erf." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::erfc,std::erfcf,std::erfcl.3 b/man/std::erfc,std::erfcf,std::erfcl.3 new file mode 100644 index 000000000..d98ded3e4 --- /dev/null +++ b/man/std::erfc,std::erfcf,std::erfcl.3 @@ -0,0 +1,127 @@ +.TH std::erfc,std::erfcf,std::erfcl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::erfc,std::erfcf,std::erfcl \- std::erfc,std::erfcf,std::erfcl + +.SH Synopsis + Defined in header + float erfc ( float num ); + + double erfc ( double num ); (until C++23) + + long double erfc ( long double num ); + /* floating-point-type */ (since C++23) + erfc ( /* floating-point-type */ num ); (constexpr since C++26) + float erfcf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double erfcl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double erfc ( Integer num ); + + 1-3) Computes the complementary error function of num, that is 1.0 - std::erf(num), + but without loss of precision for large num. + The library provides overloads of std::erfc for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, value of the complementary error function of num, that is + \\(\\frac{2}{\\sqrt{\\pi} }\\int_{num}^{\\infty}{e^{-{t^2} }\\mathsf{d}t}\\) + + 2 + √ + π + + ∫∞ + nume^-t2 + dt or \\({\\small 1-\\operatorname{erf}(num)}\\)1-erf(num), is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is +∞, +0 is returned. + * If the argument is -∞, 2 is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + For the IEEE-compatible type double, underflow is guaranteed if num > 26.55. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::erfc(num) has the same effect as std::erfc(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + double normalCDF(double x) // Phi(-∞, x) aka N(x) + { + return std::erfc(-x / std::sqrt(2)) / 2; + } + + int main() + { + std::cout << "normal cumulative distribution function:\\n" + << std::fixed << std::setprecision(2); + for (double n = 0; n < 1; n += 0.1) + std::cout << "normalCDF(" << n << ") = " << 100 * normalCDF(n) << "%\\n"; + + std::cout << "special values:\\n" + << "erfc(-Inf) = " << std::erfc(-INFINITY) << '\\n' + << "erfc(Inf) = " << std::erfc(INFINITY) << '\\n'; + } + +.SH Output: + + normal cumulative distribution function: + normalCDF(0.00) = 50.00% + normalCDF(0.10) = 53.98% + normalCDF(0.20) = 57.93% + normalCDF(0.30) = 61.79% + normalCDF(0.40) = 65.54% + normalCDF(0.50) = 69.15% + normalCDF(0.60) = 72.57% + normalCDF(0.70) = 75.80% + normalCDF(0.80) = 78.81% + normalCDF(0.90) = 81.59% + normalCDF(1.00) = 84.13% + special values: + erfc(-Inf) = 2.00 + erfc(Inf) = 0.00 + +.SH See also + + erf + erff + erfl error function + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + erfc + +.SH External links + + Weisstein, Eric W. "Erfc." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::erfc.3 b/man/std::erfc.3 deleted file mode 100644 index 28e07f58d..000000000 --- a/man/std::erfc.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::erfc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float erfc( float arg ); \fI(since C++11)\fP - double erfc( double arg ); \fI(since C++11)\fP - long double erfc( long double arg ); \fI(since C++11)\fP - double erfc( Integral arg ); \fI(since C++11)\fP - - Computes the complementary error function of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - The value of the complementary error function of arg, that is 1-std::erf(arg). - -.SH See also - - erf error function - \fI(C++11)\fP \fI(function)\fP - -.SH External links - - Weisstein, Eric W. "Erfc." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::errc.3 b/man/std::errc.3 index aa40588b0..8fb850659 100644 --- a/man/std::errc.3 +++ b/man/std::errc.3 @@ -1,4 +1,7 @@ -.TH std::errc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::errc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::errc \- std::errc + .SH Synopsis Defined in header enum class errc; \fI(since C++11)\fP @@ -8,190 +11,204 @@ .SH Member constants - Constant Explanation - address_family_not_supported error condition corresponding to POSIX code - EAFNOSUPPORT - address_in_use error condition corresponding to POSIX code - EADDRINUSE - address_not_available error condition corresponding to POSIX code - EADDRNOTAVAIL - already_connected error condition corresponding to POSIX code - EISCONN - argument_list_too_long error condition corresponding to POSIX code E2BIG - argument_out_of_domain error condition corresponding to POSIX code EDOM - bad_address error condition corresponding to POSIX code - EFAULT - bad_file_descriptor error condition corresponding to POSIX code EBADF - bad_message error condition corresponding to POSIX code - EBADMSG - broken_pipe error condition corresponding to POSIX code EPIPE - connection_aborted error condition corresponding to POSIX code - ECONNABORTED - connection_already_in_progress error condition corresponding to POSIX code - EALREADY - connection_refused error condition corresponding to POSIX code - ECONNREFUSED - connection_reset error condition corresponding to POSIX code - ECONNRESET - cross_device_link error condition corresponding to POSIX code EXDEV - destination_address_required error condition corresponding to POSIX code - EDESTADDRREQ - device_or_resource_busy error condition corresponding to POSIX code EBUSY - directory_not_empty error condition corresponding to POSIX code - ENOTEMPTY - executable_format_error error condition corresponding to POSIX code - ENOEXEC - file_exists error condition corresponding to POSIX code - EEXIST - file_too_large error condition corresponding to POSIX code EFBIG - filename_too_long error condition corresponding to POSIX code - ENAMETOOLONG - function_not_supported error condition corresponding to POSIX code - ENOSYS - host_unreachable error condition corresponding to POSIX code - EHOSTUNREACH - identifier_removed error condition corresponding to POSIX code EIDRM - illegal_byte_sequence error condition corresponding to POSIX code - EILSEQ - inappropriate_io_control_operation error condition corresponding to POSIX code - ENOTTY - interrupted error condition corresponding to POSIX code EINTR - invalid_argument error condition corresponding to POSIX code - EINVAL - invalid_seek error condition corresponding to POSIX code - ESPIPE - io_error error condition corresponding to POSIX code EIO - is_a_directory error condition corresponding to POSIX code - EISDIR - message_size error condition corresponding to POSIX code - EMSGSIZE - network_down error condition corresponding to POSIX code - ENETDOWN - network_reset error condition corresponding to POSIX code - ENETRESET - network_unreachable error condition corresponding to POSIX code - ENETUNREACH - no_buffer_space error condition corresponding to POSIX code - ENOBUFS - no_child_process error condition corresponding to POSIX code - ECHILD - no_link error condition corresponding to POSIX code - ENOLINK - no_lock_available error condition corresponding to POSIX code - ENOLCK - no_message_available error condition corresponding to POSIX code - ENODATA - no_message error condition corresponding to POSIX code - ENOMSG - no_protocol_option error condition corresponding to POSIX code - ENOPROTOOPT - no_space_on_device error condition corresponding to POSIX code - ENOSPC - no_stream_resources error condition corresponding to POSIX code ENOSR - no_such_device_or_address error condition corresponding to POSIX code ENXIO - no_such_device error condition corresponding to POSIX code - ENODEV - no_such_file_or_directory error condition corresponding to POSIX code - ENOENT - no_such_process error condition corresponding to POSIX code ESRCH - not_a_directory error condition corresponding to POSIX code - ENOTDIR - not_a_socket error condition corresponding to POSIX code - ENOTSOCK - not_a_stream error condition corresponding to POSIX code - ENOSTR - not_connected error condition corresponding to POSIX code - ENOTCONN - not_enough_memory error condition corresponding to POSIX code - ENOMEM - not_supported error condition corresponding to POSIX code - ENOTSUP - operation_canceled error condition corresponding to POSIX code - ECANCELED - operation_in_progress error condition corresponding to POSIX code - EINPROGRESS - operation_not_permitted error condition corresponding to POSIX code EPERM - operation_not_supported error condition corresponding to POSIX code - EOPNOTSUPP - operation_would_block error condition corresponding to POSIX code - EWOULDBLOCK - owner_dead error condition corresponding to POSIX code - EOWNERDEAD - permission_denied error condition corresponding to POSIX code - EACCES - protocol_error error condition corresponding to POSIX code - EPROTO - protocol_not_supported error condition corresponding to POSIX code - EPROTONOSUPPORT - read_only_file_system error condition corresponding to POSIX code EROFS - resource_deadlock_would_occur error condition corresponding to POSIX code - EDEADLK - resource_unavailable_try_again error condition corresponding to POSIX code - EAGAIN - result_out_of_range error condition corresponding to POSIX code - ERANGE - state_not_recoverable error condition corresponding to POSIX code - ENOTRECOVERABLE - stream_timeout error condition corresponding to POSIX code ETIME - text_file_busy error condition corresponding to POSIX code - ETXTBSY - timed_out error condition corresponding to POSIX code - ETIMEDOUT - too_many_files_open_in_system error condition corresponding to POSIX code - ENFILE - too_many_files_open error condition corresponding to POSIX code - EMFILE - too_many_links error condition corresponding to POSIX code - EMLINK - too_many_symbolic_link_levels error condition corresponding to POSIX code ELOOP - value_too_large error condition corresponding to POSIX code - EOVERFLOW - wrong_protocol_type error condition corresponding to POSIX code - EPROTOTYPE + Constant Equivalent POSIX Error + address_family_not_supported EAFNOSUPPORT + address_in_use EADDRINUSE + address_not_available EADDRNOTAVAIL + already_connected EISCONN + argument_list_too_long E2BIG + argument_out_of_domain EDOM + bad_address EFAULT + bad_file_descriptor EBADF + bad_message EBADMSG + broken_pipe EPIPE + connection_aborted ECONNABORTED + connection_already_in_progress EALREADY + connection_refused ECONNREFUSED + connection_reset ECONNRESET + cross_device_link EXDEV + destination_address_required EDESTADDRREQ + device_or_resource_busy EBUSY + directory_not_empty ENOTEMPTY + executable_format_error ENOEXEC + file_exists EEXIST + file_too_large EFBIG + filename_too_long ENAMETOOLONG + function_not_supported ENOSYS + host_unreachable EHOSTUNREACH + identifier_removed EIDRM + illegal_byte_sequence EILSEQ + inappropriate_io_control_operation ENOTTY + interrupted EINTR + invalid_argument EINVAL + invalid_seek ESPIPE + io_error EIO + is_a_directory EISDIR + message_size EMSGSIZE + network_down ENETDOWN + network_reset ENETRESET + network_unreachable ENETUNREACH + no_buffer_space ENOBUFS + no_child_process ECHILD + no_link ENOLINK + no_lock_available ENOLCK + no_message_available \fB(deprecated)\fP ENODATA + no_message ENOMSG + no_protocol_option ENOPROTOOPT + no_space_on_device ENOSPC + no_stream_resources \fB(deprecated)\fP ENOSR + no_such_device_or_address ENXIO + no_such_device ENODEV + no_such_file_or_directory ENOENT + no_such_process ESRCH + not_a_directory ENOTDIR + not_a_socket ENOTSOCK + not_a_stream \fB(deprecated)\fP ENOSTR + not_connected ENOTCONN + not_enough_memory ENOMEM + not_supported ENOTSUP + operation_canceled ECANCELED + operation_in_progress EINPROGRESS + operation_not_permitted EPERM + operation_not_supported EOPNOTSUPP + operation_would_block EWOULDBLOCK + owner_dead EOWNERDEAD + permission_denied EACCES + protocol_error EPROTO + protocol_not_supported EPROTONOSUPPORT + read_only_file_system EROFS + resource_deadlock_would_occur EDEADLK + resource_unavailable_try_again EAGAIN + result_out_of_range ERANGE + state_not_recoverable ENOTRECOVERABLE + stream_timeout \fB(deprecated)\fP ETIME + text_file_busy ETXTBSY + timed_out ETIMEDOUT + too_many_files_open_in_system ENFILE + too_many_files_open EMFILE + too_many_links EMLINK + too_many_symbolic_link_levels ELOOP + value_too_large EOVERFLOW + wrong_protocol_type EPROTOTYPE .SH Non-member functions - make_error_code(std::errc) constructs an std::errc error code - \fI(C++11)\fP \fI(function)\fP - make_error_condition(std::errc) constructs an std::errc error condition - \fI(C++11)\fP \fI(function)\fP + make_error_code(std::errc) creates error code value for errc enum e + \fI(C++11)\fP \fI(function)\fP + make_error_condition(std::errc) creates an error condition for an errc value e + \fI(C++11)\fP \fI(function)\fP .SH Helper classes extends the type trait - is_error_condition_enum std::is_error_condition_enum to identify the the - \fI(C++11)\fP std::errc values as error conditions - \fI(function template)\fP + is_error_condition_enum std::is_error_condition_enum to identify errc + \fI(C++11)\fP values as error conditions + \fI(function template)\fP .SH Example - + // Run this code + #include + #include + #include #include + #include #include #include + + void print_error(const std::string& details, std::error_code error_code) + { + std::string value_name; + if (error_code == std::errc::invalid_argument) + value_name = "std::errc::invalid_argument"; + if (error_code == std::errc::no_such_file_or_directory) + value_name = "std::errc::no_such_file_or_directory"; + if (error_code == std::errc::is_a_directory) + value_name = "std::errc::is_a_directory"; + if (error_code == std::errc::permission_denied) + value_name = "std::errc::permission_denied"; + + std::cout << details << ":\\n " + << std::quoted(error_code.message()) + << " (" << value_name << ")\\n\\n"; + } + + void print_errno(const std::string& details, int errno_value = errno) + { + print_error(details, std::make_error_code(std::errc(errno_value))); + } + int main() { - try { - std::thread().detach(); // detaching a not-a-thread - } catch (const std::system_error& e) { - std::cout << "Caught a system_error\\n"; - if(e.code() == std::errc::invalid_argument) - std::cout << "The error condition is std::errc::invalid_argument\\n"; - std::cout << "the error description is " << e.what() << '\\n'; + std::cout << "Detaching a not-a-thread...\\n"; + try + { + std::thread().detach(); + } + catch (const std::system_error& e) + { + print_error("Error detaching empty thread", e.code()); } + + std::cout << "Opening nonexistent file...\\n"; + std::ifstream nofile{"nonexistent-file"}; + if (!nofile.is_open()) + print_errno("Error opening nonexistent file for reading"); + + std::cout << "Reading from directory as a file...\\n"; + std::filesystem::create_directory("dir"); + std::ifstream dir_stream{"dir"}; + [[maybe_unused]] char c = dir_stream.get(); + if (!dir_stream.good()) + print_errno("Error reading data from directory"); + + std::cout << "Open read-only file for writing...\\n"; + std::fstream{"readonly-file", std::ios::out}; + std::filesystem::permissions("readonly-file", std::filesystem::perms::owner_read); + std::fstream write_readonly("readonly-file", std::ios::out); + if (!write_readonly.is_open()) + print_errno("Error opening read-only file for writing"); } -.SH Output: +.SH Possible output: + + Detaching a not-a-thread... + Error detaching empty thread: + "Invalid argument" (std::errc::invalid_argument) + + Opening nonexistent file... + Error opening nonexistent file for reading: + "No such file or directory" (std::errc::no_such_file_or_directory) + + Reading from directory as a file... + Error reading data from directory: + "Is a directory" (std::errc::is_a_directory) + + Open read-only file for writing... + Error opening read-only file for writing: + "Permission denied" (std::errc::permission_denied) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the member constants no_message_available, + LWG 3869 C++11 no_stream_resources, not_a_stream and deprecated them + stream_timeout + referred to the obsolete POSIX STREAMS API^[1] - Caught a system_error - The error condition is std::errc::invalid_argument - the error description is Invalid argument + 1. ↑ Although the corresponding POSIX error numbers ENODATA, ENOSR, ENOSTR and + ETIME were marked "obsolescent" in POSIX 2017, the STREAMS API was optional and + not required for conformance to the previous POSIX standard (because popular + unix-like systems refused to implement it). .SH See also error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::error_category.3 b/man/std::error_category.3 index 50c0cd5f2..8b1858b32 100644 --- a/man/std::error_category.3 +++ b/man/std::error_category.3 @@ -1,4 +1,7 @@ -.TH std::error_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category \- std::error_category + .SH Synopsis Defined in header class error_category; \fI(since C++11)\fP @@ -12,38 +15,42 @@ .SH Member functions constructor constructs an error_category - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs an error_category - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP operator= not copy assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP name obtains the name of the category - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP default_error_condition maps error_code to error_condition - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP equivalent compares error_code and error_condition for equivalence - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP message obtains the explanatory string - \fB[virtual]\fP \fI(virtual public member function)\fP - operator== compares two error categories - operator!= \fI(function)\fP - operator< + \fB[virtual]\fP \fI(virtual public member function)\fP + operator== + operator!= + operator< compares two error categories + operator<=> \fI(function)\fP + (removed in C++20) + (removed in C++20) + (C++20) Specific error categories -.SH See also - - error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP - error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP - - generic_category identifies the generic error category - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP system_category identifies the operating system error category - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP iostream_category identifies the iostream error category - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP future_category identifies the future error category - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + +.SH See also + + + error_condition holds a portable error code + \fI(C++11)\fP \fI(class)\fP + error_code holds a platform-dependent error code + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::error_category::default_error_condition.3 b/man/std::error_category::default_error_condition.3 index 63bc3b10e..64dbdafd2 100644 --- a/man/std::error_category::default_error_condition.3 +++ b/man/std::error_category::default_error_condition.3 @@ -1,22 +1,24 @@ -.TH std::error_category::default_error_condition 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category::default_error_condition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::default_error_condition \- std::error_category::default_error_condition + .SH Synopsis - virtual std::error_condition default_error_condition( int code ) \fI(since C++11)\fP - const; + virtual std::error_condition default_error_condition( int val ) const \fI(since C++11)\fP + noexcept; + + Returns the error condition for the given error value. - Returns the error condition for the given error code. + Equivalent to std::error_condition(val, *this). - Equivalent to std::error_condition(code, *this). + Classes derived from error_category may override this function to map certain error + values to a generic category. For example, std::system_category overrides this + function to map the error values that match POSIX errno values to + std::generic_category. .SH Parameters - code - error code for which to return error condition + val - error value for which to return error condition .SH Return value The error condition for the given error code. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_category::equivalent.3 b/man/std::error_category::equivalent.3 index 8218c12c6..ac884561a 100644 --- a/man/std::error_category::equivalent.3 +++ b/man/std::error_category::equivalent.3 @@ -1,10 +1,13 @@ -.TH std::error_category::equivalent 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category::equivalent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::equivalent \- std::error_category::equivalent + .SH Synopsis virtual bool equivalent( int code, const std::error_condition& condition ) \fB(1)\fP \fI(since C++11)\fP - const; + const noexcept; virtual bool equivalent( const std::error_code& code, \fB(2)\fP \fI(since C++11)\fP - int condition ) const; + int condition ) const noexcept; Checks whether error code is equivalent to an error condition for the error category represented by *this. @@ -21,9 +24,3 @@ true if the error code is equivalent to the given error condition for the error category represented by *this, false otherwise. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_category::error_category.3 b/man/std::error_category::error_category.3 index 1f0292443..97cd72e37 100644 --- a/man/std::error_category::error_category.3 +++ b/man/std::error_category::error_category.3 @@ -1,17 +1,23 @@ -.TH std::error_category::error_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category::error_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::error_category \- std::error_category::error_category + .SH Synopsis - error_category( const error_category& other ) = delete; \fB(1)\fP \fI(since C++11)\fP - constexpr error_category(); \fB(2)\fP \fI(since C++14)\fP + constexpr error_category() noexcept; \fB(1)\fP \fI(since C++11)\fP + error_category( const error_category& ) = delete; \fB(2)\fP \fI(since C++11)\fP - Constructs the error category object. + 1) Constructs the error category object. + 2) Copy constructor is deleted. error_category is neither MoveConstructible nor + CopyConstructible. .SH Parameters \fI(none)\fP -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 2) - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + LWG 2145 C++11 error_category was not constructible default constructor added diff --git a/man/std::error_category::message.3 b/man/std::error_category::message.3 index 3cb5d234d..6649efd95 100644 --- a/man/std::error_category::message.3 +++ b/man/std::error_category::message.3 @@ -1,4 +1,7 @@ -.TH std::error_category::message 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category::message 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::message \- std::error_category::message + .SH Synopsis virtual std::string message( int condition ) const = 0; \fI(since C++11)\fP @@ -15,6 +18,4 @@ .SH Exceptions - noexcept specification: - noexcept - + May throw implementation-defined exceptions. diff --git a/man/std::error_category::name.3 b/man/std::error_category::name.3 index 82c99bb72..74ee27262 100644 --- a/man/std::error_category::name.3 +++ b/man/std::error_category::name.3 @@ -1,6 +1,9 @@ -.TH std::error_category::name 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category::name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::name \- std::error_category::name + .SH Synopsis - virtual const char* name() const = 0; \fI(since C++11)\fP + virtual const char* name() const noexcept = 0; \fI(since C++11)\fP Returns a pointer to a null-terminated byte string that specifies the name of the error category. @@ -12,9 +15,3 @@ .SH Return value Null-terminated byte string specifying the name of the error category. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_category::operator==,!=,.3 b/man/std::error_category::operator==,!=,.3 new file mode 100644 index 000000000..e9f0d3b61 --- /dev/null +++ b/man/std::error_category::operator==,!=,.3 @@ -0,0 +1,37 @@ +.TH std::error_category::operator==,!=, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::operator==,!=, \- std::error_category::operator==,!=, + +.SH Synopsis + bool operator==( const error_category& rhs ) const noexcept; \fB(1)\fP \fI(since C++11)\fP + bool operator!=( const error_category& rhs ) const noexcept; \fB(2)\fP \fI(since C++11)\fP + \fI(until C++20)\fP + bool operator<( const error_category& rhs ) const noexcept; \fB(3)\fP \fI(since C++11)\fP + \fI(until C++20)\fP + std::strong_ordering operator<=>( const error_category& rhs ) \fB(4)\fP \fI(since C++20)\fP + const noexcept; + + Compares to another error category. + + 1) Checks whether *this and rhs refer to the same object. + 2) Checks whether *this and rhs do not refer to the same object. + 3) Orders *this and rhs by the order of this and &rhs. Equivalent to std::less()(this, &rhs). + 4) Orders *this and rhs by the order of this and &rhs. Equivalent to + std::compare_three_way()(this, &rhs). + + The <, <=, >, >=, and != operators are synthesized from operator<=> \fI(since C++20)\fP + and operator== respectively. + +.SH Parameters + + rhs - specifies the error_category to compare + +.SH Return value + + 1) true if *this and rhs refer to the same object, false otherwise. + 2) true if *this and rhs do not refer to the same object, false otherwise. + 3) true if *this is less than rhs as defined by the order of this and &rhs. + 4) std::strong_order::less if *this is less than rhs as defined by the order of this + and &rhs, otherwise std::strong_order::greater if rhs is less than *this in the + order, otherwise std::strong_order::equal. diff --git a/man/std::error_category::operator==,!=,<.3 b/man/std::error_category::operator==,!=,<.3 deleted file mode 100644 index bb1b8deb5..000000000 --- a/man/std::error_category::operator==,!=,<.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH std::error_category::operator==,!=,< 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bool operator==( const error_category& rhs ) const; \fB(1)\fP \fI(since C++11)\fP - bool operator!=( const error_category& rhs ) const; \fB(2)\fP \fI(since C++11)\fP - bool operator<( const error_category& rhs ) const; \fB(3)\fP \fI(since C++11)\fP - - Compares to another error category. - - 1) Checks whether *this and rhs refer to the same object. - 2) Checks whether *this and rhs do not refer to the same object. - 3) Orders *this and rhs by the order of this and &rhs. Equivalent to std::less()(this, &rhs). - -.SH Parameters - - code - specifies the error code to compare - condition - specifies the error condition to compare - -.SH Return value - - 1) true if *this and rhs refer to the same object, false otherwise. - 2) true if *this and rhs do not refer to the same object, false otherwise. - 3) true if *this is less than rhs as defined by the order of this and &rhs. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_category::~error_category.3 b/man/std::error_category::~error_category.3 index 7b65d8915..939eab06d 100644 --- a/man/std::error_category::~error_category.3 +++ b/man/std::error_category::~error_category.3 @@ -1,4 +1,7 @@ -.TH std::error_category::~error_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_category::~error_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_category::~error_category \- std::error_category::~error_category + .SH Synopsis virtual ~error_category(); \fI(since C++11)\fP diff --git a/man/std::error_code.3 b/man/std::error_code.3 index b9a57327a..6748708d1 100644 --- a/man/std::error_code.3 +++ b/man/std::error_code.3 @@ -1,55 +1,64 @@ -.TH std::error_code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code \- std::error_code + .SH Synopsis Defined in header class error_code; \fI(since C++11)\fP - std::error_code is a platform-dependent error code. Each std::error_code object - holds a pair of error code originating from the operating system, or some low-level - interface and a pointer to an object of type std::error_category, which corresponds - to the said interface. The error code values may be not unique across different - error categories. + std::error_code represents a platform-dependent error code value. Each + std::error_code object holds an error code value originating from the operating + system or some low-level interface and a pointer to an object of type + std::error_category, which corresponds to the said interface. The error code values + are not required to be unique across different error categories. .SH Member functions constructor constructs an error code - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns another error code - \fI(public member function)\fP + \fI(public member function)\fP assign assigns another error code - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers - clear sets the error_code to value 0 in generic_category - \fI(public member function)\fP + clear sets the error_code to value 0 in system_category + \fI(public member function)\fP .SH Observers value obtains the value of the error_code - \fI(public member function)\fP + \fI(public member function)\fP category obtains the error_category for this error_code - \fI(public member function)\fP + \fI(public member function)\fP default_error_condition obtains the error_condition for this error_code - \fI(public member function)\fP + \fI(public member function)\fP message obtains the explanatory string for this error_code - \fI(public member function)\fP + \fI(public member function)\fP operator bool checks if the value is non-zero - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - operator== compares two error_codes - operator!= \fI(function)\fP - operator< - operator<< outputs the value and the message to an output stream - \fI(function)\fP + operator== + operator!= + operator< compares two error_codes + operator<=> \fI(function)\fP + (removed in C++20) + (removed in C++20) + (C++20) + operator<< outputs the value and the category name to an output stream + \fI(function)\fP .SH Helper classes is_error_code_enum identifies a class as an error_code enumeration - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP std::hash hash support for std::error_code - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP .SH See also - error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP - error_category base class for error categories - \fI(C++11)\fP \fI(class)\fP + error_condition holds a portable error code + \fI(C++11)\fP \fI(class)\fP + error_category base class for error categories + \fI(C++11)\fP \fI(class)\fP + make_error_code(std::errc) creates error code value for errc enum e + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::error_code::assign.3 b/man/std::error_code::assign.3 index 310006f72..abed6a38e 100644 --- a/man/std::error_code::assign.3 +++ b/man/std::error_code::assign.3 @@ -1,25 +1,22 @@ -.TH std::error_code::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::assign \- std::error_code::assign + .SH Synopsis - void assign( int ec, const error_category& ecat ); \fI(since C++11)\fP + void assign( int val, const error_category& cat ) noexcept; \fI(since C++11)\fP - Replaces the contents with error code ec and corresponding category ecat. + Replaces the contents with error code value val and corresponding category cat. .SH Parameters - ec - platform-dependent error code enum to assign - ecat - error category corresponding to ec + val - platform-dependent error code value to assign + cat - error category corresponding to val .SH Return value \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also operator= assigns another error code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::error_code::category.3 b/man/std::error_code::category.3 index ff8376e70..bded8f1aa 100644 --- a/man/std::error_code::category.3 +++ b/man/std::error_code::category.3 @@ -1,8 +1,11 @@ -.TH std::error_code::category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::category \- std::error_code::category + .SH Synopsis - const std::error_category& category() const; \fI(since C++11)\fP + const std::error_category& category() const noexcept; \fI(since C++11)\fP - Returns the error category of the error value. + Returns the error category of the error code. .SH Parameters @@ -10,15 +13,9 @@ .SH Return value - The error category of the error value. - -.SH Exceptions - - noexcept specification: - noexcept - + The error category of the error code. .SH See also value obtains the value of the error_code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::error_code::clear.3 b/man/std::error_code::clear.3 index c98f8e72f..04f25c326 100644 --- a/man/std::error_code::clear.3 +++ b/man/std::error_code::clear.3 @@ -1,6 +1,9 @@ -.TH std::error_code::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::clear \- std::error_code::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP Replaces the error code and error category with default values. @@ -13,9 +16,3 @@ .SH Return value \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_code::default_error_condition.3 b/man/std::error_code::default_error_condition.3 index 09e20c74d..cd17fdc75 100644 --- a/man/std::error_code::default_error_condition.3 +++ b/man/std::error_code::default_error_condition.3 @@ -1,6 +1,9 @@ -.TH std::error_code::default_error_condition 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::default_error_condition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::default_error_condition \- std::error_code::default_error_condition + .SH Synopsis - std::error_condition default_error_condition() const; \fI(since C++11)\fP + std::error_condition default_error_condition() const noexcept; \fI(since C++11)\fP Returns the default error condition for the current error value. @@ -13,9 +16,3 @@ .SH Return value The default error condition for the current error value. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_code::error_code.3 b/man/std::error_code::error_code.3 index 1e0ad64d3..88541ec0e 100644 --- a/man/std::error_code::error_code.3 +++ b/man/std::error_code::error_code.3 @@ -1,9 +1,16 @@ -.TH std::error_code::error_code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::error_code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::error_code \- std::error_code::error_code + .SH Synopsis - error_code(); \fB(1)\fP \fI(since C++11)\fP - error_code( int ec, const error_category& ecat ); \fB(2)\fP \fI(since C++11)\fP - template< class ErrorCodeEnum > \fB(3)\fP \fI(since C++11)\fP - error_code( ErrorCodeEnum e ); + error_code() noexcept; \fB(1)\fP \fI(since C++11)\fP + error_code( int ec, const error_category& ecat ) noexcept; \fB(2)\fP \fI(since C++11)\fP + template< class ErrorCodeEnum > \fB(3)\fP \fI(since C++11)\fP + error_code( ErrorCodeEnum e ) noexcept; + error_code( const error_code& other ) = default; \fB(4)\fP \fI(since C++11)\fP + (implicitly declared) + error_code( error_code&& other ) = default; \fB(5)\fP \fI(since C++11)\fP + (implicitly declared) Constructs new error code. @@ -11,18 +18,34 @@ std::system_category()). 2) Constructs error code with ec as the platform-dependent error code and ecat as the corresponding error category. - 3) Constructs error code from an error code enum e. Equivalent to *this = - std::make_error_code(e). The overload participates in overload resolutions only if - std::is_error_code_enum::value == true. + 3) Constructs error code from an error code enum e. Equivalent to + make_error_code(e), where make_error_code is only found by argument-dependent + lookup. This overload participates in overload resolution only if + std::is_error_code_enum::value is true. + 4,5) Implicitly defined copy constructor and move constructor. Initializes the error + code with the contents of the other. .SH Parameters - ec - platform dependent error code to construct with - ecat - error category corresponding to ec - e - error code enum to construct with + other - another error code to initialize with + ec - platform dependent error code to construct with + ecat - error category corresponding to ec + e - error code enum to construct with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3629 C++11 only std::make_error_code overloads were ADL-found overloads are + used used -.SH Exceptions +.SH See also - noexcept specification: - noexcept - + make_error_code(std::errc) creates error code value for errc enum e + \fI(C++11)\fP \fI(function)\fP + make_error_code(std::io_errc) constructs an iostream error code + \fI(C++11)\fP \fI(function)\fP + make_error_code(std::future_errc) constructs a future error code + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::error_code::message.3 b/man/std::error_code::message.3 index 74d947bdf..25e2e7718 100644 --- a/man/std::error_code::message.3 +++ b/man/std::error_code::message.3 @@ -1,8 +1,11 @@ -.TH std::error_code::message 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::message 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::message \- std::error_code::message + .SH Synopsis std::string message() const; \fI(since C++11)\fP - Returns the message corresponding to the current error value and category. + Returns the message corresponding to the current error code value and category. Equivalent to category().message(value()). @@ -12,8 +15,8 @@ .SH Return value - The error message corresponding to the current error value and category. + The error message corresponding to the current error code value and category. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. diff --git a/man/std::error_code::operator=.3 b/man/std::error_code::operator=.3 index 57c434e34..fe073442c 100644 --- a/man/std::error_code::operator=.3 +++ b/man/std::error_code::operator=.3 @@ -1,33 +1,45 @@ -.TH std::error_code::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class ErrorCodeEnum > \fI(since C++11)\fP - error_code& operator=( ErrorCodeEnum e ); +.TH std::error_code::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::operator= \- std::error_code::operator= - Replaces the error code and corresponding category with those representing error +.SH Synopsis + template< class ErrorCodeEnum > \fB(1)\fP \fI(since C++11)\fP + error_code& operator=( ErrorCodeEnum e ) noexcept; + error_code& operator=( const error_code& other ) = \fB(2)\fP \fI(since C++11)\fP + default; (implicitly declared) + error_code& operator=( error_code&& other ) = default; \fB(3)\fP \fI(since C++11)\fP + (implicitly declared) + + 1) Replaces the error code and corresponding category with those representing error code enum e. - Equivalent to *this = std::make_error_code(e). The overload participates in overload - resolutions only if std::is_error_code_enum::value == true. + Equivalent to *this = make_error_code(e), where make_error_code is only found by + argument-dependent lookup. + + This overload participates in overload resolution only if + std::is_error_code_enum::value is true. + 2,3) Implicitly defined copy-assignment operator and move-assignment operator assign + the contents of other to *this. .SH Parameters - e - error code enum to construct + e - error code enum to construct + other - another error code to assign with .SH Return value *this -.SH Exceptions - - noexcept specification: - noexcept - + Defect reports -.SH Notes + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Copy-assignment operator is defined implicitly. + DR Applied to Behavior as published Correct behavior + LWG 3629 C++11 only std::make_error_code overloads were ADL-found overloads are + used used .SH See also assign assigns another error code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::error_code::operatorbool.3 b/man/std::error_code::operatorbool.3 index 0238e1489..8b1b308d4 100644 --- a/man/std::error_code::operatorbool.3 +++ b/man/std::error_code::operatorbool.3 @@ -1,8 +1,11 @@ -.TH std::error_code::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::operatorbool \- std::error_code::operatorbool + .SH Synopsis - explicit operator bool() const; \fI(since C++11)\fP + explicit operator bool() const noexcept; \fI(since C++11)\fP - Checks if the error value is valid, i.e. non-zero. + Checks if the error code value is valid, i.e. non-zero. .SH Parameters @@ -12,8 +15,8 @@ false if value() == 0, true otherwise. -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + Although this operator is often used as a convenient shorthand to check if any error + was returned, as in if (ec) { /* handle error */ }, such use is not robust: some + error codes, for example, HTTP status code 200, may indicate success as well. diff --git a/man/std::error_code::value.3 b/man/std::error_code::value.3 index 4c701d751..00ede3445 100644 --- a/man/std::error_code::value.3 +++ b/man/std::error_code::value.3 @@ -1,8 +1,11 @@ -.TH std::error_code::value 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_code::value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_code::value \- std::error_code::value + .SH Synopsis - int value() const; \fI(since C++11)\fP + int value() const noexcept; \fI(since C++11)\fP - Returns the platform dependent error value. + Returns the platform dependent error code value. .SH Parameters @@ -10,15 +13,9 @@ .SH Return value - The platform-dependent error value. - -.SH Exceptions - - noexcept specification: - noexcept - + The platform-dependent error code value. .SH See also category obtains the error_category for this error_code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::error_condition.3 b/man/std::error_condition.3 index e49df0c04..77653ed0b 100644 --- a/man/std::error_condition.3 +++ b/man/std::error_condition.3 @@ -1,11 +1,15 @@ -.TH std::error_condition 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition \- std::error_condition + .SH Synopsis Defined in header class error_condition; \fI(since C++11)\fP - std::error_condition is a platform-independent error code. Like std::error_code, it - is uniquely identified by an integer value and a std::error_category, but unlike - std::error_code, the value is not platform-dependent. + std::error_condition holds a platform-independent value identifying an error + condition. Like std::error_code, it is uniquely identified by an integer value and a + std::error_category, but unlike std::error_code, the value is not + platform-dependent. A typical implementation holds one integer data member (the value) and a pointer to an std::error_category. @@ -13,36 +17,80 @@ .SH Member functions constructor constructs an error_condition - \fI(public member function)\fP + \fI(public member function)\fP operator= replaces the contents - \fI(public member function)\fP + \fI(public member function)\fP assign replaces the contents - \fI(public member function)\fP + \fI(public member function)\fP clear sets the error_condition to value 0 in generic_category - \fI(public member function)\fP + \fI(public member function)\fP value obtains the value of the error_condition - \fI(public member function)\fP + \fI(public member function)\fP category obtains the error_category for this error_condition - \fI(public member function)\fP + \fI(public member function)\fP message obtains the explanatory string - \fI(public member function)\fP + \fI(public member function)\fP operator bool checks if the value is non-zero - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - operator== compares error_conditions and error_codes - operator!= \fI(function)\fP - operator< + operator== + operator!= + operator< compares error_conditions and error_codes + operator<=> \fI(function)\fP + (removed in C++20) + (removed in C++20) + (C++20) .SH Helper classes - is_error_condition_enum identifies an enumeration as an std::error_condition - \fI(C++11)\fP \fI(class template)\fP + is_error_condition_enum identifies an enumeration as an std::error_condition + \fI(C++11)\fP \fI(class template)\fP + std::hash hash support for std::error_condition + \fI(C++17)\fP \fI(class template specialization)\fP + +.SH Notes + + The comparison between a std::error_code and a std::error_condition is defined by + their error categories. Notably, an error condition of std::generic_category may + compare equal to an error code of a specific category (e.g. std::system_category), + if they represent the same kind of error. + + A std::errc value can be compared to an error code via implicit conversion to + std::error_condition. + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::error_code ec{ERROR_FILE_EXISTS, std::system_category()}; + std::error_condition econd{EEXIST, std::generic_category()}; + + std::cout.setf(std::ios::boolalpha); + std::cout << (ec == econd) << '\\n'; // typically true + std::cout << (ec == std::errc::file_exists) << '\\n'; // ditto + std::cout << (ec == make_error_code(std::errc::file_exists)) << '\\n'; // false: + // different category + } + +.SH Possible output: + + true + true + false .SH See also - error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP - error_category base class for error categories - \fI(C++11)\fP \fI(class)\fP + error_code holds a platform-dependent error code + \fI(C++11)\fP \fI(class)\fP + error_category base class for error categories + \fI(C++11)\fP \fI(class)\fP + make_error_condition(std::errc) creates an error condition for an errc value e + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::error_condition::assign.3 b/man/std::error_condition::assign.3 index 622063b59..24ed8f270 100644 --- a/man/std::error_condition::assign.3 +++ b/man/std::error_condition::assign.3 @@ -1,21 +1,18 @@ -.TH std::error_condition::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::assign \- std::error_condition::assign + .SH Synopsis - void assign( int val, const error_category& cat ); \fI(since C++11)\fP + void assign( int val, const error_category& cat ) noexcept; \fI(since C++11)\fP - Assigns contents to an error condition. Sets the error code to val and error + Assigns contents to an error condition. Sets the error value to val and error category to cat. .SH Parameters - val - error code + val - error value cat - error category .SH Return value \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_condition::category.3 b/man/std::error_condition::category.3 index 1ab222318..806b00f9e 100644 --- a/man/std::error_condition::category.3 +++ b/man/std::error_condition::category.3 @@ -1,6 +1,9 @@ -.TH std::error_condition::category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::category \- std::error_condition::category + .SH Synopsis - const error_category& category() const; \fI(since C++11)\fP + const error_category& category() const noexcept; \fI(since C++11)\fP Returns the stored error category. @@ -12,8 +15,7 @@ The stored error category. -.SH Exceptions +.SH See also - noexcept specification: - noexcept - + error_category base class for error categories + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::error_condition::clear.3 b/man/std::error_condition::clear.3 index 1d967e622..b1813ab6a 100644 --- a/man/std::error_condition::clear.3 +++ b/man/std::error_condition::clear.3 @@ -1,8 +1,11 @@ -.TH std::error_condition::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::clear \- std::error_condition::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP - Clears the state of the error condition. Sets the error code to 0 and error + Clears the state of the error condition. Sets the error value to 0 and error category to std::generic_category. .SH Parameters @@ -12,9 +15,3 @@ .SH Return value \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_condition::error_condition.3 b/man/std::error_condition::error_condition.3 index 7490d8240..a228bae53 100644 --- a/man/std::error_condition::error_condition.3 +++ b/man/std::error_condition::error_condition.3 @@ -1,31 +1,52 @@ -.TH std::error_condition::error_condition 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::error_condition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::error_condition \- std::error_condition::error_condition + .SH Synopsis - error_condition(); \fB(1)\fP \fI(since C++11)\fP - error_condition( const error_condition& other ); \fB(2)\fP \fI(since C++11)\fP - (implicitly declared) - error_condition( int val, const error_category& cat ); \fB(3)\fP \fI(since C++11)\fP - template< class ErrorConditionEnum > \fB(4)\fP \fI(since C++11)\fP - error_condition( ErrorConditionEnum e ); + error_condition() noexcept; \fB(1)\fP \fI(since C++11)\fP + error_condition( int val, const error_category& cat ) \fB(2)\fP \fI(since C++11)\fP + noexcept; + template< class ErrorConditionEnum > \fB(3)\fP \fI(since C++11)\fP + error_condition( ErrorConditionEnum e ) noexcept; + error_condition( const error_condition& other ) = default; \fB(4)\fP \fI(since C++11)\fP + (implicitly declared) + error_condition( error_condition&& other ) = default; \fB(5)\fP \fI(since C++11)\fP + (implicitly declared) Constructs new error condition. 1) Default constructor. Initializes the error condition with generic category and - error code 0. - 2) Copy constructor. Initializes the error condition with the contents of other. - 3) Initializes the error condition with error code val and error category cat. - 4) Initializes the error condition with enum e. Effectively calls - make_error_condition(). Does not participate in the overload resolution unless - is_error_condition_enum::value is true. + error value 0. + 2) Initializes the error condition with error value val and error category cat. + 3) Initializes the error condition with enum e. Effectively calls + make_error_condition that is only found by argument-dependent lookup for e. This + overload participates in overload resolution only if + std::is_error_condition_enum::value is true. + 4,5) Implicitly defined copy constructor and move constructor. Initializes the error + condition with the contents of the other. .SH Parameters other - another error condition to initialize with - val - error code + val - error value cat - error category e - error condition enum -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3629 C++11 only std::make_error_condition overloads ADL-found overloads + were used are used + +.SH See also - noexcept specification: - noexcept - + make_error_condition(std::errc) creates an error condition for an errc value + \fI(C++11)\fP e + \fI(function)\fP + make_error_condition(std::io_errc) constructs an iostream error condition + \fI(C++11)\fP \fI(function)\fP + make_error_condition(std::future_errc) constructs a future error_condition + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::error_condition::message.3 b/man/std::error_condition::message.3 index 29d9baa6c..c3efbe0e1 100644 --- a/man/std::error_condition::message.3 +++ b/man/std::error_condition::message.3 @@ -1,8 +1,11 @@ -.TH std::error_condition::message 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::message 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::message \- std::error_condition::message + .SH Synopsis std::string message() const; \fI(since C++11)\fP - Returns an explanatory message for the stored error code and error category. + Returns an explanatory message for the stored error value and error category. Effectively calls category().message(value()). .SH Parameters @@ -11,8 +14,13 @@ .SH Return value - An explanatory message for the stored error code and error category. + An explanatory message for the stored error value and error category. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH See also + + message obtains the explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::error_category)\fP diff --git a/man/std::error_condition::operator=.3 b/man/std::error_condition::operator=.3 index 2320b449c..b9c7c4d74 100644 --- a/man/std::error_condition::operator=.3 +++ b/man/std::error_condition::operator=.3 @@ -1,28 +1,39 @@ -.TH std::error_condition::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::operator= \- std::error_condition::operator= + .SH Synopsis - error_condition& operator=( const error_condition& other \fB(1)\fP \fI(since C++11)\fP - ); (implicitly declared) - template< class ErrorConditionEnum > \fB(2)\fP \fI(since C++11)\fP - error_condition& operator=( ErrorConditionEnum e ); + template< class ErrorConditionEnum > + error_condition& operator=( ErrorConditionEnum e ) \fB(1)\fP \fI(since C++11)\fP + noexcept; + error_condition& operator=( const error_condition& other ) \fB(2)\fP \fI(since C++11)\fP + = default; (implicitly declared) + error_condition& operator=( error_condition&& other ) = \fB(3)\fP \fI(since C++11)\fP + default; (implicitly declared) Assigns contents to an error condition. - 1) Copy assignment operator. Assigns the contents of other. - 2) Assigns error condition for enum e. Effectively calls make_error_condition(). - Does not participate in the overload resolution unless - is_error_condition_enum::value is true. + 1) Assigns error condition for enum e. Effectively calls make_error_condition that + is only found by argument-dependent lookup for e and then replaces *this with the + result. This overload participates in overload resolution only if + std::is_error_condition_enum::value is true. + 2,3) Implicitly defined copy-assignment operator and move-assignment operator assign + the contents of other to *this. .SH Parameters - other - another error condition to initialize with e - error condition enum + other - another error condition to assign with .SH Return value *this. -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + LWG 3629 C++11 only std::make_error_condition overloads ADL-found overloads + were used are used diff --git a/man/std::error_condition::operator==,!=,<.3 b/man/std::error_condition::operator==,!=,<.3 deleted file mode 100644 index c99836ff2..000000000 --- a/man/std::error_condition::operator==,!=,<.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH std::error_condition::operator==,!=,< 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - bool operator==( const error_condition& lhs, const \fB(1)\fP \fI(since C++11)\fP - error_condition& rhs ); - bool operator==( const error_code& lhs, const error_condition& rhs \fB(2)\fP \fI(since C++11)\fP - ); - bool operator==( const error_condition& lhs, const error_code& rhs \fB(2)\fP \fI(since C++11)\fP - ); - bool operator!=( const error_condition& lhs, const \fB(3)\fP \fI(since C++11)\fP - error_condition& rhs ); - bool operator!=( const error_code& lhs, const error_condition& rhs \fB(4)\fP \fI(since C++11)\fP - ); - bool operator!=( const error_condition& lhs, const error_code& rhs \fB(4)\fP \fI(since C++11)\fP - ); - bool operator<( const error_condition& lhs, const error_condition& \fB(5)\fP \fI(since C++11)\fP - rhs ); - - Compares two error conditions. - - 1-2) Checks whether lhs and rhs are equal. - 3-4) Checks whether lhs and rhs are not equal. - 5) Checks whether lhs is less than rhs. - -.SH Parameters - - lhs, rhs - error conditions to compare - -.SH Return value - - 1) true if the error category and error value compare equal. - 2) true if lhs.category().equivalent(rhs.value(), lhs) or - rhs.category().equivalent(lhs.value(), rhs) is true. - 3) true if the error category or error value compare are not equal. - 4) true if lhs.category().equivalent(rhs.value(), lhs) and - rhs.category().equivalent(lhs.value(), rhs) is false. - 5) true if lhs.category() < rhs.category(). Otherwise, true if lhs.category() == - rhs.category() && lhs.value() < rhs.value(). Otherwise, false. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_condition::operatorbool.3 b/man/std::error_condition::operatorbool.3 index 9c9934d0b..92f190a50 100644 --- a/man/std::error_condition::operatorbool.3 +++ b/man/std::error_condition::operatorbool.3 @@ -1,8 +1,11 @@ -.TH std::error_condition::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::operatorbool \- std::error_condition::operatorbool + .SH Synopsis - explicit operator bool() const; \fI(since C++11)\fP + explicit operator bool() const noexcept; \fI(since C++11)\fP - Checks whether the stored error code is not zero. + Checks whether the stored error value is not zero. .SH Parameters @@ -11,9 +14,3 @@ .SH Return value true if value != 0, false otherwise. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::error_condition::value.3 b/man/std::error_condition::value.3 index 9f61e7f20..a6882f8de 100644 --- a/man/std::error_condition::value.3 +++ b/man/std::error_condition::value.3 @@ -1,8 +1,11 @@ -.TH std::error_condition::value 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::error_condition::value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::error_condition::value \- std::error_condition::value + .SH Synopsis - int value() const; \fI(since C++11)\fP + int value() const noexcept; \fI(since C++11)\fP - Returns the stored error code. + Returns the stored error value. .SH Parameters @@ -10,10 +13,4 @@ .SH Return value - The stored error code. - -.SH Exceptions - - noexcept specification: - noexcept - + The stored error value. diff --git a/man/std::exception.3 b/man/std::exception.3 index a1308e8ce..f80725e97 100644 --- a/man/std::exception.3 +++ b/man/std::exception.3 @@ -1,11 +1,49 @@ -.TH std::exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exception \- std::exception + .SH Synopsis Defined in header class exception; Provides consistent interface to handle errors through the throw expression. - All exceptions generated by the standard library inherit from std::exception + All exceptions generated by the standard library inherit from std::exception. + +.SH Member functions + + constructor constructs the exception object + \fI(public member function)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= copies exception object + \fI(public member function)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function)\fP + + Standard exception requirements + + Each standard library class T that derives from std::exception has the following + publicly accessible member functions, each of them + do not exit with an exception + \fI(until C++11)\fP + having a non-throwing exception specification + \fI(since C++11)\fP: + + * default constructor (unless other constructors are provided) + * copy constructor + * copy assignment operator + + The copy constructor and the copy assignment operator meet the following + postcondition: + + * If two objects lhs and rhs both have dynamic type T and lhs is a copy of rhs, + then std::strcmp(lhs.what(), rhs.what()) is equal to 0. + + The what() member function of each such T satisfies the constraints specified for + std::exception::what(). + + Standard exceptions * logic_error @@ -13,37 +51,41 @@ * domain_error * length_error * out_of_range - * future_error\fI(C++11)\fP - + * future_error \fI(since C++11)\fP * runtime_error * range_error * overflow_error * underflow_error - * regex_error\fI(C++11)\fP - * system_error\fI(C++11)\fP - - * ios_base::failure\fI(since C++11)\fP + * regex_error \fI(since C++11)\fP + * system_error \fI(since C++11)\fP + * ios_base::failure \fI(since C++11)\fP + * filesystem::filesystem_error \fI(since C++17)\fP + * tx_exception (TM TS) + * nonexistent_local_time \fI(since C++20)\fP + * ambiguous_local_time \fI(since C++20)\fP + * format_error \fI(since C++20)\fP * bad_typeid * bad_cast - * bad_weak_ptr\fI(C++11)\fP - * bad_function_call\fI(C++11)\fP - * bad_alloc - * bad_array_length\fI(C++14)\fP - * bad_array_new_length\fI(C++11)\fP + * bad_any_cast \fI(since C++17)\fP + * bad_optional_access \fI(since C++17)\fP + * bad_expected_access (since C++23) + * bad_weak_ptr \fI(since C++11)\fP + * bad_function_call \fI(since C++11)\fP + * bad_alloc + * bad_array_new_length \fI(since C++11)\fP * bad_exception - * ios_base::failure\fI(until C++11)\fP + * ios_base::failure \fI(until C++11)\fP + * bad_variant_access \fI(since C++17)\fP -.SH Member functions + Defect reports - constructor constructs the exception object - \fI(public member function)\fP - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function)\fP - operator= copies exception object - \fI(public member function)\fP - what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 471 C++98 there was no requirement on standard library added + classes derived from std::exception diff --git a/man/std::exception::exception.3 b/man/std::exception::exception.3 index 41c7f4ebe..899a75929 100644 --- a/man/std::exception::exception.3 +++ b/man/std::exception::exception.3 @@ -1,20 +1,39 @@ -.TH std::exception::exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exception::exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exception::exception \- std::exception::exception + .SH Synopsis - exception(); \fB(1)\fP - exception( const exception& other ); \fB(2)\fP + exception() throw(); \fI(until C++11)\fP + exception() noexcept; \fB(1)\fP \fI(since C++11)\fP + exception( const exception& other ) throw(); \fB(2)\fP \fI(until C++11)\fP + exception( const exception& other ) noexcept; \fI(since C++11)\fP Constructs new exception object. - 1) Default constructor. what() returns empty string. - 2) Copy constructor. Initializes the contents with those of other + 1) Default constructor. what() returns an implementation-defined string. + 2) Copy constructor. Initializes the contents with those of other. If *this and + other both have dynamic type std::exception then std::strcmp(what(), other.what()) + == 0. .SH Parameters other - another exception to assign the contents of -.SH Exceptions +.SH Notes + + Because copying std::exception is not permitted to throw exceptions, when derived + classes (such as std::runtime_error) have to manage a user-defined diagnostic + message, it is typically implemented as a copy-on-write string. + + The Microsoft implementation includes non-standard constructors taking strings thus + allowing instances to be thrown directly with a meaningful error message. The + nearest standard equivalents are std::runtime_error or std::logic_error. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + DR Applied to Behavior as published Correct behavior + LWG 471 C++98 there is no requirement on what() of the added + exception copy diff --git a/man/std::exception::operator=.3 b/man/std::exception::operator=.3 index 2b177597d..26fef99c5 100644 --- a/man/std::exception::operator=.3 +++ b/man/std::exception::operator=.3 @@ -1,16 +1,27 @@ -.TH std::exception::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exception::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exception::operator= \- std::exception::operator= + .SH Synopsis - exception& operator=( const exception& other ); + exception& operator=( const exception& other ) throw(); \fI(until C++11)\fP + exception& operator=( const exception& other ) noexcept; \fI(since C++11)\fP + + Copy assignment operator. Assigns the contents of other. - Copy assignment operator. Assigns the contents of other + If *this and other both have dynamic type std::exception then std::strcmp(what(), + other.what()) == 0 after assignment. .SH Parameters other - another exception to assign the contents of -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + DR Applied to Behavior as published Correct behavior + required to be the same as + LWG 471 C++98 the effects of calling what() after the original + assignment are implementation-defined what() if the dynamic types + are the same diff --git a/man/std::exception::what.3 b/man/std::exception::what.3 index 1c7fdcd31..d6d72d5ef 100644 --- a/man/std::exception::what.3 +++ b/man/std::exception::what.3 @@ -1,6 +1,10 @@ -.TH std::exception::what 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exception::what 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exception::what \- std::exception::what + .SH Synopsis - virtual const char* what() const; + virtual const char* what() const throw(); \fI(until C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP Returns the explanatory string. @@ -15,9 +19,11 @@ is destroyed, or until a non-const member function on the exception object is called. -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + DR Applied to Behavior as published Correct behavior + LWG 108 C++98 it was unspecified when the returned pointer specified + becomes invalid diff --git a/man/std::exception::~exception.3 b/man/std::exception::~exception.3 index fdbbf7fe4..cda83e451 100644 --- a/man/std::exception::~exception.3 +++ b/man/std::exception::~exception.3 @@ -1,4 +1,7 @@ -.TH std::exception::~exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exception::~exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exception::~exception \- std::exception::~exception + .SH Synopsis virtual ~exception(); diff --git a/man/std::exception_ptr.3 b/man/std::exception_ptr.3 index 9315dc242..9996fe269 100644 --- a/man/std::exception_ptr.3 +++ b/man/std::exception_ptr.3 @@ -1,4 +1,7 @@ -.TH std::exception_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exception_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exception_ptr \- std::exception_ptr + .SH Synopsis Defined in header typedef /*unspecified*/ exception_ptr; \fI(since C++11)\fP @@ -8,61 +11,73 @@ std::exception_ptr may be passed to another function, possibly on another thread, where the exception may be rethrown and handled with a catch clause. - Default-constructed std::exception_ptr is a null pointer, it does not point to an + A default-constructed std::exception_ptr is a null pointer; it does not point to an exception object. Two instances of std::exception_ptr compare equal only if they are both null or both point at the same exception object. std::exception_ptr is not implicitly convertible to any arithmetic, enumeration, or - pointer type. It is convertible to bool. + pointer type. It is contextually convertible to bool, and will evaluate to false if + it is null, true otherwise. The exception object referenced by an std::exception_ptr remains valid as long as there remains at least one std::exception_ptr that is referencing it: - std::exception_ptr is a shared-ownership smart pointer. + std::exception_ptr is a shared-ownership smart pointer (note: this is in addition to + the usual exception object lifetime rules). + + std::exception_ptr meets the requirements of NullablePointer. .SH Example - - + + // Run this code - #include - #include #include + #include #include - + #include + void handle_eptr(std::exception_ptr eptr) // passing by value is ok { - try { - if (eptr != std::exception_ptr()) { + try + { + if (eptr) std::rethrow_exception(eptr); - } - } catch(const std::exception& e) { - std::cout << "Caught exception \\"" << e.what() << "\\"\\n"; + } + catch(const std::exception& e) + { + std::cout << "Caught exception: '" << e.what() << "'\\n"; } } - + int main() { std::exception_ptr eptr; - try { - std::string().at(1); // this generates an std::out_of_range - } catch(...) { + + try + { + std::string().at(1); // this generates a std::out_of_range + } + catch(...) + { eptr = std::current_exception(); // capture } + handle_eptr(eptr); + } // destructor for std::out_of_range called here, when the eptr is destructed -.SH Output: +.SH Possible output: - Caught exception "basic_string::at" + Caught exception: 'basic_string::at: __n (which is 1) >= this->size() (which is 0)' .SH See also make_exception_ptr creates an std::exception_ptr from an exception object - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP current_exception captures the current exception in a std::exception_ptr - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP rethrow_exception throws the exception from an std::exception_ptr - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::exchange.3 b/man/std::exchange.3 index c76057379..625c73879 100644 --- a/man/std::exchange.3 +++ b/man/std::exchange.3 @@ -1,97 +1,139 @@ -.TH std::exchange 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exchange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exchange \- std::exchange + .SH Synopsis Defined in header - template< class T, class U = T > \fI(since C++14)\fP - T exchange( T& obj, U&& new_value ); + template< class T, class U = T > \fI(since C++14)\fP + T exchange( T& obj, U&& new_value ); \fI(until C++20)\fP + template< class T, class U = T > \fI(since C++20)\fP + constexpr T exchange( T& obj, U&& new_value ); (until C++23) + template< class T, class U = T > + constexpr T exchange( T& obj, U&& new_value ) noexcept(/* see below (since C++23) + */); Replaces the value of obj with new_value and returns the old value of obj. .SH Parameters - obj - object whose value to replace - new_value - the value to assign to obj + obj - object whose value to replace + new_value - the value to assign to obj .SH Type requirements - - T must meet the requirements of MoveAssignable. Also, it must be possible to - move-assign objects of type U to objects of type T + T must meet the requirements of MoveConstructible. Also, it must be possible to + move-assign objects of type U to objects of type T. .SH Return value - The old value of obj + The old value of obj. .SH Exceptions - \fI(none)\fP + \fI(none)\fP (until C++23) + noexcept specification: + noexcept( + + std::is_nothrow_move_constructible_v && (since C++23) + std::is_nothrow_assignable_v + + ) .SH Possible implementation template + constexpr // Since C++20 T exchange(T& obj, U&& new_value) + noexcept( // Since C++23 + std::is_nothrow_move_constructible::value && + std::is_nothrow_assignable::value + ) { T old_value = std::move(obj); obj = std::forward(new_value); return old_value; } +.SH Notes + + The std::exchange can be used when implementing move assignment operators and move + constructors: + + struct S + { + int n; + + S(S&& other) noexcept : n{std::exchange(other.n, 0)} {} + + S& operator=(S&& other) noexcept + { + n = std::exchange(other.n, 0); // Move n, while leaving zero in other.n + // (note: in self-move-assignment, n is unchanged) + return *this; + } + }; + + Feature-test macro Value Std Feature + __cpp_lib_exchange_function 201304L \fI(C++14)\fP std::exchange + .SH Example - + // Run this code #include + #include #include #include - #include - + class stream { - public: - - using flags_type = int; - - public: - - flags_type flags() const - { return flags_; } - - ///Replaces flags_ by newf, and returns the old value. - flags_type flags(flags_type newf) - { return std::exchange(flags_, newf); } - - private: - + public: + using flags_type = int; + + public: + flags_type flags() const { return flags_; } + + // Replaces flags_ by newf, and returns the old value. + flags_type flags(flags_type newf) { return std::exchange(flags_, newf); } + + private: flags_type flags_ = 0; }; - + void f() { std::cout << "f()"; } - + int main() { - stream s; - - std::cout << s.flags() << '\\n'; - std::cout << s.flags(12) << '\\n'; - std::cout << s.flags() << "\\n\\n"; - - std::vector v; - - //Since the second template parameter has a default value, it is possible - //to use a braced-init-list as second argument. The expression below - //is equivalent to std::exchange(v, std::vector{1,2,3,4}); - - std::exchange(v, {1,2,3,4}); - - std::copy(begin(v),end(v), std::ostream_iterator(std::cout,", ")); - - std::cout << "\\n\\n"; - - void (*fun)(); - - //the default value of template parameter also makes possible to use a - //normal function as second argument. The expression below is equivalent to - //std::exchange(fun, std::static_cast(f)) - std::exchange(fun,f); - fun(); + stream s; + + std::cout << s.flags() << '\\n'; + std::cout << s.flags(12) << '\\n'; + std::cout << s.flags() << "\\n\\n"; + + std::vector v; + + // Since the second template parameter has a default value, it is possible + // to use a braced-init-list as second argument. The expression below + // is equivalent to std::exchange(v, std::vector{1, 2, 3, 4}); + + std::exchange(v, {1, 2, 3, 4}); + + std::copy(begin(v), end(v), std::ostream_iterator(std::cout, ", ")); + + std::cout << "\\n\\n"; + + void (*fun)(); + + // The default value of template parameter also makes possible to use a + // normal function as second argument. The expression below is equivalent to + // std::exchange(fun, static_cast(f)) + std::exchange(fun, f); + fun(); + + std::cout << "\\n\\nFibonacci sequence: "; + for (int a{0}, b{1}; a < 100; a = std::exchange(b, a + b)) + std::cout << a << ", "; + std::cout << "...\\n"; } .SH Output: @@ -99,16 +141,21 @@ 0 0 12 - + 1, 2, 3, 4, - + f() + Fibonacci sequence: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, ... + .SH See also swap swaps the values of two objects - \fI(function template)\fP + \fI(function template)\fP atomic_exchange atomically replaces the value of the atomic object with atomic_exchange_explicit non-atomic argument and returns the old value of the atomic - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::exclusive_scan.3 b/man/std::exclusive_scan.3 new file mode 100644 index 000000000..998ff3835 --- /dev/null +++ b/man/std::exclusive_scan.3 @@ -0,0 +1,175 @@ +.TH std::exclusive_scan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exclusive_scan \- std::exclusive_scan + +.SH Synopsis + Defined in header + template< class InputIt, class OutputIt, class T > + \fI(since C++17)\fP + OutputIt exclusive_scan( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + + OutputIt d_first, T init ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class T > + ForwardIt2 exclusive_scan( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 + last, + + ForwardIt2 d_first, T init ); + template< class InputIt, class OutputIt, + + class T, class BinaryOp > \fI(since C++17)\fP + OutputIt exclusive_scan( InputIt first, InputIt last, \fB(3)\fP (constexpr since C++20) + + OutputIt d_first, T init, + BinaryOp op ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class T, class BinaryOp > + ForwardIt2 exclusive_scan( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 + last, + + ForwardIt2 d_first, T init, + BinaryOp op ); + + 1) Equivalent to exclusive_scan(first, last, d_first, init, std::plus<>(). + 3) Computes the exclusive prefix sum using op. + For each integer i in [0, std::distance(first, last)), performs the following + operations in order: + 1. Creates a sequence which is formed by init followed by the elements of + [first, iter) in order, where iter is the next i + th iterator of first. + 2. Computes the generalized noncommutative sum of the sequence over op. + 3. Assigns the result to *dest, where dest is the next i + th iterator of d_first. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + The generalized noncommutative sum of a sequence of elements over a binary operation + binary_op is defined as follows: + + * If the sequence only has one element, the sum is the value of the element. + * Otherwise, performs the following operations in order: + 1. Selects any two adjacent elements elem1 and elem2 from the sequence. + 2. Calculates binary_op(elem1, elem2) and replaces the two elements in the sequence + with the result. + 3. Repeats steps 1 and 2 until there is only one element in the sequence. + + Given binary_op as the actual binary operation: + + * The result is non-deterministic if the binary_op is not associative (such as + floating-point addition). + * If any of the following values is not convertible to T, the program is + ill-formed: + + * binary_op(init, *first) + * binary_op(init, init) + * binary_op(*first, *first) + * If any of the following conditions is satisfied, the behavior is undefined: + + * T is not MoveConstructible. + * binary_op modifies any element of [first, last). + * binary_op invalidates any iterator or subrange of [first, last]. + +.SH Parameters + + first, last - the range of elements to sum + d_first - the beginning of the destination range; may be equal to first + policy - the execution policy to use. See execution policy for details. + init - the initial value + op - binary FunctionObject that will be applied in to the result of + dereferencing the input iterators, the results of other op, and init +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + +.SH Return value + + Iterator to the element past the last element written. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) \\(\\scriptsize O(N)\\)O(N) applications of std::plus<>(). + 3,4) \\(\\scriptsize O(N)\\)O(N) applications of op. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector data{3, 1, 4, 1, 5, 9, 2, 6}; + + std::cout << "Exclusive sum: "; + std::exclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + 0); + + std::cout << "\\nInclusive sum: "; + std::inclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " ")); + + std::cout << "\\n\\nExclusive product: "; + std::exclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + 1, std::multiplies<>{}); + + std::cout << "\\nInclusive product: "; + std::inclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + std::multiplies<>{}); + } + +.SH Output: + + Exclusive sum: 0 3 4 8 9 14 23 25 + Inclusive sum: 3 4 8 9 14 23 25 31 + + Exclusive product: 1 3 3 12 12 60 540 1080 + Inclusive product: 3 3 12 12 60 540 1080 6480 + +.SH See also + + computes the differences between adjacent elements in a + adjacent_difference range + \fI(function template)\fP + accumulate sums up or folds a range of elements + \fI(function template)\fP + partial_sum computes the partial sum of a range of elements + \fI(function template)\fP + transform_exclusive_scan applies an invocable, then calculates exclusive scan + \fI(C++17)\fP \fI(function template)\fP + inclusive_scan similar to std::partial_sum, includes the i^th input + \fI(C++17)\fP element in the i^th sum + \fI(function template)\fP diff --git a/man/std::execution::ensure_started.3 b/man/std::execution::ensure_started.3 new file mode 100644 index 000000000..06d4dc772 --- /dev/null +++ b/man/std::execution::ensure_started.3 @@ -0,0 +1,37 @@ +.TH std::execution::ensure_started 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::ensure_started \- std::execution::ensure_started + +.SH Synopsis + Defined in header + execution::sender auto ensure_started( + + execution::sender auto sender (since C++26) + + ); + +.SH Parameters + + sender - input sender of which the stopped channel is mapped into err + +.SH Return value + + Returns a sender which completes when the provided sender completes and sends values + equivalent to those of the provided sender. + +.SH Notes + + * Once ensure_started returns, it is known that the provided sender has been + connected and start has been called on the resulting operation state. In other + words, the work described by the provided sender has been submitted for + execution on the appropriate execution resources. + * If the returned sender is destroyed before execution::connect() is called, or if + execution::connect() is called but the returned operation-state is destroyed + before execution::start() is called, then a stop-request is sent to the eagerly + launched operation and the operation is detached and will run to completion in + the background. + * In such a case, the operation's result will be discarded when it is eventually + complete. + * Note that the application will need to make sure that resources are kept alive + in the case that the operation detaches (e.g. by holding a std::shared_ptr to + those resources). diff --git a/man/std::execution::into_variant.3 b/man/std::execution::into_variant.3 new file mode 100644 index 000000000..4a582975b --- /dev/null +++ b/man/std::execution::into_variant.3 @@ -0,0 +1,22 @@ +.TH std::execution::into_variant 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::into_variant \- std::execution::into_variant + +.SH Synopsis + Defined in header + execution::sender auto into_variant( + + execution::sender auto snd (since C++26) + + ); + +.SH Parameters + + snd - input sender which can send multiple sets of values depending on runtime + conditions. + +.SH Return value + + Returns a sender that sends a variant of tuples of all the possible sets of types + sent by the input sender. The helper function turns them into a single variant + value. diff --git a/man/std::execution::just.3 b/man/std::execution::just.3 new file mode 100644 index 000000000..10d87cb16 --- /dev/null +++ b/man/std::execution::just.3 @@ -0,0 +1,19 @@ +.TH std::execution::just 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::just \- std::execution::just + +.SH Synopsis + Defined in header + execution::sender auto just( + + auto ...&& values (since C++26) + + ); + +.SH Parameters + + values - input values which are decay-copied into the returned sender. + +.SH Return value + + Returns a sender with no completion schedulers, which sends the provided values. diff --git a/man/std::execution::just_error.3 b/man/std::execution::just_error.3 new file mode 100644 index 000000000..0b1c47677 --- /dev/null +++ b/man/std::execution::just_error.3 @@ -0,0 +1,22 @@ +.TH std::execution::just_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::just_error \- std::execution::just_error + +.SH Synopsis + Defined in header + execution::sender auto just_error( auto && error ); (since C++26) + +.SH Parameters + + error - input error which will be injected and returned by the receiver. + +.SH Return value + + Returns a sender with no completion schedulers, which sends the provided values. + +.SH Notes + + If the provided error is an lvalue reference, a copy is made inside the returned + sender and a non-const lvalue reference to the copy is sent to the receiver’s + set_error. If the provided value is an rvalue reference, it is moved into the + returned sender and an rvalue reference to it is sent to the receiver’s set_error. diff --git a/man/std::execution::just_stopped.3 b/man/std::execution::just_stopped.3 new file mode 100644 index 000000000..7bb486a2f --- /dev/null +++ b/man/std::execution::just_stopped.3 @@ -0,0 +1,16 @@ +.TH std::execution::just_stopped 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::just_stopped \- std::execution::just_stopped + +.SH Synopsis + Defined in header + execution::sender auto just_stopped(); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Returns a sender with no completion schedulers, which completes immediately by + calling the receiver’s set_stopped. diff --git a/man/std::execution::let_error.3 b/man/std::execution::let_error.3 new file mode 100644 index 000000000..27a93de3f --- /dev/null +++ b/man/std::execution::let_error.3 @@ -0,0 +1,24 @@ +.TH std::execution::let_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::let_error \- std::execution::let_error + +.SH Synopsis + Defined in header + execution::sender auto let_error( + + execution::sender auto input, (since C++26) + std::invocable function + + ); + +.SH Parameters + + input - sender which once an error occurs, sends the errors to the function + function - invocable to be called with errors in case an error occurs by input + sender + +.SH Return value + + Returns a sender describing the task graph described by the input sender, with an + added node of invoking the provided function with errors sent by the input sender, + if an error occurs. diff --git a/man/std::execution::let_stopped.3 b/man/std::execution::let_stopped.3 new file mode 100644 index 000000000..1b2a8d103 --- /dev/null +++ b/man/std::execution::let_stopped.3 @@ -0,0 +1,23 @@ +.TH std::execution::let_stopped 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::let_stopped \- std::execution::let_stopped + +.SH Synopsis + Defined in header + execution::sender auto let_stopped( + + execution::sender auto input, (since C++26) + std::invocable auto function + + ); + +.SH Parameters + + input - sender which once stopped, sends the "stop token" to execute the function + function - invocable to be called with errors in case an error occurs by input + sender + +.SH Return value + + Returns a sender describing the task graph described by the input sender, with an + added node invoked when the "stopped" signal is sent. diff --git a/man/std::execution::let_value.3 b/man/std::execution::let_value.3 new file mode 100644 index 000000000..99cefed3b --- /dev/null +++ b/man/std::execution::let_value.3 @@ -0,0 +1,29 @@ +.TH std::execution::let_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::let_value \- std::execution::let_value + +.SH Synopsis + Defined in header + execution::sender auto let_value( + + execution::sender auto input, (since C++26) + std::invocable function + + ); + +.SH Parameters + + input - sender which once executed sends the values upon which the function + executes + function - invocable to be called with the values from the input sender + +.SH Return value + + Returns a sender describing the task graph described by the input sender, with an + added node of invoking the provided function with the values sent by the input + sender as arguments. + + let_value is similar to then, however, where the sender returned from then sends + exactly what that function ends up returning - let_value requires that the function + returns a sender, and the sender returned by let_value sends the values sent by the + sender returned from the callback. diff --git a/man/std::execution::on.3 b/man/std::execution::on.3 new file mode 100644 index 000000000..270e9bbba --- /dev/null +++ b/man/std::execution::on.3 @@ -0,0 +1,24 @@ +.TH std::execution::on 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::on \- std::execution::on + +.SH Synopsis + Defined in header + execution::sender auto on( + + execution::scheduler auto sched, (since C++26) + execution::sender auto snd + + ); + +.SH Parameters + + sched - provides execution agent on which the sender will be executed + snd - work to be executed on the execution resource associated with sched + +.SH Return value + + Returns a sender which, when started, will start the provided sender on an execution + agent belonging to the execution resource associated with the provided scheduler. + + The returned sender has no completion schedulers. diff --git a/man/std::execution::read.3 b/man/std::execution::read.3 new file mode 100644 index 000000000..31a88b84e --- /dev/null +++ b/man/std::execution::read.3 @@ -0,0 +1,41 @@ +.TH std::execution::read 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::read \- std::execution::read + +.SH Synopsis + Defined in header + execution::sender auto read( auto tag ); (since C++26) + +.SH Parameters + + tag - by which the customization point is recognized + +.SH Return value + + Returns a sender that reaches into a receiver’s environment and pulls out the + current value associated with the customization point denoted by Tag. + +.SH Example + + Possible usage of tags in read function, to retrieve the value associated with the + customization point. + + execution::sender auto get_scheduler() + { + return read(execution::get_scheduler); + } + + execution::sender auto get_delegatee_scheduler() + { + return read(execution::get_delegatee_scheduler); + } + + execution::sender auto get_allocator() + { + return read(execution::get_allocator); + } + + execution::sender auto get_stop_token() + { + return read(execution::get_stop_token); + } diff --git a/man/std::execution::schedule.3 b/man/std::execution::schedule.3 new file mode 100644 index 000000000..c6330eb53 --- /dev/null +++ b/man/std::execution::schedule.3 @@ -0,0 +1,27 @@ +.TH std::execution::schedule 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::schedule \- std::execution::schedule + +.SH Synopsis + Defined in header + execution::sender auto schedule( + + execution::scheduler auto scheduler (since C++26) + + ); + +.SH Parameters + + scheduler - scheduler on which the start of the task graph is scheduled. + +.SH Return value + + Returns a sender describing the start of a task graph on the provided scheduler. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::execution::seq,std::execution::par,std::execution::par_unseq,std::execution::unseq.3 b/man/std::execution::seq,std::execution::par,std::execution::par_unseq,std::execution::unseq.3 new file mode 100644 index 000000000..80c5ad974 --- /dev/null +++ b/man/std::execution::seq,std::execution::par,std::execution::par_unseq,std::execution::unseq.3 @@ -0,0 +1,105 @@ +.TH std::execution::seq,std::execution::par,std::execution::par_unseq,std::execution::unseq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::seq,std::execution::par,std::execution::par_unseq,std::execution::unseq \- std::execution::seq,std::execution::par,std::execution::par_unseq,std::execution::unseq + +.SH Synopsis + Defined in header + inline constexpr \fI(since C++17)\fP + std::execution::sequenced_policy seq { /* unspecified */ }; + inline constexpr \fI(since C++17)\fP + std::execution::parallel_policy par { /* unspecified */ }; + inline constexpr + std::execution::parallel_unsequenced_policy par_unseq { /* \fI(since C++17)\fP + unspecified */ }; + inline constexpr \fI(since C++20)\fP + std::execution::unsequenced_policy unseq { /* unspecified */ }; + + The execution policy types + + * std::execution::sequenced_policy, + * std::execution::parallel_policy, + * std::execution::parallel_unsequenced_policy, and + * std::execution::unsequenced_policy + + have the following respective instances: + + * std::execution::seq, + * std::execution::par, + * std::execution::par_unseq, and + * std::execution::unseq. + + These instances are used to specify the execution policy of parallel algorithms, + i.e., the kinds of parallelism allowed. + + Additional execution policies may be provided by a standard library implementation + (possible future additions may include std::parallel::cuda and + std::parallel::opencl). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + #ifdef PARALLEL + #include + namespace execution = std::execution; + #else + enum class execution { seq, unseq, par_unseq, par }; + #endif + + void measure([[maybe_unused]] auto policy, std::vector v) + { + const auto start = std::chrono::steady_clock::now(); + #ifdef PARALLEL + std::sort(policy, v.begin(), v.end()); + #else + std::sort(v.begin(), v.end()); + #endif + const auto finish = std::chrono::steady_clock::now(); + std::cout << std::chrono::duration_cast(finish - start) + << '\\n'; + }; + + int main() + { + std::vector v(1'000'000); + std::mt19937 gen {std::random_device{}()}; + std::ranges::generate(v, gen); + + measure(execution::seq, v); + measure(execution::unseq, v); + measure(execution::par_unseq, v); + measure(execution::par, v); + } + +.SH Possible output: + + // online GNU/gcc compiler (PARALLEL macro is not defined) + 81ms + 80ms + 79ms + 78ms + + // with g++ -std=c++23 -O3 ./test.cpp -ltbb -DPARALLEL + 165ms + 163ms + 30ms + 27ms + +.SH See also + + sequenced_policy + parallel_policy + parallel_unsequenced_policy + unsequenced_policy execution policy types + \fI(C++17)\fP \fI(class)\fP + \fI(C++17)\fP + \fI(C++17)\fP + (C++20) diff --git a/man/std::execution::sequenced_policy,std::execution::parallel_policy,.3 b/man/std::execution::sequenced_policy,std::execution::parallel_policy,.3 new file mode 100644 index 000000000..1279d2dee --- /dev/null +++ b/man/std::execution::sequenced_policy,std::execution::parallel_policy,.3 @@ -0,0 +1,100 @@ +.TH std::execution::sequenced_policy,std::execution::parallel_policy, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::sequenced_policy,std::execution::parallel_policy, \- std::execution::sequenced_policy,std::execution::parallel_policy, + +.SH Synopsis + + Defined in header + class sequenced_policy { /* unspecified */ }; \fB(1)\fP \fI(since C++17)\fP + class parallel_policy { /* unspecified */ }; \fB(2)\fP \fI(since C++17)\fP + class parallel_unsequenced_policy { /* unspecified */ }; \fB(3)\fP \fI(since C++17)\fP + class unsequenced_policy { /* unspecified */ }; \fB(4)\fP \fI(since C++20)\fP + + 1) The execution policy type used as a unique type to disambiguate parallel + algorithm overloading and require that a parallel algorithm's execution may not be + parallelized. The invocations of element access functions in parallel algorithms + invoked with this policy (usually specified as std::execution::seq) are + indeterminately sequenced in the calling thread. + 2) The execution policy type used as a unique type to disambiguate parallel + algorithm overloading and indicate that a parallel algorithm's execution may be + parallelized. The invocations of element access functions in parallel algorithms + invoked with this policy (usually specified as std::execution::par) are permitted to + execute in either the invoking thread or in a thread implicitly created by the + library to support parallel algorithm execution. Any such invocations executing in + the same thread are indeterminately sequenced with respect to each other. + 3) The execution policy type used as a unique type to disambiguate parallel + algorithm overloading and indicate that a parallel algorithm's execution may be + parallelized, vectorized, or migrated across threads (such as by a parent-stealing + scheduler). The invocations of element access functions in parallel algorithms + invoked with this policy are permitted to execute in an unordered fashion in + unspecified threads, and unsequenced with respect to one another within each thread. + 4) The execution policy type used as a unique type to disambiguate parallel + algorithm overloading and indicate that a parallel algorithm's execution may be + vectorized, e.g., executed on a single thread using instructions that operate on + multiple data items. + + During the execution of a parallel algorithm with any of these execution policies, + if the invocation of an element access function exits via an uncaught exception, + std::terminate is called, but the implementations may define additional execution + policies that handle exceptions differently. + +.SH Notes + + When using parallel execution policy, it is the programmer's responsibility to avoid + data races and deadlocks: + + int a[] = {0, 1}; + std::vector v; + std::for_each(std::execution::par, std::begin(a), std::end(a), [&](int i) + { + v.push_back(i * 2 + 1); // Error: data race + }); + + std::atomic x {0}; + int a[] = {1, 2}; + std::for_each(std::execution::par, std::begin(a), std::end(a), [&](int) + { + x.fetch_add(1, std::memory_order_relaxed); + while (x.load(std::memory_order_relaxed) == 1) { } // Error: assumes execution order + }); + + int x = 0; + std::mutex m; + int a[] = {1, 2}; + std::for_each(std::execution::par, std::begin(a), std::end(a), [&](int) + { + std::lock_guard guard(m); + ++x; // correct + }); + + Unsequenced execution policies are the only case where function calls are + unsequenced with respect to each other, meaning they can be interleaved. In all + other situations in C++, they are indeterminately-sequenced (cannot interleave). + Because of that, users are not allowed to allocate or deallocate memory, acquire + mutexes, use non-lockfree std::atomic specializations, or, in general, perform any + vectorization-unsafe operations when using these policies (vectorization-unsafe + functions are the ones that synchronize-with another function, e.g. + std::mutex::unlock synchronizes-with the next std::mutex::lock). + + int x = 0; + std::mutex m; + int a[] = {1, 2}; + std::for_each(std::execution::par_unseq, std::begin(a), std::end(a), [&](int) + { + std::lock_guard guard(m); // Error: lock_guard constructor calls m.lock() + ++x; + }); + + If the implementation cannot parallelize or vectorize (e.g. due to lack of + resources), all standard execution policies can fall back to sequential execution. + +.SH See also + + seq + par + par_unseq + unseq global execution policy objects + \fI(C++17)\fP (constant) + \fI(C++17)\fP + \fI(C++17)\fP + (C++20) diff --git a/man/std::execution::stopped_as_error.3 b/man/std::execution::stopped_as_error.3 new file mode 100644 index 000000000..70259a03e --- /dev/null +++ b/man/std::execution::stopped_as_error.3 @@ -0,0 +1,22 @@ +.TH std::execution::stopped_as_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::stopped_as_error \- std::execution::stopped_as_error + +.SH Synopsis + Defined in header + template + + execution::sender auto stopped_as_error( + execution::sender auto snd, (since C++26) + Error err + + ); + +.SH Parameters + + snd - input sender of which the stopped channel is mapped into err + err - error to which the stop channel is mapped into + +.SH Return value + + Returns a sender that maps the stopped channel to an error of err. diff --git a/man/std::execution::stopped_as_optional.3 b/man/std::execution::stopped_as_optional.3 new file mode 100644 index 000000000..8210ce2f2 --- /dev/null +++ b/man/std::execution::stopped_as_optional.3 @@ -0,0 +1,21 @@ +.TH std::execution::stopped_as_optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::stopped_as_optional \- std::execution::stopped_as_optional + +.SH Synopsis + Defined in header + execution::sender auto stopped_as_optional( + + single-sender auto snd (since C++26) + + ); + +.SH Parameters + + snd - input sender of which the value channel and stopped channel are mapped. + +.SH Return value + + Returns a sender that maps the value channel from a T to an + std::optional>, and maps the stopped channel to a value of an empty + std::optional>. diff --git a/man/std::execution::sync_wait.3 b/man/std::execution::sync_wait.3 new file mode 100644 index 000000000..4180542e2 --- /dev/null +++ b/man/std::execution::sync_wait.3 @@ -0,0 +1,35 @@ +.TH std::execution::sync_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::sync_wait \- std::execution::sync_wait + +.SH Synopsis + Defined in header + auto sync_wait( execution::sender auto sender ) + + requires (/*always-sends-some-values*/(sender)) (since C++26) + + -> std::optional>; + +.SH Parameters + + sender - sender upon which the completion of sync_wait is blocked + +.SH Return value + + Returns an optional tuple of values that were sent by the provided sender on its + completion of work. + +.SH Notes + + The sender returned by sync_wait similarly to ensure_started, except that it blocks + the current std::thread or thread of main until the work is completed. + +.SH See also + + Eagerly starts a sender, returning a sender that will deliver the + results to a receiver to which it is connected and started, if any. + When the result sender is not connected to a receiver, or if the + ensure_started resulting operation state is not started, the results are ignored. If + such a sender is destroyed before the underlying operation completes, + the operation continues running detached. + \fI(function template)\fP diff --git a/man/std::execution::then.3 b/man/std::execution::then.3 new file mode 100644 index 000000000..f8f14af78 --- /dev/null +++ b/man/std::execution::then.3 @@ -0,0 +1,39 @@ +.TH std::execution::then 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::then \- std::execution::then + +.SH Synopsis + Defined in header + execution::sender auto then( + + execution::sender auto input, (since C++26) + std::invocable function + + ); + +.SH Parameters + + input - sender which once executed sends the values upon which the function + executes + function - invocable to be called by the new sender chained to the input sender + +.SH Return value + + Returns a sender describing the task graph described by the input sender, with an + added node of invoking the provided function with the values sent by the input + sender as arguments. + + then is guaranteed to not begin executing function until the returned sender is + started. + +.SH Example + + Possible usage of execution::then. + + execution::sender auto input = get_input(); + execution::sender auto snd = execution::then(input, [](auto... args) + { + std::print(args...); + }); + // snd describes the work described by pred + // followed by printing all of the values sent by pred diff --git a/man/std::execution::transfer.3 b/man/std::execution::transfer.3 new file mode 100644 index 000000000..0ecfcd4da --- /dev/null +++ b/man/std::execution::transfer.3 @@ -0,0 +1,35 @@ +.TH std::execution::transfer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::transfer \- std::execution::transfer + +.SH Synopsis + Defined in header + execution::sender auto transfer( + + execution::sender auto input, + execution::scheduler auto scheduler + + ); + +.SH Parameters + + input - sender to be transfered on the scheduler + scheduler - scheduler on which the sender will run + +.SH Return value + + Returns a sender describing the transition from the execution agent of the input + sender to the execution agent of the target scheduler. + +.SH Example + + Possible usage of execution::transfer. + + execution::scheduler auto cpu_sched = get_system_thread_pool().scheduler(); + execution::scheduler auto gpu_sched = cuda::scheduler(); + + execution::sender auto cpu_task = execution::schedule(cpu_sched); + // cpu_task describes the creation of a new task on the system thread pool + + execution::sender auto gpu_task = execution::transfer(cpu_task, gpu_sched); + // gpu_task describes the transition of the task graph described by cpu_task to the GPU diff --git a/man/std::execution::upon_error.3 b/man/std::execution::upon_error.3 new file mode 100644 index 000000000..a70951f27 --- /dev/null +++ b/man/std::execution::upon_error.3 @@ -0,0 +1,24 @@ +.TH std::execution::upon_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::upon_error \- std::execution::upon_error + +.SH Synopsis + Defined in header + execution::sender auto upon_error( + + execution::sender auto input, (since C++26) + std::invocable function + + ); + +.SH Parameters + + input - sender which once an error occurs, sends the errors to the function + function - invocable to be called with errors in case an error occurs by input + sender + +.SH Return value + + Returns a sender describing the task graph described by the input sender, with an + added node of invoking the provided function with the errors sent by the input + sender as arguments (in case of an error). diff --git a/man/std::execution::upon_stopped.3 b/man/std::execution::upon_stopped.3 new file mode 100644 index 000000000..b4c23f52a --- /dev/null +++ b/man/std::execution::upon_stopped.3 @@ -0,0 +1,25 @@ +.TH std::execution::upon_stopped 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::upon_stopped \- std::execution::upon_stopped + +.SH Synopsis + Defined in header + execution::sender auto upon_stopped( + + execution::sender auto input, (since C++26) + std::invocable auto function + + ); + +.SH Parameters + + input - sender which once gets "stop token", will notify the new node to execute + the function + function - invocable to be called in case a "stopped" signal is sent to the input + sender + +.SH Return value + + Returns a sender describing the task graph described by the input sender, with an + added node of invoking the provided function in case the "stopped" signal is sent to + the input sender. diff --git a/man/std::execution::when_all.3 b/man/std::execution::when_all.3 new file mode 100644 index 000000000..04e9a2569 --- /dev/null +++ b/man/std::execution::when_all.3 @@ -0,0 +1,34 @@ +.TH std::execution::when_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::execution::when_all \- std::execution::when_all + +.SH Synopsis + Defined in header + execution::sender auto when_all( + + execution::sender auto ...inputs (since C++26) + + ); + +.SH Parameters + + inputs - senders upon which the completion of when_all is blocked. Can only include + senders that can complete with a single set of values. + +.SH Return value + + Returns a sender that completes once all of the input senders have completed. The + values sent by this sender are the values sent by each of the input senders, in + order of the arguments passed to when_all. + +.SH Notes + + * The sender returned by when_all completes inline on the execution resource on + which the last input sender completes, unless stop is requested before when_all + is started, in which case it completes inline within the call to start. + +.SH See also + + when_all produces a future that becomes ready when all given futures or + (concurrency TS) shared_futures are ready + \fI(function template)\fP diff --git a/man/std::exit.3 b/man/std::exit.3 index 7f825cd74..8ce936a41 100644 --- a/man/std::exit.3 +++ b/man/std::exit.3 @@ -1,4 +1,7 @@ -.TH std::exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exit \- std::exit + .SH Synopsis Defined in header void exit( int exit_code ); \fI(until C++11)\fP @@ -8,72 +11,80 @@ Several cleanup steps are performed: - 1) destructors of objects with static storage duration are called in - reverse order of completion of their constructors or the completion of - their dynamic initialization, and the functions passed to std::atexit - are called in reverse order they are registered (last one first). - a) any static objects whose initialization was completed before the - call to std::atexit for some function F will be destroyed after the \fI(until C++11)\fP - call to F during program termination. - b) any static objects whose construction began after the call to - std::atexit for some function F will be destroyed before the call to F - during program termination (this includes the case where std::atexit - was called from the constructor of the static object) - 1) The destructors of objects with thread local storage duration, the - destructors of objects with static storage duration, and the functions - registered with std::atexit are executed concurrently, while - maintaining the following guarantees: + 1) Objects with static storage duration are destroyed and functions + registered by calling std::atexit are called: + a) Non-local objects with static storage duration are destroyed in the + reverse order of the completion of their constructor. + b) Functions registered with std::atexit are called in the reverse + order of their registration, except that a function is called after + any previously registered functions that had already been called at + the time it was registered. + c) For each function f registered with std::atexit and each non-local + object obj of static storage duration, \fI(until C++11)\fP + + * if f is registered before the initialization of obj, f will only + be called after the destruction of obj; + * if f is registered after the initialization of obj, f will only be + called before the destruction of obj. + d) For each local object obj with static storage duration, obj is + destroyed as if a function calling the destructor of obj were + registered with std::atexit at the completion of the constructor of + obj. + 1) The destructors of objects with thread local storage duration that + are associated with the current thread, the destructors of objects + with static storage duration, and the functions registered with + std::atexit are executed concurrently, while maintaining the following + guarantees: a) The last destructor for thread-local objects is sequenced-before - the first destructor for a static object + the first destructor for a static object. b) If the completion of the constructor or dynamic initialization for thread-local or static object A was sequenced-before thread-local or static object B, the completion of the destruction of B is - sequenced-before the start of the destruction of A - c) If the completion of the initialization of a static object A was \fI(since C++11)\fP + sequenced-before the start of the destruction of A. \fI(since C++11)\fP + c) If the completion of the initialization of a static object A was sequenced-before the call to std::atexit for some function F, the call to F during termination is sequenced-before the start of the - destruction of A + destruction of A. d) If the call to std::atexit for some function F was sequenced-before the completion of initialization of a static object A, the start of the destruction of A is sequenced-before the call to F during termination. e) If a call to std::atexit for some function F1 was sequenced-before the call to std::atexit for some function F2, then the call to F2 - during termination is sequenced-before the call to F1 + during termination is sequenced-before the call to F1. * In the above, - * if any function registered with atexit or any destructor of static/thread-local - object throws an exception, std::terminate is called - * if the compiler opted to lift dynamic initialization of an object to the static + * If any function registered with atexit or any destructor of static/thread-local + object throws an exception, std::terminate is called. + * If the compiler opted to lift dynamic initialization of an object to the static initialization phase of non-local initialization, the sequencing of destruction honors its would-be dynamic initialization. * If a function-local (block-scope) static object was destroyed and then that function is called from the destructor of another static object and the control flow passes through the definition of that object (or if it is used indirectly, via pointer or reference), the behavior is undefined. - * if a function-local (block-scope) static object was initialized during + * If a function-local (block-scope) static object was initialized during construction of a subobject of a class or array, it is only destroyed after all subobjects of that class or all elements of that array were destroyed. - - 2) all C streams are flushed and closed - 3) files created by std::tmpfile are removed - 4) control is returned to the host environment. If exit_code is 0 or EXIT_SUCCESS, + 2) All C streams are flushed and closed. + 3) Files created by std::tmpfile are removed. + 4) Control is returned to the host environment. If exit_code is 0 or EXIT_SUCCESS, an implementation-defined status indicating successful termination is returned. If exit_code is EXIT_FAILURE, an implementation-defined status indicating unsuccessful termination is returned. In other cases implementation-defined status value is returned. - Stack is not unwound: destructors of variables with automatic storage durations are + Stack is not unwound: destructors of variables with automatic storage duration are not called. .SH Relationship with the main function - Returning from the the main function, either by a return statement or by reaching - the end of the function performs the normal function termination (calls the - destructors of the variables with automatic storage durations) and then executes - std::exit, passing the argument of the return statement (or 0 if implicit return - was used) as exit_code. + Returning from the main function, either by a return statement or by reaching the + end of the function performs the normal function termination (calls the destructors + of the variables with automatic storage durations) and then executes std::exit, + passing the argument of the return statement (or 0 if implicit return was used) as + exit_code. .SH Parameters @@ -85,63 +96,78 @@ .SH Example - + // Run this code - #include #include - - class Static { - public: - + #include + + struct Static + { ~Static() { - std::cout << "Static dtor\\n"; + std::cout << "Static destructor\\n"; } }; - - class Local { - public: + + struct Local + { ~Local() { - std::cout << "Local dtor\\n"; + std::cout << "Local destructor\\n"; } }; - - Static static_variable; // dtor of this object *will* be called - + + Static static_variable; // Destructor of this object *will* be called + void atexit_handler() { std::cout << "atexit handler\\n"; } - + int main() { - Local local_variable; // dtor of this object will *not* be called - const int result = std::atexit(atexit_handler); // handler will be called - - if (result != 0) { + Local local_variable; // Destructor of this object will *not* be called + const int result = std::atexit(atexit_handler); // Handler will be called + + if (result != 0) + { std::cerr << "atexit registration failed\\n"; return EXIT_FAILURE; } - + std::cout << "test\\n"; std::exit(EXIT_FAILURE); + + std::cout << "this line will *not* be executed\\n"; } .SH Output: test atexit handler - Static dtor + Static destructor + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + during cleanup, the behavior was unclear when \fB(1)\fP + LWG 3 C++98 a function is made clear + registered with std::atexit or \fB(2)\fP a static local + object is initialized .SH See also - abort causes abnormal program termination (without cleaning up) - \fI(function)\fP - atexit registers a function to be called on std::exit() invocation - \fI(function)\fP - quick_exit causes normal program termination without completely cleaning up - \fI(C++11)\fP \fI(function)\fP + abort causes abnormal program termination (without cleaning up) + \fI(function)\fP + atexit registers a function to be called on std::exit() invocation + \fI(function)\fP + quick_exit causes quick program termination without completely cleaning up + \fI(C++11)\fP \fI(function)\fP + at_quick_exit registers a function to be called on std::quick_exit invocation + \fI(C++11)\fP \fI(function)\fP C documentation for exit diff --git a/man/std::exp(std::complex).3 b/man/std::exp(std::complex).3 index 16af4c1e0..cc800e986 100644 --- a/man/std::exp(std::complex).3 +++ b/man/std::exp(std::complex).3 @@ -1,10 +1,14 @@ -.TH std::exp(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exp(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exp(std::complex) \- std::exp(std::complex) + .SH Synopsis Defined in header template< class T > - complex exp( const complex& z ); + std::complex exp( const std::complex& z ); - Compute e (Euler's number, 2.7182818) raised to the complex base-e exponential of x. + Compute base-e exponential of z, that is e (Euler's number, 2.7182818) raised to the + z power. .SH Parameters @@ -12,34 +16,92 @@ .SH Return value - e raised to a complex power. + If no errors occur, e raised to the power of z, \\(\\small e^z\\)ez + , is returned. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::exp(std::conj(z)) == std::conj(std::exp(z)) + * If z is (±0,+0), the result is (1,+0) + * If z is (x,+∞) (for any finite x), the result is (NaN,NaN) and FE_INVALID is + raised. + * If z is (x,NaN) (for any finite x), the result is (NaN,NaN) and FE_INVALID may + be raised. + * If z is (+∞,+0), the result is (+∞,+0) + * If z is (-∞,y) (for any finite y), the result is +0cis(y) + * If z is (+∞,y) (for any finite nonzero y), the result is +∞cis(y) + * If z is (-∞,+∞), the result is (±0,±0) (signs are unspecified) + * If z is (+∞,+∞), the result is (±∞,NaN) and FE_INVALID is raised (the sign of + the real part is unspecified) + * If z is (-∞,NaN), the result is (±0,±0) (signs are unspecified) + * If z is (+∞,NaN), the result is (±∞,NaN) (the sign of the real part is + unspecified) + * If z is (NaN,+0), the result is (NaN,+0) + * If z is (NaN,y) (for any nonzero y), the result is (NaN,NaN) and FE_INVALID may + be raised + * If z is (NaN,NaN), the result is (NaN,NaN) + + where \\(\\small{\\rm cis}(y)\\)cis(y) is \\(\\small \\cos(y)+{\\rm i}\\sin(y)\\)cos(y) + i + sin(y). + +.SH Notes + + The complex exponential function \\(\\small e^z\\)ez + for \\(\\small z = x + {\\rm i}y\\)z = x+iy equals \\(\\small e^x {\\rm cis}(y)\\)ex + cis(y), or, \\(\\small e^x (\\cos(y)+{\\rm i}\\sin(y))\\)ex + (cos(y) + i sin(y)). + + The exponential function is an entire function in the complex plane and has no + branch cuts. + + The following have equivalent results when the real part is 0: + + * std::exp(std::complex(0, theta)) + * std::complex(cosf(theta), sinf(theta)) + * std::polar(1.f, theta) + + In this case exp can be about 4.5x slower. One of the other forms should be used + instead of calling exp with an argument whose real part is literal 0. There is no + benefit in trying to avoid exp with a runtime check of z.real() == 0 though. .SH Example - + // Run this code + #include #include #include - + int main() { - const double pi = std::acos(-1); - const std::complex i(0, 1); - - std::cout << std::fixed << " exp(i*pi) = " << std::exp(i * pi) << '\\n'; + const double pi = std::acos(-1.0); + const std::complex i(0.0, 1.0); + + std::cout << std::fixed << " exp(i * pi) = " << std::exp(i * pi) << '\\n'; } .SH Output: - exp(i*pi) = (-1.000000,0.000000) + exp(i * pi) = (-1.000000,0.000000) .SH See also - exp returns e raised to the given power (e^x) - \fI(function)\fP - pow(std::complex) complex power, one or both arguments may be a complex number - \fI(function template)\fP - complex natural logarithm with the branch cuts along the negative - log(std::complex) real axis - \fI(function template)\fP + complex natural logarithm with the branch cuts along the negative + log(std::complex) real axis + \fI(function template)\fP + exp + expf returns e raised to the given power (\\({\\small e^x}\\)e^x) + expl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp(std::valarray) applies the function std::exp to each element of valarray + \fI(function template)\fP + polar constructs a complex number from magnitude and phase angle + \fI(function template)\fP + C documentation for + cexp diff --git a/man/std::exp(std::valarray).3 b/man/std::exp(std::valarray).3 index 66ccb62cd..7c5ca3c72 100644 --- a/man/std::exp(std::valarray).3 +++ b/man/std::exp(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::exp(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exp(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exp(std::valarray) \- std::exp(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -18,7 +21,7 @@ .SH Notes Unqualified function (exp) is used to perform the computation. If such function is - not available, std::exp is used due to argument dependent lookup. + not available, std::exp is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -26,22 +29,24 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Possible implementation - template< class T > - valarray exp( const valarray& va ) + template + valarray exp(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = exp(i); - } + return other; // proxy object may be returned } @@ -50,36 +55,45 @@ This example demonstrates the Euler's identity eiπ = -1 and the related exponents. - + // Run this code - #include #include + #include + #include #include - + int main() { - const double pi = std::acos(-1); - std::valarray> v = { - {0, 0}, {0, pi/2}, {0, pi}, {0, 3*pi/2}, {0, 2*pi} + const double pi = std::numbers::pi; + std::valarray> v = + { + {0, 0}, {0, pi / 2}, {0, pi}, {0, 3 * pi / 2}, {0, 2 * pi} }; std::valarray> v2 = std::exp(v); - for(auto n : v2) { - std::cout << std::fixed << n << '\\n'; - } + for (std::cout << std::showpos << std::fixed; auto n : v2) + std::cout << n << '\\n'; } .SH Output: - (1.000000,0.000000) - (0.000000,1.000000) - (-1.000000,0.000000) + (+1.000000,+0.000000) + (+0.000000,+1.000000) + (-1.000000,+0.000000) (-0.000000,-1.000000) - (1.000000,-0.000000) + (+1.000000,-0.000000) .SH See also - exp returns e raised to the given power (e^x) - \fI(function)\fP - exp(std::complex) complex base e exponential - \fI(function template)\fP + log(std::valarray) applies the function std::log to each element of valarray + \fI(function template)\fP + exp + expf returns e raised to the given power (\\({\\small e^x}\\)e^x) + expl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp(std::complex) complex base e exponential + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::exp,std::expf,std::expl.3 b/man/std::exp,std::expf,std::expl.3 new file mode 100644 index 000000000..ad7464b91 --- /dev/null +++ b/man/std::exp,std::expf,std::expl.3 @@ -0,0 +1,150 @@ +.TH std::exp,std::expf,std::expl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exp,std::expf,std::expl \- std::exp,std::expf,std::expl + +.SH Synopsis + Defined in header + float exp ( float num ); + + double exp ( double num ); (until C++23) + + long double exp ( long double num ); + /* floating-point-type */ (since C++23) + exp ( /* floating-point-type */ num ); (constexpr since C++26) + float expf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double expl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double exp ( Integer num ); + + 1-3) Computes e (Euler's number, 2.7182818...) raised to the given power num. + The library provides overloads of std::exp for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the base-e exponential of num (enum + ) is returned. + + If a range error occurs due to overflow, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is + returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, 1 is returned. + * If the argument is -∞, +0 is returned. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + For IEEE-compatible type double, overflow is guaranteed if 709.8 < num, and + underflow is guaranteed if num < -708.4. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::exp(num) has the same effect as std::exp(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + consteval double approx_e() + { + long double e{1.0}; + for (auto fac{1ull}, n{1llu}; n != 18; ++n, fac *= n) + e += 1.0 / fac; + return e; + } + + int main() + { + std::cout << std::setprecision(16) + << "exp(1) = e¹ = " << std::exp(1) << '\\n' + << "numbers::e = " << std::numbers::e << '\\n' + << "approx_e = " << approx_e() << '\\n' + << "FV of $100, continuously compounded at 3% for 1 year = " + << std::setprecision(6) << 100 * std::exp(0.03) << '\\n'; + + // special values + std::cout << "exp(-0) = " << std::exp(-0.0) << '\\n' + << "exp(-Inf) = " << std::exp(-INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "exp(710) = " << std::exp(710) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Possible output: + + exp\fB(1)\fP = e¹ = 2.718281828459045 + numbers::e = 2.718281828459045 + approx_e = 2.718281828459045 + FV of $100, continuously compounded at 3% for 1 year = 103.045 + exp(-0) = 1 + exp(-Inf) = 0 + exp(710) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + exp2 + exp2f + exp2l returns 2 raised to the given power (\\({\\small 2^x}\\)2^x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + expm1 + expm1f returns e raised to the given power, minus one (\\({\\small + expm1l e^x-1}\\)e^x-1) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log + logf computes natural (base e) logarithm (\\({\\small\\ln{x}}\\)ln(x)) + logl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp(std::complex) complex base e exponential + \fI(function template)\fP + exp(std::valarray) applies the function std::exp to each element of valarray + \fI(function template)\fP + C documentation for + exp diff --git a/man/std::exp.3 b/man/std::exp.3 deleted file mode 100644 index e31f9b379..000000000 --- a/man/std::exp.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH std::exp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float exp( float arg ); - double exp( double arg ); - long double exp( long double arg ); - double exp( Integral arg ); \fI(since C++11)\fP - - Computes the e (Euler's number, 2.7182818) raised to the given power arg - -.SH Parameters - - arg - value of floating-point or Integral type - -.SH Return value - - e raised to the power arg - - If the result is too large for the underlying type, range error occurs and HUGE_VAL - is returned. - -.SH See also - - log computes natural (base e) logarithm (to base e) (ln(x)) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - exp(std::complex) complex base e exponential - \fI(function template)\fP - pow(std::complex) complex power, one or both arguments may be a complex number - \fI(function template)\fP - applies the function std::pow to two valarrays or a valarray and - pow(std::valarray) a value - \fI(function template)\fP - C documentation for - exp diff --git a/man/std::exp2,std::exp2f,std::exp2l.3 b/man/std::exp2,std::exp2f,std::exp2l.3 new file mode 100644 index 000000000..b34cf4a0c --- /dev/null +++ b/man/std::exp2,std::exp2f,std::exp2l.3 @@ -0,0 +1,137 @@ +.TH std::exp2,std::exp2f,std::exp2l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exp2,std::exp2f,std::exp2l \- std::exp2,std::exp2f,std::exp2l + +.SH Synopsis + Defined in header + float exp2 ( float num ); + + double exp2 ( double num ); (until C++23) + + long double exp2 ( long double num ); + /* floating-point-type */ (since C++23) + exp2 ( /* floating-point-type */ num ); (constexpr since C++26) + float exp2f( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double exp2l( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double exp2 ( Integer num ); + + 1-3) Computes 2 raised to the given power num. + The library provides overloads of std::exp2 for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the base-2 exponential of num (2num + ) is returned. + + If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is + returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, 1 is returned. + * If the argument is -∞, +0 is returned. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::exp2(num) has the same effect as std::exp2(static_cast(num)). + + For integral exponents, it may be preferable to use std::ldexp. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "exp2(4) = " << std::exp2(4) << '\\n' + << "exp2(0.5) = " << std::exp2(0.5) << '\\n' + << "exp2(-4) = " << std::exp2(-4) << '\\n'; + + // special values + std::cout << "exp2(-0) = " << std::exp2(-0.0) << '\\n' + << "exp2(-Inf) = " << std::exp2(-INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + const double inf = std::exp2(1024); + const bool is_range_error = errno == ERANGE; + + std::cout << "exp2(1024) = " << inf << '\\n'; + if (is_range_error) + std::cout << " errno == ERANGE: " << std::strerror(ERANGE) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Possible output: + + exp2\fB(4)\fP = 16 + exp2(0.5) = 1.41421 + exp2(-4) = 0.0625 + exp2(-0) = 1 + exp2(-Inf) = 0 + exp2(1024) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + exp + expf returns e raised to the given power (\\({\\small e^x}\\)e^x) + expl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + expm1 + expm1f + expm1l returns e raised to the given power, minus one (\\({\\small e^x-1}\\)e^x-1) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ldexp + ldexpf multiplies a number by 2 raised to an integral power + ldexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log2 + log2f + log2l base 2 logarithm of the given number (\\({\\small\\log_{2}{x}}\\)log[2](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + exp2 diff --git a/man/std::exp2.3 b/man/std::exp2.3 deleted file mode 100644 index b90c37e66..000000000 --- a/man/std::exp2.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::exp2 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - double exp2( double n ); \fI(since C++11)\fP - float exp2( float n ); \fI(since C++11)\fP - long double exp2( long double n ); \fI(since C++11)\fP - double exp2( Integral n ); \fI(since C++11)\fP - - Computes 2 raised to the given power n - -.SH Parameters - - n - value of floating-point or Integral type - -.SH Return value - - 2 raised to the n (i.e. 2^n) - - If the result is too large for the underlying type, range error occurs and HUGE_VAL - is returned. - -.SH See also - - exp returns e raised to the given power (e^x) - \fI(function)\fP - log2 base 2 logarithm of the given number - \fI(C++11)\fP \fI(function)\fP - log computes natural (base e) logarithm (to base e) (ln(x)) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - C documentation for - exp2 diff --git a/man/std::expected.3 b/man/std::expected.3 new file mode 100644 index 000000000..d823ce626 --- /dev/null +++ b/man/std::expected.3 @@ -0,0 +1,182 @@ +.TH std::expected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected \- std::expected + +.SH Synopsis + Defined in header + template< class T, class E > (since C++23) + class expected; + + The class template std::expected provides a way to store either of two values. An + object of std::expected at any given time either holds an expected value of type T, + or an unexpected value of type E. std::expected is never valueless. + + The stored value is allocated directly within the storage occupied by the expected + object. No dynamic memory allocation takes place. + + A program is ill-formed if it instantiates an expected with a reference type, a + function type, or a specialization of std::unexpected. In addition, T must not be + std::in_place_t or std::unexpect_t. + +.SH Template parameters + + the type of the expected value. The type must either be (possibly cv-qualified) + T - void, or meet the Destructible requirements (in particular, array and reference + types are not allowed). + the type of the unexpected value. The type must meet the Destructible + E - requirements, and must be a valid template argument for std::unexpected (in + particular, arrays, non-object types, and cv-qualified types are not allowed). + +.SH Member types + + Member type Definition + value_type T + error_type E + unexpected_type std::unexpected + +.SH Member alias templates + + Type Definition + rebind expected + +.SH Member functions + + constructor constructs the expected object + \fI(public member function)\fP + destructor destroys the expected object, along with its contained value + \fI(public member function)\fP + operator= assigns contents + \fI(public member function)\fP +.SH Observers + operator-> accesses the expected value + operator* \fI(public member function)\fP + operator bool checks whether the object contains an expected value + has_value \fI(public member function)\fP + value returns the expected value + \fI(public member function)\fP + error returns the unexpected value + \fI(public member function)\fP + value_or returns the expected value if present, another value otherwise + \fI(public member function)\fP + Monadic operations + returns the result of the given function on the expected value if it + and_then exists; otherwise, returns the expected itself + \fI(public member function)\fP + returns an expected containing the transformed expected value if it + transform exists; otherwise, returns the expected itself + \fI(public member function)\fP + returns the expected itself if it contains an expected value; + or_else otherwise, returns the result of the given function on the + unexpected value + \fI(public member function)\fP + returns the expected itself if it contains an expected value; + transform_error otherwise, returns an expected containing the transformed unexpected + value + \fI(public member function)\fP +.SH Modifiers + emplace constructs the expected value in-place + \fI(public member function)\fP + swap exchanges the contents + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares expected objects + (C++23) \fI(function template)\fP + swap(std::expected) specializes the std::swap algorithm + (C++23) \fI(function)\fP + +.SH Helper classes + + unexpected represented as an unexpected value + (C++23) \fI(class template)\fP + bad_expected_access exception indicating checked access to an expected that contains + (C++23) an unexpected value + \fI(class template)\fP + unexpect in-place construction tag for unexpected value in expected + unexpect_t (tag) + (C++23) + +.SH Notes + + Types with the same functionality are called Result in Rust and Either in Haskell. + + Feature-test macro Value Std Feature + 202202L (C++23) class template std::expected and associated + __cpp_lib_expected helper classes + 202211L (C++23) Monadic functions for std::expected + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + enum class parse_error + { + invalid_input, + overflow + }; + + auto parse_number(std::string_view& str) -> std::expected + { + const char* begin = str.data(); + char* end; + double retval = std::strtod(begin, &end); + + if (begin == end) + return std::unexpected(parse_error::invalid_input); + else if (std::isinf(retval)) + return std::unexpected(parse_error::overflow); + + str.remove_prefix(end - begin); + return retval; + } + + int main() + { + auto process = [](std::string_view str) + { + std::cout << "str: " << std::quoted(str) << ", "; + if (const auto num = parse_number(str); num.has_value()) + std::cout << "value: " << *num << '\\n'; + // If num did not have a value, dereferencing num + // would cause an undefined behavior, and + // num.value() would throw std::bad_expected_access. + // num.value_or(123) uses specified default value 123. + else if (num.error() == parse_error::invalid_input) + std::cout << "error: invalid input\\n"; + else if (num.error() == parse_error::overflow) + std::cout << "error: overflow\\n"; + else + std::cout << "unexpected!\\n"; // or invoke std::unreachable(); + }; + + for (auto src : {"42", "42abc", "meow", "inf"}) + process(src); + } + +.SH Output: + + str: "42", value: 42 + str: "42abc", value: 42 + str: "meow", error: invalid input + str: "inf", error: overflow + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 22.8 Expected objects [expected] + +.SH See also + + variant a type-safe discriminated union + \fI(C++17)\fP \fI(class template)\fP + optional a wrapper that may or may not hold an object + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::expected::and_then.3 b/man/std::expected::and_then.3 new file mode 100644 index 000000000..29ea603c6 --- /dev/null +++ b/man/std::expected::and_then.3 @@ -0,0 +1,101 @@ +.TH std::expected::and_then 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::and_then \- std::expected::and_then + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr auto and_then( F&& f ) &; + template< class F > \fB(2)\fP (since C++23) + constexpr auto and_then( F&& f ) const&; + template< class F > \fB(3)\fP (since C++23) + constexpr auto and_then( F&& f ) &&; + template< class F > \fB(4)\fP (since C++23) + constexpr auto and_then( F&& f ) const&&; + + If *this contains an expected value, invokes f and returns its result; otherwise, + returns a std::expected object that contains a copy of error(). + + If T is not (possibly cv-qualified) void, the contained expected value (obtained + from operator*) is passed as an argument to f; otherwise f takes no argument. + + 1,2) Given type U as + * std::remove_cvref_t> if T is (possibly cv-qualified) + void, or + * std::remove_cvref_t> otherwise. + If U is not a specialization of std::expected, or std::is_same_v + is false, the program is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if constexpr (std::is_void_v) + return std::invoke(std::forward(f)); + else + return std::invoke(std::forward(f), **this); + } + else + return U(std::unexpect, error()); + + These overloads participate in overload resolution only if + std::is_constructible_v is true. + 3,4) Given type U as + * std::remove_cvref_t> if T is (possibly cv-qualified) + void, or + * std::remove_cvref_t> + otherwise. + If U is not a specialization of std::expected, or std::is_same_v + is false, the program is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if constexpr (std::is_void_v) + return std::invoke(std::forward(f)); + else + return std::invoke(std::forward(f), std::move(**this)); + } + else + return U(std::unexpect, std::move(error())); + + These overloads participate in overload resolution only if + std::is_constructible_v is true. + +.SH Parameters + + f - a suitable function or Callable object that returns a std::expected + +.SH Return value + + The result of f or a std::expected object that contains an error value, as described + above. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_expected 202211L (C++23) Monadic functions for std::expected + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3938 C++23 and_then was ill-formed if T is not (possibly made well-formed + cv-qualified) void and E is not copyable + +.SH See also + + unexpect in-place construction tag for unexpected value in expected + unexpect_t (tag) + (C++23) + returns an expected containing the transformed expected value if it + transform exists; otherwise, returns the expected itself + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::emplace.3 b/man/std::expected::emplace.3 new file mode 100644 index 000000000..dad34dce2 --- /dev/null +++ b/man/std::expected::emplace.3 @@ -0,0 +1,56 @@ +.TH std::expected::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::emplace \- std::expected::emplace + +.SH Synopsis + T is not cv void + template< class... Args > \fB(1)\fP (since C++23) + constexpr T& emplace( Args&&... args ) noexcept; + template< class U, class... Args > + constexpr T& emplace( std::initializer_list il, Args&&... args \fB(2)\fP (since C++23) + ) noexcept; + T is cv void + constexpr void emplace() noexcept; \fB(3)\fP (since C++23) + + Constructs an expected value in-place. After the call, has_value() returns true. + + 1) Destroys the contained value, then initializes the expected value contained in + *this as if by direct-initializing an object of type T from the arguments + std::forward(args).... + This overload participates in overload resolution only if + std::is_nothrow_constructible_v is true. + 2) Destroys the contained value, then initializes the expected value contained in + *this as if by direct-initializing an object of type T from the arguments il and + std::forward(args).... + This overload participates in overload resolution only if + std::is_nothrow_constructible_v&, Args...> is true. + 3) If *this contains an unexpected value, destroys that value. + +.SH Parameters + + args - the arguments to pass to the constructor + il - the initializer list to pass to the constructor + +.SH Return value + + 1,2) A reference to the new contained value. + 3) \fI(none)\fP + +.SH Notes + + If the construction of T is potentially-throwing, this function is not defined. In + this case, it is the responsibility of the user to create a temporary object and + move or copy it. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns contents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::error.3 b/man/std::expected::error.3 new file mode 100644 index 000000000..f101693e0 --- /dev/null +++ b/man/std::expected::error.3 @@ -0,0 +1,38 @@ +.TH std::expected::error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::error \- std::expected::error + +.SH Synopsis + constexpr const E& error() const& noexcept; \fB(1)\fP (since C++23) + constexpr E& error() & noexcept; \fB(2)\fP (since C++23) + constexpr const E&& error() const&& noexcept; \fB(3)\fP (since C++23) + constexpr E&& error() && noexcept; \fB(4)\fP (since C++23) + + Accesses the unexpected value contained in *this. + + The behavior is undefined if this->has_value() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the unexpected value contained in *this. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator-> accesses the expected value + operator* \fI(public member function)\fP + value returns the expected value + \fI(public member function)\fP + operator bool checks whether the object contains an expected value + has_value \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::expected.3 b/man/std::expected::expected.3 new file mode 100644 index 000000000..25c2484d9 --- /dev/null +++ b/man/std::expected::expected.3 @@ -0,0 +1,206 @@ +.TH std::expected::expected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::expected \- std::expected::expected + +.SH Synopsis + constexpr expected(); \fB(1)\fP (since C++23) + constexpr expected( const expected& other ); \fB(2)\fP (since C++23) + constexpr expected( expected&& other ) noexcept(/* see below \fB(3)\fP (since C++23) + */); + template< class U, class G > + constexpr explicit(/* see below */) expected( const expected& other ); + template< class U, class G > + constexpr explicit(/* see below */) expected( expected&& \fB(5)\fP (since C++23) + other ); + template< class U = T > (since C++23) + constexpr explicit(!std::is_convertible_v) expected( U&& \fB(6)\fP (T is not cv + v ); void) + template< class G > + + constexpr explicit(!std::is_convertible_v) \fB(7)\fP (since C++23) + + expected( const std::unexpected& e ); + template< class G > + + constexpr explicit(!std::is_convertible_v) \fB(8)\fP (since C++23) + + expected( std::unexpected&& e ); + template< class... Args > (since C++23) + constexpr explicit expected( std::in_place_t, Args&&... args ); \fB(9)\fP (T is not cv + void) + template< class U, class... Args > + (since C++23) + constexpr explicit expected( std::in_place_t, \fB(10)\fP (T is not cv + void) + std::initializer_list il, + Args&&... args ); + constexpr explicit expected( std::in_place_t ) noexcept; \fB(11)\fP (since C++23) + (T is cv void) + template< class... Args > \fB(12)\fP (since C++23) + constexpr explicit expected( std::unexpect_t, Args&&... args ); + template< class U, class... Args > + + constexpr explicit expected( std::unexpect_t, \fB(13)\fP (since C++23) + + std::initializer_list il, + Args&&... args ); + + Constructs a new expected object. + + 1) Default constructor. If T is not (possibly cv-qualified) void, constructs an + object that contains an expected value, which is value-initialized. + After construction, has_value() returns true. + This overload participates in overload resolution only if T is (possibly + cv-qualified) void or std::is_default_constructible_v is true. + 2) Copy constructor. If other.has_value() is false, the new object contains an + unexpected value, which is direct-initialized from other.error(). Otherwise, if T is + not (possibly cv-qualified) void, the new object contains an expected value, which + is direct-initialized from *other. + After construction, has_value() is equal to other.has_value(). + This constructor is defined as deleted unless + * either T is (possibly cv-qualified) void, or std::is_copy_constructible_v is + true, and + * std::is_copy_constructible_v is true. + This constructor is trivial if + * either T is (possibly cv-qualified) void, or + std::is_trivially_copy_constructible_v is true, and + * std::is_trivially_copy_constructible_v is true. + 3) Move constructor. If other.has_value() is false, the new object contains an + unexpected value, which is direct-initialized from std::move(other.error()). + Otherwise, if T is not (possibly cv-qualified) void, the new object contains an + expected value, which is direct-initialized from std::move(*other). + After construction, has_value() is equal to other.has_value(). + This constructor participates in overload resolution only if + * either T is (possibly cv-qualified) void, or std::is_move_constructible_v is + true, and + * std::is_move_constructible_v is true. + This constructor is trivial if + * std::is_trivially_move_constructible_v is true, and + * std::is_trivially_move_constructible_v is true. + 4,5) Let + * UF be std::add_lvalue_reference_t for \fB(4)\fP and U for \fB(5)\fP, and + * GF be const G& for \fB(4)\fP and G for \fB(5)\fP. + If other.has_value() is false, the new object contains an unexpected value, which is + direct-initialized from std::forward(other.error()). Otherwise, if T is not + (possibly cv-qualified) void, the new object contains an expected value, which is + direct-initialized from std::forward(*other). + After construction, has_value() is equal to other.has_value(). + Each of these constructors does not participate in overload resolution unless the + following conditions are met respectively: + * Either + * T is (possibly cv-qualified) void, and std::is_void_v is true, or + * std::is_constructible_v is true. + * std::is_constructible_v is true. + * If T is not (possibly cv-qualified) bool, T is not constructible or convertible + from any expression of type (possibly const) std::expected, i.e., the + following 8 values are all false: + * std::is_constructible_v& + * std::is_constructible_v + * std::is_constructible_v& + * std::is_constructible_v + * std::is_convertible_v&, T> + * std::is_convertible_v, T> + * std::is_convertible_v&, T> + * std::is_convertible_v, T> + * std::unexpected is not constructible from any expression of type (possibly + const) std::expected, i.e., the following 4 values are all false: + * std::is_constructible_v, std::expected& + * std::is_constructible_v, std::expected + * std::is_constructible_v, const std::expected& + * std::is_constructible_v, const std::expected + These constructors are explicit if std::is_convertible_v or + std::is_convertible_v is false. + 6) Constructs an object that contains an expected value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T with the + expression std::forward(v). + After construction, has_value() returns true. + This constructor does not participate in overload resolution unless the following + conditions are met: + * T is not (possibly cv-qualified) void. + * std::is_same_v, std::in_place_t> is false. + * std::is_same_v> is false. + * std::is_constructible_v is true. + * std::remove_cvref_t is not a specialization of std::unexpected. + * If T is (possibly cv-qualified) bool, std::remove_cvref_t is not a + specialization of std::expected. + 7,8) Let GF be const G& for \fB(7)\fP and G for \fB(8)\fP. Constructs an object that contains an + unexpected value, which is direct-initialized from std::forward(e.error()). + After construction, has_value() returns false. + These overloads participate in overload resolution only if + std::is_constructible_v is true. + 9) Constructs an object that contains an expected value, which is direct-initialized + from the arguments std::forward(args).... + After construction, has_value() returns true. + This overload participates in overload resolution only if std::is_constructible_v is true. + 10) Constructs an object that contains an expected value, which is + direct-initialized from the arguments il, std::forward(args).... + After construction, has_value() returns true. + This overload participates in overload resolution only if std::is_constructible_v&, Args...> is true. + 11) Constructs an object such that after construction, has_value() returns true. + 12) Constructs an object that contains an unexpected value, which is + direct-initialized from the arguments std::forward(args).... + After construction, has_value() returns false. + This overload participates in overload resolution only if std::is_constructible_v is true. + 13) Constructs an object that contains an unexpected value, which is + direct-initialized from the arguments il, std::forward(args).... + After construction, has_value() returns false. + This overload participates in overload resolution only if std::is_constructible_v&, Args...> is true. + +.SH Parameters + + other - another expected object whose contained value is copied + e - std::unexpected object whose contained value is copied + v - value with which to initialize the contained value + args... - arguments with which to initialize the contained value + il - initializer list with which to initialize the contained value + +.SH Exceptions + + 1) Throws any exception thrown by the constructor of T. + If T is (possibly cv-qualified) void, + noexcept specification: + noexcept + + 2) Throws any exception thrown by the constructor of T or E. + 3) If T is (possibly cv-qualified) void, + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v) + Otherwise, + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v + && std::is_nothrow_move_constructible_v) + 4,5) Throws any exception thrown by the constructor of T or E. + 6) Throws any exception thrown by the constructor of T. + 7,8) Throws any exception thrown by the constructor of E. + 9,10) Throws any exception thrown by the constructor of T. + 12,13) Throws any exception thrown by the constructor of E. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + unexpected represented as an unexpected value + (C++23) \fI(class template)\fP + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP + unexpect in-place construction tag for unexpected value in expected + unexpect_t (tag) + (C++23) + +.SH Categories: + * unconditionally noexcept + * conditionally noexcept + * Todo no example diff --git a/man/std::expected::operator->,std::expected::operator*.3 b/man/std::expected::operator->,std::expected::operator*.3 new file mode 100644 index 000000000..18b8a49d0 --- /dev/null +++ b/man/std::expected::operator->,std::expected::operator*.3 @@ -0,0 +1,88 @@ +.TH std::expected::operator->,std::expected::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::operator->,std::expected::operator* \- std::expected::operator->,std::expected::operator* + +.SH Synopsis + T is not cv void + constexpr const T* operator->() const noexcept; \fB(1)\fP (since C++23) + constexpr T* operator->() noexcept; \fB(1)\fP (since C++23) + constexpr const T& operator*() const& noexcept; \fB(2)\fP (since C++23) + constexpr T& operator*() & noexcept; \fB(2)\fP (since C++23) + constexpr const T&& operator*() const&& noexcept; \fB(2)\fP (since C++23) + constexpr T&& operator*() && noexcept; \fB(2)\fP (since C++23) + T is cv void + constexpr void operator*() const noexcept; \fB(3)\fP (since C++23) + + Accesses the expected value contained in *this. + + 1) Returns a pointer to the contained value. + 2) Returns a reference to the contained value. + 3) Returns nothing. + + The behavior is undefined if this->has_value() is false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer or reference to the contained value. + +.SH Notes + + These operators do not check whether the optional contains a value! You can do so + manually by using has_value() or simply operator bool(). Alternatively, if checked + access is needed, value() or value_or() may be used. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using namespace std::string_literals; + + std::expected ex1 = 6; + assert(*ex1 == 6); + + *ex1 = 9; + assert(*ex1 == 9); + + ex1 = std::unexpected("error"s); + // *ex1 = 13 // UB, ex1 contains "unexpected" value + assert(ex1.value_or(42) == 42); + + std::expected ex2 = "Moon"s; + std::cout << "ex2: " << std::quoted(*ex2) << ", size: " << ex2->size() << '\\n'; + + // You can "take" the contained value by calling operator* on an rvalue to expected + + auto taken = *std::move(ex2); + std::cout << "taken: " << std::quoted(taken) << "\\n" + "ex2: " << std::quoted(*ex2) << ", size: " << ex2->size() << '\\n'; + } + +.SH Possible output: + + ex2: "Moon", size: 4 + taken: "Moon" + ex2: "", size: 0 + +.SH See also + + value returns the expected value + \fI(public member function)\fP + value_or returns the expected value if present, another value otherwise + \fI(public member function)\fP + operator bool checks whether the object contains an expected value + has_value \fI(public member function)\fP + error returns the unexpected value + \fI(public member function)\fP diff --git a/man/std::expected::operator=.3 b/man/std::expected::operator=.3 new file mode 100644 index 000000000..58f97c721 --- /dev/null +++ b/man/std::expected::operator=.3 @@ -0,0 +1,169 @@ +.TH std::expected::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::operator= \- std::expected::operator= + +.SH Synopsis + constexpr expected& operator=( const expected& other ); \fB(1)\fP (since C++23) + constexpr expected& operator=( expected&& other ) \fB(2)\fP (since C++23) + noexcept(/*see below*/); + template< class U = T > \fB(3)\fP (since C++23) + constexpr expected& operator=( U&& v ); (T is not cv void) + template< class G > \fB(4)\fP (since C++23) + constexpr expected& operator=( const unexpected& other ); + template< class G > \fB(5)\fP (since C++23) + constexpr expected& operator=( unexpected&& other ); + + Assigns a new value to an existing expected object. + + 1,2) Assigns the state of other. + * If this->has_value() equals other.has_value(), assigns the value contained in + other. Does nothing if T is (possibly cv-qualified) void and other.has_value() + is true. + * Otherwise, destroys the currently contained value (does nothing if + this->has_value() is true and T is (possibly cv-qualified) void), and makes + *this contain a copy of the value contained in other. + + If other.has_value() is true and T is (possibly cv-qualified) void, does not + construct the new value. Otherwise, the new value is copy-constructed \fB(1)\fP or + move-constructed \fB(2)\fP from *other or other.error(), as appropriate. If an exception + is thrown, the old value is retained; *this does not become valueless. + + If no exception was thrown, after assignment, has_value() is equal to + other.has_value(). + + * Overload \fB(1)\fP is defined as deleted unless + * either T is (possibly cv-qualified) void or std::is_copy_assignable_v is + true, and + * either T is (possibly cv-qualified) void or std::is_copy_constructible_v + is true, and + * std::is_copy_assignable_v is true, and + * std::is_copy_constructible_v is true, and + * at least one of the following is true: + * T is (possibly cv-qualified) void + * std::is_nothrow_move_constructible_v + * std::is_nothrow_move_constructible_v + * Overload \fB(2)\fP participates in overload resolution only if + * either T is (possibly cv-qualified) void or std::is_move_assignable_v is + true, and + * either T is (possibly cv-qualified) void or std::is_move_constructible_v + is true, and + * std::is_move_assignable_v is true, and + * std::is_move_constructible_v is true, and + * at least one of the following is true: + * T is (possibly cv-qualified) void + * std::is_nothrow_move_constructible_v + * std::is_nothrow_move_constructible_v + 3) Assigns from expected value. + * If this->has_value() is true, equivalent to **this = std::forward(v). + * Otherwise, destroys the value contained in *this, and makes *this contain a + value initialized from std::forward(v). If an exception is thrown, the old + value is retained; *this does not become valueless. + + If no exception was thrown, after assignment, this->has_value() is true. + + * This overload participates in overload resolution only if + * std::is_same_v> is false, and + * std::remove_cvref_t is not a specialization of std::unexpected, and + * std::is_constructible_v is true, and + * std::is_assignable_v is true, and + * at least one of the following is true: + * std::is_nothrow_constructible_v + * std::is_nothrow_move_constructible_v + * std::is_nothrow_move_constructible_v + 4,5) Assigns from unexpected value. + + Let GF be const G& for overload \fB(4)\fP, and G for overload \fB(5)\fP. + + * If this->has_value() is true, destroys the value contained in *this (does + nothing if T is (possibly cv-qualified) void), and makes *this contain a value + initialized from std::forward(e.error()). If an exception is thrown, the old + value is retained; *this does not become valueless. + * Otherwise, equivalent to this->error() = std::forward(e.error()). + + If no exception was thrown, after assignment, this->has_value() is false. + + * This overload participates in overload resolution only if + * std::is_constructible_v is true, and + * std::is_assignable_v is true, and + * at least one of the following is true: + * T is (possibly cv-qualified) void + * std::is_nothrow_constructible_v + * std::is_nothrow_move_constructible_v + * std::is_nothrow_move_constructible_v + + In all cases, if T is not (possibly cv-qualified) void, the destruction of old value + and construction of new value is performed as if by the following exposition-only + function reinit_expected. + + template + constexpr void reinit_expected(NewType& new_val, OldType& old_val, Args&&... args) + { + if constexpr (std::is_nothrow_constructible_v) + { + std::destroy_at(std::addressof(old_val)); + std::construct_at(std::addressof(new_val), std::forward(args)...); + } + else if constexpr (std::is_nothrow_move_constructible_v) + { + NewType temp(std::forward(args)...); + std::destroy_at(std::addressof(old_val)); + std::construct_at(std::addressof(new_val), std::move(temp)); + } + else + { + OldType temp(std::move(old_val)); + std::destroy_at(std::addressof(old_val)); + try + { + std::construct_at(std::addressof(new_val), std::forward(args)...); + } + catch (...) + { + std::construct_at(std::addressof(old_val), std::move(temp)); + throw; + } + } + } + +.SH Parameters + + other - another expected object whose contained value to assign + value - value to assign to the contained value + e - std::unexpected object whose contained value to assign + +.SH Return value + + *this + +.SH Exceptions + + 1) Throws any exception thrown by the copy constructor or copy assignment operator + of T or E. + 2) If T is (possibly cv-qualified) void, + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v && + std::is_nothrow_move_assignable_v) + Otherwise, + noexcept specification: + noexcept( + + std::is_nothrow_move_constructible_v && std::is_nothrow_move_assignable_v + && + + std::is_nothrow_move_constructible_v && std::is_nothrow_move_assignable_v) + 3) Throws any exception thrown by the constructor or assignment operator of T. + 4,5) Throws any exception thrown by the constructor or assignment operator of E. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace constructs the expected value in-place + \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::expected::operatorbool,std::expected::has_value.3 b/man/std::expected::operatorbool,std::expected::has_value.3 new file mode 100644 index 000000000..c00041247 --- /dev/null +++ b/man/std::expected::operatorbool,std::expected::has_value.3 @@ -0,0 +1,38 @@ +.TH std::expected::operatorbool,std::expected::has_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::operatorbool,std::expected::has_value \- std::expected::operatorbool,std::expected::has_value + +.SH Synopsis + constexpr explicit operator bool() const noexcept; (since C++23) + constexpr bool has_value() const noexcept; (since C++23) + + Checks whether *this contains an expected value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if *this contains an expected value, false if *this contains an unexpected + value. + +.SH Notes + + A std::expected object is never empty. If has_value() returns true, operator* can be + used to access the contained value; otherwise, error() can be used. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator-> accesses the expected value + operator* \fI(public member function)\fP + error returns the unexpected value + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::or_else.3 b/man/std::expected::or_else.3 new file mode 100644 index 000000000..caf65e730 --- /dev/null +++ b/man/std::expected::or_else.3 @@ -0,0 +1,92 @@ +.TH std::expected::or_else 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::or_else \- std::expected::or_else + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr auto or_else( F&& f ) &; + template< class F > \fB(2)\fP (since C++23) + constexpr auto or_else( F&& f ) const&; + template< class F > \fB(3)\fP (since C++23) + constexpr auto or_else( F&& f ) &&; + template< class F > \fB(4)\fP (since C++23) + constexpr auto or_else( F&& f ) const&&; + + If *this contains an unexpected value, invokes f with the argument error() and + returns its result; otherwise, returns a std::expected object that contains a copy + of the contained expected value (obtained from operator*). + + 1,2) Given type G as std::remove_cvref_t>. + If G is not a specialization of std::expected, or std::is_same_v + is false, the program is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if constexpr (std::is_void_v) + return G(); + else + return G(std::in_place, **this); + } + else + return std::invoke(std::forward(f), error()); + + These overloads participate in overload resolution only if std::is_void_v or + std::is_constructible_v is true. + 3,4) Given type G as std::remove_cvref_t>. + If G is not a specialization of std::expected, or std::is_same_v + is false, the program is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if constexpr (std::is_void_v) + return G(); + else + return G(std::in_place, std::move(**this)); + } + else + return std::invoke(std::forward(f), std::move(error())); + + These overloads participate in overload resolution only if std::is_void_v or + std::is_constructible_v is true. + +.SH Parameters + + f - a suitable function or Callable object that returns a std::expected + +.SH Return value + + The result of f, or a std::expected object that contains a copy of the expected + value, as described above. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_expected 202211L (C++23) Monadic functions for std::expected + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3938 C++23 or_else was ill-formed if T is not (possibly made well-formed + cv-qualified) void and E is not copyable + +.SH See also + + returns the expected itself if it contains an expected value; + transform_error otherwise, returns an expected containing the transformed unexpected + value + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::swap.3 b/man/std::expected::swap.3 new file mode 100644 index 000000000..a8ed80c45 --- /dev/null +++ b/man/std::expected::swap.3 @@ -0,0 +1,111 @@ +.TH std::expected::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::swap \- std::expected::swap + +.SH Synopsis + constexpr void swap( expected& other ) noexcept(/*see below*/); (since C++23) + + Swaps the contents with those of other. + + * If both this->has_value() and other.has_value() are true: + + * If T is (possibly cv-qualified) void, no effects. + * Otherwise, equivalent to using std::swap; swap(**this, *other);. + * If both this->has_value() and other.has_value() are false, equivalent to + using std::swap; swap(this->error(), other.error());. + * If this->has_value() is false and other.has_value() is true, calls + other.swap(*this). + * If this->has_value() is true and other.has_value() is false, + + * If T is (possibly cv-qualified) void, let unex be the member that represents the + unexpected value, equivalent to: + + std::construct_at(std::addressof(unex), std::move(other.unex)); + std::destroy_at(std::addressof(other.unex)); + + * Otherwise, let val be the member that represents the expected value and unex be + the member that represents the unexpected value, equivalent to: + + if constexpr (std::is_nothrow_move_constructible_v) { + E temp(std::move(other.unex)); + std::destroy_at(std::addressof(other.unex)); + try { + std::construct_at(std::addressof(other.val), std::move(val)); + std::destroy_at(std::addressof(val)); + std::construct_at(std::addressof(unex), std::move(temp)); + } catch(...) { + std::construct_at(std::addressof(other.unex), std::move(temp)); + throw; + } + } else { + T temp(std::move(val)); + std::destroy_at(std::addressof(val)); + try { + std::construct_at(std::addressof(unex), std::move(other.unex)); + std::destroy_at(std::addressof(other.unex)); + std::construct_at(std::addressof(other.val), std::move(temp)); + } catch(...) { + std::construct_at(std::addressof(val), std::move(temp)); + throw; + } + } + + * In either case, if no exception was thrown, after swap, this->has_value() is + false, and other.has_value() is true. + + This function participates in overload resolution only if + + * either T is (possibly cv-qualified) void, or std::is_swappable_v is true, and + * std::is_swappable_v is true, and + * either T is (possibly cv-qualified) void, or std::is_move_constructible_v is + true, and + * std::is_move_constructible_v is true, and + * at least one of the following is true: + * T is (possibly cv-qualified) void + * std::is_nothrow_move_constructible_v + * std::is_nothrow_move_constructible_v + +.SH Parameters + + other - the optional object to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + If T is (possibly cv-qualified) void, + noexcept specification: + noexcept( + + std::is_nothrow_move_constructible_v && std::is_nothrow_swappable_v + + ) + Otherwise, + noexcept specification: + noexcept( + + std::is_nothrow_move_constructible_v && std::is_nothrow_swappable_v && + std::is_nothrow_move_constructible_v && std::is_nothrow_swappable_v + + ) + + In the case of thrown exception, the states of the contained values of *this and + other are determined by the exception safety guarantees of swap or T's and E's move + constructor, whichever is called. For both *this and other, if the object contained + an expected value, it is left containing an expected value, and the other way round. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap(std::expected) specializes the std::swap algorithm + (C++23) \fI(function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::expected::transform.3 b/man/std::expected::transform.3 new file mode 100644 index 000000000..0609a58e2 --- /dev/null +++ b/man/std::expected::transform.3 @@ -0,0 +1,112 @@ +.TH std::expected::transform 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::transform \- std::expected::transform + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr auto transform( F&& f ) &; + template< class F > \fB(2)\fP (since C++23) + constexpr auto transform( F&& f ) const&; + template< class F > \fB(3)\fP (since C++23) + constexpr auto transform( F&& f ) &&; + template< class F > \fB(4)\fP (since C++23) + constexpr auto transform( F&& f ) const&&; + + If *this contains an expected value, invokes f and returns a std::expected object + that contains its result; otherwise, returns a std::expected object that contains a + copy of error(). + + If T is not (possibly cv-qualified) void, the contained value (obtained from + operator*) is passed as an argument to f; otherwise f takes no argument. + + 1,2) Given type U as + * std::remove_cv_t> if T is (possibly cv-qualified) void, + or + * std::remove_cv_t> otherwise, + and expression /* invoke-expr */ as + * std::invoke(std::forward(f)) if T is (possibly cv-qualified) void, or + * std::invoke(std::forward(f), **this) otherwise. + If U is not a valid value type for std::expected, or U u(/* invoke-expr */); is + ill-formed when std::is_void_v is false, the program is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if constexpr (std::is_void_v) + { + /* invoke-expr */; + return std::expected(); + } + else + // the returned std::expected object contains an expected value, + // which is direct-non-list-initialized with /* invoke-expr */ + return /* an std::expected object */; + } + else + return std::expected(std::unexpect, error()); + + These overloads participate in overload resolution only if + std::is_constructible_v is true. + 3,4) Given type U as + * std::remove_cv_t> if T is (possibly cv-qualified) void, + or + * std::remove_cv_t> + otherwise, + and expression /* invoke-expr */ as + * std::invoke(std::forward(f)) if T is (possibly cv-qualified) void, or + * std::invoke(std::forward(f), std::move(**this)) otherwise. + If U is not a valid value type for std::expected, or U u(/* invoke-expr */); is + ill-formed when std::is_void_v is false, the program is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if constexpr (std::is_void_v) + { + /* invoke-expr */; + return std::expected(); + } + else + // the returned std::expected object contains an expected value, + // which is direct-non-list-initialized with /* invoke-expr */ + return /* an std::expected object */; + } + else + return std::expected(std::unexpect, std::move(error())); + + These overloads participate in overload resolution only if + std::is_constructible_v is true. + +.SH Parameters + + f - a suitable function or Callable object whose call signature returns a + non-reference type + +.SH Return value + + A std::expected object containing either the result of f or an error value, as + described above. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3938 C++23 transform was ill-formed if T is not (possibly made well-formed + cv-qualified) void and E is not copyable + +.SH See also + + returns the expected itself if it contains an expected value; + transform_error otherwise, returns an expected containing the transformed unexpected + value + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::transform_error.3 b/man/std::expected::transform_error.3 new file mode 100644 index 000000000..4871a2f70 --- /dev/null +++ b/man/std::expected::transform_error.3 @@ -0,0 +1,99 @@ +.TH std::expected::transform_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::transform_error \- std::expected::transform_error + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr auto transform_error( F&& f ) &; + template< class F > \fB(2)\fP (since C++23) + constexpr auto transform_error( F&& f ) const&; + template< class F > \fB(3)\fP (since C++23) + constexpr auto transform_error( F&& f ) &&; + template< class F > \fB(4)\fP (since C++23) + constexpr auto transform_error( F&& f ) const&&; + + If *this contains an error value, invokes f with the argument error() and returns a + std::expected object that contains its result; otherwise, returns a std::expected + object that contains a copy of the contained expected value (obtained from + operator*). + + 1,2) Given type G as std::remove_cv_t>. + If G is not a valid template argument for std::unexpected, or G + g(std::invoke(std::forward(f), error())); is ill-formed, the program is + ill-formed. + The effect is equivalent to + + if (has_value()) + { + if (std::is_void_v) + return std::expected(); + else + return std::expected(std::in_place, **this); + } + else + // the returned std::expected object contains an unexpected value, + // which is direct-non-list-initialized with + // std::invoke(std::forward(f), error()) + return /* an std::expected object */; + + These overloads participate in overload resolution only if std::is_void_v or + std::is_constructible_v is true. + 3,4) Given type G as std::remove_cv_t>. + If G is not a valid template argument for std::unexpected, or G + g(std::invoke(std::forward(f), std::move(error()))); is ill-formed, the program + is ill-formed. + The effect is equivalent to + + if (has_value()) + { + if (std::is_void_v) + return std::expected(); + else + return std::expected(std::in_place, std::move(**this)); + } + else + // the returned std::expected object contains an unexpected value, + // which is direct-non-list-initialized with + // std::invoke(std::forward(f), std::move(error())) + return /* an std::expected object */; + + These overloads participate in overload resolution only if std::is_void_v or + std::is_constructible_v is true. + +.SH Parameters + + f - a suitable function or Callable object whose call signature returns a + non-reference type + +.SH Return value + + A std::expected object containing either the result of f or an expected value, as + described above. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + transform_error was ill-formed if T is not + LWG 3938 C++23 (possibly cv-qualified) void and E is not made well-formed + copyable + +.SH See also + + returns the expected itself if it contains an expected value; otherwise, + or_else returns the result of the given function on the unexpected value + \fI(public member function)\fP + returns an expected containing the transformed expected value if it + transform exists; otherwise, returns the expected itself + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::value.3 b/man/std::expected::value.3 new file mode 100644 index 000000000..7dbc75bf7 --- /dev/null +++ b/man/std::expected::value.3 @@ -0,0 +1,70 @@ +.TH std::expected::value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::value \- std::expected::value + +.SH Synopsis + T is not (possibly cv-qualified) void + constexpr T& value() &; \fB(1)\fP (since C++23) + constexpr const T& value() const&; \fB(2)\fP (since C++23) + constexpr T&& value() &&; \fB(3)\fP (since C++23) + constexpr const T&& value() const&&; \fB(4)\fP (since C++23) + T is (possibly cv-qualified) void + constexpr void value() const&; \fB(5)\fP (since C++23) + constexpr void value() &&; \fB(6)\fP (since C++23) + + If *this contains an expected value, returns a reference to the contained value. + Returns nothing if T is (possibly cv-qualified) void. + + Otherwise, throws an exception of type std::bad_expected_access> + that contains a copy of error(). + + 1,2) If std::is_copy_constructible_v is false, the program is ill-formed. + 3,4) If std::is_copy_constructible_v or std::is_constructible_v is false, the program is ill-formed. + 5) If std::is_copy_constructible_v is false, the program is ill-formed. + 6) If std::is_move_constructible_v is false, the program is ill-formed. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1-4) The expected value contained in *this. + 5,6) \fI(none)\fP + +.SH Exceptions + + 1,2,5) Throws std::bad_expected_access(std::as_const(error())) if *this contains an + unexpected value. + 3,4,6) Throws std::bad_expected_access(std::move(error())) if *this contains an + unexpected value. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3940 C++23 E was not required to be required + copy/move-constructible for overloads (5,6) + +.SH See also + + value_or returns the expected value if present, another value otherwise + \fI(public member function)\fP + operator-> accesses the expected value + operator* \fI(public member function)\fP + error returns the unexpected value + \fI(public member function)\fP + bad_expected_access exception indicating checked access to an expected that contains + (C++23) an unexpected value + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::value_or.3 b/man/std::expected::value_or.3 new file mode 100644 index 000000000..82f67a7fc --- /dev/null +++ b/man/std::expected::value_or.3 @@ -0,0 +1,53 @@ +.TH std::expected::value_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::value_or \- std::expected::value_or + +.SH Synopsis + template< class U > \fB(1)\fP (since C++23) + constexpr T value_or( U&& default_value ) const&; + template< class U > \fB(2)\fP (since C++23) + constexpr T value_or( U&& default_value ) &&; + + Returns the contained value if *this contains an expected value, otherwise returns + default_value. + + 1) Returns bool(*this) ? **this : static_cast(std::forward(default_value)) + 2) Returns bool(*this) ? std::move(**this) : + static_cast(std::forward(default_value)) + +.SH Parameters + + default_value - the value to use in case *this does not contain an expected value +.SH Type requirements + - + T must meet the requirements of CopyConstructible in order to use overload \fB(1)\fP. + - + T must meet the requirements of MoveConstructible in order to use overload \fB(2)\fP. + - + U&& must be convertible to T + +.SH Return value + + The currently contained value if *this contains an expected value, or default_value + otherwise. + +.SH Exceptions + + Any exception thrown by the selected constructor of the return value T. + +.SH Notes + + If T is (possibly cv-qualified) void, this member is not declared. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + value returns the expected value + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::expected::~expected.3 b/man/std::expected::~expected.3 new file mode 100644 index 000000000..cf6d19801 --- /dev/null +++ b/man/std::expected::~expected.3 @@ -0,0 +1,24 @@ +.TH std::expected::~expected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expected::~expected \- std::expected::~expected + +.SH Synopsis + constexpr ~expected(); (since C++23) + + Destroys the currently contained value. That is, if has_value() is false, destroys + the unexpected value; otherwise, if T is not (possibly cv-qualified) void, destroys + the expected value. + + This destructor is trivial if + + * either T is (possibly cv-qualified) void, or std::is_trivially_destructible_v + is true, and + * std::is_trivially_destructible_v is true. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::all_of,std::experimental::any_of,std::experimental::none_of,.3 b/man/std::experimental::all_of,std::experimental::any_of,std::experimental::none_of,.3 new file mode 100644 index 000000000..989e18852 --- /dev/null +++ b/man/std::experimental::all_of,std::experimental::any_of,std::experimental::none_of,.3 @@ -0,0 +1,71 @@ +.TH std::experimental::all_of,std::experimental::any_of,std::experimental::none_of, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::all_of,std::experimental::any_of,std::experimental::none_of, \- std::experimental::all_of,std::experimental::any_of,std::experimental::none_of, + +.SH Synopsis + + Defined in header + template< class T, class Abi > \fB(1)\fP (parallelism TS v2) + bool all_of( const simd_mask& k ); + template< class T, class Abi > \fB(2)\fP (parallelism TS v2) + bool any_of( const simd_mask& k ); + template< class T, class Abi > \fB(3)\fP (parallelism TS v2) + bool none_of( const simd_mask& k ); + template< class T, class Abi > \fB(4)\fP (parallelism TS v2) + bool some_of( const simd_mask& k ); + + 1) Returns true if all values in k are true. + 2) Returns true if at least one value in k is true. + 3) Returns true if all values in k are false. + 4) Returns true if at least one value in k is true but not all values in k are true. + +.SH Parameters + + k - the simd_mask to apply the reduction to + +.SH Return value + + The boolean result of the horizontal reduction. + +.SH Example + + +// Run this code + + #include + #include + + namespace stq = std::experimental; + + int main() + { + using mask = stq::fixed_size_simd_mask; + + mask mask1{false}; // = {0, 0, 0, 0} + assert + ( + stq::none_of(mask1) == true && + stq::any_of(mask1) == false && + stq::some_of(mask1) == false && + stq::all_of(mask1) == false + ); + + mask mask2{true}; // = {1, 1, 1, 1} + assert + ( + stq::none_of(mask2) == false && + stq::any_of(mask2) == true && + stq::some_of(mask2) == false && + stq::all_of(mask2) == true + ); + + mask mask3{true}; + mask3[0] = mask3[1] = false; // mask3 = {0, 0, 1, 1} + assert + ( + stq::none_of(mask3) == false && + stq::any_of(mask3) == true && + stq::some_of(mask3) == true && + stq::all_of(mask3) == false + ); + } diff --git a/man/std::experimental::any.3 b/man/std::experimental::any.3 new file mode 100644 index 000000000..5ba68a8fd --- /dev/null +++ b/man/std::experimental::any.3 @@ -0,0 +1,56 @@ +.TH std::experimental::any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any \- std::experimental::any + +.SH Synopsis + Defined in header + class any; (library fundamentals TS) + + The class any describes a type-safe container for single values of any type. + + 1) An object of class any stores an instance of any type that satisfies the + constructor requirements or is empty, and this is referred to as the state of the + class any object. The stored instance is called the contained object. Two states are + equivalent if they are either both empty or if both are not empty and if the + contained objects are equivalent. + 2) The non-member any_cast functions provide type-safe access to the contained + object. + + Implementations are encouraged to avoid dynamic allocations for small objects, but + such an optimization may only be applied to types that for which + std::is_nothrow_move_constructible returns true. + +.SH Member functions + + constructor constructs an any object + \fI(public member function)\fP + operator= assigns an any object + \fI(public member function)\fP + destructor destroys an any object + \fI(public member function)\fP +.SH Modifiers + clear destroys contained object + \fI(public member function)\fP + swap swaps two any objects + \fI(public member function)\fP +.SH Observers + empty checks if object holds a value + \fI(public member function)\fP + type returns the typeid of the contained value + \fI(public member function)\fP + +.SH Non-member functions + + swap swaps two any instances + \fI(function)\fP + any_cast type-safe access to the contained object + \fI(function template)\fP + +.SH Helper classes + + bad_any_cast exception thrown by the value-returning forms of any_cast + (library fundamentals TS) on a type mismatch + \fI(class)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::any.3 b/man/std::experimental::any::any.3 new file mode 100644 index 000000000..2c24a6070 --- /dev/null +++ b/man/std::experimental::any::any.3 @@ -0,0 +1,46 @@ +.TH std::experimental::any::any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::any \- std::experimental::any::any + +.SH Synopsis + any() noexcept; \fB(1)\fP (library fundamentals TS) + any( const any& other ); \fB(2)\fP (library fundamentals TS) + any( any&& other ) noexcept; \fB(3)\fP (library fundamentals TS) + template \fB(4)\fP (library fundamentals TS) + any( ValueType&& value ); + + Constructs a new any object. + + 1) Constructs an empty object. + 2,3) Copies \fB(2)\fP or moves \fB(3)\fP content of other into a new instance, so that any + content is equivalent in both type and value to those of other prior to the + constructor call, or empty if other is empty. + 4) Constructs an object with initial content an object of type + std::decay_t, direct-initialized from std::forward(value). If + std::is_copy_constructible>::value is false, the program is + ill-formed. This overload participates in overload resolution only if + std::decay_t is not the same type as any. + +.SH Template parameters + + ValueType - contained value type +.SH Type requirements + - + std::decay_t must meet the requirements of CopyConstructible. + +.SH Parameters + + other - another any object to copy or move from + value - value to initialize the contained value with + +.SH Exceptions + + 2,4) Throws any exception thrown by the constructor of the contained type. + +.SH See also + + operator= assigns an any object + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::clear.3 b/man/std::experimental::any::clear.3 new file mode 100644 index 000000000..f09f87d0c --- /dev/null +++ b/man/std::experimental::any::clear.3 @@ -0,0 +1,19 @@ +.TH std::experimental::any::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::clear \- std::experimental::any::clear + +.SH Synopsis + void clear() noexcept; (library fundamentals TS) + + If not empty, destroys the contained object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::empty.3 b/man/std::experimental::any::empty.3 new file mode 100644 index 000000000..c2339c996 --- /dev/null +++ b/man/std::experimental::any::empty.3 @@ -0,0 +1,19 @@ +.TH std::experimental::any::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::empty \- std::experimental::any::empty + +.SH Synopsis + bool empty() const noexcept; (library fundamentals TS) + + Checks whether the object contains a value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if instance is empty, otherwise false. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::operator=.3 b/man/std::experimental::any::operator=.3 new file mode 100644 index 000000000..f2fc17b01 --- /dev/null +++ b/man/std::experimental::any::operator=.3 @@ -0,0 +1,48 @@ +.TH std::experimental::any::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::operator= \- std::experimental::any::operator= + +.SH Synopsis + any& operator=( const any& rhs ); \fB(1)\fP (library fundamentals TS) + any& operator=( any&& rhs ) noexcept; \fB(2)\fP (library fundamentals TS) + template< typename ValueType > \fB(3)\fP (library fundamentals TS) + any& operator=( ValueType&& rhs ); + + Assigns contents to the contained value. + + 1) Assigns by copying the state of rhs, as if by any(rhs).swap(*this). + 2) Assigns by moving the state of rhs, as if by any(std::move(rhs)).swap(*this). rhs + is left in a valid but unspecified state after the assignment. + 3) Assigns the type and value of rhs, as if by + any(std::forward(rhs)).swap(*this). If + std::is_copy_constructible>::value is false, the program is + ill-formed. This overload participates in overload resolution only if + std::decay_t is not the same type as any. + +.SH Template parameters + + ValueType - contained value type +.SH Type requirements + - + std::decay_t must meet the requirements of CopyConstructible. + +.SH Parameters + + rhs - object whose contained value to assign + +.SH Return value + + *this + +.SH Exceptions + + 1,3) Throws bad_alloc or any exception thrown by the constructor of the contained + type. If an exception is thrown, there are no effects \fI(strong exception guarantee)\fP. + +.SH See also + + constructor constructs an any object + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::swap.3 b/man/std::experimental::any::swap.3 new file mode 100644 index 000000000..223f65f55 --- /dev/null +++ b/man/std::experimental::any::swap.3 @@ -0,0 +1,19 @@ +.TH std::experimental::any::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::swap \- std::experimental::any::swap + +.SH Synopsis + void swap(any& other) noexcept; (library fundamentals TS) + + Swaps the content of two any objects. + +.SH Parameters + + other - object to swap with + +.SH Return value + + \fI(none)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::type.3 b/man/std::experimental::any::type.3 new file mode 100644 index 000000000..100495920 --- /dev/null +++ b/man/std::experimental::any::type.3 @@ -0,0 +1,19 @@ +.TH std::experimental::any::type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::type \- std::experimental::any::type + +.SH Synopsis + const type_info& type() const noexcept; (library fundamentals TS) + + Queries the contained type. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The typeid of the contained value if instance is non-empty, otherwise typeid(void). + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any::~any.3 b/man/std::experimental::any::~any.3 new file mode 100644 index 000000000..7e7b9fdff --- /dev/null +++ b/man/std::experimental::any::~any.3 @@ -0,0 +1,16 @@ +.TH std::experimental::any::~any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any::~any \- std::experimental::any::~any + +.SH Synopsis + ~any(); (library fundamentals TS) + + Destroys the contained object, if any, as if by a call to clear(). + +.SH See also + + clear destroys contained object + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::any_cast.3 b/man/std::experimental::any_cast.3 new file mode 100644 index 000000000..00f912d9a --- /dev/null +++ b/man/std::experimental::any_cast.3 @@ -0,0 +1,41 @@ +.TH std::experimental::any_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::any_cast \- std::experimental::any_cast + +.SH Synopsis + template \fB(1)\fP (library fundamentals TS) + ValueType any_cast(const any& operand); + template \fB(2)\fP (library fundamentals TS) + ValueType any_cast(any& operand); + template \fB(3)\fP (library fundamentals TS) + ValueType any_cast(any&& operand); + template + const ValueType* any_cast(const any* operand) \fB(4)\fP (library fundamentals TS) + noexcept; + template \fB(5)\fP (library fundamentals TS) + ValueType* any_cast(any* operand) noexcept; + + Performs type-safe access to the contained object. + + For (1-3), the program is ill-formed if ValueType is not a reference and + std::is_copy_constructible::value is false. + +.SH Parameters + + operand - target any object + +.SH Return value + + 1) Returns + *any_cast>>(&operand). + 2,3) Returns *any_cast>(&operand). + 4,5) If operand is not a null pointer, and the typeid of the requested ValueType + matches that of the contents of operand, a pointer to the value contained by + operand, otherwise a null pointer. + +.SH Exceptions + + 1-3) Throws bad_any_cast if the typeid of the requested ValueType does not match + that of the contents of operand. +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::apply.3 b/man/std::experimental::apply.3 new file mode 100644 index 000000000..0cbd29f7c --- /dev/null +++ b/man/std::experimental::apply.3 @@ -0,0 +1,76 @@ +.TH std::experimental::apply 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::apply \- std::experimental::apply + +.SH Synopsis + Defined in header + template< class F, class Tuple > (library fundamentals TS) + constexpr decltype(auto) apply(F&& f, Tuple&& t); + + Invoke the Callable object f with a tuple of arguments. + +.SH Parameters + + f - Callable object to be invoked + t - tuple whose elements to be used as arguments to f + +.SH Return value + + What returned by f. + +.SH Possible implementation + + namespace detail + { + template + constexpr decltype(auto) apply_impl(F&& f, Tuple&& t, std::index_sequence) + { + return std::invoke(std::forward(f), std::get(std::forward(t))...); + // Note: std::invoke is a C++17 feature + } + } // namespace detail + + template + constexpr decltype(auto) apply(F&& f, Tuple&& t) + { + return detail::apply_impl(std::forward(f), std::forward(t), + std::make_index_sequence>>{}); + } + +.SH Example + + +// Run this code + + #include + #include + + template + void print_tuple(const std::tuple &tuple) + { + std::apply([](const auto&... elem) + { + ((std::cout << elem << '\\n'), ...); + }, tuple); + } + + int main() + { + const std::tuple t = std::make_tuple(5, 'a'); + print_tuple(t); + } + +.SH Output: + + 5 + a + +.SH See also + + make_tuple creates a tuple object of the type defined by the argument types + \fI(C++11)\fP \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::atomic_shared_ptr.3 b/man/std::experimental::atomic_shared_ptr.3 new file mode 100644 index 000000000..3e3b49979 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr.3 @@ -0,0 +1,35 @@ +.TH std::experimental::atomic_shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr \- std::experimental::atomic_shared_ptr + +.SH Synopsis + Defined in header + template< class T > (concurrency TS) + class atomic_shared_ptr; + + The class template atomic_shared_ptr provides thread-safe atomic pointer operations + over a std::shared_ptr. It provides a better alternative to the non-member + shared_ptr atomic access functions. + +.SH Member functions + + constructor constructs an atomic_shared_ptr object + \fI(public member function)\fP + operator= stores a value into an atomic_shared_ptr object + \fI(public member function)\fP + is_lock_free checks if the atomic_shared_ptr object is lock-free + \fI(public member function)\fP + atomically replaces the value of the atomic object with a + store non-atomic argument + \fI(public member function)\fP + load atomically obtains the value of the atomic object + \fI(public member function)\fP + operator shared_ptr loads a value from an atomic object + \fI(public member function)\fP + atomically replaces the value of the atomic object and + exchange obtains the value held previously + \fI(public member function)\fP + atomically compares the value of the atomic object with + compare_exchange_weak non-atomic argument and performs atomic exchange if equal or + compare_exchange_strong atomic load if not + \fI(public member function)\fP diff --git a/man/std::experimental::atomic_shared_ptr::atomic_shared_ptr.3 b/man/std::experimental::atomic_shared_ptr::atomic_shared_ptr.3 new file mode 100644 index 000000000..afd94a9f8 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::atomic_shared_ptr.3 @@ -0,0 +1,21 @@ +.TH std::experimental::atomic_shared_ptr::atomic_shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::atomic_shared_ptr \- std::experimental::atomic_shared_ptr::atomic_shared_ptr + +.SH Synopsis + constexpr atomic_shared_ptr() noexcept; \fB(1)\fP + constexpr atomic_shared_ptr( shared_ptr desired ) noexcept; \fB(2)\fP + atomic_shared_ptr( const atomic_shared_ptr& ) = delete; \fB(3)\fP + + Constructs a new atomic_shared_ptr object. + + 1) The default constructor initializes the object to an empty state. + 2) Initializes the underlying shared_ptr with desired. The initialization is not + atomic. + 3) Atomic variables are not CopyConstructible. + +.SH Parameters + + desired - value to initialize with + +.SH Exceptions diff --git a/man/std::experimental::atomic_shared_ptr::compare_exchange_strong,.3 b/man/std::experimental::atomic_shared_ptr::compare_exchange_strong,.3 new file mode 100644 index 000000000..e00848236 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::compare_exchange_strong,.3 @@ -0,0 +1,113 @@ +.TH std::experimental::atomic_shared_ptr::compare_exchange_strong, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::compare_exchange_strong, \- std::experimental::atomic_shared_ptr::compare_exchange_strong, + +.SH Synopsis + + bool compare_exchange_weak( std::shared_ptr& expected, const + std::shared_ptr& desired, \fB(1)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_weak( std::shared_ptr& expected, std::shared_ptr&& + desired, \fB(2)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_weak( std::shared_ptr& expected, const + std::shared_ptr& desired, \fB(3)\fP + std::memory_order order = std::memory_order_seq_cst + ) noexcept; + bool compare_exchange_weak( std::shared_ptr& expected, std::shared_ptr&& + desired, \fB(4)\fP + std::memory_order order = std::memory_order_seq_cst + ) noexcept; + bool compare_exchange_strong( std::shared_ptr& expected, const + std::shared_ptr& desired, \fB(5)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_strong( std::shared_ptr& expected, + std::shared_ptr&& desired, \fB(6)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_strong( std::shared_ptr& expected, const + std::shared_ptr& desired, \fB(7)\fP + std::memory_order order = + std::memory_order_seq_cst ) noexcept; + bool compare_exchange_strong( std::shared_ptr& expected, + std::shared_ptr&& desired, \fB(8)\fP + std::memory_order order = + std::memory_order_seq_cst ) noexcept; + + Atomically compares the underlying shared_ptr in *this with expected, and if they + are equivalent, replaces the former with desired (performs read-modify-write + operation). Otherwise, loads the actual value stored in *this into expected + (performs load operation). The replacement is performed as if by the copy or move + assignment operator of shared_ptr, as appropriate. + + Two shared_ptrs are equivalent if and only if they store the same pointer value and + share ownership. + + The memory models for the read-modify-write and load operations are success and + failure respectively. For overloads (3,4,7,8), order is used for both + read-modify-write and load operations, except that std::memory_order_acquire and + std::memory_order_relaxed are used for the load operation if order == + std::memory_order_acq_rel, or order == std::memory_order_release respectively. + + The weak versions (1-4) may fail spuriously. + +.SH Parameters + + expected - reference to the value expected to be found in the atomic object + desired - the value to store in the atomic object if it is as expected + success - the memory synchronization ordering for the read-modify-write operation + if the comparison succeeds. All values are permitted + the memory synchronization ordering for the load operation if the + failure - comparison fails. Cannot be std::memory_order_release or + std::memory_order_acq_rel and cannot specify stronger ordering than + success + order - the memory synchronization ordering for both operations + +.SH Return value + + true if the underlying atomic value was changed, false otherwise. + + Remarks + + All changes to the atomic_shared_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + + If the compare-exchange operation return true, expected is not accessed after the + atomic update step. If it returns false, expected is updated with the existing value + read from the atomic_shared_ptr object in the attempted atomic update. The use_count + update corresponding to the write to expected is part of the atomic operation, but + the write to expected itself is not required to be part of the atomic operation. + + For overloads (1,3,5,7), desired is not accessed after the atomic update step. + + For overloads (2,4,6,8), desired is moved from only if the compare-exchange + operation returns true; the moving occurs after the atomic update step. + +.SH Notes + + The weak forms (1-4) of the functions are allowed to fail spuriously, that is, act + as if *this and expected are not equivalent even when they are. When a + compare-and-exchange is in a loop, the weak version will yield better performance on + some platforms. + +.SH See also + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_shared_ptr::exchange.3 b/man/std::experimental::atomic_shared_ptr::exchange.3 new file mode 100644 index 000000000..e3a5df188 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::exchange.3 @@ -0,0 +1,43 @@ +.TH std::experimental::atomic_shared_ptr::exchange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::exchange \- std::experimental::atomic_shared_ptr::exchange + +.SH Synopsis + shared_ptr exchange( shared_ptr desired, std::memory_order order = + std::memory_order_seq_cst ) noexcept; + + Atomically replaces the underlying shared_ptr with desired. The operation is a + read-modify-write operation. Memory is affected according to the value of order. + +.SH Parameters + + desired - value to assign + order - memory order constraints to enforce + +.SH Return value + + The value of the atomic variable before the call. + + Remarks + + All changes to the atomic_shared_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + +.SH See also + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_shared_ptr::is_lock_free.3 b/man/std::experimental::atomic_shared_ptr::is_lock_free.3 new file mode 100644 index 000000000..ab4b19fee --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::is_lock_free.3 @@ -0,0 +1,33 @@ +.TH std::experimental::atomic_shared_ptr::is_lock_free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::is_lock_free \- std::experimental::atomic_shared_ptr::is_lock_free + +.SH Synopsis + bool is_lock_free() const noexcept; + + Checks whether the atomic operations on all objects of this type are lock-free. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the atomic operations on the objects of this type are lock-free, false + otherwise. + +.SH See also + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_shared_ptr::load.3 b/man/std::experimental::atomic_shared_ptr::load.3 new file mode 100644 index 000000000..88b415db4 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::load.3 @@ -0,0 +1,47 @@ +.TH std::experimental::atomic_shared_ptr::load 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::load \- std::experimental::atomic_shared_ptr::load + +.SH Synopsis + shared_ptr load( std::memory_order order = std::memory_order_seq_cst ) const + noexcept; + + Atomically loads and returns the current value of the atomic_shared_ptr. Memory is + affected according to the value of order. + + order must be one of std::memory_order_relaxed, std::memory_order_consume, + std::memory_order_acquire or std::memory_order_seq_cst. Otherwise the behavior is + undefined. + +.SH Parameters + + order - memory order constraints to enforce + + Remarks + + All associated use_count increments are guaranteed to be performed as part of the + atomic operation. + +.SH Return value + + The current value of the atomic_shared_ptr. + +.SH See also + + loads a value from an + operator shared_ptr atomic object + \fI\fI(public member\fP\fP + function) + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_shared_ptr::operator=.3 b/man/std::experimental::atomic_shared_ptr::operator=.3 new file mode 100644 index 000000000..e43bc2231 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::operator=.3 @@ -0,0 +1,55 @@ +.TH std::experimental::atomic_shared_ptr::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::operator= \- std::experimental::atomic_shared_ptr::operator= + +.SH Synopsis + void operator=( shared_ptr desired ) noexcept; \fB(1)\fP + void operator=( const atomic_shared_ptr& ) = delete; \fB(2)\fP + + 1) Atomically assigns a value desired to the atomic variable. Equivalent to + store(desired). + 2) Atomic variables are not CopyAssignable. + +.SH Parameters + + desired - value to assign + +.SH Notes + + Unlike most assignment operators, the assignment operators for atomic_shared_ptr + returns void. + + Remarks + + All changes to the atomic_shared_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + +.SH See also + + constructs an + atomic_shared_ptr + constructor object + \fI\fI(public member\fP\fP + function) + atomically replaces + the value of the + store atomic object with a + non-atomic argument + \fI\fI(public member\fP\fP + function) + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_shared_ptr::operatorshared_ptr.3 b/man/std::experimental::atomic_shared_ptr::operatorshared_ptr.3 new file mode 100644 index 000000000..2da94f112 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::operatorshared_ptr.3 @@ -0,0 +1,27 @@ +.TH std::experimental::atomic_shared_ptr::operatorshared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::operatorshared_ptr \- std::experimental::atomic_shared_ptr::operatorshared_ptr + +.SH Synopsis + operator shared_ptr() const noexcept; + + Atomically loads and returns the current value of the atomic_shared_ptr. Equivalent + to load(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current value of the atomic_shared_ptr. + + Remarks + + All associated use_count increments are guaranteed to be performed as part of the + atomic operation. + +.SH See also + + load atomically obtains the value of the atomic object + \fI(public member function)\fP diff --git a/man/std::experimental::atomic_shared_ptr::store.3 b/man/std::experimental::atomic_shared_ptr::store.3 new file mode 100644 index 000000000..365e267c6 --- /dev/null +++ b/man/std::experimental::atomic_shared_ptr::store.3 @@ -0,0 +1,51 @@ +.TH std::experimental::atomic_shared_ptr::store 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_shared_ptr::store \- std::experimental::atomic_shared_ptr::store + +.SH Synopsis + void store( shared_ptr desired, std::memory_order order = + std::memory_order_seq_cst ) noexcept; + + Atomically replaces the current value with desired. Memory is affected according to + the value of order. + + order must be one of std::memory_order_relaxed, std::memory_order_release or + std::memory_order_seq_cst. Otherwise the behavior is undefined. + +.SH Parameters + + desired - the shared_ptr to store into the atomic variable + order - memory order constraints to enforce + +.SH Return value + + \fI(none)\fP + + Remarks + + All changes to the atomic_shared_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + +.SH See also + + stores a value into an + atomic_shared_ptr + operator= object + \fI\fI(public member\fP\fP + function) + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_weak_ptr.3 b/man/std::experimental::atomic_weak_ptr.3 new file mode 100644 index 000000000..eb02535d5 --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr.3 @@ -0,0 +1,34 @@ +.TH std::experimental::atomic_weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr \- std::experimental::atomic_weak_ptr + +.SH Synopsis + Defined in header + template< class T > (concurrency TS) + class atomic_weak_ptr; + + The class template atomic_weak_ptr provides thread-safe atomic pointer operations + over a std::weak_ptr. + +.SH Member functions + + constructor constructs an atomic_weak_ptr object + \fI(public member function)\fP + operator= stores a value into an atomic_weak_ptr object + \fI(public member function)\fP + is_lock_free checks if the atomic_weak_ptr object is lock-free + \fI(public member function)\fP + atomically replaces the value of the atomic object with a + store non-atomic argument + \fI(public member function)\fP + load atomically obtains the value of the atomic object + \fI(public member function)\fP + operator weak_ptr loads a value from an atomic object + \fI(public member function)\fP + atomically replaces the value of the atomic object and + exchange obtains the value held previously + \fI(public member function)\fP + atomically compares the value of the atomic object with + compare_exchange_weak non-atomic argument and performs atomic exchange if equal or + compare_exchange_strong atomic load if not + \fI(public member function)\fP diff --git a/man/std::experimental::atomic_weak_ptr::atomic_weak_ptr.3 b/man/std::experimental::atomic_weak_ptr::atomic_weak_ptr.3 new file mode 100644 index 000000000..0d1daf687 --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::atomic_weak_ptr.3 @@ -0,0 +1,19 @@ +.TH std::experimental::atomic_weak_ptr::atomic_weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::atomic_weak_ptr \- std::experimental::atomic_weak_ptr::atomic_weak_ptr + +.SH Synopsis + constexpr atomic_weak_ptr() noexcept; \fB(1)\fP + constexpr atomic_weak_ptr( weak_ptr desired ) noexcept; \fB(2)\fP + atomic_weak_ptr( const atomic_weak_ptr& ) = delete; \fB(3)\fP + + Constructs a new atomic_weak_ptr object. + + 1) The default constructor initializes the object to an empty state. + 2) Initializes the underlying weak_ptr with desired. The initialization is not + atomic. + 3) Atomic variables are not CopyConstructible. + +.SH Parameters + + desired - value to initialize with diff --git a/man/std::experimental::atomic_weak_ptr::compare_exchange_strong,.3 b/man/std::experimental::atomic_weak_ptr::compare_exchange_strong,.3 new file mode 100644 index 000000000..fff982250 --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::compare_exchange_strong,.3 @@ -0,0 +1,113 @@ +.TH std::experimental::atomic_weak_ptr::compare_exchange_strong, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::compare_exchange_strong, \- std::experimental::atomic_weak_ptr::compare_exchange_strong, + +.SH Synopsis + + bool compare_exchange_weak( std::weak_ptr& expected, const std::weak_ptr& + desired, \fB(1)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_weak( std::weak_ptr& expected, std::weak_ptr&& + desired, \fB(2)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_weak( std::weak_ptr& expected, const std::weak_ptr& + desired, \fB(3)\fP + std::memory_order order = std::memory_order_seq_cst + ) noexcept; + bool compare_exchange_weak( std::weak_ptr& expected, std::weak_ptr&& + desired, \fB(4)\fP + std::memory_order order = std::memory_order_seq_cst + ) noexcept; + bool compare_exchange_strong( std::weak_ptr& expected, const + std::weak_ptr& desired, \fB(5)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_strong( std::weak_ptr& expected, std::weak_ptr&& + desired, \fB(6)\fP + std::memory_order success, std::memory_order + failure ) noexcept; + bool compare_exchange_strong( std::weak_ptr& expected, const + std::weak_ptr& desired, \fB(7)\fP + std::memory_order order = + std::memory_order_seq_cst ) noexcept; + bool compare_exchange_strong( std::weak_ptr& expected, std::weak_ptr&& + desired, \fB(8)\fP + std::memory_order order = + std::memory_order_seq_cst ) noexcept; + + Atomically compares the underlying weak_ptr in *this with expected, and if they are + equivalent, replaces the former with desired (performs read-modify-write operation). + Otherwise, loads the actual value stored in *this into expected (performs load + operation). The replacement is performed as if by the copy or move assignment + operator of weak_ptr, as appropriate. + + Two weak_ptrs are equivalent if and only if they store the same pointer value and + share ownership. + + The memory models for the read-modify-write and load operations are success and + failure respectively. For overloads (3,4,7,8), order is used for both + read-modify-write and load operations, except that std::memory_order_acquire and + std::memory_order_relaxed are used for the load operation if order == + std::memory_order_acq_rel, or order == std::memory_order_release respectively. + + The weak versions (1-4) may fail spuriously. + +.SH Parameters + + expected - reference to the value expected to be found in the atomic object + desired - the value to store in the atomic object if it is as expected + success - the memory synchronization ordering for the read-modify-write operation + if the comparison succeeds. All values are permitted + the memory synchronization ordering for the load operation if the + failure - comparison fails. Cannot be std::memory_order_release or + std::memory_order_acq_rel and cannot specify stronger ordering than + success + order - the memory synchronization ordering for both operations + +.SH Return value + + true if the underlying atomic value was changed, false otherwise. + + Remarks + + All changes to the atomic_weak_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + + If the compare-exchange operation return true, expected is not accessed after the + atomic update step. If it returns false, expected is updated with the existing value + read from the atomic_weak_ptr object in the attempted atomic update. The use_count + update corresponding to the write to expected is part of the atomic operation, but + the write to expected itself is not required to be part of the atomic operation. + + For overloads (1,3,5,7), desired is not accessed after the atomic update step. + + For overloads (2,4,6,8), desired is moved from only if the compare-exchange + operation returns true; the moving occurs after the atomic update step. + +.SH Notes + + The weak forms (1-4) of the functions are allowed to fail spuriously, that is, act + as if *this and expected are not equivalent even when they are. When a + compare-and-exchange is in a loop, the weak version will yield better performance on + some platforms. + +.SH See also + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_weak_ptr::exchange.3 b/man/std::experimental::atomic_weak_ptr::exchange.3 new file mode 100644 index 000000000..7660ef70f --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::exchange.3 @@ -0,0 +1,43 @@ +.TH std::experimental::atomic_weak_ptr::exchange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::exchange \- std::experimental::atomic_weak_ptr::exchange + +.SH Synopsis + weak_ptr exchange( weak_ptr desired, std::memory_order order = + std::memory_order_seq_cst ) noexcept; + + Atomically replaces the underlying weak_ptr with desired. The operation is a + read-modify-write operation. Memory is affected according to the value of order. + +.SH Parameters + + desired - value to assign + order - memory order constraints to enforce + +.SH Return value + + The value of the atomic variable before the call. + + Remarks + + All changes to the atomic_weak_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + +.SH See also + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_weak_ptr::is_lock_free.3 b/man/std::experimental::atomic_weak_ptr::is_lock_free.3 new file mode 100644 index 000000000..b560efd4a --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::is_lock_free.3 @@ -0,0 +1,33 @@ +.TH std::experimental::atomic_weak_ptr::is_lock_free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::is_lock_free \- std::experimental::atomic_weak_ptr::is_lock_free + +.SH Synopsis + bool is_lock_free() const noexcept; + + Checks whether the atomic operations on all objects of this type are lock-free. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the atomic operations on the objects of this type are lock-free, false + otherwise. + +.SH See also + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_weak_ptr::load.3 b/man/std::experimental::atomic_weak_ptr::load.3 new file mode 100644 index 000000000..ad4834f51 --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::load.3 @@ -0,0 +1,47 @@ +.TH std::experimental::atomic_weak_ptr::load 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::load \- std::experimental::atomic_weak_ptr::load + +.SH Synopsis + weak_ptr load( std::memory_order order = std::memory_order_seq_cst ) const + noexcept; + + Atomically loads and returns the current value of the atomic_weak_ptr. Memory is + affected according to the value of order. + + order must be one of std::memory_order_relaxed, std::memory_order_consume, + std::memory_order_acquire or std::memory_order_seq_cst. Otherwise the behavior is + undefined. + +.SH Parameters + + order - memory order constraints to enforce + + Remarks + + All associated use_count increments are guaranteed to be performed as part of the + atomic operation. + +.SH Return value + + The current value of the atomic_weak_ptr. + +.SH See also + + loads a value from an + operator weak_ptr atomic object + \fI\fI(public member\fP\fP + function) + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_weak_ptr::operator=.3 b/man/std::experimental::atomic_weak_ptr::operator=.3 new file mode 100644 index 000000000..4bf43d442 --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::operator=.3 @@ -0,0 +1,54 @@ +.TH std::experimental::atomic_weak_ptr::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::operator= \- std::experimental::atomic_weak_ptr::operator= + +.SH Synopsis + void operator=( weak_ptr desired ) noexcept; \fB(1)\fP + void operator=( const atomic_weak_ptr& ) = delete; \fB(2)\fP + + 1) Atomically assigns a value desired to the atomic variable. Equivalent to + store(desired). + 2) Atomic variables are not CopyAssignable. + +.SH Parameters + + desired - value to assign + +.SH Notes + + Unlike most assignment operators, the assignment operators for atomic_weak_ptr + returns void. + + Remarks + + All changes to the atomic_weak_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + +.SH See also + + constructs an + constructor atomic_weak_ptr object + \fI\fI(public member\fP\fP + function) + atomically replaces + the value of the + store atomic object with a + non-atomic argument + \fI\fI(public member\fP\fP + function) + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::atomic_weak_ptr::operatorweak_ptr.3 b/man/std::experimental::atomic_weak_ptr::operatorweak_ptr.3 new file mode 100644 index 000000000..45fb906c3 --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::operatorweak_ptr.3 @@ -0,0 +1,27 @@ +.TH std::experimental::atomic_weak_ptr::operatorweak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::operatorweak_ptr \- std::experimental::atomic_weak_ptr::operatorweak_ptr + +.SH Synopsis + operator weak_ptr() const noexcept; + + Atomically loads and returns the current value of the atomic_weak_ptr. Equivalent to + load(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current value of the atomic_weak_ptr. + + Remarks + + All associated use_count increments are guaranteed to be performed as part of the + atomic operation. + +.SH See also + + load atomically obtains the value of the atomic object + \fI(public member function)\fP diff --git a/man/std::experimental::atomic_weak_ptr::store.3 b/man/std::experimental::atomic_weak_ptr::store.3 new file mode 100644 index 000000000..ea177e9ee --- /dev/null +++ b/man/std::experimental::atomic_weak_ptr::store.3 @@ -0,0 +1,50 @@ +.TH std::experimental::atomic_weak_ptr::store 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::atomic_weak_ptr::store \- std::experimental::atomic_weak_ptr::store + +.SH Synopsis + void store( weak_ptr desired, std::memory_order order = + std::memory_order_seq_cst ) noexcept; + + Atomically replaces the current value with desired. Memory is affected according to + the value of order. + + order must be one of std::memory_order_relaxed, std::memory_order_release or + std::memory_order_seq_cst. Otherwise the behavior is undefined. + +.SH Parameters + + desired - the weak_ptr to store into the atomic variable + order - memory order constraints to enforce + +.SH Return value + + \fI(none)\fP + + Remarks + + All changes to the atomic_weak_ptr object itself, and all associated use_count + increments, are guaranteed to be performed atomically. Associated use_count + decrements take place after the atomic operation, but are not required to be part of + it. Any associated destruction or deallocation operations take place after the + atomic operation and are not part of it. + +.SH See also + + stores a value into an + operator= atomic_weak_ptr object + \fI\fI(public member\fP\fP + function) + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) diff --git a/man/std::experimental::bad_any_cast.3 b/man/std::experimental::bad_any_cast.3 new file mode 100644 index 000000000..8da3b130c --- /dev/null +++ b/man/std::experimental::bad_any_cast.3 @@ -0,0 +1,88 @@ +.TH std::experimental::bad_any_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::bad_any_cast \- std::experimental::bad_any_cast + +.SH Synopsis + Defined in header + class bad_any_cast : public std::bad_cast; (library fundamentals TS) + + Defines a type of object to be thrown by the value-returning forms of + std::experimental::any_cast on failure. + +.SH Member functions + + constructor constructs a new bad_any_cast object + \fI(public member function)\fP + operator= replaces the bad_any_cast object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::experimental::bad_any_cast::bad_any_cast + + bad_any_cast() noexcept; \fB(1)\fP (library fundamentals TS) + bad_any_cast( const bad_any_cast& other ) noexcept; \fB(2)\fP (library fundamentals TS) + + Constructs a new bad_any_cast object with an implementation-defined null-terminated + byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type + std::experimental::bad_any_cast then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::experimental::bad_any_cast::operator= + + bad_any_cast& operator=( const bad_any_cast& other ) (library fundamentals TS) + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::experimental::bad_any_cast then std::strcmp(what(), other.what()) == 0 after + assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::experimental::bad_any_cast::what + + virtual const char* what() const noexcept; (library fundamentals TS) + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + +Inherited from std::bad_cast + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::bad_optional_access.3 b/man/std::experimental::bad_optional_access.3 new file mode 100644 index 000000000..1179b2f61 --- /dev/null +++ b/man/std::experimental::bad_optional_access.3 @@ -0,0 +1,93 @@ +.TH std::experimental::bad_optional_access 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::bad_optional_access \- std::experimental::bad_optional_access + +.SH Synopsis + Defined in header + class bad_optional_access; (library fundamentals TS) + + Defines a type of object to be thrown by std::experimental::optional::value when + accessing an optional object that does not contain a value. + + std-bad optional access-inheritance.svg + + Inheritance diagram + +.SH Member functions + + constructor constructs a new bad_optional_access object + \fI(public member function)\fP + operator= replaces the bad_optional_access object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::experimental::bad_optional_access::bad_optional_access + + bad_optional_access() noexcept; \fB(1)\fP (library fundamentals TS) + bad_optional_access( const bad_optional_access& other \fB(2)\fP (library fundamentals TS) + ) noexcept; + + Constructs a new bad_optional_access object with an implementation-defined + null-terminated byte string which is accessible through what(). + + 1) Default constructor. + 2) Copy constructor. If *this and other both have dynamic type + std::experimental::bad_optional_access then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + other - another exception object to copy + +std::experimental::bad_optional_access::operator= + + bad_optional_access& operator=( const (library fundamentals TS) + bad_optional_access& other ) noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::experimental::bad_optional_access then std::strcmp(what(), other.what()) == 0 + after assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::experimental::bad_optional_access::what + + virtual const char* what() const noexcept; (library fundamentals TS) + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). + +Inherited from std::logic_error + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::barrier.3 b/man/std::experimental::barrier.3 new file mode 100644 index 000000000..cb0166f20 --- /dev/null +++ b/man/std::experimental::barrier.3 @@ -0,0 +1,42 @@ +.TH std::experimental::barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::barrier \- std::experimental::barrier + +.SH Synopsis + Defined in header + class barrier; (concurrency TS) + + The class std::experimental::barrier provides a thread-coordination mechanism that + allows a set of participating threads to block until an operation is completed. + Unlike std::experimental::latch, barriers are reusable; once the participating + threads are released from a barrier's synchronization point, they can reuse the same + barrier. + + A barrier has a completion phase, which is executed by one of the participating + threads once all threads in the set of participating threads arrive at the + synchronization point. The arrive_and_wait and arrive_and_drop calls synchronize + with the start of the completion phase; the end of the completion phase synchronizes + with the returns from all calls blocked by its completion. + + For std::experimental::barrier, the completion phase is empty. + std::experimental::flex_barrier allows the user to control the completion phase with + a function object. + + The set of participating threads for a barrier constructed for num_threads threads + is the first num_threads threads to arrive at its synchronization point after + construction. The same set of threads (except for threads that called + arrive_and_drop()) must arrive at the barrier each cycle. + +.SH Member functions + + constructor constructs a barrier + \fI(public member function)\fP + destructor destroys the barrier + \fI(public member function)\fP + operator= not copy-assignable + [deleted] \fI(public member function)\fP + arrive_and_wait arrive at the synchronization point and block + \fI(public member function)\fP + arrive at the synchronization point and remove the current thread + arrive_and_drop from the set of participating threads + \fI(public member function)\fP diff --git a/man/std::experimental::barrier::arrive_and_drop.3 b/man/std::experimental::barrier::arrive_and_drop.3 new file mode 100644 index 000000000..4b0f06e04 --- /dev/null +++ b/man/std::experimental::barrier::arrive_and_drop.3 @@ -0,0 +1,38 @@ +.TH std::experimental::barrier::arrive_and_drop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::barrier::arrive_and_drop \- std::experimental::barrier::arrive_and_drop + +.SH Synopsis + void arrive_and_drop(); (concurrency TS) + + Arrive at the barrier's synchronization point and remove the current thread from the + set of participating threads. It is unspecified whether this function blocks until + the completion phase has ended. + + The behavior is undefined if the calling thread is not in the set of participating + threads of this barrier. + + Calls to arrive_and_drop synchronizes with the start of the completion phase of the + barrier. If the call blocks, then the completion of the completion phase + synchronizes with the return from the call. + + Calls to arrive_and_drop and arrive_and_wait never introduce data races with + themselves or each other. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + If every participating thread calls arrive_and_drop(), the barrier can only be + destroyed. + + After a thread calls arrive_and_drop() on a barrier, it is no longer a member of its + set of participating threads and hence can no longer call either arrive_and_drop() + or arrive_and_wait() on the same barrier. + +.SH See also + + arrive_and_wait arrive at the synchronization point and block + \fI(public member function)\fP diff --git a/man/std::experimental::barrier::arrive_and_wait.3 b/man/std::experimental::barrier::arrive_and_wait.3 new file mode 100644 index 000000000..1a4858fbb --- /dev/null +++ b/man/std::experimental::barrier::arrive_and_wait.3 @@ -0,0 +1,39 @@ +.TH std::experimental::barrier::arrive_and_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::barrier::arrive_and_wait \- std::experimental::barrier::arrive_and_wait + +.SH Synopsis + void arrive_and_wait(); (concurrency TS) + + Blocks and arrive at the barrier's synchronization point. + + The behavior is undefined if the calling thread is not in the set of participating + threads of this barrier. + + Calls to arrive_and_wait synchronizes with the start of the completion phase of the + barrier. The completion of the completion phase synchronizes with the return from + the call. + + Calls to arrive_and_drop and arrive_and_wait never introduce data races with + themselves or each other. + +.SH Notes + + It is safe for a thread to call either arrive_and_wait() or arrive_and_drop() + immediately on return from this call. It's not necessary to ensure that all blocked + threads have exited arrive_and_wait() before a thread calls it again. + + The set of participating threads for a barrier constructed for num_threads threads + is the first num_threads to arrive at its synchronization point. This set does not + change from cycle to cycle, except for threads removed from the set due to + arrive_and_drop() calls. + +.SH Exceptions + + Throws nothing. + +.SH See also + + arrive at the synchronization point and remove the current thread + arrive_and_drop from the set of participating threads + \fI(public member function)\fP diff --git a/man/std::experimental::barrier::barrier.3 b/man/std::experimental::barrier::barrier.3 new file mode 100644 index 000000000..c7e712922 --- /dev/null +++ b/man/std::experimental::barrier::barrier.3 @@ -0,0 +1,22 @@ +.TH std::experimental::barrier::barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::barrier::barrier \- std::experimental::barrier::barrier + +.SH Synopsis + explicit barrier( std::ptrdiff_t num_threads ); \fB(1)\fP (concurrency TS) + barrier( const barrier & ) = delete; \fB(2)\fP (concurrency TS) + + 1) Constructs a barrier for num_threads participating threads. The set of + participating threads is the first num_threads threads to arrive at the + synchronization point. + 2) Copy constructor is deleted; barrier is not copyable. + +.SH Parameters + + num_threads - the number of participating threads for the barrier; must be + non-negative + +.SH Notes + + If num_threads is zero, the set of participating threads is empty, and barrier can + only be destroyed. diff --git a/man/std::experimental::barrier::~barrier.3 b/man/std::experimental::barrier::~barrier.3 new file mode 100644 index 000000000..9cfef8922 --- /dev/null +++ b/man/std::experimental::barrier::~barrier.3 @@ -0,0 +1,10 @@ +.TH std::experimental::barrier::~barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::barrier::~barrier \- std::experimental::barrier::~barrier + +.SH Synopsis + ~barrier(); (concurrency TS) + + Destroys the barrier. + + The behavior is undefined if a thread is blocked at the synchronization point. diff --git a/man/std::experimental::basic_string_view.3 b/man/std::experimental::basic_string_view.3 new file mode 100644 index 000000000..523d3f000 --- /dev/null +++ b/man/std::experimental::basic_string_view.3 @@ -0,0 +1,145 @@ +.TH std::experimental::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view \- std::experimental::basic_string_view + +.SH Synopsis + Defined in header + template< + + class CharT, (library fundamentals TS) + class Traits = std::char_traits + + > class basic_string_view; + + The class template basic_string_view describes an object that can refer to a + constant contiguous sequence of char-like objects with the first element of the + sequence at position zero. + + A typical implementation holds only two members: a pointer to constant CharT and a + size. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::experimental::string_view std::experimental::basic_string_view + std::experimental::wstring_view std::experimental::basic_string_view + std::experimental::u16string_view std::experimental::basic_string_view + std::experimental::u32string_view std::experimental::basic_string_view + +.SH Template parameters + + CharT - character type + Traits - traits class specifying the operations on the character type + +.SH Member types + + Member type Definition + traits_type Traits + value_type CharT + pointer CharT* + const_pointer const CharT* + reference CharT& + const_reference const CharT& + const_iterator implementation-defined LegacyRandomAccessIterator + iterator const_iterator + reverse_iterator const_reverse_iterator + const_reverse_iterator std::reverse_iterator + size_type std::size_t + difference_type std::ptrdiff_t + + Note: iterator and const_iterator are the same type because string views are views + into constant character sequences. + +.SH Member functions + + constructor constructs a basic_string_view + \fI(public member function)\fP + operator= assigns a view + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Element access + operator[] access specified character + \fI(public member function)\fP + at access specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function)\fP +.SH Capacity + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP +.SH Modifiers + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Operations + to_string creates a string from the view + operator basic_string \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator== + operator!= + operator< lexicographically compares two views + operator> \fI(function template)\fP + operator<= + operator>= +.SH Input/output + operator<< performs stream output on views + \fI(function template)\fP + +.SH Helper classes + + std::hash + std::hash hash support for views + std::hash \fI(class template specialization)\fP + std::hash + + Feature test macros + + a value of at least 201411 indicates that + __cpp_lib_experimental_string_view basic_string_view template is supported + (macro constant) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::at.3 b/man/std::experimental::basic_string_view::at.3 new file mode 100644 index 000000000..981a7d38e --- /dev/null +++ b/man/std::experimental::basic_string_view::at.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::at \- std::experimental::basic_string_view::at + +.SH Synopsis + constexpr const_reference at(size_type pos) const; (library fundamentals TS) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH See also + + operator[] access specified character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::back.3 b/man/std::experimental::basic_string_view::back.3 new file mode 100644 index 000000000..225d84132 --- /dev/null +++ b/man/std::experimental::basic_string_view::back.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::back \- std::experimental::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; (library fundamentals TS) + + Returns reference to the last character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::basic_string_view.3 b/man/std::experimental::basic_string_view::basic_string_view.3 new file mode 100644 index 000000000..6cb89c751 --- /dev/null +++ b/man/std::experimental::basic_string_view::basic_string_view.3 @@ -0,0 +1,81 @@ +.TH std::experimental::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::basic_string_view \- std::experimental::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP (library fundamentals TS) + constexpr basic_string_view( const basic_string_view& \fB(2)\fP (library fundamentals TS) + other ) noexcept = default; + template + basic_string_view( const std::basic_string& str ) noexcept; + constexpr basic_string_view( const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + count ); + constexpr basic_string_view( const CharT* s ); \fB(5)\fP (library fundamentals TS) + + 1) Default constructor. Constructs an empty basic_string_view. + 2) Copy constructor. Constructs a view of the same content as other. + 3) Constructs a view of the first str.size() characters of the character array + starting with the element pointed by str.data(). + 4) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). + 5) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range (even though the constructor may not access any of the elements of + this range). + +.SH Parameters + + other - another view to initialize the view with + str - a C++ string object to initialize view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + +.SH Exceptions + + 4,5) Throws nothing. + +.SH Complexity + + 1-4) Constant. + 5) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string cppstr = "Foo"; + char array[3] = {'B', 'a', 'r'}; + + std::experimental::string_view cppstr_v(cppstr); + std::experimental::string_view array_v(array, sizeof array); + + std::experimental::wstring_view wcstr_v = L"xyzzy"; + + std::cout << cppstr_v << '\\n' + << array_v << '\\n' + << wcstr_v.size() << '\\n'; + } + +.SH Output: + + Foo + Bar + 5 + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::begin,.3 b/man/std::experimental::basic_string_view::begin,.3 new file mode 100644 index 000000000..a9e63b5a8 --- /dev/null +++ b/man/std::experimental::basic_string_view::begin,.3 @@ -0,0 +1,32 @@ +.TH std::experimental::basic_string_view::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::begin, \- std::experimental::basic_string_view::begin, + +.SH Synopsis + + constexpr const_iterator begin() const noexcept; (library fundamentals TS) + constexpr const_iterator cbegin() const noexcept; (library fundamentals TS) + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::compare.3 b/man/std::experimental::basic_string_view::compare.3 new file mode 100644 index 000000000..338a318c6 --- /dev/null +++ b/man/std::experimental::basic_string_view::compare.3 @@ -0,0 +1,77 @@ +.TH std::experimental::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::compare \- std::experimental::basic_string_view::compare + +.SH Synopsis + constexpr int compare(basic_string_view v) const \fB(1)\fP (library fundamentals TS) + noexcept; + constexpr int compare(size_type pos1, size_type + count1, \fB(2)\fP (library fundamentals TS) + basic_string_view v) const + constexpr int compare(size_type pos1, size_type + count1, basic_string_view v, \fB(3)\fP (library fundamentals TS) + size_type pos2, size_type + count2) const; + constexpr int compare(const CharT* s) const; \fB(4)\fP (library fundamentals TS) + constexpr int compare(size_type pos1, size_type + count1, \fB(5)\fP (library fundamentals TS) + const CharT* s) const; + constexpr int compare(size_type pos1, size_type + count1, \fB(6)\fP (library fundamentals TS) + const CharT* s, size_type + count2) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less <0 + than v + size() < this is less <0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater >0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater >0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH See also + + operator== + operator!= + operator< lexicographically compares two views + operator> \fI(function template)\fP + operator<= + operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::copy.3 b/man/std::experimental::basic_string_view::copy.3 new file mode 100644 index 000000000..b3a99c4ea --- /dev/null +++ b/man/std::experimental::basic_string_view::copy.3 @@ -0,0 +1,39 @@ +.TH std::experimental::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::copy \- std::experimental::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, + + size_type count, (library fundamentals TS) + + size_type pos = 0) const; + + Copies the substring [pos, pos + rcount) to the character string pointed to by dest, + where rcount is the smaller of count and size() - pos. + +.SH Parameters + + dest - pointer to the destination character string + pos - position of the first character + count - requested substring length + +.SH Return value + + Number of characters copied + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH See also + + substr returns a substring + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::data.3 b/man/std::experimental::basic_string_view::data.3 new file mode 100644 index 000000000..e4fc2d4ff --- /dev/null +++ b/man/std::experimental::basic_string_view::data.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::data \- std::experimental::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; (library fundamentals TS) + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. (n.b. Unlike basic_string::data() and string literals, data() + may return a pointer to a buffer that is not null-terminated. Therefore it is + typically a mistake to pass data() to a routine that takes just a const CharT* and + expects a null-terminated string.) + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::empty.3 b/man/std::experimental::basic_string_view::empty.3 new file mode 100644 index 000000000..d632d1769 --- /dev/null +++ b/man/std::experimental::basic_string_view::empty.3 @@ -0,0 +1,30 @@ +.TH std::experimental::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::empty \- std::experimental::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; (library fundamentals TS) + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::end,.3 b/man/std::experimental::basic_string_view::end,.3 new file mode 100644 index 000000000..3aa72c145 --- /dev/null +++ b/man/std::experimental::basic_string_view::end,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::end, \- std::experimental::basic_string_view::end, + +.SH Synopsis + + constexpr const_iterator end() const noexcept; (library fundamentals TS) + constexpr const_iterator cend() const noexcept; (library fundamentals TS) + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::find.3 b/man/std::experimental::basic_string_view::find.3 new file mode 100644 index 000000000..2013b2b4c --- /dev/null +++ b/man/std::experimental::basic_string_view::find.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find \- std::experimental::basic_string_view::find + +.SH Synopsis + constexpr size_type find(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = 0) const noexcept; + constexpr size_type find(CharT c, size_type pos = 0) \fB(2)\fP (library fundamentals TS) + const noexcept; + constexpr size_type find(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type find(const CharT* s, size_type pos \fB(4)\fP (library fundamentals TS) + = 0) const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(&c, 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::find_first_not_of.3 b/man/std::experimental::basic_string_view::find_first_not_of.3 new file mode 100644 index 000000000..5005621e5 --- /dev/null +++ b/man/std::experimental::basic_string_view::find_first_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_not_of \- std::experimental::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_first_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + 0) const noexcept; + constexpr size_type (library fundamentals + find_first_not_of(CharT c, size_type pos = 0) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos = 0) \fB(4)\fP TS) + const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::find_first_of.3 b/man/std::experimental::basic_string_view::find_first_of.3 new file mode 100644 index 000000000..be72db3a5 --- /dev/null +++ b/man/std::experimental::basic_string_view::find_first_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_of \- std::experimental::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type find_first_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = 0) const noexcept; TS) + constexpr size_type find_first_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + 0) const noexcept; TS) + constexpr size_type find_first_of(const CharT* s, \fB(3)\fP (library fundamentals + size_type pos, size_type count) const; TS) + constexpr size_type find_first_of(const CharT* s, \fB(4)\fP (library fundamentals + size_type pos = 0) const; TS) + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_first_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::find_last_not_of.3 b/man/std::experimental::basic_string_view::find_last_not_of.3 new file mode 100644 index 000000000..48128b2ee --- /dev/null +++ b/man/std::experimental::basic_string_view::find_last_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_not_of \- std::experimental::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_last_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + npos) const noexcept; + constexpr size_type (library fundamentals + find_last_not_of(CharT c, size_type pos = npos) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos = npos) \fB(4)\fP TS) + const; + + Finds the last character not equal to any of the characters in the given character + sequence. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::find_last_of.3 b/man/std::experimental::basic_string_view::find_last_of.3 new file mode 100644 index 000000000..30d0a0127 --- /dev/null +++ b/man/std::experimental::basic_string_view::find_last_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_of \- std::experimental::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type find_last_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = npos) const noexcept; TS) + constexpr size_type find_last_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + npos) const noexcept; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(3)\fP (library fundamentals + pos, size_type count) const; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(4)\fP (library fundamentals + pos = npos) const; TS) + + Finds the last character equal to any of the characters in the given character + sequence. + + 1) Finds the last occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_last_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::front.3 b/man/std::experimental::basic_string_view::front.3 new file mode 100644 index 000000000..1cc047f8c --- /dev/null +++ b/man/std::experimental::basic_string_view::front.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::front \- std::experimental::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; (library fundamentals TS) + + Returns reference to the first character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH See also + + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::max_size.3 b/man/std::experimental::basic_string_view::max_size.3 new file mode 100644 index 000000000..113ef28f1 --- /dev/null +++ b/man/std::experimental::basic_string_view::max_size.3 @@ -0,0 +1,31 @@ +.TH std::experimental::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::max_size \- std::experimental::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; (library fundamentals TS) + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::npos.3 b/man/std::experimental::basic_string_view::npos.3 new file mode 100644 index 000000000..b1fc5ec8f --- /dev/null +++ b/man/std::experimental::basic_string_view::npos.3 @@ -0,0 +1,14 @@ +.TH std::experimental::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::npos \- std::experimental::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); (library fundamentals TS) + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::operator=.3 b/man/std::experimental::basic_string_view::operator=.3 new file mode 100644 index 000000000..86f334c8d --- /dev/null +++ b/man/std::experimental::basic_string_view::operator=.3 @@ -0,0 +1,47 @@ +.TH std::experimental::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator= \- std::experimental::basic_string_view::operator= + +.SH Synopsis + basic_string_view& operator=( const basic_string_view& (library fundamentals TS) + view ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::experimental::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::operator[].3 b/man/std::experimental::basic_string_view::operator[].3 new file mode 100644 index 000000000..7d32e4ff5 --- /dev/null +++ b/man/std::experimental::basic_string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::experimental::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator[] \- std::experimental::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[](size_type pos) (library fundamentals TS) + const; + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character + +.SH Exceptions + + Does not throw + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = "Exemplar"; + std::experimental::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at access specified character with bounds checking + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::rbegin,.3 b/man/std::experimental::basic_string_view::rbegin,.3 new file mode 100644 index 000000000..5f3041018 --- /dev/null +++ b/man/std::experimental::basic_string_view::rbegin,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rbegin, \- std::experimental::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crbegin() const (library fundamentals TS) + noexcept; + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::remove_prefix.3 b/man/std::experimental::basic_string_view::remove_prefix.3 new file mode 100644 index 000000000..6b4896fca --- /dev/null +++ b/man/std::experimental::basic_string_view::remove_prefix.3 @@ -0,0 +1,51 @@ +.TH std::experimental::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_prefix \- std::experimental::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix(size_type n); (library fundamentals TS) + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = " trim me"; + std::experimental::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::remove_suffix.3 b/man/std::experimental::basic_string_view::remove_suffix.3 new file mode 100644 index 000000000..f1152e212 --- /dev/null +++ b/man/std::experimental::basic_string_view::remove_suffix.3 @@ -0,0 +1,54 @@ +.TH std::experimental::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_suffix \- std::experimental::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); (library fundamentals TS) + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::experimental::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::rend,.3 b/man/std::experimental::basic_string_view::rend,.3 new file mode 100644 index 000000000..e8bb706e2 --- /dev/null +++ b/man/std::experimental::basic_string_view::rend,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rend, \- std::experimental::basic_string_view::rend, + +.SH Synopsis + + constexpr const_reverse_iterator rend() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crend() const noexcept; (library fundamentals TS) + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::rfind.3 b/man/std::experimental::basic_string_view::rfind.3 new file mode 100644 index 000000000..e6512905c --- /dev/null +++ b/man/std::experimental::basic_string_view::rfind.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rfind \- std::experimental::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = npos) const noexcept; + constexpr size_type rfind(CharT c, size_type pos = \fB(2)\fP (library fundamentals TS) + npos) const noexcept; + constexpr size_type rfind(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type rfind(const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + pos = npos) const; + + Finds the last substring equal to the given character sequence. + + 1) Finds the last occurence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(&c, 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::size,.3 b/man/std::experimental::basic_string_view::size,.3 new file mode 100644 index 000000000..d7e0c24ba --- /dev/null +++ b/man/std::experimental::basic_string_view::size,.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::size, \- std::experimental::basic_string_view::size, + +.SH Synopsis + + constexpr size_type size() const noexcept; (library fundamentals TS) + constexpr size_type length() const noexcept; (library fundamentals TS) + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::substr.3 b/man/std::experimental::basic_string_view::substr.3 new file mode 100644 index 000000000..ac0ecbb2e --- /dev/null +++ b/man/std::experimental::basic_string_view::substr.3 @@ -0,0 +1,37 @@ +.TH std::experimental::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::substr \- std::experimental::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view + substr(size_type pos = 0, size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rcount), where rcount is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rcount). + +.SH Exceptions + + std::out_of_range if pos > size() + +.SH Complexity + + Constant. + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::swap.3 b/man/std::experimental::basic_string_view::swap.3 new file mode 100644 index 000000000..a183aebcd --- /dev/null +++ b/man/std::experimental::basic_string_view::swap.3 @@ -0,0 +1,23 @@ +.TH std::experimental::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::swap \- std::experimental::basic_string_view::swap + +.SH Synopsis + constexpr void swap(basic_string_view& v) noexcept; (library fundamentals TS) + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::basic_string_view::to_string,.3 b/man/std::experimental::basic_string_view::to_string,.3 new file mode 100644 index 000000000..7f51adeb3 --- /dev/null +++ b/man/std::experimental::basic_string_view::to_string,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::to_string, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::to_string, \- std::experimental::basic_string_view::to_string, + +.SH Synopsis + + template> + + basic_string (library fundamentals TS) + + to_string(const Allocator& a = Allocator()) const; + template + explicit operator basic_string() const; + + Creates a basic_string with a copy of the content of the current view. + +.SH Template parameters + + Allocator - Allocator type used to allocate internal storage + +.SH Parameters + + a - Allocator instance to use for allocating the new string + +.SH Return value + + A basic_string containing a copy of the characters of the current view. + +.SH Complexity + + Linear in size() + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::boyer_moore_horspool_searcher,.3 b/man/std::experimental::boyer_moore_horspool_searcher,.3 new file mode 100644 index 000000000..6d15ce0ed --- /dev/null +++ b/man/std::experimental::boyer_moore_horspool_searcher,.3 @@ -0,0 +1,159 @@ +.TH std::experimental::boyer_moore_horspool_searcher, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::boyer_moore_horspool_searcher, \- std::experimental::boyer_moore_horspool_searcher, + +.SH Synopsis + + Defined in header + template< class RandomIt1, + + class Hash = std::hash::value_type>, fundamentals TS) + class BinaryPredicate = std::equal_to<> > + + class boyer_moore_horspool_searcher; + + A searcher suitable for use with std::experimental::search that implements the + Boyer-Moore-Horspool string searching algorithm. + + boyer_moore_horspool_searcher is CopyConstructible and CopyAssignable. + + RandomIt1 must meet the requirements of LegacyRandomAccessIterator. + +.SH Member functions + +std::experimental::boyer_moore_horspool_searcher::boyer_moore_horspool_searcher + + boyer_moore_horspool_searcher( RandomIt1 pat_first, + + RandomIt1 pat_last, + Hash hf = Hash(), + + BinaryPredicate pred = BinaryPredicate() ); + + Constructs a boyer_moore_horspool_searcher by storing copies of pat_first, pat_last, + hf, and pred, setting up any necessary internal data structures. + + The value type of RandomIt1 must be DefaultConstructible, CopyConstructible and + CopyAssignable. + + For any two values A and B of the type std::iterator_traits::value_type, + if pred(A, B) == true, then hf(A) == hf(B) shall be true. + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + hf - a callable object used to hash the elements of the string + pred - a callable object used to determine equality + +.SH Exceptions + + Any exceptions thrown by + + * the copy constructor of RandomIt1; + * the default constructor, copy constructor, or copy assignment operator of the + value type of RandomIt1; or + * the copy constructor or function call operator of BinaryPredicate or Hash. + + May also throw std::bad_alloc if additional memory required for internal data + structures cannot be allocated. + +std::experimental::boyer_moore_horspool_searcher::operator() + + template< class RandomIt2 > \fI(until C++17)\fP + RandomIt2 operator()( RandomIt2 first, RandomIt2 last ) const; + template< class RandomIt2 > + std::pair operator()( RandomIt2 first, RandomIt2 \fI(since C++17)\fP + last ) const; + + The member function called by std::experimental::search to perform a search with + this searcher. RandomIt2 must meet the requirements of LegacyRandomAccessIterator. + + RandomIt1 and RandomIt2 must have the same value type. + +.SH Parameters + + first, last - a pair of iterators designating the string to be examined + +.SH Return value + + If the pattern [pat_first, pat_last) is empty, returns first. + + Otherwise, an iterator to the first position in [first, last) where a \fI(until C++17)\fP + subsequence that compares equal to [pat_first, pat_last) as defined by + pred is located, or a copy of last otherwise. + If the pattern [pat_first, pat_last) is empty, returns + make_pair(first, first). + + Otherwise, returns a pair of iterators to the first and one past last \fI(since C++17)\fP + positions in [first, last) where a subsequence that compares equal to + [pat_first, pat_last) as defined by pred is located, or + make_pair(last, last) otherwise. + + Helper Functions + + template< class RandomIt, + + class Hash = std::hash::value_type>, + class BinaryPredicate = std::equal_to<> > + boyer_moore_horspool_searcher (library + make_boyer_moore_horspool_searcher( RandomIt pat_first, fundamentals TS) + RandomIt pat_last, + Hash hf = Hash(), + + BinaryPredicate pred = + BinaryPredicate() ); + + Helper function that constructs a std::experimental::boyer_moore_horspool_searcher + using template argument deduction. Equivalent to return + boyer_moore_horspool_searcher(pat_first, pat_last, + hf, pred); + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + hf - a callable object used to hash the elements of the string + pred - a callable object used to determine equality + +.SH Return value + + A boyer_moore_horspool_searcher constructed with the arguments pat_first, pat_last, + hf, and pred. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string in = "Lorem ipsum dolor sit amet, consectetur adipiscing elit," + " sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + std::string needle = "pisci"; + auto it = std::experimental::search(in.begin(), in.end(), + std::experimental::make_boyer_moore_horspool_searcher( + needle.begin(), needle.end())); + if (it != in.end()) + std::cout << "The string " << needle << " found at offset " + << it - in.begin() << '\\n'; + else + std::cout << "The string " << needle << " not found\\n"; + } + +.SH Output: + + The string pisci found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::boyer_moore_searcher,std::experimental::make_boyer_moore_searcher.3 b/man/std::experimental::boyer_moore_searcher,std::experimental::make_boyer_moore_searcher.3 new file mode 100644 index 000000000..ceebd258e --- /dev/null +++ b/man/std::experimental::boyer_moore_searcher,std::experimental::make_boyer_moore_searcher.3 @@ -0,0 +1,157 @@ +.TH std::experimental::boyer_moore_searcher,std::experimental::make_boyer_moore_searcher 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::boyer_moore_searcher,std::experimental::make_boyer_moore_searcher \- std::experimental::boyer_moore_searcher,std::experimental::make_boyer_moore_searcher + +.SH Synopsis + Defined in header + template< class RandomIt1, + + class Hash = std::hash::value_type>, fundamentals TS) + class BinaryPredicate = std::equal_to<> > + + class boyer_moore_searcher; + + A searcher suitable for use with std::experimental::search that implements the + Boyer-Moore string searching algorithm. + + boyer_moore_searcher is CopyConstructible and CopyAssignable. + + RandomIt1 must meet the requirements of LegacyRandomAccessIterator. + +.SH Member functions + +std::experimental::boyer_moore_searcher::boyer_moore_searcher + + boyer_moore_searcher( RandomIt1 pat_first, + + RandomIt1 pat_last, + Hash hf = Hash(), + + BinaryPredicate pred = BinaryPredicate() ); + + Constructs a boyer_moore_searcher by storing copies of pat_first, pat_last, hf, and + pred, setting up any necessary internal data structures. + + The value type of RandomIt1 must be DefaultConstructible, CopyConstructible and + CopyAssignable. + + For any two values A and B of the type std::iterator_traits::value_type, + if pred(A, B) == true, then hf(A) == hf(B) shall be true. + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + hf - a callable object used to hash the elements of the string + pred - a callable object used to determine equality + +.SH Exceptions + + Any exceptions thrown by + + * the copy constructor of RandomIt1; + * the default constructor, copy constructor, and copy assignment operator of the + value type of RandomIt1; or + * the copy constructor and function call operator of BinaryPredicate or Hash. + + May also throw std::bad_alloc if additional memory required for internal data + structures cannot be allocated. + +std::experimental::boyer_moore_searcher::operator() + + template< class RandomIt2 > \fI(until C++17)\fP + RandomIt2 operator()( RandomIt2 first, RandomIt2 last ) const; + template< class RandomIt2 > + std::pair operator()( RandomIt2 first, RandomIt2 \fI(since C++17)\fP + last ) const; + + The member function called by std::experimental::search to perform a search with + this searcher. RandomIt2 must meet the requirements of LegacyRandomAccessIterator. + + RandomIt1 and RandomIt2 must have the same value type. + +.SH Parameters + + first, last - a pair of iterators designating the string to be examined + +.SH Return value + + If the pattern [pat_first, pat_last) is empty, returns first. + + Otherwise, an iterator to the first position in [first, last) where a \fI(until C++17)\fP + subsequence that compares equal to [pat_first, pat_last) as defined by + pred is located, or a copy of last otherwise. + If the pattern [pat_first, pat_last) is empty, returns + make_pair(first, first). + + Otherwise, returns a pair of iterators to the first and one past last \fI(since C++17)\fP + positions in [first, last) where a subsequence that compares equal to + [pat_first, pat_last) as defined by pred is located, or + make_pair(last, last) otherwise. + + Helper Functions + + template< class RandomIt, + + class Hash = std::hash::value_type>, + class BinaryPredicate = std::equal_to<> > + boyer_moore_searcher (library + make_boyer_moore_searcher( fundamentals TS) + RandomIt pat_first, + RandomIt pat_last, + Hash hf = Hash(), + + BinaryPredicate pred = BinaryPredicate()); + + Helper function that constructs a std::experimental::boyer_moore_searcher using + template argument deduction. Equivalent to return boyer_moore_searcher(pat_first, pat_last, hf, pred); + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + hf - a callable object used to hash the elements of the string + pred - a callable object used to determine equality + +.SH Return value + + A boyer_moore_searcher constructed with the arguments pat_first, pat_last, hf, and + pred. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string in = "Lorem ipsum dolor sit amet, consectetur adipiscing elit," + " sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + std::string needle = "pisci"; + auto it = std::experimental::search(in.begin(), in.end(), + std::experimental::make_boyer_moore_searcher( + needle.begin(), needle.end())); + if (it != in.end()) + std::cout << "The string " << needle << " found at offset " + << it - in.begin() << '\\n'; + else + std::cout << "The string " << needle << " not found\\n"; + } + +.SH Output: + + The string pisci found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::clamp.3 b/man/std::experimental::clamp.3 new file mode 100644 index 000000000..0769c5c51 --- /dev/null +++ b/man/std::experimental::clamp.3 @@ -0,0 +1,72 @@ +.TH std::experimental::clamp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::clamp \- std::experimental::clamp + +.SH Synopsis + Defined in header + template< class T, class Abi > + + simd (parallelism TS v2) + + clamp( const simd& v, const simd& lo, const + simd& hi ); + +.SH Parameters + + v - the elements to clamp + lo, hi - the boundaries to clamp v to + +.SH Return value + + The result of element-wise application of std::clamp(v[i], lo[i], hi[i]) for all i ∈ + [0, size()). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + namespace stdx = std::experimental; + + void println(auto rem, auto const v) + { + std::cout << rem << ": "; + for (std::size_t i = 0; i != v.size(); ++i) + std::cout << std::setw(4) << v[i] << ' '; + std::cout << '\\n'; + } + + int main() + { + stdx::fixed_size_simd a{[](int i) { + static constexpr auto c = {-129, -128, -1, 0, 42, 127, 128, 255}; + return c.begin()[i]; + }}; + println("a", a); + + stdx::fixed_size_simd lo1{INT8_MIN}; + stdx::fixed_size_simd hi1{INT8_MAX}; + const auto b = stdx::clamp(a, lo1, hi1); + println("b", b); + + stdx::fixed_size_simd lo2{0}; + stdx::fixed_size_simd hi2{UINT8_MAX}; + const auto c = stdx::clamp(a, lo2, hi2); + println("c", c); + } + +.SH Output: + + a: -129 -128 -1 0 42 127 128 255 + b: -128 -128 -1 0 42 127 127 127 + c: 0 0 0 0 42 127 128 255 + +.SH See also + + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::experimental::concat.3 b/man/std::experimental::concat.3 new file mode 100644 index 000000000..340dea7c0 --- /dev/null +++ b/man/std::experimental::concat.3 @@ -0,0 +1,29 @@ +.TH std::experimental::concat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::concat \- std::experimental::concat + +.SH Synopsis + Defined in header + template< class T, class... Abis > + + simd + ...)>> \fB(1)\fP (parallelism TS v2) + + concat( const simd&... vs ) noexcept; + template< class T, class... Abis > + + simd_mask + \fB(2)\fP (parallelism TS v2) + ...)>> + + concat( const simd_mask&... vs ) noexcept; + + Concatenates the input simd or simd_mask objects. + + Parameter + + vs - the input simd or simd_mask parameter pack + +.SH Return value + + The concatenated result of a single simd or simd_mask object. + +.SH Example diff --git a/man/std::experimental::conjunction.3 b/man/std::experimental::conjunction.3 new file mode 100644 index 000000000..f9c1479ef --- /dev/null +++ b/man/std::experimental::conjunction.3 @@ -0,0 +1,91 @@ +.TH std::experimental::conjunction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::conjunction \- std::experimental::conjunction + +.SH Synopsis + Defined in header + template< class... B > (library fundamentals TS v2) + struct conjunction; + + Forms the logical conjunction of the type traits B..., effectively performing a + logical AND on the sequence of traits. + + The specialization std::experimental::conjunction has a public and + unambiguous base that is + + * if sizeof...(B) == 0, std::true_type; otherwise + * the first type Bi in B1, ..., BN for which bool(Bi::value) == false, or BN if + there is no such type. + + The member names of the base class, other than conjunction and operator=, are not + hidden and are unambiguously available in conjunction. + + Conjunction is short-circuiting: if there is a template type argument Bi with + bool(Bi::value) == false, then instantiating conjunction::value does + not require the instantiation of Bj::value for j > i. + +.SH Template parameters + + B... - every template argument Bi for which Bi::value is instantiated must be usable + as a base class and define member value that is convertible to bool + + Helper variable template + + template< class... B > + constexpr bool conjunction_v = (library fundamentals TS v2) + conjunction::value; + +.SH Possible implementation + + template struct conjunction : std::true_type {}; + template struct conjunction : B1 {}; + template + struct conjunction + : std::conditional_t, B1> {}; + +.SH Notes + + A specialization of conjunction does not necessarily inherit from either + std::true_type or std::false_type: it simply inherits from the first B + whose ::value, converted to bool, is false, or from the very last B when all of them + convert to true. For example, conjunction, + std::integral_constant>::value is 4. + +.SH Example + + +// Run this code + + #include + #include + + // func is enabled if all Ts... have the same type + template + constexpr std::enable_if_t...>> + func(T, Ts...) + { + std::cout << "All types are the same.\\n"; + } + + template + constexpr std::enable_if_t...>> + func(T, Ts...) + { + std::cout << "Types differ.\\n"; + } + + int main() + { + func(1, 2'7, 3'1); + func(1, 2.7, '3'); + } + +.SH Output: + + All types are the same. + Types differ. + +.SH See also + + conjunction variadic logical AND metafunction + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::experimental::const_where_expression.3 b/man/std::experimental::const_where_expression.3 new file mode 100644 index 000000000..17fdb38c5 --- /dev/null +++ b/man/std::experimental::const_where_expression.3 @@ -0,0 +1,36 @@ +.TH std::experimental::const_where_expression 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::const_where_expression \- std::experimental::const_where_expression + +.SH Synopsis + Defined in header + template< class M, class V > (parallelism TS v2) + class const_where_expression; + + The class template const_where_expression abstracts the notion of selected elements + of a given const object of arithmetic or data-parallel type. Selected elements + signifies the elements data[i] for all i ∈ { j ∈ ℕ | j < M::size() ⋀ mask[j] }. + +.SH Template parameters + + M - The mask type + V - The value type M applies on + + Valid combinations of (M, V) are: (simd_mask, const simd), + (simd_mask, const simd_mask), (bool, const T). + +.SH Member functions + + operator- unary operators + operator+ \fI(public member function)\fP + operator~ + copy_to stores selected elements to address + \fI(public member function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::default_searcher,std::experimental::make_default_searcher.3 b/man/std::experimental::default_searcher,std::experimental::make_default_searcher.3 new file mode 100644 index 000000000..40326d0f2 --- /dev/null +++ b/man/std::experimental::default_searcher,std::experimental::make_default_searcher.3 @@ -0,0 +1,133 @@ +.TH std::experimental::default_searcher,std::experimental::make_default_searcher 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::default_searcher,std::experimental::make_default_searcher \- std::experimental::default_searcher,std::experimental::make_default_searcher + +.SH Synopsis + Defined in header + template< class ForwardIterator1, class BinaryPredicate = + std::equal_to<> > (library fundamentals TS) + class default_searcher; + + A class suitable for use with std::experimental::search that delegates the search + operation to the standard library's std::search. + + default_searcher is CopyConstructible and CopyAssignable. + +.SH Member functions + +std::experimental::default_searcher::default_searcher + + default_searcher( ForwardIterator pat_first, + + ForwardIterator pat_last, + + BinaryPredicate pred = BinaryPredicate() ); + + Constructs a default_searcher by storing copies of pat_first, pat_last, and pred. + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + pred - a callable object used to determine equality + +.SH Exceptions + + Any exceptions thrown by the copy constructors of BinaryPredicate or + ForwardIterator. + +std::experimental::default_searcher::operator() + + template< class ForwardIterator2 > + ForwardIterator2 operator()( ForwardIterator2 first, ForwardIterator2 \fI(until C++17)\fP + last ) const; + template< class ForwardIterator2 > + + std::pair \fI(since C++17)\fP + + operator()( ForwardIterator2 first, ForwardIterator2 last ) + const; + + The member function called by std::experimental::search to perform a search with + this searcher. + + Equivalent to std::search(first, last, pat_first, pat_last, pred);. \fI(until C++17)\fP + Returns a pair of iterators i, j, where i is std::search(first, last, + pat_first, pat_last, pred) and j is std::next(i, \fI(until C++17)\fP + std::distance(pat_first, pat_last)) unless std::search returned last + (no match), in which case j equals last as well. + +.SH Parameters + + first, last - a pair of iterators designating the string to be examined + +.SH Return value + + Iterator to the first position in [first, last) where a subsequence + that compares equal to [pat_first, pat_last) as defined by pred is \fI(until C++17)\fP + located, or a copy of last otherwise. + A pair of iterators to the first and one past last positions in + [first, last) where a subsequence that compares equal to \fI(since C++17)\fP + [pat_first, pat_last) as defined by pred is located, or a pair of + copies of last otherwise. + + Helper Functions + + template< class ForwardIterator, class BinaryPredicate = + std::equal_to<> > + + default_searcher (library fundamentals + make_default_searcher( TS) + ForwardIterator pat_first, + ForwardIterator pat_last, + + BinaryPredicate pred = BinaryPredicate()); + + Helper function that constructs a std::experimental::default_searcher using template + argument deduction. Equivalent to return default_searcher(pat_first, pat_last, pred); + +.SH Parameters + + pat_first, pat_last - a pair of iterators designating the string to be searched for + pred - a callable object used to determine equality + +.SH Return value + + A default_searcher constructed with the arguments pat_first, pat_last, pred. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string in = "Lorem ipsum dolor sit amet, consectetur adipiscing elit," + " sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + std::string needle = "pisci"; + auto it = std::experimental::search(in.begin(), in.end(), + std::experimental::make_default_searcher( + needle.begin(), needle.end())); + if (it != in.end()) + std::cout << "The string " << needle << " found at offset " + << it - in.begin() << '\\n'; + else + std::cout << "The string " << needle << " not found\\n"; + } + +.SH Output: + + The string pisci found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::disjunction.3 b/man/std::experimental::disjunction.3 new file mode 100644 index 000000000..e745d692f --- /dev/null +++ b/man/std::experimental::disjunction.3 @@ -0,0 +1,65 @@ +.TH std::experimental::disjunction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::disjunction \- std::experimental::disjunction + +.SH Synopsis + Defined in header + template< class... B > (library fundamentals TS v2) + struct disjunction; + + Forms the logical disjunction of the type traits B..., effectively performing a + logical or on the sequence of traits. + + The specialization std::experimental::disjunction has a public and + unambiguous base that is + + * if sizeof...(B) == 0, std::false_type; otherwise + * the first type Bi in B1, ..., BN for which bool(Bi::value) == true, or BN if + there is no such type. + + The member names of the base class, other than disjunction and operator=, are not + hidden and are unambiguously available in disjunction. + + Disjunction is short-circuiting: if there is a template type argument Bi with + bool(Bi::value) != false, then instantiating disjunction::value does + not require the instantiation of Bj::value for j > i. + +.SH Template parameters + + B... - every template argument Bi for which Bi::value is instantiated must be usable + as a base class and define member value that is convertible to bool + + Helper variable template + + template< class... B > + constexpr bool disjunction_v = (library fundamentals TS v2) + disjunction::value; + +.SH Possible implementation + + template struct disjunction : std::false_type {}; + template struct disjunction : B1 {}; + template + struct disjunction + : std::conditional_t> {}; + +.SH Notes + + A specialization of disjunction does not necessarily inherit from of either + std::true_type or std::false_type: it simply inherits from the first B whose + ::value, explicitly converted to bool, is true, or from the very last B when all of + them convert to false. For example, disjunction, + std::integral_constant>::value is 2. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + disjunction variadic logical OR metafunction + \fI(C++17)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::element_aligned_tag,std::experimental::element_aligned.3 b/man/std::experimental::element_aligned_tag,std::experimental::element_aligned.3 new file mode 100644 index 000000000..bc9d61d14 --- /dev/null +++ b/man/std::experimental::element_aligned_tag,std::experimental::element_aligned.3 @@ -0,0 +1,20 @@ +.TH std::experimental::element_aligned_tag,std::experimental::element_aligned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::element_aligned_tag,std::experimental::element_aligned \- std::experimental::element_aligned_tag,std::experimental::element_aligned + +.SH Synopsis + Defined in header + struct element_aligned_tag {}; (parallelism TS v2) + inline constexpr element_aligned_tag element_aligned{}; + + This tag type indicates that the buffer of copy_from and copy_to is aligned to its + element alignment. + +.SH See also + + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + overaligned_tag flag indicating alignment of the load/store address to the + overaligned specified alignment + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::erase(std::basic_string).3 b/man/std::experimental::erase(std::basic_string).3 new file mode 100644 index 000000000..82bfac289 --- /dev/null +++ b/man/std::experimental::erase(std::basic_string).3 @@ -0,0 +1,52 @@ +.TH std::experimental::erase(std::basic_string) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase(std::basic_string) \- std::experimental::erase(std::basic_string) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class A, class U + > (library fundamentals TS v2) + void erase( std::basic_string& c, + const U& value ); + + Erases all elements that compare equal to value from the container. Equivalent to + c.erase(std::remove(c.begin(), c.end(), value), c.end());. + +.SH Parameters + + c - container from which to erase + value - value to be removed + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string data{"$$P$A$S$S$$W$O$R$$D$"}; + std::cout << data << '\\n'; + auto crack{'$'}; + std::experimental::erase(data, crack); + std::cout << data << '\\n'; + } + +.SH Output: + + $$P$A$S$S$$W$O$R$$D$ + PASSWORD + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + erase_if (std::basic_string) erases all elements satisfying a predicate from a + (library fundamentals 2 TS) std::basic_string + \fI(function template)\fP diff --git a/man/std::experimental::erase(std::deque).3 b/man/std::experimental::erase(std::deque).3 new file mode 100644 index 000000000..03222eb98 --- /dev/null +++ b/man/std::experimental::erase(std::deque).3 @@ -0,0 +1,56 @@ +.TH std::experimental::erase(std::deque) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase(std::deque) \- std::experimental::erase(std::deque) + +.SH Synopsis + Defined in header + template< class T, class A, class U > (library fundamentals TS v2) + void erase( std::deque& c, const U& value ); + + Erases all elements that compare equal to value from the container. Equivalent to + c.erase(std::remove(c.begin(), c.end(), value), c.end());. + +.SH Parameters + + c - container from which to erase + value - value to be removed + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + auto show = [](const auto& container) + { + for (auto e : container) + std::cout << e; + std::cout << '\\n'; + }; + + int main() + { + std::deque data{1, 1, 1, 4, 1, 1, 1, 2, 1, 1, 1}; + show(data); + std::experimental::erase(data, 1); + show(data); + } + +.SH Output: + + 11141112111 + 42 + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + erase_if (std::deque) erases all elements satisfying a predicate from a + (library fundamentals 2 TS) std::deque + \fI(function template)\fP diff --git a/man/std::experimental::erase(std::forward_list).3 b/man/std::experimental::erase(std::forward_list).3 new file mode 100644 index 000000000..d25ccceb1 --- /dev/null +++ b/man/std::experimental::erase(std::forward_list).3 @@ -0,0 +1,66 @@ +.TH std::experimental::erase(std::forward_list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase(std::forward_list) \- std::experimental::erase(std::forward_list) + +.SH Synopsis + Defined in header + template< class T, class A, class U > + void erase( std::forward_list& c, const U& value (library fundamentals TS v2) + ); + + Erases all elements that compare equal to value from the container. Equivalent to + c.remove_if([&](auto& elem) { return elem == value; });. + +.SH Parameters + + c - container from which to erase + value - value to be removed + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + auto show = [](const auto& container) + { + for (auto e : container) + std::cout << e; + std::cout << '\\n'; + }; + + int main() + { + std::forward_list data{1, 1, 1, 4, 1, 1, 1, 2, 1, 1, 1}; + show(data); + std::experimental::erase(data, 1); + show(data); + } + +.SH Output: + + 11141112111 + 42 + +.SH Notes + + Unlike std::forward_list::remove, this function template accepts heterogeneous types + and does not force a conversion to the container's value type before invoking the == + operator. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI\fI(public member\fP function of\fP + std::forward_list) + erase_if (std::forward_list) erases all elements satisfying a predicate from a + (library fundamentals 2 TS) std::forward_list + \fI(function template)\fP diff --git a/man/std::experimental::erase(std::list).3 b/man/std::experimental::erase(std::list).3 new file mode 100644 index 000000000..7724a96cb --- /dev/null +++ b/man/std::experimental::erase(std::list).3 @@ -0,0 +1,65 @@ +.TH std::experimental::erase(std::list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase(std::list) \- std::experimental::erase(std::list) + +.SH Synopsis + Defined in header + template< class T, class A, class U > (library fundamentals TS v2) + void erase( std::list& c, const U& value ); + + Erases all elements that compare equal to value from the container. Equivalent to + c.remove_if([&](auto& elem) { return elem == value; });. + +.SH Parameters + + c - container from which to erase + value - value to be removed + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + auto show = [](const auto& container) + { + for (auto e : container) + std::cout << e; + std::cout << '\\n'; + }; + + int main() + { + std::list data{1, 1, 1, 4, 1, 1, 1, 2, 1, 1, 1}; + show(data); + std::experimental::erase(data, 1); + show(data); + } + +.SH Output: + + 11141112111 + 42 + +.SH Notes + + Unlike std::list::remove, this function template accepts heterogeneous types and + does not force a conversion to the container's value type before invoking the == + operator. + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(public member function of std::list)\fP + + erase_if (std::list) erases all elements satisfying a predicate from a + (library fundamentals 2 TS) std::list + \fI(function template)\fP diff --git a/man/std::experimental::erase(std::vector).3 b/man/std::experimental::erase(std::vector).3 new file mode 100644 index 000000000..007504ac4 --- /dev/null +++ b/man/std::experimental::erase(std::vector).3 @@ -0,0 +1,56 @@ +.TH std::experimental::erase(std::vector) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase(std::vector) \- std::experimental::erase(std::vector) + +.SH Synopsis + Defined in header + template< class T, class A, class U > (library fundamentals TS v2) + void erase( std::vector& c, const U& value ); + + Erases all elements that compare equal to value from the container. Equivalent to + c.erase(std::remove(c.begin(), c.end(), value), c.end());. + +.SH Parameters + + c - container from which to erase + value - value to be removed + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + auto show = [](const auto& container) + { + for (auto e : container) + std::cout << e; + std::cout << '\\n'; + }; + + int main() + { + std::vector data{1, 1, 1, 4, 1, 1, 1, 2, 1, 1, 1}; + show(data); + std::experimental::erase(data, 1); + show(data); + } + +.SH Output: + + 11141112111 + 42 + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + erase_if (std::vector) erases all elements satisfying a predicate from a + (library fundamentals 2 TS) std::vector + \fI(function template)\fP diff --git a/man/std::experimental::erase_if(std::basic_string).3 b/man/std::experimental::erase_if(std::basic_string).3 new file mode 100644 index 000000000..3bc1658ef --- /dev/null +++ b/man/std::experimental::erase_if(std::basic_string).3 @@ -0,0 +1,56 @@ +.TH std::experimental::erase_if(std::basic_string) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::basic_string) \- std::experimental::erase_if(std::basic_string) + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class Alloc, + class Pred > (library fundamentals TS v2) + void erase_if( std::basic_string& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to c.erase(std::remove_if(c.begin(), c.end(), pred), c.end());. + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string data{"1337!p_C00L_ + template< class T, class Alloc, class Pred > (library fundamentals TS v2) + void erase_if( std::deque& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to c.erase(std::remove_if(c.begin(), c.end(), pred), c.end());. + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::deque data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + { 3 3 4 5 5 6 6 7 2 1 0 } + Erase all items divisible by 3: + { 4 5 5 7 2 1 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + erase (std::deque) erases all elements equal to a specific value from a + (library fundamentals 2 TS) std::deque + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::forward_list).3 b/man/std::experimental::erase_if(std::forward_list).3 new file mode 100644 index 000000000..b2ed4cb0d --- /dev/null +++ b/man/std::experimental::erase_if(std::forward_list).3 @@ -0,0 +1,68 @@ +.TH std::experimental::erase_if(std::forward_list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::forward_list) \- std::experimental::erase_if(std::forward_list) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class Pred > + void erase_if( std::forward_list& c, Pred (library fundamentals TS v2) + pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to c.remove_if(pred);. + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::forward_list data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + { 3 3 4 5 5 6 6 7 2 1 0 } + Erase all items divisible by 3: + { 4 5 5 7 2 1 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI\fI(public member\fP function of\fP + std::forward_list) + erase (std::forward_list) erases all elements equal to a specific value from a + (library fundamentals 2 TS) std::forward_list + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::list).3 b/man/std::experimental::erase_if(std::list).3 new file mode 100644 index 000000000..24b03489b --- /dev/null +++ b/man/std::experimental::erase_if(std::list).3 @@ -0,0 +1,67 @@ +.TH std::experimental::erase_if(std::list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::list) \- std::experimental::erase_if(std::list) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class Pred > (library fundamentals TS v2) + void erase_if( std::list& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to c.remove_if(pred);. + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::list data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + { 3 3 4 5 5 6 6 7 2 1 0 } + Erase all items divisible by 3: + { 4 5 5 7 2 1 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(public member function of std::list)\fP + + erase (std::list) erases all elements equal to a specific value from a + (library fundamentals 2 TS) std::list + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::map).3 b/man/std::experimental::erase_if(std::map).3 new file mode 100644 index 000000000..4e04ccfd5 --- /dev/null +++ b/man/std::experimental::erase_if(std::map).3 @@ -0,0 +1,74 @@ +.TH std::experimental::erase_if(std::map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::map) \- std::experimental::erase_if(std::map) + +.SH Synopsis + Defined in header + template< class Key, class T, class Compare, class + Alloc, class Pred > (library fundamentals TS v2) + void erase_if( std::map& c, + Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& cont) + { + os << '{'; + for (const auto& item : cont) + os << '{' << item.first << ", " << item.second << '}'; + return os << '}'; + } + + int main() + { + std::map data{{1, 'a'},{2, 'b'},{3, 'c'},{4, 'd'}, + {5, 'e'},{4, 'f'},{5, 'g'},{5, 'g'}}; + std::cout << "Original:\\n" << data << '\\n'; + std::experimental::erase_if(data, [](const auto& item) + { + return (item.first & 1) == 1; + }); + std::cout << "Erase items with odd keys:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + {{1, a}{2, b}{3, c}{4, d}{5, e}} + Erase items with odd keys: + {{2, b}{4, d}} + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::multimap).3 b/man/std::experimental::erase_if(std::multimap).3 new file mode 100644 index 000000000..e95d46e33 --- /dev/null +++ b/man/std::experimental::erase_if(std::multimap).3 @@ -0,0 +1,74 @@ +.TH std::experimental::erase_if(std::multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::multimap) \- std::experimental::erase_if(std::multimap) + +.SH Synopsis + Defined in header + template< class Key, class T, class Compare, class + Alloc, class Pred > (library fundamentals TS v2) + void erase_if( std::multimap& + c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& cont) + { + os << '{'; + for (const auto& item : cont) + os << '{' << item.first << ", " << item.second << '}'; + return os << '}'; + } + + int main() + { + std::multimap data{{1, 'a'},{2, 'b'},{3, 'c'},{4, 'd'}, + {5, 'e'},{4, 'f'},{5, 'g'},{5, 'g'}}; + std::cout << "Original:\\n" << data << '\\n'; + std::experimental::erase_if(data, [](const auto& item) + { + return (item.first & 1) == 1; + }); + std::cout << "Erase items with odd keys:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + {{1, a}{2, b}{3, c}{4, d}{4, f}{5, e}{5, g}{5, g}} + Erase items with odd keys: + {{2, b}{4, d}{4, f}} + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::multiset).3 b/man/std::experimental::erase_if(std::multiset).3 new file mode 100644 index 000000000..feeecac74 --- /dev/null +++ b/man/std::experimental::erase_if(std::multiset).3 @@ -0,0 +1,71 @@ +.TH std::experimental::erase_if(std::multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::multiset) \- std::experimental::erase_if(std::multiset) + +.SH Synopsis + Defined in header + template< class Key, class Compare, class Alloc, class + Pred > (library fundamentals TS v2) + void erase_if( std::multiset& c, + Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::multiset data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + { 0 1 2 3 3 4 5 5 6 6 7 } + Erase all items divisible by 3: + { 1 2 4 5 5 7 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::set).3 b/man/std::experimental::erase_if(std::set).3 new file mode 100644 index 000000000..96169be04 --- /dev/null +++ b/man/std::experimental::erase_if(std::set).3 @@ -0,0 +1,71 @@ +.TH std::experimental::erase_if(std::set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::set) \- std::experimental::erase_if(std::set) + +.SH Synopsis + Defined in header + template< class Key, class Compare, class Alloc, class + Pred > (library fundamentals TS v2) + void erase_if( std::set& c, Pred + pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::set data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + { 0 1 2 3 4 5 6 7 } + Erase all items divisible by 3: + { 1 2 4 5 7 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::unordered_map).3 b/man/std::experimental::erase_if(std::unordered_map).3 new file mode 100644 index 000000000..bd8864fad --- /dev/null +++ b/man/std::experimental::erase_if(std::unordered_map).3 @@ -0,0 +1,74 @@ +.TH std::experimental::erase_if(std::unordered_map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::unordered_map) \- std::experimental::erase_if(std::unordered_map) + +.SH Synopsis + Defined in header + template< class Key, class T, class Hash, class KeyEqual, + class Alloc, class Pred > (library fundamentals TS + void erase_if( std::unordered_map& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& cont) + { + os << '{'; + for (const auto& item : cont) + os << '{' << item.first << ", " << item.second << '}'; + return os << '}'; + } + + int main() + { + std::unordered_map data{{1, 'a'},{2, 'b'},{3, 'c'},{4, 'd'}, + {5, 'e'},{4, 'f'},{5, 'g'},{5, 'g'}}; + std::cout << "Original:\\n" << data << '\\n'; + std::experimental::erase_if(data, [](const auto& item) + { + return (item.first & 1) == 1; + }); + std::cout << "Erase items with odd keys:\\n" << data << '\\n'; + } + +.SH Possible output: + + Original: + {{5, e}{4, d}{3, c}{2, b}{1, a}} + Erase items with odd keys: + {{4, d}{2, b}} + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::unordered_multimap).3 b/man/std::experimental::erase_if(std::unordered_multimap).3 new file mode 100644 index 000000000..4f7e5e478 --- /dev/null +++ b/man/std::experimental::erase_if(std::unordered_multimap).3 @@ -0,0 +1,74 @@ +.TH std::experimental::erase_if(std::unordered_multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::unordered_multimap) \- std::experimental::erase_if(std::unordered_multimap) + +.SH Synopsis + Defined in header + template< class Key, class T, class Hash, class KeyEqual, + class Alloc, class Pred > (library fundamentals TS + void erase_if( std::unordered_multimap& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& cont) + { + os << '{'; + for (const auto& item : cont) + os << '{' << item.first << ", " << item.second << '}'; + return os << '}'; + } + + int main() + { + std::unordered_multimap data{{1, 'a'},{2, 'b'},{3, 'c'},{4, 'd'}, + {5, 'e'},{4, 'f'},{5, 'g'},{5, 'g'}}; + std::cout << "Original:\\n" << data << '\\n'; + std::experimental::erase_if(data, [](const auto& item) + { + return (item.first & 1) == 1; + }); + std::cout << "Erase items with odd keys:\\n" << data << '\\n'; + } + +.SH Possible output: + + Original: + {{5, g}{5, g}{5, e}{4, f}{4, d}{3, c}{2, b}{1, a}} + Erase items with odd keys: + {{4, f}{4, d}{2, b}} + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::unordered_multiset).3 b/man/std::experimental::erase_if(std::unordered_multiset).3 new file mode 100644 index 000000000..335029b49 --- /dev/null +++ b/man/std::experimental::erase_if(std::unordered_multiset).3 @@ -0,0 +1,71 @@ +.TH std::experimental::erase_if(std::unordered_multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::unordered_multiset) \- std::experimental::erase_if(std::unordered_multiset) + +.SH Synopsis + Defined in header + template< class Key, class Hash, class KeyEqual, class + Alloc, class Pred > (library fundamentals TS + void erase_if( std::unordered_multiset& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::unordered_multiset data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Possible output: + + Original: + { 0 1 2 7 6 6 5 5 4 3 3 } + Erase all items divisible by 3: + { 1 2 7 5 5 4 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::unordered_set).3 b/man/std::experimental::erase_if(std::unordered_set).3 new file mode 100644 index 000000000..35e2d66bf --- /dev/null +++ b/man/std::experimental::erase_if(std::unordered_set).3 @@ -0,0 +1,71 @@ +.TH std::experimental::erase_if(std::unordered_set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::unordered_set) \- std::experimental::erase_if(std::unordered_set) + +.SH Synopsis + Defined in header + template< class Key, class Hash, class KeyEqual, class + Alloc, class Pred > (library fundamentals TS + void erase_if( std::unordered_set& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to + + for (auto i = c.begin(), last = c.end(); i != last;) + { + if (pred(*i)) + i = c.erase(i); + else + ++i; + } + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::unordered_set data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Possible output: + + Original: + { 0 1 2 7 6 5 4 3 } + Erase all items divisible by 3: + { 1 2 7 5 4 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erase_if(std::vector).3 b/man/std::experimental::erase_if(std::vector).3 new file mode 100644 index 000000000..785c6bebe --- /dev/null +++ b/man/std::experimental::erase_if(std::vector).3 @@ -0,0 +1,64 @@ +.TH std::experimental::erase_if(std::vector) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erase_if(std::vector) \- std::experimental::erase_if(std::vector) + +.SH Synopsis + Defined in header + template< class T, class Alloc, class Pred > (library fundamentals TS v2) + void erase_if( std::vector& c, Pred pred ); + + Erases all elements that satisfy the predicate pred from the container. Equivalent + to c.erase(std::remove_if(c.begin(), c.end(), pred), c.end());. + +.SH Parameters + + c - container from which to erase + pred - predicate that determines which elements should be erased + +.SH Complexity + + Linear. + +.SH Example + + +// Run this code + + #include + #include + + template + inline Os& operator<<(Os& os, Container const& container) + { + os << "{ "; + for (const auto& item : container) + os << item << ' '; + return os << '}'; + } + + int main() + { + std::vector data{3, 3, 4, 5, 5, 6, 6, 7, 2, 1, 0}; + std::cout << "Original:\\n" << data << '\\n'; + auto divisible_by_3 = [](auto const& x) { return (x % 3) == 0; }; + std::experimental::erase_if(data, divisible_by_3); + std::cout << "Erase all items divisible by 3:\\n" << data << '\\n'; + } + +.SH Output: + + Original: + { 3 3 4 5 5 6 6 7 2 1 0 } + Erase all items divisible by 3: + { 4 5 5 7 2 1 } + +.SH See also + + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + erase (std::vector) erases all elements equal to a specific value from a + (library fundamentals 2 TS) std::vector + \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::erased_type.3 b/man/std::experimental::erased_type.3 new file mode 100644 index 000000000..172641182 --- /dev/null +++ b/man/std::experimental::erased_type.3 @@ -0,0 +1,18 @@ +.TH std::experimental::erased_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::erased_type \- std::experimental::erased_type + +.SH Synopsis + Defined in header + struct erased_type { }; (library fundamentals TS) + (removed in library fundamentals TS v3) + + The class erased_type is an empty struct that serves as a placeholder for a type in + situations where the actual type is determined at runtime. For example, in classes + that use type-erased allocators, the nested typedef allocator_type is an alias for + erased_type. + +.SH Notes + + erased_type is removed in LFTS v3 because std::pmr::polymorphic_allocator<> is + preferable for type erasure. diff --git a/man/std::experimental::filesystem::absolute,std::experimental::filesystem::system_complete.3 b/man/std::experimental::filesystem::absolute,std::experimental::filesystem::system_complete.3 new file mode 100644 index 000000000..91180d6d2 --- /dev/null +++ b/man/std::experimental::filesystem::absolute,std::experimental::filesystem::system_complete.3 @@ -0,0 +1,97 @@ +.TH std::experimental::filesystem::absolute,std::experimental::filesystem::system_complete 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::absolute,std::experimental::filesystem::system_complete \- std::experimental::filesystem::absolute,std::experimental::filesystem::system_complete + +.SH Synopsis + Defined in header + path absolute( const path& p, const path& base = current_path() \fB(1)\fP (filesystem TS) + ); + path system_complete( const path& p ); \fB(2)\fP (filesystem TS) + path system_complete( const path& p, error_code& ec ); + + 1) Returns absolute path of p relative to base according to the following rules: + + * If p has both root name and root directory (e.g. "C:\\users", then the path is + returned, unmodified. + * If p has a root name not followed by a root directory (e.g. "C:text.txt"), then + base is inserted between p's root name and the remainder of p. Formally, + p.root_name() / fs::absolute(base).root_directory() / + fs::absolute(base).relative_path() / p.relative_path() is returned, + * If p has no root name, but has a root directory (e.g. "/var/tmp/file.txt" on a + POSIX system or "\\users\\ABC\\Document.doc" on Windows, then the root name of + base, if it has one, is prepended to p (on a POSIX system, p is not modified, on + a Windows system, "\\users\\ABC\\Document.doc" becomes "C:\\users\\ABC\\Document.doc". + Formally, fs::absolute(base).root_name() / p is returned. + * If p has no root name and no root directory (e.g. "../file.txt", then the entire + base is prepended to p. Formally, absolute(base) / p is returned. + 2) Obtains the absolute path that identifies the file that the OS file opening API + would access given the pathname p. On POSIX systems, this is equivalent to \fB(1)\fP with + the default base (fs::current_path()). On Windows systems, each logical drive has + its own current working directory, and so if p is not already absolute and has a + root name component (e.g. "E:filename.txt", that drive's current working directory + is used, which may have been set by an earlier executed program. + +.SH Parameters + + p - path to convert to absolute form + base - path (not necessarily absolute) to serve as the starting location + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + Returns an absolute (although not necessarily canonical) path formed by combining p + and base as described above. + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument, base as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept + + +.SH Notes + + On systems that support root names (e.g. Windows), the result of calling absolute on + a relative path that has a root name (e.g. "D:file.txt" when the root name of base + is different will usually result in a non-existent path. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = "C:cl.exe"; + std::cout << "Current path is " << fs::current_path() << '\\n' + << "Absolute path for " << p << " is " << fs::absolute(p) << '\\n' + << "System complete path for " << p << " is " + << fs::system_complete(p) << '\\n'; + } + +.SH Possible output: + + Current path is "D:/local/ConsoleApplication1" + Absolute path for "C:cl.exe" is "C:/local/ConsoleApplication1/cl.exe" + System complete path for "C:cl.exe" is "C:\\Program Files (x86)\\Microsoft Visual Studio 12.0\\VC\\bin\\cl.exe" + +.SH See also + + canonical composes a canonical path + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::absolute.3 b/man/std::experimental::filesystem::absolute.3 deleted file mode 100644 index 9439b92db..000000000 --- a/man/std::experimental::filesystem::absolute.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH std::experimental::filesystem::absolute 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - path absolute( const path& p, const path& base = current_path() ); (filesystem TS) - - Returns absolute path of p relative to base according to the following table: - - p.has_root_directory() !p.has_root_directory() - return p.root_name() / - absolute(base).root_directory() - p.has_root_name() return p - / absolute(base).relative_path() / - p.relative_path() - !p.has_root_name() absolute(base).root_name() / return absolute(base) / p - p - -.SH Parameters - - This section is incomplete - -.SH Return value - - This section is incomplete - -.SH Exceptions - - This section is incomplete - - * std::bad_alloc if memory allocation fails - -.SH Notes - - The returned path is always absolute. - -.SH See also - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::begin(directory_iterator),.3 b/man/std::experimental::filesystem::begin(directory_iterator),.3 new file mode 100644 index 000000000..b6332dc22 --- /dev/null +++ b/man/std::experimental::filesystem::begin(directory_iterator),.3 @@ -0,0 +1,69 @@ +.TH std::experimental::filesystem::begin(directory_iterator), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::begin(directory_iterator), \- std::experimental::filesystem::begin(directory_iterator), + +.SH Synopsis + + directory_iterator begin( directory_iterator iter ); \fB(1)\fP (filesystem TS) + directory_iterator end( const directory_iterator& ); \fB(2)\fP (filesystem TS) + + 1) Returns iter unchanged. + 2) Returns a default-constructed directory_iterator, which serves as the end + iterator. The argument is ignored. + + These non-member functions enable the use of directory_iterators with range-based + for loops. + +.SH Parameters + + iter - a directory_iterator + +.SH Return value + + 1) iter unchanged. + 2) End iterator (default-constructed directory_iterator). + +.SH Exceptions + + noexcept specification: + noexcept + + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b"); + std::ofstream("sandbox/file1.txt"); + std::ofstream("sandbox/file2.txt"); + for (auto& p : fs::directory_iterator("sandbox")) + std::cout << p << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/a" + "sandbox/file1.txt" + "sandbox/file2.txt" + +.SH See also + + filesystem::begin(filesystem::recursive_directory_iterator) range-based for loop + filesystem::end(filesystem::recursive_directory_iterator) support + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::begin(recursive_directory_iterator),.3 b/man/std::experimental::filesystem::begin(recursive_directory_iterator),.3 new file mode 100644 index 000000000..ac5a7bb00 --- /dev/null +++ b/man/std::experimental::filesystem::begin(recursive_directory_iterator),.3 @@ -0,0 +1,71 @@ +.TH std::experimental::filesystem::begin(recursive_directory_iterator), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::begin(recursive_directory_iterator), \- std::experimental::filesystem::begin(recursive_directory_iterator), + +.SH Synopsis + + recursive_directory_iterator begin( recursive_directory_iterator \fB(1)\fP (filesystem TS) + iter ); + recursive_directory_iterator end( const \fB(2)\fP (filesystem TS) + recursive_directory_iterator& ); + + 1) Returns iter unchanged. + 2) Returns a default-constructed recursive_directory_iterator, which serves as the + end iterator. The argument is ignored. + + These non-member functions enable the use of recursive_directory_iterators with + range-based for loops. + +.SH Parameters + + iter - a recursive_directory_iterator + +.SH Return value + + 1) iter unchanged. + 2) End iterator (default-constructed recursive_directory_iterator). + +.SH Exceptions + + noexcept specification: + noexcept + + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b"); + std::ofstream("sandbox/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + for (auto& p : fs::recursive_directory_iterator("sandbox")) + std::cout << p << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/a" + "sandbox/a/b" + "sandbox/file1.txt" + "sandbox/syma" + +.SH See also + + filesystem::begin(filesystem::directory_iterator) range-based for loop support + filesystem::end(filesystem::directory_iterator) \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::canonical.3 b/man/std::experimental::filesystem::canonical.3 index fedb79fed..0a9ef8a90 100644 --- a/man/std::experimental::filesystem::canonical.3 +++ b/man/std::experimental::filesystem::canonical.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::canonical 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::canonical 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::canonical \- std::experimental::filesystem::canonical + .SH Synopsis Defined in header path canonical( const path& p, const path& base = current_path() \fB(1)\fP (filesystem TS) @@ -7,36 +10,72 @@ path canonical( const path& p, const path& base, error_code& ec \fB(3)\fP (filesystem TS) ); - Converts path p to a canonical absolute path, i.e. one that has no dot, dot-dot - elements or symbolic links. p is optionally relative to base. - - p must resolve to an existing file, otherwise error occurs. + Converts path p to a canonical absolute path, i.e. an absolute path that has no dot, + dot-dot elements or symbolic links. - The return path resolves to the same path as absolute(p, base (or absolute(p) for - \fB(2)\fP}}. + If p is not an absolute path, the function behaves as if it is first made absolute + by absolute(p, base) or absolute(p) for \fB(2)\fP. - This section is incomplete - Reason: errors + The path p must exist. .SH Parameters - This section is incomplete - - ec - error code to store error status to + p - a path which may be absolute or relative to base, and which must be an + existing path + base - base path to be used in case p is relative + ec - error code to store error status to .SH Return value - The canonical absolute path of p, which is optionally relative to base. + An absolute path that resolves to the same file as absolute(p, base) (or absolute(p) + for \fB(2)\fP). .SH Exceptions - This section is incomplete + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument, base as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept + + + This function is modeled after the POSIX realpath. + +.SH Example -.SH See also - This section is incomplete +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = fs::path("..") / ".." / "AppData"; + std::cout << "Current path is " << fs::current_path() << '\\n' + << "Canonical path for " << p << " is " << fs::canonical(p) << '\\n'; + } + +.SH Possible output: + + Current path is "C:\\Users\\abcdef\\AppData\\Local\\Temp" + Canonical path for "..\\..\\AppData" is "C:\\Users\\abcdef\\AppData" + +.SH See also - Categories: + path represents a path + \fI(class)\fP + absolute composes an absolute path + system_complete converts a path to an absolute path replicating OS-specific behavior + \fI(function)\fP - * Todo with reason - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::copy.3 b/man/std::experimental::filesystem::copy.3 index 1588e2fc6..75440736c 100644 --- a/man/std::experimental::filesystem::copy.3 +++ b/man/std::experimental::filesystem::copy.3 @@ -1,23 +1,75 @@ -.TH std::experimental::filesystem::copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::copy \- std::experimental::filesystem::copy + .SH Synopsis Defined in header void copy( const path& from, const path& to ); \fB(1)\fP (filesystem TS) - void copy( const path& from, const path& to, error_code& ec ); \fB(2)\fP (filesystem TS) - void copy( const path& from, const path& to, copy_options \fB(3)\fP (filesystem TS) - options ); + void copy( const path& from, const path& to, error_code& ec ); + void copy( const path& from, const path& to, copy_options + options ); \fB(2)\fP (filesystem TS) void copy( const path& from, const path& to, copy_options - options, \fB(4)\fP (filesystem TS) - error_code& ec ); + options, error_code& ec ); - Copies file or directory. + Copies files and directories, with a variety of options: - This section is incomplete + 1) The default, equivalent to \fB(2)\fP with copy_options::none used as options. + 2) Copies the file or directory from to file or directory to, using the copy options + indicated by options. The behavior is undefined if there is more than one option in + any of the copy_options option group present in options (even in the copy_file + group, which is not relevant to copy). -.SH Parameters + The behavior is as follows: - This section is incomplete + * First, before doing anything else, obtains type and permissions of from by no + more than single call to status (or, if copy_options::skip_symlinks or + copy_options::create_symlinks are present in options, by a call to + symlink_status). + * If necessary, obtains the status of to the same way, by no more than a single + status or symlink_status call. + * If from does not exist, reports an error. + * If from and to are the same file as determined by equivalent(), reports an + error. + * If either from or to is not a regular file, a directory, or a symlink, as + determined by is_other, reports an error. + * If from is a directory, but to is a regular file, reports an error. + * If from is a symbolic link, then - ec - error code to store error status to + * If copy_options::skip_symlink is present in options, does nothing. + * Otherwise, if to does not exist and copy_options::copy_symlinks is present in + options, then behaves as if copy_symlink(from, to). + * Otherwise, reports an error. + * Otherwise, if from is a regular file, then + + * If copy_options::directories_only is present in options, does nothing. + * Otherwise, if copy_options::create_symlinks is present in options, creates a + symlink to to. Note: from must be an absolute path unless to is in the current + directory. + * Otherwise, if copy_options::create_hard_links is present in options, creates a + hard link to to. + * Otherwise, if to is a directory, then behaves as if copy_file(from, + to/from.filename(), options) (creates a copy of from as a file in the directory + to). + * Otherwise, behaves as if copy_file(from, to, options) (copies the file). + * Otherwise, if from is a directory and either options has copy_options::recursive + or is copy_options::none. + + * If to does not exist, first executes create_directory(to, from) (creates the new + directory with a copy of the old directory's attributes). + * Then, whether to already existed or was just created, iterates over the files + contained in from as if by for (const directory_entry& x : + directory_iterator(from)) and for each directory entry, recursively calls + copy(x.path(), to/x.path().filename(), options | unspecified), where unspecified + is a special bit that has no other effect when set in options (the sole purpose + of setting this bit is to prevent recursive copying subdirectories if options is + copy_options::none). + * Otherwise does nothing. + +.SH Parameters + + from - path to the source file, directory, or symlink + to - path to the target file, directory, or symlink + ec - out-parameter for error reporting in the non-throwing overload .SH Return value @@ -25,17 +77,80 @@ .SH Exceptions - This section is incomplete - - 2,4) - noexcept specification: + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with from as the first argument, to as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: noexcept - -.SH See also - This section is incomplete +.SH Notes + + The default behavior when copying directories is the non-recursive copy: the files + are copied, but not the subdirectories: + + // Given + // /dir1 contains /dir1/file1, /dir1/file2, /dir1/dir2 + // and /dir1/dir2 contains /dir1/dir2/file3 + // After + std::experimental::filesystem::copy("/dir1", "/dir3"); + // /dir3 is created (with the attributes of /dir1) + // /dir1/file1 is copied to /dir3/file1 + // /dir1/file2 is copied to /dir3/file2 + + While with copy_options::recursive, the subdirectories are also copied, with their + content, recursively. + + // ...but after + std::experimental::filesystem::copy("/dir1", "/dir3", copy_options::recursive); + // /dir3 is created (with the attributes of /dir1) + // /dir1/file1 is copied to /dir3/file1 + // /dir1/file2 is copied to /dir3/file2 + // /dir3/dir2 is created (with the attributes of /dir1/dir2) + // /dir1/dir2/file3 is copied to /dir3/dir2/file3 + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/dir/subdir"); + std::ofstream("sandbox/file1.txt").put('a'); + fs::copy("sandbox/file1.txt", "sandbox/file2.txt"); // copy file + fs::copy("sandbox/dir", "sandbox/dir2"); // copy directory (non-recursive) + // sandbox holds 2 files and 2 directories, one of which has a subdirectory + // sandbox/file1.txt + // sandbox/file2.txt + // sandbox/dir2 + // sandbox/dir + // sandbox/dir/subdir + fs::copy("sandbox", "sandbox/copy", fs::copy_options::recursive); + // sandbox/copy holds copies of the above files and subdirectories + fs::remove_all("sandbox"); + } + +.SH See also -.SH Category: + copy_options specifies semantics of copy operations + \fI(enum)\fP + copy_symlink copies a symbolic link + \fI(function)\fP + copy_file copies file contents + \fI(function)\fP - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::copy_file.3 b/man/std::experimental::filesystem::copy_file.3 index 2d0cb07a8..dde7c94ec 100644 --- a/man/std::experimental::filesystem::copy_file.3 +++ b/man/std::experimental::filesystem::copy_file.3 @@ -1,47 +1,128 @@ -.TH std::experimental::filesystem::copy_file 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::copy_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::copy_file \- std::experimental::filesystem::copy_file + .SH Synopsis Defined in header - bool copy_file( const path& from, const path& to ); \fB(1)\fP (filesystem TS) - bool copy_file( const path& from, const path& to, \fB(2)\fP (filesystem TS) - error_code& ec ); - bool copy_file( const path& from, const path& to, copy_options \fB(3)\fP (filesystem TS) - options ); + bool copy_file( const path& from, const path& to ); + bool copy_file( const path& from, const path& to, error_code& ec \fB(1)\fP (filesystem TS) + ); + bool copy_file( const path& from, const path& to, copy_options + options ); \fB(2)\fP (filesystem TS) bool copy_file( const path& from, const path& to, copy_options - options, \fB(4)\fP (filesystem TS) - error_code& ec ); + options, error_code& ec ); + + 1) The default, equivalent to \fB(2)\fP with copy_options::none used as options. + 2) Copies a single file from from to to, using the copy options indicated by + options. The behavior is undefined if there is more than one option in any of the + copy_options option group present in options (even in the groups not relevant to + copy_file). + * If the destination file does not exist, + + * copies the contents and the attributes of the file to which from resolves to the + file to which to resolves (symlinks are followed). + * Otherwise, if the destination file already exists: + + * If to and from are the same as determined by equivalent(from, to), report an + error. + * Otherwise, if none of the copy_file control options are set in options, report + an error. + * Otherwise, if copy_options::skip_existing is set in options, do nothing. + * Otherwise, if copy_options::overwrite_existing is set in options, copy the + contents and the attributes of the file to which from resolves to the file to + which to resolves. + * Otherwise, if copy_options::update_existing is set in options, only copy the + file if from is newer than to, as defined by last_write_time(). + + The non-throwing overloads return false if an error occurs. - Copies file contents and their attributes. +.SH Parameters - 1) Equivalent to copy_file(from, to, copy_options::none). - 2) Equivalent to copy_file(from, to, copy_options::none, ec). + from - path to the source file + to - path to the target file + ec - out-parameter for error reporting in the non-throwing overload - This section is incomplete +.SH Return value - The functions involve at most one direct or indirect call to status(to). + true if the file was copied, false otherwise. -.SH Parameters +.SH Exceptions - This section is incomplete + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with from as the first argument, to as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept - ec - error code to store error status to -.SH Return value +.SH Notes - This section is incomplete + The functions involve at most one direct or indirect call to status(to) (used both + to determine if the file exists, and, for copy_options::update_existing option, its + last write time). -.SH Exceptions + Error is reported when copy_file is used to copy a directory: use copy for that. - This section is incomplete + copy_file follows symlinks: use copy_symlink or copy with + copy_options::copy_symlinks for that. - 2,4) - noexcept specification: - noexcept - +.SH Example -.SH See also - This section is incomplete +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directory("sandbox"); + std::ofstream("sandbox/file1.txt").put('a'); + + fs::copy_file("sandbox/file1.txt", "sandbox/file2.txt"); + + // now there are two files in sandbox: + std::cout << "file1.txt holds : " + << std::ifstream("sandbox/file1.txt").rdbuf() << '\\n'; + std::cout << "file2.txt holds : " + << std::ifstream("sandbox/file2.txt").rdbuf() << '\\n'; -.SH Category: + // fail to copy directory + fs::create_directory("sandbox/abc"); + try + { + fs::copy_file("sandbox/abc", "sandbox/def"); + } + catch (fs::filesystem_error& e) + { + std::cout << "Could not copy sandbox/abc: " << e.what() << '\\n'; + } + fs::remove_all("sandbox"); + } + +.SH Possible output: + + file1.txt holds : a + file2.txt holds : a + Could not copy sandbox/abc: copy_file: Is a directory: "sandbox/abc", "sandbox/def" + +.SH See also - * Todo without reason + copy_options specifies semantics of copy operations + \fI(enum)\fP + copy_symlink copies a symbolic link + \fI(function)\fP + copy copies files or directories + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::copy_options.3 b/man/std::experimental::filesystem::copy_options.3 index 7ae1bd9c1..a73d01fb6 100644 --- a/man/std::experimental::filesystem::copy_options.3 +++ b/man/std::experimental::filesystem::copy_options.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::copy_options 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::copy_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::copy_options \- std::experimental::filesystem::copy_options + .SH Synopsis Defined in header enum class copy_options { @@ -16,27 +19,76 @@ }; - This section is incomplete + This type represents available options that control the behavior of the copy() and + copy_file() function. + + copy_options satisfies the requirements of BitmaskType (which means the bitwise + operators operator&, operator|, operator^, operator~, operator&=, operator|=, and + operator^= are defined for this type). + +.SH Member constants + + At most one copy option in each of the following options groups may be present, + otherwise the behavior of the copy functions is undefined. + + Member constant Value Meaning + options controlling copy_file() when the file already exists + none 0 Report an error (default behavior). + skip_existing 1 Keep the existing file, without reporting an error. + overwrite_existing 2 Replace the existing file. + update_existing 4 Replace the existing file only if it is older than the file + being copied. + options controlling the effects of copy() on subdirectories + none 0 Skip subdirectories (default behavior). + recursive 8 Recursively copy subdirectories and their content. + options controlling the effects of copy() on symbolic links + none 0 Follow symlinks (default behavior). + copy_symlinks 16 Copy symlinks as symlinks, not as the files they point to. + skip_symlinks 32 Ignore symlinks. + options controlling the kind of copying copy() does + none 0 Copy file content (default behavior). + directories_only 64 Copy the directory structure, but do not copy any + non-directory files. + Instead of creating copies of files, create symlinks + create_symlinks 128 pointing to the originals. Note: the source path must be an + absolute path unless the destination path is in the current + directory. + create_hard_links 256 Instead of creating copies of files, create hardlinks that + resolve to the same files as the originals. -.SH Constants +.SH Example - {{dsc | copy_symlinks - Constant Meaning - skip_existing do not overwrite existing file or report an error - overwrite_existing overwrite existing file - update_existing overwrite existing file if it is older than the replacement - recursive recursively copy sub-directories and their contents - skip_symlinks ignore symbolic links - directories-only copy directory structure only, skip all files - create symlinks instead of copying the files. The source path - create_symlinks shall be an absolute path unless the destination path is in the - current directory. - create_hard_links create hard links instead of copying the files + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/dir/subdir"); + std::ofstream("sandbox/file1.txt").put('a'); + fs::copy("sandbox/file1.txt", "sandbox/file2.txt"); // copy file + fs::copy("sandbox/dir", "sandbox/dir2"); // copy directory (non-recursive) + // sandbox holds 2 files and 2 directories, one of which has a subdirectory + // sandbox/file1.txt + // sandbox/file2.txt + // sandbox/dir2 + // sandbox/dir + // sandbox/dir/subdir + fs::copy("sandbox", "sandbox/copy", fs::copy_options::recursive); + // sandbox/copy holds copies of the above files and subdirectories + fs::remove_all("sandbox"); + } .SH See also - This section is incomplete + copy copies files or directories + \fI(function)\fP + copy_file copies file contents + \fI(function)\fP .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::copy_symlink.3 b/man/std::experimental::filesystem::copy_symlink.3 index 8e6ff5eef..26f4f2496 100644 --- a/man/std::experimental::filesystem::copy_symlink.3 +++ b/man/std::experimental::filesystem::copy_symlink.3 @@ -1,8 +1,11 @@ -.TH std::experimental::filesystem::copy_symlink 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::copy_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::copy_symlink \- std::experimental::filesystem::copy_symlink + .SH Synopsis Defined in header - void copy_symlink( const path& from, const path& to); \fB(1)\fP (filesystem TS) - void copy_symlink( const path& from, const path& to, \fB(2)\fP (filesystem TS) + void copy_symlink( const path& from, const path& to ); \fB(1)\fP (filesystem TS) + void copy_symlink( const path& from, const path& to, \fB(2)\fP (filesystem TS) error_code& ec ); Copies a symlink to another location. @@ -13,14 +16,11 @@ or create_directory_symlink depending on whether from resolves to a file or directory. - This section is incomplete - Reason: errors - .SH Parameters from - path to a symbolic link to copy to - destination path of the new symlink - ec - error code to store the error status + ec - out-parameter for error reporting in the non-throwing overload .SH Return value @@ -28,18 +28,30 @@ .SH Exceptions - This section is incomplete - - 2) - noexcept specification: + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with from as the first argument, to as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: noexcept - -.SH See also - - This section is incomplete - Categories: +.SH See also - * Todo with reason - * Todo without reason + copy copies files or directories + \fI(function)\fP + copy_file copies file contents + \fI(function)\fP + create_symlink creates a symbolic link + create_directory_symlink \fI(function)\fP + read_symlink obtains the target of a symbolic link + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::create_directory,.3 b/man/std::experimental::filesystem::create_directory,.3 new file mode 100644 index 000000000..894a11283 --- /dev/null +++ b/man/std::experimental::filesystem::create_directory,.3 @@ -0,0 +1,113 @@ +.TH std::experimental::filesystem::create_directory, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::create_directory, \- std::experimental::filesystem::create_directory, + +.SH Synopsis + + Defined in header + bool create_directory( const path& p ); \fB(1)\fP (filesystem TS) + bool create_directory( const path& p, error_code& ec ); + bool create_directory( const path& p, const path& existing_p ); + bool create_directory( const path& p, const path& existing_p, \fB(2)\fP (filesystem TS) + error_code& ec ); + bool create_directories( const path& p ); \fB(3)\fP (filesystem TS) + bool create_directories( const path& p, error_code& ec ); + + 1) Creates the directory p as if by POSIX mkdir() with a second argument of + static_cast(fs::perms::all) (the parent directory must already exist). If p + already exists and is already a directory, the function does nothing (this condition + is not treated as an error). + 2) Same as \fB(1)\fP, except that the attributes of the new directory are copied from + existing_p (which must be a directory that exists). It is OS-dependent which + attributes are copied: on POSIX systems, the attributes are copied as if by + + stat(existing_p.c_str(), &attributes_stat) + mkdir(p.c_str(), attributes_stat.st_mode) + + On Windows OS, the attributes are copied as if by + + CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0) + + 3) Executes \fB(1)\fP for every element of p that does not already exist. + + The non-throwing overloads return false if any error occurs. + +.SH Parameters + + p - the path to the new directory to create + existing_p - the path to a directory to copy the attributes from + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + 1,2) true if directory creation is successful, false otherwise. + +.SH Exceptions + + 1,3) The overload that does not take an error_code& parameter throws + filesystem_error on underlying OS API errors, constructed with p as the first + argument and the OS error code as the error code argument. std::bad_alloc may be + thrown if memory allocation fails. The overload taking an error_code& parameter sets + it to the OS API error code if an OS API call fails, and executes ec.clear() if no + errors occur. This overload has + noexcept specification: + noexcept + + 2) The overload that does not take an error_code& parameter throws filesystem_error + on underlying OS API errors, constructed with p as the first argument, existing_p as + the second argument, and the OS error code as the error code argument. + std::bad_alloc may be thrown if memory allocation fails. The overload taking an + error_code& parameter sets it to the OS API error code if an OS API call fails, and + executes ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept + + +.SH Notes + + The attribute-preserving overload \fB(2)\fP is implicitly invoked by copy() when + recursively copying directories. Its equivalent in boost.filesystem is + copy_directory (with argument order reversed). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/1/2/a"); + fs::create_directory("sandbox/1/2/b"); + fs::permissions("sandbox/1/2/b", fs::perms::remove_perms | fs::perms::others_all); + fs::create_directory("sandbox/1/2/c", "sandbox/1/2/b"); + std::system("ls -l sandbox/1/2"); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + drwxr-xr-x 2 user group 4096 Apr 15 09:33 a + drwxr-x--- 2 user group 4096 Apr 15 09:33 b + drwxr-x--- 2 user group 4096 Apr 15 09:33 c + +.SH See also + + create_symlink creates a symbolic link + create_directory_symlink \fI(function)\fP + copy copies files or directories + \fI(function)\fP + perms identifies file system permissions + \fI(enum)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::create_directory,create_directories.3 b/man/std::experimental::filesystem::create_directory,create_directories.3 deleted file mode 100644 index bde454dae..000000000 --- a/man/std::experimental::filesystem::create_directory,create_directories.3 +++ /dev/null @@ -1,64 +0,0 @@ -.TH std::experimental::filesystem::create_directory,create_directories 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - bool create_directory( const path& p ); \fB(1)\fP (filesystem TS) - bool create_directory( const path& p, error_code& ec ); \fB(2)\fP (filesystem TS) - bool create_directory( const path& p, const path& existing_p ); \fB(3)\fP (filesystem TS) - bool create_directory( const path& p, const path& existing_p, \fB(4)\fP (filesystem TS) - error_code& ec ); - bool create_directories( const path& p ); \fB(5)\fP (filesystem TS) - bool create_directories( const path& p, error_code& ec ); \fB(6)\fP (filesystem TS) - - Creates directory that p resolves to. Directory creating failures caused by an - already existing directory at p are not treated as errors. - - 1-4) Parent directories are not created. If parent directory of p does not exist, - error occurs. (3-4) additionally copy operating system-dependent set of attributes - from existing_p to the newly created directory. - 5-6) If parent directory does not exist, any missing directories are created as if - by call to create_directory. - - true is returned on success, false on failure. - - The \fB(2)\fP, \fB(4)\fP and \fB(6)\fP overloads set ec to an appropriate error code if an error - occurs. Otherwise, ec is cleared with a call to ec.clear(). - -.SH Parameters - - p - the path to the new directory to create - existing_p - the path to a directory to copy the attributes from - ec - error code to store the error status to - -.SH Return value - - true if directory creation is successful, false otherwise. - -.SH Exceptions - - 1,3,5) filesystem_error if a directory can not be created or any other error occurs. - The exception object is constructed with p (and existing_p in case of (3-4)) as an - argument. The error code is set to appropriate operating system dependent value. - 2,4,6) - noexcept specification: - noexcept - - -.SH Notes - - On POSIX systems, new directories are created as if by calling mkdir(p.c_str(), - S_IRWXU|S_IRWXG|S_IRWXO). - - On POSIX systems, the attributes copied by (3-4) are those copied by - mkdir(p.c_str(), attr.st_mode, where attr are retrieved as if by - stat(existing_p.c_str(), &attr). - - On Windows-based operating systems the attributes copied by (3-4) are those copied - by native CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0). - -.SH See also - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::create_hard_link.3 b/man/std::experimental::filesystem::create_hard_link.3 index 89cd2c6e5..2a45a97ef 100644 --- a/man/std::experimental::filesystem::create_hard_link.3 +++ b/man/std::experimental::filesystem::create_hard_link.3 @@ -1,27 +1,25 @@ -.TH std::experimental::filesystem::create_hard_link 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::create_hard_link 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::create_hard_link \- std::experimental::filesystem::create_hard_link + .SH Synopsis Defined in header - void create_hard_link( const path& to, const path& new_link ); \fB(1)\fP (filesystem TS) - void create_hard_link( const path& to, const path& new_link, \fB(2)\fP (filesystem TS) - error_code& ec ); - - Creates a hard link at new_link which links to a file or directory to. - equivalent(to, new_link) holds after successful creation of a hard link. - - The contents of to are not changed. + void create_hard_link( const path& target, const path& link ); + void create_hard_link( const path& target, const path& link, (filesystem TS) + error_code& ec ); - The second overload sets ec to an appropriate error code if an error occurs. - Otherwise, ec is cleared with a call to ec.clear(). + Creates a hard link link with its target set to target as if by POSIX link(): the + pathname target must exist. - Symbolic link support depends on the operating system the program runs on and on the - target file system. Some operating systems do not support hard links or support hard - links only for regular files. Some file systems do not support hard links at all. + Once created, link and target are two logical names that refer to the same file + (they are equivalent). Even if the original name target is deleted, the file + continues to exist and is accessible as link. .SH Parameters - to - path of the file to link to - new_link - path of the new symbolic link - ec - error code to store the error state to + target - path of the file or directory to link to + link - path of the new hard link + ec - out-parameter for error reporting in the non-throwing overload .SH Return value @@ -29,18 +27,71 @@ .SH Exceptions - 1) filesystem_error if an error occurs. The exception object is constructed with to - and new_link as arguments. The error code is set to an appropriate error code for - the error that caused the failure. - 2) - noexcept specification: + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with target as the first argument, link as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: noexcept - -.SH See also - This section is incomplete +.SH Notes + + Some operating systems do not support hard links at all or support them only for + regular files. + + Some file systems do not support hard links regardless of the operating system: the + FAT file system used on memory cards and flash drives, for example. + + Some file systems limit the number of links per file. + + Hardlinking to directories is typically restricted to the superuser. + + Hard links typically cannot cross filesystem boundaries. + + The special pathname dot (".") is a hard link to its parent directory. The special + pathname dot-dot ".." is a hard link to the directory that is the parent of its + parent. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/subdir"); + std::ofstream("sandbox/a").put('a'); // create regular file + fs::create_hard_link("sandbox/a", "sandbox/b"); + fs::remove("sandbox/a"); + // read from the original file via surviving hard link + char c = std::ifstream("sandbox/b").get(); + std::cout << c << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Output: + + a + +.SH See also -.SH Category: + create_symlink creates a symbolic link + create_directory_symlink \fI(function)\fP + returns the number of hard links referring to the specific + hard_link_count file + \fI(function)\fP - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::create_symlink,.3 b/man/std::experimental::filesystem::create_symlink,.3 new file mode 100644 index 000000000..14724aa9e --- /dev/null +++ b/man/std::experimental::filesystem::create_symlink,.3 @@ -0,0 +1,101 @@ +.TH std::experimental::filesystem::create_symlink, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::create_symlink, \- std::experimental::filesystem::create_symlink, + +.SH Synopsis + + Defined in header + void create_symlink( const path& target, const path& link ); + void create_symlink( const path& target, const path& link, \fB(1)\fP (filesystem TS) + error_code& ec ); + void create_directory_symlink( const path& target, const path& + link ); \fB(2)\fP (filesystem TS) + void create_directory_symlink( const path& target, const path& + link, error_code& ec ); + + Creates a symbolic link link with its target set to target as if by POSIX symlink(): + the pathname target may be invalid or non-existing. + + Some operating systems require symlink creation to identify that the link is to a + directory. Portable code should use \fB(2)\fP to create directory symlinks rather than + \fB(1)\fP, even though there is no distinction on POSIX systems. + +.SH Parameters + + target - path to point the symlink to, does not have to exist + link - path of the new symbolic link + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with target as the first argument, link as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept + + +.SH Notes + + Some operating systems do not support symbolic links at all or support them only for + regular files. + + Some file systems do not support symbolic links regardless of the operating system, + for example the FAT system used on some memory cards and flash drives. + + Like a hard link, a symbolic link allows a file to have multiple logical names. The + presence of a hard link guarantees the existence of a file, even after the original + name has been removed. A symbolic link provides no such assurance; in fact, the file + named by the target argument need not exist when the link is created. A symbolic + link can cross file system boundaries. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/subdir"); + fs::create_symlink("target", "sandbox/sym1"); + fs::create_directory_symlink("subdir", "sandbox/sym2"); + + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + if (is_symlink(it->symlink_status())) + std::cout << *it << "->" << read_symlink(*it) << '\\n'; + + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/sym1"->"target" + "sandbox/sym2"->"subdir" + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + read_symlink obtains the target of a symbolic link + \fI(function)\fP + create_hard_link creates a hard link + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::create_symlink,create_directory_symlink.3 b/man/std::experimental::filesystem::create_symlink,create_directory_symlink.3 deleted file mode 100644 index f3fe6f568..000000000 --- a/man/std::experimental::filesystem::create_symlink,create_directory_symlink.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH std::experimental::filesystem::create_symlink,create_directory_symlink 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - void create_symlink( const path& to, const path& new_symlink ); \fB(1)\fP (filesystem TS) - void create_symlink( const path& to, const path& new_symlink, \fB(2)\fP (filesystem TS) - error_code& ec ); - void create_directory_symlink( const path& to, const path& \fB(3)\fP (filesystem TS) - new_symlink ); - void create_directory_symlink( const path& to, const path& - new_symlink, \fB(4)\fP (filesystem TS) - error_code& ec ); - - Creates a symbolic link from new_symlink to to. The (1-2) overloads should be used - to create symbolic links to files whereas the (3-4) overloads should be used to - create symbolic links to directories. - - The \fB(2)\fP and \fB(4)\fP versions set ec to an appropriate error code if an error occurs. - Otherwise, ec is cleared with a call to ec.clear(). - - Symbolic link support depends on the operating system the program runs on and on the - target file system. Some operating systems do not support symbolic links or support - symbolic links only for regular files. Some file systems do not support symbolic - links at all. - -.SH Parameters - - to - path of the file to link to - new_symlink - path of the new symbolic link - ec - error code to store the error state to - -.SH Return value - - \fI(none)\fP - -.SH Exceptions - - 1, 3) filesystem_error if an error occurs. The exception object is constructed with - to and new_symlink as arguments. The error code is set to an appropriate error code - for the error that caused the failure. - 2, 4) - noexcept specification: - noexcept - - -.SH See also - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::current_path.3 b/man/std::experimental::filesystem::current_path.3 index 1c8ad6b6f..c40bb1336 100644 --- a/man/std::experimental::filesystem::current_path.3 +++ b/man/std::experimental::filesystem::current_path.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::current_path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::current_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::current_path \- std::experimental::filesystem::current_path + .SH Synopsis Defined in header path current_path(); \fB(1)\fP (filesystem TS) @@ -8,38 +11,39 @@ Returns or changes the current path. - 1-2) Returns the absolute path of the current working directory. \fB(2)\fP returns path() - if error occurs. - 3-4) Changes the current working directory to p. + 1,2) Returns the absolute path of the current working directory, obtained as if by + POSIX getcwd. \fB(2)\fP returns path() if error occurs. + 3,4) Changes the current working directory to p, as if by POSIX chdir. .SH Parameters p - path to change the current working directory to - ec - error code to set in case of errors + ec - out-parameter for error reporting in the non-throwing overloads .SH Return value - 1-2) Returns the current working directory. - 3-4) \fI(none)\fP + 1,2) Returns the current working directory. + 3,4) \fI(none)\fP .SH Exceptions - 1) - - This section is incomplete - - 2) - noexcept specification: + 1,2) The overload that does not take an error_code& parameter throws + filesystem_error on underlying OS API errors, constructed with the OS error code as + the error code argument. std::bad_alloc may be thrown if memory allocation fails. + The overload taking an error_code& parameter sets it to the OS API error code if an + OS API call fails, and executes ec.clear() if no errors occur. This overload has + noexcept specification: noexcept - - 3) - This section is incomplete - - 4) - noexcept specification: + 3,4) The overload that does not take an error_code& parameter throws + filesystem_error on underlying OS API errors, constructed with p as the first + argument and the OS error code as the error code argument. std::bad_alloc may be + thrown if memory allocation fails. The overload taking an error_code& parameter sets + it to the OS API error code if an OS API call fails, and executes ec.clear() if no + errors occur. This overload has + noexcept specification: noexcept - + .SH Notes @@ -56,6 +60,10 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_entry.3 b/man/std::experimental::filesystem::directory_entry.3 index 0a107d84c..f7e6d76c3 100644 --- a/man/std::experimental::filesystem::directory_entry.3 +++ b/man/std::experimental::filesystem::directory_entry.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::directory_entry 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_entry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry \- std::experimental::filesystem::directory_entry + .SH Synopsis Defined in header class directory_entry; (filesystem TS) @@ -9,27 +12,30 @@ .SH Member functions - constructor constructs a directory entry - \fI(public member function)\fP - destructor default destructor - \fI(public member function)\fP + constructor constructs a directory entry + \fI(public member function)\fP + destructor default destructor + \fI(public member function)\fP .SH Modifiers - operator= assigns contents - \fI(public member function)\fP - assign assigns contents - \fI(public member function)\fP - replace_filename sets the filename - \fI(public member function)\fP + operator= assigns contents + \fI(public member function)\fP + assign assigns contents + \fI(public member function)\fP + replace_filename sets the filename + \fI(public member function)\fP .SH Observers - path returns the path the entry refers to - \fI(public member function)\fP - status returns the status of the file entry refers to - \fI(public member function)\fP - symbolic_status returns the status of the target of the symbolic link - \fI(public member function)\fP + path returns the path the entry refers to + operator const path& \fI(public member function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory + symlink_status entry + \fI(public member function)\fP operator== - opretaro|= - opetator< compares two directory entries - operator<= \fI(public member function)\fP + operator!= + operator< compares two directory entries + operator<= \fI(public member function)\fP operator> operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::directory_entry::assign.3 b/man/std::experimental::filesystem::directory_entry::assign.3 index 4c915382b..7eea85509 100644 --- a/man/std::experimental::filesystem::directory_entry::assign.3 +++ b/man/std::experimental::filesystem::directory_entry::assign.3 @@ -1,10 +1,11 @@ -.TH std::experimental::filesystem::directory_entry::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_entry::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::assign \- std::experimental::filesystem::directory_entry::assign + .SH Synopsis - void assign( const path& p, file_status status = file_status(), (filesystem TS) - file_status symlink_status = file_status() ); + void assign( const path& p ); (filesystem TS) - Assigns new content to the directory entry object. Sets the path to p, file status - to status and symlink status to symlink_status. + Assigns new content to the directory entry object. Sets the path to p. .SH Parameters @@ -21,8 +22,8 @@ .SH See also operator= assigns contents - \fI(public member function)\fP - -.SH Category: + \fI(public member function)\fP +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::directory_entry::directory_entry.3 b/man/std::experimental::filesystem::directory_entry::directory_entry.3 index b40d07e08..5bf829890 100644 --- a/man/std::experimental::filesystem::directory_entry::directory_entry.3 +++ b/man/std::experimental::filesystem::directory_entry::directory_entry.3 @@ -1,20 +1,19 @@ -.TH std::experimental::filesystem::directory_entry::directory_entry 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_entry::directory_entry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::directory_entry \- std::experimental::filesystem::directory_entry::directory_entry + .SH Synopsis - directory_entry() = default; \fB(1)\fP (filesystem TS) - directory_entry( const directory_entry& ) = default; \fB(2)\fP (filesystem TS) - directory_entry( directory_entry&& ) = default; \fB(3)\fP (filesystem TS) - explicit directory_entry( const path& p, file_status status = - file_status(), \fB(4)\fP (filesystem TS) - file_status symlink_status = - file_status() ); + directory_entry() = default; \fB(1)\fP (filesystem TS) + directory_entry( const directory_entry& ) = default; \fB(2)\fP (filesystem TS) + directory_entry( directory_entry&& ) = default; \fB(3)\fP (filesystem TS) + explicit directory_entry( const path& p ); \fB(4)\fP (filesystem TS) Constructs a new directory_entry object. 1) Default constructor. 2) Default copy constructor. 3) Default move constructor. - 4) Initializes the directory entry with path p and file and symlink statuses - initialized to status and file_status respectively. + 4) Initializes the directory entry with path p. .SH Parameters @@ -24,6 +23,6 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::directory_entry::operator=.3 b/man/std::experimental::filesystem::directory_entry::operator=.3 index a50f2cad3..a1ab5ea21 100644 --- a/man/std::experimental::filesystem::directory_entry::operator=.3 +++ b/man/std::experimental::filesystem::directory_entry::operator=.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::directory_entry::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_entry::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::operator= \- std::experimental::filesystem::directory_entry::operator= + .SH Synopsis directory_entry& operator=( const directory_entry& ) = default; \fB(1)\fP (filesystem TS) directory_entry& operator=( directory_entry&&) = default; \fB(2)\fP (filesystem TS) @@ -18,15 +21,19 @@ This section is incomplete 2) - noexcept specification: + noexcept specification: noexcept - + .SH See also assign assigns contents - \fI(public member function)\fP - -.SH Category: + \fI(public member function)\fP +.SH Categories: + * Noindexed pages * Todo without reason + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_entry::operator==,!=,,>=.3 b/man/std::experimental::filesystem::directory_entry::operator==,!=,,>=.3 new file mode 100644 index 000000000..aa54d6697 --- /dev/null +++ b/man/std::experimental::filesystem::directory_entry::operator==,!=,,>=.3 @@ -0,0 +1,44 @@ +.TH std::experimental::filesystem::directory_entry::operator==,!=,,>= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::operator==,!=,,>= \- std::experimental::filesystem::directory_entry::operator==,!=,,>= + +.SH Synopsis + bool operator==( const directory_entry& rhs ) const; \fB(1)\fP (filesystem TS) + bool operator!=( const directory_entry& rhs ) const; \fB(2)\fP (filesystem TS) + bool operator<( const directory_entry& rhs ) const; \fB(3)\fP (filesystem TS) + bool operator<=( const directory_entry& rhs ) const; \fB(4)\fP (filesystem TS) + bool operator>( const directory_entry& rhs ) const; \fB(5)\fP (filesystem TS) + bool operator>=( const directory_entry& rhs ) const; \fB(6)\fP (filesystem TS) + + Compares the path with the directory entry rhs. + +.SH Parameters + + rhs - directory_entry to compare + +.SH Return value + + 1) true if path() == rhs.path(), false otherwise. + 2) true if path() != rhs.path(), false otherwise. + 3) true if path() < rhs.path(), false otherwise. + 4) true if path() <= rhs.path(), false otherwise. + 5) true if path() > rhs.path(), false otherwise. + 6) true if path() >= rhs.path(), false otherwise. + +.SH Exceptions + + noexcept specification: + noexcept + + +.SH See also + + path returns the path the entry refers to + operator const path& \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_entry::operator==,!=,<,<=,>,>=.3 b/man/std::experimental::filesystem::directory_entry::operator==,!=,<,<=,>,>=.3 deleted file mode 100644 index 15855bc70..000000000 --- a/man/std::experimental::filesystem::directory_entry::operator==,!=,<,<=,>,>=.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::experimental::filesystem::directory_entry::operator==,!=,<,<=,>,>= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Compares the path with the directory entry rhs. - -.SH Parameters - - This section is incomplete - -.SH Return value - - This section is incomplete - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - This section is incomplete - - bool operator==( const directory_entry& rhs ) const; (filesystem TS) - bool operator!=( const directory_entry& rhs ) const; (filesystem TS) - bool operator<( const directory_entry& rhs ) const; (filesystem TS) - bool operator<=( const directory_entry& rhs ) const; (filesystem TS) - bool operator>( const directory_entry& rhs ) const; (filesystem TS) - bool operator>=( const directory_entry& rhs ) const; (filesystem TS) - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::directory_entry::path.3 b/man/std::experimental::filesystem::directory_entry::path.3 index 44e5112a4..be67a96e7 100644 --- a/man/std::experimental::filesystem::directory_entry::path.3 +++ b/man/std::experimental::filesystem::directory_entry::path.3 @@ -1,6 +1,10 @@ -.TH std::experimental::filesystem::directory_entry::path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_entry::path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::path \- std::experimental::filesystem::directory_entry::path + .SH Synopsis - const path& path() const; (filesystem TS) + const path& path() const; (filesystem TS) + operator const path& () const; (filesystem TS) Returns the full path the directory entry refers to. @@ -14,14 +18,18 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + .SH See also This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_entry::replace_filename.3 b/man/std::experimental::filesystem::directory_entry::replace_filename.3 index 14d5207ea..f7336f6f7 100644 --- a/man/std::experimental::filesystem::directory_entry::replace_filename.3 +++ b/man/std::experimental::filesystem::directory_entry::replace_filename.3 @@ -1,11 +1,11 @@ -.TH std::experimental::filesystem::directory_entry::replace_filename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_entry::replace_filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::replace_filename \- std::experimental::filesystem::directory_entry::replace_filename + .SH Synopsis - void replace_filename( const path& p, file_status status = - file_status(), (filesystem TS) - file_status symlink_status = file_status() - ); + void replace_filename( const path& p ); (filesystem TS) - Changes the filename and the cached file and symlink status of the directory entry. + Changes the filename of the directory entry. Effectively sets path to path().parent_path() / p. @@ -13,9 +13,7 @@ .SH Parameters - p - the path to append to the parent path of the currently stored path - status - new cached file status - symlink_status - new cached symlink status + p - the path to append to the parent path of the currently stored path .SH Return value @@ -29,6 +27,6 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::directory_entry::status,.3 b/man/std::experimental::filesystem::directory_entry::status,.3 new file mode 100644 index 000000000..f90f4f2b4 --- /dev/null +++ b/man/std::experimental::filesystem::directory_entry::status,.3 @@ -0,0 +1,152 @@ +.TH std::experimental::filesystem::directory_entry::status, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_entry::status, \- std::experimental::filesystem::directory_entry::status, + +.SH Synopsis + + file_status status() const; \fB(1)\fP (filesystem TS) + file_status status( error_code& ec ) const; + file_status symlink_status() const; \fB(2)\fP (filesystem TS) + file_status symlink_status( error_code& ec ) const; + + 1) Returns the potentially cached status of the entry, as if determined by a status + call (symlinks are followed to their targets). + 2) Returns the potentially cached status of the entry, as if determined by a + symlink_status call (symlinks are not followed). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The status of the file referred to by the entry. + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + The file status information is usually provided as a byproduct of directory + iteration, in which case it is cached and may be obtained by these member functions + without the cost of an additional system call. During directory iteration, calling + status is unnecessary and accessors such as is_directory should be called with the + cached status value, not with a path. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::experimental::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ... } + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_directory("sandbox/dir"); + mkfifo("sandbox/pipe", 0644); + struct sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, (struct sockaddr*)&addr, sizeof addr); + fs::create_symlink("file", "sandbox/symlink"); + + // demo different status accessors + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "dev/null" is a character device + "dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + file_status represents file type and permissions + \fI(class)\fP + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + status_known checks whether file status is known + \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_entry::status.3 b/man/std::experimental::filesystem::directory_entry::status.3 deleted file mode 100644 index f7b1113d6..000000000 --- a/man/std::experimental::filesystem::directory_entry::status.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::experimental::filesystem::directory_entry::status 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - file_status status() const; (filesystem TS) - file_status status( error_code& ec ) const; (filesystem TS) - - Returns the potentially cached status of the entry. - - The second version returns file_status::none and sets ec to an appropriate error - code if an error occurs. Otherwise, ec is cleared with a call to ec.clear(). - -.SH Parameters - - ec - error code to set - -.SH Return value - - The status of the file referred to by the entry. - -.SH Exceptions - - 1) filesystem_error if an error occurs. The exception object is constructed with - path of the directory entry as an argument. - 2) - noexcept specification: - noexcept - - -.SH See also - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::directory_entry::symlink_status.3 b/man/std::experimental::filesystem::directory_entry::symlink_status.3 deleted file mode 100644 index 65bbbcbf7..000000000 --- a/man/std::experimental::filesystem::directory_entry::symlink_status.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::experimental::filesystem::directory_entry::symlink_status 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - file_status symlink_status() const; (filesystem TS) - file_status symlink_status( error_code& ec ) const; (filesystem TS) - - Returns potentially cached status of the target of the symbolic link referred to by - entry. - - This section is incomplete - -.SH Parameters - - ec - error code to set in case of errors - -.SH Return value - - Returns the symlink status of the directory entry. - -.SH Exceptions - - This section is incomplete - - 2) - noexcept specification: - noexcept - - -.SH See also - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::directory_iterator.3 b/man/std::experimental::filesystem::directory_iterator.3 index 59aa80dc0..a4439a3b0 100644 --- a/man/std::experimental::filesystem::directory_iterator.3 +++ b/man/std::experimental::filesystem::directory_iterator.3 @@ -1,34 +1,90 @@ -.TH std::experimental::filesystem::directory_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_iterator \- std::experimental::filesystem::directory_iterator + .SH Synopsis Defined in header - class directory_iterator : public std::iterator; + class directory_iterator; (filesystem TS) + + directory_iterator is a LegacyInputIterator that iterates over the directory_entry + elements of a directory (but does not visit the subdirectories). The iteration order + is unspecified, except that each directory entry is visited only once. The special + pathnames dot and dot-dot are skipped. - directory_iterator is an input iterator that can advance through entries of a - directory. Directory iteration never returns directory entries to the current (dot) - and parent (dot-dot) directories. The order of directory entries is unspecified. + If the directory_iterator is advanced past the last directory entry, it becomes + equal to the default-constructed iterator, also known as the end iterator. Two end + iterators are always equal, dereferencing or incrementing the end iterator is + undefined behavior. - The past-the-end iterator (simply called the end iterator) is a special iterator. An - end iterator is always equal to an end iterator and never equal to a non-end - iterator. An end iterator is created by the default constructor of directory - iterator and when a directory iterator is advanced past the last directory element. - Calling operator* or operator-> on an end iterator yields undefined behavior. + If a file or a directory is deleted or added to the directory tree after the + directory iterator has been created, it is unspecified whether the change would be + observed through the iterator. - If a file in a directory is deleted after the directory iterator has been created, - the directory iterator may return a directory entry to the deleted file. If, on the - other hand, a new file is created after the directory iterator has been created, - iteration of the directory is not guaranteed to return a directory entry to the new - file. +.SH Member types + + Member type Definition + value_type filesystem::directory_entry + difference_type std::ptrdiff_t + pointer const filesystem::directory_entry* + reference const filesystem::directory_entry& + iterator_category std::input_iterator_tag .SH Member functions constructor constructs a directory iterator - \fI(public member function)\fP + \fI(public member function)\fP destructor default destructor - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP operator* accesses the pointed-to entry - operator-> \fI(public member function)\fP + operator-> \fI(public member function)\fP increment advances to the next entry - operator++ \fI(public member function)\fP + operator++ \fI(public member function)\fP + +.SH Non-member functions + + filesystem::begin(filesystem::directory_iterator) range-based for loop support + filesystem::end(filesystem::directory_iterator) \fI(function)\fP + + Additionally, operator== and operator!= are provided, either as members or as + non-members, as required by LegacyInputIterator. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b"); + std::ofstream{"sandbox/file1.txt"}; + std::ofstream{"sandbox/file2.txt"}; + for (const fs::directory_entry& entry : fs::directory_iterator{"sandbox"}) + std::cout << entry << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/a" + "sandbox/file1.txt" + "sandbox/file2.txt" + +.SH See also + + an iterator to the contents of a directory and its + recursive_directory_iterator subdirectories + \fI(class)\fP + directory_options options for iterating directory contents + \fI(enum)\fP + directory_entry a directory entry + \fI(class)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::directory_iterator::directory_iterator.3 b/man/std::experimental::filesystem::directory_iterator::directory_iterator.3 index 9a72215ec..e2212aef7 100644 --- a/man/std::experimental::filesystem::directory_iterator::directory_iterator.3 +++ b/man/std::experimental::filesystem::directory_iterator::directory_iterator.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::directory_iterator::directory_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_iterator::directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_iterator::directory_iterator \- std::experimental::filesystem::directory_iterator::directory_iterator + .SH Synopsis directory_iterator(); \fB(1)\fP (filesystem TS) explicit directory_iterator( const path& p ); \fB(2)\fP (filesystem TS) @@ -10,7 +13,7 @@ 1) Constructs the end iterator. 2) Constructs a directory iterator that refers to the first directory entry of a - directory identified by p. If p refers to an non-existing file or not a directory, + directory identified by p. If p refers to a non-existing file or not a directory, returns the end iterator. .SH Parameters @@ -20,21 +23,25 @@ .SH Exceptions 1) - noexcept specification: + noexcept specification: noexcept - + 2) filesystem_error if an error occurs. The exception object is constructed with p as an argument. 3) - noexcept specification: + noexcept specification: noexcept - + .SH Notes To iterate over the current directory, construct the iterator as directory_iterator(".") instead of directory_iterator(""). -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_iterator::operator*,operator->.3 b/man/std::experimental::filesystem::directory_iterator::operator*,operator->.3 index f5745fac9..3f4c31584 100644 --- a/man/std::experimental::filesystem::directory_iterator::operator*,operator->.3 +++ b/man/std::experimental::filesystem::directory_iterator::operator*,operator->.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::directory_iterator::operator*,operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_iterator::operator*,operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_iterator::operator*,operator-> \- std::experimental::filesystem::directory_iterator::operator*,operator-> + .SH Synopsis const directory_entry& operator*() const; @@ -6,9 +9,9 @@ const directory_entry* operator->() const; - Accesses the pointed-to directory entry. + Accesses the pointed-to directory_entry. - This section is incomplete + The result of operator* or operator-> on the end iterator is undefined behavior. .SH Parameters @@ -16,12 +19,18 @@ .SH Return value - This section is incomplete + 1) Value of the directory_entry referred to by this iterator. + 2) Pointer to the directory_entry referred to by this iterator. .SH Exceptions - This section is incomplete + May throw implementation-defined exceptions. -.SH Category: +.SH See also - * Todo without reason + operator* accesses the pointed-to entry + operator-> \fI\fI(public member\fP function of\fP + std::experimental::filesystem::recursive_directory_iterator) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::directory_iterator::operator=.3 b/man/std::experimental::filesystem::directory_iterator::operator=.3 index 8db8bc685..502e9f949 100644 --- a/man/std::experimental::filesystem::directory_iterator::operator=.3 +++ b/man/std::experimental::filesystem::directory_iterator::operator=.3 @@ -1,14 +1,19 @@ -.TH std::experimental::filesystem::directory_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_iterator::operator= \- std::experimental::filesystem::directory_iterator::operator= + .SH Synopsis - directory_iterator& operator=(const directory_iterator&) = default; - (filesystem TS) - directory_iterator& operator=(directory_iterator&&) = default; + directory_iterator& operator++(); + (filesystem TS) + directory_iterator& increment( error_code& ec ) noexcept; + + Advances the iterator to the next entry. This section is incomplete .SH Parameters - This section is incomplete + ec - error code to store error status to .SH Return value @@ -16,8 +21,18 @@ .SH Exceptions + 1) + This section is incomplete -.SH Category: + 2) + noexcept specification: + noexcept +.SH Categories: + * Noindexed pages * Todo without reason + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::directory_options.3 b/man/std::experimental::filesystem::directory_options.3 index 8d25e6833..2d9d392e0 100644 --- a/man/std::experimental::filesystem::directory_options.3 +++ b/man/std::experimental::filesystem::directory_options.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::directory_options 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::directory_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::directory_options \- std::experimental::filesystem::directory_options + .SH Synopsis Defined in header enum class directory_options { @@ -7,14 +10,32 @@ follow_directory_symlink, (filesystem TS) skip_permission_denied - } + }; + + This type represents available options that control the behavior of the + directory_iterator and recursive_directory_iterator. + + directory_options satisfies the requirements of BitmaskType (which means the bitwise + operators operator&, operator|, operator^, operator~, operator&=, operator|=, and + operator^= are defined for this type). - This section is incomplete +.SH Member constants + + Member constant Value Meaning + none 0 (Default) Skip directory symlinks, permission denied + is error. + follow_directory_symlink 1 Follow rather than skip directory symlinks. + skip_permission_denied 2 Skip directories that would otherwise result in + permission denied errors. .SH See also - This section is incomplete + constructs a directory iterator + constructor \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_iterator) + constructs a recursive directory iterator + constructor \fI\fI(public member\fP function of\fP + std::experimental::filesystem::recursive_directory_iterator) .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::equivalent.3 b/man/std::experimental::filesystem::equivalent.3 index cc68b9b55..b47fe97bc 100644 --- a/man/std::experimental::filesystem::equivalent.3 +++ b/man/std::experimental::filesystem::equivalent.3 @@ -1,45 +1,91 @@ -.TH std::experimental::filesystem::equivalent 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::equivalent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::equivalent \- std::experimental::filesystem::equivalent + .SH Synopsis Defined in header - bool equivalent( const path& p1, const path& p2 ); \fB(1)\fP (filesystem TS) - bool equivalent( const path& p1, const path& p2, error_code& ec \fB(2)\fP (filesystem TS) + bool equivalent( const path& p1, const path& p2 ); + bool equivalent( const path& p1, const path& p2, error_code& ec \fB(1)\fP (filesystem TS) ); - Checks whether the paths p1 and p2 refer to the same file or directory. + Checks whether the paths p1 and p2 refer to the same file or directory and have the + same file status as determined by status (symlinks are followed). - Internally, the function checks whether the paths have the same file status and - resolve to the same file system entity, i.e. are on the same physical device at the - same location. + If p1 or p2 does not exist or if their file type is not file, directory, or symlink + (as determined by is_other), an error is reported. - The second version sets ec to an appropriate error code and returns false if an - error occurs. Otherwise, ec is cleared with a call to ec.clear(). + The non-throwing overload returns false on errors. .SH Parameters p1, p2 - paths to check for equivalence - ec - error code to store error status to + ec - out-parameter for error reporting in the non-throwing overload .SH Return value - true if the paths refer to the same file or directory. + true if the p1 and p2 refer to the same file or directory and their file status is + the same. false otherwise. .SH Exceptions - 1) filesystem_error if + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p1 as the first argument, p2 as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept - * neither of the paths resolve to an existing file - * both paths resolve to a file of type other - * other error occurs - 2) - noexcept specification: - noexcept - +.SH Notes + + Two paths are considered to resolve to the same file system entity if st_dev and + st_ino of their POSIX stat structure, obtained as if by POSIX stat, are equal + (meaning, the files are located on the same device at the same location). + + In particular, all hard links for the same file or directory are equivalent, and a + symlink and its target on the same file system are equivalent. + +.SH Example -.SH See also - This section is incomplete +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + // hard link equivalency + fs::path p1 = "."; + fs::path p2 = fs::current_path(); + if (fs::equivalent(p1, p2)) + std::cout << p1 << " is equivalent to " << p2 << '\\n'; + + // symlink equivalency + fs::path p3 = "/lib/libc.so.6"; + fs::path p4 = p3.parent_path() / fs::read_symlink(p3); + if (fs::equivalent(p3, p4)) + std::cout << p3 << " is equivalent to " << p4 << '\\n'; + } + +.SH Possible output: + + "." is equivalent to "/var/tmp/test" + "/lib/libc.so.6" is equivalent to "/lib/libc-2.12.so" + +.SH See also -.SH Category: + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::exists.3 b/man/std::experimental::filesystem::exists.3 index 967f1162e..6f646c8da 100644 --- a/man/std::experimental::filesystem::exists.3 +++ b/man/std::experimental::filesystem::exists.3 @@ -1,23 +1,25 @@ -.TH std::experimental::filesystem::exists 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::exists 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::exists \- std::experimental::filesystem::exists + .SH Synopsis Defined in header - bool exists( file_status s ) noexcept; \fB(1)\fP (filesystem TS) - bool exists( const path& p ); \fB(2)\fP (filesystem TS) - bool exists( const path& p, error_code& ec ) noexcept; \fB(3)\fP (filesystem TS) + bool exists( file_status s ) \fB(1)\fP (filesystem TS) + bool exists( const path& p ); \fB(2)\fP (filesystem TS) + bool exists( const path& p, error_code& ec ) Checks if the given file status or path corresponds to an existing file or directory. - 1) Equivalent to status_known(s) && s.type() |= file_type::not_found. - 2) Equivalent to exists(status(p)). - 3) Equivalent to exists(status(p, ec)). Returns false and sets ec to an appropriate - error code if an error occurs. Otherwise, ec is cleared with a call to ec.clear(). + 1) Equivalent to status_known(s) && s.type() != file_type::not_found. + 2) Equivalent to exists(status(p)) or exists(status(p, ec)) (symlinks are followed). + The non-throwing overload returns false if an error occurs. .SH Parameters s - file status to check p - path to examine - ec - error code to store the error status to + ec - out-parameter for error reporting in the non-throwing overload .SH Return value @@ -26,18 +28,79 @@ .SH Exceptions - 1,3) - noexcept specification: + 1) + noexcept specification: noexcept - - 2) filesystem_error if an error occurs. The exception object is constructed with p - as an argument. The error code is set to an appropriate error code for the error - that caused the failure. -.SH See also + 2) The overload that does not take an error_code& parameter throws filesystem_error + on underlying OS API errors, constructed with p as the first argument and the OS + error code as the error code argument. std::bad_alloc may be thrown if memory + allocation fails. The overload taking an error_code& parameter sets it to the OS API + error code if an OS API call fails, and executes ec.clear() if no errors occur. This + overload has + noexcept specification: + noexcept + + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration. During directory iteration, calling exists(*iterator) is less + efficient than exists(iterator->status()). + +.SH Example + - This section is incomplete +// Run this code + + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + void demo_exists(const fs::path& p, fs::file_status s = fs::file_status{}) + { + std::cout << p; + if (fs::status_known(s) ? fs::exists(s) : fs::exists(p)) + std::cout << " exists\\n"; + else + std::cout << " does not exist\\n"; + } + + int main() + { + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_symlink("non-existing", "sandbox/symlink"); + + demo_exists("sandbox"); + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_exists(*it, it->status()); // use cached status from directory entry + fs::remove_all("sandbox"); + } + +.SH Output: + + "sandbox" exists + "sandbox/file" exists + "sandbox/symlink" does not exist + +.SH See also -.SH Category: + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + file_status represents file type and permissions + \fI(class)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory entry + symlink_status \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::file_size.3 b/man/std::experimental::filesystem::file_size.3 index f7126a8b1..e0d600942 100644 --- a/man/std::experimental::filesystem::file_size.3 +++ b/man/std::experimental::filesystem::file_size.3 @@ -1,42 +1,83 @@ -.TH std::experimental::filesystem::file_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_size \- std::experimental::filesystem::file_size + .SH Synopsis Defined in header - uintmax_t file_size( const path& p ); \fB(1)\fP (filesystem TS) - uintmax_t file_size( const path& p, error_code& ec ); \fB(2)\fP (filesystem TS) + std::uintmax_t file_size( const path& p ); \fB(1)\fP (filesystem TS) + std::uintmax_t file_size( const path& p, error_code& ec ); - Returns the size of a regular file. If p does not resolve to a regular file, returns - -1. + Returns the size of the regular file p, determined as if by reading the st_size + member of the structure obtained by POSIX stat (symlinks are followed). - The second version sets ec to an appropriate error code if an error occurs. - Otherwise, ec is cleared with a call to ec.clear(). + Attempting to determine the size of a directory (as well as any other file that is + not a regular file or a symlink) is treated as an error. - This section is incomplete - Reason: does the first version throw if p is not a regular file? + The non-throwing overload returns returns -1 on errors. .SH Parameters - p - path to the regular file - ec - error code to modify in case of error + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload .SH Return value - The size of the file or -1 on error. + The size of the file, in bytes. .SH Exceptions - 1) filesystem_error if an error occurs. The exception object is constructed with p - as an argument. The error code is set to an appropriate error code for the error - that caused the failure. - 2) - noexcept specification: + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: noexcept - -.SH See also - This section is incomplete +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = fs::current_path() / "example.bin"; + std::ofstream(p).put('a'); // create file of size 1 + std::cout << "File size = " << fs::file_size(p) << '\\n'; + fs::remove(p); + + try + { + fs::file_size("/dev"); // attempt to get size of a directory + } + catch (fs::filesystem_error& e) + { + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + File size = 1 + filesystem error: cannot get file size: Is a directory [/dev] + +.SH See also - Categories: + resize_file changes the size of a regular file by truncation or zero-fill + \fI(function)\fP + space determines available free space on the file system + \fI(function)\fP - * Todo with reason - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::file_status.3 b/man/std::experimental::filesystem::file_status.3 index 20e4655bb..32b34e402 100644 --- a/man/std::experimental::filesystem::file_status.3 +++ b/man/std::experimental::filesystem::file_status.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::file_status 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_status \- std::experimental::filesystem::file_status + .SH Synopsis Defined in header class file_status; (filesystem TS) @@ -8,12 +11,15 @@ .SH Member functions constructor constructs a file_status object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP destructor implicit destructor - \fI(public member function)\fP + \fI(public member function)\fP type gets or sets the type of the file - \fI(public member function)\fP + \fI(public member function)\fP permissions gets or sets the permissions of the file - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::file_status::file_status.3 b/man/std::experimental::filesystem::file_status::file_status.3 index 385b01b9a..924d0caca 100644 --- a/man/std::experimental::filesystem::file_status::file_status.3 +++ b/man/std::experimental::filesystem::file_status::file_status.3 @@ -1,9 +1,12 @@ -.TH std::experimental::filesystem::file_status::file_status 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_status::file_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_status::file_status \- std::experimental::filesystem::file_status::file_status + .SH Synopsis - file_status( const file_status& ) = default; \fB(1)\fP (filesystem TS) - file_status( file_status&& ) = default; \fB(2)\fP (filesystem TS) - explicit file_status( file_type type = file_type::none, \fB(3)\fP (filesystem TS) - perms permissions = perms::unknown); + file_status( const file_status& ) = default; \fB(1)\fP (filesystem TS) + file_status( file_status&& ) = default; \fB(2)\fP (filesystem TS) + explicit file_status( file_type type = file_type::none, \fB(3)\fP (filesystem TS) + perms permissions = perms::unknown ); Constructs a new file_status object. @@ -18,9 +21,13 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - -.SH Category: +.SH Categories: + * Noindexed pages * Todo without reason + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::file_status::operator=.3 b/man/std::experimental::filesystem::file_status::operator=.3 index 7be867eb2..72d5db539 100644 --- a/man/std::experimental::filesystem::file_status::operator=.3 +++ b/man/std::experimental::filesystem::file_status::operator=.3 @@ -1,9 +1,10 @@ -.TH std::experimental::filesystem::file_status::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_status::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_status::operator= \- std::experimental::filesystem::file_status::operator= + .SH Synopsis file_status& operator=( const file_status& other ) = default; \fB(1)\fP (filesystem TS) file_status& operator=( file_status&& other ) = default; \fB(2)\fP (filesystem TS) - explicit file_status( file_type type = file_type::none, \fB(3)\fP (filesystem TS) - perms permissions = perms::unknown); Copy- or move-assigns another file type object. @@ -17,9 +18,13 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - -.SH Category: +.SH Categories: + * Noindexed pages * Todo without reason + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::file_status::permissions.3 b/man/std::experimental::filesystem::file_status::permissions.3 index ef469cd7b..197719576 100644 --- a/man/std::experimental::filesystem::file_status::permissions.3 +++ b/man/std::experimental::filesystem::file_status::permissions.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::file_status::permissions 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_status::permissions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_status::permissions \- std::experimental::filesystem::file_status::permissions + .SH Synopsis perms permissions() const; \fB(1)\fP (filesystem TS) void permissions( perms perm ); \fB(2)\fP (filesystem TS) @@ -19,6 +22,12 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::file_status::type.3 b/man/std::experimental::filesystem::file_status::type.3 index bfb522db3..4e6480c72 100644 --- a/man/std::experimental::filesystem::file_status::type.3 +++ b/man/std::experimental::filesystem::file_status::type.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::file_status::type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_status::type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_status::type \- std::experimental::filesystem::file_status::type + .SH Synopsis file_type type() const; \fB(1)\fP (filesystem TS) void type( file_type type ); \fB(2)\fP (filesystem TS) @@ -19,6 +22,12 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::file_time_type.3 b/man/std::experimental::filesystem::file_time_type.3 index 7825eb018..982ef97d8 100644 --- a/man/std::experimental::filesystem::file_time_type.3 +++ b/man/std::experimental::filesystem::file_time_type.3 @@ -1,14 +1,55 @@ -.TH std::experimental::filesystem::file_time_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_time_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_time_type \- std::experimental::filesystem::file_time_type + .SH Synopsis Defined in header using file_time_type = chrono::time_point; (filesystem TS) - Represents file time. + Represents file time. trivial-clock is an implementation-defined type that satisfies + TrivialClock and is sufficient to represent the resolution and range of the file + time values offered by the filesystem. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + using namespace std::chrono_literals; + + int main() + { + fs::path p = fs::current_path() / "example.bin"; + std::ofstream(p.c_str()).put('a'); // create file + auto ftime = fs::last_write_time(p); + + std::time_t cftime = decltype(ftime)::clock::to_time_t(ftime); // assuming system_clock + std::cout << "File write time is " << std::asctime(std::localtime(&cftime)) << '\\n'; + + fs::last_write_time(p, ftime + 1h); // move file write time 1 hour to the future + ftime = fs::last_write_time(p); // read back from the filesystem + + cftime = decltype(ftime)::clock::to_time_t(ftime); + std::cout << "File write time is " << std::asctime(std::localtime(&cftime)) << '\\n'; + fs::remove(p); + } + +.SH Possible output: + + File write time is Tue Mar 31 19:47:04 2015 + + File write time is Tue Mar 31 20:47:04 2015 .SH See also - This section is incomplete + last_write_time gets or sets the time of the last data modification + \fI(function)\fP .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::file_type.3 b/man/std::experimental::filesystem::file_type.3 index ec0846d77..e5683f311 100644 --- a/man/std::experimental::filesystem::file_type.3 +++ b/man/std::experimental::filesystem::file_type.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::file_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::file_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::file_type \- std::experimental::filesystem::file_type + .SH Synopsis Defined in header enum class file_type { @@ -39,6 +42,6 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::filesystem_error.3 b/man/std::experimental::filesystem::filesystem_error.3 index 47fbec464..5cdcc0021 100644 --- a/man/std::experimental::filesystem::filesystem_error.3 +++ b/man/std::experimental::filesystem::filesystem_error.3 @@ -1,28 +1,31 @@ -.TH std::experimental::filesystem::filesystem_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::filesystem_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::filesystem_error \- std::experimental::filesystem::filesystem_error + .SH Synopsis Defined in header class filesystem_error; (filesystem TS) An exception type thrown when errors are encountered. - This section is incomplete - Reason: add inheritance diagram + std-experimental-filesystem-filesystem error-inheritance.svg + + Inheritance diagram .SH Member functions constructor constructs the error object - \fI(public member function)\fP + \fI(public member function)\fP path1 returns the paths that were involved in the operation that caused the path2 error - \fI(public member function)\fP + \fI(public member function)\fP what returns the explanatory string - \fI(public member function)\fP + \fI(public member function)\fP .SH See also This section is incomplete - Categories: - - * Todo with reason +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::filesystem_error::filesystem_error.3 b/man/std::experimental::filesystem::filesystem_error::filesystem_error.3 index cb4f0d899..2cc112fce 100644 --- a/man/std::experimental::filesystem::filesystem_error::filesystem_error.3 +++ b/man/std::experimental::filesystem::filesystem_error::filesystem_error.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::filesystem_error::filesystem_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::filesystem_error::filesystem_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::filesystem_error::filesystem_error \- std::experimental::filesystem::filesystem_error::filesystem_error + .SH Synopsis filesystem_error( const string& what_arg, error_code ec ); \fB(1)\fP (filesystem TS) filesystem_error( const string& what_arg, const path& p1, \fB(2)\fP (filesystem TS) @@ -18,6 +21,6 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::filesystem_error::path1,path2.3 b/man/std::experimental::filesystem::filesystem_error::path1,path2.3 index 60ef15a65..2f98b8ce9 100644 --- a/man/std::experimental::filesystem::filesystem_error::path1,path2.3 +++ b/man/std::experimental::filesystem::filesystem_error::path1,path2.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::filesystem_error::path1,path2 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::filesystem_error::path1,path2 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::filesystem_error::path1,path2 \- std::experimental::filesystem::filesystem_error::path1,path2 + .SH Synopsis const path& path1() const; (filesystem TS) const path& path2() const; (filesystem TS) @@ -11,14 +14,18 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + .SH See also This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::filesystem_error::what.3 b/man/std::experimental::filesystem::filesystem_error::what.3 index 8979047a7..49aa3dfd3 100644 --- a/man/std::experimental::filesystem::filesystem_error::what.3 +++ b/man/std::experimental::filesystem::filesystem_error::what.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::filesystem_error::what 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::filesystem_error::what 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::filesystem_error::what \- std::experimental::filesystem::filesystem_error::what + .SH Synopsis const char* what() const; (filesystem TS) @@ -10,14 +13,18 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + .SH See also This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::hard_link_count.3 b/man/std::experimental::filesystem::hard_link_count.3 index 29ebce86e..7cece4949 100644 --- a/man/std::experimental::filesystem::hard_link_count.3 +++ b/man/std::experimental::filesystem::hard_link_count.3 @@ -1,17 +1,20 @@ -.TH std::experimental::filesystem::hard_link_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::hard_link_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::hard_link_count \- std::experimental::filesystem::hard_link_count + .SH Synopsis Defined in header - uintmax_t hard_link_count( const path& p ); \fB(1)\fP (filesystem TS) - uintmax_t hard_link_count( const path& p, error_code& ec ); \fB(2)\fP (filesystem TS) + std::uintmax_t hard_link_count( const path& p ); \fB(1)\fP (filesystem TS) + std::uintmax_t hard_link_count( const path& p, error_code& ec ); - Returns the number of hard links for the file identified by path p. + Returns the number of hard links for the filesystem object identified by path p. - The second version returns -1 and sets ec to an appropriate error code if an error - occurs. Otherwise, ec is cleared using ec.clear(). + The non-throwing overload returns static_cast(-1) on errors. .SH Parameters - p - path to return the hard link count for + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload .SH Return value @@ -19,17 +22,53 @@ .SH Exceptions - 1) filesystem_error if an error occurs. The exception object is constructed with p - as an argument. - 2) - noexcept specification: + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: noexcept - -.SH See also - This section is incomplete +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + // On a POSIX-style filesystem, each directory has at least 2 hard links: + // itself and the special member pathname "." + fs::path p = fs::current_path(); + std::cout << "Number of hard links for current path is " + << fs::hard_link_count(p) << '\\n'; + + // each ".." is a hard link to the parent directory, so the total number + // of hard links for any directory is 2 plus number of direct subdirectories + p = fs::current_path() / ".."; // each dot-dot is a hard link to parent + std::cout << "Number of hard links for .. is " + << fs::hard_link_count(p) << '\\n'; + } + +.SH Output: + + Number of hard links for current path is 2 + Number of hard links for .. is 3 + +.SH See also -.SH Category: + create_hard_link creates a hard link + \fI(function)\fP - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_block_file.3 b/man/std::experimental::filesystem::is_block_file.3 index cf2f0d1bb..ae63edf78 100644 --- a/man/std::experimental::filesystem::is_block_file.3 +++ b/man/std::experimental::filesystem::is_block_file.3 @@ -1,42 +1,163 @@ -.TH std::experimental::filesystem::is_block_file 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_block_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_block_file \- std::experimental::filesystem::is_block_file + .SH Synopsis Defined in header - bool is_block_file( file_status s ); \fB(1)\fP (filesystem TS) - bool is_block_file( const path& p ); \fB(2)\fP (filesystem TS) - bool is_block_file( const path& p, error_code& ec ); \fB(3)\fP (filesystem TS) + bool is_block_file( file_status s ); \fB(1)\fP (filesystem TS) + bool is_block_file( const path& p ); \fB(2)\fP (filesystem TS) + bool is_block_file( const path& p, error_code& ec ) noexcept; - Checks if the given file status or path corresponds to a block special file. + Checks if the given file status or path corresponds to a block special file, as if + determined by the POSIX S_ISBLK . Examples of block special files are block devices + such as /dev/sda or /dev/loop0 on Linux. - 1) Equivalent to s.type() == file_type::character. - 2) Equivalent to is_block_file(status(p)). - 3) Equivalent to is_block_file(status(p, ec)). Returns false and sets ec to an - appropriate error code if an error occurs. Otherwise, ec is cleared with a call to - ec.clear(). + 1) Equivalent to s.type() == file_type::block. + 2) Equivalent to is_block_file(status(p)) or is_block_file(status(p, ec)). .SH Parameters s - file status to check p - path to examine - ec - error code to store error status to + ec - out-parameter for error reporting in the non-throwing overload .SH Return value - true if the given path or file status corresponds to a block special file. + true if the file indicated by p or if the type indicated s refers to a block device. + The non-throwing overload returns false if an error occurs. .SH Exceptions - 1,3) - noexcept specification: + 1) + noexcept specification: noexcept - - 2) filesystem_error if an error occurs. The exception object is constructed with p - as an argument. The error code is set to an appropriate error code for the error - that caused the failure. -.SH See also + 2) The overload that does not take an error_code& parameter throws filesystem_error + on underlying OS API errors, constructed with p as the first argument and the OS + error code as the error code argument. std::bad_alloc may be thrown if memory + allocation fails. The overload taking an error_code& parameter sets it to the OS API + error code if an OS API call fails, and executes ec.clear() if no errors occur. This + overload has + noexcept specification: + noexcept + + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration. During directory iteration, calling is_block_file(*iterator) is + less efficient than is_block_file(iterator->status()). + +.SH Example + + +// Run this code - This section is incomplete + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::experimental::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ... } + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_directory("sandbox/dir"); + mkfifo("sandbox/pipe", 0644); + struct sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, (struct sockaddr*)&addr, sizeof addr); + fs::create_symlink("file", "sandbox/symlink"); + + // demo different status accessors + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "dev/null" is a character device + "dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also -.SH Category: + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + file_status represents file type and permissions + \fI(class)\fP + status_known checks whether file status is known + \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory + symlink_status entry + \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_character_file.3 b/man/std::experimental::filesystem::is_character_file.3 index 032f60c7b..b108b9319 100644 --- a/man/std::experimental::filesystem::is_character_file.3 +++ b/man/std::experimental::filesystem::is_character_file.3 @@ -1,43 +1,164 @@ -.TH std::experimental::filesystem::is_character_file 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_character_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_character_file \- std::experimental::filesystem::is_character_file + .SH Synopsis Defined in header bool is_character_file( file_status s ); \fB(1)\fP (filesystem TS) bool is_character_file( const path& p ); \fB(2)\fP (filesystem TS) - bool is_character_file( const path& p, error_code& ec ); \fB(3)\fP (filesystem TS) + bool is_character_file( const path& p, error_code& ec ); - Checks if the given file status or path corresponds to a character special file. + Checks if the given file status or path corresponds to a character special file, as + if determined by POSIX S_ISCHR. Examples of character special files are character + devices such as /dev/null, /dev/tty, /dev/audio, or /dev/nvram on Linux. 1) Equivalent to s.type() == file_type::character. - 2) Equivalent to is_character_file(status(p)). - 3) Equivalent to is_character_file(status(p, ec)). Returns false and sets ec to an - appropriate error code if an error occurs. Otherwise, ec is cleared with a call to - ec.clear(). + 2) Equivalent to is_character_file(status(p)) or is_character_file(status(p, ec)) + respectively. .SH Parameters s - file status to check p - path to examine - ec - error code to store the error status to + ec - out-parameter for error reporting in the non-throwing overload .SH Return value - true if the given path or file status corresponds to a character special file, false - otherwise. + true if the file indicated by p or if the type indicated s refers to a block device, + false otherwise. The non-throwing overload returns false if an error occurs. .SH Exceptions - 1,3) - noexcept specification: + 1) + noexcept specification: noexcept - - 2) filesystem_error if an error occurs. The exception object is constructed with p - as an argument. The error code is set to an appropriate error code for the error - that caused the failure. -.SH See also + 2) The overload that does not take an error_code& parameter throws filesystem_error + on underlying OS API errors, constructed with p as the first argument and the OS + error code as the error code argument. std::bad_alloc may be thrown if memory + allocation fails. The overload taking an error_code& parameter sets it to the OS API + error code if an OS API call fails, and executes ec.clear() if no errors occur. This + overload has + noexcept specification: + noexcept + + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration. During directory iteration, calling + is_character_file(*iterator) is less efficient than + is_character_file(iterator->status()). + +.SH Example + + +// Run this code - This section is incomplete + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::experimental::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ... } + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_directory("sandbox/dir"); + mkfifo("sandbox/pipe", 0644); + struct sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, (struct sockaddr*)&addr, sizeof addr); + fs::create_symlink("file", "sandbox/symlink"); + + // demo different status accessors + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "dev/null" is a character device + "dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also -.SH Category: + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + file_status represents file type and permissions + \fI(class)\fP + status_known checks whether file status is known + \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory entry + symlink_status \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_directory.3 b/man/std::experimental::filesystem::is_directory.3 index 848f4b436..469bc3ff9 100644 --- a/man/std::experimental::filesystem::is_directory.3 +++ b/man/std::experimental::filesystem::is_directory.3 @@ -1,13 +1,16 @@ -.TH std::experimental::filesystem::is_directory 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_directory 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_directory \- std::experimental::filesystem::is_directory + .SH Synopsis Defined in header bool is_directory( file_status s ); \fB(1)\fP (filesystem TS) bool is_directory( const path& p ); \fB(2)\fP (filesystem TS) bool is_directory( const path& p, error_code& ec ); \fB(3)\fP (filesystem TS) - Checks if the gived file status or path corresponds to a directory. + Checks if the given file status or path corresponds to a directory. - 1) Equivalent to s.type() == file_type::character. + 1) Equivalent to s.type() == file_type::directory. 2) Equivalent to is_directory(status(p)). 3) Equivalent to is_directory(status(p, ec)). Returns false if error occurs. @@ -24,9 +27,9 @@ .SH Exceptions 1,3) - noexcept specification: + noexcept specification: noexcept - + 2) Throws filesystem_error if an error occurs. The exception object is constructed with p as an argument. @@ -34,6 +37,10 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_empty.3 b/man/std::experimental::filesystem::is_empty.3 index eb69fae67..152d6c850 100644 --- a/man/std::experimental::filesystem::is_empty.3 +++ b/man/std::experimental::filesystem::is_empty.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::is_empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_empty \- std::experimental::filesystem::is_empty + .SH Synopsis Defined in header bool is_empty( const path& p ); \fB(1)\fP (filesystem TS) @@ -24,14 +27,18 @@ as an argument. The error code is set to an appropriate error code for the error that caused the failure. 2) - noexcept specification: + noexcept specification: noexcept - + .SH See also This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_fifo.3 b/man/std::experimental::filesystem::is_fifo.3 index db14cb06c..729c17fab 100644 --- a/man/std::experimental::filesystem::is_fifo.3 +++ b/man/std::experimental::filesystem::is_fifo.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::is_fifo 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_fifo 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_fifo \- std::experimental::filesystem::is_fifo + .SH Synopsis Defined in header bool is_fifo( file_status s ); \fB(1)\fP (filesystem TS) @@ -25,9 +28,9 @@ .SH Exceptions 1,3) - noexcept specification: + noexcept specification: noexcept - + 2) Throws filesystem_error if an error occurs. The exception object is constructed with p as an argument. @@ -35,6 +38,10 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_other.3 b/man/std::experimental::filesystem::is_other.3 index 7e32e39f4..327f7b08d 100644 --- a/man/std::experimental::filesystem::is_other.3 +++ b/man/std::experimental::filesystem::is_other.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::is_other 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_other 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_other \- std::experimental::filesystem::is_other + .SH Synopsis Defined in header bool is_other( file_status s ); \fB(1)\fP (filesystem TS) @@ -28,9 +31,9 @@ .SH Exceptions 1,3) - noexcept specification: + noexcept specification: noexcept - + 2) Throws filesystem_error if an error occurs. The error is constructed with p as an argument. The error code is set to an appropriate error code for the error that caused the failure. @@ -39,6 +42,10 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_regular_file.3 b/man/std::experimental::filesystem::is_regular_file.3 index 4e671807c..c3b014e0c 100644 --- a/man/std::experimental::filesystem::is_regular_file.3 +++ b/man/std::experimental::filesystem::is_regular_file.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::is_regular_file 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_regular_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_regular_file \- std::experimental::filesystem::is_regular_file + .SH Synopsis Defined in header bool is_regular_file( file_status s ); \fB(1)\fP (filesystem TS) @@ -7,7 +10,7 @@ Checks if the given file status or path corresponds to a regular file. - 1) Equivalent to s.type() == file_type::socket. + 1) Equivalent to s.type() == file_type::regular. 2) Equivalent to is_regular_file(status(p)). 3) Equivalent to is_regular_file(status(p, ec)). Returns false and sets ec to an appropriate error code if an error occurs. Otherwise, ec is cleared with a call to @@ -32,9 +35,9 @@ .SH Exceptions 1,3) - noexcept specification: + noexcept specification: noexcept - + 2) Throws filesystem_error if an error occurs. The error is constructed with p as an argument. The error code is set to an appropriate error code for the error that caused the failure. @@ -43,7 +46,11 @@ This section is incomplete - Categories: - +.SH Categories: + * Noindexed pages * Todo with reason + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_socket.3 b/man/std::experimental::filesystem::is_socket.3 index 498635542..7165ca373 100644 --- a/man/std::experimental::filesystem::is_socket.3 +++ b/man/std::experimental::filesystem::is_socket.3 @@ -1,42 +1,166 @@ -.TH std::experimental::filesystem::is_socket 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_socket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_socket \- std::experimental::filesystem::is_socket + .SH Synopsis Defined in header bool is_socket( file_status s ); \fB(1)\fP (filesystem TS) bool is_socket( const path& p ); \fB(2)\fP (filesystem TS) - bool is_socket( const path& p, error_code& ec ); \fB(3)\fP (filesystem TS) + bool is_socket( const path& p, error_code& ec ); - Checks if the given file status or path corresponds to a socket file. + Checks if the given file status or path corresponds to a named IPC socket, as if + determined by the POSIX S_IFSOCK. 1) Equivalent to s.type() == file_type::socket. - 2) Equivalent to is_socket(status(p)). - 3) Equivalent to is_socket(status(p, ec)). Returns false and sets ec to an - appropriate error code if an error occurs. Otherwise, ec is cleared with a call to - ec.clear(). + 2) Equivalent to is_socket(status(p)) or is_socket(status(p, ec)). .SH Parameters s - file status to check p - path to examine - ec - error code to store the error status to + ec - out-parameter for error reporting in the non-throwing overload .SH Return value - true if the given path or file status corresponds to a socket file, false otherwise. + true if the file indicated by p or if the type indicated s refers to a named socket. + The non-throwing overload returns false if an error occurs. .SH Exceptions - 1,3) - noexcept specification: + 1) + noexcept specification: noexcept - - 2) Throws filesystem_error if an error occurs. The error is constructed with p as an - argument. The error code is set to an appropriate error code for the error that - caused the failure. -.SH See also + 2) The overload that does not take an error_code& parameter throws filesystem_error + on underlying OS API errors, constructed with p as the first argument and the OS + error code as the error code argument. std::bad_alloc may be thrown if memory + allocation fails. The overload taking an error_code& parameter sets it to the OS API + error code if an OS API call fails, and executes ec.clear() if no errors occur. This + overload has + noexcept specification: + noexcept + + +.SH Notes + + Named sockets are UNIX domain sockets constructed with socket and bind POSIX APIs, + which may be used for advanced interprocess communication. In particular, they may + be used to transport open file descriptors from one running process to another. + + The information provided by this function is usually also provided as a byproduct of + directory iteration. During directory iteration, calling is_socket(*iterator) is + less efficient than is_socket(iterator->status()). + +.SH Example + + +// Run this code - This section is incomplete + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::experimental::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ... } + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_directory("sandbox/dir"); + mkfifo("sandbox/pipe", 0644); + struct sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, (struct sockaddr*)&addr, sizeof addr); + fs::create_symlink("file", "sandbox/symlink"); + + // demo different status accessors + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "dev/null" is a character device + "dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also -.SH Category: + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + file_status represents file type and permissions + \fI(class)\fP + status_known checks whether file status is known + \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory + symlink_status entry + \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::is_symlink.3 b/man/std::experimental::filesystem::is_symlink.3 index 8f264bbee..64f623369 100644 --- a/man/std::experimental::filesystem::is_symlink.3 +++ b/man/std::experimental::filesystem::is_symlink.3 @@ -1,43 +1,162 @@ -.TH std::experimental::filesystem::is_symlink 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::is_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::is_symlink \- std::experimental::filesystem::is_symlink + .SH Synopsis Defined in header bool is_symlink( file_status s ); \fB(1)\fP (filesystem TS) bool is_symlink( const path& p ); \fB(2)\fP (filesystem TS) - bool is_symlink( const path& p, error_code& ec ); \fB(3)\fP (filesystem TS) + bool is_symlink( const path& p, error_code& ec ); - Checks if the given file status or path corresponds to a symbolic file. + Checks if the given file status or path corresponds to a symbolic link, as if + determined by the POSIX S_IFLNK. 1) Equivalent to s.type() == file_type::symlink. - 2) Equivalent to is_symlink(status(p)). - 3) Equivalent to is_symlink(status(p, ec)). Returns false and sets ec to an - appropriate error code if an error occurs. Otherwise, ec is cleared with a call to - ec.clear(). + 2) Equivalent to is_symlink(status(p)) or is_symlink(status(p, ec)). .SH Parameters s - file status to check p - path to examine - ec - error code to store the error status to + ec - out-parameter for error reporting in the non-throwing overload .SH Return value - true if the given path or file status corresponds to a symbolic link, false - otherwise. + true if the file indicated by p or if the type indicated s refers to a symbolic + link. The non-throwing overload returns false if an error occurs. .SH Exceptions - 1,3) - noexcept specification: + 1) + noexcept specification: noexcept - - 2) Throws filesystem_error if an error occurs. The error is constructed with p as an - argument. The error code is set to an appropriate error code for the error that - caused the failure. -.SH See also + 2) The overload that does not take an error_code& parameter throws filesystem_error + on underlying OS API errors, constructed with p as the first argument and the OS + error code as the error code argument. std::bad_alloc may be thrown if memory + allocation fails. The overload taking an error_code& parameter sets it to the OS API + error code if an OS API call fails, and executes ec.clear() if no errors occur. This + overload has + noexcept specification: + noexcept + + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration. During directory iteration, calling is_symlink(*iterator) is + less efficient than is_symlink(iterator->status()). + +.SH Example + + +// Run this code - This section is incomplete + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::experimental::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ... } + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_directory("sandbox/dir"); + mkfifo("sandbox/pipe", 0644); + struct sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, (struct sockaddr*)&addr, sizeof addr); + fs::create_symlink("file", "sandbox/symlink"); + + // demo different status accessors + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "dev/null" is a character device + "dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also -.SH Category: + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + file_status represents file type and permissions + \fI(class)\fP + status_known checks whether file status is known + \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory + symlink_status entry + \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::last_write_time.3 b/man/std::experimental::filesystem::last_write_time.3 new file mode 100644 index 000000000..94abf8b41 --- /dev/null +++ b/man/std::experimental::filesystem::last_write_time.3 @@ -0,0 +1,94 @@ +.TH std::experimental::filesystem::last_write_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::last_write_time \- std::experimental::filesystem::last_write_time + +.SH Synopsis + Defined in header + file_time_type last_write_time( const path& p ); \fB(1)\fP (filesystem TS) + file_time_type last_write_time( const path& p, error_code& ec ) + void last_write_time( const path& p, file_time_type new_time ); + void last_write_time( const path& p, file_time_type new_time, \fB(2)\fP (filesystem TS) + error_code& ec ); + + 1) Returns the time of the last modification of p, determined as if by accessing the + member st_mtime of the POSIX stat (symlinks are followed). The non-throwing overload + returns file_time_type::min() on errors. + 2) Changes the time of the last modification of p, as if by POSIX futimens (symlinks + are followed). + +.SH Parameters + + p - path to examine or modify + new_time - new modification time + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + 1) The time of the last modification of p. + 2) \fI(none)\fP + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + It is not guaranteed that immediately after setting the write time, the value + returned by \fB(1)\fP is the same as what was passed as the argument to \fB(2)\fP because the + file system's time may be more granular than file_time_type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + using namespace std::chrono_literals; + + int main() + { + fs::path p = fs::current_path() / "example.bin"; + std::ofstream(p.c_str()).put('a'); // create file + auto ftime = fs::last_write_time(p); + + std::time_t cftime = decltype(ftime)::clock::to_time_t(ftime); // assuming system_clock + std::cout << "File write time is " << std::asctime(std::localtime(&cftime)) << '\\n'; + + fs::last_write_time(p, ftime + 1h); // move file write time 1 hour to the future + ftime = fs::last_write_time(p); // read back from the filesystem + + cftime = decltype(ftime)::clock::to_time_t(ftime); + std::cout << "File write time is " << std::asctime(std::localtime(&cftime)) << '\\n'; + fs::remove(p); + } + +.SH Possible output: + + File write time is Tue Mar 31 19:47:04 2015 + + File write time is Tue Mar 31 20:47:04 2015 + +.SH See also + + file_time_type represents file time values + \fI(typedef)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path.3 b/man/std::experimental::filesystem::path.3 index 7d1be4f83..b06a17821 100644 --- a/man/std::experimental::filesystem::path.3 +++ b/man/std::experimental::filesystem::path.3 @@ -1,135 +1,169 @@ -.TH std::experimental::filesystem::path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path \- std::experimental::filesystem::path + .SH Synopsis Defined in header class path; (filesystem TS) - Objects of type path represent a path. Only syntactic aspects of paths are handled: - the pathname may represent a non-existing path or even one that is not allowed on - the current operating or file system. + Objects of type path represent paths on a filesystem. Only syntactic aspects of + paths are handled: the pathname may represent a non-existing path or even one that + is not allowed to exist on the current file system or OS. + + The path name has the following syntax: + + 1. root-name(optional): identifies the root on a filesystem with multiple roots + (such as "C:" or "//myserver". POSIX filesystems have single root. + 2. root-directory(optional): a directory separator that, if present, marks this + path as absolute. If it is missing (and the first element other than the root + name is a file name), then the path is relative and requires another path as the + starting location to resolve to a file name. + 3. Zero or more of the following: + + * file-name: sequence of characters that aren't directory separators or preferred + directory separators (additional limitations may be imposed by the OS or file + system). This name may identify a file, a hard link, a symbolic link, or a + directory. Two special file-names are recognized: + + * dot: the file name consisting of a single dot character . is a directory name + that refers to the current directory. + * dot-dot: the file name consisting of two dot characters .. is a directory name + that refers to the parent directory. + * directory-separators: the forward slash character / or the alternative character + provided as path::preferred_separator. If this character is repeated, it is + treated as a single directory separator: /usr///////lib is the same as /usr/lib. The path can be traversed element-wise via iterators returned by the begin() and - end() functions. + end() functions, which iterates over root name, root directory, and the subsequent + file name elements (directory separators are skipped except the one that identifies + the root directory). If the very last element in the path is a directory separator, + the last iterator will dereference to a file name dot. Calling any non-const member function of a path invalidates all iterators referring to elements of that object. - The forward traversal is done in the following order: + If the OS uses a native syntax that is different from the portable generic syntax + described above, all library functions accept path names in both formats. - * The root name element, if any - * The root directory element, if any. The element is presented in generic format, - thus lexicographical comparisons work correctly. - * Each successive filename element. - * . if one or mare trailing non-root / characters are present. + Paths are implicitly convertible to and from std::basic_strings, which makes it + possible to use them with other file APIs, e.g. as an argument to + std::ifstream::open. .SH Member types Type Definition - value_type todo + value_type character type used by the native encoding of the filesystem: char on + POSIX, wchar_t on Windows string_type std::basic_string - iterator a constant BidirectionalIterator with a value_type of path - const_iterator todo + const_iterator a constant LegacyBidirectionalIterator with a value_type of path + iterator an alias to const_iterator .SH Member constants - constexpr value_type preferred_separator todo - \fB[static]\fP \fI(public static member constant)\fP + alternative directory separator which may be used in addition + constexpr value_type to the portable /. On Windows, this is the backslash character + preferred_separator \\. On POSIX, this is the same forward slash / as the portable + \fB[static]\fP separator + \fI(public static member constant)\fP .SH Member functions constructor constructs a path - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a path object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns another path - \fI(public member function)\fP + \fI(public member function)\fP assign assigns contents - \fI(public member function)\fP + \fI(public member function)\fP Concatenation append appends elements to the path - operator/= \fI(public member function)\fP - concat concatenates two paths - operator+= \fI(public member function)\fP + operator/= \fI(public member function)\fP + concat concatenates two paths without introducing a directory + operator+= separator + \fI(public member function)\fP .SH Modifiers clear erases the contents - \fI(public member function)\fP + \fI(public member function)\fP make_preferred converts directory separators to preferred directory separator - \fI(public member function)\fP + \fI(public member function)\fP remove_filename removes filename path component - \fI(public member function)\fP + \fI(public member function)\fP replace_filename replaces the last path component with another path - \fI(public member function)\fP + \fI(public member function)\fP replace_extension replaces the extension - \fI(public member function)\fP + \fI(public member function)\fP swap swaps two paths - \fI(public member function)\fP + \fI(public member function)\fP Format observers - native returns the native version of the path - operator string_type \fI(public member function)\fP c_str returns the native version of the path - \fI(public member function)\fP + native \fI(public member function)\fP + operator string_type string wstring returns the path in native pathname format converted to a u8string string - u16string \fI(public member function)\fP + u16string \fI(public member function)\fP u32string generic_string generic_wstring returns the path in generic pathname format converted to a generic_u8string string - generic_u16string \fI(public member function)\fP + generic_u16string \fI(public member function)\fP generic_u32string Compare compares the lexical representations of two paths compare lexicographically - \fI(public member function)\fP + \fI(public member function)\fP Decomposition root_name returns the root-name of the path, if present - \fI(public member function)\fP + \fI(public member function)\fP root_directory returns the root directory of the path, if present - \fI(public member function)\fP + \fI(public member function)\fP root_path returns the root path of the path, if present - \fI(public member function)\fP + \fI(public member function)\fP relative_path returns path relative to the root path - \fI(public member function)\fP + \fI(public member function)\fP parent_path returns the path of the parent path - \fI(public member function)\fP + \fI(public member function)\fP filename returns the filename path component - \fI(public member function)\fP + \fI(public member function)\fP stem returns the stem path component - \fI(public member function)\fP + \fI(public member function)\fP extension returns the file extension path component - \fI(public member function)\fP + \fI(public member function)\fP Queries empty checks if the path is empty - \fI(public member function)\fP + \fI(public member function)\fP has_root_path has_root_name has_root_directory has_relative_path checks if the corresponding path element is not empty - has_parent_path \fI(public member function)\fP + has_parent_path \fI(public member function)\fP has_filename has_stem has_extension is_absolute checks if root_path() uniquely identifies file system location - is_relative \fI(public member function)\fP + is_relative \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning of element list - \fI(public member function)\fP - end returns an iterator to the end of element list - \fI(public member function)\fP + begin iterator access to the path as a sequence of elements + end \fI(public member function)\fP .SH Non-member functions - swap(std::fs::path) swaps two paths - \fI(function)\fP + swap(std::experimental::filesystem::path) swaps two paths + \fI(function)\fP operator== operator!= - operator< lexicographically compares two paths - operator<= \fI(function)\fP + operator< lexicographically compares two paths + operator<= \fI(function)\fP operator> operator>= - operator/ concatenates two paths - \fI(function)\fP - operator<< performs stream input and output on a path - operator>> \fI(function)\fP - u8path creates a path from a UTF-8 encoded source - \fI(function)\fP + concatenates two paths with a directory + operator/ separator + \fI(function)\fP + operator<< performs stream input and output on a path + operator>> \fI(function)\fP + u8path creates a path from a UTF-8 encoded source + \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::append,.3 b/man/std::experimental::filesystem::path::append,.3 new file mode 100644 index 000000000..dfab7a604 --- /dev/null +++ b/man/std::experimental::filesystem::path::append,.3 @@ -0,0 +1,85 @@ +.TH std::experimental::filesystem::path::append, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::append, \- std::experimental::filesystem::path::append, + +.SH Synopsis + + path& operator/=( const path& p ); \fB(1)\fP (filesystem TS) + template< class Source > \fB(2)\fP (filesystem TS) + path& operator/=( const Source& source ); + template< class Source > \fB(3)\fP (filesystem TS) + path& append( const Source& source ); + template< class InputIt > \fB(4)\fP (filesystem TS) + path& append( InputIt first, InputIt last ); + + 1) First, appends the preferred directory separator to this, except if any of the + following conditions is true: + * the separator would be redundant (*this already ends with a separator). + * *this is empty, or adding it would turn a relative path to an absolute path in + some other way. + * p is an empty path. + * p.native() begins with a directory separator. + Then, appends p.native() to the pathname maintained by *this. + 2,3) Same as \fB(1)\fP, but accepts any std::basic_string, null-terminated multicharacter + string, or an input iterator pointing to a null-terminated multicharacter sequence. + 4) Same as \fB(1)\fP, but accepts any iterator pair that designates a multicharacter + string. + +.SH Parameters + + p - pathname to append + std::basic_string, null-terminated multicharacter string, or an input + source - iterator pointing to a null-terminated multicharacter sequence, which + represents a path name (either in portable or in native format) + first, last - pair of LegacyInputIterators that specify a multicharacter sequence + that represents a path name +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of InputIt must be one of the encoded character types (char, wchar_t, + char16_t and char32_t). + +.SH Return value + + *this + +.SH Exceptions + + May throw filesystem_error on underlying OS API errors or std::bad_alloc if memory + allocation fails. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p1 = "C:"; + p1 /= "Users"; // does not insert a separator + // "C:Users" is a relative path in Windows + // adding directory separator would turn it to an absolute path + std::cout << "\\"C:\\" / \\"Users\\" == " << p1 << '\\n'; + p1 /= "batman"; // inserts fs::path::preferred_separator, '\\' on Windows + std::cout << "\\"C:\\" / \\"Users\\" / \\"batman\\" == " << p1 << '\\n'; + } + +.SH Possible output: + + "C:" / "Users" == "C:Users" + "C:" / "Users" / "batman" == "C:Users\\batman" + +.SH See also + + concat concatenates two paths without introducing a directory separator + operator+= \fI(public member function)\fP + operator/ concatenates two paths with a directory separator + \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::assign.3 b/man/std::experimental::filesystem::path::assign.3 index 576e2c281..e769a6325 100644 --- a/man/std::experimental::filesystem::path::assign.3 +++ b/man/std::experimental::filesystem::path::assign.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::assign \- std::experimental::filesystem::path::assign + .SH Synopsis template< class Source > \fB(1)\fP (filesystem TS) path& assign( const Source& source ); @@ -19,12 +22,10 @@ first, last - a range to assign .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - The value type of InputIt must be one of the encoded character types (char, wchar_t, - char16_t and char32_t) - - |} + char16_t and char32_t). .SH Return value @@ -37,8 +38,8 @@ .SH See also operator= assigns another path - \fI(public member function)\fP - -.SH Category: + \fI(public member function)\fP +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::path::begin,std::experimental::filesystem::path::end.3 b/man/std::experimental::filesystem::path::begin,std::experimental::filesystem::path::end.3 new file mode 100644 index 000000000..9c7f4ca5e --- /dev/null +++ b/man/std::experimental::filesystem::path::begin,std::experimental::filesystem::path::end.3 @@ -0,0 +1,65 @@ +.TH std::experimental::filesystem::path::begin,std::experimental::filesystem::path::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::begin,std::experimental::filesystem::path::end \- std::experimental::filesystem::path::begin,std::experimental::filesystem::path::end + +.SH Synopsis + iterator begin() const; \fB(1)\fP (filesystem TS) + iterator end() const; \fB(2)\fP (filesystem TS) + + 1) Returns an iterator to the first element of the path. If the path is empty, the + returned iterator is equal to end(). + 2) Returns an iterator one past the last element of the path. Dereferencing this + iterator is undefined behavior. + + The sequence denoted by this pair of iterators consists of the following: + + 1) root-name (if any). + 2) root-directory (if any). + 3) Sequence of file-names, omitting any directory separators. + 4) If there is a directory separator after the last file-name in the path, the last + element before the end iterator is a fictitious dot file name. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Iterator to the first element of the path. + 2) Iterator one past the end of the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = "C:\\\\users\\\\abcdef\\\\AppData\\\\Local\\\\Temp\\\\"; + std::cout << "Examining the path " << p << " through iterators gives\\n"; + for (auto& e : p) + std::cout << e << '\\n'; + } + +.SH Output: + + Examining the path "C:\\users\\abcdef\\AppData\\Local\\Temp\\" through iterators gives + "C:" + "/" + "users" + "abcdef" + "AppData" + "Local" + "Temp" + "." + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::begin.3 b/man/std::experimental::filesystem::path::begin.3 deleted file mode 100644 index c5fe9e4ec..000000000 --- a/man/std::experimental::filesystem::path::begin.3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::experimental::filesystem::path::begin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin() const; (filesystem TS) - - Returns an iterator to the first element of the path. - - If the path is empty, the returned iterator is equal to end(). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element of the path. - -.SH Exceptions - - \fI(none)\fP - -.SH See also - - end returns an iterator to the end of element list - \fI(public member function)\fP diff --git a/man/std::experimental::filesystem::path::c_str,std::experimental::filesystem::path::native,.3 b/man/std::experimental::filesystem::path::c_str,std::experimental::filesystem::path::native,.3 new file mode 100644 index 000000000..86b8eb133 --- /dev/null +++ b/man/std::experimental::filesystem::path::c_str,std::experimental::filesystem::path::native,.3 @@ -0,0 +1,107 @@ +.TH std::experimental::filesystem::path::c_str,std::experimental::filesystem::path::native, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::c_str,std::experimental::filesystem::path::native, \- std::experimental::filesystem::path::c_str,std::experimental::filesystem::path::native, + +.SH Synopsis + + const value_type* c_str() const; \fB(1)\fP (filesystem TS) + const string_type& native() const; \fB(2)\fP (filesystem TS) + operator string_type() const; \fB(3)\fP (filesystem TS) + + Accesses the native path name as a character string. + + 1) Equivalent to native().c_str(). + 2) Returns the native string representation of the pathname by reference. + 3) Returns the native string representation of the pathname by value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The native string representation of the pathname, using native syntax, native + character type, and native character encoding. This string is suitable for use with + OS APIs. + +.SH Exceptions + + 1,2) + noexcept specification: + noexcept + + +.SH Notes + + The conversion function \fB(3)\fP is provided so that standard file-opening APIs that + accept std::basic_string file names, such as the std::ifstream constructor, can use + pathnames with no changes to code: + + fs::path p = "/tmp/text.txt"; + std::ifstream f(p); + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::locale::global(std::locale("en_US.utf8")); + + fs::path p = fs::u8path(u8"要らない.txt"); + + // native string representation can be used with OS APIs + std::ofstream(p) << "File contents"; // this uses operator string() + if (std::FILE* f = std::fopen(p.c_str(), "r")) + { + int ch; + while ((ch=fgetc(f))!= EOF) putchar(ch); + std::fclose(f); + } + + // multibyte and wide representation can be used for output + std::cout.imbue(std::locale()); + std::cout << "\\nFile name in narrow multibyte encoding: " + << p.string() << '\\n'; + + std::wcerr.imbue(std::locale()); + std::wcerr << "File name in wide encoding: " + << p.wstring() << '\\n'; + + fs::remove(p); + } + +.SH Possible output: + + File contents + File name in narrow multibyte encoding: 要らない.txt + File name in wide encoding: 要らない.txt + +.SH See also + + string + wstring returns the path in native pathname format converted to a string + u8string \fI(public member function)\fP + u16string + u32string + generic_string + generic_wstring returns the path in generic pathname format converted to a string + generic_u8string \fI(public member function)\fP + generic_u16string + generic_u32string + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path::c_str.3 b/man/std::experimental::filesystem::path::c_str.3 deleted file mode 100644 index aa353b230..000000000 --- a/man/std::experimental::filesystem::path::c_str.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::experimental::filesystem::path::c_str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - const value_type* c_str() const; (filesystem TS) - - Returts C-string version of the path. - - Equivalent to native().c_str(). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - C-string version of the path name. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - native returns the native version of the path - operator string_type \fI(public member function)\fP diff --git a/man/std::experimental::filesystem::path::clear.3 b/man/std::experimental::filesystem::path::clear.3 index 91def9c88..6eb263fc7 100644 --- a/man/std::experimental::filesystem::path::clear.3 +++ b/man/std::experimental::filesystem::path::clear.3 @@ -1,8 +1,11 @@ -.TH std::experimental::filesystem::path::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::clear \- std::experimental::filesystem::path::clear + .SH Synopsis void clear(); (filesystem TS) - Clears the stored pathname. clear() is true after the call. + Clears the stored pathname. empty() is true after the call. .SH Parameters @@ -14,6 +17,12 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path::compare.3 b/man/std::experimental::filesystem::path::compare.3 index 79318236c..ad655a54c 100644 --- a/man/std::experimental::filesystem::path::compare.3 +++ b/man/std::experimental::filesystem::path::compare.3 @@ -1,23 +1,25 @@ -.TH std::experimental::filesystem::path::compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::compare \- std::experimental::filesystem::path::compare + .SH Synopsis - int compare( const path& p ) const; \fB(1)\fP (filesystem TS) - int compare( const std::string& str ) const; \fB(2)\fP (filesystem TS) - int compare( const value_type& s ) const; \fB(3)\fP (filesystem TS) + int compare( const path& p ) const noexcept; \fB(1)\fP (filesystem TS) + int compare( const string_type& str ) const; \fB(2)\fP (filesystem TS) + int compare( const value_type* s ) const; \fB(3)\fP (filesystem TS) Compares the lexical representations of the path and another path. 1) Returns a value less than, equal to or greater than 0 if the native representation of the path (native()) is respectively lexicographically less than, - equal to or greater than the native representation of p (p.native()). + equal to or greater than the native representation of p (p.native()). Comparison is + performed element-wise, as if by iterating both paths from begin() to end(). 2) Equivalent to compare(path(str)). 3) Equivalent to compare(path(s)). .SH Parameters p - a path to compare to - a string representing path to compare to - str - - } + str - a string representing path to compare to s - a null-terminated string representing path to compare to .SH Return value @@ -30,17 +32,52 @@ .SH Exceptions - 1) - noexcept specification: - noexcept - - 2-3) \fI(none)\fP + 2,3) May throw implementation-defined exceptions. + +.SH Notes + + For two-way comparisons, binary operators may be more suitable. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + void demo(int rc, fs::path p1, fs::path p2) + { + if (rc < 0) + std::cout << p1 << " < " << p2 << '\\n'; + else if (rc > 0) + std::cout << p1 << " > " << p2 << '\\n'; + else if (rc == 0) + std::cout << p1 << " = " << p2 << '\\n'; + } + + int main() + { + fs::path p1 = "/a/b/"; // as if "a/b/." for lexicographical iteration + fs::path p2 = "/a/b/#"; + demo(p1.compare(p2), p1, p2); + demo(p1.compare("a/b/_"), p1, "a/b/_"); + } + +.SH Output: + + "/a/b/" > "/a/b/#" + "/a/b/" < "a/b/_" .SH See also operator== operator!= operator< lexicographically compares two paths - operator<= \fI(function)\fP + operator<= \fI(function)\fP operator> operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::concat,.3 b/man/std::experimental::filesystem::path::concat,.3 new file mode 100644 index 000000000..257c2e54b --- /dev/null +++ b/man/std::experimental::filesystem::path::concat,.3 @@ -0,0 +1,105 @@ +.TH std::experimental::filesystem::path::concat, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::concat, \- std::experimental::filesystem::path::concat, + +.SH Synopsis + + path& operator+=( const path& p ); \fB(1)\fP (filesystem TS) + path& operator+=( const string_type& str ); \fB(2)\fP (filesystem TS) + path& operator+=( const value_type* ptr ); \fB(3)\fP (filesystem TS) + path& operator+=( value_type x ); \fB(4)\fP (filesystem TS) + template< class Source > \fB(5)\fP (filesystem TS) + path& operator+=( const Source& source ); + template< class CharT > \fB(6)\fP (filesystem TS) + path& operator+=( CharT x ); + template< class Source > \fB(7)\fP (filesystem TS) + path& concat( const Source& source ); + template< class InputIt > \fB(8)\fP (filesystem TS) + path& concat( InputIterator first, InputIterator last ); + + Concatenates the current path and the argument. + + 1) Concatenates *this and p in such a way that native() of the result is exactly + original native() concatenated with p.native(). + 2) Same as \fB(1)\fP, except the resulting native() is a concatenation of the original + native() and the string str. + 3) Same as \fB(1)\fP, except the resulting native() is a concatenation of the original + native() and the null-terminated string whose first character is pointed to by ptr. + 4) Same as \fB(1)\fP, except the resulting native() is a concatenation of the original + native() and the single character x. + 5) Same as \fB(1)\fP, except the resulting native() is a concatenation of the original + native() and the sequence (which may be in portable or native format) represented by + source, which may be std::basic_string, null-terminated multicharacter string, or an + input iterator pointing to a null-terminated multicharacter sequence. + 6) Same as \fB(4)\fP, except that character conversion may be performed. + 7) Same as \fB(5)\fP. + 8) Same as \fB(5)\fP, except that the sequence is represented by any iterator pair that + designates a multicharacter string. + +.SH Parameters + + p - path to append + str - string to append + ptr - pointer to the beginning of a null-terminated string to append + x - single character to append + std::basic_string, null-terminated multicharacter string, or an input + source - iterator pointing to a null-terminated multicharacter sequence, which + represents a path name (either in portable or in native format) + first, last - pair of LegacyInputIterators that specify a multicharacter sequence + that represents a path name +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of InputIt must be one of the encoded character types (char, wchar_t, + char16_t and char32_t). + - + CharT must be one of the encoded character types (char, wchar_t, char16_t and + char32_t). + +.SH Return value + + *this + +.SH Exceptions + + May throw filesystem_error on underlying OS API errors or std::bad_alloc if memory + allocation fails. + +.SH Notes + + Unlike with append() or operator/=, additional directory separators are never + introduced. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p1; // empty path + p1 += "var"; // does not insert a separator + std::cout << "\\"\\" + \\"var\\" == " << p1 << '\\n'; + p1 += "lib"; // does not insert a separator + std::cout << "\\"\\" + \\"var\\" + \\"lib\\" == " << p1 << '\\n'; + } + +.SH Output: + + "" + "var" == "var" + "" + "var" + "lib" == "varlib" + +.SH See also + + append appends elements to the path + operator/= \fI(public member function)\fP + operator/ concatenates two paths with a directory separator + \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::concat,operator+=.3 b/man/std::experimental::filesystem::path::concat,operator+=.3 deleted file mode 100644 index b0621deb7..000000000 --- a/man/std::experimental::filesystem::path::concat,operator+=.3 +++ /dev/null @@ -1,55 +0,0 @@ -.TH std::experimental::filesystem::path::concat,operator+= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - path& operator+=( const path& p ); \fB(1)\fP (filesystem TS) - path& operator+=( const string_type& x ); \fB(2)\fP (filesystem TS) - path& operator+=( const value_type* x ); \fB(3)\fP (filesystem TS) - path& operator+=( value_type x ); \fB(4)\fP (filesystem TS) - template< class Source > \fB(5)\fP (filesystem TS) - path& operator+=( const Source& source ); - template< class CharT > \fB(6)\fP (filesystem TS) - path& operator+=( CharT x ); - template< class Source > \fB(7)\fP (filesystem TS) - path& concat( const Source& source ); - template< class InputIt > \fB(8)\fP (filesystem TS) - path& concat( InputIterator first, InputIterator last ); - - Concatenates the current path and the argument. Differently from append() or - operator/=, separator is not appended. - - 1) Concatenates the current path and p.native() - 2-4) Concatenates the current path and x - 5,7) Concatenates the current path and the effective argument. The argument is - firstly converted to path::value_type if such conversion is necessary. - 6) Concatenates the current path and x. - 8) Concatenates the current path and the range [first, last). - -.SH Parameters - - p - path to append - source - effective argument to append - first, last - the range to append -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. - - - The value type of InputIt must be one of the encoded character types (char, wchar_t, - char16_t and char32_t) - - - CharT must be one of the encoded character types (char, wchar_t, char16_t and - char32_t) - -.SH Return value - - *this - -.SH Exceptions - - This section is incomplete - -.SH See also - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::path::empty.3 b/man/std::experimental::filesystem::path::empty.3 index a116ff05d..50639a3c6 100644 --- a/man/std::experimental::filesystem::path::empty.3 +++ b/man/std::experimental::filesystem::path::empty.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::empty \- std::experimental::filesystem::path::empty + .SH Synopsis bool empty() const; (filesystem TS) @@ -14,9 +17,9 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + .SH See also @@ -24,7 +27,14 @@ has_root_name has_root_directory has_relative_path checks if the corresponding path element is not empty - has_parent_path \fI(public member function)\fP + has_parent_path \fI(public member function)\fP has_filename has_stem has_extension + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path::end.3 b/man/std::experimental::filesystem::path::end.3 deleted file mode 100644 index b764d7efc..000000000 --- a/man/std::experimental::filesystem::path::end.3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::experimental::filesystem::path::end 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end() const; (filesystem TS) - - Returns an iterator to the past-the-last element of the path. - - The iterator acts as a placeholder. Accessing it yields undefined behavior. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the past-the-last element of the path. - -.SH Exceptions - - \fI(none)\fP - -.SH See also - - begin returns an iterator to the beginning of element list - \fI(public member function)\fP diff --git a/man/std::experimental::filesystem::path::extension.3 b/man/std::experimental::filesystem::path::extension.3 index 4476d5511..8846e8f2c 100644 --- a/man/std::experimental::filesystem::path::extension.3 +++ b/man/std::experimental::filesystem::path::extension.3 @@ -1,15 +1,19 @@ -.TH std::experimental::filesystem::path::extension 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::extension 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::extension \- std::experimental::filesystem::path::extension + .SH Synopsis path extension() const; (filesystem TS) - Returns the extension of the filename() identified by the path. + Returns the extension of the filename component of the path *this. - The extension is the substring between the last . character and the end of the - filename. The return value of the function returns the . character if an extension - is present. + If the filename() component of the path contains a period (.), and is not one of the + special filesystem elements dot or dot-dot, then the extension is the substring + beginning at the rightmost period (including the period) and until the end of the + pathname. - If the pathname is either . or .., or the pathname does not contain the . character, - then empty path is returned. + If the pathname is either . or .., or if filename() does not contain the . + character, then empty path is returned. Additional behavior may be defined by the implementations for file systems which append additional elements (such as alternate data streams or partitioned dataset @@ -25,44 +29,60 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Notes + + The extension as returned by this function includes a period to make it possible to + distinguish the file that ends with a period \fI(function returns ".") from a file with\fP + no extension \fI(function returns "").\fP + + For any path p, p.stem()+p.extension() == p.filename(). .SH Example - + // Run this code - #include + #include #include - + namespace fs = std::experimental::filesystem; + int main() { - std::cout << std::fs::path("/foo/bar.txt").extension() << '\\n'; - std::cout << std::fs::path("/foo/bar.").extension() << '\\n'; - std::cout << std::fs::path("/foo/bar").extension() << '\\n'; - std::cout << std::fs::path("/foo/bar.txt/bar.cc").extension() << '\\n'; - std::cout << std::fs::path("/foo/bar.txt/bar.").extension() << '\\n'; - std::cout << std::fs::path("/foo/bar.txt/bar").extension() << '\\n'; - std::cout << std::fs::path("/foo/.").extension() << '\\n'; - std::cout << std::fs::path("/foo/..").extension() << '\\n'; - std::cout << std::fs::path("/foo/.hidden").extension() << '\\n'; + std::cout << fs::path("/foo/bar.txt").extension() << '\\n' + << fs::path("/foo/bar.").extension() << '\\n' + << fs::path("/foo/bar").extension() << '\\n' + << fs::path("/foo/bar.txt/bar.cc").extension() << '\\n' + << fs::path("/foo/bar.txt/bar.").extension() << '\\n' + << fs::path("/foo/bar.txt/bar").extension() << '\\n' + << fs::path("/foo/.").extension() << '\\n' + << fs::path("/foo/..").extension() << '\\n' + << fs::path("/foo/.hidden").extension() << '\\n'; } .SH Output: - .txt - . - - .cc - . - - - - .hidden + ".txt" + "." + "" + ".cc" + "." + "" + "" + "" + ".hidden" .SH See also - filename returns the filename path component - \fI(public member function)\fP - stem returns the stem path component - \fI(public member function)\fP + filename returns the filename path component + \fI(public member function)\fP + stem returns the stem path component + \fI(public member function)\fP + replace_extension replaces the extension + \fI(public member function)\fP + has_extension checks if the corresponding path element is not empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::filename.3 b/man/std::experimental::filesystem::path::filename.3 index 5ae53eb31..27846d43c 100644 --- a/man/std::experimental::filesystem::path::filename.3 +++ b/man/std::experimental::filesystem::path::filename.3 @@ -1,8 +1,11 @@ -.TH std::experimental::filesystem::path::filename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::filename \- std::experimental::filesystem::path::filename + .SH Synopsis path filename() const; (filesystem TS) - Returns the filename identified by the path. + Returns the filename component of the path. Equivalent to empty() ? path() : *--end(). @@ -16,44 +19,50 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code - #include + #include #include - + namespace fs = std::experimental::filesystem; + int main() { - std::cout << std::fs::path("/foo/bar.txt").extension() << '\\n'; - std::cout << std::fs::path("/foo/.bar").extension() << '\\n'; - std::cout << std::fs::path("/foo/bar/").extension() << '\\n'; - std::cout << std::fs::path("/foo/.").extension() << '\\n'; - std::cout << std::fs::path("/foo/..").extension() << '\\n'; - std::cout << std::fs::path(".").extension() << '\\n'; - std::cout << std::fs::path("..").extension() << '\\n'; - std::cout << std::fs::path("/").extension() << '\\n'; + std::cout << fs::path("/foo/bar.txt").filename() << '\\n' + << fs::path("/foo/.bar").filename() << '\\n' + << fs::path("/foo/bar/").filename() << '\\n' + << fs::path("/foo/.").filename() << '\\n' + << fs::path("/foo/..").filename() << '\\n' + << fs::path(".").filename() << '\\n' + << fs::path("..").filename() << '\\n' + << fs::path("/").filename() << '\\n'; } .SH Output: - bar.txt - .bar - / - - .cc - . - .. - . - .. - / + "bar.txt" + ".bar" + "." + "." + ".." + "." + ".." + "/" .SH See also - extension returns the file extension path component - \fI(public member function)\fP - stem returns the stem path component - \fI(public member function)\fP + extension returns the file extension path component + \fI(public member function)\fP + stem returns the stem path component + \fI(public member function)\fP + replace_filename replaces the last path component with another path + \fI(public member function)\fP + has_filename checks if the corresponding path element is not empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,....3 b/man/std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,....3 index 352c20c69..65fbc3cf1 100644 --- a/man/std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,....3 +++ b/man/std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,....3 @@ -1,14 +1,17 @@ -.TH std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,... 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,... 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,... \- std::experimental::filesystem::path::generic_string,generic_wstring,generic_u8string,... + .SH Synopsis - template< class CharT, class Traits = std::char_traits + template< class CharT, class Traits = std::char_traits, - class Alloc = std::allocator > \fB(1)\fP (filesystem TS) + class Alloc = std::allocator > \fB(1)\fP (filesystem TS) std::basic_string - generic_string( const Allocator& a = Allocator() ) const; + generic_string( const Alloc& a = Alloc() ) const; std::string generic_string() const; std::wstring generic_wstring() const; - std::u8string generic_u8string() const; \fB(2)\fP (filesystem TS) + std::string generic_u8string() const; \fB(2)\fP (filesystem TS) std::u16string generic_u16string() const; std::u32string generic_u32string() const; @@ -33,12 +36,16 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH See also string wstring returns the path in native pathname format converted to a string - u8string \fI(public member function)\fP + u8string \fI(public member function)\fP u16string u32string + +.SH Categories: + * Noindexed pages + * Uses of dcl rev begin with nonempty note diff --git a/man/std::experimental::filesystem::path::has_....3 b/man/std::experimental::filesystem::path::has_....3 new file mode 100644 index 000000000..c0c23ff74 --- /dev/null +++ b/man/std::experimental::filesystem::path::has_....3 @@ -0,0 +1,44 @@ +.TH std::experimental::filesystem::path::has_... 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::has_... \- std::experimental::filesystem::path::has_... + +.SH Synopsis + bool has_root_path() const; \fB(1)\fP (filesystem TS) + bool has_root_name() const; \fB(2)\fP (filesystem TS) + bool has_root_directory() const; \fB(3)\fP (filesystem TS) + bool has_relative_path() const; \fB(4)\fP (filesystem TS) + bool has_parent_path() const; \fB(5)\fP (filesystem TS) + bool has_filename() const; \fB(6)\fP (filesystem TS) + bool has_stem() const; \fB(7)\fP (filesystem TS) + bool has_extension() const; \fB(8)\fP (filesystem TS) + + Checks whether the path contains the corresponding path element. + + 1) Checks whether root_path() is empty. + 2) Checks whether root_name() is empty. + 3) Checks whether root_directory() is empty. + 4) Checks whether relative_path() is empty. + 5) Checks whether parent_path() is empty. + 6) Checks whether filename() is empty. + 7) Checks whether stem() is empty. + 8) Checks whether extension() is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the corresponding path is not empty, false otherwise. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH See also + + empty checks if the path is empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::has_..._path.3 b/man/std::experimental::filesystem::path::has_..._path.3 deleted file mode 100644 index 83c97fd7f..000000000 --- a/man/std::experimental::filesystem::path::has_..._path.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::experimental::filesystem::path::has_..._path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bool has_root_path() const; \fB(1)\fP (filesystem TS) - bool has_root_name() const; \fB(2)\fP (filesystem TS) - bool has_root_directory() const; \fB(3)\fP (filesystem TS) - bool has_relative_path() const; \fB(4)\fP (filesystem TS) - bool has_parent_path() const; \fB(5)\fP (filesystem TS) - bool has_filename() const; \fB(6)\fP (filesystem TS) - bool has_stem() const; \fB(7)\fP (filesystem TS) - bool has_extension() const; \fB(8)\fP (filesystem TS) - - Checks whether the path contains the corresponding path element. - - 1) Checks whether root_path() is empty. - 2) Checks whether root_name() is empty. - 3) Checks whether root_directory() is empty. - 4) Checks whether relative_path() is empty. - 5) Checks whether parent_path() is empty. - 6) Checks whether filename() is empty. - 7) Checks whether stem() is empty. - 8) Checks whether extension() is empty. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - true if the corresponding path is not empty, false otherwise. - -.SH Exceptions - - \fI(none)\fP - -.SH See also - - empty checks if the path is empty - \fI(public member function)\fP diff --git a/man/std::experimental::filesystem::path::is_absolute,is_relative.3 b/man/std::experimental::filesystem::path::is_absolute,is_relative.3 index 5b6014a7c..562447b5f 100644 --- a/man/std::experimental::filesystem::path::is_absolute,is_relative.3 +++ b/man/std::experimental::filesystem::path::is_absolute,is_relative.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::is_absolute,is_relative 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::is_absolute,is_relative 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::is_absolute,is_relative \- std::experimental::filesystem::path::is_absolute,is_relative + .SH Synopsis bool is_absolute() const; \fB(1)\fP (filesystem TS) bool is_relative() const; \fB(2)\fP (filesystem TS) @@ -19,12 +22,18 @@ .SH Exceptions - This section is incomplete + May throw implementation-defined exceptions. .SH See also - This section is incomplete + has_root_path + has_root_name + has_root_directory + has_relative_path checks if the corresponding path element is not empty + has_parent_path \fI(public member function)\fP + has_filename + has_stem + has_extension .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::make_preferred.3 b/man/std::experimental::filesystem::path::make_preferred.3 index 1ac8a6f9e..413109e2c 100644 --- a/man/std::experimental::filesystem::path::make_preferred.3 +++ b/man/std::experimental::filesystem::path::make_preferred.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::make_preferred 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::make_preferred 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::make_preferred \- std::experimental::filesystem::path::make_preferred + .SH Synopsis path& make_preferred() \fB(1)\fP (filesystem TS) @@ -17,12 +20,12 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH See also This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::path::native,operatorstring_type().3 b/man/std::experimental::filesystem::path::native,operatorstring_type().3 deleted file mode 100644 index fd4f7267f..000000000 --- a/man/std::experimental::filesystem::path::native,operatorstring_type().3 +++ /dev/null @@ -1,25 +0,0 @@ -.TH std::experimental::filesystem::path::native,operatorstring_type() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - const string_type& native() const; \fB(1)\fP (filesystem TS) - operator string_type() const; \fB(2)\fP (filesystem TS) - - Returns the path name converted to the native path encoding. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - *this - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - c_str returns the native version of the path - \fI(public member function)\fP diff --git a/man/std::experimental::filesystem::path::operator=.3 b/man/std::experimental::filesystem::path::operator=.3 index 08629e257..9c7eb8ab9 100644 --- a/man/std::experimental::filesystem::path::operator=.3 +++ b/man/std::experimental::filesystem::path::operator=.3 @@ -1,22 +1,26 @@ -.TH std::experimental::filesystem::path::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::operator= \- std::experimental::filesystem::path::operator= + .SH Synopsis path& operator=( const path& p ); \fB(1)\fP (filesystem TS) path& operator=( path&& p ); \fB(2)\fP (filesystem TS) - template< class Source > \fB(2)\fP (filesystem TS) + template< class Source > \fB(3)\fP (filesystem TS) path& operator=( const Source& source ); - Assigns the contents of another path object. - - 1) Assigns the pathname of p. - 2) Assigns the pathname of p. p is in valid, but unspecified state after the call. - 3) Assigns the range of the source. - - This section is incomplete + 1) Replaces the contents of *this with a copy of the contents of p. + 2) Replaces the contents of *this with p, possibly using move semantics: p is left + in valid, but unspecified state. + 3) Replaces the contents of *this with a new path value constructed from source as + if by overload \fB(4)\fP of the path constructor. Equivalent to assign(source). .SH Parameters p - a path to assign - source - a range to assign + a std::basic_string, pointer to a null-terminated character/wide character + source - string, or an input iterator that points to a null-terminated + character/wide character sequence. The character type must be one of char, + char16_t, char32_t, wchar_t .SH Return value @@ -26,16 +30,37 @@ 1) \fI(none)\fP 2) - noexcept specification: + noexcept specification: noexcept - + 3) \fI(none)\fP -.SH See also +.SH Example - assign assigns contents - \fI(public member function)\fP -.SH Category: +// Run this code + + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = "C:/users/abcdef/AppData/Local"; + p = p / "Temp"; // move assignment + const wchar_t* wstr = L"D:/猫.txt"; + p = wstr; // assignment from a source + } + +.SH See also + + assign assigns contents + \fI(public member function)\fP + constructor constructs a path + \fI(public member function)\fP - * Todo without reason +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path::parent_path.3 b/man/std::experimental::filesystem::path::parent_path.3 index b6b05b75c..13ae3729e 100644 --- a/man/std::experimental::filesystem::path::parent_path.3 +++ b/man/std::experimental::filesystem::path::parent_path.3 @@ -1,12 +1,15 @@ -.TH std::experimental::filesystem::path::parent_path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::parent_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::parent_path \- std::experimental::filesystem::path::parent_path + .SH Synopsis path parent_path() const; (filesystem TS) Returns the path to the parent directory. Returns empty path if empty() or there's - only a single element in the path (begin() == --end(). + only a single element in the path (begin() == --end()). - The resulting path is constructed by appending all elements in a range [begin(), - --end()) to an empty path. + The resulting path is constructed by appending all elements in a range + [begin(), --end()) to an empty path. .SH Parameters @@ -18,17 +21,35 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - This section is incomplete -.SH See also +// Run this code - This section is incomplete + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + for (fs::path p : {"/var/tmp/example.txt", "/", "/var/tmp/."}) + std::cout << "The parent path of " << p + << " is " << p.parent_path() << '\\n'; + } +.SH Possible output: -.SH Category: + The parent path of "/var/tmp/example.txt" is "/var/tmp" + The parent path of "/" is "" + The parent path of "/var/tmp/." is "/var/tmp" + +.SH See also + + + This section is incomplete +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::path::path.3 b/man/std::experimental::filesystem::path::path.3 index ecf764021..b7b95edb4 100644 --- a/man/std::experimental::filesystem::path::path.3 +++ b/man/std::experimental::filesystem::path::path.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::path \- std::experimental::filesystem::path::path + .SH Synopsis path(); \fB(1)\fP (filesystem TS) path( const path& p ); \fB(2)\fP (filesystem TS) @@ -18,41 +21,97 @@ 2) Copy constructor. Constructs a copy of p. 3) Move constructor. Constructs a copy of p, p is left in valid but unspecified state. - 4-7) Constructs the path from either a range of source (4,6) - - This section is incomplete - - or a range [first, last) (5,7). The format and encoding are converted, if needed. - 4-5) + 4,5) Constructs the path from a character sequence provided by source \fB(4)\fP, which is + a pointer or an input iterator to a null-terminated character/wide character + sequence or an std::basic_string, or represented as a pair of input iterators + [first, last) \fB(5)\fP. Any of the four character types char, char16_t, char32_t, wchar_t + is allowed, and the method of conversion to the native character set depends on the + character type used by source. - This section is incomplete - - 6-7) Uses loc to perform the encoding conversion. If value_type is wchar_t, converts - to native wide encoding using the std::codecvt of loc. Otherwise, the - conversion firstly is performed using the std::codecvt facet and is - followed by second conversion to the current byte encoding. + * If the source character type is char, the encoding of the source is assumed to + be the native narrow encoding (so no conversion takes place on POSIX systems). + * If the source character type is char16_t, conversion from UTF-16 to native + filesystem encoding is used. + * If the source character type is char32_t, conversion from UTF-32 to native + filesystem encoding is used. + * If the source character type is wchar_t, the input is assumed to be the native + wide encoding (so no conversion takes places on Windows). + 6,7) Constructs the path from a character sequence provided by source \fB(6)\fP, which is + a pointer or an input iterator to a null-terminated character sequence or an + std::string, or represented as a pair of input iterators [first, last) \fB(7)\fP. The only + character type allowed is char. Uses loc to perform the character encoding + conversion. If value_type is wchar_t, converts from to wide using the + std::codecvt facet of loc. Otherwise, first converts + to wide using the std::codecvt facet and then + converts to filesystem native character type using std::codecvt + facet of loc. .SH Parameters - p - a path to copy - source - todo - first, last - a range of characters to initialize with - loc - locale that defines encoding conversion to use + p - a path to copy + a std::basic_string, pointer to a null-terminated character string, or + source - an input iterator with a character value type that points to a + null-terminated character sequence (the character type must be char + for overload \fB(6)\fP + first, last - pair of LegacyInputIterators that specify a UTF-8 encoded character + sequence + loc - locale that defines encoding conversion to use .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of InputIt must be one of the four character types char, wchar_t, + char16_t and char32_t to use the overload \fB(5)\fP. - - The value type of InputIt must be one of the encoded character types (char, wchar_t, - char16_t and char32_t) + The value type of InputIt must be char to use the overload \fB(7)\fP. .SH Exceptions - 1-2) \fI(none)\fP + 1,2) \fI(none)\fP 3) - noexcept specification: + noexcept specification: noexcept - + 4-7) \fI(none)\fP -.SH Category: - * Todo without reason +.SH Notes + + For portable pathname generation from Unicode strings, see u8path. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p1 = "/usr/lib/sendmail.cf"; // portable format + fs::path p2 = "C:\\\\users\\\\abcdef\\\\AppData\\\\Local\\\\Temp\\\\"; // native format + fs::path p3 = L"D:/猫.txt"; // wide string + + std::cout << "p1 = " << p1 << '\\n' + << "p2 = " << p2 << '\\n' + << "p3 = " << p3 << '\\n'; + } + +.SH Output: + + p1 = "/usr/lib/sendmail.cf" + p2 = "C:\\users\\abcdef\\AppData\\Local\\Temp\\" + p3 = "D:/猫.txt" + +.SH See also + + u8path creates a path from a UTF-8 encoded source + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path::relative_path.3 b/man/std::experimental::filesystem::path::relative_path.3 index 0d5f8c233..5728489a9 100644 --- a/man/std::experimental::filesystem::path::relative_path.3 +++ b/man/std::experimental::filesystem::path::relative_path.3 @@ -1,31 +1,57 @@ -.TH std::experimental::filesystem::path::relative_path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::relative_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::relative_path \- std::experimental::filesystem::path::relative_path + .SH Synopsis path relative_path() const; (filesystem TS) - Returns path relative to the root-path. If *this is an empty path, returns an empty + Returns path relative to root path. If *this is an empty path, returns an empty path. - This section is incomplete - Reason: what is root-path? - .SH Parameters \fI(none)\fP .SH Return value - Path relative to the root-path. + Path relative to the root path. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. -.SH See also +.SH Example + + +// Run this code - This section is incomplete + #include + #include + namespace fs = std::experimental::filesystem; + int main() + { + fs::path p = fs::current_path(); + + std::cout << "The current path " << p << " decomposes into:\\n" + << "root-path " << p.root_path() << '\\n' + << "relative path " << p.relative_path() << '\\n'; + } + +.SH Possible output: + + The current path "C:\\Users\\abcdef\\Local Settings\\temp" decomposes into: + root-path "C:\\" + relative path "Users\\abcdef\\Local Settings\\temp" + +.SH See also - Categories: + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_directory returns the root directory of the path, if present + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP - * Todo with reason - * Todo without reason +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::remove_filename.3 b/man/std::experimental::filesystem::path::remove_filename.3 index de09a0f7c..0661a9bd3 100644 --- a/man/std::experimental::filesystem::path::remove_filename.3 +++ b/man/std::experimental::filesystem::path::remove_filename.3 @@ -1,10 +1,14 @@ -.TH std::experimental::filesystem::path::remove_filename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::remove_filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::remove_filename \- std::experimental::filesystem::path::remove_filename + .SH Synopsis path& remove_filename() \fB(1)\fP (filesystem TS) Removes a single filename component. - This section is incomplete + The behavior is undefined if the path has no filename component (has_filename + returns false). .SH Parameters @@ -16,30 +20,36 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code - #include + #include #include - + namespace fs = std::experimental::filesystem; + int main() { - std::cout << std::fs::path("/foo").remove_filename() << '\\n'; - std::cout << std::fs::path("/").remove_filename() << '\\n'; + std::cout << fs::path("/foo").remove_filename() << '\\n' + << fs::path("/").remove_filename() << '\\n'; } .SH Output: - / + "/" + "" .SH See also - This section is incomplete + filename returns the filename path component + \fI(public member function)\fP + replace_filename replaces the last path component with another path + \fI(public member function)\fP + has_filename checks if the corresponding path element is not empty + \fI(public member function)\fP .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::replace_extension.3 b/man/std::experimental::filesystem::path::replace_extension.3 index 832346b19..f8f089cfa 100644 --- a/man/std::experimental::filesystem::path::replace_extension.3 +++ b/man/std::experimental::filesystem::path::replace_extension.3 @@ -1,15 +1,19 @@ -.TH std::experimental::filesystem::path::replace_extension 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::replace_extension 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::replace_extension \- std::experimental::filesystem::path::replace_extension + .SH Synopsis path& replace_extension( const path& replacement = path() ); \fB(1)\fP (filesystem TS) - Replaces the extension with replacement. + Replaces the extension with replacement or removes it when the default value of + replacement is used. - Firstly, any existing extension is removed. + Firstly, if this path has an extension(), it is removed. Then, a dot character is appended if replacement is not empty or does not begin with a dot character. - replacement is appended to the path. + Then replacement is appended to the path. .SH Parameters @@ -21,9 +25,40 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = "/foo/bar.jpeg"; + std::cout << "Was: " << p << '\\n'; + p.replace_extension(".jpg"); + std::cout << "Now: " << p << '\\n'; + } + +.SH Output: + + Was: "/foo/bar.jpeg" + Now: "/foo/bar.jpg" .SH See also - replace_filename replaces the last path component with another path - \fI(public member function)\fP + extension returns the file extension path component + \fI(public member function)\fP + filename returns the filename path component + \fI(public member function)\fP + stem returns the stem path component + \fI(public member function)\fP + has_extension checks if the corresponding path element is not empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::replace_filename.3 b/man/std::experimental::filesystem::path::replace_filename.3 index 2298621c8..ced09b1ac 100644 --- a/man/std::experimental::filesystem::path::replace_filename.3 +++ b/man/std::experimental::filesystem::path::replace_filename.3 @@ -1,11 +1,19 @@ -.TH std::experimental::filesystem::path::replace_filename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::replace_filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::replace_filename \- std::experimental::filesystem::path::replace_filename + .SH Synopsis - path& replace_filename( const path& replacement ); \fB(1)\fP (filesystem TS) + path& replace_filename( const path& replacement ); (filesystem TS) + + Replaces a single filename component with replacement. + + Equivalent to the following: - Replaces a single filename component with replacement. Equivalent to the following: + remove_filename(); + operator/=(replacement); - remove_filename(); - operator/=(replacement); + The behavior is undefined if the path has no filename component (has_filename + returns false). .SH Parameters @@ -17,28 +25,38 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code - #include + #include #include - + namespace fs = std::experimental::filesystem; + int main() { - std::cout << std::fs::path("/foo").replace_filename("bar") << '\\n'; - std::cout << std::fs::path("/").replace_filename("bar") << '\\n'; + std::cout << fs::path("/foo").replace_filename("bar") << '\\n' + << fs::path("/").replace_filename("bar") << '\\n'; } .SH Output: - /bar - bar + "/bar" + "bar" .SH See also replace_extension replaces the extension - \fI(public member function)\fP + \fI(public member function)\fP + filename returns the filename path component + \fI(public member function)\fP + remove_filename removes filename path component + \fI(public member function)\fP + has_filename checks if the corresponding path element is not empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::root_directory.3 b/man/std::experimental::filesystem::path::root_directory.3 index 76d3af0c2..b80c07fe9 100644 --- a/man/std::experimental::filesystem::path::root_directory.3 +++ b/man/std::experimental::filesystem::path::root_directory.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::root_directory 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::root_directory 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::root_directory \- std::experimental::filesystem::path::root_directory + .SH Synopsis path root_directory() const; (filesystem TS) @@ -15,11 +18,40 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = fs::current_path(); + + std::cout << "The current path " << p << " decomposes into:\\n" + << "root name " << p.root_name() << '\\n' + << "root directory " << p.root_directory() << '\\n' + << "relative path " << p.relative_path() << '\\n'; + } + +.SH Possible output: + + The current path "C:\\Users\\abcdef\\Local Settings\\temp" decomposes into: + root name "C:" + root directory "\\" + relative path "Users\\abcdef\\Local Settings\\temp" .SH See also root_name returns the root-name of the path, if present - \fI(public member function)\fP + \fI(public member function)\fP root_path returns the root path of the path, if present - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::root_name.3 b/man/std::experimental::filesystem::path::root_name.3 index c0043ed5f..dc2fa0118 100644 --- a/man/std::experimental::filesystem::path::root_name.3 +++ b/man/std::experimental::filesystem::path::root_name.3 @@ -1,27 +1,49 @@ -.TH std::experimental::filesystem::path::root_name 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::root_name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::root_name \- std::experimental::filesystem::path::root_name + .SH Synopsis - path root_path() const; (filesystem TS) + path root_name() const; (filesystem TS) - Returns the root path of the path. If the path does not include root path, returns + Returns the root name of the path. If the path does not include root name, returns path(). - Effectively, returns the following: root_name() / root_directory() - .SH Parameters \fI(none)\fP .SH Return value - The root path of the path. + The root name of the path. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + std::cout << "Current root name is: " << fs::current_path().root_name() << '\\n'; + } + +.SH Possible output: + + Current root name is: "C:" .SH See also - root_name returns the root-name of the path, if present - \fI(public member function)\fP root_directory returns the root directory of the path, if present - \fI(public member function)\fP + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::root_path.3 b/man/std::experimental::filesystem::path::root_path.3 new file mode 100644 index 000000000..87ca6749f --- /dev/null +++ b/man/std::experimental::filesystem::path::root_path.3 @@ -0,0 +1,51 @@ +.TH std::experimental::filesystem::path::root_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::root_path \- std::experimental::filesystem::path::root_path + +.SH Synopsis + path root_path() const; (filesystem TS) + + Returns the root path of the path. If the path does not include root path, returns + path(). + + Effectively, returns the following: root_name() / root_directory() + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The root path of the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + std::cout << "Current root path is: " << fs::current_path().root_path() << '\\n'; + } + +.SH Possible output: + + Current root path is: "C:\\" + +.SH See also + + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_directory returns the root directory of the path, if present + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::stem.3 b/man/std::experimental::filesystem::path::stem.3 index 53051714f..1a1d0f7f3 100644 --- a/man/std::experimental::filesystem::path::stem.3 +++ b/man/std::experimental::filesystem::path::stem.3 @@ -1,12 +1,17 @@ -.TH std::experimental::filesystem::path::stem 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::stem 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::stem \- std::experimental::filesystem::path::stem + .SH Synopsis path stem() const; (filesystem TS) Returns the filename identified by the path stripped of its extension. - If filename() is not equal to . or .., then returns the substring between its - beginning and the last . character, if present. The . character is not included into - the return value. + Returns the substring from the beginning of filename() up to and not including the + last period (.) character. + + If the filename is one of the special filesystem components dot or dot-dot, or if it + has no periods, the function returns the entire filename(). .SH Parameters @@ -18,32 +23,40 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code - #include + #include #include - + namespace fs = std::experimental::filesystem; + int main() { - std::cout << std::fs::path("/foo/bar.txt").stem() << '\\n'; - std::cout << std::fs::path("/foo/.bar").stem() << '\\n'; - std::cout << std::fs::path("/foo/bar").extension() << '\\n'; + std::cout << fs::path("/foo/bar.txt").stem() << '\\n' + << fs::path("/foo/.bar").stem() << '\\n'; + + for (fs::path p = "foo.bar.baz.tar"; !p.extension().empty(); p = p.stem()) + std::cout << p.extension() << '\\n'; } .SH Output: - bar - - bar + "bar" + "" + ".tar" + ".baz" + ".bar" .SH See also filename returns the filename path component - \fI(public member function)\fP + \fI(public member function)\fP extension returns the file extension path component - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::path::string,wstring,u8string,....3 b/man/std::experimental::filesystem::path::string,wstring,u8string,....3 index 063c43d53..981abc156 100644 --- a/man/std::experimental::filesystem::path::string,wstring,u8string,....3 +++ b/man/std::experimental::filesystem::path::string,wstring,u8string,....3 @@ -1,14 +1,17 @@ -.TH std::experimental::filesystem::path::string,wstring,u8string,... 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::string,wstring,u8string,... 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::string,wstring,u8string,... \- std::experimental::filesystem::path::string,wstring,u8string,... + .SH Synopsis - template< class CharT, class Traits = std::char_traits + template< class CharT, class Traits = std::char_traits, - class Alloc = std::allocator > \fB(1)\fP (filesystem TS) + class Alloc = std::allocator > \fB(1)\fP (filesystem TS) std::basic_string - string( const Alloc& a = Allocator() ) const; + string( const Alloc& a = Alloc() ) const; std::string string() const; std::wstring wstring() const; - std::u8string u8string() const; \fB(2)\fP (filesystem TS) + std::string u8string() const; \fB(2)\fP (filesystem TS) std::u16string u16string() const; std::u32string u32string() const; @@ -24,17 +27,67 @@ .SH Return value - The internal pathname in generic pathname format, converted to specified string - type. + The internal pathname in native pathname format, converted to specified string type. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + + +// Run this code + + #include + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::locale::global(std::locale("en_US.utf8")); + + fs::path p = fs::u8path(u8"要らない.txt"); + + // native string representation can be used with OS APIs + std::ofstream(p) << "File contents"; // this uses operator string() + if (std::FILE* f = std::fopen(p.c_str(), "r")) + { + int ch; + while ((ch=fgetc(f))!= EOF) putchar(ch); + std::fclose(f); + } + + // multibyte and wide representation can be used for output + std::cout.imbue(std::locale()); + std::cout << "\\nFile name in narrow multibyte encoding: " + << p.string() << '\\n'; + + std::wcerr.imbue(std::locale()); + std::wcerr << "File name in wide encoding: " + << p.wstring() << '\\n'; + + fs::remove(p); + } + +.SH Possible output: + + File contents + File name in narrow multibyte encoding: 要らない.txt + File name in wide encoding: 要らない.txt .SH See also generic_string generic_wstring returns the path in generic pathname format converted to a string - generic_u8string \fI(public member function)\fP + generic_u8string \fI(public member function)\fP generic_u16string generic_u32string + +.SH Categories: + * Noindexed pages + * Uses of dcl rev begin with nonempty note diff --git a/man/std::experimental::filesystem::path::swap.3 b/man/std::experimental::filesystem::path::swap.3 index 456caa20a..5b62770b6 100644 --- a/man/std::experimental::filesystem::path::swap.3 +++ b/man/std::experimental::filesystem::path::swap.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::path::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::swap \- std::experimental::filesystem::path::swap + .SH Synopsis void swap( path& other ); \fB(1)\fP (filesystem TS) @@ -14,9 +17,9 @@ .SH Exceptions - noexcept specification: + noexcept specification: noexcept - + .SH Complexity @@ -26,6 +29,10 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages + * unconditionally noexcept * Todo without reason +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::path::~path.3 b/man/std::experimental::filesystem::path::~path.3 index fb877c9b2..2f07d7db4 100644 --- a/man/std::experimental::filesystem::path::~path.3 +++ b/man/std::experimental::filesystem::path::~path.3 @@ -1,5 +1,11 @@ -.TH std::experimental::filesystem::path::~path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::path::~path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::path::~path \- std::experimental::filesystem::path::~path + .SH Synopsis ~path(); (filesystem TS) Destroys the path object. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::permissions.3 b/man/std::experimental::filesystem::permissions.3 new file mode 100644 index 000000000..fd46a9521 --- /dev/null +++ b/man/std::experimental::filesystem::permissions.3 @@ -0,0 +1,120 @@ +.TH std::experimental::filesystem::permissions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::permissions \- std::experimental::filesystem::permissions + +.SH Synopsis + Defined in header + void permissions( const path& p, perms prms ); (filesystem TS) + void permissions( const path& p, perms prms, error_code& ec ); + + Changes access permissions of the file to which p resolves, as if by POSIX fchmodat. + Symlinks are followed if prms::resolve_symlinks is set. + + The effects depend on prms as follows: + + * If neither perms::add_perms nor perms::remove_perms is set, file permissions are + set to exactly prms & fs::perms::mask (meaning, every valid bit of prms is + applied). + * If perms::add_perms, the file permissions are set to exactly + status(p).permissions() | (prms & perms::mask) (meaning, any valid bit that is + set in prms, but not in the file's current permissions is added to the file's + permissions). + * If perms::remove_perms is set, the file permissions are set to exactly + status(p).permissions() & ~(prms & perms::mask) (meaning, any valid bit that is + clear in prms, but set in the file's current permissions is cleared in the + file's permissions). + * If both perms::add_perms and perms::remove_perms are set, error occurs. + + The non-throwing overload has no special action on error. + +.SH Parameters + + p - path to examine + prms - permissions to set, add, or remove + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + Permissions may not necessarily be implemented as bits, but they are treated that + way conceptually. + + Some permission bits may be ignored on some systems, and changing some bits may + automatically change others (e.g. on platforms without owner/group/all distinction, + setting any of the three write bits set all three). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + void demo_perms(fs::perms p) + { + std::cout << ((p & fs::perms::owner_read) != fs::perms::none ? "r" : "-") + << ((p & fs::perms::owner_write) != fs::perms::none ? "w" : "-") + << ((p & fs::perms::owner_exec) != fs::perms::none ? "x" : "-") + << ((p & fs::perms::group_read) != fs::perms::none ? "r" : "-") + << ((p & fs::perms::group_write) != fs::perms::none ? "w" : "-") + << ((p & fs::perms::group_exec) != fs::perms::none ? "x" : "-") + << ((p & fs::perms::others_read) != fs::perms::none ? "r" : "-") + << ((p & fs::perms::others_write) != fs::perms::none ? "w" : "-") + << ((p & fs::perms::others_exec) != fs::perms::none ? "x" : "-") + << '\\n'; + } + + int main() + { + std::ofstream("test.txt"); // create file + + std::cout << "Created file with permissions: "; + demo_perms(fs::status("test.txt").permissions()); + + fs::permissions("test.txt", fs::perms::add_perms | + fs::perms::owner_all | fs::perms::group_all); + + std::cout << "After adding o+rwx and g+rwx: "; + demo_perms(fs::status("test.txt").permissions()); + + fs::remove("test.txt"); + } + +.SH Possible output: + + Created file with permissions: rw-r--r-- + After adding o+rwx and g+rwx: rwxrwxr-- + +.SH See also + + perms identifies file system permissions + \fI(enum)\fP + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::perms.3 b/man/std::experimental::filesystem::perms.3 index 92fd95ab3..8a1e98fc5 100644 --- a/man/std::experimental::filesystem::perms.3 +++ b/man/std::experimental::filesystem::perms.3 @@ -1,60 +1,145 @@ -.TH std::experimental::filesystem::perms 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::perms 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::perms \- std::experimental::filesystem::perms + .SH Synopsis Defined in header - enum class perms { - - owner_read = 0, - owner_write = 0400, - owner_exec = 0200, - owner_all = 0100, - group_read = 0700, - group_write = 040, - group_exec = 020, - group_all = 010, - others_read = 070, - others_write = 04, - others_exec = 02, (filesystem TS) - others_all = 01, - all = 0777, - set_uid = 04000, - set_gid = 02000, - sticky_bit = 01000, - mask = 07777, - unknown = 0xffff, - add_perms = 0x10000, - remove_perms = 0x20000, - resolve_symlinks = 0x40000 - - }; - - This section is incomplete - -.SH Constants - - {{dsc | mask | all | set_uid | set_gid | sticky_bit - Constant Meaning - owner_read - owner_write - owner_exec - owner_all - group_read - group_write - group_exec - group_all - others_read - others_write - others_exec - others_all - all - set_uid - set_gid - sticky_bit meaning operating-system dependent - unknown + enum class perms; (filesystem TS) + + This type represents file access permissions. perms satisfies the requirements of + BitmaskType (which means the bitwise operators operator&, operator|, operator^, + operator~, operator&=, operator|=, and operator^= are defined for this type). + + Access permissions model POSIX permission bits, and any individual file permissions + (as reported by status) are a combination of some of the following bits: + +.SH Member constants + + Member constant Value (octal) POSIX equivalent Meaning + none 0 No permission bits are set + owner_read 0400 S_IRUSR File owner has read permission + owner_write 0200 S_IWUSR File owner has write permission + owner_exec 0100 S_IXUSR File owner has execute/search + permission + File owner has read, write, and + execute/search permissions + owner_all 0700 S_IRWXU + Equivalent to owner_read | + owner_write | owner_exec + group_read 040 S_IRGRP The file's user group has read + permission + group_write 020 S_IWGRP The file's user group has write + permission + group_exec 010 S_IXGRP The file's user group has + execute/search permission + The file's user group has read, + write, and execute/search permissions + group_all 070 S_IRWXG + Equivalent to group_read | + group_write | group_exec + others_read 04 S_IROTH Other users have read permission + others_write 02 S_IWOTH Other users have write permission + others_exec 01 S_IXOTH Other users have execute/search + permission + Other users have read, write, and + execute/search permissions + others_all 07 S_IRWXO + Equivalent to others_read | + others_write | others_exec + All users have read, write, and + execute/search permissions + all 0777 + Equivalent to owner_all | group_all | + others_all + set_uid 04000 S_ISUID Set user ID to file owner user ID on + execution + set_gid 02000 S_ISGID Set group ID to file's user group ID + on execution + Implementation-defined meaning, but + POSIX XSI specifies that when set on + sticky_bit 01000 S_ISVTX a directory, only file owners may + delete files even if the directory is + writeable to others (used with /tmp) + All valid permission bits + mask 07777 + Equivalent to all | set_uid | set_gid + | sticky_bit + + Additionally, the following constants of this type are defined, which do not + represent permissions: + + Member constant Value (hex) Meaning + unknown 0xFFFF Unknown permissions (e.g. when file_status is created + without permissions) + add_perms 0x10000 Control bit that instructs permissions to add, but not + clear permission bits + remove_perms 0x20000 Control bit that instructs permissions to clear, but + not add permission bits + resolve_symlinks 0x40000 Control bit that instructs permissions to resolve + symlinks + +.SH Notes + + Permissions may not necessarily be implemented as bits, but they are treated that + way conceptually. + + Some permission bits may be ignored on some systems, and changing some bits may + automatically change others (e.g. on platforms without owner/group/all distinction, + setting any of the three write bits set all three). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + void demo_perms(fs::perms p) + { + std::cout << ((p & fs::perms::owner_read) != fs::perms::none ? "r" : "-") + << ((p & fs::perms::owner_write) != fs::perms::none ? "w" : "-") + << ((p & fs::perms::owner_exec) != fs::perms::none ? "x" : "-") + << ((p & fs::perms::group_read) != fs::perms::none ? "r" : "-") + << ((p & fs::perms::group_write) != fs::perms::none ? "w" : "-") + << ((p & fs::perms::group_exec) != fs::perms::none ? "x" : "-") + << ((p & fs::perms::others_read) != fs::perms::none ? "r" : "-") + << ((p & fs::perms::others_write) != fs::perms::none ? "w" : "-") + << ((p & fs::perms::others_exec) != fs::perms::none ? "x" : "-") + << '\\n'; + } + + int main() + { + std::ofstream("test.txt"); // create file + + std::cout << "Created file with permissions: "; + demo_perms(fs::status("test.txt").permissions()); + + fs::permissions("test.txt", fs::perms::add_perms | + fs::perms::owner_all | fs::perms::group_all); + + std::cout << "After adding o+rwx and g+rwx: "; + demo_perms(fs::status("test.txt").permissions()); + + fs::remove("test.txt"); + } + +.SH Possible output: + + Created file with permissions: rw-r--r-- + After adding o+rwx and g+rwx: rwxrwxr-- .SH See also - This section is incomplete + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + permissions modifies file access permissions + \fI(function)\fP .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::read_symlink.3 b/man/std::experimental::filesystem::read_symlink.3 new file mode 100644 index 000000000..3277e2a75 --- /dev/null +++ b/man/std::experimental::filesystem::read_symlink.3 @@ -0,0 +1,78 @@ +.TH std::experimental::filesystem::read_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::read_symlink \- std::experimental::filesystem::read_symlink + +.SH Synopsis + Defined in header + path read_symlink( const path& p ); (filesystem TS) + path read_symlink( const path& p, error_code& ec ); + + If the path p refers to a symbolic link, returns a new path object which refers to + the target of that symbolic link. + + It is an error if p does not refer to a symbolic link. + + The non-throwing overload returns an empty path on errors. + +.SH Parameters + + p - path to a symlink + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The target of the symlink (which may not necessarily exist). + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + // on a typical Linux system, /lib/libc.so.6 is a symlink + fs::path p = "/lib/libc.so.6"; + if (exists(p) && is_symlink(p)) + std::cout << p << " -> " << read_symlink(p) << '\\n'; + else + std::cout << p << " does not exist or is not a symlink\\n"; + } + +.SH Possible output: + + "/lib/libc.so.6" -> "libc-2.12.so" + +.SH See also + + is_symlink checks whether the argument refers to a symbolic link + \fI(function)\fP + create_symlink creates a symbolic link + create_directory_symlink \fI(function)\fP + copy_symlink copies a symbolic link + \fI(function)\fP + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::recursive_directory_iterator.3 b/man/std::experimental::filesystem::recursive_directory_iterator.3 index 21cc4fddb..73105ba36 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator.3 @@ -1,56 +1,125 @@ -.TH std::experimental::filesystem::recursive_directory_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator \- std::experimental::filesystem::recursive_directory_iterator + .SH Synopsis Defined in header - class recursive_directory_iterator : (filesystem TS) - public std::iterator; + class recursive_directory_iterator; (filesystem TS) + + recursive_directory_iterator is a LegacyInputIterator that iterates over the + directory_entry elements of a directory, and, recursively, over the entries of all + subdirectories. The iteration order is unspecified, except that each directory entry + is visited only once. + + By default, symlinks are not followed, but this can be enabled by specifying the + directory option follow_directory_symlink at construction time. - recursive_directory_iterator is an input iterator that can recursively advance - through entries of a directory and its children directories. Directory iteration - never returns directory entries to the current (dot) and parent (dot-dot) - directories. The order of directory entries is unspecified. + The special pathnames dot and dot-dot are skipped. - The past-the-end iterator (simply called the end iterator) is a special iterator. An - end iterator is always equal to an end iterator and never equal to a non-end - iterator. An end iterator is created by the default constructor of directory - iterator and when a directory iterator is advanced past the last directory element. - Calling operator* or operator-> on an end iterator yields undefined behavior. + If the recursive_directory_iterator is advanced past the last directory entry of the + top-level directory, it becomes equal to the default-constructed iterator, also + known as the end iterator. Two end iterators are always equal, dereferencing or + incrementing the end iterator is undefined behavior. - This section is incomplete - Reason: clarify + If a file or a directory is deleted or added to the directory tree after the + recursive directory iterator has been created, it is unspecified whether the change + would be observed through the iterator. - If a file in a directory is deleted after the directory iterator has been created, - the directory iterator may return a directory entry to the deleted file. If, on the - other hand, a new file is created after the directory iterator has been created, - iteration of the directory is not guaranteed to return a directory entry to the new - file. + If the directory structure contains cycles, the end iterator may be unreachable. + +.SH Member types + + Member type Definition + value_type filesystem::directory_entry + difference_type std::ptrdiff_t + pointer const filesystem::directory_entry* + reference const filesystem::directory_entry& + iterator_category std::input_iterator_tag .SH Member functions constructor constructs a recursive directory iterator - \fI(public member function)\fP + \fI(public member function)\fP destructor default destructor - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers operator* accesses the pointed-to entry - operator-> \fI(public member function)\fP + operator-> \fI(public member function)\fP returns the currently active options that affect the options iteration - \fI(public member function)\fP + \fI(public member function)\fP depth returns the current recursion depth - \fI(public member function)\fP + \fI(public member function)\fP checks whether the recursion is disabled for the current recursion_pending directory - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP increment advances to the next entry - operator++ \fI(public member function)\fP + operator++ \fI(public member function)\fP pop moves the iterator one level up in the directory hierarchy - \fI(public member function)\fP + \fI(public member function)\fP disable_recursion_pending disables recursion until the next increment - \fI(public member function)\fP + \fI(public member function)\fP -.SH Category: +.SH Non-member functions + + filesystem::begin(filesystem::recursive_directory_iterator) range-based for loop + filesystem::end(filesystem::recursive_directory_iterator) support + \fI(function)\fP + + Additionally, operator== and operator!= are provided, either as members or as + non-members, as required by LegacyInputIterator. + +.SH Notes + + A recursive_directory_iterator typically holds a reference-counted pointer (to + satisfy shallow-copy semantics of LegacyInputIterator) to an implementation object, + which holds: + + * a container (such as std::vector) of non-recursive directory_iterators that + forms the recursion stack. + * the recursion depth counter (accessible with depth()). + * the directory options used at construction (accessible with options()). + * the pending recursion flag (accessible with recursion_pending(), may be combined + with the directory options to save space). - * Todo with reason +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b"); + std::ofstream("sandbox/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + for (const fs::directory_entry& entry : fs::recursive_directory_iterator("sandbox")) + std::cout << entry << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/a" + "sandbox/a/b" + "sandbox/file1.txt" + "sandbox/syma" + +.SH See also + + directory_iterator an iterator to the contents of the directory + \fI(class)\fP + directory_entry a directory entry + \fI(class)\fP + directory_options options for iterating directory contents + \fI(enum)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::depth.3 b/man/std::experimental::filesystem::recursive_directory_iterator::depth.3 index eeac6110c..d8c027d8c 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::depth.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::depth.3 @@ -1,11 +1,16 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::depth 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::depth 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::depth \- std::experimental::filesystem::recursive_directory_iterator::depth + .SH Synopsis int depth() const; (filesystem TS) Returns the number of directories from the starting directory to the currently iterated directory, i.e. the current depth of the directory hierarchy. - The starting directory has depth of 0. + The starting directory has depth of 0, its subdirectories have depth 1, etc. + + The behavior is undefined if *this is the end iterator. .SH Parameters @@ -17,4 +22,48 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. + +.SH Example + + This example uses iteration depth to calculate the indentation of a directory tree + printout. + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b/c"); + fs::create_directories("sandbox/a/b/d/e"); + std::ofstream("sandbox/a/b/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + for (auto i = fs::recursive_directory_iterator("sandbox"); + i != fs::recursive_directory_iterator(); ++i) + { + std::cout << std::string(i.depth(), ' ') << *i; + if (fs::is_symlink(i->symlink_status())) + std::cout << " -> " << fs::read_symlink(*i); + std::cout << '\\n'; + } + fs::remove_all("sandbox"); + } + +.SH Output: + + "sandbox/a" + "sandbox/a/b" + "sandbox/a/b/c" + "sandbox/a/b/d" + "sandbox/a/b/d/e" + "sandbox/a/b/file1.txt" + "sandbox/syma" -> "a" + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending.3 b/man/std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending.3 index 45df3048b..f7eba037b 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending.3 @@ -1,9 +1,21 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending \- std::experimental::filesystem::recursive_directory_iterator::disable_recursion_pending + .SH Synopsis void disable_recursion_pending(); (filesystem TS) - Disables recursion to the currently referred directory, if any. recursion_pending() - == false after the call. + Disables recursion to the currently referred subdirectory, if any. + + The call modifies the pending recursion flag on the iterator in such a way that the + next time increment is called, the iterator will advance within the current directly + even if it is currently referring to a subdirectory that hasn't been visited. + + The status of the pending recursion flag can be queried with recursion_pending(), + which is false after this call. It is reset back to true after increment, and its + initial value is also true. + + The behavior is undefined if *this is the end iterator. .SH Parameters @@ -15,11 +27,52 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. - This section is incomplete - Reason: underspecified? +.SH Example -.SH Category: - * Todo with reason +// Run this code + + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b/c"); + fs::create_directories("sandbox/a/b/d/e"); + std::ofstream("sandbox/a/b/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + for (auto i = fs::recursive_directory_iterator("sandbox"); + i != fs::recursive_directory_iterator(); ++i) + { + std::cout << std::string(i.depth(), ' ') << *i; + if (fs::is_symlink(i->symlink_status())) + std::cout << " -> " << fs::read_symlink(*i); + std::cout << '\\n'; + + // do not descend into "b" + if (i->path().filename() == "b") + i.disable_recursion_pending(); + } + fs::remove_all("sandbox"); + } + +.SH Output: + + "sandbox/a" + "sandbox/a/b" + "sandbox/syma" -> "a" + +.SH See also + + recursion_pending checks whether the recursion is disabled for the current directory + \fI(public member function)\fP + increment advances to the next entry + operator++ \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::operator*,.3 b/man/std::experimental::filesystem::recursive_directory_iterator::operator*,.3 new file mode 100644 index 000000000..51fa176e7 --- /dev/null +++ b/man/std::experimental::filesystem::recursive_directory_iterator::operator*,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::filesystem::recursive_directory_iterator::operator*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::operator*, \- std::experimental::filesystem::recursive_directory_iterator::operator*, + +.SH Synopsis + + const directory_entry& operator*() const; \fB(1)\fP (filesystem TS) + const directory_entry* operator->() const; \fB(2)\fP (filesystem TS) + + Accesses the pointed-to directory_entry. + + The result of operator* or operator-> on the end iterator is undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Value of the directory_entry referred to by this iterator. + 2) Pointer to the directory_entry referred to by this iterator. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH See also + + operator* accesses the pointed-to entry + operator-> \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_iterator) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::operator*,operator->.3 b/man/std::experimental::filesystem::recursive_directory_iterator::operator*,operator->.3 deleted file mode 100644 index 5de3e696b..000000000 --- a/man/std::experimental::filesystem::recursive_directory_iterator::operator*,operator->.3 +++ /dev/null @@ -1,27 +0,0 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::operator*,operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - const recursive_directory_entry& operator*() const; - - (filesystem TS) - - const recursive_directory_entry* operator->() const; - - Accesses the pointed-to directory entry. - - This section is incomplete - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - This section is incomplete - -.SH Exceptions - - This section is incomplete - -.SH Category: - - * Todo without reason diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::operator++,increment.3 b/man/std::experimental::filesystem::recursive_directory_iterator::operator++,increment.3 index 5a3717bc9..d54a686fb 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::operator++,increment.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::operator++,increment.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::operator++,increment 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::operator++,increment 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::operator++,increment \- std::experimental::filesystem::recursive_directory_iterator::operator++,increment + .SH Synopsis recursive_directory_iterator& operator++(); (filesystem TS) recursive_directory_iterator& increment( error_code& ec ); (filesystem TS) @@ -19,8 +22,7 @@ * The directory is not a symlink or following symlinks is enabled, i.e. !is_symlink(this->symlink_status()) || - - (options() & directory_options::follow_directory_symlink) != 0). + (options() & directory_options::follow_directory_symlink) != 0). .SH Parameters @@ -35,6 +37,12 @@ 1) filesystem_error if an error occurs. The error code is set to an appropriate error code for the error that caused the failure. 2) - noexcept specification: + noexcept specification: noexcept - + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::operator=.3 b/man/std::experimental::filesystem::recursive_directory_iterator::operator=.3 index b412bc6cd..89b2cb660 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::operator=.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::operator=.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::operator= \- std::experimental::filesystem::recursive_directory_iterator::operator= + .SH Synopsis recursive_directory_iterator& operator=( const (filesystem TS) recursive_directory_iterator& ) = default; @@ -17,10 +20,10 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::options.3 b/man/std::experimental::filesystem::recursive_directory_iterator::options.3 index cea7e580a..b436cb961 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::options.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::options.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::options 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::options \- std::experimental::filesystem::recursive_directory_iterator::options + .SH Synopsis directory_options options() const; (filesystem TS) @@ -17,4 +20,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::pop.3 b/man/std::experimental::filesystem::recursive_directory_iterator::pop.3 index ff66c4424..73d7b19e4 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::pop.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::pop.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::pop 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::pop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::pop \- std::experimental::filesystem::recursive_directory_iterator::pop + .SH Synopsis void pop(); (filesystem TS) @@ -19,6 +22,6 @@ This section is incomplete -.SH Category: - +.SH Categories: + * Noindexed pages * Todo without reason diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::recursion_pending.3 b/man/std::experimental::filesystem::recursive_directory_iterator::recursion_pending.3 index 521a100fa..597854273 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::recursion_pending.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::recursion_pending.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::recursion_pending 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::recursion_pending 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::recursion_pending \- std::experimental::filesystem::recursive_directory_iterator::recursion_pending + .SH Synopsis bool recursion_pending() const; (filesystem TS) @@ -19,4 +22,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 b/man/std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 index 41caef2ad..fbd33bdb1 100644 --- a/man/std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 +++ b/man/std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator \- std::experimental::filesystem::recursive_directory_iterator::recursive_directory_iterator + .SH Synopsis recursive_directory_iterator(); \fB(1)\fP (filesystem TS) recursive_directory_iterator( const \fB(2)\fP (filesystem TS) @@ -13,11 +16,11 @@ error_code& ec ); recursive_directory_iterator( const path& p, error_code& ec ); \fB(6)\fP (filesystem TS) - Contructs new recursive directory iterator. + Constructs new recursive directory iterator. 1) Default constructor. Constructs an end iterator. - 2-3) Default copy and move constructors. - 4-6) Constructs a iterator that refers to the first entry in the directory that p + 2,3) Default copy and move constructors. + 4-6) Constructs an iterator that refers to the first entry in the directory that p resolves to. This section is incomplete @@ -30,9 +33,9 @@ .SH Exceptions 1,5,6) - noexcept specification: + noexcept specification: noexcept - + This section is incomplete @@ -42,7 +45,11 @@ this behavior, specify directory_options::follow_directory_symlink among the options option set. - Categories: - +.SH Categories: + * Noindexed pages * Todo with reason * Todo without reason + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::remove,std::experimental::filesystem::remove_all.3 b/man/std::experimental::filesystem::remove,std::experimental::filesystem::remove_all.3 new file mode 100644 index 000000000..253549cf1 --- /dev/null +++ b/man/std::experimental::filesystem::remove,std::experimental::filesystem::remove_all.3 @@ -0,0 +1,80 @@ +.TH std::experimental::filesystem::remove,std::experimental::filesystem::remove_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::remove,std::experimental::filesystem::remove_all \- std::experimental::filesystem::remove,std::experimental::filesystem::remove_all + +.SH Synopsis + Defined in header + bool remove( const path& p ); \fB(1)\fP (filesystem TS) + bool remove( const path& p, error_code& ec ); + std::uintmax_t remove_all( const path& p ); \fB(2)\fP (filesystem TS) + std::uintmax_t remove_all( const path& p, error_code& ec ); + + 1) The file or empty directory identified by the path p is deleted as if by the + POSIX remove. Symlinks are not followed (symlink is removed, not its target). + 2) Deletes the contents of p (if it is a directory) and the contents of all its + subdirectories, recursively, then deletes p itself as if by repeatedly applying the + POSIX remove. Symlinks are not followed (symlink is removed, not its target). + +.SH Parameters + + p - path to delete + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + 1) true if the file was deleted, false if it did not exist. The overload that takes + error_code& argument returns false on errors. + 2) Returns the number of files and directories that were deleted (which may be zero + if p did not exist to begin with). The overload that takes error_code& argument + returns static_cast(-1) on error. + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + On POSIX systems, this function typically calls unlink and rmdir as needed, on + Windows RemoveDirectoryW and DeleteFileW. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path dir = fs::temp_directory_path(); + fs::create_directories(dir / "abcdef/example"); + std::uintmax_t n = fs::remove_all(dir / "abcdef"); + std::cout << "Deleted " << n << " files or directories\\n"; + } + +.SH Possible output: + + Deleted 2 files or directories + +.SH See also + + remove erases a file + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::rename.3 b/man/std::experimental::filesystem::rename.3 new file mode 100644 index 000000000..67422f666 --- /dev/null +++ b/man/std::experimental::filesystem::rename.3 @@ -0,0 +1,106 @@ +.TH std::experimental::filesystem::rename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::rename \- std::experimental::filesystem::rename + +.SH Synopsis + Defined in header + void rename( const path& old_p, const path& new_p ); + void rename( const path& old_p, const path& new_p, std::error_code& (filesystem TS) + ec ); + + Moves or renames the filesystem object identified by old_p to new_p as if by the + POSIX rename: + + * If old_p is a non-directory file, then new_p must be one of: + + * the same file as old_p or a hardlink to it: nothing is done in this case. + * existing non-directory file: new_p is first deleted, then, without allowing + other processes to observe new_p as deleted, the pathname new_p is linked to the + file and old_p is unlinked from the file. Write permissions are required to both + the directory that contains old_p and the directory that contains new_p. + * non-existing file in an existing directory: The pathname new_p is linked to the + file and old_p is unlinked from the file. Write permissions are required to both + the directory that contains old_p and the directory that contains new_p. + * If old_p is a directory, then new_p must be one of: + + * the same directory as old_p or a hardlink to it: nothing is done in this case. + * existing directory: new_p is deleted if empty on POSIX systems, but this may be + an error on other systems. If not an error, then new_p is first deleted, then, + without allowing other processes to observe new_p as deleted, the pathname new_p + is linked to the directory and old_p is unlinked from the directory. Write + permissions are required to both the directory that contains old_p and the + directory that contains new_p. + * non-existing directory, not ending with a directory separator, and whose parent + directory exists: The pathname new_p is linked to the directory and old_p is + unlinked from the directory. Write permissions are required to both the + directory that contains old_p and the directory that contains new_p. + * Symlinks are not followed: if old_p is a symlink, it is itself renamed, not its + target. If new_p is an existing symlink, it is itself erased, not its target. + + Rename fails if + + * new_p ends with dot or with dot-dot. + * new_p names a non-existing directory ending with a directory separator. + * old_p is a directory which is an ancestor of new_p. + +.SH Parameters + + old_p - path to move or rename + new_p - target path for the move/rename operation + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with old_p as the first argument, new_p as the + second argument, and the OS error code as the error code argument. std::bad_alloc + may be thrown if memory allocation fails. The overload taking an error_code& + parameter sets it to the OS API error code if an OS API call fails, and executes + ec.clear() if no errors occur. This overload has + noexcept specification: + noexcept + + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = fs::current_path() / "sandbox"; + fs::create_directories(p/"from"); + std::ofstream(p/"from/file1.txt").put('a'); + fs::create_directory(p/"to"); + + // fs::rename(p/"from/file1.txt", p/"to/"); // error: to is a directory + fs::rename(p/"from/file1.txt", p/"to/file2.txt"); // OK + // fs::rename(p/"from", p/"to"); // error: to is not empty + fs::rename(p/"from", p/"to/subdir"); // OK + + fs::remove_all(p); + } + +.SH See also + + rename renames a file + \fI(function)\fP + remove removes a file or empty directory + remove_all removes a file or directory and all its contents, recursively + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::resize_file.3 b/man/std::experimental::filesystem::resize_file.3 new file mode 100644 index 000000000..827bf79c0 --- /dev/null +++ b/man/std::experimental::filesystem::resize_file.3 @@ -0,0 +1,87 @@ +.TH std::experimental::filesystem::resize_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::resize_file \- std::experimental::filesystem::resize_file + +.SH Synopsis + Defined in header + void resize_file( const path& p, std::uintmax_t new_size ); + void resize_file( const path& p, std::uintmax_t new_size, (filesystem TS) + error_code& ec ); + + Changes the size of the regular file named by p as if by POSIX truncate: if the file + size was previously larger than new_size, the remainder of the file is discarded. If + the file was previously smaller than new_size, the file size is increased and the + new area appears as if zero-filled. + +.SH Parameters + + p - path to resize + new_size - size that the file will now have + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + On systems that support sparse files, increasing the file size does not increase the + space it occupies on the file system: space allocation takes place only when + non-zero bytes are written to the file. + +.SH Example + + Demonstrates the effect of creating a sparse file on the free space. + + +// Run this code + + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::path p = fs::temp_directory_path() / "example.bin"; + std::ofstream(p).put('a'); + std::cout << "File size: " << fs::file_size(p) << '\\n' + << "Free space: " << fs::space(p).free << '\\n'; + fs::resize_file(p, 64*1024); // resize to 64 KB + std::cout << "File size: " << fs::file_size(p) << '\\n' + << "Free space: " << fs::space(p).free << '\\n'; + fs::remove(p); + } + +.SH Possible output: + + File size: 1 + Free space: 31805444096 + File size: 65536 + Free space: 31805444096 + +.SH See also + + file_size returns the size of a file + \fI(function)\fP + space determines available free space on the file system + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::space.3 b/man/std::experimental::filesystem::space.3 new file mode 100644 index 000000000..48d19840f --- /dev/null +++ b/man/std::experimental::filesystem::space.3 @@ -0,0 +1,87 @@ +.TH std::experimental::filesystem::space 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::space \- std::experimental::filesystem::space + +.SH Synopsis + Defined in header + space_info space( const path& p ); (filesystem TS) + space_info space( const path& p, error_code& ec ) noexcept; + + Determines the information about the filesystem on which the pathname p is located, + as if by POSIX statvfs. + + Populates and returns an object of type space_info, set from the members of the + POSIX struct statvfs as follows: + + * space_info.capacity is set as if by f_blocks * f_frsize. + * space_info.free is set to f_bfree * f_frsize. + * space_info.available is set to f_bavail * f_frsize. + * Any member that could not be determined is set to + static_cast(-1). + + The non-throwing overload sets all members to static_cast(-1) on + error. + +.SH Parameters + + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The filesystem information (a space_info object). + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + space_info.available may be less than space_info.free. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::space_info devi = fs::space("/dev/null"); + fs::space_info tmpi = fs::space("/tmp"); + + std::cout << " Capacity Free Available\\n" + << "/dev: " << devi.capacity << " " + << devi.free << " " << devi.available << '\\n' + << "/tmp: " << tmpi.capacity << ' ' + << tmpi.free << ' ' << tmpi.available << '\\n'; + } + +.SH Possible output: + + Capacity Free Available + /dev: 4175114240 4175110144 4175110144 + /tmp: 420651237376 411962273792 390570749952 + +.SH See also + + space_info information about free and available space on the filesystem + \fI(class)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::space_info.3 b/man/std::experimental::filesystem::space_info.3 index 63a53d5a0..3d7170b52 100644 --- a/man/std::experimental::filesystem::space_info.3 +++ b/man/std::experimental::filesystem::space_info.3 @@ -1,4 +1,7 @@ -.TH std::experimental::filesystem::space_info 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::space_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::space_info \- std::experimental::filesystem::space_info + .SH Synopsis Defined in header struct space_info { @@ -9,14 +12,46 @@ }; - This section is incomplete + Represents the filesystem information as determined by space. + + The members have the following meaning: + + * capacity -- total size of the filesystem, in bytes + * free -- free space on the filesystem, in bytes + * available -- free space available to a non-privileged process (may be equal or + less than free) + +.SH Example + + +// Run this code - available -- free space available to a non-privileged process + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + fs::space_info devi = fs::space("/dev/null"); + fs::space_info tmpi = fs::space("/tmp"); + + std::cout << " Capacity Free Available\\n" + << "/dev: " << devi.capacity << " " + << devi.free << " " << devi.available << '\\n' + << "/tmp: " << tmpi.capacity << ' ' + << tmpi.free << ' ' << tmpi.available << '\\n'; + } + +.SH Possible output: + + Capacity Free Available + /dev: 4175114240 4175110144 4175110144 + /tmp: 420651237376 411962273792 390570749952 .SH See also - This section is incomplete + space determines available free space on the file system + \fI(function)\fP .SH Category: - - * Todo without reason + * Noindexed pages diff --git a/man/std::experimental::filesystem::status,std::experimental::filesystem::symlink_status.3 b/man/std::experimental::filesystem::status,std::experimental::filesystem::symlink_status.3 new file mode 100644 index 000000000..d96452eb4 --- /dev/null +++ b/man/std::experimental::filesystem::status,std::experimental::filesystem::symlink_status.3 @@ -0,0 +1,172 @@ +.TH std::experimental::filesystem::status,std::experimental::filesystem::symlink_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::status,std::experimental::filesystem::symlink_status \- std::experimental::filesystem::status,std::experimental::filesystem::symlink_status + +.SH Synopsis + Defined in header + file_status status( const path& p ); \fB(1)\fP (filesystem TS) + file_status status( const path& p, error_code& ec ) noexcept; + file_status symlink_status( const path& p ); + file_status symlink_status( const path& p, error_code& ec ) \fB(2)\fP (filesystem TS) + noexcept; + + 1) Determines the type and attributes of the filesystem object identified by p as if + by POSIX stat (symlinks are followed to their targets). + + * If p is a regular file, returns file_status(file_type::regular). + * If p is a directory, returns file_status(file_type::directory). + * If p is a block special file, returns file_status(file_type::block). + * If p is a character special file, returns file_status(file_type::character). + * If p is a fifo or pipe file, returns file_status(file_type::fifo). + * If p is a socket, returns file_status(file_type::socket). + * If p does not exist, returns file_status(file_type::not_found). + * If p exists but file attributes cannot be determined, e.g. due to lack of + permissions, returns file_status(file_type::unknown). + * If errors prevent even knowing whether p exists, the non-throwing overload sets + ec and returns file_status(file_type::none), and the throwing overload throws + filesystem_error. + * Otherwise, returns file_status(file_type::unknown). + 2) Same as \fB(1)\fP except that the behavior is as if the POSIX lstat is used (symlinks + are not followed): + + * If p is a symlink, returns file_status(file_type::symlink). + +.SH Parameters + + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The file status (a file_status object). + +.SH Exceptions + + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with p as the first argument and the OS error + code as the error code argument. std::bad_alloc may be thrown if memory allocation + fails. The overload taking an error_code& parameter sets it to the OS API error code + if an OS API call fails, and executes ec.clear() if no errors occur. This overload + has + noexcept specification: + noexcept + + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration, and may be obtained by the member functions of directory_entry. + During directory iteration, calling status again is unnecessary. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::experimental::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ... } + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + std::ofstream("sandbox/file"); // create regular file + fs::create_directory("sandbox/dir"); + mkfifo("sandbox/pipe", 0644); + struct sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, (struct sockaddr*)&addr, sizeof addr); + fs::create_symlink("file", "sandbox/symlink"); + + // demo different status accessors + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "dev/null" is a character device + "dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + file_status represents file type and permissions + \fI(class)\fP + status_known checks whether file status is known + \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory + symlink_status entry + \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::status_known.3 b/man/std::experimental::filesystem::status_known.3 new file mode 100644 index 000000000..3a5e08dd6 --- /dev/null +++ b/man/std::experimental::filesystem::status_known.3 @@ -0,0 +1,46 @@ +.TH std::experimental::filesystem::status_known 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::status_known \- std::experimental::filesystem::status_known + +.SH Synopsis + Defined in header + bool status_known( file_status s ); \fB(1)\fP (filesystem TS) + + Checks if the given file status is known, Equivalent to s.type() != file_type::none. + +.SH Parameters + + s - file status to check + +.SH Return value + + true if the given file status is an unknown file status. + +.SH Exceptions + + noexcept specification: + noexcept + + +.SH Notes + + Despite the name, the function checks for the file status of file_type::none + (meaning an error occurred), not file_type::unknown (meaning file exists, but its + type cannot be determined). + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(function)\fP + cached status of the file designated by this directory entry + status cached symlink_status of the file designated by this directory entry + symlink_status \fI\fI(public member\fP function of\fP + std::experimental::filesystem::directory_entry) + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::swap(std::experimental::filesystem::path).3 b/man/std::experimental::filesystem::swap(std::experimental::filesystem::path).3 new file mode 100644 index 000000000..731f5e6d6 --- /dev/null +++ b/man/std::experimental::filesystem::swap(std::experimental::filesystem::path).3 @@ -0,0 +1,34 @@ +.TH std::experimental::filesystem::swap(std::experimental::filesystem::path) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::swap(std::experimental::filesystem::path) \- std::experimental::filesystem::swap(std::experimental::filesystem::path) + +.SH Synopsis + void swap( path& lhs, path& rhs ); (filesystem TS) + + Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - paths whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept + + +.SH See also + + swap swaps two paths + \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::temp_directory_path.3 b/man/std::experimental::filesystem::temp_directory_path.3 index 758d76a41..acc3c0cba 100644 --- a/man/std::experimental::filesystem::temp_directory_path.3 +++ b/man/std::experimental::filesystem::temp_directory_path.3 @@ -1,15 +1,13 @@ -.TH std::experimental::filesystem::temp_directory_path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::temp_directory_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::temp_directory_path \- std::experimental::filesystem::temp_directory_path + .SH Synopsis Defined in header path temp_directory_path(); \fB(1)\fP (filesystem TS) - path temp_directory_path( error_code& ec ); \fB(2)\fP (filesystem TS) - - Returns an unspecified directory suitable for temporary files. - - An error is reported if the path to be returned does not exist or is not directory. + path temp_directory_path( error_code& ec ); - The second version returns path() and sets ec to an appropriate error code if error - occurs. Otherwise, ec is cleared via ec.clear(). + Returns the directory location suitable for temporary files. .SH Parameters @@ -17,34 +15,56 @@ .SH Return value - A directory suitable for temporary files. + A directory suitable for temporary files. The path is guaranteed to exist and to be + a directory. The overload that takes error_code& argument returns an empty path on + error. .SH Exceptions - 1) filesystem_error if an error occurs. - 2) - noexcept specification: + The overload that does not take an error_code& parameter throws filesystem_error on + underlying OS API errors, constructed with path to be returned as the first argument + and the OS error code as the error code argument. std::bad_alloc may be thrown if + memory allocation fails. The overload taking an error_code& parameter sets it to the + OS API error code if an OS API call fails, and executes ec.clear() if no errors + occur. This overload has + noexcept specification: noexcept - + + +.SH Notes + + On POSIX systems, the path may be the one specified in the environment variables + TMPDIR, TMP, TEMP, TEMPDIR, and, if none of them are specified, the path "/tmp" is + returned. + + On Windows systems, the path is typically the one returned by GetTempPath. .SH Example - + // Run this code - #include + #include #include - + namespace fs = std::experimental::filesystem; + int main() { - namespace fs = std::experimental::filesystem; - std::cout << fs::temp_directory_path() << '\\n'; + std::cout << "Temp directory is " << fs::temp_directory_path() << '\\n'; } -.SH Output: +.SH Possible output: - /tmp + Temp directory is "C:\\Windows\\TEMP\\" .SH See also - Template:cpp/experimental/fs/dsc unique path + tmpfile creates and opens a temporary, auto-removing file + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept +.SH Hidden categories: + * Pages with unreviewed unconditional noexcept template + * Pages with unreviewed noexcept template diff --git a/man/std::experimental::filesystem::u8path.3 b/man/std::experimental::filesystem::u8path.3 index 0cb5937b3..36fcf1f54 100644 --- a/man/std::experimental::filesystem::u8path.3 +++ b/man/std::experimental::filesystem::u8path.3 @@ -1,52 +1,111 @@ -.TH std::experimental::filesystem::u8path 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::filesystem::u8path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::filesystem::u8path \- std::experimental::filesystem::u8path + .SH Synopsis + Defined in header template< class Source > \fB(1)\fP (filesystem TS) path u8path( const Source& source ); template< class InputIt > \fB(2)\fP (filesystem TS) path u8path( InputIt first, InputIt last ); - Creates an UTF-8 path from the given UTF-8 encoded char-based sources. - - If value_type is char and the current native narrow encoding is UTF-8, returns - path(source) or path(begin, end). - - Otherwise, if value_type is wchar_t and the native wide encoding is UTF-16, or if - value_type is char16_t or char32_t, converts source or the range [first, last) to a - temporary value of type string_type and returns a path constructed from that value. + Constructs a path p from a UTF-8 encoded sequence of chars, supplied either as an + std::string, or as a null-terminated multibyte string, or as a [first, last) + iterator pair. - Otherwise, converts source or the range [first, last) to a temporary value of type - std::u32string and returns a path constructed from that value. - - This section is incomplete - Reason: argument format conversion - - It is unspecified how Unicode encoding conversions are performed. + * If path::value_type is char and native encoding is UTF-8, constructs a path + directly as if by path(source) or path(first, last). Note: this is the typical + situation of a POSIX system that uses Unicode, such as Linux. + * Otherwise, if path::value_type is wchar_t and native encoding is UTF-16 (this is + the situation on Windows), or if path::value_type is char16_t (native encoding + guaranteed UTF-16) or char32_t (native encoding guaranteed UTF-32), then first + converts the UTF-8 character sequence to a temporary string tmp of type + path::string_type and then the new path is constructed as if by path(tmp). + * Otherwise (for non-UTF-8 narrow character encodings and for non-UTF-16 wchar_t), + first converts the UTF-8 character sequence to a temporary UTF-32-encoded string + tmp of type std::u32string, and then the new path is constructed as if by + path(tmp) (this path is taken on a POSIX system with a non-Unicode multibyte or + single-byte encoded filesystem). .SH Parameters - a character sequence to construct the path - source - from. - - This section is incomplete - a range to construct the path from. - first, last - - This section is incomplete + a UTF-8 encoded std::string, pointer to a null-terminated multibyte + source - string, or an input iterator with char value type that points to a + null-terminated multibyte string + first, last - pair of LegacyInputIterators that specify a UTF-8 encoded character + sequence .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - The value type of InputIt must be one of the encoded character types (char, wchar_t, - char16_t and char32_t) + The value type of InputIt must be char. .SH Return value - A newly constructed UTF-8 encoded path. + The path constructed from the input string after conversion from UTF-8 to the + filesystem's native character encoding. .SH Exceptions - \fI(none)\fP + May throw filesystem_error on underlying OS API errors or std::bad_alloc if memory + allocation fails. + +.SH Notes + + On systems where native path format differs from the generic path format (neither + Windows nor POSIX systems are examples of such OSes), if the argument to this + function is using generic format, it will be converted to native. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + namespace fs = std::experimental::filesystem; + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::locale::global(std::locale("en_US.utf8")); + + fs::path p = fs::u8path(u8"要らない.txt"); + + // native string representation can be used with OS APIs + std::ofstream(p) << "File contents"; // this uses operator string() + if (std::FILE* f = std::fopen(p.c_str(), "r")) + { + int ch; + while ((ch=fgetc(f))!= EOF) putchar(ch); + std::fclose(f); + } + + // multibyte and wide representation can be used for output + std::cout.imbue(std::locale()); + std::cout << "\\nFile name in narrow multibyte encoding: " + << p.string() << '\\n'; + + std::wcerr.imbue(std::locale()); + std::wcerr << "File name in wide encoding: " + << p.wstring() << '\\n'; + + fs::remove(p); + } + +.SH Possible output: + + File contents + File name in narrow multibyte encoding: 要らない.txt + File name in wide encoding: 要らない.txt + +.SH See also - Categories: + path represents a path + \fI(class)\fP - * Todo with reason - * Todo without reason +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::find_first_set,std::experimental::find_last_set.3 b/man/std::experimental::find_first_set,std::experimental::find_last_set.3 new file mode 100644 index 000000000..830f5a891 --- /dev/null +++ b/man/std::experimental::find_first_set,std::experimental::find_last_set.3 @@ -0,0 +1,69 @@ +.TH std::experimental::find_first_set,std::experimental::find_last_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::find_first_set,std::experimental::find_last_set \- std::experimental::find_first_set,std::experimental::find_last_set + +.SH Synopsis + Defined in header + template< class T, class Abi > \fB(1)\fP (parallelism TS v2) + int find_first_set( const simd_mask& k ); + template< class T, class Abi > \fB(2)\fP (parallelism TS v2) + int find_last_set( const simd_mask& k ); + + 1) Returns the lowest index i where k[i] is true. + 2) Returns the greatest index i where k[i] is true. + + The behavior is undefined if any_of(k) is false. + +.SH Parameters + + k - the simd_mask to apply the reduction to + +.SH Return value + + An int in the range [0, simd_size_v). + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace stdx = std::experimental; + + template + int find(stdx::simd_mask const& v) + { + if (stdx::any_of(v)) + return find_first_set(v); + return -1; + } + + int main() + { + stdx::simd_mask a{0}; + a[2] = a[a.size() - 2] = 1; + + for (std::size_t i = 0; i < a.size(); ++i) + std::cout << a[i] << ' '; + std::cout << '\\n'; + + std::cout << "find_first_set: " << stdx::find_first_set(a) << '\\n'; + std::cout << "find_last_set: " << stdx::find_last_set(a) << '\\n'; + std::cout << "find: " << find(a) << '\\n'; + a[2] = 0; + std::cout << "find: " << find(a) << '\\n'; + a[a.size() - 2] = 0; + std::cout << "find: " << find(a) << '\\n'; + } + +.SH Possible output: + + 0 0 1 0 0 0 1 0 + find_first_set: 2 + find_last_set: 6 + find: 2 + find: 6 + find: -1 diff --git a/man/std::experimental::flex_barrier.3 b/man/std::experimental::flex_barrier.3 new file mode 100644 index 000000000..23d7c8675 --- /dev/null +++ b/man/std::experimental::flex_barrier.3 @@ -0,0 +1,42 @@ +.TH std::experimental::flex_barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::flex_barrier \- std::experimental::flex_barrier + +.SH Synopsis + Defined in header + class flex_barrier; (concurrency TS) + + The class std::experimental::flex_barrier provides a thread-coordination mechanism + that allows a set of participating threads to block until an operation is completed. + Unlike std::experimental::latch, barriers are reusable; once the participating + threads are released from a barrier's synchronization point, they can reuse the same + barrier. + + A barrier has a completion phase, which is executed by one of the participating + threads once all threads in the set of participating threads arrive at the + synchronization point. The arrive_and_wait and arrive_and_drop calls synchronize + with the start of the completion phase; the end of the completion phase synchronizes + with the returns from all calls blocked by its completion. + + std::experimental::flex_barrier allows the user to control the completion phase with + a function object. If the function object returns -1, the set of participating + threads is unchanged (and the same set of participating threads must arrive at the + synchronization point in the next cycle); otherwise the set of participating threads + becomes a new set with a size equal to the returned value N, and consists of the + next N threads to arrive at the barrier's synchronization point. + + Users who do not need this functionality can use std::experimental::barrier. + +.SH Member functions + + constructor constructs a flex_barrier + \fI(public member function)\fP + destructor destroys the flex_barrier + \fI(public member function)\fP + operator= not copy-assignable + [deleted] \fI(public member function)\fP + arrive_and_wait arrive at the synchronization point and block + \fI(public member function)\fP + arrive at the synchronization point and remove the current thread + arrive_and_drop from the set of participating threads + \fI(public member function)\fP diff --git a/man/std::experimental::flex_barrier::arrive_and_drop.3 b/man/std::experimental::flex_barrier::arrive_and_drop.3 new file mode 100644 index 000000000..3a60b5afc --- /dev/null +++ b/man/std::experimental::flex_barrier::arrive_and_drop.3 @@ -0,0 +1,39 @@ +.TH std::experimental::flex_barrier::arrive_and_drop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::flex_barrier::arrive_and_drop \- std::experimental::flex_barrier::arrive_and_drop + +.SH Synopsis + void arrive_and_drop(); (concurrency TS) + + Arrive at the flex_barrier's synchronization point and remove the current thread + from the set of participating threads. It is unspecified whether this function + blocks until the completion phase has ended. If the function blocks, the calling + thread may be chosen to execute the completion phase. + + The behavior is undefined if the calling thread is not in the set of participating + threads of this flex_barrier. + + Calls to arrive_and_drop synchronizes with the start of the completion phase of the + flex_barrier. If the call blocks, then the completion of the completion phase + synchronizes with the return from the call. + + Calls to arrive_and_drop and arrive_and_wait never introduce data races with + themselves or each other. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + The completion phase will be executed even if every participating thread calls + arrive_and_drop. + + After a thread calls arrive_and_drop on a flex_barrier, it cannot call any member + function on that barrier except for the destructor, even if the function object + invoked by the completion phase returns a positive value. + +.SH See also + + arrive_and_wait arrive at the synchronization point and block + \fI(public member function)\fP diff --git a/man/std::experimental::flex_barrier::arrive_and_wait.3 b/man/std::experimental::flex_barrier::arrive_and_wait.3 new file mode 100644 index 000000000..bf35168fb --- /dev/null +++ b/man/std::experimental::flex_barrier::arrive_and_wait.3 @@ -0,0 +1,44 @@ +.TH std::experimental::flex_barrier::arrive_and_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::flex_barrier::arrive_and_wait \- std::experimental::flex_barrier::arrive_and_wait + +.SH Synopsis + void arrive_and_wait(); (concurrency TS) + + Blocks and arrives at the flex_barrier's synchronization point. + + The behavior is undefined if the calling thread is not in the set of participating + threads of this flex_barrier. + + Calls to arrive_and_wait synchronizes with the start of the completion phase of the + flex_barrier. The completion of the completion phase synchronizes with the return + from the call. + + Calls to arrive_and_drop and arrive_and_wait never introduce data races with + themselves or each other. + +.SH Notes + + It is safe for a thread to call either arrive_and_wait() or arrive_and_drop() + immediately on return from this call (provided that the function object for the + completion phase did not return zero). It's not necessary to ensure that all blocked + threads have exited arrive_and_wait() before a thread calls it again. + + The completion phase executes the function object specified when the flex_barrier + was constructed. If it returns -1, the set of participating threads is unchanged; + otherwise, the set of participating threads is a new set with the size equal to the + return value N, and consists of the next N threads to arrive at the synchronization + point. If N == 0, the flex_barrier can only be destroyed. + + The initial set of participating threads for a flex_barrier constructed for + num_threads threads is the first num_threads to arrive at its synchronization point. + +.SH Exceptions + + Throws nothing. + +.SH See also + + arrive at the synchronization point and remove the current thread + arrive_and_drop from the set of participating threads + \fI(public member function)\fP diff --git a/man/std::experimental::flex_barrier::flex_barrier.3 b/man/std::experimental::flex_barrier::flex_barrier.3 new file mode 100644 index 000000000..87c434688 --- /dev/null +++ b/man/std::experimental::flex_barrier::flex_barrier.3 @@ -0,0 +1,32 @@ +.TH std::experimental::flex_barrier::flex_barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::flex_barrier::flex_barrier \- std::experimental::flex_barrier::flex_barrier + +.SH Synopsis + explicit flex_barrier( std::ptrdiff_t num_threads ); \fB(1)\fP (concurrency TS) + template< class F > \fB(2)\fP (concurrency TS) + flex_barrier( std::ptrdiff_t num_threads, F completion ); + flex_barrier( const flex_barrier & ) = delete; \fB(3)\fP (concurrency TS) + + 1) Has the same effect as flex_barrier(num_threads, c), where c is a Callable object + whose invocation returns -1 and has no side effects. + 2) Constructs a flex_barrier for num_threads participating threads, using completion + for the completion phase. The set of participating threads is the first num_threads + threads to arrive at the synchronization point. + 3) Copy constructor is deleted; flex_barrier is not copyable. + +.SH Parameters + + num_threads - the number of participating threads for the flex_barrier; must be + non-negative + a function object controlling the completion phase; must be Callable + completion - with no arguments and return type std::ptrdiff_t, and when invoked, + must return a value no less than -1 and must not throw an exception +.SH Type requirements + - + F must meet the requirements of CopyConstructible. + +.SH Notes + + If num_threads is zero, the set of participating threads is empty, and flex_barrier + can only be destroyed. diff --git a/man/std::experimental::flex_barrier::~flex_barrier.3 b/man/std::experimental::flex_barrier::~flex_barrier.3 new file mode 100644 index 000000000..1102254e2 --- /dev/null +++ b/man/std::experimental::flex_barrier::~flex_barrier.3 @@ -0,0 +1,10 @@ +.TH std::experimental::flex_barrier::~flex_barrier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::flex_barrier::~flex_barrier \- std::experimental::flex_barrier::~flex_barrier + +.SH Synopsis + ~flex_barrier(); (concurrency TS) + + Destroys the flex_barrier. + + The behavior is undefined if a thread is blocked at the synchronization point. diff --git a/man/std::experimental::function.3 b/man/std::experimental::function.3 new file mode 100644 index 000000000..c0242c5f7 --- /dev/null +++ b/man/std::experimental::function.3 @@ -0,0 +1,85 @@ +.TH std::experimental::function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::function \- std::experimental::function + +.SH Synopsis + Defined in header + template< class > (library fundamentals TS) + class function; /* undefined */ + template< class R, class... Args > (library fundamentals TS) + class function + + std::experimental::function is a modified version of std::function with support for + type-erased allocators. + +.SH Member types + + Type Definition + std::experimental::erased_type (library fundamentals TS) + allocator_type (until library fundamentals TS v3) + std::pmr::polymorphic_allocator<> (library fundamentals TS v3) + +.SH Member functions + + constructs a new std::experimental::function + constructor instance + \fI(public member function)\fP + operator= assigns a new target + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + get_memory_resource retrieves a pointer to the memory resource used by + (removed in library fundamentals this object to allocate memory + TS v3) \fI(public member function)\fP + retrieves a type-erased + get_allocator std::pmr::polymorphic_allocator used by this object + (library fundamentals TS v3) to allocate memory + \fI(public member function)\fP + +.SH Non-member functions + + std::experimental::swap(std::experimental::function) specializes the swap algorithm + \fI(function template)\fP + operator== compares an + operator!= std::experimental::function + (removed in library fundamentals TS v3) with nullptr + \fI(function template)\fP + +.SH Helper classes + + specializes the std::uses_allocator + std::uses_allocator type trait + (removed in library fundamentals TS v3) \fI(class template specialization)\fP + + +Members identical to std::function + +.SH Member types + + Type Definition + result_type R + Member types removed in Library Fundamental TS v3 + argument_type T if sizeof...(Args) == 1 and T is the first and only type in + Args... + first_argument_type T1 if sizeof...(Args) == 2 and T1 is the first of the two types + in Args... + second_argument_type T2 if sizeof...(Args) == 2 and T2 is the second of the two + types in Args... + + Member types argument_type, first_argument_type, and (library fundamentals TS + second_argument_type are removed, because the correponding v3) + member types of std::function are removed in C++20. + +.SH Member functions + + destructor destroys a std::function instance + \fI(public member function of std::function)\fP + operator bool checks if a target is contained + \fI(public member function of std::function)\fP + operator() invokes the target + \fI(public member function of std::function)\fP +.SH Target access + target_type obtains the typeid of the stored target + \fI(public member function of std::function)\fP + target obtains a pointer to the stored target + \fI(public member function of std::function)\fP diff --git a/man/std::experimental::function::function.3 b/man/std::experimental::function::function.3 new file mode 100644 index 000000000..8b881a242 --- /dev/null +++ b/man/std::experimental::function::function.3 @@ -0,0 +1,155 @@ +.TH std::experimental::function::function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::function::function \- std::experimental::function::function + +.SH Synopsis + (library +function() noexcept; \fB(1)\fP fundamentals + TS) +function( (library +std::nullptr_t ) \fB(2)\fP fundamentals +noexcept; TS) +function( const (library +function& other ); \fB(3)\fP fundamentals + TS) +function( function&& (library +other ); \fB(4)\fP fundamentals + TS) +template< class F > (library +function( F f ); \fB(5)\fP fundamentals + TS) +template< class Alloc +> (library +function( fundamentals +std::allocator_arg_t, TS) +const Alloc& alloc ) +noexcept; +function( +std::allocator_arg_t, (library + const fundamentals +allocator_type& alloc TS v3) +) noexcept; +template< class Alloc +> + +function( (library +std::allocator_arg_t, fundamentals +const Alloc& alloc, TS) + + +std::nullptr_t ) +noexcept; +function( +std::allocator_arg_t, +const allocator_type& (library +alloc, fundamentals + TS v3) +std::nullptr_t ) +noexcept; +template< class Alloc +> + +function( (library +std::allocator_arg_t, fundamentals +const Alloc& alloc, \fB(6)\fP TS) + + const +function& other ); +function( +std::allocator_arg_t, (library +const allocator_type& \fB(7)\fP fundamentals +alloc, TS v3) + const +function& other ); +template< class Alloc +> + +function( (library +std::allocator_arg_t, \fB(8)\fP fundamentals +const Alloc& alloc, TS) + + function&& +other ); +function( +std::allocator_arg_t, (library +const allocator_type& fundamentals +alloc, \fB(9)\fP TS v3) + function&& +other ); +template< class F, +class Alloc > (library +function( fundamentals +std::allocator_arg_t, TS) +const Alloc& alloc, F \fB(10)\fP +f ); +function( (library +std::allocator_arg_t, fundamentals +const allocator_type& TS v3) +alloc, F f ); + + Constructs a std::experimental::function from a variety of sources. + + 1,2) Creates an empty function. + 3) Copies the target of other to the target of *this. If other is empty, *this will + be empty after the call too. + 4) Moves the target of other to the target of *this. If other is empty, *this will + be empty after the call too. + After construction, *this stores a copy of other.get_allocator(). + (library fundamentals TS v3) + 5) Initializes the target with a copy of f. If f is a null pointer to function or + null pointer to member, *this will be empty after the call. This constructor does + not participate in overload resolution unless f is Callable for argument types + Args... and return type R. + 6-10) Same as (1-5) except that alloc is used to allocate memory for any internal + data structures that the function might use. + These constructors treat alloc as a type-erased allocator (see below). + (until library fundamentals TS v3) + + After construction via (1-5), this->get_memory_resource() (library + returns the same value as fundamentals TS) + std::experimental::pmr::get_default_resource() during (until library + construction. fundamentals TS v3) + After construction via (1-3) and \fB(5)\fP, *this stores a default (library + constructed std::pmr::polymorphic_allocator<>. fundamentals TS v3) + + When the target is a function pointer or a std::reference_wrapper, small object + optimization is guaranteed, that is, these targets are always directly stored inside + the std::experimental::function object, no dynamic allocation takes place. Other + large objects may be constructed in dynamic allocated storage and accessed by the + std::experimental::function object through a pointer. + + If a constructor moves or copies a function object, including an instance of + std::experimental::function, then that move or copy is performed by using-allocator + construction with allocator + this->get_memory_resource() + (until library fundamentals TS v3) + this->get_allocator() + (library fundamentals TS v3). + +.SH Parameters + + other - the function object used to initialize *this + f - a callable used to initialize *this + alloc - an allocator used for internal memory allocation +.SH Type requirements + - + F must meet the requirements of Callable and CopyConstructible. + +.SH Exceptions + + 3,8) Does not throw if other's target is a function pointer or a + std::reference_wrapper, otherwise may throw std::bad_alloc or any exception thrown + by the copy constructor of the stored callable object. + 4) \fI(none)\fP + 5,10) Does not throw if f is a function pointer or a std::reference_wrapper, + otherwise may throw std::bad_alloc or any exception thrown by the copy constructor + of the stored callable object. + 9) \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::function::get_allocator.3 b/man/std::experimental::function::get_allocator.3 new file mode 100644 index 000000000..7e5c205ed --- /dev/null +++ b/man/std::experimental::function::get_allocator.3 @@ -0,0 +1,25 @@ +.TH std::experimental::function::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::function::get_allocator \- std::experimental::function::get_allocator + +.SH Synopsis + std::pmr::polymorphic_allocator<> get_allocator() const (library fundamentals TS + noexcept; v3) + + Returns the std::pmr::polymorphic_allocator<> stored at the construction of function + object. If no allocator was explicitly specified, the stored allocator is equal to + the source allocator in move construction, or is default-constructed otherwise. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The std::pmr::polymorphic_allocator<> stored at the construction of function object. + +.SH See also + + get_memory_resource retrieves a pointer to the memory resource + (removed in library fundamentals TS v3) used by this object to allocate memory + \fI(public member function)\fP diff --git a/man/std::experimental::function::get_memory_resource.3 b/man/std::experimental::function::get_memory_resource.3 new file mode 100644 index 000000000..d0879dc89 --- /dev/null +++ b/man/std::experimental::function::get_memory_resource.3 @@ -0,0 +1,27 @@ +.TH std::experimental::function::get_memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::function::get_memory_resource \- std::experimental::function::get_memory_resource + +.SH Synopsis + (library fundamentals + std::experimental::pmr::memory_resource* TS) + get_memory_resource() const noexcept; (removed in library + fundamentals TS v3) + + Returns a pointer to the memory resource used by this object to allocate memory. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the memory resource used by this object to allocate memory. + +.SH See also + + constructor constructs a new std::experimental::function instance + \fI(public member function)\fP + get_allocator retrieves a type-erased std::pmr::polymorphic_allocator + (library fundamentals TS used by this object to allocate memory + v3) \fI(public member function)\fP diff --git a/man/std::experimental::function::operator=.3 b/man/std::experimental::function::operator=.3 new file mode 100644 index 000000000..d0b7c7cb1 --- /dev/null +++ b/man/std::experimental::function::operator=.3 @@ -0,0 +1,71 @@ +.TH std::experimental::function::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::function::operator= \- std::experimental::function::operator= + +.SH Synopsis + function& operator=( const function& other \fB(1)\fP (library + ); fundamentals TS) + function& operator=( function&& other ); \fB(2)\fP (library + fundamentals TS) + function& operator=( std::nullptr_t ) \fB(3)\fP (library + noexcept; fundamentals TS) + template< class F > \fB(4)\fP (library + function& operator=( F&& f ); fundamentals TS) + template< class F > (library + function& operator=( fundamentals TS) + std::reference_wrapper f ); \fB(5)\fP + template< class F > (library + function& operator=( fundamentals TS v3) + std::reference_wrapper f ) noexcept; + + Assigns a new target to std::experimental::function. In the description below, let + ALLOCATOR_OF(f) be the allocator specified in the construction of f, or + the value of std::experimental::pmr::get_default_resource() + (until library fundamentals TS v3) + the default-constructed std::pmr::polymorphic_allocator<> value + (library fundamentals TS v3) at the time of construction if no allocator was + specified. + + 1) Assigns a copy of target of other, as if by executing + function(std::allocator_arg, ALLOCATOR_OF(*this), other).swap(*this);. + 2) Moves the target of other to *this, as if by executing + function(std::allocator_arg, ALLOCATOR_OF(*this), std::move(other)).swap(*this);. + other is in a valid state with an unspecified value. + 3) Destroys the target of *this. *this is empty after the call. The memory resource + returned by get_memory_resource() after the assignment is equivalent to the memory + resource before the assignment, but the address may change. + 4) Sets the target of *this to the callable f, as if by executing + function(std::allocator_arg, ALLOCATOR_OF(*this),std::forward(f)).swap(*this);. + This operator does not participate in overload resolution unless f is Callable for + argument types Args... and return type R. + 5) Sets the target of *this to a copy of f, as if by executing + function(std::allocator_arg, ALLOCATOR_OF(*this), f).swap(*this);. + +.SH Parameters + + other - another std::experimental::function object to copy or move from + f - a callable to initialize the target with +.SH Type requirements + - + F must meet the requirements of Callable. + +.SH Return value + + *this + +.SH Exceptions + + 1,2,4) Exception thrown on needed allocation of the storage or initialization of the + target of *this, if any. + 5) \fI(none)\fP + +.SH Notes + + The move assignment operator may need to allocate storage if + get_memory_resource() != other.get_memory_resource() + (until library fundamentals TS v3) + get_allocator() != other.get_allocator() + (library fundamentals TS v3) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::function::swap.3 b/man/std::experimental::function::swap.3 new file mode 100644 index 000000000..f4205f146 --- /dev/null +++ b/man/std::experimental::function::swap.3 @@ -0,0 +1,24 @@ +.TH std::experimental::function::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::function::swap \- std::experimental::function::swap + +.SH Synopsis + void swap( function& other ); (library fundamentals TS) + + Exchanges the stored callable objects of *this and other. + + The allocators of *this and other are not exchanged. + + The behavior is undefined if *this->get_memory_resource() (library fundamentals TS) + != *other.get_memory_resource(). (until library + fundamentals TS v3) + The behavior is undefined if this->get_allocator() != (library fundamentals TS + other.get_allocator(). v3) + +.SH Parameters + + other - function wrapper to exchange the stored callable object with + +.SH Return value + + \fI(none)\fP diff --git a/man/std::experimental::future.3 b/man/std::experimental::future.3 new file mode 100644 index 000000000..4dfd0b037 --- /dev/null +++ b/man/std::experimental::future.3 @@ -0,0 +1,71 @@ +.TH std::experimental::future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::future \- std::experimental::future + +.SH Synopsis + Defined in header + template< class T > class future; \fB(1)\fP (concurrency TS) + template< class T > class future; \fB(2)\fP (concurrency TS) + template<> class future; \fB(3)\fP (concurrency TS) + + The class template std::experimental::future extends std::future with the following + operations: + + * an unwrapping constructor from future>; + * a member function is_ready to query whether the associated shared state is + ready; and + * a member function then to attach a continuation to the future. + + However, there is no interoperation between std::experimental::future and + std::future. + +.SH Member functions + + constructor construct a future object + \fI(public member function)\fP + is_ready checks if the shared state is ready + \fI(public member function)\fP + then attaches a continuation to a future + \fI(public member function)\fP + operator= moves the future object + \fI(public member function)\fP + +Members identical to std::future + +.SH Member functions + + Note that share() returns a std::experimental::shared_future. The behavior is + otherwise identical. + + destructor destructs the future object + \fI(public member function of std::future)\fP + share transfers the shared state from *this to a shared_future and returns it + \fI(public member function of std::future)\fP +.SH Getting the result + get returns the result + \fI(public member function of std::future)\fP +.SH State + valid checks if the future has a shared state + \fI(public member function of std::future)\fP + wait waits for the result to become available + \fI(public member function of std::future)\fP + waits for the result, returns if it is not available for the specified + wait_for timeout duration + \fI(public member function of std::future)\fP + waits for the result, returns if it is not available until specified + wait_until time point has been reached + \fI(public member function of std::future)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + shared_future a version of std::shared_future enhanced with continuations and + (concurrency TS) other features + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::future::future.3 b/man/std::experimental::future::future.3 new file mode 100644 index 000000000..8a89afd81 --- /dev/null +++ b/man/std::experimental::future::future.3 @@ -0,0 +1,54 @@ +.TH std::experimental::future::future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::future::future \- std::experimental::future::future + +.SH Synopsis + future() noexcept; \fB(1)\fP + future( std::experimental::future&& f ) noexcept; \fB(2)\fP + future( const std::experimental::future& ) = delete; \fB(3)\fP + future( std::experimental::future> && other ) \fB(4)\fP + noexcept; + + 1) Default constructor. Constructs an empty future object that does not refer to a + shared state. + 2) Constructs a future object, transferring the shared state held by f, if any. + After construction, f.valid() is false. + 3) Copy constructor is deleted. future cannot be copied. + 4) Unwrapping constructor. Constructs a future object from the shared state referred + to by other, if any. If other.valid() == false prior to this call, the constructed + future object is empty. Otherwise, the resulting future object becomes ready when + one of the following happens: + * other and other.get() are both ready. The value or exception from other.get() is + stored in the shared state associated with the resulting future object. + * other is ready, but other.get() is invalid. An exception of type + std::future_error with an error condition of std::future_errc::broken_promise is + stored in the shared state associated with the resulting future object. + After this constructor returns, valid() is equal to the value of other.valid() prior + to this call, and other.valid() == false. + +.SH Parameters + + f - another future object to initialize with + other - a std::experimental::future object to unwrap + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2697 Concurrency TS behavior of unwrapping constructor is constructs an empty + unclear with an invalid future future + +.SH See also + + constructor constructs the future object + \fI(public member function of std::future)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::future::is_ready.3 b/man/std::experimental::future::is_ready.3 new file mode 100644 index 000000000..d662fefbc --- /dev/null +++ b/man/std::experimental::future::is_ready.3 @@ -0,0 +1,31 @@ +.TH std::experimental::future::is_ready 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::future::is_ready \- std::experimental::future::is_ready + +.SH Synopsis + bool is_ready() const; + + Checks if the associated shared state is ready. + + The behavior is undefined if valid() is false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the associated shared state is ready, otherwise false. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + valid checks if the future has a shared state + \fI(public member function of std::future)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::future::operator=.3 b/man/std::experimental::future::operator=.3 new file mode 100644 index 000000000..a915b47ac --- /dev/null +++ b/man/std::experimental::future::operator=.3 @@ -0,0 +1,24 @@ +.TH std::experimental::future::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::future::operator= \- std::experimental::future::operator= + +.SH Synopsis + std::experimental::future& operator=( std::experimental::future&& other ) \fB(1)\fP + noexcept; + std::experimental::future& operator=( const std::experimental::future& \fB(2)\fP + other ) = delete; + + Assigns the contents of another future object. + + 1) Releases any shared state and move-assigns the contents of other to *this. After + the assignment, other.valid() == false and this->valid() will yield the same value + as other.valid() before the assignment. + 2) std::experimental::future is not CopyAssignable. + +.SH Parameters + + other - a std::experimental::future that will transfer state to *this + +.SH Return value + + *this diff --git a/man/std::experimental::future::then.3 b/man/std::experimental::future::then.3 new file mode 100644 index 000000000..7bc4be16e --- /dev/null +++ b/man/std::experimental::future::then.3 @@ -0,0 +1,59 @@ +.TH std::experimental::future::then 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::future::then \- std::experimental::future::then + +.SH Synopsis + template< class F > + future then( F&& func ) ; + + Attach the continuation func to *this. The behavior is undefined if *this has no + associated shared state (i.e., valid() == false). + + Creates a shared state associated with the future object to be returned, and a copy + fd of func constructed as if by DECAY_COPY(std::forward(func)) evaluated in the + thread calling then, where DECAY_COPY is defined as + + template + std::decay_t DECAY_COPY(T&& v) + { + return std::forward(v); + } + + When the shared state currently associated with *this is ready, the continuation + INVOKE(std::move(fd), std::move(*this)) is called on an unspecified thread of + execution, where INVOKE is the operation defined in Callable. If that expression is + invalid, the behavior is undefined. + + Any value returned from the continuation is stored as the result in the shared state + of the returned future object. Any exception propagated from the execution of the + continuation is stored as the exceptional result in the shared state of the returned + future object. + + Let U be the return type of the continuation (i.e. + std::result_of_t(std::experimental::future)>). If U is + std::experimental::future for some type T2, then the return type of then is + std::experimental::future, otherwise it is std::experimental::future. This is + known as implicit unwrapping. + + If implicit unwrapping takes place and the continuation returns an invalid future, + then the shared state is made ready with an exception of type std::future_error with + an error condition of std::future_errc::broken_promise. + + After this function returns, valid() is false. + +.SH Parameters + + func - a continuation to be attached + +.SH Return value + + A std::experimental::future object associated with the shared state created by this + object. valid() == true for the returned object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::gcd.3 b/man/std::experimental::gcd.3 new file mode 100644 index 000000000..b6c55839e --- /dev/null +++ b/man/std::experimental::gcd.3 @@ -0,0 +1,36 @@ +.TH std::experimental::gcd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::gcd \- std::experimental::gcd + +.SH Synopsis + Defined in header + template< class M, class N> (library fundamentals TS v2) + constexpr std::common_type_t gcd( M m, N n ); + + Computes the greatest common divisor of the integers m and n. + +.SH Parameters + + m, n - integer values + +.SH Return value + + If both m and n are zero, returns zero. Otherwise, returns the greatest common + divisor of |m| and |n|. + + Remarks + + If either M or N is not an integer type, or if either is (possibly cv-qualified) + bool, the program is ill-formed. + + If either |m| or |n| is not representable as a value of type std::common_type_t, the behavior is undefined. + +.SH Exceptions + + Throws no exceptions. + +.SH See also + + lcm constexpr function template returning the least common multiple of two integers + \fI(function template)\fP diff --git a/man/std::experimental::get_underlying.3 b/man/std::experimental::get_underlying.3 new file mode 100644 index 000000000..d7fb378b3 --- /dev/null +++ b/man/std::experimental::get_underlying.3 @@ -0,0 +1,21 @@ +.TH std::experimental::get_underlying 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::get_underlying \- std::experimental::get_underlying + +.SH Synopsis + template< class T > + constexpr T& get_underlying( propagate_const& pt ) (library fundamentals TS v2) + noexcept; + template< class T > + constexpr const T& get_underlying( const (library fundamentals TS v2) + propagate_const& pt ) noexcept; + + Retrieves a reference to the pointer-like object stored in a propagate_const. + +.SH Parameters + + pt - a propagate_const object + +.SH Return value + + A reference to the pointer-like object stored in pt. diff --git a/man/std::experimental::in_place.3 b/man/std::experimental::in_place.3 new file mode 100644 index 000000000..4f3db0fc9 --- /dev/null +++ b/man/std::experimental::in_place.3 @@ -0,0 +1,26 @@ +.TH std::experimental::in_place 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::in_place \- std::experimental::in_place + +.SH Synopsis + Defined in header + constexpr in_place_t in_place{}; (library fundamentals TS) + + std::experimental::in_place is a constant of type std::experimental::in_place_t that + is used to disambiguate the overloads of constructors and member functions of that + take arguments (possibly a parameter pack) for in-place construction of some value. + +.SH See also + + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP + optional a wrapper that may or may not hold an object + \fI(C++17)\fP \fI(class template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::in_place_t.3 b/man/std::experimental::in_place_t.3 new file mode 100644 index 000000000..aab94a7e7 --- /dev/null +++ b/man/std::experimental::in_place_t.3 @@ -0,0 +1,26 @@ +.TH std::experimental::in_place_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::in_place_t \- std::experimental::in_place_t + +.SH Synopsis + Defined in header + struct in_place_t {}; (library fundamentals TS) + + std::experimental::in_place_t is an empty class type used to disambiguate the + overloads of constructors and member functions of that take arguments (possibly a + parameter pack) for in-place construction of some value. + +.SH See also + + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP + optional a wrapper that may or may not hold an object + \fI(C++17)\fP \fI(class template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::invocation_type,std::experimental::raw_invocation_type.3 b/man/std::experimental::invocation_type,std::experimental::raw_invocation_type.3 new file mode 100644 index 000000000..2c2461706 --- /dev/null +++ b/man/std::experimental::invocation_type,std::experimental::raw_invocation_type.3 @@ -0,0 +1,99 @@ +.TH std::experimental::invocation_type,std::experimental::raw_invocation_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::invocation_type,std::experimental::raw_invocation_type \- std::experimental::invocation_type,std::experimental::raw_invocation_type + +.SH Synopsis + Defined in header + template< class > + + struct raw_invocation_type; //undefined + \fB(1)\fP (library fundamentals TS) + template< class Fn, class... ArgTypes > + + struct raw_invocation_type; + template< class > + + struct invocation_type; //undefined + \fB(2)\fP (library fundamentals TS) + template< class Fn, class... ArgTypes > + + struct invocation_type; + + Computes the invocation parameters when Fn is called with the arguments ArgTypes..., + as in INVOKE(std::declval(), std::declval()...), where INVOKE is the + operation defined in Callable. + + The invocation parameters of the expression INVOKE(f, t1, t2, ..., tN) is defined as + follows, where T1 is the (possibly cv-qualified) type of t1 and U1 is T1& if t1 is + an lvalue and T1&& otherwise: + + * If f is a pointer to a member function of a class T, then the invocation + parameters are U1 followed by the parameters of f matched by t2, ..., tN. + * If N == 1 and f is a pointer to member data of a class T, then the invocation + parameter is U1. + * If f is an object of class type, the invocation parameters are the parameters + matching t1, ..., tN of the best viable function for the arguments t1, ..., tN + among the function call operators and surrogate call functions of f. + * In all other cases, the invocations parameters are the parameters of f matching + t1, ..., tN. + + If an argument tI matches an ellipsis in the function's parameter list, the + corresponding invocation parameter is the result of applying the default argument + promotions to tI. + + Fn and all types in ArgTypes can be any complete type, array of unknown bound, or + (possibly cv-qualified) void. + +.SH Member types + + Member type Definition + R(T1, T2, ...), where: + * R is + std::result_of_t. + * T1, T2, ... are the invocation + parameters of + raw_invocation_type::type INVOKE(std::declval(), + std::declval()...) as + defined above. + + Only defined if Fn can be called with the + arguments ArgTypes... in unevaluated + context. + R(U1, U2, ...), where + * R is + std::result_of_t. + * T1, T2, ... are the invocation + parameters of + INVOKE(std::declval(), + std::declval()...) as + invocation_type::type defined above. + * A1, A2, ... denotes ArgTypes... + * Ui is std::decay_t if + std::declval() is an rvalue and + Ti otherwise. + + Only defined if Fn can be called with the + arguments ArgTypes... in unevaluated + context. + +.SH Helper types + + template< class T > + using raw_invocation_type_t = typename (library fundamentals TS) + raw_invocation_type::type; + template< class T > + using invocation_type_t = typename (library fundamentals TS) + invocation_type::type; + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + C++ documentation for + Reflection TS + +.SH Category: + * Todo no example diff --git a/man/std::experimental::is_abi_tag.3 b/man/std::experimental::is_abi_tag.3 new file mode 100644 index 000000000..bc42ab3d9 --- /dev/null +++ b/man/std::experimental::is_abi_tag.3 @@ -0,0 +1,68 @@ +.TH std::experimental::is_abi_tag 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::is_abi_tag \- std::experimental::is_abi_tag + +.SH Synopsis + Defined in header + template< class T > (parallelism TS v2) + struct is_abi_tag; + + If T is an ABI tag in the simd_abi namespace, provides the member constant value + equal true. For any other type, value is false. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > (parallelism TS v2) + inline constexpr bool is_abi_tag_v = is_abi_tag::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is an ABI tag type, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + namespace stdx = std::experimental; + std::cout << std::boolalpha + << stdx::is_abi_tag_v << '\\n' + << stdx::is_abi_tag_v << '\\n'; + } + +.SH Output: + + true + false + +.SH See also + + is_simd_flag_type checks if a type is a simd flag type + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::is_detected,std::experimental::detected_t,.3 b/man/std::experimental::is_detected,std::experimental::detected_t,.3 new file mode 100644 index 000000000..f498cb3d5 --- /dev/null +++ b/man/std::experimental::is_detected,std::experimental::detected_t,.3 @@ -0,0 +1,150 @@ +.TH std::experimental::is_detected,std::experimental::detected_t, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::is_detected,std::experimental::detected_t, \- std::experimental::is_detected,std::experimental::detected_t, + +.SH Synopsis + + Defined in header + template< template class Op, class... Args > (library fundamentals TS v2) + using is_detected = /* see below */; + template< template class Op, class... Args > (library fundamentals TS v2) + using detected_t = /* see below */; + template< class Default, template class Op, + class... Args > (library fundamentals TS v2) + using detected_or = /* see below */; + + The alias template detected_or is an alias for an unspecified class type with two + public member typedefs value_t and type, which are defined as follows: + + * If the template-id Op denotes a valid type, then value_t is an alias + for std::true_type, and type is an alias for Op; + * Otherwise, value_t is an alias for std::false_type and type is an alias for + Default. + + The alias template is_detected is equivalent to typename + detected_or::value_t. It is an alias for + std::true_type if the template-id Op denotes a valid type; otherwise it is + an alias for std::false_type. + + The alias template detected_t is equivalent to typename + detected_or::type. It is an alias for + Op if that template-id denotes a valid type; otherwise it is an alias for + the class std::experimental::nonesuch. + + Additional utilities + + template< template class Op, class... Args > (library fundamentals TS + constexpr bool is_detected_v = is_detected::value; + template< template class Op, class... Args > (library fundamentals TS + constexpr inline bool is_detected_v = is_detected::value; + template< class Default, template class Op, + class... Args > (library fundamentals TS + using detected_or_t = typename detected_or::type; + template< class Expected, template class Op, + class... Args > (library fundamentals TS + using is_detected_exact = std::is_same>; + template< class Expected, template class Op, + class... Args > + (library fundamentals TS + constexpr bool is_detected_exact_v = v2) + + is_detected_exact::value; + template< class Expected, template class Op, + class... Args > + (library fundamentals TS + constexpr inline bool is_detected_exact_v = v3) + + is_detected_exact::value; + template< class To, template class Op, class... + Args > + (library fundamentals TS + using is_detected_convertible = v2) + + std::is_convertible, To>; + template< class To, template class Op, class... + Args > + (library fundamentals TS + constexpr bool is_detected_convertible_v = v2) + + is_detected_convertible::value; + template< class To, template class Op, class... + Args > + (library fundamentals TS + constexpr inline bool is_detected_convertible_v = v3) + + is_detected_convertible::value; + + The alias template is_detected_exact checks whether detected_t is + Expected. + + The alias template is_detected_convertible checks whether detected_t is + convertible to To. + +.SH Possible implementation + + namespace detail + { + template class Op, class... Args> + struct detector + { + using value_t = std::false_type; + using type = Default; + }; + + template class Op, class... Args> + struct detector>, Op, Args...> + { + using value_t = std::true_type; + using type = Op; + }; + } // namespace detail + + template class Op, class... Args> + using is_detected = typename detail::detector::value_t; + + template class Op, class... Args> + using detected_t = typename detail::detector::type; + + template class Op, class... Args> + using detected_or = detail::detector; + +.SH Example + + +// Run this code + + #include + #include + + template + using copy_assign_t = decltype(std::declval() = std::declval()); + + struct Meow {}; + struct Purr { void operator=(const Purr&) = delete; }; + + static_assert(std::experimental::is_detected::value, + "Meow should be copy assignable!"); + static_assert(!std::experimental::is_detected_v, + "Purr should not be copy assignable!"); + static_assert(std::experimental::is_detected_exact_v, + "Copy assignment of Meow should return Meow&!"); + + template + using diff_t = typename T::difference_type; + + template + using difference_type = std::experimental::detected_or_t; + + struct Woof { using difference_type = int; }; + struct Bark {}; + + static_assert(std::is_same, int>::value, + "Woof's difference_type should be int!"); + static_assert(std::is_same, std::ptrdiff_t>::value, + "Bark's difference_type should be ptrdiff_t!"); + + int main() {} diff --git a/man/std::experimental::is_simd,std::experimental::is_simd_mask.3 b/man/std::experimental::is_simd,std::experimental::is_simd_mask.3 new file mode 100644 index 000000000..50dc0d86c --- /dev/null +++ b/man/std::experimental::is_simd,std::experimental::is_simd_mask.3 @@ -0,0 +1,119 @@ +.TH std::experimental::is_simd,std::experimental::is_simd_mask 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::is_simd,std::experimental::is_simd_mask \- std::experimental::is_simd,std::experimental::is_simd_mask + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP (parallelism TS v2) + struct is_simd; + template< class T > \fB(2)\fP (parallelism TS v2) + struct is_simd_mask; + + 1) If T is a specialization of the simd class template, provides the member constant + value equal true. For any other type, value is false. + 2) If T is a specialization of the simd_mask class template, provides the member + constant value equal true. For any other type, value is false. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > (parallelism TS v2) + inline constexpr bool is_simd_v = is_simd::value; + template< class T > (parallelism TS v2) + inline constexpr bool is_simd_mask_v = is_simd_mask::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is a simd/simd_mask type, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + is_simd_v is necessary but not sufficient for testing whether T can be used as a + SIMD type. For example, is_simd_v> is true, even though bool is not + included in the permissible vectorizable types. The missing condition is + std::is_constructible_v, which is false for simd. + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace stdx = std::experimental; + + template + void test_simd(std::string_view type_name) + { + std::cout << std::boolalpha + << "Type: " << type_name << '\\n' + << " is_simd: " << stdx::is_simd_v << '\\n' + << " is_constructible: " << std::is_constructible_v << '\\n'; + } + + template + void test_simd_mask(std::string_view type_name) + { + std::cout << std::boolalpha + << "Type: " << type_name << '\\n' + << " is_simd_mask: " << stdx::is_simd_mask_v << '\\n' + << " is_constructible: " << std::is_constructible_v << "\\n\\n"; + } + + int main() + { + test_simd("int"); + test_simd_mask("int"); + + test_simd>("simd"); + test_simd_mask>("simd_mask"); + + test_simd>("simd"); + test_simd_mask>("simd_mask"); + } + +.SH Output: + + Type: int + is_simd: false + is_constructible: true + Type: int + is_simd_mask: false + is_constructible: true + + Type: simd + is_simd: true + is_constructible: true + Type: simd_mask + is_simd_mask: true + is_constructible: true + + Type: simd + is_simd: true + is_constructible: false + Type: simd_mask + is_simd_mask: true + is_constructible: false diff --git a/man/std::experimental::is_simd_flag_type.3 b/man/std::experimental::is_simd_flag_type.3 new file mode 100644 index 000000000..9701fe988 --- /dev/null +++ b/man/std::experimental::is_simd_flag_type.3 @@ -0,0 +1,70 @@ +.TH std::experimental::is_simd_flag_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::is_simd_flag_type \- std::experimental::is_simd_flag_type + +.SH Synopsis + Defined in header + template< class T > (parallelism TS v2) + struct is_simd_flag_type; + + If T is a valid type for the second argument to copy_from, copy_to or the + corresponding load constructors of simd or simd_mask, provides the member constant + value equal true. For any other type, value is false. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + inline constexpr bool is_simd_flag_type_v = (parallelism TS v2) + is_simd_flag_type::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is a load/store flag tag type, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + namespace stdx = std::experimental; + std::cout << std::boolalpha + << stdx::is_simd_flag_type_v << '\\n' + << stdx::is_simd_flag_type_v << '\\n'; + } + +.SH Output: + + true + false + +.SH See also + + is_abi_tag checks if a type is an ABI tag type + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::latch.3 b/man/std::experimental::latch.3 new file mode 100644 index 000000000..03f793def --- /dev/null +++ b/man/std::experimental::latch.3 @@ -0,0 +1,33 @@ +.TH std::experimental::latch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch \- std::experimental::latch + +.SH Synopsis + Defined in header + class latch; (concurrency TS) + + The latch class is a downward counter of type ptrdiff_t which can be used to + synchronize threads. The value of the counter is initialized on creation. Threads + may block on the latch until the counter is decremented to zero. There is no + possibility to increase or reset the counter, which makes the latch a single-use + barrier. + + Unlike std::experimental::barrier, std::experimental::latch can be decremented by a + participating thread more than once. + +.SH Member functions + + constructor constructs a latch + \fI(public member function)\fP + destructor destroys the latch + \fI(public member function)\fP + operator= not copy-assignable + [deleted] \fI(public member function)\fP + count_down_and_wait decrements the counter by 1 and blocks until it reaches zero + \fI(public member function)\fP + count_down decrements the counter in a non-blocking manner + \fI(public member function)\fP + is_ready tests if the internal counter equals zero + \fI(public member function)\fP + wait blocks until the counter reaches zero + \fI(public member function)\fP diff --git a/man/std::experimental::latch::count_down.3 b/man/std::experimental::latch::count_down.3 new file mode 100644 index 000000000..a9133204c --- /dev/null +++ b/man/std::experimental::latch::count_down.3 @@ -0,0 +1,26 @@ +.TH std::experimental::latch::count_down 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch::count_down \- std::experimental::latch::count_down + +.SH Synopsis + void count_down( ptrdiff_t n = 1 ); \fB(1)\fP (concurrency TS) + + Atomically decrements the internal counter by n without blocking the caller. + + If n is greater than the value of the internal counter or is negative, the behavior + is undefined. + + This operation synchronizes with all calls that block on this latch and all is_ready + calls on this latch that returns true. + +.SH Parameters + + n - the value by which the internal counter is decreased + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. diff --git a/man/std::experimental::latch::count_down_and_wait.3 b/man/std::experimental::latch::count_down_and_wait.3 new file mode 100644 index 000000000..10e416e13 --- /dev/null +++ b/man/std::experimental::latch::count_down_and_wait.3 @@ -0,0 +1,26 @@ +.TH std::experimental::latch::count_down_and_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch::count_down_and_wait \- std::experimental::latch::count_down_and_wait + +.SH Synopsis + void count_down_and_wait(); \fB(1)\fP (concurrency TS) + + Atomically decrements the internal counter by 1 and (if necessary) blocks the + calling thread until the counter reaches zero. + + The behavior is undefined if the internal counter is already zero. + + This operation synchronizes with all calls that block on this latch and all is_ready + calls on this latch that returns true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. diff --git a/man/std::experimental::latch::is_ready.3 b/man/std::experimental::latch::is_ready.3 new file mode 100644 index 000000000..465125b08 --- /dev/null +++ b/man/std::experimental::latch::is_ready.3 @@ -0,0 +1,16 @@ +.TH std::experimental::latch::is_ready 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch::is_ready \- std::experimental::latch::is_ready + +.SH Synopsis + bool is_ready() const noexcept; \fB(1)\fP (concurrency TS) + + Returns true if the internal counter equals zero. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the internal counter of *this latch equals zero. diff --git a/man/std::experimental::latch::latch.3 b/man/std::experimental::latch::latch.3 new file mode 100644 index 000000000..c390d2361 --- /dev/null +++ b/man/std::experimental::latch::latch.3 @@ -0,0 +1,14 @@ +.TH std::experimental::latch::latch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch::latch \- std::experimental::latch::latch + +.SH Synopsis + explicit latch( ptrdiff_t value ); \fB(1)\fP (concurrency TS) + latch( const latch & ) = delete; \fB(2)\fP (concurrency TS) + + 1) Constructs a latch and initializes its internal counter. + 2) Copy constructor is deleted. latch is not copyable. + +.SH Parameters + + value - the initial value of the internal counter; must be non-negative diff --git a/man/std::experimental::latch::wait.3 b/man/std::experimental::latch::wait.3 new file mode 100644 index 000000000..97fddf3bb --- /dev/null +++ b/man/std::experimental::latch::wait.3 @@ -0,0 +1,21 @@ +.TH std::experimental::latch::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch::wait \- std::experimental::latch::wait + +.SH Synopsis + void wait() const; \fB(1)\fP (concurrency TS) + + Blocks the calling thread until the internal counter reaches 0. If it is zero + already, returns immediately. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. diff --git a/man/std::experimental::latch::~latch.3 b/man/std::experimental::latch::~latch.3 new file mode 100644 index 000000000..c45f88dcc --- /dev/null +++ b/man/std::experimental::latch::~latch.3 @@ -0,0 +1,19 @@ +.TH std::experimental::latch::~latch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::latch::~latch \- std::experimental::latch::~latch + +.SH Synopsis + ~latch(); (concurrency TS) + + Destroys the latch. + + The behavior is undefined if a thread is blocked at the synchronization point. + + The destructor may be called even if not all threads have returned from wait() or + count_down_and_wait(), provided the internal counter must equal zero. + + The destructor may block until all threads have returned from the blocking + functions. + + No thread is allowed to block on this latch after one thread has invoked the + destructor. diff --git a/man/std::experimental::lcm.3 b/man/std::experimental::lcm.3 new file mode 100644 index 000000000..5da939c55 --- /dev/null +++ b/man/std::experimental::lcm.3 @@ -0,0 +1,37 @@ +.TH std::experimental::lcm 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::lcm \- std::experimental::lcm + +.SH Synopsis + Defined in header + template< class M, class N > (library fundamentals TS v2) + constexpr std::common_type_t lcm( M m, N n ); + + Computes the least common multiple of the integers m and n. + +.SH Parameters + + m, n - integer values + +.SH Return value + + If either m or n is zero, returns zero. Otherwise, return the least common multiple + of |m| and |n|. + + Remarks + + If either M or N is not an integer type, or if either is (possibly cv-qualified) + bool, the program is ill-formed. + + The behavior is undefined if |m|, |n| or the least common multiple of |m| and |n| is + not representable as a value of type std::common_type_t. + +.SH Exceptions + + Throws no exceptions. + +.SH See also + + constexpr function template returning the greatest common divisor of two + gcd integers + \fI(function template)\fP diff --git a/man/std::experimental::make_array.3 b/man/std::experimental::make_array.3 new file mode 100644 index 000000000..0e44d41b9 --- /dev/null +++ b/man/std::experimental::make_array.3 @@ -0,0 +1,81 @@ +.TH std::experimental::make_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_array \- std::experimental::make_array + +.SH Synopsis + Defined in header + template< class D = void, class... Types > + constexpr std::array make_array( Types&&... t ); + + Creates a std::array whose size is equal to the number of arguments and whose + elements are initialized from the corresponding arguments. Returns std::array{std::forward(t)...}. + + If D is void, then the deduced type VT is std::common_type_t. Otherwise, + it is D. + + If D is void and any of std::decay_t... is a specialization of + std::reference_wrapper, the program is ill-formed. + +.SH Notes + + make_array is removed in Library Fundamentals TS v3 because the deduction guide for + std::array and std::to_array have been already in C++20. + +.SH Possible implementation + +namespace details +{ + template struct is_ref_wrapper : std::false_type{}; + template struct is_ref_wrapper> : std::true_type{}; + + template + using not_ref_wrapper = std::negation>>; + + template struct return_type_helper { using type = D; }; + template + struct return_type_helper : std::common_type + { + static_assert(std::conjunction_v...>, + "Types cannot contain reference_wrappers when D is void"); + }; + + template + using return_type = std::array::type, + sizeof...(Types)>; +} + +template +constexpr details::return_type make_array(Types&&... t) +{ + return {std::forward(t)...}; +} + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto arr = std::experimental::make_array(1, 2, 3, 4, 5); + bool is_array_of_5_ints = std::is_same>::value; + std::cout << "Returns an array of five ints? "; + std::cout << std::boolalpha << is_array_of_5_ints << '\\n'; + } + +.SH Output: + + Returns an array of five ints? true + +.SH See also + + C++ documentation for + std::array deduction guides + to_array creates a std::array object from a built-in array + \fI(function template)\fP diff --git a/man/std::experimental::make_exceptional_future.3 b/man/std::experimental::make_exceptional_future.3 new file mode 100644 index 000000000..a25ee4388 --- /dev/null +++ b/man/std::experimental::make_exceptional_future.3 @@ -0,0 +1,29 @@ +.TH std::experimental::make_exceptional_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_exceptional_future \- std::experimental::make_exceptional_future + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP (concurrency TS) + future make_exceptional_future( std::exception_ptr ex ); + template< class T, class E > \fB(2)\fP (concurrency TS) + future make_exceptional_future( E ex ); + + 1) Creates a shared state of type T that is immediately ready and stores the + exception pointer ex, then return a future associated with that shared state, as if + by promise p; p.set_exception(ex); return p.get_future();. The behavior is + undefined if ex is null. + 2) Creates a shared state of type T that is immediately ready and stores an + exception pointer created from ex, then return a future associated with that shared + state, as if by promise p; p.set_exception(std::make_exception_ptr(ex)); return + p.get_future();. + +.SH Return value + + A future object associated with the shared state that was created. + +.SH See also + + make_ready_future produces a future that is ready immediately and holds the given + (concurrency TS) value + \fI(function template)\fP diff --git a/man/std::experimental::make_observer.3 b/man/std::experimental::make_observer.3 new file mode 100644 index 000000000..0d6b06a4c --- /dev/null +++ b/man/std::experimental::make_observer.3 @@ -0,0 +1,28 @@ +.TH std::experimental::make_observer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_observer \- std::experimental::make_observer + +.SH Synopsis + Defined in header + template< class W > (library fundamentals TS + std::experimental::observer_ptr make_observer( W* p ) v2) + noexcept; + + Creates an observer_ptr object, deducing the template argument from the type of the + function argument. + +.SH Parameters + + p - pointer to the object to be watched by the observer_ptr object + +.SH Return value + + A observer_ptr object, created as if by std::experimental::observer_ptr(p). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::make_optional.3 b/man/std::experimental::make_optional.3 new file mode 100644 index 000000000..599580f43 --- /dev/null +++ b/man/std::experimental::make_optional.3 @@ -0,0 +1,34 @@ +.TH std::experimental::make_optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_optional \- std::experimental::make_optional + +.SH Synopsis + Defined in header + template< class T > + + constexpr optional::type> (library fundamentals TS) + + make_optional( T&& value ); + + Creates an optional object from value. Effectively calls optional::type>(std::forward(value)). + +.SH Parameters + + value - the value to construct optional object with + +.SH Return value + + An optional object with value as the contained value. + +.SH Exceptions + + Throws any exception thrown by the constructor of T. + +.SH See also + + constructor constructs the optional object + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::make_ostream_joiner.3 b/man/std::experimental::make_ostream_joiner.3 new file mode 100644 index 000000000..6658ad30d --- /dev/null +++ b/man/std::experimental::make_ostream_joiner.3 @@ -0,0 +1,47 @@ +.TH std::experimental::make_ostream_joiner 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_ostream_joiner \- std::experimental::make_ostream_joiner + +.SH Synopsis + Defined in header + template< class CharT, class Traits, class DelimT > + + std::experimental::ostream_joiner, CharT, (library + Traits> fundamentals TS + make_ostream_joiner( std::basic_ostream& os, v2) + + DelimT&& delimiter ); + + Creates an ostream_joiner object, deducing the template arguments from the types of + the function arguments. + +.SH Parameters + + os - the basic_ostream object that the iterator is to be associated to + delimiter - the delimiter + +.SH Return value + + An ostream_joiner object, created as if by + std::experimental::ostream_joiner, CharT, Traits>(os, + std::forward(delimiter)) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector x{1, 2, 3, 4}; + std::copy(x.begin(), x.end(), + std::experimental::make_ostream_joiner(std::cout, ", ")); + } + +.SH Output: + + 1, 2, 3, 4 diff --git a/man/std::experimental::make_ready_future.3 b/man/std::experimental::make_ready_future.3 new file mode 100644 index 000000000..9a7bbb4fd --- /dev/null +++ b/man/std::experimental::make_ready_future.3 @@ -0,0 +1,27 @@ +.TH std::experimental::make_ready_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_ready_future \- std::experimental::make_ready_future + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP (concurrency TS) + future make_ready_future( T&& value ); + future make_ready_future(); \fB(2)\fP (concurrency TS) + + 1) If std::decay_t is std::reference_wrapper, then the type V is X&, + otherwise, V is std::decay_t. + Creates a shared state of type V that is immediately ready, with the result + constructed from std::forward(value), then returns a std::experimental::future + associated with that shared state. + 2) Creates a shared state of type void that is immediately ready, then returns a + std::experimental::future associated with that shared state. + +.SH Return value + + A std::experimental::future associated with the shared state that is created. + +.SH See also + + make_exceptional_future produces a future that is ready immediately and holds the + (concurrency TS) given exception + \fI(function template)\fP diff --git a/man/std::experimental::make_unique_resource_checked.3 b/man/std::experimental::make_unique_resource_checked.3 new file mode 100644 index 000000000..fcfc39f17 --- /dev/null +++ b/man/std::experimental::make_unique_resource_checked.3 @@ -0,0 +1,75 @@ +.TH std::experimental::make_unique_resource_checked 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::make_unique_resource_checked \- std::experimental::make_unique_resource_checked + +.SH Synopsis + Defined in header + template< class R, class D, class S = std::decay_t > + + std::experimental::unique_resource, + std::decay_t> (library + make_unique_resource_checked( R&& r, const S& invalid, D&& fundamentals TS v3) + d ) + + noexcept(/*see below*/); + + Creates a unique_resource, initializes its stored resource handle is initialized + with std::forward(r) and its deleter with std::forward(d). The created + unique_resource owns the resource if and only if bool(r == invalid) is false. + + The program is ill-formed if the expression r == invalid cannot be contextually + converted to bool, and the behavior is undefined if the conversion results in + undefined behavior or throws an exception. + +.SH Exceptions + + Any exception thrown in initialization of the stored resource handle and the + deleter. + + noexcept specification: + noexcept( + + std::is_nothrow_constructible_v, R> && + std::is_nothrow_constructible_v, D> + + ) + +.SH Notes + + make_unique_resource_checked exists to avoid calling a deleter function with an + invalid argument. + + Resource handle r is either copied or moved into the return value, and the created + unique_resource always holds an underlying resource handle with object type. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // avoid calling fclose when fopen fails + auto file = std::experimental::make_unique_resource_checked( + std::fopen("potentially_nonexistent_file.txt", "r"), + nullptr, + [](std::FILE *fptr) { std::fclose(fptr); } + ); + if (file.get()) + std::puts("The file exits."); + else + std::puts("The file does not exist."); + } + +.SH Possible output: + + The file does not exist. + +.SH See also + + +.SH Category: + * conditionally noexcept diff --git a/man/std::experimental::max.3 b/man/std::experimental::max.3 new file mode 100644 index 000000000..19dc76a70 --- /dev/null +++ b/man/std::experimental::max.3 @@ -0,0 +1,29 @@ +.TH std::experimental::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::max \- std::experimental::max + +.SH Synopsis + Defined in header + template< class T, class Abi > + simd max( const simd& a, const simd& b (parallelism TS v2) + ) noexcept; + +.SH Parameters + + a - the first vector of elements for max + b - the second vector of elements for max + +.SH Return value + + The result of binary element-wise application of std::max(a[i], b[i]) for all i ∈ + [0, size()). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + +.SH Category: + * Todo no example diff --git a/man/std::experimental::memory_alignment.3 b/man/std::experimental::memory_alignment.3 new file mode 100644 index 000000000..ef80d9774 --- /dev/null +++ b/man/std::experimental::memory_alignment.3 @@ -0,0 +1,68 @@ +.TH std::experimental::memory_alignment 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::memory_alignment \- std::experimental::memory_alignment + +.SH Synopsis + Defined in header + template< class T, class U = typename T::value_type > (parallelism TS v2) + struct memory_alignment; + + If is_simd_mask_v is true and U is bool, or if is_simd_v is true and U is a + vectorizable type, provides the member constant value equal to the minimum alignment + of a pointer passed to a load constructor, copy_from function, or copy_to function. + For any other types T and U, there is no member value. + + If the program adds specializations for std::memory_alignment + or std::memory_alignment_v + \fI(since C++17)\fP, the behavior is undefined. + +.SH Member constants + + value the minimum alignment of a pointer passed to a load constructor, copy_from + \fB[static]\fP function, or copy_to function + \fI(public static member constant)\fP + +.SH Member functions + + operator std::size_t converts the object to std::size_t, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type std::size_t + type std::integral_constant< std::size_t, value> + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + constructor constructs a simd object + (parallelism TS v2) \fI(public member function of std::experimental::simd)\fP + + copy_from loads simd elements from contiguous memory + (parallelism TS v2) \fI(public member function of std::experimental::simd)\fP + + copy_to stores simd elements to contiguous memory + (parallelism TS v2) \fI(public member function of std::experimental::simd)\fP + + constructor constructs a simd_mask object + (parallelism TS v2) \fI(public member function of std::experimental::simd_mask)\fP + + copy_from loads simd_mask elements from contiguous memory + (parallelism TS v2) \fI(public member function of std::experimental::simd_mask)\fP + + copy_to stores simd_mask elements to contiguous memory + (parallelism TS v2) \fI(public member function of std::experimental::simd_mask)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::experimental::min.3 b/man/std::experimental::min.3 new file mode 100644 index 000000000..cdf188200 --- /dev/null +++ b/man/std::experimental::min.3 @@ -0,0 +1,29 @@ +.TH std::experimental::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::min \- std::experimental::min + +.SH Synopsis + Defined in header + template< class T, class Abi > + simd min( const simd& a, const simd& b (parallelism TS v2) + ) noexcept; + +.SH Parameters + + a - the first vector of elements for min + b - the second vector of elements for min + +.SH Return value + + The result of binary element-wise application of std::min(a[i], b[i]) for all i ∈ + [0, size()). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + +.SH Category: + * Todo no example diff --git a/man/std::experimental::minmax.3 b/man/std::experimental::minmax.3 new file mode 100644 index 000000000..d0a821fd9 --- /dev/null +++ b/man/std::experimental::minmax.3 @@ -0,0 +1,34 @@ +.TH std::experimental::minmax 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::minmax \- std::experimental::minmax + +.SH Synopsis + Defined in header + template< class T, class Abi > + + std::pair, simd> (parallelism TS v2) + + minmax( const simd& a, const simd& b ) + noexcept; + + Returns both the element-wise min result and element-wise max result. + +.SH Parameters + + a - the first vector of elements for minmax + b - the second vector of elements for minmax + +.SH Return value + + An object r, where the i^th element of r.first is std::min(a[i], b[i]), and the i^th + element of r.second is std::max(a[i], b[i]). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + +.SH Category: + * Todo no example diff --git a/man/std::experimental::negation.3 b/man/std::experimental::negation.3 new file mode 100644 index 000000000..7d514323c --- /dev/null +++ b/man/std::experimental::negation.3 @@ -0,0 +1,63 @@ +.TH std::experimental::negation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::negation \- std::experimental::negation + +.SH Synopsis + Defined in header + template< class B > \fB(1)\fP (library fundamentals TS v2) + struct negation; + + Forms the logical negation of the type trait B. + + The type negation is a UnaryTypeTrait with a base characteristic of + std::integral_constant. + +.SH Template parameters + + B - any type such that the expression bool(B::value) is a valid constant expression + + Helper variable template + + template< class B > (library fundamentals TS v2) + constexpr bool negation_v = negation::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if B has a member ::value such that !bool(B::value) is true, false + \fB[static]\fP otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Possible implementation + + template + struct negation : std::integral_constant {}; + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + negation logical NOT metafunction + \fI(C++17)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::nonesuch.3 b/man/std::experimental::nonesuch.3 new file mode 100644 index 000000000..f14a0d8d6 --- /dev/null +++ b/man/std::experimental::nonesuch.3 @@ -0,0 +1,32 @@ +.TH std::experimental::nonesuch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::nonesuch \- std::experimental::nonesuch + +.SH Synopsis + Defined in header + struct nonesuch { + + ~nonesuch() = delete; + nonesuch(nonesuch const&) = delete; (library fundamentals TS v2) + void operator=(nonesuch const&) = delete; + + }; + + std::experimental::nonesuch is a class type used by std::experimental::detected_t to + indicate detection failure. + + nonesuch has no default constructor or initializer-list constructor, and is not an + aggregate. + +.SH Notes + + nonesuch cannot be constructed, destroyed, or copied. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2960 LFTSv2 nonesuch may be an aggregate and has an made non-aggregate and + implicit conversion sequence from {} removed ICS diff --git a/man/std::experimental::not_fn.3 b/man/std::experimental::not_fn.3 new file mode 100644 index 000000000..7caf67d6b --- /dev/null +++ b/man/std::experimental::not_fn.3 @@ -0,0 +1,85 @@ +.TH std::experimental::not_fn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::not_fn \- std::experimental::not_fn + +.SH Synopsis + Defined in header + template< class F> (library fundamentals TS v2) + /*unspecified*/ not_fn( F&& f ); + + Creates a forwarding call wrapper that returns the complement of the callable object + it holds. + +.SH Parameters + + f - the object from which the Callable object held by the wrapper is constructed + +.SH Return value + + Let FD be std::decay_t and fd be an lvalue of type FD constructed from + std::forward(f). + + not_fn returns a forwarding call wrapper fn of unspecified type such that fn(a1, a2, + ..., aN) is equivalent to !INVOKE(fd, a1, ..., aN), where INVOKE is the operation + described in Callable. + + The returned call wrapper is always MoveConstructible, and is CopyConstructible if + FD is CopyConstructible. + + Remarks + + If fd is not Callable, or std::is_constructible::value is not true, the + behavior is undefined. + +.SH Exceptions + + Throws no exceptions, unless the construction of fd throws. + +.SH Possible implementation + + namespace detail { + template + struct not_fn_t { + F f; + template + auto operator()(Args&&... args) + noexcept(noexcept(!std::invoke(f, std::forward(args)...))) + -> decltype(!std::invoke(f, std::forward(args)...)) { + return !std::invoke(f, std::forward(args)...); + } + + // cv-qualified overload for QoI + template + auto operator()(Args&&... args) const + noexcept(noexcept(!std::invoke(f, std::forward(args)...))) + -> decltype(!std::invoke(f, std::forward(args)...)) { + return !std::invoke(f, std::forward(args)...); + } + + template + auto operator()(Args&&... args) volatile + noexcept(noexcept(!std::invoke(f, std::forward(args)...))) + -> decltype(!std::invoke(f, std::forward(args)...)) { + return !std::invoke(f, std::forward(args)...); + } + template + auto operator()(Args&&... args) const volatile + noexcept(noexcept(!std::invoke(f, std::forward(args)...))) + -> decltype(!std::invoke(f, std::forward(args)...)) { + return !std::invoke(f, std::forward(args)...); + } + }; + } + + template + detail::not_fn_t> not_fn(F&& f) { return { std::forward(f) }; } + +.SH Notes + + not_fn is intended to replace the C++03-era negators std::not1 and std::not2. + +.SH See also + + not_fn creates a function object that returns the complement of the result of the + \fI(C++17)\fP function object it holds + \fI(function template)\fP diff --git a/man/std::experimental::nullopt.3 b/man/std::experimental::nullopt.3 new file mode 100644 index 000000000..a0d571d77 --- /dev/null +++ b/man/std::experimental::nullopt.3 @@ -0,0 +1,18 @@ +.TH std::experimental::nullopt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::nullopt \- std::experimental::nullopt + +.SH Synopsis + Defined in header + constexpr nullopt_t nullopt{/*unspecified*/}; (library fundamentals TS) + + std::experimental::nullopt is a constant of type std::experimental::nullopt_t that + is used to indicate optional type with uninitialized state. + +.SH See also + + nullopt_t indicator of optional type with uninitialized state + (library fundamentals TS) \fI(class)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::nullopt_t.3 b/man/std::experimental::nullopt_t.3 new file mode 100644 index 000000000..dae89e961 --- /dev/null +++ b/man/std::experimental::nullopt_t.3 @@ -0,0 +1,38 @@ +.TH std::experimental::nullopt_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::nullopt_t \- std::experimental::nullopt_t + +.SH Synopsis + Defined in header + struct nullopt_t; (library fundamentals TS) + + std::experimental::nullopt_t is an empty class type used to indicate optional type + with uninitialized state. In particular, std::experimental::optional has a + constructor with nullopt_t as a single argument, which creates an optional that does + not contain a value. + + std::experimental::nullopt_t must be a LiteralType and cannot have a default + constructor. + + It must have a constexpr constructor that takes some implementation-defined literal + type. + +.SH Notes + + nullopt_t is not DefaultConstructible to support both op = {}; and op = nullopt; as + the syntax for disengaging an optional object. + + A possible implementation of this class is + + struct nullopt_t + { + constexpr nullopt_t(int) {} + }; + +.SH See also + + nullopt an object of type nullopt_t + \fI(C++17)\fP (constant) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::observer_ptr.3 b/man/std::experimental::observer_ptr.3 new file mode 100644 index 000000000..a2c889ebc --- /dev/null +++ b/man/std::experimental::observer_ptr.3 @@ -0,0 +1,87 @@ +.TH std::experimental::observer_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr \- std::experimental::observer_ptr + +.SH Synopsis + Defined in header + template< class W > (library fundamentals TS v2) + class observer_ptr; + + std::experimental::observer_ptr is a non-owning pointer, or observer. The observer + stores a pointer to a second object, known as the watched object. An observer_ptr + may also have no watched object. + + An observer is not responsible in any way for the watched object; there is no + inherent relationship between an observer and the object it watches. + + It is intended as a near drop-in replacement for raw pointer types, with the + advantage that, as a vocabulary type, it indicates its intended use without need for + detailed analysis by code readers. + + Specializations of observer_ptr satisfy the requirements of CopyConstructible and + CopyAssignable. + +.SH Type requirements + - + W shall not be a reference type, but may be an incomplete type. + +.SH Member types + + Member type Definition + element_type W, the type of the object watched by this observer_ptr + +.SH Member functions + + constructor constructs a new observer_ptr + \fI(public member function)\fP + destructor destructs an observer_ptr + (implicitly declared) \fI(public member function)\fP + operator= implicitly declared copy and move assignment operators that + (implicitly declared) assign the stored pointer + \fI(public member function)\fP +.SH Modifiers + returns a pointer to the watched object and stops watching + release the object + \fI(public member function)\fP + reset replaces the watched object + \fI(public member function)\fP + swap swaps the watched objects + \fI(public member function)\fP +.SH Observers + get returns a pointer to the watched object + \fI(public member function)\fP + operator bool checks if there is an associated watched object + \fI(public member function)\fP + operator* dereferences pointer to the watched object + operator-> \fI(public member function)\fP +.SH Conversions + operator element_type* explicit conversion function to the stored pointer + \fI(public member function)\fP + +.SH Non-member functions + + creates an observer_ptr + make_observer that watches an object + \fI(function template)\fP + operator== + operator!= compares to another + operator< observer_ptr or with + operator<= nullptr + operator> \fI(function template)\fP + operator>= + specializes the swap + std::experimental::swap(std::experimental::observer_ptr) algorithm + \fI(function template)\fP + +.SH Helper classes + + std::hash hash support for observer_ptr + \fI(class template specialization)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::get.3 b/man/std::experimental::observer_ptr::get.3 new file mode 100644 index 000000000..a76dc9f28 --- /dev/null +++ b/man/std::experimental::observer_ptr::get.3 @@ -0,0 +1,29 @@ +.TH std::experimental::observer_ptr::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::get \- std::experimental::observer_ptr::get + +.SH Synopsis + constexpr element_type* get() const noexcept; (library fundamentals TS v2) + + Returns a pointer to the watched object or nullptr if no object is watched. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the watched object or nullptr if no object is watched. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + release returns a pointer to the watched object and stops watching the object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::observer_ptr.3 b/man/std::experimental::observer_ptr::observer_ptr.3 new file mode 100644 index 000000000..1728ee1df --- /dev/null +++ b/man/std::experimental::observer_ptr::observer_ptr.3 @@ -0,0 +1,28 @@ +.TH std::experimental::observer_ptr::observer_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::observer_ptr \- std::experimental::observer_ptr::observer_ptr + +.SH Synopsis + constexpr observer_ptr() noexcept; \fB(1)\fP (library fundamentals TS v2) + constexpr observer_ptr( nullptr_t ) noexcept; + constexpr explicit observer_ptr( element_type* p ) \fB(2)\fP (library fundamentals TS v2) + noexcept; + template< class W2 > + constexpr observer_ptr( observer_ptr other ) \fB(3)\fP (library fundamentals TS v2) + noexcept; + observer_ptr( const observer_ptr& other ) = \fB(4)\fP (library fundamentals TS v2) + default; (implicitly declared) + observer_ptr( observer_ptr&& other ) = default; \fB(5)\fP (library fundamentals TS v2) + (implicitly declared) + + 1) Constructs an observer_ptr that has no corresponding watched object. + 2) Constructs an observer_ptr that watches p. + 3) Constructs an observer_ptr that watches other.get(). This overload participates + in overload resolution only if W2* is convertible to element_type*. + 4,5) Implicitly declared copy and move constructors. Constructs an observer_ptr that + watches other.get(). + +.SH Parameters + + p - a pointer to an object to watch + other - another observer_ptr to copy from diff --git a/man/std::experimental::observer_ptr::operator*,.3 b/man/std::experimental::observer_ptr::operator*,.3 new file mode 100644 index 000000000..80dc4fc82 --- /dev/null +++ b/man/std::experimental::observer_ptr::operator*,.3 @@ -0,0 +1,41 @@ +.TH std::experimental::observer_ptr::operator*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::operator*, \- std::experimental::observer_ptr::operator*, + +.SH Synopsis + + constexpr std::add_lvalue_reference_t \fB(1)\fP (library fundamentals + operator*() const; TS v2) + constexpr element_type* operator->() const noexcept; \fB(2)\fP (library fundamentals + TS v2) + + operator* and operator-> provide access to the object watched by *this. + + The behavior of operator* is undefined if get() == nullptr. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Returns the object watched by *this, equivalent to *get(). + + 2) Returns a pointer to the object watched by *this, i.e. get(). + +.SH Exceptions + + 1) Throws nothing. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the watched object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::operatorbool.3 b/man/std::experimental::observer_ptr::operatorbool.3 new file mode 100644 index 000000000..334802a8b --- /dev/null +++ b/man/std::experimental::observer_ptr::operatorbool.3 @@ -0,0 +1,30 @@ +.TH std::experimental::observer_ptr::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::operatorbool \- std::experimental::observer_ptr::operatorbool + +.SH Synopsis + constexpr explicit operator bool() const noexcept; (library fundamentals TS v2) + + Checks whether *this has an associated watched object, i.e. whether get() != + nullptr. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if *this has an associated watched object, false otherwise. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the watched object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::operatorelement_type*.3 b/man/std::experimental::observer_ptr::operatorelement_type*.3 new file mode 100644 index 000000000..2091e54ce --- /dev/null +++ b/man/std::experimental::observer_ptr::operatorelement_type*.3 @@ -0,0 +1,30 @@ +.TH std::experimental::observer_ptr::operatorelement_type* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::operatorelement_type* \- std::experimental::observer_ptr::operatorelement_type* + +.SH Synopsis + constexpr explicit operator element_type*() const (library fundamentals TS v2) + noexcept; + + Provides an explicit conversion to the type of the stored pointer. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the watched object, i.e., get(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the watched object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::release.3 b/man/std::experimental::observer_ptr::release.3 new file mode 100644 index 000000000..163f9a40d --- /dev/null +++ b/man/std::experimental::observer_ptr::release.3 @@ -0,0 +1,32 @@ +.TH std::experimental::observer_ptr::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::release \- std::experimental::observer_ptr::release + +.SH Synopsis + constexpr element_type* release() noexcept; (library fundamentals TS v2) + + Stop watching the watched object, if any. get() returns nullptr after the call. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the previously watched object, or nullptr if there was no watched + object, i.e. the value which would be returned by get() before the call. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the watched object + \fI(public member function)\fP + reset replaces the watched object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::reset.3 b/man/std::experimental::observer_ptr::reset.3 new file mode 100644 index 000000000..24240d50e --- /dev/null +++ b/man/std::experimental::observer_ptr::reset.3 @@ -0,0 +1,26 @@ +.TH std::experimental::observer_ptr::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::reset \- std::experimental::observer_ptr::reset + +.SH Synopsis + constexpr void reset( element_type* p = nullptr ) (library fundamentals TS v2) + noexcept; + + Set *this to watch the object pointed to by p. get() returns p after the call. + +.SH Parameters + + ptr - pointer to a new object to watch + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + release returns a pointer to the watched object and stops watching the object + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::observer_ptr::swap.3 b/man/std::experimental::observer_ptr::swap.3 new file mode 100644 index 000000000..5b7d0028e --- /dev/null +++ b/man/std::experimental::observer_ptr::swap.3 @@ -0,0 +1,25 @@ +.TH std::experimental::observer_ptr::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::observer_ptr::swap \- std::experimental::observer_ptr::swap + +.SH Synopsis + constexpr void swap( observer_ptr& other ) noexcept; (library fundamentals TS v2) + + Swaps the watched object of *this and another observer_ptr object other, by invoking + swap on the stored pointers of *this and other. + +.SH Parameters + + other - another observer_ptr object to swap the watched object with + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::optional.3 b/man/std::experimental::optional.3 index 862c4a4d0..85f69e311 100644 --- a/man/std::experimental::optional.3 +++ b/man/std::experimental::optional.3 @@ -1,45 +1,49 @@ -.TH std::experimental::optional 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional \- std::experimental::optional + .SH Synopsis - Defined in header - template< class T > (library fundamentals TS) + Defined in header + template< class T > (library fundamentals TS) class optional; The class template std::experimental::optional manages an optional contained value, - i.e. a value that semantically may not be present. + i.e. a value that may or may not be present. A common use case for optional is the return value of a function that may fail. As opposed to other approaches, such as std::pair, optional handles expensive to construct objects well and is more readable, as the intent is expressed explicitly. - The value is guaranteed to be allocated within the optional object itself, i.e. no - dynamic memory allocation ever takes place. Thus, an optional object models an - object, not a pointer, even though the operator*() and operator->() are defined. + Any instance of optional at any given point in time either contains a value or + does not contain a value. - The value inside an optional object may be in either an initialized or uninitialized - state. An optional object with a value in initialized state is called engaged, - whereas if the value is in uninitialized state, the object is called disengaged. + If an optional contains a value, the value is guaranteed to be allocated as part + of the optional object footprint, i.e. no dynamic memory allocation ever takes + place. Thus, an optional object models an object, not a pointer, even though the + operator*() and operator->() are defined. - The optional object is engaged on the following conditions: + When an object of type optional is contextually converted to bool, the conversion + returns true if the object contains a value and false if it does not contain a + value. - * The object is initialized with a value of type T + The optional object contains a value in the following conditions: - * The object is assigned an engaged optional. + * The object is initialized with a value of type T. + * The object is assigned from another optional that contains a value. - The object is disengaged on the following conditions: + The object does not contain a value in the following conditions: * The object is default-initialized. - - * The object is initialized with a value of std::experimental::nullopt_t or a - disengaged optional object. - - * The object is assigned a value of std::experimental::nullopt_t or a disengaged - optional. + * The object is initialized with a value of std::experimental::nullopt_t or an + optional object that does not contain a value. + * The object is assigned from a value of std::experimental::nullopt_t or from an + optional that does not contain a value. .SH Template parameters T - the type of the value to manage initialization state for. The type must meet the - requirements of Destructible + requirements of Destructible. .SH Member types @@ -49,36 +53,65 @@ .SH Member functions constructor constructs the optional object - \fI(public member function)\fP - destructor if engaged, destroys the contained value - \fI(public member function)\fP + \fI(public member function)\fP + destructor destroys the contained value, if there is one + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers operator-> accesses the contained value - operator* \fI(public member function)\fP - operator bool checks whether the object is in engaged state - \fI(public member function)\fP + operator* \fI(public member function)\fP + operator bool checks whether the object contains a value + \fI(public member function)\fP value returns the contained value - \fI(public member function)\fP - value_or returns the contained value if engaged, another value otherwise - \fI(public member function)\fP + \fI(public member function)\fP + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP .SH Modifiers swap exchanges the contents - \fI(public member function)\fP + \fI(public member function)\fP emplace constructs the contained value in-place - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Member objects + + Member name Definition + val (private) pointer to the contained value (which points at a data member of the + same object), the name is for exposition only .SH Non-member functions - operator== compares optional objects - operator< \fI(function template)\fP + operator== + operator!= + operator< compares optional objects + operator<= \fI(function template)\fP + operator> + operator>= make_optional creates an optional object - \fI(function template)\fP + \fI(function template)\fP std::swap(std::experimental::optional) specializes the std::swap algorithm - \fI(function)\fP + \fI(function)\fP .SH Helper classes std::hash specializes the std::hash algorithm - \fI(class template specialization)\fP + \fI(class template specialization)\fP + nullopt_t indicator of optional type with uninitialized + (library fundamentals TS) state + \fI(class)\fP + in_place_t disambiguation tag type for in-place + (library fundamentals TS) construction of optional types + \fI(class)\fP + bad_optional_access exception indicating checked access to an + (library fundamentals TS) optional that doesn't contain a value + \fI(class)\fP + + Helper objects + + nullopt an object of type nullopt_t + (library fundamentals TS) \fI(function)\fP + in_place an object of type std::experimental::in_place_t + (library fundamentals TS) \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::optional::emplace.3 b/man/std::experimental::optional::emplace.3 index a860650d8..f1ecc7910 100644 --- a/man/std::experimental::optional::emplace.3 +++ b/man/std::experimental::optional::emplace.3 @@ -1,4 +1,7 @@ -.TH std::experimental::optional::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::emplace \- std::experimental::optional::emplace + .SH Synopsis template< class... Args > (library fundamentals TS) void emplace( Args&&... args ); @@ -6,13 +9,15 @@ void emplace( std::initializer_list ilist, Args&&... (library fundamentals TS) args ); - Constructs the contained value in-place. If *this is in engaged state before the - call, the contained value is destroyed by calling its destructor. + Constructs the contained value in-place. If *this already contains a value before + the call, the contained value is destroyed by calling its destructor. - 1) Initializes the contained value by calling its constructor with args... as - parameters. - 2) Initializes the contained value by calling its constructor with ilist and args... - as parameters. + 1) Initializes the contained value by direct-initializing (but not + direct-list-initializing) with std::forward(args)... as parameters. + 2) Initializes the contained value by calling its constructor with ilist, + std::forward(args)... as parameters. This overload participates in overload + resolution only if std::is_constructible&, + Args&&...>::value is true. .SH Parameters @@ -31,9 +36,13 @@ .SH Exceptions Any exception thrown by the selected constructor of T. If an exception is thrown, - *this is in disengaged state after the call. + *this does not contain a value after this call (the previously contained value, if + any, had been destroyed). .SH See also operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::optional::operator->,std::experimental::optional::operator*.3 b/man/std::experimental::optional::operator->,std::experimental::optional::operator*.3 index 450d17742..1ef0b4290 100644 --- a/man/std::experimental::optional::operator->,std::experimental::optional::operator*.3 +++ b/man/std::experimental::optional::operator->,std::experimental::optional::operator*.3 @@ -1,16 +1,21 @@ -.TH std::experimental::optional::operator->,std::experimental::optional::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::operator->,std::experimental::optional::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::operator->,std::experimental::optional::operator* \- std::experimental::optional::operator->,std::experimental::optional::operator* + .SH Synopsis - constexpr const T* operator->() const; \fB(1)\fP (library fundamentals TS) - T* operator->(); \fB(1)\fP (library fundamentals TS) - constexpr const T& operator*() const; \fB(2)\fP (library fundamentals TS) - T& operator*(); \fB(2)\fP (library fundamentals TS) + constexpr const T* operator->() const; \fB(1)\fP (library fundamentals TS) + constexpr T* operator->(); \fB(1)\fP (library fundamentals TS) + constexpr const T& operator*() const&; \fB(2)\fP (library fundamentals TS) + constexpr T& operator*() &; \fB(2)\fP (library fundamentals TS) + constexpr const T&& operator*() const&&; \fB(2)\fP (library fundamentals TS) + constexpr T&& operator*() &&; \fB(2)\fP (library fundamentals TS) Accesses the contained value. 1) Returns a pointer to the contained value. 2) Returns a reference to the contained value. - The behavior is undefined if *this is in disengaged state. + The behavior is undefined if *this does not contain a value. .SH Parameters @@ -22,4 +27,43 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. + +.SH Notes + + This operator does not check whether the optional contains a value. If checked + access is needed, value() or value_or() may be used. + +.SH Example + + +// Run this code + + #include + #include + #include + using namespace std::literals; + + int main() + { + std::experimental::optional opt1 = 1; + std::cout << *opt1 << '\\n'; + + std::experimental::optional opt2 = "abc"s; + std::cout << opt2->size() << '\\n'; + } + +.SH Output: + + 1 + 3 + +.SH See also + + value returns the contained value + \fI(public member function)\fP + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::optional::operator=.3 b/man/std::experimental::optional::operator=.3 index 2c4be448d..2f1754f2e 100644 --- a/man/std::experimental::optional::operator=.3 +++ b/man/std::experimental::optional::operator=.3 @@ -1,26 +1,34 @@ -.TH std::experimental::optional::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::operator= \- std::experimental::optional::operator= + .SH Synopsis - optional& operator=( std::nullopt_t ); \fB(1)\fP (library fundamentals TS) - optional& operator=( const optional& other ); \fB(2)\fP (library fundamentals TS) - optional& operator=( optional&& other ); \fB(3)\fP (library fundamentals TS) - template< class U > \fB(4)\fP (library fundamentals TS) + optional& operator=( std::experimental::nullopt_t ) \fB(1)\fP (library fundamentals TS) + noexcept; + optional& operator=( const optional& other ); \fB(2)\fP (library fundamentals TS) + optional& operator=( optional&& other ) noexcept(/* \fB(3)\fP (library fundamentals TS) + see below */); + template< class U > \fB(4)\fP (library fundamentals TS) optional& operator=( U&& value ); - Assigns contents to the contained value. - - 1) If *this is in engaged state before the call, the contained value is destroyed by - calling its destructor. *this is in disengaged state after the call. - 2-3) Assigns the state of other. - * If both *this and other are in disengaged states, the function has no effect. - * If *this is in engaged state, but other is not, then the contained value is - destroyed by calling its destructor. *this is in disengaged state after the call. - * If other is in engaged state, then depending on whether *this is in engaged state, - the contained value is either direct-constructed or assigned the contained value of - other. The contained value is either copied \fB(2)\fP, or moved \fB(3)\fP. - 4) Depending on whether *this is in engaged state before the call, the contained - value is either direct-constructed from value or assigned value. T must be - constructible and assignable from U, i.e. the following must hold: - std::is_constructible::value == true && std::is_assignable::value == true + Replaces contents of *this with the contents of other. + + 1) If *this contains a value before the call, the contained value is destroyed by + calling its destructor as if by val->T::~T(). *this does not contain a value after + this call. + 2,3) Assigns the state of other. + * If both *this and other do not contain a value, the function has no effect. + * If *this contains a value, but other does not, then the contained value is + destroyed by calling its destructor. *this does not contain a value after the + call. + * If other contains a value, then depending on whether *this contains a value, the + contained value is either direct-initialized or assigned from *other \fB(2)\fP or + std::move(*other) \fB(3)\fP. Note that a moved-from optional still contains a value. + 4) Decay-only perfect-forwarded assignment: depending on whether *this contains a + value before the call, the contained value is either direct-initialized from + std::forward(value) or assigned from std::forward(value). The function does + not participate in overload resolution unless std::is_same, + T>::value is true. .SH Parameters @@ -40,23 +48,47 @@ .SH Exceptions - 1) - noexcept specification: - noexcept - 2-4) Throws any exception thrown by the constructor or assignment operator of T. If an exception is thrown, the initialization state of *this (and of other in case of - \fB(2)\fP ) is unchanged, i.e. if the object was in engaged state, it is left in engaged - state, and the other way round. The contents of value and the contained values of - *this and other depend on the exception safety guarantees of the operation from - which the exception originates (copy-constructor, move-assignment, etc.). - 3) Throws any exception thrown by the constructor or assignment operator T. Has the - following noexcept declaration: - noexcept specification: \fI(since C++11)\fP + \fB(2)\fP) is unchanged, i.e. if the object contained a value, it still contains a value, + and the other way round. The contents of value and the contained values of *this and + other depend on the exception safety guarantees of the operation from which the + exception originates (copy-constructor, move-assignment, etc.). + \fB(3)\fP has the following noexcept declaration: + noexcept specification: noexcept(std::is_nothrow_move_assignable::value && std::is_nothrow_move_constructible::value) +.SH Notes + + An optional object op may be turned into an empty optional with both op = {}; and op + = nullopt;. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::experimental::optional s1 = "abc", s2; // constructor + s2 = s1; // assignment + s1 = "def"; // decaying assignment (U = char[4], T = const char*) + std::cout << *s2 << ' ' << *s1 << '\\n'; + } + +.SH Output: + + abc def + .SH See also emplace constructs the contained value in-place - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * conditionally noexcept diff --git a/man/std::experimental::optional::operatorbool.3 b/man/std::experimental::optional::operatorbool.3 index c69e6a469..60ae0b8c4 100644 --- a/man/std::experimental::optional::operatorbool.3 +++ b/man/std::experimental::optional::operatorbool.3 @@ -1,9 +1,11 @@ -.TH std::experimental::optional::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::operatorbool \- std::experimental::optional::operatorbool + .SH Synopsis - constexpr explicit operator bool() const; (library fundamentals TS) + constexpr explicit operator bool() const noexcept; (library fundamentals TS) - Checks whether *this is in engaged state, i.e. whether the contained value is - initialized. + Checks whether *this contains a value. .SH Parameters @@ -11,10 +13,7 @@ .SH Return value - true if *this is in engaged state, false otherwise. - -.SH Exceptions + true if *this contains a value, false if *this does not contain a value. - noexcept specification: - noexcept - +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::optional::optional.3 b/man/std::experimental::optional::optional.3 index 244053f0f..fb5374982 100644 --- a/man/std::experimental::optional::optional.3 +++ b/man/std::experimental::optional::optional.3 @@ -1,6 +1,111 @@ -.TH std::experimental::optional::optional 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::optional \- std::experimental::optional::optional + .SH Synopsis - ~optional() (library fundamentals TS) + constexpr optional() noexcept; (library fundamentals + constexpr optional( std::experimental::nullopt_t ) \fB(1)\fP TS) + noexcept; + optional( const optional& other ); \fB(2)\fP (library fundamentals + TS) + optional( optional&& other ) noexcept(/* see below */); \fB(3)\fP (library fundamentals + TS) + constexpr optional( const T& value ); \fB(4)\fP (library fundamentals + TS) + constexpr optional( T&& value ); \fB(5)\fP (library fundamentals + TS) + template< class... Args > (library fundamentals + constexpr explicit optional( \fB(6)\fP TS) + std::experimental::in_place_t, Args&&... args ); + template< class U, class... Args > + + constexpr explicit optional( + std::experimental::in_place_t, \fB(7)\fP (library fundamentals + std::initializer_list TS) + ilist, + + Args&&... args ); + + Constructs a new optional object. + + 1) Constructs the object that does not contain a value. + 2) Copy constructor: If other contains a value, initializes the contained value as + if direct-initializing (but not direct-list-initializing) an object of type T with + the expression *other. If other does not contain a value, constructs an object that + does not contain a value. + 3) Move constructor: If other contains a value, initializes the contained value as + if direct-initializing (but not direct-list-initializing) an object of type T with + the expression std::move(*other) and does not make other empty: a moved-from + optional still contains a value, but the value itself is moved from. If other does + not contain a value, constructs an object that does not contain a value. + 4) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T with the + expression value. This constructor is constexpr if the constructor of T selected by + direct-initialization is constexpr. + 5) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T with the + expression std::move(value). This constructor is constexpr if the constructor of T + selected by direct-initialization is constexpr. + 6) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T from the + arguments std::forward(args).... + 7) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T from the + arguments ilist, std::forward(args).... The function does not participate in + the overload resolution if std::is_constructible&, + Args&&...>::value != true. + +.SH Parameters + + other - another optional object whose contained value to copy + value - value to initialize the contained value with + args... - arguments to initialize the contained value with + ilist - initializer list to initialize the contained value with +.SH Type requirements + - + T must meet the requirements of CopyConstructible in order to use overloads (2,4). + - + T must meet the requirements of MoveConstructible in order to use overloads (3,5). + +.SH Exceptions + + 2) Throws any exception thrown by the constructor of T. + 3) Throws any exception thrown by the constructor of T. Has the following noexcept + declaration: + noexcept specification: + noexcept(std::is_nothrow_move_constructible::value) + 4-7) Throws any exception thrown by the constructor of T. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::experimental::optional o1, // empty + o2 = 1, // init from rvalue + o3 = o2; // copy-constructor + + std::experimental::optional o4(std::experimental::in_place, + {'a', 'b', 'c'}); + + std::cout << *o2 << ' ' << *o3 << ' ' << *o4 << '\\n'; + } + +.SH Output: + + 1 1 abc + +.SH See also + + make_optional creates an optional object + \fI(function template)\fP - If the object is in engaged state, destroys the contained value by calling its - destructor. +.SH Categories: + * Noindexed pages + * conditionally noexcept diff --git a/man/std::experimental::optional::swap.3 b/man/std::experimental::optional::swap.3 index 026517d95..76471ec61 100644 --- a/man/std::experimental::optional::swap.3 +++ b/man/std::experimental::optional::swap.3 @@ -1,18 +1,20 @@ -.TH std::experimental::optional::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::swap \- std::experimental::optional::swap + .SH Synopsis - void swap( optional& other ); (library fundamentals TS) + void swap( optional& other ) noexcept(/* see below */); (library fundamentals TS) Swaps the contents with those of other. - * If none of *this and other are in engaged states, the function has no effect. - - * If only one of *this and other is in engaged state (let's call this object in - and the other un), the contained value of un is initialized by moving the - contained value of in, followed by destruction of the contained value of in. in - is in disengaged state and un is in engaged state afterwards. - - * If both *this and other have engaged states, the contained values are exchanged - by calling swap(**this, *other). + * If neither *this nor other contain a value, the function has no effect. + * If only one of *this and other contains a value (let's call this object in and + the other un), the contained value of un is direct-initialized from + std::move(*in), followed by destruction of the contained value of in as if by + in.val->T::~T(). After this call, in does not contain a value un contains a + value. + * If both *this and other contain values, the contained values are exchanged by + calling using std::swap; swap(**this, *other). T lvalues must satisfy Swappable. .SH Parameters @@ -24,16 +26,20 @@ .SH Exceptions - noexcept specification: \fI(since C++11)\fP - noexcept(is_nothrow_move_constructible::value && - noexcept(swap(declval(), declval()))) + noexcept specification: + noexcept(std::is_nothrow_move_constructible::value && + noexcept(swap(std::declval(), std::declval()))) In the case of thrown exception, the states of the contained values of *this and other are determined by the exception safety guarantees of swap of type T or T's - move constructor, whichever is called. For both *this and other, if the object was - in engaged state, it is left in engaged state, and the other way round. + move constructor, whichever is called. For both *this and other, if the object + contained a value, it is left containing a value, and the other way round. .SH See also std::swap(std::experimental::optional) specializes the std::swap algorithm - \fI(function)\fP + \fI(function)\fP + +.SH Categories: + * Noindexed pages + * conditionally noexcept diff --git a/man/std::experimental::optional::value.3 b/man/std::experimental::optional::value.3 index 670502c2c..264dc9d58 100644 --- a/man/std::experimental::optional::value.3 +++ b/man/std::experimental::optional::value.3 @@ -1,10 +1,19 @@ -.TH std::experimental::optional::value 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::value \- std::experimental::optional::value + .SH Synopsis - constexpr const T& value() const; (library fundamentals TS) - T& value(); (library fundamentals TS) + constexpr T& value() &; \fB(1)\fP (library fundamentals TS) + constexpr const T & value() const &; + constexpr T&& value() &&; \fB(2)\fP (library fundamentals TS) + constexpr const T&& value() const &&; Returns the contained value. + 1) Equivalent to return bool(*this) ? *val : throw bad_optional_access();. + 2) Equivalent to return bool(*this) ? std::move(*val) : throw + bad_optional_access();. + .SH Parameters \fI(none)\fP @@ -15,9 +24,49 @@ .SH Exceptions - std::bad_optional_access if *this is in disengaged state. + std::experimental::bad_optional_access if *this does not contain a value. + +.SH Notes + + The dereference operator operator*() does not check if this optional contains a + value, which may be more efficient than value(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::experimental::optional opt = {}; + + try + { + int n = opt.value(); + } + catch (const std::logic_error& e) + { + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + optional::value: not engaged .SH See also - value_or returns the contained value if engaged, another value otherwise - \fI(public member function)\fP + returns the contained value if available, another value + value_or otherwise + \fI(public member function)\fP + operator-> accesses the contained value + operator* \fI(public member function)\fP + bad_optional_access exception indicating checked access to an optional that + (library fundamentals TS) doesn't contain a value + \fI(class)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::optional::value_or.3 b/man/std::experimental::optional::value_or.3 index 4268dac55..a9e490ae3 100644 --- a/man/std::experimental::optional::value_or.3 +++ b/man/std::experimental::optional::value_or.3 @@ -1,39 +1,69 @@ -.TH std::experimental::optional::value_or 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::experimental::optional::value_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::value_or \- std::experimental::optional::value_or + .SH Synopsis - template< class U > (library fundamentals TS) - constexpr T value_or( U&& value ) const&; - template< class U > (library fundamentals TS) - T value_or( U&& value ) &&; + template< class U > (library fundamentals TS) + constexpr T value_or( U&& default_value ) const&; + template< class U > (library fundamentals TS) + constexpr T value_or( U&& default_value ) &&; + + Returns the contained value if *this has a value, otherwise returns default_value. - Returns the contained value if *this is in engaged state, otherwise returns value. + 1) Equivalent to bool(*this) ? **this : + static_cast(std::forward(default_value)). + 2) Equivalent to bool(*this) ? std::move(**this) : + static_cast(std::forward(default_value)). .SH Parameters - value - the value to exchange + default_value - the value to use in case *this is empty .SH Type requirements - T must meet the requirements of CopyConstructible in order to use overload \fB(1)\fP. - T must meet the requirements of MoveConstructible in order to use overload \fB(2)\fP. - - U&& must be convertible to T + U&& must be convertible to T. .SH Return value - The current value if *this is in engaged state, or value otherwise. + The current value if *this has a value, or default_value otherwise. .SH Exceptions - Any exception thrown by the selected constructor of T. + Any exception thrown by the selected constructor of the return value T. + +.SH Example + + +// Run this code - If an exception is thrown, the exception safety guarantee is as follows: + #include + #include + #include - * If *this was in engaged state, the contents of the contained value depend on the - exception safety guarantee of T's constructor. - * Otherwise, the state of *this does not change. The contents of value depend on - the exception safety guarantee of T's constructor. + std::experimental::optional maybe_getenv(const char* n) + { + if (const char* x = std::getenv(n)) + return x; + else + return {}; + } + + int main() + { + std::cout << maybe_getenv("MYPWD").value_or("\fI(none)\fP") << '\\n'; + } + +.SH Possible output: + + \fI(none)\fP .SH See also value returns the contained value - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::optional::~optional.3 b/man/std::experimental::optional::~optional.3 new file mode 100644 index 000000000..3713ded7d --- /dev/null +++ b/man/std::experimental::optional::~optional.3 @@ -0,0 +1,20 @@ +.TH std::experimental::optional::~optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::optional::~optional \- std::experimental::optional::~optional + +.SH Synopsis + ~optional(); (library fundamentals TS) + + If the object contains a value and the type T is not trivially destructible (see + std::is_trivially_destructible), destroys the contained value by calling its + destructor, as if by val->T::~T(). + + Otherwise, does nothing. + +.SH Notes + + If T is trivially-destructible, then this destructor is also trivial, so optional + is also trivially-destructible. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::ostream_joiner.3 b/man/std::experimental::ostream_joiner.3 new file mode 100644 index 000000000..b9593ba86 --- /dev/null +++ b/man/std::experimental::ostream_joiner.3 @@ -0,0 +1,90 @@ +.TH std::experimental::ostream_joiner 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ostream_joiner \- std::experimental::ostream_joiner + +.SH Synopsis + Defined in header + template< + + class DelimT, + class CharT = char, (library fundamentals TS v2) + class Traits = std::char_traits + > + + class ostream_joiner; + + std::experimental::ostream_joiner is a single-pass LegacyOutputIterator that writes + successive objects into the std::basic_ostream object for which it was constructed, + using operator<<, separated by a delimiter. The delimiter is written to the output + stream between every two objects that are written. The write operation is performed + when the iterator (whether dereferenced or not) is assigned to. Incrementing the + ostream_joiner is a no-op. + + In a typical implementation, the only data members of ostream_joiner are a pointer + to the associated std::basic_ostream, the delimiter, and a bool member that + indicates whether the next write is for the first element in the sequence. + + Compared to std::ostream_iterator, ostream_joiner prints the delimiter sequence one + fewer time, and is not templated on the type of the object to be printed. + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + ostream_type std::basic_ostream + value_type void + difference_type void + pointer void + reference void + iterator_category std::output_iterator_tag + +.SH Member functions + + constructor constructs a new ostream_joiner + \fI(public member function)\fP + destructor destructs an ostream_joiner + (implicitly declared) \fI(public member function)\fP + operator= writes an object to the associated output sequence + \fI(public member function)\fP + operator* no-op + \fI(public member function)\fP + operator++ no-op + operator++(int) \fI(public member function)\fP + +.SH Non-member functions + + creates an ostream_joiner object, deducing the template's type + make_ostream_joiner arguments from the function arguments + \fI(function template)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + int i[] = {1, 2, 3, 4, 5}; + std::copy(std::begin(i), + std::end(i), + std::experimental::make_ostream_joiner(std::cout, ", ")); + } + +.SH Output: + + 1, 2, 3, 4, 5 + +.SH See also + + ostreambuf_iterator output iterator that writes to std::basic_streambuf + \fI(class template)\fP + ostream_iterator output iterator that writes to std::basic_ostream + \fI(class template)\fP + istream_iterator input iterator that reads from std::basic_istream + \fI(class template)\fP diff --git a/man/std::experimental::ostream_joiner::operator*.3 b/man/std::experimental::ostream_joiner::operator*.3 new file mode 100644 index 000000000..252c88624 --- /dev/null +++ b/man/std::experimental::ostream_joiner::operator*.3 @@ -0,0 +1,20 @@ +.TH std::experimental::ostream_joiner::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ostream_joiner::operator* \- std::experimental::ostream_joiner::operator* + +.SH Synopsis + ostream_joiner& operator*() noexcept; (library fundamentals TS v2) + + Does nothing, this member function is provided to satisfy the requirements of + LegacyOutputIterator. + + It returns the iterator itself, which makes it possible to use code such as *iter = + value to output (insert) the value into the underlying stream. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this diff --git a/man/std::experimental::ostream_joiner::operator++.3 b/man/std::experimental::ostream_joiner::operator++.3 new file mode 100644 index 000000000..2925317eb --- /dev/null +++ b/man/std::experimental::ostream_joiner::operator++.3 @@ -0,0 +1,19 @@ +.TH std::experimental::ostream_joiner::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ostream_joiner::operator++ \- std::experimental::ostream_joiner::operator++ + +.SH Synopsis + ostream_joiner& operator++() noexcept; (library fundamentals TS v2) + ostream_joiner& operator++( int ) noexcept; (library fundamentals TS v2) + + Does nothing. These operator overloads are provided to satisfy the requirements of + LegacyOutputIterator. They make it possible for the expressions *iter++=value and + *++iter=value to be used to output (insert) a value into the underlying stream. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this diff --git a/man/std::experimental::ostream_joiner::operator=.3 b/man/std::experimental::ostream_joiner::operator=.3 new file mode 100644 index 000000000..ed4fdc190 --- /dev/null +++ b/man/std::experimental::ostream_joiner::operator=.3 @@ -0,0 +1,56 @@ +.TH std::experimental::ostream_joiner::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ostream_joiner::operator= \- std::experimental::ostream_joiner::operator= + +.SH Synopsis + template< class T > \fB(1)\fP (library fundamentals TS v2) + ostream_joiner& operator=( const T& value ); + ostream_joiner& operator=( const ostream_joiner& \fB(2)\fP (library fundamentals TS v2) + other ) = default; (implicitly declared) + ostream_joiner& operator=( ostream_joiner&& other ) \fB(3)\fP (library fundamentals TS v2) + = default; (implicitly declared) + + 1) First, if the private "first element" flag is false, insert the delimiter delim + into the output stream os associated with this iterator as if by os << delim;. + Then, unconditionally sets the "first element" flag to false, and insert value into + the output stream as if by os << value;. + Let out_stream, delim, and first_element denote the private stream pointer, + delimiter, and "first element" flag members respectively. Then this function is + equivalent to + + if (!first_element) + *out_stream << delim; + first_element = false; + *out_stream << value; + return *this; + + 2,3) Implicitly declared copy/move assignment operator that copy/move assigns the + private stream pointer, delimiter, and "first element" flag members. + +.SH Parameters + + value - the object to to be written to the stream + other - the ostream_joiner object to be assigned to this object + +.SH Return value + + *this. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto joiner = std::experimental::make_ostream_joiner(std::cout, ", "); + joiner = "First"; + joiner = "do no harm."; // prefixes with the delimiter + } + +.SH Output: + + First, do no harm. diff --git a/man/std::experimental::ostream_joiner::ostream_joiner.3 b/man/std::experimental::ostream_joiner::ostream_joiner.3 new file mode 100644 index 000000000..3cc6369d0 --- /dev/null +++ b/man/std::experimental::ostream_joiner::ostream_joiner.3 @@ -0,0 +1,37 @@ +.TH std::experimental::ostream_joiner::ostream_joiner 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ostream_joiner::ostream_joiner \- std::experimental::ostream_joiner::ostream_joiner + +.SH Synopsis + ostream_joiner( ostream_type& stream, const DelimT& \fB(1)\fP (library fundamentals TS v2) + delimiter ); + ostream_joiner( ostream_type& stream, DelimT&& \fB(2)\fP (library fundamentals TS v2) + delimiter ); + ostream_joiner( const ostream_joiner& other ) = \fB(3)\fP (library fundamentals TS v2) + default; (implicitly declared) + ostream_joiner( ostream_joiner&& other ) = default; \fB(4)\fP (library fundamentals TS v2) + (implicitly declared) + + 1) Constructs the iterator with the private ostream_type* member initialized with + std::addressof(stream), the private delimiter member initialized with delimiter, and + the private "first element" flag set to true. + 2) Constructs the iterator with the private ostream_type* member initialized with + std::addressof(stream), the private delimiter member initialized with + std::move(delimiter), and the private "first element" flag set to true. + 3,4) Implicitly declared copy/move constructor that copy/move constructs the private + stream pointer, delimiter, and "first element" flag members. + +.SH Parameters + + stream - the output stream to be accessed by this iterator + delimiter - the delimiter to be inserted into the stream in between two outputs + other - the ostream_joiner object from which this object is to be copy- or + move-constructed + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::overaligned_tag,std::experimental::overaligned.3 b/man/std::experimental::overaligned_tag,std::experimental::overaligned.3 new file mode 100644 index 000000000..95aa0e1ba --- /dev/null +++ b/man/std::experimental::overaligned_tag,std::experimental::overaligned.3 @@ -0,0 +1,28 @@ +.TH std::experimental::overaligned_tag,std::experimental::overaligned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::overaligned_tag,std::experimental::overaligned \- std::experimental::overaligned_tag,std::experimental::overaligned + +.SH Synopsis + Defined in header + template< std::size_t N > + + struct overaligned_tag {}; + (parallelism TS v2) + template< std::size_t N > + + inline constexpr overaligned_tag overaligned{}; + + This tag type indicates that the buffer of copy_from and copy_to is aligned to N. + +.SH Template parameters + + N - the alignment in bytes the memory access may assume + +.SH See also + + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + element_aligned_tag flag indicating alignment of the load/store address to element + element_aligned alignment + (parallelism TS v2) \fI(class)\fP diff --git a/man/std::experimental::packaged_task(concurrencyTS).3 b/man/std::experimental::packaged_task(concurrencyTS).3 new file mode 100644 index 000000000..616dc6cc3 --- /dev/null +++ b/man/std::experimental::packaged_task(concurrencyTS).3 @@ -0,0 +1,16 @@ +.TH std::experimental::packaged_task(concurrencyTS) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::packaged_task(concurrencyTS) \- std::experimental::packaged_task(concurrencyTS) + +.SH Synopsis + Defined in header + template< class > class packaged_task; //not defined \fB(1)\fP (concurrency TS) + template< class R, class ...Args > \fB(2)\fP (concurrency TS) + class packaged_task; + + std::experimental::concurrency_v1::packaged_task is a modified version of + std::packaged_task provided by the concurrency TS that works with + std::experimental::future. + + The only change from std::packaged_task is that the get_future() member function + returns a std::experimental::future. diff --git a/man/std::experimental::packaged_task(libraryfundamentalsTS).3 b/man/std::experimental::packaged_task(libraryfundamentalsTS).3 new file mode 100644 index 000000000..df011772b --- /dev/null +++ b/man/std::experimental::packaged_task(libraryfundamentalsTS).3 @@ -0,0 +1,73 @@ +.TH std::experimental::packaged_task(libraryfundamentalsTS) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::packaged_task(libraryfundamentalsTS) \- std::experimental::packaged_task(libraryfundamentalsTS) + +.SH Synopsis + Defined in header + template< class > class packaged_task; //not defined \fB(1)\fP (library fundamentals TS) + template< class R, class ...Args > \fB(2)\fP (library fundamentals TS) + class packaged_task; + + std::experimental::fundamentals_v1::packaged_task (and + std::experimental::fundamentals_v2::packaged_task) is a modified version of + std::packaged_task provided by the library fundamentals TS with support for + type-erased allocators. + +.SH Member types + + Member type Definition + allocator_type std::experimental::erased_type + +.SH Member functions + + constructor constructs the task object + \fI(public member function)\fP + retrieves a pointer to the memory resource used by this object + get_memory_resource to allocate memory + \fI(public member function)\fP + + Non-member function + + specializes the swap + std::experimental::swap(std::experimental::packaged_task) algorithm + \fI(function template)\fP + +.SH Helper classes + + specializes the + std::uses_allocator std::uses_allocator type trait + (class template + specialization) + +Members identical to std::packaged_task + +.SH Member functions + + destructs the task object + destructor \fI(public member function of std::packaged_task)\fP + + moves the task object + operator= \fI(public member function of std::packaged_task)\fP + + checks if the task object has a valid function + valid \fI(public member function of std::packaged_task)\fP + + swaps two task objects + swap \fI(public member function of std::packaged_task)\fP + +.SH Getting the result + returns a std::future associated with the promised result + get_future \fI(public member function of std::packaged_task)\fP + +.SH Execution + executes the function + operator() \fI(public member function of std::packaged_task)\fP + + executes the function ensuring that the result is ready + make_ready_at_thread_exit only once the current thread exits + \fI(public member function of std::packaged_task)\fP + + resets the state abandoning any stored results of previous + reset executions + \fI(public member function of std::packaged_task)\fP + diff --git a/man/std::experimental::packaged_task::get_memory_resource.3 b/man/std::experimental::packaged_task::get_memory_resource.3 new file mode 100644 index 000000000..d3ba23055 --- /dev/null +++ b/man/std::experimental::packaged_task::get_memory_resource.3 @@ -0,0 +1,22 @@ +.TH std::experimental::packaged_task::get_memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::packaged_task::get_memory_resource \- std::experimental::packaged_task::get_memory_resource + +.SH Synopsis + std::experimental::pmr::memory_resource* (library fundamentals + get_memory_resource() const noexcept; TS) + + Returns a pointer to the memory resource used by this object to allocate memory. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the memory resource used by this object to allocate memory. + +.SH See also + + constructor constructs the task object + \fI(public member function)\fP diff --git a/man/std::experimental::packaged_task::packaged_task(libraryfundamentalsTS).3 b/man/std::experimental::packaged_task::packaged_task(libraryfundamentalsTS).3 new file mode 100644 index 000000000..85d423e48 --- /dev/null +++ b/man/std::experimental::packaged_task::packaged_task(libraryfundamentalsTS).3 @@ -0,0 +1,65 @@ +.TH std::experimental::packaged_task::packaged_task(libraryfundamentalsTS) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::packaged_task::packaged_task(libraryfundamentalsTS) \- std::experimental::packaged_task::packaged_task(libraryfundamentalsTS) + +.SH Synopsis + packaged_task() noexcept; \fB(1)\fP (library fundamentals TS) + template< class F > \fB(2)\fP (library fundamentals TS) + explicit packaged_task( F&& f ); + template< class F, class Allocator > + explicit packaged_task( std::allocator_arg_t, const \fB(3)\fP (library fundamentals TS) + Allocator& alloc, F&& f ); + packaged_task( const packaged_task& ) = delete; \fB(4)\fP (library fundamentals TS) + packaged_task( packaged_task&& rhs ) noexcept; \fB(5)\fP (library fundamentals TS) + + Constructs a new std::experimental::packaged_task object. + + 1) Constructs a std::experimental::packaged_task object with no task and no shared + state. + 2) Constructs a std::experimental::packaged_task object with a shared state and a + copy of the task, initialized with std::forward(f). This constructor does not + participate in overload resolution if std::decay::type is the same type as + std::packaged_task. + 3) Constructs a std::experimental::packaged_task object with a shared state and a + copy of the task, initialized with std::forward(f). Uses the provided allocator + to allocate memory necessary to store the task, which is treated as a type-erased + allocator (see below). This constructor does not participate in overload resolution + if std::decay::type is the same type as std::packaged_task. + 4) The copy constructor is deleted, std::experimental::packaged_task is move-only. + 5) Constructs a std::experimental::packaged_task with the shared state and task + formerly owned by rhs, leaving rhs with no shared state and a moved-from task. + + Type-erased allocator + + The constructors of packaged_task taking an allocator argument alloc treats that + argument as a type-erased allocator. The memory resource pointer used by + packaged_task to allocate memory is determined using the allocator argument (if + specified) as follows: + +Type of alloc Value of the memory resource pointer +Non-existent (no allocator specified at time The value of std::experimental::pmr::get_default_resource() +of construction) at time of construction. +std::nullptr_t The value of std::experimental::pmr::get_default_resource() + at time of construction. +A pointer type convertible to static_cast(alloc) +std::experimental::pmr::memory_resource* +A specialization of alloc.resource() +std::experimental::pmr::polymorphic_allocator + A pointer to a value of type +Any other type meeting the Allocator std::experimental::pmr::resource_adaptor(alloc), where A +requirements is the type of alloc. The pointer remains valid only for the + lifetime of the packaged_task object. +None of the above The program is ill-formed. + +.SH Parameters + + f - the callable target \fI(function, member function, lambda-expression, functor)\fP + to execute + alloc - the allocator to use when storing the task + rhs - the std::experimental::packaged_task to move from + +.SH Exceptions + + 2,3) Any exceptions thrown by copy/move constructor of f and possiblly + std::bad_alloc if the allocation fails. + 4) \fI(none)\fP diff --git a/man/std::experimental::parallel::is_execution_policy.3 b/man/std::experimental::parallel::is_execution_policy.3 new file mode 100644 index 000000000..2236bce77 --- /dev/null +++ b/man/std::experimental::parallel::is_execution_policy.3 @@ -0,0 +1,52 @@ +.TH std::experimental::parallel::is_execution_policy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::parallel::is_execution_policy \- std::experimental::parallel::is_execution_policy + +.SH Synopsis + Defined in header + template< class T > (parallelism TS) + struct is_execution_policy; + + Checks whether T is a standard or implementation-defined execution policy type. + + Provides the member constant value which is equal to true, if T is execution_policy, + sequential_execution_policy, parallel_execution_policy, + parallel_vector_execution_policy, or an implementation-defined execution policy + type. Otherwise, value is equal to false. + + The behavior of a program that adds specializations for is_execution_policy is + undefined. + +.SH Template parameters + + T - a type to check + + Helper template + + Defined in header + template< class T > + constexpr bool is_execution_policy_v = (parallelism TS) + is_execution_policy::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is a standard or implementation-defined execution policy type, + \fB[static]\fP false otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant diff --git a/man/std::experimental::parallel::reduce.3 b/man/std::experimental::parallel::reduce.3 new file mode 100644 index 000000000..e7b5da83c --- /dev/null +++ b/man/std::experimental::parallel::reduce.3 @@ -0,0 +1,167 @@ +.TH std::experimental::parallel::reduce 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::parallel::reduce \- std::experimental::parallel::reduce + +.SH Synopsis + Defined in header + template< class InputIt > + + typename std::iterator_traits::value_type reduce( \fB(1)\fP (parallelism TS) + + InputIt first, InputIt last ); + template< class ExecutionPolicy, class InputIterator > + + typename std::iterator_traits::value_type reduce( \fB(2)\fP (parallelism TS) + + ExecutionPolicy&& policy, InputIt first, InputIt last ); + template< class InputIt, class T > \fB(3)\fP (parallelism TS) + T reduce( InputIt first, InputIt last, T init ); + template< class ExecutionPolicy, class InputIt, class T > + T reduce( ExecutionPolicy&& policy, InputIt first, InputIt \fB(4)\fP (parallelism TS) + last, T init ); + template< class InputIt, class T, class BinaryOp > + T reduce( InputIt first, InputIt last, T init, BinaryOp \fB(5)\fP (parallelism TS) + binary_op ); + template< class ExecutionPolicy, class InputIt, class T, class + BinaryOp > + + T reduce( ExecutionPolicy&& policy, \fB(6)\fP (parallelism TS) + + InputIt first, InputIt last, T init, BinaryOp + binary_op ); + + 1) Same as reduce(first, last, typename + std::iterator_traits::value_type{}). + 3) Same as reduce(first, last, init, std::plus<>()). + 5) Reduces the range [first, last), possibly permuted and aggregated in unspecified + manner, along with the initial value init over binary_op. + 2,4,6) Same as (1,3,5), but executed according to policy. + + The behavior is non-deterministic if binary_op is not associative or not + commutative. + + The behavior is undefined if binary_op modifies any element or invalidates any + iterator in [first, last). + +.SH Parameters + + first, last - the range of elements to apply the algorithm to + init - the initial value of the generalized sum + policy - the execution policy + binary FunctionObject that will be applied in unspecified order to the + binary_op - result of dereferencing the input iterators, the results of other + binary_op and init +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + Generalized sum of init and *first, *(first + 1), ... *(last - 1) over binary_op, + + where generalized sum GSUM(op, a + 1, ..., a + N) is defined as follows: + + * if N=1, a + 1 + * if N > 1, op(GSUM(op, b + 1, ..., b + K), GSUM(op, b + M, ..., b + N)) where + + * b + 1, ..., b + N may be any permutation of a1, ..., aN and + * 1 < K+1 = M ≤ N + + in other words, the elements of the range may be grouped and rearranged in arbitrary + order. + +.SH Complexity + + O(last - first) applications of binary_op. + +.SH Exceptions + + * If execution of a function invoked as part of the algorithm throws an exception, + + * if policy is parallel_vector_execution_policy, std::terminate is called. + * if policy is sequential_execution_policy or parallel_execution_policy, the + algorithm exits with an exception_list containing all uncaught exceptions. If + there was only one uncaught exception, the algorithm may rethrow it without + wrapping in exception_list. It is unspecified how much work the algorithm will + perform before returning after the first exception was encountered. + * if policy is some other type, the behavior is implementation-defined. + * If the algorithm fails to allocate memory (either for itself or to construct an + exception_list when handling a user exception), std::bad_alloc is thrown. + +.SH Notes + + If the range is empty, init is returned, unmodified. + + * If policy is an instance of sequential_execution_policy, all operations are + performed in the calling thread. + * If policy is an instance of parallel_execution_policy, operations may be + performed in unspecified number of threads, indeterminately sequenced with each + other. + * If policy is an instance of parallel_vector_execution_policy, execution may be + both parallelized and vectorized: function body boundaries are not respected and + user code may be overlapped and combined in arbitrary manner (in particular, + this implies that a user-provided Callable must not acquire a mutex to access a + shared resource). + +.SH Example + + reduce is the out-of-order version of std::accumulate: + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::vector v(10'000'007, 0.5); + + { + auto t1 = std::chrono::high_resolution_clock::now(); + double result = std::accumulate(v.begin(), v.end(), 0.0); + auto t2 = std::chrono::high_resolution_clock::now(); + std::chrono::duration ms = t2 - t1; + std::cout << std::fixed << "std::accumulate result " << result + << " took " << ms.count() << " ms\\n"; + } + + { + auto t1 = std::chrono::high_resolution_clock::now(); + double result = std::experimental::parallel::reduce( + std::experimental::parallel::par, + v.begin(), v.end()); + auto t2 = std::chrono::high_resolution_clock::now(); + std::chrono::duration ms = t2 - t1; + std::cout << "parallel::reduce result " + << result << " took " << ms.count() << " ms\\n"; + } + } + +.SH Possible output: + + std::accumulate result 5000003.50000 took 12.7365 ms + parallel::reduce result 5000003.50000 took 5.06423 ms + +.SH See also + + accumulate sums up or folds a range of elements + \fI(function template)\fP + applies a function to a range of elements, storing results in a + transform destination range + \fI(function template)\fP + transform_reduce applies a functor, then reduces out of order + (parallelism TS) \fI(function template)\fP diff --git a/man/std::experimental::parallel::seq,std::experimental::parallel::par,.3 b/man/std::experimental::parallel::seq,std::experimental::parallel::par,.3 new file mode 100644 index 000000000..5c34c824c --- /dev/null +++ b/man/std::experimental::parallel::seq,std::experimental::parallel::par,.3 @@ -0,0 +1,15 @@ +.TH std::experimental::parallel::seq,std::experimental::parallel::par, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::parallel::seq,std::experimental::parallel::par, \- std::experimental::parallel::seq,std::experimental::parallel::par, + +.SH Synopsis + + Defined in header + constexpr sequential_execution_policy seq{}; (parallelism TS) + constexpr parallel_execution_policy par{}; (parallelism TS) + constexpr parallel_vector_execution_policy par_vec{}; (parallelism TS) + + seq, par and par_vec are instances of the execution policy types + sequential_execution_policy, parallel_execution_policy and + parallel_vector_execution_policy respectively. They are used to specify the + execution policy of parallel algorithms - i.e., the kinds of parallelism allowed. diff --git a/man/std::experimental::parallel::sequential_execution_policy,.3 b/man/std::experimental::parallel::sequential_execution_policy,.3 new file mode 100644 index 000000000..cd475ce20 --- /dev/null +++ b/man/std::experimental::parallel::sequential_execution_policy,.3 @@ -0,0 +1,15 @@ +.TH std::experimental::parallel::sequential_execution_policy, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::parallel::sequential_execution_policy, \- std::experimental::parallel::sequential_execution_policy, + +.SH Synopsis + std::experimental::parallel::parallel_vector_execution_policy + + Defined in header + class sequential_execution_policy { /* unspecified */ }; (parallelism TS) + class parallel_execution_policy { /* unspecified */ }; (parallelism TS) + class parallel_vector_execution_policy { /* unspecified */ }; (parallelism TS) + + sequential_execution_policy, parallel_execution_policy and + parallel_vector_execution_policy are tag types used to indicate the kinds of + parallelism allowed in the execution of a parallel algorithm. diff --git a/man/std::experimental::parallel::transform_reduce.3 b/man/std::experimental::parallel::transform_reduce.3 new file mode 100644 index 000000000..58349cea1 --- /dev/null +++ b/man/std::experimental::parallel::transform_reduce.3 @@ -0,0 +1,150 @@ +.TH std::experimental::parallel::transform_reduce 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::parallel::transform_reduce \- std::experimental::parallel::transform_reduce + +.SH Synopsis + Defined in header + template< class InputIt, class UnaryOp, class T, class BinaryOp + > + + T transform_reduce( InputIt first, InputIt last, \fB(1)\fP (parallelism TS) + + UnaryOp unary_op, T init, BinaryOp + binary_op ); + template< class ExecutionPolicy, + + class InputIt, class UnaryOp, class T, class BinaryOp + > + T transform_reduce( ExecutionPolicy&& policy, \fB(2)\fP (parallelism TS) + InputIt first, InputIt last, + + UnaryOp unary_op, T init, BinaryOp + binary_op ); + + Applies unary_op to each element in the range [first, last) and reduces the results + (possibly permuted and aggregated in unspecified manner) along with the initial + value init over binary_op. + + The behavior is non-deterministic if binary_op is not associative or not + commutative. + + The behavior is undefined if unary_op or binary_op modifies any element or + invalidates any iterator in [first, last). + +.SH Parameters + + first, last - the range of elements to apply the algorithm to + init - the initial value of the generalized sum + policy - the execution policy + unary_op - unary FunctionObject that will be applied to each element of the input + range. The return type must be acceptable as input to binary_op + binary_op - binary FunctionObject that will be applied in unspecified order to the + results of unary_op, the results of other binary_op and init +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + Generalized sum of init and unary_op(*first), unary_op(*(first + 1)), ... + unary_op(*(last - 1)) over binary_op, where generalized sum GSUM(op, a + 1, ..., a + N) is defined as follows: + + * if N = 1, a + 1, + * if N > 1, op(GSUM(op, b + 1, ..., b + K), GSUM(op, b + M, ..., b + N)) where + + * b + 1, ..., b + N may be any permutation of a1, ..., aN and + * 1 < K + 1 = M ≤ N + + in other words, the results of unary_op may be grouped and arranged in arbitrary + order. + +.SH Complexity + + O(last - first) applications each of unary_op and binary_op. + +.SH Exceptions + + * If execution of a function invoked as part of the algorithm throws an exception, + + * if policy is parallel_vector_execution_policy, std::terminate is called. + * if policy is sequential_execution_policy or parallel_execution_policy, the + algorithm exits with an exception_list containing all uncaught exceptions. If + there was only one uncaught exception, the algorithm may rethrow it without + wrapping in exception_list. It is unspecified how much work the algorithm will + perform before returning after the first exception was encountered. + * if policy is some other type, the behavior is implementation-defined. + * If the algorithm fails to allocate memory (either for itself or to construct an + exception_list when handling a user exception), std::bad_alloc is thrown. + +.SH Notes + + unary_op is not applied to init. + + If the range is empty, init is returned, unmodified. + + * If policy is an instance of sequential_execution_policy, all operations are + performed in the calling thread. + * If policy is an instance of parallel_execution_policy, operations may be + performed in unspecified number of threads, indeterminately sequenced with each + other. + * If policy is an instance of parallel_vector_execution_policy, execution may be + both parallelized and vectorized: function body boundaries are not respected and + user code may be overlapped and combined in arbitrary manner (in particular, + this implies that a user-provided Callable must not acquire a mutex to access a + shared resource). + +.SH Example + + transform_reduce can be used to parallelize std::inner_product: + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + int main() + { + std::vector xvalues(10007, 1.0), yvalues(10007, 1.0); + + double result = std::experimental::parallel::transform_reduce( + std::experimental::parallel::par, + boost::iterators::make_zip_iterator( + boost::make_tuple(std::begin(xvalues), std::begin(yvalues))), + boost::iterators::make_zip_iterator( + boost::make_tuple(std::end(xvalues), std::end(yvalues))), + [](auto r) { return boost::get<0>(r) * boost::get<1>(r); } + 0.0, + std::plus<>() + ); + std::cout << result << '\\n'; + } + +.SH Output: + + 10007 + +.SH See also + + accumulate sums up or folds a range of elements + \fI(function template)\fP + applies a function to a range of elements, storing results in a + transform destination range + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + (parallelism TS) \fI(function template)\fP diff --git a/man/std::experimental::pmr::get_default_resource.3 b/man/std::experimental::pmr::get_default_resource.3 new file mode 100644 index 000000000..52421f83b --- /dev/null +++ b/man/std::experimental::pmr::get_default_resource.3 @@ -0,0 +1,32 @@ +.TH std::experimental::pmr::get_default_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::get_default_resource \- std::experimental::pmr::get_default_resource + +.SH Synopsis + Defined in header + memory_resource* get_default_resource() noexcept; (library fundamentals TS) + + Gets the default memory resource pointer. + + The default memory resource pointer is used by certain facilities when an explicit + memory resource is not supplied. The initial default memory resource pointer is the + return value of new_delete_resource(). + + This function is thread-safe. Previous call to set_default_resource synchronizes + with (see std::memory_order) the subsequent get_default_resource calls. + +.SH Return value + + Returns the value of the default memory resource pointer. + +.SH See also + + set_default_resource sets the default memory_resource + \fI(function)\fP + returns a static program-wide memory_resource that uses the + new_delete_resource global operator new and operator delete to allocate and + deallocate memory + \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource.3 b/man/std::experimental::pmr::memory_resource.3 new file mode 100644 index 000000000..4a5f59cb6 --- /dev/null +++ b/man/std::experimental::pmr::memory_resource.3 @@ -0,0 +1,41 @@ +.TH std::experimental::pmr::memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource \- std::experimental::pmr::memory_resource + +.SH Synopsis + Defined in header + class memory_resource; (library fundamentals TS) + + The class std::experimental::pmr::memory_resource is an abstract interface to an + unbounded set of classes encapsulating memory resources. + +.SH Member functions + + constructor constructs a new memory_resource + (implicitly declared) \fI(public member function)\fP + destructor destructs a memory_resource + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= implicitly declared copy assignment operator + (implicitly declared) \fI(public member function)\fP +.SH Public member functions + allocate allocates memory + \fI(public member function)\fP + deallocate deallocates memory + \fI(public member function)\fP + is_equal compare for equality with another memory_resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocates memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate deallocates memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP + + Non-member-functions + + operator== compare two memory_resources + operator!= \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::allocate.3 b/man/std::experimental::pmr::memory_resource::allocate.3 new file mode 100644 index 000000000..7a71c5c03 --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::allocate.3 @@ -0,0 +1,26 @@ +.TH std::experimental::pmr::memory_resource::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::allocate \- std::experimental::pmr::memory_resource::allocate + +.SH Synopsis + void* allocate( std::size_t bytes, std::size_t alignment (library fundamentals TS) + = alignof(std::max_align_t) ); + + Allocates storage with a size of at least bytes bytes. The returned storage is + aligned to the specified alignment if such alignment is supported, and to + alignof(std::max_align_t) otherwise. + + Equivalent to return do_allocate(bytes, alignment);. + +.SH Exceptions + + Throws an exception if storage of the requested size and alignment cannot be + obtained. + +.SH See also + + do_allocate allocates memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::deallocate.3 b/man/std::experimental::pmr::memory_resource::deallocate.3 new file mode 100644 index 000000000..d389d46a2 --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::deallocate.3 @@ -0,0 +1,25 @@ +.TH std::experimental::pmr::memory_resource::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::deallocate \- std::experimental::pmr::memory_resource::deallocate + +.SH Synopsis + void* deallocate( void* p, std::size_t bytes, std::size_t (library fundamentals TS) + alignment = alignof(std::max_align_t) ); + + Deallocates the storage pointed to by p. p shall have been returned by a prior call + to allocate(bytes, alignment) on a memory_resource that compares equal to *this, and + the storage it points to shall not yet have been deallocated. + + Equivalent to return do_deallocate(p, bytes, alignment);. + +.SH Exceptions + + Throws nothing. + +.SH See also + + do_deallocate deallocates memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::do_allocate.3 b/man/std::experimental::pmr::memory_resource::do_allocate.3 new file mode 100644 index 000000000..69fcbec78 --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::do_allocate.3 @@ -0,0 +1,26 @@ +.TH std::experimental::pmr::memory_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::do_allocate \- std::experimental::pmr::memory_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t (library fundamentals TS) + alignment ) = 0; + + Allocates storage with a size of at least bytes bytes. The returned storage is + aligned to the specified alignment if such alignment is supported, and to + alignof(std::max_align_t) otherwise. + + alignment shall be a power of two. + +.SH Exceptions + + Throws an exception if storage of the requested size and alignment cannot be + obtained. + +.SH See also + + allocate allocates memory + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::do_deallocate.3 b/man/std::experimental::pmr::memory_resource::do_deallocate.3 new file mode 100644 index 000000000..6312331fb --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::do_deallocate.3 @@ -0,0 +1,23 @@ +.TH std::experimental::pmr::memory_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::do_deallocate \- std::experimental::pmr::memory_resource::do_deallocate + +.SH Synopsis + virtual void* do_deallocate( void* p, std::size_t bytes, (library fundamentals TS) + std::size_t alignment ) = 0; + + Deallocates the storage pointed to by p. p shall have been returned by a prior call + to allocate(bytes, alignment) on a memory_resource that compares equal to *this, and + the storage it points to shall not yet have been deallocated. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate deallocates memory + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::do_is_equal.3 b/man/std::experimental::pmr::memory_resource::do_is_equal.3 new file mode 100644 index 000000000..dd5826efe --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::do_is_equal.3 @@ -0,0 +1,27 @@ +.TH std::experimental::pmr::memory_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::do_is_equal \- std::experimental::pmr::memory_resource::do_is_equal + +.SH Synopsis + virtual bool is_equal( const memory_resource& other ) (library fundamentals TS) + const noexcept = 0; + + Compares *this for equality with other. + + Two memory_resources compare equal if and only if memory allocated from one + memory_resource can be deallocated from the other and vice versa. + +.SH Notes + + The most-derived type of other may not match the most derived type of *this. A + derived class implementation therefore must typically check whether the most derived + types of *this and other match using dynamic_cast, and immediately return false if + the cast fails. + +.SH See also + + is_equal compare for equality with another memory_resource + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::is_equal.3 b/man/std::experimental::pmr::memory_resource::is_equal.3 new file mode 100644 index 000000000..041f8f92f --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::is_equal.3 @@ -0,0 +1,21 @@ +.TH std::experimental::pmr::memory_resource::is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::is_equal \- std::experimental::pmr::memory_resource::is_equal + +.SH Synopsis + bool is_equal( const memory_resource& other ) const (library fundamentals TS) + noexcept; + + Compares *this for equality with other. Two memory_resources compare equal if and + only if memory allocated from one memory_resource can be deallocated from the other + and vice versa. + + Equivalent to return do_is_equal(other);. + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::memory_resource::memory_resource.3 b/man/std::experimental::pmr::memory_resource::memory_resource.3 new file mode 100644 index 000000000..1ae749bf2 --- /dev/null +++ b/man/std::experimental::pmr::memory_resource::memory_resource.3 @@ -0,0 +1,14 @@ +.TH std::experimental::pmr::memory_resource::memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::memory_resource::memory_resource \- std::experimental::pmr::memory_resource::memory_resource + +.SH Synopsis + memory_resource() = default; \fB(1)\fP (library fundamentals TS) + (implicitly declared) + memory_resource( const memory_resource& ) = default; \fB(2)\fP (library fundamentals TS) + (implicitly declared) + + 1) Implicitly declared default constructor. + 2) Implicitly declared copy constructor. +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource.3 b/man/std::experimental::pmr::monotonic_buffer_resource.3 new file mode 100644 index 000000000..c2437fbf3 --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource.3 @@ -0,0 +1,45 @@ +.TH std::experimental::pmr::monotonic_buffer_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource \- std::experimental::pmr::monotonic_buffer_resource + +.SH Synopsis + Defined in header + class monotonic_buffer_resource : public memory_resource; (library fundamentals TS) + + The class std::experimental::pmr::monotonic_buffer_resource is a special-purpose + memory resource class that releases the allocated memory only when the resource is + destroyed. It is intended for very fast memory allocations in situations where + memory is used to build up a few objects and then is released all at once. + + monotonic_buffer_resource can be constructed with an initial buffer. If there is no + initial buffer, or if the buffer is exhausted, additional buffers are obtained from + an upstream memory resource supplied at construction. The size of buffers obtained + follows a geometric progression. + + monotonic_buffer_resource is not thread-safe. + +.SH Member functions + + constructor constructs a monotonic_buffer_resource + \fI(public member function)\fP + destructor destroys a monotonic_buffer_resource, releasing all allocated + \fB[virtual]\fP memory + \fI(virtual public member function)\fP + operator= copy assignment operator is deleted. monotonic_buffer_resource is + [deleted] not copy assignable + \fI(public member function)\fP +.SH Public member functions + release release all allocated memory + \fI(public member function)\fP + upstream_resource returns a pointer to the upstream memory resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocate memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate no-op + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::do_allocate.3 b/man/std::experimental::pmr::monotonic_buffer_resource::do_allocate.3 new file mode 100644 index 000000000..94050c310 --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::do_allocate.3 @@ -0,0 +1,41 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::do_allocate \- std::experimental::pmr::monotonic_buffer_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t (library fundamentals TS) + alignment ); + + Allocates storage. + + If the current buffer has sufficient unused space to fit a block with the specified + size and alignment, allocates the return block from the current buffer. + + Otherwise, this function allocates a new buffer by calling + upstream_resource()->allocate(n, m), where n is not less than the greater of bytes + and the next buffer size and m is not less than alignment. It sets the new buffer as + the current buffer, increases the next buffer size by an implementation-defined + growth factor (which is not necessarily integral), and then allocates the return + block from the newly allocated buffer. + +.SH Return value + + A pointer to allocated storage of at least bytes bytes in size, aligned to the + specified alignment if such alignment is supported, and to alignof(std::max_align_t) + otherwise. + +.SH Exceptions + + Throws nothing unless calling allocate() on the upstream memory resource throws. + +.SH See also + + allocates memory + allocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + do_allocate allocates memory + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::do_deallocate.3 b/man/std::experimental::pmr::monotonic_buffer_resource::do_deallocate.3 new file mode 100644 index 000000000..da18003eb --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::do_deallocate.3 @@ -0,0 +1,26 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::do_deallocate \- std::experimental::pmr::monotonic_buffer_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, (library fundamentals TS) + std::size_t alignment ); + + This function has no effect. Memory used by a monotonic_buffer_resource, as its name + indicates, increases monotonically until the resource is destroyed. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + do_deallocate deallocates memory + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::do_is_equal.3 b/man/std::experimental::pmr::monotonic_buffer_resource::do_is_equal.3 new file mode 100644 index 000000000..7af2b235a --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::do_is_equal.3 @@ -0,0 +1,23 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::do_is_equal \- std::experimental::pmr::monotonic_buffer_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const memory_resource& other ) (library fundamentals TS) + const noexcept; + + Compare *this with other for identity - memory allocated using a + monotonic_buffer_resource can only be deallocated using that same resource. + +.SH Return value + + this == dynamic_cast(&other) + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::monotonic_buffer_resource.3 b/man/std::experimental::pmr::monotonic_buffer_resource::monotonic_buffer_resource.3 new file mode 100644 index 000000000..6ef3c3fdb --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::monotonic_buffer_resource.3 @@ -0,0 +1,47 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::monotonic_buffer_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::monotonic_buffer_resource \- std::experimental::pmr::monotonic_buffer_resource::monotonic_buffer_resource + +.SH Synopsis + monotonic_buffer_resource(); \fB(1)\fP (library fundamentals TS) + explicit monotonic_buffer_resource( memory_resource* \fB(2)\fP (library fundamentals TS) + upstream ); + explicit monotonic_buffer_resource( std::size_t \fB(3)\fP (library fundamentals TS) + initial_size ); + monotonic_buffer_resource( std::size_t initial_size, + memory_resource* upstream \fB(4)\fP (library fundamentals TS) + ); + monotonic_buffer_resource( void* buffer, std::size_t \fB(5)\fP (library fundamentals TS) + buffer_size ); + monotonic_buffer_resource( void* buffer, std::size_t + buffer_size, \fB(6)\fP (library fundamentals TS) + memory_resource* upstream + ); + monotonic_buffer_resource( const \fB(7)\fP (library fundamentals TS) + monotonic_buffer_resource& ) = delete; + + Constructs a monotonic_buffer_resource. The constructors not taking an upstream + memory resource pointer uses the return value of + std::experimental::pmr::get_default_resource() as the upstream memory resource. + + 1,2) Sets the current buffer to null and the next buffer size to an + implementation-defined size. + 3,4) Sets the current buffer to null and the next buffer size to a size no smaller + than initial_size. + 5,6) Sets the current buffer to buffer and the next buffer size to buffer_size (but + not less than 1). Then increase the next buffer size by an implementation-defined + growth factor (which does not have to be integral). + 7) Copy constructor is deleted. + +.SH Parameters + + upstream - the upstream memory resource to use; must point to a valid memory + resource + initial_size - the minimum size of the first buffer to allocate; must be greater + than zero + buffer - the initial buffer to use + buffer_size - the size of the initial buffer; cannot be greater than the number of + bytes in buffer + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::release.3 b/man/std::experimental::pmr::monotonic_buffer_resource::release.3 new file mode 100644 index 000000000..4eb6d0d8d --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::release.3 @@ -0,0 +1,21 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::release \- std::experimental::pmr::monotonic_buffer_resource::release + +.SH Synopsis + void release(); (library fundamentals TS) + + Releases all allocated memory by calling the deallocate function on the upstream + memory resource as necessary. + + Memory is released back to the upstream resource even if deallocate has not been + called for some of the allocated blocks. + +.SH See also + + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::upstream_resource.3 b/man/std::experimental::pmr::monotonic_buffer_resource::upstream_resource.3 new file mode 100644 index 000000000..138245423 --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::upstream_resource.3 @@ -0,0 +1,17 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::upstream_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::upstream_resource \- std::experimental::pmr::monotonic_buffer_resource::upstream_resource + +.SH Synopsis + memory_resource* upstream_resource() const; (library fundamentals TS) + + Returns a pointer to the upstream memory resource. This is the same value as the + upstream argument passed to the constructor of this object. + +.SH See also + + constructor constructs a monotonic_buffer_resource + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::monotonic_buffer_resource::~monotonic_buffer_resource.3 b/man/std::experimental::pmr::monotonic_buffer_resource::~monotonic_buffer_resource.3 new file mode 100644 index 000000000..de50d9d10 --- /dev/null +++ b/man/std::experimental::pmr::monotonic_buffer_resource::~monotonic_buffer_resource.3 @@ -0,0 +1,18 @@ +.TH std::experimental::pmr::monotonic_buffer_resource::~monotonic_buffer_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::monotonic_buffer_resource::~monotonic_buffer_resource \- std::experimental::pmr::monotonic_buffer_resource::~monotonic_buffer_resource + +.SH Synopsis + virtual ~monotonic_buffer_resource(); (library fundamentals TS) + + Destroys a monotonic_buffer_resource. + + Deallocates all memory owned by this resource by calling this->release(). + +.SH See also + + release release all allocated memory + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::new_delete_resource.3 b/man/std::experimental::pmr::new_delete_resource.3 new file mode 100644 index 000000000..741610073 --- /dev/null +++ b/man/std::experimental::pmr::new_delete_resource.3 @@ -0,0 +1,24 @@ +.TH std::experimental::pmr::new_delete_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::new_delete_resource \- std::experimental::pmr::new_delete_resource + +.SH Synopsis + Defined in header + memory_resource* new_delete_resource() noexcept; (library fundamentals TS) + + Returns a pointer to a memory_resource that uses the global operator new and + operator delete to allocate memory. + +.SH Return value + + Returns a pointer p to a static storage duration object of a type derived from + std::experimental::pmr::memory_resource, with the following properties: + + * its allocate() function uses ::operator new to allocate memory; + * its deallocate() function uses ::operator delete to deallocate memory; + * for any memory_resource r, p->is_equal(r) returns &r == p. + + The same value is returned every time this function is called. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::null_memory_resource.3 b/man/std::experimental::pmr::null_memory_resource.3 new file mode 100644 index 000000000..8b02448b1 --- /dev/null +++ b/man/std::experimental::pmr::null_memory_resource.3 @@ -0,0 +1,23 @@ +.TH std::experimental::pmr::null_memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::null_memory_resource \- std::experimental::pmr::null_memory_resource + +.SH Synopsis + Defined in header + memory_resource* null_memory_resource() noexcept; (library fundamentals TS) + + Returns a pointer to a memory_resource that doesn't perform any allocation. + +.SH Return value + + Returns a pointer p to a static storage duration object of a type derived from + std::experimental::pmr::memory_resource, with the following properties: + + * its allocate() function always throws std::bad_alloc; + * its deallocate() function has no effect; + * for any memory_resource r, p->is_equal(r) returns &r == p. + + The same value is returned every time this function is called. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator.3 b/man/std::experimental::pmr::polymorphic_allocator.3 new file mode 100644 index 000000000..184ef0d21 --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator.3 @@ -0,0 +1,52 @@ +.TH std::experimental::pmr::polymorphic_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator \- std::experimental::pmr::polymorphic_allocator + +.SH Synopsis + Defined in header + template< class T > (library fundamentals TS) + class polymorphic_allocator; + + The class template std::experimental::pmr::polymorphic_allocator is an Allocator + whose allocation behavior depends on the memory resource it is constructed with. + Thus, different instances of polymorphic_allocator can exhibit entirely different + allocation behavior. This runtime polymorphism allows objects using + polymorphic_allocator to behave as if they used different allocator types at run + time despite the identical static allocator type. + +.SH Member types + + Member type definition + value_type T + +.SH Member functions + + constructor constructs a polymorphic_allocator + \fI(public member function)\fP + destructor implicitly declared destructor + (implicitly declared) \fI(public member function)\fP + operator= copy assignment operator + \fI(public member function)\fP +.SH Public member functions + allocate allocate memory + \fI(public member function)\fP + deallocate deallocate memory + \fI(public member function)\fP + construct constructs an object in allocated storage + \fI(public member function)\fP + destroy destroys an object in allocated storage + \fI(public member function)\fP + create a new polymorphic_allocator for use by + select_on_container_copy_construction a container's copy constructor + \fI(public member function)\fP + returns a pointer to the underlying memory + resource resource + \fI(public member function)\fP + +.SH Non-member functions + + operator== compare two polymorphic_allocators + operator!= \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::allocate.3 b/man/std::experimental::pmr::polymorphic_allocator::allocate.3 new file mode 100644 index 000000000..e2d86fac8 --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::allocate.3 @@ -0,0 +1,30 @@ +.TH std::experimental::pmr::polymorphic_allocator::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::allocate \- std::experimental::pmr::polymorphic_allocator::allocate + +.SH Synopsis + T* allocate( std::size_t n ); (library fundamentals TS) + + Allocates storage for n objects of type T using the underlying memory resource. + Equivalent to + + return static_cast(this->resource()->allocate(n * sizeof(T), alignof(T)));. + +.SH Parameters + + n - the number of objects to allocate storage for + +.SH Return value + + A pointer to the allocated storage. + +.SH See also + + allocate allocates uninitialized storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::construct.3 b/man/std::experimental::pmr::polymorphic_allocator::construct.3 new file mode 100644 index 000000000..b4cbe907a --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::construct.3 @@ -0,0 +1,124 @@ +.TH std::experimental::pmr::polymorphic_allocator::construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::construct \- std::experimental::pmr::polymorphic_allocator::construct + +.SH Synopsis + template< class U, class... Args > \fB(1)\fP (library fundamentals TS) + void construct( U* p, Args&&... args ); + template< class T1, class T2, class... Args1, class... + Args2 > + + void construct( std::pair* p, \fB(2)\fP (library fundamentals TS) + std::piecewise_construct_t, + std::tuple x, + + std::tuple y ); + template< class T1, class T2 > \fB(3)\fP (library fundamentals TS) + void construct( std::pair* p ); + template< class T1, class T2, class U, class V > \fB(4)\fP (library fundamentals TS) + void construct( std::pair* p, U&& x, V&& y ); + template< class T1, class T2, class U, class V > + void construct( std::pair* p, const \fB(5)\fP (library fundamentals TS) + std::pair& xy ); + template< class T1, class T2, class U, class V > + void construct( std::pair* p, std::pair&& xy ); + + Constructs an object in allocated, but not initialized storage pointed to by p the + provided constructor arguments. If the object is of type that itself uses + allocators, or if it is std::pair, passes this->resource() down to the constructed + object. + + 1) If std::uses_allocator::value == false (the type U does not + use allocators) and std::is_constructible::value == true, then + constructs the object as if by ::new((void *) p) U(std::forward(args)...);. + + Otherwise, if std::uses_allocator::value == true (the type U + uses allocators, e.g. it is a container) and std::is_constructible::value == true, then constructs the + object as if by ::new((void *) p) U(std::allocator_arg, this->resource(), + std::forward(args)...);. + + Otherwise, if std::uses_allocator::value == true (the type U + uses allocators, e.g. it is a container) and std::is_constructible::value == true, then constructs the object as if by ::new((void *) + p) U(std::forward(args)..., this->resource());. + + Otherwise, the program is ill-formed. + + 2) First, if either T1 or T2 is allocator-aware, modifies the tuples x and y to + include this->resource(), resulting in the two new tuples xprime and yprime, + according to the following three rules: + + 2a) if T1 is not allocator-aware (std::uses_allocator::value + == false) and std::is_constructible::value == true, then xprime is x, + unmodified. + + 2b) if T1 is allocator-aware (std::uses_allocator::value == + true), and its constructor takes an allocator tag (std::is_constructible::value == true, then xprime is + std::tuple_cat(std::make_tuple(std::allocator_arg, this->resource()), std::move(x)). + + 2c) if T1 is allocator-aware (std::uses_allocator::value == + true), and its constructor takes the allocator as the last argument + (std::is_constructible::value == true), then xprime + is std::tuple_cat(std::move(x), std::make_tuple(this->resource())). + + 2d) Otherwise, the program is ill-formed. + + Same rules apply to T2 and the replacement of y with yprime. + + Once xprime and yprime are constructed, constructs the pair p in allocated storage + as if by ::new((void *) p) pair(std::piecewise_construct, std::move(xprime), + std::move(yprime));. + + 3) Equivalent to construct(p, std::piecewise_construct, std::tuple<>(), + std::tuple<>()), that is, passes the memory resource on to the pair's member types + if they accept them. + + 4) Equivalent to + + construct(p, std::piecewise_construct, std::forward_as_tuple(std::forward(x)), + std::forward_as_tuple(std::forward(y))) + + 5) Equivalent to + + construct(p, std::piecewise_construct, std::forward_as_tuple(xy.first), + std::forward_as_tuple(xy.second)) + + 6) Equivalent to + + construct(p, std::piecewise_construct, + std::forward_as_tuple(std::forward(xy.first)), + + std::forward_as_tuple(std::forward(xy.second))) + +.SH Parameters + + p - pointer to allocated, but not initialized storage + args... - the constructor arguments to pass to the constructor of T + x - the constructor arguments to pass to the constructor of T1 + y - the constructor arguments to pass to the constructor of T2 + xy - the pair whose two members are the constructor arguments for T1 and T2 + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called (through std::allocator_traits) by any allocator-aware + object, such as std::vector, that was given a std::polymorphic_allocator as the + allocator to use. Since memory_resource* implicitly converts to + polymorphic_allocator, the memory resource pointer will propagate to any + allocator-aware subobjects using polymorphic allocators. + +.SH See also + + construct constructs an object in the allocated storage + \fB[static]\fP \fI(function template)\fP + construct constructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::deallocate.3 b/man/std::experimental::pmr::polymorphic_allocator::deallocate.3 new file mode 100644 index 000000000..adf7f1e4e --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::deallocate.3 @@ -0,0 +1,32 @@ +.TH std::experimental::pmr::polymorphic_allocator::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::deallocate \- std::experimental::pmr::polymorphic_allocator::deallocate + +.SH Synopsis + void deallocate( T* p, std::size_t n ); (library fundamentals TS) + + Deallocates the storage pointed to by p, which must have been allocated from a + memory_resource x that compares equal to *resource() using x.allocate(n * sizeof(T), + alignof(T)). + + Equivalent to this->resource()->deallocate(p, n * sizeof(T), alignof(T));. + +.SH Parameters + + p - pointer to memory to deallocate + n - the number of objects originally allocated + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate deallocates storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::destroy.3 b/man/std::experimental::pmr::polymorphic_allocator::destroy.3 new file mode 100644 index 000000000..0c55ba92e --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::destroy.3 @@ -0,0 +1,21 @@ +.TH std::experimental::pmr::polymorphic_allocator::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::destroy \- std::experimental::pmr::polymorphic_allocator::destroy + +.SH Synopsis + template< class U > (library fundamentals TS) + void destroy( U* p ); + + Destroys the object pointed to by p, as if by calling p->~U(). + +.SH Parameters + + p - pointer to the object being destroyed + +.SH See also + + destroy destructs an object stored in the allocated storage + \fB[static]\fP \fI(function template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::operator=.3 b/man/std::experimental::pmr::polymorphic_allocator::operator=.3 new file mode 100644 index 000000000..64cf6c380 --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::operator=.3 @@ -0,0 +1,21 @@ +.TH std::experimental::pmr::polymorphic_allocator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::operator= \- std::experimental::pmr::polymorphic_allocator::operator= + +.SH Synopsis + polymorphic_allocator& operator=( const (library fundamentals TS) + polymorphic_allocator& rhs ) = default; + + Copy assigns this polymorphic_allocator. Sets the memory resource pointer of *this + to that of rhs. + +.SH Parameters + + rhs - another polymorphic_allocator to copy from + +.SH Return value + + *this + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::polymorphic_allocator.3 b/man/std::experimental::pmr::polymorphic_allocator::polymorphic_allocator.3 new file mode 100644 index 000000000..aae9dfdae --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::polymorphic_allocator.3 @@ -0,0 +1,30 @@ +.TH std::experimental::pmr::polymorphic_allocator::polymorphic_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::polymorphic_allocator \- std::experimental::pmr::polymorphic_allocator::polymorphic_allocator + +.SH Synopsis + polymorphic_allocator() noexcept; \fB(1)\fP + polymorphic_allocator( const polymorphic_allocator& other ) noexcept = default; \fB(2)\fP + template< class U > \fB(3)\fP + polymorphic_allocator( const polymorphic_allocator& other ) noexcept; + polymorphic_allocator( memory_resource* r ); \fB(4)\fP + + Constructs a new polymorphic_allocator. + + 1) Constructs a polymorphic_allocator using the return value of + std::experimental::pmr::get_default_resource() as the underlying memory resource. + 2,3) Constructs a polymorphic_allocator using other.resource() as the underlying + memory resource. + 4) Constructs a polymorphic_allocator using r as the underlying memory resource. + This constructor provides an implicit conversion from memory_resource*. + +.SH Parameters + + other - another polymorphic_allocator to copy from + r - pointer to the memory resource to use. May not be null + +.SH Exceptions + + 4) Throws nothing. +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::resource.3 b/man/std::experimental::pmr::polymorphic_allocator::resource.3 new file mode 100644 index 000000000..02de3de2b --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::resource.3 @@ -0,0 +1,19 @@ +.TH std::experimental::pmr::polymorphic_allocator::resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::resource \- std::experimental::pmr::polymorphic_allocator::resource + +.SH Synopsis + memory_resource* resource() const; (library fundamentals TS) + + Returns the memory resource pointer used by this polymorphic allocator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The memory resource pointer used by this polymorphic allocator. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::polymorphic_allocator::select_on_container_copy_construction.3 b/man/std::experimental::pmr::polymorphic_allocator::select_on_container_copy_construction.3 new file mode 100644 index 000000000..8f660d478 --- /dev/null +++ b/man/std::experimental::pmr::polymorphic_allocator::select_on_container_copy_construction.3 @@ -0,0 +1,31 @@ +.TH std::experimental::pmr::polymorphic_allocator::select_on_container_copy_construction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::polymorphic_allocator::select_on_container_copy_construction \- std::experimental::pmr::polymorphic_allocator::select_on_container_copy_construction + +.SH Synopsis + polymorphic_allocator select_on_container_copy_construction() (library fundamentals + const; TS) + + Returns a default-constructed polymorphic_allocator object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A default-constructed polymorphic_allocator object. + +.SH Notes + + polymorphic_allocators do not propagate on container copy construction. + +.SH See also + + obtains the allocator to use after copying a + select_on_container_copy_construction standard container + \fB[static]\fP \fI\fI(public static member\fP function of\fP + std::allocator_traits) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::pool_options.3 b/man/std::experimental::pmr::pool_options.3 new file mode 100644 index 000000000..0148d6476 --- /dev/null +++ b/man/std::experimental::pmr::pool_options.3 @@ -0,0 +1,47 @@ +.TH std::experimental::pmr::pool_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::pool_options \- std::experimental::pmr::pool_options + +.SH Synopsis + Defined in header + struct pool_options { + + std::size_t max_blocks_per_chunk = 0; (library fundamentals TS) + std::size_t largest_required_pool_block = 0; + + }; + + The struct std::experimental::pmr::pool_options contains a set of constructor + options for std::experimental::pmr::synchronized_pool_resource and + std::experimental::pmr::unsynchronized_pool_resource. + + Data members + + the maximum number of blocks that will be + std::size_t max_blocks_per_chunk allocated at once from the upstream memory + resource to replenish a pool + \fI(public member object)\fP + the largest allocation size that is required + std::size_t largest_required_pool_block to be fulfilled through the pooling + mechanism + \fI(public member object)\fP + + If the value of max_blocks_per_chunk is zero or greater than an + implementation-defined limit, that limit is used instead. The implementation may use + a smaller value than is specified and may use different values for different pools. + + If the value of largest_required_pool_block is zero or greater than an + implementation-defined limit, that limit is used instead. The implementation may use + a threshold greater than specified in this field. + +.SH See also + + a thread-safe memory_resource for managing allocations + synchronized_pool_resource in pools of different block sizes + \fI(class)\fP + a thread-unsafe memory_resource for managing + unsynchronized_pool_resource allocations in pools of different block sizes + \fI(class)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::resource_adaptor,std::pmr::experimental::resource_adaptor.3 b/man/std::experimental::pmr::resource_adaptor,std::pmr::experimental::resource_adaptor.3 new file mode 100644 index 000000000..be0d91dd7 --- /dev/null +++ b/man/std::experimental::pmr::resource_adaptor,std::pmr::experimental::resource_adaptor.3 @@ -0,0 +1,124 @@ +.TH std::experimental::pmr::resource_adaptor,std::pmr::experimental::resource_adaptor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::resource_adaptor,std::pmr::experimental::resource_adaptor \- std::experimental::pmr::resource_adaptor,std::pmr::experimental::resource_adaptor + +.SH Synopsis + Defined in header + template< class Alloc > + + using resource_adaptor = /*resource-adaptor-imp*/< + typename (library fundamentals TS) + std::allocator_traits:: + + template + rebind_alloc>; + template< class Alloc > + class /*resource-adaptor-imp*/ : public memory_resource; (library fundamentals TS) + // for exposition only + + The alias template resource_adaptor adapts the allocator type Alloc with a + memory_resource interface. The allocator is rebound to a char value type before it + is actually adapted (using the resource-adaptor-imp class template), so that + adapting specializations of the same allocator template always yields the same type, + regardless of the value type the allocator template is originally instantiated with. + + resource_adaptor is defined in namespace (library fundamentals + std::experimental::pmr, and the base type memory_resorce in TS) + this page is std::experimental::pmr::memory_resource. (until library + fundamentals TS v3) + resource_adaptor is defined in namespace (library fundamentals + std::pmr::experimental, and the base type memory_resorce in TS v3) + this page is std::pmr::memory_resource. + + resource-adaptor-imp is a class template whose members are described below. The name + resource-adaptor-imp is for exposition purposes only and not normative. + + In addition to meeting the Allocator requirements, Alloc must additionally satisfy + the following requirements: + + * std::allocator_traits::pointer shall be identical to Alloc::value_type*. + * std::allocator_traits::const_pointer shall be identical to + Alloc::value_type const*. + * std::allocator_traits::void_pointer shall be identical to void*. + * std::allocator_traits::const_const_pointer shall be identical to void + const*. + + Member types of resource-adaptor-imp + + Member type Definition + allocator_type Alloc + + Member functions of resource-adaptor-imp + +resource-adaptor-imp::resource-adaptor-imp + + /*resource-adaptor-imp*/() = default; \fB(1)\fP (library + fundamentals TS) + /*resource-adaptor-imp*/(const /*resource-adaptor-imp*/& (library + other) \fB(2)\fP fundamentals TS) + = default; + /*resource-adaptor-imp*/(/*resource-adaptor-imp*/&& other) \fB(3)\fP (library + = default; fundamentals TS) + explicit /*resource-adaptor-imp*/(const Alloc& a2); \fB(4)\fP (library + fundamentals TS) + explicit /*resource-adaptor-imp*/(Alloc&& a2); \fB(5)\fP (library + fundamentals TS) + + 1) Default constructor. Default constructs the wrapped allocator. + 2) Copy constructor. Copy constructs the wrapped allocator from the allocator + wrapped by other. + 3) Move constructor. Move constructs the wrapped allocator from the allocator + wrapped by other. + 4) Initializes the wrapped allocator with a2. + 5) Initializes the wrapped allocator with std::move(a2). + +.SH Parameters + + other - another resource-adaptor-imp object to copy or move from + a2 - another Alloc object to copy or move from + +resource-adaptor-imp::get_allocator + + allocator_type get_allocator() const; (library fundamentals TS) + + Returns a copy of the wrapped allocator. + +resource-adaptor-imp::operator= + + /*resource-adaptor-imp*/& operator=(const + /*resource-adaptor-imp*/& other) (library fundamentals TS) + = default; + + Defaulted copy assignment operator. Copy assigns the wrapped allocator from that of + other. + +resource-adaptor-imp::do_allocate + + protected: + virtual void* do_allocate(std::size_t bytes, std::size_t (library fundamentals TS) + alignment); + + Allocates memory using the allocate member function of the wrapped allocator. + +resource-adaptor-imp::do_deallocate + + protected: + virtual void do_deallocate(void *p, std::size_t bytes, (library fundamentals TS) + std::size_t alignment); + + Deallocates the storage pointed to by p using the deallocate member function of the + wrapped allocator. + + p must have been allocated using the allocate member function of an allocator that + compares equal to the wrapped allocator, and must not have been subsequently + deallocated. + +resource-adaptor-imp::do_is_equal + + protected: + virtual bool do_is_equal(const memory_resource& other) (library fundamentals TS) + const noexcept; + + Let p be dynamic_cast(&other). If p is a null + pointer value, returns false. Otherwise, return the result of comparing the + allocators wrapped by *p and *this using operator==. diff --git a/man/std::experimental::pmr::set_default_resource.3 b/man/std::experimental::pmr::set_default_resource.3 new file mode 100644 index 000000000..d58b0261d --- /dev/null +++ b/man/std::experimental::pmr::set_default_resource.3 @@ -0,0 +1,35 @@ +.TH std::experimental::pmr::set_default_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::set_default_resource \- std::experimental::pmr::set_default_resource + +.SH Synopsis + Defined in header + memory_resource* set_default_resource( memory_resource* r (library fundamentals TS) + ) noexcept; + + If r is not null, sets the default memory resource pointer to r; otherwise, sets the + default memory resource pointer to new_delete_resource(). + + The default memory resource pointer is used by certain facilities when an explicit + memory resource is not supplied. The initial default memory resource pointer is the + return value of new_delete_resource(). + + This function is thread-safe. Every call to set_default_resource synchronizes with + (see std::memory_order) the subsequent set_default_resource and get_default_resource + calls. + +.SH Return value + + Returns the previous value of the default memory resource pointer. + +.SH See also + + get_default_resource gets the default memory_resource + \fI(function)\fP + returns a static program-wide memory_resource that uses the + new_delete_resource global operator new and operator delete to allocate and + deallocate memory + \fI(function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource.3 b/man/std::experimental::pmr::synchronized_pool_resource.3 new file mode 100644 index 000000000..e4156cb0a --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource.3 @@ -0,0 +1,60 @@ +.TH std::experimental::pmr::synchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource \- std::experimental::pmr::synchronized_pool_resource + +.SH Synopsis + Defined in header + class synchronized_pool_resource : public (library fundamentals TS) + memory_resource; + + The class std::experimental::pmr::synchronized_pool_resource is a general-purpose + memory resource class with the following properties: + + * It owns the allocated memory and frees it on destruction, even if deallocate has + not been called for some of the allocated blocks. + * It consists of a collection of pools that serves request for different block + sizes. Each pool manages a collection of chunks that are then divided into + blocks of uniform size. + * Calls to do_allocate are dispatched to the pool serving the smallest blocks + accommodating the requested size. + * Exhausting memory in the pool causes the next allocation request for that pool + to allocate an additional chunk of memory from the upstream allocator to + replenish the pool. The chunk size obtained increases geometrically. + * Allocations requests that exceed the largest block size are served from the + upstream allocator directly. + * The largest block size and maximum chunk size may be tuned by passing a + std::experimental::pmr::pool_options struct to its constructor. + + synchronized_pool_resource may be accessed from multiple threads without external + synchronization, and may have thread-specific pools to reduce synchronization costs. + If the memory resource is only accessed from one thread, + unsynchronized_pool_resource is more efficient. + +.SH Member functions + + constructor constructs a synchronized_pool_resource + \fI(public member function)\fP + destructor destroys a synchronized_pool_resource, releasing all allocated + \fB[virtual]\fP memory + \fI(virtual public member function)\fP + operator= copy assignment operator is deleted. synchronized_pool_resource is + [deleted] not copy assignable + \fI(public member function)\fP +.SH Public member functions + release release all allocated memory + \fI(public member function)\fP + upstream_resource returns a pointer to the upstream memory resource + \fI(public member function)\fP + returns the options that control the pooling behavior of this + options resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocate memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate return memory to the pool + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::do_allocate.3 b/man/std::experimental::pmr::synchronized_pool_resource::do_allocate.3 new file mode 100644 index 000000000..f80f3410e --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::do_allocate.3 @@ -0,0 +1,38 @@ +.TH std::experimental::pmr::synchronized_pool_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::do_allocate \- std::experimental::pmr::synchronized_pool_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t (library fundamentals TS) + alignment ); + + Allocates storage. + + If the pool selected for a block of size bytes is unable to satisfy the request from + its internal data structures, calls allocate() on the upstream memory resource to + obtain memory. + + If the size requested is larger than what the largest pool can handle, memory is + allocated by calling allocate() on the upstream memory resource. + +.SH Return value + + A pointer to allocated storage of at least bytes bytes in size, aligned to the + specified alignment if such alignment is supported, and to alignof(std::max_align_t) + otherwise. + +.SH Exceptions + + Throws nothing unless calling allocate() on the upstream memory resource throws. + +.SH See also + + allocates memory + allocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + do_allocate allocates memory + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::do_deallocate.3 b/man/std::experimental::pmr::synchronized_pool_resource::do_deallocate.3 new file mode 100644 index 000000000..ce17e841b --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::do_deallocate.3 @@ -0,0 +1,27 @@ +.TH std::experimental::pmr::synchronized_pool_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::do_deallocate \- std::experimental::pmr::synchronized_pool_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, (library fundamentals TS) + std::size_t alignment ); + + Returns the memory at p to the pool. It is unspecified if or under what + circumstances this operation will result in a call to deallocate() on the upstream + memory resource. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + do_deallocate deallocates memory + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::do_is_equal.3 b/man/std::experimental::pmr::synchronized_pool_resource::do_is_equal.3 new file mode 100644 index 000000000..32b192df2 --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::do_is_equal.3 @@ -0,0 +1,23 @@ +.TH std::experimental::pmr::synchronized_pool_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::do_is_equal \- std::experimental::pmr::synchronized_pool_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const memory_resource& other ) (library fundamentals TS) + const noexcept; + + Compare *this with other for identity - memory allocated using a + synchronized_pool_resource can only be deallocated using that same resource. + +.SH Return value + + this == dynamic_cast(&other) + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::options.3 b/man/std::experimental::pmr::synchronized_pool_resource::options.3 new file mode 100644 index 000000000..e927dfe2c --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::options.3 @@ -0,0 +1,22 @@ +.TH std::experimental::pmr::synchronized_pool_resource::options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::options \- std::experimental::pmr::synchronized_pool_resource::options + +.SH Synopsis + pool_options options() const; (library fundamentals TS) + + Returns the options that controls the pooling behavior of this resource. + + The values in the returned struct may differ from those supplied to the constructor + in the following ways: + + * Values of zero will be replaced with implementation-specified defaults; + * Sizes may be rounded to an unspecified granularity. + +.SH See also + + constructor constructs a synchronized_pool_resource + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::release.3 b/man/std::experimental::pmr::synchronized_pool_resource::release.3 new file mode 100644 index 000000000..9e5449526 --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::release.3 @@ -0,0 +1,21 @@ +.TH std::experimental::pmr::synchronized_pool_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::release \- std::experimental::pmr::synchronized_pool_resource::release + +.SH Synopsis + void release(); (library fundamentals TS) + + Releases all memory owned by this resource by calling the deallocate function of the + upstream memory resource as needed. + + Memory is released back to the upstream resource even if deallocate has not been + called for some of the allocated blocks. + +.SH See also + + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::synchronized_pool_resource.3 b/man/std::experimental::pmr::synchronized_pool_resource::synchronized_pool_resource.3 new file mode 100644 index 000000000..aa0eeb32a --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::synchronized_pool_resource.3 @@ -0,0 +1,38 @@ +.TH std::experimental::pmr::synchronized_pool_resource::synchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::synchronized_pool_resource \- std::experimental::pmr::synchronized_pool_resource::synchronized_pool_resource + +.SH Synopsis + synchronized_pool_resource(); \fB(1)\fP (library fundamentals TS) + explicit synchronized_pool_resource( memory_resource* \fB(2)\fP (library fundamentals TS) + upstream ); + explicit synchronized_pool_resource( const \fB(3)\fP (library fundamentals TS) + pool_options& opts ); + synchronized_pool_resource( const pool_options& opts, + memory_resource* upstream \fB(4)\fP (library fundamentals TS) + ); + synchronized_pool_resource( const \fB(5)\fP (library fundamentals TS) + synchronized_pool_resource& ) = delete; + + Constructs a synchronized_pool_resource. + + 1-4) Constructs a synchronized_pool_resource using the specified upstream memory + resource and tuned according to the specified options. The resulting object holds a + copy of upstream but does not own the resource to which upstream points. + The overloads not taking opts as a parameter uses a default constructed instance of + pool_options as the options. The overloads not taking upstream as a parameter uses + the return value of std::experimental::pmr::get_default_resource() as the upstream + memory resource. + 5) Copy constructor is deleted. + +.SH Parameters + + opts - a pool_options struct containing the constructor options + upstream - the upstream memory resource to use + +.SH Exceptions + + 1-4) Throws only if a call to the allocate() function of the upstream resource + throws. It is unspecified if or under what conditions such a call takes place. +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::upstream_resource.3 b/man/std::experimental::pmr::synchronized_pool_resource::upstream_resource.3 new file mode 100644 index 000000000..9266a745e --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::upstream_resource.3 @@ -0,0 +1,17 @@ +.TH std::experimental::pmr::synchronized_pool_resource::upstream_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::upstream_resource \- std::experimental::pmr::synchronized_pool_resource::upstream_resource + +.SH Synopsis + memory_resource* upstream_resource() const; (library fundamentals TS) + + Returns a pointer to the upstream memory resource. This is the same value as the + upstream argument passed to the constructor of this object. + +.SH See also + + constructor constructs a synchronized_pool_resource + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::synchronized_pool_resource::~synchronized_pool_resource.3 b/man/std::experimental::pmr::synchronized_pool_resource::~synchronized_pool_resource.3 new file mode 100644 index 000000000..12d0754b6 --- /dev/null +++ b/man/std::experimental::pmr::synchronized_pool_resource::~synchronized_pool_resource.3 @@ -0,0 +1,18 @@ +.TH std::experimental::pmr::synchronized_pool_resource::~synchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::synchronized_pool_resource::~synchronized_pool_resource \- std::experimental::pmr::synchronized_pool_resource::~synchronized_pool_resource + +.SH Synopsis + virtual ~synchronized_pool_resource(); (library fundamentals TS) + + Destroys a synchronized_pool_resource. + + Deallocates all memory owned by this resource by calling this->release(). + +.SH See also + + release release all allocated memory + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource.3 b/man/std::experimental::pmr::unsynchronized_pool_resource.3 new file mode 100644 index 000000000..e237af599 --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource.3 @@ -0,0 +1,59 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource \- std::experimental::pmr::unsynchronized_pool_resource + +.SH Synopsis + Defined in header + class unsynchronized_pool_resource : public (library fundamentals TS) + memory_resource; + + The class std::experimental::pmr::unsynchronized_pool_resource is a general-purpose + memory resource class with the following properties: + + * It owns the allocated memory and frees it on destruction, even if deallocate has + not been called for some of the allocated blocks. + * It consists of a collection of pools that serves request for different block + sizes. Each pool manages a collection of chunks that are then divided into + blocks of uniform size. + * Calls to do_allocate are dispatched to the pool serving the smallest blocks + accommodating the requested size. + * Exhausting memory in the pool causes the next allocation request for that pool + to allocate an additional chunk of memory from the upstream allocator to + replenish the pool. The chunk size obtained increases geometrically. + * Allocations requests that exceed the largest block size are served from the + upstream allocator directly. + * The largest block size and maximum chunk size may be tuned by passing a + std::experimental::pmr::pool_options struct to its constructor. + + unsynchronized_pool_resource is not thread-safe, and cannot be accessed from + multiple threads simultaneously; use synchronized_pool_resource if access from + multiple threads is required. + +.SH Member functions + + constructor constructs an unsynchronized_pool_resource + \fI(public member function)\fP + destructor destroys an unsynchronized_pool_resource, releasing all allocated + \fB[virtual]\fP memory + \fI(virtual public member function)\fP + operator= copy assignment operator is deleted. unsynchronized_pool_resource + [deleted] is not copy assignable + \fI(public member function)\fP +.SH Public member functions + release release all allocated memory + \fI(public member function)\fP + upstream_resource returns a pointer to the upstream memory resource + \fI(public member function)\fP + returns the options that control the pooling behavior of this + options resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocate memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate return memory to the pool + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::do_allocate.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::do_allocate.3 new file mode 100644 index 000000000..ab2ffda5b --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::do_allocate.3 @@ -0,0 +1,38 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::do_allocate \- std::experimental::pmr::unsynchronized_pool_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t (library fundamentals TS) + alignment ); + + Allocates storage. + + If the pool selected for a block of size bytes is unable to satisfy the request from + its internal data structures, calls allocate() on the upstream memory resource to + obtain memory. + + If the size requested is larger than what the largest pool can handle, memory is + allocated by calling allocate() on the upstream memory resource. + +.SH Return value + + A pointer to allocated storage of at least bytes bytes in size, aligned to the + specified alignment if such alignment is supported, and to alignof(std::max_align_t) + otherwise. + +.SH Exceptions + + Throws nothing unless calling allocate() on the upstream memory resource throws. + +.SH See also + + allocates memory + allocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + do_allocate allocates memory + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::do_deallocate.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::do_deallocate.3 new file mode 100644 index 000000000..8d5d4da11 --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::do_deallocate.3 @@ -0,0 +1,27 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::do_deallocate \- std::experimental::pmr::unsynchronized_pool_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, (library fundamentals TS) + std::size_t alignment ); + + Returns the memory at p to the pool. It is unspecified if or under what + circumstances this operation will result in a call to deallocate() on the upstream + memory resource. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + do_deallocate deallocates memory + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::do_is_equal.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::do_is_equal.3 new file mode 100644 index 000000000..224ba9dc2 --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::do_is_equal.3 @@ -0,0 +1,23 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::do_is_equal \- std::experimental::pmr::unsynchronized_pool_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const memory_resource& other ) (library fundamentals TS) + const noexcept; + + Compare *this with other for identity - memory allocated using an + unsynchronized_pool_resource can only be deallocated using that same resource. + +.SH Return value + + this == dynamic_cast(&other) + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::experimental::pmr::memory_resource) + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::options.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::options.3 new file mode 100644 index 000000000..ea31b3ed6 --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::options.3 @@ -0,0 +1,22 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::options \- std::experimental::pmr::unsynchronized_pool_resource::options + +.SH Synopsis + pool_options options() const; (library fundamentals TS) + + Returns the options that controls the pooling behavior of this resource. + + The values in the returned struct may differ from those supplied to the constructor + in the following ways: + + * Values of zero will be replaced with implementation-specified defaults; + * Sizes may be rounded to an unspecified granularity. + +.SH See also + + constructor constructs an unsynchronized_pool_resource + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::release.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::release.3 new file mode 100644 index 000000000..5e5ed8eec --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::release.3 @@ -0,0 +1,21 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::release \- std::experimental::pmr::unsynchronized_pool_resource::release + +.SH Synopsis + void release(); (library fundamentals TS) + + Releases all memory owned by this resource by calling the deallocate function of the + upstream memory resource as needed. + + Memory is released back to the upstream resource even if deallocate has not been + called for some of the allocated blocks. + +.SH See also + + deallocates memory + deallocate \fI(public member function of std::experimental::pmr::memory_resource)\fP + + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource.3 new file mode 100644 index 000000000..336874933 --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource.3 @@ -0,0 +1,38 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource \- std::experimental::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource + +.SH Synopsis + unsynchronized_pool_resource(); \fB(1)\fP (library fundamentals + TS) + explicit unsynchronized_pool_resource( memory_resource* \fB(2)\fP (library fundamentals + upstream ); TS) + explicit unsynchronized_pool_resource( const pool_options& \fB(3)\fP (library fundamentals + opts ); TS) + unsynchronized_pool_resource( const pool_options& opts, \fB(4)\fP (library fundamentals + memory_resource* upstream ); TS) + unsynchronized_pool_resource( const \fB(5)\fP (library fundamentals + unsynchronized_pool_resource& ) = delete; TS) + + Constructs an unsynchronized_pool_resource. + + 1-4) Constructs an unsynchronized_pool_resource using the specified upstream memory + resource and tuned according to the specified options. The resulting object holds a + copy of upstream but does not own the resource to which upstream points. + The overloads not taking opts as a parameter uses a default constructed instance of + pool_options as the options. The overloads not taking upstream as a parameter uses + the return value of std::experimental::pmr::get_default_resource() as the upstream + memory resource. + 5) Copy constructor is deleted. + +.SH Parameters + + opts - a pool_options struct containing the constructor options + upstream - the upstream memory resource to use + +.SH Exceptions + + 1-4) Throws only if a call to the allocate() function of the upstream resource + throws. It is unspecified if or under what conditions such a call takes place. +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::upstream_resource.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::upstream_resource.3 new file mode 100644 index 000000000..7baa2c03a --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::upstream_resource.3 @@ -0,0 +1,17 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::upstream_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::upstream_resource \- std::experimental::pmr::unsynchronized_pool_resource::upstream_resource + +.SH Synopsis + memory_resource* upstream_resource() const; (library fundamentals TS) + + Returns a pointer to the upstream memory resource. This is the same value as the + upstream argument passed to the constructor of this object. + +.SH See also + + constructor constructs an unsynchronized_pool_resource + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource.3 b/man/std::experimental::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource.3 new file mode 100644 index 000000000..7ef92ee4b --- /dev/null +++ b/man/std::experimental::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource.3 @@ -0,0 +1,18 @@ +.TH std::experimental::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource \- std::experimental::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource + +.SH Synopsis + virtual ~unsynchronized_pool_resource(); (library fundamentals TS) + + Destroys a unsynchronized_pool_resource. + + Deallocates all memory owned by this resource by calling this->release(). + +.SH See also + + release release all allocated memory + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::popcount.3 b/man/std::experimental::popcount.3 new file mode 100644 index 000000000..86664892b --- /dev/null +++ b/man/std::experimental::popcount.3 @@ -0,0 +1,57 @@ +.TH std::experimental::popcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::popcount \- std::experimental::popcount + +.SH Synopsis + Defined in header + template< class T, class Abi > (parallelism TS v2) + int popcount( const simd_mask& k ) noexcept; + + Returns the number of true values in the mask k. + +.SH Parameters + + k - the simd_mask to apply the reduction to + +.SH Return value + + An int in the range [0, simd_size_v). + +.SH Example + + +// Run this code + + #include + #include + #include + namespace stdx = std::experimental; + + template + int count_zeros(stdx::simd v) + { + return stdx::popcount(v == 0); // v == 0 returns a simd_mask + } + + void println(auto rem, auto const v) + { + std::cout << rem << ": "; + for (std::size_t i = 0; i != v.size(); ++i) + std::cout << v[i] << ' '; + } + + int main() + { + stdx::simd x{8}; + println("x", x); + std::cout << " zeros: " << count_zeros(x) << '\\n'; + + x[3] = x[1] = false; + println("x", x); + std::cout << " zeros: " << count_zeros(x) << '\\n'; + } + +.SH Possible output: + + x: 8 8 8 8 zeros: 0 + x: 8 0 8 0 zeros: 2 diff --git a/man/std::experimental::promise(concurrencyTS).3 b/man/std::experimental::promise(concurrencyTS).3 new file mode 100644 index 000000000..067fa7c76 --- /dev/null +++ b/man/std::experimental::promise(concurrencyTS).3 @@ -0,0 +1,15 @@ +.TH std::experimental::promise(concurrencyTS) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::promise(concurrencyTS) \- std::experimental::promise(concurrencyTS) + +.SH Synopsis + Defined in header + template< class R > class promise; \fB(1)\fP (concurrency TS) + template< class R > class promise; \fB(2)\fP (concurrency TS) + template<> class promise; \fB(3)\fP (concurrency TS) + + std::experimental::concurrency_v1::promise is a modified version of std::promise + provided by the concurrency TS that works with std::experimental::future. + + The only change from std::promise is that the get_future() member function returns a + std::experimental::future. diff --git a/man/std::experimental::promise(libraryfundamentalsTS).3 b/man/std::experimental::promise(libraryfundamentalsTS).3 new file mode 100644 index 000000000..f22758c91 --- /dev/null +++ b/man/std::experimental::promise(libraryfundamentalsTS).3 @@ -0,0 +1,63 @@ +.TH std::experimental::promise(libraryfundamentalsTS) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::promise(libraryfundamentalsTS) \- std::experimental::promise(libraryfundamentalsTS) + +.SH Synopsis + Defined in header + template< class R > class promise; \fB(1)\fP (library fundamentals TS) + template< class R > class promise; \fB(2)\fP (library fundamentals TS) + template<> class promise; \fB(3)\fP (library fundamentals TS) + + std::experimental::fundamentals_v1::promise (and + std::experimental::fundamentals_v2::promise) is a modified version of std::promise + provided by the library fundamentals TS with support for type-erased allocators. + +.SH Member types + + Member type Definition + allocator_type std::experimental::erased_type + +.SH Member functions + + constructor constructs the promise object + \fI(public member function)\fP + retrieves a pointer to the memory resource used by this object + get_memory_resource to allocate memory + \fI(public member function)\fP + + Non-member function + + std::experimental::swap(std::experimental::promise) specializes the swap algorithm + \fI(function template)\fP + +.SH Helper classes + + specializes the std::uses_allocator + std::uses_allocator type trait + \fI(class template specialization)\fP + + +Members identical to std::promise + +.SH Member functions + + destructor destructs the promise object + \fI(public member function of std::promise)\fP + operator= assigns the shared state + \fI(public member function of std::promise)\fP + swap swaps two promise objects + \fI(public member function of std::promise)\fP +.SH Getting the result + get_future returns a future associated with the promised result + \fI(public member function of std::promise)\fP +.SH Setting the result + set_value sets the result to specific value + \fI(public member function of std::promise)\fP + sets the result to specific value while delivering the + set_value_at_thread_exit notification only at thread exit + \fI(public member function of std::promise)\fP + set_exception sets the result to indicate an exception + \fI(public member function of std::promise)\fP + sets the result to indicate an exception while + set_exception_at_thread_exit delivering the notification only at thread exit + \fI(public member function of std::promise)\fP diff --git a/man/std::experimental::promise::get_memory_resource.3 b/man/std::experimental::promise::get_memory_resource.3 new file mode 100644 index 000000000..c0d512222 --- /dev/null +++ b/man/std::experimental::promise::get_memory_resource.3 @@ -0,0 +1,22 @@ +.TH std::experimental::promise::get_memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::promise::get_memory_resource \- std::experimental::promise::get_memory_resource + +.SH Synopsis + std::experimental::pmr::memory_resource* (library fundamentals + get_memory_resource() const noexcept; TS) + + Returns a pointer to the memory resource used by this object to allocate memory. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the memory resource used by this object to allocate memory. + +.SH See also + + constructor constructs the promise object + \fI(public member function)\fP diff --git a/man/std::experimental::promise::promise(libraryfundamentalsTS).3 b/man/std::experimental::promise::promise(libraryfundamentalsTS).3 new file mode 100644 index 000000000..947e0d36d --- /dev/null +++ b/man/std::experimental::promise::promise(libraryfundamentalsTS).3 @@ -0,0 +1,49 @@ +.TH std::experimental::promise::promise(libraryfundamentalsTS) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::promise::promise(libraryfundamentalsTS) \- std::experimental::promise::promise(libraryfundamentalsTS) + +.SH Synopsis + promise(); \fB(1)\fP (library fundamentals TS) + template< class Alloc > \fB(2)\fP (library fundamentals TS) + promise( std::allocator_arg_t, const Alloc& alloc ); + promise( promise&& other ) noexcept; \fB(3)\fP (library fundamentals TS) + promise( const promise& other ) = delete; \fB(4)\fP (library fundamentals TS) + + Constructs a std::experimental::promise object. + + 1) Default constructor. Constructs the promise with an empty shared state. + 2) Constructs the promise with an empty shared state. The shared state is allocated + using alloc, which is treated as a type-erased allocator (see below). + 3) Move constructor. Constructs the promise with the shared state of other using + move semantics. After construction, other has no shared state. + 4) std::experimental::promise is not copyable. + + Type-erased allocator + + The constructors of promise taking an allocator argument alloc treats that argument + as a type-erased allocator. The memory resource pointer used by promise to allocate + memory is determined using the allocator argument (if specified) as follows: + +Type of alloc Value of the memory resource pointer +Non-existent (no allocator specified at time The value of std::experimental::pmr::get_default_resource() +of construction) at time of construction. +std::nullptr_t The value of std::experimental::pmr::get_default_resource() + at time of construction. +A pointer type convertible to static_cast(alloc) +std::experimental::pmr::memory_resource* +A specialization of alloc.resource() +std::experimental::pmr::polymorphic_allocator + A pointer to a value of type +Any other type meeting the Allocator std::experimental::pmr::resource_adaptor(alloc), where A +requirements is the type of alloc. The pointer remains valid only for the + lifetime of the promise object. +None of the above The program is ill-formed. + +.SH Parameters + + alloc - allocator to use to allocate the shared state + other - another std::experimental::promise to acquire the state from + +.SH Exceptions + + 1,2) \fI(none)\fP diff --git a/man/std::experimental::propagate_const.3 b/man/std::experimental::propagate_const.3 new file mode 100644 index 000000000..6a0159655 --- /dev/null +++ b/man/std::experimental::propagate_const.3 @@ -0,0 +1,144 @@ +.TH std::experimental::propagate_const 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const \- std::experimental::propagate_const + +.SH Synopsis + Defined in header + template< class T > (library fundamentals TS v2) + class propagate_const; + + std::experimental::propagate_const is a const-propagating wrapper for pointers and + pointer-like objects. It treats the wrapped pointer as a pointer to const when + accessed through a const access path, hence the name. + + The class satisfies the requirements of MoveConstructible and MoveAssignable if the + underlying pointer-like type satisfies the corresponding requirement, but + propagate_const is neither CopyConstructible nor CopyAssignable. + +.SH Type requirements + - + T must be cv-unqualified pointer-to-object type or a cv-unqualified pointer-like + class type, as specified below. + +.SH Member types + + Member type Definition + element_type std::remove_reference_t())>, the type of the + object pointed to by T + +.SH Member functions + + constructor constructs a new propagate_const + \fI(public member function)\fP + destructor destructs a propagate_const, destroying the contained + (implicitly declared) pointer + \fI(public member function)\fP + operator= assigns the propagate_const object + \fI(public member function)\fP + swap swaps the wrapped pointer + \fI(public member function)\fP +.SH Observers + returns a pointer to the object pointed to by the + get wrapped pointer + \fI(public member function)\fP + operator bool checks if the wrapped pointer is null + \fI(public member function)\fP + operator* dereferences the wrapped pointer + operator-> \fI(public member function)\fP + operator element_type* implicit conversion function to pointer + operator const element_type* \fI(public member function)\fP + +.SH Non-member functions + + operator== compares to another + operator!= propagate_const, another + operator< pointer, or with nullptr + operator<= \fI(function template)\fP + operator> + operator>= + specializes the swap + std::experimental::swap(std::experimental::propagate_const) algorithm + \fI(function template)\fP + + retrieves a reference to + the wrapped pointer-like + get_underlying object + \fI(function template)\fP + + +.SH Helper classes + + hash support for + std::hash propagate_const + (class template + specialization) + std::equal_to specializations of the + std::not_equal_to standard comparison function + std::less objects for propagate_const + std::greater (class template + std::less_equal specialization) + std::greater_equal + +.SH Example + + +// Run this code + + #include + #include + #include + + struct X + { + void g() const { std::cout << "X::g (const)\\n"; } + void g() { std::cout << "X::g (non-const)\\n"; } + }; + + struct Y + { + Y() : m_propConstX(std::make_unique()), m_autoPtrX(std::make_unique()) {} + + void f() const + { + std::cout << "Y::f (const)\\n"; + m_propConstX->g(); + m_autoPtrX->g(); + } + + void f() + { + std::cout << "Y::f (non-const)\\n"; + m_propConstX->g(); + m_autoPtrX->g(); + } + + std::experimental::propagate_const> m_propConstX; + std::unique_ptr m_autoPtrX; + }; + + int main() + { + Y y; + y.f(); + + const Y cy; + cy.f(); + } + +.SH Output: + + Y::f (non-const) + X::g (non-const) + X::g (non-const) + Y::f (const) + X::g (const) + X::g (non-const) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3136 LFTSv2 meaningless T like int* const, void*, or const disallowed + PtrLike were allowed diff --git a/man/std::experimental::propagate_const::get.3 b/man/std::experimental::propagate_const::get.3 new file mode 100644 index 000000000..48ff55461 --- /dev/null +++ b/man/std::experimental::propagate_const::get.3 @@ -0,0 +1,25 @@ +.TH std::experimental::propagate_const::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::get \- std::experimental::propagate_const::get + +.SH Synopsis + constexpr element_type* get(); (library fundamentals TS v2) + constexpr const element_type* get() const; (library fundamentals TS v2) + + Returns a pointer to the object pointed to by the wrapped pointer-like object, t_. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If T is an object pointer type, then t_. Otherwise, t_.get(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::propagate_const::operator*,.3 b/man/std::experimental::propagate_const::operator*,.3 new file mode 100644 index 000000000..b6032a0cb --- /dev/null +++ b/man/std::experimental::propagate_const::operator*,.3 @@ -0,0 +1,37 @@ +.TH std::experimental::propagate_const::operator*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::operator*, \- std::experimental::propagate_const::operator*, + +.SH Synopsis + + constexpr element_type& operator*(); \fB(1)\fP (library fundamentals TS v2) + constexpr const element_type& operator*() const; \fB(2)\fP (library fundamentals TS v2) + constexpr element_type* operator->(); \fB(3)\fP (library fundamentals TS v2) + constexpr const element_type* operator->() const; \fB(4)\fP (library fundamentals TS v2) + + Provides access to the object pointed to by the pointer-like object *this wraps. + + The behavior of these functions is undefined if get() == nullptr. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,2) The object pointed to by the wrapped pointer-like object, i.e., *get(). + 3,4) A pointer to the object pointed to by the wrapped pointer-like object, i.e., + get(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the object pointed to by the wrapped pointer + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::propagate_const::operator=.3 b/man/std::experimental::propagate_const::operator=.3 new file mode 100644 index 000000000..65a04009a --- /dev/null +++ b/man/std::experimental::propagate_const::operator=.3 @@ -0,0 +1,36 @@ +.TH std::experimental::propagate_const::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::operator= \- std::experimental::propagate_const::operator= + +.SH Synopsis + constexpr propagate_const& operator=( \fB(1)\fP (library fundamentals TS v2) + propagate_const&& p ) = default; + template< class U > + constexpr propagate_const& operator=( \fB(2)\fP (library fundamentals TS v2) + propagate_const&& pu ); + template< class U > \fB(3)\fP (library fundamentals TS v2) + constexpr propagate_const& operator=( U&& u ); + propagate_const& operator=( const propagate_const& \fB(4)\fP (library fundamentals TS v2) + ) = delete; + + Let t_ designate the private data member that is the wrapped pointer-like object. + + 1) Explicitly defaulted move assignment operator that move assigns this->t_ from + p.t_. + 2) Assigns std::move(pu.t_) to this->t_. + This overload participates in overload resolution only if U is implicitly + convertible to T. + 3) Assigns std::forward(u) to this->t_. + This overload participates in overload resolution only if U is implicitly + convertible to T and std::decay_t is not a specialization of propagate_const. + 4) Copy assignment operator is explicitly deleted. propagate_const is non-copyable. + +.SH Parameters + + p - another propagate_const object to move from + pu - another propagate_const object of a different specialization to move from + u - another object to assign to the contained pointer + +.SH Return value + + *this. diff --git a/man/std::experimental::propagate_const::operatorbool.3 b/man/std::experimental::propagate_const::operatorbool.3 new file mode 100644 index 000000000..cb02e73c5 --- /dev/null +++ b/man/std::experimental::propagate_const::operatorbool.3 @@ -0,0 +1,29 @@ +.TH std::experimental::propagate_const::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::operatorbool \- std::experimental::propagate_const::operatorbool + +.SH Synopsis + constexpr explicit operator bool() const; (library fundamentals TS v2) + + Checks whether the wrapped pointer-like object, t_, is null. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the wrapped object is not null, otherwise false. Equivalent to (bool)t_. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the object pointed to by the wrapped pointer + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::propagate_const::operatorelement_type*,.3 b/man/std::experimental::propagate_const::operatorelement_type*,.3 new file mode 100644 index 000000000..c07ea49e7 --- /dev/null +++ b/man/std::experimental::propagate_const::operatorelement_type*,.3 @@ -0,0 +1,37 @@ +.TH std::experimental::propagate_const::operatorelement_type*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::operatorelement_type*, \- std::experimental::propagate_const::operatorelement_type*, + +.SH Synopsis + + constexpr operator element_type*(); \fB(1)\fP (library fundamentals TS v2) + constexpr operator const element_type*() const; \fB(2)\fP (library fundamentals TS v2) + + Provides implicit conversions to element_type* and const element_type*. + + 1) This function does not participate in overload resolution unless T is an object + pointer type or is implicitly convertible to element_type*. + 2) This function does not participate in overload resolution unless T is an object + pointer type or is implicitly convertible to const element_type*. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the object pointed to by the wrapped pointer-like object, i.e., + this->get(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns a pointer to the object pointed to by the wrapped pointer + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::propagate_const::propagate_const.3 b/man/std::experimental::propagate_const::propagate_const.3 new file mode 100644 index 000000000..2b70aa991 --- /dev/null +++ b/man/std::experimental::propagate_const::propagate_const.3 @@ -0,0 +1,43 @@ +.TH std::experimental::propagate_const::propagate_const 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::propagate_const \- std::experimental::propagate_const::propagate_const + +.SH Synopsis + constexpr propagate_const() = default; \fB(1)\fP (library fundamentals TS v2) + constexpr propagate_const( propagate_const&& p ) = \fB(2)\fP (library fundamentals TS v2) + default; + template< class U > + /* see below */ constexpr propagate_const( \fB(3)\fP (library fundamentals TS v2) + propagate_const&& pu ); + template< class U > \fB(4)\fP (library fundamentals TS v2) + /* see below */ constexpr propagate_const( U&& u ); + propagate_const( const propagate_const& ) = delete; \fB(5)\fP (library fundamentals TS v2) + + Let t_ designate the private data member that is the wrapped pointer-like object. + + 1) Constructs a propagate_const, default-initializing this->t_. + 2) Explicitly defaulted move constructor that move constructs this->t_ from p.t_. + 3) Initializes this->t_ as if by direct-non-list-initialization from the expression + std::move(pu.t_). + This constructor does not participate in overload resolution unless + std::is_constructible::value is true, and is explicit if and only if + std::is_convertible::value is false. + 4) Initializes this->t_ as if by direct-non-list-initialization with the expression + std::forward(u). + This constructor does not participate in overload resolution unless + std::is_constructible::value is true and std::decay_t is not a + specialization of propagate_const. This constructor is explicit if and only if + std::is_convertible::value is false. + 5) Copy constructor is explicitly deleted. propagate_const is non-copyable. + +.SH Parameters + + p - another propagate_const object to move from + pu - another propagate_const object of a different specialization to move from + u - another object to initialize the contained pointer with + +.SH Notes + + In Library Fundamental TS v2 (based on C++14), \fB(4)\fP and \fB(5)\fP are typically implemented + in explicit/non-explicit overload pairs. Since Library Fundamental TS v3 (based on + C++20), they can be implemented in conditional explicit specifiers. diff --git a/man/std::experimental::propagate_const::swap.3 b/man/std::experimental::propagate_const::swap.3 new file mode 100644 index 000000000..8bb718c7c --- /dev/null +++ b/man/std::experimental::propagate_const::swap.3 @@ -0,0 +1,40 @@ +.TH std::experimental::propagate_const::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::propagate_const::swap \- std::experimental::propagate_const::swap + +.SH Synopsis + constexpr void swap( propagate_const & pt ) (library fundamentals TS v2) + noexcept(/* see below */); + + Swaps the wrapped pointer with that of pt. Let t_ designate the private data member + that is the wrapped pointer-like object, then this function is equivalent to + swap(t_, pt.t_), where the overload resolution for swap is performed among std::swap + and any declaration found by the usual lookup rules, as described in Swappable. + + The behavior is undefined if lvalues of T do not satisfy Swappable. + +.SH Parameters + + pt - another propagate_const object to swap with + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(swap(t_, pt.t_))) + The lookup for the identifier swap in the exception (library + specification finds overloads described above, and does not find fundamentals TS v2) + the member function itself, making the exception specification + equivalent to C++17 std::is_nothrow_swappable. + noexcept specification: (library + noexcept(std::is_nothrow_swappable_v) fundamentals TS v3) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3413 LFTSv2 the exception specification was ill-formed made well-formed + +.SH Category: + * conditionally noexcept diff --git a/man/std::experimental::randint.3 b/man/std::experimental::randint.3 new file mode 100644 index 000000000..8ee1f0dbc --- /dev/null +++ b/man/std::experimental::randint.3 @@ -0,0 +1,50 @@ +.TH std::experimental::randint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::randint \- std::experimental::randint + +.SH Synopsis + Defined in header + template< class IntType > (library fundamentals TS v2) + IntType randint( IntType a, IntType b ); + + Generates a random integer in the closed interval [a, b]. + +.SH Parameters + + a, b - integer values specifying the range + +.SH Return value + + A random integer i in the closed interval [a, b], produced using a thread-local + instance of std::uniform_int_distribution invoked with the per-thread + random number engine. + + Remarks + + If IntType is not one of short, int, long, long long, unsigned short, unsigned int, + unsigned long, or unsigned long long, the program is ill-formed. + + The behavior is undefined if a > b. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int random_number = std::experimental::randint(100, 999); + std::cout << "random 3-digit number: " << random_number << '\\n'; + } + +.SH Possible output: + + random 3-digit number: 273 + +.SH See also + + reseed reseeds the per-thread random engine + \fI(function)\fP diff --git a/man/std::experimental::ranges::Assignable.3 b/man/std::experimental::ranges::Assignable.3 new file mode 100644 index 000000000..f2d4799d3 --- /dev/null +++ b/man/std::experimental::ranges::Assignable.3 @@ -0,0 +1,71 @@ +.TH std::experimental::ranges::Assignable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Assignable \- std::experimental::ranges::Assignable + +.SH Synopsis + Defined in header + template< class T, class U > + + concept bool Assignable = + std::is_lvalue_reference::value && + CommonReference< + const std::remove_reference_t&, (ranges TS) + const std::remove_reference_t&> && + requires(T t, U&& u) { + { t = std::forward(u) } -> Same&&; + + }; + + The concept Assignable specifies that an expression of the type and value + category specified by U can be assigned to an lvalue expression whose type is + specified by T. + + Given + + * t, an lvalue of type std::remove_reference_t that refers to an object o, + * u, an expression such that decltype((u)) is U, + * u2, a distinct object that is equal to u, + + Assignable is satisfied only if + + * std::addressof(t = u) == std::addressof(o) (i.e., the assignment expression + yields an lvalue referring to the left operand); + * After evaluating t = u: + * t is equal to u2, unless u is a non-const xvalue that refers to o (i.e., + the assignment is a self-move-assignment), + * if u is a glvalue: + * If it is a non-const xvalue, the object to which it refers is in a + valid but unspecified state; + * Otherwise, the object it refers to is not modified; + + There need not be any subsumption relationship between Assignable and + std::is_lvalue_reference::value. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + +.SH Notes + + A deduction constraint of the form { expression } -> Same&& effectively requires + decltype((expression))&& to be the exact same type as T&&. This constrains both the + expression's type and its value category. + + Assignment need not be a total function. In particular, if assigning to some object + x can cause some other object y to be modified, then x = y is likely not in the + domain of =. This typically happens if the right operand is owned directly or + indirectly by the left operand (e.g., with smart pointers to nodes in a node-based + data structure, or with something like std::vector). diff --git a/man/std::experimental::ranges::BidirectionalIterator.3 b/man/std::experimental::ranges::BidirectionalIterator.3 new file mode 100644 index 000000000..097216d53 --- /dev/null +++ b/man/std::experimental::ranges::BidirectionalIterator.3 @@ -0,0 +1,56 @@ +.TH std::experimental::ranges::BidirectionalIterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::BidirectionalIterator \- std::experimental::ranges::BidirectionalIterator + +.SH Synopsis + Defined in header + template< class I > + + concept bool BidirectionalIterator = + ForwardIterator && + DerivedFrom, + ranges::bidirectional_iterator_tag> && (ranges TS) + requires(I i) { + { --i } -> Same&; + { i-- } -> Same&&; + + }; + + The concept BidirectionalIterator refines ForwardIterator by adding the ability + to move an iterator backward. + + A bidirectional iterator r is said to be decrementable if and only if there exists + some s such that ++s == r. All decrementable iterators r shall be in the domain of + the expressions --r and r--. + + Let a and b be decrementable objects of type I. BidirectionalIterator is + satisfied only if: + + * Pre-decrement yields an lvalue that refers to the operand: std::addressof(--a) + == std::addressof(a). + * Post-decrement yields the previous value of the operand: if bool(a == b), then + bool(a-- == b). + * Post-decrement and pre-decrement perform the same modification on its operand: + If bool(a == b), then after evaluating both a-- and --b, bool(a == b) still + holds. + * Increment and decrement are inverses of each other: + + * If a is incrementable and bool(a == b), then bool(--(++a) == b). + * If bool(a == b), then bool(++(--a) == b). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. diff --git a/man/std::experimental::ranges::BidirectionalRange.3 b/man/std::experimental::ranges::BidirectionalRange.3 new file mode 100644 index 000000000..ccd3fc5c6 --- /dev/null +++ b/man/std::experimental::ranges::BidirectionalRange.3 @@ -0,0 +1,18 @@ +.TH std::experimental::ranges::BidirectionalRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::BidirectionalRange \- std::experimental::ranges::BidirectionalRange + +.SH Synopsis + Defined in header + template< class T > + + concept bool BidirectionalRange = (ranges TS) + ForwardRange && + + BidirectionalIterator>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::Boolean.3 b/man/std::experimental::ranges::Boolean.3 new file mode 100644 index 000000000..ae9a6c8bb --- /dev/null +++ b/man/std::experimental::ranges::Boolean.3 @@ -0,0 +1,82 @@ +.TH std::experimental::ranges::Boolean 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Boolean \- std::experimental::ranges::Boolean + +.SH Synopsis + Defined in header + template< class B > + + concept bool Boolean = + Movable> && + requires(const std::remove_reference_t& b1, + const std::remove_reference_t& b2, const bool a) { + { b1 } -> ConvertibleTo&&; + { !b1 } -> ConvertibleTo&&; + { b1 && a } -> Same&&; + { b1 || a } -> Same&&; + { b1 && b2 } -> Same&&; (ranges TS) + { a && b2 } -> Same&&; + { b1 || b2 } -> Same&&; + { a || b2 } -> Same&&; + { b1 == b2 } -> ConvertibleTo&&; + { b1 == a } -> ConvertibleTo&&; + { a == b2 } -> ConvertibleTo&&; + { b1 != b2 } -> ConvertibleTo&&; + { b1 != a } -> ConvertibleTo&&; + { a != b2 } -> ConvertibleTo&&; + + }; + + The concept Boolean specifies the requirements for a type usable in Boolean + contexts. For Boolean to be satisfied, the logical operators must have the usual + behavior (including short-circuiting). More precisely, given + + * b1, b2, two lvalues of type const std::remove_reference_t, + + Boolean is satisfied only if: + + * bool(b1) == !bool(!b1); + * b1 && b2, b1 && bool(b2) and bool(b1) && b2 are all equal to bool(b1) && + bool(b2) and have the same short-circuit evaluation; + * b1 || b2, b1 || bool(b2) and bool(b1) || b2 are all equal to bool(b1) || + bool(b2) and have the same short-circuit evaluation; + * bool(b1 == b2), bool(b1 == bool(b2)), and bool(bool(b1) == b2) are all equal to + (bool(b1) == bool(b2)); + * bool(b1 != b2), bool(b1 != bool(b2)), and bool(bool(b1) != b2) are all equal to + (bool(b1) != bool(b2)). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + + Implicit expression variations + + A requires-expression that uses an expression that is non-modifying for some + constant lvalue operand also implicitly requires additional variations of that + expression that accept a non-constant lvalue or (possibly constant) rvalue for the + given operand unless such an expression variation is explicitly required with + differing semantics. These implicit expression variations must meet the same + semantic requirements of the declared expression. The extent to which an + implementation validates the syntax of the variations is unspecified. + +.SH Notes + + Examples of Boolean types include bool, std::true_type, and + std::bitset::reference. Pointers are not Boolean types. + + A deduction constraint of the form { expression } -> Same&& effectively requires + decltype((expression))&& to be the exact same type as T&&. This constrains both the + expression's type and its value category. diff --git a/man/std::experimental::ranges::BoundedRange.3 b/man/std::experimental::ranges::BoundedRange.3 new file mode 100644 index 000000000..954127090 --- /dev/null +++ b/man/std::experimental::ranges::BoundedRange.3 @@ -0,0 +1,18 @@ +.TH std::experimental::ranges::BoundedRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::BoundedRange \- std::experimental::ranges::BoundedRange + +.SH Synopsis + Defined in header + template< class T > + + concept bool BoundedRange = (ranges TS) + Range && + + Same, ranges::sentinel_t>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::Common.3 b/man/std::experimental::ranges::Common.3 new file mode 100644 index 000000000..1bf073138 --- /dev/null +++ b/man/std::experimental::ranges::Common.3 @@ -0,0 +1,57 @@ +.TH std::experimental::ranges::Common 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Common \- std::experimental::ranges::Common + +.SH Synopsis + Defined in header + template< class T, class U > + + concept bool Common = + Same, ranges::common_type_t> && + ConvertibleTo> && + ConvertibleTo> && + CommonReference< + std::add_lvalue_reference_t, (ranges TS) + std::add_lvalue_reference_t> && + CommonReference< + std::add_lvalue_reference_t>, + ranges::common_reference_t< + std::add_lvalue_reference_t, + + std::add_lvalue_reference_t>>; + + The concept Common specifies that two types T and U share a common type (as + computed by ranges::common_type_t) to which both can be converted. + + Common is satisfied only if, given expressions t and u such that decltype((t)) + is T and decltype((u)) is U, + + * ranges::common_type_t(t) is equal to ranges::common_type_t(t) if and + only if t is an equality-preserving expression; and + * ranges::common_type_t(u) is equal to ranges::common_type_t(u) if and + only if u is an equality-preserving expression. + + In other words, the conversion to the common type must not alter the + equality-preservation property of the original expression. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH See also + + common_type determine the common type of a set of types + \fI(class template)\fP + common_reference determine the common reference type of a set of types + \fI(class template)\fP + CommonReference specifies that two types share a common reference type + (concept) diff --git a/man/std::experimental::ranges::CommonReference.3 b/man/std::experimental::ranges::CommonReference.3 new file mode 100644 index 000000000..c020a7f3a --- /dev/null +++ b/man/std::experimental::ranges::CommonReference.3 @@ -0,0 +1,51 @@ +.TH std::experimental::ranges::CommonReference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::CommonReference \- std::experimental::ranges::CommonReference + +.SH Synopsis + Defined in header + template< class T, class U > + + concept bool CommonReference = + Same, (ranges TS) + ranges::common_reference_t> && + ConvertibleTo> && + + ConvertibleTo>; + + The concept CommonReference specifies that two types T and U share a common + reference type (as computed by ranges::common_reference_t) to which both can be + converted. + + CommonReference is satisfied only if, given expressions t and u such that + decltype((t)) is T and decltype((u)) is U, + + * ranges::common_reference_t(t) is equal to ranges::common_reference_t(t) if and only if t is an equality-preserving expression; and + * ranges::common_reference_t(u) is equal to ranges::common_reference_t(u) if and only if u is an equality-preserving expression. + + In other words, the conversion to the common reference type must not alter the + equality-preservation property of the original expression. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH See also + + common_reference determine the common reference type of a set of types + \fI(class template)\fP + Common specifies that two types share a common type + (concept) + common_type determine the common type of a set of types + \fI(class template)\fP diff --git a/man/std::experimental::ranges::Constructible.3 b/man/std::experimental::ranges::Constructible.3 new file mode 100644 index 000000000..e403f4676 --- /dev/null +++ b/man/std::experimental::ranges::Constructible.3 @@ -0,0 +1,26 @@ +.TH std::experimental::ranges::Constructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Constructible \- std::experimental::ranges::Constructible + +.SH Synopsis + Defined in header + template< class T, class... Args > + + concept bool Constructible = (ranges TS) + + Destructible && std::is_constructible::value; + + The Constructible concept specifies that a variable of type T can be initialized + with the given set of argument types Args.... + + There need not be any subsumption relationship between Constructible and + std::is_constructible::value. + +.SH See also + + is_constructible + is_trivially_constructible + is_nothrow_constructible checks if a type has a constructor for specific arguments + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::ranges::ConvertibleTo.3 b/man/std::experimental::ranges::ConvertibleTo.3 new file mode 100644 index 000000000..c8e9dc43c --- /dev/null +++ b/man/std::experimental::ranges::ConvertibleTo.3 @@ -0,0 +1,59 @@ +.TH std::experimental::ranges::ConvertibleTo 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::ConvertibleTo \- std::experimental::ranges::ConvertibleTo + +.SH Synopsis + Defined in header + template< class From, class To > + + concept bool ConvertibleTo = + std::is_convertible::value && (ranges TS) + requires(From (&f)()) { + static_cast(f()); + + }; + + The concept ConvertibleTo specifies that an expression of the type and + value category specified by From can be implicitly and explicitly converted to the + type To, and the two forms of conversion are equivalent. + + Specifically, ConvertibleTo is satisfied only if, given the invented + function To test(From (&f)()) { return f(); } and a function f of type From () such + that the expression f() is equality-preserving (see below), + + * Either + * To is neither an object type nor a reference-to-object type, or + * static_cast(f()) is equal to test(f), and + * One of the following is true: + * From is not a reference-to-object type, or + * From is an rvalue reference to a non-const-qualified type, and the + resulting state of the object referenced by f() is valid but unspecified + after either expression above; or + * the object referred to by f() is not modified by either expression above. + + There need not be any subsumption relationship between ConvertibleTo and + std::is_convertible::value. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + +.SH See also + + is_convertible + is_nothrow_convertible checks if a type can be converted to the other type + \fI(C++11)\fP \fI(class template)\fP + (C++20) diff --git a/man/std::experimental::ranges::CopyConstructible.3 b/man/std::experimental::ranges::CopyConstructible.3 new file mode 100644 index 000000000..d3c25000b --- /dev/null +++ b/man/std::experimental::ranges::CopyConstructible.3 @@ -0,0 +1,39 @@ +.TH std::experimental::ranges::CopyConstructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::CopyConstructible \- std::experimental::ranges::CopyConstructible + +.SH Synopsis + Defined in header + template< class T > + + concept bool CopyConstructible = + MoveConstructible && (ranges TS) + Constructible && ConvertibleTo && + Constructible && ConvertibleTo && + + Constructible && ConvertibleTo; + + The concept CopyConstructible is satisfied if T is an lvalue reference type, or if + it is a MoveConstructible object type where an object of that type can constructed + from a (possibly const) lvalue or const rvalue of that type in both direct- and + copy-initialization contexts with the usual semantics (a copy is constructed with + the source unchanged). + + More precisely, if T is an object type, then CopyConstructible is satisfied only + if given + + * v, an lvalue of type (possibly const) T or an rvalue of type const T, + + the following are true: + + * After the definition T u = v;, u is equal to v; + * T{v} is equal to v. + +.SH See also + + is_copy_constructible + is_trivially_copy_constructible + is_nothrow_copy_constructible checks if a type has a copy constructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::ranges::Copyable.3 b/man/std::experimental::ranges::Copyable.3 new file mode 100644 index 000000000..5ae586701 --- /dev/null +++ b/man/std::experimental::ranges::Copyable.3 @@ -0,0 +1,27 @@ +.TH std::experimental::ranges::Copyable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Copyable \- std::experimental::ranges::Copyable + +.SH Synopsis + Defined in header + template< class T > + + concept bool Copyable = + CopyConstructible && (ranges TS) + Movable && + + Assignable; + + The concept Copyable specifies that T is an Movable object type that can also + copied (that is, it supports copy construction and copy assignment). + +.SH Notes + + It is intended that Copyable also requires Assignable (assignment + from const rvalue) and Assignable (assignment from non-const lvalue) to be + satisfied. + +.SH See also + + Movable specifies that an object of a type can be moved and swapped + (concept) diff --git a/man/std::experimental::ranges::DefaultConstructible.3 b/man/std::experimental::ranges::DefaultConstructible.3 new file mode 100644 index 000000000..a2b11c595 --- /dev/null +++ b/man/std::experimental::ranges::DefaultConstructible.3 @@ -0,0 +1,24 @@ +.TH std::experimental::ranges::DefaultConstructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::DefaultConstructible \- std::experimental::ranges::DefaultConstructible + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool DefaultConstructible = Constructible; + + The DefaultConstructible concept provides a shorthand for the common case when the + question is whether a type can be constructed with no arguments. + +.SH See also + + specifies that a variable of the type can be + Constructible constructed from or bound to a set of argument + types + (concept) + is_default_constructible + is_trivially_default_constructible + is_nothrow_default_constructible checks if a type has a default constructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::ranges::DerivedFrom.3 b/man/std::experimental::ranges::DerivedFrom.3 new file mode 100644 index 000000000..e3030a2cd --- /dev/null +++ b/man/std::experimental::ranges::DerivedFrom.3 @@ -0,0 +1,31 @@ +.TH std::experimental::ranges::DerivedFrom 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::DerivedFrom \- std::experimental::ranges::DerivedFrom + +.SH Synopsis + Defined in header + template< class T, class U > + + concept bool DerivedFrom = + std::is_base_of::value && (ranges TS) + + std::is_convertible*, + std::remove_cv_t*>::value; + + The concept DerivedFrom is satisfied if and only if U is a class type that is + either T or a public and unambiguous base of T. + + Despite the use of std::is_base_of and std::is_convertible in its description above, + DerivedFrom is not required to use it in its implementation. Thus, there need not be + any subsumption relationship between DerivedFrom and + std::is_base_of::value or std::is_convertible*, + std::remove_cv_t*>::value. + +.SH See also + + is_base_of checks if a type is derived from the other type + \fI(C++11)\fP \fI(class template)\fP + is_convertible + is_nothrow_convertible checks if a type can be converted to the other type + \fI(C++11)\fP \fI(class template)\fP + (C++20) diff --git a/man/std::experimental::ranges::Destructible.3 b/man/std::experimental::ranges::Destructible.3 new file mode 100644 index 000000000..fb3dee6c6 --- /dev/null +++ b/man/std::experimental::ranges::Destructible.3 @@ -0,0 +1,29 @@ +.TH std::experimental::ranges::Destructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Destructible \- std::experimental::ranges::Destructible + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool Destructible = std::is_nothrow_destructible::value; + + The concept Destructible specifies the concept of all types whose instances can + safely be destroyed at the end of their lifetime (including reference types). + + There need not be any subsumption relationship between Destructible and + std::is_nothrow_destructible::value. + +.SH Notes + + Unlike the Destructible named requirement in the main C++ standard, Destructible + requires the destructor to be noexcept(true), not merely non-throwing when invoked, + and allows reference types and array types. + +.SH See also + + is_destructible + is_trivially_destructible + is_nothrow_destructible checks if a type has a non-deleted destructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::ranges::EqualityComparable,.3 b/man/std::experimental::ranges::EqualityComparable,.3 new file mode 100644 index 000000000..acdb18948 --- /dev/null +++ b/man/std::experimental::ranges::EqualityComparable,.3 @@ -0,0 +1,64 @@ +.TH std::experimental::ranges::EqualityComparable, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::EqualityComparable, \- std::experimental::ranges::EqualityComparable, + +.SH Synopsis + + Defined in header + template< class T > + concept bool EqualityComparable = WeaklyEqualityComparableWith; + template< class T, class U > + + concept bool EqualityComparableWith = + EqualityComparable && + EqualityComparable && + CommonReference< + const std::remove_reference_t&, \fB(2)\fP (ranges TS) + const std::remove_reference_t&> && + EqualityComparable< + ranges::common_reference_t< + const std::remove_reference_t&, + const std::remove_reference_t&>> && + + WeaklyEqualityComparableWith; + + 1) The concept EqualityComparable specifies that the comparison operators == and + != on T reflects equality: == yields true if and only if the operands are equal. + EqualityComparable is satisfied only if, given objects a and b of type T, bool(a + == b) is true if and only if a and b are equal. Together with the requirement that a + == b is equality preserving, this implies that == is symmetric and transitive, and + further that == is reflexive for all objects a that are equal to at least one other + object. + 2) The concept EqualityComparableWith specifies that the comparison operators + == and != on (possibly mixed) T and U operands yield results consistent with + equality. Comparing mixed operands yields results equivalent to comparing the + operands converted to their common type. + Formally, EqualityComparableWith is satisfied only if, given any lvalue t of + type const std::remove_reference_t and any lvalue u of type const + std::remove_reference_t, and let C be ranges::common_reference_t&, const std::remove_reference_t&>, bool(t == u) == + bool(C(t) == C(u)). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Implicit expression variations + + A requires-expression that uses an expression that is non-modifying for some + constant lvalue operand also implicitly requires additional variations of that + expression that accept a non-constant lvalue or (possibly constant) rvalue for the + given operand unless such an expression variation is explicitly required with + differing semantics. These implicit expression variations must meet the same + semantic requirements of the declared expression. The extent to which an + implementation validates the syntax of the variations is unspecified. diff --git a/man/std::experimental::ranges::ForwardIterator.3 b/man/std::experimental::ranges::ForwardIterator.3 new file mode 100644 index 000000000..5c59ac637 --- /dev/null +++ b/man/std::experimental::ranges::ForwardIterator.3 @@ -0,0 +1,40 @@ +.TH std::experimental::ranges::ForwardIterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::ForwardIterator \- std::experimental::ranges::ForwardIterator + +.SH Synopsis + Defined in header + template< class I > + + concept bool ForwardIterator = + InputIterator && + DerivedFrom, (ranges TS) + ranges::forward_iterator_tag> && + Incrementable && + + Sentinel; + + The concept ForwardIterator refines InputIterator by adding equality comparison + and the multi-pass guarantee. + + The domain of == for forward iterators is that of iterators over the same underlying + sequence, except that value-initialized iterators of the same type may be compared + with each other and shall compare equal. + + Pointers and references obtained from a forward iterator into a range [i, s) must + remain valid while [i, s) continues to denote a range. + + Let a and b be two dereferenceable iterators of type I. ForwardIterator is + satisfied only if: + + * a == b implies ++a == ++b; and + * The expression ([](X x){ ++x; }(a), *a) is equivalent to *a, i.e., incrementing + a copy of a has no effect on the result of dereferencing a. + + This is known as the multi-pass guarantee. + +.SH Notes + + A forward iterator cannot be "stashing": it cannot return a reference to an object + within itself, because such references would be invalidated by the destruction of + the forward iterator. diff --git a/man/std::experimental::ranges::ForwardRange.3 b/man/std::experimental::ranges::ForwardRange.3 new file mode 100644 index 000000000..56267552b --- /dev/null +++ b/man/std::experimental::ranges::ForwardRange.3 @@ -0,0 +1,17 @@ +.TH std::experimental::ranges::ForwardRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::ForwardRange \- std::experimental::ranges::ForwardRange + +.SH Synopsis + Defined in header + template< class T > + + concept bool ForwardRange = (ranges TS) + + InputRange && ForwardIterator>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::Incrementable.3 b/man/std::experimental::ranges::Incrementable.3 new file mode 100644 index 000000000..cc7a604eb --- /dev/null +++ b/man/std::experimental::ranges::Incrementable.3 @@ -0,0 +1,48 @@ +.TH std::experimental::ranges::Incrementable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Incrementable \- std::experimental::ranges::Incrementable + +.SH Synopsis + Defined in header + template< class I > + + concept bool Incrementable = + Regular && + WeaklyIncrementable && (ranges TS) + requires(I i) { + { i++ } -> Same&&; + + }; + + The concept Incrementable specifies the requirements on a type that can be + incremented (with the pre- and post-increment operators). The increment operations + (including those required by WeaklyIncrementable) are required to be + equality-preserving, and the type is required to be EqualityComparable. + + Let a and b be incrementable objects of type I. Incrementable is satisfied only + if: + + * If bool(a == b) then bool(a++ == b). + * If bool(a == b) then bool(void(a++), a) == ++b). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + +.SH Notes + + The requirement that a equals b implies ++a equals ++b allows the use of multi-pass + algorithms with Incrementable types. diff --git a/man/std::experimental::ranges::IndirectRelation.3 b/man/std::experimental::ranges::IndirectRelation.3 new file mode 100644 index 000000000..05cce9371 --- /dev/null +++ b/man/std::experimental::ranges::IndirectRelation.3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::IndirectRelation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectRelation \- std::experimental::ranges::IndirectRelation + +.SH Synopsis + Defined in header + template< class F, class I1, class I2 = I1 > + + concept bool IndirectRelation = + Readable && Readable && + CopyConstructible && + Relation&, ranges::value_type_t&> + && (ranges TS) + Relation&, ranges::reference_t> && + Relation, ranges::value_type_t&> && + Relation, ranges::reference_t> && + + Relation, + ranges::iter_common_reference_t>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectStrictWeakOrder.3 b/man/std::experimental::ranges::IndirectStrictWeakOrder.3 new file mode 100644 index 000000000..21a260d56 --- /dev/null +++ b/man/std::experimental::ranges::IndirectStrictWeakOrder.3 @@ -0,0 +1,28 @@ +.TH std::experimental::ranges::IndirectStrictWeakOrder 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectStrictWeakOrder \- std::experimental::ranges::IndirectStrictWeakOrder + +.SH Synopsis + Defined in header + template< class F, class I1, class I2 = I1 > + + concept bool IndirectStrictWeakOrder = + Readable && Readable && + CopyConstructible && + StrictWeakOrder&, + ranges::value_type_t&> && + StrictWeakOrder&, (ranges TS) + ranges::reference_t> && + StrictWeakOrder, + ranges::value_type_t&> && + StrictWeakOrder, + ranges::reference_t> && + StrictWeakOrder, + + ranges::iter_common_reference_t>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectUnaryInvocable,.3 b/man/std::experimental::ranges::IndirectUnaryInvocable,.3 new file mode 100644 index 000000000..fc5a07bc2 --- /dev/null +++ b/man/std::experimental::ranges::IndirectUnaryInvocable,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::ranges::IndirectUnaryInvocable, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectUnaryInvocable, \- std::experimental::ranges::IndirectUnaryInvocable, + +.SH Synopsis + + Defined in header + template< class F, class I > + + concept bool IndirectUnaryInvocable = + Readable && CopyConstructible && + Invocable&> && + Invocable> && (ranges TS) + Invocable> && + CommonReference< + std::result_of_t&)>, + + std::result_of_t&&)>>; + template< class F, class I > + + concept bool IndirectRegularUnaryInvocable = + Readable && CopyConstructible && + RegularInvocable&> && + RegularInvocable> && (ranges TS) + RegularInvocable> && + CommonReference< + std::result_of_t&)>, + + std::result_of_t&&)>>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectUnaryPredicate.3 b/man/std::experimental::ranges::IndirectUnaryPredicate.3 new file mode 100644 index 000000000..f53f0fe85 --- /dev/null +++ b/man/std::experimental::ranges::IndirectUnaryPredicate.3 @@ -0,0 +1,20 @@ +.TH std::experimental::ranges::IndirectUnaryPredicate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectUnaryPredicate \- std::experimental::ranges::IndirectUnaryPredicate + +.SH Synopsis + Defined in header + template< class F, class I > + + concept bool IndirectUnaryPredicate = + Readable && CopyConstructible && (ranges TS) + Predicate&> && + Predicate> && + + Predicate>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectlyComparable.3 b/man/std::experimental::ranges::IndirectlyComparable.3 new file mode 100644 index 000000000..362a38916 --- /dev/null +++ b/man/std::experimental::ranges::IndirectlyComparable.3 @@ -0,0 +1,19 @@ +.TH std::experimental::ranges::IndirectlyComparable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectlyComparable \- std::experimental::ranges::IndirectlyComparable + +.SH Synopsis + Defined in header + template< class I1, class I2, class R = ranges::equal_to<>, + + class P1 = ranges::identity, class P2 = ranges::identity > + concept bool IndirectlyComparable = (ranges TS) + + IndirectRelation, + ranges::projected>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectlyCopyable.3 b/man/std::experimental::ranges::IndirectlyCopyable.3 new file mode 100644 index 000000000..3e9db844a --- /dev/null +++ b/man/std::experimental::ranges::IndirectlyCopyable.3 @@ -0,0 +1,17 @@ +.TH std::experimental::ranges::IndirectlyCopyable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectlyCopyable \- std::experimental::ranges::IndirectlyCopyable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept bool IndirectlyCopyable = (ranges TS) + + Readable && Writable>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectlyCopyableStorable.3 b/man/std::experimental::ranges::IndirectlyCopyableStorable.3 new file mode 100644 index 000000000..056ea852f --- /dev/null +++ b/man/std::experimental::ranges::IndirectlyCopyableStorable.3 @@ -0,0 +1,21 @@ +.TH std::experimental::ranges::IndirectlyCopyableStorable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectlyCopyableStorable \- std::experimental::ranges::IndirectlyCopyableStorable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept bool IndirectlyCopyableStorable = + IndirectlyCopyable && + Writable&> && (ranges TS) + Copyable> && + Constructible, ranges::reference_t> && + + Assignable&, ranges::reference_t>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectlyMovable.3 b/man/std::experimental::ranges::IndirectlyMovable.3 new file mode 100644 index 000000000..95b2cc53a --- /dev/null +++ b/man/std::experimental::ranges::IndirectlyMovable.3 @@ -0,0 +1,17 @@ +.TH std::experimental::ranges::IndirectlyMovable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectlyMovable \- std::experimental::ranges::IndirectlyMovable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept bool IndirectlyMovable = (ranges TS) + + Readable && Writable>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectlyMovableStorable.3 b/man/std::experimental::ranges::IndirectlyMovableStorable.3 new file mode 100644 index 000000000..455e68c48 --- /dev/null +++ b/man/std::experimental::ranges::IndirectlyMovableStorable.3 @@ -0,0 +1,23 @@ +.TH std::experimental::ranges::IndirectlyMovableStorable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectlyMovableStorable \- std::experimental::ranges::IndirectlyMovableStorable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept bool IndirectlyMovableStorable = + IndirectlyMovable && + Writable> && + Movable> && (ranges TS) + Constructible, + ranges::rvalue_reference_t> && + + Assignable&, + ranges::rvalue_reference_t>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::IndirectlySwappable.3 b/man/std::experimental::ranges::IndirectlySwappable.3 new file mode 100644 index 000000000..1793e391e --- /dev/null +++ b/man/std::experimental::ranges::IndirectlySwappable.3 @@ -0,0 +1,23 @@ +.TH std::experimental::ranges::IndirectlySwappable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::IndirectlySwappable \- std::experimental::ranges::IndirectlySwappable + +.SH Synopsis + Defined in header + template< class I1, class I2 = I1 > + + concept bool IndirectlySwappable = + Readable && Readable && + requires(I1&& i1, I2&& i2) { + ranges::iter_swap(std::forward(i1), std::forward(i2)); (ranges TS) + ranges::iter_swap(std::forward(i2), std::forward(i1)); + ranges::iter_swap(std::forward(i1), std::forward(i1)); + ranges::iter_swap(std::forward(i2), std::forward(i2)); + + }; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::InputIterator.3 b/man/std::experimental::ranges::InputIterator.3 new file mode 100644 index 000000000..0b64c37fd --- /dev/null +++ b/man/std::experimental::ranges::InputIterator.3 @@ -0,0 +1,23 @@ +.TH std::experimental::ranges::InputIterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::InputIterator \- std::experimental::ranges::InputIterator + +.SH Synopsis + Defined in header + template< class I > + + concept bool InputIterator = + Iterator && Readable && (ranges TS) + requires { typename ranges::iterator_category_t; } && + + DerivedFrom, + ranges::input_iterator_tag>; + + The InputIterator concept is a refinement of Iterator, adding the requirement that + the referenced values can be read (via Readable) and the requirement that the + iterator category tag be present. + +.SH Notes + + Unlike the input iterator requirements in the C++ standard, InputIterator in the + Ranges TS does not require EqualityComparable. diff --git a/man/std::experimental::ranges::InputRange.3 b/man/std::experimental::ranges::InputRange.3 new file mode 100644 index 000000000..ccf7c0a9d --- /dev/null +++ b/man/std::experimental::ranges::InputRange.3 @@ -0,0 +1,17 @@ +.TH std::experimental::ranges::InputRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::InputRange \- std::experimental::ranges::InputRange + +.SH Synopsis + Defined in header + template< class T > + + concept bool InputRange = (ranges TS) + + Range && InputIterator>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::Integral.3 b/man/std::experimental::ranges::Integral.3 new file mode 100644 index 000000000..5f2f85c15 --- /dev/null +++ b/man/std::experimental::ranges::Integral.3 @@ -0,0 +1,18 @@ +.TH std::experimental::ranges::Integral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Integral \- std::experimental::ranges::Integral + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool Integral = std::is_integral::value; + + The concept Integral is satisfied if and only if T is an integral type. + + There need not be any subsumption relationship between Integral and + std::is_integral::value. + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::experimental::ranges::Invocable,std::experimental::ranges::RegularInvocable.3 b/man/std::experimental::ranges::Invocable,std::experimental::ranges::RegularInvocable.3 new file mode 100644 index 000000000..23f21a463 --- /dev/null +++ b/man/std::experimental::ranges::Invocable,std::experimental::ranges::RegularInvocable.3 @@ -0,0 +1,48 @@ +.TH std::experimental::ranges::Invocable,std::experimental::ranges::RegularInvocable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Invocable,std::experimental::ranges::RegularInvocable \- std::experimental::ranges::Invocable,std::experimental::ranges::RegularInvocable + +.SH Synopsis + Defined in header + template< class F, class... Args > + + concept bool Invocable = + requires(F&& f, Args&&... args) { + ranges::invoke(std::forward(f), (ranges TS) + std::forward(args)...); + /* not required to be equality preserving */ + + }; + template< class F, class... Args > (ranges TS) + concept bool RegularInvocable = Invocable; + + The Invocable concept specifies that a callable type F can be called with a set of + argument types Args... using the function template ranges::invoke. + + The RegularInvocable concept adds to the Invocable concept by requiring the invoke + expression to be equality preserving and not modify either the function object or + the arguments. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + +.SH Notes + + The distinction between Invocable and RegularInvocable is purely semantic. + + A random number generator may satisfy Invocable but cannot satisfy RegularInvocable + (comical ones excluded). diff --git a/man/std::experimental::ranges::Iterator.3 b/man/std::experimental::ranges::Iterator.3 new file mode 100644 index 000000000..45a736f97 --- /dev/null +++ b/man/std::experimental::ranges::Iterator.3 @@ -0,0 +1,48 @@ +.TH std::experimental::ranges::Iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Iterator \- std::experimental::ranges::Iterator + +.SH Synopsis + Defined in header + template< class I > + + concept bool Iterator = + requires(I i) { (ranges TS) + { *i } -> auto&&; // Requires: i is dereferenceable + } && + + WeaklyIncrementable; + + The Iterator concept forms the basis of the iterator concept taxonomy; every + iterator satisfies the Iterator requirements. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + +.SH Notes + + Iterator itself only specifies operations for dereferencing and incrementing an + iterator. Most algorithms will require additional operations, for example: + + * comparing iterators with sentinels (see Sentinel); + * reading values from an iterator (see Readable and InputIterator); + * writing values to an iterator (see Writable and OutputIterator); + * a richer set of iterator movements (see ForwardIterator, BidirectionalIterator, + RandomAccessIterator). + + The -> auto&& constraint implies that the result type of the deference cannot be + void. diff --git a/man/std::experimental::ranges::Mergeable.3 b/man/std::experimental::ranges::Mergeable.3 new file mode 100644 index 000000000..ae10da214 --- /dev/null +++ b/man/std::experimental::ranges::Mergeable.3 @@ -0,0 +1,21 @@ +.TH std::experimental::ranges::Mergeable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Mergeable \- std::experimental::ranges::Mergeable + +.SH Synopsis + template< class I1, class I2, class Out, class R = ranges::less<>, + + class P1 = ranges::identity, class P2 = ranges::identity > + concept bool Mergeable = + InputIterator && + InputIterator && (ranges TS) + WeaklyIncrementable && + IndirectlyCopyable && + IndirectlyCopyable && + + IndirectStrictWeakOrder, + ranges::projected>; + + The Mergeable concept specifies the common requirements of algorithms that merge + sorted sequences into an output sequence by copying the elements (for example, + ranges::merge). diff --git a/man/std::experimental::ranges::Movable.3 b/man/std::experimental::ranges::Movable.3 new file mode 100644 index 000000000..2ff9709c9 --- /dev/null +++ b/man/std::experimental::ranges::Movable.3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::Movable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Movable \- std::experimental::ranges::Movable + +.SH Synopsis + Defined in header + template< class T > + + concept bool Movable = + std::is_object::value && (ranges TS) + MoveConstructible && + Assignable && + + Swappable; + + The concept Movable specifies that T is an object type that can moved (that is, + it can be move constructed, move assigned, and lvalues of type T can be swapped). + + There need not be any subsumption relationship between Movable and + std::is_object::value. + +.SH See also + + Copyable specifies that an object of a type can be copied, moved, and swapped + (concept) diff --git a/man/std::experimental::ranges::MoveConstructible.3 b/man/std::experimental::ranges::MoveConstructible.3 new file mode 100644 index 000000000..31e6d269a --- /dev/null +++ b/man/std::experimental::ranges::MoveConstructible.3 @@ -0,0 +1,38 @@ +.TH std::experimental::ranges::MoveConstructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::MoveConstructible \- std::experimental::ranges::MoveConstructible + +.SH Synopsis + Defined in header + template< class T > + + concept bool MoveConstructible = (ranges TS) + + Constructible && ConvertibleTo; + + The concept MoveConstructible is satisfied if T is a reference type, or if it is an + object type where an object of that type can constructed from an rvalue of that type + in both direct- and copy-initialization contexts, with the usual semantics. + + More precisely, if T is an object type, then MoveConstructible is satisfied only + if given + + * rv, an rvalue of type T, and + * u2, a distinct object of type T equal to rv, + + the following are true: + + * After the definition T u = rv;, u is equal to u2; + * T{rv} is equal to u2; and + * If T is not const-qualified, then rv's resulting state (after the + definition/expression is evaluated in either bullets above) is valid but + unspecified; otherwise, it is unchanged. + +.SH See also + + is_move_constructible + is_trivially_move_constructible checks if a type can be constructed from an rvalue + is_nothrow_move_constructible reference + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::ranges::OutputIterator.3 b/man/std::experimental::ranges::OutputIterator.3 new file mode 100644 index 000000000..ae1cbc8f4 --- /dev/null +++ b/man/std::experimental::ranges::OutputIterator.3 @@ -0,0 +1,43 @@ +.TH std::experimental::ranges::OutputIterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::OutputIterator \- std::experimental::ranges::OutputIterator + +.SH Synopsis + Defined in header + template< class I, class T > + + concept bool OutputIterator = + Iterator && Writable && + requires(I i, T&& t) { (ranges TS) + *i++ = std::forward(t); // not required to be equality + preserving + + }; + + The OutputIterator concept is a refinement of Iterator, adding the requirement that + it can be used to write values of values of type and value category encoded by T + (via Writable). EqualityComparable is not required. + + Let E be an expression such that decltype((E)) is T, and i be a dereferenceable + object of type I. OutputIterator is satisfied only if *i++ = E; has effects + equivalent to *i = E; ++i;. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH Notes + + Unlike the output iterator requirements in the C++ standard, OutputIterator in the + Ranges TS does not require that the iterator category tag be defined. + + Algorithms on output iterators should be single pass. diff --git a/man/std::experimental::ranges::OutputRange.3 b/man/std::experimental::ranges::OutputRange.3 new file mode 100644 index 000000000..a9bf369fc --- /dev/null +++ b/man/std::experimental::ranges::OutputRange.3 @@ -0,0 +1,17 @@ +.TH std::experimental::ranges::OutputRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::OutputRange \- std::experimental::ranges::OutputRange + +.SH Synopsis + Defined in header + template< class R, class T > + + concept bool OutputRange = (ranges TS) + + Range && OutputIterator, T>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::Permutable.3 b/man/std::experimental::ranges::Permutable.3 new file mode 100644 index 000000000..17dd62cc8 --- /dev/null +++ b/man/std::experimental::ranges::Permutable.3 @@ -0,0 +1,15 @@ +.TH std::experimental::ranges::Permutable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Permutable \- std::experimental::ranges::Permutable + +.SH Synopsis + template< class I > + + concept bool Permutable = + ForwardIterator && (ranges TS) + IndirectlyMovableStorable && + + IndirectlySwappable; + + The Permutable concept specifies the common requirements of algorithms that reorder + elements in place by moving or swapping them (for example, ranges::rotate). diff --git a/man/std::experimental::ranges::Predicate.3 b/man/std::experimental::ranges::Predicate.3 new file mode 100644 index 000000000..aeee5229c --- /dev/null +++ b/man/std::experimental::ranges::Predicate.3 @@ -0,0 +1,32 @@ +.TH std::experimental::ranges::Predicate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Predicate \- std::experimental::ranges::Predicate + +.SH Synopsis + Defined in header + template< class F, class... Args > + + concept bool Predicate = (ranges TS) + RegularInvocable && + + Boolean>; + + The concept Predicate specifies that F is a predicate that accepts + arguments whose types and value categories are encoded by Args..., i.e., it can be + invoked with these arguments to produce a Boolean result. + + Note that RegularInvocable requires the invocation to not modify either the callable + object or the arguments and be equality-preserving. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. diff --git a/man/std::experimental::ranges::RandomAccessIterator.3 b/man/std::experimental::ranges::RandomAccessIterator.3 new file mode 100644 index 000000000..15ebce16a --- /dev/null +++ b/man/std::experimental::ranges::RandomAccessIterator.3 @@ -0,0 +1,73 @@ +.TH std::experimental::ranges::RandomAccessIterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::RandomAccessIterator \- std::experimental::ranges::RandomAccessIterator + +.SH Synopsis + Defined in header + template< class I > + + concept bool RandomAccessIterator = + BidirectionalIterator && + DerivedFrom, + ranges::random_access_iterator_tag> && + StrictTotallyOrdered && + SizedSentinel && + requires(I i, const I j, const ranges::difference_type_t n) { (ranges TS) + { i += n } -> Same&; + { j + n } -> Same&&; + { n + j } -> Same&&; + { i -= n } -> Same&; + { j - n } -> Same&&; + j[n]; + requires Same>; + + }; + + The concept RandomAccessIterator refines BidirectionalIterator by adding support + for constant time advancement with the +=, +, -=, and - operators, constant time + computation of distance with -, and array notation with subscripting. + + Let a and b be valid iterators of type I such that b is reachable from a, and let n + be a value of type ranges::difference_type_t equal to b - a. + RandomAccessIterator is satisfied only if: + + * (a += n) is equal to b. + * std::addressof(a += n) is equal to std::addressof(a). + * (a + n) is equal to (a += n). + * (a + n) is equal to (n + a). + * For any two positive integers x and y, if a + (x + y) is valid, then a + (x + y) + is equal to (a + x) + y. + * a + 0 is equal to a. + * If (a + (n - 1)) is valid, then --b is equal to (a + (n - 1)). + * (b += -n) and (b -= n) are both equal to a. + * std::addressof(b -= n) is equal to std::addressof(b). + * (b - n) is equal to (b -= n). + * If b is dereferenceable, then a[n] is valid and is equal to *b. + * bool(a <= b) is true . + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + + Implicit expression variations + + A requires-expression that uses an expression that is non-modifying for some + constant lvalue operand also implicitly requires additional variations of that + expression that accept a non-constant lvalue or (possibly constant) rvalue for the + given operand unless such an expression variation is explicitly required with + differing semantics. These implicit expression variations must meet the same + semantic requirements of the declared expression. The extent to which an + implementation validates the syntax of the variations is unspecified. diff --git a/man/std::experimental::ranges::RandomAccessRange.3 b/man/std::experimental::ranges::RandomAccessRange.3 new file mode 100644 index 000000000..f5099b595 --- /dev/null +++ b/man/std::experimental::ranges::RandomAccessRange.3 @@ -0,0 +1,18 @@ +.TH std::experimental::ranges::RandomAccessRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::RandomAccessRange \- std::experimental::ranges::RandomAccessRange + +.SH Synopsis + Defined in header + template< class T > + + concept bool RandomAccessRange = (ranges TS) + BidirectionalRange && + + RandomAccessIterator>; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::Range.3 b/man/std::experimental::ranges::Range.3 new file mode 100644 index 000000000..aac97a6f4 --- /dev/null +++ b/man/std::experimental::ranges::Range.3 @@ -0,0 +1,23 @@ +.TH std::experimental::ranges::Range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Range \- std::experimental::ranges::Range + +.SH Synopsis + Defined in header + template< class T > + + concept bool Range = + requires(T&& t) { + ranges::begin(t); /* not necessarily equality-preserving (see (ranges TS) + below) */ + ranges::end(t); + + }; + + Given an lvalue t of type std::remove_reference_t, Range is satisfied only if + + * [ranges::begin(t), ranges::end(t)) denotes a range; and + * both ranges::begin(t) and ranges::end(t) are amortized constant time and + non-modifying. + * If ranges::iterator_t satisfies ForwardIterator, ranges::begin(t) is equality + preserving. diff --git a/man/std::experimental::ranges::Readable.3 b/man/std::experimental::ranges::Readable.3 new file mode 100644 index 000000000..adc34de3b --- /dev/null +++ b/man/std::experimental::ranges::Readable.3 @@ -0,0 +1,24 @@ +.TH std::experimental::ranges::Readable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Readable \- std::experimental::ranges::Readable + +.SH Synopsis + Defined in header + template< class In > + + concept bool Readable = + requires { + typename ranges::value_type_t; + typename ranges::reference_t; + typename ranges::rvalue_reference_t; + } && (ranges TS) + CommonReference&&, + ranges::value_type_t&> && + CommonReference&&, + ranges::rvalue_reference_t&&> && + + CommonReference&&, const + ranges::value_type_t&>; + + The concept Readable is satisfied by types that are readable by applying operator*, + such as pointers, smart pointers, and iterators. diff --git a/man/std::experimental::ranges::Regular.3 b/man/std::experimental::ranges::Regular.3 new file mode 100644 index 000000000..e6b71fdba --- /dev/null +++ b/man/std::experimental::ranges::Regular.3 @@ -0,0 +1,12 @@ +.TH std::experimental::ranges::Regular 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Regular \- std::experimental::ranges::Regular + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool Regular = Semiregular && EqualityComparable; + + The Regular concept specifies that a type is regular, that is, it is copyable, + default constructible, and equality comparable. It is satisfied by types that behave + similarly to built-in types like int, and that are comparable with ==. diff --git a/man/std::experimental::ranges::Relation.3 b/man/std::experimental::ranges::Relation.3 new file mode 100644 index 000000000..48c6b1234 --- /dev/null +++ b/man/std::experimental::ranges::Relation.3 @@ -0,0 +1,41 @@ +.TH std::experimental::ranges::Relation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Relation \- std::experimental::ranges::Relation + +.SH Synopsis + Defined in header + template< class R, class T, class U > + + concept bool Relation = + Predicate && + Predicate && + CommonReference< + const std::remove_reference_t&, + const std::remove_reference_t&> && + Predicate&, + const std::remove_reference_t&>, + ranges::common_reference_t< + const std::remove_reference_t&, + const std::remove_reference_t&>> && + Predicate && + + Predicate; + + The concept Relation specifies that R defines a binary relation over the + set of expressions whose type and value category are those encoded by either T or U. + + Given + + * r, an expression such that decltype((r)) is R, + * t, an expression such that decltype((t)) is T, + * u, an expression such that decltype((u)) is U, + + and let C be ranges::common_reference_t&, const + std::remove_reference_t&>, + + then Relation is satisfied only if + + * bool(r(t, u)) == bool(r(C(t), C(u))) and + * bool(r(u, t)) == bool(r(C(u), C(t))). diff --git a/man/std::experimental::ranges::Same.3 b/man/std::experimental::ranges::Same.3 new file mode 100644 index 000000000..fabecb1fa --- /dev/null +++ b/man/std::experimental::ranges::Same.3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::Same 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Same \- std::experimental::ranges::Same + +.SH Synopsis + Defined in header + template< class T, class U > (ranges TS) + concept bool Same = std::is_same::value; // see below + + The concept Same is satisfied if and only if T and U denote the same type. + + Despite being specified using it, there need not be any subsumption relationship + between Same and std::is_same::value. + + For the purposes of constraint checking, Same implies Same. + +.SH Notes + + The additional requirement on constraint checking differentiates Same from + std::is_same. + +.SH See also + + is_same checks if two types are the same + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::experimental::ranges::Semiregular.3 b/man/std::experimental::ranges::Semiregular.3 new file mode 100644 index 000000000..5d6ffd464 --- /dev/null +++ b/man/std::experimental::ranges::Semiregular.3 @@ -0,0 +1,12 @@ +.TH std::experimental::ranges::Semiregular 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Semiregular \- std::experimental::ranges::Semiregular + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool Semiregular = Copyable && DefaultConstructible; + + The Semiregular concept specifies that a type is both copyable and default + constructible. It is satisfied by types that behave similarly to built-in types like + int, except that they need not support comparison with ==. diff --git a/man/std::experimental::ranges::Sentinel.3 b/man/std::experimental::ranges::Sentinel.3 new file mode 100644 index 000000000..24fc02e12 --- /dev/null +++ b/man/std::experimental::ranges::Sentinel.3 @@ -0,0 +1,26 @@ +.TH std::experimental::ranges::Sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Sentinel \- std::experimental::ranges::Sentinel + +.SH Synopsis + Defined in header + template< class S, class I > + + concept bool Sentinel = (ranges TS) + Semiregular && Iterator && + + WeaklyEqualityComparableWith; + + The Sentinel concept specifies the relationship between an Iterator type and a + Semiregular type whose values denote a range. + + Let s and i be values of type S and I, respectively, such that [i, s) denotes a + range. Sentinel is satisfied only if: + + * i == s is well-defined. + * If bool(i != s) then i is dereferenceable and [++i, s) denotes a range. + + The domain of == can change over time. Given an iterator i and sentinel s such that + [i, s) denotes a range and i != s, [i, s) is not required to continue to denote a + range after incrementing any iterator equal to i (and so i == s is no longer + required to be well-defined after such an increment). diff --git a/man/std::experimental::ranges::SignedIntegral.3 b/man/std::experimental::ranges::SignedIntegral.3 new file mode 100644 index 000000000..281eb7995 --- /dev/null +++ b/man/std::experimental::ranges::SignedIntegral.3 @@ -0,0 +1,26 @@ +.TH std::experimental::ranges::SignedIntegral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::SignedIntegral \- std::experimental::ranges::SignedIntegral + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool SignedIntegral = Integral && std::is_signed::value; + + The concept SignedIntegral is satisfied if and only if T is an integral type and + std::is_signed::value is true. + + There need not be any subsumption relationship between SignedIntegral and + std::is_signed::value. + +.SH Notes + + SignedIntegral may be satisfied by a type that is not a signed integer type, for + example, char (on a system where char is signed). + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::experimental::ranges::SizedRange.3 b/man/std::experimental::ranges::SizedRange.3 new file mode 100644 index 000000000..4ccc6add3 --- /dev/null +++ b/man/std::experimental::ranges::SizedRange.3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::SizedRange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::SizedRange \- std::experimental::ranges::SizedRange + +.SH Synopsis + Defined in header + template< class T > + + concept bool SizedRange = + Range && + + !ranges::disable_sized_range>> (ranges + && TS) + requires(T& t) { + { ranges::size(t) } + -> + ConvertibleTo>>; + + }; + + This section is incomplete + Reason: add description and extra caveats + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::ranges::SizedSentinel.3 b/man/std::experimental::ranges::SizedSentinel.3 new file mode 100644 index 000000000..e4b421eac --- /dev/null +++ b/man/std::experimental::ranges::SizedSentinel.3 @@ -0,0 +1,64 @@ +.TH std::experimental::ranges::SizedSentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::SizedSentinel \- std::experimental::ranges::SizedSentinel + +.SH Synopsis + Defined in header + template< class S, class I > + + concept bool SizedSentinel = + Sentinel && + !ranges::disable_sized_sentinel, + std::remove_cv_t> && \fB(1)\fP (ranges TS) + requires(const I& i, const S& s) { + { s - i } -> Same>&&; + { i - s } -> Same>&&; + + }; + template< class S, class I > \fB(1)\fP (ranges TS) + constexpr bool disable_sized_sentinel = false; + + The SizedSentinel concept specifies that an object of the iterator type I and an + object of the sentinel type S can be subtracted to compute the distance between them + in constant time. + + Let i be an iterator of type I, and s a sentinel of type S such that [i, s) denotes + a range. Let N be the smallest number of applications of ++i necessary to make + bool(i == s) be true. Then SizedSentinel is satisfied only if: + + * If N is representable by ranges::difference_type_t, then s - i is + well-defined and equals N; and + * If -N is representable by ranges::difference_type_t, then i - s is + well-defined and equals -N. + + The variable template disable_sized_sentinel provides a mechanism for iterators and + sentinels that can be subtracted but do not meet the semantic requirements of + SizedSentinel to opt out of the concept by specializing the variable template to + have the value true. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + + Implicit expression variations + + A requires-expression that uses an expression that is non-modifying for some + constant lvalue operand also implicitly requires additional variations of that + expression that accept a non-constant lvalue or (possibly constant) rvalue for the + given operand unless such an expression variation is explicitly required with + differing semantics. These implicit expression variations must meet the same + semantic requirements of the declared expression. The extent to which an + implementation validates the syntax of the variations is unspecified. diff --git a/man/std::experimental::ranges::Sortable.3 b/man/std::experimental::ranges::Sortable.3 new file mode 100644 index 000000000..d81b49692 --- /dev/null +++ b/man/std::experimental::ranges::Sortable.3 @@ -0,0 +1,15 @@ +.TH std::experimental::ranges::Sortable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Sortable \- std::experimental::ranges::Sortable + +.SH Synopsis + template< class I, class R = ranges::less<>, class P = ranges::identity + > + + concept bool Sortable = (ranges TS) + Permutable && + + IndirectStrictWeakOrder>; + + The Sortable concept specifies the common requirements of algorithms that permute + sequences into ordered sequences (for example, ranges::sort). diff --git a/man/std::experimental::ranges::StrictTotallyOrdered,.3 b/man/std::experimental::ranges::StrictTotallyOrdered,.3 new file mode 100644 index 000000000..f0cd63000 --- /dev/null +++ b/man/std::experimental::ranges::StrictTotallyOrdered,.3 @@ -0,0 +1,101 @@ +.TH std::experimental::ranges::StrictTotallyOrdered, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::StrictTotallyOrdered, \- std::experimental::ranges::StrictTotallyOrdered, + +.SH Synopsis + + Defined in header + template< class T > + + concept bool StrictTotallyOrdered = + EqualityComparable && + requires(const std::remove_reference_t& a, + const std::remove_reference_t& b) { \fB(1)\fP (ranges TS) + { a < b } -> Boolean&&; + { a > b } -> Boolean&&; + { a <= b } -> Boolean&&; + { a >= b } -> Boolean&&; + + }; + template< class T, class U > + + concept bool StrictTotallyOrderedWith = + StrictTotallyOrdered && + StrictTotallyOrdered && + CommonReference< + const std::remove_reference_t&, + const std::remove_reference_t&> && + StrictTotallyOrdered< + ranges::common_reference_t< + const std::remove_reference_t&, + const std::remove_reference_t&>> && + EqualityComparableWith && \fB(2)\fP (ranges TS) + requires(const std::remove_reference_t& t, + const std::remove_reference_t& u) { + { t < u } -> Boolean&&; + { t > u } -> Boolean&&; + { t <= u } -> Boolean&&; + { t >= u } -> Boolean&&; + { u < t } -> Boolean&&; + { u > t } -> Boolean&&; + { u <= t } -> Boolean&&; + { u >= t } -> Boolean&&; + + }; + + 1) The concept StrictTotallyOrdered specifies that the comparison operators + ==,!=,<,>,<=,>= on T yield results consistent with a strict total order on T. + + StrictTotallyOrdered is satisfied only if, given lvalues a, b and c of type const + std::remove_reference_t: + + * Exactly one of bool(a < b), bool(a > b) and bool(a == b) is true; + * If bool(a < b) and bool(b < c) are both true, then bool(a < c) is true; + * bool(a > b) == bool(b < a) + * bool(a >= b) == !bool(a < b) + * bool(a <= b) == !bool(b < a) + 2) The concept StrictTotallyOrderedWith specifies that the comparison + operators ==,!=,<,>,<=,>= on (possibly mixed) T and U operands yield results + consistent with a strict total order. Comparing mixed operands yields results + equivalent to comparing the operands converted to their common type. + + Formally, StrictTotallyOrderedWith is satisfied only if, given any lvalue t of + type const std::remove_reference_t and any lvalue u of type const + std::remove_reference_t, and let C be ranges::common_reference_t&, const std::remove_reference_t&>: + + * bool(t < u) == bool(C(t) < C(u)) + * bool(t > u) == bool(C(t) > C(u)) + * bool(t <= u) == bool(C(t) <= C(u)) + * bool(t >= u) == bool(C(t) >= C(u)) + * bool(u < t) == bool(C(u) < C(t)) + * bool(u > t) == bool(C(u) > C(t)) + * bool(u <= t) == bool(C(u) <= C(t)) + * bool(u >= t) == bool(C(u) >= C(t)) + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + + Implicit expression variations + + A requires-expression that uses an expression that is non-modifying for some + constant lvalue operand also implicitly requires additional variations of that + expression that accept a non-constant lvalue or (possibly constant) rvalue for the + given operand unless such an expression variation is explicitly required with + differing semantics. These implicit expression variations must meet the same + semantic requirements of the declared expression. The extent to which an + implementation validates the syntax of the variations is unspecified. diff --git a/man/std::experimental::ranges::StrictWeakOrder.3 b/man/std::experimental::ranges::StrictWeakOrder.3 new file mode 100644 index 000000000..b8f0ba312 --- /dev/null +++ b/man/std::experimental::ranges::StrictWeakOrder.3 @@ -0,0 +1,24 @@ +.TH std::experimental::ranges::StrictWeakOrder 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::StrictWeakOrder \- std::experimental::ranges::StrictWeakOrder + +.SH Synopsis + Defined in header + template< class R, class T, class U > \fB(1)\fP (ranges TS) + concept bool StrictWeakOrder = Relation; + + The concept StrictWeakOrder specifies that the Relation R imposes a strict + weak ordering on its arguments. A relation r is a strict weak ordering if + + * it is irreflexive: for all x, r(x, x) is false; + * it is transitive: for all a, b and c, if r(a, b) and r(b, c) are both true then + r(a, c) is true; + * let e(a, b) be !r(a, b) && !r(b, a), then e is transitive: e(a, b) && e(b, c) + implies e(a, c). + + Under these conditions, it can be shown that e is an equivalence relation, and r + induces a strict total ordering on the equivalence classes determined by e. + +.SH Notes + + The distinction between Relation and StrictWeakOrder is purely semantic. diff --git a/man/std::experimental::ranges::Swappable,std::experimental::ranges::SwappableWith.3 b/man/std::experimental::ranges::Swappable,std::experimental::ranges::SwappableWith.3 new file mode 100644 index 000000000..79acde807 --- /dev/null +++ b/man/std::experimental::ranges::Swappable,std::experimental::ranges::SwappableWith.3 @@ -0,0 +1,51 @@ +.TH std::experimental::ranges::Swappable,std::experimental::ranges::SwappableWith 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Swappable,std::experimental::ranges::SwappableWith \- std::experimental::ranges::Swappable,std::experimental::ranges::SwappableWith + +.SH Synopsis + Defined in header + template< class T > + + concept bool Swappable = + requires(T& a, T& b) { \fB(1)\fP (ranges TS) + ranges::swap(a, b); + + }; + template< class T, class U > + + concept bool SwappableWith = + CommonReference< + const std::remove_reference_t&, + const std::remove_reference_t&> && + requires(T&& t, U&& u) { \fB(2)\fP (ranges TS) + ranges::swap(std::forward(t), std::forward(t)); + ranges::swap(std::forward(u), std::forward(u)); + ranges::swap(std::forward(t), std::forward(u)); + ranges::swap(std::forward(u), std::forward(t)); + + }; + + The concept Swappable specifies that lvalues of type T are swappable. + + The concept SwappableWith specifies that expressions of the type and value + category encoded by T and U are swappable with each other. SwappableWith is + satisfied only if a call to ranges::swap(t, u) exchanges the value of t and u, that + is, given distinct objects t2 equal to t and u2 equal to u, after evaluating either + ranges::swap(t, u) or ranges::swap(u, t), t2 is equal to u and u2 is equal to t. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. diff --git a/man/std::experimental::ranges::TagSpecifier.3 b/man/std::experimental::ranges::TagSpecifier.3 new file mode 100644 index 000000000..d5b184c6f --- /dev/null +++ b/man/std::experimental::ranges::TagSpecifier.3 @@ -0,0 +1,30 @@ +.TH std::experimental::ranges::TagSpecifier 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::TagSpecifier \- std::experimental::ranges::TagSpecifier + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool TagSpecifier = /* implementation-defined */; + + The concept TagSpecifier is satisfied if and only if T is a tag specifier for use + with ranges::tagged. + + The Ranges TS provides a set of tag specifiers in . + Users cannot define their own tag specifiers. + +.SH See also + + tagged augument a tuple-like type with named accessors + \fI(class template)\fP + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::TaggedType.3 b/man/std::experimental::ranges::TaggedType.3 new file mode 100644 index 000000000..b907a2e1e --- /dev/null +++ b/man/std::experimental::ranges::TaggedType.3 @@ -0,0 +1,32 @@ +.TH std::experimental::ranges::TaggedType 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::TaggedType \- std::experimental::ranges::TaggedType + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool TaggedType = /* implementation-defined */; + + The concept TaggedType is satisfied if and only if T is a unary function type of + the form R(A), where R is a TagSpecifier. + + Such types are used with the convenience alias templates tagged_tuple and + tagged_pair. + +.SH See also + + tagged_tuple alias template for a tagged std::tuple + (alias template) + tagged_pair alias template for a tagged std::pair + (alias template) + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::UniformRandomNumberGenerator.3 b/man/std::experimental::ranges::UniformRandomNumberGenerator.3 new file mode 100644 index 000000000..e9cec606a --- /dev/null +++ b/man/std::experimental::ranges::UniformRandomNumberGenerator.3 @@ -0,0 +1,28 @@ +.TH std::experimental::ranges::UniformRandomNumberGenerator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::UniformRandomNumberGenerator \- std::experimental::ranges::UniformRandomNumberGenerator + +.SH Synopsis + Defined in header + template< class G > + + concept bool UniformRandomNumberGenerator = + Invocable && + UnsignedIntegral> && (ranges TS) + requires { + { G::min() } -> Same>&&; + { G::max() } -> Same>&&; + + }; + + The concept UniformRandomNumberGenerator specifies that G is the type of a + uniform random number generator, that is, objects of type G is a function object + returning unsigned integer values such that each value in the range of possible + results has (ideally) equal probability of being returned. + + UniformRandomNumberGenerator is satisfied only if, given any object g of type G: + + * G::min() and G::max() are prvalue constant expressions; + * G::min() < G::max() + * g() is in the range [G::min(), G::max()] + * g() has amortized constant complexity. diff --git a/man/std::experimental::ranges::UnsignedIntegral.3 b/man/std::experimental::ranges::UnsignedIntegral.3 new file mode 100644 index 000000000..da9b7e95c --- /dev/null +++ b/man/std::experimental::ranges::UnsignedIntegral.3 @@ -0,0 +1,23 @@ +.TH std::experimental::ranges::UnsignedIntegral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::UnsignedIntegral \- std::experimental::ranges::UnsignedIntegral + +.SH Synopsis + Defined in header + template< class T > (ranges TS) + concept bool UnsignedIntegral = Integral && !SignedIntegral; + + The concept UnsignedIntegral is satisfied if and only if T is an integral type + and std::is_signed::value is false. + +.SH Notes + + UnsignedIntegral may be satisfied by a type that is not a unsigned integer type, + for example, bool. + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::experimental::ranges::View.3 b/man/std::experimental::ranges::View.3 new file mode 100644 index 000000000..19b256432 --- /dev/null +++ b/man/std::experimental::ranges::View.3 @@ -0,0 +1,27 @@ +.TH std::experimental::ranges::View 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::View \- std::experimental::ranges::View + +.SH Synopsis + Defined in header + template< class T > + concept bool View = Range && Semiregular && /* view-predicate (ranges TS) + */; + template< class T > (ranges TS) + struct enable_view {}; + struct view_base {}; (ranges TS) + + The concept View specifies the semiregular range T has constant-time copy, move, + and assignment operations. + + The /* view-predicate */ portion of the concept is determined as follows: + + * if the qualified-id ranges::enable_view::type is valid and denotes a type, + ranges::enable_view::type::value; + * otherwise, if std::is_base_of_v is true, true; + * otherwise, if T is a specialization of std::initializer_list, std::set, + std::multiset, std::unordered_set, or std::unordered_multiset, false; + * otherwise, if both T and const T satisfy Range and ranges::reference_t + > is not the same type as + ranges::reference_t>, false; + * otherwise, true. diff --git a/man/std::experimental::ranges::WeaklyEqualityComparableWith.3 b/man/std::experimental::ranges::WeaklyEqualityComparableWith.3 new file mode 100644 index 000000000..8791715b1 --- /dev/null +++ b/man/std::experimental::ranges::WeaklyEqualityComparableWith.3 @@ -0,0 +1,64 @@ +.TH std::experimental::ranges::WeaklyEqualityComparableWith 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::WeaklyEqualityComparableWith \- std::experimental::ranges::WeaklyEqualityComparableWith + +.SH Synopsis + Defined in header + template< class T, class U > + + concept bool WeaklyEqualityComparableWith = + requires(const std::remove_reference_t& t, + const std::remove_reference_t& u) { + { t == u } -> Boolean&&; (ranges TS) + { t != u } -> Boolean&&; + { u == t } -> Boolean&&; + { u != t } -> Boolean&&; + + }; + + The concept WeaklyEqualityComparableWith specifies that an object of type T + and an object of type U can be compared for equality with each other (in either + order) using both == and !=, and the results of the comparisons are consistent. More + formally, WeaklyEqualityComparableWith is satisfied only if given + + * t, an lvalue of type const std::remove_reference_t and + * u, an lvalue of type const std::remove_reference_t, + + the following are true: + + * t == u, u == t, t != u,u != t have the same domain; + * bool(u == t) == bool(t == u); + * bool(t != u) == !bool(t == u); and + * bool(u != t) == bool(t != u). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + + Unless noted otherwise, every expression used in a requires-expression is required + to be equality preserving and stable, and the evaluation of the expression may only + modify its non-constant operands. Operands that are constant must not be modified. + + Implicit expression variations + + A requires-expression that uses an expression that is non-modifying for some + constant lvalue operand also implicitly requires additional variations of that + expression that accept a non-constant lvalue or (possibly constant) rvalue for the + given operand unless such an expression variation is explicitly required with + differing semantics. These implicit expression variations must meet the same + semantic requirements of the declared expression. The extent to which an + implementation validates the syntax of the variations is unspecified. + +.SH See also + + EqualityComparable specifies that operator == is an equivalence relation + EqualityComparableWith (concept) diff --git a/man/std::experimental::ranges::WeaklyIncrementable.3 b/man/std::experimental::ranges::WeaklyIncrementable.3 new file mode 100644 index 000000000..339828ac2 --- /dev/null +++ b/man/std::experimental::ranges::WeaklyIncrementable.3 @@ -0,0 +1,49 @@ +.TH std::experimental::ranges::WeaklyIncrementable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::WeaklyIncrementable \- std::experimental::ranges::WeaklyIncrementable + +.SH Synopsis + Defined in header + template< class I > + + concept bool WeaklyIncrementable = + Semiregular && + requires(I i) { + typename ranges::difference_type_t; (ranges TS) + requires SignedIntegral>; + { ++i } -> Same&; /* not required to be equality preserving + */ + i++; /* not required to be equality preserving */ + + }; + + The concept WeaklyIncrementable specifies the requirements on a type that can be + incremented (with the pre- and post-increment operators). The increment operations + need not be equality-preserving, and the type need not be EqualityComparable. + + Let i be an object of type I. i is said to be incrementable if it is in the domain + of both pre- and post-increment. WeaklyIncrementable is satisfied only if: + + * ++i and i++ have the same domain; + * If i is incrementable, then: + * ++i and i++ both advance i to the next element; and + * ++i refers to the same object as i. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH Notes + + For WeaklyIncrementable types, a equals b does not imply that ++a equals ++b. + Algorithms on such types should be single pass and never attempt to pass through the + same value twice. diff --git a/man/std::experimental::ranges::Writable.3 b/man/std::experimental::ranges::Writable.3 new file mode 100644 index 000000000..6070c49c6 --- /dev/null +++ b/man/std::experimental::ranges::Writable.3 @@ -0,0 +1,58 @@ +.TH std::experimental::ranges::Writable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::Writable \- std::experimental::ranges::Writable + +.SH Synopsis + Defined in header + template< class Out, class T > + + concept bool Writable = + requires(Out&& o, T&& t) { + *o = std::forward(t); + *std::forward(o) = std::forward(t); + const_cast&&>(*o) = + std::forward(t); (ranges TS) + const_cast&&>(*std::forward(o)) = + std::forward(t); + }; + + /* none of the four expressions above are required to be + equality-preserving */ + + The concept Writable specifies the requirements for writing a value whose + type and value category are encoded by T into an iterator Out's referenced object. + + Let E be an expression such that decltype((E)) is T, and o be a dereferenceable + object of type Out, then Writable is satisfied only if: + + * If Readable && Same, std::decay_t> is + satisfied, then *o after any above assignment is equal to the value of E before + the assignment. + + o is not required to be dereferenceable after evaluating any of the assignment + expressions above. If E is an xvalue, the resulting state of the object it denotes + is valid but unspecified. + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH Notes + + The only valid use of operator* is on the left side of an assignment expression. + Assignment through the same value of a writable type may happen only once. + + The required expressions with const_cast prevent Readable objects with prvalue + reference types from satisfying the syntactic requirements of Writable by accident, + while permitting proxy references to continue to work as long as their constness is + shallow. See Ranges TS issue 381. diff --git a/man/std::experimental::ranges::adjacent_find.3 b/man/std::experimental::ranges::adjacent_find.3 new file mode 100644 index 000000000..dfd2b74ac --- /dev/null +++ b/man/std::experimental::ranges::adjacent_find.3 @@ -0,0 +1,90 @@ +.TH std::experimental::ranges::adjacent_find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::adjacent_find \- std::experimental::ranges::adjacent_find + +.SH Synopsis + Defined in header + template< ForwardIterator I, Sentinel S, class Proj = + ranges::identity, + + IndirectRelation> Pred = \fB(1)\fP (ranges TS) + ranges::equal_to<> > + + I adjacent_find( I first, S last, Pred pred = Pred{}, Proj proj = + Proj{} ); + template< ForwardRange R, class Proj = ranges::identity, + + IndirectRelation, Proj>> + Pred = ranges::equal_to<> > \fB(2)\fP (ranges TS) + + ranges::safe_iterator_t adjacent_find( R&& r, Pred pred = Pred{}, + Proj proj = Proj{} ); + + 1) Searches the range [first, last) for two consecutive identical elements. Elements + are compared using pred after being projected with proj. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + pred - predicate to use to compare the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator to the first of the first pair of identical elements, that is, the first + iterator i such that both i and i + 1 are in the range [first, last) and + ranges::invoke(pred, ranges::invoke(proj, *i), ranges::invoke(proj, *(i + 1))) != + false. + + If no such elements are found, an iterator that compares equal to last is returned. + +.SH Complexity + + If the range is nonempty, exactly min((result - first) + 1, (last - first) - 1) + applications of the predicate where result is the return value, and at most twice as + many applications of the projection. + +.SH Possible implementation + + template S, class Proj = ranges::identity, + IndirectRelation> Pred = ranges::equal_to<>> + I adjacent_find(I first, S last, Pred pred = Pred{}, Proj proj = Proj{}) + { + if (first == last) + return first; + I next = first; + ++next; + while (next != last) + { + if (ranges::invoke(pred, ranges::invoke(proj, *first), + ranges::invoke(proj, *next))) + return first; + ++next; + ++first; + } + return next; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + finds the first two adjacent items that are equal (or satisfy a given + adjacent_find predicate) + \fI(function template)\fP + unique removes consecutive duplicate elements in a range + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::advance.3 b/man/std::experimental::ranges::advance.3 new file mode 100644 index 000000000..8d26194c0 --- /dev/null +++ b/man/std::experimental::ranges::advance.3 @@ -0,0 +1,67 @@ +.TH std::experimental::ranges::advance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::advance \- std::experimental::ranges::advance + +.SH Synopsis + Defined in header + namespace { + (ranges TS) + constexpr /* unspecified */ advance = /* unspecified (customization point + */; object) + + } + Call signature + template< Iterator I > + constexpr void advance( I& i, ranges::difference_type_t \fB(1)\fP + n ); + template< Iterator I, Sentinel S > \fB(2)\fP + constexpr void advance( I& i, S bound ); + template< Iterator I, Sentinel S > + constexpr ranges::difference_type_t advance( I& i, \fB(3)\fP + ranges::difference_type_t n, S bound ); + + Advances the iterator i n times, or until bound is reached, whichever comes first. + + 1) If I models RandomAccessIterator, equivalent to i += n. Otherwise, increments (or + decrements if n is negative) i n times. The behavior is undefined if n is negative + and I does not model BidirectionalIterator. + 2) If Assignable is satisfied, equivalent to i = std::move(bound). + Otherwise, if [i, bound) does not denote a range, the behavior is undefined. + Otherwise, if SizedSentinel is satisfied, equivalent to ranges::advance(i, + bound - i). + Otherwise, increments i until i == bound. + 3) If SizedSentinel is satisfied, equivalent to ranges::advance(i, bound) if + |n| >= |bound - i|, and ranges::advance(i, n) otherwise. + Otherwise, increments (or decrements if n is negative) i either n times or until i + == bound, whichever comes first. + If n > 0, [i, bound) shall denote a range; if n == 0, either [i, bound) or + [bound, i) shall denote a range; if n < 0, [bound, i) shall denote a range, I and S + shall be the same type, and I must model BidirectionalIterator. Otherwise, the + behavior is undefined. + +.SH Return value + + 1,2) \fI(none)\fP + 3) The number of increment/decrements not performed due to reaching bound. In other + words, n - M, where M is the distance from the starting position of i to the ending + position and is negative if the ending position is before the starting position. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + advance advances an iterator by given distance + \fI(function template)\fP + returns the distance between an iterator and a sentinel, or between the + distance beginning and the end of a range + \fI(function template)\fP + next increment an iterator + \fI(function template)\fP + prev decrement an iterator + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::all_of,std::experimental::ranges::any_of,.3 b/man/std::experimental::ranges::all_of,std::experimental::ranges::any_of,.3 new file mode 100644 index 000000000..84a2e1404 --- /dev/null +++ b/man/std::experimental::ranges::all_of,std::experimental::ranges::any_of,.3 @@ -0,0 +1,180 @@ +.TH std::experimental::ranges::all_of,std::experimental::ranges::any_of, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::all_of,std::experimental::ranges::any_of, \- std::experimental::ranges::all_of,std::experimental::ranges::any_of, + +.SH Synopsis + + Defined in header + template< InputIterator I, Sentinel S, class Proj = + ranges::identity, + \fB(1)\fP (ranges TS) + IndirectUnaryPredicate> Pred > + + bool all_of( I first, S last, Pred pred, Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryPredicate, \fB(2)\fP (ranges TS) + Proj>> Pred > + + bool all_of( R&& r, Pred pred, Proj proj = Proj{} ); + template< InputIterator I, Sentinel S, class Proj = + ranges::identity, + \fB(3)\fP (ranges TS) + IndirectUnaryPredicate> Pred > + + bool any_of( I first, S last, Pred pred, Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryPredicate, \fB(4)\fP (ranges TS) + Proj>> Pred > + + bool any_of( R&& r, Pred pred, Proj proj = Proj{} ); + template< InputIterator I, Sentinel S, class Proj = identity, + + IndirectUnaryPredicate> Pred > \fB(5)\fP (ranges TS) + + bool none_of( I first, S last, Pred pred, Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryPredicate, \fB(6)\fP (ranges TS) + Proj>> Pred > + + bool none_of( R&& r, Pred pred, Proj proj = Proj{} ); + + 1) Checks if unary predicate pred returns true for all elements in the range + [first, last). + 3) Checks if unary predicate pred returns true for at least one element in the range + [first, last). + 5) Checks if unary predicate pred returns true for no elements in the range + [first, last). + 2,4,6) Same as (1,3,5), but uses r as the source range, as if using ranges::begin(r) + as first and ranges::end(r) as last. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range of the elements to examine + r - the range of the elements to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1,2) true if pred returns true for all elements in the range, false otherwise. + Returns true if the range is empty. + 3,4) true if pred returns true for at least one element in the range, false + otherwise. Returns false if the range is empty. + 5,6) true if pred returns true for no elements in the range, false otherwise. + Returns true if the range is empty. + +.SH Complexity + + 1-6) At most last - first applications of the predicate and last - first + applications of the projection. + +.SH Possible implementation + +.SH First version + template S, class Proj = ranges::identity, + IndirectUnaryPredicate> Pred> + bool all_of(I first, S last, Pred pred, Proj proj = Proj{}) + { + return ranges::find_if_not(first, last, std::ref(pred), std::ref(proj)) == last; + } + + template, Proj>> Pred> + bool all_of(R&& r, Pred pred, Proj proj = Proj{}) + { + return ranges::all_of(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } +.SH Second version + template S, class Proj = ranges::identity, + IndirectUnaryPredicate> Pred> + bool any_of(I first, S last, Pred pred, Proj proj = Proj{}) + { + return ranges::find_if(first, last, std::ref(pred), std::ref(proj)) != last; + } + + template, Proj>> Pred> + bool any_of(R&& r, Pred pred, Proj proj = Proj{}) + { + return ranges::any_of(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + Third version + template S, class Proj = identity, + IndirectUnaryPredicate> Pred> + bool none_of(I first, S last, Pred pred, Proj proj = Proj{}) + { + return ranges::find_if(first, last, std::ref(pred), std::ref(proj)) == last; + } + + template, Proj>> Pred> + bool none_of(R&& r, Pred pred, Proj proj = Proj{}) + { + return ranges::none_of(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + namespace ranges = std::experimental::ranges; + + int main() + { + std::vector v(10, 2); + std::partial_sum(v.cbegin(), v.cend(), v.begin()); + std::cout << "Among the numbers: "; + ranges::copy(v, ranges::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + + if (ranges::all_of(v.cbegin(), v.cend(), [](int i) { return i % 2 == 0; })) + std::cout << "All numbers are even\\n"; + if (ranges::none_of(v, std::bind(std::modulus(), std::placeholders::_1, 2))) + std::cout << "None of them are odd\\n"; + + struct DivisibleBy + { + const int d; + DivisibleBy(int n) : d(n) {} + bool operator()(int n) const { return n % d == 0; } + }; + + if (ranges::any_of(v, DivisibleBy(7))) + std::cout << "At least one number is divisible by 7\\n"; + } + +.SH Output: + + Among the numbers: 2 4 6 8 10 12 14 16 18 20 + All numbers are even + None of them are odd + At least one number is divisible by 7 + +.SH See also + + all_of + any_of checks if a predicate is true for all, any or none of the elements in a + none_of range + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::ranges::common_reference.3 b/man/std::experimental::ranges::common_reference.3 new file mode 100644 index 000000000..18c1351cc --- /dev/null +++ b/man/std::experimental::ranges::common_reference.3 @@ -0,0 +1,115 @@ +.TH std::experimental::ranges::common_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::common_reference \- std::experimental::ranges::common_reference + +.SH Synopsis + Defined in header + template< class... T > (ranges TS) + struct common_reference; + + Determines the common reference type of the types T..., that is, the type to which + all the types in T... can be converted or bound. If such a type exists (as + determined according to the rules below), the member type names that type. + Otherwise, there is no member type. The behavior is undefined if any of the types in + T... is an incomplete type other than (possibly cv-qualified) void. + + When given reference types, common_reference attempts to find a reference type to + which the supplied reference types can all be bound, but may return a non-reference + type if it cannot find such a reference type. + + * If sizeof...(T) is zero, there is no member type. + * If sizeof...(T) is one (i.e., T... contains only one type T0), the member type + names the same type as T0. + * If sizeof...(T) is two (i.e., T... contains two types T1 and T2): + * If T1 and T2 are both reference types, and the simple common reference type + S of T1 and T2 (as defined below) exists, then the member type type names + S; + * Otherwise, if basic_common_reference::type exists, + where TiR is std::remove_cv_t> and TiQ is an + alias template such that TiQ is Ti, then the member type type names + that type; + * Otherwise, if decltype(false? val() : val()), where val is a + function template template T val();, denotes a valid type, then + the member type type names that type; + * Otherwise, if ranges::common_type_t is a valid type, then the + member type type names that type; + * Otherwise, there is no member type. + * If sizeof...(T) is greater than two (i.e., T... consists of the types T1, T2, + R...), then if ranges::common_reference_t exists, the member type + denotes ranges::common_reference_t, R...> if + such a type exists. In all other cases, there is no member type. + + The simple common reference type of two reference types T1 and T2 is defined as + follows: + + * If T1 is cv1 X & and T2 is cv2 Y & (i.e., both are lvalue reference types): + their simple common reference type is decltype(false? std::declval() : + std::declval()), where cv12 is the union of cv1 and cv2, if that type + exists and is a reference type. + * If T1 and T2 are both rvalue reference types: if the simple common reference + type of T1 & and T2 & (determined according to the previous bullet) exists, then + let C denote that type's corresponding rvalue reference type. If + std::is_convertible::value and std::is_convertible::value are both + true, then the simple common reference type of T1 and T2 is C. + * Otherwise, one of the two types must be an lvalue reference type A & and the + other must be an rvalue reference type B && (A and B might be cv-qualified). Let + D denote the simple common reference type of A & and B const &, if any. If D + exists and std::is_convertible::value is true, then the simple common + reference type is D. + * Otherwise, there's no simple common reference type. + +.SH Member types + + Name Definition + type the common reference type for all T... + +.SH Helper types + + template< class... T > + using common_reference_t = typename common_reference::type; + template< class T, class U, template class TQual, template class + UQual > + struct basic_common_reference {}; + + The class template basic_common_reference is a customization point that allows users + to influence the result of common_reference for user-defined types (typically proxy + references). The primary template is empty. + +.SH Specializations + + A program may specialize basic_common_reference on the first two + parameters T and U if std::is_same> and std::is_same> are both true and at least one of them depends on a program-defined + type. + + If such a specialization has a member named type, it must be a public and + unambiguous member type that names a type to which both TQual and UQual are + convertible. Additionally, ranges::basic_common_reference::type + and ranges::basic_common_reference::type must denote the same + type. + + A program may not specialize basic_common_reference on the third or fourth + parameters, nor may it specialize common_reference itself. A program that adds + specializations in violation of these rules has undefined behavior. + +.SH Notes + + This section is incomplete + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + common_type determines the common type of a group of types + \fI(C++11)\fP \fI(class template)\fP + common_type determine the common type of a set of types + \fI(class template)\fP + CommonReference specifies that two types share a common reference type + (concept) + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::experimental::ranges::common_type.3 b/man/std::experimental::ranges::common_type.3 new file mode 100644 index 000000000..68e89f4d3 --- /dev/null +++ b/man/std::experimental::ranges::common_type.3 @@ -0,0 +1,79 @@ +.TH std::experimental::ranges::common_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::common_type \- std::experimental::ranges::common_type + +.SH Synopsis + Defined in header + template< class... T > (ranges TS) + struct common_type; + + Determines the common type among all types T..., that is the type all T... can be + implicitly converted to. If such a type exists (as determined according to the rules + below), the member type names that type. Otherwise, there is no member type. The + behavior is undefined if any of the types in T... is an incomplete type other than + (possibly cv-qualified) void. + + * If sizeof...(T) is zero, there is no member type. + * If sizeof...(T) is one (i.e., T... contains only one type T0), the member type + names the same type as std::decay_t. + * If sizeof...(T) is two (i.e., T... contains exactly two types T1 and T2), + + * If applying std::decay to at least one of T1 and T2 produces a different type, + the member type names the same type as ranges::common_type_t, + std::decay_t>, if it exists; if not, there is no member type; + * Otherwise, (and unless there is a user specialization for + ranges::common_type), if std::common_type_t is well-formed, then + the member type denotes that type; + * Otherwise, the member type denotes the type std::decay_t() : std::declval())>, if that conditional + expression is well-formed; if not, there is no member type. + * If sizeof...(T) is greater than two (i.e., T... consists of the types T1, T2, + R...), then if ranges::common_type_t exists, the member type denotes + ranges::common_type_t, R...> if such a type + exists. In all other cases, there is no member type. + +.SH Member types + + Name Definition + type the common type for all T... + +.SH Helper types + + template< class... T > + using common_type_t = typename common_type::type; + +.SH Specializations + + Users may specialize common_type for types T1 and T2 if + + * At least one of T1 and T2 depends on a user-defined type, and + * std::decay is an identity transformation for both T1 and T2. + + If such a specialization has a member named type, it must be a public and + unambiguous member type that names a cv-unqualified non-reference type to which both + T1 and T2 are explicitly convertible. Additionally, ranges::common_type_t + and ranges::common_type_t must denote the same type. + + A program that adds common_type specializations in violation of these rules has + undefined behavior. + +.SH Notes + + For arithmetic types not subject to promotion, the common type may be viewed as the + type of the (possibly mixed-mode) arithmetic expression such as T0() + T1() + ... + + Tn(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + common_type determines the common type of a group of types + \fI(C++11)\fP \fI(class template)\fP + common_reference determine the common reference type of a set of types + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::copy,std::experimental::ranges::copy_if.3 b/man/std::experimental::ranges::copy,std::experimental::ranges::copy_if.3 new file mode 100644 index 000000000..112d64d04 --- /dev/null +++ b/man/std::experimental::ranges::copy,std::experimental::ranges::copy_if.3 @@ -0,0 +1,196 @@ +.TH std::experimental::ranges::copy,std::experimental::ranges::copy_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::copy,std::experimental::ranges::copy_if \- std::experimental::ranges::copy,std::experimental::ranges::copy_if + +.SH Synopsis + Defined in header + template< InputIterator I, Sentinel S, WeaklyIncrementable O > + + requires IndirectlyCopyable \fB(1)\fP (ranges TS) + ranges::tagged_pair + + copy( I first, S last, O result ); + template< InputRange R, WeaklyIncrementable O > + + requires IndirectlyCopyable, O> + ranges::tagged_pair), \fB(2)\fP (ranges TS) + tag::out(O)> + + copy( R&& r, O result ); + template< InputIterator I, Sentinel S, WeaklyIncrementable O, + + class Proj = ranges::identity, + IndirectUnaryPredicate> Pred > + requires IndirectlyCopyable \fB(3)\fP (ranges TS) + ranges::tagged_pair + + copy_if( I first, S last, O result, Pred pred, Proj proj = + Proj{} ); + template< InputRange R, WeaklyIncrementable O, + + class Proj = ranges::identity, + IndirectUnaryPredicate, + Proj>> Pred > \fB(4)\fP (ranges TS) + requires IndirectlyCopyable, O> + ranges::tagged_pair), + tag::out(O)> + + copy_if( R&& r, O result, Pred pred, Proj proj = Proj{} ); + + Copies elements in the source range ([first, last) or r) into the destination range + beginning at result, starting from the first element in the source range and + proceeding to the last one. + + 1) Copies all elements in the range [first, last). For each non-negative integer n < + (last - first), performs *(result + n) = *(first + n). The behavior is undefined if + result is within the range [first, last). In this case, ranges::copy_backward may be + used instead. + 2) Same as \fB(1)\fP, but uses r as the source range, as if by + ranges::copy(ranges::begin(r), ranges::end(r), result); except that result may not + be copied. + 3) Only copies the elements for which the predicate pred returns true when applied + to the element's value as projected by the projection proj. The order of the + elements that are copied is preserved. The behavior is undefined if the source and + the destination ranges overlap. + 4) Same as \fB(3)\fP, but uses r as the source range, as if by + ranges::copy_if(ranges::begin(r), ranges::end(r), result, pred, proj); except that + result, pred and proj may not be copied. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range of elements to copy + r - the range of elements to copy + result - the beginning of the destination range + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + A tagged_pair object containing the following two members: + + * The first member, with the tag tag::in, is the past-the-end iterator of the + source range (that is, an iterator of type I that compares equal to the sentinel + last). + * The second member, with the tag tag::out, is the past-the-end iterator of the + result range. + +.SH Complexity + + 1) Exactly ranges::distance(first, last) assignments. + 2) Exactly ranges::distance(r) assignments. + 3) Exactly ranges::distance(first, last) applications of the corresponding + projection and predicate. + 4) Exactly ranges::distance(r) applications of the corresponding projection and + predicate. + +.SH Possible implementations + +.SH First version + template S, WeaklyIncrementable O> + requires IndirectlyCopyable() + ranges::tagged_pair + copy(I first, S last, O result) + { + for (; first != last; ++first, (void)++result) + *result = *first; + return {first, result}; + } +.SH Second version + template + requires IndirectlyCopyable, O>() + ranges::tagged_pair), tag::out(O)> + copy(R&& r, O result) + { + return ranges::copy(ranges::begin(r), ranges::end(r), result); + } + Third version + template S, WeaklyIncrementable O, + class Proj = ranges::identity, + IndirectUnaryPredicate> Pred> + requires IndirectlyCopyable() + ranges::tagged_pair + copy_if(I first, S last, O result, Pred pred, Proj proj = Proj{}) + { + for (; first != last; ++first) + if (ranges::invoke(pred, ranges::invoke(proj, *first))) + { + *result = *first; + ++result; + } + return {first, result}; + } + Fourth version + template, Proj>> Pred> + requires IndirectlyCopyable, O>() + ranges::tagged_pair), tag::out(O)> + copy_if(R&& r, O result, Pred pred, Proj proj = Proj{}) + { + return ranges::copy_if(ranges::begin(r), ranges::end(r), result, pred, proj); + } + +.SH Example + + The following code uses copy to both copy the contents of one vector to another and + to display the resulting vector: + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + // see https://en.cppreference.com/w/cpp/language/namespace_alias + namespace ranges = std::experimental::ranges; + + std::vector from_vector(10); + std::iota(from_vector.begin(), from_vector.end(), 0); + + std::vector to_vector; + ranges::copy_if(from_vector.begin(), from_vector.end(), + ranges::back_inserter(to_vector), + [](const auto i) + { + return i % 3; + }); + // or, alternatively, + // std::vector to_vector(from_vector.size()); + // std::copy(from_vector, to_vector.begin()); + + std::cout << "to_vector contains: "; + + ranges::copy(to_vector, ranges::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + +.SH Output: + + to_vector contains: 1 2 4 5 7 8 + +.SH See also + + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + copy_backward copies a range of elements in backwards order + \fI(function template)\fP + reverse_copy creates a copy of a range that is reversed + \fI(function template)\fP + copy_n copies a number of elements to a new location + \fI(function template)\fP + fill assigns a range of elements a certain value + \fI(function template)\fP + remove_copy copies a range of elements omitting those that satisfy specific + remove_copy_if criteria + \fI(function template)\fP diff --git a/man/std::experimental::ranges::count,std::experimental::ranges::count_if.3 b/man/std::experimental::ranges::count,std::experimental::ranges::count_if.3 new file mode 100644 index 000000000..804bc87a5 --- /dev/null +++ b/man/std::experimental::ranges::count,std::experimental::ranges::count_if.3 @@ -0,0 +1,114 @@ +.TH std::experimental::ranges::count,std::experimental::ranges::count_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::count,std::experimental::ranges::count_if \- std::experimental::ranges::count,std::experimental::ranges::count_if + +.SH Synopsis + Defined in header + template< InputIterator I, Sentinel S, class T, class Proj = + ranges::identity > + + requires IndirectRelation, projected, const T*> + + ranges::difference_type_t count( I first, S last, const T& value, + Proj proj = Proj{} ); + template< InputRange R, class T, class Proj = ranges::identity > + + requires IndirectRelation, + projected, \fB(2)\fP (ranges TS) + Proj>, const T*> + ranges::difference_type_t> + + count( R&& r, const T& value, Proj proj = Proj{} ); + template< InputIterator I, Sentinel S, class Proj = + ranges::identity, + + IndirectUnaryPredicate> Pred > \fB(3)\fP (ranges TS) + + ranges::difference_type_t count_if( I first, S last, Pred pred, + Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryPredicate, + Proj>> Pred > \fB(4)\fP (ranges TS) + ranges::difference_type_t> + + count_if( R&& r, Pred pred, Proj proj = Proj{} ); + + Returns the number of elements in the range [first, last) satisfying specific + criteria. + + 1) Counts the elements whose projected values are equal to value (i.e., + ranges::invoke(proj, *i) == value). + 3) Counts the elements whose projected values satisfy the predicate pred (i.e., + ranges::invoke(pred, ranges::invoke(proj, *i)) != false). + 2,4) Same as (1,3), but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + value - the value to search for + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Number of elements satisfying the condition. + +.SH Complexity + + Exactly last - first comparisons / applications of the predicate, and the same + number of applications of the projection. + +.SH Notes + + For the number of elements in the range [first, last) without any additional + criteria, see ranges::distance. + +.SH Possible implementation + +.SH First version + template S, class T, class Proj = ranges::identity> + requires IndirectRelation, projected, const T*> + ranges::difference_type_t count(I first, S last, const T& value, Proj proj = Proj{}) + { + ranges::difference_type_t ret = 0; + for (; first != last; ++first) + if (ranges::invoke(proj, *first) == value) + ++ret; + return ret; + } +.SH Second version + template S, class Proj = ranges::identity, + IndirectUnaryPredicate> Pred> + ranges::difference_type_t count_if(I first, S last, Pred pred, Proj proj = Proj{}) + { + ranges::difference_type_t ret = 0; + for (; first != last; ++first) + if (ranges::invoke(pred, ranges::invoke(proj, *i))) + ++ret; + return ret; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + count returns the number of elements satisfying specific criteria + count_if \fI(function template)\fP + returns the distance between an iterator and a sentinel, or between the + distance beginning and the end of a range + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::dangling,std::experimental::ranges::safe_iterator_t.3 b/man/std::experimental::ranges::dangling,std::experimental::ranges::safe_iterator_t.3 new file mode 100644 index 000000000..a9ec6d170 --- /dev/null +++ b/man/std::experimental::ranges::dangling,std::experimental::ranges::safe_iterator_t.3 @@ -0,0 +1,51 @@ +.TH std::experimental::ranges::dangling,std::experimental::ranges::safe_iterator_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::dangling,std::experimental::ranges::safe_iterator_t \- std::experimental::ranges::dangling,std::experimental::ranges::safe_iterator_t + +.SH Synopsis + Defined in header + template< CopyConstructible T > + + class dangling { + public: + dangling() requires DefaultConstructible(); (ranges TS) + dangling(T t); + T get_unsafe() const; + + }; + template< Range R > + + using safe_iterator_t = + std::conditional_t::value, (ranges TS) + ranges::iterator_t, + + + ranges::dangling>; + + The class template dangling is a simple wrapper around an object to indicate that + the wrapped object may be dangling, that is, it refers to another object whose + lifetime may have ended. + + The alias template safe_iterator_t returns the iterator type of R, wrapped in + dangling if the range was an rvalue range (as indicated by R not being an lvalue + reference type). + + They are used by range algorithms that accept rvalue ranges and return iterators + into them. + +.SH Member functions + +std::experimental::ranges::dangling::dangling + + dangling() requires DefaultConstructible(); \fB(1)\fP + dangling(T t); \fB(2)\fP + + 1) Default constructor. Value-initializes the wrapped object. + 2) Initializes the wrapped object with t. Note that this constructor defines an + implicit conversion from T to dangling. + +std::experimental::ranges::dangling::get_unsafe + + T get_unsafe() const; + + Returns a copy of the wrapped object. diff --git a/man/std::experimental::ranges::difference_type.3 b/man/std::experimental::ranges::difference_type.3 new file mode 100644 index 000000000..59aabf715 --- /dev/null +++ b/man/std::experimental::ranges::difference_type.3 @@ -0,0 +1,58 @@ +.TH std::experimental::ranges::difference_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::difference_type \- std::experimental::ranges::difference_type + +.SH Synopsis + Defined in header + template< class I > \fB(1)\fP + struct difference_type {}; + template< class T > \fB(2)\fP + struct difference_type; + template< class T > \fB(3)\fP + struct difference_type : difference_type> {}; + template< class T > + + requires requires { typename T::difference_type; } \fB(4)\fP + + struct difference_type; + template< class T > + + requires !requires { typename T::difference_type; } && \fB(5)\fP + requires(const T& a, const T& b) { {a - b} -> Integral; } + + struct difference_type; + + Computes the associated difference type of the type I, if any. Users may specialize + difference_type for a program-defined type. + + 1) Primary template is an empty struct. + 2) Specialization for pointers. If T is an object type, provides a member type type + equal to std::ptrdiff_t. Otherwise, there is no member type. + 3) Specialization for const-qualified types. + 4) Specialization for types that define a public and accessible member type + difference_type. Provides a member type type equal to T::difference_type. + 5) Specialization for types that do not define a public and accessible member type + difference_type but do support subtraction. Provides a member type type equal to + std::make_signed_t() - std::declval())>. + + Helper alias template + + template< class T > (ranges TS) + using difference_type_t = typename ranges::difference_type::type; + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + specifies that a Semiregular type can be incremented with pre- + WeaklyIncrementable and post-increment operators + (concept) + compatibility traits class that collects an iterator’s + iterator_traits associated types + (alias template) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::distance.3 b/man/std::experimental::ranges::distance.3 new file mode 100644 index 000000000..119912c43 --- /dev/null +++ b/man/std::experimental::ranges::distance.3 @@ -0,0 +1,61 @@ +.TH std::experimental::ranges::distance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::distance \- std::experimental::ranges::distance + +.SH Synopsis + Defined in header + namespace { + (ranges TS) + constexpr /* unspecified */ distance = /* unspecified */; (customization + point object) + } + Call signature + template< Iterator I, Sentinel S > + constexpr ranges::difference_type_t distance( I first, S last \fB(1)\fP + ); + template< Range R > + constexpr ranges::difference_type_t> \fB(2)\fP + distance( R&& r ); + template< SizedRange R > + constexpr ranges::difference_type_t> \fB(3)\fP + distance( R&& r ); + + Returns the distance between first and last, or between the beginning and the end of + the range r. + + 1) If SizedSentinel is satisfied, equivalent to return last - first;. + Otherwise, returns the number of increments needed to get from first to last. If + [first, last) does not denote a range, then I and S must be the same type and must + model SizedSentinel, and [last, first) must denote a range. Otherwise, the behavior + is undefined. + 2) Equivalent to return ranges::distance(ranges::begin(r), ranges::end(r));. + 3) Equivalent to return ranges::size(r);. + + Instantiating overloads (2,3) may be ill-formed if the header + is not included before the point of instantiation. + +.SH Return value + + The distance between first and last, or between the beginning and the end of the + range r. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + distance returns the distance between two iterators + \fI(function template)\fP + advance advances an iterator by given distance + \fI(function template)\fP + next increment an iterator + \fI(function template)\fP + prev decrement an iterator + \fI(function template)\fP + size obtains the size of a range whose size can be calculated in constant time + (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::equal.3 b/man/std::experimental::ranges::equal.3 new file mode 100644 index 000000000..49873d3f6 --- /dev/null +++ b/man/std::experimental::ranges::equal.3 @@ -0,0 +1,160 @@ +.TH std::experimental::ranges::equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::equal \- std::experimental::ranges::equal + +.SH Synopsis + Defined in header + template< InputIterator I1, Sentinel S1, InputIterator I2, + Sentinel S2, + + class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > \fB(1)\fP (ranges TS) + requires IndirectlyComparable + bool equal( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = + Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ); + template< InputRange R1, InputRange R2, class Pred = + ranges::equal_to<>, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires IndirectlyComparable, \fB(2)\fP (ranges TS) + ranges::iterator_t, + Pred, Proj1, Proj2> + bool equal( R1&& r1, R2&& r2, Pred pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ); + template< InputIterator I1, Sentinel S1, class I2, + + class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > (ranges TS) + requires InputIterator> && !Range && \fB(3)\fP \fB(deprecated)\fP + IndirectlyComparable, Pred, + Proj1, Proj2> + bool equal( I1 first1, S1 last1, I2&& first2_, Pred pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ); + template< InputRange R1, class I2, class Pred = ranges::equal_to<>, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires InputIterator> && !Range && \fB(4)\fP (ranges TS) + IndirectlyComparable, \fB(deprecated)\fP + std::decay_t, Pred, Proj1, Proj2> + bool equal( R1&& r1, I2&& first2_, Pred pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ); + + 1) Returns true if the range [first1, last1) is equal to the range [first2, last2), + and false otherwise. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + 3) Same as \fB(1)\fP, except that the second range is considered to end when either the + first range is exhausted or the first mismatch is detected. Equivalent to return + last1 == ranges::mismatch(first1, last1, std::forward(first2_), comp, proj1, + proj2).in1(); + 4) Same as \fB(3)\fP, but uses r1 as the first source range, as if using ranges::begin(r1) + as first1 and ranges::end(r1) as last1. + + Two ranges are considered equal if they have the same number of elements and, for + every iterator i in the range [first1, last1), ranges::invoke(pred, + ranges::invoke(proj1, *i), ranges::invoke(proj2, *(first2 + (i - first1)))) is true. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first1, last1 - the first range of the elements + r1 - the first range of the elements + first2, last2 - the second range of the elements + r2 - the second range of the elements + first2_ - the beginning of the second range of the elements + pred - predicate to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + true if the two ranges are equal, otherwise returns false. + +.SH Notes + + ranges::equal should not be used to compare the ranges formed by the iterators from + std::unordered_set, std::unordered_multiset, std::unordered_map, or + std::unordered_multimap because the order in which the elements are stored in those + containers may be different even if the two containers store the same elements. + + When comparing entire containers for equality, operator== for the corresponding + container are usually preferred. + +.SH Complexity + + 1,2) If SizedSentinel && SizedSentinel is satisfied and last1 - + first1 != last2 - first2, no applications of the predicate and projections. + Otherwise, at most min(last1 - first1, last2 - first2) applications of the predicate + and each projection. + 3,4) At most last1 - first1 applications of the predicate and each projection. + +.SH Possible implementation + + namespace detail + { + template S1, + InputIterator I2, SizedSentinel S2> + bool check_size(I1& first1, S1& last1, I2& first2, S2& last2) + { + return last1 - first1 != last2 - first2; + } + + template S1, InputIterator I2, Sentinel S2> + bool check_size(I1& first1, S1& last1, I2& first2, S2& last2) + { + return false; + } + } + + template S1, InputIterator I2, Sentinel S2, + class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = ranges::identity> + requires IndirectlyComparable + bool equal(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{}) + { + if (detail::check_size(first1, last1, first2, last2)) + return false; + for (; first1 != last1 && first2 != last2; (void) ++first1, (void)++first2) + if (!ranges::invoke(pred, ranges::invoke(proj1, *first1), + ranges::invoke(proj2, *first2))) + return false; + return first1 == last1 && first2 == last2; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal determines if two sets of elements are the same + \fI(function template)\fP + find finds the first element satisfying specific criteria + find_if \fI(function template)\fP + find_if_not + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::equal_to.3 b/man/std::experimental::ranges::equal_to.3 new file mode 100644 index 000000000..89be4aa47 --- /dev/null +++ b/man/std::experimental::ranges::equal_to.3 @@ -0,0 +1,95 @@ +.TH std::experimental::ranges::equal_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::equal_to \- std::experimental::ranges::equal_to + +.SH Synopsis + Defined in header + template< class T = void > + + requires EqualityComparable || + Same || (ranges TS) + /* == on two const T lvalues invokes a built-in operator + comparing pointers */ + + struct equal_to; + template<> (ranges TS) + struct equal_to; + + Function object for performing comparisons. The primary template invokes operator == + on const lvalues of type T. The specialization equal_to deduces the parameter + types of the function call operator from the arguments (but not the return type). + + All specializations of equal_to are Semiregular. + +.SH Member types + + Member type Definition + is_transparent (member only of equal_to specialization) /* unspecified */ + +.SH Member functions + + operator() checks if the arguments are equal + \fI(public member function)\fP + +std::experimental::ranges::equal_to::operator() + + constexpr bool operator()(const T& x, const T& y) \fB(1)\fP (member only of primary + const; equal_to template) + template< class T, class U > + + requires EqualityComparableWith || + /* std::declval() == (member only of equal_to + std::declval() resolves to \fB(2)\fP specialization) + a built-in operator comparing + pointers */ + + constexpr bool operator()(T&& t, U&& u) const; + + 1) Compares x and y. Equivalent to return ranges::equal_to<>{}(x, y);. + 2) Compares t and u. Equivalent to return std::forward(t) == std::forward(u);, + except when that expression resolves to a call to a builtin operator == comparing + pointers. + + When a call to \fB(1)\fP or \fB(2)\fP would invoke a built-in operator comparing pointers of + type P, the result is instead determined as follows: + + * Returns false if one of the (possibly converted) value of the first argument and + the (possibly converted) value of the second argument precedes the other in the + implementation-defined strict total ordering over all pointer values of type P. + This strict total ordering is consistent with the partial order imposed by the + builtin operators <, >, <=, and >=. + * Otherwise (neither precedes the other), returns true. + + The behavior is undefined unless the conversion sequences from both T and U to P are + equality-preserving (see below). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH Notes + + Unlike std::equal_to, ranges::equal_to requires both == and != to be valid (via the + EqualityComparable and EqualityComparableWith constraints). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_to function object implementing x == y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::exchange.3 b/man/std::experimental::ranges::exchange.3 new file mode 100644 index 000000000..892d275e0 --- /dev/null +++ b/man/std::experimental::ranges::exchange.3 @@ -0,0 +1,46 @@ +.TH std::experimental::ranges::exchange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::exchange \- std::experimental::ranges::exchange + +.SH Synopsis + Defined in header + template< MoveConstructible T, class U = T > + + requires Assignable (ranges TS) + + constexpr T exchange( T& obj, U&& new_val ) noexcept(/* see below */); + + Replaces the value of obj with new_value and returns the old value of obj, as if by + + T old_value = std::move(obj); + obj = std::forward(new_value); + return old_value; + +.SH Parameters + + obj - object whose value to replace + new_value - the value to assign to obj + +.SH Return value + + The old value of obj. + +.SH Exceptions + + noexcept specification: + noexcept(std::is_nothrow_move_constructible::value && + std::is_nothrow_assignable::value) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + exchange replaces the argument with a new value and returns its previous value + \fI(C++14)\fP \fI(function template)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::ranges::find,std::experimental::ranges::find_if,.3 b/man/std::experimental::ranges::find,std::experimental::ranges::find_if,.3 new file mode 100644 index 000000000..863ec7fcd --- /dev/null +++ b/man/std::experimental::ranges::find,std::experimental::ranges::find_if,.3 @@ -0,0 +1,141 @@ +.TH std::experimental::ranges::find,std::experimental::ranges::find_if, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::find,std::experimental::ranges::find_if, \- std::experimental::ranges::find,std::experimental::ranges::find_if, + +.SH Synopsis + + Defined in header + template< InputIterator I, Sentinel S, class T, class Proj = + ranges::identity > + + requires IndirectRelation, projected, const T*> + + I find( I first, S last, const T& value, Proj proj = Proj{} ); + template< InputRange R, class T, class Proj = ranges::identity > + + requires IndirectRelation, + projected, \fB(2)\fP (ranges TS) + Proj>, const T*> + + ranges::safe_iterator_t find( R&& r, const T& value, Proj proj = + Proj{} ); + template< InputIterator I, Sentinel S, class Proj = + ranges::identity, + \fB(3)\fP (ranges TS) + IndirectUnaryPredicate> Pred > + + I find_if( I first, S last, Pred pred, Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryPredicate, + Proj>> Pred > \fB(4)\fP (ranges TS) + + ranges::safe_iterator_t find_if( R&& r, Pred pred, Proj proj = + Proj{} ); + template< InputIterator I, Sentinel S, class Proj = + ranges::identity, + \fB(5)\fP (ranges TS) + IndirectUnaryPredicate> Pred > + + I find_if_not( I first, S last, Pred pred, Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryPredicate, + Proj>> Pred > \fB(6)\fP (ranges TS) + + ranges::safe_iterator_t find_if_not( R&& r, Pred pred, Proj proj + = Proj{} ); + + Returns the first element in the range [first, last) that satisfies specific + criteria: + + 1) find searches for an element whose projected value is equal to value (i.e., value + == ranges::invoke(proj, *i)). + 3) find_if searches for an element for whose projected value predicate p returns + true (i.e., ranges::invoke(pred, ranges::invoke(proj, *i))) is true). + 5) find_if_not searches for an element for whose projected value predicate q returns + false (i.e., ranges::invoke(pred, ranges::invoke(proj, *i))) is false). + 2,4,6) Same as (1,3,5), but uses r as the source range, as if using ranges::begin(r) + as first and ranges::end(r) as last. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + value - value to compare the projected elements to + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Iterator to the first element satisfying the condition. If no such element is found, + returns an iterator that compares equal to last. + +.SH Complexity + + At most last - first applications of the predicate and projection. + +.SH Possible implementation + +.SH First version + template S, class T, class Proj = ranges::identity> + requires IndirectRelation, projected, const T*> + I find(I first, S last, const T& value, Proj proj = Proj{}) + { + for (; first != last; ++first) + if (ranges::invoke(proj, *first) == value) + break; + return first; + } +.SH Second version + template S, class Proj = ranges::identity, + IndirectUnaryPredicate> Pred> + I find_if(I first, S last, Pred pred, Proj proj = Proj{}) + { + for (; first != last; ++first) + if (ranges::invoke(pred, ranges::invoke(proj, *first))) + break; + return first; + } + Third version + template S, class Proj = ranges::identity, + IndirectUnaryPredicate> Pred> + I find_if_not(I first, S last, Pred pred, Proj proj = Proj{}) + { + for (; first != last; ++first) + if (!ranges::invoke(pred, ranges::invoke(proj, *first))) + break; + return first; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP + \fI(C++11)\fP + finds the first two adjacent items that are equal (or satisfy a given + adjacent_find predicate) + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + find_first_of searches for any one of a set of elements + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::find_end.3 b/man/std::experimental::ranges::find_end.3 new file mode 100644 index 000000000..ee7c45e3a --- /dev/null +++ b/man/std::experimental::ranges::find_end.3 @@ -0,0 +1,115 @@ +.TH std::experimental::ranges::find_end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::find_end \- std::experimental::ranges::find_end + +.SH Synopsis + Defined in header + template< ForwardIterator I1, Sentinel S1, ForwardIterator I2, + Sentinel S2, + + class Proj = ranges::identity, + IndirectRelation> Pred = \fB(1)\fP (ranges TS) + ranges::equal_to<> > + I1 find_end( I1 first1, S1 last1, I2 first2, S2 last2, + + Pred pred = Pred{}, Proj proj = Proj{} ); + template< ForwardRange R1, ForwardRange R2, class Proj = + ranges::identity, + + IndirectRelation, + projected, Proj>> \fB(2)\fP (ranges TS) + Pred = ranges::equal_to<> > + ranges::safe_iterator_t find_end( Rng1&& rng1, Rng2&& rng2, + + Pred pred = Pred{}, Proj proj + = Proj{} ); + + 1) Searches for the last occurrence of the sequence [first2, last2) in the range + [first1, last1) (after projection with proj). + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first1, last1 - the range of elements to examine + r1 - the range of elements to examine + first2, last2 - the range of elements to search for + r2 - the range of elements to search for + pred - predicate to compare the elements + proj - projection to apply to the elements in the first range + +.SH Return value + + Iterator to the beginning of last occurrence of the sequence [first2, last2) in + range [first1, last1) (after projection with proj). + + If [first2, last2) is empty or if no such sequence is found, an iterator that + compares equal to last1 is returned. + +.SH Complexity + + At most S * (N - S + 1) applications of the predicate and projection, where S = + last2 - first2 and N = last1 - first1. + +.SH Notes + + The projection is only applied to the range [first1, last1). + +.SH Possible implementation + + template S1, ForwardIterator I2, Sentinel S2, + class Proj = ranges::identity, + IndirectRelation> Pred = ranges::equal_to<>> + I1 find_end(I1 first1, S1 last1, I2 first2, S2 last2, + Pred pred = Pred{}, Proj proj = Proj{}) + { + I1 result = ranges::next(first1, last1); + if (first2 == last2) + return result; + while (true) + { + I1 new_result = ranges::search(first1, last1, first2, last2, pred, proj); + if (new_result == last1) + break; + else + { + result = new_result; + first1 = result; + ++first1; + } + } + return result; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + includes returns true if one set is a subset of another + \fI(function template)\fP + finds the first two adjacent items that are equal (or satisfy a given + adjacent_find predicate) + \fI(function template)\fP + find finds the first element satisfying specific criteria + find_if \fI(function template)\fP + find_if_not + find_first_of searches for any one of a set of elements + \fI(function template)\fP + search_n searches for a number consecutive copies of an element in a range + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::find_first_of.3 b/man/std::experimental::ranges::find_first_of.3 new file mode 100644 index 000000000..18757cefc --- /dev/null +++ b/man/std::experimental::ranges::find_first_of.3 @@ -0,0 +1,91 @@ +.TH std::experimental::ranges::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::find_first_of \- std::experimental::ranges::find_first_of + +.SH Synopsis + Defined in header + template< InputIterator I1, Sentinel S1, ForwardIterator I2, + Sentinel S2, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity, + IndirectRelation, \fB(1)\fP (ranges TS) + projected> Pred = + ranges::equal_to<> > + I1 find_first_of( I1 first1, S1 last1, I2 first2, S2 last2, Pred + pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ); + template< InputRange R1, ForwardRange R2, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity, + IndirectRelation, Proj1>, + projected, Proj2>> \fB(2)\fP (ranges TS) + Pred = ranges::equal_to<> > + ranges::safe_iterator_t find_first_of( R1&& r1, R2&& r2, Pred + pred = Pred{}, + + Proj1 proj1 = Proj1{}, + Proj2 proj2 = Proj2{} ); + + 1) Searches the range [first1, last1) for any of the elements in the range + [first2, last2), after projecting the ranges with proj1 and proj2 respectively. The + projected elements are compared using pred. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + +.SH Parameters + + first1, last1 - the range of elements to examine + r1 - the range of elements to examine + first2, last2 - the range of elements to search for + r2 - the range of elements to search for + pred - predicate to use to compare the projected elements with + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + Iterator to the first element in the range [first1, last1) that is equal to an + element from the range [first2, last2) after projection. If no such element is + found, an iterator comparing equal to last1 is returned. + +.SH Complexity + + At most (S * N) applications of the predicate and each projection, where S = + distance(last2 - first2) and N = last1 - first1. + +.SH Possible implementation + + template S1, ForwardIterator I2, Sentinel S2, + class Proj1 = ranges::identity, class Proj2 = ranges::identity, + IndirectRelation, + projected> Pred = ranges::equal_to<>> + I1 find_first_of(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{}) + { + for (; first1 != last1; ++first1) + for (ForwardIt it = first2; it != last2; ++it) + if (ranges::invoke(pred, ranges::invoke(proj1, *first1), + ranges::invoke(proj2, *it))) + return first1; + return first1; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find_first_of searches for any one of a set of elements + \fI(function template)\fP + find finds the first element satisfying specific criteria + find_if \fI(function template)\fP + find_if_not + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::for_each.3 b/man/std::experimental::ranges::for_each.3 new file mode 100644 index 000000000..0ef23f511 --- /dev/null +++ b/man/std::experimental::ranges::for_each.3 @@ -0,0 +1,94 @@ +.TH std::experimental::ranges::for_each 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::for_each \- std::experimental::ranges::for_each + +.SH Synopsis + Defined in header + template< InputIterator I, Sentinel S, class Proj = + ranges::identity, + + IndirectUnaryInvocable> Fun > \fB(1)\fP (ranges TS) + ranges::tagged_pair + + for_each( I first, S last, Fun f, Proj proj = Proj{} ); + template< InputRange R, class Proj = ranges::identity, + + IndirectUnaryInvocable, + Proj>> Fun > \fB(2)\fP (ranges TS) + ranges::tagged_pair), + tag::fun(Fun)> + + for_each( R&& r, Fun f, Proj proj = Proj{} ); + + 1) Invokes the given function object f to the result of invoking the projection proj + on dereferencing every iterator in the range [first, last) (i.e.,ranges::invoke(f, + ranges::invoke(proj, *i))), in order. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + For both overloads, if the iterator type is mutable, f may modify the elements of + the range through the dereferenced iterator. If f returns a result, the result is + ignored. + + Unlike the rest of the algorithms, for_each is not allowed to make copies of the + elements in the sequence even if they are trivially copyable. + + Unlike std::for_each (which requires only MoveConstructible), these functions + require Fun to model CopyConstructible. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range to apply the function to + r - the range to apply the function to + f - callable object to be applied to each projected element in the range + proj - projection to apply to the elements + +.SH Return value + + A tagged_pair object containing the following two members: + + * The first member, with the tag tag::in, is the past-the-end iterator of the + source range (that is, an iterator of type I that compares equal to the sentinel + last). + * The second member, with the tag tag::fun, is initialized from std::move(f) + (after all applications of the function object). + +.SH Complexity + + Exactly last - first applications of f and proj. + +.SH Possible implementation + + template S, class Proj = ranges::identity, + IndirectUnaryInvocable> Fun> + auto for_each(I first, S last, Fun f, Proj proj = Proj{}) + -> ranges::tagged_pair + { + for (; first != last; ++first) + ranges::invoke(f, ranges::invoke(proj, *first)); + return {std::move(first), std::move(f)}; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + transform applies a function to a range of elements + \fI(function template)\fP + range-for loop\fI(C++11)\fP executes loop over range + for_each applies a function to a range of elements + \fI(function template)\fP + for_each_n applies a function object to the first N elements of a + \fI(C++17)\fP sequence + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::greater.3 b/man/std::experimental::ranges::greater.3 new file mode 100644 index 000000000..99ade683d --- /dev/null +++ b/man/std::experimental::ranges::greater.3 @@ -0,0 +1,72 @@ +.TH std::experimental::ranges::greater 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::greater \- std::experimental::ranges::greater + +.SH Synopsis + Defined in header + template< class T = void > + + requires StrictTotallyOrdered || + Same || (ranges TS) + /* < on two const T lvalues invokes a built-in operator + comparing pointers */ + + struct greater; + template<> (ranges TS) + struct greater; + + Function object for performing comparisons. The primary template invokes operator< + on const lvalues of type T with the argument order inverted. The specialization + greater deduces the parameter types of the function call operator from the + arguments (but not the return type). + + All specializations of greater are Semiregular. + +.SH Member types + + Member type Definition + is_transparent (member only of greater specialization) /* unspecified */ + +.SH Member functions + + operator() checks if the first argument is greater than the second + \fI(public member function)\fP + +std::experimental::ranges::greater::operator() + + constexpr bool operator()(const T& x, const T& y) \fB(1)\fP (member only of primary + const; greater template) + template< class T, class U > + + requires StrictTotallyOrderedWith || + /* std::declval() < (member only of greater + std::declval() resolves to \fB(2)\fP specialization) + a built-in operator comparing + pointers */ + + constexpr bool operator()(T&& t, U&& u) const; + + 1) Compares x and y. Equivalent to return ranges::less<>{}(y, x);. + 2) Compares t and u. Equivalent to return ranges::less<>{}(std::forward(u), + std::forward(t));. + +.SH Notes + + Unlike std::greater, ranges::greater requires all six comparison operators <, <=, >, + >=, == and != to be valid (via the StrictTotallyOrdered and StrictTotallyOrderedWith + constraints) and is entirely defined in terms of ranges::less. However, the + implementation is free to use operator> directly, because those concepts require the + results of the comparison operators to be consistent. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + greater function object implementing x > y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::greater_equal.3 b/man/std::experimental::ranges::greater_equal.3 new file mode 100644 index 000000000..d591ddb43 --- /dev/null +++ b/man/std::experimental::ranges::greater_equal.3 @@ -0,0 +1,73 @@ +.TH std::experimental::ranges::greater_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::greater_equal \- std::experimental::ranges::greater_equal + +.SH Synopsis + Defined in header + template< class T = void > + + requires StrictTotallyOrdered || + Same || (ranges TS) + /* < on two const T lvalues invokes a built-in operator + comparing pointers */ + + struct greater_equal; + template<> (ranges TS) + struct greater_equal; + + Function object for performing comparisons. The primary template invokes operator< + on const lvalues of type T and negates the result. The specialization + greater_equal deduces the parameter types of the function call operator from + the arguments (but not the return type). + + All specializations of greater_equal are Semiregular. + +.SH Member types + + Member type Definition + is_transparent (member only of greater_equal specialization) /* unspecified */ + +.SH Member functions + + operator() checks if the first argument is greater than or equal to the second + \fI(public member function)\fP + +std::experimental::ranges::greater_equal::operator() + + constexpr bool operator()(const T& x, const T& y) \fB(1)\fP (member only of primary + const; greater_equal template) + template< class T, class U > + + requires StrictTotallyOrderedWith || + /* std::declval() < (member only of + std::declval() resolves to \fB(2)\fP greater_equal + a built-in operator comparing specialization) + pointers */ + + constexpr bool operator()(T&& t, U&& u) const; + + 1) Compares x and y. Equivalent to return !ranges::less<>{}(x, y);. + 2) Compares t and u. Equivalent to return !ranges::less<>{}(std::forward(t), + std::forward(u));. + +.SH Notes + + Unlike std::greater_equal, ranges::greater_equal requires all six comparison + operators <, <=, >, >=, == and != to be valid (via the StrictTotallyOrdered and + StrictTotallyOrderedWith constraints) and is entirely defined in terms of + ranges::less. However, the implementation is free to use operator>= directly, + because those concepts require the results of the comparison operators to be + consistent. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + greater_equal function object implementing x >= y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::identity.3 b/man/std::experimental::ranges::identity.3 new file mode 100644 index 000000000..90c1342d3 --- /dev/null +++ b/man/std::experimental::ranges::identity.3 @@ -0,0 +1,38 @@ +.TH std::experimental::ranges::identity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::identity \- std::experimental::ranges::identity + +.SH Synopsis + Defined in header + struct identity; (ranges TS) + + ranges::identity is a function object type whose operator() returns its argument + unchanged. It is used as the default projection for all Ranges TS algorithms. + +.SH Member functions + + operator() returns the argument unchanged + \fI(public member function)\fP + +std::experimental::ranges::identity::operator() + + template< class T > + constexpr T&& operator()( T&& t ) const noexcept; + + Returns std::forward(t). + +.SH Parameters + + t - argument to return + +.SH Return value + + std::forward(t). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::indirect_result_of.3 b/man/std::experimental::ranges::indirect_result_of.3 new file mode 100644 index 000000000..c34550949 --- /dev/null +++ b/man/std::experimental::ranges::indirect_result_of.3 @@ -0,0 +1,13 @@ +.TH std::experimental::ranges::indirect_result_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::indirect_result_of \- std::experimental::ranges::indirect_result_of + +.SH Synopsis + Defined in header + template< class > struct indirect_result_of {}; + + template< class F, class... Is > + requires Invocable...> (ranges TS) + struct indirect_result_of + + : std::result_of&&...)> {}; diff --git a/man/std::experimental::ranges::input_iterator_tag,.3 b/man/std::experimental::ranges::input_iterator_tag,.3 new file mode 100644 index 000000000..25df05caa --- /dev/null +++ b/man/std::experimental::ranges::input_iterator_tag,.3 @@ -0,0 +1,53 @@ +.TH std::experimental::ranges::input_iterator_tag, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::input_iterator_tag, \- std::experimental::ranges::input_iterator_tag, + +.SH Synopsis + std::experimental::ranges::forward_iterator_tag, + std::experimental::ranges::bidirectional_iterator_tag, + std::experimental::ranges::random_access_iterator_tag + + Defined in header + struct input_iterator_tag {}; + struct output_iterator_tag {}; + struct forward_iterator_tag : public input_iterator_tag {}; + struct bidirectional_iterator_tag : public forward_iterator_tag {}; + struct random_access_iterator_tag : public bidirectional_iterator_tag {}; + + Defines the category of an iterator. Each tag is an empty type and corresponds to + one of the five iterator categories: + + * input_iterator_tag corresponds to InputIterator. + * forward_iterator_tag corresponds to ForwardIterator. + * bidirectional_iterator_tag corresponds to BidirectionalIterator. + * random_access_iterator_tag corresponds to RandomAccessIterator. + * output_iterator_tag corresponds to OutputIterator; it is not used and provided + solely for backward compatiblity. + + Iterator category tags carry information that can be used to select the most + efficient algorithms for the specific requirement set that is implied by the + category. However, concept-based overloading is preferred. + + For every InputIterator type I, ranges::iterator_category_t must be defined to be + an alias for the most specific category tag that describes the iterator's behavior. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + input_iterator_tag + output_iterator_tag + forward_iterator_tag empty class types used to indicate iterator categories + bidirectional_iterator_tag \fI(class)\fP + random_access_iterator_tag + contiguous_iterator_tag + (C++20) + compatibility traits class that collects an iterator’s + iterator_traits associated types + (alias template) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::invoke.3 b/man/std::experimental::ranges::invoke.3 new file mode 100644 index 000000000..3f05f0fe4 --- /dev/null +++ b/man/std::experimental::ranges::invoke.3 @@ -0,0 +1,37 @@ +.TH std::experimental::ranges::invoke 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::invoke \- std::experimental::ranges::invoke + +.SH Synopsis + Defined in header + template< class F, class... Args > (ranges TS) + std::result_of_t invoke( F&& f, Args&&... args ); + + Invoke the Callable object f with the parameters args, and return the result, as if + by return INVOKE(std::forward(f), std::forward(args)...);, where INVOKE(f, + t1, t2, ..., tN) is defined as follows: + + * if f is a pointer to member function of class T: + + * If std::is_base_of>::value is true, then INVOKE(f, + t1, t2, ..., tN) is equivalent to (t1.*f)(t2, ..., tN), + * otherwise, INVOKE(f, t1, t2, ..., tN) is equivalent to ((*t1).*f)(t2, ..., tN). + * otherwise, if N == 1 and f is a pointer to data member of class T: + + * If std::is_base_of>::value is true, then INVOKE(f, + t1) is equivalent to t1.*f, + * otherwise, then INVOKE(f, t1) is equivalent to (*t1).*f. + * otherwise, INVOKE(f, t1, t2, ..., tN) is equivalent to f(t1, t2, ..., tN) (that + is, f is a FunctionObject). + +.SH Parameters + + f - Callable object to be invoked + args - arguments to pass to f + +.SH See also + + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP diff --git a/man/std::experimental::ranges::is_permutation.3 b/man/std::experimental::ranges::is_permutation.3 new file mode 100644 index 000000000..29bc1114e --- /dev/null +++ b/man/std::experimental::ranges::is_permutation.3 @@ -0,0 +1,116 @@ +.TH std::experimental::ranges::is_permutation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::is_permutation \- std::experimental::ranges::is_permutation + +.SH Synopsis + Defined in header + template< ForwardIterator I1, Sentinel S1, ForwardIterator I2, + Sentinel S2, + + class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > \fB(1)\fP (ranges TS) + requires IndirectlyComparable + bool is_permutation( I1 first1, S1 last1, I2 first2, S2 last2, Pred + pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} + ); + template< ForwardRange R1, ForwardRange R2, class Pred = + ranges::equal_to<>, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires IndirectlyComparable, \fB(2)\fP (ranges TS) + ranges::iterator_t, + Pred, Proj1, Proj2> + bool is_permutation( R1&& r1, R2&& r2, Pred pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} + ); + template< ForwardIterator I1, Sentinel S1, class I2, + + class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires ForwardIterator> && !Range && (ranges TS) + IndirectlyComparable, Pred, \fB(3)\fP \fB(deprecated)\fP + Proj1, Proj2> + bool is_permutation( I1 first1, S1 last1, I2&& first2_, Pred pred = + Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} + ); + template< ForwardRange R1, class I2, class Pred = + ranges::equal_to<>, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires ForwardIterator> && !Range && \fB(4)\fP (ranges TS) + IndirectlyComparable, \fB(deprecated)\fP + std::decay_t, Pred, Proj1, Proj2> + bool is_permutation( R1&& r1, I2&& first2_, Pred pred = Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} + ); + + 1) Returns true if there exists a permutation of the elements in range + [first1, last1) that makes the range equal to [first2, last2), and false otherwise. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + 3) Same as \fB(1)\fP, except that first2 is defined as if by std::decay_t first2 = + std::forward(first2_); and last2 is first2 + (last1 - first1). + 4) Same as \fB(3)\fP, but uses r1 as the first source range, as if using ranges::begin(r1) + as first1 and ranges::end(r1) as last1. + + Two ranges are considered equal if they have the same number of elements and, for + every iterator i in the range [first1, last1), ranges::invoke(pred, + ranges::invoke(proj1, *i), ranges::invoke(proj2, *(first2 + (i - first1)))) is true. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first1, last1 - the first range of the elements + r1 - the first range of the elements + first2, last2 - the second range of the elements + r2 - the second range of the elements + first2_ - the beginning of the second range of the elements + pred - predicate to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + true if the range [first1, last1) is a permutation of the range [first2, last2). + +.SH Complexity + + At most O(N^2) applications of the predicate and each projection, or exactly N if + the sequences are already equal, where N = last1 - first1. + + However if SizedSentinel && SizedSentinel is satisfied and last1 - + first1 != last2 - first2, no applications of the predicate and projections are made. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_permutation determines if a sequence is a permutation of another sequence + \fI(C++11)\fP \fI(function template)\fP + generates the next greater lexicographic permutation of a range of + next_permutation elements + \fI(function template)\fP + generates the next smaller lexicographic permutation of a range of + prev_permutation elements + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::is_swappable_with,std::experimental::ranges::is_swappable,.3 b/man/std::experimental::ranges::is_swappable_with,std::experimental::ranges::is_swappable,.3 new file mode 100644 index 000000000..9db1ee492 --- /dev/null +++ b/man/std::experimental::ranges::is_swappable_with,std::experimental::ranges::is_swappable,.3 @@ -0,0 +1,80 @@ +.TH std::experimental::ranges::is_swappable_with,std::experimental::ranges::is_swappable, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::is_swappable_with,std::experimental::ranges::is_swappable, \- std::experimental::ranges::is_swappable_with,std::experimental::ranges::is_swappable, + +.SH Synopsis + std::experimental::ranges::is_nothrow_swappable + + Defined in header + template< class T, class U > \fB(1)\fP (ranges TS) + struct is_swappable_with; + template< class T > \fB(2)\fP (ranges TS) + struct is_swappable; + template< class T, class U > \fB(3)\fP (ranges TS) + struct is_nothrow_swappable_with; + template< class T > \fB(4)\fP (ranges TS) + struct is_nothrow_swappable; + + 1) If the expressions ranges::swap(std::declval(), std::declval()) and + ranges::swap(std::declval(), std::declval()) are both well-formed when treated + as an unevaluated operand, provides the member constant value equal true. Otherwise, + value is false. Access checks are performed as if from a context unrelated to either + type. + 2) If T is not a referenceable type (i.e., possibly cv-qualified void or a function + type with a cv-qualifier-seq or a ref-qualifier), provides a member constant value + equal to false. Otherwise, provides a member constant value equal to + ranges::is_swappable_with::value. + 3) Same as \fB(1)\fP, but evaluations of both expressions from (1) are known not to throw + exceptions. + 4) Same as \fB(2)\fP, but uses is_nothrow_swappable_with. + + T and U shall each be a complete type, (possibly cv-qualified) void, or an array of + unknown bound. Otherwise, the behavior is undefined. + +.SH Member constants + + value true if T is swappable with U, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + This trait does not check anything outside the immediate context of the swap + expressions: if the use of T or U would trigger template specializations, generation + of implicitly-defined special member functions etc, and those have errors, the + actual swap may not compile even if ranges::is_swappable_with::value compiles + and evaluates to true. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + Swappable specifies that a type can be swapped or that two types can + SwappableWith be swapped with each other + (concept) + is_swappable_with + is_swappable + is_nothrow_swappable_with checks if objects of a type can be swapped with objects of + is_nothrow_swappable same or different type + \fI(C++17)\fP \fI(class template)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::iterator_category.3 b/man/std::experimental::ranges::iterator_category.3 new file mode 100644 index 000000000..cf8c7b650 --- /dev/null +++ b/man/std::experimental::ranges::iterator_category.3 @@ -0,0 +1,76 @@ +.TH std::experimental::ranges::iterator_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::iterator_category \- std::experimental::ranges::iterator_category + +.SH Synopsis + Defined in header + template< class I > \fB(1)\fP + struct iterator_category {}; + template< class T > \fB(2)\fP + struct iterator_category; + template< class T > \fB(3)\fP + struct iterator_category : iterator_category {}; + template< class T > + + requires requires { typename T::iterator_category; } \fB(4)\fP + + struct iterator_category; + + Computes the iterator category of the class I, if any. Users may specialize + iterator_category for a program-defined type. + + 1) Primary template is an empty struct. + 2) Specialization for pointers. If T is an object type, provides a member type type + equal to ranges::random_access_iterator_tag. Otherwise, there is no member type. + 3) Specialization for const-qualified types. + 4) Specialization for types that define a public and accessible member type + iterator_category. If T::iterator_category is the same as or derived from one of + iterator category tags in namespace std, it is mapped to the corresponding tag in + the namespace ranges as described below. Otherwise, provides a member type type + equal to T::iterator_category. + * If T::iterator_category is the same as or derives from + std::random_access_iterator_tag, provides a member type type equal to + ranges::random_access_iterator_tag. + * Otherwise, if T::iterator_category is the same as or derives from + std::bidirectional_iterator_tag, provides a member type type equal to + ranges::bidirectional_iterator_tag. + * Otherwise, if T::iterator_category is the same as or derives from + std::forward_iterator_tag, provides a member type type equal to + ranges::forward_iterator_tag. + * Otherwise, if T::iterator_category is the same as or derives from + std::input_iterator_tag, provides a member type type equal to + ranges::input_iterator_tag. + * Otherwise, if T::iterator_category is the same as or derives from + std::output_iterator_tag, there is no member type. + + Helper alias template + + template< class T > + using iterator_category_t = typename (ranges TS) + ranges::iterator_category::type; + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + input_iterator_tag + output_iterator_tag + forward_iterator_tag empty class types used to indicate iterator categories + bidirectional_iterator_tag \fI(class)\fP + random_access_iterator_tag + contiguous_iterator_tag + (C++20) + input_iterator_tag + output_iterator_tag empty class types used to indicate iterator categories + forward_iterator_tag \fI(class)\fP + bidirectional_iterator_tag + random_access_iterator_tag + compatibility traits class that collects an iterator’s + iterator_traits associated types + (alias template) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::iterator_t,std::experimental::ranges::sentinel_t.3 b/man/std::experimental::ranges::iterator_t,std::experimental::ranges::sentinel_t.3 new file mode 100644 index 000000000..d4821639b --- /dev/null +++ b/man/std::experimental::ranges::iterator_t,std::experimental::ranges::sentinel_t.3 @@ -0,0 +1,12 @@ +.TH std::experimental::ranges::iterator_t,std::experimental::ranges::sentinel_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::iterator_t,std::experimental::ranges::sentinel_t \- std::experimental::ranges::iterator_t,std::experimental::ranges::sentinel_t + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP (ranges TS) + using iterator_t = decltype(ranges::begin(std::declval())); + template< class T > \fB(2)\fP (ranges TS) + using sentinel_t = decltype(ranges::end(std::declval())); + + Obtain the iterator and sentinel types of a range T. diff --git a/man/std::experimental::ranges::less.3 b/man/std::experimental::ranges::less.3 new file mode 100644 index 000000000..693e15095 --- /dev/null +++ b/man/std::experimental::ranges::less.3 @@ -0,0 +1,96 @@ +.TH std::experimental::ranges::less 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::less \- std::experimental::ranges::less + +.SH Synopsis + Defined in header + template< class T = void > + + requires StrictTotallyOrdered || + Same || (ranges TS) + /* < on two const T lvalues invokes a built-in operator + comparing pointers */ + + struct less; + template<> (ranges TS) + struct less; + + Function object for performing comparisons. The primary template invokes operator< + on const lvalues of type T. The specialization less deduces the parameter + types of the function call operator from the arguments (but not the return type). + + All specializations of less are Semiregular. + +.SH Member types + + Member type Definition + is_transparent (member only of less specialization) /* unspecified */ + +.SH Member functions + + operator() checks if the first argument is less than the second + \fI(public member function)\fP + +std::experimental::ranges::less::operator() + + constexpr bool operator()(const T& x, const T& y) \fB(1)\fP (member only of primary + const; less template) + template< class T, class U > + + requires StrictTotallyOrderedWith || + /* std::declval() < std::declval() (member only of less + resolves to \fB(2)\fP specialization) + a built-in operator comparing + pointers */ + + constexpr bool operator()(T&& t, U&& u) const; + + 1) Compares x and y. Equivalent to return ranges::less<>{}(x, y);. + 2) Compares t and u. Equivalent to return std::forward(t) < std::forward(u);, + except when that expression resolves to a call to a builtin operator< comparing + pointers. + + When a call to \fB(1)\fP or \fB(2)\fP would invoke a built-in operator comparing pointers of + type P, the result is instead determined as follows: + + * Returns true if the (possibly converted) value of the first argument precedes + the (possibly converted) value of the second argument in the + implementation-defined strict total ordering over all pointer values of type P. + This strict total ordering is consistent with the partial order imposed by the + builtin operators <, >, <=, and >=. + * Otherwise, returns false. + + The behavior is undefined unless the conversion sequences from both T and U to P are + equality-preserving (see below). + + Equality preservation + + An expression is equality preserving if it results in equal outputs given equal + inputs. + + * The inputs to an expression consist of its operands. + * The outputs of an expression consist of its result and all operands modified by + the expression (if any). + + Every expression required to be equality preserving is further required to be + stable: two evaluations of such an expression with the same input objects must have + equal outputs absent any explicit intervening modification of those input objects. + +.SH Notes + + Unlike std::less, ranges::less requires all six comparison operators <, <=, >, >=, + == and != to be valid (via the StrictTotallyOrdered and StrictTotallyOrderedWith + constraints). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + less function object implementing x < y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::less_equal.3 b/man/std::experimental::ranges::less_equal.3 new file mode 100644 index 000000000..2f2a01e97 --- /dev/null +++ b/man/std::experimental::ranges::less_equal.3 @@ -0,0 +1,73 @@ +.TH std::experimental::ranges::less_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::less_equal \- std::experimental::ranges::less_equal + +.SH Synopsis + Defined in header + template< class T = void > + + requires StrictTotallyOrdered || + Same || (ranges TS) + /* < on two const T lvalues invokes a built-in operator + comparing pointers */ + + struct less_equal; + template<> (ranges TS) + struct less_equal; + + Function object for performing comparisons. The primary template invokes operator< + on const lvalues of type T with the argument order inverted and then negates the + result. The specialization less_equal deduces the parameter types of the + function call operator from the arguments (but not the return type). + + All specializations of less_equal are Semiregular. + +.SH Member types + + Member type Definition + is_transparent (member only of less_equal specialization) /* unspecified */ + +.SH Member functions + + operator() checks if the first argument is less than or equal to the second + \fI(public member function)\fP + +std::experimental::ranges::less_equal::operator() + + constexpr bool operator()(const T& x, const T& \fB(1)\fP (member only of primary + y) const; less_equal template) + template< class T, class U > + + requires StrictTotallyOrderedWith || + /* std::declval() < (member only of less_equal + std::declval() resolves to \fB(2)\fP specialization) + a built-in operator comparing + pointers */ + + constexpr bool operator()(T&& t, U&& u) const; + + 1) Compares x and y. Equivalent to return !ranges::less<>{}(y, x);. + 2) Compares t and u. Equivalent to return !ranges::less<>{}(std::forward(u), + std::forward(t));. + +.SH Notes + + Unlike std::less_equal, ranges::less_equal requires all six comparison operators <, + <=, >, >=, == and != to be valid (via the StrictTotallyOrdered and + StrictTotallyOrderedWith constraints) and is entirely defined in terms of + ranges::less. However, the implementation is free to use operator<= directly, + because those concepts require the results of the comparison operators to be + consistent. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + less_equal function object implementing x <= y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::lexicographical_compare.3 b/man/std::experimental::ranges::lexicographical_compare.3 new file mode 100644 index 000000000..dc65acb95 --- /dev/null +++ b/man/std::experimental::ranges::lexicographical_compare.3 @@ -0,0 +1,109 @@ +.TH std::experimental::ranges::lexicographical_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::lexicographical_compare \- std::experimental::ranges::lexicographical_compare + +.SH Synopsis + Defined in header + template< InputIterator I1, Sentinel S1, InputIterator I2, + Sentinel S2, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity, + class Comp = ranges::less<> > + requires IndirectStrictWeakOrder, \fB(1)\fP (ranges TS) + projected> + bool lexicographical_compare( I1 first1, S1 last1, I2 first2, S2 + last2, + Comp comp = Comp{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = + Proj2{} ); + template< InputRange R1, InputRange R2, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity, + class Comp = ranges::less<> > + requires IndirectStrictWeakOrder, Proj1>, \fB(2)\fP (ranges TS) + + projected, Proj2>> + bool lexicographical_compare( R1&& r1, R2&& r2, Comp comp = Comp{}, + + Proj1 proj1 = Proj1{}, Proj2 proj2 = + Proj2{} ); + + 1) Checks if the first range [first1, last1) is lexicographically less than the + second range [first2, last2). Elements are compared using the given binary + comparison function comp, after being projected with proj1 and proj2 respectively. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + Lexicographical comparison is an operation with the following properties: + + * Two ranges are compared element by element. + * The first mismatching element defines which range is lexicographically less or + greater than the other. + * If one range is a prefix of another, the shorter range is lexicographically less + than the other. + * If two ranges have equivalent elements and are of the same length, then the + ranges are lexicographically equal. + * An empty range is lexicographically less than any non-empty range. + * Two empty ranges are lexicographically equal. + +.SH Parameters + + first1, last1 - the first range of elements to examine + r1 - the first range of elements to examine + first2, last2 - the second range of elements to examine + r2 - the second range of elements to examine + comp - comparison function to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + true if the first range is lexicographically less than the second. + +.SH Complexity + + At most 2·min(N1, N2) applications of the comparison operation, where N1 = last1 - + first1 and N2 = last2 - first2. + +.SH Possible implementation + + template S1, InputIterator I2, Sentinel S2, + class Proj1 = ranges::identity, class Proj2 = ranges::identity, + class Comp = ranges::less<>> + requires IndirectStrictWeakOrder, projected> + bool lexicographical_compare(I1 first1, S1 last1, I2 first2, S2 last2, + Comp comp = Comp{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{}) + { + for (; (first1 != last1) && (first2 != last2); (void) ++first1, (void) ++first2) + { + if (ranges::invoke(comp, ranges::invoke(proj1, *first1), + ranges::invoke(proj2, *first2))) + return true; + if (ranges::invoke(comp, ranges::invoke(proj2, *first2), + ranges::invoke(proj1, *first1))) + return false; + } + return (first1 == last1) && (first2 != last2); + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + equal determines if two sets of elements are the same + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::make_tagged_pair.3 b/man/std::experimental::ranges::make_tagged_pair.3 new file mode 100644 index 000000000..5b4d6feea --- /dev/null +++ b/man/std::experimental::ranges::make_tagged_pair.3 @@ -0,0 +1,44 @@ +.TH std::experimental::ranges::make_tagged_pair 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::make_tagged_pair \- std::experimental::ranges::make_tagged_pair + +.SH Synopsis + Defined in header + template< TagSpecifier Tag1, TagSpecifier Tag2, class T1, class T2 > + constexpr ranges::tagged make_tagged_pair( (ranges TS) + T1&& x, T2&& y ); + + Convenience function for creating a tagged pair, deducing the element types from the + arguments (the tag specifiers must be explicitly specified). + + The see below portion of the return type is + decltype(std::make_pair(std::forward(x), std::forward(y))). + +.SH Return value + + R(std::forward(x), std::forward(y)), where R is the return type. + +.SH See also + + specifies that a type represents a tag specifier and its element + TaggedType type + (concept) + tagged augument a tuple-like type with named accessors + \fI(class template)\fP + tagged_pair alias template for a tagged std::pair + (alias template) + tagged_tuple alias template for a tagged std::tuple + (alias template) + make_tagged_tuple convenience function for creating a tagged_tuple + \fI(function template)\fP + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::make_tagged_tuple.3 b/man/std::experimental::ranges::make_tagged_tuple.3 new file mode 100644 index 000000000..7a680ac3c --- /dev/null +++ b/man/std::experimental::ranges::make_tagged_tuple.3 @@ -0,0 +1,47 @@ +.TH std::experimental::ranges::make_tagged_tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::make_tagged_tuple \- std::experimental::ranges::make_tagged_tuple + +.SH Synopsis + Defined in header + template< TagSpecifier... Tags, class... Types > + + requires sizeof...(Tags) == sizeof...(Types) (ranges TS) + + constexpr ranges::tagged make_tagged_tuple( + Types&&... t ); + + Convenience function for creating a tagged tuple, deducing the element types from + the arguments (the tag specifiers must be explicitly specified). + + The see below portion of the return type is + decltype(std::make_tuple(std::forward(t)...)). + +.SH Return value + + R(std::forward(t)...), where R is the return type. + +.SH See also + + specifies that a type represents a tag specifier and its element + TaggedType type + (concept) + tagged augument a tuple-like type with named accessors + \fI(class template)\fP + tagged_pair alias template for a tagged std::pair + (alias template) + make_tagged_pair convenience function for creating a tagged_pair + \fI(function template)\fP + tagged_tuple alias template for a tagged std::tuple + (alias template) + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::mismatch.3 b/man/std::experimental::ranges::mismatch.3 new file mode 100644 index 000000000..7c2465519 --- /dev/null +++ b/man/std::experimental::ranges::mismatch.3 @@ -0,0 +1,149 @@ +.TH std::experimental::ranges::mismatch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::mismatch \- std::experimental::ranges::mismatch + +.SH Synopsis + Defined in header + template< InputIterator I1, Sentinel S1, InputIterator I2, + Sentinel S2, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity, + class Pred = ranges::equal_to<> > + requires IndirectRelation, \fB(1)\fP (ranges TS) + projected> + auto mismatch( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred + = Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ) + + -> ranges::tagged_pair; + template< InputRange R1, InputRange R2, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity, + class Pred = ranges::equal_to<> > + requires IndirectRelation, Proj1>, \fB(2)\fP (ranges TS) + projected, + Proj2>> + auto mismatch( R1&& r1, R2&& r2, Pred pred = Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ) + -> ranges::tagged_pair), + + tag::in2(ranges::safe_iterator_t)>; + template< InputIterator I1, Sentinel S1, class I2, + + class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires InputIterator> && !Range && + IndirectRelation, (ranges TS) + projected, \fB(3)\fP \fB(deprecated)\fP + Proj2>> + auto mismatch( I1 first1, S1 last1, I2&& first2_, Pred pred = + Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ) + + -> ranges::tagged_pair)>; + template< InputRange R1, class I2, class Pred = ranges::equal_to<>, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires InputIterator> && !Range && + IndirectRelation, Proj1>, \fB(4)\fP (ranges TS) + projected, \fB(deprecated)\fP + Proj2>> + auto mismatch( R1&& r1, I2&& first2_, Pred pred = Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{} ) + -> ranges::tagged_pair), + + tag::in2(std::decay_t)>; + + 1) Returns the first mismatching pair of elements from two ranges: one defined by + [first1, last1) and another defined by [first2, last2). + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + 3) Same as \fB(1)\fP, but behaves as if first2 is std::decay_t first2 = + std::forward(first2_); and last2 is ranges::unreachable{}. The underlying + algorithm never increments first2 more than last1 - first1 times. + 4) Same as \fB(3)\fP, but uses r1 as the first source range, as if using ranges::begin(r1) + as first1 and ranges::end(r1) as last1. + + Elements are compared using pred to the projected elements of the two ranges, as if + by ranges::invoke(pred, ranges::invoke(proj1, *i), ranges::invoke(proj2, *j)). + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first1, last1 - the first range of the elements + r1 - the first range of the elements + first2, last2 - the second range of the elements + r2 - the second range of the elements + first2_ - the beginning of the second range of the elements + pred - predicate to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + A tagged_pair object with iterators to the first two non-equal elements (the + iterator from the first range has the tag in1 and the iterator from the second range + has the tag in2). + + If no mismatches are found when the comparison reaches last1 or last2, whichever + happens first, the pair holds the end iterator and the corresponding iterator from + the other range. + +.SH Complexity + + At most last1 - first1 applications of the predicate and each projection. + +.SH Possible implementation + + template S1, InputIterator I2, Sentinel S2, + class Proj1 = ranges::identity, class Proj2 = ranges::identity, + class Pred = ranges::equal_to<>> + requires IndirectRelation, projected> + auto mismatch(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = Pred{}, + Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{}) + -> ranges::tagged_pair + { + while (first1 != last1 && first2 != last2 && + ranges::invoke(pred, ranges::invoke(proj1, *first1), + ranges::invoke(proj2, *first2))) + { + ++first1; + ++first2; + } + return {first1, first2}; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + mismatch finds the first position where two ranges differ + \fI(function template)\fP + equal determines if two sets of elements are the same + \fI(function template)\fP + find finds the first element satisfying specific criteria + find_if \fI(function template)\fP + find_if_not + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::next.3 b/man/std::experimental::ranges::next.3 new file mode 100644 index 000000000..da5e0f8e7 --- /dev/null +++ b/man/std::experimental::ranges::next.3 @@ -0,0 +1,58 @@ +.TH std::experimental::ranges::next 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::next \- std::experimental::ranges::next + +.SH Synopsis + Defined in header + namespace { + (ranges TS) + constexpr /* unspecified */ next = /* unspecified */; (customization point + object) + } + Call signature + template< Iterator I > \fB(1)\fP + constexpr I next( I i ); + template< Iterator I > \fB(2)\fP + constexpr I next( I i, ranges::difference_type_t n ); + template< Iterator I, Sentinel S > \fB(3)\fP + constexpr I next( I i, S bound ); + template< Iterator I, Sentinel S > + constexpr I next( I i, ranges::difference_type_t n, S \fB(4)\fP + bound ); + + Advances the iterator i n times, or until bound is reached, whichever comes first, + and returns the advanced iterator. + + 1) Equivalent to ++i; return i;. + 2) Equivalent to ranges::advance(i, n); return i;. + 3) Equivalent to ranges::advance(i, bound); return i;. + 4) Equivalent to ranges::advance(i, n, bound); return i;. + +.SH Return value + + The advanced iterator. + +.SH Notes + + Even though omitting n for overload \fB(2)\fP behaves as if n is 1, omitting n for + overload \fB(4)\fP effectively behaves as if n is infinity (always advance to bound). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + next increment an iterator + \fI(C++11)\fP \fI(function template)\fP + advance advances an iterator by given distance + \fI(function template)\fP + prev decrement an iterator + \fI(function template)\fP + returns the distance between an iterator and a sentinel, or between the + distance beginning and the end of a range + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::not_equal_to.3 b/man/std::experimental::ranges::not_equal_to.3 new file mode 100644 index 000000000..f756e3d7f --- /dev/null +++ b/man/std::experimental::ranges::not_equal_to.3 @@ -0,0 +1,73 @@ +.TH std::experimental::ranges::not_equal_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::not_equal_to \- std::experimental::ranges::not_equal_to + +.SH Synopsis + Defined in header + template< class T = void > + + requires EqualityComparable || + Same || (ranges TS) + /* == on two const T lvalues invokes a built-in operator + comparing pointers */ + + struct not_equal_to; + template<> (ranges TS) + struct not_equal_to; + + Function object for performing comparisons. The primary template invokes operator == + on const lvalues of type T and negates the result. The specialization + not_equal_to deduces the parameter types of the function call operator from + the arguments (but not the return type). + + All specializations of not_equal_to are Semiregular. + +.SH Member types + + Member type Definition + is_transparent (member only of not_equal_to specialization) /* unspecified */ + +.SH Member functions + + operator() checks if the arguments are not equal + \fI(public member function)\fP + +std::experimental::ranges::not_equal_to::operator() + + constexpr bool operator()(const T& x, const \fB(1)\fP (member only of primary + T& y) const; not_equal_to template) + template< class T, class U > + + requires EqualityComparableWith || + /* std::declval() == + std::declval() resolves to \fB(2)\fP (member only of not_equal_to + a built-in operator comparing specialization) + pointers */ + + constexpr bool operator()(T&& t, U&& u) + const; + + 1) Compares x and y. Equivalent to return !ranges::equal_to<>{}(x, y);. + 2) Compares t and u. Equivalent to return !ranges::equal_to<>{}(std::forward(t), + std::forward(u));. + +.SH Notes + + Unlike std::not_equal_to, ranges::not_equal_to requires both == and != to be valid + (via the EqualityComparable and EqualityComparableWith constraints), and is entirely + defined in terms of ranges::equal_to. However, the implementation is free to use + operator!= directly, because those concepts require the results of == and != to be + consistent. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + not_equal_to function object implementing x != y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::prev.3 b/man/std::experimental::ranges::prev.3 new file mode 100644 index 000000000..1c821e7ec --- /dev/null +++ b/man/std::experimental::ranges::prev.3 @@ -0,0 +1,50 @@ +.TH std::experimental::ranges::prev 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::prev \- std::experimental::ranges::prev + +.SH Synopsis + Defined in header + namespace { + (ranges TS) + constexpr /* unspecified */ prev = /* unspecified */; (customization point + object) + } + Call signature + template< Iterator I > \fB(1)\fP + constexpr I prev( I i ); + template< Iterator I > \fB(2)\fP + constexpr I prev( I i, ranges::difference_type_t n ); + template< Iterator I > + constexpr I prev( I i, ranges::difference_type_t n, I \fB(3)\fP + bound ); + + Decrements the iterator i n times, or until bound is reached, whichever comes first, + and returns the decremented iterator. + + 1) Equivalent to --i; return i;. + 2) Equivalent to ranges::advance(i, -n); return i;. + 3) Equivalent to ranges::advance(i, -n, bound); return i;. + +.SH Return value + + The decremented iterator. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + prev decrement an iterator + \fI(C++11)\fP \fI(function template)\fP + advance advances an iterator by given distance + \fI(function template)\fP + next increment an iterator + \fI(function template)\fP + returns the distance between an iterator and a sentinel, or between the + distance beginning and the end of a range + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::projected.3 b/man/std::experimental::ranges::projected.3 new file mode 100644 index 000000000..1b7327bc1 --- /dev/null +++ b/man/std::experimental::ranges::projected.3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::projected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::projected \- std::experimental::ranges::projected + +.SH Synopsis +Defined in header +template< Readable I, IndirectRegularUnaryInvocable Proj > + +struct projected { + using value_type = + +std::remove_cv_t>>; + ranges::indirect_result_of_t operator*() const; (ranges +}; TS) + +template< WeaklyIncrementable I, class Proj > +struct difference_type> { + using type = ranges::difference_type_t; + +}; + + The class template projected bundles a Readable type I and a function Proj into a + new Readable type whose reference type is the result of applying Proj to the + reference type of I. It exists solely to ease constraint specification, and so its + operator*() may not be actually defined. diff --git a/man/std::experimental::ranges::reference_t,std::experimental::ranges::rvalue_reference_t,.3 b/man/std::experimental::ranges::reference_t,std::experimental::ranges::rvalue_reference_t,.3 new file mode 100644 index 000000000..d194f7f40 --- /dev/null +++ b/man/std::experimental::ranges::reference_t,std::experimental::ranges::rvalue_reference_t,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::ranges::reference_t,std::experimental::ranges::rvalue_reference_t, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::reference_t,std::experimental::ranges::rvalue_reference_t, \- std::experimental::ranges::reference_t,std::experimental::ranges::rvalue_reference_t, + +.SH Synopsis + + Defined in header + template< class T > (exposition + concept bool /*dereferenceable*/ = requires(T& t) { {*t} -> auto&&; only*) + }; + template< /*dereferenceable*/ T > \fB(1)\fP (ranges TS) + using reference_t = decltype(*declval()); + template< /*dereferenceable*/ T > + + requires requires(T& t) { { ranges::iter_move(t) } -> auto&&; } \fB(2)\fP (ranges TS) + + using rvalue_reference_t = + decltype(ranges::iter_move(declval())); + template< Readable T > + + using iter_common_reference_t = + ranges::common_reference_t, \fB(3)\fP (ranges TS) + + + ranges::value_type_t&>; + + 1) Obtain the reference type of a dereferenceable type T. + 2) Obtain the rvalue reference type of a dereferenceable type T, that is, the return + type of ranges::iter_move. + 3) Compute a Readable type's common reference type. This is the common reference + type of its reference type and an lvalue reference to its value type. + +.SH Notes + + The -> auto&& constraint checks that the type of the expression is not void. diff --git a/man/std::experimental::ranges::search.3 b/man/std::experimental::ranges::search.3 new file mode 100644 index 000000000..5a6ba29cc --- /dev/null +++ b/man/std::experimental::ranges::search.3 @@ -0,0 +1,118 @@ +.TH std::experimental::ranges::search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::search \- std::experimental::ranges::search + +.SH Synopsis + Defined in header + template< ForwardIterator I1, Sentinel S1, + + ForwardIterator I2, Sentinel S2, class Pred = + ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > \fB(1)\fP (ranges TS) + requires IndirectlyComparable + I1 search( I1 first1, S1 last1, I2 first2, S2 last2, + + Pred pred = Pred{}, Proj1 proj1 = Proj1{}, Proj2 proj2 = + Proj2{} ); + template< ForwardRange R1, ForwardRange R2, class Pred = + ranges::equal_to<>, + + class Proj1 = ranges::identity, class Proj2 = + ranges::identity > + requires IndirectlyComparable, + ranges::iterator_t, \fB(2)\fP (ranges TS) + Pred, Proj1, Proj2> + ranges::safe_iterator_t search( R1&& r1, R2&& r2, Pred pred = + Pred{}, + + Proj1 proj1 = Proj1{}, Proj2 + proj2 = Proj2{} ); + + 1) Searches for the first occurrence of the sequence of elements [first2, last2) in + the range [first1, last1). Elements are compared using pred after being projected + with proj2 and proj1, respectively. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first1, last1 - the range of elements to examine + r1 - the range of elements to examine + first2, last2 - the range of elements to search for + r2 - the range of elements to search for + pred - predicate to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + An iterator to the beginning of first occurrence of the sequence [first2, last2) in + the range [first1, last1). If [first2, last2) is empty, first1 is returned. If no + such occurrence is found, an iterator that compares equal to last1 is returned. + +.SH Complexity + + At most S * N applications of the predicate and each projection, where S = last2 - + first2 and N = last1 - first1. + +.SH Possible implementation + + template S1, + ForwardIterator I2, Sentinel S2, class Pred = ranges::equal_to<>, + class Proj1 = ranges::identity, class Proj2 = ranges::identity> + requires IndirectlyComparable + I1 search(I1 first1, S1 last1, I2 first2, S2 last2, + Pred pred = Pred{}, Proj1 proj1 = Proj1{}, Proj2 proj2 = Proj2{}) + { + for (; ; ++first1) + { + I1 it = first1; + for (I2 it2 = first2; ; (void)++it, (void)++it2) + { + if (it2 == last2) + return first1; + if (it == last1) + return it; + if (!ranges::invoke(pred, ranges::invoke(proj1, *it), + ranges::invoke(proj2, *it2))) + break; + } + } + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + includes returns true if one set is a subset of another + \fI(function template)\fP + equal determines if two sets of elements are the same + \fI(function template)\fP + find finds the first element satisfying specific criteria + find_if \fI(function template)\fP + find_if_not + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + searches for a number consecutive copies of an element in a + search_n range + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::search_n.3 b/man/std::experimental::ranges::search_n.3 new file mode 100644 index 000000000..d8200c9f0 --- /dev/null +++ b/man/std::experimental::ranges::search_n.3 @@ -0,0 +1,106 @@ +.TH std::experimental::ranges::search_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::search_n \- std::experimental::ranges::search_n + +.SH Synopsis + Defined in header + template< ForwardIterator I, Sentinel S, class T, + + class Pred = ranges::equal_to<>, class Proj = + ranges::identity > + requires IndirectlyComparable \fB(1)\fP (ranges TS) + I search_n( I first, S last, ranges::difference_type_t count, + + const T& value, Pred pred = Pred{}, Proj proj = Proj{} + ); + template< ForwardRange R, class T, class Pred = ranges::equal_to<>, + + class Proj = ranges::identity > + requires IndirectlyComparable, const T*, + Pred, Proj> + ranges::safe_iterator_t search_n( R&& r, \fB(2)\fP (ranges TS) + + ranges::difference_type_t> count, + + const T& value, Pred pred = + Pred{}, Proj proj = Proj{} ); + + 1) Searches the range [first, last) for the first sequence of count elements whose + projected values are each equal to the given value value according to the predicate + pred. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + count - the length of the sequence to search for + value - the value to search for + pred - the predicate that compares the projected elements with value + proj - the projection to apply to the elements + +.SH Return value + + Iterator to the beginning of the found sequence in the range [first, last). If no + such sequence is found, an iterator that compares equal to last is returned. + +.SH Complexity + + At most last - first applications of the predicate and the projection. + +.SH Possible implementation + + template S, class T, + class Pred = ranges::equal_to<>, class Proj = ranges::identity> + requires IndirectlyComparable + I search_n(I first, S last, ranges::difference_type_t count, + const T& value, Pred pred = Pred{}, Proj proj = Proj{}) + { + for (; first != last; ++first) + { + if (!ranges::invoke(pred, ranges::invoke(proj, *first), value)) + continue; + + I candidate = first; + ranges::difference_type_t cur_count = 0; + + while (true) + { + ++cur_count; + if (cur_count == count) + // success + return candidate; + + ++first; + if (first == last) + // exhausted the list + return first; + + if (!ranges::invoke(pred, ranges::invoke(proj, *first), value)) + // too few in a row + break; + } + } + return first; + } + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + search_n searches a range for a number of consecutive copies of an element + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + find finds the first element satisfying specific criteria + find_if \fI(function template)\fP + find_if_not + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::sort.3 b/man/std::experimental::ranges::sort.3 new file mode 100644 index 000000000..d34facb78 --- /dev/null +++ b/man/std::experimental::ranges::sort.3 @@ -0,0 +1,61 @@ +.TH std::experimental::ranges::sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::sort \- std::experimental::ranges::sort + +.SH Synopsis + Defined in header + template< RandomAccessIterator I, Sentinel S, + + class Comp = ranges::less<>, class Proj = ranges::identity + > \fB(1)\fP (ranges TS) + requires Sortable + + I sort( I first, S last, Comp comp = Comp{}, Proj proj = Proj{} ); + template< RandomAccessRange R, + + class Comp = ranges::less<>, class Proj = ranges::identity + > \fB(2)\fP (ranges TS) + requires Sortable, Comp, Proj> + + ranges::safe_iterator_t sort( R&& r, Comp comp = Comp{}, Proj + proj = Proj{} ); + + 1) Sorts the elements in the range [first, last) in ascending order. The order of + equal elements is not guaranteed to be preserved. Elements are compared using comp + after applying the projection proj. + 2) Sorts the elements in the range r, as if by return ranges::sort(ranges::begin(r), + ranges::end(r), comp, proj);. + + Notwithstanding the declarations depicted above, the actual number and order of + template parameters for algorithm declarations is unspecified. Thus, if explicit + template arguments are used when calling an algorithm, the program is probably + non-portable. + +.SH Parameters + + first, last - the range of elements to sort + r - the range of elements to sort + comp - the comparator to use + proj - the projection to apply to elements in the range + +.SH Return value + + An iterator pointing past the end of the range (i.e., it compares equal to last for + overload \fB(1)\fP, and ranges::end(r) for overload \fB(2)\fP). + +.SH Complexity + + O(N·log(N)) comparisons, where N is equal to the number of elements in the range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sort sorts a range into ascending order + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::ranges::swap(ranges::tagged).3 b/man/std::experimental::ranges::swap(ranges::tagged).3 new file mode 100644 index 000000000..652b4f655 --- /dev/null +++ b/man/std::experimental::ranges::swap(ranges::tagged).3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::swap(ranges::tagged) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::swap(ranges::tagged) \- std::experimental::ranges::swap(ranges::tagged) + +.SH Synopsis + friend constexpr void swap( tagged& lhs, tagged& rhs ) + noexcept(noexcept(lhs.swap(rhs))) + requires Swappable; + + Swap the contents of *this and rhs, as if by lhs.swap(rhs);. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when tagged is an associated class of the + arguments. + +.SH Notes + + Unlike most non-member swaps in the standard library, this swap is a hidden friend + function declared in the body of tagged, not a function template. The tagged in the + function declaration is the injected-class-name. + +.SH See also + + swap swaps the contents of two tagged objects + \fI(public member function)\fP diff --git a/man/std::experimental::ranges::swap.3 b/man/std::experimental::ranges::swap.3 new file mode 100644 index 000000000..93e7d5ae9 --- /dev/null +++ b/man/std::experimental::ranges::swap.3 @@ -0,0 +1,70 @@ +.TH std::experimental::ranges::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::swap \- std::experimental::ranges::swap + +.SH Synopsis + Defined in header + namespace { + + constexpr /* unspecified */ swap = /* unspecified (ranges TS) + */; (customization point object) + + } + Call signature + template< class T, class U > + + requires /* see below */ + + void swap( T&& t, U&& u ) noexcept(/* see below */); + + Exchanges the values referenced by t and u. + + A call to ranges::swap is equivalent to: + + 1) (void)swap(std::forward(t), std::forward(u)), if that expression is valid, + where the overload resolution is performed with the following candidates: + * template void swap(T&, T&) = delete; + * template void swap(T(&)[N], T(&)[N]) = delete; + * any declarations of swap found by argument-dependent lookup. + If the function selected by overload resolution does not exchange the values + referenced by t and u, the program is ill-formed; no diagnostic required. + 2) Otherwise, (void)ranges::swap_ranges(t, u), if T and U are lvalue references to + array types of equal extent (but possibly different element types) and + ranges::swap(*t, *u) is a valid expression. + 3) Otherwise, if T and U are both V& for some type V that meets the syntactic + requirements of MoveConstructible and Assignable, exchanges the referenced + values as if by V v{std::move(t)}; t = std::move(u); u = std::move(v);. If the + semantic requirements of either concept are not satisfied, the program is + ill-formed; no diagnostic required. + 4) In all other cases, a call to ranges::swap is ill-formed. + + ranges::swap can be used in a constant expression if every function it calls (as + specified above) can be so used. + +.SH Exceptions + + 1) + noexcept specification: + noexcept(noexcept((void)swap(std::forward(t), std::forward(u)))) + , where swap is found as described above. + 2) + noexcept specification: + noexcept(noexcept(ranges::swap(*t, *u))) + 3) + noexcept specification: + noexcept(std::is_nothrow_move_constructible::value && + std::is_nothrow_move_assignable::value) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::ranges::tag::in,in1,in2,out,out1,out2,fun,min,max,begin,end.3 b/man/std::experimental::ranges::tag::in,in1,in2,out,out1,out2,fun,min,max,begin,end.3 new file mode 100644 index 000000000..98a1917eb --- /dev/null +++ b/man/std::experimental::ranges::tag::in,in1,in2,out,out1,out2,fun,min,max,begin,end.3 @@ -0,0 +1,25 @@ +.TH std::experimental::ranges::tag::in,in1,in2,out,out1,out2,fun,min,max,begin,end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tag::in,in1,in2,out,out1,out2,fun,min,max,begin,end \- std::experimental::ranges::tag::in,in1,in2,out,out1,out2,fun,min,max,begin,end + +.SH Synopsis + Defined in header + struct in { /* implementation-defined */ }; + + struct in1 { /* implementation-defined */ }; + struct in2 { /* implementation-defined */ }; + struct out { /* implementation-defined */ }; + struct out1 { /* implementation-defined */ }; + struct out2 { /* implementation-defined */ }; (ranges TS) + struct fun { /* implementation-defined */ }; + struct min { /* implementation-defined */ }; + struct max { /* implementation-defined */ }; + struct begin { /* implementation-defined */ }; + + struct end { /* implementation-defined */ }; + + These classes are TagSpecifiers for use with ranges::tagged. + + The name of a specifier is also the element name it corresponds to. For instance, + ranges::tagged, tag::min, tag::max> provides a set of named + accessors named min and a set of named accessors named max. diff --git a/man/std::experimental::ranges::tagged.3 b/man/std::experimental::ranges::tagged.3 new file mode 100644 index 000000000..95855280e --- /dev/null +++ b/man/std::experimental::ranges::tagged.3 @@ -0,0 +1,78 @@ +.TH std::experimental::ranges::tagged 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tagged \- std::experimental::ranges::tagged + +.SH Synopsis + Defined in header + template< class Base, TagSpecifier... Tags > + + requires sizeof...(Tags) <= std::tuple_size::value (ranges TS) + + struct tagged; + + The class template tagged augments a tuple-like class type Base, which it publicly + derives from, with a set of named accessors specified by the tag specifiers Tags.... + The tags are applied in order: the i-th tag specifier in Tags... correspond to the + i-th element of the tuple. + + The tag specifiers in Tags... shall be unique. Otherwise, the behavior is undefined. + + It is not possible to delete an instance of tagged through a pointer to any base + other than Base. + +.SH Member functions + + constructor construct a tagged object + \fI(public member function)\fP + operator= assigns a tagged object + \fI(public member function)\fP + swap swaps the contents of two tagged objects + \fI(public member function)\fP + + Named element accessors + + For the N-th tag specifier in Tags... whose corresponding element name is name, + tagged provides accessors named name as follows: + + constexpr decltype(auto) name() & { return std::get(*this); } + constexpr decltype(auto) name() const & { return std::get(*this); } + constexpr decltype(auto) name() && { return std::get(std::move(*this)); } + +.SH Non-member functions + + ranges::swap(ranges::tagged) specializes swap for tagged objects + \fI(function)\fP + + Tuple-like access + + obtains the size of a tagged + std::tuple_size (class template + specialization) + obtains the types of the + std::tuple_element elements of a tagged + (class template + specialization) + +.SH See also + + TagSpecifier specifies that a type is a tag specifier + (concept) + tagged_pair alias template for a tagged std::pair + (alias template) + make_tagged_pair convenience function for creating a tagged_pair + \fI(function template)\fP + tagged_tuple alias template for a tagged std::tuple + (alias template) + make_tagged_tuple convenience function for creating a tagged_tuple + \fI(function template)\fP + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::tagged::operator=.3 b/man/std::experimental::ranges::tagged::operator=.3 new file mode 100644 index 000000000..445692649 --- /dev/null +++ b/man/std::experimental::ranges::tagged::operator=.3 @@ -0,0 +1,39 @@ +.TH std::experimental::ranges::tagged::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tagged::operator= \- std::experimental::ranges::tagged::operator= + +.SH Synopsis + tagged &operator=( tagged&& that ) = default; \fB(1)\fP + tagged &operator=( const tagged& that ) = default; \fB(2)\fP + template< class Other > + + requires Assignable \fB(3)\fP + constexpr tagged& operator=( ranges::tagged&& that ) + + noexcept(std::is_nothrow_assignable::value); + template< class Other > + + requires Assignable \fB(4)\fP + + constexpr tagged& operator=( const ranges::tagged& that ); + template< class U > + + requires Assignable && !Same, tagged> \fB(5)\fP + + constexpr tagged& operator=( U&& that ) + noexcept(std::is_nothrow_assignable::value); + + Assigns the contents of that to *this. + + 1,2) tagged has defaulted copy and move assignment operators that invoke the + corresponding assignment operator of Base. + 3) Converting move assignment from a different tagged specialization with matching + tags. Equivalent to static_cast(*this) = static_cast(that);. + 4) Converting copy assignment from a different tagged specialization with matching + tags. Equivalent to static_cast(*this) = static_cast(that);. + 5) Assigns that to the Base subobject. Equivalent to static_cast(*this) = + std::forward(that);. + +.SH Return value + + *this. diff --git a/man/std::experimental::ranges::tagged::swap.3 b/man/std::experimental::ranges::tagged::swap.3 new file mode 100644 index 000000000..872840083 --- /dev/null +++ b/man/std::experimental::ranges::tagged::swap.3 @@ -0,0 +1,23 @@ +.TH std::experimental::ranges::tagged::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tagged::swap \- std::experimental::ranges::tagged::swap + +.SH Synopsis + constexpr void swap( tagged& rhs ) noexcept(/* see below */) + requires Swappable; + + Swap the contents of *this and rhs, as if by ranges::swap(static_cast(*this), + static_cast(rhs));. + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(ranges::swap(std::declval(), std::declval()))) + +.SH See also + + ranges::swap(ranges::tagged) specializes swap for tagged objects + \fI(function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::experimental::ranges::tagged::tagged.3 b/man/std::experimental::ranges::tagged::tagged.3 new file mode 100644 index 000000000..2f7538667 --- /dev/null +++ b/man/std::experimental::ranges::tagged::tagged.3 @@ -0,0 +1,38 @@ +.TH std::experimental::ranges::tagged::tagged 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tagged::tagged \- std::experimental::ranges::tagged::tagged + +.SH Synopsis + using Base::Base; \fB(1)\fP + tagged() = default; \fB(2)\fP + tagged( tagged&& that ) = default; \fB(3)\fP + tagged( const tagged& that ) = default; \fB(4)\fP + tagged( Base&& that ) noexcept(std::is_nothrow_move_constructible::value) \fB(5)\fP + requires MoveConstructible; + tagged( const Base& that ) + noexcept(std::is_nothrow_copy_constructible::value) \fB(6)\fP + requires CopyConstructible; + template< class Other > + + requires Constructible \fB(7)\fP + constexpr tagged( ranges::tagged && that ) + + noexcept(std::is_nothrow_constructible::value); + template< class Other > + + requires Constructible \fB(8)\fP + + constexpr tagged( const ranges::tagged &that ); + + Constructs a tagged object. + + 1) tagged inherits the constructors of Base. + 2-4) tagged has defaulted default, copy, and move constructors that invoke the + corresponding constructor of Base. + 5) Converting move constructor from Base. Initializes the Base subobject with + std::move(that). + 6) Converting copy constructor from Base. Initializes the Base subobject with that. + 7) Converting move constructor from a different tagged specialization with matching + tags. Initializes the Base subobject with static_cast(that). + 8) Converting copy constructor from a different tagged specialization with matching + tags. Initializes the Base subobject with static_cast(that). diff --git a/man/std::experimental::ranges::tagged_pair.3 b/man/std::experimental::ranges::tagged_pair.3 new file mode 100644 index 000000000..9db34f3dd --- /dev/null +++ b/man/std::experimental::ranges::tagged_pair.3 @@ -0,0 +1,49 @@ +.TH std::experimental::ranges::tagged_pair 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tagged_pair \- std::experimental::ranges::tagged_pair + +.SH Synopsis + Defined in header + template< TaggedType T1, TaggedType T2 > (ranges TS) + using tagged_pair = /* see below */; + + Convenience alias template for naming a ranges::tagged wrapping a std::pair. + + A TaggedType is a function type S(T), where S is a TagSpecifier and T is the type of + the element. + + tagged_pair is an alias for ranges::tagged, S1, + S2>. + +.SH Notes + + Because a function type is used to "glue" the tag specifier and the corresponding + element type together, the usual parameter type adjustments apply. In particular, + top-level cv-qualifiers are removed and array types are adjusted to pointers: + tagged_pair is + ranges::tagged, tag::in, tag::out>. + +.SH See also + + specifies that a type represents a tag specifier and its element + TaggedType type + (concept) + tagged augument a tuple-like type with named accessors + \fI(class template)\fP + make_tagged_pair convenience function for creating a tagged_pair + \fI(function template)\fP + tagged_tuple alias template for a tagged std::tuple + (alias template) + make_tagged_tuple convenience function for creating a tagged_tuple + \fI(function template)\fP + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::tagged_tuple.3 b/man/std::experimental::ranges::tagged_tuple.3 new file mode 100644 index 000000000..2ae84b12e --- /dev/null +++ b/man/std::experimental::ranges::tagged_tuple.3 @@ -0,0 +1,49 @@ +.TH std::experimental::ranges::tagged_tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::tagged_tuple \- std::experimental::ranges::tagged_tuple + +.SH Synopsis + Defined in header + template< TaggedType... Types > (ranges TS) + using tagged_tuple = /* see below */; + + Convenience alias template for naming a ranges::tagged wrapping a std::tuple. + + A TaggedType is a function type S(T), where S is a TagSpecifier and T is the type of + the element. + + tagged_tuple is an alias for ranges::tagged, S1, ..., SN>. + +.SH Notes + + Because a function type is used to "glue" the tag specifier and the corresponding + element type together, the usual parameter type adjustments apply. In particular, + top-level cv-qualifiers are removed and array types are adjusted to pointers: + tagged_tuple is + ranges::tagged, tag::in, tag::out>. + +.SH See also + + specifies that a type represents a tag specifier and its element + TaggedType type + (concept) + tagged augument a tuple-like type with named accessors + \fI(class template)\fP + tagged_pair alias template for a tagged std::pair + (alias template) + make_tagged_pair convenience function for creating a tagged_pair + \fI(function template)\fP + make_tagged_tuple convenience function for creating a tagged_tuple + \fI(function template)\fP + in + in1 + in2 + out + out1 tag specifiers for use with ranges::tagged + out2 \fI(class)\fP + fun + min + max + begin + end diff --git a/man/std::experimental::ranges::value_type.3 b/man/std::experimental::ranges::value_type.3 new file mode 100644 index 000000000..efe387336 --- /dev/null +++ b/man/std::experimental::ranges::value_type.3 @@ -0,0 +1,67 @@ +.TH std::experimental::ranges::value_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::ranges::value_type \- std::experimental::ranges::value_type + +.SH Synopsis + Defined in header + template< class I > \fB(1)\fP + struct value_type {}; + template< class T > \fB(2)\fP + struct value_type; + template< class I > + + requires std::is_array::value \fB(3)\fP + + struct value_type : value_type> {}; + template< class T > \fB(4)\fP + struct value_type : value_type> {}; + template< class T > + + requires requires { typename T::value_type; } \fB(5)\fP + + struct value_type; + template< class T > + + requires requires { typename T::element_type; } \fB(6)\fP + + struct value_type; + + Computes the associated value type of the type I, if any. Users may specialize + value_type for a program-defined type. + + 1) Primary template is an empty struct. + 2) Specialization for pointers. If T is an object type, provides a member type type + equal to std::remove_cv_t. Otherwise, there is no member type. + 3) Specialization for array types. + 4) Specialization for const-qualified types. + 5) Specialization for types that define a public and accessible member type + value_type. If T::value_type is an object type, provides a member type type equal to + T::value_type. Otherwise, there is no member type. + 6) Specialization for types that define a public and accessible member type + element_type (e.g., std::shared_ptr). If T::element_type is an object type, provides + a member type type equal to std::remove_cv_t. Otherwise, + there is no member type. + +.SH Notes + + If a type contains both a value_type member and a element_type member, then the + specializations \fB(5)\fP and \fB(6)\fP are ambiguous. + + value_type is intended for use with Readable types such as iterators. It is not + intended for use with ranges. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + Readable specifies that a type is readable by applying operator * + (concept) + compatibility traits class that collects an iterator’s associated + iterator_traits types + (alias template) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::rebind_simd,std::experimental::resize_simd.3 b/man/std::experimental::rebind_simd,std::experimental::resize_simd.3 new file mode 100644 index 000000000..967ad2735 --- /dev/null +++ b/man/std::experimental::rebind_simd,std::experimental::resize_simd.3 @@ -0,0 +1,79 @@ +.TH std::experimental::rebind_simd,std::experimental::resize_simd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::rebind_simd,std::experimental::resize_simd \- std::experimental::rebind_simd,std::experimental::resize_simd + +.SH Synopsis + Defined in header + template< class T, class V > \fB(1)\fP (parallelism TS v2) + struct rebind_simd; + template< int N, class V > \fB(2)\fP (parallelism TS v2) + struct resize_simd; + + Creates a simd or simd_mask type with a different element type or size. The new type + likely uses an ABI tag type different from V::abi_type. + + 1) Changes the element type to T and keeps the size unchanged. + 2) Changes the size to N and keeps the element type unchanged. + +.SH Template parameters + + T - the new element type; an arithmetic type other than bool + N - the new number of elements + V - a simd or simd_mask type + +.SH Member types + + Name Definition + type simd or simd_mask type with a different element type \fB(1)\fP or size \fB(2)\fP + +.SH Helper types + + template< class T, class V > (parallelism TS v2) + using rebind_simd_t = typename rebind_simd::type; + template< int N, class V > (parallelism TS v2) + using resize_simd_t = typename resize_simd::type; + +.SH Example + + +// Run this code + + #include + #include + + namespace stdx = std::experimental; + using floatv = stdx::native_simd; + + // use double precision internally + floatv dp(floatv x) + { + using doublev = stdx::rebind_simd_t; + return stdx::static_simd_cast(stdx::simd_cast(x) - 1.234); + } + + template + stdx::resize_simd_t partial_reduction(T x) + { + auto [lo, hi] = stdx::split>(x); + return lo + hi; + } + + int main() + { + floatv x([](auto i) { return 1.234f + std::numeric_limits::epsilon() * i; }); + x = dp(x); + const auto y = partial_reduction(x); + for (unsigned i = 0; i < y.size(); ++i) + std::cout << y[i] << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 1.73569e-07 4.11987e-07 + +.SH See also + + deduce obtains an ABI type for given element type and number of + deduce_t elements + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::reduce,std::experimental::hmin,std::experimental::hmax.3 b/man/std::experimental::reduce,std::experimental::hmin,std::experimental::hmax.3 new file mode 100644 index 000000000..5fc01b7d7 --- /dev/null +++ b/man/std::experimental::reduce,std::experimental::hmin,std::experimental::hmax.3 @@ -0,0 +1,139 @@ +.TH std::experimental::reduce,std::experimental::hmin,std::experimental::hmax 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reduce,std::experimental::hmin,std::experimental::hmax \- std::experimental::reduce,std::experimental::hmin,std::experimental::hmax + +.SH Synopsis + Defined in header + template< class T, class Abi, class BinaryOperation = + std::plus<> > \fB(1)\fP (parallelism TS v2) + T reduce( const simd& v, BinaryOperation binary_op + = {} ); + template< class M, class V, class BinaryOperation > + + typename V::value_type + reduce( const const_where_expression& x, \fB(2)\fP (parallelism TS v2) + + typename V::value_type identity_element, + BinaryOperation binary_op = {} ); + template< class M, class V > + + typename V::value_type \fB(3)\fP (parallelism TS v2) + + reduce( const const_where_expression& x, std::plus<> + binary_op ) noexcept; + template< class M, class V > + + typename V::value_type \fB(4)\fP (parallelism TS v2) + + reduce( const const_where_expression& x, + std::multiplies<> binary_op ) noexcept; + template< class M, class V > + + typename V::value_type \fB(5)\fP (parallelism TS v2) + + reduce( const const_where_expression& x, + std::bit_and<> binary_op ) noexcept; + template< class M, class V > + + typename V::value_type \fB(6)\fP (parallelism TS v2) + + reduce( const const_where_expression& x, + std::bit_or<> binary_op ) noexcept; + template< class M, class V > + + typename V::value_type \fB(7)\fP (parallelism TS v2) + + reduce( const const_where_expression& x, + std::bit_xor<> binary_op ) noexcept; + template< class T, class Abi > \fB(8)\fP (parallelism TS v2) + T hmin( const simd& v ) noexcept; + template< class M, class V > + + typename V::value_type \fB(9)\fP (parallelism TS v2) + + hmin( const const_where_expression& x ) noexcept; + template< class T, class Abi > \fB(10)\fP (parallelism TS v2) + T hmax( const simd& v ) noexcept; + template< class M, class V > + + typename V::value_type \fB(11)\fP (parallelism TS v2) + + hmax( const const_where_expression& x ) noexcept; + + 1) Reduces all values in v over binary_op. + 2) Reduces the values in x where the associated mask element is true over binary_op. + 3) Returns the sum of all values in x where the associated mask element is true. + 4) Returns the product of all values in x where the associated mask element is true. + 5) Returns the aggregation using bitwise-and of all values in x where the associated + mask element is true. + 6) Returns the aggregation using bitwise-or of all values in x where the associated + mask element is true. + 7) Returns the aggregation using bitwise-xor of all values in x where the associated + mask element is true. + 8) Reduces all values in v over std::min. + 9) Reduces all values in x where the associated mask element is true over std::min. + 10) Reduces all values in v over std::max. + 11) Reduces all values in x where the associated mask element is true over std::max. + + The behavior is non-deterministic if binary_op is not associative or not + commutative. + +.SH Parameters + + v - the simd vector to apply the reduction to + x - the return value of a where expression to apply the reduction to + a value that acts as identity element for binary_op; + identity_element - binary_op(identity_element, a) == a must hold for all finite a of + type V::value_type + binary FunctionObject that will be applied in unspecified order + binary_op - to arguments of type V::value_type or simd, + with unspecified ABI tag A. binary_op(v, v) must be convertible + to V + +.SH Return value + + The result of operation of the type: + + 1,8,10) T + 2-7,9,11) V::value_type + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + namespace stdx = std::experimental; + + int main() + { + using V = stdx::native_simd; + + alignas(stdx::memory_alignment_v) std::array data; + std::iota(data.begin(), data.end(), 0); + + V::value_type acc{}; + for (std::size_t i = 0; i < data.size(); i += V::size()) + acc += stdx::reduce(V(&data[i], stdx::vector_aligned), std::plus{}); + std::cout << "sum of data = " << acc << '\\n'; + + using W = stdx::fixed_size_simd; + alignas(stdx::memory_alignment_v) std::array arr{2, 5, 4, 1}; + auto w = W(&arr[0], stdx::vector_aligned); + assert(stdx::hmin(w) == 1 and stdx::hmax(w) == 5); + } + +.SH Output: + + sum of data = 523776 + +.SH See also + + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::experimental::reflect::Alias.3 b/man/std::experimental::reflect::Alias.3 new file mode 100644 index 000000000..c84f7b4f7 --- /dev/null +++ b/man/std::experimental::reflect::Alias.3 @@ -0,0 +1,26 @@ +.TH std::experimental::reflect::Alias 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Alias \- std::experimental::reflect::Alias + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Alias = Named && ScopedMember && /* see below */; + + The Alias concept is satisfied if and only if T reflects a typedef declaration, an + alias-declaration, a namespace alias, a template type parameter, a + decltype-specifier, or a declaration introduced by using-declaration (Note: The + Scope of an Alias is the scope that the alias was injected into). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Base.3 b/man/std::experimental::reflect::Base.3 new file mode 100644 index 000000000..3292341af --- /dev/null +++ b/man/std::experimental::reflect::Base.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Base \- std::experimental::reflect::Base + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Base = Object && /* see below */; + + The Base concept is satisfied if and only if T reflects a direct base class, as + returned by the template get_base_classes. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Callable.3 b/man/std::experimental::reflect::Callable.3 new file mode 100644 index 000000000..d68844135 --- /dev/null +++ b/man/std::experimental::reflect::Callable.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Callable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Callable \- std::experimental::reflect::Callable + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Callable = ScopeMember && Scope && /* see below */; + + The Callable concept is satisfied if and only if T reflects a function, including + constructors and destructors. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Class.3 b/man/std::experimental::reflect::Class.3 new file mode 100644 index 000000000..389fa21f8 --- /dev/null +++ b/man/std::experimental::reflect::Class.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Class 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Class \- std::experimental::reflect::Class + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Class = Record && /* see below */; + + The Class concept is satisfied if and only if T reflects a non-union class type. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Constant.3 b/man/std::experimental::reflect::Constant.3 new file mode 100644 index 000000000..a5635d544 --- /dev/null +++ b/man/std::experimental::reflect::Constant.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Constant 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Constant \- std::experimental::reflect::Constant + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Constant = ScopeMember && Typed && /* see below */; + + The Constant concept is satisfied if and only if T reflects a constant expression. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Constructor.3 b/man/std::experimental::reflect::Constructor.3 new file mode 100644 index 000000000..75340af63 --- /dev/null +++ b/man/std::experimental::reflect::Constructor.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::Constructor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Constructor \- std::experimental::reflect::Constructor + +.SH Synopsis + Defined in header + template< class T > + concept Constructor = Callable && RecordMember && /* see (reflection TS) + below */; + + The Constructor concept is satisfied if and only if T reflects a constructor (Note: + Some types that satisfy Constructor also satisfy SpecialMemberFunction). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::ConversionOperator.3 b/man/std::experimental::reflect::ConversionOperator.3 new file mode 100644 index 000000000..061ec7e4d --- /dev/null +++ b/man/std::experimental::reflect::ConversionOperator.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::ConversionOperator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::ConversionOperator \- std::experimental::reflect::ConversionOperator + +.SH Synopsis + Defined in header + template< class T > + concept ConversionOperator = Operator && MemberFunction && /* (reflection TS) + see below */; + + The ConversionOperator concept is satisfied if and only if T reflects a conversion + function. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Destructor.3 b/man/std::experimental::reflect::Destructor.3 new file mode 100644 index 000000000..899f20f34 --- /dev/null +++ b/man/std::experimental::reflect::Destructor.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Destructor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Destructor \- std::experimental::reflect::Destructor + +.SH Synopsis + Defined in header + template< class T > + concept Destructor = Callable && SpecialMemberFunction && /* (reflection TS) + see below */; + + The Destructor concept is satisfied if and only if T reflects a destructor. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Enum.3 b/man/std::experimental::reflect::Enum.3 new file mode 100644 index 000000000..8f0866ab1 --- /dev/null +++ b/man/std::experimental::reflect::Enum.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Enum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Enum \- std::experimental::reflect::Enum + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Enum = Type && Scope && /* see below */; + + The Enum concept is satisfied if and only if T reflects an enumeration type. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Enumerator.3 b/man/std::experimental::reflect::Enumerator.3 new file mode 100644 index 000000000..c9987afa2 --- /dev/null +++ b/man/std::experimental::reflect::Enumerator.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::Enumerator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Enumerator \- std::experimental::reflect::Enumerator + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Enumerator = Typed && ScopeMember && /* see below */; + + The Enumerator concept is satisfied if and only if T reflects an enumerator (Note: + The Scope of an Enumerator is its type also for enumerations that are unscoped + enumeration types). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Expression.3 b/man/std::experimental::reflect::Expression.3 new file mode 100644 index 000000000..1fd720897 --- /dev/null +++ b/man/std::experimental::reflect::Expression.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Expression 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Expression \- std::experimental::reflect::Expression + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Expression = Object && /* see below */; + + The Expression concept is satisfied if and only if T reflects an expression. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Function.3 b/man/std::experimental::reflect::Function.3 new file mode 100644 index 000000000..0e2648352 --- /dev/null +++ b/man/std::experimental::reflect::Function.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Function \- std::experimental::reflect::Function + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Function = Callable && Typed && /* see below */; + + The Function concept is satisfied if and only if T reflects a function, excluding + constructors and destructors. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::FunctionCallExpression.3 b/man/std::experimental::reflect::FunctionCallExpression.3 new file mode 100644 index 000000000..3edacab68 --- /dev/null +++ b/man/std::experimental::reflect::FunctionCallExpression.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::FunctionCallExpression 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::FunctionCallExpression \- std::experimental::reflect::FunctionCallExpression + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept FunctionCallExpression = Expression && /* see below */; + + The FunctionCallExpression concept is satisfied if and only if T reflects a + function-call-expression. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::FunctionParameter.3 b/man/std::experimental::reflect::FunctionParameter.3 new file mode 100644 index 000000000..3490d7315 --- /dev/null +++ b/man/std::experimental::reflect::FunctionParameter.3 @@ -0,0 +1,26 @@ +.TH std::experimental::reflect::FunctionParameter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::FunctionParameter \- std::experimental::reflect::FunctionParameter + +.SH Synopsis + Defined in header + template< class T > + concept FunctionParameter = Typed && ScopeMember && /* see (reflection TS) + below */; + + The FunctionParameter concept is satisfied if and only if T reflects a function + parameter (Note: A FunctionParameter does not satisfy Variable, and thus does not + offer an interface for getting the pointer to a parameter). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::FunctionalTypeConversion.3 b/man/std::experimental::reflect::FunctionalTypeConversion.3 new file mode 100644 index 000000000..c84061111 --- /dev/null +++ b/man/std::experimental::reflect::FunctionalTypeConversion.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::FunctionalTypeConversion 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::FunctionalTypeConversion \- std::experimental::reflect::FunctionalTypeConversion + +.SH Synopsis + Defined in header + template< class T > + concept FunctionalTypeConversion = Expression && /* see below (reflection TS) + */; + + The FunctionalTypeConversion concept is satisfied if and only if T reflects a + functional-type-conv-expression. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::GlobalScope.3 b/man/std::experimental::reflect::GlobalScope.3 new file mode 100644 index 000000000..47fc14fa9 --- /dev/null +++ b/man/std::experimental::reflect::GlobalScope.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::GlobalScope 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::GlobalScope \- std::experimental::reflect::GlobalScope + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept GlobalScope = Namespace && /* see below */; + + The GlobalScope concept is satisfied if and only if T reflects the global namespace + (Note: Any such T does not satisfy ScopeMember). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Lambda.3 b/man/std::experimental::reflect::Lambda.3 new file mode 100644 index 000000000..eb9f80731 --- /dev/null +++ b/man/std::experimental::reflect::Lambda.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Lambda 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Lambda \- std::experimental::reflect::Lambda + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Lambda = Type && Scope && /* see below */; + + The Lambda concept is satisfied if and only if T reflects a closure object + (excluding generic lambdas). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::LambdaCapture.3 b/man/std::experimental::reflect::LambdaCapture.3 new file mode 100644 index 000000000..111ec07ac --- /dev/null +++ b/man/std::experimental::reflect::LambdaCapture.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::LambdaCapture 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::LambdaCapture \- std::experimental::reflect::LambdaCapture + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept LambdaCapture = Variable && /* see below */; + + The LambdaCapture concept is satisfied if and only if T reflects a lambda capture as + introduced by the capture list or by capture defaults. (Note: The Scope of a + LambdaCapture is its immediately enclosing Lambda). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::MemberFunction.3 b/man/std::experimental::reflect::MemberFunction.3 new file mode 100644 index 000000000..3c9f2e549 --- /dev/null +++ b/man/std::experimental::reflect::MemberFunction.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::MemberFunction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::MemberFunction \- std::experimental::reflect::MemberFunction + +.SH Synopsis + Defined in header + template< class T > + concept MemberFunction = RecordMember && Function && /* see (reflection TS) + below */; + + The MemberFunction concept is satisfied if and only if T reflects a member function, + excluding constructors and destructors. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Named.3 b/man/std::experimental::reflect::Named.3 new file mode 100644 index 000000000..470d99067 --- /dev/null +++ b/man/std::experimental::reflect::Named.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Named 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Named \- std::experimental::reflect::Named + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Named = Object && /* see below */; + + The Named concept is satisfied if and only if T has an associated (possibly empty) + name. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Namespace.3 b/man/std::experimental::reflect::Namespace.3 new file mode 100644 index 000000000..72b38ddc4 --- /dev/null +++ b/man/std::experimental::reflect::Namespace.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::Namespace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Namespace \- std::experimental::reflect::Namespace + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Namespace = Scope && /* see below */; + + The Namespace concept is satisfied if and only if T reflects a namespace including + the global namespace (Note: Any such T that does not reflect the global namespace + also satisfies ScopeMember). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Object.3 b/man/std::experimental::reflect::Object.3 new file mode 100644 index 000000000..ab2538fe8 --- /dev/null +++ b/man/std::experimental::reflect::Object.3 @@ -0,0 +1,42 @@ +.TH std::experimental::reflect::Object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Object \- std::experimental::reflect::Object + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Object = /* see below */; + + The Object concept is satisfied if and only if T is a meta-object type. + +.SH Example + + +// Run this code + + #include + + namespace reflect = std::experimental::reflect; + + template + struct meta_t { + template + friend constexpr bool operator==(meta_t, meta_t) noexcept + { + return reflect::reflects_same_v; + } + template + friend constexpr bool operator!=(meta_t, meta_t) noexcept + { + return !reflect::reflects_same_v; + } + }; + + template + constexpr meta_t meta{}; + + int main() + { + static_assert(meta == meta, ""); + // meta; // error: int is not a meta-object type + } diff --git a/man/std::experimental::reflect::ObjectSequence.3 b/man/std::experimental::reflect::ObjectSequence.3 new file mode 100644 index 000000000..39dd56038 --- /dev/null +++ b/man/std::experimental::reflect::ObjectSequence.3 @@ -0,0 +1,51 @@ +.TH std::experimental::reflect::ObjectSequence 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::ObjectSequence \- std::experimental::reflect::ObjectSequence + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept ObjectSequence = Object && /* see below */; + + The ObjectSequence concept is satisfied by meta-object sequence types. + + A meta-object sequence type is a meta-object type that is obtained from a + meta-object operation that generates a sequence, e.g. get_data_members. Each element + of a meta-object sequence type is a meta-object type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + namespace reflect = std::experimental::reflect; + + template + using tuple_from_seq_t = std::tuple>...>; + + template + using collect_tuple = reflect::unpack_sequence_t< + tuple_from_seq_t, + reflect::get_data_members_t>; + + int main() + { + static_assert(reflect::ObjectSequence< + reflect::get_data_members>, ""); + static_assert(std::is_same, + std::tuple>::value, ""); + } + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Operator.3 b/man/std::experimental::reflect::Operator.3 new file mode 100644 index 000000000..2778d097c --- /dev/null +++ b/man/std::experimental::reflect::Operator.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::Operator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Operator \- std::experimental::reflect::Operator + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Operator = Function && /* see below */; + + The Operator concept is satisfied if and only if T reflects an operator function or + a conversion function (Note: Some types that satisfy Operator also satisfy + MemberFunction or SpecialMemberFunction). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::ParenthesizedExpression.3 b/man/std::experimental::reflect::ParenthesizedExpression.3 new file mode 100644 index 000000000..6d9ecb45a --- /dev/null +++ b/man/std::experimental::reflect::ParenthesizedExpression.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::ParenthesizedExpression 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::ParenthesizedExpression \- std::experimental::reflect::ParenthesizedExpression + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept ParenthesizedExpression = Expression && /* see below */; + + The ParenthesizedExpression concept is satisfied if and only if T reflects a + parenthesized expression. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Record.3 b/man/std::experimental::reflect::Record.3 new file mode 100644 index 000000000..3cd569d10 --- /dev/null +++ b/man/std::experimental::reflect::Record.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Record 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Record \- std::experimental::reflect::Record + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Record = Type && Scope && /* see below */; + + The Record concept is satisfied if and only if T reflects a class type. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::RecordMember.3 b/man/std::experimental::reflect::RecordMember.3 new file mode 100644 index 000000000..67d9c2868 --- /dev/null +++ b/man/std::experimental::reflect::RecordMember.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::RecordMember 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::RecordMember \- std::experimental::reflect::RecordMember + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept RecordMember = ScopeMember && /* see below */; + + The RecordMember concept is satisfied if and only if T reflects a + member-declaration. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Scope.3 b/man/std::experimental::reflect::Scope.3 new file mode 100644 index 000000000..590a83e28 --- /dev/null +++ b/man/std::experimental::reflect::Scope.3 @@ -0,0 +1,25 @@ +.TH std::experimental::reflect::Scope 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Scope \- std::experimental::reflect::Scope + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Scope = Object && /* see below */; + + The Scope concept is satisfied if and only if T reflects a namespace (including the + global namespace), class, enumeration, function, or closure-type (Note: Any such T + that does not reflect the global namespace also satisfies ScopeMember). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::ScopeMember.3 b/man/std::experimental::reflect::ScopeMember.3 new file mode 100644 index 000000000..a5ebc35a0 --- /dev/null +++ b/man/std::experimental::reflect::ScopeMember.3 @@ -0,0 +1,26 @@ +.TH std::experimental::reflect::ScopeMember 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::ScopeMember \- std::experimental::reflect::ScopeMember + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept ScopeMember = Named && /* see below */; + + The ScopeMember concept is satisfied if and only if T satisfies RecordMember, + Enumerator, or Variable, or if T reflects a namespace that is not the global + namespace (Note: The scope of members of an unnamed union is the unnamed union; the + scope of enumerators is their type). + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::SpecialMemberFunction.3 b/man/std::experimental::reflect::SpecialMemberFunction.3 new file mode 100644 index 000000000..daf04edec --- /dev/null +++ b/man/std::experimental::reflect::SpecialMemberFunction.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::SpecialMemberFunction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::SpecialMemberFunction \- std::experimental::reflect::SpecialMemberFunction + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept SpecialMemberFunction = RecordMember && /* see below */; + + The SpecialMemberFunction concept is satisfied if and only if T reflects a special + member function. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Type.3 b/man/std::experimental::reflect::Type.3 new file mode 100644 index 000000000..f931ef0a4 --- /dev/null +++ b/man/std::experimental::reflect::Type.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Type \- std::experimental::reflect::Type + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Type = Named && ScopeMember && /* see below */; + + The Type concept is satisfied if and only if T reflects a type. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Typed.3 b/man/std::experimental::reflect::Typed.3 new file mode 100644 index 000000000..b378296c2 --- /dev/null +++ b/man/std::experimental::reflect::Typed.3 @@ -0,0 +1,23 @@ +.TH std::experimental::reflect::Typed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Typed \- std::experimental::reflect::Typed + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Typed = Named && /* see below */; + + The Typed concept is satisfied if and only if T reflects an entity with a type. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::Variable.3 b/man/std::experimental::reflect::Variable.3 new file mode 100644 index 000000000..2fd7e63a6 --- /dev/null +++ b/man/std::experimental::reflect::Variable.3 @@ -0,0 +1,24 @@ +.TH std::experimental::reflect::Variable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::Variable \- std::experimental::reflect::Variable + +.SH Synopsis + Defined in header + template< class T > (reflection TS) + concept Variable = Typed && /* see below */; + + The Variable concept is satisfied if and only if T reflects a variable or data + member. + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + This section is incomplete + Reason: templatization + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::get_source_column.3 b/man/std::experimental::reflect::get_source_column.3 new file mode 100644 index 000000000..682e5864f --- /dev/null +++ b/man/std::experimental::reflect::get_source_column.3 @@ -0,0 +1,45 @@ +.TH std::experimental::reflect::get_source_column 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::get_source_column \- std::experimental::reflect::get_source_column + +.SH Synopsis + Defined in header + template< Object T > (reflection TS) + struct get_source_column; + + Provides the member constant value equal to the implementation-defined value + representing some offset from the start of the line of the declaration of the entity + or typedef-name reflected by T. + +.SH Member constants + + value the implementation-defined value representing some offset from the start of + \fB[static]\fP the line of the declaration of the entity or typedef-name reflected by T + \fI(public static member constant)\fP + +.SH Member functions + + converts the object to std::uint_least32_t, returns + operator std::uint_least32_t value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type std::uint_least32_t + type std::integral_constant + +.SH Example + + This section is incomplete + Reason: examples + +.SH See also + + column return the column number represented by this object + \fI(public member function of std::source_location)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::experimental::reflect::get_source_line.3 b/man/std::experimental::reflect::get_source_line.3 new file mode 100644 index 000000000..544022cb6 --- /dev/null +++ b/man/std::experimental::reflect::get_source_line.3 @@ -0,0 +1,65 @@ +.TH std::experimental::reflect::get_source_line 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reflect::get_source_line \- std::experimental::reflect::get_source_line + +.SH Synopsis + Defined in header + template< Object T > (reflection TS) + struct get_source_line; + + Provides the member constant value equal to the presumed line number of the + declaration of the entity or typedef-name reflected by T. + +.SH Member constants + + value the presumed line number of the declaration of the entity or typedef-name + \fB[static]\fP reflected by T + \fI(public static member constant)\fP + +.SH Member functions + + converts the object to std::uint_least32_t, returns + operator std::uint_least32_t value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type std::uint_least32_t + type std::integral_constant + +.SH Example + + The following code shows the source code line of an object or a class. + + +// Run this code + + #include + #include + + using refl = std::experimental::reflect; + + float f; + struct P{}; + + int main() + { + std::cout << refl::get_source_line_v << '\\n'; + std::cout << refl::get_source_line_v << '\\n'; + } + +.SH Output: + + 6 + 7 + +.SH See also + + line return the line number represented by this object + \fI(public member function of std::source_location)\fP + source_line gets the line number that lexically relates the evaluation represented + (C++23) by the stacktrace_entry + \fI(public member function of std::stacktrace_entry)\fP diff --git a/man/std::experimental::reseed.3 b/man/std::experimental::reseed.3 new file mode 100644 index 000000000..ab78089cb --- /dev/null +++ b/man/std::experimental::reseed.3 @@ -0,0 +1,53 @@ +.TH std::experimental::reseed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::reseed \- std::experimental::reseed + +.SH Synopsis + Defined in header + void reseed(); \fB(1)\fP (library fundamentals + TS v2) + void reseed( std::default_random_engine::result_type value \fB(2)\fP (library fundamentals + ); TS v2) + + Reseeds the per-thread random number engine and any std::uniform_int_distribution + instances used by randint. + + 1) Sets the per-thread engine to an unpredictable state. + 2) Seeds the per-thread engine g as if by g.seed(value). + +.SH Parameters + + value - value of the new seed + + Remarks + + Subsequent calls to randint do not depend on values produced by the per-thread + engine prior to calling reseed. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::experimental::reseed(); + + std::cout << "Random 2-digit decimal numbers: "; + + for (auto i = 0; i != 3; ++i) + std::cout << std::experimental::randint(10, 99) << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + Random 2-digit decimal numbers: 41 60 56 + +.SH See also + + randint generates a random integer in the specified range + \fI(function template)\fP diff --git a/man/std::experimental::sample.3 b/man/std::experimental::sample.3 new file mode 100644 index 000000000..5a0fb84b2 --- /dev/null +++ b/man/std::experimental::sample.3 @@ -0,0 +1,107 @@ +.TH std::experimental::sample 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::sample \- std::experimental::sample + +.SH Synopsis + Defined in header + template< class PopulationIterator, class + SampleIterator, + + class Distance, class URBG > + SampleIterator sample( PopulationIterator first, \fB(1)\fP (library fundamentals TS) + PopulationIterator last, + SampleIterator out, Distance + n, + + URBG&& g ); + template< class PopulationIterator, class + SampleIterator, class Distance > + + SampleIterator sample( PopulationIterator first, \fB(2)\fP (library fundamentals TS + PopulationIterator last, v2) + + SampleIterator out, Distance n + ); + + Selects n elements from the sequence [first, last) such that each possible sample + has equal probability of appearance, and writes those selected elements into the + output iterator out. + + If n is greater than the number of elements in the sequence, selects last - first + elements. + + The algorithm is stable only if PopulationIterator meets the requirements of + LegacyForwardIterator. + + 1) Random numbers are generated using the random number generator g. + 2) Random numbers are generated using the per-thread engine. + +.SH Parameters + + first, last - pair of iterators forming the range from which to make + the sampling (the population) + out - the output iterator where the samples are written. Must + not be in the range [first, last) + n - number of samples to make + g - the random number generator used as the source of + randomness + - + PopulationIterator must meet the requirements of LegacyInputIterator. + - + SampleIterator must meet the requirements of LegacyOutputIterator. + - + SampleIterator must also meet the requirements of LegacyRandomAccessIterator if + PopulationIterator doesn't meet LegacyForwardIterator. + - + PopulationIterator's value type must be writeable to out. + - + Distance must be an integer type. + - + URBG must meet the requirements of UniformRandomBitGenerator and its return type + must be convertible to Distance. + +.SH Return value + + Returns a copy of out after the last sample that was output, that is, end of the + sample range. + +.SH Complexity + + Linear in std::distance(first, last). + +.SH Notes + + This function may implement selection sampling or reservoir sampling. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string in = "abcdefgh", out; + std::experimental::sample(in.begin(), in.end(), std::back_inserter(out), + 5, std::mt19937{std::random_device{}()}); + std::cout << "five random letters out of " << in << " : " << out << '\\n'; + } + +.SH Possible output: + + five random letters out of abcdefgh : cdefg + +.SH See also + + random_shuffle + shuffle randomly re-orders elements in a range + \fI(until C++17)\fP \fI(function template)\fP + \fI(C++11)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::scope_exit.3 b/man/std::experimental::scope_exit.3 new file mode 100644 index 000000000..62d43a0a6 --- /dev/null +++ b/man/std::experimental::scope_exit.3 @@ -0,0 +1,83 @@ +.TH std::experimental::scope_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_exit \- std::experimental::scope_exit + +.SH Synopsis + Defined in header + template< class EF > (library fundamentals TS v3) + class scope_exit; + + The class template scope_exit is a general-purpose scope guard intended to call its + exit function when a scope is exited. + + scope_exit is not CopyConstructible, CopyAssignable or MoveAssignable, however, it + may be MoveConstructible if EF meets some requirements, which permits wrapping a + scope_exit into another object. + + A scope_exit may be either active, i.e. calls its exit function on destruction, or + inactive, i.e. does nothing on destruction. A scope_exit is active after constructed + from an exit function. + + A scope_exit can become inactive by calling release() on it either manually or + automatically (by the move constructor). An inactive scope_exit may also be obtained + by initializing with another inactive scope_exit. Once a scope_exit is inactive, it + cannot become active again. + + A scope_exit effectively holds an EF and a bool flag indicating if it is active. + +.SH Template parameters + + EF - type of stored exit function +.SH Type requirements + - + EF shall be either: + * a Destructible FunctionObject type, + * an lvalue reference to FunctionObject, + * an lvalue reference to function. + - + Calling an lvalue of std::remove_reference_t with no argument shall be + well-formed. + +.SH Member functions + + constructor constructs a new scope_exit + \fI(public member function)\fP + calls the exit function when the scope is exited if the scope_exit is + destructor active, then destroys the scope_exit + \fI(public member function)\fP + operator= scope_exit is not assignable + [deleted] \fI(public member function)\fP +.SH Modifiers + release makes the scope_exit inactive + \fI(public member function)\fP + + Deduction guides + +.SH Notes + + Constructing a scope_exit of dynamic storage duration might lead to unexpected + behavior. + + If the EF stored in a scope_exit object refers to a local variable of the function + where it is defined, e.g., as a lambda capturing the variable by reference, and that + variable is used as a return operand in that function, that variable might have + already been returned when the scope_exit's destructor executes, calling the exit + function. This can lead to surprising behavior. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + wraps a function object and invokes it on exiting the scope through + scope_fail an exception + \fI(class template)\fP + scope_success wraps a function object and invokes it on exiting the scope normally + \fI(class template)\fP + default_delete default deleter for unique_ptr + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::scope_exit::release.3 b/man/std::experimental::scope_exit::release.3 new file mode 100644 index 000000000..a6c70fe6c --- /dev/null +++ b/man/std::experimental::scope_exit::release.3 @@ -0,0 +1,40 @@ +.TH std::experimental::scope_exit::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_exit::release \- std::experimental::scope_exit::release + +.SH Synopsis + void release() noexcept; (library fundamentals TS v3) + + Makes the scope_exit inactive. + + Once a scope_exit is inactive, it cannot become active again, and will not call its + exit function on destruction. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + release may be either manually called or automatically called by scope_exit's move + constructor. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new scope_exit + \fI(public member function)\fP + calls the exit function when the scope is exited if the scope_exit is + destructor active, then destroys the scope_exit + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::scope_exit::scope_exit.3 b/man/std::experimental::scope_exit::scope_exit.3 new file mode 100644 index 000000000..9e511791c --- /dev/null +++ b/man/std::experimental::scope_exit::scope_exit.3 @@ -0,0 +1,75 @@ +.TH std::experimental::scope_exit::scope_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_exit::scope_exit \- std::experimental::scope_exit::scope_exit + +.SH Synopsis + template< class Fn > + explicit scope_exit( Fn&& fn ) noexcept(/*see \fB(1)\fP (library fundamentals TS v3) + below*/); + scope_exit( scope_exit&& other ) noexcept(/*see \fB(2)\fP (library fundamentals TS v3) + below*/); + scope_exit( const scope_exit& ) = delete; \fB(3)\fP (library fundamentals TS v3) + + Creates a scope_exit from a function, a function object or another scope_exit. + + 1) Initializes the exit function with a function or function object. The constructed + scope_exit is active. + If Fn is not an lvalue reference type and std::is_nothrow_constructible_v is + true, the stored EF is initialized with std::forward(fn); otherwise it is + initialized with fn. + If initialization of the stored EF throws an exception, calls fn(). + This overload participates in overload resolution only if + std::is_same_v, scope_exit> is false and + std::is_constructible_v is true. + The program is ill-formed if function call expression fn() is ill-formed. + The behavior is undefined if calling fn() throws an exception or results in + undefined behavior, even if fn has not been called. + 2) Move constructor. Initializes the stored EF with the one in other. The + constructed scope_exit is active if and only if other is active before the + construction. + If std::is_nothrow_move_constructible_v is true, initializes stored EF (denoted + by exitfun) with std::forward(other.exitfun), otherwise initializes it with + other.exitfun. + After successful move construction, other.release() is called and other becomes + inactive. + This overload participates in overload resolution only if + std::is_nothrow_move_constructible_v is true or std::is_copy_constructible_v + is true. + The behavior is undefined if + * std::is_nothrow_move_constructible_v is true and EF does not meet the + requirements of MoveConstructible, or + * std::is_nothrow_move_constructible_v is false and EF does not meet the + requirements of CopyConstructible. + 3) scope_exit is not CopyConstructible. + +.SH Parameters + + fn - function or function object used for initializing the stored EF + other - scope_exit to move from + +.SH Exceptions + + Any exception thrown during the initialization of the stored EF. + + 1) + noexcept specification: + noexcept(std::is_nothrow_constructible_v || + std::is_nothrow_constructible_v) + 2) + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v || + std::is_nothrow_copy_constructible_v) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + release makes the scope_exit inactive + \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::scope_exit::~scope_exit.3 b/man/std::experimental::scope_exit::~scope_exit.3 new file mode 100644 index 000000000..6cf763778 --- /dev/null +++ b/man/std::experimental::scope_exit::~scope_exit.3 @@ -0,0 +1,14 @@ +.TH std::experimental::scope_exit::~scope_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_exit::~scope_exit \- std::experimental::scope_exit::~scope_exit + +.SH Synopsis + ~scope_exit() noexcept; (library fundamentals TS v3) + + Calls the exit function if the scope_exit is active, then destroys the stored EF (if + it is a function object) and any other non-static data members. + +.SH See also + + release makes the scope_exit inactive + \fI(public member function)\fP diff --git a/man/std::experimental::scope_fail.3 b/man/std::experimental::scope_fail.3 new file mode 100644 index 000000000..0e66cdb67 --- /dev/null +++ b/man/std::experimental::scope_fail.3 @@ -0,0 +1,82 @@ +.TH std::experimental::scope_fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_fail \- std::experimental::scope_fail + +.SH Synopsis + Defined in header + template< class EF > (library fundamentals TS v3) + class scope_fail; + + The class template scope_fail is a general-purpose scope guard intended to call its + exit function when a scope is exited via an exception. + + scope_fail is not CopyConstructible, CopyAssignable or MoveAssignable, however, it + may be MoveConstructible if EF meets some requirements, which permits wrapping a + scope_fail into another object. + + A scope_fail may be either active, i.e. calls its exit function on destruction, or + inactive, i.e. does nothing on destruction. A scope_fail is active after constructed + from an exit function. + + A scope_fail can become inactive by calling release() on it either manually or + automatically (by the move constructor). An inactive scope_fail may also be obtained + by initializing with another inactive scope_fail. Once a scope_fail is inactive, it + cannot become active again. + + A scope_fail effectively holds an EF and a bool flag indicating if it is active, + alongwith a counter of uncaught exceptions used for detecting whether the destructor + is called during stack unwinding. + +.SH Template parameters + + EF - type of stored exit function +.SH Type requirements + - + EF shall be either: + * a Destructible FunctionObject type, + * an lvalue reference to FunctionObject, + * an lvalue reference to function. + - + Calling an lvalue of std::remove_reference_t with no argument shall be + well-formed. + +.SH Member functions + + constructor constructs a new scope_fail + \fI(public member function)\fP + calls the exit function when the scope is exited via an exception if + destructor the scope_fail is active, then destroys the scope_fail + \fI(public member function)\fP + operator= scope_fail is not assignable + [deleted] \fI(public member function)\fP +.SH Modifiers + release makes the scope_fail inactive + \fI(public member function)\fP + + Deduction guides + +.SH Notes + + Constructing a scope_fail of dynamic storage duration might lead to unexpected + behavior. + + Constructing a scope_fail is constructed from another scope_fail created in a + different thread might also lead to unexpected behavior since the count of uncaught + exceptions obtained in different threads may be compared during the destruction. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + scope_exit wraps a function object and invokes it on exiting the scope + \fI(class template)\fP + scope_success wraps a function object and invokes it on exiting the scope normally + \fI(class template)\fP + default_delete default deleter for unique_ptr + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::scope_fail::release.3 b/man/std::experimental::scope_fail::release.3 new file mode 100644 index 000000000..ae4c8b92c --- /dev/null +++ b/man/std::experimental::scope_fail::release.3 @@ -0,0 +1,40 @@ +.TH std::experimental::scope_fail::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_fail::release \- std::experimental::scope_fail::release + +.SH Synopsis + void release() noexcept; (library fundamentals TS v3) + + Makes the scope_fail inactive. + + Once a scope_fail is inactive, it cannot become active again, and will not call its + exit function on destruction. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + release may be either manually called or automatically called by scope_fail's move + constructor. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new scope_fail + \fI(public member function)\fP + calls the exit function when the scope is exited via an exception if + destructor the scope_fail is active, then destroys the scope_fail + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::scope_fail::scope_fail.3 b/man/std::experimental::scope_fail::scope_fail.3 new file mode 100644 index 000000000..d64370aec --- /dev/null +++ b/man/std::experimental::scope_fail::scope_fail.3 @@ -0,0 +1,81 @@ +.TH std::experimental::scope_fail::scope_fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_fail::scope_fail \- std::experimental::scope_fail::scope_fail + +.SH Synopsis + template< class Fn > + explicit scope_fail( Fn&& fn ) noexcept(/*see \fB(1)\fP (library fundamentals TS v3) + below*/); + scope_fail( scope_fail&& other ) noexcept(/*see \fB(2)\fP (library fundamentals TS v3) + below*/); + scope_fail( const scope_fail& ) = delete; \fB(3)\fP (library fundamentals TS v3) + + Creates a scope_fail from a function, a function object or another scope_fail. + + 1) Initializes the exit function with a function or function object, and initializes + the counter of uncaught exceptions as if with std::uncaught_exceptions(). The + constructed scope_fail is active. + If Fn is not an lvalue reference type and std::is_nothrow_constructible_v is + true, the stored EF is initialized with std::forward(fn); otherwise it is + initialized with fn. + If initialization of the stored EF throws an exception, calls fn(). + This overload participates in overload resolution only if + std::is_same_v, scope_fail> is false and + std::is_constructible_v is true. + The program is ill-formed if function call expression fn() is ill-formed. + The behavior is undefined if calling fn() throws an exception or results in + undefined behavior, even if fn has not been called. + 2) Move constructor. Initializes the stored EF with the one in other, and + initializes the counter of uncaught exceptions with the one in other. The + constructed scope_fail is active if and only if other is active before the + construction. + If std::is_nothrow_move_constructible_v is true, initializes stored EF (denoted + by exitfun) with std::forward(other.exitfun), otherwise initializes it with + other.exitfun. + After successful move construction, other.release() is called and other becomes + inactive. + This overload participates in overload resolution only if + std::is_nothrow_move_constructible_v is true or std::is_copy_constructible_v + is true. + The behavior is undefined if + * std::is_nothrow_move_constructible_v is true and EF does not meet the + requirements of MoveConstructible, or + * std::is_nothrow_move_constructible_v is false and EF does not meet the + requirements of CopyConstructible. + 3) scope_fail is not CopyConstructible. + +.SH Parameters + + fn - function or function object used for initializing the stored EF + other - scope_fail to move from + +.SH Exceptions + + Any exception thrown during the initialization of the stored EF. + + 1) + noexcept specification: + noexcept(std::is_nothrow_constructible_v || + std::is_nothrow_constructible_v) + 2) + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v || + std::is_nothrow_copy_constructible_v) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + uncaught_exception + uncaught_exceptions checks if exception handling is currently in progress + (removed in C++20) \fI(function)\fP + \fI(C++17)\fP + release makes the scope_fail inactive + \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::scope_fail::~scope_fail.3 b/man/std::experimental::scope_fail::~scope_fail.3 new file mode 100644 index 000000000..b843a3174 --- /dev/null +++ b/man/std::experimental::scope_fail::~scope_fail.3 @@ -0,0 +1,22 @@ +.TH std::experimental::scope_fail::~scope_fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_fail::~scope_fail \- std::experimental::scope_fail::~scope_fail + +.SH Synopsis + ~scope_fail() noexcept; (library fundamentals TS v3) + + Calls the exit function if the result of std::uncaught_exceptions() is greater than + the counter of uncaught exceptions (typically on stack unwinding) and the scope_fail + is active, then destroys the stored EF (if it is a function object) and any other + non-static data members. + +.SH Notes + + Whether the destructor is called on stack unwinding can be detected by the + comparison of the result of std::uncaught_exceptions() and the counter of uncaught + exceptions in the scope_fail. + +.SH See also + + release makes the scope_fail inactive + \fI(public member function)\fP diff --git a/man/std::experimental::scope_success.3 b/man/std::experimental::scope_success.3 new file mode 100644 index 000000000..e4c26818e --- /dev/null +++ b/man/std::experimental::scope_success.3 @@ -0,0 +1,89 @@ +.TH std::experimental::scope_success 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_success \- std::experimental::scope_success + +.SH Synopsis + Defined in header + template< class EF > (library fundamentals TS v3) + class scope_success; + + The class template scope_success is a general-purpose scope guard intended to call + its exit function when a scope is normally exited. + + scope_success is not CopyConstructible, CopyAssignable or MoveAssignable, however, + it may be MoveConstructible if EF meets some requirements, which permits wrapping a + scope_success into another object. + + A scope_success may be either active, i.e. calls its exit function on destruction, + or inactive, i.e. does nothing on destruction. A scope_success is active after + constructed from an exit function. + + A scope_success can become inactive by calling release() on it either manually or + automatically (by the move constructor). An inactive scope_success may also be + obtained by initializing with another inactive scope_success. Once a scope_success + is inactive, it cannot become active again. + + A scope_success effectively holds an EF and a bool flag indicating if it is active, + alongwith a counter of uncaught exceptions used for detecting whether the destructor + is called during stack unwinding. + +.SH Template parameters + + EF - type of stored exit function +.SH Type requirements + - + EF shall be either: + * a Destructible FunctionObject type, + * an lvalue reference to FunctionObject, + * an lvalue reference to function. + - + Calling an lvalue of std::remove_reference_t with no argument shall be + well-formed. + +.SH Member functions + + constructor constructs a new scope_success + \fI(public member function)\fP + calls the exit function when the scope is exited normally if the + destructor scope_success is active, then destroys the scope_success + \fI(public member function)\fP + operator= scope_success is not assignable + [deleted] \fI(public member function)\fP +.SH Modifiers + release makes the scope_success inactive + \fI(public member function)\fP + + Deduction guides + +.SH Notes + + Constructing a scope_success of dynamic storage duration might lead to unexpected + behavior. + + Constructing a scope_success is constructed from another scope_success created in a + different thread might also lead to unexpected behavior since the count of uncaught + exceptions obtained in different threads may be compared during the destruction. + + If the EF stored in a scope_success object refers to a local variable of the + function where it is defined, e.g., as a lambda capturing the variable by reference, + and that variable is used as a return operand in that function, that variable might + have already been returned when the scope_success's destructor executes, calling the + exit function. This can lead to surprising behavior. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + scope_exit wraps a function object and invokes it on exiting the scope + \fI(class template)\fP + wraps a function object and invokes it on exiting the scope through + scope_fail an exception + \fI(class template)\fP + default_delete default deleter for unique_ptr + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::scope_success::release.3 b/man/std::experimental::scope_success::release.3 new file mode 100644 index 000000000..123331cbc --- /dev/null +++ b/man/std::experimental::scope_success::release.3 @@ -0,0 +1,40 @@ +.TH std::experimental::scope_success::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_success::release \- std::experimental::scope_success::release + +.SH Synopsis + void release() noexcept; (library fundamentals TS v3) + + Makes the scope_success inactive. + + Once a scope_success is inactive, it cannot become active again, and will not call + its exit function on destruction. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + release may be either manually called or automatically called by scope_success's + move constructor. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new scope_success + \fI(public member function)\fP + calls the exit function when the scope is exited normally if the + destructor scope_success is active, then destroys the scope_success + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::scope_success::scope_success.3 b/man/std::experimental::scope_success::scope_success.3 new file mode 100644 index 000000000..d8e90a457 --- /dev/null +++ b/man/std::experimental::scope_success::scope_success.3 @@ -0,0 +1,80 @@ +.TH std::experimental::scope_success::scope_success 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_success::scope_success \- std::experimental::scope_success::scope_success + +.SH Synopsis + template< class Fn > + explicit scope_success( Fn&& fn ) noexcept(/*see \fB(1)\fP (library fundamentals TS v3) + below*/); + scope_success( scope_success&& other ) \fB(2)\fP (library fundamentals TS v3) + noexcept(/*see below*/); + scope_success( const scope_success& ) = delete; \fB(3)\fP (library fundamentals TS v3) + + Creates a scope_success from a function, a function object or another scope_success. + + 1) Initializes the exit function with a function or function object, and initializes + the counter of uncaught exceptions as if with std::uncaught_exceptions(). The + constructed scope_success is active. + If Fn is not an lvalue reference type and std::is_nothrow_constructible_v is + true, the stored EF is initialized with std::forward(fn); otherwise it is + initialized with fn. + This overload participates in overload resolution only if + std::is_same_v, scope_success> is false and + std::is_constructible_v is true. + The program is ill-formed if function call expression fn() is ill-formed. + The behavior is undefined if calling fn() results in undefined behavior, even if fn + has not been called. + 2) Move constructor. Initializes the stored EF with the one in other, and + initializes the counter of uncaught exceptions with the one in other. The + constructed scope_success is active if and only if other is active before the + construction. + If std::is_nothrow_move_constructible_v is true, initializes stored EF (denoted + by exitfun) with std::forward(other.exitfun), otherwise initializes it with + other.exitfun. + After successful move construction, other.release() is called and other becomes + inactive. + This overload participates in overload resolution only if + std::is_nothrow_move_constructible_v is true or std::is_copy_constructible_v + is true. + The behavior is undefined if + * std::is_nothrow_move_constructible_v is true and EF does not meet the + requirements of MoveConstructible, or + * std::is_nothrow_move_constructible_v is false and EF does not meet the + requirements of CopyConstructible. + 3) scope_success is not CopyConstructible. + +.SH Parameters + + fn - function or function object used for initializing the stored EF + other - scope_success to move from + +.SH Exceptions + + Any exception thrown during the initialization of the stored EF. + + 1) + noexcept specification: + noexcept(std::is_nothrow_constructible_v || + std::is_nothrow_constructible_v) + 2) + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v || + std::is_nothrow_copy_constructible_v) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + uncaught_exception + uncaught_exceptions checks if exception handling is currently in progress + (removed in C++20) \fI(function)\fP + \fI(C++17)\fP + release makes the scope_success inactive + \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::scope_success::~scope_success.3 b/man/std::experimental::scope_success::~scope_success.3 new file mode 100644 index 000000000..fa051b037 --- /dev/null +++ b/man/std::experimental::scope_success::~scope_success.3 @@ -0,0 +1,31 @@ +.TH std::experimental::scope_success::~scope_success 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::scope_success::~scope_success \- std::experimental::scope_success::~scope_success + +.SH Synopsis + ~scope_success() noexcept(noexcept(std::declval()())); (library fundamentals + TS v3) + + Calls the exit function if the result of std::uncaught_exceptions() is less than or + equal to the counter of uncaught exceptions (typically on normal exit) and the + scope_success is active, then destroys the stored EF (if it is a function object) + and any other non-static data members. + +.SH Exceptions + + Throws any exception thrown by calling the exit function. + +.SH Notes + + Whether the destructor is called on stack unwinding can be detected by the + comparison of the result of std::uncaught_exceptions() and the counter of uncaught + exceptions in the scope_success. + + Unlike other classes or class template specializations in the C++ standard library + and other C++ TR/TS's, scope_success's destructor is permitted to throw an + exception. + +.SH See also + + release makes the scope_success inactive + \fI(public member function)\fP diff --git a/man/std::experimental::search.3 b/man/std::experimental::search.3 new file mode 100644 index 000000000..131a4c5ef --- /dev/null +++ b/man/std::experimental::search.3 @@ -0,0 +1,80 @@ +.TH std::experimental::search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::search \- std::experimental::search + +.SH Synopsis + Defined in header + template< class ForwardIterator, class Searcher > + + ForwardIterator search( ForwardIterator first, (library fundamentals TS) + ForwardIterator last, + + const Searcher& searcher ); + + Searches the sequence [first, last) for the pattern specified in the constructor of + searcher. + + Effectively executes searcher(first, last). \fI(until C++17)\fP + Effectively executes searcher(first, last).first. \fI(since C++17)\fP + + Searcher need not be CopyConstructible. + + The standard library provides the following searchers: + + default_searcher standard C++ library search algorithm implementation + \fI(class template)\fP + boyer_moore_searcher Boyer-Moore search algorithm implementation + \fI(class template)\fP + boyer_moore_horspool_searcher Boyer-Moore-Horspool search algorithm implementation + \fI(class template)\fP + +.SH Parameters + + This section is incomplete + +.SH Return value + + Returns the result of searcher.operator(), that is, an iterator to the location at + which the substring is found or a copy of last if it was not found. + +.SH Complexity + + Depends on the searcher. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string in = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed " + "do eiusmod tempor incididunt ut labore et dolore magna aliqua"; + std::string needle = "pisci"; + auto it = std::experimental::search(in.begin(), in.end(), + std::experimental::make_boyer_moore_searcher( + needle.begin(), needle.end())); + if (it != in.end()) + std::cout << "The string " << needle << " found at offset " + << it - in.begin() << '\\n'; + else + std::cout << "The string " << needle << " not found\\n"; + } + +.SH Output: + + The string pisci found at offset 43 + +.SH See also + + search searches for a range of elements + \fI(function template)\fP + +.SH Categories: + * Noindexed pages + * Todo without reason diff --git a/man/std::experimental::shared_future.3 b/man/std::experimental::shared_future.3 new file mode 100644 index 000000000..3cc4cc697 --- /dev/null +++ b/man/std::experimental::shared_future.3 @@ -0,0 +1,66 @@ +.TH std::experimental::shared_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_future \- std::experimental::shared_future + +.SH Synopsis + Defined in header + template< class T > class shared_future; \fB(1)\fP (concurrency TS) + template< class T > class shared_future; \fB(2)\fP (concurrency TS) + template<> class shared_future; \fB(3)\fP (concurrency TS) + + The class template std::experimental::shared_future extends std::shared_future with + the following operations: + + * an unwrapping constructor from future>; + * a member function is_ready to query whether the associated shared state is + ready; and + * a member function then to attach a continuation to the future. + + There is no interoperation between std::experimental::shared_future and + std::shared_future. + +.SH Member functions + + constructor constructs a shared_future + \fI(public member function)\fP + is_ready checks if the shared state is ready + \fI(public member function)\fP + then attaches a continuation to a shared_future + \fI(public member function)\fP + operator= assigns the contents + \fI(public member function)\fP + +Members identical to std::shared_future + +.SH Member functions + + destructor destructs the future object + \fI(public member function of std::shared_future)\fP +.SH Getting the result + get returns the result + \fI(public member function of std::shared_future)\fP +.SH State + valid checks if the future has a shared state + \fI(public member function of std::shared_future)\fP + wait waits for the result to become available + \fI(public member function of std::shared_future)\fP + waits for the result, returns if it is not available for the specified + wait_for timeout duration + \fI(public member function of std::shared_future)\fP + waits for the result, returns if it is not available until specified + wait_until time point has been reached + \fI(public member function of std::shared_future)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + future a version of std::future enhanced with continuations and other + (concurrency TS) features + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::shared_future::is_ready.3 b/man/std::experimental::shared_future::is_ready.3 new file mode 100644 index 000000000..afab65ec9 --- /dev/null +++ b/man/std::experimental::shared_future::is_ready.3 @@ -0,0 +1,31 @@ +.TH std::experimental::shared_future::is_ready 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_future::is_ready \- std::experimental::shared_future::is_ready + +.SH Synopsis + bool is_ready() const; + + Checks if the associated shared state is ready. + + The behavior is undefined if valid() is false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the associated shared state is ready, otherwise false. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + valid checks if the future has a shared state + \fI(public member function of std::shared_future)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::shared_future::operator=.3 b/man/std::experimental::shared_future::operator=.3 new file mode 100644 index 000000000..0bdba3ba1 --- /dev/null +++ b/man/std::experimental::shared_future::operator=.3 @@ -0,0 +1,25 @@ +.TH std::experimental::shared_future::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_future::operator= \- std::experimental::shared_future::operator= + +.SH Synopsis + std::experimental::shared_future& operator=( const \fB(1)\fP + std::experimental::shared_future& other ); + std::experimental::shared_future& operator=( \fB(2)\fP + std::experimental::shared_future&& other ) noexcept; + + Assigns the contents of another std::experimental::shared_future object. + + 1) Releases any shared state and assigns the contents of other to *this. After the + assignment, this->valid() == other.valid(). + 2) Releases any shared state and move-assigns the contents of other to *this. After + the assignment, other.valid() == false and this->valid() will yield the same value + as other.valid() before the assignment. + +.SH Parameters + + other - a std::experimental::shared_future object to assign from + +.SH Return value + + *this diff --git a/man/std::experimental::shared_future::shared_future.3 b/man/std::experimental::shared_future::shared_future.3 new file mode 100644 index 000000000..52eca5ffd --- /dev/null +++ b/man/std::experimental::shared_future::shared_future.3 @@ -0,0 +1,57 @@ +.TH std::experimental::shared_future::shared_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_future::shared_future \- std::experimental::shared_future::shared_future + +.SH Synopsis + shared_future() noexcept; \fB(1)\fP + shared_future( std::experimental::shared_future&& f ) noexcept; \fB(2)\fP + shared_future( const std::experimental::shared_future& f ); \fB(3)\fP + shared_future( std::experimental::future> \fB(4)\fP + && other ) noexcept; + shared_future( std::experimental::future&& f ) noexcept; \fB(5)\fP + + 1) Default constructor. Constructs an empty shared_future object that does not refer + to a shared state. + 2) Constructs a shared_future object, transferring the shared state held by f, if + any. After construction, f.valid() is false. + 3) Constructs a shared future that refers to the same shared state as f, if any. + 4) Unwrapping constructor. Constructs a shared_future object from the shared state + referred to by other, if any. If other.valid() == false prior to this call, the + constructed shared_future object is empty. Otherwise, the resulting shared_future + object becomes ready when one of the following happens: + * other and other.get() are both ready. The value or exception from other.get() is + stored in the shared state associated with the resulting shared_future object. + * other is ready, but other.get() is invalid. An exception of type + std::future_error with an error condition of std::future_errc::broken_promise is + stored in the shared state associated with the resulting shared_future object. + After this constructor returns, valid() is equal to the value of other.valid() prior + to this call, and other.valid() == false. + 5) Constructs a shared_future object, transferring the shared state held by f, if + any. After construction, f.valid() is false. + +.SH Parameters + + f - another future object to initialize with + other - a std::experimental::future object to unwrap + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2697 Concurrency TS behavior of unwrapping constructor is constructs an empty + unclear with an invalid future future + +.SH See also + + constructor constructs the future object + \fI(public member function of std::shared_future)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::shared_future::then.3 b/man/std::experimental::shared_future::then.3 new file mode 100644 index 000000000..e4a0b461a --- /dev/null +++ b/man/std::experimental::shared_future::then.3 @@ -0,0 +1,59 @@ +.TH std::experimental::shared_future::then 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_future::then \- std::experimental::shared_future::then + +.SH Synopsis + template< class F > + future then( F&& func ) const; + + Attach the continuation func to *this. The behavior is undefined if *this has no + associated shared state (i.e., valid() == false). + + Creates a shared state associated with the future object to be returned, and a copy + fd of func constructed as if by DECAY_COPY(std::forward(func)) evaluated in the + thread calling then, where DECAY_COPY is defined as + + template + std::decay_t DECAY_COPY(T&& v) + { + return std::forward(v); + } + + When the shared state currently associated with *this is ready, the continuation + INVOKE(std::move(fd), *this) is called on an unspecified thread of execution, where + INVOKE is the operation defined in Callable. If that expression is invalid, the + behavior is undefined. + + Any value returned from the continuation is stored as the result in the shared state + of the returned future object. Any exception propagated from the execution of the + continuation is stored as the exceptional result in the shared state of the returned + future object. + + Let U be the return type of the continuation (i.e. + std::result_of_t(const std::experimental::shared_future &)>). If + U is std::experimental::future for some type T2, then the return type of then is + std::experimental::future, otherwise it is std::experimental::future. This is + known as implicit unwrapping. + + If implicit unwrapping takes place and the continuation returns an invalid future, + then the shared state is made ready with an exception of type std::future_error with + an error condition of std::future_errc::broken_promise. + + After this function returns, valid() is true. + +.SH Parameters + + func - a continuation to be attached + +.SH Return value + + A std::experimental::future object associated with the shared state created by this + object. valid() == true for the returned object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::shared_ptr.3 b/man/std::experimental::shared_ptr.3 new file mode 100644 index 000000000..db0364664 --- /dev/null +++ b/man/std::experimental::shared_ptr.3 @@ -0,0 +1,138 @@ +.TH std::experimental::shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_ptr \- std::experimental::shared_ptr + +.SH Synopsis + Defined in header + template< class T > class shared_ptr; (library fundamentals TS) + + std::experimental::shared_ptr is a modified version of std::shared_ptr that adds + support for arrays. + +.SH Member types + + Member type Definition + element_type std::remove_extent_t + +.SH Member functions + + constructor constructs new shared_ptr + \fI(public member function)\fP +.SH Observers + get returns the stored pointer + \fI(public member function)\fP + operator* dereferences the stored pointer + operator-> \fI(public member function)\fP + operator[] provides index access to the array + \fI(public member function)\fP + +.SH Non-member functions + + static_pointer_cast applies static_cast, dynamic_cast, const_cast, or + dynamic_pointer_cast reinterpret_cast to the stored pointer + const_pointer_cast \fI(function template)\fP + reinterpret_pointer_cast + +.SH Helper classes + + hash support for + std::hash std::experimental::shared_ptr + \fI(class template specialization)\fP + +Members and non-members identical to std::shared_ptr + +.SH Member functions + + The following member functions work with std::experimental::shared_ptr instead of + std::shared_ptr and std::experimental::weak_ptr instead of std::weak_ptr. The + behavior is otherwise identical. + + destructor destructs the owned object if no more shared_ptrs link to it + \fI(public member function of std::shared_ptr)\fP + operator= assigns the shared_ptr + \fI(public member function of std::shared_ptr)\fP +.SH Modifiers + reset replaces the managed object + \fI(public member function of std::shared_ptr)\fP + swap swaps the managed objects + \fI(public member function of std::shared_ptr)\fP +.SH Observers + returns the number of shared_ptr objects referring to the same managed + use_count object + \fI(public member function of std::shared_ptr)\fP + unique checks whether the managed object is managed only by the current + \fI(until C++20)\fP shared_ptr object + \fI(public member function of std::shared_ptr)\fP + operator bool checks if the stored pointer is not null + \fI(public member function of std::shared_ptr)\fP + owner_before provides owner-based ordering of shared pointers + \fI(public member function of std::shared_ptr)\fP + +.SH Non-member functions + + These non-member functions are declared in the std::experimental namespace, and work + with std::experimental::shared_ptr rather than std::shared_ptr, but otherwise + behaves identically to the corresponding C++14 function. + + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + allocate_shared creates a shared pointer that manages a new object + allocate_shared_for_overwrite allocated using an allocator + (C++20) \fI(function template)\fP + get_deleter returns the deleter of specified type, if owned + \fI(function template)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= compares with another shared_ptr or with nullptr + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + outputs the value of the stored pointer to an output + operator<<(std::shared_ptr) stream + \fI(function template)\fP + std::swap(std::shared_ptr) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + + std::atomic_is_lock_free(std::shared_ptr) + std::atomic_load(std::shared_ptr) + std::atomic_load_explicit(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP + std::atomic_compare_exchange_strong(std::shared_ptr) + std::atomic_compare_exchange_weak_explicit(std::shared_ptr) + std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) + + Helper class templates + + These class templates are declared in the std::experimental namespace, and work with + std::experimental::shared_ptr and std::experimental::weak_ptr rather than + std::shared_ptr and std::weak_ptr, but otherwise behaves identically to the + corresponding C++14 class template. + + owner_less provides mixed-type owner-based ordering of shared and weak + \fI(C++11)\fP pointers + \fI(class template)\fP + enable_shared_from_this allows an object to create a shared_ptr referring to itself + \fI(C++11)\fP \fI(class template)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::shared_ptr::get.3 b/man/std::experimental::shared_ptr::get.3 new file mode 100644 index 000000000..dfbced59c --- /dev/null +++ b/man/std::experimental::shared_ptr::get.3 @@ -0,0 +1,35 @@ +.TH std::experimental::shared_ptr::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_ptr::get \- std::experimental::shared_ptr::get + +.SH Synopsis + element_type* get() const noexcept; (library fundamentals TS) + + Returns the stored pointer. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The stored pointer. + +.SH Notes + + A shared_ptr may share ownership of an object while storing a pointer to another + object. get() returns the stored pointer, not the managed pointer. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* dereferences the stored pointer + operator-> \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::shared_ptr::operator*,std::experimental::shared_ptr::operator->.3 b/man/std::experimental::shared_ptr::operator*,std::experimental::shared_ptr::operator->.3 new file mode 100644 index 000000000..d5f640a50 --- /dev/null +++ b/man/std::experimental::shared_ptr::operator*,std::experimental::shared_ptr::operator->.3 @@ -0,0 +1,44 @@ +.TH std::experimental::shared_ptr::operator*,std::experimental::shared_ptr::operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_ptr::operator*,std::experimental::shared_ptr::operator-> \- std::experimental::shared_ptr::operator*,std::experimental::shared_ptr::operator-> + +.SH Synopsis + T& operator*() const noexcept; \fB(1)\fP (library fundamentals TS) + T* operator->() const noexcept; \fB(2)\fP (library fundamentals TS) + + Dereferences the stored pointer. The behavior is undefined if the stored pointer is + null. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The result of dereferencing the stored pointer, i.e., *get(). + 2) The stored pointer, i.e., get(). + + Remarks + + When T is an array type or (possibly cv-qualified) void, it is unspecified whether + function \fB(1)\fP is declared. + + When T is an array type, it is unspecified whether function \fB(2)\fP is declared. + + In either case, if the function is declared, it is unspecified what its return type + is, except that the declaration (although not necessarily the definition) of the + function is guaranteed to be legal. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns the stored pointer + \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::shared_ptr::operator[].3 b/man/std::experimental::shared_ptr::operator[].3 new file mode 100644 index 000000000..91d14935c --- /dev/null +++ b/man/std::experimental::shared_ptr::operator[].3 @@ -0,0 +1,43 @@ +.TH std::experimental::shared_ptr::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_ptr::operator[] \- std::experimental::shared_ptr::operator[] + +.SH Synopsis + element_type& operator[]( std::ptrdiff_t i ) const (library fundamentals TS) + noexcept; + + Index into the array pointed to by the stored pointer. + + The behavior is undefined if the stored pointer is null or if i is negative. + + If T (the template parameter of shared_ptr) is an array type U[N], i shall be less + than N, or the behavior is undefined. + +.SH Parameters + + i - the array index + +.SH Return value + + A reference to the i-th element of the array, i.e., get()[i]. + + Remarks + + When T is not an array type, it is unspecified whether this function is declared. If + the function is declared, it is unspecified what its return type is, except that the + declaration (although not necessarily the definition) of the function is guaranteed + to be legal. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get returns the stored pointer + \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::shared_ptr::shared_ptr.3 b/man/std::experimental::shared_ptr::shared_ptr.3 new file mode 100644 index 000000000..5abf790d4 --- /dev/null +++ b/man/std::experimental::shared_ptr::shared_ptr.3 @@ -0,0 +1,137 @@ +.TH std::experimental::shared_ptr::shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shared_ptr::shared_ptr \- std::experimental::shared_ptr::shared_ptr + +.SH Synopsis + constexpr shared_ptr() noexcept; \fB(1)\fP + constexpr shared_ptr( std::nullptr_t ) noexcept; \fB(2)\fP + template< class Y > \fB(3)\fP + explicit shared_ptr( Y* ptr ); + template< class Y, class Deleter > \fB(4)\fP + shared_ptr( Y* ptr, Deleter d ); + template< class Deleter > \fB(5)\fP + shared_ptr( std::nullptr_t ptr, Deleter d ); + template< class Y, class Deleter, class Alloc > \fB(6)\fP + shared_ptr( Y* ptr, Deleter d, Alloc alloc ); + template< class Deleter, class Alloc > \fB(7)\fP + shared_ptr( std::nullptr_t ptr, Deleter d, Alloc alloc ); + template< class Y > \fB(8)\fP + shared_ptr( const shared_ptr& r, element_type *ptr ) noexcept; + shared_ptr( const shared_ptr& r ) noexcept; \fB(9)\fP + template< class Y > \fB(9)\fP + shared_ptr( const shared_ptr& r ) noexcept; + shared_ptr( shared_ptr&& r ) noexcept; \fB(10)\fP + template< class Y > \fB(10)\fP + shared_ptr( shared_ptr&& r ) noexcept; + template< class Y > \fB(11)\fP + explicit shared_ptr( const std::weak_ptr& r ); + template< class Y > \fB(12)\fP + shared_ptr( std::auto_ptr&& r ); + template< class Y, class Deleter > \fB(13)\fP + shared_ptr( std::unique_ptr&& r ); + + Constructs new shared_ptr from a variety of pointer types that refer to an object to + manage. + + For the purposes of the description below, a pointer type Y* is said to be + compatible with a pointer type T* if either Y* is convertible to T* or Y is the + array type U[N] and T is U cv [] (where cv is some set of cv-qualifiers). + + 1,2) Constructs a shared_ptr with no managed object, i.e. empty shared_ptr. + 3-7) Constructs a shared_ptr with ptr as the pointer to the managed object. If T is + an array type U[N], Y(*)[N] must be convertible to T*. If T is an array type U[], + Y(*)[] must be convertible to T*. Otherwise, Y* must be convertible to T*. + Additionally: + 3) Uses a delete-expression (delete ptr, if T is not an array type; delete[] ptr if + T is an array type) as the deleter. Y must be a complete type. That delete + expression must be well formed, have well-defined behavior and not throw any + exceptions. + 4,5) Uses the specified deleter d as the deleter. The expression d(ptr) must be well + formed, have well-defined behavior and not throw any exceptions. Deleter must be + CopyConstructible, and its copy constructor and destructor must not throw + exceptions. + 6,7) Same as (4,5), but additionally uses a copy of alloc for allocation of data for + internal use. Alloc must be a Allocator, and its copy constructor and destructor + must not throw exceptions. + 8) The aliasing constructor: constructs a shared_ptr which shares ownership + information with r, but holds an unrelated and unmanaged pointer ptr. Even if this + shared_ptr is the last of the group to go out of scope, it will call the destructor + for the object originally managed by r. However, calling get() on this will always + return a copy of ptr. It is the responsibility of the programmer to make sure that + this ptr remains valid as long as this shared_ptr exists, such as in the typical use + cases where ptr is a member of the object managed by r or is an alias (e.g., + downcast) of r.get(). + 9) Constructs a shared_ptr which shares ownership of the object managed by r. If r + manages no object, *this manages no object too. The template overload doesn't + participate in overload resolution if Y* is not compatible with T*. + 10) Move-constructs a shared_ptr from r. After the construction, *this contains a + copy of the previous state of r, r is empty. The template overload doesn't + participate in overload resolution if Y* is not compatible with T*. + 11) Constructs a shared_ptr which shares ownership of the object managed by r. Y* + must be compatible with T*. Note that r.lock() may be used for the same purpose: the + difference is that this constructor throws an exception if the argument is empty, + while weak_ptr::lock() constructs an empty shared_ptr in that case. + 12) Constructs a shared_ptr that stores and owns the object formerly owned by r. Y* + must be convertible to T*. After construction, r is empty. + 13) Constructs a shared_ptr which manages the object currently managed by r. The + deleter associated with r is stored for future deletion of the managed object. r + manages no object after the call. This overload doesn't participate in overload + resolution if Y* is not compatible with T*. + If D is a reference type, equivalent to shared_ptr(r.release(), + std::ref(r.get_deleter()). Otherwise, equivalent to shared_ptr(r.release(), + r.get_deleter()). + +.SH Notes + + When constructing a shared_ptr from a raw pointer to an object of a type derived + from std::experimental::enable_shared_from_this, the constructors of shared_ptr + update the private weak_ptr member of the std::experimental::enable_shared_from_this + base so that future calls to shared_from_this() would share ownership with the + shared_ptr created by this raw pointer constructor. + + The raw pointer overloads assume ownership of the pointed-to object, and so + constructing a shared_ptr using the raw pointer overload for an object that is + already managed by a shared_ptr may lead to undefined behavior, even if the object + is of a type derived from std::experimental::enable_shared_from_this. + +.SH Parameters + + ptr - a pointer to an object to manage + d - a deleter to use to destroy the object + alloc - an allocator to use for allocations of data for internal use + r - another smart pointer to share the ownership to or acquire the ownership + from + +.SH Exceptions + + 3) std::bad_alloc if required additional memory could not be obtained. May throw + implementation-defined exception for other errors. The applicable delete-expression + (delete ptr if T is not an array type, delete[] ptr otherwise) is called if an + exception occurs. + 4-7) std::bad_alloc if required additional memory could not be obtained. May throw + implementation-defined exception for other errors. d(ptr) is called if an exception + occurs. + 11) std::bad_weak_ptr if r.expired() == true. The constructor has no effect in this + case. + 12) std::bad_alloc if required additional memory could not be obtained. May throw + implementation-defined exception for other errors. This constructor has no effect if + an exception occurs. + 13) If an exception is thrown, the constructor has no effects. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + allocate_shared creates a shared pointer that manages a new object + allocate_shared_for_overwrite allocated using an allocator + (C++20) \fI(function template)\fP + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::shuffle.3 b/man/std::experimental::shuffle.3 new file mode 100644 index 000000000..089a69fbe --- /dev/null +++ b/man/std::experimental::shuffle.3 @@ -0,0 +1,61 @@ +.TH std::experimental::shuffle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::shuffle \- std::experimental::shuffle + +.SH Synopsis + Defined in header + template< class RandomIt > (library fundamentals TS v2) + void shuffle( RandomIt first, RandomIt last ); + + Reorders the elements in the given range [first, last) such that each possible + permutation of those elements has equal probability of appearance, using the + per-thread random number engine as the random number generator. + +.SH Parameters + + first, last - the range of elements to shuffle randomly + - + RandomIt must meet the requirements of ValueSwappable and + LegacyRandomAccessIterator. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the distance between first and last. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string sample{"ABCDEF"}; + + for (int i = 0; i != 4; ++i) + { + std::experimental::shuffle(sample.begin(), sample.end()); + std::cout << sample << '\\n'; + } + } + +.SH Possible output: + + DACBFE + CDFBAE + BDCAFE + BAFCED + +.SH See also + + random_shuffle + shuffle randomly re-orders elements in a range + \fI(until C++17)\fP \fI(function template)\fP + \fI(C++11)\fP diff --git a/man/std::experimental::simd.3 b/man/std::experimental::simd.3 new file mode 100644 index 000000000..519369eee --- /dev/null +++ b/man/std::experimental::simd.3 @@ -0,0 +1,104 @@ +.TH std::experimental::simd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd \- std::experimental::simd + +.SH Synopsis + Defined in header + template< class T, class Abi = simd_abi::compatible > (parallelism TS v2) + class simd; + + The class template simd is a data-parallel type. The width of a given simd + instantiation is a constant expression, determined by the template parameters. + + An ABI tag is a type in the simd_abi namespace that indicates a choice of size and + binary representation for objects of data-parallel type. + +.SH Template parameters + + T - element type; an arithmetic type other than bool + Abi - tag type used to determine the number of elements and storage + + Helper alias templates + + template< class T, int N > + using fixed_size_simd = std::experimental::simd>; + template< class T > + using native_simd = std::experimental::simd>; + +.SH Member types + + Member type Definition + value_type T + reference implementation-defined + mask_type simd_mask + abi_type Abi + +.SH Member functions + + constructor constructs a simd object + (parallelism TS v2) \fI(public member function)\fP + copy_from loads simd elements from contiguous memory + (parallelism TS v2) \fI(public member function)\fP + copy_to stores simd elements to contiguous memory + (parallelism TS v2) \fI(public member function)\fP + operator[] accesses specified element + (parallelism TS v2) \fI(public member function)\fP + operator++ element-wise increment and decrement + operator-- \fI(public member function)\fP + (parallelism TS v2) + operator! + operator~ element-wise unary operators + operator+ \fI(public member function)\fP + operator- + (parallelism TS v2) + size returns the width / number of elements + \fB[static]\fP (parallelism TS v2) \fI(public static member function)\fP + +.SH Non-member functions + + operator+ + operator- + operator* + operator/ + operator% element-wise binary operators + operator& \fI(function)\fP + operator| + operator^ + operator<< + operator>> + (parallelism TS v2) + operator+= + operator-= + operator*= + operator/= + operator%= element-wise compound binary operators + operator&= \fI(function)\fP + operator|= + operator^= + operator<<= + operator>>= + (parallelism TS v2) + operator== + operator!= + operator>= element-wise relational operators + operator<= \fI(function)\fP + operator> + operator< + (parallelism TS v2) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + simd_mask data-parallel type with the element type bool + (parallelism TS v2) \fI(class template)\fP + valarray numeric arrays, array masks and array slices + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::simd::copy_from.3 b/man/std::experimental::simd::copy_from.3 new file mode 100644 index 000000000..b0cbcc03a --- /dev/null +++ b/man/std::experimental::simd::copy_from.3 @@ -0,0 +1,70 @@ +.TH std::experimental::simd::copy_from 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::copy_from \- std::experimental::simd::copy_from + +.SH Synopsis + template< class U, class Flags > (parallelism TS v2) + void copy_from( const U* mem, Flags flags ); + + The load function replaces all elements of a simd such that the i^th element is + assigned with static_cast(mem[i]) for all i in the range of [0, size()). + +.SH Parameters + + mem - a pointer into an array where [mem, mem + size()) is a valid range + flags - if of type vector_aligned_tag, the load constructor may assume mem to point + to storage aligned by memory_alignment_v +.SH Type requirements + - + U must be a vectorizable type. + - + is_simd_flag_type_v must be true. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace stdx = std::experimental; + + void print(auto const& a) + { + for (std::size_t i{}; i != std::size(a); ++i) + std::cout << a[i] << ' '; + std::cout << '\\n'; + } + + int main() + { + alignas(stdx::memory_alignment_v>) + std::array::size() * 2> mem = {}; + std::iota(mem.begin(), mem.end(), 0); + print(mem); + + stdx::native_simd a; // uninitialized + + a.copy_from(&mem[0], stdx::vector_aligned); + print(a); + + a.copy_from(&mem[1], stdx::element_aligned); // vector_aligned would likely crash + print(a); + } + +.SH Possible output: + + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 + 0 1 2 3 4 5 6 7 + 1 2 3 4 5 6 7 8 + +.SH See also + + memory_alignment obtains an appropriate alignment for vector_aligned + (parallelism TS v2) \fI(class template)\fP + copy_to stores simd elements to contiguous memory + (parallelism TS v2) \fI(public member function)\fP + constructor constructs a simd object + (parallelism TS v2) \fI(public member function)\fP diff --git a/man/std::experimental::simd::copy_to.3 b/man/std::experimental::simd::copy_to.3 new file mode 100644 index 000000000..4cb7ccde6 --- /dev/null +++ b/man/std::experimental::simd::copy_to.3 @@ -0,0 +1,64 @@ +.TH std::experimental::simd::copy_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::copy_to \- std::experimental::simd::copy_to + +.SH Synopsis + template< class U, class Flags > (parallelism TS v2) + void copy_to( U* mem, Flags flags ); + + The store function copies all elements of a simd such that the i-th element is + converted to U and subsequently written to mem[i] for all i in the range of + [0, size()). + +.SH Parameters + + mem - a pointer into an array where [mem, mem + size()) is a valid range + flags - if of type vector_aligned_tag, the load constructor may assume mem to point + to storage aligned by memory_alignment_v +.SH Type requirements + - + U must be a vectorizable type. + - + is_simd_flag_type_v must be true. + +.SH Example + + +// Run this code + + #include + #include + namespace stdx = std::experimental; + + int main() + { + alignas(stdx::memory_alignment_v>) + std::array::size()> mem = {}; + + stdx::native_simd a = 7; + a.copy_to(&mem[0], stdx::vector_aligned); + + for (int e : mem) + std::cout << e << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 + +.SH See also + + element_aligned_tag flag indicating alignment of the load/store address to element + element_aligned alignment + (parallelism TS v2) \fI(class)\fP + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + overaligned_tag flag indicating alignment of the load/store address to the + overaligned specified alignment + (parallelism TS v2) \fI(class template)\fP + memory_alignment obtains an appropriate alignment for vector_aligned + (parallelism TS v2) \fI(class template)\fP + copy_from loads simd elements from contiguous memory + (parallelism TS v2) \fI(public member function)\fP diff --git a/man/std::experimental::simd::operator!,~,+,-.3 b/man/std::experimental::simd::operator!,~,+,-.3 new file mode 100644 index 000000000..619221f6b --- /dev/null +++ b/man/std::experimental::simd::operator!,~,+,-.3 @@ -0,0 +1,69 @@ +.TH std::experimental::simd::operator!,~,+,- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::operator!,~,+,- \- std::experimental::simd::operator!,~,+,- + +.SH Synopsis + mask_type operator!() const noexcept; \fB(1)\fP (parallelism TS v2) + simd operator~() const noexcept; \fB(2)\fP (parallelism TS v2) + simd operator+() const noexcept; \fB(3)\fP (parallelism TS v2) + simd operator-() const noexcept; \fB(4)\fP (parallelism TS v2) + + Applies the given unary operator on each element of the simd. + + 1) Returns a simd_mask where the i^th element equals !operator[](i) for all + i in the range of [0, size()). + 2) Returns a simd where each bit is the inverse of the corresponding bit in *this. + This overload participates in overload resolution only if T is an integral type. + 3) Returns a copy of itself. + 4) Returns a simd where the i^th element is initialized to -operator[](i) for all i + in the range of [0, size()). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace stdx = std::experimental; + + void println(std::string_view op, const stdx::native_simd_mask x) + { + std::cout << op << ": "; + for (std::size_t i = 0; i < x.size(); ++i) + std::cout << std::boolalpha << x[i] << ' '; + std::cout << '\\n'; + } + + void println(std::string_view op, const stdx::native_simd x) + { + std::cout << op << ": "; + for (std::size_t i = 0; i < x.size(); ++i) + std::cout << x[i] << ' '; + std::cout << '\\n'; + } + + int main() + { + const stdx::native_simd a([](int i) { return i; }); + + println(" a", a); + println(" !a", !a); + println(" ~a", ~a); + println("~~a", ~~a); + println(" +a", +a); + println(" -a", -a); + println("+-a", +-a); + } + +.SH Possible output: + + a: 0 1 2 3 + !a: true false false false + ~a: -1 -2 -3 -4 + ~~a: 0 1 2 3 + +a: 0 1 2 3 + -a: 0 -1 -2 -3 + +-a: 0 -1 -2 -3 diff --git a/man/std::experimental::simd::operator++,std::experimental::simd::operator--.3 b/man/std::experimental::simd::operator++,std::experimental::simd::operator--.3 new file mode 100644 index 000000000..55a4b2029 --- /dev/null +++ b/man/std::experimental::simd::operator++,std::experimental::simd::operator--.3 @@ -0,0 +1,56 @@ +.TH std::experimental::simd::operator++,std::experimental::simd::operator-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::operator++,std::experimental::simd::operator-- \- std::experimental::simd::operator++,std::experimental::simd::operator-- + +.SH Synopsis + simd& operator++() noexcept; \fB(1)\fP (parallelism TS v2) + simd operator++( int ) noexcept; \fB(2)\fP (parallelism TS v2) + simd& operator--() noexcept; \fB(3)\fP (parallelism TS v2) + simd operator--( int ) noexcept; \fB(4)\fP (parallelism TS v2) + + Applies the increment or decrement operator on each element of the simd. + + 1) Increments all values in the simd by 1 and returns a reference to itself. + 2) Increments all values in the simd by 1 and returns a copy of itself before the + operation. + 3) Decrements all values in the simd by 1 and returns a reference to itself. + 4) Decrements all values in the simd by 1 and returns a copy of itself before the + operation. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace stdx = std::experimental; + + void print(auto rem, auto const& a) + { + std::cout << rem << ": "; + for (std::size_t i{}; i != std::size(a); ++i) + std::cout << a[i] << ' '; + std::cout << '\\n'; + } + + int main() + { + stdx::native_simd p = -2; + print('p', p); + + ++p; + print('p', p); + + auto q = p--; + print('p', p); + print('q', q); + } + +.SH Possible output: + + p: -2 -2 -2 -2 + p: -1 -1 -1 -1 + p: -2 -2 -2 -2 + q: -1 -1 -1 -1 diff --git a/man/std::experimental::simd::operator==,!=,,>=.3 b/man/std::experimental::simd::operator==,!=,,>=.3 new file mode 100644 index 000000000..1b9779016 --- /dev/null +++ b/man/std::experimental::simd::operator==,!=,,>=.3 @@ -0,0 +1,95 @@ +.TH std::experimental::simd::operator==,!=,,>= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::operator==,!=,,>= \- std::experimental::simd::operator==,!=,,>= + +.SH Synopsis + friend simd_mask operator==( const simd& lhs, const simd& \fB(1)\fP (parallelism TS v2) + rhs ) noexcept; + friend simd_mask operator!=( const simd& lhs, const simd& \fB(2)\fP (parallelism TS v2) + rhs ) noexcept; + friend simd_mask operator<( const simd& lhs, const simd& rhs \fB(3)\fP (parallelism TS v2) + ) noexcept; + friend simd_mask operator<=( const simd& lhs, const simd& \fB(4)\fP (parallelism TS v2) + rhs ) noexcept; + friend simd_mask operator>( const simd& lhs, const simd& rhs \fB(5)\fP (parallelism TS v2) + ) noexcept; + friend simd_mask operator>=( const simd& lhs, const simd& \fB(6)\fP (parallelism TS v2) + rhs ) noexcept; + + Applies the given comparison element-wise to each corresponding element of the + operands. Returns a simd_mask such that for all i in the range of [0, size()) the + i^th element equals: + + 1) lhs[i] == rhs[i]. + 2) lhs[i] != rhs[i]. + 3) lhs[i] < rhs[i]. + 4) lhs[i] <= rhs[i]. + 5) lhs[i] > rhs[i]. + 6) lhs[i] >= rhs[i]. + +.SH Parameters + + lhs - left operands + rhs - right operands + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + #include + namespace stdx = std::experimental; + + int main() + { + using V = stdx::fixed_size_simd; + using M = stdx::fixed_size_simd_mask; + + auto assert_equivalence = [](M&& x, std::initializer_list&& y) + { + for (decltype(M::size()) i{}; i != M::size(); ++i) + assert(x[i] == std::cbegin(y)[i]); + }; + + V a{2}, b, c{3}; + b[0] = 1, b[1] = 2, b[2] = 3, b[3] = 4; + + // a == {2, 2, 2, 2} + // b == {1, 2, 3, 4} + // c == {3, 3, 3, 3} + + assert_equivalence(a == a, {1, 1, 1, 1}); + assert_equivalence(a == b, {0, 1, 0, 0}); + assert_equivalence(b == c, {0, 0, 1, 0}); + assert_equivalence(a == c, {0, 0, 0, 0}); + + assert_equivalence(a != a, {0, 0, 0, 0}); + assert_equivalence(a != b, {1, 0, 1, 1}); + assert_equivalence(b != c, {1, 1, 0, 1}); + assert_equivalence(a != c, {1, 1, 1, 1}); + + assert_equivalence(a < a, {0, 0, 0, 0}); + assert_equivalence(a < b, {0, 0, 1, 1}); + assert_equivalence(b < c, {1, 1, 0, 0}); + assert_equivalence(a < c, {1, 1, 1, 1}); + } + +.SH See also + + all_of + any_of reductions of simd_mask to bool + none_of \fI(function template)\fP + some_of + (parallelism TS v2) + popcount reduction of simd_mask to the number of true values + (parallelism TS v2) \fI(function template)\fP + find_first_set reductions of simd_mask to the index of the first or last true + find_last_set value + (parallelism TS v2) \fI(function template)\fP + simd_mask data-parallel type with the element type bool + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::simd::operator[].3 b/man/std::experimental::simd::operator[].3 new file mode 100644 index 000000000..c12f8d7f7 --- /dev/null +++ b/man/std::experimental::simd::operator[].3 @@ -0,0 +1,44 @@ +.TH std::experimental::simd::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::operator[] \- std::experimental::simd::operator[] + +.SH Synopsis + reference operator[]( std::size_t i ); \fB(1)\fP (parallelism TS v2) + value_type operator[]( std::size_t i ) const; \fB(2)\fP (parallelism TS v2) + + The subscript operators allow reading and writing single elements of a simd. + + 1) Returns a reference proxy to the i-th element. This proxy type should not be + captured into an lvalue. Lvalues of simd::reference can only convert to value_type. + Rvalues of simd::reference overload assignment and all compound assignment operators + as well as swap. + 2) Returns a prvalue of the i-th element. In contrast to containers, which contain + objects of type value_type, a simd is not a container of individual objects and + therefore cannot return an lvalue-reference. + +.SH Parameters + + i - the element index. Required to be less than size() + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace stdx = std::experimental; + + int main() + { + const stdx::native_simd a = 3; + for (std::size_t i = 0; i != a.size(); ++i) + std::cout << a[i] << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 3 3 3 3 3 3 3 3 diff --git a/man/std::experimental::simd::simd.3 b/man/std::experimental::simd::simd.3 new file mode 100644 index 000000000..d213aa8ae --- /dev/null +++ b/man/std::experimental::simd::simd.3 @@ -0,0 +1,100 @@ +.TH std::experimental::simd::simd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::simd \- std::experimental::simd::simd + +.SH Synopsis + simd() noexcept = default; \fB(1)\fP (parallelism TS v2) + template< class U > \fB(2)\fP (parallelism TS v2) + simd( U&& value ) noexcept; + template< class U > + simd( const simd>& other ) \fB(3)\fP (parallelism TS v2) + noexcept; + template< class G > \fB(4)\fP (parallelism TS v2) + explicit simd( G&& generator ) noexcept; + template< class U, class Flags > \fB(5)\fP (parallelism TS v2) + simd( const U* mem, Flags flags ); + simd( const simd& other ) noexcept = default; \fB(6)\fP (parallelism TS v2) + (implicitly declared) + simd( simd&& other ) noexcept = default; \fB(7)\fP (parallelism TS v2) + (implicitly declared) + + 1) Constructs a simd using default initialization (constructed without initializer) + or value initialization (constructed with an empty initializer). + 2) The broadcast constructor constructs a simd with all values initialized to value. + This overload participates in overload resolution only if the conversion from U to T + is value-preserving, or U is either int or unsigned int if T is an unsigned integral + type. + 3) Constructs a simd where the i-th element is initialized to + static_cast(other[i]) for all i in the range of [0, size()). This overload + participates in overload resolution only if Abi is simd_abi::fixed_size and + the conversion from U to T is value-preserving, and, if both U and T are integral, + the integer conversion rank of T is greater than the integer conversion rank of U. + 4) The generator constructor constructs a simd where the i-th element is initialized + to generator(std::integral_constant()). This overload participates + in overload resolution only if simd(gen(std::integral_constant())) + is well-formed for all i in the range of [0, size()). The calls to generator are + unsequenced with respect to each other. Vectorization-unsafe standard library + functions may not be invoked by generator. + 5) The load constructor constructs a simd where the i-th element is initialized to + static_cast(mem[i]) for all i in the range of [0, size()). + 6,7) Implicitly declared copy and move constructors. Constructs a simd where each + element is initialized from the values of the elements in other. + +.SH Parameters + + value - the value used for initialization of all simd elements + other - another simd to copy from + generator - a function object used for initialization of each simd + element + mem - a pointer into an array where [mem, mem + size()) is a + valid range + if of type vector_aligned_tag, the load constructor may + flags - assume mem to point to storage aligned by + memory_alignment_v +.SH Type requirements + - + The conversion from U to T must be value-preserving. The broadcast constructor \fB(2)\fP + additionally allows U to be int or to be unsigned int if T is an unsigned integral + type. + - + is_simd_flag_type_v must be true. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace stdx = std::experimental; + + int main() + { + stdx::native_simd a; // uninitialized + a = 1; // all elements set to 1 + stdx::native_simd b([](int i) { return i; }); // {0, 1, 2, 3, ...} + + alignas(stdx::memory_alignment_v>) + std::array::size() * 2> mem = {}; + for (std::size_t i = 0; i < mem.size(); ++i) + mem[i] = i & 1; + + stdx::native_simd c(&mem[0], stdx::vector_aligned); // {0, 1, 0, 1, ...} + stdx::native_simd d(&mem[1], stdx::element_aligned); // {1, 0, 1, 0, ...} + + auto sum = a + b + c + d; + + for (std::size_t i = 0; i < sum.size(); ++i) + std::cout << sum[i] << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 + +.SH See also + + copy_from loads simd elements from contiguous memory + (parallelism TS v2) \fI(public member function)\fP diff --git a/man/std::experimental::simd::size.3 b/man/std::experimental::simd::size.3 new file mode 100644 index 000000000..fdd38f11c --- /dev/null +++ b/man/std::experimental::simd::size.3 @@ -0,0 +1,41 @@ +.TH std::experimental::simd::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd::size \- std::experimental::simd::size + +.SH Synopsis + static constexpr size_t size() noexcept; (parallelism TS v2) + + Returns the width (the number of values) of simd. + +.SH Example + + The actual output depends on target and compiler flags. + + +// Run this code + + #include + #include + #include + namespace stdx = std::experimental; + + int main() + { + stdx::native_simd a = 1; + std::cout << a.size() << '\\n'; + std::cout << reduce(a) << '\\n'; + } + +.SH Possible output: + + 16 + 16 + +.SH See also + + simd_size obtains the number of elements of a given element type and + (parallelism TS v2) ABI tag + \fI(class template)\fP + size returns the width / number of elements + \fB[static]\fP (parallelism TS \fI\fI(public static member\fP function of\fP + v2) std::experimental::simd_mask) diff --git a/man/std::experimental::simd_abi::compatible.3 b/man/std::experimental::simd_abi::compatible.3 new file mode 100644 index 000000000..d4e5ccee9 --- /dev/null +++ b/man/std::experimental::simd_abi::compatible.3 @@ -0,0 +1,28 @@ +.TH std::experimental::simd_abi::compatible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_abi::compatible \- std::experimental::simd_abi::compatible + +.SH Synopsis + Defined in header + template< class T > (parallelism TS v2) + using compatible = /*implementation-defined*/; + + compatible is an implementation-defined alias for an ABI tag. + +.SH Notes + + The intent is to use the ABI tag producing the most efficient data-parallel + execution for the element type T that ensures ABI compatibility between translation + units on the target architecture. + +.SH See also + + scalar tag type for storing a single element + (parallelism TS v2) \fI(typedef)\fP + fixed_size tag type for storing specified number of elements + (parallelism TS v2) (alias template) + native tag type that is most efficient + (parallelism TS v2) (alias template) + deduce obtains an ABI type for given element type and number of + deduce_t elements + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::simd_abi::deduce.3 b/man/std::experimental::simd_abi::deduce.3 new file mode 100644 index 000000000..199abc35c --- /dev/null +++ b/man/std::experimental::simd_abi::deduce.3 @@ -0,0 +1,61 @@ +.TH std::experimental::simd_abi::deduce 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_abi::deduce \- std::experimental::simd_abi::deduce + +.SH Synopsis + Defined in header + template< class T, std::size_t N, class ...Abis > (parallelism TS v2) + struct deduce; + + The type deduce::type is present if and only if: + + * T is a vectorizable type, + * simd_abi::fixed_size is supported, and + * every type in Abis... is an ABI tag. + + Let DA denote deduce::type when it presents, then + + * simd_size_v == N, + * simd is default constructible, i.e. it is supported, + * DA is simd_abi::scalar if N == 1, otherwise it is implementation-defined. + +.SH Member types + + Name Definition + type an ABI tag type suitable for specified element type T and size N + +.SH Helper types + + template< class T, std::size_t N, class ...Abis > (parallelism TS v2) + using deduce_t = typename deduce::type; + +.SH Notes + + simd_abi::deduce is SFINAE-friendly. + + The ABI tag deduced via this facility is a Quality-of-Implementation feature. + Implementations can base the choice on Abis..., but can also ignore the Abis... + arguments. A simple implementation might simply return fixed_size + unconditionally. An optimized implementation might return an implementation-defined + extended ABI tag for most inputs. Consequently, if you need an ABI tag for a certain + number of elements, use fixed_size if ABI stability is of concern, and prefer + deduce_t otherwise. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + scalar tag type for storing a single element + (parallelism TS v2) \fI(typedef)\fP + fixed_size tag type for storing specified number of elements + (parallelism TS v2) (alias template) + compatible tag type that ensures ABI compatibility + (parallelism TS v2) (alias template) + native tag type that is most efficient + (parallelism TS v2) (alias template) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::simd_abi::fixed_size.3 b/man/std::experimental::simd_abi::fixed_size.3 new file mode 100644 index 000000000..38b65b0aa --- /dev/null +++ b/man/std::experimental::simd_abi::fixed_size.3 @@ -0,0 +1,45 @@ +.TH std::experimental::simd_abi::fixed_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_abi::fixed_size \- std::experimental::simd_abi::fixed_size + +.SH Synopsis + Defined in header + template< int N > (parallelism TS v2) + struct fixed_size {}; + + The simd_abi::fixed_size tag type ensures data-parallel types to store and + manipulate N elements (i.e. simd>::size() returns N). An + implementation shall support at least all N ∈ [1, 32]. Additionally, for every + supported simd, where Abi is an implementation-defined ABI tag, N = simd::size() shall be supported. + +.SH Notes + + An implementation may choose to forego ABI compatibility between differently + compiled translation units for simd and simd_mask instantiations using the same + simd_abi::fixed_size tag. Otherwise, the efficiency of simd is likely to + be better than simd>> (with Abi not an instance of + simd_abi::fixed_size). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + max_fixed_size the maximum number of elements guaranteed to be supported by + (parallelism TS v2) fixed + (constant) + scalar tag type for storing a single element + (parallelism TS v2) \fI(typedef)\fP + compatible tag type that ensures ABI compatibility + (parallelism TS v2) (alias template) + native tag type that is most efficient + (parallelism TS v2) (alias template) + deduce obtains an ABI type for given element type and number of + deduce_t elements + (parallelism TS v2) \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::simd_abi::max_fixed_size.3 b/man/std::experimental::simd_abi::max_fixed_size.3 new file mode 100644 index 000000000..b4b41a5a6 --- /dev/null +++ b/man/std::experimental::simd_abi::max_fixed_size.3 @@ -0,0 +1,46 @@ +.TH std::experimental::simd_abi::max_fixed_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_abi::max_fixed_size \- std::experimental::simd_abi::max_fixed_size + +.SH Synopsis + Defined in header + template< class T > + inline constexpr int max_fixed_size = (parallelism TS v2) + /*implementation-defined*/; + + The value of max_fixed_size declares that an instance of simd> + with N <= max_fixed_size is supported by the implementation. The value of + max_fixed_size is at least 32. + +.SH Notes + + It is unspecified whether an implementation supports simd> with N > + max_fixed_size. The value of max_fixed_size may depend on compiler flags and + may change between different compiler versions. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace stq = std::experimental; + + int main() + { + std::cout << stq::simd_abi::max_fixed_size << ' '; + std::cout << stq::simd_abi::max_fixed_size << ' '; + std::cout << stq::simd_abi::max_fixed_size << ' '; + std::cout << stq::simd_abi::max_fixed_size << '\\n'; + } + +.SH Possible output: + + 32 32 32 32 + +.SH See also + + fixed_size tag type for storing specified number of elements + (parallelism TS v2) (alias template) diff --git a/man/std::experimental::simd_abi::native.3 b/man/std::experimental::simd_abi::native.3 new file mode 100644 index 000000000..ba0e0eb23 --- /dev/null +++ b/man/std::experimental::simd_abi::native.3 @@ -0,0 +1,32 @@ +.TH std::experimental::simd_abi::native 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_abi::native \- std::experimental::simd_abi::native + +.SH Synopsis + Defined in header + template< class T > (parallelism TS v2) + using native = /*implementation-defined*/; + + native is an implementation-defined alias for an ABI tag. This is the primary ABI + tag to use for efficient explicit vectorization. + +.SH Notes + + The intent is to use the ABI tag producing the most efficient data-parallel + execution for the element type T that is supported on the currently targeted system. + For target architectures without ISA extensions, the native and compatible + aliases will likely be the same. For target architectures with ISA extensions, + compiler flags may influence the native alias while compatible will be the + same independent of such flags. + +.SH See also + + scalar tag type for storing a single element + (parallelism TS v2) \fI(typedef)\fP + fixed_size tag type for storing specified number of elements + (parallelism TS v2) (alias template) + compatible tag type that ensures ABI compatibility + (parallelism TS v2) (alias template) + deduce obtains an ABI type for given element type and number of + deduce_t elements + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::simd_abi::scalar.3 b/man/std::experimental::simd_abi::scalar.3 new file mode 100644 index 000000000..683f33b3f --- /dev/null +++ b/man/std::experimental::simd_abi::scalar.3 @@ -0,0 +1,27 @@ +.TH std::experimental::simd_abi::scalar 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_abi::scalar \- std::experimental::simd_abi::scalar + +.SH Synopsis + Defined in header + using scalar = /*unspecified*/; (parallelism TS v2) + + With the scalar ABI tag, data-parallel types are equivalent to a single element + type. However, the full simd and simd_mask interface is supported and thus eases + development of generic code. + +.SH Notes + + scalar is not an alias to fixed_size<1>. + +.SH See also + + fixed_size tag type for storing specified number of elements + (parallelism TS v2) (alias template) + compatible tag type that ensures ABI compatibility + (parallelism TS v2) (alias template) + native tag type that is most efficient + (parallelism TS v2) (alias template) + deduce obtains an ABI type for given element type and number of + deduce_t elements + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::simd_cast,std::experimental::static_simd_cast.3 b/man/std::experimental::simd_cast,std::experimental::static_simd_cast.3 new file mode 100644 index 000000000..ea14baa77 --- /dev/null +++ b/man/std::experimental::simd_cast,std::experimental::static_simd_cast.3 @@ -0,0 +1,58 @@ +.TH std::experimental::simd_cast,std::experimental::static_simd_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_cast,std::experimental::static_simd_cast \- std::experimental::simd_cast,std::experimental::static_simd_cast + +.SH Synopsis + Defined in header + template< class V, class T, class Abi > \fB(1)\fP (parallelism TS v2) + /*see below*/ simd_cast( const simd& v ) noexcept; + template< class V, class T, class Abi > + /*see below*/ static_simd_cast( const simd& v ) \fB(2)\fP (parallelism TS v2) + noexcept; + + Cast a simd object to another simd object. If V is T, returns simd; + otherwise, if V is a scalar type, returns simd::size()>>. Otherwise, V must be a simd type, and the function returns V. + + 1) This function does not participate in overloading resolution unless + * every possible value of the input element can be represented with the output + element, + * either is_simd_v is false, or V::size() is simd::size(). + 2) This function does not participate in overloading resolution unless either + is_simd_v is false, or V::size() is simd::size(). + +.SH Parameters + + v - the input simd object + +.SH Return value + + A simd object with the i-th element initialized to static_cast(v[i]), where To + is the output element type as specified. + +.SH Notes + + The TS specification is missing simd_cast and static_simd_cast overloads for + simd_mask. The libstdc++ implementation provides the missing overloads in the + std::experimental::__proposed namespace. If you already use the + + namespace stdx = std::experimental; + + shortcut, you might be interested to use + + namespace stdx { + using namespace std::experimental; + using namespace std::experimental::__proposed; + } + + instead. Alternatively, libstdc++ implements a __cvt() member function in simd_mask, + which allows implicit conversion of the mask. See also: + https://github.com/VcDevel/std-simd/issues/41 + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::simd_mask.3 b/man/std::experimental::simd_mask.3 new file mode 100644 index 000000000..95dbafa11 --- /dev/null +++ b/man/std::experimental::simd_mask.3 @@ -0,0 +1,81 @@ +.TH std::experimental::simd_mask 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_mask \- std::experimental::simd_mask + +.SH Synopsis + Defined in header + template< class T, class Abi = simd_abi::compatible > (parallelism TS v2) + class simd_mask; + + The class template simd_mask is a data-parallel type with the element type bool. The + width of a given simd_mask instantiation is a constant expression, determined by the + template parameters. Specifically, simd_mask::size() is always simd::size(). + +.SH Template parameters + + T - the element type simd_mask applies on + Abi - the ABI type simd_mask applies on + + Helper alias templates + + Template Definition + template< class T, int N > using simd_mask> + fixed_size_simd_mask + template< class T > using native_simd_mask simd_mask> + +.SH Member types + + Member type Definition + value_type bool + reference implementation-defined + simd_type simd + abi_type Abi + +.SH Member functions + + constructor constructs a simd_mask object + (parallelism TS v2) \fI(public member function)\fP + copy_from loads simd_mask elements from contiguous memory + (parallelism TS v2) \fI(public member function)\fP + copy_to stores simd_mask elements to contiguous memory + (parallelism TS v2) \fI(public member function)\fP + operator[] accesses specified element + (parallelism TS v2) \fI(public member function)\fP + operator! negates each element + (parallelism TS v2) \fI(public member function)\fP + size returns the width / number of elements + \fB[static]\fP (parallelism TS v2) \fI(public static member function)\fP + +.SH Non-member functions + + operator&& element-wise logic operators + operator|| \fI(function)\fP + (parallelism TS v2) + operator& + operator| element-wise bitwise operators + operator^ \fI(function)\fP + (parallelism TS v2) + operator&= + operator|= element-wise compound operators + operator^= \fI(function)\fP + (parallelism TS v2) + operator== element-wise relation operators + operator!= \fI(function)\fP + (parallelism TS v2) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + simd data-parallel vector type + (parallelism TS v2) \fI(class template)\fP + proxy to a subset of a valarray after applying a boolean mask + mask_array operator[] + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::simd_mask::copy_from.3 b/man/std::experimental::simd_mask::copy_from.3 new file mode 100644 index 000000000..62a0bb240 --- /dev/null +++ b/man/std::experimental::simd_mask::copy_from.3 @@ -0,0 +1,40 @@ +.TH std::experimental::simd_mask::copy_from 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_mask::copy_from \- std::experimental::simd_mask::copy_from + +.SH Synopsis + template (parallelism TS v2) + void copy_from( const bool* mem, Flags flags ); + + The load function replaces all elements of a simd_mask such that the i-th element is + assigned with mem[i] for all i in the range of [0, size()). + +.SH Parameters + + mem - a pointer into an array where [mem, mem + size()) is a valid range + flags - if of type vector_aligned_tag, the load constructor may assume mem to point + to storage aligned by memory_alignment_v +.SH Type requirements + - + is_simd_flag_type_v must be true. + +.SH See also + + element_aligned_tag flag indicating alignment of the load/store address to element + element_aligned alignment + (parallelism TS v2) \fI(class)\fP + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + overaligned_tag flag indicating alignment of the load/store address to the + overaligned specified alignment + (parallelism TS v2) \fI(class template)\fP + memory_alignment obtains an appropriate alignment for vector_aligned + (parallelism TS v2) \fI(class template)\fP + constructor constructs a simd_mask object + (parallelism TS v2) \fI(public member function)\fP + copy_to stores simd_mask elements to contiguous memory + (parallelism TS v2) \fI(public member function)\fP + copy_from loads simd elements from contiguous memory + (parallelism TS v2) \fI(public member function of std::experimental::simd)\fP + diff --git a/man/std::experimental::simd_mask::copy_to.3 b/man/std::experimental::simd_mask::copy_to.3 new file mode 100644 index 000000000..9fc8a1c32 --- /dev/null +++ b/man/std::experimental::simd_mask::copy_to.3 @@ -0,0 +1,35 @@ +.TH std::experimental::simd_mask::copy_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_mask::copy_to \- std::experimental::simd_mask::copy_to + +.SH Synopsis + template (parallelism TS v2) + void copy_to( bool* mem, Flags flags ); + + The store function copies all elements of a simd_mask such that the i-th element is + written to mem[i] for all i in the range of [0, size()). + +.SH Parameters + + mem - a pointer into an array where [mem, mem + size()) is a valid range + flags - if if of type vector_aligned_tag, the load constructor may assume mem to + point to storage aligned by memory_alignment_v +.SH Type requirements + - + is_simd_flag_type_v must be true. + +.SH See also + + element_aligned_tag flag indicating alignment of the load/store address to element + element_aligned alignment + (parallelism TS v2) \fI(class)\fP + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + overaligned_tag flag indicating alignment of the load/store address to the + overaligned specified alignment + (parallelism TS v2) \fI(class template)\fP + memory_alignment obtains an appropriate alignment for vector_aligned + (parallelism TS v2) \fI(class template)\fP + copy_from loads simd_mask elements from contiguous memory + (parallelism TS v2) \fI(public member function)\fP diff --git a/man/std::experimental::simd_mask::operator[].3 b/man/std::experimental::simd_mask::operator[].3 new file mode 100644 index 000000000..6883d8498 --- /dev/null +++ b/man/std::experimental::simd_mask::operator[].3 @@ -0,0 +1,44 @@ +.TH std::experimental::simd_mask::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_mask::operator[] \- std::experimental::simd_mask::operator[] + +.SH Synopsis + reference operator[]( size_t i ); \fB(1)\fP (parallelism TS v2) + bool operator[]( size_t i ) const; \fB(2)\fP (parallelism TS v2) + + The subscript operators allow reading and writing single elements of a simd_mask. + + 1) Returns a reference proxy to the i-th element. This proxy type should not be + captured into an lvalue. Lvalues of simd_mask::reference can only convert to + value_type. Rvalues of simd_mask::reference overload assignment and all compound + assignment operators as well as swap. + 2) Returns a prvalue of the i-th element. In contrast to containers, which contain + objects of type value_type, a simd_mask is not a container of individual objects and + therefore cannot return an lvalue-reference. + +.SH Parameters + + i - the element index. Required to be less than size() + +.SH Example + + +// Run this code + + #include + #include + #include + namespace stdx = std::experimental; + + int main() + { + stdx::native_simd_mask a{true}; + a[1] = 0; + for (std::size_t i = 0; i != a.size(); ++i) + std::cout << a[i] << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 1 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 diff --git a/man/std::experimental::simd_mask::simd_mask.3 b/man/std::experimental::simd_mask::simd_mask.3 new file mode 100644 index 000000000..d748c780f --- /dev/null +++ b/man/std::experimental::simd_mask::simd_mask.3 @@ -0,0 +1,91 @@ +.TH std::experimental::simd_mask::simd_mask 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_mask::simd_mask \- std::experimental::simd_mask::simd_mask + +.SH Synopsis + simd_mask() noexcept = default; \fB(1)\fP (parallelism TS v2) + explicit simd_mask( bool value ) noexcept; \fB(2)\fP (parallelism TS v2) + template< class U > + simd_mask( const simd_mask>& other ) noexcept; + template< class U, class Flags > \fB(4)\fP (parallelism TS v2) + simd_mask( const bool* mem, Flags flags ); + simd_mask( const simd_mask& other ) noexcept = default; \fB(5)\fP (parallelism TS v2) + (implicitly declared) + simd_mask( simd_mask&& other ) noexcept = default; \fB(6)\fP (parallelism TS v2) + (implicitly declared) + + 1) Constructs a simd_mask using default initialization (constructed without + initializer) or value initialization (constructed with an empty initializer). + 2) The broadcast constructor constructs a simd_mask with all values initialized to + value. + 3) Constructs a simd_mask where the i-th element is initialized to other[i] for all + i in the range of [0, size()). This overload participates in overload resolution + only if Abi is simd_abi::fixed_size. + 4) The load constructor constructs a simd_mask where the i-th element is initialized + to mem[i] for all i in the range of [0, size()). + 5,6) Implicitly declared copy and move constructors. Constructs a simd_mask where + each element is initialized from the values of the elements in other. + +.SH Parameters + + value - the value used for initialization of all simd_mask elements + other - another simd_mask to copy from + mem - a pointer into an array where [mem, mem + size()) is a valid range + flags - if of type vector_aligned_tag, the load constructor may assume mem to point + to storage aligned by memory_alignment_v +.SH Type requirements + - + is_simd_flag_type_v must be true. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace stdx = std::experimental; + + int main() + { + [[maybe_unused]] + stdx::native_simd_mask a; // uninitialized + stdx::native_simd_mask b(true); // all elements initialized with true + stdx::native_simd_mask c{}; // all elements initialized with false + + alignas(stdx::memory_alignment_v>) + std::array::size() * 2> mem = {}; + std::ranges::generate(mem, [i{0}] mutable -> bool { return i++ & 1; }); + + stdx::native_simd_mask d(&mem[0], stdx::vector_aligned); // {0, 1, 0, 1, ...} + stdx::native_simd_mask e(&mem[1], stdx::element_aligned); // {1, 0, 1, 0, ...} + + const auto xored = b ^ c ^ d ^ e; + + for (std::size_t i{}; i != xored.size(); ++i) + std::cout << xored[i] << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 0 0 0 0 0 0 0 0 + +.SH See also + + element_aligned_tag flag indicating alignment of the load/store address to element + element_aligned alignment + (parallelism TS v2) \fI(class)\fP + vector_aligned_tag flag indicating alignment of the load/store address to vector + vector_aligned alignment + (parallelism TS v2) \fI(class)\fP + overaligned_tag flag indicating alignment of the load/store address to the + overaligned specified alignment + (parallelism TS v2) \fI(class template)\fP + memory_alignment obtains an appropriate alignment for vector_aligned + (parallelism TS v2) \fI(class template)\fP + copy_from loads simd_mask elements from contiguous memory + (parallelism TS v2) \fI(public member function)\fP diff --git a/man/std::experimental::simd_mask::size.3 b/man/std::experimental::simd_mask::size.3 new file mode 100644 index 000000000..3d3dd564b --- /dev/null +++ b/man/std::experimental::simd_mask::size.3 @@ -0,0 +1,40 @@ +.TH std::experimental::simd_mask::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_mask::size \- std::experimental::simd_mask::size + +.SH Synopsis + static constexpr size_t size() noexcept; (parallelism TS v2) + + Returns the width (the number of values) of simd_mask. + +.SH Example + + The actual output depends on target and compiler flags. + + +// Run this code + + #include + #include + namespace stdx = std::experimental; + + int main() + { + stdx::native_simd_mask a { true }; + std::cout << a.size() << '\\n'; + std::cout << popcount(a) << '\\n'; + } + +.SH Possible output: + + 16 + 16 + +.SH See also + + simd_size obtains the number of elements of a given element type and + (parallelism TS v2) ABI tag + \fI(class template)\fP + size returns the width / number of elements + \fB[static]\fP (parallelism TS \fI\fI(public static member\fP function of\fP + v2) std::experimental::simd) diff --git a/man/std::experimental::simd_size.3 b/man/std::experimental::simd_size.3 new file mode 100644 index 000000000..958f8eadb --- /dev/null +++ b/man/std::experimental::simd_size.3 @@ -0,0 +1,52 @@ +.TH std::experimental::simd_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::simd_size \- std::experimental::simd_size + +.SH Synopsis + Defined in header + template< class T, class Abi = simd_abi::compatible > (parallelism TS v2) + struct simd_size; + + If T is a vectorizable type and is_abi_tag_v is true, provides the member + constant value equal to the width (number of elements) of simd, irrespective + of whether simd is supported or not. For any other types T and Abi, there is + no member value. + + If the program adds specializations for std::simd_size + or std::simd_size_v + \fI(since C++17)\fP, the behavior is undefined. + +.SH Member constants + + value the width of simd + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator std::size_t converts the object to std::size_t, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type std::size_t + type std::integral_constant + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + size returns the width / number of elements + \fB[static]\fP (parallelism TS \fI\fI(public static member\fP function of\fP + v2) std::experimental::simd) + size returns the width / number of elements + \fB[static]\fP (parallelism TS \fI\fI(public static member\fP function of\fP + v2) std::experimental::simd_mask) + +.SH Category: + * Todo no example diff --git a/man/std::experimental::source_location.3 b/man/std::experimental::source_location.3 new file mode 100644 index 000000000..002b628a1 --- /dev/null +++ b/man/std::experimental::source_location.3 @@ -0,0 +1,66 @@ +.TH std::experimental::source_location 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location \- std::experimental::source_location + +.SH Synopsis + Defined in header + struct source_location; (library fundamentals TS v2) + + The source_location class represents certain information about the source code, such + as file names, line numbers, and function names. Previously, functions that desire + to obtain this information about the call site (for logging, testing, or debugging + purposes) must use macros so that predefined macros like __LINE__ and __FILE__ are + expanded in the context of the caller. The source_location class provides a better + alternative. + +.SH Member functions + + Creation + constructs a new source_location with implementation-defined + constructor values + \fI(public member function)\fP + current constructs a new source_location + \fB[static]\fP \fI(public static member function)\fP + Other special member functions + destructor destructs a source_location + (implicitly declared) \fI(public member function)\fP + operator= implicitly declared copy/move assignment operators + (implicitly declared) \fI(public member function)\fP + Field access + line return the line number represented by this object + \fI(public member function)\fP + column return the column number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + return the name of the function represented by this object, if + function_name any + \fI(public member function)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + void log(const std::string_view message, + const std::experimental::source_location location = + std::experimental::source_location::current()) + { + std::cout << "info:" + << location.file_name() << ':' + << location.line() << ' ' + << message << '\\n'; + } + + int main() + { + log("Hello world!"); + } + +.SH Possible output: + + info:main.cpp:15 Hello world! diff --git a/man/std::experimental::source_location::column.3 b/man/std::experimental::source_location::column.3 new file mode 100644 index 000000000..f4233d880 --- /dev/null +++ b/man/std::experimental::source_location::column.3 @@ -0,0 +1,59 @@ +.TH std::experimental::source_location::column 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location::column \- std::experimental::source_location::column + +.SH Synopsis + constexpr std::uint_least32_t column() const noexcept; (library fundamentals TS v2) + + Returns an implementation-defined value representing some offset from the start of + the line represented by this object (i.e., the column number). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An implementation-defined value representing some offset from the start of the line + represented by this object (i.e., the column number). + +.SH Example + + +// Run this code + + #include + #include + + template + inline void pos(const T& location = T::current()) + { + std::cout + << "(" + << location.line() + << ':' + << location.column() + << ") "; + } + + int main() + { + pos(); std::cout << "Proxima\\n"; + pos(); std::cout << "Centauri\\n"; + } + +.SH Possible output: + + (17:5) Proxima + (18:5) Centauri + +.SH See also + + line return the line number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + C++ documentation for + Filename and line information diff --git a/man/std::experimental::source_location::current.3 b/man/std::experimental::source_location::current.3 new file mode 100644 index 000000000..a5c460fce --- /dev/null +++ b/man/std::experimental::source_location::current.3 @@ -0,0 +1,37 @@ +.TH std::experimental::source_location::current 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location::current \- std::experimental::source_location::current + +.SH Synopsis + static constexpr source_location current() noexcept; (library fundamentals TS v2) + + Constructs a new source_location object. + +.SH Return value + + If current() is invoked directly (via a function call that names current()), it + returns a source_location object with implementation-defined values representing the + location of the call. The values should be affected by the #line preprocessor + directive in the same manner as the predefined macros __LINE__ and __FILE__. + + If current() is invoked in any other manner, the return value is unspecified. + + Remarks + + If current() is used in an initializer for a non-static data member, the return + value corresponds to the location of the constructor or aggregate initialization + that initializes the data member. + +.SH Notes + + When current() is used in a default argument, the return value will correspond to + the location of the call to current() at the call site. + +.SH Parameters + + \fI(none)\fP + +.SH See also + + constructor constructs a new source_location with implementation-defined values + \fI(public member function)\fP diff --git a/man/std::experimental::source_location::file_name.3 b/man/std::experimental::source_location::file_name.3 new file mode 100644 index 000000000..15fe77533 --- /dev/null +++ b/man/std::experimental::source_location::file_name.3 @@ -0,0 +1,54 @@ +.TH std::experimental::source_location::file_name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location::file_name \- std::experimental::source_location::file_name + +.SH Synopsis + constexpr const char* file_name() const noexcept; (library fundamentals TS v2) + + Returns the name of the current source file represented by this object, represented + as a null-terminated byte string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The name of the current source file represented by this object, represented as a + null-terminated byte string. + +.SH Example + + +// Run this code + + #include + #include + + inline void print_this_file_name( + const std::experimental::source_location& location + = std::experimental::source_location::current()) + { + // Name of file that contains the call-site of this function. + std::cout << "File: " << location.file_name() << '\\n'; + } + + int main() + { + print_this_file_name(); + } + +.SH Possible output: + + File: main.cpp + +.SH See also + + line return the line number represented by this object + \fI(public member function)\fP + column return the column number represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + C++ documentation for + Filename and line information diff --git a/man/std::experimental::source_location::function_name.3 b/man/std::experimental::source_location::function_name.3 new file mode 100644 index 000000000..c2f72efb0 --- /dev/null +++ b/man/std::experimental::source_location::function_name.3 @@ -0,0 +1,85 @@ +.TH std::experimental::source_location::function_name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location::function_name \- std::experimental::source_location::function_name + +.SH Synopsis + constexpr const char* function_name() const noexcept; (library fundamentals TS v2) + + Returns the name of the function associated with the position represented by this + object, if any. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If this object represents a position in a body of a function, returns an + implementation-defined null-terminated byte string corresponding to the name of the + function. + + Otherwise, an empty string is returned. + +.SH Example + + The following example shows how it is possible to use the + std::source_location::function_name() to print a name of a function, constructor, + destructor, or overloaded operator(). + + +// Run this code + + #include + #include + #include + + inline void function_name( + const std::string_view signature = "()", + const std::experimental::source_location& location + = std::experimental::source_location::current()) + { + std::cout + << location.function_name() // <- name of the caller! + << signature + << '\\n'; + } + + void foo() { function_name(); } + + struct S { + S() { function_name(); } + S(int) { function_name("(int)"); } + S& operator=(S const&) { function_name("(const S&)"); return *this; } + S& operator=(S&&) { function_name("(S&&)"); return *this; } + ~S() { function_name(); } + }; + + int main() + { + foo(); + S p; + S q{42}; + p = q; + p = std::move(q); + } + +.SH Possible output: + + foo() + S() + S(int) + operator=(const S&) + operator=(S&&) + ~S() + ~S() + +.SH See also + + line return the line number represented by this object + \fI(public member function)\fP + column return the column number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + C++ documentation for + Filename and line information diff --git a/man/std::experimental::source_location::line.3 b/man/std::experimental::source_location::line.3 new file mode 100644 index 000000000..641a59f56 --- /dev/null +++ b/man/std::experimental::source_location::line.3 @@ -0,0 +1,62 @@ +.TH std::experimental::source_location::line 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location::line \- std::experimental::source_location::line + +.SH Synopsis + constexpr std::uint_least32_t line() const noexcept; (library fundamentals TS v2) + + Returns the line number represented by this object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The line number represented by this object. + +.SH Example + + +// Run this code + + #include + #include + #include + using std::experimental::source_location; + + inline void cur_line( + const std::string_view message = "", + const source_location& location = source_location::current()) + { + std::cout + << location.line() // <- the call-site line # + << ") " + << message; + } + + int main() + { + cur_line("++" "\\n"); + cur_line(); std::cout << "Hello," "\\n"; + cur_line(); std::cout << "C++20!" "\\n"; + cur_line("--" "\\n"); + } + +.SH Output: + + 18) ++ + 19) Hello, + 20) C++20! + 21) -- + +.SH See also + + column return the column number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + C++ documentation for + Filename and line information diff --git a/man/std::experimental::source_location::source_location.3 b/man/std::experimental::source_location::source_location.3 new file mode 100644 index 000000000..60c0f2380 --- /dev/null +++ b/man/std::experimental::source_location::source_location.3 @@ -0,0 +1,22 @@ +.TH std::experimental::source_location::source_location 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::source_location::source_location \- std::experimental::source_location::source_location + +.SH Synopsis + constexpr source_location() noexcept; \fB(1)\fP (library fundamentals TS v2) + source_location( const source_location& other ) = \fB(2)\fP (library fundamentals TS v2) + default; (implicitly declared) + source_location( source_location&& other ) = \fB(3)\fP (library fundamentals TS v2) + default; (implicitly declared) + + 1) Constructs a source_location object whose values are implementation defined. + 2,3) Implicitly declared copy and move constructors. + +.SH Parameters + + other - another source_location to copy from + +.SH See also + + current constructs a new source_location + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::experimental::split,split_by.3 b/man/std::experimental::split,split_by.3 new file mode 100644 index 000000000..7b5b08199 --- /dev/null +++ b/man/std::experimental::split,split_by.3 @@ -0,0 +1,72 @@ +.TH std::experimental::split,split_by 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::split,split_by \- std::experimental::split,split_by + +.SH Synopsis + Defined in header + template< std::size_t... Sizes, class T, class Abi > + + std::tuple>...> \fB(1)\fP (parallelism TS v2) + + split( const simd& v ) noexcept; + template< std::size_t... Sizes, class T, class Abi > + + std::tuple>...> \fB(2)\fP (parallelism TS v2) + + split( const simd_mask& v ) noexcept; + template< class V, class Abi > + + std::array / + V::size()> \fB(3)\fP (parallelism TS v2) + + split( const simd& v ) + noexcept; + template< class V, class Abi > + + std::array / + V::size()> \fB(4)\fP (parallelism TS v2) + + split( const simd_mask& v ) + noexcept; + template< size_t N, class T, class A > + + array / N, simd>, N> \fB(5)\fP (parallelism TS v2) + + split_by( const simd& v ) noexcept; + template< size_t N, class T, class A > + + array / N, simd_mask>, \fB(6)\fP (parallelism TS v2) + N> + + split_by( const simd_mask& v ) noexcept; + + Splits the input simd or simd_mask object into multiple simd or simd_mask objects. + + 1,2) Split the input object into potentially different types (e.g. types with + different sizes) of objects. These functions do not participate in overloading + resolution unless Sizes... sum up to v.size(). + 3,4) Split the input object into an array of objects. These functions do not + participate in overloading resolution unless + * The array element must be of type simd or simd_mask, for the type of v as simd + or simd_mask, respectively. + * simd_size_v is an integral multiple of V::size(). + 5,6) Split the input object into an array of objects. These functions shall not + participate in overload resolution unless simd_size_v is an integral multiple + of N. + +.SH Parameters + + v - the input simd or simd_mask object + +.SH Return value + + 1,2) A tuple that contains the splitted simd or simd_mask objects. + 3-6) An array that contains the splitted simd or simd_mask objects. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::static_pointer_cast,std::experimental::dynamic_pointer_cast,.3 b/man/std::experimental::static_pointer_cast,std::experimental::dynamic_pointer_cast,.3 new file mode 100644 index 000000000..7c1feddf9 --- /dev/null +++ b/man/std::experimental::static_pointer_cast,std::experimental::dynamic_pointer_cast,.3 @@ -0,0 +1,79 @@ +.TH std::experimental::static_pointer_cast,std::experimental::dynamic_pointer_cast, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::static_pointer_cast,std::experimental::dynamic_pointer_cast, \- std::experimental::static_pointer_cast,std::experimental::dynamic_pointer_cast, + +.SH Synopsis + + template< class T, class U > + + std::experimental::shared_ptr \fB(1)\fP (library fundamentals + TS) + static_pointer_cast( const + std::experimental::shared_ptr& r ) noexcept; + template< class T, class U > + + std::experimental::shared_ptr \fB(2)\fP (library fundamentals + TS) + dynamic_pointer_cast( const + std::experimental::shared_ptr& r ) noexcept; + template< class T, class U > + + std::experimental::shared_ptr \fB(3)\fP (library fundamentals + TS) + const_pointer_cast( const + std::experimental::shared_ptr& r ) noexcept; + template< class T, class U > + + std::experimental::shared_ptr \fB(4)\fP (library fundamentals + TS) + reinterpret_pointer_cast( const + std::experimental::shared_ptr& r ) noexcept; + + Creates a new instance of std::experimental::shared_ptr whose stored pointer is + obtained from r's stored pointer using a cast expression. If r is empty, so is the + new shared_ptr (but its stored pointer is not necessarily null). + + Otherwise, the new shared_ptr will share ownership with r, except that it is empty + if the dynamic_cast performed by dynamic_pointer_cast returns a null pointer. + + Let Y be typename std::experimental::shared_ptr::element_type, then the resulting + std::experimental::shared_ptr's stored pointer will be obtained by calling (in + respective order): + + 1) static_cast(r.get()). + 2) dynamic_cast(r.get()) (if the result of the dynamic_cast is a null pointer + value, the returned shared_ptr will be empty). + 3) const_cast(r.get()). + 4) reinterpret_cast(r.get()). + + The behavior of these functions is undefined unless the corresponding cast from U* + to T* is well formed: + + 1) The behavior is undefined unless static_cast((U*)nullptr) is well formed. + 2) The behavior is undefined unless dynamic_cast((U*)nullptr) is well formed. + 3) The behavior is undefined unless const_cast((U*)nullptr) is well formed. + 4) The behavior is undefined unless reinterpret_cast((U*)nullptr) is well + formed. + +.SH Parameters + + r - the pointer to convert + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs new shared_ptr + \fI(public member function)\fP + static_pointer_cast + dynamic_pointer_cast applies static_cast, dynamic_cast, const_cast, or + const_pointer_cast reinterpret_cast to the stored pointer + reinterpret_pointer_cast \fI(function template)\fP + \fI(C++17)\fP + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::string_view::at.3 b/man/std::experimental::string_view::at.3 new file mode 100644 index 000000000..981a7d38e --- /dev/null +++ b/man/std::experimental::string_view::at.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::at \- std::experimental::basic_string_view::at + +.SH Synopsis + constexpr const_reference at(size_type pos) const; (library fundamentals TS) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH See also + + operator[] access specified character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::back.3 b/man/std::experimental::string_view::back.3 new file mode 100644 index 000000000..225d84132 --- /dev/null +++ b/man/std::experimental::string_view::back.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::back \- std::experimental::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; (library fundamentals TS) + + Returns reference to the last character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::basic_string_view.3 b/man/std::experimental::string_view::basic_string_view.3 new file mode 100644 index 000000000..6cb89c751 --- /dev/null +++ b/man/std::experimental::string_view::basic_string_view.3 @@ -0,0 +1,81 @@ +.TH std::experimental::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::basic_string_view \- std::experimental::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP (library fundamentals TS) + constexpr basic_string_view( const basic_string_view& \fB(2)\fP (library fundamentals TS) + other ) noexcept = default; + template + basic_string_view( const std::basic_string& str ) noexcept; + constexpr basic_string_view( const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + count ); + constexpr basic_string_view( const CharT* s ); \fB(5)\fP (library fundamentals TS) + + 1) Default constructor. Constructs an empty basic_string_view. + 2) Copy constructor. Constructs a view of the same content as other. + 3) Constructs a view of the first str.size() characters of the character array + starting with the element pointed by str.data(). + 4) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). + 5) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range (even though the constructor may not access any of the elements of + this range). + +.SH Parameters + + other - another view to initialize the view with + str - a C++ string object to initialize view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + +.SH Exceptions + + 4,5) Throws nothing. + +.SH Complexity + + 1-4) Constant. + 5) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string cppstr = "Foo"; + char array[3] = {'B', 'a', 'r'}; + + std::experimental::string_view cppstr_v(cppstr); + std::experimental::string_view array_v(array, sizeof array); + + std::experimental::wstring_view wcstr_v = L"xyzzy"; + + std::cout << cppstr_v << '\\n' + << array_v << '\\n' + << wcstr_v.size() << '\\n'; + } + +.SH Output: + + Foo + Bar + 5 + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::begin,.3 b/man/std::experimental::string_view::begin,.3 new file mode 100644 index 000000000..a9e63b5a8 --- /dev/null +++ b/man/std::experimental::string_view::begin,.3 @@ -0,0 +1,32 @@ +.TH std::experimental::basic_string_view::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::begin, \- std::experimental::basic_string_view::begin, + +.SH Synopsis + + constexpr const_iterator begin() const noexcept; (library fundamentals TS) + constexpr const_iterator cbegin() const noexcept; (library fundamentals TS) + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::compare.3 b/man/std::experimental::string_view::compare.3 new file mode 100644 index 000000000..338a318c6 --- /dev/null +++ b/man/std::experimental::string_view::compare.3 @@ -0,0 +1,77 @@ +.TH std::experimental::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::compare \- std::experimental::basic_string_view::compare + +.SH Synopsis + constexpr int compare(basic_string_view v) const \fB(1)\fP (library fundamentals TS) + noexcept; + constexpr int compare(size_type pos1, size_type + count1, \fB(2)\fP (library fundamentals TS) + basic_string_view v) const + constexpr int compare(size_type pos1, size_type + count1, basic_string_view v, \fB(3)\fP (library fundamentals TS) + size_type pos2, size_type + count2) const; + constexpr int compare(const CharT* s) const; \fB(4)\fP (library fundamentals TS) + constexpr int compare(size_type pos1, size_type + count1, \fB(5)\fP (library fundamentals TS) + const CharT* s) const; + constexpr int compare(size_type pos1, size_type + count1, \fB(6)\fP (library fundamentals TS) + const CharT* s, size_type + count2) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less <0 + than v + size() < this is less <0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater >0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater >0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH See also + + operator== + operator!= + operator< lexicographically compares two views + operator> \fI(function template)\fP + operator<= + operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::copy.3 b/man/std::experimental::string_view::copy.3 new file mode 100644 index 000000000..b3a99c4ea --- /dev/null +++ b/man/std::experimental::string_view::copy.3 @@ -0,0 +1,39 @@ +.TH std::experimental::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::copy \- std::experimental::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, + + size_type count, (library fundamentals TS) + + size_type pos = 0) const; + + Copies the substring [pos, pos + rcount) to the character string pointed to by dest, + where rcount is the smaller of count and size() - pos. + +.SH Parameters + + dest - pointer to the destination character string + pos - position of the first character + count - requested substring length + +.SH Return value + + Number of characters copied + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH See also + + substr returns a substring + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::data.3 b/man/std::experimental::string_view::data.3 new file mode 100644 index 000000000..e4fc2d4ff --- /dev/null +++ b/man/std::experimental::string_view::data.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::data \- std::experimental::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; (library fundamentals TS) + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. (n.b. Unlike basic_string::data() and string literals, data() + may return a pointer to a buffer that is not null-terminated. Therefore it is + typically a mistake to pass data() to a routine that takes just a const CharT* and + expects a null-terminated string.) + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::empty.3 b/man/std::experimental::string_view::empty.3 new file mode 100644 index 000000000..d632d1769 --- /dev/null +++ b/man/std::experimental::string_view::empty.3 @@ -0,0 +1,30 @@ +.TH std::experimental::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::empty \- std::experimental::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; (library fundamentals TS) + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::end,.3 b/man/std::experimental::string_view::end,.3 new file mode 100644 index 000000000..3aa72c145 --- /dev/null +++ b/man/std::experimental::string_view::end,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::end, \- std::experimental::basic_string_view::end, + +.SH Synopsis + + constexpr const_iterator end() const noexcept; (library fundamentals TS) + constexpr const_iterator cend() const noexcept; (library fundamentals TS) + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::find.3 b/man/std::experimental::string_view::find.3 new file mode 100644 index 000000000..2013b2b4c --- /dev/null +++ b/man/std::experimental::string_view::find.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find \- std::experimental::basic_string_view::find + +.SH Synopsis + constexpr size_type find(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = 0) const noexcept; + constexpr size_type find(CharT c, size_type pos = 0) \fB(2)\fP (library fundamentals TS) + const noexcept; + constexpr size_type find(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type find(const CharT* s, size_type pos \fB(4)\fP (library fundamentals TS) + = 0) const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(&c, 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::find_first_not_of.3 b/man/std::experimental::string_view::find_first_not_of.3 new file mode 100644 index 000000000..5005621e5 --- /dev/null +++ b/man/std::experimental::string_view::find_first_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_not_of \- std::experimental::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_first_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + 0) const noexcept; + constexpr size_type (library fundamentals + find_first_not_of(CharT c, size_type pos = 0) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos = 0) \fB(4)\fP TS) + const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::find_first_of.3 b/man/std::experimental::string_view::find_first_of.3 new file mode 100644 index 000000000..be72db3a5 --- /dev/null +++ b/man/std::experimental::string_view::find_first_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_of \- std::experimental::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type find_first_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = 0) const noexcept; TS) + constexpr size_type find_first_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + 0) const noexcept; TS) + constexpr size_type find_first_of(const CharT* s, \fB(3)\fP (library fundamentals + size_type pos, size_type count) const; TS) + constexpr size_type find_first_of(const CharT* s, \fB(4)\fP (library fundamentals + size_type pos = 0) const; TS) + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_first_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::find_last_not_of.3 b/man/std::experimental::string_view::find_last_not_of.3 new file mode 100644 index 000000000..48128b2ee --- /dev/null +++ b/man/std::experimental::string_view::find_last_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_not_of \- std::experimental::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_last_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + npos) const noexcept; + constexpr size_type (library fundamentals + find_last_not_of(CharT c, size_type pos = npos) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos = npos) \fB(4)\fP TS) + const; + + Finds the last character not equal to any of the characters in the given character + sequence. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::find_last_of.3 b/man/std::experimental::string_view::find_last_of.3 new file mode 100644 index 000000000..30d0a0127 --- /dev/null +++ b/man/std::experimental::string_view::find_last_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_of \- std::experimental::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type find_last_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = npos) const noexcept; TS) + constexpr size_type find_last_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + npos) const noexcept; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(3)\fP (library fundamentals + pos, size_type count) const; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(4)\fP (library fundamentals + pos = npos) const; TS) + + Finds the last character equal to any of the characters in the given character + sequence. + + 1) Finds the last occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_last_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::front.3 b/man/std::experimental::string_view::front.3 new file mode 100644 index 000000000..1cc047f8c --- /dev/null +++ b/man/std::experimental::string_view::front.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::front \- std::experimental::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; (library fundamentals TS) + + Returns reference to the first character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH See also + + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::max_size.3 b/man/std::experimental::string_view::max_size.3 new file mode 100644 index 000000000..113ef28f1 --- /dev/null +++ b/man/std::experimental::string_view::max_size.3 @@ -0,0 +1,31 @@ +.TH std::experimental::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::max_size \- std::experimental::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; (library fundamentals TS) + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::npos.3 b/man/std::experimental::string_view::npos.3 new file mode 100644 index 000000000..b1fc5ec8f --- /dev/null +++ b/man/std::experimental::string_view::npos.3 @@ -0,0 +1,14 @@ +.TH std::experimental::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::npos \- std::experimental::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); (library fundamentals TS) + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::operator=.3 b/man/std::experimental::string_view::operator=.3 new file mode 100644 index 000000000..86f334c8d --- /dev/null +++ b/man/std::experimental::string_view::operator=.3 @@ -0,0 +1,47 @@ +.TH std::experimental::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator= \- std::experimental::basic_string_view::operator= + +.SH Synopsis + basic_string_view& operator=( const basic_string_view& (library fundamentals TS) + view ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::experimental::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::operator[].3 b/man/std::experimental::string_view::operator[].3 new file mode 100644 index 000000000..7d32e4ff5 --- /dev/null +++ b/man/std::experimental::string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::experimental::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator[] \- std::experimental::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[](size_type pos) (library fundamentals TS) + const; + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character + +.SH Exceptions + + Does not throw + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = "Exemplar"; + std::experimental::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at access specified character with bounds checking + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::rbegin,.3 b/man/std::experimental::string_view::rbegin,.3 new file mode 100644 index 000000000..5f3041018 --- /dev/null +++ b/man/std::experimental::string_view::rbegin,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rbegin, \- std::experimental::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crbegin() const (library fundamentals TS) + noexcept; + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::remove_prefix.3 b/man/std::experimental::string_view::remove_prefix.3 new file mode 100644 index 000000000..6b4896fca --- /dev/null +++ b/man/std::experimental::string_view::remove_prefix.3 @@ -0,0 +1,51 @@ +.TH std::experimental::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_prefix \- std::experimental::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix(size_type n); (library fundamentals TS) + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = " trim me"; + std::experimental::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::remove_suffix.3 b/man/std::experimental::string_view::remove_suffix.3 new file mode 100644 index 000000000..f1152e212 --- /dev/null +++ b/man/std::experimental::string_view::remove_suffix.3 @@ -0,0 +1,54 @@ +.TH std::experimental::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_suffix \- std::experimental::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); (library fundamentals TS) + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::experimental::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::rend,.3 b/man/std::experimental::string_view::rend,.3 new file mode 100644 index 000000000..e8bb706e2 --- /dev/null +++ b/man/std::experimental::string_view::rend,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rend, \- std::experimental::basic_string_view::rend, + +.SH Synopsis + + constexpr const_reverse_iterator rend() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crend() const noexcept; (library fundamentals TS) + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::rfind.3 b/man/std::experimental::string_view::rfind.3 new file mode 100644 index 000000000..e6512905c --- /dev/null +++ b/man/std::experimental::string_view::rfind.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rfind \- std::experimental::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = npos) const noexcept; + constexpr size_type rfind(CharT c, size_type pos = \fB(2)\fP (library fundamentals TS) + npos) const noexcept; + constexpr size_type rfind(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type rfind(const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + pos = npos) const; + + Finds the last substring equal to the given character sequence. + + 1) Finds the last occurence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(&c, 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::size,.3 b/man/std::experimental::string_view::size,.3 new file mode 100644 index 000000000..d7e0c24ba --- /dev/null +++ b/man/std::experimental::string_view::size,.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::size, \- std::experimental::basic_string_view::size, + +.SH Synopsis + + constexpr size_type size() const noexcept; (library fundamentals TS) + constexpr size_type length() const noexcept; (library fundamentals TS) + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::substr.3 b/man/std::experimental::string_view::substr.3 new file mode 100644 index 000000000..ac0ecbb2e --- /dev/null +++ b/man/std::experimental::string_view::substr.3 @@ -0,0 +1,37 @@ +.TH std::experimental::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::substr \- std::experimental::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view + substr(size_type pos = 0, size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rcount), where rcount is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rcount). + +.SH Exceptions + + std::out_of_range if pos > size() + +.SH Complexity + + Constant. + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::swap.3 b/man/std::experimental::string_view::swap.3 new file mode 100644 index 000000000..a183aebcd --- /dev/null +++ b/man/std::experimental::string_view::swap.3 @@ -0,0 +1,23 @@ +.TH std::experimental::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::swap \- std::experimental::basic_string_view::swap + +.SH Synopsis + constexpr void swap(basic_string_view& v) noexcept; (library fundamentals TS) + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::string_view::to_string,.3 b/man/std::experimental::string_view::to_string,.3 new file mode 100644 index 000000000..7f51adeb3 --- /dev/null +++ b/man/std::experimental::string_view::to_string,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::to_string, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::to_string, \- std::experimental::basic_string_view::to_string, + +.SH Synopsis + + template> + + basic_string (library fundamentals TS) + + to_string(const Allocator& a = Allocator()) const; + template + explicit operator basic_string() const; + + Creates a basic_string with a copy of the content of the current view. + +.SH Template parameters + + Allocator - Allocator type used to allocate internal storage + +.SH Parameters + + a - Allocator instance to use for allocating the new string + +.SH Return value + + A basic_string containing a copy of the characters of the current view. + +.SH Complexity + + Linear in size() + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::swap(std::experimental::any).3 b/man/std::experimental::swap(std::experimental::any).3 new file mode 100644 index 000000000..778bcf469 --- /dev/null +++ b/man/std::experimental::swap(std::experimental::any).3 @@ -0,0 +1,24 @@ +.TH std::experimental::swap(std::experimental::any) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::any) \- std::experimental::swap(std::experimental::any) + +.SH Synopsis + void swap(any& lhs, any& rhs) noexcept; (library fundamentals TS) + + Swaps the content of two any objects. Calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - objects to swap + +.SH Return value + + \fI(none)\fP + +.SH See also + + swap swaps two any objects + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::swap(std::experimental::function).3 b/man/std::experimental::swap(std::experimental::function).3 new file mode 100644 index 000000000..eb69a2756 --- /dev/null +++ b/man/std::experimental::swap(std::experimental::function).3 @@ -0,0 +1,38 @@ +.TH std::experimental::swap(std::experimental::function) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::function) \- std::experimental::swap(std::experimental::function) + +.SH Synopsis + template< class R, class... Args > + + void swap( std::experimental::function &lhs, + + std::experimental::function &rhs ); + + Overloads the swap algorithm for std::experimental::function. Exchanges the state of + lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - polymorphic function wrappers whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps the contents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::swap(std::experimental::observer_ptr).3 b/man/std::experimental::swap(std::experimental::observer_ptr).3 new file mode 100644 index 000000000..033847289 --- /dev/null +++ b/man/std::experimental::swap(std::experimental::observer_ptr).3 @@ -0,0 +1,30 @@ +.TH std::experimental::swap(std::experimental::observer_ptr) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::observer_ptr) \- std::experimental::swap(std::experimental::observer_ptr) + +.SH Synopsis + template< class W > + void swap( observer_ptr& lhs, observer_ptr& rhs (library fundamentals TS v2) + ) noexcept; + + Specializes the swap algorithm for std::experimental::observer_ptr. Swaps the + pointers of lhs and rhs. Calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - observer_ptrs whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap swaps the watched objects + \fI(public member function)\fP diff --git a/man/std::experimental::swap(std::experimental::optional).3 b/man/std::experimental::swap(std::experimental::optional).3 new file mode 100644 index 000000000..bda1e139c --- /dev/null +++ b/man/std::experimental::swap(std::experimental::optional).3 @@ -0,0 +1,40 @@ +.TH std::experimental::swap(std::experimental::optional) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::optional) \- std::experimental::swap(std::experimental::optional) + +.SH Synopsis + Defined in header + template< class T > + void swap( optional& lhs, optional& rhs ) (library fundamentals TS) + noexcept(/* see below */); + + Overloads the std::swap algorithm for std::experimental::optional. Exchanges the + state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - optional objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap exchanges the contents + \fI(public member function)\fP + +.SH Categories: + * Noindexed pages + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::swap(std::experimental::packaged_task).3 b/man/std::experimental::swap(std::experimental::packaged_task).3 new file mode 100644 index 000000000..ed2cbf5e7 --- /dev/null +++ b/man/std::experimental::swap(std::experimental::packaged_task).3 @@ -0,0 +1,34 @@ +.TH std::experimental::swap(std::experimental::packaged_task) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::packaged_task) \- std::experimental::swap(std::experimental::packaged_task) + +.SH Synopsis + template< class R, class... Args > + + void swap( std::experimental::packaged_task &lhs, + + std::experimental::packaged_task &rhs ) noexcept; + + Overloads the swap algorithm for std::experimental::packaged_task. Exchanges the + state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - packaged_tasks whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two task objects + \fI(public member function of std::packaged_task)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::swap(std::experimental::promise).3 b/man/std::experimental::swap(std::experimental::promise).3 new file mode 100644 index 000000000..5f012a501 --- /dev/null +++ b/man/std::experimental::swap(std::experimental::promise).3 @@ -0,0 +1,34 @@ +.TH std::experimental::swap(std::experimental::promise) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::promise) \- std::experimental::swap(std::experimental::promise) + +.SH Synopsis + template< class R > + + void swap( std::experimental::promise &lhs, + + std::experimental::promise &rhs ) noexcept; + + Overloads the swap algorithm for std::experimental::promise. Exchanges the state of + lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - promises whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two promise objects + \fI(public member function of std::promise)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::swap(std::experimental::propagate_const).3 b/man/std::experimental::swap(std::experimental::propagate_const).3 new file mode 100644 index 000000000..79d98db5f --- /dev/null +++ b/man/std::experimental::swap(std::experimental::propagate_const).3 @@ -0,0 +1,45 @@ +.TH std::experimental::swap(std::experimental::propagate_const) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::swap(std::experimental::propagate_const) \- std::experimental::swap(std::experimental::propagate_const) + +.SH Synopsis + template< class T > + + constexpr void swap( std::experimental::propagate_const& (library fundamentals + lhs, TS v2) + + std::experimental::propagate_const& + rhs ) noexcept(/* see below */); + + Specializes the swap algorithm for std::experimental::propagate_const. Swaps the + pointers of lhs and rhs. Equivalent to lhs.swap(rhs). + + This overload participates in overload resolution only (library fundamentals TS v3) + if std::is_swappable_v is true. + +.SH Parameters + + lhs, rhs - propagate_consts whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(lhs.swap(rhs))) + +.SH Complexity + + Constant. + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap swaps the wrapped pointer + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::experimental::to_array.3 b/man/std::experimental::to_array.3 new file mode 100644 index 000000000..20c670904 --- /dev/null +++ b/man/std::experimental::to_array.3 @@ -0,0 +1,74 @@ +.TH std::experimental::to_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::to_array \- std::experimental::to_array + +.SH Synopsis + Defined in header + template< class T, std::size_t N > (library fundamentals TS + constexpr std::array, N> to_array(T v2) + (&a)[N]); + + Creates a std::array from the built-in array a. The elements of the std::array are + copy-initialized from the corresponding element of a. + +.SH Parameters + + a - the built-in array to be used to initialize the std::array + +.SH Return value + + An std::array object whose elements are copy-initialized from the corresponding + element of a. + +.SH Possible implementation + + namespace detail + { + template + constexpr std::array, N> + to_array_impl(T (&a)[N], std::index_sequence) + { + return { {a[I]...} }; + } + } + + template + constexpr std::array, N> to_array(T (&a)[N]) + { + return detail::to_array_impl(a, std::make_index_sequence{}); + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // mkstemp(3) that works + template + int tempfd(char const (&tmpl)[N]) + { + auto s = std::experimental::to_array(tmpl); + int fd = mkstemp(s.data()); + if (fd != -1) + unlink(s.data()); + + return fd; + } + + int main() + { + int fd = tempfd("/tmp/test.XXXXXX"); + int rt = close(fd); + assert(rt == 0); + } + +.SH See also + + make_array creates a std::array object whose size and optionally + (library fundamentals TS v2) element type are deduced from the arguments + \fI(function template)\fP diff --git a/man/std::experimental::to_fixed_size,std::experimental::to_native,.3 b/man/std::experimental::to_fixed_size,std::experimental::to_native,.3 new file mode 100644 index 000000000..aa3e67656 --- /dev/null +++ b/man/std::experimental::to_fixed_size,std::experimental::to_native,.3 @@ -0,0 +1,59 @@ +.TH std::experimental::to_fixed_size,std::experimental::to_native, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::to_fixed_size,std::experimental::to_native, \- std::experimental::to_fixed_size,std::experimental::to_native, + +.SH Synopsis + + Defined in header + template< class T, class Abi > + + fixed_size_simd> \fB(1)\fP (parallelism TS v2) + + to_fixed_size( const simd& v ) noexcept; + template< class T, class Abi > + + fixed_size_simd_mask> \fB(2)\fP (parallelism TS v2) + + to_fixed_size( const simd_mask& v ) noexcept; + template< class T, std::size_t N > + + native_simd \fB(3)\fP (parallelism TS v2) + + to_native( const fixed_size_simd& v ) noexcept; + template< class T, std::size_t N > + + native_simd_mask \fB(4)\fP (parallelism TS v2) + + to_native( const fixed_size_simd_mask>& v ) noexcept; + template< class T, std::size_t N > + + simd \fB(5)\fP (parallelism TS v2) + + to_compatible( const fixed_size_simd& v ) noexcept; + template< class T, std::size_t N > + + simd_mask \fB(6)\fP (parallelism TS v2) + + to_compatible( const fixed_size_simd_mask& v ) + noexcept; + + Returns a simd or simd_mask object with the same elements, but a different ABI. + + 3-6) These functions do not participate in overloading resolution unless N is the + same as the size of the return type. + +.SH Parameters + + v - the input simd or simd_mask object + +.SH Return value + + The simd or simd_mask object with the specified ABI. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::u16string_view::at.3 b/man/std::experimental::u16string_view::at.3 new file mode 100644 index 000000000..981a7d38e --- /dev/null +++ b/man/std::experimental::u16string_view::at.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::at \- std::experimental::basic_string_view::at + +.SH Synopsis + constexpr const_reference at(size_type pos) const; (library fundamentals TS) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH See also + + operator[] access specified character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::back.3 b/man/std::experimental::u16string_view::back.3 new file mode 100644 index 000000000..225d84132 --- /dev/null +++ b/man/std::experimental::u16string_view::back.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::back \- std::experimental::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; (library fundamentals TS) + + Returns reference to the last character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::basic_string_view.3 b/man/std::experimental::u16string_view::basic_string_view.3 new file mode 100644 index 000000000..6cb89c751 --- /dev/null +++ b/man/std::experimental::u16string_view::basic_string_view.3 @@ -0,0 +1,81 @@ +.TH std::experimental::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::basic_string_view \- std::experimental::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP (library fundamentals TS) + constexpr basic_string_view( const basic_string_view& \fB(2)\fP (library fundamentals TS) + other ) noexcept = default; + template + basic_string_view( const std::basic_string& str ) noexcept; + constexpr basic_string_view( const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + count ); + constexpr basic_string_view( const CharT* s ); \fB(5)\fP (library fundamentals TS) + + 1) Default constructor. Constructs an empty basic_string_view. + 2) Copy constructor. Constructs a view of the same content as other. + 3) Constructs a view of the first str.size() characters of the character array + starting with the element pointed by str.data(). + 4) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). + 5) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range (even though the constructor may not access any of the elements of + this range). + +.SH Parameters + + other - another view to initialize the view with + str - a C++ string object to initialize view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + +.SH Exceptions + + 4,5) Throws nothing. + +.SH Complexity + + 1-4) Constant. + 5) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string cppstr = "Foo"; + char array[3] = {'B', 'a', 'r'}; + + std::experimental::string_view cppstr_v(cppstr); + std::experimental::string_view array_v(array, sizeof array); + + std::experimental::wstring_view wcstr_v = L"xyzzy"; + + std::cout << cppstr_v << '\\n' + << array_v << '\\n' + << wcstr_v.size() << '\\n'; + } + +.SH Output: + + Foo + Bar + 5 + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::begin,.3 b/man/std::experimental::u16string_view::begin,.3 new file mode 100644 index 000000000..a9e63b5a8 --- /dev/null +++ b/man/std::experimental::u16string_view::begin,.3 @@ -0,0 +1,32 @@ +.TH std::experimental::basic_string_view::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::begin, \- std::experimental::basic_string_view::begin, + +.SH Synopsis + + constexpr const_iterator begin() const noexcept; (library fundamentals TS) + constexpr const_iterator cbegin() const noexcept; (library fundamentals TS) + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::compare.3 b/man/std::experimental::u16string_view::compare.3 new file mode 100644 index 000000000..338a318c6 --- /dev/null +++ b/man/std::experimental::u16string_view::compare.3 @@ -0,0 +1,77 @@ +.TH std::experimental::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::compare \- std::experimental::basic_string_view::compare + +.SH Synopsis + constexpr int compare(basic_string_view v) const \fB(1)\fP (library fundamentals TS) + noexcept; + constexpr int compare(size_type pos1, size_type + count1, \fB(2)\fP (library fundamentals TS) + basic_string_view v) const + constexpr int compare(size_type pos1, size_type + count1, basic_string_view v, \fB(3)\fP (library fundamentals TS) + size_type pos2, size_type + count2) const; + constexpr int compare(const CharT* s) const; \fB(4)\fP (library fundamentals TS) + constexpr int compare(size_type pos1, size_type + count1, \fB(5)\fP (library fundamentals TS) + const CharT* s) const; + constexpr int compare(size_type pos1, size_type + count1, \fB(6)\fP (library fundamentals TS) + const CharT* s, size_type + count2) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less <0 + than v + size() < this is less <0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater >0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater >0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH See also + + operator== + operator!= + operator< lexicographically compares two views + operator> \fI(function template)\fP + operator<= + operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::copy.3 b/man/std::experimental::u16string_view::copy.3 new file mode 100644 index 000000000..b3a99c4ea --- /dev/null +++ b/man/std::experimental::u16string_view::copy.3 @@ -0,0 +1,39 @@ +.TH std::experimental::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::copy \- std::experimental::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, + + size_type count, (library fundamentals TS) + + size_type pos = 0) const; + + Copies the substring [pos, pos + rcount) to the character string pointed to by dest, + where rcount is the smaller of count and size() - pos. + +.SH Parameters + + dest - pointer to the destination character string + pos - position of the first character + count - requested substring length + +.SH Return value + + Number of characters copied + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH See also + + substr returns a substring + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::data.3 b/man/std::experimental::u16string_view::data.3 new file mode 100644 index 000000000..e4fc2d4ff --- /dev/null +++ b/man/std::experimental::u16string_view::data.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::data \- std::experimental::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; (library fundamentals TS) + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. (n.b. Unlike basic_string::data() and string literals, data() + may return a pointer to a buffer that is not null-terminated. Therefore it is + typically a mistake to pass data() to a routine that takes just a const CharT* and + expects a null-terminated string.) + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::empty.3 b/man/std::experimental::u16string_view::empty.3 new file mode 100644 index 000000000..d632d1769 --- /dev/null +++ b/man/std::experimental::u16string_view::empty.3 @@ -0,0 +1,30 @@ +.TH std::experimental::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::empty \- std::experimental::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; (library fundamentals TS) + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::end,.3 b/man/std::experimental::u16string_view::end,.3 new file mode 100644 index 000000000..3aa72c145 --- /dev/null +++ b/man/std::experimental::u16string_view::end,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::end, \- std::experimental::basic_string_view::end, + +.SH Synopsis + + constexpr const_iterator end() const noexcept; (library fundamentals TS) + constexpr const_iterator cend() const noexcept; (library fundamentals TS) + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::find.3 b/man/std::experimental::u16string_view::find.3 new file mode 100644 index 000000000..2013b2b4c --- /dev/null +++ b/man/std::experimental::u16string_view::find.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find \- std::experimental::basic_string_view::find + +.SH Synopsis + constexpr size_type find(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = 0) const noexcept; + constexpr size_type find(CharT c, size_type pos = 0) \fB(2)\fP (library fundamentals TS) + const noexcept; + constexpr size_type find(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type find(const CharT* s, size_type pos \fB(4)\fP (library fundamentals TS) + = 0) const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(&c, 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::find_first_not_of.3 b/man/std::experimental::u16string_view::find_first_not_of.3 new file mode 100644 index 000000000..5005621e5 --- /dev/null +++ b/man/std::experimental::u16string_view::find_first_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_not_of \- std::experimental::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_first_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + 0) const noexcept; + constexpr size_type (library fundamentals + find_first_not_of(CharT c, size_type pos = 0) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos = 0) \fB(4)\fP TS) + const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::find_first_of.3 b/man/std::experimental::u16string_view::find_first_of.3 new file mode 100644 index 000000000..be72db3a5 --- /dev/null +++ b/man/std::experimental::u16string_view::find_first_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_of \- std::experimental::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type find_first_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = 0) const noexcept; TS) + constexpr size_type find_first_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + 0) const noexcept; TS) + constexpr size_type find_first_of(const CharT* s, \fB(3)\fP (library fundamentals + size_type pos, size_type count) const; TS) + constexpr size_type find_first_of(const CharT* s, \fB(4)\fP (library fundamentals + size_type pos = 0) const; TS) + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_first_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::find_last_not_of.3 b/man/std::experimental::u16string_view::find_last_not_of.3 new file mode 100644 index 000000000..48128b2ee --- /dev/null +++ b/man/std::experimental::u16string_view::find_last_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_not_of \- std::experimental::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_last_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + npos) const noexcept; + constexpr size_type (library fundamentals + find_last_not_of(CharT c, size_type pos = npos) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos = npos) \fB(4)\fP TS) + const; + + Finds the last character not equal to any of the characters in the given character + sequence. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::find_last_of.3 b/man/std::experimental::u16string_view::find_last_of.3 new file mode 100644 index 000000000..30d0a0127 --- /dev/null +++ b/man/std::experimental::u16string_view::find_last_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_of \- std::experimental::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type find_last_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = npos) const noexcept; TS) + constexpr size_type find_last_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + npos) const noexcept; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(3)\fP (library fundamentals + pos, size_type count) const; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(4)\fP (library fundamentals + pos = npos) const; TS) + + Finds the last character equal to any of the characters in the given character + sequence. + + 1) Finds the last occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_last_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::front.3 b/man/std::experimental::u16string_view::front.3 new file mode 100644 index 000000000..1cc047f8c --- /dev/null +++ b/man/std::experimental::u16string_view::front.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::front \- std::experimental::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; (library fundamentals TS) + + Returns reference to the first character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH See also + + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::max_size.3 b/man/std::experimental::u16string_view::max_size.3 new file mode 100644 index 000000000..113ef28f1 --- /dev/null +++ b/man/std::experimental::u16string_view::max_size.3 @@ -0,0 +1,31 @@ +.TH std::experimental::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::max_size \- std::experimental::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; (library fundamentals TS) + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::npos.3 b/man/std::experimental::u16string_view::npos.3 new file mode 100644 index 000000000..b1fc5ec8f --- /dev/null +++ b/man/std::experimental::u16string_view::npos.3 @@ -0,0 +1,14 @@ +.TH std::experimental::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::npos \- std::experimental::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); (library fundamentals TS) + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::operator=.3 b/man/std::experimental::u16string_view::operator=.3 new file mode 100644 index 000000000..86f334c8d --- /dev/null +++ b/man/std::experimental::u16string_view::operator=.3 @@ -0,0 +1,47 @@ +.TH std::experimental::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator= \- std::experimental::basic_string_view::operator= + +.SH Synopsis + basic_string_view& operator=( const basic_string_view& (library fundamentals TS) + view ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::experimental::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::operator[].3 b/man/std::experimental::u16string_view::operator[].3 new file mode 100644 index 000000000..7d32e4ff5 --- /dev/null +++ b/man/std::experimental::u16string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::experimental::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator[] \- std::experimental::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[](size_type pos) (library fundamentals TS) + const; + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character + +.SH Exceptions + + Does not throw + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = "Exemplar"; + std::experimental::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at access specified character with bounds checking + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::rbegin,.3 b/man/std::experimental::u16string_view::rbegin,.3 new file mode 100644 index 000000000..5f3041018 --- /dev/null +++ b/man/std::experimental::u16string_view::rbegin,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rbegin, \- std::experimental::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crbegin() const (library fundamentals TS) + noexcept; + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::remove_prefix.3 b/man/std::experimental::u16string_view::remove_prefix.3 new file mode 100644 index 000000000..6b4896fca --- /dev/null +++ b/man/std::experimental::u16string_view::remove_prefix.3 @@ -0,0 +1,51 @@ +.TH std::experimental::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_prefix \- std::experimental::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix(size_type n); (library fundamentals TS) + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = " trim me"; + std::experimental::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::remove_suffix.3 b/man/std::experimental::u16string_view::remove_suffix.3 new file mode 100644 index 000000000..f1152e212 --- /dev/null +++ b/man/std::experimental::u16string_view::remove_suffix.3 @@ -0,0 +1,54 @@ +.TH std::experimental::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_suffix \- std::experimental::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); (library fundamentals TS) + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::experimental::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::rend,.3 b/man/std::experimental::u16string_view::rend,.3 new file mode 100644 index 000000000..e8bb706e2 --- /dev/null +++ b/man/std::experimental::u16string_view::rend,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rend, \- std::experimental::basic_string_view::rend, + +.SH Synopsis + + constexpr const_reverse_iterator rend() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crend() const noexcept; (library fundamentals TS) + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::rfind.3 b/man/std::experimental::u16string_view::rfind.3 new file mode 100644 index 000000000..e6512905c --- /dev/null +++ b/man/std::experimental::u16string_view::rfind.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rfind \- std::experimental::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = npos) const noexcept; + constexpr size_type rfind(CharT c, size_type pos = \fB(2)\fP (library fundamentals TS) + npos) const noexcept; + constexpr size_type rfind(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type rfind(const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + pos = npos) const; + + Finds the last substring equal to the given character sequence. + + 1) Finds the last occurence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(&c, 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::size,.3 b/man/std::experimental::u16string_view::size,.3 new file mode 100644 index 000000000..d7e0c24ba --- /dev/null +++ b/man/std::experimental::u16string_view::size,.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::size, \- std::experimental::basic_string_view::size, + +.SH Synopsis + + constexpr size_type size() const noexcept; (library fundamentals TS) + constexpr size_type length() const noexcept; (library fundamentals TS) + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::substr.3 b/man/std::experimental::u16string_view::substr.3 new file mode 100644 index 000000000..ac0ecbb2e --- /dev/null +++ b/man/std::experimental::u16string_view::substr.3 @@ -0,0 +1,37 @@ +.TH std::experimental::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::substr \- std::experimental::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view + substr(size_type pos = 0, size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rcount), where rcount is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rcount). + +.SH Exceptions + + std::out_of_range if pos > size() + +.SH Complexity + + Constant. + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::swap.3 b/man/std::experimental::u16string_view::swap.3 new file mode 100644 index 000000000..a183aebcd --- /dev/null +++ b/man/std::experimental::u16string_view::swap.3 @@ -0,0 +1,23 @@ +.TH std::experimental::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::swap \- std::experimental::basic_string_view::swap + +.SH Synopsis + constexpr void swap(basic_string_view& v) noexcept; (library fundamentals TS) + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u16string_view::to_string,.3 b/man/std::experimental::u16string_view::to_string,.3 new file mode 100644 index 000000000..7f51adeb3 --- /dev/null +++ b/man/std::experimental::u16string_view::to_string,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::to_string, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::to_string, \- std::experimental::basic_string_view::to_string, + +.SH Synopsis + + template> + + basic_string (library fundamentals TS) + + to_string(const Allocator& a = Allocator()) const; + template + explicit operator basic_string() const; + + Creates a basic_string with a copy of the content of the current view. + +.SH Template parameters + + Allocator - Allocator type used to allocate internal storage + +.SH Parameters + + a - Allocator instance to use for allocating the new string + +.SH Return value + + A basic_string containing a copy of the characters of the current view. + +.SH Complexity + + Linear in size() + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::at.3 b/man/std::experimental::u32string_view::at.3 new file mode 100644 index 000000000..981a7d38e --- /dev/null +++ b/man/std::experimental::u32string_view::at.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::at \- std::experimental::basic_string_view::at + +.SH Synopsis + constexpr const_reference at(size_type pos) const; (library fundamentals TS) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH See also + + operator[] access specified character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::back.3 b/man/std::experimental::u32string_view::back.3 new file mode 100644 index 000000000..225d84132 --- /dev/null +++ b/man/std::experimental::u32string_view::back.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::back \- std::experimental::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; (library fundamentals TS) + + Returns reference to the last character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::basic_string_view.3 b/man/std::experimental::u32string_view::basic_string_view.3 new file mode 100644 index 000000000..6cb89c751 --- /dev/null +++ b/man/std::experimental::u32string_view::basic_string_view.3 @@ -0,0 +1,81 @@ +.TH std::experimental::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::basic_string_view \- std::experimental::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP (library fundamentals TS) + constexpr basic_string_view( const basic_string_view& \fB(2)\fP (library fundamentals TS) + other ) noexcept = default; + template + basic_string_view( const std::basic_string& str ) noexcept; + constexpr basic_string_view( const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + count ); + constexpr basic_string_view( const CharT* s ); \fB(5)\fP (library fundamentals TS) + + 1) Default constructor. Constructs an empty basic_string_view. + 2) Copy constructor. Constructs a view of the same content as other. + 3) Constructs a view of the first str.size() characters of the character array + starting with the element pointed by str.data(). + 4) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). + 5) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range (even though the constructor may not access any of the elements of + this range). + +.SH Parameters + + other - another view to initialize the view with + str - a C++ string object to initialize view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + +.SH Exceptions + + 4,5) Throws nothing. + +.SH Complexity + + 1-4) Constant. + 5) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string cppstr = "Foo"; + char array[3] = {'B', 'a', 'r'}; + + std::experimental::string_view cppstr_v(cppstr); + std::experimental::string_view array_v(array, sizeof array); + + std::experimental::wstring_view wcstr_v = L"xyzzy"; + + std::cout << cppstr_v << '\\n' + << array_v << '\\n' + << wcstr_v.size() << '\\n'; + } + +.SH Output: + + Foo + Bar + 5 + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::begin,.3 b/man/std::experimental::u32string_view::begin,.3 new file mode 100644 index 000000000..a9e63b5a8 --- /dev/null +++ b/man/std::experimental::u32string_view::begin,.3 @@ -0,0 +1,32 @@ +.TH std::experimental::basic_string_view::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::begin, \- std::experimental::basic_string_view::begin, + +.SH Synopsis + + constexpr const_iterator begin() const noexcept; (library fundamentals TS) + constexpr const_iterator cbegin() const noexcept; (library fundamentals TS) + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::compare.3 b/man/std::experimental::u32string_view::compare.3 new file mode 100644 index 000000000..338a318c6 --- /dev/null +++ b/man/std::experimental::u32string_view::compare.3 @@ -0,0 +1,77 @@ +.TH std::experimental::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::compare \- std::experimental::basic_string_view::compare + +.SH Synopsis + constexpr int compare(basic_string_view v) const \fB(1)\fP (library fundamentals TS) + noexcept; + constexpr int compare(size_type pos1, size_type + count1, \fB(2)\fP (library fundamentals TS) + basic_string_view v) const + constexpr int compare(size_type pos1, size_type + count1, basic_string_view v, \fB(3)\fP (library fundamentals TS) + size_type pos2, size_type + count2) const; + constexpr int compare(const CharT* s) const; \fB(4)\fP (library fundamentals TS) + constexpr int compare(size_type pos1, size_type + count1, \fB(5)\fP (library fundamentals TS) + const CharT* s) const; + constexpr int compare(size_type pos1, size_type + count1, \fB(6)\fP (library fundamentals TS) + const CharT* s, size_type + count2) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less <0 + than v + size() < this is less <0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater >0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater >0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH See also + + operator== + operator!= + operator< lexicographically compares two views + operator> \fI(function template)\fP + operator<= + operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::copy.3 b/man/std::experimental::u32string_view::copy.3 new file mode 100644 index 000000000..b3a99c4ea --- /dev/null +++ b/man/std::experimental::u32string_view::copy.3 @@ -0,0 +1,39 @@ +.TH std::experimental::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::copy \- std::experimental::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, + + size_type count, (library fundamentals TS) + + size_type pos = 0) const; + + Copies the substring [pos, pos + rcount) to the character string pointed to by dest, + where rcount is the smaller of count and size() - pos. + +.SH Parameters + + dest - pointer to the destination character string + pos - position of the first character + count - requested substring length + +.SH Return value + + Number of characters copied + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH See also + + substr returns a substring + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::data.3 b/man/std::experimental::u32string_view::data.3 new file mode 100644 index 000000000..e4fc2d4ff --- /dev/null +++ b/man/std::experimental::u32string_view::data.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::data \- std::experimental::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; (library fundamentals TS) + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. (n.b. Unlike basic_string::data() and string literals, data() + may return a pointer to a buffer that is not null-terminated. Therefore it is + typically a mistake to pass data() to a routine that takes just a const CharT* and + expects a null-terminated string.) + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::empty.3 b/man/std::experimental::u32string_view::empty.3 new file mode 100644 index 000000000..d632d1769 --- /dev/null +++ b/man/std::experimental::u32string_view::empty.3 @@ -0,0 +1,30 @@ +.TH std::experimental::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::empty \- std::experimental::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; (library fundamentals TS) + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::end,.3 b/man/std::experimental::u32string_view::end,.3 new file mode 100644 index 000000000..3aa72c145 --- /dev/null +++ b/man/std::experimental::u32string_view::end,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::end, \- std::experimental::basic_string_view::end, + +.SH Synopsis + + constexpr const_iterator end() const noexcept; (library fundamentals TS) + constexpr const_iterator cend() const noexcept; (library fundamentals TS) + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::find.3 b/man/std::experimental::u32string_view::find.3 new file mode 100644 index 000000000..2013b2b4c --- /dev/null +++ b/man/std::experimental::u32string_view::find.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find \- std::experimental::basic_string_view::find + +.SH Synopsis + constexpr size_type find(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = 0) const noexcept; + constexpr size_type find(CharT c, size_type pos = 0) \fB(2)\fP (library fundamentals TS) + const noexcept; + constexpr size_type find(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type find(const CharT* s, size_type pos \fB(4)\fP (library fundamentals TS) + = 0) const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(&c, 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::find_first_not_of.3 b/man/std::experimental::u32string_view::find_first_not_of.3 new file mode 100644 index 000000000..5005621e5 --- /dev/null +++ b/man/std::experimental::u32string_view::find_first_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_not_of \- std::experimental::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_first_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + 0) const noexcept; + constexpr size_type (library fundamentals + find_first_not_of(CharT c, size_type pos = 0) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos = 0) \fB(4)\fP TS) + const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::find_first_of.3 b/man/std::experimental::u32string_view::find_first_of.3 new file mode 100644 index 000000000..be72db3a5 --- /dev/null +++ b/man/std::experimental::u32string_view::find_first_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_of \- std::experimental::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type find_first_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = 0) const noexcept; TS) + constexpr size_type find_first_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + 0) const noexcept; TS) + constexpr size_type find_first_of(const CharT* s, \fB(3)\fP (library fundamentals + size_type pos, size_type count) const; TS) + constexpr size_type find_first_of(const CharT* s, \fB(4)\fP (library fundamentals + size_type pos = 0) const; TS) + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_first_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::find_last_not_of.3 b/man/std::experimental::u32string_view::find_last_not_of.3 new file mode 100644 index 000000000..48128b2ee --- /dev/null +++ b/man/std::experimental::u32string_view::find_last_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_not_of \- std::experimental::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_last_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + npos) const noexcept; + constexpr size_type (library fundamentals + find_last_not_of(CharT c, size_type pos = npos) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos = npos) \fB(4)\fP TS) + const; + + Finds the last character not equal to any of the characters in the given character + sequence. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::find_last_of.3 b/man/std::experimental::u32string_view::find_last_of.3 new file mode 100644 index 000000000..30d0a0127 --- /dev/null +++ b/man/std::experimental::u32string_view::find_last_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_of \- std::experimental::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type find_last_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = npos) const noexcept; TS) + constexpr size_type find_last_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + npos) const noexcept; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(3)\fP (library fundamentals + pos, size_type count) const; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(4)\fP (library fundamentals + pos = npos) const; TS) + + Finds the last character equal to any of the characters in the given character + sequence. + + 1) Finds the last occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_last_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::front.3 b/man/std::experimental::u32string_view::front.3 new file mode 100644 index 000000000..1cc047f8c --- /dev/null +++ b/man/std::experimental::u32string_view::front.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::front \- std::experimental::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; (library fundamentals TS) + + Returns reference to the first character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH See also + + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::max_size.3 b/man/std::experimental::u32string_view::max_size.3 new file mode 100644 index 000000000..113ef28f1 --- /dev/null +++ b/man/std::experimental::u32string_view::max_size.3 @@ -0,0 +1,31 @@ +.TH std::experimental::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::max_size \- std::experimental::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; (library fundamentals TS) + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::npos.3 b/man/std::experimental::u32string_view::npos.3 new file mode 100644 index 000000000..b1fc5ec8f --- /dev/null +++ b/man/std::experimental::u32string_view::npos.3 @@ -0,0 +1,14 @@ +.TH std::experimental::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::npos \- std::experimental::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); (library fundamentals TS) + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::operator=.3 b/man/std::experimental::u32string_view::operator=.3 new file mode 100644 index 000000000..86f334c8d --- /dev/null +++ b/man/std::experimental::u32string_view::operator=.3 @@ -0,0 +1,47 @@ +.TH std::experimental::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator= \- std::experimental::basic_string_view::operator= + +.SH Synopsis + basic_string_view& operator=( const basic_string_view& (library fundamentals TS) + view ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::experimental::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::operator[].3 b/man/std::experimental::u32string_view::operator[].3 new file mode 100644 index 000000000..7d32e4ff5 --- /dev/null +++ b/man/std::experimental::u32string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::experimental::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator[] \- std::experimental::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[](size_type pos) (library fundamentals TS) + const; + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character + +.SH Exceptions + + Does not throw + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = "Exemplar"; + std::experimental::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at access specified character with bounds checking + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::rbegin,.3 b/man/std::experimental::u32string_view::rbegin,.3 new file mode 100644 index 000000000..5f3041018 --- /dev/null +++ b/man/std::experimental::u32string_view::rbegin,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rbegin, \- std::experimental::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crbegin() const (library fundamentals TS) + noexcept; + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::remove_prefix.3 b/man/std::experimental::u32string_view::remove_prefix.3 new file mode 100644 index 000000000..6b4896fca --- /dev/null +++ b/man/std::experimental::u32string_view::remove_prefix.3 @@ -0,0 +1,51 @@ +.TH std::experimental::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_prefix \- std::experimental::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix(size_type n); (library fundamentals TS) + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = " trim me"; + std::experimental::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::remove_suffix.3 b/man/std::experimental::u32string_view::remove_suffix.3 new file mode 100644 index 000000000..f1152e212 --- /dev/null +++ b/man/std::experimental::u32string_view::remove_suffix.3 @@ -0,0 +1,54 @@ +.TH std::experimental::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_suffix \- std::experimental::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); (library fundamentals TS) + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::experimental::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::rend,.3 b/man/std::experimental::u32string_view::rend,.3 new file mode 100644 index 000000000..e8bb706e2 --- /dev/null +++ b/man/std::experimental::u32string_view::rend,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rend, \- std::experimental::basic_string_view::rend, + +.SH Synopsis + + constexpr const_reverse_iterator rend() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crend() const noexcept; (library fundamentals TS) + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::rfind.3 b/man/std::experimental::u32string_view::rfind.3 new file mode 100644 index 000000000..e6512905c --- /dev/null +++ b/man/std::experimental::u32string_view::rfind.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rfind \- std::experimental::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = npos) const noexcept; + constexpr size_type rfind(CharT c, size_type pos = \fB(2)\fP (library fundamentals TS) + npos) const noexcept; + constexpr size_type rfind(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type rfind(const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + pos = npos) const; + + Finds the last substring equal to the given character sequence. + + 1) Finds the last occurence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(&c, 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::size,.3 b/man/std::experimental::u32string_view::size,.3 new file mode 100644 index 000000000..d7e0c24ba --- /dev/null +++ b/man/std::experimental::u32string_view::size,.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::size, \- std::experimental::basic_string_view::size, + +.SH Synopsis + + constexpr size_type size() const noexcept; (library fundamentals TS) + constexpr size_type length() const noexcept; (library fundamentals TS) + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::substr.3 b/man/std::experimental::u32string_view::substr.3 new file mode 100644 index 000000000..ac0ecbb2e --- /dev/null +++ b/man/std::experimental::u32string_view::substr.3 @@ -0,0 +1,37 @@ +.TH std::experimental::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::substr \- std::experimental::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view + substr(size_type pos = 0, size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rcount), where rcount is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rcount). + +.SH Exceptions + + std::out_of_range if pos > size() + +.SH Complexity + + Constant. + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::swap.3 b/man/std::experimental::u32string_view::swap.3 new file mode 100644 index 000000000..a183aebcd --- /dev/null +++ b/man/std::experimental::u32string_view::swap.3 @@ -0,0 +1,23 @@ +.TH std::experimental::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::swap \- std::experimental::basic_string_view::swap + +.SH Synopsis + constexpr void swap(basic_string_view& v) noexcept; (library fundamentals TS) + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::u32string_view::to_string,.3 b/man/std::experimental::u32string_view::to_string,.3 new file mode 100644 index 000000000..7f51adeb3 --- /dev/null +++ b/man/std::experimental::u32string_view::to_string,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::to_string, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::to_string, \- std::experimental::basic_string_view::to_string, + +.SH Synopsis + + template> + + basic_string (library fundamentals TS) + + to_string(const Allocator& a = Allocator()) const; + template + explicit operator basic_string() const; + + Creates a basic_string with a copy of the content of the current view. + +.SH Template parameters + + Allocator - Allocator type used to allocate internal storage + +.SH Parameters + + a - Allocator instance to use for allocating the new string + +.SH Return value + + A basic_string containing a copy of the characters of the current view. + +.SH Complexity + + Linear in size() + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::unique_resource.3 b/man/std::experimental::unique_resource.3 new file mode 100644 index 000000000..8a479ae5b --- /dev/null +++ b/man/std::experimental::unique_resource.3 @@ -0,0 +1,92 @@ +.TH std::experimental::unique_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource \- std::experimental::unique_resource + +.SH Synopsis + Defined in header + template< class R, class D > (library fundamentals TS v3) + class unique_resource; + + unique_resource is universal RAII wrapper for resource handles that owns and manages + a resource through a handle and disposes of that resource when the unique_resource + is destroyed. + + The resource is disposed of using the deleter of type D when either of the following + happens: + + * the managing unique_resource object is destroyed, + * the managing unique_resource object is assigned from another resource via + operator= or reset(). + + Let type RS be R if R is an object type, or + std::reference_wrapper> otherwise: + + * unique_resource effectively holds a subobject of type RS which is or wraps the + resource handle, a deleter of type D and a bool flag indicating whether the + wrapper is owning the resource. + * For explanatory purpose, the subobject of type RS is called stored resource + handle, and the stored (if R is an object type) or wrapped (if R is a reference + type) R is called underlying resource handle. These two terms are not used by + the LFTS. + +.SH Template parameters + + R - resource handle type + D - deleter type +.SH Type requirements + - + R shall be an object type or an lvalue reference to an object type. Let UnrefR be + std::remove_reference_t, UnrefR shall be MoveConstructible, and if UnrefR is not + CopyConstructible, std::is_nothrow_move_constructible_v shall be true. + - + D shall be a Destructible and MoveConstructible FunctionObject type, and if D is not + CopyConstructible, std::is_nothrow_move_constructible_v shall be true. Given an + lvalue d of type D and an lvalue r of type UnrefR, the expression d(r) shall be + well-formed. + +.SH Member functions + + constructor constructs a new unique_resource + \fI(public member function)\fP + destructor disposes the managed resource if such is present + \fI(public member function)\fP + operator= assigns a unique_resource + \fI(public member function)\fP +.SH Modifiers + release releases the ownership + \fI(public member function)\fP + reset disposes or replaces the managed resource + \fI(public member function)\fP +.SH Observers + get accesses the underlying resource handle + \fI(public member function)\fP + get_deleter accesses the deleter used for disposing of the managed resource + \fI(public member function)\fP + operator* accesses the pointee if the resource handle is a pointer + operator-> \fI(public member function)\fP + +.SH Non-member functions + + make_unique_resource_checked creates a unique_resource, checking invalid value + \fI(function template)\fP + + Deduction guides + +.SH Notes + + Resource handle types satisfying NullablePointer can also be managed by + std::unique_ptr. Unlike unique_ptr, unique_resource does not require + NullablePointer. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + unique_ptr smart pointer with unique object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::unique_resource::get.3 b/man/std::experimental::unique_resource::get.3 new file mode 100644 index 000000000..072e6873e --- /dev/null +++ b/man/std::experimental::unique_resource::get.3 @@ -0,0 +1,31 @@ +.TH std::experimental::unique_resource::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::get \- std::experimental::unique_resource::get + +.SH Synopsis + const R& get() const noexcept; (library fundamentals TS v3) + + Accesses the underlying resource handle. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying resource handle. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the pointee if the resource handle is a pointer + operator-> \fI(public member function)\fP + get returns a pointer to the managed object + \fI(public member function of std::unique_ptr)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::unique_resource::get_deleter.3 b/man/std::experimental::unique_resource::get_deleter.3 new file mode 100644 index 000000000..8c50b921c --- /dev/null +++ b/man/std::experimental::unique_resource::get_deleter.3 @@ -0,0 +1,29 @@ +.TH std::experimental::unique_resource::get_deleter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::get_deleter \- std::experimental::unique_resource::get_deleter + +.SH Synopsis + const D& get_deleter() const noexcept; (library fundamentals TS v3) + + Accesses the deleter object which would be used for disposing the managed resource. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The stored deleter. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get_deleter returns the deleter that is used for destruction of the managed object + \fI(public member function of std::unique_ptr)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::unique_resource::operator*,std::experimental::unique_resource> \fB(1)\fP (library fundamentals TS + operator*() const noexcept; v3) + R operator->() const noexcept; \fB(2)\fP (library fundamentals TS + v3) + + 1) Access the object or function pointed by the underlying resource handle which is + a pointer. This function participates in overload resolution only if + std::is_pointer_v is true and std::is_void_v> is false. + If the resource handle is not pointing to an object or a function, the behavior is + undefined. + 2) Get a copy of the underlying resource handle which is a pointer. This function + participates in overload resolution only if std::is_pointer_v is true. The return + value is typically used to access the pointed object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The object or function pointed by the underlying resource handle. + 2) Copy of the underlying resource handle. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + get accesses the underlying resource handle + \fI(public member function)\fP + operator* dereferences pointer to the managed object + operator-> \fI(public member function of std::unique_ptr)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::unique_resource::operator=.3 b/man/std::experimental::unique_resource::operator=.3 new file mode 100644 index 000000000..1219df9d2 --- /dev/null +++ b/man/std::experimental::unique_resource::operator=.3 @@ -0,0 +1,65 @@ +.TH std::experimental::unique_resource::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::operator= \- std::experimental::unique_resource::operator= + +.SH Synopsis + unique_resource& operator=( unique_resource&& other ) (library fundamentals TS v3) + noexcept(/*see below*/); + + Move assignment operator. Replaces the managed resource and the deleter with + other's. + + Formally, let RS be the type of stored resource handle: + + * First, calls reset() to dispose the currently owned resource, if any. + * Then assigns the stored resource handle and the deleter with other's. std::move + is applied to the stored resource handle or the deleter of other if + std::is_nothrow_move_assignable_v or std::is_nothrow_move_assignable_v is + true respectively. Assignment of the stored resource handle is executed first, + unless std::is_nothrow_move_assignable_v is false and + std::is_nothrow_move_assignable_v is true. + * Finally, sets *this to own the resource if and only if other owned it before + assignment, and other not to own the resource. + + If std::is_nothrow_move_assignable_v is true, RS shall satisfy the + MoveAssignable requirements; otherwise RS shall satisfy the CopyAssignable + requirements. If std::is_nothrow_move_assignable_v is true, D shall satisfy the + MoveAssignable requirements; otherwise D shall satisfy the CopyAssignable + requirements. Failing to satisfy above requirements results in undefined behavior. + +.SH Parameters + + other - resource wrapper from which ownership will be transferred + +.SH Return value + + *this + +.SH Exceptions + + Any exception thrown in copy-assignment. + + noexcept specification: + noexcept(std::is_nothrow_move_assignable_v && + std::is_nothrow_move_assignable_v) + +.SH Notes + + If a copy of a member throws an exception, this mechanism leaves other intact and + *this in the released state. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + reset disposes or replaces the managed resource + \fI(public member function)\fP + operator= assigns the unique_ptr + \fI(public member function of std::unique_ptr)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::unique_resource::release.3 b/man/std::experimental::unique_resource::release.3 new file mode 100644 index 000000000..faade09ae --- /dev/null +++ b/man/std::experimental::unique_resource::release.3 @@ -0,0 +1,34 @@ +.TH std::experimental::unique_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::release \- std::experimental::unique_resource::release + +.SH Synopsis + void release() noexcept; (library fundamentals TS v3) + + Releases the ownership of the managed resource if any. The destructor will not + execute the deleter after the call, unless reset is called later for managing new + resource. + + Unlike std::unique_ptr::release, this function is not required to modify the stored + resource handle. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + release returns a pointer to the managed object and releases the ownership + \fI(public member function of std::unique_ptr)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::unique_resource::reset.3 b/man/std::experimental::unique_resource::reset.3 new file mode 100644 index 000000000..5677424e0 --- /dev/null +++ b/man/std::experimental::unique_resource::reset.3 @@ -0,0 +1,52 @@ +.TH std::experimental::unique_resource::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::reset \- std::experimental::unique_resource::reset + +.SH Synopsis + void reset() noexcept; \fB(1)\fP (library fundamentals TS v3) + template< class RR > \fB(2)\fP (library fundamentals TS v3) + void reset( RR&& r ); + + 1) Disposes the resource by calling the deleter with the underlying resource handle + if the unique_resource owns it. The unique_resource does not own the resource after + the call. + 2) Replaces the resource by calling \fB(1)\fP and then assigns the stored resource handle + with std::forward(r) if std::is_nothrow_assignable_v is true, otherwise + std::as_const(r), where RS is the type of stored resource handle. The + unique_resource owns the resource after the call. + If copy-assignment of the store resource handle throws an exception, calls del_(r), + where del is the deleter object. + This overload participates in overload resolution only if the selected assignment + expression assigning the stored resource handle is well-formed. + The program is ill-formed if del_(r) is ill-formed. + The behavior is undefined if del_(r) results in undefined behavior or throws an + exception. + +.SH Parameters + + r - resource handle for a new resource to manage + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + 2) Any exception thrown in assigning the stored resource handle. + +.SH Notes + + The mechanism ensures no leaking of resources. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + reset replaces the managed object + \fI(public member function of std::unique_ptr)\fP + +.SH Category: + * Todo no example diff --git a/man/std::experimental::unique_resource::unique_resource.3 b/man/std::experimental::unique_resource::unique_resource.3 new file mode 100644 index 000000000..3bed1ae00 --- /dev/null +++ b/man/std::experimental::unique_resource::unique_resource.3 @@ -0,0 +1,97 @@ +.TH std::experimental::unique_resource::unique_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::unique_resource \- std::experimental::unique_resource::unique_resource + +.SH Synopsis + unique_resource(); \fB(1)\fP (library fundamentals TS v3) + template< class RR, class DD > + unique_resource( RR&& r, DD&& d ) noexcept(/*see \fB(2)\fP (library fundamentals TS v3) + below*/) + unique_resource( unique_resource&& other ); \fB(3)\fP (library fundamentals TS v3) + + Follow items are used for explanatory purpose: + + * RS is the type of stored resource handle. + * The expression res_ refers the underlying resource handle. + * del_ refers the deleter object. + 1) Default constructor. Value-initializes the stored resource handle and the + deleter. The constructed unique_resource does not own the resource. + This overload participates in overload resolution only if both + std::is_default_constructible_v and std::is_default_constructible_v are true. + 2) The stored resource handle is initialized with std::forward(r) if + std::is_nothrow_constructible_v is true, otherwise r. If initialization of + the stored resource handle throws an exception, calls d(r). + Then, the deleter is initialized with std::forward

(d) if + std::is_nothrow_constructible_v is true, otherwise d. If initialization of + deleter throws an exception, calls d(res_). + The constructed unique_resource owns the resource. + This overload participates in overload resolution only if all of + std::is_constructible_v, std::is_constructible_v, + std::is_nothrow_constructible_v || std::is_constructible_v and + std::is_nothrow_constructible_v || std::is_constructible_v are true. + The program is ill-formed if any of the expressions d(r), d(res_) and del_(res_) is + ill-formed. + The behavior is undefined if any of the expressions d(r), d(res_) and del_(res_) + results in undefined behavior or throws an exception. + 3) Move constructor. The stored resource handle is initialized from the one of + other, using std::move if std::is_nothrow_move_constructible_v is true. If + initialization of the stored resource handle throws an exception, other is not + modified. + Then, the deleter is initialized with the one of other, using std::move if + std::is_nothrow_move_constructible_v is true. If initialization of the deleter + throws an exception and std::is_nothrow_move_constructible_v is true and other + owns the resource, calls the deleter of other with res_ to dispose the resource, + then calls other.release(). + After construction, the constructed unique_resource owns its resource if and only if + other owned the resource before the construction, and other is set to not own the + resource. + +.SH Parameters + + r - a resource handle + d - a deleter to use to dispose the resource + other - another unique_resource to acquire the ownership from + +.SH Exceptions + + Any exception thrown during initialization of the stored resource handle or the + deleter. + + 2) + noexcept specification: + noexcept(( + + std::is_nothrow_constructible_v || std::is_nothrow_constructible_v + ) && + ( + std::is_nothrow_constructible_v || std::is_nothrow_constructible_v + + )) + 3) + noexcept specification: + noexcept( + + std::is_nothrow_move_constructible_v && + std::is_nothrow_move_constructible_v + + ) + +.SH Notes + + The mechanism of these constructors ensures no leaking of resources. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new unique_ptr + \fI(public member function of std::unique_ptr)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::experimental::unique_resource::~unique_resource.3 b/man/std::experimental::unique_resource::~unique_resource.3 new file mode 100644 index 000000000..1f48ee0fa --- /dev/null +++ b/man/std::experimental::unique_resource::~unique_resource.3 @@ -0,0 +1,17 @@ +.TH std::experimental::unique_resource::~unique_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::unique_resource::~unique_resource \- std::experimental::unique_resource::~unique_resource + +.SH Synopsis + ~unique_resource(); (library fundamentals TS v3) + + Disposes the resource by calling the deleter with the underlying resource handle if + the unique_resource owns it, equivalent to calling reset(). Then destroys the stored + resource handle and the deleter. + +.SH See also + + reset disposes or replaces the managed resource + \fI(public member function)\fP + destructor destructs the managed object if such is present + \fI(public member function of std::unique_ptr)\fP diff --git a/man/std::experimental::vector_aligned_tag,std::experimental::vector_aligned.3 b/man/std::experimental::vector_aligned_tag,std::experimental::vector_aligned.3 new file mode 100644 index 000000000..6134ec046 --- /dev/null +++ b/man/std::experimental::vector_aligned_tag,std::experimental::vector_aligned.3 @@ -0,0 +1,27 @@ +.TH std::experimental::vector_aligned_tag,std::experimental::vector_aligned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::vector_aligned_tag,std::experimental::vector_aligned \- std::experimental::vector_aligned_tag,std::experimental::vector_aligned + +.SH Synopsis + Defined in header + struct vector_aligned_tag {}; (parallelism TS v2) + inline constexpr vector_aligned_tag vector_aligned{}; + + This tag type indicates that the buffer of copy_from and copy_to is aligned to + memory_alignment_v, where the copy operation operates on the simd/simd_mask + type T, and the buffer with element type U. + +.SH Notes + + This tag type allows to implement vector-aligned load and store. + +.SH See also + + element_aligned_tag flag indicating alignment of the load/store address to element + element_aligned alignment + (parallelism TS v2) \fI(class)\fP + overaligned_tag flag indicating alignment of the load/store address to the + overaligned specified alignment + (parallelism TS v2) \fI(class template)\fP + memory_alignment obtains an appropriate alignment for vector_aligned + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::experimental::void_t.3 b/man/std::experimental::void_t.3 new file mode 100644 index 000000000..157f27800 --- /dev/null +++ b/man/std::experimental::void_t.3 @@ -0,0 +1,22 @@ +.TH std::experimental::void_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::void_t \- std::experimental::void_t + +.SH Synopsis + Defined in header + template< class... > (library fundamentals TS v2) + using void_t = void; + + A utility metafunction that maps a sequence of any types to the type void. + +.SH Notes + + This utility metafunction is used in template metaprogramming to detect ill-formed + types in SFINAE context. First voted into C++17 as std::void_t, it was later added + as well to the library fundamentals TS as std::experimental::void_t, because it is a + dependency of the detection idiom and the LFTS v2 is based on C++14. + +.SH See also + + void_t void variadic alias template + \fI(C++17)\fP (alias template) diff --git a/man/std::experimental::weak_ptr.3 b/man/std::experimental::weak_ptr.3 new file mode 100644 index 000000000..987330c1d --- /dev/null +++ b/man/std::experimental::weak_ptr.3 @@ -0,0 +1,65 @@ +.TH std::experimental::weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::weak_ptr \- std::experimental::weak_ptr + +.SH Synopsis + Defined in header + template< class T > class weak_ptr; (library fundamentals TS) + + std::experimental::weak_ptr is a modified version of std::weak_ptr that + interoperates with std::experimental::shared_ptr and has support for arrays. + +.SH Member types + + Member type Definition + element_type std::remove_extent_t + +.SH Member functions + + constructor constructs new weak_ptr + \fI(public member function)\fP + +Members and non-members identical to std::weak_ptr + +.SH Member functions + + The following member functions work with std::experimental::shared_ptr instead of + std::shared_ptr and std::experimental::weak_ptr instead of std::weak_ptr. The + behavior is otherwise identical. + + destructor destroys a weak_ptr + \fI(public member function of std::weak_ptr)\fP + operator= assigns the weak_ptr + \fI(public member function of std::weak_ptr)\fP +.SH Modifiers + reset releases the ownership of the managed object + \fI(public member function of std::weak_ptr)\fP + swap swaps the managed objects + \fI(public member function of std::weak_ptr)\fP +.SH Observers + use_count returns the number of shared_ptr objects that manage the object + \fI(public member function of std::weak_ptr)\fP + expired checks whether the referenced object was already deleted + \fI(public member function of std::weak_ptr)\fP + lock creates a shared_ptr that manages the referenced object + \fI(public member function of std::weak_ptr)\fP + owner_before provides owner-based ordering of weak pointers + \fI(public member function of std::weak_ptr)\fP + +.SH Non-member functions + + This non-member function is declared in the std::experimental namespace, and work + with std::experimental::weak_ptr rather than std::weak_ptr, but otherwise behaves + identically to the corresponding C++14 function. + + std::swap(std::weak_ptr) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::experimental::weak_ptr::weak_ptr.3 b/man/std::experimental::weak_ptr::weak_ptr.3 new file mode 100644 index 000000000..ff9794193 --- /dev/null +++ b/man/std::experimental::weak_ptr::weak_ptr.3 @@ -0,0 +1,60 @@ +.TH std::experimental::weak_ptr::weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::weak_ptr::weak_ptr \- std::experimental::weak_ptr::weak_ptr + +.SH Synopsis + constexpr weak_ptr() noexcept; \fB(1)\fP (library fundamentals + TS) + weak_ptr( const weak_ptr& r ) noexcept; \fB(2)\fP (library fundamentals + TS) + template< class Y > \fB(2)\fP (library fundamentals + weak_ptr( const weak_ptr& r ) noexcept; TS) + template< class Y > (library fundamentals + weak_ptr( const std::experimental::shared_ptr& r ) \fB(2)\fP TS) + noexcept; + weak_ptr( weak_ptr&& r ) noexcept; \fB(3)\fP (library fundamentals + TS) + template< class Y > \fB(3)\fP (library fundamentals + weak_ptr( weak_ptr&& r ) noexcept; TS) + + Constructs a new weak_ptr that potentially shares an object with r. + + 1) Default constructor. Constructs empty weak_ptr. + 2) Constructs new weak_ptr which shares an object managed by r. If r manages no + object, *this manages no object too. The templated overloads don't participate in + overload resolution unless either Y* is implicitly convertible to T*, or Y is the + type "array of N U" for some type U and some number N, and T is the type "array of + unknown bound of (possibly cv-qualified) U". + 3) Move constructors. Moves a weak_ptr instance from r into *this. After this, r is + empty and r.use_count() == 0. The templated overload doesn't participate in overload + resolution unless either Y* is implicitly convertible to T*, or Y is the type "array + of N U" for some type U and some number N, and T is the type "array of unknown bound + of (possibly cv-qualified) U". + +.SH Parameters + + r - a std::experimental::shared_ptr or std::experimental::weak_ptr that will be + viewed by this std::experimental::weak_ptr + +.SH Exceptions + + noexcept specification: + noexcept + + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor creates a new weak_ptr + \fI(public member function of std::weak_ptr)\fP + operator= assigns the weak_ptr + \fI(public member function of std::weak_ptr)\fP + +.SH Categories: + * Noindexed pages + * unconditionally noexcept + * Todo no example diff --git a/man/std::experimental::when_all.3 b/man/std::experimental::when_all.3 new file mode 100644 index 000000000..7033296b9 --- /dev/null +++ b/man/std::experimental::when_all.3 @@ -0,0 +1,53 @@ +.TH std::experimental::when_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::when_all \- std::experimental::when_all + +.SH Synopsis + Defined in header + template< class InputIt > + + auto when_all( InputIt first, InputIt last ) \fB(1)\fP (concurrency TS) + + -> future::value_type>>; + template< class... Futures > + + auto when_all( Futures&&... futures ) \fB(2)\fP (concurrency TS) + + -> future...>>; + + Create a future object that becomes ready when all of the input futures and + shared_futures become ready. The behavior is undefined if any input future or + shared_future is invalid. + + In particular, let Sequence be a std::vector::value_type> for \fB(1)\fP and + std::tuple...> for \fB(2)\fP. This function template creates a + shared state containing Sequence and returns a future referring to the shared state. + Every input future is moved into the corresponding object in the Sequence in the + shared state, and every input shared_future is copied to the corresponding object in + the Sequence in the shared state. The order of the objects in the Sequence matches + the order of arguments. + + 1) This function does not participate in overload resolution unless InputIt's value + type (i.e., typename std::iterator_traits::value_type) is a + std::experimental::future or std::experimental::shared_future. + 2) This function does not participate in overload resolution unless every argument + is either a (possibly cv-qualified) std::experimental::shared_future or a + cv-unqualified std::experimental::future. (Formally, for every type Fn in Futures, + either std::remove_reference_t is std::experimental::future, or + std::decay_t is std::experimental::shared_future.) + + After this call, every input future is no longer valid; every input shared_future + remains valid. + +.SH Return value + + A future referring to the shared state created by the call. The future is always + valid(), and it becomes ready when all of the input futures and shared_futures the + call are ready. + + 1) If the range is empty (i.e., first == last), the returned future contains an + empty vector and is ready immediately. + 2) If there are no arguments supplied, a future> is returned and is + immediately ready. diff --git a/man/std::experimental::when_any.3 b/man/std::experimental::when_any.3 new file mode 100644 index 000000000..69fe82728 --- /dev/null +++ b/man/std::experimental::when_any.3 @@ -0,0 +1,64 @@ +.TH std::experimental::when_any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::when_any \- std::experimental::when_any + +.SH Synopsis + Defined in header + template< class Sequence > + + struct when_any_result { (concurrency + std::size_t index; TS) + Sequence futures; + + }; + template< class InputIt > + + auto when_any( InputIt first, InputIt last ) \fB(1)\fP (concurrency + TS) + -> future::value_type>>>; + template< class... Futures > + + auto when_any( Futures&&... futures ) \fB(2)\fP (concurrency + TS) + -> + future...>>>; + + Create a future object that becomes ready when at least one of the input futures and + shared_futures become ready. The behavior is undefined if any input future or + shared_future is invalid. + + In particular, let Sequence be a std::vector::value_type> for \fB(1)\fP and + std::tuple...> for \fB(2)\fP. This function template creates a + shared state containing when_any_result and returns a future referring to + the shared state. Every input future is moved into the corresponding object in the + futures member of the when_any_result in the shared state, and every input + shared_future is copied to the corresponding object in the futures member of the + when_any_result in the shared state. The order of the objects in the + Sequence matches the order of arguments. + + 1) This function does not participate in overload resolution unless InputIt's value + type (i.e., typename std::iterator_traits::value_type) is a + std::experimental::future or std::experimental::shared_future. + 2) This function does not participate in overload resolution unless every argument + is either a (possibly cv-qualified) std::experimental::shared_future or a + cv-unqualified std::experimental::future. (Formally, for every type Fn in Futures, + either std::remove_reference_t is std::experimental::future, or + std::decay_t is std::experimental::shared_future.) + + After this call, every input future is no longer valid; every input shared_future + remains valid. + +.SH Return value + + A future referring to the shared state created by the call. The future is always + valid(), and it becomes ready when at least one of the input futures and + shared_futures the call are ready. The index member of the when_any_result contains + the position of the ready future or shared_future in the futures member. + + 1) If the range is empty (i.e., first == last), the returned future is ready + immediately; the futures field of the when_any_result is an empty vector, and the + index field is size_t(-1). + 2) If no argument is provided, the returned future is ready immediately; the futures + field of the when_any_result is an empty tuple, and the index field is size_t(-1). diff --git a/man/std::experimental::where.3 b/man/std::experimental::where.3 new file mode 100644 index 000000000..9c1b7d61e --- /dev/null +++ b/man/std::experimental::where.3 @@ -0,0 +1,75 @@ +.TH std::experimental::where 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::where \- std::experimental::where + +.SH Synopsis + Defined in header + template< class T, class Abi > + + where_expression, simd> \fB(1)\fP (parallelism TS v2) + where( const typename simd::mask_type& mask, + + simd& value ) noexcept; + template< class T, class Abi > + + const_where_expression, const simd> \fB(2)\fP (parallelism TS v2) + where( const typename simd::mask_type& mask, + + const simd& value ) noexcept; + template< class T, class Abi > + + where_expression, simd_mask> \fB(3)\fP (parallelism TS v2) + where( const type_identity_t>& mask, + + simd_mask& value ) noexcept; + template< class T, class Abi > + + const_where_expression, const simd_mask> \fB(4)\fP (parallelism TS v2) + where( const type_identity_t>& mask, + + const simd_mask& value ) noexcept; + template< class T > + + where_expression \fB(5)\fP (parallelism TS v2) + + where( /*see below*/ mask, T& value ) noexcept; + template< class T > + + const_where_expression \fB(6)\fP (parallelism TS v2) + + where( /*see below*/ mask, const T& value ) noexcept; + + Constructs a new const_where_expression or where_expression. + + 1-6) Constructs a where_expression from given mask and value parameters. + +.SH Parameters + + 1-4) + + mask - the simd_mask object + value - reference to the simd object that mask applies on + + 5,6) + + mask - the mask of type bool + value - reference to the scalar that mask applies on + +.SH Return value + + The constructed const_where_expression or where_expression. + +.SH Notes + + 5,6) Uses implementation defined type of mask, so that implicit conversions from + other types to bool is disabled. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::experimental::where_expression.3 b/man/std::experimental::where_expression.3 new file mode 100644 index 000000000..0b72f5571 --- /dev/null +++ b/man/std::experimental::where_expression.3 @@ -0,0 +1,83 @@ +.TH std::experimental::where_expression 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::where_expression \- std::experimental::where_expression + +.SH Synopsis + Defined in header + template< class M, class V > (parallelism TS v2) + class where_expression; + + The class template where_expression abstracts the notion of selected elements of a + given lvalue of arithmetic or data-parallel type. Selected elements are the elements + of the lvalue (of type V) for which the corresponding element of the mask (of type + M) is true. Operators applied to objects of type where_expression are applied + only to selected elements. All other elements are left unchanged. + + Use the where function to construct where_expression objects. + +.SH Template parameters + + M - The mask type + V - The value type M applies on + + Valid combinations of (M, V) are: + + * (simd_mask, simd), + * (simd_mask, simd_mask), + * (bool, T). + +.SH Member functions + + operator= assigns to selected positions + \fI(public member function)\fP + operator+= + operator-= + operator*= + operator/= + operator%= compound operators + operator&= \fI(public member function)\fP + operator|= + operator^= + operator<<= + operator>>= + operator++ increment and decrement operators + operator-- \fI(public member function)\fP + copy_from loads from address to selected positions + \fI(public member function)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + namespace stdx = std::experimental; + + void print(auto const& a) + { + for (std::size_t i{}; i != std::size(a); ++i) + std::cout << a[i] << ' '; + std::cout << '\\n'; + } + + template + stdx::simd my_abs(stdx::simd x) + { + where(x < 0, x) = -x; + return x; + } + + int main() + { + const stdx::native_simd a([](int i) { return i - 2; }); + print(a); + const auto b = my_abs(a); + print(b); + } + +.SH Possible output: + + -2 -1 0 1 + 2 1 0 1 diff --git a/man/std::experimental::wstring_view::at.3 b/man/std::experimental::wstring_view::at.3 new file mode 100644 index 000000000..981a7d38e --- /dev/null +++ b/man/std::experimental::wstring_view::at.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::at \- std::experimental::basic_string_view::at + +.SH Synopsis + constexpr const_reference at(size_type pos) const; (library fundamentals TS) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH See also + + operator[] access specified character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::back.3 b/man/std::experimental::wstring_view::back.3 new file mode 100644 index 000000000..225d84132 --- /dev/null +++ b/man/std::experimental::wstring_view::back.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::back \- std::experimental::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; (library fundamentals TS) + + Returns reference to the last character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::basic_string_view.3 b/man/std::experimental::wstring_view::basic_string_view.3 new file mode 100644 index 000000000..6cb89c751 --- /dev/null +++ b/man/std::experimental::wstring_view::basic_string_view.3 @@ -0,0 +1,81 @@ +.TH std::experimental::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::basic_string_view \- std::experimental::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP (library fundamentals TS) + constexpr basic_string_view( const basic_string_view& \fB(2)\fP (library fundamentals TS) + other ) noexcept = default; + template + basic_string_view( const std::basic_string& str ) noexcept; + constexpr basic_string_view( const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + count ); + constexpr basic_string_view( const CharT* s ); \fB(5)\fP (library fundamentals TS) + + 1) Default constructor. Constructs an empty basic_string_view. + 2) Copy constructor. Constructs a view of the same content as other. + 3) Constructs a view of the first str.size() characters of the character array + starting with the element pointed by str.data(). + 4) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). + 5) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range (even though the constructor may not access any of the elements of + this range). + +.SH Parameters + + other - another view to initialize the view with + str - a C++ string object to initialize view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + +.SH Exceptions + + 4,5) Throws nothing. + +.SH Complexity + + 1-4) Constant. + 5) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string cppstr = "Foo"; + char array[3] = {'B', 'a', 'r'}; + + std::experimental::string_view cppstr_v(cppstr); + std::experimental::string_view array_v(array, sizeof array); + + std::experimental::wstring_view wcstr_v = L"xyzzy"; + + std::cout << cppstr_v << '\\n' + << array_v << '\\n' + << wcstr_v.size() << '\\n'; + } + +.SH Output: + + Foo + Bar + 5 + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::begin,.3 b/man/std::experimental::wstring_view::begin,.3 new file mode 100644 index 000000000..a9e63b5a8 --- /dev/null +++ b/man/std::experimental::wstring_view::begin,.3 @@ -0,0 +1,32 @@ +.TH std::experimental::basic_string_view::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::begin, \- std::experimental::basic_string_view::begin, + +.SH Synopsis + + constexpr const_iterator begin() const noexcept; (library fundamentals TS) + constexpr const_iterator cbegin() const noexcept; (library fundamentals TS) + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::compare.3 b/man/std::experimental::wstring_view::compare.3 new file mode 100644 index 000000000..338a318c6 --- /dev/null +++ b/man/std::experimental::wstring_view::compare.3 @@ -0,0 +1,77 @@ +.TH std::experimental::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::compare \- std::experimental::basic_string_view::compare + +.SH Synopsis + constexpr int compare(basic_string_view v) const \fB(1)\fP (library fundamentals TS) + noexcept; + constexpr int compare(size_type pos1, size_type + count1, \fB(2)\fP (library fundamentals TS) + basic_string_view v) const + constexpr int compare(size_type pos1, size_type + count1, basic_string_view v, \fB(3)\fP (library fundamentals TS) + size_type pos2, size_type + count2) const; + constexpr int compare(const CharT* s) const; \fB(4)\fP (library fundamentals TS) + constexpr int compare(size_type pos1, size_type + count1, \fB(5)\fP (library fundamentals TS) + const CharT* s) const; + constexpr int compare(size_type pos1, size_type + count1, \fB(6)\fP (library fundamentals TS) + const CharT* s, size_type + count2) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less <0 + than v + size() < this is less <0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater >0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater >0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH See also + + operator== + operator!= + operator< lexicographically compares two views + operator> \fI(function template)\fP + operator<= + operator>= + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::copy.3 b/man/std::experimental::wstring_view::copy.3 new file mode 100644 index 000000000..b3a99c4ea --- /dev/null +++ b/man/std::experimental::wstring_view::copy.3 @@ -0,0 +1,39 @@ +.TH std::experimental::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::copy \- std::experimental::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, + + size_type count, (library fundamentals TS) + + size_type pos = 0) const; + + Copies the substring [pos, pos + rcount) to the character string pointed to by dest, + where rcount is the smaller of count and size() - pos. + +.SH Parameters + + dest - pointer to the destination character string + pos - position of the first character + count - requested substring length + +.SH Return value + + Number of characters copied + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH See also + + substr returns a substring + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::data.3 b/man/std::experimental::wstring_view::data.3 new file mode 100644 index 000000000..e4fc2d4ff --- /dev/null +++ b/man/std::experimental::wstring_view::data.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::data \- std::experimental::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; (library fundamentals TS) + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. (n.b. Unlike basic_string::data() and string literals, data() + may return a pointer to a buffer that is not null-terminated. Therefore it is + typically a mistake to pass data() to a routine that takes just a const CharT* and + expects a null-terminated string.) + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::empty.3 b/man/std::experimental::wstring_view::empty.3 new file mode 100644 index 000000000..d632d1769 --- /dev/null +++ b/man/std::experimental::wstring_view::empty.3 @@ -0,0 +1,30 @@ +.TH std::experimental::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::empty \- std::experimental::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; (library fundamentals TS) + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::end,.3 b/man/std::experimental::wstring_view::end,.3 new file mode 100644 index 000000000..3aa72c145 --- /dev/null +++ b/man/std::experimental::wstring_view::end,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::end, \- std::experimental::basic_string_view::end, + +.SH Synopsis + + constexpr const_iterator end() const noexcept; (library fundamentals TS) + constexpr const_iterator cend() const noexcept; (library fundamentals TS) + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::find.3 b/man/std::experimental::wstring_view::find.3 new file mode 100644 index 000000000..2013b2b4c --- /dev/null +++ b/man/std::experimental::wstring_view::find.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find \- std::experimental::basic_string_view::find + +.SH Synopsis + constexpr size_type find(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = 0) const noexcept; + constexpr size_type find(CharT c, size_type pos = 0) \fB(2)\fP (library fundamentals TS) + const noexcept; + constexpr size_type find(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type find(const CharT* s, size_type pos \fB(4)\fP (library fundamentals TS) + = 0) const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(&c, 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::find_first_not_of.3 b/man/std::experimental::wstring_view::find_first_not_of.3 new file mode 100644 index 000000000..5005621e5 --- /dev/null +++ b/man/std::experimental::wstring_view::find_first_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_not_of \- std::experimental::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_first_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + 0) const noexcept; + constexpr size_type (library fundamentals + find_first_not_of(CharT c, size_type pos = 0) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_first_not_of(const CharT* s, size_type pos = 0) \fB(4)\fP TS) + const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::find_first_of.3 b/man/std::experimental::wstring_view::find_first_of.3 new file mode 100644 index 000000000..be72db3a5 --- /dev/null +++ b/man/std::experimental::wstring_view::find_first_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_first_of \- std::experimental::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type find_first_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = 0) const noexcept; TS) + constexpr size_type find_first_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + 0) const noexcept; TS) + constexpr size_type find_first_of(const CharT* s, \fB(3)\fP (library fundamentals + size_type pos, size_type count) const; TS) + constexpr size_type find_first_of(const CharT* s, \fB(4)\fP (library fundamentals + size_type pos = 0) const; TS) + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_first_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::find_last_not_of.3 b/man/std::experimental::wstring_view::find_last_not_of.3 new file mode 100644 index 000000000..48128b2ee --- /dev/null +++ b/man/std::experimental::wstring_view::find_last_not_of.3 @@ -0,0 +1,59 @@ +.TH std::experimental::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_not_of \- std::experimental::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type (library fundamentals + find_last_not_of(basic_string_view v, size_type pos = \fB(1)\fP TS) + npos) const noexcept; + constexpr size_type (library fundamentals + find_last_not_of(CharT c, size_type pos = npos) const \fB(2)\fP TS) + noexcept; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos, \fB(3)\fP TS) + size_type count) const; + constexpr size_type (library fundamentals + find_last_not_of(const CharT* s, size_type pos = npos) \fB(4)\fP TS) + const; + + Finds the last character not equal to any of the characters in the given character + sequence. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::find_last_of.3 b/man/std::experimental::wstring_view::find_last_of.3 new file mode 100644 index 000000000..30d0a0127 --- /dev/null +++ b/man/std::experimental::wstring_view::find_last_of.3 @@ -0,0 +1,55 @@ +.TH std::experimental::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::find_last_of \- std::experimental::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type find_last_of(basic_string_view v, \fB(1)\fP (library fundamentals + size_type pos = npos) const noexcept; TS) + constexpr size_type find_last_of(CharT c, size_type pos = \fB(2)\fP (library fundamentals + npos) const noexcept; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(3)\fP (library fundamentals + pos, size_type count) const; TS) + constexpr size_type find_last_of(const CharT* s, size_type \fB(4)\fP (library fundamentals + pos = npos) const; TS) + + Finds the last character equal to any of the characters in the given character + sequence. + + 1) Finds the last occurence of any of the characters of v in this view, starting at + position pos. + 2) Equivalent to find_last_of(basic_string_view(&c, 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::front.3 b/man/std::experimental::wstring_view::front.3 new file mode 100644 index 000000000..1cc047f8c --- /dev/null +++ b/man/std::experimental::wstring_view::front.3 @@ -0,0 +1,28 @@ +.TH std::experimental::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::front \- std::experimental::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; (library fundamentals TS) + + Returns reference to the first character in the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH See also + + back accesses the last character + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::max_size.3 b/man/std::experimental::wstring_view::max_size.3 new file mode 100644 index 000000000..113ef28f1 --- /dev/null +++ b/man/std::experimental::wstring_view::max_size.3 @@ -0,0 +1,31 @@ +.TH std::experimental::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::max_size \- std::experimental::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; (library fundamentals TS) + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::npos.3 b/man/std::experimental::wstring_view::npos.3 new file mode 100644 index 000000000..b1fc5ec8f --- /dev/null +++ b/man/std::experimental::wstring_view::npos.3 @@ -0,0 +1,14 @@ +.TH std::experimental::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::npos \- std::experimental::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); (library fundamentals TS) + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::operator=.3 b/man/std::experimental::wstring_view::operator=.3 new file mode 100644 index 000000000..86f334c8d --- /dev/null +++ b/man/std::experimental::wstring_view::operator=.3 @@ -0,0 +1,47 @@ +.TH std::experimental::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator= \- std::experimental::basic_string_view::operator= + +.SH Synopsis + basic_string_view& operator=( const basic_string_view& (library fundamentals TS) + view ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::experimental::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::operator[].3 b/man/std::experimental::wstring_view::operator[].3 new file mode 100644 index 000000000..7d32e4ff5 --- /dev/null +++ b/man/std::experimental::wstring_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::experimental::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::operator[] \- std::experimental::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[](size_type pos) (library fundamentals TS) + const; + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character + +.SH Exceptions + + Does not throw + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = "Exemplar"; + std::experimental::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at access specified character with bounds checking + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::rbegin,.3 b/man/std::experimental::wstring_view::rbegin,.3 new file mode 100644 index 000000000..5f3041018 --- /dev/null +++ b/man/std::experimental::wstring_view::rbegin,.3 @@ -0,0 +1,34 @@ +.TH std::experimental::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rbegin, \- std::experimental::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crbegin() const (library fundamentals TS) + noexcept; + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character + +.SH Complexity + + Constant + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::remove_prefix.3 b/man/std::experimental::wstring_view::remove_prefix.3 new file mode 100644 index 000000000..6b4896fca --- /dev/null +++ b/man/std::experimental::wstring_view::remove_prefix.3 @@ -0,0 +1,51 @@ +.TH std::experimental::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_prefix \- std::experimental::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix(size_type n); (library fundamentals TS) + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::string str = " trim me"; + std::experimental::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::remove_suffix.3 b/man/std::experimental::wstring_view::remove_suffix.3 new file mode 100644 index 000000000..f1152e212 --- /dev/null +++ b/man/std::experimental::wstring_view::remove_suffix.3 @@ -0,0 +1,54 @@ +.TH std::experimental::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::remove_suffix \- std::experimental::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); (library fundamentals TS) + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::experimental::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::rend,.3 b/man/std::experimental::wstring_view::rend,.3 new file mode 100644 index 000000000..e8bb706e2 --- /dev/null +++ b/man/std::experimental::wstring_view::rend,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rend, \- std::experimental::basic_string_view::rend, + +.SH Synopsis + + constexpr const_reverse_iterator rend() const noexcept; (library fundamentals TS) + constexpr const_reverse_iterator crend() const noexcept; (library fundamentals TS) + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::rfind.3 b/man/std::experimental::wstring_view::rfind.3 new file mode 100644 index 000000000..e6512905c --- /dev/null +++ b/man/std::experimental::wstring_view::rfind.3 @@ -0,0 +1,53 @@ +.TH std::experimental::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::rfind \- std::experimental::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind(basic_string_view v, \fB(1)\fP (library fundamentals TS) + size_type pos = npos) const noexcept; + constexpr size_type rfind(CharT c, size_type pos = \fB(2)\fP (library fundamentals TS) + npos) const noexcept; + constexpr size_type rfind(const CharT* s, size_type \fB(3)\fP (library fundamentals TS) + pos, size_type count) const; + constexpr size_type rfind(const CharT* s, size_type \fB(4)\fP (library fundamentals TS) + pos = npos) const; + + Finds the last substring equal to the given character sequence. + + 1) Finds the last occurence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(&c, 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::size,.3 b/man/std::experimental::wstring_view::size,.3 new file mode 100644 index 000000000..d7e0c24ba --- /dev/null +++ b/man/std::experimental::wstring_view::size,.3 @@ -0,0 +1,33 @@ +.TH std::experimental::basic_string_view::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::size, \- std::experimental::basic_string_view::size, + +.SH Synopsis + + constexpr size_type size() const noexcept; (library fundamentals TS) + constexpr size_type length() const noexcept; (library fundamentals TS) + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::substr.3 b/man/std::experimental::wstring_view::substr.3 new file mode 100644 index 000000000..ac0ecbb2e --- /dev/null +++ b/man/std::experimental::wstring_view::substr.3 @@ -0,0 +1,37 @@ +.TH std::experimental::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::substr \- std::experimental::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view + substr(size_type pos = 0, size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rcount), where rcount is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rcount). + +.SH Exceptions + + std::out_of_range if pos > size() + +.SH Complexity + + Constant. + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::swap.3 b/man/std::experimental::wstring_view::swap.3 new file mode 100644 index 000000000..a183aebcd --- /dev/null +++ b/man/std::experimental::wstring_view::swap.3 @@ -0,0 +1,23 @@ +.TH std::experimental::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::swap \- std::experimental::basic_string_view::swap + +.SH Synopsis + constexpr void swap(basic_string_view& v) noexcept; (library fundamentals TS) + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Category: + * Noindexed pages diff --git a/man/std::experimental::wstring_view::to_string,.3 b/man/std::experimental::wstring_view::to_string,.3 new file mode 100644 index 000000000..7f51adeb3 --- /dev/null +++ b/man/std::experimental::wstring_view::to_string,.3 @@ -0,0 +1,35 @@ +.TH std::experimental::basic_string_view::to_string, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::experimental::basic_string_view::to_string, \- std::experimental::basic_string_view::to_string, + +.SH Synopsis + + template> + + basic_string (library fundamentals TS) + + to_string(const Allocator& a = Allocator()) const; + template + explicit operator basic_string() const; + + Creates a basic_string with a copy of the content of the current view. + +.SH Template parameters + + Allocator - Allocator type used to allocate internal storage + +.SH Parameters + + a - Allocator instance to use for allocating the new string + +.SH Return value + + A basic_string containing a copy of the characters of the current view. + +.SH Complexity + + Linear in size() + +.SH Category: + * Noindexed pages diff --git a/man/std::expint,std::expintf,std::expintl.3 b/man/std::expint,std::expintf,std::expintl.3 new file mode 100644 index 000000000..e8b775264 --- /dev/null +++ b/man/std::expint,std::expintf,std::expintl.3 @@ -0,0 +1,78 @@ +.TH std::expint,std::expintf,std::expintl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expint,std::expintf,std::expintl \- std::expint,std::expintf,std::expintl + +.SH Synopsis + double expint( double arg ); + + double expint( float arg ); + double expint( long double arg ); \fB(1)\fP + float expintf( float arg ); + + long double expintl( long double arg ); + double expint( IntegralType arg ); \fB(2)\fP + + 1) Computes the exponential integral of arg. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, expint is only guaranteed to be available in if + __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least + 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any + standard library headers. + +.SH Parameters + + arg - value of a floating-point or Integral type + +.SH Return value + + If no errors occur, value of the exponential integral of arg, that is -∫∞ + -arg + + e^-t + t + + dt, is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If the argument is ±0, -∞ is returned. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + int main() + { + std::cout << "Ei(0) = " << std::expint(0) << '\\n' + << "Ei(1) = " << std::expint(1) << '\\n' + << "Gompetz constant = " << -std::exp(1) * std::expint(-1) << '\\n'; + } + +.SH Output: + + Ei\fB(0)\fP = -inf + Ei\fB(1)\fP = 1.89512 + Gompetz constant = 0.596347 + +.SH External links + + Weisstein, Eric W. "Exponential Integral." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::expm1,std::expm1f,std::expm1l.3 b/man/std::expm1,std::expm1f,std::expm1l.3 new file mode 100644 index 000000000..f44a3fbe5 --- /dev/null +++ b/man/std::expm1,std::expm1f,std::expm1l.3 @@ -0,0 +1,141 @@ +.TH std::expm1,std::expm1f,std::expm1l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::expm1,std::expm1f,std::expm1l \- std::expm1,std::expm1f,std::expm1l + +.SH Synopsis + Defined in header + float expm1 ( float num ); + + double expm1 ( double num ); (until C++23) + + long double expm1 ( long double num ); + /* floating-point-type */ (since C++23) + expm1 ( /* floating-point-type */ num ); (constexpr since C++26) + float expm1f( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double expm1l( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double expm1 ( Integer num ); + + 1-3) Computes the e (Euler's number, 2.7182818...) raised to the given power num, + minus 1.0. This function is more accurate than the expression std::exp(num) - 1.0 if + num is close to zero. + The library provides overloads of std::expm1 for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur enum + -1 is returned. + + If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is + returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, it is returned, unmodified. + * If the argument is -∞, -1 is returned. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + The functions std::expm1 and std::log1p are useful for financial calculations, for + example, when calculating small daily interest rates: (1+x)n + -1 can be expressed as std::expm1(n * std::log1p(x)). These functions also simplify + writing accurate inverse hyperbolic functions. + + For IEEE-compatible type double, overflow is guaranteed if 709.8 < num. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::expm1(num) has the same effect as std::expm1(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "expm1(1) = " << std::expm1(1) << '\\n' + << "Interest earned in 2 days on $100, compounded daily at 1%\\n" + << " on a 30/360 calendar = " + << 100 * std::expm1(2 * std::log1p(0.01 / 360)) << '\\n' + << "exp(1e-16)-1 = " << std::exp(1e-16) - 1 + << ", but expm1(1e-16) = " << std::expm1(1e-16) << '\\n'; + + // special values + std::cout << "expm1(-0) = " << std::expm1(-0.0) << '\\n' + << "expm1(-Inf) = " << std::expm1(-INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "expm1(710) = " << std::expm1(710) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Possible output: + + expm1\fB(1)\fP = 1.71828 + Interest earned in 2 days on $100, compounded daily at 1% + on a 30/360 calendar = 0.00555563 + exp(1e-16)-1 = 0, but expm1(1e-16) = 1e-16 + expm1(-0) = -0 + expm1(-Inf) = -1 + expm1(710) = inf + errno == ERANGE: Result too large + FE_OVERFLOW raised + +.SH See also + + exp + expf returns e raised to the given power (\\({\\small e^x}\\)e^x) + expl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp2 + exp2f + exp2l returns 2 raised to the given power (\\({\\small 2^x}\\)2^x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log1p + log1pf natural logarithm (to base e) of 1 plus the given number + log1pl (\\({\\small\\ln{(1+x)}}\\)ln(1+x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + expm1 diff --git a/man/std::expm1.3 b/man/std::expm1.3 deleted file mode 100644 index 73332af02..000000000 --- a/man/std::expm1.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::expm1 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float expm1( float arg ); \fI(since C++11)\fP - double expm1( double arg ); \fI(since C++11)\fP - long double expm1( long double arg ); \fI(since C++11)\fP - double expm1( Integral arg ); \fI(since C++11)\fP - - Computes the e (Euler's number, 2.7182818) raised to the given power arg, minus 1. - This function is more accurate than the expression std::exp(arg)-1 if arg is close - to zero. - -.SH Parameters - - arg - value of floating-point or Integral type - -.SH Return value - - earg - -1 - - If the result is too large for the underlying type, range error occurs and HUGE_VAL - is returned. - -.SH See also - - exp returns e raised to the given power (e^x) - \fI(function)\fP - log1p natural logarithm (to base e) of 1 plus the given number - \fI(C++11)\fP \fI(function)\fP - exp2 returns 2 raised to the given power (2^x) - \fI(C++11)\fP \fI(function)\fP - C documentation for - expm1 diff --git a/man/std::exponential_distribution.3 b/man/std::exponential_distribution.3 index 2a75abefa..31ab477ee 100644 --- a/man/std::exponential_distribution.3 +++ b/man/std::exponential_distribution.3 @@ -1,81 +1,99 @@ -.TH std::exponential_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution \- std::exponential_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP class exponential_distribution; - Produces random non-negative floating-point values x, distributed according to - probability density function: + Produces random non-negative floating-point values \\(\\small x\\)x, distributed + according to probability density function: - P(x|λ) = λe-λx + \\(\\small P(x|\\lambda) = \\lambda e^{-\\lambda x}\\)P(x|λ) = λe-λx The value obtained is the time/distance until the next random event if random events - occur at constant rate λ per unit of time/distance. For example, this distribution - describes the time between the clicks of a Geiger counter or the distance between - point mutations in a DNA strand. + occur at constant rate \\(\\small\\lambda\\)λ per unit of time/distance. For example, + this distribution describes the time between the clicks of a Geiger counter or the + distance between point mutations in a DNA strand. + + This is the continuous counterpart of std::geometric_distribution. + + std::exponential_distribution satisfies RandomNumberDistribution. + +.SH Template parameters - This is the continuous counterpart of std::geometric_distribution + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics lambda returns the lambda distribution parameter (rate of events) - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP + +.SH Notes + + Some implementations may occasionally return infinity if RealType is float. This is + LWG issue 2524. .SH Example - + // Run this code - #include #include - #include + #include #include #include + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); - + // if particles decay once per second on average, // how much time, in seconds, until the next one? std::exponential_distribution<> d(1); - + std::map hist; - for(int n=0; n<10000; ++n) { - ++hist[2*d(gen)]; - } - for(auto p : hist) { + for (int n = 0; n != 10000; ++n) + ++hist[2 * d(gen)]; + + for (auto const& [x, y] : hist) std::cout << std::fixed << std::setprecision(1) - << p.first/2.0 << '-' << (p.first+1)/2.0 << - ' ' << std::string(p.second/200, '*') << '\\n'; - } + << x / 2.0 << '-' << (x + 1) / 2.0 << ' ' + << std::string(y / 200, '*') << '\\n'; } .SH Possible output: @@ -91,5 +109,5 @@ .SH External links - Weisstein, Eric W. "Exponential Distribution." From MathWorld--A Wolfram Web + Weisstein, Eric W. "Exponential Distribution." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::exponential_distribution::exponential_distribution.3 b/man/std::exponential_distribution::exponential_distribution.3 index d0875b2b1..964e88655 100644 --- a/man/std::exponential_distribution::exponential_distribution.3 +++ b/man/std::exponential_distribution::exponential_distribution.3 @@ -1,11 +1,16 @@ -.TH std::exponential_distribution::exponential_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::exponential_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::exponential_distribution \- std::exponential_distribution::exponential_distribution + .SH Synopsis - explicit exponential_distribution( RealType lambda = 1.0 ); \fB(1)\fP \fI(since C++11)\fP - explicit exponential_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + exponential_distribution() : exponential_distribution(1.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit exponential_distribution( RealType lambda ); \fB(2)\fP \fI(since C++11)\fP + explicit exponential_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses lambda as the - distribution parameter, the second version uses params as the distribution - parameter. + 2) Uses lambda as the distribution parameter. + 3) Uses params as the distribution parameter. .SH Parameters @@ -15,3 +20,11 @@ .SH Notes Requires that 0 < lambda. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::exponential_distribution::lambda.3 b/man/std::exponential_distribution::lambda.3 index fa1c3cfe2..3438675c2 100644 --- a/man/std::exponential_distribution::lambda.3 +++ b/man/std::exponential_distribution::lambda.3 @@ -1,4 +1,7 @@ -.TH std::exponential_distribution::lambda 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::lambda 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::lambda \- std::exponential_distribution::lambda + .SH Synopsis RealType lambda() const; \fI(since C++11)\fP @@ -11,9 +14,9 @@ .SH Return value - Floating point value identifying the rate of events per unit + Floating point value identifying the rate of events per unit. .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::exponential_distribution::max.3 b/man/std::exponential_distribution::max.3 index e23859282..d5a8438de 100644 --- a/man/std::exponential_distribution::max.3 +++ b/man/std::exponential_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::exponential_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::max \- std::exponential_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::exponential_distribution::min.3 b/man/std::exponential_distribution::min.3 index 9bba371e2..456c99c26 100644 --- a/man/std::exponential_distribution::min.3 +++ b/man/std::exponential_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::exponential_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::min \- std::exponential_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::exponential_distribution::operator().3 b/man/std::exponential_distribution::operator().3 index 97141609e..3f3ab142a 100644 --- a/man/std::exponential_distribution::operator().3 +++ b/man/std::exponential_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::exponential_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::operator() \- std::exponential_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::exponential_distribution::param.3 b/man/std::exponential_distribution::param.3 index d9fabbf63..9d1e72794 100644 --- a/man/std::exponential_distribution::param.3 +++ b/man/std::exponential_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::exponential_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::param \- std::exponential_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::exponential_distribution::reset.3 b/man/std::exponential_distribution::reset.3 index 80da30ffa..43fdd72fb 100644 --- a/man/std::exponential_distribution::reset.3 +++ b/man/std::exponential_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::exponential_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::exponential_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::exponential_distribution::reset \- std::exponential_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::extent.3 b/man/std::extent.3 index 9378c9b60..7550a1aa2 100644 --- a/man/std::extent.3 +++ b/man/std::extent.3 @@ -1,13 +1,20 @@ -.TH std::extent 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extent \- std::extent + .SH Synopsis Defined in header - template< class T, unsigned N = 0> \fI(since C++11)\fP + template< class T, unsigned N = 0 > \fI(since C++11)\fP struct extent; If T is an array type, provides the member constant value equal to the number of - elements along the Nth dimension of the array, if N is in [0, std::rank::value). - For any other type, or if T is array of unknown bound along its first dimension and - N is 0, value is 0. + elements along the N^th dimension of the array, if N is in [0, std::rank::value). + For any other type, or if T is an array of unknown bound along its first dimension + and N is 0, value is 0. + + If the program adds specializations for std::extent + or std::extent_v + \fI(since C++17)\fP, the behavior is undefined. .SH Member constants @@ -18,6 +25,8 @@ operator std::size_t converts the object to std::size_t, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -27,53 +36,67 @@ .SH Possible implementation -template -struct extent : std::integral_constant {}; - -template -struct extent : std::integral_constant {}; - -template -struct extent : std::integral_constant::value> {}; - -template -struct extent : std::integral_constant {}; - -template -struct extent : std::integral_constant::value> {}; + template + struct extent : std::integral_constant {}; + + template + struct extent : std::integral_constant {}; + + template + struct extent : std::extent {}; + + template + struct extent : std::integral_constant {}; + + template + struct extent : std::extent {}; .SH Example - + // Run this code #include #include - + int main() { - std::cout << std::extent::value << '\\n'; - std::cout << std::extent::value << '\\n'; - std::cout << std::extent::value << '\\n'; - std::cout << std::extent::value << '\\n'; - std::cout << std::extent::value << '\\n'; + static_assert( + std::extent_v == 3 && //< default dimension is 0 + std::extent_v == 3 && //< the same as above + std::extent_v == 3 && + std::extent_v == 4 && + std::extent_v == 0 && + std::extent_v == 0 + ); + + const auto ext = std::extent{}; + std::cout << ext << '\\n'; //< implicit conversion to std::size_t + + const int ints[]{1, 2, 3, 4}; + static_assert(std::extent_v == 4); //< array size + + [[maybe_unused]] int ary[][3] = {{1, 2, 3}}; + + // ary[0] is type of reference of 'int[3]', so, extent + // cannot calculate correctly and return 0 + static_assert(std::is_same_v); + static_assert(std::extent_v == 0); + // removing reference will give correct extent value 3 + static_assert(std::extent_v> == 3); } .SH Output: - 3 - 3 - 4 - 0 - 0 + 42 .SH See also is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP rank obtains the number of dimensions of an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_extent removes one extent from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_all_extents removes all extents from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::extents,std::dextents.3 b/man/std::extents,std::dextents.3 new file mode 100644 index 000000000..478307a56 --- /dev/null +++ b/man/std::extents,std::dextents.3 @@ -0,0 +1,93 @@ +.TH std::extents,std::dextents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents,std::dextents \- std::extents,std::dextents + +.SH Synopsis + Defined in header + template< class IndexType, std::size_t... Extents > \fB(1)\fP (since C++23) + class extents; + template< class IndexType, std::size_t Rank > \fB(2)\fP (since C++23) + using dextents = /* see below */ + + 1) Represents a multidimensional index space of rank equal to sizeof...(Extents). + 2) A convenient alias template for an all-dynamic extents. Let d denote + std::dynamic_extent, each specialization of it dextents is + equivalent to extents (i.e. d is repeated a total of + Rank times). + + Each specialization of extents models regular and is TriviallyCopyable. + +.SH Template parameters + + IndexType - the type of each non-dynamic Extents. Shall be a signed or unsigned + integer type. Otherwise, the program is ill-formed + represents extent (size of an integer interval) for each rank index. + Each element of it is either equal to std::dynamic_extent (in this case, + Extents - it represents a dynamic extent and the extent size will be determined + dynamically), or is representable as a value of type IndexType (then it + represents a static extent and the extent size is just the value of it), + or else the program is ill-formed + Rank - denotes the rank of an all-dynamic extents + +.SH Member types + + Member type Definition + index_type IndexType + size_type std::make_unsigned_t + rank_type std::size_t + +.SH Member objects + + Member name Definition + An array of type std::array, + dynamic-extents (private) which stores the size of each dynamic extents. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an extents + \fI(public member function)\fP +.SH Observers + rank returns the static rank of an extents + \fB[static]\fP \fI(public static member function)\fP + rank_dynamic returns the dynamic rank of an extents + \fB[static]\fP \fI(public static member function)\fP + static_extent returns static extent size of an extents at a certain rank index + \fB[static]\fP \fI(public static member function)\fP + returns dynamic extent size of an extents at a certain rank + extent index + \fI(public member function)\fP + Helpers + fwd-prod-of-extents returns the product of extent size in range [0, i) + (exposition-only member function*) + rev-prod-of-extents returns the product of extents size in range [i + 1, rank()) + (exposition-only member function*) + index-cast casts the input into an integer type + (exposition-only member function*) + dynamic-index returns the number of dynamic extents below a certain rank index + (private) (exposition-only member function*) + dynamic-index-inv returns the number r such that in range [0, r + 1) there is + (private) exactly i + 1 dynamic extents for a certain argument i + (exposition-only member function*) + +.SH Non-member functions + + operator== compare underlying extents in each dimension of two extents + (C++23) \fI(function)\fP + + Deduction guides(C++23) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rank obtains the number of dimensions of an array type + \fI(C++11)\fP \fI(class template)\fP + extent obtains the size of an array type along a specified dimension + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::extents::dynamic-index-inv.3 b/man/std::extents::dynamic-index-inv.3 new file mode 100644 index 000000000..ba44c8e2e --- /dev/null +++ b/man/std::extents::dynamic-index-inv.3 @@ -0,0 +1,35 @@ +.TH std::extents::dynamic-index-inv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::dynamic-index-inv \- std::extents::dynamic-index-inv + +.SH Synopsis + private: + + template< class OtherIndexType > (since C++23) + (exposition only*) + static constexpr auto /*dynamic-index-inv*/( rank_type i ) + noexcept; + + Returns the number r such that in range [0, r + 1) there are exactly [0, i + 1) + dynamic extents. If i <= rank_dynamic() is false, the behavior is undefined. + +.SH Parameters + + i - the index + +.SH Return value + + The minimum value of r such that dynamic-index(r + 1) == i + 1 is true. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::extents::dynamic-index.3 b/man/std::extents::dynamic-index.3 new file mode 100644 index 000000000..66bb11548 --- /dev/null +++ b/man/std::extents::dynamic-index.3 @@ -0,0 +1,35 @@ +.TH std::extents::dynamic-index 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::dynamic-index \- std::extents::dynamic-index + +.SH Synopsis + private: + + template< class OtherIndexType > (since C++23) + (exposition only*) + static constexpr auto /*dynamic-index*/( rank_type i ) + noexcept; + + Returns the number of dynamic extents below index i. If i <= rank() is false, the + behavior is undefined. + +.SH Parameters + + i - the index + +.SH Return value + + The number of E[r] with r < i for which E[r] is a dynamic extent. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::extents::extent.3 b/man/std::extents::extent.3 new file mode 100644 index 000000000..a82648171 --- /dev/null +++ b/man/std::extents::extent.3 @@ -0,0 +1,44 @@ +.TH std::extents::extent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::extent \- std::extents::extent + +.SH Synopsis + constexpr index_type extent( rank_type i ) const noexcept; (since C++23) + + Returns dynamic extent size of an extents at a certain rank index. + +.SH Parameters + + i - The rank index to get the extent size of + +.SH Return value + + The dynamic extent size of an extents at a certain rank index. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::extents e1; + std::extents e2(4, 5); + std::cout << e1.extent(0) << ", " << e1.extent(1) << '\\n'; + std::cout << e2.extent(0) << ", " << e2.extent(1) << ", " << e2.extent(2) << '\\n'; + } + +.SH Output: + + 1, 2 + 3, 4, 5 + +.SH See also + + static_extent returns static extent size of an extents at a certain rank index + \fB[static]\fP \fI(public static member function)\fP + extent obtains the size of an array type along a specified dimension + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::extents::extents.3 b/man/std::extents::extents.3 new file mode 100644 index 000000000..4fcf14f44 --- /dev/null +++ b/man/std::extents::extents.3 @@ -0,0 +1,95 @@ +.TH std::extents::extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::extents \- std::extents::extents + +.SH Synopsis + constexpr extents() = default; \fB(1)\fP (since C++23) + template< class OtherIndexType, std::size_t... OtherExtents > + + constexpr explicit(/*see below*/) \fB(2)\fP (since C++23) + + extents( const std::extents& + other ) noexcept; + template< class... OtherIndexTypes > \fB(3)\fP (since C++23) + constexpr explicit extents( OtherIndexTypes... exts ) noexcept; + template< class OtherIndexType, std::size_t N > + + constexpr explicit(N != rank_dynamic()) \fB(4)\fP (since C++23) + + extents( std::span exts ) noexcept; + template< class OtherIndexType, std::size_t N > + + constexpr explicit(N != rank_dynamic()) \fB(5)\fP (since C++23) + + extents( const std::array& exts ) noexcept; + + Construct an extents. One can construct extents from just dynamic extents, which are + all the values getting stored, or from all the extents with a precondition. + + 1) Default constructor. Initializes all dynamic extents to zero. + 2) Conversion from another extents object. After construction, *this == other is + true. + * The behavior is undefined if + + * other.extent(r) != static_extent(r) for any r for which static_extent(r) + represents a static extent, or + * other.extent(r) is not representable as a value of type IndexType for any rank + value r in other. + * This overload participates in overload resolution only if + + * sizeof...(OtherExtents) == rank() is true, and + * ((OtherExtents == std::dynamic_extent || Extents == std::dynamic_extent || + OtherExtents == Extents) && ...) is true. + * This constructor is explicit if + + * ((Extents != std::dynamic_extent && OtherExtents == std::dynamic_extent) || ...) + is true, or + * std::numeric_limits::max() < + std::numeric_limits::max() is true. + 3) Let N be sizeof...(exts) and exts_arr be std::array{static_cast(std::move(exts))...}, equivalent to extents(exts_arr). + * This overload participates in overload resolution only if + + * (std::is_convertible_v && ...) is true, + * (std::is_nothrow_constructible_v && ...) is true, + and + * N == rank_dynamic() || N == rank() is true. + * The behavior is undefined if + + * N != rank_dynamic() and exts_arr[r] is not equal to static_extent(r) for any r + for which static_extent(r) represents a static extent, or + * an element in exts is negative or not representable as a value of type + IndexType. + 4,5) If N equals rank_dynamic(), for all d in [0, rank_dynamic()), + direct-non-list-initializes dynamic-extents[d] with std::as_const(exts[d]). + Otherwise, for all d in [0, rank_dynamic()), direct-non-list-initializes + dynamic-extents[d] with std::as_const(exts[dynamic-index-inv(d)]). + * This overload participates in overload resolution only if + + * std::is_convertible_v is true, + * std::is_nothrow_constructible_v is true, and + * N == rank_dynamic() || N == rank() is true. + * The behavior is undefined if + + * N != rank_dynamic() and exts[r] is not equal to static_extent(r) for any r for + which static_extent(r) represents a static extent, or + * exts[r] is negative or not representable as a value of type IndexType for any + rank index r. + +.SH Parameters + + other - another extents to convert from + exts - represents the extents + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::extents::fwd-prod-of-extents.3 b/man/std::extents::fwd-prod-of-extents.3 new file mode 100644 index 000000000..896908287 --- /dev/null +++ b/man/std::extents::fwd-prod-of-extents.3 @@ -0,0 +1,32 @@ +.TH std::extents::fwd-prod-of-extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::fwd-prod-of-extents \- std::extents::fwd-prod-of-extents + +.SH Synopsis + constexpr std::size_t rank_type /*fwd-prod-of-extents*/( (since C++23) + rank_type i ) const noexcept; (exposition only*) + + Returns the product of the sizes of extents with index less than i. The behavior is + undefined if i <= rank() is false. + +.SH Parameters + + i - The end index of the range of extents to be multiplied together. + +.SH Return value + + If i > 0 is true, return the product of extent(k) for all k in range [0, i), + otherwise 1. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rev-prod-of-extents returns the product of extents size in range [i + 1, rank()) + (exposition-only member function*) + +.SH Category: + * Todo no example diff --git a/man/std::extents::index-cast.3 b/man/std::extents::index-cast.3 new file mode 100644 index 000000000..a951aa758 --- /dev/null +++ b/man/std::extents::index-cast.3 @@ -0,0 +1,39 @@ +.TH std::extents::index-cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::index-cast \- std::extents::index-cast + +.SH Synopsis + template< class OtherIndexType > (since C++23) + static constexpr auto /*index-cast*/( OtherIndexType&& i ) (exposition only*) + noexcept; + + Casts the index i in type OtherIndexType into certain integral type. It is + equivalent to: + + * return i;, if OtherIndexType is an integral type other than bool and + * return static_cast(i); otherwise. + +.SH Parameters + + i - the index to be cast + +.SH Return value + + Cast index. + +.SH Notes + + This section is incomplete + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::extents::rank.3 b/man/std::extents::rank.3 new file mode 100644 index 000000000..90a8373d1 --- /dev/null +++ b/man/std::extents::rank.3 @@ -0,0 +1,42 @@ +.TH std::extents::rank 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::rank \- std::extents::rank + +.SH Synopsis + static constexpr rank_type rank() const noexcept; (since C++23) + + Returns the number of dimensions in extents. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of dimensions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::extents e1; + std::extents e2(5); + std::cout << e1.rank() << ", " << e2.rank() << '\\n'; + } + +.SH Output: + + 2, 3 + +.SH See also + + rank_dynamic returns the dynamic rank of an extents + \fB[static]\fP \fI(public static member function)\fP + rank obtains the number of dimensions of an array type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::extents::rank_dynamic.3 b/man/std::extents::rank_dynamic.3 new file mode 100644 index 000000000..abd5f977a --- /dev/null +++ b/man/std::extents::rank_dynamic.3 @@ -0,0 +1,45 @@ +.TH std::extents::rank_dynamic 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::rank_dynamic \- std::extents::rank_dynamic + +.SH Synopsis + static constexpr rank_type rank_dynamic() const noexcept; (since C++23) + + Returns the number of dynamic dimensions in extents. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of dynamic dimensions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::extents e1; + std::extents e2(5); + std::extents e3(6, 8); + std::cout << e1.rank_dynamic() << ", " + << e2.rank_dynamic() << ", " + << e3.rank_dynamic() << '\\n'; + } + +.SH Output: + + 0, 1, 2 + +.SH See also + + rank returns the static rank of an extents + \fB[static]\fP \fI(public static member function)\fP + rank obtains the number of dimensions of an array type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::extents::rev-prod-of-extents.3 b/man/std::extents::rev-prod-of-extents.3 new file mode 100644 index 000000000..ac41cd3d9 --- /dev/null +++ b/man/std::extents::rev-prod-of-extents.3 @@ -0,0 +1,33 @@ +.TH std::extents::rev-prod-of-extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::rev-prod-of-extents \- std::extents::rev-prod-of-extents + +.SH Synopsis + constexpr std::size_t rank_type /*rev-prod-of-extents*/( (since C++23) + rank_type i ) const noexcept; (exposition only*) + + Returns the product of the sizes of extents with index greater than i. The behavior + is undefined if i < rank() is false. + +.SH Parameters + + i - an index above which the sizes of corresponding extents will be multiplied + together + +.SH Return value + + If i + 1 < rank() is true, return the product of extent(k) for all k in range [i + + 1, rank()), otherwise 1. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + fwd-prod-of-extents returns the product of extent size in range [0, i) + (exposition-only member function*) + +.SH Category: + * Todo no example diff --git a/man/std::extents::static_extent.3 b/man/std::extents::static_extent.3 new file mode 100644 index 000000000..e9a2c5946 --- /dev/null +++ b/man/std::extents::static_extent.3 @@ -0,0 +1,47 @@ +.TH std::extents::static_extent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extents::static_extent \- std::extents::static_extent + +.SH Synopsis + static constexpr std::size_t static_extent( rank_type i ) noexcept; (since C++23) + + Returns static extent size of an extents at the rank index i. If the rank index i is + a dynamic extent, returns std::dynamic_extent. + +.SH Parameters + + i - The rank index to get the static extent size of + +.SH Return value + + The static extent size or std::dynamic_extent value. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::extents e1; + std::extents e2(4, 5); + std::cout << e1.static_extent(0) << ", " << e1.static_extent(1) << '\\n'; + std::cout << (e2.static_extent(0) == std::dynamic_extent) << ", " + << (e2.static_extent(1) == std::dynamic_extent) << ", " + << (e2.static_extent(2) == std::dynamic_extent) << '\\n'; + } + +.SH Output: + + 1, 2 + 0, 1, 1 + +.SH See also + + extent returns dynamic extent size of an extents at a certain rank index + \fI(public member function)\fP + extent obtains the size of an array type along a specified dimension + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::extreme_value_distribution.3 b/man/std::extreme_value_distribution.3 index 0c9fca112..d63123e27 100644 --- a/man/std::extreme_value_distribution.3 +++ b/man/std::extreme_value_distribution.3 @@ -1,14 +1,17 @@ -.TH std::extreme_value_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution \- std::extreme_value_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP class extreme_value_distribution; - The extreme_value_distribution class is a RandomNumberDistribution that produces - random numbers according to the extreme value distribution (it is also known as - Gumbel Type I, log-Weibull, Fisher-Tippett Type I): + Produces random numbers according to the Generalized extreme value distribution (it + is also known as Gumbel Type I, log-Weibull, Fisher-Tippett Type I): - p(x;a,b) = + \\({\\small p(x;a,b) = \\frac{1}{b} \\exp{(\\frac{a-x}{b}-\\exp{(\\frac{a-x}{b})})} + }\\)p(x;a,b) = 1 b @@ -33,60 +36,143 @@ ⎟ ⎠ -.SH Contents - - * 1 Member types - * 2 Member functions + std::extreme_value_distribution satisfies all requirements of + RandomNumberDistribution. - * 2.1 Generation - * 2.2 Characteristics +.SH Template parameters - * 3 Non-member functions - * 4 Example - * 5 External links + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics a returns the distribution parameters b \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + void draw_vbars(Seq&& s, const bool DrawMinMax = true) + { + static_assert(0 < Height and 0 < BarWidth and 0 <= Padding and 0 <= Offset); + + auto cout_n = [](auto&& v, int n = 1) + { + while (n-- > 0) + std::cout << v; + }; + + const auto [min, max] = std::minmax_element(std::cbegin(s), std::cend(s)); + + std::vector qr; + for (typedef decltype(*std::cbegin(s)) V; V e : s) + qr.push_back(std::div(std::lerp(V(0), 8 * Height, + (e - *min) / (*max - *min)), 8)); + + for (auto h{Height}; h-- > 0; cout_n('\\n')) + { + cout_n(' ', Offset); + + for (auto dv : qr) + { + const auto q{dv.quot}, r{dv.rem}; + unsigned char d[]{0xe2, 0x96, 0x88, 0}; // Full Block: '█' + q < h ? d[0] = ' ', d[1] = 0 : q == h ? d[2] -= (7 - r) : 0; + cout_n(d, BarWidth), cout_n(' ', Padding); + } + + if (DrawMinMax && Height > 1) + Height - 1 == h ? std::cout << "┬ " << *max: + h ? std::cout << "│ " + : std::cout << "┴ " << *min; + } + } + + int main() + { + std::random_device rd{}; + std::mt19937 gen{rd()}; + + std::extreme_value_distribution<> d{-1.618f, 1.618f}; + + const int norm = 10'000; + const float cutoff = 0.000'3f; + + std::map hist{}; + for (int n = 0; n != norm; ++n) + ++hist[std::round(d(gen))]; + + std::vector bars; + std::vector indices; + for (const auto& [n, p] : hist) + if (const float x = p * (1.0f / norm); x > cutoff) + { + bars.push_back(x); + indices.push_back(n); + } + + draw_vbars<8,4>(bars); + + for (int n : indices) + std::cout << ' ' << std::setw(2) << n << " "; + std::cout << '\\n'; + } + +.SH Possible output: + + ████ ▅▅▅▅ ┬ 0.2186 + ████ ████ │ + ▁▁▁▁ ████ ████ ▇▇▇▇ │ + ████ ████ ████ ████ │ + ████ ████ ████ ████ ▆▆▆▆ │ + ████ ████ ████ ████ ████ ▁▁▁▁ │ + ▄▄▄▄ ████ ████ ████ ████ ████ ████ ▃▃▃▃ │ + ▁▁▁▁ ████ ████ ████ ████ ████ ████ ████ ████ ▆▆▆▆ ▃▃▃▃ ▂▂▂▂ ▁▁▁▁ ▁▁▁▁ ▁▁▁▁ ▁▁▁▁ ┴ 0.0005 + -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 10 .SH External links - Weisstein, Eric W. "Extreme Value Distribution." From MathWorld--A Wolfram Web + Weisstein, Eric W. "Extreme Value Distribution." From MathWorld — A Wolfram Web Resource. - -.SH Category: - - * Todo no example diff --git a/man/std::extreme_value_distribution::a,b.3 b/man/std::extreme_value_distribution::a,b.3 index 4b2c506fb..721b018fb 100644 --- a/man/std::extreme_value_distribution::a,b.3 +++ b/man/std::extreme_value_distribution::a,b.3 @@ -1,12 +1,15 @@ -.TH std::extreme_value_distribution::a,b 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::a,b 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::a,b \- std::extreme_value_distribution::a,b + .SH Synopsis RealType a() const; \fB(1)\fP \fI(since C++11)\fP RealType b() const; \fB(2)\fP \fI(since C++11)\fP Returns the parameters the distribution was constructed with. - 1) Returns the a distribution parameter (scale). The default value is 1.0. - 2) Returns the b distribution parameter (location). The default value is 0.0. + 1) Returns the a distribution parameter (location). The default value is 1.0. + 2) Returns the b distribution parameter (scale). The default value is 0.0. .SH Parameters @@ -14,10 +17,10 @@ .SH Return value - 1) The a distribution parameter (scale). + 1) The a distribution parameter (location). 2) The b distribution parameter (scale). .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::extreme_value_distribution::extreme_value_distribution.3 b/man/std::extreme_value_distribution::extreme_value_distribution.3 index df08be978..68615f547 100644 --- a/man/std::extreme_value_distribution::extreme_value_distribution.3 +++ b/man/std::extreme_value_distribution::extreme_value_distribution.3 @@ -1,15 +1,28 @@ -.TH std::extreme_value_distribution::extreme_value_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::extreme_value_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::extreme_value_distribution \- std::extreme_value_distribution::extreme_value_distribution + .SH Synopsis - explicit extreme_value_distribution( RealType a = 0.0, RealType b \fB(1)\fP \fI(since C++11)\fP - = 1.0 ); - explicit extreme_value_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + extreme_value_distribution() : extreme_value_distribution(0.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit extreme_value_distribution( RealType a, RealType b = 1.0 \fB(2)\fP \fI(since C++11)\fP + ); + explicit extreme_value_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses a and b as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses a and b as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters a - the a distribution parameter (location) b - the b distribution parameter (scale) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::extreme_value_distribution::max.3 b/man/std::extreme_value_distribution::max.3 index 55dbdf84f..c201f851d 100644 --- a/man/std::extreme_value_distribution::max.3 +++ b/man/std::extreme_value_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::extreme_value_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::max \- std::extreme_value_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::extreme_value_distribution::min.3 b/man/std::extreme_value_distribution::min.3 index 5c819d2a2..fd70f61c5 100644 --- a/man/std::extreme_value_distribution::min.3 +++ b/man/std::extreme_value_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::extreme_value_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::min \- std::extreme_value_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::extreme_value_distribution::operator().3 b/man/std::extreme_value_distribution::operator().3 index 215fe3699..fe90c5f3c 100644 --- a/man/std::extreme_value_distribution::operator().3 +++ b/man/std::extreme_value_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::extreme_value_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::operator() \- std::extreme_value_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::extreme_value_distribution::param.3 b/man/std::extreme_value_distribution::param.3 index 1aa6f8b4b..391a5a5f9 100644 --- a/man/std::extreme_value_distribution::param.3 +++ b/man/std::extreme_value_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::extreme_value_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::param \- std::extreme_value_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::extreme_value_distribution::reset.3 b/man/std::extreme_value_distribution::reset.3 index 434573db4..2c00011ac 100644 --- a/man/std::extreme_value_distribution::reset.3 +++ b/man/std::extreme_value_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::extreme_value_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::extreme_value_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::extreme_value_distribution::reset \- std::extreme_value_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::fclose.3 b/man/std::fclose.3 index 7794f8e75..a2899e97f 100644 --- a/man/std::fclose.3 +++ b/man/std::fclose.3 @@ -1,4 +1,7 @@ -.TH std::fclose 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fclose 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fclose \- std::fclose + .SH Synopsis Defined in header int fclose( std::FILE* stream ); @@ -10,30 +13,62 @@ file, and the buffer allocated by std::setbuf or std::setvbuf, if any, is also disassociated and deallocated if automatic allocation was used. + The behavior is undefined if the value of the pointer stream is used after fclose + returns. + .SH Parameters stream - the file stream to close .SH Return value - 0 on success, EOF otherwise + 0 on success, EOF otherwise. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + int is_ok = EXIT_FAILURE; + FILE* fp = std::fopen("/tmp/test.txt", "w+"); + if (!fp) + { + std::perror("File opening failed"); + return is_ok; + } + + int c; // Note: int, not char, required to handle EOF + while ((c = std::fgetc(fp)) != EOF) // Standard C I/O file reading loop + std::putchar(c); + + if (std::ferror(fp)) + std::puts("I/O error when reading"); + else if (std::feof(fp)) + { + std::puts("End of file reached successfully"); + is_ok = EXIT_SUCCESS; + } + + std::fclose(fp); + return is_ok; + } + +.SH Output: + + End of file reached successfully .SH See also fopen opens a file - \fI(function)\fP + \fI(function)\fP freopen open an existing stream with a different name - \fI(function)\fP + \fI(function)\fP close flushes the put area buffer and closes the associated file - \fI(public member function of std::basic_filebuf)\fP + \fI(public member function of std::basic_filebuf)\fP C documentation for fclose - -.SH Category: - - * Todo no example diff --git a/man/std::fdim,std::fdimf,std::fdiml.3 b/man/std::fdim,std::fdimf,std::fdiml.3 new file mode 100644 index 000000000..fb683ed7a --- /dev/null +++ b/man/std::fdim,std::fdimf,std::fdiml.3 @@ -0,0 +1,146 @@ +.TH std::fdim,std::fdimf,std::fdiml 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fdim,std::fdimf,std::fdiml \- std::fdim,std::fdimf,std::fdiml + +.SH Synopsis + Defined in header + float fdim ( float x, float y ); + + double fdim ( double x, double y ); (until C++23) + + long double fdim ( long double x, long double y ); + constexpr /* floating-point-type */ + + fdim ( /* floating-point-type */ x, (since C++23) + \fB(1)\fP + /* floating-point-type */ y ); + float fdimf( float x, float y ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double fdiml( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double fdim ( Integer x, Integer y ); + + 1-3) Returns the positive difference between x and y, that is, if x > y, returns x - + y, otherwise (i.e. if x <= y) returns +0. + The library provides overloads of std::fdim for all cv-unqualified floating-point + types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + x, y - floating-point or integer values + +.SH Return value + + If successful, returns the positive difference between x and y. + + If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is + returned. + + If a range error due to underflow occurs, the correct value (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If either argument is NaN, NaN is returned. + +.SH Notes + + Equivalent to std::fmax(x - y, 0), except for the NaN handling requirements. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::fdim(num1, num2) + has the same effect as std::fdim(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::fdim(num1, num2) has the same effect as (until C++23) + std::fdim(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::fdim(num1, + num2) has the same effect as std::fdim(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::fdim(num1, num2) has + the same effect as std::fdim(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + #ifndef __GNUC__ + #pragma STDC FENV_ACCESS ON + #endif + + int main() + { + std::cout << "fdim(4, 1) = " << std::fdim(4, 1) << '\\n' + << "fdim(1, 4) = " << std::fdim(1, 4) << '\\n' + << "fdim(4,-1) = " << std::fdim(4, -1) << '\\n' + << "fdim(1,-4) = " << std::fdim(1, -4) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "fdim(1e308, -1e308) = " << std::fdim(1e308, -1e308) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Output: + + fdim(4, 1) = 3 + fdim(1, 4) = 0 + fdim(4,-1) = 5 + fdim(1,-4) = 5 + fdim(1e308, -1e308) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + abs(int) + labs computes absolute value of an integral value (\\(\\small{|x|}\\)|x|) + llabs \fI(function)\fP + \fI(C++11)\fP + fmax + fmaxf + fmaxl larger of two floating-point values + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + fdim diff --git a/man/std::fdim.3 b/man/std::fdim.3 deleted file mode 100644 index 132762739..000000000 --- a/man/std::fdim.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::fdim 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float fdim( float x, float y ); \fB(1)\fP \fI(since C++11)\fP - double fdim( double x, double y ); \fB(2)\fP \fI(since C++11)\fP - long double fdim( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP - Promoted fdim( Arithmetic1 x, Arithmetic2 y ); \fB(4)\fP \fI(since C++11)\fP - - Returns the positive difference between x and y. This could be implemented as fmax - (x - y, 0), so if x ≤ y, the result is always equals to 0, otherwise it is x - y. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - -.SH Parameters - - x, y - values of floating-point or integral types - -.SH Return value - - The positive difference value. - -.SH See also - - abs(int) - labs computes absolute value of an integral value (|x|) - llabs \fI(function)\fP - imaxabs - \fI(C++11)\fP - fmax larger of two floating point values - \fI(C++11)\fP \fI(function)\fP - C documentation for - fdim diff --git a/man/std::feclearexcept.3 b/man/std::feclearexcept.3 index c7ca11a47..695a04e00 100644 --- a/man/std::feclearexcept.3 +++ b/man/std::feclearexcept.3 @@ -1,4 +1,7 @@ -.TH std::feclearexcept 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::feclearexcept 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::feclearexcept \- std::feclearexcept + .SH Synopsis Defined in header int feclearexcept( int excepts ); \fI(since C++11)\fP @@ -17,47 +20,44 @@ .SH Example - - + + // Run this code - #include #include #include - - #pragma STDC FENV_ACCESS ON - + #include + + // #pragma STDC FENV_ACCESS ON + volatile double zero = 0.0; // volatile not needed where FENV_ACCESS is supported volatile double one = 1.0; // volatile not needed where FENV_ACCESS is supported - + int main() { std::feclearexcept(FE_ALL_EXCEPT); std::cout << "1.0/0.0 = " << 1.0 / zero << '\\n'; - if(std::fetestexcept(FE_DIVBYZERO)) { + if (std::fetestexcept(FE_DIVBYZERO)) std::cout << "division by zero reported\\n"; - } else { - std::cout << "divsion by zero not reported\\n"; - } - + else + std::cout << "division by zero not reported\\n"; + std::feclearexcept(FE_ALL_EXCEPT); - std::cout << "1.0/10 = " << one/10 << '\\n'; - if(std::fetestexcept(FE_INEXACT)) { + std::cout << "1.0/10 = " << one / 10 << '\\n'; + if (std::fetestexcept(FE_INEXACT)) std::cout << "inexact result reported\\n"; - } else { + else std::cout << "inexact result not reported\\n"; - } - + std::feclearexcept(FE_ALL_EXCEPT); std::cout << "sqrt(-1) = " << std::sqrt(-1) << '\\n'; - if(std::fetestexcept(FE_INVALID)) { + if (std::fetestexcept(FE_INVALID)) std::cout << "invalid result reported\\n"; - } else { + else std::cout << "invalid result not reported\\n"; - } } -.SH Output: +.SH Possible output: 1.0/0.0 = inf division by zero reported @@ -69,4 +69,6 @@ .SH See also fetestexcept determines which of the specified floating-point status flags are set - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + feclearexcept diff --git a/man/std::fegetenv,std::fesetenv.3 b/man/std::fegetenv,std::fesetenv.3 index 2fcb3b026..607dbc335 100644 --- a/man/std::fegetenv,std::fesetenv.3 +++ b/man/std::fegetenv,std::fesetenv.3 @@ -1,4 +1,7 @@ -.TH std::fegetenv,std::fesetenv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fegetenv,std::fesetenv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fegetenv,std::fesetenv \- std::fegetenv,std::fesetenv + .SH Synopsis Defined in header int fegetenv( std::fenv_t* envp ) \fB(1)\fP \fI(since C++11)\fP @@ -28,9 +31,12 @@ feholdexcept saves the environment, clears all status flags and ignores all future \fI(C++11)\fP errors - \fI(function)\fP - feupdateenv restores the floating-point environment and raises the previously raise - \fI(C++11)\fP exceptions - \fI(function)\fP + \fI(function)\fP + feupdateenv restores the floating-point environment and raises the previously + \fI(C++11)\fP raised exceptions + \fI(function)\fP FE_DFL_ENV default floating-point environment - \fI(C++11)\fP (macro constant) + \fI(C++11)\fP (macro constant) + C documentation for + fegetenv, + fesetenv diff --git a/man/std::fegetexceptflag,std::fesetexceptflag.3 b/man/std::fegetexceptflag,std::fesetexceptflag.3 index 2a643fd0d..f18b3837f 100644 --- a/man/std::fegetexceptflag,std::fesetexceptflag.3 +++ b/man/std::fegetexceptflag,std::fesetexceptflag.3 @@ -1,4 +1,7 @@ -.TH std::fegetexceptflag,std::fesetexceptflag 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fegetexceptflag,std::fesetexceptflag 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fegetexceptflag,std::fesetexceptflag \- std::fegetexceptflag,std::fesetexceptflag + .SH Synopsis Defined in header int fegetexceptflag( std::fexcept_t* flagp, int excepts ); \fB(1)\fP \fI(since C++11)\fP @@ -27,3 +30,9 @@ .SH Return value 0 on success, non-zero otherwise. + +.SH See also + + C documentation for + fegetexceptflag, + fesetexceptflag diff --git a/man/std::fegetround,std::fesetround.3 b/man/std::fegetround,std::fesetround.3 index 0cf0da6c9..f3b807a33 100644 --- a/man/std::fegetround,std::fesetround.3 +++ b/man/std::fegetround,std::fesetround.3 @@ -1,4 +1,7 @@ -.TH std::fegetround,std::fesetround 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fegetround,std::fesetround 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fegetround,std::fesetround \- std::fegetround,std::fesetround + .SH Synopsis Defined in header int fesetround( int round ) \fB(1)\fP \fI(since C++11)\fP @@ -19,68 +22,90 @@ 1) 0 on success, non-zero otherwise. - 2) the floating point rounding macro describing the current rounding direction or a - negative value if the direction cannot be determined + 2) The floating point rounding macro describing the current rounding direction or a + negative value if the direction cannot be determined. + +.SH Notes + + The current rounding mode, reflecting the effects of the most recent fesetround, can + also be queried with FLT_ROUNDS. + + See floating-point rounding macros for the effects of rounding. .SH Example - - + + // Run this code - #include #include + #include + #include #include - + #include + // #pragma STDC FENV_ACCESS ON + int main() { - #pragma STDC FENV_ACCESS ON - std::fesetround(FE_DOWNWARD); - std::cout << "rounding using FE_DOWNWARD: \\n" << std::fixed - << " 12.0 -> " << std::nearbyint(12.0) << '\\n' - << " 12.1 -> " << std::nearbyint(12.1) << '\\n' - << "-12.1 -> " << std::nearbyint(-12.1) << '\\n' - << " 12.5 -> " << std::nearbyint(12.5) << '\\n' - << " 12.9 -> " << std::nearbyint(12.9) << '\\n' - << "-12.9 -> " << std::nearbyint(-12.9) << '\\n' - << " 13.0 -> " << std::nearbyint(13.0) << '\\n'; - std::fesetround(FE_TONEAREST); - std::cout << "rounding using FE_TONEAREST: \\n" - << " 12.0 -> " << std::nearbyint(12.0) << '\\n' - << " 12.1 -> " << std::nearbyint(12.1) << '\\n' - << "-12.1 -> " << std::nearbyint(-12.1) << '\\n' - << " 12.5 -> " << std::nearbyint(12.5) << '\\n' - << " 12.9 -> " << std::nearbyint(12.9) << '\\n' - << "-12.9 -> " << std::nearbyint(-12.9) << '\\n' - << " 13.0 -> " << std::nearbyint(13.0) << '\\n'; + static constexpr std::pair samples[] + { + {" 12.0", 12.0}, {" 12.1", 12.1}, {"-12.1", -12.1}, {" 12.5", 12.5}, + {"-12.5", -12.5}, {" 12.9", 12.9}, {"-12.9", -12.9}, {" 13.0", 13.0} + }; + + std::cout << + "│ sample │ FE_DOWNWARD │ FE_UPWARD │ FE_TONEAREST │ FE_TOWARDZERO │\\n"; + + for (const auto& [str, fp] : samples) + { + std::cout << "│ " << std::setw(6) << str << " │ "; + for (const int dir : {FE_DOWNWARD, FE_UPWARD, FE_TONEAREST, FE_TOWARDZERO}) + { + std::fesetround(dir); + std::cout << std::setw(10) << std::fixed << std::nearbyint(fp) << " │ "; + } + std::cout << '\\n'; + } } .SH Output: - rounding using FE_DOWNWARD: - 12.0 -> 12.000000 - 12.1 -> 12.000000 - -12.1 -> -13.000000 - 12.5 -> 12.000000 - 12.9 -> 12.000000 - -12.9 -> -13.000000 - 13.0 -> 13.000000 - rounding using FE_TONEAREST: - 12.0 -> 12.000000 - 12.1 -> 12.000000 - -12.1 -> -12.000000 - 12.5 -> 12.000000 - 12.9 -> 13.000000 - -12.9 -> -13.000000 - 13.0 -> 13.000000 + │ sample │ FE_DOWNWARD │ FE_UPWARD │ FE_TONEAREST │ FE_TOWARDZERO │ + │ 12.0 │ 12.000000 │ 12.000000 │ 12.000000 │ 12.000000 │ + │ 12.1 │ 12.000000 │ 13.000000 │ 12.000000 │ 12.000000 │ + │ -12.1 │ -13.000000 │ -12.000000 │ -12.000000 │ -12.000000 │ + │ 12.5 │ 12.000000 │ 13.000000 │ 12.000000 │ 12.000000 │ + │ -12.5 │ -13.000000 │ -12.000000 │ -12.000000 │ -12.000000 │ + │ 12.9 │ 12.000000 │ 13.000000 │ 13.000000 │ 12.000000 │ + │ -12.9 │ -13.000000 │ -12.000000 │ -13.000000 │ -12.000000 │ + │ 13.0 │ 13.000000 │ 13.000000 │ 13.000000 │ 13.000000 │ .SH See also - nearbyint nearest integer using current rounding mode - \fI(C++11)\fP \fI(function)\fP + nearbyint + nearbyintf + nearbyintl nearest integer using current rounding mode + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP rint - lrint nearest integer using current rounding mode with - llrint exception if the result differs - \fI(C++11)\fP \fI(function)\fP + rintf + rintl + lrint + lrintf + lrintl + llrint + llrintf nearest integer using current rounding mode with + llrintl exception if the result differs + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP \fI(C++11)\fP \fI(C++11)\fP + C documentation for + fegetround, + fesetround diff --git a/man/std::feholdexcept.3 b/man/std::feholdexcept.3 index 544a31863..2328594f8 100644 --- a/man/std::feholdexcept.3 +++ b/man/std::feholdexcept.3 @@ -1,4 +1,7 @@ -.TH std::feholdexcept 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::feholdexcept 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::feholdexcept \- std::feholdexcept + .SH Synopsis Defined in header int feholdexcept( std::fenv_t* envp ) \fI(since C++11)\fP @@ -25,11 +28,13 @@ .SH See also - feupdateenv restores the floating-point environment and raises the previously raise + feupdateenv restores the floating-point environment and raises the previously raised \fI(C++11)\fP exceptions - \fI(function)\fP - fegetenv saves or restores the current floating point environment - fesetenv \fI(function)\fP + \fI(function)\fP + fegetenv saves or restores the current floating-point environment + fesetenv \fI(function)\fP \fI(C++11)\fP FE_DFL_ENV default floating-point environment - \fI(C++11)\fP (macro constant) + \fI(C++11)\fP (macro constant) + C documentation for + feholdexcept diff --git a/man/std::feof.3 b/man/std::feof.3 index 6b30b38b5..e95bbb542 100644 --- a/man/std::feof.3 +++ b/man/std::feof.3 @@ -1,4 +1,7 @@ -.TH std::feof 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::feof 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::feof \- std::feof + .SH Synopsis Defined in header int feof( std::FILE* stream ); @@ -26,40 +29,51 @@ .SH Example - + // Run this code #include #include - + int main() { - FILE* fp = std::fopen("test.txt", "r"); - if(!fp) { + int is_ok = EXIT_FAILURE; + FILE* fp = std::fopen("/tmp/test.txt", "w+"); + if (!fp) + { std::perror("File opening failed"); - return EXIT_FAILURE; + return is_ok; } - - int c; // note: int, not char, required to handle EOF - while ((c = std::fgetc(fp)) != EOF) { // standard C I/O file reading loop - std::putchar(c); - } - + + int c; // Note: int, not char, required to handle EOF + while ((c = std::fgetc(fp)) != EOF) // Standard C I/O file reading loop + std::putchar(c); + if (std::ferror(fp)) std::puts("I/O error when reading"); else if (std::feof(fp)) + { std::puts("End of file reached successfully"); + is_ok = EXIT_SUCCESS; + } + + std::fclose(fp); + return is_ok; } +.SH Output: + + End of file reached successfully + .SH See also eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP clearerr clears errors - \fI(function)\fP + \fI(function)\fP perror displays a character string corresponding of the current error to stderr - \fI(function)\fP + \fI(function)\fP ferror checks for a file error - \fI(function)\fP + \fI(function)\fP C documentation for feof diff --git a/man/std::feraiseexcept.3 b/man/std::feraiseexcept.3 index 42ea99a8b..c071e0a9f 100644 --- a/man/std::feraiseexcept.3 +++ b/man/std::feraiseexcept.3 @@ -1,4 +1,7 @@ -.TH std::feraiseexcept 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::feraiseexcept 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::feraiseexcept \- std::feraiseexcept + .SH Synopsis Defined in header int feraiseexcept( int excepts ); \fI(since C++11)\fP @@ -19,36 +22,32 @@ .SH Example - + // Run this code - #include #include - - #pragma STDC FENV_ACCESS ON - + #include + + // #pragma STDC FENV_ACCESS ON + int main() { std::feclearexcept(FE_ALL_EXCEPT); - int r = std::feraiseexcept(FE_UNDERFLOW | FE_DIVBYZERO); - std::cout << "Raising divbyzero and underflow simultaneously " - << (r?"fails":"succeeds") << " and results in\\n"; - int e = std::fetestexcept(FE_ALL_EXCEPT); - if (e & FE_DIVBYZERO) { + const int r = std::feraiseexcept(FE_UNDERFLOW | FE_DIVBYZERO); + std::cout << "Raising divbyzero and underflow simultaneously " + << (r ? "fails" : "succeeds") << " and results in\\n"; + + const int e = std::fetestexcept(FE_ALL_EXCEPT); + if (e & FE_DIVBYZERO) std::cout << "division by zero\\n"; - } - if (e & FE_INEXACT) { + if (e & FE_INEXACT) std::cout << "inexact\\n"; - } - if (e & FE_INVALID) { + if (e & FE_INVALID) std::cout << "invalid\\n"; - } - if (e & FE_UNDERFLOW) { + if (e & FE_UNDERFLOW) std::cout << "underflow\\n"; - } - if (e & FE_OVERFLOW) { + if (e & FE_OVERFLOW) std::cout << "overflow\\n"; - } } .SH Output: @@ -60,6 +59,8 @@ .SH See also feclearexcept clears the specified floating-point status flags - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP fetestexcept determines which of the specified floating-point status flags are set - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + feraiseexcept diff --git a/man/std::ferror.3 b/man/std::ferror.3 index dda46e15a..c77fb98ba 100644 --- a/man/std::ferror.3 +++ b/man/std::ferror.3 @@ -1,4 +1,7 @@ -.TH std::ferror 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ferror 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ferror \- std::ferror + .SH Synopsis Defined in header int ferror( std::FILE* stream ); @@ -11,42 +14,48 @@ .SH Return value - Nonzero value if the file stream has errors occurred, 0 otherwise + Nonzero value if the file stream has errors occurred, 0 otherwise. .SH Example - + // Run this code + #include #include #include - + #include + int main() { - FILE* fp = std::fopen("test.txt", "r"); - if(!fp) { - std::perror("File opening failed"); - return EXIT_FAILURE; - } - - int c; // note: int, not char, required to handle EOF - while ((c = std::fgetc(fp)) != EOF) { // standard C I/O file reading loop - std::putchar(c); - } - - if (std::ferror(fp)) - std::puts("I/O error when reading"); - else if (std::feof(fp)) - std::puts("End of file reached successfully"); + const char *fname = std::tmpnam(nullptr); + std::FILE* f = std::fopen(fname, "wb"); + std::fputs("\\xff\\xff\\n", f); // not a valid UTF-8 character sequence + std::fclose(f); + + std::setlocale(LC_ALL, "en_US.utf8"); + f = std::fopen(fname, "rb"); + std::wint_t ch; + while ((ch=std::fgetwc(f)) != WEOF) // attempt to read as UTF-8 + std::printf("%#x ", ch); + + if (std::feof(f)) + puts("EOF indicator set"); + if (std::ferror(f)) + puts("Error indicator set"); } +.SH Output: + + Error indicator set + .SH See also clearerr clears errors - \fI(function)\fP + \fI(function)\fP feof checks for the end-of-file - \fI(function)\fP - perror displays a character string corresponding of the current error to stderr - \fI(function)\fP + \fI(function)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP C documentation for ferror diff --git a/man/std::fetestexcept.3 b/man/std::fetestexcept.3 index 92cad1a81..4423eff5a 100644 --- a/man/std::fetestexcept.3 +++ b/man/std::fetestexcept.3 @@ -1,4 +1,7 @@ -.TH std::fetestexcept 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fetestexcept 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fetestexcept \- std::fetestexcept + .SH Synopsis Defined in header int fetestexcept( int excepts ); \fI(since C++11)\fP @@ -18,47 +21,44 @@ .SH Example - - + + // Run this code - #include #include #include - - #pragma STDC FENV_ACCESS ON - + #include + + // #pragma STDC FENV_ACCESS ON + volatile double zero = 0.0; // volatile not needed where FENV_ACCESS is supported volatile double one = 1.0; // volatile not needed where FENV_ACCESS is supported - + int main() { std::feclearexcept(FE_ALL_EXCEPT); std::cout << "1.0/0.0 = " << 1.0 / zero << '\\n'; - if(std::fetestexcept(FE_DIVBYZERO)) { + if (std::fetestexcept(FE_DIVBYZERO)) std::cout << "division by zero reported\\n"; - } else { - std::cout << "divsion by zero not reported\\n"; - } - + else + std::cout << "division by zero not reported\\n"; + std::feclearexcept(FE_ALL_EXCEPT); - std::cout << "1.0/10 = " << one/10 << '\\n'; - if(std::fetestexcept(FE_INEXACT)) { + std::cout << "1.0/10 = " << one / 10 << '\\n'; + if (std::fetestexcept(FE_INEXACT)) std::cout << "inexact result reported\\n"; - } else { + else std::cout << "inexact result not reported\\n"; - } - + std::feclearexcept(FE_ALL_EXCEPT); std::cout << "sqrt(-1) = " << std::sqrt(-1) << '\\n'; - if(std::fetestexcept(FE_INVALID)) { + if (std::fetestexcept(FE_INVALID)) std::cout << "invalid result reported\\n"; - } else { + else std::cout << "invalid result not reported\\n"; - } } -.SH Output: +.SH Possible output: 1.0/0.0 = inf division by zero reported @@ -70,4 +70,6 @@ .SH See also feclearexcept clears the specified floating-point status flags - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + fetestexcept diff --git a/man/std::feupdatedenv.3 b/man/std::feupdatedenv.3 deleted file mode 100644 index 5a74abd49..000000000 --- a/man/std::feupdatedenv.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH std::feupdatedenv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - int feupdateenv( const std::fenv_t* envp ) \fI(since C++11)\fP - - First, remembers the currently raised floating-point exceptions, then restores the - floating-point environment from the object pointed to by envp (similar to - std::fesetenv), then raises the floating-point exceptions that were saved. - - This function may be used to end the non-stop mode established by an earlier call to - std::feholdexcept. - -.SH Parameters - - envp - pointer to the object of type std::fenv_t set by an earlier call to - std::feholdexcept or std::fegetenv or equal to FE_DFL_ENV - -.SH Return value - - 0 on success, non-zero otherwise. - -.SH See also - - feholdexcept saves the environment, clears all status flags and ignores all future - \fI(C++11)\fP errors - \fI(function)\fP - fegetenv saves or restores the current floating point environment - fesetenv \fI(function)\fP - \fI(C++11)\fP - FE_DFL_ENV default floating-point environment - \fI(C++11)\fP (macro constant) diff --git a/man/std::feupdateenv.3 b/man/std::feupdateenv.3 new file mode 100644 index 000000000..d7e73c603 --- /dev/null +++ b/man/std::feupdateenv.3 @@ -0,0 +1,36 @@ +.TH std::feupdateenv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::feupdateenv \- std::feupdateenv + +.SH Synopsis + Defined in header + int feupdateenv( const std::fenv_t* envp ) \fI(since C++11)\fP + + First, remembers the currently raised floating-point exceptions, then restores the + floating-point environment from the object pointed to by envp (similar to + std::fesetenv), then raises the floating-point exceptions that were saved. + + This function may be used to end the non-stop mode established by an earlier call to + std::feholdexcept. + +.SH Parameters + + envp - pointer to the object of type std::fenv_t set by an earlier call to + std::feholdexcept or std::fegetenv or equal to FE_DFL_ENV + +.SH Return value + + 0 on success, non-zero otherwise. + +.SH See also + + feholdexcept saves the environment, clears all status flags and ignores all future + \fI(C++11)\fP errors + \fI(function)\fP + fegetenv saves or restores the current floating-point environment + fesetenv \fI(function)\fP + \fI(C++11)\fP + FE_DFL_ENV default floating-point environment + \fI(C++11)\fP (macro constant) + C documentation for + feupdateenv diff --git a/man/std::fflush.3 b/man/std::fflush.3 index 3bba57e32..7fc124a11 100644 --- a/man/std::fflush.3 +++ b/man/std::fflush.3 @@ -1,31 +1,47 @@ -.TH std::fflush 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fflush 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fflush \- std::fflush + .SH Synopsis Defined in header int fflush( std::FILE* stream ); - Causes the output file stream to be synchronized with the actual contents of the - file. + For output streams (and for update streams on which the last operation was output), + writes any unwritten data from the stream's buffer to the associated output device. - The behavior is undefined if the given stream is of the input type or if the given - stream is of the update type, but the last I/O operation was not an output - operation. + For input streams (and for update streams on which the last operation was input), + the behavior is undefined. - If stream is NULL, all open streams are flushed. + If stream is a null pointer, all open output streams are flushed, including the ones + manipulated within library packages or otherwise not directly accessible to the + program. .SH Parameters - stream - the file stream to synchronize + stream - the file stream to write out .SH Return value Returns zero on success. Otherwise EOF is returned and the error indicator of the file stream is set. +.SH Notes + + POSIX extends the specification of fflush by defining its effects on an input + stream, as long as that stream represents a file or another seekable device: in that + case the POSIX file pointer is repositioned to match the C stream pointer (which + effectively undoes any read buffering) and the effects of any std::ungetc or + std::ungetwc that weren't yet read back from the stream are discarded. + + Microsoft also extends the specification of fflush by defining its effects on an + input stream: in Visual Studio 2013 and prior, it discarded the input buffer, in + Visual Studio 2015 and newer, it has no effect, buffers are retained. + .SH See also fopen opens a file - \fI(function)\fP + \fI(function)\fP fclose closes a file - \fI(function)\fP + \fI(function)\fP C documentation for fflush diff --git a/man/std::fgetc,std::getc.3 b/man/std::fgetc,std::getc.3 index 648006d7e..07bb901c8 100644 --- a/man/std::fgetc,std::getc.3 +++ b/man/std::fgetc,std::getc.3 @@ -1,11 +1,13 @@ -.TH std::fgetc,std::getc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fgetc,std::getc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fgetc,std::getc \- std::fgetc,std::getc + .SH Synopsis Defined in header int fgetc( std::FILE* stream ); int getc( std::FILE* stream ); - Reads the next character from the given input stream. getc() may be implemented as a - macro. + Reads the next character from the given input stream. .SH Parameters @@ -19,14 +21,53 @@ indicator (see std::feof()) on stream. If the failure has been caused by some other error, sets the error indicator (see std::ferror()) on stream. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int is_ok = EXIT_FAILURE; + FILE* fp = std::fopen("/tmp/test.txt", "w+"); + if (!fp) + { + std::perror("File opening failed"); + return is_ok; + } + + int c; // Note: int, not char, required to handle EOF + while ((c = std::fgetc(fp)) != EOF) // Standard C I/O file reading loop + std::putchar(c); + + if (std::ferror(fp)) + std::puts("I/O error when reading"); + else if (std::feof(fp)) + { + std::puts("End of file reached successfully"); + is_ok = EXIT_SUCCESS; + } + + std::fclose(fp); + return is_ok; + } + +.SH Output: + + End of file reached successfully + .SH See also - gets reads a character string from stdin - \fI(function)\fP - fputc writes a character to a file stream - putc \fI(function)\fP - ungetc puts a character back into a file stream - \fI(function)\fP + gets reads a character string from stdin + (deprecated in C++11) \fI(function)\fP + (removed in C++14) + fputc writes a character to a file stream + putc \fI(function)\fP + ungetc puts a character back into a file stream + \fI(function)\fP C documentation for fgetc, getc diff --git a/man/std::fgetpos.3 b/man/std::fgetpos.3 index 5f34ef4ea..8bafcdf51 100644 --- a/man/std::fgetpos.3 +++ b/man/std::fgetpos.3 @@ -1,4 +1,7 @@ -.TH std::fgetpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fgetpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fgetpos \- std::fgetpos + .SH Synopsis Defined in header int fgetpos( std::FILE* stream, std::fpos_t* pos ); @@ -24,14 +27,13 @@ .SH See also ftell returns the current file position indicator - \fI(function)\fP + \fI(function)\fP fseek moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP fsetpos moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP C documentation for fgetpos .SH Category: - * Todo no example diff --git a/man/std::fgets.3 b/man/std::fgets.3 index 888d9cf17..509bb7115 100644 --- a/man/std::fgets.3 +++ b/man/std::fgets.3 @@ -1,71 +1,104 @@ -.TH std::fgets 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fgets 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fgets \- std::fgets + .SH Synopsis Defined in header char* fgets( char* str, int count, std::FILE* stream ); - Reads at most count - 1 characters from the given file stream and stores them in - str. The produced character string is always null-terminated. Parsing stops if - end-of-file occurs or a newline character is found, in which case str will contain - that newline character. + Reads at most count - 1 characters from the given file stream and stores them in the + character array pointed to by str. Parsing stops if a newline character is found, in + which case str will contain that newline character, or if end-of-file occurs. If + bytes are read and no errors occur, writes a null character at the position + immediately after the last character written to str. .SH Parameters - str - string to read the characters to - count - the length of str + str - pointer to an element of a char array + count - maximum number of characters to write (typically the length of str) stream - file stream to read the data from .SH Return value - str on success, NULL on failure. + str on success, null pointer on failure. + + If the end-of-file condition is encountered, sets the eof indicator on stream (see + std::feof()). This is only a failure if it causes no bytes to be read, in which case + a null pointer is returned and the contents of the array pointed to by str are not + altered (i.e. the first byte is not overwritten with a null character). + + If the failure has been caused by some other error, sets the error indicator (see + std::ferror()) on stream. The contents of the array pointed to by str are + indeterminate (it may not even be null-terminated). + +.SH Notes - If the failure has been caused by end of file condition, additionally sets the eof - indicator (see std::feof()) on stdin. If the failure has been caused by some other - error, sets the error indicator (see std::ferror()) on stdin. + POSIX additionally requires that fgets sets errno if it encounters a failure other + than the end-of-file condition. + + Although the standard specification is unclear in the cases where count <= 1, common + implementations do + + * if count < 1, do nothing, report error, + * if count == 1, + + * some implementations do nothing, report error, + * others read nothing, store zero in str[0], report success. .SH Example - + // Run this code - #include #include #include - + #include + #include + #include + + void dump(std::span buf, std::size_t offset) + { + std::cout << std::dec; + for (char ch : buf) + std::cout << (ch >= ' ' ? ch : '.'), offset--; + std::cout << std::string(offset, ' ') << std::hex + << std::setfill('0') << std::uppercase; + for (unsigned ch : buf) + std::cout << std::setw(2) << ch << ' '; + std::cout << std::dec << '\\n'; + } + int main() { std::FILE* tmpf = std::tmpfile(); std::fputs("Alan Turing\\n", tmpf); std::fputs("John von Neumann\\n", tmpf); std::fputs("Alonzo Church\\n", tmpf); - + std::rewind(tmpf); - char buf[8]; - while (std::fgets(buf, sizeof buf, tmpf) != NULL) { - std::cout << '"' << buf << '"' << '\\n'; - } + for (char buf[8]; std::fgets(buf, sizeof buf, tmpf) != nullptr;) + dump(buf, 10); } .SH Output: - "Alan Tu" - "ring - " - "John vo" - "n Neuma" - "nn - " - "Alonzo " - "Church - " + Alan Tu. 41 6C 61 6E 20 54 75 00 + ring..u. 72 69 6E 67 0A 00 75 00 + John vo. 4A 6F 68 6E 20 76 6F 00 + n Neuma. 6E 20 4E 65 75 6D 61 00 + nn..uma. 6E 6E 0A 00 75 6D 61 00 + Alonzo . 41 6C 6F 6E 7A 6F 20 00 + Church.. 43 68 75 72 63 68 0A 00 .SH See also - scanf reads formatted input from stdin, a file stream or a buffer - fscanf \fI(function)\fP + scanf reads formatted input from stdin, a file stream or a buffer + fscanf \fI(function)\fP sscanf - gets reads a character string from stdin - \fI(function)\fP - fputs writes a character string to a file stream - \fI(function)\fP + gets reads a character string from stdin + (deprecated in C++11) \fI(function)\fP + (removed in C++14) + fputs writes a character string to a file stream + \fI(function)\fP C documentation for fgets diff --git a/man/std::fgetwc.3 b/man/std::fgetwc.3 index cecf6bae3..46f3c6677 100644 --- a/man/std::fgetwc.3 +++ b/man/std::fgetwc.3 @@ -1,8 +1,11 @@ -.TH std::fgetwc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fgetwc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fgetwc \- std::fgetwc + .SH Synopsis Defined in header - wint_t fgetwc( std::FILE* stream ); - wint_t getwc( std::FILE* stream ); + std::wint_t fgetwc( std::FILE* stream ); + std::wint_t getwc( std::FILE* stream ); Reads the next wide character from the given input stream. getwc() may be implemented as a macro and may evaluate stream more than once. @@ -19,12 +22,12 @@ .SH See also fgetc gets a character from a file stream - getc \fI(function)\fP + getc \fI(function)\fP fgetws gets a wide string from a file stream - \fI(function)\fP + \fI(function)\fP fputwc writes a wide character to a file stream - putwc \fI(function)\fP + putwc \fI(function)\fP ungetwc puts a wide character back into a file stream - \fI(function)\fP + \fI(function)\fP C documentation for fgetwc diff --git a/man/std::fgetws.3 b/man/std::fgetws.3 new file mode 100644 index 000000000..ffe7a125e --- /dev/null +++ b/man/std::fgetws.3 @@ -0,0 +1,97 @@ +.TH std::fgetws 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fgetws \- std::fgetws + +.SH Synopsis + Defined in header + wchar_t* fgetws( wchar_t* str, int count, std::FILE* stream ); + + Reads at most count - 1 wide characters from the given file stream and stores them + in str. The produced wide string is always null-terminated. Parsing stops if + end-of-file occurs or a newline wide character is found, in which case str will + contain that wide newline character. + +.SH Parameters + + str - wide string to read the characters to + count - the length of str + stream - file stream to read the data from + +.SH Return value + + str on success, a null pointer on an error. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + void dump(std::span sp, std::size_t width = 14) + { + for (wchar_t wc : sp) + std::wcout << (std::iswprint(wc) ? wc : L'.'); + std::wcout << std::wstring(width > sp.size() ? width - sp.size() : 1, L' ') + << std::hex << std::uppercase << std::setfill(L'0'); + for (wchar_t wc : sp) + std::wcout << std::setw(sizeof wc) << static_cast(wc) << ' '; + std::wcout << '\\n'; + } + + int main() + { + // Create temp file that contains wide characters + std::setlocale(LC_ALL, "en_US.utf8"); + std::FILE* tmpf = std::tmpfile(); + + for (const wchar_t* text : { + L"Tétraèdre" L"\\n", + L"Cube" L"\\n", + L"Octaèdre" L"\\n", + L"Icosaèdre" L"\\n", + L"Dodécaèdre" L"\\n" + }) + if (int rc = std::fputws(text, tmpf); rc == EOF) + { + std::perror("fputws()"); // POSIX requires that errno is set + return EXIT_FAILURE; + } + + std::rewind(tmpf); + + std::array buf; + while (std::fgetws(buf.data(), buf.size(), tmpf) != nullptr) + dump(std::span(buf.data(), buf.size())); + + return EXIT_SUCCESS; + } + +.SH Possible output: + + Tétraèdre... 0054 00E9 0074 0072 0061 00E8 0064 0072 0065 000A 0000 0000 + Cube..dre... 0043 0075 0062 0065 000A 0000 0064 0072 0065 000A 0000 0000 + Octaèdre.... 004F 0063 0074 0061 00E8 0064 0072 0065 000A 0000 0000 0000 + Icosaèdre... 0049 0063 006F 0073 0061 00E8 0064 0072 0065 000A 0000 0000 + Dodécaèdre.. 0044 006F 0064 00E9 0063 0061 00E8 0064 0072 0065 000A 0000 + +.SH See also + + wscanf reads formatted wide character input from stdin, a file stream or a buffer + fwscanf \fI(function)\fP + swscanf + fgetwc gets a wide character from a file stream + getwc \fI(function)\fP + fputws writes a wide string to a file stream + \fI(function)\fP + C documentation for + fgetws diff --git a/man/std::filebuf.3 b/man/std::filebuf.3 deleted file mode 120000 index a5ce16e09..000000000 --- a/man/std::filebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf.3 \ No newline at end of file diff --git a/man/std::filebuf.3 b/man/std::filebuf.3 new file mode 100644 index 000000000..b456ca49a --- /dev/null +++ b/man/std::filebuf.3 @@ -0,0 +1,247 @@ +.TH std::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf \- std::basic_filebuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_filebuf : public std::basic_streambuf + + std::basic_filebuf is a std::basic_streambuf whose associated character sequence is + a file. Both the input sequence and the output sequence are associated with the same + file, and a joint file position is maintained for both operations. The restrictions + on reading and writing a sequence with std::basic_filebuf are the same as + std::FILEs. + + The functions underflow() and overflow() / sync() perform the actual I/O between the + file and the get and put areas of the buffer. When CharT is not char, most + implementations store multibyte characters in the file and a std::codecvt facet is + used to perform wide/multibyte character conversion. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::filebuf std::basic_filebuf + std::wfilebuf std::basic_filebuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type which is required to be + std::fpos + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + +.SH Public member functions + constructor constructs a basic_filebuf object + \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + is_open checks if the associated file is open + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP +.SH Protected member functions + showmanyc optionally provides the number of characters available for input from + \fB[virtual]\fP the file + \fI(virtual protected member function)\fP + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function)\fP + uflow reads from the associated file and advances the next pointer in the + \fB[virtual]\fP get area + \fI(virtual protected member function)\fP + pbackfail backs out the input sequence to unget a character, not affecting the + \fB[virtual]\fP associated file + \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + setbuf provides user-supplied buffer or turns this filebuf unbuffered + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + sync writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Non-member functions + + std::swap(std::basic_filebuf) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) +.SH Locales + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + +.SH Positioning + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + +.SH Putback + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + + +.SH Protected member functions + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Get area + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + eback returns a pointer to the beginning, current character and the end of + gptr the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + pbase returns a pointer to the beginning, current character and the end of + pptr the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH See also + + object type, capable of holding all information needed to control a C I/O + FILE stream + \fI(typedef)\fP diff --git a/man/std::filebuf::basic_filebuf.3 b/man/std::filebuf::basic_filebuf.3 deleted file mode 120000 index 202c5b9db..000000000 --- a/man/std::filebuf::basic_filebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::basic_filebuf.3 \ No newline at end of file diff --git a/man/std::filebuf::basic_filebuf.3 b/man/std::filebuf::basic_filebuf.3 new file mode 100644 index 000000000..1c84686c4 --- /dev/null +++ b/man/std::filebuf::basic_filebuf.3 @@ -0,0 +1,44 @@ +.TH std::basic_filebuf::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::basic_filebuf \- std::basic_filebuf::basic_filebuf + +.SH Synopsis + basic_filebuf(); \fB(1)\fP + basic_filebuf( const std::basic_filebuf& rhs ) = delete; \fB(2)\fP \fI(since C++11)\fP + basic_filebuf( std::basic_filebuf&& rhs ); \fB(3)\fP \fI(since C++11)\fP + + Constructs new std::basic_filebuf object. + + 1) Constructs a std::basic_filebuf object, initializing the base class by calling + the default constructor of std::basic_streambuf. The created basic_filebuf is not + associated with a file, and is_open() returns false. + 2) The copy constructor is deleted; std::basic_filebuf is not CopyConstructible. + 3) Move-constructs a std::basic_filebuf object by moving all contents from another + std::basic_filebuf object rhs, including the buffers, the associated file, the + locale, the openmode, the is_open variable, and all other state. After move, rhs is + not associated with a file and rhs.is_open() == false. The member pointers of the + base class std::basic_streambuf of rhs and of the base class of *this are guaranteed + to point to different buffers (unless null). + +.SH Parameters + + rhs - another basic_filebuf + +.SH Notes + + Typically called by the constructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::close.3 b/man/std::filebuf::close.3 deleted file mode 120000 index db60d7b11..000000000 --- a/man/std::filebuf::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::close.3 \ No newline at end of file diff --git a/man/std::filebuf::close.3 b/man/std::filebuf::close.3 new file mode 100644 index 000000000..7126ff40d --- /dev/null +++ b/man/std::filebuf::close.3 @@ -0,0 +1,66 @@ +.TH std::basic_filebuf::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::close \- std::basic_filebuf::close + +.SH Synopsis + std::basic_filebuf* close(); + + If a put area exist (e.g. file was opened for writing), first calls + overflow(Traits::eof()) to write all pending output to the file, including any + unshift sequences. + + If the most recently called function, out of underflow(), overflow(), seekpos(), and + seekoff(), was overflow(), then calls std::codecvt::unshift(), perhaps multiple + times, to determine the unshift sequence according to the imbued locale, and writes + that sequence to file with overflow(Traits::eof()). + + Then, closes the file as if by calling std::fclose(), regardless of whether any of + the preceding calls succeeded or failed. + + If any of the function calls made, including the call to std::fclose(), fails, + returns a null pointer. If any of the function calls made throws an exception, the + exception is caught and rethrown after closing the file. If the file is already + closed, returns a null pointer right away. + + In any case, updates the private member variable that is accessed by is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + this on success, a null pointer on failure. + +.SH Notes + + close() is typically called through the destructor of std::basic_filebuf (which, in + turn, is typically called by the destructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 443 C++98 the file was written using changed to overflow(Traits::eof()) + overflow(EOF) + it was unclear how to handle + LWG 622 C++98 the it is rethrown after closing the + exception thrown during file + closing + +.SH See also + + is_open checks if the associated file is open + \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::filebuf.3 b/man/std::filebuf::filebuf.3 deleted file mode 120000 index 202c5b9db..000000000 --- a/man/std::filebuf::filebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::basic_filebuf.3 \ No newline at end of file diff --git a/man/std::filebuf::filebuf.3 b/man/std::filebuf::filebuf.3 new file mode 100644 index 000000000..1c84686c4 --- /dev/null +++ b/man/std::filebuf::filebuf.3 @@ -0,0 +1,44 @@ +.TH std::basic_filebuf::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::basic_filebuf \- std::basic_filebuf::basic_filebuf + +.SH Synopsis + basic_filebuf(); \fB(1)\fP + basic_filebuf( const std::basic_filebuf& rhs ) = delete; \fB(2)\fP \fI(since C++11)\fP + basic_filebuf( std::basic_filebuf&& rhs ); \fB(3)\fP \fI(since C++11)\fP + + Constructs new std::basic_filebuf object. + + 1) Constructs a std::basic_filebuf object, initializing the base class by calling + the default constructor of std::basic_streambuf. The created basic_filebuf is not + associated with a file, and is_open() returns false. + 2) The copy constructor is deleted; std::basic_filebuf is not CopyConstructible. + 3) Move-constructs a std::basic_filebuf object by moving all contents from another + std::basic_filebuf object rhs, including the buffers, the associated file, the + locale, the openmode, the is_open variable, and all other state. After move, rhs is + not associated with a file and rhs.is_open() == false. The member pointers of the + base class std::basic_streambuf of rhs and of the base class of *this are guaranteed + to point to different buffers (unless null). + +.SH Parameters + + rhs - another basic_filebuf + +.SH Notes + + Typically called by the constructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::imbue.3 b/man/std::filebuf::imbue.3 deleted file mode 120000 index 79eaa84b5..000000000 --- a/man/std::filebuf::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::imbue.3 \ No newline at end of file diff --git a/man/std::filebuf::imbue.3 b/man/std::filebuf::imbue.3 new file mode 100644 index 000000000..d0aad8e7b --- /dev/null +++ b/man/std::filebuf::imbue.3 @@ -0,0 +1,39 @@ +.TH std::basic_filebuf::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::imbue \- std::basic_filebuf::imbue + +.SH Synopsis + protected: + virtual void imbue( const std::locale& loc ) + + Changes the associated locale so that all characters inserted or extracted after + this call (and until another call to imbue()) are converted using the std::codecvt + facet of loc. + + If the old locale's encoding is state-dependent and file is not positioned at the + beginning, then the new locale must have the same std::codecvt facet as the one + previously imbued. + +.SH Parameters + + loc - the locale to imbue the stream with + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::is_open.3 b/man/std::filebuf::is_open.3 deleted file mode 120000 index 387eb1c16..000000000 --- a/man/std::filebuf::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::is_open.3 \ No newline at end of file diff --git a/man/std::filebuf::is_open.3 b/man/std::filebuf::is_open.3 new file mode 100644 index 000000000..e8cefa70c --- /dev/null +++ b/man/std::filebuf::is_open.3 @@ -0,0 +1,53 @@ +.TH std::basic_filebuf::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::is_open \- std::basic_filebuf::is_open + +.SH Synopsis + bool is_open() const; + + Returns true if the most recent call to open() succeeded and there has been no call + to close() since then. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the associated file is open, false otherwise. + +.SH Notes + + This function is typically called by std::basic_fstream::is_open(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ifstream fs("test.txt"); + std::filebuf fb; + fb.open("test.txt", std::ios_base::in); + std::cout << std::boolalpha + << "direct call: " << fb.is_open() << '\\n' + << "through streambuf: " << fs.rdbuf()->is_open() << '\\n' + << "through fstream: " << fs.is_open() << '\\n'; + } + +.SH Output: + + direct call: true + through streambuf: true + through fstream: true + +.SH See also + + open opens a file and configures it as the associated character sequence + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP diff --git a/man/std::filebuf::native_handle.3 b/man/std::filebuf::native_handle.3 new file mode 100644 index 000000000..43544dbf7 --- /dev/null +++ b/man/std::filebuf::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_filebuf::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::native_handle \- std::basic_filebuf::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with *this. The + behavior is undefined if is_open() is false. + +.SH Return value + + implementation defined handle. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::filebuf::open.3 b/man/std::filebuf::open.3 deleted file mode 120000 index 83b9deb43..000000000 --- a/man/std::filebuf::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::open.3 \ No newline at end of file diff --git a/man/std::filebuf::open.3 b/man/std::filebuf::open.3 new file mode 100644 index 000000000..384c0b7ed --- /dev/null +++ b/man/std::filebuf::open.3 @@ -0,0 +1,134 @@ +.TH std::basic_filebuf::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::open \- std::basic_filebuf::open + +.SH Synopsis + basic_filebuf* open( const char* s, std::ios_base::openmode mode \fB(1)\fP + ); + basic_filebuf* open( const std::string& str, \fB(2)\fP \fI(since C++11)\fP + std::ios_base::openmode mode ); + basic_filebuf* open( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode ); + basic_filebuf* open( const std::filesystem::path::value_type* s, \fB(4)\fP \fI(since C++17)\fP + std::ios_base::openmode mode ); + + If the associated file was already open (is_open() != false), returns a null pointer + right away. + + Otherwise, opens the file with the given name (s + , p.c_str() + \fI(since C++17)\fP or str.c_str(), depending on the overload). std::ios_base::openmode + values may be written as, e.g., std::ios_base::out | std::ios_base::app. + + Overload \fB(4)\fP is only provided if std::filesystem::path::value_type is \fI(since C++17)\fP + not char. + + The file is opened as if by calling std::fopen with the second argument (file access + mode) determined by the result of mode & ~std::ios_base::ate as follows, open() + fails if the result is not some combination of flags shown in the table: + + mode & ~std::ios_base::ate  std::fopen  Action if file Action if file + binary in out trunc app noreplace access already exists does not exist + (since C++23) mode + - + - - - - "r" Failure to + + + - - - - "rb" Read from start open + - + + - - - "r+" Error + + + + - - - "r+b" + - - + - - - "w" + - - + + - - + + - + - - - "wb" Destroy contents Create new + + - + + - - + - + + + - - "w+" + + + + + - - "w+b" + - - + - - + "wx" + - - + + - + + + - + - - + "wbx" Failure to open Create new + + - + + - + + - + + + - + "w+x" + + + + + - + "w+bx" + - - + - + - "a" + - - - - + - + + - + - + - "ab" + + - - - + - Write to end Create new + - + + - + - "a+" + - + - - + - + + + + - + - "a+b" + + + - - + - + + If the open operation succeeds and (openmode & std::ios_base::ate) != 0 (the ate bit + is set), repositions the file position to the end of file, as if by calling + std::fseek(file, 0, SEEK_END), where file is the pointer returned by calling + std::fopen. If the repositioning fails, calls close() and returns a null pointer to + indicate failure. + +.SH Parameters + + s, str, p - the file name to open; s must point to a null-terminated string + openmode - the file opening mode, a binary OR of the std::ios_base::openmode modes + +.SH Return value + + this on success, a null pointer on failure. + +.SH Notes + + open() is typically called through the constructor or the open() member function of + std::basic_fstream. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string filename = "Test.b"; + std::filebuf fb; + + // prepare a file to read + double d = 3.14; + if (!fb.open(filename, std::ios::binary | std::ios::out)) + { + std::cout << "Open file " << filename << " for write failed\\n"; + return 1; + } + fb.sputn(reinterpret_cast(&d), sizeof d); + fb.close(); + + // open file for reading + double d2 = 0.0; + if (!fb.open(filename, std::ios::binary | std::ios::in)) + { + std::cout << "Open file " << filename << " for read failed\\n"; + return 1; + } + + auto got = fb.sgetn(reinterpret_cast(&d2), sizeof d2); + if (sizeof(d2) != got) + std::cout << "Read of " << filename << " failed\\n"; + else + std::cout << "Read back from file: " << d2 << '\\n'; + } + +.SH Output: + + Read back from file: 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 596 C++98 open() could not open files in append can open in append mode + mode + +.SH See also + + is_open checks if the associated file is open + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP diff --git a/man/std::filebuf::operator=.3 b/man/std::filebuf::operator=.3 deleted file mode 120000 index d9f13e533..000000000 --- a/man/std::filebuf::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::operator=.3 \ No newline at end of file diff --git a/man/std::filebuf::operator=.3 b/man/std::filebuf::operator=.3 new file mode 100644 index 000000000..a0532ed24 --- /dev/null +++ b/man/std::filebuf::operator=.3 @@ -0,0 +1,64 @@ +.TH std::basic_filebuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::operator= \- std::basic_filebuf::operator= + +.SH Synopsis + std::basic_filebuf& operator=( std::basic_filebuf&& rhs ); \fB(1)\fP \fI(since C++11)\fP + std::basic_filebuf& operator=( const std::basic_filebuf& rhs ) = \fB(2)\fP + delete; + + Assigns another basic_filebuf object. + + 1) First calls close() to close the associated file, then moves the contents of rhs + into *this: the put and get buffers, the associated file, the locale, the openmode, + the is_open flag, and any other state. After the move, rhs is not associated with a + file and rhs.is_open() == false. + 2) The copy assignment operator is deleted; basic_filebuf is not CopyAssignable. + +.SH Parameters + + rhs - another basic_filebuf that will be moved from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ofstream{"test.in"} << "test\\n"; // writes via a temporary object + std::ifstream fin("test.in"); // read-only stream + std::ofstream fout("test.out"); // write-only stream + + std::string s; + std::getline(fin, s); + std::cout << "s = [" << s << "]\\n"; // s contains "test" + + assert(fout.is_open()); + *fin.rdbuf() = std::move(*fout.rdbuf()); + assert(!fout.is_open()); + + std::getline(fin, s); + std::cout << "s = [" << s << "]\\n"; // s is empty input + } + +.SH Output: + + s = [test] + s = [] + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::filebuf::overflow.3 b/man/std::filebuf::overflow.3 deleted file mode 120000 index d0686b770..000000000 --- a/man/std::filebuf::overflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::overflow.3 \ No newline at end of file diff --git a/man/std::filebuf::overflow.3 b/man/std::filebuf::overflow.3 new file mode 100644 index 000000000..4136ce654 --- /dev/null +++ b/man/std::filebuf::overflow.3 @@ -0,0 +1,49 @@ +.TH std::basic_filebuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::overflow \- std::basic_filebuf::overflow + +.SH Synopsis + protected: + virtual int_type overflow ( int_type c = Traits::eof() ); + + Writes some data from the put area to the associated character sequence (to the + file). + + Behaves like the base class std::basic_streambuf::overflow, except that to write the + data, first uses std::codecvt::out of the imbued locale to convert the characters + into external (possibly multibyte) representation, stored in a temporary buffer + (allocated as large as necessary), then uses file I/O to copy all fully-converted + bytes into the file. + + If std::codecvt::always_noconv is true, the call to std::codecvt::out may be + skipped. + + If the conversion fails with std::codecvt_base::error, returns Traits::eof() without + attempting any output. + + If the associated file is not open (is_open() == false), returns Traits::eof() + before doing anything. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Traits::not_eof(c) to indicate success or Traits::eof() to indicate failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::pbackfail.3 b/man/std::filebuf::pbackfail.3 deleted file mode 120000 index 952f18032..000000000 --- a/man/std::filebuf::pbackfail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::pbackfail.3 \ No newline at end of file diff --git a/man/std::filebuf::pbackfail.3 b/man/std::filebuf::pbackfail.3 new file mode 100644 index 000000000..6fde947cd --- /dev/null +++ b/man/std::filebuf::pbackfail.3 @@ -0,0 +1,67 @@ +.TH std::basic_filebuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::pbackfail \- std::basic_filebuf::pbackfail + +.SH Synopsis + protected: + virtual int_type pbackfail( int_type c = Traits::eof() ) + + This protected virtual function is called by the public functions + basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called + by basic_istream::unget and basic_istream::putback). + + 1) The caller is requesting that the get area is backed up by one character + (pbackfail() is called with no arguments), in which case, this function re-reads the + file starting one byte earlier and decrements basic_streambuf::gptr(), e.g. by + calling gbump(-1). + 2) The caller attempts to putback a different character from the one retrieved + earlier (pbackfail() is called with the character that needs to be put back), in + which case + a) First, checks if there is a putback position, and if there isn't, backs up the + get area by re-reading the file starting one byte earlier. + a) Then checks what character is in the putback position. If the character held + there is already equal to c, as determined by Traits::eq(to_char_type(c), + gptr()[-1]), then simply decrements basic_streambuf::gptr(). + b) Otherwise, if the buffer is allowed to modify its own get area, decrements + basic_streambuf::gptr() and writes c to the location pointed to gptr() after + adjustment. + + This function never modifies the file, only the get area of the in-memory buffer. + + If the file is not open (is_open()==false, this function returns Traits::eof() + immediately. + +.SH Parameters + + c - the character to put back, or Traits::eof() to indicate that backing up of the + get area is requested + +.SH Return value + + c on success except if c was Traits::eof(), in which case Traits::not_eof(c) is + returned. + + Traits::eof() on failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function of std::basic_streambuf)\fP + sputbackc puts one character back in the input sequence + \fI(public member function of std::basic_streambuf)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::seekoff.3 b/man/std::filebuf::seekoff.3 deleted file mode 120000 index fe8922894..000000000 --- a/man/std::filebuf::seekoff.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::seekoff.3 \ No newline at end of file diff --git a/man/std::filebuf::seekoff.3 b/man/std::filebuf::seekoff.3 new file mode 100644 index 000000000..2ce6f772b --- /dev/null +++ b/man/std::filebuf::seekoff.3 @@ -0,0 +1,141 @@ +.TH std::basic_filebuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::seekoff \- std::basic_filebuf::seekoff + +.SH Synopsis + protected: + + virtual pos_type seekoff( off_type off, + std::ios_base::seekdir dir, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions the file pointer, if possible, to the position that corresponds to + exactly off characters from beginning, end, or current position of the file + (depending on the value of dir). + + If the associated file is not open (is_open() == false), fails immediately. + + If the multibyte character encoding is state-dependent (codecvt::encoding() returned + -1) or variable-length (codecvt::encoding() returned 0) and the offset off is not 0, + fails immediately: this function cannot determine the number of bytes that + correspond to off characters. + + If dir is not std::basic_ios::cur or the offset off is not 0, and the most recent + operation done on this filebuf object was output (that is, either the put buffer is + not empty, or the most recently called function was overflow()), then calls + std::codecvt::unshift to determine the unshift sequence necessary, and writes that + sequence to the file by calling overflow(). + + Then converts the argument dir to a value whence of type int as follows: + + value of dir value of whence + std::basic_ios::beg SEEK_SET + std::basic_ios::end SEEK_END + std::basic_ios::cur SEEK_CUR + + Then, if the character encoding is fixed-width (codecvt::encoding() returns some + positive number width), moves the file pointer as if by std::fseek(file, width*off, + whence). + + Otherwise, moves the file pointer as if by std::fseek(file, 0, whence). + + The openmode argument, required by the base class function signature, is usually + ignored, because std::basic_filebuf maintains only one file position. + +.SH Parameters + + off - relative position to set the position indicator to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + A newly constructed object of type pos_type which stores the resulting file + position, or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekoff() is called by std::basic_streambuf::pubseekoff, which is called by + std::basic_istream::seekg, std::basic_ostream::seekp, std::basic_istream::tellg, and + std::basic_ostream::tellp. + +.SH Example + + +// Run this code + + #include + #include + #include + + template + int get_encoding(const std::basic_istream& stream) + { + using Facet = std::codecvt; + return std::use_facet(stream.getloc()).encoding(); + } + + int main() + { + // prepare a 10-byte file holding 4 characters ("zß水𝄋") in UTF-8 + std::ofstream("text.txt") << "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + + // open using a non-converting encoding + std::ifstream f1("text.txt"); + std::cout << "f1's locale's encoding() returns " + << get_encoding(f1) << '\\n' + << "pubseekoff(3, beg) returns " + << f1.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' + << "pubseekoff(0, end) returns " + << f1.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; + + // open using UTF-8 + std::wifstream f2("text.txt"); + f2.imbue(std::locale("en_US.UTF-8")); + std::cout << "f2's locale's encoding() returns " + << get_encoding(f2) << '\\n' + << "pubseekoff(3, beg) returns " + << f2.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' + << "pubseekoff(0, end) returns " + << f2.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; + } + +.SH Output: + + f1's locale's encoding() returns 1 + pubseekoff(3, beg) returns 3 + pubseekoff(0, end) returns 10 + f2's locale's encoding() returns 0 + pubseekoff(3, beg) returns -1 + pubseekoff(0, end) returns 10 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + fseek moves the file position indicator to a specific location in a file + \fI(function)\fP diff --git a/man/std::filebuf::seekpos.3 b/man/std::filebuf::seekpos.3 deleted file mode 120000 index 4364ae51f..000000000 --- a/man/std::filebuf::seekpos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::seekpos.3 \ No newline at end of file diff --git a/man/std::filebuf::seekpos.3 b/man/std::filebuf::seekpos.3 new file mode 100644 index 000000000..8996817bc --- /dev/null +++ b/man/std::filebuf::seekpos.3 @@ -0,0 +1,118 @@ +.TH std::basic_filebuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::seekpos \- std::basic_filebuf::seekpos + +.SH Synopsis + protected: + + virtual pos_type seekpos( pos_type sp, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions the file pointer, if possible, to the position indicated by sp. If the + associated file is not open (is_open() == false), fails immediately. + + Reposition performs as follows: + + 1) If the file is open for writing, writes the put area and any unshift sequences + required by the currently imbued locale, using overflow(). + 2) Repositions the file pointer, as if by calling std::fsetpos(). + 3) If the file is open for reading, updates the get area if necessary. + + If sp was not obtained by calling seekoff() or seekpos() on the same file, the + behavior is undefined. + +.SH Parameters + + sp - file position obtained by seekoff() or seekpos() called earlier on the same + file + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + sp on success or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the + single-argument versions of std::basic_istream::seekg() and + std::basic_ostream::seekp(). + + Many implementations do not update the get area in seekpos(), delegating to + underflow() that is called by the next sgetc(). + +.SH Example + + On some implementations, the get area is emptied by seekpos() and the second + underflow() is necessary to observe the effects. + + +// Run this code + + #include + #include + + struct mybuf : std::filebuf + { + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::filebuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + // uncomment if get area is emptied by seekpos() + // std::filebuf::underflow(); + // std::cout << "after forced underflow(), size of the get area is " + // << egptr() - eback() << " with " + // << egptr() - gptr() << " read positions available.\\n"; + + return rc; + } + }; + + int main() + { + mybuf buf; + buf.open("test.txt", std::ios_base::in); + std::istream stream(&buf); + stream.get(); // read one char to force underflow() + stream.seekg(2); + } + +.SH Possible output: + + Before seekpos\fB(2)\fP, size of the get area is 110 with 109 read positions available. + seekpos() returns 2. + After the call, size of the get area is 110 with 108 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekpos returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + LWG 171 C++98 the sequence of the operations of made clear + reposition was not clear + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + fseek moves the file position indicator to a specific location in a file + \fI(function)\fP diff --git a/man/std::filebuf::setbuf.3 b/man/std::filebuf::setbuf.3 deleted file mode 120000 index afcf8b009..000000000 --- a/man/std::filebuf::setbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::setbuf.3 \ No newline at end of file diff --git a/man/std::filebuf::setbuf.3 b/man/std::filebuf::setbuf.3 new file mode 100644 index 000000000..1f795b151 --- /dev/null +++ b/man/std::filebuf::setbuf.3 @@ -0,0 +1,97 @@ +.TH std::basic_filebuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::setbuf \- std::basic_filebuf::setbuf + +.SH Synopsis + protected: + virtual std::basic_streambuf* setbuf( char_type* s, std::streamsize + n ) + + If s is a null pointer and n is zero, the filebuf becomes unbuffered for output, + meaning pbase() and pptr() are null and any output is immediately sent to file. + + Otherwise, a call to setbuf() replaces the internal buffer (the controlled character + sequence) with the user-supplied character array whose first element is pointed to + by s and allows this std::basic_filebuf object to use up to n bytes in that array + for buffering. + + This function is protected virtual, it may only be called through pubsetbuf() or + from member functions of a user-defined class derived from std::basic_filebuf. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer or null + n - the number of CharT elements in the user-provided buffer or zero + +.SH Return value + + this + +.SH Notes + + The conditions when this function may be used and the way in which the provided + buffer is used is implementation-defined. + + * GCC 4.6 libstdc++ + + setbuf() may only be called when the std::basic_filebuf is not associated with a + file (has no effect otherwise). With a user-provided buffer, reading from file reads + n-1 bytes at a time. + * Clang++3.0 libc++ + + setbuf() may be called after opening the file, but before any I/O (may crash + otherwise). With a user-provided buffer, reading from file reads largest multiples + of 4096 that fit in the buffer. + * Visual Studio 2010 + + setbuf() may be called at any time, even after some I/O took place. Current contents + of the buffer, if any, are lost. + + The standard does not define any behavior for this function except that setbuf(0, 0) + called before any I/O has taken place is required to set unbuffered output. + +.SH Example + + Provides a 10k buffer for reading. On linux, the strace utility may be used to + observe the actual number of bytes read. + + +// Run this code + + #include + #include + #include + + int main() + { + int cnt = 0; + std::ifstream file; + char buf[10241]; + + file.rdbuf()->pubsetbuf(buf, sizeof buf); + file.open("/usr/share/dict/words"); + + for (std::string line; getline(file, line);) + ++cnt; + std::cout << cnt << '\\n'; + } + +.SH Possible output: + + 356010 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 173 C++98 the type of n was misspecified as corrected to std::streamsize + int + +.SH See also + + pubsetbuf invokes setbuf() + \fI(public member function of std::basic_streambuf)\fP + setvbuf sets the buffer and its size for a file stream + \fI(function)\fP diff --git a/man/std::filebuf::showmanyc.3 b/man/std::filebuf::showmanyc.3 deleted file mode 120000 index 9031dd00d..000000000 --- a/man/std::filebuf::showmanyc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::showmanyc.3 \ No newline at end of file diff --git a/man/std::filebuf::showmanyc.3 b/man/std::filebuf::showmanyc.3 new file mode 100644 index 000000000..5bee45bae --- /dev/null +++ b/man/std::filebuf::showmanyc.3 @@ -0,0 +1,62 @@ +.TH std::basic_filebuf::showmanyc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::showmanyc \- std::basic_filebuf::showmanyc + +.SH Synopsis + protected: + virtual std::streamsize showmanyc() + + If implemented, returns the number of characters left to read from the file. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters available for reading from the file, or -1 if the end of + file was reached. + +.SH Notes + + This function is optional. If not implemented, this function returns 0 (since the + base class version std::basic_streambuf::showmanyc gets called) + + Whether implemented or not, this function is normally called by + std::basic_streambuf::in_avail if the get area is empty. + + The name of this function stands for "stream: how many characters?", so it is + pronounced "S how many C", rather than "show many C" + +.SH Example + + implementation test to see if showmanyc() is implemented for filebuf + + +// Run this code + + #include + #include + + struct mybuf : std::filebuf + { + using std::filebuf::showmanyc; + }; + + int main() + { + mybuf fin; + fin.open("main.cpp", std::ios_base::in); + std::cout << "showmanyc() returns " << fin.showmanyc() << '\\n'; + } + +.SH Possible output: + + showmanyc() returns 267 + +.SH See also + + in_avail obtains the number of characters immediately available in the get area + \fI(public member function of std::basic_streambuf)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::filebuf::swap.3 b/man/std::filebuf::swap.3 deleted file mode 120000 index 4ab9bb9ee..000000000 --- a/man/std::filebuf::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::swap.3 \ No newline at end of file diff --git a/man/std::filebuf::swap.3 b/man/std::filebuf::swap.3 new file mode 100644 index 000000000..cae59ea19 --- /dev/null +++ b/man/std::filebuf::swap.3 @@ -0,0 +1,55 @@ +.TH std::basic_filebuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::swap \- std::basic_filebuf::swap + +.SH Synopsis + void swap( std::basic_filebuf& rhs ); \fI(since C++11)\fP + + Swaps the state and the contents of *this and rhs. + +.SH Parameters + + rhs - another basic_filebuf + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called automatically when swapping std::fstream objects, it is + rarely necessary to call it directly. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream fin("test.in"); // read-only + std::ofstream fout("test.out"); // write-only + + std::string s; + getline(fin, s); + std::cout << s << '\\n'; // outputs the first line of test.in + + fin.rdbuf()->swap(*fout.rdbuf()); //swap the underlying buffers + + getline(fin, s); // fails: cannot read from a write-only filebuf + std::cout << s << '\\n'; // prints empty line + } + +.SH See also + + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + std::swap(std::basic_filebuf) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + swap swaps two file streams + \fI(C++11)\fP \fI\fI(public member\fP function of\fP + std::basic_fstream) diff --git a/man/std::filebuf::sync.3 b/man/std::filebuf::sync.3 deleted file mode 120000 index 640a566a2..000000000 --- a/man/std::filebuf::sync.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::sync.3 \ No newline at end of file diff --git a/man/std::filebuf::sync.3 b/man/std::filebuf::sync.3 new file mode 100644 index 000000000..f32ce2eaf --- /dev/null +++ b/man/std::filebuf::sync.3 @@ -0,0 +1,43 @@ +.TH std::basic_filebuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::sync \- std::basic_filebuf::sync + +.SH Synopsis + protected: + virtual int sync() + + If a put area exists (e.g. the file was opened for writing), calls overflow() to + write all pending output to the file, then flushes the file as if by calling + std::fflush. + + If a get area exists (e.g. the file was opened for reading), the effect is + implementation-defined. Typical implementation may empty out the get area and move + the current file position back by the corresponding number of bytes. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 0 in case of success, -1 in case of failure. + +.SH Notes + + sync() or its equivalent is implicitly called for output streams by close(), + seekoff(), and seekpos() and explicitly called by std::basic_streambuf::pubsync() + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pubsync invokes sync() + \fI(public member function of std::basic_streambuf)\fP + fflush synchronizes an output stream with the actual file + \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::uflow.3 b/man/std::filebuf::uflow.3 deleted file mode 120000 index f77660456..000000000 --- a/man/std::filebuf::uflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::uflow.3 \ No newline at end of file diff --git a/man/std::filebuf::uflow.3 b/man/std::filebuf::uflow.3 new file mode 100644 index 000000000..299084c3e --- /dev/null +++ b/man/std::filebuf::uflow.3 @@ -0,0 +1,39 @@ +.TH std::basic_filebuf::uflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::uflow \- std::basic_filebuf::uflow + +.SH Synopsis + protected: + virtual int_type uflow() + + Behaves like the underflow(), except that if underflow() succeeds (does not return + Traits::eof()), then advances the next pointer for the get area. In other words, + consumes one of the characters obtained by underflow(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character that was read and consumed in case of success, or + Traits::eof() in case of failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + reads characters from the associated input sequence to the get area and + uflow advances the next pointer + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filebuf::underflow.3 b/man/std::filebuf::underflow.3 deleted file mode 120000 index c24e46aa6..000000000 --- a/man/std::filebuf::underflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::underflow.3 \ No newline at end of file diff --git a/man/std::filebuf::underflow.3 b/man/std::filebuf::underflow.3 new file mode 100644 index 000000000..7dc11e56a --- /dev/null +++ b/man/std::filebuf::underflow.3 @@ -0,0 +1,86 @@ +.TH std::basic_filebuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::underflow \- std::basic_filebuf::underflow + +.SH Synopsis + protected: + virtual int_type underflow() + + Reads more data into the input area. + + Behaves like the base class std::basic_streambuf::underflow, except that to read the + data from the associated character sequence (the file) into the get area, first + reads the bytes from the file into a temporary buffer (allocated as large as + necessary), then uses std::codecvt::in of the imbued locale to convert the external + (typically, multibyte) representation to the internal form which is then used to + populate the get area. The conversion may be skipped if the locale's + std::codecvt::always_noconv returns true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Traits::to_int_type(*gptr()) (the first character of the pending sequence) in case + of success, or Traits::eof() in case of failure. + +.SH Example + + +// Run this code + + #include + #include + + struct mybuf : std::filebuf + { + int underflow() + { + std::cout << "Before underflow(): size of the get area is " + << egptr()-eback() << " with " + << egptr()-gptr() << " read positions available\\n"; + int rc = std::filebuf::underflow(); + std::cout << "underflow() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr()-eback() << " with " + << egptr()-gptr() << " read positions available\\n"; + return rc; + } + }; + + int main() + { + mybuf buf; + buf.open("test.txt", std::ios_base::in); + std::istream stream(&buf); + while (stream.get()) ; + } + +.SH Possible output: + + Before underflow(): size of the get area is 0 with 0 read positions available + underflow() returns 73. + After the call, size of the get area is 110 with 110 read positions available + Before underflow(): size of the get area is 110 with 0 read positions available + underflow() returns -1. + After the call, size of the get area is 0 with 0 read positions available + +.SH See also + + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + underflow reads a character from the input sequence without advancing the next + \fB[virtual]\fP pointer + \fI(virtual protected member function of std::strstreambuf)\fP + uflow reads from the associated file and advances the next pointer in the get + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::filebuf::~basic_filebuf.3 b/man/std::filebuf::~basic_filebuf.3 deleted file mode 120000 index 571377e96..000000000 --- a/man/std::filebuf::~basic_filebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::~basic_filebuf.3 \ No newline at end of file diff --git a/man/std::filebuf::~basic_filebuf.3 b/man/std::filebuf::~basic_filebuf.3 new file mode 100644 index 000000000..788f635a4 --- /dev/null +++ b/man/std::filebuf::~basic_filebuf.3 @@ -0,0 +1,47 @@ +.TH std::basic_filebuf::~basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::~basic_filebuf \- std::basic_filebuf::~basic_filebuf + +.SH Synopsis + + virtual ~basic_filebuf(); + + Calls close() to close the associated file and destructs all other members of + basic_filebuf. If an exception occurs during the destruction of the object, + including the call to close(), it is caught and not rethrown. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Typically called by the destructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 622 C++98 it was unclear how to handle the exception it is caught but not + thrown during destruction rethrown + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::absolute.3 b/man/std::filesystem::absolute.3 new file mode 100644 index 000000000..496dc4536 --- /dev/null +++ b/man/std::filesystem::absolute.3 @@ -0,0 +1,74 @@ +.TH std::filesystem::absolute 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::absolute \- std::filesystem::absolute + +.SH Synopsis + Defined in header + path absolute( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + path absolute( const std::filesystem::path& p, std::error_code& ec \fB(2)\fP \fI(since C++17)\fP + ); + + Returns a path referencing the same file system location as p, for which + filesystem::path::is_absolute() is true. + + 2) This non-throwing overload returns default-constructed path if an error occurs. + +.SH Parameters + + p - path to convert to absolute form + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + Returns an absolute (although not necessarily canonical) pathname referencing the + same file as p. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Implementations are encouraged to not consider p not existing to be an error. + + For POSIX-based operating systems, std::filesystem::absolute(p) is equivalent to + std::filesystem::current_path() / p except for when p is the empty path. + + For Windows, std::filesystem::absolute may be implemented as a call to + GetFullPathNameW. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::filesystem::path p = "foo.c"; + std::cout << "Current path is " << std::filesystem::current_path() << '\\n'; + std::cout << "Absolute path for " << p << " is " << fs::absolute(p) << '\\n'; + } + +.SH Possible output: + + Current path is "/tmp/1666297965.0051296" + Absolute path for "foo.c" is "/tmp/1666297965.0051296/foo.c" + +.SH See also + + canonical composes a canonical path + weakly_canonical \fI(function)\fP + \fI(C++17)\fP + relative composes a relative path + proximate \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::begin(directory_iterator),std::filesystem::end(directory_iterator).3 b/man/std::filesystem::begin(directory_iterator),std::filesystem::end(directory_iterator).3 new file mode 100644 index 000000000..a20143f89 --- /dev/null +++ b/man/std::filesystem::begin(directory_iterator),std::filesystem::end(directory_iterator).3 @@ -0,0 +1,65 @@ +.TH std::filesystem::begin(directory_iterator),std::filesystem::end(directory_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::begin(directory_iterator),std::filesystem::end(directory_iterator) \- std::filesystem::begin(directory_iterator),std::filesystem::end(directory_iterator) + +.SH Synopsis + Defined in header + directory_iterator begin( directory_iterator iter ) noexcept; \fB(1)\fP \fI(since C++17)\fP + directory_iterator end( directory_iterator ) noexcept; \fB(2)\fP \fI(since C++17)\fP + + 1) Returns iter unchanged. + 2) Returns a default-constructed directory_iterator, which serves as the end + iterator. The argument is ignored. + + These non-member functions enable the use of directory_iterators with range-based + for loops + and make directory_iterator a range type + \fI(since C++20)\fP. + +.SH Parameters + + iter - a directory_iterator + +.SH Return value + + 1) iter unchanged. + 2) End iterator (default-constructed directory_iterator). + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::create_directories("sandbox/a/b"); + std::ofstream("sandbox/file1.txt"); + std::ofstream("sandbox/file2.txt"); + for (auto& p : fs::directory_iterator("sandbox")) + std::cout << p << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/a" + "sandbox/file1.txt" + "sandbox/file2.txt" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3480 C++17 end took the argument by reference takes the argument by value + +.SH See also + + begin(std::filesystem::recursive_directory_iterator) range-based for loop support + end(std::filesystem::recursive_directory_iterator) \fI(function)\fP diff --git a/man/std::filesystem::begin(recursive_directory_iterator),.3 b/man/std::filesystem::begin(recursive_directory_iterator),.3 new file mode 100644 index 000000000..ec2bdb3f2 --- /dev/null +++ b/man/std::filesystem::begin(recursive_directory_iterator),.3 @@ -0,0 +1,86 @@ +.TH std::filesystem::begin(recursive_directory_iterator), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::begin(recursive_directory_iterator), \- std::filesystem::begin(recursive_directory_iterator), + +.SH Synopsis + + Defined in header + recursive_directory_iterator begin( recursive_directory_iterator \fB(1)\fP \fI(since C++17)\fP + iter ) noexcept; + recursive_directory_iterator end( recursive_directory_iterator ) \fB(2)\fP \fI(since C++17)\fP + noexcept; + + 1) Returns iter unchanged. + 2) Returns a default-constructed recursive_directory_iterator, which serves as the + end iterator. The argument is ignored. + + These non-member functions enable the use of recursive_directory_iterators with + range-based for loops + and make recursive_directory_iterator a range type + \fI(since C++20)\fP. + +.SH Parameters + + iter - a recursive_directory_iterator + +.SH Return value + + 1) iter unchanged. + 2) End iterator (default-constructed recursive_directory_iterator). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::current_path(fs::temp_directory_path()); + fs::create_directories("sandbox/a/b"); + std::ofstream("sandbox/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + + std::cout << "Print dir structure using OS specific command 'tree':\\n"; + std::system("tree --noreport sandbox"); + + std::cout << "\\nPrint dir structure using directory iterator:\\n"; + for (auto& p : fs::recursive_directory_iterator("sandbox")) + std::cout << p << '\\n'; + + fs::remove_all("sandbox"); + } + +.SH Possible output: + + Print dir structure using OS specific command 'tree': + sandbox + ├── a + │ └── b + ├── file1.txt + └── syma -> a + + Print dir structure using directory iterator: + "sandbox/syma" + "sandbox/file1.txt" + "sandbox/a" + "sandbox/a/b" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3480 C++17 end took the argument by reference takes the argument by value + +.SH See also + + begin(std::filesystem::directory_iterator) range-based for loop support + end(std::filesystem::directory_iterator) \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::canonical,std::filesystem::weakly_canonical.3 b/man/std::filesystem::canonical,std::filesystem::weakly_canonical.3 new file mode 100644 index 000000000..e42480254 --- /dev/null +++ b/man/std::filesystem::canonical,std::filesystem::weakly_canonical.3 @@ -0,0 +1,132 @@ +.TH std::filesystem::canonical,std::filesystem::weakly_canonical 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::canonical,std::filesystem::weakly_canonical \- std::filesystem::canonical,std::filesystem::weakly_canonical + +.SH Synopsis + Defined in header + path canonical( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + path canonical( const std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ); + path weakly_canonical( const std::filesystem::path& p ); \fB(3)\fP \fI(since C++17)\fP + path weakly_canonical( const std::filesystem::path& p, \fB(4)\fP \fI(since C++17)\fP + std::error_code& ec ); + + 1,2) Converts path p to a canonical absolute path, i.e. an absolute path that has no + dot, dot-dot elements or symbolic links in its generic format representation. If p + is not an absolute path, the function behaves as if it is first made absolute by + std::filesystem::absolute(p). The path p must exist. + 3,4) Returns a path composed by operator/= from the result of calling canonical() + with a path argument composed of the leading elements of p that exist (as determined + by status(p) or status(p, ec)), if any, followed by the elements of p that do not + exist. The resulting path is in normal form. + +.SH Parameters + + p - a path which may be absolute or relative; for canonical it must be an existing + path + ec - error code to store error status to + +.SH Return value + + 1,2) An absolute path that resolves to the same file as + std::filesystem::absolute(p). + 3,4) A normal path of the form canonical(x)/y, where x is a path composed of the + longest leading sequence of elements in p that exist, and y is a path composed of + the remaining trailing non-existent elements of p. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The function canonical() is modeled after the POSIX realpath. + + The function weakly_canonical() was introduced to simplify operational semantics of + relative(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + /* set up sandbox directories: + a + └── b + ├── c1 + │ └── d <== current path + └── c2 + └── e + */ + auto old = std::filesystem::current_path(); + auto tmp = std::filesystem::temp_directory_path(); + std::filesystem::current_path(tmp); + auto d1 = tmp / "a/b/c1/d"; + auto d2 = tmp / "a/b/c2/e"; + std::filesystem::create_directories(d1); + std::filesystem::create_directories(d2); + std::filesystem::current_path(d1); + + auto p1 = std::filesystem::path("../../c2/./e"); + auto p2 = std::filesystem::path("../no-such-file"); + std::cout << "Current path is " + << std::filesystem::current_path() << '\\n' + << "Canonical path for " << p1 << " is " + << std::filesystem::canonical(p1) << '\\n' + << "Weakly canonical path for " << p2 << " is " + << std::filesystem::weakly_canonical(p2) << '\\n'; + try + { + [[maybe_unused]] auto x_x = std::filesystem::canonical(p2); + // NOT REACHED + } + catch (const std::exception& ex) + { + std::cout << "Canonical path for " << p2 << " threw exception:\\n" + << ex.what() << '\\n'; + } + + // cleanup + std::filesystem::current_path(old); + const auto count = std::filesystem::remove_all(tmp / "a"); + std::cout << "Deleted " << count << " files or directories.\\n"; + } + +.SH Possible output: + + Current path is "/tmp/a/b/c1/d" + Canonical path for "../../c2/./e" is "/tmp/a/b/c2/e" + Weakly canonical path for "../no-such-file" is "/tmp/a/b/c1/no-such-file" + Canonical path for "../no-such-file" threw exception: + filesystem error: in canonical: No such file or directory [../no-such-file] [/tmp/a/b/c1/d] + Deleted 6 files or directories. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2956 C++17 canonical has a spurious base parameter removed + +.SH See also + + path represents a path + \fI(C++17)\fP \fI(class)\fP + absolute composes an absolute path + \fI(C++17)\fP \fI(function)\fP + relative composes a relative path + proximate \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::copy.3 b/man/std::filesystem::copy.3 new file mode 100644 index 000000000..d1d239347 --- /dev/null +++ b/man/std::filesystem::copy.3 @@ -0,0 +1,199 @@ +.TH std::filesystem::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::copy \- std::filesystem::copy + +.SH Synopsis + Defined in header + void copy( const std::filesystem::path& from, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& to ); + void copy( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ); + void copy( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(3)\fP \fI(since C++17)\fP + + std::filesystem::copy_options options ); + void copy( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(4)\fP \fI(since C++17)\fP + std::filesystem::copy_options options, + + std::error_code& ec ); + + Copies files and directories, with a variety of options. + + 1,2) The default, equivalent to (3,4) with copy_options::none used as options. + 3,4) Copies the file or directory from to file or directory to, using the copy + options indicated by options. The behavior is undefined if there is more than one + option in any of the copy_options option group present in options (even in the + copy_file group). + + The behavior is as follows: + + * First, before doing anything else, obtains type and permissions of from by no + more than a single call to + + * std::filesystem::symlink_status, if copy_options::skip_symlinks, + copy_options::copy_symlinks, or copy_options::create_symlinks is present in + options; + * std::filesystem::status otherwise. + * If necessary, obtains the status of to, by no more than a single call to + + * std::filesystem::symlink_status, if copy_options::skip_symlinks or + copy_options::create_symlinks is present in options; + * std::filesystem::status otherwise (including the case where + copy_options::copy_symlinks is present in options). + * If either from or to has an implementation-defined file type, the effects of + this function are implementation-defined. + * If from does not exist, reports an error. + * If from and to are the same file as determined by std::filesystem::equivalent, + reports an error. + * If either from or to is not a regular file, a directory, or a symlink, as + determined by std::filesystem::is_other, reports an error. + * If from is a directory, but to is a regular file, reports an error. + * If from is a symbolic link, then + + * If copy_options::skip_symlink is present in options, does nothing. + * Otherwise, if to does not exist and copy_options::copy_symlinks is present in + options, then behaves as if copy_symlink(from, to). + * Otherwise, reports an error. + * Otherwise, if from is a regular file, then + + * If copy_options::directories_only is present in options, does nothing. + * Otherwise, if copy_options::create_symlinks is present in options, creates a + symlink to to. Note: from must be an absolute path unless to is in the current + directory. + * Otherwise, if copy_options::create_hard_links is present in options, creates a + hard link to to. + * Otherwise, if to is a directory, then behaves as if copy_file(from, + to/from.filename(), options) (creates a copy of from as a file in the directory + to). + * Otherwise, behaves as if copy_file(from, to, options) (copies the file). + * Otherwise, if from is a directory and copy_options::create_symlinks is set in + options, reports an error with an error code equal to + std::make_error_code(std::errc::is_a_directory). + * Otherwise, if from is a directory and either options has copy_options::recursive + or is copy_options::none, + + * If to does not exist, first executes create_directory(to, from) (creates the new + directory with a copy of the old directory's attributes). + * Then, whether to already existed or was just created, iterates over the files + contained in from as if by for (const std::filesystem::directory_entry& x : + std::filesystem::directory_iterator(from)) and for each directory entry, + recursively calls copy(x.path(), to/x.path().filename(), options | + in-recursive-copy), where in-recursive-copy is a special bit that has no other + effect when set in options. (The sole purpose of setting this bit is to prevent + recursive copying subdirectories if options is copy_options::none.) + * Otherwise does nothing. + +.SH Parameters + + from - path to the source file, directory, or symlink + to - path to the target file, directory, or symlink + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with from as the first path argument, to as the second path argument, + and the OS error code as the error code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The default behavior when copying directories is the non-recursive copy: the files + are copied, but not the subdirectories: + + // Given + // /dir1 contains /dir1/file1, /dir1/file2, /dir1/dir2 + // and /dir1/dir2 contains /dir1/dir2/file3 + // After + std::filesystem::copy("/dir1", "/dir3"); + // /dir3 is created (with the attributes of /dir1) + // /dir1/file1 is copied to /dir3/file1 + // /dir1/file2 is copied to /dir3/file2 + + While with copy_options::recursive, the subdirectories are also copied, with their + content, recursively. + + // ...but after + std::filesystem::copy("/dir1", "/dir3", std::filesystem::copy_options::recursive); + // /dir3 is created (with the attributes of /dir1) + // /dir1/file1 is copied to /dir3/file1 + // /dir1/file2 is copied to /dir3/file2 + // /dir3/dir2 is created (with the attributes of /dir1/dir2) + // /dir1/dir2/file3 is copied to /dir3/dir2/file3 + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::create_directories("sandbox/dir/subdir"); + std::ofstream("sandbox/file1.txt").put('a'); + fs::copy("sandbox/file1.txt", "sandbox/file2.txt"); // copy file + fs::copy("sandbox/dir", "sandbox/dir2"); // copy directory (non-recursive) + const auto copyOptions = fs::copy_options::update_existing + | fs::copy_options::recursive + | fs::copy_options::directories_only + ; + fs::copy("sandbox", "sandbox_copy", copyOptions); + static_cast(std::system("tree")); + fs::remove_all("sandbox"); + fs::remove_all("sandbox_copy"); + } + +.SH Possible output: + + . + ├── sandbox + │ ├── dir + │ │ └── subdir + │ ├── dir2 + │ ├── file1.txt + │ └── file2.txt + └── sandbox_copy + ├── dir + │ └── subdir + └── dir2 + + 8 directories, 2 files + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3013 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + LWG 2682 C++17 attempting to create a symlink for a directory reports an error + succeeds but does nothing + +.SH See also + + copy_options specifies semantics of copy operations + \fI(C++17)\fP \fI(enum)\fP + copy_symlink copies a symbolic link + \fI(C++17)\fP \fI(function)\fP + copy_file copies file contents + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::copy_file.3 b/man/std::filesystem::copy_file.3 new file mode 100644 index 000000000..b59fb8560 --- /dev/null +++ b/man/std::filesystem::copy_file.3 @@ -0,0 +1,144 @@ +.TH std::filesystem::copy_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::copy_file \- std::filesystem::copy_file + +.SH Synopsis + Defined in header + bool copy_file( const std::filesystem::path& from, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& to ); + bool copy_file( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ); + bool copy_file( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(3)\fP \fI(since C++17)\fP + + std::filesystem::copy_options options ); + bool copy_file( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(4)\fP \fI(since C++17)\fP + std::filesystem::copy_options options, + + std::error_code& ec ); + + 1,2) The default, equivalent to (3,4) with copy_options::none used as options. + 3,4) Copies a single file from from to to, using the copy options indicated by + options. The behavior is undefined if there is more than one option in any of the + copy_options option group present in options (even in the groups not relevant to + filesystem::copy_file). + * If !filesystem::is_regular_file(from) (either because the source file doesn't + exist or because it is not a regular file), report an error. + * Otherwise, if the destination file does not exist, + + * copies the contents and the attributes of the file to which from resolves to the + file to which to resolves (symlinks are followed). + * Otherwise, if the destination file already exists, + + * report an error if any of the following is true: + + * to and from are the same as determined by filesystem::equivalent(from, to); + * to is not a regular file as determined by !filesystem::is_regular_file(to); + * none of the filesystem::copy_file control options are set in options. + * Otherwise, if copy_options::skip_existing is set in options, do nothing. + * Otherwise, if copy_options::overwrite_existing is set in options, copy the + contents and the attributes of the file to which from resolves to the file to + which to resolves. + * Otherwise, if copy_options::update_existing is set in options, only copy the + file if from is newer than to, as defined by filesystem::last_write_time(). + + The non-throwing overloads return false if an error occurs. + +.SH Parameters + + from - path to the source file + to - path to the target file + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the file was copied, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with from as the first path argument, to as the second path argument, + and the OS error code as the error code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The functions involve at most one direct or indirect call to filesystem::status(to) + (used both to determine if the file exists, and, for + filesystem::copy_options::update_existing option, its last write time). + + Error is reported when filesystem::copy_file is used to copy a directory: use + filesystem::copy for that. + + filesystem::copy_file follows symlinks: use filesystem::copy_symlink or + filesystem::copy with filesystem::copy_options::copy_symlinks for that. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::create_directory("sandbox"); + std::ofstream("sandbox/file1.txt").put('a'); + + fs::copy_file("sandbox/file1.txt", "sandbox/file2.txt"); + + // now there are two files in sandbox: + std::cout << "file1.txt holds: " + << std::ifstream("sandbox/file1.txt").rdbuf() << '\\n'; + std::cout << "file2.txt holds: " + << std::ifstream("sandbox/file2.txt").rdbuf() << '\\n'; + + // fail to copy directory + fs::create_directory("sandbox/abc"); + try + { + fs::copy_file("sandbox/abc", "sandbox/def"); + } + catch (fs::filesystem_error& e) + { + std::cout << "Could not copy sandbox/abc: " << e.what() << '\\n'; + } + fs::remove_all("sandbox"); + } + +.SH Possible output: + + file1.txt holds: a + file2.txt holds: a + Could not copy sandbox/abc: copy_file: Is a directory: "sandbox/abc", "sandbox/def" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3014 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + +.SH See also + + copy_options specifies semantics of copy operations + \fI(C++17)\fP \fI(enum)\fP + copy_symlink copies a symbolic link + \fI(C++17)\fP \fI(function)\fP + copy copies files or directories + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::copy_options.3 b/man/std::filesystem::copy_options.3 new file mode 100644 index 000000000..2b7c2698f --- /dev/null +++ b/man/std::filesystem::copy_options.3 @@ -0,0 +1,107 @@ +.TH std::filesystem::copy_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::copy_options \- std::filesystem::copy_options + +.SH Synopsis + Defined in header + enum class copy_options { + + none = /* unspecified */, + skip_existing = /* unspecified */, + overwrite_existing = /* unspecified */, + update_existing = /* unspecified */, + recursive = /* unspecified */, \fI(since C++17)\fP + copy_symlinks = /* unspecified */, + skip_symlinks = /* unspecified */, + directories_only = /* unspecified */, + create_symlinks = /* unspecified */, + create_hard_links = /* unspecified */ + + }; + + This type represents available options that control the behavior of the copy() and + copy_file() function. + + copy_options satisfies the requirements of BitmaskType (which means the bitwise + operators operator&, operator|, operator^, operator~, operator&=, operator|=, and + operator^= are defined for this type). none represents the empty bitmask; every + other enumerator represents a distinct bitmask element. + +.SH Member constants + + At most one copy option in each of the following options groups may be present, + otherwise the behavior of the copy functions is undefined. + + Member constant Meaning + options controlling copy_file() when the file already exists + none Report an error (default behavior). + skip_existing Keep the existing file, without reporting an error. + overwrite_existing Replace the existing file. + update_existing Replace the existing file only if it is older than the file being + copied. + options controlling the effects of copy() on subdirectories + none Skip subdirectories (default behavior). + recursive Recursively copy subdirectories and their content. + options controlling the effects of copy() on symbolic links + none Follow symlinks (default behavior). + copy_symlinks Copy symlinks as symlinks, not as the files they point to. + skip_symlinks Ignore symlinks. + options controlling the kind of copying copy() does + none Copy file content (default behavior). + directories_only Copy the directory structure, but do not copy any non-directory + files. + Instead of creating copies of files, create symlinks pointing to + create_symlinks the originals. Note: the source path must be an absolute path + unless the destination path is in the current directory. + create_hard_links Instead of creating copies of files, create hardlinks that + resolve to the same files as the originals. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::create_directories("sandbox/dir/subdir"); + std::ofstream("sandbox/file1.txt").put('a'); + fs::copy("sandbox/file1.txt", "sandbox/file2.txt"); // copy file + fs::copy("sandbox/dir", "sandbox/dir2"); // copy directory (non-recursive) + const auto copyOptions = fs::copy_options::update_existing + | fs::copy_options::recursive + | fs::copy_options::directories_only + ; + fs::copy("sandbox", "sandbox_copy", copyOptions); + static_cast(std::system("tree")); + fs::remove_all("sandbox"); + fs::remove_all("sandbox_copy"); + } + +.SH Possible output: + + . + ├── sandbox + │ ├── dir + │ │ └── subdir + │ ├── dir2 + │ ├── file1.txt + │ └── file2.txt + └── sandbox_copy + ├── dir + │ └── subdir + └── dir2 + + 8 directories, 2 files + +.SH See also + + copy copies files or directories + \fI(C++17)\fP \fI(function)\fP + copy_file copies file contents + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::copy_symlink.3 b/man/std::filesystem::copy_symlink.3 new file mode 100644 index 000000000..4c8f62c04 --- /dev/null +++ b/man/std::filesystem::copy_symlink.3 @@ -0,0 +1,62 @@ +.TH std::filesystem::copy_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::copy_symlink \- std::filesystem::copy_symlink + +.SH Synopsis + Defined in header + void copy_symlink( const std::filesystem::path& from, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& to); + void copy_symlink( const std::filesystem::path& from, + + const std::filesystem::path& to, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + + Copies a symlink to another location. + + 1) Effectively calls f(read_symlink(from), to) where f is create_symlink or + create_directory_symlink depending on whether from resolves to a file or directory. + 2) Effectively calls f(read_symlink(from, ec), to, ec) where f is create_symlink or + create_directory_symlink depending on whether from resolves to a file or directory. + +.SH Parameters + + from - path to a symbolic link to copy + to - destination path of the new symlink + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with from as the first path argument, to as the second path argument, and the OS + error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + copy copies files or directories + \fI(C++17)\fP \fI(function)\fP + copy_file copies file contents + \fI(C++17)\fP \fI(function)\fP + create_symlink + create_directory_symlink creates a symbolic link + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + read_symlink obtains the target of a symbolic link + \fI(C++17)\fP \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::create_directory,std::filesystem::create_directories.3 b/man/std::filesystem::create_directory,std::filesystem::create_directories.3 new file mode 100644 index 000000000..77e9841bf --- /dev/null +++ b/man/std::filesystem::create_directory,std::filesystem::create_directories.3 @@ -0,0 +1,136 @@ +.TH std::filesystem::create_directory,std::filesystem::create_directories 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::create_directory,std::filesystem::create_directories \- std::filesystem::create_directory,std::filesystem::create_directories + +.SH Synopsis + Defined in header + bool create_directory( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + bool create_directory( const std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + bool create_directory( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + const std::filesystem::path& existing_p ); + bool create_directory( const std::filesystem::path& p, + + const std::filesystem::path& existing_p, \fB(4)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + bool create_directories( const std::filesystem::path& p ); \fB(5)\fP \fI(since C++17)\fP + bool create_directories( const std::filesystem::path& p, \fB(6)\fP \fI(since C++17)\fP + std::error_code& ec ); + + 1,2) Creates the directory p as if by POSIX mkdir() with a second argument of + static_cast(std::filesystem::perms::all) (the parent directory must already + exist). If the function fails because p resolves to an existing directory, no error + is reported. Otherwise on failure an error is reported. + 3,4) Same as (1,2), except that the attributes of the new directory are copied from + existing_p (which must be a directory that exists). It is OS-dependent which + attributes are copied: on POSIX systems, the attributes are copied as if by + + stat(existing_p.c_str(), &attributes_stat) + mkdir(p.c_str(), attributes_stat.st_mode) + + On Windows OS, no attributes of existing_p are copied. + 5,6) Executes (1,2) for every element of p that does not already exist. If p already + exists, the function does nothing (this condition is not treated as an error). + +.SH Parameters + + p - the path to the new directory to create + existing_p - the path to a directory to copy the attributes from + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if a directory was newly created for the directory p resolves to, false + otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,5) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 2,6) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + 3) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument, existing_p as the second path argument, and the + OS error code as the error code argument. + 4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The attribute-preserving overload (3,4) is implicitly invoked by copy() when + recursively copying directories. Its equivalent in boost.filesystem is + copy_directory (with argument order reversed). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::filesystem::current_path(std::filesystem::temp_directory_path()); + + // Basic usage + std::filesystem::create_directories("sandbox/1/2/a"); + std::filesystem::create_directory("sandbox/1/2/b"); + + // Directory already exists (false returned, no error) + assert(!std::filesystem::create_directory("sandbox/1/2/b")); + + // Permissions copying usage + std::filesystem::permissions( + "sandbox/1/2/b", + std::filesystem::perms::others_all, + std::filesystem::perm_options::remove + ); + std::filesystem::create_directory("sandbox/1/2/c", "sandbox/1/2/b"); + + std::system("ls -l sandbox/1/2"); + std::system("tree sandbox"); + std::filesystem::remove_all("sandbox"); + } + +.SH Possible output: + + drwxr-xr-x 2 user group 4096 Apr 15 09:33 a + drwxr-x--- 2 user group 4096 Apr 15 09:33 b + drwxr-x--- 2 user group 4096 Apr 15 09:33 c + sandbox + └── 1 + └── 2 + ├── a + ├── b + └── c + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2935 C++17 error if target already exists but is not a not error + directory + LWG 3014 C++17 error_code overload of create_directories noexcept removed + marked noexcept but can allocate memory + P1164R1 C++17 creation failure caused by an existing made error + non-directory file is not an error + +.SH See also + + create_symlink + create_directory_symlink creates a symbolic link + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + copy copies files or directories + \fI(C++17)\fP \fI(function)\fP + perms identifies file system permissions + \fI(C++17)\fP \fI(enum)\fP diff --git a/man/std::filesystem::create_hard_link.3 b/man/std::filesystem::create_hard_link.3 new file mode 100644 index 000000000..2d890e4b2 --- /dev/null +++ b/man/std::filesystem::create_hard_link.3 @@ -0,0 +1,95 @@ +.TH std::filesystem::create_hard_link 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::create_hard_link \- std::filesystem::create_hard_link + +.SH Synopsis + Defined in header + void create_hard_link( const std::filesystem::path& target, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& link ); + void create_hard_link( const std::filesystem::path& target, + + const std::filesystem::path& link, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + + Creates a hard link link with its target set to target as if by POSIX link(): the + pathname target must exist. + + Once created, link and target are two logical names that refer to the same file + (they are equivalent). Even if the original name target is deleted, the file + continues to exist and is accessible as link. + +.SH Parameters + + target - path of the file or directory to link to + link - path of the new hard link + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with target as the first path argument, link as the second path argument, and the OS + error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Some operating systems do not support hard links at all or support them only for + regular files. + + Some file systems do not support hard links regardless of the operating system: the + FAT file system used on memory cards and flash drives, for example. + + Some file systems limit the number of links per file. + + Hardlinking to directories is typically restricted to the superuser. + + Hard links typically cannot cross filesystem boundaries. + + The special pathname dot (".") is a hard link to its parent directory. The special + pathname dot-dot ".." is a hard link to the directory that is the parent of its + parent. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::create_directories("sandbox/subdir"); + std::ofstream("sandbox/a").put('a'); // create regular file + fs::create_hard_link("sandbox/a", "sandbox/b"); + fs::remove("sandbox/a"); + // read from the original file via surviving hard link + char c = std::ifstream("sandbox/b").get(); + std::cout << c << '\\n'; + fs::remove_all("sandbox"); + } + +.SH Output: + + a + +.SH See also + + create_symlink + create_directory_symlink creates a symbolic link + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + hard_link_count returns the number of hard links referring to the specific + \fI(C++17)\fP file + \fI(function)\fP diff --git a/man/std::filesystem::create_symlink,std::filesystem::create_directory_symlink.3 b/man/std::filesystem::create_symlink,std::filesystem::create_directory_symlink.3 new file mode 100644 index 000000000..ac3858213 --- /dev/null +++ b/man/std::filesystem::create_symlink,std::filesystem::create_directory_symlink.3 @@ -0,0 +1,105 @@ +.TH std::filesystem::create_symlink,std::filesystem::create_directory_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::create_symlink,std::filesystem::create_directory_symlink \- std::filesystem::create_symlink,std::filesystem::create_directory_symlink + +.SH Synopsis + Defined in header + void create_symlink( const std::filesystem::path& target, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& link ); + void create_symlink( const std::filesystem::path& target, + + const std::filesystem::path& link, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + void create_directory_symlink( const std::filesystem::path& + target, \fB(3)\fP \fI(since C++17)\fP + const std::filesystem::path& link + ); + void create_directory_symlink( const std::filesystem::path& + target, + \fB(4)\fP \fI(since C++17)\fP + const std::filesystem::path& link, + + std::error_code& ec ) noexcept; + + Creates a symbolic link link with its target set to target as if by POSIX symlink(): + the pathname target may be invalid or non-existing. + + Some operating systems require symlink creation to identify that the link is to a + directory. Portable code should use (3,4) to create directory symlinks rather than + (1,2), even though there is no distinction on POSIX systems. + +.SH Parameters + + target - path to point the symlink to, does not have to exist + link - path of the new symbolic link + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with target as the first path argument, link as the second path + argument, and the OS error code as the error code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Some operating systems do not support symbolic links at all or support them only for + regular files. + + Some file systems do not support symbolic links regardless of the operating system, + for example the FAT system used on some memory cards and flash drives. + + Like a hard link, a symbolic link allows a file to have multiple logical names. The + presence of a hard link guarantees the existence of a file, even after the original + name has been removed. A symbolic link provides no such assurance; in fact, the file + named by the target argument need not exist when the link is created. A symbolic + link can cross file system boundaries. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::create_directories("sandbox/subdir"); + fs::create_symlink("target", "sandbox/sym1"); + fs::create_directory_symlink("subdir", "sandbox/sym2"); + + for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it) + if (is_symlink(it->symlink_status())) + std::cout << *it << "->" << read_symlink(*it) << '\\n'; + + assert(std::filesystem::equivalent("sandbox/sym2", "sandbox/subdir")); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/sym1"->"target" + "sandbox/sym2"->"subdir" + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + read_symlink obtains the target of a symbolic link + \fI(C++17)\fP \fI(function)\fP + create_hard_link creates a hard link + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::current_path.3 b/man/std::filesystem::current_path.3 new file mode 100644 index 000000000..d7883bcd4 --- /dev/null +++ b/man/std::filesystem::current_path.3 @@ -0,0 +1,76 @@ +.TH std::filesystem::current_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::current_path \- std::filesystem::current_path + +.SH Synopsis + Defined in header + path current_path(); \fB(1)\fP \fI(since C++17)\fP + path current_path( std::error_code& ec ); \fB(2)\fP \fI(since C++17)\fP + void current_path( const std::filesystem::path& p ); \fB(3)\fP \fI(since C++17)\fP + void current_path( const std::filesystem::path& p, \fB(4)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Returns or changes the current path. + + 1,2) Returns the absolute path of the current working directory, obtained as if (in + native format) by POSIX getcwd. \fB(2)\fP returns path() if error occurs. + 3,4) Changes the current working directory to p, as if by POSIX chdir. + +.SH Parameters + + p - path to change the current working directory to + ec - out-parameter for error reporting in the non-throwing overloads + +.SH Return value + + 1,2) Returns the current working directory. + 3,4) \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + 3) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The current working directory is the directory, associated with the process, that is + used as the starting location in pathname resolution for relative paths. + + The current path as returned by many operating systems is a dangerous global + variable. It may be changed unexpectedly by third-party or system library functions, + or by another thread. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << "Current path is " << fs::current_path() << '\\n'; // (1) + fs::current_path(fs::temp_directory_path()); // (3) + std::cout << "Current path is " << fs::current_path() << '\\n'; + } + +.SH Possible output: + + Current path is "D:/local/ConsoleApplication1" + Current path is "E:/Temp" + +.SH See also + + temp_directory_path returns a directory suitable for temporary files + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry.3 b/man/std::filesystem::directory_entry.3 new file mode 100644 index 000000000..f97beba3a --- /dev/null +++ b/man/std::filesystem::directory_entry.3 @@ -0,0 +1,88 @@ +.TH std::filesystem::directory_entry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry \- std::filesystem::directory_entry + +.SH Synopsis + Defined in header + class directory_entry; \fI(since C++17)\fP + + Represents a directory entry. The object stores a path as a member and may also + store additional file attributes (hard link count, status, symlink status, file + size, and last write time) during directory iteration. + +.SH Member functions + + constructor constructs a directory entry + \fI(public member function)\fP + destructor default destructor + \fI(public member function)\fP +.SH Modifiers + operator= assigns contents + \fI(public member function)\fP + assign assigns contents + \fI(public member function)\fP + replace_filename sets the filename + \fI(public member function)\fP + refresh updates the cached file attributes + \fI(public member function)\fP +.SH Observers + path returns the path the entry refers to + operator const path& \fI(public member function)\fP + checks whether directory entry refers to existing file system + exists object + \fI(public member function)\fP + is_block_file checks whether the directory entry refers to block device + \fI(public member function)\fP + is_character_file checks whether the directory entry refers to a character device + \fI(public member function)\fP + is_directory checks whether the directory entry refers to a directory + \fI(public member function)\fP + is_fifo checks whether the directory entry refers to a named pipe + \fI(public member function)\fP + is_other checks whether the directory entry refers to an other file + \fI(public member function)\fP + is_regular_file checks whether the directory entry refers to a regular file + \fI(public member function)\fP + is_socket checks whether the directory entry refers to a named IPC socket + \fI(public member function)\fP + is_symlink checks whether the directory entry refers to a symbolic link + \fI(public member function)\fP + returns the size of the file to which the directory entry + file_size refers + \fI(public member function)\fP + returns the number of hard links referring to the file to which + hard_link_count the directory entry refers + \fI(public member function)\fP + gets the time of the last data modification of the file to + last_write_time which the directory entry refers + \fI(public member function)\fP + status status of the file designated by this directory entry; + symlink_status status of the file/symlink designated by this directory entry + \fI(public member function)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= compares two directory entries + operator<=> \fI(public member function)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + +.SH Non-member functions + + operator<< performs stream output on a directory entry + \fI(function)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3171 C++17 directory_entry couldn't be inserted by output enabled again + operator<< because of LWG2989 diff --git a/man/std::filesystem::directory_entry::assign.3 b/man/std::filesystem::directory_entry::assign.3 new file mode 100644 index 000000000..0297a51cc --- /dev/null +++ b/man/std::filesystem::directory_entry::assign.3 @@ -0,0 +1,95 @@ +.TH std::filesystem::directory_entry::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::assign \- std::filesystem::directory_entry::assign + +.SH Synopsis + void assign( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + void assign( const std::filesystem::path& p, std::error_code& ec \fB(2)\fP \fI(since C++17)\fP + ); + + Assigns new content to the directory entry object. Sets the path to p and calls + refresh to update the cached attributes. If an error occurs, the values of the + cached attributes are unspecified. + + This function does not commit any changes to the filesystem. + +.SH Parameters + + p - path to the filesystem object to which the directory entry will refer + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_entry_info(const std::filesystem::directory_entry& entry) + { + if (std::cout << "The entry " << entry; not entry.exists()) + { + std::cout << " does not exists on the file system\\n"; + return; + } + std::cout << " is "; + if (entry.is_directory()) + std::cout << "a directory\\n"; + if (entry.is_regular_file()) + std::cout << "a regular file\\n"; + /*...*/ + } + + int main() + { + std::filesystem::current_path(std::filesystem::temp_directory_path()); + + std::filesystem::directory_entry entry{std::filesystem::current_path()}; + print_entry_info(entry); + + std::filesystem::path name{"cppreference.html"}; + std::ofstream{name} << "C++"; + + std::cout << "entry.assign();\\n"; + entry.assign(entry/name); + print_entry_info(entry); + + std::cout << "remove(entry);\\n"; + std::filesystem::remove(entry); + print_entry_info(entry); // the entry still contains old "state" + + std::cout << "entry.assign();\\n"; + entry.assign(entry); // or just call entry.refresh() + print_entry_info(entry); + } + +.SH Possible output: + + The entry "/tmp" is a directory + entry.assign(); + The entry "/tmp/cppreference.html" is a regular file + remove(entry); + The entry "/tmp/cppreference.html" is a regular file + entry.assign(); + The entry "/tmp/cppreference.html" does not exists on the file system + +.SH See also + + operator= assigns contents + \fI(public member function)\fP diff --git a/man/std::filesystem::directory_entry::directory_entry.3 b/man/std::filesystem::directory_entry::directory_entry.3 new file mode 100644 index 000000000..04ebbe563 --- /dev/null +++ b/man/std::filesystem::directory_entry::directory_entry.3 @@ -0,0 +1,44 @@ +.TH std::filesystem::directory_entry::directory_entry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::directory_entry \- std::filesystem::directory_entry::directory_entry + +.SH Synopsis + directory_entry() noexcept = default; \fB(1)\fP \fI(since C++17)\fP + directory_entry( const directory_entry& ) = default; \fB(2)\fP \fI(since C++17)\fP + directory_entry( directory_entry&& ) noexcept = default; \fB(3)\fP \fI(since C++17)\fP + explicit directory_entry( const std::filesystem::path& p ); \fB(4)\fP \fI(since C++17)\fP + directory_entry( const std::filesystem::path& p, std::error_code& \fB(5)\fP \fI(since C++17)\fP + ec ); + + Constructs a new directory_entry object. + + 1) Default constructor. + 2) Defaulted copy constructor. + 3) Defaulted move constructor. + 4,5) Initializes the directory entry with path p and calls refresh to update the + cached attributes. If an error occurs, the non-throwing overload leaves the + directory_entry holding a default-constructed path. + +.SH Parameters + + p - path to the filesystem object to which the directory entry will refer + ec - out-parameter for error reporting in the non-throwing overload + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1-4) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 5) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::directory_entry::exists.3 b/man/std::filesystem::directory_entry::exists.3 new file mode 100644 index 000000000..8c409c2b9 --- /dev/null +++ b/man/std::filesystem::directory_entry::exists.3 @@ -0,0 +1,74 @@ +.TH std::filesystem::directory_entry::exists 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::exists \- std::filesystem::directory_entry::exists + +.SH Synopsis + bool exists() const; \fB(1)\fP \fI(since C++17)\fP + bool exists( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object exists. Effectively returns: + + 1) std::filesystem::exists(status()), + 2) std::filesystem::exists(status(ec)). + + Note that status() follows symlinks to their targets. + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object exists. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (auto const str: + { + "/usr/bin/cat", + "/usr/bin/mouse", + "/usr/bin/python", + "/usr/bin/bison", + "/usr/bin/yacc", + "/usr/bin/c++", + }) + { + std::filesystem::directory_entry entry{str}; + + std::cout << "directory entry " << entry + << (entry.exists() ? " exists\\n" : " does not exist\\n"); + } + } + +.SH Possible output: + + // Output on a POSIX system: + directory entry "/usr/bin/cat" exist + directory entry "/usr/bin/mouse" does not exist + directory entry "/usr/bin/python" exists + directory entry "/usr/bin/bison" exists + directory entry "/usr/bin/yacc" does not exist + directory entry "/usr/bin/c++" exists + +.SH See also + + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::file_size.3 b/man/std::filesystem::directory_entry::file_size.3 new file mode 100644 index 000000000..7e4e02ba2 --- /dev/null +++ b/man/std::filesystem::directory_entry::file_size.3 @@ -0,0 +1,83 @@ +.TH std::filesystem::directory_entry::file_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::file_size \- std::filesystem::directory_entry::file_size + +.SH Synopsis + std::uintmax_t file_size() const; \fB(1)\fP \fI(since C++17)\fP + std::uintmax_t file_size( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + If the file size is cached in this directory_entry, returns the cached value. + Otherwise, returns: + + 1) std::filesystem::file_size(path()), + 2) std::filesystem::file_size(path(), ec). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The size of the referred-to filesystem object. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + Prints the list of files in a given directory alongside with their sizes in human + readable form. + + +// Run this code + + #include + #include + #include + #include + + struct HumanReadable + { + std::uintmax_t size{}; + + template friend Os& operator<<(Os& os, HumanReadable hr) + { + int i{}; + double mantissa = hr.size; + for (; mantissa >= 1024.0; mantissa /= 1024.0, ++i) + {} + os << std::ceil(mantissa * 10.0) / 10.0 << i["BKMGTPE"]; + return i ? os << "B (" << hr.size << ')' : os; + } + }; + + int main(int argc, const char* argv[]) + { + const auto dir = argc == 2 ? std::filesystem::path{argv[1]} + : std::filesystem::current_path(); + + for (std::filesystem::directory_entry const& entry : + std::filesystem::directory_iterator(dir)) + if (entry.is_regular_file()) + std::cout << entry.path().filename() << " size: " + << HumanReadable{entry.file_size()} << '\\n'; + } + +.SH Possible output: + + "boost_1_73_0.tar.bz2" size: 104.2MB (109247910) + "CppCon 2018 - Jon Kalb “Copy Elision”.mp4" size: 15.7MB (16411990) + "cppreference-doc-20190607.tar.xz" size: 6.3MB (6531336) + "hana.hpp" size: 6.7KB (6807) + +.SH See also + + file_size returns the size of a file + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::hard_link_count.3 b/man/std::filesystem::directory_entry::hard_link_count.3 new file mode 100644 index 000000000..7a149b181 --- /dev/null +++ b/man/std::filesystem::directory_entry::hard_link_count.3 @@ -0,0 +1,45 @@ +.TH std::filesystem::directory_entry::hard_link_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::hard_link_count \- std::filesystem::directory_entry::hard_link_count + +.SH Synopsis + std::uintmax_t hard_link_count() const; \fB(1)\fP \fI(since C++17)\fP + std::uintmax_t hard_link_count( std::error_code& ec ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + + If the number of hard links is cached in this directory_entry, returns the cached + value. Otherwise, returns: + + 1) std::filesystem::hard_link_count(path()), + 2) std::filesystem::hard_link_count(path(), ec). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The number of hard links for the referred-to filesystem object. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + hard_link_count returns the number of hard links referring to the specific file + \fI(C++17)\fP \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::directory_entry::is_block_file.3 b/man/std::filesystem::directory_entry::is_block_file.3 new file mode 100644 index 000000000..8638af11c --- /dev/null +++ b/man/std::filesystem::directory_entry::is_block_file.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::directory_entry::is_block_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_block_file \- std::filesystem::directory_entry::is_block_file + +.SH Synopsis + bool is_block_file() const; \fB(1)\fP \fI(since C++17)\fP + bool is_block_file( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a block device. Effectively returns: + + 1) std::filesystem::is_block_file(status()). + 2) std::filesystem::is_block_file(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a block device, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void print_entry_type(const std::filesystem::directory_entry& entry) + { + std::cout << entry.path() << ": "; + + if (!entry.exists()) + std::cout << "does not exist "; + if (entry.is_block_file()) + std::cout << "is a block device "; + if (entry.is_character_file()) + std::cout << "is a character device "; + if (entry.is_directory()) + std::cout << "is a directory "; + if (entry.is_fifo()) + std::cout << "is a named IPC pipe "; + if (entry.is_regular_file()) + std::cout << "is a regular file "; + if (entry.is_socket()) + std::cout << "is a named IPC socket "; + if (entry.is_symlink()) + std::cout << "(a symlink)"; + if (entry.is_other()) + std::cout << "(an `other` file)"; + + std::cout << '\\n'; + } + + template + class scoped_cleanup + { + std::unique_ptr> u; + + public: + scoped_cleanup(Type* ptr, Fun fun) : u{ptr, std::move(fun)} {} + }; + + int main() + { + // Create files of different kinds. + std::filesystem::current_path(fs::temp_directory_path()); + const std::filesystem::path sandbox{"sandbox"}; + scoped_cleanup remove_all_at_exit{&sandbox, [](const fs::path* p) + { + std::cout << "cleanup: remove_all(" << *p << ")\\n"; + fs::remove_all(*p); + }}; + std::filesystem::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // Creates a regular file + std::filesystem::create_directory(sandbox/"dir"); + + mkfifo((sandbox/"pipe").string().data(), 0644); + struct sockaddr_un addr; addr.sun_family = AF_UNIX; + + std::strcpy(addr.sun_path, (sandbox/"sock").string().data()); + int fd{socket(PF_UNIX, SOCK_STREAM, 0)}; + scoped_cleanup close_socket_at_exit{&fd, [](const int* f) + { + std::cout << "cleanup: close socket #" << *f << '\\n'; + close(*f); + }}; + bind(fd, reinterpret_cast(std::addressof(addr)), sizeof addr); + + fs::create_symlink("file", sandbox/"symlink"); + + for (std::filesystem::directory_entry entry: fs::directory_iterator(sandbox)) + print_entry_type(entry); + + // Request file system objects status directly: + for (const char* str : {"/dev/null", "/dev/cpu", "/usr/include/c++", + "/usr/include/asm", "/usr/include/time.h"}) + print_entry_type(fs::directory_entry{str}); + + } // Cleanup via scoped_cleanup objects + +.SH Possible output: + + "sandbox/symlink": is a regular file (a symlink) + "sandbox/sock": is a named IPC socket (an `other` file) + "sandbox/pipe": is a named IPC pipe (an `other` file) + "sandbox/dir": is a directory + "sandbox/file": is a regular file + "/dev/null": is a character device (an `other` file) + "/dev/cpu": does not exist + "/usr/include/c++": is a directory + "/usr/include/asm": is a directory (a symlink) + "/usr/include/time.h": is a regular file + cleanup: close socket #3 + cleanup: remove_all("sandbox") + +.SH See also + + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_character_file.3 b/man/std::filesystem::directory_entry::is_character_file.3 new file mode 100644 index 000000000..2328cd055 --- /dev/null +++ b/man/std::filesystem::directory_entry::is_character_file.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::directory_entry::is_character_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_character_file \- std::filesystem::directory_entry::is_character_file + +.SH Synopsis + bool is_character_file() const; \fB(1)\fP \fI(since C++17)\fP + bool is_character_file( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a character device. Effectively returns: + + 1) std::filesystem::is_character_file(status()), + 2) std::filesystem::is_character_file(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a character device, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void print_entry_type(const std::filesystem::directory_entry& entry) + { + std::cout << entry.path() << ": "; + + if (!entry.exists()) + std::cout << "does not exist "; + if (entry.is_block_file()) + std::cout << "is a block device "; + if (entry.is_character_file()) + std::cout << "is a character device "; + if (entry.is_directory()) + std::cout << "is a directory "; + if (entry.is_fifo()) + std::cout << "is a named IPC pipe "; + if (entry.is_regular_file()) + std::cout << "is a regular file "; + if (entry.is_socket()) + std::cout << "is a named IPC socket "; + if (entry.is_symlink()) + std::cout << "(a symlink)"; + if (entry.is_other()) + std::cout << "(an `other` file)"; + + std::cout << '\\n'; + } + + template + class scoped_cleanup + { + std::unique_ptr> u; + + public: + scoped_cleanup(Type* ptr, Fun fun) : u{ptr, std::move(fun)} {} + }; + + int main() + { + // Create files of different kinds. + std::filesystem::current_path(fs::temp_directory_path()); + const std::filesystem::path sandbox{"sandbox"}; + scoped_cleanup remove_all_at_exit{&sandbox, [](const fs::path* p) + { + std::cout << "cleanup: remove_all(" << *p << ")\\n"; + fs::remove_all(*p); + }}; + std::filesystem::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // Creates a regular file + std::filesystem::create_directory(sandbox/"dir"); + + mkfifo((sandbox/"pipe").string().data(), 0644); + struct sockaddr_un addr; addr.sun_family = AF_UNIX; + + std::strcpy(addr.sun_path, (sandbox/"sock").string().data()); + int fd{socket(PF_UNIX, SOCK_STREAM, 0)}; + scoped_cleanup close_socket_at_exit{&fd, [](const int* f) + { + std::cout << "cleanup: close socket #" << *f << '\\n'; + close(*f); + }}; + bind(fd, reinterpret_cast(std::addressof(addr)), sizeof addr); + + fs::create_symlink("file", sandbox/"symlink"); + + for (std::filesystem::directory_entry entry: fs::directory_iterator(sandbox)) + print_entry_type(entry); + + // Request file system objects status directly: + for (const char* str : {"/dev/null", "/dev/cpu", "/usr/include/c++", + "/usr/include/asm", "/usr/include/time.h"}) + print_entry_type(fs::directory_entry{str}); + + } // Cleanup via scoped_cleanup objects + +.SH Possible output: + + "sandbox/symlink": is a regular file (a symlink) + "sandbox/sock": is a named IPC socket (an `other` file) + "sandbox/pipe": is a named IPC pipe (an `other` file) + "sandbox/dir": is a directory + "sandbox/file": is a regular file + "/dev/null": is a character device (an `other` file) + "/dev/cpu": does not exist + "/usr/include/c++": is a directory + "/usr/include/asm": is a directory (a symlink) + "/usr/include/time.h": is a regular file + cleanup: close socket #3 + cleanup: remove_all("sandbox") + +.SH See also + + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_directory.3 b/man/std::filesystem::directory_entry::is_directory.3 new file mode 100644 index 000000000..3ca00b009 --- /dev/null +++ b/man/std::filesystem::directory_entry::is_directory.3 @@ -0,0 +1,78 @@ +.TH std::filesystem::directory_entry::is_directory 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_directory \- std::filesystem::directory_entry::is_directory + +.SH Synopsis + bool is_directory() const; \fB(1)\fP \fI(since C++17)\fP + bool is_directory( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a directory. Effectively returns: + + 1) std::filesystem::is_directory(status()), + 2) std::filesystem::is_directory(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a directory, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace fs = std::filesystem; + + void check_directory(fs::directory_entry const& d, std::string_view rem = "") + { + std::cout << "is_directory(" << d << "): " << d.is_directory() << rem << '\\n'; + } + + int main() + { + fs::directory_entry d1("."); + fs::directory_entry d2("file.txt"); + fs::directory_entry d3("new_dir"); + + std::cout << std::boolalpha; + + check_directory(d1); + check_directory(d2); + check_directory(d3, " (has not been created yet)."); + + std::filesystem::create_directory("new_dir"); + + check_directory(d3, " (before refresh)."); + d3.refresh(); + check_directory(d3, " (after refresh)."); + } + +.SH Possible output: + + is_directory("."): true + is_directory("file.txt"): false + is_directory("new_dir"): false (has not been created yet). + is_directory("new_dir"): false (before refresh). + is_directory("new_dir"): true (after refresh). + +.SH See also + + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_fifo.3 b/man/std::filesystem::directory_entry::is_fifo.3 new file mode 100644 index 000000000..7b6b9c9ff --- /dev/null +++ b/man/std::filesystem::directory_entry::is_fifo.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::directory_entry::is_fifo 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_fifo \- std::filesystem::directory_entry::is_fifo + +.SH Synopsis + bool is_fifo() const; \fB(1)\fP \fI(since C++17)\fP + bool is_fifo( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a FIFO or pipe file. Effectively returns: + + 1) std::filesystem::is_fifo(status()). + 2) std::filesystem::is_fifo(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a FIFO or pipe file, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void print_entry_type(const std::filesystem::directory_entry& entry) + { + std::cout << entry.path() << ": "; + + if (!entry.exists()) + std::cout << "does not exist "; + if (entry.is_block_file()) + std::cout << "is a block device "; + if (entry.is_character_file()) + std::cout << "is a character device "; + if (entry.is_directory()) + std::cout << "is a directory "; + if (entry.is_fifo()) + std::cout << "is a named IPC pipe "; + if (entry.is_regular_file()) + std::cout << "is a regular file "; + if (entry.is_socket()) + std::cout << "is a named IPC socket "; + if (entry.is_symlink()) + std::cout << "(a symlink)"; + if (entry.is_other()) + std::cout << "(an `other` file)"; + + std::cout << '\\n'; + } + + template + class scoped_cleanup + { + std::unique_ptr> u; + + public: + scoped_cleanup(Type* ptr, Fun fun) : u{ptr, std::move(fun)} {} + }; + + int main() + { + // Create files of different kinds. + std::filesystem::current_path(fs::temp_directory_path()); + const std::filesystem::path sandbox{"sandbox"}; + scoped_cleanup remove_all_at_exit{&sandbox, [](const fs::path* p) + { + std::cout << "cleanup: remove_all(" << *p << ")\\n"; + fs::remove_all(*p); + }}; + std::filesystem::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // Creates a regular file + std::filesystem::create_directory(sandbox/"dir"); + + mkfifo((sandbox/"pipe").string().data(), 0644); + struct sockaddr_un addr; addr.sun_family = AF_UNIX; + + std::strcpy(addr.sun_path, (sandbox/"sock").string().data()); + int fd{socket(PF_UNIX, SOCK_STREAM, 0)}; + scoped_cleanup close_socket_at_exit{&fd, [](const int* f) + { + std::cout << "cleanup: close socket #" << *f << '\\n'; + close(*f); + }}; + bind(fd, reinterpret_cast(std::addressof(addr)), sizeof addr); + + fs::create_symlink("file", sandbox/"symlink"); + + for (std::filesystem::directory_entry entry: fs::directory_iterator(sandbox)) + print_entry_type(entry); + + // Request file system objects status directly: + for (const char* str : {"/dev/null", "/dev/cpu", "/usr/include/c++", + "/usr/include/asm", "/usr/include/time.h"}) + print_entry_type(fs::directory_entry{str}); + + } // Cleanup via scoped_cleanup objects + +.SH Possible output: + + "sandbox/symlink": is a regular file (a symlink) + "sandbox/sock": is a named IPC socket (an `other` file) + "sandbox/pipe": is a named IPC pipe (an `other` file) + "sandbox/dir": is a directory + "sandbox/file": is a regular file + "/dev/null": is a character device (an `other` file) + "/dev/cpu": does not exist + "/usr/include/c++": is a directory + "/usr/include/asm": is a directory (a symlink) + "/usr/include/time.h": is a regular file + cleanup: close socket #3 + cleanup: remove_all("sandbox") + +.SH See also + + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_other.3 b/man/std::filesystem::directory_entry::is_other.3 new file mode 100644 index 000000000..bb49e03c2 --- /dev/null +++ b/man/std::filesystem::directory_entry::is_other.3 @@ -0,0 +1,143 @@ +.TH std::filesystem::directory_entry::is_other 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_other \- std::filesystem::directory_entry::is_other + +.SH Synopsis + bool is_other() const; \fB(1)\fP \fI(since C++17)\fP + bool is_other( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is an other file (not a regular file, directory + or symlink). Effectively returns: + + 1) std::filesystem::is_other(status()). + 2) std::filesystem::is_other(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is an other file, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void print_entry_type(const std::filesystem::directory_entry& entry) + { + std::cout << entry.path() << ": "; + + if (!entry.exists()) + std::cout << "does not exist "; + if (entry.is_block_file()) + std::cout << "is a block device "; + if (entry.is_character_file()) + std::cout << "is a character device "; + if (entry.is_directory()) + std::cout << "is a directory "; + if (entry.is_fifo()) + std::cout << "is a named IPC pipe "; + if (entry.is_regular_file()) + std::cout << "is a regular file "; + if (entry.is_socket()) + std::cout << "is a named IPC socket "; + if (entry.is_symlink()) + std::cout << "(a symlink)"; + if (entry.is_other()) + std::cout << "(an `other` file)"; + + std::cout << '\\n'; + } + + template + class scoped_cleanup + { + std::unique_ptr> u; + + public: + scoped_cleanup(Type* ptr, Fun fun) : u{ptr, std::move(fun)} {} + }; + + int main() + { + // Create files of different kinds. + std::filesystem::current_path(fs::temp_directory_path()); + const std::filesystem::path sandbox{"sandbox"}; + scoped_cleanup remove_all_at_exit{&sandbox, [](const fs::path* p) + { + std::cout << "cleanup: remove_all(" << *p << ")\\n"; + fs::remove_all(*p); + }}; + std::filesystem::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // Creates a regular file + std::filesystem::create_directory(sandbox/"dir"); + + mkfifo((sandbox/"pipe").string().data(), 0644); + struct sockaddr_un addr; addr.sun_family = AF_UNIX; + + std::strcpy(addr.sun_path, (sandbox/"sock").string().data()); + int fd{socket(PF_UNIX, SOCK_STREAM, 0)}; + scoped_cleanup close_socket_at_exit{&fd, [](const int* f) + { + std::cout << "cleanup: close socket #" << *f << '\\n'; + close(*f); + }}; + bind(fd, reinterpret_cast(std::addressof(addr)), sizeof addr); + + fs::create_symlink("file", sandbox/"symlink"); + + for (std::filesystem::directory_entry entry: fs::directory_iterator(sandbox)) + print_entry_type(entry); + + // Request file system objects status directly: + for (const char* str : {"/dev/null", "/dev/cpu", "/usr/include/c++", + "/usr/include/asm", "/usr/include/time.h"}) + print_entry_type(fs::directory_entry{str}); + + } // Cleanup via scoped_cleanup objects + +.SH Possible output: + + "sandbox/symlink": is a regular file (a symlink) + "sandbox/sock": is a named IPC socket (an `other` file) + "sandbox/pipe": is a named IPC pipe (an `other` file) + "sandbox/dir": is a directory + "sandbox/file": is a regular file + "/dev/null": is a character device (an `other` file) + "/dev/cpu": does not exist + "/usr/include/c++": is a directory + "/usr/include/asm": is a directory (a symlink) + "/usr/include/time.h": is a regular file + cleanup: close socket #3 + cleanup: remove_all("sandbox") + +.SH See also + + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_regular_file.3 b/man/std::filesystem::directory_entry::is_regular_file.3 new file mode 100644 index 000000000..7b3a45a3b --- /dev/null +++ b/man/std::filesystem::directory_entry::is_regular_file.3 @@ -0,0 +1,73 @@ +.TH std::filesystem::directory_entry::is_regular_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_regular_file \- std::filesystem::directory_entry::is_regular_file + +.SH Synopsis + bool is_regular_file() const; \fB(1)\fP \fI(since C++17)\fP + bool is_regular_file( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a regular file. Effectively returns: + + 1) std::filesystem::is_regular_file(status()). + 2) std::filesystem::is_regular_file(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a regular file, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace fs = std::filesystem; + + int main(int argc, const char* argv[]) + { + // Print out all regular files in a directory 'dir'. + try + { + const auto dir{argc == 2 ? fs::path{argv[1]} : fs::current_path()}; + + std::cout << "Current dir: " << dir << '\\n' + << std::string(40, '-') << '\\n'; + + for (fs::directory_entry const& entry : fs::directory_iterator(dir)) + if (entry.is_regular_file()) + std::cout << entry.path().filename() << '\\n'; + } + catch(const fs::filesystem_error& e) + { + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + Current dir: "/tmp/1588616534.9884143" + ---------------------------------------- + "main.cpp" + "a.out" + +.SH See also + + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_socket.3 b/man/std::filesystem::directory_entry::is_socket.3 new file mode 100644 index 000000000..63f8a2161 --- /dev/null +++ b/man/std::filesystem::directory_entry::is_socket.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::directory_entry::is_socket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_socket \- std::filesystem::directory_entry::is_socket + +.SH Synopsis + bool is_socket() const; \fB(1)\fP \fI(since C++17)\fP + bool is_socket( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a named socket. Effectively returns: + + 1) std::filesystem::is_socket(status()), + 2) std::filesystem::is_socket(status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a named socket, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void print_entry_type(const std::filesystem::directory_entry& entry) + { + std::cout << entry.path() << ": "; + + if (!entry.exists()) + std::cout << "does not exist "; + if (entry.is_block_file()) + std::cout << "is a block device "; + if (entry.is_character_file()) + std::cout << "is a character device "; + if (entry.is_directory()) + std::cout << "is a directory "; + if (entry.is_fifo()) + std::cout << "is a named IPC pipe "; + if (entry.is_regular_file()) + std::cout << "is a regular file "; + if (entry.is_socket()) + std::cout << "is a named IPC socket "; + if (entry.is_symlink()) + std::cout << "(a symlink)"; + if (entry.is_other()) + std::cout << "(an `other` file)"; + + std::cout << '\\n'; + } + + template + class scoped_cleanup + { + std::unique_ptr> u; + + public: + scoped_cleanup(Type* ptr, Fun fun) : u{ptr, std::move(fun)} {} + }; + + int main() + { + // Create files of different kinds. + std::filesystem::current_path(fs::temp_directory_path()); + const std::filesystem::path sandbox{"sandbox"}; + scoped_cleanup remove_all_at_exit{&sandbox, [](const fs::path* p) + { + std::cout << "cleanup: remove_all(" << *p << ")\\n"; + fs::remove_all(*p); + }}; + std::filesystem::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // Creates a regular file + std::filesystem::create_directory(sandbox/"dir"); + + mkfifo((sandbox/"pipe").string().data(), 0644); + struct sockaddr_un addr; addr.sun_family = AF_UNIX; + + std::strcpy(addr.sun_path, (sandbox/"sock").string().data()); + int fd{socket(PF_UNIX, SOCK_STREAM, 0)}; + scoped_cleanup close_socket_at_exit{&fd, [](const int* f) + { + std::cout << "cleanup: close socket #" << *f << '\\n'; + close(*f); + }}; + bind(fd, reinterpret_cast(std::addressof(addr)), sizeof addr); + + fs::create_symlink("file", sandbox/"symlink"); + + for (std::filesystem::directory_entry entry: fs::directory_iterator(sandbox)) + print_entry_type(entry); + + // Request file system objects status directly: + for (const char* str : {"/dev/null", "/dev/cpu", "/usr/include/c++", + "/usr/include/asm", "/usr/include/time.h"}) + print_entry_type(fs::directory_entry{str}); + + } // Cleanup via scoped_cleanup objects + +.SH Possible output: + + "sandbox/symlink": is a regular file (a symlink) + "sandbox/sock": is a named IPC socket (an `other` file) + "sandbox/pipe": is a named IPC pipe (an `other` file) + "sandbox/dir": is a directory + "sandbox/file": is a regular file + "/dev/null": is a character device (an `other` file) + "/dev/cpu": does not exist + "/usr/include/c++": is a directory + "/usr/include/asm": is a directory (a symlink) + "/usr/include/time.h": is a regular file + cleanup: close socket #3 + cleanup: remove_all("sandbox") + +.SH See also + + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::is_symlink.3 b/man/std::filesystem::directory_entry::is_symlink.3 new file mode 100644 index 000000000..dd6b5f84e --- /dev/null +++ b/man/std::filesystem::directory_entry::is_symlink.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::directory_entry::is_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::is_symlink \- std::filesystem::directory_entry::is_symlink + +.SH Synopsis + bool is_symlink() const; \fB(1)\fP \fI(since C++17)\fP + bool is_symlink( std::error_code& ec ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the pointed-to object is a symlink. Effectively returns: + + 1) std::filesystem::is_symlink(symlink_status()), + 2) std::filesystem::is_symlink(symlink_status(ec)). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the referred-to filesystem object is a symlink, false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void print_entry_type(const std::filesystem::directory_entry& entry) + { + std::cout << entry.path() << ": "; + + if (!entry.exists()) + std::cout << "does not exist "; + if (entry.is_block_file()) + std::cout << "is a block device "; + if (entry.is_character_file()) + std::cout << "is a character device "; + if (entry.is_directory()) + std::cout << "is a directory "; + if (entry.is_fifo()) + std::cout << "is a named IPC pipe "; + if (entry.is_regular_file()) + std::cout << "is a regular file "; + if (entry.is_socket()) + std::cout << "is a named IPC socket "; + if (entry.is_symlink()) + std::cout << "(a symlink)"; + if (entry.is_other()) + std::cout << "(an `other` file)"; + + std::cout << '\\n'; + } + + template + class scoped_cleanup + { + std::unique_ptr> u; + + public: + scoped_cleanup(Type* ptr, Fun fun) : u{ptr, std::move(fun)} {} + }; + + int main() + { + // Create files of different kinds. + std::filesystem::current_path(fs::temp_directory_path()); + const std::filesystem::path sandbox{"sandbox"}; + scoped_cleanup remove_all_at_exit{&sandbox, [](const fs::path* p) + { + std::cout << "cleanup: remove_all(" << *p << ")\\n"; + fs::remove_all(*p); + }}; + std::filesystem::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // Creates a regular file + std::filesystem::create_directory(sandbox/"dir"); + + mkfifo((sandbox/"pipe").string().data(), 0644); + struct sockaddr_un addr; addr.sun_family = AF_UNIX; + + std::strcpy(addr.sun_path, (sandbox/"sock").string().data()); + int fd{socket(PF_UNIX, SOCK_STREAM, 0)}; + scoped_cleanup close_socket_at_exit{&fd, [](const int* f) + { + std::cout << "cleanup: close socket #" << *f << '\\n'; + close(*f); + }}; + bind(fd, reinterpret_cast(std::addressof(addr)), sizeof addr); + + fs::create_symlink("file", sandbox/"symlink"); + + for (std::filesystem::directory_entry entry: fs::directory_iterator(sandbox)) + print_entry_type(entry); + + // Request file system objects status directly: + for (const char* str : {"/dev/null", "/dev/cpu", "/usr/include/c++", + "/usr/include/asm", "/usr/include/time.h"}) + print_entry_type(fs::directory_entry{str}); + + } // Cleanup via scoped_cleanup objects + +.SH Possible output: + + "sandbox/symlink": is a regular file (a symlink) + "sandbox/sock": is a named IPC socket (an `other` file) + "sandbox/pipe": is a named IPC pipe (an `other` file) + "sandbox/dir": is a directory + "sandbox/file": is a regular file + "/dev/null": is a character device (an `other` file) + "/dev/cpu": does not exist + "/usr/include/c++": is a directory + "/usr/include/asm": is a directory (a symlink) + "/usr/include/time.h": is a regular file + cleanup: close socket #3 + cleanup: remove_all("sandbox") + +.SH See also + + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::last_write_time.3 b/man/std::filesystem::directory_entry::last_write_time.3 new file mode 100644 index 000000000..1e34997db --- /dev/null +++ b/man/std::filesystem::directory_entry::last_write_time.3 @@ -0,0 +1,76 @@ +.TH std::filesystem::directory_entry::last_write_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::last_write_time \- std::filesystem::directory_entry::last_write_time + +.SH Synopsis + std::filesystem::file_time_type last_write_time() const; \fB(1)\fP \fI(since C++17)\fP + std::filesystem::file_time_type last_write_time( std::error_code& \fB(2)\fP \fI(since C++17)\fP + ec ) const noexcept; + + If the last modification time is cached in this directory_entry, returns the cached + value. Otherwise, returns: + + 1) std::filesystem::last_write_time(path()). + 2) std::filesystem::last_write_time(path(), ec). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The last modification time for the referred-to filesystem object. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + std::string to_string(const std::filesystem::file_time_type& ftime) + { + #if __cpp_lib_format + return std::format("{:%c}", ftime); + #else + std::time_t cftime = std::chrono::system_clock::to_time_t( + std::chrono::file_clock::to_sys(ftime)); + std::string str = std::asctime(std::localtime(&cftime)); + str.pop_back(); // rm the trailing '\\n' put by `asctime` + return str; + #endif + } + + int main() + { + auto dir = std::filesystem::current_path(); + using Entry = std::filesystem::directory_entry; + for (Entry const& entry : std::filesystem::directory_iterator(dir)) + std::cout << to_string(entry.last_write_time()) << " : " + << entry.path().filename() << '\\n'; + } + +.SH Possible output: + + Wed Sep 6 13:37:13.960314156 2023 : "main.cpp" + Wed Sep 6 13:37:42.690271828 2023 : "a.out" + +.SH See also + + last_write_time gets or sets the time of the last data modification + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::directory_entry::operator=.3 b/man/std::filesystem::directory_entry::operator=.3 new file mode 100644 index 000000000..a61f5907b --- /dev/null +++ b/man/std::filesystem::directory_entry::operator=.3 @@ -0,0 +1,35 @@ +.TH std::filesystem::directory_entry::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::operator= \- std::filesystem::directory_entry::operator= + +.SH Synopsis + directory_entry& operator=( const directory_entry& other ) = \fB(1)\fP \fI(since C++17)\fP + default; + directory_entry& operator=( directory_entry&& other ) noexcept = \fB(2)\fP \fI(since C++17)\fP + default; + + Replaces the contents of the directory entry (path and cached attributes, if any) + with the contents of other. + + Both copy- and move-assignment operators for directory_entry are defaulted. + +.SH Parameters + + other - other directory_entry + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + assign assigns contents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::directory_entry::operator==,!=,,>=,.3 b/man/std::filesystem::directory_entry::operator==,!=,,>=,.3 new file mode 100644 index 000000000..9f25673d1 --- /dev/null +++ b/man/std::filesystem::directory_entry::operator==,!=,,>=,.3 @@ -0,0 +1,42 @@ +.TH std::filesystem::directory_entry::operator==,!=,,>=, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::operator==,!=,,>=, \- std::filesystem::directory_entry::operator==,!=,,>=, + +.SH Synopsis + bool operator==( const directory_entry& rhs ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + bool operator!=( const directory_entry& rhs ) const noexcept; \fB(2)\fP \fI(since C++17)\fP + \fI(until C++20)\fP + bool operator<( const directory_entry& rhs ) const noexcept; \fB(3)\fP \fI(since C++17)\fP + \fI(until C++20)\fP + bool operator<=( const directory_entry& rhs ) const noexcept; \fB(4)\fP \fI(since C++17)\fP + \fI(until C++20)\fP + bool operator>( const directory_entry& rhs ) const noexcept; \fB(5)\fP \fI(since C++17)\fP + \fI(until C++20)\fP + bool operator>=( const directory_entry& rhs ) const noexcept; \fB(6)\fP \fI(since C++17)\fP + \fI(until C++20)\fP + std::strong_ordering operator<=>( const directory_entry& rhs ) \fB(7)\fP \fI(since C++20)\fP + const noexcept; + + Compares the path with the directory entry rhs. + + The <, <=, >, >=, and != operators are synthesized from operator<=> \fI(since C++20)\fP + and operator== respectively. + +.SH Parameters + + rhs - directory_entry to compare + +.SH Return value + + 1) true if path() == rhs.path(), false otherwise. + 2) true if path() != rhs.path(), false otherwise. + 3) true if path() < rhs.path(), false otherwise. + 4) true if path() <= rhs.path(), false otherwise. + 5) true if path() > rhs.path(), false otherwise. + 6) true if path() >= rhs.path(), false otherwise. + 7) The result of path() <=> rhs.path(). + +.SH See also + + path returns the path the entry refers to + operator const path& \fI(public member function)\fP diff --git a/man/std::filesystem::directory_entry::path.3 b/man/std::filesystem::directory_entry::path.3 new file mode 100644 index 000000000..7d886a3d6 --- /dev/null +++ b/man/std::filesystem::directory_entry::path.3 @@ -0,0 +1,65 @@ +.TH std::filesystem::directory_entry::path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::path \- std::filesystem::directory_entry::path + +.SH Synopsis + const std::filesystem::path& path() const noexcept; \fI(since C++17)\fP + operator const std::filesystem::path& () const noexcept; \fI(since C++17)\fP + + Returns the full path the directory entry refers to. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The full path the directory entry refers to. + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace fs = std::filesystem; + + std::string get_stem(const fs::path& p) { return p.stem().string(); } + void create_file(const fs::path& p) { std::ofstream o{p}; } + + int main() + { + const fs::path dir{"tmp_dir"}; + fs::create_directory(dir); + create_file(dir / "one"); + create_file(dir / "two"); + create_file(dir / "three"); + + for (const auto& file : fs::directory_iterator(dir)) + { + // Explicit conversion + std::cout << get_stem(file.path()) << '\\n'; + + // Implicit conversion + std::cout << get_stem(file) << '\\n'; + } + + fs::remove_all(dir); + } + +.SH Possible output: + + two + two + one + one + three + three + +.SH See also + + path represents a path + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::filesystem::directory_entry::refresh.3 b/man/std::filesystem::directory_entry::refresh.3 new file mode 100644 index 000000000..2896d25c4 --- /dev/null +++ b/man/std::filesystem::directory_entry::refresh.3 @@ -0,0 +1,82 @@ +.TH std::filesystem::directory_entry::refresh 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::refresh \- std::filesystem::directory_entry::refresh + +.SH Synopsis + void refresh(); \fB(1)\fP \fI(since C++17)\fP + void refresh( std::error_code& ec ) noexcept; \fB(2)\fP \fI(since C++17)\fP + + Examines the filesystem object referred to by this directory entry and stores its + attributes for retrieval with status, exists, is_regular_file, and other status + accessors. + + If an error occurs, the value of any cached attributes is unspecified. + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Many low-level OS APIs for directory traversal retrieve file attributes along with + the next directory entry. The constructors and the non-const member functions of + std::filesystem::directory_iterator store these attributes, if any, in the + pointed-to std::filesystem::directory_entry without calling + directory_entry::refresh, which makes it possible to examine the attributes of the + directory entries as they are being iterated over, without making additional system + calls. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + status status of the file designated by this directory entry; + symlink_status status of the file/symlink designated by this directory entry + \fI(public member function)\fP + checks whether directory entry refers to existing file system + exists object + \fI(public member function)\fP + is_block_file checks whether the directory entry refers to block device + \fI(public member function)\fP + is_character_file checks whether the directory entry refers to a character device + \fI(public member function)\fP + is_directory checks whether the directory entry refers to a directory + \fI(public member function)\fP + is_fifo checks whether the directory entry refers to a named pipe + \fI(public member function)\fP + is_other checks whether the directory entry refers to an other file + \fI(public member function)\fP + is_regular_file checks whether the directory entry refers to a regular file + \fI(public member function)\fP + is_socket checks whether the directory entry refers to a named IPC socket + \fI(public member function)\fP + is_symlink checks whether the directory entry refers to a symbolic link + \fI(public member function)\fP + file_size returns the size of the file to which the directory entry refers + \fI(public member function)\fP + returns the number of hard links referring to the file to which + hard_link_count the directory entry refers + \fI(public member function)\fP + gets the time of the last data modification of the file to which + last_write_time the directory entry refers + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::directory_entry::replace_filename.3 b/man/std::filesystem::directory_entry::replace_filename.3 new file mode 100644 index 000000000..dce3d9531 --- /dev/null +++ b/man/std::filesystem::directory_entry::replace_filename.3 @@ -0,0 +1,74 @@ +.TH std::filesystem::directory_entry::replace_filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::replace_filename \- std::filesystem::directory_entry::replace_filename + +.SH Synopsis + void replace_filename( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + void replace_filename( const std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ); + + Changes the filename of the directory entry. + + Effectively modifies the path member by path.replace_filename(p) and calls refresh + to update the cached attributes. If an error occurs, the values of the cached + attributes are unspecified. + + This function does not commit any changes to the filesystem. + +.SH Parameters + + p - the path to append to the parent path of the currently stored path + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + namespace fs = std::filesystem; + { + fs::directory_entry entry{"alpha"}; + std::cout << entry << '\\n'; + entry.replace_filename("omega"); + std::cout << entry << '\\n'; + } + { + fs::directory_entry entry{"/alpha/"}; + std::cout << entry << '\\n'; + entry.replace_filename("omega"); + std::cout << entry << '\\n'; + } + } + +.SH Output: + + "alpha" + "omega" + "/alpha/" + "/alpha/omega" + +.SH See also + + assign assigns contents + \fI(public member function)\fP + replace_filename replaces the last path component with another path + \fI(public member function of std::filesystem::path)\fP diff --git a/man/std::filesystem::directory_entry::status,std::filesystem::directory_entry::symlink_status.3 b/man/std::filesystem::directory_entry::status,std::filesystem::directory_entry::symlink_status.3 new file mode 100644 index 000000000..b2b547c48 --- /dev/null +++ b/man/std::filesystem::directory_entry::status,std::filesystem::directory_entry::symlink_status.3 @@ -0,0 +1,154 @@ +.TH std::filesystem::directory_entry::status,std::filesystem::directory_entry::symlink_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_entry::status,std::filesystem::directory_entry::symlink_status \- std::filesystem::directory_entry::status,std::filesystem::directory_entry::symlink_status + +.SH Synopsis + std::filesystem::file_status status() const; \fB(1)\fP \fI(since C++17)\fP + std::filesystem::file_status status( std::error_code& ec ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + std::filesystem::file_status symlink_status() const; \fB(3)\fP \fI(since C++17)\fP + std::filesystem::file_status symlink_status( std::error_code& ec ) \fB(4)\fP \fI(since C++17)\fP + const noexcept; + + 1,2) Returns status of the entry, as if determined by a filesystem::status call + (symlinks are followed to their targets). + 3,4) Returns status of the entry, as if determined by a filesystem::symlink_status + call (symlinks are not followed). + +.SH Parameters + + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The status of the file referred to by the entry. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Many low-level OS APIs for directory traversal retrieve file attributes along with + the next directory entry. The constructors and the non-const member functions of + std::filesystem::directory_iterator store these attributes, if any, in the + pointed-to std::filesystem::directory_entry without calling + directory_entry::refresh, which makes it possible to examine the attributes of the + directory entries as they are being iterated over, without making additional system + calls. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + refresh updates the cached file attributes + \fI(public member function)\fP + checks whether directory entry refers to existing file system + exists object + \fI(public member function)\fP + is_block_file checks whether the directory entry refers to block device + \fI(public member function)\fP + is_character_file checks whether the directory entry refers to a character device + \fI(public member function)\fP + is_directory checks whether the directory entry refers to a directory + \fI(public member function)\fP + is_fifo checks whether the directory entry refers to a named pipe + \fI(public member function)\fP + is_other checks whether the directory entry refers to an other file + \fI(public member function)\fP + is_regular_file checks whether the directory entry refers to a regular file + \fI(public member function)\fP + is_socket checks whether the directory entry refers to a named IPC socket + \fI(public member function)\fP + is_symlink checks whether the directory entry refers to a symbolic link + \fI(public member function)\fP + file_size returns the size of the file to which the directory entry refers + \fI(public member function)\fP + returns the number of hard links referring to the file to which + hard_link_count the directory entry refers + \fI(public member function)\fP + gets the time of the last data modification of the file to which + last_write_time the directory entry refers + \fI(public member function)\fP diff --git a/man/std::filesystem::directory_iterator.3 b/man/std::filesystem::directory_iterator.3 new file mode 100644 index 000000000..4b569cd18 --- /dev/null +++ b/man/std::filesystem::directory_iterator.3 @@ -0,0 +1,161 @@ +.TH std::filesystem::directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_iterator \- std::filesystem::directory_iterator + +.SH Synopsis + Defined in header + class directory_iterator; \fI(since C++17)\fP + + directory_iterator is a LegacyInputIterator that iterates over the directory_entry + elements of a directory (but does not visit the subdirectories). The iteration order + is unspecified, except that each directory entry is visited only once. The special + pathnames dot and dot-dot are skipped. + + If the directory_iterator reports an error or is advanced past the last directory + entry, it becomes equal to the default-constructed iterator, also known as the end + iterator. Two end iterators are always equal, dereferencing or incrementing the end + iterator is undefined behavior. + + If a file or a directory is deleted or added to the directory tree after the + directory iterator has been created, it is unspecified whether the change would be + observed through the iterator. + +.SH Member types + + Member type Definition + value_type std::filesystem::directory_entry + difference_type std::ptrdiff_t + pointer const std::filesystem::directory_entry* + reference const std::filesystem::directory_entry& + iterator_category std::input_iterator_tag + +.SH Member functions + + constructor constructs a directory iterator + \fI(public member function)\fP + destructor default destructor + \fI(public member function)\fP + operator= assigns contents + \fI(public member function)\fP + operator* accesses the pointed-to entry + operator-> \fI(public member function)\fP + increment advances to the next entry + operator++ \fI(public member function)\fP + +.SH Non-member functions + + begin(std::filesystem::directory_iterator) range-based for loop support + end(std::filesystem::directory_iterator) \fI(function)\fP + \fI(C++17)\fP + + Additionally, + operator== and operator!= are + \fI(until C++20)\fP + operator== is + \fI(since C++20)\fP provided as required by LegacyInputIterator. + + It is unspecified + whether operator!= is provided because it can be synthesized from operator==, and + \fI(since C++20)\fP whether an equality operator is a member or non-member. + + Helper templates + + namespace std::ranges { + + template<> (since + inline constexpr bool C++20) + enable_borrowed_range = true; + + } + namespace std::ranges { + + template<> (since + inline constexpr bool enable_view = C++20) + true; + + } + + These specializations for directory_iterator make it a borrowed_range and a view. + +.SH Notes + + Many low-level OS APIs for directory traversal retrieve file attributes along with + the next directory entry. The constructors and the non-const member functions of + std::filesystem::directory_iterator store these attributes, if any, in the + pointed-to std::filesystem::directory_entry without calling + directory_entry::refresh, which makes it possible to examine the attributes of the + directory entries as they are being iterated over, without making additional system + calls. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::filesystem::path sandbox{"sandbox"}; + std::filesystem::create_directories(sandbox/"dir1"/"dir2"); + std::ofstream{sandbox/"file1.txt"}; + std::ofstream{sandbox/"file2.txt"}; + + std::cout << "directory_iterator:\\n"; + // directory_iterator can be iterated using a range-for loop + for (auto const& dir_entry : std::filesystem::directory_iterator{sandbox}) + std::cout << dir_entry.path() << '\\n'; + + std::cout << "\\ndirectory_iterator as a range:\\n"; + // directory_iterator behaves as a range in other ways, too + std::ranges::for_each( + std::filesystem::directory_iterator{sandbox}, + [](const auto& dir_entry) { std::cout << dir_entry << '\\n'; }); + + std::cout << "\\nrecursive_directory_iterator:\\n"; + for (auto const& dir_entry : std::filesystem::recursive_directory_iterator{sandbox}) + std::cout << dir_entry << '\\n'; + + // delete the sandbox dir and all contents within it, including subdirs + std::filesystem::remove_all(sandbox); + } + +.SH Possible output: + + directory_iterator: + "sandbox/file2.txt" + "sandbox/file1.txt" + "sandbox/dir1" + + directory_iterator as a range: + "sandbox/file2.txt" + "sandbox/file1.txt" + "sandbox/dir1" + + recursive_directory_iterator: + "sandbox/file2.txt" + "sandbox/file1.txt" + "sandbox/dir1" + "sandbox/dir1/dir2" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3480 C++20 directory_iterator was neither a borrowed_range it is both + nor a view + +.SH See also + + recursive_directory_iterator an iterator to the contents of a directory and its + \fI(C++17)\fP subdirectories + \fI(class)\fP + directory_options options for iterating directory contents + \fI(C++17)\fP \fI(enum)\fP + directory_entry a directory entry + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::filesystem::directory_iterator::directory_iterator.3 b/man/std::filesystem::directory_iterator::directory_iterator.3 new file mode 100644 index 000000000..d81d58130 --- /dev/null +++ b/man/std::filesystem::directory_iterator::directory_iterator.3 @@ -0,0 +1,78 @@ +.TH std::filesystem::directory_iterator::directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_iterator::directory_iterator \- std::filesystem::directory_iterator::directory_iterator + +.SH Synopsis + directory_iterator() noexcept; \fB(1)\fP \fI(since C++17)\fP + explicit directory_iterator( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + directory_iterator( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::filesystem::directory_options options ); + directory_iterator( const std::filesystem::path& p, \fB(4)\fP \fI(since C++17)\fP + std::error_code& ec ); + directory_iterator( const std::filesystem::path& p, + + std::filesystem::directory_options options, \fB(5)\fP \fI(since C++17)\fP + + std::error_code& ec ); + directory_iterator( const directory_iterator& other ) = default; \fB(6)\fP \fI(since C++17)\fP + directory_iterator( directory_iterator&& other ) = default; \fB(7)\fP \fI(since C++17)\fP + + Constructs a new directory iterator. + + 1) Constructs the end iterator. + 2) Constructs a directory iterator that refers to the first directory entry of a + directory identified by p. If p refers to a non-existing file or not a directory, + throws std::filesystem::filesystem_error. + 3) Same as \fB(2)\fP, but if std::filesystem::directory_options::skip_permission_denied is + set in options and construction encounters a permissions denied error, constructs + the end iterator and does not report an error. + 4) Constructs a directory iterator that refers to the first directory entry of a + directory identified by p. If p refers to a non-existing file or not a directory, + returns the end iterator and sets ec. + 5) Same as \fB(4)\fP, but if std::filesystem::directory_options::skip_permission_denied is + set in options and construction encounters a permissions denied error, constructs + the end iterator and does not report an error. + 6) Copy constructor. + 7) Move constructor. + +.SH Parameters + + p - path to the filesystem object to which the directory iterator will refer + ec - out-parameter for error reporting in the non-throwing overloads + options - the set of BitmaskType options that control the behavior of the directory + iterator + other - another directory iterator to use as source to initialize the directory + iterator with + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 4,5) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + To iterate over the current directory, construct the iterator as + directory_iterator(".") instead of directory_iterator(""). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3013 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::directory_iterator::operator*,.3 b/man/std::filesystem::directory_iterator::operator*,.3 new file mode 100644 index 000000000..ced768874 --- /dev/null +++ b/man/std::filesystem::directory_iterator::operator*,.3 @@ -0,0 +1,31 @@ +.TH std::filesystem::directory_iterator::operator*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_iterator::operator*, \- std::filesystem::directory_iterator::operator*, + +.SH Synopsis + + const std::filesystem::directory_entry& operator*() const; \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::directory_entry* operator->() const; \fB(2)\fP \fI(since C++17)\fP + + Accesses the pointed-to directory_entry. + + The result of operator* or operator-> on the end iterator is undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Value of the directory_entry referred to by this iterator. + 2) Pointer to the directory_entry referred to by this iterator. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH See also + + operator* accesses the pointed-to entry + operator-> \fI(public member function of std::filesystem::recursive_directory_iterator)\fP + diff --git a/man/std::filesystem::directory_iterator::operator++,.3 b/man/std::filesystem::directory_iterator::operator++,.3 new file mode 100644 index 000000000..d3b228ffc --- /dev/null +++ b/man/std::filesystem::directory_iterator::operator++,.3 @@ -0,0 +1,49 @@ +.TH std::filesystem::directory_iterator::operator++, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_iterator::operator++, \- std::filesystem::directory_iterator::operator++, + +.SH Synopsis + + directory_iterator& operator++(); \fB(1)\fP \fI(since C++17)\fP + directory_iterator& increment( std::error_code& ec ); \fB(2)\fP \fI(since C++17)\fP + + Advances the iterator to the next entry. Invalidates all copies of the previous + value of *this. + + This section is incomplete + +.SH Parameters + + ec - error code to store error status to + +.SH Return value + + *this + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3013 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::filesystem::directory_iterator::operator=.3 b/man/std::filesystem::directory_iterator::operator=.3 new file mode 100644 index 000000000..e14e3595a --- /dev/null +++ b/man/std::filesystem::directory_iterator::operator=.3 @@ -0,0 +1,25 @@ +.TH std::filesystem::directory_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_iterator::operator= \- std::filesystem::directory_iterator::operator= + +.SH Synopsis + directory_iterator& operator=(const directory_iterator&) = default; + \fI(since C++17)\fP + directory_iterator& operator=(directory_iterator&&) = default; + + This section is incomplete + +.SH Parameters + + This section is incomplete + +.SH Return value + + *this + +.SH Exceptions + + This section is incomplete + +.SH Category: + * Todo without reason diff --git a/man/std::filesystem::directory_options.3 b/man/std::filesystem::directory_options.3 new file mode 100644 index 000000000..acfad289a --- /dev/null +++ b/man/std::filesystem::directory_options.3 @@ -0,0 +1,46 @@ +.TH std::filesystem::directory_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::directory_options \- std::filesystem::directory_options + +.SH Synopsis + Defined in header + enum class directory_options { + + none = /* unspecified */, + follow_directory_symlink = /* unspecified */, \fI(since C++17)\fP + skip_permission_denied = /* unspecified */ + + }; + + This type represents available options that control the behavior of the + directory_iterator and recursive_directory_iterator. + + directory_options satisfies the requirements of BitmaskType (which means the bitwise + operators operator&, operator|, operator^, operator~, operator&=, operator|=, and + operator^= are defined for this type). none represents the empty bitmask; every + other enumerator represents a distinct bitmask element. + +.SH Member constants + + Member constant Meaning + none (Default) Skip directory symlinks, permission denied is + error. + follow_directory_symlink Follow rather than skip directory symlinks. + skip_permission_denied Skip directories that would otherwise result in permission + denied errors. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a directory iterator + \fI(public member function of std::filesystem::directory_iterator)\fP + constructs a recursive directory iterator + constructor \fI\fI(public member\fP function of\fP + std::filesystem::recursive_directory_iterator) + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::equivalent.3 b/man/std::filesystem::equivalent.3 new file mode 100644 index 000000000..9ea403060 --- /dev/null +++ b/man/std::filesystem::equivalent.3 @@ -0,0 +1,124 @@ +.TH std::filesystem::equivalent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::equivalent \- std::filesystem::equivalent + +.SH Synopsis + Defined in header + bool equivalent( const std::filesystem::path& p1, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& p2 ); + bool equivalent( const std::filesystem::path& p1, + + const std::filesystem::path& p2, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + + Checks whether the paths p1 and p2 resolve to the same file system entity. + + If either p1 or p2 does not exist, an error is reported. + + The non-throwing overload returns false on errors. + +.SH Parameters + + p1, p2 - paths to check for equivalence + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the p1 and p2 refer to the same file or directory and their file status is + the same. false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p1 as the first path argument, p2 as the second path argument, and the OS error + code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Two paths are considered to resolve to the same file system entity if the two + candidate entities the paths resolve to are located on the same device at the same + location. For POSIX, this means that the st_dev and st_ino members of their POSIX + stat structure, obtained as if by POSIX stat(), are equal. + + In particular, all hard links for the same file or directory are equivalent, and a + symlink and its target on the same file system are equivalent. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + // hard link equivalency + fs::path p1 = "."; + fs::path p2 = fs::current_path(); + if (fs::equivalent(p1, p2)) + std::cout << p1 << " is equivalent to " << p2 << '\\n'; + + // symlink equivalency + for (const fs::path lib : {"/lib/libc.so.6", "/lib/x86_64-linux-gnu/libc.so.6"}) + { + try + { + p2 = lib.parent_path() / fs::read_symlink(lib); + } + catch (std::filesystem::filesystem_error const& ex) + { + std::cout << ex.what() << '\\n'; + continue; + } + + if (fs::equivalent(lib, p2)) + std::cout << lib << " is equivalent to " << p2 << '\\n'; + } + } + +.SH Possible output: + + "." is equivalent to "/var/tmp/test" + filesystem error: read_symlink: No such file or directory [/lib/libc.so.6] + "/lib/x86_64-linux-gnu/libc.so.6" is equivalent to "/lib/x86_64-linux-gnu/libc-2.23.so" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2937 C++17 error condition specified incorrectly corrected + +.SH See also + + compares the lexical representations of two paths + compare lexicographically + \fI(public member function of std::filesystem::path)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= + operator<=> lexicographically compares two paths + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + (C++20) + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::exists.3 b/man/std::filesystem::exists.3 new file mode 100644 index 000000000..517faa556 --- /dev/null +++ b/man/std::filesystem::exists.3 @@ -0,0 +1,99 @@ +.TH std::filesystem::exists 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::exists \- std::filesystem::exists + +.SH Synopsis + Defined in header + bool exists( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool exists( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool exists( const std::filesystem::path& p, std::error_code& ec ) \fB(3)\fP \fI(since C++17)\fP + noexcept; + + Checks if the given file status or path corresponds to an existing file or + directory. + + 1) Equivalent to status_known(s) && s.type() != file_type::not_found. + 2,3) Let s be a std::filesystem::file_status determined as if by status(p) or + status(p, ec) (symlinks are followed), respectively. Returns exists(s). The + non-throwing overload calls ec.clear() if status_known(s). + +.SH Parameters + + s - file status to check + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the given path or file status corresponds to an existing file or directory, + false otherwise. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + + No filesystem exception is thrown if object does not exist (use return value). + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration. During directory iteration, calling exists(*iterator) is less + efficient than exists(iterator->status()). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + void demo_exists(const fs::path& p, fs::file_status s = fs::file_status{}) + { + std::cout << p; + if (fs::status_known(s) ? fs::exists(s) : fs::exists(p)) + std::cout << " exists\\n"; + else + std::cout << " does not exist\\n"; + } + + int main() + { + const fs::path sandbox{"sandbox"}; + fs::create_directory(sandbox); + std::ofstream{sandbox/"file"}; // create regular file + fs::create_symlink("non-existing", sandbox/"symlink"); + + demo_exists(sandbox); + + for (const auto& entry : fs::directory_iterator(sandbox)) + demo_exists(entry, entry.status()); // use cached status from directory entry + + fs::remove_all(sandbox); + } + +.SH Output: + + "sandbox" exists + "sandbox/symlink" does not exist + "sandbox/file" exists + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + exists checks whether directory entry refers to existing file system object + \fI(public member function of std::filesystem::directory_entry)\fP diff --git a/man/std::filesystem::file_size.3 b/man/std::filesystem::file_size.3 new file mode 100644 index 000000000..866af79a0 --- /dev/null +++ b/man/std::filesystem::file_size.3 @@ -0,0 +1,113 @@ +.TH std::filesystem::file_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_size \- std::filesystem::file_size + +.SH Synopsis + Defined in header + std::uintmax_t file_size( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + std::uintmax_t file_size( const std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + If p does not exist, reports an error. + + For a regular file p, returns the size determined as if by reading the st_size + member of the structure obtained by POSIX stat (symlinks are followed). + + The result of attempting to determine the size of a directory (as well as any other + file that is not a regular file or a symlink) is implementation-defined. + + The non-throwing overload returns static_cast(-1) on errors. + +.SH Parameters + + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The size of the file, in bytes. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + struct HumanReadable + { + std::uintmax_t size{}; + + private: + friend std::ostream& operator<<(std::ostream& os, HumanReadable hr) + { + int o{}; + double mantissa = hr.size; + for (; mantissa >= 1024.; mantissa /= 1024., ++o); + os << std::ceil(mantissa * 10.) / 10. << "BKMGTPE"[o]; + return o ? os << "B (" << hr.size << ')' : os; + } + }; + + int main(int, char const* argv[]) + { + fs::path example = "example.bin"; + fs::path p = fs::current_path() / example; + std::ofstream(p).put('a'); // create file of size 1 + std::cout << example << " size = " << fs::file_size(p) << '\\n'; + fs::remove(p); + + p = argv[0]; + std::cout << p << " size = " << HumanReadable{fs::file_size(p)} << '\\n'; + + try + { + std::cout << "Attempt to get size of a directory:\\n"; + [[maybe_unused]] auto x_x = fs::file_size("/dev"); + } + catch (fs::filesystem_error& e) + { + std::cout << e.what() << '\\n'; + } + + for (std::error_code ec; fs::path bin : {"cat", "mouse"}) + { + bin = "/bin"/bin; + if (const std::uintmax_t size = fs::file_size(bin, ec); ec) + std::cout << bin << " : " << ec.message() << '\\n'; + else + std::cout << bin << " size = " << HumanReadable{size} << '\\n'; + } + } + +.SH Possible output: + + "example.bin" size = 1 + "./a.out" size = 22KB (22512) + Attempt to get size of a directory: + filesystem error: cannot get file size: Is a directory [/dev] + "/bin/cat" size = 50.9KB (52080) + "/bin/mouse" : No such file or directory + +.SH See also + + resize_file changes the size of a regular file by truncation or zero-fill + \fI(C++17)\fP \fI(function)\fP + space determines available free space on the file system + \fI(C++17)\fP \fI(function)\fP + file_size returns the size of the file to which the directory entry refers + \fI(public member function of std::filesystem::directory_entry)\fP diff --git a/man/std::filesystem::file_status.3 b/man/std::filesystem::file_status.3 new file mode 100644 index 000000000..4ffe40248 --- /dev/null +++ b/man/std::filesystem::file_status.3 @@ -0,0 +1,37 @@ +.TH std::filesystem::file_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_status \- std::filesystem::file_status + +.SH Synopsis + Defined in header + class file_status; \fI(since C++17)\fP + + Stores information about the type and permissions of a file. + +.SH Member functions + + constructor constructs a file_status object + \fI(public member function)\fP + operator= assigns contents + \fI(public member function)\fP + destructor implicit destructor + \fI(public member function)\fP + type gets or sets the type of the file + \fI(public member function)\fP + permissions gets or sets the permissions of the file + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares two file_status objects + (C++20) \fI(function)\fP + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + status status of the file designated by this directory entry; + symlink_status status of the file/symlink designated by this directory entry + \fI(public member function of std::filesystem::directory_entry)\fP diff --git a/man/std::filesystem::file_status::file_status.3 b/man/std::filesystem::file_status::file_status.3 new file mode 100644 index 000000000..13e33c01e --- /dev/null +++ b/man/std::filesystem::file_status::file_status.3 @@ -0,0 +1,35 @@ +.TH std::filesystem::file_status::file_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_status::file_status \- std::filesystem::file_status::file_status + +.SH Synopsis + file_status() noexcept : \fB(1)\fP \fI(since C++17)\fP + file_status(std::filesystem::file_type::none) {} + file_status( const file_status& ) noexcept = default; \fB(2)\fP \fI(since C++17)\fP + file_status( file_status&& ) noexcept = default; \fB(3)\fP \fI(since C++17)\fP + explicit file_status( + + std::filesystem::file_type type, \fB(4)\fP \fI(since C++17)\fP + + std::filesystem::perms permissions = + std::filesystem::perms::unknown ) noexcept; + + Constructs a new file_status object. + + 1) Default constructor that calls \fB(4)\fP with std::filesystem::file_type::none. + 2,3) Copy and move constructors are defaulted. + 4) Initializes the file status object with type as type and permissions as + permissions. + +.SH Parameters + + type - type of the file status + permissions - permissions of the file status + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::file_status::operator=.3 b/man/std::filesystem::file_status::operator=.3 new file mode 100644 index 000000000..e04b29c9e --- /dev/null +++ b/man/std::filesystem::file_status::operator=.3 @@ -0,0 +1,26 @@ +.TH std::filesystem::file_status::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_status::operator= \- std::filesystem::file_status::operator= + +.SH Synopsis + file_status& operator=( const file_status& other ) noexcept = \fB(1)\fP \fI(since C++17)\fP + default; + file_status& operator=( file_status&& other ) noexcept = default; \fB(2)\fP \fI(since C++17)\fP + + Copy- or move-assigns another file status object. + +.SH Parameters + + other - another file_status object to assign + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::file_status::permissions.3 b/man/std::filesystem::file_status::permissions.3 new file mode 100644 index 000000000..f6d919f7a --- /dev/null +++ b/man/std::filesystem::file_status::permissions.3 @@ -0,0 +1,73 @@ +.TH std::filesystem::file_status::permissions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_status::permissions \- std::filesystem::file_status::permissions + +.SH Synopsis + std::filesystem::perms permissions() const noexcept; \fB(1)\fP \fI(since C++17)\fP + void permissions( std::filesystem::perms perm ) noexcept; \fB(2)\fP \fI(since C++17)\fP + + Accesses the file permissions information. + + 1) Returns file permissions information. + 2) Sets file permissions to perm. + +.SH Parameters + + perm - file permissions to set to + +.SH Return value + + 1) File permissions information. + 2) \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + void demo_perms(std::filesystem::perms p) + { + using std::filesystem::perms; + auto show = [=](char op, perms perm) + { + std::cout << (perms::none == (perm & p) ? '-' : op); + }; + show('r', perms::owner_read); + show('w', perms::owner_write); + show('x', perms::owner_exec); + show('r', perms::group_read); + show('w', perms::group_write); + show('x', perms::group_exec); + show('r', perms::others_read); + show('w', perms::others_write); + show('x', perms::others_exec); + std::cout << '\\n'; + } + + int main() + { + std::ofstream("test.txt"); // create file + + std::cout << "Created file with permissions: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::permissions( + "test.txt", + std::filesystem::perms::owner_all | std::filesystem::perms::group_all, + std::filesystem::perm_options::add + ); + + std::cout << "After adding u+rwx and g+rwx: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::remove("test.txt"); + } + +.SH Possible output: + + Created file with permissions: rw-r--r-- + After adding u+rwx and g+wrx: rwxrwxr-- diff --git a/man/std::filesystem::file_status::type.3 b/man/std::filesystem::file_status::type.3 new file mode 100644 index 000000000..5335fd9a2 --- /dev/null +++ b/man/std::filesystem::file_status::type.3 @@ -0,0 +1,29 @@ +.TH std::filesystem::file_status::type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_status::type \- std::filesystem::file_status::type + +.SH Synopsis + std::filesystem::file_type type() const noexcept; \fB(1)\fP \fI(since C++17)\fP + void type( std::filesystem::file_type type ) noexcept; \fB(2)\fP \fI(since C++17)\fP + + Accesses the file type information. + + 1) Returns file type information. + 2) Sets file type to type. + +.SH Parameters + + type - file type to set to + +.SH Return value + + 1) File type information. + 2) \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::file_time_type.3 b/man/std::filesystem::file_time_type.3 new file mode 100644 index 000000000..574fe4303 --- /dev/null +++ b/man/std::filesystem::file_time_type.3 @@ -0,0 +1,57 @@ +.TH std::filesystem::file_time_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_time_type \- std::filesystem::file_time_type + +.SH Synopsis + Defined in header + using file_time_type = std::chrono::time_point; \fI(since C++17)\fP + \fI(until C++20)\fP + using file_time_type = \fI(since C++20)\fP + std::chrono::time_point; + + Represents file time. + + trivial-clock is an implementation-defined type that satisfies + TrivialClock and is sufficient to represent the resolution and range \fI(until C++20)\fP + of the file time values offered by the filesystem. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + int main() + { + auto p = std::filesystem::temp_directory_path() / "example.bin"; + std::ofstream{p.c_str()}.put('a'); // create file + + std::filesystem::file_time_type ftime = std::filesystem::last_write_time(p); + std::cout << std::format("File write time is {}\\n", ftime); + + // move file write time 1 hour to the future + std::filesystem::last_write_time(p, ftime + 1h); + + // read back from the filesystem + ftime = std::filesystem::last_write_time(p); + std::cout << std::format("File write time is {}\\n", ftime); + + std::filesystem::remove(p); + } + +.SH Possible output: + + File write time is 2023-09-04 19:33:24.702639224 + File write time is 2023-09-04 20:33:24.702639224 + +.SH See also + + last_write_time gets or sets the time of the last data modification + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::file_type.3 b/man/std::filesystem::file_type.3 new file mode 100644 index 000000000..05854f71a --- /dev/null +++ b/man/std::filesystem::file_type.3 @@ -0,0 +1,162 @@ +.TH std::filesystem::file_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::file_type \- std::filesystem::file_type + +.SH Synopsis + Defined in header + enum class file_type { + + none = /* unspecified */, + not_found = /* unspecified */, + regular = /* unspecified */, + directory = /* unspecified */, + symlink = /* unspecified */, + block = /* unspecified */, \fI(since C++17)\fP + character = /* unspecified */, + fifo = /* unspecified */, + socket = /* unspecified */, + unknown = /* unspecified */, + /* implementation-defined */ + + }; + + file_type defines constants that indicate a type of a file or directory a path + refers to. The value of the enumerators are distinct. + +.SH Constants + + Constant Meaning + none indicates that the file status has not been evaluated yet, or + an error occurred when evaluating it + not_found indicates that the file was not found (this is not considered + an error) + regular a regular file + directory a directory + symlink a symbolic link + block a block special file + character a character special file + fifo a FIFO (also known as pipe) file + socket a socket file + an additional implementation-defined constant for each + implementation-defined additional file type supported by the implementation (e.g. + MSVC STL defines junction for NTFS junctions) + unknown the file exists but its type could not be determined + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + switch (s.type()) + { + case fs::file_type::none: + std::cout << " has `not-evaluated-yet` type"; + break; + case fs::file_type::not_found: + std::cout << " does not exist"; + break; + case fs::file_type::regular: + std::cout << " is a regular file"; + break; + case fs::file_type::directory: + std::cout << " is a directory"; + break; + case fs::file_type::symlink: + std::cout << " is a symlink"; + break; + case fs::file_type::block: + std::cout << " is a block device"; + break; + case fs::file_type::character: + std::cout << " is a character device"; + break; + case fs::file_type::fifo: + std::cout << " is a named IPC pipe"; + break; + case fs::file_type::socket: + std::cout << " is a named IPC socket"; + break; + case fs::file_type::unknown: + std::cout << " has `unknown` type"; + break; + default: + std::cout << " has `implementation-defined` type"; + break; + } + std::cout << '\\n'; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a regular file + is_regular_file \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::filesystem_error.3 b/man/std::filesystem::filesystem_error.3 new file mode 100644 index 000000000..da305d69a --- /dev/null +++ b/man/std::filesystem::filesystem_error.3 @@ -0,0 +1,102 @@ +.TH std::filesystem::filesystem_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::filesystem_error \- std::filesystem::filesystem_error + +.SH Synopsis + Defined in header + class filesystem_error; \fI(since C++17)\fP + + The class std::filesystem::filesystem_error defines an exception object that is + thrown on failure by the throwing overloads of the functions in the filesystem + library. + + std-filesystem-filesystem error-inheritance.svg + + Inheritance diagram + +.SH Member functions + + constructor constructs the exception object + \fI(public member function)\fP + operator= replaces the exception object + \fI(public member function)\fP + path1 returns the paths that were involved in the operation that caused the + path2 error + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +Inherited from std::system_error + +.SH Member functions + + code returns error code + \fI(public member function of std::system_error)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::system_error)\fP + +Inherited from std::runtime_error + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Notes + + In order to ensure that copy functions of filesystem_error are noexcept, typical + implementations store an object holding the return value of what() and two + std::filesystem::path objects referenced by path1() and path2() respectively in a + separately-allocated reference-counted storage. + + Currently the MS STL implementation is non-conforming: objects mentioned above are + stored directly in the filesystem object, which makes the copy functions not + noexcept. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const std::filesystem::path from{"/none1/a"}, to{"/none2/b"}; + + try + { + std::filesystem::copy_file(from, to); // throws: files do not exist + } + catch (std::filesystem::filesystem_error const& ex) + { + std::cout << "what(): " << ex.what() << '\\n' + << "path1(): " << ex.path1() << '\\n' + << "path2(): " << ex.path2() << '\\n' + << "code().value(): " << ex.code().value() << '\\n' + << "code().message(): " << ex.code().message() << '\\n' + << "code().category(): " << ex.code().category().name() << '\\n'; + } + + // All functions have non-throwing equivalents + std::error_code ec; + std::filesystem::copy_file(from, to, ec); // does not throw + std::cout << "\\nNon-throwing form sets error_code: " << ec.message() << '\\n'; + } + +.SH Possible output: + + what(): filesystem error: cannot copy file: No such file or directory [/none1/a] [/none2/b] + path1(): "/none1/a" + path2(): "/none2/b" + code().value(): 2 + code().message(): No such file or directory + code().category(): generic + + Non-throwing form sets error_code: No such file or directory diff --git a/man/std::filesystem::filesystem_error::filesystem_error.3 b/man/std::filesystem::filesystem_error::filesystem_error.3 new file mode 100644 index 000000000..280d6b70a --- /dev/null +++ b/man/std::filesystem::filesystem_error::filesystem_error.3 @@ -0,0 +1,55 @@ +.TH std::filesystem::filesystem_error::filesystem_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::filesystem_error::filesystem_error \- std::filesystem::filesystem_error::filesystem_error + +.SH Synopsis + filesystem_error( const std::string& what_arg, \fB(1)\fP \fI(since C++17)\fP + std::error_code ec ); + filesystem_error( const std::string& what_arg, + + const std::filesystem::path& p1, \fB(2)\fP \fI(since C++17)\fP + + std::error_code ec ); + filesystem_error( const std::string& what_arg, + + const std::filesystem::path& p1, \fB(3)\fP \fI(since C++17)\fP + const std::filesystem::path& p2, + + std::error_code ec ); + filesystem_error( const filesystem_error& other ) noexcept; \fB(4)\fP \fI(since C++17)\fP + + Constructs a new filesystem_error object. + + 1-3) The error code is set to ec and optionally, the paths that were involved in the + operation that resulted in the error, are set to p1 and p2. what() after + construction returns a string that contains what_arg (assuming that it does not + contain an embedded null character ). If either or both path arguments are not + provided, a null path is used instead. + 4) Copy constructor. Initialize the contents with those of other. If *this and other + both have dynamic type std::filesystem_error::filesystem_error then + std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + what_arg - explanatory string + ec - error code for the specific operating system dependent error + p1, p2 - paths involved in the operation raising system error + other - another filesystem_error object to copy + +.SH Notes + + Because copying std::filesystem::filesystem_error is not permitted to throw + exceptions, the explanatory string is typically stored internally in a + separately-allocated reference-counted storage. This is also why there is no + constructor taking std::string&&: it would have to copy the content anyway. + + Typical implementations also store path objects referenced by path1() and path2() in + the reference-counted storage. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::filesystem_error::operator=.3 b/man/std::filesystem::filesystem_error::operator=.3 new file mode 100644 index 000000000..1b0dd42a3 --- /dev/null +++ b/man/std::filesystem::filesystem_error::operator=.3 @@ -0,0 +1,33 @@ +.TH std::filesystem::filesystem_error::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::filesystem_error::operator= \- std::filesystem::filesystem_error::operator= + +.SH Synopsis + filesystem_error& operator=( const filesystem_error& other ) \fI(since C++17)\fP + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::filesystem::filesystem_error then std::strcmp(what(), other.what()) == 0 after + assignment. + +.SH Parameters + + other - another filesystem_error object to assign with + +.SH Return value + + *this + +.SH Notes + + Typical implementations store path objects referenced by path1() and path2() in a + reference-counted storage. As a result, *this and other usually share their path + objects after assignment. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::filesystem_error::path1,std::filesystem::filesystem_error::path2.3 b/man/std::filesystem::filesystem_error::path1,std::filesystem::filesystem_error::path2.3 new file mode 100644 index 000000000..2c94e4a4c --- /dev/null +++ b/man/std::filesystem::filesystem_error::path1,std::filesystem::filesystem_error::path2.3 @@ -0,0 +1,47 @@ +.TH std::filesystem::filesystem_error::path1,std::filesystem::filesystem_error::path2 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::filesystem_error::path1,std::filesystem::filesystem_error::path2 \- std::filesystem::filesystem_error::path1,std::filesystem::filesystem_error::path2 + +.SH Synopsis + const std::filesystem::path& path1() const noexcept; \fI(since C++17)\fP + const std::filesystem::path& path2() const noexcept; \fI(since C++17)\fP + + Returns the paths that were stored in the exception object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + References to the copy of the path parameters stored by the constructor. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const std::filesystem::path old_p{std::tmpnam(nullptr)}, + new_p{std::tmpnam(nullptr)}; + try { + std::filesystem::rename(old_p, new_p); // throws since old_p does not exist + } + catch(std::filesystem::filesystem_error const& ex) { + std::cout + << "what(): " << ex.what() << '\\n' + << "path1(): " << ex.path1() << '\\n' + << "path2(): " << ex.path2() << '\\n'; + } + } + +.SH Possible output: + + what(): filesystem error: cannot rename: No such file or directory [/tmp/fileIzzRLB] [/tmp/fileiUDWlV] + path1(): "/tmp/fileIzzRLB" + path2(): "/tmp/fileiUDWlV" diff --git a/man/std::filesystem::filesystem_error::what.3 b/man/std::filesystem::filesystem_error::what.3 new file mode 100644 index 000000000..1092657a0 --- /dev/null +++ b/man/std::filesystem::filesystem_error::what.3 @@ -0,0 +1,79 @@ +.TH std::filesystem::filesystem_error::what 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::filesystem_error::what \- std::filesystem::filesystem_error::what + +.SH Synopsis + const char* what() const noexcept override; \fI(since C++17)\fP + + Returns an explanatory byte string. This explanatory string contains the explanatory + string passed at the time of construction. Implementations are encouraged to include + the pathnames of path1() and path2() in native format and the + std::system_error::what() string inside the returned string as well. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A C-stye explanatory byte string that contains the explanatory string passed at the + time of construction. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + void explain(std::string_view note, fs::filesystem_error const& ex) + { + std::cout << note << " exception:\\n" + << "what(): " << ex.what() << '\\n' + << "path1(): " << ex.path1() << ", path2(): " + << ex.path2() << "\\n\\n"; + } + + int main() + { + try + { + std::filesystem::rename("/dev", "/null"); + } + catch(fs::filesystem_error const& ex) + { + explain("fs::rename()", ex); + } + + for (auto const path : {"/bool", "/bin/cat", "/bin/mouse"}) + try + { + std::filesystem::create_directory(path); + } + catch(fs::filesystem_error const& ex) + { + explain("fs::create_directory()", ex); + } + } + +.SH Possible output: + + fs::rename() exception: + what(): filesystem error: cannot rename: Permission denied [/dev] [/null] + path1(): "/dev", path2(): "/null" + + fs::create_directory() exception: + what(): filesystem error: cannot create directory: Permission denied [/bool] + path1(): "/bool", path2(): "" + + fs::create_directory() exception: + what(): filesystem error: cannot create directory: File exists [/bin/cat] + path1(): "/bin/cat", path2(): "" + + fs::create_directory() exception: + what(): filesystem error: cannot create directory: Read-only file system [/bin/mouse] + path1(): "/bin/mouse", path2(): "" diff --git a/man/std::filesystem::hard_link_count.3 b/man/std::filesystem::hard_link_count.3 new file mode 100644 index 000000000..9d1d5c7e9 --- /dev/null +++ b/man/std::filesystem::hard_link_count.3 @@ -0,0 +1,69 @@ +.TH std::filesystem::hard_link_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::hard_link_count \- std::filesystem::hard_link_count + +.SH Synopsis + Defined in header + std::uintmax_t hard_link_count( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + std::uintmax_t hard_link_count( const std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Returns the number of hard links for the filesystem object identified by path p. + + The non-throwing overload returns static_cast(-1) on errors. + +.SH Parameters + + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The number of hard links for p. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + // On a POSIX-style filesystem, each directory has at least 2 hard links: + // itself and the special member pathname "." + fs::path p = fs::current_path(); + std::cout << "Number of hard links for current path is " + << fs::hard_link_count(p) << '\\n'; + + // Each ".." is a hard link to the parent directory, so the total number + // of hard links for any directory is 2 plus number of direct subdirectories + p = fs::current_path() / ".."; // Each dot-dot is a hard link to parent + std::cout << "Number of hard links for .. is " + << fs::hard_link_count(p) << '\\n'; + } + +.SH Possible output: + + Number of hard links for current path is 2 + Number of hard links for .. is 3 + +.SH See also + + create_hard_link creates a hard link + \fI(C++17)\fP \fI(function)\fP + returns the number of hard links referring to the file to which the + hard_link_count directory entry refers + \fI(public member function of std::filesystem::directory_entry)\fP diff --git a/man/std::filesystem::hash_value.3 b/man/std::filesystem::hash_value.3 new file mode 100644 index 000000000..cf98b2189 --- /dev/null +++ b/man/std::filesystem::hash_value.3 @@ -0,0 +1,113 @@ +.TH std::filesystem::hash_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::hash_value \- std::filesystem::hash_value + +.SH Synopsis + Defined in header + std::size_t hash_value( const std::filesystem::path& p ) noexcept; \fI(since C++17)\fP + +.SH Parameters + + p - a std::filesystem::path object + +.SH Return value + + A hash value such that if for two paths, p1 == p2 then hash_value(p1) == + hash_value(p2). + + The return value is consistent with std::hash. + +.SH Notes + + Equality of two paths is determined by comparing each component separately, so, for + example "a//b" equals "a/b" and has the same hash_value. + + hash_value originates from the Boost.filesystem library where it was used for + interoperability with boost.hash (which calls hash_value found by argument-dependent + lookup or boost::hash_value where available). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + namespace fs = std::filesystem; + + void show_hash(fs::path const& p) + { + std::cout << std::hex << std::uppercase << std::setw(16) + << fs::hash_value(p) << " : " << p << '\\n'; + } + + int main() + { + auto tmp1 = fs::path{"/tmp"}; + auto tmp2 = fs::path{"/tmp/../tmp"}; + assert(!(tmp1 == tmp2)); + assert(fs::equivalent(tmp1, tmp2)); + show_hash(tmp1); + show_hash(tmp2); + + for (auto s : {"/a///b", "/a//b", "/a/c", "...", "..", ".", ""}) + show_hash(s); + + // A hash function object to work with unordered_* containers: + struct PathHash + { + std::size_t operator()(fs::path const& p) const noexcept + { + return fs::hash_value(p); + } + }; + std::unordered_set dirs{ + "/bin", "/bin", "/lib", "/lib", "/opt", "/opt", "/tmp", "/tmp/../tmp"}; + for (fs::path const& p : dirs) + std::cout << p << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 6050C47ADB62DFE5 : "/tmp" + 62795A58B69AD90A : "/tmp/../tmp" + FF302110C9991974 : "/a///b" + FF302110C9991974 : "/a//b" + FD6167277915D464 : "/a/c" + C42040F82CD8B542 : "..." + D2D30154E0B78BBC : ".." + D18C722215ED0530 : "." + 0 : "" + "/tmp/../tmp" "/opt" "/lib" "/tmp" "/bin" + +.SH See also + + compares the lexical representations of two paths + compare lexicographically + \fI(public member function)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= + operator<=> lexicographically compares two paths + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + (C++20) + equivalent checks whether two paths refer to the same file + \fI(C++17)\fP system object + \fI(function)\fP + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + std::hash hash support for std::filesystem::path + \fI(C++17)\fP \fI(class template specialization)\fP diff --git a/man/std::filesystem::is_block_file.3 b/man/std::filesystem::is_block_file.3 new file mode 100644 index 000000000..737e54a29 --- /dev/null +++ b/man/std::filesystem::is_block_file.3 @@ -0,0 +1,143 @@ +.TH std::filesystem::is_block_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_block_file \- std::filesystem::is_block_file + +.SH Synopsis + Defined in header + bool is_block_file( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_block_file( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_block_file( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Checks if the given file status or path corresponds to a block special file, as if + determined by the POSIX S_ISBLK. Examples of block special files are block devices + such as /dev/sda or /dev/loop0 on Linux. + + 1) Equivalent to s.type() == file_type::block. + 2,3) Equivalent to is_block_file(status(p)) or is_block_file(status(p, ec)). + +.SH Parameters + + s - file status to check + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a block device. + The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to block device + is_block_file \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::is_character_file.3 b/man/std::filesystem::is_character_file.3 new file mode 100644 index 000000000..d6b391100 --- /dev/null +++ b/man/std::filesystem::is_character_file.3 @@ -0,0 +1,144 @@ +.TH std::filesystem::is_character_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_character_file \- std::filesystem::is_character_file + +.SH Synopsis + Defined in header + bool is_character_file( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_character_file( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_character_file( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Checks if the given file status or path corresponds to a character special file, as + if determined by POSIX S_ISCHR. Examples of character special files are character + devices such as /dev/null, /dev/tty, /dev/audio, or /dev/nvram on Linux. + + 1) Equivalent to s.type() == file_type::character. + 2,3) Equivalent to is_character_file(status(p)) or is_character_file(status(p, ec)) + respectively. + +.SH Parameters + + s - file status to check + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a character + device, false otherwise. The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a character device + is_character_file \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::is_directory.3 b/man/std::filesystem::is_directory.3 new file mode 100644 index 000000000..fa8b09ba2 --- /dev/null +++ b/man/std::filesystem::is_directory.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::is_directory 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_directory \- std::filesystem::is_directory + +.SH Synopsis + Defined in header + bool is_directory( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_directory( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_directory( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Checks if the given file status or path corresponds to a directory. + + 1) Equivalent to s.type() == file_type::directory. + 2,3) Equivalent to is_directory(status(p)) or is_directory(status(p, ec)), + respectively. + +.SH Parameters + + s - file status to check + p - path to query + ec - error code to modify in case of errors + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a directory, + false otherwise. The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a directory + is_directory \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::is_empty.3 b/man/std::filesystem::is_empty.3 new file mode 100644 index 000000000..ab1c7c719 --- /dev/null +++ b/man/std::filesystem::is_empty.3 @@ -0,0 +1,90 @@ +.TH std::filesystem::is_empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_empty \- std::filesystem::is_empty + +.SH Synopsis + Defined in header + bool is_empty( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + bool is_empty( const std::filesystem::path& p, std::error_code& ec \fB(2)\fP \fI(since C++17)\fP + ); + + Checks whether the given path refers to an empty file or directory. + +.SH Parameters + + p - path to examine + ec - error code to modify in case of error + +.SH Return value + + true if the path indicated by p refers to an empty file or directory, false + otherwise. The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + namespace fs = std::filesystem; + + const fs::path tmp_dir{fs::temp_directory_path()}; + std::cout << std::boolalpha + << "Temp dir: " << tmp_dir << '\\n' + << "is_empty(): " << fs::is_empty(tmp_dir) << '\\n'; + + const fs::path tmp_name{tmp_dir / std::tmpnam(nullptr)}; + std::cout << "Temp file: " << tmp_name << '\\n'; + + std::ofstream file{tmp_name.string()}; + std::cout << "is_empty(): " << fs::is_empty(tmp_name) << '\\n'; + file << "cppreference.com"; + file.flush(); + std::cout << "is_empty(): " << fs::is_empty(tmp_name) << '\\n' + << "file_size(): " << fs::file_size(tmp_name) << '\\n'; + file.close(); + fs::remove(tmp_name); + } + +.SH Possible output: + + Temp dir: "/tmp" + is_empty(): false + Temp file: "/tmp/fileCqd9DM" + is_empty(): true + is_empty(): false + file_size(): 16 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3013 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::is_fifo.3 b/man/std::filesystem::is_fifo.3 new file mode 100644 index 000000000..042415cd1 --- /dev/null +++ b/man/std::filesystem::is_fifo.3 @@ -0,0 +1,142 @@ +.TH std::filesystem::is_fifo 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_fifo \- std::filesystem::is_fifo + +.SH Synopsis + Defined in header + bool is_fifo( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_fifo( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_fifo( const std::filesystem::path& p, std::error_code& ec \fB(3)\fP \fI(since C++17)\fP + ) noexcept; + + Checks if the given file status or path corresponds to a FIFO or pipe file as if + determined by POSIX S_ISFIFO. + + 1) Equivalent to s.type() == file_type::fifo. + 2,3) Equivalent to is_fifo(status(p)) or is_fifo(status(p, ec)) respectively. + +.SH Parameters + + s - file status to check + p - path to query + ec - error code to modify in case of errors + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a FIFO pipe, + false otherwise. The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a named pipe + is_fifo \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::is_other.3 b/man/std::filesystem::is_other.3 new file mode 100644 index 000000000..68d85d85a --- /dev/null +++ b/man/std::filesystem::is_other.3 @@ -0,0 +1,75 @@ +.TH std::filesystem::is_other 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_other \- std::filesystem::is_other + +.SH Synopsis + Defined in header + bool is_other( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_other( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_other( const std::filesystem::path& p, std::error_code& ec \fB(3)\fP \fI(since C++17)\fP + ) noexcept; + + Checks if the given file status or path corresponds to a file of type other type. + That is, the file exists, but is neither regular file, nor directory nor a symlink. + + 1) Equivalent to exists(s) && !is_regular_file(s) && !is_directory(s) && + !is_symlink(s). + 2,3) Equivalent to is_other(status(p)) or is_other(status(p, ec)), respectively. + +.SH Parameters + + s - file status to check + p - path to examine + ec - error code to store the error status to + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a file that is + not regular file, directory, or a symlink, false otherwise. The non-throwing + overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to an other file + is_other \fI(public member function of std::filesystem::directory_entry)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::is_regular_file.3 b/man/std::filesystem::is_regular_file.3 new file mode 100644 index 000000000..7ae11437b --- /dev/null +++ b/man/std::filesystem::is_regular_file.3 @@ -0,0 +1,149 @@ +.TH std::filesystem::is_regular_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_regular_file \- std::filesystem::is_regular_file + +.SH Synopsis + Defined in header + bool is_regular_file( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_regular_file( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_regular_file( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Checks if the given file status or path corresponds to a regular file. + + 1) Equivalent to s.type() == file_type::regular. + 2,3) Equivalent to is_regular_file(status(p)) or is_regular_file(status(p, ec)) + respectively. + +.SH Parameters + + s - file status to check + p - path to examine + ec - error code to store the error status to + +.SH Return value + + true if the file indicated by p or if the type indicated by s refers to a regular + file, false otherwise. The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The throwing overload is additionally specified to throw + std::filesystem::filesystem_error if status(p) would throw. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + file_type the type of a file + \fI(C++17)\fP \fI(enum)\fP + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a regular file + is_regular_file \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::is_socket.3 b/man/std::filesystem::is_socket.3 new file mode 100644 index 000000000..f1ae17a82 --- /dev/null +++ b/man/std::filesystem::is_socket.3 @@ -0,0 +1,148 @@ +.TH std::filesystem::is_socket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_socket \- std::filesystem::is_socket + +.SH Synopsis + Defined in header + bool is_socket( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_socket( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_socket( const std::filesystem::path& p, std::error_code& \fB(3)\fP \fI(since C++17)\fP + ec ) noexcept; + + Checks if the given file status or path corresponds to a named IPC socket, as if + determined by the POSIX S_IFSOCK. + + 1) Equivalent to s.type() == file_type::socket. + 2,3) Equivalent to is_socket(status(p)) or is_socket(status(p, ec)). + +.SH Parameters + + s - file status to check + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a named socket. + The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Named sockets are UNIX domain sockets constructed with socket and bind POSIX APIs, + which may be used for advanced interprocess communication. In particular, they may + be used to transport open file descriptors from one running process to another. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a named IPC socket + is_socket \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::is_symlink.3 b/man/std::filesystem::is_symlink.3 new file mode 100644 index 000000000..d3952939f --- /dev/null +++ b/man/std::filesystem::is_symlink.3 @@ -0,0 +1,143 @@ +.TH std::filesystem::is_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::is_symlink \- std::filesystem::is_symlink + +.SH Synopsis + Defined in header + bool is_symlink( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + bool is_symlink( const std::filesystem::path& p ); \fB(2)\fP \fI(since C++17)\fP + bool is_symlink( const std::filesystem::path& p, std::error_code& \fB(3)\fP \fI(since C++17)\fP + ec ) noexcept; + + Checks if the given file status or path corresponds to a symbolic link, as if + determined by the POSIX S_IFLNK. + + 1) Equivalent to s.type() == file_type::symlink. + 2,3) Equivalent to is_symlink(symlink_status(p)) or is_symlink(symlink_status(p, + ec)). + +.SH Parameters + + s - file status to check + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + true if the file indicated by p or if the type indicated s refers to a symbolic + link. The non-throwing overload returns false if an error occurs. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + checks whether the directory entry refers to a symbolic link + is_symlink \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::last_write_time.3 b/man/std::filesystem::last_write_time.3 new file mode 100644 index 000000000..e0856b57a --- /dev/null +++ b/man/std::filesystem::last_write_time.3 @@ -0,0 +1,97 @@ +.TH std::filesystem::last_write_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::last_write_time \- std::filesystem::last_write_time + +.SH Synopsis + Defined in header + std::filesystem::file_time_type last_write_time( const \fB(1)\fP \fI(since C++17)\fP + std::filesystem::path& p ); + std::filesystem::file_time_type last_write_time( const + std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& + ec ) noexcept; + void last_write_time( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::filesystem::file_time_type new_time ); + void last_write_time( const std::filesystem::path& p, + + std::filesystem::file_time_type new_time, \fB(4)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + + 1,2) Returns the time of the last modification of p, determined as if by accessing + the member st_mtime of the POSIX stat (symlinks are followed). The non-throwing + overload returns file_time_type::min() on errors. + 3,4) Changes the time of the last modification of p, as if by POSIX futimens + (symlinks are followed). + +.SH Parameters + + p - path to examine or modify + new_time - new modification time + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + 1,2) The time of the last modification of p. + 3,4) \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + It is not guaranteed that immediately after setting the write time, the value + returned by (1,2) is the same as what was passed as the argument to (3,4) because + the file system's time may be more granular than filesystem::file_time_type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + int main() + { + auto p = std::filesystem::temp_directory_path() / "example.bin"; + std::ofstream{p.c_str()}.put('a'); // create file + + std::filesystem::file_time_type ftime = std::filesystem::last_write_time(p); + std::cout << std::format("File write time is {}\\n", ftime); + + // move file write time 1 hour to the future + std::filesystem::last_write_time(p, ftime + 1h); + + // read back from the filesystem + ftime = std::filesystem::last_write_time(p); + std::cout << std::format("File write time is {}\\n", ftime); + + std::filesystem::remove(p); + } + +.SH Possible output: + + File write time is 2023-09-04 19:33:24.702639224 + File write time is 2023-09-04 20:33:24.702639224 + +.SH See also + + file_time_type represents file time values + \fI(C++17)\fP \fI(typedef)\fP + gets the time of the last data modification of the file to which the + last_write_time directory entry refers + \fI(public member function of std::filesystem::directory_entry)\fP diff --git a/man/std::filesystem::path.3 b/man/std::filesystem::path.3 new file mode 100644 index 000000000..08fc999a7 --- /dev/null +++ b/man/std::filesystem::path.3 @@ -0,0 +1,252 @@ +.TH std::filesystem::path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path \- std::filesystem::path + +.SH Synopsis + Defined in header + class path; \fI(since C++17)\fP + + Objects of type path represent paths on a filesystem. Only syntactic aspects of + paths are handled: the pathname may represent a non-existing path or even one that + is not allowed to exist on the current file system or OS. + + The path name has the following syntax: + + 1. root-name(optional): identifies the root on a filesystem with multiple roots + (such as "C:" or "//myserver"). In case of ambiguity, the longest sequence of + characters that forms a valid root-name is treated as the root-name. The + standard library may define additional root-names besides the ones understood by + the OS API. + 2. root-directory(optional): a directory separator that, if present, marks this + path as absolute. If it is missing (and the first element other than the root + name is a file name), then the path is relative and requires another path as the + starting location to resolve to a file name. + 3. Zero or more of the following: + + * file-name: sequence of characters that aren't directory separators or preferred + directory separators (additional limitations may be imposed by the OS or file + system). This name may identify a file, a hard link, a symbolic link, or a + directory. Two special file-names are recognized: + + * dot: the file name consisting of a single dot character . is a directory name + that refers to the current directory. + * dot-dot: the file name consisting of two dot characters .. is a directory name + that refers to the parent directory. + * directory-separators: the forward slash character / or the alternative character + provided as path::preferred_separator. If this character is repeated, it is + treated as a single directory separator: /usr///////lib is the same as /usr/lib. + + A path can be normalized by following this algorithm: + + 1. If the path is empty, stop (normal form of an empty path is an empty path). + 2. Replace each directory-separator (which may consist of multiple slashes) with a + single path::preferred_separator. + 3. Replace each slash character in the root-name with path::preferred_separator. + 4. Remove each dot and any immediately following directory-separator. + 5. Remove each non-dot-dot filename immediately followed by a directory-separator + and a dot-dot, along with any immediately following directory-separator. + 6. If there is root-directory, remove all dot-dots and any directory-separators + immediately following them. + 7. If the last filename is dot-dot, remove any trailing directory-separator. + 8. If the path is empty, add a dot (normal form of ./ is .). + + The path can be traversed element-wise via iterators returned by the begin() and + end() functions, which views the path in generic format and iterates over root name, + root directory, and the subsequent file name elements (directory separators are + skipped except the one that identifies the root directory). If the very last element + in the path is a directory separator, the last iterator will dereference to an empty + element. + + Calling any non-const member function of a path invalidates all iterators referring + to elements of that object. + + If the OS uses a native syntax that is different from the portable generic syntax + described above, library functions that are defined to accept "detected format" + accept path names in both formats: a detected format argument is taken to be in the + generic format if and only if it matches the generic format but is not acceptable to + the operating system as a native path. On those OS where native format differs + between pathnames of directories and pathnames of files, a generic pathname is + treated as a directory path if it ends on a directory separator and a regular file + otherwise. + + In any case, the path class behaves as if it stores a pathname in the native format + and automatically converts to generic format as needed (each member function + specifies which format it interprets the path as). + + On POSIX systems, the generic format is the native format and there is no need to + distinguish or convert between them. + + Paths are implicitly convertible to and from std::basic_strings, which makes it + possible to use them with other file APIs. + + The stream operators use std::quoted so that spaces do not cause truncation when + later read by stream input operator. + + Decomposition member functions (e.g. extension) return filesystem::path objects + instead of string objects as other APIs do. + +.SH Member types and constants + + Type Definition + value_type character type used by the native encoding of the filesystem: char on + POSIX, wchar_t on Windows + string_type std::basic_string + a constant LegacyInputIterator with a value_type of path that meets + all requirements of LegacyBidirectionalIterator except that for two + equal dereferenceable iterators a and b of type const_iterator, there + const_iterator is no requirement that *a and *b refer to the same object. + + It is unspecified whether const_iterator is actually a + LegacyBidirectionalIterator + iterator an alias to const_iterator + determines how to interpret string representations of pathnames. + + The following enumerators are also defined: + + format Constant Explanation + \fI(C++17)\fP native_format native pathname format + generic_format generic pathname format + auto_format implementation-defined format, auto-detected where + possible + + \fI(enum)\fP + +.SH Member constants + + alternative directory separator which may be used in addition + constexpr value_type to the portable /. On Windows, this is the backslash character + preferred_separator \\. On POSIX, this is the same forward slash / as the portable + \fB[static]\fP separator + \fI(public static member constant)\fP + +.SH Member functions + + constructor constructs a path + \fI(public member function)\fP + destructor destroys a path object + \fI(public member function)\fP + operator= assigns another path + \fI(public member function)\fP + assign assigns contents + \fI(public member function)\fP + Concatenation + append appends elements to the path with a directory separator + operator/= \fI(public member function)\fP + concat concatenates two paths without introducing a directory + operator+= separator + \fI(public member function)\fP +.SH Modifiers + clear erases the contents + \fI(public member function)\fP + make_preferred converts directory separators to preferred directory separator + \fI(public member function)\fP + remove_filename removes filename path component + \fI(public member function)\fP + replace_filename replaces the last path component with another path + \fI(public member function)\fP + replace_extension replaces the extension + \fI(public member function)\fP + swap swaps two paths + \fI(public member function)\fP + Format observers + c_str returns the native version of the path + native \fI(public member function)\fP + operator string_type + string + wstring returns the path in native pathname format converted to a + u8string string + u16string \fI(public member function)\fP + u32string + generic_string + generic_wstring returns the path in generic pathname format converted to a + generic_u8string string + generic_u16string \fI(public member function)\fP + generic_u32string + Compare + compares the lexical representations of two paths + compare lexicographically + \fI(public member function)\fP +.SH Generation + lexically_normal converts path to normal form + lexically_relative converts path to relative form + lexically_proximate converts path to proximate form + \fI(public member function)\fP + Decomposition + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_directory returns the root directory of the path, if present + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP + relative_path returns path relative to the root path + \fI(public member function)\fP + parent_path returns the path of the parent path + \fI(public member function)\fP + filename returns the filename path component + \fI(public member function)\fP + returns the stem path component (filename without the final + stem extension) + \fI(public member function)\fP + extension returns the file extension path component + \fI(public member function)\fP + Queries + empty checks if the path is empty + \fI(public member function)\fP + has_root_path + has_root_name + has_root_directory + has_relative_path checks if the corresponding path element is not empty + has_parent_path \fI(public member function)\fP + has_filename + has_stem + has_extension + is_absolute checks if root_path() uniquely identifies file system location + is_relative \fI(public member function)\fP +.SH Iterators + begin iterator access to the path as a sequence of elements + end \fI(public member function)\fP + +.SH Non-member functions + + Defined in namespace std::filesystem + swap(std::filesystem::path) swaps two paths + \fI(C++17)\fP \fI(function)\fP + hash_value calculates a hash value for a path object + \fI(C++17)\fP \fI(function)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= + operator<=> lexicographically compares two paths + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + (C++20) + operator/ concatenates two paths with a directory separator + \fI(C++17)\fP \fI(function)\fP + operator<< performs stream input and output on a quoted path + operator>> \fI(function)\fP + \fI(C++17)\fP + u8path creates a path from a UTF-8 encoded source + \fI(C++17)\fP(deprecated in C++20) \fI(function)\fP + +.SH Helper classes + + Defined in namespace std + std::hash hash support for std::filesystem::path + \fI(C++17)\fP \fI(class template specialization)\fP + std::formatter formatting support for filesystem::path + (C++26) \fI(class template specialization)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3657 C++17 hash for path was disabled enabled diff --git a/man/std::filesystem::path::assign.3 b/man/std::filesystem::path::assign.3 new file mode 100644 index 000000000..c5ec1e6da --- /dev/null +++ b/man/std::filesystem::path::assign.3 @@ -0,0 +1,59 @@ +.TH std::filesystem::path::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::assign \- std::filesystem::path::assign + +.SH Synopsis + path& assign( string_type&& source ); \fB(1)\fP \fI(since C++17)\fP + template< class Source > \fB(2)\fP \fI(since C++17)\fP + path& assign( const Source& source ); + template< class InputIt > \fB(3)\fP \fI(since C++17)\fP + path& assign( InputIt first, InputIt last ); + + Replaces the contents to the path object by a new pathname constructed from the + given character sequence. + + 1) Assigns the pathname identified by the detected-format string source, which is + left in valid, but unspecified state. + 2) Assigns the pathname identified by the detected-format character range source. + 3) Assigns the pathname identified by detected-format character range [first, last). + + \fB(2)\fP participates in overload resolution only if Source and path are not the same + type, and either: + + * Source is a specialization of std::basic_string or std::basic_string_view, or + * std::iterator_traits>::value_type is valid and denotes a + possibly const-qualified encoding character type (char, + char8_t, + \fI(since C++20)\fPchar16_t, char32_t, or wchar_t). + +.SH Parameters + + a character range to use, represented as std::string, + source - std::string_view, pointer to a null-terminated multibyte string, or as + an input iterator with char value type that points to a + null-terminated multibyte string + first, last - a character range to use +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of InputIt must be one of the encoded character types (char, wchar_t, + char16_t and char32_t) + +.SH Return value + + *this + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3244 C++17 constraint that Source cannot be path was added + missing + +.SH See also + + operator= assigns another path + \fI(public member function)\fP diff --git a/man/std::filesystem::path::begin,std::filesystem::path::end.3 b/man/std::filesystem::path::begin,std::filesystem::path::end.3 new file mode 100644 index 000000000..9507235d1 --- /dev/null +++ b/man/std::filesystem::path::begin,std::filesystem::path::end.3 @@ -0,0 +1,66 @@ +.TH std::filesystem::path::begin,std::filesystem::path::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::begin,std::filesystem::path::end \- std::filesystem::path::begin,std::filesystem::path::end + +.SH Synopsis + iterator begin() const; \fB(1)\fP \fI(since C++17)\fP + iterator end() const; \fB(2)\fP \fI(since C++17)\fP + + 1) Returns an iterator to the first element of the path. If the path is empty, the + returned iterator is equal to end(). + 2) Returns an iterator one past the last element of the path. Dereferencing this + iterator is undefined behavior. + + The sequence denoted by this pair of iterators consists of the following: + + 1. root-name (if any). + 2. root-directory (if any). + 3. Sequence of file-names, omitting any directory separators. + 4. If there is a directory separator after the last file-name in the path, the last + element before the end iterator is an empty element. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Iterator to the first element of the path. + 2) Iterator one past the end of the path + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + const fs::path p = + # ifdef _WIN32 + "C:\\\\users\\\\abcdef\\\\AppData\\\\Local\\\\Temp\\\\"; + # else + "/home/user/.config/Cppcheck/Cppcheck-GUI.conf"; + # endif + std::cout << "Examining the path " << p << " through iterators gives\\n"; + for (auto it = p.begin(); it != p.end(); ++it) + std::cout << *it << " │ "; + std::cout << '\\n'; + } + +.SH Possible output: + + --- Windows --- + Examining the path "C:\\users\\abcdef\\AppData\\Local\\Temp\\" through iterators gives + "C:" │ "/" │ "users" │ "abcdef" │ "AppData" │ "Local" │ "Temp" │ "" │ + + --- UNIX --- + Examining the path "/home/user/.config/Cppcheck/Cppcheck-GUI.conf" through iterators gives + "/" │ "home" │ "user" │ ".config" │ "Cppcheck" │ "Cppcheck-GUI.conf" │ diff --git a/man/std::filesystem::path::c_str,std::filesystem::path::native,.3 b/man/std::filesystem::path::c_str,std::filesystem::path::native,.3 new file mode 100644 index 000000000..f07d56433 --- /dev/null +++ b/man/std::filesystem::path::c_str,std::filesystem::path::native,.3 @@ -0,0 +1,93 @@ +.TH std::filesystem::path::c_str,std::filesystem::path::native, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::c_str,std::filesystem::path::native, \- std::filesystem::path::c_str,std::filesystem::path::native, + +.SH Synopsis + + const value_type* c_str() const noexcept; \fB(1)\fP \fI(since C++17)\fP + const string_type& native() const noexcept; \fB(2)\fP \fI(since C++17)\fP + operator string_type() const; \fB(3)\fP \fI(since C++17)\fP + + Accesses the native path name as a character string. + + 1) Equivalent to native().c_str(). + 2) Returns the native-format representation of the pathname by reference. + 3) Returns the native-format representation of the pathname by value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The native string representation of the pathname, using native syntax, native + character type, and native character encoding. This string is suitable for use with + OS APIs. + +.SH Notes + + The conversion function \fB(3)\fP is provided so that APIs that accept std::basic_string + file names can use pathnames with no changes to code. + +.SH Example + + +// Run this code + + #include + #ifdef _MSC_VER + #include + #include + #else + #include + #include + #endif + #include + #include + + int main() + { + #ifdef _MSC_VER + _setmode(_fileno(stderr), _O_WTEXT); + #else + std::setlocale(LC_ALL, ""); + std::locale::global(std::locale("")); + #endif + + std::filesystem::path p(u8"要らない.txt"); + std::ofstream(p) << "File contents"; // Prior to LWG2676 uses operator string_type() + // on MSVC, where string_type is wstring, only + // works due to non-standard extension. + // Post-LWG2676 uses new fstream constructors + + // Native string representation can be used with OS-specific APIs + #ifdef _MSC_VER + if (std::FILE* f = _wfopen(p.c_str(), L"r")) + #else + if (std::FILE* f = std::fopen(p.c_str(), "r")) + #endif + { + for (int ch; (ch = fgetc(f)) != EOF; std::putchar(ch)) + {} + std::fclose(f); + } + + std::filesystem::remove(p); + } + +.SH Possible output: + + File contents + +.SH See also + + string + wstring returns the path in native pathname format converted to a string + u8string \fI(public member function)\fP + u16string + u32string + generic_string + generic_wstring returns the path in generic pathname format converted to a string + generic_u8string \fI(public member function)\fP + generic_u16string + generic_u32string diff --git a/man/std::filesystem::path::clear.3 b/man/std::filesystem::path::clear.3 new file mode 100644 index 000000000..4fe3ea9ed --- /dev/null +++ b/man/std::filesystem::path::clear.3 @@ -0,0 +1,16 @@ +.TH std::filesystem::path::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::clear \- std::filesystem::path::clear + +.SH Synopsis + void clear() noexcept; \fI(since C++17)\fP + + Clears the stored pathname. empty() is true after the call. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP diff --git a/man/std::filesystem::path::compare.3 b/man/std::filesystem::path::compare.3 new file mode 100644 index 000000000..1ec130522 --- /dev/null +++ b/man/std::filesystem::path::compare.3 @@ -0,0 +1,111 @@ +.TH std::filesystem::path::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::compare \- std::filesystem::path::compare + +.SH Synopsis + int compare( const path& p ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + int compare( const string_type& str ) const; \fB(2)\fP \fI(since C++17)\fP + int compare( std::basic_string_view str ) const; + int compare( const value_type* s ) const; \fB(3)\fP \fI(since C++17)\fP + + Compares the lexical representations of the path and another path. + + 1) If root_name().native().compare(p.root_name().native()) is nonzero, returns that + value. + Otherwise, if has_root_directory() != p.has_root_directory(), returns a value less + than zero if has_root_directory() is false and a value greater than zero otherwise. + Otherwise returns a value less than, equal to or greater than 0 if the relative + portion of the path (relative_path()) is respectively lexicographically less than, + equal to or greater than the relative portion of p (p.relative_path()). Comparison + is performed element-wise, as if by iterating both paths from begin() to end() and + comparing the result of native() for each element. + 2) Equivalent to compare(path(str)). + 3) Equivalent to compare(path(s)). + +.SH Parameters + + p - a path to compare to + str - a string or string view representing path to compare to + s - a null-terminated string representing path to compare to + +.SH Return value + + A value less than 0 if the path is lexicographically less than the given path. + + A value equal to 0 if the path is lexicographically equal to the given path. + + A value greater than 0 if the path is lexicographically greater than the given path. + +.SH Exceptions + + 2,3) May throw implementation-defined exceptions. + +.SH Notes + + For two-way comparisons, binary operators may be more suitable. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + void demo(fs::path p1, fs::path p2, std::string_view msg) + { + std::cout << p1; + const int rc = p1.compare(p2); + if (rc < 0) + std::cout << " < "; + else if (rc > 0) + std::cout << " > "; + else + std::cout << " == "; + std::cout << p2 << " \\t: " << msg << '\\n'; + } + + int main() + { + demo("/a/b/", "/a/b/", "simple"); + demo("/a/b/", "/a/b/c", "simple"); + demo("/a/b/../b", "/a/b", "no canonical conversion"); + demo("/a/b", "/a/b/.", "no canonical conversion"); + demo("/a/b/", "a/c", "absolute paths order after relative ones"); + } + +.SH Output: + + "/a/b/" == "/a/b/" : simple + "/a/b/" < "/a/b/c" : simple + "/a/b/../b" > "/a/b" : no canonical conversion + "/a/b" < "/a/b/." : no canonical conversion + "/a/b/" > "a/c" : absolute paths order after relative ones + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2936 C++17 compared all path elements root name and root directory handled + directly separately + +.SH See also + + operator== + operator!= + operator< + operator<= + operator> + operator>= + operator<=> lexicographically compares two paths + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + \fI(C++17)\fP\fI(until C++20)\fP + (C++20) diff --git a/man/std::filesystem::path::concat,std::filesystem::path::operator+=.3 b/man/std::filesystem::path::concat,std::filesystem::path::operator+=.3 new file mode 100644 index 000000000..dc1f4327e --- /dev/null +++ b/man/std::filesystem::path::concat,std::filesystem::path::operator+=.3 @@ -0,0 +1,115 @@ +.TH std::filesystem::path::concat,std::filesystem::path::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::concat,std::filesystem::path::operator+= \- std::filesystem::path::concat,std::filesystem::path::operator+= + +.SH Synopsis + path& operator+=( const path& p ); \fB(1)\fP \fI(since C++17)\fP + path& operator+=( const string_type& str ); \fB(2)\fP \fI(since C++17)\fP + path& operator+=( std::basic_string_view str ); + path& operator+=( const value_type* ptr ); \fB(3)\fP \fI(since C++17)\fP + path& operator+=( value_type x ); \fB(4)\fP \fI(since C++17)\fP + template< class CharT > \fB(5)\fP \fI(since C++17)\fP + path& operator+=( CharT x ); + template< class Source > \fB(6)\fP \fI(since C++17)\fP + path& operator+=( const Source& source ); + template< class Source > \fB(7)\fP \fI(since C++17)\fP + path& concat( const Source& source ); + template< class InputIt > \fB(8)\fP \fI(since C++17)\fP + path& concat( InputIt first, InputIt last ); + + Concatenates the current path and the argument + + 1-3,6,7) Appends path(p).native() to the pathname stored in *this in the native + format. This directly manipulates the value of native() and may not be portable + between operating systems. + 4,5) Same as return *this += std::basic_string_view(&x, 1);. + 8) Same as return *this += path(first, last);. + + \fB(6)\fP and \fB(7)\fP participate in overload resolution only if Source and path are not the + same type, and either: + + * Source is a specialization of std::basic_string or std::basic_string_view, or + * std::iterator_traits>::value_type is valid and denotes a + possibly const-qualified encoding character type (char, + char8_t, + \fI(since C++20)\fPchar16_t, char32_t, or wchar_t). + +.SH Parameters + + p - path to append + str - string or string view to append + ptr - pointer to the beginning of a null-terminated string to append + x - single character to append + std::basic_string, std::basic_string_view, null-terminated + source - multicharacter string, or an input iterator pointing to a + null-terminated multicharacter sequence, which represents a path name + (either in portable or in native format) + first, last - pair of LegacyInputIterators that specify a multicharacter sequence + that represents a path name +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of InputIt must be one of the encoded character types (char, wchar_t, + char16_t and char32_t). + - + CharT must be one of the encoded character types (char, wchar_t, char16_t and + char32_t). + +.SH Return value + + *this + +.SH Exceptions + + May throw std::bad_alloc if memory allocation fails. + +.SH Notes + + Unlike with append() or operator/=, additional directory separators are never + introduced. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::filesystem::path p1; // an empty path + p1 += "var"; // does not insert a separator + std::cout << R"("" + "var" --> )" << p1 << '\\n'; + p1 += "lib"; // does not insert a separator + std::cout << R"("var" + "lib" --> )" << p1 << '\\n'; + auto str = std::string{"1234567"}; + p1.concat(std::begin(str) + 3, std::end(str) - 1); + std::cout << "p1.concat --> " << p1 << '\\n'; + } + +.SH Output: + + "" + "var" --> "var" + "var" + "lib" --> "varlib" + p1.concat --> "varlib456" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3055 C++17 the specification of concatenating a single made well-formed + character was ill-formed + LWG 3244 C++17 constraint that Source cannot be path was added + missing + +.SH See also + + append appends elements to the path with a directory separator + operator/= \fI(public member function)\fP + operator/ concatenates two paths with a directory separator + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::path::empty.3 b/man/std::filesystem::path::empty.3 new file mode 100644 index 000000000..0cb5decb7 --- /dev/null +++ b/man/std::filesystem::path::empty.3 @@ -0,0 +1,31 @@ +.TH std::filesystem::path::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::empty \- std::filesystem::path::empty + +.SH Synopsis + bool empty() const noexcept; \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the path in generic format is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the path is empty, false otherwise. + +.SH Notes + + An empty path can be obtained by calling clear and by default-constructing a path. + It can also be returned by a path decomposition function (such as extension) if the + corresponding component is not present in the path. + + An empty path is classified as a relative path. + +.SH See also + + constructor constructs a path + \fI(public member function)\fP diff --git a/man/std::filesystem::path::extension.3 b/man/std::filesystem::path::extension.3 new file mode 100644 index 000000000..e45c888f0 --- /dev/null +++ b/man/std::filesystem::path::extension.3 @@ -0,0 +1,92 @@ +.TH std::filesystem::path::extension 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::extension \- std::filesystem::path::extension + +.SH Synopsis + path extension() const; \fI(since C++17)\fP + + Returns the extension of the filename component of the generic-format view of *this. + + If the filename() component of the generic-format path contains a period (.), and is + not one of the special filesystem elements dot or dot-dot, then the extension is the + substring beginning at the rightmost period (including the period) and until the end + of the pathname. + + If the first character in the filename is a period, that period is ignored (a + filename like ".profile" is not treated as an extension). + + If the pathname is either . or .., or if filename() does not contain the '.' + character, then empty path is returned. + + Additional behavior may be defined by the implementations for file systems which + append additional elements (such as alternate data streams or partitioned dataset + names) to extensions. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The extension of the current pathname or an empty path if there's no extension. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + The extension as returned by this function includes a period to make it possible to + distinguish the file that ends with a period \fI(function returns ".") from a file with\fP + no extension \fI(function returns "").\fP + + On a non-POSIX system, it is possible that p.stem() + p.extension() != p.filename() + even though generic-format versions are the same. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << fs::path("/foo/bar.txt").extension() << '\\n' + << fs::path("/foo/bar.").extension() << '\\n' + << fs::path("/foo/bar").extension() << '\\n' + << fs::path("/foo/bar.txt/bar.cc").extension() << '\\n' + << fs::path("/foo/bar.txt/bar.").extension() << '\\n' + << fs::path("/foo/bar.txt/bar").extension() << '\\n' + << fs::path("/foo/.").extension() << '\\n' + << fs::path("/foo/..").extension() << '\\n' + << fs::path("/foo/.hidden").extension() << '\\n' + << fs::path("/foo/..bar").extension() << '\\n'; + } + +.SH Output: + + ".txt" + "." + "" + ".cc" + "." + "" + "" + "" + "" + ".bar" + +.SH See also + + filename returns the filename path component + \fI(public member function)\fP + returns the stem path component (filename without the final + stem extension) + \fI(public member function)\fP + replace_extension replaces the extension + \fI(public member function)\fP + has_extension checks if the corresponding path element is not empty + \fI(public member function)\fP diff --git a/man/std::filesystem::path::filename.3 b/man/std::filesystem::path::filename.3 new file mode 100644 index 000000000..faf3ebad6 --- /dev/null +++ b/man/std::filesystem::path::filename.3 @@ -0,0 +1,68 @@ +.TH std::filesystem::path::filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::filename \- std::filesystem::path::filename + +.SH Synopsis + path filename() const; \fI(since C++17)\fP + + Returns the generic-format filename component of the path. + + Equivalent to relative_path().empty() ? path() : *--end(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The filename identified by the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << fs::path("/foo/bar.txt").filename() << '\\n' + << fs::path("/foo/.bar").filename() << '\\n' + << fs::path("/foo/bar/").filename() << '\\n' + << fs::path("/foo/.").filename() << '\\n' + << fs::path("/foo/..").filename() << '\\n' + << fs::path(".").filename() << '\\n' + << fs::path("..").filename() << '\\n' + << fs::path("/").filename() << '\\n' + << fs::path("//host").filename() << '\\n'; + } + +.SH Output: + + "bar.txt" + ".bar" + "" + "." + ".." + "." + ".." + "" + "host" + +.SH See also + + extension returns the file extension path component + \fI(public member function)\fP + returns the stem path component (filename without the final + stem extension) + \fI(public member function)\fP + replace_filename replaces the last path component with another path + \fI(public member function)\fP + has_filename checks if the corresponding path element is not empty + \fI(public member function)\fP diff --git a/man/std::filesystem::path::format.3 b/man/std::filesystem::path::format.3 new file mode 100644 index 000000000..18b37d1df --- /dev/null +++ b/man/std::filesystem::path::format.3 @@ -0,0 +1,31 @@ +.TH std::filesystem::path::format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::format \- std::filesystem::path::format + +.SH Synopsis + enum format { + + native_format, + generic_format, \fI(since C++17)\fP + auto_format + + }; + + Determines how string representations of pathnames are interpreted by the + constructors of std::filesystem::path that accept strings. + +.SH Constants + + Value Explanation + native_format Native pathname format + generic_format Generic pathname format + auto_format Implementation-defined pathname format, auto-detected where possible + +.SH Notes + + On POSIX systems, there is no difference between native and generic format. + +.SH See also + + constructor constructs a path + \fI(public member function)\fP diff --git a/man/std::filesystem::path::generic_string,std::filesystem::path::generic_wstring,.3 b/man/std::filesystem::path::generic_string,std::filesystem::path::generic_wstring,.3 new file mode 100644 index 000000000..4392e3f51 --- /dev/null +++ b/man/std::filesystem::path::generic_string,std::filesystem::path::generic_wstring,.3 @@ -0,0 +1,116 @@ +.TH std::filesystem::path::generic_string,std::filesystem::path::generic_wstring, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::generic_string,std::filesystem::path::generic_wstring, \- std::filesystem::path::generic_string,std::filesystem::path::generic_wstring, + +.SH Synopsis + std::filesystem::path::generic_u32string + + template< class CharT, class Traits = + std::char_traits, + (since + class Alloc = std::allocator > \fB(1)\fP C++17) + std::basic_string + + generic_string( const Alloc& a = Alloc() ) const; + std::string generic_string() const; + std::wstring generic_wstring() const; + std::u16string generic_u16string() const; + std::u32string generic_u32string() const; + \fB(2)\fP (since (since + std::string generic_u8string() const; C++17) C++17) + \fB(3)\fP (until + C++20) + std::u8string generic_u8string() const; (since + C++20) + + Returns the internal pathname in generic pathname format, converted to specific + string type. Conversion, if any, is specified as follows: + + + * If path::value_type is char, conversion, if any, is system-dependent. This is + the case on typical POSIX systems (such as Linux), where native encoding is + UTF-8 and string() performs no conversion. + * Otherwise, if path::value_type is wchar_t, conversion, if any, is unspecified. + This is the case on Windows, where wchar_t is 16 bit and the native encoding is + UTF-16. + * Otherwise, if path::value_type is char16_t, native encoding is UTF-16 and the + conversion method is unspecified. + * Otherwise, if path::value_type is char32_t, native encoding is UTF-32 and the + conversion method is unspecified. + * Otherwise, if path::value_type is char8_t, native encoding is UTF-8 and the + conversion method is unspecified. + + The / character is used as the directory separator. + + 1) All memory allocations are performed by a. + 3) The result encoding in the case of u8string() is always UTF-8. + +.SH Parameters + + a - allocator to construct the string with +.SH Type requirements + - + CharT must be one of the encoded character types (char, wchar_t + , char8_t + \fI(since C++20)\fP, char16_t and char32_t). + +.SH Return value + + The internal pathname in generic pathname format, converted to specified string + type. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(std::string_view rem, auto const& str) + { + std::cout << rem << std::hex << std::uppercase << std::setfill('0'); + for (const auto b : std::as_bytes(std::span{str})) + std::cout << std::setw(2) << std::to_integer(b) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::filesystem::path p{"/家/屋"}; + std::cout << p << '\\n'; + + print("string : ", p.generic_string()); + print("u8string : ", p.generic_u8string()); + print("u16string : ", p.generic_u16string()); + print("u32string : ", p.generic_u32string()); + print("wstring : ", p.generic_wstring()); + } + +.SH Possible output: + + "/家/屋" + string : 2F E5 AE B6 2F E5 B1 8B + u8string : 2F E5 AE B6 2F E5 B1 8B + u16string : 2F 00 B6 5B 2F 00 4B 5C + u32string : 2F 00 00 00 B6 5B 00 00 2F 00 00 00 4B 5C 00 00 + wstring : 2F 00 00 00 B6 5B 00 00 2F 00 00 00 4B 5C 00 00 + +.SH See also + + string + wstring returns the path in native pathname format converted to a string + u8string \fI(public member function)\fP + u16string + u32string + +.SH Category: + * Uses of dcl rev begin with nonempty note diff --git a/man/std::filesystem::path::has_root_path,std::filesystem::path::has_root_name,.3 b/man/std::filesystem::path::has_root_path,std::filesystem::path::has_root_name,.3 new file mode 100644 index 000000000..003bcf1f0 --- /dev/null +++ b/man/std::filesystem::path::has_root_path,std::filesystem::path::has_root_name,.3 @@ -0,0 +1,52 @@ +.TH std::filesystem::path::has_root_path,std::filesystem::path::has_root_name, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::has_root_path,std::filesystem::path::has_root_name, \- std::filesystem::path::has_root_path,std::filesystem::path::has_root_name, + +.SH Synopsis + std::filesystem::path::has_parent_path, std::filesystem::path::has_filename, + std::filesystem::path::has_stem, std::filesystem::path::has_extension + + bool has_root_path() const; \fB(1)\fP \fI(since C++17)\fP + bool has_root_name() const; \fB(2)\fP \fI(since C++17)\fP + bool has_root_directory() const; \fB(3)\fP \fI(since C++17)\fP + bool has_relative_path() const; \fB(4)\fP \fI(since C++17)\fP + bool has_parent_path() const; \fB(5)\fP \fI(since C++17)\fP + bool has_filename() const; \fB(6)\fP \fI(since C++17)\fP + bool has_stem() const; \fB(7)\fP \fI(since C++17)\fP + bool has_extension() const; \fB(8)\fP \fI(since C++17)\fP + + Checks whether the path contains the corresponding path element. + + 1) Checks whether root_path() is empty. + 2) Checks whether root_name() is empty. + 3) Checks whether root_directory() is empty. + 4) Checks whether relative_path() is empty. + 5) Checks whether parent_path() is empty. + 6) Checks whether filename() is empty. + 7) Checks whether stem() is empty. + 8) Checks whether extension() is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the corresponding path component is not empty, false otherwise. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + empty checks if the path is empty + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::path::is_absolute,is_relative.3 b/man/std::filesystem::path::is_absolute,is_relative.3 new file mode 100644 index 000000000..88f3df6f9 --- /dev/null +++ b/man/std::filesystem::path::is_absolute,is_relative.3 @@ -0,0 +1,34 @@ +.TH std::filesystem::path::is_absolute,is_relative 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::is_absolute,is_relative \- std::filesystem::path::is_absolute,is_relative + +.SH Synopsis + bool is_absolute() const; \fB(1)\fP \fI(since C++17)\fP + bool is_relative() const; \fB(2)\fP \fI(since C++17)\fP + + Checks whether the path is absolute or relative. An absolute path is a path that + unambiguously identifies the location of a file without reference to an additional + starting location. The first version returns true if the path, in native format, is + absolute, false otherwise; the second version the other way round. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) true if the path is absolute, false otherwise. + 2) false if the path is absolute, true otherwise. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + The path "/" is absolute on a POSIX OS, but is relative on Windows. + +.SH See also + + absolute composes an absolute path + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::path::lexically_normal,std::filesystem::path::lexically_relative,.3 b/man/std::filesystem::path::lexically_normal,std::filesystem::path::lexically_relative,.3 new file mode 100644 index 000000000..a41f0ffa6 --- /dev/null +++ b/man/std::filesystem::path::lexically_normal,std::filesystem::path::lexically_relative,.3 @@ -0,0 +1,100 @@ +.TH std::filesystem::path::lexically_normal,std::filesystem::path::lexically_relative, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::lexically_normal,std::filesystem::path::lexically_relative, \- std::filesystem::path::lexically_normal,std::filesystem::path::lexically_relative, + +.SH Synopsis + + path lexically_normal() const; \fB(1)\fP \fI(since C++17)\fP + path lexically_relative( const path& base ) const; \fB(2)\fP \fI(since C++17)\fP + path lexically_proximate( const path& base ) const; \fB(3)\fP \fI(since C++17)\fP + + 1) Returns *this converted to normal form in its generic format. + 2) Returns *this made relative to base. + + * First, if root_name() != base.root_name() is true or is_absolute() != + base.is_absolute() is true or (!has_root_directory() && + base.has_root_directory()) is true or any filename in relative_path() or + base.relative_path() can be interpreted as a root-name, returns a + default-constructed path. + * Otherwise, first determines the first mismatched element of *this and base as if + by auto [a, b] = mismatch(begin(), end(), base.begin(), base.end()), then + + * if a == end() and b == base.end(), returns path("."), + * otherwise, define N as the number of nonempty filename elements that are neither + dot nor dot-dot in [b, base.end()), minus the number of dot-dot filename + elements, If N < 0, returns a default-constructed path, + * otherwise, if N = 0 and a == end() || a->empty(), returns path("."), + * otherwise returns an object composed from + + * a default-constructed path() followed by + * N applications of operator/=(path("..")), followed by + * one application of operator/= for each element in the half-open range + [a, end()). + 3) If the value of lexically_relative(base) is not an empty path, return it. + Otherwise return *this. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The normal form of the path. + 2) The relative form of the path. + 3) The proximate form of the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + These conversions are purely lexical. They do not check that the paths exist, do not + follow symlinks, and do not access the filesystem at all. For symlink-following + counterparts of lexically_relative and lexically_proximate, see relative and + proximate. + + On Windows, the returned path has backslashes (the preferred separators). + + On POSIX, no filename in a relative path is acceptable as a root-name. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + assert(fs::path("a/./b/..").lexically_normal() == "a/"); + assert(fs::path("a/.///b/../").lexically_normal() == "a/"); + assert(fs::path("/a/d").lexically_relative("/a/b/c") == "../../d"); + assert(fs::path("/a/b/c").lexically_relative("/a/d") == "../b/c"); + assert(fs::path("a/b/c").lexically_relative("a") == "b/c"); + assert(fs::path("a/b/c").lexically_relative("a/b/c/x/y") == "../.."); + assert(fs::path("a/b/c").lexically_relative("a/b/c") == "."); + assert(fs::path("a/b").lexically_relative("c/d") == "../../a/b"); + assert(fs::path("a/b").lexically_relative("/a/b") == ""); + assert(fs::path("a/b").lexically_proximate("/a/b") == "a/b"); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3070 C++17 a filename that can also be a root-name treated as error case + may cause surprising result + LWG 3096 C++17 trailing "/" and "/." are handled corrected + incorrectly + +.SH See also + + relative composes a relative path + proximate \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::path::make_preferred.3 b/man/std::filesystem::path::make_preferred.3 new file mode 100644 index 000000000..d870de88c --- /dev/null +++ b/man/std::filesystem::path::make_preferred.3 @@ -0,0 +1,71 @@ +.TH std::filesystem::path::make_preferred 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::make_preferred \- std::filesystem::path::make_preferred + +.SH Synopsis + path& make_preferred(); \fI(since C++17)\fP + + Converts all directory separators in the generic-format view of the path to the + preferred directory separator. + + For example, on Windows, where \\ is the preferred separator, the path foo/bar will + be converted to foo\\bar. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + Windows can use / as a separator, but prefers \\, so make_preferred converts the + forward slashes to backslashes. On the other hand, POSIX does not use \\ as a + separator, because backslashes are valid filename characters — the Windows path on + POSIX actually refers to a file with the name "a\\\\b\\\\c". For this reason the + "separators" are not converted. + + +// Run this code + + #include + #include + + int main() + { + std::filesystem::path + windows_path("a\\\\b\\\\c"), + posix_path("a/b/c"); + + std::cout + << "Windows path: " + << windows_path << " -> " + << windows_path.make_preferred() << '\\n' + << "POSIX path: " + << posix_path << " -> " + << posix_path.make_preferred() << '\\n'; + } + +.SH Output: + + // on Windows + Windows path: "a\\\\b\\\\c" -> "a\\\\b\\\\c" + POSIX path: "a/b/c" -> "a\\\\b\\\\c" + + // on POSIX + Windows path: "a\\\\b\\\\c" -> "a\\\\b\\\\c" + POSIX path: "a/b/c" -> "a/b/c" + +.SH See also + + alternative directory separator which may be used in addition + constexpr value_type to the portable /. On Windows, this is the backslash character + preferred_separator \\. On POSIX, this is the same forward slash / as the portable + \fB[static]\fP separator + \fI(public static member constant)\fP diff --git a/man/std::filesystem::path::operator=.3 b/man/std::filesystem::path::operator=.3 new file mode 100644 index 000000000..6eaebe10d --- /dev/null +++ b/man/std::filesystem::path::operator=.3 @@ -0,0 +1,77 @@ +.TH std::filesystem::path::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::operator= \- std::filesystem::path::operator= + +.SH Synopsis + path& operator=( const path& p ); \fB(1)\fP \fI(since C++17)\fP + path& operator=( path&& p ) noexcept; \fB(2)\fP \fI(since C++17)\fP + path& operator=( string_type&& source ); \fB(3)\fP \fI(since C++17)\fP + template< class Source > \fB(4)\fP \fI(since C++17)\fP + path& operator=( const Source& source ); + + 1) Replaces the contents of *this with a pathname whose both native and generic + format representations equal those of p. + 2) Replaces the contents of *this with a pathname whose both native and generic + format representations equal those of p, possibly using move semantics: p is left in + a valid, but unspecified state. + 3) Replaces the contents of *this with a new path value constructed from + detected-format source, which is left in valid, but unspecified state. Equivalent to + assign(std::move(source)). + 4) Replaces the contents of *this with a new path value constructed from + detected-format source as if by overload \fB(4)\fP of the path constructor. Equivalent to + assign(source). + + \fB(4)\fP participates in overload resolution only if Source and path are not the same + type, and either: + + * Source is a specialization of std::basic_string or std::basic_string_view, or + * std::iterator_traits>::value_type is valid and denotes a + possibly const-qualified encoding character type (char, + char8_t, + \fI(since C++20)\fPchar16_t, char32_t, or wchar_t). + +.SH Parameters + + p - a path to assign + a std::basic_string, std::basic_string_view, pointer to a null-terminated + character/wide character string, or an input iterator that points to a + source - null-terminated character/wide character sequence. The character type must + be one of char, + char8_t, + \fI(since C++20)\fPchar16_t, char32_t, wchar_t + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + namespace fs = std::filesystem; + + int main() + { + fs::path p = "C:/users/abcdef/AppData/Local"; + p = p / "Temp"; // move assignment + const wchar_t* wstr = L"D:/猫.txt"; + p = wstr; // assignment from a source + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3244 C++17 constraint that Source cannot be path was added + missing + +.SH See also + + assign assigns contents + \fI(public member function)\fP + constructor constructs a path + \fI(public member function)\fP diff --git a/man/std::filesystem::path::parent_path.3 b/man/std::filesystem::path::parent_path.3 new file mode 100644 index 000000000..8d8dcd05d --- /dev/null +++ b/man/std::filesystem::path::parent_path.3 @@ -0,0 +1,55 @@ +.TH std::filesystem::path::parent_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::parent_path \- std::filesystem::path::parent_path + +.SH Synopsis + path parent_path() const; \fI(since C++17)\fP + + Returns the path to the parent directory. + + If has_relative_path() returns false, the result is a copy of *this. Otherwise, the + result is a path whose generic format pathname is the longest prefix of the generic + format pathname of *this that produces one fewer element in its iteration. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The path to the parent directory, or a copy of *this if not has_relative_path(). + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + for (fs::path p : {"/var/tmp/example.txt", "/", "/var/tmp/."}) + std::cout << "The parent path of " << p + << " is " << p.parent_path() << '\\n'; + } + +.SH Possible output: + + The parent path of "/var/tmp/example.txt" is "/var/tmp" + The parent path of "/" is "/" + The parent path of "/var/tmp/." is "/var/tmp" + +.SH See also + + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_directory returns the root directory of the path, if present + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP diff --git a/man/std::filesystem::path::path.3 b/man/std::filesystem::path::path.3 new file mode 100644 index 000000000..52361c36a --- /dev/null +++ b/man/std::filesystem::path::path.3 @@ -0,0 +1,140 @@ +.TH std::filesystem::path::path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::path \- std::filesystem::path::path + +.SH Synopsis + path() noexcept; \fB(1)\fP \fI(since C++17)\fP + path( const path& p ); \fB(2)\fP \fI(since C++17)\fP + path( path&& p ) noexcept; \fB(3)\fP \fI(since C++17)\fP + path( string_type&& source, format fmt = auto_format ); \fB(4)\fP \fI(since C++17)\fP + template< class Source > \fB(5)\fP \fI(since C++17)\fP + path( const Source& source, format fmt = auto_format ); + template< class InputIt > \fB(6)\fP \fI(since C++17)\fP + path( InputIt first, InputIt last, format fmt = auto_format ); + template< class Source > + path( const Source& source, const std::locale& loc, format fmt = \fB(7)\fP \fI(since C++17)\fP + auto_format ); + template< class InputIt > + path( InputIt first, InputIt last, const std::locale& loc, format \fB(8)\fP \fI(since C++17)\fP + fmt = auto_format ); + + Constructs a new path object. + + 1) Constructs an empty path. + 2) Copy constructor. Constructs a path whose pathname, in both native and generic + formats, is the same as that of p. + 3) Move constructor. Constructs a path whose pathname, in both native and generic + formats, is the same as that of p, p is left in valid but unspecified state. + 4-6) Constructs the path from a character sequence (format interpreted as specified + by fmt) provided by source (4,5), which is a pointer or an input iterator to a + null-terminated character/wide character sequence, an std::basic_string or an + std::basic_string_view, or represented as a pair of input iterators [first, last) + \fB(6)\fP. Any of the character types char, + char8_t, + \fI(since C++20)\fPchar16_t, char32_t, wchar_t is allowed, and the method of conversion to + the native character set depends on the character type used by source. + + * If the source character type is char, the encoding of the source is assumed to + be the native narrow encoding (so no conversion takes place on POSIX systems). + + * If the source character type is char8_t, conversion from UTF-8 to \fI(since C++20)\fP + native filesystem encoding is used. + + * If the source character type is char16_t, conversion from UTF-16 to native + filesystem encoding is used. + * If the source character type is char32_t, conversion from UTF-32 to native + filesystem encoding is used. + * If the source character type is wchar_t, the input is assumed to be the native + wide encoding (so no conversion takes places on Windows). + 7,8) Constructs the path from a character sequence (format interpreted as specified + by fmt) provided by source \fB(7)\fP, which is a pointer or an input iterator to a + null-terminated character sequence, an std::string, an std::string_view, or + represented as a pair of input iterators [first, last) \fB(8)\fP. The only character type + allowed is char. Uses loc to perform the character encoding conversion. If + value_type is wchar_t, converts from to wide using the std::codecvt facet of loc. Otherwise, first converts to wide using the + std::codecvt facet and then converts to filesystem + native character type using std::codecvt facet of loc. + + \fB(5)\fP and \fB(7)\fP participate in overload resolution only if Source and path are not the + same type, and either: + + * Source is a specialization of std::basic_string or std::basic_string_view, or + * std::iterator_traits>::value_type is valid and denotes a + possibly const-qualified encoding character type (char, + char8_t, + \fI(since C++20)\fPchar16_t, char32_t, or wchar_t). + +.SH Parameters + + p - a path to copy + std::basic_string, std::basic_string_view, pointer to a + source - null-terminated character string, or input iterator with a character + value type that points to a null-terminated character sequence (the + character type must be char for overload \fB(7)\fP) + first, last - pair of LegacyInputIterators that specify a character sequence + fmt - enumerator of type path::format which specifies how pathname format is + to be interpreted + loc - locale that defines encoding conversion to use +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of InputIt must be one of the character types char, wchar_t, + char8_t, + \fI(since C++20)\fPchar16_t and char32_t to use the overload \fB(6)\fP. + - + The value type of InputIt must be char to use the overload \fB(8)\fP. + +.SH Exceptions + + 2,4-8) May throw implementation-defined exceptions. + +.SH Notes + + For portable pathname generation from Unicode strings, see u8path. \fI(until C++20)\fP + path constructor supports creation from UTF-8 string when the source \fI(since C++20)\fP + is a sequence of char8_t. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::path p1 = "/usr/lib/sendmail.cf"; // portable format + fs::path p2 = "C:\\\\users\\\\abcdef\\\\AppData\\\\Local\\\\Temp\\\\"; // native format + fs::path p3 = U"D:/猫.txt"; // UTF-32 string + fs::path p4 = u8"~/狗.txt"; // UTF-8 string + + std::cout << "p1 = " << p1 << '\\n' + << "p2 = " << p2 << '\\n' + << "p3 = " << p3 << '\\n' + << "p4 = " << p4 << '\\n'; + } + +.SH Output: + + p1 = "/usr/lib/sendmail.cf" + p2 = "C:\\\\users\\\\abcdef\\\\AppData\\\\Local\\\\Temp\\\\" + p3 = "D:/猫.txt" + p4 = "~/狗.txt" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3244 C++17 constraint that Source cannot be path was added + missing + +.SH See also + + u8path creates a path from a UTF-8 encoded source + \fI(C++17)\fP(deprecated in C++20) \fI(function)\fP diff --git a/man/std::filesystem::path::relative_path.3 b/man/std::filesystem::path::relative_path.3 new file mode 100644 index 000000000..680951e51 --- /dev/null +++ b/man/std::filesystem::path::relative_path.3 @@ -0,0 +1,55 @@ +.TH std::filesystem::path::relative_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::relative_path \- std::filesystem::path::relative_path + +.SH Synopsis + path relative_path() const; \fI(since C++17)\fP + + Returns path relative to root-path, that is, a pathname composed of every + generic-format component of *this after root-path. If *this is an empty path, + returns an empty path. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Path relative to the root path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::path p = fs::current_path(); + + std::cout << "The current path " << p << " decomposes into:\\n" + << "root-path " << p.root_path() << '\\n' + << "relative path " << p.relative_path() << '\\n'; + } + +.SH Possible output: + + The current path "C:\\Users\\abcdef\\Local Settings\\temp" decomposes into: + root-path "C:\\" + relative path "Users\\abcdef\\Local Settings\\temp" + +.SH See also + + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_directory returns the root directory of the path, if present + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP diff --git a/man/std::filesystem::path::remove_filename.3 b/man/std::filesystem::path::remove_filename.3 new file mode 100644 index 000000000..66f943039 --- /dev/null +++ b/man/std::filesystem::path::remove_filename.3 @@ -0,0 +1,60 @@ +.TH std::filesystem::path::remove_filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::remove_filename \- std::filesystem::path::remove_filename + +.SH Synopsis + path& remove_filename(); \fI(since C++17)\fP + + Removes a single generic-format filename component (as returned by filename) from + the given generic-format path. + + After this function completes, has_filename returns false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::path p; + std::cout << std::boolalpha + << (p = "foo/bar").remove_filename() << '\\t' << p.has_filename() << '\\n' + << (p = "foo/").remove_filename() << '\\t' << p.has_filename() << '\\n' + << (p = "/foo").remove_filename() << '\\t' << p.has_filename() << '\\n' + << (p = "/").remove_filename() << '\\t' << p.has_filename() << '\\n' + << (p = "").remove_filename() << '\\t' << p.has_filename() << '\\n'; + } + +.SH Output: + + "foo/" false + "foo/" false + "/" false + "/" false + "" false + +.SH See also + + filename returns the filename path component + \fI(public member function)\fP + replace_filename replaces the last path component with another path + \fI(public member function)\fP + has_filename checks if the corresponding path element is not empty + \fI(public member function)\fP diff --git a/man/std::filesystem::path::replace_extension.3 b/man/std::filesystem::path::replace_extension.3 new file mode 100644 index 000000000..c0bcfcb3d --- /dev/null +++ b/man/std::filesystem::path::replace_extension.3 @@ -0,0 +1,105 @@ +.TH std::filesystem::path::replace_extension 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::replace_extension \- std::filesystem::path::replace_extension + +.SH Synopsis + path& replace_extension( const path& replacement = path() ); \fI(since C++17)\fP + + Replaces the extension with replacement or removes it when the default value of + replacement is used. + + Firstly, if this path has an extension(), it is removed from the generic-format view + of the pathname. + + Then, a dot character is appended to the generic-format view of the pathname, if + replacement is not empty and does not begin with a dot character. + + Then replacement is appended as if by operator+=(replacement). + +.SH Parameters + + replacement - the extension to replace with + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + The type of replacement is std::filesystem::path even though it is not intended to + represent an object on the file system in order to correctly account for the + filesystem character encoding. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const int width1{18}, width2{11}; // columns' width + + std::cout << std::left << std::setw(width1) << "Path:" + << std::setw(width2) << "Ext:" << "Result:\\n"; + for (const auto& [p, e] : { + std::make_pair("/foo/bar.jpg", ".png"), + {"/foo/bar.jpg", "png"}, + {"/foo/bar.jpg", "."}, + {"/foo/bar.jpg", ""}, + {"/foo/bar.", "png"}, + {"/foo/bar", ".png"}, + {"/foo/bar", "png"}, + {"/foo/bar", "."}, + {"/foo/bar", ""}, + {"/foo/.", ".png"}, + {"/foo/.", "png"}, + {"/foo/.", "."}, + {"/foo/.", ""}, + {"/foo/", ".png"}, + {"/foo/", "png"}}) + { + std::filesystem::path path{p}, ext{e}; + std::cout << std::setw(width1) << path << std::setw(width2) << ext; + path.replace_extension(ext); + std::cout << path << '\\n'; + } + } + +.SH Output: + + Path: Ext: Result: + "/foo/bar.jpg" ".png" "/foo/bar.png" + "/foo/bar.jpg" "png" "/foo/bar.png" + "/foo/bar.jpg" "." "/foo/bar." + "/foo/bar.jpg" "" "/foo/bar" + "/foo/bar." "png" "/foo/bar.png" + "/foo/bar" ".png" "/foo/bar.png" + "/foo/bar" "png" "/foo/bar.png" + "/foo/bar" "." "/foo/bar." + "/foo/bar" "" "/foo/bar" + "/foo/." ".png" "/foo/..png" + "/foo/." "png" "/foo/..png" + "/foo/." "." "/foo/.." + "/foo/." "" "/foo/." + "/foo/" ".png" "/foo/.png" + "/foo/" "png" "/foo/.png" + +.SH See also + + extension returns the file extension path component + \fI(public member function)\fP + filename returns the filename path component + \fI(public member function)\fP + stem returns the stem path component (filename without the final extension) + \fI(public member function)\fP + has_extension checks if the corresponding path element is not empty + \fI(public member function)\fP diff --git a/man/std::filesystem::path::replace_filename.3 b/man/std::filesystem::path::replace_filename.3 new file mode 100644 index 000000000..e40a4acfa --- /dev/null +++ b/man/std::filesystem::path::replace_filename.3 @@ -0,0 +1,55 @@ +.TH std::filesystem::path::replace_filename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::replace_filename \- std::filesystem::path::replace_filename + +.SH Synopsis + path& replace_filename( const path& replacement ); \fI(since C++17)\fP + + Replaces a single filename component with replacement. + + Equivalent to: remove_filename(); return operator/=(replacement);. + +.SH Parameters + + replacement - path used for replacing the filename component + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << fs::path("/foo").replace_filename("bar") << '\\n' + << fs::path("/").replace_filename("bar") << '\\n' + << fs::path("").replace_filename("pub") << '\\n'; + } + +.SH Output: + + "/bar" + "/bar" + "pub" + +.SH See also + + replace_extension replaces the extension + \fI(public member function)\fP + filename returns the filename path component + \fI(public member function)\fP + remove_filename removes filename path component + \fI(public member function)\fP + has_filename checks if the corresponding path element is not empty + \fI(public member function)\fP diff --git a/man/std::filesystem::path::root_directory.3 b/man/std::filesystem::path::root_directory.3 new file mode 100644 index 000000000..6dfcff8a1 --- /dev/null +++ b/man/std::filesystem::path::root_directory.3 @@ -0,0 +1,54 @@ +.TH std::filesystem::path::root_directory 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::root_directory \- std::filesystem::path::root_directory + +.SH Synopsis + path root_directory() const; \fI(since C++17)\fP + + Returns the root directory of the generic-format path. If the path (in generic + format) does not include root directory, returns path(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The root directory of the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::path p = fs::current_path(); + + std::cout << "The current path " << p << " decomposes into:\\n" + << "root name " << p.root_name() << '\\n' + << "root directory " << p.root_directory() << '\\n' + << "relative path " << p.relative_path() << '\\n'; + } + +.SH Possible output: + + The current path "C:\\Users\\abcdef\\Local Settings\\temp" decomposes into: + root name "C:" + root directory "\\" + relative path "Users\\abcdef\\Local Settings\\temp" + +.SH See also + + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP diff --git a/man/std::filesystem::path::root_name.3 b/man/std::filesystem::path::root_name.3 new file mode 100644 index 000000000..e92ac2b09 --- /dev/null +++ b/man/std::filesystem::path::root_name.3 @@ -0,0 +1,46 @@ +.TH std::filesystem::path::root_name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::root_name \- std::filesystem::path::root_name + +.SH Synopsis + path root_name() const; \fI(since C++17)\fP + + Returns the root name of the generic-format path. If the path (in generic format) + does not include root name, returns path(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The root name of the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << "Current root name is: " << fs::current_path().root_name() << '\\n'; + } + +.SH Possible output: + + Current root name is: "C:" + +.SH See also + + root_directory returns the root directory of the path, if present + \fI(public member function)\fP + root_path returns the root path of the path, if present + \fI(public member function)\fP diff --git a/man/std::filesystem::path::root_path.3 b/man/std::filesystem::path::root_path.3 new file mode 100644 index 000000000..44aa3a333 --- /dev/null +++ b/man/std::filesystem::path::root_path.3 @@ -0,0 +1,48 @@ +.TH std::filesystem::path::root_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::root_path \- std::filesystem::path::root_path + +.SH Synopsis + path root_path() const; \fI(since C++17)\fP + + Returns the root path of the path. If the path does not include root path, returns + path(). + + Effectively returns root_name() / root_directory(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The root path of the path. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << "Current root path is: " << fs::current_path().root_path() << '\\n'; + } + +.SH Possible output: + + Current root path is: "C:\\" + +.SH See also + + root_name returns the root-name of the path, if present + \fI(public member function)\fP + root_directory returns the root directory of the path, if present + \fI(public member function)\fP diff --git a/man/std::filesystem::path::stem.3 b/man/std::filesystem::path::stem.3 new file mode 100644 index 000000000..3d3ab76cc --- /dev/null +++ b/man/std::filesystem::path::stem.3 @@ -0,0 +1,67 @@ +.TH std::filesystem::path::stem 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::stem \- std::filesystem::path::stem + +.SH Synopsis + path stem() const; \fI(since C++17)\fP + + Returns the filename identified by the generic-format path stripped of its + extension. + + Returns the substring from the beginning of filename() up to and not including the + last period (.) character, with the following exceptions: + + * If the first character in the filename is a period, that period is ignored (a + filename like ".profile" is not treated as an extension). + * If the filename is one of the special filesystem components dot or dot-dot, or + if it has no periods, the function returns the entire filename(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The stem of the filename identified by the path (i.e. the filename without the final + extension). + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + for (const fs::path p : {"/foo/bar.txt", "/foo/.bar", "foo.bar.baz.tar"}) + std::cout << "path: " << p << ", stem: " << p.stem() << '\\n'; + + std::cout << '\\n'; + + for (fs::path p = "foo.bar.baz.tar"; !p.extension().empty(); p = p.stem()) + std::cout << "path: " << p << ", extension: " << p.extension() << '\\n'; + } + +.SH Output: + + path: "/foo/bar.txt", stem: "bar" + path: "/foo/.bar", stem: ".bar" + path: "foo.bar.baz.tar", stem: "foo.bar.baz" + + path: "foo.bar.baz.tar", extension: ".tar" + path: "foo.bar.baz", extension: ".baz" + path: "foo.bar", extension: ".bar" + +.SH See also + + filename returns the filename path component + \fI(public member function)\fP + extension returns the file extension path component + \fI(public member function)\fP diff --git a/man/std::filesystem::path::string,std::filesystem::path::wstring,.3 b/man/std::filesystem::path::string,std::filesystem::path::wstring,.3 new file mode 100644 index 000000000..92d2183c1 --- /dev/null +++ b/man/std::filesystem::path::string,std::filesystem::path::wstring,.3 @@ -0,0 +1,113 @@ +.TH std::filesystem::path::string,std::filesystem::path::wstring, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::string,std::filesystem::path::wstring, \- std::filesystem::path::string,std::filesystem::path::wstring, + +.SH Synopsis + std::filesystem::path::u32string + + template< class CharT, class Traits = + std::char_traits, + (since + class Alloc = std::allocator > \fB(1)\fP C++17) + std::basic_string + + string( const Alloc& a = Alloc() ) const; + std::string string() const; + std::wstring wstring() const; + std::u16string u16string() const; + std::u32string u32string() const; + \fB(2)\fP (since (since + std::string u8string() const; C++17) C++17) + \fB(3)\fP (until + C++20) + std::u8string u8string() const; (since + C++20) + + Returns the internal pathname in native pathname format, converted to specific + string type. Conversion, if any, is performed as follows: + + * If path::value_type is char, conversion, if any, is system-dependent. This is + the case on typical POSIX systems (such as Linux), where native encoding is + UTF-8 and string() performs no conversion. + * Otherwise, if path::value_type is wchar_t, conversion, if any, is unspecified. + This is the case on Windows, where wchar_t is 16 bit and the native encoding is + UTF-16. + * Otherwise, if path::value_type is char16_t, native encoding is UTF-16 and the + conversion method is unspecified. + * Otherwise, if path::value_type is char32_t, native encoding is UTF-32 and the + conversion method is unspecified. + * Otherwise, if path::value_type is char8_t, native encoding is UTF-8 and the + conversion method is unspecified. + 1) All memory allocations are performed by a. + 3) The result encoding in the case of u8string() is always UTF-8. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The internal pathname in native pathname format, converted to specified string type. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + const char* const localeName = "ja_JP.utf-8"; + std::setlocale(LC_ALL, localeName); + std::locale::global(std::locale(localeName)); + + const std::filesystem::path p(u8"要らない.txt"); + std::ofstream(p) << "File contents"; + + // native string representation can be used with OS APIs + if (std::FILE* const f = std::fopen(p.string().c_str(), "r")) + { + for (int ch; (ch = std::fgetc(f)) != EOF;) + std::putchar(ch); + + std::fclose(f); + } + + // multibyte and wide representation can be used for output + std::cout << "\\nFile name in narrow multibyte encoding: " << p.string() << '\\n'; + + // wstring() will throw in stdlibc++ (as per gcc-12.1.0), see: + // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95048 + // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102839 + // works with more recent gcc-12.2.1 (2023/02/01) and clang-10+ + std::wcout << "File name in wide encoding: " << p.wstring() << '\\n'; + + std::filesystem::remove(p); + } + +.SH Possible output: + + File contents + File name in narrow multibyte encoding: 要らない.txt + File name in wide encoding: 要らない.txt + +.SH See also + + generic_string + generic_wstring returns the path in generic pathname format converted to a string + generic_u8string \fI(public member function)\fP + generic_u16string + generic_u32string + +.SH Category: + * Uses of dcl rev begin with nonempty note diff --git a/man/std::filesystem::path::swap.3 b/man/std::filesystem::path::swap.3 new file mode 100644 index 000000000..40cbe0913 --- /dev/null +++ b/man/std::filesystem::path::swap.3 @@ -0,0 +1,25 @@ +.TH std::filesystem::path::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::swap \- std::filesystem::path::swap + +.SH Synopsis + void swap( path& other ) noexcept; \fB(1)\fP \fI(since C++17)\fP + + Swaps the contents (both native and generic format) of *this and other. + +.SH Parameters + + other - another path to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH See also + + swap(std::filesystem::path) swaps two paths + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::path::~path.3 b/man/std::filesystem::path::~path.3 new file mode 100644 index 000000000..b057f89d4 --- /dev/null +++ b/man/std::filesystem::path::~path.3 @@ -0,0 +1,8 @@ +.TH std::filesystem::path::~path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::path::~path \- std::filesystem::path::~path + +.SH Synopsis + ~path(); \fI(since C++17)\fP + + Destroys the path object. diff --git a/man/std::filesystem::perm_options.3 b/man/std::filesystem::perm_options.3 new file mode 100644 index 000000000..e2d3ceb9a --- /dev/null +++ b/man/std::filesystem::perm_options.3 @@ -0,0 +1,95 @@ +.TH std::filesystem::perm_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::perm_options \- std::filesystem::perm_options + +.SH Synopsis + Defined in header + enum class perm_options { + + replace = /* unspecified */, + add = /* unspecified */, \fI(since C++17)\fP + remove = /* unspecified */, + nofollow = /* unspecified */ + + }; + + This type represents available options that control the behavior of the function + std::filesystem::permissions(). + + perm_options satisfies the requirements of BitmaskType (which means the bitwise + operators operator&, operator|, operator^, operator~, operator&=, operator|=, and + operator^= are defined for this type). + +.SH Member constants + + At most one of add, remove, replace may be present, otherwise the behavior of the + permissions function is undefined. + + Member constant Meaning + replace Permissions will be completely replaced by the argument to + permissions() (default behavior) + add Permissions will be replaced by the bitwise OR of the argument and + the current permissions + remove Permissions will be replaced by the bitwise AND of the negated + argument and current permissions + nofollow Permissions will be changed on the symlink itself, rather than on + the file it resolves to + +.SH Example + + +// Run this code + + #include + #include + #include + + void demo_perms(std::filesystem::perms p) + { + using std::filesystem::perms; + auto show = [=](char op, perms perm) + { + std::cout << (perms::none == (perm & p) ? '-' : op); + }; + show('r', perms::owner_read); + show('w', perms::owner_write); + show('x', perms::owner_exec); + show('r', perms::group_read); + show('w', perms::group_write); + show('x', perms::group_exec); + show('r', perms::others_read); + show('w', perms::others_write); + show('x', perms::others_exec); + std::cout << '\\n'; + } + + int main() + { + std::ofstream("test.txt"); // create file + + std::cout << "Created file with permissions: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::permissions( + "test.txt", + std::filesystem::perms::owner_all | std::filesystem::perms::group_all, + std::filesystem::perm_options::add + ); + + std::cout << "After adding u+rwx and g+rwx: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::remove("test.txt"); + } + +.SH Possible output: + + Created file with permissions: rw-r--r-- + After adding u+rwx and g+wrx: rwxrwxr-- + +.SH See also + + permissions modifies file access permissions + \fI(C++17)\fP \fI(function)\fP + perms identifies file system permissions + \fI(C++17)\fP \fI(enum)\fP diff --git a/man/std::filesystem::permissions.3 b/man/std::filesystem::permissions.3 new file mode 100644 index 000000000..92d132145 --- /dev/null +++ b/man/std::filesystem::permissions.3 @@ -0,0 +1,136 @@ +.TH std::filesystem::permissions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::permissions \- std::filesystem::permissions + +.SH Synopsis + Defined in header + void permissions( const std::filesystem::path& p, + + std::filesystem::perms prms, \fB(1)\fP \fI(since C++17)\fP + + std::filesystem::perm_options opts = + perm_options::replace ); + void permissions( const std::filesystem::path& p, + + std::filesystem::perms prms, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + void permissions( const std::filesystem::path& p, + + std::filesystem::perms prms, \fB(3)\fP \fI(since C++17)\fP + std::filesystem::perm_options opts, + + std::error_code& ec ); + + Changes access permissions of the file to which p resolves, as if by POSIX fchmodat. + Symlinks are followed unless perm_options::nofollow is set in opts. + + The second signature behaves as if called with opts set to perm_options::replace. + + The effects depend on prms and opts as follows: + + * If opts is perm_options::replace, file permissions are set to exactly prms & + std::filesystem::perms::mask (meaning, every valid bit of prms is applied). + * If opts is perm_options::add, the file permissions are set to exactly + status(p).permissions() | (prms & perms::mask) (meaning, any valid bit that is + set in prms, but not in the file's current permissions is added to the file's + permissions). + * If opts is perm_options::remove, the file permissions are set to exactly + status(p).permissions() & ~(prms & perms::mask) (meaning, any valid bit that is + clear in prms, but set in the file's current permissions is cleared in the + file's permissions). + + opts is required to have only one of replace, add, or remove to be set. + + The non-throwing overload has no special action on error. + +.SH Parameters + + p - path to examine + prms - permissions to set, add, or remove + opts - options controlling the action taken by this function + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2,3) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Permissions may not necessarily be implemented as bits, but they are treated that + way conceptually. + + Some permission bits may be ignored on some systems, and changing some bits may + automatically change others (e.g. on platforms without owner/group/all distinction, + setting any of the three write bits set all three). + +.SH Example + + +// Run this code + + #include + #include + #include + + void demo_perms(std::filesystem::perms p) + { + using std::filesystem::perms; + auto show = [=](char op, perms perm) + { + std::cout << (perms::none == (perm & p) ? '-' : op); + }; + show('r', perms::owner_read); + show('w', perms::owner_write); + show('x', perms::owner_exec); + show('r', perms::group_read); + show('w', perms::group_write); + show('x', perms::group_exec); + show('r', perms::others_read); + show('w', perms::others_write); + show('x', perms::others_exec); + std::cout << '\\n'; + } + + int main() + { + std::ofstream("test.txt"); // create file + + std::cout << "Created file with permissions: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::permissions( + "test.txt", + std::filesystem::perms::owner_all | std::filesystem::perms::group_all, + std::filesystem::perm_options::add + ); + + std::cout << "After adding u+rwx and g+rwx: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::remove("test.txt"); + } + +.SH Possible output: + + Created file with permissions: rw-r--r-- + After adding u+rwx and g+wrx: rwxrwxr-- + +.SH See also + + perms identifies file system permissions + \fI(C++17)\fP \fI(enum)\fP + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::perms.3 b/man/std::filesystem::perms.3 new file mode 100644 index 000000000..8a41c4c27 --- /dev/null +++ b/man/std::filesystem::perms.3 @@ -0,0 +1,146 @@ +.TH std::filesystem::perms 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::perms \- std::filesystem::perms + +.SH Synopsis + Defined in header + enum class perms; \fI(since C++17)\fP + + This type represents file access permissions. + + perms satisfies the requirements of BitmaskType (which means the bitwise operators + operator&, operator|, operator^, operator~, operator&=, operator|=, and operator^= + are defined for this type). none represents the empty bitmask; every other + enumerator represents a distinct bitmask element. + + Access permissions model POSIX permission bits, and any individual file permissions + (as reported by filesystem::status) are a combination of some of the following bits: + +.SH Member constants + + Member constant Value (octal) POSIX equivalent Meaning + none 0 No permission bits are set + owner_read 0400 S_IRUSR File owner has read permission + owner_write 0200 S_IWUSR File owner has write permission + owner_exec 0100 S_IXUSR File owner has execute/search + permission + File owner has read, write, and + execute/search permissions + owner_all 0700 S_IRWXU + Equivalent to owner_read | + owner_write | owner_exec + group_read 040 S_IRGRP The file's user group has read + permission + group_write 020 S_IWGRP The file's user group has write + permission + group_exec 010 S_IXGRP The file's user group has + execute/search permission + The file's user group has read, + write, and execute/search permissions + group_all 070 S_IRWXG + Equivalent to group_read | + group_write | group_exec + others_read 04 S_IROTH Other users have read permission + others_write 02 S_IWOTH Other users have write permission + others_exec 01 S_IXOTH Other users have execute/search + permission + Other users have read, write, and + execute/search permissions + others_all 07 S_IRWXO + Equivalent to others_read | + others_write | others_exec + All users have read, write, and + execute/search permissions + all 0777 + Equivalent to owner_all | group_all | + others_all + set_uid 04000 S_ISUID Set user ID to file owner user ID on + execution + set_gid 02000 S_ISGID Set group ID to file's user group ID + on execution + Implementation-defined meaning, but + POSIX XSI specifies that when set on + sticky_bit 01000 S_ISVTX a directory, only file owners may + delete files even if the directory is + writeable to others (used with /tmp) + All valid permission bits. + mask 07777 + Equivalent to all | set_uid | set_gid + | sticky_bit + + Additionally, the following constants of this type are defined, which do not + represent permissions: + + Member constant Value (hex) Meaning + unknown 0xFFFF Unknown permissions (e.g. when filesystem::file_status + is created without permissions) + +.SH Notes + + Permissions may not necessarily be implemented as bits, but they are treated that + way conceptually. + + Some permission bits may be ignored on some systems, and changing some bits may + automatically change others (e.g. on platforms without owner/group/all distinction, + setting any of the three write bits set all three). + +.SH Example + + +// Run this code + + #include + #include + #include + + void demo_perms(std::filesystem::perms p) + { + using std::filesystem::perms; + auto show = [=](char op, perms perm) + { + std::cout << (perms::none == (perm & p) ? '-' : op); + }; + show('r', perms::owner_read); + show('w', perms::owner_write); + show('x', perms::owner_exec); + show('r', perms::group_read); + show('w', perms::group_write); + show('x', perms::group_exec); + show('r', perms::others_read); + show('w', perms::others_write); + show('x', perms::others_exec); + std::cout << '\\n'; + } + + int main() + { + std::ofstream("test.txt"); // create file + + std::cout << "Created file with permissions: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::permissions( + "test.txt", + std::filesystem::perms::owner_all | std::filesystem::perms::group_all, + std::filesystem::perm_options::add + ); + + std::cout << "After adding u+rwx and g+rwx: "; + demo_perms(std::filesystem::status("test.txt").permissions()); + + std::filesystem::remove("test.txt"); + } + +.SH Possible output: + + Created file with permissions: rw-r--r-- + After adding u+rwx and g+wrx: rwxrwxr-- + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + permissions modifies file access permissions + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::read_symlink.3 b/man/std::filesystem::read_symlink.3 new file mode 100644 index 000000000..d7bc95cfb --- /dev/null +++ b/man/std::filesystem::read_symlink.3 @@ -0,0 +1,81 @@ +.TH std::filesystem::read_symlink 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::read_symlink \- std::filesystem::read_symlink + +.SH Synopsis + Defined in header + std::filesystem::path read_symlink( const std::filesystem::path& p \fB(1)\fP \fI(since C++17)\fP + ); + std::filesystem::path read_symlink( const std::filesystem::path& + p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ); + + If the path p refers to a symbolic link, returns a new path object which refers to + the target of that symbolic link. + + It is an error if p does not refer to a symbolic link. + + The non-throwing overload returns an empty path on errors. + +.SH Parameters + + p - path to a symlink + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The target of the symlink (which may not necessarily exist). + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + + namespace fs = std::filesystem; + + int main() + { + for (fs::path p : {"/usr/bin/gcc", "/bin/cat", "/bin/mouse"}) + { + std::cout << p; + fs::exists(p) ? + fs::is_symlink(p) ? + std::cout << " -> " << fs::read_symlink(p) << '\\n' : + std::cout << " exists but it is not a symlink\\n" : + std::cout << " does not exist\\n"; + } + } + +.SH Possible output: + + "/usr/bin/gcc" -> "gcc-5" + "/bin/cat" exists but it is not a symlink + "/bin/mouse" does not exist + +.SH See also + + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + create_symlink + create_directory_symlink creates a symbolic link + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + copy_symlink copies a symbolic link + \fI(C++17)\fP \fI(function)\fP + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::recursive_directory_iterator.3 b/man/std::filesystem::recursive_directory_iterator.3 new file mode 100644 index 000000000..324d99e8d --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator.3 @@ -0,0 +1,179 @@ +.TH std::filesystem::recursive_directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator \- std::filesystem::recursive_directory_iterator + +.SH Synopsis + Defined in header + class recursive_directory_iterator; \fI(since C++17)\fP + + recursive_directory_iterator is a LegacyInputIterator that iterates over the + directory_entry elements of a directory, and, recursively, over the entries of all + subdirectories. The iteration order is unspecified, except that each directory entry + is visited only once. + + By default, symlinks are not followed, but this can be enabled by specifying the + directory option follow_directory_symlink at construction time. + + The special pathnames dot and dot-dot are skipped. + + If the recursive_directory_iterator reports an error or is advanced past the last + directory entry of the top-level directory, it becomes equal to the + default-constructed iterator, also known as the end iterator. Two end iterators are + always equal, dereferencing or incrementing the end iterator is undefined behavior. + + If a file or a directory is deleted or added to the directory tree after the + recursive directory iterator has been created, it is unspecified whether the change + would be observed through the iterator. + + If the directory structure contains cycles, the end iterator may be unreachable. + +.SH Member types + + Member type Definition + value_type std::filesystem::directory_entry + difference_type std::ptrdiff_t + pointer const std::filesystem::directory_entry* + reference const std::filesystem::directory_entry& + iterator_category std::input_iterator_tag + +.SH Member functions + + constructor constructs a recursive directory iterator + \fI(public member function)\fP + destructor default destructor + \fI(public member function)\fP +.SH Observers + operator* accesses the pointed-to entry + operator-> \fI(public member function)\fP + returns the currently active options that affect the + options iteration + \fI(public member function)\fP + depth returns the current recursion depth + \fI(public member function)\fP + checks whether the recursion is disabled for the current + recursion_pending directory + \fI(public member function)\fP +.SH Modifiers + operator= assigns contents + \fI(public member function)\fP + increment advances to the next entry + operator++ \fI(public member function)\fP + pop moves the iterator one level up in the directory hierarchy + \fI(public member function)\fP + disable_recursion_pending disables recursion until the next increment + \fI(public member function)\fP + +.SH Non-member functions + + begin(std::filesystem::recursive_directory_iterator) range-based for loop support + end(std::filesystem::recursive_directory_iterator) \fI(function)\fP + + Additionally, + operator== and operator!= are + \fI(until C++20)\fP + operator== is + \fI(since C++20)\fP provided as required by LegacyInputIterator. + + It is unspecified + whether operator!= is provided because it can be synthesized from operator==, and + \fI(since C++20)\fP whether an equality operator is a member or non-member. + + Helper templates + + namespace std::ranges { + + template<> + inline constexpr bool (since + enable_borrowed_range = C++20) + true; + + } + namespace std::ranges { + + template<> (since + inline constexpr bool C++20) + enable_view = true; + + } + + These specializations for recursive_directory_iterator make it a borrowed_range and + a view. + +.SH Notes + + A recursive_directory_iterator typically holds a reference-counted pointer (to + satisfy shallow-copy semantics of LegacyInputIterator) to an implementation object, + which holds: + + * a container (such as std::vector) of non-recursive directory_iterators that + forms the recursion stack, + * the recursion depth counter (accessible with depth()), + * the directory options used at construction (accessible with options()), + * the pending recursion flag (accessible with recursion_pending(), may be combined + with the directory options to save space). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::filesystem::current_path(std::filesystem::temp_directory_path()); + std::filesystem::create_directories("sandbox/a/b"); + std::ofstream("sandbox/file1.txt"); + std::filesystem::create_symlink("a", "sandbox/syma"); + + // Iterate over the std::filesystem::directory_entry elements explicitly + auto entry_length{3UZ}; + for (const fs::directory_entry& dir_entry : + fs::recursive_directory_iterator("sandbox")) + { + std::cout << dir_entry << '\\n'; + if (auto l{dir_entry.path().string().length()}; entry_length < l) + entry_length = l; + } + std::cout << std::string(entry_length + 2, '-') << '\\n'; + + // Iterate over the std::filesystem::directory_entry elements using `auto` + for (auto const& dir_entry : fs::recursive_directory_iterator("sandbox")) + std::cout << dir_entry << '\\n'; + + std::filesystem::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/syma" + "sandbox/file1.txt" + "sandbox/a" + "sandbox/a/b" + ------------------- + "sandbox/syma" + "sandbox/file1.txt" + "sandbox/a" + "sandbox/a/b" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3480 C++20 recursive_directory_iterator was neither a it is both + borrowed_range nor a view + +.SH See also + + directory_iterator an iterator to the contents of the directory + \fI(C++17)\fP \fI(class)\fP + directory_entry a directory entry + \fI(C++17)\fP \fI(class)\fP + directory_options options for iterating directory contents + \fI(C++17)\fP \fI(enum)\fP diff --git a/man/std::filesystem::recursive_directory_iterator::depth.3 b/man/std::filesystem::recursive_directory_iterator::depth.3 new file mode 100644 index 000000000..5d8a52caf --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::depth.3 @@ -0,0 +1,68 @@ +.TH std::filesystem::recursive_directory_iterator::depth 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::depth \- std::filesystem::recursive_directory_iterator::depth + +.SH Synopsis + int depth() const; \fI(since C++17)\fP + + Returns the number of directories from the starting directory to the currently + iterated directory, i.e. the current depth of the directory hierarchy. + + The starting directory has depth of 0, its subdirectories have depth 1, etc. + + The behavior is undefined if *this is the end iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Current depth of the directory hierarchy. + +.SH Exceptions + + Throws nothing. + +.SH Example + + This example uses iteration depth to calculate the indentation of a directory tree + printout. + + +// Run this code + + #include + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::current_path(fs::temp_directory_path()); + fs::create_directories("sandbox/a/b/c"); + fs::create_directories("sandbox/a/b/d/e"); + std::ofstream("sandbox/a/b/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + for (auto i = fs::recursive_directory_iterator("sandbox"); + i != fs::recursive_directory_iterator(); + ++i) + { + std::cout << std::string(i.depth() << 1, ' ') << *i; + if (fs::is_symlink(i->symlink_status())) + std::cout << " -> " << fs::read_symlink(*i); + std::cout << '\\n'; + } + fs::remove_all("sandbox"); + } + +.SH Output: + + "sandbox/syma" -> "a" + "sandbox/a" + "sandbox/a/b" + "sandbox/a/b/d" + "sandbox/a/b/d/e" + "sandbox/a/b/file1.txt" + "sandbox/a/b/c" diff --git a/man/std::filesystem::recursive_directory_iterator::disable_recursion_pending.3 b/man/std::filesystem::recursive_directory_iterator::disable_recursion_pending.3 new file mode 100644 index 000000000..fdf29609b --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::disable_recursion_pending.3 @@ -0,0 +1,89 @@ +.TH std::filesystem::recursive_directory_iterator::disable_recursion_pending 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::disable_recursion_pending \- std::filesystem::recursive_directory_iterator::disable_recursion_pending + +.SH Synopsis + void disable_recursion_pending(); \fI(since C++17)\fP + + Disables recursion to the currently referred subdirectory, if any. + + The call modifies the pending recursion flag on the iterator in such a way that the + next time increment is called, the iterator will advance within the current + directory even if it is currently referring to a subdirectory that hasn't been + visited. + + The status of the pending recursion flag can be queried with recursion_pending(), + which is false after this call. It is reset back to true after increment, and its + initial value is also true. + + The behavior is undefined if *this is the end iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::current_path(fs::temp_directory_path()); + fs::create_directories("sandbox/a/b/c"); + fs::create_directories("sandbox/a/b/d/e"); + std::ofstream("sandbox/a/b/file1.txt"); + fs::create_symlink("a", "sandbox/syma"); + std::system("tree sandbox"); + for (auto i = fs::recursive_directory_iterator("sandbox"); + i != fs::recursive_directory_iterator(); + ++i) + { + std::cout << std::string(i.depth() * 2, ' ') << *i; + if (fs::is_symlink(i->symlink_status())) + std::cout << " -> " << fs::read_symlink(*i); + std::cout << '\\n'; + + // do not descend into "b" + if (i->path().filename() == "b") + i.disable_recursion_pending(); + } + fs::remove_all("sandbox"); + } + +.SH Possible output: + + sandbox + ├── a + │ └── b + │ ├── c + │ ├── d + │ │ └── e + │ └── file1.txt + └── syma -> a + + "sandbox/a" + "sandbox/a/b" + "sandbox/syma" -> "a" + +.SH See also + + recursion_pending checks whether the recursion is disabled for the current directory + \fI(public member function)\fP + increment advances to the next entry + operator++ \fI(public member function)\fP diff --git a/man/std::filesystem::recursive_directory_iterator::operator*,.3 b/man/std::filesystem::recursive_directory_iterator::operator*,.3 new file mode 100644 index 000000000..53c736aa4 --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::operator*,.3 @@ -0,0 +1,30 @@ +.TH std::filesystem::recursive_directory_iterator::operator*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::operator*, \- std::filesystem::recursive_directory_iterator::operator*, + +.SH Synopsis + + const std::filesystem::directory_entry& operator*() const; \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::directory_entry* operator->() const; \fB(2)\fP \fI(since C++17)\fP + + Accesses the pointed-to directory_entry. + + The result of operator* or operator-> on the end iterator is undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Value of the directory_entry referred to by this iterator. + 2) Pointer to the directory_entry referred to by this iterator. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH See also + + operator* accesses the pointed-to entry + operator-> \fI(public member function of std::filesystem::directory_iterator)\fP diff --git a/man/std::filesystem::recursive_directory_iterator::operator++,.3 b/man/std::filesystem::recursive_directory_iterator::operator++,.3 new file mode 100644 index 000000000..0804f64da --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::operator++,.3 @@ -0,0 +1,63 @@ +.TH std::filesystem::recursive_directory_iterator::operator++, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::operator++, \- std::filesystem::recursive_directory_iterator::operator++, + +.SH Synopsis + + recursive_directory_iterator& operator++(); \fB(1)\fP \fI(since C++17)\fP + recursive_directory_iterator& increment( std::error_code& ec ); \fB(2)\fP \fI(since C++17)\fP + + Advances the iterator to the next entry. Invalidates all copies of the previous + value of *this. + + If there are no more entries left in the currently iterated directory, the iteration + is resumed over the parent directory. The process is repeated if the parent + directory has no sibling entries that can to be iterated on. If the parent of the + directory hierarchy that has been recursively iterated on is reached (there are no + candidate entries at depth() == 0), *this is set to an end iterator. + + Otherwise, if *this refers to a directory, it is iterated into if the following + conditions are met: + + * disable_recursion_pending() has not been called before this increment, i.e. + recursion_pending() == true. + * The directory is not a symlink or following symlinks is enabled, i.e., at least + one of the following is true: + * !is_symlink((*this)->symlink_status()). + * (options() & directory_options::follow_directory_symlink) != + directory_options::none) + +.SH Parameters + + ec - error code to store the error status to + +.SH Return value + + *this + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3013 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::recursive_directory_iterator::operator=.3 b/man/std::filesystem::recursive_directory_iterator::operator=.3 new file mode 100644 index 000000000..94ce5a22d --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::operator=.3 @@ -0,0 +1,28 @@ +.TH std::filesystem::recursive_directory_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::operator= \- std::filesystem::recursive_directory_iterator::operator= + +.SH Synopsis + recursive_directory_iterator& operator=( const \fI(since C++17)\fP + recursive_directory_iterator& other ) = default; + recursive_directory_iterator& operator=( \fI(since C++17)\fP + recursive_directory_iterator&& other ) = default; + + Assigns a recursive directory iterator. + +.SH Parameters + + other - another directory iterator to assign + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + + This section is incomplete + +.SH Category: + * Todo without reason diff --git a/man/std::filesystem::recursive_directory_iterator::options.3 b/man/std::filesystem::recursive_directory_iterator::options.3 new file mode 100644 index 000000000..bc263d22c --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::options.3 @@ -0,0 +1,24 @@ +.TH std::filesystem::recursive_directory_iterator::options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::options \- std::filesystem::recursive_directory_iterator::options + +.SH Synopsis + std::filesystem::directory_options options() const; \fI(since C++17)\fP + + Returns the options that affect the directory iteration. The options can only be + supplied when constructing the directory iterator. + + If the options argument was not supplied, returns + std::filesystem::directory_options::none. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The effective options that affect the directory iteration. + +.SH Exceptions + + Throws nothing. diff --git a/man/std::filesystem::recursive_directory_iterator::pop.3 b/man/std::filesystem::recursive_directory_iterator::pop.3 new file mode 100644 index 000000000..b0c544d95 --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::pop.3 @@ -0,0 +1,39 @@ +.TH std::filesystem::recursive_directory_iterator::pop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::pop \- std::filesystem::recursive_directory_iterator::pop + +.SH Synopsis + void pop(); \fB(1)\fP \fI(since C++17)\fP + void pop( std::error_code& ec ); \fB(2)\fP \fI(since C++17)\fP + + Moves the iterator one level up in the directory hierarchy. Invalidates all copies + of the previous value of *this. + + If the parent directory is outside directory hierarchy that is iterated on (i.e. + depth() == 0), sets *this to an end directory iterator. + +.SH Parameters + + ec - error code to store the error status to + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::recursive_directory_iterator::recursion_pending.3 b/man/std::filesystem::recursive_directory_iterator::recursion_pending.3 new file mode 100644 index 000000000..1bc7b9cc1 --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::recursion_pending.3 @@ -0,0 +1,33 @@ +.TH std::filesystem::recursive_directory_iterator::recursion_pending 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::recursion_pending \- std::filesystem::recursive_directory_iterator::recursion_pending + +.SH Synopsis + bool recursion_pending() const; \fI(since C++17)\fP + + Returns true if the next increment will cause the directory currently referred to by + *this to be iterated into. + + This function returns true immediately after construction or an increment. Recursion + can be disabled via disable_recursion_pending(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the next increment will iterate into the currently referred directory, false + otherwise. + +.SH Exceptions + + Throws nothing. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 b/man/std::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 new file mode 100644 index 000000000..21a288464 --- /dev/null +++ b/man/std::filesystem::recursive_directory_iterator::recursive_directory_iterator.3 @@ -0,0 +1,80 @@ +.TH std::filesystem::recursive_directory_iterator::recursive_directory_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::recursive_directory_iterator::recursive_directory_iterator \- std::filesystem::recursive_directory_iterator::recursive_directory_iterator + +.SH Synopsis + recursive_directory_iterator() noexcept; \fB(1)\fP \fI(since C++17)\fP + recursive_directory_iterator( const recursive_directory_iterator& \fB(2)\fP \fI(since C++17)\fP + other ); + recursive_directory_iterator( recursive_directory_iterator&& other \fB(3)\fP \fI(since C++17)\fP + ) noexcept; + explicit recursive_directory_iterator( const \fB(4)\fP \fI(since C++17)\fP + std::filesystem::path& p ); + recursive_directory_iterator( + + const std::filesystem::path& p, \fB(5)\fP \fI(since C++17)\fP + + std::filesystem::directory_options options ); + recursive_directory_iterator( + + const std::filesystem::path& p, \fB(6)\fP \fI(since C++17)\fP + std::filesystem::directory_options options, + + std::error_code& ec ); + recursive_directory_iterator( const std::filesystem::path& p, \fB(7)\fP \fI(since C++17)\fP + std::error_code& ec ); + + Constructs new recursive directory iterator. + + 1) Default constructor. Constructs an end iterator. + 2) Copy constructor. + 3) Move constructor. + 4-7) Constructs an iterator that refers to the first entry in the directory that p + resolves to. + + This section is incomplete + Reason: errors + +.SH Parameters + + p - path to the filesystem object to which the directory iterator will refer + ec - out-parameter for error reporting in the non-throwing overloads + options - the set of BitmaskType options that control the behavior of the directory + iterator + other - another directory iterator to use as source to initialize the directory + iterator with + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 4,5) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 6,7) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + Recursive directory iterators do not follow directory symlinks by default. To enable + this behavior, specify directory_options::follow_directory_symlink among the options + option set. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3013 C++17 error_code overload marked noexcept but can noexcept removed + allocate memory + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::filesystem::relative,std::filesystem::proximate.3 b/man/std::filesystem::relative,std::filesystem::proximate.3 new file mode 100644 index 000000000..bbafe4144 --- /dev/null +++ b/man/std::filesystem::relative,std::filesystem::proximate.3 @@ -0,0 +1,125 @@ +.TH std::filesystem::relative,std::filesystem::proximate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::relative,std::filesystem::proximate \- std::filesystem::relative,std::filesystem::proximate + +.SH Synopsis + Defined in header + path relative( const std::filesystem::path& p, \fB(1)\fP \fI(since C++17)\fP + std::error_code& ec ); + path relative( const std::filesystem::path& p, + const std::filesystem::path& base = \fB(2)\fP \fI(since C++17)\fP + std::filesystem::current_path() ); + path relative( const std::filesystem::path& p, + + const std::filesystem::path& base, \fB(3)\fP \fI(since C++17)\fP + + std::error_code& ec ); + path proximate( const std::filesystem::path& p, \fB(4)\fP \fI(since C++17)\fP + std::error_code& ec ); + path proximate( const std::filesystem::path& p, + const std::filesystem::path& base = \fB(5)\fP \fI(since C++17)\fP + std::filesystem::current_path() ); + path proximate( const std::filesystem::path& p, + + const std::filesystem::path& base, \fB(6)\fP \fI(since C++17)\fP + + std::error_code& ec ); + + 1) Returns relative(p, current_path(), ec). + 2,3) Returns p made relative to base. Resolves symlinks and normalizes both p and + base before other processing. Effectively returns + std::filesystem::weakly_canonical(p).lexically_relative(std::filesystem::weakly_canonical(base)) + or std::filesystem::weakly_canonical(p, + ec).lexically_relative(std::filesystem::weakly_canonical(base, ec)), except the + error code form returns path() at the first error occurrence, if any. + 4) Returns proximate(p, current_path(), ec). + 5,6) Effectively returns + std::filesystem::weakly_canonical(p).lexically_proximate(std::filesystem::weakly_canonical(base)) + or std::filesystem::weakly_canonical(p, + ec).lexically_proximate(std::filesystem::weakly_canonical(base, ec)), except the + error code form returns path() at the first error occurrence, if any. + +.SH Parameters + + p - an existing path + base - base path, against which p will be made relative/proximate + ec - error code to store error status to + +.SH Return value + + 1) p made relative against current_path(). + 2,3) p made relative against base. + 4) p made proximate against current_path(). + 5,6) p made proximate against base. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 2,5) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument, base as the second path argument, and + the OS error code as the error code argument. + 1,3,4,6) Sets a std::error_code& parameter to the OS API error code if an OS API + call fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + + void show(std::filesystem::path x, std::filesystem::path y) + { + std::cout << "x:\\t\\t " << x << "\\ny:\\t\\t " << y << '\\n' + << "relative(x, y): " + << std::filesystem::relative(x, y) << '\\n' + << "proximate(x, y): " + << std::filesystem::proximate(x, y) << "\\n\\n"; + } + + int main() + { + show("/a/b/c", "/a/b"); + show("/a/c", "/a/b"); + show("c", "/a/b"); + show("/a/b", "c"); + } + +.SH Possible output: + + x: "/a/b/c" + y: "/a/b" + relative(x, y): "c" + proximate(x, y): "c" + + x: "/a/c" + y: "/a/b" + relative(x, y): "../c" + proximate(x, y): "../c" + + x: "c" + y: "/a/b" + relative(x, y): "" + proximate(x, y): "c" + + x: "/a/b" + y: "c" + relative(x, y): "" + proximate(x, y): "/a/b" + +.SH See also + + path represents a path + \fI(C++17)\fP \fI(class)\fP + absolute composes an absolute path + \fI(C++17)\fP \fI(function)\fP + canonical composes a canonical path + weakly_canonical \fI(function)\fP + \fI(C++17)\fP + lexically_normal converts path to normal form + lexically_relative converts path to relative form + lexically_proximate converts path to proximate form + \fI(public member function of std::filesystem::path)\fP diff --git a/man/std::filesystem::remove,std::filesystem::remove_all.3 b/man/std::filesystem::remove,std::filesystem::remove_all.3 new file mode 100644 index 000000000..c98133fd4 --- /dev/null +++ b/man/std::filesystem::remove,std::filesystem::remove_all.3 @@ -0,0 +1,83 @@ +.TH std::filesystem::remove,std::filesystem::remove_all 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::remove,std::filesystem::remove_all \- std::filesystem::remove,std::filesystem::remove_all + +.SH Synopsis + Defined in header + bool remove( const std::filesystem::path& p ); \fB(1)\fP \fI(since C++17)\fP + bool remove( const std::filesystem::path& p, std::error_code& ec ) \fB(2)\fP \fI(since C++17)\fP + noexcept; + std::uintmax_t remove_all( const std::filesystem::path& p ); \fB(3)\fP \fI(since C++17)\fP + std::uintmax_t remove_all( const std::filesystem::path& p, \fB(4)\fP \fI(since C++17)\fP + std::error_code& ec ); + + 1,2) The file or empty directory identified by the path p is deleted as if by the + POSIX remove. Symlinks are not followed (symlink is removed, not its target). + 3,4) Deletes the contents of p (if it is a directory) and the contents of all its + subdirectories, recursively, then deletes p itself as if by repeatedly applying the + POSIX remove. Symlinks are not followed (symlink is removed, not its target). + +.SH Parameters + + p - path to delete + ec - out-parameter for error reporting in the non-throwing overload. + +.SH Return value + + 1,2) true if the file was deleted, false if it did not exist. The overload that + takes error_code& argument returns false on errors. + 3,4) Returns the number of files and directories that were deleted (which may be + zero if p did not exist to begin with). The overload that takes error_code& argument + returns static_cast(-1) on error. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + On POSIX systems, this function typically calls unlink and rmdir as needed, on + Windows RemoveDirectoryW and DeleteFileW. + +.SH Example + + +// Run this code + + #include + #include + #include + namespace fs = std::filesystem; + + int main() + { + fs::path tmp{std::filesystem::temp_directory_path()}; + std::filesystem::create_directories(tmp / "abcdef/example"); + std::uintmax_t n{fs::remove_all(tmp / "abcdef")}; + std::cout << "Deleted " << n << " files or directories\\n"; + } + +.SH Possible output: + + Deleted 2 files or directories + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3014 C++17 error_code overload of remove_all marked noexcept removed + noexcept but can allocate memory + +.SH See also + + remove erases a file + \fI(function)\fP diff --git a/man/std::filesystem::rename.3 b/man/std::filesystem::rename.3 new file mode 100644 index 000000000..7833167b2 --- /dev/null +++ b/man/std::filesystem::rename.3 @@ -0,0 +1,102 @@ +.TH std::filesystem::rename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::rename \- std::filesystem::rename + +.SH Synopsis + Defined in header + void rename( const std::filesystem::path& old_p, \fB(1)\fP \fI(since C++17)\fP + const std::filesystem::path& new_p ); + void rename( const std::filesystem::path& old_p, + + const std::filesystem::path& new_p, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + + Moves or renames the filesystem object identified by old_p to new_p as if by the + POSIX rename: + + * If old_p is a non-directory file, then new_p must be one of: + + * the same file as old_p or a hardlink to it: nothing is done in this case. + * existing non-directory file: new_p is first deleted, then, without allowing + other processes to observe new_p as deleted, the pathname new_p is linked to the + file and old_p is unlinked from the file. Write permissions are required to both + the directory that contains old_p and the directory that contains new_p. + * non-existing file in an existing directory: The pathname new_p is linked to the + file and old_p is unlinked from the file. Write permissions are required to both + the directory that contains old_p and the directory that contains new_p. + * If old_p is a directory, then new_p must be one of: + + * the same directory as old_p or a hardlink to it: nothing is done in this case. + * existing directory: new_p is deleted if empty on POSIX systems, but this may be + an error on other systems. If not an error, then new_p is first deleted, then, + without allowing other processes to observe new_p as deleted, the pathname new_p + is linked to the directory and old_p is unlinked from the directory. Write + permissions are required to both the directory that contains old_p and the + directory that contains new_p. + * non-existing directory, not ending with a directory separator, and whose parent + directory exists: The pathname new_p is linked to the directory and old_p is + unlinked from the directory. Write permissions are required to both the + directory that contains old_p and the directory that contains new_p. + * Symlinks are not followed: if old_p is a symlink, it is itself renamed, not its + target. If new_p is an existing symlink, it is itself erased, not its target. + + Rename fails if + + * new_p ends with dot or with dot-dot. + * new_p names a non-existing directory ending with a directory separator. + * old_p is a directory which is an ancestor of new_p. + +.SH Parameters + + old_p - path to move or rename + new_p - target path for the move/rename operation + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with old_p as the first path argument, new_p as the second path argument, and the OS + error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::filesystem::path p = std::filesystem::current_path() / "sandbox"; + std::filesystem::create_directories(p / "from"); + std::ofstream{ p / "from/file1.txt" }.put('a'); + std::filesystem::create_directory(p / "to"); + + // fs::rename(p / "from/file1.txt", p / "to/"); // error: "to" is a directory + fs::rename(p / "from/file1.txt", p / "to/file2.txt"); // OK + // fs::rename(p / "from", p / "to"); // error: "to" is not empty + fs::rename(p / "from", p / "to/subdir"); // OK + + std::filesystem::remove_all(p); + } + +.SH See also + + rename renames a file + \fI(function)\fP + remove removes a file or empty directory + remove_all removes a file or directory and all its contents, recursively + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP diff --git a/man/std::filesystem::resize_file.3 b/man/std::filesystem::resize_file.3 new file mode 100644 index 000000000..0dca112d7 --- /dev/null +++ b/man/std::filesystem::resize_file.3 @@ -0,0 +1,83 @@ +.TH std::filesystem::resize_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::resize_file \- std::filesystem::resize_file + +.SH Synopsis + Defined in header + void resize_file( const std::filesystem::path& p, \fB(1)\fP \fI(since C++17)\fP + std::uintmax_t new_size ); + void resize_file( const std::filesystem::path& p, + + std::uintmax_t new_size, \fB(2)\fP \fI(since C++17)\fP + + std::error_code& ec ) noexcept; + + Changes the size of the regular file named by p as if by POSIX truncate: if the file + size was previously larger than new_size, the remainder of the file is discarded. If + the file was previously smaller than new_size, the file size is increased and the + new area appears as if zero-filled. + +.SH Parameters + + p - path to resize + new_size - size that the file will now have + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + On systems that support sparse files, increasing the file size does not increase the + space it occupies on the file system: space allocation takes place only when + non-zero bytes are written to the file. + +.SH Example + + Demonstrates the effect creating a sparse file has on the free space. + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto p = std::filesystem::temp_directory_path() / "example.bin"; + std::ofstream{p}.put('a'); + std::cout.imbue(std::locale{"en_US.UTF8"}); + std::cout << "File size: " << std::filesystem::file_size(p) << '\\n' + << "Free space: " << std::filesystem::space(p).free << '\\n'; + std::filesystem::resize_file(p, 64*1024); // resize to 64 KB + std::cout << "File size: " << std::filesystem::file_size(p) << '\\n' + << "Free space: " << std::filesystem::space(p).free << '\\n'; + std::filesystem::remove(p); + } + +.SH Possible output: + + File size: 1 + Free space: 42,954,108,928 + File size: 65,536 + Free space: 42,954,108,928 + +.SH See also + + file_size returns the size of a file + \fI(C++17)\fP \fI(function)\fP + space determines available free space on the file system + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::space.3 b/man/std::filesystem::space.3 new file mode 100644 index 000000000..fd91fc23c --- /dev/null +++ b/man/std::filesystem::space.3 @@ -0,0 +1,114 @@ +.TH std::filesystem::space 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::space \- std::filesystem::space + +.SH Synopsis + Defined in header + std::filesystem::space_info space( const std::filesystem::path& p \fB(1)\fP \fI(since C++17)\fP + ); + std::filesystem::space_info space( const std::filesystem::path& p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ) noexcept; + + Determines the information about the filesystem on which the pathname p is located, + as if by POSIX statvfs. + + Populates and returns an object of type filesystem::space_info, set from the members + of the POSIX struct statvfs as follows: + + * space_info.capacity is set as if by f_blocks * f_frsize. + * space_info.free is set to f_bfree * f_frsize. + * space_info.available is set to f_bavail * f_frsize. + * Any member that could not be determined is set to + static_cast(-1). + + The non-throwing overload sets all members to static_cast(-1) on + error. + +.SH Parameters + + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The filesystem information (a filesystem::space_info object). + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with p as the first path argument and the OS error code as the error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + space_info.available may be less than space_info.free. + +.SH Example + + +// Run this code + + #include + #include + #include + + std::uintmax_t disk_usage_percent(const std::filesystem::space_info& si, + bool is_privileged = false) noexcept + { + if (constexpr std::uintmax_t X(-1); + si.capacity == 0 || si.free == 0 || si.available == 0 || + si.capacity == X || si.free == X || si.available == X + ) + return 100; + + std::uintmax_t unused_space = si.free, capacity = si.capacity; + if (!is_privileged) + { + const std::uintmax_t privileged_only_space = si.free - si.available; + unused_space -= privileged_only_space; + capacity -= privileged_only_space; + } + const std::uintmax_t used_space{capacity - unused_space}; + return 100 * used_space / capacity; + } + + void print_disk_space_info(auto const& dirs, int width = 14) + { + (std::cout << std::left).imbue(std::locale("en_US.UTF-8")); + + for (const auto s : {"Capacity", "Free", "Available", "Use%", "Dir"}) + std::cout << "│ " << std::setw(width) << s << ' '; + + for (std::cout << '\\n'; auto const& dir : dirs) + { + std::error_code ec; + const std::filesystem::space_info si = std::filesystem::space(dir, ec); + for (auto x : {si.capacity, si.free, si.available, disk_usage_percent(si)}) + std::cout << "│ " << std::setw(width) << static_cast(x) << ' '; + std::cout << "│ " << dir << '\\n'; + } + } + + int main() + { + const auto dirs = {"/dev/null", "/tmp", "/home", "/proc", "/null"}; + print_disk_space_info(dirs); + } + +.SH Possible output: + + │ Capacity │ Free │ Available │ Use% │ Dir + │ 84,417,331,200 │ 42,732,986,368 │ 40,156,028,928 │ 50 │ /dev/null + │ 84,417,331,200 │ 42,732,986,368 │ 40,156,028,928 │ 50 │ /tmp + │ -1 │ -1 │ -1 │ 100 │ /home + │ 0 │ 0 │ 0 │ 100 │ /proc + │ -1 │ -1 │ -1 │ 100 │ /null + +.SH See also + + space_info information about free and available space on the filesystem + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::filesystem::space_info.3 b/man/std::filesystem::space_info.3 new file mode 100644 index 000000000..e40eeb8ef --- /dev/null +++ b/man/std::filesystem::space_info.3 @@ -0,0 +1,109 @@ +.TH std::filesystem::space_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::space_info \- std::filesystem::space_info + +.SH Synopsis + Defined in header + struct space_info { + + std::uintmax_t capacity; + std::uintmax_t free; \fI(since C++17)\fP + std::uintmax_t available; + + }; + + Represents the filesystem information as determined by filesystem::space. + +.SH Member objects + + capacity total size of the filesystem, in bytes + \fI(public member object)\fP + free free space on the filesystem, in bytes + \fI(public member object)\fP + free space available to a non-privileged process (may be equal or less + available than free) + \fI(public member object)\fP + +.SH Non-member functions + + operator== compares two space_infos + (C++20) \fI(function)\fP + +operator==(std::filesystem::space_info) + + friend bool operator==( const space_info&, const space_info& ) = \fI(since C++20)\fP + default; + + Checks if capacity, free and available of both arguments are equal respectively. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::filesystem::space_info is an + associated class of the arguments. + + The != operator is synthesized from operator==. + +.SH Example + + +// Run this code + + #include + #include + #include + + std::uintmax_t disk_usage_percent(const std::filesystem::space_info& si, + bool is_privileged = false) noexcept + { + if (constexpr std::uintmax_t X(-1); + si.capacity == 0 || si.free == 0 || si.available == 0 || + si.capacity == X || si.free == X || si.available == X + ) + return 100; + + std::uintmax_t unused_space = si.free, capacity = si.capacity; + if (!is_privileged) + { + const std::uintmax_t privileged_only_space = si.free - si.available; + unused_space -= privileged_only_space; + capacity -= privileged_only_space; + } + const std::uintmax_t used_space{capacity - unused_space}; + return 100 * used_space / capacity; + } + + void print_disk_space_info(auto const& dirs, int width = 14) + { + (std::cout << std::left).imbue(std::locale("en_US.UTF-8")); + + for (const auto s : {"Capacity", "Free", "Available", "Use%", "Dir"}) + std::cout << "│ " << std::setw(width) << s << ' '; + + for (std::cout << '\\n'; auto const& dir : dirs) + { + std::error_code ec; + const std::filesystem::space_info si = std::filesystem::space(dir, ec); + for (auto x : {si.capacity, si.free, si.available, disk_usage_percent(si)}) + std::cout << "│ " << std::setw(width) << static_cast(x) << ' '; + std::cout << "│ " << dir << '\\n'; + } + } + + int main() + { + const auto dirs = {"/dev/null", "/tmp", "/home", "/proc", "/null"}; + print_disk_space_info(dirs); + } + +.SH Possible output: + + │ Capacity │ Free │ Available │ Use% │ Dir + │ 84,417,331,200 │ 42,732,986,368 │ 40,156,028,928 │ 50 │ /dev/null + │ 84,417,331,200 │ 42,732,986,368 │ 40,156,028,928 │ 50 │ /tmp + │ -1 │ -1 │ -1 │ 100 │ /home + │ 0 │ 0 │ 0 │ 100 │ /proc + │ -1 │ -1 │ -1 │ 100 │ /null + +.SH See also + + space determines available free space on the file system + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::status,std::filesystem::symlink_status.3 b/man/std::filesystem::status,std::filesystem::symlink_status.3 new file mode 100644 index 000000000..067853e14 --- /dev/null +++ b/man/std::filesystem::status,std::filesystem::symlink_status.3 @@ -0,0 +1,183 @@ +.TH std::filesystem::status,std::filesystem::symlink_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::status,std::filesystem::symlink_status \- std::filesystem::status,std::filesystem::symlink_status + +.SH Synopsis + Defined in header + std::filesystem::file_status status( const std::filesystem::path& \fB(1)\fP \fI(since C++17)\fP + p ); + std::filesystem::file_status status( const std::filesystem::path& + p, \fB(2)\fP \fI(since C++17)\fP + std::error_code& ec ) + noexcept; + std::filesystem::file_status symlink_status( const \fB(3)\fP \fI(since C++17)\fP + std::filesystem::path& p ); + std::filesystem::file_status symlink_status( const + std::filesystem::path& p, \fB(4)\fP \fI(since C++17)\fP + std::error_code& ec ) + noexcept; + + 1,2) Determines the type and attributes of the filesystem object identified by p as + if by POSIX stat (symlinks are followed to their targets). In the following + description, prms is the result of (m & perms::mask), where m is obtained as if by + taking st_mode from the POSIX struct stat and converting it to the type + std::filesystem::perms. + + * If p is a regular file (as if by POSIX S_ISREG), returns + file_status(file_type::regular, prms). + * If p is a directory (as if by POSIX S_ISDIR), returns + file_status(file_type::directory, prms). + * If p is a block special file (as if by POSIX S_ISBLK), returns + file_status(file_type::block, prms). + * If p is a character special file (as if by POSIX S_ISCHR), returns + file_status(file_type::character, prms). + * If p is a fifo or pipe file (as if by POSIX S_ISFIFO), returns + file_status(file_type::fifo, prms). + * If p is a socket (as if by POSIX S_ISSOCK), returns + file_status(file_type::socket, prms). + * If p has an implementation-defined file type, returns file_status(file_type::A, + prms) where A is the implementation-defined file_type constant for that type. + * If p does not exist, returns file_status(file_type::not_found). + * If p exists but file attributes cannot be determined, e.g. due to lack of + permissions, returns file_status(file_type::unknown). + * If errors prevent even knowing whether p exists, the non-throwing overload sets + ec and returns file_status(file_type::none), and the throwing overload throws + filesystem_error. + * Otherwise, returns file_status(file_type::unknown, prms). + 3,4) Same as (1,2) except that the behavior is as if the POSIX lstat is used + (symlinks are not followed): + + * If p is a symlink, returns file_status(file_type::symlink). + +.SH Parameters + + p - path to examine + ec - out-parameter for error reporting in the non-throwing overload + +.SH Return value + + The file status (a filesystem::file_status object). + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1,3) Throws std::filesystem::filesystem_error on underlying OS API errors, + constructed with p as the first path argument and the OS error code as the error + code argument. + 2,4) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + The information provided by this function is usually also provided as a byproduct of + directory iteration, and may be obtained by the member functions of + filesystem::directory_entry. During directory iteration, calling status again is + unnecessary. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + namespace fs = std::filesystem; + + void demo_status(const fs::path& p, fs::file_status s) + { + std::cout << p; + // alternative: switch(s.type()) { case fs::file_type::regular: ...} + if (fs::is_regular_file(s)) + std::cout << " is a regular file\\n"; + if (fs::is_directory(s)) + std::cout << " is a directory\\n"; + if (fs::is_block_file(s)) + std::cout << " is a block device\\n"; + if (fs::is_character_file(s)) + std::cout << " is a character device\\n"; + if (fs::is_fifo(s)) + std::cout << " is a named IPC pipe\\n"; + if (fs::is_socket(s)) + std::cout << " is a named IPC socket\\n"; + if (fs::is_symlink(s)) + std::cout << " is a symlink\\n"; + if (!fs::exists(s)) + std::cout << " does not exist\\n"; + } + + int main() + { + // create files of different kinds + fs::create_directory("sandbox"); + fs::create_directory("sandbox/dir"); + std::ofstream{"sandbox/file"}; // create regular file + fs::create_symlink("file", "sandbox/symlink"); + + mkfifo("sandbox/pipe", 0644); + sockaddr_un addr; + addr.sun_family = AF_UNIX; + std::strcpy(addr.sun_path, "sandbox/sock"); + int fd = socket(PF_UNIX, SOCK_STREAM, 0); + bind(fd, reinterpret_cast(&addr), sizeof addr); + + // demo different status accessors + for (auto it{fs::directory_iterator("sandbox")}; it != fs::directory_iterator(); ++it) + demo_status(*it, it->symlink_status()); // use cached status from directory entry + demo_status("/dev/null", fs::status("/dev/null")); // direct calls to status + demo_status("/dev/sda", fs::status("/dev/sda")); + demo_status("sandbox/no", fs::status("/sandbox/no")); + + // cleanup (prefer std::unique_ptr-based custom deleters) + close(fd); + fs::remove_all("sandbox"); + } + +.SH Possible output: + + "sandbox/file" is a regular file + "sandbox/dir" is a directory + "sandbox/pipe" is a named IPC pipe + "sandbox/sock" is a named IPC socket + "sandbox/symlink" is a symlink + "/dev/null" is a character device + "/dev/sda" is a block device + "sandbox/no" does not exist + +.SH See also + + file_status represents file type and permissions + \fI(C++17)\fP \fI(class)\fP + status_known checks whether file status is known + \fI(C++17)\fP \fI(function)\fP + is_block_file checks whether the given path refers to block device + \fI(C++17)\fP \fI(function)\fP + is_character_file checks whether the given path refers to a character device + \fI(C++17)\fP \fI(function)\fP + is_directory checks whether the given path refers to a directory + \fI(C++17)\fP \fI(function)\fP + is_fifo checks whether the given path refers to a named pipe + \fI(C++17)\fP \fI(function)\fP + is_other checks whether the argument refers to an other file + \fI(C++17)\fP \fI(function)\fP + is_regular_file checks whether the argument refers to a regular file + \fI(C++17)\fP \fI(function)\fP + is_socket checks whether the argument refers to a named IPC socket + \fI(C++17)\fP \fI(function)\fP + is_symlink checks whether the argument refers to a symbolic link + \fI(C++17)\fP \fI(function)\fP + exists checks whether path refers to existing file system object + \fI(C++17)\fP \fI(function)\fP + status of the file designated by this directory entry; + status status of the file/symlink designated by this directory entry + symlink_status \fI(public member function of std::filesystem::directory_entry)\fP + diff --git a/man/std::filesystem::status_known.3 b/man/std::filesystem::status_known.3 new file mode 100644 index 000000000..83c30f26c --- /dev/null +++ b/man/std::filesystem::status_known.3 @@ -0,0 +1,33 @@ +.TH std::filesystem::status_known 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::status_known \- std::filesystem::status_known + +.SH Synopsis + Defined in header + bool status_known( std::filesystem::file_status s ) noexcept; \fB(1)\fP \fI(since C++17)\fP + + Checks if the given file status is known, equivalent to s.type() != file_type::none. + +.SH Parameters + + s - file status to check + +.SH Return value + + true if the given file status is a known file status. + +.SH Notes + + Despite the name, the function checks for the file status of file_type::none + (meaning an error occurred), not file_type::unknown (meaning file exists, but its + type cannot be determined). + +.SH See also + + status determines file attributes + symlink_status determines file attributes, checking the symlink target + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + status status of the file designated by this directory entry; + symlink_status status of the file/symlink designated by this directory entry + \fI(public member function of std::filesystem::directory_entry)\fP diff --git a/man/std::filesystem::swap(std::filesystem::path).3 b/man/std::filesystem::swap(std::filesystem::path).3 new file mode 100644 index 000000000..f68d9fbe4 --- /dev/null +++ b/man/std::filesystem::swap(std::filesystem::path).3 @@ -0,0 +1,23 @@ +.TH std::filesystem::swap(std::filesystem::path) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::swap(std::filesystem::path) \- std::filesystem::swap(std::filesystem::path) + +.SH Synopsis + Defined in header + void swap( std::filesystem::path& lhs, std::filesystem::path& rhs ) \fI(since C++17)\fP + noexcept; + + Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - paths whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH See also + + swap swaps two paths + \fI(public member function)\fP diff --git a/man/std::filesystem::temp_directory_path.3 b/man/std::filesystem::temp_directory_path.3 new file mode 100644 index 000000000..85014b979 --- /dev/null +++ b/man/std::filesystem::temp_directory_path.3 @@ -0,0 +1,64 @@ +.TH std::filesystem::temp_directory_path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::temp_directory_path \- std::filesystem::temp_directory_path + +.SH Synopsis + Defined in header + path temp_directory_path(); \fB(1)\fP \fI(since C++17)\fP + path temp_directory_path( std::error_code& ec ); \fB(2)\fP \fI(since C++17)\fP + + Returns the directory location suitable for temporary files. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A directory suitable for temporary files. The path is guaranteed to exist and to be + a directory. The overload that takes error_code& argument returns an empty path on + error. + +.SH Exceptions + + Any overload not marked noexcept may throw std::bad_alloc if memory allocation + fails. + + 1) Throws std::filesystem::filesystem_error on underlying OS API errors, constructed + with path to be returned as the first path argument and the OS error code as the + error code argument. + 2) Sets a std::error_code& parameter to the OS API error code if an OS API call + fails, and executes ec.clear() if no errors occur. + +.SH Notes + + On POSIX systems, the path may be the one specified in the environment variables + TMPDIR, TMP, TEMP, TEMPDIR, and, if none of them are specified, the path "/tmp" is + returned. + + On Windows systems, the path is typically the one returned by GetTempPath. + +.SH Example + + +// Run this code + + #include + #include + namespace fs = std::filesystem; + + int main() + { + std::cout << "Temp directory is " << fs::temp_directory_path() << '\\n'; + } + +.SH Possible output: + + Temp directory is "C:\\Windows\\TEMP\\" + +.SH See also + + tmpfile creates and opens a temporary, auto-removing file + \fI(function)\fP + current_path returns or sets the current working directory + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::filesystem::u8path.3 b/man/std::filesystem::u8path.3 new file mode 100644 index 000000000..27654688c --- /dev/null +++ b/man/std::filesystem::u8path.3 @@ -0,0 +1,115 @@ +.TH std::filesystem::u8path 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::filesystem::u8path \- std::filesystem::u8path + +.SH Synopsis + Defined in header + template< class Source > \fB(1)\fP \fI(since C++17)\fP + std::filesystem::path u8path( const Source& source ); (deprecated in C++20) + template< class InputIt > \fI(since C++17)\fP + std::filesystem::path u8path( InputIt first, InputIt last \fB(2)\fP (deprecated in C++20) + ); + + Constructs a path p from a UTF-8 encoded sequence of chars + or char8_ts + \fI(since C++20)\fP, supplied either as an std::string, or as std::string_view, or as a + null-terminated multibyte string, or as a [first, last) iterator pair. + + * If path::value_type is char and native encoding is UTF-8, constructs a path + directly as if by path(source) or path(first, last). Note: this is the typical + situation of a POSIX system that uses Unicode, such as Linux. + * Otherwise, if path::value_type is wchar_t and native encoding is UTF-16 (this is + the situation on Windows), or if path::value_type is char16_t (native encoding + guaranteed UTF-16) or char32_t (native encoding guaranteed UTF-32), then first + converts the UTF-8 character sequence to a temporary string tmp of type + path::string_type and then the new path is constructed as if by path(tmp). + * Otherwise (for non-UTF-8 narrow character encodings and for non-UTF-16 wchar_t), + first converts the UTF-8 character sequence to a temporary UTF-32-encoded string + tmp of type std::u32string, and then the new path is constructed as if by + path(tmp) (this path is taken on a POSIX system with a non-Unicode multibyte or + single-byte encoded filesystem). + +.SH Parameters + + a UTF-8 encoded std::string, std::string_view, a pointer to a + source - null-terminated multibyte string, or an input iterator with char value + type that points to a null-terminated multibyte string + first, last - pair of LegacyInputIterators that specify a UTF-8 encoded character + sequence +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + The value type of Source or InputIt must be char + or char8_t. + \fI(since C++20)\fP + +.SH Return value + + The path constructed from the input string after conversion from UTF-8 to the + filesystem's native character encoding. + +.SH Exceptions + + May throw std::bad_alloc if memory allocation fails. + +.SH Notes + + On systems where native path format differs from the generic path format (neither + Windows nor POSIX systems are examples of such OSes), if the argument to this + function is using generic format, it will be converted to native. + +.SH Example + + +// Run this code + + #include + #ifdef _MSC_VER + #include + #include + #else + #include + #include + #endif + #include + #include + + int main() + { + #ifdef _MSC_VER + _setmode(_fileno(stderr), _O_WTEXT); + #else + std::setlocale(LC_ALL, ""); + std::locale::global(std::locale("")); + #endif + + std::filesystem::path p(u8"要らない.txt"); + std::ofstream(p) << "File contents"; // Prior to LWG2676 uses operator string_type() + // on MSVC, where string_type is wstring, only + // works due to non-standard extension. + // Post-LWG2676 uses new fstream constructors + + // Native string representation can be used with OS-specific APIs + #ifdef _MSC_VER + if (std::FILE* f = _wfopen(p.c_str(), L"r")) + #else + if (std::FILE* f = std::fopen(p.c_str(), "r")) + #endif + { + for (int ch; (ch = fgetc(f)) != EOF; std::putchar(ch)) + {} + std::fclose(f); + } + + std::filesystem::remove(p); + } + +.SH Possible output: + + File contents + +.SH See also + + path represents a path + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::fill.3 b/man/std::fill.3 index 0b631fa63..e51dacace 100644 --- a/man/std::fill.3 +++ b/man/std::fill.3 @@ -1,71 +1,155 @@ -.TH std::fill 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fill \- std::fill + .SH Synopsis Defined in header - template< class ForwardIt, class T > - void fill( ForwardIt first, ForwardIt last, const T& value ); - - Assigns the given value to the elements in the range [first, last). + template< class ForwardIt, class T > (constexpr since + void fill( ForwardIt first, ForwardIt last, C++20) + const T& value ); (until C++26) + template< class ForwardIt, class T = typename + std::iterator_traits + + + ::value_type > (since C++26) + constexpr void fill( ForwardIt first, + ForwardIt last, + + const T& value ); + template< class ExecutionPolicy, class + ForwardIt, class T > + \fB(1)\fP \fI(since C++17)\fP + void fill( ExecutionPolicy&& policy, (until C++26) + + ForwardIt first, ForwardIt last, + const T& value ); + template< class ExecutionPolicy, + \fB(2)\fP + class ForwardIt, class T = typename + std::iterator_traits + (since C++26) + ::value_type > + void fill( ExecutionPolicy&& policy, + + ForwardIt first, ForwardIt last, + const T& value ); + + 1) Assigns the given value to all elements in the range [first, last). + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If value is not writable to first, the program is ill-formed. .SH Parameters - first, last - the range of elements to modify - value - the value to be assigned + first, last - the range of elements to modify + value - the value to be assigned + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. -.SH Return value +.SH Complexity - \fI(none)\fP + Exactly std::distance(first, last) assignments. -.SH Complexity +.SH Exceptions - Exactly last - first assignments. + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template< class ForwardIt, class T > + fill + template::value_type> void fill(ForwardIt first, ForwardIt last, const T& value) { - for (; first != last; ++first) { + for (; first != last; ++first) *first = value; - } } +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + .SH Example - The following code uses fill() to set all of the elements of a vector of integers to - -1: - // Run this code #include - #include + #include #include - + #include + + void println(const auto& seq) + { + for (const auto& e : seq) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { - int data[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; - std::vector v1(data, data+10); - - std::fill(v1.begin(), v1.end(), -1); - - for (auto elem : v1) { - std::cout << elem << " "; - } - std::cout << "\\n"; + std::vector v{0, 1, 2, 3, 4, 5, 6, 7, 8}; + println(v); + + // set all of the elements to 8 + std::fill(v.begin(), v.end(), 8); + println(v); + + std::vector> nums{{1, 3}, {2, 2}, {4, 8}}; + println(nums); + #ifdef __cpp_lib_algorithm_default_value_type + std::fill(nums.begin(), nums.end(), {4, 2}); + #else + std::fill(nums.begin(), nums.end(), std::complex{4, 2}); + #endif + println(nums); } .SH Output: - -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 + 0 1 2 3 4 5 6 7 8 + 8 8 8 8 8 8 8 8 8 + (1,3) (2,2) (4,8) + (4,2) (4,2) (4,2) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be CopyAssignable, required to be writable + LWG 283 C++98 but instead + T is not always writable to ForwardIt .SH See also - fill_n assigns a value to a number of elements - \fI(function template)\fP - generate saves the result of a function in a range - \fI(function template)\fP - transform applies a function to a range of elements - \fI(function template)\fP + fill_n copy-assigns the given value to N elements in a range + \fI(function template)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + assigns the results of successive function calls to every element in a + generate range + \fI(function template)\fP + applies a function to a range of elements, storing results in a + transform destination range + \fI(function template)\fP + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) diff --git a/man/std::fill_n.3 b/man/std::fill_n.3 index caff11dc2..fe56d7286 100644 --- a/man/std::fill_n.3 +++ b/man/std::fill_n.3 @@ -1,72 +1,162 @@ -.TH std::fill_n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fill_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fill_n \- std::fill_n + .SH Synopsis Defined in header - template< class OutputIt, class Size, class T > \fI(until C++11)\fP - void fill_n( OutputIt first, Size count, const T& value ); - template< class OutputIt, class Size, class T > \fI(since C++11)\fP - OutputIt fill_n( OutputIt first, Size count, const T& value ); - - Assigns the given value value to the first count elements in the range beginning at + template< class OutputIt, class Size, class T (constexpr since + > C++20) + OutputIt fill_n( OutputIt first, Size count, (until C++26) + const T& value ); + template< class OutputIt, class Size, + + class T = typename + std::iterator_traits + (since C++26) + ::value_type > + constexpr OutputIt fill_n( OutputIt first, + Size count, + + const T& value ); + template< class ExecutionPolicy, + + class ForwardIt, class Size, class \fB(1)\fP + T > \fI(since C++17)\fP + ForwardIt fill_n( ExecutionPolicy&& policy, (until C++26) + + ForwardIt first, Size + count, const T& value ); + template< class ExecutionPolicy, + \fB(2)\fP + class ForwardIt, class Size, + class T = typename + std::iterator_traits + (since C++26) + ::value_type > + ForwardIt fill_n( ExecutionPolicy&& policy, + + ForwardIt first, Size + count, const T& value ); + + 1) Assigns the given value to the first count elements in the range beginning at first if count > 0. Does nothing otherwise. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the program is ill-formed: + + * value is not writable to first. + * Size is not convertible to an integral type. .SH Parameters - first - the beginning of the range of elements to modify - count - number of elements to modify - value - the value to be assigned + first - the beginning of the range of elements to modify + count - number of elements to modify + value - the value to be assigned + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value - \fI(none)\fP \fI(until C++11)\fP - Iterator one past the last element assigned if count > 0, first \fI(since C++11)\fP - otherwise. + Iterator one past the last element assigned if count > 0, first otherwise. .SH Complexity - Exactly count assignments, for count > 0. + Exactly std::max(0, count) assignments. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template + fill_n + template::value_type> OutputIt fill_n(OutputIt first, Size count, const T& value) { - for (Size i = 0; i < count; i++) { + for (Size i = 0; i < count; i++) *first++ = value; - } return first; } +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + .SH Example - The following code uses fill_n() to assign -1 to the first half of a vector of - integers: - // Run this code #include - #include + #include #include #include - + #include + int main() { std::vector v1{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; - + + // replace values of the first 5 elements with -1 std::fill_n(v1.begin(), 5, -1); - - std::copy(begin(v1), end(v1), std::ostream_iterator(std::cout, " ")); - std::cout << "\\n"; + + std::copy_n(v1.cbegin(), v1.size(), std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + + std::vector> nums{{1, 3}, {2, 2}, {4, 8}}; + #ifdef __cpp_lib_algorithm_default_value_type + std::fill_n(nums.begin(), 2, {4, 2}); + #else + std::fill_n(nums.begin(), 2, std::complex{4, 2}); + #endif + std::copy_n(nums.cbegin(), nums.size(), + std::ostream_iterator>(std::cout, " ")); + std::cout << '\\n'; } .SH Output: -1 -1 -1 -1 -1 5 6 7 8 9 + (4,2) (4,2) (4,8) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 283 C++98 T was required to be CopyAssignable, but required to be writable + T is not always writable to OutputIt instead + the complexity requirement was “exactly + LWG 426 C++98 count no assignment if + assignments”, which is broken if count is count is non-positive + negative + the location of the first element + LWG 865 C++98 following returned + the filling range was not returned .SH See also - fill assigns a range of elements a certain value - \fI(function template)\fP + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + ranges::fill_n assigns a value to a number of elements + (C++20) (niebloid) diff --git a/man/std::find,std::find_if,std::find_if_not.3 b/man/std::find,std::find_if,std::find_if_not.3 index 2870c4a43..a4eedd11a 100644 --- a/man/std::find,std::find_if,std::find_if_not.3 +++ b/man/std::find,std::find_if,std::find_if_not.3 @@ -1,162 +1,252 @@ -.TH std::find,std::find_if,std::find_if_not 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::find,std::find_if,std::find_if_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::find,std::find_if,std::find_if_not \- std::find,std::find_if,std::find_if_not + .SH Synopsis Defined in header - template< class InputIt, class T > \fB(1)\fP - InputIt find( InputIt first, InputIt last, const T& value ); - template< class InputIt, class UnaryPredicate > - - InputIt find_if( InputIt first, InputIt last, \fB(2)\fP - - UnaryPredicate p ); - template< class InputIt, class UnaryPredicate > - - InputIt find_if_not( InputIt first, InputIt last, \fB(3)\fP \fI(since C++11)\fP - - UnaryPredicate q ); - - Returns the first element in the range [first, last) that satisfies specific - criteria: - - 1) find searches for an element equal to value - 2) find_if searches for an element for which predicate p returns true - 3) find_if_not searches for element for which predicate q returns false + template< class InputIt, class T > (constexpr since + InputIt find( InputIt first, InputIt last, C++20) + const T& value ); (until C++26) + template< class InputIt, class T = + typename std::iterator_traits + + (since C++26) + ::value_type > + + constexpr InputIt find( InputIt first, + InputIt last, const T& value ); + template< class ExecutionPolicy, class + ForwardIt, class T > + \fI(since C++17)\fP + ForwardIt find( ExecutionPolicy&& policy, (until C++26) + + ForwardIt first, ForwardIt + last, const T& value ); + template< class ExecutionPolicy, + + class ForwardIt, class T = + typename std::iterator_traits + (since C++26) + ::value_type > + ForwardIt find( ExecutionPolicy&& policy, \fB(1)\fP + + ForwardIt first, ForwardIt + last, const T& value ); + template< class InputIt, class UnaryPred > (constexpr since + InputIt find_if( InputIt first, InputIt \fB(3)\fP C++20) + last, UnaryPred p ); \fB(2)\fP + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if( ExecutionPolicy&& \fB(4)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred p ); + template< class InputIt, class UnaryPred > \fI(since C++11)\fP + InputIt find_if_not( InputIt first, \fB(5)\fP (constexpr since + InputIt last, UnaryPred q ); C++20) + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if_not( ExecutionPolicy&& \fB(6)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred q ); + + Returns an iterator to the first element in the range [first, last) that satisfies + specific criteria (or last if there is no such iterator). + + 1) find searches for an element equal to value (using operator==). + 3) find_if searches for an element for which predicate p returns true. + 5) find_if_not searches for an element for which predicate q returns false. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine value - value to compare the elements to + policy - the execution policy to use. See execution policy for details. unary predicate which returns true for the required element. - The signature of the predicate function should be equivalent to the - following: - - p - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. unary predicate which returns false for the required element. - The signature of the predicate function should be equivalent to the - following: - - q - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression q(v) must be convertible to bool for every argument v + q - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. - UnaryPredicate must meet the requirements of Predicate. .SH Return value - Iterator to the first element satisfying the condition or last if no such element is - found. + The first iterator it in the range [first, last) satisfying the following condition + or last if there is no such iterator: + + 1,2) *it == value is true. + 3,4) p(*it) is true. + 5,6) q(*it) is false. .SH Complexity - At most last - first applications of the predicate + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize N\\)N comparisons with value using operator==. + 3,4) At most \\(\\scriptsize N\\)N applications of the predicate p. + 5,6) At most \\(\\scriptsize N\\)N applications of the predicate q. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - InputIt find(InputIt first, InputIt last, const T& value) + find + template::value_type> + constexpr InputIt find(InputIt first, InputIt last, const T& value) { - for (; first != last; ++first) { - if (*first == value) { + for (; first != last; ++first) + if (*first == value) return first; - } - } + return last; } -.SH Second version - template - InputIt find_if(InputIt first, InputIt last, UnaryPredicate p) + find_if + template + constexpr InputIt find_if(InputIt first, InputIt last, UnaryPred p) { - for (; first != last; ++first) { - if (p(*first)) { + for (; first != last; ++first) + if (p(*first)) return first; - } - } + return last; } - Third version - template - InputIt find_if_not(InputIt first, InputIt last, UnaryPredicate q) + find_if_not + template + constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) { - for (; first != last; ++first) { - if (!q(*first)) { + for (; first != last; ++first) + if (!q(*first)) return first; - } - } + return last; } - If you do not have C++11, an equivalent to std::find_if_not is to use std::find_if +.SH Notes + + If C++11 is not available, an equivalent to std::find_if_not is to use std::find_if with the negated predicate. - template - InputIt find_if_not(InputIt first, InputIt last, UnaryPredicate q) + template + InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) { return std::find_if(first, last, std::not1(q)); } + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + .SH Example - The following example finds an integer in a vector of integers. + The following example finds numbers in given sequences. + - // Run this code - #include #include + #include + #include + #include + #include #include - #include - + int main() { - int n1 = 3; - int n2 = 5; - - std::vector v{0, 1, 2, 3, 4}; - - auto result1 = std::find(std::begin(v), std::end(v), n1); - auto result2 = std::find(std::begin(v), std::end(v), n2); - - if (result1 != std::end(v)) { - std::cout << "v contains: " << n1 << '\\n'; - } else { - std::cout << "v does not contain: " << n1 << '\\n'; - } - - if (result2 != std::end(v)) { - std::cout << "v contains: " << n2 << '\\n'; - } else { - std::cout << "v does not contain: " << n2 << '\\n'; - } + const auto v = {1, 2, 3, 4}; + + for (const int n : {3, 5}) + (std::find(v.begin(), v.end(), n) == std::end(v)) + ? std::cout << "v does not contain " << n << '\\n' + : std::cout << "v contains " << n << '\\n'; + + auto is_even = [](int i) { return i % 2 == 0; }; + + for (const auto& w : {std::array{3, 1, 4}, {1, 3, 5}}) + if (auto it = std::find_if(begin(w), end(w), is_even); it != std::end(w)) + std::cout << "w contains an even number " << *it << '\\n'; + else + std::cout << "w does not contain even numbers\\n"; + + std::vector> nums{{4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + // T gets deduced making list-initialization possible + const auto it = std::find(nums.begin(), nums.end(), {4, 2}); + #else + const auto it = std::find(nums.begin(), nums.end(), std::complex{4, 2}); + #endif + assert(it == nums.begin()); } .SH Output: - v contains: 3 - v does not contain: 5 + v contains 3 + v does not contain 5 + w contains an even number 4 + w does not contain even numbers + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, + LWG 283 C++98 but removed the requirement + the value type of InputIt might not be T .SH See also - finds two identical (or some other relationship) items adjacent to - adjacent_find each other - \fI(function template)\fP - find_end finds the last sequence of elements in a certain range - \fI(function template)\fP - find_first_of searches for any one of a set of elements - \fI(function template)\fP - mismatch finds the first position where two ranges differ - \fI(function template)\fP - search searches for a range of elements - \fI(function template)\fP + finds the first two adjacent items that are equal (or satisfy a + adjacent_find given predicate) + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + find_first_of searches for any one of a set of elements + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) diff --git a/man/std::find.3 b/man/std::find.3 deleted file mode 120000 index 1bc08435f..000000000 --- a/man/std::find.3 +++ /dev/null @@ -1 +0,0 @@ -std::find,std::find_if,std::find_if_not.3 \ No newline at end of file diff --git a/man/std::find.3 b/man/std::find.3 new file mode 100644 index 000000000..a4eedd11a --- /dev/null +++ b/man/std::find.3 @@ -0,0 +1,252 @@ +.TH std::find,std::find_if,std::find_if_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::find,std::find_if,std::find_if_not \- std::find,std::find_if,std::find_if_not + +.SH Synopsis + Defined in header + template< class InputIt, class T > (constexpr since + InputIt find( InputIt first, InputIt last, C++20) + const T& value ); (until C++26) + template< class InputIt, class T = + typename std::iterator_traits + + (since C++26) + ::value_type > + + constexpr InputIt find( InputIt first, + InputIt last, const T& value ); + template< class ExecutionPolicy, class + ForwardIt, class T > + \fI(since C++17)\fP + ForwardIt find( ExecutionPolicy&& policy, (until C++26) + + ForwardIt first, ForwardIt + last, const T& value ); + template< class ExecutionPolicy, + + class ForwardIt, class T = + typename std::iterator_traits + (since C++26) + ::value_type > + ForwardIt find( ExecutionPolicy&& policy, \fB(1)\fP + + ForwardIt first, ForwardIt + last, const T& value ); + template< class InputIt, class UnaryPred > (constexpr since + InputIt find_if( InputIt first, InputIt \fB(3)\fP C++20) + last, UnaryPred p ); \fB(2)\fP + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if( ExecutionPolicy&& \fB(4)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred p ); + template< class InputIt, class UnaryPred > \fI(since C++11)\fP + InputIt find_if_not( InputIt first, \fB(5)\fP (constexpr since + InputIt last, UnaryPred q ); C++20) + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if_not( ExecutionPolicy&& \fB(6)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred q ); + + Returns an iterator to the first element in the range [first, last) that satisfies + specific criteria (or last if there is no such iterator). + + 1) find searches for an element equal to value (using operator==). + 3) find_if searches for an element for which predicate p returns true. + 5) find_if_not searches for an element for which predicate q returns false. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of elements to examine + value - value to compare the elements to + policy - the execution policy to use. See execution policy for details. + unary predicate which returns true for the required element. + + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. + unary predicate which returns false for the required element. + + The expression q(v) must be convertible to bool for every argument v + q - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + UnaryPredicate must meet the requirements of Predicate. + +.SH Return value + + The first iterator it in the range [first, last) satisfying the following condition + or last if there is no such iterator: + + 1,2) *it == value is true. + 3,4) p(*it) is true. + 5,6) q(*it) is false. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize N\\)N comparisons with value using operator==. + 3,4) At most \\(\\scriptsize N\\)N applications of the predicate p. + 5,6) At most \\(\\scriptsize N\\)N applications of the predicate q. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + find + template::value_type> + constexpr InputIt find(InputIt first, InputIt last, const T& value) + { + for (; first != last; ++first) + if (*first == value) + return first; + + return last; + } + find_if + template + constexpr InputIt find_if(InputIt first, InputIt last, UnaryPred p) + { + for (; first != last; ++first) + if (p(*first)) + return first; + + return last; + } + find_if_not + template + constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) + { + for (; first != last; ++first) + if (!q(*first)) + return first; + + return last; + } + +.SH Notes + + If C++11 is not available, an equivalent to std::find_if_not is to use std::find_if + with the negated predicate. + + template + InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) + { + return std::find_if(first, last, std::not1(q)); + } + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + The following example finds numbers in given sequences. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + const auto v = {1, 2, 3, 4}; + + for (const int n : {3, 5}) + (std::find(v.begin(), v.end(), n) == std::end(v)) + ? std::cout << "v does not contain " << n << '\\n' + : std::cout << "v contains " << n << '\\n'; + + auto is_even = [](int i) { return i % 2 == 0; }; + + for (const auto& w : {std::array{3, 1, 4}, {1, 3, 5}}) + if (auto it = std::find_if(begin(w), end(w), is_even); it != std::end(w)) + std::cout << "w contains an even number " << *it << '\\n'; + else + std::cout << "w does not contain even numbers\\n"; + + std::vector> nums{{4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + // T gets deduced making list-initialization possible + const auto it = std::find(nums.begin(), nums.end(), {4, 2}); + #else + const auto it = std::find(nums.begin(), nums.end(), std::complex{4, 2}); + #endif + assert(it == nums.begin()); + } + +.SH Output: + + v contains 3 + v does not contain 5 + w contains an even number 4 + w does not contain even numbers + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, + LWG 283 C++98 but removed the requirement + the value type of InputIt might not be T + +.SH See also + + finds the first two adjacent items that are equal (or satisfy a + adjacent_find given predicate) + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + find_first_of searches for any one of a set of elements + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) diff --git a/man/std::find_end.3 b/man/std::find_end.3 index b8352d850..9bbfc4fa4 100644 --- a/man/std::find_end.3 +++ b/man/std::find_end.3 @@ -1,26 +1,60 @@ -.TH std::find_end 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::find_end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::find_end \- std::find_end + .SH Synopsis Defined in header template< class ForwardIt1, class ForwardIt2 > - ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, \fB(1)\fP + ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, \fB(1)\fP (constexpr since C++20) + + ForwardIt2 s_first, ForwardIt2 + s_last ); + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > + + ForwardIt1 find_end( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + + ForwardIt2 s_first, ForwardIt2 + s_last ); + template< class ForwardIt1, class ForwardIt2, class + BinaryPred > + + ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, \fB(3)\fP (constexpr since C++20) + ForwardIt2 s_first, ForwardIt2 + s_last, + + BinaryPred p ); + template< class ExecutionPolicy, - ForwardIt2 s_first, ForwardIt2 s_last ); - template< class ForwardIt1, class ForwardIt2, class BinaryPredicate > + class ForwardIt1, class ForwardIt2, class + BinaryPred > + ForwardIt1 find_end( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + ForwardIt2 s_first, ForwardIt2 + s_last, - ForwardIt1 find_end( ForwardIt1 first, ForwardIt1 last, \fB(2)\fP + BinaryPred p ); - ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p - ); + Searches for the last occurrence of the sequence [s_first, s_last) in the range + [first, last). - Searches for the last subsequence of elements [s_first, s_last) in the range [first, - last). The first version uses operator== to compare the elements, the second version - uses the given binary predicate p. + 1) Elements are compared using operator==. + 3) Elements are compared using the given binary predicate p. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine s_first, s_last - the range of elements to search for + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -28,49 +62,66 @@ the following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must - not modify the objects passed to it. + + p - While the signature does not need to have const &, the function + must not modify the objects passed to it and must be able to + accept all values of type (possibly const) Type1 and Type2 + regardless of value category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types ForwardIt1 and ForwardIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. - - .SH Type requirements - - ForwardIt1 must meet the requirements of ForwardIterator. + ForwardIt1 must meet the requirements of LegacyForwardIterator. - - ForwardIt2 must meet the requirements of ForwardIterator. + ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value - Iterator to the beginning of last subsequence [s_first, s_last) in range [first, - last). + Iterator to the beginning of last occurrence of the sequence [s_first, s_last) in + range [first, last). - If no such subsequence is found, last is returned. \fI(until C++11)\fP - If [s_first, s_last) is empty or if no such subsequence is found, last \fI(since C++11)\fP - is returned. + If [s_first, s_last) is empty or if no such sequence is found, last is returned. .SH Complexity - Does at most S*(N-S+1) comparisons where S = distance(s_first, s_last) and N = - distance(first, last). + Given \\(\\scriptsize N\\)N as std::distance(first1, last1) and \\(\\scriptsize S\\)S as + std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize S\\cdot(N-S+1)\\)S·(N-S+1) comparisons using operator==. + 3,4) At most \\(\\scriptsize S\\cdot(N-S+1)\\)S·(N-S+1) applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + find_end \fB(1)\fP template + constexpr //< since C++20 ForwardIt1 find_end(ForwardIt1 first, ForwardIt1 last, ForwardIt2 s_first, ForwardIt2 s_last) { if (s_first == s_last) return last; + ForwardIt1 result = last; - while \fB(1)\fP { + while (true) + { ForwardIt1 new_result = std::search(first, last, s_first, s_last); - if (new_result == last) { - return result; - } else { + if (new_result == last) + break; + else + { result = new_result; first = result; ++first; @@ -78,20 +129,24 @@ } return result; } -.SH Second version - template + find_end \fB(3)\fP + template + constexpr //< since C++20 ForwardIt1 find_end(ForwardIt1 first, ForwardIt1 last, ForwardIt2 s_first, ForwardIt2 s_last, - BinaryPredicate p) + BinaryPred p) { if (s_first == s_last) return last; + ForwardIt1 result = last; - while \fB(1)\fP { + while (true) + { ForwardIt1 new_result = std::search(first, last, s_first, s_last, p); - if (new_result == last) { - return result; - } else { + if (new_result == last) + break; + else + { result = new_result; first = result; ++first; @@ -102,59 +157,77 @@ .SH Example - The following code uses find_end() to search for two different sequences of numbers. - // Run this code #include + #include + #include #include - #include - + + auto print_result = [](auto result, const auto& v) + { + result == v.end() + ? std::cout << "Sequence not found\\n" + : std::cout << "Last occurrence is at: " << std::distance(v.begin(), result) + << '\\n'; + }; + int main() { - std::vector v{1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4}; - std::vector::iterator result; - - std::vector t1{1, 2, 3}; - - result = std::find_end(v.begin(), v.end(), t1.begin(), t1.end()); - if (result == v.end()) { - std::cout << "subsequence not found\\n"; - } else { - std::cout << "last subsequence is at: " - << std::distance(v.begin(), result) << "\\n"; + const auto v = {1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto const& x : {std::array{1, 2, 3}, {4, 5, 6}}) + { + auto iter = std::find_end(v.begin(), v.end(), x.begin(), x.end()); // overload (1) + print_result(iter, v); } - - std::vector t2{4, 5, 6}; - result = std::find_end(v.begin(), v.end(), t2.begin(), t2.end()); - if (result == v.end()) { - std::cout << "subsequence not found\\n"; - } else { - std::cout << "last subsequence is at: " - << std::distance(v.begin(), result) << "\\n"; + + for (auto const& x : {std::array{-1, -2, -3}, {-4, -5, -6}}) + { + auto iter = std::find_end(v.begin(), v.end(), x.begin(), x.end(), // overload (3) + [](int x, int y) + { + return std::abs(x) == std::abs(y); + }); + print_result(iter, v); } } .SH Output: - last subsequence is at: 8 - subsequence not found + Last occurrence is at: 8 + Sequence not found + Last occurrence is at: 8 + Sequence not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1205 C++98 the return value was unclear if returns last in this + [s_first, s_last) is empty case + LWG 2150 C++98 the condition of “sequence occurence” was corrected + incorrect .SH See also - search searches for a range of elements - \fI(function template)\fP - includes returns true if one set is a subset of another - \fI(function template)\fP - finds two identical (or some other relationship) items adjacent to - adjacent_find each other - \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + includes returns true if one sequence is a subsequence of another + \fI(function template)\fP + finds the first two adjacent items that are equal (or satisfy a + adjacent_find given predicate) + \fI(function template)\fP find - find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP \fI(C++11)\fP - find_first_of searches for any one of a set of elements - \fI(function template)\fP - search_n searches for a number consecutive copies of an element in a range - \fI(function template)\fP + find_first_of searches for any one of a set of elements + \fI(function template)\fP + search_n searches a range for a number of consecutive copies of an element + \fI(function template)\fP + ranges::find_end finds the last sequence of elements in a certain range + (C++20) (niebloid) diff --git a/man/std::find_first_of.3 b/man/std::find_first_of.3 index 3d8e9d5bd..511c942aa 100644 --- a/man/std::find_first_of.3 +++ b/man/std::find_first_of.3 @@ -1,45 +1,62 @@ -.TH std::find_first_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::find_first_of \- std::find_first_of + .SH Synopsis Defined in header - template< class ForwardIt1, class ForwardIt2 > - - ForwardIt1 find_first_of( ForwardIt1 first, - ForwardIt1 last, \fI(until C++11)\fP - - ForwardIt2 s_first, - ForwardIt2 s_last ); template< class InputIt, class ForwardIt > - InputIt find_first_of( InputIt first, InputIt - last, \fI(since C++11)\fP + InputIt find_first_of( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) - ForwardIt s_first, - ForwardIt s_last ); - template< class ForwardIt1, class ForwardIt2, \fB(1)\fP - class BinaryPredicate > + ForwardIt s_first, ForwardIt + s_last ); + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > - ForwardIt1 find_first_of( ForwardIt1 first, \fI(until C++11)\fP - ForwardIt1 last, + ForwardIt1 find_first_of( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 \fB(2)\fP \fI(since C++17)\fP + last, - ForwardIt2 s_first, - ForwardIt2 s_last, BinaryPredicate p ); \fB(2)\fP + ForwardIt2 s_first, ForwardIt2 + s_last ); template< class InputIt, class ForwardIt, class - BinaryPredicate > + BinaryPred > - InputIt find_first_of( InputIt first, InputIt \fI(since C++11)\fP + InputIt find_first_of( InputIt first, InputIt last, \fB(3)\fP (constexpr since C++20) + ForwardIt s_first, ForwardIt + s_last, + + BinaryPred p ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + BinaryPred > + ForwardIt1 find_first_of( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt \fB(4)\fP \fI(since C++17)\fP last, + ForwardIt2 s_first, ForwardIt2 + s_last, + + BinaryPred p ); - ForwardIt s_first, - ForwardIt s_last, BinaryPredicate p ); + Searches the range [first, last) for any of the elements in the range + [s_first, s_last). - Searches the range [first, last) for any of the elements in the range [s_first, - s_last). The first version uses operator== to compare the elements, the second - version uses the given binary predicate p. + 1) Elements are compared using operator==. + 3) Elements are compared using the given binary predicate p. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine s_first, s_last - the range of elements to search for + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -47,61 +64,76 @@ the following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must - not modify the objects passed to it. + + p - While the signature does not need to have const &, the function + must not modify the objects passed to it and must be able to + accept all values of type (possibly const) Type1 and Type2 + regardless of value category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types ForwardIt1 and ForwardIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. - - .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - ForwardIt1 must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. - - ForwardIt2 must meet the requirements of ForwardIterator. + ForwardIt1 must meet the requirements of LegacyForwardIterator. + - + ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + BinaryPred must meet the requirements of BinaryPredicate. .SH Return value Iterator to the first element in the range [first, last) that is equal to an element - from the range [s_first; s_last). If no such element is found, last is returned. + from the range [s_first, s_last). + + If [s_first, s_last) is empty or if no such element is found, last is returned. .SH Complexity - Does at most (S*N) comparisons where S = distance(s_first, s_last) and N = - distance(first, last). + Given \\(\\scriptsize N\\)N as std::distance(first, last) and \\(\\scriptsize S\\)S as + std::distance(s_first, s_last): + + 1,2) At most \\(\\scriptsize N\\cdot S\\)N·S comparisons using operator==. + 3,4) At most \\(\\scriptsize N\\cdot S\\)N·S applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + find_first_of \fB(1)\fP template InputIt find_first_of(InputIt first, InputIt last, ForwardIt s_first, ForwardIt s_last) { - for (; first != last; ++first) { - for (ForwardIt it = s_first; it != s_last; ++it) { - if (*first == *it) { + for (; first != last; ++first) + for (ForwardIt it = s_first; it != s_last; ++it) + if (*first == *it) return first; - } - } - } return last; } -.SH Second version - template + find_first_of \fB(3)\fP + template InputIt find_first_of(InputIt first, InputIt last, ForwardIt s_first, ForwardIt s_last, - BinaryPredicate p) + BinaryPred p) { - for (; first != last; ++first) { - for (ForwardIt it = s_first; it != s_last; ++it) { - if (p(*first, *it)) { + for (; first != last; ++first) + for (ForwardIt it = s_first; it != s_last; ++it) + if (p(*first, *it)) return first; - } - } - } return last; } @@ -109,35 +141,77 @@ The following code searches for any of specified integers in a vector of integers: - + // Run this code #include #include #include - - int main() + + auto print_sequence = [](const auto id, const auto& seq, int pos = -1) { - std::vector v{0, 2, 3, 25, 5}; - std::vector t{3, 19, 10, 2}; - - auto result = std::find_first_of(v.begin(), v.end(), t.begin(), t.end()); - - if (result == v.end()) { - std::cout << "no elements of v were equal to 3, 19, 10 or 2\\n"; - } else { - std::cout << "found a match at " - << std::distance(v.begin(), result) << "\\n"; + std::cout << id << "{ "; + for (int i{}; auto const& e : seq) + { + const bool mark{i == pos}; + std::cout << (i++ ? ", " : ""); + std::cout << (mark ? "[ " : "") << e << (mark ? " ]" : ""); } - } + std::cout << " }\\n"; + }; + + int main() + { + const std::vector v{0, 2, 3, 25, 5}; + const auto t1 = {19, 10, 3, 4}; + const auto t2 = {1, 6, 7, 9}; + + auto find_any_of = [](const auto& v, const auto& t) + { + const auto result = std::find_first_of(v.begin(), v.end(), + t.begin(), t.end()); + if (result == v.end()) + { + std::cout << "No elements of v are equal to any element of "; + print_sequence("t = ", t); + print_sequence("v = ", v); + } + else + { + const auto pos = std::distance(v.begin(), result); + std::cout << "Found a match (" << *result << ") at position " << pos; + print_sequence(", where t = ", t); + print_sequence("v = ", v, pos); + } + }; + + find_any_of(v, t1); + find_any_of(v, t2); + } .SH Output: - found a match at 1 + Found a match \fB(3)\fP at position 2, where t = { 19, 10, 3, 4 } + v = { 0, 2, [ 3 ], 25, 5 } + No elements of v are equal to any element of t = { 1, 6, 7, 9 } + v = { 0, 2, 3, 25, 5 } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 576 C++98 first and last needed to be they only need to be + LegacyForwardIterators LegacyInputIterators + LWG 1205 C++98 the return value was unclear if returns last in this case + [s_first, s_last) is empty .SH See also find - find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP \fI(C++11)\fP + ranges::find_first_of searches for any one of a set of elements + (C++20) (niebloid) diff --git a/man/std::find_if.3 b/man/std::find_if.3 deleted file mode 120000 index 1bc08435f..000000000 --- a/man/std::find_if.3 +++ /dev/null @@ -1 +0,0 @@ -std::find,std::find_if,std::find_if_not.3 \ No newline at end of file diff --git a/man/std::find_if.3 b/man/std::find_if.3 new file mode 100644 index 000000000..a4eedd11a --- /dev/null +++ b/man/std::find_if.3 @@ -0,0 +1,252 @@ +.TH std::find,std::find_if,std::find_if_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::find,std::find_if,std::find_if_not \- std::find,std::find_if,std::find_if_not + +.SH Synopsis + Defined in header + template< class InputIt, class T > (constexpr since + InputIt find( InputIt first, InputIt last, C++20) + const T& value ); (until C++26) + template< class InputIt, class T = + typename std::iterator_traits + + (since C++26) + ::value_type > + + constexpr InputIt find( InputIt first, + InputIt last, const T& value ); + template< class ExecutionPolicy, class + ForwardIt, class T > + \fI(since C++17)\fP + ForwardIt find( ExecutionPolicy&& policy, (until C++26) + + ForwardIt first, ForwardIt + last, const T& value ); + template< class ExecutionPolicy, + + class ForwardIt, class T = + typename std::iterator_traits + (since C++26) + ::value_type > + ForwardIt find( ExecutionPolicy&& policy, \fB(1)\fP + + ForwardIt first, ForwardIt + last, const T& value ); + template< class InputIt, class UnaryPred > (constexpr since + InputIt find_if( InputIt first, InputIt \fB(3)\fP C++20) + last, UnaryPred p ); \fB(2)\fP + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if( ExecutionPolicy&& \fB(4)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred p ); + template< class InputIt, class UnaryPred > \fI(since C++11)\fP + InputIt find_if_not( InputIt first, \fB(5)\fP (constexpr since + InputIt last, UnaryPred q ); C++20) + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if_not( ExecutionPolicy&& \fB(6)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred q ); + + Returns an iterator to the first element in the range [first, last) that satisfies + specific criteria (or last if there is no such iterator). + + 1) find searches for an element equal to value (using operator==). + 3) find_if searches for an element for which predicate p returns true. + 5) find_if_not searches for an element for which predicate q returns false. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of elements to examine + value - value to compare the elements to + policy - the execution policy to use. See execution policy for details. + unary predicate which returns true for the required element. + + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. + unary predicate which returns false for the required element. + + The expression q(v) must be convertible to bool for every argument v + q - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + UnaryPredicate must meet the requirements of Predicate. + +.SH Return value + + The first iterator it in the range [first, last) satisfying the following condition + or last if there is no such iterator: + + 1,2) *it == value is true. + 3,4) p(*it) is true. + 5,6) q(*it) is false. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize N\\)N comparisons with value using operator==. + 3,4) At most \\(\\scriptsize N\\)N applications of the predicate p. + 5,6) At most \\(\\scriptsize N\\)N applications of the predicate q. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + find + template::value_type> + constexpr InputIt find(InputIt first, InputIt last, const T& value) + { + for (; first != last; ++first) + if (*first == value) + return first; + + return last; + } + find_if + template + constexpr InputIt find_if(InputIt first, InputIt last, UnaryPred p) + { + for (; first != last; ++first) + if (p(*first)) + return first; + + return last; + } + find_if_not + template + constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) + { + for (; first != last; ++first) + if (!q(*first)) + return first; + + return last; + } + +.SH Notes + + If C++11 is not available, an equivalent to std::find_if_not is to use std::find_if + with the negated predicate. + + template + InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) + { + return std::find_if(first, last, std::not1(q)); + } + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + The following example finds numbers in given sequences. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + const auto v = {1, 2, 3, 4}; + + for (const int n : {3, 5}) + (std::find(v.begin(), v.end(), n) == std::end(v)) + ? std::cout << "v does not contain " << n << '\\n' + : std::cout << "v contains " << n << '\\n'; + + auto is_even = [](int i) { return i % 2 == 0; }; + + for (const auto& w : {std::array{3, 1, 4}, {1, 3, 5}}) + if (auto it = std::find_if(begin(w), end(w), is_even); it != std::end(w)) + std::cout << "w contains an even number " << *it << '\\n'; + else + std::cout << "w does not contain even numbers\\n"; + + std::vector> nums{{4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + // T gets deduced making list-initialization possible + const auto it = std::find(nums.begin(), nums.end(), {4, 2}); + #else + const auto it = std::find(nums.begin(), nums.end(), std::complex{4, 2}); + #endif + assert(it == nums.begin()); + } + +.SH Output: + + v contains 3 + v does not contain 5 + w contains an even number 4 + w does not contain even numbers + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, + LWG 283 C++98 but removed the requirement + the value type of InputIt might not be T + +.SH See also + + finds the first two adjacent items that are equal (or satisfy a + adjacent_find given predicate) + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + find_first_of searches for any one of a set of elements + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) diff --git a/man/std::find_if_not.3 b/man/std::find_if_not.3 deleted file mode 120000 index 1bc08435f..000000000 --- a/man/std::find_if_not.3 +++ /dev/null @@ -1 +0,0 @@ -std::find,std::find_if,std::find_if_not.3 \ No newline at end of file diff --git a/man/std::find_if_not.3 b/man/std::find_if_not.3 new file mode 100644 index 000000000..a4eedd11a --- /dev/null +++ b/man/std::find_if_not.3 @@ -0,0 +1,252 @@ +.TH std::find,std::find_if,std::find_if_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::find,std::find_if,std::find_if_not \- std::find,std::find_if,std::find_if_not + +.SH Synopsis + Defined in header + template< class InputIt, class T > (constexpr since + InputIt find( InputIt first, InputIt last, C++20) + const T& value ); (until C++26) + template< class InputIt, class T = + typename std::iterator_traits + + (since C++26) + ::value_type > + + constexpr InputIt find( InputIt first, + InputIt last, const T& value ); + template< class ExecutionPolicy, class + ForwardIt, class T > + \fI(since C++17)\fP + ForwardIt find( ExecutionPolicy&& policy, (until C++26) + + ForwardIt first, ForwardIt + last, const T& value ); + template< class ExecutionPolicy, + + class ForwardIt, class T = + typename std::iterator_traits + (since C++26) + ::value_type > + ForwardIt find( ExecutionPolicy&& policy, \fB(1)\fP + + ForwardIt first, ForwardIt + last, const T& value ); + template< class InputIt, class UnaryPred > (constexpr since + InputIt find_if( InputIt first, InputIt \fB(3)\fP C++20) + last, UnaryPred p ); \fB(2)\fP + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if( ExecutionPolicy&& \fB(4)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred p ); + template< class InputIt, class UnaryPred > \fI(since C++11)\fP + InputIt find_if_not( InputIt first, \fB(5)\fP (constexpr since + InputIt last, UnaryPred q ); C++20) + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt find_if_not( ExecutionPolicy&& \fB(6)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred q ); + + Returns an iterator to the first element in the range [first, last) that satisfies + specific criteria (or last if there is no such iterator). + + 1) find searches for an element equal to value (using operator==). + 3) find_if searches for an element for which predicate p returns true. + 5) find_if_not searches for an element for which predicate q returns false. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of elements to examine + value - value to compare the elements to + policy - the execution policy to use. See execution policy for details. + unary predicate which returns true for the required element. + + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. + unary predicate which returns false for the required element. + + The expression q(v) must be convertible to bool for every argument v + q - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + UnaryPredicate must meet the requirements of Predicate. + +.SH Return value + + The first iterator it in the range [first, last) satisfying the following condition + or last if there is no such iterator: + + 1,2) *it == value is true. + 3,4) p(*it) is true. + 5,6) q(*it) is false. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize N\\)N comparisons with value using operator==. + 3,4) At most \\(\\scriptsize N\\)N applications of the predicate p. + 5,6) At most \\(\\scriptsize N\\)N applications of the predicate q. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + find + template::value_type> + constexpr InputIt find(InputIt first, InputIt last, const T& value) + { + for (; first != last; ++first) + if (*first == value) + return first; + + return last; + } + find_if + template + constexpr InputIt find_if(InputIt first, InputIt last, UnaryPred p) + { + for (; first != last; ++first) + if (p(*first)) + return first; + + return last; + } + find_if_not + template + constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) + { + for (; first != last; ++first) + if (!q(*first)) + return first; + + return last; + } + +.SH Notes + + If C++11 is not available, an equivalent to std::find_if_not is to use std::find_if + with the negated predicate. + + template + InputIt find_if_not(InputIt first, InputIt last, UnaryPred q) + { + return std::find_if(first, last, std::not1(q)); + } + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + The following example finds numbers in given sequences. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + const auto v = {1, 2, 3, 4}; + + for (const int n : {3, 5}) + (std::find(v.begin(), v.end(), n) == std::end(v)) + ? std::cout << "v does not contain " << n << '\\n' + : std::cout << "v contains " << n << '\\n'; + + auto is_even = [](int i) { return i % 2 == 0; }; + + for (const auto& w : {std::array{3, 1, 4}, {1, 3, 5}}) + if (auto it = std::find_if(begin(w), end(w), is_even); it != std::end(w)) + std::cout << "w contains an even number " << *it << '\\n'; + else + std::cout << "w does not contain even numbers\\n"; + + std::vector> nums{{4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + // T gets deduced making list-initialization possible + const auto it = std::find(nums.begin(), nums.end(), {4, 2}); + #else + const auto it = std::find(nums.begin(), nums.end(), std::complex{4, 2}); + #endif + assert(it == nums.begin()); + } + +.SH Output: + + v contains 3 + v does not contain 5 + w contains an even number 4 + w does not contain even numbers + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, + LWG 283 C++98 but removed the requirement + the value type of InputIt might not be T + +.SH See also + + finds the first two adjacent items that are equal (or satisfy a + adjacent_find given predicate) + \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + find_first_of searches for any one of a set of elements + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) diff --git a/man/std::fisher_f_distribution.3 b/man/std::fisher_f_distribution.3 index 5fa6edf14..223f5b8ca 100644 --- a/man/std::fisher_f_distribution.3 +++ b/man/std::fisher_f_distribution.3 @@ -1,13 +1,17 @@ -.TH std::fisher_f_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution \- std::fisher_f_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP class fisher_f_distribution; - The fisher_f_distribution class is a RandomNumberDistribution that produces random - numbers according to the f-distribution: + Produces random numbers according to the F-distribution: - p(x;m,n) = + \\(P(x;m,n)=\\frac{\\Gamma{(\\frac{m+n}{2})} + }{\\Gamma{(\\frac{m}{2})}\\Gamma{(\\frac{n}{2})} }{(\\frac{m}{n})}^{\\frac{m}{2} + }x^{\\frac{m}{2}-1}{(1+\\frac{m}{n}x)}^{-\\frac{m+n}{2} }\\)P(x;m,n) = Γ((m+n)/2) Γ(m/2) Γ(n/2) @@ -21,49 +25,160 @@ )-(m+n)/2 - m and n are the degrees of freedom. + \\(\\small m\\)m and \\(\\small n\\)n are the degrees of freedom. + + std::fisher_f_distribution satisfies all requirements of RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics m returns the distribution parameters - n \fI(public member function)\fP + n \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - This section is incomplete - Reason: no example -.SH External links - - Weisstein, Eric W. "F-Distribution." From MathWorld--A Wolfram Web Resource. +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + void draw_vbars(Seq&& s, const bool DrawMinMax = true) + { + static_assert(0 < Height and 0 < BarWidth and 0 <= Padding and 0 <= Offset); + + auto cout_n = [](auto&& v, int n = 1) + { + while (n-- > 0) + std::cout << v; + }; + + const auto [min, max] = std::minmax_element(std::cbegin(s), std::cend(s)); + + std::vector qr; + for (typedef decltype(*std::cbegin(s)) V; V e : s) + qr.push_back(std::div(std::lerp(V(0), 8 * Height, + (e - *min) / (*max - *min)), 8)); + + for (auto h{Height}; h-- > 0; cout_n('\\n')) + { + cout_n(' ', Offset); + + for (auto dv : qr) + { + const auto q{dv.quot}, r{dv.rem}; + unsigned char d[]{0xe2, 0x96, 0x88, 0}; // Full Block: '█' + q < h ? d[0] = ' ', d[1] = 0 : q == h ? d[2] -= (7 - r) : 0; + cout_n(d, BarWidth), cout_n(' ', Padding); + } + + if (DrawMinMax && Height > 1) + Height - 1 == h ? std::cout << "┬ " << *max: + h ? std::cout << "│ " + : std::cout << "┴ " << *min; + } + } + + int main() + { + std::random_device rd{}; + std::mt19937 gen{rd()}; + + auto fisher = [&gen](const float d1, const float d2) + { + std::fisher_f_distribution d{d1 /* m */, d2 /* n */}; + + const int norm = 1'00'00; + const float cutoff = 0.002f; + + std::map hist{}; + for (int n = 0; n != norm; ++n) + ++hist[std::round(d(gen))]; + + std::vector bars; + std::vector indices; + for (auto const& [n, p] : hist) + if (float x = p * (1.0 / norm); cutoff < x) + { + bars.push_back(x); + indices.push_back(n); + } + + std::cout << "d₁ = " << d1 << ", d₂ = " << d2 << ":\\n"; + for (draw_vbars<4, 3>(bars); int n : indices) + std::cout << std::setw(2) << n << " "; + std::cout << "\\n\\n"; + }; + + fisher(/* d₁ = */ 1.0f, /* d₂ = */ 5.0f); + fisher(/* d₁ = */ 15.0f, /* d₂ = */ 10.f); + fisher(/* d₁ = */ 100.0f, /* d₂ = */ 3.0f); + } + +.SH Possible output: + + d₁ = 1, d₂ = 5: + ███ ┬ 0.4956 + ███ │ + ███ ▇▇▇ │ + ███ ███ ▇▇▇ ▄▄▄ ▂▂▂ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0021 + 0 1 2 3 4 5 6 7 8 9 10 11 12 14 + + d₁ = 15, d₂ = 10: + ███ ┬ 0.6252 + ███ │ + ███ ▂▂▂ │ + ▆▆▆ ███ ███ ▃▃▃ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0023 + 0 1 2 3 4 5 6 + + d₁ = 100, d₂ = 3: + ███ ┬ 0.4589 + ███ │ + ▁▁▁ ███ ▅▅▅ │ + ███ ███ ███ ▆▆▆ ▃▃▃ ▂▂▂ ▂▂▂ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ▁▁▁ ┴ 0.0021 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 -.SH Category: +.SH External links - * Todo no example + Weisstein, Eric W. "F-Distribution." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::fisher_f_distribution::fisher_f_distribution.3 b/man/std::fisher_f_distribution::fisher_f_distribution.3 index 0a0a26d91..3f24c67db 100644 --- a/man/std::fisher_f_distribution::fisher_f_distribution.3 +++ b/man/std::fisher_f_distribution::fisher_f_distribution.3 @@ -1,15 +1,27 @@ -.TH std::fisher_f_distribution::fisher_f_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::fisher_f_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::fisher_f_distribution \- std::fisher_f_distribution::fisher_f_distribution + .SH Synopsis - explicit fisher_f_distribution( RealType m = 1.0, RealType n = 1.0 \fB(1)\fP \fI(since C++11)\fP - ); - explicit fisher_f_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + fisher_f_distribution() : fisher_f_distribution(1.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit fisher_f_distribution( RealType m, RealType n = 1.0 ); \fB(2)\fP \fI(since C++11)\fP + explicit fisher_f_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses m and n as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses m and n as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters m - the m distribution parameter (degrees of freedom) n - the n distribution parameter (degrees of freedom) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::fisher_f_distribution::m,n.3 b/man/std::fisher_f_distribution::m,n.3 index 8f9ead30f..6b25031a9 100644 --- a/man/std::fisher_f_distribution::m,n.3 +++ b/man/std::fisher_f_distribution::m,n.3 @@ -1,4 +1,7 @@ -.TH std::fisher_f_distribution::m,n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::m,n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::m,n \- std::fisher_f_distribution::m,n + .SH Synopsis RealType m() const; \fB(1)\fP \fI(since C++11)\fP RealType n() const; \fB(2)\fP \fI(since C++11)\fP @@ -25,5 +28,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::fisher_f_distribution::max.3 b/man/std::fisher_f_distribution::max.3 index 22a6ccb7c..6b04aa802 100644 --- a/man/std::fisher_f_distribution::max.3 +++ b/man/std::fisher_f_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::fisher_f_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::max \- std::fisher_f_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::fisher_f_distribution::min.3 b/man/std::fisher_f_distribution::min.3 index 924e86c5d..6fd56e653 100644 --- a/man/std::fisher_f_distribution::min.3 +++ b/man/std::fisher_f_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::fisher_f_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::min \- std::fisher_f_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::fisher_f_distribution::operator().3 b/man/std::fisher_f_distribution::operator().3 index 99e338e06..97d73da6e 100644 --- a/man/std::fisher_f_distribution::operator().3 +++ b/man/std::fisher_f_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::fisher_f_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::operator() \- std::fisher_f_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::fisher_f_distribution::param.3 b/man/std::fisher_f_distribution::param.3 index 5569e45a6..9c6e0fc0b 100644 --- a/man/std::fisher_f_distribution::param.3 +++ b/man/std::fisher_f_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::fisher_f_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::param \- std::fisher_f_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::fisher_f_distribution::reset.3 b/man/std::fisher_f_distribution::reset.3 index 0e30ee9c5..06956bc3a 100644 --- a/man/std::fisher_f_distribution::reset.3 +++ b/man/std::fisher_f_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::fisher_f_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fisher_f_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fisher_f_distribution::reset \- std::fisher_f_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::fixed,std::scientific,std::hexfloat,std::defaultfloat.3 b/man/std::fixed,std::scientific,std::hexfloat,std::defaultfloat.3 index 3b9da939e..cf7aadc51 100644 --- a/man/std::fixed,std::scientific,std::hexfloat,std::defaultfloat.3 +++ b/man/std::fixed,std::scientific,std::hexfloat,std::defaultfloat.3 @@ -1,4 +1,7 @@ -.TH std::fixed,std::scientific,std::hexfloat,std::defaultfloat 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fixed,std::scientific,std::hexfloat,std::defaultfloat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fixed,std::scientific,std::hexfloat,std::defaultfloat \- std::fixed,std::scientific,std::hexfloat,std::defaultfloat + .SH Synopsis Defined in header std::ios_base& fixed( std::ios_base& str ); \fB(1)\fP @@ -6,12 +9,12 @@ std::ios_base& hexfloat( std::ios_base& str ); \fB(3)\fP \fI(since C++11)\fP std::ios_base& defaultfloat( std::ios_base& str ); \fB(4)\fP \fI(since C++11)\fP - Modifies the default formatting for floating-point input/output. + Modifies the default formatting for floating-point output. 1) Sets the floatfield of the stream str to fixed as if by calling - str.setf(std::ios_base::fixed, std::ios_base::floatfield) + str.setf(std::ios_base::fixed, std::ios_base::floatfield). 2) Sets the floatfield of the stream str to scientific as if by calling - str.setf(std::ios_base::scientific, std::ios_base::floatfield) + str.setf(std::ios_base::scientific, std::ios_base::floatfield). 3) Sets the floatfield of the stream str to fixed and scientific simultaneously as if by calling str.setf(std::ios_base::fixed | std::ios_base::scientific, std::ios_base::floatfield). This enables hexadecimal floating-point formatting. @@ -20,8 +23,8 @@ formatting, which is different from fixed and scientific. This is an I/O manipulator, it may be called with an expression such as out << - std::fixed for any out of type std::basic_ostream or with an expression such as in - >> std::scientific for any in of type std::basic_istream. + std::fixed for any out of type std::basic_ostream (or with an expression such as in + >> std::scientific for any in of type std::basic_istream). .SH Parameters @@ -29,36 +32,86 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). + +.SH Notes + + Hexadecimal floating-point formatting ignores the stream precision specification, as + required by the specification of std::num_put::do_put. + + These manipulators do not affect floating-point parsing. .SH Example - + // Run this code + #include #include #include - + + enum class cap { title, middle, end }; + + void print(const char* text, double num, cap c) + { + if (c == cap::title) + std::cout << + "┌──────────┬────────────┬──────────────────────────┐\\n" + "│ number │ iomanip │ representation │\\n" + "├──────────┼────────────┼──────────────────────────┤\\n"; + std::cout << std::left + << "│ " << std::setw(8) << text << " │ fixed │ " + << std::setw(24) << std::fixed << num << " │\\n" + << "│ " << std::setw(8) << text << " │ scientific │ " + << std::setw(24) << std::scientific << num << " │\\n" + << "│ " << std::setw(8) << text << " │ hexfloat │ " + << std::setw(24) << std::hexfloat << num << " │\\n" + << "│ " << std::setw(8) << text << " │ default │ " + << std::setw(24) << std::defaultfloat << num << " │\\n"; + std::cout << (c != cap::end ? + "├──────────┼────────────┼──────────────────────────┤\\n" : + "└──────────┴────────────┴──────────────────────────┘\\n"); + } + int main() { - std::cout << "The number 0.01 in fixed: " << std::fixed << 0.01 << '\\n' - << "The number 0.01 in scientific: " << std::scientific << 0.01 << '\\n' - << "The number 0.01 in hexfloat: " << std::hexfloat << 0.01 << '\\n' - << "The number 0.01 in default: " << std::defaultfloat << 0.01 << '\\n'; + print("0.0", 0.0, cap::title); + print("0.01", 0.01, cap::middle); + print("0.00001", 0.00001, cap::end); + + // Note; choose clang for correct output double f; - std::istringstream("0x1P-1022") >> std::hexfloat >> f; - std::cout << "Parsing 0x1P-1022 as hex gives " << f << '\\n'; + std::istringstream("0x1.8p+0") >> f; + std::cout << "Parsing 0x1.8p+0 gives " << f << '\\n'; + + std::istringstream("0x1P-1022") >> f; + std::cout << "Parsing 0x1P-1022 gives " << f << '\\n'; } .SH Output: - The number 0.01 in fixed: 0.010000 - The number 0.01 in scientific: 1.000000e-02 - The number 0.01 in hexfloat: 0x1.47ae147ae147bp-7 - The number 0.01 in default: 0.01 - Parsing 0x1P-1022 as hex gives 2.22507e-308 + ┌──────────┬────────────┬──────────────────────────┐ + │ number │ iomanip │ representation │ + ├──────────┼────────────┼──────────────────────────┤ + │ 0.0 │ fixed │ 0.000000 │ + │ 0.0 │ scientific │ 0.000000e+00 │ + │ 0.0 │ hexfloat │ 0x0p+0 │ + │ 0.0 │ default │ 0 │ + ├──────────┼────────────┼──────────────────────────┤ + │ 0.01 │ fixed │ 0.010000 │ + │ 0.01 │ scientific │ 1.000000e-02 │ + │ 0.01 │ hexfloat │ 0x1.47ae147ae147bp-7 │ + │ 0.01 │ default │ 0.01 │ + ├──────────┼────────────┼──────────────────────────┤ + │ 0.00001 │ fixed │ 0.000010 │ + │ 0.00001 │ scientific │ 1.000000e-05 │ + │ 0.00001 │ hexfloat │ 0x1.4f8b588e368f1p-17 │ + │ 0.00001 │ default │ 1e-05 │ + └──────────┴────────────┴──────────────────────────┘ + Parsing 0x1.8p+0 gives 1.5 + Parsing 0x1P-1022 gives 2.22507e-308 .SH See also setprecision changes floating-point precision - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::flat_map.3 b/man/std::flat_map.3 new file mode 100644 index 000000000..792f0a5a1 --- /dev/null +++ b/man/std::flat_map.3 @@ -0,0 +1,229 @@ +.TH std::flat_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map \- std::flat_map + +.SH Synopsis + Defined in header + template< + + class Key, + class T, + class Compare = std::less, (since C++23) + class KeyContainer = std::vector, + class MappedContainer = std::vector + + > class flat_map; + + The flat map is a container adaptor that gives the functionality of an associative + container that contains key-value pairs with unique keys. Keys are sorted by using + the comparison function Compare. + + The class template flat_map acts as a wrapper to the two underlying containers, + passed as objects of type KeyContainer and MappedContainer respectively. The first + container is sorted, and for each key its corresponding value is in the second + container at the same index (offset). The number of elements in both containers is + the same. + + Everywhere the standard library uses the Compare requirements, uniqueness is + determined by using the equivalence relation. Informally, two objects a and b are + considered equivalent if neither compares less than the other: !comp(a, b) && + !comp(b, a). + + std::flat_map meets the requirements of Container, ReversibleContainer, optional + container requirements, and all requirements of AssociativeContainer (including + logarithmic search complexity), except that: + + * requirements related to nodes are not applicable, + * iterator invalidation requirements differ, + * the complexity of insertion and erasure operations is linear. + + A flat map supports most AssociativeContainer's operations that use unique keys. + +.SH Template parameters + + Key - The type of the keys. The program is ill-formed if Key is not the + same type as KeyContainer::value_type. + T - The type of mapped values. The program is ill-formed if T is not + the same type as MappedContainer::value_type. + Compare - A Compare type providing a strict weak ordering. + The types of the underlying SequenceContainer to store keys and + mapped values correspondingly. The iterators of such containers + should satisfy LegacyRandomAccessIterator or model + KeyContainer - random_access_iterator. Invocations of their member functions size + MappedContainer and max_size should not exit via an exception. + + The standard containers std::vector and std::deque satisfy these + requirements. + +.SH Member types + + Member type Definition + key_container_type KeyContainer + mapped_container_type MappedContainer + key_type Key + mapped_type T + value_type std::pair + key_compare Compare + reference std::pair + const_reference std::pair + size_type std::size_t + difference_type std::ptrdiff_t + iterator implementation-defined LegacyInputIterator and + random_access_iterator to value_type + const_iterator implementation-defined LegacyInputIterator and + random_access_iterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + type describing the underlying containers + + struct containers + containers { + key_container_type keys; + mapped_container_type values; + }; + +.SH Member classes + + value_compare compares objects of type value_type + \fI(class)\fP + +.SH Member objects + + Member name Definition + c (private) the object of type containers + (exposition-only member object*) + compare (private) the comparison function object of type key_compare + (exposition-only member object*) + +.SH Member functions + + constructor constructs the flat_map + \fI(public member function)\fP + destructor destroys every element of the container adaptor + (implicitly declared) \fI(public member function)\fP + operator= assigns values to the container adaptor + \fI(public member function)\fP +.SH Element access + at access specified element with bounds checking + \fI(public member function)\fP + operator[] access or insert specified element + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Capacity + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP +.SH Modifiers + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if + try_emplace the key exists + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + insert_range inserts a range of elements + \fI(public member function)\fP + inserts an element or assigns to the current element if the + insert_or_assign key already exists + \fI(public member function)\fP + extract extracts the underlying containers + \fI(public member function)\fP + replace replaces the underlying containers + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP +.SH Lookup + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + returns an iterator to the first element not less than the + lower_bound given key + \fI(public member function)\fP + returns an iterator to the first element greater than the + upper_bound given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP +.SH Observers + key_comp returns the function that compares keys + \fI(public member function)\fP + returns the function that compares keys in objects of type + value_comp value_type + \fI(public member function)\fP + keys direct access to the underlying keys container + \fI(public member function)\fP + values direct access to the underlying values container + \fI(public member function)\fP + +.SH Non-member functions + + operator== lexicographically compares the values of two flat_maps + operator<=> \fI(function template)\fP + (C++23) + std::swap(std::flat_map) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + erase_if(std::flat_map) erases all elements satisfying specific criteria + (C++23) \fI(function template)\fP + +.SH Helper classes + + std::uses_allocator specializes the std::uses_allocator type trait + (C++23) \fI(class template specialization)\fP + + Tags + + sorted_unique indicates that elements of a range are sorted and unique + sorted_unique_t (tag) + (C++23) + + Deduction guides + +.SH Notes + + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_flat_map 202207L (C++23) std::flat_map and std::flat_multimap + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + flat_multimap adapts two containers to provide a collection of key-value pairs, + (C++23) sorted by keys + \fI(class template)\fP + map collection of key-value pairs, sorted by keys, keys are unique + \fI(class template)\fP + unordered_map collection of key-value pairs, hashed by keys, keys are unique + \fI(C++11)\fP \fI(class template)\fP + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::flat_map::at.3 b/man/std::flat_map::at.3 new file mode 100644 index 000000000..900970e11 --- /dev/null +++ b/man/std::flat_map::at.3 @@ -0,0 +1,56 @@ +.TH std::flat_map::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::at \- std::flat_map::at + +.SH Synopsis + T& at( const Key& key ); \fB(1)\fP (since C++23) + const T& at( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + T& at( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const T& at( const K& x ) const; + + Returns a reference to the mapped value of the element with specified key. If no + such element exists, an exception of type std::out_of_range is thrown. + + 1,2) The key is equivalent to key. + 3,4) The key compares equivalent to the value x. The reference to the mapped value + is obtained as if by expression this->find(x)->second. + The expression this->find(x) must be well-formed and have well-defined behavior, + otherwise the behavior is undefined. + These overloads participate in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - the key of the element to find + x - a value of any type that can be transparently compared with a key + +.SH Return value + + A reference to the mapped value of the requested element. + +.SH Exceptions + + 1,2) std::out_of_range if the container does not have an element with the specified + key. + 3,4) std::out_of_range if the container does not have the specified element, that + is, if find(x) == end() is true. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] access or insert specified element + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_map::begin,.3 b/man/std::flat_map::begin,.3 new file mode 100644 index 000000000..c4e712316 --- /dev/null +++ b/man/std::flat_map::begin,.3 @@ -0,0 +1,65 @@ +.TH std::flat_map::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::begin, \- std::flat_map::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP (since C++23) + const_iterator begin() const noexcept; \fB(2)\fP (since C++23) + const_iterator cbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the first element of the flat_map. + + If the flat_map is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_map map{{4, 4.13}, {9, 9.24}, {1, 1.09}}; + + for (auto it = map.cbegin(); it != map.cend(); ++it) + std::cout << '[' << it->first << "] = " << it->second << '\\n'; + + // Unlike std::map's bidirectional iterators, the std::flat_map iterators + // are random-access, so they can be used with the operator[]: + auto it = map.cbegin(); + assert(it[0] == map[1]); + assert(it[1] == map[4]); + assert(it[2] == map[9]); + } + +.SH Output: + + [1] = 1.09 + [4] = 4.13 + [9] = 9.24 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_map::clear.3 b/man/std::flat_map::clear.3 new file mode 100644 index 000000000..bb4a63bff --- /dev/null +++ b/man/std::flat_map::clear.3 @@ -0,0 +1,61 @@ +.TH std::flat_map::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::clear \- std::flat_map::clear + +.SH Synopsis + void clear() noexcept; (since C++23) + + Erases all elements from the container adaptor. After this call, size() returns + zero. + + Invalidates any references, pointers, and iterators referring to contained elements. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the size of the container adaptor, i.e., the number of elements. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::flat_map& v) + { + std::cout << rem << "{ "; + for (const auto& [key, value] : v) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::flat_map container{{1, 'x'}, {2, 'y'}, {3, 'z'}}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { [1]:x [2]:y [3]:z } + Size=3 + After clear: { } + Size=0 + +.SH See also + + erase erases elements + \fI(public member function)\fP diff --git a/man/std::flat_map::contains.3 b/man/std::flat_map::contains.3 new file mode 100644 index 000000000..f1569b44a --- /dev/null +++ b/man/std::flat_map::contains.3 @@ -0,0 +1,60 @@ +.TH std::flat_map::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::contains \- std::flat_map::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_map example{{1, 'a'}, {2, 'b'}}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_map::count.3 b/man/std::flat_map::count.3 new file mode 100644 index 000000000..89a0aa7fd --- /dev/null +++ b/man/std::flat_map::count.3 @@ -0,0 +1,48 @@ +.TH std::flat_map::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::count \- std::flat_map::count + +.SH Synopsis + size_type count( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + size_type count( const K& x ) const; + + Returns the number of elements with key that compares equivalent to the specified + argument. + + 1) Returns the number of elements with key key. This is either 1 or 0 since this + container does not allow duplicates. + 2) Returns the number of elements with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the elements to count + x - alternative value to compare to the keys + +.SH Return value + + Number of elements with key that compares equivalent to key or x, which, for + overload \fB(1)\fP, is either 1 or 0. + +.SH Complexity + + Logarithmic in the size of the container plus linear in the number of elements + found. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_map::emplace.3 b/man/std::flat_map::emplace.3 new file mode 100644 index 000000000..f0c77eb50 --- /dev/null +++ b/man/std::flat_map::emplace.3 @@ -0,0 +1,100 @@ +.TH std::flat_map::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::emplace \- std::flat_map::emplace + +.SH Synopsis + template< class... Args > (since C++23) + std::pair emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args, + if there is no element with the key in the container. + + Initializes an object t of type std::pair with + std::forward(args)...; if the map already contains an element whose key is + equivalent to t.first, *this is unchanged. Otherwise, equivalent to: + + auto key_it = ranges::upper_bound(c.keys, t.first, compare); + auto value_it = c.values.begin() + std::distance(c.keys.begin(), key_it); + c.keys.insert(key_it, std::move(t.first)); + c.values.insert(value_it, std::move(t.second)); + + This overload participates in overload resolution only if + std::is_constructible_v, Args...> is true. + + Careful use of emplace allows the new element to be constructed while avoiding + unnecessary copy or move operations. + + Information on iterator invalidation is copied from here + +.SH Parameters + + args - arguments to forward to the constructor of the element + +.SH Return value + + A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + If insertion occurs, linear in the size of the container, otherwise logarithmic in + the size of the container + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_map m; + + // uses pair's move constructor + m.emplace(std::make_pair(std::string("a"), std::string("a"))); + + // uses pair's converting move constructor + m.emplace(std::make_pair("b", "abcd")); + + // uses pair's template constructor + m.emplace("d", "ddd"); + + // emplace with duplicate key has no effect + m.emplace("d", "DDD"); + + // uses pair's piecewise constructor + m.emplace(std::piecewise_construct, + std::forward_as_tuple("c"), + std::forward_as_tuple(10, 'c')); + // an alternative is: m.try_emplace("c", 10, 'c'); + + for (const auto& p : m) + std::cout << p.first << " => " << p.second << '\\n'; + } + +.SH Output: + + a => a + b => abcd + c => cccccccccc + d => ddd + +.SH See also + + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if the key + try_emplace exists + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP diff --git a/man/std::flat_map::emplace_hint.3 b/man/std::flat_map::emplace_hint.3 new file mode 100644 index 000000000..3cc9ec493 --- /dev/null +++ b/man/std::flat_map::emplace_hint.3 @@ -0,0 +1,139 @@ +.TH std::flat_map::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::emplace_hint \- std::flat_map::emplace_hint + +.SH Synopsis + template< class... Args > (since C++23) + iterator emplace_hint( const_iterator hint, Args&&... args ); + + Inserts a new element into the container as close as possible to the position just + before hint. + + The constructor of the element type (value_type, that is, std::pair) + is called with exactly the same arguments as supplied to the function, forwarded + with std::forward(args).... + + Information on iterator invalidation is copied from here + +.SH Parameters + + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + An iterator to the inserted element, or to the element that prevented the insertion. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + This section is incomplete + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const int n_operations = 100'500'0; + + std::size_t map_emplace() + { + std::flat_map map; + for (int i = 0; i < n_operations; ++i) + map.emplace(i, 'a'); + return map.size(); + } + + std::size_t map_emplace_hint() + { + std::flat_map map; + auto it = map.begin(); + for (int i = 0; i < n_operations; ++i) + { + map.emplace_hint(it, i, 'b'); + it = map.end(); + } + return map.size(); + } + + std::size_t map_emplace_hint_wrong() + { + std::flat_map map; + auto it = map.begin(); + for (int i = n_operations; i > 0; --i) + { + map.emplace_hint(it, i, 'c'); + it = map.end(); + } + return map.size(); + } + + std::size_t map_emplace_hint_corrected() + { + std::flat_map map; + auto it = map.begin(); + for (int i = n_operations; i > 0; --i) + { + map.emplace_hint(it, i, 'd'); + it = map.begin(); + } + return map.size(); + } + + std::size_t map_emplace_hint_closest() + { + std::flat_map map; + auto it = map.begin(); + for (int i = 0; i < n_operations; ++i) + it = map.emplace_hint(it, i, 'e'); + return map.size(); + } + + double time_it(std::function map_test, + std::string what = "", double ratio = 0.0) + { + const auto start = std::chrono::system_clock::now(); + const std::size_t map_size = map_test(); + const auto stop = std::chrono::system_clock::now(); + std::chrono::duration time = stop - start; + if (what.size() && map_size) + std::cout << std::setw(8) << time << " for " << what << " (ratio: " + << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\\n"; + return time.count(); + } + + int main() + { + std::cout << std::fixed << std::setprecision(2); + time_it(map_emplace); // cache warmup + const auto x = time_it(map_emplace, "plain emplace"); + time_it(map_emplace_hint, "emplace with correct hint", x); + time_it(map_emplace_hint_wrong, "emplace with wrong hint", x); + time_it(map_emplace_hint_corrected, "corrected emplace", x); + time_it(map_emplace_hint_closest, "emplace using returned iterator", x); + } + +.SH Possible output: + + ...TODO... + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + +.SH Category: + * Todo without reason diff --git a/man/std::flat_map::empty.3 b/man/std::flat_map::empty.3 new file mode 100644 index 000000000..92aa926ae --- /dev/null +++ b/man/std::flat_map::empty.3 @@ -0,0 +1,58 @@ +.TH std::flat_map::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::empty \- std::flat_map::empty + +.SH Synopsis + [[nodiscard]] bool empty() const noexcept; (since C++23) + + Checks if the underlying containers have no elements. Equivalent to return begin() + == end();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the underlying containers are empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses empty to check if a std::flat_map contains any + elements: + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_map numbers; + std::cout << std::boolalpha; + std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; + + numbers.emplace(42, 13); + numbers.insert(std::make_pair(13317, 123)); + std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; + } + +.SH Output: + + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false + +.SH See also + + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::flat_map::end,.3 b/man/std::flat_map::end,.3 new file mode 100644 index 000000000..ce41adbac --- /dev/null +++ b/man/std::flat_map::end,.3 @@ -0,0 +1,66 @@ +.TH std::flat_map::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::end, \- std::flat_map::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP (since C++23) + const_iterator end() const noexcept; \fB(2)\fP (since C++23) + const_iterator cend() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the element following the last element of the flat_map. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_map map{{4, 4.13}, {9, 9.24}, {1, 1.09}}; + + for (auto it = map.cbegin(); it != map.cend(); ++it) + std::cout << '[' << it->first << "] = " << it->second << '\\n'; + + // Unlike std::map's bidirectional iterators, the std::flat_map iterators + // are random-access, so they can be used with the operator[]: + auto it = map.cbegin(); + assert(it[0] == map[1]); + assert(it[1] == map[4]); + assert(it[2] == map[9]); + } + +.SH Output: + + [1] = 1.09 + [4] = 4.13 + [9] = 9.24 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_map::equal_range.3 b/man/std::flat_map::equal_range.3 new file mode 100644 index 000000000..23d7c1217 --- /dev/null +++ b/man/std::flat_map::equal_range.3 @@ -0,0 +1,116 @@ +.TH std::flat_map::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::equal_range \- std::flat_map::equal_range + +.SH Synopsis + std::pair equal_range( const Key& key ); \fB(1)\fP (since C++23) + std::pair equal_range( const Key& \fB(2)\fP (since C++23) + key ) const; + template< class K > \fB(3)\fP (since C++23) + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP (since C++23) + ) const; + + Returns a range containing all elements with the given key in the container. The + range is defined by two iterators, one pointing to the first element that is not + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). + + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + std::pair containing a pair of iterators defining the wanted range: the first + pointing to the first element that is not less than key and the second pointing to + the first element greater than key. + + If there are no elements not less than key, past-the-end (see end()) iterator is + returned as the first element. Similarly if there are no elements greater than key, + past-the-end iterator is returned as the second element. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::flat_map m + { + {0, "zero"}, + {1, "one"}, + {2, "two"} + }; + + auto p = m.equal_range(1); + for (auto& q = p.first; q != p.second; ++q) + std::cout << "m[" << q->first << "] = " << q->second << '\\n'; + + if (p.second == m.find(2)) + std::cout << "end of equal_range (p.second) is one-past p.first\\n"; + else + std::cout << "unexpected; p.second expected to be one-past p.first\\n"; + + auto pp = m.equal_range(-1); + if (pp.first == m.begin()) + std::cout << "pp.first is iterator to first not-less than -1\\n"; + else + std::cout << "unexpected pp.first\\n"; + + if (pp.second == m.begin()) + std::cout << "pp.second is iterator to first element greater-than -1\\n"; + else + std::cout << "unexpected pp.second\\n"; + + auto ppp = m.equal_range(3); + if (ppp.first == m.end()) + std::cout << "ppp.first is iterator to first not-less than 3\\n"; + else + std::cout << "unexpected ppp.first\\n"; + + if (ppp.second == m.end()) + std::cout << "ppp.second is iterator to first element greater-than 3\\n"; + else + std::cout << "unexpected ppp.second\\n"; + } + +.SH Output: + + m[1] = one + end of equal_range (p.second) is one-past p.first + pp.first is iterator to first not-less than -1 + pp.second is iterator to first element greater-than -1 + ppp.first is iterator to first not-less than 3 + ppp.second is iterator to first element greater-than 3 + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::flat_map::erase.3 b/man/std::flat_map::erase.3 new file mode 100644 index 000000000..9c5f23773 --- /dev/null +++ b/man/std::flat_map::erase.3 @@ -0,0 +1,96 @@ +.TH std::flat_map::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::erase \- std::flat_map::erase + +.SH Synopsis + iterator erase( iterator position ); \fB(1)\fP (since C++23) + iterator erase( const_iterator pos ); \fB(2)\fP (since C++23) + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP (since C++23) + size_type erase( const Key& key ); \fB(4)\fP (since C++23) + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. + + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes the element (if one exists) with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. + + Information on iterator invalidation is copied from here + + The iterator pos must be valid and dereferenceable. Thus the end() iterator (which + is valid, but is not dereferenceable) cannot be used as a value for pos. + +.SH Parameters + + pos - iterator to the element to remove + first, last - range of elements to remove + key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove + +.SH Return value + + 1-3) Iterator following the last removed element. + 4) Number of elements removed (0 or 1). + 5) Number of elements removed. + +.SH Exceptions + + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. + +.SH Complexity + + Depends on underlying containers. Typically linear. + + This section is incomplete + Reason: revision required + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_map c = + { + {1, "one"}, {2, "two"}, {3, "three"}, + {4, "four"}, {5, "five"}, {6, "six"} + }; + + // erase all odd numbers from c + for (auto it = c.begin(); it != c.end();) + { + if (it->first % 2 != 0) + it = c.erase(it); + else + ++it; + } + + for (auto& p : c) + std::cout << p.second << ' '; + std::cout << '\\n'; + } + +.SH Output: + + two four six + +.SH See also + + clear clears the contents + \fI(public member function)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::flat_map::extract.3 b/man/std::flat_map::extract.3 new file mode 100644 index 000000000..5220f735d --- /dev/null +++ b/man/std::flat_map::extract.3 @@ -0,0 +1,63 @@ +.TH std::flat_map::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::extract \- std::flat_map::extract + +.SH Synopsis + containers extract() &&; (since C++23) + + Extracts adapted containers c. Equivalent to return std::move(c);. + + After this operation *this is empty, even if an exception is thrown. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + std::move(c). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::flat_map map{{1, 1.1}, {2, 2.2}, {3, 3.3}}; + const auto size = map.size(); + + auto c = map.extract(); + assert(c.keys.size() == size); + assert(c.values.size() == size); + assert(map.empty()); + assert(map.keys().empty()); + assert(map.values().empty()); + + // The default keys and values containers are std::vector: + static_assert(std::is_same_v>); + static_assert(std::is_same_v>); + + std::println("keys: {}", c.keys); + std::println("values: {}", c.values); + } + +.SH Output: + + keys: [1, 2, 3] + values: [1.1, 2.2, 3.3] + +.SH See also + + replace replaces the underlying containers + \fI(public member function)\fP diff --git a/man/std::flat_map::find.3 b/man/std::flat_map::find.3 new file mode 100644 index 000000000..801f88b48 --- /dev/null +++ b/man/std::flat_map::find.3 @@ -0,0 +1,103 @@ +.TH std::flat_map::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::find \- std::flat_map::find + +.SH Synopsis + iterator find( const Key& key ); \fB(1)\fP (since C++23) + const_iterator find( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator find( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator find( const K& x ) const; + + 1,2) Finds an element with key equivalent to key. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + + int main() + { + // Simple comparison demo. + std::flat_map example{{1,'a'}, {2,'b'}}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << search->first << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::flat_map> example2{{{1, {}}, 'a'}, {{2, {}}, 'b'}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Obtaining const iterators. + // Compiler decides whether to return iterator of (non) const type by way of + // accessing map; to prevent intentional modification, one of the simplest + // options is to access the map via a constant reference. + const auto& example2ref = example2; + if (auto search = example2ref.find(lk); search != example2.end()) + { + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + // search->second = 'c'; // error: assignment of member + // 'std::pair::second' + // in read-only object + } + } + +.SH Output: + + Found 2 b + Found 2 b + Found 2 b + +.SH See also + + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_map::flat_map.3 b/man/std::flat_map::flat_map.3 new file mode 100644 index 000000000..2d219070d --- /dev/null +++ b/man/std::flat_map::flat_map.3 @@ -0,0 +1,268 @@ +.TH std::flat_map::flat_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::flat_map \- std::flat_map::flat_map + +.SH Synopsis + flat_map() \fB(1)\fP (since C++23) + : flat_map(key_compare()) { } + template< class Allocator > \fB(2)\fP (since C++23) + flat_map( const flat_map&, const Allocator& alloc ); + template< class Allocator > \fB(3)\fP (since C++23) + flat_map( flat_map&&, const Allocator& alloc ); + flat_map( key_container_type key_cont, mapped_container_type + mapped_cont, \fB(4)\fP (since C++23) + const key_compare& comp = key_compare() ); + template< class Allocator > + + flat_map( const key_container_type& key_cont, \fB(5)\fP (since C++23) + const mapped_container_type& mapped_cont, + + const Allocator& alloc ); + template< class Allocator > + + flat_map( const key_container_type& key_cont, \fB(6)\fP (since C++23) + const mapped_container_type& mapped_cont, + + const key_compare& comp, const Allocator& alloc ); + flat_map( std::sorted_unique_t, key_container_type key_cont, + + mapped_container_type mapped_cont, \fB(7)\fP (since C++23) + + const key_compare& comp = key_compare() ); + template< class Allocator > + + flat_map( std::sorted_unique_t, const key_container_type& + key_cont, \fB(8)\fP (since C++23) + + const mapped_container_type& mapped_cont, const + Allocator& alloc ); + template< class Allocator > + + flat_map( std::sorted_unique_t, const key_container_type& + key_cont, \fB(9)\fP (since C++23) + const mapped_container_type& mapped_cont, + + const key_compare& comp, const Allocator& alloc ); + explicit flat_map( const key_compare& comp ) \fB(10)\fP (since C++23) + : c(), compare(comp) { } + template< class Allocator > \fB(11)\fP (since C++23) + flat_map( const key_compare& comp, const Allocator& alloc ); + template< class Allocator > \fB(12)\fP (since C++23) + explicit flat_map( const Allocator& alloc ); + template< class InputIter > + + flat_map( InputIter first, InputIter last, \fB(13)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(), compare(comp); + template< class InputIter, class Allocator > + + flat_map( InputIter first, InputIter last, \fB(14)\fP (since C++23) + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + flat_map( InputIter first, InputIter last, const Allocator& alloc \fB(15)\fP (since C++23) + ); + template< container-compatible-range R > + + flat_map( std::from_range_t, R&& rg, const key_compare& comp ) \fB(16)\fP (since C++23) + + : flat_map(comp); + template< container-compatible-range R > + + flat_map( std::from_range_t fr, R&& rg ) \fB(17)\fP (since C++23) + + : flat_map(fr, std::forward(rg), key_compare()) { } + template< container-compatible-range R, class + Allocator > \fB(18)\fP (since C++23) + flat_map( std::from_range_t, R&& rg, const Allocator& alloc ); + template< container-compatible-range R, class + Allocator > + \fB(19)\fP (since C++23) + flat_map( std::from_range_t, R&& rg, const key_compare& comp, + + const Allocator& alloc ); + template< class InputIter > + + flat_map( std::sorted_unique_t s, InputIter first, InputIter + last, \fB(20)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(), compare(comp); + template< class InputIter, class Allocator > + + flat_map( std::sorted_unique_t s, InputIter first, InputIter \fB(21)\fP (since C++23) + last, + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + + flat_map( std::sorted_unique_t s, InputIter first, InputIter \fB(22)\fP (since C++23) + last, + + const Allocator& alloc ); + flat_map( std::initializer_list init, + + const key_compare& comp = key_compare() ) \fB(23)\fP (since C++23) + + : flat_map(init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_map( std::initializer_list init, const \fB(24)\fP (since C++23) + key_compare& comp, + + const Allocator& alloc ); + template< class Allocator > + flat_map( std::initializer_list init, const \fB(25)\fP (since C++23) + Allocator& alloc ); + flat_map( std::sorted_unique_t s, + std::initializer_list init, + \fB(26)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : flat_map(s, init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_map( std::sorted_unique_t s, \fB(27)\fP (since C++23) + std::initializer_list init, + + const key_compare& comp, const Allocator& alloc ); + template< class Allocator > + + flat_map( std::sorted_unique_t s, \fB(28)\fP (since C++23) + std::initializer_list init, + + const Allocator& alloc ); + + Constructs new container adaptor from a variety of data sources and optionally using + user supplied comparison function object comp and/or allocator alloc. + + 1) A default constructor. Constructs an empty container adaptor. + 2) A copy constructor. Constructs c with the copy of the contents of other.c and + compare with other.compare. See allocator usage note below. + 3) A move constructor. Constructs the container adaptor with the contents of other + using move semantics. See allocator usage note below. + 4) First, initializes c.keys with std::move(key_cont), c.values with + std::move(mapped_cont), and compare with comp. Then sorts the underlying range + [begin(), end()) with respect to value_comp(). Finally, erases the duplicate + elements as if by: + auto zv = views::zip(c.keys, c.values); + auto it = ranges::unique(zv, key_equiv(compare)).begin(); + auto dist = distance(zv.begin(), it); + c.keys.erase(c.keys.begin() + dist, c.keys.end()); + c.values.erase(c.values.begin() + dist, c.values.end());. + 5) Same as \fB(4)\fP, equivalent to flat_map(key_cont, mapped_cont);. See allocator usage + note below. + 6) Same as \fB(4)\fP, equivalent to flat_map(key_cont, mapped_cont, comp);. See allocator + usage note below. + 7) Initializes c.keys with std::move(key_cont), c.values with + std::move(mapped_cont), and compare with comp. + 8) Same as \fB(7)\fP, equivalent to flat_map(s, key_cont, mapped_cont);. See allocator + usage note below. + 9) Same as \fB(7)\fP, equivalent to flat_map(s, key_cont, mapped_cont, comp);. See + allocator usage note below. + 10) Constructs an empty container adaptor. + 11,12) Constructs an empty container adaptor. See allocator usage note below. + 13) Constructs the container adaptor with the contents of the range [first, last), + equivalent to insert(first, last);. + 14,15) Same as \fB(13)\fP. See allocator usage note below. + 16) Constructs the container adaptor with the contents of the range rg. First, uses + \fB(10)\fP as delegating constructor. Then initializes c with the contents of rg as if by + insert_range(std::forward(rg));. + 17) Same as \fB(16)\fP using it as delegating constructor. + 18,19) Same as \fB(16)\fP. See allocator usage note below. + 20) Constructs the underlying containers with the contents of the range + [first, last) as if by insert(first, last). + 21,22) Same as \fB(20)\fP. See allocator usage note below. + 23) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(13)\fP as delegating constructor. + 24,25) Same as \fB(23)\fP. See allocator usage note below. + 26) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(20)\fP as delegating constructor. + 27,28) Save as \fB(26)\fP. See allocator usage note below. + + Note for overloads (13-15,20-22): If [first, last) is not a valid range, the + behavior is undefined. + + Note for overloads (4-6,13-19,23-25): If multiple elements in the range have keys + that compare equivalent, it is unspecified which element is inserted (pending + LWG2844). + +.SH Parameters + + key_cont - a container to be used as source to initialize the underlying keys + container + mapped_cont - a container to be used as source to initialize the underlying values + container + other - another flat_map to be used as source to initialize the elements of + the underlying containers with + alloc - an allocator to use for all memory allocations of the underlying + containers + comp - a function object to be used for all comparisons of keys + first, last - a range to copy the elements from + init - an initializer list to initialize the elements of the underlying + containers with + a container compatible range (that is, an input_range whose elements + rg - are convertible to value_type) to be used as source to initialize the + underlying containers + fr - a disambiguation tag that indicates that the contained member should + be range constructed + s - a disambiguation tag that indicates that the input sequence is sorted + with respect to value_comp() and all its elements are unique +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + Compare must meet the requirements of Compare. + - + Allocator must meet the requirements of Allocator. + +.SH Complexity + + 1) Constant. + 2) Linear in size of other. + 3) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 4-6) Linear in \\(\\scriptsize N\\)N if cont is sorted with respect to value_comp(), + otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of key_cont.size() before this call. + 7-9) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 10-12) Constant. + 13-15) Linear in \\(\\scriptsize N\\)N if the input range [first, last) is sorted with + respect to value_comp(), otherwise \\(\\scriptsize + \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where \\(\\scriptsize N\\)N is the value of + key_cont.size() before this call. + 16-19) Linear in \\(\\scriptsize N\\)N if the input range rg is sorted with respect to + value_comp(), otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), + where \\(\\scriptsize N\\)N is the value of key_cont.size() before this call. + 20-22) Linear in size of [first, last). + 23-25) Linear in \\(\\scriptsize N\\)N if the elements of init are sorted with respect + to value_comp(), otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), + where \\(\\scriptsize N\\)N is the value of key_cont.size() before this call. + 26-28) Linear in size of init. + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload \fB(3)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns values to the container adaptor + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_map::insert.3 b/man/std::flat_map::insert.3 new file mode 100644 index 000000000..c57633ba1 --- /dev/null +++ b/man/std::flat_map::insert.3 @@ -0,0 +1,163 @@ +.TH std::flat_map::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::insert \- std::flat_map::insert + +.SH Synopsis + std::pair insert( const value_type& value ); \fB(1)\fP (since C++23) + std::pair insert( value_type&& value ); \fB(2)\fP (since C++23) + iterator insert( const_iterator pos, const value_type& value ); \fB(3)\fP (since C++23) + iterator insert( const_iterator pos, value_type&& value ); \fB(4)\fP (since C++23) + template< class P > \fB(5)\fP (since C++23) + std::pair insert( P&& x ); + template< class P > \fB(6)\fP (since C++23) + iterator insert( const_iterator pos, P&& x ); + template< class InputIt > \fB(7)\fP (since C++23) + void insert( InputIt first, InputIt last ); + template< class InputIt > \fB(8)\fP (since C++23) + void insert( std::sorted_unique_t, InputIt first, InputIt last ); + void insert( std::initializer_list ilist ); \fB(9)\fP (since C++23) + void insert( std::sorted_unique_t s, \fB(10)\fP (since C++23) + std::initializer_list ilist ); + + Inserts element(s) into the container, if the container does not already contain an + element with an equivalent key. + + 1) Inserts value. Equivalent to return emplace(value);. + 2) Inserts value. Equivalent to return emplace(std::move(value));. + 3) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, value);. + 4) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, std::move(value));. + 5) If *this already contains an element which transparently compares equivalent to + x, does nothing. Otherwise, inserts x into *this as if by + emplace(std::forward

(x));. This overload participates in overload resolution only + if std::is_constructible_v, P> is true. + 6) If *this already contains an element which transparently compares equivalent to + x, does nothing. Otherwise, inserts x into *this in the position as close as + possible to the position just prior to pos. Equivalent to return + emplace_hint(position, std::forward

(x));. This overload participates in overload + resolution only if std::is_constructible_v, P> is true. + 7) Inserts elements from range [first, last) as if performing the following + operations sequentially: + 1. Adds elements to c as if by + for (; first != last; ++first) + { + value_type value = *first; + c.keys.insert(c.keys.end(), std::move(value.first)); + c.values.insert(c.values.end(), std::move(value.second)); + } + 2. Sorts the range of newly inserted elements with respect to value_comp. + 3. Merges the resulting sorted range and the sorted range of pre-existing elements + into a single sorted range. + 4. Erases the duplicate elements as if by: + auto zv = std::views::zip(c.keys, c.values); + auto it = ranges::unique(zv, key_equiv(compare)).begin(); + auto dist = std::distance(zv.begin(), it); + c.keys.erase(c.keys.begin() + dist, c.keys.end()); + c.values.erase(c.values.begin() + dist, c.values.end()); + May allocate memory during the in-place merge operation. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + 8) Inserts elements from range [first, last) as if performing the following + operations sequentially: + 1. Adds elements to c as if by + for (; first != last; ++first) + { + value_type value = *first; + c.keys.insert(c.keys.end(), std::move(value.first)); + c.values.insert(c.values.end(), std::move(value.second)); + } + 2. Merges the sorted range of newly added elements and the sorted range of + pre-existing elements into a single sorted range. + 3. Erases the duplicate elements as if by: + auto zv = std::views::zip(c.keys, c.values); + auto it = ranges::unique(zv, key_equiv(compare)).begin(); + auto dist = std::distance(zv.begin(), it); + c.keys.erase(c.keys.begin() + dist, c.keys.end()); + c.values.erase(c.values.begin() + dist, c.values.end()); + May allocate memory during the in-place merge operation. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + 9) Inserts elements from initializer list ilist. Equivalent to insert(ilist.begin(), + ilist.end());. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + 10) Inserts elements from initializer list ilist. Equivalent to insert(s, + ilist.begin(), ilist.end());. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + + Information on iterator invalidation is copied from here + +.SH Parameters + + pos - an iterator to the position before which the new element will be + inserted + value - an element value to insert + first, last - a range of elements to insert + ilist - an initializer list to insert the values from + x - a value of any type that can be transparently compared with a key + s - a disambiguation tag indicating that the input sequence is sorted + (with respect to value_comp()) and contains only unique elements +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1,2) A pair consisting of an iterator to the inserted element (or to the element + that prevented the insertion) and a bool value set to true if and only if the + insertion took place. + 3,4) An iterator to the inserted element, or to the element that prevented the + insertion. + 5) A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. + 6) An iterator to the inserted element, or to the element that prevented the + insertion. + 7-10) \fI(none)\fP + +.SH Exceptions + + 1-6) If an exception is thrown by any operation, the insertion has no effect. + + This section is incomplete + Reason: cases 7-10 + +.SH Complexity + + 1-6) Linear in size(). + 7) N + M·log(M), where N is the size() before the operation and M is + std::distance(first, last). + 8) Linear in size(). + 9) N + M·log(M), where N is the size() before the operation and M is ilist.size(). + 10) Linear in N, where N is size() after the operation. + +.SH Notes + + The hinted insert (3,4,6) does not return a boolean in order to be + signature-compatible with positional insert on sequential containers, such as + std::vector::insert. This makes it possible to create generic inserters such as + std::inserter. One way to check success of a hinted insert is to compare size() + before and after. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserts an element or assigns to the current element if the key + insert_or_assign already exists + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::flat_map::insert_or_assign.3 b/man/std::flat_map::insert_or_assign.3 new file mode 100644 index 000000000..55ce3b1ba --- /dev/null +++ b/man/std::flat_map::insert_or_assign.3 @@ -0,0 +1,123 @@ +.TH std::flat_map::insert_or_assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::insert_or_assign \- std::flat_map::insert_or_assign + +.SH Synopsis + template< class M > + std::pair insert_or_assign( const key_type& k, M&& \fB(1)\fP (since C++23) + obj ); + template< class M > + std::pair insert_or_assign( key_type&& k, M&& obj \fB(2)\fP (since C++23) + ); + template< class K, class M > \fB(3)\fP (since C++23) + std::pair insert_or_assign( K&& k, M&& obj ); + template< class M > + iterator insert_or_assign( const_iterator hint, const key_type& k, \fB(4)\fP (since C++23) + M&& obj ); + template< class M > + iterator insert_or_assign( const_iterator hint, key_type&& k, M&& \fB(5)\fP (since C++23) + obj ); + template< class K, class M > \fB(6)\fP (since C++23) + iterator insert_or_assign( const_iterator hint, K&& k, M&& obj ); + + 1,2) If a key equivalent to k already exists in the container, assigns + std::forward(obj) to the mapped_type corresponding to the key k. If the key does + not exist, inserts the new value as if by + * (1,2) try_emplace(std::forward(k), std::forward(obj)), + * (4,5) try_emplace(hint, std::forward(k), std::forward(obj)). + The program is ill-formed if either std::is_assignable_v or + std::is_constructible_v is false. + 3,6) If a key equivalent to k already exists in the container, assigns + std::forward(obj) to the mapped_type corresponding to the key k. Otherwise, + equivalent to + * \fB(3)\fP try_emplace(std::forward(k), std::forward(obj)), + * \fB(6)\fP try_emplace(hint, std::forward(k), std::forward(obj)). + The conversion from k into key_type must construct an object u, for which find(k) == + find(u) is true. Otherwise, the behavior is undefined. + These overloads participate in overload resolution only if : + * The qualified-id Compare::is_transparent is valid and denotes a type. + * std::is_constructible_v is true. + * std::is_assignable_v is true. + * std::is_constructible_v is true. + + Information on iterator invalidation is copied from here + +.SH Parameters + + k - the key used both to look up and to insert if not found + hint - iterator to the position before which the new element will be inserted + obj - the value to insert or assign + +.SH Return value + + 1-3) The bool component is true if the insertion took place and false if the + assignment took place. The iterator component is pointing at the element that was + inserted or updated. + 4-6) Iterator pointing at the element that was inserted or updated. + +.SH Complexity + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Notes + + insert_or_assign returns more information than operator[] and does not require + default-constructibility of the mapped type. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_node(const auto& node) + { + std::cout << '[' << node.first << "] = " << node.second << '\\n'; + } + + void print_result(auto const& pair) + { + std::cout << (pair.second ? "inserted: " : "assigned: "); + print_node(*pair.first); + } + + int main() + { + std::flat_map map; + + print_result(map.insert_or_assign("a", "apple")); + print_result(map.insert_or_assign("b", "banana")); + print_result(map.insert_or_assign("c", "cherry")); + print_result(map.insert_or_assign("c", "clementine")); + + for (const auto& node : map) + print_node(node); + } + +.SH Output: + + inserted: [a] = apple + inserted: [b] = banana + inserted: [c] = cherry + assigned: [c] = clementine + [a] = apple + [b] = banana + [c] = clementine + +.SH See also + + operator[] access or insert specified element + \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + emplace constructs element in-place + \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if the key + try_emplace exists + \fI(public member function)\fP diff --git a/man/std::flat_map::insert_range.3 b/man/std::flat_map::insert_range.3 new file mode 100644 index 000000000..6bebe9ef1 --- /dev/null +++ b/man/std::flat_map::insert_range.3 @@ -0,0 +1,85 @@ +.TH std::flat_map::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::insert_range \- std::flat_map::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg into underlying containers c as if + by: + + for (const auto& e : rg) + { + c.keys.insert(c.keys.end(), e.first); + c.values.insert(c.values.end(), e.second); + } + + Then, sorts the range of newly inserted elements with respect to value_comp(). + Merges the resulting sorted range and the sorted range of pre-existing elements into + a single sorted range. Finally, erases the duplicate elements as if by: + + auto zv = views::zip(c.keys, c.values); + auto it = ranges::unique(zv, key_equiv(compare)).begin(); + auto dist = std::distance(zv.begin(), it); + c.keys.erase(c.keys.begin() + dist, c.keys.end()); + c.values.erase(c.values.begin() + dist, c.values.end()); + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + Information on iterator invalidation is copied from here + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N + M·log(M), where N is size() before the operation and M is ranges::distance(rg). + +.SH Notes + + Since insert_range performs an in-place merge operation, that may allocate memory. + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto, auto const& container) + { + for (const auto& [key, value] : container) + std::cout << '{' << key << ',' << value << '}' << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::flat_map{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}}; + const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + {-2,-22} {-1,-11} {1,11} {2,22} {3,33} {4,44} + +.SH See also + + insert inserts elements + \fI(public member function)\fP diff --git a/man/std::flat_map::key_comp.3 b/man/std::flat_map::key_comp.3 new file mode 100644 index 000000000..b3cda8c05 --- /dev/null +++ b/man/std::flat_map::key_comp.3 @@ -0,0 +1,76 @@ +.TH std::flat_map::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::key_comp \- std::flat_map::key_comp + +.SH Synopsis + key_compare key_comp() const; (since C++23) + + Returns the function object that compares the keys, which is a copy of this + container's constructor argument comp. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The key comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_map cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.key_comp(); + + for (const auto it : cont) + { + const bool before = comp_func(it.first, 100); + const bool after = comp_func(100, it.first); + + std::cout << "Key (" << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + +.SH See also + + value_comp returns the function that compares keys in objects of type value_type + \fI(public member function)\fP diff --git a/man/std::flat_map::keys.3 b/man/std::flat_map::keys.3 new file mode 100644 index 000000000..1921e43ff --- /dev/null +++ b/man/std::flat_map::keys.3 @@ -0,0 +1,50 @@ +.TH std::flat_map::keys 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::keys \- std::flat_map::keys + +.SH Synopsis + const key_container_type& keys() const noexcept; (since C++23) + + Return a constant reference to the adapted keys container. Equivalent to return + c.keys;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying keys container. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_map adaptor{{1, 1.1}, {2, 2.2}, {3, 3.3}}; + + // The default keys container is std::vector: + static_assert(std::is_same_v&>); + + std::println("{}", adaptor.keys()); + } + +.SH Output: + + [1, 2, 3] + +.SH See also + + values direct access to the underlying values container + \fI(public member function)\fP diff --git a/man/std::flat_map::lower_bound.3 b/man/std::flat_map::lower_bound.3 new file mode 100644 index 000000000..ab36a54e4 --- /dev/null +++ b/man/std::flat_map::lower_bound.3 @@ -0,0 +1,47 @@ +.TH std::flat_map::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::lower_bound \- std::flat_map::lower_bound + +.SH Synopsis + iterator lower_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is not less than key. If no such element + is found, a past-the-end iterator (see end()) is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_map::max_size.3 b/man/std::flat_map::max_size.3 new file mode 100644 index 000000000..dda03a37c --- /dev/null +++ b/man/std::flat_map::max_size.3 @@ -0,0 +1,54 @@ +.TH std::flat_map::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::max_size \- std::flat_map::max_size + +.SH Synopsis + size_type max_size() const noexcept; (since C++23) + + Returns the maximum number of elements the container is able to hold due to system + or library implementation limitations. Equivalent to + std::min(c.keys.max_size(), c.values.max_size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of elements. + +.SH Complexity + + Constant. + +.SH Notes + + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the + container may be limited to a value smaller than max_size() by the amount of RAM + available. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_map q; + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "Maximum size of a std::flat_map is " << q.max_size() << '\\n'; + } + +.SH Possible output: + + Maximum size of a std::flat_map is 768,614,336,404,564,650 + +.SH See also + + size returns the number of elements + \fI(public member function)\fP diff --git a/man/std::flat_map::operator=.3 b/man/std::flat_map::operator=.3 new file mode 100644 index 000000000..feeb807bb --- /dev/null +++ b/man/std::flat_map::operator=.3 @@ -0,0 +1,92 @@ +.TH std::flat_map::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::operator= \- std::flat_map::operator= + +.SH Synopsis + flat_map& operator=( const flat_map& other ); \fB(1)\fP (since C++23) + (implicitly declared) + flat_map& operator=( flat_map&& other ); \fB(2)\fP (since C++23) + (implicitly declared) + flat_map& operator=( std::initializer_list \fB(3)\fP (since C++23) + ilist ); + + Replaces the contents of the container adaptor with the contents of given argument. + + 1) Copy assignment operator. Replaces the contents with a copy of the contents of + other. Effectively calls c = other.c; comp = other.comp;. + 2) Move assignment operator. Replaces the contents with those of other using move + semantics. Effectively calls c = std::move(other.c); comp = std::move(other.comp);. + 3) Replaces the contents with those identified by initializer list ilist. + +.SH Parameters + + other - another container adaptor to be used as source + ilist - initializer list to be used as source + +.SH Return value + + *this + +.SH Complexity + + 1,2) Equivalent to that of operator= of the underlying container. + 3) Linear in the size of *this and ilist. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_map x{{1, 1}, {2, 2}, {3, 3}}, y, z; + const auto w = {std::pair{4, 4}, {5, 5}, {6, 6}, {7, 7}}; + + std::println("Initially:"); + std::println("x = {}", x); + std::println("y = {}", y); + std::println("z = {}", z); + + y = x; // overload (1) + std::println("Copy assignment copies data from x to y:"); + std::println("x = {}", x); + std::println("y = {}", y); + + z = std::move(x); // overload (2) + std::println("Move assignment moves data from x to z, modifying both x and z:"); + std::println("x = {}", x); + std::println("z = {}", z); + + z = w; // overload (3) + std::println("Assignment of initializer_list w to z:"); + std::println("w = {}", w); + std::println("z = {}", z); + } + +.SH Output: + + Initially: + x = {1: 1, 2: 2, 3: 3} + y = {} + z = {} + Copy assignment copies data from x to y: + x = {1: 1, 2: 2, 3: 3} + y = {1: 1, 2: 2, 3: 3} + Move assignment moves data from x to z, modifying both x and z: + x = {} + z = {1: 1, 2: 2, 3: 3} + Assignment of initializer_list w to z: + w = {4: 4, 5: 5, 6: 6, 7: 7} + z = {4: 4, 5: 5, 6: 6, 7: 7} + +.SH See also + + constructor constructs the flat_map + \fI(public member function)\fP + replace replaces the underlying containers + \fI(public member function)\fP diff --git a/man/std::flat_map::operator[].3 b/man/std::flat_map::operator[].3 new file mode 100644 index 000000000..573c40d02 --- /dev/null +++ b/man/std::flat_map::operator[].3 @@ -0,0 +1,119 @@ +.TH std::flat_map::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::operator[] \- std::flat_map::operator[] + +.SH Synopsis + T& operator[]( const Key& key ); \fB(1)\fP (since C++23) + T& operator[]( Key&& key ); \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + T& operator[]( K&& x ); + + Returns a reference to the value that is mapped to a key equivalent to key or x + respectively, performing an insertion if such key does not already exist. + + 1) Inserts a value_type object constructed in-place if the key does not exist. + Equivalent to return try_emplace(x).first->second;. + 2) Inserts a value_type object constructed in-place if the key does not exist. + Equivalent to return try_emplace(std::move(x)).first->second; + 3) Inserts a value_type object constructed in-place if there is no key that + transparently compares equivalent to the value x. + Equivalent to return this->try_emplace(std::forward(x)).first->second;. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + + Information on iterator invalidation is copied from here + +.SH Parameters + + key - the key of the element to find + x - a value of any type that can be transparently compared with a key + +.SH Return value + + 1,2) A reference to the mapped value of the new element if no element with key key + existed. Otherwise, a reference to the mapped value of the existing element whose + key is equivalent to key. + 3) A reference to the mapped value of the new element if no element with key that + compares equivalent to the value x existed. Otherwise, a reference to the mapped + value of the existing element whose key compares equivalent to x. + +.SH Exceptions + + If an exception is thrown by any operation, the insertion has no effect. + +.SH Complexity + + Logarithmic in the size of the container, plus the cost of insertion (if any) of an + empty element. + +.SH Notes + + operator[] is non-const because it inserts the key if it doesn't exist. If this + behavior is undesirable or if the container is const, at may be used. + + insert_or_assign returns more information than operator[] and does not require + default-constructibility of the mapped type. + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto const comment, auto const& map) + { + std::cout << comment << '{'; + for (const auto& pair : map) + std::cout << '{' << pair.first << ": " << pair.second << '}'; + std::cout << "}\\n"; + } + + int main() + { + std::flat_map letter_counts{{'a', 27}, {'b', 3}, {'c', 1}}; + + println("letter_counts initially contains: ", letter_counts); + + letter_counts['b'] = 42; // updates an existing value + letter_counts['x'] = 9; // inserts a new value + + println("after modifications it contains: ", letter_counts); + + // count the number of occurrences of each word + // (the first call to operator[] initialized the counter with zero) + std::flat_map word_map; + for (const auto& w : {"this", "sentence", "is", "not", "a", "sentence", + "this", "sentence", "is", "a", "hoax"}) + ++word_map[w]; + word_map["that"]; // just inserts the pair {"that", 0} + + for (const auto& [word, count] : word_map) + std::cout << count << " occurrence(s) of word '" << word << "'\\n"; + } + +.SH Output: + + letter_counts initially contains: {{a: 27}{b: 3}{c: 1}} + after modifications it contains: {{a: 27}{b: 42}{c: 1}{x: 9}} + 2 occurrence(s) of word 'a' + 1 occurrence(s) of word 'hoax' + 2 occurrence(s) of word 'is' + 1 occurrence(s) of word 'not' + 3 occurrence(s) of word 'sentence' + 0 occurrence(s) of word 'that' + 2 occurrence(s) of word 'this' + +.SH See also + + at access specified element with bounds checking + \fI(public member function)\fP + inserts an element or assigns to the current element if the key + insert_or_assign already exists + \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if the key + try_emplace exists + \fI(public member function)\fP diff --git a/man/std::flat_map::rbegin,.3 b/man/std::flat_map::rbegin,.3 new file mode 100644 index 000000000..d27a24d28 --- /dev/null +++ b/man/std::flat_map::rbegin,.3 @@ -0,0 +1,77 @@ +.TH std::flat_map::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::rbegin, \- std::flat_map::rbegin, + +.SH Synopsis + + reverse_iterator rbegin() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rbegin() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the first element of the reversed flat_map. It + corresponds to the last element of the non-reversed flat_map. If the flat_map is + empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::flat_map coins + { + {10, "dime"}, + {100, "dollar"}, + {50, "half dollar"}, + {5, "nickel"}, + {1, "penny"}, + {25, "quarter"} + }; // initializer entries in name alphabetical order + + std::cout << "US coins in circulation, largest to smallest denomination:\\n"; + for (auto it = coins.crbegin(); it != coins.crend(); ++it) + std::cout << std::setw(11) << it->second << " = ¢" << it->first << '\\n'; + } + +.SH Output: + + US coins in circulation, largest to smallest denomination: + dollar = ¢100 + half dollar = ¢50 + quarter = ¢25 + dime = ¢10 + nickel = ¢5 + penny = ¢1 + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_map::rend,.3 b/man/std::flat_map::rend,.3 new file mode 100644 index 000000000..ed685e8cc --- /dev/null +++ b/man/std::flat_map::rend,.3 @@ -0,0 +1,82 @@ +.TH std::flat_map::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::rend, \- std::flat_map::rend, + +.SH Synopsis + + reverse_iterator rend() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rend() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crend() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the element following the last element of the reversed + flat_map. It corresponds to the element preceding the first element of the + non-reversed flat_map. This element acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono; + + int main() + { + const std::flat_map messages + { + {February/17/2023, 10}, + {February/17/2023, 20}, + {February/16/2022, 30}, + {October/22/2022, 40}, + {June/14/2022, 50}, + {November/23/2021, 60}, + {December/10/2022, 55}, + {December/12/2021, 45}, + {April/1/2020, 42}, + {April/1/2020, 24} + }; + + std::cout << "Messages received (date order is reversed):\\n"; + for (auto it = messages.crbegin(); it != messages.crend(); ++it) + std::cout << it->first << " : " << it->second << '\\n'; + } + +.SH Possible output: + + Messages received (date order is reversed): + 2023-02-17 : 10 + 2022-12-10 : 55 + 2022-10-22 : 40 + 2022-06-14 : 50 + 2022-02-16 : 30 + 2021-12-12 : 45 + 2021-11-23 : 60 + 2020-04-01 : 42 + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_map::replace.3 b/man/std::flat_map::replace.3 new file mode 100644 index 000000000..d35113ef7 --- /dev/null +++ b/man/std::flat_map::replace.3 @@ -0,0 +1,75 @@ +.TH std::flat_map::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::replace \- std::flat_map::replace + +.SH Synopsis + void replace( key_container_type&& key_cont, mapped_container_type&& (since C++23) + mapped_cont ); + + Replaces the underlying containers c. Equivalent to: + + c.keys = std::move(key_cont); + c.values = std::move(mapped_cont); + + The following conditions must be met: + + * The expression key_cont.size() == mapped_cont.size() is true, + * The elements of key_cont are sorted with respect to compare, and + * key_cont does not contain equal elements. + + Otherwise, the behavior is undefined. + +.SH Parameters + + keys_cont - a sorted keys container of type KeyContainer, the contents of which + will be moved into *this + mapped_cont - a container of mapped values of type MappedContainer, the contents of + which will be moved into *this + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Equals to complexity of std::move applied to adapted containers. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector keys{1, 2, 3}; + assert(std::ranges::is_sorted(keys)); + std::vector values{2.2, 3.3, 1.1}; + assert(keys.size() == values.size()); + + std::flat_map map; + assert(map.empty()); + + map.replace(keys, values); + assert(map.size() == 3); + assert(map.keys() == 3); + assert(map.values() == 3); + assert(keys.empty()); + assert(values.empty()); + + std::println("{}", map); + } + +.SH Output: + + {1: 2.2, 2: 3.3, 3: 1.1} + +.SH See also + + extract extracts the underlying containers + \fI(public member function)\fP diff --git a/man/std::flat_map::size.3 b/man/std::flat_map::size.3 new file mode 100644 index 000000000..ba141c442 --- /dev/null +++ b/man/std::flat_map::size.3 @@ -0,0 +1,55 @@ +.TH std::flat_map::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::size \- std::flat_map::size + +.SH Synopsis + size_type size() const noexcept; (since C++23) + + Returns the number of elements in the container adaptor. Equivalent to return + c.keys.size(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements in the container adaptor. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses size to display the number of elements in a std::flat_map: + + +// Run this code + + #include + #include + + int main() + { + std::flat_map nums{{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; + + std::cout << "nums contains " << nums.size() << " elements.\\n"; + } + +.SH Output: + + nums contains 4 elements. + +.SH See also + + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + max_size returns the maximum possible number of elements + \fI(public member function)\fP diff --git a/man/std::flat_map::swap.3 b/man/std::flat_map::swap.3 new file mode 100644 index 000000000..97ba59ed9 --- /dev/null +++ b/man/std::flat_map::swap.3 @@ -0,0 +1,42 @@ +.TH std::flat_map::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::swap \- std::flat_map::swap + +.SH Synopsis + void swap( flat_map& other ) noexcept; (since C++23) + + Exchanges the contents of the container adaptor with those of other. Effectively + calls + + ranges::swap(compare, other.compare); + ranges::swap(c.keys, other.c.keys); + ranges::swap(c.values, other.c.values); + +.SH Parameters + + other - container adaptor to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + \fI(none)\fP + +.SH Complexity + + Same as underlying container (typically constant). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::flat_map) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_map::try_emplace.3 b/man/std::flat_map::try_emplace.3 new file mode 100644 index 000000000..6cb9fb738 --- /dev/null +++ b/man/std::flat_map::try_emplace.3 @@ -0,0 +1,135 @@ +.TH std::flat_map::try_emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::try_emplace \- std::flat_map::try_emplace + +.SH Synopsis + template< class... Args > + std::pair try_emplace( const key_type& k, \fB(1)\fP (since C++23) + Args&&... args ); + template< class... Args > + std::pair try_emplace( key_type&& k, Args&&... \fB(2)\fP (since C++23) + args ); + template< class K, class... Args > \fB(3)\fP (since C++23) + std::pair try_emplace( K&& k, Args&&... args ); + template< class... Args > + iterator try_emplace( const_iterator hint, const key_type& k, \fB(4)\fP (since C++23) + Args&&... args ); + template< class... Args > + iterator try_emplace( const_iterator hint, key_type&& k, Args&&... \fB(5)\fP (since C++23) + args ); + template< class K, class... Args > + iterator try_emplace( const_iterator hint, K&& k, Args&&... args \fB(6)\fP (since C++23) + ); + + If a key equivalent to k already exists in the container, does nothing. Otherwise, + inserts a new element into the underlying containers c with key k and value + constructed with args. + + 1,2,4,5) Equivalent to: + + auto key_it = ranges::upper_bound(c.keys, k, compare); + auto value_it = c.values.begin() + std::distance(c.keys.begin(), key_it); + c.keys.insert(key_it, std::forward(k)); + c.values.emplace(value_it, std::forward(args)...); + + 3,6) Equivalent to: + + auto key_it = ranges::upper_bound(c.keys, k, compare); + auto value_it = c.values.begin() + std::distance(c.keys.begin(), key_it); + c.keys.emplace(key_it, std::forward(k)); + c.values.emplace(value_it, std::forward(args)...); + + The conversion from k into key_type must construct an object u, for which find(k) == + find(u) is true. Otherwise, the behavior is undefined. + These overloads participate in overload resolution only if : + * The qualified-id Compare::is_transparent is valid and denotes a type. + * std::is_constructible_v is true. + * std::is_assignable_v is true. + * For \fB(3)\fP only, std::is_convertible_v and + std::is_convertible_v are both false. + + Information on iterator invalidation is copied from here + +.SH Parameters + + k - the key used both to look up and to insert if not found + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Complexity + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Notes + + Unlike insert or emplace, these functions do not move from rvalue arguments if the + insertion does not happen, which makes it easy to manipulate maps whose values are + move-only types, such as std::flat_map>. In + addition, try_emplace treats the key and the arguments to the mapped_type + separately, unlike emplace, which requires the arguments to construct a value_type + (that is, a std::pair). + + Overloads (3,6) can be called without constructing an object of type key_type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print_node(const auto& node) + { + std::cout << '[' << node.first << "] = " << node.second << '\\n'; + } + + void print_result(auto const& pair) + { + std::cout << (pair.second ? "inserted: " : "ignored: "); + print_node(*pair.first); + } + + int main() + { + using namespace std::literals; + std::map m; + + print_result(m.try_emplace( "a", "a"s)); + print_result(m.try_emplace( "b", "abcd")); + print_result(m.try_emplace( "c", 10, 'c')); + print_result(m.try_emplace( "c", "Won't be inserted")); + + for (const auto& p : m) + print_node(p); + } + +.SH Output: + + inserted: [a] = a + inserted: [b] = abcd + inserted: [c] = cccccccccc + ignored: [c] = cccccccccc + [a] = a + [b] = abcd + [c] = cccccccccc + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + inserts an element or assigns to the current element if the key + insert_or_assign already exists + \fI(public member function)\fP diff --git a/man/std::flat_map::upper_bound.3 b/man/std::flat_map::upper_bound.3 new file mode 100644 index 000000000..d38f35e7c --- /dev/null +++ b/man/std::flat_map::upper_bound.3 @@ -0,0 +1,46 @@ +.TH std::flat_map::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::upper_bound \- std::flat_map::upper_bound + +.SH Synopsis + iterator upper_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator upper_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator upper_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is greater than key. If no such element + is found, past-the-end (see end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_map::value_comp.3 b/man/std::flat_map::value_comp.3 new file mode 100644 index 000000000..8979b9786 --- /dev/null +++ b/man/std::flat_map::value_comp.3 @@ -0,0 +1,76 @@ +.TH std::flat_map::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::value_comp \- std::flat_map::value_comp + +.SH Synopsis + std::flat_map::value_compare value_comp() const; (since C++23) + + Returns a function object that compares objects of type std::flat_map::value_type + (key-value pairs) by using key_comp to compare the first components of the pairs. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_map cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.value_comp(); + + for (const std::pair val = {100, 'a'}; auto it : cont) + { + const bool before = comp_func(it, val); + const bool after = comp_func(val, it); + + std::cout << '(' << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val.first << ")\\n"; + else if (before) + std::cout << "goes before key (" << val.first << ")\\n"; + else if (after) + std::cout << "goes after key (" << val.first << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + +.SH See also + + key_comp returns the function that compares keys + \fI(public member function)\fP diff --git a/man/std::flat_map::value_compare.3 b/man/std::flat_map::value_compare.3 new file mode 100644 index 000000000..e7d276221 --- /dev/null +++ b/man/std::flat_map::value_compare.3 @@ -0,0 +1,52 @@ +.TH std::flat_map::value_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::value_compare \- std::flat_map::value_compare + +.SH Synopsis + class value_compare; (since C++23) + + std::flat_map::value_compare is a function object that compares objects of type + std::flat_map::const_reference (a pair of references to the stored key/value) by + comparing the first components (i.e. keys) of the passed pairs. + +.SH Member objects + + Member name Definition + comp (private) the comparison function object of type std::flat_map::key_compare + (exposition-only member object*) + +.SH Member functions + + constructor constructs value_compare object + (private) \fI(public member function)\fP + operator() compares two values of type value_type + \fI(public member function)\fP + +std::flat_map::value_compare::value_compare + + private: (exposition only*) + value_compare( key_compare c ); + + Initializes the underlying instance of the comparator comp to c. + +.SH Parameters + + c - a comparator to assign + +std::flat_map::value_compare::operator() + + bool operator()( const const_reference& lhs, const const_reference& rhs ) const; + + Compares lhs.first and rhs.first by calling the stored comparator comp. + +.SH Parameters + + lhs, rhs - values to compare + +.SH Return value + + comp(lhs.first, rhs.first) + +.SH Exceptions + + May throw implementation-defined exceptions. diff --git a/man/std::flat_map::values.3 b/man/std::flat_map::values.3 new file mode 100644 index 000000000..5a5e7406d --- /dev/null +++ b/man/std::flat_map::values.3 @@ -0,0 +1,50 @@ +.TH std::flat_map::values 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_map::values \- std::flat_map::values + +.SH Synopsis + const mapped_container_type& values() const noexcept; (since C++23) + + Return a constant reference to the adapted values container. Equivalent to return + c.values;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying values container. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_map map{{1, 1.1}, {2, 2.2}, {3, 3.3}}; + + // The default values container is std::vector: + static_assert(std::is_same_v&>); + + std::println("{}", map.values()); + } + +.SH Output: + + [1.1, 2.2, 3.3] + +.SH See also + + keys direct access to the underlying keys container + \fI(public member function)\fP diff --git a/man/std::flat_multimap.3 b/man/std::flat_multimap.3 new file mode 100644 index 000000000..d0b421db0 --- /dev/null +++ b/man/std::flat_multimap.3 @@ -0,0 +1,220 @@ +.TH std::flat_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap \- std::flat_multimap + +.SH Synopsis + Defined in header + template< + + class Key, + class T, + class Compare = std::less, (since C++23) + class KeyContainer = std::vector, + class MappedContainer = std::vector + + > class flat_multimap; + + The flat multimap is a container adaptor that gives the functionality of an + associative container that contains key-value pairs, while permitting multiple + entries with the same key value. Keys are sorted by using the comparison function + Compare. + + The class template flat_multimap acts as a wrapper to the two underlying containers, + passed as objects of type KeyContainer and MappedContainer respectively. The first + container is sorted, and for each key its corresponding value is in the second + container at the same index (offset). The number of elements in both containers is + the same. + + Everywhere the standard library uses the Compare requirements, uniqueness is + determined by using the equivalence relation. Informally, two objects a and b are + considered equivalent if neither compares less than the other: !comp(a, b) && + !comp(b, a). + + std::flat_multimap meets the requirements of Container, ReversibleContainer, + optional container requirements, and all requirements of AssociativeContainer + (including logarithmic search complexity), except that: + + * requirements related to nodes are not applicable, + * iterator invalidation requirements differ, + * the complexity of insertion and erasure operations is linear. + + A flat multimap supports most AssociativeContainer's operations that use equal keys. + +.SH Template parameters + + Key - The type of the keys. The program is ill-formed if Key is not the + same type as KeyContainer::value_type. + T - The type of mapped values. The program is ill-formed if T is not + the same type as MappedContainer::value_type. + Compare - A Compare type providing a strict weak ordering. + The types of the underlying SequenceContainer to store keys and + mapped values correspondingly. The iterators of such containers + should satisfy LegacyRandomAccessIterator or model + KeyContainer - random_access_iterator. Invocations of their member functions size + MappedContainer and max_size should not exit via an exception. + + The standard containers std::vector and std::deque satisfy these + requirements. + +.SH Member types + + Member type Definition + key_container_type KeyContainer + mapped_container_type MappedContainer + key_type Key + mapped_type T + value_type std::pair + key_compare Compare + reference std::pair + const_reference std::pair + size_type std::size_t + difference_type std::ptrdiff_t + iterator implementation-defined LegacyInputIterator and + random_access_iterator to value_type + const_iterator implementation-defined LegacyInputIterator and + random_access_iterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + type describing the underlying containers + + struct containers + containers { + key_container_type keys; + mapped_container_type values; + }; + +.SH Member classes + + value_compare compares objects of type value_type + \fI(class)\fP + +.SH Member objects + + Member name Definition + c (private) the object of type containers + (exposition-only member object*) + compare (private) the comparison function object of type key_compare + (exposition-only member object*) + +.SH Member functions + + constructor constructs the flat_multimap + \fI(public member function)\fP + destructor destroys every element of the container adaptor + (implicitly declared) \fI(public member function)\fP + operator= assigns values to the container adaptor + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Capacity + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP +.SH Modifiers + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + insert_range inserts a range of elements + \fI(public member function)\fP + extract extracts the underlying containers + \fI(public member function)\fP + replace replaces the underlying containers + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP +.SH Lookup + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + returns an iterator to the first element not less than the + lower_bound given key + \fI(public member function)\fP + returns an iterator to the first element greater than the + upper_bound given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP +.SH Observers + key_comp returns the function that compares keys + \fI(public member function)\fP + returns the function that compares keys in objects of type + value_comp value_type + \fI(public member function)\fP + keys direct access to the underlying keys container + \fI(public member function)\fP + values direct access to the underlying values container + \fI(public member function)\fP + +.SH Non-member functions + + operator== lexicographically compares the values of two + operator<=> flat_multimaps + (C++23) \fI(function template)\fP + std::swap(std::flat_multimap) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + erase_if(std::flat_multimap) erases all elements satisfying specific criteria + (C++23) \fI(function template)\fP + +.SH Helper classes + + std::uses_allocator specializes the std::uses_allocator type + (C++23) trait + \fI(class template specialization)\fP + + Tags + + sorted_equivalent indicates that elements of a range are sorted (uniqueness is not + sorted_equivalent_t required) + (C++23) (tag) + + Deduction guides + +.SH Notes + + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_flat_map 202207L (C++23) std::flat_map and std::flat_multimap + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + flat_map adapts two containers to provide a collection of key-value pairs, + (C++23) sorted by unique keys + \fI(class template)\fP + multimap collection of key-value pairs, sorted by keys + \fI(class template)\fP + unordered_multimap collection of key-value pairs, hashed by keys + \fI(C++11)\fP \fI(class template)\fP + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::flat_multimap::begin,.3 b/man/std::flat_multimap::begin,.3 new file mode 100644 index 000000000..33b7b3a21 --- /dev/null +++ b/man/std::flat_multimap::begin,.3 @@ -0,0 +1,67 @@ +.TH std::flat_multimap::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::begin, \- std::flat_multimap::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP (since C++23) + const_iterator begin() const noexcept; \fB(2)\fP (since C++23) + const_iterator cbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the first element of the flat_multimap. + + If the flat_multimap is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multimap map{{4, 13}, {9, 94}, {1, 19}, {4, 42}}; + + for (auto it = map.cbegin(); it != map.cend(); ++it) + std::cout << '[' << it->first << "] = " << it->second << '\\n'; + + // Unlike std::multimap's bidirectional iterators, the std::flat_multimap + // iterators are random-access, so they can be used with the operator[]: + auto it = map.cbegin(); + assert(it[1] == 19); + assert(it[4] == 13); + assert(it[4] == 42); + assert(it[9] == 94); + } + +.SH Output: + + [1] = 19 + [4] = 13 + [4] = 42 + [9] = 94 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multimap::clear.3 b/man/std::flat_multimap::clear.3 new file mode 100644 index 000000000..84a17e325 --- /dev/null +++ b/man/std::flat_multimap::clear.3 @@ -0,0 +1,61 @@ +.TH std::flat_multimap::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::clear \- std::flat_multimap::clear + +.SH Synopsis + void clear() noexcept; (since C++23) + + Erases all elements from the container adaptor. After this call, size() returns + zero. + + Invalidates any references, pointers, and iterators referring to contained elements. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the size of the container adaptor, i.e., the number of elements. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::flat_multimap& v) + { + std::cout << rem << "{ "; + for (const auto& [key, value] : v) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::flat_multimap container{{1, 'x'}, {2, 'y'}, {3, 'z'}}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { [1]:x [2]:y [3]:z } + Size=3 + After clear: { } + Size=0 + +.SH See also + + erase erases elements + \fI(public member function)\fP diff --git a/man/std::flat_multimap::contains.3 b/man/std::flat_multimap::contains.3 new file mode 100644 index 000000000..8ccfe8611 --- /dev/null +++ b/man/std::flat_multimap::contains.3 @@ -0,0 +1,60 @@ +.TH std::flat_multimap::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::contains \- std::flat_multimap::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multimap example{{1, 'a'}, {2, 'b'}}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_multimap::count.3 b/man/std::flat_multimap::count.3 new file mode 100644 index 000000000..bbefa0cd5 --- /dev/null +++ b/man/std::flat_multimap::count.3 @@ -0,0 +1,46 @@ +.TH std::flat_multimap::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::count \- std::flat_multimap::count + +.SH Synopsis + size_type count( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + size_type count( const K& x ) const; + + Returns the number of elements with key that compares equivalent to the specified + argument. + + 1) Returns the number of elements with key key. + 2) Returns the number of elements with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the elements to count + x - alternative value to compare to the keys + +.SH Return value + + Number of elements with key that compares equivalent to key or x. + +.SH Complexity + + Logarithmic in the size of the container plus linear in the number of elements + found. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multimap::emplace.3 b/man/std::flat_multimap::emplace.3 new file mode 100644 index 000000000..369b1571f --- /dev/null +++ b/man/std::flat_multimap::emplace.3 @@ -0,0 +1,96 @@ +.TH std::flat_multimap::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::emplace \- std::flat_multimap::emplace + +.SH Synopsis + template< class... Args > (since C++23) + iterator emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args. + + Initializes an object t of type std::pair with + std::forward(args)...; if the map already contains an element whose key is + equivalent to t.first, *this is unchanged. Otherwise, equivalent to: + + auto key_it = ranges::upper_bound(c.keys, t.first, compare); + auto value_it = c.values.begin() + std::distance(c.keys.begin(), key_it); + c.keys.insert(key_it, std::move(t.first)); + c.values.insert(value_it, std::move(t.second)); + + This overload participates in overload resolution only if + std::is_constructible_v, Args...> is true. + + Careful use of emplace allows the new element to be constructed while avoiding + unnecessary copy or move operations. + + Information on iterator invalidation is copied from here + +.SH Parameters + + args - arguments to forward to the constructor of the element + +.SH Return value + + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in the size of the container + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_multimap m; + + // uses pair's move constructor + m.emplace(std::make_pair(std::string("a"), std::string("a"))); + + // uses pair's converting move constructor + m.emplace(std::make_pair("b", "abcd")); + + // uses pair's template constructor + m.emplace("d", "ddd"); + + // emplace with duplicate key + m.emplace("d", "DDD"); + + // uses pair's piecewise constructor + m.emplace(std::piecewise_construct, + std::forward_as_tuple("c"), + std::forward_as_tuple(10, 'c')); + + for (const auto& p : m) + std::cout << p.first << " => " << p.second << '\\n'; + } + +.SH Output: + + a => a + b => abcd + c => cccccccccc + d => ddd + d => DDD + +.SH See also + + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if the key + try_emplace exists + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP diff --git a/man/std::flat_multimap::emplace_hint.3 b/man/std::flat_multimap::emplace_hint.3 new file mode 100644 index 000000000..b1ce8bcb3 --- /dev/null +++ b/man/std::flat_multimap::emplace_hint.3 @@ -0,0 +1,50 @@ +.TH std::flat_multimap::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::emplace_hint \- std::flat_multimap::emplace_hint + +.SH Synopsis + template< class... Args > (since C++23) + iterator emplace_hint( const_iterator hint, Args&&... args ); + + Inserts a new element into the container as close as possible to the position just + before hint. + + The constructor of the element type (value_type, that is, std::pair) + is called with exactly the same arguments as supplied to the function, forwarded + with std::forward(args).... + + Information on iterator invalidation is copied from here + +.SH Parameters + + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + This section is incomplete + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::flat_multimap::empty.3 b/man/std::flat_multimap::empty.3 new file mode 100644 index 000000000..e150a490f --- /dev/null +++ b/man/std::flat_multimap::empty.3 @@ -0,0 +1,58 @@ +.TH std::flat_multimap::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::empty \- std::flat_multimap::empty + +.SH Synopsis + [[nodiscard]] bool empty() const noexcept; (since C++23) + + Checks if the underlying containers have no elements. Equivalent to return begin() + == end();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the underlying containers are empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses empty to check if a std::flat_multimap contains + any elements: + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multimap numbers; + std::cout << std::boolalpha; + std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; + + numbers.emplace(42, 13); + numbers.insert(std::make_pair(13317, 123)); + std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; + } + +.SH Output: + + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false + +.SH See also + + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::flat_multimap::end,.3 b/man/std::flat_multimap::end,.3 new file mode 100644 index 000000000..900a58f2e --- /dev/null +++ b/man/std::flat_multimap::end,.3 @@ -0,0 +1,68 @@ +.TH std::flat_multimap::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::end, \- std::flat_multimap::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP (since C++23) + const_iterator end() const noexcept; \fB(2)\fP (since C++23) + const_iterator cend() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the element following the last element of the flat_multimap. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multimap map{{4, 13}, {9, 94}, {1, 19}, {4, 42}}; + + for (auto it = map.cbegin(); it != map.cend(); ++it) + std::cout << '[' << it->first << "] = " << it->second << '\\n'; + + // Unlike std::multimap's bidirectional iterators, the std::flat_multimap + // iterators are random-access, so they can be used with the operator[]: + auto it = map.cbegin(); + assert(it[1] == 19); + assert(it[4] == 13); + assert(it[4] == 42); + assert(it[9] == 94); + } + +.SH Output: + + [1] = 19 + [4] = 13 + [4] = 42 + [9] = 94 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multimap::equal_range.3 b/man/std::flat_multimap::equal_range.3 new file mode 100644 index 000000000..b5d977436 --- /dev/null +++ b/man/std::flat_multimap::equal_range.3 @@ -0,0 +1,99 @@ +.TH std::flat_multimap::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::equal_range \- std::flat_multimap::equal_range + +.SH Synopsis + std::pair equal_range( const Key& key ); \fB(1)\fP (since C++23) + std::pair equal_range( const Key& \fB(2)\fP (since C++23) + key ) const; + template< class K > \fB(3)\fP (since C++23) + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP (since C++23) + ) const; + + Returns a range containing all elements with the given key in the container. The + range is defined by two iterators, one pointing to the first element that is not + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). + + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + std::pair containing a pair of iterators defining the wanted range: the first + pointing to the first element that is not less than key and the second pointing to + the first element greater than key. + + If there are no elements not less than key, past-the-end (see end()) iterator is + returned as the first element. Similarly if there are no elements greater than key, + past-the-end iterator is returned as the second element. + + Since emplace and unhinted insert always insert at the upper bound, the order of + equivalent elements in the equal range is the order of insertion unless hinted + insert or emplace_hint was used to insert an element at a different position. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + template + void print_equal_range(I first, I lb, I ub, I last) + { + for (I i{first}; i != lb; ++i) + std::cout << *i << ' '; + std::cout << "[ "; + + for (I i{lb}; i != ub; ++i) + std::cout << *i << ' '; + std::cout << ") "; + + for (I i{ub}; i != last; ++i) + std::cout << *i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::flat_multimap c{4, 3, 2, 1, 3, 3}; + std::cout << "c = "; + print_equal_range(begin(c), begin(c), end(c), end(c)); + for (int key{}; key != 6; ++key) + { + std::cout << "key = " << key << "; equal range = "; + const auto [lb, ub] = c.equal_range(key); + print_equal_range(begin(c), lb, ub, end(c)); + } + } + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::flat_multimap::erase.3 b/man/std::flat_multimap::erase.3 new file mode 100644 index 000000000..e7057851e --- /dev/null +++ b/man/std::flat_multimap::erase.3 @@ -0,0 +1,97 @@ +.TH std::flat_multimap::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::erase \- std::flat_multimap::erase + +.SH Synopsis + iterator erase( iterator position ); \fB(1)\fP (since C++23) + iterator erase( const_iterator pos ); \fB(2)\fP (since C++23) + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP (since C++23) + size_type erase( const Key& key ); \fB(4)\fP (since C++23) + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. The order of the remaining equivalent + elements is preserved. + + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes all elements with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. + + Information on iterator invalidation is copied from here + + The iterator pos must be valid and dereferenceable. Thus the end() iterator (which + is valid, but is not dereferenceable) cannot be used as a value for pos. + +.SH Parameters + + pos - iterator to the element to remove + first, last - range of elements to remove + key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove + +.SH Return value + + 1-3) Iterator following the last removed element. + 4) Number of elements removed. + 5) Number of elements removed. + +.SH Exceptions + + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. + +.SH Complexity + + Depends on underlying containers. Typically linear. + + This section is incomplete + Reason: revision required + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multimap c = + { + {1, "one"}, {2, "two"}, {3, "three"}, + {4, "four"}, {5, "five"}, {6, "six"} + }; + + // erase all odd numbers from c + for (auto it = c.begin(); it != c.end();) + { + if (it->first % 2 != 0) + it = c.erase(it); + else + ++it; + } + + for (auto& p : c) + std::cout << p.second << ' '; + std::cout << '\\n'; + } + +.SH Output: + + two four six + +.SH See also + + clear clears the contents + \fI(public member function)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::flat_multimap::extract.3 b/man/std::flat_multimap::extract.3 new file mode 100644 index 000000000..b44027a27 --- /dev/null +++ b/man/std::flat_multimap::extract.3 @@ -0,0 +1,63 @@ +.TH std::flat_multimap::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::extract \- std::flat_multimap::extract + +.SH Synopsis + containers extract() &&; (since C++23) + + Extracts adapted containers c. Equivalent to return std::move(c);. + + After this operation *this is empty, even if an exception is thrown. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + std::move(c). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::flat_multimap map{{1, 1.1}, {2, 2.2}, {3, 3.3}}; + const auto size = map.size(); + + auto c = map.extract(); + assert(c.keys.size() == size); + assert(c.values.size() == size); + assert(map.empty()); + assert(map.keys().empty()); + assert(map.values().empty()); + + // The default keys and values containers are std::vector: + static_assert(std::is_same_v>); + static_assert(std::is_same_v>); + + std::println("keys: {}", c.keys); + std::println("values: {}", c.values); + } + +.SH Output: + + keys: [1, 2, 3] + values: [1.1, 2.2, 3.3] + +.SH See also + + replace replaces the underlying containers + \fI(public member function)\fP diff --git a/man/std::flat_multimap::find.3 b/man/std::flat_multimap::find.3 new file mode 100644 index 000000000..6699b473d --- /dev/null +++ b/man/std::flat_multimap::find.3 @@ -0,0 +1,104 @@ +.TH std::flat_multimap::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::find \- std::flat_multimap::find + +.SH Synopsis + iterator find( const Key& key ); \fB(1)\fP (since C++23) + const_iterator find( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator find( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator find( const K& x ) const; + + 1,2) Finds an element with key equivalent to key. If there are several elements with + the requested key in the container, any of them may be returned. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + + int main() + { + // Simple comparison demo. + std::flat_multimap example{{1,'a'}, {2,'b'}}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << search->first << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::flat_multimap> example2{{{1, {}}, 'a'}, {{2, {}}, 'b'}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Obtaining const iterators. + // Compiler decides whether to return iterator of (non) const type by way of + // accessing map; to prevent intentional modification, one of the simplest + // options is to access the map via a constant reference. + const auto& example2ref = example2; + if (auto search = example2ref.find(lk); search != example2.end()) + { + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + // search->second = 'c'; // error: assignment of member + // 'std::pair::second' + // in read-only object + } + } + +.SH Output: + + Found 2 b + Found 2 b + Found 2 b + +.SH See also + + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_multimap::flat_multimap.3 b/man/std::flat_multimap::flat_multimap.3 new file mode 100644 index 000000000..8762f5dca --- /dev/null +++ b/man/std::flat_multimap::flat_multimap.3 @@ -0,0 +1,262 @@ +.TH std::flat_multimap::flat_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::flat_multimap \- std::flat_multimap::flat_multimap + +.SH Synopsis + flat_multimap() \fB(1)\fP (since C++23) + : flat_multimap(key_compare()) { } + template< class Allocator > \fB(2)\fP (since C++23) + flat_multimap( const flat_multimap&, const Allocator& alloc ); + template< class Allocator > \fB(3)\fP (since C++23) + flat_multimap( flat_multimap&&, const Allocator& alloc ); + flat_multimap( key_container_type key_cont, mapped_container_type + mapped_cont, \fB(4)\fP (since C++23) + const key_compare& comp = key_compare() ); + template< class Allocator > + + flat_multimap( const key_container_type& key_cont, \fB(5)\fP (since C++23) + const mapped_container_type& mapped_cont, + + const Allocator& alloc ); + template< class Allocator > + + flat_multimap( const key_container_type& key_cont, \fB(6)\fP (since C++23) + const mapped_container_type& mapped_cont, + + const key_compare& comp, const Allocator& alloc ); + flat_multimap( std::sorted_equivalent_t, key_container_type + key_cont, + \fB(7)\fP (since C++23) + mapped_container_type mapped_cont, + + const key_compare& comp = key_compare() ); + template< class Allocator > + + flat_multimap( std::sorted_equivalent_t, const + key_container_type& key_cont, \fB(8)\fP (since C++23) + + const mapped_container_type& mapped_cont, const + Allocator& alloc ); + template< class Allocator > + + flat_multimap( std::sorted_equivalent_t, const + key_container_type& key_cont, \fB(9)\fP (since C++23) + const mapped_container_type& mapped_cont, + + const key_compare& comp, const Allocator& alloc ); + explicit flat_multimap( const key_compare& comp ) \fB(10)\fP (since C++23) + : c(), compare(comp) { } + template< class Allocator > \fB(11)\fP (since C++23) + flat_multimap( const key_compare& comp, const Allocator& alloc ); + template< class Allocator > \fB(12)\fP (since C++23) + explicit flat_multimap( const Allocator& alloc ); + template< class InputIter > + + flat_multimap( InputIter first, InputIter last, \fB(13)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(), compare(comp); + template< class InputIter, class Allocator > + + flat_multimap( InputIter first, InputIter last, \fB(14)\fP (since C++23) + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + flat_multimap( InputIter first, InputIter last, const Allocator& \fB(15)\fP (since C++23) + alloc ); + template< container-compatible-range R > + + flat_multimap( std::from_range_t, R&& rg, const key_compare& comp \fB(16)\fP (since C++23) + ) + + : flat_multimap(comp); + template< container-compatible-range R > + + flat_multimap( std::from_range_t fr, R&& rg ) \fB(17)\fP (since C++23) + + : flat_multimap(fr, std::forward(rg), key_compare()) { } + template< container-compatible-range R, class + Allocator > \fB(18)\fP (since C++23) + flat_multimap( std::from_range_t, R&& rg, const Allocator& alloc + ); + template< container-compatible-range R, class + Allocator > + + flat_multimap( std::from_range_t, R&& rg, const key_compare& \fB(19)\fP (since C++23) + comp, + + const Allocator& alloc ); + template< class InputIter > + + flat_multimap( std::sorted_equivalent_t s, InputIter first, + InputIter last, \fB(20)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(), compare(comp); + template< class InputIter, class Allocator > + + flat_multimap( std::sorted_equivalent_t s, InputIter first, \fB(21)\fP (since C++23) + InputIter last, + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + + flat_multimap( std::sorted_equivalent_t s, InputIter first, \fB(22)\fP (since C++23) + InputIter last, + + const Allocator& alloc ); + flat_multimap( std::initializer_list init, + + const key_compare& comp = key_compare() ) \fB(23)\fP (since C++23) + + : flat_multimap(init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_multimap( std::initializer_list init, const \fB(24)\fP (since C++23) + key_compare& comp, + + const Allocator& alloc ); + template< class Allocator > + flat_multimap( std::initializer_list init, const \fB(25)\fP (since C++23) + Allocator& alloc ); + flat_multimap( std::sorted_equivalent_t s, + std::initializer_list init, + \fB(26)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : flat_multimap(s, init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_multimap( std::sorted_equivalent_t s, \fB(27)\fP (since C++23) + std::initializer_list init, + + const key_compare& comp, const Allocator& alloc ); + template< class Allocator > + + flat_multimap( std::sorted_equivalent_t s, \fB(28)\fP (since C++23) + std::initializer_list init, + + const Allocator& alloc ); + + Constructs new container adaptor from a variety of data sources and optionally using + user supplied comparison function object comp and/or allocator alloc. + + 1) A default constructor. Constructs an empty container adaptor. + 2) A copy constructor. Constructs c with the copy of the contents of other.c and + compare with other.compare. See allocator usage note below. + 3) A move constructor. Constructs the container adaptor with the contents of other + using move semantics. See allocator usage note below. + 4) First, initializes c.keys with std::move(key_cont), c.values with + std::move(mapped_cont), and compare with comp. Then sorts the underlying range + [begin(), end()) with respect to value_comp(). + 5) Same as \fB(4)\fP, equivalent to flat_multimap(key_cont, mapped_cont);. See allocator + usage note below. + 6) Same as \fB(4)\fP, equivalent to flat_multimap(key_cont, mapped_cont, comp);. See + allocator usage note below. + 7) Initializes c.keys with std::move(key_cont), c.values with + std::move(mapped_cont), and compare with comp. + 8) Same as \fB(7)\fP, equivalent to flat_multimap(s, key_cont, mapped_cont);. See + allocator usage note below. + 9) Same as \fB(7)\fP, equivalent to flat_multimap(s, key_cont, mapped_cont, comp);. See + allocator usage note below. + 10) Constructs an empty container adaptor. + 11,12) Constructs an empty container adaptor. See allocator usage note below. + 13) Constructs the container adaptor with the contents of the range [first, last), + equivalent to insert(first, last);. + 14,15) Same as \fB(13)\fP. See allocator usage note below. + 16) Constructs the container adaptor with the contents of the range rg. First, uses + \fB(10)\fP as delegating constructor. Then initializes c with the contents of rg as if by + insert_range(std::forward(rg));. + 17) Same as \fB(16)\fP using it as delegating constructor. + 18,19) Same as \fB(16)\fP. See allocator usage note below. + 20) Constructs the underlying containers with the contents of the range + [first, last) as if by insert(first, last). + 21,22) Same as \fB(20)\fP. See allocator usage note below. + 23) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(13)\fP as delegating constructor. + 24,25) Same as \fB(23)\fP. See allocator usage note below. + 26) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(20)\fP as delegating constructor. + 27,28) Save as \fB(26)\fP. See allocator usage note below. + + Note for overloads (13-15,20-22): If [first, last) is not a valid range, the + behavior is undefined. + +.SH Parameters + + key_cont - a container to be used as source to initialize the underlying keys + container + mapped_cont - a container to be used as source to initialize the underlying values + container + other - another flat_multimap to be used as source to initialize the elements + of the underlying containers with + alloc - an allocator to use for all memory allocations of the underlying + containers + comp - a function object to be used for all comparisons of keys + first, last - a range to copy the elements from + init - an initializer list to initialize the elements of the underlying + containers with + a container compatible range (that is, an input_range whose elements + rg - are convertible to value_type) to be used as source to initialize the + underlying containers + fr - a disambiguation tag that indicates that the contained member should + be range constructed + s - a disambiguation tag that indicates that the input sequence is sorted + with respect to value_comp() +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + Compare must meet the requirements of Compare. + - + Allocator must meet the requirements of Allocator. + +.SH Complexity + + 1) Constant. + 2) Linear in size of other. + 3) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 4-6) Linear in \\(\\scriptsize N\\)N if cont is sorted with respect to value_comp(), + otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of key_cont.size() before this call. + 7-9) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 10-12) Constant. + 13-15) Linear in \\(\\scriptsize N\\)N if the input range [first, last) is sorted with + respect to value_comp(), otherwise \\(\\scriptsize + \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where \\(\\scriptsize N\\)N is the value of + key_cont.size() before this call. + 16-19) Linear in \\(\\scriptsize N\\)N if the input range rg is sorted with respect to + value_comp(), otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), + where \\(\\scriptsize N\\)N is the value of key_cont.size() before this call. + 20-22) Linear in size of [first, last). + 23-25) Linear in \\(\\scriptsize N\\)N if the elements of init are sorted with respect + to value_comp(), otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), + where \\(\\scriptsize N\\)N is the value of key_cont.size() before this call. + 26-28) Linear in size of init. + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload \fB(3)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns values to the container adaptor + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multimap::insert.3 b/man/std::flat_multimap::insert.3 new file mode 100644 index 000000000..02432a020 --- /dev/null +++ b/man/std::flat_multimap::insert.3 @@ -0,0 +1,122 @@ +.TH std::flat_multimap::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::insert \- std::flat_multimap::insert + +.SH Synopsis + iterator insert( const value_type& value ); \fB(1)\fP (since C++23) + iterator insert( value_type&& value ); \fB(2)\fP (since C++23) + iterator insert( const_iterator pos, const value_type& value ); \fB(3)\fP (since C++23) + iterator insert( const_iterator pos, value_type&& value ); \fB(4)\fP (since C++23) + template< class P > \fB(5)\fP (since C++23) + iterator insert( P&& x ); + template< class P > \fB(6)\fP (since C++23) + iterator insert( const_iterator pos, P&& x ); + template< class InputIt > \fB(7)\fP (since C++23) + void insert( InputIt first, InputIt last ); + template< class InputIt > + void insert( std::sorted_equivalent_t, InputIt first, InputIt \fB(8)\fP (since C++23) + last ); + void insert( std::initializer_list ilist ); \fB(9)\fP (since C++23) + void insert( std::sorted_equivalent_t s, \fB(10)\fP (since C++23) + std::initializer_list ilist ); + + Inserts element(s) into the container. + + 1) Inserts value. Equivalent to return emplace(value);. + 2) Inserts value. Equivalent to return emplace(std::move(value));. + 3) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, value);. + 4) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, std::move(value));. + 5) Inserts x into *this as if by emplace(std::forward

(x));. This overload + participates in overload resolution only if std::is_constructible_v, P> is true. + 6) Inserts x into *this in the position as close as possible to the position just + prior to pos. Equivalent to return emplace_hint(position, std::forward

(x));. This + overload participates in overload resolution only if + std::is_constructible_v, P> is true. + 7) Inserts elements from range [first, last) as if performing the following + operations sequentially: + 1. Adds elements to c as if by + for (; first != last; ++first) + { + value_type value = *first; + c.keys.insert(c.keys.end(), std::move(value.first)); + c.values.insert(c.values.end(), std::move(value.second)); + } + 2. Sorts the range of newly inserted elements with respect to value_comp. + 3. Merges the resulting sorted range and the sorted range of pre-existing elements + into a single sorted range. + May allocate memory during the in-place merge operation. + 8) Inserts elements from range [first, last) as if performing the following + operations sequentially: + 1. Adds elements to c as if by + for (; first != last; ++first) + { + value_type value = *first; + c.keys.insert(c.keys.end(), std::move(value.first)); + c.values.insert(c.values.end(), std::move(value.second)); + } + 2. Merges the sorted range of newly added elements and the sorted range of + pre-existing elements into a single sorted range. + May allocate memory during the in-place merge operation. + 9) Inserts elements from initializer list ilist. Equivalent to insert(ilist.begin(), + ilist.end());. + 10) Inserts elements from initializer list ilist. Equivalent to insert(s, + ilist.begin(), ilist.end());. + + Information on iterator invalidation is copied from here + +.SH Parameters + + pos - an iterator to the position before which the new element will be + inserted + value - an element value to insert + first, last - a range of elements to insert + ilist - an initializer list to insert the values from + x - a value of any type that can be transparently compared with a key + s - a disambiguation tag indicating that the input sequence is sorted + (with respect to value_comp()) +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1-6) An iterator to the inserted element. + 7-10) \fI(none)\fP + +.SH Exceptions + + 1-6) If an exception is thrown by any operation, the insertion has no effect. + 7-10) No exception safety guarantee. (?) + + This section is incomplete + Reason: double check cases 7-10 + +.SH Complexity + + 1-6) Linear in size(). + 7) N + M·log(M), where N is the size() before the operation and M is + std::distance(first, last). + 8) Linear in size(). + 9) N + M·log(M), where N is the size() before the operation and M is ilist.size(). + 10) Linear in N, where N is size() after the operation. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::flat_multimap::insert_range.3 b/man/std::flat_multimap::insert_range.3 new file mode 100644 index 000000000..f4d99345a --- /dev/null +++ b/man/std::flat_multimap::insert_range.3 @@ -0,0 +1,79 @@ +.TH std::flat_multimap::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::insert_range \- std::flat_multimap::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg into underlying containers c as if + by: + + for (const auto& e : rg) + { + c.keys.insert(c.keys.end(), e.first); + c.values.insert(c.values.end(), e.second); + } + + Then, sorts the range of newly inserted elements with respect to value_comp(). + Merges the resulting sorted range and the sorted range of pre-existing elements into + a single sorted range. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + Information on iterator invalidation is copied from here + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N + M·log(M), where N is size() before the operation and M is ranges::distance(rg). + +.SH Notes + + Since insert_range performs an in-place merge operation, that may allocate memory. + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto, auto const& container) + { + for (const auto& [key, value] : container) + std::cout << '{' << key << ',' << value << '}' << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::flat_multimap{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}}; + const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + {-2,-22} {-1,-11} {1,11} {2,22} {3,33} {3,-33} {4,44} + +.SH See also + + insert inserts elements + \fI(public member function)\fP diff --git a/man/std::flat_multimap::key_comp.3 b/man/std::flat_multimap::key_comp.3 new file mode 100644 index 000000000..5b20912af --- /dev/null +++ b/man/std::flat_multimap::key_comp.3 @@ -0,0 +1,76 @@ +.TH std::flat_multimap::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::key_comp \- std::flat_multimap::key_comp + +.SH Synopsis + key_compare key_comp() const; (since C++23) + + Returns the function object that compares the keys, which is a copy of this + container's constructor argument comp. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The key comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_multimap cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.key_comp(); + + for (const auto it : cont) + { + const bool before = comp_func(it.first, 100); + const bool after = comp_func(100, it.first); + + std::cout << "Key (" << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + +.SH See also + + value_comp returns the function that compares keys in objects of type value_type + \fI(public member function)\fP diff --git a/man/std::flat_multimap::keys.3 b/man/std::flat_multimap::keys.3 new file mode 100644 index 000000000..33ffd90dd --- /dev/null +++ b/man/std::flat_multimap::keys.3 @@ -0,0 +1,50 @@ +.TH std::flat_multimap::keys 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::keys \- std::flat_multimap::keys + +.SH Synopsis + const key_container_type& keys() const noexcept; (since C++23) + + Return a constant reference to the adapted keys container. Equivalent to return + c.keys;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying keys container. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_multimap adaptor{{1, 1.1}, {2, 2.2}, {3, 3.3}}; + + // The default keys container is std::vector: + static_assert(std::is_same_v&>); + + std::println("{}", adaptor.keys()); + } + +.SH Output: + + [1, 2, 3] + +.SH See also + + values direct access to the underlying values container + \fI(public member function)\fP diff --git a/man/std::flat_multimap::lower_bound.3 b/man/std::flat_multimap::lower_bound.3 new file mode 100644 index 000000000..9841407c0 --- /dev/null +++ b/man/std::flat_multimap::lower_bound.3 @@ -0,0 +1,47 @@ +.TH std::flat_multimap::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::lower_bound \- std::flat_multimap::lower_bound + +.SH Synopsis + iterator lower_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is not less than key. If no such element + is found, a past-the-end iterator (see end()) is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multimap::max_size.3 b/man/std::flat_multimap::max_size.3 new file mode 100644 index 000000000..a83d6e4c9 --- /dev/null +++ b/man/std::flat_multimap::max_size.3 @@ -0,0 +1,54 @@ +.TH std::flat_multimap::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::max_size \- std::flat_multimap::max_size + +.SH Synopsis + size_type max_size() const noexcept; (since C++23) + + Returns the maximum number of elements the container is able to hold due to system + or library implementation limitations. Equivalent to + std::min(c.keys.max_size(), c.values.max_size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of elements. + +.SH Complexity + + Constant. + +.SH Notes + + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the + container may be limited to a value smaller than max_size() by the amount of RAM + available. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multimap q; + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "Maximum size of a std::flat_multimap is " << q.max_size() << '\\n'; + } + +.SH Possible output: + + Maximum size of a std::flat_multimap is 768,614,336,404,564,650 + +.SH See also + + size returns the number of elements + \fI(public member function)\fP diff --git a/man/std::flat_multimap::operator=.3 b/man/std::flat_multimap::operator=.3 new file mode 100644 index 000000000..b323e4c0e --- /dev/null +++ b/man/std::flat_multimap::operator=.3 @@ -0,0 +1,92 @@ +.TH std::flat_multimap::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::operator= \- std::flat_multimap::operator= + +.SH Synopsis + flat_multimap& operator=( const flat_multimap& other ); \fB(1)\fP (since C++23) + (implicitly declared) + flat_multimap& operator=( flat_multimap&& other ); \fB(2)\fP (since C++23) + (implicitly declared) + flat_multimap& operator=( \fB(3)\fP (since C++23) + std::initializer_list ilist ); + + Replaces the contents of the container adaptor with the contents of given argument. + + 1) Copy assignment operator. Replaces the contents with a copy of the contents of + other. Effectively calls c = other.c; comp = other.comp;. + 2) Move assignment operator. Replaces the contents with those of other using move + semantics. Effectively calls c = std::move(other.c); comp = std::move(other.comp);. + 3) Replaces the contents with those identified by initializer list ilist. + +.SH Parameters + + other - another container adaptor to be used as source + ilist - initializer list to be used as source + +.SH Return value + + *this + +.SH Complexity + + 1,2) Equivalent to that of operator= of the underlying container. + 3) Linear in the size of *this and ilist. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_multimap x{{1, 1}, {2, 2}, {3, 3}}, y, z; + const auto w = {std::pair{4, 4}, {5, 5}, {6, 6}, {7, 7}}; + + std::println("Initially:"); + std::println("x = {}", x); + std::println("y = {}", y); + std::println("z = {}", z); + + y = x; // overload (1) + std::println("Copy assignment copies data from x to y:"); + std::println("x = {}", x); + std::println("y = {}", y); + + z = std::move(x); // overload (2) + std::println("Move assignment moves data from x to z, modifying both x and z:"); + std::println("x = {}", x); + std::println("z = {}", z); + + z = w; // overload (3) + std::println("Assignment of initializer_list w to z:"); + std::println("w = {}", w); + std::println("z = {}", z); + } + +.SH Output: + + Initially: + x = {1: 1, 2: 2, 3: 3} + y = {} + z = {} + Copy assignment copies data from x to y: + x = {1: 1, 2: 2, 3: 3} + y = {1: 1, 2: 2, 3: 3} + Move assignment moves data from x to z, modifying both x and z: + x = {} + z = {1: 1, 2: 2, 3: 3} + Assignment of initializer_list w to z: + w = {4: 4, 5: 5, 6: 6, 7: 7} + z = {4: 4, 5: 5, 6: 6, 7: 7} + +.SH See also + + constructor constructs the flat_multimap + \fI(public member function)\fP + replace replaces the underlying containers + \fI(public member function)\fP diff --git a/man/std::flat_multimap::rbegin,.3 b/man/std::flat_multimap::rbegin,.3 new file mode 100644 index 000000000..6629e1fb6 --- /dev/null +++ b/man/std::flat_multimap::rbegin,.3 @@ -0,0 +1,87 @@ +.TH std::flat_multimap::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::rbegin, \- std::flat_multimap::rbegin, + +.SH Synopsis + + reverse_iterator rbegin() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rbegin() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the first element of the reversed flat_multimap. It + corresponds to the last element of the non-reversed flat_multimap. If the + flat_multimap is empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_multimap map + { + {"█", 1}, + {"▒", 5}, + {"░", 3}, + {"▓", 7}, + {"▓", 8}, + {"░", 4}, + {"▒", 6}, + {"█", 2} + }; + + std::cout << "Print out in reverse order using const reverse iterators:\\n"; + std::for_each(map.crbegin(), map.crend(), + [](std::pair const& e) + { + std::cout << "{ \\"" << e.first << "\\", " << e.second << " };\\n"; + }); + + map.rbegin()->second = 42; // OK: non-const value is modifiable + // map.crbegin()->second = 42; // Error: cannot modify the const value + } + +.SH Possible output: + + Print out in reverse order using const reverse iterators: + { "▓", 8 }; + { "▓", 7 }; + { "▒", 6 }; + { "▒", 5 }; + { "░", 4 }; + { "░", 3 }; + { "█", 2 }; + { "█", 1 }; + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multimap::rend,.3 b/man/std::flat_multimap::rend,.3 new file mode 100644 index 000000000..88c0d7c66 --- /dev/null +++ b/man/std::flat_multimap::rend,.3 @@ -0,0 +1,84 @@ +.TH std::flat_multimap::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::rend, \- std::flat_multimap::rend, + +.SH Synopsis + + reverse_iterator rend() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rend() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crend() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the element following the last element of the reversed + flat_multimap. It corresponds to the element preceding the first element of the + non-reversed flat_multimap. This element acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono; + + int main() + { + const std::flat_multimap messages + { + {February/17/2023, 10}, + {February/17/2023, 20}, + {February/16/2022, 30}, + {October/22/2022, 40}, + {June/14/2022, 50}, + {November/23/2021, 60}, + {December/10/2022, 55}, + {December/12/2021, 45}, + {April/1/2020, 42}, + {April/1/2020, 24} + }; + + std::cout << "Messages received (date order is reversed):\\n"; + for (auto it = messages.crbegin(); it != messages.crend(); ++it) + std::cout << it->first << " : " << it->second << '\\n'; + } + +.SH Possible output: + + Messages received (date order is reversed): + 2023-02-17 : 20 + 2023-02-17 : 10 + 2022-12-10 : 55 + 2022-10-22 : 40 + 2022-06-14 : 50 + 2022-02-16 : 30 + 2021-12-12 : 45 + 2021-11-23 : 60 + 2020-04-01 : 24 + 2020-04-01 : 42 + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multimap::replace.3 b/man/std::flat_multimap::replace.3 new file mode 100644 index 000000000..0d6468398 --- /dev/null +++ b/man/std::flat_multimap::replace.3 @@ -0,0 +1,74 @@ +.TH std::flat_multimap::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::replace \- std::flat_multimap::replace + +.SH Synopsis + void replace( key_container_type&& key_cont, mapped_container_type&& (since C++23) + mapped_cont ); + + Replaces the underlying containers c. Equivalent to: + + c.keys = std::move(key_cont); + c.values = std::move(mapped_cont); + + The following conditions must be met: + + * The expression key_cont.size() == mapped_cont.size() is true, + * The elements of key_cont are sorted with respect to compare. + + Otherwise, the behavior is undefined. + +.SH Parameters + + keys_cont - a sorted keys container of type KeyContainer, the contents of which + will be moved into *this + mapped_cont - a container of mapped values of type MappedContainer, the contents of + which will be moved into *this + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Equals to complexity of std::move applied to adapted containers. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector keys{1, 2, 3}; + assert(std::ranges::is_sorted(keys)); + std::vector values{2.2, 3.3, 1.1}; + assert(keys.size() == values.size()); + + std::flat_multimap map; + assert(map.empty()); + + map.replace(keys, values); + assert(map.size() == 3); + assert(map.keys() == 3); + assert(map.values() == 3); + assert(keys.empty()); + assert(values.empty()); + + std::println("{}", map); + } + +.SH Output: + + {1: 2.2, 2: 3.3, 3: 1.1} + +.SH See also + + extract extracts the underlying containers + \fI(public member function)\fP diff --git a/man/std::flat_multimap::size.3 b/man/std::flat_multimap::size.3 new file mode 100644 index 000000000..5f2bedc5d --- /dev/null +++ b/man/std::flat_multimap::size.3 @@ -0,0 +1,56 @@ +.TH std::flat_multimap::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::size \- std::flat_multimap::size + +.SH Synopsis + size_type size() const noexcept; (since C++23) + + Returns the number of elements in the container adaptor. Equivalent to return + c.keys.size(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements in the container adaptor. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses size to display the number of elements in a + std::flat_multimap: + + +// Run this code + + #include + #include + + int main() + { + std::flat_multimap nums{{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; + + std::cout << "nums contains " << nums.size() << " elements.\\n"; + } + +.SH Output: + + nums contains 4 elements. + +.SH See also + + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + max_size returns the maximum possible number of elements + \fI(public member function)\fP diff --git a/man/std::flat_multimap::swap.3 b/man/std::flat_multimap::swap.3 new file mode 100644 index 000000000..6a6e3b38a --- /dev/null +++ b/man/std::flat_multimap::swap.3 @@ -0,0 +1,42 @@ +.TH std::flat_multimap::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::swap \- std::flat_multimap::swap + +.SH Synopsis + void swap( flat_multimap& other ) noexcept; (since C++23) + + Exchanges the contents of the container adaptor with those of other. Effectively + calls + + ranges::swap(compare, other.compare); + ranges::swap(c.keys, other.c.keys); + ranges::swap(c.values, other.c.values); + +.SH Parameters + + other - container adaptor to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + \fI(none)\fP + +.SH Complexity + + Same as underlying container (typically constant). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::flat_multimap) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multimap::upper_bound.3 b/man/std::flat_multimap::upper_bound.3 new file mode 100644 index 000000000..90df91c6b --- /dev/null +++ b/man/std::flat_multimap::upper_bound.3 @@ -0,0 +1,46 @@ +.TH std::flat_multimap::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::upper_bound \- std::flat_multimap::upper_bound + +.SH Synopsis + iterator upper_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator upper_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator upper_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is greater than key. If no such element + is found, past-the-end (see end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multimap::value_comp.3 b/man/std::flat_multimap::value_comp.3 new file mode 100644 index 000000000..54c7798a5 --- /dev/null +++ b/man/std::flat_multimap::value_comp.3 @@ -0,0 +1,77 @@ +.TH std::flat_multimap::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::value_comp \- std::flat_multimap::value_comp + +.SH Synopsis + std::flat_multimap::value_compare value_comp() const; (since C++23) + + Returns a function object that compares objects of type + std::flat_multimap::value_type (key-value pairs) by using key_comp to compare the + first components of the pairs. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_multimap cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.value_comp(); + + for (const std::pair val = {100, 'a'}; auto it : cont) + { + const bool before = comp_func(it, val); + const bool after = comp_func(val, it); + + std::cout << '(' << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val.first << ")\\n"; + else if (before) + std::cout << "goes before key (" << val.first << ")\\n"; + else if (after) + std::cout << "goes after key (" << val.first << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + +.SH See also + + key_comp returns the function that compares keys + \fI(public member function)\fP diff --git a/man/std::flat_multimap::value_compare.3 b/man/std::flat_multimap::value_compare.3 new file mode 100644 index 000000000..4eb3d9999 --- /dev/null +++ b/man/std::flat_multimap::value_compare.3 @@ -0,0 +1,53 @@ +.TH std::flat_multimap::value_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::value_compare \- std::flat_multimap::value_compare + +.SH Synopsis + class value_compare; (since C++23) + + std::flat_multimap::value_compare is a function object that compares objects of type + std::flat_multimap::const_reference (a pair of references to the stored key/value) + by comparing the first components (i.e. keys) of the passed pairs. + +.SH Member objects + + Member name Definition + the comparison function object of type + comp (private) std::flat_multimap::key_compare + (exposition-only member object*) + +.SH Member functions + + constructor constructs value_compare object + (private) \fI(public member function)\fP + operator() compares two values of type value_type + \fI(public member function)\fP + +std::flat_multimap::value_compare::value_compare + + private: (exposition only*) + value_compare( key_compare c ); + + Initializes the underlying instance of the comparator comp to c. + +.SH Parameters + + c - a comparator to assign + +std::flat_multimap::value_compare::operator() + + bool operator()( const const_reference& lhs, const const_reference& rhs ) const; + + Compares lhs.first and rhs.first by calling the stored comparator comp. + +.SH Parameters + + lhs, rhs - values to compare + +.SH Return value + + comp(lhs.first, rhs.first) + +.SH Exceptions + + May throw implementation-defined exceptions. diff --git a/man/std::flat_multimap::values.3 b/man/std::flat_multimap::values.3 new file mode 100644 index 000000000..470b7621f --- /dev/null +++ b/man/std::flat_multimap::values.3 @@ -0,0 +1,50 @@ +.TH std::flat_multimap::values 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multimap::values \- std::flat_multimap::values + +.SH Synopsis + const mapped_container_type& values() const noexcept; (since C++23) + + Return a constant reference to the adapted values container. Equivalent to return + c.values;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying values container. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::flat_multimap map{{1, 1.1}, {2, 2.2}, {3, 3.3}}; + + // The default values container is std::vector: + static_assert(std::is_same_v&>); + + std::println("{}", map.values()); + } + +.SH Output: + + [1.1, 2.2, 3.3] + +.SH See also + + keys direct access to the underlying keys container + \fI(public member function)\fP diff --git a/man/std::flat_multiset.3 b/man/std::flat_multiset.3 new file mode 100644 index 000000000..a912c7fb5 --- /dev/null +++ b/man/std::flat_multiset.3 @@ -0,0 +1,194 @@ +.TH std::flat_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset \- std::flat_multiset + +.SH Synopsis + Defined in header + template< + + class Key, + class Compare = std::less, (since C++23) + class KeyContainer = std::vector + + > class flat_multiset; + + The flat multiset is a container adaptor that gives the functionality of an + associative container that stores a sorted set of objects of type Key. Unlike + std::flat_set, multiple keys with equivalent values are allowed. Sorting is done + using the key comparison function Compare. + + The class template flat_multiset acts as a wrapper to the underlying sorted + container passed as object of type KeyContainer. + + Everywhere the standard library uses the Compare requirements, uniqueness is + determined by using the equivalence relation. Informally, two objects a and b are + considered equivalent if neither compares less than the other: !comp(a, b) && + !comp(b, a). + + std::flat_multiset meets the requirements of Container, ReversibleContainer, + optional container requirements, and all requirements of AssociativeContainer + (including logarithmic search complexity), except that: + + * requirements related to nodes are not applicable, + * iterator invalidation requirements differ, + * the complexity of insertion and erasure operations is linear. + + A flat multiset supports most AssociativeContainer's operations that use equal keys. + +.SH Template parameters + + Key - The type of the stored elements. The program is ill-formed if Key is + not the same type as KeyContainer::value_type. + Compare - A Compare type providing a strict weak ordering. + The type of the underlying SequenceContainer to store the elements. + The iterators of such container should satisfy + KeyContainer - LegacyRandomAccessIterator or model random_access_iterator. + + The standard containers std::vector and std::deque satisfy these + requirements. + +.SH Member types + + Member type Definition + container_type KeyContainer + key_type Key + value_type Key + key_compare Compare + value_compare Compare + reference value_type& + const_reference const value_type& + size_type typename KeyContainer::size_type + difference_type typename KeyContainer::difference_type + iterator implementation-defined LegacyRandomAccessIterator and + random_access_iterator to value_type + const_iterator implementation-defined LegacyRandomAccessIterator and + random_access_iterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + +.SH Member objects + + Member name Definition + c (private) the underlying container of container_type + (exposition-only member object*) + compare (private) the comparison function object of type key_compare + (exposition-only member object*) + +.SH Member functions + + constructor constructs the flat_multiset + \fI(public member function)\fP + destructor destroys every element of the container adaptor + (implicitly declared) \fI(public member function)\fP + operator= assigns values to the container adaptor + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Capacity + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP +.SH Modifiers + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + insert_range inserts a range of elements + \fI(public member function)\fP + extract extracts the underlying container + \fI(public member function)\fP + replace replaces the underlying container + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP +.SH Lookup + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + returns an iterator to the first element not less than the + lower_bound given key + \fI(public member function)\fP + returns an iterator to the first element greater than the + upper_bound given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP +.SH Observers + key_comp returns the function that compares keys + \fI(public member function)\fP + returns the function that compares keys in objects of type + value_comp value_type + \fI(public member function)\fP + +.SH Non-member functions + + operator== lexicographically compares the values of two + operator<=> flat_multisets + (C++23) \fI(function template)\fP + std::swap(std::flat_multiset) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + erase_if(std::flat_multiset) erases all elements satisfying specific criteria + (C++23) \fI(function template)\fP + +.SH Helper classes + + std::uses_allocator specializes the std::uses_allocator type + (C++23) trait + \fI(class template specialization)\fP + + Tags + + sorted_equivalent indicates that elements of a range are sorted (uniqueness is not + sorted_equivalent_t required) + (C++23) (tag) + + Deduction guides + +.SH Notes + + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_flat_set 202207L (C++23) std::flat_set and std::flat_multiset + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + flat_set adapts a container to provide a collection of unique keys, sorted + (C++23) by keys + \fI(class template)\fP + multiset collection of keys, sorted by keys + \fI(class template)\fP + unordered_multiset collection of keys, hashed by keys + \fI(C++11)\fP \fI(class template)\fP + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::flat_multiset::begin,.3 b/man/std::flat_multiset::begin,.3 new file mode 100644 index 000000000..55b068fe9 --- /dev/null +++ b/man/std::flat_multiset::begin,.3 @@ -0,0 +1,65 @@ +.TH std::flat_multiset::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::begin, \- std::flat_multiset::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP (since C++23) + const_iterator begin() const noexcept; \fB(2)\fP (since C++23) + const_iterator cbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the first element of the flat_multiset. + + If the flat_multiset is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multiset set{3, 1, 4, 1, 5, 9, 2, 6, 5}; + std::for_each(set.cbegin(), set.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: + + 1 1 2 3 4 5 5 6 9 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multiset::clear.3 b/man/std::flat_multiset::clear.3 new file mode 100644 index 000000000..b026d0955 --- /dev/null +++ b/man/std::flat_multiset::clear.3 @@ -0,0 +1,61 @@ +.TH std::flat_multiset::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::clear \- std::flat_multiset::clear + +.SH Synopsis + void clear() noexcept; (since C++23) + + Erases all elements from the container adaptor. After this call, size() returns + zero. + + Invalidates any references, pointers, and iterators referring to contained elements. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the size of the container adaptor, i.e., the number of elements. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::flat_multiset& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::flat_multiset container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + +.SH See also + + erase erases elements + \fI(public member function)\fP diff --git a/man/std::flat_multiset::contains.3 b/man/std::flat_multiset::contains.3 new file mode 100644 index 000000000..656ad808c --- /dev/null +++ b/man/std::flat_multiset::contains.3 @@ -0,0 +1,60 @@ +.TH std::flat_multiset::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::contains \- std::flat_multiset::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multiset example{1, 2, 3, 4}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_multiset::count.3 b/man/std::flat_multiset::count.3 new file mode 100644 index 000000000..3306ad33d --- /dev/null +++ b/man/std::flat_multiset::count.3 @@ -0,0 +1,46 @@ +.TH std::flat_multiset::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::count \- std::flat_multiset::count + +.SH Synopsis + size_type count( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + size_type count( const K& x ) const; + + Returns the number of elements with key that compares equivalent to the specified + argument. + + 1) Returns the number of elements with key key. + 2) Returns the number of elements with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the elements to count + x - alternative value to compare to the keys + +.SH Return value + + Number of elements with key that compares equivalent to key or x. + +.SH Complexity + + Logarithmic in the size of the container plus linear in the number of elements + found. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multiset::emplace.3 b/man/std::flat_multiset::emplace.3 new file mode 100644 index 000000000..045e3b167 --- /dev/null +++ b/man/std::flat_multiset::emplace.3 @@ -0,0 +1,55 @@ +.TH std::flat_multiset::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::emplace \- std::flat_multiset::emplace + +.SH Synopsis + template< class... Args > (since C++23) + iterator emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args. + + First, initializes an object t of type value_type with std::forward(args)..., + then inserts t as if by + + auto it = ranges::upper_bound(c, t, compare); + c.insert(it, std::move(t)); + + This overload participates in overload resolution only if + std::is_constructible_v is true. + + Careful use of emplace allows the new element to be constructed while avoiding + unnecessary copy or move operations. + + Information on iterator invalidation is copied from here + +.SH Parameters + + args - arguments to forward to the constructor of the element + +.SH Return value + + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multiset::emplace_hint.3 b/man/std::flat_multiset::emplace_hint.3 new file mode 100644 index 000000000..56c4c3eff --- /dev/null +++ b/man/std::flat_multiset::emplace_hint.3 @@ -0,0 +1,49 @@ +.TH std::flat_multiset::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::emplace_hint \- std::flat_multiset::emplace_hint + +.SH Synopsis + template< class... Args > (since C++23) + iterator emplace_hint( const_iterator hint, Args&&... args ); + + Inserts a new element into the container as close as possible to the position just + before hint. + + The constructors of the key and mapped value are called with exactly the same + arguments as supplied to the function, forwarded with std::forward(args).... + + Information on iterator invalidation is copied from here + +.SH Parameters + + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + This section is incomplete + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::flat_multiset::empty.3 b/man/std::flat_multiset::empty.3 new file mode 100644 index 000000000..2778a057a --- /dev/null +++ b/man/std::flat_multiset::empty.3 @@ -0,0 +1,57 @@ +.TH std::flat_multiset::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::empty \- std::flat_multiset::empty + +.SH Synopsis + [[nodiscard]] bool empty() const noexcept; (since C++23) + + Checks if the underlying container has no elements. Equivalent to return begin() == + end();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the underlying container is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses empty to check if a std::flat_multiset contains any + elements: + + +// Run this code + + #include + #include + + int main() + { + std::flat_multiset numbers; + std::cout << std::boolalpha; + std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; + + numbers.insert(42); + numbers.insert(19937); + std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; + } + +.SH Output: + + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false + +.SH See also + + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::flat_multiset::end,.3 b/man/std::flat_multiset::end,.3 new file mode 100644 index 000000000..a9084e61c --- /dev/null +++ b/man/std::flat_multiset::end,.3 @@ -0,0 +1,66 @@ +.TH std::flat_multiset::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::end, \- std::flat_multiset::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP (since C++23) + const_iterator end() const noexcept; \fB(2)\fP (since C++23) + const_iterator cend() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the element following the last element of the flat_multiset. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multiset set{3, 1, 4, 1, 5, 9, 2, 6, 5}; + std::for_each(set.cbegin(), set.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: + + 1 1 2 3 4 5 5 6 9 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multiset::equal_range.3 b/man/std::flat_multiset::equal_range.3 new file mode 100644 index 000000000..5aee5b20a --- /dev/null +++ b/man/std::flat_multiset::equal_range.3 @@ -0,0 +1,109 @@ +.TH std::flat_multiset::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::equal_range \- std::flat_multiset::equal_range + +.SH Synopsis + std::pair equal_range( const Key& key ); \fB(1)\fP (since C++23) + std::pair equal_range( const Key& \fB(2)\fP (since C++23) + key ) const; + template< class K > \fB(3)\fP (since C++23) + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP (since C++23) + ) const; + + Returns a range containing all elements with the given key in the container. The + range is defined by two iterators, one pointing to the first element that is not + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). + + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + std::pair containing a pair of iterators defining the wanted range: the first + pointing to the first element that is not less than key and the second pointing to + the first element greater than key. + + If there are no elements not less than key, past-the-end (see end()) iterator is + returned as the first element. Similarly if there are no elements greater than key, + past-the-end iterator is returned as the second element. + + Since emplace and unhinted insert always insert at the upper bound, the order of + equivalent elements in the equal range is the order of insertion unless hinted + insert or emplace_hint was used to insert an element at a different position. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + template + void print_equal_range(I first, I lb, I ub, I last) + { + for (I i{first}; i != lb; ++i) + std::cout << *i << ' '; + std::cout << "[ "; + + for (I i{lb}; i != ub; ++i) + std::cout << *i << ' '; + std::cout << ") "; + + for (I i{ub}; i != last; ++i) + std::cout << *i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::flat_multiset c{4, 3, 2, 1, 3, 3}; + std::cout << "c = "; + print_equal_range(begin(c), begin(c), end(c), end(c)); + for (int key{}; key != 6; ++key) + { + std::cout << "key = " << key << "; equal range = "; + const auto [lb, ub] = c.equal_range(key); + print_equal_range(begin(c), lb, ub, end(c)); + } + } + +.SH Output: + + c = [ 1 2 3 3 3 4 ) + key = 0; equal range = [ ) 1 2 3 3 3 4 + key = 1; equal range = [ 1 ) 2 3 3 3 4 + key = 2; equal range = 1 [ 2 ) 3 3 3 4 + key = 3; equal range = 1 2 [ 3 3 3 ) 4 + key = 4; equal range = 1 2 3 3 3 [ 4 ) + key = 5; equal range = 1 2 3 3 3 4 [ ) + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::flat_multiset::erase.3 b/man/std::flat_multiset::erase.3 new file mode 100644 index 000000000..df4fef3b6 --- /dev/null +++ b/man/std::flat_multiset::erase.3 @@ -0,0 +1,100 @@ +.TH std::flat_multiset::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::erase \- std::flat_multiset::erase + +.SH Synopsis + iterator erase( iterator position ); \fB(1)\fP (since C++23) + iterator erase( const_iterator pos ); \fB(2)\fP (since C++23) + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP (since C++23) + size_type erase( const Key& key ); \fB(4)\fP (since C++23) + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. The order of the remaining equivalent + elements is preserved. + + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes all elements with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. + + Information on iterator invalidation is copied from here + + The iterator pos must be valid and dereferenceable. Thus the end() iterator (which + is valid, but is not dereferenceable) cannot be used as a value for pos. + +.SH Parameters + + pos - iterator to the element to remove + first, last - range of elements to remove + key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove + +.SH Return value + + 1-3) Iterator following the last removed element. + 4) Number of elements removed. + 5) Number of elements removed. + +.SH Exceptions + + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. + +.SH Complexity + + Depends on underlying container. Typically linear. + + This section is incomplete + Reason: revision required + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multiset c = {1, 2, 3, 4, 1, 2, 3, 4}; + + auto print = [&c] + { + std::cout << "c = { "; + for (int n : c) + std::cout << n << ' '; + std::cout << "}\\n"; + }; + print(); + + std::cout << "Erase all odd numbers:\\n"; + for (auto it = c.begin(); it != c.end();) + { + if (*it % 2 != 0) + it = c.erase(it); + else + ++it; + } + print(); + + std::cout << "Erase 1, erased count: " << c.erase(1) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + print(); + } + +.SH See also + + clear clears the contents + \fI(public member function)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::flat_multiset::extract.3 b/man/std::flat_multiset::extract.3 new file mode 100644 index 000000000..c84fd3319 --- /dev/null +++ b/man/std::flat_multiset::extract.3 @@ -0,0 +1,59 @@ +.TH std::flat_multiset::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::extract \- std::flat_multiset::extract + +.SH Synopsis + container_type extract() &&; (since C++23) + + Extracts adapted container c. Equivalent to return std::move(c);. + + After this operation *this is empty, even if an exception is thrown. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + std::move(c). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::flat_multiset set{1, 2, 3}; + const auto size = set.size(); + + auto c = set.extract(); + assert(c.size() == size); + assert(set.empty()); + assert(set.keys().empty()); + assert(set.values().empty()); + + // The default keys container is std::vector: + static_assert(std::is_same_v>); + + std::println("{}", c); + } + +.SH Output: + + [1, 2, 3] + +.SH See also + + replace replaces the underlying container + \fI(public member function)\fP diff --git a/man/std::flat_multiset::find.3 b/man/std::flat_multiset::find.3 new file mode 100644 index 000000000..ac1e875f5 --- /dev/null +++ b/man/std::flat_multiset::find.3 @@ -0,0 +1,90 @@ +.TH std::flat_multiset::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::find \- std::flat_multiset::find + +.SH Synopsis + iterator find( const Key& key ); \fB(1)\fP (since C++23) + const_iterator find( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator find( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator find( const K& x ) const; + + 1,2) Finds an element with key equivalent to key. If there are several elements with + the requested key in the container, any of them may be returned. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + + int main() + { + // Simple comparison demo. + std::flat_multiset example{1, 2, 3, 4}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << (*search) << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::flat_multiset> example2{{1, {}}, {2, {}}, {3, {}}, {4, {}}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->x << '\\n'; + else + std::cout << "Not found\\n"; + } + +.SH Output: + + Found 2 + Found 2 + +.SH See also + + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_multiset::flat_multiset.3 b/man/std::flat_multiset::flat_multiset.3 new file mode 100644 index 000000000..d1160fc4e --- /dev/null +++ b/man/std::flat_multiset::flat_multiset.3 @@ -0,0 +1,254 @@ +.TH std::flat_multiset::flat_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::flat_multiset \- std::flat_multiset::flat_multiset + +.SH Synopsis + flat_multiset() \fB(1)\fP (since C++23) + : flat_multiset(key_compare()) { } + template< class Allocator > + flat_multiset( const flat_multiset& other, const Allocator& alloc \fB(2)\fP (since C++23) + ); + template< class Allocator > \fB(3)\fP (since C++23) + flat_multiset( flat_multiset&& other, const Allocator& alloc ); + explicit flat_multiset( container_type cont, + const key_compare& comp = key_compare() \fB(4)\fP (since C++23) + ); + template< class Allocator > + flat_multiset( const container_type& cont, const Allocator& alloc \fB(5)\fP (since C++23) + ); + template< class Allocator > + + flat_multiset( const container_type& cont, const key_compare& \fB(6)\fP (since C++23) + comp, + + const Allocator& alloc ); + flat_multiset( std::sorted_equivalent_t s, container_type cont, + + const key_compare& comp = key_compare() ) \fB(7)\fP (since C++23) + + : c(std::move(cont)), compare(comp) { } + template< class Allocator > + + flat_multiset( std::sorted_equivalent_t s, const container_type& \fB(8)\fP (since C++23) + cont, + + const Allocator& alloc ); + template< class Allocator > + + flat_multiset( std::sorted_equivalent_t s, const container_type& \fB(9)\fP (since C++23) + cont, + + const key_compare& comp, const Allocator& alloc ); + explicit flat_multiset( const key_compare& comp ) \fB(10)\fP (since C++23) + : c(), compare(comp) { } + template< class Allocator > \fB(11)\fP (since C++23) + flat_multiset( const key_compare& comp, const Allocator& alloc ); + template< class Allocator > \fB(12)\fP (since C++23) + explicit flat_multiset( const Allocator& alloc ); + template< class InputIter > + + flat_multiset( InputIter first, InputIter last, \fB(13)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(), compare(comp); + template< class InputIter, class Allocator > + + flat_multiset( InputIter first, InputIter last, \fB(14)\fP (since C++23) + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + flat_multiset( InputIter first, InputIter last, const Allocator& \fB(15)\fP (since C++23) + alloc ); + template< container-compatible-range R > + + flat_multiset( std::from_range_t, R&& rg, const key_compare& comp \fB(16)\fP (since C++23) + ) + + : flat_multiset(comp); + template< container-compatible-range R > + + flat_multiset( std::from_range_t fr, R&& rg ) \fB(17)\fP (since C++23) + + : flat_multiset( fr, std::forward(rg), key_compare() ) { } + template< container-compatible-range R, class + Allocator > \fB(18)\fP (since C++23) + flat_multiset( std::from_range_t, R&& rg, const Allocator& alloc + ); + template< container-compatible-range R, class + Allocator > + + flat_multiset( std::from_range_t, R&& rg, const key_compare& \fB(19)\fP (since C++23) + comp, + + const Allocator& alloc ); + template< class InputIter > + + flat_multiset( std::sorted_equivalent_t s, InputIter first, + InputIter last, \fB(20)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(first, last), compare(comp) { } + template< class InputIter, class Allocator > + + flat_multiset( std::sorted_equivalent_t s, InputIter first, \fB(21)\fP (since C++23) + InputIter last, + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + + flat_multiset( std::sorted_equivalent_t s, InputIter first, \fB(22)\fP (since C++23) + InputIter last, + + const Allocator& alloc ); + flat_multiset( std::initializer_list init, + + const key_compare& comp = key_compare() ) \fB(23)\fP (since C++23) + + : flat_multiset(init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_multiset( std::initializer_list init, const \fB(24)\fP (since C++23) + key_compare& comp, + + const Allocator& alloc ); + template< class Allocator > + flat_multiset( std::initializer_list init, const \fB(25)\fP (since C++23) + Allocator& alloc ); + flat_multiset( std::sorted_equivalent_t s, + std::initializer_list init, + \fB(26)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : flat_multiset(s, init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_multiset( std::sorted_equivalent_t s, \fB(27)\fP (since C++23) + std::initializer_list init, + + const key_compare& comp, const Allocator& alloc ); + template< class Allocator > + + flat_multiset( std::sorted_equivalent_t s, \fB(28)\fP (since C++23) + std::initializer_list init, + + const Allocator& alloc ); + + Constructs new container adaptor from a variety of data sources and optionally + provided comparison function object comp and/or allocator alloc. + + 1) A default constructor. Constructs an empty container adaptor. + 2) A copy constructor. Constructs c with the copy of the contents of other.c and + compare with other.compare. See allocator usage note below. + 3) A move constructor. Constructs the container adaptor with the contents of other + using move semantics. See allocator usage note below. + 4) Constructs the underlying container with the contents of the container cont. + First, initializes c with std::move(cont) and compare with comp. Then sorts the c + with respect to comp. + 5) Same as \fB(4)\fP, equivalent to flat_multiset(cont);. See allocator usage note below. + 6) Same as \fB(4)\fP, equivalent to flat_multiset(cont, comp);. See allocator usage note + below. + 7) Constructs the underlying container with the contents of the other container + cont. Initializes c with std::move(cont) and compare with comp. + 8) Same as \fB(7)\fP, equivalent to flat_multiset(s, cont);. See allocator usage note + below. + 9) Same as \fB(7)\fP, equivalent to flat_multiset(s, cont, comp);. See allocator usage + note below. + 10) Constructs an empty container adaptor. + 11,12) Constructs an empty container adaptor. See allocator usage note below. + 13) Constructs the container adaptor with the contents of the range [first, last), + equivalent to insert(first, last);. + 14,15) Same as \fB(13)\fP. See allocator usage note below. + 16) Constructs the container adaptor with the contents of the range rg. First, uses + \fB(10)\fP as delegating constructor. Then initializes c with the contents of rg as if by + insert_range(std::forward(rg));. + 17) Same as \fB(16)\fP using it as delegating constructor. + 18,19) Same as \fB(16)\fP. See allocator usage note below. + 20) Constructs the underlying container with the contents of the range + [first, last). Initializes c with c(first, last) and compare with compare(comp). + 21,22) Same as \fB(20)\fP. See allocator usage note below. + 23) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(13)\fP as delegating constructor. + 24,25) Same as \fB(23)\fP. See allocator usage note below. + 26) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(20)\fP as delegating constructor. + 27,28) Save as \fB(26)\fP. See allocator usage note below. + + Note for overloads (13-15,20-22): If [first, last) is not a valid range, the + behavior is undefined. + +.SH Parameters + + cont - a container to be used as source to initialize the underlying + container + other - another flat_multiset to be used as source to initialize the elements + of the underlying container with + alloc - an allocator to use for all memory allocations of the underlying + container + comp - a function object to be used for all comparisons of keys + first, last - a range to copy the elements from + init - an initializer list to initialize the elements of the underlying + container with + a container compatible range (that is, an input_range whose elements + rg - are convertible to value_type) to be used as source to initialize the + underlying container + fr - a disambiguation tag that indicates that the contained member should + be range constructed + s - a disambiguation tag that indicates that the input sequence is sorted + with respect to compare +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + Compare must meet the requirements of Compare. + - + Allocator must meet the requirements of Allocator. + +.SH Complexity + + 1) Constant. + 2) Linear in size of other. + 3) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 4-6) Linear in \\(\\scriptsize N\\)N if cont is sorted with respect to compare, + otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of cont.size() before this call. + 7-9) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 10-12) Constant. + 13-15) Linear in \\(\\scriptsize N\\)N if the input range [first, last) is sorted with + respect to compare, otherwise \\(\\scriptsize + \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where \\(\\scriptsize N\\)N is the value of + cont.size() before this call. + 16-19) Linear in \\(\\scriptsize N\\)N if the input range rg is sorted with respect to + compare, otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of cont.size() before this call. + 20-22) Linear in size of [first, last). + 23-25) Linear in \\(\\scriptsize N\\)N if the elements of init are sorted with respect + to compare, otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of cont.size() before this call. + 26-28) Linear in size of init. + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload (3,16-19)), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns values to the container adaptor + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multiset::insert.3 b/man/std::flat_multiset::insert.3 new file mode 100644 index 000000000..32bebefdd --- /dev/null +++ b/man/std::flat_multiset::insert.3 @@ -0,0 +1,98 @@ +.TH std::flat_multiset::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::insert \- std::flat_multiset::insert + +.SH Synopsis + iterator insert( const value_type& value ) \fB(1)\fP (since C++23) + iterator insert( value_type&& value ); \fB(2)\fP (since C++23) + iterator insert( const_iterator pos, const value_type& value ); \fB(3)\fP (since C++23) + iterator insert( const_iterator pos, value_type&& value ); \fB(4)\fP (since C++23) + template< class InputIt > \fB(5)\fP (since C++23) + void insert( InputIt first, InputIt last ); + template< class InputIt > + void insert( std::sorted_equivalent_t, InputIt first, InputIt last \fB(6)\fP (since C++23) + ); + void insert( std::initializer_list ilist ); \fB(7)\fP (since C++23) + void insert( std::sorted_equivalent_t s, \fB(8)\fP (since C++23) + std::initializer_list ilist ); + + Inserts element(s) into the container. The order of the remaining equivalent + elements is preserved. + + 1) Inserts value. If the container has elements with equivalent key, inserts at the + upper bound of that range. Equivalent to return emplace(value);. + 2) Inserts value. If the container has elements with equivalent key, inserts at the + upper bound of that range. Equivalent to return emplace(std::move(value));. + 3) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, value);. + 4) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, std::move(value));. + 5) Inserts elements from range [first, last) as if performing the following + operations sequentially: + 1. Adds elements to c as if by c.insert(c.end(), first, last);. + 2. Sorts the range of newly inserted elements with respect to compare. + 3. Merges the resulting sorted range and the sorted range of pre-existing elements + into a single sorted range. + May allocate memory during the in-place merge stage. + 6) Inserts elements from range [first, last). Equivalent to insert(first, last);. + 7) Inserts elements from initializer list ilist. Equivalent to insert(ilist.begin(), + ilist.end());. + 8) Inserts elements from initializer list ilist. Equivalent to insert(s, + ilist.begin(), ilist.end());. + + Information on iterator invalidation is copied from here + +.SH Parameters + + pos - iterator to the position before which the new element will be inserted + value - element value to insert + first, last - range of elements to insert + ilist - initializer list to insert the values from + s - a disambiguation tag indicating that the input sequence is sorted + (with respect to key_compare) +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1-4) An iterator to the inserted element. + 5-8) \fI(none)\fP + +.SH Exceptions + + 1-4) Depends on underlying container. + 5-8) No exception safety guarantee. + + This section is incomplete + Reason: exception guarantees 1..8 + +.SH Complexity + + 1-4) Linear. + 5) N + M·log(M), where NN is the size() before the operation and M is + std::distance(first, last). + 6) Linear. + 7) N + M·log(M), where NN is the size() before the operation and M is ilist.size(). + 8) Linear. + + This section is incomplete + Reason: recheck the complexity: 1-4, 8 + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::flat_multiset::insert_range.3 b/man/std::flat_multiset::insert_range.3 new file mode 100644 index 000000000..3dfadb902 --- /dev/null +++ b/man/std::flat_multiset::insert_range.3 @@ -0,0 +1,74 @@ +.TH std::flat_multiset::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::insert_range \- std::flat_multiset::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg into underlying container c as if by: + + for (const auto& e : rg) + c.insert(c.end(), e); + + Then, sorts the range of newly inserted elements with respect to compare. Merges the + resulting sorted range and the sorted range of pre-existing elements into a single + sorted range. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + Information on iterator invalidation is copied from here + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N + M·log(M), where N is size() before the operation and M is ranges::distance(rg). + +.SH Notes + + Since insert_range performs an in-place merge operation, that may allocate memory. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto, auto const& container) + { + for (const auto& elem : container) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::flat_multiset{1, 3, 2, 4}; + const auto rg = {-1, 3, -2}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + -2 -1 1 2 3 3 4 + +.SH See also + + insert inserts elements + \fI(public member function)\fP diff --git a/man/std::flat_multiset::key_comp.3 b/man/std::flat_multiset::key_comp.3 new file mode 100644 index 000000000..d340cbf5a --- /dev/null +++ b/man/std::flat_multiset::key_comp.3 @@ -0,0 +1,75 @@ +.TH std::flat_multiset::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::key_comp \- std::flat_multiset::key_comp + +.SH Synopsis + key_compare key_comp() const; (since C++23) + + Returns the function object that compares the keys, which is a copy of this + container's constructor argument comp. It is the same as value_comp. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The key comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_multiset cont{1, 2, 3, 4, 5}; + + auto comp_func = cont.key_comp(); + + for (const int key : cont) + { + const bool before = comp_func(key, 100); + const bool after = comp_func(100, key); + + std::cout << '(' << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + +.SH See also + + value_comp returns the function that compares keys in objects of type value_type + \fI(public member function)\fP diff --git a/man/std::flat_multiset::lower_bound.3 b/man/std::flat_multiset::lower_bound.3 new file mode 100644 index 000000000..784f5f8c1 --- /dev/null +++ b/man/std::flat_multiset::lower_bound.3 @@ -0,0 +1,47 @@ +.TH std::flat_multiset::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::lower_bound \- std::flat_multiset::lower_bound + +.SH Synopsis + iterator lower_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is not less than key. If no such element + is found, a past-the-end iterator (see end()) is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multiset::max_size.3 b/man/std::flat_multiset::max_size.3 new file mode 100644 index 000000000..1008f735d --- /dev/null +++ b/man/std::flat_multiset::max_size.3 @@ -0,0 +1,54 @@ +.TH std::flat_multiset::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::max_size \- std::flat_multiset::max_size + +.SH Synopsis + size_type max_size() const noexcept; (since C++23) + + Returns the maximum number of elements the container is able to hold due to system + or library implementation limitations, i.e. std::distance(begin(), end()) for the + largest container. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of elements. + +.SH Complexity + + Constant. + +.SH Notes + + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the + container may be limited to a value smaller than max_size() by the amount of RAM + available. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multiset q; + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "Maximum size of a std::flat_multiset is " << q.max_size() << '\\n'; + } + +.SH Possible output: + + Maximum size of a std::flat_multiset is 768,614,336,404,564,650 + +.SH See also + + size returns the number of elements + \fI(public member function)\fP diff --git a/man/std::flat_multiset::operator=.3 b/man/std::flat_multiset::operator=.3 new file mode 100644 index 000000000..53e1aa0a6 --- /dev/null +++ b/man/std::flat_multiset::operator=.3 @@ -0,0 +1,91 @@ +.TH std::flat_multiset::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::operator= \- std::flat_multiset::operator= + +.SH Synopsis + flat_multiset& operator=( const flat_multiset& other ); \fB(1)\fP (since C++23) + (implicitly declared) + flat_multiset& operator=( flat_multiset&& other ); \fB(2)\fP (since C++23) + (implicitly declared) + flat_multiset& operator=( std::initializer_list \fB(3)\fP (since C++23) + ilist ); + + Replaces the contents of the container adaptor with the contents of given argument. + + 1) Copy assignment operator. Replaces the contents with a copy of the contents of + other. Effectively calls c = other.c; comp = other.comp;. + 2) Move assignment operator. Replaces the contents with those of other using move + semantics. Effectively calls c = std::move(other.c); comp = std::move(other.comp);. + 3) Replaces the contents with those identified by initializer list ilist. + +.SH Parameters + + other - another container adaptor to be used as source + ilist - initializer list to be used as source + +.SH Return value + + *this + +.SH Complexity + + 1,2) Equivalent to that of operator= of the underlying container. + 3) Linear in the size of *this and ilist. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multiset x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + + std::println("Initially:"); + std::println("x = {}", x); + std::println("y = {}", y); + std::println("z = {}", z); + + y = x; // overload (1) + std::println("Copy assignment copies data from x to y:"); + std::println("x = {}", x); + std::println("y = {}", y); + + z = std::move(x); // overload (2) + std::println("Move assignment moves data from x to z, modifying both x and z:"); + std::println("x = {}", x); + std::println("z = {}", z); + + z = w; // overload (3) + std::println("Assignment of initializer_list w to z:"); + std::println("w = {}", w); + std::println("z = {}", z); + } + +.SH Output: + + Initially: + x = {1, 2, 3} + y = {} + z = {} + Copy assignment copies data from x to y: + x = {1, 2, 3} + y = {1, 2, 3} + Move assignment moves data from x to z, modifying both x and z: + x = {} + z = {1, 2, 3} + Assignment of initializer_list w to z: + w = {4, 5, 6, 7} + z = {4, 5, 6, 7} + +.SH See also + + constructor constructs the flat_multiset + \fI(public member function)\fP + replace replaces the underlying container + \fI(public member function)\fP diff --git a/man/std::flat_multiset::rbegin,.3 b/man/std::flat_multiset::rbegin,.3 new file mode 100644 index 000000000..3772ce812 --- /dev/null +++ b/man/std::flat_multiset::rbegin,.3 @@ -0,0 +1,75 @@ +.TH std::flat_multiset::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::rbegin, \- std::flat_multiset::rbegin, + +.SH Synopsis + + reverse_iterator rbegin() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rbegin() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the first element of the reversed flat_multiset. It + corresponds to the last element of the non-reversed flat_multiset. If the + flat_multiset is empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multiset rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ ⏼ + ⏼ + ⏼ + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multiset::rend,.3 b/man/std::flat_multiset::rend,.3 new file mode 100644 index 000000000..78ec19b73 --- /dev/null +++ b/man/std::flat_multiset::rend,.3 @@ -0,0 +1,73 @@ +.TH std::flat_multiset::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::rend, \- std::flat_multiset::rend, + +.SH Synopsis + + reverse_iterator rend() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rend() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crend() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the element following the last element of the reversed + flat_multiset. It corresponds to the element preceding the first element of the + non-reversed flat_multiset. This element acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_multiset rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ ⏼ + ⏼ + ⏼ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_multiset::replace.3 b/man/std::flat_multiset::replace.3 new file mode 100644 index 000000000..e62db0b5f --- /dev/null +++ b/man/std::flat_multiset::replace.3 @@ -0,0 +1,59 @@ +.TH std::flat_multiset::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::replace \- std::flat_multiset::replace + +.SH Synopsis + void replace( container_type&& cont ); (since C++23) + + Replaces the underlying container c. Equivalent to: c = std::move(cont);. + + The elements of cont must be sorted with respect to compare. Otherwise, the behavior + is undefined. + +.SH Parameters + + cont - a sorted container of type KeyContainer, the contents of which will be moved + into *this + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Equals to complexity of std::move applied to adapted container. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector keys{1, 2, 3}; + assert(std::ranges::is_sorted(keys)); + + std::flat_multiset set; + assert(set.empty()); + + set.replace(keys); + assert(set.size() == 3); + assert(keys.empty()); + + std::println("{}", set); // set.keys() + } + +.SH Output: + + [1, 2, 3] + +.SH See also + + extract extracts the underlying container + \fI(public member function)\fP diff --git a/man/std::flat_multiset::size.3 b/man/std::flat_multiset::size.3 new file mode 100644 index 000000000..4da08b70d --- /dev/null +++ b/man/std::flat_multiset::size.3 @@ -0,0 +1,56 @@ +.TH std::flat_multiset::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::size \- std::flat_multiset::size + +.SH Synopsis + size_type size() const noexcept; (since C++23) + + Returns the number of elements in the container adaptor. Equivalent to return + c.size(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements in the container adaptor. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses size to display the number of elements in a + std::flat_multiset: + + +// Run this code + + #include + #include + + int main() + { + std::flat_multiset nums{1, 3, 5, 7}; + + std::cout << "nums contains " << nums.size() << " elements.\\n"; + } + +.SH Output: + + nums contains 4 elements. + +.SH See also + + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + max_size returns the maximum possible number of elements + \fI(public member function)\fP diff --git a/man/std::flat_multiset::swap.3 b/man/std::flat_multiset::swap.3 new file mode 100644 index 000000000..c8d79f054 --- /dev/null +++ b/man/std::flat_multiset::swap.3 @@ -0,0 +1,41 @@ +.TH std::flat_multiset::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::swap \- std::flat_multiset::swap + +.SH Synopsis + void swap( flat_multiset& other ) noexcept; (since C++23) + + Exchanges the contents of the container adaptor with those of other. Effectively + calls + + ranges::swap(compare, other.compare); + ranges::swap(c, other.c); + +.SH Parameters + + other - container adaptor to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + \fI(none)\fP + +.SH Complexity + + Same as underlying container (typically constant). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::flat_multiset) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multiset::upper_bound.3 b/man/std::flat_multiset::upper_bound.3 new file mode 100644 index 000000000..c8a7b385b --- /dev/null +++ b/man/std::flat_multiset::upper_bound.3 @@ -0,0 +1,46 @@ +.TH std::flat_multiset::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::upper_bound \- std::flat_multiset::upper_bound + +.SH Synopsis + iterator upper_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator upper_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator upper_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is greater than key. If no such element + is found, past-the-end (see end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_multiset::value_comp.3 b/man/std::flat_multiset::value_comp.3 new file mode 100644 index 000000000..0f1d5147a --- /dev/null +++ b/man/std::flat_multiset::value_comp.3 @@ -0,0 +1,75 @@ +.TH std::flat_multiset::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_multiset::value_comp \- std::flat_multiset::value_comp + +.SH Synopsis + std::flat_multiset::value_compare value_comp() const; (since C++23) + + Returns the function object that compares the values. It is the same as key_comp. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_multiset cont{1, 2, 3, 4, 5}; + + // Same behaviour as key_comp() + auto comp_func = cont.value_comp(); + + for (const int val{100}; const int key : cont) + { + const bool before = comp_func(key, val); + const bool after = comp_func(val, key); + + std::cout << "Key (" << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val << ")\\n"; + else if (before) + std::cout << "goes before key (" << val << ")\\n"; + else if (after) + std::cout << "goes after key (" << val << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + +.SH See also + + key_comp returns the function that compares keys + \fI(public member function)\fP diff --git a/man/std::flat_set.3 b/man/std::flat_set.3 new file mode 100644 index 000000000..f8ea0d645 --- /dev/null +++ b/man/std::flat_set.3 @@ -0,0 +1,211 @@ +.TH std::flat_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set \- std::flat_set + +.SH Synopsis + Defined in header + template< + + class Key, + class Compare = std::less, (since C++23) + class KeyContainer = std::vector + + > class flat_set; + + The flat set is a container adaptor that gives the functionality of an associative + container that stores a sorted set of unique objects of type Key. Sorting is done + using the key comparison function Compare. + + The class template flat_set acts as a wrapper to the underlying sorted container + passed as object of type KeyContainer. + + Everywhere the standard library uses the Compare requirements, uniqueness is + determined by using the equivalence relation. Informally, two objects a and b are + considered equivalent if neither compares less than the other: !comp(a, b) && + !comp(b, a). + + std::flat_set meets the requirements of Container, ReversibleContainer, optional + container requirements, and all requirements of AssociativeContainer (including + logarithmic search complexity), except that: + + * requirements related to nodes are not applicable, + * iterator invalidation requirements differ, + * the complexity of insertion and erasure operations is linear. + + A flat set supports most AssociativeContainer's operations that use unique keys. + +.SH Template parameters + + Key - The type of the stored elements. The program is ill-formed if Key is + not the same type as KeyContainer::value_type. + Compare - A Compare type providing a strict weak ordering. + The type of the underlying SequenceContainer to store the elements. + The iterators of such container should satisfy + KeyContainer - LegacyRandomAccessIterator or model random_access_iterator. + + The standard containers std::vector and std::deque satisfy these + requirements. + +.SH Member types + + Member type Definition + container_type KeyContainer + key_type Key + value_type Key + key_compare Compare + value_compare Compare + reference value_type& + const_reference const value_type& + size_type typename KeyContainer::size_type + difference_type typename KeyContainer::difference_type + iterator implementation-defined LegacyRandomAccessIterator and + random_access_iterator to value_type + const_iterator implementation-defined LegacyRandomAccessIterator and + random_access_iterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + +.SH Member objects + + Member name Definition + c (private) the underlying container of container_type + (exposition-only member object*) + compare (private) the comparison function object of type key_compare + (exposition-only member object*) + +.SH Member functions + + constructor constructs the flat_set + \fI(public member function)\fP + destructor destroys every element of the container adaptor + (implicitly declared) \fI(public member function)\fP + operator= assigns values to the container adaptor + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Capacity + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP +.SH Modifiers + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + insert_range inserts a range of elements + \fI(public member function)\fP + extract extracts the underlying container + \fI(public member function)\fP + replace replaces the underlying container + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP +.SH Lookup + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + returns an iterator to the first element not less than the + lower_bound given key + \fI(public member function)\fP + returns an iterator to the first element greater than the + upper_bound given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP +.SH Observers + key_comp returns the function that compares keys + \fI(public member function)\fP + returns the function that compares keys in objects of type + value_comp value_type + \fI(public member function)\fP + +.SH Non-member functions + + operator== lexicographically compares the values of two flat_sets + operator<=> \fI(function template)\fP + (C++23) + std::swap(std::flat_set) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + erase_if(std::flat_set) erases all elements satisfying specific criteria + (C++23) \fI(function template)\fP + +.SH Helper classes + + std::uses_allocator specializes the std::uses_allocator type trait + (C++23) \fI(class template specialization)\fP + + Tags + + sorted_unique indicates that elements of a range are sorted and unique + sorted_unique_t (tag) + (C++23) + + Deduction guides + +.SH Notes + + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Some advantages of flat set over other standard container adaptors are: + + * Potentially faster lookup (even though search operations have logarithmic + complexity). + * Much faster iteration: random access iterators instead of bidirectional + iterators. + * Less memory consumption for small objects (and for big objects if + KeyContainer::shrink_to_fit() is available). + * Better cache performance (depending on KeyContainer, keys are stored in a + contiguous block(s) of memory). + + Some disadvantages of flat set are: + + * Non-stable iterators (iterators are invalidated when inserting and erasing + elements). + * Non-copyable and non-movable type values can not be stored. + * Weaker exception safety (copy/move constructors can throw when shifting values + in erasures and insertions). + * Slower (i.e. linear) insertion and erasure, especially for non-movable types. + + Feature-test macro Value Std Feature + __cpp_lib_flat_set 202207L (C++23) std::flat_set and std::flat_multiset + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + flat_multiset adapts a container to provide a collection of keys, sorted by keys + (C++23) \fI(class template)\fP + set collection of unique keys, sorted by keys + \fI(class template)\fP + unordered_set collection of unique keys, hashed by keys + \fI(C++11)\fP \fI(class template)\fP + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::flat_set::begin,.3 b/man/std::flat_set::begin,.3 new file mode 100644 index 000000000..5ba4b3dad --- /dev/null +++ b/man/std::flat_set::begin,.3 @@ -0,0 +1,65 @@ +.TH std::flat_set::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::begin, \- std::flat_set::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP (since C++23) + const_iterator begin() const noexcept; \fB(2)\fP (since C++23) + const_iterator cbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the first element of the flat_set. + + If the flat_set is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_set set{3, 1, 4, 1, 5, 9, 2, 6, 5}; + std::for_each(set.cbegin(), set.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 6 9 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_set::clear.3 b/man/std::flat_set::clear.3 new file mode 100644 index 000000000..977b50411 --- /dev/null +++ b/man/std::flat_set::clear.3 @@ -0,0 +1,61 @@ +.TH std::flat_set::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::clear \- std::flat_set::clear + +.SH Synopsis + void clear() noexcept; (since C++23) + + Erases all elements from the container adaptor. After this call, size() returns + zero. + + Invalidates any references, pointers, and iterators referring to contained elements. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the size of the container adaptor, i.e., the number of elements. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::flat_set& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::flat_set container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + +.SH See also + + erase erases elements + \fI(public member function)\fP diff --git a/man/std::flat_set::contains.3 b/man/std::flat_set::contains.3 new file mode 100644 index 000000000..fd0e1cfdb --- /dev/null +++ b/man/std::flat_set::contains.3 @@ -0,0 +1,60 @@ +.TH std::flat_set::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::contains \- std::flat_set::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_set example{1, 2, 3, 4}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_set::count.3 b/man/std::flat_set::count.3 new file mode 100644 index 000000000..2fde4310c --- /dev/null +++ b/man/std::flat_set::count.3 @@ -0,0 +1,48 @@ +.TH std::flat_set::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::count \- std::flat_set::count + +.SH Synopsis + size_type count( const Key& key ) const; \fB(1)\fP (since C++23) + template< class K > \fB(2)\fP (since C++23) + size_type count( const K& x ) const; + + Returns the number of elements with key that compares equivalent to the specified + argument. + + 1) Returns the number of elements with key key. This is either 1 or 0 since this + container does not allow duplicates. + 2) Returns the number of elements with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the elements to count + x - alternative value to compare to the keys + +.SH Return value + + Number of elements with key that compares equivalent to key or x, which, for + overload \fB(1)\fP, is either 1 or 0. + +.SH Complexity + + Logarithmic in the size of the container plus linear in the number of elements + found. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_set::emplace.3 b/man/std::flat_set::emplace.3 new file mode 100644 index 000000000..fbd36406e --- /dev/null +++ b/man/std::flat_set::emplace.3 @@ -0,0 +1,58 @@ +.TH std::flat_set::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::emplace \- std::flat_set::emplace + +.SH Synopsis + template< class... Args > (since C++23) + std::pair emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args, + if there is no element with the key in the container. + + First, initializes an object t of type value_type with std::forward(args)..., + then inserts t as if by + + auto it = ranges::upper_bound(c, t, compare); + c.insert(it, std::move(t)); + + This overload participates in overload resolution only if + std::is_constructible_v is true. + + Careful use of emplace allows the new element to be constructed while avoiding + unnecessary copy or move operations. + + Information on iterator invalidation is copied from here + +.SH Parameters + + args - arguments to forward to the constructor of the element + +.SH Return value + + A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_set::emplace_hint.3 b/man/std::flat_set::emplace_hint.3 new file mode 100644 index 000000000..97ae174a3 --- /dev/null +++ b/man/std::flat_set::emplace_hint.3 @@ -0,0 +1,139 @@ +.TH std::flat_set::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::emplace_hint \- std::flat_set::emplace_hint + +.SH Synopsis + template< class... Args > (since C++23) + iterator emplace_hint( const_iterator hint, Args&&... args ); + + Inserts a new element into the container as close as possible to the position just + before hint. + + The constructors of the key and mapped value are called with exactly the same + arguments as supplied to the function, forwarded with std::forward(args).... + + Information on iterator invalidation is copied from here + +.SH Parameters + + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + An iterator to the inserted element, or to the element that prevented the insertion. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + This section is incomplete + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const int n_operations = 100'500'0; + + std::size_t set_emplace() + { + std::flat_set set; + for (int i = 0; i < n_operations; ++i) + set.emplace(i); + return set.size(); + } + + std::size_t set_emplace_hint() + { + std::flat_set set; + auto it = set.begin(); + for (int i = 0; i < n_operations; ++i) + { + set.emplace_hint(it, i); + it = set.end(); + } + return set.size(); + } + + std::size_t set_emplace_hint_wrong() + { + std::flat_set set; + auto it = set.begin(); + for (int i = n_operations; i > 0; --i) + { + set.emplace_hint(it, i); + it = set.end(); + } + return set.size(); + } + + std::size_t set_emplace_hint_corrected() + { + std::flat_set set; + auto it = set.begin(); + for (int i = n_operations; i > 0; --i) + { + set.emplace_hint(it, i); + it = set.begin(); + } + return set.size(); + } + + std::size_t set_emplace_hint_closest() + { + std::flat_set set; + auto it = set.begin(); + for (int i = 0; i < n_operations; ++i) + it = set.emplace_hint(it, i); + return set.size(); + } + + double time_it(std::function set_test, + const char* what = nullptr, + double ratio = 0.0) + { + const auto start = std::chrono::system_clock::now(); + const std::size_t setsize = set_test(); + const auto stop = std::chrono::system_clock::now(); + const std::chrono::duration time = stop - start; + if (what != nullptr && setsize > 0) + std::cout << std::setw(8) << time << " for " << what << " (ratio: " + << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\\n"; + return time.count(); + } + + int main() + { + std::cout << std::fixed << std::setprecision(2); + time_it(set_emplace); // cache warmup + const auto x = time_it(set_emplace, "plain emplace"); + time_it(set_emplace_hint, "emplace with correct hint", x); + time_it(set_emplace_hint_wrong, "emplace with wrong hint", x); + time_it(set_emplace_hint_corrected, "corrected emplace", x); + time_it(set_emplace_hint_closest, "emplace using returned iterator", x); + } + +.SH Possible output: + + ...TODO... + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + +.SH Category: + * Todo without reason diff --git a/man/std::flat_set::empty.3 b/man/std::flat_set::empty.3 new file mode 100644 index 000000000..717c8b929 --- /dev/null +++ b/man/std::flat_set::empty.3 @@ -0,0 +1,57 @@ +.TH std::flat_set::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::empty \- std::flat_set::empty + +.SH Synopsis + [[nodiscard]] bool empty() const noexcept; (since C++23) + + Checks if the underlying container has no elements. Equivalent to return begin() == + end();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the underlying container is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses empty to check if a std::flat_set contains any + elements: + + +// Run this code + + #include + #include + + int main() + { + std::flat_set numbers; + std::cout << std::boolalpha; + std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; + + numbers.insert(42); + numbers.insert(19937); + std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; + } + +.SH Output: + + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false + +.SH See also + + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::flat_set::end,.3 b/man/std::flat_set::end,.3 new file mode 100644 index 000000000..96785a50f --- /dev/null +++ b/man/std::flat_set::end,.3 @@ -0,0 +1,66 @@ +.TH std::flat_set::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::end, \- std::flat_set::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP (since C++23) + const_iterator end() const noexcept; \fB(2)\fP (since C++23) + const_iterator cend() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator to the element following the last element of the flat_set. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_set set{3, 1, 4, 1, 5, 9, 2, 6, 5}; + std::for_each(set.cbegin(), set.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 6 9 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_set::equal_range.3 b/man/std::flat_set::equal_range.3 new file mode 100644 index 000000000..597049fc8 --- /dev/null +++ b/man/std::flat_set::equal_range.3 @@ -0,0 +1,105 @@ +.TH std::flat_set::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::equal_range \- std::flat_set::equal_range + +.SH Synopsis + std::pair equal_range( const Key& key ); \fB(1)\fP (since C++23) + std::pair equal_range( const Key& \fB(2)\fP (since C++23) + key ) const; + template< class K > \fB(3)\fP (since C++23) + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP (since C++23) + ) const; + + Returns a range containing all elements with the given key in the container. The + range is defined by two iterators, one pointing to the first element that is not + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). + + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + std::pair containing a pair of iterators defining the wanted range: the first + pointing to the first element that is not less than key and the second pointing to + the first element greater than key. + + If there are no elements not less than key, past-the-end (see end()) iterator is + returned as the first element. Similarly if there are no elements greater than key, + past-the-end iterator is returned as the second element. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + template + void print_equal_range(I first, I lb, I ub, I last) + { + for (I i{first}; i != lb; ++i) + std::cout << *i << ' '; + std::cout << "[ "; + + for (I i{lb}; i != ub; ++i) + std::cout << *i << ' '; + std::cout << ") "; + + for (I i{ub}; i != last; ++i) + std::cout << *i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::flat_set c{4, 3, 2, 1, 3, 3}; + std::cout << "c = "; + print_equal_range(begin(c), begin(c), end(c), end(c)); + for (int key{}; key != 6; ++key) + { + std::cout << "key = " << key << "; equal range = "; + const auto [lb, ub] = c.equal_range(key); + print_equal_range(begin(c), lb, ub, end(c)); + } + } + +.SH Output: + + c = [ 1 2 3 4 ) + key = 0; equal range = [ ) 1 2 3 4 + key = 1; equal range = [ 1 ) 2 3 4 + key = 2; equal range = 1 [ 2 ) 3 4 + key = 3; equal range = 1 2 [ 3 ) 4 + key = 4; equal range = 1 2 3 [ 4 ) + key = 5; equal range = 1 2 3 4 [ ) + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::flat_set::erase.3 b/man/std::flat_set::erase.3 new file mode 100644 index 000000000..b0ab4d3ba --- /dev/null +++ b/man/std::flat_set::erase.3 @@ -0,0 +1,99 @@ +.TH std::flat_set::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::erase \- std::flat_set::erase + +.SH Synopsis + iterator erase( iterator position ); \fB(1)\fP (since C++23) + iterator erase( const_iterator pos ); \fB(2)\fP (since C++23) + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP (since C++23) + size_type erase( const Key& key ); \fB(4)\fP (since C++23) + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. + + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes the element (if one exists) with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. + + Information on iterator invalidation is copied from here + + The iterator pos must be valid and dereferenceable. Thus the end() iterator (which + is valid, but is not dereferenceable) cannot be used as a value for pos. + +.SH Parameters + + pos - iterator to the element to remove + first, last - range of elements to remove + key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove + +.SH Return value + + 1-3) Iterator following the last removed element. + 4) Number of elements removed (0 or 1). + 5) Number of elements removed. + +.SH Exceptions + + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. + +.SH Complexity + + Depends on underlying container. Typically linear. + + This section is incomplete + Reason: revision required + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_set c = {1, 2, 3, 4, 1, 2, 3, 4}; + + auto print = [&c] + { + std::cout << "c = { "; + for (int n : c) + std::cout << n << ' '; + std::cout << "}\\n"; + }; + print(); + + std::cout << "Erase all odd numbers:\\n"; + for (auto it = c.begin(); it != c.end();) + { + if (*it % 2 != 0) + it = c.erase(it); + else + ++it; + } + print(); + + std::cout << "Erase 1, erased count: " << c.erase(1) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + print(); + } + +.SH See also + + clear clears the contents + \fI(public member function)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::flat_set::extract.3 b/man/std::flat_set::extract.3 new file mode 100644 index 000000000..cfb9cb0e4 --- /dev/null +++ b/man/std::flat_set::extract.3 @@ -0,0 +1,59 @@ +.TH std::flat_set::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::extract \- std::flat_set::extract + +.SH Synopsis + container_type extract() &&; (since C++23) + + Extracts adapted container c. Equivalent to return std::move(c);. + + After this operation *this is empty, even if an exception is thrown. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + std::move(c). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::flat_set set{1, 2, 3}; + const auto size = set.size(); + + auto c = set.extract(); + assert(c.size() == size); + assert(set.empty()); + assert(set.keys().empty()); + assert(set.values().empty()); + + // The default keys container is std::vector: + static_assert(std::is_same_v>); + + std::println("{}", c); + } + +.SH Output: + + [1, 2, 3] + +.SH See also + + replace replaces the underlying container + \fI(public member function)\fP diff --git a/man/std::flat_set::find.3 b/man/std::flat_set::find.3 new file mode 100644 index 000000000..df4084bdc --- /dev/null +++ b/man/std::flat_set::find.3 @@ -0,0 +1,89 @@ +.TH std::flat_set::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::find \- std::flat_set::find + +.SH Synopsis + iterator find( const Key& key ); \fB(1)\fP (since C++23) + const_iterator find( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator find( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator find( const K& x ) const; + + 1,2) Finds an element with key equivalent to key. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + + int main() + { + // Simple comparison demo. + std::flat_set example{1, 2, 3, 4}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << (*search) << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::flat_set> example2{{1, {}}, {2, {}}, {3, {}}, {4, {}}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->x << '\\n'; + else + std::cout << "Not found\\n"; + } + +.SH Output: + + Found 2 + Found 2 + +.SH See also + + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::flat_set::flat_set.3 b/man/std::flat_set::flat_set.3 new file mode 100644 index 000000000..ccb256a6d --- /dev/null +++ b/man/std::flat_set::flat_set.3 @@ -0,0 +1,248 @@ +.TH std::flat_set::flat_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::flat_set \- std::flat_set::flat_set + +.SH Synopsis + flat_set() \fB(1)\fP (since C++23) + : flat_set(key_compare()) { } + template< class Allocator > \fB(2)\fP (since C++23) + flat_set( const flat_set& other, const Allocator& alloc ); + template< class Allocator > \fB(3)\fP (since C++23) + flat_set( flat_set&& other, const Allocator& alloc ); + explicit flat_set( container_type cont, \fB(4)\fP (since C++23) + const key_compare& comp = key_compare() ); + template< class Allocator > \fB(5)\fP (since C++23) + flat_set( const container_type& cont, const Allocator& alloc ); + template< class Allocator > + + flat_set( const container_type& cont, const key_compare& comp, \fB(6)\fP (since C++23) + + const Allocator& alloc ); + flat_set( std::sorted_unique_t s, container_type cont, + + const key_compare& comp = key_compare() ) \fB(7)\fP (since C++23) + + : c(std::move(cont)), compare(comp) { } + template< class Allocator > + + flat_set( std::sorted_unique_t s, const container_type& cont, \fB(8)\fP (since C++23) + + const Allocator& alloc ); + template< class Allocator > + + flat_set( std::sorted_unique_t s, const container_type& cont, \fB(9)\fP (since C++23) + + const key_compare& comp, const Allocator& alloc ); + explicit flat_set( const key_compare& comp ) \fB(10)\fP (since C++23) + : c(), compare(comp) { } + template< class Allocator > \fB(11)\fP (since C++23) + flat_set( const key_compare& comp, const Allocator& alloc ); + template< class Allocator > \fB(12)\fP (since C++23) + explicit flat_set( const Allocator& alloc ); + template< class InputIter > + + flat_set( InputIter first, InputIter last, \fB(13)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(), compare(comp); + template< class InputIter, class Allocator > + + flat_set( InputIter first, InputIter last, \fB(14)\fP (since C++23) + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + flat_set( InputIter first, InputIter last, const Allocator& alloc \fB(15)\fP (since C++23) + ); + template< container-compatible-range R > + + flat_set( std::from_range_t, R&& rg, const key_compare& comp ) \fB(16)\fP (since C++23) + + : flat_set(comp); + template< container-compatible-range R > + + flat_set( std::from_range_t fr, R&& rg ) \fB(17)\fP (since C++23) + + : flat_set( fr, std::forward(rg), key_compare() ) { } + template< container-compatible-range R, class + Allocator > \fB(18)\fP (since C++23) + flat_set( std::from_range_t, R&& rg, const Allocator& alloc ); + template< container-compatible-range R, class + Allocator > + \fB(19)\fP (since C++23) + flat_set( std::from_range_t, R&& rg, const key_compare& comp, + + const Allocator& alloc ); + template< class InputIter > + + flat_set( std::sorted_unique_t s, InputIter first, InputIter + last, \fB(20)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : c(first, last), compare(comp) { } + template< class InputIter, class Allocator > + + flat_set( std::sorted_unique_t s, InputIter first, InputIter \fB(21)\fP (since C++23) + last, + + const key_compare& comp, const Allocator& alloc ); + template< class InputIter, class Allocator > + + flat_set( std::sorted_unique_t s, InputIter first, InputIter \fB(22)\fP (since C++23) + last, + + const Allocator& alloc ); + flat_set( std::initializer_list init, + + const key_compare& comp = key_compare() ) \fB(23)\fP (since C++23) + + : flat_set(init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_set( std::initializer_list init, const \fB(24)\fP (since C++23) + key_compare& comp, + + const Allocator& alloc ); + template< class Allocator > + flat_set( std::initializer_list init, const \fB(25)\fP (since C++23) + Allocator& alloc ); + flat_set( std::sorted_unique_t s, + std::initializer_list init, + \fB(26)\fP (since C++23) + const key_compare& comp = key_compare() ) + + : flat_set(s, init.begin(), init.end(), comp) { } + template< class Allocator > + + flat_set( std::sorted_unique_t s, \fB(27)\fP (since C++23) + std::initializer_list init, + + const key_compare& comp, const Allocator& alloc ); + template< class Allocator > + + flat_set( std::sorted_unique_t s, \fB(28)\fP (since C++23) + std::initializer_list init, + + const Allocator& alloc ); + + Constructs new container adaptor from a variety of data sources and optionally + provided comparison function object comp and/or allocator alloc. + + 1) A default constructor. Constructs an empty container adaptor. + 2) A copy constructor. Constructs c with the copy of the contents of other.c and + compare with other.compare. See allocator usage note below. + 3) A move constructor. Constructs the container adaptor with the contents of other + using move semantics. See allocator usage note below. + 4) Constructs the underlying container with the contents of the container cont. + First, initializes c with std::move(cont) and compare with comp. Then sorts the c + with respect to comp. Finally, makes elements unique, i.e. erases all but the first + element from each group of consecutive equivalent elements. + 5) Same as \fB(4)\fP, equivalent to flat_set(cont);. See allocator usage note below. + 6) Same as \fB(4)\fP, equivalent to flat_set(cont, comp);. See allocator usage note below. + 7) Constructs the underlying container with the contents of the other container + cont. Initializes c with std::move(cont) and compare with comp. + 8) Same as \fB(7)\fP, equivalent to flat_set(s, cont);. See allocator usage note below. + 9) Same as \fB(7)\fP, equivalent to flat_set(s, cont, comp);. See allocator usage note + below. + 10) Constructs an empty container adaptor. + 11,12) Constructs an empty container adaptor. See allocator usage note below. + 13) Constructs the container adaptor with the contents of the range [first, last), + equivalent to insert(first, last);. + 14,15) Same as \fB(13)\fP. See allocator usage note below. + 16) Constructs the container adaptor with the contents of the range rg. First, uses + \fB(10)\fP as delegating constructor. Then initializes c with the contents of rg as if by + insert_range(std::forward(rg));. + 17) Same as \fB(16)\fP using it as delegating constructor. + 18,19) Same as \fB(16)\fP. See allocator usage note below. + 20) Constructs the underlying container with the contents of the range + [first, last). Initializes c with c(first, last) and compare with compare(comp). + 21,22) Same as \fB(20)\fP. See allocator usage note below. + 23) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(13)\fP as delegating constructor. + 24,25) Same as \fB(23)\fP. See allocator usage note below. + 26) An initializer-list constructor. Constructs the underlying container with the + contents of the initializer list init, using \fB(20)\fP as delegating constructor. + 27,28) Save as \fB(26)\fP. See allocator usage note below. + + Note for overloads (13-15,20-22): If [first, last) is not a valid range, the + behavior is undefined. + + Note for overloads (4-6,13-19,23-25): If multiple elements in the range have keys + that compare equivalent, it is unspecified which element is inserted (pending + LWG2844). + +.SH Parameters + + cont - a container to be used as source to initialize the underlying + container + other - another flat_set to be used as source to initialize the elements of + the underlying container with + alloc - an allocator to use for all memory allocations of the underlying + container + comp - a function object to be used for all comparisons of keys + first, last - a range to copy the elements from + init - an initializer list to initialize the elements of the underlying + container with + a container compatible range (that is, an input_range whose elements + rg - are convertible to value_type) to be used as source to initialize the + underlying container + fr - a disambiguation tag that indicates that the contained member should + be range constructed + s - a disambiguation tag that indicates that the input sequence is sorted + with respect to compare and all its elements are unique +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + Compare must meet the requirements of Compare. + - + Allocator must meet the requirements of Allocator. + +.SH Complexity + + 1) Constant. + 2) Linear in size of other. + 3) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 4-6) Linear in \\(\\scriptsize N\\)N if cont is sorted with respect to compare, + otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of cont.size() before this call. + 7-9) Same as the corresponding move-constructor of the wrapped container, i.e. + constant or linear in size of cont. + 10-12) Constant. + 13-15) Linear in \\(\\scriptsize N\\)N if the input range [first, last) is sorted with + respect to compare, otherwise \\(\\scriptsize + \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where \\(\\scriptsize N\\)N is the value of + cont.size() before this call. + 16-19) Linear in \\(\\scriptsize N\\)N if the input range rg is sorted with respect to + compare, otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of cont.size() before this call. + 20-22) Linear in size of [first, last). + 23-25) Linear in \\(\\scriptsize N\\)N if the elements of init are sorted with respect + to compare, otherwise \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)), where + \\(\\scriptsize N\\)N is the value of cont.size() before this call. + 26-28) Linear in size of init. + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload (3,16-19)), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns values to the container adaptor + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_set::insert.3 b/man/std::flat_set::insert.3 new file mode 100644 index 000000000..57dbfb4d3 --- /dev/null +++ b/man/std::flat_set::insert.3 @@ -0,0 +1,162 @@ +.TH std::flat_set::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::insert \- std::flat_set::insert + +.SH Synopsis + std::pair insert( const value_type& value ); \fB(1)\fP (since C++23) + std::pair insert( value_type&& value ); \fB(2)\fP (since C++23) + iterator insert( const_iterator pos, const value_type& value ); \fB(3)\fP (since C++23) + iterator insert( const_iterator pos, value_type&& value ); \fB(4)\fP (since C++23) + template< class K > \fB(5)\fP (since C++23) + iterator insert( const_iterator pos, K&& x ); + template< class InputIt > \fB(6)\fP (since C++23) + void insert( InputIt first, InputIt last ); + template< class K > \fB(7)\fP (since C++23) + std::pair insert( K&& x ); + template< class InputIt > \fB(8)\fP (since C++23) + void insert( std::sorted_unique_t, InputIt first, InputIt last ); + void insert( std::initializer_list ilist ); \fB(9)\fP (since C++23) + void insert( std::sorted_unique_t s, \fB(10)\fP (since C++23) + std::initializer_list ilist ); + + Inserts element(s) into the container, if the container does not already contain an + element with an equivalent key. + + 1) Inserts value. Equivalent to return emplace(value);. + 2) Inserts value. Equivalent to return emplace(std::move(value));. + 3) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, value);. + 4) Inserts value in the position as close as possible to the position just prior to + pos. Equivalent to return emplace_hint(pos, std::move(value));. + 5,7) If *this already contains an element which transparently compares equivalent to + x, does nothing. Otherwise, inserts a new element as if by: + * \fB(5)\fP emplace(pos, std::forward(x)) (in the position as close as possible to + the position just prior to pos); + * \fB(7)\fP emplace(std::forward(x)). + The conversion from x into key_type must construct an object u, for which find(k) == + find(u) is true. Otherwise, the behavior is undefined. + These overloads participate in overload resolution only if + * The qualified-id Compare::is_transparent is valid and denotes a type, and + * std::is_constructible_v is true, + which together allows calling this function without constructing an instance of Key. + 6) Equivalent to the sequence of operations: + 1. Inserts elements from range [first, last) as if by c.insert(c.end(), first, + last);. + 2. Sorts the range of newly inserted elements with respect to compare. + 3. Merges the resulting sorted range and the sorted range of pre-existing elements + into a single sorted range. (Note: the merge operation may allocate memory). + 4. Erases all but the first element from each group of consecutive equivalent + elements. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + 8) Inserts elements from range [first, last). Equivalent to insert(first, last);. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + 9) Inserts elements from initializer list ilist. Equivalent to insert(ilist.begin(), + ilist.end());. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + 10) Inserts elements from initializer list ilist. Equivalent to insert(s, + ilist.begin(), ilist.end());. + If multiple elements in the range have keys that compare equivalent, it is + unspecified which element is inserted (pending LWG2844). + + Information on iterator invalidation is copied from here + +.SH Parameters + + pos - iterator to the position before which the new element will be inserted + value - element value to insert + first, last - range of elements to insert + ilist - initializer list to insert the values from + x - a value of any type that can be transparently compared with a key + s - a disambiguation tag indicating that the input sequence is sorted + (with respect to compare) and contains only unique elements +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1,2) A pair consisting of an iterator to the inserted element (or to the element + that prevented the insertion) and a bool value set to true if and only if the + insertion took place. + 3-5) An iterator to the inserted element, or to the element that prevented the + insertion. + 6) \fI(none)\fP + 7) A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. + 8-10) \fI(none)\fP + +.SH Exceptions + + 1-5,7) If an exception is thrown by any operation, the insertion has no effect. + + This section is incomplete + Reason: cases 6,8-10 + +.SH Complexity + + 1-5) Linear in size(). + 6) N + M·log(M), where N is the size() before the operation and M is + std::distance(first, last). + 7) Linear in size(). + 8) Linear in N, where N is size() after the operation. + 9) N + M·log(M), where N is the size() before the operation and M is ilist.size(). + 10) Linear in N, where N is size() after the operation. + + This section is incomplete + Reason: recheck the complexity: 1-5, 7, 9, 10. The lookup is log(N), but insertion + in underlying container is N/2 on average => Linear. + +.SH Notes + + The hinted insert (3-5) does not return a boolean in order to be + signature-compatible with positional insert on sequential containers, such as + std::vector::insert. This makes it possible to create generic inserters such as + std::inserter. One way to check success of a hinted insert is to compare size() + before and after. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_set set; + + auto result_1 = set.insert(3); + assert(result_1.first != set.end()); // it is a valid iterator + assert(*result_1.first == 3); + if (result_1.second) + std::cout << "insert done\\n"; + + auto result_2 = set.insert(3); + assert(result_2.first == result_1.first); // the same iterator + assert(*result_2.first == 3); + if (!result_2.second) + std::cout << "no insertion\\n"; + } + +.SH Output: + + insert done + no insertion + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::flat_set::insert_range.3 b/man/std::flat_set::insert_range.3 new file mode 100644 index 000000000..c59719cea --- /dev/null +++ b/man/std::flat_set::insert_range.3 @@ -0,0 +1,75 @@ +.TH std::flat_set::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::insert_range \- std::flat_set::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg into underlying container c as if by: + + for (const auto& e : rg) + c.insert(c.end(), e); + + Then, sorts the range of newly inserted elements with respect to compare. Merges the + resulting sorted range and the sorted range of pre-existing elements into a single + sorted range. Finally, erases all but the first element from each group of + consecutive equivalent elements. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + Information on iterator invalidation is copied from here + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N + M·log(M), where N is size() before the operation and M is ranges::distance(rg). + +.SH Notes + + Since insert_range performs an in-place merge operation, that may allocate memory. + +.SH Example + + +// Run this code + + #include + #include + + void println(auto, auto const& container) + { + for (const auto& elem : container) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::flat_set{1, 3, 2, 4}; + const auto rg = {-1, 3, -2}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + -2 -1 1 2 3 4 + +.SH See also + + insert inserts elements + \fI(public member function)\fP diff --git a/man/std::flat_set::key_comp.3 b/man/std::flat_set::key_comp.3 new file mode 100644 index 000000000..fd6e8e629 --- /dev/null +++ b/man/std::flat_set::key_comp.3 @@ -0,0 +1,75 @@ +.TH std::flat_set::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::key_comp \- std::flat_set::key_comp + +.SH Synopsis + key_compare key_comp() const; (since C++23) + + Returns the function object that compares the keys, which is a copy of this + container's constructor argument comp. It is the same as value_comp. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The key comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_set cont{1, 2, 3, 4, 5}; + + auto comp_func = cont.key_comp(); + + for (const int key : cont) + { + const bool before = comp_func(key, 100); + const bool after = comp_func(100, key); + + std::cout << '(' << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + +.SH See also + + value_comp returns the function that compares keys in objects of type value_type + \fI(public member function)\fP diff --git a/man/std::flat_set::lower_bound.3 b/man/std::flat_set::lower_bound.3 new file mode 100644 index 000000000..33ffbe4b6 --- /dev/null +++ b/man/std::flat_set::lower_bound.3 @@ -0,0 +1,47 @@ +.TH std::flat_set::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::lower_bound \- std::flat_set::lower_bound + +.SH Synopsis + iterator lower_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is not less than key. If no such element + is found, a past-the-end iterator (see end()) is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_set::max_size.3 b/man/std::flat_set::max_size.3 new file mode 100644 index 000000000..dd1179903 --- /dev/null +++ b/man/std::flat_set::max_size.3 @@ -0,0 +1,54 @@ +.TH std::flat_set::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::max_size \- std::flat_set::max_size + +.SH Synopsis + size_type max_size() const noexcept; (since C++23) + + Returns the maximum number of elements the container is able to hold due to system + or library implementation limitations, i.e. std::distance(begin(), end()) for the + largest container. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of elements. + +.SH Complexity + + Constant. + +.SH Notes + + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the + container may be limited to a value smaller than max_size() by the amount of RAM + available. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_set q; + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "Maximum size of a std::flat_set is " << q.max_size() << '\\n'; + } + +.SH Possible output: + + Maximum size of a std::flat_set is 768,614,336,404,564,650 + +.SH See also + + size returns the number of elements + \fI(public member function)\fP diff --git a/man/std::flat_set::operator=.3 b/man/std::flat_set::operator=.3 new file mode 100644 index 000000000..90d233072 --- /dev/null +++ b/man/std::flat_set::operator=.3 @@ -0,0 +1,91 @@ +.TH std::flat_set::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::operator= \- std::flat_set::operator= + +.SH Synopsis + flat_set& operator=( const flat_set& other ); \fB(1)\fP (since C++23) + (implicitly declared) + flat_set& operator=( flat_set&& other ); \fB(2)\fP (since C++23) + (implicitly declared) + flat_set& operator=( std::initializer_list ilist \fB(3)\fP (since C++23) + ); + + Replaces the contents of the container adaptor with the contents of given argument. + + 1) Copy assignment operator. Replaces the contents with a copy of the contents of + other. Effectively calls c = other.c; comp = other.comp;. + 2) Move assignment operator. Replaces the contents with those of other using move + semantics. Effectively calls c = std::move(other.c); comp = std::move(other.comp);. + 3) Replaces the contents with those identified by initializer list ilist. + +.SH Parameters + + other - another container adaptor to be used as source + ilist - initializer list to be used as source + +.SH Return value + + *this + +.SH Complexity + + 1,2) Equivalent to that of operator= of the underlying container. + 3) Linear in the size of *this and ilist. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_set x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + + std::println("Initially:"); + std::println("x = {}", x); + std::println("y = {}", y); + std::println("z = {}", z); + + y = x; // overload (1) + std::println("Copy assignment copies data from x to y:"); + std::println("x = {}", x); + std::println("y = {}", y); + + z = std::move(x); // overload (2) + std::println("Move assignment moves data from x to z, modifying both x and z:"); + std::println("x = {}", x); + std::println("z = {}", z); + + z = w; // overload (3) + std::println("Assignment of initializer_list w to z:"); + std::println("w = {}", w); + std::println("z = {}", z); + } + +.SH Output: + + Initially: + x = {1, 2, 3} + y = {} + z = {} + Copy assignment copies data from x to y: + x = {1, 2, 3} + y = {1, 2, 3} + Move assignment moves data from x to z, modifying both x and z: + x = {} + z = {1, 2, 3} + Assignment of initializer_list w to z: + w = {4, 5, 6, 7} + z = {4, 5, 6, 7} + +.SH See also + + constructor constructs the flat_set + \fI(public member function)\fP + replace replaces the underlying container + \fI(public member function)\fP diff --git a/man/std::flat_set::rbegin,.3 b/man/std::flat_set::rbegin,.3 new file mode 100644 index 000000000..dd85c00e6 --- /dev/null +++ b/man/std::flat_set::rbegin,.3 @@ -0,0 +1,71 @@ +.TH std::flat_set::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::rbegin, \- std::flat_set::rbegin, + +.SH Synopsis + + reverse_iterator rbegin() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rbegin() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the first element of the reversed flat_set. It + corresponds to the last element of the non-reversed flat_set. If the flat_set is + empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_set rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_set::rend,.3 b/man/std::flat_set::rend,.3 new file mode 100644 index 000000000..6a7aff002 --- /dev/null +++ b/man/std::flat_set::rend,.3 @@ -0,0 +1,69 @@ +.TH std::flat_set::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::rend, \- std::flat_set::rend, + +.SH Synopsis + + reverse_iterator rend() noexcept; \fB(1)\fP (since C++23) + const_reverse_iterator rend() const noexcept; \fB(2)\fP (since C++23) + const_reverse_iterator crend() const noexcept; \fB(3)\fP (since C++23) + + Returns a reverse iterator to the element following the last element of the reversed + flat_set. It corresponds to the element preceding the first element of the + non-reversed flat_set. This element acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::flat_set rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::flat_set::replace.3 b/man/std::flat_set::replace.3 new file mode 100644 index 000000000..19e37bad6 --- /dev/null +++ b/man/std::flat_set::replace.3 @@ -0,0 +1,59 @@ +.TH std::flat_set::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::replace \- std::flat_set::replace + +.SH Synopsis + void replace( container_type&& cont ); (since C++23) + + Replaces the underlying container c. Equivalent to: c = std::move(cont);. + + The elements of cont must be sorted with respect to compare, and cont must not + contain equal elements. Otherwise, the behavior is undefined. + +.SH Parameters + + cont - a sorted container of type KeyContainer, the contents of which will be moved + into *this + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Equals to complexity of std::move applied to adapted container. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector keys{1, 2, 3}; + assert(std::ranges::is_sorted(keys)); + + std::flat_set set; + assert(set.empty()); + + set.replace(keys); + assert(set.size() == 3); + assert(keys.empty()); + + std::println("{}", set); // set.keys() + } + +.SH Output: + + [1, 2, 3] + +.SH See also + + extract extracts the underlying container + \fI(public member function)\fP diff --git a/man/std::flat_set::size.3 b/man/std::flat_set::size.3 new file mode 100644 index 000000000..e449cb61f --- /dev/null +++ b/man/std::flat_set::size.3 @@ -0,0 +1,56 @@ +.TH std::flat_set::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::size \- std::flat_set::size + +.SH Synopsis + size_type size() const noexcept; (since C++23) + + Returns the number of elements in the container adaptor. Equivalent to return + c.size(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements in the container adaptor. + +.SH Complexity + + Constant. + +.SH Example + + + + The following code uses size to display the number of elements in a + std::flat_set: + + +// Run this code + + #include + #include + + int main() + { + std::flat_set nums{1, 3, 5, 7}; + + std::cout << "nums contains " << nums.size() << " elements.\\n"; + } + +.SH Output: + + nums contains 4 elements. + +.SH See also + + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + max_size returns the maximum possible number of elements + \fI(public member function)\fP diff --git a/man/std::flat_set::swap.3 b/man/std::flat_set::swap.3 new file mode 100644 index 000000000..a66272d9a --- /dev/null +++ b/man/std::flat_set::swap.3 @@ -0,0 +1,41 @@ +.TH std::flat_set::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::swap \- std::flat_set::swap + +.SH Synopsis + void swap( flat_set& other ) noexcept; (since C++23) + + Exchanges the contents of the container adaptor with those of other. Effectively + calls + + ranges::swap(compare, other.compare); + ranges::swap(c, other.c); + +.SH Parameters + + other - container adaptor to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + \fI(none)\fP + +.SH Complexity + + Same as underlying container (typically constant). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::flat_set) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_set::upper_bound.3 b/man/std::flat_set::upper_bound.3 new file mode 100644 index 000000000..6b052bcd4 --- /dev/null +++ b/man/std::flat_set::upper_bound.3 @@ -0,0 +1,46 @@ +.TH std::flat_set::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::upper_bound \- std::flat_set::upper_bound + +.SH Synopsis + iterator upper_bound( const Key& key ); \fB(1)\fP (since C++23) + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP (since C++23) + template< class K > \fB(3)\fP (since C++23) + iterator upper_bound( const K& x ); + template< class K > \fB(4)\fP (since C++23) + const_iterator upper_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value to compare the elements to + x - alternative value that can be compared to Key + +.SH Return value + + Iterator pointing to the first element that is greater than key. If no such element + is found, past-the-end (see end()) iterator is returned. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::flat_set::value_comp.3 b/man/std::flat_set::value_comp.3 new file mode 100644 index 000000000..3656e5036 --- /dev/null +++ b/man/std::flat_set::value_comp.3 @@ -0,0 +1,75 @@ +.TH std::flat_set::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flat_set::value_comp \- std::flat_set::value_comp + +.SH Synopsis + std::flat_set::value_compare value_comp() const; (since C++23) + + Returns the function object that compares the values. It is the same as key_comp. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value comparison function object. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::flat_set cont{1, 2, 3, 4, 5}; + + // Same behaviour as key_comp() + auto comp_func = cont.value_comp(); + + for (const int val{100}; const int key : cont) + { + const bool before = comp_func(key, val); + const bool after = comp_func(val, key); + + std::cout << "Key (" << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val << ")\\n"; + else if (before) + std::cout << "goes before key (" << val << ")\\n"; + else if (after) + std::cout << "goes after key (" << val << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + +.SH See also + + key_comp returns the function that compares keys + \fI(public member function)\fP diff --git a/man/std::float_denorm_style.3 b/man/std::float_denorm_style.3 index d6fe30c36..04e4726f7 100644 --- a/man/std::float_denorm_style.3 +++ b/man/std::float_denorm_style.3 @@ -1,10 +1,13 @@ -.TH std::float_denorm_style 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::float_denorm_style 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::float_denorm_style \- std::float_denorm_style + .SH Synopsis Defined in header enum float_denorm_style { denorm_indeterminate = -1, - denorm_absent = 0, + denorm_absent = 0, (deprecated in C++23) denorm_present = 1 }; @@ -22,4 +25,4 @@ .SH See also has_denorm identifies the denormalization style used by the floating-point type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::float_round_style.3 b/man/std::float_round_style.3 index 2fa684402..59f017c21 100644 --- a/man/std::float_round_style.3 +++ b/man/std::float_round_style.3 @@ -1,4 +1,7 @@ -.TH std::float_round_style 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::float_round_style 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::float_round_style \- std::float_round_style + .SH Synopsis Defined in header enum float_round_style { @@ -12,8 +15,8 @@ }; Enumeration constants of type std::float_round_style indicate the rounding style - used by floating-point arithmetics whenever a result of an expression is stored in - an object of a floating-point type. The values are: + used by floating-point arithmetic whenever a result of an expression is stored in an + object of a floating-point type. The values are: Enumeration constants @@ -27,9 +30,9 @@ .SH See also round_style identifies the rounding style used by the type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP FE_DOWNWARD FE_TONEAREST floating-point rounding direction - FE_TOWARDZERO (macro constant) + FE_TOWARDZERO (macro constant) FE_UPWARD \fI(C++11)\fP diff --git a/man/std::floating_point.3 b/man/std::floating_point.3 new file mode 100644 index 000000000..816c3a132 --- /dev/null +++ b/man/std::floating_point.3 @@ -0,0 +1,56 @@ +.TH std::floating_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::floating_point \- std::floating_point + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + concept floating_point = std::is_floating_point_v; + + The concept floating_point is satisfied if and only if T is a floating-point + type. + +.SH Example + + +// Run this code + + #include + #include + #include + + constexpr std::floating_point auto x2(std::floating_point auto x) + { + return x + x; + } + + constexpr std::integral auto x2(std::integral auto x) + { + return x << 1; + } + + int main() + { + constexpr auto d = x2(1.1); + static_assert(std::is_same_v); + std::cout << d << '\\n'; + + constexpr auto f = x2(2.2f); + static_assert(std::is_same_v); + std::cout << f << '\\n'; + + constexpr auto i = x2(444); + static_assert(std::is_same_v); + std::cout << i << '\\n'; + } + +.SH Output: + + 2.2 + 4.4 + 888 + +.SH See also + + is_floating_point checks if a type is a floating-point type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::floor,std::floorf,std::floorl.3 b/man/std::floor,std::floorf,std::floorl.3 new file mode 100644 index 000000000..5d7cfecd6 --- /dev/null +++ b/man/std::floor,std::floorf,std::floorl.3 @@ -0,0 +1,125 @@ +.TH std::floor,std::floorf,std::floorl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::floor,std::floorf,std::floorl \- std::floor,std::floorf,std::floorl + +.SH Synopsis + Defined in header + float floor ( float num ); + + double floor ( double num ); (until C++23) + + long double floor ( long double num ); + constexpr /* floating-point-type */ (since C++23) + floor ( /* floating-point-type */ num ); + float floorf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double floorl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double floor ( Integer num ); + + 1-3) Computes the largest integer value not greater than num. + The library provides overloads of std::floor for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the largest integer value not greater than num, that is ⌊num⌋, + is returned. + +.SH Return value + math-floor.svg + num + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * The current rounding mode has no effect. + * If num is ±∞, it is returned, unmodified. + * If num is ±0, it is returned, unmodified. + * If num is NaN, NaN is returned. + +.SH Notes + + FE_INEXACT may be (but isn't required to be) raised when rounding a non-integer + finite value. + + The largest representable floating-point values are exact integers in all standard + floating-point formats, so this function never overflows on its own; however the + result may overflow any integer type (including std::intmax_t), when stored in an + integer variable. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::floor(num) has the same effect as std::floor(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::fixed + << "floor(+2.7) = " << std::floor(+2.7) << '\\n' + << "floor(-2.7) = " << std::floor(-2.7) << '\\n' + << "floor(-0.0) = " << std::floor(-0.0) << '\\n' + << "floor(-Inf) = " << std::floor(-INFINITY) << '\\n'; + } + +.SH Output: + + floor(+2.7) = 2.000000 + floor(-2.7) = -3.000000 + floor(-0.0) = -0.000000 + floor(-Inf) = -inf + +.SH See also + + ceil + ceilf nearest integer not less than the given value + ceill \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + trunc + truncf + truncl nearest integer not greater in magnitude than the given value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + round + roundf + roundl + lround + lroundf + lroundl + llround + llroundf + llroundl nearest integer, rounding away from zero in halfway cases + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + floor diff --git a/man/std::floor.3 b/man/std::floor.3 deleted file mode 100644 index 39a2b2334..000000000 --- a/man/std::floor.3 +++ /dev/null @@ -1,64 +0,0 @@ -.TH std::floor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float floor( float arg ); - double floor( double arg ); - long double floor( long double arg ); - double floor( Integral arg ); \fI(since C++11)\fP - - Computes nearest integer not greater than arg. - -.SH Parameters - - arg - floating point value - -.SH Return value - - Nearest integer not greater than arg - -.SH Return value - math-floor.svg - Argument - -.SH Notes - - The integer value can be always represented by the given floating point type. - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::cout << std::fixed; - std::cout << std::floor(12.0) << '\\n'; - std::cout << std::floor(12.1) << '\\n'; - std::cout << std::floor(12.5) << '\\n'; - std::cout << std::floor(12.9) << '\\n'; - std::cout << std::floor(13.0) << '\\n'; - } - -.SH Output: - - 12.000000 - 12.000000 - 12.000000 - 12.000000 - 13.000000 - -.SH See also - - ceil nearest integer not less than the given value - \fI(function)\fP - trunc nearest integer not greater in magnitude than the given value - \fI(C++11)\fP \fI(function)\fP - round - lround - llround nearest integer, rounding away from zero in halfway cases - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP diff --git a/man/std::flush.3 b/man/std::flush.3 index 4ea99ae25..25cb9fda0 100644 --- a/man/std::flush.3 +++ b/man/std::flush.3 @@ -1,8 +1,11 @@ -.TH std::flush 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::flush 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flush \- std::flush + .SH Synopsis Defined in header template< class CharT, class Traits > - std::basic_ostream& flush( std::basic_ostream& os ); + std::basic_ostream& flush( std::basic_ostream& os ); Flushes the output sequence os as if by calling os.flush(). @@ -32,49 +35,50 @@ .SH Return value - os (reference to the stream after manipulation) + os (reference to the stream after manipulation). .SH Example Without std::flush, the output would be the same, but may not appear in real time. - + // Run this code - #include #include + #include + template void log_progress(Diff d) { - std::cout << "..(" - << std::chrono::duration_cast(d).count() - << " ms).." << std::flush; + std::cout << std::chrono::duration_cast(d) << " ... " + << std::flush; } + int main() { - volatile int sink=0; - + volatile int sink = 0; + auto t1 = std::chrono::high_resolution_clock::now(); - for(int j=0; j<5; ++j) + for (int j = 0; j < 5; ++j) { - for(int n=0; n<10000; ++n) - for(int m=0; m<20000; ++m) - sink += m*n; // do some work + for (int n = 0; n < 10000; ++n) + for (int m = 0; m < 20000; ++m) + sink += m * n; // do some work auto now = std::chrono::high_resolution_clock::now(); log_progress(now - t1); } std::cout << '\\n'; } -.SH Output: +.SH Possible output: - ..(450 ms)....(901 ms)....(1350 ms)....(1800 ms)....(2250 ms).. + 567ms ... 1137ms ... 1707ms ... 2269ms ... 2842ms ... .SH See also unitbuf controls whether output is flushed after each operation - nounitbuf \fI(function)\fP + nounitbuf \fI(function)\fP endl outputs '\\n' and flushes the output stream - \fI(function template)\fP + \fI(function template)\fP flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::flush_emit.3 b/man/std::flush_emit.3 new file mode 100644 index 000000000..4adeb76b0 --- /dev/null +++ b/man/std::flush_emit.3 @@ -0,0 +1,37 @@ +.TH std::flush_emit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::flush_emit \- std::flush_emit + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + std::basic_ostream& flush_emit( \fI(since C++20)\fP + std::basic_ostream& os ); + + Flushes the output sequence os as if by calling os.flush(). Then, if os.rdbuf() + actually points to a std::basic_syncbuf buf, calls + buf.emit(). + + This is an output-only I/O manipulator, it may be called with an expression such as + out << std::flush_emit for any out of type std::basic_ostream. + +.SH Parameters + + os - reference to output stream + +.SH Return value + + os (reference to the stream after manipulation) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::fma,std::fmaf,std::fmal.3 b/man/std::fma,std::fmaf,std::fmal.3 new file mode 100644 index 000000000..41edb979c --- /dev/null +++ b/man/std::fma,std::fmaf,std::fmal.3 @@ -0,0 +1,199 @@ +.TH std::fma,std::fmaf,std::fmal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fma,std::fmaf,std::fmal \- std::fma,std::fmaf,std::fmal + +.SH Synopsis + Defined in header + float fma ( float x, float y, float z ); + + double fma ( double x, double y, double z ); \fI(since C++11)\fP + (until C++23) + long double fma ( long double x, long double y, long + double z ); + constexpr /* floating-point-type */ + + fma ( /* floating-point-type */ x, (since C++23) + /* floating-point-type */ y, + + /* floating-point-type */ z ); + float fmaf( float x, float y, float z ); \fB(2)\fP \fI(since C++11)\fP + \fB(1)\fP (constexpr since C++23) + long double fmal( long double x, long double y, long \fB(3)\fP \fI(since C++11)\fP + double z ); (constexpr since C++23) + #define FP_FAST_FMA /* implementation-defined */ \fB(4)\fP \fI(since C++11)\fP + #define FP_FAST_FMAF /* implementation-defined */ \fB(5)\fP \fI(since C++11)\fP + #define FP_FAST_FMAL /* implementation-defined */ \fB(6)\fP \fI(since C++11)\fP + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2, + class Arithmetic3 > + \fI(since C++11)\fP + /* common-floating-point-type */ (A) (constexpr since C++23) + + fma( Arithmetic1 x, Arithmetic2 y, Arithmetic3 z + ); + + 1-3) Computes x * y + z as if to infinite precision and rounded only once to fit the + result type. + The library provides overloads of std::fma for all cv-unqualified floating-point + types as the type of the parameters x, y and z. + (since C++23) + 4-6) If the macro constants FP_FAST_FMA, FP_FAST_FMAF, or FP_FAST_FMAL are defined, + the function std::fma evaluates faster (in addition to being more precise) than the + expression x * y + z for double, float, and long double arguments, respectively. If + defined, these macros evaluate to integer 1. + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + x, y, z - floating-point or integer values + +.SH Return value + + If successful, returns the value of x * y + z as if calculated to infinite precision + and rounded once to fit the result type (or, alternatively, calculated as a single + ternary floating-point operation). + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned. + + If a range error due to underflow occurs, the correct value (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If x is zero and y is infinite or if x is infinite and y is zero, and + * if z is not a NaN, then NaN is returned and FE_INVALID is raised, + * if z is a NaN, then NaN is returned and FE_INVALID may be raised. + * If x * y is an exact infinity and z is an infinity with the opposite sign, NaN + is returned and FE_INVALID is raised. + * If x or y are NaN, NaN is returned. + * If z is NaN, and x * y is not 0 * Inf or Inf * 0, then NaN is returned (without + FE_INVALID). + +.SH Notes + + This operation is commonly implemented in hardware as fused multiply-add CPU + instruction. If supported by hardware, the appropriate FP_FAST_FMA? macros are + expected to be defined, but many implementations make use of the CPU instruction + even when the macros are not defined. + + POSIX (fma, fmaf, fmal) additionally specifies that the situations specified to + return FE_INVALID are domain errors. + + Due to its infinite intermediate precision, std::fma is a common building block of + other correctly-rounded mathematical operations, such as std::sqrt or even the + division (where not provided by the CPU, e.g. Itanium). + + As with all floating-point expressions, the expression x * y + z may be compiled as + a fused multiply-add unless the #pragma STDC FP_CONTRACT is off. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1, second argument + num2 and third argument num3: + + * If num1, num2 or num3 has type long double, then std::fma(num1, + num2, num3) has the same effect as std::fma(static_cast(num1), + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 and/or num3 has type double or an integer + type, then std::fma(num1, num2, num3) has the same effect as + std::fma(static_cast(num1), (until C++23) + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 or num3 has type float, then + std::fma(num1, num2, num3) has the same effect as + std::fma(static_cast(num1), + static_cast(num2), + static_cast(num3)). + If num1, num2 and num3 have arithmetic types, then std::fma(num1, + num2, num3) has the same effect as std::fma(static_cast(num1), + static_cast(num2), + static_cast(num3)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point (since C++23) + conversion subrank among the types of num1, num2 and num3, arguments + of integer type are considered to have the same floating-point + conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + #ifndef __GNUC__ + #pragma STDC FENV_ACCESS ON + #endif + + int main() + { + // demo the difference between fma and built-in operators + const double in = 0.1; + std::cout << "0.1 double is " << std::setprecision(23) << in + << " (" << std::hexfloat << in << std::defaultfloat << ")\\n" + << "0.1*10 is 1.0000000000000000555112 (0x8.0000000000002p-3), " + << "or 1.0 if rounded to double\\n"; + + const double expr_result = 0.1 * 10 - 1; + const double fma_result = std::fma(0.1, 10, -1); + std::cout << "0.1 * 10 - 1 = " << expr_result + << " : 1 subtracted after intermediate rounding\\n" + << "fma(0.1, 10, -1) = " << std::setprecision(6) << fma_result << " (" + << std::hexfloat << fma_result << std::defaultfloat << ")\\n\\n"; + + // fma is used in double-double arithmetic + const double high = 0.1 * 10; + const double low = std::fma(0.1, 10, -high); + std::cout << "in double-double arithmetic, 0.1 * 10 is representable as " + << high << " + " << low << "\\n\\n"; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + std::cout << "fma(+Inf, 10, -Inf) = " << std::fma(INFINITY, 10, -INFINITY) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + 0.1 double is 0.10000000000000000555112 (0x1.999999999999ap-4) + 0.1*10 is 1.0000000000000000555112 (0x8.0000000000002p-3), or 1.0 if rounded to double + 0.1 * 10 - 1 = 0 : 1 subtracted after intermediate rounding + fma(0.1, 10, -1) = 5.55112e-17 (0x1p-54) + + in double-double arithmetic, 0.1 * 10 is representable as 1 + 5.55112e-17 + + fma(+Inf, 10, -Inf) = -nan + FE_INVALID raised + +.SH See also + + remainder + remainderf + remainderl signed remainder of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remquo + remquof + remquol signed remainder as well as the three last bits of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + fma diff --git a/man/std::fma.3 b/man/std::fma.3 deleted file mode 100644 index 544bb5f75..000000000 --- a/man/std::fma.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::fma 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float fma( float x, float y, float z ); \fB(1)\fP \fI(since C++11)\fP - double fma( double x, double y, double z ); \fB(2)\fP \fI(since C++11)\fP - long double fma( long double x, long double y, long double z ); \fB(3)\fP \fI(since C++11)\fP - Promoted fma( Arithmetic1 x, Arithmetic2 y, Arithmetic3 z ); \fB(4)\fP \fI(since C++11)\fP - #define FP_FAST_FMA /* implementation-defined */ \fB(5)\fP \fI(since C++11)\fP - #define FP_FAST_FMAF /* implementation-defined */ \fB(6)\fP \fI(since C++11)\fP - #define FP_FAST_FMAL /* implementation-defined */ \fB(7)\fP \fI(since C++11)\fP - - The fma functions compute (x*y) + z, rounded as one ternary operation, according to - the rounding mode characterized by the value of FLT_ROUNDS. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - - 5-7) If the macro constants FP_FAST_FMAF, FP_FAST_FMA, or FP_FAST_FMAL are defined, - the function std::fma evaluates faster than the expression x*y+z for float, double, - and long double arguments, respectively. If defined, these macros evaluate to - integer 1. - -.SH Parameters - - x, y, z - values of floating-point or integral types - -.SH Return value - - (x*y) + z, rounded as one ternary operation - -.SH See also - - remainder signed remainder of the division operation - \fI(C++11)\fP \fI(function)\fP - remquo signed remainder as well as the three last bits of the division operation - \fI(C++11)\fP \fI(function)\fP - C documentation for - fma diff --git a/man/std::fmax,std::fmaxf,std::fmaxl.3 b/man/std::fmax,std::fmaxf,std::fmaxl.3 new file mode 100644 index 000000000..81956342f --- /dev/null +++ b/man/std::fmax,std::fmaxf,std::fmaxl.3 @@ -0,0 +1,129 @@ +.TH std::fmax,std::fmaxf,std::fmaxl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fmax,std::fmaxf,std::fmaxl \- std::fmax,std::fmaxf,std::fmaxl + +.SH Synopsis + Defined in header + float fmax ( float x, float y ); + + double fmax ( double x, double y ); (until C++23) + + long double fmax ( long double x, long double y ); + constexpr /* floating-point-type */ + + fmax ( /* floating-point-type */ x, (since C++23) + \fB(1)\fP + /* floating-point-type */ y ); + float fmaxf( float x, float y ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double fmaxl( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double fmax ( Integer x, Integer y ); + + 1-3) Returns the larger of two floating point arguments, treating NaNs as missing + data (between a NaN and a numeric value, the numeric value is chosen). + The library provides overloads of std::fmax for all cv-unqualified floating-point + types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + x, y - floating-point or integer values + +.SH Return value + + If successful, returns the larger of two floating point values. The value returned + is exact and does not depend on any rounding modes. + +.SH Error handling + + This function is not subject to any of the error conditions specified in + math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If one of the two arguments is NaN, the value of the other argument is returned. + * Only if both arguments are NaN, NaN is returned. + +.SH Notes + + This function is not required to be sensitive to the sign of zero, although some + implementations additionally enforce that if one argument is +0 and the other is -0, + then +0 is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::fmax(num1, num2) + has the same effect as std::fmax(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::fmax(num1, num2) has the same effect as (until C++23) + std::fmax(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::fmax(num1, + num2) has the same effect as std::fmax(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::fmax(num1, num2) has + the same effect as std::fmax(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "fmax(2,1) = " << std::fmax(2, 1) << '\\n' + << "fmax(-Inf,0) = " << std::fmax(-INFINITY, 0) << '\\n' + << "fmax(NaN,-1) = " << std::fmax(NAN, -1) << '\\n'; + } + +.SH Output: + + fmax(2,1) = 2 + fmax(-Inf,0) = 0 + fmax(NaN,-1) = -1 + +.SH See also + + isgreater checks if the first floating-point argument is greater than the + \fI(C++11)\fP second + \fI(function)\fP + fmin + fminf + fminl smaller of two floating point values + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + max returns the greater of the given values + \fI(function template)\fP + max_element returns the largest element in a range + \fI(function template)\fP + minmax returns the smaller and larger of two elements + \fI(C++11)\fP \fI(function template)\fP + minmax_element returns the smallest and the largest elements in a range + \fI(C++11)\fP \fI(function template)\fP + C documentation for + fmax diff --git a/man/std::fmax.3 b/man/std::fmax.3 deleted file mode 100644 index aff526762..000000000 --- a/man/std::fmax.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::fmax 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float fmax( float x, float y ); \fB(1)\fP \fI(since C++11)\fP - double fmax( double x, double y ); \fB(2)\fP \fI(since C++11)\fP - long double fmax( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP - Promoted fmax( Arithmetic1 x, Arithmetic2 y ); \fB(4)\fP \fI(since C++11)\fP - - Returns the larger of two floating point arguments. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - - If one of the arguments is NaN, this function returns the other argument. If both - arguments are NaNs, the function returns NaN. - -.SH Parameters - - x, y - values of floating-point or integral types - -.SH Return value - - The larger of two floating point values. - -.SH See also - - fmin smaller of two floating point values - \fI(C++11)\fP \fI(function)\fP - C documentation for - fmax diff --git a/man/std::fmin,std::fminf,std::fminl.3 b/man/std::fmin,std::fminf,std::fminl.3 new file mode 100644 index 000000000..7ad46be41 --- /dev/null +++ b/man/std::fmin,std::fminf,std::fminl.3 @@ -0,0 +1,128 @@ +.TH std::fmin,std::fminf,std::fminl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fmin,std::fminf,std::fminl \- std::fmin,std::fminf,std::fminl + +.SH Synopsis + Defined in header + float fmin ( float x, float y ); + + double fmin ( double x, double y ); (until C++23) + + long double fmin ( long double x, long double y ); + constexpr /* floating-point-type */ + + fmin ( /* floating-point-type */ x, (since C++23) + \fB(1)\fP + /* floating-point-type */ y ); + float fminf( float x, float y ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double fminl( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double fmin ( Integer x, Integer y ); + + 1-3) Returns the smaller of two floating point arguments, treating NaNs as missing + data (between a NaN and a numeric value, the numeric value is chosen). + The library provides overloads of std::fmin for all cv-unqualified floating-point + types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + x, y - floating-point or integer values + +.SH Return value + + If successful, returns the smaller of two floating point values. The value returned + is exact and does not depend on any rounding modes. + +.SH Error handling + + This function is not subject to any of the error conditions specified in + math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If one of the two arguments is NaN, the value of the other argument is returned. + * Only if both arguments are NaN, NaN is returned. + +.SH Notes + + This function is not required to be sensitive to the sign of zero, although some + implementations additionally enforce that if one argument is +0 and the other is -0, + then -0 is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::fmin(num1, num2) + has the same effect as std::fmin(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::fmin(num1, num2) has the same effect as (until C++23) + std::fmin(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::fmin(num1, + num2) has the same effect as std::fmin(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::fmin(num1, num2) has + the same effect as std::fmin(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "fmin(2,1) = " << std::fmin(2, 1) << '\\n' + << "fmin(-Inf,0) = " << std::fmin(-INFINITY, 0) << '\\n' + << "fmin(NaN,-1) = " << std::fmin(NAN, -1) << '\\n'; + } + +.SH Possible output: + + fmin(2,1) = 1 + fmin(-Inf,0) = -inf + fmin(NaN,-1) = -1 + +.SH See also + + isless checks if the first floating-point argument is less than the second + \fI(C++11)\fP \fI(function)\fP + fmax + fmaxf + fmaxl larger of two floating-point values + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + min returns the smaller of the given values + \fI(function template)\fP + min_element returns the smallest element in a range + \fI(function template)\fP + minmax returns the smaller and larger of two elements + \fI(C++11)\fP \fI(function template)\fP + minmax_element returns the smallest and the largest elements in a range + \fI(C++11)\fP \fI(function template)\fP + C documentation for + fmin diff --git a/man/std::fmin.3 b/man/std::fmin.3 deleted file mode 100644 index b8dc558c5..000000000 --- a/man/std::fmin.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::fmin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float fmin( float x, float y ); \fB(1)\fP \fI(since C++11)\fP - double fmin( double x, double y ); \fB(2)\fP \fI(since C++11)\fP - long double fmin( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP - Promoted fmin( Arithmetic x, Arithmetic y ); \fB(4)\fP \fI(since C++11)\fP - - Returns the smaller of two floating point arguments. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - - If one of the arguments is NaN, this function returns the other argument. If both - arguments are NaNs, the function returns NaN. - -.SH Parameters - - x, y - values of floating-point or integral types - -.SH Return value - - The smaller of two floating point values. - -.SH See also - - fmax larger of two floating point values - \fI(C++11)\fP \fI(function)\fP - C documentation for - fmin diff --git a/man/std::fmod,std::fmodf,std::fmodl.3 b/man/std::fmod,std::fmodf,std::fmodl.3 new file mode 100644 index 000000000..19ceb7b7d --- /dev/null +++ b/man/std::fmod,std::fmodf,std::fmodl.3 @@ -0,0 +1,182 @@ +.TH std::fmod,std::fmodf,std::fmodl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fmod,std::fmodf,std::fmodl \- std::fmod,std::fmodf,std::fmodl + +.SH Synopsis + Defined in header + float fmod ( float x, float y ); + + double fmod ( double x, double y ); (until C++23) + + long double fmod ( long double x, long double y ); + constexpr /* floating-point-type */ + + fmod ( /* floating-point-type */ x, (since C++23) + \fB(1)\fP + /* floating-point-type */ y ); + float fmodf( float x, float y ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double fmodl( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double fmod ( Integer x, Integer y ); + + 1-3) Computes the floating-point remainder of the division operation x / y. + The library provides overloads of std::fmod for all cv-unqualified floating-point + types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + + The floating-point remainder of the division operation x / y calculated by this + function is exactly the value x - rem * y, where rem is x / y with its fractional + part truncated. + + The returned value has the same sign as x and is less than y in magnitude. + +.SH Parameters + + x, y - floating-point or integer values + +.SH Return value + + If successful, returns the floating-point remainder of the division x / y as defined + above. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error may occur if y is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If x is ±0 and y is not zero, ±0 is returned. + * If x is ±∞ and y is not NaN, NaN is returned and FE_INVALID is raised. + * If y is ±0 and x is not NaN, NaN is returned and FE_INVALID is raised. + * If y is ±∞ and x is finite, x is returned. + * If either argument is NaN, NaN is returned. + +.SH Notes + + POSIX requires that a domain error occurs if x is infinite or y is zero. + + std::fmod, but not std::remainder is useful for doing silent wrapping of + floating-point types to unsigned integer types: (0.0 <= (y = std::fmod(std::rint(x), + 65536.0)) ? y : 65536.0 + y) is in the range [-0.0, 65535.0], which corresponds to + unsigned short, but std::remainder(std::rint(x), 65536.0 is in the range + [-32767.0, +32768.0], which is outside of the range of signed short. + + The double version of std::fmod behaves as if implemented as follows: + + double fmod(double x, double y) + { + #pragma STDC FENV_ACCESS ON + double result = std::remainder(std::fabs(x), y = std::fabs(y)); + if (std::signbit(result)) + result += y; + return std::copysign(result, x); + } + + The expression x - std::trunc(x / y) * y may not equal std::fmod(x, y), when the + rounding of x / y to initialize the argument of std::trunc loses too much precision + (example: x = 30.508474576271183309, y = 6.1016949152542370172). + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::fmod(num1, num2) + has the same effect as std::fmod(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::fmod(num1, num2) has the same effect as (until C++23) + std::fmod(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::fmod(num1, + num2) has the same effect as std::fmod(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::fmod(num1, num2) has + the same effect as std::fmod(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "fmod(+5.1, +3.0) = " << std::fmod(5.1, 3) << '\\n' + << "fmod(-5.1, +3.0) = " << std::fmod(-5.1, 3) << '\\n' + << "fmod(+5.1, -3.0) = " << std::fmod(5.1, -3) << '\\n' + << "fmod(-5.1, -3.0) = " << std::fmod(-5.1, -3) << '\\n'; + + // special values + std::cout << "fmod(+0.0, 1.0) = " << std::fmod(0, 1) << '\\n' + << "fmod(-0.0, 1.0) = " << std::fmod(-0.0, 1) << '\\n' + << "fmod(5.1, Inf) = " << std::fmod(5.1, INFINITY) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + std::cout << "fmod(+5.1, 0) = " << std::fmod(5.1, 0) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + fmod(+5.1, +3.0) = 2.1 + fmod(-5.1, +3.0) = -2.1 + fmod(+5.1, -3.0) = 2.1 + fmod(-5.1, -3.0) = -2.1 + fmod(+0.0, 1.0) = 0 + fmod(-0.0, 1.0) = -0 + fmod(5.1, Inf) = 5.1 + fmod(+5.1, 0) = -nan + FE_INVALID raised + +.SH See also + + div(int) + ldiv computes quotient and remainder of integer division + lldiv \fI(function)\fP + \fI(C++11)\fP + remainder + remainderf + remainderl signed remainder of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remquo + remquof + remquol signed remainder as well as the three last bits of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + fmod diff --git a/man/std::fmod.3 b/man/std::fmod.3 deleted file mode 100644 index ad85cea26..000000000 --- a/man/std::fmod.3 +++ /dev/null @@ -1,37 +0,0 @@ -.TH std::fmod 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float fmod( float x, float y ); \fB(1)\fP - double fmod( double x, double y ); \fB(2)\fP - long double fmod( long double x, long double y ); \fB(3)\fP - Promoted fmod( Arithmetic1 x, Arithmetic2 y ); \fB(4)\fP \fI(since C++11)\fP - - Computes the remainder of the division operation x/y. - - Specifically, the returned value is x - n*y, where n is x/y with its fractional part - truncated. - - The returned value will have the same sign as x. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - -.SH Parameters - - x, y - floating point values - -.SH Return value - - Remainder of dividing arguments. The result has the same sign as x. - -.SH See also - - div - ldiv the quotient and remainder of integer division - lldiv \fI(function)\fP - imaxdiv - \fI(C++11)\fP - remainder signed remainder of the division operation - \fI(C++11)\fP \fI(function)\fP - C documentation for - fmod diff --git a/man/std::fopen.3 b/man/std::fopen.3 index 0a9b5e953..5f394d813 100644 --- a/man/std::fopen.3 +++ b/man/std::fopen.3 @@ -1,4 +1,7 @@ -.TH std::fopen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fopen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fopen \- std::fopen + .SH Synopsis Defined in header std::FILE* fopen( const char* filename, const char* mode ); @@ -9,39 +12,97 @@ .SH Parameters filename - file name to associate the file stream to - null-terminated character string determining file access mode - - Action if Action if - File access Meaning Explanation file file - mode string already does not - exists exist - "r" read Open a file for read from failure to - reading start open - "w" write Create a file for destroy create new - writing contents - mode - "a" append Append to a file write to end create new - "r+" read extended Open a file for read from error - read/write start - "w+" write extended Create a file for destroy create new - read/write contents - "a+" append Open a file for write to end create new - extended read/write - File access mode flag "b" can optionally be specified to open a file in - binary mode. This flag has effect only on Windows systems. - On the append file access modes, data is written to the end of the file - regardless of the current position of the file position indicator. + mode - null-terminated character string determining file access mode + + File access flags + + File access Meaning Explanation Action if file Action if file + mode string already exists does not exist + "r" read Open a file for read from start return NULL and + reading set error + "w" write Create a file for destroy contents create new + writing + "a" append Append to a file write to end create new + "r+" read extended Open a file for read from start return NULL and + read/write set error + "w+" write extended Create a file for destroy contents create new + read/write + "a+" append extended Open a file for write to end create new + read/write + File access mode flag "b" can optionally be specified to open a file in binary mode. + This flag has no effect on POSIX systems, but on Windows, for example, it disables + special handling of '\\n' and '\\x1A'. + On the append file access modes, data is written to the end of the file regardless + of the current position of the file position indicator. + File access mode flag "x" can optionally be appended to "w" or "w+" specifiers. This + flag forces the function to fail if the file exists, instead of overwriting it. + \fI(C++17)\fP + The behavior is undefined if the mode is not one of the strings listed above. Some + implementations define additional supported modes (e.g. Windows). .SH Return value - Opened file stream on success, NULL on failure + If successful, returns a pointer to the object that controls the opened file stream, + with both eof and error bits cleared. The stream is fully buffered unless filename + refers to an interactive device. + + On error, returns a null pointer. POSIX requires that errno is set in this case. + +.SH Notes + + The format of filename is implementation-defined, and does not necessarily refer to + a file (e.g. it may be the console or another device accessible through filesystem + API). On platforms that support them, filename may include absolute or relative + filesystem path. + + For portable directory and file naming, see C++ filesystem library or + boost.filesystem. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int is_ok = EXIT_FAILURE; + FILE* fp = std::fopen("/tmp/test.txt", "w+"); + if (!fp) + { + std::perror("File opening failed"); + return is_ok; + } + + int c; // Note: int, not char, required to handle EOF + while ((c = std::fgetc(fp)) != EOF) // Standard C I/O file reading loop + std::putchar(c); + + if (std::ferror(fp)) + std::puts("I/O error when reading"); + else if (std::feof(fp)) + { + std::puts("End of file reached successfully"); + is_ok = EXIT_SUCCESS; + } + + std::fclose(fp); + return is_ok; + } + +.SH Output: + + End of file reached successfully .SH See also fclose closes a file - \fI(function)\fP + \fI(function)\fP fflush synchronizes an output stream with the actual file - \fI(function)\fP + \fI(function)\fP freopen open an existing stream with a different name - \fI(function)\fP + \fI(function)\fP C documentation for fopen diff --git a/man/std::for_each.3 b/man/std::for_each.3 index 867e51fe7..d26d5b5e7 100644 --- a/man/std::for_each.3 +++ b/man/std::for_each.3 @@ -1,96 +1,180 @@ -.TH std::for_each 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::for_each 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::for_each \- std::for_each + .SH Synopsis Defined in header - template< class InputIt, class UnaryFunction > - UnaryFunction for_each( InputIt first, InputIt last, UnaryFunction f ); + template< class InputIt, class UnaryFunc > + UnaryFunc for_each( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + UnaryFunc f ); + template< class ExecutionPolicy, class ForwardIt, class + UnaryFunc > + + void for_each( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, + UnaryFunc f ); Applies the given function object f to the result of dereferencing every iterator in - the range [first, last), in order. + the range [first, last). If f returns a result, the result is ignored. + + 1) f is applied in order starting from first. + + If UnaryFunc is not MoveConstructible, the behavior is undefined. \fI(since C++11)\fP + + 2) f might not be applied in order. The algorithm is executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If UnaryFunc is not CopyConstructible, the behavior is undefined. + + If the iterator type (InputIt/ForwardIt) is mutable, f may modify the elements of + the range through the dereferenced iterator. - If InputIt is a mutable iterator, f may modify the elements of the range through the - dereferenced iterator. If f returns a result, the result is ignored. + Unlike the rest of the parallel algorithms, for_each is not allowed to make copies + of the elements in the sequence even if they are TriviallyCopyable. .SH Parameters - first, last - the range to apply the function to - f - the unary function object to be applied + first, last - the range to apply the function to + policy - the execution policy to use. See execution policy for details. + function object, to be applied to the result of dereferencing every + iterator in the range [first, last) + + The signature of the function should be equivalent to the following: + + f - void fun(const Type &a); + + The signature does not need to have const &. + The type Type must be such that an object of type InputIt can be + dereferenced and then implicitly converted to Type. + + .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - UnaryFunction must meet the requirements of MoveConstructible. Does not have to be - CopyConstructible + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value - f \fI(until C++11)\fP - std::move(f) \fI(since C++11)\fP + 1) f + 2) \fI(none)\fP .SH Complexity - Exactly last - first applications of f + Exactly std::distance(first, last) applications of f. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template - UnaryFunction for_each(InputIt first, InputIt last, UnaryFunction f) + See also the implementations in libstdc++, libc++ and MSVC stdlib. + + template + constexpr UnaryFunc for_each(InputIt first, InputIt last, UnaryFunc f) { - for (; first != last; ++first) { + for (; first != last; ++first) f(*first); - } - return f; + + return f; // implicit move since C++11 } +.SH Notes + + For overload \fB(1)\fP, f can be a stateful function object. The return value can be + considered as the final state of the batch operation. + + For overload \fB(2)\fP, multiple copies of f may be created to perform parallel + invocation. No value is returned because parallelization often does not permit + efficient state accumulation. + .SH Example - The following example uses a lambda function to increment all of the elements of a - vector and then uses an overloaded operator() in a functor to compute their sum: + The following example uses a lambda-expression to increment all of the elements of a + vector and then uses an overloaded operator() in a function object (a.k.a., + "functor") to compute their sum. Note that to compute the sum, it is recommended to + use the dedicated algorithm std::accumulate. + - // Run this code - #include #include #include - - struct Sum { - Sum() { sum = 0; } - void operator()(int n) { sum += n; } - - int sum; - }; - + #include + int main() { - std::vector nums{3, 4, 2, 9, 15, 267}; - - std::cout << "before: "; - for (auto n : nums) { - std::cout << n << " "; - } + std::vector v{3, -4, 2, -8, 15, 267}; + + auto print = [](const int& n) { std::cout << n << ' '; }; + + std::cout << "before:\\t"; + std::for_each(v.cbegin(), v.cend(), print); std::cout << '\\n'; - - std::for_each(nums.begin(), nums.end(), [](int &n){ n++; }); - - // Calls Sum::operator() for each number - Sum s = std::for_each(nums.begin(), nums.end(), Sum()); - - std::cout << "after: "; - for (auto n : nums) { - std::cout << n << " "; - } + + // increment elements in-place + std::for_each(v.begin(), v.end(), [](int &n) { n++; }); + + std::cout << "after:\\t"; + std::for_each(v.cbegin(), v.cend(), print); std::cout << '\\n'; - std::cout << "sum: " << s.sum << '\\n'; + + struct Sum + { + void operator()(int n) { sum += n; } + int sum {0}; + }; + + // invoke Sum::operator() for each element + Sum s = std::for_each(v.cbegin(), v.cend(), Sum()); + std::cout << "sum:\\t" << s.sum << '\\n'; } .SH Output: - before: 3 4 2 9 15 267 - after: 4 5 3 10 16 268 - sum: 306 + before: 3 -4 2 -8 15 267 + after: 4 -3 3 -7 16 268 + sum: 281 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether f can modify + the elements + LWG 475 C++98 of the sequence being iterated over made clear (allowed if the + (for_each is iterator type is mutable) + classified as “non-modifying sequence + operations”) + LWG 2747 C++11 overload \fB(1)\fP returned std::move(f) returns f (which + implicitly moves) .SH See also - transform applies a function to a range of elements - \fI(function template)\fP - range-for loop executes loop over range \fI(since C++11)\fP + applies a function to a range of elements, storing results in + transform a destination range + \fI(function template)\fP + for_each_n applies a function object to the first N elements of a + \fI(C++17)\fP sequence + \fI(function template)\fP + ranges::for_each applies a function to a range of elements + (C++20) (niebloid) + ranges::for_each_n applies a function object to the first N elements of a + (C++20) sequence + (niebloid) + range-for loop\fI(C++11)\fP executes loop over range diff --git a/man/std::for_each_n.3 b/man/std::for_each_n.3 new file mode 100644 index 000000000..bb77c6f31 --- /dev/null +++ b/man/std::for_each_n.3 @@ -0,0 +1,136 @@ +.TH std::for_each_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::for_each_n \- std::for_each_n + +.SH Synopsis + Defined in header + template< class InputIt, class Size, class UnaryFunc > \fI(since C++17)\fP + InputIt for_each_n( InputIt first, Size n, UnaryFunc f \fB(1)\fP (constexpr since C++20) + ); + template< class ExecutionPolicy, + + class ForwardIt, class Size, class UnaryFunc > + ForwardIt for_each_n( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, Size n, UnaryFunc + f ); + + Applies the given function object f to the result of dereferencing every iterator in + the range [first, first + n). If f returns a result, the result is ignored. + + 1) f is applied in order starting from first. + If UnaryFunc is not MoveConstructible, the behavior is undefined. + 2) f might not be applied in order. The algorithm is executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If UnaryFunc is not CopyConstructible, the behavior is undefined. + + If n >= 0 is not true, the behavior is undefined. + + If the iterator type (InputIt/ForwardIt) is mutable, f may modify the elements of + the range through the dereferenced iterator. + + Unlike the rest of the parallel algorithms, for_each_n is not allowed to make copies + of the elements in the sequence even if they are TriviallyCopyable. + +.SH Parameters + + first - the beginning of the range to apply the function to + n - the number of elements to apply the function to + policy - the execution policy to use. See execution policy for details. + function object, to be applied to the result of dereferencing every + iterator in the range [first, first + n) + + The signature of the function should be equivalent to the following: + + f - void fun(const Type &a); + + The signature does not need to have const &. + The type Type must be such that an object of type InputIt can be + dereferenced and then implicitly converted to Type. + + +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Size must be convertible to an integral type. + +.SH Return value + + An iterator equal to first + n, or more formally, to std::advance(first, n). + +.SH Complexity + + Exactly n applications of f. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + See also the implementation in libstdc++, libc++ and MSVC stdlib. + + template + InputIt for_each_n(InputIt first, Size n, UnaryFunc f) + { + for (Size i = 0; i < n; ++first, (void) ++i) + f(*first); + + return first; + } + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto const& v) + { + for (auto count{v.size()}; const auto& e : v) + std::cout << e << (--count ? ", " : "\\n"); + } + + int main() + { + std::vector vi{1, 2, 3, 4, 5}; + println(vi); + + std::for_each_n(vi.begin(), 3, [](auto& n) { n *= 2; }); + println(vi); + } + +.SH Output: + + 1, 2, 3, 4, 5 + 2, 4, 6, 4, 5 + +.SH See also + + applies a function to a range of elements, storing results in + transform a destination range + \fI(function template)\fP + range-for loop\fI(C++11)\fP executes loop over range + for_each applies a function to a range of elements + \fI(function template)\fP + ranges::for_each_n applies a function object to the first N elements of a + (C++20) sequence + (niebloid) diff --git a/man/std::format.3 b/man/std::format.3 new file mode 100644 index 000000000..8d1cc3e3e --- /dev/null +++ b/man/std::format.3 @@ -0,0 +1,194 @@ +.TH std::format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::format \- std::format + +.SH Synopsis + Defined in header + template< class... Args > + std::string format( std::format_string fmt, Args&&... \fB(1)\fP \fI(since C++20)\fP + args ); + template< class... Args > + std::wstring format( std::wformat_string fmt, Args&&... \fB(2)\fP \fI(since C++20)\fP + args ); + template< class... Args > + + std::string format( const std::locale& loc, \fB(3)\fP \fI(since C++20)\fP + + std::format_string fmt, Args&&... + args ); + template< class... Args > + + std::wstring format( const std::locale& loc, \fB(4)\fP \fI(since C++20)\fP + + std::wformat_string fmt, Args&&... + args ); + + Format args according to the format string fmt, and return the result as a string. + If present, loc is used for locale-specific formatting. + + 1) Equivalent to return std::vformat(fmt.get(), std::make_format_args(args...));. + 2) Equivalent to return std::vformat(fmt.get(), std::make_wformat_args(args...));. + 3) Equivalent to return std::vformat(loc, fmt.get(), + std::make_format_args(args...));. + 4) Equivalent to return std::vformat(loc, fmt.get(), + std::make_wformat_args(args...));. + + Since P2216R3, std::format does a compile-time check on the format string (via the + helper type std::format_string or std::wformat_string). If it is found to be invalid + for the types of the arguments to be formatted, a compilation error will be emitted. + If the format string cannot be a compile-time constant, or the compile-time check + needs to be avoided, use std::vformat + or std::runtime_format on fmt + (since C++26) instead. + + The following requirements apply to each type T in Args, where CharT is char for + overloads (1,3), wchar_t for overloads (2,4): + + * std::formatter must satisfy BasicFormatter + * std::formatter::parse() must be constexpr since P2216R3 (std::vformat + does not have this requirement) + +.SH Parameters + + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + loc - std::locale used for locale-specific formatting + +.SH Return value + + A string object holding the formatted result. + +.SH Exceptions + + Throws std::bad_alloc on allocation failure. Also propagates exception thrown by any + formatter. + +.SH Notes + + It is not an error to provide more arguments than the format string requires: + + std::format("{} {}!", "Hello", "world", "something"); // OK, produces "Hello world!" + + As of P2216R3, it is an error if the format string is not a constant expression. + std::vformat can be used in this case. + + std::string f(std::string_view runtime_format_string) + { + // return std::format(runtime_format_string, "foo", "bar"); // error + return std::vformat(runtime_format_string, std::make_format_args("foo", "bar")); // OK + } + + std::runtime_format can be used directly on std::format instead of std::vformat + which requires std::basic_format_args as an argument. + (since + std::string f(std::string_view runtime_format_string) C++26) + { + return std::format(std::runtime_format(runtime_format_string), "foo", "bar"); + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + std::string dyna_print(std::string_view rt_fmt_str, Args&&... args) + { + return std::vformat(rt_fmt_str, std::make_format_args(args...)); + } + + int main() + { + std::cout << std::format("Hello {}!\\n", "world"); + + std::string fmt; + for (int i{}; i != 3; ++i) + { + fmt += "{} "; // constructs the formatting string + std::cout << fmt << " : "; + std::cout << dyna_print(fmt, "alpha", 'Z', 3.14, "unused"); + std::cout << '\\n'; + } + } + +.SH Output: + + Hello world! + {} : alpha + {} {} : alpha Z + {} {} {} : alpha Z 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2216R3 C++20 throws std::format_error for invalid format string results in + invalid format string compile-time error + objects that are neither + P2418R2 C++20 const-usable nor copyable allow formatting these objects + (such as generator-like objects) + are not formattable + P2508R1 C++20 there's no user-visible name for the name basic_format_string is + this facility exposed + +.SH See also + + format_to writes out formatted representation of its arguments through an output + (C++20) iterator + \fI(function template)\fP + format_to_n writes out formatted representation of its arguments through an output + (C++20) iterator, not exceeding specified size + \fI(function template)\fP diff --git a/man/std::format_error.3 b/man/std::format_error.3 new file mode 100644 index 000000000..6184228bf --- /dev/null +++ b/man/std::format_error.3 @@ -0,0 +1,98 @@ +.TH std::format_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::format_error \- std::format_error + +.SH Synopsis + Defined in header + class format_error; \fI(since C++20)\fP + + Defines the type of exception object thrown to report errors in the formatting + library. + + std-format error-inheritance.svg + + Inheritance diagram + +.SH Member functions + + constructor constructs a new format_error object with the given message + \fI(public member function)\fP + operator= replaces the format_error object + \fI(public member function)\fP + +std::format_error::format_error + + format_error( const std::string& what_arg ); \fB(1)\fP + format_error( const char* what_arg ); \fB(2)\fP + format_error( const format_error& other ) noexcept; \fB(3)\fP + + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::format_error + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. + +.SH Parameters + + what_arg - explanatory string + other - another exception object to copy + +.SH Exceptions + + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::format_error is not permitted to throw exceptions, this message + is typically stored internally as a separately-allocated reference-counted string. + This is also why there is no constructor taking std::string&&: it would have to copy + the content anyway. + + A derived standard exception class must have a publicly accessible copy constructor. + It can be implicitly defined as long as the explanatory strings obtained by what() + are the same for the original object and the copied object. + +std::format_error::operator= + + format_error& operator=( const format_error& other ) noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::format_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + A derived standard exception class must have a publicly accessible copy assignment + operator. It can be implicitly defined as long as the explanatory strings obtained + by what() are the same for the original object and the copied object. + +Inherited from std::runtime_error + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + +.SH Category: + * Todo no example diff --git a/man/std::format_kind.3 b/man/std::format_kind.3 new file mode 100644 index 000000000..2baf0bc02 --- /dev/null +++ b/man/std::format_kind.3 @@ -0,0 +1,110 @@ +.TH std::format_kind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::format_kind \- std::format_kind + +.SH Synopsis + Defined in header + template< class R > + inline constexpr /* unspecified */ format_kind = /* unspecified \fB(1)\fP (since C++23) + */; + template< ranges::input_range R > + + requires std::same_as> \fB(2)\fP (since C++23) + + inline constexpr range_format format_kind = /* see description + */; + + The variable template format_kind selects an appropriate std::range_format for a + range R. + + std::format_kind is defined as follows: + + * If std::same_as>, R> is true, + std::format_kind is std::range_format::disabled. + * Otherwise, if R::key_type is valid and denotes a type: + * If R::mapped_type is valid and denotes a type, let U be + std::remove_cvref_t>. + + If either U is a specialization of std::pair or U is a specialization of std::tuple + and std::tuple_size_v == 2, std::format_kind is std::range_format::map. + * + * Otherwise, std::format_kind is std::range_format::set. + * Otherwise, std::format_kind is std::range_format::sequence. + + A program that instantiates a primary template of the format_kind variable template + is ill-formed. + + Given a cv-unqualified program-defined type T that models input_range, a program can + spcialize format_kind for T. Such specializations are usable in constant + expressions, and have type const std::range_format. + +.SH Possible implementation + +namespace detail +{ + template< typename > + inline constexpr bool is_pair_or_tuple_2 = false; + + template< typename T, typename U > + inline constexpr bool is_pair_or_tuple_2> = true; + + template< typename... Ts > + inline constexpr bool is_pair_or_tuple_2> = sizeof...(Ts) == 2; + + template < typename T > + requires std::is_reference_v || std::is_const_v + inline constexpr bool is_pair_or_tuple_2 = + is_pair_or_tuple_2>; +} + +template< class R > +inline constexpr range_format format_kind = [] +{ + static_assert(false, "instantiating a primary template is not allowed"); + return range_format::disabled; +}(); + +template< ranges::input_range R > + requires std::same_as> +inline constexpr range_format format_kind = [] +{ + if constexpr (std::same_as>, R>) + return range_format::disabled; + else if constexpr (requires { typename R::key_type; }) + { + if constexpr (requires { typename R::mapped_type; } && + detail::is_pair_or_tuple_2>) + return range_format::map; + else + return range_format::set; + } + else + return range_format::sequence; +}(); + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct A {}; + + static_assert(std::format_kind> == std::range_format::sequence); + static_assert(std::format_kind> == std::range_format::map); + static_assert(std::format_kind> == std::range_format::set); + static_assert(std::format_kind == std::range_format::disabled); + // ill-formed: + // static_assert(std::format_kind == std::range_format::disabled); + + int main() {} + +.SH See also + + range_format specifies how a range should be formatted + (C++23) \fI(enum)\fP diff --git a/man/std::format_to.3 b/man/std::format_to.3 new file mode 100644 index 000000000..bad1bb30d --- /dev/null +++ b/man/std::format_to.3 @@ -0,0 +1,185 @@ +.TH std::format_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::format_to \- std::format_to + +.SH Synopsis + Defined in header + template< class OutputIt, class... Args > + OutputIt format_to( OutputIt out, std::format_string fmt, \fB(1)\fP \fI(since C++20)\fP + Args&&... args ); + template< class OutputIt, class... Args > + OutputIt format_to( OutputIt out, std::wformat_string \fB(2)\fP \fI(since C++20)\fP + fmt, Args&&... args ); + template< class OutputIt, class... Args > + + OutputIt format_to( OutputIt out, const std::locale& loc, \fB(3)\fP \fI(since C++20)\fP + + std::format_string fmt, Args&&... + args ); + template< class OutputIt, class... Args > + + OutputIt format_to( OutputIt out, const std::locale& loc, \fB(4)\fP \fI(since C++20)\fP + + std::wformat_string fmt, Args&&... + args ); + + Format args according to the format string fmt, and write the result to the output + iterator out. If present, loc is used for locale-specific formatting. + + 1) equivalent to return std::vformat_to(out, fmt.str, + std::make_format_args(args...)); + 2) equivalent to return std::vformat_to(std::move(out), fmt.str, + std::make_wformat_args(args...)); + 3) equivalent to return std::vformat_to(out, loc, fmt.str, + std::make_format_args(args...)); + 4) equivalent to return std::vformat_to(std::move(out), loc, fmt.str, + std::make_wformat_args(args...)); + + Let CharT be char for overloads (1,3), wchar_t for overloads (2,4). + + These overloads participate in overload resolution only if OutputIt satisfies the + concept std::output_iterator. + + The behavior is undefined if OutputIt does not model (meet the semantic requirements + of) the concept std::output_iterator, or if std::formatter + does not meet the BasicFormatter requirements for any Ti in Args (as required by + std::make_format_args and std::make_wformat_args). + +.SH Parameters + + out - iterator to the output buffer + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + loc - std::locale used for locale-specific formatting + +.SH Return value + + Iterator past the end of the output range. + +.SH Exceptions + + Propagates any exception thrown by formatter or iterator operations. + +.SH Notes + + As of P2216R3, it is an error if the format string is not a constant expression. + std::vformat_to + or std::runtime_format + (since C++26) can be used in this case. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + auto main() -> int + { + std::string buffer; + + std::format_to( + std::back_inserter(buffer), //< OutputIt + "Hello, C++{}!\\n", //< fmt + "20"); //< arg + std::cout << buffer; + buffer.clear(); + + std::format_to( + std::back_inserter(buffer), //< OutputIt + "Hello, {0}::{1}!{2}", //< fmt + "std", //< arg {0} + "format_to()", //< arg {1} + "\\n", //< arg {2} + "extra param(s)..."); //< unused + std::cout << buffer; + + std::wstring wbuffer; + std::format_to( + std::back_inserter(wbuffer),//< OutputIt + L"Hello, {2}::{1}!{0}", //< fmt + L"\\n", //< arg {0} + L"format_to()", //< arg {1} + L"std", //< arg {2} + L"...is not..." //< unused + L"...an error!"); //< unused + std::wcout << wbuffer; + } + +.SH Output: + + Hello, C++20! + Hello, std::format_to()! + Hello, std::format_to()! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2216R3 C++20 throws std::format_error for invalid format string results in + invalid format string compile-time error + objects that are neither + P2418R2 C++20 const-usable nor copyable allow formatting these objects + (such as generator-like objects) + are not formattable + P2508R1 C++20 there's no user-visible name for the name basic_format_string is + this facility exposed + +.SH See also + + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP + format_to_n writes out formatted representation of its arguments through an output + (C++20) iterator, not exceeding specified size + \fI(function template)\fP diff --git a/man/std::format_to_n,std::format_to_n_result.3 b/man/std::format_to_n,std::format_to_n_result.3 new file mode 100644 index 000000000..15235509a --- /dev/null +++ b/man/std::format_to_n,std::format_to_n_result.3 @@ -0,0 +1,201 @@ +.TH std::format_to_n,std::format_to_n_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::format_to_n,std::format_to_n_result \- std::format_to_n,std::format_to_n_result + +.SH Synopsis + Defined in header + template< class OutputIt, class... Args > + + std::format_to_n_result + format_to_n( OutputIt out, std::iter_difference_t n, \fB(1)\fP \fI(since C++20)\fP + + std::format_string fmt, Args&&... args + ); + template< class OutputIt, class... Args > + + std::format_to_n_result + format_to_n( OutputIt out, std::iter_difference_t n, \fB(2)\fP \fI(since C++20)\fP + + std::wformat_string fmt, Args&&... args + ); + template< class OutputIt, class... Args > + + std::format_to_n_result + format_to_n( OutputIt out, std::iter_difference_t n, \fB(3)\fP \fI(since C++20)\fP + const std::locale& loc, + + std::format_string fmt, Args&&... args + ); + template< class OutputIt, class... Args > + + std::format_to_n_result + format_to_n( OutputIt out, std::iter_difference_t n, \fB(4)\fP \fI(since C++20)\fP + const std::locale& loc, + + std::wformat_string fmt, Args&&... args + ); +.SH Helper types + template< class OutputIt > + + struct format_to_n_result { + OutputIt out; \fB(5)\fP \fI(since C++20)\fP + std::iter_difference_t size; + + }; + + Format args according to the format string fmt, and write the result to the output + iterator out. At most n characters are written. If present, loc is used for + locale-specific formatting. + + Let CharT be char for overloads (1,3), wchar_t for overloads (2,4). + + These overloads participate in overload resolution only if OutputIt satisfies the + concept std::output_iterator. + + The behavior is undefined if OutputIt does not model (meet the semantic requirements + of) the concept std::output_iterator, or if + std::formatter, CharT> does not meet the BasicFormatter + requirements for any Ti in Args. + + 5) std::format_to_n_result has no base classes, or members other than out, size and + implicitly declared special member functions. + +.SH Parameters + + out - iterator to the output buffer + n - maximum number of characters to be written to the buffer + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + loc - std::locale used for locale-specific formatting + +.SH Return value + + A format_to_n_result such that the out member is an iterator past the end of the + output range, and the size member is the total (not truncated) output size. + +.SH Exceptions + + Propagates any exception thrown by formatter or iterator operations. + +.SH Example + + At Godbolt's Compiler Explorer: clang (trunk) + libc++, gcc (trunk) + libstdc++. + + +// Run this code + + #include + #include + #include + + int main() + { + char buffer[64]; + + for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz}) + { + const auto result = + std::format_to_n( + buffer, max_chars_to_write, + "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters + 71, // {0}, occupies 2 bytes + 8, // {1}, occupies 1 byte + "\\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO) + "\\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO) + "\\u00B1" // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN) + ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\\0' + + *result.out = '\\0'; // adds terminator to buffer + + const std::string_view str{buffer, result.out}; // uses C++20 constructor + + std::cout << "Buffer until '\\\\0': \\"" << str << "\\"\\n" + << "Max chars to write: " << max_chars_to_write << '\\n' + << "result.out offset: " << result.out - buffer << '\\n' + << "Untruncated output size: " << result.size << "\\n\\n"; + } + } + +.SH Output: + + Buffer until '\\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc." + Max chars to write: 63 + result.out offset: 35 + Untruncated output size: 35 + + Buffer until '\\0': "Hubble's H₀ ≅ 71±8" + Max chars to write: 23 + result.out offset: 23 + Untruncated output size: 35 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2216R3 C++20 throws std::format_error for invalid format string results in + invalid format string compile-time error + objects that are neither + P2418R2 C++20 const-usable nor copyable allow formatting these objects + (such as generator-like objects) + are not formattable + P2508R1 C++20 there's no user-visible name for the name basic_format_string is + this facility exposed + +.SH See also + + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP + format_to writes out formatted representation of its arguments through an + (C++20) output iterator + \fI(function template)\fP + formatted_size determines the number of characters necessary to store the formatted + (C++20) representation of its arguments + \fI(function template)\fP diff --git a/man/std::formattable.3 b/man/std::formattable.3 new file mode 100644 index 000000000..b94c7c677 --- /dev/null +++ b/man/std::formattable.3 @@ -0,0 +1,60 @@ +.TH std::formattable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::formattable \- std::formattable + +.SH Synopsis + Defined in header + template< class T, class CharT > + + concept formattable = /* formattable_with */< + std::remove_reference_t, \fB(1)\fP (since C++23) + std::basic_format_context, CharT> + + >; + Helper templates + template< class CharT > \fB(2)\fP (exposition only*) + using /* fmt_iter_for */ = /* unspecified */; + template< class T, class Context, + + class Formatter = + typename Context::template + formatter_type> > + concept /* formattable_with */ = + std::semiregular && + requires (Formatter& f, const Formatter& cf, T&& t, Context + fc, \fB(3)\fP (exposition only*) + std::basic_format_parse_context< + typename Context::char_type + > pc) { + { f.parse(pc) } -> std::same_as; + { cf.format(t, fc) } -> std::same_as; + + }; + + The concept formattable specifies that std::formatter, CharT> + meets the requirements of BasicFormatter and Formatter (if + std::remove_reference_t is const-qualified). + + The exposition-only alias template /* fmt_iter_for */ yields an unspecified type + that satisfies std::output_iterator. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3925 C++23 the second template argument of provided + std::basic_format_context was not provided + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP + BasicFormatter abstracts formatting operations for a given formatting argument type + (C++20) and character type + (named requirement) + Formatter defines functions used by the formatting library + (C++20) (named requirement) diff --git a/man/std::formatted_size.3 b/man/std::formatted_size.3 new file mode 100644 index 000000000..39571e9d8 --- /dev/null +++ b/man/std::formatted_size.3 @@ -0,0 +1,156 @@ +.TH std::formatted_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::formatted_size \- std::formatted_size + +.SH Synopsis + Defined in header + template< class... Args > + std::size_t formatted_size( std::format_string fmt, \fB(1)\fP \fI(since C++20)\fP + Args&&... args ); + template< class... Args > + std::size_t formatted_size( std::wformat_string fmt, \fB(2)\fP \fI(since C++20)\fP + Args&&... args ); + template< class... Args > + + std::size_t formatted_size( const std::locale& loc, \fB(3)\fP \fI(since C++20)\fP + + std::format_string fmt, + Args&&... args ); + template< class... Args > + + std::size_t formatted_size( const std::locale& loc, \fB(4)\fP \fI(since C++20)\fP + + std::wformat_string fmt, + Args&&... args ); + + Determine the total number of characters in the formatted string by formatting args + according to the format string fmt. If present, loc is used for locale-specific + formatting. + + The behavior is undefined if std::formatter, CharT> does not + meet the BasicFormatter requirements for any Ti in Args. + +.SH Parameters + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + loc - std::locale used for locale-specific formatting + +.SH Return value + + The total number of characters in the formatted string. + +.SH Exceptions + + Propagates any exception thrown by formatter. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals::string_view_literals; + + constexpr auto fmt_str { "Hubble's H{0} {1} {2:*^4} miles/sec/mpc."sv }; + constexpr auto sub_zero { "₀"sv }; // { "\\u2080"sv } => { 0xe2, 0x82, 0x80 }; + constexpr auto aprox_equ { "≅"sv }; // { "\\u2245"sv } => { 0xe2, 0x89, 0x85 }; + constexpr int Ho { 42 }; // H₀ + + + const auto min_buffer_size = std::formatted_size(fmt_str, sub_zero, aprox_equ, Ho); + + std::cout << "Min buffer size = " << min_buffer_size << '\\n'; + + // Use std::vector as dynamic buffer. Note: buffer does not include the trailing '\\0'. + std::vector buffer(min_buffer_size); + + std::format_to_n(buffer.data(), buffer.size(), fmt_str, sub_zero, aprox_equ, Ho); + + std::cout << "Buffer: \\"" << std::string_view{buffer.data(), min_buffer_size} << "\\"\\n"; + + // Or we can print the buffer directly by adding the trailing '\\0'. + buffer.push_back('\\0'); + std::cout << "Buffer: \\"" << buffer.data() << "\\"\\n"; + } + +.SH Output: + + Min buffer size = 37 + Buffer: "Hubble's H₀ ≅ *42* miles/sec/mpc." + Buffer: "Hubble's H₀ ≅ *42* miles/sec/mpc." + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2216R3 C++20 throws std::format_error for invalid format string results in + invalid format string compile-time error + objects that are neither + P2418R2 C++20 const-usable nor copyable allow formatting these objects + (such as generator-like objects) + are not formattable + P2508R1 C++20 there's no user-visible name for the name basic_format_string is + this facility exposed + +.SH See also + + format_to writes out formatted representation of its arguments through an output + (C++20) iterator + \fI(function template)\fP + format_to_n writes out formatted representation of its arguments through an output + (C++20) iterator, not exceeding specified size + \fI(function template)\fP diff --git a/man/std::formatter,std::chrono::local_time_format.3 b/man/std::formatter,std::chrono::local_time_format.3 new file mode 100644 index 000000000..78d8d4541 --- /dev/null +++ b/man/std::formatter,std::chrono::local_time_format.3 @@ -0,0 +1,238 @@ +.TH std::formatter,std::chrono::local_time_format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::formatter,std::chrono::local_time_format \- std::formatter,std::chrono::local_time_format + +.SH Synopsis + Defined in header + template< class Duration, class CharT > \fB(1)\fP + struct formatter, CharT>; + template< class Duration > + + struct /*local-time-format-t*/ { + std::chrono::local_time time; // exposition + only + const std::string* abbrev; // exposition \fB(2)\fP (exposition only*) + only + const std::chrono::seconds* offset; // exposition + only + + }; + template< class Duration > + + /*local-time-format-t*/ + local_time_format( const + std::chrono::local_time& tp, \fB(3)\fP + const std::string* abbrev = nullptr, + + const std::chrono::seconds* offset_sec + = nullptr ); + template< class Duration, class CharT > \fB(4)\fP + struct formatter, CharT>; + + Specialization of std::formatter that defines formatting rules for a + std::chrono::local_time. + + 1) If %Z, %z or a modified variant of %z is used, a std::format_error is thrown. + 2-4) The local_time_format function returns a value of unspecified type that holds + the local time, offset, and time zone abbreviation. + When an object f of this unspecified type is formatted, if %Z is used, it is + replaced with *f.abbrev widened to CharT if f.abbrev is not null; otherwise a + std::format_error is thrown. If %z or a modified variant thereof is used, an offset + of *f.offset_sec will be formatted if f.offset_sec is not null; otherwise a + std::format_error is thrown. + + std::formatter is usually not directly accessed, but is used through formatting + functions. + + Format specification + + The format specification has the form + + fill-and-align (optional) width (optional) precision (optional) L(optional) + chrono-spec (optional) + + fill-and-align, width, and precision have the same meaning as in standard format + specification. precision is valid only for std::chrono::duration types where the + representation type Rep is a floating-point type, otherwise std::format_error is + thrown. + + The locale used for formatting is determined as follows: + + * the default "C" locale if L is not present in the format specification, + * otherwise, the locale denoted by the std::locale passed to the formatting + function, if any, + * otherwise (L is present but no std::locale is passed to the formatting + function), the global locale. + + The chrono-spec consists of one or more conversion specifiers and ordinary + characters (other than {, }, and %). A chrono-spec must start with a conversion + specifier. All ordinary characters are written to the output without modification. + Each unmodified conversion specifier begins with a % character followed by a + character that determines the behavior of the specifier. Some conversion specifiers + have a modified form in which an E or O modifier character is inserted after the % + character. Each conversion specifier is replaced by appropriate characters in the + output as described below. + + If the chrono-spec is empty, the chrono object is formatted as if by streaming it to + an object os of type std::basic_ostringstream with the formatting locale (one + of std::locale::classic(), the passed std::locale object, and std::locale::global()) + imbued and copying os.str() to the output buffer with additional padding and + adjustments as per format specifiers. + + The following format specifiers are available: + + Conversion Explanation + specifier + %% Writes a literal % character. + %n Writes a newline character. + %t Writes a horizontal tab character. + Year + Writes the year divided by 100 using floored division. If the result is + %C a single decimal digit, it is prefixed with 0. + %EC + The modified command %EC writes the locale's alternative representation + of the century. + Writes the last two decimal digits of the year. If the result is a + single digit it is prefixed by 0. + %y + %Oy The modified command %Oy writes the locale's alternative representation. + %Ey + The modified command %Ey writes the locale's alternative representation + of offset from %EC (year only). + Writes the year as a decimal number. If the result is less than four + %Y digits it is left-padded with 0 to four digits. + %EY + The modified command %EY writes the locale's alternative full year + representation. + Month + %b Writes the locale's abbreviated month name. + %h + %B Writes the locale's full month name. + Writes the month as a decimal number (January is 01). If the result is a + %m single digit, it is prefixed with 0. + %Om + The modified command %Om writes the locale's alternative representation. + Day + Writes the day of month as a decimal number. If the result is a single + %d decimal digit, it is prefixed with 0. + %Od + The modified command %Od writes the locale's alternative representation. + Writes the day of month as a decimal number. If the result is a single + %e decimal digit, it is prefixed with a space. + %Oe + The modified command %Oe writes the locale's alternative representation. + Day of the week + %a Writes the locale's abbreviated weekday name. + %A Writes the locale's full weekday name. + %u Writes the ISO weekday as a decimal number (1-7), where Monday is 1. + %Ou + The modified command %Ou writes the locale's alternative representation. + %w Writes the weekday as a decimal number (0-6), where Sunday is 0. + %Ow + The modified command %Ow writes the locale's alternative representation. + ISO 8601 week-based year + In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the + following requirements: + + * Includes January 4 + * Includes first Thursday of the year + %g Writes the last two decimal digits of the ISO 8601 week-based year. If + the result is a single digit it is prefixed by 0. + %G Writes the ISO 8601 week-based year as a decimal number. If the result + is less than four digits it is left-padded with 0 to four digits. + Writes the ISO 8601 week of the year as a decimal number. If the result + %V is a single digit, it is prefixed with 0. + %OV + The modified command %OV writes the locale's alternative representation. + Week/day of the year + Writes the day of the year as a decimal number (January 1 is 001). If + %j the result is less than three digits, it is left-padded with 0 to three + digits. + Writes the week number of the year as a decimal number. The first Sunday + of the year is the first day of week 01. Days of the same year prior to + %U that are in week 00. If the result is a single digit, it is prefixed + %OU with 0. + + The modified command %OU writes the locale's alternative representation. + Writes the week number of the year as a decimal number. The first Monday + of the year is the first day of week 01. Days of the same year prior to + %W that are in week 00. If the result is a single digit, it is prefixed + %OW with 0. + + The modified command %OW writes the locale's alternative representation. + Date + %D Equivalent to "%m/%d/%y". + %F Equivalent to "%Y-%m-%d". + Writes the locale's date representation. + %x + %Ex The modified command %Ex produces the locale's alternate date + representation. + Time of day + Writes the hour (24-hour clock) as a decimal number. If the result is a + %H single digit, it is prefixed with 0. + %OH + The modified command %OH writes the locale's alternative representation. + Writes the hour (12-hour clock) as a decimal number. If the result is a + %I single digit, it is prefixed with 0. + %OI + The modified command %OI writes the locale's alternative representation. + Writes the minute as a decimal number. If the result is a single digit, + %M it is prefixed with 0. + %OM + The modified command %OM writes the locale's alternative representation. + Writes the second as a decimal number. If the number of seconds is less + than 10, the result is prefixed with 0. + + If the precision of the input cannot be exactly represented with + %S seconds, then the format is a decimal floating-point number with a fixed + %OS format and a precision matching that of the precision of the input (or + to a microseconds precision if the conversion to floating-point decimal + seconds cannot be made within 18 fractional digits). The character for + the decimal point is localized according to the locale. + + The modified command %OS writes the locale's alternative representation. + %p Writes the locale's equivalent of the AM/PM designations associated with + a 12-hour clock. + %R Equivalent to "%H:%M". + %T Equivalent to "%H:%M:%S". + %r Writes the locale's 12-hour clock time. + Writes the locale's time representation. + %X + %EX The modified command %EX writes the locale's alternate time + representation. + Time zone + Writes the offset from UTC in the ISO 8601 format. For example -0430 + %z refers to 4 hours 30 minutes behind UTC. If the offset is zero, +0000 is + %Ez used. + %Oz + The modified commands %Ez and %Oz insert a : between the hours and + minutes (e.g., -04:30). + %Z Writes the time zone abbreviation. +.SH Miscellaneous + Writes the locale's date and time representation. + %c + %Ec The modified command %Ec writes the locale's alternative date and time + representation. + + The following specifiers are recognized, but will cause std::format_error to be + thrown: + + Conversion Explanation + specifier + Duration count + %Q Writes the count of ticks of the duration, i.e. the value obtained via + count(). + %q Writes the unit suffix of the duration, as specified in operator<<(). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::formatter.3 b/man/std::formatter.3 new file mode 100644 index 000000000..8a4cdd3ef --- /dev/null +++ b/man/std::formatter.3 @@ -0,0 +1,80 @@ +.TH std::formatter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::formatter \- std::formatter + +.SH Synopsis + Defined in header + template< class CharT > (since C++26) + struct formatter; + + The template specialization of std::formatter for the std::filesystem::path class + allows users to convert a pathname to its textual representation using formatting + functions. This specialization is debug-enabled. + +.SH Member functions + + set_debug_format enables to format the pathname as an escaped string + \fI(public member function)\fP + parse parses the format specifier as specified by path-format-spec + \fI(public member function)\fP + format writes the formatted output as specified by path-format-spec + \fI(public member function)\fP + +std::formatter::set_debug_format + + constexpr void set_debug_format(); + + Allows the current object to format pathname as an escaped string. + +std::formatter::parse + + constexpr auto parse( std::basic_format_parse_context& ctx ) + -> std::basic_format_parse_context::iterator; + + Parses the format specifiers as a path-format-spec and stores the parsed specifiers + in the current object. + + Returns an iterator past the end of the path-format-spec. + +std::formatter::format + + template< class FormatContext > + + auto format( const std::filesystem::path& p, FormatContext& ctx ) const + + -> FormatContext::iterator; + + Let s be p.generic() if the g option is used, + otherwise p.native(). Writes s into ctx.out() as specified by path-format-spec. + + For character transcoding of the pathname: + + * The pathname is transcoded from the native encoding for wide character strings + to UTF-8 with maximal subparts of ill-formed subsequences substituted with + U+FFFD REPLACEMENT CHARACTER if + * std::is_same_v is true, + * std::is_same_v is true, and + * ordinary literal encoding is UTF-8. + * Otherwise, no transcoding is performed if std::is_same_v is true. + * Otherwise, transcoding is implementation-defined. + + Returns an iterator past the end of the output range. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_format_path 202403L (C++26) formatting support for std::filesystem::path + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::forward.3 b/man/std::forward.3 index 04734a797..c7eeb8ecf 100644 --- a/man/std::forward.3 +++ b/man/std::forward.3 @@ -1,28 +1,39 @@ -.TH std::forward 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward \- std::forward + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - T&& forward( typename std::remove_reference::type& t ); \fI(until C++14)\fP - template< class T > - constexpr T&& forward( typename std::remove_reference::type& t \fB(1)\fP \fI(since C++14)\fP - ); - template< class T > \fB(2)\fP \fI(since C++11)\fP - T&& forward( typename std::remove_reference::type&& t ); \fI(until C++14)\fP + template< class T > \fI(since C++11)\fP + T&& forward( typename std::remove_reference::type& \fI(until C++14)\fP + t ) noexcept; template< class T > - constexpr T&& forward( typename std::remove_reference::type&& t \fB(2)\fP \fI(since C++14)\fP - ); - - When used according to the following recipe in a function template, forwards the - argument to another function exactly as it was passed to the calling function. - - For example, if used in wrapper such as the following, the template behaves as + constexpr T&& forward( std::remove_reference_t& t ) \fI(since C++14)\fP + noexcept; + template< class T > \fB(1)\fP (since + T&& forward( typename std::remove_reference::type&& C++11) + t ) noexcept; (until + \fB(2)\fP C++14) + template< class T > (since + constexpr T&& forward( std::remove_reference_t&& t C++14) + ) noexcept; + + 1) Forwards lvalues as either lvalues or as rvalues, depending on T. + + When t is a forwarding reference (a function argument that is declared as an rvalue + reference to a cv-unqualified function template parameter), this overload forwards + the argument to another function with the value category it had when passed to the + calling function. + + For example, if used in a wrapper such as the following, the template behaves as described below: - template - void wrapper(T&& arg) - { - foo(std::forward(arg)); // Forward a single argument. - } + template + void wrapper(T&& arg) + { + // arg is always lvalue + foo(std::forward(arg)); // Forward as lvalue or as rvalue, depending on T + } * If a call to wrapper() passes an rvalue std::string, then T is deduced to std::string (not std::string&, const std::string&, or std::string&&), and @@ -33,14 +44,38 @@ * If a call to wrapper() passes a non-const lvalue std::string, then T is deduced to std::string&, and std::forward ensures that a non-const lvalue reference is passed to foo. + 2) Forwards rvalues as rvalues and prohibits forwarding of rvalues as lvalues. -.SH Notes + This overload makes it possible to forward a result of an expression (such as + function call), which may be rvalue or lvalue, as the original value category of a + forwarding reference argument. + + For example, if a wrapper does not just forward its argument, but calls a member + function on the argument, and forwards its result: - Attempting to forward an rvalue as an lvalue, such as by instantiating the form 2) + // transforming wrapper + template + void wrapper(T&& arg) + { + foo(forward(arg).get())>(forward(arg).get())); + } + + where the type of arg may be + + struct Arg + { + int i = 1; + int get() && { return i; } // call to this overload is rvalue + int& get() & { return i; } // call to this overload is lvalue + }; + + Attempting to forward an rvalue as an lvalue, such as by instantiating the form \fB(2)\fP with lvalue reference type T, is a compile-time error. - See template argument deduction for the special rules behind T&& used as a function - parameter. +.SH Notes + + See template argument deduction for the special rules behind forwarding references + (T&& used as a function parameter) and forwarding references for other detail. .SH Parameters @@ -50,11 +85,9 @@ static_cast(t) -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Constant. .SH Example @@ -62,53 +95,61 @@ the constructor of class T. Also, perfect forwarding of parameter packs is demonstrated. - + // Run this code #include #include #include - #include - - struct A { - A(int&& n) { std::cout << "rvalue overload, n=" << n << "\\n"; } - A(int& n) { std::cout << "lvalue overload, n=" << n << "\\n"; } + + struct A + { + A(int&& n) { std::cout << "rvalue overload, n=" << n << '\\n'; } + A(int& n) { std::cout << "lvalue overload, n=" << n << '\\n'; } }; - - class B { + + class B + { public: template B(T1&& t1, T2&& t2, T3&& t3) : a1_{std::forward(t1)}, a2_{std::forward(t2)}, a3_{std::forward(t3)} - { - } - + {} + private: A a1_, a2_, a3_; }; - + template std::unique_ptr make_unique1(U&& u) { return std::unique_ptr(new T(std::forward(u))); } - + template - std::unique_ptr make_unique(U&&... u) + std::unique_ptr make_unique2(U&&... u) { return std::unique_ptr(new T(std::forward(u)...)); } - + + auto make_B(auto&&... args) // since C++20 + { + return B(std::forward(args)...); + } + int main() { auto p1 = make_unique1(2); // rvalue int i = 1; auto p2 = make_unique1(i); // lvalue - + std::cout << "B\\n"; - auto t = make_unique(2, i, 3); + auto t = make_unique2(2, i, 3); + + std::cout << "make_B\\n"; + [[maybe_unused]] B b = make_B(4, i, 5); } .SH Output: @@ -119,14 +160,14 @@ rvalue overload, n=2 lvalue overload, n=1 rvalue overload, n=3 - -.SH Complexity - - Constant + make_B + rvalue overload, n=4 + lvalue overload, n=1 + rvalue overload, n=5 .SH See also move obtains an rvalue reference - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP move_if_noexcept obtains an rvalue reference if the move constructor does not throw - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::forward_as_tuple.3 b/man/std::forward_as_tuple.3 index feff07f3e..0cff6b759 100644 --- a/man/std::forward_as_tuple.3 +++ b/man/std::forward_as_tuple.3 @@ -1,16 +1,16 @@ -.TH std::forward_as_tuple 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_as_tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_as_tuple \- std::forward_as_tuple + .SH Synopsis Defined in header - template< class... Types > \fI(since C++11)\fP - tuple forward_as_tuple( Types&&... args ); \fI(until C++14)\fP - template< class... Types > \fI(since C++14)\fP - constexpr tuple forward_as_tuple( Types&&... args ); + template< class... Types > \fI(since C++11)\fP + tuple forward_as_tuple( Types&&... args ) (constexpr since C++14) + noexcept; Constructs a tuple of references to the arguments in args suitable for forwarding as an argument to a function. The tuple has rvalue reference data members when rvalues - are used as arguments, and otherwise has lvalue reference data members. If rvalues - are used, the result of this function must be consumed before the next sequence - point. + are used as arguments, and otherwise has lvalue reference data members. .SH Parameters @@ -21,31 +21,30 @@ A std::tuple object created as if by std::tuple(std::forward(args)...) -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + If the arguments are temporaries, forward_as_tuple does not extend their lifetime; + they have to be used before the end of the full expression. .SH Example - + // Run this code #include #include #include #include - + int main() { std::map m; - + m.emplace(std::piecewise_construct, std::forward_as_tuple(10), std::forward_as_tuple(20, 'a')); std::cout << "m[10] = " << m[10] << '\\n'; - + // The following is an error: it produces a // std::tuple holding two dangling references. // @@ -57,10 +56,14 @@ m[10] = aaaaaaaaaaaaaaaaaaaa +.SH See also + make_tuple creates a tuple object of the type defined by the argument types - \fI(function template)\fP - creates a tuple of lvalue references or unpacks a tuple into individual - tie objects - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into individual + \fI(C++11)\fP objects + \fI(function template)\fP tuple_cat creates a tuple by concatenating any number of tuples - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + apply calls a function with a tuple of arguments + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::forward_iterator.3 b/man/std::forward_iterator.3 new file mode 100644 index 000000000..1fe5697fe --- /dev/null +++ b/man/std::forward_iterator.3 @@ -0,0 +1,63 @@ +.TH std::forward_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_iterator \- std::forward_iterator + +.SH Synopsis + Defined in header + template< class I > + + concept forward_iterator = + std::input_iterator && + std::derived_from, \fI(since C++20)\fP + std::forward_iterator_tag> && + std::incrementable && + + std::sentinel_for; + + This concept refines std::input_iterator by requiring that I also model + std::incrementable (thereby making it suitable for multi-pass algorithms), and + guaranteeing that two iterators to the same range can be compared against each + other. + +.SH Notes + + Unlike the LegacyForwardIterator requirements, the forward_iterator concept does not + require dereference to return a reference. + +.SH Example + + A minimum forward iterator. + + #include + #include + + struct SimpleForwardIterator + { + using difference_type = std::ptrdiff_t; + using value_type = int; + + int operator*() const; + + SimpleForwardIterator& operator++(); + + SimpleForwardIterator operator++(int) + { + auto tmp = *this; + ++*this; + return tmp; + } + + bool operator==(const SimpleForwardIterator&) const; + }; + + static_assert(std::forward_iterator); + +.SH See also + + specifies that a type is an input iterator, that is, its + input_iterator referenced values can be read and it can be both pre- and + (C++20) post-incremented + (concept) + bidirectional_iterator specifies that a forward_iterator is a bidirectional + (C++20) iterator, supporting movement backwards + (concept) diff --git a/man/std::forward_like.3 b/man/std::forward_like.3 new file mode 100644 index 000000000..8a631a9e8 --- /dev/null +++ b/man/std::forward_like.3 @@ -0,0 +1,199 @@ +.TH std::forward_like 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_like \- std::forward_like + +.SH Synopsis + Defined in header + template< class T, class U > (since C++23) + [[nodiscard]] constexpr auto&& forward_like( U&& x ) noexcept; + + Returns a reference to x which has similar properties to T&&. + + The return type is determined as below: + + 1. If std::remove_reference_t is a const-qualified type, then the referenced + type of the return type is const std::remove_reference_t. Otherwise, the + referenced type is std::remove_reference_t. + 2. If T&& is an lvalue reference type, then the return type is also an lvalue + reference type. Otherwise, the return type is an rvalue reference type. + + If T is not a referenceable type, the program is ill-formed. + +.SH Parameters + + x - a value needs to be forwarded like type T + +.SH Return value + + A reference to x of the type determined as above. + +.SH Notes + + Like std::forward, std::move, and std::as_const, std::forward_like is a type cast + that only influences the value category of an expression, or potentially adds + const-qualification. + + When m is an actual member and thus o.m a valid expression, this is usually spelled + as std::forward(o).m in C++20 code. + + This leads to three possible models, called merge, tuple, and language. + + * merge: merge the const qualifiers, and adopt the value category of the Owner. + * tuple: what std::get<0>(Owner) does, assuming Owner is a std::tuple. + * language: what std::forward(o).m does. + + The main scenario that std::forward_like caters to is adapting “far” objects. + Neither the tuple nor the language scenarios do the right thing for that main + use-case, so the merge model is used for std::forward_like. + + Feature-test macro Value Std Feature + __cpp_lib_forward_like 202207L (C++23) std::forward_like + +.SH Possible implementation + + template + [[nodiscard]] constexpr auto&& forward_like(U&& x) noexcept + { + constexpr bool is_adding_const = std::is_const_v>; + if constexpr (std::is_lvalue_reference_v) + { + if constexpr (is_adding_const) + return std::as_const(x); + else + return static_cast(x); + } + else + { + if constexpr (is_adding_const) + return std::move(std::as_const(x)); + else + return std::move(x); + } + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + struct TypeTeller + { + void operator()(this auto&& self) + { + using SelfType = decltype(self); + using UnrefSelfType = std::remove_reference_t; + if constexpr (std::is_lvalue_reference_v) + { + if constexpr (std::is_const_v) + std::cout << "const lvalue\\n"; + else + std::cout << "mutable lvalue\\n"; + } + else + { + if constexpr (std::is_const_v) + std::cout << "const rvalue\\n"; + else + std::cout << "mutable rvalue\\n"; + } + } + }; + + struct FarStates + { + std::unique_ptr ptr; + std::optional opt; + std::vector container; + + auto&& from_opt(this auto&& self) + { + return std::forward_like(self.opt.value()); + // It is OK to use std::forward(self).opt.value(), + // because std::optional provides suitable accessors. + } + + auto&& operator[](this auto&& self, std::size_t i) + { + return std::forward_like(self.container.at(i)); + // It is not so good to use std::forward(self)[i], because + // containers do not provide rvalue subscript access, although they could. + } + + auto&& from_ptr(this auto&& self) + { + if (!self.ptr) + throw std::bad_optional_access{}; + return std::forward_like(*self.ptr); + // It is not good to use *std::forward(self).ptr, because + // std::unique_ptr always dereferences to a non-const lvalue. + } + }; + + int main() + { + FarStates my_state + { + .ptr{std::make_unique()}, + .opt{std::in_place, TypeTeller{}}, + .container{std::vector(1)}, + }; + + my_state.from_ptr()(); + my_state.from_opt()(); + my_state[0](); + + std::cout << '\\n'; + + std::as_const(my_state).from_ptr()(); + std::as_const(my_state).from_opt()(); + std::as_const(my_state)[0](); + + std::cout << '\\n'; + + std::move(my_state).from_ptr()(); + std::move(my_state).from_opt()(); + std::move(my_state)[0](); + + std::cout << '\\n'; + + std::move(std::as_const(my_state)).from_ptr()(); + std::move(std::as_const(my_state)).from_opt()(); + std::move(std::as_const(my_state))[0](); + + std::cout << '\\n'; + } + +.SH Output: + + mutable lvalue + mutable lvalue + mutable lvalue + + const lvalue + const lvalue + const lvalue + + mutable rvalue + mutable rvalue + mutable rvalue + + const rvalue + const rvalue + const rvalue + +.SH See also + + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP + forward forwards a function argument + \fI(C++11)\fP \fI(function template)\fP + as_const obtains a reference to const to its argument + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::forward_list.3 b/man/std::forward_list.3 index 2490964eb..ac82e495a 100644 --- a/man/std::forward_list.3 +++ b/man/std::forward_list.3 @@ -1,24 +1,34 @@ -.TH std::forward_list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list \- std::forward_list + .SH Synopsis Defined in header template< - class T, \fI(since C++11)\fP + class T, \fB(1)\fP \fI(since C++11)\fP class Allocator = std::allocator > class forward_list; + namespace pmr { + + template< class T > + using forward_list = std::forward_list>; + + } std::forward_list is a container that supports fast insertion and removal of elements from anywhere in the container. Fast random access is not supported. It is - implemented as a singly-linked list and essentially does not have any overhead - compared to its implementation in C. Compared to std::list this container provides + implemented as a singly-linked list. Compared to std::list this container provides more space efficient storage when bidirectional iteration is not needed. - Addition, removal and moving the elements within the list or across several lists - does not invalidate the iterators. An iterator is invalidated only when the - corresponding element is deleted. + Adding, removing and moving the elements within the list, or across several lists, + does not invalidate the iterators currently referring to other elements in the list. + However, an iterator or reference referring to an element is invalidated when the + corresponding element is removed (via erase_after) from the list. - std::forward_list meets the requirements of Container (except for the size() member + std::forward_list meets the requirements of Container (except for the size member function and that operator=='s complexity is always linear), AllocatorAwareContainer and SequenceContainer. @@ -26,94 +36,148 @@ The type of the elements. - T - The requirements that are imposed on the elements depend on the actual - operations performed on the container. Generally, it is required that - element type meets the requirements of MoveConstructible and - MoveAssignable, but many member functions impose stricter requirements. - Allocator - An allocator that is used to acquire memory to store the elements. The - type must meet the requirements of Allocator. + The requirements that are imposed on the elements depend on the + actual operations performed on the container. Generally, it is (until + required that element type is a complete type and meets the C++17) + requirements of Erasable, but many member functions impose + stricter requirements. + The requirements that are imposed on the elements depend on the + actual operations performed on the container. Generally, it is + required that element type meets the requirements of Erasable, but + T - many member functions impose stricter requirements. This container + (but not its members) can be instantiated with an incomplete + element type if the allocator satisfies the allocator completeness (since + requirements. C++17) + + Feature-test macro Value Std Feature + Minimal + __cpp_lib_incomplete_container_elements 201505L \fI(C++17)\fP incomplete + type + support + + + An allocator that is used to acquire/release memory and to + construct/destroy the elements in that memory. The type must meet the + requirements of Allocator. + Allocator - The behavior is undefined + \fI(until C++20)\fP + The program is ill-formed + \fI(since C++20)\fP if Allocator::value_type is not the same as T. .SH Member types Member type Definition - value_type T - allocator_type Allocator - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - reference value_type& - const_reference const value_type& - pointer std::allocator_traits::pointer - const_pointer std::allocator_traits::const_pointer - iterator ForwardIterator - const_iterator Constant forward iterator + value_type T + allocator_type Allocator + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + reference value_type& + const_reference const value_type& + pointer std::allocator_traits::pointer + const_pointer std::allocator_traits::const_pointer + iterator LegacyForwardIterator to value_type + const_iterator LegacyForwardIterator to const value_type .SH Member functions - constructor constructs the forward_list - \fI(public member function)\fP - destructor destructs the forward_list - \fI(public member function)\fP - operator= assigns values to the container - \fI(public member function)\fP - assign assigns values to the container - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs the forward_list + \fI(public member function)\fP + destructor destructs the forward_list + \fI(public member function)\fP + operator= assigns values to the container + \fI(public member function)\fP + assign assigns values to the container + \fI(public member function)\fP + assign_range assigns a range of values to the container + (C++23) \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Element access - front access the first element - \fI(public member function)\fP + front access the first element + \fI(public member function)\fP .SH Iterators - before_begin returns an iterator to the element before beginning - cbefore_begin \fI(public member function)\fP - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP + before_begin returns an iterator to the element before beginning + cbefore_begin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP .SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP + empty checks whether the container is empty + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP .SH Modifiers - clear clears the contents - \fI(public member function)\fP - insert_after inserts elements after an element - \fI(public member function)\fP - emplace_after constructs elements in-place after an element - \fI(public member function)\fP - erase_after erases an element after an element - \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - emplace_front constructs elements in-place at the beginning - \fI(public member function)\fP - pop_front removes the first element - \fI(public member function)\fP - resize changes the number of elements stored - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP + insert_after inserts elements after an element + \fI(public member function)\fP + emplace_after constructs elements in-place after an element + \fI(public member function)\fP + insert_range_after inserts a range of elements after an element + (C++23) \fI(public member function)\fP + erase_after erases an element after an element + \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + pop_front removes the first element + \fI(public member function)\fP + resize changes the number of elements stored + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP .SH Operations - merge merges two sorted lists - \fI(public member function)\fP - splice_after moves elements from another forward_list - \fI(public member function)\fP - remove removes elements satisfying specific criteria - remove_if \fI(public member function)\fP - reverse reverses the order of the elements - \fI(public member function)\fP - unique removes consecutive duplicate elements - \fI(public member function)\fP - sort sorts the elements - \fI(public member function)\fP + merge merges two sorted lists + \fI(public member function)\fP + splice_after moves elements from another forward_list + \fI(public member function)\fP + remove removes elements satisfying specific criteria + remove_if \fI(public member function)\fP + reverse reverses the order of the elements + \fI(public member function)\fP + unique removes consecutive duplicate elements + \fI(public member function)\fP + sort sorts the elements + \fI(public member function)\fP .SH Non-member functions operator== - operator!= lexicographically compares the values in the - operator< forward_list - operator<= \fI(function template)\fP + operator!= + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two + operator<=> forward_lists + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP(removed in C++20) + (C++20) std::swap(std::forward_list) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + erase(std::forward_list) erases all elements satisfying specific criteria + erase_if(std::forward_list) \fI(function template)\fP + (C++20) + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::forward_list::assign.3 b/man/std::forward_list::assign.3 index b04c479d4..50f027484 100644 --- a/man/std::forward_list::assign.3 +++ b/man/std::forward_list::assign.3 @@ -1,4 +1,7 @@ -.TH std::forward_list::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::assign \- std::forward_list::assign + .SH Synopsis void assign( size_type count, const T& value ); \fB(1)\fP \fI(since C++11)\fP template< class InputIt > \fB(2)\fP \fI(since C++11)\fP @@ -7,59 +10,74 @@ Replaces the contents of the container. - 1) Replaces the contents with count copies of value value - 2) Replaces the contents with copies of those in the range [first, last) + 1) Replaces the contents with count copies of value value. + 2) Replaces the contents with copies of those in the range [first, last). The + behavior is undefined if either argument is an iterator into *this. + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + 3) Replaces the contents with the elements from the initializer list ilist. + All iterators, pointers and references to the elements of the container are + invalidated. + .SH Parameters count - the new size of the container value - the value to initialize elements of the container with first, last - the range to copy the elements from ilist - initializer list to copy the values from -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. .SH Complexity - 1) Linear in count - 2) Linear in distance between first and last - 3) Linear in ilist.size() + 1) Linear in count. + 2) Linear in distance between first and last. + 3) Linear in ilist.size(). .SH Example The following code uses assign to add several characters to a std::forward_list: - + // Run this code #include #include - + #include + int main() { std::forward_list characters; - + + auto print_forward_list = [&]() + { + for (char c : characters) + std::cout << c << ' '; + std::cout << '\\n'; + }; + characters.assign(5, 'a'); - - for (char c : characters) { - std::cout << c << '\\n'; - } - - return 0; + print_forward_list(); + + const std::string extra(6, 'b'); + characters.assign(extra.begin(), extra.end()); + print_forward_list(); + + characters.assign({'C', '+', '+', '1', '1'}); + print_forward_list(); } .SH Output: - a - a - a - a - a + a a a a a + b b b b b b + C + + 1 1 .SH See also constructor constructs the forward_list - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::forward_list::assign_range.3 b/man/std::forward_list::assign_range.3 new file mode 100644 index 000000000..7749ea74a --- /dev/null +++ b/man/std::forward_list::assign_range.3 @@ -0,0 +1,67 @@ +.TH std::forward_list::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::assign_range \- std::forward_list::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void assign_range( R&& rg ); + + Replaces elements in the container with a copy of each element in rg. + + Invalidates all iterators, pointers and references to the elements. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + rg - an input_range with reference type convertible to the element type + of the container +.SH Type requirements + - + std::assignable_from> must be modeled. Otherwise, + the program is ill-formed. + - + T must be EmplaceConstructible into the container from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto source = std::list{2, 7, 1}; + auto destination = std::forward_list{3, 1, 4}; + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.cbegin(), source.cend()); + #endif + assert(std::ranges::equal(source, destination)); + } + +.SH See also + + insert_range_after inserts a range of elements after an element + (C++23) \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + assign assigns values to the container + \fI(public member function)\fP diff --git a/man/std::forward_list::before_begin,cbefore_begin.3 b/man/std::forward_list::before_begin,cbefore_begin.3 index f09e9058c..4528d1656 100644 --- a/man/std::forward_list::before_begin,cbefore_begin.3 +++ b/man/std::forward_list::before_begin,cbefore_begin.3 @@ -1,8 +1,11 @@ -.TH std::forward_list::before_begin,cbefore_begin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::before_begin,cbefore_begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::before_begin,cbefore_begin \- std::forward_list::before_begin,cbefore_begin + .SH Synopsis - iterator before_begin(); \fI(since C++11)\fP - const_iterator before_begin() const; \fI(since C++11)\fP - const_iterator cbefore_begin() const; \fI(since C++11)\fP + iterator before_begin() noexcept; \fI(since C++11)\fP + const_iterator before_begin() const noexcept; \fI(since C++11)\fP + const_iterator cbefore_begin() const noexcept; \fI(since C++11)\fP Returns an iterator to the element before the first element of the container. This element acts as a placeholder, attempting to access it results in undefined @@ -19,19 +22,21 @@ Iterator to the element before the first element. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. +.SH Example + + This section is incomplete + Reason: no example + .SH See also begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::forward_list::begin,std::forward_list::cbegin.3 b/man/std::forward_list::begin,std::forward_list::cbegin.3 index efc911652..785bbe149 100644 --- a/man/std::forward_list::begin,std::forward_list::cbegin.3 +++ b/man/std::forward_list::begin,std::forward_list::cbegin.3 @@ -1,12 +1,15 @@ -.TH std::forward_list::begin,std::forward_list::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::begin,std::forward_list::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::begin,std::forward_list::cbegin \- std::forward_list::begin,std::forward_list::cbegin + .SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator begin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the forward_list. - If the container is empty, the returned iterator will be equal to end(). + If the forward_list is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,19 +19,57 @@ .SH Return value - Iterator to the first element + Iterator to the first element. -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Constant. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::forward_list nums{1, 2, 4, 8, 16}; + std::forward_list fruits{"orange", "apple", "raspberry"}; + std::forward_list empty; + + // Print forward_list. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the forward_list nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the forward_list fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "forward_list 'empty' is indeed empty.\\n"; + } + +.SH Output: - Constant + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + forward_list 'empty' is indeed empty. .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::forward_list::clear.3 b/man/std::forward_list::clear.3 index 0b5de2214..6be5f793c 100644 --- a/man/std::forward_list::clear.3 +++ b/man/std::forward_list::clear.3 @@ -1,11 +1,14 @@ -.TH std::forward_list::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::clear \- std::forward_list::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP - Removes all elements from the container. + Erases all elements from the container. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterator remains valid. .SH Parameters @@ -15,21 +18,50 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::forward_list& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + } + + int main() + { + std::forward_list container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + After clear: { } + + Defect reports - Linear in the size of the container. + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - clear is defined in terms of erase, which has linear complexity. \fI(until C++11)\fP - complexity of clear is omitted \fI(since C++11)\fP - clear has linear complexity for sequence containers. \fI(since C++14)\fP + DR Applied to Behavior as published Correct behavior + LWG 2231 C++11 complexity guarantee was mistakenly complexity reaffirmed as + omitted in C++11 linear .SH See also erase_after erases an element after an element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::forward_list::emplace_after.3 b/man/std::forward_list::emplace_after.3 index 33faa7323..9422b2681 100644 --- a/man/std::forward_list::emplace_after.3 +++ b/man/std::forward_list::emplace_after.3 @@ -1,4 +1,7 @@ -.TH std::forward_list::emplace_after 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::emplace_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::emplace_after \- std::forward_list::emplace_after + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace_after( const_iterator pos, Args&&... args ); @@ -17,17 +20,74 @@ .SH Return value - iterator to the new element. + Iterator to the new element. .SH Complexity - This section is incomplete + Constant. -.SH See also +.SH Exceptions - insert_after inserts elements after an element - \fI(public member function)\fP + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + The example demonstrates a canonical filling of a single-linked list in natural (as + opposed to reverse) order. + + +// Run this code + + #include + #include + #include + + struct Sum + { + std::string remark; + int sum; + + Sum(std::string remark, int sum) + : remark{std::move(remark)}, sum{sum} {} -.SH Category: + void print() const + { + std::cout << remark << " = " << sum << '\\n'; + } + }; - * Todo without reason + int main() + { + std::forward_list list; + + auto iter = list.before_begin(); + std::string str{"1"}; + + for (int i{1}, sum{1}; i != 10; sum += i) + { + iter = list.emplace_after(iter, str, sum); + ++i; + str += " + " + std::to_string(i); + } + + for (const Sum& s : list) + s.print(); + } + +.SH Output: + + 1 = 1 + 1 + 2 = 3 + 1 + 2 + 3 = 6 + 1 + 2 + 3 + 4 = 10 + 1 + 2 + 3 + 4 + 5 = 15 + 1 + 2 + 3 + 4 + 5 + 6 = 21 + 1 + 2 + 3 + 4 + 5 + 6 + 7 = 28 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 = 36 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 = 45 + +.SH See also + + insert_after inserts elements after an element + \fI(public member function)\fP diff --git a/man/std::forward_list::emplace_front.3 b/man/std::forward_list::emplace_front.3 index e2271b94f..5b93d66b2 100644 --- a/man/std::forward_list::emplace_front.3 +++ b/man/std::forward_list::emplace_front.3 @@ -1,27 +1,42 @@ -.TH std::forward_list::emplace_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::emplace_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::emplace_front \- std::forward_list::emplace_front + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace_front( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace_front( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + reference emplace_front( Args&&... args ); Inserts a new element to the beginning of the container. The element is constructed - in-place, i.e. no copy or move operations are performed. The constructor of the - element is called with exactly the same arguments, as supplied to the function. + through std::allocator_traits::construct, which typically uses placement-new to + construct the element in-place at the location provided by the container. The + arguments args... are forwarded to the constructor as std::forward(args).... No iterators or references are invalidated. .SH Parameters - args - arguments to forward to the constructor of the element + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of EmplaceConstructible. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + A reference to the inserted element. \fI(since C++17)\fP .SH Complexity Constant. +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + .SH See also - push_front inserts elements to the beginning - \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP diff --git a/man/std::forward_list::empty.3 b/man/std::forward_list::empty.3 index 8a9166578..f1b3cbbb2 100644 --- a/man/std::forward_list::empty.3 +++ b/man/std::forward_list::empty.3 @@ -1,6 +1,11 @@ -.TH std::forward_list::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::empty \- std::forward_list::empty + .SH Synopsis - bool empty() const; \fI(since C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,13 +15,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the container is empty, false otherwise. .SH Complexity @@ -24,22 +23,23 @@ .SH Example - + The following code uses empty to check if a std::forward_list contains any elements: - + // Run this code #include #include - + int main() { std::forward_list numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.push_front(42); numbers.push_front(13317); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -47,5 +47,10 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false + +.SH See also + + distance returns the distance between two iterators + \fI(function template)\fP diff --git a/man/std::forward_list::end,std::forward_list::cend.3 b/man/std::forward_list::end,std::forward_list::cend.3 index ec08c5a7a..4e35478d3 100644 --- a/man/std::forward_list::end,std::forward_list::cend.3 +++ b/man/std::forward_list::end,std::forward_list::cend.3 @@ -1,10 +1,13 @@ -.TH std::forward_list::end,std::forward_list::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::end,std::forward_list::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::end,std::forward_list::cend \- std::forward_list::end,std::forward_list::cend + .SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP + iterator end() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator end() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the forward_list. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,17 +22,55 @@ Iterator to the element following the last element. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::forward_list nums{1, 2, 4, 8, 16}; + std::forward_list fruits{"orange", "apple", "raspberry"}; + std::forward_list empty; + + // Print forward_list. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the forward_list nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the forward_list fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "forward_list 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + forward_list 'empty' is indeed empty. + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::forward_list::erase_after.3 b/man/std::forward_list::erase_after.3 index fac78740f..169fd7e9a 100644 --- a/man/std::forward_list::erase_after.3 +++ b/man/std::forward_list::erase_after.3 @@ -1,12 +1,15 @@ -.TH std::forward_list::erase_after 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::erase_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::erase_after \- std::forward_list::erase_after + .SH Synopsis - iterator erase_after( const_iterator position ); \fB(1)\fP \fI(since C++11)\fP + iterator erase_after( const_iterator pos ); \fB(1)\fP \fI(since C++11)\fP iterator erase_after( const_iterator first, const_iterator last ); \fB(2)\fP \fI(since C++11)\fP Removes specified elements from the container. 1) Removes the element following pos. - 2) Removes the elements in the range (first; last). + 2) Removes the elements following first until last. .SH Parameters @@ -26,29 +29,32 @@ .SH Example - + // Run this code #include - #include #include + #include + int main() { - std::forward_list l = { 1, 2, 3, 4, 5, 6, 7, 8, 9 }; - - // l.erase( l.begin() ); // ERROR: No function erase - - l.erase_after( l.before_begin() ); // Removes first element - - for( auto n : l ) std::cout << n << " "; + std::forward_list l = {1, 2, 3, 4, 5, 6, 7, 8, 9}; + + // l.erase(l.begin()); // Error: no function erase() + + l.erase_after(l.before_begin()); // Removes first element + + for (auto n : l) + std::cout << n << ' '; std::cout << '\\n'; - - auto fi= std::next( l.begin() ); - auto la= std::next( fi, 3 ); - - l.erase_after( fi, la ); - - for( auto n : l ) std::cout << n << " "; + + auto fi = std::next(l.begin()); + auto la = std::next(fi, 3); + + l.erase_after(fi, la); + + for (auto n : l) + std::cout << n << ' '; std::cout << '\\n'; } @@ -60,4 +66,4 @@ .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::forward_list::forward_list.3 b/man/std::forward_list::forward_list.3 index 6c3dab755..a2335a0f4 100644 --- a/man/std::forward_list::forward_list.3 +++ b/man/std::forward_list::forward_list.3 @@ -1,124 +1,184 @@ -.TH std::forward_list::forward_list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::forward_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::forward_list \- std::forward_list::forward_list + .SH Synopsis - explicit forward_list( const Allocator& alloc = \fI(since C++11)\fP - Allocator() ); \fI(until C++14)\fP - forward_list : forward_list( Allocator() ) {} \fI(since C++14)\fP - explicit forward_list( const Allocator& alloc ); + forward_list(); \fB(1)\fP \fI(since C++11)\fP + explicit forward_list( const Allocator& alloc ); \fB(2)\fP \fI(since C++11)\fP forward_list( size_type count, - const T& value, \fB(2)\fP \fI(since C++11)\fP + const T& value, \fB(3)\fP \fI(since C++11)\fP - const Allocator& alloc = - Allocator()); + const Allocator& alloc = Allocator() + ); explicit forward_list( size_type count ); \fI(since C++11)\fP \fI(until C++14)\fP - explicit forward_list( size_type count, const \fI(since C++14)\fP - Allocator& alloc = Allocator() ); - template< class InputIt > \fB(1)\fP + explicit forward_list( size_type count, + const Allocator& alloc = \fI(since C++14)\fP + Allocator() ); + template< class InputIt > - forward_list( InputIt first, InputIt last, \fB(4)\fP \fI(since C++11)\fP + forward_list( InputIt first, InputIt last, \fB(5)\fP \fI(since C++11)\fP - const Allocator& alloc = - Allocator() ); \fB(3)\fP - forward_list( const forward_list& other ); \fB(5)\fP \fI(since C++11)\fP - forward_list( const forward_list& other, const \fB(5)\fP \fI(since C++11)\fP - Allocator& alloc ); - forward_list( forward_list&& other ) \fB(6)\fP \fI(since C++11)\fP - forward_list( forward_list&& other, const \fB(6)\fP \fI(since C++11)\fP + const Allocator& alloc = Allocator() + ); + forward_list( const forward_list& other ); \fB(6)\fP \fI(since C++11)\fP + forward_list( const forward_list& other, const \fB(4)\fP \fB(7)\fP \fI(since C++11)\fP Allocator& alloc ); + forward_list( forward_list&& other ); \fB(8)\fP \fI(since C++11)\fP + forward_list( forward_list&& other, const Allocator& \fB(9)\fP \fI(since C++11)\fP + alloc ); forward_list( std::initializer_list init, - const Allocator& alloc = \fB(7)\fP \fI(since C++11)\fP - Allocator() ); + const Allocator& alloc = Allocator() \fB(10)\fP \fI(since C++11)\fP + ); + template< container-compatible-range R > - Constructs new container from a variety of data sources and optionally using user + forward_list( std::from_range_t, R&& rg, \fB(11)\fP (since C++23) + + const Allocator& alloc = Allocator() + ); + + Constructs a new container from a variety of data sources, optionally using a user supplied allocator alloc. - 1) Default constructor. Constructs empty container. - 2) Constructs the container with count copies of elements with value value. - 3) Constructs the container with count value-initialized (default constructed, for - classes) instances of T. No copies are made. - 4) Constructs the container with the contents of the range [first, last). - 5) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_container_copy_construction(other). - 6) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 7) Constructs the container with the contents of the initializer list init. + 1) Default constructor. Constructs an empty container with a default-constructed + allocator. + 2) Constructs an empty container with the given allocator alloc. + 3) Constructs the container with count copies of elements with value value. + 4) Constructs the container with count default-inserted instances of T. No copies + are made. + 5) Constructs the container with the contents of the range [first, last). This + overload participates in overload resolution only if InputIt satisfies + LegacyInputIterator, to avoid ambiguity with the overload \fB(3)\fP. + 6) Copy constructor. Constructs the container with the copy of the contents of + other. + The allocator is obtained as if by calling + std::allocator_traits::select_on_container_copy_construction( + other.get_allocator()). + 7) Constructs the container with the copy of the contents of other, using alloc as + the allocator. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 8) Move constructor. Constructs the container with the contents of other using move + semantics. Allocator is obtained by move-construction from the allocator belonging + to other. + 9) Allocator-extended move constructor. Using alloc as the allocator for the new + container, moving the contents from other; if alloc != other.get_allocator(), this + results in an element-wise move. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 10) Constructs the container with the contents of the initializer list init. + 11) Constructs the container with the contents of the range rg. .SH Parameters alloc - allocator to use for all memory allocations of this container count - the size of the container value - the value to initialize elements of the container with - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with -.SH Type requirements - - - Allocator must meet the requirements of Allocator. - - - InputIt must meet the requirements of InputIterator. + rg - a container compatible range, that is, an input_range whose elements + are convertible to T .SH Complexity - 1) Constant - 2-3) Linear in count - 4) Linear in distance between first and last - 5) Linear in size of other - 6) Constant. If alloc is given and alloc != other.get_allocator(), then linear. - 7) Linear in size of init + 1,2) Constant. + 3,4) Linear in count. + 5) Linear in distance between first and last. + 6,7) Linear in size of other. + 8) Constant. + 9) Linear if alloc != other.get_allocator(), otherwise constant. + 10) Linear in size of init. + 11) Linear in ranges::distance(rg). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload \fB(8)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(11)\fP .SH Example - + // Run this code - #include - #include #include - + #include + #include + template - std::ostream& operator<<(std::ostream& s, const std::forward_list& v) { - s.put('['); - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& e : v) { - s << comma << e; - comma[0] = ','; - } - return s << ']'; + std::ostream& operator<<(std::ostream& s, const std::forward_list& v) + { + s.put('{'); + for (char comma[]{'\\0', ' ', '\\0'}; const auto& e : v) + s << comma << e, comma[0] = ','; + return s << "}\\n"; } - + int main() { - // c++11 initializer list syntax: - std::forward_list words1 {"the", "frogurt", "is", "also", "cursed"}; - std::cout << "words1: " << words1 << '\\n'; - + // C++11 initializer list syntax: + std::forward_list words1{"the", "frogurt", "is", "also", "cursed"}; + std::cout << "1: " << words1; + // words2 == words1 std::forward_list words2(words1.begin(), words1.end()); - std::cout << "words2: " << words2 << '\\n'; - + std::cout << "2: " << words2; + // words3 == words1 std::forward_list words3(words1); - std::cout << "words3: " << words3 << '\\n'; - + std::cout << "3: " << words3; + // words4 is {"Mo", "Mo", "Mo", "Mo", "Mo"} std::forward_list words4(5, "Mo"); - std::cout << "words4: " << words4 << '\\n'; + std::cout << "4: " << words4; + + auto const rg = {"cat", "cow", "crow"}; + #ifdef __cpp_lib_containers_ranges + std::forward_list words5(std::from_range, rg); // overload (11) + #else + std::forward_list words5(rg.begin(), rg.end()); // overload (5) + #endif + std::cout << "5: " << words5; } .SH Output: - words1: [the, frogurt, is, also, cursed] - words2: [the, frogurt, is, also, cursed] - words3: [the, frogurt, is, also, cursed] - words4: [Mo, Mo, Mo, Mo, Mo] + 1: {the, frogurt, is, also, cursed} + 2: {the, frogurt, is, also, cursed} + 3: {the, frogurt, is, also, cursed} + 4: {Mo, Mo, Mo, Mo, Mo} + 5: {cat, cow, crow} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2193 C++11 the default constructor is explicit made non-explicit .SH See also assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::forward_list::front.3 b/man/std::forward_list::front.3 index 87bab63ab..6ccea5495 100644 --- a/man/std::forward_list::front.3 +++ b/man/std::forward_list::front.3 @@ -1,11 +1,14 @@ -.TH std::forward_list::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::front \- std::forward_list::front + .SH Synopsis - reference front(); \fI(since C++11)\fP - const_reference front() const; \fI(since C++11)\fP + reference front(); \fB(1)\fP \fI(since C++11)\fP + const_reference front() const; \fB(2)\fP \fI(since C++11)\fP Returns a reference to the first element in the container. - Calling front on an empty container is undefined. + Calling front on an empty container causes undefined behavior. .SH Parameters @@ -13,11 +16,11 @@ .SH Return value - reference to the first element + Reference to the first element. .SH Complexity - Constant + Constant. .SH Notes @@ -28,21 +31,27 @@ The following code uses front to display the first element of a std::forward_list: - + // Run this code #include #include - + int main() { - std::forward_list letters {'o', 'm', 'g', 'w', 't', 'f'}; - - if (!letters.empty()) { - std::cout << "The first character is: " << letters.front() << '\\n'; - } + std::forward_list letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The first character is '" << letters.front() << "'.\\n"; } .SH Output: - The first character is o + The first character is 'a'. + +.SH See also + + push_front inserts an element to the beginning + \fI(public member function)\fP + pop_front removes the first element + \fI(public member function)\fP diff --git a/man/std::forward_list::get_allocator.3 b/man/std::forward_list::get_allocator.3 index abd392de0..6e4b4ba9b 100644 --- a/man/std::forward_list::get_allocator.3 +++ b/man/std::forward_list::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::forward_list::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::get_allocator \- std::forward_list::get_allocator + .SH Synopsis - allocator_type get_allocator() const; \fI(since C++11)\fP + allocator_type get_allocator() const noexcept; \fI(since C++11)\fP Returns the allocator associated with the container. diff --git a/man/std::forward_list::insert_after.3 b/man/std::forward_list::insert_after.3 index 355fb0339..39746f168 100644 --- a/man/std::forward_list::insert_after.3 +++ b/man/std::forward_list::insert_after.3 @@ -1,4 +1,7 @@ -.TH std::forward_list::insert_after 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::insert_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::insert_after \- std::forward_list::insert_after + .SH Synopsis iterator insert_after( const_iterator pos, const T& value ); \fB(1)\fP \fI(since C++11)\fP iterator insert_after( const_iterator pos, T&& value ); \fB(2)\fP \fI(since C++11)\fP @@ -12,38 +15,102 @@ Inserts elements after the specified position in the container. - 1-2) inserts value after the element pointed to by pos - 3) inserts count copies of the value after the element pointed to by pos - 4) inserts elements from range [first, last) after the element pointed to by pos - 5) inserts elements from initializer list ilist. + 1,2) Inserts value after the element pointed to by pos. + 3) Inserts count copies of the value after the element pointed to by pos. + 4) Inserts elements from range [first, last) after the element pointed to by pos. + The behavior is undefined if first and last are iterators into *this. + 5) Inserts elements from initializer list ilist. - Information on iterator invalidation is copied from here + No iterators or references are invalidated. .SH Parameters - pos - element after which the content will be inserted + pos - iterator after which the content will be inserted value - element value to insert + count - number of copies to insert first, last - the range of elements to insert ilist - initializer list to insert the values from .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - Iterator to the inserted element. + 1,2) Iterator to the inserted element. + 3) Iterator to the last element inserted, or pos if count == 0. + 4) Iterator to the last element inserted, or pos if first == last. + 5) Iterator to the last element inserted, or pos if ilist is empty. + +.SH Exceptions + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). .SH Complexity - This section is incomplete + 1,2) Constant. + 3) Linear in count. + 4) Linear in std::distance(first, last). + 5) Linear in ilist.size(). -.SH See also +.SH Example - emplace_after constructs elements in-place after an element - \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP -.SH Category: +// Run this code + + #include + #include + #include + #include + + void print(const std::forward_list& list) + { + std::cout << "list: {"; + for (char comma[3] = {'\\0', ' ', '\\0'}; int i : list) + { + std::cout << comma << i; + comma[0] = ','; + } + std::cout << "}\\n"; + } + + int main() + { + std::forward_list ints{1, 2, 3, 4, 5}; + print(ints); + + // insert_after (2) + auto beginIt = ints.begin(); + ints.insert_after(beginIt, -6); + print(ints); - * Todo without reason + // insert_after (3) + auto anotherIt = beginIt; + ++anotherIt; + anotherIt = ints.insert_after(anotherIt, 2, -7); + print(ints); + + // insert_after (4) + const std::vector v = {-8, -9, -10}; + anotherIt = ints.insert_after(anotherIt, v.cbegin(), v.cend()); + print(ints); + + // insert_after (5) + ints.insert_after(anotherIt, {-11, -12, -13, -14}); + print(ints); + } + +.SH Output: + + list: {1, 2, 3, 4, 5} + list: {1, -6, 2, 3, 4, 5} + list: {1, -6, -7, -7, 2, 3, 4, 5} + list: {1, -6, -7, -7, -8, -9, -10, 2, 3, 4, 5} + list: {1, -6, -7, -7, -8, -9, -10, -11, -12, -13, -14, 2, 3, 4, 5} + +.SH See also + + emplace_after constructs elements in-place after an element + \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP diff --git a/man/std::forward_list::insert_range_after.3 b/man/std::forward_list::insert_range_after.3 new file mode 100644 index 000000000..13b0a3f3b --- /dev/null +++ b/man/std::forward_list::insert_range_after.3 @@ -0,0 +1,77 @@ +.TH std::forward_list::insert_range_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::insert_range_after \- std::forward_list::insert_range_after + +.SH Synopsis + template< container-compatible-range R > (since C++23) + iterator insert_range_after( const_iterator pos, R&& rg ); + + Inserts, in non-reversing order, the copies of elements in rg before pos. Each + iterator in the range rg is dereferenced exactly once. + + pos must be any dereferenceable iterator in the range [begin(), end()) or the + before_begin() iterator (thus, end() is not a valid argument for pos). + + No iterators or references become invalidated. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + pos - an iterator after which the content will be inserted + rg - a container compatible range, that is, an input_range whose + elements are convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into forward_list from *ranges::begin(rg). Otherwise, + the behavior is undefined. + +.SH Return value + + An iterator that points at the copy of the last element inserted into forward_list + or at pos if rg is empty. + +.SH Complexity + + Linear in size of rg. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto container = std::forward_list{1, 2, 3, 4}; + auto pos = std::next(container.cbegin()); + assert(*pos == 2); + const auto rg = std::vector{-1, -2, -3}; + + #ifdef __cpp_lib_containers_ranges + container.insert_range_after(pos, rg); + #else + container.insert_after(pos, rg.cbegin(), rg.cend()); + #endif + + assert(std::ranges::equal(container, std::vector{1, 2, -1, -2, -3, 3, 4})); + } + +.SH See also + + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + insert_after inserts elements after an element + \fI(public member function)\fP + emplace_after constructs elements in-place after an element + \fI(public member function)\fP diff --git a/man/std::forward_list::max_size.3 b/man/std::forward_list::max_size.3 index 64aefb11b..baa27c9dd 100644 --- a/man/std::forward_list::max_size.3 +++ b/man/std::forward_list::max_size.3 @@ -1,6 +1,9 @@ -.TH std::forward_list::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::max_size \- std::forward_list::max_size + .SH Synopsis - size_type max_size() const; \fI(since C++11)\fP + size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,19 +17,40 @@ Maximum number of elements. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::forward_list p; + std::forward_list q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + q.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF diff --git a/man/std::forward_list::merge.3 b/man/std::forward_list::merge.3 index 6d34c23c1..48594ad58 100644 --- a/man/std::forward_list::merge.3 +++ b/man/std::forward_list::merge.3 @@ -1,87 +1,132 @@ -.TH std::forward_list::merge 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::merge \- std::forward_list::merge + .SH Synopsis void merge( forward_list& other ); \fB(1)\fP \fI(since C++11)\fP - void merge( forward_list&& other ); \fB(1)\fP \fI(since C++11)\fP - template \fB(2)\fP \fI(since C++11)\fP + void merge( forward_list&& other ); \fB(2)\fP \fI(since C++11)\fP + template< class Compare > \fB(3)\fP \fI(since C++11)\fP void merge( forward_list& other, Compare comp ); - template \fB(2)\fP \fI(since C++11)\fP + template< class Compare > \fB(4)\fP \fI(since C++11)\fP void merge( forward_list&& other, Compare comp ); - Merges two sorted lists into one. The lists should be sorted into ascending order. + The function does nothing if other refers to the same object as *this. + + Otherwise, merges other into *this. Both lists should be sorted. No elements are + copied, and the container other becomes empty after the merge. This operation is + stable: for equivalent elements in the two lists, the elements from *this always + precede the elements from other, and the order of equivalent elements of *this and + other does not change. + + No iterators or references become invalidated. The pointers and references to the + elements moved from *this, as well as the iterators referring to these elements, + will refer to the same elements of *this, instead of other. - No elements are copied. The container other becomes empty after the operation. The - function does nothing if this == &other. If get_allocator() != - other.get_allocator(), the behavior is undefined. No iterators or references become - invalidated, except that the iterators of moved elements now refer into *this, not - into other. The first version uses operator< to compare the elements, the second - version uses the given comparison function comp. + 1,2) Elements are compared using operator<. + 3,4) Elements are compared using comp. - This operation is stable: for equivalent elements in the two lists, the elements - from *this shall always precede the elements from other, and the order of equivalent - elements of *this and other does not change. + If *this or other is not sorted with respected to the corresponding comparator, or + get_allocator() != other.get_allocator(), the behavior is undefined. .SH Parameters other - another container to merge comparison function object (i.e. an object that satisfies the requirements - of Compare) which returns true if the first argument is less (i.e. is - ordered before) the second element. + of Compare) which returns true if the first argument is less than (i.e. is + ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must - not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type - forward_list::const_iterator can be dereferenced and then - implicitly converted to both of them. + forward_list::const_iterator can be dereferenced and then + implicitly converted to both of them. +.SH Type requirements + - + Compare must meet the requirements of Compare. .SH Return value \fI(none)\fP +.SH Exceptions + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). Except if the exception comes from a comparison. + +.SH Complexity + + If other refers to the same object as *this, no comparisons are performed. + + Otherwise, given \\(\\scriptsize N\\)N as std::distance(begin(), end()) and + \\(\\scriptsize R\\)R as std::distance(other.begin(), other.end()): + + 1,2) At most \\(\\scriptsize N+R-1\\)N+R-1 comparisons using operator<. + 3,4) At most \\(\\scriptsize N+R-1\\)N+R-1 applications of the comparison function + comp. + .SH Example - + // Run this code #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::forward_list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (const int i : list) + ostr << ' ' << i; return ostr; } - + int main() { - std::forward_list list1 = { 5,9,0,1,3 }; - std::forward_list list2 = { 8,7,2,6,4 }; - + std::forward_list list1 = {5, 9, 1, 3, 3}; + std::forward_list list2 = {8, 7, 2, 3, 4, 4}; + list1.sort(); list2.sort(); - std::cout << "list1: " << list1 << "\\n"; - std::cout << "list2: " << list2 << "\\n"; + std::cout << "list1: " << list1 << '\\n'; + std::cout << "list2: " << list2 << '\\n'; + list1.merge(list2); - std::cout << "merged: " << list1 << "\\n"; + std::cout << "merged:" << list1 << '\\n'; } .SH Output: - list1: 0 1 3 5 9 - list2: 2 4 6 7 8 - merged: 0 1 2 3 4 5 6 7 8 9 + list1: 1 3 3 5 9 + list2: 2 3 4 4 7 8 + merged: 1 2 3 3 3 4 4 5 7 8 9 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - at most size() + other.size() - 1 comparisons. + DR Applied to Behavior as published Correct behavior + O(1) node moving could not be guaranteed the behavior is + LWG 2045 C++11 if undefined in this case + get_allocator() != other.get_allocator() .SH See also - splice_after moves elements from another forward_list - \fI(public member function)\fP + splice_after moves elements from another forward_list + \fI(public member function)\fP + merge merges two sorted ranges + \fI(function template)\fP + inplace_merge merges two ordered ranges in-place + \fI(function template)\fP + ranges::merge merges two sorted ranges + (C++20) (niebloid) + ranges::inplace_merge merges two ordered ranges in-place + (C++20) (niebloid) diff --git a/man/std::forward_list::operator=.3 b/man/std::forward_list::operator=.3 index 650921d51..682a76c44 100644 --- a/man/std::forward_list::operator=.3 +++ b/man/std::forward_list::operator=.3 @@ -1,27 +1,40 @@ -.TH std::forward_list::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::operator= \- std::forward_list::operator= + .SH Synopsis - forward_list& operator=( const forward_list& other ); \fB(1)\fP \fI(since C++11)\fP - forward_list& operator=( forward_list&& other ); \fB(2)\fP \fI(since C++11)\fP - forward_list& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + forward_list& operator=( const forward_list& other \fB(1)\fP \fI(since C++11)\fP + ); + forward_list& operator=( forward_list&& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + forward_list& operator=( forward_list&& other ) \fB(2)\fP \fI(since C++17)\fP + noexcept(/* see below */); + forward_list& operator=( \fB(3)\fP \fI(since C++11)\fP + std::initializer_list ilist ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + If + std::allocator_traits::propagate_on_container_copy_assignment::value + is true, the allocator of *this is replaced by a copy of other. If the allocator of + *this after assignment would compare unequal to its old value, the old allocator is + used to deallocate the memory, then the new allocator is used to allocate it before + copying the elements. Otherwise, the memory owned by *this may be reused when + possible. In any case, the elements originally belonging to *this may be either + destroyed or replaced by element-wise copy-assignment. 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,68 +48,97 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) \fI(since C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::forward_list to another: - The following code uses to assign one std::forward_list to another: - // Run this code - #include + #include #include - - void display_sizes(const std::forward_list &nums1, - const std::forward_list &nums2, - const std::forward_list &nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << std::distance(nums1.begin(), nums1.end()) - << " nums2: " << std::distance(nums2.begin(), nums2.end()) - << " nums3: " << std::distance(nums3.begin(), nums3.end()) << '\\n'; + auto size = std::ranges::distance(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::forward_list nums1 {3, 1, 4, 6, 5, 9}; - std::forward_list nums2; - std::forward_list nums3; - + std::forward_list x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 1, 2, 3 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 1, 2, 3 } + y = { 1, 2, 3 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 1, 2, 3 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 4, 5, 6, 7 } .SH See also constructor constructs the forward_list - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::forward_list::pop_front.3 b/man/std::forward_list::pop_front.3 index 69a894623..83e4159b6 100644 --- a/man/std::forward_list::pop_front.3 +++ b/man/std::forward_list::pop_front.3 @@ -1,8 +1,12 @@ -.TH std::forward_list::pop_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::pop_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::pop_front \- std::forward_list::pop_front + .SH Synopsis void pop_front(); \fI(since C++11)\fP - Removes the first element of the container. + Removes the first element of the container. If there are no elements in the + container, the behavior is undefined. References and iterators to the erased element are invalidated. @@ -18,7 +22,36 @@ Constant. +.SH Exceptions + + Does not throw. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::forward_list chars{'A', 'B', 'C', 'D'}; + + for (; !chars.empty(); chars.pop_front()) + std::cout << "chars.front(): '" << chars.front() << "'\\n"; + } + +.SH Output: + + chars.front(): 'A' + chars.front(): 'B' + chars.front(): 'C' + chars.front(): 'D' + .SH See also - push_front inserts elements to the beginning - \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + front access the first element + \fI(public member function)\fP diff --git a/man/std::forward_list::prepend_range.3 b/man/std::forward_list::prepend_range.3 new file mode 100644 index 000000000..4be3cd852 --- /dev/null +++ b/man/std::forward_list::prepend_range.3 @@ -0,0 +1,68 @@ +.TH std::forward_list::prepend_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::prepend_range \- std::forward_list::prepend_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void prepend_range( R&& rg ); + + Inserts, in non-reversing order, copies of elements in rg before begin(). Each + iterator in the range rg is dereferenced exactly once. + + No iterators or references are invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose + elements are convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into forward_list from *ranges::begin(rg). Otherwise, + the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in size of rg. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto container = std::forward_list{0, 1, 2, 3}; + const auto rg = std::vector{-3, -2, -1}; + + #if __cpp_lib_containers_ranges + container.prepend_range(rg); + #else + container.insert_after(container.before_begin(), rg.cbegin(), rg.cend()); + #endif + assert(std::ranges::equal(container, std::forward_list{-3, -2, -1, 0, 1, 2, 3})); + } + +.SH See also + + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + insert_range_after inserts a range of elements after an element + (C++23) \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(public member function)\fP diff --git a/man/std::forward_list::push_front.3 b/man/std::forward_list::push_front.3 index d717fce97..ac8805420 100644 --- a/man/std::forward_list::push_front.3 +++ b/man/std::forward_list::push_front.3 @@ -1,7 +1,10 @@ -.TH std::forward_list::push_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::push_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::push_front \- std::forward_list::push_front + .SH Synopsis - void push_front( const T& value ); \fI(since C++11)\fP - void push_front( T&& value ); \fI(since C++11)\fP + void push_front( const T& value ); \fB(1)\fP \fI(since C++11)\fP + void push_front( T&& value ); \fB(2)\fP \fI(since C++11)\fP Prepends the given element value to the beginning of the container. @@ -21,11 +24,45 @@ .SH Exceptions - If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::forward_list letters; + + letters.push_front("abc"); + std::string s{"def"}; + letters.push_front(std::move(s)); + + std::cout << "std::forward_list letters holds: "; + for (auto&& e : letters) + std::cout << std::quoted(e) << ' '; + + std::cout << "\\nMoved-from string s holds: " << std::quoted(s) << '\\n'; + } + +.SH Possible output: + + std::forward_list letters holds: "def" "abc" + Moved-from string s holds: "" .SH See also - emplace_front constructs elements in-place at the beginning - \fI(public member function)\fP - pop_front removes the first element - \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(public member function)\fP + pop_front removes the first element + \fI(public member function)\fP + creates a std::front_insert_iterator of type inferred from the + front_inserter argument + \fI(function template)\fP diff --git a/man/std::forward_list::remove,remove_if.3 b/man/std::forward_list::remove,remove_if.3 index 3f497b2e0..c6c800110 100644 --- a/man/std::forward_list::remove,remove_if.3 +++ b/man/std::forward_list::remove,remove_if.3 @@ -1,63 +1,84 @@ -.TH std::forward_list::remove,remove_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::remove,remove_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::remove,remove_if \- std::forward_list::remove,remove_if + .SH Synopsis - void remove( const T& value ); \fI(since C++11)\fP - template< class UnaryPredicate > \fI(since C++11)\fP - void remove_if( UnaryPredicate p ); + void remove( const T& value ); \fI(since C++11)\fP + \fI(until C++20)\fP + size_type remove( const T& value ); \fI(since C++20)\fP + template< class UnaryPredicate > \fB(1)\fP \fI(since C++11)\fP + void remove_if( UnaryPredicate p ); \fB(2)\fP \fI(until C++20)\fP + template< class UnaryPredicate > \fI(since C++20)\fP + size_type remove_if( UnaryPredicate p ); + + Removes all elements satisfying specific criteria. Invalidates only the iterators + and references to the removed elements. - Removes all elements satisfying specific criteria. The first version removes all - elements that are equal to value, the second version removes all elements for which - predicate p returns true. + 1) Removes all elements that are equal to value (using operator==). + 2) Removes all elements for which predicate p returns true. .SH Parameters value - value of the elements to remove unary predicate which returns true if the element should be removed. - The signature of the predicate function should be equivalent to the - following: - - p - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type - forward_list::const_iterator can be dereferenced and then - implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v of type + p - (possibly const) T, regardless of value category, and must not modify v. + Thus, a parameter type of T&is not allowed + , nor is T unless for T a move is equivalent to a copy + \fI(since C++11)\fP. +.SH Type requirements + - + UnaryPredicate must meet the requirements of Predicate. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++20)\fP + The number of elements removed. \fI(since C++20)\fP .SH Complexity - Linear in the size of the container + Given \\(\\scriptsize N\\)N as std::distance(begin(), end()): + + 1) Exactly \\(\\scriptsize N\\)N comparisons using operator==. + 2) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_list_remove_return_type 201806L (C++20) Change the return type .SH Example - + // Run this code #include #include - + int main() { - std::forward_list l = { 1,100,2,3,10,1,11,-1,12 }; - - l.remove(1); // remove both elements equal to 1 - l.remove_if([](int n){ return n > 10; }); // remove all elements greater than 10 - - for (int n : l) { + std::forward_list l = {1, 100, 2, 3, 10, 1, 11, -1, 12}; + + auto count1 = l.remove(1); + std::cout << count1 << " elements equal to 1 were removed\\n"; + + auto count2 = l.remove_if([](int n){ return n > 10; }); + std::cout << count2 << " elements greater than 10 were removed\\n"; + + std::cout << "Finally, the list contains: "; + for (int n : l) std::cout << n << ' '; - } std::cout << '\\n'; } .SH Output: - 2 3 10 -1 + 2 elements equal to 1 were removed + 3 elements greater than 10 were removed + Finally, the list contains: 2 3 10 -1 .SH See also remove removes elements satisfying specific criteria - remove_if \fI(function template)\fP + remove_if \fI(function template)\fP diff --git a/man/std::forward_list::resize.3 b/man/std::forward_list::resize.3 index fe2238a23..51783bfc0 100644 --- a/man/std::forward_list::resize.3 +++ b/man/std::forward_list::resize.3 @@ -1,29 +1,31 @@ -.TH std::forward_list::resize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::resize \- std::forward_list::resize + .SH Synopsis - void resize( size_type count ); - void resize( size_type count, const value_type& value); + void resize( size_type count ); \fB(1)\fP \fI(since C++11)\fP + void resize( size_type count, const value_type& value ); \fB(2)\fP \fI(since C++11)\fP - Resizes the container to contain count elements. + Resizes the container to contain count elements, does nothing if count == + std::distance(begin(), end()) (i.e. if count is equal to the current size). If the current size is greater than count, the container is reduced to its first - count elements as if by repeatedly calling pop_back() + count elements. - If the current size is less than count, additional elements are \fI(until C++11)\fP - appended and initialized with copies of value. If the current size is less than count, - \fI(since C++11)\fP - 1) additional value-initialized elements are appended - 2) additional copies of value are appended + + 1) additional default-inserted elements are appended. + 2) additional copies of value are appended. .SH Parameters - count - new size of the container - value - the value to initialize the new elements with + count - new size of the container + value - the value to initialize the new elements with .SH Type requirements - - 1) T must meet the requirements of DefaultConstructible and MoveInsertable. + T must meet the requirements of DefaultInsertable in order to use overload \fB(1)\fP. - - 2) T must meet the requirements of CopyInsertable and MoveInsertable. + T must meet the requirements of CopyInsertable in order to use overload \fB(2)\fP. .SH Return value @@ -31,6 +33,56 @@ .SH Complexity - Linear in the size of the container + Linear in the difference between the current size and count. Additional complexity + possible due to list traversal to reach the first element to erase/the end position + to insert. + +.SH Notes + + If value-initialization in overload \fB(1)\fP is undesirable, for example, if the elements + are of non-class type and zeroing out is not needed, it can be avoided by providing + a custom Allocator::construct. + +.SH Example + + +// Run this code + + #include + #include + + void print(auto rem, const std::forward_list& c) + { + for (std::cout << rem; const int el : c) + std::cout << el << ' '; + std::cout << '\\n'; + } + + int main() + { + std::forward_list c = {1, 2, 3}; + print("The forward_list holds: ", c); + + c.resize(5); + print("After resize up to 5: ", c); + + c.resize(2); + print("After resize down to 2: ", c); + + c.resize(6, 4); + print("After resize up to 6 (initializer = 4): ", c); + } + +.SH Output: + + The forward_list holds: 1 2 3 + After resize up to 5: 1 2 3 0 0 + After resize down to 2: 1 2 + After resize up to 6 (initializer = 4): 1 2 4 4 4 4 .SH See also + + insert_after inserts elements after an element + \fI(public member function)\fP + erase_after erases an element after an element + \fI(public member function)\fP diff --git a/man/std::forward_list::reverse.3 b/man/std::forward_list::reverse.3 index b21fdf3ea..f4de2120b 100644 --- a/man/std::forward_list::reverse.3 +++ b/man/std::forward_list::reverse.3 @@ -1,6 +1,9 @@ -.TH std::forward_list::reverse 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::reverse 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::reverse \- std::forward_list::reverse + .SH Synopsis - void reverse(); \fI(since C++11)\fP + void reverse() noexcept; \fI(since C++11)\fP Reverses the order of the elements in the container. No references or iterators become invalidated. @@ -13,44 +16,44 @@ \fI(none)\fP +.SH Complexity + + Linear in the size of the container. + .SH Example - + // Run this code #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::forward_list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (auto& i : list) + ostr << ' ' << i; return ostr; } - + int main() { - std::forward_list list = { 8,7,5,9,0,1,3,2,6,4 }; - - std::cout << "before: " << list << "\\n"; + std::forward_list list = {8, 7, 5, 9, 0, 1, 3, 2, 6, 4}; + std::cout << "initially: " << list << '\\n'; + list.sort(); - std::cout << "ascending: " << list << "\\n"; + std::cout << "ascending: " << list << '\\n'; + list.reverse(); - std::cout << "descending: " << list << "\\n"; + std::cout << "descending:" << list << '\\n'; } .SH Output: - before: 8 7 5 9 0 1 3 2 6 4 - ascending: 0 1 2 3 4 5 6 7 8 9 - descending: 9 8 7 6 5 4 3 2 1 0 - -.SH Complexity - - Linear in the size of the container + initially: 8 7 5 9 0 1 3 2 6 4 + ascending: 0 1 2 3 4 5 6 7 8 9 + descending: 9 8 7 6 5 4 3 2 1 0 .SH See also sort sorts the elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::forward_list::sort.3 b/man/std::forward_list::sort.3 index 8a6545dc6..6bef40e5c 100644 --- a/man/std::forward_list::sort.3 +++ b/man/std::forward_list::sort.3 @@ -1,68 +1,98 @@ -.TH std::forward_list::sort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::sort \- std::forward_list::sort + .SH Synopsis void sort(); \fB(1)\fP \fI(since C++11)\fP template< class Compare > \fB(2)\fP \fI(since C++11)\fP void sort( Compare comp ); - Sorts the elements in ascending order. The order of equal elements is preserved. The - first version uses operator< to compare the elements, the second version uses the - given comparison function comp. + Sorts the elements and preserves the order of equivalent elements. No references or + iterators become invalidated. + + 1) Elements are compared using operator<. + 2) Elements are compared using comp. + + If an exception is thrown, the order of elements in *this is unspecified. .SH Parameters comparison function object (i.e. an object that satisfies the requirements of - Compare) which returns true if the first argument is less (i.e. is ordered - before) the second element. + Compare) which returns true if the first argument is less than (i.e. is + ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must not - modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of type + (possibly const) Type1 and Type2 regardless of value category (thus, Type1& + is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type forward_list::const_iterator can be dereferenced and then - implicitly converted to both of them. + implicitly converted to both of them. +.SH Type requirements + - + Compare must meet the requirements of Compare. .SH Return value \fI(none)\fP +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(begin(), end()): + + 1) Approximately \\(\\scriptsize N \\cdot log(N)\\)N·log(N) comparisons using operator<. + 2) Approximately \\(\\scriptsize N \\cdot log(N)\\)N·log(N) applications of the + comparison function comp. + +.SH Notes + + std::sort requires random access iterators and so cannot be used with forward_list. + This function also differs from std::sort in that it does not require the element + type of the forward_list to be swappable, preserves the values of all iterators, and + performs a stable sort. + .SH Example - + // Run this code - #include #include + #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::forward_list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (const int i : list) + ostr << ' ' << i; return ostr; } - + int main() { - std::forward_list list = { 8,7,5,9,0,1,3,2,6,4 }; - - std::cout << "before: " << list << "\\n"; + std::forward_list list{8, 7, 5, 9, 0, 1, 3, 2, 6, 4}; + std::cout << "initially: " << list << '\\n'; + list.sort(); - std::cout << "ascending: " << list << "\\n"; + std::cout << "ascending: " << list << '\\n'; + list.sort(std::greater()); - std::cout << "descending: " << list << "\\n"; + std::cout << "descending:" << list << '\\n'; } .SH Output: - before: 8 7 5 9 0 1 3 2 6 4 - ascending: 0 1 2 3 4 5 6 7 8 9 - descending: 9 8 7 6 5 4 3 2 1 0 + initially: 8 7 5 9 0 1 3 2 6 4 + ascending: 0 1 2 3 4 5 6 7 8 9 + descending: 9 8 7 6 5 4 3 2 1 0 -.SH Complexity +.SH See also - N · log(N) comparisons, where N is the size of the container. + reverse reverses the order of the elements + \fI(public member function)\fP diff --git a/man/std::forward_list::splice_after.3 b/man/std::forward_list::splice_after.3 index f7f4a567e..b49a0ce18 100644 --- a/man/std::forward_list::splice_after.3 +++ b/man/std::forward_list::splice_after.3 @@ -1,32 +1,45 @@ -.TH std::forward_list::splice_after 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::splice_after 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::splice_after \- std::forward_list::splice_after + .SH Synopsis void splice_after( const_iterator pos, forward_list& other ); \fB(1)\fP \fI(since C++11)\fP - void splice_after( const_iterator pos, forward_list&& other ); \fB(1)\fP \fI(since C++11)\fP - void splice_after( const_iterator pos, forward_list& other, \fB(2)\fP \fI(since C++11)\fP + void splice_after( const_iterator pos, forward_list&& other ); \fB(2)\fP \fI(since C++11)\fP + void splice_after( const_iterator pos, forward_list& other, \fB(3)\fP \fI(since C++11)\fP const_iterator it ); - void splice_after( const_iterator pos, forward_list&& other, \fB(2)\fP \fI(since C++11)\fP + void splice_after( const_iterator pos, forward_list&& other, \fB(4)\fP \fI(since C++11)\fP const_iterator it ); - void splice_after( const_iterator pos, forward_list& other, \fB(3)\fP \fI(since C++11)\fP + void splice_after( const_iterator pos, forward_list& other, \fB(5)\fP \fI(since C++11)\fP const_iterator first, const_iterator last ); - void splice_after( const_iterator pos, forward_list&& other, \fB(3)\fP \fI(since C++11)\fP + void splice_after( const_iterator pos, forward_list&& other, \fB(6)\fP \fI(since C++11)\fP const_iterator first, const_iterator last ); - Moves elements from another forward_list to *this. + Moves elements from another forward_list to *this. The elements are inserted after + the element pointed to by pos. + + No elements are copied. No iterators or references become invalidated. The iterators + to the moved elements now refer into *this, not into other. + + 1,2) Moves all elements from other into *this. The container other becomes empty + after the operation. + 3,4) Moves the element pointed to by the iterator following it from other into + *this. Has no effect if pos == it or if pos == ++it. + 5,6) Moves the elements in the range (first, last) from other into *this. The + element pointed-to by first is not moved. + + The behavior is undefined if - No elements are copied. pos is a valid iterator in *this or is the before_begin() - iterator. The behavior is undefined if get_allocator() != other.get_allocator(). No - iterators or references become invalidated, the iterators to moved elements now - refer into *this, not into other. + * get_allocator() != other.get_allocator(), + * pos is neither before_begin() nor a dereferenceable iterator in + [begin(), end()), + * for overloads (1,2), *this and other refer to the same object, + * for overloads (3,4), the iterator following it is not a dereferenceable iterator + into other, or + * for overloads (5,6), - 1) Moves all elements from other into *this. The elements are inserted after the - element pointed to by pos. The container other becomes empty after the operation. - The behavior is undefined if this == &other - 2) Moves the element pointed to by the iterator following it from other into *this. - The element is inserted after the element pointed to by pos. - 3) Moves the elements in the range (first, last) from other into *this. The elements - are inserted after the element pointed to by pos. The element pointed-to by first is - not moved. The behavior is undefined if pos is an iterator in the range - (first,last). + * (first, last) is not a valid range in other, + * some iterators in (first, last) are not dereferenceable, or + * pos is in (first, last). .SH Parameters @@ -40,48 +53,77 @@ \fI(none)\fP +.SH Exceptions + + Throws nothing. + .SH Complexity - 1) Linear in the size of other - 2) Constant - 3) Linear in std::distance(first, last) + 1,2) Linear in the size of other. + 3,4) Constant. + 5,6) Linear in std::distance(first, last). .SH Example - Demonstrates the meaning of open interval (first, last) in the third form of - splice_after(): the first element of l1 is not moved. - // Run this code - #include + #include #include - + int main() { - std::forward_list l1 = {1,2,3,4,5}; - std::forward_list l2 = {10,11,12}; - + using F = std::forward_list; + + // Demonstrate the meaning of open range (first, last) + // in overload (5): the first element of l1 is not moved. + F l1 = {1, 2, 3, 4, 5}; + F l2 = {10, 11, 12}; + l2.splice_after(l2.cbegin(), l1, l1.cbegin(), l1.cend()); - // not equivalent to l2.splice_after(l2.cbegin(), l1); - - for(int n : l1) - std::cout << n << ' '; - std::cout << '\\n'; - - for(int n : l2) - std::cout << n << ' '; - std::cout << '\\n'; + // Not equivalent to l2.splice_after(l2.cbegin(), l1); + // which is equivalent to + // l2.splice_after(l2.cbegin(), l1, l1.cbefore_begin(), l1.end()); + + assert((l1 == F{1})); + assert((l2 == F{10, 2, 3, 4, 5, 11, 12})); + + // Overload (1) + F x = {1, 2, 3, 4, 5}; + F y = {10, 11, 12}; + x.splice_after(x.cbegin(), y); + assert((x == F{1, 10, 11, 12, 2, 3, 4, 5})); + assert((y == F{})); + + // Overload (3) + x = {1, 2, 3, 4, 5}; + y = {10, 11, 12}; + x.splice_after(x.cbegin(), y, y.cbegin()); + assert((x == F{1, 11, 2, 3, 4, 5})); + assert((y == F{10, 12})); + + // Overload (5) + x = {1, 2, 3, 4, 5}; + y = {10, 11, 12}; + x.splice_after(x.cbegin(), y, y.cbegin(), y.cend()); + assert((x == F{1, 11, 12, 2, 3, 4, 5})); + assert((y == F{10})); } -.SH Output: + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 1 - 10 2 3 4 5 11 12 + DR Applied to Behavior as published Correct behavior + LWG 2045 C++11 O(1) splicing could not be guaranteed if the behavior is + get_allocator() != other.get_allocator() undefined in this case .SH See also - merge merges two sorted lists - \fI(public member function)\fP - remove removes elements satisfying specific criteria - remove_if \fI(public member function)\fP + merge merges two sorted lists + \fI(public member function)\fP + remove removes elements satisfying specific criteria + remove_if \fI(public member function)\fP + before_begin returns an iterator to the element before beginning + cbefore_begin \fI(public member function)\fP diff --git a/man/std::forward_list::swap.3 b/man/std::forward_list::swap.3 index e4c5e97f3..1deb35a3e 100644 --- a/man/std::forward_list::swap.3 +++ b/man/std::forward_list::swap.3 @@ -1,17 +1,23 @@ -.TH std::forward_list::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::swap \- std::forward_list::swap + .SH Synopsis - void swap( forward_list& other ); \fI(since C++11)\fP + void swap( forward_list& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + void swap( forward_list& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. It is unspecified whether an iterator + holding the end() value in this container will refer to this or the other container + after the operation. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -23,13 +29,59 @@ .SH Exceptions - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::forward_list a1{1, 2, 3}, a2{4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + int& ref1 = a1.front(); + int& ref2 = a2.front(); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that after swap the iterators and references stay associated with their + // original elements, e.g. it1 that pointed to an element in 'a1' with value 2 + // still points to the same element, though this element was moved into 'a2'. + } + +.SH Output: + + { 1 2 3 } { 4 5 } 2 5 1 4 + { 4 5 } { 1 2 3 } 2 5 1 4 + .SH See also std::swap(std::forward_list) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::forward_list::unique.3 b/man/std::forward_list::unique.3 index 97fb993b0..c90567c8e 100644 --- a/man/std::forward_list::unique.3 +++ b/man/std::forward_list::unique.3 @@ -1,12 +1,25 @@ -.TH std::forward_list::unique 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::unique 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::unique \- std::forward_list::unique + .SH Synopsis - void unique(); \fB(1)\fP \fI(since C++11)\fP - template< class BinaryPredicate > \fB(2)\fP \fI(since C++11)\fP - void unique( BinaryPredicate p ); + void unique(); \fI(since C++11)\fP + \fI(until C++20)\fP + size_type unique(); \fI(since C++20)\fP + template< class BinaryPredicate > \fB(1)\fP \fI(since C++11)\fP + void unique( BinaryPredicate p ); \fB(2)\fP \fI(until C++20)\fP + template< class BinaryPredicate > \fI(since C++20)\fP + size_type unique( BinaryPredicate p ); Removes all consecutive duplicate elements from the container. Only the first - element in each group of equal elements is left. The first version uses operator== - to compare the elements, the second version uses the given binary predicate p. + element in each group of equal elements is left. Invalidates only the iterators and + references to the removed elements. + + 1) Uses operator== to compare the elements. + 2) Uses p to compare the elements. + + The behavior is undefined if the corresponding comparator does not establish an + equivalence relation. .SH Parameters @@ -16,54 +29,84 @@ bool pred(const Type1 &a, const Type2 &b); - p - The signature does not need to have const &, but the function must not modify - the objects passed to it. + While the signature does not need to have const &, the function must not modify + p - the objects passed to it and must be able to accept all values of type (possibly + const) Type1 and Type2 regardless of value category (thus, Type1 & is not + allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type forward_list::const_iterator can be dereferenced and then implicitly converted to both of them. - - +.SH Type requirements + - + BinaryPredicate must meet the requirements of BinaryPredicate. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++20)\fP + The number of elements removed. \fI(since C++20)\fP .SH Complexity - Linear in the size of the container + If empty() is true, no comparison is performed. + + Otherwise, given \\(\\scriptsize N\\)N as std::distance(begin(), end()): + + 1) Exactly \\(\\scriptsize N-1\\)N-1 comparisons using operator==. + 2) Exactly \\(\\scriptsize N-1\\)N-1 applications of the predicate p. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_list_remove_return_type 201806L (C++20) Change the return type .SH Example - + // Run this code #include #include - + + std::ostream& operator<< (std::ostream& os, std::forward_list const& container) + { + for (int val : container) + os << val << ' '; + return os << '\\n'; + } + int main() { - std::forward_list x = {1, 2, 2, 3, 3, 2, 1, 1, 2}; - - std::cout << "contents before:"; - for (auto val : x) - std::cout << ' ' << val; - std::cout << '\\n'; - - x.unique(); - std::cout << "contents after unique():"; - for (auto val : x) - std::cout << ' ' << val; - std::cout << '\\n'; - - return 0; + std::forward_list c{1, 2, 2, 3, 3, 2, 1, 1, 2}; + std::cout << "Before unique(): " << c; + const auto count1 = c.unique(); + std::cout << "After unique(): " << c + << count1 << " elements were removed\\n"; + + c = {1, 2, 12, 23, 3, 2, 51, 1, 2, 2}; + std::cout << "\\nBefore unique(pred): " << c; + + const auto count2 = c.unique([mod = 10](int x, int y) + { + return (x % mod) == (y % mod); + }); + + std::cout << "After unique(pred): " << c + << count2 << " elements were removed\\n"; } .SH Output: - contents before: 1 2 2 3 3 2 1 1 2 - contents after unique(): 1 2 3 2 1 2 + Before unique(): 1 2 2 3 3 2 1 1 2 + After unique(): 1 2 3 2 1 2 + 3 elements were removed + + Before unique(pred): 1 2 12 23 3 2 51 1 2 2 + After unique(pred): 1 2 23 2 51 2 + 4 elements were removed .SH See also unique removes consecutive duplicate elements in a range - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::forward_list::~forward_list.3 b/man/std::forward_list::~forward_list.3 index e615fc9ec..a84598bbd 100644 --- a/man/std::forward_list::~forward_list.3 +++ b/man/std::forward_list::~forward_list.3 @@ -1,11 +1,14 @@ -.TH std::forward_list::~forward_list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::forward_list::~forward_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::forward_list::~forward_list \- std::forward_list::~forward_list + .SH Synopsis ~forward_list(); \fI(since C++11)\fP - Destructs the container. The destructors of the elements are called and the used + Destructs the forward_list. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the forward_list. diff --git a/man/std::fpclassify.3 b/man/std::fpclassify.3 index 447b0c80e..8571db070 100644 --- a/man/std::fpclassify.3 +++ b/man/std::fpclassify.3 @@ -1,32 +1,102 @@ -.TH std::fpclassify 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fpclassify 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fpclassify \- std::fpclassify + .SH Synopsis Defined in header - int fpclassify( float arg ); \fI(since C++11)\fP - int fpclassify( double arg ); \fI(since C++11)\fP - int fpclassify( long double arg ); \fI(since C++11)\fP + int fpclassify( float num ); + \fI(since C++11)\fP + int fpclassify( double num ); (until C++23) + + int fpclassify( long double num ); + constexpr int fpclassify( /* floating-point-type */ \fB(1)\fP (since C++23) + num ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + int fpclassify( Integer num ); (constexpr since C++23) - Categorizes floating point value arg into the following categories: zero, subnormal, - normal, infinite, NAN, or implementation-defined category. + 1) Categorizes floating point value num into the following categories: zero, + subnormal, normal, infinite, NAN, or implementation-defined category. + The library provides overloads of std::fpclassify for all cv-unqualified + floating-point types as the type of the parameter num. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. .SH Parameters - arg - floating point value + num - floating-point or integer value .SH Return value one of FP_INFINITE, FP_NAN, FP_NORMAL, FP_SUBNORMAL, FP_ZERO or - implementation-defined type, specifying the category of arg. + implementation-defined type, specifying the category of num. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::fpclassify(num) has the same effect as + std::fpclassify(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + auto show_classification(double x) + { + switch (std::fpclassify(x)) + { + case FP_INFINITE: + return "Inf"; + case FP_NAN: + return "NaN"; + case FP_NORMAL: + return "normal"; + case FP_SUBNORMAL: + return "subnormal"; + case FP_ZERO: + return "zero"; + default: + return "unknown"; + } + } + + int main() + { + std::cout << "1.0/0.0 is " << show_classification(1 / 0.0) << '\\n' + << "0.0/0.0 is " << show_classification(0.0 / 0.0) << '\\n' + << "DBL_MIN/2 is " << show_classification(DBL_MIN / 2) << '\\n' + << "-0.0 is " << show_classification(-0.0) << '\\n' + << "1.0 is " << show_classification(1.0) << '\\n'; + } + +.SH Output: + + 1.0/0.0 is Inf + 0.0/0.0 is NaN + DBL_MIN/2 is subnormal + -0.0 is zero + 1.0 is normal .SH See also isfinite checks if the given number has finite value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isinf checks if the given number is infinite - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnan checks if the given number is NaN - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnormal checks if the given number is normal - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP provides an interface to query properties of all fundamental numeric - numeric_limits types. - \fI(class template)\fP + numeric_limits types + \fI(class template)\fP + C documentation for + fpclassify diff --git a/man/std::fpos.3 b/man/std::fpos.3 index d47b6b293..a8a7c8729 100644 --- a/man/std::fpos.3 +++ b/man/std::fpos.3 @@ -1,4 +1,7 @@ -.TH std::fpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fpos \- std::fpos + .SH Synopsis Defined in header template< class State > @@ -9,44 +12,85 @@ (typically as a private member of type std::streamoff) and the current shift state, a value of type State (typically std::mbstate_t). - Four specializations of std::fpos are provided: - - Defined in header - Type Definition - streampos std::fpos::state_type> - u16streampos std::fpos::state_type> - u32streampos std::fpos::state_type> - wstreampos std::fpos::state_type> + The following typedef names for std::fpos are provided (although + they are spelled differently in the standard, they denote the same type): -.SH Member functions - - state gets/sets the value of the shift state - \fI(public member function)\fP + Defined in header + Type Definition + std::streampos std::fpos::state_type> + std::wstreampos std::fpos::state_type> + std::u8streampos(C++20) std::fpos::state_type> + std::u16streampos \fI(C++11)\fP std::fpos::state_type> + std::u32streampos \fI(C++11)\fP std::fpos::state_type> - In addition, the following member functions and operators must be provided, although - it's unspecified if they are members or non-member. + All specializations of fpos meet the DefaultConstructible, CopyConstructible, + CopyAssignable, Destructible, and EqualityComparable requirements. - * A constructor that accepts an argument of type int. + If State is trivially copy constructible, fpos has a trivial copy constructor. If + State is trivially copy assignable, fpos has a trivial copy assignment operator. If + State is trivially destructible, fpos has a trivial destructor. - * A constructor that accepts an argument of type std::streamoff. This constructor - must also accept the special value std::streamoff(-1): the std::fpos constructed - in this manner is returned by some stream operations to indicate errors. +.SH Type requirements + - + State must meet the requirements of Destructible, CopyAssignable, CopyConstructible + and DefaultConstructible. - * A conversion operator that converts fpos to std::streamoff with the value equal - to the offset from std::fpos\fB(0)\fP. - - * operator== that compares two objects of type std::fpos and returns a value of - type convertible to bool - - * operator!= that compares two objects of type std::fpos and returns a value of - type convertible to bool - - * operator+ and operator+= which can add std::streamoff to std::fpos +.SH Member functions - * operator- and operator-= which can subtract std::streamoff from an std::fpos + state gets/sets the value of the shift state + \fI(public member function)\fP - * operator- which can subtract two objects of type std::fpos producing an - std::streamoff + In addition, member and non-member functions are provided to support the following + operations: + + * A default constructor that stores an offset of zero and value-initializes the + state object. + * A non-explicit constructor that accepts an argument of type (possibly const) + std::streamoff, which stores that offset and value-initializes the state object. + This constructor must also accept the special value std::streamoff(-1): the + std::fpos constructed in this manner is returned by some stream operations to + indicate errors. + * Explicit conversion from (possibly const) fpos to std::streamoff. The result is + the stored offset. + * operator== and operator!= that compare two objects of type (possibly const) + std::fpos and returns a value of type convertible to bool. p != q is equivalent + to !(p == q). + * operator+ and operator- such that, for an object p of type (possibly const) + fpos and an object o of type (possibly const) std::streamoff + + * p + o has type fpos and stores an offset that is the result of adding o + to the offset of p. + * o + p has a type convertible to fpos and the result of the conversion is + equal to p + o. + * p - o has type fpos and stores an offset that is the result of + subtracting o from the offset of p. + * operator+= and operator-= which can accept a (possibly const) std::streamoff and + adds/subtracts it from the stored offset, respectively. + * operator- which can subtract two objects of type (possibly const) std::fpos + producing an std::streamoff, such that for two such objects p and q, p == q + (p + - q). + +.SH Notes + + Some of the I/O streams member functions return and manipulate objects of member + typedef pos_type. For streams, these member typedefs are provided by the template + parameter Traits, which defaults to std::char_traits, which define their pos_types + to be specializations of std::fpos. The behavior of the I/O streams library is + implementation-defined when Traits::pos_type is not std::fpos (aka + std::streampos, std::wstreampos, etc.). + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + streampos and wstreampos were contradictionally clarified to + LWG 57 C++98 allowed to be different while required to be the be the same + same + P0759R1 C++98 specification was unclear and incomplete cleaned up + P1148R0 C++11 unclear what and in which header the made clear + definitions u16streampos and u32streampos are .SH See also @@ -54,8 +98,8 @@ streamoff represent any file size \fI(typedef)\fP tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP fgetpos gets the file position indicator - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::fpos::state.3 b/man/std::fpos::state.3 index 444ae6625..c0877de1a 100644 --- a/man/std::fpos::state.3 +++ b/man/std::fpos::state.3 @@ -1,15 +1,18 @@ -.TH std::fpos::state 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fpos::state 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fpos::state \- std::fpos::state + .SH Synopsis State state() const; \fB(1)\fP void state( State st ); \fB(2)\fP Manages the file position state. - 1) Returns the value of the file position state + 1) Returns the value of the file position state. 2) Replaces the file position state with the value of st. For the specializations of std::fpos that are used in the standard library, State is - always std::mbstate_t + always std::mbstate_t. .SH Parameters @@ -17,24 +20,24 @@ .SH Return value - 1) the current value of the fpos state + 1) The current value of the fpos state. 2) \fI(none)\fP .SH Example - + // Run this code + #include #include #include - #include - + int main() { std::istringstream s("test"); std::mbstate_t st = s.tellg().state(); - - if(std::mbsinit(&st)) + + if (std::mbsinit(&st)) std::cout << "The stream is in the initial shift state\\n"; } @@ -42,8 +45,17 @@ The stream is in the initial shift state + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 441 C++98 overload \fB(1)\fP was not declared const (it is const added const + in the synopsis) + .SH See also conversion state information necessary to iterate multibyte character mbstate_t strings - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::fpos_t.3 b/man/std::fpos_t.3 new file mode 100644 index 000000000..ee74f3a93 --- /dev/null +++ b/man/std::fpos_t.3 @@ -0,0 +1,29 @@ +.TH std::fpos_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fpos_t \- std::fpos_t + +.SH Synopsis + Defined in header + typedef /* implementation-defined */ fpos_t; + + std::fpos_t is a non-array complete object type, can be used to store (by + std::fgetpos) and restore (by std::fsetpos) the position and multibyte parser state + (if any) for a C stream. + + The multibyte parser state of a wide-oriented C stream is represented by a + std::mbstate_t object, whose value is stored as part of the value of a std::fpos_t + object by std::fgetpos. + +.SH See also + + fgetpos gets the file position indicator + \fI(function)\fP + fsetpos moves the file position indicator to a specific location in a file + \fI(function)\fP + conversion state information necessary to iterate multibyte character + mbstate_t strings + \fI(class)\fP + fpos represents absolute position in a stream or a file + \fI(class template)\fP + C documentation for + fpos_t diff --git a/man/std::fputc,std::putc.3 b/man/std::fputc,std::putc.3 index 78764a840..21bd250b1 100644 --- a/man/std::fputc,std::putc.3 +++ b/man/std::fputc,std::putc.3 @@ -1,55 +1,61 @@ -.TH std::fputc,std::putc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fputc,std::putc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fputc,std::putc \- std::fputc,std::putc + .SH Synopsis Defined in header int fputc( int ch, std::FILE* stream ); int putc( int ch, std::FILE* stream ); - Writes a character ch to the given output stream stream. putc() function may be - implemented as a macro. + Writes a character ch to the given output stream stream. Internally, the character is converted to unsigned char just before being written. + In C, putc() may be implemented as a macro, which is disallowed in C++. Therefore, + calls to std::fputc() and std::putc() always have the same effect. + .SH Parameters - ch - character to be written + ch - character to be written + stream - output stream .SH Return value On success, returns the written character. - On failure, returns EOF and sets the error indicator (see ferror()) on stdout. + On failure, returns EOF and sets the error indicator (see std::ferror()) on stream. .SH Example - + // Run this code #include - + int main() { for (char c = 'a'; c != 'z'; c++) std::putc(c, stdout); - std::putc('\\n', stdout); - - // putchar return value is not equal to the argument - int r = 0x1070; - std::printf("\\n0x%x\\n", r); - r = std::putchar(r, stdout); - std::printf("\\n0x%x\\n", r); + + // putchar's return value is not equal to the argument + int r = 0x102A; + std::printf("\\nr = 0x%x\\n", r); + + r = std::putchar(r); + std::printf("\\nr = 0x%x\\n", r); } -.SH Output: +.SH Possible output: abcdefghijklmnopqrstuvwxy - 0x1070 - p - 0x70 + r = 0x102A + * + r = 0x2A .SH See also putchar writes a character to stdout - \fI(function)\fP + \fI(function)\fP C documentation for fputc, putc diff --git a/man/std::fputs.3 b/man/std::fputs.3 index db5a4ae87..8fdd70ef1 100644 --- a/man/std::fputs.3 +++ b/man/std::fputs.3 @@ -1,9 +1,15 @@ -.TH std::fputs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fputs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fputs \- std::fputs + .SH Synopsis Defined in header int fputs( const char* str, std::FILE* stream ); - Writes given null-terminated character string to the given output stream. + Writes every character from the null-terminated string str to the output stream + stream, as if by repeatedly executing std::fputc. + + The terminating null character from str is not written. .SH Parameters @@ -12,18 +18,51 @@ .SH Return value - Non-negative integer on success, EOF on failure + On success, returns a non-negative value + + On failure, returns EOF and sets the error indicator (see std::ferror) on stream. + +.SH Notes + + The related function std::puts appends a newline character to the output, while + std::fputs writes the string unmodified. + + Different implementations return different non-negative numbers: some return the + last character written, some return the number of characters written (or INT_MAX if + the string was longer than that), some simply return a non-negative constant such as + zero. + +.SH Example + + +// Run this code + + #include + + int main(void) + { + int rc = std::fputs("Hello World", stdout); + + if (rc == EOF) + std::perror("fputs()"); // POSIX requires that errno is set + } + +.SH Output: + + Hello World .SH See also printf fprintf prints formatted output to stdout, a file stream or a buffer - sprintf \fI(function)\fP + sprintf \fI(function)\fP snprintf \fI(C++11)\fP puts writes a character string to stdout - \fI(function)\fP + \fI(function)\fP + fputws writes a wide string to a file stream + \fI(function)\fP fgets gets a character string from a file stream - \fI(function)\fP + \fI(function)\fP C documentation for fputs diff --git a/man/std::fputwc.3 b/man/std::fputwc.3 index 5879c0734..fb3913133 100644 --- a/man/std::fputwc.3 +++ b/man/std::fputwc.3 @@ -1,11 +1,15 @@ -.TH std::fputwc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fputwc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fputwc \- std::fputwc + .SH Synopsis Defined in header - wint_t fputwc( wchar_t ch, std::FILE* stream ); - wint_t putwc( wchar_t ch, std::FILE* stream ); + std::wint_t fputwc( wchar_t ch, std::FILE* stream ); \fB(1)\fP + std::wint_t putwc( wchar_t ch, std::FILE* stream ); \fB(2)\fP + + Writes a wide character ch to the given output stream stream. - Writes a wide character ch to the given output stream stream. putwc() may be - implemented as a macro and may evaluate stream more than once. + 2) May be implemented as a macro and may evaluate stream more than once. .SH Parameters @@ -16,13 +20,53 @@ ch on success, WEOF on failure. If an encoding error occurs, errno is set to EILSEQ. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + + for (const wchar_t ch : + { + L'\\u2200', // Unicode name: "FOR ALL" + L'\\n', + L'∀', + }) + { + if (errno = 0; std::fputwc(ch, stdout) == WEOF) + { + std::puts(errno == EILSEQ + ? "Encoding error in fputwc" + : "I/O error in fputwc" + ); + return EXIT_FAILURE; + } + } + return EXIT_SUCCESS; + } + +.SH Possible output: + + ∀ + ∀ + .SH See also fputc writes a character to a file stream - putc \fI(function)\fP + putc \fI(function)\fP fputws writes a wide string to a file stream - \fI(function)\fP + \fI(function)\fP fgetwc gets a wide character from a file stream - getwc \fI(function)\fP + getwc \fI(function)\fP C documentation for fputwc diff --git a/man/std::fputws.3 b/man/std::fputws.3 index 8b3bd6f38..c9473459b 100644 --- a/man/std::fputws.3 +++ b/man/std::fputws.3 @@ -1,9 +1,15 @@ -.TH std::fputws 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fputws 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fputws \- std::fputws + .SH Synopsis Defined in header int fputws( const wchar_t* str, std::FILE* stream ); - Writes given null-terminated wide string to the given output stream. + Writes every wide character from the null-terminated wide string str to the output + stream stream, as if by repeatedly executing std::fputwc. + + The terminating null wide character from str is not written. .SH Parameters @@ -12,18 +18,42 @@ .SH Return value - Non-negative integer on success, WEOF on failure + On success, returns a non-negative value + + On failure, returns EOF and sets the error indicator (see std::ferror) on stream. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + int rc = std::fputws(L"御休みなさい", stdout); + + if (rc == EOF) + std::perror("fputws()"); // POSIX requires that errno is set + } + +.SH Possible output: + + 御休みなさい .SH See also fputs writes a character string to a file stream - \fI(function)\fP + \fI(function)\fP wprintf prints formatted wide character output to stdout, a file stream or a buffer - fwprintf \fI(function)\fP + fwprintf \fI(function)\fP swprintf fputws writes a wide string to a file stream - \fI(function)\fP + \fI(function)\fP fgetws gets a wide string from a file stream - \fI(function)\fP + \fI(function)\fP C documentation for fputws diff --git a/man/std::fread.3 b/man/std::fread.3 index b3b404990..2c9f87898 100644 --- a/man/std::fread.3 +++ b/man/std::fread.3 @@ -1,4 +1,7 @@ -.TH std::fread 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fread \- std::fread + .SH Synopsis Defined in header std::size_t fread( void* buffer, std::size_t size, std::size_t count, std::FILE* @@ -13,13 +16,14 @@ If the objects are not TriviallyCopyable, the behavior is undefined. If an error occurs, the resulting value of the file position indicator for the - stream is indeterminate. If a partial element is read, its value is indeterminate + stream is indeterminate. If a partial element is read, its value is indeterminate. .SH Parameters buffer - pointer to the first object in the array to be read size - size of each object in bytes count - the number of the objects to be read + stream - input file stream to read from .SH Return value @@ -28,44 +32,53 @@ If size or count is zero, fread returns zero and performs no other action. + fread does not distinguish between end-of-file and error, and callers must use + std::feof and std::ferror to determine which occurred. + .SH Example - + // Run this code - #include + #include #include #include + #include + #include #include + int main() { - // prepare file + // Prepare file std::ofstream("test.txt") << 1 << ' ' << 2 << '\\n'; std::FILE* f = std::fopen("test.txt", "r"); - - std::vector buf(4); // char is trivally copyable - std::fread(&buf[0], sizeof buf[0], buf.size(), f); - - for(char n : buf) - std::cout << n; - + + std::vector buf(4); // char is trivially copyable + const std::size_t n = std::fread(&buf[0], sizeof buf[0], buf.size(), f); + + std::cout << "Read " << n << " object" << (n > 1 ? "s" : "") << ": " + << std::hex << std::uppercase << std::setfill('0'); + for (char n : buf) + std::cout << "0x" << std::setw(2) << static_cast(n) << ' '; + std::cout << '\\n'; + std::vector buf2; // string is not trivially copyable - // this would result in undefined behavior - // std::fread(&buf2[0], sizeof buf2[0], buf2.size(), f); + // This would result in undefined behavior: + // std::fread(&buf2[0], sizeof buf2[0], buf2.size(), f); } -.SH Output: +.SH Possible output: - 1 2 + Read 4 objects: 0x31 0x20 0x32 0x0A .SH See also scanf reads formatted input from stdin, a file stream or a buffer - fscanf \fI(function)\fP + fscanf \fI(function)\fP sscanf fgets gets a character string from a file stream - \fI(function)\fP + \fI(function)\fP fwrite writes to a file - \fI(function)\fP + \fI(function)\fP C documentation for fread diff --git a/man/std::free.3 b/man/std::free.3 index 697e1d4ba..4796db5c0 100644 --- a/man/std::free.3 +++ b/man/std::free.3 @@ -1,17 +1,44 @@ -.TH std::free 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::free 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::free \- std::free + .SH Synopsis Defined in header void free( void* ptr ); - Deallocates the space previously allocated by std::malloc(), std::calloc() or - std::realloc(). If ptr is null-pointer, the function does nothing. + Deallocates the space previously allocated by std::malloc, std::calloc + , std::aligned_alloc + \fI(since C++17)\fP, or std::realloc. + + If ptr is a null pointer, the function does nothing. + + The behavior is undefined if the value of ptr does not equal a value returned + earlier by std::malloc, std::calloc + , std::aligned_alloc + \fI(since C++17)\fP, or std::realloc. + + The behavior is undefined if the memory area referred to by ptr has already been + deallocated, that is, std::free or std::realloc has already been called with ptr as + the argument and no calls to std::malloc, std::calloc + , std::aligned_alloc + \fI(since C++17)\fP, or std::realloc resulted in a pointer equal to ptr afterwards. - The behavior is undefined if ptr does not match a pointer returned earlier by - std::malloc(), std::calloc() or std::realloc(). Also, the behavior is undefined if - the memory area referred to by ptr has already been deallocated, that is, free() or - std::realloc() has already been called with ptr as the argument and no calls to - std::malloc(), std::calloc() or std::realloc() resulted in a pointer equal to ptr - afterwards. + The behavior is undefined if after std::free returns, an access is made through the + pointer ptr (unless another allocation function happened to result in a pointer + value equal to ptr). + + The following functions are required to be thread-safe: + + * The library versions of operator new and operator delete + * User replacement versions of global operator new and operator + delete + * std::calloc, std::malloc, std::realloc \fI(since C++11)\fP + , std::aligned_alloc + \fI(since C++17)\fP, std::free + + Calls to these functions that allocate or deallocate a particular unit + of storage occur in a single total order, and each such deallocation + call happens-before the next allocation (if any) in this order. .SH Parameters @@ -21,16 +48,32 @@ \fI(none)\fP +.SH Notes + + The function accepts (and does nothing with) the null pointer to reduce the amount + of special-casing. Whether allocation succeeds or not, the pointer returned by an + allocation function can be passed to std::free. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + + int main() + { + int* p1 = (int*)std::malloc(10 * sizeof *p1); + std::free(p1); // every allocated pointer must be freed + + int* p2 = (int*)std::calloc(10, sizeof *p2); + int* p3 = (int*)std::realloc(p2, 1000 * sizeof *p3); + if (!p3) // p3 null means realloc failed and p2 must be freed. + std::free(p2); + std::free(p3); // p3 can be freed whether or not it is null. + } .SH See also C documentation for free - -.SH Category: - - * Todo no example diff --git a/man/std::freopen.3 b/man/std::freopen.3 index 7401cd731..d7a1d4a57 100644 --- a/man/std::freopen.3 +++ b/man/std::freopen.3 @@ -1,56 +1,80 @@ -.TH std::freopen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::freopen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::freopen \- std::freopen + .SH Synopsis Defined in header std::FILE* freopen( const char* filename, const char* mode, std::FILE* stream ); - Reassigns an existing file stream stream to a different file identified by - filenameusing specified mode. mode is used to determine the new file access mode. + First, attempts to close the file associated with stream, ignoring any errors. Then, + if filename is not null, attempts to open the file specified by filename using mode + as if by std::fopen, and associates that file with the file stream pointed to by + stream. If filename is a null pointer, then the function attempts to reopen the file + that is already associated with stream (it is implementation defined which mode + changes are allowed in this case). .SH Parameters filename - file name to associate the file stream to - null-terminated character string determining new file access mode - - Action if Action if - File access Meaning Explanation file file - mode string already does not - exists exist - "r" read Open a file for read from failure to - reading start open - "w" write Create a file for destroy create new - writing contents - mode - "a" append Append to a file write to end create new - "r+" read extended Open a file for read from error - read/write start - "w+" write extended Create a file for destroy create new - read/write contents - "a+" append Open a file for write to end create new - extended read/write - File access mode flag "b" can optionally be specified to open a file in - binary mode. This flag has effect only on Windows systems. - On the append file access modes, data is written to the end of the file - regardless of the current position of the file position indicator. + mode - null-terminated character string determining new file access mode stream - the file stream to modify + File access flags + + File access Meaning Explanation Action if file Action if file + mode string already exists does not exist + "r" read Open a file for read from start return NULL and + reading set error + "w" write Create a file for destroy contents create new + writing + "a" append Append to a file write to end create new + "r+" read extended Open a file for read from start return NULL and + read/write set error + "w+" write extended Create a file for destroy contents create new + read/write + "a+" append extended Open a file for write to end create new + read/write + File access mode flag "b" can optionally be specified to open a file in binary mode. + This flag has no effect on POSIX systems, but on Windows, for example, it disables + special handling of '\\n' and '\\x1A'. + On the append file access modes, data is written to the end of the file regardless + of the current position of the file position indicator. + File access mode flag "x" can optionally be appended to "w" or "w+" specifiers. This + flag forces the function to fail if the file exists, instead of overwriting it. + \fI(C++17)\fP + The behavior is undefined if the mode is not one of the strings listed above. Some + implementations define additional supported modes (e.g. Windows). + .SH Return value - stream on success, NULL on failure + stream on success, a null pointer on failure. + +.SH Notes + + std::freopen is the only way to change the narrow/wide orientation of a stream once + it has been established by an I/O operation or by std::fwide. + + Microsoft CRT version of std::freopen does not support any mode changes when + filename is a null pointer and treats this as an error (see documentation). A + possible workaround is the non-standard function _setmode(). .SH Example - The following code redirects stdout to a file + The following code redirects stdout to a file. + - // Run this code #include - + int main() { - std::printf("stdout is printed to console"); - std::freopen("redir.txt", "w", stdout); - std::printf("stdout is redirected to a file"); - std::fclose(stdout); + std::printf("stdout is printed to console\\n"); + if (std::freopen("redir.txt", "w", stdout)) + { + std::printf("stdout is redirected to a file\\n"); // this is written to redir.txt + std::fclose(stdout); + } } .SH Output: @@ -60,8 +84,8 @@ .SH See also fopen opens a file - \fI(function)\fP + \fI(function)\fP fclose closes a file - \fI(function)\fP + \fI(function)\fP C documentation for freopen diff --git a/man/std::frexp,std::frexpf,std::frexpl.3 b/man/std::frexp,std::frexpf,std::frexpl.3 new file mode 100644 index 000000000..3b3d65694 --- /dev/null +++ b/man/std::frexp,std::frexpf,std::frexpl.3 @@ -0,0 +1,143 @@ +.TH std::frexp,std::frexpf,std::frexpl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::frexp,std::frexpf,std::frexpl \- std::frexp,std::frexpf,std::frexpl + +.SH Synopsis + Defined in header + float frexp ( float num, int* exp ); + + double frexp ( double num, int* exp ); (until C++23) + + long double frexp ( long double num, int* exp ); + constexpr /* floating-point-type */ + frexp ( /* floating-point-type */ num, (since C++23) + int* exp ); \fB(1)\fP + float frexpf( float num, int* exp ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double frexpl( long double num, int* exp ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double frexp ( Integer num, int* exp ); + + 1-3) Decomposes given floating point value num into a normalized fraction and an + integral exponent of two. + The library provides overloads of std::frexp for all cv-unqualified floating-point + types as the type of the parameter num. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + exp - pointer to integer value to store the exponent to + +.SH Return value + + If num is zero, returns zero and stores zero in *exp. + + Otherwise (if num is not zero), if no errors occur, returns the value x in the range + (-1, -0.5], [0.5, 1) and stores an integer value in *exp such that x×2(*exp) + == num. + + If the value to be stored in *exp is outside the range of int, the behavior is + unspecified. + +.SH Error handling + + This function is not subject to any errors specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If num is ±0, it is returned, unmodified, and 0 is stored in *exp. + * If num is ±∞, it is returned, and an unspecified value is stored in *exp. + * If num is NaN, NaN is returned, and an unspecified value is stored in *exp. + * No floating-point exceptions are raised. + * If FLT_RADIX is 2 (or a power of 2), the returned value is exact, the current + rounding mode is ignored. + +.SH Notes + + On a binary system (where FLT_RADIX is 2), std::frexp may be implemented as + + { + *exp = (value == 0) ? 0 : (int)(1 + std::logb(value)); + return std::scalbn(value, -(*exp)); + } + + The function std::frexp, together with its dual, std::ldexp, can be used to + manipulate the representation of a floating-point number without direct bit + manipulations. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::frexp(num, exp) has the same effect as std::frexp(static_cast(num), + exp). + +.SH Example + + Compares different floating-point decomposition functions: + + +// Run this code + + #include + #include + #include + + int main() + { + double f = 123.45; + std::cout << "Given the number " << f << " or " << std::hexfloat + << f << std::defaultfloat << " in hex,\\n"; + + double f3; + double f2 = std::modf(f, &f3); + std::cout << "modf() makes " << f3 << " + " << f2 << '\\n'; + + int i; + f2 = std::frexp(f, &i); + std::cout << "frexp() makes " << f2 << " * 2^" << i << '\\n'; + + i = std::ilogb(f); + std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) + << " * " << std::numeric_limits::radix + << "^" << std::ilogb(f) << '\\n'; + } + +.SH Possible output: + + Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, + modf() makes 123 + 0.45 + frexp() makes 0.964453 * 2^7 + logb()/ilogb() make 1.92891 * 2^6 + +.SH See also + + ldexp + ldexpf multiplies a number by 2 raised to an integral power + ldexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + logb + logbf + logbl extracts exponent of the number + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ilogb + ilogbf + ilogbl extracts exponent of the number + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + modf + modff decomposes a number into integer and fractional parts + modfl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + frexp diff --git a/man/std::frexp.3 b/man/std::frexp.3 deleted file mode 100644 index a212fcda5..000000000 --- a/man/std::frexp.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::frexp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float frexp( float arg, int* exp ); - double frexp( double arg, int* exp ); - long double frexp( long double arg, int* exp ); - double frexp( Integral arg, int* exp ); \fI(since C++11)\fP - - Decomposes given floating point value to significand and exponent. - -.SH Parameters - - arg - floating point value - exp - pointer to integer value to store the exponent to - -.SH Return value - - Significand of the given floating point number in the range of [0.5; 1). The - exponent is put into integer value pointed to by exp. - -.SH See also - - ldexp multiplies a number by 2 raised to a power - \fI(function)\fP - logb extracts exponent of the number - \fI(C++11)\fP \fI(function)\fP - ilogb extracts exponent of the number - \fI(C++11)\fP \fI(function)\fP - modf decomposes a number into integer and fractional parts - \fI(function)\fP diff --git a/man/std::from_chars.3 b/man/std::from_chars.3 new file mode 100644 index 000000000..9660a39fa --- /dev/null +++ b/man/std::from_chars.3 @@ -0,0 +1,205 @@ +.TH std::from_chars 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::from_chars \- std::from_chars + +.SH Synopsis + Defined in header + std::from_chars_result + + from_chars( const char* first, const char* last, \fB(1)\fP \fI(since C++17)\fP + (constexpr since C++23) + /* integer-type */& value, int base = 10 + ); + std::from_chars_result + + from_chars( const char* first, const char* last, + /* floating-point-type */& value, \fB(2)\fP \fI(since C++17)\fP + + std::chars_format fmt = + std::chars_format::general ); + + Analyzes the character sequence [first, last) for a pattern described below. If no + characters match the pattern or if the value obtained by parsing the matched + characters is not representable in the type of value, value is unmodified, otherwise + the characters matching the pattern are interpreted as a text representation of an + arithmetic value, which is stored in value. + + 1) Integer parsers: Expects the pattern identical to the one used by std::strtol in + the default ("C") locale and the given non-zero numeric base, except that + * "0x" or "0X" prefixes are not recognized if base is 16 + * only the minus sign is recognized (not the plus sign), and only for signed + integer types of value + * leading whitespace is not ignored. + The library provides overloads for all + cv-unqualified + (since C++23) signed and unsigned integer types and char as the referenced type of + the parameter value. + 2) Floating-point parsers: Expects the pattern identical to the one used by + std::strtod in the default ("C") locale, except that + * the plus sign is not recognized outside of the exponent (only the minus sign is + permitted at the beginning) + * if fmt has std::chars_format::scientific set but not std::chars_format::fixed, + the exponent part is required (otherwise it is optional) + * if fmt has std::chars_format::fixed set but not std::chars_format::scientific, + the optional exponent is not permitted + * if fmt is std::chars_format::hex, the prefix "0x" or "0X" is not permitted (the + string "0x123" parses as the value "0" with unparsed remainder "x123") + * leading whitespace is not ignored. + In any case, the resulting value is one of at most two floating-point values closest + to the value of the string matching the pattern, after rounding according to + std::round_to_nearest. + The library provides overloads for all cv-unqualified + standard + (until C++23) floating-point types as the referenced type of the parameter value. + +.SH Parameters + + first, last - valid character range to parse + value - the out-parameter where the parsed value is stored if successful + base - integer base to use: a value between 2 and 36 (inclusive). + fmt - floating-point formatting to use, a bitmask of type std::chars_format + +.SH Return value + + On success, returns a value of type std::from_chars_result such that ptr points at + the first character not matching the pattern, or has the value equal to last if all + characters match and ec is value-initialized. + + If there is no pattern match, returns a value of type std::from_chars_result such + that ptr equals first and ec equals std::errc::invalid_argument. value is + unmodified. + + If the pattern was matched, but the parsed value is not in the range representable + by the type of value, returns value of type std::from_chars_result such that ec + equals std::errc::result_out_of_range and ptr points at the first character not + matching the pattern. value is unmodified. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + Unlike other parsing functions in C++ and C libraries, std::from_chars is + locale-independent, non-allocating, and non-throwing. Only a small subset of parsing + policies used by other libraries (such as std::sscanf) is provided. This is intended + to allow the fastest possible implementation that is useful in common + high-throughput contexts such as text-based interchange (JSON or XML). + + The guarantee that std::from_chars can recover every floating-point value formatted + by std::to_chars exactly is only provided if both functions are from the same + implementation. + + A pattern consisting of a sign with no digits following it is treated as pattern + that did not match anything. + + Feature-test macro Value Std Feature + 201611L \fI(C++17)\fP Elementary string conversions + __cpp_lib_to_chars (std::from_chars, std::to_chars) + 202306L (C++26) Testing for success or failure of + functions + Add constexpr modifiers to + __cpp_lib_constexpr_charconv 202207L (C++23) std::from_chars and std::to_chars + overloads for integral types + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + for (std::string_view const str : {"1234", "15 foo", "bar", " 42", "5000000000"}) + { + std::cout << "String: " << std::quoted(str) << ". "; + int result{}; + auto [ptr, ec] = std::from_chars(str.data(), str.data() + str.size(), result); + + if (ec == std::errc()) + std::cout << "Result: " << result << ", ptr -> " << std::quoted(ptr) << '\\n'; + else if (ec == std::errc::invalid_argument) + std::cout << "This is not a number.\\n"; + else if (ec == std::errc::result_out_of_range) + std::cout << "This number is larger than an int.\\n"; + } + + // C++23's constexpr from_char demo / C++26's operator bool() demo: + auto to_int = [](std::string_view s) -> std::optional + { + int value{}; + #if __cpp_lib_to_chars >= 202306L + if (std::from_chars(s.data(), s.data() + s.size(), value)) + #else + if (std::from_chars(s.data(), s.data() + s.size(), value).ec == std::errc{}) + #endif + return value; + else + return std::nullopt; + }; + + assert(to_int("42") == 42); + assert(to_int("foo") == std::nullopt); + #if __cpp_lib_constexpr_charconv and __cpp_lib_optional >= 202106 + static_assert(to_int("42") == 42); + static_assert(to_int("foo") == std::nullopt); + #endif + } + +.SH Output: + + String: "1234". Result: 1234, ptr -> "" + String: "15 foo". Result: 15, ptr -> " foo" + String: "bar". This is not a number. + String: " 42". This is not a number. + String: "5000000000". This number is larger than an int. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2955 C++17 this function was in and used moved to and + std::error_code uses std::errc + LWG 3373 C++17 std::from_chars_result might have additional members are + additional members prohibited + +.SH See also + + from_chars_result the return type of std::from_chars + \fI(C++17)\fP \fI(class)\fP + to_chars converts an integer or floating-point value to a character + \fI(C++17)\fP sequence + \fI(function)\fP + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stof + stod + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + strtol converts a byte string to an integer value + strtoll \fI(function)\fP + \fI(C++11)\fP + strtof converts a byte string to a floating-point value + strtod \fI(function)\fP + strtold + scanf reads formatted input from stdin, a file stream or a buffer + fscanf \fI(function)\fP + sscanf + extracts formatted data + operator>> \fI(public member function of std::basic_istream)\fP + diff --git a/man/std::from_chars_result.3 b/man/std::from_chars_result.3 new file mode 100644 index 000000000..2fe911d4a --- /dev/null +++ b/man/std::from_chars_result.3 @@ -0,0 +1,82 @@ +.TH std::from_chars_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::from_chars_result \- std::from_chars_result + +.SH Synopsis + Defined in header + struct from_chars_result; \fI(since C++17)\fP + + std::from_chars_result is the return type of std::from_chars. It has no base + classes, and only has the following members. + +.SH Notes + + Feature-test macro Value Std Feature + 201611L \fI(C++17)\fP Elementary string conversions (std::to_chars, + __cpp_lib_to_chars std::from_chars) + 202306L (C++26) Testing for success or failure of + functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + for (std::string_view const str : {"1234", "15 foo", "bar", " 42", "5000000000"}) + { + std::cout << "String: " << std::quoted(str) << ". "; + int result{}; + auto [ptr, ec] = std::from_chars(str.data(), str.data() + str.size(), result); + + if (ec == std::errc()) + std::cout << "Result: " << result << ", ptr -> " << std::quoted(ptr) << '\\n'; + else if (ec == std::errc::invalid_argument) + std::cout << "This is not a number.\\n"; + else if (ec == std::errc::result_out_of_range) + std::cout << "This number is larger than an int.\\n"; + } + + // C++23's constexpr from_char demo / C++26's operator bool() demo: + auto to_int = [](std::string_view s) -> std::optional + { + int value{}; + #if __cpp_lib_to_chars >= 202306L + if (std::from_chars(s.data(), s.data() + s.size(), value)) + #else + if (std::from_chars(s.data(), s.data() + s.size(), value).ec == std::errc{}) + #endif + return value; + else + return std::nullopt; + }; + + assert(to_int("42") == 42); + assert(to_int("foo") == std::nullopt); + #if __cpp_lib_constexpr_charconv and __cpp_lib_optional >= 202106 + static_assert(to_int("42") == 42); + static_assert(to_int("foo") == std::nullopt); + #endif + } + +.SH Output: + + String: "1234". Result: 1234, ptr -> "" + String: "15 foo". Result: 15, ptr -> " foo" + String: "bar". This is not a number. + String: " 42". This is not a number. + String: "5000000000". This number is larger than an int. + +.SH See also + + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::from_range,std::from_range_t.3 b/man/std::from_range,std::from_range_t.3 new file mode 100644 index 000000000..330f14555 --- /dev/null +++ b/man/std::from_range,std::from_range_t.3 @@ -0,0 +1,110 @@ +.TH std::from_range,std::from_range_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::from_range,std::from_range_t \- std::from_range,std::from_range_t + +.SH Synopsis + Defined in header + struct from_range_t { explicit from_range_t() = default; }; (since C++23) + inline constexpr std::from_range_t from_range {}; (since C++23) + + std::from_range is a disambiguation tag that can be passed to the constructors of + the suitable containers to indicate that the contained member is range constructed. + + The corresponding type std::from_range_t can be used in the constructor's parameter + list to match the intended tag. + +.SH Standard library + + The following standard library types use std::from_range_t type in their + constructors: + +.SH Containers library + constructor constructs the vector from a range + (C++23) \fI(public member function of std::vector)\fP + constructor constructs the deque from a range + (C++23) \fI(public member function of std::deque)\fP + constructor constructs the forward_list from a range + (C++23) \fI(public member function of std::forward_list)\fP + constructor constructs the list from a range + (C++23) \fI(public member function of std::list)\fP + constructor constructs the set from a range + (C++23) \fI(public member function of std::set)\fP + constructor constructs the map from a range + (C++23) \fI(public member function of std::map)\fP + constructor constructs the multiset from a range + (C++23) \fI(public member function of std::multiset)\fP + constructor constructs the multimap from a range + (C++23) \fI(public member function of std::multimap)\fP + constructor constructs the unordered_set from a range + (C++23) \fI\fI(public member\fP function of\fP + std::unordered_set) + constructor constructs the unordered_map from a range + (C++23) \fI\fI(public member\fP function of\fP + std::unordered_map) + constructor constructs the unordered_multiset from a range + (C++23) \fI\fI(public member\fP function of\fP + std::unordered_multiset) + constructor constructs the unordered_multimap from a range + (C++23) \fI\fI(public member\fP function of\fP + std::unordered_multimap) + constructor constructs the priority_queue from a range + (C++23) \fI(public member function of std::priority_queue)\fP + constructor constructs the queue from a range + (C++23) \fI(public member function of std::queue)\fP + constructor constructs the stack from a range + (C++23) \fI(public member function of std::stack)\fP + constructor constructs the flat_set from a range + (C++23) \fI(public member function of std::flat_set)\fP + constructor constructs the flat_map from a range + (C++23) \fI\fI(public member\fP function of\fP + std::flat_map) + constructor constructs the flat_multiset from a range + (C++23) \fI\fI(public member\fP function of\fP + std::flat_multiset) + constructor constructs the flat_multimap from a range + (C++23) \fI\fI(public member\fP function of\fP + std::flat_multimap) +.SH Strings library + constructor constructs the basic_string from a range + (C++23) \fI(public member function of std::basic_string)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructors to construct from + container compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + #ifdef __cpp_lib_containers_ranges + auto const range = {0x43, 43, 43}; + std::string str{std::from_range, range}; // uses tagged constructor + assert(str == "C++"); + #endif + } + +.SH See also + + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP + sorted_equivalent indicates that elements of a range are sorted (uniqueness is not + sorted_equivalent_t required) + (C++23) (tag) + sorted_unique indicates that elements of a range are sorted and unique + sorted_unique_t (tag) + (C++23) + ranges::to constructs a new non-view object from an input range + (C++23) \fI(function template)\fP diff --git a/man/std::front_insert_iterator.3 b/man/std::front_insert_iterator.3 index d3851bfbe..56dd1c4a6 100644 --- a/man/std::front_insert_iterator.3 +++ b/man/std::front_insert_iterator.3 @@ -1,68 +1,84 @@ -.TH std::front_insert_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::front_insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::front_insert_iterator \- std::front_insert_iterator + .SH Synopsis Defined in header template< class Container > - class front_insert_iterator : public std::iterator< std::output_iterator_tag, + class front_insert_iterator \fI(until C++17)\fP - void,void,void,void > + : public std::iterator + template< class Container > \fI(since C++17)\fP + class front_insert_iterator; - std::front_insert_iterator is an output iterator that prepends elements to a + std::front_insert_iterator is a LegacyOutputIterator that prepends elements to a container for which it was constructed. The container's push_front() member function is called whenever the iterator (whether dereferenced or not) is assigned to. Incrementing the std::front_insert_iterator is a no-op. .SH Member types - Member type Definition - container_type Container + Member type Definition + iterator_category std::output_iterator_tag + value_type void + difference_type void \fI(until C++20)\fP + std::ptrdiff_t \fI(since C++20)\fP + pointer void + reference void + container_type Container + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. .SH Member functions constructor constructs a new front_insert_iterator - \fI(public member function)\fP + \fI(public member function)\fP operator= inserts an object into the associated container - \fI(public member function)\fP + \fI(public member function)\fP operator* no-op - \fI(public member function)\fP + \fI(public member function)\fP operator++ no-op - operator++(int) \fI(public member function)\fP + operator++(int) \fI(public member function)\fP .SH Member objects Member name Definition container (protected) a pointer of type Container* -Inherited from std::iterator - -.SH Member types - - Member type Definition - value_type void - difference_type void - pointer void - reference void - iterator_category std::output_iterator_tag - .SH Example - + // Run this code - #include + #include #include #include #include - #include + #include + + namespace stb + { + void println(auto, auto const& d) + { + std::ranges::copy(d, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + } + int main() { - std::vector v{1,2,3,4,5}; + std::vector v{1, 2, 3, 4, 5}; std::deque d; + std::copy(v.begin(), v.end(), - std::front_insert_iterator>(d)); // or std::front_inserter(d) - for(int n : d) - std::cout << n << ' '; - std::cout << '\\n'; + std::front_insert_iterator>(d)); + // or std::front_inserter(d) + + stb::println("{}", d); } .SH Output: @@ -73,8 +89,8 @@ Inherited from std::iterator creates a std::front_insert_iterator of type inferred from the front_inserter argument - \fI(function template)\fP + \fI(function template)\fP back_insert_iterator iterator adaptor for insertion at the end of a container - \fI(class template)\fP + \fI(class template)\fP insert_iterator iterator adaptor for insertion into a container - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::front_insert_iterator::front_insert_iterator.3 b/man/std::front_insert_iterator::front_insert_iterator.3 index 38789487f..d7c19ee54 100644 --- a/man/std::front_insert_iterator::front_insert_iterator.3 +++ b/man/std::front_insert_iterator::front_insert_iterator.3 @@ -1,9 +1,23 @@ -.TH std::front_insert_iterator::front_insert_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::front_insert_iterator::front_insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::front_insert_iterator::front_insert_iterator \- std::front_insert_iterator::front_insert_iterator + .SH Synopsis - explicit front_insert_iterator( Container& c ); + explicit front_insert_iterator( Container& c ); \fI(until C++20)\fP + constexpr explicit front_insert_iterator( Container& c ); \fI(since C++20)\fP - Initializes the underlying pointer to the container to &c . + Initializes the underlying pointer to the container to std::addressof(c). .SH Parameters c - container to initialize the inserter with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + default constructor was provided as removed along with the + P2325R3 C++20 C++20 requirement + iterators must be default_initializable diff --git a/man/std::front_insert_iterator::operator*.3 b/man/std::front_insert_iterator::operator*.3 index 75740db9f..451df40a5 100644 --- a/man/std::front_insert_iterator::operator*.3 +++ b/man/std::front_insert_iterator::operator*.3 @@ -1,9 +1,13 @@ -.TH std::front_insert_iterator::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::front_insert_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::front_insert_iterator::operator* \- std::front_insert_iterator::operator* + .SH Synopsis - front_insert_iterator& operator*(); + front_insert_iterator& operator*(); \fI(until C++20)\fP + constexpr front_insert_iterator& operator*(); \fI(since C++20)\fP Does nothing, this member function is provided to satisfy the requirements of - OutputIterator. + LegacyOutputIterator. It returns the iterator itself, which makes it possible to use code such as *iter = value to output (insert) the value into the underlying container. diff --git a/man/std::front_insert_iterator::operator++.3 b/man/std::front_insert_iterator::operator++.3 index 3d62f29ea..83506fa1d 100644 --- a/man/std::front_insert_iterator::operator++.3 +++ b/man/std::front_insert_iterator::operator++.3 @@ -1,10 +1,15 @@ -.TH std::front_insert_iterator::operator++ 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::front_insert_iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::front_insert_iterator::operator++ \- std::front_insert_iterator::operator++ + .SH Synopsis - front_insert_iterator& operator++(); - front_insert_iterator& operator++( int ); + front_insert_iterator& operator++(); \fI(until C++20)\fP + constexpr front_insert_iterator& operator++(); \fI(since C++20)\fP + front_insert_iterator operator++( int ); \fI(until C++20)\fP + constexpr front_insert_iterator operator++( int ); \fI(since C++20)\fP Does nothing. These operator overloads are provided to satisfy the requirements of - OutputIterator. They make it possible for the expressions *iter++=value and + LegacyOutputIterator. They make it possible for the expressions *iter++=value and *++iter=value to be used to output (insert) a value into the underlying container. .SH Parameters diff --git a/man/std::front_insert_iterator::operator=.3 b/man/std::front_insert_iterator::operator=.3 index 2837c1cf9..4b8ff8ef6 100644 --- a/man/std::front_insert_iterator::operator=.3 +++ b/man/std::front_insert_iterator::operator=.3 @@ -1,14 +1,28 @@ -.TH std::front_insert_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::front_insert_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::front_insert_iterator::operator= \- std::front_insert_iterator::operator= + .SH Synopsis - front_insert_iterator& \fB(1)\fP - operator=( const typename Container::value_type& value ); - front_insert_iterator& \fB(2)\fP - operator=( typename Container::value_type&& value ); + front_insert_iterator& + operator=( typename \fI(until C++11)\fP + Container::const_reference value ); + front_insert_iterator& \fI(since C++11)\fP + operator=( const typename \fI(until C++20)\fP + Container::value_type& value ); + constexpr front_insert_iterator& + operator=( const typename \fB(1)\fP \fI(since C++20)\fP + Container::value_type& value ); + front_insert_iterator& \fI(since C++11)\fP + operator=( typename Container::value_type&& \fI(until C++20)\fP + value ); \fB(2)\fP + constexpr front_insert_iterator& + operator=( typename Container::value_type&& \fI(since C++20)\fP + value ); Inserts the given value value to the container. - 1) Results in container->push_front(value) - 2) Results in container->push_front(std::move(value)) + 1) Results in container->push_front(value). + 2) Results in container->push_front(std::move(value)). .SH Parameters @@ -20,8 +34,26 @@ .SH Example - This section is incomplete -.SH Category: +// Run this code + + #include + #include + #include + + int main() + { + std::deque q; + std::front_insert_iterator> it(q); + + for (int i = 0; i < 10; ++i) + it = i; // calls q.push_front(i) + + for (auto& elem : q) + std::cout << elem << ' '; + std::cout << '\\n'; + } + +.SH Output: - * Todo without reason + 9 8 7 6 5 4 3 2 1 0 diff --git a/man/std::front_inserter.3 b/man/std::front_inserter.3 index 75778c7e9..b900219e0 100644 --- a/man/std::front_inserter.3 +++ b/man/std::front_inserter.3 @@ -1,8 +1,12 @@ -.TH std::front_inserter 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::front_inserter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::front_inserter \- std::front_inserter + .SH Synopsis Defined in header - template< class Container > - std::front_insert_iterator front_inserter( Container& c ); + template< class Container > (constexpr since + std::front_insert_iterator front_inserter( Container& c C++20) + ); front_inserter is a convenience function template that constructs a std::front_insert_iterator for the container c with the type deduced from the type @@ -15,11 +19,11 @@ .SH Return value A std::front_insert_iterator which can be used to add elements to the beginning of - the container c + the container c. .SH Possible implementation - template< class Container > + template std::front_insert_iterator front_inserter( Container& c ) { return std::front_insert_iterator(c); @@ -27,33 +31,36 @@ .SH Example - + // Run this code - #include - #include #include + #include + #include #include - + #include + int main() { - std::deque v{1,2,3,4,5,6,7,8,9,10}; - std::fill_n(std::front_inserter(v), 3, -1); - for (int n : v) + std::vector v{1, 2, 3, 4, 5}; + std::deque d; + std::copy(v.begin(), v.end(), std::front_inserter(d)); + for (int n : d) std::cout << n << ' '; + std::cout << '\\n'; } .SH Output: - -1 -1 -1 1 2 3 4 5 6 7 8 9 10 + 5 4 3 2 1 .SH See also front_insert_iterator iterator adaptor for insertion at the front of a container - \fI(class template)\fP + \fI(class template)\fP creates a std::back_insert_iterator of type inferred from the back_inserter argument - \fI(function template)\fP + \fI(function template)\fP creates a std::insert_iterator of type inferred from the inserter argument - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::fseek.3 b/man/std::fseek.3 index b3e631d18..c61d67bbe 100644 --- a/man/std::fseek.3 +++ b/man/std::fseek.3 @@ -1,4 +1,7 @@ -.TH std::fseek 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fseek 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fseek \- std::fseek + .SH Synopsis Defined in header int fseek( std::FILE* stream, long offset, int origin ); @@ -8,11 +11,17 @@ If the stream is open in binary mode, the new position is exactly offset bytes measured from the beginning of the file if origin is SEEK_SET, from the current file position if origin is SEEK_CUR, and from the end of the file if origin is SEEK_END. - Some binary streams may not support the SEEK_END. + Binary streams are not required to support SEEK_END, in particular if additional + null bytes are output. If the stream is open in text mode, the only supported values for offset are zero (which works with any origin) and a value returned by an earlier call to std::ftell - on a stream associated with the same file (which only works with origin of SEEK_SET. + on a stream associated with the same file (which only works with origin of + SEEK_SET). + + If the stream is wide-oriented, the restrictions of both text and binary streams + apply (result of std::ftell is allowed with SEEK_SET and zero offset is allowed from + SEEK_SET and SEEK_CUR, but not SEEK_END). In addition to changing the file position indicator, fseek undoes the effects of std::ungetc and clears the end-of-file status, if applicable. @@ -31,24 +40,66 @@ 0 upon success, nonzero value otherwise. +.SH Notes + + After seeking to a non-end position in a wide stream, the next call to any output + function may render the remainder of the file undefined, e.g. by outputting a + multibyte sequence of a different length. + + POSIX allows seeking beyond the existing end of file. If an output is performed + after this seek, any read from the gap will return zero bytes. Where supported by + the filesystem, this creates a sparse file. + + POSIX also requires that fseek first performs fflush if there are any unwritten data + (but whether the shift state is restored is implementation-defined). The standard + C++ file streams guarantee both flushing and unshifting: + std::basic_filebuf::seekoff. + + POSIX specifies, that fseek should return -1 on error, and set errno to indicate the + error. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::ofstream("dummy.nfo") << "8 bytes\\n"; // create the file + + std::FILE* fp = std::fopen("dummy.nfo", "rb"); + assert(fp); + + std::fseek(fp, 0, SEEK_END); // seek to end + const std::size_t filesize = std::ftell(fp); + std::vector buffer(filesize); + + std::fseek(fp, 0, SEEK_SET); // seek to start + std::fread(buffer.data(), sizeof(std::uint8_t), buffer.size(), fp); + + std::fclose(fp); + std::printf("I've read %zi bytes\\n", filesize); + } + +.SH Possible output: + + I've read 8 bytes .SH See also fsetpos moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP fgetpos gets the file position indicator - \fI(function)\fP + \fI(function)\fP ftell returns the current file position indicator - \fI(function)\fP + \fI(function)\fP rewind moves the file position indicator to the beginning in a file - \fI(function)\fP + \fI(function)\fP C documentation for fseek - -.SH Category: - - * Todo no example diff --git a/man/std::fsetpos.3 b/man/std::fsetpos.3 index d382501ac..d2d6ce9ec 100644 --- a/man/std::fsetpos.3 +++ b/man/std::fsetpos.3 @@ -1,4 +1,7 @@ -.TH std::fsetpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fsetpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fsetpos \- std::fsetpos + .SH Synopsis Defined in header int fsetpos( std::FILE* stream, const std::fpos_t* pos ); @@ -9,7 +12,7 @@ Besides establishing new parse state and position, a call to this function undoes the effects of std::ungetc and clears the end-of-file state, if it is set. - If a read or write error occurs, the error indicator (std::ferror)for the stream is + If a read or write error occurs, the error indicator (std::ferror) for the stream is set. .SH Parameters @@ -22,13 +25,76 @@ 0 upon success, nonzero value otherwise. Also, sets errno on failure. +.SH Notes + + After seeking to a non-end position in a wide stream, the next call to any output + function may render the remainder of the file undefined, e.g. by outputting a + multibyte sequence of a different length. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Prepare an array of floating-point values. + const int SIZE = 5; + double A[SIZE] = {1., 2., 3., 4., 5.}; + // Write array to a file. + std::FILE * fp = std::fopen("test.bin", "wb"); + std::fwrite(A, sizeof(double), SIZE, fp); + std::fclose(fp); + + // Read the values into array B. + double B[SIZE]; + fp = std::fopen("test.bin", "rb"); + std::fpos_t pos; + if (std::fgetpos(fp, &pos) != 0) // current position: start of file + { + std::perror("fgetpos()"); + std::fprintf(stderr, "fgetpos() failed in file %s at line # %d\\n", + __FILE__, __LINE__-3); + std::exit(EXIT_FAILURE); + } + + int ret_code = std::fread(B, sizeof(double), 1, fp); // read one value + // current position: after reading one value + std::printf("%.1f; read count = %d\\n", B[0], ret_code); // print one value and ret_code + + if (std::fsetpos(fp, &pos) != 0) // reset current position to start of file + { + if (std::ferror(fp)) + { + std::perror("fsetpos()"); + std::fprintf(stderr, "fsetpos() failed in file %s at line # %d\\n", + __FILE__, __LINE__-5); + std::exit(EXIT_FAILURE); + } + } + + ret_code = std::fread(B, sizeof(double), 1, fp); // re-read first value + std::printf("%.1f; read count = %d\\n", B[0], ret_code); // print one value and ret_code + std::fclose(fp); + + return EXIT_SUCCESS; + } + +.SH Output: + + 1.0; read count = 1 + 1.0; read count = 1 + .SH See also fgetpos gets the file position indicator - \fI(function)\fP + \fI(function)\fP ftell returns the current file position indicator - \fI(function)\fP + \fI(function)\fP fseek moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP C documentation for fsetpos diff --git a/man/std::fstream.3 b/man/std::fstream.3 deleted file mode 120000 index 47d3c081d..000000000 --- a/man/std::fstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream.3 \ No newline at end of file diff --git a/man/std::fstream.3 b/man/std::fstream.3 new file mode 100644 index 000000000..1cf5a4b01 --- /dev/null +++ b/man/std::fstream.3 @@ -0,0 +1,366 @@ +.TH std::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream \- std::basic_fstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_fstream : public std::basic_iostream + + The class template basic_fstream implements high-level input/output operations on + file based streams. It interfaces a file-based streambuffer (std::basic_filebuf) + with the high-level interface of (std::basic_iostream). + + A typical implementation of std::basic_fstream holds only one non-derived data + member: an instance of std::basic_filebuf. + + std-basic fstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::fstream std::basic_fstream + std::wfstream std::basic_fstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + + constructor constructs the file stream + \fI(public member function)\fP + destructor destructs the basic_fstream and the associated + \fB[virtual]\fP (implicitly declared) buffer, closes the file + \fI(virtual public member function)\fP + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw file device object + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP +.SH File operations + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_fstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename{"test.bin"}; + std::fstream s{filename, s.binary | s.trunc | s.in | s.out}; + + if (!s.is_open()) + std::cout << "failed to open " << filename << '\\n'; + else + { + // write + double d{3.14}; + s.write(reinterpret_cast(&d), sizeof d); // binary output + s << 123 << "abc"; // text output + + // for fstream, this moves the file position pointer (both put and get) + s.seekp(0); + + // read + d = 2.71828; + s.read(reinterpret_cast(&d), sizeof d); // binary input + int n; + std::string str; + if (s >> n >> str) // text input + std::cout << "read back from file: " << d << ' ' << n << ' ' << str << '\\n'; + } + } + +.SH Output: + + read back from file: 3.14 123 abc + +.SH See also + + getline read data from an I/O stream into a string + \fI(function template)\fP diff --git a/man/std::fstream::basic_fstream.3 b/man/std::fstream::basic_fstream.3 deleted file mode 120000 index 4401b4547..000000000 --- a/man/std::fstream::basic_fstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::basic_fstream.3 \ No newline at end of file diff --git a/man/std::fstream::basic_fstream.3 b/man/std::fstream::basic_fstream.3 new file mode 100644 index 000000000..d3641c529 --- /dev/null +++ b/man/std::fstream::basic_fstream.3 @@ -0,0 +1,111 @@ +.TH std::basic_fstream::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::basic_fstream \- std::basic_fstream::basic_fstream + +.SH Synopsis + basic_fstream(); \fB(1)\fP + explicit basic_fstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::filesystem::path::value_type* + filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in | + std::ios_base::out ); + template< class FsPath > + + explicit basic_fstream( const FsPath& filename, + std::ios_base::openmode mode \fB(5)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + basic_fstream( basic_fstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_fstream( const basic_fstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_fstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::fstream f0; + std::fstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::fstream f2(name); + std::fstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default argument of mode in overload + LWG 460 C++98 (2) added + was missing (it is present in the synopsis) + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_iostream)\fP diff --git a/man/std::fstream::close.3 b/man/std::fstream::close.3 deleted file mode 120000 index f7405b513..000000000 --- a/man/std::fstream::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::close.3 \ No newline at end of file diff --git a/man/std::fstream::close.3 b/man/std::fstream::close.3 new file mode 100644 index 000000000..8b47101e3 --- /dev/null +++ b/man/std::fstream::close.3 @@ -0,0 +1,70 @@ +.TH std::basic_fstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::close \- std::basic_fstream::close + +.SH Synopsis + void close(); + + Closes the associated file. + + Effectively calls rdbuf()->close(). If an error occurs during operation, + setstate(failbit) is called. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called by the destructor of basic_fstream when the stream object + goes out of scope and is not usually invoked directly. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::fstream f1("example1", std::ios::out), + f2("example2", std::ios::out), + f3("example3", std::ios::out); + + std::cout << std::boolalpha + << f1.is_open() << '\\n' + << f2.is_open() << '\\n' + << f3.is_open() << '\\n'; + + f1.close(); + f2.close(); + + std::cout << f1.is_open() << '\\n' + << f2.is_open() << '\\n' + << f3.is_open() << '\\n'; + } + +.SH Possible output: + + true + true + true + false + false + true + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::fstream::fstream.3 b/man/std::fstream::fstream.3 deleted file mode 120000 index 4401b4547..000000000 --- a/man/std::fstream::fstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::basic_fstream.3 \ No newline at end of file diff --git a/man/std::fstream::fstream.3 b/man/std::fstream::fstream.3 new file mode 100644 index 000000000..d3641c529 --- /dev/null +++ b/man/std::fstream::fstream.3 @@ -0,0 +1,111 @@ +.TH std::basic_fstream::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::basic_fstream \- std::basic_fstream::basic_fstream + +.SH Synopsis + basic_fstream(); \fB(1)\fP + explicit basic_fstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::filesystem::path::value_type* + filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in | + std::ios_base::out ); + template< class FsPath > + + explicit basic_fstream( const FsPath& filename, + std::ios_base::openmode mode \fB(5)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + basic_fstream( basic_fstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_fstream( const basic_fstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_fstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::fstream f0; + std::fstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::fstream f2(name); + std::fstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default argument of mode in overload + LWG 460 C++98 (2) added + was missing (it is present in the synopsis) + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_iostream)\fP diff --git a/man/std::fstream::is_open.3 b/man/std::fstream::is_open.3 deleted file mode 120000 index d699f38b4..000000000 --- a/man/std::fstream::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::is_open.3 \ No newline at end of file diff --git a/man/std::fstream::is_open.3 b/man/std::fstream::is_open.3 new file mode 100644 index 000000000..39cb27b98 --- /dev/null +++ b/man/std::fstream::is_open.3 @@ -0,0 +1,65 @@ +.TH std::basic_fstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::is_open \- std::basic_fstream::is_open + +.SH Synopsis + bool is_open() const; + + Checks if the file stream has an associated file. + + Effectively calls rdbuf()->is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the file stream has an associated file, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "some_file"; + + std::fstream fs(filename, std::ios::in); + + std::cout << std::boolalpha; + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + + if (!fs.is_open()) + { + fs.clear(); + fs.open(filename, std::ios::out); + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + } + } + +.SH Possible output: + + fs.is_open() = false + fs.is_open() = true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP diff --git a/man/std::fstream::native_handle.3 b/man/std::fstream::native_handle.3 new file mode 100644 index 000000000..48601a86f --- /dev/null +++ b/man/std::fstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_fstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::native_handle \- std::basic_fstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::fstream::open.3 b/man/std::fstream::open.3 deleted file mode 120000 index 0cec9a126..000000000 --- a/man/std::fstream::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::open.3 \ No newline at end of file diff --git a/man/std::fstream::open.3 b/man/std::fstream::open.3 new file mode 100644 index 000000000..ada1a2dfe --- /dev/null +++ b/man/std::fstream::open.3 @@ -0,0 +1,107 @@ +.TH std::basic_fstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::open \- std::basic_fstream::open + +.SH Synopsis + void open( const char* filename, + + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::filesystem::path& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP + + = std::ios_base::in | std::ios_base::out ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode) (see std::basic_filebuf::open + for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. It is a BitmaskType, the following constants + are defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "example.123"; + + std::fstream fs; + fs.open(filename); + + if (!fs.is_open()) + { + fs.clear(); + fs.open(filename, std::ios::out); // create file + fs.close(); + fs.open(filename); + } + + std::cout << std::boolalpha; + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + std::cout << "fs.good() = " << fs.good() << '\\n'; + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + LWG 460 C++98 the default argument of mode in overload (1) added + was missing (it is present in the synopsis) + + 1. ↑ The resolution of LWG issue #22 is overriden. + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::fstream::operator=.3 b/man/std::fstream::operator=.3 deleted file mode 120000 index 731a08752..000000000 --- a/man/std::fstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::operator=.3 \ No newline at end of file diff --git a/man/std::fstream::operator=.3 b/man/std::fstream::operator=.3 new file mode 100644 index 000000000..31af32e71 --- /dev/null +++ b/man/std::fstream::operator=.3 @@ -0,0 +1,37 @@ +.TH std::basic_fstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::operator= \- std::basic_fstream::operator= + +.SH Synopsis + basic_fstream& operator=( basic_fstream&& other ); \fI(since C++11)\fP + + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_iostream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. + +.SH Parameters + + other - file stream to move + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::fstream::rdbuf.3 b/man/std::fstream::rdbuf.3 deleted file mode 120000 index acf3172d0..000000000 --- a/man/std::fstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::fstream::rdbuf.3 b/man/std::fstream::rdbuf.3 new file mode 100644 index 000000000..50d1692f2 --- /dev/null +++ b/man/std::fstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_fstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::rdbuf \- std::basic_fstream::rdbuf + +.SH Synopsis + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP + + Returns pointer to the underlying raw file device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw file device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::fstream::swap.3 b/man/std::fstream::swap.3 deleted file mode 120000 index d88b5421c..000000000 --- a/man/std::fstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::swap.3 \ No newline at end of file diff --git a/man/std::fstream::swap.3 b/man/std::fstream::swap.3 new file mode 100644 index 000000000..2051eb906 --- /dev/null +++ b/man/std::fstream::swap.3 @@ -0,0 +1,81 @@ +.TH std::basic_fstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::swap \- std::basic_fstream::swap + +.SH Synopsis + void swap( basic_fstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_iostream::swap(other) and + rdbuf()->swap(other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" + +.SH See also + + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::ftell.3 b/man/std::ftell.3 index 651006cc3..6dda7cca8 100644 --- a/man/std::ftell.3 +++ b/man/std::ftell.3 @@ -1,4 +1,7 @@ -.TH std::ftell 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ftell 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ftell \- std::ftell + .SH Synopsis Defined in header long ftell( std::FILE* stream ); @@ -9,7 +12,7 @@ number of bytes from the beginning of the file. If the stream is open in text mode, the value returned by this function is - unspecified and is only meaningful as the input to std::fseek + unspecified and is only meaningful as the input to std::fseek. .SH Parameters @@ -22,24 +25,80 @@ .SH Example - This section is incomplete - Reason: no example + Demonstrates std::ftell() with error checking. Writes then reads a few + floating-point (FP) values to/from a file. + + +// Run this code + + #include + #include + #include + + // If the condition is not met then exit the program with error message. + void check(bool condition, const char* func, int line) + { + if (condition) + return; + std::perror(func); + std::cerr << func << " failed in file " << __FILE__ << " at line # " << line - 1 + << '\\n'; + std::exit(EXIT_FAILURE); + } + + int main() + { + // Prepare an array of FP values. + constexpr int SIZE {5}; + double A[SIZE] = {1.1, 2.2, 3.3, 4.4, 5.5}; + + // Write array to a file. + const char* fname = "/tmp/test.bin"; + FILE* file = std::fopen(fname, "wb"); + check(file != NULL, "fopen()", __LINE__); + + const int write_count = std::fwrite(A, sizeof(double), SIZE, file); + check(write_count == SIZE, "fwrite()", __LINE__); + + std::fclose(file); + + // Read the FP values into array B. + double B[SIZE]; + file = std::fopen(fname, "rb"); + check(file != NULL, "fopen()", __LINE__); + + long pos = std::ftell(file); // position indicator at start of file + check(pos != -1L, "ftell()", __LINE__); + std::cout << "pos: " << pos << '\\n'; + + const int read_count = std::fread(B, sizeof(double), 1, file); // read one FP value + check(read_count == 1, "fread()", __LINE__); + + pos = std::ftell(file); // position indicator after reading one FP value + check(pos != -1L, "ftell()", __LINE__); + std::cout << "pos: " << pos << '\\n'; + std::cout << "B[0]: " << B[0] << '\\n'; // print one FP value + + return EXIT_SUCCESS; + } + +.SH Possible output: + + pos: 0 + pos: 8 + B[0]: 1.1 .SH See also fgetpos gets the file position indicator - \fI(function)\fP + \fI(function)\fP fseek moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP fsetpos moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP C documentation for ftell - -.SH Category: - - * Todo no example diff --git a/man/std::full_extent,std::full_extent_t.3 b/man/std::full_extent,std::full_extent_t.3 new file mode 100644 index 000000000..843a2c261 --- /dev/null +++ b/man/std::full_extent,std::full_extent_t.3 @@ -0,0 +1,80 @@ +.TH std::full_extent,std::full_extent_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::full_extent,std::full_extent_t \- std::full_extent,std::full_extent_t + +.SH Synopsis + Defined in header + struct full_extent_t { explicit full_extent_t() = default; }; \fB(1)\fP (since C++26) + inline constexpr std::full_extent_t full_extent {}; \fB(2)\fP (since C++26) + + 1) The class std::full_extent_t is a slice specifier type that can be used in + std::submdspan. + 2) The corresponding std::full_extent instance of \fB(1)\fP is a slice specifier to + indicate full range of indices in the specified extent in std::submdspan. + +.SH Example + + +// Run this code + + #include + #include + + void print_view(auto view) + { + static_assert(view.rank() <= 2); + + if constexpr (view.rank() == 2) + { + for (std::size_t i = 0; i < view.extent(0); ++i) + { + for (std::size_t j = 0; j < view.extent(1); ++j) + std::print("{} ", view[i, j]); + std::println(""); + } + } + else if constexpr (view.rank() == 1) + { + for (std::size_t i = 0; i < view.extent(0); ++i) + std::print("{} ", view[i]); + std::println(""); + } + else + { + std::println("{}", view[]); + } + std::println(""); + } + + int main() + { + char letters [] { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I' }; + std::mdspan view (letters, 3, 3); + + print_view(view); + print_view(std::submdspan(view, std::full_extent, std::full_extent)); + print_view(std::submdspan(view, std::full_extent, 1)); + print_view(std::submdspan(view, 1, std::full_extent)); + print_view(std::submdspan(view, 2, 1)); + } + +.SH Possible output: + + A B C + D E F + G H I + + A B C + D E F + G H I + + B E H + + D E F + + H + +.SH See also + + submdspan returns a view of a subset of an existing mdspan + (C++26) \fI(function template)\fP diff --git a/man/std::function.3 b/man/std::function.3 index 8801841e5..edb90acc9 100644 --- a/man/std::function.3 +++ b/man/std::function.3 @@ -1,14 +1,19 @@ -.TH std::function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function \- std::function + .SH Synopsis Defined in header template< class > \fI(since C++11)\fP class function; /* undefined */ template< class R, class... Args > \fI(since C++11)\fP - class function + class function; Class template std::function is a general-purpose polymorphic function wrapper. - Instances of std::function can store, copy, and invoke any callable target -- - functions, lambda expressions, bind expressions, or other function objects. + Instances of std::function can store, copy, and invoke any CopyConstructible + Callable target -- functions (via pointers thereto), lambda expressions, bind + expressions, or other function objects, as well as pointers to member functions and + pointers to data members. The stored callable object is called the target of std::function. If a std::function contains no target, it is called empty. Invoking the target of an empty @@ -18,116 +23,172 @@ .SH Member types - Type Definition - result_type R - argument_type T if sizeof...(Args)==1 and T is the first and only type in - Args... - first_argument_type T1 if sizeof...(Args)==2 and T1 is the first of the two types - in Args... - second_argument_type T2 if sizeof...(Args)==2 and T2 is the second of the two types - in Args... + Type Definition + result_type R + argument_type(deprecated in C++17)(removed in T if sizeof...(Args)==1 and T is the + C++20) first and only type in Args... + first_argument_type(deprecated in T1 if sizeof...(Args)==2 and T1 is the + C++17)(removed in C++20) first of the two types in Args... + second_argument_type(deprecated in T2 if sizeof...(Args)==2 and T2 is the + C++17)(removed in C++20) second of the two types in Args... .SH Member functions - constructor constructs a new std::function instance - \fI(public member function)\fP - destructor destroys a std::function instance - \fI(public member function)\fP - operator= assigns a new target - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP - assign assigns a new target - \fI(public member function)\fP - operator bool checks if a valid target is contained - \fI(public member function)\fP - operator() invokes the target - \fI(public member function)\fP + constructor constructs a new std::function instance + \fI(public member function)\fP + destructor destroys a std::function instance + \fI(public member function)\fP + operator= assigns a new target + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + assign assigns a new target + (removed in C++17) \fI(public member function)\fP + operator bool checks if a target is contained + \fI(public member function)\fP + operator() invokes the target + \fI(public member function)\fP .SH Target access - target_type obtains the typeid of the stored target of a std::function - \fI(public member function)\fP - target obtains a pointer to the stored target of a std::function - \fI(public member function)\fP + target_type obtains the typeid of the stored target + \fI(public member function)\fP + target obtains a pointer to the stored target + \fI(public member function)\fP .SH Non-member functions std::swap(std::function) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP - operator== compares an std::function with std::nullptr - operator!= \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + operator== compares a std::function with nullptr + operator!= \fI(function template)\fP + (removed in C++20) .SH Helper classes std::uses_allocator specializes the std::uses_allocator type trait - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(until C++17)\fP \fI(class template specialization)\fP + + Deduction guides\fI(since C++17)\fP + +.SH Notes + + Care should be taken when a std::function, whose result type is a + reference, is initialized from a lambda expression without a + trailing-return-type. Due to the way auto deduction works, such lambda (until C++23) + expression will always return a prvalue. Hence, the resulting + reference will usually bind to a temporary whose lifetime ends when + std::function::operator() returns. + If a std::function returning a reference is initialized from a + function or function object returning a prvalue (including a lambda + expression without a trailing-return-type), the program is ill-formed (since C++23) + because binding the returned reference to a temporary object is + forbidden. + + std::function F([] { return 42; }); // Error since C++23: can't bind + // the returned reference to a temporary + int x = F(); // Undefined behavior until C++23: the result of F() is a dangling reference + + std::function G([]() -> int& { static int i{0x2A}; return i; }); // OK + + std::function H([i{052}] -> const int& { return i; }); // OK .SH Example - + // Run this code #include #include - - struct Foo { + + struct Foo + { Foo(int num) : num_(num) {} - void print_add(int i) const { std::cout << num_+i << '\\n'; } + void print_add(int i) const { std::cout << num_ + i << '\\n'; } int num_; }; - + void print_num(int i) { std::cout << i << '\\n'; } - - struct PrintNum { + + struct PrintNum + { void operator()(int i) const { std::cout << i << '\\n'; } }; - + int main() { // store a free function std::function f_display = print_num; f_display(-9); - + // store a lambda std::function f_display_42 = []() { print_num(42); }; f_display_42(); - + // store the result of a call to std::bind std::function f_display_31337 = std::bind(print_num, 31337); f_display_31337(); - + // store a call to a member function std::function f_add_display = &Foo::print_add; const Foo foo(314159); f_add_display(foo, 1); - + f_add_display(314159, 1); + + // store a call to a data member accessor + std::function f_num = &Foo::num_; + std::cout << "num_: " << f_num(foo) << '\\n'; + // store a call to a member function and object using std::placeholders::_1; - std::function f_add_display2= std::bind( &Foo::print_add, foo, _1 ); + std::function f_add_display2 = std::bind(&Foo::print_add, foo, _1); f_add_display2(2); - + + // store a call to a member function and object ptr + std::function f_add_display3 = std::bind(&Foo::print_add, &foo, _1); + f_add_display3(3); + // store a call to a function object std::function f_display_obj = PrintNum(); f_display_obj(18); + + auto factorial = [](int n) + { + // store a lambda object to emulate "recursive lambda"; aware of extra overhead + std::function fac = [&](int n) { return (n < 2) ? 1 : n * fac(n - 1); }; + // note that "auto fac = [&](int n) {...};" does not work in recursive calls + return fac(n); + }; + for (int i{5}; i != 8; ++i) + std::cout << i << "! = " << factorial(i) << "; "; + std::cout << '\\n'; } -.SH Output: +.SH Possible output: -9 42 31337 314160 + 314160 + num_: 314159 314161 + 314162 18 + 5! = 120; 6! = 720; 7! = 5040; .SH See also - bad_function_call the exception thrown when invoking an empty std::function - \fI(C++11)\fP \fI(class)\fP - mem_fn creates a function object out of a pointer to a member - \fI(C++11)\fP \fI(function template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + bad_function_call the exception thrown when invoking an empty std::function + \fI(C++11)\fP \fI(class)\fP + mem_fn creates a function object out of a pointer to a member + \fI(C++11)\fP \fI(function template)\fP + typeid queries information of a type, returning a std::type_info object + representing the type diff --git a/man/std::function::assign.3 b/man/std::function::assign.3 index b6ed9d041..77e7ebd9b 100644 --- a/man/std::function::assign.3 +++ b/man/std::function::assign.3 @@ -1,12 +1,15 @@ -.TH std::function::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::assign \- std::function::assign + .SH Synopsis template< class F, class Alloc > \fI(since C++11)\fP - void assign( F&& f, const Alloc& alloc ); + void assign( F&& f, const Alloc& alloc ); (removed in C++17) - Initializes the target with f. alloc is used to allocate memory for any internal + Initializes the target with f. The alloc is used to allocate memory for any internal data structures that the function might use. - Equivalent to function(allocator_arg, alloc, std::forward(f)).swap(*this) + Equivalent to function(std::allocator_arg, alloc, std::forward(f)).swap(*this);. .SH Parameters @@ -19,9 +22,9 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH See also operator= assigns a new target - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::function::function.3 b/man/std::function::function.3 index 539a58bb1..e12134c0d 100644 --- a/man/std::function::function.3 +++ b/man/std::function::function.3 @@ -1,73 +1,126 @@ -.TH std::function::function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::function \- std::function::function + .SH Synopsis - function(); \fB(1)\fP \fI(since C++11)\fP - function( std::nullptr_t ); \fB(2)\fP \fI(since C++11)\fP - function( const function& other ); \fB(3)\fP \fI(since C++11)\fP - function( function&& other ); \fB(4)\fP \fI(since C++11)\fP - template< class F > \fB(5)\fP \fI(since C++11)\fP - function( F f ); - template< class Alloc > \fB(6)\fP \fI(since C++11)\fP - function( std::allocator_arg_t, const Alloc& alloc ); + function() noexcept; \fB(1)\fP \fI(since C++11)\fP + function( std::nullptr_t ) noexcept; \fB(2)\fP \fI(since C++11)\fP + function( const function& other ); \fB(3)\fP \fI(since C++11)\fP + function( function&& other ); \fI(since C++11)\fP + \fI(until C++20)\fP + function( function&& other ) noexcept; \fI(since C++20)\fP + template< class F > \fB(5)\fP \fI(since C++11)\fP + function( F&& f ); + template< class Alloc > \fI(since C++11)\fP + function( std::allocator_arg_t, const Alloc& \fB(6)\fP (removed in C++17) + alloc ) noexcept; template< class Alloc > - function( std::allocator_arg_t, const Alloc& alloc, \fB(7)\fP \fI(since C++11)\fP + function( std::allocator_arg_t, const Alloc& \fB(7)\fP \fI(since C++11)\fP + alloc, (removed in C++17) - std::nullptr_t ); - template< class Alloc > + std::nullptr_t ) noexcept; + template< class Alloc > \fB(4)\fP - function( std::allocator_arg_t, const Alloc& alloc, \fB(8)\fP \fI(since C++11)\fP + function( std::allocator_arg_t, const Alloc& \fB(8)\fP \fI(since C++11)\fP + alloc, (removed in C++17) const function& other ); template< class Alloc > - function( std::allocator_arg_t, const Alloc& alloc, \fB(9)\fP \fI(since C++11)\fP + function( std::allocator_arg_t, const Alloc& \fB(9)\fP \fI(since C++11)\fP + alloc, (removed in C++17) function&& other ); - template< class F, class Alloc > \fB(10)\fP \fI(since C++11)\fP - function( std::allocator_arg_t, const Alloc& alloc, F f ); + template< class F, class Alloc > \fI(since C++11)\fP + function( std::allocator_arg_t, const Alloc& \fB(10)\fP (removed in C++17) + alloc, F f ); Constructs a std::function from a variety of sources. - 1-2) Creates an empty function. - 3-4) Copies \fB(3)\fP or moves \fB(4)\fP the target of other to the target of *this. If other is - empty, *this will be empty after the call too. - 5) Initializes the target with a copy of f. If f is a null pointer to function or - null pointer to member, *this will be empty after the call. - This constructor does not participate in overload resolution unless f is Callable - for argument types Args... and return type R. - \fI(since C++14)\fP - 6-10) Same as (1-5) just that alloc is used to allocate memory for any internal data - structures that the function might use. + 1,2) Creates an empty std::function. + 3) Copies the target of other to the target of *this. + If other is empty, *this will be empty right after the call too. + 4) Moves the target of other to the target of *this. + If other is empty, *this will be empty right after the call too. + other is in a valid but unspecified state right after the call. + 5) Initializes the target with std::forward(f). The target is of type + std::decay::type. + If f is a null pointer to function, a null pointer to member, or an empty value of + some std::function specialization, *this will be empty right after the call. + This overload participates in overload resolution only if all following conditions + are satisfied: + + * std::is_same_v, std::function (since C++23) + is false. + + * An lvalue of type std::decay::type is callable for argument types Args... and + return type R. + + If std::is_copy_constructible_v> or + std::is_constructible_v, F> is false, the program is (since C++23) + ill-formed. + + If F is not CopyConstructible, the behavior is undefined. + 6-10) Same as (1-5) except that alloc is used to allocate memory for any internal + data structures that the std::function might use. + + When the target is a function pointer or a std::reference_wrapper, small object + optimization is guaranteed, that is, these targets are always directly stored inside + the std::function object, no dynamic allocation takes place. Other large objects may + be constructed in dynamic allocated storage and accessed by the std::function object + through a pointer. .SH Parameters - other - the function object used to initialize *this - f - a callable used to initialize *this - alloc - an Allocator used for internal memory allocation + other - the function object used to initialize *this + f - a callable object used to initialize *this + alloc - an Allocator used for internal memory allocation .SH Type requirements - - - F must meet the requirements of Callable and CopyConstructible. - Alloc must meet the requirements of Allocator. .SH Exceptions - 1-2) - noexcept specification: - noexcept - - 3-5) \fI(none)\fP - 6-7) - noexcept specification: - noexcept - - 8-10) \fI(none)\fP + 3,8,9) Does not throw if other's target is a function pointer or a + std::reference_wrapper, otherwise may throw std::bad_alloc or any exception thrown + by the constructor used to copy or move the stored callable object. + + 4) Does not throw if other's target is a function pointer or a + std::reference_wrapper, otherwise may throw std::bad_alloc or any \fI(until C++20)\fP + exception thrown by the constructor used to copy or move the stored + callable object. + + 5,10) Does not throw if f is a function pointer or a std::reference_wrapper, + otherwise may throw std::bad_alloc or any exception thrown by the copy constructor + of the stored callable object. + +.SH Notes + + std::function's allocator support was poorly specified and inconsistently + implemented. Some implementations do not provide overloads (6-10) at all, some + provide the overloads but ignore the supplied allocator argument, and some provide + the overloads and use the supplied allocator for construction but not when the + std::function is reassigned. As a result, allocator support was removed in C++17. .SH Example This section is incomplete Reason: no example -.SH Category: + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2132 C++11 overloads (5,10) might be ambiguous constrained + LWG 2774 C++11 (5,10) performed an additional move eliminated +.SH See also + + constructor constructs a new std::move_only_function object + (C++23) \fI(public member function of std::move_only_function)\fP + +.SH Category: * Todo no example diff --git a/man/std::function::operator().3 b/man/std::function::operator().3 index 767ac38c7..8871f1657 100644 --- a/man/std::function::operator().3 +++ b/man/std::function::operator().3 @@ -1,8 +1,14 @@ -.TH std::function::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::operator() \- std::function::operator() + .SH Synopsis - R operator()( ArgTypes... args ) const; \fI(since C++11)\fP + R operator()( Args... args ) const; \fI(since C++11)\fP + + Invokes the stored callable function target with the parameters args. - Calls the stored callable function target with the parameters args. + Effectively does INVOKE(f, std::forward(args)...), where f is the target + object of *this. .SH Parameters @@ -15,39 +21,39 @@ .SH Exceptions - * std::bad_function_call if *this does not store a callable function target, - !*this == true. + Throws std::bad_function_call if *this does not store a callable function target, + i.e. !*this == true. .SH Example - The following example shows how std::function can passed to other functions by - value. Also, it shown how std::function can store lambdas. + The following example shows how std::function can be passed to other functions by + value. Also, it shows how std::function can store lambdas. + - // Run this code - #include #include - - void call(std::function f) // can be passed by value + #include + + void call(std::function f) // can be passed by value { std::cout << f() << '\\n'; } - + int normal_function() { return 42; } - + int main() { int n = 1; std::function f = [&n](){ return n; }; call(f); - + n = 2; call(f); - + f = normal_function; call(f); } @@ -60,8 +66,13 @@ .SH See also - This section is incomplete - -.SH Category: - - * Todo without reason + operator() invokes the target + (C++23) \fI(public member function of std::move_only_function)\fP + operator() calls the stored function + \fI(public member function of std::reference_wrapper)\fP + bad_function_call the exception thrown when invoking an empty std::function + \fI(C++11)\fP \fI(class)\fP + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP diff --git a/man/std::function::operator=.3 b/man/std::function::operator=.3 index 476ee32af..2103a68c7 100644 --- a/man/std::function::operator=.3 +++ b/man/std::function::operator=.3 @@ -1,12 +1,15 @@ -.TH std::function::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::operator= \- std::function::operator= + .SH Synopsis - function& operator=( const function& other ); \fB(1)\fP \fI(since C++11)\fP - function& operator=( function&& other ); \fB(2)\fP \fI(since C++11)\fP - function& operator=( std::nullptr_t ); \fB(3)\fP \fI(since C++11)\fP - template< class F > \fB(4)\fP \fI(since C++11)\fP + function& operator=( const function& other ); \fB(1)\fP \fI(since C++11)\fP + function& operator=( function&& other ); \fB(2)\fP \fI(since C++11)\fP + function& operator=( std::nullptr_t ) noexcept; \fB(3)\fP \fI(since C++11)\fP + template< class F > \fB(4)\fP \fI(since C++11)\fP function& operator=( F&& f ); - template< class F > \fB(5)\fP \fI(since C++11)\fP - function& operator=( std::reference_wrapper f ); + template< class F > \fB(5)\fP \fI(since C++11)\fP + function& operator=( std::reference_wrapper f ) noexcept; Assigns a new target to std::function. @@ -15,12 +18,12 @@ 2) Moves the target of other to *this. other is in a valid state with an unspecified value. 3) Drops the current target. *this is empty after the call. - 4) Moves the callable f to the target of *this, as if by executing - function(std::forward(f)).swap(*this);. - This operator does not participate in overload resolution unless f is Callable for - argument types Args... and return type R. - \fI(since C++14)\fP - 5) Assigns a copy of f, as if by executing function(f).swap(*this); + 4) Sets the target of *this to the callable f, as if by executing + function(std::forward(f)).swap(*this);. This operator does not participate in + overload resolution unless f is Callable for argument types Args... and return type + R. + 5) Sets the target of *this to a copy of f, as if by executing + function(f).swap(*this); .SH Parameters @@ -34,16 +37,26 @@ *this -.SH Exceptions +.SH Notes - 1-4) \fI(none)\fP - 5) - noexcept specification: - noexcept - + Even before allocator support was removed from std::function in C++17, these + assignment operators use the default allocator rather than the allocator of *this or + the allocator of other (see LWG issue 2386). -.SH See also + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + DR Applied to Behavior as published Correct behavior + LWG 2132 C++11 the overload taking a Callable object might be constrained + ambiguous + LWG 2401 C++11 assignment operator from std::nullptr_t not required + required to be noexcept + +.SH See also - assign assigns a new target - \fI(public member function)\fP + operator= replaces or destroys the target + (C++23) \fI(public member function of std::move_only_function)\fP + assign assigns a new target + (removed in C++17) \fI(public member function)\fP diff --git a/man/std::function::operatorbool.3 b/man/std::function::operatorbool.3 index e8ce5b833..6d9721f88 100644 --- a/man/std::function::operatorbool.3 +++ b/man/std::function::operatorbool.3 @@ -1,6 +1,9 @@ -.TH std::function::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::operatorbool \- std::function::operatorbool + .SH Synopsis - explicit operator bool() const; \fI(since C++11)\fP + explicit operator bool() const noexcept; \fI(since C++11)\fP Checks whether *this stores a callable function target, i.e. is not empty. @@ -12,51 +15,50 @@ true if *this stores a callable function target, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - - typedef std::function SomeVoidFunc; - - class C { - public: - C(SomeVoidFunc void_func = nullptr) - : void_func_(std::move(void_func)) + + void sampleFunction() + { + std::cout << "This is the sample function!\\n"; + } + + void checkFunc(std::function const& func) + { + // Use operator bool to determine if callable target is available. + if (func) { - if (!void_func_) { - void_func_ = std::bind(&C::default_func, this, std::placeholders::_1); - } - void_func_(7); + std::cout << "Function is not empty! Calling function.\\n"; + func(); } - - void default_func(int i) { std::cout << i << '\\n'; }; - - private: - SomeVoidFunc void_func_; - }; - - void user_func(int i) - { - std::cout << (i + 1) << '\\n'; + else + std::cout << "Function is empty. Nothing to do.\\n"; } - + int main() { - C c1; - C c2(user_func); + std::function f1; + std::function f2(sampleFunction); + + std::cout << "f1: "; + checkFunc(f1); + + std::cout << "f2: "; + checkFunc(f2); } .SH Output: - 7 - 8 + f1: Function is empty. Nothing to do. + f2: Function is not empty! Calling function. + This is the sample function! + +.SH See also + + operator bool checks if the std::move_only_function has a target + (C++23) \fI(public member function of std::move_only_function)\fP diff --git a/man/std::function::swap.3 b/man/std::function::swap.3 index 302563fb7..f49884a70 100644 --- a/man/std::function::swap.3 +++ b/man/std::function::swap.3 @@ -1,6 +1,9 @@ -.TH std::function::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::swap \- std::function::swap + .SH Synopsis - void swap( function& other ); \fI(since C++11)\fP + void swap( function& other ) noexcept; \fI(since C++11)\fP Exchanges the stored callable objects of *this and other. @@ -12,8 +15,7 @@ \fI(none)\fP -.SH Exceptions +.SH See also - noexcept specification: - noexcept - + swap swaps the targets of two std::move_only_function objects + (C++23) \fI(public member function of std::move_only_function)\fP diff --git a/man/std::function::target.3 b/man/std::function::target.3 index d3b8e64dd..333fd9405 100644 --- a/man/std::function::target.3 +++ b/man/std::function::target.3 @@ -1,9 +1,12 @@ -.TH std::function::target 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::target 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::target \- std::function::target + .SH Synopsis - template< class T > \fB(1)\fP \fI(since C++11)\fP - T* target(); - template< class T > \fB(2)\fP \fI(since C++11)\fP - const T* target() const; + template< class T > \fB(1)\fP \fI(since C++11)\fP + T* target() noexcept; + template< class T > \fB(2)\fP \fI(since C++11)\fP + const T* target() const noexcept; Returns a pointer to the stored callable function target. @@ -16,48 +19,56 @@ A pointer to the stored function if target_type() == typeid(T), otherwise a null pointer. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - - void normal_fun() + + int f(int, int) { return 1; } + int g(int, int) { return 2; } + void test(std::function const& arg) { - std::cout << "hello\\n"; + std::cout << "test function: "; + if (arg.target>()) + std::cout << "it is plus\\n"; + if (arg.target>()) + std::cout << "it is minus\\n"; + + int (*const* ptr)(int, int) = arg.target(); + if (ptr && *ptr == f) + std::cout << "it is the function f\\n"; + if (ptr && *ptr == g) + std::cout << "it is the function g\\n"; } - + int main() { - using fptr = void(*)(); - - fptr fun = normal_fun; //pointer to function - - std::function f = fun; - - fun = *f.target(); - //I know that f keeps a fptr object, then I invoke target to make a copy - //of the object - fun(); - - std::cout << std::boolalpha << (f.target() == nullptr) << '\\n'; - //f doesn't keep an object of type int + test(std::function(std::plus())); + test(std::function(std::minus())); + test(std::function(f)); + test(std::function(g)); } .SH Output: - hello - true + test function: it is plus + test function: it is minus + test function: it is the function f + test function: it is the function g + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2591 C++11 the behavior is undefined if T is behavior is defined (always + not Callable returns nullptr) .SH See also - target_type obtains the typeid of the stored target of a std::function - \fI(public member function)\fP + target_type obtains the typeid of the stored target + \fI(public member function)\fP diff --git a/man/std::function::target_type.3 b/man/std::function::target_type.3 index fdb0d8615..9087cacda 100644 --- a/man/std::function::target_type.3 +++ b/man/std::function::target_type.3 @@ -1,6 +1,9 @@ -.TH std::function::target_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::target_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::target_type \- std::function::target_type + .SH Synopsis - const std::type_info& target_type() const; \fI(since C++11)\fP + const std::type_info& target_type() const noexcept; \fI(since C++11)\fP Returns the type of the stored function. @@ -12,22 +15,40 @@ typeid(T) if the stored function has type T, otherwise typeid(void) -.SH Exceptions +.SH Example - noexcept specification: - noexcept - -.SH Example +// Run this code - This section is incomplete - Reason: no example + #include + #include -.SH See also + int f(int a) { return -a; } + void g(double) {} + int main() + { + // fn1 and fn2 have the same type, but their targets do not + std::function fn1(f), + fn2([](int a) {return -a;}); + std::cout << fn1.target_type().name() << '\\n' + << fn2.target_type().name() << '\\n'; - target obtains a pointer to the stored target of a std::function - \fI(public member function)\fP + // since C++17 deduction guides (CTAD) can avail + std::cout << std::function{g}.target_type().name() << '\\n'; + } -.SH Category: +.SH Possible output: + + PFiiE + Z4mainEUliE_ + PFvdE + +.SH See also - * Todo no example + target obtains a pointer to the stored target + \fI(public member function)\fP + typeid Queries information of a type, returning a std::type_info object + representing the type. + contains some type's information, generated by the implementation. + type_info This is the class returned by the typeid operator. + \fI(class)\fP diff --git a/man/std::function::~function.3 b/man/std::function::~function.3 index 4cf694a46..cf11aed2a 100644 --- a/man/std::function::~function.3 +++ b/man/std::function::~function.3 @@ -1,12 +1,14 @@ -.TH std::function::~function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::function::~function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function::~function \- std::function::~function + .SH Synopsis ~function(); \fI(since C++11)\fP - Destroys the std::function instance. If the stored callable is valid, it is - destroyed also. + Destroys the std::function instance. If the std::function is not empty, its target + is destroyed also. -.SH Exceptions +.SH See also - noexcept specification: - noexcept - + destructor destroys a std::move_only_function object + (C++23) \fI(public member function of std::move_only_function)\fP diff --git a/man/std::function_ref.3 b/man/std::function_ref.3 new file mode 100644 index 000000000..e6df02a76 --- /dev/null +++ b/man/std::function_ref.3 @@ -0,0 +1,84 @@ +.TH std::function_ref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function_ref \- std::function_ref + +.SH Synopsis + Defined in header + template< class... > \fB(1)\fP (since C++26) + class function_ref; // not defined + template< class R, class... Args > + + class function_ref; + template< class R, class... Args > + class function_ref; \fB(2)\fP (since C++26) + template< class R, class... Args > + class function_ref; + template< class R, class... Args > + + class function_ref; + + Class template std::function_ref is a non-owning function wrapper. std::function_ref + objects can store and invoke reference to Callable target - functions, lambda + expressions, bind expressions, or other function objects, but not pointers to member + functions and pointers to member objects. std::nontype can be used to construct + std::function_ref by passing function pointers, pointers to member functions, and + pointers to member objects. + + std::function_refs supports every possible combination of cv-qualifiers, and + noexcept-specifiers not including volatile provided in its template parameter. + + Every specialization of std::function_ref is a TriviallyCopyable type that satisfies + copyable. + +.SH Member objects + + Member name Definition + an object that has an unspecified TriviallyCopyable type + BoundEntityType, that satisfies copyable and is capable of + bound-entity (private) storing a pointer to object value or pointer to function + value + (exposition-only member object*) + a pointer to function of type R(*)(BoundEntityType, + Args&&...) noexcept(/*noex*/) where /*noex*/ is true if + thunk-ptr (private) noexcept is present in function signature as part of the + template parameter of std::function_ref + (exposition-only member object*) + +.SH Member functions + + constructor constructs a new function_ref object + (C++26) \fI(public member function)\fP + operator= assigns a function_ref + (C++26) \fI(public member function)\fP + operator() invokes the stored thunk of a function_ref + (C++26) \fI(public member function)\fP + + Deduction guides + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_function_ref 202306L (C++26) std::function_ref + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + copyable_function refinement of std::move_only_function that wraps callable object + (C++26) of any copy constructible type + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + nontype value construction tag + nontype_t (tag) + (C++26) + +.SH Category: + * Todo with reason diff --git a/man/std::function_ref::function_ref.3 b/man/std::function_ref::function_ref.3 new file mode 100644 index 000000000..e97afad9f --- /dev/null +++ b/man/std::function_ref::function_ref.3 @@ -0,0 +1,85 @@ +.TH std::function_ref::function_ref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function_ref::function_ref \- std::function_ref::function_ref + +.SH Synopsis + template< class F > \fB(1)\fP (since C++26) + function_ref( F* f ) noexcept; + template< class F > \fB(2)\fP (since C++26) + function_ref( F&& f ) noexcept; + template< auto f > \fB(3)\fP (since C++26) + function_ref( std::nontype_t ) noexcept; + template< auto f, class U > \fB(4)\fP (since C++26) + function_ref( std::nontype_t, U&& obj ) noexcept; + template< auto f, class T > \fB(5)\fP (since C++26) + function_ref( std::nontype_t, /*cv*/ T* obj ) noexcept; + function_ref( const function_ref& other ) = default; \fB(6)\fP (since C++26) + + Creates a new std::function_ref. + + 1) Initializes bound-entity with f, and thunk-ptr with the address of a function + thunk. The behavior is undefined if f is a null pointer. + * This overload participates in overload resolution only if both + std::is_function_v and /*is-invocable-using*/ are true. + 2) Initializes bound-entity with std::addressof(f), and thunk-ptr with the address + of a function thunk. + * Let T be std::remove_reference_t. This overload participates in overload + resolution only if : + * std::remove_cvref_t is not the same type as function_ref, + * std::is_member_pointer_v is false, and + * /*is-invocable-using*/ is true. + 3) Initializes bound-entity with a pointer to an unspecified object or null pointer + value, and thunk-ptr with the address of a function thunk. + * Let F be decltype(f). This overload participates in overload resolution only if + /*is-invocable-using*/ is true. + * The program is ill-formed if f != nullptr is false when std::is_pointer_v || + std::is_member_pointer_v is true. + 4) Initializes bound-entity with std::addressof(obj), and thunk-ptr with the address + of a function thunk. + * Let T be std::remove_reference_t and F be decltype(f). This overload + participates in overload resolution only if : + * std::is_rvalue_reference_v is false, and + * /*is-invocable-using*/ is true. + * The program is ill-formed if f != nullptr is false when std::is_pointer_v || + std::is_member_pointer_v is true. + 5) Initializes bound-entity with obj, and thunk-ptr with the address of a function + thunk. The behavior is undefined if obj is a null pointer when + std::is_member_pointer_v is true. + * Let F be decltype(f). This overload participates in overload resolution only if + /*is-invocable-using*/ is true. + * The program is ill-formed if f != nullptr is false when std::is_pointer_v || + std::is_member_pointer_v is true. + 6) Defaulted copy constructor copies the bound-entity and thunk-ptr of other. + + The address of a function thunk is used to initialize thunk-ptr such that a call to + thunk(bound-entity, call-args...) is expression-equivalent to: + + Overloads Expression-equivalence + (1,3) std::invoke_r(f, call-args...) + \fB(2)\fP std::invoke_r(static_cast(f), call-args...) + \fB(4)\fP std::invoke_r(f, static_cast(obj), call-args...) + \fB(5)\fP std::invoke_r(f, obj, call-args...) + + /*is-invocable-using*/ is true if and only if: + + * std::is_nothrow_invocable_r_v is true if noex is true, or + * std::is_invocable_r_v is true + +.SH Parameters + + other - another function_ref to copy from + f - a function or a Callable object to wrap + obj - an object or pointer to bound + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new std::move_only_function object + (C++23) \fI(public member function of std::move_only_function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::function_ref::operator().3 b/man/std::function_ref::operator().3 new file mode 100644 index 000000000..99df6ca31 --- /dev/null +++ b/man/std::function_ref::operator().3 @@ -0,0 +1,39 @@ +.TH std::function_ref::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function_ref::operator() \- std::function_ref::operator() + +.SH Synopsis + R operator()( Args... args ) const noexcept(/*noex*/); (since C++26) + + Invokes the stored thunk-ptr with bound-entity as its first parameter and the rest + of the parameters args. The /*noex*/ part of operator() is identical to those of the + template parameter of std::function_ref. + + Equivalent to return thunk-ptr(bound-entity, std::forward(args)...);. + +.SH Parameters + + args - rest parameters to pass to the stored thunk-ptr + +.SH Return value + + thunk-ptr(bound-entity, std::forward(args)...). + +.SH Exceptions + + Propagates the exception thrown by the underlying function call. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator() invokes the target + \fI(public member function of std::function)\fP + operator() calls the stored function + \fI(public member function of std::reference_wrapper)\fP + +.SH Category: + * Todo no example diff --git a/man/std::function_ref::operator=.3 b/man/std::function_ref::operator=.3 new file mode 100644 index 000000000..5dc395c88 --- /dev/null +++ b/man/std::function_ref::operator=.3 @@ -0,0 +1,28 @@ +.TH std::function_ref::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::function_ref::operator= \- std::function_ref::operator= + +.SH Synopsis + constexpr function_ref& operator=( const function_ref& ) noexcept \fB(1)\fP (since C++26) + = default; + template< class T > \fB(2)\fP (since C++26) + constexpr function_ref& operator=( T ) = delete; + + 1) Copy assignment operator is explicitly-defaulted. std::function_ref satisfies + copyable and TriviallyCopyable. This defaulted assignment operator performs a + shallow copy of the stored thunk-ptr and bound-entity. + 2) User-defined assignment operator is explicitly-deleted if T is not the same type + as std::function_ref, std::is_pointer_v is false, and T is not a specialization + of std::nontype_t. This overload participates in overload resolution only if the + constraints are satisfied in the conditions above. + +.SH Return value + + *this + +.SH See also + + constructor constructs a new function_ref object + (C++26) \fI(public member function)\fP + operator= assigns a new target + \fI(public member function of std::function)\fP diff --git a/man/std::future.3 b/man/std::future.3 index 65325921d..1e956f874 100644 --- a/man/std::future.3 +++ b/man/std::future.3 @@ -1,9 +1,12 @@ -.TH std::future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future \- std::future + .SH Synopsis Defined in header - template< class T > class future; \fB(1)\fP \fI(since C++11)\fP - template< class T > class future; \fB(2)\fP \fI(since C++11)\fP - template<> class future; \fB(3)\fP \fI(since C++11)\fP + template< class T > class future; \fB(1)\fP \fI(since C++11)\fP + template< class T > class future; \fB(2)\fP \fI(since C++11)\fP + template<> class future; \fB(3)\fP \fI(since C++11)\fP The class template std::future provides a mechanism to access the result of asynchronous operations: @@ -11,11 +14,9 @@ * An asynchronous operation (created via std::async, std::packaged_task, or std::promise) can provide a std::future object to the creator of that asynchronous operation. - * The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from the std::future. These methods may block if the asynchronous operation has not yet provided a value. - * When the asynchronous operation is ready to send a result to the creator, it can do so by modifying shared state (e.g. std::promise::set_value) that is linked to the creator's std::future. @@ -26,60 +27,60 @@ .SH Member functions constructor constructs the future object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the future object - \fI(public member function)\fP + \fI(public member function)\fP operator= moves the future object - \fI(public member function)\fP + \fI(public member function)\fP transfers the shared state from *this to a shared_future and returns share it - \fI(public member function)\fP + \fI(public member function)\fP .SH Getting the result get returns the result - \fI(public member function)\fP + \fI(public member function)\fP .SH State valid checks if the future has a shared state - \fI(public member function)\fP + \fI(public member function)\fP wait waits for the result to become available - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available until specified wait_until time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Examples -.SH Example - // Run this code - #include #include + #include #include - + int main() { // future from a packaged_task - std::packaged_task task([](){ return 7; }); // wrap the function - std::future f1 = task.get_future(); // get a future - std::thread(std::move(task)).detach(); // launch on a thread - + std::packaged_task task([]{ return 7; }); // wrap the function + std::future f1 = task.get_future(); // get a future + std::thread t(std::move(task)); // launch on a thread + // future from an async() - std::future f2 = std::async(std::launch::async, [](){ return 8; }); - + std::future f2 = std::async(std::launch::async, []{ return 8; }); + // future from a promise std::promise p; std::future f3 = p.get_future(); - std::thread( [](std::promise p){ p.set_value_at_thread_exit(9); }, - std::move(p) ).detach(); - + std::thread([&p]{ p.set_value_at_thread_exit(9); }).detach(); + std::cout << "Waiting..." << std::flush; f1.wait(); f2.wait(); f3.wait(); std::cout << "Done!\\nResults are: " << f1.get() << ' ' << f2.get() << ' ' << f3.get() << '\\n'; + t.join(); } .SH Output: @@ -87,11 +88,58 @@ Waiting...Done! Results are: 7 8 9 + Example with exceptions + + +// Run this code + + #include + #include + #include + + int main() + { + std::promise p; + std::future f = p.get_future(); + + std::thread t([&p] + { + try + { + // code that may throw + throw std::runtime_error("Example"); + } + catch (...) + { + try + { + // store anything thrown in the promise + p.set_exception(std::current_exception()); + } + catch (...) {} // set_exception() may throw too + } + }); + + try + { + std::cout << f.get(); + } + catch (const std::exception& e) + { + std::cout << "Exception from the thread: " << e.what() << '\\n'; + } + t.join(); + } + +.SH Output: + + Exception from the thread: Example + .SH See also async runs a function asynchronously (potentially in a new thread) and \fI(C++11)\fP returns a std::future that will hold the result - \fI(function template)\fP + \fI(function template)\fP shared_future waits for a value (possibly referenced by other futures) that is set \fI(C++11)\fP asynchronously - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::future::future.3 b/man/std::future::future.3 index 27fe9d0bd..4f8054ace 100644 --- a/man/std::future::future.3 +++ b/man/std::future::future.3 @@ -1,7 +1,10 @@ -.TH std::future::future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::future \- std::future::future + .SH Synopsis - future(); \fB(1)\fP \fI(since C++11)\fP - future( future&& other ); \fB(2)\fP \fI(since C++11)\fP + future() noexcept; \fB(1)\fP \fI(since C++11)\fP + future( future&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP future( const future& other ) = delete; \fB(3)\fP \fI(since C++11)\fP Constructs a std::future object. @@ -15,10 +18,3 @@ .SH Parameters other - another std::future to acquire shared state from - -.SH Exceptions - - 1-2) - noexcept specification: - noexcept - diff --git a/man/std::future::get.3 b/man/std::future::get.3 index 19497da88..993d6cf35 100644 --- a/man/std::future::get.3 +++ b/man/std::future::get.3 @@ -1,32 +1,26 @@ -.TH std::future::get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - T get(); \fB(1)\fP (member only of generic future template) - \fI(since C++11)\fP - T& get(); \fB(2)\fP (member only of future template specialization) - \fI(since C++11)\fP - void get(); \fB(3)\fP (member only of future template specialization) - \fI(since C++11)\fP - - The get method waits until the future has a valid result and (depending on which - template is used) retrieves it. It effectively calls wait() in order to wait for the - result. - - The generic template and two template specializations each contain a single version - of get. The three versions of get differ only in the return type. - - The behavior is undefined if valid() is false before the call to this function. +.TH std::future::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::get \- std::future::get - valid() is false after a call to this method. +.SH Synopsis + Main template + T get(); \fB(1)\fP \fI(since C++11)\fP + std::future specializations + T& get(); \fB(2)\fP \fI(since C++11)\fP + std::future specialization + void get(); \fB(3)\fP \fI(since C++11)\fP -.SH Parameters + The get member function waits (by calling wait()) until the shared state is ready, + then retrieves the value stored in the shared state (if any). Right after calling + this function, valid() is false. - \fI(none)\fP + If valid() is false before the call to this function, the behavior is undefined. .SH Return value 1) The value v stored in the shared state, as std::move(v). - 2) Reference to the value in the shared state. - 3) Nothing. + 2) The reference stored as value in the shared state. + 3) \fI(none)\fP .SH Exceptions @@ -35,20 +29,89 @@ .SH Notes - The implementations are encouraged to detect the case when valid() is false before - the call and throw a std::future_error with an error condition of + The C++ standard recommends the implementations to detect the case when valid() is + false before the call and throw a std::future_error with an error condition of std::future_errc::no_state. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + std::string time() + { + static auto start = std::chrono::steady_clock::now(); + std::chrono::duration d = std::chrono::steady_clock::now() - start; + return "[" + std::to_string(d.count()) + "s]"; + } + + int main() + { + using namespace std::chrono_literals; + + { + std::cout << time() << " launching thread\\n"; + std::future f = std::async(std::launch::async, [] + { + std::this_thread::sleep_for(1s); + return 7; + }); + std::cout << time() << " waiting for the future, f.valid() = " + << f.valid() << '\\n'; + int n = f.get(); + std::cout << time() << " f.get() returned " << n << ", f.valid() = " + << f.valid() << '\\n'; + } + + { + std::cout << time() << " launching thread\\n"; + std::future f = std::async(std::launch::async, [] + { + std::this_thread::sleep_for(1s); + return true ? throw std::runtime_error("7") : 7; + }); + std::cout << time() << " waiting for the future, f.valid() = " + << f.valid() << '\\n'; + + try + { + int n = f.get(); + std::cout << time() << " f.get() returned " << n + << ", f.valid() = " << f.valid() << '\\n'; + } + catch (const std::exception& e) + { + std::cout << time() << " caught exception " << e.what() + << ", f.valid() = " << f.valid() << '\\n'; + } + } + } + +.SH Possible output: + + [0.000004s] launching thread + [0.000461s] waiting for the future, f.valid() = 1 + [1.001156s] f.get() returned with 7, f.valid() = 0 + [1.001192s] launching thread + [1.001275s] waiting for the future, f.valid() = 1 + [2.002356s] caught exception 7, f.valid() = 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2096 C++11 overload \fB(1)\fP needed to check whether T is not required + MoveAssignable .SH See also valid checks if the future has a shared state - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::future::operator=.3 b/man/std::future::operator=.3 index 037ab8a81..e332705c4 100644 --- a/man/std::future::operator=.3 +++ b/man/std::future::operator=.3 @@ -1,6 +1,9 @@ -.TH std::future::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::operator= \- std::future::operator= + .SH Synopsis - future& operator=( future&& other ); \fB(1)\fP \fI(since C++11)\fP + future& operator=( future&& other ) noexcept; \fB(1)\fP \fI(since C++11)\fP future& operator=( const future& other ) = delete; \fB(2)\fP \fI(since C++11)\fP Assigns the contents of another future object. @@ -8,7 +11,6 @@ 1) Releases any shared state and move-assigns the contents of other to *this. After the assignment, other.valid() == false and this->valid() will yield the same value as other.valid() before the assignment. - 2) std::future is not CopyAssignable. .SH Parameters @@ -18,9 +20,3 @@ .SH Return value *this - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::future::share.3 b/man/std::future::share.3 index 5ca3e1001..bfccaf81d 100644 --- a/man/std::future::share.3 +++ b/man/std::future::share.3 @@ -1,39 +1,44 @@ -.TH std::future::share 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::share 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::share \- std::future::share + .SH Synopsis - std::shared_future share(); + std::shared_future share() noexcept; - Transfers the shared state of *this to a std::shared_future object. Multiple - std::shared_future objects may reference the same shared state, which is not - possible with std::future. + Transfers the shared state of *this, if any, to a std::shared_future object. + Multiple std::shared_future objects may reference the same shared state, which is + not possible with std::future. After calling share on a std::future, valid() == false. - The behavior is undefined if valid()== false before the call to this function. - .SH Parameters \fI(none)\fP .SH Return value - A std::shared_future object containing the shared state previously held by *this - -.SH Notes - - The implementations are encouraged to detect the case when valid == false before the - call and throw a future_error with an error condition of future_errc::no_state. + A std::shared_future object containing the shared state previously held by *this, if + any, constructed as if by std::shared_future(std::move(*this)). .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2556 C++11 share() requires valid() to be requirement removed and made + true noexcept + .SH See also shared_future waits for a value (possibly referenced by other futures) that is set \fI(C++11)\fP asynchronously - \fI(class template)\fP + \fI(class template)\fP .SH Category: - * Todo no example diff --git a/man/std::future::valid.3 b/man/std::future::valid.3 index 1a8b48a3c..3ead6a977 100644 --- a/man/std::future::valid.3 +++ b/man/std::future::valid.3 @@ -1,10 +1,21 @@ -.TH std::future::valid 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::valid 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::valid \- std::future::valid + .SH Synopsis - bool valid() const; \fI(since C++11)\fP + bool valid() const noexcept; \fI(since C++11)\fP + + Checks if the future refers to a shared state. + + This is the case only for futures that were not default-constructed or moved from + (i.e. returned by std::promise::get_future(), std::packaged_task::get_future() or + std::async()) until the first time get() or share() is called. - Checks if the future refers to a shared state. This is the case only for futures - returned by std::promise::get_future(), std::packaged_task::get_future() or - std::async() until the first time get()or share() is called. + The behavior is undefined if any member function other than the destructor, the + move-assignment operator, or valid is called on a future that does not refer to + shared state (although implementations are encouraged to throw std::future_error + indicating no_state in this case). It is valid to move from a future object for + which valid() is false. .SH Parameters @@ -14,22 +25,35 @@ true if *this refers to a shared state, otherwise false. -.SH Exceptions +.SH Example - noexcept specification: - noexcept - -.SH Example +// Run this code - This section is incomplete - Reason: no example + #include + #include -.SH See also + int main() + { + std::promise p; + std::future f = p.get_future(); - wait waits for the result to become available - \fI(public member function)\fP + std::cout << std::boolalpha; + + std::cout << f.valid() << '\\n'; + p.set_value(); + std::cout << f.valid() << '\\n'; + f.get(); + std::cout << f.valid() << '\\n'; + } + +.SH Output: -.SH Category: + true + true + false - * Todo no example +.SH See also + + wait waits for the result to become available + \fI(public member function)\fP diff --git a/man/std::future::wait.3 b/man/std::future::wait.3 index 07af6cd9e..9fd1e6eca 100644 --- a/man/std::future::wait.3 +++ b/man/std::future::wait.3 @@ -1,10 +1,13 @@ -.TH std::future::wait 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::wait \- std::future::wait + .SH Synopsis void wait() const; \fI(since C++11)\fP Blocks until the result becomes available. valid() == true after the call. - The behavior is undefined if valid()== false before the call to this function. + The behavior is undefined if valid() == false before the call to this function. .SH Parameters @@ -16,57 +19,61 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes - The implementations are encouraged to detect the case when valid == false before the - call and throw a std::future_error with an error condition of + The implementations are encouraged to detect the case when valid() == false before + the call and throw a std::future_error with an error condition of std::future_errc::no_state. .SH Example - + // Run this code - #include + #include #include + #include #include - + int fib(int n) { - if (n < 3) return 1; - else return fib(n-1) + fib(n-2); + if (n < 3) + return 1; + else + return fib(n - 1) + fib(n - 2); } - + int main() { - std::future f1 = std::async(std::launch::async, [](){ - return fib(20); - }); - std::future f2 = std::async(std::launch::async, [](){ - return fib(25); - }); - - std::cout << "waiting...\\n"; + std::future f1 = std::async(std::launch::async, []() { return fib(40); }); + std::future f2 = std::async(std::launch::async, []() { return fib(43); }); + + std::cout << "waiting... " << std::flush; + const auto start = std::chrono::system_clock::now(); + f1.wait(); f2.wait(); - + + const auto diff = std::chrono::system_clock::now() - start; + std::cout << std::chrono::duration(diff).count() << " seconds\\n"; + std::cout << "f1: " << f1.get() << '\\n'; std::cout << "f2: " << f2.get() << '\\n'; } -.SH Output: +.SH Possible output: - waiting... - f1: 6765 - f2: 75025 + waiting... 1.61803 seconds + f1: 102334155 + f2: 433494437 .SH See also waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available until specified time wait_until point has been reached - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::future::wait_for.3 b/man/std::future::wait_for.3 index 4cc5f7e48..b20eab894 100644 --- a/man/std::future::wait_for.3 +++ b/man/std::future::wait_for.3 @@ -1,17 +1,27 @@ -.TH std::future::wait_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::wait_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::wait_for \- std::future::wait_for + .SH Synopsis template< class Rep, class Period > std::future_status wait_for( const std::chrono::duration& \fI(since C++11)\fP timeout_duration ) const; Waits for the result to become available. Blocks until specified timeout_duration - has elapsed or the result becomes available, whichever comes first. Returns value + has elapsed or the result becomes available, whichever comes first. The return value identifies the state of the result. - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + If the future is the result of a call to std::async that used lazy evaluation, this + function returns immediately without waiting. + + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. - The behavior is undefined if valid()== false before the call to this function. + The standard recommends that a steady clock is used to measure the duration. If an + implementation uses a system clock instead, the wait time may also be sensitive to + clock adjustments. + + The behavior is undefined if valid() is false before the call to this function. .SH Parameters @@ -20,51 +30,62 @@ .SH Return value Constant Explanation - future_status::deferred The function to calculate the result has not been started - yet + The shared state contains a deferred function using lazy + future_status::deferred evaluation, so the result will be computed only when + explicitly requested future_status::ready The result is ready future_status::timeout The timeout has expired .SH Exceptions Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + time points, and durations provided by the standard library never throw). .SH Notes The implementations are encouraged to detect the case when valid == false before the - call and throw a future_error with an error condition of future_errc::no_state. + call and throw a std::future_error with an error condition of + std::future_errc::no_state. .SH Example - + // Run this code - #include + #include #include + #include #include - #include - + using namespace std::chrono_literals; + int main() { - std::future future = std::async(std::launch::async, [](){ - std::this_thread::sleep_for(std::chrono::seconds(3)); + std::future future = std::async(std::launch::async, []() + { + std::this_thread::sleep_for(3s); return 8; }); - + std::cout << "waiting...\\n"; std::future_status status; - do { - status = future.wait_for(std::chrono::seconds(1)); - if (status == std::future_status::deferred) { - std::cout << "deferred\\n"; - } else if (status == std::future_status::timeout) { - std::cout << "timeout\\n"; - } else if (status == std::future_status::ready) { - std::cout << "ready!\\n"; + + do + { + switch (status = future.wait_for(1s); status) + { + case std::future_status::deferred: + std::cout << "deferred\\n"; + break; + case std::future_status::timeout: + std::cout << "timeout\\n"; + break; + case std::future_status::ready: + std::cout << "ready!\\n"; + break; } - } while (status != std::future_status::ready); - + } + while (status != std::future_status::ready); + std::cout << "result is " << future.get() << '\\n'; } @@ -73,13 +94,14 @@ waiting... timeout timeout + timeout ready! result is 8 .SH See also wait waits for the result to become available - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available until specified time wait_until point has been reached - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::future::wait_until.3 b/man/std::future::wait_until.3 index c4b5cc52e..ea34b63b9 100644 --- a/man/std::future::wait_until.3 +++ b/man/std::future::wait_until.3 @@ -1,4 +1,7 @@ -.TH std::future::wait_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::wait_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::wait_until \- std::future::wait_until + .SH Synopsis template< class Clock, class Duration > std::future_status wait_until( const \fI(since C++11)\fP @@ -8,15 +11,13 @@ timeout_time has been reached or the result becomes available, whichever comes first. The return value indicates why wait_until returned. - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might differ from - timeout_time - Clock::now() at the time of the call, depending on the direction of - the adjustment. - - The function also may block for longer than until after timeout_time has been - reached due to scheduling or resource contention delays. + If the future is the result of a call to async that used lazy evaluation, this + function returns immediately without waiting. - The behavior is undefined if valid()== false before the call to this function. + The behavior is undefined if valid() is false before the call to this function, or + Clock does not meet the Clock requirements. + The programs is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP .SH Parameters @@ -25,34 +26,95 @@ .SH Return value Constant Explanation - future_status::deferred The function to calculate the result has not been started - yet + The shared state contains a deferred function using lazy + future_status::deferred evaluation, so the result will be computed only when + explicitly requested future_status::ready The result is ready future_status::timeout The timeout has expired .SH Exceptions Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + time points, and durations provided by the standard library never throw). .SH Notes - The implementations are encouraged to detect the case when valid == false before the - call and throw a future_error with an error condition of future_errc::no_state. + The implementations are encouraged to detect the case when valid() == false before + the call and throw a std::future_error with an error condition of + future_errc::no_state. + + The standard recommends that the clock tied to timeout_time be used to measure time; + that clock is not required to be a monotonic clock. There are no guarantees + regarding the behavior of this function if the clock is adjusted discontinuously, + but the existing implementations convert timeout_time from Clock to + std::chrono::system_clock and delegate to POSIX pthread_cond_timedwait so that the + wait honors adjustments to the system clock, but not to the user-provided Clock. In + any case, the function also may wait for longer than until after timeout_time has + been reached due to scheduling or resource contention delays. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::chrono::system_clock::time_point two_seconds_passed + = std::chrono::system_clock::now() + std::chrono::seconds(2); + + // Make a future that takes 1 second to complete + std::promise p1; + std::future f_completes = p1.get_future(); + std::thread([](std::promise p1) + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + p1.set_value_at_thread_exit(9); + }, + std::move(p1) + ).detach(); + + // Make a future that takes 5 seconds to complete + std::promise p2; + std::future f_times_out = p2.get_future(); + std::thread([](std::promise p2) + { + std::this_thread::sleep_for(std::chrono::seconds(5)); + p2.set_value_at_thread_exit(8); + }, + std::move(p2) + ).detach(); + + std::cout << "Waiting for 2 seconds..." << std::endl; + + if (std::future_status::ready == f_completes.wait_until(two_seconds_passed)) + std::cout << "f_completes: " << f_completes.get() << "\\n"; + else + std::cout << "f_completes did not complete!\\n"; + + if (std::future_status::ready == f_times_out.wait_until(two_seconds_passed)) + std::cout << "f_times_out: " << f_times_out.get() << "\\n"; + else + std::cout << "f_times_out did not complete!\\n"; + + std::cout << "Done!\\n"; + } + +.SH Possible output: + + Waiting for 2 seconds... + f_completes: 9 + f_times_out did not complete! + Done! .SH See also wait waits for the result to become available - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::future::~future.3 b/man/std::future::~future.3 index 4ebb4f470..5de4af82e 100644 --- a/man/std::future::~future.3 +++ b/man/std::future::~future.3 @@ -1,5 +1,22 @@ -.TH std::future::~future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future::~future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future::~future \- std::future::~future + .SH Synopsis ~future(); \fI(since C++11)\fP - Abandons the ownership of the shared state, if any. + Releases any shared state. This means + + * if the current object holds the last reference to its shared state, the shared + state is destroyed; + * the current object gives up its reference to its shared state; + + * these actions will not block for the shared state to become ready, + except that they may block if all of the following are true: + 1. the shared state was created by a call to std::async, \fI(since C++14)\fP + 2. the shared state is not yet ready, and + 3. the current object was the last reference to the shared state. + + In practice, these actions will block only if the task’s launch policy is + std::launch::async (see "Effective Modern C++" Item 36), either because that was + chosen by the runtime system or because it was specified in the call to std::async. diff --git a/man/std::future_category.3 b/man/std::future_category.3 index 11bc9ad9b..26e59218a 100644 --- a/man/std::future_category.3 +++ b/man/std::future_category.3 @@ -1,12 +1,15 @@ -.TH std::future_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_category \- std::future_category + .SH Synopsis Defined in header - const std::error_category& future_category(); \fI(since C++11)\fP + const std::error_category& future_category() noexcept; \fI(since C++11)\fP - Obtains a reference to the static error category object for future object errors. - The object is required to override the virtual function error_category::name() to - return a pointer to the string "future". It is used to identify error codes provided - in the exceptions of type std::future_error. + Obtains a reference to the static error category object for the errors related to + futures and promises. The object is required to override the virtual function + error_category::name() to return a pointer to the string "future". It is used to + identify error codes provided in the exceptions of type std::future_error. .SH Parameters @@ -17,12 +20,6 @@ A reference to the static object of unspecified runtime type, derived from std::error_category. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -30,11 +27,12 @@ .SH See also - future_error reports an error related to futures or promises - \fI(C++11)\fP \fI(class)\fP - future_errc identifies the future error codes - \fI(C++11)\fP \fI(enum)\fP + future_errc identifies the future error codes + \fI(C++11)\fP \fI(enum)\fP + future_error reports an error related to futures or promises + \fI(C++11)\fP \fI(class)\fP + error_category base class for error categories + \fI(C++11)\fP \fI(class)\fP .SH Category: - * Todo no example diff --git a/man/std::future_errc.3 b/man/std::future_errc.3 index b931d7f40..c95a303a4 100644 --- a/man/std::future_errc.3 +++ b/man/std::future_errc.3 @@ -1,4 +1,7 @@ -.TH std::future_errc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_errc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_errc \- std::future_errc + .SH Synopsis Defined in header enum class future_errc { @@ -32,34 +35,36 @@ .SH Non-member functions make_error_code(std::future_errc) constructs a future error code - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP make_error_condition(std::future_errc) constructs a future error_condition - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP .SH Helper classes is_error_code_enum extends the type trait std::is_error_code_enum \fI(C++11)\fP to identify future error codes - \fI(class template)\fP - -.SH Notes - - In C++11, broken_promise was specified to equal zero despite - std::error_code/std::error_condition using zero to mean "no error". This was fixed - in LWG issue @2056 for C++14. + \fI(class template)\fP .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2056 C++11 broken_promise was specified to be zero which specified to be + is conventionally used to mean "no error" non-zero + .SH See also error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP .SH Category: - * Todo no example diff --git a/man/std::future_error.3 b/man/std::future_error.3 index 445477500..aa39fdf11 100644 --- a/man/std::future_error.3 +++ b/man/std::future_error.3 @@ -1,4 +1,7 @@ -.TH std::future_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_error \- std::future_error + .SH Synopsis Defined in header class future_error; \fI(since C++11)\fP @@ -9,18 +12,19 @@ exception carries an error code compatible with std::error_code. std-future error-inheritance.svg - About this image Inheritance diagram .SH Member functions constructor creates a std::future_error object - \fI(public member function)\fP + \fI(public member function)\fP + operator= replaces the std::future_error object + \fI(public member function)\fP code returns the error code - \fI(public member function)\fP + \fI(public member function)\fP what returns the explanatory string specific to the error code - \fI(public member function)\fP + \fI(public member function)\fP Inherited from std::logic_error @@ -28,31 +32,35 @@ Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code #include #include - + int main() { std::future empty; - try { - int n = empty.get(); - } catch (const std::future_error& e) { + try + { + int n = empty.get(); // The behavior is undefined, but + // some implementations throw std::future_error + } + catch (const std::future_error& e) + { std::cout << "Caught a future_error with code \\"" << e.code() << "\\"\\nMessage: \\"" << e.what() << "\\"\\n"; } } -.SH Output: +.SH Possible output: Caught a future_error with code "future:3" Message: "No associated state" @@ -60,4 +68,4 @@ Inherited from std::exception .SH See also future_errc identifies the future error codes - \fI(C++11)\fP \fI(enum)\fP + \fI(C++11)\fP \fI(enum)\fP diff --git a/man/std::future_error::code.3 b/man/std::future_error::code.3 index 1f322921f..466e44b0b 100644 --- a/man/std::future_error::code.3 +++ b/man/std::future_error::code.3 @@ -1,6 +1,9 @@ -.TH std::future_error::code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_error::code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_error::code \- std::future_error::code + .SH Synopsis - const std::error_code& code() const; \fI(since C++11)\fP + const std::error_code& code() const noexcept; \fI(since C++11)\fP Returns the stored error code. @@ -12,13 +15,7 @@ The stored error code. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also what returns the explanatory string specific to the error code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::future_error::future_error.3 b/man/std::future_error::future_error.3 index d1de2153a..8b487b74c 100644 --- a/man/std::future_error::future_error.3 +++ b/man/std::future_error::future_error.3 @@ -1,9 +1,25 @@ -.TH std::future_error::future_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_error::future_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_error::future_error \- std::future_error::future_error + .SH Synopsis - future_error( std::error_code ec ); \fI(since C++11)\fP + future_error( const future_error& other ) noexcept; \fB(1)\fP \fI(since C++11)\fP + explicit future_error( std::future_errc ec ); \fB(2)\fP \fI(since C++17)\fP - Constructs a new future error object containing error code ec. + 1) Copy constructor. Initializes the contents of the new future_error object with + those of other. If *this and other both have dynamic type std::future_error then + std::strcmp(what(), other.what()) == 0. + 2) Constructs a new future_error object containing the error code + std::make_error_code(ec). .SH Parameters - ec - error code + other - another future_error object to copy + ec - error code + +.SH Notes + + There is no standard-compliant way for the user to construct a future_error other + than copying from another future_error prior to C++17. C++11 and C++14 depict an + exposition-only public constructor taking a std::error_code, and some + implementations provide such a constructor. diff --git a/man/std::future_error::operator=.3 b/man/std::future_error::operator=.3 new file mode 100644 index 000000000..239cbb39b --- /dev/null +++ b/man/std::future_error::operator=.3 @@ -0,0 +1,25 @@ +.TH std::future_error::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_error::operator= \- std::future_error::operator= + +.SH Synopsis + future_error& operator=( const future_error& other ) noexcept; \fI(since C++11)\fP + + Assigns the contents with those of other. If *this and other both have dynamic type + std::future_error then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another future_error object to assign with + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::future_error::what.3 b/man/std::future_error::what.3 index 45494e8a9..86eda4c4c 100644 --- a/man/std::future_error::what.3 +++ b/man/std::future_error::what.3 @@ -1,6 +1,9 @@ -.TH std::future_error::what 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_error::what 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_error::what \- std::future_error::what + .SH Synopsis - virtual const char* what() const; \fI(since C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP Returns the explanatory string. @@ -12,13 +15,7 @@ Pointer to a null-terminated string with explanatory information. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also code returns the error code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::future_status.3 b/man/std::future_status.3 index 180cabd19..39b963984 100644 --- a/man/std::future_status.3 +++ b/man/std::future_status.3 @@ -1,4 +1,7 @@ -.TH std::future_status 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::future_status 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::future_status \- std::future_status + .SH Synopsis Defined in header enum class future_status { @@ -23,13 +26,13 @@ waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function of std::future)\fP + \fI(public member function of std::future)\fP waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function of std::shared_future)\fP + \fI(public member function of std::shared_future)\fP waits for the result, returns if it is not available until specified time wait_until point has been reached - \fI(public member function of std::future)\fP + \fI(public member function of std::future)\fP waits for the result, returns if it is not available until specified time wait_until point has been reached - \fI(public member function of std::shared_future)\fP + \fI(public member function of std::shared_future)\fP diff --git a/man/std::fwgets.3 b/man/std::fwgets.3 deleted file mode 100644 index 5cdaccb9c..000000000 --- a/man/std::fwgets.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH std::fwgets 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - wchar_t* fgetws( wchar_t* str, int count, std::FILE* stream ); - - Reads at most count - 1 wide characters from the given file stream and stores them - in str. The produced wide string is always NULL-terminated. Parsing stops if - end-of-file occurs or a newline wide character is found, in which case str will - contain that wide newline character. - -.SH Parameters - - str - wide string to read the characters to - count - the length of str - stream - file stream to read the data from - -.SH Return value - - str on success, NULL on an error - -.SH See also - - wscanf reads formatted wide character input from stdin, a file stream or a buffer - fwscanf \fI(function)\fP - swscanf - fgetwc gets a wide character from a file stream - getwc \fI(function)\fP - fputws writes a wide string to a file stream - \fI(function)\fP - C documentation for - fgetws diff --git a/man/std::fwide.3 b/man/std::fwide.3 index fa2f5df15..4c277b43a 100644 --- a/man/std::fwide.3 +++ b/man/std::fwide.3 @@ -1,12 +1,18 @@ -.TH std::fwide 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fwide 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fwide \- std::fwide + .SH Synopsis Defined in header int fwide( std::FILE* stream, int mode ); If mode > 0, attempts to make stream wide-oriented. If mode < 0, attempts to make - stream byte-oriented. If mode==0, only queries the current orientation of the + stream byte-oriented. If mode == 0, only queries the current orientation of the stream. + If the orientation of the stream has already been decided (by executing output or by + an earlier call to fwide), this function does nothing. + .SH Parameters stream - pointer to the C I/O stream to modify or query @@ -19,9 +25,92 @@ than zero if the stream is byte-oriented after this call, and zero if the stream has no orientation. +.SH Example + + The following code sets and resets the stream orientation. + + +// Run this code + + #include + #include + #include + #include + + void show_orientation(int n) + { + n < 0 ? std::wcout << "\\tnarrow orientation\\n" : + n > 0 ? std::wcout << "\\twide orientation\\n" : + std::wcout << "\\tno orientation\\n"; + } + + void try_read(FILE* fp) + { + if (const int c = std::fgetc(fp); c == EOF) + std::wcout << "\\tnarrow character read failed\\n"; + else + std::wcout << "\\tnarrow character read '" << static_cast(c) << "'\\n"; + + if (const wint_t wc = std::fgetwc(fp); wc == WEOF) + std::wcout << "\\twide character read failed\\n"; + else + std::wcout << "\\twide character read '" << static_cast(wc) << "'\\n"; + } + + int main() + { + enum fwide_orientation : int { narrow = -1, query, wide }; + + FILE* fp = std::fopen("main.cpp", "r"); + if (!fp) + { + std::wcerr << "fopen() failed\\n"; + return EXIT_FAILURE; + } + + std::wcout << "1) A newly opened stream has no orientation.\\n"; + show_orientation(std::fwide(fp, fwide_orientation::query)); + + std::wcout << "2) Establish byte orientation.\\n"; + show_orientation(std::fwide(fp, fwide_orientation::narrow)); + try_read(fp); + + std::wcout << "3) Only freopen() can reset stream orientation.\\n"; + if (std::freopen("main.cpp", "r", fp) == NULL) + { + std::wcerr << "freopen() failed\\n"; + return EXIT_FAILURE; + } + + std::wcout << "4) A reopened stream has no orientation.\\n"; + show_orientation(std::fwide(fp, fwide_orientation::query)); + + std::wcout << "5) Establish wide orientation.\\n"; + show_orientation(std::fwide(fp, fwide_orientation::wide)); + try_read(fp); + + std::fclose(fp); + } + +.SH Possible output: + + 1) A newly opened stream has no orientation. + no orientation + 2) Establish byte orientation. + narrow orientation + narrow character read '#' + wide character read failed + 3) Only freopen() can reset stream orientation. + 4) A reopened stream has no orientation. + no orientation + 5) Establish wide orientation. + wide orientation + narrow character read failed + wide character read '#' + .SH See also fopen opens a file - \fI(function)\fP + \fI(function)\fP C documentation for fwide diff --git a/man/std::fwrite.3 b/man/std::fwrite.3 index b1502349d..614f25633 100644 --- a/man/std::fwrite.3 +++ b/man/std::fwrite.3 @@ -1,11 +1,14 @@ -.TH std::fwrite 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::fwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::fwrite \- std::fwrite + .SH Synopsis Defined in header std::size_t fwrite( const void* buffer, std::size_t size, std::size_t count, std::FILE* stream ); Writes up to count binary objects from the given array buffer to the output stream - stream. The objects are written as if by reinterepreting each object as an array of + stream. The objects are written as if by reinterpreting each object as an array of unsigned char and calling std::fputc size times for each object to write those unsigned chars into stream, in order. The file position indicator for the stream is advanced by the number of characters written. @@ -17,9 +20,10 @@ .SH Parameters - buffer - pointer to the first object object in the array to be written + buffer - pointer to the first object in the array to be written size - size of each object count - the number of the objects to be written + stream - output file stream to write to .SH Return value @@ -30,46 +34,50 @@ .SH Example - + // Run this code + #include #include - + #include + int main () { // write buffer to file - std::FILE *f1; - char buffer[] = { 'x' , 'y' , 'z' }; - f1 = std::fopen("file.bin", "wb"); - std::fwrite(buffer, sizeof(char), sizeof(buffer), f1); - std::fclose(f1); - + if (std::FILE* f1 = std::fopen("file.bin", "wb")) + { + std::array v = {42, -1, 7}; // underlying storage of std::array is an array + std::fwrite(v.data(), sizeof v[0], v.size(), f1); + std::fclose(f1); + } + // read the same data and print it to the standard output - std::FILE *f2; - char rbuf[10]; - f2 = std::fopen("file.bin", "rb"); - const char* res = std::fgets(rbuf, sizeof(rbuf), f2); - std::fclose(f2); - - if (res) { // points to rbuf on read success, NULL on failure - std::puts(res); + if (std::FILE* f2 = std::fopen("file.bin", "rb")) + { + std::vector rbuf(10); // underlying storage of std::vector is also an array + std::size_t sz = std::fread(rbuf.data(), sizeof rbuf[0], rbuf.size(), f2); + std::fclose(f2); + for (std::size_t n = 0; n < sz; ++n) + std::printf("%d\\n", rbuf[n]); } } .SH Output: - xyz + 42 + -1 + 7 .SH See also printf fprintf prints formatted output to stdout, a file stream or a buffer - sprintf \fI(function)\fP + sprintf \fI(function)\fP snprintf \fI(C++11)\fP fputs writes a character string to a file stream - \fI(function)\fP + \fI(function)\fP fread reads from a file - \fI(function)\fP + \fI(function)\fP C documentation for fwrite diff --git a/man/std::gamma_distribution.3 b/man/std::gamma_distribution.3 index 36d2883ec..8bc7d2fe0 100644 --- a/man/std::gamma_distribution.3 +++ b/man/std::gamma_distribution.3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution \- std::gamma_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -7,7 +10,8 @@ Produces random positive floating-point values x, distributed according to probability density function: - P(x|α,β) = + \\(\\mathsf{p}(x\\mid\\alpha,\\beta) = \\frac{e^{-x/\\beta} + }{\\beta^\\alpha\\cdot\\Gamma(\\alpha)}\\cdot x^{\\alpha-1} \\)P(x|α,β) = e-x/β βα @@ -15,52 +19,106 @@ · xα-1 - where α is known as the shape parameter and β is known as the scale parameter. + where α is known as the shape parameter and β is known as the scale parameter. The + shape parameter is sometimes denoted by the letter k and the scale parameter is + sometimes denoted by the letter θ. For floating-point α, the value obtained is the sum of α independent exponentially - distributed random variables, each of which has a mean of β + distributed random variables, each of which has a mean of β. + + std::gamma_distribution satisfies RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics alpha returns the distribution parameters - beta \fI(public member function)\fP + beta \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - This section is incomplete - Reason: no example -.SH External links - - Weisstein, Eric W. "Gamma Distribution." From MathWorld--A Wolfram Web Resource. +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::random_device rd; + std::mt19937 gen(rd()); + + // A gamma distribution with alpha = 1, and beta = 2 + // approximates an exponential distribution. + std::gamma_distribution<> d(1, 2); + + std::map hist; + for (int n = 0; n != 10000; ++n) + ++hist[2 * d(gen)]; + + for (auto const& [x, y] : hist) + if (y / 100.0 > 0.5) + std::cout << std::fixed << std::setprecision(1) + << x / 2.0 << '-' << (x + 1) / 2.0 << ' ' + << std::string(y / 100, '*') << '\\n'; + } + +.SH Possible output: + + 0.0-0.5 ********************** + 0.5-1.0 **************** + 1.0-1.5 ************* + 1.5-2.0 ********** + 2.0-2.5 ******** + 2.5-3.0 ****** + 3.0-3.5 ***** + 3.5-4.0 **** + 4.0-4.5 *** + 4.5-5.0 ** + 5.0-5.5 ** + 5.5-6.0 * + 6.0-6.5 * + 6.5-7.0 + 7.0-7.5 + 7.5-8.0 -.SH Category: +.SH External links - * Todo no example + Weisstein, Eric W. "Gamma Distribution." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::gamma_distribution::alpha,beta.3 b/man/std::gamma_distribution::alpha,beta.3 index 5d52d3f6e..c3ad408d9 100644 --- a/man/std::gamma_distribution::alpha,beta.3 +++ b/man/std::gamma_distribution::alpha,beta.3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution::alpha,beta 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::alpha,beta 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::alpha,beta \- std::gamma_distribution::alpha,beta + .SH Synopsis RealType alpha() const; \fB(1)\fP \fI(since C++11)\fP RealType beta() const; \fB(2)\fP \fI(since C++11)\fP @@ -16,10 +19,10 @@ .SH Return value - 1) Floating point value identifying the α parameter - 2) Floating point value identifying the β parameter + 1) Floating point value identifying the α parameter. + 2) Floating point value identifying the β parameter. .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::gamma_distribution::gamma_distribution.3 b/man/std::gamma_distribution::gamma_distribution.3 index 47b687cd6..0e781d218 100644 --- a/man/std::gamma_distribution::gamma_distribution.3 +++ b/man/std::gamma_distribution::gamma_distribution.3 @@ -1,15 +1,28 @@ -.TH std::gamma_distribution::gamma_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::gamma_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::gamma_distribution \- std::gamma_distribution::gamma_distribution + .SH Synopsis - explicit gamma_distribution( RealType alpha = 1.0, RealType beta = \fB(1)\fP \fI(since C++11)\fP - 1.0 ); - explicit gamma_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + gamma_distribution() : gamma_distribution(1.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit gamma_distribution( RealType alpha, RealType beta = 1.0 \fB(2)\fP \fI(since C++11)\fP + ); + explicit gamma_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses alpha and beta as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses alpha and beta as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters - alpha - the α distribution parameter (scale) - beta - the β distribution parameter (shape) + alpha - the α distribution parameter (shape) + beta - the β distribution parameter (scale) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::gamma_distribution::max.3 b/man/std::gamma_distribution::max.3 index c91b4fef6..01c1058c2 100644 --- a/man/std::gamma_distribution::max.3 +++ b/man/std::gamma_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::max \- std::gamma_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::gamma_distribution::min.3 b/man/std::gamma_distribution::min.3 index 8c5b4e12c..d268bb9c1 100644 --- a/man/std::gamma_distribution::min.3 +++ b/man/std::gamma_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::min \- std::gamma_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::gamma_distribution::operator().3 b/man/std::gamma_distribution::operator().3 index 05b1b1911..fb6179504 100644 --- a/man/std::gamma_distribution::operator().3 +++ b/man/std::gamma_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::operator() \- std::gamma_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::gamma_distribution::param.3 b/man/std::gamma_distribution::param.3 index 7272eb6a7..6b3c4b8d4 100644 --- a/man/std::gamma_distribution::param.3 +++ b/man/std::gamma_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::param \- std::gamma_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::gamma_distribution::reset.3 b/man/std::gamma_distribution::reset.3 index a2d289ce8..99ce3c137 100644 --- a/man/std::gamma_distribution::reset.3 +++ b/man/std::gamma_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::gamma_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gamma_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gamma_distribution::reset \- std::gamma_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::gcd.3 b/man/std::gcd.3 new file mode 100644 index 000000000..601987a98 --- /dev/null +++ b/man/std::gcd.3 @@ -0,0 +1,60 @@ +.TH std::gcd 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gcd \- std::gcd + +.SH Synopsis + Defined in header + template< class M, class N > \fI(since C++17)\fP + constexpr std::common_type_t gcd( M m, N n ); + + Computes the greatest common divisor of the integers m and n. + + If either M or N is not an integer type, or if either is (possibly cv-qualified) + bool, the program is ill-formed. + + If either |m| or |n| is not representable as a value of type std::common_type_t, the behavior is undefined. + +.SH Parameters + + m, n - integer values + +.SH Return value + + If both m and n are zero, returns zero. Otherwise, returns the greatest common + divisor of |m| and |n|. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_gcd_lcm 201606L \fI(C++17)\fP std::gcd, std::lcm + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr int p{2 * 2 * 3}; + constexpr int q{2 * 3 * 3}; + static_assert(2 * 3 == std::gcd(p, q)); + + static_assert(std::gcd( 6, 10) == 2); + static_assert(std::gcd( 6, -10) == 2); + static_assert(std::gcd(-6, -10) == 2); + + static_assert(std::gcd( 24, 0) == 24); + static_assert(std::gcd(-24, 0) == 24); + } + +.SH See also + + lcm computes the least common multiple of two integers + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::generate.3 b/man/std::generate.3 index 0bf75ac20..a85fac836 100644 --- a/man/std::generate.3 +++ b/man/std::generate.3 @@ -1,15 +1,34 @@ -.TH std::generate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::generate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generate \- std::generate + .SH Synopsis Defined in header template< class ForwardIt, class Generator > - void generate( ForwardIt first, ForwardIt last, Generator g ); + void generate( ForwardIt first, ForwardIt last, \fB(1)\fP (constexpr since C++20) + Generator g ); + template< class ExecutionPolicy, class ForwardIt, class + Generator > + + void generate( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, + Generator g ); - Assigns each element in range [first, last) a value generated by the given function - object g. + 1) Assigns each element in range [first, last) a value generated by the given + function object g. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to generate + policy - the execution policy to use. See execution policy for details. generator function object that will be called. The signature of the function should be equivalent to the following: @@ -17,70 +36,84 @@ Ret fun(); The type Ret must be such that an object of type ForwardIt can be - dereferenced and assigned a value of type Ret. + dereferenced and assigned a value of type Ret. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. - -.SH Return value - - \fI(none)\fP + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Complexity Exactly std::distance(first, last) invocations of g() and assignments. +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + .SH Possible implementation template + constexpr //< since C++20 void generate(ForwardIt first, ForwardIt last, Generator g) { - while (first != last) { - *first++ = g(); - } + for (; first != last; ++first) + *first = g(); } .SH Example - The following code fills a vector with random numbers: - // Run this code #include #include - #include - + #include + + void println(std::string_view fmt, const auto& v) + { + for (std::cout << fmt; const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + }; + + + int f() + { + static int i; + return ++i; + } + int main() { std::vector v(5); - std::generate(v.begin(), v.end(), std::rand); // Using the C function rand() - - std::cout << "v: "; - for (auto iv: v) { - std::cout << iv << " "; - } - std::cout << "\\n"; - + + std::generate(v.begin(), v.end(), f); + println("v: ", v); + // Initialize with default values 0,1,2,3,4 from a lambda function - int n(0); - std::generate(v.begin(), v.end(), [&]{ return n++; }); - - std::cout << "v: "; - for (auto iv: v) { - std::cout << iv << " "; - } - std::cout << "\\n"; + // Equivalent to std::iota(v.begin(), v.end(), 0); + std::generate(v.begin(), v.end(), [n = 0] () mutable { return n++; }); + println("v: ", v); } -.SH Possible output: +.SH Output: - v: 52894 15984720 41513563 41346135 51451456 + v: 1 2 3 4 5 v: 0 1 2 3 4 .SH See also - fill assigns a range of elements a certain value - \fI(function template)\fP - generate_n saves the result of N applications of a function - \fI(function template)\fP + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + assigns the results of successive function calls to N elements in a + generate_n range + \fI(function template)\fP + iota fills a range with successive increments of the starting value + \fI(C++11)\fP \fI(function template)\fP + ranges::generate saves the result of a function in a range + (C++20) (niebloid) diff --git a/man/std::generate_canonical.3 b/man/std::generate_canonical.3 index 440999636..d9a580074 100644 --- a/man/std::generate_canonical.3 +++ b/man/std::generate_canonical.3 @@ -1,18 +1,20 @@ -.TH std::generate_canonical 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::generate_canonical 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generate_canonical \- std::generate_canonical + .SH Synopsis - template< class RealType, size_t bits, class Generator > \fI(since C++11)\fP + Defined in header + template< class RealType, std::size_t Bits, class Generator > \fI(since C++11)\fP RealType generate_canonical( Generator& g ); - Generates a random floating point number in range [0; 1). + Generates a random floating point number in range [0, 1). - g() is called as many times as needed to generate enough entropy, i.e. at least - max(1, ⌈ min(b - 1, b - 2) / log - 2 R ⌉) times, where + To generate enough entropy, generate_canonical() will call g() exactly \\(\\small k\\)k + times, where \\(\\small k = \\max(1, \\lceil \\frac{b}{\\log_2 R} \\rceil)\\)k = max(1, ⌈ b + / log + 2 R ⌉) and - * b1 = std::numeric_limits::digits - * b2 = std::numeric_limits::bits + * b = std::min(Bits, std::size_t {std::numeric_limits::digits}), * R = g.max() - g.min() + 1. .SH Parameters @@ -21,37 +23,42 @@ .SH Return value - Floating point value in range [0; 1). + Floating point value in range [0, 1). .SH Exceptions - None except from those thrown by g + None except from those thrown by g. + +.SH Notes + + Some existing implementations have a bug where they may occasionally return 1.0 if + RealType is float GCC #63176 LLVM #18767 MSVC STL #1074. This is LWG issue 2524. .SH Example - produce random numbers with 10 bits of randomness: this may produce only 1024 - distinct values + Produce random numbers with 10 bits of randomness: this may produce only k * R + distinct values. + - // Run this code - #include #include - + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); - for(int n=0; n<10; ++n) { + for (int n = 0; n < 10; ++n) std::cout << std::generate_canonical(gen) << ' '; - } + std::cout << '\\n'; } -.SH Output: +.SH Possible output: 0.208143 0.824147 0.0278604 0.343183 0.0173263 0.864057 0.647037 0.539467 0.0583497 0.609219 .SH See also uniform_real_distribution produces real values evenly distributed across a range - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::generate_n.3 b/man/std::generate_n.3 index 7df68ad04..3beaa693e 100644 --- a/man/std::generate_n.3 +++ b/man/std::generate_n.3 @@ -1,82 +1,124 @@ -.TH std::generate_n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::generate_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generate_n \- std::generate_n + .SH Synopsis Defined in header - template< class OutputIt, class Size, class Generator > \fI(until C++11)\fP - void generate_n( OutputIt first, Size count, Generator g ); - template< class OutputIt, class Size, class Generator > \fI(since C++11)\fP - OutputIt generate_n( OutputIt first, Size count, Generator g ); + template< class OutputIt, class Size, class Generator > + OutputIt generate_n( OutputIt first, Size count, \fB(1)\fP (constexpr since C++20) + Generator g ); + template< class ExecutionPolicy, + + class ForwardIt, class Size, class Generator > + ForwardIt generate_n( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, Size count, + Generator g ); + + 1) Assigns values, generated by given function object g, to the first count elements + in the range beginning at first, if count > 0. Does nothing otherwise. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if - Assigns values, generated by given function object g, to the first count elements in - the range beginning at first, if count>0. Does nothing otherwise. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If Size is not convertible to an integral type, the program is ill-formed. .SH Parameters - first - the beginning of the range of elements to generate - count - number of the elements to generate - generator function object that will be called. + first - the beginning of the range of elements to generate + count - number of the elements to generate + policy - the execution policy to use. See execution policy for details. + generator function object that will be called. - The signature of the function should be equivalent to the following: - g - - Ret fun(); + The signature of the function should be equivalent to the following: + g - + Ret fun(); - The type Ret must be such that an object of type OutputIt can be - dereferenced and assigned a value of type Ret. + The type Ret must be such that an object of type OutputIt can be + dereferenced and assigned a value of type Ret. .SH Type requirements - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value - \fI(none)\fP \fI(until C++11)\fP - Iterator one past the last element assigned if count>0, first \fI(since C++11)\fP - otherwise. + Iterator one past the last element assigned if count > 0, first otherwise. .SH Complexity - Exactly count invocations of g() and assignments, for count>0. + Exactly std::max(0, count) invocations of g() and assignments. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template< class OutputIt, class Size, class Generator > - OutputIt generate_n( OutputIt first, Size count, Generator g ) + template + constexpr // since C++20 + OutputIt generate_n(OutputIt first, Size count, Generator g) { - for( Size i = 0; i < count; i++ ) { - *first++ = g(); - } + for (Size i = 0; i < count; ++i, ++first) + *first = g(); + return first; } .SH Example - The following code fills an array of integers with random numbers. - // Run this code - #include - #include + #include + #include #include #include - #include - + #include + int main() { - const std::size_t N = 5; - int ar[N]; - std::generate_n(ar, N, std::rand); // Using the C function rand() - - std::cout << "ar: "; - std::copy(ar, ar+N, std::ostream_iterator(std::cout, " ")); - std::cout << "\\n"; + std::mt19937 rng; // default constructed, seeded with fixed seed + std::generate_n(std::ostream_iterator(std::cout, " "), + 5, std::ref(rng)); + std::cout << '\\n'; } -.SH Possible output: +.SH Output: + + 3499211612 581869302 3890346734 3586334585 545404204 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - ar: 52894 15984720 41513563 41346135 51451456 + DR Applied to Behavior as published Correct behavior + the complexity requirement was “exactly no invocation or + LWG 426 C++98 count invocations assignment + or assignments”, which is broken if if count is non-positive + count is negative + the location of the first element + LWG 865 C++98 following returned + the generation range was not returned .SH See also - fill_n assigns a value to a number of elements - \fI(function template)\fP - generate saves the result of a function in a range - \fI(function template)\fP + fill_n copy-assigns the given value to N elements in a range + \fI(function template)\fP + assigns the results of successive function calls to every element + generate in a range + \fI(function template)\fP + ranges::generate_n saves the result of N applications of a function + (C++20) (niebloid) diff --git a/man/std::generator.3 b/man/std::generator.3 new file mode 100644 index 000000000..9cf2c280a --- /dev/null +++ b/man/std::generator.3 @@ -0,0 +1,197 @@ +.TH std::generator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator \- std::generator + +.SH Synopsis + Defined in header + template< + + class Ref, + class V = void, \fB(1)\fP (since C++23) + class Allocator = void > + class generator + + : public ranges::view_interface> + namespace pmr { + + template< class Ref, class V = void > + using generator = \fB(2)\fP (since C++23) + std::generator>; + + } + + 1) The class template std::generator presents a view of the elements yielded by the + evaluation of a coroutine. + 2) Convenience alias template for the generator using the polymorphic allocator. + + A std::generator generates a sequence of elements by repeatedly resuming the + coroutine from which it was returned. Each time a co_yield statement is evaluated, + the coroutine produces one element of the sequence. When the co_yield statement is + of the form co_yield ranges::elements_of(rng), each element of the range rng is + successively produced as an element of the sequence. + + std::generator models view and input_range. + + The behavior of a program that adds a specialization for std::generator is + undefined. + +.SH Template parameters + + Ref - the reference type (ranges::range_reference_t) of the generator. If V is + void, both the reference type and the value type are inferred from Ref + V - the value type (range_value_t) of the generator, or void + Allocator - an allocator type or void + + If Allocator is not void, then the behavior is undefined if Allocator does not meet + the Allocator requirements. + +.SH Member types + + Member type Definition + std::conditional_t, std::remove_cvref_t, + value (private) V>;. + (exposition-only member type*) + reference std::conditional_t, Ref&&, Ref>;. + (private) (exposition-only member type*) + yielded std::conditional_t, reference, const + reference&>. + +.SH Type requirements + - + std::allocator_traits::pointer is a pointer type. + - + value is a cv-unqualified object type. + - + reference is either a reference type, or a cv-unqualified object type that models + copy_constructible. + - + Let /*RRef*/ denote:std::remove_reference_t&&, if /*reference*/ is a + reference type, and /*reference*/ otherwise. + * std::common_reference_with is modeled. + * std::common_reference_with is modeled. + * std::common_reference_with is modeled. + + The program is ill-formed if any of these type requirements is not satisfied. + +.SH Member objects + + Member name Definition + Internally, each active instance of std::generator is associated with a + stack (handled as if by object of type + std::unique_ptr>>). + + * When begin is called, a new stack is created and the generator is + added to the stack. + active_ * When co_yield ranges::elements_of(rng) is evaluated in a generator + (private) body, rng is converted to a generator and added to the stack that + contains the enclosing generator. + * When a generator iterator is incremented, the coroutine at the top + of the associated stack is resumed. + * When a generator finishes (i.e. when final_suspend is called), it + is removed from the stack. + (exposition-only member object*) + coroutine_ a handle of type std::coroutine_handle + (private) (exposition-only member object*) + +.SH Member functions + + constructor constructs a generator object + \fI(public member function)\fP + destructor effectively destroys the entire stack of yielded generators + \fI(public member function)\fP + operator= assigns a generator object + \fI(public member function)\fP + resumes the initially suspended coroutine and returns an iterator to + begin its handle + \fI(public member function)\fP + end returns std::default_sentinel + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + + Nested classes + + promise_type the promise type + \fI(public member class)\fP + iterator the iterator type + (exposition-only member class*) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_generator 202207L (C++23) std::generator – synchronous coroutine generator + for ranges + +.SH Example + + Can be tried in Compiler Explorer + + +// Run this code + + #include + #include + + template + struct Tree + { + T value; + Tree *left{}, *right{}; + + std::generator traverse_inorder() const + { + if (left) + for (const T& x : left->traverse_inorder()) + co_yield x; + + co_yield value; + if (right) + for (const T& x : right->traverse_inorder()) + co_yield x; + } + }; + + int main() + { + Tree tree[] + { + {'D', tree + 1, tree + 2}, + // │ + // ┌───────────────┴────────────────┐ + // │ │ + {'B', tree + 3, tree + 4}, {'F', tree + 5, tree + 6}, + // │ │ + // ┌─────────┴─────────────┐ ┌───────────┴─────────────┐ + // │ │ │ │ + {'A'}, {'C'}, {'E'}, {'G'} + }; + + for (char x : tree->traverse_inorder()) + std::cout << x << ' '; + std::cout << '\\n'; + } + +.SH Output: + + A B C D E F G + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.8 Range generators [coro.generator] + +.SH See also + + noop_coroutine creates a coroutine handle that has no observable effects when + (C++20) resumed or destroyed + \fI(function)\fP diff --git a/man/std::generator::begin.3 b/man/std::generator::begin.3 new file mode 100644 index 000000000..8f708f13a --- /dev/null +++ b/man/std::generator::begin.3 @@ -0,0 +1,28 @@ +.TH std::generator::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::begin \- std::generator::begin + +.SH Synopsis + /*iterator*/ begin(); (since C++23) + + Pushes coroutine_ into *active_ stack, then evaluates coroutine_.resume(). + + Before invocation of begin() the coroutine_ must refer to a coroutine suspended at + its initial suspend point. + +.SH Return value + + An iterator whose coroutine_ member refers to the same coroutine as coroutine_ does. + +.SH Notes + + It is an undefined behavior to call begin() more than once on the same generator + object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::generator::end.3 b/man/std::generator::end.3 new file mode 100644 index 000000000..d3e6da80b --- /dev/null +++ b/man/std::generator::end.3 @@ -0,0 +1,20 @@ +.TH std::generator::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::end \- std::generator::end + +.SH Synopsis + std::default_sentinel_t end() const noexcept; (since C++23) + + Equivalent to return std::default_sentinel. + +.SH Return value + + A sentinel. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::generator::generator.3 b/man/std::generator::generator.3 new file mode 100644 index 000000000..8085bcfdb --- /dev/null +++ b/man/std::generator::generator.3 @@ -0,0 +1,28 @@ +.TH std::generator::generator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::generator \- std::generator::generator + +.SH Synopsis + generator( const generator& ) = delete; \fB(1)\fP (since C++23) + generator( generator&& other ) noexcept; \fB(2)\fP (since C++23) + + Constructs a generator. + + 1) The copy-constructor is deleted. + 2) The move-constructor that initializes the underlying coroutine_ with + std::exchange(other.coroutine_, {}), and the underlying stack of coroutine handles + (active_) with std::exchange(other.active_, nullptr). Note, that the iterators, + previously obtained from other, are not invalidated, but become iterators into + *this. + +.SH Parameters + + other - a generator object to be moved in + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::generator::iterator.3 b/man/std::generator::iterator.3 new file mode 100644 index 000000000..85ae9999c --- /dev/null +++ b/man/std::generator::iterator.3 @@ -0,0 +1,96 @@ +.TH std::generator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::iterator \- std::generator::iterator + +.SH Synopsis + class /*iterator*/; (since C++23) + (exposition only*) + + The return type of generator::begin. + + Models indirectly_readable and input_iterator. + +.SH Member types + + Member type Definition + value_type std::generator::value + difference_type std::ptrdiff_t + + Data members + + Member name Definition + coroutine_ A coroutine handle of type + (private) std::coroutine_handle. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + \fI(public member function)\fP + operator= assigns another iterator + \fI(public member function)\fP + operator* returns an underlying value + \fI(public member function)\fP + operator++ advances the iterator + operator++(int) \fI(public member function)\fP + +std::generator::iterator::iterator + + /*iterator*/( /*iterator*/&& other ) noexcept; (since C++23) + + Initializes coroutine_ with std::exchange(other.coroutine_, {});. + +std::generator::iterator::operator= + + /*iterator*/& operator=( /*iterator*/&& other ) noexcept; (since C++23) + + Equivalent to coroutine_ = std::exchange(other.coroutine_, {});. + + Returns: *this. + +std::generator::iterator::operator* + + reference operator*() const (since C++23) + noexcept( std::is_nothrow_copy_constructible_v ); + + 1. Let reference be the std::generator's underlying type. + 2. Let for some generator object x its coroutine_ be in the stack *x.active_. + 3. Let x.active_->top() refer to a suspended coroutine with promise object p. + + Equivalent to return static_cast(*p.value_);. + +std::generator::iterator::operator++ + + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + + 1) Let for some generator object x the coroutine_ be in the stack *x.active_. + Equivalent to x.active_->top().resume(). + Returns: *this. + 2) Equivalent to ++*this;. + +.SH Non-member functions + + operator== compares the underlying iterator with a sentinel + (C++23) \fI(function)\fP + +operator==(std::generator::iterator) + + friend bool operator==( const /*iterator*/& i, (since C++23) + std::default_sentinel_t ); + + Equivalent to return i.coroutine_.done();. + + The != operator is synthesized from operator==. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::generator::iterator is an + associated class of the arguments. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::generator::operator=.3 b/man/std::generator::operator=.3 new file mode 100644 index 000000000..5b6a31e86 --- /dev/null +++ b/man/std::generator::operator=.3 @@ -0,0 +1,42 @@ +.TH std::generator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::operator= \- std::generator::operator= + +.SH Synopsis + generator& operator=( generator other ) noexcept; (since C++23) + + Replaces the contents of the generator object. + + Equivalent to: + + std::swap(coroutine_, other.coroutine_); + std::swap(active_, other.active_); + +.SH Parameters + + other - another generator to be moved from + +.SH Return value + + *this + +.SH Complexity + + This section is incomplete + +.SH Notes + + Iterators previously obtained from other are not invalidated – they become iterators + into *this. + + This assignment operator is technically a copy assignment operator, although + std::generator is only move assignable. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::generator::promise_type.3 b/man/std::generator::promise_type.3 new file mode 100644 index 000000000..5ad0a8815 --- /dev/null +++ b/man/std::generator::promise_type.3 @@ -0,0 +1,46 @@ +.TH std::generator::promise_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type \- std::generator::promise_type + +.SH Synopsis + class generator::promise_type; (since C++23) + + The promise type of std::generator. + +.SH Member functions + + constructor constructs the promise_type object + (implicitly declared) \fI(public member function)\fP + destructor destroys the promise_type object + (implicitly declared) \fI(public member function)\fP + get_return_object issues the generator object + \fI(public member function)\fP + initial_suspend issues an awaiter for initial suspend point + \fI(public member function)\fP + final_suspend issues an awaiter for final suspend point + \fI(public member function)\fP + yield_value processes the object obtained from co_yield + \fI(public member function)\fP + await_transform maps the object obtained from co_await to an awaiter + [deleted] \fI(public member function)\fP + return_void handles co_return; or the exit out of coroutine's body + \fI(public member function)\fP + unhandled_exception processes exceptions that leaked from the coroutine's body + \fI(public member function)\fP + operator new allocates memory using Allocator + \fB[static]\fP (C++23) \fI(public static member function)\fP + operator delete deallocates memory previously obtained from operator new + \fB[static]\fP (C++23) \fI(public static member function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + noop_coroutine_promise used for coroutines with no observable effects + (C++20) \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::generator::promise_type::final_suspend.3 b/man/std::generator::promise_type::final_suspend.3 new file mode 100644 index 000000000..3d89a7e63 --- /dev/null +++ b/man/std::generator::promise_type::final_suspend.3 @@ -0,0 +1,28 @@ +.TH std::generator::promise_type::final_suspend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::final_suspend \- std::generator::promise_type::final_suspend + +.SH Synopsis + auto final_suspend() noexcept; (since C++23) + + Let x be some generator object. + + final_suspend does the following: + + 1. Pops the coroutine handle from the top of *active_. + 2. If *x.active_ is not empty, resumes execution of the coroutine referred to by + x.active_->top(). If it is empty, control flow returns to the current coroutine + caller or resumer. + + A handle referring to the coroutine whose promise object is *this must be at the top + of *x.active_ of x. This function must be called by the coroutine upon reaching its + final suspend point, otherwise the behavior is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An awaitable object of unspecified type whose member functions are configured to + suspend the calling coroutine. diff --git a/man/std::generator::promise_type::get_return_object.3 b/man/std::generator::promise_type::get_return_object.3 new file mode 100644 index 000000000..eece453f3 --- /dev/null +++ b/man/std::generator::promise_type::get_return_object.3 @@ -0,0 +1,18 @@ +.TH std::generator::promise_type::get_return_object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::get_return_object \- std::generator::promise_type::get_return_object + +.SH Synopsis + std::generator get_return_object() noexcept; (since C++23) + + Returns a generator object whose member coroutine_ is obtained via the expression + std::coroutine_handle::from_promise(*this), and whose member active_ + points to an empty stack. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The generator object. diff --git a/man/std::generator::promise_type::initial_suspend.3 b/man/std::generator::promise_type::initial_suspend.3 new file mode 100644 index 000000000..36b0e67c9 --- /dev/null +++ b/man/std::generator::promise_type::initial_suspend.3 @@ -0,0 +1,17 @@ +.TH std::generator::promise_type::initial_suspend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::initial_suspend \- std::generator::promise_type::initial_suspend + +.SH Synopsis + std::suspend_always initial_suspend() const noexcept; (since C++23) + + Equivalent to { return std::suspend_always{}; }, that is, std::generator always + starts lazily (in suspended state). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The awaitable object. diff --git a/man/std::generator::promise_type::operatordelete.3 b/man/std::generator::promise_type::operatordelete.3 new file mode 100644 index 000000000..af987fb48 --- /dev/null +++ b/man/std::generator::promise_type::operatordelete.3 @@ -0,0 +1,22 @@ +.TH std::generator::promise_type::operatordelete 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::operatordelete \- std::generator::promise_type::operatordelete + +.SH Synopsis + void operator delete( void* ptr, std::size_t n ) noexcept; (since C++23) + + Deallocates the storage pointed to by ptr using an allocator equivalent to that used + to allocate this memory. + + The ptr passed to this function must be the one returned from an invocation of one + of the operator new overloads with a size argument equal to n. Otherwise the + behavior is undefined. + +.SH Parameters + + ptr - a pointer obtained from the previous call to operator new + n - the size of the storage to be deallocated + +.SH Return value + + \fI(none)\fP diff --git a/man/std::generator::promise_type::operatornew.3 b/man/std::generator::promise_type::operatornew.3 new file mode 100644 index 000000000..611b0eafc --- /dev/null +++ b/man/std::generator::promise_type::operatornew.3 @@ -0,0 +1,63 @@ +.TH std::generator::promise_type::operatornew 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::operatornew \- std::generator::promise_type::operatornew + +.SH Synopsis + void* operator new( std::size_t size ) + + requires std::same_as || \fB(1)\fP (since C++23) + + std::default_initializable; + template< class Alloc, class... Args > + + requires std::same_as || + std::convertible_to \fB(2)\fP (since C++23) + void* operator new( std::size_t size, std::allocator_arg_t, + + const Alloc& alloc, const Args&... ); + template< class This, class Alloc, class... Args > + + requires std::same_as || + std::convertible_to \fB(3)\fP (since C++23) + void* operator new( std::size_t size, const This&, + std::allocator_arg_t, + + const Alloc& alloc, const Args&... ); + + Allocates size bytes of uninitialized storage using default or user-provided + allocator. + + Let A be + + * Allocator, if it is not void, + * Alloc for (2,3), or + * std::allocator otherwise. + + Let B be std::allocator_traits::template rebind_alloc where U is an + unspecified type whose size and alignment are both __STDCPP_DEFAULT_NEW_ALIGNMENT__. + + Initializes an allocator b of type B with: + + 1) A(), + 2,3) A(alloc). + + Uses b to allocate storage for the smallest array of U sufficient to provide storage + for a coroutine state of size size, and unspecified additional state necessary to + ensure that operator delete can later deallocate this memory block with an allocator + equal to b. + + Note: std::allocator_traits::pointer must be of a pointer type, otherwise the + behavior is undefined. + +.SH Parameters + + size - the size of the storage to allocate + alloc - a user provided allocator of type Alloc + +.SH Return value + + A pointer to the allocated storage. + +.SH Exceptions + + 1-3) May throw. diff --git a/man/std::generator::promise_type::return_void.3 b/man/std::generator::promise_type::return_void.3 new file mode 100644 index 000000000..dad34e58d --- /dev/null +++ b/man/std::generator::promise_type::return_void.3 @@ -0,0 +1,17 @@ +.TH std::generator::promise_type::return_void 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::return_void \- std::generator::promise_type::return_void + +.SH Synopsis + void return_void() const noexcept (since C++23) + + No-op. Equivalent to {}. A user provided coroutine that uses the generator cannot + issue a value via co_return operator or reaching the end of the coroutine body. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP diff --git a/man/std::generator::promise_type::unhandled_exception.3 b/man/std::generator::promise_type::unhandled_exception.3 new file mode 100644 index 000000000..8afc54160 --- /dev/null +++ b/man/std::generator::promise_type::unhandled_exception.3 @@ -0,0 +1,28 @@ +.TH std::generator::promise_type::unhandled_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::unhandled_exception \- std::generator::promise_type::unhandled_exception + +.SH Synopsis + void unhandled_exception(); (since C++23) + + Let x be some generator object. + + If a handle referring to the coroutine whose promise object is *this is at the top + of *active_ of x: + + * If the handle referring to the coroutine whose promise object is *this is the + only element of x.*active_, equivalent to throw. + * Otherwise, assigns std::current_exception() to except_. + * Otherwise, the behavior is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw. diff --git a/man/std::generator::promise_type::yield_value.3 b/man/std::generator::promise_type::yield_value.3 new file mode 100644 index 000000000..bedcdf344 --- /dev/null +++ b/man/std::generator::promise_type::yield_value.3 @@ -0,0 +1,81 @@ +.TH std::generator::promise_type::yield_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::promise_type::yield_value \- std::generator::promise_type::yield_value + +.SH Synopsis + std::suspend_always yield_value( yielded val ) noexcept; \fB(1)\fP (since + C++23) + auto yield_value( const std::remove_reference_t& lval ) + + requires std::is_rvalue_reference_v && \fB(2)\fP (since + std::constructible_from, C++23) + + const std::remove_reference_t&>; + template< class R2, class V2, class Alloc2, class Unused > + + requires std::same_as::yielded, yielded> \fB(3)\fP C++23) + auto yield_value( ranges::elements_of&&, + + Unused> g ) noexcept; + template< ranges::input_range R, class Alloc > + (since + requires std::convertible_to, yielded> \fB(4)\fP C++23) + + auto yield_value( ranges::elements_of r ) noexcept; + + An implementation of coroutine interface functions used internally to support + operator co_yield. + + (yielded is a reference type defined in std::generator.) + + 1) Assigns std::addressof(val) to value_. Returns {}. + 2) Returns an awaitable object of an unspecified type that stores an object of type + std::remove_cvref_t direct-non-list-initialized with lval, whose member + functions are configures so that value_ points to that stored object. Then suspends + the coroutine. + 3) Let x be some generator object. + + Returns an awaitable object of an unspecified type into which g.range is moved, + + * whose member await_ready returns false, + * whose member await_suspend pushes g.range.coroutine_ into *x.active_ and + * resumes execution of the coroutine referred to by g.range.coroutine_, and + * whose member await_resume evaluates + + * std::rethrow_exception(except_) if bool(except_) is true. + * If bool(except_) is false, the await_resume member has no effects. + The coroutine referred to by g.range.coroutine_ must be suspended at its initial + suspend point. Otherwise the behavior is undefined. + 4) Equivalent to: + + auto nested = [](std::allocator_arg_t, Alloc, ranges::iterator_t i, + ranges::sentinel_t s) -> + std::generator, Alloc> + { + for (; i != s; ++i) + co_yield static_cast(*i); + }; + + return yield_value(ranges::elements_of(nested( + allocator_arg, r.allocator, ranges::begin(r.range), ranges::end(r.range)))); + + 2,3) A handle referring to the coroutine whose promise object is *this must be at + the top of *active_ of some generator object. Otherwise the behavior is undefined. + 2-4) A yield-expression that calls these overload has the type void. + +.SH Parameters + + val - a value which is a result of the yield-expression evaluation + lval - an lvalue which is a result of the yield-expression evaluation + g - a range of elements produced by a generator + r - a range of elements + +.SH Return value + + 1) The awaitable object of type std::suspend_always. + 2-4) An awaitable object of an unspecified type as described above. + +.SH Exceptions + + 2) May throw any exception thrown by the initialization of the stored object. diff --git a/man/std::generator::~generator.3 b/man/std::generator::~generator.3 new file mode 100644 index 000000000..a4d082fac --- /dev/null +++ b/man/std::generator::~generator.3 @@ -0,0 +1,30 @@ +.TH std::generator::~generator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generator::~generator \- std::generator::~generator + +.SH Synopsis + ~generator(); (since C++23) + + Destructs the generator object. + + Given coroutine_ as the underlying coroutine object, equivalent to: + + if (coroutine_) + coroutine_.destroy(); + + Note, that destroying the root generator effectively destroys the entire stack of + yielded generators, because the ownership of recursively yielded generators is held + in awaitable objects in the coroutine frame of the yielding generator. + +.SH Complexity + + This section is incomplete + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * Todo without reason + * Todo no example diff --git a/man/std::generic_category.3 b/man/std::generic_category.3 index 946fa2494..9385c1b65 100644 --- a/man/std::generic_category.3 +++ b/man/std::generic_category.3 @@ -1,7 +1,10 @@ -.TH std::generic_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::generic_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::generic_category \- std::generic_category + .SH Synopsis Defined in header - const std::error_category& generic_category(); \fI(since C++11)\fP + const std::error_category& generic_category() noexcept; \fI(since C++11)\fP Obtains a reference to the static error category object for generic errors. The object is required to override the virtual function error_category::name() to return @@ -17,21 +20,16 @@ A reference to the static object of unspecified runtime type, derived from std::error_category. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code - #include - #include #include + #include #include + #include + int main() { std::error_condition econd = std::generic_category().default_error_condition(EDOM); @@ -49,7 +47,7 @@ .SH See also system_category identifies the operating system error category - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP errc the std::error_condition enumeration listing all standard \fI(C++11)\fP macro constants - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::geometric_distribution.3 b/man/std::geometric_distribution.3 index 33af2d773..6cfa876ea 100644 --- a/man/std::geometric_distribution.3 +++ b/man/std::geometric_distribution.3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution \- std::geometric_distribution + .SH Synopsis Defined in header template< class IntType = int > \fI(since C++11)\fP @@ -7,79 +10,94 @@ Produces random non-negative integer values i, distributed according to discrete probability function: - P(i|p) = p · (1 − p)i + \\(P(i|p) = p \\cdot (1-p)^i\\)P(i|p) = p · (1 − p)i - The value represents the number of yes/no trials (each succeeding with probability - p) which are necessary to obtain a single success. + The value represents the number of failures in a series of independent yes/no trials + (each succeeds with probability p), before exactly 1 success occurs. std::geometric_distribution<>(p) is exactly equivalent to std::negative_binomial_distribution<>(1, p). It is also the discrete counterpart of std::exponential_distribution. + std::geometric_distribution satisfies RandomNumberDistribution. + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + IntType - this is not one of short, int, long, long long, unsigned short, unsigned + int, unsigned long, or unsigned long long. + .SH Member types - Member type Definition - result_type IntType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP IntType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - returns the p distribution parameter (probability of a trial - p generating true) - \fI(public member function)\fP + p returns the p distribution parameter (probability of a trial + \fI(C++11)\fP generating true) + \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - geometric_distribution<>(0.5) is the default and represents the number of coin - tosses that are required to get heads + std::geometric_distribution<>(0.5) is the default and represents the number of coin + tosses that are required to get heads. + - // Run this code - #include #include - #include + #include #include #include + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); - - std::geometric_distribution<> d; // same as std::negative_binomial_distribution<> d(1, 0.5); - + + std::geometric_distribution<> d; + // same as + // std::negative_binomial_distribution<> d(1, 0.5): + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n = 0; n != 10000; ++n) ++hist[d(gen)]; - } - for(auto p : hist) { - std::cout << p.first << - ' ' << std::string(p.second/100, '*') << '\\n'; + + for (auto [x, y] : hist) + { + const char c = x < 10 ? x + '0' : x - 10 + 'a'; + std::cout << c << ' ' << std::string(y / 100, '*') << '\\n'; } } -.SH Output: +.SH Possible output: 0 ************************************************* 1 ************************* @@ -91,9 +109,8 @@ 7 8 9 - 10 - 11 .SH External links - Weisstein, Eric W. "Geometric Distribution." From MathWorld--A Wolfram Web Resource. + Weisstein, Eric W. "Geometric Distribution." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::geometric_distribution::geometric_distribution.3 b/man/std::geometric_distribution::geometric_distribution.3 index 062ca0ee0..506e76e99 100644 --- a/man/std::geometric_distribution::geometric_distribution.3 +++ b/man/std::geometric_distribution::geometric_distribution.3 @@ -1,10 +1,16 @@ -.TH std::geometric_distribution::geometric_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::geometric_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::geometric_distribution \- std::geometric_distribution::geometric_distribution + .SH Synopsis - explicit geometric_distribution( double p = 0.5 ); \fB(1)\fP \fI(since C++11)\fP - explicit geometric_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + geometric_distribution() : geometric_distribution(0.5) {} \fB(1)\fP \fI(since C++11)\fP + explicit geometric_distribution( double p ); \fB(2)\fP \fI(since C++11)\fP + explicit geometric_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs new distribution object. The first version uses p as the distribution - parameter, the second version uses params as the distribution parameter. + 2) Uses p as the distribution parameter. + 3) Uses params as the distribution parameter. .SH Parameters @@ -13,4 +19,12 @@ .SH Notes - Requires that 0 < p < 1 + Requires that 0 < p < 1. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::geometric_distribution::max.3 b/man/std::geometric_distribution::max.3 index 265596cd1..a3b6437e9 100644 --- a/man/std::geometric_distribution::max.3 +++ b/man/std::geometric_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::max \- std::geometric_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::geometric_distribution::min.3 b/man/std::geometric_distribution::min.3 index 8e192a297..29e5668e7 100644 --- a/man/std::geometric_distribution::min.3 +++ b/man/std::geometric_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::min \- std::geometric_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::geometric_distribution::operator().3 b/man/std::geometric_distribution::operator().3 index b1f4eaa5d..38ae79b23 100644 --- a/man/std::geometric_distribution::operator().3 +++ b/man/std::geometric_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::operator() \- std::geometric_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::geometric_distribution::p.3 b/man/std::geometric_distribution::p.3 index f1ee38681..a591028e3 100644 --- a/man/std::geometric_distribution::p.3 +++ b/man/std::geometric_distribution::p.3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution::p 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::p 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::p \- std::geometric_distribution::p + .SH Synopsis double p() const; \fI(since C++11)\fP @@ -16,5 +19,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::geometric_distribution::param.3 b/man/std::geometric_distribution::param.3 index dfcbe44b1..e5699a694 100644 --- a/man/std::geometric_distribution::param.3 +++ b/man/std::geometric_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::param \- std::geometric_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::geometric_distribution::reset.3 b/man/std::geometric_distribution::reset.3 index 7b62fc07f..e01f3f82f 100644 --- a/man/std::geometric_distribution::reset.3 +++ b/man/std::geometric_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::geometric_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::geometric_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::geometric_distribution::reset \- std::geometric_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::get(std::array).3 b/man/std::get(std::array).3 index 35acdb422..485aa87ee 100644 --- a/man/std::get(std::array).3 +++ b/man/std::get(std::array).3 @@ -1,13 +1,19 @@ -.TH std::get(std::array) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< size_t I, class T, size_t N > \fB(1)\fP \fI(since C++11)\fP - constexpr T& get( array& a ); - template< size_t I, class T, size_t N > \fB(2)\fP \fI(since C++11)\fP - constexpr T&& get( array&& a ); - template< size_t I, class T, size_t N > \fB(3)\fP \fI(since C++11)\fP - constexpr const T& get( const array& a ); +.TH std::get(std::array) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get(std::array) \- std::get(std::array) - Extracts the Ith element element from the array. +.SH Synopsis + Defined in header + template< std::size_t I, class T, std::size_t N > \fB(1)\fP \fI(since C++11)\fP + T& get( std::array& a ) noexcept; (constexpr since C++14) + template< std::size_t I, class T, std::size_t N > \fB(2)\fP \fI(since C++11)\fP + T&& get( std::array&& a ) noexcept; (constexpr since C++14) + template< std::size_t I, class T, std::size_t N > \fB(3)\fP \fI(since C++11)\fP + const T& get( const std::array& a ) noexcept; (constexpr since C++14) + template< std::size_t I, class T, std::size_t N > \fB(4)\fP \fI(since C++11)\fP + const T&& get( const std::array&& a ) noexcept; (constexpr since C++14) + + Extracts the I^th element from the array using tuple-like interface. I must be an integer value in range [0, N). This is enforced at compile time as opposed to at() or operator[]. @@ -18,56 +24,60 @@ .SH Return value - 1) Reference to the Ith element of a. - - 2) Rvalue reference to the Ith element of a, unless the element is of lvalue - reference type, in which case lvalue reference is returned. - - 3) Const reference to the Ith element of a. + A reference to the I^th element of a. -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - - -.SH Notes - - The overloads are marked as constexpr since C++14. + Constant. .SH Example - + // Run this code - #include #include - + #include + + constexpr std::array v{1, 2, 3}; + static_assert(get<0>(v) == 1 && get<1>(v) == 2 && get<2>(v) == 3); + int main() { - std::array arr; - + std::array a; + // set values: - std::get<0>(arr) = 1; - std::get<1>(arr) = 2; - std::get<2>(arr) = 3; - + get<0>(a) = 1, get<1>(a) = 2, get<2>(a) = 3; + // get values: - std::cout << "(" << std::get<0>(arr) << ", " << std::get<1>(arr) - << ", " << std::get<2>(arr) << ")\\n"; + std::cout << '(' << get<0>(a) << ',' << get<1>(a) << ',' << get<2>(a) << ")\\n"; } .SH Output: - (1, 2, 3) + (1,2,3) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2485 C++11 there are no overloads for const array&& the overloads are added .SH See also - operator[] access specified element - \fI(public member function)\fP - at access specified element with bounds checking - \fI(public member function)\fP - std::get(std::tuple) tuple accesses specified element - \fI(function template)\fP - std::get(std::pair) accesses an element of a pair - \fI(C++11)\fP \fI(function template)\fP + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple + elements of the initializer + operator[] access specified element + \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + get(std::tuple) tuple accesses specified element + \fI(C++11)\fP \fI(function template)\fP + get(std::pair) accesses an element of a pair + \fI(C++11)\fP \fI(function template)\fP + get(std::variant) reads the value of the variant given the index or the + \fI(C++17)\fP type (if the type is unique), throws on error + \fI(function template)\fP + get(std::ranges::subrange) obtains iterator or sentinel from a std::ranges::subrange + (C++20) \fI(function template)\fP diff --git a/man/std::get(std::complex).3 b/man/std::get(std::complex).3 new file mode 100644 index 000000000..a23afc596 --- /dev/null +++ b/man/std::get(std::complex).3 @@ -0,0 +1,45 @@ +.TH std::get(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get(std::complex) \- std::get(std::complex) + +.SH Synopsis + Defined in header + template< std::size_t I > \fB(1)\fP (since C++26) + friend constexpr T& get( std::complex& x ); + template< std::size_t I > \fB(2)\fP (since C++26) + friend constexpr const T& get( const std::complex& x ); + template< std::size_t I > \fB(3)\fP (since C++26) + friend constexpr T&& get( std::complex&& x ); + template< std::size_t I > \fB(4)\fP (since C++26) + friend constexpr const T&& get( const std::complex&& x ); + + Returns the reference to real or imaginary part from a complex when I == 0 or I == + 1, respectively. It is mainly provided for structured binding support. + +.SH Parameters + + x - a complex + +.SH Return value + + 1-4) A reference to the real or imaginary part from the stored one when I == 0 or I + == 1, respectively. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple + elements of the initializer + get(std::tuple) tuple accesses specified element + \fI(C++11)\fP \fI(function template)\fP + get(std::pair) accesses an element of a pair + \fI(C++11)\fP \fI(function template)\fP + get(std::array) accesses an element of an array + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::get(std::pair).3 b/man/std::get(std::pair).3 index dc508e66b..ecbd1f031 100644 --- a/man/std::get(std::pair).3 +++ b/man/std::get(std::pair).3 @@ -1,63 +1,58 @@ -.TH std::get(std::pair) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get(std::pair) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get(std::pair) \- std::get(std::pair) + .SH Synopsis - template< size_t N, class T1, class T2 > - (since - typename std::tuple_element \fB(1)\fP C++11) - >::type& (until - C++14) - get( pair& p ); - template< size_t N, class T1, class T2 > - - constexpr typename std::tuple_element >::type& C++14) - - get( pair& p ); - template< size_t N, class T1, class T2 > - (since - const typename std::tuple_element >::type& (until - C++14) - get( const pair& p ); - template< size_t N, class T1, class T2 > - - constexpr const typename std::tuple_element >::type& C++14) - - get( const pair& p ); - template< size_t N, class T1, class T2 > - (since - typename std::tuple_element \fB(1)\fP \fB(3)\fP C++11) - >::type&& (until - C++14) - get( std::pair&& p ); - template< size_t N, class T1, class T2 > - - constexpr typename std::tuple_element >::type&& C++14) - - get( std::pair&& p ); - template - - constexpr T& get(std::pair& p); \fB(3)\fP (since - \fB(4)\fP C++14) - template - - constexpr const T& get(const std::pair& p); - template \fB(5)\fP (since - constexpr T&& get(std::pair&& p); C++14) - template - - constexpr T& get(std::pair& p); (since - \fB(6)\fP C++14) - template - - constexpr const T& get(const std::pair& p); - template \fB(7)\fP (since - constexpr T&& get(std::pair&& p); C++14) - - Extracts a element from the pair using tuple-like interface. - - Type-based overloads 4-7 fail to compile if the types T and U are the same. + Defined in header + template< std::size_t I, class T1, class T2 > + + typename std::tuple_element \fB(1)\fP \fI(since C++11)\fP + >::type& (constexpr since C++14) + + get( std::pair& p ) noexcept; + template< std::size_t I, class T1, class T2 > + + const typename std::tuple_element \fB(2)\fP \fI(since C++11)\fP + >::type& (constexpr since C++14) + + get( const std::pair& p ) noexcept; + template< std::size_t I, class T1, class T2 > + + typename std::tuple_element \fB(3)\fP \fI(since C++11)\fP + >::type&& (constexpr since C++14) + + get( std::pair&& p ) noexcept; + template< std::size_t I, class T1, class T2 > + + const typename std::tuple_element \fB(4)\fP \fI(since C++11)\fP + >::type&& (constexpr since C++14) + + get( const std::pair&& p ) noexcept; + template< class T, class U > \fB(5)\fP \fI(since C++14)\fP + constexpr T& get( std::pair& p ) noexcept; + template< class T, class U > + constexpr const T& get( const std::pair& p ) \fB(6)\fP \fI(since C++14)\fP + noexcept; + template< class T, class U > \fB(7)\fP \fI(since C++14)\fP + constexpr T&& get( std::pair&& p ) noexcept; + template< class T, class U > + constexpr const T&& get( const std::pair&& p ) \fB(8)\fP \fI(since C++14)\fP + noexcept; + template< class T, class U > \fB(9)\fP \fI(since C++14)\fP + constexpr T& get( std::pair& p ) noexcept; + template< class T, class U > + constexpr const T& get( const std::pair& p ) \fB(10)\fP \fI(since C++14)\fP + noexcept; + template< class T, class U > \fB(11)\fP \fI(since C++14)\fP + constexpr T&& get( std::pair&& p ) noexcept; + template< class T, class U > + constexpr const T&& get( const std::pair&& p ) \fB(12)\fP \fI(since C++14)\fP + noexcept; + + Extracts an element from the pair using tuple-like interface. + + 1-4) The index-based overloads fail to compile if the index I is neither 0 nor 1. + 5-12) The type-based overloads fail to compile if the types T and U are the same. .SH Parameters @@ -65,28 +60,18 @@ .SH Return value - 1,2) Returns p.first if N==0 and p.second if N==1. - 3) Returns std::forward(p.first) if N==0 and std::forward(p.second) if - N==1 - 4) Returns std::get<0>(p) - 5) Returns std::get<0>(std::move(p)) - 6) Returns std::get<1>(p) - 7) Returns std::get<1>(std::move(p)) - -.SH Exceptions - - noexcept specification: - noexcept - + 1-4) Returns a reference to p.first if I == 0 and a reference to p.second if I == 1. + 5-8) Returns a reference to p.first. + 9-12) Returns a reference to p.second. .SH Example - + // Run this code #include #include - + int main() { auto p = std::make_pair(1, 3.14); @@ -99,9 +84,25 @@ (1, 3.14) (1, 3.14) + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2485 C++11 (by index) there are no overloads for const the overloads are added + C++14 (by type) pair&& + .SH See also - std::get(std::tuple) tuple accesses specified element - \fI(function template)\fP - std::get(std::array) accesses an element of an array - \fI(function template)\fP + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple + elements of the initializer + get(std::tuple) tuple accesses specified element + \fI(C++11)\fP \fI(function template)\fP + get(std::array) accesses an element of an array + \fI(C++11)\fP \fI(function template)\fP + get(std::variant) reads the value of the variant given the index or the + \fI(C++17)\fP type (if the type is unique), throws on error + \fI(function template)\fP + get(std::ranges::subrange) obtains iterator or sentinel from a std::ranges::subrange + (C++20) \fI(function template)\fP diff --git a/man/std::get(std::tuple).3 b/man/std::get(std::tuple).3 index 351a86b43..61ed85e95 100644 --- a/man/std::get(std::tuple).3 +++ b/man/std::get(std::tuple).3 @@ -1,47 +1,46 @@ -.TH std::get(std::tuple) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< std::size_t I, class... Types > - \fI(since C++11)\fP - typename std::tuple_element >::type& \fB(1)\fP \fI(until C++14)\fP +.TH std::get(std::tuple) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get(std::tuple) \- std::get(std::tuple) - get( tuple& t ); +.SH Synopsis + Defined in header template< std::size_t I, class... Types > + \fI(since C++11)\fP + typename std::tuple_element >::type& \fB(1)\fP (constexpr since C++14) - constexpr typename std::tuple_element >::type& \fB(1)\fP \fI(since C++14)\fP - - get( tuple& t ); + get( tuple& t ) noexcept; template< std::size_t I, class... Types > - \fI(since C++11)\fP - typename std::tuple_element >::type&& \fB(2)\fP \fI(until C++14)\fP + \fI(since C++11)\fP + typename std::tuple_element >::type&& \fB(2)\fP (constexpr since C++14) - get( tuple&& t ); + get( tuple&& t ) noexcept; template< std::size_t I, class... Types > - constexpr typename std::tuple_element >::type&& \fB(2)\fP \fI(since C++14)\fP + typename std::tuple_element >::type \fB(3)\fP \fI(since C++11)\fP + const& (constexpr since C++14) - get( tuple&& t ); + get( const tuple& t ) noexcept; template< std::size_t I, class... Types > - \fI(since C++11)\fP - typename std::tuple_element >::type const& \fB(3)\fP \fI(until C++14)\fP - - get( const tuple& t ); - template< std::size_t I, class... Types > - - constexpr typename std::tuple_element >::type \fB(3)\fP \fI(since C++14)\fP - const& - - get( const tuple& t ); - template< class T, class... Types > \fB(4)\fP \fI(since C++14)\fP - constexpr T& get(tuple& t); - template< class T, class... Types > \fB(5)\fP \fI(since C++14)\fP - constexpr T&& get(tuple&& t); - template< class T, class... Types > \fB(6)\fP \fI(since C++14)\fP - constexpr const T& get(const tuple& t); - 1-3) Extracts the Ith element element from the tuple. I is an integer value in [0, - sizeof...(Types)). - 4-6) Extracts the element of the tuple t whose type is T. Fails to compile if the - tuple has more than one element of that type. + typename std::tuple_element >::type \fB(4)\fP \fI(since C++11)\fP + const&& (constexpr since C++14) + + get( const tuple&& t ) noexcept; + template< class T, class... Types > \fB(5)\fP \fI(since C++14)\fP + constexpr T& get( tuple& t ) noexcept; + template< class T, class... Types > \fB(6)\fP \fI(since C++14)\fP + constexpr T&& get( tuple&& t ) noexcept; + template< class T, class... Types > + constexpr const T& get( const tuple& t ) \fB(7)\fP \fI(since C++14)\fP + noexcept; + template< class T, class... Types > + constexpr const T&& get( const tuple&& t ) \fB(8)\fP \fI(since C++14)\fP + noexcept; + + 1-4) Extracts the I^th element from the tuple. I must be an integer value in + [0, sizeof...(Types)). + 5-8) Extracts the element of the tuple t whose type is T. Fails to compile unless + the tuple has exactly one element of that type. .SH Parameters @@ -49,45 +48,68 @@ .SH Return value - 1,4) Reference to the selected element of t. - 2,5) Rvalue reference to the selected element of t, unless the element is of lvalue - reference type, in which case lvalue reference is returned. - 3,6) Const reference to the selected element of t. + A reference to the selected element of t. -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + Feature-test macro Value Std Feature + __cpp_lib_tuples_by_type 201304L \fI(C++14)\fP Addressing tuples by type .SH Example - + // Run this code #include #include #include - + int main() { auto t = std::make_tuple(1, "Foo", 3.14); - // index-based access - std::cout << "(" << std::get<0>(t) << ", " << std::get<1>(t) - << ", " << std::get<2>(t) << ")\\n"; - // type-based access - std::cout << "(" << std::get(t) << ", " << std::get(t) - << ", " << std::get(t) << ")\\n"; + + // Index-based access + std::cout << "( " << get<0>(t) + << ", " << get<1>(t) + << ", " << get<2>(t) + << " )\\n"; + + // Type-based access (C++14 or later) + std::cout << "( " << get(t) + << ", " << get(t) + << ", " << get(t) + << " )\\n"; + + // Note: std::tie and structured binding may also be used to decompose a tuple. } .SH Output: - (1, Foo, 3.14) - (1, Foo, 3.14) + ( 1, Foo, 3.14 ) + ( 1, Foo, 3.14 ) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2485 C++11 (by index) there are no overloads for const the overloads are added + C++14 (by type) tuple&& .SH See also - std::get(std::array) accesses an element of an array - \fI(function template)\fP - std::get(std::pair) accesses an element of a pair - \fI(C++11)\fP \fI(function template)\fP + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple + elements of the initializer + get(std::array) accesses an element of an array + \fI(C++11)\fP \fI(function template)\fP + get(std::pair) accesses an element of a pair + \fI(C++11)\fP \fI(function template)\fP + get(std::variant) reads the value of the variant given the index or the + \fI(C++17)\fP type (if the type is unique), throws on error + \fI(function template)\fP + get(std::ranges::subrange) obtains iterator or sentinel from a std::ranges::subrange + (C++20) \fI(function template)\fP + get(std::complex) obtains a reference to real or imaginary part from a + (C++26) std::complex + \fI(function template)\fP diff --git a/man/std::get(std::variant).3 b/man/std::get(std::variant).3 new file mode 100644 index 000000000..7630b3ca5 --- /dev/null +++ b/man/std::get(std::variant).3 @@ -0,0 +1,121 @@ +.TH std::get(std::variant) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get(std::variant) \- std::get(std::variant) + +.SH Synopsis + Defined in header + template< std::size_t I, class... Types > + + constexpr std::variant_alternative_t>& + + get( std::variant& v ); + template< std::size_t I, class... Types > + + constexpr std::variant_alternative_t>&& + + get( std::variant&& v ); + template< std::size_t I, class... Types > + + constexpr const std::variant_alternative_t>& + \fB(1)\fP \fI(since C++17)\fP + get( const std::variant& v ); + template< std::size_t I, class... Types > + + constexpr const std::variant_alternative_t>&& + + get( const std::variant&& v ); + template< class T, class... Types > + constexpr T& get( std::variant& v ); + template< class T, class... Types > + constexpr T&& get( std::variant&& v ); + template< class T, class... Types > \fB(2)\fP (since + constexpr const T& get( const std::variant& C++17) + v ); + template< class T, class... Types > + constexpr const T&& get( const + std::variant&& v ); + + 1) Index-based value accessor: If v.index() == I, returns a reference to the value + stored in v. Otherwise, throws std::bad_variant_access. The call is ill-formed if I + is not a valid index in the variant. + 2) Type-based value accessor: If v holds the alternative T, returns a reference to + the value stored in v. Otherwise, throws std::bad_variant_access. The call is + ill-formed if T is not a unique element of Types.... + +.SH Template parameters + + I - index to look up + T - unique type to look up + Types... - types forming the variant + +.SH Parameters + + v - a variant + +.SH Return value + + Reference to the value stored in the variant. + +.SH Exceptions + + 1,2) Throws std::bad_variant_access on errors. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::variant v{12}, w; + std::cout << std::get(v) << '\\n'; + w = std::get(v); + w = std::get<0>(v); // same effect as the previous line + + // std::get(v); // error: no double in [int, float] + // std::get<3>(v); // error: valid index values are 0 and 1 + + try + { + w = 42.0f; + std::cout << std::get(w) << '\\n'; // ok, prints 42 + w = 42; + std::cout << std::get(w) << '\\n'; // throws + } + catch (std::bad_variant_access const& ex) + { + std::cout << ex.what() << ": w contained int, not float\\n"; + } + } + +.SH Possible output: + + 12 + 42 + Unexpected index: w contained int, not float + +.SH See also + + obtains a pointer to the value of a pointed-to variant + get_if given the index or the type (if unique), returns null on + \fI(C++17)\fP error + \fI(function template)\fP + get(std::tuple) tuple accesses specified element + \fI(C++11)\fP \fI(function template)\fP + get(std::array) accesses an element of an array + \fI(C++11)\fP \fI(function template)\fP + get(std::pair) accesses an element of a pair + \fI(C++11)\fP \fI(function template)\fP + get(std::ranges::subrange) obtains iterator or sentinel from a std::ranges::subrange + (C++20) \fI(function template)\fP + +.SH Category: + * Uses of dcl rev begin with nonempty note diff --git a/man/std::get_deleter.3 b/man/std::get_deleter.3 index 1c61f73ef..036000f9c 100644 --- a/man/std::get_deleter.3 +++ b/man/std::get_deleter.3 @@ -1,12 +1,16 @@ -.TH std::get_deleter 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_deleter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_deleter \- std::get_deleter + .SH Synopsis - template - Deleter* get_deleter(const shared_ptr & p); + Defined in header + template< class Deleter, class T > \fI(since C++11)\fP + Deleter* get_deleter( const std::shared_ptr& p ) noexcept; Access to the p's deleter. If the shared pointer p owns a deleter of type - cv-unqualified D (e.g. if it was created with one of the constructors that take a - deleter as a parameter), then returns a pointer to the deleter. Otherwise, returns a - null pointer. + cv-unqualified Deleter (e.g. if it was created with one of the constructors that + take a deleter as a parameter), then returns a pointer to the deleter. Otherwise, + returns a null pointer. .SH Parameters @@ -14,14 +18,8 @@ .SH Return value - A pointer to the owned deleter or 0. The returned pointer is valid at least as long - as there remains at least one shared_ptr instance that owns it. - -.SH Exceptions - - noexcept specification: - noexcept - + A pointer to the owned deleter or nullptr. The returned pointer is valid at least as + long as there remains at least one shared_ptr instance that owns it. .SH Notes @@ -31,25 +29,25 @@ .SH Example - demonstrates that shared_ptr deleter is independent of the shared_ptr's type + Demonstrates that std::shared_ptr deleter is independent of the shared_ptr's type. + - // Run this code #include #include - + struct Foo { int i; }; - void foo_deleter(Foo * p) + void foo_deleter(Foo* p) { std::cout << "foo_deleter called!\\n"; delete p; } - + int main() { std::shared_ptr aptr; - + { // create a shared_ptr that owns a Foo and a deleter auto foo_p = new Foo; @@ -57,14 +55,15 @@ aptr = std::shared_ptr(r, &r->i); // aliasing ctor // aptr is now pointing to an int, but managing the whole Foo } // r gets destroyed (deleter not called) - + // obtain pointer to the deleter: - if(auto del_p = std::get_deleter(aptr)) + if (auto del_p = std::get_deleter(aptr)) { std::cout << "shared_ptr owns a deleter\\n"; - if(*del_p == foo_deleter) + if (*del_p == foo_deleter) std::cout << "...and it equals &foo_deleter\\n"; - } else + } + else std::cout << "The deleter of shared_ptr is null!\\n"; } // deleter called here @@ -78,3 +77,5 @@ constructor std::shared_ptr constructors \fI(public member function)\fP + get_deleter returns the deleter that is used for destruction of the managed object + \fI(public member function of std::unique_ptr)\fP diff --git a/man/std::get_if(std::variant).3 b/man/std::get_if(std::variant).3 new file mode 100644 index 000000000..2d1ada347 --- /dev/null +++ b/man/std::get_if(std::variant).3 @@ -0,0 +1,83 @@ +.TH std::get_if(std::variant) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_if(std::variant) \- std::get_if(std::variant) + +.SH Synopsis + Defined in header + template< std::size_t I, class... Types > + + constexpr std::add_pointer_t>> + + get_if( std::variant* pv ) noexcept; + template< std::size_t I, class... Types > + + constexpr std::add_pointer_t>> + \fB(1)\fP (since + get_if( const std::variant* pv ) noexcept; C++17) + template< class T, class... Types > + + constexpr std::add_pointer_t + + get_if( std::variant* pv ) noexcept; \fB(2)\fP (since + template< class T, class... Types > C++17) + + constexpr std::add_pointer_t + + get_if( const std::variant* pv ) noexcept; + + 1) Index-based non-throwing accessor: If pv is not a null pointer and pv->index() == + I, returns a pointer to the value stored in the variant pointed to by pv. Otherwise, + returns a null pointer value. The call is ill-formed if I is not a valid index in + the variant. + 2) Type-based non-throwing accessor: Equivalent to \fB(1)\fP with I being the zero-based + index of T in Types.... The call is ill-formed if T is not a unique element of + Types.... + +.SH Parameters + + I - index to look up + Type - unique type to look up + pv - pointer to a variant + +.SH Return value + + Pointer to the value stored in the pointed-to variant or null pointer on error. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto check_value = [](const std::variant& v) + { + if (const int* pval = std::get_if(&v)) + std::cout << "variant value: " << *pval << '\\n'; + else + std::cout << "failed to get value!" << '\\n'; + }; + + std::variant v{12}, w{3.f}; + check_value(v); + check_value(w); + } + +.SH Output: + + variant value: 12 + failed to get value! + +.SH See also + + get(std::variant) reads the value of the variant given the index or the type (if the + \fI(C++17)\fP type is unique), throws on error + \fI(function template)\fP + +.SH Category: + * Uses of dcl rev begin with nonempty note diff --git a/man/std::get_money.3 b/man/std::get_money.3 index 1e1731180..c0fa84d5d 100644 --- a/man/std::get_money.3 +++ b/man/std::get_money.3 @@ -1,4 +1,7 @@ -.TH std::get_money 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_money 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_money \- std::get_money + .SH Synopsis Defined in header template< class MoneyT > \fI(since C++11)\fP @@ -8,48 +11,67 @@ a monetary value, as specified by the std::money_get facet of the locale currently imbued in in, and stores the value in mon. - This function behaves as a FormattedInputFunction. + The extraction operation in in >> get_money(mon, intl) behaves as a + FormattedInputFunction. .SH Parameters mon - variable where monetary value will be written. Can be either long double or - basic_string + std::basic_string intl - expects to find required international currency strings if true, expects optional currency symbols otherwise .SH Return value - Returns an object of unspecified type such that if in is the name of an output - stream of type std::basic_istream, then the expression in >> - get_money(mon, intl) behaves as if the following code was executed: + An object of unspecified type such that + + * if in is an object of type std::basic_istream, the expression in + >> get_money(mon, intl) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, mon, intl) + + where the function f is defined as: + + template + void f(std::basic_ios& str, MoneyT& mon, bool intl) + { + using Iter = std::istreambuf_iterator; + using MoneyGet = std::money_get; + + std::ios_base::iostate err = std::ios_base::goodbit; + const MoneyGet& mg = std::use_facet(str.getloc()); - typedef std::istreambuf_iterator Iter; - typedef std::money_get MoneyGet; - std::ios_base::iostate err = std::ios_base::goodbit; - const MoneyGet &mg = std::use_facet(in.getloc()); - mg.get(Iter(in.rdbuf()), Iter(), intl, in, err, mon); - if (std::ios_base::goodbit != err) - out.setstate(err); + mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon); + + if (err != std::ios_base::goodbit) + str.setstate(err); + } .SH Example - + // Run this code + #include #include - #include #include - #include + #include + int main() { std::istringstream in("$1,234.56 2.22 USD 3.33"); long double v1, v2; std::string v3; + in.imbue(std::locale("en_US.UTF-8")); in >> std::get_money(v1) >> std::get_money(v2) >> std::get_money(v3, true); - - std::cout << '"' << in.str() << "\\" parsed as: " - << v1 << ", " << v2 << ", " << v3 << '\\n'; + + if (in) + std::cout << std::quoted(in.str()) << " parsed as: " + << v1 << ", " << v2 << ", " << v3 << '\\n'; + else + std::cout << "Parse failed"; } .SH Output: @@ -59,6 +81,6 @@ .SH See also money_get parses and constructs a monetary value from an input character sequence - \fI(class template)\fP + \fI(class template)\fP put_money formats and outputs a monetary value - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::get_new_handler.3 b/man/std::get_new_handler.3 index b295f6320..bdc6564b0 100644 --- a/man/std::get_new_handler.3 +++ b/man/std::get_new_handler.3 @@ -1,10 +1,17 @@ -.TH std::get_new_handler 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_new_handler 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_new_handler \- std::get_new_handler + .SH Synopsis Defined in header - std::new_handler get_new_handler(); \fI(since C++11)\fP + std::new_handler get_new_handler() noexcept; \fI(since C++11)\fP Returns the currently installed new-handler, which may be a null pointer. + This function is thread-safe. Previous call to std::set_new_handler + synchronizes-with (see std::memory_order) the subsequent calls to + std::get_new_handler. + .SH Parameters \fI(none)\fP @@ -13,17 +20,11 @@ The currently installed new-handler, which may be a null pointer value. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP set_new_handler registers a new handler - \fI(function)\fP + \fI(function)\fP new_handler function pointer type of the new handler - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::get_pointer_safety.3 b/man/std::get_pointer_safety.3 index e8b13f0ae..158e32a67 100644 --- a/man/std::get_pointer_safety.3 +++ b/man/std::get_pointer_safety.3 @@ -1,7 +1,11 @@ -.TH std::get_pointer_safety 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_pointer_safety 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_pointer_safety \- std::get_pointer_safety + .SH Synopsis Defined in header - std::pointer_safety get_pointer_safety() \fI(since C++11)\fP + std::pointer_safety get_pointer_safety() noexcept; \fI(since C++11)\fP + (removed in C++23) Obtains the implementation-defined pointer safety model, which is a value of type std::pointer_safety. @@ -14,13 +18,37 @@ The pointer safety used by this implementation. -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "Pointer safety: "; + switch (std::get_pointer_safety()) + { + case std::pointer_safety::strict: + std::cout << "strict\\n"; + break; + case std::pointer_safety::preferred: + std::cout << "preferred\\n"; + break; + case std::pointer_safety::relaxed: + std::cout << "relaxed\\n"; + break; + } + } + +.SH Possible output: - noexcept specification: - noexcept - + Pointer safety: relaxed .SH See also - pointer_safety lists pointer safety models - \fI(C++11)\fP \fI(class)\fP + pointer_safety lists pointer safety models + \fI(C++11)\fP \fI(enum)\fP + (removed in C++23) diff --git a/man/std::get_temporary_buffer.3 b/man/std::get_temporary_buffer.3 index e3068cba7..d0389f372 100644 --- a/man/std::get_temporary_buffer.3 +++ b/man/std::get_temporary_buffer.3 @@ -1,53 +1,89 @@ -.TH std::get_temporary_buffer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_temporary_buffer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_temporary_buffer \- std::get_temporary_buffer + .SH Synopsis Defined in header template< class T > - std::pair< T*, std::ptrdiff_t > get_temporary_buffer( std::ptrdiff_t count ) - Allocates storage sufficient to store up to count adjacent objects of type T. If - there is insufficient memory for all count objects, allocates less than count, if - possible. + std::pair \fI(until C++11)\fP + + get_temporary_buffer( std::ptrdiff_t count ); + template< class T > + \fI(since C++11)\fP + std::pair (deprecated in C++17) + (removed in C++20) + get_temporary_buffer( std::ptrdiff_t count ) noexcept; + + If count is negative or zero, does nothing. + + Otherwise, requests to allocate uninitialized contiguous storage for count adjacent + objects of type T. The request is non-binding, and the implementation may instead + allocate the storage for any other number of (including zero) adjacent objects of + type T. + + It is implementation-defined whether over-aligned types are supported. \fI(since C++11)\fP .SH Parameters - count - the number of objects to allocate + count - the desired number of objects .SH Return value - An std::pair holding a pointer to the beginning of the allocated storage and the - number of objects that fit in the storage that was actually allocated (may be zero). + A std::pair, the member first is a pointer to the beginning of the allocated storage + and the member second is the number of objects that fit in the storage that was + actually allocated. + + If count <= 0 or allocated storage is not enough to store a single element of type + T, the member first of the result is a null pointer and the member second is zero. -.SH Exceptions +.SH Notes - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + This API was originally designed with the intent of providing a more efficient + implementation than the general-purpose operator new, but no such implementation was + created and the API was deprecated and removed. .SH Example - - + + // Run this code #include #include + #include #include #include - + int main() { const std::string s[] = {"string", "1", "test", "..."}; - std::string* p = std::get_temporary_buffer(4).first; - - std::copy(std::begin(s), std::end(s), - std::raw_storage_iterator(p)); - - for (std::string* i = p; i != p+4; ++i) { - std::cout << *i << '\\n'; - i->~basic_string(); - } - std::return_temporary_buffer(p); + const auto p = std::get_temporary_buffer(4); + // requires that p.first is passed to return_temporary_buffer + // (beware of early exit points and exceptions), or better use: + std::unique_ptr on_exit(p.first, + [](std::string* p) + { + std::cout << "returning temporary buffer...\\n"; + std::return_temporary_buffer(p); + }); + + std::copy(s, s + p.second, + std::raw_storage_iterator(p.first)); + // has same effect as: std::uninitialized_copy(s, s + p.second, p.first); + // requires that each string in p is individually destroyed + // (beware of early exit points and exceptions) + + std::copy(p.first, p.first + p.second, + std::ostream_iterator{std::cout, "\\n"}); + + std::for_each(p.first, p.first + p.second, [](std::string& e) + { + e.~basic_string(); + }); // same as: std::destroy(p.first, p.first + p.second); + + // manually reclaim memory if unique_ptr-like technique is not used: + // std::return_temporary_buffer(p.first); } .SH Output: @@ -56,8 +92,24 @@ 1 test ... + returning temporary buffer... + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 425 C++98 the behavior when count <= 0 was unclear made clear + LWG 2072 C++98 it was not allowed to allocate insufficient allowed + memory .SH See also return_temporary_buffer frees uninitialized storage - \fI(function template)\fP + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) + allocates storage at least as large as the requested size + allocate_at_least via an allocator + \fB[static]\fP (C++23) \fI\fI(public static member\fP function of\fP + std::allocator_traits) diff --git a/man/std::get_terminate.3 b/man/std::get_terminate.3 index 95f2aae0d..ec49caf7b 100644 --- a/man/std::get_terminate.3 +++ b/man/std::get_terminate.3 @@ -1,10 +1,16 @@ -.TH std::get_terminate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_terminate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_terminate \- std::get_terminate + .SH Synopsis Defined in header - std::terminate_handler get_terminate(); \fI(since C++11)\fP + std::terminate_handler get_terminate() noexcept; \fI(since C++11)\fP Returns the currently installed std::terminate_handler, which may be a null pointer. + This function is thread-safe. Prior call to std::set_terminate \fI(since C++11)\fP + synchronizes-with (see std::memory_order) this function. + .SH Parameters \fI(none)\fP @@ -13,15 +19,9 @@ The currently installed std::terminate_handler. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also terminate_handler the type of the function called by std::terminate - \fI(typedef)\fP + \fI(typedef)\fP set_terminate changes the function to be called by std::terminate - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::get_time.3 b/man/std::get_time.3 index 6d5c53484..c0a091002 100644 --- a/man/std::get_time.3 +++ b/man/std::get_time.3 @@ -1,13 +1,16 @@ -.TH std::get_time 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_time \- std::get_time + .SH Synopsis Defined in header - template< class CharT > \fI(since C++11)\fP - /*unspecified*/ get_time( std::tm* tmb, const CharT* fmt); + template< class CharT > \fI(since C++11)\fP + /*unspecified*/ get_time( std::tm* tmb, const CharT* fmt ); When used in an expression in >> get_time(tmb, fmt), parses the character input as a date/time value according to format string fmt according to the std::time_get facet - of the locale currently imbued in the output stream out. The resultant value is - stored in a std::tm object pointed to by tmb. + of the locale currently imbued in the input stream in. The resultant value is stored + in a std::tm object pointed to by tmb. .SH Parameters @@ -26,9 +29,9 @@ Conversion Explanation Writes to fields specifier % matches a literal %. The full conversion \fI(none)\fP - specification must be %%. - t matches any whitespace. \fI(none)\fP - n matches any whitespace. \fI(none)\fP + specification must be %% + t matches any whitespace \fI(none)\fP + n matches any whitespace \fI(none)\fP Year Y parses full year as a 4 digit decimal number, tm_year leading zeroes permitted but not required @@ -76,12 +79,12 @@ Day of the year/month parses day of the year as a decimal number (range j [001,366]), leading zeroes permitted but not tm_yday - fmt - required - parses the day of the month as a decimal number + required + fmt - parses the day of the month as a decimal number d (range [01,31]), leading zeroes permitted but not tm_mday required parses the day of the month using the alternative - Od numeric system, e.g 二十七 parses as 23 in ja_JP tm_mday + Od numeric system, e.g. 二十七 parses as 27 in ja_JP tm_mday locale, leading zeroes permitted but not required e synonym of d tm_mday Oe synonym of Od tm_mday @@ -142,48 +145,79 @@ tm_sec p parses the locale's equivalent of a.m. or p.m. tm_hour + Note: tm_isdst is not written to, and needs to be set explicitly for use with + functions such as mktime + .SH Return value - Returns an object of unspecified type such that if in is the name of an input stream - of type std::basic_istream, then the expression in >> get_time(tmb, - fmt) behaves as if the following code was executed: + An object of unspecified type such that + + * if in is an object of type std::basic_istream, the expression in + >> get_time(tmb, fmt) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, tmb, fmt) + + where the function f is defined as: + + template + void f(std::basic_ios& str, std::tm* tmb, const CharT* fmt) + { + using Iter = std::istreambuf_iterator; + using TimeGet = time_get; + + std::ios_base::iostate err = std::ios_base::goodbit; + const TimeGet& tg = std::use_facet(str.getloc()); + + tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb, + fmt, fmt + Traits::length(fmt)); + + if (err != std::ios_base::goodbit) + str.setstate(err); + } + +.SH Notes - typedef std::istreambuf_iterator Iter; - typedef std::time_get TimeGet; - std::ios_base::iostate err = std::ios_base::goodbit; - const TimeGet& tg = std::use_facet(in.getloc()); - tg.get(Iter(in.rdbuf()), Iter(), in, err, tmb, fmt, fmt + traits::length(fmt)); - if (err != std::ios_base::goodbit) - in.setstate(err); + As specified in std::time_get::do_get, which this function calls, it's unspecified + if this function zero out the fields in *tmb that are not set directly by the + conversion specifiers that appear in fmt: portable programs should initialize every + field of *tmb to zero before calling std::get_time. .SH Example - + Note: choose clang or gcc >= 12.1 to observe the output. libstdc++ before 12.1 does + not correctly implement the %b specifier: bug #78714. + + // Run this code + #include #include - #include #include - #include - #include - + #include + int main() { - std::tm t; + std::tm t = {}; std::istringstream ss("2011-Februar-18 23:12:34"); - ss.imbue(std::locale("de_DE")); + ss.imbue(std::locale("de_DE.utf-8")); ss >> std::get_time(&t, "%Y-%b-%d %H:%M:%S"); - std::cout << std::put_time(&t, "%c") << '\\n'; + + if (ss.fail()) + std::cout << "Parse failed\\n"; + else + std::cout << std::put_time(&t, "%c") << '\\n'; } -.SH Output: +.SH Possible output: Sun Feb 18 23:12:34 2011 .SH See also - parses time/date values from an input character sequence into struct - time_get std::tm - \fI(class template)\fP + time_get parses time/date values from an input character sequence into std::tm + \fI(class template)\fP put_time formats and outputs a date/time value according to the specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + parse parses a chrono object from a stream + (C++20) \fI(function template)\fP diff --git a/man/std::get_unexpected.3 b/man/std::get_unexpected.3 index 7246079bc..1d5d239ea 100644 --- a/man/std::get_unexpected.3 +++ b/man/std::get_unexpected.3 @@ -1,11 +1,19 @@ -.TH std::get_unexpected 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::get_unexpected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::get_unexpected \- std::get_unexpected + .SH Synopsis Defined in header - std::unexpected_handler get_unexpected(); \fI(since C++11)\fP\fB(deprecated)\fP + \fI(since C++11)\fP + std::unexpected_handler get_unexpected() noexcept; \fB(deprecated)\fP + (removed in C++17) Returns the currently installed std::unexpected_handler, which may be a null pointer. + This function is thread-safe. Prior call to std::set_unexpected synchronizes-with + (see std::memory_order) the subsequent calls to this function. + .SH Parameters \fI(none)\fP @@ -14,15 +22,9 @@ The currently installed std::unexpected_handler. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also unexpected_handler the type of the function called by std::unexpected - \fB(deprecated)\fP \fI(typedef)\fP + (removed in C++17) \fI(typedef)\fP set_unexpected changes the function to be called by std::unexpected - \fB(deprecated)\fP \fI(function)\fP + (removed in C++17) \fI(function)\fP diff --git a/man/std::getchar.3 b/man/std::getchar.3 index aa62ddeb3..d4a7fbda5 100644 --- a/man/std::getchar.3 +++ b/man/std::getchar.3 @@ -1,4 +1,7 @@ -.TH std::getchar 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::getchar 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::getchar \- std::getchar + .SH Synopsis Defined in header int getchar(); @@ -16,12 +19,54 @@ The obtained character on success or EOF on failure. If the failure has been caused by end of file condition, additionally sets the eof - indicator (see feof()) on stdin. If the failure has been caused by some other error, - sets the error indicator (see ferror()) on stdin. + indicator (see std::feof()) on stdin. If the failure has been caused by some other + error, sets the error indicator (see std::ferror()) on stdin. + +.SH Example + + std::getchar with error checking. Exit program by entering ESC char. + + #include + #include + #include + #include + #include + + int main() + { + for (int ch; (ch = std::getchar()) != EOF ;) // read/print "abc" from stdin + { + if (std::isprint(ch)) + std::cout << static_cast(ch) << '\\n'; + if (ch == 27) // 'ESC' (escape) in ASCII + return EXIT_SUCCESS; + } + + // Test reason for reaching EOF. + if (std::feof(stdin)) // if failure caused by end-of-file condition + std::cout << "End of file reached\\n"; + else if (std::ferror(stdin)) // if failure caused by some other error + { + std::perror("getchar()"); + std::cerr << "getchar() failed in file " << std::quoted(__FILE__) + << " at line # " << __LINE__ - 14 << '\\n'; + std::exit(EXIT_FAILURE); + } + + return EXIT_SUCCESS; + } + +.SH Possible output: + + abc + a + b + c + ^[ .SH See also fgetc gets a character from a file stream - getc \fI(function)\fP + getc \fI(function)\fP C documentation for getchar diff --git a/man/std::getenv.3 b/man/std::getenv.3 index 34dd61c02..416202fc1 100644 --- a/man/std::getenv.3 +++ b/man/std::getenv.3 @@ -1,7 +1,10 @@ -.TH std::getenv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::getenv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::getenv \- std::getenv + .SH Synopsis Defined in header - const char* getenv( const char* env_var ); + char* getenv( const char* env_var ); Searches the environment list provided by the host environment (the OS), for a string that matches the C string pointed to by env_var and returns a pointer to the @@ -17,8 +20,7 @@ unsetenv(), and putenv() would introduce a data race if called without synchronization. - Modifying the string returned by getenv (e.g. after casting away constness) invokes - undefined behavior. + Modifying the string returned by getenv invokes undefined behavior. .SH Parameters @@ -33,20 +35,21 @@ .SH Notes On POSIX systems, the environment variables are also accessible through the global - variable environ, declared as extern char **environ; in , and through the + variable environ, declared as extern char** environ; in , and through the optional third argument, envp, of the main function. .SH Example - + // Run this code - #include #include - - int main(int argc, char *argv[]) + #include + + int main() { - std::cout << "Your PATH is: " << std::getenv("PATH") << std::endl; + if (const char* env_p = std::getenv("PATH")) + std::cout << "Your PATH is: " << env_p << '\\n'; } .SH Possible output: diff --git a/man/std::getline.3 b/man/std::getline.3 index b2e42eb17..0f474542b 100644 --- a/man/std::getline.3 +++ b/man/std::getline.3 @@ -1,42 +1,41 @@ -.TH std::getline 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::getline 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::getline \- std::getline + .SH Synopsis Defined in header template< class CharT, class Traits, class Allocator > - std::basic_istream& getline( - std::basic_istream& input, \fB(1)\fP - - std::basic_string& str, + std::basic_istream& + getline( std::basic_istream& input, \fB(1)\fP - CharT delim ); + std::basic_string& str, + CharT delim ); template< class CharT, class Traits, class Allocator > - std::basic_istream& getline( - std::basic_istream&& input, \fB(1)\fP \fI(since C++11)\fP - - std::basic_string& str, + std::basic_istream& + getline( std::basic_istream&& input, \fB(2)\fP \fI(since C++11)\fP - CharT delim ); + std::basic_string& str, + CharT delim ); template< class CharT, class Traits, class Allocator > - std::basic_istream& getline( - std::basic_istream& input, \fB(2)\fP + std::basic_istream& \fB(3)\fP + getline( std::basic_istream& input, - - std::basic_string& str ); + std::basic_string& str ); template< class CharT, class Traits, class Allocator > - std::basic_istream& getline( - std::basic_istream&& input, \fB(2)\fP \fI(since C++11)\fP + std::basic_istream& \fB(4)\fP \fI(since C++11)\fP + getline( std::basic_istream&& input, - - std::basic_string& str ); + std::basic_string& str ); getline reads characters from an input stream and places them into a string: - 1) Behaves as UnformattedInputFunction, except that input.gcount() is not affected. - After constructing and checking the sentry object, performs the following: - 1) Calls str.erase() + 1,2) Behaves as UnformattedInputFunction, except that input.gcount() is not + affected. After constructing and checking the sentry object, performs the following: + 1) Calls str.erase(). 2) Extracts characters from input and appends them to str until one of the following occurs (checked in the order listed) a) end-of-file condition on input, in which case, getline sets eofbit. @@ -47,8 +46,8 @@ and returns. 3) If no characters were extracted for whatever reason (not even the discarded delimiter), getline sets failbit and returns. - 2) Same as getline(input, str, input.widen(’\\n’)), that is, the default delimiter is - the endline character. + 3,4) Same as getline(input, str, input.widen('\\n')), that is, the default delimiter + is the endline character. .SH Parameters @@ -62,25 +61,30 @@ .SH Notes - When used immediately after whitespace-delimited input, e.g. after int n; std::cin - >> n;, getline consumes the endline character left on the input stream by - operator>>, and returns immediately. A common solution is to ignore all leftover - characters on the line of input with - cin.ignore(std::numeric_limits::max(), '\\n'); before switching to - line-oriented input. + When consuming whitespace-delimited input (e.g. int n; std::cin >> n;) any + whitespace that follows, including a newline character, will be left on the input + stream. Then when switching to line-oriented input, the first line retrieved with + getline will be just that whitespace. In the likely case that this is unwanted + behaviour, possible solutions include: + + * An explicit extraneous initial call to getline. + * Removing consecutive whitespace with std::cin >> std::ws. + * Ignoring all leftover characters on the line of input with + cin.ignore(std::numeric_limits::max(), '\\n');. .SH Example - The following example demonstrates how to use getline function to read user's input - and how to process file line by line. + The following example demonstrates how to use the getline function to read user + input, and to process a stream line by line, or by parts of a line using the delim + parameter. + - // Run this code - #include #include #include - + #include + int main() { // greet the user @@ -88,20 +92,44 @@ std::cout << "What is your name? "; std::getline(std::cin, name); std::cout << "Hello " << name << ", nice to meet you.\\n"; - + // read file line by line std::istringstream input; input.str("1\\n2\\n3\\n4\\n5\\n6\\n7\\n"); int sum = 0; - for (std::string line; std::getline(input, line); ) { + for (std::string line; std::getline(input, line);) sum += std::stoi(line); - } - std::cout << "\\nThe sum is: " << sum << "\\n"; + std::cout << "\\nThe sum is " << sum << ".\\n\\n"; + + // use separator to read parts of the line + std::istringstream input2; + input2.str("a;b;c;d"); + for (std::string line; std::getline(input2, line, ';');) + std::cout << line << '\\n'; } .SH Possible output: What is your name? John Q. Public Hello John Q. Public, nice to meet you. - - The sum is 28 + + The sum is 28. + + a + b + c + d + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 91 C++98 getline did not behave as an unformatted behaves as an unformatted + input function input function + +.SH See also + + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::gets.3 b/man/std::gets.3 index 2ca01e2b4..331315b44 100644 --- a/man/std::gets.3 +++ b/man/std::gets.3 @@ -1,7 +1,11 @@ -.TH std::gets 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gets 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gets \- std::gets + .SH Synopsis Defined in header - char* gets( char* str ); \fI(until C++14)\fP + char* gets( char* str ); (deprecated in C++11) + (removed in C++14) Reads stdin into given character string until a newline character is found or end-of-file occurs. @@ -12,7 +16,7 @@ .SH Return value - str on success, NULL on failure. + str on success, a null pointer on failure. If the failure has been caused by end of file condition, additionally sets the eof indicator (see std::feof()) on stdin. If the failure has been caused by some other @@ -20,20 +24,67 @@ .SH Notes - The function provides no means to prevent buffer overflow of the destination array, - given sufficiently long input string. std::gets was deprecated in C++11 and removed - from C++14. + The std::gets() function does not perform bounds checking. Therefore, this function + is extremely vulnerable to buffer-overflow attacks. It cannot be used safely (unless + the program runs in an environment which restricts what can appear on stdin). For + this reason, the function was deprecated in C++11 and removed altogether in C++14. + std::fgets() may be used instead. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::puts("Never use std::gets(). Use std::fgets() instead!"); + + std::array buf; + + std::printf("Enter a string:\\n>"); + + if (std::fgets(buf.data(), buf.size(), stdin)) + { + const auto len = std::strlen(buf.data()); + std::printf( + "The input string:\\n[%s] is %s and has the length %li characters.\\n", + buf.data(), len + 1 < buf.size() ? "not truncated" : "truncated", len + ); + } + else if (std::feof(stdin)) + { + std::puts("Error: the end of stdin stream has been reached."); + } + else if (std::ferror(stdin)) + { + std::puts("I/O error when reading from stdin."); + } + else + { + std::puts("Unknown stdin error."); + } + } + +.SH Possible output: - std::fgets can be used instead. + Never use std::gets(). Use std::fgets() instead! + Enter a string: + >Living on Earth is expensive, but it does include a free trip around the Sun. + The input string: + [Living on Earth] is truncated and has the length 15 characters. .SH See also scanf reads formatted input from stdin, a file stream or a buffer - fscanf \fI(function)\fP + fscanf \fI(function)\fP sscanf fgets gets a character string from a file stream - \fI(function)\fP + \fI(function)\fP fputs writes a character string to a file stream - \fI(function)\fP + \fI(function)\fP C documentation for gets diff --git a/man/std::getwchar.3 b/man/std::getwchar.3 index 57f89a347..97538b5ed 100644 --- a/man/std::getwchar.3 +++ b/man/std::getwchar.3 @@ -1,7 +1,10 @@ -.TH std::getwchar 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::getwchar 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::getwchar \- std::getwchar + .SH Synopsis Defined in header - wint_t getwchar(); + std::wint_t getwchar(); Reads the next wide character from stdin. @@ -11,14 +14,14 @@ .SH Return value - The obtained wide character or WEOF if an error has occurred or the end of file + The obtained wide character, or WEOF if an error has occurred or the end of file reached .SH See also getchar reads a character from stdin - \fI(function)\fP + \fI(function)\fP fgetwc gets a wide character from a file stream - getwc \fI(function)\fP + getwc \fI(function)\fP C documentation for getwchar diff --git a/man/std::gmtime.3 b/man/std::gmtime.3 index d1581cb81..633ca53d3 100644 --- a/man/std::gmtime.3 +++ b/man/std::gmtime.3 @@ -1,4 +1,7 @@ -.TH std::gmtime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gmtime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gmtime \- std::gmtime + .SH Synopsis Defined in header std::tm* gmtime( const std::time_t* time ); @@ -12,9 +15,9 @@ .SH Return value - Pointer to a static internal std::tm object on success, or NULL otherwise. The - structure may be shared between std::gmtime, std::localtime, and std::ctime and may - be overwritten on each invocation. + Pointer to a static internal std::tm object on success, or null pointer otherwise. + The structure may be shared between std::gmtime, std::localtime, and std::ctime and + may be overwritten on each invocation. .SH Notes @@ -25,28 +28,39 @@ .SH Example - + // Run this code - #include - #include #include - + #include + #include + #include + int main() { - std::time_t t = std::time(NULL); + setenv("TZ", "/usr/share/zoneinfo/Europe/London", 1); // POSIX-specific + + std::tm tm{}; // get_time does not set all fields hence {} + tm.tm_year = 2020 - 1900; // 2020 + tm.tm_mon = 7 - 1; // July + tm.tm_mday = 15; // 15th + tm.tm_hour = 10; + tm.tm_min = 15; + tm.tm_isdst = 1; // Daylight saving in London + std::time_t t = std::mktime(&tm); + std::cout << "UTC: " << std::put_time(std::gmtime(&t), "%c %Z") << '\\n'; std::cout << "local: " << std::put_time(std::localtime(&t), "%c %Z") << '\\n'; } -.SH Output: +.SH Possible output: - UTC: Wed Dec 28 11:44:28 2011 GMT - local: Wed Dec 28 06:44:28 2011 EST + UTC: Wed Jul 15 09:15:00 2020 GMT + local: Wed Jul 15 10:15:00 2020 BST .SH See also localtime converts time since epoch to calendar time expressed as local time - \fI(function)\fP + \fI(function)\fP C documentation for gmtime diff --git a/man/std::greater.3 b/man/std::greater.3 index 00a254ca5..7ced8455c 100644 --- a/man/std::greater.3 +++ b/man/std::greater.3 @@ -1,46 +1,29 @@ -.TH std::greater 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::greater 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::greater \- std::greater + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct greater; - template< class T = void > \fI(since C++14)\fP - struct greater; - - Function object for performing comparisons. Unless specialized, invokes operator> on - type T. - -.SH Specializations - - If the built-in operator> does not provide total order for pointers, a partial - specialization of std::greater for pointer types is provided, which guarantees total - order. - - The standard library provides a specialization of std::greater when T - is not specified, which leaves the parameter types and return type to - be deduced. - \fI(since C++14)\fP - function object implementing x > y deducing argument and - greater return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class greater; -.SH Member types - - type definition - result_type bool - first_argument_type T - second_argument_type T + std::greater is a specialization of std::greater with parameter and return + type deduced. .SH Member functions - operator() checks if the first argument is greater than the second + operator() tests if lhs compares greater than rhs \fI(public member function)\fP - std::greater::operator() +std::greater::operator() + + template< class T, class U > - bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const - Checks whether lhs is greater than rhs. + -> decltype(std::forward(lhs) > std::forward(rhs)); + + Returns the result of std::forward(lhs) > std::forward(rhs). .SH Parameters @@ -48,15 +31,46 @@ .SH Return value - true if lhs > rhs, false otherwise. + std::forward(lhs) > std::forward(rhs). + + If a built-in operator comparing pointers is called, the result is consistent with + the implementation-defined strict total order over pointers. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + + constexpr bool strictly_positive(int lhs) + { + return std::greater<>()(lhs, 0); + } + + int main() + { + constexpr std::int64_t low = 0B11; + constexpr std::uint16_t high = 0X11; + std::greater<> greater{}; + static_assert(greater(high, low)); + + constexpr static auto arr = {0, 1, 2, 3, 4, 5}; + static_assert(!std::all_of(arr.begin(), arr.end(), strictly_positive)); + static_assert(std::all_of(arr.begin() + 1, arr.end(), strictly_positive)); + } + + Defect reports -.SH Possible implementation + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - constexpr bool operator()(const T &lhs, const T &rhs) const - { - return lhs > rhs; - } + DR Applied to Behavior as published Correct behavior + LWG 2562 C++98 the pointer total order might be guaranteed to be consistent + inconsistent diff --git a/man/std::greater.3 b/man/std::greater.3 deleted file mode 100644 index 30ead089b..000000000 --- a/man/std::greater.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::greater 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class greater; - - std::greater<> is a specialization of std::greater with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() tests if the lhs compares greater than rhs - \fI(public member function)\fP - - std::greater<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) > std::forward(rhs)); - - Returns the result of lhs > rhs. - -.SH Parameters - - lhs, rhs - values to compare - -.SH Return value - - The result of lhs > rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::greater_equal.3 b/man/std::greater_equal.3 index 4c8a82b0e..c85528939 100644 --- a/man/std::greater_equal.3 +++ b/man/std::greater_equal.3 @@ -1,4 +1,7 @@ -.TH std::greater_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::greater_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::greater_equal \- std::greater_equal + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -6,36 +9,31 @@ template< class T = void > \fI(since C++14)\fP struct greater_equal; - Function object for performing comparisons. Unless specialized, invokes operator>= - on type T. + Function object for performing comparisons. The main template invokes operator>= on + type T. .SH Specializations - If the built-in operator<= does not provide total order for pointers, a partial - specialization of std::greater_equal for pointer types is provided, which guarantees - total order. - - The standard library provides a specialization of std::greater_equal - when T is not specified, which leaves the parameter types and return - type to be deduced. - \fI(since C++14)\fP - function object implementing x >= y deducing - greater_equal argument and return types - \fI(class template specialization)\fP + greater_equal function object implementing x >= y deducing parameter and + \fI(C++14)\fP return types + \fI(class template specialization)\fP .SH Member types - type definition - result_type bool - first_argument_type T - second_argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) bool + first_argument_type (deprecated in C++17)(removed in C++20) T + second_argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Member functions operator() checks if the first argument is greater than or equal to the second \fI(public member function)\fP - std::greater_equal::operator() +std::greater_equal::operator() bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP @@ -48,15 +46,34 @@ .SH Return value - true if lhs >= rhs, false otherwise. + lhs >= rhs. + + If T is a pointer type, the result is consistent with the implementation-defined + strict total order over pointers. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr bool operator()(const T &lhs, const T &rhs) const + constexpr bool operator()(const T& lhs, const T& rhs) const { - return lhs >= rhs; + return lhs >= rhs; // assumes that the implementation handles pointer total order } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2562 C++98 the pointer total order might be guaranteed to be consistent + inconsistent + +.SH See also + + less function object implementing x < y + \fI(class template)\fP + ranges::greater_equal constrained function object implementing x >= y + (C++20) \fI(class)\fP diff --git a/man/std::greater_equal.3 b/man/std::greater_equal.3 deleted file mode 100644 index 5548bc994..000000000 --- a/man/std::greater_equal.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::greater_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class greater_equal; - - std::greater_equal<> is a specialization of std::greater_equal with parameter and - return type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() tests if the lhs compares greater or equal than rhs - \fI(public member function)\fP - - std::greater_equal<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) >= std::forward(rhs)); - - Returns the result of lhs >= rhs. - -.SH Parameters - - lhs, rhs - values to compare - -.SH Return value - - The result of lhs >= rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::gslice.3 b/man/std::gslice.3 index 8fc0b6437..03680c810 100644 --- a/man/std::gslice.3 +++ b/man/std::gslice.3 @@ -1,4 +1,7 @@ -.TH std::gslice 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gslice 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gslice \- std::gslice + .SH Synopsis Defined in header class gslice; @@ -17,20 +20,23 @@ j). For example, a gslice with starting index 3, strides {19,4,1} and lengths {2,4,3} - generates the following set of indices: + generates the following set of 24=2*4*3 indices: 3 + 0*19 + 0*4 + 0*1 = 3, 3 + 0*19 + 0*4 + 1*1 = 4, 3 + 0*19 + 0*4 + 2*1 = 5, 3 + 0*19 + 1*4 + 0*1 = 7, 3 + 0*19 + 1*4 + 1*1 = 8, + 3 + 0*19 + 1*4 + 2*1 = 9, + 3 + 0*19 + 2*4 + 0*1 = 11, ... + 3 + 1*19 + 3*4 + 1*1 = 35, 3 + 1*19 + 3*4 + 2*1 = 36 It is possible to construct std::gslice objects that select some indices more than - once: if the above example used the strides {1,1,1} , the indices would have been - {3, 4, 5, 4, 5, 6, ...} . Such gslices may only be used as arguments to the const - version of std::valarray::operator[], otherwise the behavior is undefined. + once: if the above example used the strides {1,1,1}, the indices would have been {3, + 4, 5, 4, 5, 6, ...}. Such gslices may only be used as arguments to the const version + of std::valarray::operator[], otherwise the behavior is undefined. .SH Member functions @@ -40,12 +46,12 @@ size \fI(public member function)\fP stride - std::gslice::gslice +std::gslice::gslice - gslice() - gslice( std::size_t start, const std::valarray& sizes, + gslice() \fB(1)\fP + gslice( std::size_t start, const std::valarray& sizes, \fB(2)\fP const std::valarray& strides ); - gslice( const gslice& other ); + gslice( const gslice& other ); \fB(3)\fP Constructs a new generic slice. @@ -63,7 +69,7 @@ in each dimension other - another slice to copy - std::slice::start, size, stride +std::slice::start, size, stride std::size_t start() const; \fB(1)\fP std::valarray size() const; \fB(2)\fP @@ -86,73 +92,76 @@ .SH Example - demonstrates the use of gslices to address columns of a 3D array + Demonstrates the use of gslices to address columns of a 3D array: + - // Run this code #include #include - void test_print(std::valarray& v, int rows, int cols, int planes) + + void test_print(std::valarray& v, int planes, int rows, int cols) { - for(int r=0; r v = // 3d array: 2 x 4 x 3 elements - { 111,112,113 , 121,122,123 , 131,132,133 , 141,142,143, - 211,212,213 , 221,222,223 , 231,232,233 , 241,242,243}; + {111,112,113 , 121,122,123 , 131,132,133 , 141,142,143, + 211,212,213 , 221,222,223 , 231,232,233 , 241,242,243}; // int ar3d[2][4][3] std::cout << "Initial 2x4x3 array:\\n"; test_print(v, 2, 4, 3); - + // update every value in the first columns of both planes - v[std::gslice(0, {2, 4}, {4*3, 3})] = 1; // two level one strides of 12 elements - // then four level two strides of 3 elements - + v[std::gslice(0, {2, 4}, {4 * 3, 3})] = 1; // two level one strides of 12 elements + // then four level two strides of 3 elements + // subtract the third column from the second column in the 1st plane - v[std::gslice(1, {1, 4}, {4*3, 3})] -= v[std::gslice(2, {1, 4}, {4*3, 3})]; - - std::cout << "After column operations: \\n"; + v[std::gslice(1, {1, 4}, {4 * 3, 3})] -= v[std::gslice(2, {1, 4}, {4 * 3, 3})]; + + std::cout << "\\n" "After column operations:\\n"; test_print(v, 2, 4, 3); } .SH Output: Initial 2x4x3 array: - 111 112 113 - 121 122 123 - 131 132 133 - 141 142 143 - - 211 212 213 - 221 222 223 - 231 232 233 - 241 242 243 - + 111 112 113 211 212 213 + 121 122 123 221 222 223 + 131 132 133 231 232 233 + 141 142 143 241 242 243 + After column operations: - 1 -1 113 - 1 -1 123 - 1 -1 133 - 1 -1 143 - - 1 212 213 - 1 222 223 - 1 232 233 - 1 242 243 + 1 -1 113 1 212 213 + 1 -1 123 1 222 223 + 1 -1 133 1 232 233 + 1 -1 143 1 242 243 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 543 C++98 it was unclear whether a default it is usable (as an empty + constructed generic slice is usable subset) .SH See also operator[] get/set valarray element, slice, or mask - \fI(public member function)\fP + \fI(public member function)\fP slice BLAS-like slice of a valarray: starting index, length, stride - \fI(class)\fP + \fI(class)\fP gslice_array proxy to a subset of a valarray after applying a gslice - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::gslice_array.3 b/man/std::gslice_array.3 index 70fff697f..bb25fbb17 100644 --- a/man/std::gslice_array.3 +++ b/man/std::gslice_array.3 @@ -1,11 +1,14 @@ -.TH std::gslice_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gslice_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gslice_array \- std::gslice_array + .SH Synopsis Defined in header template< class T > class gslice_array; - std::gslice_array is a helper template used by std::gslice subscript operator. It - has reference semantics to a subset of the array specified by the std::gslice - object. + std::gslice_array is a helper template used by the valarray subscript operator with + std::gslice argument. It has reference semantics to a subset of the array specified + by the std::gslice object. .SH Member types @@ -15,17 +18,17 @@ .SH Member functions constructor constructs a gslice_array - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a gslice_array - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP operator+= operator-= operator*= operator/= operator%= performs arithmetic operation on the array referred by generic slice. - operator&= \fI(public member function)\fP + operator&= \fI(public member function)\fP operator|= operator^= operator<<= @@ -33,14 +36,65 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - slice_array proxy to a subset of a valarray after applying a slice - \fI(class template)\fP + #include + #include + #include + #include + #include + #include + + int main() + { + std::valarray data(32); + std::iota(std::begin(data), std::end(data), 0); + + const std::size_t offset = 1, z = 2, y = 3, x = 4; + const std::valarray sizes{z, y, x}; + const std::valarray strides{15, 5, 1}; + const std::gslice gslice = std::gslice(offset, sizes, strides); + // Indices are generated according to the formula: + // index[k] = offset + [0,1,2)*15 + [0,1,2,3)*5 + [0,1,2,3,4)*1 + // = offset + inner_product(sizes[k], strides); + // where sizes[k] = {[0,z), [0,y), [0,x)}, while the rightmost index (x) + // runs fastest. As a result we have following set of indices: + // index[0] = 1 + 0*15 + 0*5 + 0*1 = 1 + // index[1] = 1 + 0*15 + 0*5 + 1*1 = 2 + // index[2] = 1 + 0*15 + 0*5 + 2*1 = 3 + // index[3] = 1 + 0*15 + 0*5 + 3*1 = 4 + // index[4] = 1 + 0*15 + 1*5 + 0*1 = 6 + // index[5] = 1 + 0*15 + 1*5 + 1*1 = 7 + // index[6] = 1 + 0*15 + 1*5 + 2*1 = 8 + // index[7] = 1 + 0*15 + 1*5 + 3*1 = 9 + // ... + // index[22] = 1 + 1*15 + 2*5 + 2*1 = 28 + // index[23] = 1 + 1*15 + 2*5 + 3*1 = 29 + + const std::valarray indices = data[gslice]; + for (unsigned i = 0; i != indices.size(); ++i) + std::cout << std::setfill('0') << std::setw(2) << indices[i] << ' '; + std::cout << "\\nTotal indices: " << indices.size() << '\\n'; + assert(indices.size() == x * y * z); -.SH Category: + data = 0; + std::gslice_array gslice_array = data[gslice]; + gslice_array = 1; + // Cells that correspond to generated indices = '1', skipped cells = '0'. + for (auto i : data) + std::cout << i << ' '; + std::cout << "\\nSum of ones = " << data.sum() << '\\n'; + } - * Todo no example +.SH Output: + + 01 02 03 04 06 07 08 09 11 12 13 14 16 17 18 19 21 22 23 24 26 27 28 29 + Total indices: 24 + 0 1 1 1 1 0 1 1 1 1 0 1 1 1 1 0 1 1 1 1 0 1 1 1 1 0 1 1 1 1 0 0 + Sum of ones = 24 + +.SH See also + + slice_array proxy to a subset of a valarray after applying a slice + \fI(class template)\fP diff --git a/man/std::gslice_array::gslice_array.3 b/man/std::gslice_array::gslice_array.3 index b64a1efca..aa413207a 100644 --- a/man/std::gslice_array::gslice_array.3 +++ b/man/std::gslice_array::gslice_array.3 @@ -1,12 +1,30 @@ -.TH std::gslice_array::gslice_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gslice_array::gslice_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gslice_array::gslice_array \- std::gslice_array::gslice_array + .SH Synopsis - gslice_array( const gslice_array& other ); + private: \fI(until C++11)\fP + gslice_array(); + public: \fB(1)\fP \fI(since C++11)\fP gslice_array() = delete; + public: \fB(2)\fP + gslice_array( const gslice_array& other ); - Constructs a gslice_array from another gslice_array other. - - The default constructor is implicitly deleted. + 1) The default constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: gslice_array is not DefaultConstructible. + 2) Constructs a gslice_array from another gslice_array other. .SH Parameters other - gslice_array to initialize with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 253 C++98 the copy constructor was private made public diff --git a/man/std::gslice_array::operator=.3 b/man/std::gslice_array::operator=.3 index 288d2e45e..39ad3e73c 100644 --- a/man/std::gslice_array::operator=.3 +++ b/man/std::gslice_array::operator=.3 @@ -1,35 +1,44 @@ -.TH std::gslice_array::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gslice_array::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gslice_array::operator= \- std::gslice_array::operator= + .SH Synopsis - void operator=( const T& value ) const; \fB(1)\fP - void operator=( const std::valarray& val_arr ) const; \fB(2)\fP - const gslice_array& operator=( const gslice_array& sl_arr) const; \fB(3)\fP \fI(since C++11)\fP + void operator=( const T& value ) const; \fB(1)\fP + void operator=( const std::valarray& val_arr ) const; \fB(2)\fP + const gslice_array& operator=( const gslice_array& other_arr ) const; \fB(3)\fP Assigns values to all referred elements. 1) Assigns value to all of the elements. 2) Assigns the elements of val_arr to the referred to elements of *this. - 3) Assigns the selected elements from sl_arr to the referred to elements of *this. + 3) Assigns the selected elements from other_arr to the referred to elements of + *this. .SH Parameters - value - a value to assign to all of the referred elements - val_arr - std::valarray to assign - sl_arr - std::gslice_array to assign + value - a value to assign to all of the referred elements + val_arr - std::valarray to assign + other_arr - std::gslice_array to assign .SH Return value - 1-2) \fI(none)\fP + 1,2) \fI(none)\fP 3) *this -.SH Exceptions - - \fI(none)\fP - .SH Example This section is incomplete Reason: no example -.SH Category: + Defect reports + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 123 C++98 overload (2) was non-const made const + LWG 253 C++98 the copy assignment operator was private made public + LWG 621 C++98 the copy assignment operator was non-const made const + +.SH Category: * Todo no example diff --git a/man/std::gslice_array::~gslice_array.3 b/man/std::gslice_array::~gslice_array.3 index 70ba605d5..558e0b58c 100644 --- a/man/std::gslice_array::~gslice_array.3 +++ b/man/std::gslice_array::~gslice_array.3 @@ -1,6 +1,9 @@ -.TH std::gslice_array::~gslice_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::gslice_array::~gslice_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::gslice_array::~gslice_array \- std::gslice_array::~gslice_array + .SH Synopsis ~gslice_array(); - Destroys the indexes in the array. The elements referred to by the object are not + Destroys the indices in the array. The elements referred to by the object are not modified. diff --git a/man/std::hardware_destructive_interference_size,std::hardware_constructive_interference_size.3 b/man/std::hardware_destructive_interference_size,std::hardware_constructive_interference_size.3 new file mode 100644 index 000000000..d24cb25c9 --- /dev/null +++ b/man/std::hardware_destructive_interference_size,std::hardware_constructive_interference_size.3 @@ -0,0 +1,229 @@ +.TH std::hardware_destructive_interference_size,std::hardware_constructive_interference_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hardware_destructive_interference_size,std::hardware_constructive_interference_size \- std::hardware_destructive_interference_size,std::hardware_constructive_interference_size + +.SH Synopsis + Defined in header + inline constexpr std::size_t + hardware_destructive_interference_size = \fB(1)\fP \fI(since C++17)\fP + /*implementation-defined*/; + inline constexpr std::size_t + hardware_constructive_interference_size = \fB(2)\fP \fI(since C++17)\fP + /*implementation-defined*/; + + 1) Minimum offset between two objects to avoid false sharing. Guaranteed to be at + least alignof(std::max_align_t) + + struct keep_apart + { + alignas(std::hardware_destructive_interference_size) std::atomic cat; + alignas(std::hardware_destructive_interference_size) std::atomic dog; + }; + + 2) Maximum size of contiguous memory to promote true sharing. Guaranteed to be at + least alignof(std::max_align_t) + + struct together + { + std::atomic dog; + int puppy; + }; + + struct kennel + { + // Other data members... + + alignas(sizeof(together)) together pack; + + // Other data members... + }; + + static_assert(sizeof(together) <= std::hardware_constructive_interference_size); + +.SH Notes + + These constants provide a portable way to access the L1 data cache line size. + + Feature-test macro Value Std Feature + constexpr + std::hardware_constructive_interference_size +__cpp_lib_hardware_interference_size 201703L \fI(C++17)\fP and + + constexpr + std::hardware_destructive_interference_size + +.SH Example + + The program uses two threads that atomically write to the data members of the given + global objects. The first object fits in one cache line, which results in "hardware + interference". The second object keeps its data members on separate cache lines, so + possible "cache synchronization" after thread writes is avoided. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + #ifdef __cpp_lib_hardware_interference_size + using std::hardware_constructive_interference_size; + using std::hardware_destructive_interference_size; + #else + // 64 bytes on x86-64 │ L1_CACHE_BYTES │ L1_CACHE_SHIFT │ __cacheline_aligned │ ... + constexpr std::size_t hardware_constructive_interference_size = 64; + constexpr std::size_t hardware_destructive_interference_size = 64; + #endif + + std::mutex cout_mutex; + + constexpr int max_write_iterations{10'000'000}; // the benchmark time tuning + + struct alignas(hardware_constructive_interference_size) + OneCacheLiner // occupies one cache line + { + std::atomic_uint64_t x{}; + std::atomic_uint64_t y{}; + } + oneCacheLiner; + + struct TwoCacheLiner // occupies two cache lines + { + alignas(hardware_destructive_interference_size) std::atomic_uint64_t x{}; + alignas(hardware_destructive_interference_size) std::atomic_uint64_t y{}; + } + twoCacheLiner; + + inline auto now() noexcept { return std::chrono::high_resolution_clock::now(); } + + template + void oneCacheLinerThread() + { + const auto start{now()}; + + for (uint64_t count{}; count != max_write_iterations; ++count) + if constexpr (xy) + oneCacheLiner.x.fetch_add(1, std::memory_order_relaxed); + else + oneCacheLiner.y.fetch_add(1, std::memory_order_relaxed); + + const std::chrono::duration elapsed{now() - start}; + std::lock_guard lk{cout_mutex}; + std::cout << "oneCacheLinerThread() spent " << elapsed.count() << " ms\\n"; + if constexpr (xy) + oneCacheLiner.x = elapsed.count(); + else + oneCacheLiner.y = elapsed.count(); + } + + template + void twoCacheLinerThread() + { + const auto start{now()}; + + for (uint64_t count{}; count != max_write_iterations; ++count) + if constexpr (xy) + twoCacheLiner.x.fetch_add(1, std::memory_order_relaxed); + else + twoCacheLiner.y.fetch_add(1, std::memory_order_relaxed); + + const std::chrono::duration elapsed{now() - start}; + std::lock_guard lk{cout_mutex}; + std::cout << "twoCacheLinerThread() spent " << elapsed.count() << " ms\\n"; + if constexpr (xy) + twoCacheLiner.x = elapsed.count(); + else + twoCacheLiner.y = elapsed.count(); + } + + int main() + { + std::cout << "__cpp_lib_hardware_interference_size " + # ifdef __cpp_lib_hardware_interference_size + "= " << __cpp_lib_hardware_interference_size << '\\n'; + # else + "is not defined, use " << hardware_destructive_interference_size + << " as fallback\\n"; + # endif + + std::cout << "hardware_destructive_interference_size == " + << hardware_destructive_interference_size << '\\n' + << "hardware_constructive_interference_size == " + << hardware_constructive_interference_size << "\\n\\n" + << std::fixed << std::setprecision(2) + << "sizeof( OneCacheLiner ) == " << sizeof(OneCacheLiner) << '\\n' + << "sizeof( TwoCacheLiner ) == " << sizeof(TwoCacheLiner) << "\\n\\n"; + + constexpr int max_runs{4}; + + int oneCacheLiner_average{0}; + for (auto i{0}; i != max_runs; ++i) + { + std::thread th1{oneCacheLinerThread<0>}; + std::thread th2{oneCacheLinerThread<1>}; + th1.join(); + th2.join(); + oneCacheLiner_average += oneCacheLiner.x + oneCacheLiner.y; + } + std::cout << "Average T1 time: " + << (oneCacheLiner_average / max_runs / 2) << " ms\\n\\n"; + + int twoCacheLiner_average{0}; + for (auto i{0}; i != max_runs; ++i) + { + std::thread th1{twoCacheLinerThread<0>}; + std::thread th2{twoCacheLinerThread<1>}; + th1.join(); + th2.join(); + twoCacheLiner_average += twoCacheLiner.x + twoCacheLiner.y; + } + std::cout << "Average T2 time: " + << (twoCacheLiner_average / max_runs / 2) << " ms\\n\\n" + << "Ratio T1/T2:~ " + << 1.0 * oneCacheLiner_average / twoCacheLiner_average << '\\n'; + } + +.SH Possible output: + + __cpp_lib_hardware_interference_size = 201703 + hardware_destructive_interference_size == 64 + hardware_constructive_interference_size == 64 + + sizeof( OneCacheLiner ) == 64 + sizeof( TwoCacheLiner ) == 128 + + oneCacheLinerThread() spent 517.83 ms + oneCacheLinerThread() spent 533.43 ms + oneCacheLinerThread() spent 527.36 ms + oneCacheLinerThread() spent 555.69 ms + oneCacheLinerThread() spent 574.74 ms + oneCacheLinerThread() spent 591.66 ms + oneCacheLinerThread() spent 555.63 ms + oneCacheLinerThread() spent 555.76 ms + Average T1 time: 550 ms + + twoCacheLinerThread() spent 89.79 ms + twoCacheLinerThread() spent 89.94 ms + twoCacheLinerThread() spent 89.46 ms + twoCacheLinerThread() spent 90.28 ms + twoCacheLinerThread() spent 89.73 ms + twoCacheLinerThread() spent 91.11 ms + twoCacheLinerThread() spent 89.17 ms + twoCacheLinerThread() spent 90.09 ms + Average T2 time: 89 ms + + Ratio T1/T2:~ 6.16 + +.SH See also + + hardware_concurrency returns the number of concurrent threads supported by the + \fB[static]\fP implementation + \fI(public static member function of std::thread)\fP + hardware_concurrency returns the number of concurrent threads supported by the + \fB[static]\fP implementation + \fI(public static member function of std::jthread)\fP diff --git a/man/std::has_facet.3 b/man/std::has_facet.3 index 23d9e67cf..de3a352c6 100644 --- a/man/std::has_facet.3 +++ b/man/std::has_facet.3 @@ -1,11 +1,19 @@ -.TH std::has_facet 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::has_facet 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::has_facet \- std::has_facet + .SH Synopsis Defined in header - template< class Facet > - bool has_facet( const locale& loc ); + template< class Facet > \fI(until C++11)\fP + bool has_facet( const locale& loc ) throw(); + template< class Facet > \fI(since C++11)\fP + bool has_facet( const locale& loc ) noexcept; Checks if the locale loc implements the facet Facet. + The program is ill-formed if Facet is not a facet or it is a volatile-qualified + facet. + .SH Parameters loc - the locale object to query @@ -14,28 +22,27 @@ Returns true if the facet Facet was installed in the locale loc, false otherwise. -.SH Exceptions +.SH Notes - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + std::has_facet must return true for all locales loc if Facet is one of the standard + facets given here. .SH Example - + // Run this code #include #include - + // minimal custom facet - struct myfacet : public std::locale::facet { + struct myfacet : public std::locale::facet + { static std::locale::id id; }; - + std::locale::id myfacet::id; - + int main() { // loc is a "C" locale with myfacet added @@ -55,9 +62,18 @@ Can loc classify char32_t? false Does loc implement myfacet? true + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 436 C++98 it was unclear whether Facet it can be const-qualified, but not + can be cv-qualified volatile-qualified + .SH See also locale set of polymorphic facets that encapsulate cultural differences - \fI(class)\fP + \fI(class)\fP use_facet obtains a facet from a locale - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::has_single_bit.3 b/man/std::has_single_bit.3 new file mode 100644 index 000000000..d82394230 --- /dev/null +++ b/man/std::has_single_bit.3 @@ -0,0 +1,91 @@ +.TH std::has_single_bit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::has_single_bit \- std::has_single_bit + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr bool has_single_bit( T x ) noexcept; + + Checks if x is an integral power of two. + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + true if x is an integral power of two; otherwise false. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_int_pow2 202002L (C++20) Integral power-of-2 operations + +.SH Possible implementation + +.SH First version + template + requires !std::same_as && !std::same_as && + !std::same_as && !std::same_as && + !std::same_as && !std::same_as + constexpr bool has_single_bit(T x) noexcept + { + return x && !(x & (x - 1)); + } +.SH Second version + template + requires !std::same_as && !std::same_as && + !std::same_as && !std::same_as && + !std::same_as && !std::same_as + constexpr bool has_single_bit(T x) noexcept + { + return std::popcount(x) == 1; + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + for (auto u = 0u; u != 10; ++u) + { + std::cout << "u = " << u << " = " << std::bitset<4>(u); + if (std::has_single_bit(u)) // `ispow2` before P1956R1 + std::cout << " = 2^" << std::log2(u) << " (is power of two)"; + std::cout << '\\n'; + } + } + +.SH Output: + + u = 0 = 0000 + u = 1 = 0001 = 2^0 (is power of two) + u = 2 = 0010 = 2^1 (is power of two) + u = 3 = 0011 + u = 4 = 0100 = 2^2 (is power of two) + u = 5 = 0101 + u = 6 = 0110 + u = 7 = 0111 + u = 8 = 1000 = 2^3 (is power of two) + u = 9 = 1001 + +.SH See also + + popcount counts the number of 1 bits in an unsigned integer + (C++20) \fI(function template)\fP + count returns the number of bits set to true + \fI(public member function of std::bitset)\fP + test accesses specific bit + \fI(public member function of std::bitset)\fP diff --git a/man/std::has_unique_object_representations.3 b/man/std::has_unique_object_representations.3 new file mode 100644 index 000000000..132fe6ef6 --- /dev/null +++ b/man/std::has_unique_object_representations.3 @@ -0,0 +1,119 @@ +.TH std::has_unique_object_representations 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::has_unique_object_representations \- std::has_unique_object_representations + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + struct has_unique_object_representations; + + std::has_unique_object_representations is a UnaryTypeTrait. + + If T is TriviallyCopyable and if any two objects of type T with the same value have + the same object representation, provides the member constant value equal true. For + any other type, value is false. + + For the purpose of this trait, two arrays have the same value if their elements have + the same values, two non-union classes have the same value if their direct + subobjects have the same value, and two unions have the same value if they have the + same active member and the value of that member is the same. + + It is implementation-defined which scalar types satisfy this trait, but + unsigned + \fI(until C++20)\fP integer types that do not use padding bits are guaranteed to have + unique object representations. + + The behavior is undefined if T is an incomplete type other than (possibly + cv-qualified) void or array of unknown bound. + + If the program adds specializations for std::has_unique_object_representations or + std::has_unique_object_representations_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + + inline constexpr bool has_unique_object_representations_v = \fI(since C++17)\fP + + has_unique_object_representations::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T has unique object representations, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + This trait was introduced to make it possible to determine whether a type can be + correctly hashed by hashing its object representation as a byte array. + + Feature-test macro Value Std Feature +__cpp_lib_has_unique_object_representations 201606L \fI(C++17)\fP std::has_unique_object_representations + +.SH Example + + +// Run this code + + #include + #include + + struct unpadded + { + std::uint32_t a, b; + }; + + struct likely_padded + { + std::uint8_t c; + std::uint16_t st; + std::uint32_t i; + }; + + int main() + { + // Every value of a char corresponds to exactly one object representation. + static_assert(std::has_unique_object_representations_v); + // For IEC 559 floats, assertion passes because the value NaN has + // multiple object representations. + static_assert(!std::has_unique_object_representations_v); + + // Should succeed in any sane implementation because unpadded + // is typically not padded, and std::uint32_t cannot contain padding bits. + static_assert(std::has_unique_object_representations_v); + // Fails in most implementations because padding bits are inserted + // between the data members c and st for the purpose of aligning st to 16 bits. + static_assert(!std::has_unique_object_representations_v); + + // Notable architectural divergence: + static_assert(std::has_unique_object_representations_v); // x86 + // static_assert(!std::has_unique_object_representations_v); // ARM + } + +.SH See also + + is_standard_layout checks if a type is a standard-layout type + \fI(C++11)\fP \fI(class template)\fP + hash hash function object + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::has_virtual_destructor.3 b/man/std::has_virtual_destructor.3 index 9ddc9ff11..507385fa0 100644 --- a/man/std::has_virtual_destructor.3 +++ b/man/std::has_virtual_destructor.3 @@ -1,21 +1,47 @@ -.TH std::has_virtual_destructor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::has_virtual_destructor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::has_virtual_destructor \- std::has_virtual_destructor + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct has_virtual_destructor; - If T is a type with a virtual destructor, provides the member constant value equal - true. For any other type, value is false. + std::has_virtual_destructor is a UnaryTypeTrait. + + If T is a type with a virtual destructor, the base characteristic is std::true_type. + For any other type, the base characteristic is std::false_type. + + If T is an incomplete non-union class type, the behavior is undefined. + + If the program adds specializations for std::has_virtual_destructor or + std::has_virtual_destructor_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + inline constexpr bool has_virtual_destructor_v = \fI(since C++17)\fP + has_virtual_destructor::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T has a virtual destructor , false otherwise + value true if T has a virtual destructor, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,38 +51,48 @@ .SH Notes - If a class has a public virtual destructor, it can be derived from, and the derived - object can be safely deleted through a pointer to the base object (C++FAQ Lite 20.7) + If a class C has a public virtual destructor, it can be derived from, and the + derived object can be safely deleted through a pointer to the base object (GotW + #18). In this case, std::is_polymorphic::value is true. .SH Example - + // Run this code - #include #include - #include - #include - + + struct S {}; + static_assert(!std::has_virtual_destructor_v); + + struct B { virtual ~B() {} }; + static_assert(std::has_virtual_destructor_v); + + struct D : B { ~D() {} }; + static_assert(std::has_virtual_destructor_v); + int main() { - std::cout << std::boolalpha - << "std::string has a virtual destructor? " - << std::has_virtual_destructor::value << '\\n' - << "std::runtime_error has a virtual destructor? " - << std::has_virtual_destructor::value << '\\n'; + B* pd = new D; + delete pd; } -.SH Output: + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - std::string has a virtual destructor? false - std::runtime_error has a virtual destructor? true + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 the behavior was undefined if the base characteristic is + T is an incomplete union type std::false_type in this case .SH See also is_destructible is_trivially_destructible is_nothrow_destructible checks if a type has a non-deleted destructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP + is_polymorphic checks if a type is a polymorphic class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::hash(std::bitset).3 b/man/std::hash(std::bitset).3 deleted file mode 100644 index 019e84ba0..000000000 --- a/man/std::hash(std::bitset).3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH std::hash(std::bitset) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template struct hash>; \fI(since C++11)\fP - - The template specialization of std::hash for std::bitset allows users to obtain - hashes of objects of type std::bitset. - -.SH Example - - The following code shows one possible output of a hash function used on several - bitsets: - - -// Run this code - - #include - #include - #include - - int main() - { - std::bitset<4> b1(1); - std::bitset<4> b2(2); - std::bitset<4> b3(b2); - - std::hash> hash_fn; - - size_t h1 = hash_fn(b1); - size_t h2 = hash_fn(b2); - size_t h3 = hash_fn(b3); - - std::cout << h1 << '\\n'; - std::cout << h2 << '\\n'; - std::cout << h3 << '\\n'; - } - -.SH Output: - - 67918732 - 118251589 - 118251589 - -.SH See also - - hash hash function object - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::hash(std::error_code).3 b/man/std::hash(std::error_code).3 deleted file mode 100644 index 86580bc9c..000000000 --- a/man/std::hash(std::error_code).3 +++ /dev/null @@ -1,7 +0,0 @@ -.TH std::hash(std::error_code) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - struct hash; \fI(since C++11)\fP - - The template specialization of std::hash for std::error_code allows users to obtain - hashes of objects of type std::error_code. diff --git a/man/std::hash(std::experimental::observer_ptr).3 b/man/std::hash(std::experimental::observer_ptr).3 new file mode 100644 index 000000000..df79ea745 --- /dev/null +++ b/man/std::hash(std::experimental::observer_ptr).3 @@ -0,0 +1,27 @@ +.TH std::hash(std::experimental::observer_ptr) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash(std::experimental::observer_ptr) \- std::hash(std::experimental::observer_ptr) + +.SH Synopsis + Defined in header + template< class T > struct (library fundamentals + hash>; TS v2) + + The template specialization of std::hash for std::experimental::observer_ptr + allows users to obtain hashes of objects of type std::experimental::observer_ptr. + + For a given std::experimental::observer_ptr p, this specialization ensures that + std::hash>()(p) == std::hash()(p.get()). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::hash(std::experimental::propagate_const).3 b/man/std::hash(std::experimental::propagate_const).3 new file mode 100644 index 000000000..93881ce8e --- /dev/null +++ b/man/std::hash(std::experimental::propagate_const).3 @@ -0,0 +1,29 @@ +.TH std::hash(std::experimental::propagate_const) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash(std::experimental::propagate_const) \- std::hash(std::experimental::propagate_const) + +.SH Synopsis + Defined in header + template< class T > struct (library fundamentals + hash>; TS v2) + + The template specialization of std::hash for std::experimental::propagate_const + allows users to obtain hashes of objects of type + std::experimental::propagate_const. + + For a given std::experimental::propagate_const p, this specialization ensures + that std::hash>()(p) == std::hash()(p.t_), + where p.t_ is the pointer-like object wrapped by p. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::hash(std::experimental::shared_ptr).3 b/man/std::hash(std::experimental::shared_ptr).3 new file mode 100644 index 000000000..a044e5376 --- /dev/null +++ b/man/std::hash(std::experimental::shared_ptr).3 @@ -0,0 +1,27 @@ +.TH std::hash(std::experimental::shared_ptr) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash(std::experimental::shared_ptr) \- std::hash(std::experimental::shared_ptr) + +.SH Synopsis + template< class T > struct (library fundamentals + hash>; TS) + + The template specialization of std::hash for std::experimental::shared_ptr allows + users to obtain hashes of objects of type std::experimental::shared_ptr. + + For a given std::experimental::shared_ptr p, this specialization ensures that + std::hash>()(p) == std::hash()(p.get()). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + +.SH Categories: + * Noindexed pages + * Todo no example diff --git a/man/std::hash(std::experimental::string_view,std::experimental::wstring_view,.3 b/man/std::hash(std::experimental::string_view,std::experimental::wstring_view,.3 new file mode 100644 index 000000000..89103ebd6 --- /dev/null +++ b/man/std::hash(std::experimental::string_view,std::experimental::wstring_view,.3 @@ -0,0 +1,24 @@ +.TH std::hash(std::experimental::string_view,std::experimental::wstring_view, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash(std::experimental::string_view,std::experimental::wstring_view, \- std::hash(std::experimental::string_view,std::experimental::wstring_view, + +.SH Synopsis + + Defined in header + template<> struct hash; + + template<> struct hash; (library fundamentals + template<> struct hash; TS) + + template<> struct hash; + + Template specializations of std::hash for the various view classes for hashing + views. + +.SH See also + + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Noindexed pages diff --git a/man/std::hash(std::string,std::wstring,std::u16string,std::u32string).3 b/man/std::hash(std::string,std::wstring,std::u16string,std::u32string).3 deleted file mode 100644 index 82527a4e0..000000000 --- a/man/std::hash(std::string,std::wstring,std::u16string,std::u32string).3 +++ /dev/null @@ -1,42 +0,0 @@ -.TH std::hash(std::string,std::wstring,std::u16string,std::u32string) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> struct hash; - - template<> struct hash; \fI(since C++11)\fP - template<> struct hash; - - template<> struct hash; - - The template specializations of std::hash for the various string classes allow users - to obtain hashes of strings. - -.SH Example - - The following code shows one possible output of a hash function used on a string: - - -// Run this code - - #include - #include - #include - - int main() - { - std::string s = "Stand back! I've got jimmies!"; - std::hash hash_fn; - - size_t hash = hash_fn(s); - - std::cout << hash << '\\n'; - } - -.SH Output: - - 325378910 - -.SH See also - - hash hash function object - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::hash(std::vector).3 b/man/std::hash(std::vector).3 deleted file mode 100644 index ff6d4c21e..000000000 --- a/man/std::hash(std::vector).3 +++ /dev/null @@ -1,20 +0,0 @@ -.TH std::hash(std::vector) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template struct hash>; \fI(since C++11)\fP - - The template specialization of std::hash for std::vector allows users to - obtain hashes of objects of type std::vector. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - hash hash function object - \fI(C++11)\fP \fI(class template)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::hash,std::hash,std::hash,.3 b/man/std::hash,std::hash,std::hash,.3 new file mode 100644 index 000000000..ce1dbd8f3 --- /dev/null +++ b/man/std::hash,std::hash,std::hash,.3 @@ -0,0 +1,66 @@ +.TH std::hash,std::hash,std::hash, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash,std::hash,std::hash, \- std::hash,std::hash,std::hash, + +.SH Synopsis + + Defined in header + template<> struct hash; \fI(since C++17)\fP + template<> struct hash; \fI(since C++17)\fP + template<> struct hash; \fI(since C++20)\fP + template<> struct hash; \fI(since C++17)\fP + template<> struct hash; \fI(since C++17)\fP + + Template specializations of std::hash for the various view classes for hashing + views. + + These hashes equal the hashes of corresponding std::basic_string classes: If S is + one of the standard basic_string types, SV is the corresponding string view type, + and s is an object of type S, then std::hash()(s) == std::hash()(SV(s)). + +.SH Example + + +// Run this code + + #include + #include + #include + using namespace std::literals; + + int main() + { + std::cout << "\\"A\\" #: " << std::hash{}("A"sv) << '\\n'; + std::cout << "L\\"B\\" #: " << std::hash{}(L"B"sv) << '\\n'; + std::cout << "u8\\"C\\" #: " << std::hash{}(u8"C"sv) << '\\n'; + std::cout << "u\\"D\\" #: " << std::hash{}(u"D"sv) << '\\n'; + std::cout << "U\\"E\\" #: " << std::hash{}(U"E"sv) << '\\n'; + + // std::hash for string_view family makes it possible to keep these view-types + // in unordered_* associative containers, such as unordered_set. But ensure + // the lifespan of referenced strings is no less than lifespan of the container, + // i.e. no dangling references occurred. + + std::unordered_set stars{"Rigel"sv, "Capella"sv, "Vega"sv, "Arcturus"sv}; + + for (std::string_view const& s : stars) + std::cout << s << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + "A" #: 6919333181322027406 + L"B" #: 11959850520494268278 + u8"C" #: 12432341034569643010 + u"D" #: 312659256970442235 + U"E" #: 18073225910249204957 + Arcturus Vega Capella Rigel + +.SH See also + + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::hash.3 b/man/std::hash.3 index efaeff74a..3b6736ea3 100644 --- a/man/std::hash.3 +++ b/man/std::hash.3 @@ -1,23 +1,76 @@ -.TH std::hash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::hash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash \- std::hash + .SH Synopsis - template struct hash>; \fI(since C++11)\fP + Defined in header + template<> \fI(since C++17)\fP + struct hash; + + The template specialization of std::hash for std::filesystem::path allows users to + obtain hash values of std::filesystem::path. - The template specialization of std::hash for std::shared_ptr allows users to - obtain hashes of objects of type std::shared_ptr. + The operator() of this specialization is noexcept. For every std::filesystem::path + value p, std::hash{}(p) is equal to + std::filesystem::hash_value(p). - For a given std::shared_ptr p, this specialization ensures that - std::hash>()(p) == std::hash()(p.get()). + This specialization was absent from the C++17 standard publication, see LWG issue + 3657. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include + #include + #include + namespace fs = std::filesystem; + + void show_hash(fs::path const& p) + { + std::cout << std::hex << std::uppercase << std::setw(16) + << std::hash{}(p) << " : " << p << '\\n'; + } - hash hash function object - \fI(C++11)\fP \fI(class template)\fP + int main() + { + auto tmp1 = fs::path{"/tmp"}; + auto tmp2 = fs::path{"/tmp/../tmp"}; + assert(!(tmp1 == tmp2)); + assert(fs::equivalent(tmp1, tmp2)); + show_hash(tmp1); + show_hash(tmp2); -.SH Category: + for (auto s : {"/a///b", "/a//b", "/a/c", "...", "..", ".", ""}) + show_hash(s); + + std::unordered_set> dirs{ + "/bin", "/bin", "/lib", "/lib", "/opt", "/opt", "/tmp", "/tmp/../tmp"}; + for (fs::path const& p : dirs) + std::cout << p << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + 6050C47ADB62DFE5 : "/tmp" + 62795A58B69AD90A : "/tmp/../tmp" + FF302110C9991974 : "/a///b" + FF302110C9991974 : "/a//b" + FD6167277915D464 : "/a/c" + C42040F82CD8B542 : "..." + D2D30154E0B78BBC : ".." + D18C722215ED0530 : "." + 0 : "" + "/tmp/../tmp" "/opt" "/lib" "/tmp" "/bin" + +.SH See also - * Todo no example + hash hash function object + \fI(C++11)\fP \fI(class template)\fP + hash_value calculates a hash value for a path object + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::hash.3 b/man/std::hash.3 deleted file mode 100644 index bef3ba452..000000000 --- a/man/std::hash.3 +++ /dev/null @@ -1,27 +0,0 @@ -.TH std::hash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template (library fundamentals TS) - struct hash>; - - The template specialization of std::hash for the std::experimental::optional class - allows users to obtain hashes of the values contained in optional objects. - -.SH Template parameters - - T - the type of the value contained in optional object. The specialization - std::hash must meet the requirements of class template hash. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - hash hash function object - \fI(C++11)\fP \fI(class template)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::hash.3 b/man/std::hash.3 deleted file mode 100644 index 22f0e7c88..000000000 --- a/man/std::hash.3 +++ /dev/null @@ -1,21 +0,0 @@ -.TH std::hash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> struct hash; \fI(since C++11)\fP - - The template specialization of std::hash for the std::thread::id class allows users - to obtain hashes of the identifiers of threads. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - hash hash function object - \fI(C++11)\fP \fI(class template)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::hash.3 b/man/std::hash.3 deleted file mode 100644 index 1bd0403f5..000000000 --- a/man/std::hash.3 +++ /dev/null @@ -1,16 +0,0 @@ -.TH std::hash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - struct hash; \fI(since C++11)\fP - - The template specialization of std::hash for std::type_index allows users to obtain - hashes of objects of type std::type_index. - -.SH Return value - - Effectively returns the same value as hash_code(). - -.SH See also - - hash_code returns hashed code - \fI(public member function)\fP diff --git a/man/std::hash>.3 b/man/std::hash>.3 new file mode 100644 index 000000000..96ad4ce3d --- /dev/null +++ b/man/std::hash>.3 @@ -0,0 +1,78 @@ +.TH std::hash> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hash> \- std::hash> + +.SH Synopsis + Defined in header + template< class Allocator > \fI(since C++11)\fP + struct hash>; + + The template specialization of std::hash for std::vector allows users to + obtain hashes of objects of type std::vector. + +.SH Example + + +// Run this code + + #include + #include + #include + + using vb = std::vector; + + vb to_vector_bool(unsigned n) + { + vb v; + do + { + v.push_back(n & 1); + n >>= 1; + } + while (n); + return v; + } + + auto print(const vb& v, bool new_line = true) + { + for (std::cout << "{ "; const bool e : v) + std::cout << e << ' '; + std::cout << '}' << (new_line ? '\\n' : ' '); + } + + int main() + { + for (auto i{0U}; i != 8; ++i) + { + std::cout << std::hex << std::uppercase; + vb v = to_vector_bool(i); + std::cout << std::hash{}(v) << ' ' << std::dec; + print(v); + } + + // std::hash for vector makes it possible to keep them in + // unordered_* associative containers, such as unordered_set. + + std::unordered_set v{vb{0}, vb{0, 0}, vb{1}, vb{1}, vb{1, 0}, vb{1, 1}}; + + for (vb const& e : v) + print(e, 0); + std::cout << '\\n'; + } + +.SH Possible output: + + 6D09EE26D5863619 { 0 } + 3C27D9F591D20E49 { 1 } + E74D3F72B7599C63 { 0 1 } + EE3BE81F55123770 { 1 1 } + 3AAD2A2EDBEC6C35 { 0 0 1 } + EB057F773CB64C43 { 1 0 1 } + 6E1354730102BE00 { 0 1 1 } + E2E622597C18899D { 1 1 1 } + { 1 1 } { 1 0 } { 1 } { 0 0 } { 0 } + +.SH See also + + hash hash function object + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::hermite,std::hermitef,std::hermitel.3 b/man/std::hermite,std::hermitef,std::hermitel.3 new file mode 100644 index 000000000..f28db9640 --- /dev/null +++ b/man/std::hermite,std::hermitef,std::hermitel.3 @@ -0,0 +1,114 @@ +.TH std::hermite,std::hermitef,std::hermitel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hermite,std::hermitef,std::hermitel \- std::hermite,std::hermitef,std::hermitel + +.SH Synopsis + double hermite( unsigned int n, double x ); + + double hermite( unsigned int n, float x ); + double hermite( unsigned int n, long double x ); \fB(1)\fP + float hermitef( unsigned int n, float x ); + + long double hermitel( unsigned int n, long double x ); + double hermite( unsigned int n, IntegralType x ); \fB(2)\fP + + 1) Computes the (physicist's) Hermite polynomials of the degree n and argument x. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, hermite is only guaranteed to be available in if + __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least + 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any + standard library headers. + +.SH Parameters + + n - the degree of the polynomial + x - the argument, a value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the order-nHermite polynomial of x, that is (-1)n + e^x2 + + dn + dxn + + e^-x2 + , is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If n is greater or equal than 128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The Hermite polynomials are the polynomial solutions of the equation u,, + - 2xu, + = -2nu. + + The first few are: + + * hermite(0, x) = 1. + * hermite(1, x) = 2x. + * hermite(2, x) = 4x2 + - 2. + * hermite(3, x) = 8x3 + - 12x. + * hermite(4, x) = 16x4 + - 48x2 + + 12. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + double H3(double x) + { + return 8 * std::pow(x, 3) - 12 * x; + } + + double H4(double x) + { + return 16 * std::pow(x, 4) - 48 * x * x + 12; + } + + int main() + { + // spot-checks + std::cout << std::hermite(3, 10) << '=' << H3(10) << '\\n' + << std::hermite(4, 10) << '=' << H4(10) << '\\n'; + } + +.SH Output: + + 7880=7880 + 155212=155212 + +.SH See also + + laguerre Laguerre polynomials + laguerref \fI(function)\fP + laguerrel + legendre Legendre polynomials + legendref \fI(function)\fP + legendrel + +.SH External links + + Weisstein, Eric W. ""Hermite Polynomial." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::holds_alternative.3 b/man/std::holds_alternative.3 new file mode 100644 index 000000000..8242c9a31 --- /dev/null +++ b/man/std::holds_alternative.3 @@ -0,0 +1,52 @@ +.TH std::holds_alternative 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::holds_alternative \- std::holds_alternative + +.SH Synopsis + Defined in header + template< class T, class... Types > + constexpr bool holds_alternative( const std::variant& v ) \fI(since C++17)\fP + noexcept; + + Checks if the variant v holds the alternative T. The call is ill-formed if T does + not appear exactly once in Types... + +.SH Parameters + + v - variant to examine + +.SH Return value + + true if the variant currently holds the alternative T, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + int main() + { + std::variant v = "abc"; + std::cout << std::boolalpha + << "variant holds int? " + << std::holds_alternative(v) << '\\n' + << "variant holds string? " + << std::holds_alternative(v) << '\\n'; + } + +.SH Output: + + variant holds int? false + variant holds string? true + +.SH See also + + returns the zero-based index of the alternative held by the + index variant + \fI(public member function)\fP + get(std::variant) reads the value of the variant given the index or the type (if the + \fI(C++17)\fP type is unique), throws on error + \fI(function template)\fP diff --git a/man/std::hypot,std::hypotf,std::hypotl.3 b/man/std::hypot,std::hypotf,std::hypotl.3 new file mode 100644 index 000000000..69cb77017 --- /dev/null +++ b/man/std::hypot,std::hypotf,std::hypotl.3 @@ -0,0 +1,259 @@ +.TH std::hypot,std::hypotf,std::hypotl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::hypot,std::hypotf,std::hypotl \- std::hypot,std::hypotf,std::hypotl + +.SH Synopsis + Defined in header + float hypot ( float x, float y ); + + double hypot ( double x, double y ); \fI(since C++11)\fP + (until C++23) + long double hypot ( long double x, long + double y ); + /* floating-point-type */ + + hypot ( /* floating-point-type (since C++23) + */ x, (constexpr since + C++26) + /* floating-point-type + */ y ); + \fI(since C++11)\fP + float hypotf( float x, float y ); \fB(2)\fP (constexpr since + C++26) + long double hypotl( long double x, long \fI(since C++11)\fP + double y ); \fB(3)\fP (constexpr since + C++26) + float hypot ( float x, float y, + float z ); + + double hypot ( double x, double y, \fI(since C++17)\fP + double z ); (until C++23) + + long double hypot ( long double x, long \fB(1)\fP + double y, long double z ); + /* floating-point-type */ + + hypot ( /* floating-point-type + */ x, (since C++23) + /* floating-point-type (constexpr since + */ y, C++26) + + /* floating-point-type \fB(4)\fP + */ z ); + Additional overloads + Defined in header + template< class Arithmetic1, Arithmetic2 > + \fI(since C++11)\fP + /* common-floating-point-type */ (A) (constexpr since + C++26) + hypot ( Arithmetic1 x, + Arithmetic2 y ); + template< class Arithmetic1, Arithmetic2, + Arithmetic3 > + \fI(since C++17)\fP + /* common-floating-point-type */ (B) (constexpr since + C++26) + hypot ( Arithmetic1 x, + Arithmetic2 y, Arithmetic3 z ); + + 1-3) Computes the square root of the sum of the squares of x and y, without undue + overflow or underflow at intermediate stages of the computation. + The library provides overloads of std::hypot for all cv-unqualified floating-point + types as the type of the parameters x and y. + (since C++23) + 4) Computes the square root of the sum of the squares of x, y, and z, without undue + overflow or underflow at intermediate stages of the computation. + The library provides overloads of std::hypot for all cv-unqualified floating-point + types as the type of the parameters x, y and z. + (since C++23) + A,B) Additional overloads are provided for all other combinations of arithmetic + types. + + The value computed by the two-argument version of this function is the length of the + hypotenuse of a right-angled triangle with sides of length x and y, or the distance + of the point (x,y) from the origin (0,0), or the magnitude of a complex number x+iy. + + The value computed by the three-argument version of this function is the distance of + the point (x,y,z) from the origin (0,0,0). + +.SH Parameters + + x, y, z - floating-point or integer values + +.SH Return value + + 1-3,A) If no errors occur, the hypotenuse of a right-angled triangle, + \\(\\scriptsize{\\sqrt{x^2+y^2} }\\) + √ + x2 + +y2 + , is returned. + 4,B) If no errors occur, the distance from origin in 3D space, + \\(\\scriptsize{\\sqrt{x^2+y^2+z^2} }\\) + √ + x2 + +y2 + +z2 + , is returned. + + If a range error due to overflow occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is + returned. + + If a range error due to underflow occurs, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * std::hypot(x, y), std::hypot(y, x), and std::hypot(x, -y) are equivalent. + * if one of the arguments is ±0, std::hypot(x, y) is equivalent to std::fabs + called with the non-zero argument. + * if one of the arguments is ±∞, std::hypot(x, y) returns +∞ even if the other + argument is NaN. + * otherwise, if any of the arguments is NaN, NaN is returned. + +.SH Notes + + Implementations usually guarantee precision of less than 1 ulp (Unit in the Last + Place — Unit of Least Precision): GNU, BSD. + + std::hypot(x, y) is equivalent to std::abs(std::complex(x, y)). + + POSIX specifies that underflow may only occur when both arguments are subnormal and + the correct result is also subnormal (this forbids naive implementations). + + Distance between two points (x1,y1,z1) and (x2,y2,z2) on 3D space can + be calculated using 3-argument overload of std::hypot as std::hypot(x2 \fI(since C++17)\fP + - x1, y2 - y1, z2 - z1). + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their first argument num1, second argument + num2 and the optional third argument num3: + + * If num1, num2 or num3 has type long double, then + + * std::hypot(num1, num2) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2)), and + * std::hypot(num1, num2, num3) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 and/or num3 has type double or an integer + type, then + + * std::hypot(num1, num2) has the same effect as + std::hypot(static_cast(num1), (until C++23) + static_cast(num2)), and + * std::hypot(num1, num2, num3) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 or num3 has type float, then + + * std::hypot(num1, num2) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2)), and + * std::hypot(num1, num2, num3) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2), + static_cast(num3)). + If num1, num2 and num3 have arithmetic types, then + + * std::hypot(num1, num2) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2)), + and + * std::hypot(num1, num2, num3) has the same effect as + std::hypot(static_cast(num1), + static_cast(num2), + static_cast(num3)), (since C++23) + + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank among the types of num1, num2 and + num3, arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + + Feature-test macro Value Std Feature + __cpp_lib_hypot 201603L \fI(C++17)\fP 3-argument overload of std::hypot + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + struct Point3D { float x, y, z; }; + + int main() + { + // typical usage + std::cout << "(1,1) cartesian is (" << std::hypot(1,1) + << ',' << std::atan2(1,1) << ") polar\\n"; + + Point3D a{3.14, 2.71, 9.87}, b{1.14, 5.71, 3.87}; + // C++17 has 3-argument hypot overload: + std::cout << "distance(a,b) = " + << std::hypot(a.x - b.x, a.y - b.y, a.z - b.z) << '\\n'; + + // special values + std::cout << "hypot(NAN,INFINITY) = " << std::hypot(NAN, INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + std::cout << "hypot(DBL_MAX,DBL_MAX) = " << std::hypot(DBL_MAX, DBL_MAX) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno = ERANGE " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Output: + + (1,1) cartesian is (1.41421,0.785398) polar + distance(a,b) = 7 + hypot(NAN,INFINITY) = inf + hypot(DBL_MAX,DBL_MAX) = inf + errno = ERANGE Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + pow + powf raises a number to the given power (\\(\\small{x^y}\\)x^y) + powl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sqrt computes square root (\\(\\small{\\sqrt{x}}\\) + sqrtf √ + sqrtl x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + cbrt computes cube root (\\(\\small{\\sqrt[3]{x}}\\) + cbrtf 3 + cbrtl √ + \fI(C++11)\fP x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + abs(std::complex) returns the magnitude of a complex number + \fI(function template)\fP + C documentation for + hypot diff --git a/man/std::hypot.3 b/man/std::hypot.3 deleted file mode 100644 index 29259adec..000000000 --- a/man/std::hypot.3 +++ /dev/null @@ -1,78 +0,0 @@ -.TH std::hypot 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float hypot( float x, float y ); \fB(1)\fP \fI(since C++11)\fP - double hypot( double x, double y ); \fB(2)\fP \fI(since C++11)\fP - long double hypot( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP - Promoted hypot( Arithmetic1 x, Arithmetic2 y ); \fB(4)\fP \fI(since C++11)\fP - - Computes the square root of the sum of the squares of x and y, without undue - overflow or underflow at intermediate stages of the computation. This is the length - of the hypotenuse of a right-angled triangle with sides of length x and y, or the - distance of the point (x,y) from the origin (0,0), or the magnitude of a complex - number x+iy - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double. - -.SH Parameters - - x, y - values of floating-point or integral types - -.SH Return value - - The hypotenuse of a right-angled triangle, - √ - x2 - +y2 - . - -.SH Exceptions - - If the result overflows, a range error may occur and FE_OVERFLOW may be raised. - - If the result is subnormal, an underflow error may occur and FE_UNDERFLOW may be - raised. - -.SH Notes - - Implementations usually guarantee precision of less than 1 ulp (units in the last - place): GNU, BSD, Open64 - -.SH Example - - -// Run this code - - #include - #include - #include - - std::pair cartesian_to_polar(double x, double y) - { - return {std::hypot(x, y), std::atan2(y,x)}; - } - - int main() - { - std::pair polar = cartesian_to_polar(1, 1); - std::cout << "(1,1) cartesian is (" << polar.first - << "," << polar.second<< ") polar\\n"; - } - -.SH Output: - - (1,1) cartesian is (1.41421,0.785398) polar - -.SH See also - - computes square root ( - sqrt √ - x) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP - C documentation for - hypot diff --git a/man/std::identity.3 b/man/std::identity.3 new file mode 100644 index 000000000..f594cdd7e --- /dev/null +++ b/man/std::identity.3 @@ -0,0 +1,93 @@ +.TH std::identity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::identity \- std::identity + +.SH Synopsis + Defined in header + struct identity; \fI(since C++20)\fP + + std::identity is a function object type whose operator() returns its argument + unchanged. + +.SH Member functions + + operator() returns the argument unchanged + \fI(public member function)\fP + +std::identity::operator() + + template< class T > + constexpr T&& operator()( T&& t ) const noexcept; + + Returns std::forward(t). + +.SH Parameters + + t - argument to return + +.SH Return value + + std::forward(t). + +.SH Notes + + std::identity serves as the default projection in constrained algorithms. Its direct + usage is usually not needed. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct Pair + { + int n; + std::string s; + friend std::ostream& operator<<(std::ostream& os, const Pair& p) + { + return os << '{' << p.n << ", " << p.s << '}'; + } + }; + + // A range-printer that can print projected (modified) elements of a range. + template //<- Notice the default projection + void print(std::string_view const rem, R&& range, Projection projection = {}) + { + std::cout << rem << '{'; + std::ranges::for_each( + range, + [O = 0](const auto& o) mutable { std::cout << (O++ ? ", " : "") << o; }, + projection + ); + std::cout << "}\\n"; + } + + int main() + { + const auto v = {Pair{1, "one"}, {2, "two"}, {3, "three"}}; + + print("Print using std::identity as a projection: ", v); + print("Project the Pair::n: ", v, &Pair::n); + print("Project the Pair::s: ", v, &Pair::s); + print("Print using custom closure as a projection: ", v, + [](Pair const& p) { return std::to_string(p.n) + ':' + p.s; }); + } + +.SH Output: + + Print using std::identity as a projection: {{1, one}, {2, two}, {3, three}} + Project the Pair::n: {1, 2, 3} + Project the Pair::s: {one, two, three} + Print using custom closure as a projection: {1:one, 2:two, 3:three} + +.SH See also + + type_identity returns the type argument unchanged + (C++20) \fI(class template)\fP diff --git a/man/std::ifstream.3 b/man/std::ifstream.3 deleted file mode 120000 index 39bb60d5b..000000000 --- a/man/std::ifstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream.3 \ No newline at end of file diff --git a/man/std::ifstream.3 b/man/std::ifstream.3 new file mode 100644 index 000000000..b1ae2381b --- /dev/null +++ b/man/std::ifstream.3 @@ -0,0 +1,332 @@ +.TH std::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream \- std::basic_ifstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_ifstream : public std::basic_istream + + The class template basic_ifstream implements high-level input operations on + file-based streams. It interfaces a file-based streambuffer (std::basic_filebuf) + with the high-level interface of (std::basic_istream). + + A typical implementation of std::basic_ifstream holds only one non-derived data + member: an instance of std::basic_filebuf. + + std-basic ifstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ifstream std::basic_ifstream + std::wifstream std::basic_ifstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + + constructor constructs the file stream + \fI(public member function)\fP + destructor destructs the basic_ifstream and the associated + \fB[virtual]\fP (implicitly declared) buffer, closes the file + \fI(virtual public member function)\fP + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw file device object + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP +.SH File operations + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ifstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "Test.b"; + + // prepare a file to read + double d = 3.14; + std::ofstream(filename, std::ios::binary) + .write(reinterpret_cast(&d), sizeof d) << 123 << "abc"; + + // open file for reading + std::ifstream istrm(filename, std::ios::binary); + if (!istrm.is_open()) + std::cout << "failed to open " << filename << '\\n'; + else + { + double d; + istrm.read(reinterpret_cast(&d), sizeof d); // binary input + int n; + std::string s; + if (istrm >> n >> s) // text input + std::cout << "read back from file: " << d << ' ' << n << ' ' << s << '\\n'; + } + } + +.SH Output: + + read back from file: 3.14 123 abc diff --git a/man/std::ifstream::basic_ifstream.3 b/man/std::ifstream::basic_ifstream.3 deleted file mode 120000 index da5f5ba66..000000000 --- a/man/std::ifstream::basic_ifstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::basic_ifstream.3 \ No newline at end of file diff --git a/man/std::ifstream::basic_ifstream.3 b/man/std::ifstream::basic_ifstream.3 new file mode 100644 index 000000000..f8e14c230 --- /dev/null +++ b/man/std::ifstream::basic_ifstream.3 @@ -0,0 +1,104 @@ +.TH std::basic_ifstream::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::basic_ifstream \- std::basic_ifstream::basic_ifstream + +.SH Synopsis + basic_ifstream(); \fB(1)\fP + explicit basic_ifstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in ); + explicit basic_ifstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + explicit basic_ifstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + template< class FsPath > + + explicit basic_ifstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + basic_ifstream( basic_ifstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ifstream( const basic_ifstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ifstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream f0; + std::ifstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ifstream f2(name); + std::ifstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::ifstream::close.3 b/man/std::ifstream::close.3 deleted file mode 120000 index 71411cd09..000000000 --- a/man/std::ifstream::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::close.3 \ No newline at end of file diff --git a/man/std::ifstream::close.3 b/man/std::ifstream::close.3 new file mode 100644 index 000000000..c0db90cca --- /dev/null +++ b/man/std::ifstream::close.3 @@ -0,0 +1,41 @@ +.TH std::basic_ifstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::close \- std::basic_ifstream::close + +.SH Synopsis + void close(); + + Closes the associated file. + + Effectively calls rdbuf()->close(). If an error occurs during operation, + setstate(failbit) is called. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called by the destructor of basic_ifstream when the stream object + goes out of scope and is not usually invoked directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ifstream::ifstream.3 b/man/std::ifstream::ifstream.3 deleted file mode 120000 index da5f5ba66..000000000 --- a/man/std::ifstream::ifstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::basic_ifstream.3 \ No newline at end of file diff --git a/man/std::ifstream::ifstream.3 b/man/std::ifstream::ifstream.3 new file mode 100644 index 000000000..f8e14c230 --- /dev/null +++ b/man/std::ifstream::ifstream.3 @@ -0,0 +1,104 @@ +.TH std::basic_ifstream::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::basic_ifstream \- std::basic_ifstream::basic_ifstream + +.SH Synopsis + basic_ifstream(); \fB(1)\fP + explicit basic_ifstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in ); + explicit basic_ifstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + explicit basic_ifstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + template< class FsPath > + + explicit basic_ifstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + basic_ifstream( basic_ifstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ifstream( const basic_ifstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ifstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream f0; + std::ifstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ifstream f2(name); + std::ifstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::ifstream::is_open.3 b/man/std::ifstream::is_open.3 deleted file mode 120000 index 286e339cb..000000000 --- a/man/std::ifstream::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::is_open.3 \ No newline at end of file diff --git a/man/std::ifstream::is_open.3 b/man/std::ifstream::is_open.3 new file mode 100644 index 000000000..180030db6 --- /dev/null +++ b/man/std::ifstream::is_open.3 @@ -0,0 +1,63 @@ +.TH std::basic_ifstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::is_open \- std::basic_ifstream::is_open + +.SH Synopsis + bool is_open() const; + + Checks if the file stream has an associated file. + + Effectively calls rdbuf()->is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the file stream has an associated file, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + // this file is called main.cpp + + bool file_exists(const std::string& str) + { + std::ifstream fs(str); + return fs.is_open(); + } + + int main() + { + std::boolalpha(std::cout); + std::cout << file_exists("main.cpp") << '\\n' + << file_exists("strange_file") << '\\n'; + } + +.SH Possible output: + + true + false + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP diff --git a/man/std::ifstream::native_handle.3 b/man/std::ifstream::native_handle.3 new file mode 100644 index 000000000..264f88e20 --- /dev/null +++ b/man/std::ifstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_ifstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::native_handle \- std::basic_ifstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::ifstream::open.3 b/man/std::ifstream::open.3 deleted file mode 120000 index 6755d8636..000000000 --- a/man/std::ifstream::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::open.3 \ No newline at end of file diff --git a/man/std::ifstream::open.3 b/man/std::ifstream::open.3 new file mode 100644 index 000000000..4b1131d62 --- /dev/null +++ b/man/std::ifstream::open.3 @@ -0,0 +1,84 @@ +.TH std::basic_ifstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::open \- std::basic_ifstream::open + +.SH Synopsis + void open( const char* filename, + + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::in ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::in ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + void open( const std::filesystem::path& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP + + = std::ios_base::in ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode | ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. It is a BitmaskType, the following constants + are defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + + 1. ↑ The resolution of LWG issue #22 is overriden. + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ifstream::operator=.3 b/man/std::ifstream::operator=.3 deleted file mode 120000 index 51b3bf9f4..000000000 --- a/man/std::ifstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::operator=.3 \ No newline at end of file diff --git a/man/std::ifstream::operator=.3 b/man/std::ifstream::operator=.3 new file mode 100644 index 000000000..149d17ae4 --- /dev/null +++ b/man/std::ifstream::operator=.3 @@ -0,0 +1,37 @@ +.TH std::basic_ifstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::operator= \- std::basic_ifstream::operator= + +.SH Synopsis + basic_ifstream& operator=( basic_ifstream&& other ); \fI(since C++11)\fP + + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_istream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. + +.SH Parameters + + other - file stream to move + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ifstream::rdbuf.3 b/man/std::ifstream::rdbuf.3 deleted file mode 120000 index 62dd2b519..000000000 --- a/man/std::ifstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::ifstream::rdbuf.3 b/man/std::ifstream::rdbuf.3 new file mode 100644 index 000000000..cb59a8031 --- /dev/null +++ b/man/std::ifstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_ifstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::rdbuf \- std::basic_ifstream::rdbuf + +.SH Synopsis + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP + + Returns pointer to the underlying raw file device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw file device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ifstream::swap.3 b/man/std::ifstream::swap.3 deleted file mode 120000 index 1cd4bf8db..000000000 --- a/man/std::ifstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::swap.3 \ No newline at end of file diff --git a/man/std::ifstream::swap.3 b/man/std::ifstream::swap.3 new file mode 100644 index 000000000..25e3093f1 --- /dev/null +++ b/man/std::ifstream::swap.3 @@ -0,0 +1,81 @@ +.TH std::basic_ifstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::swap \- std::basic_ifstream::swap + +.SH Synopsis + void swap( basic_ifstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_istream::swap(other) and + rdbuf()->swap(other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" + +.SH See also + + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::ignore.3 b/man/std::ignore.3 index c09c05ac2..db29d6784 100644 --- a/man/std::ignore.3 +++ b/man/std::ignore.3 @@ -1,37 +1,68 @@ -.TH std::ignore 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ignore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ignore \- std::ignore + .SH Synopsis Defined in header - const /*unspecified*/ ignore; \fI(since C++11)\fP + const /*unspecified*/ ignore; \fI(since C++11)\fP + \fI(until C++17)\fP + inline constexpr /*unspecified*/ ignore; \fI(since C++17)\fP An object of unspecified type such that any value can be assigned to it with no effect. Intended for use with std::tie when unpacking a std::tuple, as a placeholder for the arguments that are not used. + While the behavior of std::ignore outside of std::tie is not formally specified, + some code guides recommend using std::ignore to avoid warnings from unused return + values of [[nodiscard]] functions. + +.SH Possible implementation + + namespace detail { + struct ignore_t + { + template + constexpr // required since C++14 + void operator=(T&&) const noexcept {} + }; + } + inline constexpr detail::ignore_t ignore; // 'const' only until C++17 + .SH Example - unpack a pair returned by set.insert(), but only save the boolean. + 1. Demonstrates the use of std::ignore together with a [[nodiscard]] function. + 2. Unpacks a std::pair returned by std::set::insert(), but only + saves the boolean. - // Run this code #include - #include #include + #include #include - + + [[nodiscard]] int dontIgnoreMe() + { + return 42; + } + int main() { + std::ignore = dontIgnoreMe(); + std::set set_of_str; - bool inserted; + bool inserted = false; std::tie(std::ignore, inserted) = set_of_str.insert("Test"); - if (inserted) { - std::cout << "Value was inserted sucessfully\\n"; - } + if (inserted) + std::cout << "Value was inserted successfully\\n"; } .SH Output: - Value was inserted sucessfully + Value was inserted successfully + +.SH See also - tie creates a tuple of lvalue references or unpacks a tuple into individual objects - \fI(function template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into individual + \fI(C++11)\fP objects + \fI(function template)\fP diff --git a/man/std::ilogb,std::ilogbf,std::ilogbl.3 b/man/std::ilogb,std::ilogbf,std::ilogbl.3 new file mode 100644 index 000000000..0781b1a2b --- /dev/null +++ b/man/std::ilogb,std::ilogbf,std::ilogbl.3 @@ -0,0 +1,176 @@ +.TH std::ilogb,std::ilogbf,std::ilogbl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ilogb,std::ilogbf,std::ilogbl \- std::ilogb,std::ilogbf,std::ilogbl + +.SH Synopsis + Defined in header + int ilogb ( float num ); + \fI(since C++11)\fP + int ilogb ( double num ); (until C++23) + + int ilogb ( long double num ); + constexpr int ilogb( /* floating-point-type */ num (since C++23) + ); + int ilogbf( float num ); \fB(2)\fP \fI(since C++11)\fP + \fB(1)\fP (constexpr since C++23) + int ilogbl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + #define FP_ILOGB0 /* implementation-defined */ \fB(4)\fP \fI(since C++11)\fP + #define FP_ILOGBNAN /* implementation-defined */ \fB(5)\fP \fI(since C++11)\fP + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + int ilogb ( Integer num ); (constexpr since C++23) + + 1-3) Extracts the value of the unbiased exponent from the floating-point argument + num, and returns it as a signed integer value. + The library provides overloads of std::ilogb for all cv-unqualified floating-point + types as the type of the parameter num. + (since C++23) + 4) Expands to integer constant expression whose value is either INT_MIN or -INT_MAX. + 5) Expands to integer constant expression whose value is either INT_MIN or +INT_MAX. + A) Additional overloads are provided for all integer types, which are treated as + double. + + Formally, the unbiased exponent is the integral part of log + r|num| as a signed integral value, for non-zero num, where r is + std::numeric_limits::radix and T is the floating-point type of num. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the unbiased exponent of num is returned as a signed int value. + + If num is zero, FP_ILOGB0 is returned. + + If num is infinite, INT_MAX is returned. + + If num is a NaN, FP_ILOGBNAN is returned. + + If the correct result is greater than INT_MAX or smaller than INT_MIN, the return + value is unspecified. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + A domain error or range error may occur if num is zero, infinite, or NaN. + + If the correct result is greater than INT_MAX or smaller than INT_MIN, a domain + error or a range error may occur. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the correct result is greater than INT_MAX or smaller than INT_MIN, + FE_INVALID is raised. + * If num is ±0, ±∞, or NaN, FE_INVALID is raised. + * In all other cases, the result is exact (FE_INEXACT is never raised) and the + current rounding mode is ignored. + +.SH Notes + + If num is not zero, infinite, or NaN, the value returned is exactly equivalent to + static_cast(std::logb(num)). + + POSIX requires that a domain error occurs if num is zero, infinite, NaN, or if the + correct result is outside of the range of int. + + POSIX also requires that, on XSI-conformant systems, the value returned when the + correct result is greater than INT_MAX is INT_MAX and the value returned when the + correct result is less than INT_MIN is INT_MIN. + + The correct result can be represented as int on all known implementations. For + overflow to occur, INT_MAX must be less than LDBL_MAX_EXP * std::log2(FLT_RADIX) or + INT_MIN must be greater than LDBL_MIN_EXP - LDBL_MANT_DIG) * std::log2(FLT_RADIX). + + The value of the exponent returned by std::ilogb is always 1 less than the exponent + retuned by std::frexp because of the different normalization requirements: for the + exponent e returned by std::ilogb, |num*r-e + | is between 1 and r (typically between 1 and 2), but for the exponent e returned by + std::frexp, |num*2-e + | is between 0.5 and 1. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::ilogb(num) has the same effect as std::ilogb(static_cast(num)). + +.SH Example + + Compares different floating-point decomposition functions: + + +// Run this code + + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + int main() + { + double f = 123.45; + std::cout << "Given the number " << f << " or " << std::hexfloat + << f << std::defaultfloat << " in hex,\\n"; + + double f3; + double f2 = std::modf(f, &f3); + std::cout << "modf() makes " << f3 << " + " << f2 << '\\n'; + + int i; + f2 = std::frexp(f, &i); + std::cout << "frexp() makes " << f2 << " * 2^" << i << '\\n'; + + i = std::ilogb(f); + std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) << " * " + << std::numeric_limits::radix + << "^" << std::ilogb(f) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "ilogb(0) = " << std::ilogb(0) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, + modf() makes 123 + 0.45 + frexp() makes 0.964453 * 2^7 + logb()/ilogb() make 1.92891 * 2^6 + ilogb\fB(0)\fP = -2147483648 + FE_INVALID raised + +.SH See also + + frexp + frexpf decomposes a number into significand and base-2 exponent + frexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + logb + logbf + logbl extracts exponent of the number + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + scalbn + scalbnf + scalbnl + scalbln + scalblnf + scalblnl multiplies a number by FLT_RADIX raised to a power + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + ilogb diff --git a/man/std::ilogb.3 b/man/std::ilogb.3 deleted file mode 100644 index 8e5570aeb..000000000 --- a/man/std::ilogb.3 +++ /dev/null @@ -1,89 +0,0 @@ -.TH std::ilogb 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - int ilogb( float arg ); \fI(since C++11)\fP - int ilogb( double arg ); \fI(since C++11)\fP - int ilogb( long double arg ); \fI(since C++11)\fP - double ilogb( Integral arg ); \fI(since C++11)\fP - #define FP_ILOGB0 /*implementation-defined*/ \fI(since C++11)\fP - #define FP_ILOGBNAN /*implementation-defined*/ \fI(since C++11)\fP - - Extracts the value of the exponent from the floating-point argument arg, and returns - it as a signed integer value. Formally, the result is the integral part of log - r|arg| as a signed integral value, for non-zero arg, where r is - std::numeric_limits::radix and T is the floating-point type of arg. - -.SH Parameters - - arg - floating point value - -.SH Return value - - The floating-point exponent, cast to integer, as if by - static_cast(std::logb(arg)). - - Domain or range error may occur if arg is zero, FP_ILOGB0 is returned in that case. - - Domain or range error may occur if arg is infinite, INT_MAX is returned in that - case. - - Domain or range error may occur if arg is NaN, FP_ILOGBNAN is returned in that case. - - If the result cannot be represented as int, the result is undefined. - -.SH Notes - - The value of the exponent returned by std::ilogb is always 1 less than the exponent - retuned by std::frexp because of the different normalization requirements: for the - exponent e returned by std::ilogb, |arg*r-e - | is between 1 and r (typically between 1 and 2), but for the exponent e returned by - std::frexp, |arg*2-e - | is between 0.5 and 1. - -.SH Example - - Compares different floating-point decomposition functions - - -// Run this code - - #include - #include - #include - int main() - { - double f = 123.45; - std::cout << "Given the number " << f << " or " << std::hexfloat - << f << std::defaultfloat << " in hex,\\n"; - - double f3; - double f2 = std::modf(f, &f3); - std::cout << "modf() makes " << f3 << " + " << f2 << '\\n'; - - int i; - f2 = std::frexp(f, &i); - std::cout << "frexp() makes " << f2 << " * 2^" << i << '\\n'; - - i = std::ilogb(f); - std::cout << "logb()/ilogb() make " << f/std::scalbn(1.0, i) << " * " - << std::numeric_limits::radix - << "^" << std::ilogb(f) << '\\n'; - } - -.SH Output: - - Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, - modf() makes 123 + 0.45 - frexp() makes 0.964453 * 2^7 - logb()/ilogb() make 1.92891 * 2^6 - -.SH See also - - frexp decomposes a number into significand and a power of 2 - \fI(function)\fP - logb extracts exponent of the number - \fI(C++11)\fP \fI(function)\fP - scalbn - scalbln multiplies a number by FLT_RADIX raised to a power - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP diff --git a/man/std::imag(std::complex).3 b/man/std::imag(std::complex).3 index 992a94d6a..ec6feab1b 100644 --- a/man/std::imag(std::complex).3 +++ b/man/std::imag(std::complex).3 @@ -1,34 +1,74 @@ -.TH std::imag(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::imag(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::imag(std::complex) \- std::imag(std::complex) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(until C++14)\fP - T imag( const complex& z ); - template< class T > \fB(1)\fP \fI(since C++14)\fP - constexpr T imag( const complex& z ); - long double imag( long double z ); \fB(2)\fP \fI(since C++11)\fP - template< class DoubleOrIngeter > \fB(3)\fP \fI(since C++11)\fP - double imag( DoubleOrInteger z ); - float imag( float z ); \fB(4)\fP \fI(since C++11)\fP + template< class T > + T imag( const std::complex& z \fI(until C++14)\fP + ); + template< class T > + constexpr T imag( const \fI(since C++14)\fP + std::complex& z ); + Additional overloads \fI(since C++11)\fP + Defined in header + float imag( float f ); + + double imag( double f ); \fI(until C++14)\fP + + long double imag( long double f ); + constexpr float imag( float + f ); \fB(1)\fP - Returns the imaginary component of the complex number z, i.e. z.imag(). + constexpr double imag( double \fI(since C++14)\fP + f ); (until C++23) + (A) + constexpr long double imag( long + double f ); + template< class FloatingPoint > + FloatingPoint imag( FloatingPoint (since C++23) + f ); + template< class Integer > \fI(until C++14)\fP + double imag( Integer i ); + template< class Integer > (B) + constexpr double imag( Integer i \fI(since C++14)\fP + ); - Additional overloads are provided for float, double, long double, and all integer - types, which are treated as complex numbers with zero imaginary component. - \fI(since C++11)\fP + 1) Returns the imaginary part of the complex number z, i.e. z.imag(). + + A,B) Additional overloads are provided for all integer and + floating-point types, which are treated as complex numbers with zero \fI(since C++11)\fP + imaginary part. .SH Parameters z - complex value + f - floating-point value + i - integer value .SH Return value - the imaginary component of z + 1) The imaginary part of z. + A) decltype(f){} (zero). + B) 0.0. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num: + + * If num has a + standard + (until C++23) floating-point type T, then std::imag(num) has the same effect as + std::imag(std::complex(num)). + * Otherwise, if num has an integer type, then std::imag(num) has the same effect + as std::imag(std::complex(num)). .SH See also imag accesses the imaginary part of the complex number - \fI(public member function)\fP - real accesses the real part of the complex number - \fI(public member function)\fP - real returns the real component - \fI(function template)\fP + \fI(public member function)\fP + real returns the real part + \fI(function template)\fP + C documentation for + cimag diff --git a/man/std::in_place,std::in_place_type,std::in_place_index,std::in_place_t,.3 b/man/std::in_place,std::in_place_type,std::in_place_index,std::in_place_t,.3 new file mode 100644 index 000000000..e26dbb620 --- /dev/null +++ b/man/std::in_place,std::in_place_type,std::in_place_index,std::in_place_t,.3 @@ -0,0 +1,49 @@ +.TH std::in_place,std::in_place_type,std::in_place_index,std::in_place_t, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::in_place,std::in_place_type,std::in_place_index,std::in_place_t, \- std::in_place,std::in_place_type,std::in_place_index,std::in_place_t, + +.SH Synopsis + + Defined in header + struct in_place_t { explicit in_place_t() = default; }; \fB(1)\fP \fI(since C++17)\fP + inline constexpr std::in_place_t in_place {}; \fB(2)\fP \fI(since C++17)\fP + template< class T > \fB(3)\fP \fI(since C++17)\fP + struct in_place_type_t { explicit in_place_type_t() = default; }; + template< class T > \fB(4)\fP \fI(since C++17)\fP + inline constexpr std::in_place_type_t in_place_type {}; + template< std::size_t I > + struct in_place_index_t { explicit in_place_index_t() = default; \fB(5)\fP \fI(since C++17)\fP + }; + template< std::size_t I > \fB(6)\fP \fI(since C++17)\fP + inline constexpr std::in_place_index_t in_place_index {}; + + 1,3,5) The type/type templates std::in_place_t, std::in_place_type_t and + std::in_place_index_t can be used in the constructor's parameter list to match the + intended tag. + 2,4,6) The corresponding std::in_place, std::in_place_type, and std::in_place_index + instances of (1,3,5) are disambiguation tags that can be passed to the constructors + of std::expected, std::optional, std::variant, and std::any to indicate that the + contained object should be constructed in-place, and (for the latter two) the type + of the object to be constructed. + +.SH Standard library + + The following standard library vocabulary types use (1-6) as disambiguation tags: + + expected a wrapper that contains either an expected or error value + (C++23) \fI(class template)\fP + optional a wrapper that may or may not hold an object + \fI(C++17)\fP \fI(class template)\fP + variant a type-safe discriminated union + \fI(C++17)\fP \fI(class template)\fP + any objects that hold instances of any CopyConstructible type + \fI(C++17)\fP \fI(class)\fP + +.SH See also + + sorted_unique indicates that elements of a range are sorted and unique + sorted_unique_t (tag) + (C++23) + sorted_equivalent indicates that elements of a range are sorted (uniqueness is not + sorted_equivalent_t required) + (C++23) (tag) diff --git a/man/std::in_place.3 b/man/std::in_place.3 deleted file mode 100644 index 145c9e6bf..000000000 --- a/man/std::in_place.3 +++ /dev/null @@ -1,15 +0,0 @@ -.TH std::in_place 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - constexpr in_place_t in_place{}; \fI(since C++14)\fP - - std::in_place is a constant of type std::in_place_t that is used to disambiguate the - overloads of constructors and member functions of that take arguments (possibly a - parameter pack) for in-place construction of some value. - -.SH See also - - in_place_t disambiguation tag type for in-place construction of optional types - \fI(C++14)\fP \fI(class)\fP - optional a wrapper that may or may not hold an object - \fI(C++14)\fP \fI(class template)\fP diff --git a/man/std::in_place_t.3 b/man/std::in_place_t.3 deleted file mode 100644 index 89e6bdf95..000000000 --- a/man/std::in_place_t.3 +++ /dev/null @@ -1,15 +0,0 @@ -.TH std::in_place_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - struct in_place_t {}; \fI(since C++14)\fP - - std::in_place_t is an empty class type used to disambiguate the overloads of - constructors and member functions of that take arguments (possibly a parameter pack) - for in-place construction of some value. - -.SH See also - - in_place an object of type std::in_place_t - \fI(C++14)\fP \fI(function)\fP - optional a wrapper that may or may not hold an object - \fI(C++14)\fP \fI(class template)\fP diff --git a/man/std::in_range.3 b/man/std::in_range.3 new file mode 100644 index 000000000..d873bd38b --- /dev/null +++ b/man/std::in_range.3 @@ -0,0 +1,71 @@ +.TH std::in_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::in_range \- std::in_range + +.SH Synopsis + Defined in header + template< class R, class T > \fI(since C++20)\fP + constexpr bool in_range( T t ) noexcept; + + Returns true if the value of t is in the range of values that can be represented in + R, that is, if t can be converted to R in a value-preserving manner. + + It is a compile-time error if either T or U is a non-integer type, a character type, + or bool. + +.SH Parameters + + t - value to test + +.SH Return value + + true if the value of t is representable in R, false otherwise. + +.SH Possible implementation + + template + constexpr bool in_range(T t) noexcept + { + return std::cmp_greater_equal(t, std::numeric_limits::min()) && + std::cmp_less_equal(t, std::numeric_limits::max()); + } + +.SH Notes + + This function cannot be used with enums (including std::byte), char, char8_t, + char16_t, char32_t, wchar_t and bool. + + Feature-test macro Value Std Feature + __cpp_lib_integer_comparison_functions 202002L (C++20) Integer comparison functions + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::cout << std::in_range(-1) << '\\n'; + std::cout << std::in_range(42) << '\\n'; + } + +.SH Output: + + false + true + +.SH See also + + ranges::min returns the smaller of the given values + (C++20) (niebloid) + ranges::max returns the greater of the given values + (C++20) (niebloid) + ranges::clamp clamps a value between a pair of boundary values + (C++20) (niebloid) + lerp linear interpolation function + (C++20) \fI(function)\fP diff --git a/man/std::includes.3 b/man/std::includes.3 index 4117c1de0..437f7f3eb 100644 --- a/man/std::includes.3 +++ b/man/std::includes.3 @@ -1,57 +1,124 @@ -.TH std::includes 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::includes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::includes \- std::includes + .SH Synopsis Defined in header template< class InputIt1, class InputIt2 > - bool includes( InputIt1 first1, InputIt1 last1, \fB(1)\fP + bool includes( InputIt1 first1, InputIt1 last1, \fB(1)\fP (constexpr since C++20) InputIt2 first2, InputIt2 last2 ); - template< class InputIt1, class InputIt2 > + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + bool includes( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, + + ForwardIt2 first2, ForwardIt2 last2 ); + template< class InputIt1, class InputIt2, class Compare + > + + bool includes( InputIt1 first1, InputIt1 last1, \fB(3)\fP (constexpr since C++20) + + InputIt2 first2, InputIt2 last2, Compare + comp ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + Compare > + bool includes( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, - bool includes( InputIt1 first1, InputIt1 last1, \fB(2)\fP + ForwardIt2 first2, ForwardIt2 last2, + Compare comp ); - InputIt2 first2, InputIt2 last2, Compare comp ); + Returns true if the sorted range [first2, last2) is a subsequence of the sorted + range [first1, last1) (a subsequence need not be contiguous). - Returns true if every element from the sorted range [first2, last2) is found within - the sorted range [first1, last1). Also returns true if [first2, last2) is empty. + 1) If [first1, last1) or [first2, last2) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first1, last1) or [first2, last2) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if - The first version expects both ranges to be sorted with operator<, the second - version expects them to be sorted with the given comparison function comp. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first1, last1 - the sorted range of elements to examine first2, last2 - the sorted range of elements to search for + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type InputIt can be dereferenced and then implicitly converted to both of - them. + them. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of Compare. .SH Return value - true if every element from [first2, last2) is a member of [first, last). + true if [first2, last2) is a subsequence of [first1, last1); otherwise false. + + An empty sequence is a subsequence of any sequence, so true is returned if + [first2, last2) is empty. .SH Complexity - At most 2·(N[1]+N[2]-1) comparisons, where N[1] = std::distance(first1, last1) and - N[2] = std::distance(first2, last2). + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + include \fB(1)\fP template bool includes(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2) @@ -60,13 +127,13 @@ { if (first1 == last1 || *first2 < *first1) return false; - if ( !(*first1 < *first2) ) + if (!(*first1 < *first2)) ++first2; } return true; } -.SH Second version - template + include \fB(3)\fP + template bool includes(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, Compare comp) { @@ -82,58 +149,70 @@ .SH Example - + // Run this code - #include #include #include - + #include + + template + Os& operator<<(Os& os, const Co& v) + { + for (const auto& i : v) + os << i << ' '; + return os << '\\t'; + } + int main() { - std::vector v1 {'a', 'b', 'c', 'f', 'h', 'x'}; - std::vector v2 {'a', 'b', 'c'}; - std::vector v3 {'a', 'c'}; - std::vector v4 {'g'}; - std::vector v5 {'a', 'c', 'g'}; - std::vector v6; - - for (auto i : v1) std::cout << i << ' '; - std::cout << "includes:\\n"; - - for (auto i : v2) std::cout << i << ' '; - std::cout << ": " << std::includes(v1.begin(), v1.end(), v2.begin(), v2.end()) << '\\n'; - for (auto i : v3) std::cout << i << ' '; - std::cout << ": " << std::includes(v1.begin(), v1.end(), v3.begin(), v3.end()) << '\\n'; - for (auto i : v4) std::cout << i << ' '; - std::cout << ": " << std::includes(v1.begin(), v1.end(), v4.begin(), v4.end()) << '\\n'; - for (auto i : v5) std::cout << i << ' '; - std::cout << ": " << std::includes(v1.begin(), v1.end(), v5.begin(), v5.end()) << '\\n'; - for (auto i : v6) std::cout << i << ' '; - std::cout << ": " << std::includes(v1.begin(), v1.end(), v6.begin(), v6.end()) << '\\n'; - - auto cmp_nocase = [](char a, char b) { - return std::tolower(a) < std::tolower(b); - }; - std::vector v7 {'A', 'B', 'C'}; - for (auto i : v7) std::cout << i << ' '; - std::cout << ": " - << std::includes(v1.begin(), v1.end(), v7.begin(), v7.end(), cmp_nocase) - << '\\n'; + const auto + v1 = {'a', 'b', 'c', 'f', 'h', 'x'}, + v2 = {'a', 'b', 'c'}, + v3 = {'a', 'c'}, + v4 = {'a', 'a', 'b'}, + v5 = {'g'}, + v6 = {'a', 'c', 'g'}, + v7 = {'A', 'B', 'C'}; + + auto no_case = [](char a, char b) { return std::tolower(a) < std::tolower(b); }; + + std::cout + << v1 << "\\nincludes:\\n" << std::boolalpha + << v2 << ": " << std::includes(v1.begin(), v1.end(), v2.begin(), v2.end()) << '\\n' + << v3 << ": " << std::includes(v1.begin(), v1.end(), v3.begin(), v3.end()) << '\\n' + << v4 << ": " << std::includes(v1.begin(), v1.end(), v4.begin(), v4.end()) << '\\n' + << v5 << ": " << std::includes(v1.begin(), v1.end(), v5.begin(), v5.end()) << '\\n' + << v6 << ": " << std::includes(v1.begin(), v1.end(), v6.begin(), v6.end()) << '\\n' + << v7 << ": " << std::includes(v1.begin(), v1.end(), v7.begin(), v7.end(), no_case) + << " (case-insensitive)\\n"; } .SH Output: - a b c f h x includes: - a b c : 1 - a c : 1 - g : 0 - a c g : 0 - A B C : 1 + a b c f h x + includes: + a b c : true + a c : true + a a b : false + g : false + a c g : false + A B C : true (case-insensitive) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1205 C++98 the return value was unclear if returns true in this + [first2, last2) is empty case .SH See also - set_difference computes the difference between two sets - \fI(function template)\fP - search searches for a range of elements - \fI(function template)\fP + set_difference computes the difference between two sets + \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + ranges::includes returns true if one sequence is a subsequence of another + (C++20) (niebloid) diff --git a/man/std::inclusive_scan.3 b/man/std::inclusive_scan.3 new file mode 100644 index 000000000..74387cb22 --- /dev/null +++ b/man/std::inclusive_scan.3 @@ -0,0 +1,198 @@ +.TH std::inclusive_scan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inclusive_scan \- std::inclusive_scan + +.SH Synopsis + Defined in header + template< class InputIt, class OutputIt > + \fI(since C++17)\fP + OutputIt inclusive_scan( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + + OutputIt d_first ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + ForwardIt2 inclusive_scan( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 + last, + + ForwardIt2 d_first ); + template< class InputIt, class OutputIt, class BinaryOp + > + \fI(since C++17)\fP + OutputIt inclusive_scan( InputIt first, InputIt last, \fB(3)\fP (constexpr since C++20) + + OutputIt d_first, BinaryOp op + ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + BinaryOp > + ForwardIt2 inclusive_scan( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 + last, + + ForwardIt2 d_first, BinaryOp + op ); + template< class InputIt, class OutputIt, + + class BinaryOp, class T > \fI(since C++17)\fP + OutputIt inclusive_scan( InputIt first, InputIt last, \fB(5)\fP (constexpr since C++20) + + OutputIt d_first, BinaryOp op, + T init ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class BinaryOp, class T > + ForwardIt2 inclusive_scan( ExecutionPolicy&& policy, \fB(6)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 + last, + + ForwardIt2 d_first, BinaryOp + op, T init ); + + 1) Equivalent to inclusive_scan(first, last, d_first, std::plus<>(). + 3) Computes the inclusive prefix sum using op. + For each integer i in [0, std::distance(first, last)), performs the following + operations in order: + 1. Creates a sequence which is formed by the elements of [first, iter] in order, + where iter is the next i + th iterator of first. + 2. Computes the generalized noncommutative sum of the sequence over op. + 3. Assigns the result to *dest, where dest is the next i + th iterator of d_first. + 5) Same as \fB(3)\fP, but each sequence created is formed by init followed by the elements + of [first, iter] in order. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + The generalized, noncommutative sum of a sequence of elements over a binary + operation binary_op is defined as follows: + + * If the sequence only has one element, the sum is the value of the element. + * Otherwise, performs the following operations in order: + 1. Selects any two adjacent elements elem1 and elem2 from the sequence. + 2. Calculates binary_op(elem1, elem2) and replaces the two elements in the sequence + with the result. + 3. Repeats steps 1 and 2 until there is only one element in the sequence. + + Given binary_op as the actual binary operation: + + * The result is non-deterministic if the binary_op is not associative (such as + floating-point addition). + * For overloads (1-4), if binary_op(*first, *first) is not convertible to the + value type of decltype(first), the program is ill-formed. + * For overloads (5,6), if any of the following values is not convertible to T, the + program is ill-formed: + + * binary_op(init, *first) + * binary_op(init, init) + * binary_op(*first, *first) + * If any of the following conditions is satisfied, the behavior is undefined: + + * For overloads (1-4), the value type of decltype(first) is not MoveConstructible. + * For overloads (5,6), T is not MoveConstructible. + * binary_op modifies any element of [first, last). + * binary_op invalidates any iterator or subrange of [first, last]. + +.SH Parameters + + first, last - the range of elements to sum + d_first - the beginning of the destination range; may be equal to first + policy - the execution policy to use. See execution policy for details. + init - the initial value + binary FunctionObject that will be applied in to the result of + op - dereferencing the input iterators, the results of other op, and init + (if provided) +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + +.SH Return value + + Iterator to the element past the last element written. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) \\(\\scriptsize O(N)\\)O(N) applications of std::plus<>(). + 3-6) \\(\\scriptsize O(N)\\)O(N) applications of op. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector data{3, 1, 4, 1, 5, 9, 2, 6}; + + std::cout << "Exclusive sum: "; + std::exclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + 0); + + std::cout << "\\nInclusive sum: "; + std::inclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " ")); + + std::cout << "\\n\\nExclusive product: "; + std::exclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + 1, std::multiplies<>{}); + + std::cout << "\\nInclusive product: "; + std::inclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + std::multiplies<>{}); + } + +.SH Output: + + Exclusive sum: 0 3 4 8 9 14 23 25 + Inclusive sum: 3 4 8 9 14 23 25 31 + + Exclusive product: 1 3 3 12 12 60 540 1080 + Inclusive product: 3 3 12 12 60 540 1080 6480 + +.SH See also + + computes the differences between adjacent elements in a + adjacent_difference range + \fI(function template)\fP + accumulate sums up or folds a range of elements + \fI(function template)\fP + partial_sum computes the partial sum of a range of elements + \fI(function template)\fP + transform_inclusive_scan applies an invocable, then calculates inclusive scan + \fI(C++17)\fP \fI(function template)\fP + exclusive_scan similar to std::partial_sum, excludes the i^th input + \fI(C++17)\fP element from the i^th sum + \fI(function template)\fP diff --git a/man/std::incrementable.3 b/man/std::incrementable.3 new file mode 100644 index 000000000..cb80e9c0b --- /dev/null +++ b/man/std::incrementable.3 @@ -0,0 +1,44 @@ +.TH std::incrementable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::incrementable \- std::incrementable + +.SH Synopsis + Defined in header + template< class I > + + concept incrementable = + std::regular && + std::weakly_incrementable && \fI(since C++20)\fP + requires(I i) { + { i++ } -> std::same_as; + + }; + + This concept specifies requirements on types that can be incremented with the pre- + and post-increment operators, whose increment operations are equality-preserving, + and the type is std::equality_comparable. + + Unlike with std::weakly_incrementable, which only support single-pass algorithms, + multi-pass one-directional algorithms can be used with types that model + std::incrementable. + + Semantic requirements + + I models std::incrementable only if given any two incrementable objects a and b of + type I: + + * bool(a == b) implies bool(a++ == b), and + * bool(a == b) implies bool(((void)a++, a) == ++b). + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH See also + + weakly_incrementable specifies that a semiregular type can be incremented with pre- + (C++20) and post-increment operators + (concept) + same_as specifies that a type is the same as another type + (C++20) (concept) diff --git a/man/std::incrementable_traits.3 b/man/std::incrementable_traits.3 new file mode 100644 index 000000000..cf7af12a7 --- /dev/null +++ b/man/std::incrementable_traits.3 @@ -0,0 +1,64 @@ +.TH std::incrementable_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::incrementable_traits \- std::incrementable_traits + +.SH Synopsis + Defined in header + template< class I, class S > + + struct incrementable_traits> { \fI(since C++20)\fP + using difference_type = std::iter_difference_t; + + }; + + Provides the uniform interface to the associated difference type of the + std::common_iterator type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using CI = std::common_iterator< + std::counted_iterator, + std::default_sentinel_t>; + using CL = std::common_iterator< + std::counted_iterator::iterator>, + std::default_sentinel_t>; + CL cl{std::default_sentinel}; + static_assert( + std::same_as::difference_type, std::ptrdiff_t> && + std::same_as::difference_type, std::ptrdiff_t> && + std::same_as::difference_type, + std::ptrdiff_t>); + } + +.SH See also + + incrementable_traits computes the difference type of a + (C++20) weakly_incrementable type + \fI(class template)\fP + iter_value_t + iter_reference_t + iter_const_reference_t + iter_difference_t + iter_rvalue_reference_t computes the associated types of an + iter_common_reference_t iterator + (C++20) (alias template) + (C++20) + (C++23) + (C++20) + (C++20) + (C++20) + provides uniform interface to the + std::iterator_traits properties of the std::common_iterator + (C++20) type + \fI(class template specialization)\fP diff --git a/man/std::independent_bits_engine.3 b/man/std::independent_bits_engine.3 index 07f58f5f6..581250a30 100644 --- a/man/std::independent_bits_engine.3 +++ b/man/std::independent_bits_engine.3 @@ -1,4 +1,7 @@ -.TH std::independent_bits_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine \- std::independent_bits_engine + .SH Synopsis Defined in header template< @@ -14,43 +17,58 @@ .SH Template parameters - Engine - the type of the wrapped engine - W - the number of bits the generated numbers should have - UIntType - the type of the generated random numbers. The type must be unsigned - integral type. + Engine - the type of the wrapped engine + W - the number of bits the generated numbers should have + the type of the generated random numbers. The effect is undefined + UIntType - unless the parameter is cv-unqualified and is one of unsigned short, + unsigned int, unsigned long, or unsigned long long. .SH Type requirements - Engine must meet the requirements of RandomNumberEngine. + - + W must be greater than zero, and no greater than + std::numeric_limits::digits. .SH Member types - Member type Definition - result_type UIntType + Member type Definition + result_type \fI(C++11)\fP UIntType .SH Member functions - constructor constructs the engine adaptor - \fI(public member function)\fP - seed sets the state of the underlying engine - \fI(public member function)\fP - base returns the underlying engine - \fI(public member function)\fP + constructor constructs the engine adaptor + \fI(C++11)\fP \fI(public member function)\fP + seed sets the state of the underlying engine + \fI(C++11)\fP \fI(public member function)\fP + base returns the underlying engine + \fI(C++11)\fP \fI(public member function)\fP .SH Generation - advances the state of the underlying engine and returns the generated - operator() value - \fI(public member function)\fP - discard advances the adaptor's state by a specified amount - \fI(public member function)\fP + operator() advances the state of the underlying engine and returns the + \fI(C++11)\fP generated value + \fI(public member function)\fP + discard advances the adaptor's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - min gets the smallest possible value in the output range (always zero). - \fB[static]\fP \fI(public static member function)\fP - max gets the largest possible value in the output range (always 2w - \fB[static]\fP -1). - \fI(public static member function)\fP + min gets the smallest possible value in the output range (always zero). + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + max gets the largest possible value in the output range (always 2w + \fB[static]\fP \fI(C++11)\fP - 1). + \fI(public static member function)\fP .SH Non-member functions - operator== compares the internal states of the adaptors and underlying engines - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number engine adaptor - operator>> \fI(function)\fP + operator== compares the internal states of the adaptors and + operator!= underlying engines + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> engine adaptor + \fI(C++11)\fP \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::independent_bits_engine::base.3 b/man/std::independent_bits_engine::base.3 index d3fc7f329..83737558d 100644 --- a/man/std::independent_bits_engine::base.3 +++ b/man/std::independent_bits_engine::base.3 @@ -1,6 +1,9 @@ -.TH std::independent_bits_engine::base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::base \- std::independent_bits_engine::base + .SH Synopsis - const Engine& base() const; \fI(since C++11)\fP + const Engine& base() const noexcept; \fI(since C++11)\fP Returns the underlying engine. @@ -11,9 +14,3 @@ .SH Return value The underlying engine. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::independent_bits_engine::discard.3 b/man/std::independent_bits_engine::discard.3 index ff84464bd..a54e1a8af 100644 --- a/man/std::independent_bits_engine::discard.3 +++ b/man/std::independent_bits_engine::discard.3 @@ -1,4 +1,7 @@ -.TH std::independent_bits_engine::discard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine::discard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::discard \- std::independent_bits_engine::discard + .SH Synopsis void discard( unsigned long long z ); \fI(since C++11)\fP @@ -16,10 +19,10 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH See also - advances the state of the underlying engine and returns the generated - operator() value - \fI(public member function)\fP + operator() advances the state of the underlying engine and returns the generated + \fI(C++11)\fP value + \fI(public member function)\fP diff --git a/man/std::independent_bits_engine::independent_bits_engine.3 b/man/std::independent_bits_engine::independent_bits_engine.3 index 770f5cbd7..b718b0ae0 100644 --- a/man/std::independent_bits_engine::independent_bits_engine.3 +++ b/man/std::independent_bits_engine::independent_bits_engine.3 @@ -1,20 +1,73 @@ -.TH std::independent_bits_engine::independent_bits_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine::independent_bits_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::independent_bits_engine \- std::independent_bits_engine::independent_bits_engine + .SH Synopsis independent_bits_engine(); \fB(1)\fP \fI(since C++11)\fP - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP + explicit independent_bits_engine( result_type s ); \fB(2)\fP \fI(since C++11)\fP + template< class Sseq > \fB(3)\fP \fI(since C++11)\fP explicit independent_bits_engine( Sseq& seq ); - explicit independent_bits_engine( const Engine& e ); \fB(3)\fP \fI(since C++11)\fP - explicit independent_bits_engine( Engine&& e ); \fB(4)\fP \fI(since C++11)\fP + explicit independent_bits_engine( const Engine& e ); \fB(4)\fP \fI(since C++11)\fP + explicit independent_bits_engine( Engine&& e ); \fB(5)\fP \fI(since C++11)\fP Constructs new pseudo-random engine adaptor. 1) Default constructor. The underlying engine is also default-constructed. - 2) Constructs the underlying engine with seed sequence seq. - 3) Constructs the underlying engine with a copy of e. - 4) Move-constructs the underlying engine with e. e holds unspecified, but valid + 2) Constructs the underlying engine with s. + 3) Constructs the underlying engine with seed sequence seq. This constructor only + participate in overload resolution if Sseq qualifies as a SeedSequence. In + particular, this constructor does not participate in overload resolution if Sseq is + implicitly convertible to result_type. + 4) Constructs the underlying engine with a copy of e. + 5) Move-constructs the underlying engine with e. e holds unspecified, but valid state afterwards. .SH Parameters + s - integer value to construct the underlying engine with seq - seed sequence to construct the underlying engine with e - pseudo-random number engine to initialize with + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto print = [](auto rem, auto engine, int count) + { + std::cout << rem << ": "; + for (int i {}; i != count; ++i) + std::cout << static_cast(engine()) << ' '; + std::cout << '\\n'; + }; + + std::independent_bits_engine + e1; // default-constructed + print("e1", e1, 8); + + std::independent_bits_engine + e2(1); // constructed with 1 + print("e2", e2, 8); + + std::random_device rd; + std::independent_bits_engine + e3(rd()); // seeded with rd() + print("e3", e3, 8); + + std::seed_seq s {3, 1, 4, 1, 5}; + std::independent_bits_engine + e4(s); // seeded with seed-sequence s + print("e4", e4, 8); + } + +.SH Possible output: + + e1: 0 0 0 1 0 1 1 1 + e2: 1 1 0 0 1 1 1 1 + e3: 3 1 5 4 3 2 3 4 + e4: 0 2 4 4 4 3 3 6 diff --git a/man/std::independent_bits_engine::max.3 b/man/std::independent_bits_engine::max.3 index 7309f74c6..1a53b0a58 100644 --- a/man/std::independent_bits_engine::max.3 +++ b/man/std::independent_bits_engine::max.3 @@ -1,10 +1,13 @@ -.TH std::independent_bits_engine::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::max \- std::independent_bits_engine::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP Returns the maximum value potentially generated by the engine adaptor. This value is equal to 2w - -1 + - 1. .SH Parameters @@ -16,9 +19,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::independent_bits_engine::min.3 b/man/std::independent_bits_engine::min.3 index 926a132bd..fc70d8bbd 100644 --- a/man/std::independent_bits_engine::min.3 +++ b/man/std::independent_bits_engine::min.3 @@ -1,9 +1,12 @@ -.TH std::independent_bits_engine::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::min \- std::independent_bits_engine::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP Returns the minimum value potentially generated by the engine adaptor. This value is - equal to 0u + equal to 0u. .SH Parameters @@ -15,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::independent_bits_engine::operator().3 b/man/std::independent_bits_engine::operator().3 new file mode 100644 index 000000000..96328412a --- /dev/null +++ b/man/std::independent_bits_engine::operator().3 @@ -0,0 +1,26 @@ +.TH std::independent_bits_engine::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::operator() \- std::independent_bits_engine::operator() + +.SH Synopsis + result_type operator()(); \fI(since C++11)\fP + + Generates a random value. The state of the underlying engine is advanced one or more + times. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pseudo-random number in [min(), max()]. + +.SH Exceptions + + Throws nothing. + +.SH See also + + discard advances the adaptor's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::independent_bits_engine::seed.3 b/man/std::independent_bits_engine::seed.3 index dc7b5a7ef..ed3d4e285 100644 --- a/man/std::independent_bits_engine::seed.3 +++ b/man/std::independent_bits_engine::seed.3 @@ -1,4 +1,7 @@ -.TH std::independent_bits_engine::seed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::independent_bits_engine::seed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::independent_bits_engine::seed \- std::independent_bits_engine::seed + .SH Synopsis void seed(); \fB(1)\fP \fI(since C++11)\fP void seed( result_type value ); \fB(2)\fP \fI(since C++11)\fP @@ -12,7 +15,10 @@ 2) Seeds the underlying engine with the seed value s. Effectively calls e.seed(value), where e is the underlying engine. 3) Seeds the underlying engine with the seed sequence seq. Effectively calls - e.seed(seq), where e is the underlying engine. + e.seed(seq), where e is the underlying engine. This template only participate in + overload resolution if Sseq qualifies as a SeedSequence. In particular, this + template does not participate in overload resolution if Sseq is implicitly + convertible to result_type. .SH Parameters @@ -27,4 +33,4 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. diff --git a/man/std::indirect_array.3 b/man/std::indirect_array.3 index 190702095..17880a2e4 100644 --- a/man/std::indirect_array.3 +++ b/man/std::indirect_array.3 @@ -1,11 +1,14 @@ -.TH std::indirect_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::indirect_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_array \- std::indirect_array + .SH Synopsis Defined in header template< class T > class indirect_array; - std::gslice_array is a helper template used by std::indirect_array subscript - operator. It has reference semantics to a subset of the array specified by an - indirect array (std::valarray object). + std::indirect_array is a helper template used by the valarray subscript operator + with std::valarray argument. It has reference semantics to a subset of + the array whose indices specified by the std::valarray object. .SH Member types @@ -15,17 +18,17 @@ .SH Member functions constructor constructs a indirect_array - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a indirect_array - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP operator+= operator-= operator*= operator/= operator%= performs arithmetic operation on the array referred by indirect array. - operator&= \fI(public member function)\fP + operator&= \fI(public member function)\fP operator|= operator^= operator<<= @@ -33,28 +36,30 @@ .SH Example - + // Run this code #include #include - + int main() { - std::valarray data = {0,1,2,3,4,5,6,7,8,9}; - - std::valarray idx = {0,2,4,6,8}; - + std::valarray data{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + + std::valarray idx{0, 2, 4, 6, 8}; + std::cout << "Original valarray: "; - for(int n: data) std::cout << n << ' '; + for (int n : data) + std::cout << n << ' '; std::cout << '\\n'; - - data[idx] += data[idx]; // double the values at indexes 'idx' - + + data[idx] += data[idx]; // double the values at indices 'idx' + // the type of data[idx] is std::indirect_array - + std::cout << "After indirect modification: "; - for(int n: data) std::cout << n << ' '; + for (int n : data) + std::cout << n << ' '; std::cout << '\\n'; } diff --git a/man/std::indirect_array::indirect_array.3 b/man/std::indirect_array::indirect_array.3 index 4413852c5..9e8901c7a 100644 --- a/man/std::indirect_array::indirect_array.3 +++ b/man/std::indirect_array::indirect_array.3 @@ -1,12 +1,30 @@ -.TH std::indirect_array::indirect_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::indirect_array::indirect_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_array::indirect_array \- std::indirect_array::indirect_array + .SH Synopsis - indirect_array( const indirect_array& other ); + private: \fI(until C++11)\fP + indirect_array(); + public: \fB(1)\fP \fI(since C++11)\fP indirect_array() = delete; + public: \fB(2)\fP + indirect_array( const indirect_array& other ); - Constructs a indirect_array from another indirect_array other. - - The default constructor is implicitly deleted. + 1) The default constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: indirect_array is not DefaultConstructible. + 2) Constructs a indirect_array from another indirect_array other. .SH Parameters other - indirect_array to initialize with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 253 C++98 the copy constructor was private made public diff --git a/man/std::indirect_array::operator=.3 b/man/std::indirect_array::operator=.3 index 7cdc1d87d..d3c37e920 100644 --- a/man/std::indirect_array::operator=.3 +++ b/man/std::indirect_array::operator=.3 @@ -1,36 +1,86 @@ -.TH std::indirect_array::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::indirect_array::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_array::operator= \- std::indirect_array::operator= + .SH Synopsis - void operator=( const T& value ) const; \fB(1)\fP - void operator=( const std::valarray& val_arr ) const; \fB(2)\fP - const indirect_array& operator=( const indirect_array& sl_arr) \fB(3)\fP \fI(since C++11)\fP - const; + void operator=( const T& value ) const; \fB(1)\fP + void operator=( const std::valarray& val_arr ) const; \fB(2)\fP + const indirect_array& operator=( const indirect_array& other_arr ) const; \fB(3)\fP Assigns values to all referred elements. 1) Assigns value to all of the elements. 2) Assigns the elements of val_arr to the referred to elements of *this. - 3) Assigns the selected elements from sl_arr to the referred to elements of *this. + 3) Assigns the selected elements from other_arr to the referred to elements of + *this. .SH Parameters - value - a value to assign to all of the referred elements - val_arr - std::valarray to assign - sl_arr - std::indirect_array to assign + value - a value to assign to all of the referred elements + val_arr - std::valarray to assign + other_arr - std::indirect_array to assign .SH Return value - 1-2) \fI(none)\fP + 1,2) \fI(none)\fP 3) *this -.SH Exceptions +.SH Example - \fI(none)\fP -.SH Example +// Run this code + + #include + #include + #include + #include + + void print(int n, std::valarray const& v) + { + std::cout << n << ':'; + for (int e : v) + std::cout << std::setw(3) << e; + std::cout << '\\n'; + } + + int main() + { + std::valarray v(8); + std::iota(std::begin(v), std::end(v), 0); + print(1, v); + + std::valarray idx{1, 3, 5, 7}; + const std::indirect_array ia = v[idx]; + // 'ia' refers to v[1], v[3], v[5], v[7] + ia = -1; // (1), effectively: + // v[1] = v[3] = v[5] = v[7] = -1; + print(2, v); + + ia = /*std::valarray*/{-1, -2, -3, -4}; // (2), + // effectively: v[1] = -1, v[3] = -2, v[5] = -3, v[7] = -4; + print(3, v); + + std::valarray idx2{0, 2, 4, 6}; + const std::indirect_array ia2 = v[idx2]; + // 'ia2' refers to v[0], v[2], v[4], v[6] + ia = ia2; // (3), effectively: + // v[1] = v[0], v[3] = v[2], v[5] = v[4], v[7] = v[6]; + print(4, v); + } + +.SH Output: + + 1: 0 1 2 3 4 5 6 7 + 2: 0 -1 2 -1 4 -1 6 -1 + 3: 0 -1 2 -2 4 -3 6 -4 + 4: 0 0 2 2 4 4 6 6 - This section is incomplete - Reason: no example + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo no example + DR Applied to Behavior as published Correct behavior + LWG 123 C++98 overload \fB(2)\fP was non-const made const + LWG 253 C++98 the copy assignment operator was private made public + LWG 621 C++98 the copy assignment operator was non-const made const diff --git a/man/std::indirect_array::~indirect_array.3 b/man/std::indirect_array::~indirect_array.3 index 0c1ccbfdb..3af2e0536 100644 --- a/man/std::indirect_array::~indirect_array.3 +++ b/man/std::indirect_array::~indirect_array.3 @@ -1,6 +1,9 @@ -.TH std::indirect_array::~indirect_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::indirect_array::~indirect_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_array::~indirect_array \- std::indirect_array::~indirect_array + .SH Synopsis ~indirect_array(); - Destroys the indexes in the array. The elements referred to by the object are not + Destroys the indices in the array. The elements referred to by the object are not modified. diff --git a/man/std::indirect_binary_predicate.3 b/man/std::indirect_binary_predicate.3 new file mode 100644 index 000000000..915a062a2 --- /dev/null +++ b/man/std::indirect_binary_predicate.3 @@ -0,0 +1,33 @@ +.TH std::indirect_binary_predicate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_binary_predicate \- std::indirect_binary_predicate + +.SH Synopsis + Defined in header + template< class F, class I1, class I2 > + + concept indirect_binary_predicate = + std::indirectly_readable && + std::indirectly_readable && + std::copy_constructible && + std::predicate&, + std::iter_value_t&> && + std::predicate&, \fI(since C++20)\fP + std::iter_reference_t> && + std::predicate, + std::iter_value_t&> && + std::predicate, + std::iter_reference_t> && + + std::predicate, + std::iter_common_reference_t>; + + The concept indirect_binary_predicate specifies requirements for algorithms that + call binary predicates as their arguments. The key difference between this concept + and std::predicate is that it is applied to the types that I1 and I2 references, + rather than I1 and I2 themselves. + + Semantic requirements + + F, I1, and I2 model indirect_binary_predicate only if all concepts it subsumes are + modeled. diff --git a/man/std::indirect_equivalence_relation.3 b/man/std::indirect_equivalence_relation.3 new file mode 100644 index 000000000..e95386048 --- /dev/null +++ b/man/std::indirect_equivalence_relation.3 @@ -0,0 +1,33 @@ +.TH std::indirect_equivalence_relation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_equivalence_relation \- std::indirect_equivalence_relation + +.SH Synopsis + Defined in header + template< class F, class I1, class I2 = I1 > + + concept indirect_equivalence_relation = + std::indirectly_readable && + std::indirectly_readable && + std::copy_constructible && + std::equivalence_relation&, + std::iter_value_t&> && + std::equivalence_relation&, \fI(since C++20)\fP + std::iter_reference_t> && + std::equivalence_relation, + std::iter_value_t&> && + std::equivalence_relation, + std::iter_reference_t> && + std::equivalence_relation, + + std::iter_common_reference_t>; + + The concept indirect_equivalence_relation specifies requirements for algorithms that + call equivalence relations as their arguments. The key difference between this + concept and std::equivalence_relation is that it is applied to the types that I1 and + I2 references, rather than I1 and I2 themselves. + + Semantic requirements + + F, I1, and I2 model indirect_equivalence_relation only if all concepts it subsumes + are modeled. diff --git a/man/std::indirect_result_t.3 b/man/std::indirect_result_t.3 new file mode 100644 index 000000000..128a77460 --- /dev/null +++ b/man/std::indirect_result_t.3 @@ -0,0 +1,55 @@ +.TH std::indirect_result_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_result_t \- std::indirect_result_t + +.SH Synopsis + Defined in header + template< class F, class... Is > + + requires (std::indirectly_readable && ...) && + std::invocable...> \fI(since C++20)\fP + + using indirect_result_t = std::invoke_result_t...>; + + The alias template indirect_result_t obtains the result type of invoking an + invocable type F on the result of dereferencing indirectly_readable types Is.... + +.SH Template parameters + + F - an invocable type + Is - indirectly readable types that are dereferenced to arguments + +.SH Example + + +// Run this code + + #include + #include + + struct Fn + { + long operator()(const int&); + int operator()(int&&); + short operator()(int, int) const; + auto operator()(const float) -> int&; + void operator()(int[8]); + }; + + static_assert( + std::is_same_v, long> and + std::is_same_v>, int> and + std::is_same_v, short> and + std::is_same_v, int&> and + std::is_same_v, void> + ); + + int main() {} + +.SH See also + + result_of deduces the result type of invoking a callable object with + invoke_result a set of arguments + \fI(C++11)\fP(removed in C++20) \fI(class template)\fP + \fI(C++17)\fP diff --git a/man/std::indirect_strict_weak_order.3 b/man/std::indirect_strict_weak_order.3 new file mode 100644 index 000000000..f236c201e --- /dev/null +++ b/man/std::indirect_strict_weak_order.3 @@ -0,0 +1,33 @@ +.TH std::indirect_strict_weak_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_strict_weak_order \- std::indirect_strict_weak_order + +.SH Synopsis + Defined in header + template< class F, class I1, class I2 = I1 > + + concept indirect_strict_weak_order = + std::indirectly_readable && + std::indirectly_readable && + std::copy_constructible && + std::strict_weak_order&, + std::iter_value_t&> && + std::strict_weak_order&, \fI(since C++20)\fP + std::iter_reference_t> && + std::strict_weak_order, + std::iter_value_t&> && + std::strict_weak_order, + std::iter_reference_t> && + std::strict_weak_order, + + std::iter_common_reference_t>; + + The concept indirect_strict_weak_order specifies requirements for algorithms that + call strict weak orders as their arguments. The key difference between this concept + and std::strict_weak_order is that it is applied to the types that I1 and I2 + references, rather than I1 and I2 themselves. + + Semantic requirements + + F, I1, and I2 model indirect_strict_weak_order only if all concepts it subsumes are + modeled. diff --git a/man/std::indirect_unary_predicate.3 b/man/std::indirect_unary_predicate.3 new file mode 100644 index 000000000..212aba8c4 --- /dev/null +++ b/man/std::indirect_unary_predicate.3 @@ -0,0 +1,24 @@ +.TH std::indirect_unary_predicate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirect_unary_predicate \- std::indirect_unary_predicate + +.SH Synopsis + Defined in header + template< class F, class I > + + concept indirect_unary_predicate = + std::indirectly_readable && + std::copy_constructible && \fI(since C++20)\fP + std::predicate&> && + std::predicate> && + + std::predicate>; + + The concept indirect_unary_predicate specifies requirements for algorithms that call + unary predicates as their arguments. The key difference between this concept and + std::predicate is that it is applied to the type that I references, rather than I + itself. + + Semantic requirements + + F and I model indirect_unary_predicate only if all concepts it subsumes are modeled. diff --git a/man/std::indirectly_comparable.3 b/man/std::indirectly_comparable.3 new file mode 100644 index 000000000..f37aa9ed0 --- /dev/null +++ b/man/std::indirectly_comparable.3 @@ -0,0 +1,27 @@ +.TH std::indirectly_comparable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_comparable \- std::indirectly_comparable + +.SH Synopsis + Defined in header + template< class I1, class I2, class Comp, + + class Proj1 = std::identity, class Proj2 = std::identity > + concept indirectly_comparable = \fI(since C++20)\fP + + std::indirect_binary_predicate, + std::projected>; + + The concept indirectly_comparable specifies the fundamental algorithm requirement + for comparing values across two independent ranges. + + Semantic requirements + + indirectly_comparable is modeled only if all concepts it subsumes are modeled. + +.SH See also + + specifies that a callable type, when invoked with the + indirect_binary_predicate result of dereferencing two indirectly_readable types, + (C++20) satisfies predicate + (concept) diff --git a/man/std::indirectly_copyable.3 b/man/std::indirectly_copyable.3 new file mode 100644 index 000000000..947799c92 --- /dev/null +++ b/man/std::indirectly_copyable.3 @@ -0,0 +1,28 @@ +.TH std::indirectly_copyable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_copyable \- std::indirectly_copyable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept indirectly_copyable = \fI(since C++20)\fP + std::indirectly_readable && + + std::indirectly_writable>; + + The indirectly_copyable concept specifies the relationship between an + indirectly_readable type and a type that is indirectly_writable. The + indirectly_writable type must be able to directly copy the object that the + indirectly_readable type references. + +.SH See also + + indirectly_movable specifies that values may be moved from an + (C++20) indirectly_readable type to an indirectly_writable type + (concept) + specifies that values may be copied from an + indirectly_copyable_storable indirectly_readable type to an indirectly_writable type + (C++20) and that the copy may be performed via an intermediate + object + (concept) diff --git a/man/std::indirectly_copyable_storable.3 b/man/std::indirectly_copyable_storable.3 new file mode 100644 index 000000000..bff2b3421 --- /dev/null +++ b/man/std::indirectly_copyable_storable.3 @@ -0,0 +1,51 @@ +.TH std::indirectly_copyable_storable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_copyable_storable \- std::indirectly_copyable_storable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept indirectly_copyable_storable = + std::indirectly_copyable && + std::indirectly_writable&> && + std::indirectly_writable&> && + std::indirectly_writable&&> && \fI(since C++20)\fP + std::indirectly_writable&&> && + std::copyable> && + std::constructible_from, + std::iter_reference_t> && + + std::assignable_from&, + std::iter_reference_t>; + + The indirectly_copyable_storable concept specifies the relationship between an + indirectly_readable type and an indirectly_writable type. In addition to + indirectly_copyable, this concept specifies that the copy from the + indirectly_readable type can be performed via an intermediate object. + + Semantic requirements + + In and Out model std::indirectly_copyable_storable only if given a + dereferenceable value i of type In: + + * After the definition std::iter_value_t obj(*i);, obj is equal to the value + previously denoted by *i, and + * if std::iter_reference_t is an rvalue reference type, *i is placed in a + valid but unspecified state after the initialization of obj. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH See also + + indirectly_copyable specifies that values may be copied from an + (C++20) indirectly_readable type to an indirectly_writable type + (concept) + specifies that values may be moved from an + indirectly_movable_storable indirectly_readable type to an indirectly_writable type + (C++20) and that the move may be performed via an intermediate + object + (concept) diff --git a/man/std::indirectly_movable.3 b/man/std::indirectly_movable.3 new file mode 100644 index 000000000..d3084399d --- /dev/null +++ b/man/std::indirectly_movable.3 @@ -0,0 +1,28 @@ +.TH std::indirectly_movable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_movable \- std::indirectly_movable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept indirectly_movable = \fI(since C++20)\fP + std::indirectly_readable && + + std::indirectly_writable>; + + The indirectly_movable concept specifies the relationship between an + indirectly_readable type and a type that is indirectly_writable. The + indirectly_writable type must be able to directly move the object that the + indirectly_readable type references. + +.SH See also + + specifies that values may be moved from an + indirectly_movable_storable indirectly_readable type to an indirectly_writable type + (C++20) and that the move may be performed via an intermediate + object + (concept) + indirectly_copyable specifies that values may be copied from an + (C++20) indirectly_readable type to an indirectly_writable type + (concept) diff --git a/man/std::indirectly_movable_storable.3 b/man/std::indirectly_movable_storable.3 new file mode 100644 index 000000000..65b220d32 --- /dev/null +++ b/man/std::indirectly_movable_storable.3 @@ -0,0 +1,48 @@ +.TH std::indirectly_movable_storable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_movable_storable \- std::indirectly_movable_storable + +.SH Synopsis + Defined in header + template< class In, class Out > + + concept indirectly_movable_storable = + std::indirectly_movable && + std::indirectly_writable> && + std::movable> && \fI(since C++20)\fP + std::constructible_from, + std::iter_rvalue_reference_t> && + + std::assignable_from&, + std::iter_rvalue_reference_t>; + + The indirectly_movable_storable concept specifies the relationship between an + indirectly_readable type and an indirectly_writable type. In addition to + indirectly_movable, this concept specifies that the move from the + indirectly_readable type can be performed via an intermediate object. + + Semantic requirements + + In and Out model std::indirectly_movable_storable only if given a + dereferenceable value i of type In: + + * After the definition std::iter_value_t obj(ranges::iter_move(i));, obj is + equal to the value previously denoted by *i, and + * if std::iter_rvalue_reference_t is an rvalue reference type, *i is placed in + a valid but unspecified state after the initialization of obj. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH See also + + indirectly_movable specifies that values may be moved from an + (C++20) indirectly_readable type to an indirectly_writable type + (concept) + specifies that values may be copied from an + indirectly_copyable_storable indirectly_readable type to an indirectly_writable type + (C++20) and that the copy may be performed via an intermediate + object + (concept) diff --git a/man/std::indirectly_readable.3 b/man/std::indirectly_readable.3 new file mode 100644 index 000000000..b47404cb5 --- /dev/null +++ b/man/std::indirectly_readable.3 @@ -0,0 +1,47 @@ +.TH std::indirectly_readable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_readable \- std::indirectly_readable + +.SH Synopsis + Defined in header + template< class In > + + concept __IndirectlyReadableImpl = + requires(const In in) { + typename std::iter_value_t; + typename std::iter_reference_t; + typename std::iter_rvalue_reference_t; + { *in } -> std::same_as>; + { ranges::iter_move(in) } -> + std::same_as>; + } && (exposition + std::common_reference_with< only*) + std::iter_reference_t&&, std::iter_value_t& + > && + std::common_reference_with< + std::iter_reference_t&&, + std::iter_rvalue_reference_t&& + > && + std::common_reference_with< + std::iter_rvalue_reference_t&&, const + std::iter_value_t& + + >; + template< class In > + + concept indirectly_readable = \fI(since C++20)\fP + + __IndirectlyReadableImpl>; + + The concept indirectly_readable is modeled by types that are readable by applying + operator*, such as pointers, smart pointers, and input iterators. + + Semantic requirements + + Given a value i of type I, I models indirectly_readable only if all concepts it + subsumes are modeled and the expression *i is equality-preserving. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). diff --git a/man/std::indirectly_readable_traits.3 b/man/std::indirectly_readable_traits.3 new file mode 100644 index 000000000..4c4c810e2 --- /dev/null +++ b/man/std::indirectly_readable_traits.3 @@ -0,0 +1,147 @@ +.TH std::indirectly_readable_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_readable_traits \- std::indirectly_readable_traits + +.SH Synopsis + Defined in header + template< class I > \fB(1)\fP \fI(since C++20)\fP + struct indirectly_readable_traits {}; + template< class T > + + struct indirectly_readable_traits : \fB(2)\fP \fI(since C++20)\fP + + /* cond-value-type */ {}; + template< class I > + + requires std::is_array_v + struct indirectly_readable_traits; \fB(3)\fP \fI(since C++20)\fP + + { using value_type = + std::remove_cv_t>; } + template< class T > + + struct indirectly_readable_traits : \fB(4)\fP \fI(since C++20)\fP + + indirectly_readable_traits {}; + template< /* has-member-value-type */ T > + + struct indirectly_readable_traits : \fB(5)\fP \fI(since C++20)\fP + + /* cond-value-type */ {}; + template< /* has-member-element-type */ T > + + struct indirectly_readable_traits : \fB(6)\fP \fI(since C++20)\fP + + /* cond-value-type */ {}; + template< /* has-member-value-type */ T > + + requires /* has-member-element-type */ \fB(7)\fP \fI(since C++20)\fP + + struct indirectly_readable_traits {}; + template< /* has-member-value-type */ T > + + requires /* has-member-element-type */ && + std::same_as, \fB(8)\fP \fI(since C++20)\fP + std::remove_cv_t> + struct indirectly_readable_traits : + + /* cond-value-type */ {}; + Helper classes and concepts + template< class > \fB(1)\fP (exposition only*) + struct /* cond-value-type */ {}; + template< class T > + + requires std::is_object_v \fB(2)\fP (exposition only*) + struct /* cond-value-type */ + + { using value_type = std::remove_cv_t; }; + template< class T > + + concept /* has-member-value-type */ = \fB(3)\fP (exposition only*) + + requires { typename T::value_type; }; + template< class T > + + concept /* has-member-element-type */ = \fB(4)\fP (exposition only*) + + requires { typename T::element_type; }; + + Computes the associated value type of the template argument. If the associated value + type exists, it is represented by the nested type value_type, otherwise value_type + is not defined. A program may specialize indirectly_readable_traits for a + program-defined type. + +.SH Explanation + + The specializations above can be informally described as below. + + Given a type T, its associated value type V is determined as follows: + + * If T is const-qualified, V is the associated value type of const-unqualified T. + * Otherwise, if T is an array type, V is the cv-unqualified array element type. + * Otherwise, a conditional value type C is determined first: + + * If T is a pointer type, C is the pointed-to type. + * Otherwise, if T has nested types value_type and element_type: + + * If these types are the same (not considering cv-qualification), C is typename + T::value_type. + * Otherwise, C is undefined. + * Otherwise, if T has the nested type value_type but not element_type, C is + typename T::value_type. + * Otherwise, if T has the nested type element_type but not value_type, C is + typename T::element_type. + * Otherwise, C is undefined. + Then V is determined from C as follows: + * If C is undefined, or C is not an object type, V is undefined. + * Otherwise, V is cv-unqualified C. + +.SH Notes + + value_type is intended for use with indirectly_readable types such as iterators. It + is not intended for use with ranges. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + specializations (5,6) were ambiguous + LWG 3446 C++20 for types having added specialization (8) + both value_type and element_type nested + types + LWG 3446 introduced hard error for + LWG 3541 C++20 ambiguous cases added specialization (7) + that value_type and element_type are + different + +.SH See also + + indirectly_readable specifies that a type is indirectly readable by applying + (C++20) operator * + (concept) + iter_value_t + iter_reference_t + iter_const_reference_t + iter_difference_t + iter_rvalue_reference_t + iter_common_reference_t computes the associated types of an iterator + (C++20) (alias template) + (C++20) + (C++23) + (C++20) + (C++20) + (C++20) + iterator_traits provides uniform interface to the properties of an iterator + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::indirectly_swappable.3 b/man/std::indirectly_swappable.3 new file mode 100644 index 000000000..cd8cd41f5 --- /dev/null +++ b/man/std::indirectly_swappable.3 @@ -0,0 +1,40 @@ +.TH std::indirectly_swappable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_swappable \- std::indirectly_swappable + +.SH Synopsis + Defined in header + template< class I1, class I2 = I1 > + + concept indirectly_swappable = + std::indirectly_readable && + std::indirectly_readable && + requires( const I1 i1, const I2 i2 ) + { \fI(since C++20)\fP + ranges::iter_swap(i1, i1); + ranges::iter_swap(i1, i2); + ranges::iter_swap(i2, i1); + ranges::iter_swap(i2, i2); + + }; + + The concept indirectly_swappable specifies a relationship between two types + respectively modelling std::indirectly_readable, where their referenced types can be + swapped. + + Semantic requirements + + I1 and I2 model indirectly_swappable only if all concepts it subsumes are modeled. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH See also + + indirectly_readable specifies that a type is indirectly readable by applying + (C++20) operator * + (concept) + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) diff --git a/man/std::indirectly_unary_invocable,std::indirectly_regular_unary_invocable.3 b/man/std::indirectly_unary_invocable,std::indirectly_regular_unary_invocable.3 new file mode 100644 index 000000000..38277441a --- /dev/null +++ b/man/std::indirectly_unary_invocable,std::indirectly_regular_unary_invocable.3 @@ -0,0 +1,45 @@ +.TH std::indirectly_unary_invocable,std::indirectly_regular_unary_invocable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_unary_invocable,std::indirectly_regular_unary_invocable \- std::indirectly_unary_invocable,std::indirectly_regular_unary_invocable + +.SH Synopsis + Defined in header + template< class F, class I > + + concept indirectly_unary_invocable = + std::indirectly_readable && + std::copy_constructible && + std::invocable&> && \fI(since C++20)\fP + std::invocable> && + std::invocable> && + std::common_reference_with< + std::invoke_result_t&>, + + std::invoke_result_t>>; + template< class F, class I > + + concept indirectly_regular_unary_invocable = + std::indirectly_readable && + std::copy_constructible && + std::regular_invocable&> && + std::regular_invocable> && \fI(since C++20)\fP + std::regular_invocable> + && + std::common_reference_with< + std::invoke_result_t&>, + + std::invoke_result_t>>; + + The concepts indirectly_unary_invocable and indirectly_regular_unary_invocable + specify requirements for algorithms that call (regular) unary invocables as their + arguments. The key difference between these concepts and std::invocable is that they + are applied to the type the I references, rather than I itself. + + Semantic requirements + + Each concept is modeled by F and I only if all concepts it subsume are modeled. + +.SH Notes + + The distinction between indirectly_unary_invocable and + indirectly_regular_unary_invocable is purely semantic. diff --git a/man/std::indirectly_writable.3 b/man/std::indirectly_writable.3 new file mode 100644 index 000000000..573485de4 --- /dev/null +++ b/man/std::indirectly_writable.3 @@ -0,0 +1,54 @@ +.TH std::indirectly_writable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::indirectly_writable \- std::indirectly_writable + +.SH Synopsis + Defined in header + template< class Out, class T > + + concept indirectly_writable = + requires(Out&& o, T&& t) { + *o = std::forward(t); + *std::forward(o) = std::forward(t); + const_cast&&>(*o) = (since + std::forward(t); C++20) + const_cast&&>(*std::forward(o)) = + std::forward(t); + }; + + /* none of the four expressions above are required to be + equality-preserving */ + + The concept indirectly_writable specifies the requirements for writing a + value whose type and value category are encoded by T into an iterator Out's + referenced object. + + Semantic requirements + + Let e be an expression such that decltype((e)) is T, and o be a dereferenceable + object of type Out, then indirectly_writable is modeled only if: + + * If std::indirectly_readable is modeled and std::iter_value_t is the + same type as std::decay_t, then *o after any above assignment is equal to the + value of e before the assignment. + + o is not required to be dereferenceable after evaluating any of the assignment + expressions above. If e is an xvalue, the resulting state of the object it denotes + is valid but unspecified. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). + +.SH Notes + + The only valid use of operator* is on the left side of an assignment expression. + Assignment through the same value of an indirectly writable type may happen only + once. + + The required expressions with const_cast prevent indirectly_readable objects with + prvalue reference types from satisfying the syntactic requirements of + indirectly_writable by accident, while permitting proxy references to continue to + work as long as their constness is shallow. See Ranges TS issue 381. diff --git a/man/std::initializer_list.3 b/man/std::initializer_list.3 index 80e3619b5..9d9c26cc4 100644 --- a/man/std::initializer_list.3 +++ b/man/std::initializer_list.3 @@ -1,110 +1,126 @@ -.TH std::initializer_list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::initializer_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::initializer_list \- std::initializer_list + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP class initializer_list; An object of type std::initializer_list is a lightweight proxy object that - provides access to an array of objects of type T. + provides access to an array of objects of type const T (that may be allocated in + read-only memory). A std::initializer_list object is automatically constructed when: - * a braced-init-list is used in list-initialization, including function-call list - initialization and assignment expressions (not to be confused with constructor - initializer lists) - * a braced-init-list is bound to auto, including in a ranged for loop - - Initializer lists may be implemented as a pair of pointers or pointer and length. - Copying a std::initializer_list does not copy the underlying objects. The underlying - array is not guaranteed to exist after the lifetime of the original initializer list - object has ended. The storage for std::initializer_list is unspecified (i.e. it - could be automatic, temporary, or static read-only memory, depending on the - situation). + * a brace-enclosed initializer list is used to list-initialize an object, where + the corresponding constructor accepts an std::initializer_list parameter, + * a brace-enclosed initializer list is used as the right operand of assignment or + as a function call argument, and the corresponding assignment operator/function + accepts an std::initializer_list parameter, + * a brace-enclosed initializer list is bound to auto, including in a ranged for + loop. -.SH Member types + std::initializer_list may be implemented as a pair of pointers or pointer and + length. Copying a std::initializer_list does not copy the backing array of the + corresponding initializer list. - Member type Definition - value_type T - reference const T& - const_reference const T& - size_type size_t - iterator const T* - const_iterator const T* + The program is ill-formed if an explicit or partial specialization of + std::initializer_list is declared. .SH Member functions constructor creates an empty initializer list - \fI(public member function)\fP + \fI(public member function)\fP .SH Capacity size returns the number of elements in the initializer list - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators - begin returns a pointer the first element - \fI(public member function)\fP + begin returns a pointer to the first element + \fI(public member function)\fP end returns a pointer to one past the last element - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - std::begin(std::initializer_list) specializes std::begin - \fI(C++11)\fP \fI(function template)\fP + std::begin(std::initializer_list) overloads std::begin + \fI(C++11)\fP \fI(function template)\fP std::end(std::initializer_list) specializes std::end - \fI(C++11)\fP \fI(function template)\fP - Defined in header - rbegin(std::initializer_list) specializes std::rbegin - \fI(C++14)\fP \fI(function)\fP - rend(std::initializer_list) specializes std::rend - \fI(C++14)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function template)\fP + Free function templates overloaded for std::initializer_list + rbegin returns a reverse iterator to the beginning of a + crbegin container or array + \fI(C++14)\fP \fI(function template)\fP + rend returns a reverse end iterator for a container or + crend array + \fI(C++14)\fP \fI(function template)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_initializer_lists 200806L \fI(C++11)\fP List-initialization and + std::initializer_list .SH Example - + // Run this code + #include #include #include - #include - - template - struct S { + + template + struct S + { std::vector v; - S(std::initializer_list l) : v(l) { + + S(std::initializer_list l) : v(l) + { std::cout << "constructed with a " << l.size() << "-element list\\n"; } - void append(std::initializer_list l) { + + void append(std::initializer_list l) + { v.insert(v.end(), l.begin(), l.end()); } - std::pair c_arr() const { - return {&v[0], v.size()}; // list-initialization in return statement - // this is NOT a use of std::initializer_list + + std::pair c_arr() const + { + return {&v[0], v.size()}; // copy list-initialization in return statement + // this is NOT a use of std::initializer_list } }; - - template + + template void templated_fn(T) {} - + int main() { - S s = {1, 2, 3, 4, 5}; // direct list-initialization - s.append({6, 7, 8}); // list-initialization in function call - - std::cout << "The vector size is now " << s.c_arr().second << " ints:\\n"; - - for (auto n : s.v) std::cout << ' ' << n; - + S s = {1, 2, 3, 4, 5}; // copy list-initialization + s.append({6, 7, 8}); // list-initialization in function call + + std::cout << "The vector now has " << s.c_arr().second << " ints:\\n"; + + for (auto n : s.v) + std::cout << n << ' '; std::cout << '\\n'; - - std::cout << "range-for over brace-init-list: \\n"; - - for (int x : {-1, -2, -3}) // the rule for auto makes this ranged for work + + std::cout << "Range-for over brace-init-list: \\n"; + + for (int x : {-1, -2, -3}) // the rule for auto makes this ranged-for work std::cout << x << ' '; std::cout << '\\n'; - - auto al = {10, 11, 12}; // special rule for auto - + + auto al = {10, 11, 12}; // special rule for auto + std::cout << "The list bound to auto has size() = " << al.size() << '\\n'; - - // templated_fn({1, 2, 3}); // compiler error! "{1, 2, 3}" is not an expression, + + // templated_fn({1, 2, 3}); // compiler error! "{1, 2, 3}" is not an expression, // it has no type, and so T cannot be deduced templated_fn>({1, 2, 3}); // OK templated_fn>({1, 2, 3}); // also OK @@ -113,8 +129,25 @@ .SH Output: constructed with a 5-element list - The vector size is now 8 ints: - 1 2 3 4 5 6 7 8 - range-for over brace-init-list: + The vector now has 8 ints: + 1 2 3 4 5 6 7 8 + Range-for over brace-init-list: -1 -2 -3 The list bound to auto has size() = 3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::initializer_list could have explicit the program is + LWG 2129 C++11 specializations or partial ill-formed in this + specializations case + +.SH See also + + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::initializer_list::begin.3 b/man/std::initializer_list::begin.3 index eb99a57a0..f32f8b3bd 100644 --- a/man/std::initializer_list::begin.3 +++ b/man/std::initializer_list::begin.3 @@ -1,8 +1,11 @@ -.TH std::initializer_list::begin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::initializer_list::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::initializer_list::begin \- std::initializer_list::begin + .SH Synopsis - const T* begin() const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr const T* begin() const; \fI(since C++14)\fP + const T* begin() const noexcept; \fI(since C++11)\fP + \fI(until C++14)\fP + constexpr const T* begin() const noexcept; \fI(since C++14)\fP Returns a pointer to the first element in the initializer list. @@ -17,17 +20,24 @@ a pointer to the first element in the initializer list -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant +.SH Example + + +// Run this code + + #include + + int main() + { + static constexpr auto il = {42, 24}; + static_assert(*il.begin() == 0x2A); + } + .SH See also end returns a pointer to one past the last element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::initializer_list::end.3 b/man/std::initializer_list::end.3 index a90826765..ca273d66c 100644 --- a/man/std::initializer_list::end.3 +++ b/man/std::initializer_list::end.3 @@ -1,11 +1,14 @@ -.TH std::initializer_list::end 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::initializer_list::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::initializer_list::end \- std::initializer_list::end + .SH Synopsis - const T* end() const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr const T* end() const; \fI(since C++14)\fP + const T* end() const noexcept; \fI(since C++11)\fP + \fI(until C++14)\fP + constexpr const T* end() const noexcept; \fI(since C++14)\fP - Returns a pointer to one past the last element in the initializer list, i.e. begin() - + size(). + Returns a pointer to one past the last element in the initializer list, i.e. + begin()+size(). If the initializer list is empty, the values of begin() and end() are unspecified, but will be identical. @@ -18,17 +21,25 @@ a pointer to one past the last element in the initializer list -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant +.SH Example + + +// Run this code + + #include + #include + + int main() + { + static constexpr auto l = {15, 14}; + static_assert(std::accumulate(l.begin(), l.end(), 13) == 42); + } + .SH See also - begin returns a pointer the first element - \fI(public member function)\fP + begin returns a pointer to the first element + \fI(public member function)\fP diff --git a/man/std::initializer_list::initializer_list.3 b/man/std::initializer_list::initializer_list.3 index d0bb40474..930b462b0 100644 --- a/man/std::initializer_list::initializer_list.3 +++ b/man/std::initializer_list::initializer_list.3 @@ -1,8 +1,11 @@ -.TH std::initializer_list::initializer_list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::initializer_list::initializer_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::initializer_list::initializer_list \- std::initializer_list::initializer_list + .SH Synopsis - initializer_list(); \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr initializer_list(); \fI(since C++14)\fP + initializer_list() noexcept; \fI(since C++11)\fP + \fI(until C++14)\fP + constexpr initializer_list() noexcept; \fI(since C++14)\fP Constructs an empty initializer list. @@ -10,37 +13,45 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant +.SH Notes + + Despite a lack of constructors, it is possible to create non-empty initializer + lists. Instances of std::initializer_list are implicitly constructed when: + + * a braced-init-list is used in list-initialization, including function-call list + initialization and assignment expressions (not to be confused with constructor + initializer lists) + * a braced-init-list is bound to auto, including in a ranged for loop + .SH Example - + // Run this code #include #include - + int main() { std::initializer_list empty_list; std::cout << "empty_list.size(): " << empty_list.size() << '\\n'; - + // create initializer lists using list-initialization std::initializer_list digits {1, 2, 3, 4, 5}; std::cout << "digits.size(): " << digits.size() << '\\n'; - + // special rule for auto means 'fractions' has the // type std::initializer_list auto fractions = {3.14159, 2.71828}; std::cout << "fractions.size(): " << fractions.size() << '\\n'; + + // create constexpr initializer list \fI(since C++14)\fP + static constexpr auto ab = {'a', 'b'}; + static_assert(ab.size() == 2 and *ab.begin() == 'a'); } .SH Output: @@ -48,13 +59,3 @@ empty_list.size(): 0 digits.size(): 5 fractions.size(): 2 - -.SH Notes - - Despite a lack of constructors, it is possible to create non-empty initializer - lists. Instances of std::initializer_list are implicitly constructed when: - - * a braced-init-list is used in list-initialization, including function-call list - initialization and assignment expressions (not to be confused with constructor - initializer lists) - * a braced-init-list is bound to auto, including in a ranged for loop diff --git a/man/std::initializer_list::size.3 b/man/std::initializer_list::size.3 index d9cc728f6..4df3faa6f 100644 --- a/man/std::initializer_list::size.3 +++ b/man/std::initializer_list::size.3 @@ -1,8 +1,11 @@ -.TH std::initializer_list::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::initializer_list::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::initializer_list::size \- std::initializer_list::size + .SH Synopsis - size_type size() const; \fI(since C++11)\fP - \fI(until C++14)\fP - constexpr size_type size() const; \fI(since C++14)\fP + size_type size() const noexcept; \fI(since C++11)\fP + \fI(until C++14)\fP + constexpr size_type size() const noexcept; \fI(since C++14)\fP Returns the number of elements in the initializer list, i.e. std::distance(begin(), end()). @@ -15,12 +18,14 @@ the number of elements in the initializer list -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant + +.SH Example + + +// Run this code + + #include + int main() { static_assert(std::initializer_list{1,2,3,4}.size() == 4); } diff --git a/man/std::inner_product.3 b/man/std::inner_product.3 index 9842c3c33..caf2f0d25 100644 --- a/man/std::inner_product.3 +++ b/man/std::inner_product.3 @@ -1,38 +1,57 @@ -.TH std::inner_product 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::inner_product 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inner_product \- std::inner_product + .SH Synopsis Defined in header template< class InputIt1, class InputIt2, class T > - T inner_product( InputIt1 first1, InputIt1 last1, \fB(1)\fP - - InputIt2 first2, T value ); - template< - - class InputIt1, - class InputIt2, - class T, - class BinaryOperation1, \fB(2)\fP - class BinaryOperation2 - > T inner_product( InputIt1 first1, InputIt1 last1, - InputIt2 first2, T value, - BinaryOperation1 op1, - - BinaryOperation2 op2 ); - - Computes inner product (i.e. sum of products) of the range [first1, last1) and - another range beginning at first2. The first version uses operator* to compute - product of the element pairs and operator+ to sum up the products, the second - version uses op2 and op1 for these tasks respectively. - - op1 and op2 must not have side effects. \fI(until C++11)\fP - op1 and op2 must not invalidate any iterators, including the end \fI(since C++11)\fP - iterators, or modify any elements of the ranges involved. + T inner_product( InputIt1 first1, InputIt1 last1, \fB(1)\fP (constexpr since C++20) + + InputIt2 first2, T init ); + template< class InputIt1, class InputIt2, class T, + + class BinaryOp1, class BinaryOp2 > + T inner_product( InputIt1 first1, InputIt1 last1, \fB(2)\fP (constexpr since C++20) + InputIt2 first2, T init, + + BinaryOp1 op1, BinaryOp2 op2 ); + + Computes inner product (i.e. sum of products) or performs ordered map/reduce + operation on the range [first1, last1) and the range of std::distance(first1, + first2) elements beginning at first2. + + 1) Initializes the accumulator acc (of type T) with the initial value init and then + modifies it with the expression + acc = acc + (*i1) * (*i2) + \fI(until C++11)\fP + acc = std::move(acc) + (*i1) * (*i2) + \fI(since C++11)\fP for every iterator i1 in the range [first1, last1) in order and its + corresponding iterator i2 in the range beginning at first2. For built-in meaning of + + and *, this computes inner product of the two ranges. + 2) Initializes the accumulator acc (of type T) with the initial value init and then + modifies it with the expression + acc = op1(acc, op2(*i1, *i2)) + \fI(until C++11)\fP + acc = op1(std::move(acc), op2(*i1, *i2)) + \fI(since C++11)\fP for every iterator i1 in the range [first1, last1) in order and its + corresponding iterator i2 in the range beginning at first2. + + Given last2 as the std::distance(first1, last1) + th next iterator of first2, if any of the following conditions is satisfied, the + behavior is undefined: + + * T is not CopyConstructible. + * T is not CopyAssignable. + * op1 or op2 modifies any element of [first1, last1) or [first2, last2). + * op1 or op2 invalidates any iterator or subrange in [first1, last1] or + [first2, last2]. .SH Parameters first1, last1 - the first range of elements first2 - the beginning of the second range of elements - value - initial value of the sum of the products + init - initial value of the sum of the products binary operation function object that will be applied. This "sum" function takes a value returned by op2 and the current value of the accumulator and produces a new value to be stored in the @@ -43,10 +62,10 @@ Ret fun(const Type1 &a, const Type2 &b); The signature does not need to have const &. - The types Type1 and Type2 must be such that objects of types T and - Type3 can be implicitly converted to Type1 and Type2 respectively. + The types Type1 and Type2 must be such that objects of types T and + Type3 can be implicitly converted to Type1 and Type2 respectively. The type Ret must be such that an object of type T can be assigned a - value of type Ret. + value of type Ret. binary operation function object that will be applied. This "product" function takes one value from each range and produces a new value. @@ -56,70 +75,80 @@ op2 - Ret fun(const Type1 &a, const Type2 &b); The signature does not need to have const &. - The types Type1 and Type2 must be such that objects of types + The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. The type Ret must be such - that an object of type Type3 can be assigned a value of type Ret. + converted to Type1 and Type2 respectively. The type Ret must be + such that an object of type Type3 can be assigned a value of type + Ret. .SH Type requirements - - InputIt1, InputIt2 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. - - T must meet the requirements of CopyAssignable and CopyConstructible. + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value - The inner product of two ranges. + acc after all modifications. .SH Possible implementation -.SH First version + inner_product \fB(1)\fP template - T inner_product(InputIt1 first1, InputIt1 last1, - InputIt2 first2, T value) + constexpr // since C++20 + T inner_product(InputIt1 first1, InputIt1 last1, InputIt2 first2, T init) { - while (first1 != last1) { - value = value + *first1 * *first2; - ++first1; - ++first2; + while (first1 != last1) + { + init = std::move(init) + (*first1) * (*first2); // std::move since C++11 + ++first1; + ++first2; } - return value; + + return init; } -.SH Second version - template - T inner_product(InputIt1 first1, InputIt1 last1, - InputIt2 first2, T value, - BinaryOperation1 op1 - BinaryOperation2 op2) + inner_product \fB(2)\fP + template + constexpr // since C++20 + T inner_product(InputIt1 first1, InputIt1 last1, InputIt2 first2, T init, + BinaryOp1 op1, BinaryOp2 op2) { - while (first1 != last1) { - value = op1(value, op2(*first1, *first2)); - ++first1; - ++first2; + while (first1 != last1) + { + init = op1(std::move(init), op2(*first1, *first2)); // std::move since C++11 + ++first1; + ++first2; } - return value; + + return init; } +.SH Notes + + The parallelizable version of this algorithm, std::transform_reduce, requires op1 + and op2 to be commutative and associative, but std::inner_product makes no such + requirement, and always performs the operations in the order given. + .SH Example - + // Run this code - #include + #include #include + #include #include - #include + int main() { std::vector a{0, 1, 2, 3, 4}; std::vector b{5, 4, 2, 3, 1}; - + int r1 = std::inner_product(a.begin(), a.end(), b.begin(), 0); std::cout << "Inner product of a and b: " << r1 << '\\n'; - + int r2 = std::inner_product(a.begin(), a.end(), b.begin(), 0, - std::plus(), std::equal_to()); + std::plus<>(), std::equal_to<>()); std::cout << "Number of pairwise matches between a and b: " << r2 << '\\n'; } @@ -128,9 +157,22 @@ Inner product of a and b: 21 Number of pairwise matches between a and b: 2 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 242 C++98 op1 and op2 could not have side effects they cannot modify the + ranges involved + LWG 2055 C++11 acc was not moved while being it is moved + (P0616R0) accumulated + .SH See also - accumulate sums up a range of elements - \fI(function template)\fP - partial_sum computes the partial sum of a range of elements - \fI(function template)\fP + transform_reduce applies an invocable, then reduces out of order + \fI(C++17)\fP \fI(function template)\fP + accumulate sums up or folds a range of elements + \fI(function template)\fP + partial_sum computes the partial sum of a range of elements + \fI(function template)\fP diff --git a/man/std::inout_ptr.3 b/man/std::inout_ptr.3 new file mode 100644 index 000000000..edc9058ba --- /dev/null +++ b/man/std::inout_ptr.3 @@ -0,0 +1,63 @@ +.TH std::inout_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inout_ptr \- std::inout_ptr + +.SH Synopsis + Defined in header + template< class Pointer = void, class Smart, class... Args > (since C++23) + auto inout_ptr( Smart& s, Args&&... args ); + + Returns an inout_ptr_t with deduced template arguments that captures arguments for + resetting by reference. + + The program is ill-formed if construction of the return value (see below) is + ill-formed. + +.SH Parameters + + s - the object (typically a smart pointer) to adapt + args... - the arguments for resetting to capture + +.SH Return value + + std::inout_ptr_t(s, std::forward(args)...), where P is + + * Pointer, if Pointer is not same as void, otherwise, + * Smart::pointer, if it is valid and denotes a type, otherwise, + * Smart::element_type*, if Smart::element_type is valid and denotes a type, + otherwise, + * std::pointer_traits::element_type*. + +.SH Notes + + Users may specify the template argument for the template parameter Pointer, in order + to interoperate with foreign functions that take a Pointer*. + + As all arguments for resetting are captured by reference, the returned inout_ptr_t + should be a temporary object destroyed at the end of the full-expression containing + the call to the foreign function, in order to avoid dangling references. + + Feature-test macro Value Std Feature + __cpp_lib_out_ptr 202106L (C++23) std::out_ptr, std::inout_ptr + 202311L (C++26) freestanding std::out_ptr and std::inout_ptr + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + out_ptr creates an out_ptr_t with an associated smart pointer and + (C++23) resetting arguments + \fI(function template)\fP + make_unique + make_unique_for_overwrite creates a unique pointer that manages a new object + \fI(C++14)\fP \fI(function template)\fP + (C++20) + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::inout_ptr_t.3 b/man/std::inout_ptr_t.3 new file mode 100644 index 000000000..aed3b1616 --- /dev/null +++ b/man/std::inout_ptr_t.3 @@ -0,0 +1,124 @@ +.TH std::inout_ptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inout_ptr_t \- std::inout_ptr_t + +.SH Synopsis + Defined in header + template< class Smart, class Pointer, class... Args > (since C++23) + class inout_ptr_t; + + inout_ptr_t is used to adapt types such as smart pointers for foreign functions that + reset ownership via a Pointer* (usually T** for some object type T) or void** + parameter. + + inout_ptr_t captures additional arguments on construction, provides a storage for + the result which such an aforementioned foreign function accesses, releases the + ownership held by the adapted Smart object, and finally resets the adapted Smart + object with the result and the captured arguments when it is destroyed. + + inout_ptr_t behaves as if it holds following non-static data members: + + * a Smart& reference, which is bound to the adapted object on construction, + * for every T in Args..., a member of type T, which is an argument captured on + construction and used for resetting while destruction, and + * a member subobject that suitable for storing a Pointer within it and providing a + void* object, where the Pointer or void* object is generally exposed to a + foreign function for ownership resetting. + + If Smart is not a pointer type, release() is called at most once on the adapted + object. Implementations may call release() within constructor, or before resetting + within destructor if the Pointer value is not null. + + Users can control whether each argument for resetting is captured by copy or by + reference, by specifying an object type or a reference type in Args... respectively. + +.SH Template parameters + + Smart - the type of the object (typically a smart pointer) to adapt + Pointer - type of the object (typically a raw pointer) to which a foreign function + accesses for ownership resetting + Args... - type of captured arguments used for resetting the adapted object +.SH Type requirements + - + Pointer must meet the requirements of NullablePointer. + - + The program is ill-formed if Smart is a std::shared_ptr specialization. + +.SH Specializations + + Unlike most class templates in the standard library, program-defined specializations + of inout_ptr_t that depend on at least one program-defined type need not meet the + requirements for the primary template. + + This license allows a program-defined specialization to expose the raw pointer + stored within a non-standard smart pointer to foreign functions. + +.SH Member functions + + constructor constructs an inout_ptr_t + (C++23) \fI(public member function)\fP + operator= inout_ptr_t is not assignable + [deleted](C++23) \fI(public member function)\fP + destructor resets the adapted smart pointer after releasing its ownership + (C++23) \fI(public member function)\fP + operator Pointer* converts the inout_ptr_t to the address of the storage for output + operator void** \fI(public member function)\fP + (C++23) + +.SH Non-member functions + + inout_ptr creates an inout_ptr_t with an associated smart pointer and resetting + (C++23) arguments + \fI(function template)\fP + +.SH Notes + + inout_ptr_t expects that the foreign functions release the ownership represented by + the value of the pointed-to Pointer, and then re-initialize it. As such operation + requires unique ownership, the usage with std::shared_ptr is forbidden. + + The typical usage of inout_ptr_t is creating its temporary objects by + std::inout_ptr, which resets the adapted smart pointer immediately. E.g. given a + setter function and a smart pointer of appropriate type declared with int + foreign_resetter(T**); and std::unique_ptr up; respectively, + + if (int ec = foreign_resetter(std::inout_ptr(up))) + return ec; + + is roughly equivalent to + + T *raw_p = up.get(); + up.release(); + int ec = foreign_resetter(&raw_p); + up.reset(raw_p); + if (ec != 0) + return ec; + + It is not recommended to create an inout_ptr_t object of a storage duration other + than automatic storage duration, because such code is likely to produce dangling + references and result in undefined behavior on destruction. + + Captured arguments are typically packed into a std::tuple. Implementations + may use different mechanism to provide the Pointer or void* object they need hold. + + Feature-test macro Value Std Feature + __cpp_lib_out_ptr 202106L (C++23) std::out_ptr, std::inout_ptr + 202311L (C++26) freestanding std::out_ptr and std::inout_ptr + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + out_ptr_t interoperates with foreign pointer setters and resets a smart pointer on + (C++23) destruction + \fI(class template)\fP + unique_ptr smart pointer with unique object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + shared_ptr smart pointer with shared object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::inout_ptr_t::inout_ptr_t.3 b/man/std::inout_ptr_t::inout_ptr_t.3 new file mode 100644 index 000000000..22205218e --- /dev/null +++ b/man/std::inout_ptr_t::inout_ptr_t.3 @@ -0,0 +1,50 @@ +.TH std::inout_ptr_t::inout_ptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inout_ptr_t::inout_ptr_t \- std::inout_ptr_t::inout_ptr_t + +.SH Synopsis + explicit inout_ptr_t( Smart &sp, Args... args ); \fB(1)\fP (since C++23) + inout_ptr_t( const inout_ptr_t& ) = delete; \fB(2)\fP (since C++23) + + 1) Creates an inout_ptr_t. Adapts sp as if binds it to the Smart& member, captures + every argument t in args... as if initializes the corresponding member of type T in + Args... with std::forward(t), then initializes the stored Pointer with sp if + Smart is a pointer type, otherwise, initializes it with sp.get(). sp.release() may + be called if Smart is not a pointer type, in which case it will not be called again + within the destructor. + 2) Copy constructor is explicitly deleted. inout_ptr_t is neither copyable nor + movable. + +.SH Parameters + + sp - the object (typically a smart pointer) to adapt + args... - the arguments used for resetting to capture + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + If Smart is not a pointer type and sp.release() is not called by the constructor, it + may be called by the destructor before resetting sp. + + Every argument in args... is moved into the created inout_ptr_t if it is of an + object type, or transferred into the created inout_ptr_t as-is if it is of a + reference type. + + The constructor of inout_ptr_t is allowed to throw exceptions. For example, when sp + is an intrusive pointer with a control block, the allocation for the new control + block may be performed within the constructor rather than the destructor. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::inout_ptr_t::operatorPointer*,.3 b/man/std::inout_ptr_t::operatorPointer*,.3 new file mode 100644 index 000000000..9b2beb651 --- /dev/null +++ b/man/std::inout_ptr_t::operatorPointer*,.3 @@ -0,0 +1,61 @@ +.TH std::inout_ptr_t::operatorPointer*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inout_ptr_t::operatorPointer*, \- std::inout_ptr_t::operatorPointer*, + +.SH Synopsis + + operator Pointer*() const noexcept; \fB(1)\fP (since C++23) + operator void**() const noexcept; \fB(2)\fP (since C++23) + + Exposes the address of a Pointer or void* object to a foreign function which will + generally release the ownership represented by its value and then re-initialize it. + + 1) Converts *this to the address of stored Pointer object. + 2) Converts *this to the address of a void* object. This conversion function + participates in overload resolution only if Pointer is not same as void*, and the + program is ill-formed if Pointer is not a pointer type. + The initial value of the void* object is equal the value of the stored Pointer + object converted to void*, and any modification to it affects the Pointer value used + in the destructor. Accessing the void* object outside the lifetime of *this has + undefined behavior. + + Once one of these two conversion functions has been called on an inout_ptr_t object, + the other shall not be called on it, otherwise, the behavior is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The address of stored Pointer object. + 2) The address of the void* object that satisfies aforementioned requirements. + +.SH Notes + + If the object pointed by the return value has not been rewritten, it is equal to the + value held by adapted Smart object before construction. + + On common implementations, the object representation of every Pointer that is a + pointer type is compatible with that of void*, and therefore these implementations + typically store the void* object within the storage for the Pointer object, no + additional storage needed: + + * If the implementation enables type-based alias analysis (which relies on the + strict aliasing rule), a properly aligned std::byte[sizeof(void*)] member + subobject may be used, and both conversion functions return the address of + objects implicitly created within the array. + * Otherwise, a Pointer member subobject may be used for both conversion functions, + and \fB(2)\fP may directly returns its address reinterpret_cast to void**. + + If Pointer is a pointer type whose object representation is incompatible with that + of void*, an additional bool flag may be needed for recording whether \fB(1)\fP (or \fB(2)\fP) + has been called. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::inout_ptr_t::~inout_ptr_t.3 b/man/std::inout_ptr_t::~inout_ptr_t.3 new file mode 100644 index 000000000..c020c5bd6 --- /dev/null +++ b/man/std::inout_ptr_t::~inout_ptr_t.3 @@ -0,0 +1,63 @@ +.TH std::inout_ptr_t::~inout_ptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inout_ptr_t::~inout_ptr_t \- std::inout_ptr_t::~inout_ptr_t + +.SH Synopsis + ~inout_ptr_t(); (since C++23) + + Resets the adapted Smart object by the value of modified Pointer object (or the + void* object if operator void**() has been called) and the captured arguments. + release() may be called on the adapted Smart object if it is not called by the + constructor. + + Let + + * s denotes the adapted Smart object, + * args... denotes the captured arguments, + * p denotes the value of stored Pointer, or static_cast(*operator + void**()) if operator void** has been called, + * SP be + * Smart::pointer, if it is valid and denotes a type, otherwise, + * Smart::element_type*, if Smart::element_type is valid and denotes a type, + otherwise, + * std::pointer_traits::element_type*, if + std::pointer_traits::element_type is valid and denotes a type, + otherwise, + * Pointer, + * /*do-release*/ denotes s.release() if the constructor does not call release(), + empty otherwise. + + If Smart is a pointer type, the destructor performs + + s = static_cast(p);, and the program is ill-formed if sizeof...(Args) > 0; + + otherwise, if s.reset(static_cast(p), std::forward(args)...) is + well-formed, the destructor performs + + /*do-release*/; if (p) { s.reset(static_cast(p), std::forward(args)...); + }; + + otherwise, if std::is_constructible_v is true, the destructor + performs + + /*do-release*/; if (p) { s = Smart(static_cast(p), std::forward(args)...); + }; + + otherwise, the program is ill-formed. + +.SH Notes + + The implementation may allocate the storage for the data structure needed for Smart + (e.g. a control block) on construction, in order to leave non-throwing works to the + destructor. + + Arguments captured by value are destroyed after resetting. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3897 C++23 the destructor did not update a raw pointer to it does + the null value diff --git a/man/std::inplace_merge.3 b/man/std::inplace_merge.3 index e19608229..5bd9e0e19 100644 --- a/man/std::inplace_merge.3 +++ b/man/std::inplace_merge.3 @@ -1,86 +1,166 @@ -.TH std::inplace_merge 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::inplace_merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inplace_merge \- std::inplace_merge + .SH Synopsis Defined in header - template< class BidirIt > \fB(1)\fP - void inplace_merge( BidirIt first, BidirIt middle, BidirIt last ); - template< class BidirIt, class Compare> - void inplace_merge( BidirIt first, BidirIt middle, BidirIt last, Compare comp \fB(2)\fP - ); + template< class BidirIt > + void inplace_merge( BidirIt first, BidirIt middle, \fB(1)\fP (constexpr since C++26) + BidirIt last ); + template< class ExecutionPolicy, class BidirIt > + + void inplace_merge( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + BidirIt first, BidirIt middle, + BidirIt last ); + template< class BidirIt, class Compare > + + void inplace_merge( BidirIt first, BidirIt middle, \fB(3)\fP (constexpr since C++26) + BidirIt last, + + Compare comp ); + template< class ExecutionPolicy, class BidirIt, class + Compare > + + void inplace_merge( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + BidirIt first, BidirIt middle, + BidirIt last, + + Compare comp ); Merges two consecutive sorted ranges [first, middle) and [middle, last) into one - sorted range [first, last). The order of equal elements is guaranteed to be - preserved. The first version uses operator< to compare the elements, the second - version uses the given comparison function comp. + sorted range [first, last). + + 1) If [first, middle) or [middle, last) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first, middle) or [middle, last) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + This merge function is stable, which means that for equivalent elements in the + original two ranges, the elements from the first range (preserving their original + order) precede the elements from the second range (preserving their original order). + + If any of the following conditions is satisfied, the behavior is undefined: + + * [first, middle) or [middle, last) is not a valid range. + * The output range overlaps with [first, middle) or [middle, last). + + * The type of *first is not Swappable. \fI(until C++11)\fP + * BiditIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first - the beginning of the first sorted range - middle - the end of the first sorted range and the beginning of the second - last - the end of the second sorted range - comparison function object (i.e. an object that satisfies the requirements - of Compare) which returns true if the first argument is less (i.e. is - ordered before) the second element. + first - the beginning of the first sorted range + middle - the end of the first sorted range and the beginning of the second + last - the end of the second sorted range + policy - the execution policy to use. See execution policy for details. + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is less + than (i.e. is ordered before) the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object must - not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type BidirIt can - be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type BidirIt can + be dereferenced and then implicitly converted to both of them. .SH Type requirements - - BidirIt must meet the requirements of ValueSwappable and BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. - - The type of dereferenced BidirIt must meet the requirements of MoveAssignable and - MoveConstructible. + Compare must meet the requirements of Compare. -.SH Return value +.SH Complexity - \fI(none)\fP + Given \\(\\scriptsize N\\)N as std::distance(first, last): -.SH Complexity + 1) Exactly \\(\\scriptsize N-1\\)N-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP if enough additional memory is available, \\(\\scriptsize O(N \\cdot + \\log(N))\\)O(N⋅log(N)) comparisons otherwise. + 2) \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N⋅log(N)) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Exactly \\(\\scriptsize N-1\\)N-1 applications of the comparison function comp if + enough additional memory is available, \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N⋅log(N)) + applications otherwise. + 4) \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N⋅log(N)) applications of the comparison + function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: - Exactly N-1 comparisons if enough additional memory is available, otherwise N·log(N) - where N = std::distance(first, last). + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + See the implementations in libstdc++ and libc++. .SH Notes - This function attempts to allocate a temporary buffer, typically by calling - std::get_temporary_buffer. If the allocation fails, the less efficient algorithm is - chosen. + This function attempts to allocate a temporary buffer. If the allocation fails, the + less efficient algorithm is chosen. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_algorithms 202306L (C++26) constexpr inplace merging .SH Example The following code is an implementation of merge sort. - + // Run this code - #include - #include #include - + #include + #include + template void merge_sort(Iter first, Iter last) { - if (last - first > 1) { + if (last - first > 1) + { Iter middle = first + (last - first) / 2; merge_sort(first, middle); merge_sort(middle, last); std::inplace_merge(first, middle, last); } } - + int main() { std::vector v{8, 2, -2, 0, 11, 11, 1, 7, 3}; merge_sort(v.begin(), v.end()); - for(auto n : v) { + for (const auto& n : v) std::cout << n << ' '; - } std::cout << '\\n'; } @@ -90,9 +170,12 @@ .SH See also - merge merges two sorted ranges - \fI(function template)\fP - sort sorts a range into ascending order - \fI(function template)\fP - stable_sort sorts a range of elements while preserving order between equal elements - \fI(function template)\fP + merge merges two sorted ranges + \fI(function template)\fP + sort sorts a range into ascending order + \fI(function template)\fP + sorts a range of elements while preserving order between equal + stable_sort elements + \fI(function template)\fP + ranges::inplace_merge merges two ordered ranges in-place + (C++20) (niebloid) diff --git a/man/std::input_iterator.3 b/man/std::input_iterator.3 new file mode 100644 index 000000000..c307dc94f --- /dev/null +++ b/man/std::input_iterator.3 @@ -0,0 +1,54 @@ +.TH std::input_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::input_iterator \- std::input_iterator + +.SH Synopsis + Defined in header + template< class I > + + concept input_iterator = + std::input_or_output_iterator && + std::indirectly_readable && \fI(since C++20)\fP + requires { typename /*ITER_CONCEPT*/; } && + + std::derived_from, + std::input_iterator_tag>; + + The input_iterator concept is a refinement of input_or_output_iterator, adding the + requirement that the referenced values can be read (via indirectly_readable) and the + requirement that the iterator concept tag be present. + +.SH Notes + + Unlike the LegacyInputIterator requirements, the input_iterator concept does not + require equality_comparable, since input iterators are typically compared with + sentinels. + +.SH Example + + A minimum input iterator. + + #include + #include + + struct SimpleInputIterator + { + using difference_type = std::ptrdiff_t; + using value_type = int; + + int operator*() const; + + SimpleInputIterator& operator++(); + void operator++(int) { ++*this; } + }; + + static_assert(std::input_iterator); + +.SH See also + + input_or_output_iterator specifies that objects of a type can be incremented and + (C++20) dereferenced + (concept) + forward_iterator specifies that an input_iterator is a forward iterator, + (C++20) supporting equality comparison and multi-pass + (concept) diff --git a/man/std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag,.3 b/man/std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag,.3 index bd38c7012..214e92b58 100644 --- a/man/std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag,.3 +++ b/man/std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag,.3 @@ -1,81 +1,119 @@ -.TH std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag, \- std::input_iterator_tag,std::output_iterator_tag,std::forward_iterator_tag, + .SH Synopsis + std::contiguous_iterator_tag Defined in header - struct input_iterator_tag { }; - struct output_iterator_tag { }; - struct forward_iterator_tag : public input_iterator_tag { }; - struct bidirectional_iterator_tag : public forward_iterator_tag { }; - struct random_access_iterator_tag : public bidirectional_iterator_tag { }; + struct input_iterator_tag {}; \fB(1)\fP + struct output_iterator_tag {}; \fB(2)\fP + struct forward_iterator_tag : public input_iterator_tag {}; \fB(3)\fP + struct bidirectional_iterator_tag : public forward_iterator_tag \fB(4)\fP + {}; + struct random_access_iterator_tag : public \fB(5)\fP + bidirectional_iterator_tag {}; + struct contiguous_iterator_tag : public random_access_iterator_tag \fB(6)\fP \fI(since C++20)\fP + {}; - Defines the category of an iterator. Each tag is an empty type and corresponds to - one of the five iterator categories: + Defines the category of an iterator. Each tag is an empty type. - * input_iterator_tag corresponds to InputIterator. - * output_iterator_tag corresponds to OutputIterator. - * forward_iterator_tag corresponds to ForwardIterator. - * bidirectional_iterator_tag corresponds to BidirectionalIterator. - * random_access_iterator_tag corresponds to RandomAccessIterator. +.SH Notes - Iterator category tags carry information that can be used to select the most - efficient algorithms for the specific requirement set that is implied by the - category. + There is no separate tag for LegacyContiguousIterator. That is, it is not possible + to tell a LegacyContiguousIterator based on its iterator_category. + To define specialized algorithm for contiguous iterators, use the + contiguous_iterator concept. + \fI(since C++20)\fP - For every iterator type, a typedef std::iterator_traits::iterator_category - is available, which is an alias to one of these five tag types. + There are no correspondences between output_iterator_tag and the output_iterator + concept. Setting iterator_concept to output_iterator_tag only indicates that the + type does not model input_iterator. .SH Example Common technique for algorithm selection based on iterator category tags is to use a - dispatcher function (the alternative is std::enable_if) + dispatcher function (the alternative is std::enable_if). + The iterator tag classes are also used in the corresponding concepts definitions to + denote the requirements, which can't be expressed in terms of usage patterns alone. + \fI(since C++20)\fP + - // Run this code #include - #include - #include #include - - template< class BDIter > - void alg(BDIter, BDIter, std::bidirectional_iterator_tag) + #include + #include + + // Using concepts (tag checking is part of the concepts themselves) + + template + void alg(BDIter, BDIter) { - std::cout << "alg() called for bidirectional iterator\\n"; + std::cout << "1. alg() \\t called for bidirectional iterator\\n"; } - - template - void alg(RAIter, RAIter, std::random_access_iterator_tag) + + template + void alg(RAIter, RAIter) { - std::cout << "alg() called for random-access iterator\\n"; + std::cout << "2. alg() \\t called for random-access iterator\\n"; } - - template< class Iter > - void alg(Iter first, Iter last) + + // Legacy, using tag dispatch + + namespace legacy { - alg(first, last, - typename std::iterator_traits::iterator_category()); - } - + // Quite often implementation details are hidden in a dedicated namespace + namespace implementation_details + { + template + void alg(BDIter, BDIter, std::bidirectional_iterator_tag) + { + std::cout << "3. legacy::alg() called for bidirectional iterator\\n"; + } + + template + void alg(RAIter, RAIter, std::random_access_iterator_tag) + { + std::cout << "4. legacy::alg() called for random-access iterator\\n"; + } + } // namespace implementation_details + + template + void alg(Iter first, Iter last) + { + implementation_details::alg(first, last, + typename std::iterator_traits::iterator_category()); + } + } // namespace legacy + int main() { - std::vector v; - alg(v.begin(), v.end()); - std::list l; - alg(l.begin(), l.end()); - - // std::istreambuf_iterator i1(std::cin), i2; - // alg(i1, i2); // compile error: no matching function for call + alg(l.begin(), l.end()); // 1. + legacy::alg(l.begin(), l.end()); // 3. + + std::vector v; + alg(v.begin(), v.end()); // 2. + legacy::alg(v.begin(), v.end()); // 4. + + // std::istreambuf_iterator i1(std::cin), i2; + // alg(i1, i2); // compile error: no matching function for call + // legacy::alg(i1, i2); // compile error: no matching function for call } .SH Output: - alg() called for random-access iterator - alg() called for bidirectional iterator + 1. alg() called for bidirectional iterator + 3. legacy::alg() called for bidirectional iterator + 2. alg() called for random-access iterator + 4. legacy::alg() called for random-access iterator .SH See also - iterator the basic iterator - \fI(class template)\fP - iterator_traits provides uniform interface to the properties of an iterator - \fI(class template)\fP + iterator base class to ease the definition of required types for simple + (deprecated in C++17) iterators + \fI(class template)\fP + iterator_traits provides uniform interface to the properties of an iterator + \fI(class template)\fP diff --git a/man/std::input_or_output_iterator.3 b/man/std::input_or_output_iterator.3 new file mode 100644 index 000000000..68c54d677 --- /dev/null +++ b/man/std::input_or_output_iterator.3 @@ -0,0 +1,60 @@ +.TH std::input_or_output_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::input_or_output_iterator \- std::input_or_output_iterator + +.SH Synopsis + Defined in header + template< class I > + + concept input_or_output_iterator = + requires(I i) { \fI(since C++20)\fP + { *i } -> /*can-reference*/; + } && + + std::weakly_incrementable; + + The input_or_output_iterator concept forms the basis of the iterator concept + taxonomy; every iterator type satisfies the input_or_output_iterator requirements. + + The exposition-only concept /*can-reference*/ is satisfied if and only if the type + is referenceable (in particular, not void). + + This section is incomplete + Reason: Is *i required to be equality-preserving? + +.SH Notes + + input_or_output_iterator itself only specifies operations for dereferencing and + incrementing an iterator. Most algorithms will require additional operations, for + example: + + * comparing iterators with sentinels (see sentinel_for); + * reading values from an iterator (see indirectly_readable and input_iterator); + * writing values to an iterator (see indirectly_writable and output_iterator); + * a richer set of iterator movements (see forward_iterator, + bidirectional_iterator, random_access_iterator). + + Unlike the LegacyIterator requirements, the input_or_output_iterator concept does + not require copyability. + +.SH Example + + A minimum iterator. + + #include + #include + + struct SimpleIterator + { + using difference_type = std::ptrdiff_t; + + int operator*(); + + SimpleIterator& operator++(); + void operator++(int) { ++*this; } + }; + + static_assert(std::input_or_output_iterator); + +.SH Category: + * Todo with reason diff --git a/man/std::insert_iterator.3 b/man/std::insert_iterator.3 index da5eabfe9..16a0238a7 100644 --- a/man/std::insert_iterator.3 +++ b/man/std::insert_iterator.3 @@ -1,66 +1,75 @@ -.TH std::insert_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::insert_iterator \- std::insert_iterator + .SH Synopsis Defined in header template< class Container > - class insert_iterator : public std::iterator< std::output_iterator_tag, + class insert_iterator : public \fI(until C++17)\fP + std::iterator + void, void, void, void> + template< class Container > \fI(since C++17)\fP + class insert_iterator; - std::insert_iterator is an output iterator that inserts elements into a container - for which it was constructed, at the position pointed to by the supplied iterator. - The container's insert() member function is called whenever the iterator (whether - dereferenced or not) is assigned to. Incrementing the std::insert_iterator is a - no-op. + std::insert_iterator is a LegacyOutputIterator that inserts elements into a + container for which it was constructed, at the position pointed to by the supplied + iterator. The container's insert() member function is called whenever the iterator + (whether dereferenced or not) is assigned to. Incrementing the std::insert_iterator + is a no-op. .SH Member types - Member type Definition - container_type Container + Member type Definition + iterator_category std::output_iterator_tag + value_type void + difference_type void \fI(until C++20)\fP + std::ptrdiff_t \fI(since C++20)\fP + pointer void + reference void + container_type Container + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. .SH Member functions constructor constructs a new insert_iterator - \fI(public member function)\fP + \fI(public member function)\fP operator= inserts an object into the associated container - \fI(public member function)\fP + \fI(public member function)\fP operator* no-op - \fI(public member function)\fP + \fI(public member function)\fP operator++ no-op - operator++(int) \fI(public member function)\fP + operator++(int) \fI(public member function)\fP .SH Member objects - Member name Definition - container (protected) a pointer of type Container* - iter (protected) an iterator of type Container::iterator - -Inherited from std::iterator - -.SH Member types - - Member type Definition - value_type void - difference_type void - pointer void - reference void - iterator_category std::output_iterator_tag + Member name Definition + container \fI(protected member object) a pointer o\fPf type Container* + an iterator of type + Container::iterator + iter \fI(protected member object) \\fPfI(until C++20)\fP + ranges::iterator_t + \fI(since C++20)\fP .SH Example - + // Run this code - #include - #include + #include #include #include - #include - + #include + #include + int main() { - std::vector v{1,2,3,4,5}; - std::list l{-1,-2,-3}; + std::vector v{1, 2, 3, 4, 5}; + std::list l{-1, -2, -3}; std::copy(v.begin(), v.end(), // may be simplified with std::inserter std::insert_iterator>(l, std::next(l.begin()))); for (int n : l) @@ -76,8 +85,8 @@ Inherited from std::iterator creates a std::insert_iterator of type inferred from the inserter argument - \fI(function template)\fP + \fI(function template)\fP back_insert_iterator iterator adaptor for insertion at the end of a container - \fI(class template)\fP + \fI(class template)\fP front_insert_iterator iterator adaptor for insertion at the front of a container - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::insert_iterator::insert_iterator.3 b/man/std::insert_iterator::insert_iterator.3 index e829da360..b4a2e1d52 100644 --- a/man/std::insert_iterator::insert_iterator.3 +++ b/man/std::insert_iterator::insert_iterator.3 @@ -1,11 +1,27 @@ -.TH std::insert_iterator::insert_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::insert_iterator::insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::insert_iterator::insert_iterator \- std::insert_iterator::insert_iterator + .SH Synopsis - explicit insert_iterator( Container& c, typename Container::iterator i ); + insert_iterator( Container& c, typename Container::iterator i ); \fI(until C++20)\fP + constexpr insert_iterator( Container& c, \fI(since C++20)\fP + ranges::iterator_t i ); - Initializes the underlying pointer to the container to &c and the interlying - iterator to iter. + Initializes the underlying pointer to the container to std::addressof(c) and the + underlying iterator to i. .SH Parameters - c - container to initialize the inserter with - iter - iterator to initialize the inserter with + c - container to initialize the inserter with + i - iterator to initialize the inserter with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 561 C++98 the type of i was independent of it is the iterator type + Container of Container + P2325R3 C++20 default constructor was provided as C++20 removed along with the + iterators must be default_initializable requirement diff --git a/man/std::insert_iterator::operator*.3 b/man/std::insert_iterator::operator*.3 index 2e1ee2345..44a9a9184 100644 --- a/man/std::insert_iterator::operator*.3 +++ b/man/std::insert_iterator::operator*.3 @@ -1,9 +1,13 @@ -.TH std::insert_iterator::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::insert_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::insert_iterator::operator* \- std::insert_iterator::operator* + .SH Synopsis - insert_iterator& operator*(); + insert_iterator& operator*(); \fI(until C++20)\fP + constexpr insert_iterator& operator*(); \fI(since C++20)\fP Does nothing, this member function is provided to satisfy the requirements of - OutputIterator. + LegacyOutputIterator. It returns the iterator itself, which makes it possible to use code such as *iter = value to output (insert) the value into the underlying container. diff --git a/man/std::insert_iterator::operator++.3 b/man/std::insert_iterator::operator++.3 index caedf09f8..9dac1e3ee 100644 --- a/man/std::insert_iterator::operator++.3 +++ b/man/std::insert_iterator::operator++.3 @@ -1,10 +1,15 @@ -.TH std::insert_iterator::operator++ 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::insert_iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::insert_iterator::operator++ \- std::insert_iterator::operator++ + .SH Synopsis - insert_iterator& operator++(); - insert_iterator& operator++( int ); + insert_iterator& operator++(); \fI(until C++20)\fP + constexpr insert_iterator& operator++(); \fI(since C++20)\fP + insert_iterator& operator++( int ); \fI(until C++20)\fP + constexpr insert_iterator& operator++( int ); \fI(since C++20)\fP Does nothing. These operator overloads are provided to satisfy the requirements of - OutputIterator. They make it possible for the expressions *iter++=value and + LegacyOutputIterator. They make it possible for the expressions *iter++=value and *++iter=value to be used to output (insert) a value into the underlying container. .SH Parameters diff --git a/man/std::insert_iterator::operator=.3 b/man/std::insert_iterator::operator=.3 index 51ef0efef..5359a5deb 100644 --- a/man/std::insert_iterator::operator=.3 +++ b/man/std::insert_iterator::operator=.3 @@ -1,14 +1,28 @@ -.TH std::insert_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::insert_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::insert_iterator::operator= \- std::insert_iterator::operator= + .SH Synopsis - insert_iterator& \fB(1)\fP - operator=( const typename Container::value_type& value ); - insert_iterator& \fB(2)\fP - operator=( typename Container::value_type&& value ); + insert_iterator& + operator=( typename \fI(until C++11)\fP + Container::const_reference value ); + insert_iterator& \fI(since C++11)\fP + operator=( const typename \fI(until C++20)\fP + Container::value_type& value ); + constexpr insert_iterator& + operator=( const typename \fB(1)\fP \fI(since C++20)\fP + Container::value_type& value ); + insert_iterator& \fI(since C++11)\fP + operator=( typename Container::value_type&& \fI(until C++20)\fP + value ); \fB(2)\fP + constexpr insert_iterator& + operator=( typename Container::value_type&& \fI(since C++20)\fP + value ); Inserts the given value value to the container. - 1) Results in iter = container->insert(iter, value); ++iter; - 2) Results in iter = container->insert(iter, std::move(value)); ++iter; + 1) Results in iter = container->insert(iter, value); ++iter;. + 2) Results in iter = container->insert(iter, std::move(value)); ++iter;. .SH Parameters @@ -18,10 +32,34 @@ *this +.SH Notes + + This function exploits the signature compatibility between hinted insert for + associative containers (such as std::set::insert) and positional insert for + sequential containers (such as std::vector::insert). + .SH Example - This section is incomplete -.SH Category: +// Run this code + + #include + #include + #include + + int main() + { + std::deque q; + std::insert_iterator> it(q, q.begin()); + + for (int i = 0; i < 10; ++i) + it = i; // inserts i + + for (auto& elem : q) + std::cout << elem << ' '; + std::cout << '\\n'; + } + +.SH Output: - * Todo without reason + 0 1 2 3 4 5 6 7 8 9 diff --git a/man/std::inserter.3 b/man/std::inserter.3 index 445daa9bc..60d3257e6 100644 --- a/man/std::inserter.3 +++ b/man/std::inserter.3 @@ -1,9 +1,19 @@ -.TH std::inserter 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::inserter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::inserter \- std::inserter + .SH Synopsis Defined in header template< class Container > - std::insert_iterator inserter( Container& c, typename - Container::iterator i ); + + std::insert_iterator \fI(until C++20)\fP + + inserter( Container& c, typename Container::iterator i ); + template< class Container > + + constexpr std::insert_iterator \fI(since C++20)\fP + + inserter( Container& c, ranges::iterator_t i ); inserter is a convenience function template that constructs a std::insert_iterator for the container c and its iterator i with the type deduced from the type of the @@ -11,7 +21,7 @@ .SH Parameters - c - container that supports a insert operation + c - container that supports an insert operation i - iterator in c indicating the insertion position .SH Return value @@ -21,54 +31,67 @@ .SH Possible implementation - template< class Container > - std::insert_iterator inserter( Container& c, typename Container::iterator i ) - { - return std::insert_iterator(c, i); - } + template + std::insert_iterator inserter(Container& c, typename Container::iterator i) + { + return std::insert_iterator(c, i); + } .SH Example - + // Run this code - #include - #include #include + #include #include #include - + #include + int main() { - std::list l{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; - std::multiset s; - - std::fill_n(std::inserter(l, std::next(l.begin())), 3, -1); - std::fill_n(std::inserter(s, s.begin()), 3, -1); - - for (int n : l) { + std::multiset s{1, 2, 3}; + + // std::inserter is commonly used with multi-sets + std::fill_n(std::inserter(s, s.end()), 5, 2); + + for (int n : s) std::cout << n << ' '; - } std::cout << '\\n'; - - for (int n : s) { + + std::vector d{100, 200, 300}; + std::vector v{1, 2, 3, 4, 5}; + + // when inserting in a sequence container, insertion point advances + // because each std::insert_iterator::operator= updates the target iterator + std::copy(d.begin(), d.end(), std::inserter(v, std::next(v.begin()))); + + for (int n : v) std::cout << n << ' '; - } std::cout << '\\n'; } .SH Output: - 1 -1 -1 -1 2 3 4 5 6 7 8 9 10 - -1 -1 -1 + 1 2 2 2 2 2 2 3 + 1 100 200 300 2 3 4 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 561 C++98 the type of i was independent of it is the iterator type of + Container Container .SH See also insert_iterator iterator adaptor for insertion into a container - \fI(class template)\fP + \fI(class template)\fP creates a std::back_insert_iterator of type inferred from the back_inserter argument - \fI(function template)\fP + \fI(function template)\fP creates a std::front_insert_iterator of type inferred from the front_inserter argument - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::integer_sequence.3 b/man/std::integer_sequence.3 index d8da5c41b..4a962d7bd 100644 --- a/man/std::integer_sequence.3 +++ b/man/std::integer_sequence.3 @@ -1,4 +1,7 @@ -.TH std::integer_sequence 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::integer_sequence 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::integer_sequence \- std::integer_sequence + .SH Synopsis Defined in header template< class T, T... Ints > \fI(since C++14)\fP @@ -23,11 +26,11 @@ size returns the number of elements in Ints \fB[static]\fP \fI(public static member function)\fP - std::integer_sequence::size +std::integer_sequence::size - static constexpr std::size_t size(); + static constexpr std::size_t size() noexcept; - Returns the number of elements in Ints. Equivalent to sizeof...(Ints) + Returns the number of elements in Ints. Equivalent to sizeof...(Ints). .SH Parameters @@ -37,97 +40,122 @@ The number of elements in Ints. -.SH Exceptions - - noexcept specification: - noexcept - - Helper templates A helper alias template std::index_sequence is defined for the common case where T - is std::size_t. + is std::size_t: - template + template< std::size_t... Ints > using index_sequence = std::integer_sequence; - A helper alias template std::make_integer_sequence is defined to simplify creation - of std::integer_sequence and std::index_sequence types with 0, 1, 2, ..., N-1 as - Ints: + Helper alias templates std::make_integer_sequence and std::make_index_sequence are + defined to simplify creation of std::integer_sequence and std::index_sequence types, + respectively, with 0, 1, 2, ..., N - 1 as Ints: - template + template< class T, T N > using make_integer_sequence = std::integer_sequence; - template - using make_index_sequence = make_integer_sequence; + N-1 */>; + template< std::size_t N > + using make_index_sequence = std::make_integer_sequence; - The behavior is undefined if N is negative. If N is zero, the indicated type is + The program is ill-formed if N is negative. If N is zero, the indicated type is integer_sequence. A helper alias template std::index_sequence_for is defined to convert any type - parameter pack into an index sequence of the same length + parameter pack into an index sequence of the same length: - template + template< class... T > using index_sequence_for = std::make_index_sequence; +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_integer_sequence 201304L \fI(C++14)\fP Compile-time integer sequences + .SH Example - + Note: see Possible Implementation in std::apply for another example. + + // Run this code - #include - #include #include + #include + #include + #include #include - - // Convert array into to tuple + + // debugging aid + template + void print_sequence(std::integer_sequence int_seq) + { + std::cout << "The sequence of size " << int_seq.size() << ": "; + ((std::cout << ints << ' '), ...); + std::cout << '\\n'; + } + + // convert array into a tuple template auto a2t_impl(const Array& a, std::index_sequence) - -> decltype(std::make_tuple(a[I]...)) { return std::make_tuple(a[I]...); } - + template> auto a2t(const std::array& a) - -> decltype(a2t_impl(a, Indices())) { - return a2t_impl(a, Indices()); + return a2t_impl(a, Indices{}); } - - // pretty-print a tuple (from http://stackoverflow.com/a/6245777/273767 ) - + + // pretty-print a tuple template - void print_tuple_impl(std::basic_ostream& os, - const Tuple & t, + void print_tuple_impl(std::basic_ostream& os, + const Tuple& t, std::index_sequence) { - using swallow = int[]; - (void)swallow{0, (void(os << (Is == 0? "" : ", ") << std::get(t)), 0)...}; + ((os << (Is == 0? "" : ", ") << std::get(t)), ...); } - + template - auto operator<<(std::basic_ostream& os, const std::tuple& t) - -> std::basic_ostream& + auto& operator<<(std::basic_ostream& os, + const std::tuple& t) { os << "("; print_tuple_impl(os, t, std::index_sequence_for{}); return os << ")"; } - + int main() { - std::array array = {1,2,3,4}; - + print_sequence(std::integer_sequence{}); + print_sequence(std::make_integer_sequence{}); + print_sequence(std::make_index_sequence<10>{}); + print_sequence(std::index_sequence_for{}); + + std::array array = {1, 2, 3, 4}; + // convert an array into a tuple auto tuple = a2t(array); - static_assert(std::is_same>::value, ""); - + static_assert(std::is_same_v>, ""); + // print it to cout - std::cout << tuple << '\\n'; + std::cout << "The tuple: " << tuple << '\\n'; } .SH Output: - (1, 2, 3, 4) + The sequence of size 7: 9 2 5 1 9 1 6 + The sequence of size 20: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 + The sequence of size 10: 0 1 2 3 4 5 6 7 8 9 + The sequence of size 3: 0 1 2 + The tuple: (1, 2, 3, 4) + +.SH See also + + to_array creates a std::array object from a built-in array + (C++20) \fI(function template)\fP + integral_constant + bool_constant compile-time constant of specified type with specified value + \fI(C++11)\fP \fI(class template)\fP + \fI(C++17)\fP diff --git a/man/std::integral.3 b/man/std::integral.3 new file mode 100644 index 000000000..10904af62 --- /dev/null +++ b/man/std::integral.3 @@ -0,0 +1,61 @@ +.TH std::integral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::integral \- std::integral + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + concept integral = std::is_integral_v; + + The concept integral is satisfied if and only if T is an integral type. + +.SH Example + + +// Run this code + + #include + #include + + void print(std::integral auto i) + { + std::cout << "Integral: " << i << '\\n'; + } + + void print(auto x) + { + std::cout << "Non-integral: " << x << '\\n'; + } + + int main() + { + std::cout << std::boolalpha; + + static_assert(std::integral); + print(true); + + static_assert(std::integral); + print('o'); + + static_assert(std::integral); + print(007); + + static_assert( ! std::integral ); + print(2e2); + + static_assert( ! std::integral ); + print("∫∫∫"); + } + +.SH Output: + + Integral: true + Integral: o + Integral: 7 + Non-integral: 200 + Non-integral: ∫∫∫ + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::integral_constant.3 b/man/std::integral_constant.3 index ee0c52831..cd2b399d9 100644 --- a/man/std::integral_constant.3 +++ b/man/std::integral_constant.3 @@ -1,4 +1,7 @@ -.TH std::integral_constant 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::integral_constant 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::integral_constant \- std::integral_constant + .SH Synopsis Defined in header template< class T, T v > \fI(since C++11)\fP @@ -7,74 +10,92 @@ std::integral_constant wraps a static constant of specified type. It is the base class for the C++ type traits. - Two specializations for the type bool are provided: + If the program adds specializations for std::integral_constant, the behavior is + undefined. + +.SH Specializations + + Two typedefs for the common case where T is bool are provided: Defined in header - Type Definition + Name Definition true_type std::integral_constant false_type std::integral_constant -.SH Member types + Nested types - Type Definition + Name Definition value_type T - type std::integral_constant + type std::integral_constant .SH Member constants - Name Value - value static constant expression of type T with value v + Name Value + constexpr T value v + \fB[static]\fP \fI(public static member constant)\fP .SH Member functions - (constexpr)operator value_type converts the object to value_type, returns value - (const noexcept) \fI(public member function)\fP - (constexpr)operator() returns value \fI(C++14)\fP - (const noexcept) \fI(public member function)\fP + operator value_type returns the wrapped value + \fI(public member function)\fP + operator() returns the wrapped value + \fI(C++14)\fP \fI(public member function)\fP + +std::integral_constant::operator value_type + + constexpr operator value_type() const noexcept; + + Conversion function. Returns the wrapped value. + +std::integral_constant::operator() + + constexpr value_type operator()() const noexcept; \fI(since C++14)\fP + + Returns the wrapped value. This function enables std::integral_constant to serve as + a source of compile-time function objects. .SH Possible implementation template - struct integral_constant { + struct integral_constant + { static constexpr T value = v; - typedef T value_type; - typedef integral_constant type; + using value_type = T; + using type = integral_constant; // using injected-class-name constexpr operator value_type() const noexcept { return value; } - constexpr value_type operator()() const noexcept { return value; } + constexpr value_type operator()() const noexcept { return value; } // since c++14 }; +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_integral_constant_callable 201304L \fI(C++14)\fP std::integral_constant::operator() + __cpp_lib_bool_constant 201505L \fI(C++17)\fP std::bool_constant + .SH Example - + // Run this code - #include #include - - int main() - { - typedef std::integral_constant two_t; - typedef std::integral_constant four_t; - - // static_assert(std::is_same::value, - // "two_t and four_t are not equal!"); - // error: static assertion failed: "two_t and four_t are not a same types" - - static_assert(two_t::value*2 == four_t::value, - "2*2 != 4" - ); - - enum class my_e { - e1, - e2 - }; - typedef std::integral_constant my_e_e1; - typedef std::integral_constant my_e_e2; - - // static_assert(my_e_e1::value == my_e::e2, - // "my_e_e1::value != my_e::e2"); - // error: static assertion failed: "my_e_e1::value != my_e::e2" - - static_assert(std::is_same::value, - "my_e_e2 != my_e_e2"); - } + + using two_t = std::integral_constant; + using four_t = std::integral_constant; + + static_assert(not std::is_same_v); + static_assert(two_t::value * 2 == four_t::value, "2*2 != 4"); + static_assert(two_t() << 1 == four_t() >> 0, "2*2 != 4"); + + enum class E{ e1, e2 }; + using c1 = std::integral_constant; + using c2 = std::integral_constant; + static_assert(c1::value != E::e2); + static_assert(c1() == E::e1); + static_assert(std::is_same_v); + + int main() {} + +.SH See also + + integer_sequence implements compile-time sequence of integers + \fI(C++14)\fP \fI(class template)\fP diff --git a/man/std::invalid_argument.3 b/man/std::invalid_argument.3 index 51232e3df..287c78d57 100644 --- a/man/std::invalid_argument.3 +++ b/man/std::invalid_argument.3 @@ -1,4 +1,7 @@ -.TH std::invalid_argument 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::invalid_argument 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::invalid_argument \- std::invalid_argument + .SH Synopsis Defined in header class invalid_argument; @@ -6,39 +9,155 @@ Defines a type of object to be thrown as exception. It reports errors that arise because an argument value has not been accepted. + This exception is thrown by std::bitset::bitset, and the std::stoi and std::stof + families of functions. + std-invalid argument-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP - - + constructor constructs a new invalid_argument object with the given message + \fI(public member function)\fP + operator= replaces the invalid_argument object + \fI(public member function)\fP - std::invalid_argument::invalid_argument +std::invalid_argument::invalid_argument - explicit invalid_argument( const std::string& what_arg ); \fB(1)\fP - explicit invalid_argument( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP + invalid_argument( const std::string& what_arg ); \fB(1)\fP + invalid_argument( const char* what_arg ); \fB(2)\fP + invalid_argument( const invalid_argument& other ); \fB(3)\fP (noexcept since C++11) - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::invalid_argument + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::invalid_argument is not permitted to throw exceptions, this + message is typically stored internally as a separately-allocated reference-counted + string. This is also why there is no constructor taking std::string&&: it would have + to copy the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::invalid_argument::operator= + + invalid_argument& operator=( const invalid_argument& other (noexcept since C++11) + ); + + Assigns the contents with those of other. If *this and other both have dynamic type + std::invalid_argument then std::strcmp(what(), other.what()) == 0 after assignment. + No exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::logic_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Notes + + The purpose of this exception type is similar to the error condition + std::errc::invalid_argument (thrown in std::system_error from member functions of + std::thread) and the related errno constant EINVAL. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + try + { + std::bitset<4>{"012"}; // Throws: only '0' or '1' expected + } + catch (std::invalid_argument const& ex) + { + std::cout << "#1: " << ex.what() << '\\n'; + } + + try + { + [[maybe_unused]] int f = std::stoi("ABBA"); // Throws: no conversion + } + catch (std::invalid_argument const& ex) + { + std::cout << "#2: " << ex.what() << '\\n'; + } + + try + { + [[maybe_unused]] float f = std::stof("(3.14)"); // Throws: no conversion + } + catch (std::invalid_argument const& ex) + { + std::cout << "#3: " << ex.what() << '\\n'; + } + } + +.SH Possible output: + + #1: bitset string ctor has invalid argument + #2: stoi: no conversion + #3: stof: no conversion + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const added + char* was missing + the explanatory strings of they are the same as that of + LWG 471 C++98 std::invalid_argument's the + copies were implementation-defined original std::invalid_argument + object diff --git a/man/std::invocable,std::regular_invocable.3 b/man/std::invocable,std::regular_invocable.3 new file mode 100644 index 000000000..f07d06fd8 --- /dev/null +++ b/man/std::invocable,std::regular_invocable.3 @@ -0,0 +1,43 @@ +.TH std::invocable,std::regular_invocable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::invocable,std::regular_invocable \- std::invocable,std::regular_invocable + +.SH Synopsis + Defined in header + template< class F, class... Args > + + concept invocable = + requires(F&& f, Args&&... args) { \fI(since C++20)\fP + std::invoke(std::forward(f), std::forward(args)...); + /* not required to be equality-preserving */ + + }; + template< class F, class... Args > \fI(since C++20)\fP + concept regular_invocable = std::invocable; + + The invocable concept specifies that a callable type F can be called with a set of + arguments Args... using the function template std::invoke. + + The regular_invocable concept adds to the invocable concept by requiring the invoke + expression to be equality-preserving and not modify either the function object or + the arguments. + +.SH Notes + + The distinction between invocable and regular_invocable is purely semantic. + + A random number generator may satisfy invocable but cannot satisfy regular_invocable + (comical ones excluded). + +.SH See also + + is_invocable + is_invocable_r checks if a type can be invoked (as if by std::invoke) with + is_nothrow_invocable the given argument types + is_nothrow_invocable_r \fI(class template)\fP + \fI(C++17)\fP + +.SH External links + + 1. A joke example of a random number generator that satisfies both invocable and + regular_invocable. diff --git a/man/std::invoke,std::invoke_r.3 b/man/std::invoke,std::invoke_r.3 new file mode 100644 index 000000000..2615d7e57 --- /dev/null +++ b/man/std::invoke,std::invoke_r.3 @@ -0,0 +1,206 @@ +.TH std::invoke,std::invoke_r 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::invoke,std::invoke_r \- std::invoke,std::invoke_r + +.SH Synopsis + Defined in header + template< class F, class... Args > + + std::invoke_result_t \fB(1)\fP \fI(since C++17)\fP + (constexpr since C++20) + invoke( F&& f, Args&&... args ) noexcept(/* see + below */); + template< class R, class F, class... Args > + + constexpr R \fB(2)\fP (since C++23) + + invoke_r( F&& f, Args&&... args ) noexcept(/* see + below */); + + 1) Invoke the Callable object f with the parameters args as by + INVOKE(std::forward(f), std::forward(args)...). This overload participates + in overload resolution only if std::is_invocable_v is true. + 2) Invoke the Callable object f with the parameters args as by + INVOKE(std::forward(f), std::forward(args)...). This overload + participates in overload resolution only if std::is_invocable_r_v is + true. + +.SH Parameters + + f - Callable object to be invoked + args - arguments to pass to f + +.SH Return value + + 1) The value returned by f. + 2) The value returned by f, implicitly converted to R, if R is not (possibly + cv-qualified) void. None otherwise. + +.SH Exceptions + + 1) + noexcept specification: + noexcept(std::is_nothrow_invocable_v) + 2) + noexcept specification: + noexcept(std::is_nothrow_invocable_r_v) + +.SH Possible implementation + + invoke \fB(1)\fP + namespace detail + { + template + constexpr bool is_reference_wrapper_v = false; + template + constexpr bool is_reference_wrapper_v> = true; + + template + using remove_cvref_t = std::remove_cv_t>; + + template + constexpr decltype(auto) invoke_memptr(Pointed C::* member, Object&& object, + Args&&... args) + { + using object_t = remove_cvref_t; + constexpr bool is_member_function = std::is_function_v; + constexpr bool is_wrapped = is_reference_wrapper_v; + constexpr bool is_derived_object = std::is_same_v + || std::is_base_of_v; + + if constexpr (is_member_function) + { + if constexpr (is_derived_object) + return (std::forward(object) .* member) + (std::forward(args)...); + else if constexpr (is_wrapped) + return (object.get() .* member)(std::forward(args)...); + else + return ((*std::forward(object)) .* member) + (std::forward(args)...); + } + else + { + static_assert(std::is_object_v && sizeof...(args) == 0); + if constexpr (is_derived_object) + return std::forward(object) .* member; + else if constexpr (is_wrapped) + return object.get() .* member; + else + return (*std::forward(object)) .* member; + } + } + } // namespace detail + + template + constexpr std::invoke_result_t invoke(F&& f, Args&&... args) + noexcept(std::is_nothrow_invocable_v) + { + if constexpr (std::is_member_pointer_v>) + return detail::invoke_memptr(f, std::forward(args)...); + else + return std::forward(f)(std::forward(args)...); + } + invoke_r \fB(2)\fP + template + requires std::is_invocable_r_v + constexpr R invoke_r(F&& f, Args&&... args) + noexcept(std::is_nothrow_invocable_r_v) + { + if constexpr (std::is_void_v) + std::invoke(std::forward(f), std::forward(args)...); + else + return std::invoke(std::forward(f), std::forward(args)...); + } + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_invoke 201411L \fI(C++17)\fP std::invoke, \fB(1)\fP + __cpp_lib_invoke_r 202106L (C++23) std::invoke_r, \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo + { + Foo(int num) : num_(num) {} + void print_add(int i) const { std::cout << num_ + i << '\\n'; } + int num_; + }; + + void print_num(int i) + { + std::cout << i << '\\n'; + } + + struct PrintNum + { + void operator()(int i) const + { + std::cout << i << '\\n'; + } + }; + + int main() + { + std::cout << "invoke a free function: "; + std::invoke(print_num, -9); + + std::cout << "invoke a lambda: "; + std::invoke([](){ print_num(42); }); + + std::cout << "invoke a member function: "; + const Foo foo(314159); + std::invoke(&Foo::print_add, foo, 1); + + std::cout << "invoke (i.e., access) a data member num_: " + << std::invoke(&Foo::num_, foo) << '\\n'; + + std::cout << "invoke a function object: "; + std::invoke(PrintNum(), 18); + + #if defined(__cpp_lib_invoke_r) + auto add = [](int x, int y){ return x + y; }; + std::cout << "invoke a lambda converting result to float: "; + auto ret = std::invoke_r(add, 11, 22); + static_assert(std::is_same()); + std::cout << std::fixed << ret << "\\ninvoke print_num: "; + std::invoke_r(print_num, 44); + #endif + } + +.SH Possible output: + + invoke a free function: -9 + invoke a lambda: 42 + invoke a member function: 314160 + invoke (i.e., access) a data member num_: 314159 + invoke a function object: 18 + invoke a lambda converting result to float: 33.000000 + invoke print_num: 44 + +.SH See also + + mem_fn creates a function object out of a pointer to a member + \fI(C++11)\fP \fI(function template)\fP + result_of deduces the result type of invoking a callable object with + invoke_result a set of arguments + \fI(C++11)\fP(removed in C++20) \fI(class template)\fP + \fI(C++17)\fP + is_invocable + is_invocable_r checks if a type can be invoked (as if by std::invoke) + is_nothrow_invocable with the given argument types + is_nothrow_invocable_r \fI(class template)\fP + \fI(C++17)\fP + apply calls a function with a tuple of arguments + \fI(C++17)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::io_errc.3 b/man/std::io_errc.3 index 19cc33383..e0fe38cf2 100644 --- a/man/std::io_errc.3 +++ b/man/std::io_errc.3 @@ -1,7 +1,14 @@ -.TH std::io_errc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::io_errc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::io_errc \- std::io_errc + .SH Synopsis Defined in header - enum class io_errc; \fI(since C++11)\fP + enum class io_errc { + + stream = 1, \fI(since C++11)\fP + + }; The scoped enumeration std::io_errc defines the error codes reported by I/O streams in std::ios_base::failure exception objects. Only one error code @@ -18,31 +25,35 @@ .SH Non-member functions make_error_code(std::io_errc) constructs an iostream error code - \fI(C++11)\fP \fI(function)\fP - make_error_condition(std::io_errc) constructs an iostream error_condition - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + make_error_condition(std::io_errc) constructs an iostream error condition + \fI(C++11)\fP \fI(function)\fP .SH Helper classes is_error_code_enum extends the type trait std::is_error_code_enum to \fI(C++11)\fP identify iostream error codes - \fI(class template)\fP + \fI(class template specialization)\fP .SH Example - + // Run this code - #include #include + #include + int main() { std::ifstream f("doesn't exist"); - try { + try + { f.exceptions(f.failbit); - } catch (const std::ios_base::failure& e) { + } + catch (const std::ios_base::failure& e) + { std::cout << "Caught an ios_base::failure.\\n"; - if(e.code() == std::io_errc::stream) + if (e.code() == std::io_errc::stream) std::cout << "The error code is std::io_errc::stream\\n"; } } @@ -55,8 +66,8 @@ .SH See also error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP diff --git a/man/std::ios.3 b/man/std::ios.3 deleted file mode 120000 index 3f1622148..000000000 --- a/man/std::ios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios.3 \ No newline at end of file diff --git a/man/std::ios.3 b/man/std::ios.3 new file mode 100644 index 000000000..53f70e4db --- /dev/null +++ b/man/std::ios.3 @@ -0,0 +1,243 @@ +.TH std::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios \- std::basic_ios + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + > class basic_ios + + : public std::ios_base + + The class std::basic_ios provides facilities for interfacing with objects that have + std::basic_streambuf interface. Several std::basic_ios objects can refer to one + actual std::basic_streambuf object. + + std-basic ios-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ios std::basic_ios + std::wios std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Public member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= the copy assignment operator is deleted + \fI(public member function)\fP +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function)\fP + eof checks if end-of-file has been reached + \fI(public member function)\fP + fail checks if an error has occurred + \fI(public member function)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function)\fP + rdstate returns state flags + \fI(public member function)\fP + setstate sets state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function)\fP + fill manages the fill character + \fI(public member function)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function)\fP + imbue sets the locale + \fI(public member function)\fP + rdbuf manages associated stream buffer + \fI(public member function)\fP + tie manages tied stream + \fI(public member function)\fP + narrow narrows characters + \fI(public member function)\fP + widen widens characters + \fI(public member function)\fP + +.SH Protected member functions + + init initializes a default-constructed std::basic_ios + \fI(protected member function)\fP + move moves from another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps with another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Straightforward implementation of std::basic_ios stores only the following members + (which all depend on the template parameters and thus cannot be part of + std::ios_base): + + * the fill character (see fill()) + * the tied stream pointer (see tie()) + * the associated stream buffer pointer (see rdbuf()). + + Actual implementations vary: + + Microsoft Visual Studio stores just those three members. + + LLVM libc++ stores 1 less member: it maintains the rdbuf pointer as a void* member + of ios_base. + + GNU libstdc++ stores 4 additional members: three cached facets and a flag to + indicate that fill was initialized. diff --git a/man/std::ios::bad.3 b/man/std::ios::bad.3 deleted file mode 120000 index 4ba5b2d1f..000000000 --- a/man/std::ios::bad.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::bad.3 \ No newline at end of file diff --git a/man/std::ios::bad.3 b/man/std::ios::bad.3 new file mode 100644 index 000000000..dab780437 --- /dev/null +++ b/man/std::ios::bad.3 @@ -0,0 +1,67 @@ +.TH std::basic_ios::bad 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::bad \- std::basic_ios::bad + +.SH Synopsis + bool bad() const; + + Returns true if non-recoverable error has occurred on the associated stream. + Specifically, returns true if badbit is set in rdstate(). + + See ios_base::iostate for the list of conditions that set badbit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if a non-recoverable error has occurred, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::ios::basic_ios.3 b/man/std::ios::basic_ios.3 deleted file mode 120000 index 3e82757c3..000000000 --- a/man/std::ios::basic_ios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::basic_ios.3 \ No newline at end of file diff --git a/man/std::ios::basic_ios.3 b/man/std::ios::basic_ios.3 new file mode 100644 index 000000000..4695bdf9d --- /dev/null +++ b/man/std::ios::basic_ios.3 @@ -0,0 +1,39 @@ +.TH std::basic_ios::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::basic_ios \- std::basic_ios::basic_ios + +.SH Synopsis + protected: \fB(1)\fP + basic_ios(); + public: \fB(2)\fP + explicit basic_ios( std::basic_streambuf* sb ); + private: \fI(until C++11)\fP + basic_ios( const basic_ios& ); \fB(3)\fP + public: \fI(since C++11)\fP + basic_ios( const basic_ios& ) = delete; + + Constructs a new std::basic_ios object. + + 1) Default constructor. The internal state is not initialized. init() must be called + before the first use of the object or before destructor, otherwise the behavior is + undefined. + 2) Initializes the internal state by calling init(sb). The associated stream buffer + is set to sb. + 3) The copy constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: I/O streams are not CopyConstructible. + +.SH Parameters + + sb - stream buffer to associate to + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1249 C++98 internal state did not need to be initialized also needs to be + before first use initialized diff --git a/man/std::ios::clear.3 b/man/std::ios::clear.3 deleted file mode 120000 index 73ea99edb..000000000 --- a/man/std::ios::clear.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::clear.3 \ No newline at end of file diff --git a/man/std::ios::clear.3 b/man/std::ios::clear.3 new file mode 100644 index 000000000..808ca3227 --- /dev/null +++ b/man/std::ios::clear.3 @@ -0,0 +1,85 @@ +.TH std::basic_ios::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::clear \- std::basic_ios::clear + +.SH Synopsis + void clear( std::ios_base::iostate state = std::ios_base::goodbit ); + + Sets the stream error state flags by assigning them the value of state. By default, + assigns std::ios_base::goodbit which has the effect of clearing all error state + flags. + + If rdbuf() is a null pointer (i.e. there is no associated stream buffer), then state + | std::ios_base::badbit is assigned. + +.SH Parameters + + new error state flags setting. It can be a combination of the following + constants: + + state - Constant Explanation + goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction error) + eofbit associated input sequence has reached end-of-file + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + If the new error state includes a bit that is also included in the exceptions() + mask, throws an exception of type failure. + +.SH Example + + clear() without arguments can be used to unset the failbit after unexpected input; + for std::cin.putback(c) see ungetc. + + +// Run this code + + #include + #include + + int main() + { + for (char c : {'\\n', '4', '1', '.', '3', '\\n', 'Z', 'Y', 'X'}) + std::cin.putback(c); // emulate user's input (not portable: see ungetc Notes) + + double n; + while (std::cout << "Please, enter a number: " && !(std::cin >> n)) + { + std::cin.clear(); + std::string line; + std::getline(std::cin, line); + std::cout << line << "\\nI am sorry, but '" << line << "' is not a number\\n"; + } + std::cout << n << "\\nThank you for entering the number " << n << '\\n'; + } + +.SH Output: + + Please, enter a number: XYZ + I am sorry, but 'XYZ' is not a number + Please, enter a number: 3.14 + Thank you for entering the number 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + an excption would be thrown if the current + LWG 412 C++98 error state checks the new + includes a bit that is also included in the error state instead + exceptions() mask + +.SH See also + + setstate sets state flags + \fI(public member function)\fP + rdstate returns state flags + \fI(public member function)\fP diff --git a/man/std::ios::copyfmt.3 b/man/std::ios::copyfmt.3 deleted file mode 120000 index ba8869565..000000000 --- a/man/std::ios::copyfmt.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::copyfmt.3 \ No newline at end of file diff --git a/man/std::ios::copyfmt.3 b/man/std::ios::copyfmt.3 new file mode 100644 index 000000000..775df7d97 --- /dev/null +++ b/man/std::ios::copyfmt.3 @@ -0,0 +1,94 @@ +.TH std::basic_ios::copyfmt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::copyfmt \- std::basic_ios::copyfmt + +.SH Synopsis + basic_ios& copyfmt( const basic_ios& other ); + + If other refers to the same object as *this, has no effects. Otherwise, copies the + state of the stream other into *this. This is done in the following sequence: + + 1) Calls every callback registered by register_callback() passing erase_event as + parameter. + 2) Copies all member objects from other to *this except for rdstate(), the exception + mask, and rdbuf(). In particular, makes copies of the locale, the formatting flags, + the contents of the arrays std::ios_base::iword and std::ios_base::pword (but not + the iword and pword pointers themselves), the callbacks, and the tied stream. + 3) Calls every callback registered by register_callback() passing copyfmt_event as + parameter. + 4) Copies the exception mask from other to *this as if by calling + exceptions(other.exceptions()). + +.SH Parameters + + other - another stream to use as source + +.SH Return value + + *this + +.SH Notes + + The second pass through the callbacks may be used to deep-copy the user-defined + objects pointed to by the pointers in std::ios_base::pword. + + copyfmt() may be used to save and restore the state of a stream. Boost provides a + more fine-grained I/O state savers library for the same purpose. + +.SH Example + + Makes the std::ofstream object "out" behave exactly like std::cout, including + formatting, tie() to std::cin, etc. + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ofstream out; + + out.copyfmt(std::cout); // copy everything except rdstate and rdbuf + out.clear(std::cout.rdstate()); // copy rdstate + out.basic_ios::rdbuf(std::cout.rdbuf()); // share the buffer + + out << "Hello, world\\n"; + + auto bin = [](std::ios_base::fmtflags f) + { + return std::bitset + { static_cast(f) }; + }; + std::ofstream out2; + std::cout << "1) out2.flags(): " << bin(out2.flags()) << '\\n'; + std::cout << "2) cout.flags(): " << bin(std::cout.flags()) << '\\n'; + std::cout.setf(std::ios::hex | std::ios::fixed | std::ios::boolalpha); + std::cout << "3) cout.flags(): " << bin(std::cout.flags()) << '\\n'; + out2.copyfmt(std::cout); // copy everything except rdstate and rdbuf + std::cout << "4) out2.flags(): " << bin(out2.flags()) << '\\n'; + } + +.SH Possible output: + + Hello, world + 1) out2.flags(): 00000000000000000001000000000010 + 2) cout.flags(): 00000000000000000001000000000010 + 3) cout.flags(): 00000000000000000001000000001111 + 4) out2.flags(): 00000000000000000001000000001111 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 256 C++98 step 3 called the registered callbacks with the corrected to + event type copy_event, which is not defined copyfmt_event + if other refers to the same object as *this, the + LWG 292 C++98 member objects do nothing + were still copied and the registered callbacks in this case + were still called diff --git a/man/std::ios::eof.3 b/man/std::ios::eof.3 deleted file mode 120000 index 6b20a3e3d..000000000 --- a/man/std::ios::eof.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::eof.3 \ No newline at end of file diff --git a/man/std::ios::eof.3 b/man/std::ios::eof.3 new file mode 100644 index 000000000..2eeb9f530 --- /dev/null +++ b/man/std::ios::eof.3 @@ -0,0 +1,80 @@ +.TH std::basic_ios::eof 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::eof \- std::basic_ios::eof + +.SH Synopsis + bool eof() const; + + Returns true if the associated stream has reached end-of-file. Specifically, returns + true if eofbit is set in rdstate(). + + See ios_base::iostate for the list of conditions that set eofbit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if an end-of-file has occurred, false otherwise. + +.SH Notes + + This function only reports the stream state as set by the most recent I/O operation; + it does not examine the associated data source. For example, if the most recent I/O + was a get() which returned the last byte of a file, eof() returns false. The next + get() fails to read anything and sets the eofbit. Only then does eof() return true. + + In typical usage, input stream processing stops on any error. eof() and fail() can + then be used to distinguish between different error conditions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true + + feof checks for the end-of-file + \fI(function)\fP diff --git a/man/std::ios::exceptions.3 b/man/std::ios::exceptions.3 deleted file mode 120000 index 049774224..000000000 --- a/man/std::ios::exceptions.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::exceptions.3 \ No newline at end of file diff --git a/man/std::ios::exceptions.3 b/man/std::ios::exceptions.3 new file mode 100644 index 000000000..56dd00a97 --- /dev/null +++ b/man/std::ios::exceptions.3 @@ -0,0 +1,62 @@ +.TH std::basic_ios::exceptions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::exceptions \- std::basic_ios::exceptions + +.SH Synopsis + std::ios_base::iostate exceptions() const; \fB(1)\fP + void exceptions( std::ios_base::iostate except ); \fB(2)\fP + + Gets and sets the exception mask of the stream. The exception mask determines which + error states trigger exceptions of type failure. + + 1) Returns the exception mask. + 2) Sets the exception mask to except. If the stream has an error state covered by + the exception mask when called, an exception is immediately triggered. + +.SH Parameters + + except - exception mask + +.SH Return value + + 1) The current exception mask. + 2) \fI(none)\fP + +.SH Notes + + This section is incomplete + Reason: discuss LWG2349 and link from ios_base::clear, and from + (un)formatted(i/o)utputfunction requirement pages (or perhaps the behavior should + be fully elaborated on the requirement pages and linked from here). See also + stackoverflow.com/a/35089910 + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int ivalue; + try + { + std::ifstream in("in.txt"); + in.exceptions(std::ifstream::failbit); // may throw + in >> ivalue; // may throw + } + catch (const std::ios_base::failure& fail) + { + // handle exception here + std::cout << fail.what() << '\\n'; + } + } + +.SH Possible output: + + basic_ios::clear: iostream error + +.SH Category: + * Todo with reason diff --git a/man/std::ios::fail.3 b/man/std::ios::fail.3 deleted file mode 120000 index ed2e7637d..000000000 --- a/man/std::ios::fail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::fail.3 \ No newline at end of file diff --git a/man/std::ios::fail.3 b/man/std::ios::fail.3 new file mode 100644 index 000000000..f5d71a0d6 --- /dev/null +++ b/man/std::ios::fail.3 @@ -0,0 +1,70 @@ +.TH std::basic_ios::fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::fail \- std::basic_ios::fail + +.SH Synopsis + bool fail() const; + + Returns true if an error has occurred on the associated stream. Specifically, + returns true if badbit or failbit is set in rdstate(). + + See ios_base::iostate for the list of conditions that set failbit or badbit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if an error has occurred, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true + + ferror checks for a file error + \fI(function)\fP diff --git a/man/std::ios::fill.3 b/man/std::ios::fill.3 deleted file mode 120000 index 1b7b51aeb..000000000 --- a/man/std::ios::fill.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::fill.3 \ No newline at end of file diff --git a/man/std::ios::fill.3 b/man/std::ios::fill.3 new file mode 100644 index 000000000..cc61848b0 --- /dev/null +++ b/man/std::ios::fill.3 @@ -0,0 +1,47 @@ +.TH std::basic_ios::fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::fill \- std::basic_ios::fill + +.SH Synopsis + CharT fill() const; \fB(1)\fP + CharT fill( CharT ch ); \fB(2)\fP + + Manages the fill character used to pad the output conversions to the specified field + width. + + 1) Returns the current fill character. + 2) Sets the fill character to ch, returns previous value of the fill character. + +.SH Parameters + + ch - the character to use as fill character + +.SH Return value + + The fill character before the call to the function. + +.SH Example + + +// Run this code + + #include + #include + + int main () + { + std::cout << "With default setting : [" << std::setw(10) << 40 << "]\\n"; + char prev = std::cout.fill('x'); + std::cout << "Replaced '" << prev << "' with '" + << std::cout.fill() << "': [" << std::setw(10) << 40 << "]\\n"; + } + +.SH Output: + + With default setting : [ 40] + Replaced ' ' with 'x': [xxxxxxxx40] + +.SH See also + + setfill changes the fill character + \fI(function template)\fP diff --git a/man/std::ios::good.3 b/man/std::ios::good.3 deleted file mode 120000 index d380a0f1c..000000000 --- a/man/std::ios::good.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::good.3 \ No newline at end of file diff --git a/man/std::ios::good.3 b/man/std::ios::good.3 new file mode 100644 index 000000000..55892fb7c --- /dev/null +++ b/man/std::ios::good.3 @@ -0,0 +1,82 @@ +.TH std::basic_ios::good 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::good \- std::basic_ios::good + +.SH Synopsis + bool good() const; + + Returns true if the most recent I/O operation on the stream completed successfully. + Specifically, returns result of rdstate() == 0. + + See ios_base::iostate for the list of conditions that set the stream status bits. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stream error flags are all false, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const char* fname = "/tmp/test.txt"; + std::ofstream ofile{fname}; + ofile << "10 " << "11 " << "12 " << "non-int"; + ofile.close(); + + std::ifstream file{fname}; + if (!file.good()) + { + std::cout << "#1. Opening file test.txt failed - " + "one of the error flags is true\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + { + std::cout << "#2. I/O error while reading - badbit is true\\n"; + return EXIT_FAILURE; + } + else if (file.eof()) + std::cout << "#3. End of file reached successfully - eofbit is true\\n" + "This is fine even though file.good() is false\\n"; + else if (file.fail()) + std::cout << "#4. Non-integer data encountered - failbit is true\\n"; + } + +.SH Possible output: + + 10 11 12 + #4. Non-integer data encountered - failbit is true + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::ios::imbue.3 b/man/std::ios::imbue.3 deleted file mode 120000 index fde227cb4..000000000 --- a/man/std::ios::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::imbue.3 \ No newline at end of file diff --git a/man/std::ios::imbue.3 b/man/std::ios::imbue.3 new file mode 100644 index 000000000..065831d53 --- /dev/null +++ b/man/std::ios::imbue.3 @@ -0,0 +1,46 @@ +.TH std::basic_ios::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::imbue \- std::basic_ios::imbue + +.SH Synopsis + std::locale imbue( const std::locale& loc ); + + Replaces the current locale. Effectively calls ios_base::imbue(loc) and if there is + an associated stream buffer (rdbuf() != 0), then calls rdbuf()->pubimbue(loc). + +.SH Parameters + + loc - the new locale + +.SH Return value + + The previous locale, as returned by ios_base::imbue(loc). + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream iss; + iss.imbue(std::locale("en_US.UTF8")); + + std::cout << "Current locale: " << iss.getloc().name() << '\\n'; + + iss.imbue(std::locale()); + std::cout << "Global locale : " << iss.getloc().name() << '\\n'; + } + +.SH Output: + + Current locale: en_US.UTF8 + Global locale : C diff --git a/man/std::ios::init.3 b/man/std::ios::init.3 deleted file mode 120000 index c1c5dfca0..000000000 --- a/man/std::ios::init.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::init.3 \ No newline at end of file diff --git a/man/std::ios::init.3 b/man/std::ios::init.3 new file mode 100644 index 000000000..18affa265 --- /dev/null +++ b/man/std::ios::init.3 @@ -0,0 +1,39 @@ +.TH std::basic_ios::init 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::init \- std::basic_ios::init + +.SH Synopsis + protected: + void init( std::basic_streambuf* sb ); + + Sets the associated stream buffer to sb and initializes the internal state. + + The postconditions are as follows: + + Element Value + rdbuf() sb + tie() null pointer + rdstate() goodbit if sb is not a null pointer, otherwise badbit + exceptions() goodbit + flags() skipws | dec + width() 0 + precision() 6 + fill() widen(' ') + getloc() a copy of the value returned by std::locale() + + This member function is protected: it is called by the constructors of the derived + stream classes std::basic_istream and std::basic_ostream once the associated stream + buffer is known. Until this function is called, every member function (including the + destructor) of the default-constructed std::basic_ios invokes undefined behavior. + Note that basic_ios is a virtual base class, and therefore its constructor is not + called by the constructors of those directly derived classes, which is why two-stage + initialization is necessary. + +.SH Parameters + + sb - stream buffer to associate to + +.SH See also + + constructor constructs the object + \fI(public member function)\fP diff --git a/man/std::ios::ios.3 b/man/std::ios::ios.3 deleted file mode 120000 index 3e82757c3..000000000 --- a/man/std::ios::ios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::basic_ios.3 \ No newline at end of file diff --git a/man/std::ios::ios.3 b/man/std::ios::ios.3 new file mode 100644 index 000000000..4695bdf9d --- /dev/null +++ b/man/std::ios::ios.3 @@ -0,0 +1,39 @@ +.TH std::basic_ios::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::basic_ios \- std::basic_ios::basic_ios + +.SH Synopsis + protected: \fB(1)\fP + basic_ios(); + public: \fB(2)\fP + explicit basic_ios( std::basic_streambuf* sb ); + private: \fI(until C++11)\fP + basic_ios( const basic_ios& ); \fB(3)\fP + public: \fI(since C++11)\fP + basic_ios( const basic_ios& ) = delete; + + Constructs a new std::basic_ios object. + + 1) Default constructor. The internal state is not initialized. init() must be called + before the first use of the object or before destructor, otherwise the behavior is + undefined. + 2) Initializes the internal state by calling init(sb). The associated stream buffer + is set to sb. + 3) The copy constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: I/O streams are not CopyConstructible. + +.SH Parameters + + sb - stream buffer to associate to + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1249 C++98 internal state did not need to be initialized also needs to be + before first use initialized diff --git a/man/std::ios::move.3 b/man/std::ios::move.3 deleted file mode 120000 index 80fb430d4..000000000 --- a/man/std::ios::move.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::move.3 \ No newline at end of file diff --git a/man/std::ios::move.3 b/man/std::ios::move.3 new file mode 100644 index 000000000..00e50ed27 --- /dev/null +++ b/man/std::ios::move.3 @@ -0,0 +1,33 @@ +.TH std::basic_ios::move 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::move \- std::basic_ios::move + +.SH Synopsis + protected: \fI(since C++11)\fP + void move( basic_ios& other ); + protected: \fI(since C++11)\fP + void move( basic_ios&& other ); + + Replaces the current state with that of other, except for the associated rdbuf. + other is in valid, but unspecified state after the call. After the call to this + function, rdbuf() returns a null pointer, other.rdbuf() returns the same value as + before the call, and other.tie() returns a null pointer. + + This member function is protected: it is called by the protected move constructors + of the derived stream classes std::basic_ostream and std::basic_istream, which, in + turn, are called by the public move constructors of the further derived stream + classes such as std::basic_ofstream, which know how to correctly move the associated + streambuffer. + +.SH Parameters + + other - the basic_ios object to transfer the state from + +.SH Return value + + \fI(none)\fP + +.SH See also + + swap swaps with another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::ios::narrow.3 b/man/std::ios::narrow.3 deleted file mode 120000 index 104f8b0c1..000000000 --- a/man/std::ios::narrow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::narrow.3 \ No newline at end of file diff --git a/man/std::ios::narrow.3 b/man/std::ios::narrow.3 new file mode 100644 index 000000000..b498eaa0c --- /dev/null +++ b/man/std::ios::narrow.3 @@ -0,0 +1,32 @@ +.TH std::basic_ios::narrow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::narrow \- std::basic_ios::narrow + +.SH Synopsis + char narrow( char_type c, char dfault ) const; + + Converts a current locale-specific character c to its standard equivalent. The + result is converted from char_type to char if needed. If no conversion can be + performed, the function returns dfault. + + Effectively calls std::use_facet< std::ctype >(getloc()).narrow(c, + dfault);. + +.SH Parameters + + c - character to convert + dfault - character to return if the conversion was unsuccessful + +.SH Return value + + Character converted to its standard equivalent and then to char. dfault is returned + if the conversion fails. + +.SH See also + + widen widens characters + \fI(public member function)\fP + narrow invokes do_narrow + \fI(public member function of std::ctype)\fP + wctob narrows a wide character to a single-byte narrow character, if possible + \fI(function)\fP diff --git a/man/std::ios::operator!.3 b/man/std::ios::operator!.3 deleted file mode 120000 index 5b157aec2..000000000 --- a/man/std::ios::operator!.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::operator!.3 \ No newline at end of file diff --git a/man/std::ios::operator!.3 b/man/std::ios::operator!.3 new file mode 100644 index 000000000..07ac029c2 --- /dev/null +++ b/man/std::ios::operator!.3 @@ -0,0 +1,65 @@ +.TH std::basic_ios::operator! 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::operator! \- std::basic_ios::operator! + +.SH Synopsis + bool operator!() const; + + Returns true if an error has occurred on the associated stream. Specifically, + returns true if badbit or failbit is set in rdstate(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if an error has occurred, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::ios::operatorbool.3 b/man/std::ios::operatorbool.3 deleted file mode 120000 index fc40e5647..000000000 --- a/man/std::ios::operatorbool.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::operatorbool.3 \ No newline at end of file diff --git a/man/std::ios::operatorbool.3 b/man/std::ios::operatorbool.3 new file mode 100644 index 000000000..40c8dc683 --- /dev/null +++ b/man/std::ios::operatorbool.3 @@ -0,0 +1,95 @@ +.TH std::basic_ios::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::operatorbool \- std::basic_ios::operatorbool + +.SH Synopsis + operator /* unspecified-boolean-type */() const; \fB(1)\fP \fI(until C++11)\fP + explicit operator bool() const; \fB(2)\fP \fI(since C++11)\fP + + Checks whether the stream has no errors. + + 1) Returns a value that evaluates to false in a boolean context if fail() returns + true, otherwise returns a value that evaluates to true in a boolean context. + 2) Returns true if the stream has no errors and is ready for I/O operations. + Specifically, returns !fail(). + + This operator makes it possible to use streams and functions that return references + to streams as loop conditions, resulting in the idiomatic C++ input loops such as + while (stream >> value) {...} or while (std::getline(stream, string)) {...}. Such + loops execute the loop's body only if the input operation succeeded. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A value that evaluates to true in a boolean context if the stream has no errors, + a value that evaluates to false in a boolean context otherwise. + 2) true if the stream has no errors, false otherwise. + +.SH Notes + + This conversion can be used in contexts where a bool is expected (e.g. an if + condition). However, implicit conversions (e.g. to int) that can occur with bool are + not allowed. + + In C++98, operator bool could not be provided directly due to the safe bool problem. + The initial solution in C++98 is to provide operator void*, which returns a null + pointer if fail() returns true or a non-null pointer otherwise. It is replaced by + the resolution of LWG issue 468, which allows Safe Bool idiom to be applied. + + Since C++11, conversion functions can be explicit. The resolution of LWG issue 1094 + introduced the explicit operator bool and the boolean conversion is now safe. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s("1 2 3 error"); + int n; + + std::cout << std::boolalpha << "s is " << static_cast(s) << '\\n'; + while (s >> n) + std::cout << n << '\\n'; + std::cout << "s is " << static_cast(s) << '\\n'; + } + +.SH Output: + + s is true + 1 + 2 + 3 + s is false + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 468 C++98 operator void* was a conversion function to an unspecified + provided boolean type is provided instead + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::ios::rdbuf.3 b/man/std::ios::rdbuf.3 deleted file mode 120000 index 72f17cfc3..000000000 --- a/man/std::ios::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::rdbuf.3 \ No newline at end of file diff --git a/man/std::ios::rdbuf.3 b/man/std::ios::rdbuf.3 new file mode 100644 index 000000000..490355c23 --- /dev/null +++ b/man/std::ios::rdbuf.3 @@ -0,0 +1,69 @@ +.TH std::basic_ios::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::rdbuf \- std::basic_ios::rdbuf + +.SH Synopsis + std::basic_streambuf* rdbuf() const; \fB(1)\fP + std::basic_streambuf* rdbuf( std::basic_streambuf* sb ); + + Manages the associated stream buffer. + + 1) Returns the associated stream buffer. If there is no associated stream buffer, + returns a null pointer. + 2) Sets the associated stream buffer to sb. The error state is cleared by calling + clear(). Returns the associated stream buffer before the operation. If there is no + associated stream buffer, returns a null pointer. + +.SH Parameters + + sb - stream buffer to associate to + +.SH Return value + + The associated stream buffer, or a null pointer if there was no associated stream + buffer. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream local; + auto cout_buff = std::cout.rdbuf(); // save pointer to std::cout buffer + + std::cout.rdbuf(local.rdbuf()); // substitute internal std::cout buffer with + // buffer of 'local' object + + // now std::cout work with 'local' buffer + // you don't see this message + std::cout << "some message"; + + // go back to old buffer + std::cout.rdbuf(cout_buff); + + // you will see this message + std::cout << "back to default buffer\\n"; + + // print 'local' content + std::cout << "local content: " << local.str() << "\\n"; + } + +.SH Output: + + back to default buffer + local content: some message + +.SH See also + + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP diff --git a/man/std::ios::rdstate.3 b/man/std::ios::rdstate.3 deleted file mode 120000 index e8a0aa35b..000000000 --- a/man/std::ios::rdstate.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::rdstate.3 \ No newline at end of file diff --git a/man/std::ios::rdstate.3 b/man/std::ios::rdstate.3 new file mode 100644 index 000000000..934207b16 --- /dev/null +++ b/man/std::ios::rdstate.3 @@ -0,0 +1,57 @@ +.TH std::basic_ios::rdstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::rdstate \- std::basic_ios::rdstate + +.SH Synopsis + iostate rdstate() const; + + Returns the current stream error state. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + current stream error state. It is a bitmask type and can be a combination of the + following constants: + + Constant Explanation + goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction error) + eofbit associated input sequence has reached end-of-file + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream stream; + + if (stream.rdstate() == std::ios_base::goodbit) + std::cout << "stream state is goodbit\\n"; + + stream.setstate(std::ios_base::eofbit); + + // check state is exactly eofbit (no failbit and no badbit) + if (stream.rdstate() == std::ios_base::eofbit) + std::cout << "stream state is eofbit\\n"; + } + +.SH Output: + + stream state is goodbit + stream state is eofbit + +.SH See also + + setstate sets state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP diff --git a/man/std::ios::set_rdbuf.3 b/man/std::ios::set_rdbuf.3 deleted file mode 120000 index 45dc49f20..000000000 --- a/man/std::ios::set_rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::set_rdbuf.3 \ No newline at end of file diff --git a/man/std::ios::set_rdbuf.3 b/man/std::ios::set_rdbuf.3 new file mode 100644 index 000000000..02b9f3f7f --- /dev/null +++ b/man/std::ios::set_rdbuf.3 @@ -0,0 +1,41 @@ +.TH std::basic_ios::set_rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::set_rdbuf \- std::basic_ios::set_rdbuf + +.SH Synopsis + protected: \fI(since C++11)\fP + void set_rdbuf( std::basic_streambuf* sb ); + + Sets the associated stream buffer to sb without clearing the error state. + + This member function is protected: it is called by the move constructors of the + derived streams such as std::basic_ofstream or std::basic_istringstream, as the + final step after constructing the base class and after moving the stream buffer: + only the most derived stream class knows how to correctly move the stream buffer, + but std::basic_ios needs to be made aware of the stream's new location so that its + public member functions can access it. + +.SH Parameters + + sb - stream buffer to associate to + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rdbuf manages associated stream buffer + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ios::setstate.3 b/man/std::ios::setstate.3 deleted file mode 120000 index 024203ede..000000000 --- a/man/std::ios::setstate.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::setstate.3 \ No newline at end of file diff --git a/man/std::ios::setstate.3 b/man/std::ios::setstate.3 new file mode 100644 index 000000000..378a09c28 --- /dev/null +++ b/man/std::ios::setstate.3 @@ -0,0 +1,61 @@ +.TH std::basic_ios::setstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::setstate \- std::basic_ios::setstate + +.SH Synopsis + void setstate( iostate state ); + + Sets the stream error flags state in addition to currently set flags. Essentially + calls clear(rdstate() | state). May throw an exception. + +.SH Parameters + + stream error state flags to set. It can be a combination of the following + constants: + + state - Constant Explanation + goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction error) + eofbit associated input sequence has reached end-of-file + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream stream; + + if (!stream.fail()) + std::cout << "stream is not fail\\n"; + + stream.setstate(std::ios_base::failbit); + + if (stream.fail()) + std::cout << "now stream is fail\\n"; + + if (!stream.good()) + std::cout << "and stream is not good\\n"; + } + +.SH Output: + + stream is not fail + now stream is fail + and stream is not good + +.SH See also + + rdstate returns state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP diff --git a/man/std::ios::swap.3 b/man/std::ios::swap.3 deleted file mode 120000 index 44127e81a..000000000 --- a/man/std::ios::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::swap.3 \ No newline at end of file diff --git a/man/std::ios::swap.3 b/man/std::ios::swap.3 new file mode 100644 index 000000000..f22600bac --- /dev/null +++ b/man/std::ios::swap.3 @@ -0,0 +1,27 @@ +.TH std::basic_ios::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::swap \- std::basic_ios::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_ios& other ) noexcept; + + Exchanges the states of *this and other, except for the associated rdbuf objects. + rdbuf() and other.rdbuf() returns the same values as before the call. + + This swap function is protected: it is called by the swap member functions of the + derived stream classes such as std::basic_ofstream or std::basic_istringstream, + which know how to correctly swap the associated streambuffers. + +.SH Parameters + + other - the basic_ios object to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH See also + + move moves from another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::ios::tie.3 b/man/std::ios::tie.3 deleted file mode 120000 index 7551d485a..000000000 --- a/man/std::ios::tie.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::tie.3 \ No newline at end of file diff --git a/man/std::ios::tie.3 b/man/std::ios::tie.3 new file mode 100644 index 000000000..3dba24394 --- /dev/null +++ b/man/std::ios::tie.3 @@ -0,0 +1,89 @@ +.TH std::basic_ios::tie 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::tie \- std::basic_ios::tie + +.SH Synopsis + std::basic_ostream* tie() const; \fB(1)\fP + std::basic_ostream* tie( std::basic_ostream* str \fB(2)\fP + ); + + Manages the tied stream. A tied stream is an output stream which is synchronized + with the sequence controlled by the stream buffer (rdbuf()), that is, flush() is + called on the tied stream before any input/output operation on *this. + + 1) Returns the current tied stream. If there is no tied stream, a null pointer is + returned. + 2) Sets the current tied stream to str. Returns the tied stream before the + operation. If there is no tied stream, a null pointer is returned. If str is not + null and tie() is reachable by traversing the linked list of tied stream objects + starting from str->tie(), the behavior is undefined. + +.SH Parameters + + str - an output stream to set as the tied stream + +.SH Return value + + The tied stream, or a null pointer if there was no tied stream. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + By default, the standard stream std::cout is tied to std::cin and std::cerr. + Similarly, its wide counterpart std::wcout is tied to std::wcin and std::wcerr. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ofstream os("test.txt"); + std::ifstream is("test.txt"); + std::string value("0"); + + os << "Hello"; + is >> value; + + std::cout << "Result before tie(): " << std::quoted(value) << "\\n"; + is.clear(); + is.tie(&os); + + is >> value; + + std::cout << "Result after tie(): " << std::quoted(value) << "\\n"; + } + +.SH Output: + + Result before tie(): "0" + Result after tie(): "Hello" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + two streams could be tied to each + LWG 835 C++98 other^[1] the behavior is undefined + (either directly or through another in this case + intermediate stream object) + + 1. ↑ std::basic_ostream::flush() is an UnformattedOutputFunction, so it creates a + sentry object while being called. When flush() is called on a stream object, the + constructor of the sentry object will call flush() on its tied stream, and that + flush() will construct another sentry object and its constructor will call + flush() on the tied stream of that stream and so on. Therefore, if streams a and + b are (directly or indirectly) tied to each other, calling a.flush() will + eventually call b.flush(), which will eventually call a.flush(), and will result + in an infinite loop. diff --git a/man/std::ios::widen.3 b/man/std::ios::widen.3 deleted file mode 120000 index 535be9e4f..000000000 --- a/man/std::ios::widen.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::widen.3 \ No newline at end of file diff --git a/man/std::ios::widen.3 b/man/std::ios::widen.3 new file mode 100644 index 000000000..f7d5906f7 --- /dev/null +++ b/man/std::ios::widen.3 @@ -0,0 +1,28 @@ +.TH std::basic_ios::widen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::widen \- std::basic_ios::widen + +.SH Synopsis + char_type widen( char c ) const; + + Converts a character c to its equivalent in the current locale. The result is + converted from char to character type used within the stream if needed. + + Effectively calls std::use_facet< std::ctype >(getloc()).widen(c). + +.SH Parameters + + c - character to convert + +.SH Return value + + Character converted to char_type + +.SH See also + + narrow narrows characters + \fI(public member function)\fP + do_widen converts a character or characters from char to CharT + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + btowc widens a single-byte narrow character to wide character, if possible + \fI(function)\fP diff --git a/man/std::ios::~basic_ios.3 b/man/std::ios::~basic_ios.3 deleted file mode 120000 index 00095a990..000000000 --- a/man/std::ios::~basic_ios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::~basic_ios.3 \ No newline at end of file diff --git a/man/std::ios::~basic_ios.3 b/man/std::ios::~basic_ios.3 new file mode 100644 index 000000000..4b2204a05 --- /dev/null +++ b/man/std::ios::~basic_ios.3 @@ -0,0 +1,21 @@ +.TH std::basic_ios::~basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::~basic_ios \- std::basic_ios::~basic_ios + +.SH Synopsis + virtual ~basic_ios(); + + Destroys the basic_ios object. rdbuf is not destroyed. + +.SH Notes + + This destructor is virtual because the base class destructor, ios_base::~ios_base is + virtual. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 53 C++98 it was unspecified whether rdbuf is destroyed it is not destroyed diff --git a/man/std::ios_base.3 b/man/std::ios_base.3 index b573ecd0d..db0ab0ac5 100644 --- a/man/std::ios_base.3 +++ b/man/std::ios_base.3 @@ -1,4 +1,7 @@ -.TH std::ios_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base \- std::ios_base + .SH Synopsis Defined in header class ios_base; @@ -6,14 +9,14 @@ The class ios_base is a multipurpose class that serves as the base class for all I/O stream classes. It maintains several kinds of data: - 1) state information: stream status flags + 1) state information: stream status flags. 2) control information: flags that control formatting of both input and output - sequences and the imbued locale + sequences and the imbued locale. 3) private storage: indexed extensible data structure that allows both long and void* members, which may be implemented as two arbitrary-length arrays or a single array of two-element structs or another container. 4) callbacks: arbitrary number of user-defined functions to be called from imbue(), - copyfmt(), and ~ios_base() + std::basic_ios::copyfmt(), and ~ios_base(). Typical implementation holds member constants corresponding to all values of fmtflags, iostate, openmode, and seekdir shown below, member variables to maintain @@ -24,140 +27,160 @@ .SH Member functions constructor constructs the object - \fI(protected member function)\fP + \fI(protected member function)\fP destructor destructs the object - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= assigns to the stream + \fI(public member function)\fP .SH Formatting flags manages format flags - \fI(public member function)\fP + \fI(public member function)\fP setf sets specific format flag - \fI(public member function)\fP + \fI(public member function)\fP unsetf clears specific format flag - \fI(public member function)\fP + \fI(public member function)\fP precision manages decimal precision of floating point operations - \fI(public member function)\fP + \fI(public member function)\fP width manages field width - \fI(public member function)\fP + \fI(public member function)\fP .SH Locales imbue sets locale - \fI(public member function)\fP + \fI(public member function)\fP getloc returns current locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function)\fP + \fI(public static member function)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function)\fP + \fI(public member function)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function)\fP + \fI(public member function)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function)\fP + \fI(public member function)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function)\fP .SH Member classes failure stream exception - \fI(public member class)\fP + \fI(public member class)\fP Init initializes standard stream objects - \fI(public member class)\fP + \fI(public member class)\fP .SH Member types and constants - Type Explanation - stream open mode type - - The following constants are also defined: - - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after - open - - \fI(typedef)\fP - formatting flags type - - The following constants are also defined: - - Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the - right) - right right adjustment (adds fill characters to the - left) - internal internal adjustment (adds fill characters to the - internal designated point) - adjustfield left|right|internal. Useful for masking operations - - generate floating point types using scientific - scientific notation, or hex notation if combined with fixed - - generate floating point types using fixed - fmtflags fixed notation, or hex notation if combined with - scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for - masking operations - boolalpha insert and extract bool type in alphanumeric - format - generate a prefix indicating the numeric base for - showbase integer output, require the currency indicator in - monetary I/O - showpoint generate a decimal-point character unconditionally - for floating-point number output - showpos generate a + character for non-negative numeric - output - skipws skip leading whitespace before certain input - operations - unitbuf flush the output after each output operation - - replace certain lowercase letters with their - uppercase uppercase - equivalents in certain output output operations - - - \fI(typedef)\fP - state of the stream type - - The following constants are also defined: - - Constant Explanation - goodbit no error - iostate badbit irrecoverable stream error - failbit input/output operation failed (formatting or - extraction error) - eofbit associated input sequence has reached end-of-file - - - \fI(typedef)\fP - seeking direction type - - The following constants are also defined: - - Constant Explanation - seekdir beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator - - - \fI(typedef)\fP - event specifies event type - \fI(enum)\fP - event_callback callback function type - \fI(typedef)\fP + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + .SH Deprecated member types - Type Explanation - io_state\fB(deprecated)\fP integer type that may be used like iostate - open_mode\fB(deprecated)\fP integer type that may be used like openmode - seek_dir\fB(deprecated)\fP integer type that may be used like seekdir - streamoff\fB(deprecated)\fP unspecified type that may be used like off_type, not - necessarily std::streamoff - streampos\fB(deprecated)\fP unspecified type that may be used like pos_type, not - necessarily std::streampos + Type Explanation + io_state \fB(deprecated)\fP integer type that may be used like iostate + open_mode \fB(deprecated)\fP integer type that may be used like openmode + seek_dir \fB(deprecated)\fP integer type that may be used like seekdir \fI(until C++17)\fP + streamoff \fB(deprecated)\fP unspecified type that may be used like + off_type, not necessarily std::streamoff + streampos \fB(deprecated)\fP unspecified type that may be used like + pos_type, not necessarily std::streampos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::ios_base defined operator~, operator& + LWG 1357 C++98 and operator| for types openmode, fmtflags and removed these + (N3110) iostate, violating the requirements of definitions + BitmaskType^[1] + + 1. ↑ A BitmaskType needs to support bitwise opertaions on its own. The bitwise + operation support should not be provided externally. + +.SH See also + + basic_ios manages an arbitrary stream buffer + \fI(class template)\fP diff --git a/man/std::ios_base::Init.3 b/man/std::ios_base::Init.3 index 1dff35180..1a694f2d9 100644 --- a/man/std::ios_base::Init.3 +++ b/man/std::ios_base::Init.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::Init 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::Init 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::Init \- std::ios_base::Init + .SH Synopsis class Init; @@ -8,27 +11,47 @@ constructed as well as flushes the output streams when the last instance is destructed. - The header declares (directly or indirectly) an instance of - std::ios_base::Init with static storage duration, whose definition is provided by - the C++ library: this makes it safe to access the standard I/O streams in the - constructors and destructors of static objects (as long as #include is - present in the translation unit) + The header behaves as if it defines (directly or indirectly) an instance + of std::ios_base::Init with static storage duration: this makes it safe to access + the standard I/O streams in the constructors and destructors of static objects with + ordered initialization (as long as is included in the translation unit + before these objects were defined). + + Each C++ library module in a hosted implementation behaves as if it + contains an interface unit that defines an unexported + std::ios_base::Init variable with ordered initialization. + (since C++23) + As a result, the definition of that variable is appearance-ordered + before any declaration following the point of importation of a C++ + library module. Whether such a definition exists is unobservable by a + program that does not reference any of the standard iostream objects. .SH Member functions - if *this is the first instance created, initializes the default C++ - constructor streams + constructor initializes the default C++ streams if they have not been created yet \fI(public member function)\fP - destructor if *this is the last instance created, flushes the default C++ streams + flushes the default C++ streams if *this is the last instance to be + destructor destroyed \fI(public member function)\fP + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the behaviors of the constructor and the + LWG 1123 C++98 destructor removed the dependency + depend on an exposition-only static data + member init_cnt + .SH See also cin reads from the standard C input stream stdin - wcin (global object) + wcin (global object) cout writes to the standard C output stream stdout - wcout (global object) + wcout (global object) cerr writes to the standard C error stream stderr, unbuffered - wcerr (global object) + wcerr (global object) clog writes to the standard C error stream stderr - wclog (global object) + wclog (global object) diff --git a/man/std::ios_base::event.3 b/man/std::ios_base::event.3 index 41b10bfbb..639105442 100644 --- a/man/std::ios_base::event.3 +++ b/man/std::ios_base::event.3 @@ -1,6 +1,9 @@ -.TH std::ios_base::event 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::event 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::event \- std::ios_base::event + .SH Synopsis - enum event; + enum event { erase_event, imbue_event, copyfmt_event }; Specifies the event type which is passed to functions registered by register_callback() on specific events. The following constants are defined: @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::ios_base::event_callback.3 b/man/std::ios_base::event_callback.3 index af363b2e0..b50d31b77 100644 --- a/man/std::ios_base::event_callback.3 +++ b/man/std::ios_base::event_callback.3 @@ -1,6 +1,9 @@ -.TH std::ios_base::event_callback 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::event_callback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::event_callback \- std::ios_base::event_callback + .SH Synopsis - typedef void (*event_callback)(event type, ios_base& ios, int index); + typedef void ( *event_callback )( event type, ios_base& ios, int index ); The type of function callbacks that can be registered using register_callback() to be called on specific events. @@ -18,10 +21,10 @@ .SH See also copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP imbue sets locale - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fB[virtual]\fP \fI(virtual public member function)\fP + \fB[virtual]\fP \fI(virtual public member function)\fP register_callback registers event callback function - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::ios_base::failure.3 b/man/std::ios_base::failure.3 index ad6d7c42b..ef8544a27 100644 --- a/man/std::ios_base::failure.3 +++ b/man/std::ios_base::failure.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::failure 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::failure 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::failure \- std::ios_base::failure + .SH Synopsis Defined in header class failure; @@ -6,43 +9,109 @@ The class std::ios_base::failure defines an exception object that is thrown on failure by the functions in the Input/Output library. - std-ios base-failure-2003-inheritance.svg - About this image \fI(until C++11)\fP + std::ios_base::failure may be defined either as a member class of + std::ios_base or as a synonym \fI(typedef)\fP for another class with \fI(since C++17)\fP + equivalent functionality. + std-ios base-failure-2003-inheritance.svg + \fI(until C++11)\fP Inheritance diagram std-ios base-failure-inheritance.svg - About this image \fI(since C++11)\fP - + \fI(since C++11)\fP Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP + constructor constructs a new failure object with the given message + \fI(public member function)\fP + operator= replaces the failure object + \fI(public member function)\fP + what returns the explanatory string + \fI(public member function)\fP + +std::ios_base::failure::failure + + explicit failure( const std::string& message ); \fI(until C++11)\fP + explicit failure( const std::string& message, + const std::error_code& ec = \fI(since C++11)\fP + std::io_errc::stream ); + explicit failure( const char* message, \fB(1)\fP + const std::error_code& ec = \fB(2)\fP \fI(since C++11)\fP + std::io_errc::stream ); + failure( const failure& other ); \fB(3)\fP \fI(until C++11)\fP + failure( const failure& other ) noexcept; \fI(since C++11)\fP + + 1,2) Constructs the exception object using message as explanation string which can + later be retrieved using what(). + ec is used to identify the specific reason for the failure. + \fI(since C++11)\fP + 3) Copy constructor. Initialize the contents with those of other. + If *this and other both have dynamic type std::ios_base::failure then + std::strcmp(what(), other.what()) == 0. + \fI(since C++11)\fP + +.SH Parameters + + message - explanatory string + ec - error code to identify the specific reason for the failure + other - another failure to copy + +.SH Notes + + Because copying std::ios_base::failure is not permitted to throw exceptions, this + message is typically stored internally as a separately-allocated reference-counted + string. This is also why there is no constructor taking std::string&&: it would have + to copy the content anyway. - std::ios_base::failure::::failure +std::ios_base::failure::operator= - explicit failure( const std::string& message ); \fI(until C++11)\fP - explicit failure( const std::string& message, \fI(since C++11)\fP - const std::error_code& ec = std::io_errc::stream ); - explicit failure( const char* message, \fI(since C++11)\fP - const std::error_code& ec = std::io_errc::stream ); + failure& operator=( const failure& other ); \fI(until C++11)\fP + failure& operator=( const failure& other ) noexcept; \fI(since C++11)\fP - Constructs the exception object using message as explanation string which can later - be retrieved using what(). + Assigns the contents with those of other. + If *this and other both have dynamic type std::ios_base::failure then + std::strcmp(what(), other.what()) == 0 after assignment. + \fI(since C++11)\fP .SH Parameters - message - explanatory string + other - another exception object to assign with + +.SH Return value + + *this + +std::ios_base::failure::what + + virtual const char* what() const throw(); \fI(until C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. The string is + suitable for conversion and display as a std::wstring. The pointer is guaranteed to + be valid at least until the exception object from which it is obtained is destroyed, + or until a non-const member function (e.g. copy assignment operator) on the + exception object is called. + +.SH Notes + + Implementations are allowed but not required to override what(). Inherited from std::system_error .SH Member functions code returns error code - \fI(public member function of std::system_error)\fP - what returns explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::system_error)\fP + \fI(public member function of std::system_error)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::system_error)\fP Inherited from std::runtime_error @@ -50,24 +119,44 @@ Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Notes + + Before the resolution of LWG issue 331, std::ios_base::failure declared a destructor + without throw(), where std::exception::~exception() was declared with throw()^[1]. + This means the std::ios_base::failure::~failure() had a weaker exception + specification. The resolution is to remove that declaration so that the non-throwing + exception specification is kept. + + LWG issue 363 targets the same defect and its resolution is to add throw() to the + declaraion of std::ios_base::failure::~failure(). That resolution was not applied + due to the confict between the two resolutions. + + 1. ↑ The non-throwing exception specification is now applied globally across the + standard library, so the destructors of standard library classes are not + declared with throw() or noexcept. .SH Example - + // Run this code - #include #include + #include + int main() { std::ifstream f("doesn't exist"); - try { + + try + { f.exceptions(f.failbit); - } catch (const std::ios_base::failure& e) + } + catch (const std::ios_base::failure& e) { std::cout << "Caught an ios_base::failure.\\n" << "Explanatory string: " << e.what() << '\\n' @@ -75,13 +164,26 @@ Inherited from std::exception } } -.SH Output: +.SH Possible output: Caught an ios_base::failure. Explanatory string: ios_base::clear: unspecified iostream_category error Error code: iostream:1 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the constructor overload \fB(1)\fP initialized + LWG 48 C++98 the base class std::exception corresponding + with msg, but the base class does not have description removed + a matching constructor + LWG 331 C++98 std::ios_base::failure declared a removed the destructor + destructor without throw() declaration + .SH See also io_errc the IO stream error codes - \fI(C++11)\fP \fI(enum)\fP + \fI(C++11)\fP \fI(enum)\fP diff --git a/man/std::ios_base::flags.3 b/man/std::ios_base::flags.3 index ef6ccabb3..d4c129f4b 100644 --- a/man/std::ios_base::flags.3 +++ b/man/std::ios_base::flags.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::flags 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::flags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::flags \- std::ios_base::flags + .SH Synopsis fmtflags flags() const; \fB(1)\fP fmtflags flags( fmtflags flags ); \fB(2)\fP @@ -6,39 +9,40 @@ Manages format flags. 1) returns current formatting setting - 2) replaces current settings with given ones. .SH Parameters - new formatting setting. It can be a combination of the following constants: - - Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - right right adjustment (adds fill characters to the left) - internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, or hex - flags - notation if combined with fixed - fixed generate floating point types using fixed notation, or hex - notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - showbase generate a prefix indicating the numeric base for integer - output, require the currency indicator in monetary I/O - showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - skipws skip leading whitespace before certain input operations - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations + flags - new formatting setting. It can be a combination of formatting flags + constants. + + Formatting flags + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see std::left + right right adjustment (adds fill characters to the left): see std::right + internal internal adjustment (adds fill characters to the internal designated + point): see std::internal + adjustfield left | right | internal. Useful for masking operations + scientific generate floating point types using scientific notation, or hex notation + if combined with fixed: see std::scientific + fixed generate floating point types using fixed notation, or hex notation if + combined with scientific: see std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see std::boolalpha + showbase generate a prefix indicating the numeric base for integer output, + require the currency indicator in monetary I/O: see std::showbase + showpoint generate a decimal-point character unconditionally for floating-point + number output: see std::showpoint + showpos generate a + character for non-negative numeric output: see std::showpos + skipws skip leading whitespace before certain input operations: see std::skipws + unitbuf flush the output after each output operation: see std::unitbuf + uppercase replace certain lowercase letters with their uppercase + equivalents in certain output operations: see std::uppercase .SH Return value @@ -52,10 +56,9 @@ .SH See also setf sets specific format flag - \fI(public member function)\fP + \fI(public member function)\fP unsetf clears specific format flag - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::ios_base::fmtflags.3 b/man/std::ios_base::fmtflags.3 index 03b9c0474..6a3faf256 100644 --- a/man/std::ios_base::fmtflags.3 +++ b/man/std::ios_base::fmtflags.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::fmtflags 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::fmtflags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::fmtflags \- std::ios_base::fmtflags + .SH Synopsis typedef /*implementation defined*/ fmtflags; static constexpr fmtflags dec = /*implementation defined*/ @@ -6,20 +9,18 @@ static constexpr fmtflags oct = /*implementation defined*/ static constexpr fmtflags hex = /*implementation defined*/ - static constexpr fmtflags basefield = /*implementation defined (dec | oct | hex)*/ + static constexpr fmtflags basefield = dec | oct | hex; static constexpr fmtflags left = /*implementation defined*/ static constexpr fmtflags right = /*implementation defined*/ static constexpr fmtflags internal = /*implementation defined*/ - static constexpr fmtflags adjustfield = /*implementation defined (left | right | - internal)*/ + static constexpr fmtflags adjustfield = left | right | internal; static constexpr fmtflags scientific = /*implementation defined*/ static constexpr fmtflags fixed = /*implementation defined*/ - static constexpr fmtflags floatfield = /*implementation defined (scientific | - fixed)*/ + static constexpr fmtflags floatfield = scientific | fixed; static constexpr fmtflags boolalpha = /*implementation defined*/ static constexpr fmtflags showbase = /*implementation defined*/ @@ -30,63 +31,63 @@ static constexpr fmtflags uppercase = /*implementation defined*/ - Specifies available formatting flags. It is a BitmaskType, the following constants + Specifies available formatting flags. It is a BitmaskType. The following constants are defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - right right adjustment (adds fill characters to the left) + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see std::left + right right adjustment (adds fill characters to the left): see std::right internal internal adjustment (adds fill characters to the internal designated - point) - adjustfield left|right|internal. Useful for masking operations + point): see std::internal + adjustfield left | right | internal. Useful for masking operations scientific generate floating point types using scientific notation, or hex notation - if combined with fixed + if combined with fixed: see std::scientific fixed generate floating point types using fixed notation, or hex notation if - combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking operations - boolalpha insert and extract bool type in alphanumeric format + combined with scientific: see std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see std::boolalpha showbase generate a prefix indicating the numeric base for integer output, - require the currency indicator in monetary I/O + require the currency indicator in monetary I/O: see std::showbase showpoint generate a decimal-point character unconditionally for floating-point - number output - showpos generate a + character for non-negative numeric output - skipws skip leading whitespace before certain input operations - unitbuf flush the output after each output operation + number output: see std::showpoint + showpos generate a + character for non-negative numeric output: see std::showpos + skipws skip leading whitespace before certain input operations: see std::skipws + unitbuf flush the output after each output operation: see std::unitbuf uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations + equivalents in certain output operations: see std::uppercase .SH Example The following example shows several different ways to print the same result. - + // Run this code #include - + int main() { - int num = 150; - + const int num = 150; + // using fmtflags as class member constants: std::cout.setf(std::ios_base::hex, std::ios_base::basefield); std::cout.setf(std::ios_base::showbase); std::cout << num << '\\n'; - + // using fmtflags as inherited class member constants: - std::cout.setf (std::ios::hex , std::ios::basefield); + std::cout.setf (std::ios::hex, std::ios::basefield); std::cout.setf (std::ios::showbase); std::cout << num << '\\n'; - + // using fmtflags as object member constants: std::cout.setf(std::cout.hex, std::cout.basefield); std::cout.setf(std::cout.showbase); std::cout << num << '\\n'; - + // using fmtflags as a type: std::ios_base::fmtflags ff; ff = std::cout.flags(); @@ -95,7 +96,7 @@ ff |= std::cout.showbase; // set showbase std::cout.flags(ff); std::cout << num << '\\n'; - + // not using fmtflags, but using manipulators: std::cout << std::hex << std::showbase << num << '\\n'; } @@ -111,33 +112,33 @@ .SH See also flags manages format flags - \fI(public member function)\fP + \fI(public member function)\fP setf sets specific format flag - \fI(public member function)\fP + \fI(public member function)\fP unsetf clears specific format flag - \fI(public member function)\fP + \fI(public member function)\fP setbase changes the base used for integer I/O - \fI(function)\fP + \fI(function)\fP setfill changes the fill character - \fI(function template)\fP + \fI(function template)\fP fixed scientific hexfloat changes formatting used for floating-point I/O - defaultfloat \fI(function)\fP + defaultfloat \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP showbase controls whether prefix is used to indicate numeric base - noshowbase \fI(function)\fP + noshowbase \fI(function)\fP boolalpha switches between textual and numeric representation of booleans - noboolalpha \fI(function)\fP + noboolalpha \fI(function)\fP showpos controls whether the + sign used with non-negative numbers - noshowpos \fI(function)\fP + noshowpos \fI(function)\fP showpoint controls whether decimal point is always included in floating-point noshowpoint representation - \fI(function)\fP + \fI(function)\fP unitbuf controls whether output is flushed after each operation - nounitbuf \fI(function)\fP + nounitbuf \fI(function)\fP skipws controls whether leading whitespace is skipped on input - noskipws \fI(function)\fP + noskipws \fI(function)\fP uppercase controls whether uppercase characters are used with some output formats - nouppercase \fI(function)\fP + nouppercase \fI(function)\fP diff --git a/man/std::ios_base::getloc.3 b/man/std::ios_base::getloc.3 index 15d68eefa..a583b3192 100644 --- a/man/std::ios_base::getloc.3 +++ b/man/std::ios_base::getloc.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::getloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::getloc \- std::ios_base::getloc + .SH Synopsis std::locale getloc() const; @@ -10,35 +13,46 @@ .SH Return value - the locale object associated with the stream. + The locale object associated with the stream. .SH Example - + The output shown was obtained using the clang compiler. + + // Run this code - #include + #include #include #include - #include - + #include + int main() { std::wbuffer_convert> conv(std::cout.rdbuf()); std::wostream out(&conv); - + out.imbue(std::locale(out.getloc(), - new std::time_put_byname("ja_JP"))); - - std::time_t t = std::time(NULL); + new std::time_put_byname("ja_JP.utf8"))); + + std::time_t t = std::time(nullptr); out << std::put_time(std::localtime(&t), L"%A %c") << '\\n'; } -.SH Output: +.SH Possible output: + + 木曜日 2023年10月05日 19時47分58秒 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 土曜日 2013年09月14日 11時31分15秒 + DR Applied to Behavior as published Correct behavior + LWG 47 C++98 the return value was misspecified as the return corrected + value of imbue() .SH See also imbue sets locale - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::ios_base::imbue.3 b/man/std::ios_base::imbue.3 index 7881d325b..c9a380c1a 100644 --- a/man/std::ios_base::imbue.3 +++ b/man/std::ios_base::imbue.3 @@ -1,10 +1,12 @@ -.TH std::ios_base::imbue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::imbue \- std::ios_base::imbue + .SH Synopsis std::locale imbue( const std::locale& loc ); - Sets the associated locale of the stream to the given one. Before returning, each - function, registered by register_callback() is called with imbue_event as a - parameter. + Sets the associated locale of the stream to loc. Before returning, each function, + registered by register_callback() is called with imbue_event as a parameter. .SH Parameters @@ -12,18 +14,28 @@ .SH Return value - The locale object, associated with the stream before the operation + The locale object associated with the stream before the operation. .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 47 C++98 the return value was misspecified as the corrected + return value of getloc() + LWG 156 C++98 the type of loc was const std::locale corrected to const + std::locale& + .SH See also getloc returns current locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::ios_base::ios_base.3 b/man/std::ios_base::ios_base.3 index 50ffdb116..5da347ec0 100644 --- a/man/std::ios_base::ios_base.3 +++ b/man/std::ios_base::ios_base.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::ios_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::ios_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::ios_base \- std::ios_base::ios_base + .SH Synopsis private: \fI(until C++11)\fP ios_base( const ios_base& ); @@ -7,16 +10,33 @@ protected: \fB(2)\fP ios_base(); - 1) The copy constuctor is deleted: streams are not copyable - + 1) The copy constructor is + private + \fI(until C++11)\fP + deleted + \fI(since C++11)\fP: streams are not copyable. 2) The default constructor is protected: only derived classes may construct std::ios_base. The internal state is undefined after the construction. The derived - class must call basic_ios::init() to complete initialization before first use or - before destructor, otherwise the behavior is undefined. + class must call std::basic_ios::init() to complete initialization before first use + or before destructor; otherwise the behavior is undefined. .SH Notes The same applies to the constructors of the next class in the I/O hierarchy, std::basic_ios. Further-derived classes (std::istream and std::ostream) are always - constructed with a concrete streambuffer object and call basic_ios::init(), possibly - more than once, to complete initialization of their virtual base. + constructed with a concrete stream buffer object and call std::basic_ios::init(), + possibly more than once, to complete initialization of their virtual base. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 50 C++98 the copy constructor was not specified specified as private + the behavior of destroying a + LWG 220 C++98 std::ios_base the behavior is + object before calling its init() was not undefined in this case + clear + LWG 1249 C++98 initialization did not need to be also needs to be + completed before first use completed diff --git a/man/std::ios_base::iostate.3 b/man/std::ios_base::iostate.3 index 7b4ec8489..9fa7e4bbe 100644 --- a/man/std::ios_base::iostate.3 +++ b/man/std::ios_base::iostate.3 @@ -1,12 +1,15 @@ -.TH std::ios_base::iostate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::iostate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::iostate \- std::ios_base::iostate + .SH Synopsis typedef /*implementation defined*/ iostate; static constexpr iostate goodbit = 0; - static constexpr iostate badbit = /*implementation defined*/ + static constexpr iostate badbit = /* implementation defined */ - static constexpr iostate failbit = /*implementation defined*/ + static constexpr iostate failbit = /* implementation defined */ - static constexpr iostate eofbit = /*implementation defined*/ + static constexpr iostate eofbit = /* implementation defined */ Specifies stream state flags. It is a BitmaskType, the following constants are defined: @@ -48,14 +51,14 @@ failbit are set, and no input takes place. * The I/O manipulator std::ws, if it reaches the end of the stream while consuming whitespace (but, unlike the formatted input sentry, it does not set failbit in - this case) + this case). * The unformatted input functions basic_istream::read, basic_istream::get, - basic_istream::peek, and basic_istream::getline, when reaching the end of the - stream. + basic_istream::peek, basic_istream::readsome, basic_istream::ignore, and + basic_istream::getline, when reaching the end of the stream. * The discard input function basic_istream::ignore, when reaching the end of the stream before reaching the specified delimiter character. * The immediate input function basic_istream::readsome, if - basic_streambuf::in_avail returns -1 + basic_streambuf::in_avail returns -1. The following functions clear eofbit as a side-effect: @@ -63,6 +66,8 @@ * basic_istream::unget * basic_istream::seekg + Note that in nearly all situations, if eofbit is set, the failbit is set as well. + .SH The failbit The failbit is set by the following standard library functions: @@ -90,7 +95,7 @@ (technically, the overloads of num_get::get they call), if the input cannot be parsed as a valid value or if the value parsed does not fit in the destination type. - * The time input manipulator std::get_time (technically, time_get::get it calls}}, + * The time input manipulator std::get_time (technically, time_get::get it calls), if the input cannot be unambiguously parsed as a time value according to the given format string. * The currency input manipulator std::get_money (technically, money_get::get it @@ -128,20 +133,20 @@ * Formatted output functions operator<<, std::put_money, and std::put_time, if they encounter the end of the output stream before completing output. * basic_ios::init when called to initialize a stream with a null pointer for - rdbuf() + rdbuf(). * basic_istream::putback and basic_istream::unget when called on a stream with a - null rdbuf() - * basic_istream::operator>>(basic_streambuf*) when a null pointer is passed as the + null rdbuf(). + * basic_ostream::operator<<(basic_streambuf*) when a null pointer is passed as the argument. - * basic_istream::putback and basic_istream::unget if - - rdbuf()->sputbackc() or rdbuf()->sungetc() return traits::eof(). - + * basic_istream::putback and basic_istream::unget if rdbuf()->sputbackc() or + rdbuf()->sungetc() return traits::eof(). * basic_istream::sync, basic_ostream::flush, and every output function on a - unitbuf output stream, if rdbuf()->pubsync() returns -1 + unitbuf output stream, if rdbuf()->pubsync() returns -1. * Every stream I/O function if an exception is thrown by any member function of - the associated stream buffer (e.g. sbumpc(), xsputn(), sgetc(), overflow(), etc) - * ios_base::iword and ios_base::pword on failure (e.g. failure to allocate memory) + the associated stream buffer (e.g. sbumpc(), xsputn(), sgetc(), overflow(), + etc). + * ios_base::iword and ios_base::pword on failure (e.g. failure to allocate + memory). .SH Example @@ -164,6 +169,12 @@ true true false false true false true false true true true true false true true true false true -.SH Category: + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Category: * Todo no example diff --git a/man/std::ios_base::iword.3 b/man/std::ios_base::iword.3 index bec098b2c..6282f5efd 100644 --- a/man/std::ios_base::iword.3 +++ b/man/std::ios_base::iword.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::iword 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::iword 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::iword \- std::ios_base::iword + .SH Synopsis long& iword( int index ); @@ -8,13 +11,14 @@ The reference may be invalidated by any operation on this ios_base object, including another call to iword(), but the stored values are retained, so that reading from - iword(index) with the same index later will produce the same value (until the next - call to std::basic_ios::copyfmt()). The value can be used for any purpose. The index - of the element must be obtained by xalloc(), otherwise collisions with other users - of this ios_base may occur. New elements are initialized to 0. + iword(index) with the same index later will produce the same value until the next + call to std::basic_ios::copyfmt(). The value can be used for any purpose. The index + of the element must be obtained by a previous call to xalloc(), otherwise the + behavior is undefined. New elements are initialized to 0. - If allocation fails, calls std::basic_ios<>::setstate(badbit) which may throw - std::basic_ios::failure + If the function fails (possibly caused by an allocation failure) and *this is a base + class subobject of a basic_ios<> object or subobject, calls + std::basic_ios<>::setstate(badbit) which may throw std::ios_base::failure. .SH Notes @@ -36,37 +40,39 @@ .SH Example - + // Run this code #include #include - - struct Foo { + + struct Foo + { static int foo_xalloc; std::string data; + Foo(const std::string& s) : data(s) {} }; - - // allocates the iword storage for use with Foo objects + + // Allocates the iword storage for use with Foo objects int Foo::foo_xalloc = std::ios_base::xalloc(); - + // This user-defined operator<< prints the string in reverse if the iword holds 1 std::ostream& operator<<(std::ostream& os, Foo& f) { - if(os.iword(Foo::foo_xalloc) == 1) + if (os.iword(Foo::foo_xalloc) == 1) return os << std::string(f.data.rbegin(), f.data.rend()); else return os << f.data; } - + // This I/O manipulator flips the number stored in iword between 0 and 1 std::ios_base& rev(std::ios_base& os) { os.iword(Foo::foo_xalloc) = !os.iword(Foo::foo_xalloc); return os; } - + int main() { Foo f("example"); @@ -79,11 +85,25 @@ elpmaxe example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the stored value might not be the stored value is retained + LWG 36 C++98 retained if the reference is until the next call of + invalidated copyfmt() + the function set badbit by itself on badbit is set by basic_ios + LWG 41 C++98 failure, (if *this is its base class + but ios_base does not provide such subobject) + interface + .SH See also resizes the private storage if necessary and access to the void* element at pword the given index - \fI(public member function)\fP + \fI(public member function)\fP xalloc returns a program-wide unique integer that is safe to use as index to \fB[static]\fP pword() and iword() - \fI(public static member function)\fP + \fI(public static member function)\fP diff --git a/man/std::ios_base::openmode.3 b/man/std::ios_base::openmode.3 index 9236a11d5..0d704feab 100644 --- a/man/std::ios_base::openmode.3 +++ b/man/std::ios_base::openmode.3 @@ -1,38 +1,60 @@ -.TH std::ios_base::openmode 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::openmode 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::openmode \- std::ios_base::openmode + .SH Synopsis - typedef /*implementation defined*/ openmode; - static constexpr openmode app = /*implementation defined*/ + typedef /* implementation defined */ openmode; + static constexpr openmode app = /* implementation defined */; - static constexpr openmode binary = /*implementation defined*/ - static constexpr openmode in = /*implementation defined*/ - static constexpr openmode out = /*implementation defined*/ - static constexpr openmode trunc = /*implementation defined*/ + static constexpr openmode binary = /* implementation defined */; + static constexpr openmode in = /* implementation defined */; + static constexpr openmode out = /* implementation defined */; + static constexpr openmode trunc = /* implementation defined */; - static constexpr openmode ate = /*implementation defined*/ + static constexpr openmode ate = /* implementation defined */; + static constexpr openmode noreplace = /* implementation defined */; (since C++23) Specifies available file open flags. It is a BitmaskType, the following constants are defined: - Constant Explanation - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - open opens a file and configures it as the associated character sequence - \fI(public member function of std::basic_filebuf)\fP - constructor constructs a basic_stringbuf object - \fI(public member function of std::basic_stringbuf)\fP + #include + #include + #include + + int main() + { + const char* fname = "unique_name.txt"; + + // write to a temporary stream object + std::fstream(fname, std::ios::out | std::ios::trunc) << "Hi"; -.SH Category: + std::string s; + std::fstream(fname, std::ios::in) >> s; + std::cout << s << '\\n'; + } - * Todo no example +.SH Output: + + Hi + +.SH See also + + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::ios_base::operator=.3 b/man/std::ios_base::operator=.3 new file mode 100644 index 000000000..7f908db48 --- /dev/null +++ b/man/std::ios_base::operator=.3 @@ -0,0 +1,24 @@ +.TH std::ios_base::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::operator= \- std::ios_base::operator= + +.SH Synopsis + private: \fI(until C++11)\fP + ios_base& operator=( const ios_base& ); + public: \fI(since C++11)\fP + ios_base& operator=( const ios_base& ) = delete; + + The copy assignment operator is + private + \fI(until C++11)\fP + deleted + \fI(since C++11)\fP: streams are not copy-assignable. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 50 C++98 the copy assignment operator was not specified as private + specified diff --git a/man/std::ios_base::precision.3 b/man/std::ios_base::precision.3 index a6cf9e618..60c2c0935 100644 --- a/man/std::ios_base::precision.3 +++ b/man/std::ios_base::precision.3 @@ -1,14 +1,18 @@ -.TH std::ios_base::precision 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::precision 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::precision \- std::ios_base::precision + .SH Synopsis streamsize precision() const; \fB(1)\fP streamsize precision( streamsize new_precision ); \fB(2)\fP - Manages the precision (i.e. how many digits are generated) of certain numeric output - conversions. + Manages the precision (i.e. how many digits are generated) of floating point output + performed by std::num_put::do_put. 1) Returns the current precision. + 2) Sets the precision to the given one. Returns the previous precision. - 2) Sets the precision to the given one. + The default precision, as established by std::basic_ios::init, is 6. .SH Parameters @@ -16,24 +20,45 @@ .SH Return value - the precision before the call to the function + The precision before the call to the function .SH Example - + // Run this code #include + int main() { - std::cout << "The default precision is " << std::cout.precision() << '\\n'; + const double d = 12.345678901234; + std::cout << "The default precision is " << std::cout.precision() << "\\n\\n"; + std::cout << "With default precision d is " << d << '\\n'; + std::cout.precision(8); + std::cout << "With high precision d is " << d << '\\n'; } .SH Output: - The default precision is 6 + The default precision is 6 + + With default precision d is 12.3457 + With high precision d is 12.345679 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 'precision' was defined as 'the number of digits + LWG 189 C++98 after corrected + the decimal point', but it is not correct in + some cases .SH See also - width manages field width - \fI(public member function)\fP + width manages field width + \fI(public member function)\fP + setprecision changes floating-point precision + \fI(function)\fP diff --git a/man/std::ios_base::pword.3 b/man/std::ios_base::pword.3 index 8a9f0428c..b86fbac7c 100644 --- a/man/std::ios_base::pword.3 +++ b/man/std::ios_base::pword.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::pword 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::pword 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::pword \- std::ios_base::pword + .SH Synopsis void*& pword( int index ); @@ -8,13 +11,14 @@ The reference may be invalidated by any operation on this ios_base object, including another call to pword(), but the stored values are retained, so that reading from - pword(index) with the same index later will produce the same value (until the next - call to copyfmt()). The value can be used for any purpose. The index of the element - must be obtained by xalloc(), otherwise collisions with other users of this ios_base - may occur. New elements are initialized to NULL. + pword(index) with the same index later will produce the same value until the next + call to std::basic_ios::copyfmt(). The value can be used for any purpose. The index + of the element must be obtained by xalloc(), otherwise the behavior is undefined. + New elements are initialized to a null pointer. - If allocation fails, calls std::basic_ios<>::setstate(badbit) which may throw - std::basic_ios::failure + If the function fails (possibly caused by an allocation failure) and *this is a base + class subobject of a basic_ios<> object or subobject, calls + std::basic_ios<>::setstate(badbit) which may throw std::ios_base::failure. .SH Parameters @@ -35,56 +39,57 @@ .SH Example - + Uses base class pword storage for runtime type identification of derived stream objects. - + // Run this code #include - - template > - class mystream : public std::basic_ostream + + template> + class mystream : public std::basic_ostream { - public: + public: static const int xindex; - mystream(std::basic_ostream& ostr) : - std::basic_ostream(ostr.rdbuf()) + + mystream(std::basic_ostream& ostr) : + std::basic_ostream(ostr.rdbuf()) { - this->pword(xindex) = this; + this->pword(xindex) = this; } - + void myfn() { *this << "[special handling for mystream]"; } }; - - // each specialization of mystream obtains a unique index from xalloc() - template - const int mystream::xindex = std::ios_base::xalloc(); - + + // Each specialization of mystream obtains a unique index from xalloc() + template + const int mystream::xindex = std::ios_base::xalloc(); + // This I/O manipulator will be able to recognize ostreams that are mystreams // by looking up the pointer stored in pword - template - std::basic_ostream& mymanip(std::basic_ostream& os) + template + std::basic_ostream& mymanip(std::basic_ostream& os) { - if (os.pword(mystream::xindex) == &os) - static_cast&>(os).myfn(); - return os; + if (os.pword(mystream::xindex) == &os) + static_cast&>(os).myfn(); + return os; } - + int main() { std::cout << "cout, narrow-character test " << mymanip << '\\n'; - + mystream myout(std::cout); myout << "myout, narrow-character test " << mymanip << '\\n'; - + std::wcout << "wcout, wide-character test " << mymanip << '\\n'; - + mystream mywout(std::wcout); mywout << "mywout, wide-character test " << mymanip << '\\n'; } @@ -96,11 +101,25 @@ wcout, wide-character test mywout, wide-character test [special handling for mystream] + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the stored value might not be the stored value is retained + LWG 36 C++98 retained if the reference is until the next call of + invalidated copyfmt() + the function set badbit by itself on badbit is set by basic_ios + LWG 41 C++98 failure, (if *this is its base class + but ios_base does not provide such subobject) + interface + .SH See also resizes the private storage if necessary and access to the long element at iword the given index - \fI(public member function)\fP + \fI(public member function)\fP xalloc returns a program-wide unique integer that is safe to use as index to \fB[static]\fP pword() and iword() - \fI(public static member function)\fP + \fI(public static member function)\fP diff --git a/man/std::ios_base::register_callback.3 b/man/std::ios_base::register_callback.3 index 3c7c78877..3ffe33575 100644 --- a/man/std::ios_base::register_callback.3 +++ b/man/std::ios_base::register_callback.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::register_callback 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::register_callback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::register_callback \- std::ios_base::register_callback + .SH Synopsis void register_callback( event_callback function, int index ); @@ -33,24 +36,24 @@ If the same function is registered multiple times, it is called multiple times. The integer value that is stored together with the callback is typically an index - obtained from xalloc() + obtained from xalloc(). .SH Example - demonstrates the use of register_callback to update locale-dependent cached values - that are used by a custom output operator + Demonstrates the use of register_callback to update locale-dependent cached values + that are used by a custom output operator. + - // Run this code + #include #include #include - #include - - // cached locale-specific message and its hash + + // Cached locale-specific message and its hash typedef std::pair cache_t; - - // populate the cached message and its hash from the locale + + // Populate the cached message and its hash from the locale void update_cache(cache_t& cache, std::locale loc) { auto& fct = std::use_facet< std::messages >(loc); @@ -58,8 +61,8 @@ cache.first = cat < 0 ? "" : fct.get(cat, 0, 0, "Memory exhausted"); cache.second = std::hash()(cache.first); } - - // update the cache if the locale changed + + // Update the cache if the locale changed void true_callback(std::ios_base::event evt, std::ios_base& str, int idx) { if (evt == std::ios_base::imbue_event) @@ -68,43 +71,43 @@ update_cache(*ptr, str.getloc()); } } - - // registers the cache in pword() and sets up the callback + + // Registers the cache in pword() and sets up the callback struct CacheSetup { CacheSetup(std::ostream& os, std::ios_base::event_callback f, cache_t* cache) { int index = std::ostream::xalloc(); - os.pword(index) = cache; // store pointer to cache in the stream - os.register_callback(f, index); // store callback and the index to the pointer - update_cache(*cache, os.getloc()); // initialize cache + os.pword(index) = cache; // Store pointer to cache in the stream + os.register_callback(f, index); // Store callback and the index to the pointer + update_cache(*cache, os.getloc()); // Initialize cache }; }; - - // some custom class - struct S { }; - // some custom class's operator<< that needs fast access to hashed message + + // Some custom class + struct S {}; + // Some custom class's operator<< that needs fast access to hashed message std::ostream& operator<<(std::ostream& os, const S&) { - static cache_t cache; - static CacheSetup setup(os, true_callback, &cache); - return os << cache.first << " : " << cache.second; + static cache_t cache; + static CacheSetup setup(os, true_callback, &cache); + return os << cache.first << " : " << cache.second; } - + int main() { std::locale loc("en_US.utf8"); - + S s; std::cout.imbue(loc); std::cout << s << '\\n'; - + std::cout.imbue(std::locale(loc, new std::messages_byname("de_DE.utf8"))); std::cout << s << '\\n'; - + std::cout.imbue(std::locale(loc, new std::messages_byname("ja_JP.utf8"))); std::cout << s << '\\n'; - + std::cout.imbue(std::locale(loc, new std::messages_byname("ru_RU.utf8"))); std::cout << s << '\\n'; } diff --git a/man/std::ios_base::seekdir.3 b/man/std::ios_base::seekdir.3 index 4a0c4aea3..46d8a8bcd 100644 --- a/man/std::ios_base::seekdir.3 +++ b/man/std::ios_base::seekdir.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::seekdir 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::seekdir 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::seekdir \- std::ios_base::seekdir + .SH Synopsis typedef /*implementation defined*/ seekdir; static constexpr seekdir beg = /*implementation defined*/ @@ -16,9 +19,48 @@ .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream in("Hello, World!"); + std::string word1, word2, word3, word4, word5; + + in >> word1; + in.seekg(0, std::ios_base::beg); // <- rewind + in >> word2; + in.seekg(1, std::ios_base::cur); // -> seek from cur pos toward the end + in >> word3; + in.seekg(-6, std::ios_base::cur); // <- seek from cur pos (end) toward begin + in >> word4; + in.seekg(-6, std::ios_base::end); // <- seek from end toward begin + in >> word5; + + std::cout << "word1 = " << word1 << '\\n' + << "word2 = " << word2 << '\\n' + << "word3 = " << word3 << '\\n' + << "word4 = " << word4 << '\\n' + << "word5 = " << word5 << '\\n'; + } + +.SH Output: + + word1 = Hello, + word2 = Hello, + word3 = World! + word4 = World! + word5 = World! + +.SH See also - * Todo no example + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::ios_base::setf.3 b/man/std::ios_base::setf.3 index 4199bf00c..e71a45aa1 100644 --- a/man/std::ios_base::setf.3 +++ b/man/std::ios_base::setf.3 @@ -1,11 +1,14 @@ -.TH std::ios_base::setf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::setf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::setf \- std::ios_base::setf + .SH Synopsis fmtflags setf( fmtflags flags ); \fB(1)\fP fmtflags setf( fmtflags flags, fmtflags mask ); \fB(2)\fP Sets the formatting flags to specified settings. - 1) Sets the formatting flags identified by flags. Effectively the following + 1) Sets the formatting flags identified by flags. Effectively, the following operation is performed fl = fl | flags where fl defines the state of internal formatting flags. 2) Clears the formatting flags under mask, and sets the cleared flags to those @@ -15,71 +18,71 @@ .SH Parameters new formatting setting. mask defines which flags can be altered, flags - defines which flags of those to be altered should be set (others will - be cleared). Both parameters can be a combination of the following - constants: - - Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - right right adjustment (adds fill characters to the left) - internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - flags, mask - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fixed generate floating point types using fixed notation, or hex - notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - showbase generate a prefix indicating the numeric base for integer - output, require the currency indicator in monetary I/O - showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - skipws skip leading whitespace before certain input operations - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations + flags, mask - defines which flags of those to be altered should be set (others will + be cleared). Both parameters can be a combination of the formatting + flags constants + + Formatting flags + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see std::left + right right adjustment (adds fill characters to the left): see std::right + internal internal adjustment (adds fill characters to the internal designated + point): see std::internal + adjustfield left | right | internal. Useful for masking operations + scientific generate floating point types using scientific notation, or hex notation + if combined with fixed: see std::scientific + fixed generate floating point types using fixed notation, or hex notation if + combined with scientific: see std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see std::boolalpha + showbase generate a prefix indicating the numeric base for integer output, + require the currency indicator in monetary I/O: see std::showbase + showpoint generate a decimal-point character unconditionally for floating-point + number output: see std::showpoint + showpos generate a + character for non-negative numeric output: see std::showpos + skipws skip leading whitespace before certain input operations: see std::skipws + unitbuf flush the output after each output operation: see std::unitbuf + uppercase replace certain lowercase letters with their uppercase + equivalents in certain output operations: see std::uppercase .SH Return value - the formatting flags before the call to the function + The formatting flags before the call to the function. .SH Example - + // Run this code - #include #include - - const double PI = 3.1415926535; - + #include + #include + int main() { + const double PI = std::numbers::pi; const int WIDTH = 15; - - std::cout.setf(std::ios::right); //equivalent: cout << right; - std::cout << std::setw(WIDTH/2) << "radius" + + std::cout.setf(std::ios::right); // equivalent: cout << right; + std::cout << std::setw(WIDTH / 2) << "radius" << std::setw(WIDTH) << "circumference" << '\\n'; - - std::cout.setf(std::ios::fixed); - for (double radius = 1; radius <= 6; radius += 0.5) { - std::cout << std::setprecision(1) << std::setw(WIDTH/2) + + std::cout.setf(std::ios::fixed); // equivalent: cout << fixed; + for (double radius = 1; radius <= 6; radius += 0.5) + std::cout << std::setprecision(1) << std::setw(WIDTH / 2) << radius << std::setprecision(2) << std::setw(WIDTH) << (2 * PI * radius) << '\\n'; - } } .SH Output: - radius circumference + radius circumference 1.0 6.28 1.5 9.42 2.0 12.57 @@ -95,6 +98,6 @@ .SH See also flags manages format flags - \fI(public member function)\fP + \fI(public member function)\fP unsetf clears specific format flag - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::ios_base::sync_with_stdio.3 b/man/std::ios_base::sync_with_stdio.3 index 17661a630..49f099b43 100644 --- a/man/std::ios_base::sync_with_stdio.3 +++ b/man/std::ios_base::sync_with_stdio.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::sync_with_stdio 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::sync_with_stdio 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::sync_with_stdio \- std::ios_base::sync_with_stdio + .SH Synopsis static bool sync_with_stdio( bool sync = true ); @@ -6,21 +9,23 @@ after each input/output operation. The standard C++ streams are the following: std::cin, std::cout, std::cerr, - std::clog, std::wcin, std::wcout, std::wcerr and std::wclog + std::clog, std::wcin, std::wcout, std::wcerr and std::wclog. - The standard C streams are the following: stdin, stdout and stderr + The standard C streams are the following: stdin, stdout and stderr. For a standard stream str, synchronized with the C stream f, the following pairs of functions have identical effect: - 1) std::fputc(f, c) and str.rdbuf()->sputc(c) - 2) std::fgetc(f) and str.rdbuf()->sbumpc() - 3) std::ungetc(c, f) and str.rdbuf()->sputbackc(c) + 1) std::fputc(f, c) and str.rdbuf()->sputc(c). + 2) std::fgetc(f) and str.rdbuf()->sbumpc(). + 3) std::ungetc(c, f) and str.rdbuf()->sputbackc(c). + + In practice, this means that the synchronized C++ streams are unbuffered, and each + I/O operation on a C++ stream is immediately applied to the corresponding C stream's + buffer. This makes it possible to freely mix C++ and C I/O. - In practice, this means that the C++ and the C streams use the same buffer, and - therefore, can be mixed freely. In addition, synchronized C++ streams are guaranteed - to be thread-safe (individual characters output from multiple threads may - interleave, but no data races occur) + In addition, synchronized C++ streams are guaranteed to be thread-safe (individual + characters output from multiple threads may interleave, but no data races occur). If the synchronization is turned off, the C++ standard streams are allowed to buffer their I/O independently, which may be considerably faster in some cases. @@ -28,8 +33,9 @@ By default, all eight standard C++ streams are synchronized with their respective C streams. - It is implementation-defined if this function has any effect if called after some - I/O occurred on the standard stream. + If this function is called after I/O has occurred on the standard stream, the + behavior is implementation-defined: implementations range from no effect to + destroying the read buffer. .SH Parameters @@ -37,35 +43,46 @@ .SH Return value - synchronization state before the call to the function + Synchronization state before the call to the function. .SH Example - + // Run this code - #include #include - + #include + int main() { - std::cout.sync_with_stdio(false); + std::ios::sync_with_stdio(false); std::cout << "a\\n"; std::printf("b\\n"); std::cout << "c\\n"; } -.SH Output: +.SH Possible output: b a c + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unspecified \fB(1)\fP which state is actually + LWG 49 C++98 returned and both specified + \fB(2)\fP what does 'synchronized' between standard C + and C++ streams mean + .SH See also cout writes to the standard C output stream stdout - wcout (global object) + wcout (global object) cerr writes to the standard C error stream stderr, unbuffered - wcerr (global object) + wcerr (global object) clog writes to the standard C error stream stderr - wclog (global object) + wclog (global object) diff --git a/man/std::ios_base::unsetf.3 b/man/std::ios_base::unsetf.3 index 1532e7793..b347eed98 100644 --- a/man/std::ios_base::unsetf.3 +++ b/man/std::ios_base::unsetf.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::unsetf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::unsetf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::unsetf \- std::ios_base::unsetf + .SH Synopsis void unsetf( fmtflags flags ); @@ -6,35 +9,36 @@ .SH Parameters - formatting flags to unset. It can be a combination of the following - constants: - - Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - right right adjustment (adds fill characters to the left) - internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, or hex - flags - notation if combined with fixed - fixed generate floating point types using fixed notation, or hex - notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - showbase generate a prefix indicating the numeric base for integer - output, require the currency indicator in monetary I/O - showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - skipws skip leading whitespace before certain input operations - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations + flags - formatting flags to unset. It can be a combination of the formatting flags + constants. + + Formatting flags + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see std::left + right right adjustment (adds fill characters to the left): see std::right + internal internal adjustment (adds fill characters to the internal designated + point): see std::internal + adjustfield left | right | internal. Useful for masking operations + scientific generate floating point types using scientific notation, or hex notation + if combined with fixed: see std::scientific + fixed generate floating point types using fixed notation, or hex notation if + combined with scientific: see std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see std::boolalpha + showbase generate a prefix indicating the numeric base for integer output, + require the currency indicator in monetary I/O: see std::showbase + showpoint generate a decimal-point character unconditionally for floating-point + number output: see std::showpoint + showpos generate a + character for non-negative numeric output: see std::showpos + skipws skip leading whitespace before certain input operations: see std::skipws + unitbuf flush the output after each output operation: see std::unitbuf + uppercase replace certain lowercase letters with their uppercase + equivalents in certain output operations: see std::uppercase .SH Return value @@ -48,10 +52,9 @@ .SH See also flags manages format flags - \fI(public member function)\fP + \fI(public member function)\fP setf sets specific format flag - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::ios_base::width.3 b/man/std::ios_base::width.3 index 6c5f6caa1..ee256577e 100644 --- a/man/std::ios_base::width.3 +++ b/man/std::ios_base::width.3 @@ -1,13 +1,16 @@ -.TH std::ios_base::width 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::width 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::width \- std::ios_base::width + .SH Synopsis streamsize width() const; \fB(1)\fP streamsize width( streamsize new_width ); \fB(2)\fP Manages the minimum number of characters to generate on certain output operations - and the maximum number of character to generate on certain input operations. + and the maximum number of characters to generate on certain input operations. 1) Returns the current field width. - 2) Sets the field width to the given one. + 2) Sets the field width to the given one. Returns the previous field width. .SH Parameters @@ -15,24 +18,109 @@ .SH Return value - The field width before the call to the function + The field width before the call to the function. .SH Notes Some I/O functions call width\fB(0)\fP before returning, see std::setw (this results in this field having effect on the next I/O function only, and not on any subsequent - I/O) + I/O). + + The exact effects this modifier has on the input and output vary between the + individual I/O functions and are described at each operator<< and operator>> + overload page individually. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - precision manages decimal precision of floating point operations - \fI(public member function)\fP + #include + #include + #include + #include + #include + #include + using namespace std::string_view_literals; + + constexpr std::array table_header = + { + "Language"sv, "Author"sv, "Birthdate"sv, "RIP date"sv + }; + + using row_t = std::array; + using widths_t = std::array; + + constexpr std::array table_body = std::to_array + ({ + {"C", "Dennis Ritchie", "1941-09-09", "2011-10-12"}, + {"C++", "Bjarne Stroustrup", "1950-12-30"}, + {"C#", "Anders Hejlsberg", "1960-12-02"}, + {"Python", "Guido van Rossum", "1956-01-31"}, + {"Javascript", "Brendan Eich", "1961-07-04"} + }); + + constexpr widths_t calculate_column_widths(std::span table) + { + widths_t widths{}; + for (const row_t& row : table) + for (size_t i = 0; i != row.size(); ++i) + widths[i] = std::max(widths[i], row[i].size()); + return widths; + } -.SH Category: + void print_row(const row_t& row, const widths_t& widths) + { + std::cout << '|'; + for (size_t i = 0; i != row.size(); ++i) + { + std::cout << ' '; + std::cout.width(widths[i]); + std::cout << row[i] << " |"; + } + std::cout << '\\n'; + }; - * Todo no example + void print_break(const widths_t& widths) + { + const std::size_t margin = 1; + std::cout.put('+').fill('-'); + for (std::size_t w : widths) + { + std::cout.width(w + margin * 2); + std::cout << '-' << '+'; + } + std::cout.put('\\n').fill(' '); + }; + + int main() + { + constexpr widths_t widths = calculate_column_widths(table_body); + + std::cout.setf(std::ios::left, std::ios::adjustfield); + print_break(widths); + print_row(table_header, widths); + print_break(widths); + for (const row_t& row : table_body) + print_row(row, widths); + print_break(widths); + } + +.SH Output: + + +------------+-------------------+------------+------------+ + | Language | Author | Birthdate | RIP date | + +------------+-------------------+------------+------------+ + | C | Dennis Ritchie | 1941-09-09 | 2011-10-12 | + | C++ | Bjarne Stroustrup | 1950-12-30 | | + | C# | Anders Hejlsberg | 1960-12-02 | | + | Python | Guido van Rossum | 1956-01-31 | | + | Javascript | Brendan Eich | 1961-07-04 | | + +------------+-------------------+------------+------------+ + +.SH See also + + precision manages decimal precision of floating point operations + \fI(public member function)\fP + setw changes the width of the next input/output field + \fI(function)\fP diff --git a/man/std::ios_base::xalloc.3 b/man/std::ios_base::xalloc.3 index c29da7596..0dec4d962 100644 --- a/man/std::ios_base::xalloc.3 +++ b/man/std::ios_base::xalloc.3 @@ -1,4 +1,7 @@ -.TH std::ios_base::xalloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::xalloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::xalloc \- std::ios_base::xalloc + .SH Synopsis static int xalloc(); @@ -6,13 +9,10 @@ one void* elements in the private storage of std::ios_base by calling iword() and pword(). The call to xalloc does not allocate memory. - This function is thread-safe; concurrent access by multiple threads does not result - in a data race. - \fI(since C++14)\fP - -.SH Parameters + This function is thread-safe: concurrent access by multiple threads \fI(since C++11)\fP + does not result in a data race. - \fI(none)\fP + Effectively increments the next available unique index. .SH Return value @@ -20,56 +20,57 @@ .SH Example - + Uses base class pword storage for runtime type identification of derived stream objects. - + // Run this code #include - - template > - class mystream : public std::basic_ostream + + template> + class mystream : public std::basic_ostream { - public: + public: static const int xindex; - mystream(std::basic_ostream& ostr) : - std::basic_ostream(ostr.rdbuf()) + + mystream(std::basic_ostream& ostr) : + std::basic_ostream(ostr.rdbuf()) { - this->pword(xindex) = this; + this->pword(xindex) = this; } - + void myfn() { *this << "[special handling for mystream]"; } }; - - // each specialization of mystream obtains a unique index from xalloc() - template - const int mystream::xindex = std::ios_base::xalloc(); - + + // Each specialization of mystream obtains a unique index from xalloc() + template + const int mystream::xindex = std::ios_base::xalloc(); + // This I/O manipulator will be able to recognize ostreams that are mystreams // by looking up the pointer stored in pword - template - std::basic_ostream& mymanip(std::basic_ostream& os) + template + std::basic_ostream& mymanip(std::basic_ostream& os) { - if (os.pword(mystream::xindex) == &os) - static_cast&>(os).myfn(); - return os; + if (os.pword(mystream::xindex) == &os) + static_cast&>(os).myfn(); + return os; } - + int main() { std::cout << "cout, narrow-character test " << mymanip << '\\n'; - + mystream myout(std::cout); myout << "myout, narrow-character test " << mymanip << '\\n'; - + std::wcout << "wcout, wide-character test " << mymanip << '\\n'; - + mystream mywout(std::wcout); mywout << "mywout, wide-character test " << mymanip << '\\n'; } @@ -81,11 +82,19 @@ wcout, wide-character test mywout, wide-character test [special handling for mystream] + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2143 C++11 xalloc was not thread-safe made thread-safe + .SH See also resizes the private storage if necessary and access to the void* element at pword the given index - \fI(public member function)\fP + \fI(public member function)\fP resizes the private storage if necessary and access to the long element at the iword given index - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::ios_base::~ios_base.3 b/man/std::ios_base::~ios_base.3 index ee849dc3a..c50bcd9d2 100644 --- a/man/std::ios_base::~ios_base.3 +++ b/man/std::ios_base::~ios_base.3 @@ -1,10 +1,23 @@ -.TH std::ios_base::~ios_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ios_base::~ios_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ios_base::~ios_base \- std::ios_base::~ios_base + .SH Synopsis virtual ~ios_base(); Destroys the ios_base object. Before any of the member functions would yield undefined results, calls callbacks, - registered by register_callback() passing erase_event as parameter. + registered by register_callback() passing erase_event as parameter. Then, + deallocates any memory obtained. No operations on rdbuf are performed, it is not destroyed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3434 C++98 the destructor was not required to reclaim required + memory for iarray and parray diff --git a/man/std::iostream.3 b/man/std::iostream.3 deleted file mode 120000 index d53b6ea77..000000000 --- a/man/std::iostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream.3 \ No newline at end of file diff --git a/man/std::iostream.3 b/man/std::iostream.3 new file mode 100644 index 000000000..0a46e3225 --- /dev/null +++ b/man/std::iostream.3 @@ -0,0 +1,316 @@ +.TH std::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream \- std::basic_iostream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + > class basic_iostream : + public basic_istream, + + public basic_ostream + + The class template basic_iostream provides support for high level input/output + operations on streams. The supported operations include sequential reading or + writing and formatting. This functionality is implemented over the interface + provided by the std::basic_streambuf class. It is accessed through std::basic_ios + class. + + std-basic iostream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::iostream std::basic_iostream + std::wiostream std::basic_iostream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Protected member functions + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + swap exchanges the state with another basic_iostream + \fI(C++11)\fP \fI(public member function)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the member types char_type, traits_type, + LWG 271 C++98 int_type, pos_type and off_type were not defined define + (std::basic_istream and std::basic_ostream both these types + define these types, resulted in ambiguity) + +.SH See also + + * Input/output manipulators diff --git a/man/std::iostream::basic_iostream.3 b/man/std::iostream::basic_iostream.3 deleted file mode 120000 index 7d6174906..000000000 --- a/man/std::iostream::basic_iostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::basic_iostream.3 \ No newline at end of file diff --git a/man/std::iostream::basic_iostream.3 b/man/std::iostream::basic_iostream.3 new file mode 100644 index 000000000..f7d884fef --- /dev/null +++ b/man/std::iostream::basic_iostream.3 @@ -0,0 +1,34 @@ +.TH std::basic_iostream::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::basic_iostream \- std::basic_iostream::basic_iostream + +.SH Synopsis + explicit basic_iostream( std::basic_streambuf* sb ); \fB(1)\fP + basic_iostream( const basic_iostream& other ) = delete; \fB(2)\fP \fI(since C++11)\fP + protected: \fB(3)\fP \fI(since C++11)\fP + basic_iostream( basic_iostream&& other ); + + Constructs new stream object. + + 1) Initializes with streambuf sb. The base classes are initialized as + basic_istream(sb) and basic_ostream(sb). After the call + rdbuf() == sb and gcount() == 0. + 2) Copy construction is not allowed. + 3) Move constructor: move-constructs the first base class basic_istream as + basic_istream(std::move(rhs));, which in turn move-constructs and + initializes the virtual base std::basic_ios. The initialization of the other base, + basic_ostream, is implementation-defined (e.g., a protected default constructor may + be added to std::basic_ostream, which does nothing) because move-construction cannot + use rhs twice. This move constructor is protected: it is called by the move + constructors of the derived stream classes std::basic_fstream and + std::basic_stringstream before they move-construct and associate the stream buffer. + +.SH Parameters + + sb - streambuf to initialize with + other - another stream to initialize with + +.SH See also + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::iostream::iostream.3 b/man/std::iostream::iostream.3 deleted file mode 120000 index 7d6174906..000000000 --- a/man/std::iostream::iostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::basic_iostream.3 \ No newline at end of file diff --git a/man/std::iostream::iostream.3 b/man/std::iostream::iostream.3 new file mode 100644 index 000000000..f7d884fef --- /dev/null +++ b/man/std::iostream::iostream.3 @@ -0,0 +1,34 @@ +.TH std::basic_iostream::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::basic_iostream \- std::basic_iostream::basic_iostream + +.SH Synopsis + explicit basic_iostream( std::basic_streambuf* sb ); \fB(1)\fP + basic_iostream( const basic_iostream& other ) = delete; \fB(2)\fP \fI(since C++11)\fP + protected: \fB(3)\fP \fI(since C++11)\fP + basic_iostream( basic_iostream&& other ); + + Constructs new stream object. + + 1) Initializes with streambuf sb. The base classes are initialized as + basic_istream(sb) and basic_ostream(sb). After the call + rdbuf() == sb and gcount() == 0. + 2) Copy construction is not allowed. + 3) Move constructor: move-constructs the first base class basic_istream as + basic_istream(std::move(rhs));, which in turn move-constructs and + initializes the virtual base std::basic_ios. The initialization of the other base, + basic_ostream, is implementation-defined (e.g., a protected default constructor may + be added to std::basic_ostream, which does nothing) because move-construction cannot + use rhs twice. This move constructor is protected: it is called by the move + constructors of the derived stream classes std::basic_fstream and + std::basic_stringstream before they move-construct and associate the stream buffer. + +.SH Parameters + + sb - streambuf to initialize with + other - another stream to initialize with + +.SH See also + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::iostream::operator=.3 b/man/std::iostream::operator=.3 deleted file mode 120000 index 369964759..000000000 --- a/man/std::iostream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::operator=.3 \ No newline at end of file diff --git a/man/std::iostream::operator=.3 b/man/std::iostream::operator=.3 new file mode 100644 index 000000000..7259ac957 --- /dev/null +++ b/man/std::iostream::operator=.3 @@ -0,0 +1,29 @@ +.TH std::basic_iostream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::operator= \- std::basic_iostream::operator= + +.SH Synopsis + basic_iostream& operator=( const basic_iostream& other ) = delete; \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_iostream& operator=( basic_iostream&& other ); + + Assigns another stream object. + + 1) Copy assignment is not allowed. + 2) Move assigns another stream object. Effectively calls swap(rhs). This move + assignment operator is protected: it is called by the move assignment operators of + the derived stream classes std::basic_stringstream and std::basic_fstream which know + how to properly move-assign the associated stream buffers. + +.SH Parameters + + other - another stream to assign state of + +.SH Return value + + *this + +.SH See also + + constructor constructs the object + \fI(public member function)\fP diff --git a/man/std::iostream::swap.3 b/man/std::iostream::swap.3 deleted file mode 120000 index 67bc50634..000000000 --- a/man/std::iostream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::swap.3 \ No newline at end of file diff --git a/man/std::iostream::swap.3 b/man/std::iostream::swap.3 new file mode 100644 index 000000000..38aeb007c --- /dev/null +++ b/man/std::iostream::swap.3 @@ -0,0 +1,22 @@ +.TH std::basic_iostream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::swap \- std::basic_iostream::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_iostream& other ); + + Exchanges the state with another input/output stream object. Effectively calls + basic_istream::swap(other). + + This member function is protected: it is called by the swap member functions of the + derived stream classes std::basic_stringstream and std::basic_fstream, which know + how to correctly swap the associated stream buffers. + +.SH Parameters + + other - another stream to exchange the state with + +.SH Return value + + *this diff --git a/man/std::iostream::~basic_iostream.3 b/man/std::iostream::~basic_iostream.3 deleted file mode 120000 index 89c19d096..000000000 --- a/man/std::iostream::~basic_iostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::~basic_iostream.3 \ No newline at end of file diff --git a/man/std::iostream::~basic_iostream.3 b/man/std::iostream::~basic_iostream.3 new file mode 100644 index 000000000..026cd1c6b --- /dev/null +++ b/man/std::iostream::~basic_iostream.3 @@ -0,0 +1,15 @@ +.TH std::basic_iostream::~basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::~basic_iostream \- std::basic_iostream::~basic_iostream + +.SH Synopsis + virtual ~basic_iostream(); + + Destructs the input/output stream. + +.SH Notes + + This destructor does not perform any operation on the underlying stream buffer + (rdbuf()): the destructors of the derived streams such as std::basic_fstream and + std::basic_stringstream are responsible for calling the destructors of the stream + buffers. diff --git a/man/std::iostream_category.3 b/man/std::iostream_category.3 index 4bbd16c8a..27bfae387 100644 --- a/man/std::iostream_category.3 +++ b/man/std::iostream_category.3 @@ -1,7 +1,10 @@ -.TH std::iostream_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iostream_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iostream_category \- std::iostream_category + .SH Synopsis Defined in header - const std::error_category& iostream_category(); \fI(since C++11)\fP + const std::error_category& iostream_category() noexcept; \fI(since C++11)\fP Obtains a reference to the static error category object for iostream errors. The object is required to override the virtual function error_category::name() to return @@ -17,31 +20,28 @@ A reference to the static object of unspecified runtime type, derived from std::error_category. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code - #include #include - + #include + int main() { std::ifstream f("doesn't exist"); - try { + try + { f.exceptions(f.failbit); - } catch (const std::ios_base::failure& e) { + } + catch (const std::ios_base::failure& e) + { std::cout << "Caught an ios_base::failure.\\n" << "Error code: " << e.code().value() << " (" << e.code().message() << ")\\n" << "Error category: " << e.code().category().name() << '\\n'; - + } } @@ -51,9 +51,17 @@ Error code: 1 (unspecified iostream_category error) Error category: iostream + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2087 C++11 iostream_category was not declared noexcept declared noexcept + .SH See also failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP io_errc the IO stream error codes - \fI(C++11)\fP \fI(enum)\fP + \fI(C++11)\fP \fI(enum)\fP diff --git a/man/std::iota.3 b/man/std::iota.3 index 715c6c4f7..126b94c8d 100644 --- a/man/std::iota.3 +++ b/man/std::iota.3 @@ -1,97 +1,121 @@ -.TH std::iota 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iota 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iota \- std::iota + .SH Synopsis Defined in header - template< class ForwardIterator, class T > \fI(since C++11)\fP - void iota( ForwardIterator first, ForwardIterator last, T value ); + template< class ForwardIt, class T > \fI(since C++11)\fP + void iota( ForwardIt first, ForwardIt last, T value ); (constexpr since C++20) Fills the range [first, last) with sequentially increasing values, starting with value and repetitively evaluating ++value. - Equivalent operation: + Equivalent operation (assuming ++value returns the incremented value): + + *first = value; + *++first = ++value; + *++first = ++value; + *++first = ++value; + // repeats until “last” is reached + + If any of the following conditions is satisfied, the program is ill-formed: - *(d_first) = value; - *(d_first+1) = ++value; - *(d_first+2) = ++value; - *(d_first+3) = ++value; - ... + * T is not convertible to the value type of ForwardIt. + * The expression ++val is ill-formed, where val is a variable of type T. .SH Parameters first, last - the range of elements to fill with sequentially increasing values starting with value - value - initial value to store, the expression ++value must be well-formed - -.SH Return value - - \fI(none)\fP + value - initial value to store .SH Complexity - Exactly last - first increments and assignments. + Exactly std::distance(first, last) increments and assignments. .SH Possible implementation - template - void iota(ForwardIterator first, ForwardIterator last, T value) + template + constexpr // since C++20 + void iota(ForwardIt first, ForwardIt last, T value) { - while(first != last) { - *first++ = value; - ++value; - } + for (; first != last; ++first, ++value) + *first = value; } .SH Notes The function is named after the integer function ⍳ from the programming language - APL. It was one of the STL components that were not included in C++98, but - eventually made it into the standard library in C++11. + APL. It was one of the STL components that were not included in C++98, but made it + into the standard library in C++11. .SH Example - The following example applies std::random_shuffle to a vector of iterators to a - std::list since std::random_shuffle cannot be applied to an std::list directly. - std::iota is used to create the vector. + The following example applies std::shuffle to a vector of std::lists' iterators. + std::iota is used to populate containers. + - // Run this code - #include #include + #include + #include #include + #include + #include #include - #include - + + class BigData // inefficient to copy + { + int data[1024]; /* some raw data */ + public: + explicit BigData(int i = 0) { data[0] = i; /* ... */ } + operator int() const { return data[0]; } + BigData& operator=(int i) { data[0] = i; return *this; } + /* ... */ + }; + int main() { - std::list l(10); + std::list l(10); std::iota(l.begin(), l.end(), -4); - - std::vector::iterator> v(l.size()); + + std::vector::iterator> v(l.size()); std::iota(v.begin(), v.end(), l.begin()); - - std::random_shuffle(v.begin(), v.end()); - - std::cout << "Contents of the list: "; - for(auto n: l) { - std::cout << n << ' '; - } + // Vector of iterators (to original data) is used to avoid expensive copying, + // and because std::shuffle (below) cannot be applied to a std::list directly. + + std::shuffle(v.begin(), v.end(), std::mt19937{std::random_device{}()}); + + std::cout << "Original contents of the list l:\\t"; + for (const auto& n : l) + std::cout << std::setw(2) << n << ' '; std::cout << '\\n'; - - std::cout << "Contents of the list, shuffled: "; - for(auto i: v) { - std::cout << *i << ' '; - } + + std::cout << "Contents of l, viewed via shuffled v:\\t"; + for (const auto i : v) + std::cout << std::setw(2) << *i << ' '; std::cout << '\\n'; } -.SH Output: +.SH Possible output: - Contents of the list: -4 -3 -2 -1 0 1 2 3 4 5 - Contents of the list, shuffled: 0 -1 3 4 -4 1 -2 -3 2 5 + Original contents of the list l: -4 -3 -2 -1 0 1 2 3 4 5 + Contents of l, viewed via shuffled v: -1 5 -4 0 2 1 4 -2 3 -3 .SH See also - fill assigns a range of elements a certain value - \fI(function template)\fP - generate saves the result of a function in a range - \fI(function template)\fP + ranges::iota_view a view consisting of a sequence generated by repeatedly + views::iota incrementing an initial value + (C++20) \fI(class template)\fP (customization point object) + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) + assigns the results of successive function calls to every element + generate in a range + \fI(function template)\fP + ranges::generate saves the result of a function in a range + (C++20) (niebloid) + ranges::iota fills a range with successive increments of the starting value + (C++23) (niebloid) diff --git a/man/std::is_abstract.3 b/man/std::is_abstract.3 index 3b6c88ab7..c21c2a027 100644 --- a/man/std::is_abstract.3 +++ b/man/std::is_abstract.3 @@ -1,22 +1,47 @@ -.TH std::is_abstract 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_abstract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_abstract \- std::is_abstract + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_abstract; + std::is_abstract is a UnaryTypeTrait. + If T is an abstract class (that is, a non-union class that declares or inherits at - least one pure virtual function), provides the member constant value equal true. For - any other type, value is false. + least one pure virtual function), provides the member constant value equal to true. + For any other type, value is false. + + If T is an incomplete non-union class type, the behavior is undefined. + + If the program adds specializations for std::is_abstract or std::is_abstract_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_abstract_v = is_abstract::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is an abstract class type , false otherwise + value true if T is an abstract class type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,45 +51,38 @@ .SH Example - + // Run this code #include #include - - struct A { - int m; - }; - - struct B { - virtual void foo(); - }; - - struct C { - virtual void foo() = 0; - }; - + + struct A { int m; }; + static_assert(std::is_abstract_v == false); + + struct B { virtual void foo(); }; + static_assert(std::is_abstract_v == false); + + struct C { virtual void foo() = 0; }; + static_assert(std::is_abstract_v == true); + struct D : C {}; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_abstract::value << '\\n'; - std::cout << std::is_abstract::value << '\\n'; - std::cout << std::is_abstract::value << '\\n'; - std::cout << std::is_abstract::value << '\\n'; - } - -.SH Output: - - false - false - true - true + static_assert(std::is_abstract_v == true); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 the behavior was undefined if the base characteristic is + T is an incomplete union type std::false_type in this case .SH See also - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP - is_polymorphic checks if a type is polymorphic class type - \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP + is_polymorphic checks if a type is a polymorphic class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_aggregate.3 b/man/std::is_aggregate.3 new file mode 100644 index 000000000..d6f356b87 --- /dev/null +++ b/man/std::is_aggregate.3 @@ -0,0 +1,98 @@ +.TH std::is_aggregate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_aggregate \- std::is_aggregate + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + struct is_aggregate; + + std::is_aggregate is a UnaryTypeTrait. + + If T is an aggregate type, provides the member constant value equal true. For any + other type, value is false. + + If T is an incomplete type other than an array type or (possibly cv-qualified) void, + the behavior is undefined. + + If the program adds specializations for std::is_aggregate or std::is_aggregate_v, + the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_aggregate_v = is_aggregate::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is an aggregate type, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_is_aggregate 201703L \fI(C++17)\fP std::is_agregate + +.SH Example + + +// Run this code + + #include + #include + #include + + // constructs a T at the uninitialized memory pointed to by p using + // list-initialization for aggregates and non-list initialization otherwise + template + T* construct(T* p, Args&&... args) + { + if constexpr (std::is_aggregate_v) + return ::new (static_cast(p)) T{std::forward(args)...}; + else + return ::new (static_cast(p)) T(std::forward(args)...); + } + + struct A { int x, y; }; + struct B { B(int, const char*) {} }; + + int main() + { + std::aligned_union_t<1, A, B> storage; + [[maybe_unused]] A* a = construct(reinterpret_cast(&storage), 1, 2); + [[maybe_unused]] B* b = construct(reinterpret_cast(&storage), 1, "hello"); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied Behavior as published Correct behavior + to + The behavior is undefined if T is an The behavior is defined + LWG array type but regardless of the + 3823 C++17 std::remove_all_extents_t is an incompleteness of + incomplete type. std::remove_all_extents_t + as long as T is an array type. diff --git a/man/std::is_arithmetic.3 b/man/std::is_arithmetic.3 index 0311f1613..b9ff013bb 100644 --- a/man/std::is_arithmetic.3 +++ b/man/std::is_arithmetic.3 @@ -1,21 +1,46 @@ -.TH std::is_arithmetic 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_arithmetic 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_arithmetic \- std::is_arithmetic + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_arithmetic; - If T is an arithmetic type (that is, an integral type or a floating-point type), - provides the member constant value equal true. For any other type, value is false. + std::is_arithmetic is a UnaryTypeTrait. + + If T is an arithmetic type (that is, an integral type or a floating-point type) or a + cv-qualified version thereof, provides the member constant value equal to true. For + any other type, value is false. + + If the program adds specializations for std::is_arithmetic + or std::is_arithmetic_v + \fI(since C++17)\fP, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_arithmetic_v = is_arithmetic::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is an arithmetic type , false otherwise + value true if T is an arithmetic type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,53 +50,59 @@ .SH Notes - Arithmetic types are the types for which the built-in arithmetic operators (+, -, *, - /) are defined (possibly in combination with the usual arithmetic conversions) + Arithmetic types are the built-in types for which the arithmetic operators (+, -, *, + /) are defined (possibly in combination with the usual arithmetic conversions). Specializations of std::numeric_limits are provided for all arithmetic types. .SH Possible implementation - template< class T > + template struct is_arithmetic : std::integral_constant::value || std::is_floating_point::value> {}; .SH Example - + // Run this code - #include + #include + #include #include - + class A {}; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_arithmetic::value << '\\n'; - std::cout << std::is_arithmetic::value << '\\n'; - std::cout << std::is_arithmetic::value << '\\n'; - std::cout << std::is_arithmetic::value << '\\n'; - std::cout << std::is_arithmetic::value << '\\n'; - std::cout << std::is_arithmetic::value << '\\n'; - std::cout << std::is_arithmetic::value << '\\n'; - } - -.SH Output: - - false - true - false - false - true - false - false + + enum class B : int { e }; + + static_assert( + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + std::is_arithmetic_v == true and + + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false and + std::is_arithmetic_v == false + ); + + int main() {} .SH See also - is_integral checks if a type is integral type - \fI(C++11)\fP \fI(class template)\fP - is_floating_point checks if a type is floating-point type - \fI(C++11)\fP \fI(class template)\fP + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_floating_point checks if a type is a floating-point type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_array.3 b/man/std::is_array.3 index 62bbca3bb..9164283ec 100644 --- a/man/std::is_array.3 +++ b/man/std::is_array.3 @@ -1,27 +1,44 @@ -.TH std::is_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_array \- std::is_array + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_array; + std::is_array is a UnaryTypeTrait. + Checks whether T is an array type. Provides the member constant value which is equal - to true, if T is an array type . Otherwise, value is equal to false. + to true, if T is an array type. Otherwise, value is equal to false. + + If the program adds specializations for std::is_array or std::is_array_v, the + behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_array_v = is_array::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is an array type , false otherwise + value true if T is an array type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -33,48 +50,59 @@ Inherited from std::integral_constant template struct is_array : std::false_type {}; - + template struct is_array : std::true_type {}; - + template struct is_array : std::true_type {}; .SH Example - + // Run this code + #include #include #include - + class A {}; - + int main() { std::cout << std::boolalpha; std::cout << std::is_array::value << '\\n'; + std::cout << std::is_array::value << '\\n'; std::cout << std::is_array::value << '\\n'; std::cout << std::is_array::value << '\\n'; std::cout << std::is_array::value << '\\n'; + std::cout << std::is_array::value << '\\n'; std::cout << std::is_array::value << '\\n'; + std::cout << std::is_array>::value << '\\n'; } .SH Output: false true + true false false true + true + false .SH See also + is_bounded_array checks if a type is an array type of known bound + (C++20) \fI(class template)\fP + is_unbounded_array checks if a type is an array type of unknown bound + (C++20) \fI(class template)\fP rank obtains the number of dimensions of an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP extent obtains the size of an array type along a specified dimension - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_extent removes one extent from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_all_extents removes all extents from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable.3 b/man/std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable.3 index ec1468cf3..35743b1c2 100644 --- a/man/std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable.3 +++ b/man/std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable.3 @@ -1,4 +1,7 @@ -.TH std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable \- std::is_assignable,std::is_trivially_assignable,std::is_nothrow_assignable + .SH Synopsis Defined in header template< class T, class U > \fB(1)\fP \fI(since C++11)\fP @@ -9,22 +12,36 @@ struct is_nothrow_assignable; 1) If the expression std::declval() = std::declval() is well-formed in - unevaluated context, provides the member constant value equal true. For any other - type, value is false. - 2) same as \fB(1)\fP, but evaluation of the assignment expression will not call any - operation that is not trivial. - 3) same as \fB(1)\fP, but the evaluation of the assignment expression will not call any + unevaluated context, provides the member constant value equal to true. Otherwise, + value is false. Access checks are performed as if from a context unrelated to either + type. + 2) Same as \fB(1)\fP, but the evaluation of the assignment expression will not call any + operation that is not trivial. For the purposes of this check, a call to + std::declval is considered trivial and not considered an odr-use of std::declval. + 3) Same as \fB(1)\fP, but the evaluation of the assignment expression will not call any operation that is not noexcept. + If T or U is not a complete type, (possibly cv-qualified) void, or an array of + unknown bound, the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + .SH Member constants - value true if T is assignable from U , false otherwise + value true if T is assignable from U, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -32,16 +49,27 @@ value_type bool type std::integral_constant +.SH Notes + + This trait does not check anything outside the immediate context of the assignment + expression: if the use of T or U would trigger template specializations, generation + of implicitly-defined special member functions etc, and those have errors, the + actual assignment may not compile even if std::is_assignable::value compiles + and evaluates to true. + .SH Example - + // Run this code #include #include #include + struct Ex1 { int n; }; - int main() { + + int main() + { std::cout << std::boolalpha << "int is assignable from int? " << std::is_assignable::value << '\\n' // 1 = 1; wouldn't compile @@ -71,12 +99,14 @@ is_copy_assignable is_trivially_copy_assignable is_nothrow_copy_assignable checks if a type has a copy assignment operator - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_move_assignable is_trivially_move_assignable is_nothrow_move_assignable checks if a type has a move assignment operator - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP + assignable_from specifies that a type is assignable from another type + (C++20) (concept) diff --git a/man/std::is_base_of.3 b/man/std::is_base_of.3 index 29dfb3963..5682107d9 100644 --- a/man/std::is_base_of.3 +++ b/man/std::is_base_of.3 @@ -1,24 +1,38 @@ -.TH std::is_base_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_base_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_base_of \- std::is_base_of + .SH Synopsis Defined in header template< class Base, class Derived > \fI(since C++11)\fP struct is_base_of; - If Derived is derived from Base or if both are the same non-union class, provides - the member constant value equal to true. Otherwise value is false. + std::is_base_of is a BinaryTypeTrait. + + If Derived is derived from Base or if both are the same non-union class (in both + cases ignoring cv-qualification), provides the member constant value equal to true. + Otherwise value is false. + + If both Base and Derived are non-union class types, and they are not the same type + (ignoring cv-qualification), Derived should be a complete type; otherwise the + behavior is undefined. - Requires that Derived is a complete type if it is not the same type as Base and if - both Base and Derived are class types. + If the program adds specializations for std::is_base_of + or std::is_base_of_v + \fI(since C++17)\fP, the behavior is undefined. .SH Member constants - value true if Derived is derived from Base , false otherwise - \fB[static]\fP \fI(public static member constant)\fP + value true if Derived is derived from Base or if both are the same non-union + \fB[static]\fP class (in both cases ignoring cv-qualification), false otherwise + \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,30 +40,82 @@ value_type bool type std::integral_constant +.SH Notes + + std::is_base_of::value is true even if A is a private, protected, or ambiguous + base class of B. In many situations, std::is_convertible is the more + appropriate test. + + Although no class is its own base, std::is_base_of::value is true because the + intent of the trait is to model the "is-a" relationship, and T is a T. Despite that, + std::is_base_of::value is false because only classes participate in the + relationship that this trait models. + + Possible Implementation + + namespace details + { + template + std::true_type test_ptr_conv(const volatile B*); + template + std::false_type test_ptr_conv(const volatile void*); + + template + auto test_is_base_of(int) -> decltype(test_ptr_conv(static_cast(nullptr))); + template + auto test_is_base_of(...) -> std::true_type; // private or ambiguous base + } + + template + struct is_base_of : + std::integral_constant< + bool, + std::is_class::value && + std::is_class::value && + decltype(details::test_is_base_of\fB(0)\fP)::value + > {}; + .SH Example - + // Run this code - #include #include - + class A {}; - class B : A {}; - - class C {}; - - int main() - { - std::cout << std::boolalpha; - std::cout << "a2b: " << std::is_base_of::value << '\\n'; - std::cout << "b2a: " << std::is_base_of::value << '\\n'; - std::cout << "c2b: " << std::is_base_of::value << '\\n'; - } - -.SH Output: - - a2b: true - b2a: false - c2b: false + class C : B {}; + class D {}; + union E {}; + using I = int; + + static_assert + ( + std::is_base_of_v == true && + std::is_base_of_v == true && + std::is_base_of_v == true && + std::is_base_of_v != true && + std::is_base_of_v != true && + std::is_base_of_v != true && + std::is_base_of_v != true + ); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 the behavior might be undefined if the base characteristic is + Derived is an incomplete union type std::false_type in this case + +.SH See also + + is_convertible + is_nothrow_convertible checks if a type can be converted to the other type + \fI(C++11)\fP \fI(class template)\fP + (C++20) + derived_from specifies that a type is derived from another type + (C++20) (concept) diff --git a/man/std::is_bind_expression.3 b/man/std::is_bind_expression.3 index 0d9b2d15d..d29f3a694 100644 --- a/man/std::is_bind_expression.3 +++ b/man/std::is_bind_expression.3 @@ -1,11 +1,22 @@ -.TH std::is_bind_expression 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_bind_expression 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_bind_expression \- std::is_bind_expression + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_bind_expression; - If T is the type produced by a call to std::bind, this template is derived from - std::true_type. For any other type, this template is derived from std::false_type. + If T is a type produced by a call to std::bind (but not std::bind_front or + std::bind_back), this template is derived from std::true_type. For any other type + (unless user-specialized), this template is derived from std::false_type. + + A program may specialize this template for a program-defined type T to implement + UnaryTypeTrait with base characteristic of std::true_type to indicate that T should + be treated by std::bind as if it were the type of a bind subexpression: when a + bind-generated function object is invoked, a bound argument of this type will be + invoked as a function object and will be given all the unbound arguments passed to + the bind-generated object. .SH Member constants @@ -16,6 +27,8 @@ operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -23,42 +36,37 @@ value_type bool type std::integral_constant - This template may be specialized for a user-defined type T to implement - UnaryTypeTrait with BaseCharacteristic of std::true_type to indicate that T should - be treated by std::bind as if it were the type of a bind subexpression: when a - bind-generated function object is invoked, a bound argument of this type will be - invoked as a function object and will be given all the unbound arguments passed to - the bind-generated object. - .SH Example - + // Run this code + #include #include #include - #include - - struct MyBind { + + struct MyBind + { typedef int result_type; int operator()(int a, int b) const { return a + b; } }; - - namespace std { + + namespace std + { template<> struct is_bind_expression : public true_type {}; } - + int f(int n1, int n2) { - return n1+n2; + return n1 + n2; } - + int main() { - // as if bind(f, bind(MyBind::operator(), _1, _2), 2) + // as if bind(f, bind(MyBind(), _1, _2), 2) auto b = std::bind(f, MyBind(), 2); - + std::cout << "Adding 2 to the sum of 10 and 11 gives " << b(10, 11) << '\\n'; } @@ -66,7 +74,16 @@ Adding 2 to the sum of 10 and 11 gives 23 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2010 C++11 program-defined specializations could can be derived from + only be derived from std::false_type std::true_type + .SH See also bind binds one or more arguments to a function object - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::is_bounded_array.3 b/man/std::is_bounded_array.3 new file mode 100644 index 000000000..2f664b31c --- /dev/null +++ b/man/std::is_bounded_array.3 @@ -0,0 +1,106 @@ +.TH std::is_bounded_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_bounded_array \- std::is_bounded_array + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + struct is_bounded_array; + + std::is_bounded_array is a UnaryTypeTrait. + + Checks whether T is an array type of known bound. Provides the member constant value + which is equal to true, if T is an array type of known bound. Otherwise, value is + equal to false. + + If the program adds specializations for std::is_bounded_array or + std::is_bounded_array_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + inline constexpr bool is_bounded_array_v = \fI(since C++20)\fP + is_bounded_array::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is an array type of known bound, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Possible implementation + + template + struct is_bounded_array : std::false_type {}; + + template + struct is_bounded_array : std::true_type {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bounded_array_traits 201902L (C++20) std::is_bounded_array, + std::is_unbounded_array + +.SH Example + + +// Run this code + + #include + #include + + #define OUT(...) std::cout << #__VA_ARGS__ << " : " << __VA_ARGS__ << '\\n' + + class A {}; + + int main() + { + std::cout << std::boolalpha; + OUT(std::is_bounded_array_v); + OUT(std::is_bounded_array_v); + OUT(std::is_bounded_array_v); + OUT(std::is_bounded_array_v); + OUT(std::is_bounded_array_v); + OUT(std::is_bounded_array_v); + OUT(std::is_bounded_array_v); + } + +.SH Output: + + std::is_bounded_array_v : false + std::is_bounded_array_v : false + std::is_bounded_array_v : true + std::is_bounded_array_v : false + std::is_bounded_array_v : false + std::is_bounded_array_v : false + std::is_bounded_array_v : true + +.SH See also + + is_array checks if a type is an array type + \fI(C++11)\fP \fI(class template)\fP + is_unbounded_array checks if a type is an array type of unknown bound + (C++20) \fI(class template)\fP + extent obtains the size of an array type along a specified dimension + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_class.3 b/man/std::is_class.3 index ed3fb374f..820a77f13 100644 --- a/man/std::is_class.3 +++ b/man/std::is_class.3 @@ -1,28 +1,45 @@ -.TH std::is_class 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_class 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_class \- std::is_class + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_class; - Checks whether T is an class or struct type. Provides the member constant value - which is equal to true, if T is an class or struct type (but not union). Otherwise, - value is equal to false. + std::is_class is a UnaryTypeTrait. + + Checks whether T is a non-union class type. Provides the member constant value which + is equal to true, if T is a class type (but not union). Otherwise, value is equal to + false. + + If the program adds specializations for std::is_class or std::is_class_v, the + behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_class_v = is_class::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a class or struct , false otherwise + value true if T is a non-union class type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -30,37 +47,65 @@ Inherited from std::integral_constant value_type bool type std::integral_constant +.SH Possible implementation + + namespace detail + { + template + std::integral_constant::value> test(int T::*); + + template + std::false_type test(...); + } + + template + struct is_class : decltype(detail::test(nullptr)) {}; + .SH Example - + // Run this code #include #include - + struct A {}; - + class B {}; - - enum class C {}; - + + enum class E {}; + + union U { class UC {}; }; + static_assert(not std::is_class_v); + static_assert(std::is_class_v); + int main() { std::cout << std::boolalpha; - std::cout << std::is_class::value << '\\n'; - std::cout << std::is_class::value << '\\n'; - std::cout << std::is_class::value << '\\n'; - std::cout << std::is_class::value << '\\n'; + std::cout << std::is_class::value << ": A\\n"; + std::cout << std::is_class_v << ": B\\n"; + std::cout << std::is_class_v << ": B*\\n"; + std::cout << std::is_class_v << ": B&\\n"; + std::cout << std::is_class_v << ": const B\\n"; + std::cout << std::is_class::value << ": E\\n"; + std::cout << std::is_class_v << ": int\\n"; + std::cout << std::is_class_v << ": struct S (incomplete)\\n"; + std::cout << std::is_class_v << ": class C (incomplete)\\n"; } .SH Output: - true - true - false - false + true: A + true: B + false: B* + false: B& + true: const B + false: E + false: int + true: struct S (incomplete) + true: class C (incomplete) .SH See also - is_union checks if a type is an union type - \fI(C++11)\fP \fI(class template)\fP + is_union checks if a type is a union type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_compound.3 b/man/std::is_compound.3 index 26cce2abd..ca1d0464d 100644 --- a/man/std::is_compound.3 +++ b/man/std::is_compound.3 @@ -1,23 +1,46 @@ -.TH std::is_compound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_compound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_compound \- std::is_compound + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_compound; + std::is_compound is a UnaryTypeTrait. + If T is a compound type (that is, array, function, object pointer, function pointer, member object pointer, member function pointer, reference, class, union, or enumeration, including any cv-qualified variants), provides the member constant value equal true. For any other type, value is false. + If the program adds specializations for std::is_compound or std::is_compound_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_compound_v = is_compound::value; + + + +Inherited from std::integral_constant + .SH Member constants - value true if T is a compound type , false otherwise + value true if T is a compound type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -32,39 +55,60 @@ .SH Possible implementation - template< class T > + template struct is_compound : std::integral_constant::value> {}; .SH Example - + // Run this code - #include #include - - int main() { - class cls {}; - std::cout << (std::is_compound::value - ? "T is compound" - : "T is not a compound") << '\\n'; - std::cout << (std::is_compound::value - ? "T is compound" - : "T is not a compound") << '\\n'; - } + #include + + static_assert(not std::is_compound_v); + static_assert(std::is_compound_v); + static_assert(std::is_compound_v); + + void f(); + static_assert(std::is_compound_v); + static_assert(std::is_compound_v); -.SH Output: + static_assert(std::is_compound_v); - T is compound - T is not a compound + class C {}; + static_assert(std::is_compound_v); + + union U {}; + static_assert(std::is_compound_v); + + enum struct E { e }; + static_assert(std::is_compound_v); + static_assert(std::is_compound_v); + + struct S + { + int i : 8; + int j; + void foo(); + }; + static_assert(not std::is_compound_v); + static_assert(not std::is_compound_v); + static_assert(std::is_compound_v); + static_assert(std::is_compound_v); + + int main() + { + std::cout << "All checks have passed\\n"; + } .SH See also - is_fundamental checks if a type is fundamental type - \fI(C++11)\fP \fI(class template)\fP - is_scalar checks if a type is scalar type - \fI(C++11)\fP \fI(class template)\fP - is_object checks if a type is object type - \fI(C++11)\fP \fI(class template)\fP + is_fundamental checks if a type is a fundamental type + \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP + is_object checks if a type is an object type + \fI(C++11)\fP \fI(class template)\fP is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_const.3 b/man/std::is_const.3 index b594dc785..4bdc7c047 100644 --- a/man/std::is_const.3 +++ b/man/std::is_const.3 @@ -1,21 +1,44 @@ -.TH std::is_const 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_const 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_const \- std::is_const + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_const; + std::is_const is a UnaryTypeTrait. + If T is a const-qualified type (that is, const, or const volatile), provides the - member constant value equal true. For any other type, value is false. + member constant value equal to true. For any other type, value is false. + + If the program adds specializations for std::is_const or std::is_const_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_const_v = is_const::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a const-qualified type , false otherwise + value true if T is a const-qualified type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -23,6 +46,12 @@ value_type bool type std::integral_constant +.SH Notes + + If T is a reference type then is_const::value is always false. The proper way to + check a potentially-reference type for const-ness is to remove the reference: + is_const::type>. + .SH Possible implementation template struct is_const : std::false_type {}; @@ -30,25 +59,52 @@ .SH Example - + // Run this code - #include #include - + + static_assert(std::is_same_v, + "Remember, const-ness binds tightly inside pointers."); + static_assert(!std::is_const_v); + static_assert(std::is_const_v); + static_assert(!std::is_const_v); + static_assert(std::is_const_v, + "Because the pointer itself can't be changed but the int pointed at can."); + static_assert(!std::is_const_v, + "Because the pointer itself can be changed but not the int pointed at."); + static_assert(!std::is_const_v); + static_assert(std::is_const_v>); + + struct S + { + void foo() const {} + void bar() const {} + }; + int main() { - std::cout << std::boolalpha; - std::cout << std::is_const::value << '\\n'; - std::cout << std::is_const::value << '\\n'; - } + // A const member function is const in a different way: + + static_assert(!std::is_const_v, + "Because &S::foo is a pointer."); -.SH Output: + using S_mem_fun_ptr = void(S::*)() const; - false - true + S_mem_fun_ptr sfp = &S::foo; + sfp = &S::bar; // OK, can be re-pointed + static_assert(!std::is_const_v, + "Because sfp is the same pointer type and thus can be re-pointed."); + + const S_mem_fun_ptr csfp = &S::foo; + // csfp = &S::bar; // Error + static_assert(std::is_const_v, + "Because csfp cannot be re-pointed."); + } .SH See also is_volatile checks if a type is volatile-qualified - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + as_const obtains a reference to const to its argument + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::is_constant_evaluated.3 b/man/std::is_constant_evaluated.3 new file mode 100644 index 000000000..2e7468d22 --- /dev/null +++ b/man/std::is_constant_evaluated.3 @@ -0,0 +1,124 @@ +.TH std::is_constant_evaluated 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_constant_evaluated \- std::is_constant_evaluated + +.SH Synopsis + Defined in header + constexpr bool is_constant_evaluated() noexcept; \fI(since C++20)\fP + + Detects whether the function call occurs within a constant-evaluated context. + Returns true if the evaluation of the call occurs within the evaluation of an + expression or conversion that is manifestly constant-evaluated; otherwise returns + false. + + To determine whether initializers of following variables are manifestly + constant-evaluated, compilers may first perform a trial constant evaluation: + + * variables with reference type or const-qualified integral or enumeration type; + * static and thread local variables. + + It is not recommended to depend on the result in this case. + + int y = 0; + const int a = std::is_constant_evaluated() ? y : 1; + // Trial constant evaluation fails. The constant evaluation is discarded. + // Variable a is dynamically initialized with 1 + + const int b = std::is_constant_evaluated() ? 2 : y; + // Constant evaluation with std::is_constant_evaluated() == true succeeds. + // Variable b is statically initialized with 2 + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the evaluation of the call occurs within the evaluation of an expression or + conversion that is manifestly constant-evaluated; otherwise false. + +.SH Possible implementation + + // This implementation requires C++23 if consteval. + constexpr bool is_constant_evaluated() noexcept + { + if consteval + { + return true; + } + else + { + return false; + } + } + +.SH Notes + + When directly used as the condition of static_assert declaration or constexpr if + statement, std::is_constant_evaluated() always returns true. + + Because if consteval is absent in C++20, std::is_constant_evaluated is typically + implemented using a compiler extension. + + Feature-test macro Value Std Feature + __cpp_lib_is_constant_evaluated 201811L (C++20) std::is_constant_evaluated + +.SH Example + + +// Run this code + + #include + #include + #include + + constexpr double power(double b, int x) + { + if (std::is_constant_evaluated() && !(b == 0.0 && x < 0)) + { + // A constant-evaluation context: Use a constexpr-friendly algorithm. + if (x == 0) + return 1.0; + double r {1.0}; + double p {x > 0 ? b : 1.0 / b}; + for (auto u = unsigned(x > 0 ? x : -x); u != 0; u /= 2) + { + if (u & 1) + r *= p; + p *= p; + } + return r; + } + else + { + // Let the code generator figure it out. + return std::pow(b, double(x)); + } + } + + int main() + { + // A constant-expression context + constexpr double kilo = power(10.0, 3); + int n = 3; + // Not a constant expression, because n cannot be converted to an rvalue + // in a constant-expression context + // Equivalent to std::pow(10.0, double(n)) + double mucho = power(10.0, n); + + std::cout << kilo << " " << mucho << "\\n"; // (3) + } + +.SH Output: + + 1000 1000 + +.SH See also + + constexpr specifier\fI(C++11)\fP specifies that the value of a variable or function can be + computed at compile time + specifies that a function is an immediate function, that + consteval specifier(C++20) is, every call to the function must be in a constant + evaluation + constinit specifier(C++20) asserts that a variable has static initialization, i.e. + zero initialization and constant initialization diff --git a/man/std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible.3 b/man/std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible.3 index ca0ec3c11..9cdc5958a 100644 --- a/man/std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible.3 +++ b/man/std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible.3 @@ -1,4 +1,7 @@ -.TH std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible \- std::is_constructible,std::is_trivially_constructible,std::is_nothrow_constructible + .SH Synopsis Defined in header template< class T, class... Args > \fB(1)\fP \fI(since C++11)\fP @@ -8,24 +11,40 @@ template< class T, class... Args > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_constructible; - 1) If the expression T obj(arg1, arg2, ... argN); is well-formed, given rvalue - references to Args... as arguments, provides the member constant value equal true. - For any other type, value is false. - - 2) same as 1), but the constructor expression does not call any operation that is - not trivial. - - 3) same as 1), but the constructor expression is noexcept. + 1) If T is an object or reference type and the variable definition T + obj(std::declval()...); is well-formed, provides the member constant value + equal to true. In all other cases, value is false. + For the purposes of this check, the variable definition is never interpreted as a + function declaration, and the use of std::declval is not considered an odr-use. + Access checks are performed as if from a context unrelated to T and any of the types + in Args. Only the validity of the immediate context of the variable definition is + considered. + 2) Same as \fB(1)\fP, but the variable definition does not call any operation that is not + trivial. For the purposes of this check, the call to std::declval is considered + trivial. + 3) Same as \fB(1)\fP, but the variable definition is noexcept. + + If T or any type in the parameter pack Args is not a complete type, (possibly + cv-qualified) void, or an array of unknown bound, the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants - value true if T is constructible from Args... , false otherwise + value true if T is constructible from Args..., false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -33,65 +52,76 @@ value_type bool type std::integral_constant +.SH Notes + + In many implementations, is_nothrow_constructible also checks if the destructor + throws because it is effectively noexcept(T(arg)). Same applies to + is_trivially_constructible, which, in these implementations, also requires that the + destructor is trivial: GCC bug 51452 LWG issue 2116. + .SH Example - + // Run this code #include #include - - class Foo { + + class Foo + { int v1; double v2; - public: + public: Foo(int n) : v1(n), v2() {} Foo(int n, double f) noexcept : v1(n), v2(f) {} }; - - int main() { - std::cout << "Foo is ...\\n" << std::boolalpha - << "\\tTrivially-constructible from const Foo&? " - << std::is_trivially_constructible::value << '\\n' - << "\\tTrivially-constructible from int? " - << std::is_trivially_constructible::value << '\\n' - << "\\tConstructible from int? " - << std::is_constructible::value << '\\n' - << "\\tNothrow-constructible from int? " - << std::is_nothrow_constructible::value << '\\n' - << "\\tNothrow-constructible from int and double? " - << std::is_nothrow_constructible::value << '\\n'; + + int main() + { + auto is = [](bool o) { return (o ? "\\t" "is " : "\\t" "isn't "); }; + std::cout << "Foo ...\\n" + << is(std::is_trivially_constructible_v) + << "Trivially-constructible from const Foo&\\n" + << is(std::is_trivially_constructible_v) + << "Trivially-constructible from int\\n" + << is(std::is_constructible_v) + << "Constructible from int\\n" + << is(std::is_nothrow_constructible_v) + << "Nothrow-constructible from int\\n" + << is(std::is_nothrow_constructible_v) + << "Nothrow-constructible from int and double\\n"; } .SH Output: - Foo is ... - Trivially-constructible from const Foo&? true - Trivially-constructible from int? false - Constructible from int? true - Nothrow-constructible from int? false - Nothrow-constructible from int and double? true + Foo ... + is Trivially-constructible from const Foo& + isn't Trivially-constructible from int + is Constructible from int + isn't Nothrow-constructible from int + is Nothrow-constructible from int and double .SH See also is_default_constructible is_trivially_default_constructible is_nothrow_default_constructible checks if a type has a default constructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_copy_constructible is_trivially_copy_constructible is_nothrow_copy_constructible checks if a type has a copy constructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_move_constructible - is_trivially_move_constructible - is_nothrow_move_constructible checks if a type has a move constructor - \fI(C++11)\fP \fI(class template)\fP + is_trivially_move_constructible checks if a type can be constructed from an + is_nothrow_move_constructible rvalue reference + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP - uses_allocator checks if the specified type supports - \fI(C++11)\fP uses-allocator construction - \fI(class template)\fP + specifies that a variable of the type can be + constructible_from constructed from or bound to a set of argument + (C++20) types + (concept) diff --git a/man/std::is_convertible,std::is_nothrow_convertible.3 b/man/std::is_convertible,std::is_nothrow_convertible.3 new file mode 100644 index 000000000..f1d412ab9 --- /dev/null +++ b/man/std::is_convertible,std::is_nothrow_convertible.3 @@ -0,0 +1,180 @@ +.TH std::is_convertible,std::is_nothrow_convertible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_convertible,std::is_nothrow_convertible \- std::is_convertible,std::is_nothrow_convertible + +.SH Synopsis + Defined in header + template< class From, class To > \fB(1)\fP \fI(since C++11)\fP + struct is_convertible; + template< class From, class To > \fB(2)\fP \fI(since C++20)\fP + struct is_nothrow_convertible; + + 1) If the imaginary function definition To test() { return std::declval(); } + is well-formed, (that is, either std::declval() can be converted to To using + implicit conversions, or both From and To are possibly cv-qualified void), provides + the member constant value equal to true. Otherwise value is false. For the purposes + of this check, the use of std::declval in the return statement is not considered an + ODR-use. + + If To is a reference type and a temporary object would be created when + binding std::declval() to To, the return statement in the (since C++26) + imaginary function is considered well-formed, even though such binding + is ill-formed in an actual function. + + Access checks are performed as if from a context unrelated to either type. Only the + validity of the immediate context of the expression in the return statement + (including conversions to the return type) is considered. + 2) Same as \fB(1)\fP, but the conversion is also noexcept. + + If From or To is not a complete type, (possibly cv-qualified) void, or an array of + unknown bound, the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + +.SH Member constants + + value true if From is convertible to To, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Possible implementation + + is_convertible \fB(1)\fP +namespace detail +{ + template + auto test_returnable(int) -> decltype( + void(static_cast(nullptr)), std::true_type{} + ); + template + auto test_returnable(...) -> std::false_type; + + template + auto test_implicitly_convertible(int) -> decltype( + void(std::declval()(std::declval())), std::true_type{} + ); + template + auto test_implicitly_convertible(...) -> std::false_type; +} // namespace detail + +template +struct is_convertible : std::integral_constant\fB(0)\fP)::value && + decltype(detail::test_implicitly_convertible\fB(0)\fP)::value) || + (std::is_void::value && std::is_void::value) +> {}; + is_nothrow_convertible \fB(2)\fP +template +struct is_nothrow_convertible : std::conjunction, std::is_void> {}; + +template + requires + requires + { + static_cast(nullptr); + { std::declval()(std::declval()) } noexcept; + } +struct is_nothrow_convertible : std::true_type {}; + +.SH Notes + + Gives well-defined results for reference types, void types, array types, and + function types. + + Currently the standard has not specified whether the destruction of the object + produced by the conversion (either a result object or a temporary bound to a + reference) is considered as a part of the conversion. This is LWG issue 3400. + + All known implementations treat the destruction as a part of the conversion, as + proposed in P0758R1. + + Feature-test macro Value Std Feature + __cpp_lib_is_nothrow_convertible 201806L (C++20) std::is_nothrow_convertible + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + class E { public: template E(T&&) {} }; + + int main() + { + class A {}; + class B : public A {}; + class C {}; + class D { public: operator C() { return c; } C c; }; + + static_assert(std::is_convertible_v); + static_assert(!std::is_convertible_v); + static_assert(std::is_convertible_v); + static_assert(!std::is_convertible_v); + // Note that the Perfect Forwarding constructor makes the class E be + // "convertible" from everything. So, A is replaceable by B, C, D..: + static_assert(std::is_convertible_v); + + static_assert(!std::is_convertible_v); + static_assert(std::is_convertible_v); + + auto stringify = [](T x) + { + if constexpr (std::is_convertible_v or + std::is_convertible_v) + return x; + else + return std::to_string(x); + }; + + using std::operator "" s, std::operator "" sv; + const char* three = "three"; + + std::cout << std::quoted(stringify("one"s)) << ' ' + << std::quoted(stringify("two"sv)) << ' ' + << std::quoted(stringify(three)) << ' ' + << std::quoted(stringify(42)) << ' ' + << std::quoted(stringify(42.0)) << '\\n'; + } + +.SH Output: + + "one" "two" "three" "42" "42.000000" + +.SH See also + + is_base_of checks if a type is derived from the other + \fI(C++11)\fP type + \fI(class template)\fP + checks if a type is a + is_pointer_interconvertible_base_of pointer-interconvertible (initial) base of + (C++20) another type + \fI(class template)\fP + checks if objects of a type are + is_pointer_interconvertible_with_class pointer-interconvertible with the specified + (C++20) subobject of that type + \fI(function template)\fP + convertible_to specifies that a type is implicitly + (C++20) convertible to another type + (concept) diff --git a/man/std::is_convertible.3 b/man/std::is_convertible.3 deleted file mode 100644 index 20f70449b..000000000 --- a/man/std::is_convertible.3 +++ /dev/null @@ -1,61 +0,0 @@ -.TH std::is_convertible 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class From, class To > \fI(since C++11)\fP - struct is_convertible; - - If an imaginary rvalue of type From can be used in the return statement of a - function returning To, that is, if it can be converted to To using implicit - conversion, provides the member constant value equal to true. Otherwise value is - false. - -.SH Member constants - - value true if From is convertible to To , false otherwise - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH Notes - - Gives well-defined results for reference types, void types, array types, and - function types. - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - class A {}; - class B : public A {}; - class C {}; - - bool b2a = std::is_convertible::value; - bool a2b = std::is_convertible::value; - bool b2c = std::is_convertible::value; - - std::cout << std::boolalpha; - std::cout << b2a << '\\n'; - std::cout << a2b << '\\n'; - std::cout << b2c << '\\n'; - } - -.SH Output: - - true - false - false diff --git a/man/std::is_copy_assignable,std::is_trivially_copy_assignable,.3 b/man/std::is_copy_assignable,std::is_trivially_copy_assignable,.3 index 46047aeb9..34f0d27b5 100644 --- a/man/std::is_copy_assignable,std::is_trivially_copy_assignable,.3 +++ b/man/std::is_copy_assignable,std::is_trivially_copy_assignable,.3 @@ -1,4 +1,7 @@ -.TH std::is_copy_assignable,std::is_trivially_copy_assignable, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_copy_assignable,std::is_trivially_copy_assignable, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_copy_assignable,std::is_trivially_copy_assignable, \- std::is_copy_assignable,std::is_trivially_copy_assignable, + .SH Synopsis Defined in header @@ -9,15 +12,23 @@ template< class T > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_copy_assignable; - 1) Checks whether a type is CopyAssignable, i.e. has an accessible explicit or - implicit copy assignment operator. If the requirement is met, a member constant - value equal true is provided, otherwise value is false. + The value of the member constant value + Type trait T is a referenceable type T is not a + referenceable type + \fB(1)\fP std::is_assignable::value + \fB(2)\fP std::is_trivially_assignable::value + \fB(3)\fP std::is_nothrow_assignable::value + + If T is not a complete type, (possibly cv-qualified) void, or an array of unknown + bound, the behavior is undefined. - 2) Same as 1), but evaluation of the copy-assignment expression will not call any - operation that is not trivial. + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. - 3) Same as 1), but the evaluation of the copy-assignment expression will not call - any operation that is not noexcept. + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants @@ -28,6 +39,8 @@ operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -37,33 +50,44 @@ .SH Possible implementation -template< class T> -struct is_copy_assignable - : std::is_assignable< typename std::add_lvalue_reference::type, + template + struct is_copy_assignable + : std::is_assignable::type, typename std::add_lvalue_reference::type> {}; - -template< class T> -struct is_trivially_copy_assignable - : std::is_trivially_assignable< typename std::add_lvalue_reference::type, + + template + struct is_trivially_copy_assignable + : std::is_trivially_assignable::type, typename std::add_lvalue_reference::type> {}; - -template< class T> -struct is_nothrow_copy_assignable - : std::is_nothrow_assignable< typename std::add_lvalue_reference::type, + + template + struct is_nothrow_copy_assignable + : std::is_nothrow_assignable::type, typename std::add_lvalue_reference::type> {}; +.SH Notes + + The trait std::is_copy_assignable is less strict than CopyAssignable because it does + not check the type of the result of the assignment (which, for a CopyAssignable + type, must be an lvalue of type T) and does not check the semantic requirement that + the argument expression remains unchanged. It also does not check that T satisfies + MoveAssignable, which is required of all CopyAssignable types. + .SH Example - + // Run this code #include - #include #include + #include + struct Foo { int n; }; - int main() { + + int main() + { std::cout << std::boolalpha - << "Foo is trivally copy-assignable? " + << "Foo is trivially copy-assignable? " << std::is_trivially_copy_assignable::value << '\\n' << "int[2] is copy-assignable? " << std::is_copy_assignable::value << '\\n' @@ -73,21 +97,21 @@ struct is_nothrow_copy_assignable .SH Output: - Foo is trivally copy-assignable? true + Foo is trivially copy-assignable? true int[2] is copy-assignable? false int is nothrow copy-assignable? true .SH See also is_assignable - is_trivially_assignable checks if a type has a assignment operator for a + is_trivially_assignable checks if a type has an assignment operator for a is_nothrow_assignable specific argument - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_move_assignable is_trivially_move_assignable is_nothrow_move_assignable checks if a type has a move assignment operator - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP diff --git a/man/std::is_copy_constructible,std::is_trivially_copy_constructible,.3 b/man/std::is_copy_constructible,std::is_trivially_copy_constructible,.3 index 0a142bc54..401937a70 100644 --- a/man/std::is_copy_constructible,std::is_trivially_copy_constructible,.3 +++ b/man/std::is_copy_constructible,std::is_trivially_copy_constructible,.3 @@ -1,4 +1,7 @@ -.TH std::is_copy_constructible,std::is_trivially_copy_constructible, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_copy_constructible,std::is_trivially_copy_constructible, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_copy_constructible,std::is_trivially_copy_constructible, \- std::is_copy_constructible,std::is_trivially_copy_constructible, + .SH Synopsis Defined in header @@ -9,24 +12,35 @@ template< class T > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_copy_constructible; - 1) Checks whether a type is CopyConstructible, i.e. can be constructed from a const - T& argument. If the requirement is met, a member constant value equal true is - provided, otherwise value is false. + The value of the member constant value + Type trait T is a referenceable type T is not a + referenceable type + \fB(1)\fP std::is_constructible::value + \fB(2)\fP std::is_trivially_constructible::value + \fB(3)\fP std::is_nothrow_constructible::value + + If T is not a complete type, (possibly cv-qualified) void, or an array of unknown + bound, the behavior is undefined. - 2) Same as \fB(1)\fP, but the copy constructor expression does not call any operation that - is not trivial. + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. - 3) Same as \fB(1)\fP, but the copy constructor expression is noexcept. + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants - value true if T is copy-constructible , false otherwise + value true if T is copy-constructible, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -36,69 +50,85 @@ .SH Possible implementation -template -struct is_copy_constructible : - std::is_constructible::type> {}; - -template -struct is_trivially_copy_constructible : - std::is_trivially_constructible::type> {}; - -template -struct is_nothrow_copy_constructible : - std::is_nothrow_constructible::type> {}; + template + struct is_copy_constructible : + std::is_constructible::type>::type> {}; + + template + struct is_trivially_copy_constructible : + std::is_trivially_constructible::type>::type> {}; + + template + struct is_nothrow_copy_constructible : + std::is_nothrow_constructible::type>::type> {}; + +.SH Notes + + In many implementations, is_nothrow_copy_constructible also checks if the destructor + throws because it is effectively noexcept(T(arg)). Same applies to + is_trivially_copy_constructible, which, in these implementations, also requires that + the destructor is trivial: GCC bug 51452, LWG issue 2116. .SH Example - + // Run this code - #include + #include #include - - struct Ex1 { - std::string str; // member has a non-trivial copy ctor + + struct S1 + { + std::string str; // member has a non-trivial copy constructor }; - struct Ex2 { + static_assert(std::is_copy_constructible_v); + static_assert(!std::is_trivially_copy_constructible_v); + + struct S2 + { int n; - Ex2(const Ex2&) = default; // trivial and non-throwing + S2(const S2&) = default; // trivial and non-throwing + }; + static_assert(std::is_trivially_copy_constructible_v); + static_assert(std::is_nothrow_copy_constructible_v); + + struct S3 + { + S3(const S3&) = delete; // explicitly deleted }; - - int main() { - std::cout << std::boolalpha << "Ex1 is copy-constructible? " - << std::is_copy_constructible::value << '\\n' - << "Ex1 is trivially copy-constructible? " - << std::is_trivially_copy_constructible::value << '\\n' - << "Ex2 is trivially copy-constructible? " - << std::is_trivially_copy_constructible::value << '\\n' - << "Ex2 is nothrow copy-constructible? " - << std::is_nothrow_copy_constructible::value << '\\n'; - } - -.SH Output: - - Ex1 is copy-constructible? true - Ex1 is trivially copy-constructible? false - Ex2 is trivially copy-constructible? true - Ex2 is nothrow copy-constructible? true + static_assert(!std::is_copy_constructible_v); + + struct S4 + { + S4(S4&) {}; // can't bind const, hence not a copy-constructible + }; + static_assert(!std::is_copy_constructible_v); + + int main() {} .SH See also is_constructible is_trivially_constructible checks if a type has a constructor for specific is_nothrow_constructible arguments - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_default_constructible is_trivially_default_constructible is_nothrow_default_constructible checks if a type has a default constructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_move_constructible - is_trivially_move_constructible - is_nothrow_move_constructible checks if a type has a move constructor - \fI(C++11)\fP \fI(class template)\fP + is_trivially_move_constructible checks if a type can be constructed from an + is_nothrow_move_constructible rvalue reference + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP + copy_constructible specifies that an object of a type can be copy + (C++20) constructed and move constructed + (concept) diff --git a/man/std::is_corresponding_member.3 b/man/std::is_corresponding_member.3 new file mode 100644 index 000000000..deff9e17d --- /dev/null +++ b/man/std::is_corresponding_member.3 @@ -0,0 +1,72 @@ +.TH std::is_corresponding_member 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_corresponding_member \- std::is_corresponding_member + +.SH Synopsis + Defined in header + template< class S1, class S2, class M1, class M2 > + constexpr bool is_corresponding_member( M1 S1::* mp, M2 S2::* mq ) \fI(since C++20)\fP + noexcept; + + Determines whether mp and mq refer corresponding members in the common initial + sequence of S1 and S2. The program is ill-formed if either S1 or S2 is an incomplete + type. + + If either S1 or S2 is not a StandardLayoutType, or either M1 or M2 is not an object + type, or either mp or mq is equal to nullptr, the result is always false. + +.SH Parameters + + mp, mq - pointers-to-member to detect + +.SH Return value + + true if mp and mq refer corresponding members in the common initial sequence of S1 + and S2, otherwise false. + +.SH Notes + + The type of a pointer-to-member expression &S::m is not always M S::*, where m is of + type M, because m may be a member inherited from a base class of S. The template + arguments can be specified in order to avoid potentially surprising results. + +.SH Example + + +// Run this code + + #include + + struct Foo + { + int x; + double d; + }; + + struct Bar + { + int y; + double z; + }; + + struct Baz : Foo, Bar {}; // not standard-layout + + static_assert( + std::is_same_v == true && + std::is_same_v == true && + std::is_corresponding_member(&Foo::x, &Bar::y) == true && + std::is_corresponding_member(&Foo::d, &Bar::z) == true && + std::is_corresponding_member(&Baz::x, &Baz::y) == true && + std::is_corresponding_member(&Baz::x, &Baz::y) == false + ); + + int main() {} + +.SH See also + + is_standard_layout checks if a type is a standard-layout type + \fI(C++11)\fP \fI(class template)\fP + is_layout_compatible checks if two types are layout-compatible + (C++20) \fI(class template)\fP + is_member_object_pointer checks if a type is a pointer to a non-static member object + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_debugger_present.3 b/man/std::is_debugger_present.3 new file mode 100644 index 000000000..13d562d7d --- /dev/null +++ b/man/std::is_debugger_present.3 @@ -0,0 +1,48 @@ +.TH std::is_debugger_present 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_debugger_present \- std::is_debugger_present + +.SH Synopsis + Defined in header + bool is_debugger_present() noexcept; (since C++26) + + Attempts to determine if the program is being executed with debugger present. + + By default, the behavior of this function is completely implementation-defined. A + C++ program may provide the definition of this signature to replace the behavior of + this function. + +.SH Return value + + The default version returns true if, to the best of its knowledge, the program is + executed under a debugger. + +.SH Notes + + The intent of this function is allowing printing out extra output to help diagnose + problems, executing extra test code, displaying an extra user interface to help in + debugging, etc. + + This function standardizes many similar existing facilities: under_debugger from + boost.test, IsDebuggerPresent() from Win32 API, isDebuggerActive from Catch2, + IsDebuggerPresent from Unreal Engine, etc. + + Feature-test macro Value Std Feature + __cpp_lib_debugging 202311L (C++26) Debugging support library + 202403L (C++26) Replaceable std::is_debugger_present + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + breakpoint pauses the running program when called + (C++26) \fI(function)\fP + breakpoint_if_debugging calls std::breakpoint if std::is_debugger_present returns + (C++26) true + \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::is_default_constructible,std::is_trivially_default_constructible,.3 b/man/std::is_default_constructible,std::is_trivially_default_constructible,.3 index 2fd8007d5..226474d75 100644 --- a/man/std::is_default_constructible,std::is_trivially_default_constructible,.3 +++ b/man/std::is_default_constructible,std::is_trivially_default_constructible,.3 @@ -1,4 +1,7 @@ -.TH std::is_default_constructible,std::is_trivially_default_constructible, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_default_constructible,std::is_trivially_default_constructible, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_default_constructible,std::is_trivially_default_constructible, \- std::is_default_constructible,std::is_trivially_default_constructible, + .SH Synopsis Defined in header @@ -9,24 +12,33 @@ template< class T > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_default_constructible; - 1) Checks whether a type is DefaultConstructible, i.e. has an accessible explicit or - implicit default constructor. If the requirement is met, a member constant value - equal true is provided, otherwise value is false. + 1) Provides the member constant value equal to std::is_constructible::value. + 2) Provides the member constant value equal to + std::is_trivially_constructible::value. + 3) Provides the member constant value equal to + std::is_nothrow_constructible::value. + + If T is not a complete type, (possibly cv-qualified) void, or an array of unknown + bound, the behavior is undefined. - 2) Same as 1), but the constructor expression does not call any operation that is - not trivial. + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. - 3) Same as 1), but the constructor expression is noexcept. + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants - value true if T is default-constructible , false otherwise + value true if T is default-constructible, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -36,66 +48,72 @@ .SH Possible implementation - template< class T> + template struct is_default_constructible : std::is_constructible {}; - - template< class T> + + template struct is_trivially_default_constructible : std::is_trivially_constructible {}; - - template< class T> + + template struct is_nothrow_default_constructible : std::is_nothrow_constructible {}; +.SH Notes + + In many implementations, std::is_nothrow_default_constructible also checks if the + destructor throws because it is effectively noexcept(T()). Same applies to + std::is_trivially_default_constructible, which, in these implementations, also + requires that the destructor is trivial: GCC bug 51452, LWG issue 2116. + + std::is_default_constructible does not test that T x; would compile; it attempts + direct-initialization with an empty argument list (see std::is_constructible). Thus, + std::is_default_constructible_v and std::is_default_constructible_v are true. + .SH Example - + // Run this code - #include + #include #include - - struct Ex1 { - std::string str; // member has a non-trivial default ctor + + struct S1 + { + std::string str; // member has a non-trivial default constructor }; - struct Ex2 { + static_assert(std::is_default_constructible_v == true); + static_assert(std::is_trivially_default_constructible_v == false); + + struct S2 + { int n; - Ex2() = default; // trivial and non-throwing + S2() = default; // trivial and non-throwing }; - - int main() { - std::cout << std::boolalpha << "Ex1 is default-constructible? " - << std::is_default_constructible::value << '\\n' - << "Ex1 is trivially default-constructible? " - << std::is_trivially_default_constructible::value << '\\n' - << "Ex2 is trivially default-constructible? " - << std::is_trivially_default_constructible::value << '\\n' - << "Ex2 is nothrow default-constructible? " - << std::is_nothrow_default_constructible::value << '\\n'; - } - -.SH Output: - - Ex1 is default-constructible? true - Ex1 is trivially default-constructible? false - Ex2 is trivially default-constructible? true - Ex2 is nothrow default-constructible? true + static_assert(std::is_trivially_default_constructible_v == true); + static_assert(std::is_nothrow_default_constructible_v == true); + + int main() {} .SH See also is_constructible is_trivially_constructible checks if a type has a constructor for specific is_nothrow_constructible arguments - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_copy_constructible is_trivially_copy_constructible is_nothrow_copy_constructible checks if a type has a copy constructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_move_constructible - is_trivially_move_constructible - is_nothrow_move_constructible checks if a type has a move constructor - \fI(C++11)\fP \fI(class template)\fP + is_trivially_move_constructible checks if a type can be constructed from an rvalue + is_nothrow_move_constructible reference + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP + default_initializable specifies that an object of a type can be default + (C++20) constructed + (concept) diff --git a/man/std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible.3 b/man/std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible.3 index 62d086928..67182df7e 100644 --- a/man/std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible.3 +++ b/man/std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible.3 @@ -1,4 +1,7 @@ -.TH std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible \- std::is_destructible,std::is_trivially_destructible,std::is_nothrow_destructible + .SH Synopsis Defined in header template< class T > \fB(1)\fP \fI(since C++11)\fP @@ -8,23 +11,26 @@ template< class T > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_destructible; - 1) If an imaginary struct containing a member object of type T has a - non-deleted destructor, provides the member constant value equal true. \fI(until C++14)\fP - For any other type, value is false. - 1) If T is a reference type, provides the member constant value equal - true - - If T is an incomplete type (including void) or a function type, value - equals false. \fI(since C++14)\fP + 1) If T is a reference type, provides the member constant value equal to true. + If T is (possibly cv-qualified) void, a function type, or an array of unknown bound, + value equals false. + If T is an object type, then, for the type U that is + std::remove_all_extents::type, if the expression std::declval().~U() is + well-formed in unevaluated context, value equals true. Otherwise, value equals + false. + 2) Same as \fB(1)\fP and additionally std::remove_all_extents::type is either a + non-class type or a class type with a trivial destructor. + 3) Same as \fB(1)\fP, but the destructor is noexcept. - If T is an object type, then, for the type U equal - std::remove_all_extents::type, if the expression - std::declval().~U() is well-formed in unevaluated context, value - equals true. Otherwise, value equals false. + If T is not a complete type, (possibly cv-qualified) void, or an array of unknown + bound, the behavior is undefined. - 2) same as 1), but the destructor does not call any operation that is not trivial. + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. - 3) same as 1), but the destructor is noexcept. + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants @@ -35,6 +41,8 @@ operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -54,42 +62,63 @@ .SH Example - + // Run this code #include #include #include - struct Foo { - std::string str; - ~Foo() noexcept {}; + + struct Foo + { + std::string str; + ~Foo() noexcept {}; }; - struct Bar { + + struct Bar + { ~Bar() = default; }; - int main() { + + int main() + { std::cout << std::boolalpha << "std::string is destructible? " << std::is_destructible::value << '\\n' + << "Foo is trivially destructible? " + << std::is_trivially_destructible_v << '\\n' << "Foo is nothrow destructible? " - << std::is_nothrow_destructible::value << '\\n' - << "Bar is trivally destructible? " - << std::is_trivially_destructible::value << '\\n'; + << std::is_nothrow_destructible() << '\\n' + << "Bar is trivially destructible? " + << std::is_trivially_destructible{} << '\\n'; } .SH Output: std::string is destructible? true + Foo is trivially destructible? false Foo is nothrow destructible? true - Bar is trivally destructible? true + Bar is trivially destructible? true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2049 C++11 the specification was incompletable because of made complete + the imaginary wrapping struct .SH See also is_constructible is_trivially_constructible is_nothrow_constructible checks if a type has a constructor for specific arguments - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP has_virtual_destructor checks if a type has a virtual destructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + destructible specifies that an object of the type can be destroyed + (C++20) (concept) + destructor releases claimed resources diff --git a/man/std::is_empty.3 b/man/std::is_empty.3 index 7f2858694..40eaed5e0 100644 --- a/man/std::is_empty.3 +++ b/man/std::is_empty.3 @@ -1,23 +1,48 @@ -.TH std::is_empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_empty \- std::is_empty + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_empty; + std::is_empty is a UnaryTypeTrait. + If T is an empty type (that is, a non-union class type with no non-static data members other than bit-fields of size 0, no virtual functions, no virtual base - classes, and no non-empty base classes), provides the member constant value equal + classes, and no non-empty base classes), provides the member constant value equal to true. For any other type, value is false. + If T is an incomplete non-union class type, the behavior is undefined. + + If the program adds specializations for std::is_empty or std::is_empty_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_empty_v = is_empty::value; + + + +Inherited from std::integral_constant + .SH Member constants - value true if T is an empty class type , false otherwise + value true if T is an empty class type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -27,44 +52,65 @@ .SH Notes - sizeof(T) always returns 1 if T is empty, but inheriting from empty base classes - usually does not increase the size of a class due to empty base optimization. + Inheriting from empty base classes usually does not increase the size of a class due + to empty base optimization. std::is_empty and all other type traits are empty classes. .SH Example - + // Run this code #include #include - + struct A {}; - - struct B { - int m; - }; - - struct C { - virtual ~C(); + static_assert(std::is_empty_v == true); + + struct B { int m; }; + static_assert(std::is_empty_v == false); + + struct C { static int m; }; + static_assert(std::is_empty_v == true); + + struct D { virtual ~D(); }; + static_assert(std::is_empty_v == false); + + union E {}; + static_assert(std::is_empty_v == false); + + struct F { [[no_unique_address]] E e; }; + + struct G + { + int:0; + // C++ standard allow "as a special case, an unnamed bit-field with a width of zero + // specifies alignment of the next bit-field at an allocation unit boundary. + // Only when declaring an unnamed bit-field may the width be zero." }; - + static_assert(std::is_empty_v); // holds only unnamed bit-fields of zero width + int main() { std::cout << std::boolalpha; - std::cout << std::is_empty::value << '\\n'; - std::cout << std::is_empty::value << '\\n'; - std::cout << std::is_empty::value << '\\n'; + std::cout << "F: " << std::is_empty_v << '\\n'; // the result is ABI-dependent } -.SH Output: +.SH Possible output: + + F: true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - true - false - false + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 the behavior was undefined if the base characteristic is + T is an incomplete union type std::false_type in this case .SH See also - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_enum.3 b/man/std::is_enum.3 index 37dbbc955..ecbc9eb5f 100644 --- a/man/std::is_enum.3 +++ b/man/std::is_enum.3 @@ -1,27 +1,44 @@ -.TH std::is_enum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_enum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_enum \- std::is_enum + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_enum; + std::is_enum is a UnaryTypeTrait. + Checks whether T is an enumeration type. Provides the member constant value which is - equal to true, if T is an enumeration type . Otherwise, value is equal to false. + equal to true, if T is an enumeration type. Otherwise, value is equal to false. + + If the program adds specializations for std::is_enum or std::is_enum_v, the behavior + is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_enum_v = is_enum::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is an enumeration type , false otherwise + value true if T is an enumeration type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -31,39 +48,32 @@ Inherited from std::integral_constant .SH Example - + // Run this code - #include #include - - class A {}; - + + struct A { enum E {}; }; + static_assert(std::is_enum_v == false); + static_assert(std::is_enum_v == true); + enum E {}; - + static_assert(std::is_enum_v == true); + enum class Ec : int {}; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_enum::value << '\\n'; - std::cout << std::is_enum::value << '\\n'; - std::cout << std::is_enum::value << '\\n'; - std::cout << std::is_enum::value << '\\n'; - } - -.SH Output: - - false - true - true - false + static_assert(std::is_enum_v == true); + + static_assert(std::is_enum_v == false); + + int main() {} .SH See also - is_void checks if a type is void - \fI(C++11)\fP \fI(class template)\fP - is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP - is_arithmetic checks if a type is arithmetic type - \fI(C++11)\fP \fI(class template)\fP + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP + is_scoped_enum checks if a type is a scoped enumeration type + (C++23) \fI(class template)\fP diff --git a/man/std::is_eq,std::is_neq,std::is_lt,std::is_gt,std::is_lteq,std::is_gteq.3 b/man/std::is_eq,std::is_neq,std::is_lt,std::is_gt,std::is_lteq,std::is_gteq.3 new file mode 100644 index 000000000..c27281554 --- /dev/null +++ b/man/std::is_eq,std::is_neq,std::is_lt,std::is_gt,std::is_lteq,std::is_gteq.3 @@ -0,0 +1,46 @@ +.TH std::is_eq,std::is_neq,std::is_lt,std::is_gt,std::is_lteq,std::is_gteq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_eq,std::is_neq,std::is_lt,std::is_gt,std::is_lteq,std::is_gteq \- std::is_eq,std::is_neq,std::is_lt,std::is_gt,std::is_lteq,std::is_gteq + +.SH Synopsis + Defined in header + constexpr bool is_eq( std::partial_ordering cmp ) noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool is_neq( std::partial_ordering cmp ) noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool is_lt( std::partial_ordering cmp ) noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr bool is_lteq( std::partial_ordering cmp ) noexcept; \fB(4)\fP \fI(since C++20)\fP + constexpr bool is_gt( std::partial_ordering cmp ) noexcept; \fB(5)\fP \fI(since C++20)\fP + constexpr bool is_gteq( std::partial_ordering cmp ) noexcept; \fB(6)\fP \fI(since C++20)\fP + + These functions take a result of 3-way comparison and convert it to the result of + one of the six relational operators + + Specifically, these functions return + + 1) cmp == 0 + 2) cmp != 0 + 3) cmp < 0 + 4) cmp <= 0 + 5) cmp > 0 + 6) cmp >= 0 + +.SH Parameters + + cmp - result of 3-way comparison + +.SH Return value + + bool result of the corresponding relational operation + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + partial_ordering the result type of 3-way comparison that supports all 6 operators, + (C++20) is not substitutable, and allows incomparable values + \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::is_error_code_enum.3 b/man/std::is_error_code_enum.3 index 47318c42f..68a1adc31 100644 --- a/man/std::is_error_code_enum.3 +++ b/man/std::is_error_code_enum.3 @@ -1,34 +1,16 @@ -.TH std::is_error_code_enum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T > \fI(since C++11)\fP - struct is_error_code_enum; - - If T is an error code enumeration, this template provides the member constant value - equal true. For any other type, value is false. - - This template may be specialized for a user-defined type to indicate that the type - is eligible for std::error_code and std::error_condition automatic conversions. - - The following classes of the standard library are an error code enum: - - * std::io_errc - * std::future_errc. +.TH std::is_error_code_enum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_error_code_enum \- std::is_error_code_enum -.SH Member constants - - value true if T is an error code enum, false otherwise - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP +.SH Synopsis + Defined in header + template<> \fI(since C++11)\fP + struct is_error_code_enum : std::true_type; -.SH Member types + Specifies that std::future_errc is an error code enum. This enables std::error_code + automatic conversions. - Type Definition - value_type bool - type std::integral_constant +.SH See also - . + is_error_code_enum identifies a class as an error_code enumeration + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_error_code_enum.3 b/man/std::is_error_code_enum.3 deleted file mode 100644 index ee57de6e3..000000000 --- a/man/std::is_error_code_enum.3 +++ /dev/null @@ -1,61 +0,0 @@ -.TH std::is_error_code_enum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< > \fI(since C++11)\fP - struct is_error_code_enum : public std::true_type { }; - - This specialization of std::is_error_code_enum informs other library components that - values of type std::io_errc are enumerations that hold error codes, which makes them - implicitly convertible and assignable to objects of type std::error_code. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH Example - - The comparison between e.code() and std::io_errc::stream compiles because - std::is_error_code_enum::value == true - - -// Run this code - - #include - #include - int main() - { - std::ifstream f("doesn't exist"); - try { - f.exceptions(f.failbit); - } catch (const std::ios_base::failure& e) { - std::cout << "Caught an ios_base::failure.\\n"; - if(e.code() == std::io_errc::stream) - std::cout << "The error code is std::io_errc::stream\\n"; - } - } - -.SH Output: - - Caught an ios_base::failure. - The error code is std::io_errc::stream - -.SH See also - - is_error_code_enum identifies a class as an error_code enumeration - \fI(C++11)\fP \fI(class template)\fP - error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP - io_errc the IO stream error codes - \fI(C++11)\fP \fI(enum)\fP diff --git a/man/std::is_error_condition_enum.3 b/man/std::is_error_condition_enum.3 index 31580412b..4dd79baab 100644 --- a/man/std::is_error_condition_enum.3 +++ b/man/std::is_error_condition_enum.3 @@ -1,26 +1,26 @@ -.TH std::is_error_condition_enum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_error_condition_enum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_error_condition_enum \- std::is_error_condition_enum + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - struct is_error_condition_enum; - - If T is an error condition enum, this template provides the member constant value - equal true. For any other type, value is false. + template<> \fI(since C++11)\fP + struct is_error_condition_enum : std::true_type; - This template may be specialized for a user-defined type to indicate that the type - is eligible for std::error_code and std::error_condition automatic conversions. - - The following class of the standard library is an error condition enum: std::errc. + Specifies that std::errc is an error condition enum. This enables implicit + conversion to std::error_condition. .SH Member constants - value true if T is an error condition enum, false otherwise + value true \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -28,4 +28,7 @@ value_type bool type std::integral_constant - . +.SH See also + + is_error_condition_enum identifies an enumeration as an std::error_condition + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_error_condition_enum.3 b/man/std::is_error_condition_enum.3 deleted file mode 100644 index 7004a39a3..000000000 --- a/man/std::is_error_condition_enum.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH std::is_error_condition_enum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++11)\fP - struct is_error_condition_enum : std::true_type; - - Specifies that std::errc is an error condition enum. This enables std::error_code - and std::error_condition automatic conversions. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - is_error_condition_enum identifies an enumeration as an std::error_condition - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_error_condition_enum.3 b/man/std::is_error_condition_enum.3 deleted file mode 100644 index cae52d65c..000000000 --- a/man/std::is_error_condition_enum.3 +++ /dev/null @@ -1,13 +0,0 @@ -.TH std::is_error_condition_enum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++11)\fP - struct is_error_condition_enum : std::true_type; - - Specifies that std::future_errc is an error condition enum. This enables - std::error_code and std::error_condition automatic conversions. - -.SH See also - - is_error_condition_enum identifies an enumeration as an std::error_condition - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_execution_policy.3 b/man/std::is_execution_policy.3 new file mode 100644 index 000000000..d39ed9ec6 --- /dev/null +++ b/man/std::is_execution_policy.3 @@ -0,0 +1,70 @@ +.TH std::is_execution_policy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_execution_policy \- std::is_execution_policy + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + struct is_execution_policy; + + Checks whether T is a standard or implementation-defined execution policy type. + + Provides the member constant value which is equal to true, if T is a standard + execution policy type, or an implementation-defined execution policy type. + Otherwise, value is equal to false. + + If the program adds specializations for std::is_execution_policy or + std::is_execution_policy_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper template + + Defined in header + template< class T > + inline constexpr bool is_execution_policy_v = \fI(since C++17)\fP + std::is_execution_policy::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is a standard or implementation-defined execution policy type, + \fB[static]\fP false otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH See also + + sequenced_policy + parallel_policy + parallel_unsequenced_policy + unsequenced_policy execution policy types + \fI(C++17)\fP \fI(class)\fP + \fI(C++17)\fP + \fI(C++17)\fP + (C++20) + seq + par + par_unseq + unseq global execution policy objects + \fI(C++17)\fP (constant) + \fI(C++17)\fP + \fI(C++17)\fP + (C++20) diff --git a/man/std::is_final.3 b/man/std::is_final.3 index b70d2633e..82684ab85 100644 --- a/man/std::is_final.3 +++ b/man/std::is_final.3 @@ -1,21 +1,47 @@ -.TH std::is_final 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_final 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_final \- std::is_final + .SH Synopsis Defined in header template< class T > \fI(since C++14)\fP struct is_final; - If T is a final class (that is, a class declared with the final specifier), provides - the member constant value equal true. For any other type, value is false. + std::is_final is a UnaryTypeTrait. + + If T is a final class, provides the member constant value equal true. For any other + type, value is false. + + If T is an incomplete class type, the behavior is undefined. + + If the program adds specializations for std::is_final + or std::is_final_v + \fI(since C++17)\fP, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_final_v = is_final::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a final class type , false otherwise + value true if T is a final class type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,23 +51,41 @@ .SH Notes - Final classes cannot be used as base classes. + std::is_final is introduced by the resolution of LWG issue 2112. + + A union can be declared final (and std::is_final will detect that), even though + unions cannot be used as bases in any case. - A union can be marked final (and std::is_final will detect that), even though unions - cannot be used as bases in any case. + Feature-test macro Value Std Feature + __cpp_lib_is_final 201402L \fI(C++14)\fP std::is_final .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP - is_polymorphic checks if a type is polymorphic class type - \fI(C++11)\fP \fI(class template)\fP + class A {}; + static_assert(std::is_final_v == false); -.SH Category: + class B final {}; + static_assert(std::is_final_v == true); + + union U final + { + int x; + double d; + }; + static_assert(std::is_final_v == true); + + int main() + { + } + +.SH See also - * Todo no example + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP + is_polymorphic checks if a type is a polymorphic class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_floating_point.3 b/man/std::is_floating_point.3 index 932e166c2..46025ffac 100644 --- a/man/std::is_floating_point.3 +++ b/man/std::is_floating_point.3 @@ -1,28 +1,49 @@ -.TH std::is_floating_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_floating_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_floating_point \- std::is_floating_point + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_floating_point; + std::is_floating_point is a UnaryTypeTrait. + Checks whether T is a floating-point type. Provides the member constant value which - is equal to true, if T is the type float, double, long double, including any - cv-qualified variants. Otherwise, value is equal to false. + is equal to true, if T is the type float, double, long double + , or any extended floating-point types (std::float16_t, std::float32_t, + std::float64_t, std::float128_t, or std::bfloat16_t) + (since C++23), including any cv-qualified variants. Otherwise, value is equal to + false. + + If the program adds specializations for std::is_floating_point or + std::is_floating_point_v, the behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > + inline constexpr bool is_floating_point_v = \fI(since C++17)\fP + is_floating_point::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a floating-point type , false otherwise + value true if T is a floating-point type (possibly cv-qualified), false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -32,43 +53,59 @@ Inherited from std::integral_constant .SH Possible implementation -template< class T > -struct is_floating_point : std::integral_constant< - bool, - std::is_same::type>::value || - std::is_same::type>::value || - std::is_same::type>::value - > {}; + template + struct is_floating_point + : std::integral_constant< + bool, + // Note: standard floating-point types + std::is_same::type>::value + || std::is_same::type>::value + || std::is_same::type>::value + // Note: extended floating-point types (C++23, if supported) + || std::is_same::type>::value + || std::is_same::type>::value + || std::is_same::type>::value + || std::is_same::type>::value + || std::is_same::type>::value + > {}; .SH Example - + // Run this code #include #include - + class A {}; - + int main() { std::cout << std::boolalpha; - std::cout << std::is_floating_point::value << '\\n'; - std::cout << std::is_floating_point::value << '\\n'; - std::cout << std::is_floating_point::value << '\\n'; + std::cout << " A: " << std::is_floating_point::value << '\\n'; + std::cout << " float: " << std::is_floating_point::value << '\\n'; + std::cout << " float&: " << std::is_floating_point::value << '\\n'; + std::cout << " double: " << std::is_floating_point::value << '\\n'; + std::cout << "double&: " << std::is_floating_point::value << '\\n'; + std::cout << " int: " << std::is_floating_point::value << '\\n'; } .SH Output: - false - true - false + A: false + float: true + float&: false + double: true + double&: false + int: false .SH See also - is_iec559 identifies the IEC 559/IEEE 754 floating-point types - \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP - is_integral checks if a type is integral type - \fI(C++11)\fP \fI(class template)\fP - is_arithmetic checks if a type is arithmetic type - \fI(C++11)\fP \fI(class template)\fP + is_iec559 identifies the IEC 559/IEEE 754 floating-point types + \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + floating_point specifies that a type is a floating-point type + (C++20) (concept) diff --git a/man/std::is_function.3 b/man/std::is_function.3 index deab27e34..11642a096 100644 --- a/man/std::is_function.3 +++ b/man/std::is_function.3 @@ -1,28 +1,46 @@ -.TH std::is_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_function \- std::is_function + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_function; - Checks whether T is a function type (not std::function). Provides the member - constant value which is equal to true, if T is a function type. Otherwise, value is - equal to false. + std::is_function is a UnaryTypeTrait. + + Checks whether T is a function type. Types like std::function, lambdas, classes with + overloaded operator() and pointers to functions don't count as function types. + Provides the member constant value which is equal to true, if T is a function type. + Otherwise, value is equal to false. + + If the program adds specializations for std::is_function or std::is_function_v, the + behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_function_v = is_function::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a function type , false otherwise + value true if T is a function type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -30,54 +48,179 @@ Inherited from std::integral_constant value_type bool type std::integral_constant +.SH Notes + + std::is_function can be implemented in much simpler ways. Implementations similar to + the following one are used by new versions of libc++, libstdc++ and MS STL: + + template + struct is_function : std::integral_constant< + bool, + !std::is_const::value && !std::is_reference::value + > {}; + + The implementation shown below is for pedagogical purposes, since it exhibits the + myriad kinds of function types. + .SH Possible implementation // primary template template - struct is_function : std::false_type { }; - + struct is_function : std::false_type {}; + // specialization for regular functions template struct is_function : std::true_type {}; - + // specialization for variadic functions such as std::printf template struct is_function : std::true_type {}; + // specialization for function types that have cv-qualifiers + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + + // specialization for function types that have ref-qualifiers + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + + // specializations for noexcept versions of all the above (C++17 and later) + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + template + struct is_function : std::true_type {}; + .SH Example - + // Run this code - #include + #include #include - - struct A {}; - - int f() + + int f(); + static_assert(std::is_function_v); + + static_assert(std::is_function_v); + static_assert(!std::is_function_v); + static_assert(!std::is_function_v); + static_assert(!std::is_function_v>); + + struct O { void operator()() {} }; + static_assert(std::is_function_v); + + struct A { - return 1; - } - + static int foo(); + int fun() const&; + }; + static_assert(!std::is_function_v); + static_assert(std::is_function_v); + static_assert(!std::is_function_v); + + template + struct PM_traits {}; + template + struct PM_traits { using member_type = U; }; + int main() { - std::cout << std::boolalpha; - std::cout << std::is_function::value << '\\n'; - std::cout << std::is_function::value << '\\n'; - std::cout << std::is_function::value << '\\n'; - std::cout << std::is_function::value << '\\n'; + using T = PM_traits::member_type; // T is int() const& + static_assert(std::is_function_v); } -.SH Output: - - false - true - true - false - .SH See also - is_object checks if a type is object type - \fI(C++11)\fP \fI(class template)\fP - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP + is_invocable + is_invocable_r checks if a type can be invoked (as if by std::invoke) with + is_nothrow_invocable the given argument types + is_nothrow_invocable_r \fI(class template)\fP + \fI(C++17)\fP + is_object checks if a type is an object type + \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_fundamental.3 b/man/std::is_fundamental.3 index d801b69ff..4386dc6f1 100644 --- a/man/std::is_fundamental.3 +++ b/man/std::is_fundamental.3 @@ -1,21 +1,44 @@ -.TH std::is_fundamental 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_fundamental 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_fundamental \- std::is_fundamental + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_fundamental; + std::is_fundamental is a UnaryTypeTrait. + If T is a fundamental type (that is, arithmetic type, void, or nullptr_t), provides the member constant value equal true. For any other type, value is false. + If the program adds specializations for std::is_fundamental or + std::is_fundamental_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_fundamental_v = is_fundamental::value; + + + +Inherited from std::integral_constant + .SH Member constants - value true if T is a fundamental type , false otherwise + value true if T is a fundamental type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,52 +48,47 @@ .SH Possible implementation - template< class T> + template struct is_fundamental - : std::integral_constant< + : std::integral_constant< bool, std::is_arithmetic::value || - std::is_void::value || + std::is_void::value || std::is_same::type>::value + // you can also use 'std::is_null_pointer::value' instead in C++14 > {}; .SH Example - + // Run this code - #include #include - + + static_assert(std::is_fundamental_v == true); + static_assert(std::is_fundamental_v == false); + static_assert(std::is_fundamental_v == false); + static_assert(std::is_fundamental_v == true); + static_assert(std::is_fundamental_v == false); + static_assert(std::is_fundamental_v == true); + static_assert(std::is_fundamental_v == false); + static_assert(std::is_fundamental_v == false); + static_assert(std::is_fundamental_v == true); + static_assert(std::is_fundamental_v> == false); + class A {}; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_fundamental::value << '\\n'; - std::cout << std::is_fundamental::value << '\\n'; - std::cout << std::is_fundamental::value << '\\n'; - std::cout << std::is_fundamental::value << '\\n'; - std::cout << std::is_fundamental::value << '\\n'; - std::cout << std::is_fundamental::value << '\\n'; - std::cout << std::is_fundamental::value << '\\n'; - } - -.SH Output: - - false - true - false - false - true - false - false + static_assert(std::is_fundamental_v == false); + static_assert(std::is_fundamental_v::value_type>); + + int main() {} .SH See also - is_compound checks if a type is compound type - \fI(C++11)\fP \fI(class template)\fP - is_arithmetic checks if a type is arithmetic type - \fI(C++11)\fP \fI(class template)\fP - is_void checks if a type is void - \fI(C++11)\fP \fI(class template)\fP + is_compound checks if a type is a compound type + \fI(C++11)\fP \fI(class template)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_void checks if a type is void + \fI(C++11)\fP \fI(class template)\fP + is_null_pointer checks if a type is std::nullptr_t + \fI(C++14)\fP \fI(class template)\fP diff --git a/man/std::is_heap.3 b/man/std::is_heap.3 index 6f2e265ba..9ebb5d422 100644 --- a/man/std::is_heap.3 +++ b/man/std::is_heap.3 @@ -1,87 +1,147 @@ -.TH std::is_heap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_heap \- std::is_heap + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP \fI(since C++11)\fP - bool is_heap( RandomIt first, RandomIt last ); - template< class RandomIt, class Compare > \fB(2)\fP \fI(since C++11)\fP - bool is_heap( RandomIt first, RandomIt last, Compare comp ); + template< class RandomIt > \fB(1)\fP \fI(since C++11)\fP + bool is_heap( RandomIt first, RandomIt last ); (constexpr since C++20) + template< class ExecutionPolicy, class RandomIt > + + bool is_heap( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last ); + template< class RandomIt, class Compare > \fI(since C++11)\fP + bool is_heap( RandomIt first, RandomIt last, Compare \fB(3)\fP (constexpr since C++20) + comp ); + template< class ExecutionPolicy, class RandomIt, class + Compare > + + bool is_heap( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP - Checks if the elements in range [first, last) are a max heap. + RandomIt first, RandomIt last, Compare + comp ); - The first version of is_heap uses operator< to compare elements, whereas the second - uses the given comparison function comp. + Checks whether [first, last) is a heap. + + 1) The heap property to be checked is with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) The heap property to be checked is with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first, last - the range of elements to examine - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the range to be checked + policy - the execution policy to use. See execution policy for details. + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. + - + Compare must meet the requirements of Compare. .SH Return value - true if the range is max heap, false otherwise. + true if the range is a heap with respect to the corresponding comparator, false + otherwise. .SH Complexity - Linear in the distance between first and last + Given \\(\\scriptsize N\\)N as std::distance(first, last): -.SH Notes + 1,2) \\(\\scriptsize O(N)\\)O(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) \\(\\scriptsize O(N)\\)O(N) applications of the comparison function comp. - A max heap is a range of elements [f,l) that has the following properties: +.SH Exceptions - * *f is the largest element in the range - * a new element can be added using std::push_heap() - * the first element can be removed using std::pop_heap() + The overloads with a template parameter named ExecutionPolicy report errors as + follows: - The actual arrangement of the elements is implementation defined. + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Example - + // Run this code - #include #include - + #include + #include + #include + int main() { - std::vector v { 3, 1, 4, 1, 5, 9 }; - - std::cout << "initially, v: "; - for (auto i : v) std::cout << i << ' '; + std::vector v{3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5, 8, 9, 7, 9}; + + std::cout << "initially, v:\\n"; + for (const auto& i : v) + std::cout << i << ' '; std::cout << '\\n'; - - if (!std::is_heap(v.begin(), v.end())) { + + if (!std::is_heap(v.begin(), v.end())) + { std::cout << "making heap...\\n"; std::make_heap(v.begin(), v.end()); } - - std::cout << "after make_heap, v: "; - for (auto i : v) std::cout << i << ' '; + + std::cout << "after make_heap, v:\\n"; + for (auto t{1U}; const auto& i : v) + std::cout << i << (std::has_single_bit(++t) ? " | " : " "); std::cout << '\\n'; } .SH Output: - initially, v: 3 1 4 1 5 9 + initially, v: + 3 1 4 1 5 9 2 6 5 3 5 8 9 7 9 making heap... - after make_heap, v: 9 5 4 1 1 3 + after make_heap, v: + 9 | 6 9 | 5 5 9 7 | 1 1 3 5 8 3 4 2 | .SH See also - is_heap_until finds the largest subrange that is a max heap - \fI(C++11)\fP \fI(function template)\fP + is_heap_until finds the largest subrange that is a max heap + \fI(C++11)\fP \fI(function template)\fP + make_heap creates a max heap out of a range of elements + \fI(function template)\fP + push_heap adds an element to a max heap + \fI(function template)\fP + pop_heap removes the largest element from a max heap + \fI(function template)\fP + sort_heap turns a max heap into a range of elements sorted in ascending order + \fI(function template)\fP + ranges::is_heap checks if the given range is a max heap + (C++20) (niebloid) diff --git a/man/std::is_heap_until.3 b/man/std::is_heap_until.3 index 82c6f4078..7c8574e6b 100644 --- a/man/std::is_heap_until.3 +++ b/man/std::is_heap_until.3 @@ -1,81 +1,126 @@ -.TH std::is_heap_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_heap_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_heap_until \- std::is_heap_until + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP \fI(since C++11)\fP - RandomIt is_heap_until( RandomIt first, RandomIt last ); - template< class RandomIt, class Compare > - RandomIt is_heap_until( RandomIt first, RandomIt last, Compare \fB(2)\fP \fI(since C++11)\fP - comp ); + template< class RandomIt > \fB(1)\fP \fI(since C++11)\fP + RandomIt is_heap_until( RandomIt first, RandomIt last ); (constexpr since C++20) + template< class ExecutionPolicy, class RandomIt > + + RandomIt is_heap_until( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last ); + template< class RandomIt, class Compare > \fI(since C++11)\fP + RandomIt is_heap_until( RandomIt first, RandomIt last, \fB(3)\fP (constexpr since C++20) + Compare comp ); + template< class ExecutionPolicy, class RandomIt, class + Compare > + + RandomIt is_heap_until( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last, + Compare comp ); Examines the range [first, last) and finds the largest range beginning at first - which is a max heap. The first version of the function uses operator< to compare the - elements, the second uses the given comparison function comp. + which is a heap. + + 1) The heap property to be checked is with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) The heap property to be checked is with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first, last - the range of elements to examine - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the range of elements to examine + policy - the execution policy to use. See execution policy for details. + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. + - + Compare must meet the requirements of Compare. .SH Return value - The upper bound of the largest range beginning at first which is a max heap. That - is, the last iterator it for which range [first, it) is a max heap. + The last iterator it for which range [first, it) is a heap. .SH Complexity - Linear in the distance between first and last + Given \\(\\scriptsize N\\)N as std::distance(first, last): -.SH Notes + 1,2) \\(\\scriptsize O(N)\\)O(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) \\(\\scriptsize O(N)\\)O(N) applications of the comparison function comp. - A max heap is a range of elements [f,l) that has the following properties: +.SH Exceptions - * *f is the largest element in the range - * a new element can be added using std::push_heap() - * the first element can be removed using std::pop_heap() + The overloads with a template parameter named ExecutionPolicy report errors as + follows: - The actual arrangement of the elements is implementation defined. + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Example - + // Run this code - #include #include - + #include + #include + int main() { - std::vector v { 3, 1, 4, 1, 5, 9 }; - + std::vector v{3, 1, 4, 1, 5, 9}; + std::make_heap(v.begin(), v.end()); - + // probably mess up the heap v.push_back(2); v.push_back(6); - + auto heap_end = std::is_heap_until(v.begin(), v.end()); - - std::cout << "all of v: "; - for (auto i : v) std::cout << i << ' '; + + std::cout << "all of v: "; + for (const auto& i : v) + std::cout << i << ' '; std::cout << '\\n'; - + std::cout << "only heap: "; - for (auto i = v.begin(); i != heap_end; ++i) std::cout << *i << ' '; + for (auto i = v.begin(); i != heap_end; ++i) + std::cout << *i << ' '; std::cout << '\\n'; } @@ -86,5 +131,16 @@ .SH See also - is_heap checks if the given range is a max heap - \fI(C++11)\fP \fI(function template)\fP + is_heap checks if the given range is a max heap + \fI(C++11)\fP \fI(function template)\fP + make_heap creates a max heap out of a range of elements + \fI(function template)\fP + push_heap adds an element to a max heap + \fI(function template)\fP + pop_heap removes the largest element from a max heap + \fI(function template)\fP + turns a max heap into a range of elements sorted in ascending + sort_heap order + \fI(function template)\fP + ranges::is_heap_until finds the largest subrange that is a max heap + (C++20) (niebloid) diff --git a/man/std::is_implicit_lifetime.3 b/man/std::is_implicit_lifetime.3 new file mode 100644 index 000000000..7f84b95b5 --- /dev/null +++ b/man/std::is_implicit_lifetime.3 @@ -0,0 +1,76 @@ +.TH std::is_implicit_lifetime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_implicit_lifetime \- std::is_implicit_lifetime + +.SH Synopsis + Defined in header + template< class T > (since C++23) + struct is_implicit_lifetime; + + std::is_implicit_lifetime is a UnaryTypeTrait. + + If T is an implicit-lifetime type, provides the member constant value equal to true. + For any other type, value is false. + + The behavior is undefined if T is an incomplete type other than an array type or + (possibly cv-qualified) void. + + If the program adds specializations for std::is_implicit_lifetime or + std::is_implicit_lifetime_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + inline constexpr bool is_implicit_lifetime_v = (since C++23) + is_implicit_lifetime::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is an implicit-lifetime type, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_is_implicit_lifetime 202302L (C++23) std::is_implicit_lifetime + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP + is_array checks if a type is an array type + \fI(C++11)\fP \fI(class template)\fP + is_aggregate checks if a type is an aggregate type + \fI(C++17)\fP \fI(class template)\fP + start_lifetime_as implicitly creates objects in given storage with the object + start_lifetime_as_array representation reused + (C++23) \fI(function template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::is_integral.3 b/man/std::is_integral.3 index cfbc176de..00acb8dc9 100644 --- a/man/std::is_integral.3 +++ b/man/std::is_integral.3 @@ -1,29 +1,48 @@ -.TH std::is_integral 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_integral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_integral \- std::is_integral + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_integral; + std::is_integral is a UnaryTypeTrait. + Checks whether T is an integral type. Provides the member constant value which is - equal to true, if T is the type bool, char, char16_t, char32_t, wchar_t, short, int, - long, long long, or any implementation-defined extended integer types, including any - signed, unsigned, and cv-qualified variants. Otherwise, value is equal to false. + equal to true, if T is the type bool, char + , char8_t + \fI(since C++20)\fP, char16_t, char32_t, wchar_t, short, int, long, long long, or any + implementation-defined extended integer types, including any signed, unsigned, and + cv-qualified variants. Otherwise, value is equal to false. + + If the program adds specializations for std::is_integral or std::is_integral_v, the + behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_integral_v = is_integral::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is an integral type , false otherwise + value true if T is an integral type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -31,35 +50,65 @@ Inherited from std::integral_constant value_type bool type std::integral_constant +.SH Possible implementation + + // Note: this implementation uses C++20 facilities + template + struct is_integral : std::bool_constant< + requires (T t, T* p, void (*f)(T)) // T* parameter excludes reference types + { + reinterpret_cast(t); // Exclude class types + f\fB(0)\fP; // Exclude enumeration types + p + t; // Exclude everything not yet excluded but integral types + }> {}; + .SH Example - + // Run this code - #include #include - + + static_assert + ( + std::is_integral_v == false && + std::is_integral_v == false && + std::is_integral_v == true && + std::is_integral_v == true && + std::is_integral_v == true && + std::is_integral_v == true + ); + class A {}; - - int main() + static_assert(std::is_integral_v == false); + + struct B { int x:4; }; + static_assert(std::is_integral_v == false); + using BF = decltype(B::x); // bit-field's type + static_assert(std::is_integral_v == true); + + enum E : int {}; + static_assert(std::is_integral_v == false); + + template + constexpr T same(T i) { - std::cout << std::boolalpha; - std::cout << std::is_integral::value << '\\n'; - std::cout << std::is_integral::value << '\\n'; - std::cout << std::is_integral::value << '\\n'; + static_assert(std::is_integral::value, "Integral required."); + return i; } + static_assert(same('"') == 042); -.SH Output: - - false - false - true + int main() {} .SH See also + integral specifies that a type is an integral type + (C++20) (concept) is_integer identifies integer types - \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP - is_floating_point checks if a type is floating-point type - \fI(C++11)\fP \fI(class template)\fP - is_arithmetic checks if a type is arithmetic type - \fI(C++11)\fP \fI(class template)\fP + \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP + is_floating_point checks if a type is a floating-point type + \fI(C++11)\fP \fI(class template)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_enum checks if a type is an enumeration type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_invocable,std::is_invocable_r,std::is_nothrow_invocable,.3 b/man/std::is_invocable,std::is_invocable_r,std::is_nothrow_invocable,.3 new file mode 100644 index 000000000..9339d40a8 --- /dev/null +++ b/man/std::is_invocable,std::is_invocable_r,std::is_nothrow_invocable,.3 @@ -0,0 +1,103 @@ +.TH std::is_invocable,std::is_invocable_r,std::is_nothrow_invocable, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_invocable,std::is_invocable_r,std::is_nothrow_invocable, \- std::is_invocable,std::is_invocable_r,std::is_nothrow_invocable, + +.SH Synopsis + + Defined in header + template< class Fn, class... ArgTypes > \fB(1)\fP \fI(since C++17)\fP + struct is_invocable; + template< class R, class Fn, class... ArgTypes > \fB(2)\fP \fI(since C++17)\fP + struct is_invocable_r; + template< class Fn, class... ArgTypes > \fB(3)\fP \fI(since C++17)\fP + struct is_nothrow_invocable; + template< class R, class Fn, class... ArgTypes > \fB(4)\fP \fI(since C++17)\fP + struct is_nothrow_invocable_r; + + 1) Determines whether INVOKE(std::declval(), std::declval()...) is + well formed when treated as an unevaluated operand. + 2) Determines whether INVOKE(std::declval(), std::declval()...) is + well formed when treated as an unevaluated operand. + 3) Determines whether INVOKE(std::declval(), std::declval()...) is + well formed when treated as an unevaluated operand, and is known not to throw any + exceptions. + 4) Determines whether INVOKE(std::declval(), std::declval()...) is + well formed when treated as an unevaluated operand, and is known not to throw any + exceptions. + + If Fn, R or any type in the parameter pack ArgTypes is not a complete type, + (possibly cv-qualified) void, or an array of unknown bound, the behavior is + undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + +.SH Member constants + + true if (for overload \fB(1)\fP) INVOKE(std::declval(), + value std::declval()...) is well formed when treated as an unevaluated + \fB[static]\fP operand, false otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_is_invocable 201703L \fI(C++17)\fP std::is_invocable, std::invoke_result + +.SH Examples + + +// Run this code + + #include + + auto func2(char) -> int (*)() + { + return nullptr; + } + + int main() + { + static_assert(std::is_invocable_v); + static_assert(not std::is_invocable_v); + static_assert(std::is_invocable_r_v); + static_assert(not std::is_invocable_r_v); + static_assert(std::is_invocable_r_v); + static_assert(not std::is_invocable_r_v); + static_assert(std::is_invocable_r_v); + static_assert(not std::is_invocable_r_v); + } + +.SH See also + + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP + result_of deduces the result type of invoking a callable object with + invoke_result a set of arguments + \fI(C++11)\fP(removed in C++20) \fI(class template)\fP + \fI(C++17)\fP + declval obtains a reference to its argument for use in unevaluated + \fI(C++11)\fP context + \fI(function template)\fP + invocable specifies that a callable type can be invoked with a given + regular_invocable set of argument types + (C++20) (concept) diff --git a/man/std::is_layout_compatible.3 b/man/std::is_layout_compatible.3 new file mode 100644 index 000000000..0b654eae3 --- /dev/null +++ b/man/std::is_layout_compatible.3 @@ -0,0 +1,110 @@ +.TH std::is_layout_compatible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_layout_compatible \- std::is_layout_compatible + +.SH Synopsis + Defined in header + template< class T, class U > \fI(since C++20)\fP + struct is_layout_compatible; + + If T and U are layout-compatible types, provides the member constant value equal to + true. Otherwise value is false. + + Every type is layout-compatible with its any cv-qualified versions, even if it is + not an object type. + + If T or U is not a complete type, (possibly cv-qualified) void, or an array of + unknown bound, the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for std::is_layout_compatible or + std::is_layout_compatible_v, the behavior is undefined. + +.SH Member constants + + value true if T and U are layout-compatible, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + A signed integer type and its unsigned counterpart are not layout-compatible. char + is layout-compatible with neither signed char nor unsigned char. + + Similar types are not layout-compatible if they are not the same type after ignoring + top-level cv-qualification. + + An enumeration type and its underlying type are not layout-compatible. + + Array types of layout-compatible but different element types (ignoring + cv-qualification) are not layout-compatible, even if they are of equal length. + + Feature-test macro Value Std Feature + __cpp_lib_is_layout_compatible 201907L (C++20) std::is_layout_compatible + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo + { + int x; + char y; + }; + + struct FooNua + { + int x; + [[no_unique_address]] char y; + }; + + class Bar + { + const int u = 42; + volatile char v = '*'; + }; + + enum E0 : int {}; + enum class E1 : int {}; + + static_assert + ( + std::is_layout_compatible_v == true and + std::is_layout_compatible_v == true and + std::is_layout_compatible_v == false and + std::is_layout_compatible_v == false and + std::is_layout_compatible_v == true and + std::is_layout_compatible_v == false and + std::is_layout_compatible_v == false and + std::is_layout_compatible_v == true and + std::is_layout_compatible_v == false // Note [1] + ); + + // [1] MSVC erroneously fails this assert + + int main() {} + +.SH See also + + is_standard_layout checks if a type is a standard-layout type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_literal_type.3 b/man/std::is_literal_type.3 index 3e4c2ee4f..3ba875804 100644 --- a/man/std::is_literal_type.3 +++ b/man/std::is_literal_type.3 @@ -1,25 +1,40 @@ -.TH std::is_literal_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_literal_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_literal_type \- std::is_literal_type + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP - struct is_literal_type; + struct is_literal_type; (deprecated in C++17) + (removed in C++20) + + std::is_literal_type is a UnaryTypeTrait. + + (This type trait has been deprecated^[1] and removed^[2] as offering negligible + value to generic code.) + + If T satisfies all requirements of LiteralType, provides the member constant value + equal to true. For any other type, value is false. - If T is a literal type, provides the member constant value equal true. For any other - type, value is false. + If std::remove_all_extents_t is an incomplete type and not (possibly + cv-qualified) void, the behavior is undefined. - A literal type is any scalar type, any reference type or a class type that: + If the program adds specializations for std::is_literal_type or + std::is_literal_type_v, the behavior is undefined. - 1. has a trivial destructor +.SH Template parameters - 2. all of its constructor calls and initializers for nonstatic data members are - constant expressions + T - a type to check - 3. is an aggregate type or has at least one constexpr constructor that is not a copy - or move constructor + Helper variable template - 4. all of its nonstatic data members and base classes are literal types + template< class T > \fI(since C++17)\fP + inline constexpr bool is_literal_type_v = \fB(deprecated)\fP + is_literal_type::value; (removed in C++20) - An array of literal types is also a literal type. + + +Inherited from std::integral_constant .SH Member constants @@ -30,6 +45,8 @@ operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -44,28 +61,35 @@ .SH Example - + // Run this code - #include #include - - struct A { - int m; - }; - - struct B { - virtual ~B(); - }; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_literal_type::value << '\\n'; - std::cout << std::is_literal_type::value << '\\n'; - } - -.SH Output: - - true - false + + struct A { int m; }; + static_assert(std::is_literal_type_v == true); + + struct B { virtual ~B(); }; + static_assert(std::is_literal_type_v == false); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 T could be an array of incomplete the behavior is + class type with unknown bound undefined in this case + +.SH External links + + 1. ↑ Alisdair Meredith. "Deprecate the is_literal Trait". Deprecating Vestigial + Library Parts in C++17. "The is_literal type trait offers negligible value to + generic code, as what is really needed is the ability to know that a specific + construction would produce constant initialization." + 2. ↑ Alisdair Meredith, Stephan T. Lavavej, Tomasz Kamiński. "Deprecated type + traits". Reviewing Deprecated Facilities of C++17 for C++20. "Strong + recommendation: Remove the traits that can live on as zombies. [...] Toronto + Review: Accept strong recommendation, strike from C++20." diff --git a/man/std::is_lvalue_reference.3 b/man/std::is_lvalue_reference.3 index 4cc7df30b..aeebab793 100644 --- a/man/std::is_lvalue_reference.3 +++ b/man/std::is_lvalue_reference.3 @@ -1,28 +1,46 @@ -.TH std::is_lvalue_reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_lvalue_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_lvalue_reference \- std::is_lvalue_reference + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_lvalue_reference; - Checks whether T is a lvalue reference type. Provides the member constant value - which is equal to true, if T is a lvalue reference type. Otherwise, value is equal + std::is_lvalue_reference is a UnaryTypeTrait. + + Checks whether T is an lvalue reference type. Provides the member constant value + which is equal to true, if T is an lvalue reference type. Otherwise, value is equal to false. + If the program adds specializations for std::is_lvalue_reference or + std::is_lvalue_reference_v, the behavior is undefined. + .SH Template parameters T - a type to check + Helper variable template + + template< class T > + inline constexpr bool is_lvalue_reference_v = \fI(since C++17)\fP + is_lvalue_reference::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is an lvalue reference type , false otherwise + value true if T is an lvalue reference type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -37,14 +55,14 @@ Inherited from std::integral_constant .SH Example - + // Run this code #include #include - + class A {}; - + int main() { std::cout << std::boolalpha; @@ -67,7 +85,8 @@ Inherited from std::integral_constant .SH See also - is_reference checks if a type is either lvalue reference or rvalue reference - \fI(C++11)\fP \fI(class template)\fP - is_rvalue_reference checks if a type is rvalue reference - \fI(C++11)\fP \fI(class template)\fP + is_reference checks if a type is either an lvalue reference or rvalue + \fI(C++11)\fP reference + \fI(class template)\fP + is_rvalue_reference checks if a type is an rvalue reference + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_member_function_pointer.3 b/man/std::is_member_function_pointer.3 index 8dbbcb9c2..8a5fe160f 100644 --- a/man/std::is_member_function_pointer.3 +++ b/man/std::is_member_function_pointer.3 @@ -1,28 +1,48 @@ -.TH std::is_member_function_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_member_function_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_member_function_pointer \- std::is_member_function_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_member_function_pointer; + std::is_member_function_pointer is a UnaryTypeTrait. + Checks whether T is a non-static member function pointer. Provides the member constant value which is equal to true, if T is a non-static member function pointer type. Otherwise, value is equal to false. + If the program adds specializations for std::is_member_function_pointer or + std::is_member_function_pointer_v, the behavior is undefined. + .SH Template parameters T - a type to check + Helper variable template + + template< class T > + + inline constexpr bool is_member_function_pointer_v = \fI(since C++17)\fP + + is_member_function_pointer::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a member function pointer type , false otherwise + value true if T is a member function pointer type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -32,41 +52,42 @@ Inherited from std::integral_constant .SH Possible implementation - template< class T > + template struct is_member_function_pointer_helper : std::false_type {}; - - template< class T, class U> + + template struct is_member_function_pointer_helper : std::is_function {}; - - template< class T > - struct is_member_function_pointer : is_member_function_pointer_helper< - typename std::remove_cv::type - > {}; + + template + struct is_member_function_pointer + : is_member_function_pointer_helper::type> {}; .SH Example - + // Run this code #include - - class A { - void member_function() { } + + class A + { + public: + void member() {} }; - + int main() { - // fails at compile time if A does not contain member_function as a function. - static_assert(std::is_member_function_pointer::value, - "Class does not contain member."); + // fails at compile time if A::member is a data member and not a function + static_assert(std::is_member_function_pointer::value, + "A::member is not a member function."); } .SH See also is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_member_object_pointer checks if a type is a pointer to a non-static member object - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_member_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP function or object - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::is_member_object_pointer.3 b/man/std::is_member_object_pointer.3 index 89bf8ff6d..7debc9976 100644 --- a/man/std::is_member_object_pointer.3 +++ b/man/std::is_member_object_pointer.3 @@ -1,28 +1,46 @@ -.TH std::is_member_object_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_member_object_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_member_object_pointer \- std::is_member_object_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_member_object_pointer; - Checks whether T is a non-static member object. Provides the member constant value - which is equal to true, if T is a non-static member object type. Otherwise, value is - equal to false. + std::is_member_object_pointer is a UnaryTypeTrait. + + Checks whether T is a non-static member object pointer. Provides the member constant + value which is equal to true, if T is a non-static member object pointer type. + Otherwise, value is equal to false. + + If the program adds specializations for std::is_member_object_pointer or + std::is_member_object_pointer_v, the behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > + inline constexpr bool is_member_object_pointer_v = \fI(since C++17)\fP + is_member_object_pointer::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a pointer to member object , false otherwise + value true if T is a pointer to member object, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -41,41 +59,35 @@ Inherited from std::integral_constant .SH Example - This section is incomplete - Reason: simplify - // Run this code #include #include - - int main() { - class cls {}; - std::cout << (std::is_member_object_pointer::value - ? "T is member object pointer" - : "T is not a member object pointer") << '\\n'; - std::cout << (std::is_member_object_pointer::value - ? "T is member object pointer" - : "T is not a member object pointer") << '\\n'; + + int main() + { + class C {}; + std::cout << "Is member object pointer?\\n" << std::boolalpha + << std::is_member_object_pointer_v + << ": int(C::*)\\n" + << std::is_member_object_pointer_v + << ": int(C::*)()\\n"; } .SH Output: - T is member object pointer - T is not a member object pointer + Is member object pointer? + true: int(C::*) + false: int(C::*)() .SH See also is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_member_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP function or object - \fI(class template)\fP + \fI(class template)\fP is_member_function_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP function - \fI(class template)\fP - -.SH Category: - - * Todo with reason + \fI(class template)\fP diff --git a/man/std::is_member_pointer.3 b/man/std::is_member_pointer.3 index 3e36f6aea..f09355c48 100644 --- a/man/std::is_member_pointer.3 +++ b/man/std::is_member_pointer.3 @@ -1,22 +1,46 @@ -.TH std::is_member_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_member_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_member_pointer \- std::is_member_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_member_pointer; + std::is_member_pointer is a UnaryTypeTrait. + If T is pointer to non-static member object or a pointer to non-static member function, provides the member constant value equal true. For any other type, value is false. + If the program adds specializations for std::is_member_pointer or + std::is_member_pointer_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + inline constexpr bool is_member_pointer_v = \fI(since C++17)\fP + is_member_pointer::value; + + + +Inherited from std::integral_constant + .SH Member constants - value true if T is a member pointer type , false otherwise + value true if T is a member pointer type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,53 +50,38 @@ .SH Possible implementation - template< class T > - struct is_member_pointer_helper : std::false_type {}; - - template< class T, class U > - struct is_member_pointer_helper : std::true_type {}; - - template< class T > - struct is_member_pointer : - is_member_pointer_helper::type> {}; + template + struct is_member_pointer_helper : std::false_type {}; + + template + struct is_member_pointer_helper : std::true_type {}; + + template + struct is_member_pointer : is_member_pointer_helper::type> {}; .SH Example - This section is incomplete - Reason: simplify - // Run this code - #include #include - - int main() { - class cls {}; - std::cout << (std::is_member_pointer::value - ? "T is member pointer" - : "T is not a member pointer") << '\\n'; - std::cout << (std::is_member_pointer::value - ? "T is member pointer" - : "T is not a member pointer") << '\\n'; - } -.SH Output: + class C {}; + static_assert(std::is_member_pointer_v); + + static_assert(!std::is_member_pointer_v); - T is member pointer - T is not a member pointer + int main() + { + } .SH See also is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_member_object_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP object - \fI(class template)\fP + \fI(class template)\fP is_member_function_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP function - \fI(class template)\fP - -.SH Category: - - * Todo with reason + \fI(class template)\fP diff --git a/man/std::is_move_assignable,std::is_trivially_move_assignable,.3 b/man/std::is_move_assignable,std::is_trivially_move_assignable,.3 index e28e2cc62..1191fc86d 100644 --- a/man/std::is_move_assignable,std::is_trivially_move_assignable,.3 +++ b/man/std::is_move_assignable,std::is_trivially_move_assignable,.3 @@ -1,4 +1,7 @@ -.TH std::is_move_assignable,std::is_trivially_move_assignable, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_move_assignable,std::is_trivially_move_assignable, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_move_assignable,std::is_trivially_move_assignable, \- std::is_move_assignable,std::is_trivially_move_assignable, + .SH Synopsis Defined in header @@ -9,15 +12,22 @@ template< class T > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_move_assignable; - 1) Checks whether a type is MoveAssignable, i.e. has an accessible explicit or - implicit move assignment operator. If the requirement is met, a member constant - value equal true is provided, otherwise value is false. + The value of the member constant value + Type trait T is a referenceable type T is not a referenceable + type + \fB(1)\fP std::is_assignable::value + \fB(2)\fP std::is_trivially_assignable::value false + \fB(3)\fP std::is_nothrow_assignable::value + + If T is not a complete type, (possibly cv-qualified) void, or an array of unknown + bound, the behavior is undefined. - 2) same as 1), but evaluation of the move-assignment expression will not call any - operation that is not trivial. + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. - 3) same as 1), but the evaluation of the move-assignment expression will not call - any operation that is not noexcept. + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants @@ -28,6 +38,8 @@ operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -37,38 +49,63 @@ .SH Possible implementation - template< class T> + template struct is_move_assignable - : std::is_assignable< typename std::add_lvalue_reference::type, - typename std::add_rvalue_reference::type> {}; - - template< class T> + : std::is_assignable::type, + typename std::add_rvalue_reference::type> {}; + + template struct is_trivially_move_assignable - : std::is_trivially_assignable< typename std::add_lvalue_reference::type, - typename std::add_rvalue_reference::type> {}; - - template< class T> + : std::is_trivially_assignable::type, + typename std::add_rvalue_reference::type> {}; + + template struct is_nothrow_move_assignable - : std::is_nothrow_assignable< typename std::add_lvalue_reference::type, - typename std::add_rvalue_reference::type> {}; + : std::is_nothrow_assignable::type, + typename std::add_rvalue_reference::type> {}; + +.SH Notes + + The trait std::is_move_assignable is less strict than MoveAssignable because it does + not check the type of the result of the assignment (which, for a MoveAssignable + type, must be T&), nor the semantic requirement that the target's value after the + assignment is equivalent to the source's value before the assignment. + + The type does not have to implement a move assignment operator in order to satisfy + this trait; see MoveAssignable for details. .SH Example - + // Run this code #include #include #include + struct Foo { int n; }; - int main() { + + struct NoMove + { + // prevents implicit declaration of default move assignment operator + // however, the class is still move-assignable because its + // copy assignment operator can bind to an rvalue argument + NoMove& operator=(const NoMove&) { return *this; } + }; + + int main() + { std::cout << std::boolalpha << "std::string is nothrow move-assignable? " << std::is_nothrow_move_assignable::value << '\\n' << "int[2] is move-assignable? " << std::is_move_assignable::value << '\\n' - << "Foo is trivally move-assignable? " - << std::is_trivially_move_assignable::value << '\\n'; + << "Foo is trivially move-assignable? " + << std::is_trivially_move_assignable::value << '\\n' + << "NoMove is move-assignable? " + << std::is_move_assignable::value << '\\n' + << "NoMove is nothrow move-assignable? " + << std::is_nothrow_move_assignable::value << '\\n'; } .SH Output: @@ -76,18 +113,20 @@ std::string is nothrow move-assignable? true int[2] is move-assignable? false Foo is trivially move-assignable? true + NoMove is move-assignable? true + NoMove is nothrow move-assignable? false .SH See also is_assignable - is_trivially_assignable checks if a type has a assignment operator for a + is_trivially_assignable checks if a type has an assignment operator for a is_nothrow_assignable specific argument - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_copy_assignable is_trivially_copy_assignable is_nothrow_copy_assignable checks if a type has a copy assignment operator - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP diff --git a/man/std::is_move_constructible,std::is_trivially_move_constructible,.3 b/man/std::is_move_constructible,std::is_trivially_move_constructible,.3 index 4c867adf0..8698b34bc 100644 --- a/man/std::is_move_constructible,std::is_trivially_move_constructible,.3 +++ b/man/std::is_move_constructible,std::is_trivially_move_constructible,.3 @@ -1,4 +1,7 @@ -.TH std::is_move_constructible,std::is_trivially_move_constructible, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_move_constructible,std::is_trivially_move_constructible, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_move_constructible,std::is_trivially_move_constructible, \- std::is_move_constructible,std::is_trivially_move_constructible, + .SH Synopsis Defined in header @@ -9,24 +12,34 @@ template< class T > \fB(3)\fP \fI(since C++11)\fP struct is_nothrow_move_constructible; - 1) Checks whether a type is MoveConstructible, that is, can be constructed from - rvalue argument. If the requirement is met, a member constant value equal to true is - provided; otherwise the value is false. + The value of the member constant value + Type trait T is a referenceable type T is not a + referenceable type + \fB(1)\fP std::is_constructible::value + \fB(2)\fP std::is_trivially_constructible::value false + \fB(3)\fP std::is_nothrow_constructible::value + + If T is not a complete type, (possibly cv-qualified) void, or an array of unknown + bound, the behavior is undefined. - 2) Same as 1), but the move constructor expression does not call any operation that - is not trivial. + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. - 3) Same as 1), but the move constructor expression is noexcept. + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member constants - value true if T is move-constructible , false otherwise + value true if T is move-constructible, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -34,6 +47,20 @@ value_type bool type std::integral_constant +.SH Possible implementation + + template + struct is_move_constructible : + std::is_constructible::type> {}; + + template + struct is_trivially_move_constructible : + std::is_trivially_constructible::type> {}; + + template + struct is_nothrow_move_constructible : + std::is_nothrow_constructible::type> {}; + .SH Notes Types without a move constructor, but with a copy constructor that accepts const T& @@ -42,77 +69,84 @@ Move constructors are usually noexcept, since otherwise they are unusable in any code that provides strong exception guarantee. -.SH Possible implementation - - template - struct is_move_constructible : - std::is_constructible::type> {}; - - template - struct is_trivially_move_constructible : - std::is_trivially_constructible::type> {}; - - template - struct is_nothrow_move_constructible : - std::is_nothrow_constructible::type> {}; + In many implementations, std::is_nothrow_move_constructible also checks if the + destructor throws because it is effectively noexcept(T(arg)). Same applies to + std::is_trivially_move_constructible, which, in these implementations, also requires + that the destructor is trivial: GCC bug 51452, LWG issue 2116. .SH Example - + // Run this code - #include + #include #include - - struct Ex1 { - std::string str; // member has a non-trivial but non-throwing move ctor + + struct Ex1 + { + std::string str; // member has a non-trivial but non-throwing move constructor }; - struct Ex2 { + static_assert(std::is_move_constructible_v); + static_assert(!std::is_trivially_move_constructible_v); + static_assert(std::is_nothrow_move_constructible_v); + + struct Ex2 + { int n; Ex2(Ex2&&) = default; // trivial and non-throwing }; - - int main() { - std::cout << std::boolalpha << "Ex1 is move-constructible? " - << std::is_move_constructible::value << '\\n' - << "Ex1 is trivially move-constructible? " - << std::is_trivially_move_constructible::value << '\\n' - << "Ex1 is nothrow move-constructible? " - << std::is_nothrow_move_constructible::value << '\\n' - << "Ex2 is trivially move-constructible? " - << std::is_trivially_move_constructible::value << '\\n' - << "Ex2 is nothrow move-constructible? " - << std::is_nothrow_move_constructible::value << '\\n'; - } - -.SH Output: - - Ex1 is move-constructible? true - Ex1 is trivially move-constructible? false - Ex1 is nothrow move-constructible? true - Ex2 is trivially move-constructible? true - Ex2 is nothrow move-constructible? true + static_assert(std::is_move_constructible_v); + static_assert(std::is_trivially_move_constructible_v); + static_assert(std::is_nothrow_move_constructible_v); + + struct NoMove1 + { + // prevents implicit declaration of default move constructor; + // however, the class is still move-constructible because its + // copy constructor can bind to an rvalue argument + NoMove1(const NoMove1&) {} + }; + static_assert(std::is_move_constructible_v); + static_assert(!std::is_trivially_move_constructible_v); + static_assert(!std::is_nothrow_move_constructible_v); + + struct NoMove2 + { + // Not move-constructible since the lvalue reference + // can't bind to the rvalue argument + NoMove2(NoMove2&) {} + }; + static_assert(!std::is_move_constructible_v); + static_assert(!std::is_trivially_move_constructible_v); + static_assert(!std::is_nothrow_move_constructible_v); + + int main() {} .SH See also is_constructible is_trivially_constructible checks if a type has a constructor for specific is_nothrow_constructible arguments - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_default_constructible is_trivially_default_constructible is_nothrow_default_constructible checks if a type has a default constructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP is_copy_constructible is_trivially_copy_constructible is_nothrow_copy_constructible checks if a type has a copy constructor - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP \fI(C++11)\fP + move_constructible specifies that an object of a type can be move + (C++20) constructed + (concept) + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP move_if_noexcept obtains an rvalue reference if the move \fI(C++11)\fP constructor does not throw - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::is_null_pointer.3 b/man/std::is_null_pointer.3 index 7382e74b4..128740564 100644 --- a/man/std::is_null_pointer.3 +++ b/man/std::is_null_pointer.3 @@ -1,9 +1,14 @@ -.TH std::is_null_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_null_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_null_pointer \- std::is_null_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++14)\fP struct is_null_pointer; + std::is_null_pointer is a UnaryTypeTrait. + Checks whether T is the type std::nullptr_t. Provides the member constant value that is equal to true, if T is the type @@ -12,15 +17,26 @@ Otherwise, value is equal to false. + If the program adds specializations for std::is_null_pointer + or std::is_null_pointer_v + \fI(since C++17)\fP, the behavior is undefined. + .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_null_pointer_v = is_null_pointer::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is the type std::nullptr_t (possibly cv-qualified) , false + value true if T is the type std::nullptr_t (possibly cv-qualified), false \fB[static]\fP otherwise \fI(public static member constant)\fP @@ -28,6 +44,8 @@ Inherited from std::integral_constant operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -35,48 +53,50 @@ Inherited from std::integral_constant value_type bool type std::integral_constant +.SH Possible implementation + + template + struct is_null_pointer : std::is_same> {}; + .SH Notes std::is_pointer is false for std::nullptr_t because it is not a built-in pointer type. + Feature-test macro Value Std Feature + __cpp_lib_is_null_pointer 201309L \fI(C++14)\fP std::is_null_pointer + .SH Example - + // Run this code - #include #include - + + static_assert(std::is_null_pointer_v); + static_assert(!std::is_null_pointer_v); + static_assert(!std::is_pointer_v); + static_assert(std::is_pointer_v); + int main() { - std::cout << std::boolalpha - << std::is_null_pointer< decltype(nullptr) >::value << ' ' - << std::is_null_pointer< int* >::value << '\\n' - << std::is_pointer< decltype(nullptr) >::value << ' ' - << std::is_pointer::value << '\\n'; } -.SH Output: - - true false - false true - .SH See also is_void checks if a type is void - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_enum checks if a type is an enumeration type - \fI(C++11)\fP \fI(class template)\fP - is_union checks if a type is an union type - \fI(C++11)\fP \fI(class template)\fP - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_union checks if a type is a union type + \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP is_function checks if a type is a function type - \fI(C++11)\fP \fI(class template)\fP - is_object checks if a type is object type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_object checks if a type is an object type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_object.3 b/man/std::is_object.3 index e776405eb..6f4a9e658 100644 --- a/man/std::is_object.3 +++ b/man/std::is_object.3 @@ -1,21 +1,45 @@ -.TH std::is_object 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_object \- std::is_object + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_object; - If T is an object type (that is, scalar, array, class, or union), provides the - member constant value equal true. For any other type, value is false. + std::is_object is a UnaryTypeTrait. + + If T is an object type (that is any possibly cv-qualified type other than function, + reference, or void types), provides the member constant value equal true. For any + other type, value is false. + + If the program adds specializations for std::is_object or std::is_object_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_object_v = is_object::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is an object type , false otherwise + value true if T is an object type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,44 +49,65 @@ .SH Possible implementation - template< class T> + template struct is_object : std::integral_constant::value || - std::is_array::value || - std::is_union::value || - std::is_class::value> {}; + std::is_scalar::value || + std::is_array::value || + std::is_union::value || + std::is_class::value> {}; .SH Example - + // Run this code + #include #include #include - - int main() { + + #define IS_OBJECT(...) \\ + std::cout << std::boolalpha << std::left << std::setw(9) << #__VA_ARGS__ \\ + << (std::is_object_v<__VA_ARGS__> ? " is object\\n" \\ + : " is not an object\\n") + + int main() + { class cls {}; - std::cout << std::boolalpha; - std::cout << std::is_object::value << '\\n'; - std::cout << std::is_object::value << '\\n'; - std::cout << std::is_object::value << '\\n'; - std::cout << std::is_object::value << '\\n'; + + IS_OBJECT(void); + IS_OBJECT(int); + IS_OBJECT(int&); + IS_OBJECT(int*); + IS_OBJECT(int*&); + IS_OBJECT(cls); + IS_OBJECT(cls&); + IS_OBJECT(cls*); + IS_OBJECT(int()); + IS_OBJECT(int(*)()); + IS_OBJECT(int(&)()); } .SH Output: - true - false - true - false + void is not an object + int is object + int& is not an object + int* is object + int*& is not an object + cls is object + cls& is not an object + cls* is object + int() is not an object + int(*)() is object + int(&)() is not an object .SH See also - is_scalar checks if a type is scalar type - \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP - is_union checks if a type is an union type - \fI(C++11)\fP \fI(class template)\fP - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_union checks if a type is a union type + \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_partitioned.3 b/man/std::is_partitioned.3 index 241b42f11..840632ca6 100644 --- a/man/std::is_partitioned.3 +++ b/man/std::is_partitioned.3 @@ -1,45 +1,75 @@ -.TH std::is_partitioned 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_partitioned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_partitioned \- std::is_partitioned + .SH Synopsis Defined in header - template< class InputIt, class UnaryPredicate > \fI(since C++11)\fP - bool is_partitioned( InputIt first, InputIt last, UnaryPredicate p ); + template< class InputIt, class UnaryPred > \fI(since C++11)\fP + bool is_partitioned( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + UnaryPred p ); + template< class ExecutionPolicy, class ForwardIt, class + UnaryPred > + + bool is_partitioned( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, + UnaryPred p ); + + 1) Checks whether [first, last) is partitioned by the predicate p: all elements + satisfy p appear before all elements that do not. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if - Returns true if all elements in the range [first, last) that satisfy the predicate p - appear before all elements that don't. Also returns true if [first, last) is empty. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to check + policy - the execution policy to use. See execution policy for details. unary predicate which returns true for the elements expected to be found in the beginning of the range. - The signature of the predicate function should be equivalent to the - following: - p - - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. and its value type + must be convertible to UnaryPred's parameter type. - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value - true if the range [first, last) is empty or is partitioned by p. false otherwise. + true if the elements e of [first, last) are partitioned with respect to the + expression p(e). false otherwise. .SH Complexity At most std::distance(first, last) applications of p. +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + .SH Possible implementation - template< class InputIt, class UnaryPredicate > - bool is_partitioned(InputIt first, InputIt last, UnaryPredicate p) + template + bool is_partitioned(InputIt first, InputIt last, UnaryPred p) { for (; first != last; ++first) if (!p(*first)) @@ -52,35 +82,38 @@ .SH Example - + // Run this code #include #include #include - + int main() { - std::array v = { 1, 2, 3, 4, 5, 6, 7, 8, 9 }; - - auto is_even = [](int i){ return i % 2 == 0; }; + std::array v {1, 2, 3, 4, 5, 6, 7, 8, 9}; + + auto is_even = [](int i) { return i % 2 == 0; }; std::cout.setf(std::ios_base::boolalpha); std::cout << std::is_partitioned(v.begin(), v.end(), is_even) << ' '; - + std::partition(v.begin(), v.end(), is_even); std::cout << std::is_partitioned(v.begin(), v.end(), is_even) << ' '; - + std::reverse(v.begin(), v.end()); - std::cout << std::is_partitioned(v.begin(), v.end(), is_even); + std::cout << std::is_partitioned(v.cbegin(), v.cend(), is_even) << ' '; + std::cout << std::is_partitioned(v.crbegin(), v.crend(), is_even) << '\\n'; } .SH Output: - false true false + false true false true .SH See also - partition divides a range of elements into two groups - \fI(function template)\fP - partition_point locates the partition point of a partitioned range - \fI(C++11)\fP \fI(function template)\fP + partition divides a range of elements into two groups + \fI(function template)\fP + partition_point locates the partition point of a partitioned range + \fI(C++11)\fP \fI(function template)\fP + ranges::is_partitioned determines if the range is partitioned by the given predicate + (C++20) (niebloid) diff --git a/man/std::is_permutation.3 b/man/std::is_permutation.3 index 6774cdd3f..70fa3822b 100644 --- a/man/std::is_permutation.3 +++ b/man/std::is_permutation.3 @@ -1,39 +1,55 @@ -.TH std::is_permutation 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_permutation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_permutation \- std::is_permutation + .SH Synopsis Defined in header template< class ForwardIt1, class ForwardIt2 > - bool is_permutation( ForwardIt1 first1, ForwardIt1 last1, \fB(1)\fP \fI(since C++11)\fP + bool is_permutation( ForwardIt1 first1, ForwardIt1 \fB(1)\fP \fI(since C++11)\fP + last1, (constexpr since C++20) ForwardIt2 first2 ); - template< class ForwardIt1, class ForwardIt2, class - BinaryPredicate > - \fB(2)\fP \fI(since C++11)\fP - bool is_permutation( ForwardIt1 first1, ForwardIt1 last1, + template< class ForwardIt1, class ForwardIt2, + + class BinaryPredicate > + bool is_permutation( ForwardIt1 first1, ForwardIt1 \fB(2)\fP \fI(since C++11)\fP + last1, (constexpr since C++20) - ForwardIt2 first2, BinaryPredicate p ); + ForwardIt2 first2, BinaryPredicate + p ); template< class ForwardIt1, class ForwardIt2 > - bool is_permutation( ForwardIt1 first1, ForwardIt1 last1, \fB(3)\fP \fI(since C++14)\fP + bool is_permutation( ForwardIt1 first1, ForwardIt1 \fI(since C++14)\fP + last1, \fB(3)\fP (constexpr since C++20) - ForwardIt2 first2, ForwardIt2 last2 ); - template< class ForwardIt1, class ForwardIt2, class - BinaryPredicate > + ForwardIt2 first2, ForwardIt2 last2 + ); + template< class ForwardIt1, class ForwardIt2, - bool is_permutation( ForwardIt1 first1, ForwardIt1 last2, \fB(4)\fP \fI(since C++14)\fP - ForwardIt2 first1, ForwardIt2 last2, + class BinaryPredicate > + bool is_permutation( ForwardIt1 first1, ForwardIt1 \fI(since C++14)\fP + last1, \fB(4)\fP (constexpr since C++20) + ForwardIt2 first2, ForwardIt2 + last2, BinaryPredicate p ); - Returns true if there exists a permutation of the elements in the range [first1, - last1) that makes that range equal to the range [first2,last2), where last2 denotes - first2 + (last1 - first1) if it was not given. The overloads \fB(1)\fP and \fB(3)\fP use - operator== for equality, whereas the overloads \fB(2)\fP and \fB(4)\fP use the binary predicate - p. + Checks whether [first1, last1) is a permutation of a range starting from first2: + + * For overloads (1,2), the second range has std::distance(first1, last1) elements. + * For overloads (3,4), the second range is [first2, last2). + 1,3) Elements are compared using operator==. + 2,4) Elements are compared using the given binary predicate p. + + If ForwardIt1 and ForwardIt2 have different value types, the program is ill-formed. + + If the comparison function is not an equivalence relation, the behavior is + undefined. .SH Parameters - first1, last2 - the range of elements to compare + first1, last1 - the range of elements to compare first2, last2 - the second range to compare binary predicate which returns true if the elements should be treated as equal. @@ -42,30 +58,44 @@ following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must - not modify the objects passed to it. + + p - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types - ForwardIt1 and ForwardIt2 can be dereferenced and then implicitly + InputIt1 and InputIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. - - .SH Type requirements - - ForwardIt1, ForwardIt2 must meet the requirements of ForwardIterator. + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value - true if the range [first1, last1) is a permutation of the range [first2, last2). + true if the range [first1, last1) is a permutation of the range [first2, last2), + false otherwise. .SH Complexity - At most O(N^2) applications of the predicate, or exactly N if the sequences are - already equal, where N=std::distance(first1, last1). - - However if ForwardIt1 and ForwardIt2 meet the requirements of RandomAccessIterator - and std::distance(first1, last1) != std::distance(first2, last2) no applications of - the predicate are made. + Given \\(\\scriptsize N\\)N as std::distance(first1, last1): + + 1) Exactly \\(\\scriptsize N\\)N comparisons using operator== if the two ranges are + equal, otherwise \\(\\scriptsize O(N^2)\\)O(N2 + ) comparisons in the worst case. + 2) Exactly \\(\\scriptsize N\\)N applications of the predicate p if the two ranges are + equal, otherwise \\(\\scriptsize O(N^2)\\)O(N2 + ) applications in the worst case. + 3,4) If ForwardIt1 and ForwardIt2 are both LegacyRandomAccessIterator, and last1 - + first1 != last2 - first2 is true, no comparison will be made. + Otherwise: + 3) Exactly \\(\\scriptsize N\\)N comparisons using operator== if the two ranges are + equal, otherwise \\(\\scriptsize O(N^2)\\)O(N2 + ) comparisons in the worst case. + 4) Exactly \\(\\scriptsize N\\)N applications of the predicate p if the two ranges are + equal, otherwise \\(\\scriptsize O(N^2)\\)O(N2 + ) applications in the worst case. .SH Possible implementation @@ -73,57 +103,77 @@ bool is_permutation(ForwardIt1 first, ForwardIt1 last, ForwardIt2 d_first) { - // skip common prefix - std::tie(first, d_first) = std::mismatch(first, last, d_first); - // iterate over the rest, counting how many times each element - // from [first, last) appears in [d_first, d_last) - if (first != last) { - ForwardIt2 d_last = d_first; - std::advance(d_last, std::distance(first, last)); - for (ForwardIt1 i = first; i != last; ++i) { - if (i != std::find(first, i, *i)) continue; // already counted this *i - + // skip common prefix + std::tie(first, d_first) = std::mismatch(first, last, d_first); + + // iterate over the rest, counting how many times each element + // from [first, last) appears in [d_first, d_last) + if (first != last) + { + ForwardIt2 d_last = std::next(d_first, std::distance(first, last)); + for (ForwardIt1 i = first; i != last; ++i) + { + if (i != std::find(first, i, *i)) + continue; // this *i has been checked + auto m = std::count(d_first, d_last, *i); - if (m==0 || std::count(i, last, *i) != m) { + if (m == 0 || std::count(i, last, *i) != m) return false; - } } } return true; } +.SH Note + + The std::is_permutation can be used in testing, namely to check the correctness of + rearranging algorithms (e.g. sorting, shuffling, partitioning). If x is an original + range and y is a permuted range then std::is_permutation(x, y) == true means that y + consist of "the same" elements, maybe staying at other positions. + .SH Example - + // Run this code #include - #include #include + + template + Os& operator<<(Os& os, const V& v) + { + os << "{ "; + for (const auto& e : v) + os << e << ' '; + return os << '}'; + } + int main() { - std::vector v1{1,2,3,4,5}; - std::vector v2{3,5,4,1,2}; - std::cout << "3,5,4,1,2 is a permutation of 1,2,3,4,5? " - << std::boolalpha - << std::is_permutation(v1.begin(), v1.end(), v2.begin()) << '\\n'; - - std::vector v3{3,5,4,1,1}; - std::cout << "3,5,4,1,1 is a permutation of 1,2,3,4,5? " - << std::boolalpha + static constexpr auto v1 = {1, 2, 3, 4, 5}; + static constexpr auto v2 = {3, 5, 4, 1, 2}; + static constexpr auto v3 = {3, 5, 4, 1, 1}; + + std::cout << v2 << " is a permutation of " << v1 << ": " << std::boolalpha + << std::is_permutation(v1.begin(), v1.end(), v2.begin()) << '\\n' + << v3 << " is a permutation of " << v1 << ": " << std::is_permutation(v1.begin(), v1.end(), v3.begin()) << '\\n'; } .SH Output: - 3,5,4,1,2 is a permutation of 1,2,3,4,5? true - 3,5,4,1,1 is a permutation of 1,2,3,4,5? false + { 3 5 4 1 2 } is a permutation of { 1 2 3 4 5 }: true + { 3 5 4 1 1 } is a permutation of { 1 2 3 4 5 }: false .SH See also - generates the next greater lexicographic permutation of a range of - next_permutation elements - \fI(function template)\fP - generates the next smaller lexicographic permutation of a range of - prev_permutation elements - \fI(function template)\fP + generates the next greater lexicographic permutation of a + next_permutation range of elements + \fI(function template)\fP + generates the next smaller lexicographic permutation of a + prev_permutation range of elements + \fI(function template)\fP + equivalence_relation specifies that a relation imposes an equivalence relation + (C++20) (concept) + ranges::is_permutation determines if a sequence is a permutation of another sequence + (C++20) (niebloid) diff --git a/man/std::is_placeholder.3 b/man/std::is_placeholder.3 index fade7ea6f..9c5259d3f 100644 --- a/man/std::is_placeholder.3 +++ b/man/std::is_placeholder.3 @@ -1,15 +1,24 @@ -.TH std::is_placeholder 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_placeholder 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_placeholder \- std::is_placeholder + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_placeholder; If T is the type of a standard placeholder (_1, _2, _3, ...), then this template is - derived from std::integral_constant, std::integral_constant, - std::integral_constant, respectively. + derived from std::integral_constant, std::integral_constant, + std::integral_constant, respectively. If T is not a standard placeholder type, this template is derived from - std::integral_constant + std::integral_constant. + + A program may specialize this template for a program-defined type T to implement + UnaryTypeTrait with base characteristic of std::integral_constant with + positive N to indicate that T should be treated as N^th placeholder type. + + std::bind uses std::is_placeholder to detect placeholders for unbound arguments. .SH Member constants @@ -20,6 +29,8 @@ operator int converts the object to int, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -27,43 +38,37 @@ value_type int type std::integral_constant - The template may be specialized for any user-defined T type: the specialization must - satisfy UnaryTypeTrait with BaseCharacteristic of std::integral_constant - with N > 0 to indicate that T should be treated as N'th placeholder type. - - std::bind uses std::is_placeholder to detect placeholders for unbound arguments. - .SH Example - + // Run this code + #include #include #include - #include - - struct My_2 { - } my_2; - - namespace std { + + struct My_2 {} my_2; + + namespace std + { template<> struct is_placeholder : public integral_constant {}; } - + int f(int n1, int n2) { - return n1+n2; + return n1 + n2; } - + int main() { std::cout << "Standard placeholder _5 is for the argument number " - << std::is_placeholder::value + << std::is_placeholder_v << '\\n'; - + auto b = std::bind(f, my_2, 2); std::cout << "Adding 2 to 11 selected with a custom placeholder gives " - << b(10, 11) + << b(10, 11) // the first argument, namely 10, is ignored << '\\n'; } @@ -75,6 +80,6 @@ .SH See also bind binds one or more arguments to a function object - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP _1, _2, _3, _4, ... placeholders for the unbound arguments in a std::bind expression - \fI(C++11)\fP (constant) + \fI(C++11)\fP (constant) diff --git a/man/std::is_pod.3 b/man/std::is_pod.3 index b799e19ae..9086b45e6 100644 --- a/man/std::is_pod.3 +++ b/man/std::is_pod.3 @@ -1,22 +1,47 @@ -.TH std::is_pod 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_pod 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_pod \- std::is_pod + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP - struct is_pod; + struct is_pod; (deprecated in C++20) + + std::is_pod is a UnaryTypeTrait. + + If T is a POD type ("plain old data type"), provides the member constant value equal + to true. For any other type, value is false. + + If std::remove_all_extents_t is an incomplete type and not (possibly + cv-qualified) void, the behavior is undefined. + + If the program adds specializations for std::is_pod or std::is_pod_v, the behavior + is undefined. + +.SH Template parameters - If T is a PODType ("plain old data type"), that is, both trivial and - standard-layout, provides the member constant value equal true. For any other type, - value is false. + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_pod_v = is_pod::value; (deprecated in C++20) + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a POD type , false otherwise + value true if T is a POD type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -24,49 +49,42 @@ value_type bool type std::integral_constant -.SH Notes - - Objects of POD types are fully compatible with the C programming language. - .SH Example - + // Run this code - #include #include - - struct A { - int m; - }; - - struct B { - int m1; - private: - int m2; - }; - - struct C { - virtual void foo(); - }; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_pod::value << '\\n'; - std::cout << std::is_pod::value << '\\n'; - std::cout << std::is_pod::value << '\\n'; - } - -.SH Output: - - true - false - false + + struct A { int m; }; + static_assert(std::is_pod_v == true); + + class B: public A { int m; }; + static_assert(std::is_pod_v == false); + + struct C { virtual void foo(); }; + static_assert(std::is_pod_v == false); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 T could be an array of incomplete the behavior is + class type with unknown bound undefined in this case .SH See also - is_standard_layout checks if a type is standard-layout type - \fI(C++11)\fP \fI(class template)\fP + is_standard_layout checks if a type is a standard-layout type + \fI(C++11)\fP \fI(class template)\fP is_trivial checks if a type is trivial - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP + +.SH External links + + Why is std::is_pod deprecated in C++20? — StackOverflow diff --git a/man/std::is_pointer.3 b/man/std::is_pointer.3 index ee3caad15..f019304a7 100644 --- a/man/std::is_pointer.3 +++ b/man/std::is_pointer.3 @@ -1,29 +1,46 @@ -.TH std::is_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_pointer \- std::is_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_pointer; - Checks whether T is a pointer to object or a pointer to function (not a pointer to a - non-static member object or to a data member). Provides the member constant value - which is equal to true, if T is a object pointer type. Otherwise, value is equal to - false. + std::is_pointer is a UnaryTypeTrait. + + Checks whether T is a pointer to object or function (including pointer to void, but + excluding pointer to member) or a cv-qualified version thereof. Provides the member + constant value which is equal to true, if T is an object/function pointer type. + Otherwise, value is equal to false. + + If the program adds specializations for std::is_pointer or std::is_pointer_v, the + behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_pointer_v = is_pointer::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a pointer type , false otherwise + value true if T is a pointer type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -33,52 +50,73 @@ Inherited from std::integral_constant .SH Possible implementation -template< class T > struct is_pointer_helper : std::false_type {}; -template< class T > struct is_pointer_helper : std::true_type {}; -template< class T > struct is_pointer : is_pointer_helper::type> {}; + template + struct is_pointer : std::false_type {}; + + template + struct is_pointer : std::true_type {}; + + template + struct is_pointer : std::true_type {}; + + template + struct is_pointer : std::true_type {}; + + template + struct is_pointer : std::true_type {}; .SH Example - + // Run this code - #include #include - - class A {}; - + int main() { - std::cout << std::boolalpha; - std::cout << std::is_pointer::value << '\\n'; - std::cout << std::is_pointer::value << '\\n'; - std::cout << std::is_pointer::value << '\\n'; - std::cout << std::is_pointer::value << '\\n'; - std::cout << std::is_pointer::value << '\\n'; - std::cout << std::is_pointer::value << '\\n'; + struct A + { + int m; + void f() {} + }; + + int A::*mem_data_ptr = &A::m; // a pointer to member data + void (A::*mem_fun_ptr)() = &A::f; // a pointer to member function + + static_assert( + ! std::is_pointer::value + && ! std::is_pointer_v // same thing as above, but in C++17! + && ! std::is_pointer() // same as above, using inherited operator bool + && ! std::is_pointer{} // ditto + && ! std::is_pointer()() // same as above, using inherited operator() + && ! std::is_pointer{}() // ditto + && std::is_pointer_v + && std::is_pointer_v + && ! std::is_pointer_v + && ! std::is_pointer_v + && ! std::is_pointer_v + && std::is_pointer_v + && ! std::is_pointer_v + && std::is_pointer_v + && std::is_pointer_v + && ! std::is_pointer_v + && ! std::is_pointer_v + && std::is_pointer_v + ); } -.SH Output: - - false - true - false - false - true - true - .SH See also is_member_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP function or object - \fI(class template)\fP + \fI(class template)\fP is_member_object_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP object - \fI(class template)\fP + \fI(class template)\fP is_member_function_pointer checks if a type is a pointer to a non-static member \fI(C++11)\fP function - \fI(class template)\fP + \fI(class template)\fP is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP - is_scalar checks if a type is scalar type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_pointer_interconvertible_base_of.3 b/man/std::is_pointer_interconvertible_base_of.3 new file mode 100644 index 000000000..1c1d8ec8e --- /dev/null +++ b/man/std::is_pointer_interconvertible_base_of.3 @@ -0,0 +1,99 @@ +.TH std::is_pointer_interconvertible_base_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_pointer_interconvertible_base_of \- std::is_pointer_interconvertible_base_of + +.SH Synopsis + Defined in header + template< class Base, class Derived > \fI(since C++20)\fP + struct is_pointer_interconvertible_base_of; + + If Derived is unambiguously derived from Base and every Derived object is + pointer-interconvertible with its Base subobject, or if both are the same non-union + class (in both cases ignoring cv-qualification), provides the member constant value + equal to true. Otherwise value is false. + + If both Base and Derived are non-union class types, and they are not the same type + (ignoring cv-qualification), Derived shall be a complete type; otherwise the + behavior is undefined. + + If the program adds specializations for std::is_pointer_interconvertible_base_of or + std::is_pointer_interconvertible_base_of_v, the behavior is undefined. + +.SH Member constants + + true if Derived is unambiguously derived from Base and every Derived object + value is pointer-interconvertible with its Base subobject, or if both are the + \fB[static]\fP same non-union class (in both cases ignoring cv-qualification), false + otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + std::is_pointer_interconvertible_base_of_v may be true even if T is a private + or protected base class of U. + + Let + + * U be a complete object type, + * T be a complete object type with cv-qualification not less than U, + * u be any valid lvalue of U, + + reinterpret_cast(u) always has well-defined result if + std::is_pointer_interconvertible_base_of_v is true. + + If T and U are not the same type (ignoring cv-qualification) and T is a + pointer-interconvertible base class of U, then both std::is_standard_layout_v and + std::is_standard_layout_v are true. + + If T is standard layout class type, then all base classes of T (if any) are + pointer-interconvertible base class of T. + + Feature-test macro Value Std Feature + Pointer-interconvertibility traits: +__cpp_lib_is_pointer_interconvertible 201907L (C++20) * std::is_pointer_interconvertible_base_of, + * std::is_pointer_interconvertible_with_class + +.SH Example + + +// Run this code + + #include + + struct Foo {}; + + struct Bar {}; + + class Baz : Foo, public Bar { int x; }; + + class NonStdLayout : public Baz { int y; }; + + static_assert(std::is_pointer_interconvertible_base_of_v); + static_assert(std::is_pointer_interconvertible_base_of_v); + static_assert(not std::is_pointer_interconvertible_base_of_v); + static_assert(std::is_pointer_interconvertible_base_of_v); + + int main() {} + +.SH See also + + is_base_of checks if a type is derived from the other type + \fI(C++11)\fP \fI(class template)\fP + is_empty checks if a type is a class (but not union) type and has no + \fI(C++11)\fP non-static data members + \fI(class template)\fP + is_standard_layout checks if a type is a standard-layout type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_pointer_interconvertible_with_class.3 b/man/std::is_pointer_interconvertible_with_class.3 new file mode 100644 index 000000000..f50e3c767 --- /dev/null +++ b/man/std::is_pointer_interconvertible_with_class.3 @@ -0,0 +1,69 @@ +.TH std::is_pointer_interconvertible_with_class 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_pointer_interconvertible_with_class \- std::is_pointer_interconvertible_with_class + +.SH Synopsis + Defined in header + template< class S, class M > + constexpr bool is_pointer_interconvertible_with_class( M S::* mp ) \fI(since C++20)\fP + noexcept; + + Given an object s of type S, determines whether s.*mp refers to a subobject of s and + s is pointer-interconvertible with its subobject s.*mp. The program is ill-formed if + S is not a complete type. + + If S is not a StandardLayoutType, or M is not an object type, or mp is equal to + nullptr, the result is always false. + +.SH Parameters + + mp - a pointer-to-member to detect + +.SH Return value + + true if s.*mp refers a subobject of s and s is pointer-interconvertible with its + subobject s.*mp, otherwise false, where s is an object of type S. + +.SH Notes + + The type of a pointer-to-member expression &S::m is not always M S::*, where m is of + type M, because m may be a member inherited from a base class of S. The template + arguments can be specified in order to avoid potentially surprising results. + + If there is a value mp of type M S::* such that + std::is_pointer_interconvertible_with_class(mp) == true, then + reinterpret_cast(s) has well-defined result and it refers the same subobject as + s.*mp, where s is a valid lvalue of type S. + + On common platforms, the bit pattern of mp is all zero if + std::is_pointer_interconvertible_with_class(mp) == true. + + Feature-test macro Value Std Feature + Pointer-interconvertibility traits: +__cpp_lib_is_pointer_interconvertible 201907L (C++20) * std::is_pointer_interconvertible_base_of, + * std::is_pointer_interconvertible_with_class + +.SH Example + + +// Run this code + + #include + + struct Foo { int x; }; + struct Bar { int y; }; + + struct Baz : Foo, Bar {}; // not standard-layout + + static_assert( not std::is_same_v ); + static_assert( std::is_pointer_interconvertible_with_class(&Baz::x) ); + static_assert( not std::is_pointer_interconvertible_with_class(&Baz::x) ); + + int main() { } + +.SH See also + + is_standard_layout checks if a type is a standard-layout type + \fI(C++11)\fP \fI(class template)\fP + is_member_object_pointer checks if a type is a pointer to a non-static member object + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_polymorphic.3 b/man/std::is_polymorphic.3 index f3051019c..1721a270b 100644 --- a/man/std::is_polymorphic.3 +++ b/man/std::is_polymorphic.3 @@ -1,22 +1,47 @@ -.TH std::is_polymorphic 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_polymorphic 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_polymorphic \- std::is_polymorphic + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_polymorphic; + std::is_polymorphic is a UnaryTypeTrait. + If T is a polymorphic class (that is, a non-union class that declares or inherits at - least one virtual function), provides the member constant value equal true. For any - other type, value is false. + least one virtual function), provides the member constant value equal to true. For + any other type, value is false. + + If T is an incomplete non-union class type, the behavior is undefined. + + If the program adds specializations for std::is_polymorphic or + std::is_polymorphic_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_polymorphic_v = is_polymorphic::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a polymorphic class type , false otherwise + value true if T is a polymorphic class type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -24,41 +49,68 @@ value_type bool type std::integral_constant +.SH Possible implementation + + namespace detail + { + template + std::true_type detect_is_polymorphic( + decltype(dynamic_cast(static_cast(nullptr))) + ); + template + std::false_type detect_is_polymorphic(...); + } // namespace detail + + template + struct is_polymorphic : decltype(detail::detect_is_polymorphic(nullptr)) {}; + .SH Example - + // Run this code - #include #include - - struct A { - int m; - }; - - struct B { - virtual void foo(); - }; - + + struct A { int m; }; + static_assert(!std::is_polymorphic_v); + + struct B { virtual void foo(); }; + static_assert(std::is_polymorphic_v); + struct C : B {}; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_polymorphic::value << '\\n'; - std::cout << std::is_polymorphic::value << '\\n'; - std::cout << std::is_polymorphic::value << '\\n'; - } + static_assert(std::is_polymorphic_v); + + struct D { virtual ~D() = default; }; + static_assert(std::is_polymorphic_v); + + // Uses inheritance, but not the virtual keyword: + struct E : A {}; + static_assert(!std::is_polymorphic_v); + + struct F : virtual A {}; + static_assert(!std::is_polymorphic_v); + + struct AX : A {}; + struct AY : A {}; + struct XY : virtual AX, virtual AY {}; + static_assert(!std::is_polymorphic_v); + + int main() {} + + Defect reports -.SH Output: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - false - true - true + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 the behavior was undefined if the base characteristic is + T is an incomplete union type std::false_type in this case .SH See also - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP - is_abstract checks if a type is abstract class type - \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP + is_abstract checks if a type is an abstract class type + \fI(C++11)\fP \fI(class template)\fP + has_virtual_destructor checks if a type has a virtual destructor + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_reference.3 b/man/std::is_reference.3 index c6c9f4a36..7eb1b8663 100644 --- a/man/std::is_reference.3 +++ b/man/std::is_reference.3 @@ -1,21 +1,44 @@ -.TH std::is_reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_reference \- std::is_reference + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_reference; + std::is_reference is a UnaryTypeTrait. + If T is a reference type (lvalue reference or rvalue reference), provides the member constant value equal true. For any other type, value is false. + If the program adds specializations for std::is_reference or std::is_reference_v, + the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_reference_v = is_reference::value; + + + +Inherited from std::integral_constant + .SH Member constants - value true if T is a reference type , false otherwise + value true if T is a reference type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,43 +48,51 @@ .SH Possible implementation - template struct is_reference : std::false_type {}; - template struct is_reference : std::true_type {}; - template struct is_reference : std::true_type {}; + template struct is_reference : std::false_type {}; + template struct is_reference : std::true_type {}; + template struct is_reference : std::true_type {}; .SH Example - + // Run this code #include #include - + class A {}; - + int main() { - std::cout << std::boolalpha; - std::cout << std::is_reference::value << '\\n'; - std::cout << std::is_reference::value << '\\n'; - std::cout << std::is_reference::value << '\\n'; - std::cout << std::is_reference::value << '\\n'; - std::cout << std::is_reference::value << '\\n'; - std::cout << std::is_reference::value << '\\n'; + # define REF(x) << #x " ?: " << x << '\\n' + std::cout << std::boolalpha + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v) + REF(std::is_reference_v); + # undef REF } .SH Output: - false - true - true - false - true - true + std::is_reference_v ?: false + std::is_reference_v ?: true + std::is_reference_v ?: true + std::is_reference_v ?: false + std::is_reference_v ?: true + std::is_reference_v ?: true + std::is_reference_v ?: false + std::is_reference_v ?: true + std::is_reference_v ?: true .SH See also - is_lvalue_reference checks if a type is lvalue reference - \fI(C++11)\fP \fI(class template)\fP - is_rvalue_reference checks if a type is rvalue reference - \fI(C++11)\fP \fI(class template)\fP + is_lvalue_reference checks if a type is an lvalue reference + \fI(C++11)\fP \fI(class template)\fP + is_rvalue_reference checks if a type is an rvalue reference + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_rvalue_reference.3 b/man/std::is_rvalue_reference.3 index 8898abdce..683b7989c 100644 --- a/man/std::is_rvalue_reference.3 +++ b/man/std::is_rvalue_reference.3 @@ -1,28 +1,46 @@ -.TH std::is_rvalue_reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_rvalue_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_rvalue_reference \- std::is_rvalue_reference + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_rvalue_reference; - Checks whether T is a rvalue reference type. Provides the member constant value - which is equal to true, if T is a rvalue reference type. Otherwise, value is equal + std::is_rvalue_reference is a UnaryTypeTrait. + + Checks whether T is an rvalue reference type. Provides the member constant value + which is equal to true, if T is an rvalue reference type. Otherwise, value is equal to false. + If the program adds specializations for std::is_rvalue_reference or + std::is_rvalue_reference_v, the behavior is undefined. + .SH Template parameters T - a type to check + Helper variable template + + template< class T > + inline constexpr bool is_rvalue_reference_v = \fI(since C++17)\fP + is_rvalue_reference::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is an rvalue reference type , false otherwise + value true if T is an rvalue reference type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -32,42 +50,81 @@ Inherited from std::integral_constant .SH Possible implementation - template struct is_rvalue_reference : std::false_type {}; - template struct is_rvalue_reference : std::true_type {}; + template struct is_rvalue_reference : std::false_type {}; + template struct is_rvalue_reference : std::true_type {}; .SH Example - + // Run this code - #include #include - + #include + class A {}; - + + static_assert + ( + std::is_rvalue_reference_v == false and + std::is_rvalue_reference_v == false and + std::is_rvalue_reference_v != false and + std::is_rvalue_reference_v == false and + std::is_rvalue_reference_v == false and + std::is_rvalue_reference_v != false + ); + + + + template + void test(T&& x) + { + static_assert(std::is_same_v); + std::cout << "T\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "T&&\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "decltype(x)\\t" << std::is_rvalue_reference::value << '\\n'; + } + int main() { std::cout << std::boolalpha; - std::cout << std::is_rvalue_reference::value << '\\n'; - std::cout << std::is_rvalue_reference::value << '\\n'; - std::cout << std::is_rvalue_reference::value << '\\n'; - std::cout << std::is_rvalue_reference::value << '\\n'; - std::cout << std::is_rvalue_reference::value << '\\n'; - std::cout << std::is_rvalue_reference::value << '\\n'; + std::cout << "A\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "A&\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "A&&\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "char\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "char&\\t" << std::is_rvalue_reference::value << '\\n'; + std::cout << "char&&\\t" << std::is_rvalue_reference::value << '\\n'; + + std::cout << "\\ntest(42)\\n"; + test(42); + + std::cout << "\\ntest(x)\\n"; + int x = 42; + test(x); } .SH Output: - false - false - true - false - false - true + A false + A& false + A&& true + char false + char& false + char&& true + + test\fB(42)\fP + T false + T&& true + decltype(x) true + + test(x) + T false + T&& false + decltype(x) false .SH See also - is_lvalue_reference checks if a type is lvalue reference - \fI(C++11)\fP \fI(class template)\fP - is_reference checks if a type is either lvalue reference or rvalue reference - \fI(C++11)\fP \fI(class template)\fP + is_lvalue_reference checks if a type is an lvalue reference + \fI(C++11)\fP \fI(class template)\fP + is_reference checks if a type is either an lvalue reference or rvalue + \fI(C++11)\fP reference + \fI(class template)\fP diff --git a/man/std::is_same.3 b/man/std::is_same.3 index b7d90c39c..ba6cbe7ef 100644 --- a/man/std::is_same.3 +++ b/man/std::is_same.3 @@ -1,21 +1,33 @@ -.TH std::is_same 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_same 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_same \- std::is_same + .SH Synopsis Defined in header template< class T, class U > \fI(since C++11)\fP struct is_same; - If T and U name the same type with the same const-volatile qualifications, provides - the member constant value equal to true. Otherwise value is false. + If T and U name the same type (taking into account const/volatile qualifications), + provides the member constant value equal to true. Otherwise value is false. + + Commutativity is satisfied, i.e. for any two types T and U, is_same::value == + true if and only if is_same::value == true. + + If the program adds specializations for std::is_same + or std::is_same_v + \fI(since C++17)\fP, the behavior is undefined. .SH Member constants - value true if T and U is the same type , false otherwise + value true if T and U are the same type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -27,65 +39,62 @@ template struct is_same : std::false_type {}; - + template struct is_same : std::true_type {}; .SH Example - + // Run this code + #include #include #include - #include - - void print_separator() - { - std::cout << "-----\\n"; - } - + int main() { std::cout << std::boolalpha; - - std::cout << std::is_same::value << '\\n'; // true - std::cout << std::is_same::value << '\\n'; // false - std::cout << std::is_same::value << '\\n'; // false - - print_separator(); - - std::cout << std::is_same::value << "\\n"; // true - std::cout << std::is_same::value << "\\n"; // false - std::cout << std::is_same::value << "\\n"; // true - - print_separator(); - - // unlike other types 'char' is not 'unsigned' and not 'signed' - std::cout << std::is_same::value << "\\n"; // true - std::cout << std::is_same::value << "\\n"; // false - std::cout << std::is_same::value << "\\n"; // false + + // some implementation-defined facts + + // usually true if 'int' is 32 bit + std::cout << std::is_same::value << ' '; // maybe true + // possibly true if ILP64 data model is used + std::cout << std::is_same::value << ' '; // maybe false + + // same tests as above, except using C++17's std::is_same_v format + std::cout << std::is_same_v << ' '; // maybe true + std::cout << std::is_same_v << '\\n'; // maybe false + + // compare the types of a couple variables + long double num1 = 1.0; + long double num2 = 2.0; + static_assert( std::is_same_v == true ); + + // 'float' is never an integral type + static_assert( std::is_same::value == false ); + + // 'int' is implicitly 'signed' + static_assert( std::is_same_v == true ); + static_assert( std::is_same_v == false ); + static_assert( std::is_same_v == true ); + + // unlike other types, 'char' is neither 'unsigned' nor 'signed' + static_assert( std::is_same_v == true ); + static_assert( std::is_same_v == false ); + static_assert( std::is_same_v == false ); + + // const-qualified type T is not same as non-const T + static_assert( !std::is_same() ); } -.SH Output: +.SH Possible output: - true - false - false - ----- - true - false - true - ----- - true - false - false + true false true false .SH See also - is_integral checks if a type is integral type - \fI(C++11)\fP \fI(class template)\fP - make_signed makes the given integral type signed - \fI(C++11)\fP \fI(class template)\fP - make_unsigned makes the given integral type unsigned - \fI(C++11)\fP \fI(class template)\fP + same_as specifies that a type is the same as another type + (C++20) (concept) + decltype specifier\fI(C++11)\fP obtains the type of an expression or an entity diff --git a/man/std::is_scalar.3 b/man/std::is_scalar.3 index e84ac04e2..c7cd2fcba 100644 --- a/man/std::is_scalar.3 +++ b/man/std::is_scalar.3 @@ -1,22 +1,44 @@ -.TH std::is_scalar 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_scalar 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_scalar \- std::is_scalar + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_scalar; - If T is a scalar type (that is, arithmetic type, enumeration type, pointer, pointer - to member, or std::nullptr_t, including any cv-qualified variants), provides the - member constant value equal true. For any other type, value is false. + std::is_scalar is a UnaryTypeTrait. + + If T is a scalar type, provides the member constant value equal true. For any other + type, value is false. + + If the program adds specializations for std::is_scalar or std::is_scalar_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_scalar_v = is_scalar::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a scalar type , false otherwise + value true if T is a scalar type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -27,52 +49,73 @@ .SH Notes Each individual memory location in the C++ memory model, including the hidden memory - locations used by language features (e.g virtual table pointer), has scalar type (or - is a sequence of adjacent bit-fields of non-zero length). Sequencing of side-effects - in expression evaluation, interthread synchronization, and dependency ordering are - all defined in terms of individual scalar objects. + locations used by language features (e.g. virtual table pointer), has scalar type + (or is a sequence of adjacent bit-fields of non-zero length). Sequencing of + side-effects in expression evaluation, inter-thread synchronization, and dependency + ordering are all defined in terms of individual scalar objects. .SH Possible implementation -template< class T > -struct is_scalar : std::integral_constant::value || - std::is_enum::value || - std::is_pointer::value || - std::is_member_pointer::value || - std::is_same::type>::value> {}; + template + struct is_scalar : std::integral_constant::value + || std::is_enum::value + || std::is_pointer::value + || std::is_member_pointer::value + || std::is_null_pointer::value> + {}; .SH Example - + // Run this code #include #include - - int main() { - class cls {}; - std::cout << (std::is_scalar::value - ? "T is scalar" - : "T is not a scalar") << '\\n'; - std::cout << (std::is_scalar::value - ? "T is scalar" - : "T is not a scalar") << '\\n'; + #include + #include + + template + void are_scalars(Head&& head, Tail&&... tail) + { + using T = std::decay_t; + + std::cout << typeid(T).name() << " is " + << (std::is_scalar_v ? "" : "not ") + << "a scalar\\n"; + + if constexpr (sizeof... (Tail)) + { + are_scalars(std::forward(tail)...); + } + } + + int main() + { + struct S { int m; } s; + int S::* mp = &S::m; + enum class E { e }; + + are_scalars(42, 3.14, E::e, "str", mp, nullptr, s); } -.SH Output: +.SH Possible output: - T is scalar - T is not a scalar + int is a scalar + double is a scalar + main::E is a scalar + char const* is a scalar + int main::S::* is a scalar + nullptr is a scalar + main::S is not a scalar .SH See also - is_arithmetic checks if a type is arithmetic type - \fI(C++11)\fP \fI(class template)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP is_enum checks if a type is an enumeration type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_member_pointer checks if a type is a pointer to a non-static member function or \fI(C++11)\fP object - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::is_scoped_enum.3 b/man/std::is_scoped_enum.3 new file mode 100644 index 000000000..c2aea54d3 --- /dev/null +++ b/man/std::is_scoped_enum.3 @@ -0,0 +1,98 @@ +.TH std::is_scoped_enum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_scoped_enum \- std::is_scoped_enum + +.SH Synopsis + Defined in header + template< class T > (since C++23) + struct is_scoped_enum; + + std::is_scoped_enum is a UnaryTypeTrait. + + Checks whether T is a scoped enumeration type. Provides the member constant value + which is equal to true, if T is a scoped enumeration type. Otherwise, value is equal + to false. + + If the program adds specializations for std::is_scoped_enum or + std::is_scoped_enum_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > (since C++23) + inline constexpr bool is_scoped_enum_v = is_scoped_enum::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is a scoped enumeration type, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_is_scoped_enum 202011L (C++23) std::is_scoped_enum + +.SH Possible implementation + + template + struct is_scoped_enum : std::bool_constant; + requires !std::is_convertible_v>; + }> + {}; + +.SH Example + + +// Run this code + + #include + + class A {}; + + enum E {}; + + enum struct Es { oz }; + + enum class Ec : int {}; + + int main() + { + static_assert(std::is_scoped_enum_v == false); + static_assert(std::is_scoped_enum_v == false); + static_assert(std::is_scoped_enum_v == true); + static_assert(std::is_scoped_enum_v == true); + static_assert(std::is_scoped_enum_v == false); + } + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP + is_enum checks if a type is an enumeration type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_signed.3 b/man/std::is_signed.3 index a2652062a..6f1ea891f 100644 --- a/man/std::is_signed.3 +++ b/man/std::is_signed.3 @@ -1,21 +1,47 @@ -.TH std::is_signed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_signed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_signed \- std::is_signed + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_signed; - If T is a signed arithmetic type, provides the member constant value equal true. For - any other type, value is false. + std::is_signed is a UnaryTypeTrait. + + If T is an arithmetic type, provides the member constant value equal to true if + T(-1) < T\fB(0)\fP: this results in true for the floating-point types and the signed + integer types, and in false for the unsigned integer types and the type bool. + + For any other type, value is false. + + If the program adds specializations for std::is_signed or std::is_signed_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_signed_v = is_signed::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a signed arithmetic type , false otherwise + value true if T is a signed arithmetic type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -23,49 +49,71 @@ value_type bool type std::integral_constant +.SH Possible implementation + + namespace detail + { + template::value> + struct is_signed : std::integral_constant {}; + + template + struct is_signed : std::false_type {}; + } + + template + struct is_signed : detail::is_signed::type {}; + .SH Example - + // Run this code #include #include - + class A {}; - enum B : int {}; - enum class C : int {}; - + static_assert(std::is_signed_v == false); + + class B { int i; }; + static_assert(std::is_signed_v == false); + + enum C : int {}; + static_assert(std::is_signed_v == false); + + enum class D : int {}; + static_assert(std::is_signed_v == false); + + static_assert( + std::is_signed::value == true and // C++11 + std::is_signed() == true and // C++11 + std::is_signed{} == true and // C++11 + std::is_signed_v == true and // C++17 + std::is_signed_v == false and + std::is_signed_v == true and + std::is_signed_v == false and + std::is_signed_v == true and + std::is_signed_v == false + ); + int main() { - std::cout << std::boolalpha; - std::cout << std::is_signed::value << '\\n'; - std::cout << std::is_signed::value << '\\n'; - std::cout << std::is_signed::value << '\\n'; - std::cout << std::is_signed::value << '\\n'; - std::cout << std::is_signed::value << '\\n'; - std::cout << std::is_signed::value << '\\n'; + // signedness of char is implementation-defined: + std::cout << std::boolalpha << std::is_signed_v << '\\n'; } -.SH Output: +.SH Possible output: - false - true true - false - false - false .SH See also - is_unsigned checks if a type is unsigned arithmetic type - \fI(C++11)\fP \fI(class template)\fP - is_signed identifies signed types - \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP - is_floating_point checks if a type is floating-point type - \fI(C++11)\fP \fI(class template)\fP - is_integral checks if a type is integral type - \fI(C++11)\fP \fI(class template)\fP - make_signed makes the given integral type signed - \fI(C++11)\fP \fI(class template)\fP - make_unsigned makes the given integral type unsigned - \fI(C++11)\fP \fI(class template)\fP + is_unsigned checks if a type is an unsigned arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_signed identifies signed types + \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + make_signed makes the given integral type signed + \fI(C++11)\fP \fI(class template)\fP + make_unsigned makes the given integral type unsigned + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_sorted.3 b/man/std::is_sorted.3 index 71d569fa8..f9726790b 100644 --- a/man/std::is_sorted.3 +++ b/man/std::is_sorted.3 @@ -1,87 +1,147 @@ -.TH std::is_sorted 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_sorted 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_sorted \- std::is_sorted + .SH Synopsis Defined in header - template< class ForwardIt > \fB(1)\fP \fI(since C++11)\fP - bool is_sorted( ForwardIt first, ForwardIt last ); - template< class ForwardIt, class Compare > \fB(2)\fP \fI(since C++11)\fP - bool is_sorted( ForwardIt first, ForwardIt last, Compare comp ); + template< class ForwardIt > \fB(1)\fP \fI(since C++11)\fP + bool is_sorted( ForwardIt first, ForwardIt last ); (constexpr since C++20) + template< class ExecutionPolicy, class ForwardIt > + + bool is_sorted( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last ); + template< class ForwardIt, class Compare > \fI(since C++11)\fP + bool is_sorted( ForwardIt first, ForwardIt last, Compare \fB(3)\fP (constexpr since C++20) + comp ); + template< class ExecutionPolicy, class ForwardIt, class + Compare > + + bool is_sorted( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, Compare + comp ); + + Checks if the elements in range [first, last) are sorted in non-descending order. - Checks if the elements in range [first, last) are sorted in ascending order. The - first version of the function uses operator< to compare the elements, the second - uses the given comparison function comp. + 1) Checks if the elements are sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Checks if the elements are sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of - them. + them. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of Compare. .SH Return value - true if the elements in the range are sorted in ascending order + true if the elements in the range are sorted in non-descending order, false + otherwise. .SH Complexity - linear in the distance between first and last + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) \\(\\scriptsize O(N)\\)O(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) \\(\\scriptsize O(N)\\)O(N) applications of the comparator comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + See also the implementations in libstdc++ and libc++. + + is_sorted \fB(1)\fP template bool is_sorted(ForwardIt first, ForwardIt last) { return std::is_sorted_until(first, last) == last; } -.SH Second version + is_sorted \fB(3)\fP template bool is_sorted(ForwardIt first, ForwardIt last, Compare comp) { return std::is_sorted_until(first, last, comp) == last; } +.SH Notes + + std::is_sorted returns true for empty ranges and ranges of length one. + .SH Example - + // Run this code - #include #include - + #include + #include + #include + #include + int main() { - const int N = 5; - int digits[N] = {3, 1, 4, 1, 5}; - - for (auto i : digits) std::cout << i << ' '; - std::cout << ": is_sorted: " << std::is_sorted(digits, digits+N) << '\\n'; - - std::sort(digits, digits+N); - - for (auto i : digits) std::cout << i << ' '; - std::cout << ": is_sorted: " << std::is_sorted(digits, digits+N) << '\\n'; - } + std::vector v; + assert(std::is_sorted(v.cbegin(), v.cend()) && "an empty range is always sorted"); + v.push_back(42); + assert(std::is_sorted(v.cbegin(), v.cend()) && "a range of size 1 is always sorted"); -.SH Output: + int data[] = {3, 1, 4, 1, 5}; + assert(not std::is_sorted(std::begin(data), std::end(data))); - 3 1 4 1 5 : is_sorted: 0 - 1 1 3 4 5 : is_sorted: 1 + std::sort(std::begin(data), std::end(data)); + assert(std::is_sorted(std::begin(data), std::end(data))); + assert(not std::is_sorted(std::begin(data), std::end(data), std::greater<>{})); + } .SH See also - is_sorted_until finds the largest sorted subrange - \fI(C++11)\fP \fI(function template)\fP + is_sorted_until finds the largest sorted subrange + \fI(C++11)\fP \fI(function template)\fP + ranges::is_sorted checks whether a range is sorted into ascending order + (C++20) (niebloid) diff --git a/man/std::is_sorted_until.3 b/man/std::is_sorted_until.3 index 008d7f715..a22b26524 100644 --- a/man/std::is_sorted_until.3 +++ b/man/std::is_sorted_until.3 @@ -1,39 +1,77 @@ -.TH std::is_sorted_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_sorted_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_sorted_until \- std::is_sorted_until + .SH Synopsis Defined in header - template< class ForwardIt > \fB(1)\fP \fI(since C++11)\fP - ForwardIt is_sorted_until( ForwardIt first, ForwardIt last ); + template< class ForwardIt > \fI(since C++11)\fP + ForwardIt is_sorted_until( ForwardIt first, ForwardIt \fB(1)\fP (constexpr since C++20) + last ); + template< class ExecutionPolicy, class ForwardIt > + + ForwardIt is_sorted_until( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt + last ); template< class ForwardIt, class Compare > - ForwardIt is_sorted_until( ForwardIt first, ForwardIt last, \fB(2)\fP \fI(since C++11)\fP + ForwardIt is_sorted_until( ForwardIt first, ForwardIt \fB(3)\fP \fI(since C++11)\fP + last, (constexpr since C++20) + + Compare comp ); + template< class ExecutionPolicy, class ForwardIt, class + Compare > + + ForwardIt is_sorted_until( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt + last, Compare comp ); Examines the range [first, last) and finds the largest range beginning at first in - which the elements are sorted in ascending order. The first version of the function - uses operator< to compare the elements, the second uses the given comparison - function comp. + which the elements are sorted in non-descending order. + + 1) Finds the largest range whether elements are sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Finds the largest range whether elements are sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of - them. + them. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of Compare. .SH Return value @@ -41,77 +79,113 @@ sorted in ascending order. That is, the last iterator it for which range [first, it) is sorted. + Returns last for empty ranges and ranges of length one. + .SH Complexity - linear in the distance between first and last + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) \\(\\scriptsize O(N)\\)O(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) \\(\\scriptsize O(N)\\)O(N) applications of the comparator comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + See also the implementations in libstdc++ and libc++. + + is_sorted_until \fB(1)\fP template + constexpr //< since C++20 ForwardIt is_sorted_until(ForwardIt first, ForwardIt last) { - if (first != last) { + return std::is_sorted_until(first, last, std::less<>()); + } + is_sorted_until \fB(2)\fP + template + constexpr //< since C++20 + ForwardIt is_sorted_until(ForwardIt first, ForwardIt last, Compare comp) + { + if (first != last) + { ForwardIt next = first; - while (++next != last) { - if (*next < *first) + while (++next != last) + { + if (comp(*next, *first)) return next; first = next; } } return last; } -.SH Second version - template< class ForwardIt, class Compare > - ForwardIt is_sorted_until(ForwardIt first, ForwardIt last, - Compare comp) - { - typedef std::iterator_traits::value_type value_type; - ForwardIt it = std::adjacent_find(begin, end, - [comp](const value_type &x, const value_type &y){ return comp(y, x); }); - return it == last ? last : it+1; - } .SH Example - + // Run this code - #include #include + #include + #include #include #include - + #include + int main() { std::random_device rd; std::mt19937 g(rd()); const int N = 6; int nums[N] = {3, 1, 4, 1, 5, 9}; - + const int min_sorted_size = 4; - int sorted_size = 0; - do { - std::random_shuffle(nums, nums + N, g); - int *sorted_end = std::is_sorted_until(nums, nums + N); + + for (int sorted_size = 0; sorted_size < min_sorted_size;) + { + std::shuffle(nums, nums + N, g); + int *const sorted_end = std::is_sorted_until(nums, nums + N); sorted_size = std::distance(nums, sorted_end); - - for (auto i : nums) std::cout << i << ' '; - std::cout << " : " << sorted_size << " initial sorted elements\\n"; - } while (sorted_size < min_sorted_size); + assert(sorted_size >= 1); + + for (const auto i : nums) + std::cout << i << ' '; + std::cout << ": " << sorted_size << " initial sorted elements\\n" + << std::string(sorted_size * 2 - 1, '^') << '\\n'; + } } .SH Possible output: - 4 1 9 5 1 3 : 1 initial sorted elements - 4 5 9 3 1 1 : 3 initial sorted elements - 9 3 1 4 5 1 : 1 initial sorted elements - 1 3 5 4 1 9 : 3 initial sorted elements - 5 9 1 1 3 4 : 2 initial sorted elements - 4 9 1 5 1 3 : 2 initial sorted elements - 1 1 4 9 5 3 : 4 initial sorted elements + 4 1 9 5 1 3 : 1 initial sorted elements + ^ + 4 5 9 3 1 1 : 3 initial sorted elements + ^^^^^ + 9 3 1 4 5 1 : 1 initial sorted elements + ^ + 1 3 5 4 1 9 : 3 initial sorted elements + ^^^^^ + 5 9 1 1 3 4 : 2 initial sorted elements + ^^^ + 4 9 1 5 1 3 : 2 initial sorted elements + ^^^ + 1 1 4 9 5 3 : 4 initial sorted elements + ^^^^^^^ .SH See also - is_sorted checks whether a range is sorted into ascending order - \fI(C++11)\fP \fI(function template)\fP + is_sorted checks whether a range is sorted into ascending order + \fI(C++11)\fP \fI(function template)\fP + ranges::is_sorted_until finds the largest sorted subrange + (C++20) (niebloid) diff --git a/man/std::is_standard_layout.3 b/man/std::is_standard_layout.3 index 13c1c2074..8bfcf71d0 100644 --- a/man/std::is_standard_layout.3 +++ b/man/std::is_standard_layout.3 @@ -1,37 +1,48 @@ -.TH std::is_standard_layout 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_standard_layout 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_standard_layout \- std::is_standard_layout + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_standard_layout; - If T is a standard layout type (that is, a scalar type, a standard-layout class, or - an array of such type/class, possibly cv-qualified), provides the member constant - value equal true. For any other type, value is false. + std::is_standard_layout is a UnaryTypeTrait. + + If T is a standard-layout type, provides the member constant value equal to true. + For any other type, value is false. + + If std::remove_all_extents_t is an incomplete type and not (possibly + cv-qualified) void, the behavior is undefined. - A standard-layout class is a class that + If the program adds specializations for std::is_standard_layout or + std::is_standard_layout_v, the behavior is undefined. - 1. has no non-static data members that aren't standard-layout +.SH Template parameters - 2. has no virtual functions and no virtual base classes + T - a type to check - 3. has the same access control for all non-static data members + Helper variable template - 4. has no base classes that aren't standard-layout + template< class T > + inline constexpr bool is_standard_layout_v = \fI(since C++17)\fP + is_standard_layout::value; - 5. either has no base class with non-static data members or has no non-static data - members in the most derived class and only one base with them - 6. has no base classes of the same type as the first non-static data member + +Inherited from std::integral_constant .SH Member constants - value true if T is a standard-layout type , false otherwise + value true if T is a standard-layout type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -47,50 +58,41 @@ If a standard-layout union holds two or more standard-layout structs, it is permitted to inspect the common initial part of them. - The macro offsetof can only be used with standard-layout classes. + The macro offsetof is only guaranteed to be usable with standard-layout classes. .SH Example - + // Run this code - #include #include - - struct A { - int m; - }; - - struct B { - int m1; - private: - int m2; - }; - - struct C { - virtual void foo(); - }; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_standard_layout::value << '\\n'; - std::cout << std::is_standard_layout::value << '\\n'; - std::cout << std::is_standard_layout::value << '\\n'; - } - -.SH Output: - - true - false - false + + struct A { int m; }; + static_assert(std::is_standard_layout_v == true); + + class B: public A { int m; }; + static_assert(std::is_standard_layout_v == false); + + struct C { virtual void foo(); }; + static_assert(std::is_standard_layout_v == false); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 T could be an array of incomplete the behavior is + class type with unknown bound undefined in this case .SH See also - is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP - is_pod checks if a type is plain-old data (POD) type - \fI(C++11)\fP \fI(class template)\fP - byte offset from the beginning of a standard-layout type to - offsetof specified member - \fI(function macro)\fP + is_trivially_copyable checks if a type is trivially copyable + \fI(C++11)\fP \fI(class template)\fP + is_pod checks if a type is a plain-old data (POD) type + \fI(C++11)\fP(deprecated in C++20) \fI(class template)\fP + byte offset from the beginning of a standard-layout + offsetof type to specified member + \fI(function macro)\fP diff --git a/man/std::is_swappable_with,std::is_swappable,std::is_nothrow_swappable_with,.3 b/man/std::is_swappable_with,std::is_swappable,std::is_nothrow_swappable_with,.3 new file mode 100644 index 000000000..99d24dfe1 --- /dev/null +++ b/man/std::is_swappable_with,std::is_swappable,std::is_nothrow_swappable_with,.3 @@ -0,0 +1,87 @@ +.TH std::is_swappable_with,std::is_swappable,std::is_nothrow_swappable_with, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_swappable_with,std::is_swappable,std::is_nothrow_swappable_with, \- std::is_swappable_with,std::is_swappable,std::is_nothrow_swappable_with, + +.SH Synopsis + + Defined in header + template< class T, class U > \fB(1)\fP \fI(since C++17)\fP + struct is_swappable_with; + template< class T > \fB(2)\fP \fI(since C++17)\fP + struct is_swappable; + template< class T, class U > \fB(3)\fP \fI(since C++17)\fP + struct is_nothrow_swappable_with; + template< class T > \fB(4)\fP \fI(since C++17)\fP + struct is_nothrow_swappable; + + 1) If the expressions swap(std::declval(), std::declval()) and + swap(std::declval(), std::declval()) are both well-formed in unevaluated + context after using std::swap; (see Swappable), provides the member constant value + equal true. Otherwise, value is false. + Access checks are performed as if from a context unrelated to either type. + 3) Same as \fB(1)\fP, but evaluations of both expressions from (1) are known not to throw + exceptions. + + The value of the member constant value + Type trait T is a referenceable type T is not a referenceable + type + \fB(2)\fP std::is_swappable_with::value false + \fB(4)\fP std::is_nothrow_swappable_with::value + + If T or U is not a complete type, (possibly cv-qualified) void, or an array of + unknown bound, the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + +.SH Member constants + + value true if T is swappable with U, false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + This trait does not check anything outside the immediate context of the swap + expressions: if the use of T or U would trigger template specializations, generation + of implicitly-defined special member functions etc, and those have errors, the + actual swap may not compile even if std::is_swappable_with::value compiles and + evaluates to true. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + is_move_assignable + is_trivially_move_assignable + is_nothrow_move_assignable checks if a type has a move assignment operator + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + swappable specifies that a type can be swapped or that two types + swappable_with can be swapped with each other + (C++20) (concept) + +.SH Category: + * Todo no example diff --git a/man/std::is_trivial.3 b/man/std::is_trivial.3 index 5efeb3ebe..947094404 100644 --- a/man/std::is_trivial.3 +++ b/man/std::is_trivial.3 @@ -1,22 +1,47 @@ -.TH std::is_trivial 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_trivial 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_trivial \- std::is_trivial + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_trivial; - If T is a trivial type (that is, a scalar type, a trivially copyable class with a - trivial default constructor, or array of such type/class, possibly cv-qualified), - provides the member constant value equal true. For any other type, value is false. + std::is_trivial is a UnaryTypeTrait. + + If T is a trivial type, provides the member constant value equal to true. For any + other type, value is false. + + If std::remove_all_extents_t is an incomplete type and not (possibly + cv-qualified) void, the behavior is undefined. + + If the program adds specializations for std::is_trivial or std::is_trivial_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_trivial_v = is_trivial::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a trivial type , false otherwise + value true if T is a trivial type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -24,49 +49,37 @@ value_type bool type std::integral_constant -.SH Notes +.SH Example - Only objects (including arrays) of trivial type may be created by a call to - std::malloc. -.SH Possible implementation +// Run this code - template< class T > - struct is_trivial : std::integral_constant< - bool, - std::is_trivially_copyable::value && - std::is_trivially_default_constructible::value - > {}; + #include -.SH Example + struct A { int m; }; + static_assert(std::is_trivial_v == true); - -// Run this code + struct B { B() {} }; + static_assert(std::is_trivial_v == false); - #include - #include - - struct A { - int m; - }; - - struct B { - B() {} - }; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_trivial::value << '\\n'; - std::cout << std::is_trivial::value << '\\n'; - } - -.SH Output: - - true - false + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 T could be an array of incomplete the behavior is + class type with unknown bound undefined in this case .SH See also - is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + is_trivially_copyable checks if a type is trivially copyable + \fI(C++11)\fP \fI(class template)\fP + is_default_constructible + is_trivially_default_constructible + is_nothrow_default_constructible checks if a type has a default constructor + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::is_trivially_copyable.3 b/man/std::is_trivially_copyable.3 index adfb6fb8d..9bae2aa51 100644 --- a/man/std::is_trivially_copyable.3 +++ b/man/std::is_trivially_copyable.3 @@ -1,37 +1,48 @@ -.TH std::is_trivially_copyable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_trivially_copyable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_trivially_copyable \- std::is_trivially_copyable + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_trivially_copyable; - If T is a trivially copyable type, provides the member constant value equal true. + std::is_trivially_copyable is a UnaryTypeTrait. + + If T is a trivially copyable type, provides the member constant value equal to true. For any other type, value is false. - The only trivially copyable types are scalar types, trivially copyable classes, and - arrays of such types/classes (possibly cv-qualified). + If std::remove_all_extents_t is an incomplete type and not (possibly + cv-qualified) void, the behavior is undefined. + + If the program adds specializations for std::is_trivially_copyable or + std::is_trivially_copyable_v, the behavior is undefined. - A trivially copyable class is a class that +.SH Template parameters - 1. Has no non-trivial copy constructors (this also requires no virtual functions or - virtual bases) + T - a type to check - 2. Has no non-trivial move constructors + Helper variable template - 3. Has no non-trivial copy assignment operators + template< class T > + inline constexpr bool is_trivially_copyable_v = \fI(since C++17)\fP + is_trivially_copyable::value; - 4. Has no non-trivial move assignment operators - 5. Has a trivial destructor + +Inherited from std::integral_constant .SH Member constants - value true if T is a trivially copyable type , false otherwise + value true if T is a trivially copyable type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -41,43 +52,47 @@ .SH Notes - Objects of trivially-copyable types are the only C++ objects that may be safely - copied with std::memcpy or serialized to/from binary files with - std::ofstream::write()/std::ifstream::read(). In general, a trivially copyable type - is any type for which the underlying bytes can be copied to an array of char or - unsigned char and into a new object of the same type, and the resulting object would - have the same value as the original. + Objects of trivially-copyable types that are not potentially-overlapping subobjects + are the only C++ objects that may be safely copied with std::memcpy or serialized + to/from binary files with std::ofstream::write() / std::ifstream::read(). .SH Example - + // Run this code - #include #include - - struct A { + + struct A { int m; }; + static_assert(std::is_trivially_copyable_v == true); + + struct B { B(B const&) {} }; + static_assert(std::is_trivially_copyable_v == false); + + struct C { virtual void foo(); }; + static_assert(std::is_trivially_copyable_v == false); + + struct D + { int m; + + D(D const&) = default; // -> trivially copyable + D(int x) : m(x + 1) {} }; - - struct B { - B(const B&) {} - }; - - struct C { - virtual void foo(); - }; - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_trivially_copyable::value << '\\n'; - std::cout << std::is_trivially_copyable::value << '\\n'; - std::cout << std::is_trivially_copyable::value << '\\n'; - } + static_assert(std::is_trivially_copyable_v == true); + + int main() {} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2015 C++11 T could be an array of incomplete the behavior is + class type with unknown bound undefined in this case -.SH Output: +.SH See also - true - false - false + is_trivial checks if a type is trivial + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_unbounded_array.3 b/man/std::is_unbounded_array.3 new file mode 100644 index 000000000..b98764cd3 --- /dev/null +++ b/man/std::is_unbounded_array.3 @@ -0,0 +1,94 @@ +.TH std::is_unbounded_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_unbounded_array \- std::is_unbounded_array + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + struct is_unbounded_array; + + std::is_unbounded_array is a UnaryTypeTrait. + + Checks whether T is an arrays of unknown bound. Provides the member constant value + which is equal to true, if T is an array type of unknown bound. Otherwise, value is + equal to false. + + If the program adds specializations for std::is_unbounded_array or + std::is_unbounded_array_v, the behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > + inline constexpr bool is_unbounded_array_v = \fI(since C++20)\fP + is_unbounded_array::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if T is an array type of unknown bound., false otherwise + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Possible implementation + + template + struct is_unbounded_array: std::false_type {}; + + template + struct is_unbounded_array : std::true_type {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bounded_array_traits 201902L (C++20) std::is_bounded_array, + std::is_unbounded_array + +.SH Example + + +// Run this code + + #include + + class A {}; + + static_assert + ("" + && std::is_unbounded_array_v == false + && std::is_unbounded_array_v == true + && std::is_unbounded_array_v == false + && std::is_unbounded_array_v == false + && std::is_unbounded_array_v == false + && std::is_unbounded_array_v == true + && std::is_unbounded_array_v == false + ); + + int main() {} + +.SH See also + + is_array checks if a type is an array type + \fI(C++11)\fP \fI(class template)\fP + is_bounded_array checks if a type is an array type of known bound + (C++20) \fI(class template)\fP + extent obtains the size of an array type along a specified dimension + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_union.3 b/man/std::is_union.3 index 0c54c8331..1bd21aa16 100644 --- a/man/std::is_union.3 +++ b/man/std::is_union.3 @@ -1,27 +1,44 @@ -.TH std::is_union 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_union 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_union \- std::is_union + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_union; - Checks whether T is an union type. Provides the member constant value which is equal - to true, if T is an union type . Otherwise, value is equal to false. + std::is_union is a UnaryTypeTrait. + + Checks whether T is a union type. Provides the member constant value, which is equal + to true if T is a union type. Otherwise, value is equal to false. + + If the program adds specializations for std::is_union or std::is_union_v, the + behavior is undefined. .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_union_v = is_union::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is a union type , false otherwise + value true if T is a union type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -31,23 +48,22 @@ Inherited from std::integral_constant .SH Example - + // Run this code #include #include - + struct A {}; - - typedef union { + + typedef union + { int a; float b; } B; - - struct C { - B d; - }; - + + struct C { B d; }; + int main() { std::cout << std::boolalpha; @@ -66,5 +82,5 @@ Inherited from std::integral_constant .SH See also - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_unsigned.3 b/man/std::is_unsigned.3 index 1ecaf4118..665726477 100644 --- a/man/std::is_unsigned.3 +++ b/man/std::is_unsigned.3 @@ -1,21 +1,47 @@ -.TH std::is_unsigned 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_unsigned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_unsigned \- std::is_unsigned + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_unsigned; - If T is an unsigned arithmetic type, provides the member constant value equal true. + std::is_unsigned is a UnaryTypeTrait. + + If T is an arithmetic type, provides the member constant value equal to true if T\fB(0)\fP + < T(-1): this results in true for the unsigned integer types and the type bool and + in false for the signed integer types and the floating-point types. + For any other type, value is false. + If the program adds specializations for std::is_unsigned or std::is_unsigned_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_unsigned_v = is_unsigned::value; + + + +Inherited from std::integral_constant + .SH Member constants - value true if T is an unsigned arithmetic type , false otherwise + value true if T is an unsigned integral type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -23,47 +49,68 @@ value_type bool type std::integral_constant +.SH Possible implementation + + namespace detail + { + template::value> + struct is_unsigned : std::integral_constant {}; + + template + struct is_unsigned : std::false_type {}; + } // namespace detail + + template + struct is_unsigned : detail::is_unsigned::type {}; + .SH Example - + // Run this code #include #include - + class A {}; + static_assert(std::is_unsigned_v == false); + enum B : unsigned {}; + static_assert(std::is_unsigned_v == false); + enum class C : unsigned {}; - + static_assert(std::is_unsigned_v == false); + + struct S { unsigned p : 1; int q : 1; }; + static_assert( + std::is_unsigned_v not_eq + std::is_unsigned_v + ); + + static_assert( + std::is_unsigned_v == false && + std::is_unsigned_v == false && + std::is_unsigned_v == true && + std::is_unsigned_v == true + ); + int main() { - std::cout << std::boolalpha; - std::cout << std::is_unsigned::value << '\\n'; - std::cout << std::is_unsigned::value << '\\n'; - std::cout << std::is_unsigned::value << '\\n'; - std::cout << std::is_unsigned::value << '\\n'; - std::cout << std::is_unsigned::value << '\\n'; - std::cout << std::is_unsigned::value << '\\n'; + std::cout << std::boolalpha << std::is_unsigned::value << '\\n'; } -.SH Output: +.SH Possible output: false - false - false - true - false - false .SH See also - is_signed checks if a type is signed arithmetic type - \fI(C++11)\fP \fI(class template)\fP - is_floating_point checks if a type is floating-point type - \fI(C++11)\fP \fI(class template)\fP - is_integral checks if a type is integral type - \fI(C++11)\fP \fI(class template)\fP - make_signed makes the given integral type signed - \fI(C++11)\fP \fI(class template)\fP - make_unsigned makes the given integral type unsigned - \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_signed identifies signed types + \fB[static]\fP \fI(public static member constant of std::numeric_limits)\fP + is_arithmetic checks if a type is an arithmetic type + \fI(C++11)\fP \fI(class template)\fP + make_signed makes the given integral type signed + \fI(C++11)\fP \fI(class template)\fP + make_unsigned makes the given integral type unsigned + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_void.3 b/man/std::is_void.3 index 24e7a3452..02e319ee6 100644 --- a/man/std::is_void.3 +++ b/man/std::is_void.3 @@ -1,28 +1,45 @@ -.TH std::is_void 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_void 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_void \- std::is_void + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_void; + std::is_void is a UnaryTypeTrait. + Checks whether T is a void type. Provides the member constant value that is equal to true, if T is the type void, const void, volatile void, or const volatile void. Otherwise, value is equal to false. + If the program adds specializations for std::is_void or std::is_void_v, the behavior + is undefined. + .SH Template parameters T - a type to check + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_void_v = is_void::value; + + + Inherited from std::integral_constant .SH Member constants - value true if T is the type void (possibly cv-qualified) , false otherwise + value true if T is the type void (possibly cv-qualified), false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -32,45 +49,44 @@ Inherited from std::integral_constant .SH Possible implementation - template< class T > - struct is_void : std::integral_constant< - bool, - std::is_same::type>::value - > {}; + template + struct is_void : std::is_same::type> {}; .SH Example - + // Run this code - #include #include - - int main() - { - std::cout << std::boolalpha; - std::cout << std::is_void::value << '\\n'; - std::cout << std::is_void::value << '\\n'; - } -.SH Output: + void foo(); + + static_assert + ( + std::is_void_v == true and + std::is_void_v == true and + std::is_void_v == true and + std::is_void_v == false and + std::is_void_v == false and + std::is_void_v == false and + std::is_void_v> == false + ); - true - false + int main() {} .SH See also is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP is_enum checks if a type is an enumeration type - \fI(C++11)\fP \fI(class template)\fP - is_union checks if a type is an union type - \fI(C++11)\fP \fI(class template)\fP - is_class checks if a type is a class type (but not union type) - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_union checks if a type is a union type + \fI(C++11)\fP \fI(class template)\fP + is_class checks if a type is a non-union class type + \fI(C++11)\fP \fI(class template)\fP is_function checks if a type is a function type - \fI(C++11)\fP \fI(class template)\fP - is_object checks if a type is object type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + is_object checks if a type is an object type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_volatile.3 b/man/std::is_volatile.3 index 68296ae23..b8d0984b8 100644 --- a/man/std::is_volatile.3 +++ b/man/std::is_volatile.3 @@ -1,21 +1,44 @@ -.TH std::is_volatile 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::is_volatile 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_volatile \- std::is_volatile + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct is_volatile; + std::is_volatile is a UnaryTypeTrait. + If T is a volatile-qualified type (that is, volatile, or const volatile), provides - the member constant value equal true. For any other type, value is false. + the member constant value equal to true. For any other type, value is false. + + If the program adds specializations for std::is_volatile or std::is_volatile_v, the + behavior is undefined. + +.SH Template parameters + + T - a type to check + + Helper variable template + + template< class T > \fI(since C++17)\fP + inline constexpr bool is_volatile_v = is_volatile::value; + + + +Inherited from std::integral_constant .SH Member constants - value true if T is a volatile-qualified type , false otherwise + value true if T is a volatile-qualified type, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -25,30 +48,26 @@ .SH Possible implementation - template struct is_volatile : std::false_type {}; + template struct is_volatile : std::false_type {}; template struct is_volatile : std::true_type {}; .SH Example - + // Run this code - #include #include - - int main() - { - std::cout << boolalpha; - std::cout << std::is_volatile::value << '\\n'; - std::cout << std::is_volatile::value << '\\n'; - } + #include -.SH Output: + static_assert(!std::is_volatile_v); + static_assert(std::is_volatile_v); + static_assert(std::is_volatile_v); + static_assert(std::is_volatile_v>); + static_assert(!std::is_volatile_v>); - false - true + int main() {} .SH See also is_const checks if a type is const-qualified - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::is_within_lifetime.3 b/man/std::is_within_lifetime.3 new file mode 100644 index 000000000..b5b2c562b --- /dev/null +++ b/man/std::is_within_lifetime.3 @@ -0,0 +1,74 @@ +.TH std::is_within_lifetime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::is_within_lifetime \- std::is_within_lifetime + +.SH Synopsis + Defined in header + template< class T > (since C++26) + consteval bool is_within_lifetime( const T* ptr ) noexcept; + + Determines whether the pointer ptr points to an object that is within its lifetime. + + During the evaluation of an expression E as a core constant expression, a call to + std::is_within_lifetime is ill-formed unless ptr points to an object + + * that is usable in constant expressions, or + * whose complete object’s lifetime began within E. + +.SH Parameters + + p - pointer to detect + +.SH Return value + + true if pointer ptr points to an object that is within its lifetime; otherwise + false. + +.SH Example + + std::is_within_lifetime can be used to check whether a union member is active: + + +// Run this code + + #include + + // an optional boolean type occupying only one byte, + // assuming sizeof(bool) == sizeof(char) + struct optional_bool + { + union { bool b; char c; }; + + // assuming the value representations for true and false + // are distinct from the value representation for 2 + constexpr optional_bool() : c(2) {} + constexpr optional_bool(bool b) : b(b) {} + + constexpr auto has_value() const -> bool + { + if consteval + { + return std::is_within_lifetime(&b); // during constant evaluation, + // cannot read from c + } + else + { + return c != 2; // during runtime, must read from c + } + } + + constexpr auto operator*() -> bool& + { + return b; + } + }; + + int main() + { + constexpr optional_bool disengaged; + constexpr optional_bool engaged(true); + + static_assert(!disengaged.has_value()); + static_assert(engaged.has_value()); + static_assert(*engaged); + } diff --git a/man/std::isalnum(std::locale).3 b/man/std::isalnum(std::locale).3 index d488e92f1..26632d062 100644 --- a/man/std::isalnum(std::locale).3 +++ b/man/std::isalnum(std::locale).3 @@ -1,11 +1,14 @@ -.TH std::isalnum(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isalnum(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isalnum(std::locale) \- std::isalnum(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isalnum( charT ch, const locale& loc ); + template< class CharT > + bool isalnum( CharT ch, const locale& loc ); - Checks if the given character classified as an alphanumeric character by the given - locale's std::ctype facet. + Checks if the given character is classified as an alphanumeric character by the + given locale's std::ctype facet. .SH Parameters @@ -18,41 +21,43 @@ .SH Possible implementation - template< class charT > - bool isalnum( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::alnum, ch); + template + bool isalnum(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::alnum, ch); } .SH Example Demonstrates the use of isalnum() with different locales (OS-specific). - + // Run this code #include #include + int main() { const wchar_t c = L'\\u2135'; // mathematical symbol aleph - + std::locale loc1("C"); std::cout << "isalnum('ℵ', C locale) returned " - << std::boolalpha << std::isalnum(c, loc1) << '\\n'; - + << std::boolalpha << std::isalnum(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF-8"); std::cout << "isalnum('ℵ', Unicode locale) returned " << std::boolalpha << std::isalnum(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: - isalpha('ℵ', C locale) returned false - isalpha('ℵ', Unicode locale) returned true + isalnum('ℵ', C locale) returned false + isalnum('ℵ', Unicode locale) returned true .SH See also isalnum checks if a character is alphanumeric - \fI(function)\fP + \fI(function)\fP iswalnum checks if a wide character is alphanumeric - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isalnum.3 b/man/std::isalnum.3 index 03ee9d274..1c20c47fb 100644 --- a/man/std::isalnum.3 +++ b/man/std::isalnum.3 @@ -1,4 +1,7 @@ -.TH std::isalnum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isalnum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isalnum \- std::isalnum + .SH Synopsis Defined in header int isalnum( int ch ); @@ -19,34 +22,59 @@ .SH Return value - Non-zero value (true) if the character is an alphanumeric character, 0 (false) - otherwise. + Non-zero value if the character is an alphanumeric character, 0 otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isalnum is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isalnum(char ch) + { + return std::isalnum(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_alnums(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isalnum) // wrong + // [](int c){ return std::isalnum(c); } // wrong + // [](char c){ return std::isalnum(c); } // wrong + [](unsigned char c){ return std::isalnum(c); } // correct + ); + } .SH Example - Demonstrates the use of isalnum() with different locales (OS-specific). + Demonstrates the use of std::isalnum with different locales (OS-specific). + - // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xdf'; // German letter ß in ISO-8859-1 - + std::cout << "isalnum(\\'\\\\xdf\\', default C locale) returned " - << std::boolalpha << (bool)std::isalnum(c) << '\\n'; - - std::setlocale(LC_ALL, "de_DE.iso88591"); - std::cout << "isalnum(\\'\\\\xdf\\', ISO-8859-1 locale) returned " - << std::boolalpha << (bool)std::isalnum(c) << '\\n'; - + << std::boolalpha << static_cast(std::isalnum(c)) << '\\n'; + + if (std::setlocale(LC_ALL, "de_DE.iso88591")) + std::cout << "isalnum(\\'\\\\xdf\\', ISO-8859-1 locale) returned " + << static_cast(std::isalnum(c)) << '\\n'; + } -.SH Output: +.SH Possible output: isalnum('\\xdf', default C locale) returned false isalnum('\\xdf', ISO-8859-1 locale) returned true @@ -54,29 +82,32 @@ .SH See also isalnum(std::locale) checks if a character is classified as alphanumeric by a locale - \fI(function template)\fP + \fI(function template)\fP iswalnum checks if a wide character is alphanumeric - \fI(function)\fP + \fI(function)\fP C documentation for isalnum - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isalpha(std::locale).3 b/man/std::isalpha(std::locale).3 index 87c69a0d7..cff957626 100644 --- a/man/std::isalpha(std::locale).3 +++ b/man/std::isalpha(std::locale).3 @@ -1,10 +1,13 @@ -.TH std::isalpha(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isalpha(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isalpha(std::locale) \- std::isalpha(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isalpha( charT ch, const locale& loc ); + template< class CharT > + bool isalpha( CharT ch, const locale& loc ); - Checks if the given character classified as an alphabetic character by the given + Checks if the given character is classified as an alphabetic character by the given locale's std::ctype facet. .SH Parameters @@ -18,34 +21,36 @@ .SH Possible implementation - template< class charT > - bool isalpha( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::alpha, ch); + template + bool isalpha(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::alpha, ch); } .SH Example Demonstrates the use of isalpha() with different locales (OS-specific). - + // Run this code #include #include + int main() { const wchar_t c = L'\\u042f'; // cyrillic capital letter ya - + std::locale loc1("C"); std::cout << "isalpha('Я', C locale) returned " - << std::boolalpha << std::isalpha(c, loc1) << '\\n'; - + << std::boolalpha << std::isalpha(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF8"); std::cout << "isalpha('Я', Unicode locale) returned " << std::boolalpha << std::isalpha(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: isalpha('Я', C locale) returned false isalpha('Я', Unicode locale) returned true @@ -53,6 +58,6 @@ .SH See also isalpha checks if a character is alphabetic - \fI(function)\fP + \fI(function)\fP iswalpha checks if a wide character is alphabetic - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isalpha.3 b/man/std::isalpha.3 index 6699545ee..13d0b2739 100644 --- a/man/std::isalpha.3 +++ b/man/std::isalpha.3 @@ -1,19 +1,22 @@ -.TH std::isalpha 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isalpha 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isalpha \- std::isalpha + .SH Synopsis Defined in header int isalpha( int ch ); Checks if the given character is an alphabetic character as classified by the currently installed C locale. In the default locale, the following characters are - alphanumeric: + alphabetic: * uppercase letters ABCDEFGHIJKLMNOPQRSTUVWXYZ * lowercase letters abcdefghijklmnopqrstuvwxyz In locales other than "C", an alphabetic character is a character for which - std::isupper() or std::islower() returns true or any other character considered + std::isupper() or std::islower() returns non-zero or any other character considered alphabetic by the locale. In any case, std::iscntrl(), std::isdigit(), - std::ispunct() and std::isspace() will return false for this character. + std::ispunct() and std::isspace() will return zero for this character. The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF. @@ -24,32 +27,59 @@ .SH Return value - Non-zero value (true) if the character is an alphabetic character, 0 (false) - otherwise. + Non-zero value if the character is an alphabetic character, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isalpha is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isalpha(char ch) + { + return std::isalpha(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_alphas(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isalpha) // wrong + // [](int c){ return std::isalpha(c); } // wrong + // [](char c){ return std::isalpha(c); } // wrong + [](unsigned char c){ return std::isalpha(c); } // correct + ); + } .SH Example - + Demonstrates the use of std::isalpha with different locales (OS-specific). + + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xdf'; // German letter ß in ISO-8859-1 - + std::cout << "isalpha(\\'\\\\xdf\\', default C locale) returned " - << std::boolalpha << (bool)std::isalpha(c) << '\\n'; - + << std::boolalpha << !!std::isalpha(c) << '\\n'; + std::setlocale(LC_ALL, "de_DE.iso88591"); std::cout << "isalpha(\\'\\\\xdf\\', ISO-8859-1 locale) returned " - << std::boolalpha << (bool)std::isalpha(c) << '\\n'; - + << static_cast(std::isalpha(c)) << '\\n'; + } -.SH Output: +.SH Possible output: isalpha('\\xdf', default C locale) returned false isalpha('\\xdf', ISO-8859-1 locale) returned true @@ -57,29 +87,32 @@ .SH See also isalpha(std::locale) checks if a character is classified as alphabetic by a locale - \fI(function template)\fP + \fI(function template)\fP iswalpha checks if a wide character is alphabetic - \fI(function)\fP + \fI(function)\fP C documentation for isalpha - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isblank(std::locale).3 b/man/std::isblank(std::locale).3 index d929937bb..9f1432209 100644 --- a/man/std::isblank(std::locale).3 +++ b/man/std::isblank(std::locale).3 @@ -1,11 +1,14 @@ -.TH std::isblank(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isblank(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isblank(std::locale) \- std::isblank(std::locale) + .SH Synopsis Defined in header - template< class charT > \fI(since C++11)\fP - bool isblank( charT ch, const locale& loc ); + template< class CharT > \fI(since C++11)\fP + bool isblank( CharT ch, const locale& loc ); Checks if the given character is classified as a blank character by the given - locale's ctype facet. + locale's std::ctype facet. .SH Parameters @@ -18,26 +21,29 @@ .SH Possible implementation - template< class charT > - bool isblank( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::blank, ch); + template + bool isblank(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::blank, ch); } .SH Example Demonstrates the use of isblank() with different locales (OS-specific). - + // Run this code #include #include - + void try_with(wchar_t c, const char* loc) { - std::wcout << "isblank('" << c << "', locale(\\"" << loc << "\\")) returned " << std::boolalpha + std::wcout << "isblank('" << c << "', locale(\\"" << loc << "\\")) returned " + << std::boolalpha << std::isblank(c, std::locale(loc)) << '\\n'; } + int main() { const wchar_t IDEO_SPACE = L'\\u3000'; // Unicode character 'IDEOGRAPHIC SPACE' @@ -45,7 +51,7 @@ try_with(IDEO_SPACE, "en_US.UTF-8"); } -.SH Output: +.SH Possible output: isblank(' ', locale("C")) returned false isblank(' ', locale("en_US.UTF-8")) returned true @@ -53,6 +59,6 @@ .SH See also isblank checks if a character is a blank character - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP iswblank checks if a wide character is a blank character - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::isblank.3 b/man/std::isblank.3 index e8c5476ed..a855c11cc 100644 --- a/man/std::isblank.3 +++ b/man/std::isblank.3 @@ -1,4 +1,7 @@ -.TH std::isblank 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isblank 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isblank \- std::isblank + .SH Synopsis Defined in header int isblank( int ch ); \fI(since C++11)\fP @@ -17,35 +20,64 @@ .SH Return value - Non-zero value (true) if the character is a blank character, 0 (false) otherwise. + Non-zero value if the character is a blank character, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isblank is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isblank(char ch) + { + return std::isblank(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_blanks(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isblank) // wrong + // [](int c){ return std::isblank(c); } // wrong + // [](char c){ return std::isblank(c); } // wrong + [](unsigned char c){ return std::isblank(c); } // correct + ); + } .SH See also isblank(std::locale) checks if a character is classified as a blank character by a \fI(C++11)\fP locale - \fI(function template)\fP + \fI(function template)\fP iswblank checks if a wide character is a blank character - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP C documentation for isblank - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iscntrl(std::locale).3 b/man/std::iscntrl(std::locale).3 index 227337ce8..bce2c7421 100644 --- a/man/std::iscntrl(std::locale).3 +++ b/man/std::iscntrl(std::locale).3 @@ -1,10 +1,13 @@ -.TH std::iscntrl(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iscntrl(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iscntrl(std::locale) \- std::iscntrl(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool iscntrl( charT ch, const locale& loc ); + template< class CharT > + bool iscntrl( CharT ch, const locale& loc ); - Checks if the given character classified as a control character by the given + Checks if the given character is classified as a control character by the given locale's std::ctype facet. .SH Parameters @@ -18,34 +21,36 @@ .SH Possible implementation - template< class charT > - bool iscntrl( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::cntrl, ch); + template + bool iscntrl(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::cntrl, ch); } .SH Example Demonstrates the use of iscntrl() with different locales (OS-specific). - + // Run this code #include #include + int main() { const wchar_t CCH = L'\\u0094'; // Destructive Backspace in Unicode - + std::locale loc1("C"); std::cout << "iscntrl(CCH, C locale) returned " << std::boolalpha << std::iscntrl(CCH, loc1) << '\\n'; - + std::locale loc2("en_US.UTF8"); std::cout << "iscntrl(CCH, Unicode locale) returned " << std::boolalpha << std::iscntrl(CCH, loc2) << '\\n'; } -.SH Output: +.SH Possible output: iscntrl(CCH, C locale) returned false iscntrl(CCH, Unicode locale) returned true @@ -53,6 +58,6 @@ .SH See also iscntrl checks if a character is a control character - \fI(function)\fP + \fI(function)\fP iswcntrl checks if a wide character is a control character - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::iscntrl.3 b/man/std::iscntrl.3 index 9070837e9..a65434e14 100644 --- a/man/std::iscntrl.3 +++ b/man/std::iscntrl.3 @@ -1,4 +1,7 @@ -.TH std::iscntrl 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iscntrl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iscntrl \- std::iscntrl + .SH Synopsis Defined in header int iscntrl( int ch ); @@ -16,31 +19,57 @@ .SH Return value - Non-zero value (true) if the character is a control character, 0 (false) otherwise. + Non-zero value if the character is a control character, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::iscntrl is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_iscntrl(char ch) + { + return std::iscntrl(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_cntrls(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::iscntrl) // wrong + // [](int c){ return std::iscntrl(c); } // wrong + // [](char c){ return std::iscntrl(c); } // wrong + [](unsigned char c){ return std::iscntrl(c); } // correct + ); + } .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\x94'; // the control code CCH in ISO-8859-1 - + std::cout << "iscntrl(\\'\\\\x94\\', default C locale) returned " - << std::boolalpha << (bool)std::iscntrl(c) << '\\n'; - + << std::boolalpha << !!std::iscntrl(c) << '\\n'; + std::setlocale(LC_ALL, "en_GB.iso88591"); std::cout << "iscntrl(\\'\\\\x94\\', ISO-8859-1 locale) returned " - << std::boolalpha << (bool)std::iscntrl(c) << '\\n'; - + << !!std::iscntrl(c) << '\\n'; + } -.SH Output: +.SH Possible output: iscntrl('\\x94', default C locale) returned false iscntrl('\\x94', ISO-8859-1 locale) returned true @@ -49,29 +78,32 @@ checks if a character is classified as a control character by a iscntrl(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP iswcntrl checks if a wide character is a control character - \fI(function)\fP + \fI(function)\fP C documentation for iscntrl - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isdigit(std::locale).3 b/man/std::isdigit(std::locale).3 index a2c1cd6e4..2ff31f48e 100644 --- a/man/std::isdigit(std::locale).3 +++ b/man/std::isdigit(std::locale).3 @@ -1,8 +1,11 @@ -.TH std::isdigit(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isdigit(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isdigit(std::locale) \- std::isdigit(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isdigit( charT ch, const locale& loc ); + template< class CharT > + bool isdigit( CharT ch, const locale& loc ); Checks if the given character is classified as a digit by the given locale's std::ctype facet. @@ -18,48 +21,52 @@ .SH Possible implementation - template< class charT > - bool isdigit( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::digit, ch); + template + bool isdigit(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::digit, ch); } .SH Example - + // Run this code #include #include #include - #include - + #include + struct jdigit_ctype : std::ctype { - std::set jdigits{L'一',L'二',L'三',L'四',L'五',L'六',L'七',L'八',L'九',L'十'}; - bool do_is(mask m, char_type c) const { - if ((m & digit) && jdigits.count(c)) - return true; // Japanese digits will be classified as digits - return ctype::do_is(m, c); // leave the rest to the parent class + std::unordered_set jdigits{ + L'一', L'二', L'三', L'四', L'五', L'六', L'七', L'八', L'九', L'十' + }; + + bool do_is(mask m, char_type c) const override + { + return (m & digit) && jdigits.contains(c) + ? true // Japanese digits will be classified as digits + : ctype::do_is(m, c); // leave the rest to the parent class } }; - + int main() { - std::wstring text = L"123一二三１２３"; std::locale loc(std::locale(""), new jdigit_ctype); - - std::locale::global(std::locale("")); + + std::locale::global(std::locale("en_US.utf8")); std::wcout.imbue(std::locale()); - - for(wchar_t c : text) - if(std::isdigit(c, loc)) + + for (const wchar_t c : text) + if (std::isdigit(c, loc)) std::wcout << c << " is a digit\\n"; else std::wcout << c << " is NOT a digit\\n"; } -.SH Output: +.SH Possible output: 1 is a digit 2 is a digit @@ -74,6 +81,6 @@ .SH See also isdigit checks if a character is a digit - \fI(function)\fP + \fI(function)\fP iswdigit checks if a wide character is a digit - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isdigit.3 b/man/std::isdigit.3 index 7b4971cad..b453edb7e 100644 --- a/man/std::isdigit.3 +++ b/man/std::isdigit.3 @@ -1,4 +1,7 @@ -.TH std::isdigit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isdigit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isdigit \- std::isdigit + .SH Synopsis Defined in header int isdigit( int ch ); @@ -14,7 +17,7 @@ .SH Return value - Non-zero value (true) if the character is a numeric character, 0 (false) otherwise. + Non-zero value if the character is a numeric character, zero otherwise. .SH Notes @@ -23,32 +26,59 @@ implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits. + Like all other functions from , the behavior of std::isdigit is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isdigit(char ch) + { + return std::isdigit(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_digits(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isdigit) // wrong + // [](int c){ return std::isdigit(c); } // wrong + // [](char c){ return std::isdigit(c); } // wrong + [](unsigned char c){ return std::isdigit(c); } // correct + ); + } + .SH See also isdigit(std::locale) checks if a character is classified as a digit by a locale - \fI(function template)\fP + \fI(function template)\fP iswdigit checks if a wide character is a digit - \fI(function)\fP + \fI(function)\fP C documentation for isdigit - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isfinite.3 b/man/std::isfinite.3 index 24651aa3b..0aaee1860 100644 --- a/man/std::isfinite.3 +++ b/man/std::isfinite.3 @@ -1,28 +1,83 @@ -.TH std::isfinite 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isfinite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isfinite \- std::isfinite + .SH Synopsis Defined in header - bool isfinite( float arg ); \fI(since C++11)\fP - bool isfinite( double arg ); \fI(since C++11)\fP - bool isfinite( long double arg ); \fI(since C++11)\fP + bool isfinite( float num ); + \fI(since C++11)\fP + bool isfinite( double num ); (until C++23) + + bool isfinite( long double num ); + constexpr bool isfinite( /* floating-point-type */ \fB(1)\fP (since C++23) + num ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + bool isfinite( Integer num ); (constexpr since C++23) - Determines if the given floating point number arg has finite value i.e. it is - normal, subnormal or zero, but not infinite or NAN. + 1) Determines if the given floating point number num has finite value i.e. it is + normal, subnormal or zero, but not infinite or NaN. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameter num. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. .SH Parameters - arg - floating point value + num - floating-point or integer value .SH Return value - true value if arg has finite value, false otherwise + true if num has finite value, false otherwise. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::isfinite(num) has the same effect as std::isfinite(static_cast(num)). + +.SH Examples + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha + << "isfinite(NaN) = " << std::isfinite(NAN) << '\\n' + << "isfinite(Inf) = " << std::isfinite(INFINITY) << '\\n' + << "isfinite(-Inf) = " << std::isfinite(-INFINITY) << '\\n' + << "isfinite(HUGE_VAL) = " << std::isfinite(HUGE_VAL) << '\\n' + << "isfinite(0.0) = " << std::isfinite(0.0) << '\\n' + << "isfinite(exp(800)) = " << std::isfinite(std::exp(800)) << '\\n' + << "isfinite(DBL_MIN/2.0) = " << std::isfinite(DBL_MIN / 2.0) << '\\n'; + } + +.SH Output: + + isfinite(NaN) = false + isfinite(Inf) = false + isfinite(-Inf) = false + isfinite(HUGE_VAL) = false + isfinite(0.0) = true + isfinite(exp(800)) = false + isfinite(DBL_MIN/2.0) = true .SH See also - fpclassify categorizes the given floating point value - \fI(C++11)\fP \fI(function)\fP + fpclassify categorizes the given floating-point value + \fI(C++11)\fP \fI(function)\fP isinf checks if the given number is infinite - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnan checks if the given number is NaN - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnormal checks if the given number is normal - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + isfinite diff --git a/man/std::isgraph(std::locale).3 b/man/std::isgraph(std::locale).3 index 81d5a359e..7d68c340f 100644 --- a/man/std::isgraph(std::locale).3 +++ b/man/std::isgraph(std::locale).3 @@ -1,10 +1,13 @@ -.TH std::isgraph(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isgraph(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isgraph(std::locale) \- std::isgraph(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isgraph( charT ch, const locale& loc ); + template< class CharT > + bool isgraph( CharT ch, const locale& loc ); - Checks if the given character classified as a graphic character (i.e. printable, + Checks if the given character is classified as a graphic character (i.e. printable, excluding space) by the given locale's std::ctype facet. .SH Parameters @@ -18,34 +21,36 @@ .SH Possible implementation - template< class charT > - bool isgraph( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::graph, ch); + template + bool isgraph(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::graph, ch); } .SH Example Demonstrates the use of isgraph() with different locales (OS-specific). - + // Run this code #include #include + int main() { const wchar_t c = L'\\u2a0c'; // quadruple integral - + std::locale loc1("C"); std::cout << "isgraph('⨌', C locale) returned " - << std::boolalpha << std::isgraph(c, loc1) << '\\n'; - + << std::boolalpha << std::isgraph(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF-8"); std::cout << "isgraph('⨌', Unicode locale) returned " << std::boolalpha << std::isgraph(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: isgraph('⨌', C locale) returned false isgraph('⨌', Unicode locale) returned true @@ -53,6 +58,6 @@ .SH See also isgraph checks if a character is a graphical character - \fI(function)\fP + \fI(function)\fP iswgraph checks if a wide character is a graphical character - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isgraph.3 b/man/std::isgraph.3 index b69c6e0f2..8f9733df2 100644 --- a/man/std::isgraph.3 +++ b/man/std::isgraph.3 @@ -1,4 +1,7 @@ -.TH std::isgraph 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isgraph 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isgraph \- std::isgraph + .SH Synopsis Defined in header int isgraph( int ch ); @@ -21,61 +24,90 @@ .SH Return value - Non-zero value (true) if the character has a graphical representation character, 0 - (false) otherwise. + Non-zero value if the character has a graphical representation character, zero + otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isgraph is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isgraph(char ch) + { + return std::isgraph(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_graphs(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isgraph) // wrong + // [](int c){ return std::isgraph(c); } // wrong + // [](char c){ return std::isgraph(c); } // wrong + [](unsigned char c){ return std::isgraph(c); } // correct + ); + } .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xb6'; // the character ¶ in ISO-8859-1 - + std::cout << "isgraph(\\'\\\\xb6\\', default C locale) returned " - << std::boolalpha << (bool)std::isgraph(c) << '\\n'; - + << std::boolalpha << (bool)std::isgraph(c) << '\\n'; + std::setlocale(LC_ALL, "en_GB.iso88591"); std::cout << "isgraph(\\'\\\\xb6\\', ISO-8859-1 locale) returned " << std::boolalpha << (bool)std::isgraph(c) << '\\n'; } -.SH Output: +.SH Possible output: isgraph('\\xb6', default C locale) returned false isgraph('\\xb6', ISO-8859-1 locale) returned true .SH See also - isgraph(std::locale) checks if a character is classfied as graphical by a locale - \fI(function template)\fP + isgraph(std::locale) checks if a character is classified as graphical by a locale + \fI(function template)\fP iswgraph checks if a wide character is a graphical character - \fI(function)\fP + \fI(function)\fP C documentation for isgraph - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isgreater.3 b/man/std::isgreater.3 index 889686a1e..4a3e5f896 100644 --- a/man/std::isgreater.3 +++ b/man/std::isgreater.3 @@ -1,30 +1,78 @@ -.TH std::isgreater 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isgreater 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isgreater \- std::isgreater + .SH Synopsis Defined in header - bool isgreater( float x, float y ); \fI(since C++11)\fP - bool isgreater( double x, double y ); \fI(since C++11)\fP - bool isgreater( long double x, long double y ); \fI(since C++11)\fP + bool isgreater( float x, float y ); + \fI(since C++11)\fP + bool isgreater( double x, double y ); (until C++23) + + bool isgreater( long double x, long double y ); + constexpr bool isgreater( /* floating-point-type */ + x, \fB(1)\fP (since C++23) + /* floating-point-type */ + y ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > (A) \fI(since C++11)\fP + bool isgreater( Arithmetic1 x, Arithmetic2 y ); (constexpr since C++23) - Determines if the floating point number x is greater than the floating-point number - (y), without setting floating-point exceptions. + 1) Determines if the floating point number x is greater than the floating-point + number y, without setting floating-point exceptions. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. .SH Parameters - x - floating point value - y - floating point value + x, y - floating-point or integer values .SH Return value - true if x > y, false otherwise + true if x > y, false otherwise. .SH Notes The built-in operator> for floating-point numbers may set FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator>. + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::isgreater(num1, + num2) has the same effect as std::isgreater(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::isgreater(num1, num2) has the same effect as (until C++23) + std::isgreater(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::isgreater(num1, num2) has the same effect as + std::isgreater(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::isgreater(num1, + num2) has the same effect as std::isgreater(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + .SH See also greater function object implementing x > y - \fI(class template)\fP + \fI(class template)\fP isless checks if the first floating-point argument is less than the second - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + isgreater diff --git a/man/std::isgreaterequal.3 b/man/std::isgreaterequal.3 index 8007a1e97..d7460be4b 100644 --- a/man/std::isgreaterequal.3 +++ b/man/std::isgreaterequal.3 @@ -1,31 +1,79 @@ -.TH std::isgreaterequal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isgreaterequal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isgreaterequal \- std::isgreaterequal + .SH Synopsis Defined in header - bool isgreaterequal( float x, float y ); \fI(since C++11)\fP - bool isgreaterequal( double x, double y ); \fI(since C++11)\fP - bool isgreaterequal( long double x, long double y ); \fI(since C++11)\fP + bool isgreaterequal( float x, float y ); + \fI(since C++11)\fP + bool isgreaterequal( double x, double y ); (until C++23) + + bool isgreaterequal( long double x, long double y ); + constexpr bool isgreaterequal( /* + floating-point-type */ x, \fB(1)\fP (since C++23) + /* + floating-point-type */ y ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > (A) \fI(since C++11)\fP + bool isgreaterequal( Arithmetic1 x, Arithmetic2 y ); (constexpr since C++23) - Determines if the floating point number x is greater than or equal to the + 1) Determines if the floating point number x is greater than or equal to the floating-point number y, without setting floating-point exceptions. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. .SH Parameters - x - floating point value - y - floating point value + x, y - floating-point or integer values .SH Return value - true if x >= y, false otherwise + true if x >= y, false otherwise. .SH Notes The built-in operator>= for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator>=. + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::isgreaterequal(num1, + num2) has the same effect as std::isgreaterequal(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, then + std::isgreaterequal(num1, num2) has the same effect as (until + std::isgreaterequal(static_cast(num1), C++23) + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::isgreaterequal(num1, + num2) has the same effect as + std::isgreaterequal(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::isgreaterequal(num1, num2) + has the same effect as std::isgreaterequal(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point (since + conversion subrank between the types of num1 and num2, arguments of integer C++23) + type are considered to have the same floating-point conversion rank as + double. + + If no such floating-point type with the greatest rank and subrank exists, + then overload resolution does not result in a usable candidate from the + overloads provided. + .SH See also greater_equal function object implementing x >= y - \fI(class template)\fP + \fI(class template)\fP islessequal checks if the first floating-point argument is less or equal than the \fI(C++11)\fP second - \fI(function)\fP + \fI(function)\fP + C documentation for + isgreaterequal diff --git a/man/std::isinf.3 b/man/std::isinf.3 index 975fc2d82..45e0b0e1c 100644 --- a/man/std::isinf.3 +++ b/man/std::isinf.3 @@ -1,27 +1,92 @@ -.TH std::isinf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isinf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isinf \- std::isinf + .SH Synopsis Defined in header - bool isinf( float arg ); \fI(since C++11)\fP - bool isinf( double arg ); \fI(since C++11)\fP - bool isinf( long double arg ); \fI(since C++11)\fP + bool isinf( float num ); + \fI(since C++11)\fP + bool isinf( double num ); (until C++23) + + bool isinf( long double num ); + constexpr bool isinf( /* floating-point-type */ num \fB(1)\fP (since C++23) + ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + bool isinf( Integer num ); (constexpr since C++23) - Determines if the given floating point number arg is positive or negative infinity. + 1) Determines if the given floating-point number num is a positive or negative + infinity. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameter num. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. .SH Parameters - arg - floating point value + num - floating-point or integer value .SH Return value - true if arg is infinite, false otherwise + true if num is infinite, false otherwise. + +.SH Notes + + GCC and Clang support a -ffinite-math option (additionally implied by -ffast-math), + which allows the respective compiler to assume the nonexistence of special IEEE-754 + floating point values such as NaN, infinity, or negative zero. In other words, + std::isinf is assumed to always return false under this option. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::isinf(num) has the same effect as std::isinf(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const double max = std::numeric_limits::max(); + const double inf = std::numeric_limits::infinity(); + + std::cout << std::boolalpha + << "isinf(NaN) = " << std::isinf(NAN) << '\\n' + << "isinf(Inf) = " << std::isinf(INFINITY) << '\\n' + << "isinf(max) = " << std::isinf(max) << '\\n' + << "isinf(inf) = " << std::isinf(inf) << '\\n' + << "isinf(0.0) = " << std::isinf(0.0) << '\\n' + << "isinf(exp(800)) = " << std::isinf(std::exp(800)) << '\\n' + << "isinf(DBL_MIN/2.0) = " << std::isinf(DBL_MIN / 2.0) << '\\n'; + } + +.SH Output: + + isinf(NaN) = false + isinf(Inf) = true + isinf(max) = false + isinf(inf) = true + isinf(0.0) = false + isinf(exp(800)) = true + isinf(DBL_MIN/2.0) = false .SH See also - fpclassify categorizes the given floating point value - \fI(C++11)\fP \fI(function)\fP + fpclassify categorizes the given floating-point value + \fI(C++11)\fP \fI(function)\fP isfinite checks if the given number has finite value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnan checks if the given number is NaN - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnormal checks if the given number is normal - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + isinf diff --git a/man/std::isless.3 b/man/std::isless.3 index c941982db..679f39aa4 100644 --- a/man/std::isless.3 +++ b/man/std::isless.3 @@ -1,30 +1,75 @@ -.TH std::isless 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isless 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isless \- std::isless + .SH Synopsis Defined in header - bool isless( float x, float y ); \fI(since C++11)\fP - bool isless( double x, double y ); \fI(since C++11)\fP - bool isless( long double x, long double y ); \fI(since C++11)\fP + bool isless( float x, float y ); + \fI(since C++11)\fP + bool isless( double x, double y ); (until C++23) + + bool isless( long double x, long double y ); + constexpr bool isless( /* floating-point-type */ x, \fB(1)\fP + /* floating-point-type */ y (since C++23) + ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > (A) \fI(since C++11)\fP + bool isless( Arithmetic1 x, Arithmetic2 y ); (constexpr since C++23) - Determines if the floating point number x is less than the floating-point number y, - without setting floating-point exceptions. + 1) Determines if the floating point number x is less than the floating-point number + y, without setting floating-point exceptions. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. .SH Parameters - x - floating point value - y - floating point value + x, y - floating-point or integer values .SH Return value - true if x < y, false otherwise + true if x < y, false otherwise. .SH Notes The built-in operator< for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator<. + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::isless(num1, num2) + has the same effect as std::isless(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::isless(num1, num2) has the same effect as (until C++23) + std::isless(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::isless(num1, + num2) has the same effect as std::isless(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::isless(num1, num2) + has the same effect as std::isless(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + .SH See also less function object implementing x < y - \fI(class template)\fP + \fI(class template)\fP isgreater checks if the first floating-point argument is greater than the second - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + isless diff --git a/man/std::islessequal.3 b/man/std::islessequal.3 index 28d933a08..9100f01cd 100644 --- a/man/std::islessequal.3 +++ b/man/std::islessequal.3 @@ -1,31 +1,79 @@ -.TH std::islessequal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::islessequal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::islessequal \- std::islessequal + .SH Synopsis Defined in header - bool islessequal( float x, float y ); \fI(since C++11)\fP - bool islessequal( double x, double y ); \fI(since C++11)\fP - bool islessequal( long double x, long double y ); \fI(since C++11)\fP + bool islessequal( float x, float y ); + \fI(since C++11)\fP + bool islessequal( double x, double y ); (until C++23) + + bool islessequal( long double x, long double y ); + constexpr bool islessequal( /* floating-point-type + */ x, \fB(1)\fP (since C++23) + /* floating-point-type + */ y ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > (A) \fI(since C++11)\fP + bool islessequal( Arithmetic1 x, Arithmetic2 y ); (constexpr since C++23) - Determines if the floating point number x is less than or equal to the + 1) Determines if the floating point number x is less than or equal to the floating-point number y, without setting floating-point exceptions. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. .SH Parameters - x - floating point value - y - floating point value + x, y - floating-point or integer values .SH Return value - true if x <= y, false otherwise + true if x <= y, false otherwise. .SH Notes The built-in operator<= for floating-point numbers may raise FE_INVALID if one or both of the arguments is NaN. This function is a "quiet" version of operator<=. + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::islessequal(num1, + num2) has the same effect as std::islessequal(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::islessequal(num1, num2) has the same effect as (until C++23) + std::islessequal(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::islessequal(num1, num2) has the same effect as + std::islessequal(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::islessequal(num1, + num2) has the same effect as std::islessequal(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + .SH See also less_equal function object implementing x <= y - \fI(class template)\fP + \fI(class template)\fP isgreaterequal checks if the first floating-point argument is greater or equal than \fI(C++11)\fP the second - \fI(function)\fP + \fI(function)\fP + C documentation for + islessequal diff --git a/man/std::islessgreater.3 b/man/std::islessgreater.3 index e7171737f..ebf86bc71 100644 --- a/man/std::islessgreater.3 +++ b/man/std::islessgreater.3 @@ -1,21 +1,37 @@ -.TH std::islessgreater 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::islessgreater 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::islessgreater \- std::islessgreater + .SH Synopsis Defined in header - bool islessgreater( float x, float y ); \fI(since C++11)\fP - bool islessgreater( double x, double y ); \fI(since C++11)\fP - bool islessgreater( long double x, long double y ); \fI(since C++11)\fP + bool islessgreater( float x, float y ); + \fI(since C++11)\fP + bool islessgreater( double x, double y ); (until C++23) + + bool islessgreater( long double x, long double y ); + constexpr bool islessgreater( /* floating-point-type + */ x, \fB(1)\fP (since C++23) + /* floating-point-type + */ y ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > (A) \fI(since C++11)\fP + bool islessgreater( Arithmetic1 x, Arithmetic2 y ); (constexpr since C++23) - Determines if the floating point number x is less than or greater than the + 1) Determines if the floating point number x is less than or greater than the floating-point number y, without setting floating-point exceptions. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. .SH Parameters - x - floating point value - y - floating point value + x, y - floating-point or integer values .SH Return value - true if x < y || x > y, false otherwise + true if x < y || x > y, false otherwise. .SH Notes @@ -23,9 +39,41 @@ if one or both of the arguments is NaN. This function is a "quiet" version of the expression x < y || x > y. + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then + std::islessgreater(num1, num2) has the same effect as + std::islessgreater(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::islessgreater(num1, num2) has the same effect as (until C++23) + std::islessgreater(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::islessgreater(num1, num2) has the same effect as + std::islessgreater(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::islessgreater(num1, + num2) has the same effect as std::islessgreater(static_cast(num1), + static_cast(num2)), where /* common-floating-point-type */ is the + floating-point type with the greatest floating-point conversion rank + and greatest floating-point conversion subrank between the types of (since C++23) + num1 and num2, arguments of integer type are considered to have the + same floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + .SH See also isless checks if the first floating-point argument is less than the second - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isgreater checks if the first floating-point argument is greater than the second - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + islessgreater diff --git a/man/std::islower(std::locale).3 b/man/std::islower(std::locale).3 index 4d650e97d..81f0e0d6b 100644 --- a/man/std::islower(std::locale).3 +++ b/man/std::islower(std::locale).3 @@ -1,11 +1,14 @@ -.TH std::islower(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::islower(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::islower(std::locale) \- std::islower(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool islower( charT ch, const locale& loc ); + template< class CharT > + bool islower( CharT ch, const locale& loc ); - Checks if the given character classified as a lowercase alphabetic character by the - given locale's std::ctype facet. + Checks if the given character is classified as a lowercase alphabetic character by + the given locale's std::ctype facet. .SH Parameters @@ -18,41 +21,50 @@ .SH Possible implementation - template< class charT > - bool islower( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::lower, ch); + template + bool islower(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::lower, ch); } .SH Example Demonstrates the use of islower() with different locales (OS-specific). - + // Run this code #include #include + int main() { - const wchar_t c = L'\\u03c0'; // greek small letter pi - + const wchar_t c = L'\\u03c0'; // GREEK SMALL LETTER PI + std::locale loc1("C"); - std::cout << "islower('π', C locale) returned " - << std::boolalpha << std::islower(c, loc1) << '\\n'; - + std::cout << std::boolalpha + << "islower('π', C locale) returned " + << std::islower(c, loc1) << '\\n' + << "isupper('π', C locale) returned " + << std::isupper(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF8"); std::cout << "islower('π', Unicode locale) returned " - << std::boolalpha << std::islower(c, loc2) << '\\n'; + << std::islower(c, loc2) << '\\n' + << "isupper('π', Unicode locale) returned " + << std::isupper(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: islower('π', C locale) returned false + isupper('π', C locale) returned false islower('π', Unicode locale) returned true + isupper('π', Unicode locale) returned false .SH See also islower checks if a character is lowercase - \fI(function)\fP + \fI(function)\fP iswlower checks if a wide character is lowercase - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::islower.3 b/man/std::islower.3 index e682b949d..84b0c0a2c 100644 --- a/man/std::islower.3 +++ b/man/std::islower.3 @@ -1,14 +1,18 @@ -.TH std::islower 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::islower 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::islower \- std::islower + .SH Synopsis Defined in header int islower( int ch ); Checks if the given character is classified as a lowercase character according to - the current C locale. In the default "C" locale, islower returns true only for the - lowercase letters (abcdefghijklmnopqrstuvwxyz). + the current C locale. In the default "C" locale, std::islower returns a nonzero + value only for the lowercase letters (abcdefghijklmnopqrstuvwxyz). - If islower returns true, it is guaranteed that iscntrl, isdigit, ispunct, and - isspace return false for the same character in the same C locale. + If islower returns a nonzero value, it is guaranteed that std::iscntrl, + std::isdigit, std::ispunct, and std::isspace return zero for the same character in + the same C locale. The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF. @@ -19,31 +23,57 @@ .SH Return value - Non-zero value (true) if the character is a lowercase letter, 0 (false) otherwise. + Non-zero value if the character is a lowercase letter, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::islower is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_islower(char ch) + { + return std::islower(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_lowers(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::islower) // wrong + // [](int c){ return std::islower(c); } // wrong + // [](char c){ return std::islower(c); } // wrong + [](unsigned char c){ return std::islower(c); } // correct + ); + } .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xe5'; // letter å in ISO-8859-1 - + std::cout << "islower(\\'\\\\xe5\\', default C locale) returned " - << std::boolalpha << (bool)std::islower(c) << '\\n'; - + << std::boolalpha << (bool)std::islower(c) << '\\n'; + std::setlocale(LC_ALL, "en_GB.iso88591"); std::cout << "islower(\\'\\\\xe5\\', ISO-8859-1 locale) returned " << std::boolalpha << (bool)std::islower(c) << '\\n'; - + } -.SH Output: +.SH Possible output: islower('\\xe5', default C locale) returned false islower('\\xe5', ISO-8859-1 locale) returned true @@ -51,29 +81,32 @@ .SH See also islower(std::locale) checks if a character is classified as lowercase by a locale - \fI(function template)\fP + \fI(function template)\fP iswlower checks if a wide character is lowercase - \fI(function)\fP + \fI(function)\fP C documentation for islower - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isnan.3 b/man/std::isnan.3 index 2d977866d..ee955ba79 100644 --- a/man/std::isnan.3 +++ b/man/std::isnan.3 @@ -1,35 +1,103 @@ -.TH std::isnan 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isnan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isnan \- std::isnan + .SH Synopsis Defined in header - bool isnan( float arg ); \fI(since C++11)\fP - bool isnan( double arg ); \fI(since C++11)\fP - bool isnan( long double arg ); \fI(since C++11)\fP + bool isnan( float num ); + \fI(since C++11)\fP + bool isnan( double num ); (until C++23) + + bool isnan( long double num ); + constexpr bool isnan( /* floating-point-type */ num \fB(1)\fP (since C++23) + ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + bool isnan( Integer num ); (constexpr since C++23) - Determines if the given floating point number arg is not-a-number (NaN). + 1) Determines if the given floating point number num is a not-a-number (NaN) value. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameter num. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. .SH Parameters - arg - floating point value + num - floating-point or integer value .SH Return value - true if arg is NaN, false otherwise + true if num is a NaN, false otherwise. .SH Notes - In C, isnan is a preprocessor macro, rather than a function. + There are many different NaN values with different sign bits and payloads, see + std::nan and std::numeric_limits::quiet_NaN. + + NaN values never compare equal to themselves or to other NaN values. Copying a NaN + is not required, by IEEE-754, to preserve its bit representation (sign and payload), + though most implementation do. + + Another way to test if a floating-point value is NaN is to compare it with itself: + bool is_nan(double x) { return x != x; }. + + GCC and Clang support a -ffinite-math option (additionally implied by -ffast-math), + which allows the respective compiler to assume the nonexistence of special IEEE-754 + floating point values such as NaN, infinity, or negative zero. In other words, + std::isnan is assumed to always return false under this option. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::isnan(num) has the same effect as std::isnan(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha + << "isnan(NaN) = " << std::isnan(NAN) << '\\n' + << "isnan(Inf) = " << std::isnan(INFINITY) << '\\n' + << "isnan(0.0) = " << std::isnan(0.0) << '\\n' + << "isnan(DBL_MIN/2.0) = " << std::isnan(DBL_MIN / 2.0) << '\\n' + << "isnan(0.0 / 0.0) = " << std::isnan(0.0 / 0.0) << '\\n' + << "isnan(Inf - Inf) = " << std::isnan(INFINITY - INFINITY) << '\\n'; + } + +.SH Output: + + isnan(NaN) = true + isnan(Inf) = false + isnan(0.0) = false + isnan(DBL_MIN/2.0) = false + isnan(0.0 / 0.0) = true + isnan(Inf - Inf) = true .SH See also - fpclassify categorizes the given floating point value - \fI(C++11)\fP \fI(function)\fP + nan + nanf + nanl not-a-number (NaN) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + fpclassify categorizes the given floating-point value + \fI(C++11)\fP \fI(function)\fP isfinite checks if the given number has finite value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isinf checks if the given number is infinite - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnormal checks if the given number is normal - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isunordered checks if two floating-point values are unordered - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP C documentation for isnan diff --git a/man/std::isnormal.3 b/man/std::isnormal.3 index 0bf6b6bad..fe980de93 100644 --- a/man/std::isnormal.3 +++ b/man/std::isnormal.3 @@ -1,28 +1,79 @@ -.TH std::isnormal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isnormal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isnormal \- std::isnormal + .SH Synopsis Defined in header - bool isnormal( float arg ); \fI(since C++11)\fP - bool isnormal( double arg ); \fI(since C++11)\fP - bool isnormal( long double arg ); \fI(since C++11)\fP + bool isnormal( float num ); + \fI(since C++11)\fP + bool isnormal( double num ); (until C++23) + + bool isnormal( long double num ); + constexpr bool isnormal( /* floating-point-type */ \fB(1)\fP (since C++23) + num ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + bool isnormal( Integer num ); (constexpr since C++23) - Determines if the given floating point number arg is normal, i.e. is neither zero, - subnormal, infinite, nor NaN. + 1) Determines if the given floating point number num is normal, i.e. is neither + zero, subnormal, infinite, nor NaN. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameter num. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. .SH Parameters - arg - floating point value + num - floating-point or integer value .SH Return value - true if arg is normal, false otherwise + true if num is normal, false otherwise. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::isnormal(num) has the same effect as std::isnormal(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha + << "isnormal(NaN) = " << std::isnormal(NAN) << '\\n' + << "isnormal(Inf) = " << std::isnormal(INFINITY) << '\\n' + << "isnormal(0.0) = " << std::isnormal(0.0) << '\\n' + << "isnormal(DBL_MIN/2.0) = " << std::isnormal(DBL_MIN / 2.0) << '\\n' + << "isnormal(1.0) = " << std::isnormal(1.0) << '\\n'; + } + +.SH Output: + + isnormal(NaN) = false + isnormal(Inf) = false + isnormal(0.0) = false + isnormal(DBL_MIN/2.0) = false + isnormal(1.0) = true .SH See also - fpclassify categorizes the given floating point value - \fI(C++11)\fP \fI(function)\fP + fpclassify categorizes the given floating-point value + \fI(C++11)\fP \fI(function)\fP isfinite checks if the given number has finite value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isinf checks if the given number is infinite - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP isnan checks if the given number is NaN - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + isnormal diff --git a/man/std::isprint(std::locale).3 b/man/std::isprint(std::locale).3 index af40f93df..bbc88dc6a 100644 --- a/man/std::isprint(std::locale).3 +++ b/man/std::isprint(std::locale).3 @@ -1,11 +1,14 @@ -.TH std::isprint(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isprint(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isprint(std::locale) \- std::isprint(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isprint( charT ch, const locale& loc ); + template< class CharT > + bool isprint( CharT ch, const locale& loc ); - Checks if the given character classified as a printable character (including space) - by the given locale's std::ctype facet. + Checks if the given character is classified as a printable character (including + space) by the given locale's std::ctype facet. .SH Parameters @@ -18,34 +21,36 @@ .SH Possible implementation - template< class charT > - bool isprint( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::print, ch); + template + bool isprint(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::print, ch); } .SH Example Demonstrates the use of isprint() with different locales (OS-specific). - + // Run this code #include #include + int main() { const wchar_t c = L'\\u2122'; // trademark sign - + std::locale loc1("C"); std::cout << "isprint('™', C locale) returned " - << std::boolalpha << std::isprint(c, loc1) << '\\n'; - + << std::boolalpha << std::isprint(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF-8"); std::cout << "isprint('™', Unicode locale) returned " << std::boolalpha << std::isprint(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: isprint('™', C locale) returned false isprint('™', Unicode locale) returned true @@ -53,6 +58,6 @@ .SH See also isprint checks if a character is a printing character - \fI(function)\fP + \fI(function)\fP iswprint checks if a wide character is a printing character - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isprint.3 b/man/std::isprint.3 index 0fef0e794..e8bfd9d9e 100644 --- a/man/std::isprint.3 +++ b/man/std::isprint.3 @@ -1,9 +1,12 @@ -.TH std::isprint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isprint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isprint \- std::isprint + .SH Synopsis Defined in header int isprint( int ch ); - Checks if is a printable character as classified by the currently installed C + Checks if ch is a printable character as classified by the currently installed C locale. In the default, "C" locale, the following characters are printable: * digits (0123456789) @@ -21,30 +24,56 @@ .SH Return value - Non-zero value (true) if the character can be printed, 0 (false) otherwise. + Non-zero value if the character can be printed, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isprint is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isprint(char ch) + { + return std::isprint(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_prints(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isprint) // wrong + // [](int c){ return std::isprint(c); } // wrong + // [](char c){ return std::isprint(c); } // wrong + [](unsigned char c){ return std::isprint(c); } // correct + ); + } .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xa0'; // the non-breaking space in ISO-8859-1 - + std::cout << "isprint(\\'\\\\xa0\\', default C locale) returned " - << std::boolalpha << (bool)std::isprint(c) << '\\n'; - + << std::boolalpha << (bool)std::isprint(c) << '\\n'; + std::setlocale(LC_ALL, "en_GB.iso88591"); std::cout << "isprint(\\'\\\\xa0\\', ISO-8859-1 locale) returned " << std::boolalpha << (bool)std::isprint(c) << '\\n'; } -.SH Output: +.SH Possible output: isprint('\\xa0', default C locale) returned false isprint('\\xa0', ISO-8859-1 locale) returned true @@ -52,29 +81,32 @@ .SH See also isprint(std::locale) checks if a character is classified as printable by a locale - \fI(function template)\fP + \fI(function template)\fP iswprint checks if a wide character is a printing character - \fI(function)\fP + \fI(function)\fP C documentation for isprint - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::ispunct(std::locale).3 b/man/std::ispunct(std::locale).3 index ae96e0034..f4031b74a 100644 --- a/man/std::ispunct(std::locale).3 +++ b/man/std::ispunct(std::locale).3 @@ -1,10 +1,13 @@ -.TH std::ispunct(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ispunct(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ispunct(std::locale) \- std::ispunct(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool ispunct( charT ch, const locale& loc ); + template< class CharT > + bool ispunct( CharT ch, const locale& loc ); - Checks if the given character is classified as an punctuation character by the given + Checks if the given character is classified as a punctuation character by the given locale's std::ctype facet. .SH Parameters @@ -18,34 +21,36 @@ .SH Possible implementation - template< class charT > - bool ispunct( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::punct, ch); + template + bool ispunct(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::punct, ch); } .SH Example - Demonstrates the use of ispunct() with different locales (OS-specific). + Demonstrates the use of std::ispunct() with different locales (OS-specific). + - // Run this code #include #include + int main() { const wchar_t c = L'\\u214b'; // upside-down ampersand - + std::locale loc1("C"); std::cout << "ispunct('⅋', C locale) returned " - << std::boolalpha << std::ispunct(c, loc1) << '\\n'; - + << std::boolalpha << std::ispunct(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF-8"); std::cout << "ispunct('⅋', Unicode locale) returned " << std::boolalpha << std::ispunct(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: isalpha('⅋', C locale) returned false isalpha('⅋', Unicode locale) returned true @@ -53,6 +58,6 @@ .SH See also ispunct checks if a character is a punctuation character - \fI(function)\fP + \fI(function)\fP iswpunct checks if a wide character is a punctuation character - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::ispunct.3 b/man/std::ispunct.3 index 05beb9b1c..f86352686 100644 --- a/man/std::ispunct.3 +++ b/man/std::ispunct.3 @@ -1,4 +1,7 @@ -.TH std::ispunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ispunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ispunct \- std::ispunct + .SH Synopsis Defined in header int ispunct( int ch ); @@ -8,7 +11,7 @@ !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ as punctuation. The behavior is undefined if the value of ch is not representable as unsigned char - and is not equal EOF. + and is not equal to EOF. .SH Parameters @@ -16,31 +19,56 @@ .SH Return value - Non-zero value (true) if the character is a punctuation character, 0 (false) - otherwise. + Non-zero value if the character is a punctuation character, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::ispunct is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_ispunct(char ch) + { + return std::ispunct(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_puncts(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::ispunct) // wrong + // [](int c){ return std::ispunct(c); } // wrong + // [](char c){ return std::ispunct(c); } // wrong + [](unsigned char c){ return std::ispunct(c); } // correct + ); + } .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xd7'; // the character × (multiplication sign) in ISO-8859-1 - + std::cout << "ispunct(\\'\\\\xd7\\', default C locale) returned " - << std::boolalpha << (bool)std::ispunct(c) << '\\n'; - + << std::boolalpha << (bool)std::ispunct(c) << '\\n'; + std::setlocale(LC_ALL, "en_GB.iso88591"); std::cout << "ispunct(\\'\\\\xd7\\', ISO-8859-1 locale) returned " << std::boolalpha << (bool)std::ispunct(c) << '\\n'; } -.SH Output: +.SH Possible output: ispunct('\\xd7', default C locale) returned false ispunct('\\xd7', ISO-8859-1 locale) returned true @@ -48,29 +76,32 @@ .SH See also ispunct(std::locale) checks if a character is classified as punctuation by a locale - \fI(function template)\fP + \fI(function template)\fP iswpunct checks if a wide character is a punctuation character - \fI(function)\fP + \fI(function)\fP C documentation for ispunct - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isspace(std::locale).3 b/man/std::isspace(std::locale).3 index 21a36ebb5..6ed113651 100644 --- a/man/std::isspace(std::locale).3 +++ b/man/std::isspace(std::locale).3 @@ -1,11 +1,14 @@ -.TH std::isspace(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isspace(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isspace(std::locale) \- std::isspace(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isspace( charT ch, const locale& loc ); + template< class CharT > + bool isspace( CharT ch, const locale& loc ); - Checks if the given character classified as a whitespace character by the given - locale's ctype facet. + Checks if the given character is classified as a whitespace character by the given + locale's std::ctype facet. .SH Parameters @@ -19,27 +22,28 @@ .SH Possible implementation - template< class charT > - bool isspace( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::space, ch); + template + bool isspace(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::space, ch); } .SH Example - Demonstrates the use of isspace() with different locales (OS-specific). + Demonstrates the use of std::isspace() with different locales (OS-specific). + - // Run this code #include #include - + void try_with(wchar_t c, const char* loc) { std::wcout << "isspace('" << c << "', locale(\\"" << loc << "\\")) returned " << std::boolalpha << std::isspace(c, std::locale(loc)) << '\\n'; } - + int main() { const wchar_t EM_SPACE = L'\\u2003'; // Unicode character 'EM SPACE' @@ -47,7 +51,7 @@ try_with(EM_SPACE, "en_US.UTF8"); } -.SH Output: +.SH Possible output: isspace(' ', locale("C")) returned false isspace(' ', locale("en_US.UTF8")) returned true @@ -55,6 +59,6 @@ .SH See also isspace checks if a character is a space character - \fI(function)\fP + \fI(function)\fP iswspace checks if a wide character is a space character - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isspace.3 b/man/std::isspace.3 index 9666b2b01..a5af4cb61 100644 --- a/man/std::isspace.3 +++ b/man/std::isspace.3 @@ -1,4 +1,7 @@ -.TH std::isspace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isspace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isspace \- std::isspace + .SH Synopsis Defined in header int isspace( int ch ); @@ -23,35 +26,63 @@ .SH Return value - Non-zero value (true) if the character is a whitespace character, 0 (false) - otherwise. + Non-zero value if the character is a whitespace character, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isspace is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isspace(char ch) + { + return std::isspace(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_spaces(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isspace) // wrong + // [](int c){ return std::isspace(c); } // wrong + // [](char c){ return std::isspace(c); } // wrong + [](unsigned char c){ return std::isspace(c); } // correct + ); + } .SH See also isspace(std::locale) checks if a character is classified as whitespace by a locale - \fI(function template)\fP + \fI(function template)\fP iswspace checks if a wide character is a space character - \fI(function)\fP + \fI(function)\fP C documentation for isspace - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::istream.3 b/man/std::istream.3 deleted file mode 120000 index fd729d8c8..000000000 --- a/man/std::istream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream.3 \ No newline at end of file diff --git a/man/std::istream.3 b/man/std::istream.3 new file mode 100644 index 000000000..1212d3f28 --- /dev/null +++ b/man/std::istream.3 @@ -0,0 +1,281 @@ +.TH std::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream \- std::basic_istream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_istream : virtual public std::basic_ios + + The class template basic_istream provides support for high level input operations on + character streams. The supported operations include formatted input (e.g. integer + values or whitespace-separated characters and characters strings) and unformatted + input (e.g. raw characters and character arrays). This functionality is implemented + in terms of the interface provided by the underlying basic_streambuf class, accessed + through the basic_ios base class. The only non-inherited data member of + basic_istream, in most implementations, is the value returned by + basic_istream::gcount(). + + std-basic istream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::istream std::basic_istream + std::wistream std::basic_istream + +.SH Global objects + + Two global basic_istream objects are provided by the standard library. + + Defined in header + cin reads from the standard C input stream stdin + wcin (global object) + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Formatted input + operator>> extracts formatted data + \fI(public member function)\fP +.SH Unformatted input + get extracts characters + \fI(public member function)\fP + peek reads the next character without extracting it + \fI(public member function)\fP + unget unextracts a character + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function)\fP + getline extracts characters until the given character is found + \fI(public member function)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function)\fP + read extracts blocks of characters + \fI(public member function)\fP + readsome extracts already available blocks of characters + \fI(public member function)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function)\fP + seekg sets the input position indicator + \fI(public member function)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function)\fP + swap swaps stream objects, except for the associated buffer + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class)\fP + +.SH Non-member functions + + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::istream::basic_istream.3 b/man/std::istream::basic_istream.3 deleted file mode 120000 index e902b6c6d..000000000 --- a/man/std::istream::basic_istream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::basic_istream.3 \ No newline at end of file diff --git a/man/std::istream::basic_istream.3 b/man/std::istream::basic_istream.3 new file mode 100644 index 000000000..102f3fc85 --- /dev/null +++ b/man/std::istream::basic_istream.3 @@ -0,0 +1,52 @@ +.TH std::basic_istream::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::basic_istream \- std::basic_istream::basic_istream + +.SH Synopsis + explicit basic_istream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_istream( const basic_istream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_istream( basic_istream&& rhs ); + + 1) Constructs the basic_istream object, assigning initial values to the base class + by calling basic_ios::init(sb). The value of gcount() is initialized to zero. + + 2) The copy constructor is protected, and is deleted. Input streams are not + copyable. + + 3) The move constructor copies the value of gcount() from rhs, sets the gcount() + value of rhs to zero, and uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable input + stream classes std::basic_ifstream and std::basic_istringstream, which know how to + correctly move the associated stream buffer. + +.SH Parameters + + sb - streambuffer to use as underlying device + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("hello"); + std::istream s2(s1.rdbuf()); // OK: s2 shares the buffer with s1 + + // std::istream s3(std::istringstream("test")); // ERROR: move constructor is protected + // std::istream s4(s2); // ERROR: copy constructor is deleted + std::istringstream s5(std::istringstream("world")); // OK: move ctor called + // by derived class + + std::cout << s2.rdbuf() << ' ' << s5.rdbuf() << '\\n'; + } + +.SH Output: + + hello world diff --git a/man/std::istream::gcount.3 b/man/std::istream::gcount.3 deleted file mode 120000 index 72c91ada0..000000000 --- a/man/std::istream::gcount.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::gcount.3 \ No newline at end of file diff --git a/man/std::istream::gcount.3 b/man/std::istream::gcount.3 new file mode 100644 index 000000000..434789c51 --- /dev/null +++ b/man/std::istream::gcount.3 @@ -0,0 +1,68 @@ +.TH std::basic_istream::gcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::gcount \- std::basic_istream::gcount + +.SH Synopsis + std::streamsize gcount() const; + + Returns the number of characters extracted by the last unformatted input operation, + or the maximum representable value of std::streamsize if the number is not + representable. + + The following member functions of basic_istream change the value of subsequent + gcount() calls: + + * move constructor + * swap() + * get() + * getline() + * ignore() + * read() + * readsome() + * operator>>(basic_streambuf*) + + The following functions set gcount() to zero: + + * constructor + * putback() + * unget() + * peek() + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters extracted by the last unformatted input operation, or the + maximum representable value of std::streamsize if the number is not representable. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char x[20]; + std::istringstream stream("Hello World"); + + stream.read(x, sizeof x); + std::cout << "Characters extracted: " << stream.gcount(); + } + +.SH Output: + + Characters extracted: 11 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3464 C++98 the return value was unspecified when the returns the maximum + result overflows value diff --git a/man/std::istream::get.3 b/man/std::istream::get.3 deleted file mode 120000 index 656be66be..000000000 --- a/man/std::istream::get.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::get.3 \ No newline at end of file diff --git a/man/std::istream::get.3 b/man/std::istream::get.3 new file mode 100644 index 000000000..fca8f370b --- /dev/null +++ b/man/std::istream::get.3 @@ -0,0 +1,126 @@ +.TH std::basic_istream::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::get \- std::basic_istream::get + +.SH Synopsis + int_type get(); \fB(1)\fP + basic_istream& get( char_type& ch ); \fB(2)\fP + basic_istream& get( char_type* s, std::streamsize count ); \fB(3)\fP + basic_istream& get( char_type* s, std::streamsize count, char_type delim ); \fB(4)\fP + basic_istream& get( basic_streambuf& strbuf ); \fB(5)\fP + basic_istream& get( basic_streambuf& strbuf, char_type delim ); \fB(6)\fP + + Extracts character or characters from stream. + + All versions behave as UnformattedInputFunctions. After constructing and checking + the sentry object, these functions perform the following: + + 1) Reads one character and returns it if available. Otherwise, returns Traits::eof() + and sets failbit and eofbit. + 2) Reads one character and stores it to ch if available. Otherwise, leaves ch + unmodified and sets failbit and eofbit. Note that this function is not overloaded on + the types signed char and unsigned char, unlike the formatted character input + operator>>. + 3) Same as get(s, count, widen('\\n')), that is, reads at most std::max(0, count - 1) + characters and stores them into character string pointed to by s until '\\n' is + found. + 4) Reads characters and stores them into the successive locations of the character + array whose first element is pointed to by s. Characters are extracted and stored + until any of the following occurs: + * count is less than 1 or count - 1 characters have been stored. + * end of file condition occurs in the input sequence (setstate(eofbit) is called). + * the next available input character c equals delim, as determined by + Traits::eq(c, delim). This character is not extracted (unlike getline()). + In any case, if count > 0, a null character (CharT() is stored in the next + successive location of the array. + 5) Same as get(strbuf, widen('\\n')), that is, reads available characters and inserts + them to the given basic_streambuf object until '\\n' is found. + 6) Reads characters and inserts them to the output sequence controlled by the given + basic_streambuf object. Characters are extracted and inserted into strbuf until any + of the following occurs: + * end of file condition occurs in the input sequence. + * inserting into the output sequence fails (in which case the character that could + not be inserted, is not extracted). + * the next available input character c equals delim, as determined by + Traits::eq(c, delim). This character is not extracted. + * an exception occurs (in which case the exception is caught and not rethrown). + + If no characters were extracted, calls setstate(failbit). + + All versions set the value of gcount() to the number of characters extracted. + +.SH Parameters + + ch - reference to the character to write the result to + s - pointer to the character string to store the characters to + count - size of character string pointed to by s + delim - delimiting character to stop the extraction at. It is not extracted and not + stored + strbuf - stream buffer to read the content to + +.SH Return value + + 1) The extracted character or Traits::eof(). + 2-6) *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("Hello, world."); + char c1 = s1.get(); // reads 'H' + std::cout << "after reading " << c1 << ", gcount() == " << s1.gcount() << '\\n'; + + char c2; + s1.get(c2); // reads 'e' + char str[5]; + s1.get(str, 5); // reads "llo," + std::cout << "after reading " << str << ", gcount() == " << s1.gcount() << '\\n'; + + std::cout << c1 << c2 << str; + s1.get(*std::cout.rdbuf()); // reads the rest, not including '\\n' + std::cout << "\\nAfter the last get(), gcount() == " << s1.gcount() << '\\n'; + } + +.SH Output: + + after reading H, gcount() == 1 + after reading llo,, gcount() == 4 + Hello, world. + After the last get(), gcount() == 7 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the effect of overload \fB(5)\fP was get(s, corrected to + LWG 370 C++98 count, widen('\\n')), get(strbuf, widen('\\n')) + which is the effect of overload \fB(3)\fP + LWG 531 C++98 overloads (3,4) could not handle the no character is + case where count is non-positive extracted in this case + +.SH See also + + read extracts blocks of characters + \fI(public member function)\fP + operator>> extracts formatted data + \fI(public member function)\fP + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP diff --git a/man/std::istream::getline.3 b/man/std::istream::getline.3 deleted file mode 120000 index 228128a18..000000000 --- a/man/std::istream::getline.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::getline.3 \ No newline at end of file diff --git a/man/std::istream::getline.3 b/man/std::istream::getline.3 new file mode 100644 index 000000000..f5d702dd1 --- /dev/null +++ b/man/std::istream::getline.3 @@ -0,0 +1,107 @@ +.TH std::basic_istream::getline 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::getline \- std::basic_istream::getline + +.SH Synopsis + basic_istream& getline( char_type* s, std::streamsize count ); \fB(1)\fP + basic_istream& getline( char_type* s, std::streamsize count, char_type delim ); \fB(2)\fP + + Extracts characters from stream until end of line or the specified delimiter delim. + + The first overload is equivalent to getline(s, count, widen('\\n')). + + Behaves as UnformattedInputFunction. After constructing and checking the sentry + object, extracts characters from *this and stores them in successive locations of + the array whose first element is pointed to by s, until any of the following occurs + (tested in the order shown): + + 1. end of file condition occurs in the input sequence. + 2. the next available character c is the delimiter, as determined by Traits::eq(c, + delim). The delimiter is extracted (unlike basic_istream::get()) and counted + towards gcount(), but is not stored. + 3. count is non-positive, or count - 1 characters have been extracted + (setstate(failbit) is called in this case). + + If the function extracts no characters, failbit is set in the local error state + before setstate() is called. + + In any case, if count > 0, it then stores a null character CharT() into the next + successive location of the array and updates gcount(). + +.SH Notes + + Because condition #2 is tested before condition #3, the input line that exactly fits + the buffer does not trigger failbit. + + Because the terminating character is counted as an extracted character, an empty + input line does not trigger failbit. + +.SH Parameters + + s - pointer to the character string to store the characters to + count - size of character string pointed to by s + delim - delimiting character to stop the extraction at. It is extracted but not + stored. + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::istringstream input("abc|def|gh"); + std::vector> v; + + // note: the following loop terminates when std::ios_base::operator bool() + // on the stream returned from getline() returns false + for (std::array a; input.getline(&a[0], 4, '|');) + v.push_back(a); + + for (auto& a : v) + std::cout << &a[0] << '\\n'; + } + +.SH Output: + + abc + def + gh + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 531 C++98 std::getline could not handle the no character is + case where count is non-positive extracted in this case + +.SH See also + + getline read data from an I/O stream into a string + \fI(function template)\fP + operator>> extracts formatted data + \fI(public member function)\fP + get extracts characters + \fI(public member function)\fP + read extracts blocks of characters + \fI(public member function)\fP diff --git a/man/std::istream::ignore.3 b/man/std::istream::ignore.3 deleted file mode 120000 index 67e193e32..000000000 --- a/man/std::istream::ignore.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::ignore.3 \ No newline at end of file diff --git a/man/std::istream::ignore.3 b/man/std::istream::ignore.3 new file mode 100644 index 000000000..3ebb6f3a3 --- /dev/null +++ b/man/std::istream::ignore.3 @@ -0,0 +1,95 @@ +.TH std::basic_istream::ignore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::ignore \- std::basic_istream::ignore + +.SH Synopsis + basic_istream& ignore( std::streamsize count = 1, int_type delim = Traits::eof() + ); + + Extracts and discards characters from the input stream until and including delim. + + ignore behaves as an UnformattedInputFunction. After constructing and checking the + sentry object, it extracts characters from the stream and discards them until any of + the following conditions occurs: + + * count characters were extracted. This test is disabled in the special case when + count equals std::numeric_limits::max(). + * end of file conditions occurs in the input sequence, in which case the function + calls setstate(eofbit). + * the next available character c in the input sequence is delim, as determined by + Traits::eq_int_type(Traits::to_int_type(c), delim). The delimiter character is + extracted and discarded. This test is disabled if delim is Traits::eof(). + +.SH Parameters + + count - number of characters to extract + delim - delimiting character to stop the extraction at. It is also extracted + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + The following example uses ignore to skip over non-numeric input: + + +// Run this code + + #include + #include + #include + + constexpr auto max_size = std::numeric_limits::max(); + + int main() + { + std::istringstream input("1\\n" + "some non-numeric input\\n" + "2\\n"); + for (;;) + { + int n; + input >> n; + + if (input.eof() || input.bad()) + break; + else if (input.fail()) + { + input.clear(); // unset failbit + input.ignore(max_size, '\\n'); // skip bad input + } + else + std::cout << n << '\\n'; + } + } + +.SH Output: + + 1 + 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 172 C++98 the type of count was misspecified corrected to std::streamsize + as int + +.SH See also + + get extracts characters + \fI(public member function)\fP + getline extracts characters until the given character is found + \fI(public member function)\fP diff --git a/man/std::istream::istream.3 b/man/std::istream::istream.3 deleted file mode 120000 index e902b6c6d..000000000 --- a/man/std::istream::istream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::basic_istream.3 \ No newline at end of file diff --git a/man/std::istream::istream.3 b/man/std::istream::istream.3 new file mode 100644 index 000000000..102f3fc85 --- /dev/null +++ b/man/std::istream::istream.3 @@ -0,0 +1,52 @@ +.TH std::basic_istream::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::basic_istream \- std::basic_istream::basic_istream + +.SH Synopsis + explicit basic_istream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_istream( const basic_istream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_istream( basic_istream&& rhs ); + + 1) Constructs the basic_istream object, assigning initial values to the base class + by calling basic_ios::init(sb). The value of gcount() is initialized to zero. + + 2) The copy constructor is protected, and is deleted. Input streams are not + copyable. + + 3) The move constructor copies the value of gcount() from rhs, sets the gcount() + value of rhs to zero, and uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable input + stream classes std::basic_ifstream and std::basic_istringstream, which know how to + correctly move the associated stream buffer. + +.SH Parameters + + sb - streambuffer to use as underlying device + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("hello"); + std::istream s2(s1.rdbuf()); // OK: s2 shares the buffer with s1 + + // std::istream s3(std::istringstream("test")); // ERROR: move constructor is protected + // std::istream s4(s2); // ERROR: copy constructor is deleted + std::istringstream s5(std::istringstream("world")); // OK: move ctor called + // by derived class + + std::cout << s2.rdbuf() << ' ' << s5.rdbuf() << '\\n'; + } + +.SH Output: + + hello world diff --git a/man/std::istream::operator=.3 b/man/std::istream::operator=.3 deleted file mode 120000 index f2a6f7666..000000000 --- a/man/std::istream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::operator=.3 \ No newline at end of file diff --git a/man/std::istream::operator=.3 b/man/std::istream::operator=.3 new file mode 100644 index 000000000..52893b371 --- /dev/null +++ b/man/std::istream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_istream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::operator= \- std::basic_istream::operator= + +.SH Synopsis + protected: \fB(1)\fP + basic_istream& operator=( const basic_istream& rhs ) = delete; + protected: \fB(2)\fP \fI(since C++11)\fP + basic_istream& operator=( basic_istream&& rhs ); + + 1) The copy assignment operator is protected, and is deleted. Input streams are not + CopyAssignable. + 2) The move assignment operator exchanges the gcount() values and all data members + of the base class, except for rdbuf(), with rhs, as if by calling swap(*rhs). This + move assignment operator is protected: it is only called by the move assignment + operators of the derived movable input stream classes std::basic_ifstream and + std::basic_istringstream, which know how to correctly move-assign the associated + streambuffers. + +.SH Parameters + + rhs - the basic_istream object from which to assign to *this + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1; + s1 = std::istringstream("test"); // OK + + // std::cin = std::istringstream("test"); // ERROR: 'operator=' is protected + } diff --git a/man/std::istream::operator>>.3 b/man/std::istream::operator>>.3 deleted file mode 120000 index 3ce9a4e0e..000000000 --- a/man/std::istream::operator>>.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::operator>>.3 \ No newline at end of file diff --git a/man/std::istream::operator>>.3 b/man/std::istream::operator>>.3 new file mode 100644 index 000000000..f4a11f8af --- /dev/null +++ b/man/std::istream::operator>>.3 @@ -0,0 +1,211 @@ +.TH std::basic_istream::operator>> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::operator>> \- std::basic_istream::operator>> + +.SH Synopsis + basic_istream& operator>>( unsigned short& value ); \fB(1)\fP + basic_istream& operator>>( unsigned int& value ); \fB(2)\fP + basic_istream& operator>>( long& value ); \fB(3)\fP + basic_istream& operator>>( unsigned long& value ); \fB(4)\fP + basic_istream& operator>>( long long& value ); \fB(5)\fP \fI(since C++11)\fP + basic_istream& operator>>( unsigned long long& value ); \fB(6)\fP \fI(since C++11)\fP + basic_istream& operator>>( float& value ); \fB(7)\fP + basic_istream& operator>>( double& value ); \fB(8)\fP + basic_istream& operator>>( long double& value ); \fB(9)\fP + basic_istream& operator>>( bool& value ); \fB(10)\fP + basic_istream& operator>>( void*& value ); \fB(11)\fP + basic_istream& operator>>( short& value ); \fB(12)\fP + basic_istream& operator>>( int& value ); \fB(13)\fP + basic_istream& operator>>( /* extended-floating-point-type */& \fB(14)\fP (since C++23) + value ); + basic_istream& operator>>( std::ios_base& (*func)(std::ios_base&) \fB(15)\fP + ); + basic_istream& operator>>( std::basic_ios& + (*func)(std::basic_ios&) ); + basic_istream& operator>>( basic_istream& (*func)(basic_istream&) \fB(17)\fP + ); + basic_istream& operator>>( std::basic_streambuf* \fB(18)\fP + sb ); + + Extracts values from an input stream. + + 1-11) Extracts a value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a value by calling + std::num_get::get(). + 12) Extracts a short value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a long value lval by + calling std::num_get::get(). After that: + * If lval < std::numeric_limits::min(), sets failbit and stores + std::numeric_limits::min() to val. + * Otherwise, if std::numeric_limits::max() < lval, sets failbit and stores + std::numeric_limits::max() to val. + * Otherwise, stores static_cast(lval) to val. + 13) Extracts an int value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a long value lval by + calling std::num_get::get(). After that: + * If lval < std::numeric_limits::min(), sets failbit and stores + std::numeric_limits::min() to val. + * Otherwise, if std::numeric_limits::max() < lval, sets failbit and stores + std::numeric_limits::max() to val. + * Otherwise, stores static_cast(lval) to val. + 14) Extracts an extended floating-point value potentially skipping preceding + whitespace. The value is stored to a given reference value. The library provides + overloads for all cv-unqualified extended floating-point types as the referenced + type of the parameter value. + Determines the standard floating-point type FP as follows: + * If the floating-point conversion rank of /* extended-floating-point-type */ is + less than or equal to that of float, then FP is float. + * Otherwise, if the floating-point conversion rank of /* + extended-floating-point-type */ is less than or equal to that of double, then FP + is double. + * Otherwise, FP is long double. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts an FP value fval by + calling std::num_get::get(). After that: + * If fval < -std::numeric_limits::max(), sets + failbit and stores -std::numeric_limits::max() to val. + * Otherwise, if std::numeric_limits::max() < + fval, sets failbit and stores std::numeric_limits::max() to val. + * Otherwise, stores static_cast(fval) to val. + 15-17) Calls func(*this), where func is an I/O manipulator. + 18) Behaves as an UnformattedInputFunction. After constructing and checking the + sentry object, extracts all data from *this and stores it to sb. The extraction + stops if one of the following conditions are met: + + * end-of-file occurs on the input sequence; + * inserting in the output sequence fails (in which case the character to be + inserted is not extracted); + * an exception occurs (in which case the exception is caught, and only rethrown if + it inserted no characters and failbit is enabled in exceptions()). + In either case, stores the number of characters extracted in the member variable + accessed by subsequent calls to gcount(). If sb is a null pointer or if no + characters were inserted into sb, calls setstate(failbit) (which may throw + std::ios_base::failure if enabled). + + If extraction fails (e.g. if a letter was entered where a digit is expected), zero + is written to value and failbit is set. For signed integers, if extraction results + in the value too large or too small to fit in value, std::numeric_limits::max() + or std::numeric_limits::min() (respectively) is written and failbit flag is set. + For unsigned integers, if extraction results in the value too large or too small to + fit in value, std::numeric_limits::max() is written and failbit flag is set. + +.SH Parameters + + value - reference to an integer or floating-point value to store the extracted value + to + func - pointer to I/O manipulator function + sb - pointer to the stream buffer to write all the data to + +.SH Return value + + 1-16,18) *this + 17) func(*this) + +.SH Notes + + For overload \fB(14)\fP, when the extended floating-point type has a floating-point + conversion rank that is not equal to the rank of any standard floating-point type, + then double rounding during the conversion can result in inaccurate results. + std::from_chars() can be used in situations where maximum accuracy is important. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string input = "41 3.14 false hello world"; + std::istringstream stream(input); + + int n; + double f; + bool b; + + stream >> n >> f >> std::boolalpha >> b; + std::cout << "n = " << n << '\\n' + << "f = " << f << '\\n' + << "b = " << std::boolalpha << b << '\\n'; + + // extract the rest using the streambuf overload + stream >> std::cout.rdbuf(); + std::cout << '\\n'; + } + +.SH Output: + + n = 41 + f = 3.14 + b = false + hello world + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether overload \fB(18)\fP + LWG 64 C++98 can only rethrow the all exceptions caught + std::ios_base::failure thrown by can be rethrown + calling setstate(failbit) + overload (12,13) delegated the + LWG 118 C++98 extraction to num_get::get, a long value is extracted + but it does not have overloads for instead of short or int + short and int + overload \fB(18)\fP only rethrew exceptions + LWG 413 C++98 thrown while extracting corrected sb to *this + characters from sb, but characters are + extracted from *this + overload \fB(18)\fP behaved as a + LWG 567 C++98 FormattedInputFunction it behaves as an + because of the resolution of LWG issue UnformattedInputFunction + 60 + overloads (12,13) did not store the + LWG 661 C++98 extracted number stores the number if + to value due to the resolution of LWG no overflow occurs + issue 118 + LWG 696 C++98 value was unchanged on extraction set to zero or minimum/ + failure maximum values + +.SH See also + + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + operator<< performs stream input and output of bitsets + operator>> \fI(function template)\fP + operator<< serializes and deserializes a complex number + operator>> \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number engine + \fI(C++11)\fP \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number distribution + \fI(C++11)\fP \fI(function template)\fP + read extracts blocks of characters + \fI(public member function)\fP + readsome extracts already available blocks of characters + \fI(public member function)\fP + get extracts characters + \fI(public member function)\fP + extracts characters until the given character is + getline found + \fI(public member function)\fP + from_chars converts a character sequence to an integer or + \fI(C++17)\fP floating-point value + \fI(function)\fP diff --git a/man/std::istream::peek.3 b/man/std::istream::peek.3 deleted file mode 120000 index 156513bd1..000000000 --- a/man/std::istream::peek.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::peek.3 \ No newline at end of file diff --git a/man/std::istream::peek.3 b/man/std::istream::peek.3 new file mode 100644 index 000000000..64eb5921a --- /dev/null +++ b/man/std::istream::peek.3 @@ -0,0 +1,57 @@ +.TH std::basic_istream::peek 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::peek \- std::basic_istream::peek + +.SH Synopsis + int_type peek(); + + Behaves as UnformattedInputFunction. After constructing and testing the sentry + object, reads the next character from the input stream without extracting it. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If good() == true, returns the next character as obtained by rdbuf()->sgetc(). + + Otherwise, returns Traits::eof(). + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("Hello, world."); + char c1 = s1.peek(); + char c2 = s1.get(); + std::cout << "Peeked: " << c1 << " got: " << c2 << '\\n'; + } + +.SH Output: + + Peeked: H got: H + +.SH See also + + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function of std::basic_streambuf)\fP + get extracts characters + \fI(public member function)\fP + unget unextracts a character + \fI(public member function)\fP diff --git a/man/std::istream::putback.3 b/man/std::istream::putback.3 deleted file mode 120000 index 03f04c9e6..000000000 --- a/man/std::istream::putback.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::putback.3 \ No newline at end of file diff --git a/man/std::istream::putback.3 b/man/std::istream::putback.3 new file mode 100644 index 000000000..6fa8681e7 --- /dev/null +++ b/man/std::istream::putback.3 @@ -0,0 +1,90 @@ +.TH std::basic_istream::putback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::putback \- std::basic_istream::putback + +.SH Synopsis + basic_istream& putback( char_type ch ); + + Puts the character ch back to the input stream so the next extracted character will + be ch. + + First clears eofbit, then behaves as UnformattedInputFunction. After constructing + and checking the sentry object, if rdbuf() is not null, calls + rdbuf()->sputbackc(ch), which calls rdbuf()->pbackfail(ch) if ch does not equal the + most recently extracted character. + + If rdbuf() is null or if rdbuf->sputbackc(ch) returns Traits::eof(), calls + setstate(badbit). + + In any case, sets the gcount() counter to zero. + +.SH Parameters + + ch - character to put into input stream + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + Demonstrates the difference between modifying and non-modifying putback(). + + +// Run this code + + #include + #include + + int main() + { + std::stringstream s1("Hello, world"); // IO stream + s1.get(); + if (s1.putback('Y')) // modifies the buffer + std::cout << s1.rdbuf() << '\\n'; + else + std::cout << "putback failed\\n"; + + std::cout << "--\\n"; + + std::istringstream s2("Hello, world"); // input-only stream + s2.get(); + if (s2.putback('Y')) // cannot modify input-only buffer + std::cout << s2.rdbuf() << '\\n'; + else + std::cout << "putback failed\\n"; + s2.clear(); + + std::cout << "--\\n"; + + if (s2.putback('H')) // non-modifying putback + std::cout << s2.rdbuf() << '\\n'; + else + std::cout << "putback failed\\n"; + } + +.SH Output: + + Yello, world + -- + putback failed + -- + Hello, world + +.SH See also + + sputbackc puts one character back in the input sequence + \fI(public member function of std::basic_streambuf)\fP + unget unextracts a character + \fI(public member function)\fP + peek reads the next character without extracting it + \fI(public member function)\fP diff --git a/man/std::istream::read.3 b/man/std::istream::read.3 deleted file mode 120000 index 08538673e..000000000 --- a/man/std::istream::read.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::read.3 \ No newline at end of file diff --git a/man/std::istream::read.3 b/man/std::istream::read.3 new file mode 100644 index 000000000..50d124360 --- /dev/null +++ b/man/std::istream::read.3 @@ -0,0 +1,98 @@ +.TH std::basic_istream::read 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::read \- std::basic_istream::read + +.SH Synopsis + basic_istream& read( char_type* s, std::streamsize count ); + + Extracts characters from stream. + + Behaves as UnformattedInputFunction. After constructing and checking the sentry + object, extracts characters and stores them into successive locations of the + character array whose first element is pointed to by s. Characters are extracted and + stored until any of the following conditions occurs: + + * count characters were extracted and stored. + * end of file condition occurs on the input sequence (in which case, + setstate(failbit|eofbit) is called). The number of successfully extracted + characters can be queried using gcount(). + +.SH Parameters + + s - pointer to the character array to store the characters to + count - number of characters to read + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + When using a non-converting locale (the default locale is non-converting), the + overrider of this function in std::basic_ifstream may be optimized for zero-copy + bulk I/O (by means of overriding std::streambuf::xsgetn). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + // read() is often used for binary I/O + std::string bin = {'\\x12', '\\x12', '\\x12', '\\x12'}; + std::istringstream raw(bin); + std::uint32_t n; + if (raw.read(reinterpret_cast(&n), sizeof n)) + std::cout << std::hex << std::showbase << n << '\\n'; + + // prepare file for next snippet + std::ofstream("test.txt", std::ios::binary) << "abcd1\\nabcd2\\nabcd3"; + + // read entire file into string + if (std::ifstream is{"test.txt", std::ios::binary | std::ios::ate}) + { + auto size = is.tellg(); + std::string str(size, '\\0'); // construct string to stream size + is.seekg(0); + if (is.read(&str[0], size)) + std::cout << str << '\\n'; + } + } + +.SH Output: + + 0x12121212 + abcd1 + abcd2 + abcd3 + +.SH See also + + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP + operator>> extracts formatted data + \fI(public member function)\fP + readsome extracts already available blocks of characters + \fI(public member function)\fP + get extracts characters + \fI(public member function)\fP + getline extracts characters until the given character is found + \fI(public member function)\fP + fread reads from a file + \fI(function)\fP diff --git a/man/std::istream::readsome.3 b/man/std::istream::readsome.3 deleted file mode 120000 index bd007d18f..000000000 --- a/man/std::istream::readsome.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::readsome.3 \ No newline at end of file diff --git a/man/std::istream::readsome.3 b/man/std::istream::readsome.3 new file mode 100644 index 000000000..88305a46e --- /dev/null +++ b/man/std::istream::readsome.3 @@ -0,0 +1,77 @@ +.TH std::basic_istream::readsome 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::readsome \- std::basic_istream::readsome + +.SH Synopsis + std::streamsize readsome( char_type* s, std::streamsize count ); + + Extracts up to count immediately available characters from the input stream. The + extracted characters are stored into the character array pointed to by s. + + Behaves as UnformattedInputFunction. After constructing and checking the sentry + object, + + * If rdbuf()->in_avail() == -1, calls setstate(eofbit) and extracts no characters. + * If rdbuf()->in_avail() == 0, extracts no characters. + * If rdbuf()->in_avail() > 0, extracts std::min(rdbuf()->in_avail(), count) + characters and stores them into successive locations of the character array + whose first element is pointed to by s. + +.SH Parameters + + s - pointer to the character array to store the characters to + count - maximum number of characters to read + +.SH Return value + + The number of characters actually extracted. + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + The behavior of this function is highly implementation-specific. For example, when + used with std::ifstream, some library implementations fill the underlying filebuf + with data as soon as the file is opened (and readsome() on such implementations + reads data, potentially, but not necessarily, the entire file), while other + implementations only read from file when an actual input operation is requested (and + readsome() issued after file opening never extracts any characters). Likewise, a + call to std::cin.readsome() may return all pending unprocessed console input, or may + always return zero and extract no characters. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char c[10] = {}; + std::istringstream input("This is sample text."); // std::stringbuf makes its entire + // buffer available for + // unblocking read + input.readsome(c, 5); // reads 'This ' and stores in c[0] .. c[4] + input.readsome(c, 9); // reads 'is sample' and stores in c[0] .. c[8] + std::cout << c << '\\n'; + } + +.SH Output: + + is sample + +.SH See also + + read extracts blocks of characters + \fI(public member function)\fP + in_avail obtains the number of characters immediately available in the get area + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::istream::seekg.3 b/man/std::istream::seekg.3 deleted file mode 120000 index de02c4c0a..000000000 --- a/man/std::istream::seekg.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::seekg.3 \ No newline at end of file diff --git a/man/std::istream::seekg.3 b/man/std::istream::seekg.3 new file mode 100644 index 000000000..a468b667d --- /dev/null +++ b/man/std::istream::seekg.3 @@ -0,0 +1,125 @@ +.TH std::basic_istream::seekg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::seekg \- std::basic_istream::seekg + +.SH Synopsis + basic_istream& seekg( pos_type pos ); \fB(1)\fP + basic_istream& seekg( off_type off, std::ios_base::seekdir dir ); \fB(2)\fP + + Sets input position indicator of the current associated streambuf object. + + Before doing anything else, seekg clears eofbit. \fI(since C++11)\fP + + seekg behaves as UnformattedInputFunction, except that gcount() is not affected. + After constructing and checking the sentry object, + + 1) if fail() != true, sets the input position indicator to absolute (relative to the + beginning of the file) value pos. Specifically, executes rdbuf()->pubseekpos(pos, + std::ios_base::in) (pubseekpos, in turn, calls seekpos of the specific buffer, such + as basic_filebuf::seekpos, basic_stringbuf::seekpos, or strstreambuf::seekpos). In + case of failure, calls setstate(std::ios_base::failbit). + 2) if fail() != true, sets the input position indicator to position off, relative to + position, defined by dir. Specifically, executes rdbuf()->pubseekoff(off, dir, + std::ios_base::in). In case of failure, calls setstate(std::ios_base::failbit). + +.SH Parameters + + pos - absolute position to set the input position indicator to + off - relative position (positive or negative) to set the input position indicator + to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + seekg(n) is not necessarily equivalent to seekg(n, ios::beg). std::basic_ifstream, + for example, requires the absolute position n to come from tellg(). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str = "Hello, world"; + std::istringstream in(str); + std::string word1, word2; + + in >> word1; + in.seekg(0); // rewind + in >> word2; + + std::cout << "word1 = " << word1 << '\\n' + << "word2 = " << word2 << '\\n'; + } + +.SH Output: + + word1 = Hello, + word2 = Hello, + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 129 C++98 there was no way to indicate a failure sets failbit on failure + LWG 136 C++98 seekg could set the output stream only sets the input stream + LWG 537 C++98 the type of off was off_type& corrected to off_type + +.SH See also + + tellg returns the input position indicator + \fI(public member function)\fP + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::istream::sentry.3 b/man/std::istream::sentry.3 deleted file mode 120000 index 3f06fb400..000000000 --- a/man/std::istream::sentry.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::sentry.3 \ No newline at end of file diff --git a/man/std::istream::sentry.3 b/man/std::istream::sentry.3 new file mode 100644 index 000000000..57fab4d3d --- /dev/null +++ b/man/std::istream::sentry.3 @@ -0,0 +1,139 @@ +.TH std::basic_istream::sentry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::sentry \- std::basic_istream::sentry + +.SH Synopsis + class sentry; + + An object of class basic_istream::sentry is constructed in local scope at the + beginning of each member function of std::basic_istream that performs input (both + formatted and unformatted). Its constructor prepares the input stream: checks if the + stream is already in a failed state, flushes the tie()'d output streams, skips + leading whitespace unless noskipws flag is set, and performs other + implementation-defined tasks if necessary. All cleanup, if necessary, is performed + in the destructor, so that it is guaranteed to happen if exceptions are thrown + during input. + +.SH Member types + + traits_type Traits + +.SH Member functions + + constructor constructs the sentry object. All the preparation tasks are done here + \fI(public member function)\fP + finalizes the stream object after formatted input or after exception, + destructor if necessary + \fI(public member function)\fP + operator= not copy assignable + [deleted] \fI(public member function)\fP + operator bool checks if the preparation of the stream object was successful + \fI(public member function)\fP + +std::basic_istream::sentry::sentry + + explicit sentry( std::basic_istream& is, bool noskipws = false ); + + Prepares the stream for formatted input. + + If is.good() is false, calls is.setstate(std::ios_base::failbit) and returns. + Otherwise, if is.tie() is not a null pointer, calls is.tie()->flush() to synchronize + the output sequence with external streams. This call can be suppressed if the put + area of is.tie() is empty. The implementation may defer the call to flush() until a + call of is.rdbuf()->underflow() occurs. If no such call occurs before the sentry + object is destroyed, it may be eliminated entirely. + + If noskipws is zero and is.flags() & std::ios_base::skipws is nonzero, the function + extracts and discards all whitespace characters until the next available character + is not a whitespace character (as determined by the currently imbued locale in is). + If is.rdbuf()->sbumpc() or is.rdbuf()->sgetc() returns traits::eof(), the function + calls setstate(std::ios_base::failbit | std::ios_base::eofbit) (which may throw + std::ios_base::failure). + + Additional implementation-defined preparation may take place, which may call + setstate(std::ios_base::failbit) (which may throw std::ios_base::failure). + + If after preparation is completed, is.good() == true, then any subsequent calls to + operator bool will return true. + +.SH Parameters + + is - input stream to prepare + noskipws - true if whitespace should not be skipped + +.SH Exceptions + + std::ios_base::failure if the end of file condition occurs when skipping whitespace. + +std::basic_istream::sentry::~sentry + + ~sentry(); + + Does nothing. + +std::basic_istream::sentry::operator bool + + explicit operator bool() const; + + Checks whether the preparation of the input stream was successful. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the initialization of the input stream was successful, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + char n[5]; + }; + + std::istream& operator>>(std::istream& is, Foo& f) + { + std::istream::sentry s(is); + if (s) + is.read(f.n, 5); + return is; + } + + int main() + { + std::string input = " abcde"; + std::istringstream stream(input); + Foo f; + stream >> f; + std::cout.write(f.n, 5); + std::cout << '\\n'; + } + +.SH Output: + + abcde + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 195 C++98 it was unclear whether the constructor made clear + would set eofbit + LWG 419 C++98 the constructor did not set failbit if sets failbit in this case + eofbit has been set + +.SH See also + + operator>> extracts formatted data + \fI(public member function)\fP + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP diff --git a/man/std::istream::swap.3 b/man/std::istream::swap.3 deleted file mode 120000 index b7cf152f2..000000000 --- a/man/std::istream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::swap.3 \ No newline at end of file diff --git a/man/std::istream::swap.3 b/man/std::istream::swap.3 new file mode 100644 index 000000000..baeb989c7 --- /dev/null +++ b/man/std::istream::swap.3 @@ -0,0 +1,42 @@ +.TH std::basic_istream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::swap \- std::basic_istream::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_istream& rhs ); + + Calls basic_ios::swap(rhs) to swap all data members of the base class except for + rdbuf(), and swaps the values of the gcount() counters between *this and rhs. This + swap function is protected: it is called by the swap functions of the swappable + input stream classes std::basic_ifstream and std::basic_istringstream, which know + how to correctly swap the associated streambuffers. + +.SH Parameters + + rhs - different basic_istream object of the same type to swap with + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream s1("hello"); + std::istringstream s2("bye"); + + s1.swap(s2); // OK, istringstream has a public swap() + std::swap(s1, s2); // OK, calls s1.swap(s2) + // std::cin.swap(s2); // ERROR: swap is a protected member + + std::cout << s1.rdbuf() << '\\n'; + } + +.SH Output: + + hello diff --git a/man/std::istream::sync.3 b/man/std::istream::sync.3 deleted file mode 120000 index 01cbcaef2..000000000 --- a/man/std::istream::sync.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::sync.3 \ No newline at end of file diff --git a/man/std::istream::sync.3 b/man/std::istream::sync.3 new file mode 100644 index 000000000..3bba89af5 --- /dev/null +++ b/man/std::istream::sync.3 @@ -0,0 +1,111 @@ +.TH std::basic_istream::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::sync \- std::basic_istream::sync + +.SH Synopsis + int sync(); + + Synchronizes the input buffer with the associated data source. + + Behaves as UnformattedInputFunction, except that gcount() is not affected. After + constructing and checking the sentry object, + + If rdbuf() is a null pointer, returns -1. + + Otherwise, calls rdbuf()->pubsync(). If that function returns -1, calls + setstate(badbit) and returns -1. Otherwise, returns 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 0 on success, -1 on failure or if the stream does not support this operation (is + unbuffered). + +.SH Notes + + As with readsome(), it is implementation-defined whether this function does anything + with library-supplied streams. The intent is typically for the next read operation + to pick up any changes that may have been made to the associated input sequence + after the stream buffer last filled its get area. To achieve that, sync() may empty + the get area, or it may refill it, or it may do nothing. A notable exception is + Visual Studio, where this operation discards the unprocessed input when called with + a standard input stream. + +.SH Example + + Demonstrates the use of input stream sync() with file input. Note that output here + is implementation-defined, since calls to std::basic_filebuf::sync are + implementation-defined for reads. + + +// Run this code + + #include + #include + + void file_abc() + { + std::ofstream f("test.txt"); + f << "abc\\n"; + } + + void file_123() + { + std::ofstream f("test.txt"); + f << "123\\n"; + } + + int main() + { + file_abc(); // file now contains "abc" + std::ifstream f("test.txt"); + std::cout << "Reading from the file\\n"; + char c; + f >> c; + std::cout << c; + file_123(); // file now contains "123" + f >> c; + std::cout << c; + f >> c; + std::cout << c << '\\n'; + f.close(); + + file_abc(); // file now contains "abc" + f.open("test.txt"); + std::cout << "Reading from the file, with sync()\\n"; + f >> c; + std::cout << c; + file_123(); // file now contains "123" + f.sync(); + f >> c; + std::cout << c; + f >> c; + std::cout << c << '\\n'; + } + +.SH Possible output: + + Reading from the file + abc + Reading from the file, with sync() + a23 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 62 C++98 sync() returned traits::eof() if returns -1 in this + rdbuf()->pubsync() returns -1 case + +.SH See also + + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::istream::tellg.3 b/man/std::istream::tellg.3 deleted file mode 120000 index 2f0fd2172..000000000 --- a/man/std::istream::tellg.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::tellg.3 \ No newline at end of file diff --git a/man/std::istream::tellg.3 b/man/std::istream::tellg.3 new file mode 100644 index 000000000..54a391297 --- /dev/null +++ b/man/std::istream::tellg.3 @@ -0,0 +1,72 @@ +.TH std::basic_istream::tellg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::tellg \- std::basic_istream::tellg + +.SH Synopsis + pos_type tellg(); + + Returns input position indicator of the current associated streambuf object. + + Behaves as UnformattedInputFunction, except that gcount() is not affected. After + constructing and checking the sentry object, if fail() == true, returns + pos_type(-1). Otherwise, returns rdbuf()->pubseekoff(0, std::ios_base::cur, + std::ios_base::in). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current position of the get pointer on success, pos_type(-1) on failure. + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str = "Hello, world"; + std::istringstream in(str); + std::string word; + in >> word; + std::cout << "After reading the word \\"" << word + << "\\" tellg() returns " << in.tellg() << '\\n'; + } + +.SH Output: + + After reading the word "Hello," tellg() returns 6 + +.SH See also + + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + seekg sets the input position indicator + \fI(public member function)\fP + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::istream::unget.3 b/man/std::istream::unget.3 deleted file mode 120000 index 3852e7e9e..000000000 --- a/man/std::istream::unget.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::unget.3 \ No newline at end of file diff --git a/man/std::istream::unget.3 b/man/std::istream::unget.3 new file mode 100644 index 000000000..020541534 --- /dev/null +++ b/man/std::istream::unget.3 @@ -0,0 +1,68 @@ +.TH std::basic_istream::unget 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::unget \- std::basic_istream::unget + +.SH Synopsis + basic_istream& unget(); + + Makes the most recently extracted character available again. + + First, clears eofbit. Then, + \fI(since C++11)\fP unget behaves as UnformattedInputFunction. After constructing and + checking the sentry object, if any ios_base::iostate flags are set, the function + sets failbit and returns. Otherwise, calls rdbuf()->sungetc(). + + If rdbuf()->sungetc() returns Traits::eof(), calls setstate(badbit). + + In any case, sets the gcount() counter to zero. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("Hello, world."); + char c1 = s1.get(); + if (s1.unget()) + { + char c2 = s1.get(); + std::cout << "Got: '" << c1 << "'. Got again: '" << c2 << "'.\\n"; + } + } + +.SH Output: + + Got: 'H'. Got again: 'H'. + +.SH See also + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function of std::basic_streambuf)\fP + get extracts characters + \fI(public member function)\fP + peek reads the next character without extracting it + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function)\fP diff --git a/man/std::istream::~basic_istream.3 b/man/std::istream::~basic_istream.3 deleted file mode 120000 index dcea33ae0..000000000 --- a/man/std::istream::~basic_istream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::~basic_istream.3 \ No newline at end of file diff --git a/man/std::istream::~basic_istream.3 b/man/std::istream::~basic_istream.3 new file mode 100644 index 000000000..132879f14 --- /dev/null +++ b/man/std::istream::~basic_istream.3 @@ -0,0 +1,44 @@ +.TH std::basic_istream::~basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::~basic_istream \- std::basic_istream::~basic_istream + +.SH Synopsis + virtual ~basic_istream(); + + Destructs the input stream. + +.SH Notes + + This destructor does not perform any operation on the underlying streambuffer + (rdbuf()): the destructors of the derived input streams such as std::basic_ifstream + and std::basic_istringstream are responsible for calling the destructors of the + streambuffers. + +.SH Example + + +// Run this code + + #include + #include + + void print_stringbuf(std::streambuf* p) + { + std::istream buf(p); // buf shares the buffer with s1 + int n; + buf >> n; + std::cout << n; + } // calls the destructor of buf. p remains unaffected + + int main() + { + std::istringstream s1("10 20"); + print_stringbuf(s1.rdbuf()); + int n; + s1 >> n; + std::cout << ',' << n << '\\n'; + } + +.SH Output: + + 10,20 diff --git a/man/std::istream_iterator.3 b/man/std::istream_iterator.3 index e0a24ac8f..4d0e23a86 100644 --- a/man/std::istream_iterator.3 +++ b/man/std::istream_iterator.3 @@ -1,64 +1,80 @@ -.TH std::istream_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istream_iterator \- std::istream_iterator + .SH Synopsis Defined in header template< class T, class CharT = char, class Traits = std::char_traits, + class Distance = std::ptrdiff_t > \fI(until C++17)\fP + class istream_iterator + + : public std::iterator + template< class T, + + class CharT = char, + class Traits = std::char_traits, \fI(since C++17)\fP class Distance = std::ptrdiff_t > - class istream_iterator: public std::iterator + class istream_iterator; std::istream_iterator is a single-pass input iterator that reads successive objects of type T from the std::basic_istream object for which it was constructed, by calling the appropriate operator>>. The actual read operation is performed when the - iterator is incremented, not when it is dereferenced. The first object may be read - when the iterator is constructed or when the first dereferencing is done. Otherwise, - dereferencing only returns a copy of the most recently read object. + iterator is incremented, not when it is dereferenced. The first object is read when + the iterator is constructed. Dereferencing only returns a copy of the most recently + read object. The default-constructed std::istream_iterator is known as the end-of-stream iterator. When a valid std::istream_iterator reaches the end of the underlying stream, it becomes equal to the end-of-stream iterator. Dereferencing or - incrementing it further invokes undefined behavior. + incrementing it further invokes undefined behavior. An end-of-stream iterator + remains in the end-of-stream state even if the underlying stream changes state. + Absent a reassignment, it cannot become a non-end-of-stream iterator anymore. A typical implementation of std::istream_iterator holds two data members: a pointer to the associated std::basic_istream object and the most recently read value of type T. -.SH Member types - - Member type Definition - char_type CharT - traits_type Traits - istream_type std::basic_istream - -.SH Member functions - - constructor constructs a new istream_iterator - \fI(public member function)\fP - destructor destructs an istream_iterator, including the cached value - (implicitly declared) \fI(public member function)\fP - operator* returns the current element - operator-> \fI(public member function)\fP - operator++ advances the iterator - operator++(int) \fI(public member function)\fP - -.SH Non-member functions - - operator== compares two istream_iterators - operator!= \fI(function template)\fP - -Inherited from std::iterator + T must meet the DefaultConstructible, CopyConstructible, and CopyAssignable + requirements. .SH Member types Member type Definition + iterator_category std::input_iterator_tag value_type T difference_type Distance pointer const T* reference const T& - iterator_category std::input_iterator_tag + char_type CharT + traits_type Traits + istream_type std::basic_istream + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. + +.SH Member functions + + constructor constructs a new istream_iterator + \fI(public member function)\fP + destructor destructs an istream_iterator, including the cached value + \fI(public member function)\fP + operator* returns the current element + operator-> \fI(public member function)\fP + operator++ advances the iterator + operator++(int) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares two istream_iterators + operator!= \fI(function template)\fP + (removed in C++20) .SH Notes @@ -69,29 +85,52 @@ Inherited from std::iterator .SH Example - + // Run this code + #include #include - #include #include #include - + #include + int main() { std::istringstream str("0.1 0.2 0.3 0.4"); std::partial_sum(std::istream_iterator(str), std::istream_iterator(), std::ostream_iterator(std::cout, " ")); + + std::istringstream str2("1 3 5 7 8 9 10"); + auto it = std::find_if(std::istream_iterator(str2), + std::istream_iterator(), + [](int i){ return i % 2 == 0; }); + + if (it != std::istream_iterator()) + std::cout << "\\nThe first even number is " << *it << ".\\n"; + //" 9 10" left in the stream } .SH Output: 0.1 0.3 0.6 1 + The first even number is 8. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0738R2 C++98 the first read might be deferred to the always performed in the + first dereference constructor .SH See also ostream_iterator output iterator that writes to std::basic_ostream - \fI(class template)\fP + \fI(class template)\fP istreambuf_iterator input iterator that reads from std::basic_streambuf - \fI(class template)\fP + \fI(class template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::istream_iterator::istream_iterator.3 b/man/std::istream_iterator::istream_iterator.3 index 13a824167..512733bbd 100644 --- a/man/std::istream_iterator::istream_iterator.3 +++ b/man/std::istream_iterator::istream_iterator.3 @@ -1,32 +1,45 @@ -.TH std::istream_iterator::istream_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istream_iterator::istream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istream_iterator::istream_iterator \- std::istream_iterator::istream_iterator + .SH Synopsis - istream_iterator(); \fB(1)\fP (since C++11, only if T is - constexpr istream_iterator(); literal type) - istream_iterator( istream_type& stream ); \fB(2)\fP - istream_iterator( const istream_iterator& other ) = \fB(3)\fP - default; - - 1) Constructs the end-of-stream iterator. - 2) Initializes the iterator and stores the address of stream in a data member. - Optionally, performs the first read from the input stream to initialize the cached - value data member (although it may be delayed until the first access) - 3) Constructs a copy of other. If T is a literal type, this copy constructor is a - trivial copy constructor. + istream_iterator(); \fI(until C++11)\fP + constexpr istream_iterator(); \fI(since C++11)\fP + constexpr istream_iterator( \fB(2)\fP \fI(since C++20)\fP + std::default_sentinel_t ); + istream_iterator( istream_type& stream ); \fB(1)\fP \fB(3)\fP + istream_iterator( const istream_iterator& other \fI(until C++11)\fP + ); \fB(4)\fP + istream_iterator( const istream_iterator& other \fI(since C++11)\fP + ) = default; + + 1,2) Constructs the end-of-stream iterator + , value-initializes the stored value. This constructor is constexpr if the + initializer in the definition auto x = T(); is a constant initializer + \fI(since C++11)\fP. + 3) Initializes the iterator, stores the address of stream in a data member, and + performs the first read from the input stream to initialize the cached value data + member. + 4) Constructs a copy of other. + If std::is_trivially_copy_constructible::value is true, this copy constructor is + a trivial copy constructor. + \fI(since C++11)\fP .SH Parameters stream - stream to initialize the istream_iterator with other - another istream_iterator of the same type -.SH Examples +.SH Example + - // Run this code + #include #include #include - #include #include + int main() { std::istringstream stream("1 2 3 4 5"); @@ -40,3 +53,13 @@ .SH Output: 1 2 3 4 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1280 C++98 overload \fB(3)\fP stored stream directly stores its address instead + P0738R2 C++98 the first read might be deferred to always performed in the + the first dereference constructor diff --git a/man/std::istream_iterator::operator*,operator->.3 b/man/std::istream_iterator::operator*,operator->.3 index a19c9235b..b3b2732c3 100644 --- a/man/std::istream_iterator::operator*,operator->.3 +++ b/man/std::istream_iterator::operator*,operator->.3 @@ -1,4 +1,7 @@ -.TH std::istream_iterator::operator*,operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istream_iterator::operator*,operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istream_iterator::operator*,operator-> \- std::istream_iterator::operator*,operator-> + .SH Synopsis const T& operator*() const; \fB(1)\fP const T* operator->() const; \fB(2)\fP @@ -17,4 +20,4 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. diff --git a/man/std::istream_iterator::operator++,operator++(int).3 b/man/std::istream_iterator::operator++,operator++(int).3 index ab3d5261a..4ce44eea1 100644 --- a/man/std::istream_iterator::operator++,operator++(int).3 +++ b/man/std::istream_iterator::operator++,operator++(int).3 @@ -1,9 +1,14 @@ -.TH std::istream_iterator::operator++,operator++(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istream_iterator::operator++,operator++(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istream_iterator::operator++,operator++(int) \- std::istream_iterator::operator++,operator++(int) + .SH Synopsis - istream_iterator& operator++(); \fB(1)\fP - istream_iterator operator++(int); \fB(2)\fP + istream_iterator& operator++(); \fB(1)\fP + istream_iterator operator++( int ); \fB(2)\fP - Reads a value from the underlying stream and stores it into the iterator object. + Reads a value from the underlying stream (using its operator>>) and stores it into + the iterator object. If the read fails (the underlying stream's fail() returns + true), the iterator becomes the end-of-stream iterator. The behavior is undefined if the iterator is end-of-stream iterator. @@ -13,9 +18,26 @@ .SH Return value - 1) *this. + 1) *this 2) An istream_iterator that holds an unchanged value. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 260 C++98 the return type of operator++(int) was corrected to + istream_iterator& istream_iterator + the underlying stream's operator void* + was + LWG 788 C++98 used to determine whether the read uses fail() instead + fails, but it + was removed by the resolution of LWG + issue 468 + LWG 838 C++98 it was unclear whether end-of-stream the behavior is undefined + iterators can be incremented diff --git a/man/std::istream_iterator::~istream_iterator.3 b/man/std::istream_iterator::~istream_iterator.3 new file mode 100644 index 000000000..d77364657 --- /dev/null +++ b/man/std::istream_iterator::~istream_iterator.3 @@ -0,0 +1,12 @@ +.TH std::istream_iterator::~istream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istream_iterator::~istream_iterator \- std::istream_iterator::~istream_iterator + +.SH Synopsis + ~istream_iterator(); \fI(until C++11)\fP + ~istream_iterator() = default; \fI(since C++11)\fP + + Destroys the iterator, including the cached value. + + If std::is_trivially_destructible::value is true, then this \fI(since C++11)\fP + destructor is a trivial destructor. diff --git a/man/std::istreambuf_iterator.3 b/man/std::istreambuf_iterator.3 index baf894eaa..4bfdd1e97 100644 --- a/man/std::istreambuf_iterator.3 +++ b/man/std::istreambuf_iterator.3 @@ -1,131 +1,156 @@ -.TH std::istreambuf_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istreambuf_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istreambuf_iterator \- std::istreambuf_iterator + .SH Synopsis Defined in header template< class CharT, class Traits = std::char_traits > - class istreambuf_iterator : public std::iterator< std::input_iterator_tag, - CharT, - typename Traits::off_type, - /* unspecified, usually CharT* - */, + class istreambuf_iterator + : public std::iterator + /* unspecified */, CharT> + template< class CharT, class Traits = std::char_traits > \fI(since C++17)\fP + class istreambuf_iterator; std::istreambuf_iterator is a single-pass input iterator that reads successive - characters from the std::basic_streambuf object for which it was constructed. The - actual read operation is performed when the iterator is incremented, not when it is - dereferenced. The first character may be read when the iterator is constructed or - when the first dereferencing is done. Otherwise, dereferencing only returns a copy - of the most recently read character. + characters from the std::basic_streambuf object for which it was constructed. The default-constructed std::istreambuf_iterator is known as the end-of-stream iterator. When a valid std::istreambuf_iterator reaches the end of the underlying stream, it becomes equal to the end-of-stream iterator. Dereferencing or incrementing it further invokes undefined behavior. - std::istreambuf_iterator has a trivial copy constructor, a constexpr default - constructor, and a trivial destructor. + std::istreambuf_iterator has a trivial copy constructor, a constexpr \fI(since C++11)\fP + default constructor, and a trivial destructor. .SH Member types - Member type Definition - char_type CharT - traits_type Traits - int_type typename traits::int_type - streambuf_type std::basic_streambuf - istream_type std::basic_istream - - This section is incomplete - Reason: the proxy member type + Member type Definition + iterator_category std::input_iterator_tag + value_type CharT + difference_type typename Traits::off_type + pointer /* unspecified */ + reference CharT + char_type CharT + traits_type Traits + int_type typename Traits::int_type + streambuf_type std::basic_streambuf + istream_type std::basic_istream + Implementation-defined class type. The name proxy is for + exposition only. + /* proxy */ A proxy object holds a char_type character and a streambuf_type* + pointer. + Dereferencing a proxy object with operator* yields the stored + character. + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. + + The member type pointer is usually CharT* (see below). .SH Member functions constructor constructs a new istreambuf_iterator - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs an istreambuf_iterator - (implicitly declared) \fI(public member function)\fP + (implicitly declared) \fI(public member function)\fP operator* obtains a copy of the current character - operator-> accesses a member of the current character, if CharT has - \fI(since C++11)\fP members - \fI(public member function)\fP + \fI(public member function)\fP operator++ advances the iterator - operator++(int) \fI(public member function)\fP + operator++(int) \fI(public member function)\fP tests if both istreambuf_iterators are end-of-stream or if equal both are valid - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - operator== compares two istreambuf_iterators - operator!= \fI(function template)\fP + operator== compares two istreambuf_iterators + operator!= \fI(function template)\fP + (removed in C++20) -Inherited from std::iterator +.SH Notes -.SH Member types + The resolution of LWG issue 659 introduced operator->. It is expected that given an + std::istreambuf_iterator i, the expressions (*i).m and i->m have the same effect. - Member type Definition - value_type CharT - difference_type Traits::off_type - pointer /* unspecified, usually CharT* */ - reference CharT - iterator_category std::input_iterator_tag + However, the resolution does not provide a formal specification of its behavior. + Thus it is implemented differently, including returning nullptr, returning the + address of a temporary, or does even provide the member at all. Its intended + behavior can hardly be achieved, and it is removed by the resolution of LWG issue + 2790. + + The resolution of LWG issue 659 also made the member type pointer unspecified in + order to allow operator-> to return a proxy. This is to allow operator-> to compile + when CharT is not a class type. .SH Example - + // Run this code - #include - #include #include #include - + #include + #include + int main() { // typical use case: an input stream represented as a pair of iterators - std::istringstream in("Hello, world"); - std::vector v( (std::istreambuf_iterator(in)), - std::istreambuf_iterator() ); - std::cout << "v has " << v.size() << " bytes. "; - v.push_back('\\0'); - std::cout << "it holds \\"" << &v[0] << "\\"\\n"; - - + std::istringstream in{"Hello, world"}; + std::istreambuf_iterator it{in}, end; + std::string ss{it, end}; + std::cout << "ss has " << ss.size() << " bytes; " + "it holds \\"" << ss << "\\"\\n"; + // demonstration of the single-pass nature - std::istringstream s("abc"); - std::istreambuf_iterator i1(s), i2(s); - std::cout << "i1 returns " << *i1 << '\\n' - << "i2 returns " << *i2 << '\\n'; + std::istringstream s{"abc"}; + std::istreambuf_iterator i1{s}, i2{s}; + std::cout << "i1 returns '" << *i1 << "'\\n" + "i2 returns '" << *i2 << "'\\n"; + ++i1; - std::cout << "after incrementing i1, but not i2\\n" - << "i1 returns " << *i1 << '\\n' - << "i2 returns " << *i2 << '\\n'; - ++i2; // this makes the apparent value of *i2 to jump from 'a' to 'c' - std::cout << "after incrementing i2, but not i1\\n" - << "i1 returns " << *i1 << '\\n' - << "i2 returns " << *i2 << '\\n'; - + std::cout << "after incrementing i1, but not i2:\\n" + "i1 returns '" << *i1 << "'\\n" + "i2 returns '" << *i2 << "'\\n"; + + ++i2; + std::cout << "after incrementing i2, but not i1:\\n" + "i1 returns '" << *i1 << "'\\n" + "i2 returns '" << *i2 << "'\\n"; } .SH Output: - v has 12 bytes. it holds "Hello, world" - i1 returns a - i2 returns a - after incrementing i1, but not i2 - i1 returns b - i2 returns a - after incrementing i2, but not i1 - i1 returns b - i2 returns c + ss has 12 bytes; it holds "Hello, world" + i1 returns 'a' + i2 returns 'a' + after incrementing i1, but not i2: + i1 returns 'b' + i2 returns 'b' + after incrementing i2, but not i1: + i1 returns 'c' + i2 returns 'c' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. std::istreambuf_iterator did not have + LWG 659 C++98 operator-> 1. added + 2. the member type pointer was specified as 2. made unspecified + CharT* + LWG 2790 C++98 the operator-> added by LWG issue 659 was removed + not useful .SH See also ostreambuf_iterator output iterator that writes to std::basic_streambuf - \fI(class template)\fP + \fI(class template)\fP istream_iterator input iterator that reads from std::basic_istream - \fI(class template)\fP - -.SH Category: - - * Todo with reason + \fI(class template)\fP diff --git a/man/std::istreambuf_iterator::equal.3 b/man/std::istreambuf_iterator::equal.3 index 417b962ba..813a1e224 100644 --- a/man/std::istreambuf_iterator::equal.3 +++ b/man/std::istreambuf_iterator::equal.3 @@ -1,4 +1,7 @@ -.TH std::istreambuf_iterator::equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istreambuf_iterator::equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istreambuf_iterator::equal \- std::istreambuf_iterator::equal + .SH Synopsis bool equal( const istreambuf_iterator& it ) const; @@ -15,4 +18,16 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 110 C++98 the signature was bool consts added + equal(istreambuf_iterator& it) + LWG issue 110 was not properly resolved, + LWG 1126 C++98 leaving const added + the parameter type as istreambuf_iterator& diff --git a/man/std::istreambuf_iterator::istreambuf_iterator.3 b/man/std::istreambuf_iterator::istreambuf_iterator.3 index 2889dadae..a6b4d02d9 100644 --- a/man/std::istreambuf_iterator::istreambuf_iterator.3 +++ b/man/std::istreambuf_iterator::istreambuf_iterator.3 @@ -1,22 +1,46 @@ -.TH std::istreambuf_iterator::istreambuf_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istreambuf_iterator::istreambuf_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istreambuf_iterator::istreambuf_iterator \- std::istreambuf_iterator::istreambuf_iterator + .SH Synopsis - constexpr istreambuf_iterator(); \fB(1)\fP - istreambuf_iterator( std::basic_istream& is ); \fB(2)\fP - istreambuf_iterator( std::basic_streambuf* s ); \fB(3)\fP + istreambuf_iterator() throw(); (until + C++11) + constexpr istreambuf_iterator() noexcept; (since + C++11) + constexpr istreambuf_iterator( \fB(2)\fP (since + std::default_sentinel_t ) noexcept; C++20) + istreambuf_iterator( (until + std::basic_istream& is ) C++11) + throw(); + istreambuf_iterator( (since + std::basic_istream& is ) C++11) + noexcept; \fB(1)\fP + istreambuf_iterator( (until + std::basic_streambuf* s ) C++11) + throw(); \fB(3)\fP + istreambuf_iterator( (since + std::basic_streambuf* s ) C++11) + noexcept; \fB(4)\fP + istreambuf_iterator( const /* proxy */& p ) (until + throw(); C++11) + istreambuf_iterator( const /* proxy */& p ) \fB(5)\fP (since + noexcept; C++11) + istreambuf_iterator( const \fB(6)\fP (since + istreambuf_iterator& ) noexcept = default; C++11) + + 1,2) Constructs an end-of-stream iterator. + 3) Initializes the iterator and stores the value of is.rdbuf() in a data member. If + is.rdbuf() is null, then end-of-stream iterator is constructed. + 4) Initializes the iterator and stores the value of s in a data member. If s is + null, then end-of-stream iterator is constructed. + 5) Effectively call \fB(3)\fP with the streambuf_type* pointer p holds. + 6) The copy constructor is trivial and explicitly defaulted. - 1) Constructs the end-of-stream iterator. - 2) Initializes the iterator and stores the address of is.rdbuf() in a data member. - If is.rdbuf() is null, then end-of-stream iterator is constructed. - 3) Initializes the iterator and stores the address of s in a data member. + The copy constructor is effectively implicitly declared and not \fI(until C++11)\fP + guaranteed to be trivial. .SH Parameters is - stream to obtain the stream buffer from s - stream buffer to initialize the iterator with - -.SH Exceptions - - 1-4) - noexcept specification: - noexcept - + p - object of the implementation-defined proxy type diff --git a/man/std::istreambuf_iterator::operator*,operator->.3 b/man/std::istreambuf_iterator::operator*,operator->.3 deleted file mode 100644 index 950825e15..000000000 --- a/man/std::istreambuf_iterator::operator*,operator->.3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::istreambuf_iterator::operator*,operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - CharT operator*() const; \fB(1)\fP - CharT* operator->() const; \fB(2)\fP - - Reads a single character. - - 1) Returns the result of sbuf_->sgetc() where sbuf_ is the stored stream buffer. - 2) Returns a pointer to the result of operator*(). - - The behavior is undefined if the iterator is end-of-stream iterator. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - 1) The value of the obtained character. - 2) A pointer to the obtained character. - -.SH Exceptions - - \fI(none)\fP diff --git a/man/std::istreambuf_iterator::operator*.3 b/man/std::istreambuf_iterator::operator*.3 new file mode 100644 index 000000000..1ba5700d3 --- /dev/null +++ b/man/std::istreambuf_iterator::operator*.3 @@ -0,0 +1,23 @@ +.TH std::istreambuf_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istreambuf_iterator::operator* \- std::istreambuf_iterator::operator* + +.SH Synopsis + CharT operator*() const; + + Reads a single character by calling sbuf_->sgetc() where sbuf_ is the stored pointer + to the stream buffer. + + The behavior is undefined if the iterator is end-of-stream iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the obtained character. + +.SH Exceptions + + May throw implementation-defined exceptions. diff --git a/man/std::istreambuf_iterator::operator++,operator++(int).3 b/man/std::istreambuf_iterator::operator++,operator++(int).3 index da47600b1..04929b7ce 100644 --- a/man/std::istreambuf_iterator::operator++,operator++(int).3 +++ b/man/std::istreambuf_iterator::operator++,operator++(int).3 @@ -1,7 +1,10 @@ -.TH std::istreambuf_iterator::operator++,operator++(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istreambuf_iterator::operator++,operator++(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istreambuf_iterator::operator++,operator++(int) \- std::istreambuf_iterator::operator++,operator++(int) + .SH Synopsis istreambuf_iterator& operator++(); \fB(1)\fP - /* unspecified */ operator++(int); \fB(2)\fP + /* proxy */ operator++( int ); \fB(2)\fP Advances the iterator by calling sbuf_->sbumpc() where sbuf_ is the stored pointer to the stream buffer. @@ -14,12 +17,12 @@ .SH Return value - 1) *this. - 2) An unspecified struct proxy holding the current character obtained via - operator*() for later retrieval. proxy is implicitly convertible to CharT. - proxy also holds the value of sbuf_. istreambuf_iterator can be constructed from - proxy. + 1) *this + 2) A proxy object holding the current character obtained via operator*() and the + sbuf_ pointer. Dereferencing a proxy object with operator* yields the stored + character. + The name proxy is for exposition only. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. diff --git a/man/std::istringstream.3 b/man/std::istringstream.3 deleted file mode 120000 index 62dbcf204..000000000 --- a/man/std::istringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream.3 \ No newline at end of file diff --git a/man/std::istringstream.3 b/man/std::istringstream.3 new file mode 100644 index 000000000..ec453448b --- /dev/null +++ b/man/std::istringstream.3 @@ -0,0 +1,291 @@ +.TH std::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream \- std::basic_istringstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + + > class basic_istringstream : public basic_istream; + + The class template std::basic_istringstream implements input operations on string + based streams. It effectively stores an instance of std::basic_string and performs + input operations on it. + + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_istream. The + complete interface to unique std::basic_stringbuf members is provided. + + std-basic istringstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::istringstream std::basic_istringstream + std::wistringstream std::basic_istringstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) + +.SH Member functions + + constructor constructs the string stream + \fI(public member function)\fP + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP +.SH String operations + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_istringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::istringstream::basic_istringstream.3 b/man/std::istringstream::basic_istringstream.3 deleted file mode 120000 index 177d568db..000000000 --- a/man/std::istringstream::basic_istringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::basic_istringstream.3 \ No newline at end of file diff --git a/man/std::istringstream::basic_istringstream.3 b/man/std::istringstream::basic_istringstream.3 new file mode 100644 index 000000000..f9d4b1964 --- /dev/null +++ b/man/std::istringstream::basic_istringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_istringstream::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::basic_istringstream \- std::basic_istringstream::basic_istringstream + +.SH Synopsis + explicit basic_istringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::in ); + explicit basic_istringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_istringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_istringstream(std::ios_base::in) {} + explicit basic_istringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + explicit basic_istringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + basic_istringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_istringstream(str, std::ios_base::in, a) {} + template< class SAlloc > + + explicit basic_istringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + explicit basic_istringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + basic_istringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_istringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_istringstream( basic_istringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_istream, and + * buf_type as std::basic_stringbuf, + + the std::basic_istream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_istream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::in) + \fB(2)\fP buf_type(std::ios_base::in) + \fB(3)\fP buf_type(str, mode | + std::ios_base::in) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::in) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::in, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::in, a) + \fB(7)\fP buf_type(str, std::ios_base::in, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::in) + \fB(9)\fP {t, mode | std::ios_base::in, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::in, a} + \fB(11)\fP {t, std::ios_base::in, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_istream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_istringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::istringstream::istringstream.3 b/man/std::istringstream::istringstream.3 deleted file mode 120000 index 177d568db..000000000 --- a/man/std::istringstream::istringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::basic_istringstream.3 \ No newline at end of file diff --git a/man/std::istringstream::istringstream.3 b/man/std::istringstream::istringstream.3 new file mode 100644 index 000000000..f9d4b1964 --- /dev/null +++ b/man/std::istringstream::istringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_istringstream::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::basic_istringstream \- std::basic_istringstream::basic_istringstream + +.SH Synopsis + explicit basic_istringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::in ); + explicit basic_istringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_istringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_istringstream(std::ios_base::in) {} + explicit basic_istringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + explicit basic_istringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + basic_istringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_istringstream(str, std::ios_base::in, a) {} + template< class SAlloc > + + explicit basic_istringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + explicit basic_istringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + basic_istringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_istringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_istringstream( basic_istringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_istream, and + * buf_type as std::basic_stringbuf, + + the std::basic_istream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_istream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::in) + \fB(2)\fP buf_type(std::ios_base::in) + \fB(3)\fP buf_type(str, mode | + std::ios_base::in) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::in) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::in, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::in, a) + \fB(7)\fP buf_type(str, std::ios_base::in, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::in) + \fB(9)\fP {t, mode | std::ios_base::in, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::in, a} + \fB(11)\fP {t, std::ios_base::in, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_istream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_istringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::istringstream::operator=.3 b/man/std::istringstream::operator=.3 deleted file mode 120000 index 9efda0c42..000000000 --- a/man/std::istringstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::operator=.3 \ No newline at end of file diff --git a/man/std::istringstream::operator=.3 b/man/std::istringstream::operator=.3 new file mode 100644 index 000000000..dcd3081c3 --- /dev/null +++ b/man/std::istringstream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_istringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::operator= \- std::basic_istringstream::operator= + +.SH Synopsis + basic_istringstream& operator=( basic_istringstream&& other ); \fI(since C++11)\fP + + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_istream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. + +.SH Parameters + + other - string stream to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::istringstream::rdbuf.3 b/man/std::istringstream::rdbuf.3 deleted file mode 120000 index a05793396..000000000 --- a/man/std::istringstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::istringstream::rdbuf.3 b/man/std::istringstream::rdbuf.3 new file mode 100644 index 000000000..2718198e0 --- /dev/null +++ b/man/std::istringstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_istringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::rdbuf \- std::basic_istringstream::rdbuf + +.SH Synopsis + std::basic_stringbuf* rdbuf() const; + + Returns pointer to the underlying raw string device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw string device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::istringstream::str.3 b/man/std::istringstream::str.3 deleted file mode 120000 index eda984c76..000000000 --- a/man/std::istringstream::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::str.3 \ No newline at end of file diff --git a/man/std::istringstream::str.3 b/man/std::istringstream::str.3 new file mode 100644 index 000000000..3c092e8bd --- /dev/null +++ b/man/std::istringstream::str.3 @@ -0,0 +1,99 @@ +.TH std::basic_istringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::str \- std::basic_istringstream::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Manages the contents of the underlying string object. + + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. + +.SH Parameters + + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string + +.SH Return value + + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP + +.SH Notes + + The copy of the underlying string returned by str is a temporary object that will be + destructed at the end of the expression, so directly calling c_str() on the result + of str() (for example in auto *ptr = out.str().c_str();) results in a dangling + pointer. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.str("1 2"); + in >> n; + std::cout << "After reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.str() << "\\"\\n"; + + std::ostringstream out("1 2"); + out << 3; + std::cout << "After writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); + ate << 3; + std::cout << "After writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" + +.SH See also + + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::istringstream::swap.3 b/man/std::istringstream::swap.3 deleted file mode 120000 index 50cec1adf..000000000 --- a/man/std::istringstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::swap.3 \ No newline at end of file diff --git a/man/std::istringstream::swap.3 b/man/std::istringstream::swap.3 new file mode 100644 index 000000000..c7cccfc1e --- /dev/null +++ b/man/std::istringstream::swap.3 @@ -0,0 +1,39 @@ +.TH std::basic_istringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::swap \- std::basic_istringstream::swap + +.SH Synopsis + void swap( basic_istringstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_istream::swap(other) and + rdbuf()->swap(*other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::istringstream::view.3 b/man/std::istringstream::view.3 new file mode 100644 index 000000000..06eecf651 --- /dev/null +++ b/man/std::istringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_istringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::view \- std::basic_istringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::istrstream.3 b/man/std::istrstream.3 index 688c7bff6..11a0593c2 100644 --- a/man/std::istrstream.3 +++ b/man/std::istrstream.3 @@ -1,7 +1,11 @@ -.TH std::istrstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istrstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istrstream \- std::istrstream + .SH Synopsis Defined in header - class istrstream : public std::istream \fB(deprecated)\fP + class istrstream : public std::istream (deprecated in C++98) + (removed in C++26) The class istrstream implements input operations on array-backed streams. It essentially wraps a raw array I/O device implementation (std::strstreambuf) into the @@ -12,19 +16,21 @@ .SH Notes - istrstream has been deprecated since C++98, std::istringstream and - boost::iostreams::array_source are the recommended replacements. + istrstream has been deprecated since C++98 and removed since C++26. + std::istringstream + , std::ispanstream + (since C++23), and boost::iostreams::array_source are the recommended replacements. .SH Member functions - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function)\fP - destructor destructs a strstream, optionally deallocating the buffer - \fB[virtual]\fP \fI(virtual public member function)\fP + constructor constructs an istrstream object, optionally allocating the buffer + \fI(public member function)\fP + destructor destructs an istrstream object, optionally deallocating the buffer + \fB[virtual]\fP \fI(virtual public member function)\fP rdbuf obtains a pointer to the associated strstreambuf - \fI(public member function)\fP + \fI(public member function)\fP str accesses the output buffer - \fI(public member function)\fP + \fI(public member function)\fP Inherited from std::basic_istream @@ -32,40 +38,40 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ios @@ -78,45 +84,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -124,40 +130,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -165,76 +171,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::istrstream::istrstream.3 b/man/std::istrstream::istrstream.3 index c88f7f5b8..40390e496 100644 --- a/man/std::istrstream::istrstream.3 +++ b/man/std::istrstream::istrstream.3 @@ -1,16 +1,23 @@ -.TH std::istrstream::istrstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - explicit istrstream(const char* s); \fB(1)\fP - explicit istrstream(char* s); \fB(2)\fP - istrstream(const char* s, std::streamsize n); \fB(3)\fP - istrstream(char* s, std::streamsize n); \fB(4)\fP - - Constructs new istrstream and its underlying std::strstreambuf. +.TH std::istrstream::istrstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istrstream::istrstream \- std::istrstream::istrstream - 1,2) Constructs the underlying std::strstreambuf by calling strstreambuf(s,0) and +.SH Synopsis + explicit istrstream( const char* s ); \fB(1)\fP (deprecated in C++98) + (removed in C++26) + explicit istrstream( char* s ); \fB(2)\fP (deprecated in C++98) + (removed in C++26) + istrstream( const char* s, std::streamsize n ); \fB(3)\fP (deprecated in C++98) + (removed in C++26) + istrstream( char* s, std::streamsize n ); \fB(4)\fP (deprecated in C++98) + (removed in C++26) + + Constructs new std::istrstream and its underlying std::strstreambuf. + + 1,2) Constructs the underlying std::strstreambuf by calling strstreambuf(s, 0) and initializes the base class with the address of the strstreambuf. The behavior is undefined if s is not pointing at an element of a null-terminated array. - 3,4) Constructs the underlying std::strstreambuf by calling strstreambuf(s,n) and + 3,4) Constructs the underlying std::strstreambuf by calling strstreambuf(s, n) and initializes the base class with the address of the strstreambuf. The behavior is undefined if s is not pointing at an element of an array whose length is at least n elements. @@ -22,22 +29,22 @@ .SH Example - + // Run this code #include #include - + int main() { std::istrstream s1("1 2 3"); // string literal - int n1,n2,n3; - if(s1 >> n1 >> n2 >> n3) + int n1, n2, n3; + if (s1 >> n1 >> n2 >> n3) std::cout << n1 << ", " << n2 << ", " << n3 << '\\n'; - + char arr[] = {'4', ' ', '5', ' ', '6'}; std::istrstream s2(arr, sizeof arr); - if(s2 >> n1 >> n2 >> n3) + if (s2 >> n1 >> n2 >> n3) std::cout << n1 << ", " << n2 << ", " << n3 << '\\n'; } @@ -49,8 +56,8 @@ .SH See also constructor constructs a strstreambuf object - \fI(public member function of std::strstreambuf)\fP - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function of std::ostrstream)\fP - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function of std::strstream)\fP + \fI(public member function of std::strstreambuf)\fP + constructor constructs an ostrstream object, optionally allocating the buffer + \fI(public member function of std::ostrstream)\fP + constructor constructs a strstream object, optionally allocating the buffer + \fI(public member function of std::strstream)\fP diff --git a/man/std::istrstream::rdbuf.3 b/man/std::istrstream::rdbuf.3 index a70a2120b..7694cda27 100644 --- a/man/std::istrstream::rdbuf.3 +++ b/man/std::istrstream::rdbuf.3 @@ -1,9 +1,13 @@ -.TH std::istrstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istrstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istrstream::rdbuf \- std::istrstream::rdbuf + .SH Synopsis - strstreambuf* rdbuf() const; + strstreambuf* rdbuf() const; (deprecated in C++98) + (removed in C++26) Returns a pointer to the associated std::strstreambuf, casting away its constness - (despite the const qualifier on the member function) + (despite the const qualifier on the member function). .SH Parameters @@ -11,16 +15,17 @@ .SH Return value - Pointer to the associated std::strsteambuf, with constness cast away. + Pointer to the associated std::strstreambuf, with constness cast away. .SH Example - + // Run this code #include + int main() { - const std::istrstream buf("example"); + const std::istrstream buf("example"); std::strstreambuf* ptr = buf.rdbuf(); } diff --git a/man/std::istrstream::str.3 b/man/std::istrstream::str.3 index 7e400df59..8d42b1004 100644 --- a/man/std::istrstream::str.3 +++ b/man/std::istrstream::str.3 @@ -1,9 +1,13 @@ -.TH std::istrstream::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istrstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istrstream::str \- std::istrstream::str + .SH Synopsis - char* str(); + char* str(); (deprecated in C++98) + (removed in C++26) Returns the pointer to the beginning of the buffer, after freezing it. Effectively - calls rdbuf()->str() + calls rdbuf()->str(). .SH Parameters @@ -11,8 +15,8 @@ .SH Return value - Pointer to the beginning of the buffer in the associated std::strsteambuf or NULL if - no buffer is available. + Pointer to the beginning of the buffer in the associated std::strstreambuf or a null + pointer if no buffer is available. .SH Example @@ -20,5 +24,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::istrstream::~istrstream.3 b/man/std::istrstream::~istrstream.3 index 6105ca3fd..dea82670a 100644 --- a/man/std::istrstream::~istrstream.3 +++ b/man/std::istrstream::~istrstream.3 @@ -1,6 +1,10 @@ -.TH std::istrstream::~istrstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::istrstream::~istrstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::istrstream::~istrstream \- std::istrstream::~istrstream + .SH Synopsis - virtual ~istrstream(); + virtual ~istrstream(); (deprecated in C++98) + (removed in C++26) Destroys a std::istrstream object, which also destroys the member std::strstreambuf. @@ -16,12 +20,12 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { { diff --git a/man/std::isunordered.3 b/man/std::isunordered.3 index 09bbe9c8e..e15c002a0 100644 --- a/man/std::isunordered.3 +++ b/man/std::isunordered.3 @@ -1,25 +1,103 @@ -.TH std::isunordered 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isunordered 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isunordered \- std::isunordered + .SH Synopsis Defined in header - bool isunordered( float x, float y ); \fI(since C++11)\fP - bool isunordered( double x, double y ); \fI(since C++11)\fP - bool isunordered( long double x, long double y ); \fI(since C++11)\fP + bool isunordered( float x, float y ); + \fI(since C++11)\fP + bool isunordered( double x, double y ); (until C++23) + + bool isunordered( long double x, long double y ); + constexpr bool isunordered( /* floating-point-type + */ x, \fB(1)\fP (since C++23) + /* floating-point-type + */ y ); + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > (A) \fI(since C++11)\fP + bool isunordered( Arithmetic1 x, Arithmetic2 y ); (constexpr since C++23) - Determines if the floating point numbers x and y are unordered, that is, one or both - are NaN and thus cannot be meaningfully compared with each other. + 1) Determines if the floating point numbers x and y are unordered, that is, one or + both are NaN and thus cannot be meaningfully compared with each other. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. .SH Parameters - x - floating point value - y - floating point value + x, y - floating-point or integer values .SH Return value - true if either x or y is NaN, false otherwise + true if either x or y is NaN, false otherwise. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::isunordered(num1, + num2) has the same effect as std::isunordered(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::isunordered(num1, num2) has the same effect as (until C++23) + std::isunordered(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::isunordered(num1, num2) has the same effect as + std::isunordered(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::isunordered(num1, + num2) has the same effect as std::isunordered(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + + #define SHOW_UNORDERED(x, y) \\ + std::cout << std::boolalpha << "isunordered(" \\ + << #x << ", " << #y << "): " \\ + << std::isunordered(x, y) << '\\n' + + int main() + { + SHOW_UNORDERED(10, 01); + SHOW_UNORDERED(INFINITY, NAN); + SHOW_UNORDERED(INFINITY, INFINITY); + SHOW_UNORDERED(NAN, NAN); + } + +.SH Output: + + isunordered(10, 01): false + isunordered(INFINITY, NAN): true + isunordered(INFINITY, INFINITY): false + isunordered(NAN, NAN): true .SH See also - fpclassify categorizes the given floating point value - \fI(C++11)\fP \fI(function)\fP + fpclassify categorizes the given floating-point value + \fI(C++11)\fP \fI(function)\fP isnan checks if the given number is NaN - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + isunordered diff --git a/man/std::isupper(std::locale).3 b/man/std::isupper(std::locale).3 index 15db1212f..53385d388 100644 --- a/man/std::isupper(std::locale).3 +++ b/man/std::isupper(std::locale).3 @@ -1,11 +1,14 @@ -.TH std::isupper(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isupper(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isupper(std::locale) \- std::isupper(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isupper( charT ch, const locale& loc ); + template< class CharT > + bool isupper( CharT ch, const locale& loc ); - Checks if the given character classified as an uppercase alphabetic character by the - given locale's std::ctype facet. + Checks if the given character is classified as an uppercase alphabetic character by + the given locale's std::ctype facet. .SH Parameters @@ -18,41 +21,48 @@ .SH Possible implementation - template< class charT > - bool isupper( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::upper, ch); + template + bool isupper(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::upper, ch); } .SH Example - Demonstrates the use of isupper() with different locales (OS-specific). + Demonstrates the use of std::isupper() with different locales (OS-specific). + - // Run this code #include #include + int main() { - const wchar_t c = L'\\u00de'; // capital letter thorn - + const wchar_t c = L'\\u00de'; // LATIN CAPITAL LETTER THORN + std::locale loc1("C"); - std::cout << "isupper('Þ', C locale) returned " - << std::boolalpha << std::isupper(c, loc1) << '\\n'; - + std::cout << std::boolalpha + << "isupper('Þ', C locale) returned " << std::isupper(c, loc1) << '\\n' + << "islower('Þ', C locale) returned " << std::islower(c, loc1) << '\\n'; + std::locale loc2("en_US.UTF8"); std::cout << "isupper('Þ', Unicode locale) returned " - << std::boolalpha << std::isupper(c, loc2) << '\\n'; + << std::isupper(c, loc2) << '\\n' + << "islower('Þ', Unicode locale) returned " + << std::islower(c, loc2) << '\\n'; } -.SH Output: +.SH Possible output: isupper('Þ', C locale) returned false + islower('Þ', C locale) returned false isupper('Þ', Unicode locale) returned true + islower('Þ', Unicode locale) returned false .SH See also isupper checks if a character is an uppercase character - \fI(function)\fP + \fI(function)\fP iswupper checks if a wide character is an uppercase character - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::isupper.3 b/man/std::isupper.3 index 960076b35..b4807235d 100644 --- a/man/std::isupper.3 +++ b/man/std::isupper.3 @@ -1,14 +1,18 @@ -.TH std::isupper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isupper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isupper \- std::isupper + .SH Synopsis Defined in header int isupper( int ch ); Checks if the given character is an uppercase character as classified by the - currently installed C locale. In the default "C" locale, isupper returns true only - for the uppercase letters (ABCDEFGHIJKLMNOPQRSTUVWXYZ). + currently installed C locale. In the default "C" locale, std::isupper returns a + nonzero value only for the uppercase letters (ABCDEFGHIJKLMNOPQRSTUVWXYZ). - If isupper returns true, it is guaranteed that iscntrl, isdigit, ispunct, and - isspace return false for the same character in the same C locale. + If std::isupper returns a nonzero value, it is guaranteed that std::iscntrl, + std::isdigit, std::ispunct, and std::isspace return zero for the same character in + the same C locale. The behavior is undefined if the value of ch is not representable as unsigned char and is not equal to EOF. @@ -19,31 +23,57 @@ .SH Return value - Non-zero value (true) if the character is an uppercase letter, 0 (false) otherwise. + Non-zero value if the character is an uppercase letter, zero otherwise. + +.SH Notes + + Like all other functions from , the behavior of std::isupper is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + bool my_isupper(char ch) + { + return std::isupper(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_uppers(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isupper) // wrong + // [](int c){ return std::isupper(c); } // wrong + // [](char c){ return std::isupper(c); } // wrong + [](unsigned char c){ return std::isupper(c); } // correct + ); + } .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xc6'; // letter Æ in ISO-8859-1 - + std::cout << "isupper(\\'\\\\xc6\\', default C locale) returned " - << std::boolalpha << (bool)std::isupper(c) << '\\n'; - + << std::boolalpha << (bool)std::isupper(c) << '\\n'; + std::setlocale(LC_ALL, "en_GB.iso88591"); std::cout << "isupper(\\'\\\\xc6\\', ISO-8859-1 locale) returned " << std::boolalpha << (bool)std::isupper(c) << '\\n'; - + } -.SH Output: +.SH Possible output: isupper('\\xc6', default C locale) returned false isupper('\\xc6', ISO-8859-1 locale) returned true @@ -51,29 +81,32 @@ .SH See also isupper(std::locale) checks if a character is classified as uppercase by a locale - \fI(function template)\fP + \fI(function template)\fP iswupper checks if a wide character is an uppercase character - \fI(function)\fP + \fI(function)\fP C documentation for isupper - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswalnum.3 b/man/std::iswalnum.3 index 3aff3e5b8..59c71e32f 100644 --- a/man/std::iswalnum.3 +++ b/man/std::iswalnum.3 @@ -1,4 +1,7 @@ -.TH std::iswalnum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswalnum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswalnum \- std::iswalnum + .SH Synopsis Defined in header int iswalnum( std::wint_t ch ); @@ -8,37 +11,45 @@ letter (abcdefghijklmnopqrstuvwxyz) or any alphanumeric character specific to the current locale. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is a alphanumeric character, 0 (false) - otherwise. + Non-zero value if the wide character is an alphanumeric character, zero otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are included in the POSIX alnum + category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u13ad'; // the Cherokee letter HA ('Ꭽ') - + std::cout << std::hex << std::showbase << std::boolalpha; std::cout << "in the default locale, iswalnum(" << (std::wint_t)c << ") = " << (bool)std::iswalnum(c) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); std::cout << "in Unicode locale, iswalnum(" << (std::wint_t)c << ") = " << (bool)std::iswalnum(c) << '\\n'; } -.SH Output: +.SH Possible output: in the default locale, iswalnum(0x13ad) = false in Unicode locale, iswalnum(0x13ad) = true @@ -46,29 +57,32 @@ .SH See also isalnum(std::locale) checks if a character is classified as alphanumeric by a locale - \fI(function template)\fP + \fI(function template)\fP isalnum checks if a character is alphanumeric - \fI(function)\fP + \fI(function)\fP C documentation for iswalnum - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswalpha.3 b/man/std::iswalpha.3 index 1e9e69137..b750d7c6d 100644 --- a/man/std::iswalpha.3 +++ b/man/std::iswalpha.3 @@ -1,4 +1,7 @@ -.TH std::iswalpha 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswalpha 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswalpha \- std::iswalpha + .SH Synopsis Defined in header int iswalpha( std::wint_t ch ); @@ -8,36 +11,44 @@ (abcdefghijklmnopqrstuvwxyz) or any alphabetic character specific to the current locale. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value if the wide character is a alphabetic character, 0 otherwise. + Non-zero value if the wide character is an alphabetic character, 0 otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are include in POSIX alpha category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u0b83'; // Tamil sign Visarga ('ஃ') - + std::cout << std::hex << std::showbase << std::boolalpha; std::cout << "in the default locale, iswalpha(" << (std::wint_t)c << ") = " << (bool)std::iswalpha(c) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); std::cout << "in Unicode locale, iswalpha(" << (std::wint_t)c << ") = " << (bool)std::iswalpha(c) << '\\n'; } -.SH Output: +.SH Possible output: in the default locale, iswalpha(0xb83) = false in Unicode locale, iswalpha(0xb83) = true @@ -45,29 +56,32 @@ .SH See also isalpha(std::locale) checks if a character is classified as alphabetic by a locale - \fI(function template)\fP + \fI(function template)\fP isalpha checks if a character is alphabetic - \fI(function)\fP + \fI(function)\fP C documentation for iswalpha - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswblank.3 b/man/std::iswblank.3 index 50753bd23..6ba564ef4 100644 --- a/man/std::iswblank.3 +++ b/man/std::iswblank.3 @@ -1,4 +1,7 @@ -.TH std::iswblank 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswblank 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswblank \- std::iswblank + .SH Synopsis Defined in header int iswblank( std::wint_t ch ); \fI(since C++11)\fP @@ -8,28 +11,35 @@ In the default C locale, only space (0x20) and horizontal tab (0x09) are blank characters. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is a blank character, 0 (false) - otherwise. + Non-zero value if the wide character is a blank character, zero otherwise. + +.SH Notes + + ISO 30112 defines POSIX blank characters as Unicode characters U+0009, U+0020, + U+1680, U+180E, U+2000..U+2006, U+2008, U+200A, U+205F, and U+3000. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u3000'; // Ideographic space ('　') - + std::cout << std::hex << std::showbase << std::boolalpha; std::cout << "in the default locale, iswblank(" << (std::wint_t)c << ") = " << (bool)std::iswblank(c) << '\\n'; @@ -47,29 +57,32 @@ isblank(std::locale) checks if a character is classified as a blank character by a \fI(C++11)\fP locale - \fI(function template)\fP + \fI(function template)\fP isblank checks if a character is a blank character - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP C documentation for iswblank - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswcntrl.3 b/man/std::iswcntrl.3 index bcacd417a..9d01b4803 100644 --- a/man/std::iswcntrl.3 +++ b/man/std::iswcntrl.3 @@ -1,4 +1,7 @@ -.TH std::iswcntrl 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswcntrl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswcntrl \- std::iswcntrl + .SH Synopsis Defined in header int iswcntrl( std::wint_t ch ); @@ -6,28 +9,35 @@ Checks if the given wide character is a control character, i.e. codes 0x00-0x1F and 0x7F and any control characters specific to the current locale. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is a control character, 0 (false) - otherwise. + Non-zero value if the wide character is a control character, zero otherwise. + +.SH Notes + + ISO 30112 defines POSIX control characters as Unicode characters U+0000..U+001F, + U+007F..U+009F, U+2028, and U+2029 (Unicode classes Cc, Zl, and Zp). .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u2028'; // the Unicode character "line separator" - + std::cout << std::hex << std::showbase << std::boolalpha; std::cout << "in the default locale, iswcntrl(" << (std::wint_t)c << ") = " << (bool)std::iswcntrl(c) << '\\n'; @@ -45,29 +55,32 @@ checks if a character is classified as a control character by a iscntrl(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP iscntrl checks if a character is a control character - \fI(function)\fP + \fI(function)\fP C documentation for iswcntrl - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswctype.3 b/man/std::iswctype.3 index 78cf09c5a..3d0e9414b 100644 --- a/man/std::iswctype.3 +++ b/man/std::iswctype.3 @@ -1,38 +1,46 @@ -.TH std::iswctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswctype 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswctype \- std::iswctype + .SH Synopsis Defined in header - int iswctype( std::wint_t ch, std::wctype_t desc ); + int iswctype( std::wint_t wc, std::wctype_t desc ); Classifies the wide character wc using the current C locale's LC_CTYPE category identified by desc. + If the value of wc is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters - ch - the wide character to classify + wc - the wide character to classify desc - the LC_CTYPE category, obtained from a call to std::wctype .SH Return value - Non-zero if the character ch has the property identified by desc in LC_CTYPE facet - of the current C locale. + Non-zero if the character wc has the property identified by desc in LC_CTYPE facet + of the current C locale, zero otherwise. .SH Example - + // Run this code #include #include #include - bool classify(wchar_t ch, const std::string& cat) + + bool classify(wchar_t wc, const std::string& cat) { - return std::iswctype(ch, std::wctype(cat.c_str())); + return std::iswctype(wc, std::wctype(cat.c_str())); } + int main() { std::setlocale(LC_ALL, "ja_JP.UTF-8"); std::cout << "The character \\u6c34 is...\\n"; - for(std::string s : {"digit", "alpha", "space", "cntrl", "jkanji"}) + for (std::string s : {"digit", "alpha", "space", "cntrl", "jkanji"}) std::cout << s << "? " << std::boolalpha << classify(L'\\u6c34', s) << '\\n'; } @@ -48,4 +56,6 @@ .SH See also wctype looks up a character classification category in the current C locale - \fI(function)\fP + \fI(function)\fP + C documentation for + iswctype diff --git a/man/std::iswdigit.3 b/man/std::iswdigit.3 index d8824061a..5072b8ac1 100644 --- a/man/std::iswdigit.3 +++ b/man/std::iswdigit.3 @@ -1,4 +1,7 @@ -.TH std::iswdigit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswdigit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswdigit \- std::iswdigit + .SH Synopsis Defined in header int iswdigit( wint_t ch ); @@ -6,96 +9,103 @@ Checks if the given wide character corresponds (if narrowed) to one of the ten decimal digit characters 0123456789. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is an numeric character, 0 (false) - otherwise. + Non-zero value if the wide character is a numeric character, zero otherwise. .SH Notes - iswdigit and iswxdigit are the only standard wide character classification functions - that are not affected by the currently installed C locale. + std::iswdigit and std::iswxdigit are the only standard wide character classification + functions that are not affected by the currently installed C locale. .SH Example Some locales offer additional character classes that detect non-ASCII digits - + // Run this code - #include - #include #include + #include + #include + void test(wchar_t a3, wchar_t u3, wchar_t j3) { std::wcout << std::boolalpha - << " '" << a3 << "' '" << u3 << "' '" << j3 << "'\\n" - << "iswdigit " + << "\\t '" << a3 << "' '" << u3 << "' '" << j3 << "'\\n" + << "iswdigit: " << (bool)std::iswdigit(a3) << " " << (bool)std::iswdigit(u3) << " " << (bool)std::iswdigit(j3) << '\\n' - << "jdigit: " + << "jdigit: " << (bool)std::iswctype(a3, std::wctype("jdigit")) << ' ' << (bool)std::iswctype(u3, std::wctype("jdigit")) << ' ' << (bool)std::iswctype(j3, std::wctype("jdigit")) << '\\n'; } + int main() { wchar_t a3 = L'3'; // the ASCII digit 3 wchar_t u3 = L'三'; // the CJK numeral 3 - wchar_t j3 = L'３'; // the fullwidth digit 3 - + wchar_t j3 = L'３'; // the full-width digit 3 + std::setlocale(LC_ALL, "en_US.utf8"); - std::wcout << "In american locale:\\n"; + std::wcout << "In American locale:\\n"; test(a3, u3, j3); - - std::wcout << "\\nIn japanese locale:\\n"; + + std::wcout << "\\nIn Japanese locale:\\n"; std::setlocale(LC_ALL, "ja_JP.utf8"); test(a3, u3, j3); } -.SH Output: +.SH Possible output: + + In American locale: + '3' '三' '３' + iswdigit: true false false + jdigit: false false false - In american locale: - '3' '三' '３' - iswdigit true false false - jdigit: false false false - - In japanese locale: - '3' '三' '３' - iswdigit true false false - jdigit: false false true + In Japanese locale: + '3' '三' '３' + iswdigit: true false false + jdigit: false false true .SH See also isdigit(std::locale) checks if a character is classified as a digit by a locale - \fI(function template)\fP + \fI(function template)\fP isdigit checks if a character is a digit - \fI(function)\fP + \fI(function)\fP C documentation for iswdigit - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswgraph.3 b/man/std::iswgraph.3 index 06caa16a9..552567933 100644 --- a/man/std::iswgraph.3 +++ b/man/std::iswgraph.3 @@ -1,13 +1,19 @@ -.TH std::iswgraph 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswgraph 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswgraph \- std::iswgraph + .SH Synopsis Defined in header int iswgraph( std::wint_t ch ); Checks if the given wide character has a graphical representation, i.e. it is either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase - letter (abcdefghijklmnopqrstuvwxyz), a punctuation - character(!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~) or any graphical character specific to - the current C locale. + letter (abcdefghijklmnopqrstuvwxyz), a punctuation character + (!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~) or any graphical character specific to the + current C locale. + + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. .SH Parameters @@ -15,28 +21,35 @@ .SH Return value - Non-zero value (true) if the wide character has a graphical representation - character, 0 (false) otherwise. + Non-zero value if the wide character has a graphical representation character, zero + otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are include in POSIX graph category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u2602'; // the Unicode character Umbrella ('☂') - - std::cout << std::hex << std::showbase << std::boolalpha; - std::cout << "in the default locale, iswgraph(" << (std::wint_t)c << ") = " - << (bool)std::iswgraph(c) << '\\n'; + + std::cout << std::hex << std::showbase << std::boolalpha + << "in the default locale, iswgraph(" + << static_cast(c) << ") = " + << static_cast(std::iswgraph(c)) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << "in Unicode locale, iswgraph(" << (std::wint_t)c << ") = " - << (bool)std::iswgraph(c) << '\\n'; + std::cout << "in Unicode locale, iswgraph(" + << static_cast(c) << ") = " + << static_cast(std::iswgraph(c)) << '\\n'; } .SH Output: @@ -46,30 +59,33 @@ .SH See also - isgraph(std::locale) checks if a character is classfied as graphical by a locale - \fI(function template)\fP + isgraph(std::locale) checks if a character is classified as graphical by a locale + \fI(function template)\fP isgraph checks if a character is a graphical character - \fI(function)\fP + \fI(function)\fP C documentation for iswgraph - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswlower.3 b/man/std::iswlower.3 index 70b51f94f..ba3dbdddb 100644 --- a/man/std::iswlower.3 +++ b/man/std::iswlower.3 @@ -1,4 +1,7 @@ -.TH std::iswlower 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswlower 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswlower \- std::iswlower + .SH Synopsis Defined in header int iswlower( std::wint_t ch ); @@ -6,34 +9,43 @@ Checks if the given wide character is a lowercase letter, i.e. one of abcdefghijklmnopqrstuvwxyz or any lowercase letter specific to the current locale. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is an lowercase letter, 0 (false) - otherwise. + Non-zero value if the wide character is a lowercase letter, zero otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are include in POSIX lower category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u0444'; // Cyrillic small letter ef ('ф') - - std::cout << std::hex << std::showbase << std::boolalpha; - std::cout << "in the default locale, iswlower(" << (std::wint_t)c << ") = " - << (bool)std::iswlower(c) << '\\n'; + + std::cout << std::hex << std::showbase << std::boolalpha + << "in the default locale, iswlower(" + << static_cast(c) << ") = " + << static_cast(std::iswlower(c)) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << "in Unicode locale, iswlower(" << (std::wint_t)c << ") = " - << (bool)std::iswlower(c) << '\\n'; + std::cout << "in Unicode locale, iswlower(" + << static_cast(c) << ") = " + << static_cast(std::iswlower(c)) << '\\n'; } .SH Output: @@ -44,29 +56,32 @@ .SH See also islower(std::locale) checks if a character is classified as lowercase by a locale - \fI(function template)\fP + \fI(function template)\fP islower checks if a character is lowercase - \fI(function)\fP + \fI(function)\fP C documentation for iswlower - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswprint.3 b/man/std::iswprint.3 index 303e99a3f..625192ae4 100644 --- a/man/std::iswprint.3 +++ b/man/std::iswprint.3 @@ -1,13 +1,19 @@ -.TH std::iswprint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswprint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswprint \- std::iswprint + .SH Synopsis Defined in header int iswprint( std::wint_t ch ); Checks if the given wide character can be printed, i.e. it is either a number (0123456789), an uppercase letter (ABCDEFGHIJKLMNOPQRSTUVWXYZ), a lowercase letter - (abcdefghijklmnopqrstuvwxyz), a punctuation - character(!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~), space or any printable character - specific to the current C locale. + (abcdefghijklmnopqrstuvwxyz), a punctuation character + (!"#$%&'()*+,-./:;<=>?@[\\]^_`{!}~), space or any printable character specific to the + current C locale. + + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. .SH Parameters @@ -15,63 +21,77 @@ .SH Return value - Non-zero value (true) if the wide character can be printed, 0 (false) otherwise. + Non-zero value if the wide character can be printed, zero otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are include in POSIX print category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + + void demo_iswprint(std::string_view rem, const std::wint_t c) + { + std::cout << std::boolalpha << std::hex << std::showbase + << rem << "iswprint('" << c << "') = " + << !!std::iswprint(c) << '\\n'; + } + int main() { - wchar_t c = L'\\u2002'; // en-space + const wchar_t c1 = L'\\u2002'; // en-space + const wchar_t c2 = L'\\u0082'; // break permitted + + demo_iswprint("In default locale:\\n", c1); + std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << std::boolalpha << std::hex << std::showbase - << "in Unicode locale,\\n" - << "iswprint('" << c << "') = " - << (bool)std::iswprint(c) << '\\n'; - - c = L'\\u0082'; // break permitted - std::cout << "iswprint('" << c << "') = " - << (bool)std::iswprint(c) << '\\n'; + demo_iswprint("In Unicode locale:\\n", c1); + demo_iswprint("", c2); } -.SH Output: +.SH Possible output: - in Unicode locale, + In default locale: + iswprint('0x2002') = false + In Unicode locale: iswprint('0x2002') = true iswprint('0x82') = false .SH See also isprint(std::locale) checks if a character is classified as printable by a locale - \fI(function template)\fP + \fI(function template)\fP isprint checks if a character is a printing character - \fI(function)\fP + \fI(function)\fP C documentation for iswprint - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswpunct.3 b/man/std::iswpunct.3 index 6226e3277..73ecbe81b 100644 --- a/man/std::iswpunct.3 +++ b/man/std::iswpunct.3 @@ -1,4 +1,7 @@ -.TH std::iswpunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswpunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswpunct \- std::iswpunct + .SH Synopsis Defined in header int iswpunct( std::wint_t ch ); @@ -7,34 +10,43 @@ !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ or any punctuation character specific to the current locale. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is a punctuation character, 0 (false) - otherwise. + Non-zero value if the wide character is a punctuation character, zero otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are include in POSIX punct category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u2051'; // Two asterisks ('⁑') - - std::cout << std::hex << std::showbase << std::boolalpha; - std::cout << "in the default locale, iswpunct(" << (std::wint_t)c << ") = " - << (bool)std::iswpunct(c) << '\\n'; + + std::cout << std::hex << std::showbase << std::boolalpha + << "in the default locale, iswpunct(" + << static_cast(c) << ") = " + << static_cast(std::iswpunct(c)) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << "in Unicode locale, iswpunct(" << (std::wint_t)c << ") = " - << (bool)std::iswpunct(c) << '\\n'; + std::cout << "in Unicode locale, iswpunct(" + << static_cast(c) << ") = " + << static_cast(std::iswpunct(c)) << '\\n'; } .SH Output: @@ -45,29 +57,32 @@ .SH See also ispunct(std::locale) checks if a character is classified as punctuation by a locale - \fI(function template)\fP + \fI(function template)\fP ispunct checks if a character is a punctuation character - \fI(function)\fP + \fI(function)\fP C documentation for iswpunct - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswspace.3 b/man/std::iswspace.3 index 2b6a9c121..327a93b31 100644 --- a/man/std::iswspace.3 +++ b/man/std::iswspace.3 @@ -1,4 +1,7 @@ -.TH std::iswspace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswspace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswspace \- std::iswspace + .SH Synopsis Defined in header int iswspace( wint_t ch ); @@ -7,12 +10,15 @@ the currently installed C locale. In the default locale, the whitespace characters are the following: - * space (0x20, ' ') - * form feed (0x0c, '\\f') - * line feed (0x0a, '\\n') - * carriage return (0x0d, '\\r') - * horizontal tab (0x09, '\\t') - * vertical tab (0x0b, '\\v') + * Space (0x20, ' ') + * Form feed (0x0c, '\\f') + * Line feed (0x0a, '\\n') + * Carriage return (0x0d, '\\r') + * Horizontal tab (0x09, '\\t') + * Vertical tab (0x0b, '\\v'). + + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. .SH Parameters @@ -20,28 +26,35 @@ .SH Return value - Non-zero value (true) if the wide character is a whitespace character, 0 (false) - otherwise. + Non-zero value if the wide character is a whitespace character, zero otherwise. + +.SH Notes + + ISO 30112 defines POSIX space characters as Unicode characters U+0009..U+000D, + U+0020, U+1680, U+180E, U+2000..U+2006, U+2008..U+200A, U+2028, U+2029, U+205F, and + U+3000. .SH Example - Demonstrates the use of iswspace() with different locales + Demonstrates the use of iswspace with different locales. + - // Run this code - #include #include #include + #include + void try_with(wchar_t c, const char* loc) { std::setlocale(LC_ALL, loc); std::wcout << "isspace('" << c << "') in " << loc << " locale returned " - << std::boolalpha << (bool)std::iswspace(c) << '\\n'; + << std::boolalpha << static_cast(std::iswspace(c)) << '\\n'; } + int main() { - wchar_t EM_SPACE = L'\\u2003'; // Unicode character 'EM SPACE' + const wchar_t EM_SPACE = L'\\u2003'; // Unicode character 'EM SPACE' try_with(EM_SPACE, "C"); try_with(EM_SPACE, "en_US.UTF8"); } @@ -54,29 +67,32 @@ .SH See also isspace(std::locale) checks if a character is classified as whitespace by a locale - \fI(function template)\fP + \fI(function template)\fP isspace checks if a character is a space character - \fI(function)\fP + \fI(function)\fP C documentation for iswspace - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswupper.3 b/man/std::iswupper.3 index 79259f8c4..d3a17030b 100644 --- a/man/std::iswupper.3 +++ b/man/std::iswupper.3 @@ -1,4 +1,7 @@ -.TH std::iswupper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswupper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswupper \- std::iswupper + .SH Synopsis Defined in header int iswupper( std::wint_t ch ); @@ -6,34 +9,43 @@ Checks if the given wide character is an uppercase letter, i.e. one of ABCDEFGHIJKLMNOPQRSTUVWXYZ or any uppercase letter specific to the current locale. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is an uppercase letter, 0 (false) - otherwise. + Non-zero value if the wide character is an uppercase letter, zero otherwise. + +.SH Notes + + ISO 30112 specifies which Unicode characters are include in POSIX upper category. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { - wchar_t c = L'\\u053d'; // Armenian capital letter xeh ('Խ') - + const wchar_t c = L'\\u053d'; // Armenian capital letter xeh ('Խ') + std::cout << std::hex << std::showbase << std::boolalpha; - std::cout << "in the default locale, iswupper(" << (std::wint_t)c << ") = " - << (bool)std::iswupper(c) << '\\n'; + std::cout << "in the default locale, iswupper(" + << static_cast(c) << ") = " + << static_cast(std::iswupper(c)) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << "in Unicode locale, iswupper(" << (std::wint_t)c << ") = " - << (bool)std::iswupper(c) << '\\n'; + std::cout << "in Unicode locale, iswupper(" + << static_cast(c) << ") = " + << static_cast(std::iswupper(c)) << '\\n'; } .SH Output: @@ -44,29 +56,32 @@ .SH See also isupper(std::locale) checks if a character is classified as uppercase by a locale - \fI(function template)\fP + \fI(function template)\fP isupper checks if a character is an uppercase character - \fI(function)\fP + \fI(function)\fP C documentation for iswupper - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iswxdigit.3 b/man/std::iswxdigit.3 index 183649c3b..cd097a763 100644 --- a/man/std::iswxdigit.3 +++ b/man/std::iswxdigit.3 @@ -1,4 +1,7 @@ -.TH std::iswxdigit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iswxdigit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iswxdigit \- std::iswxdigit + .SH Synopsis Defined in header int iswxdigit( wint_t ch ); @@ -6,47 +9,72 @@ Checks if the given wide character corresponds (if narrowed) to a hexadecimal numeric character, i.e. one of 0123456789abcdefABCDEF. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character .SH Return value - Non-zero value (true) if the wide character is a hexadecimal numeric character, 0 - (false) otherwise. + Non-zero value if the wide character is a hexadecimal numeric character, zero + otherwise. .SH Notes - iswdigit and iswxdigit are the only standard wide character classification functions - that are not affected by the currently installed C locale. + std::iswdigit and std::iswxdigit are the only standard wide character classification + functions that are not affected by the currently installed C locale. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha + << (std::iswxdigit(L'a') != 0) << ' ' + << (std::iswxdigit(L'ä') != 0) << '\\n'; + } + +.SH Output: + + true false .SH See also checks if a character is classified as a hexadecimal digit by isxdigit(std::locale) a locale - \fI(function template)\fP + \fI(function template)\fP isxdigit checks if a character is a hexadecimal character - \fI(function)\fP + \fI(function)\fP C documentation for iswxdigit - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::isxdigit(std::locale).3 b/man/std::isxdigit(std::locale).3 index 89bbfbffc..f36ecb64b 100644 --- a/man/std::isxdigit(std::locale).3 +++ b/man/std::isxdigit(std::locale).3 @@ -1,8 +1,11 @@ -.TH std::isxdigit(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isxdigit(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isxdigit(std::locale) \- std::isxdigit(std::locale) + .SH Synopsis Defined in header - template< class charT > - bool isxdigit( charT ch, const locale& loc ); + template< class CharT > + bool isxdigit( CharT ch, const locale& loc ); Checks if the given character is classified as a hexadecimal digit by the given locale's std::ctype facet. @@ -18,23 +21,63 @@ .SH Possible implementation - template< class charT > - bool isxdigit( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).is(std::ctype_base::xdigit, ch); + template + bool isxdigit(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).is(std::ctype_base::xdigit, ch); } .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - isxdigit checks if a character is a hexadecimal character - \fI(function)\fP - iswxdigit checks if a character is a hexadecimal character - \fI(function)\fP + #include + #include + #include + #include + + struct gxdigit_ctype : std::ctype + { + std::unordered_set greek_digits{L'α', L'β', L'γ', L'δ', L'ε', L'ζ'}; + + bool do_is(mask m, char_type c) const override + { + return (m & xdigit) && greek_digits.contains(c) + ? true // 6 first Greek small letters will be classified as digits + : ctype::do_is(m, c); // leave the rest to the parent class + } + }; + + int main() + { + std::wstring text = L"0123456789abcdefABCDEFαβγδεζηθικλμ"; + std::locale loc(std::locale(""), new gxdigit_ctype); + + std::locale::global(std::locale("en_US.utf8")); + std::wcout.imbue(std::locale()); -.SH Category: + std::wcout << "Hexadecimal digits in text: "; + for (const wchar_t c : text) + if (std::isxdigit(c, loc)) + std::wcout << c << L' '; + std::wcout << L'\\n'; - * Todo no example + std::wcout << "Not hexadecimal digits in text: "; + for (const wchar_t c : text) + if (not std::isxdigit(c, loc)) + std::wcout << c << L' '; + std::wcout << L'\\n'; + } + +.SH Output: + + Hexadecimal digits in text: 0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F α β γ δ ε ζ + Not hexadecimal digits in text: η θ ι κ λ μ + +.SH See also + + isxdigit checks if a character is a hexadecimal character + \fI(function)\fP + iswxdigit checks if a wide character is a hexadecimal character + \fI(function)\fP diff --git a/man/std::isxdigit.3 b/man/std::isxdigit.3 index 6c2997d9a..1c348e111 100644 --- a/man/std::isxdigit.3 +++ b/man/std::isxdigit.3 @@ -1,9 +1,12 @@ -.TH std::isxdigit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::isxdigit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::isxdigit \- std::isxdigit + .SH Synopsis Defined in header int isxdigit( int ch ); - Checks if the given wide character is a hexadecimal numeric character + Checks if the given character is a hexadecimal numeric character (0123456789abcdefABCDEF). The behavior is undefined if the value of ch is not representable as unsigned char @@ -15,43 +18,90 @@ .SH Return value - Non-zero value (true) if the character is an hexadecimal numeric character, 0 - (false) otherwise. + Non-zero value if the character is a hexadecimal numeric character, zero otherwise. .SH Notes - isdigit and isxdigit are the only standard narrow character classification functions - that are not affected by the currently installed C locale. although some + std::isdigit and std::isxdigit are the only standard narrow character classification + functions that are not affected by the currently installed C locale. although some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits. + Like all other functions from , the behavior of std::isxdigit is undefined + if the argument's value is neither representable as unsigned char nor equal to EOF. + To use these functions safely with plain chars (or signed chars), the argument + should first be converted to unsigned char: + + bool my_isxdigit(char ch) + { + return std::isxdigit(static_cast(ch)); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + int count_xdigits(const std::string& s) + { + return std::count_if(s.begin(), s.end(), + // static_cast(std::isxdigit) // wrong + // [](int c){ return std::isxdigit(c); } // wrong + // [](char c){ return std::isxdigit(c); } // wrong + [](unsigned char c){ return std::isxdigit(c); } // correct + ); + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + for (int c = 0; UCHAR_MAX >= c; ++c) + if (isxdigit(c)) + std::cout << static_cast(c); + std::cout << '\\n'; + } + +.SH Output: + + 0123456789ABCDEFabcdef + .SH See also checks if a character is classified as a hexadecimal digit by isxdigit(std::locale) a locale - \fI(function template)\fP - iswxdigit checks if a character is a hexadecimal character - \fI(function)\fP + \fI(function template)\fP + iswxdigit checks if a wide character is a hexadecimal character + \fI(function)\fP C documentation for isxdigit - ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit - (hex) iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit -0 - 8 0x00-0x08 control codes (NUL, ≠0 0 0 0 0 0 0 0 0 0 0 0 - etc.) -9 0x09 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 -10 - 13 0x0A-0x0D whitespaces ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 - (\\n,\\v,\\f,\\r) -14 - 31 0x0E-0x1F control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 -32 0x20 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 -33 - 47 0x21-0x2F !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -48 - 57 0x30-0x39 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 -58 - 64 0x3a-0x40 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -65 - 70 0x41-0x46 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 -71 - 90 0x47-0x5A GHIJKLMNOPQRSTUVWXYZ 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 -91 - 96 0x5B-0x60 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -97 -102 0x61-0x66 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 -103-122 0x67-0x7A ghijklmnopqrstuvwxyz 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 -123-126 0x7B-0x7E {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 -127 0x7F backspace character ≠0 0 0 0 0 0 0 0 0 0 0 0 - (DEL) + ASCII values characters iscntrl isprint isspace isblank isgraph ispunct isalnum isalpha isupper islower isdigit isxdigit +decimal hexadecimal octal iswcntrl iswprint iswspace iswblank iswgraph iswpunct iswalnum iswalpha iswupper iswlower iswdigit iswxdigit +0–8 \\x0–\\x8 \\0–\\10 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 + (NUL, etc.) +9 \\x9 \\11 tab (\\t) ≠0 0 ≠0 ≠0 0 0 0 0 0 0 0 0 + whitespaces +10–13 \\xA–\\xD \\12–\\15 (\\n, \\v, \\f, ≠0 0 ≠0 0 0 0 0 0 0 0 0 0 + \\r) +14–31 \\xE–\\x1F \\16–\\37 control codes ≠0 0 0 0 0 0 0 0 0 0 0 0 +32 \\x20 \\40 space 0 ≠0 ≠0 ≠0 0 0 0 0 0 0 0 0 +33–47 \\x21–\\x2F \\41–\\57 !"#$%&'()*+,-./ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +48–57 \\x30–\\x39 \\60–\\71 0123456789 0 ≠0 0 0 ≠0 0 ≠0 0 0 0 ≠0 ≠0 +58–64 \\x3A–\\x40 \\72–\\100 :;<=>?@ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +65–70 \\x41–\\x46 \\101–\\106 ABCDEF 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 ≠0 +71–90 \\x47–\\x5A \\107–\\132 GHIJKLMNOP 0 ≠0 0 0 ≠0 0 ≠0 ≠0 ≠0 0 0 0 + QRSTUVWXYZ +91–96 \\x5B–\\x60 \\133–\\140 [\\]^_` 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +97–102 \\x61–\\x66 \\141–\\146 abcdef 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 ≠0 +103–122 \\x67–\\x7A \\147–\\172 ghijklmnop 0 ≠0 0 0 ≠0 0 ≠0 ≠0 0 ≠0 0 0 + qrstuvwxyz +123–126 \\x7B–\\x7E \\172–\\176 {|}~ 0 ≠0 0 0 ≠0 ≠0 0 0 0 0 0 0 +127 \\x7F \\177 backspace ≠0 0 0 0 0 0 0 0 0 0 0 0 + character (DEL) diff --git a/man/std::iter_move(std::reverse_iterator).3 b/man/std::iter_move(std::reverse_iterator).3 new file mode 100644 index 000000000..a7319bb40 --- /dev/null +++ b/man/std::iter_move(std::reverse_iterator).3 @@ -0,0 +1,105 @@ +.TH std::iter_move(std::reverse_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iter_move(std::reverse_iterator) \- std::iter_move(std::reverse_iterator) + +.SH Synopsis + friend constexpr std::iter_rvalue_reference_t + iter_move( const std::reverse_iterator& i ) noexcept(/* see below \fI(since C++20)\fP + */); + + Casts the result of dereferencing the adjusted underlying iterator to its associated + rvalue reference type. + + The function body is equivalent to: + + auto tmp = i.base(); + return std::ranges::iter_move(--tmp); + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::reverse_iterator + is an associated class of the arguments. + +.SH Parameters + + i - a source reverse iterator + +.SH Return value + + An rvalue reference or a prvalue temporary. + +.SH Complexity + + Constant. + +.SH Exceptions + + noexcept specification: + noexcept( + + std::is_nothrow_copy_constructible_v && + noexcept(std::ranges::iter_move(--std::declval())) + + ) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto const& rem, auto const& v) + { + std::cout << rem << '[' << size(v) << "] {"; + for (char comma[]{0, 0}; auto const& s : v) + std::cout << comma << ' ' << std::quoted(s), comma[0] = ','; + std::cout << " }\\n"; + } + + int main() + { + std::vector p{"Alpha", "Bravo", "Charlie"}, q; + + print("p", p), print("q", q); + + using RI = std::reverse_iterator::iterator>; + + for (RI iter{p.rbegin()}, rend{p.rend()}; iter != rend; ++iter) + q.emplace_back(/* ADL */ iter_move(iter)); + + print("p", p), print("q", q); + } + +.SH Possible output: + + p[3] { "Alpha", "Bravo", "Charlie" } + q[0] { } + p[3] { "", "", "" } + q[3] { "Charlie", "Bravo", "Alpha" } + +.SH See also + + iter_move casts the result of dereferencing an object to its associated + (C++20) rvalue reference type + (customization point object) + iter_move casts the result of dereferencing the underlying iterator to + (C++20) its associated rvalue reference type + \fI(function)\fP + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP + move_if_noexcept obtains an rvalue reference if the move constructor does not + \fI(C++11)\fP throw + \fI(function template)\fP + forward forwards a function argument + \fI(C++11)\fP \fI(function template)\fP + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) + +.SH Category: + * conditionally noexcept diff --git a/man/std::iter_swap(std::reverse_iterator).3 b/man/std::iter_swap(std::reverse_iterator).3 new file mode 100644 index 000000000..062b3592c --- /dev/null +++ b/man/std::iter_swap(std::reverse_iterator).3 @@ -0,0 +1,92 @@ +.TH std::iter_swap(std::reverse_iterator) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iter_swap(std::reverse_iterator) \- std::iter_swap(std::reverse_iterator) + +.SH Synopsis + template< std::indirectly_swappable Iter2 > + + friend constexpr void + iter_swap( const reverse_iterator& x, \fI(since C++20)\fP + + const std::reverse_iterator& y ) + noexcept(/*see below*/); + + Swaps the objects pointed to by two adjusted underlying iterators. The function body + is equivalent to: + + auto tmp_x = x.base(); + auto tmp_y = y.base(); + ranges::iter_swap(--tmp_x, --tmp_y); + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::reverse_iterator + is an associated class of the arguments. + +.SH Parameters + + x, y - reverse iterators to the elements to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + noexcept specification: + noexcept( + + std::is_nothrow_copy_constructible_v && + std::is_nothrow_copy_constructible_v && + noexcept(ranges::iter_swap(--std::declval(), --std::declval())) + + ) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v{1, 2, 3}; + std::list l{4, 5, 6}; + + std::reverse_iterator::iterator> r1{v.rbegin()}; + std::reverse_iterator::iterator> r2{l.rbegin()}; + + std::cout << *r1 << ' ' << *r2 << '\\n'; + + iter_swap(r1, r2); // ADL + + std::cout << *r1 << ' ' << *r2 << '\\n'; + } + +.SH Output: + + 3 6 + 6 3 + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::iter_swap.3 b/man/std::iter_swap.3 index ba5f4618a..f35928fec 100644 --- a/man/std::iter_swap.3 +++ b/man/std::iter_swap.3 @@ -1,19 +1,25 @@ -.TH std::iter_swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iter_swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iter_swap \- std::iter_swap + .SH Synopsis Defined in header - template< class ForwardIt1, class ForwardIt2 > + template< class ForwardIt1, class ForwardIt2 > (constexpr since C++20) void iter_swap( ForwardIt1 a, ForwardIt2 b ); Swaps the values of the elements the given iterators are pointing to. + If any of the following conditions is satisfied, the behavior is undefined: + + * a or b is not dereferenceable. + * *a is not Swappable with *b. + .SH Parameters - a, b - iterators to the elements to swap + a, b - iterators to the elements to swap .SH Type requirements - - ForwardIt1, ForwardIt2 must meet the requirements of ForwardIterator. - - - *a, *b must meet the requirements of Swappable. + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value @@ -21,64 +27,94 @@ .SH Complexity - constant + Constant. + +.SH Notes + + This function template models the semantics of the swap operation given by + Swappable. That is, overloads of swap found by ADL and the fall back of std::swap + are considered. .SH Possible implementation template + constexpr //< since C++20 void iter_swap(ForwardIt1 a, ForwardIt2 b) { - using std::swap; - swap(*a, *b); + using std::swap; + swap(*a, *b); } .SH Example - The following is an implementation of selection sort in C++ + The following is an implementation of selection sort in C++. + - // Run this code + #include + #include #include + #include #include - #include - #include - #include - #include - + template void selection_sort(ForwardIt begin, ForwardIt end) { - for (ForwardIt i = begin; i != end; ++i) - std::iter_swap(i, std::min_element(i, end)); + for (ForwardIt it = begin; it != end; ++it) + std::iter_swap(it, std::min_element(it, end)); } - + + void println(std::string_view rem, std::vector const& v) + { + std::cout << rem; + for (int e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + template + int rand_int() + { + static std::uniform_int_distribution dist(min, max); + static std::mt19937 gen(std::random_device{}()); + return dist(gen); + } + int main() { - std::random_device rd; - std::mt19937 gen(rd()); - std::uniform_int_distribution<> dist(-10, 10); std::vector v; - generate_n(back_inserter(v), 20, bind(dist, gen)); - - std::cout << "Before sort: "; - copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); - + std::generate_n(std::back_inserter(v), 20, rand_int<-9, +9>); + + std::cout << std::showpos; + println("Before sort: ", v); selection_sort(v.begin(), v.end()); - - std::cout << "\\nAfter sort: "; - copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); - std::cout << '\\n'; + println("After sort: ", v); } -.SH Output: +.SH Possible output: + + Before sort: -9 -3 +2 -8 +0 -1 +8 -4 -5 +1 -4 -5 +4 -9 -8 -6 -6 +8 -4 -6 + After sort: -9 -9 -8 -8 -6 -6 -6 -5 -5 -4 -4 -4 -3 -1 +0 +1 +2 +4 +8 +8 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Before sort: -7 6 2 4 -1 6 -9 -1 2 -5 10 -9 -5 -3 -5 -3 6 6 1 8 - After sort: -9 -9 -7 -5 -5 -5 -3 -3 -1 -1 1 2 2 4 6 6 6 6 8 10 + DR Applied to Behavior as published Correct behavior + LWG 187 C++98 it was unspecified whether swap the effect is equivalent to + is used swap(*a, *b) .SH See also swap swaps the values of two objects - \fI(function template)\fP + \fI(function template)\fP swap_ranges swaps two ranges of elements - \fI(function template)\fP + \fI(function template)\fP + iter_swap swaps the objects pointed to by two adjusted underlying iterators + (C++20) \fI(function template)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function template)\fP + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) diff --git a/man/std::iter_value_t,std::iter_reference_t,std::iter_const_reference_t,.3 b/man/std::iter_value_t,std::iter_reference_t,std::iter_const_reference_t,.3 new file mode 100644 index 000000000..da19979c8 --- /dev/null +++ b/man/std::iter_value_t,std::iter_reference_t,std::iter_const_reference_t,.3 @@ -0,0 +1,75 @@ +.TH std::iter_value_t,std::iter_reference_t,std::iter_const_reference_t, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iter_value_t,std::iter_reference_t,std::iter_const_reference_t, \- std::iter_value_t,std::iter_reference_t,std::iter_const_reference_t, + +.SH Synopsis + + Defined in header + template< class T > (exposition + concept /*dereferenceable*/ = /* see below */; only*) + template< class T > \fB(1)\fP \fI(since C++20)\fP + using iter_value_t = /* see below */; + template< /*dereferenceable*/ T > \fB(2)\fP \fI(since C++20)\fP + using iter_reference_t = decltype(*std::declval()); + template< std::indirectly_readable T > + + using iter_const_reference_t = std::common_reference_t&&, \fB(3)\fP (since C++23) + + + std::iter_reference_t>; + template< class T > \fB(4)\fP \fI(since C++20)\fP + using iter_difference_t = /* see below */; + template< /*dereferenceable*/ T> + + requires /* see below */ \fB(5)\fP \fI(since C++20)\fP + + using iter_rvalue_reference_t = + decltype(ranges::iter_move(std::declval())); + template< std::indirectly_readable T > + + using iter_common_reference_t = + std::common_reference_t, \fB(6)\fP \fI(since C++20)\fP + + + std::iter_value_t&>; + + Compute the associated types of an iterator. The exposition-only concept + dereferenceable is satisfied if and only if the expression *std::declval() is + valid and has a referenceable type (in particular, not void). + + 1) Computes the value type of T. + * If std::iterator_traits> is not specialized, then + std::iter_value_t is + std::indirectly_readable_traits>::value_type. + * Otherwise, it is std::iterator_traits>::value_type. + 2) Computes the reference type of T. + 3) Computes the const reference type of T. + 4) Computes the difference type of T. + * If std::iterator_traits> is not specialized, then + std::iter_difference_t is + std::incrementable_traits>::difference_type. + * Otherwise, it is std::iterator_traits>::difference_type. + 5) Computes the rvalue reference type of T. The "see below" portion of the + constraint on this alias template is satisfied if and only if the expression + ranges::iter_move(std::declval()) is valid and has a referenceable type (in + particular, not void). + 6) Computes the common reference type of T. This is the common reference type + between its reference type and an lvalue reference to its value type. + +.SH See also + + indirectly_readable specifies that a type is indirectly readable by applying + (C++20) operator * + (concept) + weakly_incrementable specifies that a semiregular type can be incremented with + (C++20) pre- and post-increment operators + (concept) + indirectly_readable_traits computes the value type of an indirectly_readable type + (C++20) \fI(class template)\fP + incrementable_traits computes the difference type of a weakly_incrementable + (C++20) type + \fI(class template)\fP + provides uniform interface to the properties of an + iterator_traits iterator + \fI(class template)\fP diff --git a/man/std::iterator.3 b/man/std::iterator.3 index 9d83c87db..04057908b 100644 --- a/man/std::iterator.3 +++ b/man/std::iterator.3 @@ -1,11 +1,14 @@ -.TH std::iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iterator \- std::iterator + .SH Synopsis Defined in header template< class Category, class T, - class Distance = std::ptrdiff_t, + class Distance = std::ptrdiff_t, (deprecated in C++17) class Pointer = T*, class Reference = T& @@ -26,19 +29,75 @@ .SH Member types Member type Definition + iterator_category Category value_type T difference_type Distance pointer Pointer reference Reference - iterator_category Category + +.SH Example + + The following example shows how to implement an input iterator by inheriting from + std::iterator + + +// Run this code + + #include + #include + + template + class Range + { + public: + // member typedefs provided through inheriting from std::iterator + class iterator : public std::iterator< + std::input_iterator_tag, // iterator_category + long, // value_type + long, // difference_type + const long*, // pointer + long // reference + > { + long num = FROM; + public: + explicit iterator(long _num = 0) : num(_num) {} + iterator& operator++() { num = TO >= FROM ? num + 1: num - 1; return *this; } + iterator operator++(int) { iterator retval = *this; ++(*this); return retval; } + bool operator==(iterator other) const { return num == other.num; } + bool operator!=(iterator other) const { return !(*this == other); } + reference operator*() const { return num; } + }; + iterator begin() { return iterator(FROM); } + iterator end() { return iterator(TO >= FROM? TO + 1 : TO - 1); } + }; + + int main() + { + // std::find requires an input iterator + auto range = Range<15, 25>(); + auto itr = std::find(range.begin(), range.end(), 18); + std::cout << *itr << '\\n'; // 18 + + // Range::iterator also satisfies range-based for requirements + for (long l : Range<3, 5>()) + std::cout << l << ' '; // 3 4 5 + std::cout << '\\n'; + } + +.SH Output: + + 18 + 3 4 5 .SH See also provides uniform interface to the properties of an iterator_traits iterator - \fI(class template)\fP + \fI(class template)\fP input_iterator_tag - output_iterator_tag empty class types used to indicate iterator categories - forward_iterator_tag \fI(class)\fP - bidirectional_iterator_tag + output_iterator_tag + forward_iterator_tag empty class types used to indicate iterator categories + bidirectional_iterator_tag \fI(class)\fP random_access_iterator_tag + contiguous_iterator_tag + (C++20) diff --git a/man/std::iterator_traits.3 b/man/std::iterator_traits.3 index ffb5b7fca..e444065c2 100644 --- a/man/std::iterator_traits.3 +++ b/man/std::iterator_traits.3 @@ -1,128 +1,210 @@ -.TH std::iterator_traits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::iterator_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::iterator_traits \- std::iterator_traits + .SH Synopsis Defined in header - template< class Iterator> + template< class Iter > struct iterator_traits; template< class T > struct iterator_traits; - template< class T > + template< class T > (removed in C++20) struct iterator_traits; std::iterator_traits is the type trait class that provides uniform interface to the - properties of iterator types. This makes it possible to implement algorithms only in - terms of iterators. - - The class defines the following types that correspond to the typedefs provided by - std::iterator: - - * difference_type - a type that can be used to identify distance between iterators - * value_type - the type of the values that can be obtained by dereferencing the - iterator. This type is void for output iterators. - * pointer - defines a pointer to the type iterated over (value_type) - * reference - defines a reference to the type iterated over (value_type) - * iterator_category - the category of the iterator. Must be one of iterator - category tags. + properties of LegacyIterator types. This makes it possible to implement algorithms + only in terms of iterators. The template can be specialized for user-defined iterators so that the information about the iterator can be retrieved even if the type does not provide the usual typedefs. -.SH Template parameters - - Iterator - the iterator type to retrieve properties for + User specializations may define the nested type iterator_concept to + one of iterator category tags, to indicate conformance to the iterator \fI(since C++20)\fP + concepts. -.SH Member types +.SH Template parameters - Member type Definition - difference_type Iterator::difference_type - value_type Iterator::value_type - pointer Iterator::pointer - reference Iterator::reference - iterator_category Iterator::iterator_category + Iter - the iterator type to retrieve properties for + + Nested types + + Nested type Definition + difference_type Iter::difference_type + value_type Iter::value_type + pointer Iter::pointer + reference Iter::reference + iterator_category Iter::iterator_category + + If Iter does not have any of the five nested types above, then this template (since + has no members by any of those names (std::iterator_traits is C++17) + SFINAE-friendly). (until + C++20) + If Iter does not have pointer, but has all four remaining nested types, then + these four nested types are declared as follows: + + Nested type Definition + difference_type Iter::difference_type + value_type Iter::value_type + pointer void + reference Iter::reference + iterator_category Iter::iterator_category + + Otherwise, if Iter satisfies the exposition-only concept + __LegacyInputIterator, the nested types are declared as follows: + + Nested type Definition + difference_type std::incrementable_traits::difference_type + value_type std::indirectly_readable_traits::value_type + * Iter::pointer if valid. + pointer * Otherwise decltype(std::declval().operator->()) + if valid. + * Otherwise void. + reference * Iter::reference if valid. + * Otherwise std::iter_reference_t. (since + * Iter::iterator_category if valid. C++20) + * Otherwise, std::random_access_iterator_tag if Iter + satisfies __LegacyRandomAccessIterator. + iterator_category * Otherwise, std::bidirectional_iterator_tag if Iter + satisfies __LegacyBidirectionalIterator. + * Otherwise, std::forward_iterator_tag if Iter satisfies + __LegacyForwardIterator. + * Otherwise, std::input_iterator_tag. + + Otherwise, if Iter satisfies the exposition-only concept __LegacyIterator, + the nested types are declared as follows: + + Nested type Definition + * std::incrementable_traits::difference_type if + difference_type valid. + * Otherwise void. + value_type void + pointer void + reference void + iterator_category std::output_iterator_tag + + Otherwise, this template has no members by any of those names + (std::iterator_traits is SFINAE-friendly). .SH Specializations This type trait may be specialized for user-provided types that may be used as - iterators. The standard library provides two partial specializations for pointer - types T*, which makes it possible to use all iterator-based algorithms with raw - pointers. + iterators. The standard library provides partial specializations for pointer types + T*, which makes it possible to use all iterator-based algorithms with raw pointers. -.SH T* specialization member types + The standard library also provides partial specializations for some \fI(since C++20)\fP + standard iterator adaptors. - Member type Definition - difference_type std::ptrdiff_t - value_type T - pointer T* - reference T& - iterator_category std::random_access_iterator_tag + T* specialization nested types + + Only specialized if std::is_object_v is true. \fI(since C++20)\fP -.SH const T* specialization member types + Nested type Definition + difference_type std::ptrdiff_t + T + value_type \fI(until C++20)\fP + std::remove_cv_t + \fI(since C++20)\fP + pointer T* + reference T& + iterator_category std::random_access_iterator_tag + iterator_concept \fI(since C++20)\fP std::contiguous_iterator_tag - Member type Definition - difference_type std::ptrdiff_t + const T* specialization nested types + + Nested type Definition + difference_type std::ptrdiff_t \fI(until C++20)\fP value_type T pointer const T* reference const T& iterator_category std::random_access_iterator_tag + Specializations for library types + + provides uniform interface to the + std::iterator_traits properties of the std::common_iterator + (C++20) type + \fI(class template specialization)\fP + provides uniform interface to the + std::iterator_traits properties of the std::counted_iterator + (C++20) type + \fI(class template specialization)\fP + .SH Example - The following example shows a general-purpose reverse() implementation for - bidirectional iterators + Shows a general-purpose std::reverse() implementation for bidirectional iterators. + - // Run this code #include #include - #include #include - + #include + template void my_reverse(BidirIt first, BidirIt last) { typename std::iterator_traits::difference_type n = std::distance(first, last); - --n; - while(n > 0) { + for (--n; n > 0; n -= 2) + { typename std::iterator_traits::value_type tmp = *first; *first++ = *--last; *last = tmp; - n -= 2; } } - + int main() { std::vector v{1, 2, 3, 4, 5}; my_reverse(v.begin(), v.end()); - for (int n : v) { + for (int n : v) std::cout << n << ' '; - } std::cout << '\\n'; - + std::list l{1, 2, 3, 4, 5}; my_reverse(l.begin(), l.end()); - for (auto n : l) { + for (int n : l) + std::cout << n << ' '; + std::cout << '\\n'; + + int a[]{1, 2, 3, 4, 5}; + my_reverse(a, a + std::size(a)); + for (int n : a) std::cout << n << ' '; - } std::cout << '\\n'; - - // std::istreambuf_iterator i1(std::cin), i2; - // my_reverse(i1, i2); // compilation error - + + // std::istreambuf_iterator i1(std::cin), i2; + // my_reverse(i1, i2); // compilation error: i1, i2 are input iterators } .SH Output: 5 4 3 2 1 5 4 3 2 1 + 5 4 3 2 1 .SH See also - iterator the basic iterator - \fI(class template)\fP + iterator base class to ease the definition of required types for + (deprecated in C++17) simple iterators + \fI(class template)\fP input_iterator_tag - output_iterator_tag empty class types used to indicate iterator categories - forward_iterator_tag \fI(class)\fP - bidirectional_iterator_tag + output_iterator_tag + forward_iterator_tag empty class types used to indicate iterator categories + bidirectional_iterator_tag \fI(class)\fP random_access_iterator_tag + contiguous_iterator_tag + (C++20) + iter_value_t + iter_reference_t + iter_const_reference_t + iter_difference_t + iter_rvalue_reference_t + iter_common_reference_t computes the associated types of an iterator + (C++20) (alias template) + (C++20) + (C++23) + (C++20) + (C++20) + (C++20) diff --git a/man/std::jmp_buf.3 b/man/std::jmp_buf.3 index de5c8ec54..3b44a790d 100644 --- a/man/std::jmp_buf.3 +++ b/man/std::jmp_buf.3 @@ -1,4 +1,7 @@ -.TH std::jmp_buf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::jmp_buf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jmp_buf \- std::jmp_buf + .SH Synopsis Defined in header typedef /* unspecified */ jmp_buf; @@ -7,13 +10,71 @@ calling environment. The stored information is sufficient to restore execution at the correct block of the program and invocation of that block. The state of floating-point status flags, or open files, or any other data is not stored in an - object of type jmp_buf. + object of type std::jmp_buf. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + std::jmp_buf solver_error_handler; + + std::array solve_quadratic_equation(double a, double b, double c) + { + const double discriminant = b * b - 4.0 * a * c; + if (discriminant < 0) + std::longjmp(solver_error_handler, true); // Go to error handler + + const double delta = std::sqrt(discriminant) / (2.0 * a); + const double argmin = -b / (2.0 * a); + return {argmin - delta, argmin + delta}; + } + + void show_quadratic_equation_solution(double a, double b, double c) + { + std::cout << std::format("Solving {}x² + {}x + {} = 0...\\n", a, b, c); + auto [x_0, x_1] = solve_quadratic_equation(a, b, c); + std::cout << std::format("x₁ = {}, x₂ = {}\\n\\n", x_0, x_1); + } + + int main() + { + if (setjmp(solver_error_handler)) + { + // Error handler for solver + std::cout << "No real solution\\n"; + return EXIT_FAILURE; + } + + for (auto [a, b, c] : {std::array{1, -3, 2}, {2, -3, -2}, {1, 2, 3}}) + show_quadratic_equation_solution(a, b, c); + + return EXIT_SUCCESS; + } + +.SH Output: + + Solving 1x² + -3x + 2 = 0... + x₁ = 1, x₂ = 2 + + Solving 2x² + -3x + -2 = 0... + x₁ = -0.5, x₂ = 2 + + Solving 1x² + 2x + 3 = 0... + No real solution .SH See also setjmp saves the context - \fI(function macro)\fP + \fI(function macro)\fP longjmp jumps to specified location - \fI(function)\fP + \fI(function)\fP C documentation for jmp_buf diff --git a/man/std::jthread.3 b/man/std::jthread.3 new file mode 100644 index 000000000..b67c5b0a4 --- /dev/null +++ b/man/std::jthread.3 @@ -0,0 +1,93 @@ +.TH std::jthread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread \- std::jthread + +.SH Synopsis + Defined in header + class jthread; \fI(since C++20)\fP + + The class jthread represents a single thread of execution. It has the same general + behavior as std::thread, except that jthread automatically rejoins on destruction, + and can be cancelled/stopped in certain situations. + + Threads begin execution immediately upon construction of the associated thread + object (pending any OS scheduling delays), starting at the top-level function + provided as a constructor argument. The return value of the top-level function is + ignored and if it terminates by throwing an exception, std::terminate is called. The + top-level function may communicate its return value or an exception to the caller + via std::promise or by modifying shared variables (which may require + synchronization, see std::mutex and std::atomic). + + Unlike std::thread, the jthread logically holds an internal private member of type + std::stop_source, which maintains a shared stop-state. The jthread constructor + accepts a function that takes a std::stop_token as its first argument, which will be + passed in by the jthread from its internal std::stop_source. This allows the + function to check if stop has been requested during its execution, and return if it + has. + + std::jthread objects may also be in the state that does not represent any thread + (after default construction, move from, detach, or join), and a thread of execution + may be not associated with any jthread objects (after detach). + + No two std::jthread objects may represent the same thread of execution; std::jthread + is not CopyConstructible or CopyAssignable, although it is MoveConstructible and + MoveAssignable. + +.SH Member types + + Member type Definition + id std::thread::id + native_handle_type (optional*) std::thread::native_handle_type + +.SH Member functions + + constructor constructs new jthread object + \fI(public member function)\fP + if the thread is joinable, then a stop is requested and the + destructor thread joins + \fI(public member function)\fP + operator= moves the jthread object + \fI(public member function)\fP +.SH Observers + checks whether the thread is joinable, i.e. potentially running + joinable in parallel context + \fI(public member function)\fP + get_id returns the id of the thread + \fI(public member function)\fP + native_handle returns the underlying implementation-defined thread handle + \fI(public member function)\fP + hardware_concurrency returns the number of concurrent threads supported by the + \fB[static]\fP implementation + \fI(public static member function)\fP +.SH Operations + join waits for the thread to finish its execution + \fI(public member function)\fP + permits the thread to execute independently from the thread + detach handle + \fI(public member function)\fP + swap swaps two jthread objects + \fI(public member function)\fP + Stop token handling + returns a stop_source object associated with the shared stop + get_stop_source state of the thread + \fI(public member function)\fP + returns a stop_token associated with the shared stop state of + get_stop_token the thread + \fI(public member function)\fP + request_stop requests execution stop via the shared stop state of the thread + \fI(public member function)\fP + +.SH Non-member functions + + swap(std::jthread) specializes the std::swap algorithm + (C++20) \fI(function)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_jthread 201911L (C++20) Stop token and joining thread + +.SH See also + + thread manages a separate thread + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::jthread::detach.3 b/man/std::jthread::detach.3 new file mode 100644 index 000000000..788df142a --- /dev/null +++ b/man/std::jthread::detach.3 @@ -0,0 +1,84 @@ +.TH std::jthread::detach 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::detach \- std::jthread::detach + +.SH Synopsis + void detach(); \fI(since C++20)\fP + + Separates the thread of execution from the jthread object, allowing execution to + continue independently. Any allocated resources will be freed once the thread exits. + + After calling detach *this no longer owns any thread. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Postconditions + + joinable is false. + +.SH Exceptions + + std::system_error if joinable() == false or an error occurs. + +.SH Example + + +// Run this code + + #include + #include + #include + + void independentThread() + { + std::cout << "Starting concurrent thread.\\n"; + std::this_thread::sleep_for(std::chrono::seconds(2)); + std::cout << "Exiting concurrent thread.\\n"; + } + + void threadCaller() + { + std::cout << "Starting thread caller.\\n"; + std::jthread t(independentThread); + t.detach(); + std::this_thread::sleep_for(std::chrono::seconds(1)); + std::cout << "Exiting thread caller.\\n"; + } + + int main() + { + threadCaller(); + std::this_thread::sleep_for(std::chrono::seconds(5)); + } + +.SH Possible output: + + Starting thread caller. + Starting concurrent thread. + Exiting thread caller. + Exiting concurrent thread. + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 33.4.4.3 Members [thread.jthread.mem] + * C++20 standard (ISO/IEC 14882:2020): + + * 32.4.3.2 Members [thread.jthread.mem] + +.SH See also + + join waits for the thread to finish its execution + \fI(public member function)\fP + checks whether the thread is joinable, i.e. potentially running in parallel + joinable context + \fI(public member function)\fP + C documentation for + thrd_detach diff --git a/man/std::jthread::get_id.3 b/man/std::jthread::get_id.3 new file mode 100644 index 000000000..622a9a0ed --- /dev/null +++ b/man/std::jthread::get_id.3 @@ -0,0 +1,65 @@ +.TH std::jthread::get_id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::get_id \- std::jthread::get_id + +.SH Synopsis + [[nodiscard]] std::jthread::id get_id() const noexcept; \fI(since C++20)\fP + + Returns a value of std::jthread::id (which is a type alias for std::thread::id) + identifying the thread associated with *this. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A value of type std::jthread::id identifying the thread associated with *this. If + there is no thread associated, default constructed std::jthread::id is returned. + +.SH Example + + +// Run this code + + #include + #include + #include + + void foo() + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + int main() + { + std::jthread t1(foo); + std::jthread::id t1_id = t1.get_id(); + + std::jthread t2(foo); + std::jthread::id t2_id = t2.get_id(); + + std::cout << "t1's id: " << t1_id << '\\n'; + std::cout << "t2's id: " << t2_id << '\\n'; + + t1.join(); + t2.join(); + + std::cout << "t1's id after join: " << t1.get_id() << '\\n'; + std::cout << "t2's id after join: " << t2.get_id() << '\\n'; + } + +.SH Possible output: + + t1's id: 140146221688576 + t2's id: 140146213295872 + t1's id after join: thread::id of a non-executing thread + t2's id after join: thread::id of a non-executing thread + +.SH See also + + id represents the id of a thread + \fI(public member class of std::thread)\fP + checks whether the thread is joinable, i.e. potentially running in parallel + joinable context + \fI(public member function)\fP diff --git a/man/std::jthread::get_stop_source.3 b/man/std::jthread::get_stop_source.3 new file mode 100644 index 000000000..cb5ad94f8 --- /dev/null +++ b/man/std::jthread::get_stop_source.3 @@ -0,0 +1,86 @@ +.TH std::jthread::get_stop_source 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::get_stop_source \- std::jthread::get_stop_source + +.SH Synopsis + std::stop_source get_stop_source() noexcept; \fI(since C++20)\fP + + Returns a std::stop_source associated with the same shared stop-state as held + internally by the jthread object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A value of type std::stop_source associated with stop-state held internally by + jthread object. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + int main() + { + std::cout << std::boolalpha; + auto print = [](std::string_view name, const std::stop_source& source) + { + std::cout << name << ": stop_possible = " << source.stop_possible(); + std::cout << ", stop_requested = " << source.stop_requested() << '\\n'; + }; + + // A worker thread + auto worker = std::jthread([](std::stop_token stoken) + { + for (int i = 10; i; --i) + { + std::this_thread::sleep_for(300ms); + if (stoken.stop_requested()) + { + std::cout << " Sleepy worker is requested to stop\\n"; + return; + } + std::cout << " Sleepy worker goes back to sleep\\n"; + } + }); + + std::stop_source stop_source = worker.get_stop_source(); + print("stop_source", stop_source); + + std::cout << "\\nPass source to other thread:\\n"; + auto stopper = std::thread( + [](std::stop_source source) + { + std::this_thread::sleep_for(500ms); + std::cout << "Request stop for worker via source\\n"; + source.request_stop(); + }, + stop_source); + stopper.join(); + std::this_thread::sleep_for(200ms); + std::cout << '\\n'; + + print("stop_source", stop_source); + } + +.SH Possible output: + + stop_source: stop_possible = true, stop_requested = false + + Pass source to other thread: + Sleepy worker goes back to sleep + Request stop for worker via source + Sleepy worker is requested to stop + + stop_source: stop_possible = true, stop_requested = true diff --git a/man/std::jthread::get_stop_token.3 b/man/std::jthread::get_stop_token.3 new file mode 100644 index 000000000..1a1897bc3 --- /dev/null +++ b/man/std::jthread::get_stop_token.3 @@ -0,0 +1,114 @@ +.TH std::jthread::get_stop_token 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::get_stop_token \- std::jthread::get_stop_token + +.SH Synopsis + std::stop_token get_stop_token() const noexcept; \fI(since C++20)\fP + + Returns a std::stop_token associated with the same shared stop-state held internally + by the jthread object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A value of type std::stop_token associated with stop-state held internally by + jthread object. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + void print(std::string_view name, const std::stop_token& token) + { + std::cout << name << ": stop_possible = " << token.stop_possible(); + std::cout << ", stop_requested = " << token.stop_requested() << '\\n'; + } + + void finite_sleepy(std::stop_token stoken) + { + for (int i = 10; i; --i) + { + std::this_thread::sleep_for(300ms); + if (stoken.stop_requested()) + { + std::cout << " Sleepy worker is requested to stop\\n"; + return; + } + + std::cout << " Sleepy worker goes back to sleep\\n"; + } + } + + void infinite_sleepy() + { + for (int i = 5; i; --i) + { + std::this_thread::sleep_for(300ms); + std::cout << " Run as long as we want\\n"; + } + } + + + int main() + { + std::cout << std::boolalpha; + + // A worker thread that will listen to stop requests + std::jthread stop_worker(finite_sleepy); + + // A worker thread that will only stop when completed + std::jthread inf_worker(infinite_sleepy); + + std::stop_token def_token; + std::stop_token stop_token = stop_worker.get_stop_token(); + std::stop_token inf_token = inf_worker.get_stop_token(); + print("def_token ", def_token); + print("stop_token", stop_token); + print("inf_token ", inf_token); + + std::cout << "\\nRequest and join stop_worker:\\n"; + stop_worker.request_stop(); + stop_worker.join(); + + std::cout << "\\nRequest and join inf_worker:\\n"; + inf_worker.request_stop(); + inf_worker.join(); + std::cout << '\\n'; + + print("def_token ", def_token); + print("stop_token", stop_token); + print("inf_token ", inf_token); + } + +.SH Possible output: + + def_token : stop_possible = false, stop_requested = false + stop_token: stop_possible = true, stop_requested = false + inf_token : stop_possible = true, stop_requested = false + + Request and join stop_worker: + Run as long as we want + Sleepy worker is requested to stop + + Request and join inf_worker: + Run as long as we want + Run as long as we want + Run as long as we want + Run as long as we want + + def_token : stop_possible = false, stop_requested = false + stop_token: stop_possible = true, stop_requested = true + inf_token : stop_possible = true, stop_requested = true diff --git a/man/std::jthread::hardware_concurrency.3 b/man/std::jthread::hardware_concurrency.3 new file mode 100644 index 000000000..9b530e13b --- /dev/null +++ b/man/std::jthread::hardware_concurrency.3 @@ -0,0 +1,42 @@ +.TH std::jthread::hardware_concurrency 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::hardware_concurrency \- std::jthread::hardware_concurrency + +.SH Synopsis + [[nodiscard]] static unsigned int hardware_concurrency() noexcept; \fI(since C++20)\fP + + Returns the number of concurrent threads supported by the implementation. The value + should be considered only a hint. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Number of concurrent threads supported. If the value is not well defined or not + computable, returns 0. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + unsigned int n = std::jthread::hardware_concurrency(); + std::cout << n << " concurrent threads are supported.\\n"; + } + +.SH Possible output: + + 4 concurrent threads are supported. + +.SH See also + + hardware_destructive_interference_size min offset to avoid false sharing + hardware_constructive_interference_size max offset to promote true sharing + \fI(C++17)\fP (constant) diff --git a/man/std::jthread::join.3 b/man/std::jthread::join.3 new file mode 100644 index 000000000..3911732fe --- /dev/null +++ b/man/std::jthread::join.3 @@ -0,0 +1,101 @@ +.TH std::jthread::join 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::join \- std::jthread::join + +.SH Synopsis + void join(); \fI(since C++20)\fP + + Blocks the current thread until the thread identified by *this finishes its + execution. + + The completion of the thread identified by *this synchronizes with the corresponding + successful return from join(). + + No synchronization is performed on *this itself. Concurrently calling join() on the + same jthread object from multiple threads constitutes a data race that results in + undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Postconditions + + joinable() is false. + +.SH Exceptions + + std::system_error if an error occurs. + + Error conditions + + * resource_deadlock_would_occur if this->get_id() == std::this_thread::get_id() + \fI(deadlock detected)\fP. + * no_such_process if the thread is not valid. + * invalid_argument if joinable() is false. + +.SH Example + + +// Run this code + + #include + #include + #include + + void foo() + { + // simulate expensive operation + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + void bar() + { + // simulate expensive operation + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + int main() + { + std::cout << "starting first helper...\\n"; + std::jthread helper1(foo); + + std::cout << "starting second helper...\\n"; + std::jthread helper2(bar); + + std::cout << "waiting for helpers to finish..." << std::endl; + helper1.join(); + helper2.join(); + + std::cout << "done!\\n"; + } + +.SH Output: + + starting first helper... + starting second helper... + waiting for helpers to finish... + done! + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 33.4.4.3 Members [thread.jthread.mem] + * C++20 standard (ISO/IEC 14882:2020): + + * 32.4.3.2 Members [thread.jthread.mem] + +.SH See also + + detach permits the thread to execute independently from the thread handle + \fI(public member function)\fP + checks whether the thread is joinable, i.e. potentially running in parallel + joinable context + \fI(public member function)\fP + C documentation for + thrd_join diff --git a/man/std::jthread::joinable.3 b/man/std::jthread::joinable.3 new file mode 100644 index 000000000..b21d032f7 --- /dev/null +++ b/man/std::jthread::joinable.3 @@ -0,0 +1,81 @@ +.TH std::jthread::joinable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::joinable \- std::jthread::joinable + +.SH Synopsis + [[nodiscard]] bool joinable() const noexcept; \fI(since C++20)\fP + + Checks if the std::jthread object identifies an active thread of execution. + Specifically, returns true if get_id() != std::jthread::id(). So a default + constructed jthread is not joinable. + + A thread that has finished executing code, but has not yet been joined is still + considered an active thread of execution and is therefore joinable. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the jthread object identifies an active thread of execution, false + otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + using namespace std::chrono_literals; + + void foo() + { + std::this_thread::sleep_for(500ms); + } + + int main() + { + std::cout << std::boolalpha; + + std::jthread t; + std::cout << "before starting, joinable: " << t.joinable() << '\\n'; + + t = std::jthread{foo}; + std::cout << "after starting, joinable: " << t.joinable() << '\\n'; + + t.join(); + std::cout << "after joining, joinable: " << t.joinable() << '\\n'; + + t = std::jthread{foo}; + t.detach(); + std::cout << "after detaching, joinable: " << t.joinable() << '\\n'; + + } + +.SH Output: + + before starting, joinable: false + after starting, joinable: true + after joining, joinable: false + after detaching, joinable: false + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 33.4.4.3 Members [thread.jthread.mem] + * C++20 standard (ISO/IEC 14882:2020): + + * 32.4.3.2 Members [thread.jthread.mem] + +.SH See also + + get_id returns the id of the thread + \fI(public member function)\fP + join waits for the thread to finish its execution + \fI(public member function)\fP + detach permits the thread to execute independently from the thread handle + \fI(public member function)\fP diff --git a/man/std::jthread::jthread.3 b/man/std::jthread::jthread.3 new file mode 100644 index 000000000..476512387 --- /dev/null +++ b/man/std::jthread::jthread.3 @@ -0,0 +1,210 @@ +.TH std::jthread::jthread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::jthread \- std::jthread::jthread + +.SH Synopsis + jthread() noexcept; \fB(1)\fP \fI(since C++20)\fP + jthread( jthread&& other ) noexcept; \fB(2)\fP \fI(since C++20)\fP + template< class F, class... Args > \fB(3)\fP \fI(since C++20)\fP + explicit jthread( F&& f, Args&&... args ); + jthread( const jthread& ) = delete; \fB(4)\fP \fI(since C++20)\fP + + Constructs new std::jthread object. + + 1) Creates new std::jthread object which does not represent a thread. + 2) Move constructor. Constructs the std::jthread object to represent the thread of + execution that was represented by other. After this call other no longer represents + a thread of execution. + 3) Creates new std::jthread object and associates it with a thread of execution. + + The new thread of execution starts executing: + + std::invoke(decay-copy(std::forward(f)), get_stop_token(), (until C++23) + decay-copy(std::forward(args))...) + std::invoke(auto(std::forward(f)), get_stop_token(), (since C++23) + auto(std::forward(args))...) + + if the expression above is well-formed, otherwise starts executing: + + std::invoke(decay-copy(std::forward(f)), (until C++23) + decay-copy(std::forward(args))...). + std::invoke(auto(std::forward(f)), (since C++23) + auto(std::forward(args))...). + + The calls of decay-copy are evaluated + (until C++23) + The values produced by auto are materialized + (since C++23) in the current thread, so that any exceptions thrown during evaluation + and copying/moving of the arguments are thrown in the current thread, without + starting the new thread. + These overloads participate in overload resolution only if std::remove_cvref_t is + not the same type as std::jthread. + If any of the following is false, the program is ill-formed: + * std::is_constructible_v, F> + * (std::is_constructible_v, Args> && ...) + * std::is_invocable_v, std::decay_t...> || + std::is_invocable_v, std::stop_token, std::decay_t...> + The completion of the invocation of the constructor synchronizes with the beginning + of the invocation of the copy of f on the new thread of execution. + 4) The copy constructor is deleted; threads are not copyable. No two std::jthread + objects may represent the same thread of execution. + +.SH Parameters + + other - another std::jthread object to construct this std::jthread object with + f - Callable object to execute in the new thread + args - arguments to pass to the new function + +.SH Postconditions + + 1) get_id() equal to std::jthread::id() (i.e. joinable() returns false) and + get_stop_source().stop_possible() is false. + 2) other.get_id() equal to std::jthread::id() and get_id() returns the value of + other.get_id() prior to the start of construction. + 3) get_id() not equal to std::jthread::id() (i.e. joinable() returns true), and + get_stop_source().stop_possible() is true. + +.SH Exceptions + + 3) std::system_error if the thread could not be started. The exception may represent + the error condition std::errc::resource_unavailable_try_again or another + implementation-specific error condition. + +.SH Notes + + The arguments to the thread function are moved or copied by value. If a reference + argument needs to be passed to the thread function, it has to be wrapped (e.g. with + std::ref or std::cref). + + Any return value from the function is ignored. If the function throws an exception, + std::terminate is called. In order to pass return values or exceptions back to the + calling thread, std::promise or std::async may be used. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + using namespace std::literals; + + void f1(int n) + { + for (int i = 0; i < 5; ++i) + { + std::cout << "Thread 1 executing\\n"; + ++n; + std::this_thread::sleep_for(10ms); + } + } + + void f2(int& n) + { + for (int i = 0; i < 5; ++i) + { + std::cout << "Thread 2 executing\\n"; + ++n; + std::this_thread::sleep_for(10ms); + } + } + + class foo + { + public: + void bar() + { + for (int i = 0; i < 5; ++i) + { + std::cout << "Thread 3 executing\\n"; + ++n; + std::this_thread::sleep_for(10ms); + } + } + int n = 0; + }; + + class baz + { + public: + void operator()() + { + for (int i = 0; i < 5; ++i) + { + std::cout << "Thread 4 executing\\n"; + ++n; + std::this_thread::sleep_for(10ms); + } + } + int n = 0; + }; + + int main() + { + int n = 0; + foo f; + baz b; + std::jthread t0; // t0 is not a thread + std::jthread t1(f1, n + 1); // pass by value + std::jthread t2a(f2, std::ref(n)); // pass by reference + std::jthread t2b(std::move(t2a)); // t2b is now running f2(). t2a is no longer a thread + std::jthread t3(&foo::bar, &f); // t3 runs foo::bar() on object f + std::jthread t4(b); // t4 runs baz::operator() on a copy of object b + t1.join(); + t2b.join(); + t3.join(); + std::cout << "Final value of n is " << n << '\\n'; + std::cout << "Final value of f.n (foo::n) is " << f.n << '\\n'; + std::cout << "Final value of b.n (baz::n) is " << b.n << '\\n'; + // t4 joins on destruction + } + +.SH Possible output: + + Thread 2 executing + Thread 1 executing + Thread 4 executing + Thread 3 executing + Thread 3 executing + Thread 4 executing + Thread 2 executing + Thread 1 executing + Thread 3 executing + Thread 1 executing + Thread 4 executing + Thread 2 executing + Thread 3 executing + Thread 1 executing + Thread 4 executing + Thread 2 executing + Thread 3 executing + Thread 1 executing + Thread 4 executing + Thread 2 executing + Final value of n is 5 + Final value of f.n (foo::n) is 5 + Final value of b.n (baz::n) is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(3)\fP directly required (the decayed + LWG 3476 C++20 types of) removed these + F and the argument types to be move requirements^[1] + constructible + + 1. ↑ The move-constructibility is already indirectly required by + std::is_constructible_v. + +.SH See also + + constructor constructs new thread object + \fI(public member function of std::thread)\fP + C documentation for + thrd_create diff --git a/man/std::jthread::native_handle.3 b/man/std::jthread::native_handle.3 new file mode 100644 index 000000000..edf991ba6 --- /dev/null +++ b/man/std::jthread::native_handle.3 @@ -0,0 +1,67 @@ +.TH std::jthread::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::native_handle \- std::jthread::native_handle + +.SH Synopsis + [[nodiscard]] native_handle_type native_handle(); \fI(since C++20)\fP + (not always present) + + Returns the implementation defined underlying thread handle. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Implementation defined handle type representing the thread. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + Uses native_handle to enable realtime scheduling of C++ threads on a POSIX system. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + std::mutex iomutex; + void f(int num) + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + + sched_param sch; + int policy; + pthread_getschedparam(pthread_self(), &policy, &sch); + std::lock_guard lk(iomutex); + std::cout << "Thread " << num << " is executing at priority " + << sch.sched_priority << '\\n'; + } + + int main() + { + std::jthread t1(f, 1), t2(f, 2); + + sched_param sch; + int policy; + pthread_getschedparam(t1.native_handle(), &policy, &sch); + sch.sched_priority = 20; + if (pthread_setschedparam(t1.native_handle(), SCHED_FIFO, &sch)) + std::cout << "Failed to setschedparam: " << std::strerror(errno) << '\\n'; + + + } + +.SH Output: + + Thread 2 is executing at priority 0 + Thread 1 is executing at priority 20 diff --git a/man/std::jthread::operator=.3 b/man/std::jthread::operator=.3 new file mode 100644 index 000000000..4b9b265c1 --- /dev/null +++ b/man/std::jthread::operator=.3 @@ -0,0 +1,22 @@ +.TH std::jthread::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::operator= \- std::jthread::operator= + +.SH Synopsis + std::jthread& operator=( std::jthread&& other ) noexcept; \fI(since C++20)\fP + + If *this still has an associated running thread (i.e. joinable() == true), calls + request_stop() followed by join(). Assigns the state of other to *this and sets + other to a default constructed state. + + After this call, this->get_id() is equal to the value of other.get_id() prior to the + call and the associated stop-state is also moved, and other no longer represents a + thread of execution nor has any stop-state. + +.SH Parameters + + other - another jthread object to assign to this jthread object + +.SH Return value + + *this diff --git a/man/std::jthread::request_stop.3 b/man/std::jthread::request_stop.3 new file mode 100644 index 000000000..709638ebd --- /dev/null +++ b/man/std::jthread::request_stop.3 @@ -0,0 +1,111 @@ +.TH std::jthread::request_stop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::request_stop \- std::jthread::request_stop + +.SH Synopsis + bool request_stop() noexcept; \fI(since C++20)\fP + + Issues a stop request to the internal stop-state, if it has not yet already had stop + requested. + + The determination is made atomically, and if stop was requested, the stop-state is + atomically updated to avoid race conditions, such that: + + * stop_requested() and stop_possible() can be concurrently invoked on other + std::stop_tokens and std::stop_sources of the same shared stop-state. + * request_stop() can be concurrently invoked from multiple threads on the same + jthread object or on other std::stop_source objects associated with the same + stop-state, and only one will actually perform the stop request. + + However, see the Notes section. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if this invocation made a stop request, otherwise false. + +.SH Postconditions + + For a std::stop_token retrieved by get_stop_token() or a std::stop_source retrieved + by get_stop_source(), stop_requested() is true. + +.SH Notes + + If the request_stop() does issue a stop request (i.e., returns true), then any + std::stop_callbacks registered for the same associated stop-state will be invoked + synchronously, on the same thread request_stop() is issued on. If an invocation of a + callback exits via an exception, std::terminate is called. + + If a stop request has already been made, this function returns false. However there + is no guarantee that another thread or std::stop_source object which has just + (successfully) requested stop for the same stop-state is not still in the middle of + invoking a std::stop_callback function. + + If the request_stop() does issue a stop request (i.e., returns true), then all + condition variables of base type std::condition_variable_any registered with an + interruptible wait for std::stop_tokens associated with the jthread's internal + stop-state will be awoken. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + int main() + { + // A sleepy worker thread + std::jthread sleepy_worker( + [](std::stop_token stoken) + { + for (int i = 10; i; --i) + { + std::this_thread::sleep_for(300ms); + if (stoken.stop_requested()) + { + std::cout << "Sleepy worker is requested to stop\\n"; + return; + } + std::cout << "Sleepy worker goes back to sleep\\n"; + } + }); + + // A waiting worker thread + // The condition variable will be awoken by the stop request. + std::jthread waiting_worker( + [](std::stop_token stoken) + { + std::mutex mutex; + std::unique_lock lock(mutex); + std::condition_variable_any().wait(lock, stoken, []{ return false; }); + std::cout << "Waiting worker is requested to stop\\n"; + return; + }); + + // std::jthread::request_stop() can be called explicitly: + std::cout << "Requesting stop of sleepy worker\\n"; + sleepy_worker.request_stop(); + sleepy_worker.join(); + std::cout << "Sleepy worker joined\\n"; + + // Or automatically using RAII: + // waiting_worker's destructor will call request_stop() + // and join the thread automatically. + } + +.SH Possible output: + + Requesting stop of sleepy worker + Sleepy worker is requested to stop + Sleepy worker joined + Waiting worker is requested to stop diff --git a/man/std::jthread::swap.3 b/man/std::jthread::swap.3 new file mode 100644 index 000000000..da9b8d57d --- /dev/null +++ b/man/std::jthread::swap.3 @@ -0,0 +1,74 @@ +.TH std::jthread::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::swap \- std::jthread::swap + +.SH Synopsis + void swap( std::jthread& other ) noexcept; \fI(since C++20)\fP + + Exchanges the underlying handles of two jthread objects. + +.SH Parameters + + other - the jthread to swap with + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + void foo() + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + void bar() + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + int main() + { + std::jthread t1(foo); + std::jthread t2(bar); + + std::cout << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + std::swap(t1, t2); + + std::cout << "after std::swap(t1, t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + t1.swap(t2); + + std::cout << "after t1.swap(t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + + } + +.SH Possible output: + + thread 1 id: 140185268262656 + thread 2 id: 140185259869952 + after std::swap(t1, t2): + thread 1 id: 140185259869952 + thread 2 id: 140185268262656 + after t1.swap(t2): + thread 1 id: 140185268262656 + thread 2 id: 140185259869952 + +.SH See also + + swap(std::jthread) specializes the std::swap algorithm + (C++20) \fI(function)\fP diff --git a/man/std::jthread::~jthread.3 b/man/std::jthread::~jthread.3 new file mode 100644 index 000000000..d6e81d462 --- /dev/null +++ b/man/std::jthread::~jthread.3 @@ -0,0 +1,39 @@ +.TH std::jthread::~jthread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::jthread::~jthread \- std::jthread::~jthread + +.SH Synopsis + ~jthread(); \fI(since C++20)\fP + + Destroys the jthread object. + + If *this has an associated thread (joinable() == true), calls request_stop() and + then join(). + +.SH Notes + + The request_stop() has no effect if the jthread was previously requested to stop. + + A jthread object does not have an associated thread after + + * it was default-constructed. + * it was moved from. + * join() has been called. + * detach() has been called. + + If join() throws an exception (e.g. because deadlock is detected), std::terminate() + may be called. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + destructs the thread object, underlying thread must be joined or + destructor detached + \fI(public member function of std::thread)\fP + +.SH Category: + * Todo no example diff --git a/man/std::kill_dependency.3 b/man/std::kill_dependency.3 index ad54442ad..37a624739 100644 --- a/man/std::kill_dependency.3 +++ b/man/std::kill_dependency.3 @@ -1,14 +1,21 @@ -.TH std::kill_dependency 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::kill_dependency 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::kill_dependency \- std::kill_dependency + .SH Synopsis Defined in header - template< class T > - T kill_dependency( T y ); + template< class T > \fI(since C++11)\fP + T kill_dependency( T y ) noexcept; Informs the compiler that the dependency tree started by an std::memory_order_consume atomic load operation does not extend past the return value of std::kill_dependency; that is, the argument does not carry a dependency into the return value. + This may be used to avoid unnecessary std::memory_order_acquire fences when the + dependency chain leaves function scope (and the function does not have the + [[carries_dependency]] attribute). + .SH Parameters y - the expression whose return value is to be removed from a dependency tree @@ -17,22 +24,51 @@ Returns y, no longer a part of a dependency tree. -.SH Exceptions +.SH Examples - noexcept specification: - noexcept - + file1.cpp: -.SH Examples + struct Foo + { + int* a; + int* b; + }; - This section is incomplete - Reason: no example + std::atomic foo_head[10]; + int foo_array[10][10]; -.SH See also + // consume operation starts a dependency chain, which escapes this function + [[carries_dependency]] Foo* f(int i) + { + return foo_head[i].load(memory_order_consume); + } - memory_order defines memory ordering constraints for the given atomic operation - \fI(C++11)\fP \fI(typedef)\fP + // the dependency chain enters this function through the right parameter and is + // killed before the function ends (so no extra acquire operation takes place) + int g(int* x, int* y [[carries_dependency]]) + { + return std::kill_dependency(foo_array[*x][*y]); + } -.SH Category: + file2.cpp: - * Todo no example + [[carries_dependency]] struct Foo* f(int i); + int g(int* x, int* y [[carries_dependency]]); + + int c = 3; + void h(int i) + { + Foo* p; + p = f(i); // dependency chain started inside f continues into p without undue acquire + do_something_with(g(&c, p->a)); // p->b is not brought in from the cache + do_something_with(g(p->a, &c)); // left argument does not have the carries_dependency + // attribute: memory acquire fence may be issued + // p->b becomes visible before g() is entered + } + +.SH See also + + memory_order defines memory ordering constraints for the given atomic operation + \fI(C++11)\fP \fI(enum)\fP + C documentation for + kill_dependency diff --git a/man/std::laguerre,std::laguerref,std::laguerrel.3 b/man/std::laguerre,std::laguerref,std::laguerrel.3 new file mode 100644 index 000000000..114fa5651 --- /dev/null +++ b/man/std::laguerre,std::laguerref,std::laguerrel.3 @@ -0,0 +1,122 @@ +.TH std::laguerre,std::laguerref,std::laguerrel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::laguerre,std::laguerref,std::laguerrel \- std::laguerre,std::laguerref,std::laguerrel + +.SH Synopsis + double laguerre( unsigned int n, double x ); + + double laguerre( unsigned int n, float x ); + double laguerre( unsigned int n, long double x ); \fB(1)\fP + float laguerref( unsigned int n, float x ); + + long double laguerrel( unsigned int n, long double x ); + double laguerre( unsigned int n, IntegralType x ); \fB(2)\fP + + 1) Computes the non-associated Laguerre polynomials of the degree n and argument x. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, laguerre is only guaranteed to be available in if + __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least + 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any + standard library headers. + +.SH Parameters + + n - the degree of the polynomial, a value of unsigned integer type + x - the argument, a value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the nonassociated Laguerre polynomial of x, that is + + e^x + n! + + dn + dxn + + (xn + e^-x), is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If x is negative, a domain error may occur. + * If n is greater or equal than 128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The Laguerre polynomials are the polynomial solutions of the equation xy,, + + (1 - x)y, + + ny = 0. + + The first few are: + + * laguerre(0, x) = 1. + * laguerre(1, x) = -x + 1. + * laguerre(2, x) = + + 1 + 2 + + [x2 + - 4x + 2]. + * laguerre(3, x) = + + 1 + 6 + + [-x3 + - 9x2 + - 18x + 6]. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + double L1(double x) + { + return -x + 1; + } + + double L2(double x) + { + return 0.5 * (x * x - 4 * x + 2); + } + + int main() + { + // spot-checks + std::cout << std::laguerre(1, 0.5) << '=' << L1(0.5) << '\\n' + << std::laguerre(2, 0.5) << '=' << L2(0.5) << '\\n'; + } + +.SH Output: + + 0.5=0.5 + 0.125=0.125 + +.SH See also + + assoc_laguerre associated Laguerre polynomials + assoc_laguerref \fI(function)\fP + assoc_laguerrel + +.SH External links + + Weisstein, Eric W. "Laguerre Polynomial." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::latch.3 b/man/std::latch.3 new file mode 100644 index 000000000..22ec91d6b --- /dev/null +++ b/man/std::latch.3 @@ -0,0 +1,112 @@ +.TH std::latch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch \- std::latch + +.SH Synopsis + Defined in header + class latch; \fI(since C++20)\fP + + The latch class is a downward counter of type std::ptrdiff_t which can be used to + synchronize threads. The value of the counter is initialized on creation. Threads + may block on the latch until the counter is decremented to zero. There is no + possibility to increase or reset the counter, which makes the latch a single-use + barrier. + + Concurrent invocations of the member functions of std::latch, except for the + destructor, do not introduce data races. + + Unlike std::barrier, std::latch can be decremented by a participating thread more + than once. + +.SH Member functions + + constructor constructs a latch + \fI(public member function)\fP + destructor destroys the latch + \fI(public member function)\fP + operator= latch is not assignable + [deleted] \fI(public member function)\fP + count_down decrements the counter in a non-blocking manner + \fI(public member function)\fP + try_wait tests if the internal counter equals zero + \fI(public member function)\fP + wait blocks until the counter reaches zero + \fI(public member function)\fP + arrive_and_wait decrements the counter and blocks until it reaches zero + \fI(public member function)\fP +.SH Constants + max the maximum value of counter supported by the implementation + \fB[static]\fP \fI(public static member function)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_latch 201907L (C++20) std::latch + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct Job + { + const std::string name; + std::string product{"not worked"}; + std::thread action{}; + }; + + int main() + { + Job jobs[]{{"Annika"}, {"Buru"}, {"Chuck"}}; + + std::latch work_done{std::size(jobs)}; + std::latch start_clean_up{1}; + + auto work = [&](Job& my_job) + { + my_job.product = my_job.name + " worked"; + work_done.count_down(); + start_clean_up.wait(); + my_job.product = my_job.name + " cleaned"; + }; + + std::cout << "Work is starting... "; + for (auto& job : jobs) + job.action = std::thread{work, std::ref(job)}; + + work_done.wait(); + std::cout << "done:\\n"; + for (auto const& job : jobs) + std::cout << " " << job.product << '\\n'; + + std::cout << "Workers are cleaning up... "; + start_clean_up.count_down(); + for (auto& job : jobs) + job.action.join(); + + std::cout << "done:\\n"; + for (auto const& job : jobs) + std::cout << " " << job.product << '\\n'; + } + +.SH Output: + + Work is starting... done: + Annika worked + Buru worked + Chuck worked + Workers are cleaning up... done: + Annika cleaned + Buru cleaned + Chuck cleaned + +.SH See also + + barrier reusable thread barrier + (C++20) \fI(class template)\fP diff --git a/man/std::latch::arrive_and_wait.3 b/man/std::latch::arrive_and_wait.3 new file mode 100644 index 000000000..ab617edb7 --- /dev/null +++ b/man/std::latch::arrive_and_wait.3 @@ -0,0 +1,24 @@ +.TH std::latch::arrive_and_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::arrive_and_wait \- std::latch::arrive_and_wait + +.SH Synopsis + void arrive_and_wait( std::ptrdiff_t n = 1 ); \fI(since C++20)\fP + + Atomically decrements the internal counter by n and (if necessary) blocks the + calling thread until the counter reaches zero. Equivalent to count_down(n); wait();. + + If n is greater than the value of the internal counter or is negative, the behavior + is undefined. + +.SH Parameters + + n - the value by which the internal counter is decreased + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. diff --git a/man/std::latch::count_down.3 b/man/std::latch::count_down.3 new file mode 100644 index 000000000..063ad3483 --- /dev/null +++ b/man/std::latch::count_down.3 @@ -0,0 +1,25 @@ +.TH std::latch::count_down 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::count_down \- std::latch::count_down + +.SH Synopsis + void count_down( std::ptrdiff_t n = 1 ); \fI(since C++20)\fP + + Atomically decrements the internal counter by n without blocking the caller. + + If n is greater than the value of the internal counter or is negative, the behavior + is undefined. + + This operation strongly happens-before all calls that are unblocked on this latch. + +.SH Parameters + + n - the value by which the internal counter is decreased + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. diff --git a/man/std::latch::latch.3 b/man/std::latch::latch.3 new file mode 100644 index 000000000..30cabb39e --- /dev/null +++ b/man/std::latch::latch.3 @@ -0,0 +1,19 @@ +.TH std::latch::latch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::latch \- std::latch::latch + +.SH Synopsis + constexpr explicit latch( std::ptrdiff_t expected ); \fB(1)\fP \fI(since C++20)\fP + latch( const latch& ) = delete; \fB(2)\fP \fI(since C++20)\fP + + 1) Constructs a latch and initializes its internal counter. The behavior is + undefined if expected is negative or greater than max(). + 2) Copy constructor is deleted. latch is neither copyable nor movable. + +.SH Parameters + + expected - the initial value of the internal counter + +.SH Exceptions + + Throws nothing. diff --git a/man/std::latch::max.3 b/man/std::latch::max.3 new file mode 100644 index 000000000..7f971dbdd --- /dev/null +++ b/man/std::latch::max.3 @@ -0,0 +1,16 @@ +.TH std::latch::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::max \- std::latch::max + +.SH Synopsis + static constexpr std::ptrdiff_t max() noexcept; \fI(since C++20)\fP + + Returns the maximum value of the internal counter supported by the implementation. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The maximum value of the internal counter supported by the implementation. diff --git a/man/std::latch::try_wait.3 b/man/std::latch::try_wait.3 new file mode 100644 index 000000000..979b17e30 --- /dev/null +++ b/man/std::latch::try_wait.3 @@ -0,0 +1,24 @@ +.TH std::latch::try_wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::try_wait \- std::latch::try_wait + +.SH Synopsis + bool try_wait() const noexcept; \fI(since C++20)\fP + + Returns true only if the internal counter has reached zero. This function may + spuriously return false with very low probability even if the internal counter has + reached zero. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + With very low probability false, otherwise cnt == 0, where cnt is the value of the + internal counter. + +.SH Notes + + The reason why a spurious result is permitted is to allow implementations to use a + memory order more relaxed than std::memory_order_seq_cst. diff --git a/man/std::latch::wait.3 b/man/std::latch::wait.3 new file mode 100644 index 000000000..6614bface --- /dev/null +++ b/man/std::latch::wait.3 @@ -0,0 +1,21 @@ +.TH std::latch::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::wait \- std::latch::wait + +.SH Synopsis + void wait() const; \fI(since C++20)\fP + + Blocks the calling thread until the internal counter reaches 0. If it is zero + already, returns immediately. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error with an error code allowed for mutex types on error. diff --git a/man/std::latch::~latch.3 b/man/std::latch::~latch.3 new file mode 100644 index 000000000..82031a5d5 --- /dev/null +++ b/man/std::latch::~latch.3 @@ -0,0 +1,13 @@ +.TH std::latch::~latch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::latch::~latch \- std::latch::~latch + +.SH Synopsis + ~latch(); \fI(since C++20)\fP + + Destroys the latch. + +.SH Notes + + The behavior is undefined if any thread is concurrently calling a member function of + the latch. diff --git a/man/std::launch.3 b/man/std::launch.3 index 098e8a182..f77e787c1 100644 --- a/man/std::launch.3 +++ b/man/std::launch.3 @@ -1,4 +1,7 @@ -.TH std::launch 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::launch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::launch \- std::launch + .SH Synopsis Defined in header enum class launch : /* unspecified */ { @@ -9,14 +12,15 @@ }; - Specifies the launch policy for a task executed by the std::async function. - std::launch is an enumeration used as BitmaskType. + std::launch is a BitmaskType. It specifies the launch policy for a task executed by + the std::async function. The following constants denoting individual bits are defined by the standard library: Constant Explanation - std::launch::async a new thread is launched to execute the task asynchronously + std::launch::async the task is executed on a different thread, potentially by + creating and launching it first std::launch::deferred the task is executed on the calling thread the first time its result is requested (lazy evaluation) @@ -26,8 +30,17 @@ applicable to a subset of launch policies, and * enable those additional bitmasks for the first (default) overload of std::async. + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2102 C++11 std::launch was an it is not + implementation-defined type implementation-defined + .SH See also async runs a function asynchronously (potentially in a new thread) and returns a \fI(C++11)\fP std::future that will hold the result - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::launder.3 b/man/std::launder.3 new file mode 100644 index 000000000..9be7425b6 --- /dev/null +++ b/man/std::launder.3 @@ -0,0 +1,138 @@ +.TH std::launder 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::launder \- std::launder + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + constexpr T* launder( T* p ) noexcept; \fI(until C++20)\fP + template< class T > \fI(since C++20)\fP + [[nodiscard]] constexpr T* launder( T* p ) noexcept; + + Provenance fence with respect to p. Returns a pointer to the same memory that p + points to, but where the referent object is assumed to have a distinct lifetime and + dynamic type. + + Formally, given + + * the pointer p represents the address A of a byte in memory + * an object x is located at the address A + * x is within its lifetime + * the type of x is the same as T, ignoring cv-qualifiers at every level + * every byte that would be reachable through the result is reachable through p + (bytes are reachable through a pointer that points to an object y if those bytes + are within the storage of an object z that is pointer-interconvertible with y, + or within the immediately enclosing array of which z is an element). + + Then std::launder(p) returns a value of type T* that points to the object x. + Otherwise, the behavior is undefined. + + The program is ill-formed if T is a function type or (possibly cv-qualified) void. + + std::launder may be used in a core constant expression if and only if the + (converted) value of its argument may be used in place of the function invocation. + In other words, std::launder does not relax restrictions in constant evaluation. + +.SH Notes + + std::launder has no effect on its argument. Its return value must be used to access + the object. Thus, it's always an error to discard the return value. + + Typical uses of std::launder include: + + * Obtaining a pointer to an object created in the storage of an existing object of + the same type, where pointers to the old object cannot be reused (for instance, + because either object is a base class subobject); + * Obtaining a pointer to an object created by placement new from a pointer to an + object providing storage for that object. + + The reachability restriction ensures that std::launder cannot be used to access + bytes not accessible through the original pointer, thereby interfering with the + compiler's escape analysis. + + int x[10]; + auto p = std::launder(reinterpret_cast(&x[0])); // OK + + int x2[2][10]; + auto p2 = std::launder(reinterpret_cast(&x2[0][0])); + // Undefined behavior: x2[1] would be reachable through the resulting pointer to x2[0] + // but is not reachable from the source + + struct X { int a[10]; } x3, x4[2]; // standard layout; assume no padding + auto p3 = std::launder(reinterpret_cast(&x3.a[0])); // OK + auto p4 = std::launder(reinterpret_cast(&x4[0].a[0])); + // Undefined behavior: x4[1] would be reachable through the resulting pointer to x4[0].a + // (which is pointer-interconvertible with x4[0]) but is not reachable from the source + + struct Y { int a[10]; double y; } x5; + auto p5 = std::launder(reinterpret_cast(&x5.a[0])); + // Undefined behavior: x5.y would be reachable through the resulting pointer to x5.a + // but is not reachable from the source + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Base + { + virtual int transmogrify(); + }; + + struct Derived : Base + { + int transmogrify() override + { + new(this) Base; + return 2; + } + }; + + int Base::transmogrify() + { + new(this) Derived; + return 1; + } + + static_assert(sizeof(Derived) == sizeof(Base)); + + int main() + { + // Case 1: the new object failed to be transparently replaceable because + // it is a base subobject but the old object is a complete object. + Base base; + int n = base.transmogrify(); + // int m = base.transmogrify(); // undefined behavior + int m = std::launder(&base)->transmogrify(); // OK + assert(m + n == 3); + + // Case 2: access to a new object whose storage is provided + // by a byte array through a pointer to the array. + struct Y { int z; }; + alignas(Y) std::byte s[sizeof(Y)]; + Y* q = new(&s) Y{2}; + const int f = reinterpret_cast(&s)->z; // Class member access is undefined + // behavior: reinterpret_cast(&s) + // has value "pointer to s" and does + // not point to a Y object + const int g = q->z; // OK + const int h = std::launder(reinterpret_cast(&s))->z; // OK + + [](...){}(f, g, h); // evokes [[maybe_unused]] effect + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + definition of reachable did not consider + LWG 2859 C++17 pointer included + arithmetic from pointer-interconvertible object + LWG 3495 C++17 std::launder might make pointer to an inactive forbidden + member dereferenceable in constant expression diff --git a/man/std::layout_left.3 b/man/std::layout_left.3 new file mode 100644 index 000000000..813454f2e --- /dev/null +++ b/man/std::layout_left.3 @@ -0,0 +1,24 @@ +.TH std::layout_left 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_left \- std::layout_left + +.SH Synopsis + Defined in header + struct layout_left; (since C++23) + + layout_left is a LayoutMappingPolicy and trivial type which provides a layout + mapping where the leftmost extent has stride 1, and strides increase left-to-right + as the product of extents. + + Member class templates + + mapping a layout mapping of layout_left + \fI(public member class template)\fP + +.SH See also + + layout_right row-major multidimensional array layout mapping policy; rightmost + (C++23) extent has stride 1 + \fI(class)\fP + layout_stride a layout mapping policy with user-defined strides + (C++23) \fI(class)\fP diff --git a/man/std::layout_left::mapping.3 b/man/std::layout_left::mapping.3 new file mode 100644 index 000000000..31c53b86e --- /dev/null +++ b/man/std::layout_left::mapping.3 @@ -0,0 +1,87 @@ +.TH std::layout_left::mapping 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_left::mapping \- std::layout_left::mapping + +.SH Synopsis + Defined in header + template< class Extents > (since C++23) + class layout_left::mapping; + + The class template layout_left::mapping controls how multidimensional indices are + mapped in a column-major manner to a one-dimensional value representing the offset. + The mapping has stride 1 at leftmost extent and strides increase left-to-right as + the products of extents. + + Every specialization of mapping is a LayoutMapping and a TriviallyCopyable type + which satisfies regular. + + The program is ill-formed if the size of the multidimensional index space Extents() + is not representable as a value of type Extents::index_type when + Extents::rank_dynamic() is 0. + +.SH Template parameters + + Extents - specifies number of dimensions, their sizes, and which are known at + compile time. Must be a specialization of std::extents. + +.SH Member types + + Member type Definition + extents_type Extents + index_type extents_type::index_type + size_type extents_type::size_type + rank_type extents_type::rank_type + layout_type std::layout_left + +.SH Member objects + + Member name Definition + extents_ (private) The extents of type extents_type. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a new mapping + \fI(public member function)\fP + operator= assigns a mapping + \fI(public member function)\fP +.SH Observers + extents obtains the extents object + \fI(public member function)\fP + required_span_size returns the required size of the mapping + \fI(public member function)\fP + operator() maps multidimensional indices into an offset value + \fI(public member function)\fP + is_unique determines if this mapping is unique (every combination of + \fB[static]\fP indexes maps to a different underlying element) + \fI(public static member function)\fP + is_exhaustive determines if this mapping is exhaustive (every underlying + \fB[static]\fP element can be accessed with some combination of indexes) + \fI(public static member function)\fP + is_strided determines if this mapping is unique (every combination of + \fB[static]\fP indexes maps to a different underlying element) + \fI(public static member function)\fP + is_always_unique determines if this layout mapping is always unique + \fB[static]\fP \fI(public static member function)\fP + is_always_exhaustive determines if this layout mapping is always exhaustive + \fB[static]\fP \fI(public static member function)\fP + is_always_strided determines if this layout mapping is always strided + \fB[static]\fP \fI(public static member function)\fP + stride obtains the stride along the specified dimension + \fI(public member function)\fP + +.SH Non-member functions + + compares this layout mapping with other + operator== mapping + \fI(function template)\fP + submdspan_mapping(std::layout_left::mapping) calculates the mapping and data handle + (C++26) offset used for subdmspan + \fI(public member function)\fP + +.SH See also + + mapping a layout mapping of layout_right + \fI(public member class template of std::layout_right)\fP + mapping a layout mapping of layout_stride + \fI(public member class template of std::layout_stride)\fP diff --git a/man/std::layout_left::mapping::extents.3 b/man/std::layout_left::mapping::extents.3 new file mode 100644 index 000000000..0696acdf2 --- /dev/null +++ b/man/std::layout_left::mapping::extents.3 @@ -0,0 +1,30 @@ +.TH std::layout_left::mapping::extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_left::mapping::extents \- std::layout_left::mapping::extents + +.SH Synopsis + constexpr const extents_type& extents() const noexcept; (since C++23) + + Returns a const reference to the extents object. Equivalent to return extents_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A const reference to the extents. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + obtains the extents object + extents \fI\fI(public member\fP function of\fP + std::mdspan) + +.SH Category: + * Todo no example diff --git a/man/std::layout_right.3 b/man/std::layout_right.3 new file mode 100644 index 000000000..09fdf8cef --- /dev/null +++ b/man/std::layout_right.3 @@ -0,0 +1,27 @@ +.TH std::layout_right 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_right \- std::layout_right + +.SH Synopsis + Defined in header + struct layout_right; (since C++23) + + layout_right is a LayoutMappingPolicy and trivial type which provides a layout + mapping where the rightmost extent has stride 1, and strides increase right-to-left + as the product of extents. + + It is the default layout mapping policy used by std::mdspan if no user-specified + layout is provided. + + Member class templates + + mapping a layout mapping of layout_right + \fI(public member class template)\fP + +.SH See also + + layout_left column-major multidimensional array layout mapping policy; leftmost + (C++23) extent has stride 1 + \fI(class)\fP + layout_stride a layout mapping policy with user-defined strides + (C++23) \fI(class)\fP diff --git a/man/std::layout_right::mapping.3 b/man/std::layout_right::mapping.3 new file mode 100644 index 000000000..7018b4e21 --- /dev/null +++ b/man/std::layout_right::mapping.3 @@ -0,0 +1,87 @@ +.TH std::layout_right::mapping 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_right::mapping \- std::layout_right::mapping + +.SH Synopsis + Defined in header + template< class Extents > (since C++23) + class layout_right::mapping; + + The class template layout_right::mapping controls how multidimensional indices are + mapped in a row-major manner to a one-dimensional value representing the offset. The + mapping has stride 1 at rightmost extent and strides increase right-to-left as the + products of extents. + + Every specialization of mapping is a LayoutMapping and a TriviallyCopyable type + which satisfies regular. + + The program is ill-formed if the size of the multidimensional index space Extents() + is not representable as a value of type Extents::index_type when + Extents::rank_dynamic() is 0. + +.SH Template parameters + + Extents - specifies number of dimensions, their sizes, and which are known at + compile time. Must be a specialization of std::extents. + +.SH Member types + + Member type Definition + extents_type Extents + index_type extents_type::index_type + size_type extents_type::size_type + rank_type extents_type::rank_type + layout_type std::layout_right + +.SH Member objects + + Member name Definition + extents_ (private) The extents of type extents_type. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a new mapping + \fI(public member function)\fP + operator= assigns a mapping + \fI(public member function)\fP +.SH Observers + extents obtains the extents object + \fI(public member function)\fP + required_span_size returns the required size of the mapping + \fI(public member function)\fP + operator() maps multidimensional indices into an offset value + \fI(public member function)\fP + is_unique determines if this mapping is unique (every combination of + \fB[static]\fP indexes maps to a different underlying element) + \fI(public static member function)\fP + is_exhaustive determines if this mapping is exhaustive (every underlying + \fB[static]\fP element can be accessed with some combination of indexes) + \fI(public static member function)\fP + is_strided determines if this mapping is unique (every combination of + \fB[static]\fP indexes maps to a different underlying element) + \fI(public static member function)\fP + is_always_unique determines if this layout mapping is always unique + \fB[static]\fP \fI(public static member function)\fP + is_always_exhaustive determines if this layout mapping is always exhaustive + \fB[static]\fP \fI(public static member function)\fP + is_always_strided determines if this layout mapping is always strided + \fB[static]\fP \fI(public static member function)\fP + stride obtains the stride along the specified dimension + \fI(public member function)\fP + +.SH Non-member functions + + compares this layout mapping with + operator== other mapping + \fI(function template)\fP + submdspan_mapping(std::layout_right::mapping) calculates the mapping and data handle + (C++26) offset used for subdmspan + \fI(public member function)\fP + +.SH See also + + mapping a layout mapping of layout_left + \fI(public member class template of std::layout_left)\fP + mapping a layout mapping of layout_stride + \fI(public member class template of std::layout_stride)\fP diff --git a/man/std::layout_right::mapping::extents.3 b/man/std::layout_right::mapping::extents.3 new file mode 100644 index 000000000..c6697c889 --- /dev/null +++ b/man/std::layout_right::mapping::extents.3 @@ -0,0 +1,30 @@ +.TH std::layout_right::mapping::extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_right::mapping::extents \- std::layout_right::mapping::extents + +.SH Synopsis + constexpr const extents_type& extents() const noexcept; (since C++23) + + Returns a const reference to the extents object. Equivalent to return extents_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A const reference to the extents. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + obtains the extents object + extents \fI\fI(public member\fP function of\fP + std::mdspan) + +.SH Category: + * Todo no example diff --git a/man/std::layout_stride.3 b/man/std::layout_stride.3 new file mode 100644 index 000000000..cb683b025 --- /dev/null +++ b/man/std::layout_stride.3 @@ -0,0 +1,24 @@ +.TH std::layout_stride 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_stride \- std::layout_stride + +.SH Synopsis + Defined in header + struct layout_stride; (since C++23) + + layout_stride is a LayoutMappingPolicy and trivial type which provides a layout + mapping where the strides are user-defined. + + Member class templates + + mapping a layout mapping of layout_stride + \fI(public member class template)\fP + +.SH See also + + layout_left column-major multidimensional array layout mapping policy; leftmost + (C++23) extent has stride 1 + \fI(class)\fP + layout_right row-major multidimensional array layout mapping policy; rightmost + (C++23) extent has stride 1 + \fI(class)\fP diff --git a/man/std::layout_stride::mapping.3 b/man/std::layout_stride::mapping.3 new file mode 100644 index 000000000..1ca3de5c2 --- /dev/null +++ b/man/std::layout_stride::mapping.3 @@ -0,0 +1,95 @@ +.TH std::layout_stride::mapping 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_stride::mapping \- std::layout_stride::mapping + +.SH Synopsis + Defined in header + template< class Extents > (since C++23) + class layout_stride::mapping; + + The class template layout_stride::mapping controls how multidimensional indices are + mapped with user-defined strides to a one-dimensional value representing the offset. + + Every specialization of mapping is a LayoutMapping and a TriviallyCopyable type + which satisfies regular. + + The program is ill-formed if the size of the multidimensional index space Extents() + is not representable as a value of type Extents::index_type when + Extents::rank_dynamic() is 0. + +.SH Template parameters + + Extents - specifies number of dimensions, their sizes, and which are known at + compile time. Must be a specialization of std::extents. + +.SH Member types + + Member type Definition + extents_type Extents + index_type extents_type::index_type + size_type extents_type::size_type + rank_type extents_type::rank_type + layout_type std::layout_stride + +.SH Member constants + + Member Definition + constexpr rank_type rank_ (private) extents_type::rank() + \fB[static]\fP (exposition-only static member constant*) + +.SH Member objects + + Member name Definition + extents_ (private) The extents of type extents_type. + (exposition-only member object*) + strides_ (private) The strides of type std::array. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a new mapping + \fI(public member function)\fP + operator= assigns a mapping + \fI(public member function)\fP +.SH Observers + extents obtains the extents object + \fI(public member function)\fP + strides obtains the array of strides + \fI(public member function)\fP + required_span_size returns the required size of the mapping + \fI(public member function)\fP + operator() maps multidimensional indices into an offset value + \fI(public member function)\fP + is_unique determines if this mapping is unique (every combination of + \fB[static]\fP indexes maps to a different underlying element) + \fI(public static member function)\fP + determines if this mapping is exhaustive (every underlying + is_exhaustive element can be accessed with some combination of indexes) + \fI(public member function)\fP + is_strided determines if this mapping is unique (every combination of + \fB[static]\fP indexes maps to a different underlying element) + \fI(public static member function)\fP + is_always_unique determines if this layout mapping is always unique + \fB[static]\fP \fI(public static member function)\fP + is_always_exhaustive determines if this layout mapping is always exhaustive + \fB[static]\fP \fI(public static member function)\fP + is_always_strided determines if this layout mapping is always strided + \fB[static]\fP \fI(public static member function)\fP + stride obtains the stride along the specified dimension + \fI(public member function)\fP + +.SH Non-member functions + + compares this layout mapping with + operator== other mapping + \fI(function template)\fP + submdspan_mapping(std::layout_stride::mapping) calculates the mapping and data + (C++26) handle offset used for subdmspan + \fI(public member function)\fP + +.SH See also + + mapping a layout mapping of layout_left + \fI(public member class template of std::layout_left)\fP + mapping a layout mapping of layout_right + \fI(public member class template of std::layout_right)\fP diff --git a/man/std::layout_stride::mapping::extents.3 b/man/std::layout_stride::mapping::extents.3 new file mode 100644 index 000000000..95dbcf672 --- /dev/null +++ b/man/std::layout_stride::mapping::extents.3 @@ -0,0 +1,30 @@ +.TH std::layout_stride::mapping::extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_stride::mapping::extents \- std::layout_stride::mapping::extents + +.SH Synopsis + constexpr const extents_type& extents() const noexcept; (since C++23) + + Returns a const reference to the extents object. Equivalent to return extents_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A const reference to the extents. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + obtains the extents object + extents \fI\fI(public member\fP function of\fP + std::mdspan) + +.SH Category: + * Todo no example diff --git a/man/std::layout_stride::mapping::strides.3 b/man/std::layout_stride::mapping::strides.3 new file mode 100644 index 000000000..00dd1c07b --- /dev/null +++ b/man/std::layout_stride::mapping::strides.3 @@ -0,0 +1,32 @@ +.TH std::layout_stride::mapping::strides 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::layout_stride::mapping::strides \- std::layout_stride::mapping::strides + +.SH Synopsis + constexpr std::array strides() const noexcept; (since C++23) + + Returns an array of strides of the mapping. Equivalent to return strides_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Array of strides + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + stride obtains the stride along the specified dimension + \fI(public member function)\fP + obtains the stride along the specified dimension + stride \fI\fI(public member\fP function of\fP + std::mdspan) + +.SH Category: + * Todo no example diff --git a/man/std::lcm.3 b/man/std::lcm.3 new file mode 100644 index 000000000..6a5a4285f --- /dev/null +++ b/man/std::lcm.3 @@ -0,0 +1,79 @@ +.TH std::lcm 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lcm \- std::lcm + +.SH Synopsis + Defined in header + template< class M, class N > \fI(since C++17)\fP + constexpr std::common_type_t lcm( M m, N n ); + + Computes the least common multiple of the integers m and n. + + If either M or N is not an integer type, or if either is (possibly cv-qualified) + bool, the program is ill-formed. + + The behavior is undefined if |m|, |n|, or the least common multiple of |m| and |n| + is not representable as a value of type std::common_type_t. + +.SH Parameters + + m, n - integer values + +.SH Return value + + If either m or n is zero, returns zero. Otherwise, returns the least common multiple + of |m| and |n|. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_gcd_lcm 201606L \fI(C++17)\fP std::gcd, std::lcm + +.SH Example + + +// Run this code + + #include + #include + + #define OUT(...) std::cout << #__VA_ARGS__ << " = " << __VA_ARGS__ << '\\n' + + constexpr auto lcm(auto x, auto... xs) + { + return ((x = std::lcm(x, xs)), ...); + } + + int main() + { + constexpr int p{2 * 2 * 3}; + constexpr int q{2 * 3 * 3}; + static_assert(2 * 2 * 3 * 3 == std::lcm(p, q)); + static_assert(225 == std::lcm(45, 75)); + + static_assert(std::lcm( 6, 10) == 30); + static_assert(std::lcm( 6, -10) == 30); + static_assert(std::lcm(-6, -10) == 30); + + static_assert(std::lcm( 24, 0) == 0); + static_assert(std::lcm(-24, 0) == 0); + + OUT(lcm(2 * 3, 3 * 4, 4 * 5)); + OUT(lcm(2 * 3 * 4, 3 * 4 * 5, 4 * 5 * 6)); + OUT(lcm(2 * 3 * 4, 3 * 4 * 5, 4 * 5 * 6, 5 * 6 * 7)); + } + +.SH Output: + + lcm(2 * 3, 3 * 4, 4 * 5) = 60 + lcm(2 * 3 * 4, 3 * 4 * 5, 4 * 5 * 6) = 120 + lcm(2 * 3 * 4, 3 * 4 * 5, 4 * 5 * 6, 5 * 6 * 7) = 840 + +.SH See also + + gcd computes the greatest common divisor of two integers + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::lconv.3 b/man/std::lconv.3 index afc918dd7..c6e8b1dad 100644 --- a/man/std::lconv.3 +++ b/man/std::lconv.3 @@ -1,4 +1,7 @@ -.TH std::lconv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lconv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lconv \- std::lconv + .SH Synopsis Defined in header struct lconv; @@ -43,8 +46,8 @@ the number of digits after the decimal point to display in a char frac_digits monetary quantity \fI(public member object)\fP - 1 if currency_symbol is placed before non-negative value, 0 - char p_cs_precedes if after + 1 if currency_symbol is placed before non-negative value, 0 if + char p_cs_precedes after \fI(public member object)\fP 1 if currency_symbol is placed before negative value, 0 if char n_cs_precedes after @@ -70,23 +73,23 @@ the number of digits after the decimal point to display in char int_frac_digits an international monetary quantity \fI(public member object)\fP - 1 if currency_symbol is placed before non-negative - char int_p_cs_precedes international monetary value, 0 if after + char int_p_cs_precedes 1 if int_curr_symbol is placed before non-negative + \fI(C++11)\fP international monetary value, 0 if after \fI(public member object)\fP - 1 if currency_symbol is placed before negative international - char int_n_cs_precedes monetary value, 0 if after + char int_n_cs_precedes 1 if int_curr_symboll is placed before negative + \fI(C++11)\fP international monetary value, 0 if after \fI(public member object)\fP - indicates the separation of currency_symbol, positive_sign, - char int_p_sep_by_space and the non-negative international monetary value + char int_p_sep_by_space indicates the separation of int_curr_symbol, positive_sign, + \fI(C++11)\fP and the non-negative international monetary value \fI(public member object)\fP - indicates the separation of currency_symbol, negative_sign, - char int_n_sep_by_space and the negative international monetary value + char int_n_sep_by_space indicates the separation of int_curr_symbol, negative_sign, + \fI(C++11)\fP and the negative international monetary value \fI(public member object)\fP - indicates the position of positive_sign in a non-negative - char int_p_sign_posn international monetary value + char int_p_sign_posn indicates the position of positive_sign in a non-negative + \fI(C++11)\fP international monetary value \fI(public member object)\fP - indicates the position of negative_sign in a negative - char int_n_sign_posn international monetary value + char int_n_sign_posn indicates the position of negative_sign in a negative + \fI(C++11)\fP international monetary value \fI(public member object)\fP The characters of the C-strings pointed to by grouping and mon_grouping are @@ -114,13 +117,13 @@ .SH Example - - + + // Run this code #include #include - + int main() { std::setlocale(LC_ALL, "ja_JP.UTF-8"); @@ -136,11 +139,11 @@ .SH See also localeconv queries numeric and monetary formatting details of the current locale - \fI(function)\fP + \fI(function)\fP numpunct defines numeric punctuation rules - \fI(class template)\fP + \fI(class template)\fP defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP C documentation for lconv diff --git a/man/std::ldexp,std::ldexpf,std::ldexpl.3 b/man/std::ldexp,std::ldexpf,std::ldexpl.3 new file mode 100644 index 000000000..d10616032 --- /dev/null +++ b/man/std::ldexp,std::ldexpf,std::ldexpl.3 @@ -0,0 +1,157 @@ +.TH std::ldexp,std::ldexpf,std::ldexpl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ldexp,std::ldexpf,std::ldexpl \- std::ldexp,std::ldexpf,std::ldexpl + +.SH Synopsis + Defined in header + float ldexp ( float num, int exp ); + + double ldexp ( double num, int exp ); (until C++23) + + long double ldexp ( long double num, int exp ); + constexpr /* floating-point-type */ + ldexp ( /* floating-point-type */ num, (since C++23) + int exp ); \fB(1)\fP + float ldexpf( float num, int exp ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double ldexpl( long double num, int exp ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + double ldexp ( Integer num, int exp ); (constexpr since C++23) + + 1-3) Multiplies a floating point value num by the number 2 raised to the exp power. + The library provides overloads of std::ldexp for all cv-unqualified floating-point + types as the type of the parameter num. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + exp - integer value + +.SH Return value + + If no errors occur, num multiplied by 2 to the power of exp (num×2exp + ) is returned. + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned. + + If a range error due to underflow occurs, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * Unless a range error occurs, FE_INEXACT is never raised (the result is exact). + * Unless a range error occurs, the current rounding mode is ignored. + * If num is ±0, it is returned, unmodified. + * If num is ±∞, it is returned, unmodified. + * If exp is 0, then num is returned, unmodified. + * If num is NaN, NaN is returned. + +.SH Notes + + On binary systems (where FLT_RADIX is 2), std::ldexp is equivalent to std::scalbn. + + The function std::ldexp ("load exponent"), together with its dual, std::frexp, can + be used to manipulate the representation of a floating-point number without direct + bit manipulations. + + On many implementations, std::ldexp is less efficient than multiplication or + division by a power of two using arithmetic operators. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::ldexp(num, exp) has the same effect as std::ldexp(static_cast(num), + exp). + + For exponentiation of 2 by a floating point exponent, std::exp2 can be used. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout + << "ldexp(5, 3) = 5 * 8 = " << std::ldexp(5, 3) << '\\n' + << "ldexp(7, -4) = 7 / 16 = " << std::ldexp(7, -4) << '\\n' + << "ldexp(1, -1074) = " << std::ldexp(1, -1074) + << " (minimum positive subnormal float64_t)\\n" + << "ldexp(nextafter(1,0), 1024) = " + << std::ldexp(std::nextafter(1,0), 1024) + << " (largest finite float64_t)\\n"; + + // special values + std::cout << "ldexp(-0, 10) = " << std::ldexp(-0.0, 10) << '\\n' + << "ldexp(-Inf, -1) = " << std::ldexp(-INFINITY, -1) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + errno = 0; + const double inf = std::ldexp(1, 1024); + const bool is_range_error = errno == ERANGE; + + std::cout << "ldexp(1, 1024) = " << inf << '\\n'; + if (is_range_error) + std::cout << " errno == ERANGE: " << std::strerror(ERANGE) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Possible output: + + ldexp(5, 3) = 5 * 8 = 40 + ldexp(7, -4) = 7 / 16 = 0.4375 + ldexp(1, -1074) = 4.94066e-324 (minimum positive subnormal float64_t) + ldexp(nextafter(1,0), 1024) = 1.79769e+308 (largest finite float64_t) + ldexp(-0, 10) = -0 + ldexp(-Inf, -1) = -inf + ldexp(1, 1024) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + frexp + frexpf decomposes a number into significand and base-2 exponent + frexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + scalbn + scalbnf + scalbnl + scalbln + scalblnf + scalblnl multiplies a number by FLT_RADIX raised to a power + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp2 + exp2f + exp2l returns 2 raised to the given power (\\({\\small 2^x}\\)2^x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + ldexp diff --git a/man/std::ldexp.3 b/man/std::ldexp.3 deleted file mode 100644 index c72a089b6..000000000 --- a/man/std::ldexp.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH std::ldexp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float ldexp( float arg, int exp ); - double ldexp( double arg, int exp ); - long double ldexp( long double arg, int exp ); - double ldexp( Integral arg, int exp ); \fI(since C++11)\fP - - Multiplies an floating point value arg by 2 raised to power exp. - -.SH Parameters - - arg - floating point value - exp - integer value - -.SH Return value - - returns arg × 2^exp - - If the result is too large for the underlying type, range error occurs and HUGE_VAL - is returned. - -.SH See also - - frexp decomposes a number into significand and a power of 2 - \fI(function)\fP - scalbn - scalbln multiplies a number by FLT_RADIX raised to a power - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP diff --git a/man/std::left,std::right,std::internal.3 b/man/std::left,std::right,std::internal.3 index d6d0c31a1..0debebc1f 100644 --- a/man/std::left,std::right,std::internal.3 +++ b/man/std::left,std::right,std::internal.3 @@ -1,24 +1,27 @@ -.TH std::left,std::right,std::internal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::left,std::right,std::internal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::left,std::right,std::internal \- std::left,std::right,std::internal + .SH Synopsis Defined in header std::ios_base& left( std::ios_base& str ); \fB(1)\fP std::ios_base& right( std::ios_base& str ); \fB(2)\fP std::ios_base& internal( std::ios_base& str ); \fB(3)\fP - Modifies the default positioning of the fill characters. left and right apply to any - output, internal applies to integer, floating-point, and monetary output. Has no - effect on input. - - 1) sets the adjustfield of the stream str to left as if by calling - str.setf(std::ios_base::left, std::ios_base::adjustfield) + Modifies the positioning of the fill characters in an output stream. left and right + apply to any type being output, internal applies to integer, floating-point, and + monetary output. Has no effect on input. - 2) sets the adjustfield of the stream str to right as if by calling - str.setf(std::ios_base::right, std::ios_base::adjustfield) + 1) Sets the adjustfield of the stream str to left as if by calling + str.setf(std::ios_base::left, std::ios_base::adjustfield). + 2) Sets the adjustfield of the stream str to right as if by calling + str.setf(std::ios_base::right, std::ios_base::adjustfield). + 3) Sets the adjustfield of the stream str to internal as if by calling + str.setf(std::ios_base::internal, std::ios_base::adjustfield). - 3) sets the adjustfield of the stream str to internal as if by calling - str.setf(std::ios_base::internal, std::ios_base::adjustfield) + The initial default for standard streams is equivalent to right. - This is an I/O manipulator, it may be called with an expression such as out << + This is an I/O manipulator. It may be called with an expression such as out << std::left for any out of type std::basic_ostream or with an expression such as in >> std::left for any in of type std::basic_istream. @@ -28,31 +31,37 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code - #include #include + #include #include - + int main() { std::cout.imbue(std::locale("en_US.utf8")); - std::cout << "Left fill:\\n" << std::left << std::setfill('*') + + std::cout << "Default positioning:\\n" << std::setfill('*') << std::setw(12) << -1.23 << '\\n' << std::setw(12) << std::hex << std::showbase << 42 << '\\n' << std::setw(12) << std::put_money(123, true) << "\\n\\n"; - - std::cout << "Internal fill:\\n" << std::internal + + std::cout << "Left positioning:\\n" << std::left << std::setw(12) << -1.23 << '\\n' << std::setw(12) << 42 << '\\n' << std::setw(12) << std::put_money(123, true) << "\\n\\n"; - - std::cout << "Right fill:\\n" << std::right + + std::cout << "Internal positioning:\\n" << std::internal + << std::setw(12) << -1.23 << '\\n' + << std::setw(12) << 42 << '\\n' + << std::setw(12) << std::put_money(123, true) << "\\n\\n"; + + std::cout << "Right positioning:\\n" << std::right << std::setw(12) << -1.23 << '\\n' << std::setw(12) << 42 << '\\n' << std::setw(12) << std::put_money(123, true) << '\\n'; @@ -60,24 +69,31 @@ .SH Output: - Left fill: + Default positioning: + *******-1.23 + ********0x2a + ***USD *1.23 + + Left positioning: -1.23******* 0x2a******** USD *1.23*** - - Internal fill: + + Internal positioning: -*******1.23 0x********2a USD ****1.23 - - Right fill: + + Right positioning: *******-1.23 ********0x2a ***USD *1.23 .SH See also - setw changes the width of the next input/output field - \fI(function)\fP - setfill changes the fill character - \fI(function template)\fP + setw changes the width of the next input/output field + \fI(function)\fP + setfill changes the fill character + \fI(function template)\fP + showbase controls whether prefix is used to indicate numeric base + noshowbase \fI(function)\fP diff --git a/man/std::legendre,std::legendref,std::legendrel.3 b/man/std::legendre,std::legendref,std::legendrel.3 new file mode 100644 index 000000000..d8d576822 --- /dev/null +++ b/man/std::legendre,std::legendref,std::legendrel.3 @@ -0,0 +1,131 @@ +.TH std::legendre,std::legendref,std::legendrel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::legendre,std::legendref,std::legendrel \- std::legendre,std::legendref,std::legendrel + +.SH Synopsis + double legendre( unsigned int n, double x ); + + double legendre( unsigned int n, float x ); + double legendre( unsigned int n, long double x ); \fB(1)\fP + float legendref( unsigned int n, float x ); + + long double legendrel( unsigned int n, long double x ); + double legendre( unsigned int n, IntegralType x ); \fB(2)\fP + + 1) Computes the unassociated Legendre polynomials of the degree n and argument x. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, legendre is only guaranteed to be available in if + __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least + 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any + standard library headers. + +.SH Parameters + + n - the degree of the polynomial + x - the argument, a value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the order-n unassociated Legendre polynomial of x, that + is + + 1 + 2n + n! + + dn + dxn + + (x2 + - 1)n + , is returned. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * The function is not required to be defined for |x| > 1. + * If n is greater or equal than 128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The first few Legendre polynomials are: + + * legendre(0, x) = 1. + * legendre(1, x) = x. + * legendre(2, x) = + + 1 + 2 + + (3x2 + - 1). + * legendre(3, x) = + + 1 + 2 + + (5x3 + - 3x). + * legendre(4, x) = + + 1 + 8 + + (35x4 + - 30x2 + + 3). + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + double P3(double x) + { + return 0.5 * (5 * std::pow(x, 3) - 3 * x); + } + + double P4(double x) + { + return 0.125 * (35 * std::pow(x, 4) - 30 * x * x + 3); + } + + int main() + { + // spot-checks + std::cout << std::legendre(3, 0.25) << '=' << P3(0.25) << '\\n' + << std::legendre(4, 0.25) << '=' << P4(0.25) << '\\n'; + } + +.SH Output: + + -0.335938=-0.335938 + 0.157715=0.157715 + +.SH See also + + laguerre Laguerre polynomials + laguerref \fI(function)\fP + laguerrel + hermite Hermite polynomials + hermitef \fI(function)\fP + hermitel + +.SH External links + + Weisstein, Eric W. "Legendre Polynomial." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::length_error.3 b/man/std::length_error.3 index 724d45662..df10ca950 100644 --- a/man/std::length_error.3 +++ b/man/std::length_error.3 @@ -1,50 +1,115 @@ -.TH std::length_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::length_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::length_error \- std::length_error + .SH Synopsis Defined in header class length_error; - Defines a type of object to be thrown as exception. It reports errors that are - consequence of attempt to exceed implementation defined length limits for some - object. + Defines a type of object to be thrown as exception. It reports errors that result + from attempts to exceed implementation defined length limits for some object. + + This exception is thrown by member functions of std::basic_string and + std::vector::reserve. std-length error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP - - + constructor constructs a new length_error object with the given message + \fI(public member function)\fP + operator= replaces the length_error object + \fI(public member function)\fP - std::length_error::length_error +std::length_error::length_error - explicit length_error( const std::string& what_arg ); \fB(1)\fP - explicit length_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP + length_error( const std::string& what_arg ); \fB(1)\fP + length_error( const char* what_arg ); \fB(2)\fP + length_error( const length_error& other ); \fB(3)\fP (noexcept since C++11) - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::length_error + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::length_error is not permitted to throw exceptions, this message + is typically stored internally as a separately-allocated reference-counted string. + This is also why there is no constructor taking std::string&&: it would have to copy + the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::length_error::operator= + + length_error& operator=( const length_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::length_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::logic_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const char* added + was missing + the explanatory strings of they are the same as that + LWG 471 C++98 std::length_error's of the + copies were implementation-defined original std::length_error + object .SH See also resize changes the number of characters stored - \fI(public member function of std::basic_string)\fP + \fI(public member function of std::basic_string)\fP diff --git a/man/std::lerp.3 b/man/std::lerp.3 new file mode 100644 index 000000000..27937853b --- /dev/null +++ b/man/std::lerp.3 @@ -0,0 +1,161 @@ +.TH std::lerp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lerp \- std::lerp + +.SH Synopsis + Defined in header + constexpr float lerp( float a, float b, float t ) + noexcept; + + constexpr double lerp( double a, double b, double t ) \fI(since C++20)\fP + noexcept; (until C++23) + constexpr long double lerp( long double a, long double b, + + long double t ) noexcept; + constexpr /* floating-point-type */ + + lerp( /* floating-point-type */ a, (since C++23) + /* floating-point-type */ b, \fB(1)\fP + + /* floating-point-type */ t ) noexcept; + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2, class + Arithmetic3 > + + constexpr /* common-floating-point-type */ (A) \fI(since C++20)\fP + + lerp( Arithmetic1 a, Arithmetic2 b, Arithmetic3 t ) + noexcept; + + 1) Computes the linear interpolation between a and b, if the parameter t is inside + [0, 1) (the linear extrapolation otherwise), i.e. the result of \\(a+t(b−a)\\)a+t(b−a) + with accounting for floating-point calculation imprecision. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameters a, b and t. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + a, b, t - floating-point or integer values + +.SH Return value + + \\(a + t(b − a)\\)a + t(b − a) + + When std::isfinite(a) && std::isfinite(b) is true, the following properties are + guaranteed: + + * If t == 0, the result is equal to a. + * If t == 1, the result is equal to b. + * If t >= 0 && t <= 1, the result is finite. + * If std::isfinite(t) && a == b, the result is equal to a. + * If std::isfinite(t) || (b - a != 0 && std::isinf(t)), the result is not NaN. + + Let CMP(x, y) be 1 if x > y, -1 if x < y, and 0 otherwise. For any t1 and t2, the + product of + + * CMP(std::lerp(a, b, t2), std::lerp(a, b, t1)), + * CMP(t2, t1), and + * CMP(b, a) + + is non-negative. (That is, std::lerp is monotonic.) + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1, second argument + num2 and third argument num3: + + * If num1, num2 or num3 has type long double, then std::lerp(num1, + num2, num3) has the same effect as std::lerp(static_cast(num1), + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 and/or num3 has type double or an integer + type, then std::lerp(num1, num2, num3) has the same effect as + std::lerp(static_cast(num1), (until C++23) + static_cast(num2), + static_cast(num3)). + * Otherwise, if num1, num2 or num3 has type float, then + std::lerp(num1, num2, num3) has the same effect as + std::lerp(static_cast(num1), + static_cast(num2), + static_cast(num3)). + If num1, num2 and num3 have arithmetic types, then std::lerp(num1, + num2, num3) has the same effect as std::lerp(static_cast(num1), + static_cast(num2), + static_cast(num3)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point (since C++23) + conversion subrank among the types of num1, num2 and num3, arguments + of integer type are considered to have the same floating-point + conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + + Feature-test macro Value Std Feature + __cpp_lib_interpolate 201902L (C++20) std::lerp, std::midpoint + +.SH Example + + +// Run this code + + #include + #include + #include + + float naive_lerp(float a, float b, float t) + { + return a + t * (b - a); + } + + int main() + { + std::cout << std::boolalpha; + + const float a = 1e8f, b = 1.0f; + const float midpoint = std::lerp(a, b, 0.5f); + + std::cout << "a = " << a << ", " << "b = " << b << '\\n' + << "midpoint = " << midpoint << '\\n'; + + std::cout << "std::lerp is exact: " + << (a == std::lerp(a, b, 0.0f)) << ' ' + << (b == std::lerp(a, b, 1.0f)) << '\\n'; + + std::cout << "naive_lerp is exact: " + << (a == naive_lerp(a, b, 0.0f)) << ' ' + << (b == naive_lerp(a, b, 1.0f)) << '\\n'; + + std::cout << "std::lerp(a, b, 1.0f) = " << std::lerp(a, b, 1.0f) << '\\n' + << "naive_lerp(a, b, 1.0f) = " << naive_lerp(a, b, 1.0f) << '\\n'; + + assert(not std::isnan(std::lerp(a, b, INFINITY))); // lerp here can be -inf + + std::cout << "Extrapolation demo, given std::lerp(5, 10, t):\\n"; + for (auto t{-2.0}; t <= 2.0; t += 0.5) + std::cout << std::lerp(5.0, 10.0, t) << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + a = 1e+08, b = 1 + midpoint = 5e+07 + std::lerp is exact?: true true + naive_lerp is exact?: true false + std::lerp(a, b, 1.0f) = 1 + naive_lerp(a, b, 1.0f) = 0 + Extrapolation demo, given std::lerp(5, 10, t): + -5 -2.5 0 2.5 5 7.5 10 12.5 15 + +.SH See also + + midpoint midpoint between two numbers or pointers + (C++20) \fI(function template)\fP diff --git a/man/std::less.3 b/man/std::less.3 index 3ae6a7048..e9d3e451b 100644 --- a/man/std::less.3 +++ b/man/std::less.3 @@ -1,46 +1,29 @@ -.TH std::less 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::less 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::less \- std::less + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct less; - template< class T = void > \fI(since C++14)\fP - struct less; - - Function object for performing comparisons. Unless specialized, invokes operator< on - type T. - -.SH Specializations - - If the built-in operator< does not provide total order for pointers, a partial - specialization of std::less for pointer types is provided, which guarantees total - order. + template<> \fI(since C++14)\fP + class less; - The standard library provides a specialization of std::less when T is - not specified, which leaves the parameter types and return type to be + std::less is a specialization of std::less with parameter and return type deduced. - \fI(since C++14)\fP - function object implementing x < y deducing argument and - less return types - \fI(class template specialization)\fP - -.SH Member types - - type definition - result_type bool - first_argument_type T - second_argument_type T .SH Member functions - operator() checks if the first argument is less than the second + operator() tests if lhs compares less than rhs \fI(public member function)\fP - std::less::operator() +std::less::operator() + + template< class T, class U > + + constexpr auto operator()( T&& lhs, U&& rhs ) const - bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + -> decltype(std::forward(lhs) < std::forward(rhs)); - Checks whether lhs is less than rhs. + Returns the result of std::forward(lhs) < std::forward(rhs). .SH Parameters @@ -48,46 +31,45 @@ .SH Return value - true if lhs < rhs, false otherwise. + std::forward(lhs) < std::forward(rhs). -.SH Exceptions - - \fI(none)\fP + If a built-in operator comparing pointers is called, the result is consistent with + the implementation-defined strict total order over pointers. -.SH Possible implementation +.SH Exceptions - constexpr bool operator()(const T &lhs, const T &rhs) const - { - return lhs < rhs; - } + May throw implementation-defined exceptions. .SH Example - + // Run this code + #include #include - #include - - template > - bool f(A a, B b, U u = U()) + + constexpr bool strictly_negative(int lhs) { - return u(a, b); + return std::less<>()(lhs, 0); } - + int main() { - std::cout << std::boolalpha; - std::cout << f(5, 20) << '\\n'; - std::cout << f(100, 10) << '\\n'; + constexpr signed low = 010; + constexpr unsigned high = 10; + std::less<> less{}; + static_assert(less(low, high)); + + constexpr static auto arr = {0, -1, -2, -3, -4, -5}; + static_assert(!std::all_of(arr.begin(), arr.end(), strictly_negative)); + static_assert(std::all_of(arr.begin() + 1, arr.end(), strictly_negative)); } -.SH Output: - - true - false + Defect reports -.SH See also + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - owner_less provides mixed-type owner-based ordering of shared and weak pointers - \fI(C++11)\fP \fI(class template)\fP + DR Applied to Behavior as published Correct behavior + LWG 2562 C++98 the pointer total order might be guaranteed to be consistent + inconsistent diff --git a/man/std::less.3 b/man/std::less.3 deleted file mode 100644 index 4e16be853..000000000 --- a/man/std::less.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH std::less 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class less; - - std::less<> is a specialization of std::less with parameter and return type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() tests if the lhs compares less than rhs - \fI(public member function)\fP - - std::less<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) < std::forward(rhs)); - - Returns the result of lhs < rhs. - -.SH Parameters - - lhs, rhs - values to compare - -.SH Return value - - The result of lhs < rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::less_equal.3 b/man/std::less_equal.3 index 0207f9e61..1fb1a88dd 100644 --- a/man/std::less_equal.3 +++ b/man/std::less_equal.3 @@ -1,46 +1,29 @@ -.TH std::less_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::less_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::less_equal \- std::less_equal + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct less_equal; - template< class T = void > \fI(since C++14)\fP - struct less_equal; - - Function object for performing comparisons. Unless specialized, invokes operator<= - on type T. - -.SH Specializations - - If the built-in operator<= does not provide total order for pointers, a partial - specialization of std::less_equal for pointer types is provided, which guarantees - total order. - - The standard library provides a specialization of std::less_equal when - T is not specified, which leaves the parameter types and return type - to be deduced. - \fI(since C++14)\fP - function object implementing x <= y deducing argument - less_equal and return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class less_equal; -.SH Member types - - type definition - result_type bool - first_argument_type T - second_argument_type T + std::less_equal is a specialization of std::less_equal with parameter and + return type deduced. .SH Member functions - operator() checks if the first argument is less than or equal to the second + operator() tests if lhs compares less or equal than rhs \fI(public member function)\fP - std::less_equal::operator() +std::less_equal::operator() + + template< class T, class U > - bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const - Checks if lhs is less than or equal to rhs. + -> decltype(std::forward(lhs) <= std::forward(rhs)); + + Returns the result of std::forward(lhs) <= std::forward(rhs). .SH Parameters @@ -48,15 +31,46 @@ .SH Return value - true if lhs <= rhs, false otherwise. + std::forward(lhs) <= std::forward(rhs). + + If a built-in operator comparing pointers is called, the result is consistent with + the implementation-defined strict total order over pointers. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + + constexpr bool strictly_not_positive(int lhs) + { + return std::less_equal<>()(lhs, 0); + } + + int main() + { + constexpr int low = 0, high = 8; + std::less_equal<> less_equal{}; + static_assert(less_equal(low, high)); + static_assert(less_equal(low, low)); + + static constexpr auto arr = {1, 0, -1, -2, -3, -4}; + static_assert(!std::all_of(arr.begin(), arr.end(), strictly_not_positive)); + static_assert(std::all_of(arr.begin() + 1, arr.end(), strictly_not_positive)); + } + + Defect reports -.SH Possible implementation + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - constexpr bool operator()(const T &lhs, const T &rhs) const - { - return lhs <= rhs; - } + DR Applied to Behavior as published Correct behavior + LWG 2562 C++98 the pointer total order might be guaranteed to be consistent + inconsistent diff --git a/man/std::less_equal.3 b/man/std::less_equal.3 deleted file mode 100644 index dfa7c6098..000000000 --- a/man/std::less_equal.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::less_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class less_equal; - - std::less_equal<> is a specialization of std::less_equal with parameter and return - type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() tests if the lhs compares less or equal than rhs - \fI(public member function)\fP - - std::less_equal<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) <= std::forward(rhs)); - - Returns the result of lhs <= rhs. - -.SH Parameters - - lhs, rhs - values to compare - -.SH Return value - - The result of lhs <= rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::lexicographical_compare.3 b/man/std::lexicographical_compare.3 index deb2844bd..bcb68f6b0 100644 --- a/man/std::lexicographical_compare.3 +++ b/man/std::lexicographical_compare.3 @@ -1,23 +1,60 @@ -.TH std::lexicographical_compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lexicographical_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lexicographical_compare \- std::lexicographical_compare + .SH Synopsis Defined in header template< class InputIt1, class InputIt2 > - bool lexicographical_compare( InputIt1 first1, InputIt1 last1, \fB(1)\fP + bool lexicographical_compare( InputIt1 first1, InputIt1 + last1, \fB(1)\fP (constexpr since C++20) + + InputIt2 first2, InputIt2 + last2 ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + bool lexicographical_compare( ExecutionPolicy&& policy, + ForwardIt1 first1, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 last1, - InputIt2 first2, InputIt2 last2 ); - template< class InputIt1, class InputIt2, class Compare > + ForwardIt2 first2, + ForwardIt2 last2 ); + template< class InputIt1, class InputIt2, class Compare + > + + bool lexicographical_compare( InputIt1 first1, InputIt1 + last1, \fB(3)\fP (constexpr since C++20) + InputIt2 first2, InputIt2 + last2, + + Compare comp ); + template< class ExecutionPolicy, - bool lexicographical_compare( InputIt1 first1, InputIt1 last1, \fB(2)\fP - InputIt2 first2, InputIt2 last2, + class ForwardIt1, class ForwardIt2, class + Compare > + bool lexicographical_compare( ExecutionPolicy&& policy, + ForwardIt1 first1, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 last1, + ForwardIt2 first2, + ForwardIt2 last2, Compare comp ); Checks if the first range [first1, last1) is lexicographically less than the second - range [first2, last2). The first version uses operator< to compare the elements, the - second version uses the given comparison function comp. + range [first2, last2). - Lexicographical comparison is a operation with the following properties: + 1) Elements are compared using operator<. + 3) Elements are compared using the given binary comparison function comp. + 2,4) Same as (1,3), but executed according to policy. These overloads participate in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + Lexicographical comparison is an operation with the following properties: * Two ranges are compared element by element. * The first mismatching element defines which range is lexicographically less or @@ -33,91 +70,128 @@ first1, last1 - the first range of elements to examine first2, last2 - the second range of elements to examine + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less than the second. + requirements of Compare) which returns true if the first argument is + less than the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. + converted to both Type1 and Type2. .SH Type requirements - - InputIt1, InputIt2 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of Compare. .SH Return value - true if the first range is lexicographically less than the second. + true if the first range is lexicographically less than the second, otherwise false. .SH Complexity - At most 2·min(N1, N2) applications of the comparison operation, where N1 = - std::distance(first1, last1) and N2 = std::distance(first2, last2). + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize 2\\min(N_1,N_2)\\)2min( + 1,N + 2) comparisons using operator<. + 3,4) At most \\(\\scriptsize 2\\min(N_1,N_2)\\)2min(N + 1,N + 2) applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + lexicographical_compare \fB(1)\fP template bool lexicographical_compare(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2) { - for ( ; (first1 != last1) && (first2 != last2); first1++, first2++ ) { - if (*first1 < *first2) return true; - if (*first2 < *first1) return false; + for (; (first1 != last1) && (first2 != last2); ++first1, (void) ++first2) + { + if (*first1 < *first2) + return true; + if (*first2 < *first1) + return false; } + return (first1 == last1) && (first2 != last2); } -.SH Second version + lexicographical_compare \fB(3)\fP template bool lexicographical_compare(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - Compare comp) + InputIt2 first2, InputIt2 last2, Compare comp) { - for ( ; (first1 != last1) && (first2 != last2); first1++, first2++ ) { - if (comp(*first1, *first2)) return true; - if (comp(*first2, *first1)) return false; + for (; (first1 != last1) && (first2 != last2); ++first1, (void) ++first2) + { + if (comp(*first1, *first2)) + return true; + if (comp(*first2, *first1)) + return false; } + return (first1 == last1) && (first2 != last2); } .SH Example - + // Run this code #include #include + #include #include - #include - #include - + + void print(const std::vector& v, auto suffix) + { + for (char c : v) + std::cout << c << ' '; + std::cout << suffix; + } + int main() { - std::vector v1 {'a', 'b', 'c', 'd'}; - std::vector v2 {'a', 'b', 'c', 'd'}; - - std::srand(std::time(0)); - while (!std::lexicographical_compare(v1.begin(), v1.end(), - v2.begin(), v2.end())) { - for (auto c : v1) std::cout << c << ' '; - std::cout << ">= "; - for (auto c : v2) std::cout << c << ' '; - std::cout << '\\n'; - - std::random_shuffle(v1.begin(), v1.end()); - std::random_shuffle(v2.begin(), v2.end()); + std::vector v1{'a', 'b', 'c', 'd'}; + std::vector v2{'a', 'b', 'c', 'd'}; + + for (std::mt19937 g{std::random_device{}()}; + !std::lexicographical_compare(v1.begin(), v1.end(), + v2.begin(), v2.end());) + { + print(v1, ">= "); + print(v2, '\\n'); + + std::shuffle(v1.begin(), v1.end(), g); + std::shuffle(v2.begin(), v2.end(), g); } - - for (auto c : v1) std::cout << c << ' '; - std::cout << "< "; - for (auto c : v2) std::cout << c << ' '; - std::cout << '\\n'; + + print(v1, "< "); + print(v2, '\\n'); } .SH Possible output: @@ -125,4 +199,28 @@ a b c d >= a b c d d a b c >= c b d a b d a c >= a d c b - a c d b < c d a b + a c d b < c d a b + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + at most \\(\\scriptsize \\min(N_1,N_2)\\)min(N + 1,N + LWG 142 C++98 2) comparisons were allowed, but that doubled the limit + is not possible (equivalence is determined by + 2 comparisons) + LWG 1205 C++98 the results of lexicographical comparisons made clear + involving empty ranges were unclear + +.SH See also + + equal determines if two sets of elements are the same + \fI(function template)\fP + lexicographical_compare_three_way compares two ranges using three-way comparison + (C++20) \fI(function template)\fP + ranges::lexicographical_compare returns true if one range is lexicographically + (C++20) less than another + (niebloid) diff --git a/man/std::lexicographical_compare_three_way.3 b/man/std::lexicographical_compare_three_way.3 new file mode 100644 index 000000000..9a0485bcf --- /dev/null +++ b/man/std::lexicographical_compare_three_way.3 @@ -0,0 +1,154 @@ +.TH std::lexicographical_compare_three_way 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lexicographical_compare_three_way \- std::lexicographical_compare_three_way + +.SH Synopsis + Defined in header + template< class InputIt1, class InputIt2, class Cmp > + + constexpr auto lexicographical_compare_three_way + ( InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 \fB(1)\fP \fI(since C++20)\fP + last2, + + Cmp comp ) -> decltype(comp(*first1, *first2)); + template< class InputIt1, class InputIt2 > + + constexpr auto lexicographical_compare_three_way \fB(2)\fP \fI(since C++20)\fP + + ( InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 + last2 ); + + Lexicographically compares two ranges [first1, last1) and [first2, last2) using + three-way comparison and produces a result of the strongest applicable comparison + category type. + + 1) Returns the order between the first non-equivalent pair of elements according to + comp in both ranges if any, otherwise (if one ranges is equivalent to the prefix of + another according to comp), returns the order between the length of both ranges. + 2) Equivalent to return std::lexicographical_compare_three_way( + first1, last1, first2, last2, std::compare_three_way()); + + If the return type is not one of the three comparison category types, the program is + ill-formed: + + * std::strong_ordering + * std::weak_ordering + * std::partial_ordering + +.SH Parameters + + first1, last1 - the first range of elements to examine + first2, last2 - the second range of elements to examine + comp - a function object +.SH Type requirements + - + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + +.SH Return value + + The value of a comparison category type specified above. + +.SH Complexity + + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1) At most \\(\\scriptsize \\min(N_1,N_2)\\)min( + 1,N + 2) applications of comp. + 2) At most \\(\\scriptsize \\min(N_1,N_2)\\)min(N + 1,N + 2) applications of std::compare_three_way(). + +.SH Possible implementation + + template + constexpr auto lexicographical_compare_three_way(I1 f1, I1 l1, I2 f2, I2 l2, Cmp comp) + -> decltype(comp(*f1, *f2)) + { + using ret_t = decltype(comp(*f1, *f2)); + static_assert(std::disjunction_v< + std::is_same, + std::is_same, + std::is_same>, + "The return type must be a comparison category type."); + + bool exhaust1 = (f1 == l1); + bool exhaust2 = (f2 == l2); + for (; !exhaust1 && !exhaust2; exhaust1 = (++f1 == l1), exhaust2 = (++f2 == l2)) + if (auto c = comp(*f1, *f2); c != 0) + return c; + + return !exhaust1 ? std::strong_ordering::greater: + !exhaust2 ? std::strong_ordering::less: + std::strong_ordering::equal; + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + using namespace std::literals; + + void show_result(std::string_view s1, std::string_view s2, std::strong_ordering o) + { + std::cout << std::quoted(s1) << " is "; + std::is_lt(o) ? std::cout << "less than ": + std::is_gt(o) ? std::cout << "greater than ": + std::cout << "equal to "; + std::cout << std::quoted(s2) << '\\n'; + } + + std::strong_ordering cmp_icase(unsigned char x, unsigned char y) + { + return std::toupper(x) <=> std::toupper(y); + }; + + int main() + { + for (const auto& [s1, s2] : + { + std::pair{"one"sv, "ONE"sv}, {"two"sv, "four"sv}, {"three"sv, "two"sv} + }) + { + const auto res = std::lexicographical_compare_three_way( + s1.cbegin(), s1.cend(), s2.cbegin(), s2.cend(), cmp_icase); + show_result(s1, s2, res); + } + } + +.SH Output: + + "one" is equal to "ONE" + "two" is greater than "four" + "three" is less than "two" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3410 C++20 extraneous comparisons between such requirement removed + iterators were required + +.SH See also + + returns true if one range is lexicographically less + lexicographical_compare than another + \fI(function template)\fP + compare_three_way constrained function object implementing x <=> y + (C++20) \fI(class)\fP + ranges::lexicographical_compare returns true if one range is lexicographically less + (C++20) than another + (niebloid) diff --git a/man/std::lgamma,std::lgammaf,std::lgammal.3 b/man/std::lgamma,std::lgammaf,std::lgammal.3 new file mode 100644 index 000000000..bfc0dea8c --- /dev/null +++ b/man/std::lgamma,std::lgammaf,std::lgammal.3 @@ -0,0 +1,146 @@ +.TH std::lgamma,std::lgammaf,std::lgammal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lgamma,std::lgammaf,std::lgammal \- std::lgamma,std::lgammaf,std::lgammal + +.SH Synopsis + Defined in header + float lgamma ( float num ); + + double lgamma ( double num ); (until C++23) + + long double lgamma ( long double num ); + /* floating-point-type */ (since C++23) + lgamma ( /* floating-point-type */ num (constexpr since C++26) + ); \fB(1)\fP + float lgammaf( float num ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double lgammal( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double lgamma ( Integer num ); + + 1-3) Computes the natural logarithm of the absolute value of the gamma function of + num. + The library provides overloads of std::lgamma for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the value of the logarithm of the gamma function of num, that is + \\(\\log_{e}|{\\int_0^\\infty t^{num-1} e^{-t} \\mathsf{d}t}|\\)log + e|∫∞ + 0tnum-1 + e^-t dt|, is returned. + + If a pole error occurs, +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL is returned. + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If num is zero or is an integer less than zero, a pole error may occur. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is 1, +0 is returned. + * If the argument is 2, +0 is returned. + * If the argument is ±0, +∞ is returned and FE_DIVBYZERO is raised. + * If the argument is a negative integer, +∞ is returned and FE_DIVBYZERO is + raised. + * If the argument is ±∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + If num is a natural number, std::lgamma(num) is the logarithm of the factorial of + num - 1. + + The POSIX version of lgamma is not thread-safe: each execution of the function + stores the sign of the gamma function of num in the static external variable + signgam. Some implementations provide lgamma_r, which takes a pointer to + user-provided storage for singgam as the second parameter, and is thread-safe. + + There is a non-standard function named gamma in various implementations, but its + definition is inconsistent. For example, glibc and 4.2BSD version of gamma executes + lgamma, but 4.4BSD version of gamma executes tgamma. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::lgamma(num) has the same effect as std::lgamma(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + const double pi = std::acos(-1); // or std::numbers::pi since C++20 + + int main() + { + std::cout << "lgamma(10) = " << std::lgamma(10) + << ", log(9!) = " << std::log(std::tgamma(10)) + << ", exp(lgamma(10)) = " << std::exp(std::lgamma(10)) << '\\n' + << "lgamma(0.5) = " << std::lgamma(0.5) + << ", log(sqrt(pi)) = " << std::log(std::sqrt(pi)) << '\\n'; + + // special values + std::cout << "lgamma(1) = " << std::lgamma(1) << '\\n' + << "lgamma(+Inf) = " << std::lgamma(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "lgamma(0) = " << std::lgamma(0) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Output: + + lgamma\fB(10)\fP = 12.8018, log(9!) = 12.8018, exp(lgamma(10)) = 362880 + lgamma(0.5) = 0.572365, log(sqrt(pi)) = 0.572365 + lgamma\fB(1)\fP = 0 + lgamma(+Inf) = inf + lgamma\fB(0)\fP = inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised + +.SH See also + + tgamma + tgammaf + tgammal gamma function + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + lgamma + +.SH External links + + Weisstein, Eric W. "Log Gamma Function." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::lgamma.3 b/man/std::lgamma.3 deleted file mode 100644 index a9979025c..000000000 --- a/man/std::lgamma.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH std::lgamma 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float lgamma( float arg ); \fI(since C++11)\fP - double lgamma( double arg ); \fI(since C++11)\fP - long double lgamma( long double arg ); \fI(since C++11)\fP - double lgamma( Integral arg ); \fI(since C++11)\fP - - Computes the natural logarithm of the absolute value of the gamma function of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - The value of the logarithm of the gamma function of arg, that is log - e|∫∞ - 0targ-1 - e^-t dt|. - - If arg is a natural number, std::lgamma(arg) is the logarithm of the factorial of - arg-1. - -.SH Exceptions - - If arg is zero or a negative integer, pole error may occur and FE_INVALID or - FE_DIVBYZERO may be raised. - - If arg is too large, range error may occur and FE_OVERFLOW may be raised. - -.SH Notes - - POSIX specification additionally requires that each execution of lgamma stores the - sign of the gamma function of arg in the external variable signgam. - -.SH See also - - tgamma gamma function - \fI(C++11)\fP \fI(function)\fP - C documentation for - lgamma - -.SH External links - - Weisstein, Eric W. "Log Gamma Function." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::linear_congruential_engine.3 b/man/std::linear_congruential_engine.3 index 06f505e06..ab1b350e9 100644 --- a/man/std::linear_congruential_engine.3 +++ b/man/std::linear_congruential_engine.3 @@ -1,4 +1,7 @@ -.TH std::linear_congruential_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine \- std::linear_congruential_engine + .SH Synopsis Defined in header template< @@ -11,64 +14,114 @@ > class linear_congruential_engine; linear_congruential_engine is a random number engine based on Linear congruential - generator (LCG). A LCG has a state that consists of single integer. + generator (LCG). + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + UIntType - this is not one of unsigned short, unsigned int, unsigned long, or + unsigned long long. + a - the multiplier term + c - the increment term + m - the modulus term + + When m is not zero, if a >= m or c >= m is true, the program is ill-formed. + + Generator properties + + The size of the states of linear_congruential_engine is 1, each of them consists of + a single integer. + + The actual modulus \\(m_0\\)m + 0 is defined as follows: + + * If m is not zero, \\(m_0\\)m + 0 is m. + * If m is zero, \\(m_0\\)m + 0 is the value of std::numeric_limits::max() plus 1 (which means + \\(m_0\\)m + 0 need not be representable as result_type). + + The transition algorithm of linear_congruential_engine is \\(TA(x_i) = (a \\cdot x_i + + c)\\mod m_0\\)TA(x + i) = (a·x + i+c) mod m + 0. + + The generation algorithm of linear_congruential_engine is \\(GA(x_i) = (a \\cdot x_i + + c)\\mod m_0\\)GA(x + i) = (a·x + i+c) mod m + 0. + + The pseudo-random number generated with the current state is also the successor + state. - The transition algorithm of the LCG function is x - i+1 ← (ax - i+c) mod m. + Predefined specializations - The following typedefs define the random number engine with two commonly used + The following specializations define the random number engine with two commonly used parameter sets: Defined in header Type Definition - std::linear_congruential_engine - minstd_rand0 + std::linear_congruential_engine + \fI(C++11)\fP Discovered in 1969 by Lewis, Goodman and Miller, adopted as "Minimal - standard" in 1988 by Park and Miller - std::linear_congruential_engine - minstd_rand - Newer "Minimum standard", recommended by Park, Miller, and Stockmeyer + standard" in 1988 by Park and Miller + std::linear_congruential_engine + \fI(C++11)\fP Newer "Minimum standard", recommended by Park, Miller, and Stockmeyer in 1993 -.SH Member types + Nested types - Member type Definition - result_type The integral type generated by the engine. Results are undefined if this - is not an unsigned integral type. + Type Definition + result_type UIntType + + Data members + + constexpr UIntType multiplier a + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType increment c + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType modulus m + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType default_seed 1u + \fB[static]\fP \fI(public static member constant)\fP .SH Member functions .SH Construction and Seeding - constructor constructs the engine - \fI(public member function)\fP - seed sets the current state of the engine - \fI(public member function)\fP + constructor constructs the engine + \fI(C++11)\fP \fI(public member function)\fP + seed sets the current state of the engine + \fI(C++11)\fP \fI(public member function)\fP .SH Generation - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP - discard advances the engine's state by a specified amount - \fI(public member function)\fP + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP + discard advances the engine's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP .SH Non-member functions - operator== compares the internal states of two pseudo-random number engines - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number engine - operator>> \fI(function)\fP + operator== compares the internal states of two pseudo-random number + operator!= engines + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> engine + \fI(C++11)\fP \fI(function template)\fP -.SH Member objects +.SH Example - constexpr UIntType multiplier the multiplier term (a). - \fB[static]\fP \fI(public static member constant)\fP - constexpr UIntType increment the increment term (c). - \fB[static]\fP \fI(public static member constant)\fP - constexpr UIntType modulus the modulus term (m). - \fB[static]\fP \fI(public static member constant)\fP - constexpr UIntType default_seed the default seed \fB(1)\fP. - \fB[static]\fP \fI(public static member constant)\fP + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::linear_congruential_engine::discard.3 b/man/std::linear_congruential_engine::discard.3 index e90891cbe..ee04117c4 100644 --- a/man/std::linear_congruential_engine::discard.3 +++ b/man/std::linear_congruential_engine::discard.3 @@ -1,9 +1,12 @@ -.TH std::linear_congruential_engine::discard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine::discard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine::discard \- std::linear_congruential_engine::discard + .SH Synopsis void discard( unsigned long long z ); \fI(since C++11)\fP Advances the internal state by z times. Equivalent to calling operator() z times and - discarding the result + discarding the result. .SH Parameters @@ -15,13 +18,15 @@ .SH Complexity - This section is incomplete + No worse than the complexity of z consecutive calls to operator(). -.SH See also +.SH Notes - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP + For some engines, "fast jump" algorithms are known, which advance the state by many + steps (order of millions) without calculating intermediate state transitions, + although not necessarily in constant time. -.SH Category: +.SH See also - * Todo without reason + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::linear_congruential_engine::linear_congruential_engine.3 b/man/std::linear_congruential_engine::linear_congruential_engine.3 index 96263c32e..cb4110da1 100644 --- a/man/std::linear_congruential_engine::linear_congruential_engine.3 +++ b/man/std::linear_congruential_engine::linear_congruential_engine.3 @@ -1,28 +1,58 @@ -.TH std::linear_congruential_engine::linear_congruential_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine::linear_congruential_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine::linear_congruential_engine \- std::linear_congruential_engine::linear_congruential_engine + .SH Synopsis - explicit linear_congruential_engine( result_type value = \fB(1)\fP \fI(since C++11)\fP - default_seed ); - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP - explicit linear_congruential_engine( Sseq& s ); + linear_congruential_engine() : \fB(1)\fP \fI(since C++11)\fP + linear_congruential_engine(default_seed) {} + explicit linear_congruential_engine( result_type value ); \fB(2)\fP \fI(since C++11)\fP + template< class SeedSeq > \fB(3)\fP \fI(since C++11)\fP + explicit linear_congruential_engine( SeedSeq& seq ); + linear_congruential_engine( const linear_congruential_engine& \fI(since C++11)\fP + other ); \fB(4)\fP (implicitly + declared) Constructs the pseudo-random number engine. - This section is incomplete + 1) The default constructor. + 2) Constructs the engine with a seed value value. The engine's initial state is + determined as follows: + * If c % m == 0 and value % m == 0 are both true, the state is 1. + * Otherwise, the state is value % m. + 3) Constructs the engine with a seed sequence seq. Given std::size_t(std::log2(m) / + 32) + 1 as k, the engine's initial state is determined as follows: + 1. Creates an invented array object a of length k + 3. + 2. Calls seq.generate(a + 0, a + k + 3). + 3. Let S be \\((\\sum^{k-1}_{j=0} a_{j+3} \\cdot 2^{32j}) \\mod m\\)(∑k-1 + j=0 a + j+3·232j + ) mod m. + 4. If both c % m == 0 and S == 0 are true, sets the engine's state to 1. Otherwise, + sets the engine’s state to S. + This overload participates in overload resolution only if SeedSeq meets the + requirements of SeedSequence. + 4) The copy constructor. Upon construction, *this == other is true. .SH Parameters value - seed value to use in the initialization of the internal state - s - seed sequence to use in the initialization of the internal state + seq - seed sequence to use in the initialization of the internal state .SH Complexity - This section is incomplete + 1,2) Constant. + 3) Same as the complexity of the seq.generate call. + 4) Constant. -.SH See also + Defect reports - seed sets the current state of the engine - \fI(public member function)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also - * Todo without reason + seed sets the current state of the engine + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::linear_congruential_engine::max.3 b/man/std::linear_congruential_engine::max.3 index e1f7e6797..402cb0a77 100644 --- a/man/std::linear_congruential_engine::max.3 +++ b/man/std::linear_congruential_engine::max.3 @@ -1,8 +1,12 @@ -.TH std::linear_congruential_engine::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine::max \- std::linear_congruential_engine::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP - Returns the maximum value potentially generated by the random-number engine. + Returns the maximum value potentially generated by the random-number engine. This + value is one less than modulus. .SH Parameters @@ -14,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::linear_congruential_engine::min.3 b/man/std::linear_congruential_engine::min.3 index 8cd731fe4..a2931ed11 100644 --- a/man/std::linear_congruential_engine::min.3 +++ b/man/std::linear_congruential_engine::min.3 @@ -1,8 +1,12 @@ -.TH std::linear_congruential_engine::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine::min \- std::linear_congruential_engine::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP - Returns the minimum value potentially generated by the random-number engine. + Returns the minimum value potentially generated by the random-number engine. This + value is equal to 1u if increment is 0u, and is equal to 0u otherwise. .SH Parameters @@ -10,13 +14,13 @@ .SH Return value - The maximum potentially generated value. + The minimum potentially generated value. .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::linear_congruential_engine::operator().3 b/man/std::linear_congruential_engine::operator().3 index f5b4f11f1..93eb9a712 100644 --- a/man/std::linear_congruential_engine::operator().3 +++ b/man/std::linear_congruential_engine::operator().3 @@ -1,4 +1,7 @@ -.TH std::linear_congruential_engine::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine::operator() \- std::linear_congruential_engine::operator() + .SH Synopsis result_type operator()(); \fI(since C++11)\fP @@ -22,8 +25,7 @@ .SH See also discard advances the engine's state by a specified amount - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo without reason diff --git a/man/std::linear_congruential_engine::seed.3 b/man/std::linear_congruential_engine::seed.3 index aefacddac..9a3c72aca 100644 --- a/man/std::linear_congruential_engine::seed.3 +++ b/man/std::linear_congruential_engine::seed.3 @@ -1,26 +1,29 @@ -.TH std::linear_congruential_engine::seed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::linear_congruential_engine::seed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::linear_congruential_engine::seed \- std::linear_congruential_engine::seed + .SH Synopsis void seed( result_type value = default_seed ); \fB(1)\fP \fI(since C++11)\fP - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP - void seed( Sseq& seq ); + template< class SeedSeq > \fB(2)\fP \fI(since C++11)\fP + void seed( SeedSeq& seq ); - Reinitializes the internal state of the random-number engine using new seed value. + Sets the state of the random-number engine. - This section is incomplete + 1) Right after the state is set, *this == std::linear_congruential_engine(value) is + true. + 2) Right after the state is set, *this == std::linear_congruential_engine(seq) is + true. .SH Parameters - value - seed value to use in the initialization of the internal state - seq - seed sequence to use in the initialization of the internal state + value - seed value to use to set the state + seq - seed sequence to use to set the state .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Complexity - This section is incomplete - -.SH Category: - - * Todo without reason + 1) Same as std::linear_congruential_engine(value). + 2) Same as std::linear_congruential_engine(seq). diff --git a/man/std::list.3 b/man/std::list.3 index ec8064441..6aee00652 100644 --- a/man/std::list.3 +++ b/man/std::list.3 @@ -1,22 +1,31 @@ -.TH std::list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list \- std::list + .SH Synopsis Defined in header template< - class T, + class T, \fB(1)\fP class Allocator = std::allocator > class list; + namespace pmr { + + template< class T > \fB(2)\fP \fI(since C++17)\fP + using list = std::list>; + + } std::list is a container that supports constant time insertion and removal of elements from anywhere in the container. Fast random access is not supported. It is - usually implemented as double-linked list. Compared to std::forward_list this + usually implemented as a doubly-linked list. Compared to std::forward_list this container provides bidirectional iteration capability while being less space efficient. - Addition, removal and moving the elements within the list or across several lists - does not invalidate the iterators. An iterator is invalidated only when the - corresponding element is deleted. + Adding, removing and moving the elements within the list or across several lists + does not invalidate the iterators or references. An iterator is invalidated only + when the corresponding element is deleted. std::list meets the requirements of Container, AllocatorAwareContainer, SequenceContainer and ReversibleContainer. @@ -25,119 +34,216 @@ The type of the elements. - T must meet the requirements of CopyAssignable and \fI(until C++11)\fP - CopyConstructible. - The requirements that are imposed on the elements depend - T - on the actual operations performed on the container. - Generally, it is required that element type meets the \fI(since C++11)\fP - requirements of MoveConstructible and MoveAssignable, but - many member functions impose stricter requirements. + T must meet the requirements of CopyConstructible. T must meet the (until + requirements of CopyAssignable if list::operator= or list::assign C++11) + is instantiated with T. + The requirements that are imposed on the elements depend on the (since + actual operations performed on the container. Generally, it is C++11) + required that element type is a complete type and meets the (until + requirements of Erasable, but many member functions impose C++17) + stricter requirements. + The requirements that are imposed on the elements depend on the + actual operations performed on the container. Generally, it is + T - required that element type meets the requirements of Erasable, but + many member functions impose stricter requirements. This container + (but not its members) can be instantiated with an incomplete + element type if the allocator satisfies the allocator completeness (since + requirements. C++17) + + Feature-test macro Value Std Feature + Minimal + __cpp_lib_incomplete_container_elements 201505L \fI(C++17)\fP incomplete + type + support - - Allocator - An allocator that is used to acquire memory to store the elements. The - type must meet the requirements of Allocator. + + An allocator that is used to acquire/release memory and to + construct/destroy the elements in that memory. The type must meet the + requirements of Allocator. + Allocator - The behavior is undefined + \fI(until C++20)\fP + The program is ill-formed + \fI(since C++20)\fP if Allocator::value_type is not the same as T. .SH Member types Member type Definition - value_type T - allocator_type Allocator - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP + value_type T + allocator_type Allocator + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator BidirectionalIterator - const_iterator Constant bidirectional iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + + + iterator LegacyBidirectionalIterator to value_type + const_iterator LegacyBidirectionalIterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator .SH Member functions constructor constructs the list - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the list - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + assign_range assigns a range of values to the container + (C++23) \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access front access the first element - \fI(public member function)\fP + \fI(public member function)\fP back access the last element - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP + \fI(C++11)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + \fI(C++11)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP erase erases elements - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP - emplace_back constructs elements in-place at the end - \fI(C++11)\fP \fI(public member function)\fP + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP pop_back removes the last element - \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - emplace_front constructs elements in-place at the beginning - \fI(C++11)\fP \fI(public member function)\fP + \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(C++11)\fP \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP pop_front removes the first element - \fI(public member function)\fP + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Operations merge merges two sorted lists - \fI(public member function)\fP + \fI(public member function)\fP splice moves elements from another list - \fI(public member function)\fP + \fI(public member function)\fP remove removes elements satisfying specific criteria - remove_if \fI(public member function)\fP + remove_if \fI(public member function)\fP reverse reverses the order of the elements - \fI(public member function)\fP + \fI(public member function)\fP unique removes consecutive duplicate elements - \fI(public member function)\fP + \fI(public member function)\fP sort sorts the elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the list - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two lists + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::list) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase(std::list) erases all elements satisfying specific criteria + erase_if(std::list) \fI(function template)\fP + (C++20) + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // Create a list containing integers + std::list l = {7, 5, 16, 8}; + + // Add an integer to the front of the list + l.push_front(25); + // Add an integer to the back of the list + l.push_back(13); + + // Insert an integer before 16 by searching + auto it = std::find(l.begin(), l.end(), 16); + if (it != l.end()) + l.insert(it, 42); + + // Print out the list + std::cout << "l = { "; + for (int n : l) + std::cout << n << ", "; + std::cout << "};\\n"; + } + +.SH Output: + + l = { 25, 7, 5, 42, 16, 8, 13, }; + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was not required to be + LWG 230 C++98 CopyConstructible T is also required to + (an element of type T might not be be CopyConstructible + able to be constructed) + LWG 276 C++98 T was always required to be only required if operator= or + CopyAssignable assign is instantiated with T diff --git a/man/std::list::append_range.3 b/man/std::list::append_range.3 new file mode 100644 index 000000000..2a2424a7a --- /dev/null +++ b/man/std::list::append_range.3 @@ -0,0 +1,74 @@ +.TH std::list::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::append_range \- std::list::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void append_range( R&& rg ); + + Inserts copies of elements from the range rg before end(), in non-reversing order. + + No iterators or references are invalidated. + + Each iterator in rg is dereferenced exactly once. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into list from *ranges::begin(rg). Otherwise, the + behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in size of rg. The number of calls to the constructor of T is exactly equal + to the std::ranges::size(rg)). + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto head = std::list{1, 2, 3, 4}; + const auto tail = std::vector{-5, -6, -7}; + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.insert(head.end(), tail.cbegin(), tail.cend()); + #endif + assert(std::ranges::equal(head, std::list{1, 2, 3, 4, -5, -6, -7})); + } + +.SH See also + + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::list::assign.3 b/man/std::list::assign.3 index 1871f8d4c..e82b9d53a 100644 --- a/man/std::list::assign.3 +++ b/man/std::list::assign.3 @@ -1,4 +1,7 @@ -.TH std::list::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::assign \- std::list::assign + .SH Synopsis void assign( size_type count, const T& value ); \fB(1)\fP template< class InputIt > \fB(2)\fP @@ -7,58 +10,84 @@ Replaces the contents of the container. - 1) Replaces the contents with count copies of value value - 2) Replaces the contents with copies of those in the range [first, last) + 1) Replaces the contents with count copies of value value. + 2) Replaces the contents with copies of those in the range [first, last). The + behavior is undefined if either argument is an iterator into *this. + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + 3) Replaces the contents with the elements from the initializer list ilist. + All iterators, pointers and references to the elements of the container are + invalidated. + .SH Parameters count - the new size of the container value - the value to initialize elements of the container with first, last - the range to copy the elements from ilist - initializer list to copy the values from -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. .SH Complexity - 1) Linear in count - 2) Linear in distance between first and last - 3) Linear in ilist.size() + 1) Linear in count. + 2) Linear in distance between first and last. + 3) Linear in ilist.size(). .SH Example The following code uses assign to add several characters to a std::list: - + // Run this code #include #include - + #include + int main() { std::list characters; - + + auto print_list = [&]() + { + for (char c : characters) + std::cout << c << ' '; + std::cout << '\\n'; + }; + characters.assign(5, 'a'); - - for (char c : characters) { - std::cout << c << '\\n'; - } - - return 0; + print_list(); + + const std::string extra(6, 'b'); + characters.assign(extra.begin(), extra.end()); + print_list(); + + characters.assign({'C', '+', '+', '1', '1'}); + print_list(); } .SH Output: - a - a - a - a - a + a a a a a + b b b b b b + C + + 1 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the replacement operation was defined as + LWG 320 C++98 erasing all removed the definition + existing elements followed by inserting + the given elements .SH See also constructor constructs the list - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::assign_range.3 b/man/std::list::assign_range.3 new file mode 100644 index 000000000..55aa4d120 --- /dev/null +++ b/man/std::list::assign_range.3 @@ -0,0 +1,69 @@ +.TH std::list::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::assign_range \- std::list::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void assign_range( R&& rg ); + + Replaces elements in the container with a copy of each element in rg. + + Invalidates all iterators, pointers and references to the elements. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + rg - an input_range with reference type convertible to the element type + of the container +.SH Type requirements + - + std::assignable_from> must be modeled. Otherwise, + the program is ill-formed. + - + T must be EmplaceConstructible into the container from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto source = std::vector{2, 7, 1}; + auto destination = std::list{3, 1, 4}; + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.cbegin(), source.cend()); + #endif + assert(std::ranges::equal(source, destination)); + } + +.SH See also + + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP + assign assigns values to the container + \fI(public member function)\fP diff --git a/man/std::list::back.3 b/man/std::list::back.3 index a501d8687..e65abe043 100644 --- a/man/std::list::back.3 +++ b/man/std::list::back.3 @@ -1,11 +1,14 @@ -.TH std::list::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::back \- std::list::back + .SH Synopsis - reference back(); - const_reference back() const; + reference back(); \fB(1)\fP + const_reference back() const; \fB(2)\fP - Returns reference to the last element in the container. + Returns a reference to the last element in the container. - Calling back on an empty container is undefined. + Calling back on an empty container causes undefined behavior. .SH Parameters @@ -21,32 +24,32 @@ .SH Notes - For a container c, the expression return c.back(); is equivalent to { auto tmp = - c.end(); --tmp; return *tmp; } + For a non-empty container c, the expression c.back() is equivalent to + *std::prev(c.end()). .SH Example The following code uses back to display the last element of a std::list: - + // Run this code #include #include - + int main() { - std::list letters {'o', 'm', 'g', 'w', 't', 'f'}; - if (!letters.empty()) { - std::cout << "The last character is: " << letters.back() << '\\n'; - } + std::list letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The last character is '" << letters.back() << "'.\\n"; } .SH Output: - The last character is f + The last character is 'f'. .SH See also front access the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::begin,std::list::cbegin.3 b/man/std::list::begin,std::list::cbegin.3 index 4e5563b09..3c84bc94a 100644 --- a/man/std::list::begin,std::list::cbegin.3 +++ b/man/std::list::begin,std::list::cbegin.3 @@ -1,12 +1,15 @@ -.TH std::list::begin,std::list::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::begin,std::list::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::begin,std::list::cbegin \- std::list::begin,std::list::cbegin + .SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin(); \fB(1)\fP (noexcept since C++11) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the list. - If the container is empty, the returned iterator will be equal to end(). + If the list is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,20 +19,62 @@ .SH Return value - Iterator to the first element + Iterator to the first element. + +.SH Complexity -.SH Exceptions + Constant. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +.SH Notes -.SH Complexity + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::list nums{1, 2, 4, 8, 16}; + std::list fruits{"orange", "apple", "raspberry"}; + std::list empty; + + // Print list. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the list nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the list fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "list 'empty' is indeed empty.\\n"; + } + +.SH Output: - Constant + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + list 'empty' is indeed empty. .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::list::clear.3 b/man/std::list::clear.3 index f2e31e468..c219dc7f2 100644 --- a/man/std::list::clear.3 +++ b/man/std::list::clear.3 @@ -1,11 +1,14 @@ -.TH std::list::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::clear \- std::list::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterator remains valid. .SH Parameters @@ -15,22 +18,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::list& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::list container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + + Defect reports - Linear in the size of the container. + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - clear is defined in terms of erase, which has linear complexity. \fI(until C++11)\fP - complexity of clear is omitted \fI(since C++11)\fP - clear has linear complexity for sequence containers. \fI(since C++14)\fP + DR Applied to Behavior as published Correct behavior + LWG 2231 C++11 complexity guarantee was mistakenly complexity reaffirmed as + omitted in C++11 linear .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::emplace.3 b/man/std::list::emplace.3 index e0215cf88..ddcb1f0c3 100644 --- a/man/std::list::emplace.3 +++ b/man/std::list::emplace.3 @@ -1,19 +1,30 @@ -.TH std::list::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::emplace \- std::list::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace( const_iterator pos, Args&&... args ); - Inserts a new element into the container directly before pos. The element is - constructed in-place, i.e. no copy or move operations are performed. The constructor - of the element is called with the arguments std::forward(args).... The element - type must be EmplaceConstructible. + Inserts a new element into the container directly before pos. + + The element is constructed through std::allocator_traits::construct, which uses + placement-new to construct the element in-place at a location provided by the + container. + + The arguments args... are forwarded to the constructor as + std::forward(args).... args... may directly or indirectly refer to a value in + the container. No iterators or references are invalidated. .SH Parameters - pos - iterator before which the new element will be constructed - args - arguments to forward to the constructor of the element + pos - iterator before which the new element will be constructed + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of EmplaceConstructible. .SH Return value @@ -28,7 +39,89 @@ If an exception is thrown (e.g. by the constructor), the container is left unmodified, as if this function was never called \fI(strong exception guarantee)\fP. +.SH Example + + +// Run this code + + #include + #include + #include + + struct A + { + std::string s; + + A(std::string str) : s(std::move(str)) { std::cout << " constructed\\n"; } + + A(const A& o) : s(o.s) { std::cout << " copy constructed\\n"; } + + A(A&& o) : s(std::move(o.s)) { std::cout << " move constructed\\n"; } + + A& operator=(const A& other) + { + s = other.s; + std::cout << " copy assigned\\n"; + return *this; + } + + A& operator=(A&& other) + { + s = std::move(other.s); + std::cout << " move assigned\\n"; + return *this; + } + }; + + int main() + { + std::list container; + + std::cout << "construct 2 times A:\\n"; + A two { "two" }; + A three { "three" }; + + std::cout << "emplace:\\n"; + container.emplace(container.end(), "one"); + + std::cout << "emplace with A&:\\n"; + container.emplace(container.end(), two); + + std::cout << "emplace with A&&:\\n"; + container.emplace(container.end(), std::move(three)); + + std::cout << "content:\\n"; + for (const auto& obj : container) + std::cout << ' ' << obj.s; + std::cout << '\\n'; + } + +.SH Output: + + construct 2 times A: + constructed + constructed + emplace: + constructed + emplace with A&: + copy constructed + emplace with A&&: + move constructed + content: + one two three + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2164 C++11 it was not clear whether the arguments can clarified + refer to the container + .SH See also - insert inserts elements - \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::list::emplace_back.3 b/man/std::list::emplace_back.3 index f6defd449..ceb582fd7 100644 --- a/man/std::list::emplace_back.3 +++ b/man/std::list::emplace_back.3 @@ -1,21 +1,31 @@ -.TH std::list::emplace_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::emplace_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::emplace_back \- std::list::emplace_back + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace_back( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace_back( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + reference emplace_back( Args&&... args ); Appends a new element to the end of the container. The element is constructed - in-place, i.e. no copy or move operations are performed. The constructor of the - element is called with exactly the same arguments that are supplied to the function. + through std::allocator_traits::construct, which typically uses placement-new to + construct the element in-place at the location provided by the container. The + arguments args... are forwarded to the constructor as std::forward(args).... No iterators or references are invalidated. .SH Parameters - args - arguments to forward to the constructor of the element + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of EmplaceConstructible. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + A reference to the inserted element. \fI(since C++17)\fP .SH Complexity @@ -32,67 +42,72 @@ constructor and shows how using emplace_back avoids the extra copy or move operation required when using push_back. - + // Run this code #include - #include + #include #include - + #include + struct President { std::string name; std::string country; int year; - + President(std::string p_name, std::string p_country, int p_year) : name(std::move(p_name)), country(std::move(p_country)), year(p_year) { std::cout << "I am being constructed.\\n"; } + President(President&& other) : name(std::move(other.name)), country(std::move(other.country)), year(other.year) { std::cout << "I am being moved.\\n"; } + President& operator=(const President& other) = default; }; - + int main() { std::list elections; std::cout << "emplace_back:\\n"; - elections.emplace_back("Nelson Mandela", "South Africa", 1994); - + auto& ref = elections.emplace_back("Nelson Mandela", "South Africa", 1994); + assert(ref.year == 1994 && "uses a reference to the created object \fI(C++17)\fP"); + std::list reElections; std::cout << "\\npush_back:\\n"; reElections.push_back(President("Franklin Delano Roosevelt", "the USA", 1936)); - + std::cout << "\\nContents:\\n"; - for (President const& president: elections) { + for (President const& president: elections) std::cout << president.name << " was elected president of " << president.country << " in " << president.year << ".\\n"; - } - for (President const& president: reElections) { + + for (President const& president: reElections) std::cout << president.name << " was re-elected president of " << president.country << " in " << president.year << ".\\n"; - } } .SH Output: emplace_back: I am being constructed. - + push_back: I am being constructed. I am being moved. - + .SH Contents: Nelson Mandela was elected president of South Africa in 1994. Franklin Delano Roosevelt was re-elected president of the USA in 1936. .SH See also - push_back adds elements to the end - \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::list::emplace_front.3 b/man/std::list::emplace_front.3 index 2b79cc2af..f3b424ae0 100644 --- a/man/std::list::emplace_front.3 +++ b/man/std::list::emplace_front.3 @@ -1,27 +1,42 @@ -.TH std::list::emplace_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::emplace_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::emplace_front \- std::list::emplace_front + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace_front( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace_front( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + reference emplace_front( Args&&... args ); Inserts a new element to the beginning of the container. The element is constructed - in-place, i.e. no copy or move operations are performed. The constructor of the - element is called with exactly the same arguments, as supplied to the function. + through std::allocator_traits::construct, which typically uses placement-new to + construct the element in-place at the location provided by the container. The + arguments args... are forwarded to the constructor as std::forward(args).... No iterators or references are invalidated. .SH Parameters - args - arguments to forward to the constructor of the element + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of EmplaceConstructible. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + A reference to the inserted element. \fI(since C++17)\fP .SH Complexity Constant. +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + .SH See also - push_front inserts elements to the beginning - \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP diff --git a/man/std::list::empty.3 b/man/std::list::empty.3 index 29f17175a..3fb6f657e 100644 --- a/man/std::list::empty.3 +++ b/man/std::list::empty.3 @@ -1,6 +1,12 @@ -.TH std::list::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::empty \- std::list::empty + .SH Synopsis - bool empty() const; + bool empty() const; \fI(until C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +16,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,21 +24,22 @@ .SH Example - + The following code uses empty to check if a std::list contains any elements: - + // Run this code #include #include - + int main() { std::list numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.push_back(42); numbers.push_back(13317); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -47,10 +47,12 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::list::end,std::list::cend.3 b/man/std::list::end,std::list::cend.3 index 8205d13da..063be5596 100644 --- a/man/std::list::end,std::list::cend.3 +++ b/man/std::list::end,std::list::cend.3 @@ -1,10 +1,13 @@ -.TH std::list::end,std::list::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::end,std::list::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::end,std::list::cend \- std::list::end,std::list::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fB(1)\fP (noexcept since C++11) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the list. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +22,60 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::list nums{1, 2, 4, 8, 16}; + std::list fruits{"orange", "apple", "raspberry"}; + std::list empty; + + // Print list. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the list nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the list fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "list 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + list 'empty' is indeed empty. + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::list::erase.3 b/man/std::list::erase.3 index 718bd76eb..bf5f9bb94 100644 --- a/man/std::list::erase.3 +++ b/man/std::list::erase.3 @@ -1,4 +1,7 @@ -.TH std::list::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::erase \- std::list::erase + .SH Synopsis iterator erase( iterator pos ); \fI(until C++11)\fP iterator erase( const_iterator pos ); \fI(since C++11)\fP @@ -6,16 +9,19 @@ iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP const_iterator last ); - Removes specified elements from the container. + Erases the specified elements from the container. 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). + 2) Removes the elements in the range [first, last). References and iterators to the erased elements are invalidated. Other references and iterators are not affected. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. + + The iterator first does not need to be dereferenceable if first == last: erasing an + empty range is a no-op. .SH Parameters @@ -26,41 +32,69 @@ Iterator following the last removed element. + 1) If pos refers to the last element, then the end() iterator is returned. + 2) If last == end() prior to removal, then the updated end() iterator is returned. + If [first, last) is an empty range, then last is returned. + +.SH Exceptions + + \fI(none)\fP + +.SH Complexity + + 1) Constant. + 2) Linear in the distance between first and last. + +.SH Notes + + When container elements need to be erased based on a predicate, rather than + iterating the container and calling unary erase, the iterator range overload is + generally used with std::remove()/std::remove_if() to minimise the number of moves + of the remaining (non-removed) elements, this is the erase-remove idiom. + std::erase_if() replaces the erase-remove idiom. + \fI(since C++20)\fP + .SH Example - + // Run this code #include #include #include - - int main( ) + + void print_container(const std::list& c) { - std::list c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; - for (auto &i : c) { - std::cout << i << " "; - } + for (int i : c) + std::cout << i << ' '; std::cout << '\\n'; - + } + + int main() + { + std::list c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + print_container(c); + c.erase(c.begin()); - - for (auto &i : c) { - std::cout << i << " "; - } - std::cout << '\\n'; - + print_container(c); + std::list::iterator range_begin = c.begin(); std::list::iterator range_end = c.begin(); - std::advance(range_begin,2); - std::advance(range_end,5); - + std::advance(range_begin, 2); + std::advance(range_end, 5); + c.erase(range_begin, range_end); - - for (auto &i : c) { - std::cout << i << " "; + print_container(c); + + // Erase all even numbers + for (std::list::iterator it = c.begin(); it != c.end();) + { + if (*it % 2 == 0) + it = c.erase(it); + else + ++it; } - std::cout << '\\n'; + print_container(c); } .SH Output: @@ -68,13 +102,22 @@ 0 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 1 2 6 7 8 9 + 1 7 9 -.SH Complexity + Defect reports - 1) Constant. - 2) Linear in the distance between first and last. + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + first was required to be dereferenceable, which not required if + LWG 151 C++98 made the behavior of clearing an empty list first == last + undefined .SH See also - clear clears the contents - \fI(public member function)\fP + erase(std::list) erases all elements satisfying specific criteria + erase_if(std::list) \fI(function template)\fP + (C++20) + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::list::front.3 b/man/std::list::front.3 index a8686e0da..e854f778d 100644 --- a/man/std::list::front.3 +++ b/man/std::list::front.3 @@ -1,11 +1,14 @@ -.TH std::list::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::front \- std::list::front + .SH Synopsis - reference front(); - const_reference front() const; + reference front(); \fB(1)\fP + const_reference front() const; \fB(2)\fP Returns a reference to the first element in the container. - Calling front on an empty container is undefined. + Calling front on an empty container causes undefined behavior. .SH Parameters @@ -13,11 +16,11 @@ .SH Return value - reference to the first element + Reference to the first element. .SH Complexity - Constant + Constant. .SH Notes @@ -27,26 +30,25 @@ The following code uses front to display the first element of a std::list: - + // Run this code #include #include - + int main() { - std::list letters {'o', 'm', 'g', 'w', 't', 'f'}; - - if (!letters.empty()) { - std::cout << "The first character is: " << letters.front() << '\\n'; - } + std::list letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The first character is '" << letters.front() << "'.\\n"; } .SH Output: - The first character is o + The first character is 'a'. .SH See also back access the last element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::get_allocator.3 b/man/std::list::get_allocator.3 index 79b08926a..b2bc62d43 100644 --- a/man/std::list::get_allocator.3 +++ b/man/std::list::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::list::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::get_allocator \- std::list::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) Returns the allocator associated with the container. diff --git a/man/std::list::insert.3 b/man/std::list::insert.3 index 6b0aea176..5948e1494 100644 --- a/man/std::list::insert.3 +++ b/man/std::list::insert.3 @@ -1,65 +1,143 @@ -.TH std::list::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::insert \- std::list::insert + .SH Synopsis - iterator insert( iterator pos, const T& value ); (until - C++11) - iterator insert( const_iterator pos, const T& value (since - ); C++11) - iterator insert( const_iterator pos, T&& value ); \fB(2)\fP (since - C++11) - void insert( iterator pos, size_type count, const T& (until - value ); C++11) - iterator insert( const_iterator pos, size_type \fB(1)\fP (since - count, const T& value ); C++11) - template< class InputIt > (until - void insert( iterator pos, InputIt first, InputIt \fB(3)\fP C++11) - last); - template< class InputIt > \fB(4)\fP (since - iterator insert( const_iterator pos, InputIt first, C++11) - InputIt last ); - iterator insert( const_iterator pos, \fB(5)\fP (since - std::initializer_list ilist ); C++11) - - Inserts elements at specified location in the container. - - 1-2) inserts value before the location pointed to by pos - 3) inserts count copies of the value before the location pointed to by pos - 4) inserts elements from range [first, last) before the location pointed to by pos. - The behavior is undefined if first and last are iterators into *this. - 5) inserts elements from initializer list ilist. + iterator insert( const_iterator pos, const T& value ); \fB(1)\fP + iterator insert( const_iterator pos, T&& value ); \fB(2)\fP \fI(since C++11)\fP + iterator insert( const_iterator pos, \fB(3)\fP + size_type count, const T& value ); + template< class InputIt > + iterator insert( const_iterator pos, InputIt first, InputIt last \fB(4)\fP + ); + iterator insert( const_iterator pos, std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); + + Inserts elements at the specified location in the container. + + 1,2) Inserts value before pos. + 3) Inserts count copies of the value before pos. + 4) Inserts elements from range [first, last) before pos. + + This overload has the same effect as overload \fB(3)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt + qualifies as LegacyInputIterator, to avoid ambiguity with the overload \fI(since C++11)\fP + \fB(3)\fP. + + If first and last are iterators into *this, the behavior is undefined. + 5) Inserts elements from initializer list ilist before pos. No iterators or references are invalidated. .SH Parameters - pos - iterator to the location before which the content will be inserted. - pos may be the end() iterator + pos - iterator before which the content will be inserted (pos may be the + end() iterator) value - element value to insert - first, last - the range of elements to insert, can't be iterators into container for - which insert is called + count - number of elements to insert + first, last - the range of elements to insert, cannot be iterators into container + for which insert is called ilist - initializer list to insert the values from .SH Type requirements - - InputIt must meet the requirements of InputIterator. + T must meet the requirements of CopyInsertable in order to use overload \fB(1)\fP. + - + T must meet the requirements of MoveInsertable in order to use overload \fB(2)\fP. + - + T must meet the requirements of CopyAssignable and CopyInsertable in order to use + overload \fB(3)\fP. + - + T must meet the requirements of EmplaceConstructible in order to use overloads + (4,5). .SH Return value - 1-2) Iterator pointing to the inserted value - 3) Iterator pointing to the first element inserted, or pos if count==0. - 4) Iterator pointing to the first element inserted, or pos if first==last. + 1,2) Iterator pointing to the inserted value. + 3) Iterator pointing to the first element inserted, or pos if count == 0. + 4) Iterator pointing to the first element inserted, or pos if first == last. 5) Iterator pointing to the first element inserted, or pos if ilist is empty. .SH Complexity - 1-2) Constant. - 3) Linear in count - 4) Linear in std::distance(first, last) - 5) Linear in ilist.size() + 1,2) Constant. + 3) Linear in count. + 4) Linear in std::distance(first, last). + 5) Linear in ilist.size(). + +.SH Exceptions + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(int id, const std::list& container) + { + std::cout << id << ". "; + for (const int x : container) + std::cout << x << ' '; + std::cout << '\\n'; + } + + int main () + { + std::list c1(3, 100); + print(1, c1); + + auto it = c1.begin(); + it = c1.insert(it, 200); + print(2, c1); + + c1.insert(it, 2, 300); + print(3, c1); + + // reset `it` to the begin: + it = c1.begin(); + + std::list c2(2, 400); + c1.insert(std::next(it, 2), c2.begin(), c2.end()); + print(4, c1); + + int arr[] = {501, 502, 503}; + c1.insert(c1.begin(), arr, arr + std::size(arr)); + print(5, c1); + + c1.insert(c1.end(), {601, 602, 603}); + print(6, c1); + } + +.SH Output: + + 1. 100 100 100 + 2. 200 100 100 100 + 3. 300 300 200 100 100 100 + 4. 300 300 400 400 200 100 100 100 + 5. 501 502 503 300 300 400 400 200 100 100 100 + 6. 501 502 503 300 300 400 400 200 100 100 100 601 602 603 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 149 C++98 overloads \fB(3)\fP and \fB(4)\fP returned nothing returns an iterator .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::list::insert_range.3 b/man/std::list::insert_range.3 new file mode 100644 index 000000000..3e877c55c --- /dev/null +++ b/man/std::list::insert_range.3 @@ -0,0 +1,71 @@ +.TH std::list::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::insert_range \- std::list::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + iterator insert_range( const_iterator pos, R&& rg ); + + Inserts, in non-reversing order, copies of elements in rg before pos. + + No iterators or references are invalidated. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + pos - iterator before which the content will be inserted (pos may be the end() + iterator) + rg - a container compatible range, that is, an input_range whose elements are + convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into list from *ranges::begin(rg). Otherwise, the + behavior is undefined. + +.SH Return value + + An iterator that points at the copy of the first element inserted into list or at + pos if rg is empty. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto container = std::list{1, 2, 3, 4}; + auto pos = std::next(container.begin(), 2); + assert(*pos == 3); + const auto rg = std::vector{-1, -2, -3}; + + #ifdef __cpp_lib_containers_ranges + container.insert_range(pos, rg); + #else + container.insert(pos, rg.cbegin(), rg.cend()); + #endif + assert(std::ranges::equal(container, std::list{1, 2, -1, -2, -3, 3, 4})); + } + +.SH See also + + insert inserts elements + \fI(public member function)\fP + prepend_range adds a range of elements to the beginning + (C++23) \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP diff --git a/man/std::list::list.3 b/man/std::list::list.3 index df90fdeee..90db13df0 100644 --- a/man/std::list::list.3 +++ b/man/std::list::list.3 @@ -1,131 +1,195 @@ -.TH std::list::list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::list \- std::list::list + .SH Synopsis - explicit list( const Allocator& alloc = Allocator() (until - ); C++14) - list : list( Allocator() ) {} (since - explicit list( const Allocator& alloc ); C++14) + list(); \fB(1)\fP + explicit list( const Allocator& alloc ); \fB(2)\fP explicit list( size_type count, - const T& value = T(), (until - C++11) + const T& value = T(), \fI(until C++11)\fP + const Allocator& alloc = - Allocator()); + Allocator() ); list( size_type count, - const T& value, (since - C++11) - const Allocator& alloc = - Allocator()); - (since - explicit list( size_type count ); \fB(1)\fP C++11) - (until - \fB(2)\fP C++14) - explicit list( size_type count, const Allocator& (since - alloc = Allocator() ); C++14) - template< class InputIt > - - list( InputIt first, InputIt last, \fB(4)\fP - \fB(3)\fP + const T& value, \fI(since C++11)\fP + + const Allocator& alloc = Allocator() ); + explicit list( size_type count ); \fI(since C++11)\fP + \fI(until C++14)\fP + explicit list( size_type count, + const Allocator& alloc = \fI(since C++14)\fP + Allocator() ); + template< class InputIt > \fB(3)\fP + + list( InputIt first, InputIt last, \fB(5)\fP + const Allocator& alloc = Allocator() ); - list( const list& other ); \fB(5)\fP - list( const list& other, const Allocator& alloc ); \fB(5)\fP (since - C++11) - list( list&& other ) \fB(6)\fP (since - C++11) - list( list&& other, const Allocator& alloc ); \fB(6)\fP (since - C++11) - list( std::initializer_list init, \fB(7)\fP (since - const Allocator& alloc = Allocator() ); C++11) - - Constructs new container from a variety of data sources and optionally using user + list( const list& other ); \fB(4)\fP \fB(6)\fP + list( const list& other, const Allocator& alloc \fB(7)\fP \fI(since C++11)\fP + ); + list( list&& other ); \fB(8)\fP \fI(since C++11)\fP + list( list&& other, const Allocator& alloc ); \fB(9)\fP \fI(since C++11)\fP + list( std::initializer_list init, \fB(10)\fP \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); + template< container-compatible-range R > + + list( std::from_range_t, R&& rg, \fB(11)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + + Constructs a new container from a variety of data sources, optionally using a user supplied allocator alloc. - 1) Default constructor. Constructs empty container. - 2) Constructs the container with count copies of elements with value value. - 3) Constructs the container with count value-initialized (default constructed, for - classes) instances of T. No copies are made. - 4) Constructs the container with the contents of the range [first, last). - 5) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_container_copy_construction(other). - 6) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 7) Constructs the container with the contents of the initializer list init. + 1) Default constructor. Constructs an empty container with a default-constructed + allocator. + 2) Constructs an empty container with the given allocator alloc. + 3) Constructs the container with count copies of elements with value value. + 4) Constructs the container with count default-inserted instances of T. No copies + are made. + 5) Constructs the container with the contents of the range [first, last). + + This constructor has the same effect as + list(static_cast(first), static_cast(last), a) \fI(until C++11)\fP + if InputIt is an integral type. + This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator, to avoid ambiguity with the overload \fI(since C++11)\fP + \fB(3)\fP. + + 6) Copy constructor. Constructs the container with the copy of the contents of + other. + + The allocator is obtained as if by calling (since + std::allocator_traits::select_on_container_copy_construction( C++11) + other.get_allocator()). + + 7) Constructs the container with the copy of the contents of other, using alloc as + the allocator. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 8) Move constructor. Constructs the container with the contents of other using move + semantics. Allocator is obtained by move-construction from the allocator belonging + to other. + 9) Allocator-extended move constructor. Using alloc as the allocator for the new + container, moving the contents from other; if alloc != other.get_allocator(), this + results in an element-wise move. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 10) Constructs the container with the contents of the initializer list init. + 11) Constructs the container with the contents of the range rg. .SH Parameters alloc - allocator to use for all memory allocations of this container count - the size of the container value - the value to initialize elements of the container with - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with -.SH Type requirements - - - Allocator must meet the requirements of Allocator. - - - InputIt must meet the requirements of InputIterator. + rg - a container compatible range, that is, an input_range whose elements + are convertible to T .SH Complexity - 1) Constant - 2-3) Linear in count - 4) Linear in distance between first and last - 5) Linear in size of other - 6) Constant. If alloc is given and alloc != other.get_allocator(), then linear. - 7) Linear in size of init + 1,2) Constant. + 3,4) Linear in count. + 5) Linear in distance between first and last. + 6,7) Linear in size of other. + 8) Constant. + 9) Linear if alloc != other.get_allocator(), otherwise constant. + 10) Linear in size of init. + 11) Linear in ranges::distance(rg). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload \fB(8)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(11)\fP .SH Example - + // Run this code - #include - #include #include - + #include + #include + template - std::ostream& operator<<(std::ostream& s, const std::list& v) { - s.put('['); - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& e : v) { - s << comma << e; - comma[0] = ','; - } - return s << ']'; + std::ostream& operator<<(std::ostream& s, const std::list& v) + { + s.put('{'); + for (char comma[]{'\\0', ' ', '\\0'}; const auto& e : v) + s << comma << e, comma[0] = ','; + return s << "}\\n"; } - + int main() { - // c++11 initializer list syntax: - std::list words1 {"the", "frogurt", "is", "also", "cursed"}; - std::cout << "words1: " << words1 << '\\n'; - + // C++11 initializer list syntax: + std::list words1{"the", "frogurt", "is", "also", "cursed"}; + std::cout << "1: " << words1; + // words2 == words1 std::list words2(words1.begin(), words1.end()); - std::cout << "words2: " << words2 << '\\n'; - + std::cout << "2: " << words2; + // words3 == words1 std::list words3(words1); - std::cout << "words3: " << words3 << '\\n'; - + std::cout << "3: " << words3; + // words4 is {"Mo", "Mo", "Mo", "Mo", "Mo"} std::list words4(5, "Mo"); - std::cout << "words4: " << words4 << '\\n'; + std::cout << "4: " << words4; + + auto const rg = {"cat", "cow", "crow"}; + #ifdef __cpp_lib_containers_ranges + std::list words5(std::from_range, rg); // overload (11) + #else + std::list words5(rg.begin(), rg.end()); // overload (5) + #endif + std::cout << "5: " << words5; } .SH Output: - words1: [the, frogurt, is, also, cursed] - words2: [the, frogurt, is, also, cursed] - words3: [the, frogurt, is, also, cursed] - words4: [Mo, Mo, Mo, Mo, Mo] + 1: {the, frogurt, is, also, cursed} + 2: {the, frogurt, is, also, cursed} + 3: {the, frogurt, is, also, cursed} + 4: {Mo, Mo, Mo, Mo, Mo} + 5: {cat, cow, crow} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 868 C++98 for overload \fB(4)\fP, the elements in the they are value-initialized + container were default constructed + LWG 2193 C++11 the default constructor is explicit made non-explicit .SH See also assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::max_size.3 b/man/std::list::max_size.3 index 3f720239f..547940ad2 100644 --- a/man/std::list::max_size.3 +++ b/man/std::list::max_size.3 @@ -1,6 +1,9 @@ -.TH std::list::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::max_size \- std::list::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,25 +17,45 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::list p; + std::list q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 768,614,336,404,564,650 = 0xAAA,AAA,AAA,AAA,AAA + q.max_size() = 768,614,336,404,564,650 = 0xAAA,AAA,AAA,AAA,AAA + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::merge.3 b/man/std::list::merge.3 index e0a078064..3cdbca97a 100644 --- a/man/std::list::merge.3 +++ b/man/std::list::merge.3 @@ -1,87 +1,136 @@ -.TH std::list::merge 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::merge \- std::list::merge + .SH Synopsis void merge( list& other ); \fB(1)\fP - void merge( list&& other ); \fB(1)\fP \fI(since C++11)\fP - template \fB(2)\fP + void merge( list&& other ); \fB(2)\fP \fI(since C++11)\fP + template< class Compare > \fB(3)\fP void merge( list& other, Compare comp ); - template \fB(2)\fP \fI(since C++11)\fP + template< class Compare > \fB(4)\fP \fI(since C++11)\fP void merge( list&& other, Compare comp ); - Merges two sorted lists into one. The lists should be sorted into ascending order. + The function does nothing if other refers to the same object as *this. + + Otherwise, merges other into *this. Both lists should be sorted. No elements are + copied, and the container other becomes empty after the merge. This operation is + stable: for equivalent elements in the two lists, the elements from *this always + precede the elements from other, and the order of equivalent elements of *this and + other does not change. + + No iterators or references become invalidated. The pointers and references to the + elements moved from *this, as well as the iterators referring to these elements, + will refer to the same elements of *this, instead of other. - No elements are copied. The container other becomes empty after the operation. The - function does nothing if this == &other. If get_allocator() != - other.get_allocator(), the behavior is undefined. No iterators or references become - invalidated, except that the iterators of moved elements now refer into *this, not - into other. The first version uses operator< to compare the elements, the second - version uses the given comparison function comp. + 1,2) Elements are compared using operator<. + 3,4) Elements are compared using comp. - This operation is stable: for equivalent elements in the two lists, the elements - from *this shall always precede the elements from other, and the order of equivalent - elements of *this and other does not change. + If *this or other is not sorted with respected to the corresponding comparator, or + get_allocator() != other.get_allocator(), the behavior is undefined. .SH Parameters other - another container to merge comparison function object (i.e. an object that satisfies the requirements - of Compare) which returns true if the first argument is less (i.e. is - ordered before) the second element. + of Compare) which returns true if the first argument is less than (i.e. is + ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must - not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type - list::const_iterator can be dereferenced and then implicitly - converted to both of them. + list::const_iterator can be dereferenced and then + implicitly converted to both of them. +.SH Type requirements + - + Compare must meet the requirements of Compare. .SH Return value \fI(none)\fP +.SH Exceptions + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). Except if the exception comes from a comparison. + +.SH Complexity + + If other refers to the same object as *this, no comparisons are performed. + + Otherwise, given \\(\\scriptsize N\\)N as std::distance(begin(), end()) and + \\(\\scriptsize R\\)R as std::distance(other.begin(), other.end()): + + 1,2) At most \\(\\scriptsize N+R-1\\)N+R-1 comparisons using operator<. + 3,4) At most \\(\\scriptsize N+R-1\\)N+R-1 applications of the comparison function + comp. + .SH Example - + // Run this code #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (const int i : list) + ostr << ' ' << i; return ostr; } - + int main() { - std::list list1 = { 5,9,0,1,3 }; - std::list list2 = { 8,7,2,6,4 }; - + std::list list1 = {5, 9, 1, 3, 3}; + std::list list2 = {8, 7, 2, 3, 4, 4}; + list1.sort(); list2.sort(); - std::cout << "list1: " << list1 << "\\n"; - std::cout << "list2: " << list2 << "\\n"; + std::cout << "list1: " << list1 << '\\n'; + std::cout << "list2: " << list2 << '\\n'; + list1.merge(list2); - std::cout << "merged: " << list1 << "\\n"; + std::cout << "merged:" << list1 << '\\n'; } .SH Output: - list1: 0 1 3 5 9 - list2: 2 4 6 7 8 - merged: 0 1 2 3 4 5 6 7 8 9 + list1: 1 3 3 5 9 + list2: 2 3 4 4 7 8 + merged: 1 2 3 3 3 4 4 5 7 8 9 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - at most size() + other.size() - 1 comparisons. + DR Applied to Behavior as published Correct behavior + LWG 300 C++98 the effect when *this and other refer specified as no-op + to the same object was not specified + LWG 1207 C++98 it was unclear whether iterators and/or keep valid + references will be invalidated + O(1) node moving could not be guaranteed if the behavior is + LWG 1215 C++98 get_allocator() != other.get_allocator() undefined in this + case .SH See also - splice moves elements from another list - \fI(public member function)\fP + splice moves elements from another list + \fI(public member function)\fP + merge merges two sorted ranges + \fI(function template)\fP + inplace_merge merges two ordered ranges in-place + \fI(function template)\fP + ranges::merge merges two sorted ranges + (C++20) (niebloid) + ranges::inplace_merge merges two ordered ranges in-place + (C++20) (niebloid) diff --git a/man/std::list::operator=.3 b/man/std::list::operator=.3 index 54697533c..2dd2e54dc 100644 --- a/man/std::list::operator=.3 +++ b/man/std::list::operator=.3 @@ -1,27 +1,39 @@ -.TH std::list::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::operator= \- std::list::operator= + .SH Synopsis - list& operator=( const list& other ); \fB(1)\fP - list& operator=( list&& other ); \fB(2)\fP \fI(since C++11)\fP - list& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + list& operator=( const list& other ); \fB(1)\fP + list& operator=( list&& other ); \fI(since C++11)\fP + \fB(2)\fP \fI(until C++17)\fP + list& operator=( list&& other ) noexcept(/* see below */); \fI(since C++17)\fP + list& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,68 +47,97 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) \fI(since C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::list to another: - The following code uses to assign one std::list to another: - // Run this code - #include + #include #include - - void display_sizes(const std::list& nums1, - const std::list& nums2, - const std::list& nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::list nums1 {3, 1, 4, 6, 5, 9}; - std::list nums2; - std::list nums3; - + std::list x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 1, 2, 3 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 1, 2, 3 } + y = { 1, 2, 3 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 1, 2, 3 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 4, 5, 6, 7 } .SH See also constructor constructs the list - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::list::pop_back.3 b/man/std::list::pop_back.3 index 3bbf3620f..71415a8ad 100644 --- a/man/std::list::pop_back.3 +++ b/man/std::list::pop_back.3 @@ -1,9 +1,14 @@ -.TH std::list::pop_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::pop_back \- std::list::pop_back + .SH Synopsis void pop_back(); Removes the last element of the container. + Calling pop_back on an empty container results in undefined behavior. + References and iterators to the erased element are invalidated. .SH Parameters @@ -18,9 +23,53 @@ Constant. +.SH Exceptions + + Throws nothing. + +.SH Example + + +// Run this code + + #include + #include + + template + void print(T const& xs) + { + std::cout << "[ "; + for (auto const& x : xs) + std::cout << x << ' '; + std::cout << "]\\n"; + } + + int main() + { + std::list numbers; + + print(numbers); + + numbers.push_back(5); + numbers.push_back(3); + numbers.push_back(4); + + print(numbers); + + numbers.pop_back(); + + print(numbers); + } + +.SH Output: + + [ ] + [ 5 3 4 ] + [ 5 3 ] + .SH See also pop_front removes the first element - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP diff --git a/man/std::list::pop_front.3 b/man/std::list::pop_front.3 index ee796a77d..6a2c8a812 100644 --- a/man/std::list::pop_front.3 +++ b/man/std::list::pop_front.3 @@ -1,8 +1,12 @@ -.TH std::list::pop_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::pop_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::pop_front \- std::list::pop_front + .SH Synopsis void pop_front(); - Removes the first element of the container. + Removes the first element of the container. If there are no elements in the + container, the behavior is undefined. References and iterators to the erased element are invalidated. @@ -18,9 +22,38 @@ Constant. +.SH Exceptions + + Does not throw. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::list chars{'A', 'B', 'C', 'D'}; + + for (; !chars.empty(); chars.pop_front()) + std::cout << "chars.front(): '" << chars.front() << "'\\n"; + } + +.SH Output: + + chars.front(): 'A' + chars.front(): 'B' + chars.front(): 'C' + chars.front(): 'D' + .SH See also pop_back removes the last element - \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP + \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + front access the first element + \fI(public member function)\fP diff --git a/man/std::list::prepend_range.3 b/man/std::list::prepend_range.3 new file mode 100644 index 000000000..7f4bda417 --- /dev/null +++ b/man/std::list::prepend_range.3 @@ -0,0 +1,68 @@ +.TH std::list::prepend_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::prepend_range \- std::list::prepend_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void prepend_range( R&& rg ); + + Inserts, in non-reversing order, copies of elements in rg before begin(). Each + iterator in the range rg is dereferenced exactly once. + + No iterators or references are invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into list from *ranges::begin(rg). Otherwise, the + behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in size of rg. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto container = std::list{0, 1, 2, 3}; + const auto rg = std::vector{-3, -2, -1}; + + #if __cpp_lib_containers_ranges + container.prepend_range(rg); + #else + container.insert(container.begin(), rg.cbegin(), rg.cend()); + #endif + assert(std::ranges::equal(container, std::list{-3, -2, -1, 0, 1, 2, 3})); + } + +.SH See also + + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::list::push_back.3 b/man/std::list::push_back.3 index db2367ac3..dc172f092 100644 --- a/man/std::list::push_back.3 +++ b/man/std::list::push_back.3 @@ -1,4 +1,7 @@ -.TH std::list::push_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::push_back \- std::list::push_back + .SH Synopsis void push_back( const T& value ); \fB(1)\fP void push_back( T&& value ); \fB(2)\fP \fI(since C++11)\fP @@ -29,42 +32,47 @@ .SH Exceptions - If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + If an exception is thrown (which can be due to Allocator::allocate() or element + copy/move constructor/assignment), this function has no effect (strong exception + guarantee). .SH Example - The following code uses push_back to add several integers to a std::list: - // Run this code - #include + #include #include - + #include + #include + int main() { - std::list numbers; - - numbers.push_back(42); - numbers.push_back(314159); - - for (int i : numbers) { // c++11 range-based for loop - std::cout << i << '\\n'; - } - - return 0; + std::list letters; + + letters.push_back("abc"); + std::string s{"def"}; + letters.push_back(std::move(s)); + + std::cout << "std::list letters holds: "; + for (auto&& e : letters) + std::cout << std::quoted(e) << ' '; + + std::cout << "\\nMoved-from string s holds: " << std::quoted(s) << '\\n'; } -.SH Output: +.SH Possible output: - 42 - 314159 + std::list letters holds: "abc" "def" + Moved-from string s holds: "" .SH See also - emplace_back constructs elements in-place at the end - \fI(C++11)\fP \fI(public member function)\fP - push_front inserts elements to the beginning - \fI(public member function)\fP - pop_back removes the last element - \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP + push_front inserts an element to the beginning + \fI(public member function)\fP + pop_back removes the last element + \fI(public member function)\fP + back_inserter creates a std::back_insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::list::push_front.3 b/man/std::list::push_front.3 index 859503c63..b8bcf57c0 100644 --- a/man/std::list::push_front.3 +++ b/man/std::list::push_front.3 @@ -1,7 +1,10 @@ -.TH std::list::push_front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::push_front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::push_front \- std::list::push_front + .SH Synopsis - void push_front( const T& value ); - void push_front( T&& value ); \fI(since C++11)\fP + void push_front( const T& value ); \fB(1)\fP + void push_front( T&& value ); \fB(2)\fP \fI(since C++11)\fP Prepends the given element value to the beginning of the container. @@ -21,13 +24,47 @@ .SH Exceptions - If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::list letters; + + letters.push_front("abc"); + std::string s{"def"}; + letters.push_front(std::move(s)); + + std::cout << "std::list letters holds: "; + for (auto&& e : letters) + std::cout << std::quoted(e) << ' '; + + std::cout << "\\nMoved-from string s holds: " << std::quoted(s) << '\\n'; + } + +.SH Possible output: + + std::list letters holds: "def" "abc" + Moved-from string s holds: "" .SH See also - emplace_front constructs elements in-place at the beginning - \fI(C++11)\fP \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP - pop_front removes the first element - \fI(public member function)\fP + emplace_front constructs an element in-place at the beginning + \fI(C++11)\fP \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + pop_front removes the first element + \fI(public member function)\fP + creates a std::front_insert_iterator of type inferred from the + front_inserter argument + \fI(function template)\fP diff --git a/man/std::list::rbegin,std::list::crbegin.3 b/man/std::list::rbegin,std::list::crbegin.3 index 304dd4ac5..cfe97dc96 100644 --- a/man/std::list::rbegin,std::list::crbegin.3 +++ b/man/std::list::rbegin,std::list::crbegin.3 @@ -1,11 +1,15 @@ -.TH std::list::rbegin,std::list::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::rbegin,std::list::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::rbegin,std::list::crbegin \- std::list::rbegin,std::list::crbegin + .SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. + Returns a reverse iterator to the first element of the reversed list. It corresponds + to the last element of the non-reversed list. If the list is empty, the returned + iterator is equal to rend(). range-rbegin-rend.svg @@ -17,18 +21,62 @@ Reverse iterator to the first element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::list nums{1, 2, 4, 8, 16}; + std::list fruits{"orange", "apple", "raspberry"}; + std::list empty; + + // Print list. + std::for_each(nums.rbegin(), nums.rend(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the list nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.rbegin(), nums.rend(), 0) << '\\n'; + + // Prints the first fruit in the list fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.rbegin() << '\\n'; + + if (empty.rbegin() == empty.rend()) + std::cout << "list 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 16 8 4 2 1 + Sum of nums: 31 + First fruit: raspberry + list 'empty' is indeed empty. + .SH See also - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::list::remove,remove_if.3 b/man/std::list::remove,remove_if.3 index 26a2bf3ad..939f07c21 100644 --- a/man/std::list::remove,remove_if.3 +++ b/man/std::list::remove,remove_if.3 @@ -1,63 +1,93 @@ -.TH std::list::remove,remove_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::remove,remove_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::remove,remove_if \- std::list::remove,remove_if + .SH Synopsis - void remove( const T& value ); - template< class UnaryPredicate > - void remove_if( UnaryPredicate p ); + void remove( const T& value ); \fI(until C++20)\fP + size_type remove( const T& value ); \fI(since C++20)\fP + template< class UnaryPredicate > \fB(1)\fP \fI(until C++20)\fP + void remove_if( UnaryPredicate p ); \fB(2)\fP + template< class UnaryPredicate > \fI(since C++20)\fP + size_type remove_if( UnaryPredicate p ); + + Removes all elements satisfying specific criteria. Invalidates only the iterators + and references to the removed elements. - Removes all elements satisfying specific criteria. The first version removes all - elements that are equal to value, the second version removes all elements for which - predicate p returns true. + 1) Removes all elements that are equal to value (using operator==). + 2) Removes all elements for which predicate p returns true. .SH Parameters value - value of the elements to remove unary predicate which returns true if the element should be removed. - The signature of the predicate function should be equivalent to the - following: - - p - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type - list::const_iterator can be dereferenced and then implicitly - converted to Type. + The expression p(v) must be convertible to bool for every argument v of type + p - (possibly const) T, regardless of value category, and must not modify v. + Thus, a parameter type of T&is not allowed + , nor is T unless for T a move is equivalent to a copy + \fI(since C++11)\fP. +.SH Type requirements + - + UnaryPredicate must meet the requirements of Predicate. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++20)\fP + The number of elements removed. \fI(since C++20)\fP .SH Complexity - Linear in the size of the container + Given \\(\\scriptsize N\\)N as std::distance(begin(), end()): + + 1) Exactly \\(\\scriptsize N\\)N comparisons using operator==. + 2) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_list_remove_return_type 201806L (C++20) Change the return type .SH Example - + // Run this code #include #include - + int main() { - std::list l = { 1,100,2,3,10,1,11,-1,12 }; - - l.remove(1); // remove both elements equal to 1 - l.remove_if([](int n){ return n > 10; }); // remove all elements greater than 10 - - for (int n : l) { + std::list l = {1, 100, 2, 3, 10, 1, 11, -1, 12}; + + auto count1 = l.remove(1); + std::cout << count1 << " elements equal to 1 were removed\\n"; + + auto count2 = l.remove_if([](int n){ return n > 10; }); + std::cout << count2 << " elements greater than 10 were removed\\n"; + + std::cout << "Finally, the list contains: "; + for (int n : l) std::cout << n << ' '; - } std::cout << '\\n'; } .SH Output: - 2 3 10 -1 + 2 elements equal to 1 were removed + 3 elements greater than 10 were removed + Finally, the list contains: 2 3 10 -1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether iterators only invalidates iterators and + LWG 1207 C++98 and/or references will be references to the removed + invalidated elements .SH See also remove removes elements satisfying specific criteria - remove_if \fI(function template)\fP + remove_if \fI(function template)\fP diff --git a/man/std::list::rend,std::list::crend.3 b/man/std::list::rend,std::list::crend.3 index 565f70668..c7d33876c 100644 --- a/man/std::list::rend,std::list::crend.3 +++ b/man/std::list::rend,std::list::crend.3 @@ -1,13 +1,16 @@ -.TH std::list::rend,std::list::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::rend,std::list::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::rend,std::list::crend \- std::list::rend,std::list::crend + .SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. + list. It corresponds to the element preceding the first element of the non-reversed + list. This element acts as a placeholder, attempting to access it results in + undefined behavior. range-rbegin-rend.svg @@ -19,18 +22,59 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::list nums{1, 2, 4, 8, 16}; + std::list fruits{"orange", "apple", "raspberry"}; + std::list empty; + + // Print list. + std::for_each(nums.rbegin(), nums.rend(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the list nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.rbegin(), nums.rend(), 0) << '\\n'; + + // Prints the first fruit in the list fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.rbegin() << '\\n'; + + if (empty.rbegin() == empty.rend()) + std::cout << "list 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 16 8 4 2 1 + Sum of nums: 31 + First fruit: raspberry + list 'empty' is indeed empty. + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::list::resize.3 b/man/std::list::resize.3 index 2a277f662..c85d98b69 100644 --- a/man/std::list::resize.3 +++ b/man/std::list::resize.3 @@ -1,30 +1,30 @@ -.TH std::list::resize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::resize \- std::list::resize + .SH Synopsis - void resize( size_type count, T value = T() ); \fI(until C++11)\fP - void resize( size_type count ); \fB(1)\fP \fI(since C++11)\fP - void resize( size_type count, const value_type& value); \fB(2)\fP \fI(since C++11)\fP + void resize( size_type count ); \fB(1)\fP + void resize( size_type count, const value_type& value ); \fB(2)\fP - Resizes the container to contain count elements. + Resizes the container to contain count elements, does nothing if count == size(). If the current size is greater than count, the container is reduced to its first - count elements as if by repeatedly calling pop_back() + count elements. - If the current size is less than count, additional elements are \fI(until C++11)\fP - appended and initialized with copies of value. If the current size is less than count, - \fI(since C++11)\fP - 1) additional value-initialized elements are appended - 2) additional copies of value are appended + + 1) additional default-inserted elements are appended. + 2) additional copies of value are appended. .SH Parameters - count - new size of the container - value - the value to initialize the new elements with + count - new size of the container + value - the value to initialize the new elements with .SH Type requirements - - 1) T must meet the requirements of DefaultConstructible and MoveInsertable. + T must meet the requirements of DefaultInsertable in order to use overload \fB(1)\fP. - - 2) T must meet the requirements of CopyInsertable and MoveInsertable. + T must meet the requirements of CopyInsertable in order to use overload \fB(2)\fP. .SH Return value @@ -32,9 +32,68 @@ .SH Complexity - Linear in the size of the container + Linear in the difference between the current size and count. + +.SH Notes + + If value-initialization in overload \fB(1)\fP is undesirable, for example, if the elements + are of non-class type and zeroing out is not needed, it can be avoided by providing + a custom Allocator::construct. + +.SH Example + + +// Run this code + + #include + #include + + void print(auto rem, const std::list& c) + { + for (std::cout << rem; const int el : c) + std::cout << el << ' '; + std::cout << '\\n'; + } + + int main() + { + std::list c = {1, 2, 3}; + print("The list holds: ", c); + + c.resize(5); + print("After resize up to 5: ", c); + + c.resize(2); + print("After resize down to 2: ", c); + + c.resize(6, 4); + print("After resize up to 6 (initializer = 4): ", c); + } + +.SH Output: + + The list holds: 1 2 3 + After resize up to 5: 1 2 3 0 0 + After resize down to 2: 1 2 + After resize up to 6 (initializer = 4): 1 2 4 4 4 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 132 C++98 random-access iterators were used to use bidirectional + determine the erase range iterators + LWG 679 C++98 resize() passed value by value passes by const reference + LWG 1420 C++98 the behavior of resize(size()) was specified + not specified .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::list::reverse.3 b/man/std::list::reverse.3 index 45da3d423..e719522b6 100644 --- a/man/std::list::reverse.3 +++ b/man/std::list::reverse.3 @@ -1,6 +1,9 @@ -.TH std::list::reverse 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::reverse 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::reverse \- std::list::reverse + .SH Synopsis - void reverse(); + void reverse(); (noexcept since C++11) Reverses the order of the elements in the container. No references or iterators become invalidated. @@ -13,44 +16,53 @@ \fI(none)\fP +.SH Complexity + + Linear in the size of the container. + .SH Example - + // Run this code #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (auto& i : list) + ostr << ' ' << i; return ostr; } - + int main() { - std::list list = { 8,7,5,9,0,1,3,2,6,4 }; - - std::cout << "before: " << list << "\\n"; + std::list list = {8, 7, 5, 9, 0, 1, 3, 2, 6, 4}; + std::cout << "initially: " << list << '\\n'; + list.sort(); - std::cout << "ascending: " << list << "\\n"; + std::cout << "ascending: " << list << '\\n'; + list.reverse(); - std::cout << "descending: " << list << "\\n"; + std::cout << "descending:" << list << '\\n'; } .SH Output: - before: 8 7 5 9 0 1 3 2 6 4 - ascending: 0 1 2 3 4 5 6 7 8 9 - descending: 9 8 7 6 5 4 3 2 1 0 + initially: 8 7 5 9 0 1 3 2 6 4 + ascending: 0 1 2 3 4 5 6 7 8 9 + descending: 9 8 7 6 5 4 3 2 1 0 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container + DR Applied to Behavior as published Correct behavior + LWG 1207 C++98 it was unclear whether iterators and/or keep valid + references will be invalidated .SH See also sort sorts the elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::size.3 b/man/std::list::size.3 index 31c73de27..dfafaedc3 100644 --- a/man/std::list::size.3 +++ b/man/std::list::size.3 @@ -1,6 +1,10 @@ -.TH std::list::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::size \- std::list::size + .SH Synopsis - size_type size() const; + size_type size() const; \fI(until C++11)\fP + size_type size() const noexcept; \fI(since C++11)\fP Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,13 +16,6 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant or linear. \fI(until C++11)\fP @@ -28,16 +25,16 @@ The following code uses size to display the number of elements in a std::list: - + // Run this code - #include #include - + #include + int main() { - std::list nums {1, 3, 5, 7}; - + std::list nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -48,8 +45,8 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::list::sort.3 b/man/std::list::sort.3 index 5e30dbec0..7b68252f6 100644 --- a/man/std::list::sort.3 +++ b/man/std::list::sort.3 @@ -1,68 +1,107 @@ -.TH std::list::sort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::sort \- std::list::sort + .SH Synopsis void sort(); \fB(1)\fP template< class Compare > \fB(2)\fP void sort( Compare comp ); - Sorts the elements in ascending order. The order of equal elements is preserved. The - first version uses operator< to compare the elements, the second version uses the - given comparison function comp. + Sorts the elements and preserves the order of equivalent elements. No references or + iterators become invalidated. + + 1) Elements are compared using operator<. + 2) Elements are compared using comp. + + If an exception is thrown, the order of elements in *this is unspecified. .SH Parameters comparison function object (i.e. an object that satisfies the requirements of - Compare) which returns true if the first argument is less (i.e. is ordered - before) the second element. + Compare) which returns true if the first argument is less than (i.e. is + ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must not - modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of type + (possibly const) Type1 and Type2 regardless of value category (thus, Type1& + is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type list::const_iterator can be dereferenced and then implicitly - converted to both of them. + converted to both of them. +.SH Type requirements + - + Compare must meet the requirements of Compare. .SH Return value \fI(none)\fP +.SH Complexity + + Given \\(\\scriptsize N\\)N as size(): + + 1) Approximately \\(\\scriptsize N \\cdot log(N)\\)N·log(N) comparisons using operator<. + 2) Approximately \\(\\scriptsize N \\cdot log(N)\\)N·log(N) applications of the + comparison function comp. + +.SH Notes + + std::sort requires random access iterators and so cannot be used with list. This + function also differs from std::sort in that it does not require the element type of + the list to be swappable, preserves the values of all iterators, and performs a + stable sort. + .SH Example - + // Run this code - #include #include + #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (const int i : list) + ostr << ' ' << i; return ostr; } - + int main() { - std::list list = { 8,7,5,9,0,1,3,2,6,4 }; - - std::cout << "before: " << list << "\\n"; + std::list list{8, 7, 5, 9, 0, 1, 3, 2, 6, 4}; + std::cout << "initially: " << list << '\\n'; + list.sort(); - std::cout << "ascending: " << list << "\\n"; + std::cout << "ascending: " << list << '\\n'; + list.sort(std::greater()); - std::cout << "descending: " << list << "\\n"; + std::cout << "descending:" << list << '\\n'; } .SH Output: - before: 8 7 5 9 0 1 3 2 6 4 - ascending: 0 1 2 3 4 5 6 7 8 9 - descending: 9 8 7 6 5 4 3 2 1 0 + initially: 8 7 5 9 0 1 3 2 6 4 + ascending: 0 1 2 3 4 5 6 7 8 9 + descending: 9 8 7 6 5 4 3 2 1 0 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1207 C++98 it was unclear whether iterators and/or keep valid + references will be invalidated + +.SH See also - N · log(N) comparisons, where N is the size of the container. + reverse reverses the order of the elements + \fI(public member function)\fP diff --git a/man/std::list::splice.3 b/man/std::list::splice.3 index 1c7aff997..0ee65e724 100644 --- a/man/std::list::splice.3 +++ b/man/std::list::splice.3 @@ -1,92 +1,120 @@ -.TH std::list::splice 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::splice 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::splice \- std::list::splice + .SH Synopsis void splice( const_iterator pos, list& other ); \fB(1)\fP - void splice( const_iterator pos, list&& other ); \fB(1)\fP \fI(since C++11)\fP - void splice( const_iterator pos, list& other, const_iterator it ); \fB(2)\fP - void splice( const_iterator pos, list&& other, const_iterator it \fB(2)\fP \fI(since C++11)\fP + void splice( const_iterator pos, list&& other ); \fB(2)\fP \fI(since C++11)\fP + void splice( const_iterator pos, list& other, const_iterator it ); \fB(3)\fP + void splice( const_iterator pos, list&& other, const_iterator it \fB(4)\fP \fI(since C++11)\fP ); - void splice( const_iterator pos, list& other, \fB(3)\fP + void splice( const_iterator pos, list& other, \fB(5)\fP const_iterator first, const_iterator last); - void splice( const_iterator pos, list&& other, \fB(3)\fP \fI(since C++11)\fP + void splice( const_iterator pos, list&& other, \fB(6)\fP \fI(since C++11)\fP const_iterator first, const_iterator last ); - Moves elements from one list to another. + Transfers elements from one list to another. + + No elements are copied or moved, only the internal pointers of the list nodes are + re-pointed. No iterators or references become invalidated, the iterators to moved + elements remain valid, but now refer into *this, not into other. + + 1,2) Transfers all elements from other into *this. The elements are inserted before + the element pointed to by pos. The container other becomes empty after the + operation. + 3,4) Transfers the element pointed to by it from other into *this. The element is + inserted before the element pointed to by pos. + 5,6) Transfers the elements in the range [first, last) from other into *this. The + elements are inserted before the element pointed to by pos. - No elements are copied. The behavior is undefined if: get_allocator() != - other.get_allocator(). No iterators or references become invalidated, the iterators - to moved elements now refer into *this, not into other. + The behavior is undefined if - 1) Moves all elements from other into *this. The elements are inserted before the - element pointed to by pos. The container other becomes empty after the operation. - The behavior is undefined if this == &other. - 2) Moves the element pointed to by it from other into *this. The element is inserted - before the element pointed to by pos. - 3) Moves the elements in the range [first, last) from other into *this. The elements - are inserted before the element pointed to by pos. The behavior is undefined if pos - is an iterator in the range [first,last). + * get_allocator() != other.get_allocator(), + * for overloads (1,2), *this and other refer to the same object, + * for overloads (3,4), it is not a dereferenceable iterator into other, or + * for overloads (5,6), + + * [first, last) is not a valid range in other, or + * pos is in [first, last). .SH Parameters pos - element before which the content will be inserted - other - another container to move the content from - it - the element to move from other to *this - first, last - the range of elements to move from other to *this + other - another container to transfer the content from + it - the element to transfer from other to *this + first, last - the range of elements to transfer from other to *this .SH Return value \fI(none)\fP -.SH Complexity +.SH Exceptions - 1-2) Constant. + Throws nothing. - 3) Constant if this == &other, otherwise linear in std::distance(first, last). +.SH Complexity + + 1-4) Constant. + 5,6) Constant if other refers to the same object as *this, otherwise linear in + std::distance(first, last). .SH Example - + // Run this code #include #include - + std::ostream& operator<<(std::ostream& ostr, const std::list& list) { - for (auto &i : list) { - ostr << " " << i; - } + for (auto& i : list) + ostr << ' ' << i; + return ostr; } - + int main () { - std::list list1 = { 1, 2, 3, 4, 5 }; - std::list list2 = { 10, 20, 30, 40, 50 }; - + std::list list1{1, 2, 3, 4, 5}; + std::list list2{10, 20, 30, 40, 50}; + auto it = list1.begin(); std::advance(it, 2); - + list1.splice(it, list2); - - std::cout << "list1: " << list1 << "\\n"; - std::cout << "list2: " << list2 << "\\n"; - + + std::cout << "list1:" << list1 << '\\n'; + std::cout << "list2:" << list2 << '\\n'; + list2.splice(list2.begin(), list1, it, list1.end()); - - std::cout << "list1: " << list1 << "\\n"; - std::cout << "list2: " << list2 << "\\n"; + + std::cout << "list1:" << list1 << '\\n'; + std::cout << "list2:" << list2 << '\\n'; } .SH Output: - list1: 1 2 10 20 30 40 50 3 4 5 + list1: 1 2 10 20 30 40 50 3 4 5 list2: - list1: 1 2 10 20 30 40 50 - list2: 3 4 5 + list1: 1 2 10 20 30 40 50 + list2: 3 4 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + references and iterators to the moved they refer or point to + LWG 250 C++98 element(s) were all invalidated the + same element(s) in *this + N2525 C++98 O(1) splicing could not be guaranteed if the behavior is + get_allocator() != other.get_allocator() undefined in this case .SH See also merge merges two sorted lists - \fI(public member function)\fP + \fI(public member function)\fP remove removes elements satisfying specific criteria - remove_if \fI(public member function)\fP + remove_if \fI(public member function)\fP diff --git a/man/std::list::swap.3 b/man/std::list::swap.3 index 9df32ecd0..2328560e9 100644 --- a/man/std::list::swap.3 +++ b/man/std::list::swap.3 @@ -1,17 +1,22 @@ -.TH std::list::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::swap \- std::list::swap + .SH Synopsis - void swap( list& other ); + void swap( list& other ); \fI(until C++17)\fP + void swap( list& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. It is unspecified whether an iterator + holding the end() value in this container will refer to this or the other container + after the operation. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -23,13 +28,59 @@ .SH Exceptions - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::list a1{1, 2, 3}, a2{4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + int& ref1 = a1.front(); + int& ref2 = a2.front(); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that after swap the iterators and references stay associated with their + // original elements, e.g. it1 that pointed to an element in 'a1' with value 2 + // still points to the same element, though this element was moved into 'a2'. + } + +.SH Output: + + { 1 2 3 } { 4 5 } 2 5 1 4 + { 4 5 } { 1 2 3 } 2 5 1 4 + .SH See also std::swap(std::list) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::list::unique.3 b/man/std::list::unique.3 index d372cd319..6f3edc0d7 100644 --- a/man/std::list::unique.3 +++ b/man/std::list::unique.3 @@ -1,12 +1,24 @@ -.TH std::list::unique 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::unique 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::unique \- std::list::unique + .SH Synopsis - void unique(); \fB(1)\fP - template< class BinaryPredicate > \fB(2)\fP - void unique( BinaryPredicate p ); + void unique(); \fI(until C++20)\fP + size_type unique(); \fI(since C++20)\fP + template< class BinaryPredicate > \fB(1)\fP \fI(until C++20)\fP + void unique( BinaryPredicate p ); \fB(2)\fP + template< class BinaryPredicate > \fI(since C++20)\fP + size_type unique( BinaryPredicate p ); Removes all consecutive duplicate elements from the container. Only the first - element in each group of equal elements is left. The first version uses operator== - to compare the elements, the second version uses the given binary predicate p. + element in each group of equal elements is left. Invalidates only the iterators and + references to the removed elements. + + 1) Uses operator== to compare the elements. + 2) Uses p to compare the elements. + + The behavior is undefined if the corresponding comparator does not establish an + equivalence relation. .SH Parameters @@ -16,54 +28,94 @@ bool pred(const Type1 &a, const Type2 &b); - p - The signature does not need to have const &, but the function must not modify - the objects passed to it. + While the signature does not need to have const &, the function must not modify + p - the objects passed to it and must be able to accept all values of type (possibly + const) Type1 and Type2 regardless of value category (thus, Type1 & is not + allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type list::const_iterator can be dereferenced and then implicitly converted to both of them. - - +.SH Type requirements + - + BinaryPredicate must meet the requirements of BinaryPredicate. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++20)\fP + The number of elements removed. \fI(since C++20)\fP .SH Complexity - Linear in the size of the container + If empty() is true, no comparison is performed. + + Otherwise, given \\(\\scriptsize N\\)N as std::distance(begin(), end()): + + 1) Exactly \\(\\scriptsize N-1\\)N-1 comparisons using operator==. + 2) Exactly \\(\\scriptsize N-1\\)N-1 applications of the predicate p. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_list_remove_return_type 201806L (C++20) Change the return type .SH Example - + // Run this code #include #include - + + std::ostream& operator<< (std::ostream& os, std::list const& container) + { + for (int val : container) + os << val << ' '; + return os << '\\n'; + } + int main() { - std::list x = {1, 2, 2, 3, 3, 2, 1, 1, 2}; - - std::cout << "contents before:"; - for (auto val : x) - std::cout << ' ' << val; - std::cout << '\\n'; - - x.unique(); - std::cout << "contents after unique():"; - for (auto val : x) - std::cout << ' ' << val; - std::cout << '\\n'; - - return 0; + std::list c{1, 2, 2, 3, 3, 2, 1, 1, 2}; + std::cout << "Before unique(): " << c; + const auto count1 = c.unique(); + std::cout << "After unique(): " << c + << count1 << " elements were removed\\n"; + + c = {1, 2, 12, 23, 3, 2, 51, 1, 2, 2}; + std::cout << "\\nBefore unique(pred): " << c; + + const auto count2 = c.unique([mod = 10](int x, int y) + { + return (x % mod) == (y % mod); + }); + + std::cout << "After unique(pred): " << c + << count2 << " elements were removed\\n"; } .SH Output: - contents before: 1 2 2 3 3 2 1 1 2 - contents after unique(): 1 2 3 2 1 2 + Before unique(): 1 2 2 3 3 2 1 1 2 + After unique(): 1 2 3 2 1 2 + 3 elements were removed + + Before unique(pred): 1 2 12 23 3 2 51 1 2 2 + After unique(pred): 1 2 23 2 51 2 + 4 elements were removed + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether iterators only invalidates iterators and + LWG 1207 C++98 and/or references will be references to the removed + invalidated elements .SH See also unique removes consecutive duplicate elements in a range - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::list::~list.3 b/man/std::list::~list.3 index 4dba934a6..5ff20ab4d 100644 --- a/man/std::list::~list.3 +++ b/man/std::list::~list.3 @@ -1,11 +1,14 @@ -.TH std::list::~list 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::list::~list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::list::~list \- std::list::~list + .SH Synopsis ~list(); - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. + Destructs the list. The destructors of the elements are called and the used storage + is deallocated. Note, that if the elements are pointers, the pointed-to objects are + not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the list. diff --git "a/man/std::literals::chrono_literals::operator\"\"d.3" "b/man/std::literals::chrono_literals::operator\"\"d.3" new file mode 100644 index 000000000..402c8509c --- /dev/null +++ "b/man/std::literals::chrono_literals::operator\"\"d.3" @@ -0,0 +1,70 @@ +.TH std::literals::chrono_literals::operator""d 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""d \- std::literals::chrono_literals::operator""d + +.SH Synopsis + Defined in header + constexpr std::chrono::day operator ""d( unsigned long long d ) \fI(since C++20)\fP + noexcept; + + Forms a std::chrono::day literal representing a day of the month in the calendar. + +.SH Parameters + + d - the day value + +.SH Return value + + A std::chrono::day storing d. If d > 255, the stored value is unspecified. + +.SH Possible implementation + + constexpr std::chrono::day operator ""d(unsigned long long d) noexcept + { + return std::chrono::day(d); + } + +.SH Notes + + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. + + In addition, within the namespace std::chrono, the directive using namespace + literals::chrono_literals; is provided by the standard library, so that if a + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals::chrono_literals; + + std::cout << static_cast(42d) << '\\t' << 42d << '\\n' + << static_cast(256d) << '\\t' << 256d << '\\n' // unspecified + << static_cast(298d) << '\\t' << 298d << '\\n'; // unspecified + } + +.SH Possible output: + + 42 42 is not a valid day + 0 00 is not a valid day + 42 42 is not a valid day + +.SH See also + + constructor constructs a day + \fI(public member function of std::chrono::day)\fP + operator unsigned retrieves the stored day value + \fI(public member function of std::chrono::day)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"h.3" "b/man/std::literals::chrono_literals::operator\"\"h.3" index 94b8954c0..f0b0c2a77 100644 --- "a/man/std::literals::chrono_literals::operator\"\"h.3" +++ "b/man/std::literals::chrono_literals::operator\"\"h.3" @@ -1,15 +1,20 @@ -.TH std::literals::chrono_literals::operator""h 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::chrono_literals::operator""h 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""h \- std::literals::chrono_literals::operator""h + .SH Synopsis Defined in header - constexpr chrono::hours operator "" h(unsigned long long hrs); \fB(1)\fP \fI(since C++14)\fP - constexpr chrono::duration> \fB(2)\fP \fI(since C++14)\fP - operator "" h(long double hrs); + constexpr std::chrono::hours \fB(1)\fP \fI(since C++14)\fP + operator""h( unsigned long long hrs ); + constexpr std::chrono::duration> \fB(2)\fP \fI(since C++14)\fP + operator""h( long double hrs ); Forms a std::chrono::duration literal representing hours. - 1) integer literal, returns exactly std::chrono::hours(hrs) - 2) floating-point literal, returns a floating-point duration equivalent to - std::chrono::hours + 1) Integer literal, returns exactly std::chrono::hours(hrs). + 2) Floating-point literal, returns a floating-point duration equivalent to + std::chrono::hours. .SH Parameters @@ -21,50 +26,55 @@ .SH Possible implementation - constexpr std::chrono::hours operator ""h(unsigned long long h) + constexpr std::chrono::hours operator""h(unsigned long long h) { return std::chrono::hours(h); } - constexpr std::chrono::duration> operator ""h(long double h) + + constexpr std::chrono::duration> operator""h(long double h) { return std::chrono::duration>(h); } .SH Notes - These operators are declared in the namespace std::literals::chrono_literals, where - both literals and chrono_literals are inline namespaces. Access to these operators - can be gained with using namespace std::literals and using namespace - std::literals::chrono_literals. + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. In addition, within the namespace std::chrono, the directive using namespace literals::chrono_literals; is provided by the standard library, so that if a - programmer uses using namespace std::chrono; to gain access to the duration classes, - the duration literal operators become visible as well. + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. .SH Example // Run this code - #include #include + #include int main() { - using namespace std::literals::chrono_literals; + using namespace std::chrono_literals; auto day = 24h; auto halfhour = 0.5h; - std::cout << "one day is " << day.count() << " hours\\n" - << "half an hour is " << halfhour.count() << " hours\\n"; + std::cout << "one day is " << day.count() << " hours (" << day << ")\\n" + << "half an hour is " << halfhour.count() << " hours (" + << halfhour << ")\\n"; } .SH Output: - one day is 24 hours - half an hour is 0.5 hours + one day is 24 hours (24h) + half an hour is 0.5 hours (0.5h) .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"min.3" "b/man/std::literals::chrono_literals::operator\"\"min.3" index 4afe93f81..50dfb5cc7 100644 --- "a/man/std::literals::chrono_literals::operator\"\"min.3" +++ "b/man/std::literals::chrono_literals::operator\"\"min.3" @@ -1,20 +1,23 @@ -.TH std::literals::chrono_literals::operator""min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::chrono_literals::operator""min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""min \- std::literals::chrono_literals::operator""min + .SH Synopsis Defined in header - constexpr chrono::minutes operator "" min(unsigned long long \fB(1)\fP \fI(since C++14)\fP - mins); - constexpr chrono::duration> \fB(2)\fP \fI(since C++14)\fP - operator "" min(long double mins); + constexpr chrono::minutes \fB(1)\fP \fI(since C++14)\fP + operator""min( unsigned long long mins ); + constexpr chrono::duration> \fB(2)\fP \fI(since C++14)\fP + operator""min( long double mins ); Forms a std::chrono::duration literal representing minutes. - 1) integer literal, returns exactly std::chrono::minutes(mins) - 2) floating-point literal, returns a floating-point duration equivalent to - std::chrono::minutes + 1) Integer literal, returns exactly std::chrono::minutes(mins). + 2) Floating-point literal, returns a floating-point duration equivalent to + std::chrono::minutes. .SH Parameters - minutes - the number of minutes + mins - the number of minutes .SH Return value @@ -22,51 +25,56 @@ .SH Possible implementation - constexpr std::chrono::minutes operator ""min(unsigned long long m) + constexpr std::chrono::minutes operator""min(unsigned long long m) { return std::chrono::minutes(m); } constexpr std::chrono::duration> operator ""min(long double m) + std::ratio<60,1>> operator""min(long double m) { return std::chrono::duration> (m); } .SH Notes - These operators are declared in the namespace std::literals::chrono_literals, where - both literals and chrono_literals are inline namespaces. Access to these operators - can be gained with using namespace std::literals and using namespace - std::literals::chrono_literals. + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. In addition, within the namespace std::chrono, the directive using namespace literals::chrono_literals; is provided by the standard library, so that if a - programmer uses using namespace std::chrono; to gain access to the duration classes, - the duration literal operators become visible as well. + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. .SH Example // Run this code - #include #include + #include int main() { - using namespace std::literals::chrono_literals; + using namespace std::chrono_literals; auto lesson = 45min; auto halfmin = 0.5min; - std::cout << "one lesson is " << lesson.count() << " minutes\\n" - << "half a minute is " << halfmin.count() << " minutes\\n"; + std::cout << "One lesson is " << lesson.count() << " minutes" + " (" << lesson << ")\\n" + << "Half a minute is " << halfmin.count() << " minutes" + " (" << halfmin << ")\\n"; } .SH Output: - one lesson is 45 minutes - half a minute is 0.5 minutes + One lesson is 45 minutes (45min) + Half a minute is 0.5 minutes (0.5min) .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"ms.3" "b/man/std::literals::chrono_literals::operator\"\"ms.3" index 0c9d3ceca..d6bc0cd71 100644 --- "a/man/std::literals::chrono_literals::operator\"\"ms.3" +++ "b/man/std::literals::chrono_literals::operator\"\"ms.3" @@ -1,17 +1,19 @@ -.TH std::literals::chrono_literals::operator""ms 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::chrono_literals::operator""ms 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""ms \- std::literals::chrono_literals::operator""ms + .SH Synopsis Defined in header - constexpr std::chrono::milliseconds operator "" ms(unsigned long \fB(1)\fP \fI(since C++14)\fP - long ms); - constexpr std::chrono::duration operator "" ms(long double \fB(2)\fP \fI(since C++14)\fP - ms); + constexpr std::chrono::milliseconds \fB(1)\fP \fI(since C++14)\fP + operator""ms( unsigned long long ms ); + constexpr std::chrono::duration \fB(2)\fP \fI(since C++14)\fP + operator""ms( long double ms ); Forms a std::chrono::duration literal representing milliseconds. - 1) integer literal, returns exactly std::chrono::milliseconds(ms) - 2) floating-point literal, returns a floating-point duration equivalent to - std::chrono::milliseconds + 1) Integer literal, returns exactly std::chrono::milliseconds(ms). + 2) Floating-point literal, returns a floating-point duration equivalent to + std::chrono::milliseconds. .SH Parameters @@ -23,50 +25,53 @@ .SH Possible implementation - constexpr std::chrono::milliseconds operator ""ms(unsigned long long ms) + constexpr std::chrono::milliseconds operator""ms(unsigned long long ms) { - return chrono::milliseconds(ms); + return std::chrono::milliseconds(ms); } - constexpr std::chrono::duration operator ""ms(long double ms) + constexpr std::chrono::duration operator""ms(long double ms) { return std::chrono::duration(ms); } .SH Notes - These operators are declared in the namespace std::literals::chrono_literals, where - both literals and chrono_literals are inline namespaces. Access to these operators - can be gained with using namespace std::literals and using namespace - std::literals::chrono_literals. + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. In addition, within the namespace std::chrono, the directive using namespace literals::chrono_literals; is provided by the standard library, so that if a - programmer uses using namespace std::chrono; to gain access to the duration classes, - the duration literal operators become visible as well. + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. .SH Example // Run this code - #include #include + #include int main() { - using namespace std::literals::chrono_literals; - auto d1 = 250ms; - std::chrono::milliseconds d2 = 1s; - std::cout << "250ms = " << d1.count() << " milliseconds\\n" - << "1 = " << d2.count() << " milliseconds\\n"; + using namespace std::chrono_literals; + constexpr auto d1{250ms}; + constexpr std::chrono::milliseconds d2{1s}; + std::cout << d1 << " = " << d1.count() << " milliseconds\\n" + << d2 << " = " << d2.count() << " milliseconds\\n"; } .SH Output: 250ms = 250 milliseconds - 1 = 1000 milliseconds + 1000ms = 1000 milliseconds .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"ns.3" "b/man/std::literals::chrono_literals::operator\"\"ns.3" index 31f101618..3e7c358a7 100644 --- "a/man/std::literals::chrono_literals::operator\"\"ns.3" +++ "b/man/std::literals::chrono_literals::operator\"\"ns.3" @@ -1,17 +1,19 @@ -.TH std::literals::chrono_literals::operator""ns 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::chrono_literals::operator""ns 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""ns \- std::literals::chrono_literals::operator""ns + .SH Synopsis Defined in header - constexpr std::chrono::nanoseconds operator "" ns(unsigned long \fB(1)\fP \fI(since C++14)\fP - long nsec); - constexpr std::chrono::duration operator "" ns(long double \fB(2)\fP \fI(since C++14)\fP - nsec); + constexpr std::chrono::nanoseconds \fB(1)\fP \fI(since C++14)\fP + operator""ns( unsigned long long nsec ); + constexpr std::chrono::duration \fB(2)\fP \fI(since C++14)\fP + operator""ns( long double nsec ); Forms a std::chrono::duration literal representing nanoseconds. - 1) integer literal, returns exactly std::chrono::nanoseconds(nsec) - 2) floating-point literal, returns a floating-point duration equivalent to - std::chrono::nanoseconds + 1) Integer literal, returns exactly std::chrono::nanoseconds(nsec). + 2) Floating-point literal, returns a floating-point duration equivalent to + std::chrono::nanoseconds. .SH Parameters @@ -23,50 +25,53 @@ .SH Possible implementation - constexpr std::chrono::nanoseconds operator ""ns(unsigned long long ns) + constexpr std::chrono::nanoseconds operator""ns(unsigned long long ns) { - return chrono::nanoseconds(ns); + return std::chrono::nanoseconds(ns); } - constexpr std::chrono::duration operator ""ns(long double ns) + constexpr std::chrono::duration operator""ns(long double ns) { return std::chrono::duration(ns); } .SH Notes - These operators are declared in the namespace std::literals::chrono_literals, where - both literals and chrono_literals are inline namespaces. Access to these operators - can be gained with using namespace std::literals and using namespace - std::literals::chrono_literals. + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. In addition, within the namespace std::chrono, the directive using namespace literals::chrono_literals; is provided by the standard library, so that if a - programmer uses using namespace std::chrono; to gain access to the duration classes, - the duration literal operators become visible as well. + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. .SH Example // Run this code - #include #include + #include int main() { - using namespace std::literals::chrono_literals; - auto d1 = 250ns; - std::chrono::nanoseconds d2 = 1us; - std::cout << "250ns = " << d1.count() << " nanoseconds\\n" - << "1us = " << d2.count() << " nanoseconds\\n"; + using namespace std::chrono_literals; + auto d1{250ns}; + std::chrono::nanoseconds d2{1us}; + std::cout << d1 << " = " << d1.count() << " nanoseconds\\n" + << d2 << " = " << d2.count() << " nanoseconds\\n"; } .SH Output: 250ns = 250 nanoseconds - 1us = 1000 nanoseconds + 1000ns = 1000 nanoseconds .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"s.3" "b/man/std::literals::chrono_literals::operator\"\"s.3" index a3c090545..9f5ad78fe 100644 --- "a/man/std::literals::chrono_literals::operator\"\"s.3" +++ "b/man/std::literals::chrono_literals::operator\"\"s.3" @@ -1,15 +1,19 @@ -.TH std::literals::chrono_literals::operator""s 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::chrono_literals::operator""s 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""s \- std::literals::chrono_literals::operator""s + .SH Synopsis Defined in header - constexpr chrono::seconds operator "" s(unsigned long long secs); \fB(1)\fP \fI(since C++14)\fP - constexpr chrono::duration operator "" s(long \fB(2)\fP \fI(since C++14)\fP - double secs); + constexpr std::chrono::seconds \fB(1)\fP \fI(since C++14)\fP + operator""s( unsigned long long secs ); + constexpr std::chrono::duration \fB(2)\fP \fI(since C++14)\fP + operator""s( long double secs ); Forms a std::chrono::duration literal representing seconds. - 1) integer literal, returns exactly std::chrono::seconds(secs) - 2) floating-point literal, returns a floating-point duration equivalent to - std::chrono::seconds + 1) Integer literal, returns exactly std::chrono::seconds(secs). + 2) Floating-point literal, returns a floating-point duration equivalent to + std::chrono::seconds. .SH Parameters @@ -21,26 +25,29 @@ .SH Possible implementation - constexpr std::chrono::seconds operator ""s(unsigned long long s) + constexpr std::chrono::seconds operator""s(unsigned long long s) { - return std::chrono::seconds(m); + return std::chrono::seconds(s); } - constexpr std::chrono::duration operator ""s(long double s) + constexpr std::chrono::duration operator""s(long double s) { return std::chrono::duration(s); } .SH Notes - These operators are declared in the namespace std::literals::chrono_literals, where - both literals and chrono_literals are inline namespaces. Access to these operators - can be gained with using namespace std::literals and using namespace - std::literals::chrono_literals. + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. In addition, within the namespace std::chrono, the directive using namespace literals::chrono_literals; is provided by the standard library, so that if a - programmer uses using namespace std::chrono; to gain access to the duration classes, - the duration literal operators become visible as well. + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. std::string also defines operator""s, to represent literal objects of type std::string, but it is a string literal: 10s is ten seconds, but "10"s is a @@ -51,23 +58,32 @@ // Run this code - #include #include + #include int main() { - using namespace std::literals::chrono_literals; - auto halfmin = 30s; - std::cout << "half a minute is " << halfmin.count() << " seconds\\n" - << "a minute and a half is " << (1min + 30s).count() << " seconds\\n"; + using namespace std::chrono_literals; + + std::chrono::seconds halfmin = 30s; + std::cout << "Half a minute is " << halfmin.count() << " seconds" + " (" << halfmin << ").\\n" + "A minute and a second is " << (1min + 1s).count() << " seconds.\\n"; + + std::chrono::duration moment = 0.1s; + std::cout << "A moment is " << moment.count() << " seconds" + " (" << moment << ").\\n" + "And thrice as much is " << (moment + 0.2s).count() << " seconds.\\n"; } .SH Output: - half a minute is 30 seconds - a minute and a half is 90 seconds + Half a minute is 30 seconds (30s). + A minute and a second is 61 seconds. + A moment is 0.1 seconds (0.1s). + And thrice as much is 0.3 seconds. .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"us.3" "b/man/std::literals::chrono_literals::operator\"\"us.3" index e60c11f33..0ad3d56af 100644 --- "a/man/std::literals::chrono_literals::operator\"\"us.3" +++ "b/man/std::literals::chrono_literals::operator\"\"us.3" @@ -1,17 +1,19 @@ -.TH std::literals::chrono_literals::operator""us 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::chrono_literals::operator""us 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""us \- std::literals::chrono_literals::operator""us + .SH Synopsis Defined in header - constexpr std::chrono::microseconds operator "" us(unsigned long \fB(1)\fP \fI(since C++14)\fP - long us); - constexpr std::chrono::duration operator "" us(long double \fB(2)\fP \fI(since C++14)\fP - us); + constexpr std::chrono::microseconds \fB(1)\fP \fI(since C++14)\fP + operator""us( unsigned long long us ); + constexpr std::chrono::duration \fB(2)\fP \fI(since C++14)\fP + operator""us( long double us ); Forms a std::chrono::duration literal representing microseconds. - 1) integer literal, returns exactly std::chrono::microseconds(us) - 2) floating-point literal, returns a floating-point duration equivalent to - std::chrono::microseconds + 1) Integer literal, returns exactly std::chrono::microseconds(us). + 2) Floating-point literal, returns a floating-point duration equivalent to + std::chrono::microseconds. .SH Parameters @@ -23,42 +25,45 @@ .SH Possible implementation - constexpr std::chrono::microseconds operator ""us(unsigned long long us) + constexpr std::chrono::microseconds operator""us(unsigned long long us) { return std::chrono::microseconds(us); } - constexpr std::chrono::duration operator ""us(long double us) + constexpr std::chrono::duration operator""us(long double us) { return std::chrono::duration(us); } .SH Notes - These operators are declared in the namespace std::literals::chrono_literals, where - both literals and chrono_literals are inline namespaces. Access to these operators - can be gained with using namespace std::literals and using namespace - std::literals::chrono_literals. + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. In addition, within the namespace std::chrono, the directive using namespace literals::chrono_literals; is provided by the standard library, so that if a - programmer uses using namespace std::chrono; to gain access to the duration classes, - the duration literal operators become visible as well. + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. .SH Example // Run this code - #include #include + #include int main() { - using namespace std::literals::chrono_literals; + using namespace std::chrono_literals; auto d1 = 250us; std::chrono::microseconds d2 = 1ms; - std::cout << "250us = " << d1.count() << " microseconds\\n" - << "1ms = " << d2.count() << " microseconds\\n"; + std::cout << d1 << " = " << d1.count() << " microseconds\\n" + << 1ms << " = " << d2.count() << " microseconds\\n"; } .SH Output: @@ -69,4 +74,4 @@ .SH See also constructor constructs new duration - \fI(public member function of std::chrono::duration)\fP + \fI(public member function of std::chrono::duration)\fP diff --git "a/man/std::literals::chrono_literals::operator\"\"y.3" "b/man/std::literals::chrono_literals::operator\"\"y.3" new file mode 100644 index 000000000..4f9f76ca3 --- /dev/null +++ "b/man/std::literals::chrono_literals::operator\"\"y.3" @@ -0,0 +1,74 @@ +.TH std::literals::chrono_literals::operator""y 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::chrono_literals::operator""y \- std::literals::chrono_literals::operator""y + +.SH Synopsis + Defined in header + constexpr std::chrono::year operator""y( unsigned long long y ) \fI(since C++20)\fP + noexcept; + + Forms a std::chrono::year literal representing a year in the proleptic Gregorian + calendar. + +.SH Parameters + + y - the year value + +.SH Return value + + A std::chrono::year initialized from int(y). If y is not in the range + [-32767, 32767], the stored value is unspecified. + +.SH Possible implementation + + constexpr std::chrono::year operator""y(unsigned long long y) noexcept + { + return std::chrono::year(static_cast(y)); + } + +.SH Notes + + This operator is declared in the namespace std::literals::chrono_literals, where + both literals and chrono_literals are inline namespaces. Access to this operator can + be gained with: + + * using namespace std::literals, + * using namespace std::chrono_literals, or + * using namespace std::literals::chrono_literals. + + In addition, within the namespace std::chrono, the directive using namespace + literals::chrono_literals; is provided by the standard library, so that if a + programmer uses using namespace std::chrono; to gain access to the classes in the + chrono library, the corresponding literal operators become visible as well. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + std::cout << int(2020y) << '\\t' << 2020y << '\\n' + << int(-220y) << '\\t' << -220y << '\\n' + << int(3000y) << '\\t' << 3000y << '\\n' + << int(32768y) << '\\t' << 32768y << '\\n' // unspecified + << int(65578y) << '\\t' << 65578y << '\\n'; // unspecified + } + +.SH Possible output: + + 2020 2020 + -220 -0220 + 3000 3000 + -32768 -32768 is not a valid year + 42 0042 + +.SH See also + + constructor constructs a year + \fI(public member function of std::chrono::year)\fP diff --git "a/man/std::literals::complex_literals::operator\"\"i,operator\"\"if,operator\"\"il.3" "b/man/std::literals::complex_literals::operator\"\"i,operator\"\"if,operator\"\"il.3" new file mode 100644 index 000000000..21b20e0d1 --- /dev/null +++ "b/man/std::literals::complex_literals::operator\"\"i,operator\"\"if,operator\"\"il.3" @@ -0,0 +1,113 @@ +.TH std::literals::complex_literals::operator""i,operator""if,operator""il 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::complex_literals::operator""i,operator""if,operator""il \- std::literals::complex_literals::operator""i,operator""if,operator""il + +.SH Synopsis + Defined in header + constexpr complex operator""i( long double arg ); \fB(1)\fP \fI(since C++14)\fP + constexpr complex operator""i( unsigned long long arg ); + constexpr complex operator""if( long double arg ); \fB(2)\fP \fI(since C++14)\fP + constexpr complex operator""if( unsigned long long arg ); + constexpr complex operator""il( long double arg ); + constexpr complex operator""il( unsigned long long \fB(3)\fP \fI(since C++14)\fP + arg ); + + Forms a std::complex literal representing an imaginary number. + + 1) Forms a literal std::complex with the real part zero and imaginary part + arg. + 2) Forms a literal std::complex with the real part zero and imaginary part + arg. + 3) Forms a literal std::complex with the real part zero and imaginary + part arg. + +.SH Parameters + + arg - the value of the imaginary number + +.SH Return value + + The std::complex literal with the real part zero and imaginary part arg. + +.SH Notes + + These operators are declared in the namespace std::literals::complex_literals, where + both literals and complex_literals are inline namespaces. Access to these operators + can be gained with either: + + * using namespace std::literals, + * using namespace std::complex_literals, or + * using namespace std::literals::complex_literals. + + Even though if is a keyword in C++, it is a ud-suffix of the literal operator of the + form operator ""if and in the literal expressions such as 1if or 1.0if because it is + not separated by whitespace and is not a standalone token. + + Feature-test macro Value Std Feature + __cpp_lib_complex_udls 201309L \fI(C++14)\fP User-Defined Literals for std::complex + +.SH Possible implementation + + operator""i + constexpr std::complex operator""i(unsigned long long d) + { + return std::complex {0.0, static_cast(d)}; + } + + constexpr std::complex operator""i(long double d) + { + return std::complex {0.0, static_cast(d)}; + } + operator""if + constexpr std::complex operator""if(unsigned long long d) + { + return std::complex {0.0f, static_cast(d)}; + } + + constexpr std::complex operator""if(long double d) + { + return std::complex {0.0f, static_cast(d)}; + } + operator""il + constexpr std::complex operator""il(unsigned long long d) + { + return std::complex {0.0L, static_cast(d)}; + } + + constexpr std::complex operator""il(long double d) + { + return std::complex {0.0L, d}; + } + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::complex_literals; + + std::complex c = 1.0 + 1i; + std::cout << "abs" << c << " = " << std::abs(c) << '\\n'; + + std::complex z = 3.0f + 4.0if; + std::cout << "abs" << z << " = " << std::abs(z) << '\\n'; + } + +.SH Output: + + abs(1,1) = 1.41421 + abs(3,4) = 5 + +.SH See also + + constructor constructs a complex number + \fI(public member function)\fP + operator= assigns the contents + \fI(public member function)\fP + C documentation for + I diff --git "a/man/std::literals::string_literals::operator\"\"s.3" "b/man/std::literals::string_literals::operator\"\"s.3" index 07ab16c4f..a1ca31ea5 100644 --- "a/man/std::literals::string_literals::operator\"\"s.3" +++ "b/man/std::literals::string_literals::operator\"\"s.3" @@ -1,17 +1,27 @@ -.TH std::literals::string_literals::operator""s 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::literals::string_literals::operator""s 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::string_literals::operator""s \- std::literals::string_literals::operator""s + .SH Synopsis Defined in header - string operator "" s(const char *str, std::size_t len); \fB(1)\fP \fI(since C++14)\fP - u16string operator "" s(const char16_t *str, std::size_t len); \fB(2)\fP \fI(since C++14)\fP - u32string operator "" s(const char32_t *str, std::size_t len); \fB(3)\fP \fI(since C++14)\fP - wstring operator "" s(const wchar_t *str, std::size_t len); \fB(4)\fP \fI(since C++14)\fP + std::string operator""s( const char* str, std::size_t \fB(1)\fP \fI(since C++14)\fP + len ); (constexpr since C++20) + constexpr std::u8string operator""s( const char8_t* str, \fB(2)\fP \fI(since C++20)\fP + std::size_t len ); + std::u16string operator""s( const char16_t* str, \fB(3)\fP \fI(since C++14)\fP + std::size_t len ); (constexpr since C++20) + std::u32string operator""s( const char32_t* str, \fB(4)\fP \fI(since C++14)\fP + std::size_t len ); (constexpr since C++20) + std::wstring operator""s( const wchar_t* str, \fB(5)\fP \fI(since C++14)\fP + std::size_t len ); (constexpr since C++20) Forms a string literal of the desired type. - 1) returns std::string{str, len} - 2) returns std::u16string{str, len} - 3) returns std::u32string{str, len} - 4) returns std::wstring{str, len} + 1) Returns std::string{str, len}. + 2) Returns std::u8string{str, len}. + 3) Returns std::u16string{str, len}. + 4) Returns std::u32string{str, len}. + 5) Returns std::wstring{str, len}. .SH Parameters @@ -25,28 +35,56 @@ .SH Notes These operators are declared in the namespace std::literals::string_literals, where - both literals and string_literals are inline namespaces. + both literals and string_literals are inline namespaces. Access to these operators + can be gained with either + + * using namespace std::literals, or + * using namespace std::string_literals, or + * using namespace std::literals::string_literals. std::chrono::duration also defines operator""s, to represent literal seconds, but it - is an integer literal: 10s is ten seconds, but "10"s is a string. + is an arithmetic literal: 10.0s and 10s are ten seconds, but "10"s is a string. + + Feature-test macro Value Std Feature + __cpp_lib_string_udls 201304L \fI(C++14)\fP User-defined literals for string types .SH Example // Run this code + #include #include + void print_with_zeros(auto const note, std::string const& s) + { + std::cout << note; + for (const char c : s) + c ? std::cout << c : std::cout << "₀"; + std::cout << " (size = " << s.size() << ")\\n"; + } + int main() { - //no need to write 'using namespace std::literals::string_literals' using namespace std::string_literals; - std::string s2 = "abc\\0\\0def"; // forms the string "abc" - std::string s1 = "abc\\0\\0def"s; // form the string "abc\\0\\0def" + std::string s1 = "abc\\0\\0def"; + std::string s2 = "abc\\0\\0def"s; + print_with_zeros("s1: ", s1); + print_with_zeros("s2: ", s2); + + std::cout << "abcdef"s.substr(1,4) << '\\n'; } +.SH Output: + + s1: abc (size = 3) + s2: abc₀₀def (size = 8) + bcde + .SH See also constructor constructs a basic_string \fI(public member function)\fP + operator""sv creates a string view of a character array literal + \fI(C++17)\fP \fI(function)\fP diff --git "a/man/std::literals::string_view_literals::operator\"\"sv.3" "b/man/std::literals::string_view_literals::operator\"\"sv.3" new file mode 100644 index 000000000..ab066588a --- /dev/null +++ "b/man/std::literals::string_view_literals::operator\"\"sv.3" @@ -0,0 +1,108 @@ +.TH std::literals::string_view_literals::operator""sv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::literals::string_view_literals::operator""sv \- std::literals::string_view_literals::operator""sv + +.SH Synopsis + Defined in header + constexpr std::string_view \fB(1)\fP \fI(since C++17)\fP + operator ""sv( const char* str, std::size_t len ) noexcept; + constexpr std::u8string_view \fB(2)\fP \fI(since C++20)\fP + operator ""sv( const char8_t* str, std::size_t len ) noexcept; + constexpr std::u16string_view + operator ""sv( const char16_t* str, std::size_t len ) \fB(3)\fP \fI(since C++17)\fP + noexcept; + constexpr std::u32string_view + operator ""sv( const char32_t* str, std::size_t len ) \fB(4)\fP \fI(since C++17)\fP + noexcept; + constexpr std::wstring_view \fB(5)\fP \fI(since C++17)\fP + operator ""sv( const wchar_t* str, std::size_t len ) noexcept; + + Forms a string view of a character literal. + + 1) Returns std::string_view{str, len}. + 2) Returns std::u8string_view{str, len}. + 3) Returns std::u16string_view{str, len}. + 4) Returns std::u32string_view{str, len}. + 5) Returns std::wstring_view{str, len}. + +.SH Parameters + + str - pointer to the beginning of the raw character array literal + len - length of the raw character array literal + +.SH Return value + + The std::basic_string_view literal. + +.SH Notes + + These operators are declared in the namespace std::literals::string_view_literals, + where both literals and string_view_literals are inline namespaces. Access to these + operators can be gained with any of: + + * using namespace std::literals, + * using namespace std::string_view_literals, or + * using namespace std::literals::string_view_literals. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_each_character(const std::string_view sw) + { + for (char c : sw) + std::cout << (c == '\\0' ? '@' : c); + std::cout << '\\n'; + } + + int main() + { + using namespace std::literals; + + std::string_view s1 = "abc\\0\\0def"; + std::string_view s2 = "abc\\0\\0def"sv; + + std::cout << "s1.size(): " << s1.size() << "; s1: "; + print_each_character(s1); + std::cout << "s2.size(): " << s2.size() << "; s2: "; + print_each_character(s2); + + std::cout << "substr(1, 4): " << "abcdef"sv.substr(1, 4) << '\\n'; + + auto value_type_info = [](T) + { + using V = typename T::value_type; + std::cout << "sizeof " << typeid(V).name() << ": " << sizeof(V) << '\\n'; + }; + + value_type_info("char A"sv); + value_type_info(L"wchar_t ∀"sv); + value_type_info(u8"char8_t ∆"sv); + value_type_info(u"char16_t ∇"sv); + value_type_info(U"char32_t ∃"sv); + value_type_info(LR"(raw ⊞)"sv); + } + +.SH Possible output: + + s1.size(): 3; s1: abc + s2.size(): 8; s2: abc@@def + substr(1, 4): bcde + sizeof char: 1 + sizeof wchar_t: 4 + sizeof char8_t: 1 + sizeof char16_t: 2 + sizeof char32_t: 4 + sizeof wchar_t: 4 + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + operator""s converts a character array literal to basic_string + \fI(C++14)\fP \fI(function)\fP diff --git a/man/std::locale.3 b/man/std::locale.3 index 276ef64ad..9a6d13893 100644 --- a/man/std::locale.3 +++ b/man/std::locale.3 @@ -1,47 +1,62 @@ -.TH std::locale 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale \- std::locale + .SH Synopsis Defined in header class locale; - An object of class std::locale is an indexed set of reference-counted pointers to - facets. Each stream object of the C++ input/output library is associated with an - std::locale and uses its facets for parsing and formatting of all data. In addition, - a locale object is associated with each basic_regex object. Locale objects can also - be used as predicates that perform string collation with the standard containers and - algorithms and can be accessed directly to obtain or modify the facets they hold. + An object of class std::locale is an immutable indexed set of immutable facets. Each + stream object of the C++ input/output library is associated with an std::locale + object and uses its facets for parsing and formatting of all data. + In addition, a locale object is associated with each std::basic_regex object. + \fI(since C++11)\fP Locale objects can also be used as predicates that perform string + collation with the standard containers and algorithms and can be accessed directly + to obtain or modify the facets they hold. Each locale constructed in a C++ program holds at least the following standard - facets, but a program may define additional specializations or completely new facets - and add them to any existing locale object. - - Supported facets - std::collate std::collate - std::ctype std::ctype - std::codecvt std::codecvt - std::codecvt std::codecvt - std::moneypunct std::moneypunct - std::moneypunct std::moneypunct - std::money_get std::money_get - std::money_put std::money_put - std::numpunct std::numpunct - std::num_get std::num_get - std::num_put std::num_put - std::time_get std::time_get - std::time_put std::time_put - std::messages std::messages - - Locale objects are immutable: since each facet may be shared among many locale - objects, altering a facet in one locale would change the behavior of unrelated - locale objects. + facets (i.e. std::has_facet returns true for all these facet types), but a program + may define additional specializations or completely new facets and add them to any + existing locale object. + + Supported facets + std::collate std::codecvt + std::collate std::codecvt + std::codecvt (since + std::ctype C++20) + std::ctype std::codecvt (since + C++20) + std::money_get std::moneypunct + std::money_get std::moneypunct + std::money_put std::moneypunct + std::money_put std::moneypunct + std::num_get + std::num_get std::numpunct + std::num_put std::numpunct + std::num_put + std::time_get + std::time_get std::messages + std::time_put std::messages + std::time_put + Deprecated facets + std::codecvt \fI(since C++11)\fP(deprecated in C++20) + std::codecvt \fI(since C++11)\fP(deprecated in C++20) + + Internally, a locale object is implemented as if it is a reference-counted pointer + to an array (indexed by std::locale::id) of reference-counted pointers to facets: + copying a locale only copies one pointer and increments several reference counts. To + maintain the standard C++ library thread safety guarantees (operations on different + objects are always thread-safe), both the locale reference count and each facet + reference count are updated in a thread-safe manner, similar to std::shared_ptr. .SH Member types the facet index type: each facet class must declare or inherit a public id static member of this type - \fI(class)\fP + \fI(class)\fP the base class for all facet categories: each facet of any category is facet derived from this type - \fI(class)\fP + \fI(class)\fP category int \fI(typedef)\fP @@ -64,65 +79,85 @@ all collate | ctype | monetary | numeric | time | messages \fB[static]\fP \fI(public static member constant)\fP + std::locale member functions expecting a category argument require one of the + category values defined above, or the union of two or more such values. The LC + constants are not accepted. + .SH Member functions - constructor constructs a new locale - \fI(public member function)\fP - destructor destructs the locale and the facets whose reference count becomes zero - \fI(public member function)\fP - operator= replaces a locale - \fI(public member function)\fP - constructs a locale with compile-time identified facet copied from - combine another locale - \fI(public member function)\fP - name returns the name of the locale or "*" if unnamed - \fI(public member function)\fP - operator== equality comparison between locale objects - operator!= \fI(public member function)\fP - lexicographically compares two strings using this locale's collate - operator() facet - \fI(public member function)\fP - global changes the global locale - \fB[static]\fP \fI(public static member function)\fP - classic obtains a reference to the "C" locale - \fB[static]\fP \fI(public static member function)\fP + constructor constructs a new locale + \fI(public member function)\fP + destructs the locale and the facets whose reference count becomes + destructor zero + \fI(public member function)\fP + operator= replaces a locale + \fI(public member function)\fP + constructs a locale with compile-time identified facet copied + combine from another locale + \fI(public member function)\fP + name returns the name of the locale or "*" if unnamed + \fI(public member function)\fP + operator== equality comparison between locale objects + operator!= \fI(public member function)\fP + (removed in C++20) + lexicographically compares two strings using this locale's + operator() collate facet + \fI(public member function)\fP + global changes the global locale + \fB[static]\fP \fI(public static member function)\fP + classic obtains a reference to the "C" locale + \fB[static]\fP \fI(public static member function)\fP .SH Example - Demonstrates the typical prologue of a locale-sensitive program (cross-platform) + Demonstrates the typical prologue of a locale-sensitive program (cross-platform). + - // Run this code #include #include - + int main() { - std::wcout << "User-preferred locale setting is " << std::locale("").name().c_str() << '\\n'; + std::wcout << "User-preferred locale setting is " + << std::locale("").name().c_str() << '\\n'; // on startup, the global locale is the "C" locale std::wcout << 1000.01 << '\\n'; - // replace the C++ global locale as well as the C locale with the user-preferred locale + + // replace the C++ global locale and the "C" locale with the user-preferred locale std::locale::global(std::locale("")); // use the new global locale for future wide character output std::wcout.imbue(std::locale()); + // output the same number again std::wcout << 1000.01 << '\\n'; } -.SH Output: +.SH Possible output: User-preferred locale setting is en_US.UTF8 1000.01 1,000.01 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 340 C++98 the set of standard facets that all locales made clear + need to hold was unclear + LWG 347 C++98 parameters of type category could accept LC not accepted anymore + constants + .SH See also use_facet obtains a facet from a locale - \fI(function template)\fP + \fI(function template)\fP has_facet checks if a locale implements a specific facet - \fI(function template)\fP + \fI(function template)\fP imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP diff --git a/man/std::locale::classic.3 b/man/std::locale::classic.3 index e809bab4d..93d43686e 100644 --- a/man/std::locale::classic.3 +++ b/man/std::locale::classic.3 @@ -1,4 +1,7 @@ -.TH std::locale::classic 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::classic 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::classic \- std::locale::classic + .SH Synopsis Defined in header static const locale& classic(); @@ -29,8 +32,7 @@ .SH See also global changes the global locale - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP .SH Category: - * Todo no example diff --git a/man/std::locale::combine.3 b/man/std::locale::combine.3 index a4e233f16..6e299631f 100644 --- a/man/std::locale::combine.3 +++ b/man/std::locale::combine.3 @@ -1,4 +1,7 @@ -.TH std::locale::combine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::combine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::combine \- std::locale::combine + .SH Synopsis Defined in header template< class Facet > @@ -7,27 +10,31 @@ Constructs a locale object which is a copy of *this except for the facet of type Facet, which is copied from other. + The program is ill-formed if Facet is not a facet or it is a volatile-qualified + facet. + .SH Return value The new, nameless, locale. .SH Exceptions - std::runtime_error if other does not implement Facet + std::runtime_error if other does not implement Facet. .SH Example - + // Run this code #include #include - + int main() { const double number = 1000.25; std::cout << "\\"C\\" locale: " << number << '\\n'; - std::locale loc = std::locale().combine>(std::locale("en_US.UTF8")); + std::locale loc = std::locale() + .combine>(std::locale("en_US.UTF8")); std::cout.imbue(loc); std::cout << "\\"C\\" locale with en_US numpunct: " << number << '\\n'; } @@ -37,7 +44,17 @@ "C" locale: 1000.25 "C" locale with en_US numpunct: 1,000.25 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 14 C++98 locale::combine was non-const made const + LWG 436 C++98 it was unclear whether Facet it can be const-qualified, but not + can be cv-qualified volatile-qualified + .SH See also constructor constructs a new locale - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::locale::facet.3 b/man/std::locale::facet.3 index 2f7e22cfe..8cc517293 100644 --- a/man/std::locale::facet.3 +++ b/man/std::locale::facet.3 @@ -1,16 +1,20 @@ -.TH std::locale::facet 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::facet 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::facet \- std::locale::facet + .SH Synopsis Defined in header class locale::facet; std::locale::facet is the base class for facets. It provides a common base class so that locales could store pointers to the facets they implement in a single indexed - container, and it abstracts support for facet reference counting. Whenever a facet - is added to a locale, the locale increments the reference count in the facet - (through an implementation-specific mechanism). Whenever a locale is destructed or - modified, it decrements the reference count in each facet it no longer implements. - Whenever a facet's reference count becomes zero, the locale performs delete - static_cast(f) where f is the pointer to the facet. + container, and it abstracts support for facet reference counting. + + Whenever a facet is added to a locale, the locale increments the reference count in + the facet (through an implementation-specific mechanism). Whenever a locale is + destructed or modified, it decrements the reference count in each facet it no longer + implements. Whenever a facet's reference count becomes zero, the locale performs + delete static_cast(f); where f is the pointer to the facet. .SH Member functions @@ -26,12 +30,20 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2694 C++98 the definition of 'facet' was removed by added the definition + the resolution of LWG issue 436 back + .SH See also the facet index type: each facet class must declare or inherit a public static id member of this type - \fI(class)\fP + \fI(class)\fP .SH Category: - * Todo no example diff --git a/man/std::locale::facet::facet.3 b/man/std::locale::facet::facet.3 index cd5d63d28..20ee0f0d8 100644 --- a/man/std::locale::facet::facet.3 +++ b/man/std::locale::facet::facet.3 @@ -1,12 +1,14 @@ -.TH std::locale::facet::facet 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::facet::facet 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::facet::facet \- std::locale::facet::facet + .SH Synopsis Defined in header explicit facet( std::size_t refs = 0 ); \fB(1)\fP - facet(const facet&) = delete; \fB(2)\fP + facet( const facet& ) = delete; \fB(2)\fP - 1) creates a facet with starting reference count refs. If refs is non-zero, the + 1) Creates a facet with starting reference count refs. If refs is non-zero, the facet will not be deleted when the last locale referencing it goes out of scope. A facet with static or dynamic storage duration should always be constructed with a non-zero refs. - - 2) copy constructor is deleted; std::locale::facet is not copyable. + 2) Copy constructor is deleted; std::locale::facet is not copyable. diff --git a/man/std::locale::global.3 b/man/std::locale::global.3 index 184b13365..78d341dc1 100644 --- a/man/std::locale::global.3 +++ b/man/std::locale::global.3 @@ -1,4 +1,7 @@ -.TH std::locale::global 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::global 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::global \- std::locale::global + .SH Synopsis Defined in header static locale global( const locale& loc ); @@ -22,15 +25,25 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unspecified whether other library specified (no other + LWG 8 C++98 functions (such library functions + as std::setlocale) can modify the global C++ allowed) + locale + .SH See also constructor constructs a new locale - \fI(public member function)\fP + \fI(public member function)\fP classic obtains a reference to the "C" locale - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP setlocale gets and sets the current C locale - \fI(function)\fP + \fI(function)\fP .SH Category: - * Todo no example diff --git a/man/std::locale::id.3 b/man/std::locale::id.3 index 0bd0378a2..6e33aa9bd 100644 --- a/man/std::locale::id.3 +++ b/man/std::locale::id.3 @@ -1,12 +1,15 @@ -.TH std::locale::id 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::id \- std::locale::id + .SH Synopsis Defined in header class locale::id; The class std::locale::id provides implementation-specific identification of a - locale facet. Each class derived from std::locale::facet must have a public static - member of type std::locale::id and each std::locale object maintains a list of - facets it implements, indexed by their ids. + locale facet. Each facet has a public static member named id of type std::locale::id + and each std::locale object maintains a list of facets it implements, indexed by + their ids. Facets with the same id belong to the same facet category and replace each other when added to a locale object. @@ -22,20 +25,20 @@ The following example shows how to construct a minimal custom facet. - + // Run this code #include #include - + struct myfacet : std::locale::facet { myfacet(std::size_t refs = 0) : facet(refs) {} - static std::locale::id id; + static ::std::locale::id id; }; - + std::locale::id myfacet::id; - + int main() { std::locale myloc(std::locale(), new myfacet); @@ -51,4 +54,4 @@ the base class for all facet categories: each facet of any category is derived facet from this type - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::locale::id::id.3 b/man/std::locale::id::id.3 index d6925746c..eb12ff881 100644 --- a/man/std::locale::id::id.3 +++ b/man/std::locale::id::id.3 @@ -1,13 +1,15 @@ -.TH std::locale::id::id 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::id::id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::id::id \- std::locale::id::id + .SH Synopsis Defined in header id(); \fB(1)\fP - id(const id&) = delete; \fB(2)\fP + id( const id& ) = delete; \fB(2)\fP - 1) default constructor: creates an object of type std::locale::id with + 1) Default constructor: creates an object of type std::locale::id with implementation-specific content. - - 2) copy constructor is deleted; std::locale::id is not copyable. + 2) Copy constructor is deleted; std::locale::id is not copyable. .SH Notes diff --git a/man/std::locale::locale.3 b/man/std::locale::locale.3 index 0d35e43d6..da005de9b 100644 --- a/man/std::locale::locale.3 +++ b/man/std::locale::locale.3 @@ -1,95 +1,142 @@ -.TH std::locale::locale 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::locale 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::locale \- std::locale::locale + .SH Synopsis Defined in header - locale(); \fB(1)\fP - locale( const locale& other ); \fB(2)\fP - explicit locale( const char* std_name ); \fB(3)\fP - explicit locale( const std::string& std_name ); \fB(4)\fP - locale( const locale& other, const char* std_name, category cat ); \fB(5)\fP - locale( const locale& other, const std::string& std_name, category cat ); \fB(6)\fP - template< class Facet > \fB(7)\fP + locale() throw(); \fI(until C++11)\fP + locale() noexcept; \fI(since C++11)\fP + locale( const locale& other ) throw(); \fI(until C++11)\fP + locale( const locale& other ) noexcept; \fI(since C++11)\fP + explicit locale( const char* std_name ); \fB(3)\fP + explicit locale( const std::string& std_name ); \fB(4)\fP \fI(since C++11)\fP + locale( const locale& other, const char* \fB(1)\fP \fB(5)\fP + std_name, category cats ); \fB(2)\fP + locale( const locale& other, const std::string& \fB(6)\fP \fI(since C++11)\fP + std_name, category cats ); + template< class Facet > \fB(7)\fP locale( const locale& other, Facet* f ); - locale( const locale& other, const locale& one, category cat ); \fB(8)\fP + locale( const locale& other, const locale& one, \fB(8)\fP + category cats ); - Contstructs a new locale object. + Constructs a new locale object. 1) Default constructor. Constructs a copy of the global C++ locale, which is the locale most recently used as the argument to std::locale::global or a copy of - std::locale::classic if no call to std::locale::global has been made. + std::locale::classic() if no call to std::locale::global has been made. 2) Copy constructor. Constructs a copy of other. - 3-4) Constructs a copy of the system locale with specified std_name (such as "C", or + 3,4) Constructs a copy of the system locale with specified std_name (such as "C", or "POSIX", or "en_US.UTF-8", or "English_US.1251"), if such locale is supported by the operating system. The locale constructed in this manner has a name. - 5-6) Constructs a copy of other except for all the facets identified by the cat + 4) Equivalent to locale(std_name.c_str()). + 5) Constructs a copy of other except for all the facets identified by the cats argument, which are copied from the system locale identified by its std_name. The - locale constructed in this manner has the same name as other. + locale constructed in this manner has a name if and only if other has a name. + 6) Equivalent to locale(other, std_name.c_str(), cats). 7) Constructs a copy of other except for the facet of type Facet (typically deduced - from the type of the argument) which is installed from the argument facet. If facet - is NULL, the constructed locale is a full copy of other. The locale constructed in - this manner has no name. - 8) Constructs a copy of other except for all the facets identified by the cat - argument, which are copied from one. If both other and one have names, then the - resulting locale also has a name. + from the type of the argument) which is installed from f. If f is a null pointer, + the constructed locale is a full copy of other. The program is ill-formed if Facet + is not a facet or it is a volatile-qualified facet. + If f is null, the constructed locale has the same name as other. Otherwise, the + constructed locale has no name. + 8) Constructs a copy of other except for all the facets identified by the cats + argument, which are copied from one. + If cats is equal to locale::none, the constructed locale has a name if and only if + other has a name. Otherwise, the constructed locale has a name if and only if other + and one both have names. .SH Parameters other - another locale to copy std_name - name of the system locale to use f - pointer to a facet to merge with other - cat - the locale category used to identify the facets to merge with other + cats - the facet categories used to identify the facets to merge with other one - another locale to take facets from .SH Exceptions - 1-2) - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - 3) std::runtime_error if the operating system has no locale named std_name or if - std_name is NULL. - 4) std::runtime_error if the operating system has no locale named std_name. - 5) std::runtime_error if the operating system has no locale named std_name or if - std_name is NULL. - 6) std::runtime_error if the operating system has no locale named std_name. - 7-8) \fI(none)\fP + 3,5) std::runtime_error if the operating system has no locale named std_name or if + std_name is a null pointer. + 4,6) std::runtime_error if the operating system has no locale named std_name. .SH Notes - Overload 7 is typically called with its second argument, f, obtained directly from a - new-expression: the locale is responsible for calling the matching delete from its + Overload \fB(7)\fP is typically called with its second argument, f, obtained directly from + a new-expression: the locale is responsible for calling the matching delete from its own destructor. .SH Example - + // Run this code + #include #include #include - #include - + + std::ostream& operator<< (std::ostream& os, std::locale const& loc) + { + if (loc.name().length() <= 80) + return os << loc.name() << '\\n'; + + for (const auto c : loc.name()) + c != ';' ? os << c : os << "\\n "; + return os << '\\n'; + } + int main() { - std::locale l1; // l1 is a copy of the classic "C" locale - std::locale l2("en_US.UTF-8"); // l2 is a unicode locale - std::locale l3(l1, l2, std::locale::ctype); // l3 is "C" except for ctype, which is unicode - std::locale l4(l1, new std::codecvt_utf8); // l4 is "C" except for codecvt - std::cout << "Locale names:\\nl1: " << l1.name() << "\\nl2: " << l2.name() - << "\\nl3: " << l3.name() << "\\nl4: " << l4.name() << '\\n'; + // l1 is a copy of the classic "C" locale + std::locale l1; + // l2 is a unicode locale + std::locale l2("en_US.UTF-8"); + // l3 is "C" except for ctype, which is unicode + std::locale l3(l1, l2, std::locale::ctype); + // l4 is "C" except for codecvt + std::locale l4(l1, new std::codecvt_utf8); + + std::cout + << "Locale names:\\n" + << "l1: " << l1 << "l2: " << l2 + << "l3: " << l3 << "l4: " << l4; } -.SH Output: +.SH Possible output: Locale names: l1: C l2: en_US.UTF-8 - l3: LC_CTYPE=en_US.UTF-8;LC_NUMERIC=C;LC_TIME=C;LC_COLLATE=C;LC_MONETARY=C;LC_MESSAGES=C;LC_PAPER=C;LC_NAME=C;LC_ADDRESS=C;LC_TELEPHONE=C;LC_MEASUREMENT=C;LC_IDENTIFICATION=C + l3: LC_CTYPE=en_US.UTF-8 + LC_NUMERIC=C + LC_TIME=C + LC_COLLATE=C + LC_MONETARY=C + LC_MESSAGES=C + LC_PAPER=C + LC_NAME=C + LC_ADDRESS=C + LC_TELEPHONE=C + LC_MEASUREMENT=C + LC_IDENTIFICATION=C l4: * + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 436 C++98 for overload \fB(7)\fP, it was unclear it can be const-qualified, + whether Facet can be cv-qualified but not volatile-qualified + LWG 2295 C++98 for overload \fB(7)\fP, the constructed it has the name of other + locale had no name even if f is null + .SH See also destructor destructs the locale and the facets whose reference count becomes zero - \fI(public member function)\fP + \fI(public member function)\fP + +.SH External links + + 1. List of Windows locale names. + 2. List of Linux locale names. diff --git a/man/std::locale::name.3 b/man/std::locale::name.3 index 53736043e..d7582cc05 100644 --- a/man/std::locale::name.3 +++ b/man/std::locale::name.3 @@ -1,4 +1,7 @@ -.TH std::locale::name 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::name \- std::locale::name + .SH Synopsis Defined in header std::string name() const; @@ -13,13 +16,13 @@ .SH Example - + // Run this code - #include #include + #include #include - + int main() { std::locale loc(std::locale(), new std::ctype); @@ -28,7 +31,7 @@ << "A nameless locale is " << loc.name() << '\\n'; } -.SH Output: +.SH Possible output: The default locale is C The user's locale is en_US.UTF8 @@ -37,4 +40,4 @@ .SH See also constructor constructs a new locale - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::locale::operator().3 b/man/std::locale::operator().3 index 1954b2e05..e43177775 100644 --- a/man/std::locale::operator().3 +++ b/man/std::locale::operator().3 @@ -1,15 +1,18 @@ -.TH std::locale::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::operator() \- std::locale::operator() + .SH Synopsis template< class CharT, class Traits, class Alloc > bool operator()( const basic_string& s1, - const basic_string& s2) const; + const basic_string& s2 ) const; Compares two string arguments s1 and s2 according to the lexicographic comparison - rules defined by this locale's std::collate facet. This operator allows any + rules defined by this locale's std::collate facet. This operator allows any locale object that has a collate facet to be used as a binary predicate in the - standard algorithms (such as std::sort) and ordered containers (such as std::set) + standard algorithms (such as std::sort) and ordered containers (such as std::set). .SH Parameters @@ -22,13 +25,13 @@ .SH Possible implementation - template + template bool operator()(const std::basic_string& s1, const std::basic_string& s2) const; { return std::use_facet>(*this).compare( - s1.data(), s1.data() + s1.size(), - s2.data(), s2.data() + s2.size() ) < 0; + s1.data(), s1.data() + s1.size(), + s2.data(), s2.data() + s2.size()) < 0; } .SH Example @@ -36,25 +39,25 @@ A vector of strings can be sorted according to a non-default locale by using the locale object as comparator: - + // Run this code - #include #include - #include - #include #include - + #include + #include + #include + int main() { - std::vector v = {L"жил", L"был", L"кот"}; + std::vector v = {L"жил", L"был", L"пёс"}; std::sort(v.begin(), v.end(), std::locale("ru_RU.UTF8")); assert(v[0] == L"был"); assert(v[1] == L"жил"); - assert(v[2] == L"кот"); + assert(v[2] == L"пёс"); } .SH See also collate defines lexicographical comparison and hashing of strings - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::locale::operator=.3 b/man/std::locale::operator=.3 index 043a19dc2..b06a4ac11 100644 --- a/man/std::locale::operator=.3 +++ b/man/std::locale::operator=.3 @@ -1,7 +1,11 @@ -.TH std::locale::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::operator= \- std::locale::operator= + .SH Synopsis Defined in header - const locale& operator=( const locale& other ); + const locale& operator=( const locale& other ) throw(); \fI(until C++11)\fP + const locale& operator=( const locale& other ) noexcept; \fI(since C++11)\fP Creates a copy of other, replacing the contents of *this. The reference counts of all facets held by other are incremented. The reference counts of all facets @@ -12,13 +16,6 @@ Returns *this, which is now a copy of other. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Example This section is incomplete @@ -27,8 +24,7 @@ .SH See also constructor constructs a new locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::locale::operator==,operator!=.3 b/man/std::locale::operator==,operator!=.3 index 1fb981ec0..07b86a15b 100644 --- a/man/std::locale::operator==,operator!=.3 +++ b/man/std::locale::operator==,operator!=.3 @@ -1,12 +1,17 @@ -.TH std::locale::operator==,operator!= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::operator==,operator!= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::operator==,operator!= \- std::locale::operator==,operator!= + .SH Synopsis Defined in header bool operator==( const locale& other ) const; \fB(1)\fP - bool operator!=( const locale& other ) const; \fB(2)\fP + bool operator!=( const locale& other ) const; \fB(2)\fP \fI(until C++20)\fP Tests two locales for equality. Named locales are considered equal if their names are equal. Unnamed locales are considered equal if they are copies of each other. + The != operator is synthesized from operator==. \fI(since C++20)\fP + .SH Parameters other - a std::locale object to compare @@ -14,7 +19,6 @@ .SH Return value 1) true if other is a copy of *this or has an identical name, false otherwise. - 2) false if other is a copy of *this or has an identical name, true otherwise. .SH Example @@ -25,10 +29,9 @@ .SH See also constructor constructs a new locale - \fI(public member function)\fP + \fI(public member function)\fP name returns the name of the locale or "*" if unnamed - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::locale::~locale.3 b/man/std::locale::~locale.3 index 361a42e33..ec7b14c81 100644 --- a/man/std::locale::~locale.3 +++ b/man/std::locale::~locale.3 @@ -1,4 +1,7 @@ -.TH std::locale::~locale 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::locale::~locale 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::locale::~locale \- std::locale::~locale + .SH Synopsis Defined in header ~locale(); @@ -10,10 +13,6 @@ \fI(none)\fP -.SH Exceptions - - \fI(none)\fP - .SH Example This section is incomplete @@ -22,8 +21,7 @@ .SH See also constructor constructs a new locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::localeconv.3 b/man/std::localeconv.3 index 1bd9e4ddb..5183f5635 100644 --- a/man/std::localeconv.3 +++ b/man/std::localeconv.3 @@ -1,4 +1,7 @@ -.TH std::localeconv 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::localeconv 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::localeconv \- std::localeconv + .SH Synopsis Defined in header std::lconv* localeconv(); @@ -23,13 +26,13 @@ .SH Example - - + + // Run this code #include #include - + int main() { std::setlocale(LC_ALL, "ja_JP.UTF-8"); @@ -45,8 +48,8 @@ .SH See also setlocale gets and sets the current C locale - \fI(function)\fP + \fI(function)\fP lconv formatting details, returned by std::localeconv - \fI(class)\fP + \fI(class)\fP C documentation for localeconv diff --git a/man/std::localtime.3 b/man/std::localtime.3 index a95565b7b..def510328 100644 --- a/man/std::localtime.3 +++ b/man/std::localtime.3 @@ -1,20 +1,23 @@ -.TH std::localtime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::localtime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::localtime \- std::localtime + .SH Synopsis Defined in header - std::tm* localtime( const std::time_t *time ); + std::tm* localtime( const std::time_t* time ); Converts given time since epoch as std::time_t value into calendar time, expressed in local time. .SH Parameters - time - pointer to a time_t object to convert + time - pointer to a std::time_t object to convert .SH Return value - pointer to a static internal std::tm object on success, or NULL otherwise. The - structure may be shared between std::gmtime, std::localtime, and std::ctime, and may - be overwritten on each invocation. + Pointer to a static internal std::tm object on success, or null pointer otherwise. + The structure may be shared between std::gmtime, std::localtime, and std::ctime, and + may be overwritten on each invocation. .SH Notes @@ -23,31 +26,50 @@ POSIX requires that this function sets errno to EOVERFLOW if it fails because the argument is too large. + POSIX specifies that the timezone information is determined by this function as if + by calling tzset, which reads the environment variable TZ. + .SH Example - + // Run this code - #include - #include #include - + #include + #include + #include + int main() { - std::time_t t = std::time(nullptr); + setenv("TZ", "/usr/share/zoneinfo/America/Los_Angeles", 1); // POSIX-specific + + std::tm tm{}; // Zero initialise + tm.tm_year = 2020 - 1900; // 2020 + tm.tm_mon = 2 - 1; // February + tm.tm_mday = 15; // 15th + tm.tm_hour = 10; + tm.tm_min = 15; + tm.tm_isdst = 0; // Not daylight saving + std::time_t t = std::mktime(&tm); + std::cout << "UTC: " << std::put_time(std::gmtime(&t), "%c %Z") << '\\n'; std::cout << "local: " << std::put_time(std::localtime(&t), "%c %Z") << '\\n'; } -.SH Output: +.SH Possible output: - UTC: Wed Dec 28 11:47:03 2011 GMT - local: Wed Dec 28 06:47:03 2011 EST + UTC: Sat Feb 15 18:15:00 2020 GMT + local: Sat Feb 15 10:15:00 2020 PST .SH See also - converts time since epoch to calendar time expressed as Universal Coordinated - gmtime Time - \fI(function)\fP + converts time since epoch to calendar time expressed as Universal + gmtime Coordinated Time + \fI(function)\fP + localtime + localtime_r converts time since epoch to calendar time expressed as local time + localtime_s \fI(function)\fP + (C23) + (C11) C documentation for localtime diff --git a/man/std::lock.3 b/man/std::lock.3 index 5755ac3df..f393ca6b8 100644 --- a/man/std::lock.3 +++ b/man/std::lock.3 @@ -1,15 +1,18 @@ -.TH std::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lock \- std::lock + .SH Synopsis Defined in header - template< class Lockable1, class Lockable2, class LockableN... > \fI(since C++11)\fP - void lock( Lockable1& lock1, Lockable2& lock2, LockableN& lockn... ); + template< class Lockable1, class Lockable2, class... LockableN > \fI(since C++11)\fP + void lock( Lockable1& lock1, Lockable2& lock2, LockableN&... lockn ); Locks the given Lockable objects lock1, lock2, ..., lockn using a deadlock avoidance algorithm to avoid deadlock. - The objects are locked by an unspecified series of calls to lock, try_lock, unlock. - If a call to lock or unlock results in an exception, unlock is called for any locked - objects before rethrowing. + The objects are locked by an unspecified series of calls to lock, try_lock, and + unlock. If a call to lock or unlock results in an exception, unlock is called for + any locked objects before rethrowing. .SH Parameters @@ -24,65 +27,117 @@ Boost provides a version of this function that takes a sequence of Lockable objects defined by a pair of iterators. + std::scoped_lock offers a RAII wrapper for this function, and is generally preferred + to a naked call to std::lock. + .SH Example The following example uses std::lock to lock pairs of mutexes without deadlock. - + // Run this code + #include + #include + #include #include + #include #include - #include #include - #include - #include - - struct Employee { - Employee(int id) : id(id) {} - int id; - std::vector lunch_partners; + + struct Employee + { + Employee(std::string id) : id(id) {} + std::string id; + std::vector lunch_partners; std::mutex m; + std::string output() const + { + std::string ret = "Employee " + id + " has lunch partners: "; + for (auto n{lunch_partners.size()}; const auto& partner : lunch_partners) + ret += partner + (--n ? ", " : ""); + return ret; + } }; - - void send_mail(Employee &e1, Employee &e2) + + void send_mail(Employee&, Employee&) { - // simulate a time-consuming messaging operation - std::this_thread::sleep_for(std::chrono::seconds(1)); + // Simulate a time-consuming messaging operation + std::this_thread::sleep_for(std::chrono::milliseconds(696)); } - - void assign_lunch_partner(Employee &e1, Employee &e2) + + void assign_lunch_partner(Employee& e1, Employee& e2) { - // use std::lock to acquire two locks without worrying about + static std::mutex io_mutex; + { + std::lock_guard lk(io_mutex); + std::cout << e1.id << " and " << e2.id << " are waiting for locks" << std::endl; + } + + // Use std::lock to acquire two locks without worrying about // other calls to assign_lunch_partner deadlocking us - std::lock(e1.m, e2.m); - - e1.lunch_partners.push_back(e2.id); - e2.lunch_partners.push_back(e1.id); - - e1.m.unlock(); - e2.m.unlock(); - + { + std::lock(e1.m, e2.m); + std::lock_guard lk1(e1.m, std::adopt_lock); + std::lock_guard lk2(e2.m, std::adopt_lock); + // Equivalent code (if unique_locks are needed, e.g. for condition variables) + // std::unique_lock lk1(e1.m, std::defer_lock); + // std::unique_lock lk2(e2.m, std::defer_lock); + // std::lock(lk1, lk2); + // Superior solution available in C++17 + // std::scoped_lock lk(e1.m, e2.m); + { + std::lock_guard lk(io_mutex); + std::cout << e1.id << " and " << e2.id << " got locks" << std::endl; + } + e1.lunch_partners.push_back(e2.id); + e2.lunch_partners.push_back(e1.id); + } send_mail(e1, e2); send_mail(e2, e1); } - + int main() { - Employee alice(0), bob(1), christina(2), dave(3); - - // assign in parallel threads because mailing users about lunch assignments + Employee alice("Alice"), bob("Bob"), christina("Christina"), dave("Dave"); + + // Assign in parallel threads because mailing users about lunch assignments // takes a long time std::vector threads; threads.emplace_back(assign_lunch_partner, std::ref(alice), std::ref(bob)); threads.emplace_back(assign_lunch_partner, std::ref(christina), std::ref(bob)); threads.emplace_back(assign_lunch_partner, std::ref(christina), std::ref(alice)); threads.emplace_back(assign_lunch_partner, std::ref(dave), std::ref(bob)); - - for (auto &thread : threads) thread.join(); + + for (auto& thread : threads) + thread.join(); + + std::cout << alice.output() << '\\n' + << bob.output() << '\\n' + << christina.output() << '\\n' + << dave.output() << '\\n'; } +.SH Possible output: + + Alice and Bob are waiting for locks + Alice and Bob got locks + Christina and Bob are waiting for locks + Christina and Bob got locks + Christina and Alice are waiting for locks + Dave and Bob are waiting for locks + Dave and Bob got locks + Christina and Alice got locks + Employee Alice has lunch partners: Bob, Christina + Employee Bob has lunch partners: Alice, Christina, Dave + Employee Christina has lunch partners: Bob, Alice + Employee Dave has lunch partners: Bob + .SH See also - try_lock attempts to obtain ownership of mutexes via repeated calls to try_lock - \fI(C++11)\fP \fI(function template)\fP + unique_lock implements movable mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + try_lock attempts to obtain ownership of mutexes via repeated calls to try_lock + \fI(C++11)\fP \fI(function template)\fP + scoped_lock deadlock-avoiding RAII wrapper for multiple mutexes + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::lock_guard.3 b/man/std::lock_guard.3 index e30754740..f078a3779 100644 --- a/man/std::lock_guard.3 +++ b/man/std::lock_guard.3 @@ -1,4 +1,7 @@ -.TH std::lock_guard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lock_guard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lock_guard \- std::lock_guard + .SH Synopsis Defined in header template< class Mutex > \fI(since C++11)\fP @@ -26,51 +29,100 @@ .SH Member functions constructor constructs a lock_guard, optionally locking the given mutex - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the lock_guard object, unlocks the underlying mutex - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP + +.SH Notes + + A common beginner error is to "forget" to give a lock_guard variable a name, e.g. + std::lock_guard(mtx); (which default constructs a lock_guard variable named mtx) or + std::lock_guard{mtx}; (which constructs a prvalue object that is immediately + destroyed), thereby not actually constructing a lock that holds a mutex for the rest + of the scope. + + std::scoped_lock offers an alternative for lock_guard that provides + the ability to lock multiple mutexes using a deadlock avoidance \fI(since C++17)\fP + algorithm. .SH Example - + Demonstrates safe and unsafe increments of a volatile variable by two threads. + + // Run this code - #include - #include #include - - int g_i = 0; + #include + #include + #include + #include + + volatile int g_i = 0; std::mutex g_i_mutex; // protects g_i - - void safe_increment() + + void safe_increment(int iterations) { - std::lock_guard lock(g_i_mutex); - ++g_i; - - std::cout << std::this_thread::get_id() << ": " << g_i << '\\n'; - - // g_i_mutex is automatically released when lock - // goes out of scope + const std::lock_guard lock(g_i_mutex); + while (iterations-- > 0) + g_i = g_i + 1; + std::cout << "thread #" << std::this_thread::get_id() << ", g_i: " << g_i << '\\n'; + + // g_i_mutex is automatically released when lock goes out of scope + } + + void unsafe_increment(int iterations) + { + while (iterations-- > 0) + g_i = g_i + 1; + std::osyncstream(std::cout) << "thread #" << std::this_thread::get_id() + << ", g_i: " << g_i << '\\n'; } - + int main() { - std::cout << __func__ << ": " << g_i << '\\n'; - - std::thread t1(safe_increment); - std::thread t2(safe_increment); - - t1.join(); - t2.join(); - - std::cout << __func__ << ": " << g_i << '\\n'; + auto test = [](std::string_view fun_name, auto fun) + { + g_i = 0; + std::cout << fun_name << ":\\nbefore, g_i: " << g_i << '\\n'; + { + std::jthread t1(fun, 1'000'000); + std::jthread t2(fun, 1'000'000); + } + std::cout << "after, g_i: " << g_i << "\\n\\n"; + }; + test("safe_increment", safe_increment); + test("unsafe_increment", unsafe_increment); } .SH Possible output: - main: 0 - 140641306900224: 1 - 140641298507520: 2 - main: 2 + safe_increment: + before, g_i: 0 + thread #140121493231360, g_i: 1000000 + thread #140121484838656, g_i: 2000000 + after, g_i: 2000000 + + unsafe_increment: + before, g_i: 0 + thread #140121484838656, g_i: 1028945 + thread #140121493231360, g_i: 1034337 + after, g_i: 1034337 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2981 C++17 redundant deduction guide from removed + lock_guard was provided + +.SH See also + + unique_lock implements movable mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + scoped_lock deadlock-avoiding RAII wrapper for multiple mutexes + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::lock_guard::lock_guard.3 b/man/std::lock_guard::lock_guard.3 index d90e3895d..48e20c004 100644 --- a/man/std::lock_guard::lock_guard.3 +++ b/man/std::lock_guard::lock_guard.3 @@ -1,4 +1,7 @@ -.TH std::lock_guard::lock_guard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lock_guard::lock_guard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lock_guard::lock_guard \- std::lock_guard::lock_guard + .SH Synopsis explicit lock_guard( mutex_type& m ); \fB(1)\fP \fI(since C++11)\fP lock_guard( mutex_type& m, std::adopt_lock_t t ); \fB(2)\fP \fI(since C++11)\fP @@ -6,11 +9,10 @@ Acquires ownership of the given mutex m. - 1) If m is not a recursive mutex, requires that the current thread does not own m. - Effectively calls m.lock(). - - 2) Requires that the current thread owns m. - + 1) Effectively calls m.lock(). + 2) Acquires ownership of the mutex m without attempting to lock it. The behavior is + undefined if the current thread does not hold a non-shared lock (i.e., a lock + acquired by lock, try_lock, try_lock_for, or try_lock_until) on m. 3) Copy constructor is deleted. The behavior is undefined if m is destroyed before the lock_guard object is. @@ -19,3 +21,8 @@ m - mutex to acquire ownership of t - tag parameter used to select non-locking version of the constructor + +.SH Exceptions + + 1) Throws any exceptions thrown by m.lock(). + 2) Throws nothing. diff --git a/man/std::lock_guard::~lock_guard.3 b/man/std::lock_guard::~lock_guard.3 index dc6def924..f428d8d67 100644 --- a/man/std::lock_guard::~lock_guard.3 +++ b/man/std::lock_guard::~lock_guard.3 @@ -1,6 +1,11 @@ -.TH std::lock_guard::~lock_guard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lock_guard::~lock_guard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lock_guard::~lock_guard \- std::lock_guard::~lock_guard + .SH Synopsis ~lock_guard(); \fI(since C++11)\fP - Releases the ownership of the owned mutex. Effectively calls m.unlock() where m is - the mutex passed to the lock_guard's constructor. + Releases the ownership of the owned mutex. + + Effectively calls m.unlock() where m is the mutex passed to the lock_guard's + constructor. diff --git a/man/std::log(std::complex).3 b/man/std::log(std::complex).3 index 88c7cf087..5935d62ac 100644 --- a/man/std::log(std::complex).3 +++ b/man/std::log(std::complex).3 @@ -1,8 +1,11 @@ -.TH std::log(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::log(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log(std::complex) \- std::log(std::complex) + .SH Synopsis Defined in header template< class T > - complex log( const complex& z ); + std::complex log( const std::complex& z ); Computes complex natural (base e) logarithm of a complex value z with a branch cut along the negative real axis. @@ -13,12 +16,94 @@ .SH Return value - Complex natural logarithm of z + If no errors occur, the complex natural logarithm of z is returned, in the range of + a strip in the interval [−iπ, +iπ] along the imaginary axis and mathematically + unbounded along the real axis. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * The function is continuous onto the branch cut taking into account the sign of + imaginary part + * std::log(std::conj(z)) == std::conj(std::log(z)) + * If z is (-0,+0), the result is (-∞,π) and FE_DIVBYZERO is raised + * If z is (+0,+0), the result is (-∞,+0) and FE_DIVBYZERO is raised + * If z is (x,+∞) (for any finite x), the result is (+∞,π/2) + * If z is (x,NaN) (for any finite x), the result is (NaN,NaN) and FE_INVALID may + be raised + * If z is (-∞,y) (for any finite positive y), the result is (+∞,π) + * If z is (+∞,y) (for any finite positive y), the result is (+∞,+0) + * If z is (-∞,+∞), the result is (+∞,3π/4) + * If z is (+∞,+∞), the result is (+∞,π/4) + * If z is (±∞,NaN), the result is (+∞,NaN) + * If z is (NaN,y) (for any finite y), the result is (NaN,NaN) and FE_INVALID may + be raised + * If z is (NaN,+∞), the result is (+∞,NaN) + * If z is (NaN,NaN), the result is (NaN,NaN) + +.SH Notes + + The natural logarithm of a complex number z with polar coordinate components (r,θ) + equals ln r + i(θ+2nπ), with the principal value ln r + iθ. + + The semantics of this function are intended to be consistent with the C function + clog. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::complex z {0.0, 1.0}; // r = 1, θ = pi / 2 + std::cout << "2 * log" << z << " = " << 2.0 * std::log(z) << '\\n'; + + std::complex z2 {sqrt(2.0) / 2, sqrt(2.0) / 2}; // r = 1, θ = pi / 4 + std::cout << "4 * log" << z2 << " = " << 4.0 * std::log(z2) << '\\n'; + + std::complex z3 {-1.0, 0.0}; // r = 1, θ = pi + std::cout << "log" << z3 << " = " << std::log(z3) << '\\n'; + std::complex z4 {-1.0, -0.0}; // the other side of the cut + std::cout << "log" << z4 << " (the other side of the cut) = " << std::log(z4) << '\\n'; + } + +.SH Possible output: + + 2 * log(0,1) = (0,3.14159) + 4 * log(0.707107,0.707107) = (0,3.14159) + log(-1,0) = (0,3.14159) + log(-1,-0) (the other side of the cut) = (0,-3.14159) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2597 C++98 specification mishandles signed zero erroneous requirement + imaginary parts removed .SH See also - exp(std::complex) complex base e exponential - \fI(function template)\fP complex common logarithm with the branch cuts along the negative log10(std::complex) real axis - \fI(function template)\fP + \fI(function template)\fP + exp(std::complex) complex base e exponential + \fI(function template)\fP + log + logf computes natural (base e) logarithm (\\({\\small\\ln{x}}\\)ln(x)) + logl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log(std::valarray) applies the function std::log to each element of valarray + \fI(function template)\fP + C documentation for + clog diff --git a/man/std::log(std::valarray).3 b/man/std::log(std::valarray).3 index d5295eea3..4faab3fab 100644 --- a/man/std::log(std::valarray).3 +++ b/man/std::log(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::log(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::log(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log(std::valarray) \- std::log(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -12,12 +15,12 @@ .SH Return value - Value array natural logarithms of the values in va. + Value array containing natural logarithms of the values in va. .SH Notes Unqualified function (log) is used to perform the computation. If such function is - not available, std::log is used due to argument dependent lookup. + not available, std::log is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,29 +28,75 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Possible implementation - template< class T > - valarray log( const valarray& va ) + template + valarray log(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = log(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + + void show(char const* title, const std::valarray& va) + { + std::cout << title << " :" << std::right << std::fixed; + for (double x : va) + std::cout << std::setw(10) << x; + std::cout << '\\n'; + } + + int main() + { + const std::valarray n{0.0, 1.0, 2.0, 3.0}; + const std::valarray exp_n{std::exp(n)}; + const std::valarray log_exp_n{std::log(exp_n)}; + + show("n ", n); + show("eⁿ ", exp_n); + show("log(eⁿ)", log_exp_n); + } + +.SH Output: + + n : 0.000000 1.000000 2.000000 3.000000 + eⁿ : 1.000000 2.718282 7.389056 20.085537 + log(eⁿ) : 0.000000 1.000000 2.000000 3.000000 + +.SH See also + + log10(std::valarray) applies the function std::log10 to each element of valarray + \fI(function template)\fP + exp(std::valarray) applies the function std::exp to each element of valarray + \fI(function template)\fP + log + logf computes natural (base e) logarithm (\\({\\small\\ln{x}}\\)ln(x)) + logl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + complex natural logarithm with the branch cuts along the + log(std::complex) negative real axis + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::log,std::logf,std::logl.3 b/man/std::log,std::logf,std::logl.3 new file mode 100644 index 000000000..b3a7a5ef1 --- /dev/null +++ b/man/std::log,std::logf,std::logl.3 @@ -0,0 +1,140 @@ +.TH std::log,std::logf,std::logl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log,std::logf,std::logl \- std::log,std::logf,std::logl + +.SH Synopsis + Defined in header + float log ( float num ); + + double log ( double num ); (until C++23) + + long double log ( long double num ); + /* floating-point-type */ (since C++23) + log ( /* floating-point-type */ num ); (constexpr since C++26) + float logf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double logl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double log ( Integer num ); + + 1-3) Computes the natural (base e) logarithm of num. + The library provides overloads of std::log for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the natural (base-e) logarithm of num (ln(num) or log + e(num)) is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is less than zero. + + Pole error may occur if num is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, -∞ is returned and FE_DIVBYZERO is raised. + * If the argument is 1, +0 is returned. + * If the argument is negative, NaN is returned and FE_INVALID is raised. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::log(num) has the same effect as std::log(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "log(1) = " << std::log(1) << '\\n' + << "base-5 logarithm of 125 = " << std::log(125) / std::log(5) << '\\n'; + + // special values + std::cout << "log(1) = " << std::log(1) << '\\n' + << "log(+Inf) = " << std::log(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "log(0) = " << std::log(0) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + log\fB(1)\fP = 0 + base-5 logarithm of 125 = 3 + log\fB(1)\fP = 0 + log(+Inf) = inf + log\fB(0)\fP = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised + +.SH See also + + log10 + log10f computes common (base 10) logarithm + log10l (\\({\\small\\log_{10}{x}}\\)log[10](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + log2 + log2f base 2 logarithm of the given number + log2l (\\({\\small\\log_{2}{x}}\\)log[2](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log1p + log1pf natural logarithm (to base e) of 1 plus the given number + log1pl (\\({\\small\\ln{(1+x)}}\\)ln(1+x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp + expf returns e raised to the given power (\\({\\small e^x}\\)e^x) + expl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + complex natural logarithm with the branch cuts along the negative + log(std::complex) real axis + \fI(function template)\fP + log(std::valarray) applies the function std::log to each element of valarray + \fI(function template)\fP + C documentation for + log diff --git a/man/std::log.3 b/man/std::log.3 deleted file mode 100644 index 4dd0cf1d5..000000000 --- a/man/std::log.3 +++ /dev/null @@ -1,61 +0,0 @@ -.TH std::log 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float log( float arg ); - double log( double arg ); - long double log( long double arg ); - double log( Integral arg ); \fI(since C++11)\fP - - Computes the natural (base e) logarithm of arg. - -.SH Parameters - - arg - value of floating-point or Integral type - -.SH Return value - - Natural logarithm of arg. - - Domain error occurs if arg is negative. NAN is returned in that case. - - Range error occurs if arg is 0. -HUGE_VAL is returned in that case. - -.SH Example - - The following code computes the binary (base 2) logarithm with help of natural - logarithm. - - -// Run this code - - #include - #include - - int main() - { - double base = 2.0; - double arg = 256.0; - double result = std::log(arg) / std::log(base); - - std::cout << result << '\\n'; - } - -.SH Output: - - 8 - -.SH See also - - exp returns e raised to the given power (e^x) - \fI(function)\fP - log10 computes common (base 10) logarithm (log[10](x)) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - complex natural logarithm with the branch cuts along the negative - log(std::complex) real axis - \fI(function template)\fP - log(std::valarray) applies the function std::log to each element of valarray - \fI(function template)\fP - C documentation for - log diff --git a/man/std::log10(std::complex).3 b/man/std::log10(std::complex).3 index 691f53b2f..fbb9cff71 100644 --- a/man/std::log10(std::complex).3 +++ b/man/std::log10(std::complex).3 @@ -1,24 +1,67 @@ -.TH std::log10(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::log10(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log10(std::complex) \- std::log10(std::complex) + .SH Synopsis Defined in header template< class T > - complex log10( const complex& z ); + std::complex log10( const std::complex& z ); Computes complex common (base 10) logarithm of a complex value z with a branch cut along the negative real axis. + The behavior of this function is equivalent to std::log(z) / std::log(T\fB(10)\fP). + .SH Parameters z - complex value .SH Return value - Complex common logarithm of z + Complex common logarithm of z. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::complex z(0.0, 1.0); // r = 0, θ = pi / 2 + std::cout << "2 * log10" << z << " = " << 2.0 * std::log10(z) << '\\n'; + + std::complex z2(sqrt(2.0) / 2, sqrt(2.0) / 2); // r = 1, θ = pi / 4 + std::cout << "4 * log10" << z2 << " = " << 4.0 * std::log10(z2) << '\\n'; + + std::complex z3(-100.0, 0.0); // r = 100, θ = pi + std::cout << "log10" << z3 << " = " << std::log10(z3) << '\\n'; + std::complex z4(-100.0, -0.0); // the other side of the cut + std::cout << "log10" << z4 << " = " << std::log10(z4) << " " + "(the other side of the cut)\\n" + "(note: pi / log(10) = " << std::acos(-1.0) / std::log(10.0) << ")\\n"; + } + +.SH Possible output: + + 2 * log10(0,1) = (0,1.36438) + 4 * log10(0.707107,0.707107) = (0,1.36438) + log10(-100,0) = (2,1.36438) + log10(-100,-0) = (2,-1.36438) (the other side of the cut) + (note: pi / log\fB(10)\fP = 1.36438) .SH See also - exp(std::complex) complex base e exponential - \fI(function template)\fP - complex natural logarithm with the branch cuts along the negative - log(std::complex) real axis - \fI(function template)\fP + complex natural logarithm with the branch cuts along the + log(std::complex) negative real axis + \fI(function template)\fP + log10 + log10f computes common (base 10) logarithm + log10l (\\({\\small\\log_{10}{x}}\\)log[10](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + log10(std::valarray) applies the function std::log10 to each element of valarray + \fI(function template)\fP diff --git a/man/std::log10(std::valarray).3 b/man/std::log10(std::valarray).3 index 247ea292d..4eee82797 100644 --- a/man/std::log10(std::valarray).3 +++ b/man/std::log10(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::log10(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::log10(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log10(std::valarray) \- std::log10(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -13,12 +16,12 @@ .SH Return value - Value array common logarithms of the values in va. + Value array containing common logarithms of the values in va. .SH Notes Unqualified function (log10) is used to perform the computation. If such function is - not available, std::log10 is used due to argument dependent lookup. + not available, std::log10 is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -26,29 +29,74 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Possible implementation - template< class T > - valarray log10( const valarray& va ) + template + valarray log10(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = log10(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + #include + + void show(char const* title, const std::valarray& va) + { + std::cout << title << " : " << std::right; + for (float x : va) + std::cout << std::setw(6) << x; + std::cout << '\\n'; + } + + int main() + { + const std::valarray n{-2.f, -1.f, 0.f, 1.f, 2.f, 3.f, INFINITY}; + const std::valarray pow10{std::pow(10.f, n)}; + const std::valarray log10_pow10{std::log10(pow10)}; + + show("n ", n); + show("10ⁿ ", pow10); + show("lg(10ⁿ)", log10_pow10); + } + +.SH Output: + + n : -2 -1 0 1 2 3 inf + 10ⁿ : 0.01 0.1 1 10 100 1000 inf + lg(10ⁿ) : -2 -1 0 1 2 3 inf + +.SH See also + + log(std::valarray) applies the function std::log to each element of valarray + \fI(function template)\fP + log10 + log10f computes common (base 10) logarithm + log10l (\\({\\small\\log_{10}{x}}\\)log[10](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + complex common logarithm with the branch cuts along the negative + log10(std::complex) real axis + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::log10,std::log10f,std::log10l.3 b/man/std::log10,std::log10f,std::log10l.3 new file mode 100644 index 000000000..af2986f53 --- /dev/null +++ b/man/std::log10,std::log10f,std::log10l.3 @@ -0,0 +1,138 @@ +.TH std::log10,std::log10f,std::log10l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log10,std::log10f,std::log10l \- std::log10,std::log10f,std::log10l + +.SH Synopsis + Defined in header + float log10 ( float num ); + + double log10 ( double num ); (until C++23) + + long double log10 ( long double num ); + /* floating-point-type */ (since C++23) + log10 ( /* floating-point-type */ num ); (constexpr since C++26) + float log10f( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double log10l( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double log10 ( Integer num ); + + 1-3) Computes the common (base-10) logarithm of num. + The library provides overloads of std::log10 for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the common (base-10) logarithm of num (log + 10(num) or lg(num)) is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is less than zero. + + Pole error may occur if num is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, -∞ is returned and FE_DIVBYZERO is raised. + * If the argument is 1, +0 is returned. + * If the argument is negative, NaN is returned and FE_INVALID is raised. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::log10(num) has the same effect as std::log10(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "log10(1000) = " << std::log10(1000) << '\\n' + << "log10(0.001) = " << std::log10(0.001) << '\\n' + << "base-5 logarithm of 125 = " + << std::log10(125) / std::log10(5) << '\\n'; + + // special values + std::cout << "log10(1) = " << std::log10(1) << '\\n' + << "log10(+Inf) = " << std::log10(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "log10(0) = " << std::log10(0) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + log10(1000) = 3 + log10(0.001) = -3 + base-5 logarithm of 125 = 3 + log10\fB(1)\fP = 0 + log10(+Inf) = inf + log10\fB(0)\fP = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised + +.SH See also + + log + logf computes natural (base e) logarithm (\\({\\small\\ln{x}}\\)ln(x)) + logl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log2 + log2f base 2 logarithm of the given number + log2l (\\({\\small\\log_{2}{x}}\\)log[2](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log1p + log1pf natural logarithm (to base e) of 1 plus the given number + log1pl (\\({\\small\\ln{(1+x)}}\\)ln(1+x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + complex common logarithm with the branch cuts along the + log10(std::complex) negative real axis + \fI(function template)\fP + log10(std::valarray) applies the function std::log10 to each element of valarray + \fI(function template)\fP + C documentation for + log10 diff --git a/man/std::log10.3 b/man/std::log10.3 deleted file mode 100644 index 14eef3fe4..000000000 --- a/man/std::log10.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::log10 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float log10( float arg ); - double log10( double arg ); - long double log10( long double arg ); - double log10( Integral arg ); \fI(since C++11)\fP - - Computes the common (base 10) logarithm of arg. - -.SH Parameters - - arg - value of floating-point or Integral type - -.SH Return value - - Base 10 logarithm of arg. - - Domain error occurs if arg is negative. NAN is returned in that case. - - Range error occurs if arg is 0. -HUGE_VAL is returned in that case. - -.SH See also - - log computes natural (base e) logarithm (to base e) (ln(x)) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - complex common logarithm with the branch cuts along the - log10(std::complex) negative real axis - \fI(function template)\fP - log10(std::valarray) applies the function std::log10 to each element of valarray - \fI(function template)\fP - C documentation for - log10 diff --git a/man/std::log1p,std::log1pf,std::log1pl.3 b/man/std::log1p,std::log1pf,std::log1pl.3 new file mode 100644 index 000000000..439e755de --- /dev/null +++ b/man/std::log1p,std::log1pf,std::log1pl.3 @@ -0,0 +1,173 @@ +.TH std::log1p,std::log1pf,std::log1pl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log1p,std::log1pf,std::log1pl \- std::log1p,std::log1pf,std::log1pl + +.SH Synopsis + Defined in header + float log1p ( float num ); + + double log1p ( double num ); (until C++23) + + long double log1p ( long double num ); + /* floating-point-type */ (since C++23) + log1p ( /* floating-point-type */ num ); (constexpr since C++26) + float log1pf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double log1pl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double log1p ( Integer num ); + + 1-3) Computes the natural (base e) logarithm of 1 + num. This function is more + precise than the expression std::log(1 + num) if num is close to zero. + The library provides overloads of std::log1p for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur ln(1+num) is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is less than -1. + + Pole error may occur if num is -1. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, it is returned unmodified. + * If the argument is -1, -∞ is returned and FE_DIVBYZERO is raised. + * If the argument is less than -1, NaN is returned and FE_INVALID is raised. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + The functions std::expm1 and std::log1p are useful for financial calculations, for + example, when calculating small daily interest rates: (1 + x)n + - 1 can be expressed as std::expm1(n * std::log1p(x)). These functions also simplify + writing accurate inverse hyperbolic functions. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::log1p(num1, num2) + has the same effect as std::log1p(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::log1p(num1, num2) has the same effect as (until C++23) + std::log1p(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::log1p(num1, + num2) has the same effect as std::log1p(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::log1p(num1, num2) + has the same effect as std::log1p(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "log1p(0) = " << log1p(0) << '\\n' + << "Interest earned in 2 days on $100, compounded daily at 1%\\n" + << " on a 30/360 calendar = " + << 100 * expm1(2 * log1p(0.01 / 360)) << '\\n' + << "log(1+1e-16) = " << std::log(1 + 1e-16) + << ", but log1p(1e-16) = " << std::log1p(1e-16) << '\\n'; + + // special values + std::cout << "log1p(-0) = " << std::log1p(-0.0) << '\\n' + << "log1p(+Inf) = " << std::log1p(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "log1p(-1) = " << std::log1p(-1) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + log1p\fB(0)\fP = 0 + Interest earned in 2 days on $100, compounded daily at 1% + on a 30/360 calendar = 0.00555563 + log(1+1e-16) = 0, but log1p(1e-16) = 1e-16 + log1p(-0) = -0 + log1p(+Inf) = inf + log1p(-1) = -inf + errno == ERANGE: Result too large + FE_DIVBYZERO raised + +.SH See also + + log + logf computes natural (base e) logarithm (\\({\\small\\ln{x}}\\)ln(x)) + logl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log10 + log10f computes common (base 10) logarithm (\\({\\small\\log_{10}{x}}\\)log[10](x)) + log10l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log2 + log2f + log2l base 2 logarithm of the given number (\\({\\small\\log_{2}{x}}\\)log[2](x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + expm1 + expm1f + expm1l returns e raised to the given power, minus one (\\({\\small e^x-1}\\)e^x-1) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + log1p diff --git a/man/std::log1p.3 b/man/std::log1p.3 deleted file mode 100644 index a7abf2afa..000000000 --- a/man/std::log1p.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::log1p 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float log1p( float arg ); \fI(since C++11)\fP - double log1p( double arg ); \fI(since C++11)\fP - long double log1p( long double arg ); \fI(since C++11)\fP - double log1p( Integral arg ); \fI(since C++11)\fP - - Computes the natural (base e) logarithm of 1+arg. This function is more precise than - the expression std::log(1+arg) if arg is close to zero. - -.SH Parameters - - arg - value of floating-point or Integral type - -.SH Return value - - ln(1+arg) - - Domain error occurs if arg is less than -1. NAN is returned in that case. - - Range error occurs if arg is -1. -HUGE_VAL is returned in that case. - -.SH See also - - log computes natural (base e) logarithm (to base e) (ln(x)) - \fI(function)\fP - expm1 returns e raised to the given power, minus one (e^x-1) - \fI(C++11)\fP \fI(function)\fP - log10 computes common (base 10) logarithm (log[10](x)) - \fI(function)\fP - log2 base 2 logarithm of the given number - \fI(C++11)\fP \fI(function)\fP - C documentation for - log1p diff --git a/man/std::log2,std::log2f,std::log2l.3 b/man/std::log2,std::log2f,std::log2l.3 new file mode 100644 index 000000000..3900a97a6 --- /dev/null +++ b/man/std::log2,std::log2f,std::log2l.3 @@ -0,0 +1,144 @@ +.TH std::log2,std::log2f,std::log2l 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::log2,std::log2f,std::log2l \- std::log2,std::log2f,std::log2l + +.SH Synopsis + Defined in header + float log2 ( float num ); + + double log2 ( double num ); (until C++23) + + long double log2 ( long double num ); + /* floating-point-type */ (since C++23) + log2 ( /* floating-point-type */ num ); (constexpr since C++26) + float log2f( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double log2l( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double log2 ( Integer num ); + + 1-3) Computes the binary (base-2) logarithm of num. + The library provides overloads of std::log2 for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the base-2 logarithm of num (log + 2(num) or lb(num)) is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is less than zero. + + Pole error may occur if num is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, -∞ is returned and FE_DIVBYZERO is raised. + * If the argument is 1, +0 is returned. + * If the argument is negative, NaN is returned and FE_INVALID is raised. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + For integer num, the binary logarithm can be interpreted as the zero-based index of + the most significant 1 bit in the input. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::log2(num) has the same effect as std::log2(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "log2(65536) = " << std::log2(65536) << '\\n' + << "log2(0.125) = " << std::log2(0.125) << '\\n' + << "log2(0x020f) = " << std::log2(0x020f) + << " (highest set bit is in position 9)\\n" + << "base-5 logarithm of 125 = " + << std::log2(125) / std::log2(5) << '\\n'; + + // special values + std::cout << "log2(1) = " << std::log2(1) << '\\n' + << "log2(+Inf) = " << std::log2(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "log2(0) = " << std::log2(0) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + log2(65536) = 16 + log2(0.125) = -3 + log2(0x020f) = 9.04166 (highest set bit is in position 9) + base-5 logarithm of 125 = 3 + log2\fB(1)\fP = 0 + log2(+Inf) = inf + log2\fB(0)\fP = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised + +.SH See also + + log + logf computes natural (base e) logarithm (\\({\\small\\ln{x}}\\)ln(x)) + logl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log10 + log10f computes common (base 10) logarithm (\\({\\small\\log_{10}{x}}\\)log[10](x)) + log10l \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + log1p + log1pf natural logarithm (to base e) of 1 plus the given number + log1pl (\\({\\small\\ln{(1+x)}}\\)ln(1+x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + exp2 + exp2f + exp2l returns 2 raised to the given power (\\({\\small 2^x}\\)2^x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + log2 diff --git a/man/std::log2.3 b/man/std::log2.3 deleted file mode 100644 index 782aa2521..000000000 --- a/man/std::log2.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::log2 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float log2( float arg ); \fI(since C++11)\fP - double log2( double arg ); \fI(since C++11)\fP - long double log2( long double arg ); \fI(since C++11)\fP - double log2( Integral arg ); \fI(since C++11)\fP - - Computes the base 2 logarithm of arg. - -.SH Parameters - - arg - value of floating-point or Integral type - -.SH Return value - - log - 2(arg) - - Domain error occurs if arg is negative. NAN is returned in that case. - - Range error occurs if arg is 0. -HUGE_VAL is returned in that case. - -.SH See also - - log computes natural (base e) logarithm (to base e) (ln(x)) - \fI(function)\fP - exp2 returns 2 raised to the given power (2^x) - \fI(C++11)\fP \fI(function)\fP - log10 computes common (base 10) logarithm (log[10](x)) - \fI(function)\fP - C documentation for - log2 diff --git a/man/std::logb,std::logbf,std::logbl.3 b/man/std::logb,std::logbf,std::logbl.3 new file mode 100644 index 000000000..b13d2a45b --- /dev/null +++ b/man/std::logb,std::logbf,std::logbl.3 @@ -0,0 +1,154 @@ +.TH std::logb,std::logbf,std::logbl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::logb,std::logbf,std::logbl \- std::logb,std::logbf,std::logbl + +.SH Synopsis + Defined in header + float logb ( float num ); + + double logb ( double num ); (until C++23) + + long double logb ( long double num ); + constexpr /* floating-point-type */ (since C++23) + logb ( /* floating-point-type */ num ); + float logbf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double logbl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double logb ( Integer num ); + + 1-3) Extracts the value of the unbiased radix-independent exponent from the + floating-point argument num, and returns it as a floating-point value. + The library provides overloads of std::logb for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + + Formally, the unbiased exponent is the signed integral part of log + r|num| (returned by this function as a floating-point value), for non-zero num, + where r is std::numeric_limits::radix and T is the floating-point type of num. If + num is subnormal, it is treated as though it was normalized. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the unbiased exponent of num is returned as a signed + floating-point value. + + If a domain error occurs, an implementation-defined value is returned. + + If a pole error occurs, -HUGE_VAL, -HUGE_VALF, or -HUGE_VALL is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain or range error may occur if num is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If num is ±0, -∞ is returned and FE_DIVBYZERO is raised. + * If num is ±∞, +∞ is returned. + * If num is NaN, NaN is returned. + * In all other cases, the result is exact (FE_INEXACT is never raised) and the + current rounding mode is ignored. + +.SH Notes + + POSIX requires that a pole error occurs if num is ±0. + + The value of the exponent returned by std::logb is always 1 less than the exponent + returned by std::frexp because of the different normalization requirements: for the + exponent e returned by std::logb, |num*r-e + | is between 1 and r (typically between 1 and 2), but for the exponent e returned by + std::frexp, |num*2-e + | is between 0.5 and 1. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::logb(num) has the same effect as std::logb(static_cast(num)). + +.SH Example + + Compares different floating-point decomposition functions: + + +// Run this code + + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + double f = 123.45; + std::cout << "Given the number " << f << " or " << std::hexfloat + << f << std::defaultfloat << " in hex,\\n"; + + double f3; + double f2 = std::modf(f, &f3); + std::cout << "modf() makes " << f3 << " + " << f2 << '\\n'; + + int i; + f2 = std::frexp(f, &i); + std::cout << "frexp() makes " << f2 << " * 2^" << i << '\\n'; + + i = std::ilogb(f); + std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) << " * " + << std::numeric_limits::radix + << "^" << std::ilogb(f) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "logb(0) = " << std::logb(0) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, + modf() makes 123 + 0.45 + frexp() makes 0.964453 * 2^7 + logb()/ilogb() make 1.92891 * 2^6 + logb\fB(0)\fP = -Inf + FE_DIVBYZERO raised + +.SH See also + + frexp + frexpf decomposes a number into significand and base-2 exponent + frexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ilogb + ilogbf + ilogbl extracts exponent of the number + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + scalbn + scalbnf + scalbnl + scalbln + scalblnf + scalblnl multiplies a number by FLT_RADIX raised to a power + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + logb diff --git a/man/std::logb.3 b/man/std::logb.3 deleted file mode 100644 index 5aad0810e..000000000 --- a/man/std::logb.3 +++ /dev/null @@ -1,80 +0,0 @@ -.TH std::logb 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float logb( float arg ); \fI(since C++11)\fP - double logb( double arg ); \fI(since C++11)\fP - long double logb( long double arg ); \fI(since C++11)\fP - double logb( Integral arg ); \fI(since C++11)\fP - - Extracts the value of the exponent from the floating-point argument arg, and returns - it as a floating-point value. Formally, the result is the integral part of log - r|arg| as a signed floating-point value, for non-zero arg, where r is - std::numeic_limits::radix and T is the floating-point type of arg. If arg is - subnormal, it is treated as though it was normalized. - -.SH Parameters - - arg - floating point value - -.SH Return value - - The floating-point exponent. - - Domain or range error may occur if arg is zero. - -.SH Notes - - The value of the exponent returned by std::logb is always 1 less than the exponent - retuned by std::frexp because of the different normalization requirements: for the - exponent e returned by std::logb, |arg*r-e - | is between 1 and r (typically between 1 and 2), but for the exponent e returned by - std::frexp, |arg*2-e - | is between 0.5 and 1. - -.SH Example - - Compares different floating-point decomposition functions - - -// Run this code - - #include - #include - #include - int main() - { - double f = 123.45; - std::cout << "Given the number " << f << " or " << std::hexfloat - << f << std::defaultfloat << " in hex,\\n"; - - double f3; - double f2 = std::modf(f, &f3); - std::cout << "modf() makes " << f3 << " + " << f2 << '\\n'; - - int i; - f2 = std::frexp(f, &i); - std::cout << "frexp() makes " << f2 << " * 2^" << i << '\\n'; - - i = std::ilogb(f); - std::cout << "logb()/ilogb() make " << f/std::scalbn(1.0, i) << " * " - << std::numeric_limits::radix - << "^" << std::ilogb(f) << '\\n'; - } - -.SH Output: - - Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, - modf() makes 123 + 0.45 - frexp() makes 0.964453 * 2^7 - logb()/ilogb() make 1.92891 * 2^6 - -.SH See also - - frexp decomposes a number into significand and a power of 2 - \fI(function)\fP - ilogb extracts exponent of the number - \fI(C++11)\fP \fI(function)\fP - scalbn - scalbln multiplies a number by FLT_RADIX raised to a power - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP diff --git a/man/std::logic_error.3 b/man/std::logic_error.3 index 03ee982ec..9bc23d2c7 100644 --- a/man/std::logic_error.3 +++ b/man/std::logic_error.3 @@ -1,4 +1,7 @@ -.TH std::logic_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::logic_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::logic_error \- std::logic_error + .SH Synopsis Defined in header class logic_error; @@ -7,39 +10,102 @@ consequence of faulty logic within the program such as violating logical preconditions or class invariants and may be preventable. + No standard library components throw this exception directly, but the exception + types std::invalid_argument, std::domain_error, std::length_error, + std::out_of_range, std::future_error, and std::experimental::bad_optional_access are + derived from std::logic_error. + std-logic error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP - - + constructor constructs a new logic_error object with the given message + \fI(public member function)\fP + operator= replaces the logic_error object + \fI(public member function)\fP - std::logic_error::logic_error +std::logic_error::logic_error - explicit logic_error( const std::string& what_arg ); \fB(1)\fP - explicit logic_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP + logic_error( const std::string& what_arg ); \fB(1)\fP + logic_error( const char* what_arg ); \fB(2)\fP + logic_error( const logic_error& other ); \fB(3)\fP (noexcept since C++11) - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::logic_error then + std::strcmp(what(), other.what()) == 0. No exception can be thrown from the copy + constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::logic_error is not permitted to throw exceptions, this message + is typically stored internally as a separately-allocated reference-counted string. + This is also why there is no constructor taking std::string&&: it would have to copy + the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::logic_error::operator= + + logic_error& operator=( const logic_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::logic_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const char* added + was missing + the explanatory strings of they are the same as that + LWG 471 C++98 std::logic_error's of the + copies were implementation-defined original std::logic_error + object diff --git a/man/std::logical_and.3 b/man/std::logical_and.3 index 40513f835..447fe2210 100644 --- a/man/std::logical_and.3 +++ b/man/std::logical_and.3 @@ -1,58 +1,42 @@ -.TH std::logical_and 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::logical_and 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::logical_and \- std::logical_and + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct logical_and; - template< class T = void > \fI(since C++14)\fP - struct logical_and; - - Function object for performing logical AND (logical conjunction). Effectively calls - operator&& on type T. - -.SH Specializations - - The standard library provides a specialization of std::logical_and - when T is not specified, which leaves the parameter types and return - type to be deduced. - \fI(since C++14)\fP - function object implementing x && y deducing - logical_and argument and return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class logical_and; -.SH Member types - - Type Definition - result_type bool - first_argument_type T - second_argument_type T + std::logical_and is a specialization of std::logical_and with parameter and + return type deduced. .SH Member functions - operator() returns the logical AND of the two arguments + operator() applies operator&& to lhs and rhs \fI(public member function)\fP - std::logical_and::operator() +std::logical_and::operator() + + template< class T, class U > - bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const - Returns the logical AND of lhs and rhs. + -> decltype(std::forward(lhs) && std::forward(rhs)); + + Returns the result of lhs && rhs. .SH Parameters - lhs, rhs - values to compute logical AND of + lhs, rhs - values to logical AND .SH Return value The result of lhs && rhs. -.SH Exceptions - - \fI(none)\fP +.SH Example -.SH Possible implementation + This section is incomplete + Reason: no example - constexpr bool operator()(const T &lhs, const T &rhs) const - { - return lhs && rhs; - } +.SH Category: + * Todo no example diff --git a/man/std::logical_and.3 b/man/std::logical_and.3 deleted file mode 100644 index 60e13225a..000000000 --- a/man/std::logical_and.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::logical_and 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class logical_and; - - std::logical_and<> is a specialization of std::logical_and with parameter and return - type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() applies operator&& to lhs and rhs - \fI(public member function)\fP - - std::logical_and<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) && std::forward(rhs)); - - Returns the result of lhs && rhs. - -.SH Parameters - - lhs, rhs - values to AND - -.SH Return value - - The result of lhs && rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::logical_not.3 b/man/std::logical_not.3 index 39bcad738..8fdfd60e9 100644 --- a/man/std::logical_not.3 +++ b/man/std::logical_not.3 @@ -1,4 +1,7 @@ -.TH std::logical_not 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::logical_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::logical_not \- std::logical_not + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -15,22 +18,25 @@ when T is not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing !x deducing argument - logical_not and return types - \fI(class template specialization)\fP + logical_not function object implementing !x deducing parameter + \fI(C++14)\fP and return types + \fI(class template specialization)\fP .SH Member types - Type Definition - result_type bool - argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) bool + argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::unary_function. .SH Member functions operator() returns the logical NOT of the argument \fI(public member function)\fP - std::logical_not::operator() +std::logical_not::operator() bool operator()( const T& arg ) const; \fI(until C++14)\fP constexpr bool operator()( const T& arg ) const; \fI(since C++14)\fP @@ -47,11 +53,12 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - const bool operator()(const T &arg) const + constexpr // since C++14 + bool operator()(const T& arg) const { return !arg; } diff --git a/man/std::logical_not.3 b/man/std::logical_not.3 deleted file mode 100644 index d4664a400..000000000 --- a/man/std::logical_not.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::logical_not 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class logical_not; - - std::logical_not<> is a specialization of std::logical_not with parameter and return - type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() to its argument - \fI(public member function)\fP - - std::logical_not<>::operator() - - template< class T > - - constexpr auto operator()( T&& arg ) const - - -> decltype(!std::forward(lhs)); - - Returns the result of !arg. - -.SH Parameters - - arg - value to apply logical NOT to - -.SH Return value - - The result of !arg. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::logical_or.3 b/man/std::logical_or.3 index d948ffda5..7bac192eb 100644 --- a/man/std::logical_or.3 +++ b/man/std::logical_or.3 @@ -1,58 +1,42 @@ -.TH std::logical_or 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::logical_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::logical_or \- std::logical_or + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct logical_or; - template< class T = void > \fI(since C++14)\fP - struct logical_or; - - Function object for performing logical OR (logical disjunction). Effectively calls - operator|| on type T. - -.SH Specializations - - The standard library provides a specialization of std::logical_or when - T is not specified, which leaves the parameter types and return type - to be deduced. - \fI(since C++14)\fP - function object implementing x || y deducing argument - logical_or and return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class logical_or; -.SH Member types - - Type Definition - result_type bool - first_argument_type T - second_argument_type T + std::logical_or is a specialization of std::logical_or with parameter and + return type deduced. .SH Member functions - operator() returns the logical OR of the two arguments + operator() applies operator|| to lhs and rhs \fI(public member function)\fP - std::logical_or::operator() +std::logical_or::operator() + + template< class T, class U > - bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const - Returns the logical OR of lhs and rhs. + -> decltype(std::forward(lhs) || std::forward(rhs)); + + Returns the result of std::forward(lhs) || std::forward(rhs). .SH Parameters - lhs, rhs - values to compute logical OR of + lhs, rhs - values to logical OR .SH Return value - The result of lhs || rhs. - -.SH Exceptions + std::forward(lhs) || std::forward(rhs). - \fI(none)\fP +.SH Example -.SH Possible implementation + This section is incomplete + Reason: no example - constexpr bool operator()(const T &lhs, const T &rhs) const - { - return lhs || rhs; - } +.SH Category: + * Todo no example diff --git a/man/std::logical_or.3 b/man/std::logical_or.3 deleted file mode 100644 index 72b8751be..000000000 --- a/man/std::logical_or.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::logical_or 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class logical_or; - - std::logical_or<> is a specialization of std::logical_or with parameter and return - type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() applies operator to lhs and rhs - \fI(public member function)\fP - - std::logical_or<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) || std::forward(rhs)); - - Returns the result of lhs || rhs. - -.SH Parameters - - lhs, rhs - values to OR - -.SH Return value - - The result of lhs || rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::lognormal_distribution.3 b/man/std::lognormal_distribution.3 index 2b9eb4fc7..1910472ba 100644 --- a/man/std::lognormal_distribution.3 +++ b/man/std::lognormal_distribution.3 @@ -1,13 +1,17 @@ -.TH std::lognormal_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution \- std::lognormal_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP class lognormal_distribution; The lognormal_distribution random number distribution produces random numbers x > 0 - according to a log-normal distribution: + according to a Log-normal distribution: - f(x; m,s) = + \\({\\small f(x;m,s) = \\frac{1}{sx\\sqrt{2\\pi} } \\exp{(-\\frac{ {(\\ln{x} - m)}^{2} + }{2{s}^{2} })} }\\)f(x; m,s) = 1 sx @@ -25,84 +29,94 @@ ⎟ ⎠ - The parameter m is the mean and the parameter s the standard deviation. + The parameters m and s are, respectively, the mean and standard deviation of the + natural logarithm of x. + + std::lognormal_distribution satisfies all requirements of RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics m returns the distribution parameters - s \fI(public member function)\fP + s \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include + #include #include - #include + #include #include #include - #include + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); - + std::lognormal_distribution<> d(1.6, 0.25); - + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n = 0; n < 1e4; ++n) ++hist[std::round(d(gen))]; - } - for(auto p : hist) { - std::cout << std::fixed << std::setprecision(1) << std::setw(2) - << p.first << ' ' << std::string(p.second/200, '*') << '\\n'; - } + + for (std::cout << std::fixed << std::setprecision(1); auto [x, y] : hist) + std::cout << std::hex << x << ' ' << std::string(y / 200, '*') << '\\n'; } -.SH Output: +.SH Possible output: 2 - 3 *** - 4 ************* - 5 *************** - 6 ********* - 7 **** - 8 * - 9 - 10 - 11 - 12 + 3 *** + 4 ************* + 5 *************** + 6 ********* + 7 **** + 8 * + 9 + a + b + c .SH External links - * Weisstein, Eric W. "Log Normal Distribution." From MathWorld--A Wolfram Web - Resource. - * Log-normal distribution. From Wikipedia. + Weisstein, Eric W. "Log Normal Distribution." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::lognormal_distribution::lognormal_distribution.3 b/man/std::lognormal_distribution::lognormal_distribution.3 index 8ccd1cf49..0201b5b52 100644 --- a/man/std::lognormal_distribution::lognormal_distribution.3 +++ b/man/std::lognormal_distribution::lognormal_distribution.3 @@ -1,15 +1,27 @@ -.TH std::lognormal_distribution::lognormal_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::lognormal_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::lognormal_distribution \- std::lognormal_distribution::lognormal_distribution + .SH Synopsis - explicit lognormal_distribution( RealType m = 0.0, RealType s = \fB(1)\fP \fI(since C++11)\fP - 1.0 ); - explicit lognormal_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + lognormal_distribution() : lognormal_distribution(0.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit lognormal_distribution( RealType m, RealType s = 1.0 ); \fB(2)\fP \fI(since C++11)\fP + explicit lognormal_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses m and s as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses m and s as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters m - the m distribution parameter (log-scale) s - the s distribution parameter (shape) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::lognormal_distribution::m,s.3 b/man/std::lognormal_distribution::m,s.3 index d01875f9c..f362259d5 100644 --- a/man/std::lognormal_distribution::m,s.3 +++ b/man/std::lognormal_distribution::m,s.3 @@ -1,13 +1,16 @@ -.TH std::lognormal_distribution::m,s 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::m,s 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::m,s \- std::lognormal_distribution::m,s + .SH Synopsis RealType m() const; \fB(1)\fP \fI(since C++11)\fP RealType s() const; \fB(2)\fP \fI(since C++11)\fP Returns the parameters the distribution was constructed with. - 1) Returns the mean m distribution parameter. It defines the location of the peak. - The default value is 0.0. - 2) Returns the deviation s distribution parameter. The default value is 1.0. + 1) Returns the log-mean m distribution parameter. It defines the location of the + peak. The default value is 0.0. + 2) Returns the log-deviation s distribution parameter. The default value is 1.0. .SH Parameters @@ -15,10 +18,10 @@ .SH Return value - 1) The mean m distribution parameter. - 2) The deviation s distribution parameter. + 1) The log-mean m distribution parameter. + 2) The log-deviation s distribution parameter. .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::lognormal_distribution::max.3 b/man/std::lognormal_distribution::max.3 index 0d8225ca1..5c9d06537 100644 --- a/man/std::lognormal_distribution::max.3 +++ b/man/std::lognormal_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::lognormal_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::max \- std::lognormal_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::lognormal_distribution::min.3 b/man/std::lognormal_distribution::min.3 index 574313a32..8477994d5 100644 --- a/man/std::lognormal_distribution::min.3 +++ b/man/std::lognormal_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::lognormal_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::min \- std::lognormal_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::lognormal_distribution::operator().3 b/man/std::lognormal_distribution::operator().3 index 15788182e..bd7dab633 100644 --- a/man/std::lognormal_distribution::operator().3 +++ b/man/std::lognormal_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::lognormal_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::operator() \- std::lognormal_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::lognormal_distribution::param.3 b/man/std::lognormal_distribution::param.3 index 88237cb84..c1c46dc04 100644 --- a/man/std::lognormal_distribution::param.3 +++ b/man/std::lognormal_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::lognormal_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::param \- std::lognormal_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::lognormal_distribution::reset.3 b/man/std::lognormal_distribution::reset.3 index 50dd9c15c..de01ebca2 100644 --- a/man/std::lognormal_distribution::reset.3 +++ b/man/std::lognormal_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::lognormal_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lognormal_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lognormal_distribution::reset \- std::lognormal_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::longjmp.3 b/man/std::longjmp.3 index 2a1619e27..025881ce3 100644 --- a/man/std::longjmp.3 +++ b/man/std::longjmp.3 @@ -1,68 +1,110 @@ -.TH std::longjmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::longjmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::longjmp \- std::longjmp + .SH Synopsis Defined in header - void longjmp( std::jmp_buf env, int status ); + void longjmp( std::jmp_buf env, int status ); \fI(until C++17)\fP + [[noreturn]] void longjmp( std::jmp_buf env, int status ); \fI(since C++17)\fP Loads the execution context env saved by a previous call to setjmp. This function does not return. Control is transferred to the call site of the macro setjmp that set up env. That setjmp then returns the value, passed as the status. If the function that called setjmp has exited, the behavior is undefined (in other - words, only long jumps up the call stack are allowed) - - No destructors for automatic objects are called. If replacing of std::longjmp with - throw and setjmp with catch would execute a non-trivial destructor for any automatic - object, the behavior of such std::longjmp is undefined. + words, only long jumps up the call stack are allowed). .SH Parameters - env - variable referring to the execution state of the program saved by - std::setjmp + env - variable referring to the execution state of the program saved by setjmp status - the value to return from setjmp. If it is equal to 0, 1 is used instead .SH Return value \fI(none)\fP +.SH Notes + + std::longjmp is the mechanism used in C to handle unexpected error conditions where + the function cannot return meaningfully. C++ generally uses exception handling for + this purpose. + .SH Example - + // Run this code - #include + #include + #include #include - - std::jmp_buf jump_buffer; - - [[noreturn]] void a(int count) + #include + #include + #include + + std::jmp_buf solver_error_handler; + + std::array solve_quadratic_equation(double a, double b, double c) { - std::cout << "a(" << count << ") called\\n"; - std::longjmp(jump_buffer, count+1); // setjump() will return count+1 + const double discriminant = b * b - 4.0 * a * c; + if (discriminant < 0) + std::longjmp(solver_error_handler, true); // Go to error handler + + const double delta = std::sqrt(discriminant) / (2.0 * a); + const double argmin = -b / (2.0 * a); + return {argmin - delta, argmin + delta}; } - + + void show_quadratic_equation_solution(double a, double b, double c) + { + std::cout << std::format("Solving {}x² + {}x + {} = 0...\\n", a, b, c); + auto [x_0, x_1] = solve_quadratic_equation(a, b, c); + std::cout << std::format("x₁ = {}, x₂ = {}\\n\\n", x_0, x_1); + } + int main() { - int count = setjmp(jump_buffer); - if (count != 9) { - a(count); // This will cause setjmp() to exit + if (setjmp(solver_error_handler)) + { + // Error handler for solver + std::cout << "No real solution\\n"; + return EXIT_FAILURE; } + + for (auto [a, b, c] : {std::array{1, -3, 2}, {2, -3, -2}, {1, 2, 3}}) + show_quadratic_equation_solution(a, b, c); + + return EXIT_SUCCESS; } .SH Output: - a\fB(0)\fP called - a\fB(1)\fP called - a\fB(2)\fP called - a\fB(3)\fP called - a\fB(4)\fP called - a\fB(5)\fP called - a\fB(6)\fP called - a\fB(7)\fP called - a\fB(8)\fP called + Solving 1x² + -3x + 2 = 0... + x₁ = 1, x₂ = 2 + + Solving 2x² + -3x + -2 = 0... + x₁ = -0.5, x₂ = 2 + + Solving 1x² + 2x + 3 = 0... + No real solution + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 619 C++98 the wording of the extra restrictions improved the wording + in C++ was vague + the behavior was undefined if the behavior is only + replacing undefined + LWG 894 C++98 std::longjmp with throw and setjmp if a non-trivial destructor + with for + catch would destroy any automatic any automatic object is + object invoked .SH See also setjmp saves the context - \fI(function macro)\fP + \fI(function macro)\fP C documentation for longjmp diff --git a/man/std::lower_bound.3 b/man/std::lower_bound.3 index 4fbf81533..be1e69e52 100644 --- a/man/std::lower_bound.3 +++ b/man/std::lower_bound.3 @@ -1,125 +1,275 @@ -.TH std::lower_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::lower_bound \- std::lower_bound + .SH Synopsis Defined in header - template< class ForwardIt, class T > \fB(1)\fP - ForwardIt lower_bound( ForwardIt first, ForwardIt last, const T& value ); - template< class ForwardIt, class T, class Compare > - ForwardIt lower_bound( ForwardIt first, ForwardIt last, const T& value, Compare \fB(2)\fP - comp ); + template< class ForwardIt, class T > + (constexpr since + ForwardIt lower_bound( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value ); + template< class ForwardIt, class T = + typename std::iterator_traits + + + ::value_type > (since C++26) + constexpr ForwardIt lower_bound( ForwardIt + first, ForwardIt last, + + const T& + value ); + template< class ForwardIt, class T, class + Compare > \fB(1)\fP + (constexpr since + ForwardIt lower_bound( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value, + Compare comp ); + template< class ForwardIt, class T = + typename std::iterator_traits \fB(2)\fP + + + ::value_type, + class Compare > (since C++26) + constexpr ForwardIt lower_bound( ForwardIt + first, ForwardIt last, + + const T& + value, Compare comp ); + + Searches for the first element in the partitioned range [first, last) which is not + ordered before value. - Returns an iterator pointing to the first element in the range [first, last) that is - not less than (i.e. greater or equal to) value. + 1) The order is determined by operator<: - The range [first, last) must be at least partially ordered, i.e. partitioned with - respect to the expression element < value or comp(element, value). A fully-sorted - range meets this criteria, as does a range resulting from a call to std::partition. + Returns the first iterator iter in [first, last) where bool(*iter < + value) is false, or last if no such iter exists. + \fI(until C++20)\fP + If the elements elem of [first, last) are not partitioned with respect + to the expression bool(elem < value), the behavior is undefined. + Equivalent to std::lower_bound(first, last, value, std::less{}). \fI(since C++20)\fP - The first version uses operator< to compare the elements, the second version uses - the given comparison function comp. + 2) The order is determined by comp: + Returns the first iterator iter in [first, last) where bool(comp(*iter, value)) is + false, or last if no such iter exists. + If the elements elem of [first, last) are not partitioned with respect to the + expression bool(comp(elem, value)), the behavior is undefined. .SH Parameters - first, last - iterators defining the partially-ordered range to examine - value - value to compare the elements to - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the partitioned range of elements to examine + value - value to compare the elements to + binary predicate which returns true if the first argument is ordered + before the second. - The signature of the comparison function should be equivalent to the - following: + The signature of the predicate function should be equivalent to the + following: - comp - bool cmp(const Type1 &a, const Type2 &b); + bool pred(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The type Type1 must be such that an object of type ForwardIt can be - dereferenced and then implicitly converted to Type1. The type Type2 - must be such that an object of type T can be implicitly converted to - Type2. + comp - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The type Type1 must be such that an object of type ForwardIt can be + dereferenced and then implicitly converted to Type1. The type Type2 + must be such that an object of type T can be implicitly converted to + Type2. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of BinaryPredicate. It is not required to satisfy + Compare. .SH Return value - Iterator pointing to the first element that is not less than value, or last if no - such element is found. + Iterator to the first element of the range [first, last) not ordered before value, + or last if no such element is found. .SH Complexity - The number of comparisons performed is logarithmic in the distance between first and - last + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) At most \\(\\scriptsize \\log_{2}(N)+O(1)\\)log + 2(N)+O(1) comparisons with value using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize \\log_{2}(N)+O(1)\\)log + 2(N)+O(1) applications of the comparator comp. + + However, if ForwardIt is not a LegacyRandomAccessIterator, the number of iterator + increments is linear in \\(\\scriptsize N\\)N. Notably, std::map, std::multimap, + std::set, and std::multiset iterators are not random access, and so their member + lower_bound functions should be preferred. .SH Possible implementation -.SH First version - template - ForwardIt lower_bound(ForwardIt first, ForwardIt last, const T& value) - { - ForwardIt it; - typename std::iterator_traits::difference_type count, step; - count = std::distance(first, last); - - while (count > 0) { - it = first; - step = count / 2; - std::advance(it, step); - if (*it < value) { - first = ++it; - count -= step + 1; - } else count = step; - } - return first; - } -.SH Second version - template - ForwardIt lower_bound(ForwardIt first, ForwardIt last, const T& value, Compare comp) - { - ForwardIt it; - typename std::iterator_traits::difference_type count, step; - count = std::distance(first,last); - - while (count > 0) { - it = first; - step = count / 2; - std::advance(it, step); - if (comp(*it, value)) { - first = ++it; - count -= step + 1; - } else count = step; - } - return first; - } + See also the implementations in libstdc++ and libc++. + + lower_bound \fB(1)\fP + template::value_type> + ForwardIt lower_bound(ForwardIt first, ForwardIt last, const T& value) + { + return std::lower_bound(first, last, value, std::less{}); + } + lower_bound \fB(2)\fP + template::value_type, + class Compare> + ForwardIt lower_bound(ForwardIt first, ForwardIt last, const T& value, Compare comp) + { + ForwardIt it; + typename std::iterator_traits::difference_type count, step; + count = std::distance(first, last); + + while (count > 0) + { + it = first; + step = count / 2; + std::advance(it, step); + + if (comp(*it, value)) + { + first = ++it; + count -= step + 1; + } + else + count = step; + } + + return first; + } + +.SH Notes + + Although std::lower_bound only requires [first, last) to be partitioned, this + algorithm is usually used in the case where [first, last) is sorted, so that the + binary search is valid for any value. + + Unlike std::binary_search, std::lower_bound does not require operator< or comp to be + asymmetric (i.e., a < b and b < a always have different results). In fact, it does + not even require value < *iter or comp(value, *iter) to be well-formed for any + iterator iter in [first, last). + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) .SH Example - + // Run this code #include + #include + #include #include - #include #include - + + struct PriceInfo { double price; }; + int main() { - std::vector data = { 1, 1, 2, 3, 3, 3, 3, 4, 4, 4, 5, 5, 6 }; - - auto lower = std::lower_bound(data.begin(), data.end(), 4); - auto upper = std::upper_bound(data.begin(), data.end(), 4); - - std::copy(lower, upper, std::ostream_iterator(std::cout, " ")); + const std::vector data{1, 2, 4, 5, 5, 6}; + + for (int i = 0; i < 8; ++i) + { + // Search for first element x such that i ≤ x + auto lower = std::lower_bound(data.begin(), data.end(), i); + + std::cout << i << " ≤ "; + lower != data.end() + ? std::cout << *lower << " at index " << std::distance(data.begin(), lower) + : std::cout << "not found"; + std::cout << '\\n'; + } + + std::vector prices{{100.0}, {101.5}, {102.5}, {102.5}, {107.3}}; + + for (const double to_find : {102.5, 110.2}) + { + auto prc_info = std::lower_bound(prices.begin(), prices.end(), to_find, + [](const PriceInfo& info, double value) + { + return info.price < value; + }); + + prc_info != prices.end() + ? std::cout << prc_info->price << " at index " << prc_info - prices.begin() + : std::cout << to_find << " not found"; + std::cout << '\\n'; + } + + using CD = std::complex; + std::vector nums{{1, 0}, {2, 2}, {2, 1}, {3, 0}}; + auto cmpz = [](CD x, CD y) { return x.real() < y.real(); }; + #ifdef __cpp_lib_algorithm_default_value_type + auto it = std::lower_bound(nums.cbegin(), nums.cend(), {2, 0}, cmpz); + #else + auto it = std::lower_bound(nums.cbegin(), nums.cend(), CD{2, 0}, cmpz); + #endif + assert((*it == CD{2, 2})); } .SH Output: - 4 4 4 + 0 ≤ 1 at index 0 + 1 ≤ 1 at index 0 + 2 ≤ 2 at index 1 + 3 ≤ 4 at index 2 + 4 ≤ 4 at index 2 + 5 ≤ 5 at index 3 + 6 ≤ 6 at index 5 + 7 ≤ not found + 102.5 at index 2 + 110.2 not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + Compare was required to satisfy only a partitioning is + LWG 270 C++98 Compare and T was required required; + to be LessThanComparable (strict weak heterogeneous comparisons + ordering required) permitted + at most \\(\\scriptsize corrected to \\(\\scriptsize + LWG 384 C++98 \\log(N)+1\\)log(N)+1 comparisons were \\log_{2}(N)+O(1)\\)log + allowed 2(N)+1 + if any iterator iter exists in + [first, last) such that + LWG 2150 C++98 bool(comp(*iter, value)) is false, no iterator after + std::lower_bound iter can be returned + could return any iterator in + [iter, last) .SH See also - equal_range returns range of elements matching a specific key - \fI(function template)\fP - partition divides a range of elements into two groups - \fI(function template)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(function template)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP + partition divides a range of elements into two groups + \fI(function template)\fP + partition_point locates the partition point of a partitioned range + \fI(C++11)\fP \fI(function template)\fP + returns an iterator to the first element greater than a certain + upper_bound value + \fI(function template)\fP + returns an iterator to the first element not less than the given + lower_bound key + \fI(public member function of std::set)\fP + + returns an iterator to the first element not less than the given + lower_bound key + \fI(public member function of std::multiset)\fP + + ranges::lower_bound returns an iterator to the first element not less than the given + (C++20) value + (niebloid) diff --git a/man/std::make_any.3 b/man/std::make_any.3 new file mode 100644 index 000000000..48abc5ff8 --- /dev/null +++ b/man/std::make_any.3 @@ -0,0 +1,77 @@ +.TH std::make_any 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_any \- std::make_any + +.SH Synopsis + Defined in header + template< class T, class... Args > \fB(1)\fP \fI(since C++17)\fP + std::any make_any( Args&&... args ); + template< class T, class U, class... Args > \fB(2)\fP \fI(since C++17)\fP + std::any make_any( std::initializer_list il, Args&&... args ); + + Constructs an any object containing an object of type T, passing the provided + arguments to T's constructor. + + 1) Equivalent to return std::any(std::in_place_type, + std::forward(args)...); + 2) Equivalent to return std::any(std::in_place_type, il, + std::forward(args)...); + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto a0 = std::make_any("Hello, std::any!\\n"); + auto a1 = std::make_any>(0.1, 2.3); + + std::cout << std::any_cast(a0); + std::cout << std::any_cast&>(a1) << '\\n'; + + using lambda = std::function; + + // Put a lambda into std::any. Attempt #1 (failed). + std::any a2 = [] { std::cout << "Lambda #1.\\n"; }; + std::cout << "a2.type() = \\"" << a2.type().name() << "\\"\\n"; + + // any_cast casts to but actual type is not + // a std::function..., but ~ main::{lambda()#1}, and it is + // unique for each lambda. So, this throws... + try + { + std::any_cast(a2)(); + } + catch (std::bad_any_cast const& ex) + { + std::cout << ex.what() << '\\n'; + } + + // Put a lambda into std::any. Attempt #2 (successful). + auto a3 = std::make_any([] { std::cout << "Lambda #2.\\n"; }); + std::cout << "a3.type() = \\"" << a3.type().name() << "\\"\\n"; + std::any_cast(a3)(); + } + +.SH Possible output: + + Hello, std::any! + (0.1,2.3) + a2.type() = "Z4mainEUlvE_" + bad any_cast + a3.type() = "St8functionIFvvEE" + Lambda #2. + +.SH See also + + constructor constructs an any object + \fI(public member function)\fP + any_cast type-safe access to the contained object + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::make_error_code(std::errc).3 b/man/std::make_error_code(std::errc).3 index 1bdf700d1..29c5e18f6 100644 --- a/man/std::make_error_code(std::errc).3 +++ b/man/std::make_error_code(std::errc).3 @@ -1,11 +1,14 @@ -.TH std::make_error_code(std::errc) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_error_code(std::errc) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_error_code(std::errc) \- std::make_error_code(std::errc) + .SH Synopsis Defined in header - error_code make_error_code( std::errc e ); \fI(since C++11)\fP + std::error_code make_error_code( std::errc e ) noexcept; \fI(since C++11)\fP Creates error code value for errc enum e. - Equivalent to error_code(static_cast(e), generic_category()) + Equivalent to std::error_code(static_cast(e), std::generic_category()) .SH Parameters @@ -15,8 +18,9 @@ Error code corresponding to e. -.SH Exceptions +.SH See also - noexcept specification: - noexcept - + make_error_code(std::io_errc) constructs an iostream error code + \fI(C++11)\fP \fI(function)\fP + make_error_code(std::future_errc) constructs a future error code + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::make_error_code(std::future_errc).3 b/man/std::make_error_code(std::future_errc).3 index e9b161da0..8d4e1e148 100644 --- a/man/std::make_error_code(std::future_errc).3 +++ b/man/std::make_error_code(std::future_errc).3 @@ -1,4 +1,7 @@ -.TH std::make_error_code(std::future_errc) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_error_code(std::future_errc) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_error_code(std::future_errc) \- std::make_error_code(std::future_errc) + .SH Synopsis Defined in header std::error_code make_error_code( std::future_errc e ); \fI(since C++11)\fP @@ -26,11 +29,14 @@ .SH See also - error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP - future_errc identifies the future error codes - \fI(C++11)\fP \fI(enum)\fP + error_code holds a platform-dependent error code + \fI(C++11)\fP \fI(class)\fP + future_errc identifies the future error codes + \fI(C++11)\fP \fI(enum)\fP + make_error_code(std::errc) creates error code value for errc enum e + \fI(C++11)\fP \fI(function)\fP + make_error_code(std::io_errc) constructs an iostream error code + \fI(C++11)\fP \fI(function)\fP .SH Category: - * Todo no example diff --git a/man/std::make_error_code(std::io_errc).3 b/man/std::make_error_code(std::io_errc).3 index 4b9a2151e..c5bda93e6 100644 --- a/man/std::make_error_code(std::io_errc).3 +++ b/man/std::make_error_code(std::io_errc).3 @@ -1,11 +1,16 @@ -.TH std::make_error_code(std::io_errc) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_error_code(std::io_errc) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_error_code(std::io_errc) \- std::make_error_code(std::io_errc) + .SH Synopsis Defined in header - std::error_code make_error_code( std::io_errc e ); \fI(since C++11)\fP + std::error_code make_error_code( std::io_errc e ) noexcept; \fI(since C++11)\fP Constructs an std::error_code object from a value of type std::io_errc as if by - return std::error_code(static_cast(e), std::iostream_category()). This function - is called by the constructor of std::error_code when given an std::io_errc argument. + return std::error_code(static_cast(e), std::iostream_category()). + + This function is called by the constructor of std::error_code with an std::io_errc + argument. .SH Parameters @@ -16,22 +21,22 @@ A value of type std::error_code that holds the error code number from e associated with the error category "iostream". -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include + int main() { std::error_code ec = std::make_error_code(std::io_errc::stream); + + // This works because of the overloaded method + // and the is_error_code_enum specialization. + ec = std::io_errc::stream; + std::cout << "Error code from io_errc::stream has category " << ec.category().name() << '\\n'; } @@ -40,9 +45,22 @@ Error code from io_errc::stream has category iostream + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2087 C++11 make_error_code(io_errc) was not declared declared noexcept + noexcept + .SH See also - error_code holds a platform-dependent error code - \fI(C++11)\fP \fI(class)\fP - io_errc the IO stream error codes - \fI(C++11)\fP \fI(enum)\fP + error_code holds a platform-dependent error code + \fI(C++11)\fP \fI(class)\fP + io_errc the IO stream error codes + \fI(C++11)\fP \fI(enum)\fP + make_error_code(std::errc) creates error code value for errc enum e + \fI(C++11)\fP \fI(function)\fP + make_error_code(std::future_errc) constructs a future error code + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::make_error_condition(std::errc).3 b/man/std::make_error_condition(std::errc).3 index b1522d294..872ad0e49 100644 --- a/man/std::make_error_condition(std::errc).3 +++ b/man/std::make_error_condition(std::errc).3 @@ -1,21 +1,37 @@ -.TH std::make_error_condition(std::errc) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_error_condition(std::errc) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_error_condition(std::errc) \- std::make_error_condition(std::errc) + .SH Synopsis Defined in header - std::error_condition make_error_condition( std::errc e ); \fI(since C++11)\fP + std::error_condition make_error_condition( std::errc e ) noexcept; \fI(since C++11)\fP - Creates an error condition for an errc value e. Sets the error code to int(e) and + Creates an error condition for an errc value e. Sets the error value to int(e) and error category to std::generic_category. .SH Parameters - e - standard error code + e - standard error value .SH Return value Error condition for e. -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto err = std::make_error_condition(std::errc::invalid_argument); + std::cout << err.message() << '\\n'; + } + +.SH Possible output: - noexcept specification: - noexcept - + Invalid argument diff --git a/man/std::make_error_condition(std::future_errc).3 b/man/std::make_error_condition(std::future_errc).3 index f0be31d03..f4bcdc004 100644 --- a/man/std::make_error_condition(std::future_errc).3 +++ b/man/std::make_error_condition(std::future_errc).3 @@ -1,4 +1,7 @@ -.TH std::make_error_condition(std::future_errc) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_error_condition(std::future_errc) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_error_condition(std::future_errc) \- std::make_error_condition(std::future_errc) + .SH Synopsis Defined in header std::error_condition make_error_condition( std::future_errc e ); \fI(since C++11)\fP @@ -25,10 +28,9 @@ .SH See also error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP future_errc identifies the future error codes - \fI(C++11)\fP \fI(enum)\fP + \fI(C++11)\fP \fI(enum)\fP .SH Category: - * Todo no example diff --git a/man/std::make_error_condition(std::io_errc).3 b/man/std::make_error_condition(std::io_errc).3 index 9da365433..2e78c46c0 100644 --- a/man/std::make_error_condition(std::io_errc).3 +++ b/man/std::make_error_condition(std::io_errc).3 @@ -1,7 +1,10 @@ -.TH std::make_error_condition(std::io_errc) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_error_condition(std::io_errc) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_error_condition(std::io_errc) \- std::make_error_condition(std::io_errc) + .SH Synopsis Defined in header - std::error_condition make_error_condition( std::io_errc e ); \fI(since C++11)\fP + std::error_condition make_error_condition( std::io_errc e ) noexcept; \fI(since C++11)\fP Constructs an std::error_condition object from a value of type std::io_errc as if by return std::error_condition(static_cast(e), std::iostream_category()). @@ -15,23 +18,17 @@ A value of type std::error_condition that holds the error code number from e associated with the error category "iostream". -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - + int main() { - std::error_condition ec = std::make_error_condition(std::io_errc::stream); + std::error_condition ec = std::make_error_condition(std::io_errc::stream); std::cout << "error condition for io_errc::stream has value " << ec.value() << "\\nand message \\"" << ec.message() << "\\"\\n"; } @@ -41,9 +38,18 @@ error condition for io_errc::stream has value 1 and message "unspecified iostream_category error" + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2087 C++11 make_error_condition(io_errc) was not declared declared + noexcept noexcept + .SH See also error_condition holds a portable error code - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP io_errc the IO stream error codes - \fI(C++11)\fP \fI(enum)\fP + \fI(C++11)\fP \fI(enum)\fP diff --git a/man/std::make_exception_ptr.3 b/man/std::make_exception_ptr.3 index 041860785..fee4a7976 100644 --- a/man/std::make_exception_ptr.3 +++ b/man/std::make_exception_ptr.3 @@ -1,8 +1,11 @@ -.TH std::make_exception_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_exception_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_exception_ptr \- std::make_exception_ptr + .SH Synopsis Defined in header - template< class E > \fI(since C++11)\fP - std::exception_ptr make_exception_ptr( E e ) + template< class E > \fI(since C++11)\fP + std::exception_ptr make_exception_ptr( E e ) noexcept; Creates an std::exception_ptr that holds a reference to a copy of e. This is done as if executing the following code: @@ -23,13 +26,11 @@ instance of std::bad_alloc or to an instance of std::bad_exception (see std::current_exception). -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + The parameter is passed by value and is subject to slicing. .SH See also current_exception captures the current exception in a std::exception_ptr - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::make_format_args,std::make_wformat_args.3 b/man/std::make_format_args,std::make_wformat_args.3 new file mode 100644 index 000000000..0e0eee356 --- /dev/null +++ b/man/std::make_format_args,std::make_wformat_args.3 @@ -0,0 +1,165 @@ +.TH std::make_format_args,std::make_wformat_args 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_format_args,std::make_wformat_args \- std::make_format_args,std::make_wformat_args + +.SH Synopsis + Defined in header + template< class Context = std::format_context, class... Args > + + /*format-arg-store*/ \fB(1)\fP \fI(since C++20)\fP + + make_format_args( Args&... args ); + template< class... Args > + + /*format-arg-store*/ \fB(2)\fP \fI(since C++20)\fP + + make_wformat_args( Args&... args ); + + Returns an object that stores an array of formatting arguments and can be implicitly + converted to std::basic_format_args. + + The behavior is undefined if typename Context::template + formatter_type> does not meet the BasicFormatter + requirements for any Ti in Args. + + The program is ill-formed if for any type Ti in Args, Ti does not satisfy + __formattable_with. + + 2) Equivalent to return std::make_format_args(args...);. + +.SH Parameters + + args... - values to be used as formatting arguments + + Returns + + An object that holds the formatting arguments. + + For each argument t of type T, let TD be + std::remove_const_t>. The corresponding + std::basic_format_arg in the result is determined as below: + + * if TD is bool or Context::char_type, the std::basic_format_arg stores t; + * otherwise, if TD is char and Context::char_type is wchar_t, the + std::basic_format_arg stores static_cast(static_cast(t)); + * otherwise, if TD is a signed integer type whose size is not greater than int, + the std::basic_format_arg stores static_cast(t); + * otherwise, if TD is a unsigned integer type whose size is not greater than + unsigned int, the std::basic_format_arg stores static_cast(t); + * otherwise, if TD is a signed integer type whose size is not greater than long + long, the std::basic_format_arg stores static_cast(t); + * otherwise, if TD is a unsigned integer type whose size is not greater than + unsigned long long, the std::basic_format_arg stores static_cast(t); + * otherwise, if TD is float, double, or long double, the std::basic_format_arg + stores t; + * otherwise, if TD is a std::basic_string_view or std::basic_string specialization + and TD::char_type is Context::char_type, the std::basic_format_arg stores + std::basic_string_view(t.data(), t.size()); + * otherwise, if std::decay_t is Context::char_type* or const + Context::char_type*, the std::basic_format_arg stores static_cast(t); + * otherwise, if std::is_void_v> is true or + std::is_null_pointer_v is true, the std::basic_format_arg stores + static_cast(t); + * otherwise, the std::basic_format_arg stores a + std::basic_format_arg::handle to t, along with extra data needed for + handle::format(). + +.SH Notes + + A formatting argument has reference semantics for user-defined types and does not + extend the lifetime of args. It is the programmer's responsibility to ensure that + args outlive the return value. Usually, the result is only used as argument to + formatting function. + + Feature-test macro Value Std Feature + __cpp_lib_format_uchar 202311L (C++20) Formatting of code units as unsigned integers + (DR) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void raw_write_to_log(std::string_view users_fmt, std::format_args&& args) + { + static int n{}; + std::clog << std::format("{:04} : ", n++) << std::vformat(users_fmt, args) << '\\n'; + } + + template + constexpr void log(Args&&... args) + { + // Generate formatting string "{} "... + std::array braces{}; + constexpr const char c[4] = "{} "; + for (auto i{0uz}; i != braces.size() - 1; ++i) + braces[i] = c[i % 3]; + braces.back() = '\\0'; + + raw_write_to_log(std::string_view{braces.data()}, std::make_format_args(args...)); + } + + template + const T& unmove(T&& x) + { + return x; + } + + int main() + { + log("Number", "of", "arguments", "is", "arbitrary."); + log("Any type that meets the BasicFormatter requirements", "can be printed."); + log("For example:", 1, 2.0, '3', "*42*"); + + raw_write_to_log("{:02} │ {} │ {} │ {}", + std::make_format_args(unmove(1), unmove(2.0), unmove('3'), "4")); + } + +.SH Output: + + 0000 : Number of arguments is arbitrary. + 0001 : Any type that meets the BasicFormatter requirements can be printed. + 0002 : For example: 1 2.0 3 *42* + 0003 : 01 │ 2.0 │ 3 │ 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + objects that are neither + P2418R2 C++20 const-usable nor copyable allow formatting these + (such as generator-like objects) are objects + not formattable + P2905R2 C++20 make_format_args accepted rvalue only takes lvalue + arguments by forwarding references references + char or wchar_t might be formatted code units are converted to + P2909R4 C++20 as the corresponding + out-of-range unsigned integer values unsigned type before such + formatting + LWG 3631 C++20 cv-qualified arguments were handling corrected + incorrectly handled after P2418R2 + +.SH See also + + basic_format_args + format_args + wformat_args class that provides access to all formatting arguments + (C++20) \fI(class template)\fP + (C++20) + (C++20) + vformat non-template variant of std::format using type-erased argument + (C++20) representation + \fI(function)\fP + vformat_to non-template variant of std::format_to using type-erased argument + (C++20) representation + \fI(function template)\fP diff --git a/man/std::make_from_tuple.3 b/man/std::make_from_tuple.3 new file mode 100644 index 000000000..9b71b9e38 --- /dev/null +++ b/man/std::make_from_tuple.3 @@ -0,0 +1,104 @@ +.TH std::make_from_tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_from_tuple \- std::make_from_tuple + +.SH Synopsis + Defined in header + template< class T, class Tuple > \fI(since C++17)\fP + constexpr T make_from_tuple( Tuple&& t ); (until C++23) + template< class T, tuple-like Tuple > (since C++23) + constexpr T make_from_tuple( Tuple&& t ); + + Construct an object of type T, using the elements of the tuple t as the arguments to + the constructor. + + Given the exposition-only function /*make-from-tuple-impl*/ defined as follows: + template // no constraint on Tuple + before C++23 + constexpr T /*make-from-tuple-impl*/(Tuple&& t, std::index_sequence) + { + return T(std::get(std::forward(t))...); + } + + The effect is equivalent to: + return /*make-from-tuple-impl*/( + std::forward(t), + std::make_index_sequence>>{} + );. + + If + + * std::tuple_size_v> is 1 and (since + std::reference_constructs_from_temporary_v< C++23) + T, decltype(std::get<0>(std::declval()))> is true, or + + * std::is_constructible_v(std::declval()))...> is + false, + + the program is ill-formed. + +.SH Parameters + + t - tuple whose elements to be used as arguments to the constructor of T + +.SH Return value + + The constructed T object or reference. + +.SH Notes + + Tuple need not be std::tuple, and instead may be anything that + supports std::get and std::tuple_size; in particular, std::array and (until C++23) + std::pair may be used. + Tuple is constrained to be tuple-like, i.e. each type therein is + required to be a specialization of std::tuple or another type (such as (since C++23) + std::array and std::pair) that models tuple-like. + + Due to guaranteed copy elision, T need not be movable. + + Feature-test macro Value Std Feature + __cpp_lib_make_from_tuple 201606L \fI(C++17)\fP std::make_from_tuple + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + Foo(int first, float second, int third) + { + std::cout << first << ", " << second << ", " << third << '\\n'; + } + }; + + int main() + { + auto tuple = std::make_tuple(42, 3.14f, 0); + std::make_from_tuple(std::move(tuple)); + } + +.SH Output: + + 42, 3.14, 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3528 C++17 cast containing reinterpret_cast etc. was prohibited + allowed in the case of 1-tuple + +.SH See also + + make_tuple creates a tuple object of the type defined by the argument types + \fI(C++11)\fP \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP + apply calls a function with a tuple of arguments + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::make_heap.3 b/man/std::make_heap.3 index 9b0bb0b4e..393338250 100644 --- a/man/std::make_heap.3 +++ b/man/std::make_heap.3 @@ -1,99 +1,162 @@ -.TH std::make_heap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_heap \- std::make_heap + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP + template< class RandomIt > \fB(1)\fP (constexpr since C++20) void make_heap( RandomIt first, RandomIt last ); template< class RandomIt, class Compare > + void make_heap( RandomIt first, RandomIt last, Compare \fB(2)\fP (constexpr since C++20) + comp ); + + Constructs a heap in the range [first, last). - void make_heap( RandomIt first, RandomIt last, \fB(2)\fP + 1) The constructed heap is with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) The constructed heap is with respect to comp. - Compare comp ); + If any of the following conditions is satisfied, the behavior is undefined: - Constructs a max heap in the range [first, last). The first version of the function - uses operator< to compare the elements, the second uses the given comparison - function comp. + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements to make the heap from - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the range to make the heap from + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. - -.SH Return value - - \fI(none)\fP + Compare must meet the requirements of Compare. .SH Complexity - At most 3*std::distance(first, last) comparisons. - -.SH Notes - - A max heap is a range of elements [f,l) that has the following properties: - - * *f is the largest element in the range - * a new element can be added using std::push_heap() - * the first element can be removed using std::pop_heap() + Given \\(\\scriptsize N\\)N as std::distance(first, last): - The actual arrangement of the elements is implementation defined. + 1) At most \\(\\scriptsize 3N\\)3N comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize 3N\\)3N applications of the comparison function comp. .SH Example - + // Run this code - #include #include - - int main() + #include + #include + #include + #include + + void print(std::string_view text, const std::vector& v = {}) { - std::vector v { 3, 1, 4, 1, 5, 9 }; - - std::cout << "initially, v: "; - for (auto i : v) std::cout << i << ' '; + std::cout << text << ": "; + for (const auto& e : v) + std::cout << e << ' '; std::cout << '\\n'; - + } + + int main() + { + print("Max heap"); + + std::vector v{3, 2, 4, 1, 5, 9}; + print("initially, v", v); + std::make_heap(v.begin(), v.end()); - - std::cout << "after make_heap, v: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; - + print("after make_heap, v", v); + std::pop_heap(v.begin(), v.end()); - auto largest = v.back(); + print("after pop_heap, v", v); + + auto top = v.back(); v.pop_back(); - std::cout << "largest element: " << largest << '\\n'; - - std::cout << "after removing the largest element, v: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; + print("former top element", {top}); + print("after removing the former top element, v", v); + + print("\\nMin heap"); + + std::vector v1{3, 2, 4, 1, 5, 9}; + print("initially, v1", v1); + + std::make_heap(v1.begin(), v1.end(), std::greater<>{}); + print("after make_heap, v1", v1); + + std::pop_heap(v1.begin(), v1.end(), std::greater<>{}); + print("after pop_heap, v1", v1); + + auto top1 = v1.back(); + v1.pop_back(); + print("former top element", {top1}); + print("after removing the former top element, v1", v1); } .SH Output: - initially, v: 3 1 4 1 5 9 - after make_heap, v: 9 5 4 1 1 3 - largest element: 9 - after removing the largest element, v: 5 3 4 1 1 + Max heap: + initially, v: 3 2 4 1 5 9 + after make_heap, v: 9 5 4 1 2 3 + after pop_heap, v: 5 3 4 1 2 9 + former top element: 9 + after removing the former top element, v: 5 3 4 1 2 + + Min heap: + initially, v1: 3 2 4 1 5 9 + after make_heap, v1: 1 2 4 3 5 9 + after pop_heap, v1: 2 3 4 9 5 1 + former top element: 1 + after removing the former top element, v1: 2 3 4 9 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3032 C++98 the elements of [first, last) was not required required + to be swappable .SH See also - sort_heap turns a max heap into a range of elements sorted in ascending order - \fI(function template)\fP + is_heap checks if the given range is a max heap + \fI(C++11)\fP \fI(function template)\fP + is_heap_until finds the largest subrange that is a max heap + \fI(C++11)\fP \fI(function template)\fP + push_heap adds an element to a max heap + \fI(function template)\fP + pop_heap removes the largest element from a max heap + \fI(function template)\fP + turns a max heap into a range of elements sorted in ascending + sort_heap order + \fI(function template)\fP + priority_queue adapts a container to provide priority queue + \fI(class template)\fP + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) diff --git a/man/std::make_move_iterator.3 b/man/std::make_move_iterator.3 index d090bac54..527bb7ce4 100644 --- a/man/std::make_move_iterator.3 +++ b/man/std::make_move_iterator.3 @@ -1,10 +1,13 @@ -.TH std::make_move_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_move_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_move_iterator \- std::make_move_iterator + .SH Synopsis Defined in header - template< class Iterator > \fI(since C++11)\fP - std::move_iterator make_move_iterator( const Iterator& i ); \fI(until C++14)\fP - template< class Iterator > \fI(since C++14)\fP - std::move_iterator make_move_iterator( Iterator i ); + template< class Iter > \fI(since C++11)\fP + std::move_iterator make_move_iterator( Iter i ); \fI(until C++17)\fP + template< class Iter > \fI(since C++17)\fP + constexpr std::move_iterator make_move_iterator( Iter i ); make_move_iterator is a convenience function template that constructs a std::move_iterator for the given iterator i with the type deduced from the type of @@ -16,57 +19,67 @@ .SH Return value - A std::move_iterator which can be used to move from the elements accessed through i + A std::move_iterator which can be used to move from the elements accessed through i. .SH Possible implementation - template< class Iterator > - std::move_iterator make_move_iterator( Iterator i ) + template + constexpr std::move_iterator make_move_iterator(Iter i) { - return std::move_iterator(i); + return std::move_iterator(std::move(i)); } .SH Example - + // Run this code + #include #include + #include #include - #include #include - #include - + #include + + auto print = [](auto const rem, auto const& seq) + { + for (std::cout << rem; auto const& str : seq) + std::cout << std::quoted(str) << ' '; + std::cout << '\\n'; + }; + int main() { std::list s{"one", "two", "three"}; - + std::vector v1(s.begin(), s.end()); // copy - + std::vector v2(std::make_move_iterator(s.begin()), std::make_move_iterator(s.end())); // move - - std::cout << "v1 now holds: "; - for (auto str : v1) - std::cout << "\\"" << str << "\\" "; - std::cout << "\\nv2 now holds: "; - for (auto str : v2) - std::cout << "\\"" << str << "\\" "; - std::cout << "\\noriginal list now holds: "; - for (auto str : s) - std::cout << "\\"" << str << "\\" "; - std::cout << '\\n'; + + print("v1 now holds: ", v1); + print("v2 now holds: ", v2); + print("original list now holds: ", s); } -.SH Output: +.SH Possible output: v1 now holds: "one" "two" "three" v2 now holds: "one" "two" "three" original list now holds: "" "" "" + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2061 C++11 make_move_iterator did not convert array made to convert + arguments to pointers + .SH See also - move_iterator iterator adaptor which dereferences to an rvalue reference - \fI(C++11)\fP \fI(class template)\fP + move_iterator iterator adaptor which dereferences to an rvalue + \fI(C++11)\fP \fI(class template)\fP move obtains an rvalue reference - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::make_obj_using_allocator.3 b/man/std::make_obj_using_allocator.3 new file mode 100644 index 000000000..5b178fe0f --- /dev/null +++ b/man/std::make_obj_using_allocator.3 @@ -0,0 +1,50 @@ +.TH std::make_obj_using_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_obj_using_allocator \- std::make_obj_using_allocator + +.SH Synopsis + Defined in header + template< class T, class Alloc, class... Args > + constexpr T make_obj_using_allocator( const Alloc& alloc, Args&&... \fI(since C++20)\fP + args ); + + Creates an object of the given type T by means of uses-allocator construction. + + Equivalent to + + return std::make_from_tuple( + std::uses_allocator_construction_args(alloc, std::forward(args)...) + ); + +.SH Parameters + + alloc - the allocator to use + args - the arguments to pass to T's constructor + +.SH Return value + + The newly-created object of type T. + +.SH Exceptions + + May throw any exception thrown by the constructor of T, typically including + std::bad_alloc. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + prepares the argument list matching the + uses_allocator_construction_args flavor of uses-allocator construction + (C++20) required by the given type + \fI(function template)\fP + creates an object of the given type at + uninitialized_construct_using_allocator specified memory location by means of + (C++20) uses-allocator construction + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::make_optional.3 b/man/std::make_optional.3 index 3f1aac4fb..38bf90f46 100644 --- a/man/std::make_optional.3 +++ b/man/std::make_optional.3 @@ -1,28 +1,80 @@ -.TH std::make_optional 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_optional \- std::make_optional + .SH Synopsis Defined in header template< class T > + constexpr std::optional> make_optional( T&& value \fB(1)\fP \fI(since C++17)\fP + ); + template< class T, class... Args > \fB(2)\fP \fI(since C++17)\fP + constexpr std::optional make_optional( Args&&... args ); + template< class T, class U, class... Args > - constexpr optional::type> (library fundamentals TS) + constexpr std::optional make_optional( std::initializer_list \fB(3)\fP \fI(since C++17)\fP + il, - make_optional( T&& value ); + Args&&... args ); - Creates an optional object from value. Effectively calls optional::type>(std::forward(v)) + 1) Creates an optional object from value. Effectively calls + std::optional>(std::forward(value)). + 2) Creates an optional object constructed in-place from args.... Equivalent to + return std::optional(std::in_place, std::forward(args)...);. + 3) Creates an optional object constructed in-place from il and args.... Equivalent + to return std::optional(std::in_place, il, std::forward(args)...);. .SH Parameters - value - the value to construct optional object with + value - the value to construct optional object with + il, args - arguments to be passed to the constructor of T .SH Return value - An optional object with value as the contained value. + The constructed optional object. .SH Exceptions Throws any exception thrown by the constructor of T. +.SH Notes + + T need not be movable for overloads (2,3) due to guaranteed copy elision. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto op1 = std::make_optional>({'a','b','c'}); + std::cout << "op1: "; + for (char c : op1.value()) + std::cout << c << ','; + auto op2 = std::make_optional>(5, 2); + std::cout << "\\nop2: "; + for (int i : *op2) + std::cout << i << ','; + std::string str{"hello world"}; + auto op3 = std::make_optional(std::move(str)); + std::cout << "\\nop3: " << std::quoted(op3.value_or("empty value")) << '\\n'; + std::cout << "str: " << std::quoted(str) << '\\n'; + } + +.SH Possible output: + + op1: a,b,c, + op2: 2,2,2,2,2, + op3: "hello world" + str: "" + .SH See also constructor constructs the optional object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::make_pair.3 b/man/std::make_pair.3 index fecc1ef67..318dfe574 100644 --- a/man/std::make_pair.3 +++ b/man/std::make_pair.3 @@ -1,12 +1,13 @@ -.TH std::make_pair 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_pair 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_pair \- std::make_pair + .SH Synopsis Defined in header - template< class T1, class T2 > \fI(until C++11)\fP - std::pair make_pair( T1 t, T2 u ); - template< class T1, class T2 > \fI(since C++11)\fP - std::pair make_pair( T1&& t, T2&& u ); \fI(until C++14)\fP - template< class T1, class T2 > \fI(since C++14)\fP - constexpr std::pair make_pair( T1&& t, T2&& u ); + template< class T1, class T2 > \fI(until C++11)\fP + std::pair make_pair( T1 t, T2 u ); + template< class T1, class T2 > \fI(since C++11)\fP + std::pair make_pair( T1&& t, T2&& u ); (constexpr since C++14) Creates a std::pair object, deducing the target type from the types of arguments. @@ -22,35 +23,44 @@ .SH Return value - An std::pair object containing the given values. + A std::pair object containing the given values. .SH Example - + // Run this code + #include #include #include - #include - + int main() { int n = 1; int a[5] = {1, 2, 3, 4, 5}; - + // build a pair from two ints auto p1 = std::make_pair(n, a[1]); std::cout << "The value of p1 is " - << "(" << p1.first << ", " << p1.second << ")\\n"; - + << '(' << p1.first << ", " << p1.second << ")\\n"; + // build a pair from a reference to int and an array (decayed to pointer) auto p2 = std::make_pair(std::ref(n), a); n = 7; std::cout << "The value of p2 is " - << "(" << p2.first << ", " << *(p2.second + 1) << ")\\n"; + << '(' << p2.first << ", " << *(p2.second + 2) << ")\\n"; } .SH Output: The value of p1 is (1, 2) - The value of p2 is (7, 2) + The value of p2 is (7, 3) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 181 C++98 the parameter types were const-reference changed these + types, which made passing arrays impossible types to value types diff --git a/man/std::make_reverse_iterator.3 b/man/std::make_reverse_iterator.3 index d9723857d..3787d1132 100644 --- a/man/std::make_reverse_iterator.3 +++ b/man/std::make_reverse_iterator.3 @@ -1,45 +1,74 @@ -.TH std::make_reverse_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_reverse_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_reverse_iterator \- std::make_reverse_iterator + .SH Synopsis Defined in header - template \fI(since C++14)\fP - std::reverse_iterator make_reverse_iterator( Iterator i ); + template< class Iter > \fI(since C++14)\fP + std::reverse_iterator make_reverse_iterator( Iter i (constexpr since C++17) + ); make_reverse_iterator is a convenience function template that constructs a - std::reverse_iterator for the given iterator i with the type deduced from the type - of the argument. + std::reverse_iterator for the given iterator i (which must be a + LegacyBidirectionalIterator) with the type deduced from the type of the argument. .SH Parameters - i - input iterator to be converted to reverse iterator + i - iterator to be converted to reverse iterator .SH Return value - A std::reverse_iterator constructed from i + A std::reverse_iterator constructed from i. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_make_reverse_iterator 201402L \fI(C++14)\fP std::make_reverse_iterator .SH Possible implementation - template< class Iterator > - std::reverse_iterator make_reverse_iterator( Iterator i ) + template + constexpr std::reverse_iterator make_reverse_iterator(Iter i) { - return std::reverse_iterator(i); + return std::reverse_iterator(i); } .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v{1, 3, 10, 8, 22}; + + std::sort(v.begin(), v.end()); + std::copy(v.begin(), v.end(), std::ostream_iterator(std::cout, ", ")); + std::cout << '\\n'; + + std::copy(std::make_reverse_iterator(v.end()), + std::make_reverse_iterator(v.begin()), + std::ostream_iterator(std::cout, ", ")); + std::cout << '\\n'; + } + +.SH Output: + + 1, 3, 8, 10, 22, + 22, 10, 8, 3, 1, .SH See also reverse_iterator iterator adaptor for reverse-order traversal - \fI(class template)\fP - rbegin returns a reverse iterator to a container or array - crbegin \fI(function)\fP + \fI(class template)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP \fI(C++14)\fP rend returns a reverse end iterator for a container or array - crend \fI(function)\fP + crend \fI(function template)\fP \fI(C++14)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::make_shared,std::make_shared_for_overwrite.3 b/man/std::make_shared,std::make_shared_for_overwrite.3 new file mode 100644 index 000000000..860810e7c --- /dev/null +++ b/man/std::make_shared,std::make_shared_for_overwrite.3 @@ -0,0 +1,226 @@ +.TH std::make_shared,std::make_shared_for_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_shared,std::make_shared_for_overwrite \- std::make_shared,std::make_shared_for_overwrite + +.SH Synopsis + Defined in header + template< class T, class... Args > \fB(1)\fP \fI(since C++11)\fP + shared_ptr make_shared( Args&&... args ); (T is not array) + template< class T > \fB(2)\fP \fI(since C++20)\fP + shared_ptr make_shared( std::size_t N ); (T is U[]) + template< class T > \fB(3)\fP \fI(since C++20)\fP + shared_ptr make_shared(); (T is U[N]) + template< class T > \fI(since C++20)\fP + shared_ptr make_shared( std::size_t N, const \fB(4)\fP (T is U[]) + std::remove_extent_t& u ); + template< class T > \fB(5)\fP \fI(since C++20)\fP + shared_ptr make_shared( const std::remove_extent_t& u ); (T is U[N]) + template< class T > \fB(6)\fP \fI(since C++20)\fP + shared_ptr make_shared_for_overwrite(); (T is not U[]) + template< class T > \fB(7)\fP \fI(since C++20)\fP + shared_ptr make_shared_for_overwrite( std::size_t N ); (T is U[]) + + 1) Constructs an object of type T and wraps it in a std::shared_ptr using args as + the parameter list for the constructor of T. The object is constructed as if by the + expression ::new (pv) T(std::forward(args)...), where pv is an internal void* + pointer to storage suitable to hold an object of type T. The storage is typically + larger than sizeof(T) in order to use one allocation for both the control block of + the shared pointer and the T object. The std::shared_ptr constructor called by this + function enables shared_from_this with a pointer to the newly constructed object of + type T. + + This overload participates in overload resolution only if T is not an \fI(since C++20)\fP + array type. + + 2,3) Same as \fB(1)\fP, but the object constructed is a possibly-multidimensional array + whose non-array elements of type std::remove_all_extents_t are value-initialized + as if by placement-new expression ::new(pv) std::remove_all_extents_t(). The + overload \fB(2)\fP creates an array of size N along the first dimension. The array + elements are initialized in ascending order of their addresses, and when their + lifetime ends are destroyed in the reverse order of their original construction. + 4,5) Same as (2,3), but every element is initialized from the default value u. If U + is not an array type, then this is performed as if by the same placement-new + expression as in \fB(1)\fP; otherwise, this is performed as if by initializing every + non-array element of the (possibly multidimensional) array with the corresponding + element from u with the same placement-new expression as in \fB(1)\fP. The overload \fB(4)\fP + creates an array of size N along the first dimension. The array elements are + initialized in ascending order of their addresses, and when their lifetime ends are + destroyed in the reverse order of their original construction. + 6) Same as \fB(1)\fP if T is not an array type and \fB(3)\fP if T is U[N], except that the + created object is default-initialized. + 7) Same as \fB(2)\fP, except that the individual array elements are default-initialized. + + In each case, the object + (or individual elements if T is an array type) + \fI(since C++20)\fP will be destroyed by p->~X(), where p is a pointer to the object and X + is its type. + +.SH Parameters + + args - list of arguments with which an instance of T will be constructed + N - array size to use + u - the initial value to initialize every element of the array + +.SH Return value + + std::shared_ptr of an instance of type T. + +.SH Exceptions + + May throw std::bad_alloc or any exception thrown by the constructor of T. If an + exception is thrown, the functions have no effect. + If an exception is thrown during the construction of the array, already-initialized + elements are destroyed in reverse order. + \fI(since C++20)\fP + +.SH Notes + + This function may be used as an alternative to std::shared_ptr(new T(args...)). + The trade-offs are: + + * std::shared_ptr(new T(args...)) performs at least two allocations (one for + the object T and one for the control block of the shared pointer), while + std::make_shared typically performs only one allocation (the standard + recommends, but does not require this; all known implementations do this). + * If any std::weak_ptr references the control block created by std::make_shared + after the lifetime of all shared owners ended, the memory occupied by T persists + until all weak owners get destroyed as well, which may be undesirable if + sizeof(T) is large. + * std::shared_ptr(new T(args...)) may call a non-public constructor of T if + executed in context where it is accessible, while std::make_shared requires + public access to the selected constructor. + * Unlike the std::shared_ptr constructors, std::make_shared does not allow a + custom deleter. + * std::make_shared uses ::new, so if any special behavior has been set up using a + class-specific operator new, it will differ from std::shared_ptr(new + T(args...)). + + * std::shared_ptr supports array types (as of C++17), but + std::make_shared does not. This functionality is supported by \fI(until C++20)\fP + boost::make_shared. + + * code such as f(std::shared_ptr(new int\fB(42)\fP), g()) can cause a + memory leak if g gets called after new int\fB(42)\fP and throws an \fI(until C++17)\fP + exception, while f(std::make_shared\fB(42)\fP, g()) is safe, since + two function calls are never interleaved. + + A constructor enables shared_from_this with a pointer ptr of type U* means that it + determines if U has an + unambiguous and accessible + \fI(since C++17)\fP base class that is a specialization of std::enable_shared_from_this, + and if so, the constructor evaluates the statement: + + if (ptr != nullptr && ptr->weak_this.expired()) + ptr->weak_this = std::shared_ptr>( + *this, const_cast*>(ptr)); + + Where weak_this is the hidden mutable std::weak_ptr member of + std::enable_shared_from_this. The assignment to the weak_this member is not atomic + and conflicts with any potentially concurrent access to the same object. This + ensures that future calls to shared_from_this() would share ownership with the + std::shared_ptr created by this raw pointer constructor. + + The test ptr->weak_this.expired() in the exposition code above makes sure that + weak_this is not reassigned if it already indicates an owner. This test is required + as of C++17. + + Feature-test macro Value Std Feature + __cpp_lib_shared_ptr_arrays 201707L (C++20) Array support of std::make_shared; + overloads (2-5) + Smart pointer creation with default + initialization + __cpp_lib_smart_ptr_for_overwrite 202002L (C++20) (std::allocate_shared_for_overwrite, + std::make_shared_for_overwrite, + std::make_unique_for_overwrite); + overloads (6,7) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + struct C + { + // constructors needed \fI(until C++20)\fP + C(int i) : i(i) {} + C(int i, float f) : i(i), f(f) {} + int i; + float f{}; + }; + + int main() + { + // using `auto` for the type of `sp1` + auto sp1 = std::make_shared(1); // overload (1) + static_assert(std::is_same_v>); + std::cout << "sp1->{ i:" << sp1->i << ", f:" << sp1->f << " }\\n"; + + // being explicit with the type of `sp2` + std::shared_ptr sp2 = std::make_shared(2, 3.0f); // overload (1) + static_assert(std::is_same_v>); + static_assert(std::is_same_v); + std::cout << "sp2->{ i:" << sp2->i << ", f:" << sp2->f << " }\\n"; + + // shared_ptr to a value-initialized float[64]; overload (2): + std::shared_ptr sp3 = std::make_shared(64); + + // shared_ptr to a value-initialized long[5][3][4]; overload (2): + std::shared_ptr sp4 = std::make_shared(5); + + // shared_ptr to a value-initialized short[128]; overload (3): + std::shared_ptr sp5 = std::make_shared(); + + // shared_ptr to a value-initialized int[7][6][5]; overload (3): + std::shared_ptr sp6 = std::make_shared(); + + // shared_ptr to a double[256], where each element is 2.0; overload (4): + std::shared_ptr sp7 = std::make_shared(256, 2.0); + + // shared_ptr to a double[7][2], where each double[2] + // element is {3.0, 4.0}; overload (4): + std::shared_ptr sp8 = std::make_shared(7, {3.0, 4.0}); + + // shared_ptr to a vector[4], where each vector + // has contents {5, 6}; overload (4): + std::shared_ptr[]> sp9 = + std::make_shared[]>(4, {5, 6}); + + // shared_ptr to a float[512], where each element is 1.0; overload (5): + std::shared_ptr spA = std::make_shared(1.0); + + // shared_ptr to a double[6][2], where each double[2] element + // is {1.0, 2.0}; overload (5): + std::shared_ptr spB = std::make_shared({1.0, 2.0}); + + // shared_ptr to a vector[4], where each vector + // has contents {5, 6}; overload (5): + std::shared_ptr[4]> spC = + std::make_shared[4]>({5, 6}); + } + +.SH Output: + + sp1->{ i:1, f:0 } + sp2->{ i:2, f:3 } + +.SH See also + + constructor constructs new shared_ptr + \fI(public member function)\fP + allocate_shared creates a shared pointer that manages a new object + allocate_shared_for_overwrite allocated using an allocator + (C++20) \fI(function template)\fP + enable_shared_from_this allows an object to create a shared_ptr referring to + \fI(C++11)\fP itself + \fI(class template)\fP + make_unique + make_unique_for_overwrite creates a unique pointer that manages a new object + \fI(C++14)\fP \fI(function template)\fP + (C++20) + operator new allocation functions + operator new[] \fI(function)\fP diff --git a/man/std::make_shared.3 b/man/std::make_shared.3 deleted file mode 100644 index 40dfbb8d9..000000000 --- a/man/std::make_shared.3 +++ /dev/null @@ -1,63 +0,0 @@ -.TH std::make_shared 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T, class... Args > - shared_ptr make_shared( Args&&... args ); - - Constructs an object of type T and wraps it in a std::shared_ptr using args as the - parameter list for the constructor of T. - -.SH Parameters - - args - list of arguments with which an instance of T will be constructed. - -.SH Return value - - std::shared_ptr of an instance of type T. - -.SH Exceptions - - May throw std::bad_alloc or any exception thrown by the constructor of T. If an - exception is thrown, this function has no effect. - -.SH Notes - - This function typically allocates memory for the T object and for the shared_ptr's - control block with a single memory allocation (it is a non-binding requirement in - the Standard). In contrast, the declaration std::shared_ptr p(new T(Args...)) - performs at least two memory allocations, which may incur unnecessary overhead. - - Moreover, f(shared_ptr(new int\fB(42)\fP), g()) can lead to memory leak if g throws - an exception. This problem doesn't exist if make_shared is used. - -.SH Example - - -// Run this code - - #include - #include - - void foo(std::shared_ptr i) - { - (*i)++; - } - - int main() - { - auto sp = std::make_shared(10); - foo(sp); - std::cout << *sp << std::endl; - } - -.SH Output: - - 11 - -.SH See also - - constructor constructs new shared_ptr - \fI(public member function)\fP - creates a shared pointer that manages a new object allocated using - allocate_shared an allocator - \fI(function template)\fP diff --git a/man/std::make_signed.3 b/man/std::make_signed.3 index a37a4d818..e9661cb93 100644 --- a/man/std::make_signed.3 +++ b/man/std::make_signed.3 @@ -1,13 +1,29 @@ -.TH std::make_signed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_signed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_signed \- std::make_signed + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct make_signed; - Given an integral (except bool) or enumeration type T, provides the member typedef + If T is an integral (except bool) or enumeration type, provides the member typedef type which is the signed integer type corresponding to T, with the same cv-qualifiers. + If T is signed or unsigned char, short, int, long, long long, the signed type from + this list corresponding to T is provided. + + If T is an enumeration type or char, wchar_t + , char8_t + \fI(since C++20)\fP, char16_t, char32_t, the signed integer type with the smallest rank + having the same sizeof as T is provided. + + Otherwise, the behavior is undefined. \fI(until C++20)\fP + Otherwise, the program is ill-formed. \fI(since C++20)\fP + + If the program adds specializations for std::make_signed, the behavior is undefined. + .SH Member types Name Definition @@ -20,38 +36,33 @@ .SH Example - + // Run this code - #include #include - - int main() { - typedef std::make_signed::type char_type; - typedef std::make_signed::type int_type; - typedef std::make_signed::type long_type; - - bool ok1 = std::is_same::value; - bool ok2 = std::is_same::value; - bool ok3 = std::is_same::value; - - std::cout << std::boolalpha - << "char_type is 'signed char'? : " << ok1 << '\\n' - << "int_type is 'signed int'? : " << ok2 << '\\n' - << "long_type is 'volatile signed long'? : " << ok3 << '\\n'; - } -.SH Output: + enum struct E : unsigned short {}; - char_type is 'signed char'? : true - int_type is 'signed int'? : true - long_type is 'volatile signed long'? : true + int main() + { + using char_type = std::make_signed_t; + using int_type = std::make_signed_t; + using long_type = std::make_signed_t; + using enum_type = std::make_signed_t; + + static_assert( + std::is_same_v and + std::is_same_v and + std::is_same_v and + std::is_same_v + ); + } .SH See also - is_signed checks if a type is signed arithmetic type - \fI(C++11)\fP \fI(class template)\fP - is_unsigned checks if a type is unsigned arithmetic type - \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_unsigned checks if a type is an unsigned arithmetic type + \fI(C++11)\fP \fI(class template)\fP make_unsigned makes the given integral type unsigned - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::make_tuple.3 b/man/std::make_tuple.3 index b8cb1d739..293416c77 100644 --- a/man/std::make_tuple.3 +++ b/man/std::make_tuple.3 @@ -1,14 +1,15 @@ -.TH std::make_tuple 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_tuple \- std::make_tuple + .SH Synopsis Defined in header - template< class... Types > \fI(since C++11)\fP - tuple make_tuple( Types&&... args ); \fI(until C++14)\fP - template< class... Types > \fI(since C++14)\fP - constexpr tuple make_tuple( Types&&... args ); + template< class... Types > \fI(since C++11)\fP + std::tuple make_tuple( Types&&... args ); (constexpr since C++14) Creates a tuple object, deducing the target type from the types of arguments. - For each Ti in Types..., the corresponding type Vi in Vtypes... is + For each Ti in Types..., the corresponding type Vi in VTypes... is std::decay::type unless application of std::decay results in std::reference_wrapper for some type X, in which case the deduced type is X&. @@ -24,58 +25,75 @@ .SH Possible implementation template - struct special_decay + struct unwrap_refwrapper { - using type = typename std::decay::type; + using type = T; }; - + template - struct special_decay> + struct unwrap_refwrapper> { using type = T&; }; - + template - using special_decay_t = typename special_decay::type; - + using unwrap_decay_t = typename unwrap_refwrapper::type>::type; + // or use std::unwrap_ref_decay_t \fI(since C++20)\fP + template - auto make_tuple(Types&&... args) + constexpr // since C++14 + std::tuple...> make_tuple(Types&&... args) { - return std::tuple...>(std::forward(args)...); + return std::tuple...>(std::forward(args)...); } .SH Example - + // Run this code #include #include #include - + + std::tuple f() // this function returns multiple values + { + int x = 5; + return std::make_tuple(x, 7); // return {x,7}; in C++17 + } + int main() { - auto t1 = std::make_tuple(10, "Test", 3.14); - std::cout << "The value of t1 is " - << "(" << std::get<0>(t1) << ", " << std::get<1>(t1) - << ", " << std::get<2>(t1) << ")\\n"; - + // heterogeneous tuple construction int n = 1; - auto t2 = std::make_tuple(std::ref(n), n); + auto t = std::make_tuple(10, "Test", 3.14, std::ref(n), n); n = 7; - std::cout << "The value of t2 is " - << "(" << std::get<0>(t2) << ", " << std::get<1>(t2) << ")\\n"; + std::cout << "The value of t is (" + << std::get<0>(t) << ", " + << std::get<1>(t) << ", " + << std::get<2>(t) << ", " + << std::get<3>(t) << ", " + << std::get<4>(t) << ")\\n"; + + // function returning multiple values + int a, b; + std::tie(a, b) = f(); + std::cout << a << ' ' << b << '\\n'; } .SH Output: - The value of t1 is (10, Test, 3.14) - The value of t2 is (7, 1) + The value of t is (10, Test, 3.14, 7, 1) + 5 7 + +.SH See also - creates a tuple of lvalue references or unpacks a tuple into - tie individual objects - \fI(function template)\fP - forward_as_tuple creates a tuple of rvalue references - \fI(function template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into + \fI(C++11)\fP individual objects + \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP tuple_cat creates a tuple by concatenating any number of tuples - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + apply calls a function with a tuple of arguments + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::make_unique,std::make_unique_for_overwrite.3 b/man/std::make_unique,std::make_unique_for_overwrite.3 new file mode 100644 index 000000000..4b0ca9baa --- /dev/null +++ b/man/std::make_unique,std::make_unique_for_overwrite.3 @@ -0,0 +1,280 @@ +.TH std::make_unique,std::make_unique_for_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_unique,std::make_unique_for_overwrite \- std::make_unique,std::make_unique_for_overwrite + +.SH Synopsis + Defined in header + (since + C++14) + template< class T, class... Args > (until + unique_ptr make_unique( C++23) + Args&&... args ); (only for + non-array + types) + (since + template< class T, class... Args > C++23) + constexpr unique_ptr (only for + make_unique( Args&&... args ); non-array + types) + (since + C++14) + (until + template< class T > C++23) + unique_ptr make_unique( (only for + std::size_t size ); array + types with + unknown + bound) + (since + C++23) + template< class T > (only for + constexpr unique_ptr array + make_unique( std::size_t size ); types with + unknown + bound) + (since + C++14) + template< class T, class... Args > (only for + /* unspecified */ make_unique( \fB(3)\fP array + Args&&... args ) = delete; types with + known + bound) + (since + \fB(1)\fP C++20) + template< class T > (until + unique_ptr C++23) + make_unique_for_overwrite(); (only for + non-array + types) + \fB(2)\fP (since + template< class T > C++23) + constexpr unique_ptr (only for + make_unique_for_overwrite(); non-array + types) + (since + C++20) + (until + template< class T > C++23) + unique_ptr (only for + make_unique_for_overwrite( array + std::size_t size ); \fB(4)\fP types + with + unknown + bound) + (since + C++23) + template< class T > \fB(5)\fP (only for + constexpr unique_ptr array + make_unique_for_overwrite( types + std::size_t size ); with + unknown + bound) + (since + C++20) + template< class T, class... Args > (only for + /* unspecified */ \fB(6)\fP array + make_unique_for_overwrite( types + Args&&... args ) = delete; with + known + bound) + + Constructs an object of type T and wraps it in a std::unique_ptr. + + 1) Constructs a non-array type T. The arguments args are passed to the constructor + of T. This overload participates in overload resolution only if T is not an array + type. The function is equivalent to: + + unique_ptr(new T(std::forward(args)...)) + + 2) Constructs an array of the given dynamic size. The array elements are + value-initialized. This overload participates in overload resolution only if T is an + array of unknown bound. The function is equivalent to: + + unique_ptr(new std::remove_extent_t[size]()) + + 3,6) Construction of arrays of known bound is disallowed. + 4) Same as \fB(1)\fP, except that the object is default-initialized. This overload + participates in overload resolution only if T is not an array type. The function is + equivalent to: + + unique_ptr(new T) + + 5) Same as \fB(2)\fP, except that the array is default-initialized. This overload + participates in overload resolution only if T is an array of unknown bound. The + function is equivalent to: + + unique_ptr(new std::remove_extent_t[size]) + +.SH Parameters + + args - list of arguments with which an instance of T will be constructed + size - the length of the array to construct + +.SH Return value + + std::unique_ptr of an instance of type T. + +.SH Exceptions + + May throw std::bad_alloc or any exception thrown by the constructor of T. If an + exception is thrown, this function has no effect. + + Possible Implementation + + make_unique (1-3) + // C++14 make_unique + namespace detail + { + template + constexpr bool is_unbounded_array_v = false; + template + constexpr bool is_unbounded_array_v = true; + + template + constexpr bool is_bounded_array_v = false; + template + constexpr bool is_bounded_array_v = true; + } // namespace detail + + template + std::enable_if_t::value, std::unique_ptr> + make_unique(Args&&... args) + { + return std::unique_ptr(new T(std::forward(args)...)); + } + + template + std::enable_if_t, std::unique_ptr> + make_unique(std::size_t n) + { + return std::unique_ptr(new std::remove_extent_t[n]()); + } + + template + std::enable_if_t> make_unique(Args&&...) = delete; + make_unique_for_overwrite (4-6) + // C++20 make_unique_for_overwrite + template + requires (!std::is_array_v) + std::unique_ptr make_unique_for_overwrite() + { + return std::unique_ptr(new T); + } + + template + requires std::is_unbounded_array_v + std::unique_ptr make_unique_for_overwrite(std::size_t n) + { + return std::unique_ptr(new std::remove_extent_t[n]); + } + + template + requires std::is_bounded_array_v + void make_unique_for_overwrite(Args&&...) = delete; + +.SH Notes + + Unlike std::make_shared (which has std::allocate_shared), std::make_unique does not + have an allocator-aware counterpart. allocate_unique proposed in P0211 would be + required to invent the deleter type D for the std::unique_ptr it returns which + would contain an allocator object and invoke both destroy and deallocate in its + operator(). + + Feature-test macro Value Std Feature + __cpp_lib_make_unique 201304L \fI(C++14)\fP std::make_unique; overload \fB(1)\fP + Smart pointer creation with default + initialization + __cpp_lib_smart_ptr_for_overwrite 202002L (C++20) (std::allocate_shared_for_overwrite, + std::make_shared_for_overwrite, + std::make_unique_for_overwrite); + overloads (4-6) + __cpp_lib_constexpr_memory 202202L (C++23) constexpr for overloads (1,2,4,5) + +.SH Example + + This section is incomplete + Reason: add more make_unique_for_overwrite() demos + + +// Run this code + + #include + #include + #include + #include + #include + + struct Vec3 + { + int x, y, z; + + // Following constructor is no longer needed since C++20. + Vec3(int x = 0, int y = 0, int z = 0) noexcept : x(x), y(y), z(z) {} + + friend std::ostream& operator<<(std::ostream& os, const Vec3& v) + { + return os << "{ x=" << v.x << ", y=" << v.y << ", z=" << v.z << " }"; + } + }; + + // Output Fibonacci numbers to an output iterator. + template + OutputIt fibonacci(OutputIt first, OutputIt last) + { + for (int a = 0, b = 1; first != last; ++first) + { + *first = b; + b += std::exchange(a, b); + } + return first; + } + + int main() + { + // Use the default constructor. + std::unique_ptr v1 = std::make_unique(); + // Use the constructor that matches these arguments. + std::unique_ptr v2 = std::make_unique(0, 1, 2); + // Create a unique_ptr to an array of 5 elements. + std::unique_ptr v3 = std::make_unique(5); + + // Create a unique_ptr to an uninitialized array of 10 integers, + // then populate it with Fibonacci numbers. + std::unique_ptr i1 = std::make_unique_for_overwrite(10); + fibonacci(i1.get(), i1.get() + 10); + + std::cout << "make_unique(): " << *v1 << '\\n' + << "make_unique(0,1,2): " << *v2 << '\\n' + << "make_unique(5): "; + for (std::size_t i = 0; i < 5; ++i) + std::cout << std::setw(i ? 30 : 0) << v3[i] << '\\n'; + std::cout << '\\n'; + + std::cout << "make_unique_for_overwrite(10), fibonacci(...): [" << i1[0]; + for (std::size_t i = 1; i < 10; ++i) + std::cout << ", " << i1[i]; + std::cout << "]\\n"; + } + +.SH Output: + + make_unique(): { x=0, y=0, z=0 } + make_unique(0,1,2): { x=0, y=1, z=2 } + make_unique\fB(5)\fP: { x=0, y=0, z=0 } + { x=0, y=0, z=0 } + { x=0, y=0, z=0 } + { x=0, y=0, z=0 } + { x=0, y=0, z=0 } + + make_unique_for_overwrite\fB(10)\fP, fibonacci(...): [1, 1, 2, 3, 5, 8, 13, 21, 34, 55] + +.SH See also + + constructor constructs a new unique_ptr + \fI(public member function)\fP + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + +.SH Category: + * Todo with reason diff --git a/man/std::make_unique.3 b/man/std::make_unique.3 deleted file mode 100644 index cf36f2607..000000000 --- a/man/std::make_unique.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH std::make_unique 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T, class... Args > \fB(1)\fP \fI(since C++14)\fP - unique_ptr make_unique( Args&&... args ); (only for non-array types) - template< class T > \fI(since C++14)\fP - unique_ptr make_unique( std::size_t size \fB(2)\fP (only for array types with unknown - ); bound) - template< class T, class... Args > \fI(since C++14)\fP - /* unspecified */ make_unique( Args&&... args \fB(3)\fP (only for array types with known - ) = delete; bound) - - Constructs an object of type T and wraps it in a std::unique_ptr. - - 1) Constructs a non-array type T. The arguments args are passed to the constructor - of T. The function does not participate in the overload resolution if T is an array - type. The function is equivalent to: - - unique_ptr(new T(std::forward(args)...)) - - 2) Constructs an array of unknown bound T. The function does not participate in the - overload resolution unless T is an array of unknown bound. The function is - equivalent to: - - unique_ptr(new typename std::remove_extent::type[size]()) - - 3) Construction of arrays of known bound is disallowed. - -.SH Parameters - - args - list of arguments with which an instance of T will be constructed. - size - the size of the array to construct - -.SH Return value - - std::unique_ptr of an instance of type T. - -.SH Exceptions - - Any exception thrown by the contructor of T. If an exception is thrown, this - function has no effect. - -.SH See also - - constructor constructs a new unique_ptr - \fI(public member function)\fP diff --git a/man/std::make_unsigned.3 b/man/std::make_unsigned.3 index 7c76058ff..fd2713583 100644 --- a/man/std::make_unsigned.3 +++ b/man/std::make_unsigned.3 @@ -1,13 +1,30 @@ -.TH std::make_unsigned 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::make_unsigned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::make_unsigned \- std::make_unsigned + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct make_unsigned; - Given an integral (except bool) or enumeration type T, provides the member typedef + If T is an integral (except bool) or enumeration type, provides the member typedef type which is the unsigned integer type corresponding to T, with the same cv-qualifiers. + If T is signed or unsigned char, short, int, long, long long; the unsigned type from + this list corresponding to T is provided. + + If T is an enumeration type or char, wchar_t + , char8_t + \fI(since C++20)\fP, char16_t, char32_t; the unsigned integer type with the smallest rank + having the same sizeof as T is provided. + + Otherwise, the behavior is undefined. \fI(until C++20)\fP + Otherwise, the program is ill-formed. \fI(since C++20)\fP + + If the program adds specializations for std::make_unsigned, the behavior is + undefined. + .SH Member types Name Definition @@ -20,38 +37,29 @@ .SH Example - + // Run this code - #include #include - - int main() { - typedef std::make_unsigned::type char_type; - typedef std::make_unsigned::type int_type; - typedef std::make_unsigned::type long_type; - - bool ok1 = std::is_same::value; - bool ok2 = std::is_same::value; - bool ok3 = std::is_same::value; - - std::cout << std::boolalpha - << "char_type is 'unsigned char'? : " << ok1 << '\\n' - << "int_type is 'unsigned int'? : " << ok2 << '\\n' - << "long_type is 'volatile unsigned long'? : " << ok3 << '\\n'; - } -.SH Output: + int main() + { + using uchar_type = std::make_unsigned_t; + using uint_type = std::make_unsigned_t; + using ulong_type = std::make_unsigned_t; - char_type is 'unsigned char'? : true - int_type is 'unsigned int'? : true - long_type is 'volatile unsigned long'? : true + static_assert( + std::is_same_v and + std::is_same_v and + std::is_same_v + ); + } .SH See also - is_signed checks if a type is signed arithmetic type - \fI(C++11)\fP \fI(class template)\fP - is_unsigned checks if a type is unsigned arithmetic type - \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP + is_unsigned checks if a type is an unsigned arithmetic type + \fI(C++11)\fP \fI(class template)\fP make_signed makes the given integral type signed - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::malloc.3 b/man/std::malloc.3 index cc0c7e35d..55c66c6e1 100644 --- a/man/std::malloc.3 +++ b/man/std::malloc.3 @@ -1,4 +1,7 @@ -.TH std::malloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::malloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::malloc \- std::malloc + .SH Synopsis Defined in header void* malloc( std::size_t size ); @@ -6,11 +9,25 @@ Allocates size bytes of uninitialized storage. If allocation succeeds, returns a pointer to the lowest (first) byte in the - allocated memory block that is suitably aligned for any object type. + allocated memory block that is suitably aligned for any scalar type (at least as + strictly as std::max_align_t) (implicitly creating objects in the destination area). If size is zero, the behavior is implementation defined (null pointer may be returned, or some non-null pointer may be returned that may not be used to access - storage) + storage, but has to be passed to std::free). + + The following functions are required to be thread-safe: + + * The library versions of operator new and operator delete + * User replacement versions of global operator new and operator + delete + * std::calloc, std::malloc, std::realloc \fI(since C++11)\fP + , std::aligned_alloc + \fI(since C++17)\fP, std::free + + Calls to these functions that allocate or deallocate a particular unit + of storage occur in a single total order, and each such deallocation + call happens-before the next allocation (if any) in this order. .SH Parameters @@ -18,51 +35,65 @@ .SH Return value - Pointer to the beginning of newly allocated memory or null pointer if error has - occurred. The pointer must be deallocated with std::free(). + On success, returns the pointer to the beginning of newly allocated memory. To avoid + a memory leak, the returned pointer must be deallocated with std::free() or + std::realloc(). + + On failure, returns a null pointer. .SH Notes - This function does not call constructors or initialize memory in any way. Thus - preferred method of memory allocation is new expression. + This function does not call constructors or initialize memory in any way. There are + no ready-to-use smart pointers that could guarantee that the matching deallocation + function is called. The preferred method of memory allocation in C++ is using + RAII-ready functions std::make_unique, std::make_shared, container constructors, + etc, and, in low-level library code, new-expression. + + For loading a large file, file mapping via OS-specific functions, e.g. mmap on POSIX + or CreateFileMapping(A/W) along with MapViewOfFile on Windows, is preferable to + allocating a buffer for file reading. .SH Example - + // Run this code #include #include - + #include + #include + int main() { - // Allocate an array of 4 integers - int *array = static_cast(std::malloc(4 * sizeof(int))); - - if (array != nullptr) { - for (int arrayIdx = 0; arrayIdx < 4; ++arrayIdx) { - array[arrayIdx] = 2 * ( arrayIdx + 1 ); - } - - for (int arrayIdx = 0; arrayIdx < 4; ++arrayIdx) { - std::cout << "Array item " << ( arrayIdx + 1 ) << " = " << array[arrayIdx] << '\\n'; + constexpr std::size_t size = 4; + if (auto ptr = reinterpret_cast(std::malloc(size * sizeof(std::string)))) + { + try + { + for (std::size_t i = 0; i < size; ++i) + std::construct_at(ptr + i, 5, 'a' + i); + for (std::size_t i = 0; i < size; ++i) + std::cout << "ptr[" << i << "] == " << ptr[i] << '\\n'; + std::destroy_n(ptr, size); } - std::free(array); + catch (...) {} + std::free(ptr); } } -.SH Possible output: +.SH Output: - Array item 1 = 2 - Array item 2 = 4 - Array item 3 = 6 - Array item 4 = 8 + p[0] == aaaaa + p[1] == bbbbb + p[2] == ccccc + p[3] == ddddd .SH See also - operator new allocation functions - operator new[] \fI(function)\fP - get_temporary_buffer obtains uninitialized storage - \fI(function template)\fP + operator new allocation functions + operator new[] \fI(function)\fP + get_temporary_buffer obtains uninitialized storage + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) C documentation for malloc diff --git a/man/std::map.3 b/man/std::map.3 index 6381a75e3..0503c78d5 100644 --- a/man/std::map.3 +++ b/man/std::map.3 @@ -1,121 +1,295 @@ -.TH std::map 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map \- std::map + .SH Synopsis Defined in header template< class Key, - class T, + class T, \fB(1)\fP class Compare = std::less, - class Allocator = std::allocator > + class Allocator = std::allocator> > class map; + namespace pmr { + + template< + class Key, + class T, + class Compare = std::less \fB(2)\fP \fI(since C++17)\fP + > using map = std::map>>; + + } std::map is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function Compare. Search, removal, and insertion operations have logarithmic complexity. Maps are usually implemented as - red-black trees. + Red–black trees. + + Iterators of std::map iterate in ascending order of keys, where ascending is defined + by the comparison that was used for construction. That is, given + + * m, a std::map + * it_l and it_r, dereferenceable iterators to m, with it_l < it_r. + + m.value_comp()(*it_l, *it_r) == true (least to greatest if using the default + comparison). + + Everywhere the standard library uses the Compare requirements, uniqueness is + determined by using the equivalence relation. In imprecise terms, two objects a and + b are considered equivalent (not unique) if neither compares less than the other: + !comp(a, b) && !comp(b, a). std::map meets the requirements of Container, AllocatorAwareContainer, AssociativeContainer and ReversibleContainer. +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - mapped_type T - value_type std::pair - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - key_compare Compare - allocator_type Allocator - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP - pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP - const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator BidirectionalIterator - const_iterator Constant bidirectional iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + Member type Definition + key_type Key + mapped_type T + value_type std::pair + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + key_compare Compare + allocator_type Allocator + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer (until + C++11) + const_pointer std::allocator_traits::const_pointer (since + C++11) + + + iterator LegacyBidirectionalIterator to value_type + const_iterator LegacyBidirectionalIterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node + type describing the result of inserting a node_type, a + specialization of + + template + struct /*unspecified*/ + insert_return_type (since { + C++17) Iter position; + bool inserted; + NodeType node; + }; + instantiated with template arguments iterator and + node_type. .SH Member classes value_compare compares objects of type value_type - \fI(class)\fP + \fI(class)\fP .SH Member functions - constructor constructs the map - \fI(public member function)\fP - destructor destructs the map - \fI(public member function)\fP - operator= assigns values to the container - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs the map + \fI(public member function)\fP + destructor destructs the map + \fI(public member function)\fP + operator= assigns values to the container + \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Element access - at access specified element with bounds checking - \fI(C++11)\fP \fI(public member function)\fP - operator[] access specified element - \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + operator[] access or insert specified element + \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - size returns the number of elements - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP + empty checks whether the container is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP .SH Modifiers - clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP - erase erases elements - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + insert_or_assign inserts an element or assigns to the current element if the key + \fI(C++17)\fP already exists + \fI(public member function)\fP + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(C++11)\fP \fI(public member function)\fP + try_emplace inserts in-place if the key does not exist, does nothing if the key + \fI(C++17)\fP exists + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup - count returns the number of elements matching specific key - \fI(public member function)\fP - find finds element with specific key - \fI(public member function)\fP - equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP + returns an iterator to the first element not less than the given + lower_bound key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP .SH Observers - key_comp returns the function that compares keys - \fI(public member function)\fP - value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + key_comp returns the function that compares keys + \fI(public member function)\fP + returns the function that compares keys in objects of type + value_comp value_type + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the map - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two maps + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::map) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase_if(std::map) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print_map(std::string_view comment, const std::map& m) + { + std::cout << comment; + // Iterate using C++17 facilities + for (const auto& [key, value] : m) + std::cout << '[' << key << "] = " << value << "; "; + + // C++11 alternative: + // for (const auto& n : m) + // std::cout << n.first << " = " << n.second << "; "; + // + // C++98 alternative: + // for (std::map::const_iterator it = m.begin(); it != m.end(); ++it) + // std::cout << it->first << " = " << it->second << "; "; + + std::cout << '\\n'; + } + + int main() + { + // Create a map of three (string, int) pairs + std::map m{{"CPU", 10}, {"GPU", 15}, {"RAM", 20}}; + + print_map("1) Initial map: ", m); + + m["CPU"] = 25; // update an existing value + m["SSD"] = 30; // insert a new value + print_map("2) Updated map: ", m); + + // Using operator[] with non-existent key always performs an insert + std::cout << "3) m[UPS] = " << m["UPS"] << '\\n'; + print_map("4) Updated map: ", m); + + m.erase("GPU"); + print_map("5) After erase: ", m); + + std::erase_if(m, [](const auto& pair){ return pair.second > 25; }); + print_map("6) After erase: ", m); + std::cout << "7) m.size() = " << m.size() << '\\n'; + + m.clear(); + std::cout << std::boolalpha << "8) Map is empty: " << m.empty() << '\\n'; + } + +.SH Output: + + 1) Initial map: [CPU] = 10; [GPU] = 15; [RAM] = 20; + 2) Updated map: [CPU] = 25; [GPU] = 15; [RAM] = 20; [SSD] = 30; + 3) m[UPS] = 0 + 4) Updated map: [CPU] = 25; [GPU] = 15; [RAM] = 20; [SSD] = 30; [UPS] = 0; + 5) After erase: [CPU] = 25; [RAM] = 20; [SSD] = 30; [UPS] = 0; + 6) After erase: [CPU] = 25; [RAM] = 20; [UPS] = 0; + 7) m.size() = 3 + 8) Map is empty: true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + Key was not required to be + LWG 230 C++98 CopyConstructible Key is also required to + (a key of type Key might not be able to be CopyConstructible + be constructed) + LWG 464 C++98 accessing a const map by key was at function provided + inconvenient + +.SH See also + + unordered_map collection of key-value pairs, hashed by keys, keys are unique + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::map::at.3 b/man/std::map::at.3 index d9f3e0847..57bd4917c 100644 --- a/man/std::map::at.3 +++ b/man/std::map::at.3 @@ -1,28 +1,78 @@ -.TH std::map::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::at \- std::map::at + .SH Synopsis - T& at( const Key& key ); \fB(1)\fP \fI(since C++11)\fP - const T & at( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + T& at( const Key& key ); \fB(1)\fP + const T& at( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP (since C++26) + T& at( const K& x ); + template< class K > \fB(4)\fP (since C++26) + const T& at( const K& x ) const; + + Returns a reference to the mapped value of the element with specified key. If no + such element exists, an exception of type std::out_of_range is thrown. - Returns a reference to the mapped value of the element with key equivalent to key. - If no such element exists, an exception of type std::out_of_range is thrown. + 1,2) The key is equivalent to key. + 3,4) The key compares equivalent to the value x. The reference to the mapped value + is obtained as if by expression this->find(x)->second. + The expression this->find(x) must be well-formed and have well-defined behavior, + otherwise the behavior is undefined. + These overloads participate in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters key - the key of the element to find + x - a value of any type that can be transparently compared with a key .SH Return value - Reference to the mapped value of the requested element + A reference to the mapped value of the requested element. .SH Exceptions - std::out_of_range if the container does not have an element with the specified key + 1,2) std::out_of_range if the container does not have an element with the specified + key. + 3,4) std::out_of_range if the container does not have the specified element, that + is, if find(x) == end() is true. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. (3,4) + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 464 C++98 map did not have this member function added + LWG 703 C++98 the complexity requirement was missing added + LWG 2007 C++98 the return value referred to the requested refers to its mapped + element value + .SH See also - operator[] access specified element - \fI(public member function)\fP + operator[] access or insert specified element + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::map::begin,std::map::cbegin.3 b/man/std::map::begin,std::map::cbegin.3 index b5a842d5a..9a1aab8f2 100644 --- a/man/std::map::begin,std::map::cbegin.3 +++ b/man/std::map::begin,std::map::cbegin.3 @@ -1,12 +1,15 @@ -.TH std::map::begin,std::map::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::begin,std::map::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::begin,std::map::cbegin \- std::map::begin,std::map::cbegin + .SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin(); \fB(1)\fP (noexcept since C++11) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the map. - If the container is empty, the returned iterator will be equal to end(). + If the map is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,20 +19,120 @@ .SH Return value - Iterator to the first element + Iterator to the first element. -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Constant. -.SH Complexity +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::map num_map; + num_map[4] = 4.13; + num_map[9] = 9.24; + num_map[1] = 1.09; + // Calls num_map.begin() and num_map.end() + for (auto it = num_map.begin(); it != num_map.end(); ++it) + std::cout << it->first << ", " << it->second << '\\n'; + } + +.SH Output: + + 1, 1.09 + 4, 4.13 + 9, 9.24 + + Example using a custom comparison function + + +// Run this code + + #include + #include + #include + + struct Point { double x, y; }; + + // Compare the x-coordinates of two Point pointers. + struct PointCmp + { + bool operator()(const Point* lhs, const Point* rhs) const + { + return lhs->x < rhs->x; + } + }; + + int main() + { + // Note that although the x-coordinates are out of order, the + // map will be iterated through by increasing x-coordinates. + Point points[3] = {{2, 0}, {1, 0}, {3, 0}}; + + // mag is a map sending the address of node to its magnitude in the x-y plane. + // Although the keys are pointers-to-Point, we want to order the map by the + // x-coordinates of the points and NOT by the addresses of the Points. This + // is done by using the PointCmp class's comparison method. + std::map mag( + {{points, 2}, {points + 1, 1}, {points + 2, 3}} + ); + + // Change each y-coordinate from 0 to the magnitude. + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; // Pointer to Node + cur->y = mag[cur]; // Could also have used cur->y = iter->second; + } + + // Update and print the magnitude of each node. + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << iter->second << '\\n'; + } + + // Repeat the above with the range-based for loop. + for (auto i : mag) + { + auto cur = i.first; + cur->y = i.second; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << mag[cur] << '\\n'; + // Note that in contrast to std::cout << iter->second << '\\n'; above, + // std::cout << i.second << '\\n'; will NOT print the updated magnitude. + // If auto &i : mag was used instead, it will print the updated magnitude. + } + } + +.SH Output: - Constant + The magnitude of (1, 1) is 1.41421 + The magnitude of (2, 2) is 2.82843 + The magnitude of (3, 3) is 4.24264 + The magnitude of (1, 1.41421) is 1.73205 + The magnitude of (2, 2.82843) is 3.4641 + The magnitude of (3, 4.24264) is 5.19615 .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::map::clear.3 b/man/std::map::clear.3 index 3ec69542b..4db7595fc 100644 --- a/man/std::map::clear.3 +++ b/man/std::map::clear.3 @@ -1,11 +1,14 @@ -.TH std::map::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::clear \- std::map::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterator remains valid. .SH Parameters @@ -15,18 +18,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::map& v) + { + std::cout << rem << "{ "; + for (const auto& [key, value] : v) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::map container{{1, 'x'}, {2, 'y'}, {3, 'z'}}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { [1]:x [2]:y [3]:z } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + LWG 224 C++98 the complexity was log(size()) + N, but N corrected to 'linear in + was not defined size()' .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::map::contains.3 b/man/std::map::contains.3 new file mode 100644 index 000000000..2069ce2d0 --- /dev/null +++ b/man/std::map::contains.3 @@ -0,0 +1,60 @@ +.TH std::map::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::contains \- std::map::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::map example{{1, 'a'}, {2, 'b'}}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::map::count.3 b/man/std::map::count.3 index 6e6fa544b..eb97459e2 100644 --- a/man/std::map::count.3 +++ b/man/std::map::count.3 @@ -1,15 +1,21 @@ -.TH std::map::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::count \- std::map::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP template< class K > \fB(2)\fP \fI(since C++14)\fP size_type count( const K& x ) const; - 1) Returns the number of elements with key key, which is either 1 or 0 since this - container does not allow duplicates + Returns the number of elements with key that compares equivalent to the specified + argument. + + 1) Returns the number of elements with key key. This is either 1 or 0 since this + container does not allow duplicates. 2) Returns the number of elements with key that compares equivalent to the value x. - These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -18,15 +24,32 @@ .SH Return value - Number of elements with key key, that is either 1 or 0 + Number of elements with key that compares equivalent to key or x, which, for + overload \fB(1)\fP, is either 1 or 0. .SH Complexity - Logarithmic in the size of the container. + Logarithmic in the size of the container plus linear in the number of elements + found. + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overload \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::map::emplace.3 b/man/std::map::emplace.3 index c4cd41568..0dc3b651d 100644 --- a/man/std::map::emplace.3 +++ b/man/std::map::emplace.3 @@ -1,15 +1,22 @@ -.TH std::map::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::emplace \- std::map::emplace + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - std::pair emplace( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + std::pair emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args, + if there is no element with the key in the container. - Inserts a new element into the container by constructing it in-place with the given - args. + The constructor of the new element (i.e. std::pair) is called with + exactly the same arguments as supplied to emplace, forwarded via + std::forward(args).... The element may be constructed even if there already is + an element with the key in the container, in which case the newly constructed + element will be destroyed immediately. Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element (i.e. - std::pair) is called with exactly the same arguments as supplied to - emplace, forwarded via std::forward(args).... + unnecessary copy or move operations. No iterators or references are invalidated. @@ -19,13 +26,14 @@ .SH Return value - Returns a pair consisting of a bool denoting whether the insertion took place and an - iterator to the inserted element, or the already-existing element if no insertion - happened. + A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -33,34 +41,38 @@ .SH Example - + // Run this code #include + #include #include - #include + int main() { std::map m; - - // uses pair's move constructor (overload 8) + + // uses pair's move constructor m.emplace(std::make_pair(std::string("a"), std::string("a"))); - - // uses pair's converting move constructor (overload 5) + + // uses pair's converting move constructor m.emplace(std::make_pair("b", "abcd")); - - // uses pair's template constructor (overload 3) + + // uses pair's template constructor m.emplace("d", "ddd"); - - // uses pair's piecewise constructor (overload 6) + + // emplace with duplicate key has no effect + m.emplace("d", "DDD"); + + // uses pair's piecewise constructor m.emplace(std::piecewise_construct, std::forward_as_tuple("c"), std::forward_as_tuple(10, 'c')); - - for (const auto &p : m) { + // an alternative is: m.try_emplace("c", 10, 'c'); + + for (const auto& p : m) std::cout << p.first << " => " << p.second << '\\n'; - } } .SH Output: @@ -73,6 +85,11 @@ .SH See also emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + try_emplace inserts in-place if the key does not exist, does nothing if the key + \fI(C++17)\fP exists + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::map::emplace_hint.3 b/man/std::map::emplace_hint.3 index a22661c89..7895df1b9 100644 --- a/man/std::map::emplace_hint.3 +++ b/man/std::map::emplace_hint.3 @@ -1,11 +1,13 @@ -.TH std::map::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::emplace_hint \- std::map::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container as close as possible to the position just + before hint. The constructor of the element type (value_type, that is, std::pair) is called with exactly the same arguments as supplied to the function, forwarded @@ -15,24 +17,127 @@ .SH Parameters - hint - iterator, used as a suggestion as to where to insert the new element + hint - iterator to the position before which the new element will be inserted args - arguments to forward to the constructor of the element .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element, or to the element that prevented the insertion. + +.SH Exceptions - If the insertion failed because the element already exists, returns an iterator to - the already existing element with the equivalent key. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Logarithmic in the size of the container in general, but amortized constant if the new element is inserted just before hint. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const int n_operations = 100'500'0; + + std::size_t map_emplace() + { + std::map map; + for (int i = 0; i < n_operations; ++i) + map.emplace(i, 'a'); + return map.size(); + } + + std::size_t map_emplace_hint() + { + std::map map; + auto it = map.begin(); + for (int i = 0; i < n_operations; ++i) + { + map.emplace_hint(it, i, 'b'); + it = map.end(); + } + return map.size(); + } + + std::size_t map_emplace_hint_wrong() + { + std::map map; + auto it = map.begin(); + for (int i = n_operations; i > 0; --i) + { + map.emplace_hint(it, i, 'c'); + it = map.end(); + } + return map.size(); + } + + std::size_t map_emplace_hint_corrected() + { + std::map map; + auto it = map.begin(); + for (int i = n_operations; i > 0; --i) + { + map.emplace_hint(it, i, 'd'); + it = map.begin(); + } + return map.size(); + } + + std::size_t map_emplace_hint_closest() + { + std::map map; + auto it = map.begin(); + for (int i = 0; i < n_operations; ++i) + it = map.emplace_hint(it, i, 'e'); + return map.size(); + } + + double time_it(std::function map_test, + std::string what = "", double ratio = 0.0) + { + const auto start = std::chrono::system_clock::now(); + const std::size_t map_size = map_test(); + const auto stop = std::chrono::system_clock::now(); + std::chrono::duration time = stop - start; + if (what.size() && map_size) + std::cout << std::setw(8) << time << " for " << what << " (ratio: " + << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\\n"; + return time.count(); + } + + int main() + { + std::cout << std::fixed << std::setprecision(2); + time_it(map_emplace); // cache warmup + const auto x = time_it(map_emplace, "plain emplace"); + time_it(map_emplace_hint, "emplace with correct hint", x); + time_it(map_emplace_hint_wrong, "emplace with wrong hint", x); + time_it(map_emplace_hint_corrected, "corrected emplace", x); + time_it(map_emplace_hint_closest, "emplace using returned iterator", x); + } + +.SH Possible output: + + 365.08ms for plain emplace (ratio: 1.00) + 96.54ms for emplace with correct hint (ratio: 3.78) + 409.40ms for emplace with wrong hint (ratio: 0.89) + 85.57ms for corrected emplace (ratio: 4.27) + 84.31ms for emplace using returned iterator (ratio: 4.33) + .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::map::empty.3 b/man/std::map::empty.3 index 0469c30c8..a129ac91d 100644 --- a/man/std::map::empty.3 +++ b/man/std::map::empty.3 @@ -1,6 +1,12 @@ -.TH std::map::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::empty \- std::map::empty + .SH Synopsis - bool empty() const; + bool empty() const; \fI(until C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +16,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,23 +24,24 @@ .SH Example - + The following code uses empty to check if a std::map contains any elements: - + // Run this code - #include #include + #include #include - + int main() { - std::map numbers; + std::map numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.emplace(42, 13); numbers.insert(std::make_pair(13317, 123)); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -49,10 +49,12 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::map::end,std::map::cend.3 b/man/std::map::end,std::map::cend.3 index d43b730c8..70a4f3072 100644 --- a/man/std::map::end,std::map::cend.3 +++ b/man/std::map::end,std::map::cend.3 @@ -1,10 +1,13 @@ -.TH std::map::end,std::map::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::end,std::map::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::end,std::map::cend \- std::map::end,std::map::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fB(1)\fP (noexcept since C++11) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the map. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +22,118 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::map num_map; + num_map[4] = 4.13; + num_map[9] = 9.24; + num_map[1] = 1.09; + // Calls num_map.begin() and num_map.end() + for (auto it = num_map.begin(); it != num_map.end(); ++it) + std::cout << it->first << ", " << it->second << '\\n'; + } + +.SH Output: + + 1, 1.09 + 4, 4.13 + 9, 9.24 + + Example using a custom comparison function + + +// Run this code + + #include + #include + #include + + struct Point { double x, y; }; + + // Compare the x-coordinates of two Point pointers. + struct PointCmp + { + bool operator()(const Point* lhs, const Point* rhs) const + { + return lhs->x < rhs->x; + } + }; + + int main() + { + // Note that although the x-coordinates are out of order, the + // map will be iterated through by increasing x-coordinates. + Point points[3] = {{2, 0}, {1, 0}, {3, 0}}; + + // mag is a map sending the address of node to its magnitude in the x-y plane. + // Although the keys are pointers-to-Point, we want to order the map by the + // x-coordinates of the points and NOT by the addresses of the Points. This + // is done by using the PointCmp class's comparison method. + std::map mag( + {{points, 2}, {points + 1, 1}, {points + 2, 3}} + ); + + // Change each y-coordinate from 0 to the magnitude. + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; // Pointer to Node + cur->y = mag[cur]; // Could also have used cur->y = iter->second; + } + + // Update and print the magnitude of each node. + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << iter->second << '\\n'; + } + + // Repeat the above with the range-based for loop. + for (auto i : mag) + { + auto cur = i.first; + cur->y = i.second; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << mag[cur] << '\\n'; + // Note that in contrast to std::cout << iter->second << '\\n'; above, + // std::cout << i.second << '\\n'; will NOT print the updated magnitude. + // If auto &i : mag was used instead, it will print the updated magnitude. + } + } + +.SH Output: + + The magnitude of (1, 1) is 1.41421 + The magnitude of (2, 2) is 2.82843 + The magnitude of (3, 3) is 4.24264 + The magnitude of (1, 1.41421) is 1.73205 + The magnitude of (2, 2.82843) is 3.4641 + The magnitude of (3, 4.24264) is 5.19615 + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::map::equal_range.3 b/man/std::map::equal_range.3 index bc1a64d47..ad994b86a 100644 --- a/man/std::map::equal_range.3 +++ b/man/std::map::equal_range.3 @@ -1,27 +1,27 @@ -.TH std::map::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::equal_range \- std::map::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fB(1)\fP - std::pair equal_range( const Key& \fB(2)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP + std::pair equal_range( const Key& \fB(2)\fP key ) const; template< class K > \fB(3)\fP \fI(since C++14)\fP - std::pair equal_range( const K& x ); + std::pair equal_range( const K& x ); template< class K > - std::pair equal_range( const K& x ) \fB(4)\fP \fI(since C++14)\fP - const; + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++14)\fP + ) const; Returns a range containing all elements with the given key in the container. The range is defined by two iterators, one pointing to the first element that is not - less than key and another pointing to the first element greater than key. The first - iterator may be alternatively obtained with lower_bound(), the second - with - upper_bound(). - - 1-2) Compares the keys to key. - 3,4) Compares the keys to the value x. These templates only participate in overload - resolution if the type Compare::is_transparent exists. They allow calling this - function without constructing an instance of Key. + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). - This section is incomplete - Reason: explain better + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. .SH Parameters @@ -42,21 +42,82 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + const std::map m + { + {0, "zero"}, + {1, "one"}, + {2, "two"} + }; + + auto p = m.equal_range(1); + for (auto& q = p.first; q != p.second; ++q) + std::cout << "m[" << q->first << "] = " << q->second << '\\n'; + + if (p.second == m.find(2)) + std::cout << "end of equal_range (p.second) is one-past p.first\\n"; + else + std::cout << "unexpected; p.second expected to be one-past p.first\\n"; + + auto pp = m.equal_range(-1); + if (pp.first == m.begin()) + std::cout << "pp.first is iterator to first not-less than -1\\n"; + else + std::cout << "unexpected pp.first\\n"; + + if (pp.second == m.begin()) + std::cout << "pp.second is iterator to first element greater-than -1\\n"; + else + std::cout << "unexpected pp.second\\n"; + + auto ppp = m.equal_range(3); + if (ppp.first == m.end()) + std::cout << "ppp.first is iterator to first not-less than 3\\n"; + else + std::cout << "unexpected ppp.first\\n"; + + if (ppp.second == m.end()) + std::cout << "ppp.second is iterator to first element greater-than 3\\n"; + else + std::cout << "unexpected ppp.second\\n"; + } + +.SH Output: + + m[1] = one + end of equal_range (p.second) is one-past p.first + pp.first is iterator to first not-less than -1 + pp.second is iterator to first element greater-than -1 + ppp.first is iterator to first not-less than 3 + ppp.second is iterator to first element greater-than 3 .SH See also find finds element with specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - - Categories: - - * Todo with reason - * Todo no example + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::map::erase.3 b/man/std::map::erase.3 index 689ce26ec..42a4f2342 100644 --- a/man/std::map::erase.3 +++ b/man/std::map::erase.3 @@ -1,49 +1,120 @@ -.TH std::map::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::erase \- std::map::erase + .SH Synopsis - void erase( iterator pos ); \fI(until C++11)\fP - iterator erase( const_iterator pos ); \fI(since C++11)\fP - void erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP - iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP - const_iterator last ); - size_type erase( const key_type& key ); \fB(3)\fP + iterator erase( iterator pos ); \fB(1)\fP + iterator erase( const_iterator pos ); \fB(2)\fP \fI(since C++11)\fP + iterator erase( iterator first, iterator last ); \fI(until C++11)\fP + iterator erase( const_iterator first, const_iterator \fI(since C++11)\fP + last ); \fB(3)\fP + size_type erase( const Key& key ); \fB(4)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); Removes specified elements from the container. - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes the element (if one exists) with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed (0 or 1). + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. .SH Complexity Given an instance c of map: - 1) Amortized constant - 2) log(c.size()) + std::distance(first, last) - 3) log(c.size()) + c.count(k) + 1,2) Amortized constant + 3) log(c.size()) + std::distance(first, last) + 4) log(c.size()) + c.count(key) + 5) log(c.size()) + c.count(x) + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::map c = + { + {1, "one"}, {2, "two"}, {3, "three"}, + {4, "four"}, {5, "five"}, {6, "six"} + }; + + // erase all odd numbers from c + for (auto it = c.begin(); it != c.end();) + { + if (it->first % 2 != 0) + it = c.erase(it); + else + ++it; + } + + for (auto& p : c) + std::cout << p.second << ' '; + std::cout << '\\n'; + } + +.SH Output: + + two four six + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the return type of overloads \fB(1)\fP and \fB(3)\fP + LWG 130 C++98 was void (it is not corrected to iterator + consistent with the erase() requirement + on sequence containers) + LWG 2059 C++11 replacing overload \fB(1)\fP with overload \fB(2)\fP added overload (1) back + introduced new ambiguity .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::map::extract.3 b/man/std::map::extract.3 new file mode 100644 index 000000000..091061a9d --- /dev/null +++ b/man/std::map::extract.3 @@ -0,0 +1,120 @@ +.TH std::map::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::extract \- std::map::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains that element from the container and returns a node handle that owns it. + Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if the + qualified-id Compare::is_transparent is valid and denotes a type, and neither + iterator nor const_iterator is implicitly convertible from K. It allows calling this + function without constructing an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed (rebalancing may occur, as with erase()). + + Extracting a node invalidates only the iterators to the extracted element. Pointers + and references to the extracted element remain valid, but cannot be used while + element is owned by a node handle: they become usable if the element is inserted + into a container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Compare object. + +.SH Complexity + + 1) Amortized constant. + 2,3) log(size()) + +.SH Notes + + extract is the only way to change a key of a map element without reallocation: + + std::map m{{1, "mango"}, {2, "papaya"}, {3, "guava"}}; + auto nh = m.extract\fB(2)\fP; + nh.key() = 4; + m.insert(std::move(nh)); + // m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}} + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto [k, v] : data) + std::cout << ' ' << k << '(' << v << ')'; + + std::cout << '\\n'; + } + + int main() + { + std::map cont{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.key() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Output: + + Start: 1(a) 2(b) 3(c) + After extract and before insert: 2(b) 3(c) + End: 2(b) 3(c) 4(a) + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::map::find.3 b/man/std::map::find.3 index a7f75670e..65fc27638 100644 --- a/man/std::map::find.3 +++ b/man/std::map::find.3 @@ -1,15 +1,20 @@ -.TH std::map::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::find \- std::map::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP - template< class K > iterator find( const K& x ); \fB(3)\fP \fI(since C++14)\fP - template< class K > const_iterator find( const K& x ) const; \fB(4)\fP \fI(since C++14)\fP + iterator find( const Key& key ); \fB(1)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator find( const K& x ) const; 1,2) Finds an element with key equivalent to key. - 3,4) Finds an element with key that compares equivalent to the value x. These - templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -18,78 +23,88 @@ .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + .SH Example - + // Run this code #include #include - #include - + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + int main() { - std::map map_ex; - map_ex.insert({{1,'a'},{2,'b'}}); - std::map::const_iterator search = map_ex.find(1); - if(search != map_ex.end()) { - std::cout << "Found " << search->first << " " << search->second << "\\n"; + // Simple comparison demo. + std::map example{{1,'a'}, {2,'b'}}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << search->first << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::map> example2{{{1, {}}, 'a'}, {{2, {}}, 'b'}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Obtaining const iterators. + // Compiler decides whether to return iterator of (non) const type by way of + // accessing map; to prevent intentional modification, one of the simplest + // options is to access the map via a constant reference. + const auto& example2ref = example2; + if (auto search = example2ref.find(lk); search != example2.end()) + { + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + // search->second = 'c'; // error: assignment of member + // 'std::pair::second' + // in read-only object } - else { - std::cout << "Not found" << std::endl; - } - return 0; } .SH Output: - Found 1 a + Found 2 b + Found 2 b + Found 2 b .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - -.SH Example - - Demonstrates the risk of accessing non-existing elements via operator []. - - -// Run this code - - #include - #include - #include - - int main() - { - std::map my_map; - my_map["x"] = 11; - my_map["y"] = 23; - - auto it = my_map.find("x"); - if (it != my_map.end()) std::cout << "x: " << it->second << "\\n"; - - it = my_map.find("z"); - if (it != my_map.end()) std::cout << "z1: " << it->second << "\\n"; - - // Accessing a non-existing element creates it - if (my_map["z"] == 42) std::cout << "Oha!\\n"; - - it = my_map.find("z"); - if (it != my_map.end()) std::cout << "z2: " << it->second << "\\n"; - } - -.SH Output: - - x: 11 - z2: 0 + \fI(public member function)\fP diff --git a/man/std::map::get_allocator.3 b/man/std::map::get_allocator.3 index 375ad5a8b..a417d0bac 100644 --- a/man/std::map::get_allocator.3 +++ b/man/std::map::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::map::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::get_allocator \- std::map::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) Returns the allocator associated with the container. diff --git a/man/std::map::insert.3 b/man/std::map::insert.3 index 2249906a7..f513db40a 100644 --- a/man/std::map::insert.3 +++ b/man/std::map::insert.3 @@ -1,79 +1,255 @@ -.TH std::map::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::insert \- std::map::insert + .SH Synopsis - std::pair insert( const value_type& \fB(1)\fP + std::pair insert( const value_type& \fB(1)\fP value ); template< class P > \fB(2)\fP \fI(since C++11)\fP - std::pair insert( P&& value ); - iterator insert( iterator hint, const value_type& \fI(until C++11)\fP + std::pair insert( P&& value ); + std::pair insert( value_type&& value \fB(3)\fP \fI(since C++17)\fP + ); + iterator insert( iterator pos, const value_type& \fI(until C++11)\fP value ); - iterator insert( const_iterator hint, const \fI(since C++11)\fP + iterator insert( const_iterator pos, const \fI(since C++11)\fP value_type& value ); - template< class P > \fB(3)\fP \fB(4)\fP \fI(since C++11)\fP - iterator insert( const_iterator hint, P&& value ); - template< class InputIt > \fB(5)\fP + template< class P > \fB(5)\fP \fI(since C++11)\fP + iterator insert( const_iterator pos, P&& value ); + iterator insert( const_iterator pos, value_type&& \fB(6)\fP \fI(since C++17)\fP + value ); \fB(4)\fP + template< class InputIt > \fB(7)\fP void insert( InputIt first, InputIt last ); - void insert( std::initializer_list ilist \fB(6)\fP \fI(since C++11)\fP + void insert( std::initializer_list ilist \fB(8)\fP \fI(since C++11)\fP + ); + insert_return_type insert( node_type&& nh ); \fB(9)\fP \fI(since C++17)\fP + iterator insert( const_iterator pos, node_type&& nh \fB(10)\fP \fI(since C++17)\fP ); Inserts element(s) into the container, if the container doesn't already contain an element with an equivalent key. - 1-2) Inserts value. The overload \fB(2)\fP is equivalent to - emplace(std::forward

(value)) and only participates in overload resolution if - std::is_constructible::value == true. - 3-4) Inserts value in the position as close as possible, just prior\fI(since C++11)\fP, to - hint. The overload \fB(4)\fP is equivalent to emplace_hint(hint, std::forward

(value)) - and only participates in overload resolution if std::is_constructible::value == true. - 5) Inserts elements from range [first, last). - 6) Inserts elements from initializer list ilist. + 1-3) Inserts value. + Overload \fB(2)\fP is equivalent to emplace(std::forward

(value)) and only participates + in overload resolution if std::is_constructible::value == true. + 4-6) Inserts value in the position as close as possible to the position just prior + to pos. + Overload \fB(5)\fP is equivalent to emplace_hint(hint, std::forward

(value)) and only + participates in overload resolution if std::is_constructible::value + == true. + 7) Inserts elements from range [first, last). If multiple elements in the range have + keys that compare equivalent, it is unspecified which element is inserted (pending + LWG2844). + 8) Inserts elements from initializer list ilist. If multiple elements in the range + have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). + 9) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container , if the container doesn't already contain an element with + a key equivalent to nh.key(). The behavior is undefined if nh is not empty and + get_allocator() != nh.get_allocator(). + 10) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, if the container + doesn't already contain an element with a key equivalent to nh.key(), and returns + the iterator pointing to the element with key equivalent to nh.key()(regardless of + whether the insert succeeded or failed). If the insertion succeeds, nh is moved + from, otherwise it retains ownership of the element. The element is inserted as + close as possible to the position just prior to pos. The behavior is undefined if nh + is not empty and get_allocator() != nh.get_allocator(). No iterators or references are invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters - hint - iterator, used as a suggestion as to where to insert the content + pos - iterator to the position before which the new element will be inserted value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-2) Returns a pair consisting of an iterator to the inserted element (or to the - element that prevented the insertion) and a bool denoting whether the insertion took - place. - 3-4) Returns an iterator to the inserted element, or to the element that prevented - the insertion. - 5-6) \fI(none)\fP + 1-3) A pair consisting of an iterator to the inserted element (or to the element + that prevented the insertion) and a bool value set to true if and only if the + insertion took place. + 4-6) An iterator to the inserted element, or to the element that prevented the + insertion. + 7,8) \fI(none)\fP + 9) An object of insert_return_type with the members initialized as follows: + * If nh is empty, inserted is false, position is end(), and node is empty. + * Otherwise if the insertion took place, inserted is true, position points to the + inserted element, and node is empty. + * If the insertion failed, inserted is false, node has the previous value of nh, + and position points to an element with a key equivalent to nh.key(). + 10) End iterator if nh was empty, iterator pointing to the inserted element if + insertion took place, and iterator pointing to an element with a key equivalent to + nh.key() if it failed. .SH Exceptions - 1-4) If an exception is thrown by any operation, the insertion has no effect. + 1-6) If an exception is thrown by any operation, the insertion has no effect. This section is incomplete - Reason: cases 5-6 + Reason: cases 7-10 .SH Complexity - 1-2) Logarithmic in the size of the container, O(log(size())). - - 3-4) Amortized constant if the insertion happens in the position just \fI(until C++11)\fP - after the hint, logarithmic in the size of the container otherwise. - 3-4) Amortized constant if the insertion happens in the position just \fI(since C++11)\fP - before the hint, logarithmic in the size of the container otherwise. - - 5-6) O(N*log(size() + N)), where N is the number of elements to insert. + 1-3) Logarithmic in the size of the container, O(log(size())). + 4-6) Amortized constant if the insertion happens in the position just + after + \fI(until C++11)\fP + before + \fI(since C++11)\fP pos, logarithmic in the size of the container otherwise. + 7,8) O(N·log(size() + N)), where N is the number of elements to insert. + 9) Logarithmic in the size of the container, O(log(size())). + 10) Amortized constant if the insertion happens in the position just before pos, + logarithmic in the size of the container otherwise. + +.SH Notes + + The hinted insert (4-6) does not return a boolean in order to be + signature-compatible with positional insert on sequential containers, such as + std::vector::insert. This makes it possible to create generic inserters such as + std::inserter. One way to check success of a hinted insert is to compare size() + before and after. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + using namespace std::literals; + + template + void print_insertion_status(It it, bool success) + { + std::cout << "Insertion of " << it->first + << (success ? " succeeded\\n" : " failed\\n"); + } + + int main() + { + std::map heights; + + // Overload 3: insert from rvalue reference + const auto [it_hinata, success] = heights.insert({"Hinata"s, 162.8}); + print_insertion_status(it_hinata, success); + + { + // Overload 1: insert from lvalue reference + const auto [it, success2] = heights.insert(*it_hinata); + print_insertion_status(it, success2); + } + { + // Overload 2: insert via forwarding to emplace + const auto [it, success] = heights.insert(std::pair{"Kageyama", 180.6}); + print_insertion_status(it, success); + } + { + // Overload 6: insert from rvalue reference with positional hint + const std::size_t n = std::size(heights); + const auto it = heights.insert(it_hinata, {"Azumane"s, 184.7}); + print_insertion_status(it, std::size(heights) != n); + } + { + // Overload 4: insert from lvalue reference with positional hint + const std::size_t n = std::size(heights); + const auto it = heights.insert(it_hinata, *it_hinata); + print_insertion_status(it, std::size(heights) != n); + } + { + // Overload 5: insert via forwarding to emplace with positional hint + const std::size_t n = std::size(heights); + const auto it = heights.insert(it_hinata, std::pair{"Tsukishima", 188.3}); + print_insertion_status(it, std::size(heights) != n); + } + + auto node_hinata = heights.extract(it_hinata); + std::map heights2; + + // Overload 7: insert from iterator range + heights2.insert(std::begin(heights), std::end(heights)); + + // Overload 8: insert from initializer_list + heights2.insert({{"Kozume"s, 169.2}, {"Kuroo", 187.7}}); + + // Overload 9: insert node + const auto status = heights2.insert(std::move(node_hinata)); + print_insertion_status(status.position, status.inserted); + + node_hinata = heights2.extract(status.position); + { + // Overload 10: insert node with positional hint + const std::size_t n = std::size(heights2); + const auto it = heights2.insert(std::begin(heights2), std::move(node_hinata)); + print_insertion_status(it, std::size(heights2) != n); + } + + // Print resulting map + std::cout << std::left << '\\n'; + for (const auto& [name, height] : heights2) + std::cout << std::setw(10) << name << " | " << height << "cm\\n"; + } + +.SH Output: + + Insertion of Hinata succeeded + Insertion of Hinata failed + Insertion of Kageyama succeeded + Insertion of Azumane succeeded + Insertion of Hinata failed + Insertion of Tsukishima succeeded + Insertion of Hinata succeeded + Insertion of Hinata succeeded + + Azumane | 184.7cm + Hinata | 162.8cm + Kageyama | 180.6cm + Kozume | 169.2cm + Kuroo | 187.7cm + Tsukishima | 188.3cm + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the insertion is required + pos was just a hint, it could be to + LWG 233 C++98 totally ignored be as close as possible to + the + position just prior to pos + the complexity of overload \fB(7)\fP was removed the linear + LWG 264 C++98 required to be linear if requirement + the range [first, last) is sorted in this special case + according to Compare + in the return value of overload \fB(1)\fP, + LWG 316 C++98 it was not specified success is + which bool value indicates a indicated by true + successful insertion + LWG 2005 C++11 overloads (2,5) were poorly described improved the description .SH See also - emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(C++11)\fP \fI(public member function)\fP + insert_or_assign inserts an element or assigns to the current element if the key + \fI(C++17)\fP already exists + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP .SH Category: - * Todo with reason diff --git a/man/std::map::insert_or_assign.3 b/man/std::map::insert_or_assign.3 new file mode 100644 index 000000000..4bcb3c8e2 --- /dev/null +++ b/man/std::map::insert_or_assign.3 @@ -0,0 +1,132 @@ +.TH std::map::insert_or_assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::insert_or_assign \- std::map::insert_or_assign + +.SH Synopsis + template< class M > + std::pair insert_or_assign( const Key& k, M&& obj \fB(1)\fP \fI(since C++17)\fP + ); + template< class M > \fB(2)\fP \fI(since C++17)\fP + std::pair insert_or_assign( Key&& k, M&& obj ); + template< class K, class M > \fB(3)\fP (since C++26) + std::pair insert_or_assign( K&& k, M&& obj ); + template< class M > + iterator insert_or_assign( const_iterator hint, const Key& k, M&& \fB(4)\fP \fI(since C++17)\fP + obj ); + template< class M > + iterator insert_or_assign( const_iterator hint, Key&& k, M&& obj \fB(5)\fP \fI(since C++17)\fP + ); + template< class K, class M > \fB(6)\fP (since C++26) + iterator insert_or_assign( const_iterator hint, K&& k, M&& obj ); + + 1,4) If a key equivalent to k already exists in the container, assigns + std::forward(obj) to the mapped_type corresponding to the key k. If the key does + not exist, inserts the new value as if by insert, constructing it from value_type(k, + std::forward(obj)). + 2,5) Same as (1,4), except the mapped value is constructed from + value_type(std::move(k), std::forward(obj)). + 3,6) If a key equivalent to k already exists in the container, assigns + std::forward(obj) to the mapped_type corresponding to the key k. If the key does + not exist, constructs an object u of value_type with std::forward(k), + std::forward(obj)), then inserts u into *this. If equal_range(u.first) == + equal_range(k) is false, the behavior is undefined. The value_type must be + EmplaceConstructible into map from std::forward(k), std::forward(obj). This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + + The behavior is undefined + \fI(until C++20)\fP + The program is ill-formed + \fI(since C++20)\fP if std::is_assignable_v is false. + + No iterators or references are invalidated. + +.SH Parameters + + k - the key used both to look up and to insert if not found + hint - iterator to the position before which the new element will be inserted + obj - the value to insert or assign + +.SH Return value + + 1-3) The bool component is true if the insertion took place and false if the + assignment took place. The iterator component is pointing at the element that was + inserted or updated. + 4-6) Iterator pointing at the element that was inserted or updated. + +.SH Complexity + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Notes + + insert_or_assign returns more information than operator[] and does not require + default-constructibility of the mapped type. + + Feature-test macro Value Std Feature + __cpp_lib_map_try_emplace 201411L \fI(C++17)\fP std::map::try_emplace, + std::map::insert_or_assign + Heterogeneous overloads + for the remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered and + unordered associative + containers. Overloads \fB(3)\fP + and \fB(6)\fP. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_node(const auto& node) + { + std::cout << '[' << node.first << "] = " << node.second << '\\n'; + } + + void print_result(auto const& pair) + { + std::cout << (pair.second ? "inserted: " : "assigned: "); + print_node(*pair.first); + } + + int main() + { + std::map myMap; + + print_result(myMap.insert_or_assign("a", "apple")); + print_result(myMap.insert_or_assign("b", "banana")); + print_result(myMap.insert_or_assign("c", "cherry")); + print_result(myMap.insert_or_assign("c", "clementine")); + + for (const auto& node : myMap) + print_node(node); + } + +.SH Output: + + inserted: [a] = apple + inserted: [b] = banana + inserted: [c] = cherry + assigned: [c] = clementine + [a] = apple + [b] = banana + [c] = clementine + +.SH See also + + operator[] access or insert specified element + \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::map::insert_range.3 b/man/std::map::insert_range.3 new file mode 100644 index 000000000..436f70ba9 --- /dev/null +++ b/man/std::map::insert_range.3 @@ -0,0 +1,76 @@ +.TH std::map::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::insert_range \- std::map::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg if and only if there is no element + with key equivalent to the key of that element in *this. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + No iterators or references are invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose + elements are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into map from *ranges::begin(rg). Otherwise, + the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N·log(a.size() + N), where N is ranges::distance(rg). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto, auto const& container) + { + for (const auto& [key, value] : container) + std::cout << '{' << key << ',' << value << '}' << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::map{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}}; + const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + {-2,-22} {-1,-11} {1,11} {2,22} {3,33} {4,44} + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::map::key_comp.3 b/man/std::map::key_comp.3 index dbbb5e1a4..0e0b949c0 100644 --- a/man/std::map::key_comp.3 +++ b/man/std::map::key_comp.3 @@ -1,4 +1,7 @@ -.TH std::map::key_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::key_comp \- std::map::key_comp + .SH Synopsis key_compare key_comp() const; @@ -17,7 +20,57 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::map cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.key_comp(); + + for (const auto it : cont) + { + const bool before = comp_func(it.first, 100); + const bool after = comp_func(100, it.first); + + std::cout << "Key (" << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + .SH See also value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::map::lower_bound.3 b/man/std::map::lower_bound.3 index 064f45069..bfcd3427c 100644 --- a/man/std::map::lower_bound.3 +++ b/man/std::map::lower_bound.3 @@ -1,17 +1,21 @@ -.TH std::map::lower_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::lower_bound \- std::map::lower_bound + .SH Synopsis iterator lower_bound( const Key& key ); \fB(1)\fP - const_iterator lower_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP - iterator lower_bound(const K& x); - template< class K > \fB(2)\fP \fI(since C++14)\fP - const_iterator lower_bound(const K& x) const; - - 1) Returns an iterator pointing to the first element that is not less than key. - 2) Returns an iterator pointing to the first element that compares not less to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. .SH Parameters @@ -27,9 +31,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::map::map.3 b/man/std::map::map.3 index 4d0ecc63f..8870f536b 100644 --- a/man/std::map::map.3 +++ b/man/std::map::map.3 @@ -1,58 +1,85 @@ -.TH std::map::map 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::map \- std::map::map + .SH Synopsis - explicit map( const Compare& comp = Compare(), (until - const Allocator& alloc = Allocator() C++14) - ); - map : map( Compare() ) {} - - explicit map( const Compare& comp, (since - C++14) - const Allocator& alloc = Allocator() - ); - explicit map( const Allocator& alloc ); \fB(1)\fP (since - C++11) + map(); \fI(until C++11)\fP + map() \fI(since C++11)\fP + : map(Compare()) {} + explicit map( const Compare& comp, \fB(2)\fP + const Allocator& alloc = Allocator() ); + explicit map( const Allocator& alloc ); \fB(3)\fP \fI(since C++11)\fP template< class InputIt > - map( InputIt first, InputIt last, + map( InputIt first, InputIt last, \fB(4)\fP const Compare& comp = Compare(), const Allocator& alloc = Allocator() ); - template< class InputIt > \fB(1)\fP - (since - map( InputIt first, InputIt last, C++14) + template< class InputIt > + + map( InputIt first, InputIt last, \fB(5)\fP \fI(since C++14)\fP + const Allocator& alloc ) + + : map(first, last, Compare(), alloc) {} + map( const map& other ); \fB(6)\fP + map( const map& other, const Allocator& alloc ); \fB(7)\fP \fI(since C++11)\fP + map( map&& other ); \fB(8)\fP \fI(since C++11)\fP + map( map&& other, const Allocator& alloc ); \fB(9)\fP \fI(since C++11)\fP + map( std::initializer_list init, \fB(1)\fP + + const Compare& comp = Compare(), \fB(10)\fP \fI(since C++11)\fP const Allocator& alloc = Allocator() ); - map( const map& other ); \fB(3)\fP - map( const map& other, const Allocator& alloc ); \fB(2)\fP \fB(3)\fP (since - C++11) - map( map&& other ); \fB(4)\fP (since - C++11) - map( map&& other, const Allocator& alloc ); \fB(4)\fP (since - C++11) map( std::initializer_list init, - (since - const Compare& comp = Compare(), C++11) - \fB(5)\fP + + const Allocator& alloc ) \fB(11)\fP \fI(since C++14)\fP + + : map(init, Compare(), alloc) {} + template< container-compatible-range R > + + map( std::from_range_t, R&& rg, \fB(12)\fP (since C++23) + const Compare& comp = Compare(), + const Allocator& alloc = Allocator() ); - map( std::initializer_list init, (since - const Allocator& alloc = Allocator() ); C++14) + template< container-compatible-range R > + + map( std::from_range_t, R&& rg, + const Allocator& alloc ) \fB(13)\fP (since C++23) + + : map(std::from_range, std::forward(rg), Compare(), + alloc) {} Constructs new container from a variety of data sources and optionally using user supplied allocator alloc or comparison function object comp. - 1) Default constructor. Constructs empty container. + 1-3) Constructs an empty container. + 4,5) Constructs the container with the contents of the range [first, last). If + multiple elements in the range have keys that compare equivalent, it is unspecified + which element is inserted (pending LWG2844). + If [first, last) is not a valid range, the behavior is undefined. + 6,7) Copy constructor. Constructs the container with the copy of the contents of + other. - 2) Constructs the container with the contents of the range [first, last). + If alloc is not provided, allocator is obtained by calling (since + std::allocator_traits:: C++11) + select_on_container_copy_construction(other.get_allocator()). + During class template argument deduction, only the first argument contributes (since + to the deduction of the container's Allocator template parameter. C++23) - 3) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). + 8,9) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. - 4) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. - 5) Constructs the container with the contents of the initializer list init. + 10,11) Initializer-list constructor. Constructs the container with the contents of + the initializer list init.If multiple elements in the range have keys that compare + equivalent, it is unspecified which element is inserted (pending LWG2844). + 12,13) Constructs the container with the contents of rg. If multiple elements in the + range have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). .SH Parameters @@ -62,9 +89,11 @@ other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - Compare must meet the requirements of Compare. - @@ -72,163 +101,184 @@ .SH Complexity - 1) Constant + 1-3) Constant. + 4,5) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + std::distance(first, last) in general, linear in \\(\\scriptsize N\\)N if [first, last) + is already sorted by value_comp(). + 6,7) Linear in size of other. + 8,9) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 10,11) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + init.size() in general, linear in \\(\\scriptsize N\\)N if init is already sorted by + value_comp(). + 12,13) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + ranges::distance(rg) in general, linear in \\(\\scriptsize N\\)N if rg is already + sorted by value_comp(). + +.SH Exceptions - 2) N log(N) where N = std::distance(first, last) in general, linear in N if the - range is already sorted by value_comp(). + Calls to Allocator::allocate may throw. - 3) Linear in size of other +.SH Notes - 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + After container move construction (overload (8,9)), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. - 5) N log(N) where N = init.size()) in general, linear in N if init is already sorted - by value_comp(). + Although not formally required until C++23, some implementations has already put the + template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (12,13) .SH Example - + // Run this code + #include #include - #include #include - - //declare printers for maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - - int main() + #include + + template + std::ostream& operator<<(std::ostream& os, std::map const& map) { - typedef std::string Key; - typedef int Mapped; - - // (1) Default constructor - std::map map; - map["something"] = 69; - map["anything"] = 199; - map["that thing"] = 50; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (2) Iterator constructor - std::map iter(map.find("anything"), map.end()); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "iter = " << iter << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (3) Copy constructor - std::map copy(map); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "copy = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (4) Move constructor - std::map moved(std::move(map)); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "moved = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (5) Initializer list constructor - const std::map init { - {"this", 100}, - {"can", 100}, - {"be", 100}, - {"const", 100}, - }; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "init = " << init << '\\n'; - } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ':' << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A specialization for Key strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":" << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; + os << "{ "; + for (auto comma{map.size()}; auto const& p : map) + os << '\\'' << p.first << "' is " << p.second << (--comma ? ", " : " "); + return os << "}\\n"; } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A specialization for Key and Mapped strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; + + struct Point + { + double x, y; + + friend std::ostream& operator<<(std::ostream& os, Point pt) + { + return os << '(' << pt.x << ", " << pt.y << ')'; + } + }; + + struct PointCmp + { + bool operator()(const Point& lhs, const Point& rhs) const + { + return lhs.x < rhs.x; // NB: y is intentionally ignored + } + }; + + int main() + { + // (1) Default constructor + std::map map1; + map1["something"] = 69; + map1["anything"] = 199; + map1["that thing"] = 50; + std::cout << "map1 = " << map1; + + // (4) Range constructor + std::map iter(map1.find("anything"), map1.end()); + std::cout << "\\niter = " << iter; + std::cout << "map1 = " << map1; + + // (6) Copy constructor + std::map copied(map1); + std::cout << "\\ncopied = " << copied; + std::cout << "map1 = " << map1; + + // (8) Move constructor + std::map moved{std::move(map1)}; + std::cout << "\\nmoved = " << moved; + std::cout << "map1 = " << map1; + + // (10) Initializer list constructor + const std::map init + { + {"this", 100}, + {"can", 100}, + {"be", 100}, + {"const", 100} + }; + std::cout << "\\ninit = " << init; + + std::cout << "\\nCustom Key class option 1:\\n"; + // Use a comparison struct + std::map mag = + { + {{5, -12}, 13}, + {{3, 4}, 5}, + {{-8, -15}, 17} + }; + std::cout << "mag = " << mag << '\\n'; + + std::cout << "Custom Key class option 2:\\n"; + // Use a comparison lambda + // This lambda sorts points according to their magnitudes, where + // these magnitudes are taken from the local variable mag. + auto cmpLambda = [&mag](const Point& lhs, const Point& rhs) + { + return mag[lhs] < mag[rhs]; + }; + + // You could also use a lambda that is not dependent on local variables, like this: + // auto cmpLambda = [](const Point& lhs, const Point& rhs){ return lhs.y < rhs.y; }; + std::map magy(cmpLambda); + + // Various ways of inserting elements: + magy.insert(std::pair({5, -12}, 13)); + magy.insert({{3, 4}, 5}); + magy.insert({Point{-8.0, -15.0}, 17}); + std::cout << "magy = " << magy << '\\n'; + + std::cout << "Construction from a range:\\n"; + using PS = std::pair; + const auto rg = {PS{"one", 1}, {"one", 101}, {"two", 2}, {"three", 3}}; + #if __cpp_lib_containers_ranges + std::map nums(std::from_range, rg); // overload (12) + #else + std::map nums(rg.begin(), rg.end()); // fallback to (4) + #endif + std::cout << "nums = " << nums << '\\n'; } .SH Output: - -------------------------------------------------------------------------------- - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - iter = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - copy = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - moved = {"anything":199, "something":69, "that thing":50} - map = {} - -------------------------------------------------------------------------------- - init = {"be":100, "can":100, "const":100, "this":100} - - This section is incomplete - Reason: cleanup/shorten this example + map1 = { 'anything' is 199, 'something' is 69, 'that thing' is 50 } -.SH See also + iter = { 'anything' is 199, 'something' is 69, 'that thing' is 50 } + map1 = { 'anything' is 199, 'something' is 69, 'that thing' is 50 } - operator= assigns values to the container - \fI(public member function)\fP + copied = { 'anything' is 199, 'something' is 69, 'that thing' is 50 } + map1 = { 'anything' is 199, 'something' is 69, 'that thing' is 50 } + + moved = { 'anything' is 199, 'something' is 69, 'that thing' is 50 } + map1 = { } + + init = { 'be' is 100, 'can' is 100, 'const' is 100, 'this' is 100 } + + Custom Key class option 1: + mag = { '(-8, -15)' is 17, '(3, 4)' is 5, '(5, -12)' is 13 } + + Custom Key class option 2: + magy = { '(3, 4)' is 5, '(5, -12)' is 13, '(-8, -15)' is 17 } -.SH Category: + Construction from a range: + nums = { 'one' is 1, 'three' is 3, 'two' is 2 } - * Todo with reason + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2076 C++11 overload \fB(4)\fP conditionally required Keyand T not required + to be CopyInsertable into *this + LWG 2193 C++11 the default constructor was explicit made non-explicit + +.SH See also + + operator= assigns values to the container + \fI(public member function)\fP diff --git a/man/std::map::max_size.3 b/man/std::map::max_size.3 index 50bb29d77..d86974635 100644 --- a/man/std::map::max_size.3 +++ b/man/std::map::max_size.3 @@ -1,6 +1,9 @@ -.TH std::map::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::max_size \- std::map::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,25 +17,45 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::map p; + std::map q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 461,168,601,842,738,790 = 0x666,666,666,666,666 + q.max_size() = 384,307,168,202,282,325 = 0x555,555,555,555,555 + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::map::merge.3 b/man/std::map::merge.3 new file mode 100644 index 000000000..929ef7ba1 --- /dev/null +++ b/man/std::map::merge.3 @@ -0,0 +1,82 @@ +.TH std::map::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::merge \- std::map::merge + +.SH Synopsis + template< class C2 > \fB(1)\fP \fI(since C++17)\fP + void merge( std::map& source ); + template< class C2 > \fB(2)\fP \fI(since C++17)\fP + void merge( std::map&& source ); + template< class C2 > \fB(3)\fP \fI(since C++17)\fP + void merge( std::multimap& source ); + template< class C2 > \fB(4)\fP \fI(since C++17)\fP + void merge( std::multimap&& source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the comparison object of *this. If there is an element in *this with key equivalent + to the key of an element from source, then that element is not extracted from + source. No elements are copied or moved, only the internal pointers of the container + nodes are repointed. All pointers and references to the transferred elements remain + valid, but now refer into *this, not into source. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Does not throw unless comparison throws. + +.SH Complexity + + N * log(size() + N)), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::map ma{{1, "apple"}, {5, "pear"}, {10, "banana"}}; + std::map mb{{2, "zorro"}, {4, "batman"}, {5, "X"}, {8, "alpaca"}}; + std::map u; + u.merge(ma); + std::cout << "ma.size(): " << ma.size() << '\\n'; + u.merge(mb); + std::cout << "mb.size(): " << mb.size() << '\\n'; + std::cout << "mb.at(5): " << mb.at(5) << '\\n'; + for (auto const& kv : u) + std::cout << kv.first << ", " << kv.second << '\\n'; + } + +.SH Output: + + ma.size(): 0 + mb.size(): 1 + mb.at\fB(5)\fP: X + 1, apple + 2, zorro + 4, batman + 5, pear + 8, alpaca + 10, banana + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::map::operator=.3 b/man/std::map::operator=.3 index faf421efb..3f30612b5 100644 --- a/man/std::map::operator=.3 +++ b/man/std::map::operator=.3 @@ -1,27 +1,39 @@ -.TH std::map::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::operator= \- std::map::operator= + .SH Synopsis map& operator=( const map& other ); \fB(1)\fP - map& operator=( map&& other ); \fB(2)\fP \fI(since C++11)\fP - map& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + map& operator=( map&& other ); \fI(since C++11)\fP + \fB(2)\fP \fI(until C++17)\fP + map& operator=( map&& other ) noexcept(/* see below */); \fI(since C++17)\fP + map& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,67 +47,98 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) O(NlogN) in general, where N is size() + ilist.size(). Linear if ilist is sorted + with respect to value_comp(). + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::map to another: - The following code uses to assign one std::map to another: - // Run this code - #include + #include #include - - void display_sizes(const std::map &nums1, - const std::map &nums2, - const std::map &nums3) + #include + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& [key, value] : container) + std::cout << '{' << key << ',' << value << (--size ? "}, " : "} "); + std::cout << "}\\n"; } - + int main() { - std::map nums1 {{3, 1}, {4, 1}, {5, 9}, - {6, 1}, {7, 1}, {8, 9}}; - std::map nums2; - std::map nums3; - + std::map x{{1,1}, {2,2}, {3,3}}, y, z; + const auto w = {std::pair{4,4}, {5,5}, {6,6}, {7,7}}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { {1,1}, {2,2}, {3,3} } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { {1,1}, {2,2}, {3,3} } + y = { {1,1}, {2,2}, {3,3} } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { {1,1}, {2,2}, {3,3} } + Assignment of initializer_list w to z: + w = { {4,4}, {5,5}, {6,6}, {7,7} } + z = { {4,4}, {5,5}, {6,6}, {7,7} } .SH See also constructor constructs the map - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::map::operator[].3 b/man/std::map::operator[].3 index b822f95a1..b2a326b23 100644 --- a/man/std::map::operator[].3 +++ b/man/std::map::operator[].3 @@ -1,44 +1,81 @@ -.TH std::map::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::operator[] \- std::map::operator[] + .SH Synopsis T& operator[]( const Key& key ); \fB(1)\fP T& operator[]( Key&& key ); \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP (since C++26) + T& operator[]( K&& x ); - Returns a reference to the value that is mapped to a key equivalent to key, - performing an insertion if such key does not already exist. - - If an insertion is performed, the mapped value is value-initialized - (default-constructed for class types, zero-initialized otherwise) and a reference to - it is returned. + Returns a reference to the value that is mapped to a key equivalent to key or x + respectively, performing an insertion if such key does not already exist. - 1) Inserts value_type(key, T()) + 1) Inserts value_type(key, T()) if the key does not exist. - key_type must meet the requirements of CopyConstructible. - - mapped_type must meet the requirements of DefaultConstructible. \fI(since C++11)\fP + mapped_type must meet the requirements of CopyConstructible and \fI(until C++11)\fP + DefaultConstructible. - 2) Inserts value_type(std::move(key), T()) + If an insertion is performed, the mapped value is value-initialized + (default-constructed for class types, zero-initialized otherwise) and + a reference to it is returned. + 1) Inserts a value_type object constructed in-place from + std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>() + if the key does not exist. + Equivalent to return this->try_emplace(key).first->second;. + \fI(since C++17)\fPWhen the default allocator is used, this results in the + key being copy constructed from key and the mapped value being + value-initialized. - - key_type must meet the requirements of MoveConstructible. \fI(since C++11)\fP + value_type must be EmplaceConstructible from std::piecewise_construct, + std::forward_as_tuple(key), std::tuple<>(). When the default allocator + is used, this means that key_type must be CopyConstructible and + mapped_type must be DefaultConstructible. + \fI(since C++11)\fP + 2) Inserts a value_type object constructed in-place from + std::piecewise_construct, std::forward_as_tuple(std::move(key)), + std::tuple<>() if the key does not exist. + Equivalent to return this->try_emplace(std::move(key)).first->second;. + \fI(since C++17)\fP + When the default allocator is used, this results in the key being move + constructed from key and the mapped value being value-initialized. + - - mapped_type must meet the requirements of DefaultConstructible. \fI(since C++11)\fP + value_type must be EmplaceConstructible from std::piecewise_construct, + std::forward_as_tuple(std::move(key)), std::tuple<>(). When the + default allocator is used, this means that key_type must be + MoveConstructible and mapped_type must be DefaultConstructible. + + 3) Inserts a value_type object constructed in-place if there is no key that + transparently compares equivalent to the value x. + Equivalent to return this->try_emplace(std::forward(x)).first->second;. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. No iterators or references are invalidated. .SH Parameters key - the key of the element to find + x - a value of any type that can be transparently compared with a key .SH Return value - Reference to the mapped value of the new element if no element with key key existed. - Otherwise a reference to the mapped value of the existing element whose key is - equivalent to key. + 1,2) A reference to the mapped value of the new element if no element with key key + existed. Otherwise, a reference to the mapped value of the existing element whose + key is equivalent to key. + 3) A reference to the mapped value of the new element if no element with key that + compares equivalent to the value x existed. Otherwise, a reference to the mapped + value of the existing element whose key compares equivalent to x. .SH Exceptions - If an exception is thrown by any operation, the insertion has no effect + If an exception is thrown by any operation, the insertion has no effect. .SH Complexity @@ -46,91 +83,100 @@ .SH Notes - Until C++11, the overload \fB(1)\fP was specified to be equivalent to - (insert(std::make_pair(key, T())).first)->second, which required T to be - CopyConstructible. + In the published C++11 and C++14 standards, this function was specified to require + mapped_type to be DefaultInsertable and key_type to be CopyInsertable or + MoveInsertable into *this. This specification was defective and was fixed by LWG + issue 2469, and the description above incorporates the resolution of that issue. + + However, one implementation (libc++) is known to construct the key_type and + mapped_type objects via two separate allocator construct() calls, as arguably + required by the standards as published, rather than emplacing a value_type object. + + operator[] is non-const because it inserts the key if it doesn't exist. If this + behavior is undesirable or if the container is const, at may be used. + + insert_or_assign returns more information than operator[] and does not \fI(since C++17)\fP + require default-constructibility of the mapped type. + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. \fB(3)\fP .SH Example - This example demonstrates how to modify existing values and insert new values using - operator[]: - // Run this code #include + #include #include - - int main() + + void println(auto const comment, auto const& map) { - std::map letter_counts {{'a', 27}, {'b', 3}, {'c', 1}}; - - std::cout << "initially:\\n"; - for (const auto &pair : letter_counts) { - std::cout << pair.first << ": " << pair.second << '\\n'; - } - - letter_counts['b'] = 42; // update an existing value - - letter_counts['x'] = 9; // insert a new value - - std::cout << "after modifications:\\n"; - for (const auto &pair : letter_counts) { - std::cout << pair.first << ": " << pair.second << '\\n'; - } + std::cout << comment << '{'; + for (const auto& pair : map) + std::cout << '{' << pair.first << ": " << pair.second << '}'; + std::cout << "}\\n"; } -.SH Output: + int main() + { + std::map letter_counts{{'a', 27}, {'b', 3}, {'c', 1}}; - initially: - a: 27 - b: 3 - c: 1 - after modifications: - a: 27 - b: 42 - c: 1 - x: 9 + println("letter_counts initially contains: ", letter_counts); - The following example counts the occurrences of each word in a vector of strings: + letter_counts['b'] = 42; // updates an existing value + letter_counts['x'] = 9; // inserts a new value - -// Run this code + println("after modifications it contains: ", letter_counts); - #include - #include - #include - #include - - int main() - { - std::vector words = { - "this", "sentence", "is", "not", "a", "sentence", - "this", "sentence", "is", "a", "hoax" - }; - - std::map word_map; - for (const auto &w : words) { + // count the number of occurrences of each word + // (the first call to operator[] initialized the counter with zero) + std::map word_map; + for (const auto& w : {"this", "sentence", "is", "not", "a", "sentence", + "this", "sentence", "is", "a", "hoax"}) ++word_map[w]; - } - - for (const auto &pair : word_map) { - std::cout << pair.second - << " occurrences of word '" - << pair.first << "'\\n"; - } + word_map["that"]; // just inserts the pair {"that", 0} + + for (const auto& [word, count] : word_map) + std::cout << count << " occurrence(s) of word '" << word << "'\\n"; } .SH Output: - 1 occurrences of word 'hoax' - 2 occurrences of word 'this' - 2 occurrences of word 'a' - 2 occurrences of word 'is' - 1 occurrences of word 'not' - 3 occurrences of word 'sentence' + letter_counts initially contains: {{a: 27}{b: 3}{c: 1}} + after modifications it contains: {{a: 27}{b: 42}{c: 1}{x: 9}} + 2 occurrence(s) of word 'a' + 1 occurrence(s) of word 'hoax' + 2 occurrence(s) of word 'is' + 1 occurrence(s) of word 'not' + 3 occurrence(s) of word 'sentence' + 0 occurrence(s) of word 'that' + 2 occurrence(s) of word 'this' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the effect of overload \fB(1)\fP was simply + LWG 334 C++98 returning provided its own + (*((insert(std::make_pair(x, description instead + T()))).first)).second .SH See also - at access specified element with bounds checking - \fI(C++11)\fP \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + insert_or_assign inserts an element or assigns to the current element if the key + \fI(C++17)\fP already exists + \fI(public member function)\fP + try_emplace inserts in-place if the key does not exist, does nothing if the key + \fI(C++17)\fP exists + \fI(public member function)\fP diff --git a/man/std::map::rbegin,std::map::crbegin.3 b/man/std::map::rbegin,std::map::crbegin.3 index 0e7af8198..3c5197ae4 100644 --- a/man/std::map::rbegin,std::map::crbegin.3 +++ b/man/std::map::rbegin,std::map::crbegin.3 @@ -1,11 +1,15 @@ -.TH std::map::rbegin,std::map::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::rbegin,std::map::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::rbegin,std::map::crbegin \- std::map::rbegin,std::map::crbegin + .SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. + Returns a reverse iterator to the first element of the reversed map. It corresponds + to the last element of the non-reversed map. If the map is empty, the returned + iterator is equal to rend(). range-rbegin-rend.svg @@ -17,18 +21,59 @@ Reverse iterator to the first element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::map coins + { + {10, "dime"}, + {100, "dollar"}, + {50, "half dollar"}, + {5, "nickel"}, + {1, "penny"}, + {25, "quarter"} + }; // initializer entries in name alphabetical order + + std::cout << "US coins in circulation, largest to smallest denomination:\\n"; + for (auto it = coins.crbegin(); it != coins.crend(); ++it) + std::cout << std::setw(11) << it->second << " = ¢" << it->first << '\\n'; + } + +.SH Output: + + US coins in circulation, largest to smallest denomination: + dollar = ¢100 + half dollar = ¢50 + quarter = ¢25 + dime = ¢10 + nickel = ¢5 + penny = ¢1 + .SH See also - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::map::rend,std::map::crend.3 b/man/std::map::rend,std::map::crend.3 index 47fa3260e..fd01ff195 100644 --- a/man/std::map::rend,std::map::crend.3 +++ b/man/std::map::rend,std::map::crend.3 @@ -1,13 +1,16 @@ -.TH std::map::rend,std::map::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::rend,std::map::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::rend,std::map::crend \- std::map::rend,std::map::crend + .SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. + map. It corresponds to the element preceding the first element of the non-reversed + map. This element acts as a placeholder, attempting to access it results in + undefined behavior. range-rbegin-rend.svg @@ -19,18 +22,65 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono; + + int main() + { + const std::map messages + { + {February/17/2023, 10}, + {February/17/2023, 20}, + {February/16/2022, 30}, + {October/22/2022, 40}, + {June/14/2022, 50}, + {November/23/2021, 60}, + {December/10/2022, 55}, + {December/12/2021, 45}, + {April/1/2020, 42}, + {April/1/2020, 24} + }; + + std::cout << "Messages received (date order is reversed):\\n"; + for (auto it = messages.crbegin(); it != messages.crend(); ++it) + std::cout << it->first << " : " << it->second << '\\n'; + } + +.SH Possible output: + + Messages received (date order is reversed): + 2023-02-17 : 10 + 2022-12-10 : 55 + 2022-10-22 : 40 + 2022-06-14 : 50 + 2022-02-16 : 30 + 2021-12-12 : 45 + 2021-11-23 : 60 + 2020-04-01 : 42 + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::map::size.3 b/man/std::map::size.3 index 91dd52239..74fb2d2f2 100644 --- a/man/std::map::size.3 +++ b/man/std::map::size.3 @@ -1,6 +1,9 @@ -.TH std::map::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::size \- std::map::size + .SH Synopsis - size_type size() const; + size_type size() const; (noexcept since C++11) Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,26 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::map: - + // Run this code - #include #include - + #include + int main() { - std::map nums {{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; - + std::map nums{{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +45,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::map::swap.3 b/man/std::map::swap.3 index c4277aa89..f6e6243e7 100644 --- a/man/std::map::swap.3 +++ b/man/std::map::swap.3 @@ -1,19 +1,23 @@ -.TH std::map::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::swap \- std::map::swap + .SH Synopsis - void swap( map& other ); + void swap( map& other ); \fI(until C++17)\fP + void swap( map& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. + + The Compare objects must be Swappable, and they are exchanged using unqualified call + to non-member swap. - The Pred objects must be Swappable, and they are exchanged using unqualified call to - non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +29,83 @@ .SH Exceptions - Any exception thrown by the swap of the Compare objects. + Any exception thrown by the swap of the Compare objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // print out a std::pair + template + Os& operator<<(Os& os, const std::pair& p) + { + return os << p.first << ':' << p.second; + } + + // print out a container + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " }\\n"; + } + + int main() + { + std::map + m1{{"γ", "gamma"}, {"β", "beta"}, {"α", "alpha"}, {"γ", "gamma"}}, + m2{{"ε", "epsilon"}, {"δ", "delta"}, {"ε", "epsilon"}}; + + const auto& ref = *(m1.begin()); + const auto iter = std::next(m1.cbegin()); + + std::cout << "──────── before swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + m1.swap(m2); + + std::cout << "──────── after swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + // Note that every iterator referring to an element in one container before + // the swap refers to the same element in the other container after the swap. + // Same is true for references. + } + +.SH Output: + + ──────── before swap ──────── + m1: { α:alpha β:beta γ:gamma } + m2: { δ:delta ε:epsilon } + ref: α:alpha + iter: β:beta + ──────── after swap ──────── + m1: { δ:delta ε:epsilon } + m2: { α:alpha β:beta γ:gamma } + ref: α:alpha + iter: β:beta + .SH See also std::swap(std::map) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::map::try_emplace.3 b/man/std::map::try_emplace.3 new file mode 100644 index 000000000..705d881de --- /dev/null +++ b/man/std::map::try_emplace.3 @@ -0,0 +1,170 @@ +.TH std::map::try_emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::try_emplace \- std::map::try_emplace + +.SH Synopsis + template< class... Args > + std::pair try_emplace( const Key& k, Args&&... \fB(1)\fP \fI(since C++17)\fP + args ); + template< class... Args > \fB(2)\fP \fI(since C++17)\fP + std::pair try_emplace( Key&& k, Args&&... args ); + template< class K, class... Args > \fB(3)\fP (since C++26) + std::pair try_emplace( K&& k, Args&&... args ); + template< class... Args > + iterator try_emplace( const_iterator hint, const Key& k, Args&&... \fB(4)\fP \fI(since C++17)\fP + args ); + template< class... Args > + iterator try_emplace( const_iterator hint, Key&& k, Args&&... args \fB(5)\fP \fI(since C++17)\fP + ); + template< class K, class... Args > + iterator try_emplace( const_iterator hint, K&& k, Args&&... args \fB(6)\fP (since C++26) + ); + + If a key equivalent to k already exists in the container, does nothing. Otherwise, + inserts a new element into the container with key k and value constructed with args. + In such case: + + 1) Behaves like emplace except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(k), + + std::forward_as_tuple(std::forward(args)...)) + 2) Behaves like emplace except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::move(k)), + + std::forward_as_tuple(std::forward(args)...)) + 3) Behaves like emplace except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::forward(k)), + + std::forward_as_tuple(std::forward(args)...)) + 4) Behaves like emplace_hint except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(k), + + std::forward_as_tuple(std::forward(args)...)) + 5) Behaves like emplace_hint except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::move(k)), + + std::forward_as_tuple(std::forward(args)...)) + 6) Behaves like emplace_hint except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::forward(k)), + + std::forward_as_tuple(std::forward(args)...)) + 1-6) If value_type is not EmplaceConstructible into map from the corresponding + expression, the behavior is undefined. + 3) This overload participates in overload resolution only if all following + conditions are satisfied: + * std::is_convertible_v and std::is_convertible_v are both false. + * The qualified-id Compare::is_transparent is valid and denotes a type. + If equal_range(u.first) == equal_range(k) is false, the behavior is undefined, where + u is the new element to be inserted. + 6) This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. + If equal_range(u.first) == equal_range(k) is false, the behavior is undefined, where + u is the new element to be inserted. + + No iterators or references are invalidated. + +.SH Parameters + + k - the key used both to look up and to insert if not found + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Complexity + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Notes + + Unlike insert or emplace, these functions do not move from rvalue arguments if the + insertion does not happen, which makes it easy to manipulate maps whose values are + move-only types, such as std::map>. In addition, + try_emplace treats the key and the arguments to the mapped_type separately, unlike + emplace, which requires the arguments to construct a value_type (that is, a + std::pair). + + Overloads (3,6) can be called without constructing an object of type Key. + + Feature-test macro Value Std Feature + __cpp_lib_map_try_emplace 201411L \fI(C++17)\fP std::map::try_emplace, + std::map::insert_or_assign + Heterogeneous overloads + for the remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered and + unordered associative + containers. Overloads \fB(3)\fP + and \fB(6)\fP. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print_node(const auto& node) + { + std::cout << '[' << node.first << "] = " << node.second << '\\n'; + } + + void print_result(auto const& pair) + { + std::cout << (pair.second ? "inserted: " : "ignored: "); + print_node(*pair.first); + } + + int main() + { + using namespace std::literals; + std::map m; + + print_result(m.try_emplace("a", "a"s)); + print_result(m.try_emplace("b", "abcd")); + print_result(m.try_emplace("c", 10, 'c')); + print_result(m.try_emplace("c", "Won't be inserted")); + + for (const auto& p : m) + print_node(p); + } + +.SH Output: + + inserted: [a] = a + inserted: [b] = abcd + inserted: [c] = cccccccccc + ignored: [c] = cccccccccc + [a] = a + [b] = abcd + [c] = cccccccccc + +.SH See also + + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::map::upper_bound.3 b/man/std::map::upper_bound.3 index 74a277376..d8e032ccd 100644 --- a/man/std::map::upper_bound.3 +++ b/man/std::map::upper_bound.3 @@ -1,17 +1,20 @@ -.TH std::map::upper_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::upper_bound \- std::map::upper_bound + .SH Synopsis iterator upper_bound( const Key& key ); \fB(1)\fP - const_iterator upper_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP iterator upper_bound( const K& x ); - template< class K > \fB(2)\fP \fI(since C++14)\fP + template< class K > \fB(4)\fP \fI(since C++14)\fP const_iterator upper_bound( const K& x ) const; - 1) Returns an iterator pointing to the first element that is greater than key. - 2) Returns an iterator pointing to the first element that compares greater to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -27,9 +30,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::map::value_comp.3 b/man/std::map::value_comp.3 index 30cf2a401..a9fa7b2bd 100644 --- a/man/std::map::value_comp.3 +++ b/man/std::map::value_comp.3 @@ -1,4 +1,7 @@ -.TH std::map::value_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::value_comp \- std::map::value_comp + .SH Synopsis std::map::value_compare value_comp() const; @@ -17,7 +20,57 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::map cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.value_comp(); + + for (const std::pair val = {100, 'a'}; auto it : cont) + { + const bool before = comp_func(it, val); + const bool after = comp_func(val, it); + + std::cout << '(' << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val.first << ")\\n"; + else if (before) + std::cout << "goes before key (" << val.first << ")\\n"; + else if (after) + std::cout << "goes after key (" << val.first << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + .SH See also key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::map::value_compare.3 b/man/std::map::value_compare.3 index e08fc9477..91e9dd9d4 100644 --- a/man/std::map::value_compare.3 +++ b/man/std::map::value_compare.3 @@ -1,4 +1,7 @@ -.TH std::map::value_compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::value_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::value_compare \- std::map::value_compare + .SH Synopsis class value_compare; @@ -8,24 +11,27 @@ .SH Member types - Type Definition - result_type bool - first_argument_type value_type - second_argument_type value_type + Type Definition + result_type (deprecated in C++17)(removed in C++20) bool + first_argument_type (deprecated in C++17)(removed in C++20) value_type + second_argument_type (deprecated in C++17)(removed in C++20) value_type + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Protected member objects - Name Type - comp Compare + Compare comp the stored comparator + \fI(protected member object)\fP .SH Member functions constructor constructs a new value_compare object - \fI(protected member function)\fP + \fI(protected member function)\fP operator() compares two values of type value_type - \fI(public member function)\fP + \fI(public member function)\fP - std::map::value_compare::value_compare +std::map::value_compare::value_compare protected: value_compare( Compare c ); @@ -36,7 +42,7 @@ c - comparator to assign - std::map::value_compare::operator() +std::map::value_compare::operator() bool operator()( const value_type& lhs, const value_type& rhs ) const; @@ -48,8 +54,8 @@ .SH Return value - comp(lhs.first, rhs.first). + comp(lhs.first, rhs.first) .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. diff --git a/man/std::map::~map.3 b/man/std::map::~map.3 index df85998f4..8cc2c075d 100644 --- a/man/std::map::~map.3 +++ b/man/std::map::~map.3 @@ -1,11 +1,14 @@ -.TH std::map::~map 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::map::~map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::map::~map \- std::map::~map + .SH Synopsis ~map(); - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. + Destructs the map. The destructors of the elements are called and the used storage + is deallocated. Note, that if the elements are pointers, the pointed-to objects are + not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the map. diff --git a/man/std::mask_array.3 b/man/std::mask_array.3 index a82c9b10c..82048dcfa 100644 --- a/man/std::mask_array.3 +++ b/man/std::mask_array.3 @@ -1,11 +1,15 @@ -.TH std::mask_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mask_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mask_array \- std::mask_array + .SH Synopsis Defined in header template< class T > class mask_array; - std::gslice_array is a helper template used by std::mask_array subscript operator. - It has reference semantics to a subset of the array specified by an mask array - (std::valarray object). + std::mask_array is a helper template used by the valarray subscript operator with + std::valarray argument. It has reference semantics and provides access to the + subset of the valarray consisting of the elements whose indices correspond to true + values in the std::valarray mask. .SH Member types @@ -15,17 +19,17 @@ .SH Member functions constructor constructs a mask_array - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a mask_array - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP operator+= operator-= operator*= operator/= operator%= performs arithmetic operation on the array referred by mask. - operator&= \fI(public member function)\fP + operator&= \fI(public member function)\fP operator|= operator^= operator<<= @@ -33,30 +37,38 @@ .SH Example - + // Run this code #include #include - - int main() + + void println(auto rem, const auto& data) { - std::valarray data = {0,1,2,3,4,5,6,7,8,9}; - - std::cout << "Initial valarray: "; - for(int n: data) std::cout << n << ' '; + for (std::cout << rem; int n : data) + std::cout << n << ' '; std::cout << '\\n'; - + } + + int main() + { + std::valarray data{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + + println("Initial valarray: ", data); + data[data > 5] = -1; // the type of data>5 is std::valarray // the type of data[data>5] is std::mask_array - - std::cout << "After v[v>5]=-1: "; - for(int n: data) std::cout << n << ' '; - std::cout << '\\n'; + + println("After v[v>5]=-1: ", data); } .SH Output: Initial valarray: 0 1 2 3 4 5 6 7 8 9 After v[v>5]=-1: 0 1 2 3 4 5 -1 -1 -1 -1 + +.SH See also + + simd_mask data-parallel type with the element type bool + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::mask_array::mask_array.3 b/man/std::mask_array::mask_array.3 index 8173ac489..13d6fa1b4 100644 --- a/man/std::mask_array::mask_array.3 +++ b/man/std::mask_array::mask_array.3 @@ -1,12 +1,30 @@ -.TH std::mask_array::mask_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mask_array::mask_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mask_array::mask_array \- std::mask_array::mask_array + .SH Synopsis - mask_array( const mask_array& other ); + private: \fI(until C++11)\fP + mask_array(); + public: \fB(1)\fP \fI(since C++11)\fP mask_array() = delete; + public: \fB(2)\fP + mask_array( const mask_array& other ); - Constructs a mask_array from another mask_array other. - - The default constructor is implicitly deleted. + 1) The default constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: mask_array is not DefaultConstructible. + 2) Constructs a mask_array from another mask_array other. .SH Parameters other - mask_array to initialize with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 253 C++98 the copy constructor was private made public diff --git a/man/std::mask_array::operator=.3 b/man/std::mask_array::operator=.3 index ac925aa1e..6f6567055 100644 --- a/man/std::mask_array::operator=.3 +++ b/man/std::mask_array::operator=.3 @@ -1,35 +1,76 @@ -.TH std::mask_array::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mask_array::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mask_array::operator= \- std::mask_array::operator= + .SH Synopsis - void operator=( const T& value ) const; \fB(1)\fP - void operator=( const std::valarray& val_arr ) const; \fB(2)\fP - const mask_array& operator=( const mask_array& sl_arr) const; \fB(3)\fP \fI(since C++11)\fP + void operator=( const T& value ) const; \fB(1)\fP + void operator=( const std::valarray& val_arr ) const; \fB(2)\fP + const mask_array& operator=( const mask_array& other_arr ) const; \fB(3)\fP Assigns values to all referred elements. 1) Assigns value to all of the elements. 2) Assigns the elements of val_arr to the referred to elements of *this. - 3) Assigns the selected elements from sl_arr to the referred to elements of *this. + 3) Assigns the selected elements from other_arr to the referred to elements of + *this. .SH Parameters - value - a value to assign to all of the referred elements - val_arr - std::valarray to assign - sl_arr - std::mask_array to assign + value - a value to assign to all of the referred elements + val_arr - std::valarray to assign + other_arr - std::mask_array to assign .SH Return value - 1-2) \fI(none)\fP + 1,2) \fI(none)\fP 3) *this -.SH Exceptions +.SH Example - \fI(none)\fP -.SH Example +// Run this code + + #include + #include + #include + + void print(std::valarray const& v) + { + for (int e : v) + std::cout << std::setw(2) << e << ' '; + std::cout << '\\n'; + } + + int main() + { + const auto init = {1, 2, 3, 4, 5, 6, 7, 8}; + std::valarray v; + + v = init; + v[(v % 2) == 0] = 0; // (1) + print(v); + + v = init; + v[(v % 2) == 1] = std::valarray{-1, -2, -3, -4}; // (2) + print(v); + + v = init; + v[(v % 2) == 0] = v[(v % 2) == 1]; // (3) + print(v); + } + +.SH Output: + + 1 0 3 0 5 0 7 0 + -1 2 -2 4 -3 6 -4 8 + 1 1 3 3 5 5 7 7 - This section is incomplete - Reason: no example + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo no example + DR Applied to Behavior as published Correct behavior + LWG 123 C++98 overload \fB(2)\fP was non-const made const + LWG 253 C++98 the copy assignment operator was private made public + LWG 621 C++98 the copy assignment operator was non-const made const diff --git a/man/std::mask_array::~mask_array.3 b/man/std::mask_array::~mask_array.3 index eb1f2743b..03c13ed21 100644 --- a/man/std::mask_array::~mask_array.3 +++ b/man/std::mask_array::~mask_array.3 @@ -1,6 +1,9 @@ -.TH std::mask_array::~mask_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mask_array::~mask_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mask_array::~mask_array \- std::mask_array::~mask_array + .SH Synopsis ~mask_array(); - Destroys the indexes in the array. The elements referred to by the object are not + Destroys the indices in the array. The elements referred to by the object are not modified. diff --git a/man/std::match_results.3 b/man/std::match_results.3 index f3f85aef1..8c8dc929c 100644 --- a/man/std::match_results.3 +++ b/man/std::match_results.3 @@ -1,12 +1,23 @@ -.TH std::match_results 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results \- std::match_results + .SH Synopsis Defined in header template< - class BidirIt, \fI(since C++11)\fP + class BidirIt, \fB(1)\fP \fI(since C++11)\fP class Alloc = std::allocator> > class match_results; + namespace pmr { + + template + using match_results = std::match_results>>; + + } The class template std::match_results holds a collection of character sequences that represent the result of a regular expression match. @@ -18,15 +29,20 @@ undefined behavior to examine std::match_results if the original character sequence was destroyed or iterators to it were invalidated for other reasons. - The first sub_match (index 0) contained in a match_result always represents the full - match within a target sequence made by a regex, and subsequent sub_matches represent - sub-expression matches corresponding in sequence to the left parenthesis delimiting - the sub-expression in the regex. + The first std::sub_match (index 0) contained in a std::match_result always + represents the full match within a target sequence made by a regex, and subsequent + std::sub_matches represent sub-expression matches corresponding in sequence to the + left parenthesis delimiting the sub-expression in the regex. + + std::match_results meets the requirements of a AllocatorAwareContainer and of a + SequenceContainer, except that only copy assignment, move assignment, and operations + defined for a constant containers are supported, and that the semantics of + comparison functions are different from those required for a container. .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. - Alloc must meet the requirements of Allocator. @@ -35,11 +51,15 @@ Several specializations for common character sequence types are provided: Defined in header - Type Definition - cmatch match_results - wcmatch match_results - smatch match_results - wsmatch match_results + Type Definition + std::cmatch std::match_results + std::wcmatch std::match_results + std::smatch std::match_results + std::wsmatch std::match_results + std::pmr::cmatch \fI(C++17)\fP std::pmr::match_results + std::pmr::wcmatch \fI(C++17)\fP std::pmr::match_results + std::pmr::smatch \fI(C++17)\fP std::pmr::match_results + std::pmr::wsmatch \fI(C++17)\fP std::pmr::match_results .SH Member types @@ -47,8 +67,8 @@ allocator_type Allocator value_type std::sub_match const_reference const value_type& - reference const_reference - const_iterator implementation defined (depends on the underlying container) + reference value_type& + const_iterator implementation-defined (depends on the underlying container) iterator const_iterator difference_type std::iterator_traits::difference_type size_type std::allocator_traits::size_type @@ -58,55 +78,55 @@ .SH Member functions constructor constructs the object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH State ready checks if the results are available \fI(public member function)\fP .SH Size empty checks whether the match was successful - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of matches in a fully-established result state - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of sub-matches - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access length returns the length of the particular sub-match - \fI(public member function)\fP + \fI(public member function)\fP returns the position of the first character of the particular position sub-match - \fI(public member function)\fP + \fI(public member function)\fP str returns the sequence of characters for the particular sub-match - \fI(public member function)\fP + \fI(public member function)\fP operator[] returns specified sub-match - \fI(public member function)\fP + \fI(public member function)\fP returns sub-sequence between the beginning of the target sequence and - prefix the beginning of the full match. - \fI(public member function)\fP + prefix the beginning of the full match + \fI(public member function)\fP returns sub-sequence between the end of the full match and the end of suffix the target sequence - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators begin returns iterator to the beginning of the list of sub-matches - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP end returns iterator to the end of the list of sub-matches - cend \fI(public member function)\fP + cend \fI(public member function)\fP .SH Format format formats match results for output - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== lexicographically compares the values in the two match operator!= result - \fI(function template)\fP - std::swap(std::match_results) specializes the std::swap() algorithm - \fI(C++11)\fP \fI(function template)\fP + (removed in C++20) \fI(function template)\fP + std::swap(std::match_results) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::match_results::begin,std::match_results::cbegin.3 b/man/std::match_results::begin,std::match_results::cbegin.3 index 14c6c1c4a..7e56ae65f 100644 --- a/man/std::match_results::begin,std::match_results::cbegin.3 +++ b/man/std::match_results::begin,std::match_results::cbegin.3 @@ -1,8 +1,11 @@ -.TH std::match_results::begin,std::match_results::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::begin,std::match_results::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::begin,std::match_results::cbegin \- std::match_results::begin,std::match_results::cbegin + .SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin() noexcept; \fI(since C++11)\fP + const_iterator begin() const noexcept; \fI(since C++11)\fP + const_iterator cbegin() const noexcept; \fI(since C++11)\fP Returns an iterator to the beginning of the list of sub-matches. If match was successful, the iterator will point to the entire matched expression. @@ -15,17 +18,11 @@ Iterator to the first sub-match. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity - Constant + Constant. .SH See also end returns iterator to the end of the list of sub-matches - cend \fI(public member function)\fP + cend \fI(public member function)\fP diff --git a/man/std::match_results::empty.3 b/man/std::match_results::empty.3 index 38bc56e1a..234fe53fd 100644 --- a/man/std::match_results::empty.3 +++ b/man/std::match_results::empty.3 @@ -1,6 +1,11 @@ -.TH std::match_results::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::empty \- std::match_results::empty + .SH Synopsis - bool empty() const; \fI(since C++11)\fP + bool empty() const; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const; \fI(since C++20)\fP Checks whether the match was successful. @@ -10,11 +15,12 @@ .SH Return value - true if the match_results object contains no matches., false otherwise + true if *this represents the result of a failed match, false otherwise, i.e. size() + == 0. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Complexity @@ -23,4 +29,4 @@ .SH See also size returns the number of matches in a fully-established result state - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::match_results::end,std::match_results::cend.3 b/man/std::match_results::end,std::match_results::cend.3 index 86b4f963c..bf5f05b87 100644 --- a/man/std::match_results::end,std::match_results::cend.3 +++ b/man/std::match_results::end,std::match_results::cend.3 @@ -1,8 +1,11 @@ -.TH std::match_results::end,std::match_results::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::end,std::match_results::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::end,std::match_results::cend \- std::match_results::end,std::match_results::cend + .SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP + iterator end() noexcept; \fI(since C++11)\fP + const_iterator end() const noexcept; \fI(since C++11)\fP + const_iterator cend() const noexcept; \fI(since C++11)\fP Returns an iterator to the end of the list of sub-matches. @@ -14,17 +17,11 @@ Iterator to the element past the last sub-match. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity - Constant + Constant. .SH See also begin returns iterator to the beginning of the list of sub-matches - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP diff --git a/man/std::match_results::format.3 b/man/std::match_results::format.3 index 806a075fa..90d68542b 100644 --- a/man/std::match_results::format.3 +++ b/man/std::match_results::format.3 @@ -1,22 +1,23 @@ -.TH std::match_results::format 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::format \- std::match_results::format + .SH Synopsis template< class OutputIt > - OutputIter format( OutputIt out, - const char_type* fmt_first, const char_type* - fmt_last, \fB(1)\fP \fI(since C++11)\fP - std::regex_constants::match_flag_type flags = + OutputIt format( OutputIt out, + const char_type* fmt_first, const char_type* \fB(1)\fP \fI(since C++11)\fP + fmt_last, + std::regex_constants::match_flag_type flags = - std::regex_constants::format_default ) - const; + std::regex_constants::format_default ) const; template< class OutputIt, class ST, class SA > - OutputIter format( OutputIt out, - const basic_string& fmt, \fB(2)\fP \fI(since C++11)\fP - std::regex_constants::match_flag_type flags = + OutputIt format( OutputIt out, + const basic_string& fmt, \fB(2)\fP \fI(since C++11)\fP + std::regex_constants::match_flag_type flags = - std::regex_constants::format_default ) - const; + std::regex_constants::format_default ) const; template< class ST, class SA > std::basic_string @@ -38,7 +39,7 @@ resulting character sequence is copied to out. 2) The format character sequence is defined by the characters in fmt. The resulting character sequence is copied to out. - 3-4) The format character sequence is defined by the characters in fmt and fmt_s + 3,4) The format character sequence is defined by the characters in fmt and fmt_s respectively. The resulting character sequence is copied to a newly constructed std::basic_string, which is returned. @@ -59,37 +60,38 @@ format specifiers and escape sequences are recognized .SH Type requirements - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. .SH Return value - 1-2) out - 3-4) The newly constructed string containing resulting character sequence. + 1,2) out + 3,4) The newly constructed string containing resulting character sequence. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::string s = "for a good time, call 867-5309"; std::regex phone_regex("\\\\d{3}-\\\\d{4}"); std::smatch phone_match; - - if (std::regex_search(s, phone_match, phone_regex)) { + + if (std::regex_search(s, phone_match, phone_regex)) + { std::string fmt_s = phone_match.format( - "$`" // $` means characters before the match - "[$&]" // $& means the matched characters - "$'"); // $' means characters following the match + "$`" // $` means characters before the match + "[$&]" // $& means the matched characters + "$'"); // $' means characters following the match std::cout << fmt_s << '\\n'; } } @@ -102,6 +104,6 @@ regex_replace replaces occurrences of a regular expression with formatted \fI(C++11)\fP replacement text - \fI(function template)\fP + \fI(function template)\fP match_flag_type options specific to matching - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP diff --git a/man/std::match_results::get_allocator.3 b/man/std::match_results::get_allocator.3 index b5dd2d1c6..7a4c16f8f 100644 --- a/man/std::match_results::get_allocator.3 +++ b/man/std::match_results::get_allocator.3 @@ -1,4 +1,7 @@ -.TH std::match_results::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::get_allocator \- std::match_results::get_allocator + .SH Synopsis allocator_type get_allocator() const; \fI(since C++11)\fP diff --git a/man/std::match_results::length.3 b/man/std::match_results::length.3 index e46dff90b..c9e62e2f8 100644 --- a/man/std::match_results::length.3 +++ b/man/std::match_results::length.3 @@ -1,4 +1,7 @@ -.TH std::match_results::length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::length \- std::match_results::length + .SH Synopsis difference_type length( size_type n = 0 ) const; \fI(since C++11)\fP @@ -6,7 +9,7 @@ If n == 0, the length of the entire matched expression is returned. - If n > 0 && n < size(), the length of nth sub-match is returned. + If n > 0 && n < size(), the length of n^th sub-match is returned. if n >= size(), a length of the unmatched match is returned. @@ -23,6 +26,6 @@ .SH See also operator[] returns specified sub-match - \fI(public member function)\fP + \fI(public member function)\fP length returns the length of the match (if any) - \fI(public member function of std::sub_match)\fP + \fI(public member function of std::sub_match)\fP diff --git a/man/std::match_results::match_results.3 b/man/std::match_results::match_results.3 index 4267d0d17..712160b0b 100644 --- a/man/std::match_results::match_results.3 +++ b/man/std::match_results::match_results.3 @@ -1,24 +1,51 @@ -.TH std::match_results::match_results 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::match_results 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::match_results \- std::match_results::match_results + .SH Synopsis - explicit match_results( const Allocator& a = Allocator() ); \fB(1)\fP \fI(since C++11)\fP - match_results( const match_results& rhs ); \fB(2)\fP \fI(since C++11)\fP - match_results( match_results&& rhs ); \fB(3)\fP \fI(since C++11)\fP + match_results() : match_results(Allocator()) {} \fB(1)\fP \fI(since C++11)\fP + explicit match_results( const Allocator& a ); \fB(2)\fP \fI(since C++11)\fP + match_results( const match_results& rhs ); \fB(3)\fP \fI(since C++11)\fP + match_results( const match_results& rhs, const Allocator& a ); \fB(4)\fP \fI(since C++11)\fP + match_results( match_results&& rhs ) noexcept; \fB(5)\fP \fI(since C++11)\fP + match_results( match_results&& rhs, const Allocator& a ); \fB(6)\fP \fI(since C++11)\fP - 1) Default-constructor. Constructs a match result with no established result state + 1) Default constructor. Constructs a match result with no established result state (ready() != true). - 2) Copy-constructor. Constructs a match result with a copy of rhs. - 3) Move-constructor. Constructs a match result with the contents of rhs using move + 2) Constructs a match result with no established result state (ready() != true) + using a copy of a as the allocator. + 3) Copy constructor. Constructs a match result with a copy of rhs. + 4) Constructs a match result with a copy of rhs, and uses a copy of a as the + allocator. + 5) Move constructor. Constructs a match result with the contents of rhs using move semantics. rhs is in valid, but unspecified state after the call. + 6) Constructs a match result with the contents of rhs using move semantics, and uses + a copy of a as the allocator. rhs is in valid, but unspecified state after the call. .SH Parameters a - allocator to use for all memory allocations of this container - rhs - another match_result to use as source to initialize the match_result with + rhs - another match_results to use as source to initialize the match_results with .SH Exceptions - 1-2) \fI(none)\fP - 3) - noexcept specification: - noexcept - + 1-4) May throw implementation-defined exceptions. + 6) Throws nothing if a == rhs.get_allocator() is true. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2195 C++11 the constructors required by added + AllocatorAwareContainer were missing + P0935R0 C++11 default constructor was explicit made implicit + +.SH Category: + * Todo no example diff --git a/man/std::match_results::max_size.3 b/man/std::match_results::max_size.3 index 70e2bb09e..94ace8e28 100644 --- a/man/std::match_results::max_size.3 +++ b/man/std::match_results::max_size.3 @@ -1,6 +1,9 @@ -.TH std::match_results::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::max_size \- std::match_results::max_size + .SH Synopsis - size_type max_size() const; \fI(since C++11)\fP + size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of submatches the match_results type is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) @@ -12,13 +15,7 @@ .SH Return value - Maximum number of submatches - -.SH Exceptions - - noexcept specification: - noexcept - + Maximum number of submatches. .SH Complexity diff --git a/man/std::match_results::operator=.3 b/man/std::match_results::operator=.3 index fa7066db8..8dc410f92 100644 --- a/man/std::match_results::operator=.3 +++ b/man/std::match_results::operator=.3 @@ -1,14 +1,17 @@ -.TH std::match_results::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::operator= \- std::match_results::operator= + .SH Synopsis Defined in header - match_results& operator=( const match_results& other ); \fB(1)\fP \fI(since C++11)\fP - match_results& operator=( match_results&& other ); \fB(2)\fP \fI(since C++11)\fP + match_results& operator=( const match_results& other ); \fB(1)\fP \fI(since C++11)\fP + match_results& operator=( match_results&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP Assigns the contents. 1) Copy assignment operator. Assigns the contents of other. 2) Move assignment operator. Assigns the contents of other using move semantics. - other is in valid, but unspecified state after the operation. + other is in a valid, but unspecified state after the operation. .SH Parameters @@ -16,12 +19,8 @@ .SH Return value - *this. + *this .SH Exceptions - 1) \fI(none)\fP - 2) - noexcept specification: - noexcept - + 1) May throw implementation-defined exceptions. diff --git a/man/std::match_results::operator[].3 b/man/std::match_results::operator[].3 index 4835c2b7a..e53950596 100644 --- a/man/std::match_results::operator[].3 +++ b/man/std::match_results::operator[].3 @@ -1,14 +1,21 @@ -.TH std::match_results::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::operator[] \- std::match_results::operator[] + .SH Synopsis const_reference operator[]( size_type n ) const; \fI(since C++11)\fP - Returns an indicated sub-match. + If n > 0 and n < size(), returns a reference to the std::sub_match representing the + part of the target sequence that was matched by the n^th captured marked + subexpression). - If n == 0, entire matched expression is returned. + If n == 0, returns a reference to the std::sub_match representing the part of the + target sequence matched by the entire matched regular expression. - If n > 0 && n < size(), nth sub-match is returned. + if n >= size(), returns a reference to a std::sub_match representing an unmatched + sub-expression (an empty subrange of the target sequence). - if n >= size(), a sub-match representing the unmatched match is returned. + The behavior is undefined unless ready() == true. .SH Parameters @@ -16,32 +23,32 @@ .SH Return value - Returns a sub-match representing the specified match or sub match. + Reference to the std::sub_match representing the specified matched subrange within + the target sequence. .SH Example - + // Run this code #include #include #include - + int main() { std::string target("baaaby"); std::smatch sm; - + std::regex re1("a(a)*b"); std::regex_search(target, sm, re1); std::cout << "entire match: " << sm[0] << '\\n' << "submatch #1: " << sm[1] << '\\n'; - + std::regex re2("a(a*)b"); std::regex_search(target, sm, re2); std::cout << "entire match: " << sm[0] << '\\n' << "submatch #1: " << sm[1] << '\\n'; - } .SH Output: @@ -54,4 +61,4 @@ .SH See also str returns the sequence of characters for the particular sub-match - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::match_results::position.3 b/man/std::match_results::position.3 index a5d584866..abc10723b 100644 --- a/man/std::match_results::position.3 +++ b/man/std::match_results::position.3 @@ -1,13 +1,16 @@ -.TH std::match_results::position 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::position 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::position \- std::match_results::position + .SH Synopsis - difference_type position( size_type sub = 0 ) const; \fI(since C++11)\fP + difference_type position( size_type n = 0 ) const; \fI(since C++11)\fP Returns the position of the first character of the specified sub-match. - If n == 0, the position of the first character of entire matched expression is + If n == 0, the position of the first character of the entire matched expression is returned. - If n > 0 && n < size(), the position of the first character of nth sub-match is + If n > 0 && n < size(), the position of the first character of the n^th sub-match is returned. if n >= size(), a position of the first character of the unmatched match is @@ -23,28 +26,28 @@ .SH Example - + // Run this code #include #include #include - + int main() { std::regex re("a(a)*b"); std::string target("aaab"); std::smatch sm; - + std::regex_match(target, sm, re); std::cout << sm.position(1) << '\\n'; } .SH Output: - 1 + 2 .SH See also operator[] returns specified sub-match - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::match_results::prefix.3 b/man/std::match_results::prefix.3 index 7aa96c5e6..2a828d2de 100644 --- a/man/std::match_results::prefix.3 +++ b/man/std::match_results::prefix.3 @@ -1,35 +1,49 @@ -.TH std::match_results::prefix 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::prefix \- std::match_results::prefix + .SH Synopsis const_reference prefix() const; \fI(since C++11)\fP + Obtains a reference to the std::sub_match object representing the target sequence + between the start of the beginning of the target sequence and the start of the + entire match of the regular expression. + + The behavior is undefined unless ready() == true. + .SH Parameters \fI(none)\fP .SH Return value - Returns a sub_match representing the part of the target sequence between the - beginning of the target sequence and the entire match of the regular expression. + Reference to the unmatched prefix. .SH Example - + // Run this code #include #include #include - + int main() { - std::regex re("a(a)*b"); - std::string target("baaaby"); - std::smatch sm; - - std::regex_search(target, sm, re); - std::cout << sm.prefix().str() << '\\n'; + std::regex re("a(a)*b"); + std::string target("baaaby"); + std::smatch sm; + + std::regex_search(target, sm, re); + std::cout << sm.prefix().str() << '\\n'; } .SH Output: b + +.SH See also + + returns sub-sequence between the end of the full match and the end of the + suffix target sequence + \fI(public member function)\fP diff --git a/man/std::match_results::ready.3 b/man/std::match_results::ready.3 index 38649cb7c..eece1c482 100644 --- a/man/std::match_results::ready.3 +++ b/man/std::match_results::ready.3 @@ -1,4 +1,7 @@ -.TH std::match_results::ready 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::ready 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::ready \- std::match_results::ready + .SH Synopsis bool ready() const; \fI(since C++11)\fP @@ -17,28 +20,28 @@ .SH Example - + // Run this code #include #include #include - + int main() { std::string target("pattern"); std::smatch sm; std::cout << "default constructed smatch is " - << (sm.ready() ? " ready\\n" : " not ready\\n"); - + << (sm.ready() ? "ready\\n" : "not ready\\n"); + std::regex re1("tte"); std::regex_search(target, sm, re1); - + std::cout << "after search, smatch is " - << (sm.ready() ? " ready\\n" : " not ready\\n"); + << (sm.ready() ? "ready\\n" : "not ready\\n"); } .SH Output: - default constructed smatch is not ready - after search, smatch is ready + default constructed smatch is not ready + after search, smatch is ready diff --git a/man/std::match_results::size.3 b/man/std::match_results::size.3 index d37af7ed7..73f3ff578 100644 --- a/man/std::match_results::size.3 +++ b/man/std::match_results::size.3 @@ -1,48 +1,55 @@ -.TH std::match_results::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::size \- std::match_results::size + .SH Synopsis - size_type size() const; \fI(since C++11)\fP + size_type size() const noexcept; \fI(since C++11)\fP Returns the number of submatches, i.e. std::distance(begin(), end()). + Returns 0 if *this does not represent the result of a successful match. + .SH Parameters \fI(none)\fP .SH Return value - The number of submatches - -.SH Exceptions - - noexcept specification: - noexcept - + The number of submatches. .SH Complexity - Constant - -.SH See also + Constant. .SH Example - + // Run this code #include #include #include - + int main() { std::regex re("a(a)*b"); std::string target("aaab"); std::smatch sm; - + + std::cout << sm.size() << '\\n'; + std::regex_match(target, sm, re); std::cout << sm.size() << '\\n'; } .SH Output: + 0 2 + +.SH See also + + begin returns iterator to the beginning of the list of sub-matches + cbegin \fI(public member function)\fP + end returns iterator to the end of the list of sub-matches + cend \fI(public member function)\fP diff --git a/man/std::match_results::str.3 b/man/std::match_results::str.3 index 356fbc952..41436a9ae 100644 --- a/man/std::match_results::str.3 +++ b/man/std::match_results::str.3 @@ -1,4 +1,7 @@ -.TH std::match_results::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::str \- std::match_results::str + .SH Synopsis string_type str( size_type n = 0 ) const; \fI(since C++11)\fP @@ -6,7 +9,7 @@ If n == 0, a string representing entire matched expression is returned. - If n > 0 && n < size(), a string representing nth sub-match is returned. + If 0 < n && n < size(), a string representing n^th sub-match is returned. if n >= size(), a string representing the unmatched match is returned. @@ -22,28 +25,27 @@ .SH Example - + // Run this code #include #include #include - + int main() { std::string target("baaaby"); std::smatch sm; - + std::regex re1("a(a)*b"); std::regex_search(target, sm, re1); std::cout << "entire match: " << sm.str(0) << '\\n' << "submatch #1: " << sm.str(1) << '\\n'; - + std::regex re2("a(a*)b"); std::regex_search(target, sm, re2); std::cout << "entire match: " << sm.str(0) << '\\n' << "submatch #1: " << sm.str(1) << '\\n'; - } .SH Output: @@ -56,4 +58,4 @@ .SH See also operator[] returns specified sub-match - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::match_results::suffix.3 b/man/std::match_results::suffix.3 index b72e26d8c..02e5c7ce0 100644 --- a/man/std::match_results::suffix.3 +++ b/man/std::match_results::suffix.3 @@ -1,8 +1,15 @@ -.TH std::match_results::suffix 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::suffix \- std::match_results::suffix + .SH Synopsis const_reference suffix() const; \fI(since C++11)\fP - This section is incomplete + Obtains a reference to the std::sub_match object representing the target sequence + between the end of the entire match of the regular expression and the end of the + target sequence. + + The behavior is undefined unless ready() is true. .SH Parameters @@ -10,32 +17,33 @@ .SH Return value - Returns a sub_match representing the part of the target sequence between the end of - the entire match of the regular expression and the end of the target sequence. + Reference to the unmatched suffix. .SH Example - + // Run this code #include #include #include - + int main() { - std::regex re("a(a)*b"); - std::string target("baaaby"); + std::regex re("a(a)*by"); + std::string target("baaaby123"); std::smatch sm; - + std::regex_search(target, sm, re); - std::cout << sm.suffix().str() << '\\n'; + std::cout << sm.suffix() << '\\n'; } .SH Output: - y + 123 -.SH Category: +.SH See also - * Todo without reason + returns sub-sequence between the beginning of the target sequence and the + prefix beginning of the full match + \fI(public member function)\fP diff --git a/man/std::match_results::swap.3 b/man/std::match_results::swap.3 index de6d0f4d2..6a9015722 100644 --- a/man/std::match_results::swap.3 +++ b/man/std::match_results::swap.3 @@ -1,6 +1,9 @@ -.TH std::match_results::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::swap \- std::match_results::swap + .SH Synopsis - void swap( match_results& other ); \fI(since C++11)\fP + void swap( match_results& other ) noexcept; \fI(since C++11)\fP Exchanges the shared states of two match_results objects. @@ -12,12 +15,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -25,9 +22,8 @@ .SH See also - std::swap(std::match_results) specializes the std::swap() algorithm - \fI(C++11)\fP \fI(function template)\fP + std::swap(std::match_results) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::match_results::~match_results.3 b/man/std::match_results::~match_results.3 index 0e7cce5b8..74e8caeb8 100644 --- a/man/std::match_results::~match_results.3 +++ b/man/std::match_results::~match_results.3 @@ -1,4 +1,7 @@ -.TH std::match_results::~match_results 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::match_results::~match_results 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::match_results::~match_results \- std::match_results::~match_results + .SH Synopsis ~match_results(); \fI(since C++11)\fP diff --git a/man/std::max.3 b/man/std::max.3 index 14934abeb..2da1f2321 100644 --- a/man/std::max.3 +++ b/man/std::max.3 @@ -1,116 +1,150 @@ -.TH std::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::max \- std::max + .SH Synopsis Defined in header - template< class T > \fB(1)\fP + template< class T > \fB(1)\fP (constexpr since C++14) const T& max( const T& a, const T& b ); - template< class T, class Compare > \fB(2)\fP + template< class T, class Compare > \fB(2)\fP (constexpr since C++14) const T& max( const T& a, const T& b, Compare comp ); template< class T > \fB(3)\fP \fI(since C++11)\fP - T max( std::initializer_list ilist ); + T max( std::initializer_list ilist ); (constexpr since C++14) template< class T, class Compare > \fB(4)\fP \fI(since C++11)\fP - T max( std::initializer_list ilist, Compare comp ); + T max( std::initializer_list ilist, Compare comp ); (constexpr since C++14) Returns the greater of the given values. - 1-2) Returns the greater of a and b. - 3-4) Returns the greatest of the values in initializer list ilist. - - The (1,3) versions use operator< to compare the values, the (2,4) versions use the - given comparison function comp. + 1,2) Returns the greater of a and b. + 1) Uses operator< to compare the values. + If T is not LessThanComparable, the behavior is undefined. + 2) Use the comparison function comp to compare the values. + 3,4) Returns the greatest of the values in initializer list ilist. + If ilist.size() is zero, or T is not CopyConstructible, the behavior is undefined. + 3) Uses operator< to compare the values. + If T is not LessThanComparable, the behavior is undefined. + 4) Use the comparison function comp to compare the values. .SH Parameters a, b - the values to compare ilist - initializer list with the values to compare comparison function object (i.e. an object that satisfies the requirements - of Compare) which returns true if if a is less than b. + of Compare) which returns true if a is less than b. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must - not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type T can be - implicitly converted to both of them. -.SH Type requirements - - - T must meet the requirements of LessThanComparable. for the overloads \fB(1)\fP and \fB(3)\fP - - - T must meet the requirements of CopyConstructible. for the overloads \fB(3)\fP and \fB(4)\fP + implicitly converted to both of them. .SH Return value - 1-2) The greater of a and b. If they are equivalent, returns a. - - 3-4) The greatest value in ilist. If several values are equivalent to the greatest, + 1,2) The greater of a and b. If they are equivalent, returns a. + 3,4) The greatest value in ilist. If several values are equivalent to the greatest, returns the leftmost one. .SH Complexity - 1-2) Constant - - 3-4) Linear in ilist.size() + 1) Exactly one comparison using operator<. + 2) Exactly one application of the comparison function comp. + 3,4) Given \\(\\scriptsize N\\)N as ilist.size(): + 3) Exactly \\(\\scriptsize N-1\\)N-1 comparisons using operator<. + 4) Exactly \\(\\scriptsize N-1\\)N-1 applications of the comparison function comp. .SH Possible implementation -.SH First version + max \fB(1)\fP template const T& max(const T& a, const T& b) { return (a < b) ? b : a; } -.SH Second version + max \fB(2)\fP template const T& max(const T& a, const T& b, Compare comp) { return (comp(a, b)) ? b : a; } - Third version - template< class T > - T max( std::initializer_list ilist) + max \fB(3)\fP + template + T max(std::initializer_list ilist) { return *std::max_element(ilist.begin(), ilist.end()); } - Fourth version - template< class T, class Compare > - T max( std::initializer_list ilist, Compare comp ) + max \fB(4)\fP + template + T max(std::initializer_list ilist, Compare comp) { return *std::max_element(ilist.begin(), ilist.end(), comp); } +.SH Notes + + Capturing the result of std::max by reference produces a dangling reference if one + of the parameters is a temporary and that parameter is returned: + + int n = -1; + const int& r = std::max(n + 2, n * 2); // r is dangling + .SH Example - + // Run this code #include + #include #include - #include - + #include + int main() { - std::cout << "larger of 1 and 9999: " << std::max(1, 9999) << '\\n' - << "larger of 'a', and 'b': " << std::max('a', 'b') << '\\n' - << "longest of \\"foo\\", \\"bar\\", and \\"hello\\": " << - std::max( { "foo", "bar", "hello" }, - [](const std::string& s1, const std::string& s2) { - return s1.size() < s2.size(); - }) << '\\n'; + auto longest = [](const std::string_view s1, const std::string_view s2) + { + return s1.size() < s2.size(); + }; + + std::cout << "Larger of 69 and 96 is " << std::max(69, 96) << "\\n" + "Larger of 'q' and 'p' is '" << std::max('q', 'p') << "'\\n" + "Largest of 010, 10, 0X10, and 0B10 is " + << std::max({010, 10, 0X10, 0B10}) << '\\n' + << R"(Longest of "long", "short", and "int" is )" + << std::quoted(std::max({"long", "short", "int"}, longest)) << '\\n'; } .SH Output: - larger of 1 and 9999: 9999 - larger of 'a', and 'b': b - longest of "foo", "bar", and "hello": hello + Larger of 69 and 96 is 96 + Larger of 'q' and 'p' is 'q' + Largest of 010, 10, 0X10, and 0B10 is 16 + Longest of "long", "short", and "int" is "short" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 281 C++98 T was required to be CopyConstructible for not required + overloads (1,2) .SH See also - min returns the smaller of two elements - \fI(function template)\fP - minmax returns the larger and the smaller of two elements - \fI(C++11)\fP \fI(function template)\fP + min returns the smaller of the given values + \fI(function template)\fP + minmax returns the smaller and larger of two elements + \fI(C++11)\fP \fI(function template)\fP max_element returns the largest element in a range - \fI(function template)\fP + \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + ranges::max returns the greater of the given values + (C++20) (niebloid) diff --git a/man/std::max_align_t.3 b/man/std::max_align_t.3 index 1093f6893..3676580e9 100644 --- a/man/std::max_align_t.3 +++ b/man/std::max_align_t.3 @@ -1,26 +1,28 @@ -.TH std::max_align_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::max_align_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::max_align_t \- std::max_align_t + .SH Synopsis Defined in header typedef /*implementation-defined*/ max_align_t; \fI(since C++11)\fP - std::max_align_t is a POD type whose alignment requirement is at least as strict (as - large) as that of every scalar type. + std::max_align_t is a trivial standard-layout type whose alignment requirement is at + least as strict (as large) as that of every scalar type. .SH Notes Pointers returned by allocation functions such as std::malloc are suitably aligned - for any object, which means they are aligned at least as strict as std::max_align_t. - - std::max_align_t is usually synonymous with the largest scalar type, which is long - double on most platforms, and its alignment requirement is either 8 or 16. + for any object, which means they are aligned at least as strictly as + std::max_align_t. .SH Example - + // Run this code - #include #include + #include + int main() { std::cout << alignof(std::max_align_t) << '\\n'; @@ -30,10 +32,30 @@ 16 +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 17.2.4 Sizes, alignments, and offsets [support.types.layout] (p: 504-505) + * C++20 standard (ISO/IEC 14882:2020): + + * 17.2.4 Sizes, alignments, and offsets [support.types.layout] (p: 507-508) + * C++17 standard (ISO/IEC 14882:2017): + + * 21.2.4 Sizes, alignments, and offsets [support.types.layout] (p: 479) + * C++14 standard (ISO/IEC 14882:2014): + + * 18.2 Types [support.types] (p: 443-444) + * C++11 standard (ISO/IEC 14882:2011): + + * 18.2 Types [support.types] (p: 454-455) + .SH See also - alignof operator queries alignment requirements of a type \fI(since C++11)\fP - alignment_of obtains the type's alignment requirements - \fI(C++11)\fP \fI(class template)\fP - is_scalar checks if a type is scalar type - \fI(C++11)\fP \fI(class template)\fP + alignof operator\fI(C++11)\fP queries alignment requirements of a type + alignment_of obtains the type's alignment requirements + \fI(C++11)\fP \fI(class template)\fP + is_scalar checks if a type is a scalar type + \fI(C++11)\fP \fI(class template)\fP + C documentation for + max_align_t diff --git a/man/std::max_element.3 b/man/std::max_element.3 index 9f93bdd95..bf8760c2d 100644 --- a/man/std::max_element.3 +++ b/man/std::max_element.3 @@ -1,34 +1,72 @@ -.TH std::max_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::max_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::max_element \- std::max_element + .SH Synopsis Defined in header - template< class ForwardIt > \fB(1)\fP - ForwardIt max_element( ForwardIt first, ForwardIt last ); - template< class ForwardIt, class Compare > \fB(2)\fP - ForwardIt max_element( ForwardIt first, ForwardIt last, Compare comp ); + template< class ForwardIt > + ForwardIt max_element( ForwardIt first, ForwardIt last \fB(1)\fP (constexpr since C++17) + ); + template< class ExecutionPolicy, class ForwardIt > - Finds the greatest element in the range [first, last). The first version uses - operator< to compare the values, the second version uses the given comparison - function comp. + ForwardIt max_element( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last + ); + template< class ForwardIt, class Compare > + + ForwardIt max_element( ForwardIt first, ForwardIt last, \fB(3)\fP (constexpr since C++17) + + Compare comp ); + template< class ExecutionPolicy, class ForwardIt, class + Compare > + + ForwardIt max_element( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt last, + + Compare comp ); + + Finds the greatest element in the range [first, last). + + 1) Elements are compared using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are compared using the comparison function comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - forward iterators defining the range to examine + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if if *a is less than *b. + requirements of Compare) which returns true if the first argument is + less than the second. The signature of the comparison function should be equivalent to the following: - cmp - bool cmp(const Type1 &a, const Type2 &b); - - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of - them. + them. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value @@ -38,81 +76,111 @@ .SH Complexity - Exactly max(N-1,0) comparisons, where N = std::distance(first, last). + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize \\max(N-1,0)\\)max(N-1,0) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) Exactly \\(\\scriptsize \\max(N-1,0)\\)max(N-1,0) applications of the comparison + function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + max_element \fB(1)\fP template ForwardIt max_element(ForwardIt first, ForwardIt last) { - if (first == last) { + if (first == last) return last; - } + ForwardIt largest = first; - ++first; - for (; first != last; ++first) { - if (*largest < *first) { + + while (++first != last) + if (*largest < *first) largest = first; - } - } + return largest; } -.SH Second version + max_element \fB(3)\fP template - ForwardIt max_element(ForwardIt first, ForwardIt last, - Compare comp) + ForwardIt max_element(ForwardIt first, ForwardIt last, Compare comp) { - if (first == last) { + if (first == last) return last; - } + ForwardIt largest = first; - ++first; - for (; first != last; ++first) { - if (comp(*largest, *first)) { + + while(++first != last) + if (comp(*largest, *first)) largest = first; - } - } + return largest; } .SH Example - + // Run this code #include + #include #include #include - #include - - static bool abs_compare(int a, int b) - { - return (std::abs(a) < std::abs(b)); - } - + int main() { - std::vector v{ 3, 1, -14, 1, 5, 9 }; + std::vector v{3, 1, -14, 1, 5, 9, -14, 9}; std::vector::iterator result; - + result = std::max_element(v.begin(), v.end()); - std::cout << "max element at: " << std::distance(v.begin(), result) << '\\n'; - - result = std::max_element(v.begin(), v.end(), abs_compare); - std::cout << "max element (absolute) at: " << std::distance(v.begin(), result); + std::cout << "Max element found at index " + << std::distance(v.begin(), result) + << " has value " << *result << '\\n'; + + result = std::max_element(v.begin(), v.end(), [](int a, int b) + { + return std::abs(a) < std::abs(b); + }); + std::cout << "Absolute max element found at index " + << std::distance(v.begin(), result) + << " has value " << *result << '\\n'; } .SH Output: - max element at: 5 - max element (absolute) at: 2 + Max element found at index 5 has value 9 + Absolute max element found at index 2 has value -14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 212 C++98 the return value was not specified if returns last in this + [first, last) is empty case + LWG 2150 C++98 the iterator to the first non-smallest corrected the return + element was returned value .SH See also - min_element returns the smallest element in a range - \fI(function template)\fP - minmax_element returns the smallest and the largest element in a range - \fI(C++11)\fP \fI(function template)\fP - max returns the larger of two elements - \fI(function template)\fP + min_element returns the smallest element in a range + \fI(function template)\fP + minmax_element returns the smallest and the largest elements in a range + \fI(C++11)\fP \fI(function template)\fP + max returns the greater of the given values + \fI(function template)\fP + ranges::max_element returns the largest element in a range + (C++20) (niebloid) diff --git a/man/std::mblen.3 b/man/std::mblen.3 index 97362f949..f98e7b8a6 100644 --- a/man/std::mblen.3 +++ b/man/std::mblen.3 @@ -1,4 +1,7 @@ -.TH std::mblen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mblen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mblen \- std::mblen + .SH Synopsis Defined in header int mblen( const char* s, std::size_t n ); @@ -6,10 +9,10 @@ Determines the size, in bytes, of the multibyte character whose first byte is pointed to by s. - If s is a null pointer, resets the global conversion state and determined whether + If s is a null pointer, resets the global conversion state and determines whether shift sequences are used. - This function is equivalent to the call std::mbtowc((wchar_t*)0, s, n), except that + This function is equivalent to the call std::mbtowc(nullptr, s, n), except that conversion state of std::mbtowc is unaffected. .SH Notes @@ -29,7 +32,7 @@ If s is not a null pointer, returns the number of bytes that are contained in the multibyte character or -1 if the first bytes pointed to by s do not form a valid - multibyte character or 0 if s is pointing at the null charcter '\\0'. + multibyte character or 0 if s is pointing at the null character '\\0'. If s is a null pointer, resets its internal conversion state to represent the initial shift state and returns 0 if the current multibyte encoding is not @@ -38,54 +41,61 @@ .SH Example - + // Run this code #include - #include - #include #include + #include + #include #include - + #include + // the number of characters in a multibyte string is the sum of mblen()'s - // note: the simpler approach is std::mbstowcs(NULL, s.c_str(), s.size()) - std::size_t strlen_mb(const std::string& s) + // note: the simpler approach is std::mbstowcs(nullptr, s.c_str(), s.size()) + std::size_t strlen_mb(const std::string_view s) { + std::mblen(nullptr, 0); // reset the conversion state std::size_t result = 0; const char* ptr = s.data(); - const char* end = ptr + s.size(); - std::mblen(NULL, 0); // reset the conversion state - while (ptr < end) { - int next = std::mblen(ptr, end-ptr); - if (next == -1) { + for (const char* const end = ptr + s.size(); ptr < end; ++result) + { + const int next = std::mblen(ptr, end - ptr); + if (next == -1) throw std::runtime_error("strlen_mb(): conversion error"); - } ptr += next; - ++result; } return result; } - + + void dump_bytes(const std::string_view str) + { + std::cout << std::hex << std::uppercase << std::setfill('0'); + for (unsigned char c : str) + std::cout << std::setw(2) << static_cast(c) << ' '; + std::cout << std::dec << '\\n'; + } + int main() { // allow mblen() to work with UTF-8 multibyte encoding std::setlocale(LC_ALL, "en_US.utf8"); // UTF-8 narrow multibyte encoding - std::string str = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; - std::cout << str << " is " << str.size() << " bytes, but only " - << strlen_mb(str) << " characters\\n"; + const std::string_view str = "z\\u00df\\u6c34\\U0001f34c"; // or u8"zß水🍌" + std::cout << std::quoted(str) << " is " << strlen_mb(str) + << " characters, but as much as " << str.size() << " bytes: "; + dump_bytes(str); } -.SH Output: +.SH Possible output: - zß水𝄋 is 10 bytes, but only 4 characters + "zß水🍌" is 4 characters, but as much as 10 bytes: 7A C3 9F E6 B0 B4 F0 9F 8D 8C .SH See also mbtowc converts the next multibyte character to wide character - \fI(function)\fP + \fI(function)\fP mbrlen returns the number of bytes in the next multibyte character, given state - \fI(function)\fP + \fI(function)\fP C documentation for mblen diff --git a/man/std::mbrlen.3 b/man/std::mbrlen.3 index 369299854..f2de73c16 100644 --- a/man/std::mbrlen.3 +++ b/man/std::mbrlen.3 @@ -1,4 +1,7 @@ -.TH std::mbrlen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbrlen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbrlen \- std::mbrlen + .SH Synopsis Defined in header std::size_t mbrlen( const char* s, std::size_t n, std::mbstate_t* ps); @@ -6,9 +9,9 @@ Determines the size, in bytes, of the remainder of the multibyte character whose first byte is pointed to by s, given the current conversion state ps. - This function is equivalent to the call std::mbrtowc(nullptr, s, n, ps?ps:&internal) - for some hidden object internal of type std::mbstate_t, except that the expression - ps is evaluated only once. + This function is equivalent to the call std::mbrtowc(nullptr, s, n, ps ? ps : + &internal) for some hidden object internal of type std::mbstate_t, except that the + expression ps is evaluated only once. .SH Parameters @@ -20,42 +23,41 @@ 0 if the next n or fewer bytes complete the null character. - The number of bytes (between 1 and n) that complete a valid multibyte character + The number of bytes (between 1 and n) that complete a valid multibyte character. - (size_t)-1 if encoding error occurs + (size_t) - 1 if encoding error occurs. - (size_t)-2 if the next n bytes are part of a possibly valid multibyte character, - which is still incomplete after examining all n bytes + (size_t) - 2 if the next n bytes are part of a possibly valid multibyte character, + which is still incomplete after examining all n bytes. .SH Example - + // Run this code #include - #include - #include #include - + #include + #include + int main() { // allow mbrlen() to work with UTF-8 multibyte encoding std::setlocale(LC_ALL, "en_US.utf8"); // UTF-8 narrow multibyte encoding - std::string str = u8"水"; // or u8"\\u6c34" or "\\xe6\\xb0\\xb4" + std::string str = "水"; // or u8"\\u6c34" or "\\xe6\\xb0\\xb4" std::mbstate_t mb = std::mbstate_t(); int len1 = std::mbrlen(&str[0], 1, &mb); - if(len1 == -2) { + if (len1 == -2) std::cout << "The first 1 byte of " << str << " is an incomplete multibyte char (mbrlen returns -2)\\n"; - } - int len2 = std::mbrlen(&str[1], str.size()-1, &mb); - std::cout << "The remaining " << str.size()-1 << " bytes of " << str + int len2 = std::mbrlen(&str[1], str.size() - 1, &mb); + std::cout << "The remaining " << str.size() - 1 << " bytes of " << str << " hold " << len2 << " bytes of the multibyte character\\n"; std::cout << "Attempting to call mbrlen() in the middle of " << str << " while in initial shift state returns " << (int)mbrlen(&str[1], str.size(), &mb) << '\\n'; - + } .SH Output: @@ -67,11 +69,12 @@ .SH See also mbrtowc converts the next multibyte character to wide character, given state - \fI(function)\fP + \fI(function)\fP mblen returns the number of bytes in the next multibyte character - \fI(function)\fP - do_length calculates the length of the externT string that would be consumed by - \fB[virtual]\fP conversion into given internT buffer - \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + calculates the length of the ExternT string that would be consumed by + do_length conversion into given InternT buffer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbrlen diff --git a/man/std::mbrtoc16.3 b/man/std::mbrtoc16.3 index 033f08c99..a4812339f 100644 --- a/man/std::mbrtoc16.3 +++ b/man/std::mbrtoc16.3 @@ -1,4 +1,7 @@ -.TH std::mbrtoc16 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbrtoc16 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbrtoc16 \- std::mbrtoc16 + .SH Synopsis Defined in header std::size_t mbrtoc16( char16_t* pc16, @@ -8,8 +11,7 @@ std::mbstate_t* ps ); - Converts a narrow multibyte character to 16-bit character representation (typically, - UTF-16). + Converts a narrow multibyte character to UTF-16 character representation. If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes @@ -24,13 +26,13 @@ char16_t, without considering *s. If s is a null pointer, the values of n and pc16 are ignored and the call is - equivalent to std::mbrtoc16(NULL, "", 1, ps). + equivalent to std::mbrtoc16(nullptr, "", 1, ps). If the wide character produced is the null character, the conversion state *ps represents the initial shift state. - If the macro __STDC_UTF_16__ is defined, the 16-bit encoding used by this function - is UTF-16, otherwise it is implementation-defined. + The multibyte encoding used by this function is specified by the currently active C + locale. .SH Parameters @@ -45,22 +47,80 @@ The first of the following that applies: * 0 if the character converted from s (and stored in *pc16 if non-null) was the - null character + null character. * the number of bytes [1...n] of the multibyte character successfully converted - from s + from s. * -3 if the next char16_t from a multi-char16_t character (e.g. a surrogate pair) has now been written to *pc16. No bytes are processed from the input in this case. * -2 if the next n bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to *pc16. * -1 if encoding error occurs. Nothing is written to *pc16, the value EILSEQ is - stored in errno and the value if *ps is unspecified. + stored in errno and the value of *ps is unspecified. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + + std::string str = "z\\u00df\\u6c34\\U0001F34C"; // or u8"zß水🍌" + + std::cout << "Processing " << str.size() << " bytes: [ " << std::showbase; + for (unsigned char c: str) + std::cout << std::hex << +c << ' '; + std::cout << "]\\n"; + + std::mbstate_t state{}; // zero-initialized to initial state + char16_t c16; + const char *ptr = &str[0], *end = &str[0] + str.size(); + + while (std::size_t rc = std::mbrtoc16(&c16, ptr, end - ptr + 1, &state)) + { + std::cout << "Next UTF-16 char: " << std::hex + << static_cast(c16) << " obtained from "; + if (rc == (std::size_t)-3) + std::cout << "earlier surrogate pair\\n"; + else if (rc == (std::size_t) - 2) + break; + else if (rc == (std::size_t) - 1) + break; + else + { + std::cout << std::dec << rc << " bytes [ "; + for (std::size_t n = 0; n < rc; ++n) + std::cout << std::hex << +static_cast(ptr[n]) << ' '; + std::cout << "]\\n"; + ptr += rc; + } + } + } + +.SH Output: + + Processing 10 bytes: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c ] + Next UTF-16 char: 0x7a obtained from 1 bytes [ 0x7a ] + Next UTF-16 char: 0xdf obtained from 2 bytes [ 0xc3 0x9f ] + Next UTF-16 char: 0x6c34 obtained from 3 bytes [ 0xe6 0xb0 0xb4 ] + Next UTF-16 char: 0xd83c obtained from 4 bytes [ 0xf0 0x9f 0x8d 0x8c ] + Next UTF-16 char: 0xdf4c obtained from earlier surrogate pair .SH See also c16rtomb convert a 16-bit wide character to narrow multibyte string - \fI(C++11)\fP \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(C++11)\fP \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbrtoc16 diff --git a/man/std::mbrtoc32.3 b/man/std::mbrtoc32.3 index e45c5a5e8..95acfea53 100644 --- a/man/std::mbrtoc32.3 +++ b/man/std::mbrtoc32.3 @@ -1,4 +1,7 @@ -.TH std::mbrtoc32 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbrtoc32 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbrtoc32 \- std::mbrtoc32 + .SH Synopsis Defined in header std::size_t mbrtoc32( char32_t* pc32, @@ -8,8 +11,7 @@ std::mbstate_t* ps ); - Converts a narrow multibyte character to its 32-bit character representation - (typically, UTF-32). + Converts a narrow multibyte character to its UTF-32 character representation. If s is not a null pointer, inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s to determine the number of bytes @@ -24,13 +26,13 @@ without considering *s. If s is a null pointer, the values of n and pc32 are ignored and the call is - equivalent to std::mbrtoc32(NULL, "", 1, ps). + equivalent to std::mbrtoc32(nullptr, "", 1, ps). If the wide character produced is the null character, the conversion state *ps represents the initial shift state. - If the macro __STDC_UTF_32__ is defined, the 32-bit encoding used by this function - is UTF-32, otherwise it is implementation-defined. + The multibyte encoding used by this function is specified by the currently active C + locale. .SH Parameters @@ -45,21 +47,75 @@ The first of the following that applies: * 0 if the character converted from s (and stored in *pc32 if non-null) was the - null character + null character. * the number of bytes [1...n] of the multibyte character successfully converted - from s + from s. * -3 if the next char32_t from a multi-char32_t character has now been written to *pc32. No bytes are processed from the input in this case. * -2 if the next n bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to *pc32. * -1 if encoding error occurs. Nothing is written to *pc32, the value EILSEQ is - stored in errno and the value if *ps is unspecified. + stored in errno and the value of *ps is unspecified. + +.SH Examples + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + + std::string str = "z\\u00df\\u6c34\\U0001F34C"; // or u8"zß水🍌" + + std::cout << "Processing " << str.size() << " bytes: [ " << std::showbase; + for (unsigned char c : str) + std::cout << std::hex << +c << ' '; + std::cout << "]\\n"; + + std::mbstate_t state{}; // zero-initialized to initial state + char32_t c32; + const char* ptr = str.c_str(), *end = str.c_str() + str.size() + 1; + + while (std::size_t rc = std::mbrtoc32(&c32, ptr, end - ptr, &state)) + { + std::cout << "Next UTF-32 char: " << std::hex + << static_cast(c32) << " obtained from "; + assert(rc != (std::size_t) - 3); // no surrogates in UTF-32 + if (rc == (std::size_t) - 1) + break; + if (rc == (std::size_t) - 2) + break; + std::cout << std::dec << rc << " bytes [ "; + for (std::size_t n = 0; n < rc; ++n) + std::cout << std::hex << +static_cast(ptr[n]) << ' '; + std::cout << "]\\n"; + ptr += rc; + } + } + +.SH Output: + + Processing 10 bytes: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c ] + Next UTF-32 char: 0x7a obtained from 1 bytes [ 0x7a ] + Next UTF-32 char: 0xdf obtained from 2 bytes [ 0xc3 0x9f ] + Next UTF-32 char: 0x6c34 obtained from 3 bytes [ 0xe6 0xb0 0xb4 ] + Next UTF-32 char: 0x1f34c obtained from 4 bytes [ 0xf0 0x9f 0x8d 0x8c ] .SH See also c32rtomb convert a 32-bit wide character to narrow multibyte string - \fI(C++11)\fP \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(C++11)\fP \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbrtoc32 diff --git a/man/std::mbrtoc8.3 b/man/std::mbrtoc8.3 new file mode 100644 index 000000000..44dbc78e0 --- /dev/null +++ b/man/std::mbrtoc8.3 @@ -0,0 +1,74 @@ +.TH std::mbrtoc8 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbrtoc8 \- std::mbrtoc8 + +.SH Synopsis + Defined in header + std::size_t mbrtoc8( char8_t* pc8, + + const char* s, \fI(since C++20)\fP + std::size_t n, + + std::mbstate_t* ps ); + + Converts a narrow multibyte character to UTF-8 encoding. + + If s is not a null pointer, inspects at most n bytes of the multibyte character + string, beginning with the byte pointed to by s to determine the number of bytes + necessary to complete the next multibyte character (including any shift sequences). + If the function determines that the next multibyte character in s is complete and + valid, converts it to UTF-8 and stores the first UTF-8 code unit in *pc8 (if pc8 is + not null). + + If UTF-8 encoding of the multibyte character in *s consists of more than one UTF-8 + code unit, then after the first call to this function, *ps is updated in such a way + that the next call to mbrtoc8 will write out the additional UTF-8 code units, + without considering *s. + + If s is a null pointer, the values of n and pc8 are ignored and the call is + equivalent to std::mbrtoc8(nullptr, "", 1, ps). + + If UTF-8 code unit produced is u8'\\0', the conversion state *ps represents the + initial shift state. + + The multibyte encoding used by this function is specified by the currently active C + locale. + +.SH Parameters + + pc8 - pointer to the location where the resulting UTF-8 code units will be written + s - pointer to the multibyte character string used as input + n - limit on the number of bytes in s that can be examined + ps - pointer to the conversion state object used when interpreting the multibyte + string + +.SH Return value + + The first of the following that applies: + + * 0 if the character converted from s (and stored in *pc8 if non-null) was the + null character. + * the number of bytes [1...n] of the multibyte character successfully converted + from s. + * static_cast(-3) if the next UTF-8 code unit from a character whose + encoding consists of multiple code units has now been written to *pc8. No bytes + are processed from the input in this case. + * static_cast(-2) if the next n bytes constitute an incomplete, but + so far valid, multibyte character. Nothing is written to *pc8. + * static_cast(-1) if encoding error occurs. Nothing is written to + *pc8, the value EILSEQ is stored in errno and the value of *ps is unspecified. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + c8rtomb converts UTF-8 string to narrow multibyte encoding + (C++20) \fI(function)\fP + C documentation for + mbrtoc8 + +.SH Category: + * Todo no example diff --git a/man/std::mbrtowc.3 b/man/std::mbrtowc.3 index 40354fbd3..d8a556b3d 100644 --- a/man/std::mbrtowc.3 +++ b/man/std::mbrtowc.3 @@ -1,4 +1,7 @@ -.TH std::mbrtowc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbrtowc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbrtowc \- std::mbrtowc + .SH Synopsis Defined in header std::size_t mbrtowc( wchar_t* pwc, @@ -18,7 +21,7 @@ is not null). If s is a null pointer, the values of n and pwc are ignored and call is equivalent - to std::mbrtowc(NULL, "", 1, ps). + to std::mbrtowc(nullptr, "", 1, ps). If the wide character produced is the null character, the conversion state stored in *ps is the initial shift state. @@ -34,10 +37,10 @@ The first of the following that applies: - * 0 if the character converted from s (and stored in pwc if non-null) was the - null character + * 0 if the character converted from s (and stored in pwc if non-null) was the null + character. * the number of bytes [1...n] of the multibyte character successfully converted - from s + from s. * static_cast(-2) if the next n bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to *pwc. * static_cast(-1) if encoding error occurs. Nothing is written to @@ -46,31 +49,32 @@ .SH Example - + // Run this code - #include #include #include #include - + #include + void print_mb(const char* ptr) { std::mbstate_t state = std::mbstate_t(); // initial state const char* end = ptr + std::strlen(ptr); int len; wchar_t wc; - while((len = std::mbrtowc(&wc, ptr, end-ptr, &state)) > 0) { + while ((len = std::mbrtowc(&wc, ptr, end-ptr, &state)) > 0) + { std::wcout << "Next " << len << " bytes are the character " << wc << '\\n'; ptr += len; } } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); // UTF-8 narrow multibyte encoding - const char* str = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" + const char* str = "z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; print_mb(str); } @@ -85,10 +89,11 @@ .SH See also mbtowc converts the next multibyte character to wide character - \fI(function)\fP + \fI(function)\fP wcrtomb converts a wide character to its multibyte representation, given state - \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbrtowc diff --git a/man/std::mbsinit.3 b/man/std::mbsinit.3 index a509b4513..6d9a2c5f0 100644 --- a/man/std::mbsinit.3 +++ b/man/std::mbsinit.3 @@ -1,4 +1,7 @@ -.TH std::mbsinit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbsinit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbsinit \- std::mbsinit + .SH Synopsis Defined in header int mbsinit( const std::mbstate_t* ps); @@ -18,37 +21,35 @@ .SH Return value - 0 if ps is not a null pointer and does not reporesent the initial conversion - state, nonzero value otherwise. + 0 if ps is not a null pointer and does not represent the initial conversion state, + nonzero value otherwise. .SH Example - + // Run this code #include - #include - #include #include - + #include + #include + int main() { // allow mbrlen() to work with UTF-8 multibyte encoding std::setlocale(LC_ALL, "en_US.utf8"); // UTF-8 narrow multibyte encoding - std::string str = u8"水"; // or u8"\\u6c34" or "\\xe6\\xb0\\xb4" + std::string str = "水"; // or u8"\\u6c34" or "\\xe6\\xb0\\xb4" std::mbstate_t mb = std::mbstate_t(); (void)std::mbrlen(&str[0], 1, &mb); - if (!std::mbsinit(&mb)) { + if (!std::mbsinit(&mb)) std::cout << "After processing the first 1 byte of " << str << " the conversion state is not initial\\n"; - } - - (void)std::mbrlen(&str[1], str.size()-1, &mb); - if (std::mbsinit(&mb)) { + + (void)std::mbrlen(&str[1], str.size() - 1, &mb); + if (std::mbsinit(&mb)) std::cout << "After processing the remaining 2 bytes of " << str << ", the conversion state is initial conversion state\\n"; - } } .SH Output: @@ -60,6 +61,6 @@ conversion state information necessary to iterate multibyte character mbstate_t strings - \fI(class)\fP + \fI(class)\fP C documentation for mbsinit diff --git a/man/std::mbsrtowcs.3 b/man/std::mbsrtowcs.3 index 6b6bdc457..03c720035 100644 --- a/man/std::mbsrtowcs.3 +++ b/man/std::mbsrtowcs.3 @@ -1,4 +1,7 @@ -.TH std::mbsrtowcs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbsrtowcs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbsrtowcs \- std::mbsrtowcs + .SH Synopsis Defined in header std::size_t mbsrtowcs( wchar_t* dst, @@ -17,14 +20,14 @@ Each multibyte character is converted as if by a call to std::mbrtowc. The conversion stops if: - * The multibyte null character was converted and stored. src is set to NULL and - *ps represents the initial shift state. + * The multibyte null character was converted and stored. src is set to a null + pointer and *ps represents the initial shift state. * An invalid multibyte character (according to the current C locale) was encountered. src is set to point at the beginning of the first unconverted multibyte character. - * the next wide character to be stored would exceed len. src is set to point at + * The next wide character to be stored would exceed len. src is set to point at the beginning of the first unconverted multibyte character. This condition is - not checked if dst==NULL. + not checked if dst is a null pointer. .SH Parameters @@ -36,53 +39,58 @@ .SH Return value On success, returns the number of wide characters, excluding the terminating L'\\0', - written to the character array.. If dst==NULL, returns the number of wide characters - that would have been written given unlimited length. + written to the character array. If dst is a null pointer, returns the number of wide + characters that would have been written given unlimited length. On conversion error (if invalid multibyte character was encountered), returns static_cast(-1), stores EILSEQ in errno, and leaves *ps in unspecified state. +.SH Notes + + This function moves the src pointer to the end of the converted multibyte string. + This doesn't happen if dst is a null pointer. + .SH Example - + // Run this code - #include - #include #include #include - + #include + #include + void print_as_wide(const char* mbstr) { std::mbstate_t state = std::mbstate_t(); - int len = 1 + std::mbsrtowcs(NULL, &mbstr, 0, &state); + std::size_t len = 1 + std::mbsrtowcs(nullptr, &mbstr, 0, &state); std::vector wstr(len); std::mbsrtowcs(&wstr[0], &mbstr, wstr.size(), &state); std::wcout << "Wide string: " << &wstr[0] << '\\n' << "The length, including '\\\\0': " << wstr.size() << '\\n'; } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); - const char* mbstr = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + const char* mbstr = "z\\u00df\\u6c34\\U0001f34c"; // or u8"zß水🍌" print_as_wide(mbstr); } .SH Output: - Wide string: zß水𝄋 + Wide string: zß水🍌 The length, including '\\0': 5 .SH See also mbrtowc converts the next multibyte character to wide character, given state - \fI(function)\fP + \fI(function)\fP wcsrtombs converts a wide string to narrow multibyte character string, given state - \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbsrtowcs diff --git a/man/std::mbstate_t.3 b/man/std::mbstate_t.3 index 414044209..339f74115 100644 --- a/man/std::mbstate_t.3 +++ b/man/std::mbstate_t.3 @@ -1,5 +1,9 @@ -.TH std::mbstate_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbstate_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbstate_t \- std::mbstate_t + .SH Synopsis + Defined in header \fI(since C++17)\fP Defined in header struct mbstate_t; @@ -15,11 +19,13 @@ shift state. The following functions should not be called from multiple threads without - synchronization with the std::mbstate_t* argument of NULL due to possible data - races: std::mbrlen, std::mbrtowc, std::mbsrtowc, std::mbtowc, std::wcrtomb, - std::wcsrtomb, std::wctomb. + synchronization with the std::mbstate_t* argument of a null pointer due to possible + data races: std::mbrlen, std::mbrtowc, std::mbsrtowcs, std::mbtowc, std::wcrtomb, + std::wcsrtombs, std::wctomb. .SH See also - mbsinit checks if the mbstate_t object represents initial shift state - \fI(function)\fP + mbsinit checks if the std::mbstate_t object represents initial shift state + \fI(function)\fP + C documentation for + mbstate_t diff --git a/man/std::mbstowcs.3 b/man/std::mbstowcs.3 index ba717a339..ecc657a92 100644 --- a/man/std::mbstowcs.3 +++ b/man/std::mbstowcs.3 @@ -1,7 +1,10 @@ -.TH std::mbstowcs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbstowcs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbstowcs \- std::mbstowcs + .SH Synopsis Defined in header - std::size_t mbstowcs( wchar_t* dst, const char* src, std::size_t len) + std::size_t mbstowcs( wchar_t* dst, const char* src, std::size_t len ); Converts a multibyte character string from the array whose first element is pointed to by src to its wide character representation. Converted characters are stored in @@ -36,21 +39,24 @@ On success, returns the number of wide characters, excluding the terminating L'\\0', written to the destination array. - On conversion error (if invalid multibyte character was encountered), returns -1. + On conversion error (if invalid multibyte character was encountered), returns + static_cast (-1). .SH Example - + // Run this code - #include #include #include + #include + int main() { std::setlocale(LC_ALL, "en_US.utf8"); - const char* mbstr = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + std::wcout.imbue(std::locale("en_US.utf8")); + const char* mbstr = "z\\u00df\\u6c34\\U0001f34c"; // or u8"zß水🍌" + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c"; wchar_t wstr[5]; std::mbstowcs(wstr, mbstr, 5); std::wcout << "wide string: " << wstr << '\\n'; @@ -58,15 +64,16 @@ .SH Output: - wide string: zß水𝄋 + wide string: zß水🍌 .SH See also mbsrtowcs converts a narrow multibyte character string to wide string, given state - \fI(function)\fP + \fI(function)\fP wcstombs converts a wide string to narrow multibyte character string - \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbstowcs diff --git a/man/std::mbtowc.3 b/man/std::mbtowc.3 index 8368d224b..f96ce5f2c 100644 --- a/man/std::mbtowc.3 +++ b/man/std::mbtowc.3 @@ -1,7 +1,10 @@ -.TH std::mbtowc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mbtowc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mbtowc \- std::mbtowc + .SH Synopsis Defined in header - int mbtowc( wchar_t* pwc, const char* s, std::size_t n ) + int mbtowc( wchar_t* pwc, const char* s, std::size_t n ); Converts a multibyte character whose first byte is pointed to by s to a wide character, written to *pwc if pwc is not null. @@ -19,7 +22,7 @@ If s is not a null pointer, returns the number of bytes that are contained in the multibyte character or -1 if the first bytes pointed to by s do not form a valid - multibyte character or 0 if s is pointing at the null charcter '\\0'. + multibyte character or 0 if s is pointing at the null character '\\0'. If s is a null pointer, resets its internal conversion state to represent the initial shift state and returns 0 if the current multibyte encoding is not @@ -36,31 +39,30 @@ .SH Example - + // Run this code - #include #include - #include #include - + #include + #include + int print_mb(const char* ptr) { - std::mbtowc(NULL, 0, 0); // reset the conversion state + std::mbtowc(nullptr, 0, 0); // reset the conversion state const char* end = ptr + std::strlen(ptr); - int ret; - for (wchar_t wc; (ret = std::mbtowc(&wc, ptr, end-ptr)) > 0; ptr+=ret) { + int ret{}; + for (wchar_t wc; (ret = std::mbtowc(&wc, ptr, end - ptr)) > 0; ptr += ret) std::wcout << wc; - } std::wcout << '\\n'; return ret; } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); // UTF-8 narrow multibyte encoding - const char* str = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" + const char* str = "z\\u00df\\u6c34\\U0001d10b"; // or "zß水𝄋" // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; print_mb(str); } @@ -72,10 +74,11 @@ .SH See also mbrtowc converts the next multibyte character to wide character, given state - \fI(function)\fP + \fI(function)\fP mblen returns the number of bytes in the next multibyte character - \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for mbtowc diff --git a/man/std::mdspan.3 b/man/std::mdspan.3 new file mode 100644 index 000000000..9573465a7 --- /dev/null +++ b/man/std::mdspan.3 @@ -0,0 +1,213 @@ +.TH std::mdspan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan \- std::mdspan + +.SH Synopsis + Defined in header + template< + + class T, + class Extents, (since C++23) + class LayoutPolicy = std::layout_right, + class AccessorPolicy = std::default_accessor + + > class mdspan; + + std::mdspan is a view into a contiguous sequence of objects that reinterprets it as + a multidimensional array. + + Each specialization MDS of mdspan models copyable and satisfies: + + * std::is_nothrow_move_constructible_v is true, + * std::is_nothrow_move_assignable_v is true, and + * std::is_nothrow_swappable_v is true. + + A specialization of mdspan is a TriviallyCopyable type if its accessor_type, + mapping_type and data_handle_type are TriviallyCopyable types. + +.SH Template parameters + + T - element type; a complete object type that is neither an abstract + class type nor an array type. + Extents - specifies number of dimensions, their sizes, and which are known at + compile time. Must be a specialization of std::extents. + LayoutPolicy - specifies how to convert multidimensional index to underlying 1D + index (column-major 3D array, symmetric triangular 2D matrix, etc). + specifies how to convert underlying 1D index to a reference to T. + AccessorPolicy - Must satisfy the constraint that std::is_same_v is true. + + This section is incomplete + Reason: add the requirement of layout policy and accessor policy. + +.SH Member types + + Member type Definition + extents_type Extents + layout_type LayoutPolicy + accessor_type AccessorPolicy + mapping_type LayoutPolicy::mapping + element_type T + value_type std::remove_cv_t + index_type Extents::index_type + size_type Extents::size_type + rank_type Extents::rank_type + data_handle_type AccessorPolicy::data_handle_type + reference AccessorPolicy::reference + +.SH Member objects + + Member name Definition + acc_ (private) The accessor of type accessor_type + (exposition-only member object*) + map_ (private) The layout mapping of type mapping_type + (exposition-only member object*) + ptr_ (private) The underlying data handle of type data_handle_type + (exposition-only member object*) + +.SH Member functions + + constructor constructs an mdspan + \fI(public member function)\fP + operator= assigns an mdspan + \fI(public member function)\fP +.SH Element access + operator[] accesses an element at the specified multidimensional index + \fI(public member function)\fP +.SH Observers + size returns the size of the multidimensional index space + \fI(public member function)\fP + empty checks if the size of the index space is zero + \fI(public member function)\fP + stride obtains the stride along the specified dimension + \fI(public member function)\fP + extents obtains the extents object + \fI(public member function)\fP + data_handle obtains the pointer to the underlying 1D sequence + \fI(public member function)\fP + mapping obtains the mapping object + \fI(public member function)\fP + accessor obtains the accessor policy object + \fI(public member function)\fP + determines if this mdspan's mapping is unique (every + is_unique combination of indices maps to a different underlying element) + \fI(public member function)\fP + determines if this mdspan's mapping is exhaustive (every + is_exhaustive underlying element can be accessed with some combination of + indices) + \fI(public member function)\fP + determines if this mdspan's mapping is strided (in each + is_strided dimension, incrementing an index jumps over the same number of + underlying elements every time) + \fI(public member function)\fP + is_always_unique determines if this mdspan's layout mapping is always unique + \fB[static]\fP \fI(public static member function)\fP + is_always_exhaustive determines if this mdspan's layout mapping is always exhaustive + \fB[static]\fP \fI(public static member function)\fP + is_always_strided determines if this mdspan's layout mapping is always strided + \fB[static]\fP \fI(public static member function)\fP + +.SH Non-member functions + + std::swap(std::mdspan) specializes the std::swap algorithm for mdspan + (C++23) \fI(function template)\fP + Subviews + submdspan_extents creates new extents from the existing extents and slice + (C++26) specifiers + \fI(function template)\fP + submdspan returns a view of a subset of an existing mdspan + (C++26) \fI(function template)\fP + + Helper types and templates + + extents a descriptor of a multidimensional index space of some rank + (C++23) \fI(class template)\fP + dextents convenience alias template for an all-dynamic std::extents + (C++23) (alias template) + layout_right row-major multidimensional array layout mapping policy; + (C++23) rightmost extent has stride 1 + \fI(class)\fP + layout_left column-major multidimensional array layout mapping policy; + (C++23) leftmost extent has stride 1 + \fI(class)\fP + layout_stride a layout mapping policy with user-defined strides + (C++23) \fI(class)\fP + default_accessor a type for indexed access to elements of mdspan + (C++23) \fI(class template)\fP + Subviews helpers + full_extent a slice specifier tag describing full range of indices in + full_extent_t the specified extent + (C++26) (tag) + strided_slice a slice specifier representing a set of regularly spaced + (C++26) indices as indicated by an offset, an extent, and a stride + \fI(class template)\fP + submdspan_mapping_result a return type of the overloads of submdspan_mapping + (C++26) \fI(class template)\fP + + Deduction guides + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_mdspan 202207L (C++23) std::mdspan + __cpp_lib_submdspan 202306L (C++26) std::submdspan + +.SH Example + + Can be previewed on Compiler Explorer. + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}; + + // View data as contiguous memory representing 2 rows of 6 ints each + auto ms2 = std::mdspan(v.data(), 2, 6); + // View the same data as a 3D array 2 x 3 x 2 + auto ms3 = std::mdspan(v.data(), 2, 3, 2); + + // Write data using 2D view + for (std::size_t i = 0; i != ms2.extent(0); i++) + for (std::size_t j = 0; j != ms2.extent(1); j++) + ms2[i, j] = i * 1000 + j; + + // Read back using 3D view + for (std::size_t i = 0; i != ms3.extent(0); i++) + { + std::println("slice @ i = {}", i); + for (std::size_t j = 0; j != ms3.extent(1); j++) + { + for (std::size_t k = 0; k != ms3.extent(2); k++) + std::print("{} ", ms3[i, j, k]); + std::println(""); + } + } + } + +.SH Output: + + slice @ i = 0 + 0 1 + 2 3 + 4 5 + slice @ i = 1 + 1000 1001 + 1002 1003 + 1004 1005 + +.SH See also + + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + valarray numeric arrays, array masks and array slices + \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::mdspan::accessor.3 b/man/std::mdspan::accessor.3 new file mode 100644 index 000000000..f33663378 --- /dev/null +++ b/man/std::mdspan::accessor.3 @@ -0,0 +1,29 @@ +.TH std::mdspan::accessor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::accessor \- std::mdspan::accessor + +.SH Synopsis + constexpr const accessor_type& accessor() const noexcept; (since C++23) + + Returns a const reference to the accessor acc_. Equivalent to return acc_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + See above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::data_handle.3 b/man/std::mdspan::data_handle.3 new file mode 100644 index 000000000..af588140d --- /dev/null +++ b/man/std::mdspan::data_handle.3 @@ -0,0 +1,29 @@ +.TH std::mdspan::data_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::data_handle \- std::mdspan::data_handle + +.SH Synopsis + constexpr const data_handle_type& data_handle() const noexcept; (since C++23) + + Returns the underlying data handle of data_handle_type. Equivalent to return ptr_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A const reference to the underlying data handle. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::empty.3 b/man/std::mdspan::empty.3 new file mode 100644 index 000000000..e2c6ab93b --- /dev/null +++ b/man/std::mdspan::empty.3 @@ -0,0 +1,30 @@ +.TH std::mdspan::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::empty \- std::mdspan::empty + +.SH Synopsis + [[nodiscard]] constexpr bool empty() const noexcept; (since C++23) + + Check if the mdspan is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the size of the multidimensional index space extents() is 0, otherwise + false. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::extents.3 b/man/std::mdspan::extents.3 new file mode 100644 index 000000000..0ef7e2771 --- /dev/null +++ b/man/std::mdspan::extents.3 @@ -0,0 +1,30 @@ +.TH std::mdspan::extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::extents \- std::mdspan::extents + +.SH Synopsis + constexpr const extents_type& extents() const noexcept; (since C++23) + + Returns a const reference to the extents of the layout mapping map_. Equivalent to + return map_.extents();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A const reference to the extents. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::is_unique,.3 b/man/std::mdspan::is_unique,.3 new file mode 100644 index 000000000..60c33157a --- /dev/null +++ b/man/std::mdspan::is_unique,.3 @@ -0,0 +1,51 @@ +.TH std::mdspan::is_unique, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::is_unique, \- std::mdspan::is_unique, + +.SH Synopsis + std::mdspan::is_strided, + std::mdspan::is_always_unique, + std::mdspan::is_always_exhaustive, + std::mdspan::is_always_strided + + Defined in header + constexpr bool is_unique() const; \fB(1)\fP (since C++23) + constexpr bool is_exhaustive() const; \fB(2)\fP (since C++23) + constexpr bool is_strided() const; \fB(3)\fP (since C++23) + static member functions + static constexpr bool is_always_unique(); \fB(4)\fP (since C++23) + static constexpr bool is_always_exhaustive(); \fB(5)\fP (since C++23) + static constexpr bool is_always_strided(); \fB(6)\fP (since C++23) + + Check if (1-3) the layout mapping map_ or (4-6) its type mapping_type satisfies some + traits. + + 1-3) Let func be \fB(1)\fP is_unique, \fB(2)\fP is_exhaustive, or \fB(3)\fP is_strided, then it's + equivalent to return map_.func();. + 4-6) Let func be \fB(4)\fP is_always_unique, \fB(5)\fP is_always_exhaustive, or \fB(6)\fP + is_always_strided, then it's equivalent to return mapping_type::func();. + + This section is incomplete + Reason: add hyperlink to layout.reqmts(yet has not been created). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + See above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo with reason + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::mapping.3 b/man/std::mdspan::mapping.3 new file mode 100644 index 000000000..755954dba --- /dev/null +++ b/man/std::mdspan::mapping.3 @@ -0,0 +1,29 @@ +.TH std::mdspan::mapping 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::mapping \- std::mdspan::mapping + +.SH Synopsis + constexpr const mapping_type& mapping() const noexcept; (since C++23) + + Returns the layout mapping. Equivalent to return map_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A const reference to the underlying layout mapping object of mapping_type. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::mdspan.3 b/man/std::mdspan::mdspan.3 new file mode 100644 index 000000000..03c83126c --- /dev/null +++ b/man/std::mdspan::mdspan.3 @@ -0,0 +1,155 @@ +.TH std::mdspan::mdspan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::mdspan \- std::mdspan::mdspan + +.SH Synopsis + constexpr mdspan(); \fB(1)\fP (since C++23) + template< class... OtherIndexTypes > + constexpr explicit mdspan( data_handle_type p, \fB(2)\fP (since C++23) + OtherIndexTypes... exts ); + template< class OtherIndexType, std::size_t N > + + constexpr explicit(N != rank_dynamic()) \fB(3)\fP (since C++23) + + mdspan( data_handle_type p, std::span + exts ); + template< class OtherIndexType, std::size_t N > + + constexpr explicit(N != rank_dynamic()) \fB(4)\fP (since C++23) + + mdspan( data_handle_type p, const + std::array& exts ); + constexpr mdspan( data_handle_type p, const extents_type& ext ); \fB(5)\fP (since C++23) + constexpr mdspan( data_handle_type p, const mapping_type& m ); \fB(6)\fP (since C++23) + constexpr mdspan( data_handle_type p, const mapping_type& m, \fB(7)\fP (since C++23) + const accessor_type& a ); + template< class OtherElementType, class OtherExtents, + + class OtherLayoutPolicy, class OtherAccessor > + constexpr explicit(/* see below */) \fB(8)\fP (since C++23) + mdspan( const mdspan& + other ); + constexpr mdspan( const mdspan& rhs ) = default; \fB(9)\fP (since C++23) + constexpr mdspan( mdspan&& rhs ) = default; \fB(10)\fP (since C++23) + + Constructs an mdspan, optionally using user-supplied data handle p, layout mapping + m, and accessor a. If extents exts or ext are supplied, they are converted to + extents_type and used to initialize the layout mapping. + + 1) Constructs an empty mdspan. Value-initializes ptr_, map_, and acc_. + * The behavior is undefined if [0, map_.required_span_size()) is not an accessible + range of ptr_ and acc_ for the values of map_ and acc_ after the invocation of + this constructor. + * This overload participates in overload resolution only if + + * rank_dynamic() > 0 is true, + * std::is_default_constructible_v is true, + * std::is_default_constructible_v is true, and + * std::is_default_constructible_v is true. + 2) Constructs an mdspan over the underlying data referred by p with extents + represented by exts.... Value-initializes acc_, direct-non-list-initializes ptr_ + with std::move(p) and map_ with + extents_type(static_cast(std::move(exts))...). + * The behavior is undefined if [0, map_.required_span_size()) is not an accessible + range of ptr_ and acc_ for the values of map_ and acc_ after the invocation of + this constructor. + * Let N be sizeof...(OtherIndexTypes). This overload participates in overload + resolution only if + + * (std::is_convertible_v && ...) is true, + * (std::is_nothrow_constructible && ...) is true, + * N == rank() || N == rank_dynamic() is true, + * std::is_constructible_v is true, and + * std::is_default_constructible_v is true. + 3,4) Constructs an mdspan over the underlying data referred by p with extents + represented by pack exts. Value-initializes acc_, direct-non-list-initializes ptr_ + with std::move(p) and map_ with extents_type(exts). + * The behavior is undefined if [0, map_.required_span_size()) is not an accessible + range of ptr_ and acc_ for the values of map_ and acc_ after the invocation of + this constructor. + * This overload participates in overload resolution only if + + * std::is_convertible_v is true, + * std::is_nothrow_constructible is true, + * N == rank() || N == rank_dynamic() is true, + * std::is_constructible_v is true, and + * std::is_default_constructible_v is true. + 5) Constructs an mdspan over the underlying data referred by p with extents + represented by ext. Value-initializes acc_, direct-non-list-initializes ptr_ with + std::move(p) and map_ with exts. + * The behavior is undefined if [0, map_.required_span_size()) is not an accessible + range of p and acc_ for the values of map_ and acc_ after the invocation of this + constructor. + * This overload participates in overload resolution only if + + * std::is_constructible_v is true, and + * std::is_default_constructible_v is true. + 6) Constructs an mdspan over the underlying data referred by p with layout mapping + m. Value-initializes acc_, direct-non-list-initializes ptr_ with std::move(p) and + map_ with m. + * The behavior is undefined if [0, m.required_span_size()) is not an accessible + range of p and acc_ for the values of acc_ after the invocation of this + constructor. + * This overload participates in overload resolution only if + std::is_default_constructible_v is true. + 7) Constructs an mdspan over the underlying data referred by p with layout mapping m + and accessor a. Direct-non-list-initializes ptr_ with std::move(p), map_ with m and + acc_ with a. + * The behavior is undefined if [0, m.required_span_size()) is not an accessible + range of p and a after the invocation of this constructor. + 8) Converting constructor from another mdspan. Direct-non-list-initializes ptr_ with + other.ptr_, map_ with other.map_ and acc_ with other.acc_. + * The behavior is undefined if : + + * [0, map_.required_span_size()) is not an accessible range of ptr_ and acc_ for + the values of map_ and acc_ after the invocation of this constructor, or + * for each rank index r of extents_type, extents_type::static_extent(r) == + std::dynamic_extent + || extents_type::static_extent(r) == other.extent(r) is false. + * This overload participates in overload resolution only if + + * std::is_constructible_v&> is true, and + * std::is_constructible_v is true. + * The program is ill-formed if: + + * std::is_constructible_v is false, or + * std::is_constructible_v is false. + * The expression inside explicit is equivalent to: !std::is_convertible_v&, mapping_type> + || !std::is_convertible_v + 9) Defaulted copy constructor. + 10) Defaulted move constructor. + +.SH Parameters + + p - a handle to the underlying data + m - a layout mapping + a - an accessor + ext - a std::extents object + exts - represents a multi-dimensional extents + other - another mdspan to convert from + rhs - another mdspan to copy or move from + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 24.7.3.6.2 Constructors [mdspan.mdspan.cons] + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::operator=.3 b/man/std::mdspan::operator=.3 new file mode 100644 index 000000000..a3144e079 --- /dev/null +++ b/man/std::mdspan::operator=.3 @@ -0,0 +1,34 @@ +.TH std::mdspan::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::operator= \- std::mdspan::operator= + +.SH Synopsis + Defined in header + constexpr mdspan& operator=( const mdspan& rhs ) = default; \fB(1)\fP (since C++23) + constexpr mdspan& operator=( mdspan&& rhs ) = default; \fB(2)\fP (since C++23) + + Assigns rhs to *this with + + 1) defaulted copy assignment operator, + 2) defaulted move assignment operator. + +.SH Parameters + + other - another mdspan to copy or move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::operator[].3 b/man/std::mdspan::operator[].3 new file mode 100644 index 000000000..c6a7440b2 --- /dev/null +++ b/man/std::mdspan::operator[].3 @@ -0,0 +1,67 @@ +.TH std::mdspan::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::operator[] \- std::mdspan::operator[] + +.SH Synopsis + template< class... OtherIndexTypes > + constexpr reference operator[]( OtherIndexTypes... indices ) \fB(1)\fP (since C++23) + const; + template< class OtherIndexType > + + constexpr reference operator[] \fB(2)\fP (since C++23) + + ( std::span indices ) const; + template< class OtherIndexType > + + constexpr reference operator[] \fB(3)\fP (since C++23) + + ( const std::array& indices ) const; + + Returns a reference to the indices^th element of the mdspan. + + 1) Equivalent to return acc_.access(ptr_, + map_(static_cast(std::move(indices))...));. + This overload participates in overload resolution only if: + * (std::is_convertible_v && ...) is true, + * (std::is_nothrow_constructible_v && ...) is true, + and + * sizeof...(OtherIndexTypes) == rank() is true. + Let I be extents_type::index-cast(std::move(indices)). Then the behavior is + undefined if I is not a multidimensional index in extents(), i.e., map_(I) < + map_.required_span_size() is false. + 2,3) Let P be a parameter pack such that std::is_same_v, + index_sequence> is true, then the operator is equivalent to return + operator[](extents_type::index-cast(std::as_const(indices[P]))...);. + This overload participates in overload resolution only if: + * std::is_convertible_v is true, and + * std::is_nothrow_constructible_v is true. + +.SH Parameters + + indices - the indices of the element to access + +.SH Return value + + A reference to the element. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3974 C++23 overloads (2,3) did not apply applies + extents_type::index-cast + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::size.3 b/man/std::mdspan::size.3 new file mode 100644 index 000000000..51b92ffce --- /dev/null +++ b/man/std::mdspan::size.3 @@ -0,0 +1,34 @@ +.TH std::mdspan::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::size \- std::mdspan::size + +.SH Synopsis + constexpr size_type size() const noexcept; (since C++23) + + Returns the number of elements in mdspan. + + Equivalent to extents().fwd-prod-of-extents(rank()). + + If the size of the multidimensional index space extents() is not representable as a + value of type size_type, the behavior of the program is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mdspan::stride.3 b/man/std::mdspan::stride.3 new file mode 100644 index 000000000..9e9ee3985 --- /dev/null +++ b/man/std::mdspan::stride.3 @@ -0,0 +1,30 @@ +.TH std::mdspan::stride 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mdspan::stride \- std::mdspan::stride + +.SH Synopsis + constexpr index_type stride( rank_type r ) const; (since C++23) + + Returns the stride of the layout mapping map_ in r^th dimension. Equivalent to + return map_.stride(r);. + +.SH Parameters + + r - the index of the dimension + +.SH Return value + + The stride. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::mem_fn.3 b/man/std::mem_fn.3 index 64133002c..d3993f07a 100644 --- a/man/std::mem_fn.3 +++ b/man/std::mem_fn.3 @@ -1,193 +1,166 @@ -.TH std::mem_fn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mem_fn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mem_fn \- std::mem_fn + .SH Synopsis Defined in header - template< class R, class T > \fB(1)\fP \fI(since C++11)\fP - /*unspecified*/ mem_fn(R T::* pm); - template< class R, class T, class... Args > - - /*unspecified*/ mem_fn(R (T::* pm)(Args...)); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) const); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) volatile); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) const volatile); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) &); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) const &); \fB(2)\fP \fI(since C++11)\fP - template< class R, class T, class... Args > \fI(until C++14)\fP - /*unspecified*/ mem_fn(R (T::* pm)(Args...) volatile &); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) const volatile &); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) &&); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) const &&); - template< class R, class T, class... Args > - /*unspecified*/ mem_fn(R (T::* pm)(Args...) volatile &&); - template< class R, class T, class... Args > - - /*unspecified*/ mem_fn(R (T::* pm)(Args...) const volatile &&); + template< class M, class T > \fI(since C++11)\fP + /* unspecified */ mem_fn( M T::* pm ) noexcept; \fI(until C++20)\fP + template< class M, class T > \fI(since C++20)\fP + constexpr /* unspecified */ mem_fn( M T::* pm ) noexcept; Function template std::mem_fn generates wrapper objects for pointers to members, which can store, copy, and invoke a pointer to member. Both references and pointers (including smart pointers) to an object can be used when invoking a std::mem_fn. - The overloads \fB(2)\fP were introduced in C++11 but removed in C++14 as defect #2048 - .SH Parameters pm - pointer to member that will be wrapped .SH Return value - std::mem_fn returns a call wrapper of unspecified type that has the following + std::mem_fn returns a call wrapper fn of unspecified type that has the following members: - std::mem_fn Return type +std::mem_fn return type .SH Member types - type definition - result_type the return type of pm if pm is a pointer to member function, - not defined for pointer to member object - argument_type T*, possibly cv-qualified, if pm is a pointer to member - function taking no arguments - first_argument_type T* if pm is a pointer to member function taking one argument - second_argument_type T1 if pm is a pointer to member function taking one argument of - type T1 + type definition + the return type of pm if pm + result_type(deprecated in C++17) is a pointer to member + function, not defined for + pointer to member object + T*, possibly cv-qualified, \fI(until C++20)\fP + argument_type(deprecated in C++17) if pm is a pointer to member + function taking no arguments + T* if pm is a pointer to + first_argument_type(deprecated in C++17) member function taking one + argument + T1 if pm is a pointer to + second_argument_type(deprecated in C++17) member function taking one + argument of type T1 .SH Member function - operator() invokes the target on a specified object, with optional parameters - \fI(public member function)\fP + template< class... Args > + + /* see below */ operator()(Args&&... args) /* cvref-qualifiers */ \fI(until C++20)\fP + + noexcept(/* see below */); + template< class... Args > + + constexpr /* see below */ operator()(Args&&... args) /* \fI(since C++20)\fP + cvref-qualifiers */ + + noexcept(/* see below */); + + The expression fn(args) is equivalent to INVOKE(pmd, args), where pmd is the + Callable object held by fn, it is of type M T::* and is direct-non-list-initialized + with pm. -.SH Exceptions + Thus, the return type of operator() is std::result_of::type + or equivalently std::invoke_result_t, and the value in + noexcept specifier is equal to std::is_nothrow_invocable_v) + \fI(since C++17)\fP. - None. + Each argument in args is perfectly forwarded, as if by std::forward(args).... -.SH Example 1 +.SH Example + + Use std::mem_fn to store and execute a member function and a member object: - Use mem_fn to store and execute a member function and a member object: - // Run this code #include #include - - struct Foo { - void display_greeting() { + #include + + struct Foo + { + void display_greeting() + { std::cout << "Hello, world.\\n"; } - void display_number(int i) { + + void display_number(int i) + { std::cout << "number: " << i << '\\n'; } + + int add_xy(int x, int y) + { + return data + x + y; + } + + template int add_many(Args... args) + { + return data + (args + ...); + } + + auto add_them(auto... args) // C++20 required + { + return data + (args + ...); + } + int data = 7; }; - - int main() { - Foo f; - + + int main() + { + auto f = Foo{}; + auto greet = std::mem_fn(&Foo::display_greeting); greet(f); - + auto print_num = std::mem_fn(&Foo::display_number); print_num(f, 42); - + auto access_data = std::mem_fn(&Foo::data); std::cout << "data: " << access_data(f) << '\\n'; - } -.SH Output: + auto add_xy = std::mem_fn(&Foo::add_xy); + std::cout << "add_xy: " << add_xy(f, 1, 2) << '\\n'; - Hello, world. - number: 42 - data: 7 + auto u = std::make_unique(); + std::cout << "access_data(u): " << access_data(u) << '\\n'; + std::cout << "add_xy(u, 1, 2): " << add_xy(u, 1, 2) << '\\n'; -.SH Example 2 - - Pass a member function to std::transform to create a sequence of numbers: - - -// Run this code + auto add_many = std::mem_fn(&Foo::add_many); + std::cout << "add_many(u, ...): " << add_many(u, 1, 2, 3) << '\\n'; - #include - #include - #include - #include - #include - #include - #include - - int main() - { - std::vector words = {"This", "is", "a", "test"}; - std::vector> words2; - words2.emplace_back(new std::string("another")); - words2.emplace_back(new std::string("test")); - - std::vector lengths; - std::transform(words.begin(), - words.end(), - std::back_inserter(lengths), - std::mem_fn(&std::string::size)); // uses references to strings - std::transform(words2.begin(), - words2.end(), - std::back_inserter(lengths), - std::mem_fn(&std::string::size)); // uses unique_ptr to strings - - std::cout << "The string lengths are "; - for(auto n : lengths) std::cout << n << ' '; - std::cout << '\\n'; + auto add_them = std::mem_fn(&Foo::add_them); + std::cout << "add_them(u, ...): " << add_them(u, 5, 7, 10.0f, 13.0) << '\\n'; } .SH Output: - The string lengths are 4 2 1 4 7 4 - -.SH Example 3 - - Demonstrates the effect of the C++14 changes to the specification of std::mem_fn - - -// Run this code + Hello, world. + number: 42 + data: 7 + add_xy: 10 + access_data(u): 7 + add_xy(u, 1, 2): 10 + add_many(u, ...): 13 + add_them(u, ...): 42 - #include - #include - - struct X { - int x; - - int& easy() {return x;} - int& get() {return x;} - const int& get() const {return x;} - }; - - - int main(void) - { - auto a = std::mem_fn (&X::easy); // no problem at all - // auto b = std::mem_fn(&X::get ); // no longer works in C++14 - auto c = std::mem_fn(&X::get ); // works with both C++11 and C++14 - auto d = [] (X& x) {return x.get();}; // another approach to overload resolution - - X x = {33}; - std::cout << "a() = " << a(x) << '\\n'; - std::cout << "c() = " << c(x) << '\\n'; - std::cout << "d() = " << d(x) << '\\n'; - } + Defect reports -.SH Output: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - a() = 33 - c() = 33 - d() = 33 + DR Applied to Behavior as published Correct behavior + LWG 2048 C++11 unnecessary overloads provided removed + LWG 2489 C++11 noexcept not required required .SH See also - function wraps callable object of any type with specified function call signature - \fI(C++11)\fP \fI(class template)\fP - bind binds one or more arguments to a function object - \fI(C++11)\fP \fI(function template)\fP + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + bind binds one or more arguments to a function object + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::mem_fun.3 b/man/std::mem_fun.3 index 3ae178307..7355194b7 100644 --- a/man/std::mem_fun.3 +++ b/man/std::mem_fun.3 @@ -1,25 +1,31 @@ -.TH std::mem_fun 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mem_fun 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mem_fun \- std::mem_fun + .SH Synopsis Defined in header - template< class Res, class T > \fB(1)\fP \fB(deprecated)\fP - std::mem_fun_t mem_fun( Res (T::*f)() ); - template< class Res, class T > \fB(1)\fP \fB(deprecated)\fP - std::const_mem_fun_t mem_fun( Res (T::*f)() ); - template< class Res, class T, class Arg > \fB(2)\fP \fB(deprecated)\fP - std::mem_fun1_t mem_fun( Res (T::*f)(Arg) ); - template< class Res, class T, class Arg > \fB(2)\fP \fB(deprecated)\fP - std::const_mem_fun1_t mem_fun( S (T::*f)(Arg) ); + template< class Res, class T > \fB(1)\fP (deprecated in C++11) + std::mem_fun_t mem_fun( Res (T::*f)() ); (removed in C++17) + template< class Res, class T > (deprecated in C++11) + std::const_mem_fun_t mem_fun( Res (T::*f)() const \fB(1)\fP (removed in C++17) + ); + template< class Res, class T, class Arg > \fB(2)\fP (deprecated in C++11) + std::mem_fun1_t mem_fun( Res (T::*f)(Arg) ); (removed in C++17) + template< class Res, class T, class Arg > (deprecated in C++11) + std::const_mem_fun1_t mem_fun( Res (T::*f)(Arg) \fB(2)\fP (removed in C++17) + const ); Creates a member function wrapper object, deducing the target type from the template arguments. The wrapper object expects a pointer to an object of type T as the first parameter to its operator(). - 1) Effectively calls std::mem_fun_t(f) or std::const_mem_fun_t(f). - 2) Effectively calls std::mem_fun1_t(f) or std::const_mem_fun1_t(f). + 1) Effectively calls std::mem_fun_t(f) or std::const_mem_fun_t(f). + 2) Effectively calls std::mem_fun1_t(f) or + std::const_mem_fun1_t(f). - This function and the related types are deprecated as of C++11 in favor of the more - general std::function and std::bind, both of which create callable - adapter-compatible function objects from plain functions. + This function and the related types were deprecated in C++11 and removed in C++17 in + favor of the more general std::mem_fn and std::bind, both of which create callable + adaptor-compatible function objects from member functions. .SH Parameters @@ -31,25 +37,80 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes The difference between std::mem_fun and std::mem_fun_ref is that the former produces - an function wrapper that expects a pointer to an object, whereas the latter -- a + a function wrapper that expects a pointer to an object, whereas the latter — a reference. .SH Example - This section is incomplete - Reason: no example + Demonstrates std::mem_fun usage and compares it with std::mem_fn. C++11/14 + compatible compilation mode might be necessary: g++/clang++ with -std=c++11, cl with + /std:c++11, etc. On recent compilers, e.g. gcc-12, might issue "deprecated + declaration" warnings if not compiled in C++98 mode. + + +// Run this code + + #include + #include + + struct S + { + int get_data() const { return data; } + void no_args() const { std::cout << "void S::no_args() const\\n"; } + void one_arg(int) { std::cout << "void S::one_arg()\\n"; } + void two_args(int, int) { std::cout << "void S::two_args(int, int)\\n"; } + #if __cplusplus > 201100 + int data{42}; + #else + int data; + S() : data(42) {} + #endif + }; + + int main() + { + S s; + + std::const_mem_fun_t p = std::mem_fun(&S::get_data); + std::cout << "s.get_data(): " << p(&s) << '\\n'; + + std::const_mem_fun_t p0 = std::mem_fun(&S::no_args); + p0(&s); + + std::mem_fun1_t p1 = std::mem_fun(&S::one_arg); + p1(&s, 1); + + #if __cplusplus > 201100 + // auto p2 = std::mem_fun(&S::two_args); // Error: mem_fun supports only member functions + // without parameters or with only one parameter. + // Thus, std::mem_fn is a better alternative: + auto p2 = std::mem_fn(&S::two_args); + p2(s, 1, 2); + + // auto pd = std::mem_fun(&S::data); // Error: pointers to data members are not supported. + // Use std::mem_fn instead: + auto pd = std::mem_fn(&S::data); + std::cout << "s.data = " << pd(s) << '\\n'; + #endif + } + +.SH Possible output: + + s.get_data(): 42 + void S::no_args() const + void S::one_arg(int) + void S::two_args(int, int) + s.data = 42 .SH See also - mem_fun_ref creates a wrapper from a pointer to member function, callable with a - \fB(deprecated)\fP reference to object - \fI(function template)\fP - -.SH Category: - - * Todo no example + mem_fn creates a function object out of a pointer to a member + \fI(C++11)\fP \fI(function template)\fP + mem_fun_ref creates a wrapper from a pointer to member function, callable + (deprecated in C++11) with a reference to object + (removed in C++17) \fI(function template)\fP diff --git a/man/std::mem_fun_ref.3 b/man/std::mem_fun_ref.3 index 8cf394c89..2233bed1a 100644 --- a/man/std::mem_fun_ref.3 +++ b/man/std::mem_fun_ref.3 @@ -1,27 +1,32 @@ -.TH std::mem_fun_ref 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mem_fun_ref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mem_fun_ref \- std::mem_fun_ref + .SH Synopsis Defined in header - template< class Res, class T > \fB(1)\fP \fB(deprecated)\fP - std::mem_fun_ref_t mem_fun_ref( Res (T::*f)() ); - template< class Res, class T > \fB(1)\fP \fB(deprecated)\fP - std::const_mem_fun_ref_t mem_fun_ref( Res (T::*f)() ); - template< class Res, class T, class Arg > \fB(2)\fP \fB(deprecated)\fP - std::mem_fun1_ref_t mem_fun_ref( Res (T::*f)(Arg) ); - template< class Res, class T, class Arg > \fB(2)\fP \fB(deprecated)\fP - std::const_mem_fun1_ref_t mem_fun_ref( S (T::*f)(Arg) ); + template< class Res, class T > \fB(1)\fP (deprecated in C++11) + std::mem_fun_ref_t mem_fun_ref( Res (T::*f)() ); (removed in C++17) + template< class Res, class T > (deprecated in C++11) + std::const_mem_fun_ref_t mem_fun_ref( Res (T::*f)() \fB(1)\fP (removed in C++17) + const ); + template< class Res, class T, class Arg > (deprecated in C++11) + std::mem_fun1_ref_t mem_fun_ref( Res \fB(2)\fP (removed in C++17) + (T::*f)(Arg) ); + template< class Res, class T, class Arg > (deprecated in C++11) + std::const_mem_fun1_ref_t mem_fun_ref( Res \fB(2)\fP (removed in C++17) + (T::*f)(Arg) const ); Creates a member function wrapper object, deducing the target type from the template arguments. The wrapper object expects a reference to an object of type T as the first parameter to its operator(). 1) Effectively calls std::mem_fun_ref_t(f) or std::const_mem_fun_ref_t(f). - 2) Effectively calls std::mem_fun1_ref_t(f) or std::const_mem_fun1_ref_t(f). - This function and the related types are deprecated as of C++11 in favor of the more - general std::function and std::bind, both of which create callable - adapter-compatible function objects from plain functions. + This function and the related types were deprecated in C++11 and removed in C++17 in + favor of the more general std::mem_fn and std::bind, both of which create callable + adaptor-compatible function objects from member functions. .SH Parameters @@ -33,32 +38,32 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes The difference between std::mem_fun and std::mem_fun_ref is that the former produces - an function wrapper that expects a pointer to an object, whereas the latter -- a + a function wrapper that expects a pointer to an object, whereas the latter — a reference. .SH Example - uses std::mem_fun_ref to bind std::string's member function .size() + Uses std::mem_fun_ref to bind std::string's member function size(). + - // Run this code - #include - #include - #include - #include #include + #include #include - + #include + #include + #include + int main() { std::vector v = {"once", "upon", "a", "time"}; - std::transform(v.begin(), v.end(), + std::transform(v.cbegin(), v.cend(), std::ostream_iterator(std::cout, " "), std::mem_fun_ref(&std::string::size)); } @@ -69,6 +74,6 @@ .SH See also - mem_fun creates a wrapper from a pointer to member function, callable with a - \fB(deprecated)\fP pointer to object - \fI(function template)\fP + mem_fun creates a wrapper from a pointer to member function, callable + (deprecated in C++11) with a pointer to object + (removed in C++17) \fI(function template)\fP diff --git a/man/std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t,.3 b/man/std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t,.3 index c987208ee..db7ff3e65 100644 --- a/man/std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t,.3 +++ b/man/std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t,.3 @@ -1,34 +1,39 @@ -.TH std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t, 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t, \- std::mem_fun_ref_t,std::mem_fun1_ref_t,std::const_mem_fun_ref_t, + .SH Synopsis + Defined in header template< class S, class T > class mem_fun_ref_t : public unary_function { - public: \fB(1)\fP \fB(deprecated)\fP - explicit mem_fun_ref_t(S (T::*p)()); + public: \fB(1)\fP (deprecated in C++11) + explicit mem_fun_ref_t(S (T::*p)()); (removed in C++17) S operator()(T& p) const; }; template< class S, class T > class const_mem_fun_ref_t : public unary_function { - public: \fB(2)\fP \fB(deprecated)\fP - explicit const_mem_fun_ref_t(S (T::*p)() const); + public: \fB(2)\fP (deprecated in C++11) + explicit const_mem_fun_ref_t(S (T::*p)() const); (removed in C++17) S operator()(const T& p) const; }; template< class S, class T, class A > class mem_fun1_ref_t : public binary_function { - public: \fB(3)\fP \fB(deprecated)\fP - explicit mem_fun1_ref_t(S (T::*p)(A)); + public: \fB(3)\fP (deprecated in C++11) + explicit mem_fun1_ref_t(S (T::*p)(A)); (removed in C++17) S operator()(T& p, A x) const; }; template< class S, class T, class A > - class const_mem_fun1_ref_t : public binary_function { - public: \fB(4)\fP \fB(deprecated)\fP + class const_mem_fun1_ref_t : public binary_function + { (deprecated in C++11) + public: \fB(4)\fP (removed in C++17) explicit const_mem_fun1_ref_t(S (T::*p)(A) const); S operator()(const T& p, A x) const; @@ -44,14 +49,12 @@ .SH See also - mem_fun_ref creates a wrapper from a pointer to member function, callable with - \fB(deprecated)\fP a reference to object - \fI(function template)\fP + mem_fun_ref creates a wrapper from a pointer to member function, callable + (deprecated in C++11) with a reference to object + (removed in C++17) \fI(function template)\fP mem_fun_t - mem_fun1_t - const_mem_fun_t wrapper for a pointer to nullary or unary member function, callable - const_mem_fun1_t with a pointer to object - \fB(deprecated)\fP \fI(class template)\fP - \fB(deprecated)\fP - \fB(deprecated)\fP - \fB(deprecated)\fP + mem_fun1_t wrapper for a pointer to nullary or unary member function, + const_mem_fun_t callable with a pointer to object + const_mem_fun1_t \fI(class template)\fP + (deprecated in C++11) + (removed in C++17) diff --git a/man/std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t.3 b/man/std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t.3 index 03a426ab8..93e7ce10a 100644 --- a/man/std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t.3 +++ b/man/std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t.3 @@ -1,33 +1,39 @@ -.TH std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t \- std::mem_fun_t,std::mem_fun1_t,std::const_mem_fun_t,std::const_mem_fun1_t + .SH Synopsis + Defined in header template< class S, class T > class mem_fun_t : public unary_function { - public: \fB(1)\fP \fB(deprecated)\fP - explicit mem_fun_t(S (T::*p)()); + public: \fB(1)\fP (deprecated in C++11) + explicit mem_fun_t(S (T::*p)()); (removed in C++17) S operator()(T* p) const; }; template< class S, class T > - class const_mem_fun_t : public unary_function { - public: \fB(2)\fP \fB(deprecated)\fP + class const_mem_fun_t : public unary_function + { (deprecated in C++11) + public: \fB(2)\fP (removed in C++17) explicit const_mem_fun_t(S (T::*p)() const); S operator()(const T* p) const; }; - template< class S, class T, class Arg > + template< class S, class T, class A > class mem_fun1_t : public binary_function { - public: \fB(2)\fP \fB(deprecated)\fP - explicit mem_fun1_t(S (T::*p)(A)); + public: \fB(3)\fP (deprecated in C++11) + explicit mem_fun1_t(S (T::*p)(A)); (removed in C++17) S operator()(T* p, A x) const; }; template< class S, class T, class A > - class const_mem_fun1_t : public binary_function { - public: \fB(4)\fP \fB(deprecated)\fP + class const_mem_fun1_t : public binary_function { (deprecated in C++11) + public: \fB(4)\fP (removed in C++17) explicit const_mem_fun1_t(S (T::*p)(A) const); S operator()(const T* p, A x) const; @@ -43,14 +49,12 @@ .SH See also - mem_fun creates a wrapper from a pointer to member function, callable - \fB(deprecated)\fP with a pointer to object - \fI(function template)\fP + mem_fun creates a wrapper from a pointer to member function, callable + (deprecated in C++11) with a pointer to object + (removed in C++17) \fI(function template)\fP mem_fun_ref_t - mem_fun1_ref_t - const_mem_fun_ref_t wapper for a pointer to nullary or unary member function, - const_mem_fun1_ref_t callable with a reference to object - \fB(deprecated)\fP \fI(class template)\fP - \fB(deprecated)\fP - \fB(deprecated)\fP - \fB(deprecated)\fP + mem_fun1_ref_t wrapper for a pointer to nullary or unary member function, + const_mem_fun_ref_t callable with a reference to object + const_mem_fun1_ref_t \fI(class template)\fP + (deprecated in C++11) + (removed in C++17) diff --git a/man/std::memchr.3 b/man/std::memchr.3 index 7664af732..6160f48c2 100644 --- a/man/std::memchr.3 +++ b/man/std::memchr.3 @@ -1,39 +1,62 @@ -.TH std::memchr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::memchr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::memchr \- std::memchr + .SH Synopsis Defined in header const void* memchr( const void* ptr, int ch, std::size_t count ); void* memchr( void* ptr, int ch, std::size_t count ); Converts ch to unsigned char and locates the first occurrence of that value in the - initial count characters (each interpreted as unsigned char) of the object pointed - to by ptr. + initial count bytes (each interpreted as unsigned char) of the object pointed to by + ptr. + + This function behaves as if it reads the bytes sequentially and stops + as soon as a matching bytes is found: if the array pointed to by ptr \fI(since C++17)\fP + is smaller than count, but the match is found within the array, the + behavior is well-defined. .SH Parameters ptr - pointer to the object to be examined - ch - character to search for - count - number of characters to examine + ch - byte to search for + count - max number of bytes to examine .SH Return value - Pointer to the location of the character, or NULL if no such character is found. + Pointer to the location of the byte, or a null pointer if no such byte is found. .SH Example - This section is incomplete - Reason: no example + Search an array of characters. + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', '\\0', 'a', 'A', 'a', 'a', 'A', 'a'}; + char *pc = (char*) std::memchr(arr, 'A', sizeof arr); + if (pc != nullptr) + std::cout << "search character found\\n"; + else + std::cout << "search character not found\\n"; + } + +.SH Output: + + search character found .SH See also strchr finds the first occurrence of a character - \fI(function)\fP + \fI(function)\fP find find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if_not \fI(function template)\fP \fI(C++11)\fP C documentation for memchr - -.SH Category: - - * Todo no example diff --git a/man/std::memcmp.3 b/man/std::memcmp.3 index ebffc606f..31d78ed6c 100644 --- a/man/std::memcmp.3 +++ b/man/std::memcmp.3 @@ -1,12 +1,19 @@ -.TH std::memcmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::memcmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::memcmp \- std::memcmp + .SH Synopsis Defined in header int memcmp( const void* lhs, const void* rhs, std::size_t count ); Reinterprets the objects pointed to by lhs and rhs as arrays of unsigned char and - compares the first count characters of these arrays. The comparison is done + compares the first count bytes of these arrays. The comparison is done lexicographically. + The sign of the result is the sign of the difference between the values of the first + pair of bytes (both interpreted as unsigned char) that differ in the objects being + compared. + .SH Parameters lhs, rhs - pointers to the memory buffers to compare @@ -25,38 +32,55 @@ .SH Notes This function reads object representations, not the object values, and is typically - meaningful for trivially-copyable objects only. For example, memcmp() between two - objects of type std::string or std::vector will not compare their contents. + meaningful for only trivially-copyable objects that have no padding. For example, + memcmp() between two objects of type std::string or std::vector will not compare + their contents, memcmp() between two objects of type struct { char c; int n; } will + compare the padding bytes whose values may differ when the values of c and n are the + same, and even if there were no padding bytes, the int would be compared without + taking into account endianness. .SH Example - + // Run this code - #include #include - + #include + + void demo(const char* lhs, const char* rhs, std::size_t sz) + { + std::cout << std::string(lhs, sz); + const int rc = std::memcmp(lhs, rhs, sz); + if (rc < 0) + std::cout << " precedes "; + else if (rc > 0) + std::cout << " follows "; + else + std::cout << " compares equal to "; + std::cout << std::string(rhs, sz) << " in lexicographical order\\n"; + } + int main() { char a1[] = {'a', 'b', 'c'}; - char a2[] = {'a', 'b', 'd'}; - - std::cout << "'abc' vs 'abd': " << std::memcmp(a1, a2, sizeof a1) << '\\n' - << "'abd' vs 'abc': " << std::memcmp(a2, a1, sizeof a1) << '\\n' - << "'abc' vs 'abc': " << std::memcmp(a1, a1, sizeof a1) << '\\n'; + char a2[sizeof a1] = {'a', 'b', 'd'}; + + demo(a1, a2, sizeof a1); + demo(a2, a1, sizeof a1); + demo(a1, a1, sizeof a1); } .SH Output: - 'abc' vs 'abd': -1 - 'abd' vs 'abc': 1 - 'abc' vs 'abc': 0 + abc precedes abd in lexicographical order + abd follows abc in lexicographical order + abc compares equal to abc in lexicographical order .SH See also strcmp compares two strings - \fI(function)\fP - strncmp compares a certain amount of characters of two strings - \fI(function)\fP + \fI(function)\fP + strncmp compares a certain number of characters from two strings + \fI(function)\fP C documentation for memcmp diff --git a/man/std::memcpy.3 b/man/std::memcpy.3 index 72f4ad806..9eba545c1 100644 --- a/man/std::memcpy.3 +++ b/man/std::memcpy.3 @@ -1,13 +1,21 @@ -.TH std::memcpy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::memcpy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::memcpy \- std::memcpy + .SH Synopsis Defined in header void* memcpy( void* dest, const void* src, std::size_t count ); Copies count bytes from the object pointed to by src to the object pointed to by - dest. + dest. Both objects are reinterpreted as arrays of unsigned char. + + If the objects overlap, the behavior is undefined. - If the objects overlap, the behavior is undefined. If the objects are not trivially - copyable (e.g. scalars, arrays, C-compatible structs), the behavior is undefined. + If either dest or src is an invalid or null pointer, the behavior is undefined, even + if count is zero. + + If the objects are potentially-overlapping or not TriviallyCopyable, the behavior of + memcpy is not specified and may be undefined. .SH Parameters @@ -19,43 +27,83 @@ dest +.SH Notes + + std::memcpy may be used to implicitly create objects in the destination buffer. + + std::memcpy is meant to be the fastest library routine for memory-to-memory copy. It + is usually more efficient than std::strcpy, which must scan the data it copies or + std::memmove, which must take precautions to handle overlapping inputs. + + Several C++ compilers transform suitable memory-copying loops to std::memcpy calls. + + Where strict aliasing prohibits examining the same memory as values of two different + types, std::memcpy may be used to convert the values. + .SH Example - + // Run this code - #include + #include #include - + #include + int main() { - char source[] = "once upon a midnight dreary..."; - char dest[4]; - + // simple usage + char source[] = "once upon a daydream...", dest[4]; std::memcpy(dest, source, sizeof dest); - - for (char c : dest) { - std::cout << c << '\\n'; - } + std::cout << "dest[4] = {"; + for (int n{}; char c : dest) + std::cout << (n++ ? ", " : "") << '\\'' << c << "'"; + std::cout << "};\\n"; + + // reinterpreting + double d = 0.1; + // std::int64_t n = *reinterpret_cast(&d); // aliasing violation + std::int64_t n; + std::memcpy(&n, &d, sizeof d); // OK + + std::cout << std::hexfloat << d << " is " << std::hex << n + << " as a std::int64_t\\n" << std::dec; + + // object creation in destination buffer + struct S + { + int x{42}; + void print() const { std::cout << '{' << x << "}\\n"; } + } s; + alignas(S) char buf[sizeof(S)]; + S* ps = new (buf) S; // placement new + std::memcpy(ps, &s, sizeof s); + ps->print(); } .SH Output: - o - n - c - e + dest[4] = {'o', 'n', 'c', 'e'}; + 0x1.999999999999ap-4 is 3fb999999999999a as a std::int64_t + {42} .SH See also memmove moves one buffer to another - \fI(function)\fP + \fI(function)\fP + memset fills a buffer with a character + \fI(function)\fP + copies a certain amount of wide characters between two + wmemcpy non-overlapping arrays + \fI(function)\fP + copies characters + copy \fI\fI(public member\fP function of\fP + std::basic_string) copy copies a range of elements to a new location - copy_if \fI(function template)\fP + copy_if \fI(function template)\fP \fI(C++11)\fP copy_backward copies a range of elements in backwards order - \fI(function template)\fP + \fI(function template)\fP is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP C documentation for memcpy diff --git a/man/std::memmove.3 b/man/std::memmove.3 index 72da60598..f3516d117 100644 --- a/man/std::memmove.3 +++ b/man/std::memmove.3 @@ -1,13 +1,23 @@ -.TH std::memmove 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::memmove 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::memmove \- std::memmove + .SH Synopsis Defined in header void* memmove( void* dest, const void* src, std::size_t count ); Copies count characters from the object pointed to by src to the object pointed to - by dest. The objects may overlap: copying takes place as if the characters were - copied to a temporary character array and then the characters were copied from the - array to dest. If the objects are not trivially-copyable (scalars, arrays, C-style - structs), the behavior is undefined. + by dest. Both objects are reinterpreted as arrays of unsigned char. + + The objects may overlap: copying takes place as if the characters were copied to a + temporary character array and then the characters were copied from the array to + dest. + + If either dest or src is an invalid or null pointer, the behavior is undefined, even + if count is zero. + + If the objects are potentially-overlapping or not TriviallyCopyable, the behavior of + memmove is not specified and may be undefined. .SH Parameters @@ -19,25 +29,56 @@ dest +.SH Notes + + std::memmove may be used to implicitly create objects in the destination buffer. + + Despite being specified "as if" a temporary buffer is used, actual implementations + of this function do not incur the overhead of double copying or extra memory. For + small count, it may load up and write out registers; for larger blocks, a common + approach (glibc and bsd libc) is to copy bytes forwards from the beginning of the + buffer if the destination starts before the source, and backwards from the end + otherwise, with a fall back to std::memcpy when there is no overlap at all. + + Where strict aliasing prohibits examining the same memory as values of two different + types, std::memmove may be used to convert the values. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + char str[] = "1234567890"; + std::cout << str << '\\n'; + std::memmove(str + 4, str + 3, 3); // copies from [4, 5, 6] to [5, 6, 7] + std::cout << str << '\\n'; + } + +.SH Output: + + 1234567890 + 1234456890 .SH See also memcpy copies one buffer to another - \fI(function)\fP + \fI(function)\fP + memset fills a buffer with a character + \fI(function)\fP + copies a certain amount of wide characters between two, + wmemmove possibly overlapping, arrays + \fI(function)\fP copy copies a range of elements to a new location - copy_if \fI(function template)\fP + copy_if \fI(function template)\fP \fI(C++11)\fP copy_backward copies a range of elements in backwards order - \fI(function template)\fP + \fI(function template)\fP is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP C documentation for memmove - -.SH Category: - - * Todo no example diff --git a/man/std::memory_order.3 b/man/std::memory_order.3 index 996d5568a..853ef0ffd 100644 --- a/man/std::memory_order.3 +++ b/man/std::memory_order.3 @@ -1,25 +1,47 @@ -.TH std::memory_order 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::memory_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::memory_order \- std::memory_order + .SH Synopsis Defined in header - enum memory_order { + typedef enum memory_order { memory_order_relaxed, memory_order_consume, - memory_order_acquire, \fI(since C++11)\fP - memory_order_release, + memory_order_acquire, \fI(since C++11)\fP + memory_order_release, \fI(until C++20)\fP memory_order_acq_rel, memory_order_seq_cst - }; - - std::memory_order specifies how regular, non-atomic memory accesses are to be - ordered around an atomic operation. Absent any constraints on a multi-core system, - when multiple threads simultaneously read and write to several variables, one thread - can observe the values change in an order different from the order another thread - wrote them. Indeed, the apparent order of changes can even differ among multiple - reader threads. + } memory_order; + enum class memory_order : /* unspecified */ { - The default behavior of the atomic operations in the library provides for + relaxed, consume, acquire, release, acq_rel, seq_cst + }; + inline constexpr memory_order memory_order_relaxed = + memory_order::relaxed; + inline constexpr memory_order memory_order_consume = + memory_order::consume; + inline constexpr memory_order memory_order_acquire = \fI(since C++20)\fP + memory_order::acquire; + inline constexpr memory_order memory_order_release = + memory_order::release; + inline constexpr memory_order memory_order_acq_rel = + memory_order::acq_rel; + + inline constexpr memory_order memory_order_seq_cst = + memory_order::seq_cst; + + std::memory_order specifies how memory accesses, including regular, non-atomic + memory accesses, are to be ordered around an atomic operation. Absent any + constraints on a multi-core system, when multiple threads simultaneously read and + write to several variables, one thread can observe the values change in an order + different from the order another thread wrote them. Indeed, the apparent order of + changes can even differ among multiple reader threads. Some similar effects can + occur even on uniprocessor systems due to compiler transformations allowed by the + memory model. + + The default behavior of all atomic operations in the library provides for sequentially consistent ordering (see discussion below). That default can hurt performance, but the library's atomic operations can be given an additional std::memory_order argument to specify the exact constraints, beyond atomicity, that @@ -29,26 +51,45 @@ Defined in header Value Explanation - memory_order_relaxed Relaxed ordering: there are no synchronization or ordering - constraints, only atomicity is required of this operation. + Relaxed operation: there are no synchronization or ordering + memory_order_relaxed constraints imposed on other reads or writes, only this + operation's atomicity is guaranteed (see Relaxed ordering + below). A load operation with this memory order performs a consume - memory_order_consume operation on the affected memory location: prior writes to - data-dependent memory locations made by the thread that did a - release operation become visible to this thread. + operation on the affected memory location: no reads or writes + in the current thread dependent on the value currently loaded + memory_order_consume can be reordered before this load. Writes to data-dependent + variables in other threads that release the same atomic + variable are visible in the current thread. On most platforms, + this affects compiler optimizations only (see Release-Consume + ordering below). A load operation with this memory order performs the acquire - memory_order_acquire operation on the affected memory location: prior writes made to - other memory locations by the thread that did the release - become visible in this thread. + operation on the affected memory location: no reads or writes + memory_order_acquire in the current thread can be reordered before this load. All + writes in other threads that release the same atomic variable + are visible in the current thread (see Release-Acquire ordering + below). A store operation with this memory order performs the release - memory_order_release operation: prior writes to other memory locations become - visible to the threads that do a consume or an acquire on the - same location. - A load operation with this memory order performs the acquire - memory_order_acq_rel operation on the affected memory location and a store operation - with this memory order performs the release operation. - Same as memory_order_acq_rel, plus a single total order exists - memory_order_seq_cst in which all threads observe all modifications (see below) in - the same order. + operation: no reads or writes in the current thread can be + reordered after this store. All writes in the current thread + memory_order_release are visible in other threads that acquire the same atomic + variable (see Release-Acquire ordering below) and writes that + carry a dependency into the atomic variable become visible in + other threads that consume the same atomic (see Release-Consume + ordering below). + A read-modify-write operation with this memory order is both an + acquire operation and a release operation. No memory reads or + writes in the current thread can be reordered before the load, + memory_order_acq_rel nor after the store. All writes in other threads that release + the same atomic variable are visible before the modification + and the modification is visible in other threads that acquire + the same atomic variable. + A load operation with this memory order performs an acquire + operation, a store performs a release operation, and + memory_order_seq_cst read-modify-write performs both an acquire operation and a + release operation, plus a single total order exists in which + all threads observe all modifications in the same order (see + Sequentially-consistent ordering below). .SH Formal description @@ -56,9 +97,6 @@ effects of expressions are ordered between different threads of execution. They are defined in the following terms: - This section is incomplete - Reason: should be moved to its own page, like evaluation_order - .SH Sequenced-before Within the same thread, evaluation A may be sequenced-before evaluation B, as @@ -67,158 +105,237 @@ .SH Carries dependency Within the same thread, evaluation A that is sequenced-before evaluation B may also - carry a dependency into B (that is, B depends on A), if any of the following is true + carry a dependency into B (that is, B depends on A), if any of the following is + true: 1) The value of A is used as an operand of B, except - a) if B is a call to std::kill_dependency + a) if B is a call to std::kill_dependency, b) if A is the left operand of the built-in &&, ||, ?:, or , operators. - 2) A writes to a scalar object M, B reads from M, and A is sequenced-before B - 3) A carries dependency into another evaluation X, and X carries dependency into B + 2) A writes to a scalar object M, B reads from M. + 3) A carries dependency into another evaluation X, and X carries dependency into B. .SH Modification order All modifications to any particular atomic variable occur in a total order that is specific to this one atomic variable. - The following three requirements are guaranteed for all atomic operations: + The following four requirements are guaranteed for all atomic operations: 1) Write-write coherence: If evaluation A that modifies some atomic M (a write) happens-before evaluation B that modifies M, then A appears earlier than B in the - modification order of M + modification order of M. 2) Read-read coherence: if a value computation A of some atomic M (a read) happens-before a value computation B on M, and if the value of A comes from a write X on M, then the value of B is either the value stored by X, or the value stored by a side effect Y on M that appears later than X in the modification order of M. 3) Read-write coherence: if a value computation A of some atomic M (a read) happens-before an operation B on M (a write), then the value of A comes from a - side-effect (a write) X that appears earlier than B in the modification order of M + side-effect (a write) X that appears earlier than B in the modification order of M. + 4) Write-read coherence: if a side effect (a write) X on an atomic object M + happens-before a value computation (a read) B of M, then the evaluation B shall take + its value from X or from a side effect Y that follows X in the modification order of + M. .SH Release sequence After a release operation A is performed on an atomic object M, the longest - continuous subsequence of the modification order of M that consists of + continuous subsequence of the modification order of M that consists of: + + 1) Writes performed by the same thread that performed A. \fI(until C++20)\fP + + 2) Atomic read-modify-write operations made to M by any thread. - 1) Writes performed by the same thread that performed A - 2) Atomic read-modify-write operations made to M by any thread + Is known as release sequence headed by A. - is known as release sequence headed by A + Synchronizes with + + If an atomic store in thread A is a release operation, an atomic load in thread B + from the same variable is an acquire operation, and the load in thread B reads a + value written by the store in thread A, then the store in thread A synchronizes-with + the load in thread B. + + Also, some library calls may be defined to synchronize-with other library calls on + other threads. .SH Dependency-ordered before Between threads, evaluation A is dependency-ordered before evaluation B if any of - the following is true + the following is true: 1) A performs a release operation on some atomic M, and, in a different thread, B - performs a consume operation on the same atomic M, and B reads a value written by - any part of the release sequence headed by A. + performs a consume operation on the same atomic M, and B reads a value written + by any part of the release sequence headed + \fI(until C++20)\fP by A. 2) A is dependency-ordered before X and X carries a dependency into B. .SH Inter-thread happens-before Between threads, evaluation A inter-thread happens before evaluation B if any of the - following is true + following is true: - 1) A synchronizes-with B - 2) A is dependency-ordered before B - 3) A synchronizes-with some evaluation X, and X is sequenced-before B - 3) A is sequenced-before some evaluation X, and X inter-thread happens-before B - 4) A inter-thread happens-before some evaluation X, and X inter-thread - happens-before B + 1) A synchronizes-with B. + 2) A is dependency-ordered before B. + 3) A synchronizes-with some evaluation X, and X is sequenced-before B. + 4) A is sequenced-before some evaluation X, and X inter-thread happens-before B. + 5) A inter-thread happens-before some evaluation X, and X inter-thread + happens-before B. .SH Happens-before Regardless of threads, evaluation A happens-before evaluation B if any of the following is true: - 1) A is sequenced-before B - 2) A inter-thread happens before B + 1) A is sequenced-before B. + 2) A inter-thread happens before B. + + The implementation is required to ensure that the happens-before relation is + acyclic, by introducing additional synchronization if necessary (it can only be + necessary if a consume operation is involved, see Batty et al). + + If one evaluation modifies a memory location, and the other reads or modifies the + same memory location, and if at least one of the evaluations is not an atomic + operation, the behavior of the program is undefined (the program has a data race) + unless there exists a happens-before relationship between these two evaluations. + + Simply happens-before + + Regardless of threads, evaluation A simply happens-before evaluation B + if any of the following is true: + + 1) A is sequenced-before B. \fI(since C++20)\fP + 2) A synchronizes-with B. + 3) A simply happens-before X, and X simply happens-before B. + + Note: without consume operations, simply happens-before and + happens-before relations are the same. + + Strongly happens-before + + Regardless of threads, evaluation A strongly happens-before evaluation B if any of + the following is true: + + 1) A is sequenced-before B. + 2) A synchronizes-with B. \fI(until C++20)\fP + 3) A strongly happens-before X, and X strongly happens-before B. + 1) A is sequenced-before B. + 2) A synchronizes with B, and both A and B are sequentially consistent + atomic operations. + 3) A is sequenced-before X, X simply happens-before Y, and Y is + sequenced-before B. + 4) A strongly happens-before X, and X strongly happens-before B. \fI(since C++20)\fP + + Note: informally, if A strongly happens-before B, then A appears to be + evaluated before B in all contexts. + + Note: strongly happens-before excludes consume operations. .SH Visible side-effects The side-effect A on a scalar M (a write) is visible with respect to value computation B on M (a read) if both of the following are true: - 1) A happens-before B + 1) A happens-before B. 2) There is no other side effect X to M where A happens-before X and X - happens-before B + happens-before B. If side-effect A is visible with respect to the value computation B, then the longest contiguous subset of the side-effects to M, in modification order, where B - does not happen-before it is known as the visible sequence of side-effects. (the - value of M, determined by B, will be the value stored by one of these side effects) + does not happen-before it is known as the visible sequence of side-effects (the + value of M, determined by B, will be the value stored by one of these side effects). - Note: inter-thread synchronization boils down to defining which side effects become - visible under what conditions + Note: inter-thread synchronization boils down to preventing data races (by + establishing happens-before relationships) and defining which side effects become + visible under what conditions. .SH Consume operation Atomic load with memory_order_consume or stronger is a consume operation. Note that - std::atomic_thread_fence is not a consume operation. + std::atomic_thread_fence imposes stronger synchronization requirements than a + consume operation. .SH Acquire operation - Atomic load with memory_order_acquire or stronger, as well as the lock() operation - on a Mutex is an acquire operation. Note that std::atomic_thread_fence is not an + Atomic load with memory_order_acquire or stronger is an acquire operation. The + lock() operation on a Mutex is also an acquire operation. Note that + std::atomic_thread_fence imposes stronger synchronization requirements than an acquire operation. .SH Release operation - Atomic store with memory_order_release or stronger, as well as the unlock() - operation on a Mutex is a release operation. Note that std::atomic_thread_fence is - not a release operation. + Atomic store with memory_order_release or stronger is a release operation. The + unlock() operation on a Mutex is also a release operation. Note that + std::atomic_thread_fence imposes stronger synchronization requirements than a + release operation. .SH Explanation .SH Relaxed ordering - Atomic operations tagged std::memory_order_relaxed are not synchronization - operations, they do not order memory. They only guarantee atomicity and modification - order consistency. + Atomic operations tagged memory_order_relaxed are not synchronization operations; + they do not impose an order among concurrent memory accesses. They only guarantee + atomicity and modification order consistency. For example, with x and y initially zero, // Thread 1: - r1 = y.load(memory_order_relaxed); // A - x.store(r1, memory_order_relaxed); // B + r1 = y.load(std::memory_order_relaxed); // A + x.store(r1, std::memory_order_relaxed); // B // Thread 2: - r2 = x.load(memory_order_relaxed); // C - y.store(42, memory_order_relaxed); // D + r2 = x.load(std::memory_order_relaxed); // C + y.store(42, std::memory_order_relaxed); // D + + is allowed to produce r1 == r2 == 42 because, although A is sequenced-before B + within thread 1 and C is sequenced before D within thread 2, nothing prevents D from + appearing before A in the modification order of y, and B from appearing before C in + the modification order of x. The side-effect of D on y could be visible to the load + A in thread 1 while the side effect of B on x could be visible to the load C in + thread 2. In particular, this may occur if D is completed before C in thread 2, + either due to compiler reordering or at runtime. + + Even with relaxed memory model, out-of-thin-air values are not allowed to + circularly depend on their own computations, for example, with x and y + initially zero, + + // Thread 1: + r1 = y.load(std::memory_order_relaxed); + if (r1 == 42) x.store(r1, std::memory_order_relaxed); (since + // Thread 2: C++14) + r2 = x.load(std::memory_order_relaxed); + if (r2 == 42) y.store(42, std::memory_order_relaxed); + + is not allowed to produce r1 == r2 == 42 since the store of 42 to y is only + possible if the store to x stores 42, which circularly depends on the store + to y storing 42. Note that until C++14, this was technically allowed by the + specification, but not recommended for implementors. + + Typical use for relaxed memory ordering is incrementing counters, such as the + reference counters of std::shared_ptr, since this only requires atomicity, but not + ordering or synchronization (note that decrementing the shared_ptr counters requires + acquire-release synchronization with the destructor). - is allowed to produce r1 == r2 == 42 because, although A is sequenced-before B and C - is sequenced before D, nothing prevents D from appearing before A in the - modification order of y, and B from appearing before C in the modification order of - x. - Typical use for relaxed memory ordering is updating counters, such as the reference - counters of std::shared_ptr, since this only requires atomicity, but not ordering or - synchronization. - - // Run this code - #include + #include #include #include - #include - - std::atomic cnt\fB(0)\fP; - + #include + + std::atomic cnt = {0}; + void f() { - for (int n = 0; n < 1000; ++n) { + for (int n = 0; n < 1000; ++n) cnt.fetch_add(1, std::memory_order_relaxed); - } } - + int main() { std::vector v; - for (int n = 0; n < 10; ++n) { + for (int n = 0; n < 10; ++n) v.emplace_back(f); - } - for (auto& t : v) { + for (auto& t : v) t.join(); - } std::cout << "Final counter value is " << cnt << '\\n'; } @@ -228,47 +345,53 @@ .SH Release-Acquire ordering - If an atomic store in thread A is tagged std::memory_order_release and an atomic - load in thread B from the same variable is tagged std::memory_order_acquire, all - memory writes (non-atomic and relaxed atomic) that happened-before the atomic store - from the point of view of thread A, become visible side-effects in thread B, that - is, once the atomic load is completed, thread B is guaranteed to see everything - thread A wrote to memory. + If an atomic store in thread A is tagged memory_order_release, an atomic load in + thread B from the same variable is tagged memory_order_acquire, and the load in + thread B reads a value written by the store in thread A, then the store in thread A + synchronizes-with the load in thread B. + + All memory writes (including non-atomic and relaxed atomic) that happened-before the + atomic store from the point of view of thread A, become visible side-effects in + thread B. That is, once the atomic load is completed, thread B is guaranteed to see + everything thread A wrote to memory. This promise only holds if B actually returns + the value that A stored, or a value from later in the release sequence. The synchronization is established only between the threads releasing and acquiring the same atomic variable. Other threads can see different order of memory accesses than either or both of the synchronized threads. - On strongly-ordered systems (x86, SPARC, IBM mainframe), release-acquire ordering is - automatic for the majority of operations. No additional CPU instructions are issued - for this synchronization mode, only certain compiler optimizations are affected - (e.g. the compiler is prohibited from moving non-atomic stores past the atomic - store-release or perform non-atomic loads earlier than the atomic load-acquire) + On strongly-ordered systems — x86, SPARC TSO, IBM mainframe, etc. — release-acquire + ordering is automatic for the majority of operations. No additional CPU instructions + are issued for this synchronization mode; only certain compiler optimizations are + affected (e.g., the compiler is prohibited from moving non-atomic stores past the + atomic store-release or performing non-atomic loads earlier than the atomic + load-acquire). On weakly-ordered systems (ARM, Itanium, PowerPC), special CPU load + or memory fence instructions are used. - Mutual exclusion locks (such as std::mutex or atomic spinlock) are an example of + Mutual exclusion locks, such as std::mutex or atomic spinlock, are an example of release-acquire synchronization: when the lock is released by thread A and acquired by thread B, everything that took place in the critical section (before the release) in the context of thread A has to be visible to thread B (after the acquire) which is executing the same critical section. - + // Run this code - #include #include #include #include - + #include + std::atomic ptr; int data; - + void producer() { - std::string* p = new std::string("Hello"); + std::string* p = new std::string("Hello"); data = 42; ptr.store(p, std::memory_order_release); } - + void consumer() { std::string* p2; @@ -277,7 +400,7 @@ assert(*p2 == "Hello"); // never fires assert(data == 42); // never fires } - + int main() { std::thread t1(producer); @@ -286,40 +409,44 @@ } The following example demonstrates transitive release-acquire ordering across three - threads + threads, using a release sequence. + - // Run this code - #include #include #include + #include #include - + std::vector data; - std::atomic flag = ATOMIC_VAR_INIT\fB(0)\fP; - + std::atomic flag = {0}; + void thread_1() { data.push_back\fB(42)\fP; flag.store(1, std::memory_order_release); } - + void thread_2() { - int expected=1; - while (!flag.compare_exchange_strong(expected, 2, std::memory_order_acq_rel)) { + int expected = 1; + // memory_order_relaxed is okay because this is an RMW, + // and RMWs (with any ordering) following a release form a release sequence + while (!flag.compare_exchange_strong(expected, 2, std::memory_order_relaxed)) + { expected = 1; } } - + void thread_3() { while (flag.load(std::memory_order_acquire) < 2) ; + // if we read the value 2 from the atomic flag, we see 42 in the vector assert(data.at\fB(0)\fP == 42); // will never fire } - + int main() { std::thread a(thread_1); @@ -330,15 +457,19 @@ .SH Release-Consume ordering - If an atomic store in thread A is tagged std::memory_order_release and an atomic - load in thread B from the same variable is tagged std::memory_order_consume, all - memory writes (non-atomic and relaxed atomic) that are dependency-ordered-before the - atomic store from the point of view of thread A, become visible side-effects in - thread B, that is, once the atomic load is completed, thread B is guaranteed to see - everything that thread A wrote to memory if it carries a data dependency into the - atomic load. + If an atomic store in thread A is tagged memory_order_release, an atomic load in + thread B from the same variable is tagged memory_order_consume, and the load in + thread B reads a value written by the store in thread A, then the store in thread A + is dependency-ordered before the load in thread B. - The synchronization is established only between the threads releasing and acquiring + All memory writes (non-atomic and relaxed atomic) that happened-before the atomic + store from the point of view of thread A, become visible side-effects within those + operations in thread B into which the load operation carries dependency, that is, + once the atomic load is completed, those operators and functions in thread B that + use the value obtained from the load are guaranteed to see what thread A wrote to + memory. + + The synchronization is established only between the threads releasing and consuming the same atomic variable. Other threads can see different order of memory accesses than either or both of the synchronized threads. @@ -352,39 +483,49 @@ etc) and publisher-subscriber situations with pointer-mediated publication, that is, when the producer publishes a pointer through which the consumer can access information: there is no need to make everything else the producer wrote to memory - visible to the consumer. An example of such scenario is rcu_dereference. + visible to the consumer (which may be an expensive operation on weakly-ordered + architectures). An example of such scenario is rcu_dereference. + + See also std::kill_dependency and [[carries_dependency]] for fine-grained dependency + chain control. + + Note that currently (2/2015) no known production compilers track dependency chains: + consume operations are lifted to acquire operations. + + The specification of release-consume ordering is being revised, and \fI(since C++17)\fP + the use of memory_order_consume is temporarily discouraged. This example demonstrates dependency-ordered synchronization for pointer-mediated publication: the integer data is not related to the pointer to string by a data-dependency relationship, thus its value is undefined in the consumer. - + // Run this code - #include #include #include #include - + #include + std::atomic ptr; int data; - + void producer() { - std::string* p = new std::string("Hello"); + std::string* p = new std::string("Hello"); data = 42; ptr.store(p, std::memory_order_release); } - + void consumer() { std::string* p2; while (!(p2 = ptr.load(std::memory_order_consume))) ; - assert(*p2 == "Hello"); // never fires - assert(data == 42); // may or may not fire + assert(*p2 == "Hello"); // never fires: *p2 carries dependency from ptr + assert(data == 42); // may or may not fire: data does not carry dependency from ptr } - + int main() { std::thread t1(producer); @@ -394,11 +535,125 @@ .SH Sequentially-consistent ordering - Atomic operations tagged std::memory_order_seq_cst not only order memory the same - way as release/acquire ordering (everything that happened-before a store in one - thread becomes a visible side effect in the thread that did a load), but also - establish a single total modification order of all atomic operations that are so - tagged. + Atomic operations tagged memory_order_seq_cst not only order memory the same way as + release/acquire ordering (everything that happened-before a store in one thread + becomes a visible side effect in the thread that did a load), but also establish a + single total modification order of all atomic operations that are so tagged. + + Formally, + + each memory_order_seq_cst operation B that loads from atomic variable M, + observes one of the following: + + * the result of the last operation A that modified M, which appears before + B in the single total order, + * OR, if there was such an A, B may observe the result of some modification + on M that is not memory_order_seq_cst and does not happen-before A, + * OR, if there wasn't such an A, B may observe the result of some unrelated + modification of M that is not memory_order_seq_cst. + + If there was a memory_order_seq_cst std::atomic_thread_fence operation X + sequenced-before B, then B observes one of the following: + + * the last memory_order_seq_cst modification of M that appears before X in + the single total order, + * some unrelated modification of M that appears later in M's modification + order. + + For a pair of atomic operations on M called A and B, where A writes and B + reads M's value, if there are two memory_order_seq_cst + std::atomic_thread_fences X and Y, and if A is sequenced-before X, Y is + sequenced-before B, and X appears before Y in the Single Total Order, then B (until + observes either: C++20) + + * the effect of A, + * some unrelated modification of M that appears after A in M's modification + order. + + For a pair of atomic modifications of M called A and B, B occurs after A in + M's modification order if + + * there is a memory_order_seq_cst std::atomic_thread_fence X such that A is + sequenced-before X and X appears before B in the Single Total Order, + * or, there is a memory_order_seq_cst std::atomic_thread_fence Y such that + Y is sequenced-before B and A appears before Y in the Single Total Order, + * or, there are memory_order_seq_cst std::atomic_thread_fences X and Y such + that A is sequenced-before X, Y is sequenced-before B, and X appears + before Y in the Single Total Order. + + Note that this means that: + + 1) as soon as atomic operations that are not tagged memory_order_seq_cst + enter the picture, the sequential consistency is lost, + 2) the sequentially-consistent fences are only establishing total ordering + for the fences themselves, not for the atomic operations in the general case + (sequenced-before is not a cross-thread relationship, unlike happens-before). + Formally, + + an atomic operation A on some atomic object M is coherence-ordered-before + another atomic operation B on M if any of the following is true: + + 1) A is a modification, and B reads the value stored by A, + 2) A precedes B in the modification order of M, + 3) A reads the value stored by an atomic modification X, X precedes B in the + modification order, and A and B are not the same atomic read-modify-write + operation, + 4) A is coherence-ordered-before X, and X is coherence-ordered-before B. + + There is a single total order S on all memory_order_seq_cst operations, + including fences, that satisfies the following constraints: + + 1) if A and B are memory_order_seq_cst operations, and A strongly + happens-before B, then A precedes B in S, + 2) for every pair of atomic operations A and B on an object M, where A is + coherence-ordered-before B: + a) if A and B are both memory_order_seq_cst operations, then A precedes B in + S, + b) if A is a memory_order_seq_cst operation, and B happens-before a + memory_order_seq_cst fence Y, then A precedes Y in S, + c) if a memory_order_seq_cst fence X happens-before A, and B is a + memory_order_seq_cst operation, then X precedes B in S, + d) if a memory_order_seq_cst fence X happens-before A, and B happens-before a + memory_order_seq_cst fence Y, then X precedes Y in S. + + The formal definition ensures that: + + 1) the single total order is consistent with the modification order of any + atomic object, + 2) a memory_order_seq_cst load gets its value either from the last (since + memory_order_seq_cst modification, or from some non-memory_order_seq_cst C++20) + modification that does not happen-before preceding memory_order_seq_cst + modifications. + + The single total order might not be consistent with happens-before. This + allows more efficient implementation of memory_order_acquire and + memory_order_release on some CPUs. It can produce surprising results when + memory_order_acquire and memory_order_release are mixed with + memory_order_seq_cst. + + For example, with x and y initially zero, + + // Thread 1: + x.store(1, std::memory_order_seq_cst); // A + y.store(1, std::memory_order_release); // B + // Thread 2: + r1 = y.fetch_add(1, std::memory_order_seq_cst); // C + r2 = y.load(std::memory_order_relaxed); // D + // Thread 3: + y.store(3, std::memory_order_seq_cst); // E + r3 = x.load(std::memory_order_seq_cst); // F + + is allowed to produce r1 == 1 && r2 == 3 && r3 == 0, where A happens-before + C, but C precedes A in the single total order C-E-F-A of memory_order_seq_cst + (see Lahav et al). + + Note that: + + 1) as soon as atomic operations that are not tagged memory_order_seq_cst + enter the picture, the sequential consistency guarantee for the program is + lost, + 2) in many cases, memory_order_seq_cst atomic operations are reorderable with + respect to other atomic operations performed by the same thread. Sequential ordering may be necessary for multiple producer-multiple consumer situations where all consumers must observe the actions of all producers occurring @@ -412,45 +667,43 @@ other ordering may trigger the assert because it would be possible for the threads c and d to observe changes to the atomics x and y in opposite order. - + // Run this code - #include #include #include - - std::atomic x = ATOMIC_VAR_INIT(false); - std::atomic y = ATOMIC_VAR_INIT(false); - std::atomic z = ATOMIC_VAR_INIT\fB(0)\fP; - + #include + + std::atomic x = {false}; + std::atomic y = {false}; + std::atomic z = {0}; + void write_x() { x.store(true, std::memory_order_seq_cst); } - + void write_y() { y.store(true, std::memory_order_seq_cst); } - + void read_x_then_y() { while (!x.load(std::memory_order_seq_cst)) ; - if (y.load(std::memory_order_seq_cst)) { + if (y.load(std::memory_order_seq_cst)) ++z; - } } - + void read_y_then_x() { while (!y.load(std::memory_order_seq_cst)) ; - if (x.load(std::memory_order_seq_cst)) { + if (x.load(std::memory_order_seq_cst)) ++z; - } } - + int main() { std::thread a(write_x); @@ -458,14 +711,15 @@ std::thread c(read_x_then_y); std::thread d(read_y_then_x); a.join(); b.join(); c.join(); d.join(); - assert(z.load() != 0); // will never happen + assert(z.load() != 0); // will never happen } .SH Relationship with volatile - Within a thread of execution, accesses (reads and writes) to all volatile objects - are guaranteed to not be reordered relative to each other, but this order is not - guaranteed to be observed by another thread, since volatile access does not + Within a thread of execution, accesses (reads and writes) through volatile glvalues + cannot be reordered past observable side-effects (including other volatile accesses) + that are sequenced-before or sequenced-after within the same thread, but this order + is not guaranteed to be observed by another thread, since volatile access does not establish inter-thread synchronization. In addition, volatile accesses are not atomic (concurrent read and write is a data @@ -473,12 +727,30 @@ around the volatile access). One notable exception is Visual Studio, where, with default settings, every volatile - write has release semantics and every volatile read has acquire semantics (MSDN), - and thus volatiles may be used for inter-thread synchronization. Standard volatile - semantics are not applicable to multithreaded programming, although they are - sufficient for e.g. communication with a signal handler (see also - std::atomic_signal_fence) + write has release semantics and every volatile read has acquire semantics (Microsoft + Docs), and thus volatiles may be used for inter-thread synchronization. Standard + volatile semantics are not applicable to multithreaded programming, although they + are sufficient for e.g. communication with a std::signal handler that runs in the + same thread when applied to sig_atomic_t variables. -.SH Category: +.SH See also + + C documentation for + memory order +.SH External links + + 1. MOESI protocol + 2. x86-TSO: A Rigorous and Usable Programmer’s Model for x86 Multiprocessors P. + Sewell et. al., 2010 + 3. A Tutorial Introduction to the ARM and POWER Relaxed Memory Models P. Sewell et + al, 2012 + 4. MESIF: A Two-Hop Cache Coherency Protocol for Point-to-Point Interconnects J.R. + Goodman, H.H.J. Hum, 2009 + 5. Memory Models Russ Cox, 2021 + + This section is incomplete + Reason: Let's find good refs on QPI, MOESI, and maybe Dragon. + +.SH Category: * Todo with reason diff --git a/man/std::memset.3 b/man/std::memset.3 index f066842e2..3f4559945 100644 --- a/man/std::memset.3 +++ b/man/std::memset.3 @@ -1,13 +1,17 @@ -.TH std::memset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::memset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::memset \- std::memset + .SH Synopsis Defined in header void* memset( void* dest, int ch, std::size_t count ); - Converts the value ch to unsigned char and copies it into each of the first count - characters of the object pointed to by dest. If the object is not trivially-copyable - (e.g., scalar, array, or a C-compatible struct), the behavior is undefined. If count - is greater than the size of the object pointed to by dest, the behavior is - undefined. + Copies the value static_cast(ch) into each of the first count + characters of the object pointed to by dest. If the object is a + potentially-overlapping subobject or is not TriviallyCopyable (e.g., scalar, + C-compatible struct, or an array of trivially copyable type), the behavior is + undefined. If count is greater than the size of the object pointed to by dest, the + behavior is undefined. .SH Parameters @@ -19,32 +23,57 @@ dest +.SH Notes + + std::memset may be optimized away (under the as-if rules) if the object modified by + this function is not accessed again for the rest of its lifetime (e.g., gcc bug + 8537). For that reason, this function cannot be used to scrub memory (e.g., to fill + an array that stored a password with zeroes). + + Solutions for that include std::fill with volatile pointers, (C23) + memset_explicit(), (C11) memset_s, FreeBSD explicit_bzero or Microsoft + SecureZeroMemory. + .SH Example - + // Run this code - #include + #include + #include #include - + #include + int main() { - int a[20]; - std::memset(a, 0, sizeof(a)); - for (int ai : a) std::cout << ai; + int a[4]; + using bits = std::bitset; + std::memset(a, 0b1111'0000'0011, sizeof a); + for (int ai : a) + std::cout << bits(ai) << '\\n'; } .SH Output: - 00000000000000000000 + 00000011000000110000001100000011 + 00000011000000110000001100000011 + 00000011000000110000001100000011 + 00000011000000110000001100000011 .SH See also memcpy copies one buffer to another - \fI(function)\fP - fill_n assigns a value to a number of elements - \fI(function template)\fP + \fI(function)\fP + memmove moves one buffer to another + \fI(function)\fP + copies the given wide character to every position in a wide + wmemset character array + \fI(function)\fP + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + fill_n copy-assigns the given value to N elements in a range + \fI(function template)\fP is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP C documentation for memset diff --git a/man/std::merge.3 b/man/std::merge.3 index 843cad547..b85f57ff1 100644 --- a/man/std::merge.3 +++ b/man/std::merge.3 @@ -1,53 +1,101 @@ -.TH std::merge 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::merge \- std::merge + .SH Synopsis Defined in header - template< class InputIt1, class InputIt2, class OutputIt > + template< class InputIt1, class InputIt2, class OutputIt + > - OutputIt merge( InputIt1 first1, InputIt1 last1, \fB(1)\fP + OutputIt merge( InputIt1 first1, InputIt1 last1, \fB(1)\fP (constexpr since C++20) InputIt2 first2, InputIt2 last2, OutputIt d_first ); - template< class InputIt1, class InputIt2, class OutputIt, class Compare> + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + ForwardIt3 > + ForwardIt3 merge( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, + ForwardIt2 first2, ForwardIt2 last2, + + ForwardIt3 d_first ); + template< class InputIt1, class InputIt2, - OutputIt merge( InputIt1 first1, InputIt1 last1, \fB(2)\fP + class OutputIt, class Compare > + OutputIt merge( InputIt1 first1, InputIt1 last1, \fB(3)\fP (constexpr since C++20) InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class ForwardIt3, class Compare > + ForwardIt3 merge( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, + ForwardIt2 first2, ForwardIt2 last2, + + ForwardIt3 d_first, Compare comp ); Merges two sorted ranges [first1, last1) and [first2, last2) into one sorted range - beginning at d_first. The first version uses operator< to compare the elements, the - second version uses the given comparison function comp. The relative order of - equivalent elements is preserved. + beginning at d_first. + + 1) If [first1, last1) or [first2, last2) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first1, last1) or [first2, last2) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if - The behavior is undefined if the destination range overlaps either of the input - ranges (the input ranges may overlap each other). + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + This merge function is stable, which means that for equivalent elements in the + original two ranges, the elements from the first range (preserving their original + order) precede the elements from the second range (preserving their original order). + + If the output range overlaps with [first1, last1) or [first2, last2), the behavior + is undefined. .SH Parameters first1, last1 - the first range of elements to merge first2, last2 - the second range of elements to merge d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. + converted to both Type1 and Type2. .SH Type requirements - - InputIt1 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. - - InputIt2 must meet the requirements of InputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - OutputIt must meet the requirements of OutputIterator. + Compare must meet the requirements of Compare. .SH Return value @@ -55,45 +103,88 @@ .SH Complexity - At most std::distance(first1, last1) + std::distance(first2, last2) - 1 comparisons. + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1) At most \\(\\scriptsize N_1+N_2-1\\)N + 1+N + 2-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) \\(\\scriptsize O(N_1+N_2)\\)O(N + 1+N + 2) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) At most \\(\\scriptsize N_1+N_2-1\\)N + 1+N + 2-1 applications of the comparison function comp. + 4) \\(\\scriptsize O(N_1+N_2)\\)O(N + 1+N + 2) applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + See also the implementations in libstdc++ and libc++. + + merge \fB(1)\fP template OutputIt merge(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, OutputIt d_first) { - for (; first1 != last1; ++d_first) { - if (first2 == last2) { + for (; first1 != last1; ++d_first) + { + if (first2 == last2) return std::copy(first1, last1, d_first); - } - if (*first2 < *first1) { + + if (*first2 < *first1) + { *d_first = *first2; ++first2; - } else { + } + else + { *d_first = *first1; ++first1; } } return std::copy(first2, last2, d_first); } -.SH Second version + merge \fB(3)\fP template OutputIt merge(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp) { - for (; first1 != last1; ++d_first) { - if (first2 == last2) { + for (; first1 != last1; ++d_first) + { + if (first2 == last2) return std::copy(first1, last1, d_first); - } - if (comp(*first2, *first1)) { + + if (comp(*first2, *first1)) + { *d_first = *first2; ++first2; - } else { + } + else + { *d_first = *first1; ++first1; } @@ -101,64 +192,94 @@ return std::copy(first2, last2, d_first); } +.SH Notes + + This algorithm performs a similar task as std::set_union does. Both consume two + sorted input ranges and produce a sorted output with elements from both inputs. The + difference between these two algorithms is with handling values from both input + ranges which compare equivalent (see notes on LessThanComparable). If any equivalent + values appeared n times in the first range and m times in the second, std::merge + would output all n + m occurrences whereas std::set_union would output std::max(n, + m) ones only. So std::merge outputs exactly std::distance(first1, last1) + + std::distance(first2, last2) values and std::set_union may produce fewer. + .SH Example - + // Run this code + #include + #include #include #include - #include - #include #include - + #include + + auto print = [](const auto rem, const auto& v) + { + std::cout << rem; + std::copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + }; + int main() { // fill the vectors with random numbers std::random_device rd; std::mt19937 mt(rd()); std::uniform_int_distribution<> dis(0, 9); - + std::vector v1(10), v2(10); std::generate(v1.begin(), v1.end(), std::bind(dis, std::ref(mt))); std::generate(v2.begin(), v2.end(), std::bind(dis, std::ref(mt))); - - // sort + + print("Originally:\\nv1: ", v1); + print("v2: ", v2); + std::sort(v1.begin(), v1.end()); std::sort(v2.begin(), v2.end()); - - // output v1 - std::cout << "v1 : "; - std::copy(v1.begin(), v1.end(), std::ostream_iterator(std::cout, " ")); - std::cout << '\\n'; - - // output v2 - std::cout << "v2 : "; - std::copy(v2.begin(), v2.end(), std::ostream_iterator(std::cout, " ")); - std::cout << '\\n'; - + + print("After sorting:\\nv1: ", v1); + print("v2: ", v2); + // merge std::vector dst; std::merge(v1.begin(), v1.end(), v2.begin(), v2.end(), std::back_inserter(dst)); - - // output - std::cout << "dst: "; - std::copy(dst.begin(), dst.end(), std::ostream_iterator(std::cout, " ")); - std::cout << '\\n'; + + print("After merging:\\ndst: ", dst); } .SH Possible output: - v1 : 0 1 3 4 4 5 5 8 8 9 - v2 : 0 2 2 3 6 6 8 8 8 9 - dst: 0 0 1 2 2 3 3 4 4 5 5 6 6 8 8 8 8 8 9 9 + Originally: + v1: 2 6 5 7 4 2 2 6 7 0 + v2: 8 3 2 5 0 1 9 6 5 0 + After sorting: + v1: 0 2 2 2 4 5 6 6 7 7 + v2: 0 0 1 2 3 5 5 6 8 9 + After merging: + dst: 0 0 0 1 2 2 2 2 3 4 5 5 5 6 6 6 7 7 8 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 780 C++98 the merge operation was not defined defined .SH See also inplace_merge merges two ordered ranges in-place - \fI(function template)\fP + \fI(function template)\fP + is_sorted checks whether a range is sorted into ascending order + \fI(C++11)\fP \fI(function template)\fP + set_union computes the union of two sets + \fI(function template)\fP sort sorts a range into ascending order - \fI(function template)\fP + \fI(function template)\fP sorts a range of elements while preserving order between equal stable_sort elements - \fI(function template)\fP + \fI(function template)\fP + ranges::merge merges two sorted ranges + (C++20) (niebloid) diff --git a/man/std::mergeable.3 b/man/std::mergeable.3 new file mode 100644 index 000000000..a8aa03e6e --- /dev/null +++ b/man/std::mergeable.3 @@ -0,0 +1,40 @@ +.TH std::mergeable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mergeable \- std::mergeable + +.SH Synopsis + Defined in header + template< class I1, class I2, class Out, class Comp = ranges::less, + + class Proj1 = std::identity, class Proj2 = std::identity > + concept mergeable = + std::input_iterator && + std::input_iterator && + std::weakly_incrementable && \fI(since C++20)\fP + std::indirectly_copyable && + std::indirectly_copyable && + std::indirect_strict_weak_order, + + std::projected>; + + The mergeable concept specifies the requirements for algorithms that merge two input + ranges into a single output range according to the strict weak ordering imposed by + Comp. + + Semantic requirements + + mergeable is modeled only if all concepts it subsumes are modeled. + +.SH See also + + ranges::merge merges two sorted ranges + (C++20) (niebloid) + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::set_intersection computes the intersection of two sets + (C++20) (niebloid) + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) + ranges::set_symmetric_difference computes the symmetric difference between two sets + (C++20) (niebloid) diff --git a/man/std::mersenne_twister_engine.3 b/man/std::mersenne_twister_engine.3 index 8fc926955..9c154dac8 100644 --- a/man/std::mersenne_twister_engine.3 +++ b/man/std::mersenne_twister_engine.3 @@ -1,115 +1,226 @@ -.TH std::mersenne_twister_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine \- std::mersenne_twister_engine + .SH Synopsis Defined in header template< - class UIntType, - size_t w, size_t n, size_t m, size_t r, - UIntType a, size_t u, UIntType d, size_t s, \fI(since C++11)\fP - UIntType b, size_t t, - UIntType c, size_t l, UIntType f + class UIntType, std::size_t w, std::size_t n, std::size_t m, + std::size_t r, \fI(since C++11)\fP + UIntType a, std::size_t u, UIntType d, std::size_t s, + UIntType b, std::size_t t, UIntType c, std::size_t l, UIntType f > class mersenne_twister_engine; mersenne_twister_engine is a random number engine based on Mersenne Twister - algorithm. It produces high quality unsigned integer random numbers. - - The following typedefs define the random number engine with two commonly used + algorithm. It produces high quality, but not cryptographically secure, unsigned + integer random numbers of type UIntType on the interval \\(\\scriptsize {[0,2^w)}\\)[0, + 2w + ). + +.SH Template parameters + + The result type generated by the generator. The effect is + UIntType - undefined if this is not one of unsigned short, unsigned int, + unsigned long, or unsigned long long. + w - the power of two that determines the range of values generated + by the engine + n - the degree of recurrence + m - the middle word, an offset used in the recurrence relation + defining the state + r - the number of bits of the lower bit-mask, also known as the + twist value + a - the conditional xor-mask, i.e. the coefficients of the + rational normal form twist matrix + u, d, s, b, t, c, l - the 1^st to 7^th components of the bit-scrambling (tempering) + matrix + f - the initialization multiplier + + If any of the following restriction is violated, the program is ill-formed: + + * m is in [1, n]. + * The following expressions are all true: + + * w >= 3 + * w >= r + * w >= u + * w >= s + * w >= t + * w >= l + * w <= std::numeric_limits::digits + * Given (1u << w) - 1u as w1, the following expressions are all true: + + * a <= w1 + * b <= w1 + * c <= w1 + * d <= w1 + * f <= w1 + + Generator properties + + The size of the states of mersenne_twister_engine is n, each of them consists of a + sequence X of n values of type result_type. \\(X_j\\)X + j stands for the \\(j\\mod n\\)j mod nth value (starting from 0) of X. + + Given the following bitwise operation notations: + + * \\(\\mathsf{bitand}\\)bitand, built-in bitwise AND. + * \\(\\mathsf{xor}\\)xor, built-in bitwise XOR. + * \\(\\mathsf{lshift}\\)lshift, built-in bitwise left-shift. + * \\(\\mathsf{rshift}\\)rshift, built-in bitwise right-shift. + + The transition algorithm of mersenne_twister_engine (\\(TA(x_i)\\)TA(x + i)) is defined as follows: + + 1. Concatenate the upper w - r bits of \\(X_{i-n}\\)X + i-n with the lower r bits of \\(X_{i+1-n}\\)X + i+1-n to obtain an unsigned integer value Y. + 2. Let y be \\(a \\cdot (Y\\ \\mathsf{bitand}\\ 1)\\)a·(Y bitand 1), and set \\(X_i\\)X + i to \\(X_{i+m−n}\\ \\mathsf{xor}\\ (Y\\ \\mathsf{rshift}\\ 1)\\ \\mathsf{xor}\\ y\\)X + i+m−n xor (Y rshift 1) xor y. + + The generation algorithm of mersenne_twister_engine (\\(GA(x_i)\\)GA(x + i)) is defined as follows: + + 1. Let \\(z_1\\)z + 1 be \\(X_i\\ \\mathsf{xor}\\ ((X_i\\ \\mathsf{rshift}\\ u)\\ \\mathsf{bitand}\\ d)\\)X + i xor ((X + i rshift u) bitand d). + 2. Let \\(z_2\\)z + 2 be \\(z_1\\ \\mathsf{xor}\\ (((z_1\\ \\mathsf{lshift}\\ s)\\mod 2^w)\\ \\mathsf{bitand}\\ + b)\\)X + i xor (((X + i lshift s) mod 2w + ) bitand b). + 3. Let \\(z_3\\)z + 3 be \\(z_2\\ \\mathsf{xor}\\ (((z_2\\ \\mathsf{lshift}\\ t)\\mod 2^w)\\ \\mathsf{bitand}\\ + c)\\)X + i xor (((X + i lshift t) mod 2w + ) bitand c). + 4. Let \\(z_4\\)z + 4 be \\(z_3\\ \\mathsf{xor}\\ (z_3\\ \\mathsf{rshift}\\ l)\\)z + 3 xor (z + 3 rshift l). + 5. Deliver \\(z_4\\)z + 4 as the result (i.e. \\(GA(x_i)=z_4\\)GA(x + i)=z + 4). + + Predefined specializations + + The following specializations define the random number engine with two commonly used parameter sets: Defined in header - Type Definition - std::mersenne_twister_engine - 32-bit Mersenne Twister by Matsumoto and Nishimura, 1998 - std::mersenne_twister_engine - 64-bit Mersenne Twister by Matsumoto and Nishimura, 2000 - -.SH Member types - - Member type Definition - result_type The integral type generated by the engine. Results are undefined if this - is not an unsigned integral type. + Type Definition + std::mersenne_twister_engine + 32-bit Mersenne Twister by Matsumoto and Nishimura, 1998 + std::mersenne_twister_engine + 64-bit Mersenne Twister by Matsumoto and Nishimura, 2000 + + Nested types + + Type Definition + result_type UIntType + + Data members + + constexpr size_t word_size w + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t state_size n + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t shift_size m + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t mask_bits r + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType xor_mask a + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t tempering_u u + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType tempering_d d + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t tempering_s s + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType tempering_b b + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t tempering_t t + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType tempering_c c + \fB[static]\fP \fI(public static member constant)\fP + constexpr size_t tempering_l l + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType initialization_multiplier f + \fB[static]\fP \fI(public static member constant)\fP + constexpr UIntType default_seed 5489u + \fB[static]\fP \fI(public static member constant)\fP .SH Member functions .SH Construction and Seeding - constructor constructs the engine - \fI(public member function)\fP - seed sets the current state of the engine - \fI(public member function)\fP + constructor constructs the engine + \fI(C++11)\fP \fI(public member function)\fP + seed sets the current state of the engine + \fI(C++11)\fP \fI(public member function)\fP .SH Generation - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP - discard advances the engine's state by a specified amount - \fI(public member function)\fP + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP + discard advances the engine's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP .SH Non-member functions - operator== compares the internal states of two pseudo-random number engines - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number engine - operator>> \fI(function)\fP - -.SH Member objects - - constexpr size_t word_size This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t state_size This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t shift_size This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t mask_bits This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType xor_mask This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t tempering_u This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType tempering_d This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t tempering_s This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType tempering_b This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t tempering_t This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType tempering_c This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t tempering_l This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType initialization_multiplier This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType default_seed This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - -.SH Category: - - * Todo without reason + operator== compares the internal states of two pseudo-random number + operator!= engines + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> engine + \fI(C++11)\fP \fI(function template)\fP + +.SH Notes + + The N^th consecutive invocation of a default-constructed engine is required to + produce the following value: + + N The random engine type The value to produce + 10000 std::mt19937 4123659995 + 10000 std::mt19937_64 9981545732273789042 + + This is to guarantee that the random engine is conforming to the standard (see + N1398). + + +// Run this code + + #include + #include + + int main() + { + std::mt19937 gen32; + std::mt19937_64 gen64; + + gen32.discard(10000 - 1); + gen64.discard(10000 - 1); + + assert(gen32() == 4123659995); + assert(gen64() == 9981545732273789042ull); + } diff --git a/man/std::mersenne_twister_engine::discard.3 b/man/std::mersenne_twister_engine::discard.3 index fa663df5e..e305e7420 100644 --- a/man/std::mersenne_twister_engine::discard.3 +++ b/man/std::mersenne_twister_engine::discard.3 @@ -1,9 +1,12 @@ -.TH std::mersenne_twister_engine::discard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine::discard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine::discard \- std::mersenne_twister_engine::discard + .SH Synopsis void discard( unsigned long long z ); \fI(since C++11)\fP Advances the internal state by z times. Equivalent to calling operator() z times and - discarding the result + discarding the result. .SH Parameters @@ -15,13 +18,15 @@ .SH Complexity - This section is incomplete + No worse than the complexity of z consecutive calls to operator(). -.SH See also +.SH Notes - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP + For some engines, "fast jump" algorithms are known, which advance the state by many + steps (order of millions) without calculating intermediate state transitions, + although not necessarily in constant time. -.SH Category: +.SH See also - * Todo without reason + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::mersenne_twister_engine::max.3 b/man/std::mersenne_twister_engine::max.3 index a149370d1..795147eac 100644 --- a/man/std::mersenne_twister_engine::max.3 +++ b/man/std::mersenne_twister_engine::max.3 @@ -1,8 +1,13 @@ -.TH std::mersenne_twister_engine::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine::max \- std::mersenne_twister_engine::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP - Returns the maximum value potentially generated by the random-number engine. + Returns the maximum value potentially generated by the random-number engine. This + value is equal to 2w + - 1, where w is the template parameter also accessible as static member word_size. .SH Parameters @@ -14,9 +19,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::mersenne_twister_engine::mersenne_twister_engine.3 b/man/std::mersenne_twister_engine::mersenne_twister_engine.3 index 704552727..b105bb53c 100644 --- a/man/std::mersenne_twister_engine::mersenne_twister_engine.3 +++ b/man/std::mersenne_twister_engine::mersenne_twister_engine.3 @@ -1,28 +1,69 @@ -.TH std::mersenne_twister_engine::mersenne_twister_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine::mersenne_twister_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine::mersenne_twister_engine \- std::mersenne_twister_engine::mersenne_twister_engine + .SH Synopsis - explicit mersenne_twister_engine( result_type value = default_seed \fB(1)\fP \fI(since C++11)\fP - ); - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP - explicit mersenne_twister_engine( Sseq& s ); + mersenne_twister_engine() : \fB(1)\fP \fI(since C++11)\fP + mersenne_twister_engine(default_seed) {} + explicit mersenne_twister_engine( result_type value ); \fB(2)\fP \fI(since C++11)\fP + template< class SeedSeq > \fB(3)\fP \fI(since C++11)\fP + explicit mersenne_twister_engine( SeedSeq& seq ); + mersenne_twister_engine( const mersenne_twister_engine& \fB(4)\fP \fI(since C++11)\fP + other ); (implicitly declared) Constructs the pseudo-random number engine. - This section is incomplete + 1) The default constructor. + 2) Constructs the engine with a seed value value. Given \\(2^w\\)2w + as p, the engine's initial state is determined as follows: + 1. Sets \\(X_{-n}\\)X + -n to value % p. + 2. For each integer i in [i - n, -1], sets \\(X_i\\)X + i to \\([f \\cdot (X_{i-1}\\ \\mathsf{xor}\\ (X_{i-1}\\ \\mathsf{rshift}\\ (w-2)))+i\\mod + n]\\mod p\\)[f·(X + i-1 xor (X + i-1 rshift (w-2)))+i mod n] mod p, where \\(\\mathsf{xor}\\)xor and + \\(\\mathsf{rshift}\\)rshift stand for built-in bitwise XOR and bitwise right-shift + respectively. + 3) Constructs the engine with a seed sequence seq. Given std::size_t(w / 32) + 1 as + k, the engine's initial state is determined as follows: + 1. Creates an invented array object a of length n * k. + 2. Calls seq.generate(a + 0, a + n * k). + 3. For each integer i in [-n, -1], sets \\(X_{i}\\)X + i to \\((\\sum^{k-1}_{j=0} a_{k(i+n)+j} \\cdot 2^{32j}) \\mod 2^w\\)(∑k-1 + j=0 a + k(i+n)+j·232j + ) mod 2w + . + 4. If the most significant w − r bits of \\(X_{-n}\\)X + -n are zero, and if each of the other resulting \\(X_{i}\\)X + i is 0, changes \\(X_{-n}\\)X + -n to \\(2^{w-1}\\)2w-1 + . + This overload participates in overload resolution only if SeedSeq meets the + requirements of SeedSequence. + 4) The copy constructor. Upon construction, *this == other is true. .SH Parameters value - seed value to use in the initialization of the internal state - s - seed sequence to use in the initialization of the internal state + seq - seed sequence to use in the initialization of the internal state .SH Complexity - This section is incomplete + 1,2) \\(\\small{O(n)}\\)O(n). + 3) Same as the complexity of the seq.generate call. + 4) \\(\\small{O(n)}\\)O(n). -.SH See also + Defect reports - seed sets the current state of the engine - \fI(public member function)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also - * Todo without reason + seed sets the current state of the engine + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::mersenne_twister_engine::min.3 b/man/std::mersenne_twister_engine::min.3 index 816961a94..2b621a05b 100644 --- a/man/std::mersenne_twister_engine::min.3 +++ b/man/std::mersenne_twister_engine::min.3 @@ -1,8 +1,12 @@ -.TH std::mersenne_twister_engine::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine::min \- std::mersenne_twister_engine::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP - Returns the minimum value potentially generated by the random-number engine. + Returns the minimum value potentially generated by the random-number engine. This + value is equal to 0u. .SH Parameters @@ -10,13 +14,13 @@ .SH Return value - The maximum potentially generated value. + The minimum potentially generated value. .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::mersenne_twister_engine::operator().3 b/man/std::mersenne_twister_engine::operator().3 index ec7610d41..9fef00672 100644 --- a/man/std::mersenne_twister_engine::operator().3 +++ b/man/std::mersenne_twister_engine::operator().3 @@ -1,4 +1,7 @@ -.TH std::mersenne_twister_engine::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine::operator() \- std::mersenne_twister_engine::operator() + .SH Synopsis result_type operator()(); \fI(since C++11)\fP @@ -22,8 +25,7 @@ .SH See also discard advances the engine's state by a specified amount - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo without reason diff --git a/man/std::mersenne_twister_engine::seed.3 b/man/std::mersenne_twister_engine::seed.3 index b7d4d77db..92c4efa45 100644 --- a/man/std::mersenne_twister_engine::seed.3 +++ b/man/std::mersenne_twister_engine::seed.3 @@ -1,42 +1,48 @@ -.TH std::mersenne_twister_engine::seed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mersenne_twister_engine::seed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mersenne_twister_engine::seed \- std::mersenne_twister_engine::seed + .SH Synopsis void seed( result_type value = default_seed ); \fB(1)\fP \fI(since C++11)\fP - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP - void seed( Sseq& seq ); + template< class SeedSeq > \fB(2)\fP \fI(since C++11)\fP + void seed( SeedSeq& seq ); - Reinitializes the internal state of the random-number engine using new seed value. + Sets the state of the random-number engine. - This section is incomplete + 1) Right after the state is set, *this == std::mersenne_twister_engine(value) is + true. + 2) Right after the state is set, *this == std::mersenne_twister_engine(seq) is true. .SH Parameters - value - seed value to use in the initialization of the internal state - seq - seed sequence to use in the initialization of the internal state + value - seed value to use to set the state + seq - seed sequence to use to set the state .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Complexity - This section is incomplete + 1) Same as std::mersenne_twister_engine(value). + 2) Same as std::mersenne_twister_engine(seq). .SH Example - + // Run this code #include #include - + int main() { std::mt19937 gen; - + // Seed the engine with an unsigned int gen.seed(1); std::cout << "after seed by 1: " << gen() << '\\n'; - + // Seed the engine with two unsigned ints std::seed_seq sseq{1, 2}; gen.seed(sseq); @@ -47,7 +53,3 @@ after seed by 1: 1791095845 after seed by {1,2}: 3127717181 - -.SH Category: - - * Todo without reason diff --git a/man/std::messages.3 b/man/std::messages.3 index 5273c6bbe..04488b982 100644 --- a/man/std::messages.3 +++ b/man/std::messages.3 @@ -1,8 +1,14 @@ -.TH std::messages 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages \- std::messages + .SH Synopsis Defined in header - template< class CharT > - class messages; + template< + + class CharT + + > class messages; Class template std::messages is a standard locale facet that encapsulates retrieval of strings from message catalogs, such as the ones provided by GNU gettext or by @@ -11,20 +17,18 @@ The source of the messages is implementation-defined. std-messages-inheritance.svg - About this image Inheritance diagram - Two standalone (locale-independent) specializations are provided by the standard - library: +.SH Specializations + + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header std::messages accesses narrow string message catalog std::messages accesses wide string message catalog - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. - .SH Member types Member type Definition @@ -38,11 +42,11 @@ destructor destructs a messages facet \fI(protected member function)\fP open invokes do_open - \fI(public member function)\fP + \fI(public member function)\fP get invokes do_get - \fI(public member function)\fP + \fI(public member function)\fP close invokes do_close - \fI(public member function)\fP + \fI(public member function)\fP .SH Member objects @@ -52,20 +56,20 @@ .SH Protected member functions do_open opens a named message catalog - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_get retrieves a message from an open message catalog - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_close closes a message catalog - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP Inherited from std::messages_base Type Definition - catalog int + catalog /* unspecified signed integer type */ .SH See also messages_base defines messages catalog type - \fI(class template)\fP - messages_byname creates a messages facet for the named locale + \fI(class)\fP + messages_byname represents the system-supplied std::messages for the named locale \fI(class template)\fP diff --git a/man/std::messages::close,std::messages::do_close.3 b/man/std::messages::close,std::messages::do_close.3 index f28e8ee46..551280fd1 100644 --- a/man/std::messages::close,std::messages::do_close.3 +++ b/man/std::messages::close,std::messages::do_close.3 @@ -1,4 +1,7 @@ -.TH std::messages::close,std::messages::do_close 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages::close,std::messages::do_close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages::close,std::messages::do_close \- std::messages::close,std::messages::do_close + .SH Synopsis Defined in header public: \fB(1)\fP @@ -6,9 +9,8 @@ protected: \fB(2)\fP virtual void do_close( catalog c ) const; - 1) public member function, calls the protected virtual member function do_close of + 1) Public member function, calls the protected virtual member function do_close of the most derived class. - 2) Releases the implementation-defined resources associated with an open catalog that is designated by the value c of type catalog (inherited from std::messages_base), which was obtained from open(). @@ -29,21 +31,21 @@ .SH Example The following example demonstrated retrieval of messages: on a typical GNU/Linux - system it reads from /usr/share/locale/de/LC_MESSAGES/sed.mo + system it reads from /usr/share/locale/de/LC_MESSAGES/sed.mo. + - // Run this code #include #include - + int main() { std::locale loc("de_DE.utf8"); std::cout.imbue(loc); auto& facet = std::use_facet>(loc); auto cat = facet.open("sed", loc); - if(cat < 0 ) + if (cat < 0) std::cout << "Could not open german \\"sed\\" message catalog\\n"; else std::cout << "\\"No match\\" in German: " @@ -53,7 +55,7 @@ facet.close(cat); } -.SH Output: +.SH Possible output: "No match" in German: Keine Übereinstimmung "Memory exhausted" in German: Speicher erschöpft diff --git a/man/std::messages::get,do_get.3 b/man/std::messages::get,do_get.3 deleted file mode 100644 index 14b5a010b..000000000 --- a/man/std::messages::get,do_get.3 +++ /dev/null @@ -1,70 +0,0 @@ -.TH std::messages::get,do_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - public: - string_type get( catalog cat, int set, int msgid, const string_type& dfault ) \fB(1)\fP - const; - protected: - virtual string_type do_get( catalog cat, int set, int msgid, const string_type& \fB(2)\fP - dfault ) const; - - 1) Public member function, calls the protected virtual member function do_get of the - most derived class. - - 2) Obtains a message from the open message catalog cat using the values set, msgid - and dfault in implementation-defined manner. If the expected message is not found in - the catalog, returns a copy of dfault. - -.SH Parameters - - cat - identifier of message catalog obtained from open() and not yet passed to - close() - set - implementation-defined argument, message set in POSIX - msgid - implementation-defined argument, message id in POSIX - dfault - the string to look up in the catalog (if the catalog uses string look-up) - and also the string to return in case of a failure - -.SH Return value - - The message from the catalog or a copy of dfault if none was found. - -.SH Notes - - On POSIX systems, this function call usually translates to a call to catgets(), and - the parameters set, msgid, and dfault are passed to catgets() as-is. In GNU - libstdc++, this function ignores set and msgid and simply calls GNU gettext(dfault) - in the required locale. - -.SH Example - - The following example demonstrated retrieval of messages: on a typical GNU/Linux - system it reads from /usr/share/locale/de/LC_MESSAGES/sed.mo - - -// Run this code - - #include - #include - - int main() - { - std::locale loc("de_DE.utf8"); - std::cout.imbue(loc); - auto& facet = std::use_facet>(loc); - auto cat = facet.open("sed", loc); - if(cat < 0 ) - std::cout << "Could not open german \\"sed\\" message catalog\\n"; - else - std::cout << "\\"No match\\" in German: " - << facet.get(cat, 0, 0, "No match") << '\\n' - << "\\"Memory exhausted\\" in German: " - << facet.get(cat, 0, 0, "Memory exhausted") << '\\n'; - facet.close(cat); - } - -.SH Output: - - "No match" in German: Keine Übereinstimmung - "Memory exhausted" in German: Speicher erschöpft - -.SH See also diff --git a/man/std::messages::get,std::messages::do_get.3 b/man/std::messages::get,std::messages::do_get.3 new file mode 100644 index 000000000..91e187262 --- /dev/null +++ b/man/std::messages::get,std::messages::do_get.3 @@ -0,0 +1,72 @@ +.TH std::messages::get,std::messages::do_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages::get,std::messages::do_get \- std::messages::get,std::messages::do_get + +.SH Synopsis + Defined in header + public: + string_type get( catalog cat, int set, int msgid, const string_type& dfault ) \fB(1)\fP + const; + protected: + virtual string_type do_get( catalog cat, int set, int msgid, const string_type& \fB(2)\fP + dfault ) const; + + 1) Public member function, calls the protected virtual member function do_get of the + most derived class. + 2) Obtains a message from the open message catalog cat using the values set, msgid + and dfault in implementation-defined manner. If the expected message is not found in + the catalog, returns a copy of dfault. + +.SH Parameters + + cat - identifier of message catalog obtained from open() and not yet passed to + close() + set - implementation-defined argument, message set in POSIX + msgid - implementation-defined argument, message id in POSIX + dfault - the string to look up in the catalog (if the catalog uses string look-up) + and also the string to return in case of a failure + +.SH Return value + + The message from the catalog or a copy of dfault if none was found. + +.SH Notes + + On POSIX systems, this function call usually translates to a call to catgets(), and + the parameters set, msgid, and dfault are passed to catgets() as-is. In GNU + libstdc++, this function ignores set and msgid and simply calls GNU gettext(dfault) + in the required locale. + +.SH Example + + The following example demonstrated retrieval of messages: on a typical GNU/Linux + system it reads from /usr/share/locale/de/LC_MESSAGES/sed.mo. + + +// Run this code + + #include + #include + + int main() + { + std::locale loc("de_DE.utf8"); + std::cout.imbue(loc); + auto& facet = std::use_facet>(loc); + auto cat = facet.open("sed", loc); + if (cat < 0) + std::cout << "Could not open german \\"sed\\" message catalog\\n"; + else + std::cout << "\\"No match\\" in German: " + << facet.get(cat, 0, 0, "No match") << '\\n' + << "\\"Memory exhausted\\" in German: " + << facet.get(cat, 0, 0, "Memory exhausted") << '\\n'; + facet.close(cat); + } + +.SH Possible output: + + "No match" in German: Keine Übereinstimmung + "Memory exhausted" in German: Speicher erschöpft + +.SH See also diff --git a/man/std::messages::messages.3 b/man/std::messages::messages.3 index df4467ac7..35c49aa36 100644 --- a/man/std::messages::messages.3 +++ b/man/std::messages::messages.3 @@ -1,10 +1,13 @@ -.TH std::messages::messages 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages::messages 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages::messages \- std::messages::messages + .SH Synopsis Defined in header explicit messages( std::size_t refs = 0 ); Creates a std::messages facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::messages::open,std::messages::do_open.3 b/man/std::messages::open,std::messages::do_open.3 index 9d57a0af5..dd6f922c7 100644 --- a/man/std::messages::open,std::messages::do_open.3 +++ b/man/std::messages::open,std::messages::do_open.3 @@ -1,4 +1,7 @@ -.TH std::messages::open,std::messages::do_open 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages::open,std::messages::do_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages::open,std::messages::do_open \- std::messages::open,std::messages::do_open + .SH Synopsis Defined in header public: @@ -10,7 +13,6 @@ 1) Public member function, calls the protected virtual member function do_open of the most derived class. - 2) Obtains a value of type catalog (inherited from std::messages_base), which can be passed to get() to retrieve messages from the message catalog named by name. This value is usable until passed to close(). @@ -41,21 +43,21 @@ .SH Example The following example demonstrated retrieval of messages: on a typical GNU/Linux - system it reads from /usr/share/locale/de/LC_MESSAGES/sed.mo + system it reads from /usr/share/locale/de/LC_MESSAGES/sed.mo. + - // Run this code #include #include - + int main() { std::locale loc("de_DE.utf8"); std::cout.imbue(loc); auto& facet = std::use_facet>(loc); auto cat = facet.open("sed", loc); - if(cat < 0 ) + if (cat < 0) std::cout << "Could not open german \\"sed\\" message catalog\\n"; else std::cout << "\\"No match\\" in German: " @@ -65,7 +67,7 @@ facet.close(cat); } -.SH Output: +.SH Possible output: "No match" in German: Keine Übereinstimmung "Memory exhausted" in German: Speicher erschöpft diff --git a/man/std::messages::~messages.3 b/man/std::messages::~messages.3 index 1f75109a3..09c1bb0cb 100644 --- a/man/std::messages::~messages.3 +++ b/man/std::messages::~messages.3 @@ -1,4 +1,7 @@ -.TH std::messages::~messages 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages::~messages 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages::~messages \- std::messages::~messages + .SH Synopsis Defined in header protected: ~messages(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_messages : public std::messages { Destructible_messages(std::size_t refs = 0) : messages(refs) {} - ~Destructible_messages() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_messages dc; - // std::messages c; // compile error: protected destructor + // std::messages c; // compile error: protected destructor } diff --git a/man/std::messages_base.3 b/man/std::messages_base.3 index dc2ca00f9..9c3d3acad 100644 --- a/man/std::messages_base.3 +++ b/man/std::messages_base.3 @@ -1,4 +1,7 @@ -.TH std::messages_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages_base \- std::messages_base + .SH Synopsis Defined in header class messages_base; @@ -9,14 +12,21 @@ .SH Member types Member type Definition - catalog /*unspecified signed integer type*/ + catalog An unspecified signed integer type + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Notes + DR Applied to Behavior as published Correct behavior + LWG 2028 C++98 catalog was defined as int defined as an unspecified signed + integer type^[1] - catalog was erroneously specified as int in C++11, this was corrected in LWG issue - #2028 and included in C++14 + 1. ↑ The catalog type nl_catd used in POSIX messaging API is a typedef of an + unspecified type. .SH See also messages implements retrieval of strings from message catalogs - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::messages_byname.3 b/man/std::messages_byname.3 index 8eac9c7e1..11b768583 100644 --- a/man/std::messages_byname.3 +++ b/man/std::messages_byname.3 @@ -1,4 +1,7 @@ -.TH std::messages_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::messages_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::messages_byname \- std::messages_byname + .SH Synopsis Defined in header template< class CharT > @@ -7,7 +10,9 @@ std::messages_byname is a std::messages facet which encapsulates retrieval of strings from message catalogs of the locale specified at its construction. - Two specializations are provided by the standard library +.SH Specializations + + The standard library is guaranteed to provide the following specializations: Defined in header std::messages_byname narrow/multibyte message catalog access @@ -22,13 +27,13 @@ .SH Member functions constructor constructs a new messages_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a messages_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP + - - std::messages_byname::messages_byname +std::messages_byname::messages_byname explicit messages_byname( const char* name, std::size_t refs = 0 ); explicit messages_byname( const std::string& name, std::size_t refs = \fI(since C++11)\fP @@ -45,9 +50,9 @@ name - the name of the locale refs - the number of references that link to the facet - - std::messages_byname::~messages_byname + +std::messages_byname::~messages_byname protected: ~messages_byname(); @@ -59,8 +64,8 @@ Inherited from std::messages .SH Member types Member type Definition - char_type charT - string_type std::basic_string + char_type CharT + string_type std::basic_string .SH Member objects @@ -70,48 +75,50 @@ Inherited from std::messages .SH Member functions open invokes do_open - \fI(public member function of std::messages)\fP + \fI(public member function of std::messages)\fP get invokes do_get - \fI(public member function of std::messages)\fP + \fI(public member function of std::messages)\fP close invokes do_close - \fI(public member function of std::messages)\fP + \fI(public member function of std::messages)\fP .SH Protected member functions do_open opens a named message catalog - \fB[virtual]\fP \fI(virtual protected member function of std::messages)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::messages)\fP do_get retrieves a message from an open message catalog - \fB[virtual]\fP \fI(virtual protected member function of std::messages)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::messages)\fP do_close closes a message catalog - \fB[virtual]\fP \fI(virtual protected member function of std::messages)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::messages)\fP .SH Example - + // Run this code #include #include - + void try_with(const std::locale& loc) { - const std::messages& facet = std::use_facet >(loc) - ; + const std::messages& facet = std::use_facet>(loc); + std::messages::catalog cat = facet.open("sed", std::cout.getloc()); - if(cat < 0 ) + if (cat < 0) std::cout << "Could not open \\"sed\\" message catalog\\n"; else std::cout << "\\"No match\\" " << facet.get(cat, 0, 0, "No match") << '\\n' << "\\"Memory exhausted\\" " << facet.get(cat, 0, 0, "Memory exhausted") << '\\n'; + facet.close(cat); } + int main() { std::locale loc("en_US.utf8"); std::cout.imbue(loc); - + try_with(std::locale(loc, new std::messages_byname("de_DE.utf8"))); try_with(std::locale(loc, new std::messages_byname("fr_FR.utf8"))); try_with(std::locale(loc, new std::messages_byname("ja_JP.utf8"))); @@ -129,4 +136,4 @@ Inherited from std::messages .SH See also messages implements retrieval of strings from message catalogs - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::midpoint.3 b/man/std::midpoint.3 new file mode 100644 index 000000000..a5de3e9cd --- /dev/null +++ b/man/std::midpoint.3 @@ -0,0 +1,107 @@ +.TH std::midpoint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::midpoint \- std::midpoint + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++20)\fP + constexpr T midpoint( T a, T b ) noexcept; + template< class T > \fB(2)\fP \fI(since C++20)\fP + constexpr T* midpoint( T* a, T* b ); + + Computes the midpoint of the integers, floating-points, or pointers a and b. + + 1) This overload participates in overload resolution only if T is an arithmetic type + other than bool. + 2) This overload participates in overload resolution only if T is an object type. + Use of this overload is ill-formed if T is an incomplete type. + +.SH Parameters + + a, b - integers, floating-points, or pointer values + +.SH Return value + + 1) Half the sum of a and b. No overflow occurs. If a and b have integer type and the + sum is odd, the result is rounded towards a. If a and b have floating-point type, at + most one inexact operation occurs. + 2) If a and b point to, respectively, x[i] and x[j] of the same array object x (for + the purpose of pointer arithmetic), returns a pointer to x[i + (j - i) / 2] (or, + equivalently x[std::midpoint(i, j)]) where the division rounds towards zero. If a + and b do not point to elements of the same array object, the behavior is undefined. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Overload \fB(2)\fP can be simply implemented as return a + (b - a) / 2; on common + platforms. However, such implementation is not guaranteed to be portable, because + there may be some platforms where creating an array with number of elements greater + than PTRDIFF_MAX is possible, and b - a may result in undefined behavior even if + both b and a point to elements in the same array. + + Feature-test macro Value Std Feature + __cpp_lib_interpolate 201902L (C++20) std::lerp, std::midpoint + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::uint32_t a = std::numeric_limits::max(); + std::uint32_t b = std::numeric_limits::max() - 2; + + std::cout << "a: " << a << '\\n' + << "b: " << b << '\\n' + << "Incorrect (overflow and wrapping): " << (a + b) / 2 << '\\n' + << "Correct: " << std::midpoint(a, b) << "\\n\\n"; + + auto on_pointers = [](int i, int j) + { + char const* text = "0123456789"; + char const* p = text + i; + char const* q = text + j; + std::cout << "std::midpoint('" << *p << "', '" << *q << "'): '" + << *std::midpoint(p, q) << "'\\n"; + }; + + on_pointers(2, 4); + on_pointers(2, 5); + on_pointers(5, 2); + on_pointers(2, 6); + } + +.SH Output: + + a: 4294967295 + b: 4294967293 + Incorrect (overflow and wrapping): 2147483646 + Correct: 4294967294 + + std::midpoint('2', '4'): '3' + std::midpoint('2', '5'): '3' + std::midpoint('5', '2'): '4' + std::midpoint('2', '6'): '4' + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.10.16 Midpoint [numeric.ops.midpoint] + * C++20 standard (ISO/IEC 14882:2020): + + * 25.10.15 Midpoint [numeric.ops.midpoint] + +.SH See also + + lerp linear interpolation function + (C++20) \fI(function)\fP diff --git a/man/std::min.3 b/man/std::min.3 index ae507f0dd..74a11bcd0 100644 --- a/man/std::min.3 +++ b/man/std::min.3 @@ -1,116 +1,145 @@ -.TH std::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::min \- std::min + .SH Synopsis Defined in header - template< class T > \fB(1)\fP + template< class T > \fB(1)\fP (constexpr since C++14) const T& min( const T& a, const T& b ); - template< class T, class Compare > \fB(2)\fP + template< class T, class Compare > \fB(2)\fP (constexpr since C++14) const T& min( const T& a, const T& b, Compare comp ); template< class T > \fB(3)\fP \fI(since C++11)\fP - T min( std::initializer_list ilist ); + T min( std::initializer_list ilist ); (constexpr since C++14) template< class T, class Compare > \fB(4)\fP \fI(since C++11)\fP - T min( std::initializer_list ilist, Compare comp ); + T min( std::initializer_list ilist, Compare comp ); (constexpr since C++14) Returns the smaller of the given values. - 1-2) Returns the smaller of a and b. - 3-4) Returns the smallest of the values in initializer list ilist. - - The (1,3) versions use operator< to compare the values, the (2,4) versions use the - given comparison function comp. + 1,2) Returns the smaller of a and b. + 1) Uses operator< to compare the values. + If T is not LessThanComparable, the behavior is undefined. + 2) Use the comparison function comp to compare the values. + 3,4) Returns the smallest of the values in initializer list ilist. + If ilist.size() is zero, or T is not CopyConstructible, the behavior is undefined. + 3) Uses operator< to compare the values. + If T is not LessThanComparable, the behavior is undefined. + 4) Use the comparison function comp to compare the values. .SH Parameters a, b - the values to compare ilist - initializer list with the values to compare comparison function object (i.e. an object that satisfies the requirements - of Compare) which returns true if if a is less than b. + of Compare) which returns true if a is less than b. The signature of the comparison function should be equivalent to the following: - cmp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must - not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + cmp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type T can be - implicitly converted to both of them. -.SH Type requirements - - - T must meet the requirements of LessThanComparable. for the overloads \fB(1)\fP and \fB(3)\fP - - - T must meet the requirements of CopyConstructible. for the overloads \fB(3)\fP and \fB(4)\fP + implicitly converted to both of them. .SH Return value - 1-2) The smaller of a and b. If the values are equivalent, returns a. - - 3-4) The smallest value in ilist. If several values are equivalent to the smallest, + 1,2) The smaller of a and b. If the values are equivalent, returns a. + 3,4) The smallest value in ilist. If several values are equivalent to the smallest, returns the leftmost such value. .SH Complexity - 1-2) Constant - - 3-4) Linear in ilist.size() + 1) Exactly one comparison using operator<. + 2) Exactly one application of the comparison function comp. + 3,4) Given \\(\\scriptsize N\\)N as ilist.size(): + 3) Exactly \\(\\scriptsize N-1\\)N-1 comparisons using operator<. + 4) Exactly \\(\\scriptsize N-1\\)N-1 applications of the comparison function comp. .SH Possible implementation -.SH First version + min \fB(1)\fP template const T& min(const T& a, const T& b) { return (b < a) ? b : a; } -.SH Second version + min \fB(2)\fP template const T& min(const T& a, const T& b, Compare comp) { return (comp(b, a)) ? b : a; } - Third version + min \fB(3)\fP template - T min( std::initializer_list ilist) + T min(std::initializer_list ilist) { return *std::min_element(ilist.begin(), ilist.end()); } - Fourth version + min \fB(4)\fP template T min(std::initializer_list ilist, Compare comp) { return *std::min_element(ilist.begin(), ilist.end(), comp); } +.SH Notes + + Capturing the result of std::min by reference produces a dangling reference if one + of the parameters is a temporary and that parameter is returned: + + int n = -1; + const int& r = std::min(n + 2, n * 2); // r is dangling + .SH Example - + // Run this code #include #include - #include - + #include + int main() { - std::cout << "smaller of 1 and 9999: " << std::min(1, 9999) << '\\n' - << "smaller of 'a', and 'b': " << std::min('a', 'b') << '\\n' - << "shortest of \\"foo\\", \\"bar\\", and \\"hello\\": " << - std::min( { "foo", "bar", "hello" }, - [](const std::string& s1, const std::string& s2) { - return s1.size() < s2.size(); - }) << '\\n'; + std::cout << "smaller of 10 and 010 is " << std::min(10, 010) << '\\n' + << "smaller of 'd' and 'b' is '" << std::min('d', 'b') << "'\\n" + << "shortest of \\"foo\\", \\"bar\\", and \\"hello\\" is \\"" + << std::min({"foo", "bar", "hello"}, + [](const std::string_view s1, const std::string_view s2) + { + return s1.size() < s2.size(); + }) << "\\"\\n"; } .SH Output: - smaller of 1 and 9999: 1 - smaller of 'a', and 'b': a - shortest of "foo", "bar", and "hello": foo + smaller of 10 and 010 is 8 + smaller of 'd' and 'b' is 'b' + shortest of "foo", "bar", and "hello" is "foo" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 281 C++98 T was required to be CopyConstructible for not required + overloads (1,2) .SH See also - max returns the larger of two elements - \fI(function template)\fP - minmax returns the larger and the smaller of two elements - \fI(C++11)\fP \fI(function template)\fP + max returns the greater of the given values + \fI(function template)\fP + minmax returns the smaller and larger of two elements + \fI(C++11)\fP \fI(function template)\fP min_element returns the smallest element in a range - \fI(function template)\fP + \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + ranges::min returns the smaller of the given values + (C++20) (niebloid) diff --git a/man/std::min_element.3 b/man/std::min_element.3 index 4f7134e6b..b678d3792 100644 --- a/man/std::min_element.3 +++ b/man/std::min_element.3 @@ -1,34 +1,72 @@ -.TH std::min_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::min_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::min_element \- std::min_element + .SH Synopsis Defined in header - template< class ForwardIt > \fB(1)\fP - ForwardIt min_element( ForwardIt first, ForwardIt last ); - template< class ForwardIt, class Compare > \fB(2)\fP - ForwardIt min_element( ForwardIt first, ForwardIt last, Compare comp ); + template< class ForwardIt > + ForwardIt min_element( ForwardIt first, ForwardIt last \fB(1)\fP (constexpr since C++17) + ); + template< class ExecutionPolicy, class ForwardIt > - Finds the smallest element in the range [first, last). The first version uses - operator< to compare the values, the second version uses the given comparison - function comp. + ForwardIt min_element( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last + ); + template< class ForwardIt, class Compare > + + ForwardIt min_element( ForwardIt first, ForwardIt last, \fB(3)\fP (constexpr since C++17) + + Compare comp ); + template< class ExecutionPolicy, class ForwardIt, class + Compare > + + ForwardIt min_element( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt last, + + Compare comp ); + + Finds the smallest element in the range [first, last). + + 1) Elements are compared using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are compared using the comparison function comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - forward iterators defining the range to examine + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if a is less than b. + requirements of Compare) which returns true if the first argument is + less than the second. The signature of the comparison function should be equivalent to the following: - cmp - bool cmp(const Type1 &a, const Type2 &b); - - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of - them. + them. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value @@ -38,68 +76,99 @@ .SH Complexity - Exactly max(N-1,0) comparisons, where N = std::distance(first, last). + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize \\max(N-1,0)\\)max(N-1,0) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) Exactly \\(\\scriptsize \\max(N-1,0)\\)max(N-1,0) applications of the comparison + function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + min_element \fB(1)\fP template ForwardIt min_element(ForwardIt first, ForwardIt last) { - if (first == last) return last; - + if (first == last) + return last; + ForwardIt smallest = first; - ++first; - for (; first != last; ++first) { - if (*first < *smallest) { + + while (++first != last) + if (*first < *smallest) smallest = first; - } - } + return smallest; } -.SH Second version + min_element \fB(3)\fP template - ForwardIt min_element(ForwardIt first, ForwardIt last, - Compare comp) + ForwardIt min_element(ForwardIt first, ForwardIt last, Compare comp) { - if (first == last) return last; - + if (first == last) + return last; + ForwardIt smallest = first; - ++first; - for (; first != last; ++first) { - if (comp(*first, *smallest)) { + + while (++first != last) + if (comp(*first, *smallest)) smallest = first; - } - } + return smallest; } .SH Example - + // Run this code #include #include #include - + int main() { - std::vector v{3, 1, 4, 1, 5, 9}; - - std::vector::iterator result = std::min_element(std::begin(v), std::end(v)); - std::cout << "min element at: " << std::distance(std::begin(v), result); + std::vector v{3, 1, -4, 1, 5, 9}; + + std::vector::iterator result = std::min_element(v.begin(), v.end()); + std::cout << "min element has value " << *result << " and index [" + << std::distance(v.begin(), result) << "]\\n"; } .SH Output: - min element at: 1 + min element has value -4 and index [2] + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 212 C++98 the return value was not specified if returns last in this + [first, last) is empty case + LWG 2150 C++98 the iterator to the first non-greatest corrected the return + element was returned value .SH See also - max_element returns the largest element in a range - \fI(function template)\fP - minmax_element returns the smallest and the largest element in a range - \fI(C++11)\fP \fI(function template)\fP - min returns the smaller of two elements - \fI(function template)\fP + max_element returns the largest element in a range + \fI(function template)\fP + minmax_element returns the smallest and the largest elements in a range + \fI(C++11)\fP \fI(function template)\fP + min returns the smaller of the given values + \fI(function template)\fP + ranges::min_element returns the smallest element in a range + (C++20) (niebloid) diff --git a/man/std::minmax.3 b/man/std::minmax.3 index 1fc8d12a5..0848d9eb9 100644 --- a/man/std::minmax.3 +++ b/man/std::minmax.3 @@ -1,114 +1,155 @@ -.TH std::minmax 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::minmax 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::minmax \- std::minmax + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - std::pair minmax( const T& a, const T& b ); + template< class T > \fI(since C++11)\fP + std::pair minmax( const T& a, const \fB(1)\fP (constexpr since C++14) + T& b ); template< class T, class Compare > - std::pair minmax( const T& a, const T& b, \fB(2)\fP \fI(since C++11)\fP - Compare comp ); - template< class T > \fB(3)\fP \fI(since C++11)\fP - std::pair minmax( std::initializer_list ilist); + + std::pair minmax( const T& a, const \fB(2)\fP \fI(since C++11)\fP + T& b, (constexpr since C++14) + + Compare comp ); + template< class T > \fI(since C++11)\fP + std::pair minmax( std::initializer_list ilist \fB(3)\fP (constexpr since C++14) + ); template< class T, class Compare > - std::pair minmax( std::initializer_list ilist, Compare \fB(4)\fP \fI(since C++11)\fP - comp ); + \fI(since C++11)\fP + std::pair minmax( std::initializer_list ilist, \fB(4)\fP (constexpr since C++14) - Returns the lowest and the greatest of the given values. + Compare comp ); - 1-2) Returns the smaller and the greater of a and b. - 3-4) Returns the smallest and the greatest of the values in initializer list ilist. + Returns the lowest and the greatest of the given values. - The (1,3) versions use operator< to compare the values, whereas the (2,4) versions - use the given comparison function comp. + 1,2) Returns references to the smaller and the greater of a and b. + 1) Uses operator< to compare the values. + If T is not LessThanComparable, the behavior is undefined. + 2) Use the comparison function comp to compare the values. + 3,4) Returns the smallest and the greatest of the values in initializer list ilist. + If ilist.size() is zero, or T is not CopyConstructible, the behavior is undefined. + 3) Uses operator< to compare the values. + If T is not LessThanComparable, the behavior is undefined. + 4) Use the comparison function comp to compare the values. .SH Parameters a, b - the values to compare ilist - initializer list with the values to compare comparison function object (i.e. an object that satisfies the requirements - of Compare) which returns true if if a is less than b. + of Compare) which returns true if the first argument is less than the + second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object must - not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must not + modify the objects passed to it and must be able to accept all values of + type (possibly const) Type1 and Type2 regardless of value category (thus, + Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type T can be - implicitly converted to both of them. -.SH Type requirements - - - T must meet the requirements of LessThanComparable. for the overloads \fB(1)\fP and \fB(3)\fP - - - T must meet the requirements of CopyConstructible. for the overloads \fB(3)\fP and \fB(4)\fP + implicitly converted to both of them. .SH Return value - 1-2) Returns the result of std::make_pair(a, b) if a(a, b) if a < b or if a is + equivalent to b. Returns the result of std::pair(b, a) if b < a. + 3,4) A pair with the smallest value in ilist as the first element and the greatest as the second. If several elements are equivalent to the smallest, the leftmost such element is returned. If several elements are equivalent to the largest, the rightmost such element is returned. .SH Complexity - 1-2) Constant - 3-4) Linear in ilist.size() + 1) Exactly one comparison using operator<. + 2) Exactly one application of the comparison function comp. + 3,4) Given \\(\\scriptsize N\\)N as ilist.size(): + 3) At most \\(\\scriptsize \\frac{3N}{2}\\) + + 3N + 2 + + comparisons using operator<. + 4) At most \\(\\scriptsize \\frac{3N}{2}\\) + + 3N + 2 + + applications of the comparison function comp. .SH Possible implementation -.SH First version + minmax \fB(1)\fP template - std::pair minmax(const T& a, const T& b) + constexpr std::pair minmax(const T& a, const T& b) { - return (b < a) ? std::make_pair(b, a) - : std::make_pair(a, b); + return (b < a) ? std::pair(b, a) + : std::pair(a, b); } -.SH Second version + minmax \fB(2)\fP template - std::pair minmax(const T& a, const T& b, Compare comp) + constexpr std::pair minmax(const T& a, const T& b, Compare comp) { - return comp(b, a) ? std::make_pair(b, a) - : std::make_pair(a, b); + return comp(b, a) ? std::pair(b, a) + : std::pair(a, b); } - Third version - template< class T > - std::pair minmax( std::initializer_list ilist) + minmax \fB(3)\fP + template + constexpr std::pair minmax(std::initializer_list ilist) { auto p = std::minmax_element(ilist.begin(), ilist.end()); - return std::make_pair(*p.first, *p.second); + return std::pair(*p.first, *p.second); } - Fourth version - template< class T, class Compare > - std::pair minmax( std::initializer_list ilist, Compare comp ) + minmax \fB(4)\fP + template + constexpr std::pair minmax(std::initializer_list ilist, Compare comp) { auto p = std::minmax_element(ilist.begin(), ilist.end(), comp); - return std::make_pair(*p.first, *p.second); + return std::pair(*p.first, *p.second); } +.SH Notes + + For overloads (1,2), if one of the parameters is a temporary, the reference returned + becomes a dangling reference at the end of the full expression that contains the + call to minmax: + + int n = 1; + auto p = std::minmax(n, n + 1); + int m = p.first; // ok + int x = p.second; // undefined behavior + + // Note that structured bindings have the same issue + auto [mm, xx] = std::minmax(n, n + 1); + xx; // undefined behavior + .SH Example - + // Run this code #include - #include - #include #include #include - + #include + #include + int main() { - std::vector v {3, 1, 4, 1, 5, 9, 2, 6}; + std::vector v{3, 1, 4, 1, 5, 9, 2, 6}; std::srand(std::time(0)); std::pair bounds = std::minmax(std::rand() % v.size(), std::rand() % v.size()); - + std::cout << "v[" << bounds.first << "," << bounds.second << "]: "; - for (int i = bounds.first; i < bounds.second; ++i) { + for (int i = bounds.first; i < bounds.second; ++i) std::cout << v[i] << ' '; - } std::cout << '\\n'; } @@ -118,7 +159,11 @@ .SH See also - min returns the smaller of two elements - \fI(function template)\fP - max returns the larger of two elements - \fI(function template)\fP + min returns the smaller of the given values + \fI(function template)\fP + max returns the greater of the given values + \fI(function template)\fP + minmax_element returns the smallest and the largest elements in a range + \fI(C++11)\fP \fI(function template)\fP + ranges::minmax returns the smaller and larger of two elements + (C++20) (niebloid) diff --git a/man/std::minmax_element.3 b/man/std::minmax_element.3 index 91c55b5ea..ad644dfca 100644 --- a/man/std::minmax_element.3 +++ b/man/std::minmax_element.3 @@ -1,40 +1,76 @@ -.TH std::minmax_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::minmax_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::minmax_element \- std::minmax_element + .SH Synopsis Defined in header template< class ForwardIt > - - std::pair \fB(1)\fP + \fI(since C++11)\fP + std::pair \fB(1)\fP (constexpr since C++17) minmax_element( ForwardIt first, ForwardIt last ); + template< class ExecutionPolicy, class ForwardIt > + + std::pair \fB(2)\fP \fI(since C++17)\fP + minmax_element( ExecutionPolicy&& policy, + + ForwardIt first, ForwardIt last ); template< class ForwardIt, class Compare > - std::pair \fB(2)\fP + std::pair \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++17) + minmax_element( ForwardIt first, ForwardIt last, + Compare comp ); + template< class ExecutionPolicy, class ForwardIt, class + Compare > + + std::pair \fB(4)\fP \fI(since C++17)\fP + minmax_element( ExecutionPolicy&& policy, + + ForwardIt first, ForwardIt last, + Compare comp ); - minmax_element( ForwardIt first, ForwardIt last, Compare comp ); + Finds the smallest and greatest element in the range [first, last). - Finds the greatest and the smallest element in the range [first, last). The first - version uses operator< to compare the values, the second version uses the given - comparison function comp. + 1) Elements are compared using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are compared using the comparison function comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - forward iterators defining the range to examine + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if if *a is less than *b. + requirements of Compare) which returns true if the first argument is + less than the second. The signature of the comparison function should be equivalent to the following: - cmp - bool cmp(const Type1 &a, const Type2 &b); - - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + cmp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of - them. + them. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value @@ -47,79 +83,125 @@ .SH Complexity - At most max(floor(3/2(N−1)), 0) applications of the predicate, where N = - std::distance(first, last). + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize \\max(\\left\\lfloor \\frac{3}{2}(N-1) \\right\\rfloor, + 0)\\)max(⌊ + + 3 + 2 + + (N-1)⌋,0) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) At most \\(\\scriptsize \\max(\\left\\lfloor \\frac{3}{2}(N-1) \\right\\rfloor, + 0)\\)max(⌊ + + 3 + 2 + + (N-1)⌋,0) applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + minmax_element template std::pair minmax_element(ForwardIt first, ForwardIt last) { - typedef typename std::iterator_traits::value_type value_t; - return std::minmax_element(first, last, std::less()); + using value_type = typename std::iterator_traits::value_type; + return std::minmax_element(first, last, std::less()); } -.SH Second version + minmax_element template std::pair minmax_element(ForwardIt first, ForwardIt last, Compare comp) { - std::pair result(first, first); - - if (first == last) return result; - if (++first == last) return result; - - if (comp(*first, *result.first)) { - result.first = first; - } else { - result.second = first; - } - while (++first != last) { - ForwardIt i = first; - if (++first == last) { - if (comp(*i, *result.first)) result.first = i; - else if (!(comp(*i, *result.second))) result.second = i; + auto min = first, max = first; + + if (first == last || ++first == last) + return {min, max}; + + if (comp(*first, *min)) + min = first; + else + max = first; + + while (++first != last) + { + auto i = first; + if (++first == last) + { + if (comp(*i, *min)) + min = i; + else if (!(comp(*i, *max))) + max = i; break; - } else { - if (comp(*first, *i)) { - if (comp(*first, *result.first)) result.first = first; - if (!(comp(*i, *result.second))) result.second = i; - } else { - if (comp(*i, *result.first)) result.first = i; - if (!(comp(*first, *result.second))) result.second = first; + } + else + { + if (comp(*first, *i)) + { + if (comp(*first, *min)) + min = first; + if (!(comp(*i, *max))) + max = i; + } + else + { + if (comp(*i, *min)) + min = i; + if (!(comp(*first, *max))) + max = first; } } } - return result; + return {min, max}; } +.SH Notes + + This algorithm is different from std::make_pair(std::min_element(), + std::max_element()), not only in efficiency, but also in that this algorithm finds + the last biggest element while std::max_element finds the first biggest element. + .SH Example - + // Run this code #include #include - #include - + int main() { - std::vector v = { 3, 9, 1, 4, 2, 5, 9 }; - - auto result = std::minmax_element(v.begin(), v.end()); - std::cout << "min element at: " << (result.first - v.begin()) << '\\n'; - std::cout << "max element at: " << (result.second - v.begin()) << '\\n'; + const auto v = {3, 9, 1, 4, 2, 5, 9}; + const auto [min, max] = std::minmax_element(begin(v), end(v)); + + std::cout << "min = " << *min << ", max = " << *max << '\\n'; } .SH Output: - min element at: 2 - max element at: 6 + min = 1, max = 9 .SH See also - min_element returns the smallest element in a range - \fI(function template)\fP - max_element returns the largest element in a range - \fI(function template)\fP + min_element returns the smallest element in a range + \fI(function template)\fP + max_element returns the largest element in a range + \fI(function template)\fP + ranges::minmax_element returns the smallest and the largest elements in a range + (C++20) (niebloid) diff --git a/man/std::minus.3 b/man/std::minus.3 index fd2b8271a..f8d361ba4 100644 --- a/man/std::minus.3 +++ b/man/std::minus.3 @@ -1,58 +1,56 @@ -.TH std::minus 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::minus 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::minus \- std::minus + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct minus; - template< class T = void > \fI(since C++14)\fP - struct minus; - - Function object for performing subtraction. Effectively calls operator- on two - instances of type T. - -.SH Specializations + template<> \fI(since C++14)\fP + class minus; - The standard library provides a specialization of std::minus when T is - not specified, which leaves the parameter types and return type to be + std::minus is a specialization of std::minus with parameter and return type deduced. - \fI(since C++14)\fP - function object implementing x - y deducing argument and - minus return types - \fI(class template specialization)\fP - -.SH Member types - - Type Definition - result_type T - first_argument_type T - second_argument_type T .SH Member functions - operator() returns the difference between two arguments + operator() returns the difference of two arguments \fI(public member function)\fP - std::minus::operator() +std::minus::operator() - T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + template< class T, class U > - Returns the difference between lhs and rhs. + constexpr auto operator()( T&& lhs, U&& rhs ) const + + -> decltype(std::forward(lhs) - std::forward(rhs)); + + Returns the difference of lhs and rhs. .SH Parameters - lhs, rhs - values to subtract from one another + lhs, rhs - values to subtract .SH Return value - The result of lhs - rhs. + std::forward(lhs) - std::forward(rhs). + +.SH Example + + +// Run this code -.SH Exceptions + #include + #include + #include - \fI(none)\fP + int main() + { + auto complex_minus = std::minus{}; // “void” can be omitted + constexpr std::complex z(4, 2); + std::cout << complex_minus(z, 1) << '\\n'; + std::cout << (z - 1) << '\\n'; + } -.SH Possible implementation +.SH Output: - constexpr T operator()(const T &lhs, const T &rhs) const - { - return lhs - rhs; - } + (3,2) + (3,2) diff --git a/man/std::minus.3 b/man/std::minus.3 deleted file mode 100644 index d1347f413..000000000 --- a/man/std::minus.3 +++ /dev/null @@ -1,55 +0,0 @@ -.TH std::minus 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class minus; - - std::minus<> is a specialization of std::minus with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() returns the difference of two arguments - \fI(public member function)\fP - - std::minus<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) - std::forward(rhs)); - - Returns the result of subtracting rhs from lhs (or whatever operator- if overloaded - to do) - -.SH Parameters - - lhs, rhs - values to subtract - -.SH Return value - - The result of lhs - rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::mismatch.3 b/man/std::mismatch.3 index 0e3fb3b25..25015635c 100644 --- a/man/std::mismatch.3 +++ b/man/std::mismatch.3 @@ -1,44 +1,95 @@ -.TH std::mismatch 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mismatch 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mismatch \- std::mismatch + .SH Synopsis Defined in header template< class InputIt1, class InputIt2 > - std::pair \fB(1)\fP + std::pair \fB(1)\fP (constexpr since C++20) mismatch( InputIt1 first1, InputIt1 last1, InputIt2 first2 ); - template< class InputIt1, class InputIt2, class BinaryPredicate > + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > - std::pair - mismatch( InputIt1 first1, InputIt1 last1, \fB(2)\fP - InputIt2 first2, + std::pair \fB(2)\fP \fI(since C++17)\fP + mismatch( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, - BinaryPredicate p ); - template< class InputIt1, class InputIt2 > + ForwardIt2 first2 ); + template< class InputIt1, class InputIt2, class + BinaryPred > - std::pair \fB(3)\fP \fI(since C++14)\fP + std::pair \fB(3)\fP (constexpr since C++20) mismatch( InputIt1 first1, InputIt1 last1, + InputIt2 first2, BinaryPred p ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + BinaryPred > + std::pair \fB(4)\fP \fI(since C++17)\fP + mismatch( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, + + ForwardIt2 first2, BinaryPred p ); + template< class InputIt1, class InputIt2 > + + std::pair \fB(5)\fP \fI(since C++14)\fP + mismatch( InputIt1 first1, InputIt1 last1, (constexpr since C++20) + InputIt2 first2, InputIt2 last2 ); - template< class InputIt1, class InputIt2, class BinaryPredicate > + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > + + std::pair \fB(6)\fP \fI(since C++17)\fP + mismatch( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, + + ForwardIt2 first2, ForwardIt2 last2 ); + template< class InputIt1, class InputIt2, class + BinaryPred > + + std::pair \fB(7)\fP \fI(since C++14)\fP + mismatch( InputIt1 first1, InputIt1 last1, (constexpr since C++20) - std::pair - mismatch( InputIt1 first1, InputIt1 last1, \fB(4)\fP \fI(since C++14)\fP InputIt2 first2, InputIt2 last2, + BinaryPred p ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + BinaryPred > + std::pair \fB(8)\fP \fI(since C++17)\fP + mismatch( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, - BinaryPredicate p ); + ForwardIt2 first2, ForwardIt2 last2, + BinaryPred p ); - Returns the first mismatching pair of elements from two ranges: one defined by - [first1, last1) and another defined by [first2,last2). If last2 is not provided - (overloads \fB(1)\fP and \fB(2)\fP), it denotes first2 + (last1 - first1). + Returns a pair of iterators to the first mismatching of elements from + [first1, last1) and a range starting from first2: - Overloads \fB(1)\fP and \fB(3)\fP use operator== to compare the elements, the overloads \fB(2)\fP and - \fB(4)\fP use the given binary predicate p. + * For overloads (1-4), the second range has std::distance(first1, last1) elements. + * For overloads (5-8), the second range is [first2, last2). + + * If std::distance(first1, last1) and std::distance(first2, last2) are different, + the comparison stops when last1 or last2 is reached. + 1,5) Elements are compared using operator==. + 3,7) Elements are compared using the given binary predicate p. + 2,4,6,8) Same as (1,3,5,7), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first1, last1 - the first range of the elements first2, last2 - the second range of the elements + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -46,58 +97,108 @@ following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must - not modify the objects passed to it. + + p - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. - - .SH Type requirements - - InputIt1 must meet the requirements of InputIterator. + InputIt1 must meet the requirements of LegacyInputIterator. + - + InputIt2 must meet the requirements of LegacyInputIterator. - - InputIt2 must meet the requirements of InputIterator. + ForwardIt1 must meet the requirements of LegacyForwardIterator. - - BinaryPredicate must meet the requirements of BinaryPredicate. + ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + BinaryPred must meet the requirements of BinaryPredicate. .SH Return value - std::pair with iterators to the first two non-equivalent elements. + std::pair with iterators to the first two non-equal elements. + + If last1 is reached, the second iterator in the pair is the std::distance(first1, + last1) + th iterator after first2. - If no mismatches are found when the comparison reaches last1, the pair - holds last1 and the corresponding iterator from the second range. The \fI(until C++14)\fP - behavior is undefined if the second range is shorter than the first - range. - If no mismatches are found when the comparison reaches last1 or last2, - whichever happens first, the pair holds the end iterator and the \fI(since C++14)\fP - corresponding iterator from the other range. + For overloads (5-8), if last2 is reached, the first iterator in the pair is the + std::distance(first2, last2) + th iterator after first1. .SH Complexity - At most last1 - first1 applications of the predicate + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize N_1\\)N + 1 comparisons using operator==. + 3,4) At most \\(\\scriptsize N_1\\)N + 1 applications of the predicate p. + 5,6) At most \\(\\scriptsize \\min(N_1,N_2)\\)min(N + 1,N + 2) comparisons using operator==. + 7,8) At most \\(\\scriptsize \\min(N_1,N_2)\\)min(N + 1,N + 2) applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + mismatch \fB(1)\fP template std::pair mismatch(InputIt1 first1, InputIt1 last1, InputIt2 first2) { - while (first1 != last1 && *first1 == *first2) { + while (first1 != last1 && *first1 == *first2) ++first1, ++first2; - } + return std::make_pair(first1, first2); } -.SH Second version - template + mismatch \fB(3)\fP + template std::pair - mismatch(InputIt1 first1, InputIt1 last1, InputIt2 first2, BinaryPredicate p) + mismatch(InputIt1 first1, InputIt1 last1, InputIt2 first2, BinaryPred p) { - while (first1 != last1 && p(*first1, *first2)) { + while (first1 != last1 && p(*first1, *first2)) ++first1, ++first2; - } + + return std::make_pair(first1, first2); + } + mismatch \fB(5)\fP + template + std::pair + mismatch(InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2) + { + while (first1 != last1 && first2 != last2 && *first1 == *first2) + ++first1, ++first2; + + return std::make_pair(first1, first2); + } + mismatch \fB(7)\fP + template + std::pair + mismatch(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, BinaryPred p) + { + while (first1 != last1 && first2 != last2 && p(*first1, *first2)) + ++first1, ++first2; + return std::make_pair(first1, first2); } @@ -105,21 +206,21 @@ This program determines the longest substring that is simultaneously found at the very beginning of the given string and at the very end of it, in reverse order - (possibly overlapping) + (possibly overlapping). + - // Run this code + #include #include #include - #include - + std::string mirror_ends(const std::string& in) { return std::string(in.begin(), std::mismatch(in.begin(), in.end(), in.rbegin()).first); } - + int main() { std::cout << mirror_ends("abXYZba") << '\\n' @@ -136,13 +237,15 @@ .SH See also equal determines if two sets of elements are the same - \fI(function template)\fP + \fI(function template)\fP find find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if_not \fI(function template)\fP \fI(C++11)\fP returns true if one range is lexicographically less than lexicographical_compare another - \fI(function template)\fP + \fI(function template)\fP search searches for a range of elements - \fI(function template)\fP + \fI(function template)\fP + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) diff --git a/man/std::mktime.3 b/man/std::mktime.3 index 1a6296f99..61707927d 100644 --- a/man/std::mktime.3 +++ b/man/std::mktime.3 @@ -1,11 +1,14 @@ -.TH std::mktime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mktime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mktime \- std::mktime + .SH Synopsis Defined in header std::time_t mktime( std::tm* time ); - Converts local calendar time to a time since epoch as a time_t object. time->tm_wday - and time->tm_yday are ignored. The values in time are not checked for being out of - range. + Converts local calendar time to a time since epoch as a std::time_t object. + time->tm_wday and time->tm_yday are ignored. The values in time are permitted to be + outside their normal ranges. A negative value of time->tm_isdst causes mktime to attempt to determine if Daylight Saving Time was in effect. @@ -23,35 +26,48 @@ Time since epoch as a std::time_t object on success or -1 if time cannot be represented as a std::time_t object. +.SH Notes + + If the std::tm object was obtained from std::get_time or the POSIX strptime, the + value of tm_isdst is indeterminate, and needs to be set explicitly before calling + mktime. + .SH Example - Display the time 100 months ago + Construct a local time explicitly. + - // Run this code - #include - #include #include - + #include + #include + #include + int main() { - std::time_t t = std::time(NULL); - std::tm tm = *std::localtime(&t); - std::cout << "Today is " << std::put_time(&tm, "%c %Z") <<'\\n'; - tm.tm_mon -= 100; - std::mktime(&tm); - std::cout << "100 months ago was " << std::put_time(&tm, "%c %Z") << '\\n'; + setenv("TZ", "/usr/share/zoneinfo/America/Los_Angeles", 1); // POSIX-specific + + std::tm tm{}; // Zero initialise + tm.tm_year = 2020 - 1900; // 2020 + tm.tm_mon = 2 - 1; // February + tm.tm_mday = 15; // 15th + tm.tm_hour = 10; + tm.tm_min = 15; + tm.tm_isdst = 0; // Not daylight saving + std::time_t t = std::mktime(&tm); + std::tm local = *std::localtime(&t); + + std::cout << "local: " << std::put_time(&local, "%c %Z") << '\\n'; } -.SH Output: +.SH Possible output: - Today is Wed Dec 28 09:56:10 2011 EST - 100 months ago was Thu Aug 28 10:56:10 2003 EDT + local: Sat Feb 15 10:15:00 2020 PST .SH See also localtime converts time since epoch to calendar time expressed as local time - \fI(function)\fP + \fI(function)\fP C documentation for mktime diff --git a/man/std::modf,std::modff,std::modfl.3 b/man/std::modf,std::modff,std::modfl.3 new file mode 100644 index 000000000..470fca52f --- /dev/null +++ b/man/std::modf,std::modff,std::modfl.3 @@ -0,0 +1,136 @@ +.TH std::modf,std::modff,std::modfl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::modf,std::modff,std::modfl \- std::modf,std::modff,std::modfl + +.SH Synopsis + Defined in header + float modf ( float num, float* iptr ); + + double modf ( double num, double* iptr ); (until C++23) + + long double modf ( long double num, long double* + iptr ); + constexpr /* floating-point-type */ + + modf ( /* floating-point-type */ num, (since C++23) + \fB(1)\fP + /* floating-point-type */* iptr + ); + float modff( float num, float* iptr ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double modfl( long double num, long double* \fB(3)\fP \fI(since C++11)\fP + iptr ); (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double modf ( Integer num, double* iptr ); + + 1-3) Decomposes given floating point value num into integral and fractional parts, + each having the same type and sign as num. The integral part (in floating-point + format) is stored in the object pointed to by iptr. + The library provides overloads of std::modf for all cv-unqualified floating-point + types as the type of the parameter num and the pointed-to type of iptr. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + iptr - pointer to floating-point value to store the integral part to + +.SH Return value + + If no errors occur, returns the fractional part of num with the same sign as num. + The integral part is put into the value pointed to by iptr. + + The sum of the returned value and the value stored in *iptr gives num (allowing for + rounding). + +.SH Error handling + + This function is not subject to any errors specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If num is ±0, ±0 is returned, and ±0 is stored in *iptr. + * If num is ±∞, ±0 is returned, and ±∞ is stored in *iptr. + * If num is NaN, NaN is returned, and NaN is stored in *iptr. + * The returned value is exact, the current rounding mode is ignored. + +.SH Notes + + This function behaves as if implemented as follows: + + double modf(double num, double* iptr) + { + #pragma STDC FENV_ACCESS ON + int save_round = std::fegetround(); + std::fesetround(FE_TOWARDZERO); + *iptr = std::nearbyint(num); + std::fesetround(save_round); + return std::copysign(std::isinf(num) ? 0.0 : num - (*iptr), num); + } + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::modf(num, iptr) has the same effect as std::modf(static_cast(num), + iptr). + +.SH Example + + Compares different floating-point decomposition functions: + + +// Run this code + + #include + #include + #include + + int main() + { + double f = 123.45; + std::cout << "Given the number " << f << " or " << std::hexfloat + << f << std::defaultfloat << " in hex,\\n"; + + double f3; + double f2 = std::modf(f, &f3); + std::cout << "modf() makes " << f3 << " + " << f2 << '\\n'; + + int i; + f2 = std::frexp(f, &i); + std::cout << "frexp() makes " << f2 << " * 2^" << i << '\\n'; + + i = std::ilogb(f); + std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) << " * " + << std::numeric_limits::radix + << "^" << std::ilogb(f) << '\\n'; + + // special values + f2 = std::modf(-0.0, &f3); + std::cout << "modf(-0) makes " << f3 << " + " << f2 << '\\n'; + f2 = std::modf(-INFINITY, &f3); + std::cout << "modf(-Inf) makes " << f3 << " + " << f2 << '\\n'; + } + +.SH Possible output: + + Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, + modf() makes 123 + 0.45 + frexp() makes 0.964453 * 2^7 + logb()/ilogb() make 1.92891 * 2^6 + modf(-0) makes -0 + -0 + modf(-Inf) makes -INF + -0 + +.SH See also + + trunc + truncf + truncl nearest integer not greater in magnitude than the given value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + modf diff --git a/man/std::modf.3 b/man/std::modf.3 deleted file mode 100644 index d691ae7b8..000000000 --- a/man/std::modf.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH std::modf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float modf( float x, float* iptr ); - double modf( double x, double* iptr ); - long double modf( long double x, long double* iptr ); - - Decomposes given floating point value x into integral and fractional parts, each - having the same type and sign as x. The integral part (in floating-point format) is - stored in the object pointed to by iptr. - -.SH Parameters - - arg - floating point value - iptr - pointer to floating point value to store the integral part to - -.SH Return value - - The fractional part of x with the same sign as x. The integral part is put into the - value pointed to by iptr. - -.SH Example - - -// Run this code - - #include - #include - int main() - { - double f = 123.45; - double f3; - double f2 = std::modf(f, &f3); - std::cout << "Given the number " << f << ", " - << "modf() makes " << f3 << " and " << f2 << '\\n'; - - f = -3.21; - f2 = std::modf(f, &f3); - std::cout << "Given the number " << f << ", " - << "modf() makes " << f3 << " and " << f2 << '\\n'; - } - -.SH Output: - - Given the number 123.45, modf() makes 123 and 0.45 - Given the number -3.21, modf() makes -3 and -0.21 - -.SH See also - - trunc nearest integer not greater in magnitude than the given value - \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::modulus.3 b/man/std::modulus.3 index 7d56ac725..99fbe254f 100644 --- a/man/std::modulus.3 +++ b/man/std::modulus.3 @@ -1,59 +1,71 @@ -.TH std::modulus 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::modulus 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::modulus \- std::modulus + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct modulus; - template< class T = void > \fI(since C++14)\fP - struct modulus; - - Function object for computing remainders of divisions. Implements operator% for type - T. - -.SH Specializations - - The standard library provides a specialization of std::modulus when T - is not specified, which leaves the parameter types and return type to - be deduced. - \fI(since C++14)\fP - function object implementing x % y deducing argument and - modulus return types - \fI(class template specialization)\fP + template<> \fI(since C++14)\fP + class modulus; -.SH Member types - - Type Definition - result_type T - first_argument_type T - second_argument_type T + std::modulus is a specialization of std::modulus with parameter and return + type deduced. .SH Member functions - returns the remainder from the division of the first argument by the - operator() second argument + operator() returns the modulus of two arguments \fI(public member function)\fP - std::modulus::operator() +std::modulus::operator() + + template< class T, class U > + + constexpr auto operator()( T&& lhs, U&& rhs ) const - T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + -> decltype(std::forward(lhs) % std::forward(rhs)); Returns the remainder of the division of lhs by rhs. .SH Parameters - lhs, rhs - values to divide one by another + lhs, rhs - values to divide .SH Return value - The result of lhs % rhs. + std::forward(lhs) % std::forward(rhs). + +.SH Example + + +// Run this code + + #include + #include + + struct M + { + M(int x) { std::cout << "M(" << x << ");\\n"; } + M() {} + }; + + auto operator%(M, M) { std::cout << "operator%(M, M);\\n"; return M{}; } + auto operator%(M, int) { std::cout << "operator%(M, int);\\n"; return M{}; } + auto operator%(int, M) { std::cout << "operator%(int, M);\\n"; return M{}; } + + int main() + { + M m; -.SH Exceptions + // 42 is converted into a temporary object M{42} + std::modulus{}(m, 42); // calls operator%(M, M) - \fI(none)\fP + // no temporary object + std::modulus{}(m, 42); // calls operator%(M, int) + std::modulus{}(42, m); // calls operator%(int, M) + } -.SH Possible implementation +.SH Output: - constexpr T operator()(const T &lhs, const T &rhs) const - { - return lhs % rhs; - } + M\fB(42)\fP; + operator%(M, M); + operator%(M, int); + operator%(int, M); diff --git a/man/std::modulus.3 b/man/std::modulus.3 deleted file mode 100644 index 096b95881..000000000 --- a/man/std::modulus.3 +++ /dev/null @@ -1,55 +0,0 @@ -.TH std::modulus 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class modulus; - - std::modulus<> is a specialization of std::modulus with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() returns the modulus of two arguments - \fI(public member function)\fP - - std::modulus<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) % std::forward(rhs)); - - Returns the remainder of the division of lhs by rhs (or whatever operator% is - overloaded to do) - -.SH Parameters - - lhs, rhs - values to divide - -.SH Return value - - The result of lhs % rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::money_base.3 b/man/std::money_base.3 index 09564509b..d8d55c0f1 100644 --- a/man/std::money_base.3 +++ b/man/std::money_base.3 @@ -1,4 +1,7 @@ -.TH std::money_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_base \- std::money_base + .SH Synopsis Defined in header class money_base; @@ -31,14 +34,14 @@ first; the value space, if present, is neither first nor last. The default format, returned by the standard specializations of std::moneypunct is - {symbol, sign, none, value} + {symbol, sign, none, value}. .SH See also defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP money_get parses and constructs a monetary value from an input character sequence - \fI(class template)\fP + \fI(class template)\fP money_put formats a monetary value for output as a character sequence - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::money_get.3 b/man/std::money_get.3 index 0830fbf9e..856288eb8 100644 --- a/man/std::money_get.3 +++ b/man/std::money_get.3 @@ -1,4 +1,7 @@ -.TH std::money_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_get \- std::money_get + .SH Synopsis Defined in header template< @@ -13,32 +16,32 @@ std::money_get facet of the I/O stream's locale. std-money get-inheritance.svg - About this image Inheritance diagram -.SH Type requirements - - - - InputIt must meet the requirements of InputIterator. + If a std::money_get specialization is not guaranteed to be provided by the standard + library (see below), the behaviors of its get() and do_get() are not guaranteed as + specified. .SH Specializations - Two standalone (locale-independent) full specializations and two partial - specializations are provided by the standard library: + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header - std::money_get parses narrow string representations of monetary - values - std::money_get parses wide string representations of monetary - values - std::money_get parses narrow string representations of monetary - values using custom input iterator - std::money_get parses wide string representations of monetary - values using custom input iterator - - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. + std::money_get parses narrow string representations of monetary values + std::money_get parses wide string representations of monetary values + + In addition, the standard library is also guaranteed to provide every specialization + that satisfies the following type requirements: + + * CharT is one of + * char, + * wchar_t, and + * any other implementation-defined character container type that meets the + requirements for a character on which any of the iostream components can be + instantiated; and + * InputIt must meet the requirements of LegacyInputIterator. .SH Member types @@ -51,15 +54,15 @@ constructor constructs a new money_get facet \fI(public member function)\fP - destructor destructs a money_get facet - \fI(protected member function)\fP get invokes do_get \fI(public member function)\fP .SH Protected member functions - do_get parses a monetary value from an input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + destructor destructs a money_get facet + \fI(protected member function)\fP + do_get parses a monetary value from an input stream + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Member objects @@ -68,36 +71,40 @@ .SH Example - + // Run this code - #include - #include - #include #include + #include #include + #include + #include + int main() { std::string str = "$1.11 $2.22 $3.33"; std::cout << std::fixed << std::setprecision(2); - - std::cout << '"' << str << "\\" parsed with the I/O manipulator: "; + + std::cout << '\\"' << str << "\\" parsed with the I/O manipulator: "; std::istringstream s1(str); s1.imbue(std::locale("en_US.UTF-8")); + long double val; - while(s1 >> std::get_money(val)) - std::cout << val/100 << ' '; + while (s1 >> std::get_money(val)) + std::cout << val / 100 << ' '; std::cout << '\\n'; - + str = "USD 1,234.56"; - std::cout << '"' << str << "\\" parsed with the facet directly: "; + std::cout << '\\"' << str << "\\" parsed with the facet directly: "; std::istringstream s2(str); s2.imbue(std::locale("en_US.UTF-8")); + auto& f = std::use_facet>(s2.getloc()); std::ios_base::iostate err; std::istreambuf_iterator beg(s2), end; f.get(beg, end, true, s2, err, val); - std::cout << val/100 << '\\n'; + + std::cout << val / 100 << '\\n'; } .SH Output: @@ -105,12 +112,29 @@ "$1.11 $2.22 $3.33" parsed with the I/O manipulator: 1.11 2.22 3.33 "USD 1,234.56" parsed with the facet directly: 1234.56 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + money_get was guaranteed to accept only guarantees to accept + any CharT that char, + LWG 427 C++98 meets the requirements for a wchar_t and other + character on which implementation- + any of the iostream components can defined character types + be instantiated + only character type CharT could be can guarantee to accept + LWG 2392 C++98 guaranteed to be accepted by implementation- + money_get defined character container + types + .SH See also defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP money_put formats a monetary value for output as a character sequence - \fI(class template)\fP + \fI(class template)\fP get_money parses a monetary value \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::money_get::get,do_get.3 b/man/std::money_get::get,do_get.3 index 6d4e3b2dc..968527bee 100644 --- a/man/std::money_get::get,do_get.3 +++ b/man/std::money_get::get,do_get.3 @@ -1,29 +1,34 @@ -.TH std::money_get::get,do_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_get::get,do_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_get::get,do_get \- std::money_get::get,do_get + .SH Synopsis Defined in header public: - iter_type get(iter_type beg, iter_type end, bool intl, std::ios_base& str, \fB(1)\fP + iter_type get( iter_type beg, iter_type end, bool intl, std::ios_base& str, \fB(1)\fP - std::ios_base::iostate& err, long double& units) const; - iter_type get(iter_type beg, iter_type end, bool intl, std::ios_base& str, \fB(2)\fP - std::ios_base::iostate& err, string_type& digits) const; + std::ios_base::iostate& err, long double& units ) const; + iter_type get( iter_type beg, iter_type end, bool intl, std::ios_base& str, \fB(2)\fP + std::ios_base::iostate& err, string_type& digits ) const; protected: - virtual iter_type get(iter_type beg, iter_type end, bool intl, std::ios_base& \fB(3)\fP - str, + virtual iter_type do_get( iter_type beg, iter_type end, bool intl, + std::ios_base& str, \fB(3)\fP - std::ios_base::iostate& err, long double& units) const; - virtual iter_type get(iter_type beg, iter_type end, bool intl, std::ios_base& - str, \fB(4)\fP - std::ios_base::iostate& err, string_type& digits) const; + std::ios_base::iostate& err, long double& units ) + const; + virtual iter_type do_get( iter_type beg, iter_type end, bool intl, + std::ios_base& str, \fB(4)\fP + std::ios_base::iostate& err, string_type& digits ) + const; Parses monetary value from an input iterator and writes the result to a long double or string. - 1-2) Public member functions, call the member function do_get of the most derived + 1,2) Public member functions, call the member function do_get of the most derived class. - 3-4) Reads characters from the input iterator beg, expecting to find a monetary + 3,4) Reads characters from the input iterator beg, expecting to find a monetary value formatted according to the rules specified by the std::ctype facet imbued in str.getloc() (ct for the rest of this page), the std::moneypunct facet imbued in str.getloc() (mp for the rest of this page), and the stream formatting @@ -31,7 +36,7 @@ If the input iterator beg becomes equal to end before the parsing was completed, sets both failbit and eofbit in err. If parsing fails for another reason, sets the - failbit in err. Either way, does not modify the output parameter ((units or digits) + failbit in err. Either way, does not modify the output parameter (units or digits) on error. If the parsing succeeds, does not change err, and stores the result in units or @@ -75,7 +80,7 @@ sscanf(buf2, "%Lf", &units); (where n is the number of characters extracted from the input and stored in buf1 and - buf2 is another sufficiently large character buffer) + buf2 is another sufficiently large character buffer). .SH Return value @@ -86,7 +91,7 @@ The currency units are assumed to be the smallest non-fractional units of the currency: cents in the U.S, yen in Japan. Thus, the input sequence "$1,056.23" in a - U.S. locale produces the number 105623.0 in units or a string "105623" in digits + U.S. locale produces the number 105623.0 in units or a string "105623" in digits. Because currency symbol is optional if showbase is off but the entire multicharacter negative_sign() is required, given the formatting pattern {sign, value, space, @@ -98,45 +103,49 @@ .SH Example - + // Run this code #include - #include #include - + #include + void demo_money_get(std::locale loc, const std::string& input) { std::istringstream str(input); str.imbue(loc); long double units; - // note, the following can be written simple with std::get_money(units) + + // The following can be written simpler with std::get_money(units) std::ios_base::iostate err = std::ios_base::goodbit; std::istreambuf_iterator ret = std::use_facet>(loc).get( - std::istreambuf_iterator(str), - std::istreambuf_iterator(), - false, str, err, units); + std::istreambuf_iterator(str), + std::istreambuf_iterator(), + false, str, err, units); str.setstate(err); - if(str) { + std::istreambuf_iterator last{}; + if (str) + { std::cout << "Successfully parsed '" << str.str() << "' as " - << units/100 << " units\\n"; - if(ret != std::istreambuf_iterator()) { + << units / 100 << " units\\n"; + if (ret != last) + { std::cout << "Remaining content: '"; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); std::cout << "'\\n"; - } else { - std::cout << "The input was fully consumed\\n"; } - } else { - std::cout << "Parse failed. Unparsed string: '"; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); - std::cout << "'\\n"; + else + std::cout << "The input was fully consumed\\n"; + } + else + { + std::cout << "Parse failed. Unparsed string: '"; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); + std::cout << "'\\n"; } } - + int main() { demo_money_get(std::locale("en_US.utf8"), "-$5.12 abc"); @@ -154,8 +163,8 @@ defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP money_get parses and constructs a monetary value from an input character sequence - \fI(class template)\fP + \fI(class template)\fP get_money parses a monetary value - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::money_get::money_get.3 b/man/std::money_get::money_get.3 index 4164d1a2a..9a8bce306 100644 --- a/man/std::money_get::money_get.3 +++ b/man/std::money_get::money_get.3 @@ -1,10 +1,13 @@ -.TH std::money_get::money_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_get::money_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_get::money_get \- std::money_get::money_get + .SH Synopsis Defined in header explicit money_get( std::size_t refs = 0 ); Creates a std::money_get facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::money_get::~money_get.3 b/man/std::money_get::~money_get.3 index 639336424..69d15087a 100644 --- a/man/std::money_get::~money_get.3 +++ b/man/std::money_get::~money_get.3 @@ -1,4 +1,7 @@ -.TH std::money_get::~money_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_get::~money_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_get::~money_get \- std::money_get::~money_get + .SH Synopsis Defined in header protected: ~money_get(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_money_get : public std::money_get { Destructible_money_get(std::size_t refs = 0) : money_get(refs) {} - ~Destructible_money_get() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_money_get dc; - // std::money_get c; // compile error: protected destructor + // std::money_get c; // compile error: protected destructor } diff --git a/man/std::money_put.3 b/man/std::money_put.3 index 5122dea9c..234f07724 100644 --- a/man/std::money_put.3 +++ b/man/std::money_put.3 @@ -1,4 +1,7 @@ -.TH std::money_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_put \- std::money_put + .SH Synopsis Defined in header template< @@ -13,32 +16,32 @@ of the I/O stream's locale. std-money put-inheritance.svg - About this image Inheritance diagram -.SH Type requirements - - - - InputIt must meet the requirements of InputIterator. + If a std::money_put specialization is not guaranteed to be provided by the standard + library (see below), the behaviors of its put() and do_put() are not guaranteed as + specified. .SH Specializations - Two standalone (locale-independent) full specializations and two partial - specializations are provided by the standard library: + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header - std::money_put creates narrow string representations of monetary - values - std::money_put creates wide string representations of monetary - values - std::money_put creates narrow string representations of monetary - values using custom output iterator - std::money_put creates wide string representations of monetary - values using custom output iterator - - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. + std::money_put creates narrow string representations of monetary values + std::money_put creates wide string representations of monetary values + + In addition, the standard library is also guaranteed to provide every specialization + that satisfies the following type requirements: + + * CharT is one of + * char, + * wchar_t, and + * any other implementation-defined character container type that meets the + requirements for a character on which any of the iostream components can be + instantiated; and + * OutputIt must meet the requirements of LegacyOutputIterator. .SH Member types @@ -51,15 +54,15 @@ constructor constructs a new money_put facet \fI(public member function)\fP - destructor destructs a money_put facet - \fI(protected member function)\fP put invokes do_put \fI(public member function)\fP .SH Protected member functions - do_put formats a monetary value and writes to output stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + destructor destructs a money_put facet + \fI(protected member function)\fP + do_put formats a monetary value and writes to output stream + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Member objects @@ -68,40 +71,57 @@ .SH Example - + // Run this code - #include - #include #include + #include #include + #include + int main() { - // using the IO manipulator + // using the I/O manipulator std::cout.imbue(std::locale("en_US.UTF-8")); - std::cout << "american locale: " - << std::showbase << std::put_money(12345678.9)<< '\\n'; - + std::cout << "American locale: " + << std::showbase << std::put_money(12345678.9) << '\\n'; + // using the facet directly - std::cout.imbue(std::locale("de_DE")); - std::cout << "german locale: " ; - std::ostreambuf_iterator out(std::cout); + std::cout.imbue(std::locale("de_DE.UTF-8")); + std::cout << "German locale: "; auto& f = std::use_facet>(std::cout.getloc()); - f.put(out, false, std::cout, std::cout.fill(), 12345678.9 ); + f.put({std::cout}, false, std::cout, std::cout.fill(), 12345678.9); std::cout << '\\n'; } .SH Output: - american locale: $123,456.79 - german locale: 123.456,79 EUR + American locale: $123,456.79 + German locale: 123.456,79 € + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + money_put was guaranteed to accept only guarantees to accept + any CharT that char, + LWG 427 C++98 meets the requirements for a wchar_t and other + character on which implementation- + any of the iostream components can defined character types + be instantiated + only character type CharT could be can guarantee to accept + LWG 2392 C++98 guaranteed to be accepted by implementation- + money_put defined character container + types .SH See also defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP money_get parses and constructs a monetary value from an input character sequence - \fI(class template)\fP + \fI(class template)\fP put_money formats and outputs a monetary value \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::money_put::money_put.3 b/man/std::money_put::money_put.3 index d14fbe599..776ba4a00 100644 --- a/man/std::money_put::money_put.3 +++ b/man/std::money_put::money_put.3 @@ -1,10 +1,13 @@ -.TH std::money_put::money_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_put::money_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_put::money_put \- std::money_put::money_put + .SH Synopsis Defined in header explicit money_put( std::size_t refs = 0 ); Creates a std::money_put facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::money_put::put,do_put.3 b/man/std::money_put::put,do_put.3 index 286b84342..14ced612e 100644 --- a/man/std::money_put::put,do_put.3 +++ b/man/std::money_put::put,do_put.3 @@ -1,24 +1,27 @@ -.TH std::money_put::put,do_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_put::put,do_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_put::put,do_put \- std::money_put::put,do_put + .SH Synopsis Defined in header public: - iter_type put(iter_type out, bool intl, std::ios_base& f, \fB(1)\fP + iter_type put( iter_type out, bool intl, std::ios_base& f, \fB(1)\fP - char_type fill, long double quant) const; - iter_type put(iter_type out, bool intl, std::ios_base& f, \fB(2)\fP - char_type fill, const string_type& quant) const; + char_type fill, long double quant ) const; + iter_type put( iter_type out, bool intl, std::ios_base& f, \fB(2)\fP + char_type fill, const string_type& quant ) const; protected: - virtual iter_type do_put(iter_type out, bool intl, std::ios_base& str, \fB(3)\fP + virtual iter_type do_put( iter_type out, bool intl, std::ios_base& str, \fB(3)\fP - char_type fill, long double units) const; - virtual iter_type do_put(iter_type out, bool intl, std::ios_base& str, \fB(4)\fP - char_type fill, const string_type& digits) const; + char_type fill, long double units ) const; + virtual iter_type do_put( iter_type out, bool intl, std::ios_base& str, \fB(4)\fP + char_type fill, const string_type& digits ) const; Formats monetary value and writes the result to output stream. - 1-2) Public member functions, call the member function do_put of the most derived + 1,2) Public member functions, call the member function do_put of the most derived class. 3) The numeric arguments units is converted to a wide character string as if by ct.widen(buf1, buf1 + std::sprintf(buf1, "%.0Lf", units), buf2), where ct is the @@ -50,7 +53,7 @@ more than one character, the first character returned is placed in the output sequence where sign appears in the formatting pattern, and the rest of the characters are placed after all other characters, for example, formatting pattern - {sign, value, space, symbol with units 123 and negative_sign of "-" may result in + {sign, value, space, symbol} with units 123 and negative_sign of "-" may result in "-1.23 €", while negative_sign of "()" would generate "(1.23 €)". If the number of characters generated for the specified format is less than the @@ -60,14 +63,14 @@ * If str.flags() & str.adjustfield equals str.internal, the fill characters are inserted where none or space appears in the formatting pattern. * Otherwise, if str.flags() & str.adjustfield equals str.left, the copies of fill - are appended after all other characters + are appended after all other characters. * Otherwise, the fill characters are placed before all other characters. In the end, calls str.width\fB(0)\fP to cancel the effects of any std::setw. .SH Return value - An iterator pointing immediately after the last character produced + An iterator pointing immediately after the last character produced. .SH Notes @@ -76,50 +79,58 @@ .SH Example - + // Run this code - #include #include + #include #include - - struct my_punct : std::moneypunct_byname { + + struct my_punct : std::moneypunct_byname + { my_punct(const char* name) : moneypunct_byname(name) {} string_type do_negative_sign() const { return "()"; } }; - + int main() { std::locale loc("ru_RU.utf8"); std::cout.imbue(loc); long double units = -123.45; - std::cout << "In Russian locale, " << units << " prints as " - << std::showbase; - // note, the following is equivalent to simply std::put_money(units) + std::cout << "In Russian locale, " << units << " prints as " << std::showbase; + + // note, the following is equivalent to simply std::put_money(units) std::use_facet>(loc).put( - std::ostreambuf_iterator(std::cout), - false, std::cout, std::cout.fill(), units); + {std::cout}, false, std::cout, std::cout.fill(), units); std::cout << '\\n'; - + std::cout.imbue(std::locale(std::cout.getloc(), new my_punct("ru_RU.utf8"))); - std::cout << "With negative_sign set to \\"()\\", it prints as "; + std::cout << "With negative_sign set to \\"()\\", it prints as "; std::use_facet>(loc).put( - std::ostreambuf_iterator(std::cout), - false, std::cout, std::cout.fill(), units); + {std::cout}, false, std::cout, std::cout.fill(), units); std::cout << '\\n'; } .SH Output: In Russian locale, -123,45 prints as -1.23 руб - With negative_sign set to "()", it prints as (1.23 руб) + With negative_sign set to "()", it prints as (1.23 руб) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 328 C++98 the format string used for std::sprintf was corrected to "%.0Lf" + "%.01f" .SH See also defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP money_get parses and constructs a monetary value from an input character sequence - \fI(class template)\fP + \fI(class template)\fP put_money formats and outputs a monetary value - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::money_put::~money_put.3 b/man/std::money_put::~money_put.3 index a06826d62..57a1798d1 100644 --- a/man/std::money_put::~money_put.3 +++ b/man/std::money_put::~money_put.3 @@ -1,4 +1,7 @@ -.TH std::money_put::~money_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::money_put::~money_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::money_put::~money_put \- std::money_put::~money_put + .SH Synopsis Defined in header protected: ~money_put(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_money_put : public std::money_put { Destructible_money_put(std::size_t refs = 0) : money_put(refs) {} - ~Destructible_money_put() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_money_put dc; - // std::money_put c; // compile error: protected destructor + // std::money_put c; // compile error: protected destructor } diff --git a/man/std::moneypunct.3 b/man/std::moneypunct.3 index 843f5c2af..27181f5ce 100644 --- a/man/std::moneypunct.3 +++ b/man/std::moneypunct.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct \- std::moneypunct + .SH Synopsis Defined in header template< class CharT, bool International = false > @@ -10,12 +13,13 @@ monetary value output. std-moneypunct-inheritance.svg - About this image Inheritance diagram - Four standalone (locale-independent) specializations are provided by the standard - library: +.SH Specializations + + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header std::moneypunct provides equivalents of the "C" locale preferences @@ -26,9 +30,6 @@ std::moneypunct provides wide character equivalents of the "C" locale preferences, with international currency symbols - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. - .SH Member types Member type Definition @@ -38,42 +39,42 @@ .SH Member functions constructor constructs a new moneypunct facet - \fI(public member function)\fP - destructor destructs a moneypunct facet - \fI(protected member function)\fP + \fI(public member function)\fP decimal_point invokes do_decimal_point - \fI(public member function)\fP + \fI(public member function)\fP thousands_sep invokes do_thousands_sep - \fI(public member function)\fP + \fI(public member function)\fP grouping invokes do_grouping - \fI(public member function)\fP + \fI(public member function)\fP curr_symbol invokes do_curr_symbol - \fI(public member function)\fP + \fI(public member function)\fP positive_sign invokes do_positive_sign or do_negative_sign - negative_sign \fI(public member function)\fP + negative_sign \fI(public member function)\fP frac_digits invokes do_frac_digits - \fI(public member function)\fP + \fI(public member function)\fP pos_format invokes do_pos_format/do_neg_format - neg_format \fI(public member function)\fP + neg_format \fI(public member function)\fP .SH Protected member functions + destructor destructs a moneypunct facet + \fI(protected member function)\fP do_decimal_point provides the character to use as decimal point - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_grouping provides the numbers of digits between each pair of thousands \fB[virtual]\fP separators - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP do_curr_symbol provides the string to use as the currency identifier - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_positive_sign provides the string to indicate a positive or negative value - do_negative_sign \fI(virtual protected member function)\fP + do_negative_sign \fI(virtual protected member function)\fP \fB[virtual]\fP do_frac_digits provides the number of digits to display after the decimal point - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_pos_format provides the formatting pattern for currency values - do_neg_format \fI(virtual protected member function)\fP + do_neg_format \fI(virtual protected member function)\fP \fB[virtual]\fP .SH Member constants @@ -86,7 +87,7 @@ static std::locale::id id id of the locale \fI(public member object)\fP - + Inherited from std::money_base @@ -98,22 +99,22 @@ Inherited from std::money_base none whitespace is permitted but not required except in the last position, where whitespace is not permitted space one or more whitespace characters are required - symbol the sequence of characters returned by moneypunct::curr_symbol - is required + symbol the sequence of characters returned by + std::moneypunct::curr_symbol is required the first of the characters returned by - sign moneypunct::positive_sign or moneypunct::negative_sign is - required + sign std::moneypunct::positive_sign or + std::moneypunct::negative_sign is required value the absolute numeric monetary value is required .SH See also money_base defines monetary formatting patterns - \fI(class)\fP + \fI(class)\fP represents the system-supplied std::moneypunct for the named moneypunct_byname locale - \fI(class template)\fP + \fI(class template)\fP parses and constructs a monetary value from an input character money_get sequence - \fI(class template)\fP + \fI(class template)\fP money_put formats a monetary value for output as a character sequence - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::moneypunct::curr_symbol,do_curr_symbol.3 b/man/std::moneypunct::curr_symbol,do_curr_symbol.3 index e0e71e259..4ba867b31 100644 --- a/man/std::moneypunct::curr_symbol,do_curr_symbol.3 +++ b/man/std::moneypunct::curr_symbol,do_curr_symbol.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct::curr_symbol,do_curr_symbol 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::curr_symbol,do_curr_symbol 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::curr_symbol,do_curr_symbol \- std::moneypunct::curr_symbol,do_curr_symbol + .SH Synopsis Defined in header public: \fB(1)\fP @@ -12,7 +15,7 @@ International (the second template parameter of std::moneypunct) is false, the identifier is usually a single (wide) character, such as "￥" or "$". If International is true, the identifier is usually a four-character string holding the - three-character international currency code followed by a space ("JPY " or "USD ") + three-character ISO 4217 currency code followed by a space ("JPY " or "USD "). .SH Return value @@ -20,11 +23,12 @@ .SH Example - + // Run this code #include #include + void show_ccy(const char* locname) { std::locale loc(locname); @@ -33,6 +37,7 @@ << "or " << std::use_facet>(loc).curr_symbol() << " for short\\n"; } + int main() { show_ccy("en_US.utf8"); @@ -50,8 +55,17 @@ ru_RU.utf8 currency symbol is RUB or руб for short vi_VN.utf8 currency symbol is VND or ₫ for short + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 666 C++98 the length of the identifier string was required not required + to be 4 if International is true + .SH See also do_pos_format provides the formatting pattern for currency values - do_neg_format \fI(virtual protected member function)\fP + do_neg_format \fI(virtual protected member function)\fP \fB[virtual]\fP diff --git a/man/std::moneypunct::decimal_point,do_decimal_point.3 b/man/std::moneypunct::decimal_point,do_decimal_point.3 index a036116bc..f9487aba4 100644 --- a/man/std::moneypunct::decimal_point,do_decimal_point.3 +++ b/man/std::moneypunct::decimal_point,do_decimal_point.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct::decimal_point,do_decimal_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::decimal_point,do_decimal_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::decimal_point,do_decimal_point \- std::moneypunct::decimal_point,do_decimal_point + .SH Synopsis Defined in header public: \fB(1)\fP @@ -10,7 +13,7 @@ derived class. 2) Returns the character to use as the decimal point separator in monetary I/O if the format uses fractions (that is, if do_frac_digits() is greater than zero). For - typical U.S. locales, it is the character '.' (or L'.') + typical U.S. locales, it is the character '.' (or L'.'). .SH Return value @@ -18,13 +21,13 @@ .SH Example - + // Run this code - #include #include + #include #include - + void show_dpt(const char* locname) { std::locale loc(locname); @@ -33,18 +36,17 @@ << std::use_facet>(loc).decimal_point() << "' for example: " << std::showbase << std::put_money(123); if (std::use_facet>(loc).frac_digits() == 0) - std::cout << " (does not use frac digits) "; - + std::cout << " (does not use frac digits)"; + std::cout << '\\n'; } - + int main() { show_dpt("en_US.utf8"); show_dpt("ja_JP.utf8"); show_dpt("sv_SE.utf8"); show_dpt("de_DE.utf8"); - } .SH Output: @@ -57,4 +59,4 @@ .SH See also do_frac_digits provides the number of digits to display after the decimal point - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::moneypunct::frac_digits,do_frac_digits.3 b/man/std::moneypunct::frac_digits,do_frac_digits.3 index 9f166b998..98b7a60e1 100644 --- a/man/std::moneypunct::frac_digits,do_frac_digits.3 +++ b/man/std::moneypunct::frac_digits,do_frac_digits.3 @@ -1,15 +1,18 @@ -.TH std::moneypunct::frac_digits,do_frac_digits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::frac_digits,do_frac_digits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::frac_digits,do_frac_digits \- std::moneypunct::frac_digits,do_frac_digits + .SH Synopsis Defined in header - public: \fB(1)\fP + public: \fB(1)\fP int frac_digits() const; - protected: \fB(2)\fP - int virtual do_thousands_sep() const; + protected: \fB(2)\fP + virtual int do_frac_digits() const; 1) Public member function, calls the member function do_frac_digits of the most derived class. 2) Returns the number of digits to be displayed after the decimal point when - printing monetary values + printing monetary values. .SH Return value @@ -18,28 +21,31 @@ .SH Example - + // Run this code - #include - #include #include + #include #include - struct space_out : std::moneypunct { - pattern do_pos_format() const { return { {value, none, none, none} };} - int do_frac_digits() const { return 0; } - char_type do_thousands_sep() const { return ' ';} - string_type do_grouping() const { return "\\002";} + #include + + struct space_out : std::moneypunct + { + pattern do_pos_format() const { return {value, none, none, none}; } + int do_frac_digits() const { return 0; } + char_type do_thousands_sep() const { return ' '; } + string_type do_grouping() const { return "\\002"; } }; + int main() { std::cout.imbue(std::locale("en_US.UTF-8")); std::cout << "american locale: " << std::showbase - << std::put_money(12345678.0)<< '\\n'; - + << std::put_money(12345678.0) << '\\n'; + std::cout.imbue(std::locale(std::cout.getloc(), new space_out)); std::cout << "locale with modified moneypunct: " - << std::put_money(12345678.0)<< '\\n'; + << std::put_money(12345678.0) << '\\n'; } .SH Output: @@ -50,6 +56,6 @@ .SH See also do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_decimal_point provides the character to use as decimal point - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::moneypunct::grouping,do_grouping.3 b/man/std::moneypunct::grouping,do_grouping.3 index 0e4e73db6..5f2e4b336 100644 --- a/man/std::moneypunct::grouping,do_grouping.3 +++ b/man/std::moneypunct::grouping,do_grouping.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct::grouping,do_grouping 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::grouping,do_grouping 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::grouping,do_grouping \- std::moneypunct::grouping,do_grouping + .SH Synopsis Defined in header public: \fB(1)\fP @@ -9,38 +12,41 @@ 1) Public member function, calls the member function do_grouping of the most derived class. 2) Returns the pattern that determines the grouping of the digits in the monetary - output, with the same exact meaning as std::numpunct::do_grouping + output, with the same exact meaning as std::numpunct::do_grouping. .SH Return value The object of type std::string holding the groups. The standard specializations of - std::numpunct return an empty string, indicating no grouping. Typical groupings + std::moneypunct return an empty string, indicating no grouping. Typical groupings (e.g. the en_US locale) return "\\003". .SH Example - + // Run this code - #include - #include #include + #include #include - struct space_out : std::moneypunct { - pattern do_pos_format() const { return { {value, none, none, none} };} - int do_frac_digits() const { return 0; } - char_type do_thousands_sep() const { return ' ';} - string_type do_grouping() const { return "\\002";} + #include + + struct space_out : std::moneypunct + { + pattern do_pos_format() const { return {value, none, none, none}; } + int do_frac_digits() const { return 0; } + char_type do_thousands_sep() const { return ' '; } + string_type do_grouping() const { return "\\002"; } }; + int main() { std::cout.imbue(std::locale("en_US.UTF-8")); std::cout << "american locale: " << std::showbase - << std::put_money(12345678.0)<< '\\n'; - + << std::put_money(12345678.0) << '\\n'; + std::cout.imbue(std::locale(std::cout.getloc(), new space_out)); std::cout << "locale with modified moneypunct: " - << std::put_money(12345678.0)<< '\\n'; + << std::put_money(12345678.0) << '\\n'; } .SH Output: @@ -51,6 +57,6 @@ .SH See also do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_decimal_point provides the character to use as decimal point - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::moneypunct::moneypunct.3 b/man/std::moneypunct::moneypunct.3 index 44b9b6e14..5d4f04590 100644 --- a/man/std::moneypunct::moneypunct.3 +++ b/man/std::moneypunct::moneypunct.3 @@ -1,10 +1,13 @@ -.TH std::moneypunct::moneypunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::moneypunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::moneypunct \- std::moneypunct::moneypunct + .SH Synopsis Defined in header explicit moneypunct( std::size_t refs = 0 ); Creates a std::moneypunct facet and forwards the starting reference count refs to - the base class constructor, locale::facet::facet() + the base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format.3 b/man/std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format.3 index 2d1ca68b9..510c6ec2f 100644 --- a/man/std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format.3 +++ b/man/std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format \- std::moneypunct::pos_format,do_pos_format,neg_format,do_neg_format + .SH Synopsis Defined in header public: \fB(1)\fP @@ -20,36 +23,44 @@ the formatting of negative monetary values. The standard specializations of std::moneypunct return the pattern {symbol, sign, - none, value} + none, value}. .SH Return value The object of type std::money_base::format describing the formatting used by this locale. +.SH Notes + + While std::money_put uses pos_format for formatting positive values and neg_format + for formatting negative values, std::money_get uses neg_format for parsing all + monetary values: it assumes that neg_format is compatible with pos_format. + .SH Example - + // Run this code - #include - #include #include - - struct my_punct : std::moneypunct_byname { + #include + #include + + struct my_punct : std::moneypunct_byname + { my_punct(const char* name) : moneypunct_byname(name) {} - pattern do_pos_format() const { return { {value, space, symbol, sign} };} - pattern do_neg_format() const { return { {value, space, symbol, sign} };} + pattern do_pos_format() const { return {value, space, symbol, sign}; } + pattern do_neg_format() const { return {value, space, symbol, sign}; } }; + int main() { std::cout.imbue(std::locale("en_US.utf8")); std::cout << "american locale: " << std::showbase << std::put_money(12345678.0) << '\\n'; - + std::cout.imbue(std::locale(std::cout.getloc(), new my_punct("en_US.utf8"))); std::cout << "locale with modified moneypunct:\\n" - << std::put_money(12345678.0) << '\\n' + << std::put_money(12345678.0) << '\\n' << std::put_money(-12345678.0) << '\\n'; } @@ -63,11 +74,13 @@ .SH See also do_curr_symbol provides the string to use as the currency identifier - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_positive_sign provides the string to indicate a positive or negative value - do_negative_sign \fI(virtual protected member function)\fP + do_negative_sign \fI(virtual protected member function)\fP \fB[virtual]\fP do_get parses a monetary value from an input stream - \fB[virtual]\fP \fI(virtual protected member function of std::money_get)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::money_get) do_put formats a monetary value and writes to output stream - \fB[virtual]\fP \fI(virtual protected member function of std::money_put)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::money_put) diff --git a/man/std::moneypunct::positive_sign,do_positive_sign,negative_sign,.3 b/man/std::moneypunct::positive_sign,do_positive_sign,negative_sign,.3 new file mode 100644 index 000000000..8e8f634cb --- /dev/null +++ b/man/std::moneypunct::positive_sign,do_positive_sign,negative_sign,.3 @@ -0,0 +1,80 @@ +.TH std::moneypunct::positive_sign,do_positive_sign,negative_sign, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::positive_sign,do_positive_sign,negative_sign, \- std::moneypunct::positive_sign,do_positive_sign,negative_sign, + +.SH Synopsis + + Defined in header + public: \fB(1)\fP + string_type positive_sign() const; + public: \fB(2)\fP + string_type negative_sign() const; + protected: \fB(3)\fP + virtual string_type do_positive_sign() const; + protected: \fB(4)\fP + virtual string_type do_negative_sign() const; + + 1) Public member function, calls the member function do_positive_sign of the most + derived class. + 2) Public member function, calls the member function do_negative_sign of the most + derived class. + 3) Returns the string that is used for formatting of positive monetary values. + 3) Returns the string that is used for formatting of negative monetary values. + + Only the first character of the string returned is the character that appears in the + pos_format()/neg_format() position indicated by the value sign. The rest of the + characters appear after the rest of the monetary string. + + In particular, for negative_sign of "-", the formatting may appear as "-1.23 €", + while for negative_sign of "()" it would appear as "(1.23 €)". + +.SH Return value + + The string of type string_type holding the characters to be used as positive or + negative sign. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct my_punct : std::moneypunct_byname + { + my_punct(const char* name) : moneypunct_byname(name) {} + string_type do_negative_sign() const { return "()"; } + }; + + int main() + { + std::locale loc("de_DE.utf8"); + std::cout.imbue(loc); + std::cout << loc.name() << " negative sign is '" + << std::use_facet>(loc).negative_sign() + << "' for example: " << std::showbase << std::put_money(-1234) << '\\n'; + + std::locale loc2("ms_MY.utf8"); + std::cout.imbue(loc2); + std::cout << loc2.name() << " negative sign is '" + << std::use_facet>(loc2).negative_sign() + << "' for example: " << std::put_money(-1234) << '\\n'; + + std::cout.imbue(std::locale(std::cout.getloc(), new my_punct("de_DE.utf8"))); + std::cout << "de_DE.utf8 with negative_sign set to \\"()\\": " + << std::put_money(-1234) << '\\n'; + } + +.SH Output: + + de_DE.utf8 negative sign is '-' for example: -12,34 € + ms_MY.utf8 negative sign is '()' for example: (RM12.34) + de_DE.utf8 with negative_sign set to "()": (12,34 €) + +.SH See also + + do_pos_format provides the formatting pattern for currency values + do_neg_format \fI(virtual protected member function)\fP + \fB[virtual]\fP diff --git a/man/std::moneypunct::positive_sign,do_positive_sign,negative_sign,do_negative_sign.3 b/man/std::moneypunct::positive_sign,do_positive_sign,negative_sign,do_negative_sign.3 deleted file mode 100644 index 6d67473f5..000000000 --- a/man/std::moneypunct::positive_sign,do_positive_sign,negative_sign,do_negative_sign.3 +++ /dev/null @@ -1,76 +0,0 @@ -.TH std::moneypunct::positive_sign,do_positive_sign,negative_sign,do_negative_sign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - public: \fB(1)\fP - string_type positive_sign() const; - public: \fB(2)\fP - string_type negative_sign() const; - protected: \fB(3)\fP - virtual string_type do_positive_sign() const; - protected: \fB(4)\fP - virtual string_type do_negative_sign() const; - - 1) Public member function, calls the member function do_positive_sign of the most - derived class. - 2) Public member function, calls the member function do_negative_sign of the most - derived class. - 3) Returns the string that is used for formatting of positive monetary values. - 3) Returns the string that is used for formatting of negative monetary values. - - Only the first character of the string returned is the character that appears in the - pos_format()/neg_format() position indicated by the value sign. The rest of the - characters appear after the rest of the monetary string. - - In particular, for negative_sign of "-", the formatting may appear as "-1.23 €", - while for negative_sign of "()" it would appear as "(1.23 €)". - -.SH Return value - - The string of type string_type holding the characters to be used as positive or - negative sign. - -.SH Example - - -// Run this code - - #include - #include - #include - - struct my_punct : std::moneypunct_byname { - my_punct(const char* name) : moneypunct_byname(name) {} - string_type do_negative_sign() const { return "()"; } - }; - - int main() - { - std::locale loc("de_DE.utf8"); - std::cout.imbue(loc); - std::cout << loc.name() << " negative sign is '" - << std::use_facet>(loc).negative_sign() - << "' for example: " << std::showbase << std::put_money(-1234) << '\\n'; - - std::locale loc2("ms_MY.utf8"); - std::cout.imbue(loc2); - std::cout << loc2.name() << " negative sign is '" - << std::use_facet>(loc2).negative_sign() - << "' for example: " << std::put_money(-1234) << '\\n'; - - std::cout.imbue(std::locale(std::cout.getloc(), new my_punct("de_DE.utf8"))); - std::cout << "de_DE.utf8 with negative_sign set to \\"()\\": " - << std::put_money(-1234) << '\\n'; - - } - -.SH Output: - - de_DE.utf8 negative sign is '-' for example: -12,34 € - ms_MY.utf8 negative sign is '()' for example: (RM12.34) - de_DE.utf8 with negative_sign set to "()": (12,34 €) - -.SH See also - - do_pos_format provides the formatting pattern for currency values - do_neg_format \fI(virtual protected member function)\fP - \fB[virtual]\fP diff --git a/man/std::moneypunct::thousands_sep,do_thousands_sep.3 b/man/std::moneypunct::thousands_sep,do_thousands_sep.3 index 5f252082e..f08cfcba1 100644 --- a/man/std::moneypunct::thousands_sep,do_thousands_sep.3 +++ b/man/std::moneypunct::thousands_sep,do_thousands_sep.3 @@ -1,10 +1,13 @@ -.TH std::moneypunct::thousands_sep,do_thousands_sep 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::thousands_sep,do_thousands_sep 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::thousands_sep,do_thousands_sep \- std::moneypunct::thousands_sep,do_thousands_sep + .SH Synopsis Defined in header public: \fB(1)\fP char_type thousands_sep() const; protected: \fB(2)\fP - char_type virtual do_thousands_sep() const; + virtual char_type do_thousands_sep() const; 1) Public member function, calls the member function do_thousands_sep of the most derived class. @@ -13,33 +16,36 @@ .SH Return value - The object of type char_type to use as the thousands separator. The standard - specializations of std::moneypunct return ’,’ and L’,’. + The object of type char_type to use as the thousands separator. In common U.S. + locales, this is ',' or L','. .SH Example - + // Run this code - #include - #include #include + #include #include - struct space_out : std::moneypunct { - pattern do_pos_format() const { return { {value, none, none, none} };} - int do_frac_digits() const { return 0; } - char_type do_thousands_sep() const { return ' ';} - string_type do_grouping() const { return "\\002";} + #include + + struct space_out : std::moneypunct + { + pattern do_pos_format() const { return {value, none, none, none}; } + int do_frac_digits() const { return 0; } + char_type do_thousands_sep() const { return ' '; } + string_type do_grouping() const { return "\\002"; } }; + int main() { std::cout.imbue(std::locale("en_US.UTF-8")); std::cout << "american locale: " << std::showbase - << std::put_money(12345678.0)<< '\\n'; - + << std::put_money(12345678.0) << '\\n'; + std::cout.imbue(std::locale(std::cout.getloc(), new space_out)); std::cout << "locale with modified moneypunct: " - << std::put_money(12345678.0)<< '\\n'; + << std::put_money(12345678.0) << '\\n'; } .SH Output: @@ -50,4 +56,4 @@ .SH See also do_grouping provides the numbers of digits between each pair of thousands separators - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::moneypunct::~moneypunct.3 b/man/std::moneypunct::~moneypunct.3 index 8a2fbca08..442a0fd63 100644 --- a/man/std::moneypunct::~moneypunct.3 +++ b/man/std::moneypunct::~moneypunct.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct::~moneypunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct::~moneypunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct::~moneypunct \- std::moneypunct::~moneypunct + .SH Synopsis Defined in header protected: ~moneypunct(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_moneypunct : public std::moneypunct { Destructible_moneypunct(std::size_t refs = 0) : moneypunct(refs) {} - ~Destructible_moneypunct() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_moneypunct dc; - // std::moneypunct c; // compile error: protected destructor + // std::moneypunct c; // compile error: protected destructor } diff --git a/man/std::moneypunct_byname.3 b/man/std::moneypunct_byname.3 index 9223597c4..bc5aa41f7 100644 --- a/man/std::moneypunct_byname.3 +++ b/man/std::moneypunct_byname.3 @@ -1,4 +1,7 @@ -.TH std::moneypunct_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::moneypunct_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::moneypunct_byname \- std::moneypunct_byname + .SH Synopsis Defined in header template< class CharT, bool Intl = false > @@ -7,13 +10,13 @@ std::moneypunct_byname is a std::moneypunct facet which encapsulates monetary formatting preferences of a locale specified at its construction. - Two specializations are provided by the standard library +.SH Specializations - Defined in header - std::moneypunct_byname locale-specific std::moneypunct facet for - narrow character I/O - std::moneypunct_byname locale-specific std::moneypunct facet for wide - character I/O + The standard library is guaranteed to provide every specialization that satisfies + the following type requirements: + + * CharT is one of char and wchar_t, and + * Intl is a possible specialization on a bool parameter. .SH Member types @@ -24,13 +27,13 @@ .SH Member functions constructor constructs a new moneypunct_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a moneypunct_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP - - std::moneypunct_byname::moneypunct_byname + +std::moneypunct_byname::moneypunct_byname explicit moneypunct_byname( const char* name, std::size_t refs = 0 ); explicit moneypunct_byname( const std::string& name, std::size_t refs \fI(since C++11)\fP @@ -47,16 +50,16 @@ name - the name of the locale refs - the number of references that link to the facet - - std::moneypunct_byname::~moneypunct_byname + +std::moneypunct_byname::~moneypunct_byname protected: ~moneypunct_byname(); Destroys the facet. - + Inherited from std::moneypunct @@ -68,40 +71,52 @@ Inherited from std::moneypunct .SH Member functions - decimal_point invokes do_decimal_point - \fI(public member function of std::moneypunct)\fP - thousands_sep invokes do_thousands_sep - \fI(public member function of std::moneypunct)\fP - grouping invokes do_grouping - \fI(public member function of std::moneypunct)\fP - curr_symbol invokes do_curr_symbol - \fI(public member function of std::moneypunct)\fP + invokes do_decimal_point + decimal_point \fI(public member function of std::moneypunct)\fP + + invokes do_thousands_sep + thousands_sep \fI(public member function of std::moneypunct)\fP + + invokes do_grouping + grouping \fI(public member function of std::moneypunct)\fP + + invokes do_curr_symbol + curr_symbol \fI(public member function of std::moneypunct)\fP + positive_sign invokes do_positive_sign or do_negative_sign - negative_sign \fI(public member function of std::moneypunct)\fP - frac_digits invokes do_frac_digits - \fI(public member function of std::moneypunct)\fP + negative_sign \fI(public member function of std::moneypunct)\fP + + invokes do_frac_digits + frac_digits \fI(public member function of std::moneypunct)\fP + pos_format invokes do_pos_format/do_neg_format - neg_format \fI(public member function of std::moneypunct)\fP + neg_format \fI(public member function of std::moneypunct)\fP + .SH Protected member functions do_decimal_point provides the character to use as decimal point - \fB[virtual]\fP \fI(virtual protected member function of std::moneypunct)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::moneypunct) do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function of std::moneypunct)\fP - do_grouping provides the numbers of digits between each pair of thousands - \fB[virtual]\fP separators - \fI(virtual protected member function of std::moneypunct)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::moneypunct) + provides the numbers of digits between each pair of thousands + do_grouping separators + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::moneypunct) do_curr_symbol provides the string to use as the currency identifier - \fB[virtual]\fP \fI(virtual protected member function of std::moneypunct)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::moneypunct) do_positive_sign provides the string to indicate a positive or negative value - do_negative_sign \fI(virtual protected member function of std::moneypunct)\fP - \fB[virtual]\fP + do_negative_sign \fI\fI(virtual protected member function\fP of\fP + \fB[virtual]\fP std::moneypunct) do_frac_digits provides the number of digits to display after the decimal point - \fB[virtual]\fP \fI(virtual protected member function of std::moneypunct)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::moneypunct) do_pos_format provides the formatting pattern for currency values - do_neg_format \fI(virtual protected member function of std::moneypunct)\fP - \fB[virtual]\fP + do_neg_format \fI\fI(virtual protected member function\fP of\fP + \fB[virtual]\fP std::moneypunct) .SH Member constants @@ -113,7 +128,7 @@ Inherited from std::moneypunct static std::locale::id id id of the locale \fI(public member object)\fP - + Inherited from std::money_base @@ -125,30 +140,31 @@ Inherited from std::money_base none whitespace is permitted but not required except in the last position, where whitespace is not permitted space one or more whitespace characters are required - symbol the sequence of characters returned by moneypunct::curr_symbol - is required + symbol the sequence of characters returned by + std::moneypunct::curr_symbol is required the first of the characters returned by - sign moneypunct::positive_sign or moneypunct::negative_sign is - required + sign std::moneypunct::positive_sign or + std::moneypunct::negative_sign is required value the absolute numeric monetary value is required .SH Example - This example demonistrates how to apply monetary formatting rules of another - language without changing the rest of the locale. + This example demonstrates how to apply monetary formatting rules of another language + without changing the rest of the locale. + - // Run this code - #include #include + #include #include + int main() { long double mon = 1234567; std::locale::global(std::locale("en_US.utf8")); std::wcout.imbue(std::locale()); - std::wcout << L"american locale : " << std::showbase + std::wcout << L"american locale: " << std::showbase << std::put_money(mon) << '\\n'; std::wcout.imbue(std::locale(std::wcout.getloc(), new std::moneypunct_byname("ru_RU.utf8"))); @@ -158,11 +174,11 @@ Inherited from std::money_base .SH Output: - american locale : $12,345.67 + american locale: $12,345.67 american locale with russian moneypunct: 12 345.67 руб .SH See also defines monetary formatting parameters used by std::money_get and moneypunct std::money_put - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::monostate.3 b/man/std::monostate.3 new file mode 100644 index 000000000..d4278c682 --- /dev/null +++ b/man/std::monostate.3 @@ -0,0 +1,108 @@ +.TH std::monostate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::monostate \- std::monostate + +.SH Synopsis + Defined in header + struct monostate { }; \fI(since C++17)\fP + + Unit type intended for use as a well-behaved empty alternative in std::variant. In + particular, a variant of non-default-constructible types may list std::monostate as + its first alternative: this makes the variant itself default-constructible. + +.SH Member functions + + constructor trivial implicit default/copy/move constructor + (implicitly declared) \fI(public member function)\fP + destructor trivial implicit destructor + (implicitly declared) \fI(public member function)\fP + operator= trivial implicit copy/move assignment + (implicitly declared) \fI(public member function)\fP + +.SH Non-member functions + +std::operator==, !=, <, <=, >, >=, <=>(std::monostate) + + constexpr bool operator==( monostate, monostate ) \fB(1)\fP \fI(since C++17)\fP + noexcept { return true; } + constexpr bool operator!=( monostate, monostate ) + noexcept { return false; } + + constexpr bool operator< ( monostate, monostate ) + noexcept { return false; } + constexpr bool operator> ( monostate, monostate ) \fI(since C++17)\fP + noexcept { return false; } \fI(until C++20)\fP + constexpr bool operator<=( monostate, monostate ) + noexcept { return true; } + \fB(2)\fP + constexpr bool operator>=( monostate, monostate ) + noexcept { return true; } + constexpr std::strong_ordering operator<=>( + monostate, monostate ) noexcept + + { \fI(since C++20)\fP + return std::strong_ordering::equal; + + } + + All instances of std::monostate compare equal. + + The <, <=, >, >=, and != operators are synthesized from operator<=> \fI(since C++20)\fP + and operator== respectively. + +.SH Helper classes + +std::hash + + template <> \fI(since C++17)\fP + struct std::hash; + + Specializes the std::hash algorithm for std::monostate. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct S + { + S(int i) : i(i) {} + int i; + }; + + int main() + { + // Without the monostate type this declaration will fail. + // This is because S is not default-constructible. + std::variant var; + assert(var.index() == 0); + + try + { + std::get(var); // throws! We need to assign a value + } + catch(const std::bad_variant_access& e) + { + std::cout << e.what() << '\\n'; + } + + var = 42; + std::cout << "std::get: " << std::get(var).i << '\\n' + << "std::hash: " << std::hex << std::showbase + << std::hash{}(std::monostate{}) << '\\n'; + } + +.SH Possible output: + + std::get: wrong index for variant + std::get: 42 + std::hash: 0xffffffffffffe19f + +.SH See also + + constructor constructs the variant object + \fI(public member function)\fP diff --git a/man/std::movable.3 b/man/std::movable.3 new file mode 100644 index 000000000..d25191a60 --- /dev/null +++ b/man/std::movable.3 @@ -0,0 +1,23 @@ +.TH std::movable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::movable \- std::movable + +.SH Synopsis + Defined in header + template< class T > + + concept movable = + std::is_object_v && \fI(since C++20)\fP + std::move_constructible && + std::assignable_from && + + std::swappable; + + The concept movable specifies that T is an object type that can be moved (that + is, it can be move constructed, move assigned, and lvalues of type T can be + swapped). + +.SH See also + + copyable specifies that an object of a type can be copied, moved, and swapped + (C++20) (concept) diff --git a/man/std::move.3 b/man/std::move.3 index b296c248b..30ea23f49 100644 --- a/man/std::move.3 +++ b/man/std::move.3 @@ -1,95 +1,125 @@ -.TH std::move 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move \- std::move + .SH Synopsis - Defined in header - template< class InputIt, class OutputIt > \fI(since C++11)\fP - OutputIt move( InputIt first, InputIt last, OutputIt d_first ); + Defined in header + template< class T > \fI(since C++11)\fP + typename std::remove_reference::type&& move( T&& t ) noexcept; \fI(until C++14)\fP + template< class T > \fI(since C++14)\fP + constexpr std::remove_reference_t&& move( T&& t ) noexcept; + + std::move is used to indicate that an object t may be "moved from", i.e. allowing + the efficient transfer of resources from t to another object. - Moves the elements in the range [first, last), to another range beginning at - d_first. After this operation the elements in the moved-from range will still - contain valid values of the appropriate type, but not necessarily the same values as - before the move. + In particular, std::move produces an xvalue expression that identifies its argument + t. It is exactly equivalent to a static_cast to an rvalue reference type. .SH Parameters - first, last - the range of elements to move - d_first - the beginning of the destination range. If d_first is within [first, - last), std::move_backward must be used instead of std::move. -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. - - - OutputIt must meet the requirements of OutputIterator. + t - the object to be moved .SH Return value - Output iterator to the element past the last element moved (d_first + (last - - first)) + static_cast::type&&>(t) -.SH Complexity +.SH Notes - Exactly last - first move assignments. + The functions that accept rvalue reference parameters (including move constructors, + move assignment operators, and regular member functions such as + std::vector::push_back) are selected, by overload resolution, when called with + rvalue arguments (either prvalues such as a temporary object or xvalues such as the + one produced by std::move). If the argument identifies a resource-owning object, + these overloads have the option, but aren't required, to move any resources held by + the argument. For example, a move constructor of a linked list might copy the + pointer to the head of the list and store nullptr in the argument instead of + allocating and copying individual nodes. + + Names of rvalue reference variables are lvalues and have to be converted to xvalues + to be bound to the function overloads that accept rvalue reference parameters, which + is why move constructors and move assignment operators typically use std::move: + + // Simple move constructor + A(A&& arg) : member(std::move(arg.member)) // the expression "arg.member" is lvalue + {} + + // Simple move assignment operator + A& operator=(A&& other) + { + member = std::move(other.member); + return *this; + } -.SH Possible implementation + One exception is when the type of the function parameter is a forwarding reference + (which looks like an rvalue reference to type template parameter), in which case + std::forward is used instead. - template - OutputIt move(InputIt first, InputIt last, OutputIt d_first) - { - while (first != last) { - *d_first++ = std::move(*first++); - } - return d_first; - } + Unless otherwise specified, all standard library objects that have been moved from + are placed in a "valid but unspecified state", meaning the object's class invariants + hold (so functions without preconditions, such as the assignment operator, can be + safely used on the object after it was moved from): -.SH Notes + std::vector v; + std::string str = "example"; + v.push_back(std::move(str)); // str is now valid but unspecified + str.back(); // undefined behavior if size() == 0: back() has a precondition !empty() + if (!str.empty()) + str.back(); // OK, empty() has no precondition and back() precondition is met - When moving overlapping ranges, std::move is appropriate when moving to the left - (beginning of the destination range is outside the source range) while - std::move_backward is appropriate when moving to the right (end of the destination - range is outside the source range). + str.clear(); // OK, clear() has no preconditions + + Also, the standard library functions called with xvalue arguments may assume the + argument is the only reference to the object; if it was constructed from an lvalue + with std::move, no aliasing checks are made. However, self-move-assignment of + standard library types is guaranteed to place the object in a valid (but usually + unspecified) state: + + std::vector v = {2, 3, 3}; + v = std::move(v); // the value of v is unspecified .SH Example - The following code moves thread objects (which themselves are not copyable) from one - container to another. - // Run this code + #include #include + #include + #include #include - #include - #include - #include - #include - - void f(int n) - { - std::this_thread::sleep_for(std::chrono::seconds(n)); - std::cout << "thread " << n << " ended" << '\\n'; - } - + int main() { - std::vector v; - v.emplace_back(f, 1); - v.emplace_back(f, 2); - v.emplace_back(f, 3); - std::list l; - // copy() would not compile, because std::thread is noncopyable - - std::move(v.begin(), v.end(), std::back_inserter(l)); - for (auto& t : l) t.join(); + std::string str = "Salut"; + std::vector v; + + // uses the push_back(const T&) overload, which means + // we'll incur the cost of copying str + v.push_back(str); + std::cout << "After copy, str is " << std::quoted(str) << '\\n'; + + // uses the rvalue reference push_back(T&&) overload, + // which means no strings will be copied; instead, the contents + // of str will be moved into the vector. This is less + // expensive, but also means str might now be empty. + v.push_back(std::move(str)); + std::cout << "After move, str is " << std::quoted(str) << '\\n'; + + std::cout << "The contents of the vector are {" << std::quoted(v[0]) + << ", " << std::quoted(v[1]) << "}\\n"; } -.SH Output: +.SH Possible output: - thread 1 ended - thread 2 ended - thread 3 ended + After copy, str is "Salut" + After move, str is "" + The contents of the vector are {"Salut", "Salut"} .SH See also - move_backward moves a range of elements to a new location in backwards order - \fI(C++11)\fP \fI(function template)\fP - move obtains an rvalue reference - \fI(C++11)\fP \fI(function template)\fP + forward forwards a function argument + \fI(C++11)\fP \fI(function template)\fP + move_if_noexcept obtains an rvalue reference if the move constructor does not throw + \fI(C++11)\fP \fI(function template)\fP + move moves a range of elements to a new location + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::move_backward.3 b/man/std::move_backward.3 index e8c3b1e18..3b6eb3600 100644 --- a/man/std::move_backward.3 +++ b/man/std::move_backward.3 @@ -1,24 +1,26 @@ -.TH std::move_backward 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_backward 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_backward \- std::move_backward + .SH Synopsis - Defined in header - template< class BidirIt1, class BidirIt2 > - BidirIt2 move_backward( BidirIt1 first, BidirIt1 last, BidirIt2 \fI(since C++11)\fP - d_last ); + template< class BidirIt1, class BidirIt2 > \fI(since C++11)\fP + BidirIt2 move_backward( BidirIt1 first, BidirIt1 last, (constexpr since C++20) + BidirIt2 d_last ); Moves the elements from the range [first, last), to another range ending at d_last. The elements are moved in reverse order (the last element is moved first), but their relative order is preserved. - The behavior is undefined if d_last is within (first, last]. std::move must be used - instead of std::move_backward in that case. + If d_last is within (first, last], the behavior is undefined. In this case, + std::move may be used instead. .SH Parameters - first, last - the range of the elements to move - d_last - end of the destination range + first, last - the range of the elements to move + d_last - end of the destination range .SH Type requirements - - BidirIt1, BidirIt2 must meet the requirements of BidirectionalIterator. + BidirIt1, BidirIt2 must meet the requirements of LegacyBidirectionalIterator. .SH Return value @@ -26,18 +28,16 @@ .SH Complexity - Exactly last - first move assignments. + Exactly std::distance(first, last) move assignments. .SH Possible implementation - template< class BidirIt1, class BidirIt2 > - BidirIt2 move_backward(BidirIt1 first, - BidirIt1 last, - BidirIt2 d_last) + template + BidirIt2 move_backward(BidirIt1 first, BidirIt1 last, BidirIt2 d_last) { - while (first != last) { + while (first != last) *(--d_last) = std::move(*(--last)); - } + return d_last; } @@ -50,54 +50,64 @@ .SH Example - + // Run this code #include - #include - #include #include - - int main() + #include + #include + #include + #include + + using container = std::vector; + + void print(std::string_view comment, const container& src, const container& dst = {}) { - std::vector src{"foo", "bar", "baz"}; - std::vector dest(src.size()); - - std::cout << "src: "; - for (const auto &s : src) - { - std::cout << s << ' '; - } - std::cout << "\\ndest: "; - for (const auto &s : dest) - { - std::cout << s << ' '; - } - std::cout << '\\n'; - - std::move_backward(src.begin(), src.end(), dest.end()); - - std::cout << "src: "; - for (const auto &s : src) - { - std::cout << s << ' '; - } - std::cout << "\\ndest: "; - for (const auto &s : dest) + auto prn = [](std::string_view name, const container& cont) { - std::cout << s << ' '; - } - std::cout << '\\n'; + std::cout << name; + for (const auto &s : cont) + std::cout << (s.empty() ? "∙" : s.data()) << ' '; + std::cout << '\\n'; + }; + std::cout << comment << '\\n'; + prn("src: ", src); + if (dst.empty()) + return; + prn("dst: ", dst); + } + + int main() + { + container src{"foo", "bar", "baz"}; + container dst{"qux", "quux", "quuz", "corge"}; + print("Non-overlapping case; before move_backward:", src, dst); + std::move_backward(src.begin(), src.end(), dst.end()); + print("After:", src, dst); + + src = {"snap", "crackle", "pop", "lock", "drop"}; + print("Overlapping case; before move_backward:", src); + std::move_backward(src.begin(), std::next(src.begin(), 3), src.end()); + print("After:", src); } .SH Output: + Non-overlapping case; before move_backward: src: foo bar baz - dest: - src: - dest: foo bar baz + dst: qux quux quuz corge + After: + src: ∙ ∙ ∙ + dst: qux foo bar baz + Overlapping case; before move_backward: + src: snap crackle pop lock drop + After: + src: ∙ ∙ snap crackle pop .SH See also - move moves a range of elements to a new location - \fI(C++11)\fP \fI(function template)\fP + move moves a range of elements to a new location + \fI(C++11)\fP \fI(function template)\fP + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) diff --git a/man/std::move_constructible.3 b/man/std::move_constructible.3 new file mode 100644 index 000000000..157143137 --- /dev/null +++ b/man/std::move_constructible.3 @@ -0,0 +1,37 @@ +.TH std::move_constructible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_constructible \- std::move_constructible + +.SH Synopsis + Defined in header + template< class T > + concept move_constructible = std::constructible_from && \fI(since C++20)\fP + std::convertible_to; + + The concept move_constructible is satisfied if T is a reference type, or if it is an + object type where an object of that type can be constructed from an rvalue of that + type in both direct- and copy-initialization contexts, with the usual semantics. + + Semantic requirements + + If T is an object type, then move_constructible is modeled only if given + + * rv, an rvalue of type T, and + * u2, a distinct object of type T equal to rv, + + the following are true: + + * After the definition T u = rv;, u is equal to u2; + * T(rv) is equal to u2; and + * If T is not const-qualified, then rv's resulting state (after the + definition/expression is evaluated in either bullets above) is valid but + unspecified; otherwise, it is unchanged. + +.SH See also + + is_move_constructible + is_trivially_move_constructible checks if a type can be constructed from an rvalue + is_nothrow_move_constructible reference + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::move_if_noexcept.3 b/man/std::move_if_noexcept.3 index 6e337b678..7b2625173 100644 --- a/man/std::move_if_noexcept.3 +++ b/man/std::move_if_noexcept.3 @@ -1,28 +1,32 @@ -.TH std::move_if_noexcept 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_if_noexcept 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_if_noexcept \- std::move_if_noexcept + .SH Synopsis Defined in header template< class T > - typename std::conditional< + typename std::conditional< !std::is_nothrow_move_constructible::value && \fI(since C++11)\fP std::is_copy_constructible::value, \fI(until C++14)\fP const T&, T&& - >::type move_if_noexcept(T& x); + >::type move_if_noexcept( T& x ) noexcept; template< class T > - constexpr typename std::conditional< + constexpr typename std::conditional< !std::is_nothrow_move_constructible::value && std::is_copy_constructible::value, \fI(since C++14)\fP const T&, T&& - >::type move_if_noexcept(T& x); + >::type move_if_noexcept( T& x ) noexcept; - move_if_noexcept obtains an rvalue reference to its argument if its move constructor - does not throw exceptions, otherwise obtains an lvalue reference to its argument. It - is typically used to combine move semantics with strong exception guarantee. + std::move_if_noexcept obtains an rvalue reference to its argument if its move + constructor does not throw exceptions or if there is no copy constructor (move-only + type), otherwise obtains an lvalue reference to its argument. It is typically used + to combine move semantics with strong exception guarantee. .SH Parameters @@ -32,11 +36,9 @@ std::move(x) or x, depending on exception guarantees. -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Constant. .SH Notes @@ -44,22 +46,22 @@ storage and then move or copy elements from old storage to new storage. If an exception occurs during this operation, std::vector::resize undoes everything it did to this point, which is only possible if std::move_if_noexcept was used to decide - whether to use move construction or copy construction. (unless copy constructor is + whether to use move construction or copy construction (unless copy constructor is not available, in which case move constructor is used either way and the strong - exception guarantee may be waived) + exception guarantee may be waived). .SH Example - + // Run this code #include #include - + struct Bad { Bad() {} - Bad(Bad&&) // may throw + Bad(Bad&&) // may throw { std::cout << "Throwing move constructor called\\n"; } @@ -68,7 +70,7 @@ std::cout << "Throwing copy constructor called\\n"; } }; - + struct Good { Good() {} @@ -81,13 +83,13 @@ std::cout << "Non-throwing copy constructor called\\n"; } }; - + int main() { Good g; Bad b; - Good g2 = std::move_if_noexcept(g); - Bad b2 = std::move_if_noexcept(b); + [[maybe_unused]] Good g2 = std::move_if_noexcept(g); + [[maybe_unused]] Bad b2 = std::move_if_noexcept(b); } .SH Output: @@ -95,13 +97,9 @@ Non-throwing move constructor called Throwing copy constructor called -.SH Complexity - - Constant - .SH See also forward forwards a function argument - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP move obtains an rvalue reference - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::move_iterator.3 b/man/std::move_iterator.3 index 2bacf8ce6..4d247adb7 100644 --- a/man/std::move_iterator.3 +++ b/man/std::move_iterator.3 @@ -1,98 +1,173 @@ -.TH std::move_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator \- std::move_iterator + .SH Synopsis Defined in header - template< class Iterator > \fI(since C++11)\fP + template< class Iter > \fI(since C++11)\fP class move_iterator; std::move_iterator is an iterator adaptor which behaves exactly like the underlying - iterator (which must be at least an InputIterator), except that dereferencing - converts the value returned by the underlying iterator into an rvalue. If this - iterator is used as an input iterator, the effect is that the values are moved from, - rather than copied from. - -.SH Member types - - Member type Definition - iterator_type Iterator - difference_type std::iterator_traits::difference_type - pointer Iterator - value_type std::iterator_traits::value_type - iterator_category std::iterator_traits::iterator_category - reference value_type&& + iterator (which must be at least a LegacyInputIterator + or model input_iterator + \fI(since C++20)\fP + , or stronger iterator concept + (since C++23)), except that dereferencing converts the value returned by the + underlying iterator into an rvalue. If this iterator is used as an input iterator, + the effect is that the values are moved from, rather than copied from. .SH Member functions - constructor constructs a new iterator adaptor - \fI(public member function)\fP - operator= assigns another iterator - \fI(public member function)\fP - base accesses the underlying iterator - \fI(public member function)\fP - operator* accesses the pointed-to element - operator-> \fI(public member function)\fP - operator[] obtains rvalue reference to indexed element - \fI(public member function)\fP + constructor constructs a new iterator adaptor + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns another iterator adaptor + \fI(C++11)\fP \fI(public member function)\fP + base accesses the underlying iterator + \fI(C++11)\fP \fI(public member function)\fP + operator* + operator-> accesses the pointed-to element + \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP(deprecated in C++20) + operator[] accesses an element by index + \fI(C++11)\fP \fI(public member function)\fP operator++ operator++(int) operator+= - operator+ advances or decrements the iterator - operator-- \fI(public member function)\fP + operator+ advances or decrements the iterator + operator-- \fI(public member function)\fP operator--(int) operator-= operator- + \fI(C++11)\fP .SH Non-member functions operator== operator!= - operator< compares the underlying iterators - operator<= \fI(function template)\fP + operator< + operator<= operator> operator>= - operator+ advances the iterator - \fI(function template)\fP - operator- computes the distance between two iterator adaptors - \fI(function template)\fP + operator<=> compares the underlying iterators + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + (C++20) + operator==(std::move_sentinel) compares the underlying iterator and the underlying + (C++20) sentinel + \fI(function template)\fP + operator+ advances the iterator + \fI(C++11)\fP \fI(function template)\fP + operator- computes the distance between two iterator adaptors + \fI(C++11)\fP \fI(function template)\fP + operator-(std::move_sentinel) computes the distance between the underlying iterator + (C++20) and the underlying sentinel + \fI(function template)\fP + iter_move casts the result of dereferencing the underlying + (C++20) iterator to its associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying + (C++20) iterators + \fI(function template)\fP + make_move_iterator creates a std::move_iterator of type inferred from + \fI(C++11)\fP the argument + \fI(function template)\fP + + Helper templates + + template< class Iterator1, class Iterator2 > + + requires (!std::sized_sentinel_for) + constexpr bool disable_sized_sentinel_for< \fI(since C++20)\fP + std::move_iterator, + + std::move_iterator> = true; + + This partial specialization of std::disable_sized_sentinel_for prevents + specializations of move_iterator from satisfying sized_sentinel_for if their + underlying iterators do not satisfy the concept. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_move_iterator_concept 202207L (C++23) Make std::move_iterator a random + access iterator .SH Example - + // Run this code - #include #include - #include + #include + #include #include - #include - - int main() + #include + #include + #include + #include + + void print(const std::string_view rem, const auto& v) { - std::vector v{"this", "is", "an", "example"}; - - std::cout << "Old contents of the vector: "; - for (auto& s : v) - std::cout << '"' << s << "\\" "; - - typedef std::vector::iterator iter_t; - std::string concat = std::accumulate( - std::move_iterator(v.begin()), - std::move_iterator(v.end()), - std::string()); // Can be simplified with std::make_move_iterator - - std::cout << "\\nConcatenated as string: " << concat << '\\n' - << "New contents of the vector: "; - for (auto& s : v) - std::cout << '"' << s << "\\" "; + std::cout << rem; + for (const auto& s : v) + std::cout << std::quoted(s) << ' '; std::cout << '\\n'; + }; + + int main() + { + std::vector v{"this", "_", "is", "_", "an", "_", "example"}; + print("Old contents of the vector: ", v); + std::string concat; + for (auto begin = std::make_move_iterator(v.begin()), + end = std::make_move_iterator(v.end()); + begin != end; ++begin) + { + std::string temp{*begin}; // moves the contents of *begin to temp + concat += temp; + } + + // Starting from C++17, which introduced class template argument deduction, + // the constructor of std::move_iterator can be used directly: + // std::string concat = std::accumulate(std::move_iterator(v.begin()), + // std::move_iterator(v.end()), + // std::string()); + + print("New contents of the vector: ", v); + print("Concatenated as string: ", std::ranges::single_view(concat)); } -.SH Output: +.SH Possible output: + + Old contents of the vector: "this" "_" "is" "_" "an" "_" "example" + New contents of the vector: "" "" "" "" "" "" "" + Concatenated as string: "this_is_an_example" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Old contents of the vector: "this" "is" "an" "example" - Concatenated as string: thisisanexample - New contents of the vector: "" "" "" "" + DR Applied Behavior as published Correct behavior + to + dereferencing a move_iterator could return a + LWG 2106 C++11 dangling reference returns the + if the dereferencing the underlying iterator object instead + returns a prvalue + LWG 3736 C++20 move_iterator was missing added + disable_sized_sentinel_for specialization + member iterator_category was defined even if iterator_category + P2259R1 C++20 std::iterator_traits::iterator_category is is + not defined not defined in + this case .SH See also make_move_iterator creates a std::move_iterator of type inferred from the argument - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + move_sentinel sentinel adaptor for use with std::move_iterator + (C++20) \fI(class template)\fP diff --git a/man/std::move_iterator::base.3 b/man/std::move_iterator::base.3 index 08272bfbf..a6ac1b3e2 100644 --- a/man/std::move_iterator::base.3 +++ b/man/std::move_iterator::base.3 @@ -1,31 +1,76 @@ -.TH std::move_iterator::base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator::base \- std::move_iterator::base + .SH Synopsis - Iterator base() const; + iterator_type base() const; \fI(since C++11)\fP + \fI(until C++17)\fP + constexpr iterator_type base() const; \fB(1)\fP \fI(since C++17)\fP + \fI(until C++20)\fP + constexpr const iterator_type& base() const& noexcept; \fI(since C++20)\fP + constexpr iterator_type base() &&; \fB(2)\fP \fI(since C++20)\fP Returns the underlying base iterator. + 1) Copy constructs the return value from the underlying iterator. \fI(until C++20)\fP + 1) Returns a reference to the underlying iterator. \fI(since C++20)\fP + + 2) Move constructs the return value from the underlying iterator. + .SH Parameters \fI(none)\fP .SH Return value - The underlying iterator. + 1) A copy of the underlying iterator. \fI(until C++20)\fP + 1) A reference to the underlying iterator. \fI(since C++20)\fP + + 2) An iterator move constructed from the underlying iterator. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include - operator* accesses the pointed-to element - operator-> \fI(public member function)\fP + int main() + { + std::vector v{0, 1, 2, 3, 4}; + std::move_iterator::reverse_iterator> + m1{v.rbegin()}, + m2{v.rend()}; -.SH Category: + std::copy(m1.base(), m2.base(), std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + +.SH Output: + + 4 3 2 1 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3391 C++20 the const version of base returns a copy of returns a reference + the underlying iterator + LWG 3593 C++20 the const version of base returns a made noexcept + reference but might not be noexcept + +.SH See also - * Todo no example + operator* + operator-> accesses the pointed-to element + \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP(deprecated in C++20) diff --git a/man/std::move_iterator::move_iterator.3 b/man/std::move_iterator::move_iterator.3 index 62441e54f..070d67874 100644 --- a/man/std::move_iterator::move_iterator.3 +++ b/man/std::move_iterator::move_iterator.3 @@ -1,16 +1,37 @@ -.TH std::move_iterator::move_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator::move_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator::move_iterator \- std::move_iterator::move_iterator + .SH Synopsis - move_iterator(); \fB(1)\fP - explicit move_iterator( Iterator x ); \fB(2)\fP - template< class U > \fB(3)\fP - move_iterator( const move_iterator& other ); + move_iterator(); \fI(until C++17)\fP + constexpr move_iterator(); \fI(since C++17)\fP + explicit move_iterator( \fI(until C++17)\fP + iterator_type x ); + constexpr explicit move_iterator( \fI(since C++17)\fP + iterator_type x ); \fB(1)\fP + template< class U > \fB(2)\fP + move_iterator( const \fI(until C++17)\fP + move_iterator& other ); \fB(3)\fP + template< class U > + constexpr move_iterator( const \fI(since C++17)\fP + move_iterator& other ); Constructs a new iterator adaptor. - 1) Default constructor. current is value-initialized. This makes sense only if - operations on an value-initialized Iterator make also sense. - 2) current is initialized with x. - 3) Copy constructor. The underlying iterator is initialized with that of other. + 1) Default constructor. The underlying iterator is value-initialized. Operations on + the resulting iterator have defined behavior if and only if the corresponding + operations on a value-initialized Iter also have defined behavior. + 2) The underlying iterator is initialized with + x + \fI(until C++20)\fP + std::move(x) + \fI(since C++20)\fP. + 3) The underlying iterator is initialized with that of other. + The behavior is undefined if U is not convertible to Iter + \fI(until C++20)\fP + This overload participates in overload resolution only if U is not the same type as + Iter and std::convertible_to is modeled + \fI(since C++20)\fP. .SH Parameters @@ -22,11 +43,21 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3435 C++20 the converting constructor from another constrained + move_iterator was not constrained + .SH See also - operator= assigns another iterator - \fI(public member function)\fP + operator= assigns another iterator adaptor + \fI(C++11)\fP \fI(public member function)\fP + make_move_iterator creates a std::move_iterator of type inferred from the argument + \fI(C++11)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::move_iterator::operator*,->.3 b/man/std::move_iterator::operator*,->.3 index 552652192..60f84862a 100644 --- a/man/std::move_iterator::operator*,->.3 +++ b/man/std::move_iterator::operator*,->.3 @@ -1,12 +1,22 @@ -.TH std::move_iterator::operator*,-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator::operator*,-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator::operator*,-> \- std::move_iterator::operator*,-> + .SH Synopsis - reference operator* () const; \fB(1)\fP - pointer operator->() const; \fB(2)\fP + reference operator* () const; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++17) + \fI(since C++11)\fP + pointer operator->() const; \fB(2)\fP (constexpr since C++17) + (deprecated in C++20) - Returns a rvalue-reference or pointer to the current element. + Returns an rvalue-reference or pointer to the current element. - 1) Equivalent to std::move(*current); - 2) Equivalent to current. + 1) Equivalent to + static_cast(*base()) + \fI(until C++20)\fP + ranges::iter_move(base()) + \fI(since C++20)\fP. + 2) Equivalent to base(). .SH Parameters @@ -14,18 +24,69 @@ .SH Return value - Rvalue-reference or pointer to the current element. + 1) Rvalue-reference to the current element or its copy. + 2) Copy of the underlying iterator. A pointer to the current element is eventually + returned if -> is directly used. + +.SH Notes + + Note that \fB(2)\fP eventually returns a pointer if -> is directly used. When + dereferencing a pointer the returned value is an lvalue. This may lead to unintended + behavior. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include + #include + + void print(auto rem, auto const& v) + { + for (std::cout << rem; auto const& e : v) + std::cout << std::quoted(e) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::vector p{"alpha", "beta", "gamma", "delta"}, q; + print("1) p: ", p); + for (std::move_iterator it{p.begin()}, end{p.end()}; it != end; ++it) + { + it->push_back('!'); // calls -> string::push_back(char) + q.emplace_back(*it); // *it <- overload (1) + } + print("2) p: ", p); + print("3) q: ", q); - operator[] obtains rvalue reference to indexed element - \fI(public member function)\fP + std::vector v{1, 2, 3}; + std::move_iterator it{v.begin()}; + // *it = 13; // error: using rvalue as lvalue + } -.SH Category: +.SH Possible output: + + 1) p: "alpha" "beta" "gamma" "delta" + 2) p: "" "" "" "" + 3) q: "alpha!" "beta!" "gamma!" "delta!" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + dereferencing a move_iterator could return a + LWG 2106 C++11 dangling reference returns the object + if the dereferencing the underlying iterator instead + returns a prvalue + +.SH See also - * Todo no example + operator[] accesses an element by index + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::move_iterator::operator++,+,+=,--,-,-=.3 b/man/std::move_iterator::operator++,+,+=,--,-,-=.3 index 749ec0eb3..cb3a18e62 100644 --- a/man/std::move_iterator::operator++,+,+=,--,-,-=.3 +++ b/man/std::move_iterator::operator++,+,+=,--,-,-=.3 @@ -1,27 +1,92 @@ -.TH std::move_iterator::operator++,+,+=,--,-,-= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator::operator++,+,+=,--,-,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator::operator++,+,+=,--,-,-= \- std::move_iterator::operator++,+,+=,--,-,-= + .SH Synopsis - move_iterator& operator++(); \fB(1)\fP - move_iterator& operator--(); \fB(2)\fP - move_iterator operator++( int ); \fB(3)\fP - move_iterator operator--( int ); \fB(4)\fP - move_iterator operator+( difference_type n ) const; \fB(5)\fP - move_iterator operator-( difference_type n ) const; \fB(6)\fP - move_iterator& operator+=( difference_type n ) const; \fB(7)\fP - move_iterator& operator-=( difference_type n ) const; \fB(8)\fP + move_iterator& (until + operator++(); C++17) + constexpr (since + move_iterator& C++17) + operator++(); + move_iterator& (until + operator--(); C++17) + constexpr (since + move_iterator& C++17) + operator--(); + move_iterator (until + operator++( int C++17) + ); + constexpr (since + move_iterator C++17) + operator++( int (until + ); C++20) + constexpr auto (since + operator++( int C++20) + ); + move_iterator (until + operator--( int C++17) + ); + constexpr + move_iterator (since + operator--( int C++17) + ); + move_iterator + operator+( (until + difference_type C++17) + n ) const; + constexpr \fB(1)\fP + move_iterator (since + operator+( \fB(2)\fP C++17) + difference_type + n ) const; + move_iterator \fB(3)\fP + operator-( (until + difference_type C++17) + n ) const; + constexpr + move_iterator \fB(4)\fP (since + operator-( C++17) + difference_type + n ) const; \fB(5)\fP + move_iterator& + operator+=( (until + difference_type C++17) + n ); + constexpr \fB(6)\fP + move_iterator& (since + operator+=( C++17) + difference_type + n ); \fB(7)\fP + move_iterator& + operator-=( (until + difference_type C++17) + n ); + constexpr \fB(8)\fP + move_iterator& (since + operator-=( C++17) + difference_type + n ); Increments or decrements the iterator. - 1-2) Pre-increments or pre-decrements by one respectively. - 3-4) Post-increments or post-decrements by one respectively. - 5-6) Returns an iterator which is advanced by n or -n positions respectively. - 7-8) Advances the iterator by n or -n positions respectively. + 1,2) Pre-increments or pre-decrements by one respectively. + 3,4) Post-increments or post-decrements by one respectively. + 5,6) Returns an iterator which is advanced by n or -n positions respectively. + 7,8) Advances the iterator by n or -n positions respectively. + +.SH Parameters + + n - position relative to current location .SH Return value - 1) *this - 2) a copy of *this that was made before the change - 3) move_iterator(base()+n) or move_iterator(base()-n) respectively. - 4) *this + 1,2) *this + 3,4) A copy of *this that was made before the change + , however, if Iter does not model forward_iterator, the post-increment operator does + not return such copy and the return type is void + \fI(since C++20)\fP. + 5,6) move_iterator(base()+n) or move_iterator(base()-n) respectively. + 7,8) *this .SH Example @@ -31,8 +96,9 @@ .SH See also operator+ advances the iterator - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + operator- computes the distance between two iterator adaptors + \fI(C++11)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::move_iterator::operator=.3 b/man/std::move_iterator::operator=.3 index b475fef38..2671ff84d 100644 --- a/man/std::move_iterator::operator=.3 +++ b/man/std::move_iterator::operator=.3 @@ -1,10 +1,20 @@ -.TH std::move_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator::operator= \- std::move_iterator::operator= + .SH Synopsis - template< class U > + template< class U > \fI(until C++17)\fP move_iterator& operator=( const move_iterator& other ); + template< class U > \fI(since C++17)\fP + constexpr move_iterator& operator=( const move_iterator& other ); + + The underlying iterator is assigned the value of the underlying iterator of other, + i.e. other.base(). - Copy assignment operator. The underlying iterator is assigned the value of the - underlying iterator of other, i.e. other.base(). + The behavior is undefined if U is not convertible to Iter. \fI(until C++20)\fP + This overload participates in overload resolution only if U is not the + same type as Iter and std::convertible_to and \fI(since C++20)\fP + std::assignable_from are modeled. .SH Parameters @@ -19,11 +29,19 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3435 C++20 the converting assignment operator was not constrained + constrained + .SH See also constructor constructs a new iterator adaptor - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::move_iterator::operator[].3 b/man/std::move_iterator::operator[].3 index 2f554b69a..00b7b86ac 100644 --- a/man/std::move_iterator::operator[].3 +++ b/man/std::move_iterator::operator[].3 @@ -1,27 +1,83 @@ -.TH std::move_iterator::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::move_iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_iterator::operator[] \- std::move_iterator::operator[] + .SH Synopsis - /*unspecified*/ operator[]( difference_type n ) const; \fI(since C++11)\fP + /* unspecified */ operator[]( difference_type n ) const; \fI(since C++11)\fP + \fI(until C++17)\fP + constexpr /* unspecified */ operator[]( difference_type n ) const; \fI(since C++17)\fP + \fI(until C++20)\fP + constexpr reference operator[]( difference_type n ) const; \fI(since C++20)\fP Returns a reference to the element at specified relative location. .SH Parameters - n - position relative to current location. + n - position relative to current location .SH Return value - A reference to the element at relative location, that is, current[n]. + An rvalue reference to the element at relative location, that is, + std::move(base()[n]) + \fI(until C++20)\fP + ranges::iter_move(base() + n) + \fI(since C++20)\fP. -.SH Examples +.SH Notes - This section is incomplete - Reason: no example + The return type is unspecified because the return type of the + underlying iterator's operator[] is also unspecified (see \fI(until C++20)\fP + LegacyRandomAccessIterator). -.SH See also +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(auto rem, auto const& v) + { + for (std::cout << rem; auto const& e : v) + std::cout << std::quoted(e) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::vector p{"alpha", "beta", "gamma", "delta"}, q; + print("1) p: ", p); - operator* accesses the pointed-to element - operator-> \fI(public member function)\fP + std::move_iterator it{p.begin()}; -.SH Category: + for (std::size_t t{}; t != p.size(); ++t) + q.emplace_back(it[t]); + + print("2) p: ", p); + print("3) q: ", q); + + std::list l{1, 2, 3}; + std::move_iterator it2{l.begin()}; + // it2[1] = 13; // compilation error: the underlying iterator + // does not model the random access iterator + // *it2 = 999; // compilation error: using rvalue as lvalue + } + +.SH Possible output: + + 1) p: "alpha" "beta" "gamma" "delta" + 2) p: "" "" "" "" + 3) q: "alpha" "beta" "gamma" "delta" + +.SH See also - * Todo no example + operator* + operator-> accesses the pointed-to element + \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP(deprecated in C++20) diff --git a/man/std::move_only_function.3 b/man/std::move_only_function.3 new file mode 100644 index 000000000..6e3cd1772 --- /dev/null +++ b/man/std::move_only_function.3 @@ -0,0 +1,131 @@ +.TH std::move_only_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function \- std::move_only_function + +.SH Synopsis + Defined in header + template< class... > \fB(1)\fP (since C++23) + class move_only_function; // not defined + template< class R, class... Args > + + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; \fB(2)\fP (since C++23) + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + class move_only_function; + template< class R, class... Args > + + class move_only_function; + + Class template std::move_only_function is a general-purpose polymorphic function + wrapper. std::move_only_function objects can store and invoke any constructible (not + required to be move constructible) Callable target — functions, lambda expressions, + bind expressions, or other function objects, as well as pointers to member functions + and pointers to member objects. + + The stored callable object is called the target of std::move_only_function. If a + std::move_only_function contains no target, it is called empty. Unlike + std::function, invoking an empty std::move_only_function results in undefined + behavior. + + std::move_only_functions supports every possible combination of cv-qualifiers, + ref-qualifiers, and noexcept-specifiers not including volatile provided in its + template parameter. These qualifiers and specifier (if any) are added to its + operator(). + + std::move_only_function satisfies the requirements of MoveConstructible and + MoveAssignable, but does not satisfy CopyConstructible or CopyAssignable. + +.SH Member types + + Type Definition + result_type R + +.SH Member functions + + constructor constructs a new std::move_only_function object + (C++23) \fI(public member function)\fP + destructor destroys a std::move_only_function object + (C++23) \fI(public member function)\fP + operator= replaces or destroys the target + (C++23) \fI(public member function)\fP + swap swaps the targets of two std::move_only_function objects + (C++23) \fI(public member function)\fP + operator bool checks if the std::move_only_function has a target + (C++23) \fI(public member function)\fP + operator() invokes the target + (C++23) \fI(public member function)\fP + +.SH Non-member functions + + swap(std::move_only_function) overloads the std::swap algorithm + (C++23) \fI(function)\fP + operator== compares a std::move_only_function with nullptr + (C++23) \fI(function)\fP + +.SH Notes + + Implementations may store a callable object of small size within the + std::move_only_function object. Such small object optimization is effectively + required for function pointers and std::reference_wrapper specializations, and can + only be applied to types T for which std::is_nothrow_move_constructible_v is + true. + + If a std::move_only_function returning a reference is initialized from a function or + function object returning a prvalue (including a lambda expression without a + trailing-return-type), the program is ill-formed because binding the returned + reference to a temporary object is forbidden. See also std::function Notes. + + Feature-test macro Value Std Feature + __cpp_lib_move_only_function 202110L (C++23) std::move_only_function + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::packaged_task packaged_task([](){ return 3.14159; }); + + std::future future = packaged_task.get_future(); + + auto lambda = [task = std::move(packaged_task)]() mutable { task(); }; + + // std::function function = std::move(lambda); // Error + std::move_only_function function = std::move(lambda); // OK + + function(); + + std::cout << future.get(); + } + +.SH Output: + + 3.14159 + +.SH See also + + function wraps callable object of any copy constructible type with specified + \fI(C++11)\fP function call signature + \fI(class template)\fP diff --git a/man/std::move_only_function::move_only_function.3 b/man/std::move_only_function::move_only_function.3 new file mode 100644 index 000000000..e2b6fa602 --- /dev/null +++ b/man/std::move_only_function::move_only_function.3 @@ -0,0 +1,105 @@ +.TH std::move_only_function::move_only_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function::move_only_function \- std::move_only_function::move_only_function + +.SH Synopsis + move_only_function() noexcept; \fB(1)\fP (since C++23) + move_only_function( std::nullptr_t ) noexcept; \fB(2)\fP (since C++23) + move_only_function( move_only_function&& other ) noexcept; \fB(3)\fP (since C++23) + move_only_function( const move_only_function& ) = delete; \fB(4)\fP (since C++23) + template< class F > \fB(5)\fP (since C++23) + move_only_function( F&& f ); + template< class T, class... CArgs > + explicit move_only_function( std::in_place_type_t, CArgs&&... \fB(6)\fP (since C++23) + args ); + template< class T, class U, class... CArgs > + + explicit move_only_function( std::in_place_type_t, \fB(7)\fP (since C++23) + + std::initializer_list il, + CArgs&&... args ); + + Creates a new std::move_only_function. + + 1,2) Default constructor and the constructor taking nullptr construct an empty + std::move_only_function. + 3) Move constructor constructs a std::move_only_function whose target is that of + other. other is in a valid but unspecified state after move construction. + 4) Copy constructor is deleted. std::move_only_function does not satisfy + CopyConstructible. + 5) Let VT be std::decay_t. If f is a null function pointer, a null pointer to + member value, or an empty std::move_only_function (may be any specialization), then + constructs an empty std::move_only_function. Otherwise, constructs a + std::move_only_function whose target is of type VT and direct-non-list-initialized + with std::forward(f). + * This overload participates in overload resolution only if VT is neither same as + move_only_function nor a specialization of std::in_place_type_t, and + /*is-callable-from*/ (see below) is true. + * The program is ill-formed if std::is_constructible_v is not true. + 6) Let VT be std::decay_t. Constructs a std::move_only_function whose target is + of type VT and direct-non-list-initialized with std::forward(args).... + * This overload participates in overload resolution only if both + std::is_constructible_v and /*is-callable-from*/ (see below) + are true. + * The program is ill-formed if VT is not the same type as T. + 7) Let VT be std::decay_t. Constructs a std::move_only_function whose target is + of type VT and direct-non-list-initialized with il, std::forward(args).... + * This overload participates in overload resolution only if both + std::is_constructible_v&, CArgs...> and + /*is-callable-from*/ (see below) are true. + * The program is ill-formed if VT is not the same type as T. + + For constructors (5-7), the behavior is undefined if VT does not satisfy the + Destructible requirements, or std::is_move_constructible_v is true but VT does + not satisfy the MoveConstructible requirements. + + The constant /*is-callable-from*/ is dependent on cv, ref, and noex in the + template parameter of std::move_only_function as below: + + cv ref noexcept(noex) /*is-callable-from*/ + std::is_invocable_r_v && + noexcept(false) + std::is_invocable_r_v + std::is_nothrow_invocable_r_v && + noexcept(true) + std::is_nothrow_invocable_r_v + std::is_invocable_r_v && + const noexcept(false) + std::is_invocable_r_v + std::is_nothrow_invocable_r_v && + const noexcept(true) + std::is_nothrow_invocable_r_v + & noexcept(false) std::is_invocable_r_v + & noexcept(true) std::is_nothrow_invocable_r_v + const & noexcept(false) std::is_invocable_r_v + const & noexcept(true) std::is_nothrow_invocable_r_v + && noexcept(false) std::is_invocable_r_v + && noexcept(true) std::is_nothrow_invocable_r_v + const && noexcept(false) std::is_invocable_r_v + const && noexcept(true) std::is_nothrow_invocable_r_v + +.SH Parameters + + other - another std::move_only_function to move from + f - a function or a Callable object to wrap + args - arguments to construct the target object + il - std::initializer_list to construct the target object + +.SH Exceptions + + 5-7) May throw std::bad_alloc on allocation failure or propagate the exception + thrown by the initialization of the target. No exception is thrown if VT is a + function pointer type or a specialization of std::reference_wrapper. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new std::function instance + \fI(public member function of std::function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::move_only_function::operator().3 b/man/std::move_only_function::operator().3 new file mode 100644 index 000000000..98251fef3 --- /dev/null +++ b/man/std::move_only_function::operator().3 @@ -0,0 +1,85 @@ +.TH std::move_only_function::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function::operator() \- std::move_only_function::operator() + +.SH Synopsis + R operator()( Args... args ) /*cv*/ /*ref*/ noexcept(/*noex*/); (since C++23) + + Invokes the stored callable target with the parameters args. The /*cv*/, /*ref*/, + and /*noex*/ parts of operator() are identical to those of the template parameter of + std::move_only_function. + + Equivalent to return std::invoke_r(/*cv-ref-cast*/(f), + std::forward(args)...);, where f is a cv-unqualified lvalue that denotes the + target object of *this, and /*cv-ref-cast*/(f) is equivalent to: + + * f if cv ref is either empty or &, or + * std::as_const(f) if cv ref is either const or const &, or + * std::move(f) if cv ref is &&, or + * std::move(std::as_const(f)) if cv ref is const &&. + + The behavior is undefined if *this is empty. + +.SH Parameters + + args - parameters to pass to the stored callable target + +.SH Return value + + std::invoke_r(/*cv-ref-cast*/(f), std::forward(args)...). + +.SH Exceptions + + Propagates the exception thrown by the underlying function call. + +.SH Example + + The following example shows how std::move_only_function can passed to other + functions by value. Also, it shows how std::move_only_function can store lambdas. + + +// Run this code + + #include + #include + + void call(std::move_only_function f) // can be passed by value + { + std::cout << f() << '\\n'; + } + + int normal_function() + { + return 42; + } + + int main() + { + int n = 1; + auto lambda = [&n](){ return n; }; + std::move_only_function f = lambda; + call(std::move(f)); + + n = 2; + call(lambda); + + f = normal_function; + call(std::move(f)); + } + +.SH Output: + + 1 + 2 + 42 + +.SH See also + + operator() invokes the target + \fI(public member function of std::function)\fP + operator() calls the stored function + \fI(public member function of std::reference_wrapper)\fP + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP diff --git a/man/std::move_only_function::operator=.3 b/man/std::move_only_function::operator=.3 new file mode 100644 index 000000000..93c86c3e9 --- /dev/null +++ b/man/std::move_only_function::operator=.3 @@ -0,0 +1,49 @@ +.TH std::move_only_function::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function::operator= \- std::move_only_function::operator= + +.SH Synopsis + move_only_function& operator=( move_only_function&& other ); \fB(1)\fP (since C++23) + move_only_function& operator=( const move_only_function& ) = \fB(2)\fP (since C++23) + delete; + move_only_function& operator=( std::nullptr_t ) noexcept; \fB(3)\fP (since C++23) + template< class F > \fB(4)\fP (since C++23) + move_only_function& operator=( F&& f ); + + Assigns a new target to std::move_only_function or destroys its target. + + 1) Moves the target of other to *this or destroys the target of *this (if any) if + other is empty, by auto(std::move(other)).swap(*this). other is in a valid state + with an unspecified value after move assignment. + 2) Copy assignment operator is deleted. std::move_only_function does not satisfy + CopyAssignable. + 3) Destroys the current target if it exists. *this is empty after the call. + 4) Sets the target of *this to the callable f, or destroys the current target if f + is a null function pointer, a null pointer to member function, or an empty + std::move_only_function, as if by executing + move_only_function(std::forward(f)).swap(*this);. This overload participates in + overload resolution only if the constructor of move_only_function from F + participates in overload resolution. The program is ill-formed or has undefined + behavior if the selected constructor call is ill-formed or has undefined behavior. + +.SH Parameters + + other - another std::move_only_function object to move the target of + f - a callable object to initialize the new target with + +.SH Return value + + *this + +.SH Notes + + It is intentional not to require the move assignment operator to be noexcept to + leave room for an allocator-aware move_only_function in future. + + move_only_function can be assigned from std::in_place_type given it can be + constructed from that argument. + +.SH See also + + operator= assigns a new target + \fI(public member function of std::function)\fP diff --git a/man/std::move_only_function::operatorbool.3 b/man/std::move_only_function::operatorbool.3 new file mode 100644 index 000000000..c3e023eb3 --- /dev/null +++ b/man/std::move_only_function::operatorbool.3 @@ -0,0 +1,66 @@ +.TH std::move_only_function::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function::operatorbool \- std::move_only_function::operatorbool + +.SH Synopsis + explicit operator bool() const noexcept; (since C++23) + + Checks whether *this stores a callable target, i.e. is not empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if *this stores a callable target, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + + void sampleFunction() + { + std::cout << "This is the sample function!\\n"; + } + + void checkFunc(std::move_only_function const& func) + { + // Use operator bool to determine if callable target is available. + if (func) + { + std::cout << "Function is not empty! Calling function.\\n"; + func(); + } + else + std::cout << "Function is empty. Nothing to do.\\n"; + } + + int main() + { + std::move_only_function f1{}; + std::move_only_function f2{sampleFunction}; + + std::cout << "f1: "; + checkFunc(f1); + + std::cout << "f2: "; + checkFunc(f2); + } + +.SH Output: + + f1: Function is empty. Nothing to do. + f2: Function is not empty! Calling function. + This is the sample function! + +.SH See also + + operator== compares a std::move_only_function with nullptr + (C++23) \fI(function)\fP + operator bool checks if a target is contained + \fI(public member function of std::function)\fP diff --git a/man/std::move_only_function::swap.3 b/man/std::move_only_function::swap.3 new file mode 100644 index 000000000..d53389e75 --- /dev/null +++ b/man/std::move_only_function::swap.3 @@ -0,0 +1,21 @@ +.TH std::move_only_function::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function::swap \- std::move_only_function::swap + +.SH Synopsis + void swap( move_only_function& other ) noexcept; (since C++23) + + Exchanges the stored callable objects of *this and other. + +.SH Parameters + + other - function wrapper to exchange the stored callable object with + +.SH Return value + + \fI(none)\fP + +.SH See also + + swap swaps the contents + \fI(public member function of std::function)\fP diff --git a/man/std::move_only_function::~move_only_function.3 b/man/std::move_only_function::~move_only_function.3 new file mode 100644 index 000000000..2f9060a16 --- /dev/null +++ b/man/std::move_only_function::~move_only_function.3 @@ -0,0 +1,14 @@ +.TH std::move_only_function::~move_only_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_only_function::~move_only_function \- std::move_only_function::~move_only_function + +.SH Synopsis + ~move_only_function(); (since C++23) + + Destroys the std::move_only_function object. If the std::move_only_function is not + empty, its target is also destroyed. + +.SH See also + + destructor destroys a std::function instance + \fI(public member function of std::function)\fP diff --git a/man/std::move_sentinel.3 b/man/std::move_sentinel.3 new file mode 100644 index 000000000..418c7099c --- /dev/null +++ b/man/std::move_sentinel.3 @@ -0,0 +1,54 @@ +.TH std::move_sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_sentinel \- std::move_sentinel + +.SH Synopsis + Defined in header + template< std::semiregular S > \fI(since C++20)\fP + class move_sentinel; + + std::move_sentinel is a sentinel adaptor used for denoting ranges together with + std::move_iterator. + +.SH Template parameters + + S - the type of underlying sentinel + +.SH Member functions + + constructor constructs a new move_sentinel + (C++20) \fI(public member function)\fP + operator= assigns the contents of one move_sentinel to another + (C++20) \fI(public member function)\fP + base return a copy of the underlying sentinel + (C++20) \fI(public member function)\fP + +.SH Member objects + + Member name Definition + last (private member object) underlying sentinel, the name is for exposition only + +.SH Non-member functions + + Notes: These functions are hidden friends of std::move_iterator and invisible to + ordinary unqualified or qualified lookup. + + operator==(std::move_sentinel) compares the underlying iterator and the underlying + (C++20) sentinel + \fI(function template)\fP + operator-(std::move_sentinel) computes the distance between the underlying iterator + (C++20) and the underlying sentinel + \fI(function template)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + move_iterator iterator adaptor which dereferences to an rvalue + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::move_sentinel::base.3 b/man/std::move_sentinel::base.3 new file mode 100644 index 000000000..17ad964ce --- /dev/null +++ b/man/std::move_sentinel::base.3 @@ -0,0 +1,33 @@ +.TH std::move_sentinel::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_sentinel::base \- std::move_sentinel::base + +.SH Synopsis + constexpr S base() const; \fI(since C++20)\fP + + Returns the underlying base sentinel. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The underlying sentinel. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + base accesses the underlying iterator + \fI(C++11)\fP \fI(public member function of std::move_iterator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::move_sentinel::move_sentinel.3 b/man/std::move_sentinel::move_sentinel.3 new file mode 100644 index 000000000..f153f9cf9 --- /dev/null +++ b/man/std::move_sentinel::move_sentinel.3 @@ -0,0 +1,37 @@ +.TH std::move_sentinel::move_sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_sentinel::move_sentinel \- std::move_sentinel::move_sentinel + +.SH Synopsis + constexpr move_sentinel(); \fB(1)\fP \fI(since C++20)\fP + constexpr explicit move_sentinel( S x ); \fB(2)\fP \fI(since C++20)\fP + template< class S2 > + + requires std::convertible_to \fB(3)\fP \fI(since C++20)\fP + + constexpr move_sentinel( const std::move_sentinel& + other ); + + Constructs a new sentinel adaptor. + + 1) Default constructor. The underlying sentinel is value-initialized. + 2) The underlying sentinel is initialized with x. + 3) The underlying sentinel is initialized with that of other. + +.SH Parameters + + x - sentinel to adapt + other - sentinel adaptor to copy + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new iterator adaptor + \fI(C++11)\fP \fI(public member function of std::move_iterator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::move_sentinel::operator=.3 b/man/std::move_sentinel::operator=.3 new file mode 100644 index 000000000..0d53c20fa --- /dev/null +++ b/man/std::move_sentinel::operator=.3 @@ -0,0 +1,35 @@ +.TH std::move_sentinel::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::move_sentinel::operator= \- std::move_sentinel::operator= + +.SH Synopsis + template< class S2 > + + requires std::assignable_from \fI(since C++20)\fP + + constexpr move_sentinel& operator=( const + std::move_sentinel& other ); + + The underlying sentinel is assigned the value of the underlying sentinel of other, + i.e. other.base(). + +.SH Parameters + + other - sentinel adaptor to assign + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns another iterator adaptor + \fI(C++11)\fP \fI(public member function of std::move_iterator)\fP + +.SH Category: + * Todo no example diff --git a/man/std::mul_sat.3 b/man/std::mul_sat.3 new file mode 100644 index 000000000..9d7ca60ec --- /dev/null +++ b/man/std::mul_sat.3 @@ -0,0 +1,98 @@ +.TH std::mul_sat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mul_sat \- std::mul_sat + +.SH Synopsis + Defined in header + template< class T > (since C++26) + constexpr T mul_sat( T x, T y ) noexcept; + + Computes the saturating multiplication x × y. This operation (unlike built-in + arithmetic operations on integers) behaves as-if it is a mathematical operation with + an infinite range. Let q denote the result of such operation. Returns: + + * q, if q is representable as a value of type T. Otherwise, + * the largest or smallest value of type T, whichever is closer to the q. + + This overload participates in overload resolution only if T is an integer type, that + is: signed char, short, int, long, long long, an extended signed integer type, or an + unsigned version of such types. In particular, T must not be (possibly cv-qualified) + bool, char, wchar_t, char8_t, char16_t, and char32_t, as these types are not + intended for arithmetic. + +.SH Parameters + + x, y - integer values + +.SH Return value + + Saturated x × y. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Unlike the built-in arithmetic operators on integers, the integral promotion does + not apply to the x and y arguments. + + If two arguments of different type are passed, the call fails to compile, i.e. the + behavior relative to template argument deduction is the same as for std::min or + std::max. + + Most modern hardware architectures have efficient support for saturation arithmetic + on SIMD vectors, including SSE2 for x86 and NEON for ARM. + + Feature-test macro Value Std Feature + __cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic + +.SH Possible implementation + + See libstdc++ (gcc). + +.SH Example + + Can be previewed on Compiler Explorer. + + +// Run this code + + #include + #include + + static_assert + ("" + && (std::mul_sat(2, 3) == 6) // not saturated + && (std::mul_sat(INT_MAX / 2, 3) == INT_MAX) // saturated + && (std::mul_sat(-2, 3) == -6) // not saturated + && (std::mul_sat(INT_MIN / -2, -3) == INT_MIN) // saturated + && (std::mul_sat(2, 3) == 6) // not saturated + && (std::mul_sat(UINT_MAX / 2, 3) == UINT_MAX) // saturated + ); + + int main() {} + +.SH See also + + add_sat saturating addition operation on two integers + (C++26) \fI(function template)\fP + sub_sat saturating subtraction operation on two integers + (C++26) \fI(function template)\fP + div_sat saturating division operation on two integers + (C++26) \fI(function template)\fP + saturate_cast returns an integer value clamped to the range of a another integer + (C++26) type + \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP + min returns the smallest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + max returns the largest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + +.SH External links + + 1. A branch-free implementation of saturation arithmetic — Locklessinc.com, 2012 diff --git a/man/std::multimap.3 b/man/std::multimap.3 index 5782b3e18..c4a9e8b10 100644 --- a/man/std::multimap.3 +++ b/man/std::multimap.3 @@ -1,118 +1,207 @@ -.TH std::multimap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap \- std::multimap + .SH Synopsis Defined in header template< class Key, - class T, + class T, \fB(1)\fP class Compare = std::less, - class Allocator = std::allocator > + class Allocator = std::allocator> > class multimap; + namespace pmr { + + template< + class Key, + class T, \fB(2)\fP \fI(since C++17)\fP + class Compare = std::less + > using multimap = std::multimap>>; + + } + + std::multimap is an associative container that contains a sorted list of key-value + pairs, while permitting multiple entries with the same key. Sorting is done + according to the comparison function Compare, applied to the keys. Search, + insertion, and removal operations have logarithmic complexity. + + Iterators of std::multimap iterate in non-descending order of keys, where + non-descending is defined by the comparison that was used for construction. That is, + given + + * m, a std::multimap + * it_l and it_r, dereferenceable iterators to m, with it_l < it_r. - Multimap is an associative container that contains a sorted list of key-value pairs. - Sorting is done according to the comparison function Compare, applied to the keys. - Search, insertion, and removal operations have logarithmic complexity. + m.value_comp()(*it_r, *it_l) == false (least to greatest if using the default + comparison). - The order of the key-value pairs whose keys compare equivalent is the order of - insertion and does not change. \fI(since C++11)\fP + The order of the key-value pairs whose keys compare equivalent is the \fI(since C++11)\fP + order of insertion and does not change. + + Everywhere the standard library uses the Compare requirements, equivalence is + determined by using the equivalence relation as described on Compare. In imprecise + terms, two objects a and b are considered equivalent if neither compares less than + the other: !comp(a, b) && !comp(b, a). std::multimap meets the requirements of Container, AllocatorAwareContainer, AssociativeContainer and ReversibleContainer. +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - mapped_type T - value_type std::pair - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - key_compare Compare - allocator_type Allocator - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP - pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP - const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator BidirectionalIterator - const_iterator Constant bidirectional iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + Member type Definition + key_type Key + mapped_type T + value_type std::pair + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + key_compare Compare + allocator_type Allocator + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer (until + C++11) + const_pointer std::allocator_traits::const_pointer (since + C++11) + + + iterator LegacyBidirectionalIterator to value_type + const_iterator LegacyBidirectionalIterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node .SH Member classes value_compare compares objects of type value_type - \fI(class)\fP + \fI(class)\fP .SH Member functions constructor constructs the multimap - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the multimap - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP + \fI(C++11)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + \fI(C++11)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP .SH Observers key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the multimap - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two multimaps + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::multimap) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase_if(std::multimap) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + Key was not required to be + LWG 230 C++98 CopyConstructible Key is also required to + (a key of type Key might not be able to be CopyConstructible + be constructed) + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::multimap::begin,.3 b/man/std::multimap::begin,.3 new file mode 100644 index 000000000..da0366147 --- /dev/null +++ b/man/std::multimap::begin,.3 @@ -0,0 +1,96 @@ +.TH std::multimap::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::begin, \- std::multimap::begin, + +.SH Synopsis + + iterator begin(); \fB(1)\fP (noexcept since C++11) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the first element of the multimap. + + If the multimap is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto show_node = [](const auto& node, char ending = '\\n') + { + std::cout << "{ " << node.first << ", " << node.second << " }" << ending; + }; + + std::multimap mmap; + assert(mmap.begin() == mmap.end()); // OK + assert(mmap.cbegin() == mmap.cend()); // OK + + mmap.insert({ sizeof(long), "LONG" }); + show_node(*(mmap.cbegin())); + assert(mmap.begin() != mmap.end()); // OK + assert(mmap.cbegin() != mmap.cend()); // OK + mmap.begin()->second = "long"; + show_node(*(mmap.cbegin())); + + mmap.insert({ sizeof(int), "int" }); + show_node(*mmap.cbegin()); + + mmap.insert({ sizeof(short), "short" }); + show_node(*mmap.cbegin()); + + mmap.insert({ sizeof(char), "char" }); + show_node(*mmap.cbegin()); + + mmap.insert({{ sizeof(float), "float" }, { sizeof(double), "double"}}); + + std::cout << "mmap = { "; + std::for_each(mmap.cbegin(), mmap.cend(), [&](const auto& n) { show_node(n, ' '); }); + std::cout << "};\\n"; + } + +.SH Possible output: + + { 8, LONG } + { 8, long } + { 4, int } + { 2, short } + { 1, char } + mmap = { { 1, char } { 2, short } { 4, int } { 4, float } { 8, long } { 8, double } }; + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multimap::begin,std::multimap::cbegin.3 b/man/std::multimap::begin,std::multimap::cbegin.3 deleted file mode 100644 index 996fa27f0..000000000 --- a/man/std::multimap::begin,std::multimap::cbegin.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::multimap::begin,std::multimap::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP - - Returns an iterator to the first element of the container. - - If the container is empty, the returned iterator will be equal to end(). - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP diff --git a/man/std::multimap::clear.3 b/man/std::multimap::clear.3 index 80cfc3967..2b1949ac5 100644 --- a/man/std::multimap::clear.3 +++ b/man/std::multimap::clear.3 @@ -1,11 +1,14 @@ -.TH std::multimap::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::clear \- std::multimap::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterator remains valid. .SH Parameters @@ -15,18 +18,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::multimap& v) + { + std::cout << rem << "{ "; + for (const auto& [key, value] : v) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::multimap container{{1, 'x'}, {2, 'y'}, {3, 'z'}}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { [1]:x [2]:y [3]:z } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + LWG 224 C++98 the complexity was log(size()) + N, but N corrected to 'linear in + was not defined size()' .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::contains.3 b/man/std::multimap::contains.3 new file mode 100644 index 000000000..7165378ed --- /dev/null +++ b/man/std::multimap::contains.3 @@ -0,0 +1,60 @@ +.TH std::multimap::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::contains \- std::multimap::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::multimap example{{1, 'a'}, {2, 'b'}}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::multimap::count.3 b/man/std::multimap::count.3 index 5154db084..2b2048e3c 100644 --- a/man/std::multimap::count.3 +++ b/man/std::multimap::count.3 @@ -1,14 +1,20 @@ -.TH std::multimap::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::count \- std::multimap::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP template< class K > \fB(2)\fP \fI(since C++14)\fP size_type count( const K& x ) const; + Returns the number of elements with key that compares equivalent to the specified + argument. + 1) Returns the number of elements with key key. 2) Returns the number of elements with key that compares equivalent to the value x. - These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -17,16 +23,31 @@ .SH Return value - Number of elements with key key. + Number of elements with key that compares equivalent to key or x. .SH Complexity - Logarithmic in the size of the container plus linear in the number of the elements + Logarithmic in the size of the container plus linear in the number of elements found. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overload \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example + .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multimap::emplace.3 b/man/std::multimap::emplace.3 index ea3a9b9e2..020009905 100644 --- a/man/std::multimap::emplace.3 +++ b/man/std::multimap::emplace.3 @@ -1,15 +1,19 @@ -.TH std::multimap::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::emplace \- std::multimap::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace( Args&&... args ); - Inserts a new element into the container by constructing it in-place with the given - args. + Inserts a new element into the container constructed in-place with the given args. + + The constructor of the new element (i.e. std::pair) is called with + exactly the same arguments as supplied to emplace, forwarded via + std::forward(args).... Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element (i.e. - std::pair) is called with exactly the same arguments as supplied to - emplace, forwarded via std::forward(args).... + unnecessary copy or move operations. No iterators or references are invalidated. @@ -19,11 +23,12 @@ .SH Return value - Returns an iterator to the inserted element. + An iterator to the inserted element. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -31,34 +36,37 @@ .SH Example - + // Run this code #include + #include #include - #include + int main() { std::multimap m; - - // uses pair's move constructor (overload 8) + + // uses pair's move constructor m.emplace(std::make_pair(std::string("a"), std::string("a"))); - - // uses pair's converting move constructor (overload 5) + + // uses pair's converting move constructor m.emplace(std::make_pair("b", "abcd")); - - // uses pair's template constructor (overload 3) + + // uses pair's template constructor m.emplace("d", "ddd"); - - // uses pair's piecewise constructor (overload 6) + + // emplace with duplicate key + m.emplace("d", "DDD"); + + // uses pair's piecewise constructor m.emplace(std::piecewise_construct, std::forward_as_tuple("c"), std::forward_as_tuple(10, 'c')); - - for (const auto &p : m) { + + for (const auto& p : m) std::cout << p.first << " => " << p.second << '\\n'; - } } .SH Output: @@ -67,10 +75,16 @@ b => abcd c => cccccccccc d => ddd + d => DDD .SH See also emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if the key + try_emplace exists + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::emplace_hint.3 b/man/std::multimap::emplace_hint.3 index 0c3ed45cb..4b84c6617 100644 --- a/man/std::multimap::emplace_hint.3 +++ b/man/std::multimap::emplace_hint.3 @@ -1,11 +1,13 @@ -.TH std::multimap::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::emplace_hint \- std::multimap::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container as close as possible to the position just + before hint. The constructor of the element type (value_type, that is, std::pair) is called with exactly the same arguments as supplied to the function, forwarded @@ -15,21 +17,36 @@ .SH Parameters - hint - iterator, used as a suggestion as to where to insert the new element + hint - iterator to the position before which the new element will be inserted args - arguments to forward to the constructor of the element .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Logarithmic in the size of the container in general, but amortized constant if the new element is inserted just before hint. +.SH Example + + This section is incomplete + Reason: no example + .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multimap::empty.3 b/man/std::multimap::empty.3 index d5de96624..8d804948d 100644 --- a/man/std::multimap::empty.3 +++ b/man/std::multimap::empty.3 @@ -1,6 +1,12 @@ -.TH std::multimap::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::empty \- std::multimap::empty + .SH Synopsis - bool empty() const; + bool empty() const; \fI(until C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +16,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,23 +24,24 @@ .SH Example - + The following code uses empty to check if a std::multimap contains any elements: - + // Run this code - #include #include + #include #include - + int main() { - std::multimap numbers; + std::multimap numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.emplace(42, 13); numbers.insert(std::make_pair(13317, 123)); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -49,10 +49,12 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::multimap::end,std::multimap::cend.3 b/man/std::multimap::end,std::multimap::cend.3 index 8ce7e2d00..2c840f5c9 100644 --- a/man/std::multimap::end,std::multimap::cend.3 +++ b/man/std::multimap::end,std::multimap::cend.3 @@ -1,10 +1,13 @@ -.TH std::multimap::end,std::multimap::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::end,std::multimap::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::end,std::multimap::cend \- std::multimap::end,std::multimap::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fB(1)\fP (noexcept since C++11) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the multimap. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +22,75 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto show_node = [](const auto& node, char ending = '\\n') + { + std::cout << "{ " << node.first << ", " << node.second << " }" << ending; + }; + + std::multimap mmap; + assert(mmap.begin() == mmap.end()); // OK + assert(mmap.cbegin() == mmap.cend()); // OK + + mmap.insert({ sizeof(long), "LONG" }); + show_node(*(mmap.cbegin())); + assert(mmap.begin() != mmap.end()); // OK + assert(mmap.cbegin() != mmap.cend()); // OK + mmap.begin()->second = "long"; + show_node(*(mmap.cbegin())); + + mmap.insert({ sizeof(int), "int" }); + show_node(*mmap.cbegin()); + + mmap.insert({ sizeof(short), "short" }); + show_node(*mmap.cbegin()); + + mmap.insert({ sizeof(char), "char" }); + show_node(*mmap.cbegin()); + + mmap.insert({{ sizeof(float), "float" }, { sizeof(double), "double"}}); + + std::cout << "mmap = { "; + std::for_each(mmap.cbegin(), mmap.cend(), [&](const auto& n) { show_node(n, ' '); }); + std::cout << "};\\n"; + } + +.SH Possible output: + + { 8, LONG } + { 8, long } + { 4, int } + { 2, short } + { 1, char } + mmap = { { 1, char } { 2, short } { 4, int } { 4, float } { 8, long } { 8, double } }; + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multimap::equal_range.3 b/man/std::multimap::equal_range.3 index 489723392..a72fd9144 100644 --- a/man/std::multimap::equal_range.3 +++ b/man/std::multimap::equal_range.3 @@ -1,27 +1,27 @@ -.TH std::multimap::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::equal_range \- std::multimap::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fB(1)\fP - std::pair equal_range( const Key& \fB(2)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP + std::pair equal_range( const Key& \fB(2)\fP key ) const; template< class K > \fB(3)\fP \fI(since C++14)\fP - std::pair equal_range( const K& x ); + std::pair equal_range( const K& x ); template< class K > - std::pair equal_range( const K& x ) \fB(4)\fP \fI(since C++14)\fP - const; + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++14)\fP + ) const; Returns a range containing all elements with the given key in the container. The range is defined by two iterators, one pointing to the first element that is not - less than key and another pointing to the first element greater than key. The first - iterator may be alternatively obtained with lower_bound(), the second - with - upper_bound(). - - 1-2) Compares the keys to key. - 3,4) Compares the keys to the value x. These templates only participate in overload - resolution if the type Compare::is_transparent exists. They allow calling this - function without constructing an instance of Key. + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). - This section is incomplete - Reason: explain better + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. .SH Parameters @@ -38,28 +38,65 @@ returned as the first element. Similarly if there are no elements greater than key, past-the-end iterator is returned as the second element. - Since insert always inserts at the upper bound, the order of \fI(since C++11)\fP - equivalent elements is the equal range is the order of insertion. + Since emplace and unhinted insert always insert at the upper bound, + the order of equivalent elements in the equal range is the order of \fI(since C++11)\fP + insertion unless hinted insert or emplace_hint was used to insert an + element at a different position. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - find finds element with specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP + #include + #include + + int main() + { + std::multimap dict + { + {1, 'A'}, + {2, 'B'}, + {2, 'C'}, + {2, 'D'}, + {4, 'E'}, + {3, 'F'} + }; - Categories: + auto range = dict.equal_range(2); - * Todo with reason - * Todo no example + for (auto i = range.first; i != range.second; ++i) + std::cout << i->first << ": " << i->second << '\\n'; + } + +.SH Output: + + 2: B + 2: C + 2: D + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::multimap::erase.3 b/man/std::multimap::erase.3 index 804c65d69..5ba002c97 100644 --- a/man/std::multimap::erase.3 +++ b/man/std::multimap::erase.3 @@ -1,49 +1,125 @@ -.TH std::multimap::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::erase \- std::multimap::erase + .SH Synopsis - void erase( iterator pos ); \fI(until C++11)\fP - iterator erase( const_iterator pos ); \fI(since C++11)\fP - void erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP - iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP - const_iterator last ); - size_type erase( const key_type& key ); \fB(3)\fP + iterator erase( iterator pos ); \fB(1)\fP + iterator erase( const_iterator pos ); \fB(2)\fP \fI(since C++11)\fP + iterator erase( iterator first, iterator last ); \fI(until C++11)\fP + iterator erase( const_iterator first, const_iterator \fI(since C++11)\fP + last ); \fB(3)\fP + size_type erase( const Key& key ); \fB(4)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); - Removes specified elements from the container. + Removes specified elements from the container. The order of the remaining equivalent + elements is preserved. - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes all elements with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed. + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. .SH Complexity Given an instance c of multimap: - 1) Amortized constant - 2) log(c.size()) + std::distance(first, last) - 3) log(c.size()) + c.count(k) + 1,2) Amortized constant + 3) log(c.size()) + std::distance(first, last) + 4) log(c.size()) + c.count(key) + 5) log(c.size()) + c.count(x) + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::multimap c = + { + {1, "one"}, {2, "two"}, {3, "three"}, + {4, "four"}, {5, "five"}, {6, "six"} + }; + + // erase all odd numbers from c + for (auto it = c.begin(); it != c.end();) + { + if (it->first % 2 != 0) + it = c.erase(it); + else + ++it; + } + + for (auto& p : c) + std::cout << p.second << ' '; + std::cout << '\\n'; + } + +.SH Output: + + two four six + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the return type of overloads \fB(1)\fP and \fB(3)\fP + LWG 130 C++98 was void (it is not corrected to iterator + consistent with the erase() requirement + on sequence containers) + the order of equivalent elements that + LWG 371 C++98 are not required to be + erased was not guaranteed to be preserved + preserved + LWG 2059 C++11 replacing overload \fB(1)\fP with overload \fB(2)\fP added overload (1) back + introduced new ambiguity .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::extract.3 b/man/std::multimap::extract.3 new file mode 100644 index 000000000..bb0369c1f --- /dev/null +++ b/man/std::multimap::extract.3 @@ -0,0 +1,120 @@ +.TH std::multimap::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::extract \- std::multimap::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains the first such element from the container and returns a node handle that + owns it. Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if the + qualified-id Compare::is_transparent is valid and denotes a type, and neither + iterator nor const_iterator is implicitly convertible from K. It allows calling this + function without constructing an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed (rebalancing may occur, as with erase()). + + Extracting a node invalidates only the iterators to the extracted element. Pointers + and references to the extracted element remain valid, but cannot be used while + element is owned by a node handle: they become usable if the element is inserted + into a container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Compare object. + +.SH Complexity + + 1) Amortized constant. + 2,3) log(size()) + +.SH Notes + + extract is the only way to change a key of a map element without reallocation: + + std::map m{{1, "mango"}, {2, "papaya"}, {3, "guava"}}; + auto nh = m.extract\fB(2)\fP; + nh.key() = 4; + m.insert(std::move(nh)); + // m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}} + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto [k, v] : data) + std::cout << ' ' << k << '(' << v << ')'; + + std::cout << '\\n'; + } + + int main() + { + std::multimap cont{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.key() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Output: + + Start: 1(a) 2(b) 3(c) + After extract and before insert: 2(b) 3(c) + End: 2(b) 3(c) 4(a) + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::multimap::find.3 b/man/std::multimap::find.3 index c5821ee0e..bbe016065 100644 --- a/man/std::multimap::find.3 +++ b/man/std::multimap::find.3 @@ -1,16 +1,21 @@ -.TH std::multimap::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::find \- std::multimap::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP - template< class K > iterator find( const K& x ); \fB(3)\fP \fI(since C++14)\fP - template< class K > const_iterator find( const K& x ) const; \fB(4)\fP \fI(since C++14)\fP + iterator find( const Key& key ); \fB(1)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator find( const K& x ) const; 1,2) Finds an element with key equivalent to key. If there are several elements with - key in the container, any of them may be returned. - 3,4) Finds an element with key that compares equivalent to the value x. These - templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key + the requested key in the container, any of them may be returned. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -19,43 +24,88 @@ .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + .SH Example - + // Run this code #include #include - #include - + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + int main() { - std::multimap map_ex; - map_ex.insert({{1,'a'},{2,'b'}}); - std::multimap::const_iterator search = map_ex.find(1); - if(search != map_ex.end()) { - std::cout << "Found " << search->first << " " << search->second << "\\n"; - } - else { - std::cout << "Not found" << std::endl; + // Simple comparison demo. + std::multimap example{{1,'a'}, {2,'b'}}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << search->first << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::multimap> example2{{{1, {}}, 'a'}, {{2, {}}, 'b'}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // Obtaining const iterators. + // Compiler decides whether to return iterator of (non) const type by way of + // accessing map; to prevent intentional modification, one of the simplest + // options is to access the map via a constant reference. + const auto& example2ref = example2; + if (auto search = example2ref.find(lk); search != example2.end()) + { + std::cout << "Found " << search->first.x << ' ' << search->second << '\\n'; + // search->second = 'c'; // error: assignment of member + // 'std::pair::second' + // in read-only object } - return 0; } .SH Output: - Found 1 a + Found 2 b + Found 2 b + Found 2 b .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::get_allocator.3 b/man/std::multimap::get_allocator.3 index 34e45ccf7..6b46c53e0 100644 --- a/man/std::multimap::get_allocator.3 +++ b/man/std::multimap::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::multimap::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::get_allocator \- std::multimap::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) Returns the allocator associated with the container. diff --git a/man/std::multimap::insert.3 b/man/std::multimap::insert.3 index 84ade155b..813b390f4 100644 --- a/man/std::multimap::insert.3 +++ b/man/std::multimap::insert.3 @@ -1,74 +1,175 @@ -.TH std::multimap::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::insert \- std::multimap::insert + .SH Synopsis iterator insert( const value_type& value ); \fB(1)\fP - template< class P > \fB(2)\fP \fI(since C++11)\fP + iterator insert( value_type&& value ); \fB(2)\fP \fI(since C++17)\fP + template< class P > \fB(3)\fP \fI(since C++11)\fP iterator insert( P&& value ); - iterator insert( iterator hint, const value_type& \fI(until C++11)\fP + iterator insert( iterator pos, const value_type& \fI(until C++11)\fP value ); - iterator insert( const_iterator hint, const \fI(since C++11)\fP + iterator insert( const_iterator pos, const \fI(since C++11)\fP value_type& value ); - template< class P > \fB(3)\fP \fB(4)\fP \fI(since C++11)\fP - iterator insert( const_iterator hint, P&& value ); - template< class InputIt > \fB(5)\fP + iterator insert( const_iterator pos, value_type&& \fB(5)\fP \fI(since C++17)\fP + value ); + template< class P > \fB(6)\fP \fI(since C++11)\fP + iterator insert( const_iterator pos, P&& value ); \fB(4)\fP + template< class InputIt > \fB(7)\fP void insert( InputIt first, InputIt last ); - void insert( std::initializer_list ilist \fB(6)\fP \fI(since C++11)\fP + void insert( std::initializer_list ilist \fB(8)\fP \fI(since C++11)\fP + ); + iterator insert( node_type&& nh ); \fB(9)\fP \fI(since C++17)\fP + iterator insert( const_iterator pos, node_type&& nh \fB(10)\fP \fI(since C++17)\fP ); Inserts element(s) into the container. - 1-2) inserts value. If the container has elements with equivalent key, inserts at - the upper bound of that range.\fI(since C++11)\fP The overload \fB(2)\fP is equivalent to - emplace(std::forward

(value)) and only participates in overload resolution if - std::is_constructible::value == true. - 3-4) inserts value in the position as close as possible, just prior\fI(since C++11)\fP, to - hint. The overload \fB(4)\fP is equivalent to emplace_hint(hint, std::forward

(value)) - and only participates in overload resolution if std::is_constructible::value == true. - 5) inserts elements from range [first, last). - 6) inserts elements from initializer list ilist. + 1-3) Inserts value. If the container has elements with equivalent key, inserts at + the upper bound of that range. + Overload \fB(3)\fP is equivalent to emplace(std::forward

(value)) and only participates + in overload resolution if std::is_constructible::value == true. + 4-6) Inserts value in the position as close as possible to the position just prior + to pos. + Overload \fB(6)\fP is equivalent to emplace_hint(hint, std::forward

(u)) to first and + std::get<1>(std::forward

(u)) to second. + This overload participates in overload resolution only if + * std::same_as, std::pair> is false, + * std::remove_cvref_t

is not a specialization of std::ranges::subrange, + * std::is_assignable_v(std::forward

(p)))> is true, + and + * std::is_assignable_v(std::forward

(p)))> is true. + 10) Assigns std::get<0>(std::forward

(u)) to first and + std::get<1>(std::forward

(u)) to second. + This overload participates in overload resolution only if + * std::same_as, std::pair> is false, + * std::remove_cvref_t

is not a specialization of std::ranges::subrange, + * std::is_assignable_v(std::forward

(p)))> is + true, and + * std::is_assignable_v(std::forward

(p)))> is + true. .SH Parameters other - pair of values to replace the contents of this pair + p - pair of values of possibly different types to replace the contents of this + pair + u - pair-like object of values to replace the contents of this pair +.SH Type requirements + - + T1 must meet the requirements of CopyAssignable from U1. \fI(until C++11)\fP + - + T2 must meet the requirements of CopyAssignable from U2. \fI(until C++11)\fP .SH Return value @@ -27,28 +120,93 @@ .SH Exceptions - 1-2) \fI(none)\fP - 3) - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: \fI(since C++11)\fP + 1-4) May throw implementation-defined exceptions. + 5) + noexcept specification: noexcept( - is_nothrow_move_assignable::value && \fI(since C++11)\fP - is_nothrow_move_assignable::value + std::is_nothrow_move_assignable::value && + std::is_nothrow_move_assignable::value ) - - 4) \fI(none)\fP + 6-10) May throw implementation-defined exceptions. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + template + Os& operator<<(Os& os, const std::vector& v) + { + os << '{'; + for (std::size_t t = 0; t != v.size(); ++t) + os << v[t] << (t + 1 < v.size() ? ", " : ""); + return os << '}'; + } + + template + Os& operator<<(Os& os, const std::pair& pair) + { + return os << '{' << pair.first << ", " << pair.second << '}'; + } + + int main() + { + std::pair> p{1, {2}}, q{2, {5, 6}}; + + p = q; // (1) operator=(const pair& other); + std::cout << std::setw(23) << std::left + << "(1) p = q;" + << "p: " << p << " q: " << q << '\\n'; + + std::pair> r{4, {7, 8, 9}}; + p = r; // (3) operator=(const pair& other); + std::cout << std::setw(23) + << "(3) p = r;" + << "p: " << p << " r: " << r << '\\n'; + + p = std::pair>{3, {4}}; + p = std::move(q); // (5) operator=(pair&& other); + std::cout << std::setw(23) + << "(5) p = std::move(q);" + << "p: " << p << " q: " << q << '\\n'; + + p = std::pair>{5, {6}}; + p = std::move(r); // (7) operator=(pair&& other); + std::cout << std::setw(23) + << "(7) p = std::move(r);" + << "p: " << p << " r: " << r << '\\n'; + } + +.SH Output: + + \fB(1)\fP p = q; p: {2, {5, 6}} q: {2, {5, 6}} + \fB(3)\fP p = r; p: {4, {7, 8, 9}} r: {4, {7, 8, 9}} + \fB(5)\fP p = std::move(q); p: {2, {5, 6}} q: {2, {}} + \fB(7)\fP p = std::move(r); p: {4, {7, 8, 9}} r: {4, {}} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 885 C++98 missing heterogeneous copy assignment added (as overload \fB(3)\fP) + pair::operator= was unconstrained and + LWG 2729 C++11 might constrained + result in unnecessary undefined behavior .SH See also + operator= assigns the contents of one tuple to another + \fI(public member function of std::tuple)\fP .SH Category: - - * Todo no example + * conditionally noexcept diff --git a/man/std::pair::pair.3 b/man/std::pair::pair.3 index b98cfe6e3..ec055f412 100644 --- a/man/std::pair::pair.3 +++ b/man/std::pair::pair.3 @@ -1,52 +1,183 @@ -.TH std::pair::pair 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pair::pair 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pair::pair \- std::pair::pair + .SH Synopsis - pair(); \fI(until C++11)\fP - constexpr pair(); \fI(since C++11)\fP - pair( const T1& x, const T2& y ); \fB(2)\fP \fI(until C++14)\fP - constexpr pair( const T1& x, const T2& y ); \fB(2)\fP \fI(since C++14)\fP - template< class U1, class U2 > \fB(3)\fP \fI(since C++11)\fP - pair( U1&& x, U2&& y ); \fI(until C++14)\fP - template< class U1, class U2 > \fB(3)\fP \fI(since C++14)\fP - constexpr pair( U1&& x, U2&& y ); - template< class U1, class U2 > \fB(4)\fP \fI(until C++14)\fP - pair( const pair& p ); - template< class U1, class U2 > \fB(4)\fP \fI(since C++14)\fP - constexpr pair( const pair& p ); \fB(1)\fP - template< class U1, class U2 > \fB(5)\fP \fI(since C++11)\fP - pair( pair&& p ); \fI(until C++14)\fP - template< class U1, class U2 > \fB(5)\fP \fI(since C++14)\fP - constexpr pair( pair&& p ); - template< class... Args1, class... Args2 > - - pair( std::piecewise_construct_t, \fB(6)\fP \fI(since C++11)\fP - std::tuple first_args, - - std::tuple second_args ); - pair( const pair& p ) = default; \fB(7)\fP - pair( pair&& p ) = default; \fB(8)\fP \fI(since C++11)\fP +pair(); \fI(until C++11)\fP + \fI(since C++11)\fP +constexpr pair(); (conditionally + explicit) +pair( const T1& x, const \fI(until C++11)\fP +T2& y ); + \fI(since C++11)\fP +pair( const T1& x, const \fI(until C++14)\fP +T2& y ); (conditionally + explicit) +constexpr pair( const T1& \fI(since C++14)\fP +x, const T2& y ); (conditionally + explicit) +template< class U1, class \fI(since C++11)\fP +U2 > \fI(until C++14)\fP +pair( U1&& x, U2&& y ); (conditionally + explicit) +template< class U1, class \fI(since C++14)\fP +U2 > (until C++23) +constexpr pair( U1&& x, (conditionally +U2&& y ); explicit) +template< class U1 = T1, (since C++23) +class U2 = T2 > (conditionally +constexpr pair( U1&& x, explicit) +U2&& y ); +template< class U1, class (since C++23) +U2 > \fB(4)\fP (conditionally +constexpr pair( pair& p ); +template< class U1, class +U2 > \fI(until C++11)\fP +pair( const pair& p +); +template< class U1, class \fI(since C++11)\fP +U2 > \fI(until C++14)\fP +pair( const pair& p (conditionally +); explicit) +template< class U1, class \fI(since C++14)\fP +U2 > (conditionally +constexpr pair( const explicit) +pair& p ); \fB(1)\fP +template< class U1, class \fI(since C++11)\fP +U2 > \fB(2)\fP \fI(until C++14)\fP +pair( pair&& p ); (conditionally + explicit) +template< class U1, class \fI(since C++14)\fP +U2 > (conditionally +constexpr pair( pair&& p ); +template< class U1, class (since C++23) +U2 > \fB(7)\fP (conditionally +constexpr pair( const explicit) +pair&& p ); +template< pair-like P > (since C++23) +constexpr pair ( P&& u ); \fB(8)\fP (conditionally + \fB(5)\fP explicit) +template< class... Args1, +class... Args2 > + +pair( (since +std::piecewise_construct_t, C++11) + std::tuple \fB(6)\fP (until +first_args, C++20) + + std::tuple +second_args ); +template< class... Args1, +class... Args2 > + \fB(9)\fP +constexpr pair( +std::piecewise_construct_t, + (since +std::tuple C++20) +first_args, + + +std::tuple +second_args ); +pair( const pair& p ) = \fB(10)\fP +default; +pair( pair&& p ) = default; \fB(11)\fP (since + C++11) Constructs a new pair. 1) Default constructor. Value-initializes both elements of the pair, first and second. + This constructor participates in overload resolution if and only if + std::is_default_constructible_v and + std::is_default_constructible_v are both true. \fI(since C++11)\fP + + This constructor is explicit if and only if either T1 or T2 is not + implicitly default-constructible. + 2) Initializes first with x and second with y. + This constructor participates in overload resolution if and only if + std::is_copy_constructible_v and std::is_copy_constructible_v + are both true. + \fI(since C++11)\fP + This constructor is explicit if and only if + std::is_convertible_v is false or + std::is_convertible_v is false. + 3) Initializes first with std::forward(x) and second with std::forward(y). + This constructor participates in overload resolution if and only if + std::is_constructible_v and std::is_constructible_v are both true. + This constructor is explicit if and only if std::is_convertible_v is false + or std::is_convertible_v is false. + + This constructor is defined as deleted if the initialization of first (since C++23) + or second would bind a reference to temporary object. 4) Initializes first with p.first and second with p.second. + This constructor participates in overload resolution if and only if + std::is_constructible_v and std::is_constructible_v are both true. + This constructor is explicit if and only if std::is_convertible_v is false + or std::is_convertible_v is false. + This constructor is defined as deleted if the initialization of first or second + would bind a reference to temporary object. + 5) Initializes first with p.first and second with p.second. - 5) Initializes first with std::move(p.first) and second with - std::move(p.second). + This constructor participates in overload resolution if and only if + std::is_constructible_v and std::is_constructible_v are both true. + \fI(since C++11)\fP + This constructor is explicit if and only if + std::is_convertible_v is false or + std::is_convertible_v is false. - 6) Forwards the elements of first_args to the constructor of first and forwards the - elements of second_args to the constructor of second. This is the only non-default - constructor that can be used to create a pair of non-copyable non-movable types. + This constructor is defined as deleted if the initialization of first (since C++23) + or second would bind a reference to temporary object. - 7) Copy constructor is defaulted, and is constexpr if copying of both elements - satisfies the requirements on constexpr functions. + 6) Initializes first with std::forward(p.first) and second with + std::forward(p.second). + This constructor participates in overload resolution if and only if + std::is_constructible_v and std::is_constructible_v are both true. + This constructor is explicit if and only if std::is_convertible_v is false + or std::is_convertible_v is false. + + This constructor is defined as deleted if the initialization of first (since C++23) + or second would bind a reference to temporary object. - 8) Move constructor is defaulted, and is constexpr if moving of both elements + 7) Initializes first with std::forward(p.first) and second with + std::forward(p.second). + This constructor participates in overload resolution if and only if + std::is_constructible_v and std::is_constructible_v are both true. + This constructor is explicit if and only if std::is_convertible_v is + false or std::is_convertible_v is false. + This constructor is defined as deleted if the initialization of first or second + would bind a reference to temporary object. + 8) Given u1 as std::get<0>(std::forward(u)) and u2 as std::get<1>(std::forward(u)), + denote their types as U1 and U2 respectively. Initializes first with u1 and second + with u2. + This constructor participates in overload resolution if and only if + * std::remove_cvref(P) is not a specialization of std::ranges::subrange, + * std::is_constructible_v is true, and + * std::is_constructible_v is false + or std::is_convertible_v is false. + This constructor is defined as deleted if the initialization of first or second + would bind a reference to temporary object. + 9) Forwards the elements of first_args to the constructor of first and forwards the + elements of second_args to the constructor of second. This is the only non-default + constructor that can be used to create a pair of non-copyable non-movable types. The + program is ill-formed if first or second is a reference and bound to a temporary + object. + 10) Copy constructor is + implicitly declared + \fI(until C++11)\fP + defaulted, and is constexpr if copying of both elements satisfies the requirements + on constexpr functions + \fI(since C++11)\fP. + 11) Move constructor is defaulted, and is constexpr if moving of both elements satisfies the requirements on constexpr functions. .SH Parameters @@ -54,6 +185,8 @@ x - value to initialize the first element of this pair y - value to initialize the second element of this pair p - pair of values used to initialize both elements of this pair + u - pair-like object of values used to initialize both elements of this + pair first_args - tuple of constructor arguments to initialize the first element of this pair second_args - tuple of constructor arguments to initialize the second element of @@ -66,45 +199,64 @@ .SH Example - + // Run this code - #include - #include #include - #include #include - + #include + #include + #include + int main() { + auto print = [](auto rem, auto const& pair) + { + std::cout << rem << "(" << pair.first << ", " << pair.second << ")\\n"; + }; + std::pair p1; - std::cout << "Value-initialized: " - << p1.first << ", " << p1.second << '\\n'; - - std::pair p2(42, 0.123); - std::cout << "Initialized with two values: " - << p2.first << ", " << p2.second << '\\n'; - - std::pair p4(p2); - std::cout << "Implicitly converted: " - << p4.first << ", " << p4.second << '\\n'; - - std::pair, std::string> p6( - std::piecewise_construct, - std::forward_as_tuple(0.123, 7.7), - std::forward_as_tuple(10, 'a')); - std::cout << "Piecewise constructed: " - << p6.first << ", " << p6.second << '\\n'; + print("(1) Value-initialized: ", p1); + + std::pair p2{42, 3.1415}; + print("(2) Initialized with two values: ", p2); + + std::pair p4{p2}; + print("(4) Implicitly converted: ", p4); + + std::pair, std::string> p6 + {std::piecewise_construct, std::forward_as_tuple(0.123, 7.7), + std::forward_as_tuple(10, 'a')}; + print("(8) Piecewise constructed: ", p6); } -.SH Output: +.SH Possible output: + + \fB(1)\fP Value-initialized: (0, 0) + \fB(2)\fP Initialized with two values: (42, 3.1415) + \fB(4)\fP Implicitly converted: (*, 3) + \fB(8)\fP Piecewise constructed: ((0.123,7.7), aaaaaaaaaa) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Value-initialized: 0, 0 - Initialized with two values: 42, 0.123 - Implicitly converted: *, 0 - Piecewise constructed: (0.123,7.7), aaaaaaaaaa + DR Applied to Behavior as published Correct behavior + the default constructor + copy-initialized first + LWG 265 C++98 and second with T1() and T2() first and second + respectively are value-initialized + (thus required T1 and T2 to be + CopyConstructible) + LWG 2510 C++11 the default constructor was made conditionally-explicit + implicit + N4387 C++11 some constructors were constructors made + implicit-only, preventing some uses conditionally-explicit .SH See also - make_pair creates a pair object of type, defined by the argument types - \fI(function template)\fP + make_pair creates a pair object of type, defined by the argument types + \fI(function template)\fP + constructor constructs a new tuple + \fI(public member function of std::tuple)\fP diff --git a/man/std::pair::swap.3 b/man/std::pair::swap.3 index 01c1799d2..05db6dddd 100644 --- a/man/std::pair::swap.3 +++ b/man/std::pair::swap.3 @@ -1,8 +1,26 @@ -.TH std::pair::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pair::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pair::swap \- std::pair::swap + .SH Synopsis - void swap(pair& other); \fI(since C++11)\fP + void swap( pair& other ) noexcept(/* see below */); \fI(since C++11)\fP + \fI(until C++20)\fP + constexpr void swap( pair& other ) noexcept(/* see below */); \fB(1)\fP \fI(since C++20)\fP + constexpr void swap( const pair& other ) const noexcept(/* see \fB(2)\fP (since C++23) + below */); + + Swaps first with other.first and second with other.second, as if by using std::swap; + swap(first, other.first); swap(second, other.second);. + + If either selected swap function call is ill-formed or does not swap (until C++23) + the value of the member, the behavior is undefined. + 1) The program is ill-formed if either std::is_swappable_v or + std::is_swappable_v is not true. + 2) The program is ill-formed if either std::is_swappable_v + or std::is_swappable_v is not true. (since C++23) - Swaps first with other.first and second with other.second. + If either selected swap function call does not swap the value of the + member, the behavior is undefined. .SH Parameters @@ -14,18 +32,36 @@ .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: \fI(since C++11)\fP + noexcept specification: noexcept( - noexcept(std::swap(first, p.first)) && \fI(since C++11)\fP - noexcept(std::swap(second, p.second)) + noexcept(swap(first, other.first)) && + noexcept(swap(second, other.second)) \fI(until C++17)\fP + + ) + + In the expression above, the identifier swap is looked up in the same + manner as the one used by the C++17 std::is_nothrow_swappable trait. + 1) + noexcept specification: + noexcept( + + std::is_nothrow_swappable_v && + std::is_nothrow_swappable_v + + ) \fI(since C++17)\fP + 2) + noexcept specification: + noexcept( + + std::is_nothrow_swappable_v && + std::is_nothrow_swappable_v ) .SH Example - + // Run this code #include @@ -33,14 +69,40 @@ #include int main() { - std::pair p1, p2; - p1 = std::make_pair(10, "test"); + std::pair p1(10, "test"), p2; p2.swap(p1); std::cout << "(" << p2.first << ", " << p2.second << ")\\n"; + + #if __cpp_lib_ranges_zip >= 202110L + // Using the C++23 const qualified swap overload + // (swap is no longer propagating pair constness) + int i1 = 10, i2{}; + std::string s1("test"), s2; + const std::pair r1(i1, s1), r2(i2, s2); + r2.swap(r1); + std::cout << "(" << i2 << ", " << s2 << ")\\n"; + #endif } -.SH Output: +.SH Possible output: (10, test) + (10, test) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2456 C++11 the noexcept specification is ill-formed made to work .SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap swaps the contents of two tuples + \fI(public member function of std::tuple)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::partial_order.3 b/man/std::partial_order.3 new file mode 100644 index 000000000..9acbc4072 --- /dev/null +++ b/man/std::partial_order.3 @@ -0,0 +1,86 @@ +.TH std::partial_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partial_order \- std::partial_order + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ partial_order = /* unspecified \fI(since C++20)\fP + */; + + } + Call signature + template< class T, class U > + + requires /* see below */ + constexpr std::partial_ordering + + partial_order( T&& t, U&& u ) noexcept(/* see below */); + + Compares two values using 3-way comparison and produces a result of type + std::partial_ordering. + + Let t and u be expressions and T and U denote decltype((t)) and decltype((u)) + respectively, std::partial_order(t, u) is expression-equivalent to: + + * If std::is_same_v, std::decay_t> is true: + * std::partial_ordering(partial_order(t, u)), if it is a well-formed + expression with overload resolution performed in a context that does not + include a declaration of std::partial_order, + * otherwise, std::partial_ordering(std::compare_three_way()(t, u)), if it is + well-formed, + * otherwise, std::partial_ordering(std::weak_order(t, u)), if it is + well-formed. + * In all other cases, the expression is ill-formed, which can result in + substitution failure when it appears in the immediate context of a template + instantiation. + + Customization point objects + + The name std::partial_order denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __partial_order_fn. + + All instances of __partial_order_fn are equal. The effects of invoking different + instances of type __partial_order_fn on the same arguments are equivalent, + regardless of whether the expression denoting the instance is an lvalue or rvalue, + and is const-qualified or not (however, a volatile-qualified instance is not + required to be invocable). Thus, std::partial_order can be copied freely and its + copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to std::partial_order above, __partial_order_fn models + + * std::invocable<__partial_order_fn, Args...>, + * std::invocable, + * std::invocable<__partial_order_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __partial_order_fn participates in overload + resolution. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + the result type of 3-way comparison that supports all + partial_ordering 6 operators, is not substitutable, and allows + (C++20) incomparable values + \fI(class)\fP + strong_order performs 3-way comparison and produces a result of + (C++20) type std::strong_ordering + (customization point object) + weak_order performs 3-way comparison and produces a result of + (C++20) type std::weak_ordering + (customization point object) + performs 3-way comparison and produces a result of + compare_partial_order_fallback type std::partial_ordering, even if operator<=> is + (C++20) unavailable + (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::partial_ordering.3 b/man/std::partial_ordering.3 new file mode 100644 index 000000000..0b79c43cb --- /dev/null +++ b/man/std::partial_ordering.3 @@ -0,0 +1,189 @@ +.TH std::partial_ordering 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partial_ordering \- std::partial_ordering + +.SH Synopsis + Defined in header + class partial_ordering; \fI(since C++20)\fP + + The class type std::partial_ordering is the result type of a three-way comparison + that: + + * Admits all six relational operators (==, !=, <, <=, >, >=). + * Does not imply substitutability: if a is equivalent to b, f(a) may not be + equivalent to f(b), where f denotes a function that reads only + comparison-salient state that is accessible via the argument's public const + members. In other words, equivalent values may be distinguishable. + * Admits incomparable values: a < b, a == b, and a > b may all be false. + +.SH Constants + + The type std::partial_ordering has four valid values, implemented as const static + data members of its type: + + Member constant Definition + less(inline constexpr) a valid value of the type std::partial_ordering + \fB[static]\fP indicating less-than (ordered before) relationship + \fI(public static member constant)\fP + a valid value of the type std::partial_ordering + equivalent(inline constexpr) indicating equivalence (neither ordered before nor + \fB[static]\fP ordered after) + \fI(public static member constant)\fP + greater(inline constexpr) a valid value of the type std::partial_ordering + \fB[static]\fP indicating greater-than (ordered after) relationship + \fI(public static member constant)\fP + unordered(inline constexpr) a valid value of the type std::partial_ordering + \fB[static]\fP indicating relationship with an incomparable value + \fI(public static member constant)\fP + +.SH Conversions + + std::partial_ordering cannot be implicitly converted to other comparison category + types, while both std::strong_ordering and std::weak_ordering are + implicitly-convertible to partial_ordering. + +.SH Comparisons + + Comparison operators are defined between values of this type and literal 0. This + supports the expressions a <=> b == 0 or a <=> b < 0 that can be used to convert the + result of a three-way comparison operator to a boolean relationship; see std::is_eq, + std::is_lt, etc. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::partial_ordering is an + associated class of the arguments. + + The behavior of a program that attempts to compare a partial_ordering with anything + other than the integer literal 0 is undefined. + + operator== + operator< + operator> compares with zero or a partial_ordering + operator<= \fI(function)\fP + operator>= + operator<=> + +operator== + + friend constexpr bool operator==( partial_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool \fB(2)\fP + operator==( partial_ordering v, partial_ordering w ) noexcept = default; + +.SH Parameters + + v, w - std::partial_ordering values to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is equivalent, false if v is less, greater, or unordered + 2) true if both parameters hold the same value, false otherwise + +operator< + + friend constexpr bool operator<( partial_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator<( /*unspecified*/ u, partial_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::partial_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is less, and false if v is greater, equivalent, or unordered + 2) true if v is greater, and false if v is less, equivalent, or unordered + +operator<= + + friend constexpr bool operator<=( partial_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator<=( /*unspecified*/ u, partial_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::partial_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is less or equivalent, and false if v is greater or unordered + 2) true if v is greater or equivalent, and false if v is less or unordered + +operator> + + friend constexpr bool operator>( partial_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator>( /*unspecified*/ u, partial_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::partial_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is greater, and false if v is less, equivalent, or unordered + 2) true if v is less, and false if v is greater, equivalent, or unordered + +operator>= + + friend constexpr bool operator>=( partial_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator>=( /*unspecified*/ u, partial_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::partial_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is greater or equivalent, and false if v is less or unordered + 2) true if v is less or equivalent, and false if v is greater or unordered + +operator<=> + + friend constexpr partial_ordering operator<=>( partial_ordering v, \fB(1)\fP + /*unspecified*/ u ) noexcept; + friend constexpr partial_ordering operator<=>( /*unspecified*/ u, \fB(2)\fP + partial_ordering v ) noexcept; + +.SH Parameters + + v - a std::partial_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) v. + 2) greater if v is less, less if v is greater, otherwise v. + +.SH Notes + + The built-in operator<=> between floating-point values uses this ordering: the + positive zero and the negative zero compare equivalent, but can be distinguished, + and NaN values compare unordered with any other value. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + strong_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is substitutable + \fI(class)\fP + weak_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is not substitutable + \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::partial_sort.3 b/man/std::partial_sort.3 index b21b9d63c..f3b2e8ce7 100644 --- a/man/std::partial_sort.3 +++ b/man/std::partial_sort.3 @@ -1,84 +1,268 @@ -.TH std::partial_sort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::partial_sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partial_sort \- std::partial_sort + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP - void partial_sort( RandomIt first, RandomIt middle, RandomIt last ); + template< class RandomIt > + void partial_sort( RandomIt first, RandomIt middle, \fB(1)\fP (constexpr since C++20) + RandomIt last ); + template< class ExecutionPolicy, class RandomIt > + + void partial_sort( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt middle, + RandomIt last ); template< class RandomIt, class Compare > - void partial_sort( RandomIt first, RandomIt middle, RandomIt last, Compare comp \fB(2)\fP - ); - Rearranges elements such that the range [first, middle) contains the sorted middle - + void partial_sort( RandomIt first, RandomIt middle, \fB(3)\fP (constexpr since C++20) + RandomIt last, + + Compare comp ); + template< class ExecutionPolicy, class RandomIt, class + Compare > + + void partial_sort( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + RandomIt first, RandomIt middle, + RandomIt last, + + Compare comp ); + + Rearranges elements such that the range [first, middle) contains the sorted middle − first smallest elements in the range [first, last). The order of equal elements is not guaranteed to be preserved. The order of the - remaining elements in the range [middle, last) is unspecified. The first version - uses operator< to compare the elements, the second version uses the given comparison - function comp. + remaining elements in the range [middle, last) is unspecified. + + 1) Elements are sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the behavior is undefined: + + * [first, middle) or [middle, last) is not a valid range. + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements to sort + first, last - random access iterators defining the range + middle - random access iterator defining the one-past-the-end iterator of the + range to be sorted + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + can be dereferenced and then implicitly converted to both of them. .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. + Compare must meet the requirements of Compare. + +.SH Complexity -.SH Return value + Given \\(\\scriptsize M\\)M as middle - first, \\(\\scriptsize N\\)N as last - first: - \fI(none)\fP + 1,2) Approximately \\(\\scriptsize N \\cdot \\log(M)\\)N·log(M) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) Approximately \\(\\scriptsize N \\cdot \\log(M)\\)N·log(M) applications of the + comparator comp. -.SH Complexity +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation - Approximately (last-first)log(middle-first)) applications of cmp + See also the implementations in libstdc++ and libc++. + + partial_sort \fB(1)\fP + template + constexpr //< since C++20 + void partial_sort(RandomIt first, RandomIt middle, RandomIt last) + { + typedef typename std::iterator_traits::value_type VT; + std::partial_sort(first, middle, last, std::less()); + } + partial_sort \fB(3)\fP + namespace impl + { + template + constexpr //< since C++20 + void sift_down(RandomIt first, RandomIt last, const Compare& comp) + { + // sift down element at “first” + const auto length = static_cast(last - first); + std::size_t current = 0; + std::size_t next = 2; + while (next < length) + { + if (comp(*(first + next), *(first + (next - 1)))) + --next; + if (!comp(*(first + current), *(first + next))) + return; + std::iter_swap(first + current, first + next); + current = next; + next = 2 * current + 2; + } + --next; + if (next < length && comp(*(first + current), *(first + next))) + std::iter_swap(first + current, first + next); + } + + template + constexpr //< since C++20 + void heap_select(RandomIt first, RandomIt middle, RandomIt last, const Compare& comp) + { + std::make_heap(first, middle, comp); + for (auto i = middle; i != last; ++i) + { + if (comp(*i, *first)) + { + std::iter_swap(first, i); + sift_down(first, middle, comp); + } + } + } + } // namespace impl + + template + constexpr //< since C++20 + void partial_sort(RandomIt first, RandomIt middle, RandomIt last, Compare comp) + { + impl::heap_select(first, middle, last, comp); + std::sort_heap(first, middle, comp); + } + +.SH Notes + +.SH Algorithm + + The algorithm used is typically heap select to select the smallest elements, and + heap sort to sort the selected elements in the heap in ascending order. + + To select elements, a heap is used (see heap). For example, for operator< as + comparison function, max-heap is used to select middle − first smallest elements. + + Heap sort is used after selection to sort [first, middle) selected elements (see + std::sort_heap). + + Intended use + + std::partial_sort algorithms are intended to be used for small constant numbers of + [first, middle) selected elements. .SH Example - + // Run this code #include - #include #include + #include #include - + + void print(const auto& s, int middle) + { + for (int a : s) + std::cout << a << ' '; + std::cout << '\\n'; + if (middle > 0) + { + while (middle-- > 0) + std::cout << "--"; + std::cout << '^'; + } + else if (middle < 0) + { + for (auto i = s.size() + middle; --i; std::cout << " ") + {} + + for (std::cout << '^'; middle++ < 0; std::cout << "--") + {} + } + std::cout << '\\n'; + }; + int main() { std::array s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; - + print(s, 0); std::partial_sort(s.begin(), s.begin() + 3, s.end()); - for (int a : s) { - std::cout << a << " "; - } + print(s, 3); + std::partial_sort(s.rbegin(), s.rbegin() + 4, s.rend()); + print(s, -4); + std::partial_sort(s.rbegin(), s.rbegin() + 5, s.rend(), std::greater{}); + print(s, -5); } -.SH Output: +.SH Possible output: + + 5 7 4 2 8 6 1 9 0 3 0 1 2 7 8 6 5 9 4 3 + ------^ + 4 5 6 7 8 9 3 2 1 0 + ^-------- + 4 3 2 1 0 5 6 7 8 9 + ^---------- + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0896R4 C++98 [first, middle) and [middle, last) the behavior is undefined + were not required to be valid ranges if any of them is invalid .SH See also - partially sorts the given range making sure that it is partitioned - nth_element by the given element - \fI(function template)\fP - partial_sort_copy copies and partially sorts a range of elements - \fI(function template)\fP - sorts a range of elements while preserving order between equal - stable_sort elements - \fI(function template)\fP - sort sorts a range into ascending order - \fI(function template)\fP + partially sorts the given range making sure that it is + nth_element partitioned by the given element + \fI(function template)\fP + partial_sort_copy copies and partially sorts a range of elements + \fI(function template)\fP + sorts a range of elements while preserving order between equal + stable_sort elements + \fI(function template)\fP + sort sorts a range into ascending order + \fI(function template)\fP + ranges::partial_sort sorts the first N elements of a range + (C++20) (niebloid) diff --git a/man/std::partial_sort_copy.3 b/man/std::partial_sort_copy.3 index 52e351dd6..10b8da270 100644 --- a/man/std::partial_sort_copy.3 +++ b/man/std::partial_sort_copy.3 @@ -1,102 +1,184 @@ -.TH std::partial_sort_copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::partial_sort_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partial_sort_copy \- std::partial_sort_copy + .SH Synopsis Defined in header template< class InputIt, class RandomIt > - RandomIt partial_sort_copy( InputIt first, InputIt last, \fB(1)\fP + RandomIt partial_sort_copy( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + + RandomIt d_first, RandomIt + d_last ); + template< class ExecutionPolicy, + + class ForwardIt, class RandomIt > + RandomIt partial_sort_copy( ExecutionPolicy&& policy, + ForwardIt first, ForwardIt \fB(2)\fP \fI(since C++17)\fP + last, - RandomIt d_first, RandomIt d_last ); + RandomIt d_first, RandomIt + d_last ); template< class InputIt, class RandomIt, class Compare > - RandomIt partial_sort_copy( InputIt first, InputIt last, \fB(2)\fP - RandomIt d_first, RandomIt d_last, + RandomIt partial_sort_copy( InputIt first, InputIt last, + RandomIt d_first, RandomIt \fB(3)\fP (constexpr since C++20) + d_last, + + Compare comp ); + template< class ExecutionPolicy, + + class ForwardIt, class RandomIt, class Compare + > + RandomIt partial_sort_copy( ExecutionPolicy&& policy, + ForwardIt first, ForwardIt \fB(4)\fP \fI(since C++17)\fP + last, + RandomIt d_first, RandomIt + d_last, Compare comp ); Sorts some of the elements in the range [first, last) in ascending order, storing the result in the range [d_first, d_last). - At most d_last - d_first of the elements are moved to the range [d_first, d_first + - n) and then sorted. n is the number of elements to sort (n = min(last - first, - d_last - d_first)). The order of equal elements is not guaranteed to be preserved. - The first version uses operator< to compare the elements, the second version uses - the given comparison function comp. + At most d_last - d_first of the elements are placed sorted to the range + [d_first, d_first + n). n is the number of elements to sort + (std::min(std::distance(first, last), d_last - d_first)). The order of equal + elements is not guaranteed to be preserved. + + 1) Elements are sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If *first is not writable to d_first, the program is ill-formed. + + If any of the following conditions is satisfied, the behavior is undefined: + + * The type of *d_first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *d_first is not MoveConstructible. \fI(since C++11)\fP + * The type of *d_first is not MoveAssignable. .SH Parameters first, last - the range of elements to sort d_first, d_last - random access iterators defining the destination range + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + is less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function - object must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function + must not modify the objects passed to it and must be able to + accept all values of type (possibly const) Type1 and Type2 + regardless of value category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type RandomIt can be dereferenced and then implicitly converted to both - of them. + of them. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. + Compare must meet the requirements of Compare. .SH Return value - an iterator to the element defining the upper boundary of the sorted range, i.e. - d_first + min(last - first, d_last - d_first). + An iterator to the element defining the upper boundary of the sorted range, i.e. + d_first + std::min(std::distance(first, last), d_last - d_first). .SH Complexity - O(N·log(min(D,N)), where N = std::distance(first, last), D = std::distance(d_first, - d_last) applications of cmp. + Given \\(\\scriptsize N\\)N as std::distance(first, last), \\(\\scriptsize D\\)D as d_last + - d_first: + + 1,2) Approximately \\(\\scriptsize N \\cdot \\log(\\min(N,D))\\)N·log(min(N,D)) + comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) Approximately \\(\\scriptsize N \\cdot \\log(\\min(N,D))\\)N·log(min(N,D)) + applications of the comparator comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + See also the implementations in libstdc++ and libc++. .SH Example - The following code sorts an vector of integers and copies them into a smaller and a + The following code sorts a vector of integers and copies them into a smaller and a larger vector. - + // Run this code #include - #include #include #include - + #include + #include + #include + + void println(std::string_view rem, const auto& v) + { + std::cout << rem; + if constexpr (std::is_scalar_v>) + std::cout << v; + else + for (int e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { - std::vector v0{4, 2, 5, 1, 3}; + const auto v0 = {4, 2, 5, 1, 3}; std::vector v1{10, 11, 12}; std::vector v2{10, 11, 12, 13, 14, 15, 16}; std::vector::iterator it; - + it = std::partial_sort_copy(v0.begin(), v0.end(), v1.begin(), v1.end()); - - std::cout << "Writing to the smaller vector in ascending order gives: "; - for (int a : v1) { - std::cout << a << " "; - } - std::cout << '\\n'; - if(it == v1.end()) - std::cout << "The return value is the end iterator\\n"; - + println("Writing to the smaller vector in ascending order gives: ", v1); + + if (it == v1.end()) + println("The return value is the end iterator", ' '); + it = std::partial_sort_copy(v0.begin(), v0.end(), v2.begin(), v2.end(), std::greater()); - - std::cout << "Writing to the larger vector in descending order gives: "; - for (int a : v2) { - std::cout << a << " "; - } - std::cout << '\\n' << "The return value is the iterator to " << *it << '\\n'; + + println("Writing to the larger vector in descending order gives: ", v2); + println("The return value is the iterator to ", *it); } .SH Output: @@ -106,11 +188,23 @@ Writing to the larger vector in descending order gives: 5 4 3 2 1 15 16 The return value is the iterator to 15 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0896R4 C++98 *first was not required to be the program is ill-formed if + writable to d_first not writable + .SH See also - partial_sort sorts the first N elements of a range - \fI(function template)\fP - sort sorts a range into ascending order - \fI(function template)\fP - stable_sort sorts a range of elements while preserving order between equal elements - \fI(function template)\fP + partial_sort sorts the first N elements of a range + \fI(function template)\fP + sort sorts a range into ascending order + \fI(function template)\fP + sorts a range of elements while preserving order between + stable_sort equal elements + \fI(function template)\fP + ranges::partial_sort_copy copies and partially sorts a range of elements + (C++20) (niebloid) diff --git a/man/std::partial_sum.3 b/man/std::partial_sum.3 index 231f013c5..641bfc4ef 100644 --- a/man/std::partial_sum.3 +++ b/man/std::partial_sum.3 @@ -1,35 +1,68 @@ -.TH std::partial_sum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::partial_sum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partial_sum \- std::partial_sum + .SH Synopsis Defined in header - template< class InputIt, class OutputIt > \fB(1)\fP - OutputIt partial_sum( InputIt first, InputIt last, OutputIt d_first ); - template< class InputIt, class OutputIt, class BinaryOperation > - - OutputIt partial_sum( InputIt first, InputIt last, OutputIt d_first, \fB(2)\fP - - BinaryOperation op ); - - Computes the partial sums of the elements in the subranges of the range [first, - last) and writes them to the range beginning at d_first. The first version uses - operator+ to sum up the elements, the second version uses the given binary function - op. - - Equivalent operation: - - *(d_first) = *first; - *(d_first+1) = *first + *(first+1); - *(d_first+2) = *first + *(first+1) + *(first+2); - *(d_first+3) = *first + *(first+1) + *(first+2) + *(first+3); - ... - - op must not have side effects. \fI(until C++11)\fP - op must not invalidate any iterators, including the end iterators, or \fI(since C++11)\fP - modify any elements of the ranges involved. + template< class InputIt, class OutputIt > + + OutputIt partial_sum( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + + OutputIt d_first ); + template< class InputIt, class OutputIt, class BinaryOp + > + \fB(2)\fP (constexpr since C++20) + OutputIt partial_sum( InputIt first, InputIt last, + + OutputIt d_first, BinaryOp op ); + + 1) If [first, last) is empty, does nothing. + Otherwise, performs the following operations in order: + 1. Creates an accumulator acc, whose type is the value type of InputIt, and + initializes it with *first. + 2. Assigns acc to *d_first. + 3. For each integer i in [1, std::distance(first, last)), performs the following + operations in order: + a) Computes + acc + *iter + \fI(until C++11)\fP + std::move(acc) + *iter + \fI(since C++11)\fP, where iter is the next i + th iterator of first. + b) Assigns the result to acc. + c) Assigns acc^[1] to *dest, where dest is the next i + th iterator of d_first. + 2) Same as \fB(1)\fP, but computes + op(acc, *iter) + \fI(until C++11)\fP + op(std::move(acc), *iter) + \fI(since C++11)\fP instead. + + Given binary_op as the actual binary operation: + + * If any of the following conditions is satisfied, the program is ill-formed: + + * The value type of InputIt is not constructible from *first. + * acc is not writable to d_first. + * The result of + binary_op(acc, *iter) + \fI(until C++11)\fP + binary_op(std::move(acc), *iter) + \fI(since C++11)\fP is not implicitly convertible to the value type of InputIt. + * Given d_last as the iterator to be returned, if any of the following conditions + is satisfied, the behavior is undefined: + + * binary_op modifies any element of [first, last) or [d_first, d_last). + * binary_op invalidates any iterator or subrange in [first, last] or + [d_first, d_last]. + + 1. ↑ The actual value to be assigned is the result of the assignment in the + previous step. We assume the assignment result is acc here. .SH Parameters first, last - the range of elements to sum - d_first - the beginning of the destination range + d_first - the beginning of the destination range; may be equal to first binary operation function object that will be applied. The signature of the function should be equivalent to the following: @@ -37,79 +70,143 @@ Ret fun(const Type1 &a, const Type2 &b); op - The signature does not need to have const &. - The type Type1 must be such that an object of type - iterator_traits::value_type can be implicitly converted to - Type1. The type Type2 must be such that an object of type InputIt can - be dereferenced and then implicitly converted to Type2. The type Ret - must be such that an object of type - iterator_traits::value_type can be assigned a value of type - Ret. + The type Type1 must be such that an object of type + std::iterator_traits::value_type can be implicitly converted + to Type1. The type Type2 must be such that an object of type InputIt + can be dereferenced and then implicitly converted to Type2. The type + Ret must be such that an object of type InputIt can be dereferenced + and assigned a value of type Ret. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. .SH Return value - Iterator to the element past the last element written. + Iterator to the element past the last element written, or d_first if [first, last) + is empty. .SH Complexity - Exactly (last - first) - 1 applications of the binary operation + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) Exactly \\(\\scriptsize N-1\\)N-1 applications of operator+. + 2) Exactly \\(\\scriptsize N-1\\)N-1 applications of the binary function op. .SH Possible implementation -.SH First version + partial_sum \fB(1)\fP template - OutputIt partial_sum(InputIt first, InputIt last, - OutputIt d_first) + constexpr // since C++20 + OutputIt partial_sum(InputIt first, InputIt last, OutputIt d_first) { - return std::partial_sum(first, last, d_first, - std::plus()); + if (first == last) + return d_first; + + typename std::iterator_traits::value_type sum = *first; + *d_first = sum; + + while (++first != last) + { + sum = std::move(sum) + *first; // std::move since C++11 + *++d_first = sum; + } + + return ++d_first; + + // or, since C++14: + // return std::partial_sum(first, last, d_first, std::plus<>()); } -.SH Second version - template + partial_sum \fB(2)\fP + template + constexpr // since C++20 OutputIt partial_sum(InputIt first, InputIt last, - OutputIt d_first, BinaryOperation op) + OutputIt d_first, BinaryOp op) { - if (first == last) return d_first; - - typename std::iterator_traits::value_type sum = *first; - *d_first = sum; - - while (++first != last) { - sum = op(sum, *first); - *++d_first = sum; + if (first == last) + return d_first; + + typename std::iterator_traits::value_type acc = *first; + *d_first = acc; + + while (++first != last) + { + acc = op(std::move(acc), *first); // std::move since C++11 + *++d_first = acc; } + return ++d_first; } +.SH Notes + + acc was introduced because of the resolution of LWG issue 539. The reason of using + acc rather than directly summing up the results (i.e. *(d_first + 2) = (*first + + *(first + 1)) + *(first + 2);) is because the semantic of the latter is confusing if + the following types mismatch: + + * the value type of InputIt + * the writable type(s) of OutputIt + * the types of the parameters of operator+ or op + * the return type of operator+ or op + + acc serves as the intermediate object to store and provide the values for each step + of the computation: + + * its type is the value type of InputIt + * it is written to d_first + * its value is passed to operator+ or op + * it stores the return value of operator+ or op + + enum not_int { x = 1, y = 2 }; + + char i_array[4] = {100, 100, 100, 100}; + not_int e_array[4] = {x, x, y, y}; + int o_array[4]; + + // OK: uses operator+(char, char) and assigns char values to int array + std::partial_sum(i_array, i_array + 4, o_array); + + // Error: cannot assign not_int values to int array + std::partial_sum(e_array, e_array + 4, o_array); + + // OK: performs conversions when needed + // 1. creates “acc” of type char (the value type) + // 2. the char arguments are used for long multiplication (char -> long) + // 3. the long product is assigned to “acc” (long -> char) + // 4. “acc” is assigned to an element of “o_array” (char -> int) + // 5. go back to step 2 to process the remaining elements in the input range + std::partial_sum(i_array, i_array + 4, o_array, std::multiplies{}); + .SH Example - + // Run this code - #include - #include + #include #include #include - #include - + #include + #include + int main() { - std::vector v = {2, 2, 2, 2, 2, 2, 2, 2, 2, 2}; - - std::cout << "The first 10 even numbers are: "; - std::partial_sum(v.begin(), v.end(), + std::vector v(10, 2); // v = {2, 2, 2, 2, 2, 2, 2, 2, 2, 2} + + std::cout << "The first " << v.size() << " even numbers are: "; + // write the result to the cout stream + std::partial_sum(v.cbegin(), v.cend(), std::ostream_iterator(std::cout, " ")); std::cout << '\\n'; - - std::partial_sum(v.begin(), v.end(), v.begin(), std::multiplies()); - std::cout << "The first 10 powers of 2 are: "; - for (auto n : v) { - std::cout << n << " "; - } + + // write the result back to the vector v + std::partial_sum(v.cbegin(), v.cend(), + v.begin(), std::multiplies()); + + std::cout << "The first " << v.size() << " powers of 2 are: "; + for (int n : v) + std::cout << n << ' '; std::cout << '\\n'; } @@ -118,9 +215,30 @@ The first 10 even numbers are: 2 4 6 8 10 12 14 16 18 20 The first 10 powers of 2 are: 2 4 8 16 32 64 128 256 512 1024 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 242 C++98 op could not have side effects it cannot modify the + ranges involved + the type requirements needed for the + LWG 539 C++98 result added + evaluations and assignments to be valid + were missing + LWG 2055 C++11 acc was not moved while being accumulated it is moved + (P0616R0) + .SH See also adjacent_difference computes the differences between adjacent elements in a range - \fI(function template)\fP - accumulate sums up a range of elements - \fI(function template)\fP + \fI(function template)\fP + accumulate sums up or folds a range of elements + \fI(function template)\fP + inclusive_scan similar to std::partial_sum, includes the i^th input element in + \fI(C++17)\fP the i^th sum + \fI(function template)\fP + exclusive_scan similar to std::partial_sum, excludes the i^th input element + \fI(C++17)\fP from the i^th sum + \fI(function template)\fP diff --git a/man/std::partition.3 b/man/std::partition.3 index f352f075b..2e9cac7d6 100644 --- a/man/std::partition.3 +++ b/man/std::partition.3 @@ -1,47 +1,55 @@ -.TH std::partition 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::partition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partition \- std::partition + .SH Synopsis Defined in header - template< class BidirIt, class UnaryPredicate > - - BidirectionalIterator partition( BidirIt first, BidirIt last, \fI(until C++11)\fP - - UnaryPredicate p ); - template< class ForwardIt, class UnaryPredicate > + template< class ForwardIt, class UnaryPred > + ForwardIt partition( ForwardIt first, ForwardIt last, \fB(1)\fP (constexpr since C++20) + UnaryPred p ); + template< class ExecutionPolicy, class ForwardIt, class + UnaryPred > - ForwardIt partition( ForwardIt first, ForwardIt last, \fI(since C++11)\fP + ForwardIt partition( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP - UnaryPredicate p ); + ForwardIt first, ForwardIt last, + UnaryPred p ); - Reorders the elements in the range [first, last) in such a way that all elements for - which the predicate p returns true precede the elements for which predicate p + 1) Reorders the elements in the range [first, last) in such a way that all elements + for which the predicate p returns true precede all elements for which predicate p returns false. Relative order of the elements is not preserved. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if -.SH Parameters - - first, last - the range of elements to reorder - unary predicate which returns true if the element - should be ordered before other elements. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) - The signature of the predicate function should be - equivalent to the following: + If + the type of *first is not Swappable + \fI(until C++11)\fP + ForwardIt is not ValueSwappable + \fI(since C++11)\fP, the behavior is undefined. - p - bool pred(const Type &a); +.SH Parameters - The signature does not need to have const &, but - the function must not modify the objects passed to - it. - The type Type must be such that an object of type - ForwardIt can be dereferenced and then implicitly - converted to Type. + first, last - the range of elements to reorder + policy - the execution policy to use. See execution policy for details. + unary predicate which returns true if the element should be ordered + before other elements. + + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of ForwardIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. - - - ForwardIt must meet the requirements of ValueSwappable and ForwardIterator. However, - the operation is more efficient if ForwardIt also satisfies the requirements of - BidirectionalIterator + ForwardIt must meet the requirements of LegacyForwardIterator. - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value @@ -49,126 +57,128 @@ .SH Complexity - Exactly last-first applications of the predicate and at most last-first swaps. If - ForwardIt meets the requirements of BidirectionalIterator at most (last-first)/2 - swaps are done. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) Exactly \\(\\scriptsize N\\)N applications of p. + At most \\(\\scriptsize N/2\\)N/2 swaps if ForwardIt meets the requirements of + LegacyBidirectionalIterator, and at most \\(\\scriptsize N\\)N swaps otherwise. + 2) \\(\\scriptsize O(N)\\)O(N) applications of p. + \\(\\scriptsize O(N \\cdot log(N))\\)O(N·log(N)) swaps. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template - BidirIt partition(BidirIt first, BidirIt last, UnaryPredicate p) + Implements overload \fB(1)\fP preserving C++11 compatibility. + + template + ForwardIt partition(ForwardIt first, ForwardIt last, UnaryPred p) { - while \fB(1)\fP { - while ((first != last) && p(*first)) { + first = std::find_if_not(first, last, p); + if (first == last) + return first; + + for (auto i = std::next(first); i != last; ++i) + if (p(*i)) + { + std::iter_swap(i, first); ++first; } - if (first == last--) break; - while ((first != last) && !p(*last)) { - --last; - } - if (first == last) break; - std::iter_swap(first++, last); - } + return first; } -.SH Example 1 +.SH Example + - // Run this code #include - #include + #include #include #include #include - - bool is_even(int i) { return i % 2 == 0; } - - int main() - { - std::vector v; - for (int i = 0; i < 10; ++i) v.push_back(i); - - std::cout << "Original vector:\\n "; - std::copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); - - // Partition the vector - std::vector::iterator p = - std::partition(v.begin(), v.end(), std::ptr_fun(is_even)); - - std::cout << "\\nPartitioned vector:\\n "; - std::copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); - std::cout << "\\nBefore partition:\\n "; - std::copy(v.begin(), p, std::ostream_iterator(std::cout, " ")); - std::cout << "\\nAfter partition:\\n "; - std::copy(p, v.end(), std::ostream_iterator(std::cout, " ")); - } - -.SH Possible output: - - Original vector: - 0 1 2 3 4 5 6 7 8 9 - Partitioned vector: - 0 8 2 6 4 5 3 7 1 9 - Before partition: - 0 8 2 6 4 - After partition: - 5 3 7 1 9 - -.SH Example 2 - -// Run this code + template + void quicksort(ForwardIt first, ForwardIt last) + { + if (first == last) + return; + + auto pivot = *std::next(first, std::distance(first, last) / 2); + auto middle1 = std::partition(first, last, [pivot](const auto& em) + { + return em < pivot; + }); + auto middle2 = std::partition(middle1, last, [pivot](const auto& em) + { + return !(pivot < em); + }); - #include - #include - #include - #include - - template - ForwardIt choose_pivot(ForwardIt first, ForwardIt last) - { - return std::next(first, std::distance(first,last)/2); - } - - template - void quicksort(ForwardIt first, ForwardIt last) - { - using T = typename std::iterator_traits::value_type; - - if(first == last) return; - - T pivot = *choose_pivot(first,last); - - ForwardIt middle1 = std::partition(first, last, - [pivot](const T& em){ return em < pivot; }); - ForwardIt middle2 = std::partition(middle1, last, - [pivot](const T& em){ return !(pivot < em); }); - quicksort(first, middle1); quicksort(middle2, last); - } - - + } + int main() { - std::forward_list fl = {1, 30, -4, 3, 5, -4, 1, 6, -8, 2, -5, 64, 1, 92}; - - quicksort(std::begin(fl), std::end(fl)); - - for(int fi : fl) std::cout << fi << ' '; - std::cout << '\\n'; + std::vector v{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + std::cout << "Original vector: "; + for (int elem : v) + std::cout << elem << ' '; + + auto it = std::partition(v.begin(), v.end(), [](int i) {return i % 2 == 0;}); + + std::cout << "\\nPartitioned vector: "; + std::copy(std::begin(v), it, std::ostream_iterator(std::cout, " ")); + std::cout << "* "; + std::copy(it, std::end(v), std::ostream_iterator(std::cout, " ")); + + std::forward_list fl {1, 30, -4, 3, 5, -4, 1, 6, -8, 2, -5, 64, 1, 92}; + std::cout << "\\nUnsorted list: "; + for (int n : fl) + std::cout << n << ' '; + + quicksort(std::begin(fl), std::end(fl)); + std::cout << "\\nSorted using quicksort: "; + for (int fi : fl) + std::cout << fi << ' '; + std::cout << '\\n'; } -.SH Output: +.SH Possible output: + + Original vector: 0 1 2 3 4 5 6 7 8 9 + Partitioned vector: 0 8 2 6 4 * 5 3 7 1 9 + Unsorted list: 1 30 -4 3 5 -4 1 6 -8 2 -5 64 1 92 + Sorted using quicksort: -8 -5 -4 -4 1 1 1 2 3 5 6 30 64 92 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - -8 -5 -4 -4 1 1 1 2 3 5 6 30 64 92 + DR Applied to Behavior as published Correct behavior + LWG 498 C++98 std::partition required first and only required to be + last to be LegacyBidirectionalIterator LegacyForwardIterator + std::partition was only required to place + LWG 2150 C++98 one element corrected the + satisfying p before one element not requirement + satisfying p .SH See also - is_partitioned determines if the range is partitioned by the given predicate - \fI(C++11)\fP \fI(function template)\fP - divides elements into two groups while preserving their relative - stable_partition order - \fI(function template)\fP + is_partitioned determines if the range is partitioned by the given predicate + \fI(C++11)\fP \fI(function template)\fP + divides elements into two groups while preserving their relative + stable_partition order + \fI(function template)\fP + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) diff --git a/man/std::partition_copy.3 b/man/std::partition_copy.3 index 6d656fcfc..91ac01bd1 100644 --- a/man/std::partition_copy.3 +++ b/man/std::partition_copy.3 @@ -1,122 +1,184 @@ -.TH std::partition_copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::partition_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partition_copy \- std::partition_copy + .SH Synopsis Defined in header template< class InputIt, class OutputIt1, - class OutputIt2, class UnaryPredicate > - std::pair \fI(since C++11)\fP - partition_copy( InputIt first, InputIt last, - OutputIt1 d_first_true, OutputIt2 d_first_false, + class OutputIt2, class UnaryPred > + std::pair \fI(since C++11)\fP + partition_copy( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + OutputIt1 d_first_true, OutputIt2 + d_first_false, + + UnaryPred p ); + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2, + + class ForwardIt3, class UnaryPred > + std::pair + partition_copy( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + ForwardIt2 d_first_true, ForwardIt3 + d_first_false, + + UnaryPred p ); - UnaryPredicate p ); + 1) Copies the elements from the range [first, last) to two different ranges + depending on the value returned by the predicate p. + * The elements that satisfy the predicate p are copied to the range beginning at + d_first_true. + * The rest of the elements are copied to the range beginning at d_first_false. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if - Copies the elements from the range [first, last) to two different ranges depending - on the value returned by the predicate p. The elements, that satisfy the predicate - p, are copied to the range beginning at d_first_true. The rest of the elements are - copied to the range beginning at d_first_false. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If *first is not writable to d_first_true or d_first_false, the program is + ill-formed. + + Among the input range and the two output ranges, if any two ranges overlap, the + behavior is undefined. .SH Parameters - first, last - the range of elements to sort + first, last - the range of elements to copy from d_first_true - the beginning of the output range for the elements that satisfy p d_first_false - the beginning of the output range for the elements that do not satisfy p + policy - the execution policy to use. See execution policy for details. unary predicate which returns true if the element should be placed in d_first_true. - The signature of the predicate function should be equivalent to the - following: - p - - bool pred(const Type &a); - - The signature does not need to have const &, but the function must - not modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a + parameter type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt1 must meet the requirements of OutputIterator. + OutputIt1, OutputIt2 must meet the requirements of LegacyOutputIterator. - - OutputIt2 must meet the requirements of OutputIterator. + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value - A pair constructed from the iterator to the end of the d_first_true range and the - iterator to the end of the d_first_false range. + A std::pair constructed from the iterator to the end of the d_first_true range and + the iterator to the end of the d_first_false range. .SH Complexity - Exactly distance(first, last) applications of p. + Exactly std::distance(first, last) applications of p. + + For the overload \fB(2)\fP, there may be a performance cost if ForwardIt's value type is + not CopyConstructible. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation + partition_copy \fB(1)\fP template + class OutputIt2, class UnaryPred> + constexpr //< since C++20 std::pair partition_copy(InputIt first, InputIt last, OutputIt1 d_first_true, OutputIt2 d_first_false, - UnaryPredicate p) + UnaryPred p) { - while (first != last) { - if (p(*first)) { + for (; first != last; ++first) + { + if (p(*first)) + { *d_first_true = *first; ++d_first_true; - } else { + } + else + { *d_first_false = *first; ++d_first_false; } - ++first; } + return std::pair(d_first_true, d_first_false); } .SH Example - + // Run this code - #include #include + #include #include - - int main() + + void print(auto rem, const auto& v) { - int arr [10] = {1,2,3,4,5,6,7,8,9,10}; - int true_arr [5] = {0}; - int false_arr [5] = {0}; - - std::partition_copy(std::begin(arr), std::end(arr), std::begin(true_arr),std::begin(false_arr), - [] (int i) {return i > 5;}); - - std::cout << "true_arr: "; - for (auto it = std::begin(true_arr); it != std::end(true_arr); ++it) { - std::cout << *it << ' '; - } + for (std::cout << rem; const auto& x : v) + std::cout << x << ' '; std::cout << '\\n'; - - std::cout << "false_arr: "; - for (auto it = std::begin(false_arr); it != std::end(false_arr); ++it) { - std::cout << *it << ' '; - } - std::cout << '\\n'; - - return 0; - + } + + int main() + { + int arr[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + int true_arr[5] = {0}; + int false_arr[5] = {0}; + + std::partition_copy(std::begin(arr), std::end(arr), + std::begin(true_arr), std::begin(false_arr), + [](int i) { return 4 < i; }); + + print("true_arr: ", true_arr); + print("false_arr: ", false_arr); } .SH Output: - true_arr: 6 7 8 9 10 - false_arr: 1 2 3 4 5 + true_arr: 5 6 7 8 9 + false_arr: 0 1 2 3 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the value type of InputIt 1. not required + P0896R4 C++11 \fI(C++11)\fP/ForwardIt1 \fI(C++17)\fP 2. the behavior is + C++17 was required to be CopyAssignable undefined in this + 2. the two output ranges could overlap case .SH See also - partition divides a range of elements into two groups - \fI(function template)\fP - divides elements into two groups while preserving their relative - stable_partition order - \fI(function template)\fP + partition divides a range of elements into two groups + \fI(function template)\fP + divides elements into two groups while preserving their + stable_partition relative order + \fI(function template)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + remove_copy copies a range of elements omitting those that satisfy + remove_copy_if specific criteria + \fI(function template)\fP + ranges::partition_copy copies a range dividing the elements into two groups + (C++20) (niebloid) diff --git a/man/std::partition_point.3 b/man/std::partition_point.3 index c565cb7ca..1c88439ab 100644 --- a/man/std::partition_point.3 +++ b/man/std::partition_point.3 @@ -1,13 +1,19 @@ -.TH std::partition_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::partition_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::partition_point \- std::partition_point + .SH Synopsis Defined in header - template< class ForwardIt, class UnaryPredicate > - ForwardIt partition_point( ForwardIt first, ForwardIt last, \fB(1)\fP \fI(since C++11)\fP - UnaryPredicate p ); + template< class ForwardIt, class UnaryPred > \fI(since C++11)\fP + ForwardIt partition_point( ForwardIt first, ForwardIt last, (constexpr since C++20) + UnaryPred p ); + + Examines the partitioned range [first, last) and locates the end of the first + partition, that is, the first element that does not satisfy p or last if all + elements satisfy p. - Examines the partitioned (as if by std::partition) range [first, last) and locates - the end of the first partition, that is, the first element that does not satisfy p - or last if all elements satisfy p. + If the elements elem of [first, last) are not partitioned with respect to the + expression bool(p(elem)), the behavior is undefined. .SH Parameters @@ -15,20 +21,17 @@ unary predicate which returns true for the elements found in the beginning of the range. - The signature of the predicate function should be equivalent to the - following: - p - - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type ForwardIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of ForwardIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value @@ -37,42 +40,87 @@ .SH Complexity - The number of applications of the predicate p is logarithmic in the distance between - first and last + Given \\(\\scriptsize N\\)N as std::distance(first, last), performs \\(\\scriptsize + O(log(N))\\)O(log(N)) applications of the predicate p. + +.SH Notes + + This algorithm is a more general form of std::lower_bound, which can be expressed in + terms of std::partition_point with the predicate [&](const auto& e) { return e < + value; });. + +.SH Possible implementation + + template + constexpr //< since C++20 + ForwardIt partition_point(ForwardIt first, ForwardIt last, UnaryPred p) + { + for (auto length = std::distance(first, last); 0 < length; ) + { + auto half = length / 2; + auto middle = std::next(first, half); + if (p(*middle)) + { + first = std::next(middle); + length -= (half + 1); + } + else + length = half; + } + + return first; + } .SH Example - + // Run this code #include #include #include #include - + + auto print_seq = [](auto rem, auto first, auto last) + { + for (std::cout << rem; first != last; std::cout << *first++ << ' ') {} + std::cout << '\\n'; + }; + int main() { - std::array v = { 1, 2, 3, 4, 5, 6, 7, 8, 9 }; - - auto is_even = [](int i){ return i % 2 == 0; }; + std::array v{1, 2, 3, 4, 5, 6, 7, 8, 9}; + + auto is_even = [](int i) { return i % 2 == 0; }; + std::partition(v.begin(), v.end(), is_even); - - auto p = std::partition_point(v.begin(), v.end(), is_even); - - std::cout << "Before partition:\\n "; - std::copy(v.begin(), p, std::ostream_iterator(std::cout, " ")); - std::cout << "\\nAfter partition:\\n "; - std::copy(p, v.end(), std::ostream_iterator(std::cout, " ")); + print_seq("After partitioning, v: ", v.cbegin(), v.cend()); + + const auto pp = std::partition_point(v.cbegin(), v.cend(), is_even); + const auto i = std::distance(v.cbegin(), pp); + std::cout << "Partition point is at " << i << "; v[" << i << "] = " << *pp << '\\n'; + + print_seq("First partition (all even elements): ", v.cbegin(), pp); + print_seq("Second partition (all odd elements): ", pp, v.cend()); } -.SH Output: +.SH Possible output: - Before partition: - 8 2 6 4 - After partition: - 5 3 7 1 9 + After partitioning, v: 8 2 6 4 5 3 7 1 9 + Partition point is at 4; v[4] = 5 + First partition (all even elements): 8 2 6 4 + Second partition (all odd elements): 5 3 7 1 9 .SH See also - is_sorted checks whether a range is sorted into ascending order - \fI(C++11)\fP \fI(function template)\fP + find + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP + \fI(C++11)\fP + is_sorted checks whether a range is sorted into ascending order + \fI(C++11)\fP \fI(function template)\fP + returns an iterator to the first element not less than the + lower_bound given value + \fI(function template)\fP + ranges::partition_point locates the partition point of a partitioned range + (C++20) (niebloid) diff --git a/man/std::permutable.3 b/man/std::permutable.3 new file mode 100644 index 000000000..f704c4128 --- /dev/null +++ b/man/std::permutable.3 @@ -0,0 +1,43 @@ +.TH std::permutable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::permutable \- std::permutable + +.SH Synopsis + Defined in header + template< class I > + + concept permutable = + std::forward_iterator && \fI(since C++20)\fP + std::indirectly_movable_storable && + + std::indirectly_swappable; + + The concept permutable refines std::forward_iterator by adding requirements for + reordering through moves and swaps. + + Semantic requirements + + I models permutable only if all concepts it subsumes are modeled. + +.SH See also + + sortable specifies the common requirements of algorithms that + (C++20) permute sequences into ordered sequences + (concept) + ranges::remove + ranges::remove_if removes elements satisfying specific criteria + (C++20) (niebloid) + (C++20) + ranges::unique removes consecutive duplicate elements in a range + (C++20) (niebloid) + ranges::reverse reverses the order of elements in a range + (C++20) (niebloid) + ranges::rotate rotates the order of elements in a range + (C++20) (niebloid) + ranges::shuffle randomly re-orders elements in a range + (C++20) (niebloid) + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::stable_partition divides elements into two groups while preserving their + (C++20) relative order + (niebloid) diff --git a/man/std::perror.3 b/man/std::perror.3 index 1dd11b827..d04103935 100644 --- a/man/std::perror.3 +++ b/man/std::perror.3 @@ -1,19 +1,22 @@ -.TH std::perror 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::perror 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::perror \- std::perror + .SH Synopsis Defined in header - void perror( const char *s ); + void perror( const char *s ); Prints a textual description of the error code currently stored in the system variable errno to stderr. The description is formed by concatenating the following components: - * the contents of the null-terminated byte string pointed to by s (unless s is a - null pointer) - * ": " - * implementation-defined error message describing the error code stored in errno. - This message is identical to the output of std::strerror(errno). - * '\\n'. + * the contents of the null-terminated byte string pointed to by s, followed by ": + " (unless s is a null pointer or the character pointed to by s is the null + character). + * implementation-defined error message string describing the error code stored in + errno, followed by '\\n'. The error message string is identical to the result of + std::strerror(errno). .SH Parameters @@ -25,30 +28,31 @@ .SH Example - + // Run this code - #include #include + #include #include - + int main() { double not_a_number = std::log(-1.0); - if (errno == EDOM) { + if (errno == EDOM) std::perror("log(-1) failed"); - } + std::printf("%f\\n", not_a_number); } -.SH Output: +.SH Possible output: log(-1) failed: Numerical argument out of domain + nan .SH See also errno macro which expands to POSIX-compatible thread-local error number variable - (macro variable) + (macro variable) strerror returns a text version of a given error code - \fI(function)\fP + \fI(function)\fP C documentation for perror diff --git a/man/std::piecewise_constant_distribution.3 b/man/std::piecewise_constant_distribution.3 index f8d95b752..50158110b 100644 --- a/man/std::piecewise_constant_distribution.3 +++ b/man/std::piecewise_constant_distribution.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution \- std::piecewise_constant_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -12,83 +15,116 @@ distribution. The probability density for any b - i≤x> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code #include - #include #include #include - + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); // 50% of the time, generate a random number between 0 and 1 // 50% of the time, generate a random number between 10 and 15 - std::vector i{0, 1, 10, 15}; - std::vector w{ 1, 0, 1}; + std::vector i {0, 1, 10, 15}; + std::vector w {1, 0, 1}; std::piecewise_constant_distribution<> d(i.begin(), i.end(), w.begin()); - + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n {}; n < 1e4; ++n) ++hist[d(gen)]; - } - for(auto p : hist) { - std::cout << p.first << ' ' << std::string(p.second/100, '*') << '\\n'; - } + + for (std::cout << std::hex << std::uppercase; auto [x, y] : hist) + std::cout << x << ' ' << std::string(y / 100, '*') << '\\n'; } -.SH Output: +.SH Possible output: 0 ************************************************** - 10 ********** - 11 ********* - 12 ********* - 13 ********** - 14 ********* + A ********** + B ********* + C ********* + D ********** + E ********* + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 28.5.9.6.2 Class template piecewise_constant_distribution + [rand.dist.samp.pconst] (p: 1421-1422) + * C++20 standard (ISO/IEC 14882:2020): + + * 29.6.9.6.2 Class template piecewise_constant_distribution + [rand.dist.samp.pconst] (p: 1207-1208) + * C++17 standard (ISO/IEC 14882:2017): + + * 29.6.8.6.2 Class template piecewise_constant_distribution + [rand.dist.samp.pconst] (p: 1098-1100) + * C++14 standard (ISO/IEC 14882:2014): + + * 26.5.8.6.2 Class template piecewise_constant_distribution + [rand.dist.samp.pconst] (p: 962-964) + * C++11 standard (ISO/IEC 14882:2011): + + * 26.5.8.6.2 Class template piecewise_constant_distribution + [rand.dist.samp.pconst] (p: 955-957) diff --git a/man/std::piecewise_constant_distribution::intervals,densities.3 b/man/std::piecewise_constant_distribution::intervals,densities.3 index b5aeb4a77..06e373386 100644 --- a/man/std::piecewise_constant_distribution::intervals,densities.3 +++ b/man/std::piecewise_constant_distribution::intervals,densities.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::intervals,densities 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::intervals,densities 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::intervals,densities \- std::piecewise_constant_distribution::intervals,densities + .SH Synopsis std::vector intervals() const; \fB(1)\fP \fI(since C++11)\fP std::vector densities() const; \fB(2)\fP \fI(since C++11)\fP diff --git a/man/std::piecewise_constant_distribution::max.3 b/man/std::piecewise_constant_distribution::max.3 index db7d3c87e..efce78b62 100644 --- a/man/std::piecewise_constant_distribution::max.3 +++ b/man/std::piecewise_constant_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::max \- std::piecewise_constant_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::piecewise_constant_distribution::min.3 b/man/std::piecewise_constant_distribution::min.3 index d6d694222..fa7e36ca5 100644 --- a/man/std::piecewise_constant_distribution::min.3 +++ b/man/std::piecewise_constant_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::min \- std::piecewise_constant_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::piecewise_constant_distribution::operator().3 b/man/std::piecewise_constant_distribution::operator().3 index 954a84a09..224f22044 100644 --- a/man/std::piecewise_constant_distribution::operator().3 +++ b/man/std::piecewise_constant_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::operator() \- std::piecewise_constant_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::piecewise_constant_distribution::param.3 b/man/std::piecewise_constant_distribution::param.3 index db9a0f467..a22d15d37 100644 --- a/man/std::piecewise_constant_distribution::param.3 +++ b/man/std::piecewise_constant_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::param \- std::piecewise_constant_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::piecewise_constant_distribution::piecewise_constant_distribution.3 b/man/std::piecewise_constant_distribution::piecewise_constant_distribution.3 index f84bdc9f9..a47db1420 100644 --- a/man/std::piecewise_constant_distribution::piecewise_constant_distribution.3 +++ b/man/std::piecewise_constant_distribution::piecewise_constant_distribution.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::piecewise_constant_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::piecewise_constant_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::piecewise_constant_distribution \- std::piecewise_constant_distribution::piecewise_constant_distribution + .SH Synopsis piecewise_constant_distribution(); \fB(1)\fP \fI(since C++11)\fP template< class InputIt1, class InputIt2 > @@ -10,7 +13,7 @@ template< class UnaryOperation > piecewise_constant_distribution( std::initializer_list \fB(3)\fP \fI(since C++11)\fP - bl, + ilist_i, UnaryOperation fw ); template< class UnaryOperation > @@ -19,18 +22,18 @@ RealType xmin, RealType xmax, UnaryOperation fw ); - explicit piecewise_constant_distribution( const param_type& parm \fB(5)\fP \fI(since C++11)\fP + explicit piecewise_constant_distribution( const param_type& param \fB(5)\fP \fI(since C++11)\fP ); Constructs new piecewise constant distribution object. 1) Constructs a distribution object with n = 1, ρ0 = 1, b0 = 0, and b1 = 1. - 2) Constructs a distribution object from iterators over the and interval sequence + 2) Constructs a distribution object from iterators over the interval sequence [first_i, last_i) and a matching weight sequence starting at first_w. 3) Constructs a distribution object where the intervals are taken from the initializer list ilist_i and the weights generated by the function fw. - 4) Constructs a distribution object with the fw intervals distributed uniformly over - [xmin, xmax] + 4) Constructs a distribution object with the nw intervals distributed uniformly over + [xmin, xmax] and the weights generated by the function fw. 5) Constructs a distribution object initialized with the parameters param. .SH Parameters @@ -38,9 +41,9 @@ first_i - iterator initialized to the start of the interval sequence last_i - iterator initialized to one-past-the-end of the interval sequence first_w - iterator initialized to the start of the density (weight) sequence - ilist_i - initializer_list yielding the interval sequnce + ilist_i - initializer_list yielding the interval sequence fw - double(double) function yielding the densities nw - the number of densities xmin - the lower bound of the interval sequence xmax - the upper bound of the interval sequence - parm - the distribution parameter set + param - the distribution parameter set diff --git a/man/std::piecewise_constant_distribution::reset.3 b/man/std::piecewise_constant_distribution::reset.3 index 4eb67e7cd..49ab5e292 100644 --- a/man/std::piecewise_constant_distribution::reset.3 +++ b/man/std::piecewise_constant_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_constant_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_constant_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_constant_distribution::reset \- std::piecewise_constant_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::piecewise_construct,std::piecewise_construct_t.3 b/man/std::piecewise_construct,std::piecewise_construct_t.3 new file mode 100644 index 000000000..f0f59445c --- /dev/null +++ b/man/std::piecewise_construct,std::piecewise_construct_t.3 @@ -0,0 +1,79 @@ +.TH std::piecewise_construct,std::piecewise_construct_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_construct,std::piecewise_construct_t \- std::piecewise_construct,std::piecewise_construct_t + +.SH Synopsis + Defined in header + struct piecewise_construct_t { explicit \fB(1)\fP \fI(since C++11)\fP + piecewise_construct_t() = default; }; + constexpr std::piecewise_construct_t \fI(since C++11)\fP + piecewise_construct{}; \fB(2)\fP \fI(until C++17)\fP + inline constexpr std::piecewise_construct_t \fI(since C++17)\fP + piecewise_construct{}; + + 1) std::piecewise_construct_t is an empty class tag type used to disambiguate + between different functions that take two tuple arguments. + 2) The constant std::piecewise_construct is an instance of \fB(1)\fP. + + The overloads that do not use std::piecewise_construct_t assume that each tuple + argument becomes the element of a pair. The overloads that use + std::piecewise_construct_t assume that each tuple argument is used to construct, + piecewise, a new object of specified type, which will become the element of the + pair. + +.SH Example + + + +// Run this code + + #include + #include + #include + + struct Foo + { + Foo(std::tuple) + { + std::cout << "Constructed a Foo from a tuple\\n"; + } + + Foo(int, float) + { + std::cout << "Constructed a Foo from an int and a float\\n"; + } + }; + + int main() + { + std::tuple t(1, 3.14); + + std::cout << "Creating p1...\\n"; + std::pair p1(t, t); + + std::cout << "Creating p2...\\n"; + std::pair p2(std::piecewise_construct, t, t); + } + +.SH Output: + + Creating p1... + Constructed a Foo from a tuple + Constructed a Foo from a tuple + Creating p2... + Constructed a Foo from an int and a float + Constructed a Foo from an int and a float + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2510 C++11 the default constructor was non-explicit, which made explicit + could lead to ambiguity + +.SH See also + + constructor constructs new pair + \fI(public member function of std::pair)\fP diff --git a/man/std::piecewise_construct.3 b/man/std::piecewise_construct.3 deleted file mode 100644 index 30663981d..000000000 --- a/man/std::piecewise_construct.3 +++ /dev/null @@ -1,50 +0,0 @@ -.TH std::piecewise_construct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - constexpr piecewise_construct_t piecewise_construct = \fI(since C++11)\fP - std::piecewise_construct_t(); - - The constant std::piecewise_construct is an instance of an empty struct tag type - std::piecewise_construct_t. - -.SH Example - - - -// Run this code - - #include - #include - #include - - struct Foo { - Foo(std::tuple) - { - std::cout << "Constructed a Foo from a tuple\\n"; - } - Foo(int, float) - { - std::cout << "Constructed a Foo from an int and a float\\n"; - } - }; - - int main() - { - std::tuple t(1, 3.14); - std::pair p1(t, t); - std::pair p2(std::piecewise_construct, t, t); - } - -.SH Output: - - Constructed a Foo from a tuple - Constructed a Foo from a tuple - Constructed a Foo from an int and a float - Constructed a Foo from an int and a float - -.SH See also - - piecewise_construct_t tag type used to select correct function overload for - \fI(C++11)\fP piecewise construction - \fI(class)\fP - constructor constructs new pair - \fI(public member function of std::pair)\fP diff --git a/man/std::piecewise_construct_t.3 b/man/std::piecewise_construct_t.3 deleted file mode 100644 index 1f44bb5d1..000000000 --- a/man/std::piecewise_construct_t.3 +++ /dev/null @@ -1,56 +0,0 @@ -.TH std::piecewise_construct_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - struct piecewise_construct_t { }; \fI(since C++11)\fP - - std::piecewise_construct_t is an empty struct tag type used to disambiguate between - different functions that take two tuple arguments. - - The overloads that do not use std::piecewise_construct_t assume that each tuple - argument becomes the element of a pair. The overloads that use - std::piecewise_construct_t assume that each tuple argument is used to construct, - piecewise, a new object of specified type, which will become the element of the - pair. - -.SH Example - - - -// Run this code - - #include - #include - #include - - struct Foo { - Foo(std::tuple) - { - std::cout << "Constructed a Foo from a tuple\\n"; - } - Foo(int, float) - { - std::cout << "Constructed a Foo from an int and a float\\n"; - } - }; - - int main() - { - std::tuple t(1, 3.14); - std::pair p1(t, t); - std::pair p2(std::piecewise_construct, t, t); - } - -.SH Output: - - Constructed a Foo from a tuple - Constructed a Foo from a tuple - Constructed a Foo from an int and a float - Constructed a Foo from an int and a float - -.SH See also - - piecewise_construct an object of type piecewise_construct_t used to disambiguate - \fI(C++11)\fP functions for piecewise construction - (constant) - constructor constructs new pair - \fI(public member function of std::pair)\fP diff --git a/man/std::piecewise_linear_distribution.3 b/man/std::piecewise_linear_distribution.3 index 55584f1fc..baecf033f 100644 --- a/man/std::piecewise_linear_distribution.3 +++ b/man/std::piecewise_linear_distribution.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution \- std::piecewise_linear_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -6,15 +9,16 @@ std::piecewise_linear_distribution produces random floating-point numbers, which are distributed according to a linear probability density function within each of the - several subintervals [b + several subintervals \\(\\small{[b_i, b_{i+1})}\\)[b i, b i+1). The distribution is such that the probability density at each interval - boundary is exactly the predefined value p + boundary is exactly the predefined value \\(\\small{p_i}\\)p i. - The probability density for any b + The probability density for any \\(\\small{ b_i \\le x < b_{i+1} }\\)b i≤x> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include #include - #include + #include #include #include - + #include + int main() { std::random_device rd; - std::mt19937 gen(rd()); + std::mt19937 gen{rd()}; // increase the probability from 0 to 5 // remain flat from 5 to 10 // decrease from 10 to 15 at the same rate std::vector i{0, 5, 10, 15}; - std::vector w{0, 1, 1, 0}; - std::piecewise_linear_distribution<> d(i.begin(), i.end(), w.begin()); - + std::vector w{0, 1, 1, 0}; + std::piecewise_linear_distribution<> d{i.begin(), i.end(), w.begin()}; + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n{}; n < 1e4; ++n) ++hist[d(gen)]; - } - for(auto p : hist) { - std::cout << std::setw(2) << std::setfill('0') << p.first << ' ' - << std::string(p.second/100,'*') << '\\n'; - } + + for (auto [x, y] : hist) + std::cout << std::setw(2) << std::setfill('0') << x + << ' ' << std::string(y / 100, '*') << '\\n'; } .SH Possible output: diff --git a/man/std::piecewise_linear_distribution::intervals,densities.3 b/man/std::piecewise_linear_distribution::intervals,densities.3 index 59ea128d9..7859826ca 100644 --- a/man/std::piecewise_linear_distribution::intervals,densities.3 +++ b/man/std::piecewise_linear_distribution::intervals,densities.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::intervals,densities 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::intervals,densities 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::intervals,densities \- std::piecewise_linear_distribution::intervals,densities + .SH Synopsis std::vector intervals() const; \fB(1)\fP \fI(since C++11)\fP std::vector densities() const; \fB(2)\fP \fI(since C++11)\fP @@ -21,4 +24,4 @@ .SH Complexity - Constant. + Linear in the number of intervals in this object. diff --git a/man/std::piecewise_linear_distribution::max.3 b/man/std::piecewise_linear_distribution::max.3 index 8f867e332..668cafbc0 100644 --- a/man/std::piecewise_linear_distribution::max.3 +++ b/man/std::piecewise_linear_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::max \- std::piecewise_linear_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::piecewise_linear_distribution::min.3 b/man/std::piecewise_linear_distribution::min.3 index 84a8ecaa1..44f6b7bb7 100644 --- a/man/std::piecewise_linear_distribution::min.3 +++ b/man/std::piecewise_linear_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::min \- std::piecewise_linear_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::piecewise_linear_distribution::operator().3 b/man/std::piecewise_linear_distribution::operator().3 index 6b55c9c53..9dd1b5336 100644 --- a/man/std::piecewise_linear_distribution::operator().3 +++ b/man/std::piecewise_linear_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::operator() \- std::piecewise_linear_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::piecewise_linear_distribution::param.3 b/man/std::piecewise_linear_distribution::param.3 index a3e344c49..5adf4a710 100644 --- a/man/std::piecewise_linear_distribution::param.3 +++ b/man/std::piecewise_linear_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::param \- std::piecewise_linear_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::piecewise_linear_distribution::piecewise_linear_distribution.3 b/man/std::piecewise_linear_distribution::piecewise_linear_distribution.3 index 36102427b..fe55eb1ea 100644 --- a/man/std::piecewise_linear_distribution::piecewise_linear_distribution.3 +++ b/man/std::piecewise_linear_distribution::piecewise_linear_distribution.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::piecewise_linear_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::piecewise_linear_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::piecewise_linear_distribution \- std::piecewise_linear_distribution::piecewise_linear_distribution + .SH Synopsis piecewise_linear_distribution(); \fB(1)\fP \fI(since C++11)\fP template< class InputIt1, class InputIt2 > @@ -23,12 +26,12 @@ Constructs new piecewise linear distribution object. 1) Constructs a distribution object with n = 1, ρ0 = 1, b0 = 0, and b1 = 1. - 2) Constructs a distribution object from iterators over the and interval sequence + 2) Constructs a distribution object from iterators over the interval sequence [first_i, last_i) and a matching weight sequence starting at first_w. 3) Constructs a distribution object where the intervals are taken from the initializer list ilist and the weights generated by the function fw. 4) Constructs a distribution object with the fw intervals distributed uniformly over - [xmin, xmax] + [xmin, xmax]. 5) Constructs a distribution object initialized with the parameters param. .SH Parameters @@ -36,7 +39,7 @@ first_i - iterator initialized to the start of the interval sequence last_i - iterator initialized to one-past-the-end of the interval sequence first_w - iterator initialized to the start of the density (weight) sequence - ilist_i - initializer_list yielding the interval sequence + ilist - initializer_list yielding the interval sequence fw - double(double) function yielding the densities nw - the number of densities xmin - the lower bound of the interval sequence diff --git a/man/std::piecewise_linear_distribution::reset.3 b/man/std::piecewise_linear_distribution::reset.3 index 9db0c6e3c..24af99158 100644 --- a/man/std::piecewise_linear_distribution::reset.3 +++ b/man/std::piecewise_linear_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::piecewise_linear_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::piecewise_linear_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::piecewise_linear_distribution::reset \- std::piecewise_linear_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N.3 b/man/std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N.3 index 31c7f1ab9..754c790f3 100644 --- a/man/std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N.3 +++ b/man/std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N.3 @@ -1,78 +1,101 @@ -.TH std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N \- std::placeholders::_1,std::placeholders::_2,...,std::placeholders::_N + .SH Synopsis Defined in header - extern /*unspecified*/ _1; + /*see below*/ _1; - extern /*unspecified*/ _2; + /*see below*/ _2; . . - extern /*unspecified*/ _N; + /*see below*/ _N; - The std::placeholders namespace contains the placeholder objects [_1, . . . _N] - where N is an implementation defined maximum number. + The std::placeholders namespace contains the placeholder objects [_1, ..., _N] where + N is an implementation defined maximum number. When used as an argument in a std::bind expression, the placeholder objects are stored in the generated function object, and when that function object is invoked with unbound arguments, each placeholder _N is replaced by the corresponding Nth unbound argument. + Each placeholder is declared as if by extern /*unspecified*/ _1;. \fI(until C++17)\fP + Implementations are encouraged to declare the placeholders as if by + inline constexpr /*unspecified*/ _1;, although declaring them by \fI(since C++17)\fP + extern /*unspecified*/ _1; is still allowed by the standard. + The types of the placeholder objects are DefaultConstructible and CopyConstructible, their default copy/move constructors do not throw exceptions, and for any - placeholder _N, the type std::is_placeholder is defined and is derived - from std::integral_constant. + placeholder _N, the type std::is_placeholder is defined, where + std::is_placeholder is derived from std::integral_constant. .SH Example - The following code shows the creation of function objects with a placeholder - argument. + The following code shows the creation of function objects with placeholder + arguments. + - // Run this code #include - #include #include - + #include + void goodbye(const std::string& s) { std::cout << "Goodbye " << s << '\\n'; } - - class Object { + + class Object + { public: void hello(const std::string& s) { std::cout << "Hello " << s << '\\n'; } }; - - int main(int argc, char* argv[]) + + int main() { - typedef std::function ExampleFunction; + using namespace std::placeholders; + + using ExampleFunction = std::function; Object instance; std::string str("World"); - ExampleFunction f = std::bind(&Object::hello, &instance, - std::placeholders::_1); - - // equivalent to instance.hello(str) - f(str); + + ExampleFunction f = std::bind(&Object::hello, &instance, _1); + f(str); // equivalent to instance.hello(str) + f = std::bind(&goodbye, std::placeholders::_1); - - // equivalent to goodbye(str) - f(str); - return 0; + f(str); // equivalent to goodbye(str) + + auto lambda = [](std::string pre, char o, int rep, std::string post) + { + std::cout << pre; + while (rep-- > 0) + std::cout << o; + std::cout << post << '\\n'; + }; + + // binding the lambda: + std::function g = + std::bind(&decltype(lambda)::operator(), &lambda, _1, _2, _3, _4); + g("G", 'o', 'o'-'g', "gol"); } .SH Output: Hello World Goodbye World + Goooooooogol .SH See also bind binds one or more arguments to a function object - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP is_placeholder indicates that an object is a standard placeholder or can be used as \fI(C++11)\fP one - \fI(class template)\fP + \fI(class template)\fP + ignore placeholder to skip an element when unpacking a tuple using tie + \fI(C++11)\fP (constant) diff --git a/man/std::plus.3 b/man/std::plus.3 index 8ab11658f..34260fdd5 100644 --- a/man/std::plus.3 +++ b/man/std::plus.3 @@ -1,4 +1,7 @@ -.TH std::plus 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::plus 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::plus \- std::plus + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -15,23 +18,26 @@ not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing x + y deducing argument and - plus return types - \fI(class template specialization)\fP + plus function object implementing x + y deducing parameter and + \fI(C++14)\fP return types + \fI(class template specialization)\fP .SH Member types - Type Definition - result_type T - first_argument_type T - second_argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) T + first_argument_type (deprecated in C++17)(removed in C++20) T + second_argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Member functions operator() returns the sum of two arguments - \fI(public member function)\fP + \fI(public member function)\fP - std::plus::operator() +std::plus::operator() T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP @@ -48,11 +54,11 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr T operator()(const T &lhs, const T &rhs) const + constexpr T operator()(const T& lhs, const T& rhs) const { return lhs + rhs; } diff --git a/man/std::plus.3 b/man/std::plus.3 deleted file mode 100644 index 351e7c46e..000000000 --- a/man/std::plus.3 +++ /dev/null @@ -1,63 +0,0 @@ -.TH std::plus 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class plus; - - std::plus<> is a specialization of std::plus with parameter and return type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() returns the sum of two arguments - \fI(public member function)\fP - - std::plus<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) + std::forward(rhs)); - - Returns the sum of lhs and rhs. - -.SH Parameters - - lhs, rhs - values to sum - -.SH Return value - - The result of lhs + rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - -// Run this code - - #include - #include - - int main() - { - std::string a = "Hello "; - const char* b = "world"; - std::cout << std::plus<>{}(a, b) << '\\n'; - } - -.SH Output: - - Hello world diff --git a/man/std::pmr::get_default_resource.3 b/man/std::pmr::get_default_resource.3 new file mode 100644 index 000000000..a6f0dc59c --- /dev/null +++ b/man/std::pmr::get_default_resource.3 @@ -0,0 +1,30 @@ +.TH std::pmr::get_default_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::get_default_resource \- std::pmr::get_default_resource + +.SH Synopsis + Defined in header + std::pmr::memory_resource* get_default_resource() noexcept; \fI(since C++17)\fP + + Gets the default memory resource pointer. + + The default memory resource pointer is used by certain facilities when an explicit + memory resource is not supplied. The initial default memory resource pointer is the + return value of std::pmr::new_delete_resource. + + This function is thread-safe. Previous call to std::pmr::set_default_resource + synchronizes with (see std::memory_order) the subsequent + std::pmr::get_default_resource calls. + +.SH Return value + + Returns the value of the default memory resource pointer. + +.SH See also + + set_default_resource sets the default std::pmr::memory_resource + \fI(C++17)\fP \fI(function)\fP + returns a static program-wide std::pmr::memory_resource that + new_delete_resource uses the global operator new and operator delete to allocate + \fI(C++17)\fP and deallocate memory + \fI(function)\fP diff --git a/man/std::pmr::memory_resource.3 b/man/std::pmr::memory_resource.3 new file mode 100644 index 000000000..46cfa3461 --- /dev/null +++ b/man/std::pmr::memory_resource.3 @@ -0,0 +1,44 @@ +.TH std::pmr::memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource \- std::pmr::memory_resource + +.SH Synopsis + Defined in header + class memory_resource; \fI(since C++17)\fP + + The class std::pmr::memory_resource is an abstract interface to an unbounded set of + classes encapsulating memory resources. + +.SH Member functions + + constructor constructs a new memory_resource + (implicitly declared) \fI(public member function)\fP + destructor destructs a memory_resource + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= Implicitly declared copy assignment operator + (implicitly declared) \fI(public member function)\fP +.SH Public member functions + allocate allocates memory + \fI(public member function)\fP + deallocate deallocates memory + \fI(public member function)\fP + is_equal compare for equality with another memory_resource + \fI(public member function)\fP + Private member functions + do_allocate allocates memory + \fB[virtual]\fP (virtual private member function) + do_deallocate deallocates memory + \fB[virtual]\fP (virtual private member function) + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP (virtual private member function) + + Non-member-functions + + operator== compare two memory_resources + operator!= \fI(function)\fP + (removed in C++20) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_memory_resource 201603L \fI(C++17)\fP std::pmr::memory_resource diff --git a/man/std::pmr::memory_resource::allocate.3 b/man/std::pmr::memory_resource::allocate.3 new file mode 100644 index 000000000..37ca8d81a --- /dev/null +++ b/man/std::pmr::memory_resource::allocate.3 @@ -0,0 +1,34 @@ +.TH std::pmr::memory_resource::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::allocate \- std::pmr::memory_resource::allocate + +.SH Synopsis + void* allocate( std::size_t bytes, \fI(since C++17)\fP + std::size_t alignment = alignof(std::max_align_t) ); \fI(until C++20)\fP + [[nodiscard]] void* allocate( std::size_t bytes, + std::size_t alignment = \fI(since C++20)\fP + alignof(std::max_align_t) ); + + Allocates storage with a size of at least bytes bytes, aligned to the specified + alignment. + + Equivalent to return do_allocate(bytes, alignment);. + +.SH Exceptions + + Throws an exception if storage of the requested size and alignment cannot be + obtained. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2843 ??? over-alignment was allowed to be alignment must be + unsupported honoured + +.SH See also + + do_allocate allocates memory + \fB[virtual]\fP (virtual private member function) diff --git a/man/std::pmr::memory_resource::deallocate.3 b/man/std::pmr::memory_resource::deallocate.3 new file mode 100644 index 000000000..c71ec74f0 --- /dev/null +++ b/man/std::pmr::memory_resource::deallocate.3 @@ -0,0 +1,25 @@ +.TH std::pmr::memory_resource::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::deallocate \- std::pmr::memory_resource::deallocate + +.SH Synopsis + void deallocate( void* p, + + std::size_t bytes, \fI(since C++17)\fP + + std::size_t alignment = alignof(std::max_align_t) ); + + Deallocates the storage pointed to by p. p shall have been returned by a prior call + to allocate(bytes, alignment) on a memory_resource that compares equal to *this, and + the storage it points to shall not yet have been deallocated. + + Equivalent to do_deallocate(p, bytes, alignment);. + +.SH Exceptions + + Throws nothing. + +.SH See also + + do_deallocate deallocates memory + \fB[virtual]\fP (virtual private member function) diff --git a/man/std::pmr::memory_resource::do_allocate.3 b/man/std::pmr::memory_resource::do_allocate.3 new file mode 100644 index 000000000..4eff9218b --- /dev/null +++ b/man/std::pmr::memory_resource::do_allocate.3 @@ -0,0 +1,31 @@ +.TH std::pmr::memory_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::do_allocate \- std::pmr::memory_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t alignment ) \fI(since C++17)\fP + = 0; + + Allocates storage with a size of at least bytes bytes, aligned to the specified + alignment. + + alignment shall be a power of two. + +.SH Exceptions + + Throws an exception if storage of the requested size and alignment cannot be + obtained. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2843 C++17 handling of unsupported alignment throws an exception + contradictory + +.SH See also + + allocate allocates memory + \fI(public member function)\fP diff --git a/man/std::pmr::memory_resource::do_deallocate.3 b/man/std::pmr::memory_resource::do_deallocate.3 new file mode 100644 index 000000000..bd7675be9 --- /dev/null +++ b/man/std::pmr::memory_resource::do_deallocate.3 @@ -0,0 +1,22 @@ +.TH std::pmr::memory_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::do_deallocate \- std::pmr::memory_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, std::size_t \fI(since C++17)\fP + alignment ) = 0; + + Deallocates the storage pointed to by p. + + p must have been returned by a prior call to allocate(bytes, alignment) on a + memory_resource that compares equal to *this, and the storage it points to must not + yet have been deallocated, otherwise the behavior is undefined. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate deallocates memory + \fI(public member function)\fP diff --git a/man/std::pmr::memory_resource::do_is_equal.3 b/man/std::pmr::memory_resource::do_is_equal.3 new file mode 100644 index 000000000..a7c72392a --- /dev/null +++ b/man/std::pmr::memory_resource::do_is_equal.3 @@ -0,0 +1,24 @@ +.TH std::pmr::memory_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::do_is_equal \- std::pmr::memory_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const std::pmr::memory_resource& other ) \fI(since C++17)\fP + const noexcept = 0; + + Compares *this for equality with other. + + Two memory_resources compare equal if and only if memory allocated from one + memory_resource can be deallocated from the other and vice versa. + +.SH Notes + + The most-derived type of other may not match the most derived type of *this. A + derived class implementation therefore must typically check whether the most derived + types of *this and other match using dynamic_cast, and immediately return false if + the cast fails. + +.SH See also + + is_equal compare for equality with another memory_resource + \fI(public member function)\fP diff --git a/man/std::pmr::memory_resource::is_equal.3 b/man/std::pmr::memory_resource::is_equal.3 new file mode 100644 index 000000000..7b9c21f97 --- /dev/null +++ b/man/std::pmr::memory_resource::is_equal.3 @@ -0,0 +1,17 @@ +.TH std::pmr::memory_resource::is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::is_equal \- std::pmr::memory_resource::is_equal + +.SH Synopsis + bool is_equal( const memory_resource& other ) const noexcept; \fI(since C++17)\fP + + Compares *this for equality with other. Two memory_resources compare equal if and + only if memory allocated from one memory_resource can be deallocated from the other + and vice versa. + + Equivalent to return do_is_equal(other);. + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP (virtual private member function) diff --git a/man/std::pmr::memory_resource::memory_resource.3 b/man/std::pmr::memory_resource::memory_resource.3 new file mode 100644 index 000000000..599a0674d --- /dev/null +++ b/man/std::pmr::memory_resource::memory_resource.3 @@ -0,0 +1,12 @@ +.TH std::pmr::memory_resource::memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::memory_resource::memory_resource \- std::pmr::memory_resource::memory_resource + +.SH Synopsis + memory_resource() = default; \fB(1)\fP \fI(since C++17)\fP + (implicitly declared) + memory_resource( const memory_resource& ) = default; \fB(2)\fP \fI(since C++17)\fP + (implicitly declared) + + 1) Implicitly declared default constructor. + 2) Implicitly declared copy constructor. diff --git a/man/std::pmr::monotonic_buffer_resource.3 b/man/std::pmr::monotonic_buffer_resource.3 new file mode 100644 index 000000000..e5b26dc96 --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource.3 @@ -0,0 +1,130 @@ +.TH std::pmr::monotonic_buffer_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource \- std::pmr::monotonic_buffer_resource + +.SH Synopsis + Defined in header + class monotonic_buffer_resource : public std::pmr::memory_resource; \fI(since C++17)\fP + + The class std::pmr::monotonic_buffer_resource is a special-purpose memory resource + class that releases the allocated memory only when the resource is destroyed. It is + intended for very fast memory allocations in situations where memory is used to + build up a few objects and then is released all at once. + + monotonic_buffer_resource can be constructed with an initial buffer. If there is no + initial buffer, or if the buffer is exhausted, additional buffers are obtained from + an upstream memory resource supplied at construction. The size of buffers obtained + follows a geometric progression. + + monotonic_buffer_resource is not thread-safe. + +.SH Member functions + + constructor constructs a monotonic_buffer_resource + \fI(public member function)\fP + destructor destroys a monotonic_buffer_resource, releasing all allocated + \fB[virtual]\fP memory + \fI(virtual public member function)\fP + operator= copy assignment operator is deleted. monotonic_buffer_resource is + [deleted] not copy assignable + \fI(public member function)\fP +.SH Public member functions + release release all allocated memory + \fI(public member function)\fP + upstream_resource returns a pointer to the upstream memory resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocate memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate no-op + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another std::pmr::memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Example + + The program measures the time of creating huge double-linked lists using the + following allocators: + + * default standard allocator, + * default pmr allocator, + * pmr allocator with monotonic resource but without explicit memory buffer, + * pmr allocator with monotonic resource and external memory buffer (on stack). + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + auto benchmark(Func test_func, int iterations) + { + const auto start = std::chrono::system_clock::now(); + while (iterations-- > 0) + test_func(); + const auto stop = std::chrono::system_clock::now(); + const auto secs = std::chrono::duration(stop - start); + return secs.count(); + } + + int main() + { + constexpr int iterations{100}; + constexpr int total_nodes{2'00'000}; + + auto default_std_alloc = [total_nodes] + { + std::list list; + for (int i{}; i != total_nodes; ++i) + list.push_back(i); + }; + + auto default_pmr_alloc = [total_nodes] + { + std::pmr::list list; + for (int i{}; i != total_nodes; ++i) + list.push_back(i); + }; + + auto pmr_alloc_no_buf = [total_nodes] + { + std::pmr::monotonic_buffer_resource mbr; + std::pmr::polymorphic_allocator pa{&mbr}; + std::pmr::list list{pa}; + for (int i{}; i != total_nodes; ++i) + list.push_back(i); + }; + + auto pmr_alloc_and_buf = [total_nodes] + { + std::array buffer; // enough to fit in all nodes + std::pmr::monotonic_buffer_resource mbr{buffer.data(), buffer.size()}; + std::pmr::polymorphic_allocator pa{&mbr}; + std::pmr::list list{pa}; + for (int i{}; i != total_nodes; ++i) + list.push_back(i); + }; + + const double t1 = benchmark(default_std_alloc, iterations); + const double t2 = benchmark(default_pmr_alloc, iterations); + const double t3 = benchmark(pmr_alloc_no_buf , iterations); + const double t4 = benchmark(pmr_alloc_and_buf, iterations); + + std::cout << std::fixed << std::setprecision(3) + << "t1 (default std alloc): " << t1 << " sec; t1/t1: " << t1/t1 << '\\n' + << "t2 (default pmr alloc): " << t2 << " sec; t1/t2: " << t1/t2 << '\\n' + << "t3 (pmr alloc no buf): " << t3 << " sec; t1/t3: " << t1/t3 << '\\n' + << "t4 (pmr alloc and buf): " << t4 << " sec; t1/t4: " << t1/t4 << '\\n'; + } + +.SH Possible output: + + t1 (default std alloc): 0.720 sec; t1/t1: 1.000 + t2 (default pmr alloc): 0.915 sec; t1/t2: 0.787 + t3 (pmr alloc no buf): 0.370 sec; t1/t3: 1.945 + t4 (pmr alloc and buf): 0.247 sec; t1/t4: 2.914 diff --git a/man/std::pmr::monotonic_buffer_resource::do_allocate.3 b/man/std::pmr::monotonic_buffer_resource::do_allocate.3 new file mode 100644 index 000000000..a011886cb --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::do_allocate.3 @@ -0,0 +1,36 @@ +.TH std::pmr::monotonic_buffer_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::do_allocate \- std::pmr::monotonic_buffer_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t alignment \fI(since C++17)\fP + ); + + Allocates storage. + + If the current buffer has sufficient unused space to fit a block with the specified + size and alignment, allocates the return block from the current buffer. + + Otherwise, this function allocates a new buffer by calling + upstream_resource()->allocate(n, m), where n is not less than the greater of bytes + and the next buffer size and m is not less than alignment. It sets the new buffer as + the current buffer, increases the next buffer size by an implementation-defined + growth factor (which is not necessarily integral), and then allocates the return + block from the newly allocated buffer. + +.SH Return value + + A pointer to allocated storage of at least bytes bytes in size, aligned to the + specified alignment if such alignment is supported, and to alignof(std::max_align_t) + otherwise. + +.SH Exceptions + + Throws nothing unless calling allocate() on the upstream memory resource throws. + +.SH See also + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP + do_allocate allocates memory + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::monotonic_buffer_resource::do_deallocate.3 b/man/std::pmr::monotonic_buffer_resource::do_deallocate.3 new file mode 100644 index 000000000..667c61a8d --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::do_deallocate.3 @@ -0,0 +1,21 @@ +.TH std::pmr::monotonic_buffer_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::do_deallocate \- std::pmr::monotonic_buffer_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, std::size_t \fI(since C++17)\fP + alignment ); + + This function has no effect. Memory used by a monotonic_buffer_resource, as its name + indicates, increases monotonically until the resource is destroyed. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP + do_deallocate deallocates memory + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::monotonic_buffer_resource::do_is_equal.3 b/man/std::pmr::monotonic_buffer_resource::do_is_equal.3 new file mode 100644 index 000000000..961a8cc43 --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::do_is_equal.3 @@ -0,0 +1,27 @@ +.TH std::pmr::monotonic_buffer_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::do_is_equal \- std::pmr::monotonic_buffer_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const std::pmr::memory_resource& other ) \fI(since C++17)\fP + const noexcept; + + Compare *this with other for identity - memory allocated using a + monotonic_buffer_resource can only be deallocated using that same resource. + +.SH Return value + + this == &other + + Defect report + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3000 C++17 unnecessary dynamic_cast was performed removed + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::monotonic_buffer_resource::monotonic_buffer_resource.3 b/man/std::pmr::monotonic_buffer_resource::monotonic_buffer_resource.3 new file mode 100644 index 000000000..472c64e39 --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::monotonic_buffer_resource.3 @@ -0,0 +1,40 @@ +.TH std::pmr::monotonic_buffer_resource::monotonic_buffer_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::monotonic_buffer_resource \- std::pmr::monotonic_buffer_resource::monotonic_buffer_resource + +.SH Synopsis + monotonic_buffer_resource(); \fB(1)\fP \fI(since C++17)\fP + explicit monotonic_buffer_resource( std::pmr::memory_resource* \fB(2)\fP \fI(since C++17)\fP + upstream ); + explicit monotonic_buffer_resource( std::size_t initial_size ); \fB(3)\fP \fI(since C++17)\fP + monotonic_buffer_resource( std::size_t initial_size, \fB(4)\fP \fI(since C++17)\fP + std::pmr::memory_resource* upstream ); + monotonic_buffer_resource( void* buffer, std::size_t buffer_size \fB(5)\fP \fI(since C++17)\fP + ); + monotonic_buffer_resource( void* buffer, std::size_t buffer_size, \fB(6)\fP \fI(since C++17)\fP + std::pmr::memory_resource* upstream ); + monotonic_buffer_resource( const monotonic_buffer_resource& ) = \fB(7)\fP \fI(since C++17)\fP + delete; + + Constructs a monotonic_buffer_resource. The constructors not taking an upstream + memory resource pointer use the return value of std::pmr::get_default_resource as + the upstream memory resource. + + 1,2) Sets the current buffer to null and the next buffer size to an + implementation-defined size. + 3,4) Sets the current buffer to null and the next buffer size to a size no smaller + than initial_size. + 5,6) Sets the current buffer to buffer and the next buffer size to buffer_size (but + not less than 1). Then increase the next buffer size by an implementation-defined + growth factor (which does not have to be integral). + 7) Copy constructor is deleted. + +.SH Parameters + + upstream - the upstream memory resource to use; must point to a valid memory + resource + initial_size - the minimum size of the first buffer to allocate; must be greater + than zero + buffer - the initial buffer to use + buffer_size - the size of the initial buffer; cannot be greater than the number of + bytes in buffer diff --git a/man/std::pmr::monotonic_buffer_resource::release.3 b/man/std::pmr::monotonic_buffer_resource::release.3 new file mode 100644 index 000000000..ba3b60035 --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::release.3 @@ -0,0 +1,27 @@ +.TH std::pmr::monotonic_buffer_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::release \- std::pmr::monotonic_buffer_resource::release + +.SH Synopsis + void release(); \fI(since C++17)\fP + + Releases all allocated memory by calling the deallocate function on the upstream + memory resource as necessary. Resets current buffer and next buffer size to their + initial values at construction. + + Memory is released back to the upstream resource even if deallocate has not been + called for some of the allocated blocks. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3120 C++17 release might not make initial buffer reusable required to do so + if provided + +.SH See also + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::monotonic_buffer_resource::upstream_resource.3 b/man/std::pmr::monotonic_buffer_resource::upstream_resource.3 new file mode 100644 index 000000000..96ba32c15 --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::upstream_resource.3 @@ -0,0 +1,14 @@ +.TH std::pmr::monotonic_buffer_resource::upstream_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::upstream_resource \- std::pmr::monotonic_buffer_resource::upstream_resource + +.SH Synopsis + std::pmr::memory_resource* upstream_resource() const; \fI(since C++17)\fP + + Returns a pointer to the upstream memory resource. This is the same value as the + upstream argument passed to the constructor of this object. + +.SH See also + + constructor constructs a monotonic_buffer_resource + \fI(public member function)\fP diff --git a/man/std::pmr::monotonic_buffer_resource::~monotonic_buffer_resource.3 b/man/std::pmr::monotonic_buffer_resource::~monotonic_buffer_resource.3 new file mode 100644 index 000000000..62898cfd3 --- /dev/null +++ b/man/std::pmr::monotonic_buffer_resource::~monotonic_buffer_resource.3 @@ -0,0 +1,15 @@ +.TH std::pmr::monotonic_buffer_resource::~monotonic_buffer_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::monotonic_buffer_resource::~monotonic_buffer_resource \- std::pmr::monotonic_buffer_resource::~monotonic_buffer_resource + +.SH Synopsis + virtual ~monotonic_buffer_resource(); \fI(since C++17)\fP + + Destroys a monotonic_buffer_resource. + + Deallocates all memory owned by this resource by calling this->release(). + +.SH See also + + release release all allocated memory + \fI(public member function)\fP diff --git a/man/std::pmr::new_delete_resource.3 b/man/std::pmr::new_delete_resource.3 new file mode 100644 index 000000000..e8f780bc5 --- /dev/null +++ b/man/std::pmr::new_delete_resource.3 @@ -0,0 +1,21 @@ +.TH std::pmr::new_delete_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::new_delete_resource \- std::pmr::new_delete_resource + +.SH Synopsis + Defined in header + std::pmr::memory_resource* new_delete_resource() noexcept; \fI(since C++17)\fP + + Returns a pointer to a memory_resource that uses the global operator new and + operator delete to allocate memory. + +.SH Return value + + Returns a pointer p to a static storage duration object of a type derived from + std::pmr::memory_resource, with the following properties: + + * its allocate() function uses ::operator new to allocate memory; + * its deallocate() function uses ::operator delete to deallocate memory; + * for any memory_resource r, p->is_equal(r) returns &r == p. + + The same value is returned every time this function is called. diff --git a/man/std::pmr::null_memory_resource.3 b/man/std::pmr::null_memory_resource.3 new file mode 100644 index 000000000..4c292fce3 --- /dev/null +++ b/man/std::pmr::null_memory_resource.3 @@ -0,0 +1,73 @@ +.TH std::pmr::null_memory_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::null_memory_resource \- std::pmr::null_memory_resource + +.SH Synopsis + Defined in header + std::pmr::memory_resource* null_memory_resource() noexcept; \fI(since C++17)\fP + + Returns a pointer to a memory_resource that doesn't perform any allocation. + +.SH Return value + + Returns a pointer p to a static storage duration object of a type derived from + std::pmr::memory_resource, with the following properties: + + * its allocate() function always throws std::bad_alloc; + * its deallocate() function has no effect; + * for any memory_resource r, p->is_equal(r) returns &r == p. + + The same value is returned every time this function is called. + +.SH Example + + The program demos the main usage of null_memory_resource: ensure that a memory pool + which requires memory allocated on the stack will NOT allocate memory on the heap if + it needs more memory. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + // allocate memory on the stack + std::array buf; + + // without fallback memory allocation on heap + std::pmr::monotonic_buffer_resource pool{buf.data(), buf.size(), + std::pmr::null_memory_resource()}; + + // allocate too much memory + std::pmr::unordered_map coll{&pool}; + try + { + for (std::size_t i = 0; i < buf.size(); ++i) + { + coll.emplace(i, "just a string with number " + std::to_string(i)); + + if (i && i % 50 == 0) + std::clog << "size: " << i << "...\\n"; + } + } + catch (const std::bad_alloc& e) + { + std::cerr << e.what() << '\\n'; + } + + std::cout << "size: " << coll.size() << '\\n'; + } + +.SH Possible output: + + size: 50... + size: 100... + size: 150... + std::bad_alloc + size: 183 diff --git a/man/std::pmr::operator==,std::pmr::operator!=.3 b/man/std::pmr::operator==,std::pmr::operator!=.3 new file mode 100644 index 000000000..4d3019eb4 --- /dev/null +++ b/man/std::pmr::operator==,std::pmr::operator!=.3 @@ -0,0 +1,26 @@ +.TH std::pmr::operator==,std::pmr::operator!= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::operator==,std::pmr::operator!= \- std::pmr::operator==,std::pmr::operator!= + +.SH Synopsis + Defined in header + bool operator==( const std::pmr::memory_resource& a, \fB(1)\fP \fI(since C++17)\fP + const std::pmr::memory_resource& b ) noexcept; + bool operator!=( const std::pmr::memory_resource& a, \fB(2)\fP \fI(since C++17)\fP + const std::pmr::memory_resource& b ) noexcept; \fI(until C++20)\fP + + Compares the memory_resources a and b for equality. Two memory_resources compare + equal if and only if memory allocated from one memory_resource can be deallocated + from the other and vice versa. + + The != operator is synthesized from operator==. \fI(since C++20)\fP + +.SH Return value + + 1) &a == &b || a.is_equal(b) + 2) !(a == b) + +.SH See also + + is_equal compare for equality with another memory_resource + \fI(public member function)\fP diff --git a/man/std::pmr::polymorphic_allocator.3 b/man/std::pmr::polymorphic_allocator.3 new file mode 100644 index 000000000..df5a3dff3 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator.3 @@ -0,0 +1,95 @@ +.TH std::pmr::polymorphic_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator \- std::pmr::polymorphic_allocator + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + class polymorphic_allocator; \fI(until C++20)\fP + template< class T = std::byte > \fI(since C++20)\fP + class polymorphic_allocator; + + The class template std::pmr::polymorphic_allocator is an Allocator which exhibits + different allocation behavior depending upon the std::pmr::memory_resource from + which it is constructed. Since memory_resource uses runtime polymorphism to manage + allocations, different container instances with polymorphic_allocator as their + static allocator type are interoperable, but can behave as if they had different + allocator types. + + All specializations of polymorphic_allocator meet the allocator completeness + requirements. + + The polymorphic_allocator::construct member function does uses-allocator + construction, so that the elements of a container using a polymorphic_allocator will + use that same allocator for their own allocations. For example, a + std::pmr::vector will use the same memory_resource for the + vector's storage and each string's storage. + + For non-polymorphic allocators, similar propagation can be achieved with the help of + std::scoped_allocator_adaptor. + +.SH Member types + + Member type definition + value_type T + +.SH Member functions + + constructor constructs a polymorphic_allocator + \fI(public member function)\fP + destructor implicitly declared destructor + (implicitly declared) \fI(public member function)\fP + operator= copy assignment operator is deleted + [deleted] \fI(public member function)\fP +.SH Public member functions + allocate allocate memory + \fI(public member function)\fP + deallocate deallocate memory + \fI(public member function)\fP + construct constructs an object in allocated storage + \fI(public member function)\fP + destroy destroys an object in allocated storage + (deprecated in C++20) \fI(public member function)\fP + (undeprecated in C++26) + allocate_bytes allocate raw aligned memory from the + (C++20) underlying resource + \fI(public member function)\fP + deallocate_bytes free raw memory obtained from allocate_bytes + (C++20) \fI(public member function)\fP + allocate_object allocates raw memory suitable for an object or + (C++20) an array + \fI(public member function)\fP + deallocate_object frees raw memory obtained by allocate_object + (C++20) \fI(public member function)\fP + new_object allocates and constructs an object + (C++20) \fI(public member function)\fP + delete_object destroys and deallocates an object + (C++20) \fI(public member function)\fP + create a new polymorphic_allocator for use by + select_on_container_copy_construction a container's copy constructor + \fI(public member function)\fP + returns a pointer to the underlying memory + resource resource + \fI(public member function)\fP + +.SH Non-member functions + + operator== compare two polymorphic_allocators + operator!= \fI(function)\fP + (removed in C++20) + +.SH Notes + + polymorphic_allocator does not propagate on container copy assignment, move + assignment, or swap. As a result, move assignment of a polymorphic_allocator-using + container can throw, and swapping two polymorphic_allocator-using containers whose + allocators do not compare equal results in undefined behavior. + + Feature-test macro Value Std Feature + __cpp_lib_polymorphic_allocator 201902L (C++20) std::pmr::polymorphic_allocator<> as + a vocabulary type + +.SH See also + + memory_resource an abstract interface for classes that encapsulate memory resources + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::pmr::polymorphic_allocator::allocate.3 b/man/std::pmr::polymorphic_allocator::allocate.3 new file mode 100644 index 000000000..9595d8729 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::allocate.3 @@ -0,0 +1,50 @@ +.TH std::pmr::polymorphic_allocator::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::allocate \- std::pmr::polymorphic_allocator::allocate + +.SH Synopsis + T* allocate( std::size_t n ); \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] T* allocate( std::size_t n ); \fI(since C++20)\fP + + Allocates storage for n objects of type T using the underlying memory resource. + Equivalent to return static_cast(resource()->allocate(n * sizeof(T), + alignof(T)));. + +.SH Parameters + + n - the number of objects to allocate storage for + +.SH Return value + + A pointer to the allocated storage. + +.SH Exceptions + + Throws std::bad_array_new_length if n > std::numeric_limits::max() / + sizeof(T); may also throw any exceptions thrown by the call to resource()->allocate. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3038 C++17 allocate might allocate storage of wrong throws length_error + size instead + LWG 3237 C++17 the exception thrown by allocate was made consistent + inconsistent with std::allocator::allocate + +.SH See also + + allocate_bytes allocate raw aligned memory from the underlying resource + (C++20) \fI(public member function)\fP + allocate_object allocates raw memory suitable for an object or an array + (C++20) \fI(public member function)\fP + new_object allocates and constructs an object + (C++20) \fI(public member function)\fP + allocate allocates uninitialized storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::allocate_bytes.3 b/man/std::pmr::polymorphic_allocator::allocate_bytes.3 new file mode 100644 index 000000000..d7ef823ab --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::allocate_bytes.3 @@ -0,0 +1,47 @@ +.TH std::pmr::polymorphic_allocator::allocate_bytes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::allocate_bytes \- std::pmr::polymorphic_allocator::allocate_bytes + +.SH Synopsis + [[nodiscard]] void* allocate_bytes( std::size_t nbytes, + std::size_t alignment = \fI(since C++20)\fP + alignof(std::max_align_t) ); + + Allocates nbytes bytes of storage at specified alignment alignment using the + underlying memory resource. Equivalent to return resource()->allocate(nbytes, + alignment);. + +.SH Parameters + + nbytes - the number of bytes to allocate + alignment - the alignment to use + +.SH Return value + + A pointer to the allocated storage. + +.SH Notes + + This function was introduced for use with the fully-specialized allocator + std::pmr::polymorphic_allocator<>, but it may be useful in any specialization. + + The return type is void* (rather than, e.g., std::byte*) to support conversion to an + arbitrary pointer type U* by static_cast. + +.SH Exceptions + + May throw any exceptions thrown by the call to resource()->allocate. + +.SH See also + + allocate_object allocates raw memory suitable for an object or an array + (C++20) \fI(public member function)\fP + new_object allocates and constructs an object + (C++20) \fI(public member function)\fP + allocate allocate memory + \fI(public member function)\fP + allocate allocates uninitialized storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::allocate_object.3 b/man/std::pmr::polymorphic_allocator::allocate_object.3 new file mode 100644 index 000000000..e601549ad --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::allocate_object.3 @@ -0,0 +1,50 @@ +.TH std::pmr::polymorphic_allocator::allocate_object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::allocate_object \- std::pmr::polymorphic_allocator::allocate_object + +.SH Synopsis + template< class U > \fI(since C++20)\fP + [[nodiscard]] U* allocate_object( std::size_t n = 1 ); + + Allocates storage for n objects of type U using the underlying memory resource. + + If std::numeric_limits::max() / sizeof(U) < n, throws + std::bad_array_new_length, otherwise equivalent to return + static_cast(allocate_bytes(n * sizeof(U), alignof(U)));. + +.SH Parameters + + n - the number of objects to allocate storage for + +.SH Return value + + A pointer to the allocated storage. + +.SH Notes + + This function was introduced for use with the fully-specialized allocator + std::pmr::polymorphic_allocator<>, but it may be useful in any specialization as a + shortcut to avoid having to rebind from std::pmr::polymorphic_allocator to + std::pmr::polymorphic_allocator. + + Since U is not deduced, it must be provided as a template argument when calling this + function. + +.SH Exceptions + + Throws std::bad_array_new_length if n > std::numeric_limits::max() / + sizeof(U); may also be any exceptions thrown by the call to resource()->allocate. + +.SH See also + + allocate_bytes allocate raw aligned memory from the underlying resource + (C++20) \fI(public member function)\fP + new_object allocates and constructs an object + (C++20) \fI(public member function)\fP + allocate allocate memory + \fI(public member function)\fP + allocate allocates uninitialized storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::construct.3 b/man/std::pmr::polymorphic_allocator::construct.3 new file mode 100644 index 000000000..aec250b59 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::construct.3 @@ -0,0 +1,121 @@ +.TH std::pmr::polymorphic_allocator::construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::construct \- std::pmr::polymorphic_allocator::construct + +.SH Synopsis + template< class U, class... Args > \fB(1)\fP \fI(since C++17)\fP + void construct( U* p, Args&&... args ); + template< class T1, class T2, class... Args1, class... Args2 > + + void construct( std::pair* p, \fI(since C++17)\fP + std::piecewise_construct_t, \fB(2)\fP \fI(until C++20)\fP + std::tuple x, + + std::tuple y ); + template< class T1, class T2 > \fB(3)\fP \fI(since C++17)\fP + void construct( std::pair* p ); \fI(until C++20)\fP + template< class T1, class T2, class U, class V > \fB(4)\fP \fI(since C++17)\fP + void construct( std::pair* p, U&& x, V&& y ); \fI(until C++20)\fP + template< class T1, class T2, class U, class V > \fB(5)\fP \fI(since C++17)\fP + void construct( std::pair* p, const std::pair& xy ); \fI(until C++20)\fP + template< class T1, class T2, class U, class V > \fB(6)\fP \fI(since C++17)\fP + void construct( std::pair* p, std::pair&& xy ); \fI(until C++20)\fP + template< class T1, class T2, class NonPair > \fB(7)\fP \fI(since C++17)\fP + void construct( std::pair* p, NonPair&& non_pair ); \fI(until C++20)\fP + + Constructs an object in allocated, but not initialized storage pointed to by p the + provided constructor arguments. If the object is of type that itself uses + allocators, or if it is std::pair, passes *this down to the constructed object. + + 1) Creates an object of the given type U by means of uses-allocator construction at + the uninitialized memory location indicated by p, using *this as the allocator. + This overload participates in overload resolution only if U is not a specialization + of std::pair. + \fI(until C++20)\fP + +2) First, if either T1 or T2 is allocator-aware, modifies the tuples x and y to include +this->resource(), resulting in the two new tuples xprime and yprime, according to the +following three rules: +2a) if T1 is not allocator-aware (std::uses_allocator::value==false) and std::is_constructible::value==true, then xprime is x, unmodified. +2b) if T1 is allocator-aware (std::uses_allocator::value==true), and its constructor takes an allocator tag +(std::is_constructible::value==true, then xprime is std::tuple_cat(std::make_tuple(std::allocator_arg, +*this), std::move(x)). +2c) if T1 is allocator-aware (std::uses_allocator::value==true), and its constructor takes the allocator as the last +argument (std::is_constructible::value==true), then +xprime is std::tuple_cat(std::move(x), std::make_tuple(*this)). +2d) Otherwise, the program is ill-formed. +Same rules apply to T2 and the replacement of y with yprime. +Once xprime and yprime are constructed, constructs the pair p in allocated storage as if +by ::new((void *) p) pair(std::piecewise_construct, std::move(xprime), +std::move(yprime));. +3) Equivalent to construct(p, std::piecewise_construct, std::tuple<>(), std::tuple<>()), +that is, passes the memory resource on to the pair's member types if they accept them. +4) Equivalent to (until + C++20) +construct(p, std::piecewise_construct, std::forward_as_tuple(std::forward(x)), + std::forward_as_tuple(std::forward(y))) + +5) Equivalent to + +construct(p, std::piecewise_construct, std::forward_as_tuple(xy.first), + std::forward_as_tuple(xy.second)) + +6) Equivalent to + +construct(p, std::piecewise_construct, std::forward_as_tuple(std::forward(xy.first)), + std::forward_as_tuple(std::forward(xy.second))) + +7) This overload participates in overload resolution only if given the exposition-only +function template + +template< class A, class B > +void /*deduce-as-pair*/( const std::pair& ); + +, /*deduce-as-pair*/(non_pair) is ill-formed when considered as an unevaluated operand. +Equivalent to + +construct(p, std::forward(non_pair)); + +.SH Parameters + + p - pointer to allocated, but not initialized storage + args... - the constructor arguments to pass to the constructor of T + x - the constructor arguments to pass to the constructor of T1 + y - the constructor arguments to pass to the constructor of T2 + xy - the pair whose two members are the constructor arguments for T1 and T2 + non_pair - non-pair argument to convert to pair for further construction + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called (through std::allocator_traits) by any allocator-aware + object, such as std::pmr::vector (or another std::vector that was given a + std::pmr::polymorphic_allocator as the allocator to use). + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2969 C++17 uses-allocator construction passed passes *this + resource() + LWG 2975 C++17 first overload is mistakenly used for constrained to not accept + pair construction in some cases pairs + LWG 3525 C++17 no overload could handle non-pair reconstructing overload + types convertible to pair added + +.SH See also + + construct constructs an object in the allocated storage + \fB[static]\fP \fI(function template)\fP + construct constructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP diff --git a/man/std::pmr::polymorphic_allocator::deallocate.3 b/man/std::pmr::polymorphic_allocator::deallocate.3 new file mode 100644 index 000000000..695672e59 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::deallocate.3 @@ -0,0 +1,35 @@ +.TH std::pmr::polymorphic_allocator::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::deallocate \- std::pmr::polymorphic_allocator::deallocate + +.SH Synopsis + void deallocate( T* p, std::size_t n ); \fI(since C++17)\fP + + Deallocates the storage pointed to by p, which must have been allocated from a + std::pmr::memory_resource x that compares equal to *resource() using x.allocate(n * + sizeof(T), alignof(T)). + + Equivalent to this->resource()->deallocate(p, n * sizeof(T), alignof(T));. + +.SH Parameters + + p - pointer to memory to deallocate + n - the number of objects originally allocated + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate_bytes free raw memory obtained from allocate_bytes + (C++20) \fI(public member function)\fP + deallocate_object frees raw memory obtained by allocate_object + (C++20) \fI(public member function)\fP + delete_object destroys and deallocates an object + (C++20) \fI(public member function)\fP + deallocate deallocates storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::deallocate_bytes.3 b/man/std::pmr::polymorphic_allocator::deallocate_bytes.3 new file mode 100644 index 000000000..4438ec617 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::deallocate_bytes.3 @@ -0,0 +1,45 @@ +.TH std::pmr::polymorphic_allocator::deallocate_bytes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::deallocate_bytes \- std::pmr::polymorphic_allocator::deallocate_bytes + +.SH Synopsis + void deallocate_bytes( void* p, + + std::size_t nbytes, \fI(since C++20)\fP + + std::size_t alignment = + alignof(std::max_align_t) ); + + Deallocates the storage pointed to by p, which must have been allocated from a + std::pmr::memory_resource x that compares equal to *resource(), using + x.allocate(nbytes, alignment), typically through a call to allocate_bytes(nbytes, + alignment). + + Equivalent to resource()->deallocate(p, nbytes, alignment);. + +.SH Parameters + + p - pointer to memory to deallocate + nbytes - the number of bytes originally allocated + alignment - the alignment originally allocated + +.SH Exceptions + + Throws nothing. + +.SH Notes + + This function was introduced for use with the fully-specialized allocator + std::pmr::polymorphic_allocator<>, but it may be useful in any specialization. + +.SH See also + + deallocate_object frees raw memory obtained by allocate_object + (C++20) \fI(public member function)\fP + delete_object destroys and deallocates an object + (C++20) \fI(public member function)\fP + deallocate deallocates storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::deallocate_object.3 b/man/std::pmr::polymorphic_allocator::deallocate_object.3 new file mode 100644 index 000000000..621876d3a --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::deallocate_object.3 @@ -0,0 +1,39 @@ +.TH std::pmr::polymorphic_allocator::deallocate_object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::deallocate_object \- std::pmr::polymorphic_allocator::deallocate_object + +.SH Synopsis + template< class U > \fI(since C++20)\fP + void deallocate_object( U* p, std::size_t n = 1 ); + + Deallocates the storage pointed to by p, which must have been allocated from a + std::pmr::memory_resource x that compares equal to *resource(), using x.allocate(n * + sizeof(U), alignof(U)), typically through a call to allocate_object(n). + + Equivalent to deallocate_bytes(p, n * sizeof(U), alignof(U));. + +.SH Parameters + + p - pointer to memory to deallocate + n - number of objects of type U the memory was for + +.SH Exceptions + + Throws nothing. + +.SH Notes + + This function was introduced for use with the fully-specialized allocator + std::pmr::polymorphic_allocator<>, but it may be useful in any specialization. + +.SH See also + + deallocate_bytes free raw memory obtained from allocate_bytes + (C++20) \fI(public member function)\fP + delete_object destroys and deallocates an object + (C++20) \fI(public member function)\fP + deallocate deallocates storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::delete_object.3 b/man/std::pmr::polymorphic_allocator::delete_object.3 new file mode 100644 index 000000000..c601a4a68 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::delete_object.3 @@ -0,0 +1,38 @@ +.TH std::pmr::polymorphic_allocator::delete_object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::delete_object \- std::pmr::polymorphic_allocator::delete_object + +.SH Synopsis + template< class U > \fI(since C++20)\fP + void delete_object( U* p ); + + Destroys the object of type U and deallocates storage allocated for it. + + Equivalent to + std::allocator_traits::destroy(*this, p); + deallocate_object(p); + +.SH Parameters + + p - pointer to the object to destroy and deallocate + +.SH Exceptions + + Throws nothing. + +.SH Notes + + This function was introduced for use with the fully-specialized allocator + std::pmr::polymorphic_allocator<>, but it may be useful in any specialization. + +.SH See also + + deallocate_bytes free raw memory obtained from allocate_bytes + (C++20) \fI(public member function)\fP + deallocate_object frees raw memory obtained by allocate_object + (C++20) \fI(public member function)\fP + deallocate deallocates storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::destroy.3 b/man/std::pmr::polymorphic_allocator::destroy.3 new file mode 100644 index 000000000..b3940a91a --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::destroy.3 @@ -0,0 +1,27 @@ +.TH std::pmr::polymorphic_allocator::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::destroy \- std::pmr::polymorphic_allocator::destroy + +.SH Synopsis + template< class U > \fI(since C++17)\fP + void destroy( U* p ); (deprecated in C++20) + (undeprecated in C++26) + + Destroys the object pointed to by p, as if by calling p->~U(). + +.SH Parameters + + p - pointer to the object being destroyed + +.SH Notes + + This function is deprecated via LWG issue 3036, because its functionality can be + provided by the default implementation of std::allocator_traits::destroy and hence + extraneous. + + This function is undeprecated via P2875R3. + +.SH See also + + destroy destructs an object stored in the allocated storage + \fB[static]\fP \fI(function template)\fP diff --git a/man/std::pmr::polymorphic_allocator::new_object.3 b/man/std::pmr::polymorphic_allocator::new_object.3 new file mode 100644 index 000000000..11e74bf71 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::new_object.3 @@ -0,0 +1,64 @@ +.TH std::pmr::polymorphic_allocator::new_object 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::new_object \- std::pmr::polymorphic_allocator::new_object + +.SH Synopsis + template< class U, class... CtorArgs > \fI(since C++20)\fP + [[nodiscard]] U* new_object( CtorArgs&&... ctor_args ); + + Allocates and constructs an object of type U. + + Given alloc is a std::pmr::polymorphic_allocator: + + U* p = alloc.new_object(std::forward(ctor_args)...); + + is equivalent to + + U* p = alloc.allocate_object(); + try + { + alloc.construct(p, std::forward(ctor_args)...); + } + catch (...) + { + alloc.deallocate_object(p); + throw; + } + +.SH Parameters + + ctor_args - the arguments to forward to the constructor of U + +.SH Return value + + A pointer to the allocated and constructed object. + +.SH Notes + + This function was introduced for use with the fully-specialized allocator + std::pmr::polymorphic_allocator<>, but it may be useful in any specialization as a + shortcut to avoid having to rebind from std::pmr::polymorphic_allocator to + std::pmr::polymorphic_allocator, and having to call allocate, construct, and + deallocate individually. + + Since U is not deduced, it must be provided as a template argument when calling this + function. + +.SH Exceptions + + May throw any exceptions thrown by the call to allocate_object or the constructor of + U. + +.SH See also + + allocate_bytes allocate raw aligned memory from the underlying resource + (C++20) \fI(public member function)\fP + allocate_object allocates raw memory suitable for an object or an array + (C++20) \fI(public member function)\fP + allocate allocate memory + \fI(public member function)\fP + allocate allocates uninitialized storage using the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::polymorphic_allocator::polymorphic_allocator.3 b/man/std::pmr::polymorphic_allocator::polymorphic_allocator.3 new file mode 100644 index 000000000..308197e0a --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::polymorphic_allocator.3 @@ -0,0 +1,41 @@ +.TH std::pmr::polymorphic_allocator::polymorphic_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::polymorphic_allocator \- std::pmr::polymorphic_allocator::polymorphic_allocator + +.SH Synopsis + polymorphic_allocator() noexcept; \fB(1)\fP + polymorphic_allocator( const polymorphic_allocator& other ) = default; \fB(2)\fP + template< class U > \fB(3)\fP + polymorphic_allocator( const polymorphic_allocator& other ) noexcept; + polymorphic_allocator( std::pmr::memory_resource* r ); \fB(4)\fP + + Constructs a new polymorphic_allocator. + + 1) Constructs a polymorphic_allocator using the return value of + std::pmr::get_default_resource() as the underlying memory resource. + 2,3) Constructs a polymorphic_allocator using other.resource() as the underlying + memory resource. + 4) Constructs a polymorphic_allocator using r as the underlying memory resource. + This constructor provides an implicit conversion from std::pmr::memory_resource*. + +.SH Parameters + + other - another polymorphic_allocator to copy from + r - pointer to the memory resource to use. May not be null + +.SH Exceptions + + 4) Throws nothing. + +.SH Notes + + Copying a container using a polymorphic_allocator will not call the allocator's copy + constructor. Instead, the new container will use the return value of + select_on_container_copy_construction (a default-constructed polymorphic_allocator) + as its allocator. + +.SH See also + + create a new polymorphic_allocator for use by + select_on_container_copy_construction a container's copy constructor + \fI(public member function)\fP diff --git a/man/std::pmr::polymorphic_allocator::resource.3 b/man/std::pmr::polymorphic_allocator::resource.3 new file mode 100644 index 000000000..e205d8c0e --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::resource.3 @@ -0,0 +1,16 @@ +.TH std::pmr::polymorphic_allocator::resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::resource \- std::pmr::polymorphic_allocator::resource + +.SH Synopsis + std::pmr::memory_resource* resource() const; \fI(since C++17)\fP + + Returns the memory resource pointer used by this polymorphic allocator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The memory resource pointer used by this polymorphic allocator. diff --git a/man/std::pmr::polymorphic_allocator::select_on_container_copy_construction.3 b/man/std::pmr::polymorphic_allocator::select_on_container_copy_construction.3 new file mode 100644 index 000000000..efe681a42 --- /dev/null +++ b/man/std::pmr::polymorphic_allocator::select_on_container_copy_construction.3 @@ -0,0 +1,27 @@ +.TH std::pmr::polymorphic_allocator::select_on_container_copy_construction 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::polymorphic_allocator::select_on_container_copy_construction \- std::pmr::polymorphic_allocator::select_on_container_copy_construction + +.SH Synopsis + polymorphic_allocator select_on_container_copy_construction() const; \fI(since C++17)\fP + + Returns a default-constructed polymorphic_allocator object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A default-constructed polymorphic_allocator object. + +.SH Notes + + polymorphic_allocators do not propagate on container copy construction. + +.SH See also + + obtains the allocator to use after copying a + select_on_container_copy_construction standard container + \fB[static]\fP \fI\fI(public static member\fP function of\fP + std::allocator_traits) diff --git a/man/std::pmr::pool_options.3 b/man/std::pmr::pool_options.3 new file mode 100644 index 000000000..5777d54e3 --- /dev/null +++ b/man/std::pmr::pool_options.3 @@ -0,0 +1,43 @@ +.TH std::pmr::pool_options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::pool_options \- std::pmr::pool_options + +.SH Synopsis + Defined in header + struct pool_options; \fI(since C++17)\fP + + std::pmr::pool_options is a set of constructor options for pool resources including + std::pmr::synchronized_pool_resource and std::pmr::unsynchronized_pool_resource. + + Data members + + Member Meaning + The maximum number of blocks that will be + allocated at once from the upstream + std::pmr::memory_resource to replenish the + pool. If the value of max_blocks_per_chunk is + std::size_t max_blocks_per_chunk; zero or is greater than an + implementation-defined limit, that limit is + used instead. The implementation may choose to + use a smaller value than is specified in this + field and may use different values for + different pools. + The largest allocation size that is required + to be fulfilled using the pooling mechanism. + Attempts to allocate a single block larger + than this threshold will be allocated directly + std::size_t from the upstream std::pmr::memory_resource. + largest_required_pool_block; If largest_required_pool_block is zero or is + greater than an implementation-defined limit, + that limit is used instead. The implementation + may choose a pass-through threshold larger + than specified in this field. + +.SH See also + + synchronized_pool_resource a thread-safe std::pmr::memory_resource for managing + \fI(C++17)\fP allocations in pools of different block sizes + \fI(class)\fP + unsynchronized_pool_resource a thread-unsafe std::pmr::memory_resource for managing + \fI(C++17)\fP allocations in pools of different block sizes + \fI(class)\fP diff --git a/man/std::pmr::set_default_resource.3 b/man/std::pmr::set_default_resource.3 new file mode 100644 index 000000000..46454c059 --- /dev/null +++ b/man/std::pmr::set_default_resource.3 @@ -0,0 +1,171 @@ +.TH std::pmr::set_default_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::set_default_resource \- std::pmr::set_default_resource + +.SH Synopsis + Defined in header + std::pmr::memory_resource* set_default_resource( \fI(since C++17)\fP + std::pmr::memory_resource* r ) noexcept; + + If r is not null, sets the default memory resource pointer to r; otherwise, sets the + default memory resource pointer to std::pmr::new_delete_resource(). + + The default memory resource pointer is used by certain facilities when an explicit + memory resource is not supplied. The initial default memory resource pointer is the + return value of std::pmr::new_delete_resource. + + This function is thread-safe. Every call to std::pmr::set_default_resource + synchronizes with (see std::memory_order) the subsequent + std::pmr::set_default_resource and std::pmr::get_default_resource calls. + +.SH Return value + + Returns the previous value of the default memory resource pointer. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + class noisy_allocator : public std::pmr::memory_resource + { + void* do_allocate(std::size_t bytes, std::size_t alignment) override + { + std::cout << "+ Allocating " << bytes << " bytes @ "; + void* p = std::pmr::new_delete_resource()->allocate(bytes, alignment); + std::cout << p << '\\n'; + return p; + } + + void do_deallocate(void* p, std::size_t bytes, std::size_t alignment) override + { + std::cout << "- Deallocating " << bytes << " bytes @ " << p << '\\n'; + return std::pmr::new_delete_resource()->deallocate(p, bytes, alignment); + } + + bool do_is_equal(const std::pmr::memory_resource& other) const noexcept override + { + return std::pmr::new_delete_resource()->is_equal(other); + } + }; + + int main() + { + constexpr int push_back_limit{16}; + noisy_allocator mem; + std::pmr::set_default_resource(&mem); + + { + std::cout << "Entering scope #1 (without buffer on stack)...\\n"; + std::cout << "Creating vector v...\\n"; + std::pmr::vector v{1, 2, 3, 4}; + std::cout << "v.data() @ " << v.data() << '\\n'; + + std::cout << "Requesting more...\\n"; + for (int i{0}; i != push_back_limit; ++i) + { + v.push_back(i); + std::cout << "v.size(): " << v.size() << '\\n'; + } + std::cout << "Exiting scope #1...\\n"; + } + + std::cout << '\\n'; + + { + std::cout << "Entering scope #2 (with buffer on stack)...\\n"; + + std::uint8_t buffer[16]; + std::cout << "Allocating buffer on stack: " << sizeof buffer << " bytes @ " + << static_cast(buffer) << '\\n'; + std::pmr::monotonic_buffer_resource mem_res{std::data(buffer), std::size(buffer)}; + + std::cout << "Creating vector v...\\n"; + std::pmr::vector v{{1, 2, 3, 4}, &mem_res}; + std::cout << "v.data() @ " << v.data() << '\\n'; // equals to `buffer` address + + std::cout << "Requesting more...\\n"; + for (int i{0}; i != push_back_limit; ++i) + { + v.push_back(i); + std::cout << "v.size(): " << v.size() << '\\n'; + } + std::cout << "Exiting scope #2...\\n"; + } + } + +.SH Possible output: + + Entering scope #1 (without buffer on stack)... + Creating vector v... + + Allocating 8 bytes @ 0x1f75c30 + v.data() @ 0x1f75c30 + Requesting more... + + Allocating 16 bytes @ 0x1f75c50 + - Deallocating 8 bytes @ 0x1f75c30 + v.size(): 5 + v.size(): 6 + v.size(): 7 + v.size(): 8 + + Allocating 32 bytes @ 0x1f75c70 + - Deallocating 16 bytes @ 0x1f75c50 + v.size(): 9 + v.size(): 10 + v.size(): 11 + v.size(): 12 + v.size(): 13 + v.size(): 14 + v.size(): 15 + v.size(): 16 + + Allocating 64 bytes @ 0x1f75ca0 + - Deallocating 32 bytes @ 0x1f75c70 + v.size(): 17 + v.size(): 18 + v.size(): 19 + v.size(): 20 + Exiting scope #1... + - Deallocating 64 bytes @ 0x1f75ca0 + + Entering scope #2 (with buffer on stack)... + Allocating buffer on stack: 16 bytes @ 0x7fffbe9f8240 + Creating vector v... + v.data() @ 0x7fffbe9f8240 + Requesting more... + + Allocating 64 bytes @ 0x1f75ca0 + v.size(): 5 + v.size(): 6 + v.size(): 7 + v.size(): 8 + v.size(): 9 + v.size(): 10 + v.size(): 11 + v.size(): 12 + v.size(): 13 + v.size(): 14 + v.size(): 15 + v.size(): 16 + + Allocating 128 bytes @ 0x1f75cf0 + v.size(): 17 + v.size(): 18 + v.size(): 19 + v.size(): 20 + Exiting scope #2... + - Deallocating 128 bytes @ 0x1f75cf0 + - Deallocating 64 bytes @ 0x1f75ca0 + +.SH See also + + get_default_resource gets the default std::pmr::memory_resource + \fI(C++17)\fP \fI(function)\fP + returns a static program-wide std::pmr::memory_resource that + new_delete_resource uses the global operator new and operator delete to allocate + \fI(C++17)\fP and deallocate memory + \fI(function)\fP diff --git a/man/std::pmr::synchronized_pool_resource.3 b/man/std::pmr::synchronized_pool_resource.3 new file mode 100644 index 000000000..c85f63c10 --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource.3 @@ -0,0 +1,56 @@ +.TH std::pmr::synchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource \- std::pmr::synchronized_pool_resource + +.SH Synopsis + Defined in header + class synchronized_pool_resource : public std::pmr::memory_resource; \fI(since C++17)\fP + + The class std::pmr::synchronized_pool_resource is a general-purpose memory resource + class with the following properties: + + * It owns the allocated memory and frees it on destruction, even if deallocate has + not been called for some of the allocated blocks. + * It consists of a collection of pools that serves requests for different block + sizes. Each pool manages a collection of chunks that are then divided into + blocks of uniform size. + * Calls to do_allocate are dispatched to the pool serving the smallest blocks + accommodating the requested size. + * Exhausting memory in the pool causes the next allocation request for that pool + to allocate an additional chunk of memory from the upstream allocator to + replenish the pool. The chunk size obtained increases geometrically. + * Allocations requests that exceed the largest block size are served from the + upstream allocator directly. + * The largest block size and maximum chunk size may be tuned by passing a + std::pmr::pool_options struct to its constructor. + + synchronized_pool_resource may be accessed from multiple threads without external + synchronization, and may have thread-specific pools to reduce synchronization costs. + If the memory resource is only accessed from one thread, + unsynchronized_pool_resource is more efficient. + +.SH Member functions + + constructor constructs a synchronized_pool_resource + \fI(public member function)\fP + destructor destroys a synchronized_pool_resource, releasing all allocated + \fB[virtual]\fP memory + \fI(virtual public member function)\fP + operator= copy assignment operator is deleted. synchronized_pool_resource is + [deleted] not copy assignable + \fI(public member function)\fP +.SH Public member functions + release release all allocated memory + \fI(public member function)\fP + upstream_resource returns a pointer to the upstream memory resource + \fI(public member function)\fP + returns the options that control the pooling behavior of this + options resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocate memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate return memory to the pool + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::pmr::synchronized_pool_resource::do_allocate.3 b/man/std::pmr::synchronized_pool_resource::do_allocate.3 new file mode 100644 index 000000000..40e64acdf --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::do_allocate.3 @@ -0,0 +1,33 @@ +.TH std::pmr::synchronized_pool_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::do_allocate \- std::pmr::synchronized_pool_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t alignment \fI(since C++17)\fP + ); + + Allocates storage. + + If the pool selected for a block of size bytes is unable to satisfy the request from + its internal data structures, calls allocate() on the upstream memory resource to + obtain memory. + + If the size requested is larger than what the largest pool can handle, memory is + allocated by calling allocate() on the upstream memory resource. + +.SH Return value + + A pointer to allocated storage of at least bytes bytes in size, aligned to the + specified alignment if such alignment is supported, and to alignof(std::max_align_t) + otherwise. + +.SH Exceptions + + Throws nothing unless calling allocate() on the upstream memory resource throws. + +.SH See also + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP + do_allocate allocates memory + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::synchronized_pool_resource::do_deallocate.3 b/man/std::pmr::synchronized_pool_resource::do_deallocate.3 new file mode 100644 index 000000000..3dac5e29c --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::do_deallocate.3 @@ -0,0 +1,22 @@ +.TH std::pmr::synchronized_pool_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::do_deallocate \- std::pmr::synchronized_pool_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, std::size_t \fI(since C++17)\fP + alignment ); + + Returns the memory at p to the pool. It is unspecified if or under what + circumstances this operation will result in a call to deallocate() on the upstream + memory resource. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP + do_deallocate deallocates memory + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::synchronized_pool_resource::do_is_equal.3 b/man/std::pmr::synchronized_pool_resource::do_is_equal.3 new file mode 100644 index 000000000..bc57fa3f3 --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::do_is_equal.3 @@ -0,0 +1,27 @@ +.TH std::pmr::synchronized_pool_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::do_is_equal \- std::pmr::synchronized_pool_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const std::pmr::memory_resource& other ) \fI(since C++17)\fP + const noexcept; + + Compare *this with other for identity - memory allocated using a + synchronized_pool_resource can only be deallocated using that same resource. + +.SH Return value + + this == &other + + Defect report + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3000 C++17 unnecessary dynamic_cast was performed removed + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::synchronized_pool_resource::options.3 b/man/std::pmr::synchronized_pool_resource::options.3 new file mode 100644 index 000000000..b0ab1225e --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::options.3 @@ -0,0 +1,19 @@ +.TH std::pmr::synchronized_pool_resource::options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::options \- std::pmr::synchronized_pool_resource::options + +.SH Synopsis + std::pmr::pool_options options() const; \fI(since C++17)\fP + + Returns the options that controls the pooling behavior of this resource. + + The values in the returned struct may differ from those supplied to the constructor + in the following ways: + + * Values of zero will be replaced with implementation-specified defaults; + * Sizes may be rounded to an unspecified granularity. + +.SH See also + + constructor constructs a synchronized_pool_resource + \fI(public member function)\fP diff --git a/man/std::pmr::synchronized_pool_resource::release.3 b/man/std::pmr::synchronized_pool_resource::release.3 new file mode 100644 index 000000000..b33019802 --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::release.3 @@ -0,0 +1,17 @@ +.TH std::pmr::synchronized_pool_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::release \- std::pmr::synchronized_pool_resource::release + +.SH Synopsis + void release(); \fI(since C++17)\fP + + Releases all memory owned by this resource by calling the deallocate function of the + upstream memory resource as needed. + + Memory is released back to the upstream resource even if deallocate has not been + called for some of the allocated blocks. + +.SH See also + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::synchronized_pool_resource::synchronized_pool_resource.3 b/man/std::pmr::synchronized_pool_resource::synchronized_pool_resource.3 new file mode 100644 index 000000000..b8b47c848 --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::synchronized_pool_resource.3 @@ -0,0 +1,34 @@ +.TH std::pmr::synchronized_pool_resource::synchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::synchronized_pool_resource \- std::pmr::synchronized_pool_resource::synchronized_pool_resource + +.SH Synopsis + synchronized_pool_resource(); \fB(1)\fP \fI(since C++17)\fP + explicit synchronized_pool_resource( std::pmr::memory_resource* \fB(2)\fP \fI(since C++17)\fP + upstream ); + explicit synchronized_pool_resource( const std::pmr::pool_options& \fB(3)\fP \fI(since C++17)\fP + opts ); + synchronized_pool_resource( const std::pmr::pool_options& opts, \fB(4)\fP \fI(since C++17)\fP + std::pmr::memory_resource* upstream ); + synchronized_pool_resource( const synchronized_pool_resource& ) = \fB(5)\fP \fI(since C++17)\fP + delete; + + Constructs a synchronized_pool_resource. + + 1-4) Constructs a synchronized_pool_resource using the specified upstream memory + resource and tuned according to the specified options. The resulting object holds a + copy of upstream but does not own the resource to which upstream points. + The overloads not taking opts as a parameter uses a default constructed instance of + pool_options as the options. The overloads not taking upstream as a parameter uses + the return value of std::pmr::get_default_resource as the upstream memory resource. + 5) Copy constructor is deleted. + +.SH Parameters + + opts - a std::pmr::pool_options struct containing the constructor options + upstream - the upstream memory resource to use + +.SH Exceptions + + 1-4) Throws only if a call to the allocate() function of the upstream resource + throws. It is unspecified if or under what conditions such a call takes place. diff --git a/man/std::pmr::synchronized_pool_resource::upstream_resource.3 b/man/std::pmr::synchronized_pool_resource::upstream_resource.3 new file mode 100644 index 000000000..472967796 --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::upstream_resource.3 @@ -0,0 +1,14 @@ +.TH std::pmr::synchronized_pool_resource::upstream_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::upstream_resource \- std::pmr::synchronized_pool_resource::upstream_resource + +.SH Synopsis + std::pmr::memory_resource* upstream_resource() const; \fI(since C++17)\fP + + Returns a pointer to the upstream memory resource. This is the same value as the + upstream argument passed to the constructor of this object. + +.SH See also + + constructor constructs a synchronized_pool_resource + \fI(public member function)\fP diff --git a/man/std::pmr::synchronized_pool_resource::~synchronized_pool_resource.3 b/man/std::pmr::synchronized_pool_resource::~synchronized_pool_resource.3 new file mode 100644 index 000000000..6f17b9a72 --- /dev/null +++ b/man/std::pmr::synchronized_pool_resource::~synchronized_pool_resource.3 @@ -0,0 +1,15 @@ +.TH std::pmr::synchronized_pool_resource::~synchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::synchronized_pool_resource::~synchronized_pool_resource \- std::pmr::synchronized_pool_resource::~synchronized_pool_resource + +.SH Synopsis + virtual ~synchronized_pool_resource(); \fI(since C++17)\fP + + Destroys a synchronized_pool_resource. + + Deallocates all memory owned by this resource by calling this->release(). + +.SH See also + + release release all allocated memory + \fI(public member function)\fP diff --git a/man/std::pmr::unsynchronized_pool_resource.3 b/man/std::pmr::unsynchronized_pool_resource.3 new file mode 100644 index 000000000..082ae16e5 --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource.3 @@ -0,0 +1,56 @@ +.TH std::pmr::unsynchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource \- std::pmr::unsynchronized_pool_resource + +.SH Synopsis + Defined in header + class unsynchronized_pool_resource : public \fI(since C++17)\fP + std::pmr::memory_resource; + + The class std::pmr::unsynchronized_pool_resource is a general-purpose memory + resource class with the following properties: + + * It owns the allocated memory and frees it on destruction, even if deallocate has + not been called for some of the allocated blocks. + * It consists of a collection of pools that serves requests for different block + sizes. Each pool manages a collection of chunks that are then divided into + blocks of uniform size. + * Calls to do_allocate are dispatched to the pool serving the smallest blocks + accommodating the requested size. + * Exhausting memory in the pool causes the next allocation request for that pool + to allocate an additional chunk of memory from the upstream allocator to + replenish the pool. The chunk size obtained increases geometrically. + * Allocations requests that exceed the largest block size are served from the + upstream allocator directly. + * The largest block size and maximum chunk size may be tuned by passing a + std::pmr::pool_options struct to its constructor. + + unsynchronized_pool_resource is not thread-safe, and cannot be accessed from + multiple threads simultaneously; use synchronized_pool_resource if access from + multiple threads is required. + +.SH Member functions + + constructor constructs an unsynchronized_pool_resource + \fI(public member function)\fP + destructor destroys an unsynchronized_pool_resource, releasing all allocated + \fB[virtual]\fP memory + \fI(virtual public member function)\fP + operator= copy assignment operator is deleted. unsynchronized_pool_resource + [deleted] is not copy assignable + \fI(public member function)\fP +.SH Public member functions + release release all allocated memory + \fI(public member function)\fP + upstream_resource returns a pointer to the upstream memory resource + \fI(public member function)\fP + returns the options that control the pooling behavior of this + options resource + \fI(public member function)\fP +.SH Protected member functions + do_allocate allocate memory + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_deallocate return memory to the pool + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_is_equal compare for equality with another std::pmr::memory_resource + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::pmr::unsynchronized_pool_resource::do_allocate.3 b/man/std::pmr::unsynchronized_pool_resource::do_allocate.3 new file mode 100644 index 000000000..3b212230b --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::do_allocate.3 @@ -0,0 +1,33 @@ +.TH std::pmr::unsynchronized_pool_resource::do_allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::do_allocate \- std::pmr::unsynchronized_pool_resource::do_allocate + +.SH Synopsis + virtual void* do_allocate( std::size_t bytes, std::size_t alignment \fI(since C++17)\fP + ); + + Allocates storage. + + If the pool selected for a block of size bytes is unable to satisfy the request from + its internal data structures, calls allocate() on the upstream memory resource to + obtain memory. + + If the size requested is larger than what the largest pool can handle, memory is + allocated by calling allocate() on the upstream memory resource. + +.SH Return value + + A pointer to allocated storage of at least bytes bytes in size, aligned to the + specified alignment if such alignment is supported, and to alignof(std::max_align_t) + otherwise. + +.SH Exceptions + + Throws nothing unless calling allocate() on the upstream memory resource throws. + +.SH See also + + allocate allocates memory + \fI(public member function of std::pmr::memory_resource)\fP + do_allocate allocates memory + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::unsynchronized_pool_resource::do_deallocate.3 b/man/std::pmr::unsynchronized_pool_resource::do_deallocate.3 new file mode 100644 index 000000000..4ec7aa1df --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::do_deallocate.3 @@ -0,0 +1,22 @@ +.TH std::pmr::unsynchronized_pool_resource::do_deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::do_deallocate \- std::pmr::unsynchronized_pool_resource::do_deallocate + +.SH Synopsis + virtual void do_deallocate( void* p, std::size_t bytes, std::size_t \fI(since C++17)\fP + alignment ); + + Returns the memory at p to the pool. It is unspecified if or under what + circumstances this operation will result in a call to deallocate() on the upstream + memory resource. + +.SH Exceptions + + Throws nothing. + +.SH See also + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP + do_deallocate deallocates memory + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::unsynchronized_pool_resource::do_is_equal.3 b/man/std::pmr::unsynchronized_pool_resource::do_is_equal.3 new file mode 100644 index 000000000..1767cbd03 --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::do_is_equal.3 @@ -0,0 +1,27 @@ +.TH std::pmr::unsynchronized_pool_resource::do_is_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::do_is_equal \- std::pmr::unsynchronized_pool_resource::do_is_equal + +.SH Synopsis + virtual bool do_is_equal( const std::pmr::memory_resource& other ) \fI(since C++17)\fP + const noexcept; + + Compare *this with other for identity - memory allocated using an + unsynchronized_pool_resource can only be deallocated using that same resource. + +.SH Return value + + this == &other + + Defect report + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3000 C++17 unnecessary dynamic_cast was performed removed + +.SH See also + + do_is_equal compare for equality with another memory_resource + \fB[virtual]\fP (virtual private member function of std::pmr::memory_resource) diff --git a/man/std::pmr::unsynchronized_pool_resource::options.3 b/man/std::pmr::unsynchronized_pool_resource::options.3 new file mode 100644 index 000000000..16cf6e6da --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::options.3 @@ -0,0 +1,19 @@ +.TH std::pmr::unsynchronized_pool_resource::options 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::options \- std::pmr::unsynchronized_pool_resource::options + +.SH Synopsis + std::pmr::pool_options options() const; \fI(since C++17)\fP + + Returns the options that controls the pooling behavior of this resource. + + The values in the returned struct may differ from those supplied to the constructor + in the following ways: + + * Values of zero will be replaced with implementation-specified defaults; + * Sizes may be rounded to an unspecified granularity. + +.SH See also + + constructor constructs an unsynchronized_pool_resource + \fI(public member function)\fP diff --git a/man/std::pmr::unsynchronized_pool_resource::release.3 b/man/std::pmr::unsynchronized_pool_resource::release.3 new file mode 100644 index 000000000..243c9b522 --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::release.3 @@ -0,0 +1,17 @@ +.TH std::pmr::unsynchronized_pool_resource::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::release \- std::pmr::unsynchronized_pool_resource::release + +.SH Synopsis + void release(); \fI(since C++17)\fP + + Releases all memory owned by this resource by calling the deallocate function of the + upstream memory resource as needed. + + Memory is released back to the upstream resource even if deallocate has not been + called for some of the allocated blocks. + +.SH See also + + deallocate deallocates memory + \fI(public member function of std::pmr::memory_resource)\fP diff --git a/man/std::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource.3 b/man/std::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource.3 new file mode 100644 index 000000000..aa9140665 --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource.3 @@ -0,0 +1,36 @@ +.TH std::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource \- std::pmr::unsynchronized_pool_resource::unsynchronized_pool_resource + +.SH Synopsis + unsynchronized_pool_resource(); \fB(1)\fP \fI(since C++17)\fP + explicit unsynchronized_pool_resource( std::pmr::memory_resource* \fB(2)\fP \fI(since C++17)\fP + upstream ); + explicit unsynchronized_pool_resource( const \fB(3)\fP \fI(since C++17)\fP + std::pmr::pool_options& opts ); + unsynchronized_pool_resource( const std::pmr::pool_options& opts, + std::pmr::memory_resource* upstream \fB(4)\fP \fI(since C++17)\fP + ); + unsynchronized_pool_resource( const unsynchronized_pool_resource& \fB(5)\fP \fI(since C++17)\fP + ) = delete; + + Constructs an unsynchronized_pool_resource. + + 1-4) Constructs an unsynchronized_pool_resource using the specified upstream memory + resource and tuned according to the specified options. The resulting object holds a + copy of upstream but does not own the resource to which upstream points. + The overloads not taking opts as a parameter uses a default constructed instance of + pool_options as the options. The overloads not taking upstream as a parameter use + the return value of std::pmr::get_default_resource() as the upstream memory + resource. + 5) Copy constructor is deleted. + +.SH Parameters + + opts - a std::pmr::pool_options struct containing the constructor options + upstream - the upstream memory resource to use + +.SH Exceptions + + 1-4) Throws only if a call to the allocate() function of the upstream resource + throws. It is unspecified if or under what conditions such a call takes place. diff --git a/man/std::pmr::unsynchronized_pool_resource::upstream_resource.3 b/man/std::pmr::unsynchronized_pool_resource::upstream_resource.3 new file mode 100644 index 000000000..d00e04b95 --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::upstream_resource.3 @@ -0,0 +1,14 @@ +.TH std::pmr::unsynchronized_pool_resource::upstream_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::upstream_resource \- std::pmr::unsynchronized_pool_resource::upstream_resource + +.SH Synopsis + std::pmr::memory_resource* upstream_resource() const; \fI(since C++17)\fP + + Returns a pointer to the upstream memory resource. This is the same value as the + upstream argument passed to the constructor of this object. + +.SH See also + + constructor constructs an unsynchronized_pool_resource + \fI(public member function)\fP diff --git a/man/std::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource.3 b/man/std::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource.3 new file mode 100644 index 000000000..7b7374d1a --- /dev/null +++ b/man/std::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource.3 @@ -0,0 +1,15 @@ +.TH std::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource \- std::pmr::unsynchronized_pool_resource::~unsynchronized_pool_resource + +.SH Synopsis + virtual ~unsynchronized_pool_resource(); \fI(since C++17)\fP + + Destroys an unsynchronized_pool_resource. + + Deallocates all memory owned by this resource by calling this->release(). + +.SH See also + + release release all allocated memory + \fI(public member function)\fP diff --git a/man/std::pointer_safety.3 b/man/std::pointer_safety.3 index cf30828e5..10f31850a 100644 --- a/man/std::pointer_safety.3 +++ b/man/std::pointer_safety.3 @@ -1,16 +1,19 @@ -.TH std::pointer_safety 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pointer_safety 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pointer_safety \- std::pointer_safety + .SH Synopsis Defined in header enum class pointer_safety { - relaxed, - preferred, \fI(since C++11)\fP + relaxed, \fI(since C++11)\fP + preferred, (removed in C++23) strict }; The scoped enumeration type pointer_safety lists the pointer safety modes supported - by C++ + by C++. Enumeration constants @@ -20,11 +23,12 @@ active. All pointers are considered valid and may be dereferenced pointer_safety::preferred or deallocated. A reachability-based leak detector may be - active + active. pointer_safety::relaxed All pointers are considered valid and may be dereferenced - or deallocated + or deallocated. .SH See also get_pointer_safety returns the current pointer safety model - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + (removed in C++23) diff --git a/man/std::pointer_to_binary_function.3 b/man/std::pointer_to_binary_function.3 index 495b82929..a990b4374 100644 --- a/man/std::pointer_to_binary_function.3 +++ b/man/std::pointer_to_binary_function.3 @@ -1,13 +1,16 @@ -.TH std::pointer_to_binary_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pointer_to_binary_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pointer_to_binary_function \- std::pointer_to_binary_function + .SH Synopsis template< class Arg1, - class Arg2, \fB(deprecated)\fP - class Result + class Arg2, (deprecated in C++11) + class Result (removed in C++17) - > class pointer_to_binary_function : public std::binary_function; + > class pointer_to_binary_function : public + std::binary_function; std::pointer_to_binary_function is a function object that acts as a wrapper around a binary function. @@ -20,7 +23,7 @@ operator() calls the stored function \fI(public member function)\fP - std::pointer_to_binary_function::pointer_to_binary_function +std::pointer_to_binary_function::pointer_to_binary_function explicit pointer_to_binary_function( Result (*f)(Arg1,Arg2) ); @@ -30,7 +33,7 @@ f - pointer to a function to store - std::pointer_to_binary_function::operator() +std::pointer_to_binary_function::operator() Result operator()( Arg1 x1, Arg2 x2 ) const; @@ -47,7 +50,8 @@ .SH See also pointer_to_unary_function adaptor-compatible wrapper for a pointer to unary function - \fB(deprecated)\fP \fI(class template)\fP + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) ptr_fun creates an adaptor-compatible function object wrapper from - \fB(deprecated)\fP a pointer to function - \fI(function template)\fP + (deprecated in C++11) a pointer to function + (removed in C++17) \fI(function template)\fP diff --git a/man/std::pointer_to_unary_function.3 b/man/std::pointer_to_unary_function.3 index b7a142167..438cd2898 100644 --- a/man/std::pointer_to_unary_function.3 +++ b/man/std::pointer_to_unary_function.3 @@ -1,12 +1,15 @@ -.TH std::pointer_to_unary_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pointer_to_unary_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pointer_to_unary_function \- std::pointer_to_unary_function + .SH Synopsis template< - class Arg, - class Result \fB(deprecated)\fP + class Arg, (deprecated in C++11) + class Result (removed in C++17) - > class pointer_to_unary_function : public std::unary_function; + > class pointer_to_unary_function : public + std::unary_function; std::pointer_to_unary_function is a function object that acts as a wrapper around a unary function. @@ -19,7 +22,7 @@ operator() calls the stored function \fI(public member function)\fP - std::pointer_to_unary_function::pointer_to_unary_function +std::pointer_to_unary_function::pointer_to_unary_function explicit pointer_to_unary_function( Result (*f)(Arg) ); @@ -29,7 +32,7 @@ f - pointer to a function to store - std::pointer_to_unary_function::operator() +std::pointer_to_unary_function::operator() Result operator()( Arg x ) const; @@ -46,8 +49,8 @@ .SH See also pointer_to_binary_function adaptor-compatible wrapper for a pointer to binary - \fB(deprecated)\fP function - \fI(class template)\fP + (deprecated in C++11) function + (removed in C++17) \fI(class template)\fP ptr_fun creates an adaptor-compatible function object wrapper - \fB(deprecated)\fP from a pointer to function - \fI(function template)\fP + (deprecated in C++11) from a pointer to function + (removed in C++17) \fI(function template)\fP diff --git a/man/std::pointer_traits.3 b/man/std::pointer_traits.3 index 218ab3e25..517bb5c2e 100644 --- a/man/std::pointer_traits.3 +++ b/man/std::pointer_traits.3 @@ -1,37 +1,52 @@ -.TH std::pointer_traits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pointer_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pointer_traits \- std::pointer_traits + .SH Synopsis Defined in header - template< class Ptr > struct pointer_traits; \fB(1)\fP \fI(since C++11)\fP - template< class T > struct pointer_traits; \fB(2)\fP \fI(since C++11)\fP + template< class Ptr > \fB(1)\fP \fI(since C++11)\fP + struct pointer_traits; + template< class T > \fB(2)\fP \fI(since C++11)\fP + struct pointer_traits; The pointer_traits class template provides the standardized way to access certain - properties of pointer-like types. The standard template std::allocator_traits relies + properties of pointer-like types (fancy pointers, such as + boost::interprocess::offset_ptr). The standard template std::allocator_traits relies on pointer_traits to determine the defaults for various typedefs required by Allocator. - 1) The non-specialized pointer_traits declares the following types: + 1) The non-specialized pointer_traits conditionally declares the following members: + + Let /*element-type-of*/ be + + * Ptr::element_type if present; + * otherwise, T if Ptr is a class template specialization Template, + where Args... is zero or more type arguments; + * otherwise, not defined. + + If /*element-type-of*/ is not defined, the primary template has no members + specified in this page. .SH Member types Type Definition pointer Ptr - element_type Ptr::element_type if present. Otherwise T if Ptr is a template - instantiation Template + element_type /*element-type-of*/ difference_type Ptr::difference_type if present, otherwise std::ptrdiff_t .SH Member alias templates - Template Definition - template using Ptr::rebind if exists, otherwise Template if - rebind Ptr is a template instantiation Template + Template Definition + template< class U > using Ptr::rebind if exists, otherwise Template + rebind if Ptr is a template specialization Template .SH Member functions - pointer_to obtains a dereferencable pointer to its argument + pointer_to obtains a dereferenceable pointer to its argument \fB[static]\fP \fI(public static member function)\fP 2) A specialization is provided for pointer types, T*, which declares the following - types + members: .SH Member types @@ -47,52 +62,67 @@ .SH Member functions - pointer_to obtains a dereferenceable pointer to its argument} + pointer_to obtains a dereferenceable pointer to its argument \fB[static]\fP \fI(public static member function)\fP + Optional member functions of program-defined specializations + + to_address obtains a raw pointer from a fancy pointer (inverse of + \fB[static]\fP (C++20)(optional) pointer_to) + \fI(public static member function)\fP + .SH Notes The rebind member template alias makes it possible, given a pointer-like type that points to T, to obtain the same pointer-like type that points to U. For example, - typedef std::pointer_traits>::rebind another_pointer; - static_assert(std::is_same>::value, ""); + using another_pointer = std::pointer_traits>::rebind; + static_assert(std::is_same>::value); + + A specialization for user-defined fancy pointer types may provide an + additional static member function to_address to customize the behavior \fI(since C++20)\fP + of std::to_address. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_memory 201811L (C++20) constexpr in std::pointer_traits .SH Example - + // Run this code - #include #include - - template + #include + + template struct BlockList { - // Predefine a memory block - struct block; - - // Define a pointer to a memory block from the kind of pointer Ptr s - // If Ptr is any kind of T*, block_ptr_t is block* - // If Ptr is smart_ptr, block_ptr_t is smart_ptr - typedef typename std::pointer_traits::template rebind block_ptr_t; - - struct block - { - std::size_t size; - block_ptr_t next_block; - }; - - block_ptr_t free_blocks; + // Predefine a memory block + struct block; + + // Define a pointer to a memory block from the kind of pointer Ptr s + // If Ptr is any kind of T*, block_ptr_t is block* + // If Ptr is smart_ptr, block_ptr_t is smart_ptr + using block_ptr_t = typename std::pointer_traits::template rebind; + + struct block + { + std::size_t size{}; + block_ptr_t next_block{}; + }; + + block_ptr_t free_blocks; }; - + int main() { + [[maybe_unused]] BlockList bl1; - // The type of bl1.free_blocks is block* - + // The type of bl1.free_blocks is BlockList:: block* + BlockList> bl2; - // The type of bl2.free_blocks is std::shared_ptr + // The type of bl2.free_blocks is + // std::shared_ptr>::block> std::cout << bl2.free_blocks.use_count() << '\\n'; } @@ -100,10 +130,19 @@ 0 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3545 C++11 primary template caused hard error when made SFINAE-friendly + element_type is invalid + .SH See also allocator_traits provides information about allocator types - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP addressof obtains actual address of an object, even if the & operator is \fI(C++11)\fP overloaded - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::pointer_traits::pointer_to.3 b/man/std::pointer_traits::pointer_to.3 index f897b4bf8..85bc1712c 100644 --- a/man/std::pointer_traits::pointer_to.3 +++ b/man/std::pointer_traits::pointer_to.3 @@ -1,20 +1,32 @@ -.TH std::pointer_traits::pointer_to 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - static pointer pointer_to( \fI(since C++11)\fP - element_type& r ); \fB(1)\fP (member of pointer_traits - specialization) - static pointer pointer_to( \fI(since C++11)\fP - element_type& r ); \fB(2)\fP (member of pointer_traits - specialization) +.TH std::pointer_traits::pointer_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pointer_traits::pointer_to \- std::pointer_traits::pointer_to - Constructs a dereferenceable pointer to its argument. +.SH Synopsis + Defined in header + + static pointer \fI(since C++11)\fP + pointer_to( \fB(1)\fP (member of pointer_traits + element_type& r ); specialization) + static pointer \fI(since C++11)\fP + pointer_to( \fI(until C++20)\fP + element_type& r ) (member of + noexcept; pointer_traits + \fB(2)\fP specialization) + static constexpr \fI(since C++20)\fP + pointer (member of + pointer_to( pointer_traits + element_type& r ) specialization) + noexcept; + + Constructs a dereferenceable pointer or pointer-like object ("fancy pointer") to its + argument. 1) The version of this function in the non-specialized std::pointer_traits template simply calls Ptr::pointer_to(r), and if Ptr does not provide a static member function pointer_to, instantiation of this function is a compile-time error. 2) The version of this function in the specialization of std::pointer_traits for - pointer types returns std::addressof(r) + pointer types returns std::addressof(r). .SH Parameters @@ -27,20 +39,23 @@ .SH Exceptions - 1) Unspecified (typically same as Ptr::pointer_to) - 2) - noexcept specification: - noexcept - + 1) Unspecified (typically same as Ptr::pointer_to). .SH Notes - The boost library version of this function returns pointer(std::addressof(r)) if - Ptr::pointer_to does not exist. + The Boost.Intrusive library version of this function returns + pointer(std::addressof(r)) if Ptr::pointer_to does not exist. .SH See also - addressof obtains actual address of an object, even if the & operator is overloaded - \fI(C++11)\fP \fI(function template)\fP - address obtains the address of an object, even if operator& is overloaded - \fI(public member function of std::allocator)\fP + addressof obtains actual address of an object, even if the & + \fI(C++11)\fP operator is overloaded + \fI(function template)\fP + address obtains the address of an object, even if operator& is + \fI(until C++20)\fP overloaded + \fI(public member function of std::allocator)\fP + to_address obtains a raw pointer from a fancy pointer (inverse of + \fB[static]\fP (C++20)(optional) pointer_to) + \fI(public static member function)\fP + to_address obtains a raw pointer from a pointer-like type + (C++20) \fI(function template)\fP diff --git a/man/std::pointer_traits::to_address.3 b/man/std::pointer_traits::to_address.3 new file mode 100644 index 000000000..90e629d19 --- /dev/null +++ b/man/std::pointer_traits::to_address.3 @@ -0,0 +1,31 @@ +.TH std::pointer_traits::to_address 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pointer_traits::to_address \- std::pointer_traits::to_address + +.SH Synopsis + Defined in header + static element_type* to_address( pointer p ) \fI(since C++20)\fP + noexcept; (optional member of program-defined + specialization) + + Constructs a raw pointer that references the same object as its pointer-like ("fancy + pointer") argument. + + This function, if defined, is the inverse of pointer_to, and exists as the + customization point to be called by std::to_address. + +.SH Parameters + + p - fancy pointer/pointer-like object + +.SH Return value + + A raw pointer of the type element_type* that references the same memory location as + the argument p. + +.SH See also + + pointer_to obtains a dereferenceable pointer to its argument + \fB[static]\fP \fI(public static member function)\fP + to_address obtains a raw pointer from a pointer-like type + (C++20) \fI(function template)\fP diff --git a/man/std::poisson_distribution.3 b/man/std::poisson_distribution.3 index d340092ff..00b7b0e66 100644 --- a/man/std::poisson_distribution.3 +++ b/man/std::poisson_distribution.3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution \- std::poisson_distribution + .SH Synopsis Defined in header template< class IntType = int > \fI(since C++11)\fP @@ -7,7 +10,7 @@ Produces random non-negative integer values i, distributed according to discrete probability function: - P(i|μ) = + \\(P(i | \\mu) = \\frac{e^{-\\mu}\\mu^i}{i!}\\)P(i|μ) = e-μ ·μi @@ -17,69 +20,80 @@ the expected, mean number of its occurrence under the same conditions (on the same time/space interval) is μ. + std::poisson_distribution satisfies RandomNumberDistribution. + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + IntType - this is not one of short, int, long, long long, unsigned short, unsigned + int, unsigned long, or unsigned long long. + .SH Member types - Member type Definition - result_type IntType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP IntType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - returns the mean distribution parameter (mean number of occurrences of - mean the event) - \fI(public member function)\fP + mean returns the mean distribution parameter (mean number of occurrences of + \fI(C++11)\fP the event) + \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include #include - #include + #include #include #include + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); - - // if an event occurs 4 times a minute on average - // how often is it that it occurs n times in one minute? + + // If an event occurs 4 times a minute on average, how + // often is it that it occurs n times in one minute? std::poisson_distribution<> d(4); - + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n = 0; n != 10000; ++n) ++hist[d(gen)]; - } - for(auto p : hist) { - std::cout << p.first << - ' ' << std::string(p.second/100, '*') << '\\n'; - } + + for (auto [x, y] : hist) + std::cout << std::hex << x << ' ' + << std::string(y / 100, '*') << '\\n'; } -.SH Output: +.SH Possible output: 0 * 1 ******* @@ -91,11 +105,12 @@ 7 ***** 8 ** 9 * - 10 - 11 - 12 - 13 + a + b + c + d .SH External links - Weisstein, Eric W. "Poisson Distribution." From MathWorld--A Wolfram Web Resource. + Weisstein, Eric W. "Poisson Distribution." From MathWorld — A Wolfram Web + Resource. diff --git a/man/std::poisson_distribution::max.3 b/man/std::poisson_distribution::max.3 index a3ae82c67..e419d493f 100644 --- a/man/std::poisson_distribution::max.3 +++ b/man/std::poisson_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::max \- std::poisson_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::poisson_distribution::mean.3 b/man/std::poisson_distribution::mean.3 index 2184ef5ff..d7251d1da 100644 --- a/man/std::poisson_distribution::mean.3 +++ b/man/std::poisson_distribution::mean.3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution::mean 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::mean 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::mean \- std::poisson_distribution::mean + .SH Synopsis double mean() const; \fI(since C++11)\fP @@ -15,5 +18,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::poisson_distribution::min.3 b/man/std::poisson_distribution::min.3 index 001b42b79..c539ada20 100644 --- a/man/std::poisson_distribution::min.3 +++ b/man/std::poisson_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::min \- std::poisson_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::poisson_distribution::operator().3 b/man/std::poisson_distribution::operator().3 index 24c60d922..72dd44d28 100644 --- a/man/std::poisson_distribution::operator().3 +++ b/man/std::poisson_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::operator() \- std::poisson_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::poisson_distribution::param.3 b/man/std::poisson_distribution::param.3 index 8dfa53eda..ffdade1f0 100644 --- a/man/std::poisson_distribution::param.3 +++ b/man/std::poisson_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::param \- std::poisson_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::poisson_distribution::poisson_distribution.3 b/man/std::poisson_distribution::poisson_distribution.3 index 88b058209..7cf23bf5a 100644 --- a/man/std::poisson_distribution::poisson_distribution.3 +++ b/man/std::poisson_distribution::poisson_distribution.3 @@ -1,11 +1,17 @@ -.TH std::poisson_distribution::poisson_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::poisson_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::poisson_distribution \- std::poisson_distribution::poisson_distribution + .SH Synopsis - explicit poisson_distribution( double mean = 1.0 ); \fB(1)\fP \fI(since C++11)\fP - explicit poisson_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + poisson_distribution() : poisson_distribution(1.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit poisson_distribution( double mean ); \fB(2)\fP \fI(since C++11)\fP + explicit poisson_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses mean as the - distribution parameter, the second version uses params as the distribution - parameter. + 1) Uses 1.0 as the distribution parameter. + 2) Uses mean as the distribution parameter. + 3) Uses params as the distribution parameter. .SH Parameters @@ -15,3 +21,11 @@ .SH Notes Requires that 0 < mean. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::poisson_distribution::reset.3 b/man/std::poisson_distribution::reset.3 index 2585b1375..2376ba7ba 100644 --- a/man/std::poisson_distribution::reset.3 +++ b/man/std::poisson_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::poisson_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::poisson_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::poisson_distribution::reset \- std::poisson_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::polar(std::complex).3 b/man/std::polar(std::complex).3 index 9c3243f24..ad08a7b5c 100644 --- a/man/std::polar(std::complex).3 +++ b/man/std::polar(std::complex).3 @@ -1,11 +1,16 @@ -.TH std::polar(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::polar(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::polar(std::complex) \- std::polar(std::complex) + .SH Synopsis Defined in header template< class T > - complex polar( const T& r, const T& theta = 0 ); + std::complex polar( const T& r, const T& theta = T() ); Returns a complex number with magnitude r and phase angle theta. + The behavior is undefined if r is negative or NaN, or if theta is infinite. + .SH Parameters r - magnitude @@ -13,11 +18,71 @@ .SH Return value - a complex number determined by r and theta + A complex number determined by r and theta. + +.SH Notes + + std::polar(r, theta) is equivalent to any of the following expressions: + + * r * std::exp(theta * 1i) + * r * (cos(theta) + sin(theta) * 1i) + * std::complex(r * cos(theta), r * sin(theta)). + + Using polar instead of exp can be about 4.5x faster in vectorized loops. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + using namespace std::complex_literals; + + int main() + { + constexpr auto π_2{std::numbers::pi / 2.0}; + constexpr auto mag{1.0}; + + std::cout + << std::fixed << std::showpos << std::setprecision(1) + << " θ: │ polar: │ exp: │ complex: │ trig:\\n"; + for (int n{}; n != 4; ++n) + { + const auto θ{n * π_2}; + std::cout << std::setw(4) << 90 * n << "° │ " + << std::polar(mag, θ) << " │ " + << mag * std::exp(θ * 1.0i) << " │ " + << std::complex(mag * cos(θ), mag * sin(θ)) << " │ " + << mag * (cos(θ) + 1.0i * sin(θ)) << '\\n'; + } + } + +.SH Output: + + θ: │ polar: │ exp: │ complex: │ trig: + +0° │ (+1.0,+0.0) │ (+1.0,+0.0) │ (+1.0,+0.0) │ (+1.0,+0.0) + +90° │ (+0.0,+1.0) │ (+0.0,+1.0) │ (+0.0,+1.0) │ (+0.0,+1.0) + +180° │ (-1.0,+0.0) │ (-1.0,+0.0) │ (-1.0,+0.0) │ (-1.0,+0.0) + +270° │ (-0.0,-1.0) │ (-0.0,-1.0) │ (-0.0,-1.0) │ (-0.0,-1.0) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2459 C++98 behavior unclear for some inputs made undefined + LWG 2870 C++98 default value of parameter theta not dependent made dependent .SH See also - arg returns the phase angle - \fI(function template)\fP abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP + \fI(function template)\fP + arg returns the phase angle + \fI(function template)\fP + exp(std::complex) complex base e exponential + \fI(function template)\fP diff --git a/man/std::pop_heap.3 b/man/std::pop_heap.3 index 5812ab6ba..a9a19faa9 100644 --- a/man/std::pop_heap.3 +++ b/man/std::pop_heap.3 @@ -1,100 +1,143 @@ -.TH std::pop_heap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pop_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pop_heap \- std::pop_heap + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP + template< class RandomIt > \fB(1)\fP (constexpr since C++20) void pop_heap( RandomIt first, RandomIt last ); - template< class RandomIt, class Compare > \fB(2)\fP - void pop_heap( RandomIt first, RandomIt last, Compare comp ); + template< class RandomIt, class Compare > + void pop_heap( RandomIt first, RandomIt last, Compare \fB(2)\fP (constexpr since C++20) + comp ); + + Swaps the value in the position first and the value in the position last - 1 and + makes the subrange [first, last - 1) into a heap. This has the effect of removing + the first element from the heap [first, last). + + 1) [first, last) is a heap with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) [first, last) is a heap with respect to comp. + + If [first, last) not a non-empty heap, the behavior is undefined. - Swaps the value in the position first and the value in the position last-1 and makes - the subrange [first, last-1) into a max heap. This has the effect of removing the - first (largest) element from the heap defined by the range [first, last). + If any of the following conditions is satisfied, the behavior is undefined: - The first version of the function uses operator< to compare the elements, the second - uses the given comparison function comp. + * [first, last) is empty. + * [first, last) is not a heap. + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements defining the valid nonempty heap to modify - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the non-empty heap to modify + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. - -.SH Return value - - \fI(none)\fP + Compare must meet the requirements of Compare. .SH Complexity - At most 2×log(N) comparisons where N=std::distance(first, last). - -.SH Notes - - A max heap is a range of elements [f,l) that has the following properties: - - * *f is the largest element in the range - * a new element can be added using std::push_heap() - * the first element can be removed using std::pop_heap() + Given \\(\\scriptsize N\\)N as std::distance(first, last): - The actual arrangement of the elements is implementation defined. + 1) At most \\(\\scriptsize 2\\log(N)\\)2log(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize 2\\log(N)\\)2log(N) applications of the comparison function + comp. .SH Example - + // Run this code - #include #include - + #include + #include + #include + #include + + void println(std::string_view rem, const auto& v) + { + std::cout << rem; + if constexpr (std::is_scalar_v>) + std::cout << v; + else + for (int e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { - std::vector v { 3, 1, 4, 1, 5, 9 }; - + std::vector v{3, 1, 4, 1, 5, 9}; + std::make_heap(v.begin(), v.end()); - - std::cout << "v: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; - + println("after make_heap: ", v); + std::pop_heap(v.begin(), v.end()); // moves the largest to the end - - std::cout << "after pop_heap: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; - + println("after pop_heap: ", v); + int largest = v.back(); - v.pop_back(); // actually removes the largest element - std::cout << "largest element: " << largest << '\\n'; - - std::cout << "heap without largest: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; + println("largest element: ", largest); + + v.pop_back(); // actually removes the largest element + println("after pop_back: ", v); } .SH Output: - v: 9 5 4 1 1 3 - after pop_heap: 5 3 4 1 1 9 + after make_heap: 9 5 4 1 1 3 + after pop_heap: 5 3 4 1 1 9 largest element: 9 - heap without largest: 5 3 4 1 1 + after pop_back: 5 3 4 1 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1205 C++98 the behavior was unclear if the behavior is undefined + [first, last) is empty in this case .SH See also - push_heap adds an element to a max heap - \fI(function template)\fP + push_heap adds an element to a max heap + \fI(function template)\fP + is_heap checks if the given range is a max heap + \fI(C++11)\fP \fI(function template)\fP + is_heap_until finds the largest subrange that is a max heap + \fI(C++11)\fP \fI(function template)\fP + make_heap creates a max heap out of a range of elements + \fI(function template)\fP + sort_heap turns a max heap into a range of elements sorted in ascending order + \fI(function template)\fP + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) diff --git a/man/std::popcount.3 b/man/std::popcount.3 new file mode 100644 index 000000000..fa5bfb9e3 --- /dev/null +++ b/man/std::popcount.3 @@ -0,0 +1,76 @@ +.TH std::popcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::popcount \- std::popcount + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + constexpr int popcount( T x ) noexcept; + + Returns the number of 1 bits in the value of x. + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + +.SH Return value + + The number of 1 bits in the value of x. + +.SH Notes + + The name popcount is a contraction for "population count". + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + static_assert(std::popcount(0xFULL) == 4); + + int main() + { + for (const std::uint8_t x : {0, 0b00011101, 0b11111111}) + std::cout << "popcount( " << std::bitset<8>(x) << " ) = " + << std::popcount(x) << '\\n'; + } + +.SH Output: + + popcount( 00000000 ) = 0 + popcount( 00011101 ) = 4 + popcount( 11111111 ) = 8 + +.SH See also + + countl_zero counts the number of consecutive 0 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countl_one counts the number of consecutive 1 bits, starting from the most + (C++20) significant bit + \fI(function template)\fP + countr_zero counts the number of consecutive 0 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + countr_one counts the number of consecutive 1 bits, starting from the least + (C++20) significant bit + \fI(function template)\fP + has_single_bit checks if a number is an integral power of 2 + (C++20) \fI(function template)\fP + count returns the number of bits set to true + \fI(public member function of std::bitset)\fP + all checks if all, any or none of the bits are set to true + any \fI(public member function of std::bitset)\fP + none diff --git a/man/std::pow(std::complex).3 b/man/std::pow(std::complex).3 index c689f55d3..88b88682c 100644 --- a/man/std::pow(std::complex).3 +++ b/man/std::pow(std::complex).3 @@ -1,45 +1,157 @@ -.TH std::pow(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pow(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pow(std::complex) \- std::pow(std::complex) + .SH Synopsis Defined in header + template< class T > (until + std::complex pow( const std::complex& x, \fB(1)\fP C++11) + int y ); template< class T > - complex pow( const complex& x, const complex& y); + std::complex pow( const std::complex& x, \fB(2)\fP + const std::complex& y ); template< class T > - complex pow( const complex& x, const T& y); + std::complex pow( const std::complex& x, \fB(3)\fP + const T& y ); template< class T > - complex pow( const T& x, const complex& y); - template< class T, class U > \fI(since C++11)\fP - complex pow( const complex& x, const complex& y); - template< class T, class U > \fI(since C++11)\fP - complex pow( const complex& x, const U& y); - template< class T, class U > \fI(since C++11)\fP - complex pow( const T& x, const complex& y); + std::complex pow( const T& x, const \fB(4)\fP + std::complex& y ); + Additional overloads \fI(since C++11)\fP + Defined in header + template< class T1, class T2 > + + std::complex (until + C++23) + pow( const std::complex& x, const + std::complex& y ); + template< class T1, class T2 > + + std::complex> (since + C++23) + pow( const std::complex& x, const + std::complex& y ); + template< class T, class NonComplex > + + std::complex (until + C++23) + pow( const std::complex& x, const + NonComplex& y ); (A) + template< class T, class NonComplex > + + std::complex> (since + C++23) + pow( const std::complex& x, const + NonComplex& y ); (B) + template< class T, class NonComplex > - Computes complex x raised to a complex power y. The operation is defined as exp(y · - log(x) ). A branch cut exists along the negative real axis. + std::complex (until + C++23) + pow( const NonComplex& x, const + std::complex& y ); (C) + template< class T, class NonComplex > - The result of pow(0, 0) is implementation-defined. + std::complex> (since + C++23) + pow( const NonComplex& x, const + std::complex& y ); - \fI(since C++11)\fPAdditional overloads are provided for all arithmetic types, such that + 1-4) Computes complex x raised to a complex power y with a branch cut along the + negative real axis for the first argument. Non-complex arguments are treated as + complex numbers with positive zero imaginary component. - 1. If either argument is long double or std::complex, then both - arguments are cast to std::complex - 2. Otherwise, if either argument is double, std::complex or integer type, - then both arguments are cast to std::complex - 3. Otherwise, if either argument is float or std::complex, then both - arguments are cast to std::complex + A-C) Additional overloads are provided. NonComplex is not a \fI(since C++11)\fP + specialization of std::complex. .SH Parameters - x - base as a complex value - y - exponent as a complex value + x - base + y - exponent .SH Return value - x raised to a power y. + 1-4) If no errors occur, the complex power xy + , is returned. + Errors and special cases are handled as if the operation is implemented by + std::exp(y * std::log(x)). + The result of std::pow(0, 0) is implementation-defined. + A-C) Same as (2-4). + +.SH Notes + + Overload \fB(1)\fP was provided in C++98 to match the extra overloads \fB(2)\fP of std::pow. + Those overloads were removed by the resolution of LWG issue 550, and overload \fB(1)\fP + was removed by the resolution of LWG issue 844. + + The additional overloads are not required to be provided exactly as (A-C). They only + need to be sufficient to ensure that for their first argument base and second + argument exponent: + + If base and/or exponent has type std::complex: + + * If base and/or exponent has type std::complex or long + double, then std::pow(base, exponent) has the same effect as + std::pow(std::complex(base), + std::complex(exponent)). + * Otherwise, if base and/or exponent has type std::complex, (until C++23) + double, or an integer type, then std::pow(base, exponent) has the + same effect as std::pow(std::complex(base), + std::complex(exponent)). + * Otherwise, if base and/or exponent has type std::complex or + float, then std::pow(base, exponent) has the same effect as + std::pow(std::complex(base), + std::complex(exponent)). + If one argument has type std::complex and the other argument has + type T2 or std::complex, then std::pow(base, exponent) has the + same effect as std::pow(std::complex>(base), (since C++23) + std::complex>(exponent)). + + If std::common_type_t is not well-formed, then the program is + ill-formed. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::fixed; + + std::complex z(1.0, 2.0); + std::cout << "(1,2)^2 = " << std::pow(z, 2) << '\\n'; + + std::complex z2(-1.0, 0.0); // square root of -1 + std::cout << "-1^0.5 = " << std::pow(z2, 0.5) << '\\n'; + + std::complex z3(-1.0, -0.0); // other side of the cut + std::cout << "(-1,-0)^0.5 = " << std::pow(z3, 0.5) << '\\n'; + + std::complex i(0.0, 1.0); // i^i = exp(-pi / 2) + std::cout << "i^i = " << std::pow(i, i) << '\\n'; + } + +.SH Output: + + (1,2)^2 = (-3.000000,4.000000) + -1^0.5 = (0.000000,1.000000) + (-1,-0)^0.5 = (0.000000,-1.000000) + i^i = (0.207880,0.000000) .SH See also - exp(std::complex) complex base e exponential - \fI(function template)\fP sqrt(std::complex) complex square root in the range of the right half-plane - \fI(function template)\fP + \fI(function template)\fP + pow + powf raises a number to the given power (\\(\\small{x^y}\\)x^y) + powl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + applies the function std::pow to two valarrays or a valarray and + pow(std::valarray) a value + \fI(function template)\fP + C documentation for + cpow diff --git a/man/std::pow(std::valarray).3 b/man/std::pow(std::valarray).3 index de80507ec..6871aa82a 100644 --- a/man/std::pow(std::valarray).3 +++ b/man/std::pow(std::valarray).3 @@ -1,12 +1,22 @@ -.TH std::pow(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pow(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pow(std::valarray) \- std::pow(std::valarray) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP - valarray pow( const valarray& base, const valarray& exp ); - template< class T > \fB(2)\fP - valarray pow( const valarray& base, const T& vexp ); - template< class T > \fB(3)\fP - valarray pow( const T& vbase, const valarray& exp ); + template< class T > + std::valarray pow( const std::valarray& base, const std::valarray& exp \fB(1)\fP + ); + template< class T > + + std::valarray pow( const std::valarray& base, \fB(2)\fP + + const typename std::valarray::value_type& vexp ); + template< class T > + + std::valarray pow( const typename std::valarray::value_type& vbase, \fB(3)\fP + + const std::valarray& exp ); Raises a value to a power. @@ -34,7 +44,7 @@ .SH Notes Unqualified function (pow) is used to perform the computation. If such function is - not available, std::pow is used due to argument dependent lookup. + not available, std::pow is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -42,23 +52,124 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Example - This section is incomplete - Reason: no example - -.SH See also - pow raises a number to the given power (x^y) - \fI(function)\fP +// Run this code + + #include + #include + #include + #include + #include + + class show + { + friend std::ostream& operator<<(std::ostream& os, show const& r) + { + constexpr char const* sup[] + { + "\\u2070", "\\u00B9", "\\u00B2", "\\u00B3", "\\u2074", + "\\u2075", "\\u2076", "\\u2077", "\\u2078", "\\u2079" + }; + + for (std::size_t n = 0; n != r.bases.size(); ++n) + { + os << std::left << r.bases[n] << std::left; + if (n < r.exponents.size()) + os << sup[r.exponents[n] % 10] << ' '; + else + os << " "; + } + + if (r.results.size() != 0) + { + os << '='; + for (std::size_t n = 0; n != r.results.size(); ++n) + os << ' ' << r.results[n]; + } + + return os << '\\n'; + } + + public: + std::valarray bases{}, exponents{}, results{}; + }; + + int main() + { + constexpr int base{2}; + constexpr int exponent{5}; + const std::valarray bases{1, 2, 3, 4, 5, 6, 7}; + const std::valarray exponents{0, 1, 2, 3, 4, 5, 6}; + const std::valarray powers1 = std::pow(bases, exponents); + const std::valarray powers2 = std::pow(bases, exponent); + const std::valarray powers3 = std::pow(base, exponents); + + std::cout + << "pow(const std::valarray& base, const std::valarray& exp); (1)\\n" + << "base : " << show{bases} + << "exp : " << show{exponents} + << "pow : " << show{bases, exponents, powers1} + << '\\n' + << "pow(const std::valarray& base, const value_type& vexp); (2)\\n" + << "base : " << show{bases} + << "vexp : " << exponent << '\\n' + << "pow : " << show{bases, std::valarray(exponent, bases.size()), powers2} + << '\\n' + << "pow(const value_type& vbase, const std::valarray& exp); (3)\\n" + << "vbase: " << base << '\\n' + << "exp : " << show{exponents} + << "pow : " << show{std::valarray(base, bases.size()), exponents, powers3}; + } + +.SH Output: + + pow(const std::valarray& base, const std::valarray& exp); \fB(1)\fP + base : 1 2 3 4 5 6 7 + exp : 0 1 2 3 4 5 6 + pow : 1⁰ 2¹ 3² 4³ 5⁴ 6⁵ 7⁶ = 1 2 9 64 625 7776 117649 + + pow(const std::valarray& base, const value_type& vexp); \fB(2)\fP + base : 1 2 3 4 5 6 7 + vexp : 5 + pow : 1⁵ 2⁵ 3⁵ 4⁵ 5⁵ 6⁵ 7⁵ = 1 32 243 1024 3125 7776 16807 + + pow(const value_type& vbase, const std::valarray& exp); \fB(3)\fP + vbase: 2 + exp : 0 1 2 3 4 5 6 + pow : 2⁰ 2¹ 2² 2³ 2⁴ 2⁵ 2⁶ = 1 2 4 8 16 32 64 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T is deduced from both the scalar and the only deduce T from the + LWG 3074 C++98 valarray for (2,3), disallowing valarray + mixed-type calls -.SH Category: +.SH See also - * Todo no example + sqrt(std::valarray) applies the function std::sqrt to each element of valarray + \fI(function template)\fP + pow + powf raises a number to the given power (\\(\\small{x^y}\\)x^y) + powl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + pow(std::complex) complex power, one or both arguments may be a complex number + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::pow,std::powf,std::powl.3 b/man/std::pow,std::powf,std::powl.3 new file mode 100644 index 000000000..37bde6052 --- /dev/null +++ b/man/std::pow,std::powf,std::powl.3 @@ -0,0 +1,236 @@ +.TH std::pow,std::powf,std::powl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pow,std::powf,std::powl \- std::pow,std::powf,std::powl + +.SH Synopsis + Defined in header + float pow ( float base, float exp ); + + double pow ( double base, double exp ); (until C++23) + + long double pow ( long double base, long double exp + ); + /* floating-point-type */ + (since C++23) + pow ( /* floating-point-type */ base, (constexpr since C++26) + + /* floating-point-type */ exp ) + float pow ( float base, int exp ); + + double pow ( double base, int exp ); \fB(1)\fP \fB(2)\fP \fI(until C++11)\fP + + long double pow ( long double base, int exp ); + float powf( float base, float exp ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double powl( long double base, long double exp \fB(4)\fP \fI(since C++11)\fP + ); (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) (constexpr since C++26) + + pow ( Arithmetic1 base, Arithmetic2 exp + ); + + 1-4) Computes the value of base raised to the power exp. + The library provides overloads of std::pow for all cv-unqualified floating-point + types as the type of the parameters base and exp. + (since C++23) + + A) Additional overloads are provided for all other combinations of \fI(since C++11)\fP + arithmetic types. + +.SH Parameters + + base - base as a floating-point or integer value + exp - exponent as a floating-point or integer value + +.SH Return value + + If no errors occur, base raised to the power of exp (baseexp + ), is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a pole error or a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or + ±HUGE_VALL is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If base is finite and negative and exp is finite and non-integer, a domain error + occurs and a range error may occur. + + If base is zero and exp is zero, a domain error may occur. + + If base is zero and exp is negative, a domain error or a pole error may occur. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * pow(+0, exp), where exp is a negative odd integer, returns +∞ and raises + FE_DIVBYZERO. + * pow(-0, exp), where exp is a negative odd integer, returns -∞ and raises + FE_DIVBYZERO. + * pow(±0, exp), where exp is negative, finite, and is an even integer or a + non-integer, returns +∞ and raises FE_DIVBYZERO. + * pow(±0, -∞) returns +∞ and may raise FE_DIVBYZERO. + * pow(+0, exp), where exp is a positive odd integer, returns +0. + * pow(-0, exp), where exp is a positive odd integer, returns -0. + * pow(±0, exp), where exp is positive non-integer or a positive even integer, + returns +0. + * pow(-1, ±∞) returns 1. + * pow(+1, exp) returns 1 for any exp, even when exp is NaN. + * pow(base, ±0) returns 1 for any base, even when base is NaN. + * pow(base, exp) returns NaN and raises FE_INVALID if base is finite and negative + and exp is finite and non-integer. + * pow(base, -∞) returns +∞ for any |base| < 1. + * pow(base, -∞) returns +0 for any |base| > 1. + * pow(base, +∞) returns +0 for any |base| < 1. + * pow(base, +∞) returns +∞ for any |base| > 1. + * pow(-∞, exp) returns -0 if exp is a negative odd integer. + * pow(-∞, exp) returns +0 if exp is a negative non-integer or negative even + integer. + * pow(-∞, exp) returns -∞ if exp is a positive odd integer. + * pow(-∞, exp) returns +∞ if exp is a positive non-integer or positive even + integer. + * pow(+∞, exp) returns +0 for any negative exp. + * pow(+∞, exp) returns +∞ for any positive exp. + * except where specified above, if any argument is NaN, NaN is returned. + +.SH Notes + + C++98 added overloads where exp has type int on top of C pow(), and the return type + of std::pow(float, int) was float. However, the additional overloads introduced in + C++11 specify that std::pow(float, int) should return double. LWG issue 550 was + raised to target this conflict, and the resolution is to removed the extra int exp + overloads. + + Although std::pow cannot be used to obtain a root of a negative number, std::cbrt is + provided for the common case where exp is 1/3. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::pow(num1, num2) + has the same effect as std::pow(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::pow(num1, num2) has the same effect as (until C++23) + std::pow(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then std::pow(num1, + num2) has the same effect as std::pow(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::pow(num1, num2) has + the same effect as std::pow(static_cast(num1), + static_cast(num2)), where + /* common-floating-point-type */ is the floating-point type with the + greatest floating-point conversion rank and greatest floating-point + conversion subrank between the types of num1 and num2, arguments of (since C++23) + integer type are considered to have the same floating-point conversion + rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + // typical usage + std::cout << "pow(2, 10) = " << std::pow(2, 10) << '\\n' + << "pow(2, 0.5) = " << std::pow(2, 0.5) << '\\n' + << "pow(-2, -3) = " << std::pow(-2, -3) << '\\n'; + + // special values + std::cout << "pow(-1, NAN) = " << std::pow(-1, NAN) << '\\n' + << "pow(+1, NAN) = " << std::pow(+1, NAN) << '\\n' + << "pow(INFINITY, 2) = " << std::pow(INFINITY, 2) << '\\n' + << "pow(INFINITY, -1) = " << std::pow(INFINITY, -1) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "pow(-1, 1/3) = " << std::pow(-1, 1.0 / 3) << '\\n'; + if (errno == EDOM) + std::cout << " errno == EDOM " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "pow(-0, -3) = " << std::pow(-0.0, -3) << '\\n'; + if (std::fetestexcept(FE_DIVBYZERO)) + std::cout << " FE_DIVBYZERO raised\\n"; + } + +.SH Possible output: + + pow(2, 10) = 1024 + pow(2, 0.5) = 1.41421 + pow(-2, -3) = -0.125 + pow(-1, NAN) = nan + pow(+1, NAN) = 1 + pow(INFINITY, 2) = inf + pow(INFINITY, -1) = 0 + pow(-1, 1/3) = -nan + errno == EDOM Numerical argument out of domain + FE_INVALID raised + pow(-0, -3) = -inf + FE_DIVBYZERO raised + +.SH See also + + sqrt computes square root (\\(\\small{\\sqrt{x}}\\) + sqrtf √ + sqrtl x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + cbrt computes cube root (\\(\\small{\\sqrt[3]{x}}\\) + cbrtf 3 + cbrtl √ + \fI(C++11)\fP x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + computes square root of the sum of the squares of two + or three + \fI(since C++17)\fP given numbers (\\(\\scriptsize{\\sqrt{x^2+y^2}}\\) + √ + hypot x2 + hypotf +y2 + hypotl ) + \fI(C++11)\fP , (\\(\\scriptsize{\\sqrt{x^2+y^2+z^2}}\\) + \fI(C++11)\fP √ + \fI(C++11)\fP x2 + +y2 + +z2 + ) + \fI(since C++17)\fP + \fI(function)\fP + pow(std::complex) complex power, one or both arguments may be a complex number + \fI(function template)\fP + applies the function std::pow to two valarrays or a valarray and + pow(std::valarray) a value + \fI(function template)\fP + C documentation for + pow diff --git a/man/std::pow.3 b/man/std::pow.3 deleted file mode 100644 index 7f49e19de..000000000 --- a/man/std::pow.3 +++ /dev/null @@ -1,75 +0,0 @@ -.TH std::pow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float pow( float base, float exp ); \fB(1)\fP - double pow( double base, double exp ); \fB(2)\fP - long double pow( long double base, long double exp ); \fB(3)\fP - float pow( float base, int iexp ); \fB(4)\fP \fI(until C++11)\fP - double pow( double base, int iexp ); \fB(5)\fP \fI(until C++11)\fP - long double pow( long double base, int iexp ); \fB(6)\fP \fI(until C++11)\fP - Promoted pow( Arithmetic1 base, Arithmetic2 exp ); \fB(7)\fP \fI(since C++11)\fP - - Computes the value of base raised to the power exp or iexp. - - 7) A set of overloads or a function template for all combinations of arguments of - arithmetic type not covered by 1-3). If any argument has integral type, it is cast - to double. If any argument is long double, then the return type Promoted is also - long double, otherwise the return type is always double. - -.SH Parameters - - base - base as a value of floating-point or integral type - exp - exponent as a value of floating-point or integral type - iexp - exponent as integer value - -.SH Return value - - base raised by power (exp or iexp). - - Domain error occurs if base is 0 and exp is less than or equal to 0. NAN is - returned in that case. - - Domain error occurs if base is negative and exp is not an integer value. NAN is - returned in that case. - - Range error occurs if an overflow takes place. HUGEVAL is returned in that case. - - If domain error occurs and math_errhandling & MATH_ERRNO is nonzero, - errno is set to EDOM. - - If domain error occurs and math_errhandling & MATH_ERREXCEPT is - nonzero, FE_INVALID raised. - \fI(since C++11)\fP - If range error occurs and math_errhandling & MATH_ERRNO is nonzero, - errno is set to ERANGE. - - If range error occurs and math_errhandling & MATH_ERREXCEPT is - nonzero, FE_OVERFLOW is raised. - -.SH Notes - - pow(float, int) returns float until C++11 (per overload 4) but returns double since - C++11 (per overload 7) - -.SH See also - - exp returns e raised to the given power (e^x) - \fI(function)\fP - log computes natural (base e) logarithm (to base e) (ln(x)) - \fI(function)\fP - computes square root ( - sqrt √ - x) - \fI(function)\fP - computes cubic root ( - cbrt 3 - \fI(C++11)\fP √ - x) - \fI(function)\fP - pow(std::complex) complex power, one or both arguments may be a complex number - \fI(function template)\fP - applies the function std::pow to two valarrays or a valarray and - pow(std::valarray) a value - \fI(function template)\fP - C documentation for - pow diff --git a/man/std::predicate.3 b/man/std::predicate.3 new file mode 100644 index 000000000..1a0b2c2f1 --- /dev/null +++ b/man/std::predicate.3 @@ -0,0 +1,24 @@ +.TH std::predicate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::predicate \- std::predicate + +.SH Synopsis + Defined in header + template< class F, class... Args > + + concept predicate = \fI(since C++20)\fP + std::regular_invocable && + + boolean-testable>; + + The concept std::predicate specifies that F is a predicate that accepts + arguments whose types and value categories are encoded by Args..., i.e., it can be + invoked with these arguments to produce a boolean-testable result. + + Note that regular_invocable requires the invocation to not modify either the + callable object or the arguments and be equality-preserving. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). diff --git a/man/std::prev.3 b/man/std::prev.3 index 38d62d681..166a55eec 100644 --- a/man/std::prev.3 +++ b/man/std::prev.3 @@ -1,63 +1,93 @@ -.TH std::prev 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::prev 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::prev \- std::prev + .SH Synopsis Defined in header + template< class BidirIt > \fI(since C++11)\fP + BidirIt prev( BidirIt it, typename \fI(until C++17)\fP + std::iterator_traits::difference_type n = 1 ); template< class BidirIt > - BidirIt prev( BidirIt it, \fI(since C++11)\fP + constexpr \fI(since C++17)\fP - typename std::iterator_traits::difference_type - n = 1 ); + BidirIt prev( BidirIt it, typename + std::iterator_traits::difference_type n = 1 ); - Return the nth predecessor of iterator it. + Return the n^th predecessor (or -n^th successor if n is negative) of iterator it. .SH Parameters - it - an iterator - n - number of elements it should be descended + it - an iterator + n - number of elements it should be descended .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Return value - The nth predecessor of iterator it. + An iterator of type BidirIt that holds the n^th predecessor (or -n^th successor if n + is negative) of iterator it. + +.SH Complexity + + Linear. + + However, if BidirIt additionally meets the requirements of + LegacyRandomAccessIterator, complexity is constant. .SH Possible implementation template + constexpr // since C++17 BidirIt prev(BidirIt it, typename std::iterator_traits::difference_type n = 1) { std::advance(it, -n); return it; } +.SH Notes + + Although the expression --c.end() often compiles, it is not guaranteed to do so: + c.end() is an rvalue expression, and there is no iterator requirement that specifies + that decrement of an rvalue is guaranteed to work. In particular, when iterators are + implemented as pointers or its operator-- is lvalue-ref-qualified, --c.end() does + not compile, while std::prev(c.end()) does. + .SH Example - + // Run this code #include #include #include - + int main() { - std::vector v{ 3, 1, 4 }; - + std::vector v{3, 1, 4}; + auto it = v.end(); - auto pv = std::prev(it, 2); - + std::cout << *pv << '\\n'; + + it = v.begin(); + pv = std::prev(it, -2); std::cout << *pv << '\\n'; } .SH Output: 1 + 4 .SH See also - next increment an iterator - \fI(C++11)\fP \fI(function)\fP - advance advances an iterator by given distance - \fI(function)\fP + next increment an iterator + \fI(C++11)\fP \fI(function template)\fP + advance advances an iterator by given distance + \fI(function template)\fP + distance returns the distance between two iterators + \fI(function template)\fP + ranges::prev decrement an iterator by a given distance or to a bound + (C++20) (niebloid) diff --git a/man/std::prev_permutation.3 b/man/std::prev_permutation.3 index 4293a8fa0..5478686e5 100644 --- a/man/std::prev_permutation.3 +++ b/man/std::prev_permutation.3 @@ -1,36 +1,56 @@ -.TH std::prev_permutation 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::prev_permutation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::prev_permutation \- std::prev_permutation + .SH Synopsis Defined in header - template< class BidirIt > \fB(1)\fP - bool prev_permutation( BidirIt first, BidirIt last); - template< class BidirIt, class Compare > \fB(2)\fP - bool prev_permutation( BidirIt first, BidirIt last, Compare comp); - - Transforms the range [first, last) into the previous permutation from the set of all - permutations that are lexicographically ordered with respect to operator< or comp. - Returns true if such permutation exists, otherwise transforms the range into the - last permutation (as if by std::sort(first, last); std::reverse(first, last);) and - returns false. + template< class BidirIt > \fB(1)\fP (constexpr since C++20) + bool prev_permutation( BidirIt first, BidirIt last ); + template< class BidirIt, class Compare > + bool prev_permutation( BidirIt first, BidirIt last, \fB(2)\fP (constexpr since C++20) + Compare comp ); + + Transforms the range [first, last) into the previous permutation. Returns true if + such permutation exists, otherwise transforms the range into the last permutation + (as if by std::sort followed by std::reverse) and returns false. + + 1) The set of all permutations is ordered lexicographically with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) The set of all permutations is ordered lexicographically with respect to comp. + + If + the type of *first is not Swappable + \fI(until C++11)\fP + BidirIt is not ValueSwappable + \fI(since C++11)\fP, the behavior is undefined. .SH Parameters - first, last - the range of elements to permute - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the range of elements to permute + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type BidirIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type BidirIt + can be dereferenced and then implicitly converted to both of them. .SH Type requirements - - BidirIt must meet the requirements of ValueSwappable and BidirectionalIterator. + BidirIt must meet the requirements of ValueSwappable and + LegacyBidirectionalIterator. .SH Return value @@ -43,22 +63,33 @@ .SH Complexity - At most (last-first)/2 swaps. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize \\frac{N}{2}\\) + + N + 2 + + swaps. .SH Possible implementation template bool prev_permutation(BidirIt first, BidirIt last) { - if (first == last) return false; + if (first == last) + return false; BidirIt i = last; - if (first == --i) return false; - - while \fB(1)\fP { + if (first == --i) + return false; + + while \fB(1)\fP + { BidirIt i1, i2; - + i1 = i; - if (*i1 < *--i) { + if (*i1 < *--i) + { i2 = last; while (!(*--i2 < *i)) ; @@ -66,42 +97,60 @@ std::reverse(i1, last); return true; } - if (i == first) { + + if (i == first) + { std::reverse(first, last); return false; } } } +.SH Notes + + Averaged over the entire sequence of permutations, typical implementations use about + 3 comparisons and 1.5 swaps per call. + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + satisfies LegacyContiguousIterator and swapping its value type calls neither + non-trivial special member function nor ADL-found swap. + .SH Example - The following code prints all six permutations of the string "abc" in reverse order + The following code prints all six permutations of the string "cab" in reverse order. + - // Run this code #include - #include #include - #include + #include + int main() { - std::string s="abc"; - std::sort(s.begin(), s.end(), std::greater()); - do { + std::string s = "cab"; + + do + { std::cout << s << ' '; - } while(std::prev_permutation(s.begin(), s.end())); - std::cout << '\\n'; + } + while (std::prev_permutation(s.begin(), s.end())); + + std::cout << s << '\\n'; } .SH Output: - cba cab bca bac acb abc + cab bca bac acb abc cba .SH See also - is_permutation determines if a sequence is a permutation of another sequence - \fI(C++11)\fP \fI(function template)\fP - generates the next smaller lexicographic permutation of a range of - prev_permutation elements - \fI(function template)\fP + is_permutation determines if a sequence is a permutation of another + \fI(C++11)\fP sequence + \fI(function template)\fP + generates the next greater lexicographic permutation of a + next_permutation range of elements + \fI(function template)\fP + ranges::prev_permutation generates the next smaller lexicographic permutation of a + (C++20) range of elements + (niebloid) diff --git a/man/std::print(std::ostream).3 b/man/std::print(std::ostream).3 new file mode 100644 index 000000000..e65e8cc00 --- /dev/null +++ b/man/std::print(std::ostream).3 @@ -0,0 +1,152 @@ +.TH std::print(std::ostream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::print(std::ostream) \- std::print(std::ostream) + +.SH Synopsis + Defined in header + template< class... Args > + void print( std::ostream& os, std::format_string fmt, (since C++23) + Args&&... args ); + + Formats args according to the format string fmt, and inserts the result into os + stream. + + If the ordinary literal encoding is UTF-8, equivalent to: + + * std::vprint_unicode(os, fmt.get(), std::make_format_args(args...));. Otherwise, + * std::vprint_nonunicode(os, fmt.get(), std::make_format_args(args...));. + + The behavior is undefined if std::formatter does not meet the + BasicFormatter requirements for any Ti in Args (as required by + std::make_format_args). + +.SH Parameters + + os - output stream to insert data into + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * Propagate any exception thrown by any formatter, e.g. std::format_error, without + regard to the value of os.exceptions() and without turning on ios_base::badbit + in the error state of os. + * May throw ios_base::failure caused by os.setstate(ios_base::badbit) which is + called if an insertion into os fails. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_print 202207L (C++23) Formatted output + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + std::array buf; + std::format_to(buf.begin(), "{:.15f}", std::numbers::sqrt2); + + unsigned num{}, sum{}; + + auto v = buf + | std::views::filter(isdigit) + | std::views::transform([](char x) { return x - '0'; }) + | std::views::take_while([&sum](char) { return sum < 42; }); + + for (auto n : v) + sum += n, ++num; + + std::stringstream stream; + + #ifdef __cpp_lib_print + std::print(stream, + #else + stream << std::format( + #endif + "√2 = {}...\\n" + "The sum of its first {} digits is {}{}", + std::numbers::sqrt2, num, sum, '.' + ); + + std::puts(stream.str().data()); + } + +.SH Output: + + √2 = 1.4142135623730951... + The sum of its first 13 digits is 42. + +.SH See also + + println(std::ostream) outputs formatted representation of the arguments with + (C++23) appended '\\n' + \fI(function template)\fP + print prints to stdout or a file stream using formatted + (C++23) representation of the arguments + \fI(function template)\fP + format stores formatted representation of the arguments in a new + (C++20) string + \fI(function template)\fP diff --git a/man/std::print.3 b/man/std::print.3 new file mode 100644 index 000000000..49cedc1b4 --- /dev/null +++ b/man/std::print.3 @@ -0,0 +1,140 @@ +.TH std::print 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::print \- std::print + +.SH Synopsis + Defined in header + template< class... Args > \fB(1)\fP (since C++23) + void print( std::format_string fmt, Args&&... args ); + template< class... Args > + + void print( std::FILE* stream, \fB(2)\fP (since C++23) + + std::format_string fmt, Args&&... args ); + + Format args according to the format string fmt, and print the result to an output + stream. + + 1) Equivalent to std::print(stdout, fmt, std::forward(args)...). + 2) If the ordinary literal encoding is UTF-8, equivalent to + (std::enable_nonlocking_formatter_optimization> && ...) + ? std::vprint_unicode_locking(stream, fmt.str, make_format_args(args...)) + : std::vprint_unicode(stream, fmt.str, make_format_args(args...));. + Otherwise, equivalent to + (std::enable_nonlocking_formatter_optimization> && ...) + ? std::vprint_nonunicode_locking(stream, fmt.str, make_format_args(args...)) + : std::vprint_nonunicode(stream, fmt.str, make_format_args(args...));. + + The behavior is undefined if std::formatter does not meet the + BasicFormatter requirements for any Ti in Args (as required by + std::make_format_args). + +.SH Parameters + + stream - output file stream to write to + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * std::system_error, if writing to the stream fails. + * Propagates any exception thrown by used formatters, e.g. std::format_error. + +.SH Notes + + Feature-test macro Value Std Feature + 202207L (C++23) Formatted output + __cpp_lib_print 202403L (C++26) Formatted output with stream locking + (DR23) + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::print("{0} {2}{1}!\\n", "Hello", 23, "C++"); // overload (2) + + const auto tmp {std::filesystem::temp_directory_path() / "test.txt"}; + + if (std::FILE* stream{std::fopen(tmp.c_str(), "w")}) + { + std::print(stream, "File: {}", tmp.string()); // overload (1) + std::fclose(stream); + } + } + +.SH Output: + + Hello C++23! + +.SH See also + + println same as std::print except that each print is terminated by + (C++23) additional new line + \fI(function template)\fP + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP + format_to writes out formatted representation of its arguments through an + (C++20) output iterator + \fI(function template)\fP + printf + fprintf prints formatted output to stdout, a file stream or a buffer + sprintf \fI(function)\fP + snprintf + \fI(C++11)\fP diff --git a/man/std::printf,std::fprintf,std::sprintf,std::snprintf.3 b/man/std::printf,std::fprintf,std::sprintf,std::snprintf.3 index 8c331c8ca..9796a9a29 100644 --- a/man/std::printf,std::fprintf,std::sprintf,std::snprintf.3 +++ b/man/std::printf,std::fprintf,std::sprintf,std::snprintf.3 @@ -1,11 +1,14 @@ -.TH std::printf,std::fprintf,std::sprintf,std::snprintf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::printf,std::fprintf,std::sprintf,std::snprintf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::printf,std::fprintf,std::sprintf,std::snprintf \- std::printf,std::fprintf,std::sprintf,std::snprintf + .SH Synopsis Defined in header int printf( const char* format, ... ); \fB(1)\fP int fprintf( std::FILE* stream, const char* format, ... ); \fB(2)\fP int sprintf( char* buffer, const char* format, ... ); \fB(3)\fP - int snprintf( char* buffer, int buf_size, const char* format, ... \fB(4)\fP \fI(since C++11)\fP - ); + int snprintf( char* buffer, std::size_t buf_size, const char* \fB(4)\fP \fI(since C++11)\fP + format, ... ); Loads the data from the given locations, converts them to character string equivalents and writes the results to a variety of sinks. @@ -15,521 +18,608 @@ 3) Writes the results to a character string buffer. 4) Writes the results to a character string buffer. At most buf_size - 1 characters are written. The resulting character string will be terminated with a null - character, unless buf_size is zero. + character, unless buf_size is zero. If buf_size is zero, nothing is written and + buffer may be a null pointer, however the return value (number of bytes that would + be written not including the null terminator) is still calculated and returned. + + If a call to sprintf or snprintf causes copying to take place between objects that + overlap, the behavior is undefined (e.g. sprintf(buf, "%s text", buf);). .SH Parameters -stream - output file stream to write to -buffer - pointer to a character string to write to -buf_size - up to buf_size - 1 characters may be written, plus the null terminator - pointer to a null-terminated multibyte string specifying how to interpret the data. - - The format string consists of ordinary characters (except %), which are copied unchanged into the output - stream, and conversion specifications. Each conversion specification has the following format: - - * introductory % character - - * (optional) one or more flags that modify the behavior of the conversion: - - * -: the result of the conversion is left-justified within the field (by default it is - right-justified) - * +: the sign of signed conversions is always prepended to the result of the conversion (by default - the result is preceded by minus only when it is negative) - * space: if the result of a signed conversion does not start with a sign character, or is empty, space - is prepended to the result. It is ignored if + flag is present. - * # : alternative form of the conversion is performed. See the table below for exact effects. - * 0 : for integer and floating point number conversions, leading zeros are used to pad the field - instead of space characters. For floating point numbers it is ignored if the precision is explicitly - specified. For other conversions using this flag results in undefined behavior. It is ignored if - - flag is present. - - * (optional) integer value or * that specifies minimum field width. The result is padded with space - characters (by default), if required, on the left when right-justified, or on the right if - left-justified. In the case when * is used, the width is specified by an additional argument of type - int. If the value of the argument is negative, it results with the - flag specified and positive - field width. - - * (optional) . followed by integer number or * that specifies precision of the conversion. In the case - when * is used, the precision is specified by an additional argument of type int. If the value of - this argument is negative, it is ignored. See the table below for exact effects of precision. - - * (optional) length modifier that specifies the size of the argument - - * conversion format specifier - - The following format specifiers are available: - - Conversion Explanation Argument type - specifier - length modifier hh h \fI(none)\fP l ll j z t L - writes literal - %. The full - % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A - specification - must be %%. - writes a - c single N/A N/A char wchar_t N/A N/A N/A N/A N/A - character - writes a - character - string. - - s Precision N/A N/A char* wchar_t* N/A N/A N/A N/A N/A - specifies the - maximum number - of bytes to be - written. - converts a - signed decimal - integer in the - style [-]dddd. - - Precision - specifies the - minimum number - of digits to - d appear. The - i default N/A - precision is - 1. - If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. - converts a - signed octal - integer in the - style [-]oooo. - - Precision - specifies the signed signed signed signed signed - minimum number char short int long long intmax_t - of digits to long - appear. The - default - precision is - 1. If both the - converted - value and the - precision are - 0 the - o conversion N/A - results in no - characters. In - the - alternative - implementation - precision is - increased if - necessary, to - write one - leading zero. - In that case - if both the - converted - value and the - precision are - 0, single - 0 is - written. - converts a size_t ptrdiff_t - signed - hexadecimal - integer in the - style [-]hhhh. - - For the x - conversion - letters abcdef - are used. - For the X - conversion - letters ABCDEF - are used. - Precision - specifies the - minimum number - of digits to - x appear. The N/A - X default - precision is - 1. If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. In unsigned unsigned unsigned unsigned unsigned - the char short int long long uintmax_t - alternative long - implementation - 0x or 0X is - prefixed to - results if the - converted - value is - nonzero. - converts an - unsigned - decimal - integer in the - style dddd. - - Precision - specifies the - minimum number - of digits to - u appear. The N/A - default - precision is - 1. If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. - converts - floating-point - number to the - decimal - notation in - the style - [-]ddd.ddd. - - Precision - specifies the - minimum number - of digits to - appear after - the decimal - f point - F character. The N/A N/A N/A N/A N/A N/A - default - precision is - 6. In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to the -format - decimal - exponent - notation. - - For the e - conversion - style - [-]d.ddde±dd - is used. - For the E - conversion - style - [-]d.dddE±dd - is used. - The exponent - contains at - least two - digits, more - digits are - used only if - necessary. If - e the value is - E 0, the N/A N/A N/A N/A N/A N/A - exponent is - also 0. - Precision - specifies the - minimum number - of digits to - appear after - the decimal - point - character. The - default - precision is - 6. In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to the - hexadecimal - exponent - notation. - - For the a - conversion - style - [-]0xh.hhhp±d - is used. - For the A - conversion - style - [-]0Xh.hhhP±d - is used. - The first - hexadecimal - digit is 0 if - the argument - is not a - normalized - floating point double double long - value. If the double - value is 0, - a the exponent - A is also 0. N/A N/A N/A N/A N/A N/A - Precision - specifies the - minimum number - of digits to - appear after - the decimal - point - character. The - default - precision is - sufficient for - exact - representation - of the value. - In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to - decimal or - decimal - exponent - notation - depending on - the value and - the precision. - - For the g - conversion - style - conversion - with style e - or f will be - performed. - For the G - conversion - style - conversion - with style E - or F will be - performed. - Let P equal - the precision - if nonzero, 6 - if the - precision is - not specified, - or 1 if the - precision is - 0. Then, if - a conversion - with style E - g would have an - G exponent of X: N/A N/A N/A N/A N/A N/A - - * if P > X ≥ - −4, the - conversion - is with - style f or - F and - precision - P − 1 − X. - * otherwise, - the - conversion - is with - style e or - E and - precision - P − 1. - - Unless - alternative - representation - is requested - the trailing - zeros are - removed, also - the decimal - point - character is - removed if no - fractional - part is left. - For infinity - and - not-a-number - conversion - style see - notes. - returns the - number of - characters - written so far - by this call - to the - function. - n N/A N/A int* N/A N/A N/A N/A N/A N/A - The result is - written to the - value pointed - to by the - argument. The - complete - specification - must be %n. - writes an - implementation - defined - p character N/A N/A void* N/A N/A N/A N/A N/A N/A - sequence - defining a - pointer. -.SH Notes: - - The floating point conversion functions convert infinity to inf or infinity. Which one is used is - implementation defined. - Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined. - The conversions F, E, G, A output INF, INFINITY, NAN instead. - The correct conversion specifiers for the fixed-width character types (std:int8_t, etc) are defined in - the header - arguments specifying data to print. If any argument is not the type expected by the corresponding -... - conversion specifier, or if there are less arguments than required by format, the behavior is undefined. - If there are more arguments than required by format, the extraneous arguments are evaluated and ignored + stream - output file stream to write to + buffer - pointer to a character string to write to + buf_size - up to buf_size - 1 characters may be written, plus the null terminator + format - pointer to a null-terminated multibyte string specifying how to interpret + the data + arguments specifying data to print. If any argument after default + conversions is not the type expected by the corresponding conversion + ... - specifier, or if there are fewer arguments than required by format, the + behavior is undefined. If there are more arguments than required by + format, the extraneous arguments are evaluated and ignored + + The format string consists of ordinary byte characters (except %), which are copied + unchanged into the output stream, and conversion specifications. Each conversion + specification has the following format: + + * introductory % character. + + * (optional) one or more flags that modify the behavior of the conversion: + + * -: the result of the conversion is left-justified within the field (by default + it is right-justified). + * +: the sign of signed conversions is always prepended to the result of the + conversion (by default the result is preceded by minus only when it is + negative). + * space: if the result of a signed conversion does not start with a sign + character, or is empty, space is prepended to the result. It is ignored if + + flag is present. + * #: alternative form of the conversion is performed. See the table below for + exact effects otherwise the behavior is undefined. + * 0: for integer and floating-point number conversions, leading zeros are used to + pad the field instead of space characters. For integer numbers it is ignored if + the precision is explicitly specified. For other conversions using this flag + results in undefined behavior. It is ignored if - flag is present. + + * (optional) integer value or * that specifies minimum field width. The result is + padded with space characters (by default), if required, on the left when + right-justified, or on the right if left-justified. In the case when * is used, + the width is specified by an additional argument of type int, which appears + before the argument to be converted and the argument supplying precision if one + is supplied. If the value of the argument is negative, it results with the - + flag specified and positive field width (Note: This is the minimum width: The + value is never truncated.). + + * (optional) . followed by integer number or *, or neither that specifies + precision of the conversion. In the case when * is used, the precision is + specified by an additional argument of type int, which appears before the + argument to be converted, but after the argument supplying minimum field width + if one is supplied. If the value of this argument is negative, it is ignored. If + neither a number nor * is used, the precision is taken as zero. See the table + below for exact effects of precision. + + * (optional) length modifier that specifies the size of the argument (in + combination with the conversion format specifier, it specifies the type of the + corresponding argument). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Expected +Specifier Argument Type + Length hh ll j z t + Modifier→ h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + Writes literal + %. The full + % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A + specification + must be %%. + Writes a single + character. + + The argument is + first converted + to unsigned + char. If the l + c modifier is N/A N/A int wint_t N/A N/A N/A N/A N/A + used, the + argument is + first converted + to a character + string as if by + %ls with a + wchar_t[2] + argument. + Writes a + character string + + The argument + must be a + pointer to the + initial element + of an array of + characters. + Precision + specifies the + maximum number + of bytes to be + written. If + Precision is not + specified, + writes every + s byte up to and N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + not including + the first null + terminator. If + the l specifier + is used, the + argument must be + a pointer to the + initial element + of an array of + wchar_t, which + is converted to + char array as if + by a call to + wcrtomb with + zero-initialized + conversion + state. + Converts a + signed integer + into decimal + representation + [-]dddd. + + Precision + specifies the + minimum number + of digits to + d appear. The signed short int long long intmax_t signed ptrdiff_t N/A + i default char long size_t + precision is 1. + + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts an + unsigned integer + into octal + representation + oooo. + + Precision + specifies the + minimum number + of digits to + appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + o the conversion N/A + results in no + characters. In + the alternative + implementation + precision is + increased if + necessary, to + write one + leading zero. In + that case if + both the + converted value + and the + precision are 0, + single 0 is + written. + + Converts an + unsigned integer + into hexadecimal + representation + hhhh. + + For the x + conversion + letters abcdef + are used. unsigned unsigned + For the X unsigned unsigned unsigned unsigned long long uintmax_t size_t version of + conversion char short int long ptrdiff_t + letters ABCDEF + are used. + Precision + specifies the + minimum number + x of digits to N/A + X appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. In + the alternative + implementation + 0x or 0X is + prefixed to + results if the + converted value + is nonzero. + + Converts an + unsigned integer + into decimal + representation + dddd. + + Precision + specifies the + minimum number + of digits to + u appear. The N/A + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts + floating-point + number to the + decimal notation + in the style + [-]ddd.ddd. + + Precision + specifies the + exact number of + digits to appear + after the + f decimal point + F character. The N/A N/A N/A N/A N/A N/A + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + decimal exponent + notation. + + For the e + conversion style + [-]d.ddde±dd is + used. + For the E + conversion style + [-]d.dddE±dd is + used. + The exponent + contains at + least two + digits, more + digits are used + only if + necessary. If + e the value is 0, N/A N/A N/A N/A N/A N/A + E the exponent is + also 0. + Precision + specifies the + exact number of + digits to appear + after the + decimal point + character. The + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + hexadecimal + exponent + notation. + + For the a + conversion style + [-]0xh.hhhp±d is + used. + For the A + conversion style + [-]0Xh.hhhP±d is + used. + The first + hexadecimal + digit is not 0 + if the argument + is a normalized + floating-point + value. If the double double\fI(C++11)\fP long + a value is 0, the double + A exponent is also N/A N/A N/A N/A N/A N/A + 0. Precision + \fI(C++11)\fP specifies the + exact number of + digits to appear + after the + hexadecimal + point character. + The default + precision is + sufficient for + exact + representation + of the value. In + the alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + + Converts + floating-point + number to + decimal or + decimal exponent + notation + depending on the + value and the + precision. + + For the g + conversion style + conversion with + style e or f + will be + performed. + For the G + conversion style + conversion with + style E or F + will be + performed. + Let P equal the + precision if + nonzero, 6 if + the precision is + not specified, + or 1 if the + precision is 0. + Then, if a + conversion with + style E would + g have an exponent + G of X: N/A N/A N/A N/A N/A N/A + + * if P > X ≥ + −4, the + conversion + is with + style f or F + and + precision P + − 1 − X. + * otherwise, + the + conversion + is with + style e or E + and + precision P + − 1. + + Unless + alternative + representation + is requested the + trailing zeros + are removed, + also the decimal + point character + is removed if no + fractional part + is left. For + infinity and + not-a-number + conversion style + see notes. + Returns the + number of + characters + written so far + by this call to + the function. + + The result is signed long signed + n written to the char* short* int* long* long* intmax_t* size_t* ptrdiff_t* N/A + value pointed to + by the argument. + The + specification + may not contain + any flag, field + width, or + precision. + Writes an + implementation + defined + p character N/A N/A void* N/A N/A N/A N/A N/A N/A + sequence + defining a + pointer. + + The floating-point conversion functions convert infinity to inf or infinity. Which + one is used is implementation defined. + + Not-a-number is converted to nan or nan(char_sequence). Which one is used is + implementation defined. + + The conversions F, E, G, A output INF, INFINITY, NAN instead. + + Even though %c expects int argument, it is safe to pass a char because of the + integer promotion that takes place when a variadic function is called. + + The correct conversion specifications for the fixed-width character types (int8_t, + etc) are defined in the header (although PRIdMAX, PRIuMAX, etc is + synonymous with %jd, %ju, etc). + + The memory-writing conversion specifier %n is a common target of security exploits + where format strings depend on user input and is not supported by the bounds-checked + printf_s family of functions. + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple %n results in the same variable or, as an edge case, + printing a string modified by an earlier %n within the same call. + + If a conversion specification is invalid, the behavior is undefined. .SH Return value - 1-2) Number of characters written if successful or negative value if an error + 1,2) Number of characters written if successful or a negative value if an error occurred. - 3) Number of characters written if successful (not including the terminating - null-byte) or negative value if an error occurred. - 4) Number of characters written if successful (not including the terminating - null-byte) or negative value if an error occurred. If the resulting string gets - truncated due to buf_size limit, function returns the total number of characters - (not including the terminating null-byte) which would have been written, if the - limit was not imposed. + 3) Number of characters written if successful (not including the terminating null + character) or a negative value if an error occurred. + 4) Number of characters that would have been written for a sufficiently large buffer + if successful (not including the terminating null character), or a negative value if + an error occurred. Thus, the (null-terminated) output has been completely written if + and only if the returned value is nonnegative and less than buf_size. + +.SH Notes + + POSIX specifies that errno is set on error. It also specifies additional conversion + specifications, most notably support for argument reordering (n$ immediately after % + indicates n^th argument). + + Calling std::snprintf with zero buf_size and null pointer for buffer is useful (when + the overhead of double-call is acceptable) to determine the necessary buffer size to + contain the output: + + auto fmt = "sqrt\fB(2)\fP = %f"; + int sz = std::snprintf(nullptr, 0, fmt, std::sqrt\fB(2)\fP); + std::vector buf(sz + 1); // note +1 for null terminator + std::sprintf(buf.data(), fmt, std::sqrt\fB(2)\fP); // certain to fit .SH Example - + // Run this code + #include + #include #include #include - #include - #include - + int main() { - std::printf("Strings:\\n"); - const char* s = "Hello"; - std::printf("\\t.%10s.\\n\\t.%-10s.\\n\\t.%*s.\\n", s, s, 10, s); - - std::printf("Characters:\\t%c %%\\n", 65); - - std::printf("Integers\\n"); - std::printf("Decimal:\\t%i %d %.6i %i %.0i %+i %u\\n", 1, 2, 3, 0, 0, 4, -1); - std::printf("Hexadecimal:\\t%x %x %X %#x\\n", 5, 10, 10, 6); - std::printf("Octal:\\t%o %#o %#o\\n", 10, 10, 4); - - std::printf("Floating point\\n"); - std::printf("Rounding:\\t%f %.0f %.32f\\n", 1.5, 1.5, 1.3); - std::printf("Padding:\\t%05.2f %.2f %5.2f\\n", 1.5, 1.5, 1.5); - std::printf("Scientific:\\t%E %e\\n", 1.5, 1.5); - std::printf("Hexadecimal:\\t%a %A\\n", 1.5, 1.5); - std::printf("Special values:\\t0/0=%g 1/0=%g\\n", 0./0, 1./0); - + std::printf("Strings:\\n"); // same as std::puts("Strings:"); + std::printf("\\t[%10s]\\n", s); + std::printf("\\t[%-10s]\\n", s); + std::printf("\\t[%*s]\\n", 10, s); + std::printf("\\t[%-10.*s]\\n", 4, s); + std::printf("\\t[%-*.*s]\\n", 10, 4, s); + + std::printf("Characters:\\t%c %%\\n", 'A'); + + std::printf("Integers:\\n"); + std::printf("\\tDecimal: \\t%i %d %.6i %i %.0i %+i %i\\n", + 1, 2, 3, 0, 0, 4,-4); + std::printf("\\tHexadecimal:\\t%x %x %X %#x\\n", + 5,10,10, 6); + std::printf("\\tOctal: \\t%o %#o %#o\\n", + 10, 10, 4); + + std::printf("Floating point:\\n"); + std::printf("\\tRounding:\\t%f %.0f %.32f\\n", 1.5, 1.5, 1.3); + std::printf("\\tPadding:\\t%05.2f %.2f %5.2f\\n", 1.5, 1.5, 1.5); + std::printf("\\tScientific:\\t%E %e\\n", 1.5, 1.5); + std::printf("\\tHexadecimal:\\t%a %A\\n", 1.5, 1.5); + std::printf("\\tSpecial values:\\t0/0=%g 1/0=%g\\n", 0.0/0.0, 1.0/0.0); + std::printf("Variable width control:\\n"); - std::printf("right-justified variable width: '%*c'\\n", 5, 'x'); - int r = std::printf("left-justified variable width : '%*c'\\n", -5, 'x'); + std::printf("\\tright-justified variable width: '%*c'\\n", 5, 'x'); + int r = std::printf("\\tleft-justified variable width : '%*c'\\n", -5, 'x'); std::printf("(the last printf printed %d characters)\\n", r); - - // fixed-width types + + std::printf("Fixed-width types:\\n"); std::uint32_t val = std::numeric_limits::max(); - std::printf("Largest 32-bit value is %" PRIu32 " or %#" PRIx32 "\\n", val, val); + std::printf("\\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\\n", + val, val); } -.SH Output: +.SH Possible output: Strings: - . Hello. - .Hello . - . Hello. + [ Hello] + [Hello ] + [ Hello] + [Hell ] + [Hell ] Characters: A % - Integers - Decimal: 1 2 000003 0 +4 4294967295 - Hexadecimal: 5 a A 0x6 - Octal: 12 012 04 - Floating point - Rounding: 1.500000 2 1.30000000000000004440892098500626 - Padding: 01.50 1.50 1.50 - Scientific: 1.500000E+00 1.500000e+00 - Hexadecimal: 0x1.8p+0 0X1.8P+0 - Special values: 0/0=nan 1/0=inf + Integers: + Decimal: 1 2 000003 0 +4 -4 + Hexadecimal: 5 a A 0x6 + Octal: 12 012 04 + Floating point: + Rounding: 1.500000 2 1.30000000000000004440892098500626 + Padding: 01.50 1.50 1.50 + Scientific: 1.500000E+00 1.500000e+00 + Hexadecimal: 0x1.8p+0 0X1.8P+0 + Special values: 0/0=-nan 1/0=inf Variable width control: - right-justified variable width: ' x' - left-justified variable width : 'x ' - (the last printf printed 40 characters) - Largest 32-bit value is 4294967295 or 0xffffffff + right-justified variable width: ' x' + left-justified variable width : 'x ' + (the last printf printed 41 characters) + Fixed-width types: + Largest 32-bit value is 4294967295 or 0xffffffff .SH See also + wprintf prints formatted wide character output to stdout, a file stream or a + fwprintf buffer + swprintf \fI(function)\fP vprintf vfprintf prints formatted output to stdout, a file stream or a buffer vsprintf using variable argument list - vsnprintf \fI(function)\fP + vsnprintf \fI(function)\fP \fI(C++11)\fP fputs writes a character string to a file stream - \fI(function)\fP + \fI(function)\fP scanf reads formatted input from stdin, a file stream or a buffer - fscanf \fI(function)\fP + fscanf \fI(function)\fP sscanf + to_chars converts an integer or floating-point value to a character sequence + \fI(C++17)\fP \fI(function)\fP + print prints to stdout or a file stream using formatted representation of the + (C++23) arguments + \fI(function template)\fP + println same as std::print except that each print is terminated by additional new + (C++23) line + \fI(function template)\fP C documentation for printf, fprintf, diff --git a/man/std::println(std::ostream).3 b/man/std::println(std::ostream).3 new file mode 100644 index 000000000..505f9c95b --- /dev/null +++ b/man/std::println(std::ostream).3 @@ -0,0 +1,112 @@ +.TH std::println(std::ostream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::println(std::ostream) \- std::println(std::ostream) + +.SH Synopsis + Defined in header + template< class... Args > + void println( std::ostream& os, std::format_string fmt, \fB(1)\fP (since C++23) + Args&&... args ); + void println( std::ostream& os ); \fB(2)\fP (since C++26) + + Formats args according to the format string fmt with appended '\\n' (which means that + each output ends with a new-line), and inserts the result into os stream. + + 1) Equivalent to: std::print(os, "{}\\n", std::format(fmt, args...)); + 2) Equivalent to: std::print(os, "\\n"); + + The behavior is undefined if std::formatter does not meet the + BasicFormatter requirements for any Ti in Args (as required by + std::make_format_args). + +.SH Parameters + + os - output stream to insert data into + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * Propagate any exception thrown by any formatter, e.g. std::format_error, without + regard to the value of os.exceptions() and without turning on ios_base::badbit + in the error state of os. + * May throw ios_base::failure caused by os.setstate(ios_base::badbit) which is + called if an insertion into os fails. + +.SH Notes + + Although overload \fB(2)\fP is added in C++26, all known implementations make it available + in C++23 mode. + + Feature-test macro Value Std Feature + __cpp_lib_print 202207L (C++23) Formatted output + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + println same as std::print except that each print is terminated by + (C++23) additional new line + \fI(function template)\fP + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::println.3 b/man/std::println.3 new file mode 100644 index 000000000..4ee88323c --- /dev/null +++ b/man/std::println.3 @@ -0,0 +1,141 @@ +.TH std::println 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::println \- std::println + +.SH Synopsis + Defined in header + template< class... Args > \fB(1)\fP (since C++23) + void println( std::format_string fmt, Args&&... args ); + template< class... Args > + + void println( std::FILE* stream, \fB(2)\fP (since C++23) + + std::format_string fmt, Args&&... args ); + void println(); \fB(3)\fP (since C++26) + void println( std::FILE* stream ); \fB(4)\fP (since C++26) + + Format args according to the format string fmt with appended '\\n' (which means that + each output ends with a new-line), and print the result to a stream. + + 1) Equivalent to std::println(stdout, fmt, std::forward(args)...). + 2) Equivalent to std::print(stream, std::runtime_format(std::string(fmt.get()) + + '\\n'), + std::forward(args)...). + 3) Equivalent to std::println(stdout). + 4) Equivalent to std::print(stream, "\\n"). + + The behavior is undefined if std::formatter does not meet the + BasicFormatter requirements for any Ti in Args (as required by + std::make_format_args). + +.SH Parameters + + stream - output file stream to write to + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to + the output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is + to be used for formatting; if it is omitted, the arguments + are used in order. + arg-id - + The arg-id s in a format string must all be present or all + be omitted. Mixing manual and automatic indexing is an + error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification + is interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see (since C++23) + thread id format specification and stacktrace entry + format specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format (since C++26) + specification. + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args... - arguments to be formatted + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * std::system_error, if writing to the stream fails. + * Propagates any exception thrown by used formatters, e.g. std::format_error. + +.SH Notes + + Although overloads (3,4) are added in C++26, all known implementations make them + available in C++23 mode. + + Feature-test macro Value Std Feature + 202207L (C++23) Formatted output + __cpp_lib_print 202403L (C++26) Formatted output with stream locking + (DR23) + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + +// Run this code + + #include + + int main() + { + // Each call to std::println ends with new-line + std::println("Please"); // overload (1) + std::println("enter"); // (1) + + std::print("pass"); + std::print("word"); + + std::println(); // (3); valid since C++26; same effect as std::print("\\n"); + } + +.SH Output: + + Please + enter + password + + +.SH See also + + print prints to stdout or a file stream using formatted + (C++23) representation of the arguments + \fI(function template)\fP + println(std::ostream) outputs formatted representation of the arguments with + (C++23) appended '\\n' + \fI(function template)\fP + format stores formatted representation of the arguments in a new + (C++20) string + \fI(function template)\fP + printf + fprintf prints formatted output to stdout, a file stream or a buffer + sprintf \fI(function)\fP + snprintf + \fI(C++11)\fP diff --git a/man/std::priority_queue.3 b/man/std::priority_queue.3 index 1e39271c2..625014f2c 100644 --- a/man/std::priority_queue.3 +++ b/man/std::priority_queue.3 @@ -1,4 +1,7 @@ -.TH std::priority_queue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue \- std::priority_queue + .SH Synopsis Defined in header template< @@ -9,59 +12,209 @@ > class priority_queue; - A priority queue is a container adaptor that provides constant time maximum (or - minimum, depending on Compare) extraction at the expense of logarithmic insertion. + The priority queue is a container adaptor that provides constant time lookup of the + largest (by default) element, at the expense of logarithmic insertion and + extraction. + + A user-provided Compare can be supplied to change the ordering, e.g. using + std::greater would cause the smallest element to appear as the top(). Working with a priority_queue is similar to managing a heap in some random access container, with the benefit of not being able to accidentally invalidate the heap. +.SH Template parameters + + T - The type of the stored elements. The program is ill-formed if T is not + the same type as Container::value_type. + The type of the underlying container to use to store the elements. The + container must satisfy the requirements of SequenceContainer, and its + iterators must satisfy the requirements of LegacyRandomAccessIterator. + Additionally, it must provide the following functions with the usual + semantics: + Container - * front(), e.g., std::vector::front(), + * push_back(), e.g., std::deque::push_back(), + * pop_back(), e.g., std::vector::pop_back(). + + The standard containers std::vector (including std::vector) and + std::deque satisfy these requirements. + A Compare type providing a strict weak ordering. + + Note that the Compare parameter is defined such that it returns true if + Compare - its first argument comes before its second argument in a weak ordering. + But because the priority queue outputs largest elements first, the + elements that "come before" are actually output last. That is, the front + of the queue contains the "last" element according to the weak ordering + imposed by Compare. + .SH Member types Member type Definition - container_type Container - value_type Container::value_type - size_type Container::size_type - reference Container::reference - const_reference Container::const_reference + container_type Container + value_compare Compare + value_type Container::value_type + size_type Container::size_type + reference Container::reference + const_reference Container::const_reference + +.SH Member objects + + Member name Definition + Container c the underlying container + \fI(protected member object)\fP + Compare comp the comparison function object + \fI(protected member object)\fP .SH Member functions constructor constructs the priority_queue - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the priority_queue - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container adaptor - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access top accesses the top element - \fI(public member function)\fP + \fI(public member function)\fP .SH Capacity - empty checks whether the underlying container is empty - \fI(public member function)\fP + empty checks whether the container adaptor is empty + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers push inserts element and sorts the underlying container - \fI(public member function)\fP + \fI(public member function)\fP + push_range inserts a range of elements and sorts the underlying container + (C++23) \fI(public member function)\fP emplace constructs element in-place and sorts the underlying container - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP -.SH Member objects - Container c the underlying container - \fI(protected member object)\fP - Compare comp the comparison function object - \fI(protected member object)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions std::swap(std::priority_queue) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes std::uses_allocator specializes the std::uses_allocator type \fI(C++11)\fP trait - \fI(function template)\fP + \fI(class template specialization)\fP + std::formatter formatting support for std::priority_queue + (C++23) \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + for containers + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void pop_println(std::string_view rem, T& pq) + { + std::cout << rem << ": "; + for (; !pq.empty(); pq.pop()) + std::cout << pq.top() << ' '; + std::cout << '\\n'; + } + + template + void println(std::string_view rem, const T& v) + { + std::cout << rem << ": "; + for (const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + const auto data = {1, 8, 5, 6, 3, 4, 0, 9, 7, 2}; + println("data", data); + + std::priority_queue max_priority_queue; + + // Fill the priority queue. + for (int n : data) + max_priority_queue.push(n); + + pop_println("max_priority_queue", max_priority_queue); + + // std::greater makes the max priority queue act as a min priority queue. + std::priority_queue, std::greater> + min_priority_queue1(data.begin(), data.end()); + + pop_println("min_priority_queue1", min_priority_queue1); + + // Second way to define a min priority queue. + std::priority_queue min_priority_queue2(data.begin(), data.end(), std::greater()); + + pop_println("min_priority_queue2", min_priority_queue2); + + // Using a custom function object to compare elements. + struct + { + bool operator()(const int l, const int r) const { return l > r; } + } customLess; + + std::priority_queue custom_priority_queue(data.begin(), data.end(), customLess); + + pop_println("custom_priority_queue", custom_priority_queue); + + // Using lambda to compare elements. + auto cmp = [](int left, int right) { return (left ^ 1) < (right ^ 1); }; + std::priority_queue, decltype(cmp)> lambda_priority_queue(cmp); + + for (int n : data) + lambda_priority_queue.push(n); + + pop_println("lambda_priority_queue", lambda_priority_queue); + } + +.SH Output: + + data: 1 8 5 6 3 4 0 9 7 2 + max_priority_queue: 9 8 7 6 5 4 3 2 1 0 + min_priority_queue1: 0 1 2 3 4 5 6 7 8 9 + min_priority_queue2: 0 1 2 3 4 5 6 7 8 9 + custom_priority_queue: 0 1 2 3 4 5 6 7 8 9 + lambda_priority_queue: 8 9 6 7 4 5 2 3 0 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 307 C++98 Container could not be allowed + std::vector + LWG 2566 C++98 Missing the requirement for ill-formed if T is not the same + Container::value_type type as Container::value_type + priority_queue takes a + LWG 2684 C++98 comparator added + but lacked member typedef for + it + +.SH See also + + vector dynamic contiguous array + \fI(class template)\fP + vector space-efficient dynamic bitset + \fI(class template specialization)\fP + deque double-ended queue + \fI(class template)\fP diff --git a/man/std::priority_queue::emplace.3 b/man/std::priority_queue::emplace.3 index cbe332cb6..d9a37251b 100644 --- a/man/std::priority_queue::emplace.3 +++ b/man/std::priority_queue::emplace.3 @@ -1,14 +1,19 @@ -.TH std::priority_queue::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::emplace \- std::priority_queue::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP void emplace( Args&&... args ); - Pushes new element to the priority queue. The element is constructed in-place, i.e. - no copy or move operations are performed. The constructor of the element is called - with exactly the same arguments as supplied to the function. + Pushes a new element to the priority queue. The element is constructed in-place, + i.e. no copy or move operations are performed. The constructor of the element is + called with exactly the same arguments as supplied to the function. + + Effectively calls - Effectively calls c.emplace_back(std::forward(args)...); - std::push_heap(c.begin(), c.end(), comp); + c.emplace_back(std::forward(args)...); + std::push_heap(c.begin(), c.end(), comp); .SH Parameters @@ -22,9 +27,40 @@ Logarithmic number of comparisons plus the complexity of Container::emplace_back. +.SH Example + + +// Run this code + + #include + #include + + struct S + { + int id; + + S(int i, double d, std::string s) : id{i} + { + std::cout << "S::S(" << i << ", " << d << ", \\"" << s << "\\");\\n"; + } + friend bool operator< (S const& x, S const& y) { return x.id < y.id; } + }; + + int main() + { + std::priority_queue queue; + queue.emplace(42, 3.14, "C++"); + std::cout << "id: " << queue.top().id << '\\n'; + } + +.SH Output: + + S::S(42, 3.14, "C++") + id = 42 + .SH See also push inserts element and sorts the underlying container - \fI(public member function)\fP + \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::priority_queue::empty.3 b/man/std::priority_queue::empty.3 index 2e6b9fac5..fed3b04c3 100644 --- a/man/std::priority_queue::empty.3 +++ b/man/std::priority_queue::empty.3 @@ -1,8 +1,12 @@ -.TH std::priority_queue::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::empty \- std::priority_queue::empty + .SH Synopsis - bool empty() const; (since {std}) + bool empty() const; \fI(until C++20)\fP + [[nodiscard]] bool empty() const; \fI(since C++20)\fP - Checks if the underlying container has no elements, i.e. whether c.empty(). + Checks if the underlying container has no elements. Equivalent to return c.empty();. .SH Parameters @@ -10,13 +14,41 @@ .SH Return value - true if the underlying container is empty, false otherwise + true if the underlying container is empty, false otherwise. .SH Complexity - Constant + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::priority_queue queue; + + std::cout << "Initially, queue.empty(): " << queue.empty() << '\\n'; + + queue.push(42); + std::cout << "After adding elements, queue.empty(): " << queue.empty() << '\\n'; + } + +.SH Output: + + Initially, queue.empty(): true + After adding elements, queue.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::priority_queue::operator=.3 b/man/std::priority_queue::operator=.3 index 44e0b3479..d5f099f73 100644 --- a/man/std::priority_queue::operator=.3 +++ b/man/std::priority_queue::operator=.3 @@ -1,16 +1,18 @@ -.TH std::priority_queue::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::operator= \- std::priority_queue::operator= + .SH Synopsis - priority_queue& \fB(1)\fP - operator=( const priority_queue& other ); - priority_queue& \fB(2)\fP \fI(since C++11)\fP - operator=( priority_queue&& other ); + priority_queue& operator=( const priority_queue& other ); \fB(1)\fP (implicitly declared) + priority_queue& operator=( priority_queue&& other ); \fB(2)\fP \fI(since C++11)\fP + (implicitly declared) - Replaces the contents of the container adaptor with those of other. + Replaces the contents of the container adaptor with the contents of given argument. 1) Copy assignment operator. Replaces the contents with a copy of the contents of - other. Effectively calls c = other.c;. (implicitly declared) + other. Effectively calls c = other.c; comp = other.comp;. 2) Move assignment operator. Replaces the contents with those of other using move - semantics. Effectively calls c = std::move(other.c); (implicitly declared) + semantics. Effectively calls c = std::move(other.c); comp = std::move(other.comp);. .SH Parameters @@ -22,9 +24,17 @@ .SH Complexity - Equivalent to that of operator= of the underlying container. + 1,2) Equivalent to that of operator= of the underlying container. + +.SH Example + + This section is incomplete + Reason: no example .SH See also constructor constructs the priority_queue - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::priority_queue::pop.3 b/man/std::priority_queue::pop.3 index 95a5ca5b1..d9e03f94e 100644 --- a/man/std::priority_queue::pop.3 +++ b/man/std::priority_queue::pop.3 @@ -1,9 +1,12 @@ -.TH std::priority_queue::pop 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::pop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::pop \- std::priority_queue::pop + .SH Synopsis - void pop(); (since {std}) + void pop(); Removes the top element from the priority queue. Effectively calls - std::pop_heap(c.begin(), c.end(), comp); c.pop_back(); + std::pop_heap(c.begin(), c.end(), comp); c.pop_back();. .SH Parameters @@ -17,9 +20,63 @@ Logarithmic number of comparisons plus the complexity of Container::pop_back. +.SH Example + + +// Run this code + + #include + #include + + struct Event + { + int priority{}; + char data{' '}; + + friend bool operator<(Event const& lhs, Event const& rhs) + { + return lhs.priority < rhs.priority; + } + + friend std::ostream& operator<<(std::ostream& os, Event const& e) + { + return os << '{' << e.priority << ", '" << e.data << "'}"; + } + }; + + int main() + { + std::priority_queue events; + + std::cout << "Fill the events queue:\\t"; + + for (auto const e : {Event{6,'L'}, {8,'I'}, {9,'S'}, {1,'T'}, {5,'E'}, {3,'N'}}) + { + std::cout << e << ' '; + events.push(e); + } + + std::cout << "\\nProcess events:\\t\\t"; + + for (; !events.empty(); events.pop()) + { + Event const& e = events.top(); + std::cout << e << ' '; + } + + std::cout << '\\n'; + } + +.SH Output: + + Fill the events queue: {6, 'L'} {8, 'I'} {9, 'S'} {1, 'T'} {5, 'E'} {3, 'N'} + Process events: {9, 'S'} {8, 'I'} {6, 'L'} {5, 'E'} {3, 'N'} {1, 'T'} + .SH See also emplace constructs element in-place and sorts the underlying container - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP push inserts element and sorts the underlying container - \fI(public member function)\fP + \fI(public member function)\fP + top accesses the top element + \fI(public member function)\fP diff --git a/man/std::priority_queue::priority_queue.3 b/man/std::priority_queue::priority_queue.3 index 97fb2adde..0172dcab7 100644 --- a/man/std::priority_queue::priority_queue.3 +++ b/man/std::priority_queue::priority_queue.3 @@ -1,155 +1,321 @@ -.TH std::priority_queue::priority_queue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::priority_queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::priority_queue \- std::priority_queue::priority_queue + .SH Synopsis - explicit priority_queue( const Compare& compare = Compare(), - const Container& cont = Container() \fI(until C++11)\fP - ); - priority_queue( const Compare& compare, const Container& cont \fI(since C++11)\fP + priority_queue() : priority_queue(Compare(), \fB(1)\fP (since + Container()) {} C++11) + explicit priority_queue( const Compare& compare ) \fB(2)\fP (since + : priority_queue(compare, Container()) {} C++11) + explicit priority_queue( const Compare& compare = + Compare(), (until + const Container& cont = C++11) + Container() ); + priority_queue( const Compare& compare, const Container& (since + cont ); C++11) + priority_queue( const Compare& compare, Container&& cont \fB(4)\fP (since + ); C++11) + priority_queue( const priority_queue& other ); \fB(5)\fP + priority_queue( priority_queue&& other ); \fB(6)\fP (since + C++11) + template< class InputIt > + (since + priority_queue( InputIt first, InputIt last, \fB(7)\fP C++11) + + const Compare& compare = Compare() ); + template< class InputIt > + + priority_queue( InputIt first, InputIt last, (until + const Compare& compare = Compare(), C++11) + + const Container& cont = Container() ); + template< class InputIt > + + priority_queue( InputIt first, InputIt last, (since + C++11) + const Compare& compare, const Container& + cont ); + template< class InputIt > + + priority_queue( InputIt first, InputIt last, \fB(9)\fP (since + C++11) + const Compare& compare, Container&& cont ); - explicit priority_queue( const Compare& compare = Compare(), \fB(2)\fP \fI(since C++11)\fP - Container&& cont = Container() ); - priority_queue( const priority_queue& other ); \fB(3)\fP - priority_queue( priority_queue&& other ); \fB(4)\fP \fI(since C++11)\fP - template< class Alloc > \fB(5)\fP \fI(since C++11)\fP - explicit priority_queue( const Alloc& alloc ); - template< class Alloc > \fB(6)\fP \fI(since C++11)\fP - priority_queue( const Compare& compare, const Alloc& alloc ); + template< class Alloc > \fB(10)\fP (since + explicit priority_queue( const Alloc& alloc ); C++11) + template< class Alloc > (since + priority_queue( const Compare& compare, const Alloc& \fB(11)\fP C++11) + alloc ); template< class Alloc > - priority_queue( const Compare& compare, const Container& \fB(7)\fP \fI(since C++11)\fP - cont, + priority_queue( const Compare& compare, const Container& \fB(12)\fP (since + cont, C++11) const Alloc& alloc ); template< class Alloc > - \fB(1)\fP - priority_queue( const Compare& compare, Container&& cont, \fB(8)\fP \fI(since C++11)\fP + \fB(3)\fP + priority_queue( const Compare& compare, Container&& \fB(13)\fP (since + cont, C++11) const Alloc& alloc ); - template< class Alloc > - priority_queue( const priority_queue& other, const Alloc& \fB(9)\fP \fI(since C++11)\fP + template< class Alloc > (since + priority_queue( const priority_queue& other, const \fB(14)\fP C++11) + Alloc& alloc ); + template< class Alloc > \fB(8)\fP (since + priority_queue( priority_queue&& other, const Alloc& \fB(15)\fP C++11) alloc ); - template< class Alloc > \fB(10)\fP \fI(since C++11)\fP - priority_queue( priority_queue&& other, const Alloc& alloc ); - template< class InputIt > + template< class InputIt, class Alloc > (since + priority_queue( InputIt first, InputIt last, const \fB(16)\fP C++11) + Alloc& alloc ); + template< class InputIt, class Alloc > - priority_queue( InputIt first, InputIt last, \fB(11)\fP \fI(since C++11)\fP + priority_queue( InputIt first, InputIt last, const \fB(17)\fP (since + Compare& compare, C++11) - const Compare& compare, const Container& cont - ); - template< class InputIt > + const Alloc& alloc ); + template< class InputIt, class Alloc > + + priority_queue( InputIt first, InputIt last, const (since + Compare& compare, \fB(18)\fP C++11) + + const Container& cont, const Alloc& + alloc ); + template< class InputIt, class Alloc > + + priority_queue( InputIt first, InputIt last, const \fB(19)\fP (since + Compare& compare, C++11) - priority_queue( InputIt first, InputIt last, \fB(12)\fP \fI(since C++11)\fP - const Compare& compare = Compare(), + Container&& cont, const Alloc& alloc ); + template< container-compatible-range R > + (since + priority_queue( std::from_range_t, R&& rg, \fB(20)\fP C++23) - Container&& cont = Container() ); + const Compare& compare = Compare() ); + template< container-compatible-range R, class Alloc > + + priority_queue( std::from_range_t, R&& rg, \fB(21)\fP (since + C++23) + const Compare& compare, const Alloc& + alloc ); + template< container-compatible-range R, class Alloc > (since + priority_queue( std::from_range_t, R&& rg, const Alloc& \fB(22)\fP C++23) + alloc ); Constructs new underlying container of the container adaptor from a variety of data sources. - 1) Copy-constructs the underlying container c with the contents of cont. + 1) Default constructor. Value-initializes the comparator and the underlying + container. + 2) Copy-constructs the comparison functor comp with the contents of compare. + Value-initializes the underlying container c. + 3) Copy-constructs the underlying container c with the contents of cont. Copy-constructs the comparison functor comp with the contents of compare. Calls - std::make_heap(c.begin(), c.end(), comp).}} + std::make_heap(c.begin(), c.end(), comp). This is also the default constructor. \fI(until C++11)\fP - 2) Move-constructs the underlying container c with std::move(cont). Move-constructs - the comparison functor comp with std::move(compare). Calls std::make_heap(c.begin(), - c.end(), comp). - This is also the default constructor. - \fI(since C++11)\fP - 3) Copy constructor. The adaptor is copy-constructed with the contents of other.c. - The comparison functor is constructed with std::move(other.comp). (implicitly - declared) - 4) Move constructor. The adaptor is constructed with std::move(other.c).The - comparison functor is constructed with std::move(other.comp). (implicitly declared) - 5-10) The following constructors are only defined if - std::uses_allocator::value == true, that is, if the - underlying container is an allocator-aware container (true for all standard library - containers). - 5) Constructs the underlying container using alloc as allocator. Effectively calls - c(alloc). comp is value-initialized. - 6) Constructs the underlying container using alloc as allocator. Effectively calls - c(alloc). Copy-constructs comp from compare. - 7) Constructs the underlying container with the contents of cont and using alloc as - allocator. Effectively calls c(cont, alloc). Copy-constructs comp from compare. - 8) Constructs the underlying container with the contents of cont using move - semantics while utilising alloc as allocator. Effectively calls c(std::move(cont), - alloc). Copy-constructs comp from compare. - 9) Constructs the adaptor with the contents of other.c and using alloc as allocator. - Effectively calls c(athor.c, alloc). Copy-constructs comp from other.comp. - 10) Constructs the adaptor with the contents of other using move semantics while - utilising alloc as allocator. Effectively calls c(std::move(other.c), alloc). - Move-constructs comp from other.comp. - 11) Copy-constructs c from cont and comp from compare. Then calls c.insert(c.end(), + 4) Move-constructs the underlying container c with std::move(cont). Copy-constructs + the comparison functor comp with compare. Calls std::make_heap(c.begin(), c.end(), + comp). + 5) Copy constructor. The underlying container is copy-constructed with other.c. The + comparison functor is copy-constructed with other.comp. (implicitly declared) + 6) Move constructor. The underlying container is constructed with + std::move(other.c). The comparison functor is constructed with + std::move(other.comp). (implicitly declared) + 7-9) Iterator-pair constructors. These overloads participate in overload resolution + only if InputIt satisfies LegacyInputIterator. + 7) Constructs c as if by c(first, last) and comp from compare. Then calls + std::make_heap(c.begin(), c.end(), comp);. + 8) Copy-constructs c from cont and comp from compare. Then calls c.insert(c.end(), first, last);, and then calls std::make_heap(c.begin(), c.end(), comp);. - 12) Move-constructs c from std::move(cont) and comp from std::move(compare). Then - calls c.insert(c.end(), first, last);, and then calls std::make_heap(c.begin(), + 9) Move-constructs c from std::move(cont) and copy-constructs comp from compare. + Then calls c.insert(c.end(), first, last);, and then calls std::make_heap(c.begin(), c.end(), comp);. + 10-15) Allocator-extended constructors. These overloads participate in overload + resolution only if std::uses_allocator::value is true, that + is, if the underlying container is an allocator-aware container (true for all + standard library containers). + 10) Constructs the underlying container using alloc as allocator. Effectively calls + c(alloc). comp is value-initialized. + 11) Constructs the underlying container using alloc as allocator. Effectively calls + c(alloc). Copy-constructs comp from compare. + 12) Constructs the underlying container with the contents of cont and using alloc as + allocator, as if by c(cont, alloc). Copy-constructs comp from compare. Then calls + std::make_heap(c.begin(), c.end(), comp). + 13) Constructs the underlying container with the contents of cont using move + semantics while using alloc as allocator, as if by c(std::move(cont), alloc). + Copy-constructs comp from compare. Then calls std::make_heap(c.begin(), c.end(), + comp). + 14) Constructs the underlying container with the contents of other.c and using alloc + as allocator. Effectively calls c(other.c, alloc). Copy-constructs comp from + other.comp. + 15) Constructs the underlying container with the contents of other using move + semantics while utilizing alloc as allocator. Effectively calls + c(std::move(other.c), alloc). Move-constructs comp from other.comp. + 16-19) Allocator-extended iterator-pair constructors. Same as (7-9), except that + alloc is used for constructing the underlying container. These overloads participate + in overload resolution only if std::uses_allocator::value is + true and InputIt satisfies LegacyInputIterator. + 20) Initializes comp with compare and c with + ranges::to(std::forward(rg)). Then calls std::make_heap(c.begin(), + c.end(), comp). + 21) Initializes comp with compare and c with + ranges::to(std::forward(rg), alloc). Then calls + std::make_heap(c.begin(), c.end(), comp). + 22) Initializes c with ranges::to(std::forward(rg), alloc). Then calls + std::make_heap(c.begin(), c.end(), comp). + + Note that how an implementation checks whether a type satisfies LegacyInputIterator + is unspecified, except that integral types are required to be rejected. .SH Parameters - alloc - allocator to use for all memory allocations of the - underlying container - other - another container adaptor to be used as source to - initialize the underlying container - cont - container to be used as source to initialize the - underlying container - compare - the comparison function object to initialize the - underlying comparison functor - first, last - range of elements to initialize with + alloc - allocator to use for all memory allocations of the + underlying container + other - another container adaptor to be used as source to + initialize the underlying container + cont - container to be used as source to initialize the + underlying container + compare - the comparison function object to initialize the + underlying comparison functor + first, last - a range [first, last) of elements to initialize with + rg - a container compatible range, that is, an input_range + whose elements are convertible to T .SH Type requirements - Alloc must meet the requirements of Allocator. - - Container must meet the requirements of Container. The constructors (5-10) are only - defined if Container meets the requirements of AllocatorAwareContainer + Compare must meet the requirements of Compare. - - InputIt must meet the requirements of InputIterator. + Container must meet the requirements of Container. The allocator-extended + constructors are only defined if Container meets the requirements of + AllocatorAwareContainer. + - + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1,3) O(N log(N)) comparisons, where N is cont.size(). - Additionally, O(N) calls to the constructor of value_type, where N is cont.size(). - 2) O(N log(N)) comparisons, where N is cont.size(). - 4-6) Constant. - 7) O(N log(N)) comparisons, where N is cont.size(). - Additionally, O(N) calls to the constructor of value_type, where N is cont.size(). - 8) O(N log(N)) comparisons, where N is cont.size(). - 9) Linear in size of other. - 10) Constant. - 11) O(N log(N)) comparisons, where N is cont.size() + std::distance(first, last). - Additionally, O(N) calls to the constructor of value_type, where N is cont.size(). - 12) O(N log(N)) comparisons, where N is cont.size() + std::distance(first, last). + 1,2) Constant. + 3,5,12) \\(\\scriptsize \\mathcal{O}{(N)}\\)O(N) comparisons and \\(\\scriptsize + \\mathcal{O}{(N)}\\)O(N) calls to the constructor of value_type, where \\(\\scriptsize + N\\)N is cont.size(). + 4) \\(\\scriptsize \\mathcal{O}{(N)}\\)O(N) comparisons, where \\(\\scriptsize N\\)N is + cont.size(). + 6) Constant. + 7,16,17) \\(\\scriptsize \\mathcal{O}{(M)}\\)O(M) comparisons, where \\(\\scriptsize M\\)M + is std::distance(first, last). + 8,18) \\(\\scriptsize \\mathcal{O}{(N + M)}\\)O(N + M) comparisons and \\(\\scriptsize + \\mathcal{O}{(N)}\\)O(N) calls to the constructor of value_type, where \\(\\scriptsize + N\\)N is cont.size() and \\(\\scriptsize M\\)M is std::distance(first, last). + 9) \\(\\scriptsize \\mathcal{O}{(N + M)}\\)O(N + M) comparisons, where \\(\\scriptsize + N\\)N is cont.size() and \\(\\scriptsize M\\)M is std::distance(first, last). + 10,11) Constant. + 13) \\(\\scriptsize \\mathcal{O}{(N)}\\)O(N) comparisons, where \\(\\scriptsize N\\)N is + cont.size(). + 14) Linear in size of other. + 15) Constant if Alloc compares equal to the allocator of other. Linear in size of + other otherwise. + 19) \\(\\scriptsize \\mathcal{O}{(N + M)}\\)O(N + M) comparisons and possibly + \\(\\scriptsize \\mathcal{O}{(N)}\\)O(N) calls to the constructor of value_type (present + if Alloc does not compare equal to the allocator of other), where \\(\\scriptsize N\\)N + is cont.size() and \\(\\scriptsize M\\)M is std::distance(first, last). + 20) \\(\\scriptsize \\mathcal{O}{(N)}\\)O(N) comparisons and \\(\\scriptsize + \\mathcal{O}{(N)}\\)O(N) calls to the constructor of value_type, where \\(\\scriptsize + N\\)N is ranges::distance(rg). + 21,22) + + This section is incomplete + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (20-22) .SH Example - + // Run this code + #include + #include + #include #include #include - #include - #include - + int main() { - std::priority_queue c1; - c1.push(5); - std::cout << c1.size() << '\\n'; - - std::priority_queue c2(c1); - std::cout << c2.size() << '\\n'; - - std::vector vec={3, 1, 4, 1, 5}; - std::priority_queue c3(std::less(), vec); - std::cout << c3.size() << '\\n'; + std::priority_queue pq1; + pq1.push(5); + std::cout << "pq1.size() = " << pq1.size() << '\\n'; + + std::priority_queue pq2 {pq1}; + std::cout << "pq2.size() = " << pq2.size() << '\\n'; + + std::vector vec {3, 1, 4, 1, 5}; + std::priority_queue pq3 {std::less(), vec}; + std::cout << "pq3.size() = " << pq3.size() << '\\n'; + + for (std::cout << "pq3 : "; !pq3.empty(); pq3.pop()) + std::cout << pq3.top() << ' '; + std::cout << '\\n'; + + // Demo With Custom Comparator: + + using my_value_t = std::complex; + using my_container_t = std::vector; + + auto my_comp = [](const my_value_t& z1, const my_value_t& z2) + { + return z2.real() < z1.real(); + }; + + std::priority_queue pq4{my_comp}; + + using namespace std::complex_literals; + pq4.push(5.0 + 1i); + pq4.push(3.0 + 2i); + pq4.push(7.0 + 3i); + + for (; !pq4.empty(); pq4.pop()) + { + const auto& z = pq4.top(); + std::cout << "pq4.top() = " << z << '\\n'; + } + + // TODO: C++23 range-aware ctors } .SH Output: - 1 - 1 - 5 + pq1.size() = 1 + pq2.size() = 1 + pq3.size() = 5 + pq3 : 5 4 3 1 1 + pq4.top() = (3,2) + pq4.top() = (5,1) + pq4.top() = (7,3) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor and constructor \fB(4)\fP made implicit + were explicit + LWG 3506 C++11 allocator-extended iterator-pair added + constructors were missing + LWG 3522 C++11 constraints on iterator-pair added + constructors were missing + LWG 3529 C++11 construction from a pair of iterators constructs the container + called insert from them .SH See also operator= assigns values to the container adaptor - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo without reason diff --git a/man/std::priority_queue::push.3 b/man/std::priority_queue::push.3 index 06aaeddbf..3ea6c44de 100644 --- a/man/std::priority_queue::push.3 +++ b/man/std::priority_queue::push.3 @@ -1,13 +1,16 @@ -.TH std::priority_queue::push 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::push 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::push \- std::priority_queue::push + .SH Synopsis - void push( const T& value ); (since {std}) - void push( T&& value ); \fI(since C++11)\fP + void push( const value_type& value ); + void push( value_type&& value ); \fI(since C++11)\fP Pushes the given element value to the priority queue. - 1) Effectively calls c.push_back(value); std::push_heap(c.begin(), c.end(), comp); + 1) Effectively calls c.push_back(value); std::push_heap(c.begin(), c.end(), comp);. 2) Effectively calls c.push_back(std::move(value)); std::push_heap(c.begin(), - c.end(), comp); + c.end(), comp);. .SH Parameters @@ -21,9 +24,61 @@ Logarithmic number of comparisons plus the complexity of Container::push_back. +.SH Example + + +// Run this code + + #include + #include + + struct Event + { + int priority{}; + char data{' '}; + + friend bool operator<(Event const& lhs, Event const& rhs) + { + return lhs.priority < rhs.priority; + } + + friend std::ostream& operator<<(std::ostream& os, Event const& e) + { + return os << '{' << e.priority << ", '" << e.data << "'}"; + } + }; + + int main() + { + std::priority_queue events; + + std::cout << "Fill the events queue:\\t"; + + for (auto const e : {Event{6,'L'}, {8,'I'}, {9,'S'}, {1,'T'}, {5,'E'}, {3,'N'}}) + { + std::cout << e << ' '; + events.push(e); + } + + std::cout << "\\nProcess events:\\t\\t"; + + for (; !events.empty(); events.pop()) + { + Event const& e = events.top(); + std::cout << e << ' '; + } + + std::cout << '\\n'; + } + +.SH Output: + + Fill the events queue: {6, 'L'} {8, 'I'} {9, 'S'} {1, 'T'} {5, 'E'} {3, 'N'} + Process events: {9, 'S'} {8, 'I'} {6, 'L'} {5, 'E'} {3, 'N'} {1, 'T'} + .SH See also emplace constructs element in-place and sorts the underlying container - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::priority_queue::push_range.3 b/man/std::priority_queue::push_range.3 new file mode 100644 index 000000000..378aaff54 --- /dev/null +++ b/man/std::priority_queue::push_range.3 @@ -0,0 +1,83 @@ +.TH std::priority_queue::push_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::push_range \- std::priority_queue::push_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void push_range( R&& rg ); + + Inserts a copy of each element of rg in priority_queue, as if by: + + * c.append_range(std::forward(rg)) if that is a valid expression (i.e. the + underlying container c has an appropriate append_range member function), or + * ranges::copy(rg, std::back_inserter(c)) otherwise. + + Then restores the heap property as if by ranges::make_heap(c, comp). After the + insertion ranges::is_heap(c, comp) is true. + + Each iterator in the range rg is dereferenced exactly once. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + The complexity of c.append_range plus the complexity of ranges::make_heap(c, comp). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + requires (std::ranges::input_range) + void println(auto, const Adaptor& adaptor) + { + struct Container : Adaptor // gain access to protected Adaptor::Container c; + { + auto const& container() const { return this->c; } + }; + + for (auto const& elem : static_cast(adaptor).container()) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + std::priority_queue adaptor; + const auto rg = {1, 3, 2, 4}; + + #ifdef __cpp_lib_containers_ranges + adaptor.push_range(rg); + #else + std::ranges::for_each(rg, [&adaptor](auto e){ adaptor.push(e); }); + #endif + + println("{}", adaptor); + } + +.SH Output: + + 4 3 2 1 + +.SH See also + + push inserts element and sorts the underlying container + \fI(public member function)\fP diff --git a/man/std::priority_queue::size.3 b/man/std::priority_queue::size.3 index c80701a95..c90f2c880 100644 --- a/man/std::priority_queue::size.3 +++ b/man/std::priority_queue::size.3 @@ -1,8 +1,12 @@ -.TH std::priority_queue::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::size \- std::priority_queue::size + .SH Synopsis - size_type size() const; (since {std}) + size_type size() const; - Returns the number of elements in the underlying container, that is, c.size(). + Returns the number of elements in the container adaptor. Equivalent to return + c.size(). .SH Parameters @@ -10,13 +14,40 @@ .SH Return value - The number of elements in the container. + The number of elements in the container adaptor. .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::priority_queue queue; + + assert(queue.size() == 0); + + const int count = 8; + + for (int i = 0; i != count; ++i) + queue.push(i); + + assert(queue.size() == count); + } + .SH See also - empty checks whether the underlying container is empty - \fI(public member function)\fP + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::priority_queue::swap.3 b/man/std::priority_queue::swap.3 index efc48e99d..267c3d045 100644 --- a/man/std::priority_queue::swap.3 +++ b/man/std::priority_queue::swap.3 @@ -1,9 +1,16 @@ -.TH std::priority_queue::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::swap \- std::priority_queue::swap + .SH Synopsis - void swap( priority_queue& other ); (since {std}) + void swap( priority_queue& other ) noexcept(/* see below */); \fI(since C++11)\fP Exchanges the contents of the container adaptor with those of other. Effectively - calls using std::swap; swap(c, other.c); swap(comp, other.comp); + calls + + using std::swap; + swap(c, other.c); + swap(comp, other.comp); .SH Parameters @@ -15,17 +22,92 @@ .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: \fI(since C++11)\fP - noexcept(noexcept(std::swap(c, other.c)) && noexcept(std::swap(comp, \fI(since C++11)\fP - other.comp))) + noexcept specification: + noexcept(noexcept(swap(c, other.c)) && noexcept(swap(comp, + other.comp))) \fI(since C++11)\fP + \fI(until C++17)\fP + In the expression above, the identifier swap is looked up in the same + manner as the one used by the C++17 std::is_nothrow_swappable trait. + noexcept specification: + noexcept(std::is_nothrow_swappable_v && \fI(since C++17)\fP + std::is_nothrow_swappable_v) .SH Complexity - Same as underlying container (linear if Container is std::array, constant - otherwise). + Same as underlying container (typically constant). + +.SH Notes + + Some implementations (e.g. libc++) provide the swap member function as an extension + to pre-C++11 modes. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + requires (std::ranges::input_range) + void print(std::string_view name, const Adaptor& adaptor) + { + struct Printer : Adaptor // to use protected Adaptor::Container c; + { + void print(std::string_view name) const + { + std::cout << name << " [" << std::size(this->c) << "]: "; + for (auto const& elem : this->c) + std::cout << elem << ' '; + std::cout << '\\n'; + } + }; + + static_cast(adaptor).print(name); + } + + int main() + { + std::vector v1{"1","2","3","4"}, + v2{"Ɐ","B","Ɔ","D","Ǝ"}; + + std::priority_queue s1(std::less<>(), std::move(v1)); + std::priority_queue s2(std::less<>(), std::move(v2)); + + print("s1", s1); + print("s2", s2); + + s1.swap(s2); + + print("s1", s1); + print("s2", s2); + } + +.SH Output: + + s1 [4]: 4 3 2 1 + s2 [5]: Ǝ D Ɔ B Ɐ + s1 [5]: Ǝ D Ɔ B Ɐ + s2 [4]: 4 3 2 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2456 C++11 the noexcept specification is ill-formed made to work .SH See also std::swap(std::priority_queue) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::priority_queue::top.3 b/man/std::priority_queue::top.3 index f57950b82..a29dfe1b6 100644 --- a/man/std::priority_queue::top.3 +++ b/man/std::priority_queue::top.3 @@ -1,4 +1,7 @@ -.TH std::priority_queue::top 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::top 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::top \- std::priority_queue::top + .SH Synopsis const_reference top() const; @@ -12,13 +15,65 @@ .SH Return value - Reference to the top element as if obtained by a call to c.front() + Reference to the top element as if obtained by a call to c.front(). .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + struct Event + { + int priority{}; + char data{' '}; + + friend bool operator<(Event const& lhs, Event const& rhs) + { + return lhs.priority < rhs.priority; + } + + friend std::ostream& operator<<(std::ostream& os, Event const& e) + { + return os << '{' << e.priority << ", '" << e.data << "'}"; + } + }; + + int main() + { + std::priority_queue events; + + std::cout << "Fill the events queue:\\t"; + + for (auto const e : {Event{6,'L'}, {8,'I'}, {9,'S'}, {1,'T'}, {5,'E'}, {3,'N'}}) + { + std::cout << e << ' '; + events.push(e); + } + + std::cout << "\\nProcess events:\\t\\t"; + + for (; !events.empty(); events.pop()) + { + Event const& e = events.top(); + std::cout << e << ' '; + } + + std::cout << '\\n'; + } + +.SH Output: + + Fill the events queue: {6, 'L'} {8, 'I'} {9, 'S'} {1, 'T'} {5, 'E'} {3, 'N'} + Process events: {9, 'S'} {8, 'I'} {6, 'L'} {5, 'E'} {3, 'N'} {1, 'T'} + .SH See also pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::priority_queue::~priority_queue.3 b/man/std::priority_queue::~priority_queue.3 index b70d01c69..f4e6708d1 100644 --- a/man/std::priority_queue::~priority_queue.3 +++ b/man/std::priority_queue::~priority_queue.3 @@ -1,11 +1,14 @@ -.TH std::priority_queue::~priority_queue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::priority_queue::~priority_queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::priority_queue::~priority_queue \- std::priority_queue::~priority_queue + .SH Synopsis - ~priority_queue(); (since {std}) + ~priority_queue(); - Destructs the container adaptor. The destructors of the elements are called and the + Destructs the priority_queue. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container adaptor. + Linear in the size of the priority_queue. diff --git a/man/std::proj(std::complex).3 b/man/std::proj(std::complex).3 index 92c3e5ead..e571c56b9 100644 --- a/man/std::proj(std::complex).3 +++ b/man/std::proj(std::complex).3 @@ -1,48 +1,76 @@ -.TH std::proj(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::proj(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::proj(std::complex) \- std::proj(std::complex) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - complex proj( const complex& z ); - std::complex proj( long double z ); \fB(2)\fP \fI(since C++11)\fP - template< class DoubleOrIngeter > \fB(3)\fP \fI(since C++11)\fP - std::complex proj( DoubleOrInteger z ); - std::complex proj( float z ); \fB(4)\fP \fI(since C++11)\fP + template< class T > \fB(1)\fP \fI(since C++11)\fP + std::complex proj( const std::complex& z ); + Additional overloads \fI(since C++11)\fP + Defined in header + std::complex proj( float f ); - Returns the projection of the complex number z onto the Riemann sphere. + std::complex proj( double f ); (until C++23) - For most z, std::proj(z)==z, but all complex infinities, even the numbers where one - component is infinite and the other is NaN, become positive real infinity, - (INFINITY, 0) or (INFINITY, -0). The sign of the imaginary (zero) component is the - sign of std::imag(z). + std::complex proj( long double f ); (A) + template< class FloatingPoint > (since C++23) + std::complex proj( FloatingPoint f ); + template< class Integer > (B) + std::complex proj( Integer i ); - \fI(since C++11)\fPAdditional overloads are provided for float, double, long double, and - all integer types, which are treated as complex numbers with zero imaginary - component. + 1) Returns the projection of the complex number z onto the Riemann sphere. + For most z, std::proj(z) == z, but all complex infinities, even the numbers where + one component is infinite and the other is NaN, become positive real infinity, + (INFINITY, 0.0) or (INFINITY, -0.0). The sign of the imaginary (zero) component is + the sign of std::imag(z). + A,B) Additional overloads are provided for all integer and floating-point types, + which are treated as complex numbers with positive zero imaginary component. .SH Parameters z - complex value + f - floating-point value + i - integer value .SH Return value - the projection of z onto the Riemann sphere + 1) The projection of z onto the Riemann sphere. + A) The projection of std::complex(f) onto the Riemann sphere. + B) The projection of std::complex(i) onto the Riemann sphere. + +.SH Notes + + The proj function helps model the Riemann sphere by mapping all infinities to one + (give or take the sign of the imaginary zero), and should be used just before any + operation, especially comparisons, that might give spurious results for any of the + other infinities. + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num: + + * If num has a + standard + (until C++23) floating-point type T, then std::proj(num) has the same effect as + std::proj(std::complex(num)). + * Otherwise, if num has an integer type, then std::proj(num) has the same effect + as std::proj(std::complex(num)). .SH Example - + // Run this code - #include #include - + #include + int main() { std::complex c1(1, 2); std::cout << "proj" << c1 << " = " << std::proj(c1) << '\\n'; - + std::complex c2(INFINITY, -1); std::cout << "proj" << c2 << " = " << std::proj(c2) << '\\n'; - + std::complex c3(0, -INFINITY); std::cout << "proj" << c3 << " = " << std::proj(c3) << '\\n'; } @@ -56,8 +84,10 @@ .SH See also abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP + \fI(function template)\fP norm returns the squared magnitude - \fI(function template)\fP + \fI(function template)\fP polar constructs a complex number from magnitude and phase angle - \fI(function template)\fP + \fI(function template)\fP + C documentation for + cproj diff --git a/man/std::projected.3 b/man/std::projected.3 new file mode 100644 index 000000000..915a800d7 --- /dev/null +++ b/man/std::projected.3 @@ -0,0 +1,110 @@ +.TH std::projected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::projected \- std::projected + +.SH Synopsis + Defined in header + template< std::indirectly_readable I, + + std::indirectly_regular_unary_invocable Proj > + struct projected + { \fI(since C++20)\fP + using value_type = (until C++26) + std::remove_cvref_t>; + std::indirect_result_t operator*() const; // + not defined + + }; + template< std::indirectly_readable I, + + std::indirectly_regular_unary_invocable Proj > (since C++26) + + using projected = /*projected-impl*/::/*__type*/; // + see \fB(3)\fP + template< std::weakly_incrementable I, class Proj > + + struct incrementable_traits> \fB(1)\fP \fI(since C++20)\fP + { \fB(2)\fP (until C++26) + using difference_type = std::iter_difference_t; + + }; + template< class I, class Proj > + + struct /*projected-impl*/ + { + struct /*__type*/ + { + using value_type = (since C++26) + std::remove_cvref_t>; \fB(3)\fP (exposition + using difference_type = std::iter_difference_t; // only*) + conditionally present + + std::indirect_result_t operator*() const; + // not defined + }; + + }; + + 1) + Class + (until C++26) + Alias + (since C++26) template projected combines an indirectly_readable type I and a + callable object type Proj into a new indirectly_readable type whose reference type + is the result of applying Proj to the std::iter_reference_t. + 2) This specialization of std::incrementable_traits makes std::projected a + weakly_incrementable type when I is also a weakly_incrementable type. + 3) An indirect layer used for avoiding unexpected argument-dependent lookup. The + member type difference_type exists only if I models weakly_incrementable. + + projected is used only to constrain algorithms that accept callable objects and + projections, and hence its operator*() is not defined. + +.SH Template parameters + + I - an indirectly readable type + Proj - projection applied to a dereferenced I + +.SH Notes + + The indirect layer prevents I and Proj to be associated classes of projected. When + an associated class of I or Proj is an incomplete class type, the indirect layer + avoids the unnecessary attempt to inspect the definition of that type that results + in hard error. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + struct Holder + { + T t; + }; + + struct Incomplete; + + using P = Holder*; + + static_assert(std::equality_comparable

); // OK + static_assert(std::indirectly_comparable>); // Error before C++26 + static_assert(std::sortable); // Error before C++26 + + int main() + { + P a[10] = {}; // ten null pointers + assert(std::count(a, a + 10, nullptr) == 10); // OK + assert(std::ranges::count(a, a + 10, nullptr) == 10); // Error before C++26 + } + +.SH See also + + projected_value_t computes the value type of an indirectly_readable type by + (C++26) projection + (alias template) diff --git a/man/std::projected_value_t.3 b/man/std::projected_value_t.3 new file mode 100644 index 000000000..a8f33e24a --- /dev/null +++ b/man/std::projected_value_t.3 @@ -0,0 +1,50 @@ +.TH std::projected_value_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::projected_value_t \- std::projected_value_t + +.SH Synopsis + Defined in header + template< std::indirectly_readable I, + + std::indirectly_regular_unary_invocable Proj > + using projected_value_t = (since C++26) + + std::remove_cvref_t&>>; + + The alias template projected_value_t obtains the value type by stripping any + reference and its topmost cv-qualifiers of the result type of applying Proj to + std::iter_value_t&. + + projected_value_t is used to determine the default value type in some algorithms + such as ranges::contains. + +.SH Template parameters + + I - an indirectly readable type + Proj - projection applied to an lvalue reference to value type of I + +.SH Notes + + Feature-test macro Value Std Feature + default template type +__cpp_lib_default_template_type_for_algorithm_values 202403L (C++26) for algorithm values + using + std::projected_value_t + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + indirect_result_t computes the result of invoking a callable object on the result of + (C++20) dereferencing some set of indirectly_readable types + (alias template) + projected helper template for specifying the constraints on algorithms that + (C++20) accept projections + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::promise.3 b/man/std::promise.3 index 1626ae8dc..2226d53f0 100644 --- a/man/std::promise.3 +++ b/man/std::promise.3 @@ -1,50 +1,131 @@ -.TH std::promise 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise \- std::promise + .SH Synopsis Defined in header - template< class T > class promise; \fB(1)\fP \fI(since C++11)\fP - template< class T > class promise; \fB(2)\fP \fI(since C++11)\fP - template<> class promise; \fB(3)\fP \fI(since C++11)\fP + template< class R > class promise; \fB(1)\fP \fI(since C++11)\fP + template< class R > class promise; \fB(2)\fP \fI(since C++11)\fP + template<> class promise; \fB(3)\fP \fI(since C++11)\fP + + 1) Base template. + 2) Non-void specialization, used to communicate objects between threads. + 3) void specialization, used to communicate stateless events. + + The class template std::promise provides a facility to store a value or an exception + that is later acquired asynchronously via a std::future object created by the + std::promise object. Note that the std::promise object is meant to be used only + once. + + Each promise is associated with a shared state, which contains some state + information and a result which may be not yet evaluated, evaluated to a value + (possibly void) or evaluated to an exception. A promise may do three things with the + shared state: - The class template std::promise provides a facility to store a value that is later - acquired asynchronously via a std::future object, that the std::promise can supply. + * make ready: the promise stores the result or the exception in the shared state. + Marks the state ready and unblocks any thread waiting on a future associated + with the shared state. + * release: the promise gives up its reference to the shared state. If this was the + last such reference, the shared state is destroyed. Unless this was a shared + state created by std::async which is not yet ready, this operation does not + block. + * abandon: the promise stores the exception of type std::future_error with error + code std::future_errc::broken_promise, makes the shared state ready, and then + releases it. - This section is incomplete + The promise is the "push" end of the promise-future communication channel: the + operation that stores a value in the shared state synchronizes-with (as defined in + std::memory_order) the successful return from any function that is waiting on the + shared state (such as std::future::get). Concurrent access to the same shared state + may conflict otherwise: for example multiple callers of std::shared_future::get must + either all be read-only or provide external synchronization. .SH Member functions constructor constructs the promise object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the promise object - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the shared state - \fI(public member function)\fP + \fI(public member function)\fP swap swaps two promise objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Getting the result get_future returns a future associated with the promised result - \fI(public member function)\fP + \fI(public member function)\fP .SH Setting the result set_value sets the result to specific value - \fI(public member function)\fP + \fI(public member function)\fP sets the result to specific value while delivering the set_value_at_thread_exit notification only at thread exit - \fI(public member function)\fP + \fI(public member function)\fP set_exception sets the result to indicate an exception - \fI(public member function)\fP + \fI(public member function)\fP sets the result to indicate an exception while set_exception_at_thread_exit delivering the notification only at thread exit - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::promise) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes std::uses_allocator specializes the std::uses_allocator type trait - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP + +.SH Example + + This example shows how promise can be used as signals between threads. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void accumulate(std::vector::iterator first, + std::vector::iterator last, + std::promise accumulate_promise) + { + int sum = std::accumulate(first, last, 0); + accumulate_promise.set_value(sum); // Notify future + } + + void do_work(std::promise barrier) + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + barrier.set_value(); + } + + int main() + { + // Demonstrate using promise to transmit a result between threads. + std::vector numbers = {1, 2, 3, 4, 5, 6}; + std::promise accumulate_promise; + std::future accumulate_future = accumulate_promise.get_future(); + std::thread work_thread(accumulate, numbers.begin(), numbers.end(), + std::move(accumulate_promise)); + + // future::get() will wait until the future has a valid result and retrieves it. + // Calling wait() before get() is not needed + // accumulate_future.wait(); // wait for result + std::cout << "result=" << accumulate_future.get() << '\\n'; + work_thread.join(); // wait for thread completion + + // Demonstrate using promise to signal state between threads. + std::promise barrier; + std::future barrier_future = barrier.get_future(); + std::thread new_work_thread(do_work, std::move(barrier)); + barrier_future.wait(); + new_work_thread.join(); + } -.SH Category: +.SH Output: - * Todo without reason + result=21 diff --git a/man/std::promise::get_future.3 b/man/std::promise::get_future.3 index 7dc0976ff..381c9debb 100644 --- a/man/std::promise::get_future.3 +++ b/man/std::promise::get_future.3 @@ -1,11 +1,19 @@ -.TH std::promise::get_future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::get_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::get_future \- std::promise::get_future + .SH Synopsis std::future get_future(); \fI(since C++11)\fP Returns a future object associated with the same shared state as *this. - Exception is thrown if *this has no shared state or get_future has already been - called. + An exception is thrown if *this has no shared state or get_future has already been + called. To get multiple "pop" ends of the promise-future communication channel, use + std::future::share. + + Calls to this function do not introduce data races with calls to set_value, + set_exception, set_value_at_thread_exit, or set_exception_at_thread_exit (therefore + they need not synchronize with each other). .SH Parameters @@ -13,13 +21,12 @@ .SH Return value - A future referring to the shared state of *this + A future referring to the shared state of *this. .SH Exceptions std::future_error on the following conditions: - * *this has no shared state. The error category is set to no_state. - + * *this has no shared state. The error code is set to no_state. * get_future() has already been called on a promise with the same shared state as - *this. The error category is set to future_already_retrieved. + *this. The error code is set to future_already_retrieved. diff --git a/man/std::promise::operator=.3 b/man/std::promise::operator=.3 index 3f6f2d938..e6857efcd 100644 --- a/man/std::promise::operator=.3 +++ b/man/std::promise::operator=.3 @@ -1,6 +1,9 @@ -.TH std::promise::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::operator= \- std::promise::operator= + .SH Synopsis - promise& operator=( promise&& other ); \fB(1)\fP \fI(since C++11)\fP + promise& operator=( promise&& other ) noexcept; \fB(1)\fP \fI(since C++11)\fP promise& operator=( const promise& rhs ) = delete; \fB(2)\fP \fI(since C++11)\fP Assigns the contents. @@ -17,10 +20,3 @@ .SH Return value *this - -.SH Exceptions - - 1) - noexcept specification: - noexcept - diff --git a/man/std::promise::promise.3 b/man/std::promise::promise.3 index 754315d53..359b5f544 100644 --- a/man/std::promise::promise.3 +++ b/man/std::promise::promise.3 @@ -1,9 +1,12 @@ -.TH std::promise::promise 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::promise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::promise \- std::promise::promise + .SH Synopsis promise(); \fB(1)\fP \fI(since C++11)\fP template< class Alloc > \fB(2)\fP \fI(since C++11)\fP promise( std::allocator_arg_t, const Alloc& alloc ); - promise( promise&& other ); \fB(3)\fP \fI(since C++11)\fP + promise( promise&& other ) noexcept; \fB(3)\fP \fI(since C++11)\fP promise( const promise& other ) = delete; \fB(4)\fP \fI(since C++11)\fP Constructs a promise object. @@ -12,7 +15,7 @@ 2) Constructs the promise with an empty shared state. The shared state is allocated using alloc. Alloc must meet the requirements of Allocator. 3) Move constructor. Constructs the promise with the shared state of other using - move semantics. other is in valid, but undefined state afterwards. + move semantics. After construction, other has no shared state. 4) promise is not copyable. .SH Parameters @@ -22,9 +25,12 @@ .SH Exceptions - 1-2) \fI(none)\fP - 3) - noexcept specification: - noexcept - - ` + 1,2) May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::promise::set_exception.3 b/man/std::promise::set_exception.3 index 275e68a08..44df4babc 100644 --- a/man/std::promise::set_exception.3 +++ b/man/std::promise::set_exception.3 @@ -1,18 +1,26 @@ -.TH std::promise::set_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::set_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::set_exception \- std::promise::set_exception + .SH Synopsis void set_exception( std::exception_ptr p ); \fI(since C++11)\fP - Stores the exception pointer p into the shared state and makes the state ready. + Atomically stores the exception pointer p into the shared state and makes the state + ready. - The operation is atomic, i.e. it behaves as though they acquire a single mutex - associated with the promise object while updating the promise object. + The operation behaves as though set_value, set_exception, set_value_at_thread_exit, + and set_exception_at_thread_exit acquire a single mutex associated with the promise + object while updating the promise object. An exception is thrown if there is no shared state or the shared state already stores a value or exception. + Calls to this function do not introduce data races with calls to get_future + (therefore they need not synchronize with each other). + .SH Parameters - p - exception pointer to store + p - exception pointer to store. The behavior is undefined if p is null .SH Return value @@ -22,39 +30,50 @@ std::future_error on the following conditions: - * *this has no shared state. The error category is set to no_state. - - * The shared state already stores a value or exception. The error category is set - to promise_already_satisfied. + * *this has no shared state. The error code is set to no_state. + * The shared state already stores a value or exception. The error code is set to + promise_already_satisfied. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { - std::promise result; - - std::thread t([&]{ - try { - // code that may throw - throw std::runtime_error("Example"); - } catch(...) { - try { - // store anything thrown in the promise - result.set_exception(std::current_exception()); - } catch(...) {} // set_exception() may throw too + std::promise p; + std::future f = p.get_future(); + + std::thread t([&p] + { + try + { + // code that may throw + throw std::runtime_error("Example"); + } + catch (...) + { + try + { + // store anything thrown in the promise + p.set_exception(std::current_exception()); + // or throw a custom exception instead + // p.set_exception(std::make_exception_ptr(MyException("mine"))); } + catch (...) {} // set_exception() may throw too + } }); - - try { - std::cout << result.get_future().get(); - } catch(const std::exception& e) { + + try + { + std::cout << f.get(); + } + catch (const std::exception& e) + { std::cout << "Exception from the thread: " << e.what() << '\\n'; } t.join(); @@ -68,4 +87,4 @@ sets the result to indicate an exception while set_exception_at_thread_exit delivering the notification only at thread exit - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::promise::set_exception_at_thread_exit.3 b/man/std::promise::set_exception_at_thread_exit.3 index 814a58858..b840d250a 100644 --- a/man/std::promise::set_exception_at_thread_exit.3 +++ b/man/std::promise::set_exception_at_thread_exit.3 @@ -1,4 +1,7 @@ -.TH std::promise::set_exception_at_thread_exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::set_exception_at_thread_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::set_exception_at_thread_exit \- std::promise::set_exception_at_thread_exit + .SH Synopsis void set_exception_at_thread_exit( std::exception_ptr p ); \fI(since C++11)\fP @@ -6,15 +9,19 @@ immediately. The state is made ready when the current thread exits, after all variables with thread-local storage duration have been destroyed. - The operation is atomic, i.e. it behaves as though they acquire a single mutex - associated with the promise object while updating the promise object. + The operation behaves as though set_value, set_exception, set_value_at_thread_exit, + and set_exception_at_thread_exit acquire a single mutex associated with the promise + object while updating the promise object. An exception is thrown if there is no shared state or the shared state already stores a value or exception. + Calls to this function do not introduce data races with calls to get_future + (therefore they need not synchronize with each other). + .SH Parameters - p - exception pointer to store + p - exception pointer to store. The behavior is undefined if p is nullptr .SH Return value @@ -24,10 +31,9 @@ std::future_error on the following conditions: - * *this has no shared state. The error category is set to no_state. - - * The shared state already stores a value or exception. The error category is set - to promise_already_satisfied. + * *this has no shared state. The error code is set to no_state. + * The shared state already stores a value or exception. The error code is set to + promise_already_satisfied. .SH Example @@ -37,8 +43,7 @@ .SH See also set_exception sets the result to indicate an exception - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::promise::set_value.3 b/man/std::promise::set_value.3 index 8b2f837f8..87c9eead7 100644 --- a/man/std::promise::set_value.3 +++ b/man/std::promise::set_value.3 @@ -1,23 +1,25 @@ -.TH std::promise::set_value 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::set_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::set_value \- std::promise::set_value + .SH Synopsis - void set_value( const R& value ); \fB(1)\fP (member only of generic promise template) - \fI(since C++11)\fP - void set_value( R&& value ); \fB(2)\fP (member only of generic promise template) - \fI(since C++11)\fP - (member only of promise template - void set_value( R& value ); \fB(3)\fP specialization) - \fI(since C++11)\fP - (member only of promise template - void set_value() \fB(4)\fP specialization) - \fI(since C++11)\fP + Main template + void set_value( const R& value ); \fB(1)\fP \fI(since C++11)\fP + void set_value( R&& value ); \fB(2)\fP \fI(since C++11)\fP + std::promise specializations + void set_value( R& value ); \fB(3)\fP \fI(since C++11)\fP + std::promise specialization + void set_value(); \fB(4)\fP \fI(since C++11)\fP - Stores the value into the shared state and makes the state ready. + 1-3) Atomically stores value into the shared state and makes the state ready. + 4) Makes the state ready. - The operation is atomic, i.e. it behaves as though they acquire a single mutex - associated with the promise object while updating the promise object. + The operation behaves as though set_value, set_exception, set_value_at_thread_exit, + and set_exception_at_thread_exit acquire a single mutex associated with the promise + object while updating the promise object. - An exception is thrown if there is no shared state or the shared state already - stores a value or exception. + Calls to this function do not introduce data races with calls to get_future + (therefore they need not synchronize with each other). .SH Parameters @@ -31,86 +33,90 @@ std::future_error on the following conditions: - * *this has no shared state. The error category is set to no_state. - - * The shared state already stores a value or exception. The error category is set - to promise_already_satisfied. + * *this has no shared state. The error code is set to no_state. + * The shared state already stores a value or exception. The error code is set to + promise_already_satisfied. Additionally: - 1-2) Any exception thrown by the copy constructor of value - 3) Any exception thrown by the move constructor of value + 1) Any exception thrown by the constructor selected to copy an object of type R. + 2) Any exception thrown by the constructor selected to move an object of type R. .SH Example - This example shows how promise can be used as signals between threads. + This example shows how std::promise can be used as signals between threads. + - // Run this code - #include - #include - #include - #include #include - #include + #include + #include + #include #include + #include #include - + #include + #include + + using namespace std::chrono_literals; + int main() { std::istringstream iss_numbers{"3 4 1 42 23 -23 93 2 -289 93"}; std::istringstream iss_letters{" a 23 b,e a2 k k?a;si,ksa c"}; - + std::vector numbers; std::vector letters; std::promise numbers_promise, letters_promise; - + auto numbers_ready = numbers_promise.get_future(); auto letter_ready = letters_promise.get_future(); - + std::thread value_reader([&] { - // I/O operations. + // I/O operations std::copy(std::istream_iterator{iss_numbers}, std::istream_iterator{}, std::back_inserter(numbers)); - - //Notify for numbers. + + // notify for numbers numbers_promise.set_value(); - + std::copy_if(std::istreambuf_iterator{iss_letters}, std::istreambuf_iterator{}, std::back_inserter(letters), ::isalpha); - - //Notify for letters. + + // notify for letters letters_promise.set_value(); }); - - + + numbers_ready.wait(); - + std::sort(numbers.begin(), numbers.end()); - - if (letter_ready.wait_for(std::chrono::seconds(1)) == - std::future_status::timeout) + + if (letter_ready.wait_for(1s) == std::future_status::timeout) { - //output the numbers while letters are being obtained. - for (int num : numbers) std::cout << num << ' '; - numbers.clear(); //Numbers were already printed. + // output the numbers while letters are being obtained + for (int num : numbers) + std::cout << num << ' '; + numbers.clear(); // numbers were already printed } - + letter_ready.wait(); std::sort(letters.begin(), letters.end()); - - //If numbers were already printed, it does nothing. - for (int num : numbers) std::cout << num << ' '; + + // does nothing if numbers were already printed + for (int num : numbers) + std::cout << num << ' '; std::cout << '\\n'; - - for (char let : letters) std::cout << let << ' '; + + for (char let : letters) + std::cout << let << ' '; std::cout << '\\n'; - + value_reader.join(); } @@ -119,7 +125,23 @@ -289 -23 1 2 3 4 23 42 93 93 a a a a b c e i k k k s s + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overloads (1,2) could only throw they can throw the exceptions + the thrown + LWG 2098 C++11 exceptions thrown by the by the actual constructor + copy/move selected + constructor of R respectively to copy/move an object of type + R + .SH See also - set_exception sets the result to indicate an exception - \fI(public member function)\fP + sets the result to specific value while delivering the + set_value_at_thread_exit notification only at thread exit + \fI(public member function)\fP + set_exception sets the result to indicate an exception + \fI(public member function)\fP diff --git a/man/std::promise::set_value_at_thread_exit.3 b/man/std::promise::set_value_at_thread_exit.3 index d9b42abbd..ff7c83a09 100644 --- a/man/std::promise::set_value_at_thread_exit.3 +++ b/man/std::promise::set_value_at_thread_exit.3 @@ -1,27 +1,26 @@ -.TH std::promise::set_value_at_thread_exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::set_value_at_thread_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::set_value_at_thread_exit \- std::promise::set_value_at_thread_exit + .SH Synopsis - void set_value_at_thread_exit( const R& (member only of generic promise - value ); \fB(1)\fP template) - \fI(since C++11)\fP - (member only of generic promise - void set_value_at_thread_exit( R&& value ); \fB(2)\fP template) - \fI(since C++11)\fP - (member only of promise template - void set_value_at_thread_exit( R& value ); \fB(3)\fP specialization) - \fI(since C++11)\fP - (member only of promise - void set_value_at_thread_exit() \fB(4)\fP template specialization) - \fI(since C++11)\fP + Main template + void set_value_at_thread_exit( const R& value ); \fB(1)\fP \fI(since C++11)\fP + void set_value_at_thread_exit( R&& value ); \fB(2)\fP \fI(since C++11)\fP + std::promise specializations + void set_value_at_thread_exit( R& value ); \fB(3)\fP \fI(since C++11)\fP + std::promise specialization + void set_value_at_thread_exit(); \fB(4)\fP \fI(since C++11)\fP Stores the value into the shared state without making the state ready immediately. The state is made ready when the current thread exits, after all variables with thread-local storage duration have been destroyed. - The operation is atomic, i.e. it behaves as though they acquire a single mutex - associated with the promise object while updating the promise object. + The operation behaves as though set_value, set_exception, set_value_at_thread_exit, + and set_exception_at_thread_exit acquire a single mutex associated with the promise + object while updating the promise object. - An exception is thrown if there is no shared state or the shared state already - stores a value or exception. + Calls to this function do not introduce data races with calls to get_future + (therefore they need not synchronize with each other). .SH Parameters @@ -35,26 +34,58 @@ std::future_error on the following conditions: - * *this has no shared state. The error category is set to no_state. - - * The shared state already stores a value or exception. The error category is set - to promise_already_satisfied. + * *this has no shared state. The error code is set to no_state. + * The shared state already stores a value or exception. The error code is set to + promise_already_satisfied. Additionally: - 1-2) Any exception thrown by the copy constructor of value - 3) Any exception thrown by the move constructor of value + 1) Any exception thrown by the constructor selected to copy an object of type R. + 2) Any exception thrown by the constructor selected to move an object of type R. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::chrono_literals; + std::promise p; + std::future f = p.get_future(); + std::thread([&p] + { + std::this_thread::sleep_for(1s); + p.set_value_at_thread_exit(9); + }).detach(); + + std::cout << "Waiting... " << std::flush; + f.wait(); + std::cout << "Done!\\nResult is: " << f.get() << '\\n'; + } - set_value sets the result to specific value - \fI(public member function)\fP +.SH Output: -.SH Category: + Waiting... Done! + Result is: 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2098 C++11 it was unclear which exceptions are required to made clear + be thrown + +.SH See also - * Todo no example + set_value sets the result to specific value + \fI(public member function)\fP + sets the result to indicate an exception while + set_exception_at_thread_exit delivering the notification only at thread exit + \fI(public member function)\fP diff --git a/man/std::promise::swap.3 b/man/std::promise::swap.3 index 6573ca25b..f7015cbd3 100644 --- a/man/std::promise::swap.3 +++ b/man/std::promise::swap.3 @@ -1,6 +1,9 @@ -.TH std::promise::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::swap \- std::promise::swap + .SH Synopsis - void swap( promise& other ); \fI(since C++11)\fP + void swap( promise& other ) noexcept; \fI(since C++11)\fP Exchanges the shared states of two promise objects. @@ -12,12 +15,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -26,8 +23,7 @@ .SH See also std::swap(std::promise) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::promise::~promise.3 b/man/std::promise::~promise.3 index a653dd27d..dfb41478b 100644 --- a/man/std::promise::~promise.3 +++ b/man/std::promise::~promise.3 @@ -1,4 +1,7 @@ -.TH std::promise::~promise 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::promise::~promise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::promise::~promise \- std::promise::~promise + .SH Synopsis ~promise(); \fI(since C++11)\fP diff --git a/man/std::ptr_fun.3 b/man/std::ptr_fun.3 index 90da80747..a14067449 100644 --- a/man/std::ptr_fun.3 +++ b/man/std::ptr_fun.3 @@ -1,14 +1,17 @@ -.TH std::ptr_fun 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ptr_fun 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ptr_fun \- std::ptr_fun + .SH Synopsis Defined in header template< class Arg, class Result > - - std::pointer_to_unary_function \fB(1)\fP \fB(deprecated)\fP + (deprecated in C++11) + std::pointer_to_unary_function \fB(1)\fP (removed in C++17) ptr_fun( Result (*f)(Arg) ); template< class Arg1, class Arg2, class Result > - - std::pointer_to_binary_function \fB(2)\fP \fB(deprecated)\fP + (deprecated in C++11) + std::pointer_to_binary_function \fB(2)\fP (removed in C++17) ptr_fun( Result (*f)(Arg1, Arg2) ); @@ -17,11 +20,10 @@ arguments. 1) Effectively calls std::pointer_to_unary_function(f). - 2) Effectively calls std::pointer_to_binary_function(f). This function and the related types are deprecated as of C++11 in favor of the more - general std::function and std::ref, both of which create callable adapter-compatible + general std::function and std::ref, both of which create callable adaptor-compatible function objects from plain functions. .SH Parameters @@ -34,34 +36,54 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code - #include - #include #include #include - - bool isvowel(char c) + #include + #include + + constexpr bool is_vowel(char c) { - return std::string("aeoiuAEIOU").find(c) != std::string::npos; + return std::string_view{"aeoiuAEIOU"}.find(c) != std::string_view::npos; } - + int main() { - std::string s = "Hello, world!"; - std::copy_if(s.begin(), s.end(), std::ostreambuf_iterator(std::cout), - std::not1(std::ptr_fun(isvowel))); + std::string_view s = "Hello, world!"; + std::ranges::copy_if(s, std::ostreambuf_iterator(std::cout), + std::not1(std::ptr_fun(is_vowel))); + #if 0 // C++11 alternatives: - // std::not1(std::ref(isvowel))); - // std::not1(std::function(isvowel))); - + std::not1(std::cref(is_vowel))); + std::not1(std::function(is_vowel))); + [](char c) { return !is_vowel(c); }); + // C++17 alternatives: + std::not_fn(is_vowel)); + #endif } .SH Output: Hll, wrld! + +.SH See also + + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP + not_fn creates a function object that returns the complement of the + \fI(C++17)\fP result of the function object it holds + \fI(function template)\fP diff --git a/man/std::ptrdiff_t.3 b/man/std::ptrdiff_t.3 index cc9963696..ea2ee143c 100644 --- a/man/std::ptrdiff_t.3 +++ b/man/std::ptrdiff_t.3 @@ -1,10 +1,15 @@ -.TH std::ptrdiff_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ptrdiff_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ptrdiff_t \- std::ptrdiff_t + .SH Synopsis Defined in header typedef /*implementation-defined*/ ptrdiff_t; std::ptrdiff_t is the signed integer type of the result of subtracting two pointers. + The bit width of std::ptrdiff_t is not less than 17. \fI(since C++11)\fP + .SH Notes std::ptrdiff_t is used for pointer arithmetic and array indexing, if negative values @@ -24,29 +29,46 @@ For char arrays shorter than PTRDIFF_MAX, std::ptrdiff_t acts as the signed counterpart of std::size_t: it can store the size of the array of any type and is, - on most platforms, synonymous with std::intptr_t). + on most platforms, synonymous with std::intptr_t. + + It is unspecified whether the declaration of std::ptrdiff_t is available in any + other standard library header. An implementation may avoid introducing this name + even when the standard requires std::ptrdiff_t to be used. + +.SH Possible implementation + + // valid since C++11 + using ptrdiff_t = decltype(static_cast(nullptr) - static_cast(nullptr)); .SH Example - + // Run this code #include - + #include + int main() { - const std::size_t N = 100; + const std::size_t N = 10; int* a = new int[N]; int* end = a + N; for (std::ptrdiff_t i = N; i > 0; --i) - *(end - i) = i; + std::cout << (*(end - i) = i) << ' '; + std::cout << '\\n'; delete[] a; } +.SH Output: + + 10 9 8 7 6 5 4 3 2 1 + .SH See also size_t unsigned integer type returned by the sizeof operator - \fI(typedef)\fP + \fI(typedef)\fP byte offset from the beginning of a standard-layout type to specified offsetof member - \fI(function macro)\fP + \fI(function macro)\fP + C documentation for + ptrdiff_t diff --git a/man/std::push_heap.3 b/man/std::push_heap.3 index 2b7043e5f..eb6afb13d 100644 --- a/man/std::push_heap.3 +++ b/man/std::push_heap.3 @@ -1,97 +1,132 @@ -.TH std::push_heap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::push_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::push_heap \- std::push_heap + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP + template< class RandomIt > \fB(1)\fP (constexpr since C++20) void push_heap( RandomIt first, RandomIt last ); template< class RandomIt, class Compare > + void push_heap( RandomIt first, RandomIt last, Compare \fB(2)\fP (constexpr since C++20) + comp ); + + Inserts the element at the position last - 1 into the heap [first, last - 1). The + heap after the insertion will be [first, last). - void push_heap( RandomIt first, RandomIt last, \fB(2)\fP + 1) The heap is with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) The heap is with respect to comp. - Compare comp ); + If any of the following conditions is satisfied, the behavior is undefined: - Inserts the element at the position last-1 into the max heap defined by the range - [first, last-1). The first version of the function uses operator< to compare the - elements, the second uses the given comparison function comp. + * [first, last - 1) is not a heap. + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements defining the heap to modify - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the range indicating the heap after the insertion + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. - -.SH Return value - - \fI(none)\fP + Compare must meet the requirements of Compare. .SH Complexity - At most 2×log(N) comparisons where N=std::distance(first, last). + Given \\(\\scriptsize N\\)N as std::distance(first, last): -.SH Notes - - A max heap is a range of elements [f,l) that has the following properties: - - * *f is the largest element in the range - * a new element can be added using std::push_heap() - * the first element can be removed using std::pop_heap() - - The actual arrangement of the elements is implementation defined. + 1) At most \\(\\scriptsize \\log(N)\\)log(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize \\log(N)\\)log(N) applications of the comparison function + comp. .SH Example - + // Run this code - #include #include - + #include + #include + #include + + void println(std::string_view rem, const std::vector& v) + { + std::cout << rem; + for (int e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { - std::vector v { 3, 1, 4, 1, 5, 9 }; - + std::vector v{3, 1, 4, 1, 5, 9}; + std::make_heap(v.begin(), v.end()); - - std::cout << "v: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; - + println("after make_heap: ", v); + v.push_back(6); - - std::cout << "before push_heap: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; - + println("after push_back: ", v); + std::push_heap(v.begin(), v.end()); - - std::cout << "after push_heap: "; - for (auto i : v) std::cout << i << ' '; - std::cout << '\\n'; + println("after push_heap: ", v); } .SH Output: - v: 9 5 4 1 1 3 - before push_heap: 9 5 4 1 1 3 6 - after push_heap: 9 5 6 1 1 3 4 + after make_heap: 9 5 4 1 1 3 + after push_back: 9 5 4 1 1 3 6 + after push_heap: 9 5 6 1 1 3 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3032 C++98 the elements of [first, last) was not required required + to be swappable .SH See also - pop_heap removes the largest element from a max heap - \fI(function template)\fP + is_heap checks if the given range is a max heap + \fI(C++11)\fP \fI(function template)\fP + is_heap_until finds the largest subrange that is a max heap + \fI(C++11)\fP \fI(function template)\fP + make_heap creates a max heap out of a range of elements + \fI(function template)\fP + pop_heap removes the largest element from a max heap + \fI(function template)\fP + turns a max heap into a range of elements sorted in ascending + sort_heap order + \fI(function template)\fP + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) diff --git a/man/std::put_money.3 b/man/std::put_money.3 index befbbe1ce..60c4e369f 100644 --- a/man/std::put_money.3 +++ b/man/std::put_money.3 @@ -1,4 +1,7 @@ -.TH std::put_money 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::put_money 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::put_money \- std::put_money + .SH Synopsis Defined in header template< class MoneyT > \fI(since C++11)\fP @@ -8,47 +11,66 @@ mon to its character representation as specified by the std::money_put facet of the locale currently imbued in out. - This function behaves as a FormattedOutputFunction + The insertion operation in out << put_money(mon, intl) behaves as a + FormattedOutputFunction. .SH Parameters - mon - a monetary value, either long double or basic_string + mon - a monetary value, either long double or std::basic_string intl - use international currency strings if true, use currency symbols otherwise .SH Return value - Returns an object of unspecified type such that if out is the name of an output - stream of type std::basic_ostream, then the expression out << - put_money(mon, intl) behaves as if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << put_money(mon, intl) + * has type std::basic_ostream& + * has value out + * behaves as a FormattedOutputFunction that calls f(out, mon, intl) - typedef std::ostreambuf_iterator Iter; - typedef std::money_put MoneyPut; - const MoneyPut& mp = std::use_facet(out.getloc()); - const Iter end = mp.put(Iter(out.rdbuf()), intl, out, out.fill(), mon); - if (end.failed()) - out.setstate(std::ios::badbit); + where the function f is defined as: + + template + void f(std::basic_ios& str, const MoneyT& mon, bool intl) + { + using Iter = std::ostreambuf_iterator; + using MoneyPut = std::money_put; + + const MoneyPut& mp = std::use_facet(str.getloc()); + const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon); + + if (end.failed()) + str.setstate(std::ios_base::badbit); + } .SH Example - + // Run this code - #include #include - + #include + int main() { long double mon = 123.45; // or std::string mon = "123.45"; - std::cout.imbue(std::locale("en_US.utf8")); + + std::cout.imbue(std::locale("en_US.UTF-8")); std::cout << std::showbase - << "en_US: " << std::put_money(mon) << " or " << std::put_money(mon, true) << '\\n'; - std::cout.imbue(std::locale("ru_RU.utf8")); - std::cout << "ru_RU: " << std::put_money(mon) << " or " << std::put_money(mon, true) << '\\n'; - std::cout.imbue(std::locale("ja_JP.utf8")); - std::cout << "ja_JP: " << std::put_money(mon) << " or " << std::put_money(mon, true) << '\\n'; + << "en_US: " << std::put_money(mon) + << " or " << std::put_money(mon, true) << '\\n'; + + std::cout.imbue(std::locale("ru_RU.UTF-8")); + std::cout << "ru_RU: " << std::put_money(mon) + << " or " << std::put_money(mon, true) << '\\n'; + + std::cout.imbue(std::locale("ja_JP.UTF-8")); + std::cout << "ja_JP: " << std::put_money(mon) + << " or " << std::put_money(mon, true) << '\\n'; } -.SH Output: +.SH Possible output: en_US: $1.23 or USD 1.23 ru_RU: 1.23 руб or 1.23 RUB @@ -57,6 +79,6 @@ .SH See also money_put formats a monetary value for output as a character sequence - \fI(class template)\fP + \fI(class template)\fP get_money parses a monetary value - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::put_time.3 b/man/std::put_time.3 index d05309e53..ede9e97cf 100644 --- a/man/std::put_time.3 +++ b/man/std::put_time.3 @@ -1,4 +1,7 @@ -.TH std::put_time 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::put_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::put_time \- std::put_time + .SH Synopsis Defined in header template< class CharT > \fI(since C++11)\fP @@ -12,223 +15,230 @@ .SH Parameters - tmb - pointer to the calendar time structure as obtained from localtime() or - gmtime() - pointer to a null-terminated CharT string specifying the format of conversion. - - The format string consists of zero or more conversion specifiers and ordinary - characters (except %). All ordinary characters, including the terminating null - character, are copied to the output string without modification. Each - conversion specification begins with % character, optionally followed by E or - O modifier (ignored if unsupported by the locale), followed by the character - that determines the behavior of the specifier. The following format specifiers - are available: - - Conversion Explanation Used fields - specifier - % writes literal %. The full conversion - specification must be %%. - n writes newline character - \fI(C++11)\fP - t writes horizontal tab character - \fI(C++11)\fP - Year - Y writes year as a 4 digit decimal number tm_year - EY writes year in the alternative representation, - \fI(C++11)\fP e.g.平成23年 (year Heisei 23) instead of 2011年 tm_year - (year 2011) in ja_JP locale - y writes last 2 digits of year as a decimal number tm_year - (range [00,99]) - Oy writes last 2 digits of year using the - \fI(C++11)\fP alternative numeric system, e.g. 十一 instead of tm_year - 11 in ja_JP locale - Ey writes year as offset from locale's alternative tm_year - \fI(C++11)\fP calendar period %EC (locale-dependent) - C writes first 2 digits of year as a decimal number tm_year - \fI(C++11)\fP (range [00,99]) - EC writes name of the base year (period) in the - \fI(C++11)\fP locale's alternative representation, e.g. 平成 tm_year - (Heisei era) in ja_JP - writes ISO 8601 week-based year, i.e. the year - that contains the specified week. - - G In IS0 8601 weeks begin with Monday and the first tm_year, tm_wday, - \fI(C++11)\fP week of the year must satisfy the following tm_yday - requirements: - - * Includes January 4 - * Includes first Thursday of the year - writes last 2 digits of ISO 8601 week-based year, - i.e. the year that contains the specified week - (range [00,99]). - - g In IS0 8601 weeks begin with Monday and the first tm_year, tm_wday, - \fI(C++11)\fP week of the year must satisfy the following tm_yday - requirements: - - * Includes January 4 - * Includes first Thursday of the year - Month - b writes abbreviated month name, e.g. Oct (locale tm_mon - dependent) - h synonym of b tm_mon - \fI(C++11)\fP - B writes full month name, e.g. October (locale tm_mon - dependent) - m writes month as a decimal number (range [01,12]) tm_mon - Om writes month using the alternative numeric tm_mon - \fI(C++11)\fP system, e.g. 十二 instead of 12 in ja_JP locale - Week - writes week of the year as a decimal number tm_year, tm_wday, - U (Sunday is the first day of the week) (range tm_yday - [00,53]) - OU writes week of the year, as by %U, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead tm_yday - of 52 in ja_JP locale - writes week of the year as a decimal number tm_year, tm_wday, - W (Monday is the first day of the week) (range tm_yday - [00,53]) - OW writes week of the year, as by %W, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead tm_yday - of 52 in ja_JP locale - writes ISO 8601 week of the year (range [01,53]). - - In IS0 8601 weeks begin with Monday and the first - V week of the year must satisfy the following tm_year, tm_wday, - \fI(C++11)\fP requirements: tm_yday - - * Includes January 4 - * Includes first Thursday of the year - fmt - OV writes week of the year, as by %V, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead tm_yday - of 52 in ja_JP locale - Day of the year/month - j writes day of the year as a decimal number (range tm_yday - [001,366]) - d writes day of the month as a decimal number tm_mday - (range [01,31]) - writes zero-based day of the month using the - Od alternative numeric system, e.g 二十七 instead of - \fI(C++11)\fP 23 in ja_JP locale tm_mday - - Single character is preceded by a space. - writes day of the month as a decimal number - e (range [1,31]). tm_mday - \fI(C++11)\fP - Single digit is preceded by a space. - writes one-based day of the month using the - Oe alternative numeric system, e.g. 二十七 instead - \fI(C++11)\fP of 27 in ja_JP locale tm_mday - - Single character is preceded by a space. - Day of the week - a writes abbreviated weekday name, e.g. Fri (locale tm_wday - dependent) - A writes full weekday name, e.g. Friday (locale tm_wday - dependent) - w writes weekday as a decimal number, where Sunday tm_wday - is 0 (range [0-6]) - Ow writes weekday, where Sunday is 0, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 tm_wday - in ja_JP locale - u writes weekday as a decimal number, where Monday tm_wday - \fI(C++11)\fP is 1 (ISO 8601 format) (range [1-7]) - Ou writes weekday, where Monday is 1, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 tm_wday - in ja_JP locale - Hour, minute, second - H writes hour as a decimal number, 24 hour clock tm_hour - (range [00-23]) - OH writes hour from 24-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 十八 instead of tm_hour - 18 in ja_JP locale - I writes hour as a decimal number, 12 hour clock tm_hour - (range [01,12]) - OI writes hour from 12-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 六 instead of 06 tm_hour - in ja_JP locale - M writes minute as a decimal number (range [00,59]) tm_min - OM writes minute using the alternative numeric tm_min - \fI(C++11)\fP system, e.g. 二十五 instead of 25 in ja_JP locale - S writes second as a decimal number (range [00,60]) tm_sec - OS writes second using the alternative numeric tm_sec - \fI(C++11)\fP system, e.g. 二十四 instead of 24 in ja_JP locale + tmb - pointer to the calendar time structure as obtained from std::localtime or + std::gmtime + fmt - pointer to a null-terminated CharT string specifying the format of conversion + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters (except %). All ordinary characters, including the terminating null + character, are copied to the output string without modification. Each conversion + specification begins with % character, optionally followed by E or O modifier + (ignored if unsupported by the locale), followed by the character that determines + the behavior of the specifier. The following format specifiers are available: + + Conversion Explanation Used fields + specifier + % writes literal %. The full conversion specification + must be %%. + n writes newline character + \fI(C++11)\fP + t writes horizontal tab character + \fI(C++11)\fP + Year + Y writes year as a decimal number, e.g. 2017 tm_year + EY writes year in the alternative representation, e.g.平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) tm_year + in ja_JP locale + y writes last 2 digits of year as a decimal number (range tm_year + [00,99]) + Oy writes last 2 digits of year using the alternative tm_year + \fI(C++11)\fP numeric system, e.g. 十一 instead of 11 in ja_JP locale + Ey writes year as offset from locale's alternative tm_year + \fI(C++11)\fP calendar period %EC (locale-dependent) + C writes first 2 digits of year as a decimal number tm_year + \fI(C++11)\fP (range [00,99]) + EC writes name of the base year (period) in the locale's + \fI(C++11)\fP alternative representation, e.g. 平成 (Heisei era) in tm_year + ja_JP + writes ISO 8601 week-based year, i.e. the year that + contains the specified week. + + G In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + writes last 2 digits of ISO 8601 week-based year, i.e. + the year that contains the specified week (range + [00,99]). + g tm_year, tm_wday, + \fI(C++11)\fP In ISO 8601 weeks begin with Monday and the first week tm_yday + of the year must satisfy the following requirements: + + * Includes January 4 + * Includes first Thursday of the year + Month + b writes abbreviated month name, e.g. Oct (locale tm_mon + dependent) + h synonym of b tm_mon + \fI(C++11)\fP + B writes full month name, e.g. October (locale dependent) tm_mon + m writes month as a decimal number (range [01,12]) tm_mon + Om writes month using the alternative numeric system, e.g. tm_mon + \fI(C++11)\fP 十二 instead of 12 in ja_JP locale + Week + U writes week of the year as a decimal number (Sunday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OU writes week of the year, as by %U, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + W writes week of the year as a decimal number (Monday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OW writes week of the year, as by %W, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + writes ISO 8601 week of the year (range [01,53]). + + V In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + OV writes week of the year, as by %V, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + Day of the year/month + j writes day of the year as a decimal number (range tm_yday + [001,366]) + d writes day of the month as a decimal number (range tm_mday + [01,31]) + writes zero-based day of the month using the + Od alternative numeric system, e.g. 二十七 instead of 27 + \fI(C++11)\fP in ja_JP locale tm_mday + + Single character is preceded by a space. + writes day of the month as a decimal number (range + e [1,31]). tm_mday + \fI(C++11)\fP + Single digit is preceded by a space. + writes one-based day of the month using the alternative + Oe numeric system, e.g. 二十七 instead of 27 in ja_JP + \fI(C++11)\fP locale tm_mday + + Single character is preceded by a space. + Day of the week + a writes abbreviated weekday name, e.g. Fri (locale tm_wday + dependent) + A writes full weekday name, e.g. Friday (locale tm_wday + dependent) + w writes weekday as a decimal number, where Sunday is 0 tm_wday + (range [0-6]) + Ow writes weekday, where Sunday is 0, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + u writes weekday as a decimal number, where Monday is 1 tm_wday + \fI(C++11)\fP (ISO 8601 format) (range [1-7]) + Ou writes weekday, where Monday is 1, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + Hour, minute, second + H writes hour as a decimal number, 24 hour clock (range tm_hour + [00-23]) + OH writes hour from 24-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 十八 instead of 18 in ja_JP locale + I writes hour as a decimal number, 12 hour clock (range tm_hour + [01,12]) + OI writes hour from 12-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 六 instead of 06 in ja_JP locale + M writes minute as a decimal number (range [00,59]) tm_min + OM writes minute using the alternative numeric system, tm_min + \fI(C++11)\fP e.g. 二十五 instead of 25 in ja_JP locale + S writes second as a decimal number (range [00,60]) tm_sec + OS writes second using the alternative numeric system, tm_sec + \fI(C++11)\fP e.g. 二十四 instead of 24 in ja_JP locale .SH Other - c writes standard date and time string, e.g. Sun all - Oct 17 04:41:13 2010 (locale dependent) - Ec writes alternative date and time string, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of 2011年 all - (year 2011) in ja_JP locale - x writes localized date representation (locale all - dependent) - Ex writes alternative date representation, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of 2011年 all - (year 2011) in ja_JP locale - X writes localized time representation (locale all - dependent) - EX writes alternative time representation (locale all - \fI(C++11)\fP dependent) - D equivalent to "%m/%d/%y" tm_mon, tm_mday, - \fI(C++11)\fP tm_year - F equivalent to "%Y-%m-%d" (the ISO 8601 date tm_mon, tm_mday, - \fI(C++11)\fP format) tm_year - r writes localized 12-hour clock time (locale tm_hour, tm_min, - \fI(C++11)\fP dependent) tm_sec - R equivalent to "%H:%M" tm_hour, tm_min - \fI(C++11)\fP - T equivalent to "%H:%M:%S" (the ISO 8601 time tm_hour, tm_min, - \fI(C++11)\fP format) tm_sec - p writes localized a.m. or p.m. (locale dependent) tm_hour - z writes offset from UTC in the ISO 8601 format - \fI(C++11)\fP (e.g. -0430), or no characters if the time zone tm_isdst - information is not available - writes time zone name or abbreviation, or no - Z characters if the time zone information is not tm_isdst - available (locale dependent) + c writes standard date and time string, e.g. Sun Oct 17 all + 04:41:13 2010 (locale dependent) + Ec writes alternative date and time string, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + x writes localized date representation (locale dependent) all + Ex writes alternative date representation, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + X writes localized time representation, e.g. 18:40:20 or all + 6:40:20 PM (locale dependent) + EX writes alternative time representation (locale all + \fI(C++11)\fP dependent) + D equivalent to "%m/%d/%y" tm_mon, tm_mday, + \fI(C++11)\fP tm_year + F equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday, + \fI(C++11)\fP tm_year + r writes localized 12-hour clock time (locale dependent) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + R equivalent to "%H:%M" tm_hour, tm_min + \fI(C++11)\fP + T equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + p writes localized a.m. or p.m. (locale dependent) tm_hour + z writes offset from UTC in the ISO 8601 format (e.g. + \fI(C++11)\fP -0430), or no characters if the time zone information tm_isdst + is not available + writes locale-dependent time zone name or abbreviation, + Z or no characters if the time zone information is not tm_isdst + available .SH Return value - Returns an object of unspecified type such that if out is the name of an output - stream of type std::basic_ostream, then the expression out << - put_time(tmb, fmt) behaves as if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << put_time(tmb, fmt) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, tmb, fmt) + + where the function f is defined as: + + template + void f(std::basic_ios& str, const std::tm* tmb, const CharT* fmt) + { + using Iter = std::ostreambuf_iterator; + using TimePut = std::time_put; + + const TimePut& tp = std::use_facet(str.getloc()); + const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb, + fmt, fmt + Traits::length(fmt)); - typedef std::ostreambuf_iterator Iter; - typedef std::time_put TimePut; - const TimePut& tp = std::use_facet(out.getloc()); - const Iter end = tp.put(Iter(out.rdbuf()), out, out.fill(), tmb, fmt, fmt + - Traits::length(fmt)); - if (end.failed()) - out.setstate(std::ios_base::badbit); + if (end.failed()) + str.setstate(std::ios_base::badbit); + } .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { std::time_t t = std::time(nullptr); std::tm tm = *std::localtime(&t); + std::cout.imbue(std::locale("ru_RU.utf8")); std::cout << "ru_RU: " << std::put_time(&tm, "%c %Z") << '\\n'; + std::cout.imbue(std::locale("ja_JP.utf8")); std::cout << "ja_JP: " << std::put_time(&tm, "%c %Z") << '\\n'; } -.SH Output: +.SH Possible output: ru_RU: Ср. 28 дек. 2011 10:21:16 EST ja_JP: 2011年12月28日 10時21分16秒 EST .SH See also - time_put formats contents of struct std::tm for output as character sequence - \fI(class template)\fP - strftime converts a tm object to custom textual representation - \fI(function)\fP - wcsftime converts a tm object to custom wide string textual representation - \fI(function)\fP + time_put formats contents of std::tm for output as character sequence + \fI(class template)\fP + get_time parses a date/time value of specified format + \fI(C++11)\fP \fI(function template)\fP + strftime converts a std::tm object to custom textual representation + \fI(function)\fP + wcsftime converts a std::tm object to custom wide string textual representation + \fI(function)\fP diff --git a/man/std::putchar.3 b/man/std::putchar.3 index cc9250a25..3eb6a0134 100644 --- a/man/std::putchar.3 +++ b/man/std::putchar.3 @@ -1,4 +1,7 @@ -.TH std::putchar 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::putchar 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::putchar \- std::putchar + .SH Synopsis Defined in header int putchar( int ch ); @@ -6,7 +9,7 @@ Writes a character ch to stdout. Internally, the character is converted to unsigned char just before being written. - Equivalent to putc(ch, stdout). + Equivalent to std::putc(ch, stdout). .SH Parameters @@ -16,38 +19,37 @@ On success, returns the written character. - On failure, returns EOF and sets the error indicator (see ferror()) on stdout. + On failure, returns EOF and sets the error indicator (see std::ferror()) on stdout. .SH Example - + // Run this code #include - + int main() { - for (char c = 'a'; c != 'z'; c++) + for (char c = 'a'; c != 'z'; ++c) std::putchar(c); - std::putchar('\\n'); - + // putchar return value is not equal to the argument - int r = 0x1070; - std::printf("\\n0x%x\\n", r); + int r = 0x1024; + std::printf("\\nr = 0x%x\\n", r); r = std::putchar(r); - std::printf("\\n0x%x\\n", r); + std::printf("\\nr = 0x%x\\n", r); } -.SH Output: +.SH Possible output: abcdefghijklmnopqrstuvwxy - 0x1070 - p - 0x70 + r = 0x1024 + $ + r = 0x24 .SH See also fputc writes a character to a file stream - putc \fI(function)\fP + putc \fI(function)\fP C documentation for putchar diff --git a/man/std::puts.3 b/man/std::puts.3 index d2b9a325f..3cb050804 100644 --- a/man/std::puts.3 +++ b/man/std::puts.3 @@ -1,9 +1,16 @@ -.TH std::puts 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::puts 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::puts \- std::puts + .SH Synopsis Defined in header int puts( const char *str ); - Writes character string str and a newline to stdout + Writes every character from the null-terminated string str and one additional + newline character '\\n' to the output stream stdout, as if by repeatedly executing + std::fputc. + + The terminating null character from str is not written. .SH Parameters @@ -11,15 +18,48 @@ .SH Return value - Non-negative number on success or EOF otherwise + On success, returns a non-negative value + + On failure, returns EOF and sets the error indicator (see std::ferror) on stdout. + +.SH Notes + + The std::puts function appends the newline character to the output, while std::fputs + function does not. + + Different implementations return different non-negative numbers: some return the + last character written, some return the number of characters written (or INT_MAX if + the string was longer than that), some simply return a non-negative constant. + + A typical cause of failure for std::puts is running out of space on the file system, + when stdout is redirected to a file. + +.SH Example + + +// Run this code + + #include + + int main() + { + int rc = std::puts("Hello World"); + + if (rc == EOF) + std::perror("puts()"); // POSIX requires that errno is set + } + +.SH Output: + + Hello World .SH See also fputs writes a character string to a file stream - \fI(function)\fP + \fI(function)\fP printf fprintf prints formatted output to stdout, a file stream or a buffer - sprintf \fI(function)\fP + sprintf \fI(function)\fP snprintf \fI(C++11)\fP C documentation for diff --git a/man/std::putwchar.3 b/man/std::putwchar.3 index 6373acbc5..938e2ac09 100644 --- a/man/std::putwchar.3 +++ b/man/std::putwchar.3 @@ -1,9 +1,12 @@ -.TH std::putwchar 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::putwchar 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::putwchar \- std::putwchar + .SH Synopsis Defined in header - wint_t putwchar( wchar_t ch ); + std::wint_t putwchar( wchar_t ch ); - Writes a wide character ch to stdout + Writes a wide character ch to stdout. .SH Parameters @@ -13,11 +16,44 @@ ch on success, WEOF on failure. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + + for (const wchar_t ch : { + L'\\u2200', // Unicode name: "FOR ALL" + L'∀', + L'\\n' + }) + if (std::putwchar(ch) == WEOF) + { + std::puts("I/O error in std::putwchar"); + return EXIT_FAILURE; + } + + return EXIT_SUCCESS; + } + +.SH Possible output: + + ∀∀ + .SH See also putchar writes a character to stdout - \fI(function)\fP + \fI(function)\fP fputwc writes a wide character to a file stream - putwc \fI(function)\fP + putwc \fI(function)\fP C documentation for putwchar diff --git a/man/std::qsort.3 b/man/std::qsort.3 index c5972b940..f46cc53e4 100644 --- a/man/std::qsort.3 +++ b/man/std::qsort.3 @@ -1,32 +1,51 @@ -.TH std::qsort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::qsort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::qsort \- std::qsort + .SH Synopsis Defined in header - void qsort( void *ptr, std::size_t count, std::size_t size, - int (*comp)(const void *, const void *) ); + void qsort( void *ptr, std::size_t count, + + std::size_t size, /* c-compare-pred */* comp ); \fB(1)\fP + void qsort( void *ptr, std::size_t count, + + std::size_t size, /* compare-pred */* comp ); + extern "C" using /* c-compare-pred */ = int(const void*, + const void*); \fB(2)\fP (exposition only*) + extern "C++" using /* compare-pred */ = int(const void*, + const void*); Sorts the given array pointed to by ptr in ascending order. The array contains count elements of size bytes. Function pointed to by comp is used for object comparison. - If comp indicates two elements as equivalent, their order is undefined. + If comp indicates two elements as equivalent, their order is unspecified. + + If the type of the elements of the array is not a + PODType + \fI(until C++11)\fP + TriviallyCopyable type + \fI(since C++11)\fP, the behavior is undefined. .SH Parameters ptr - pointer to the array to sort - count - number of element in the array + count - number of elements in the array size - size of each element in the array in bytes comparison function which returns a negative integer value if the first - argument is less than the second, + argument is less than the second, a positive integer value if the first + argument is greater than the second and zero if the arguments are + equivalent. - a positive integer value if the first argument is greater than the second - and zero if the arguments are equal. The signature of the comparison function should be equivalent to the - comp - following: - + following: + comp - int cmp(const void *a, const void *b); - The function must not modify the objects passed to it. + The function must not modify the objects passed to it and must return + consistent results when called for the same objects, regardless of their + positions in the array. + - .SH Return value @@ -34,49 +53,71 @@ .SH Notes - The type of the elements of the array must be a trivial type, otherwise the behavior - is undefined. + Despite the name, C++, C, and POSIX standards do not require this function to be + implemented using Quicksort or make any complexity or stability guarantees. + + The two overloads provided by the C++ standard library are distinct because the + types of the parameter comp are distinct (language linkage is part of its type). .SH Example - The following code sorts an array of integers using qsort(). + The following code sorts an array of integers using qsort(): + - // Run this code - #include + #include + #include + #include #include - - int compare_ints(const void* a, const void* b) // comparison function - { - int arg1 = *reinterpret_cast(a); - int arg2 = *reinterpret_cast(b); - if(arg1 < arg2) return -1; - if(arg1 > arg2) return 1; - return 0; - } - + #include + int main() { - int a[] = { -2, 99, 0, -743, 2, 3, 4 }; - constexpr std::size_t size = sizeof(a)/sizeof(int); - - std::qsort(a, size, sizeof(int), compare_ints); - - for (int ai : a) std::cout << ai << ' '; + std::array a{-2, 99, 0, -743, INT_MAX, 2, INT_MIN, 4}; + + std::qsort + ( + a.data(), + a.size(), + sizeof(decltype(a)::value_type), + [](const void* x, const void* y) + { + const int arg1 = *static_cast(x); + const int arg2 = *static_cast(y); + const auto cmp = arg1 <=> arg2; + if (cmp < 0) + return -1; + if (cmp > 0) + return 1; + return 0; + } + ); + + for (int ai : a) + std::cout << ai << ' '; + std::cout << '\\n'; } .SH Output: - -743 -2 0 2 3 4 99 + -2147483648 -743 -2 0 2 4 99 2147483647 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 405 C++98 the elements of the array could have any type limited to PODType .SH See also bsearch searches an array for an element of unspecified type - \fI(function)\fP + \fI(function)\fP sort sorts a range into ascending order - \fI(function template)\fP + \fI(function template)\fP is_trivial checks if a type is trivial - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP C documentation for qsort diff --git a/man/std::queue.3 b/man/std::queue.3 index 4badd9864..3e101960a 100644 --- a/man/std::queue.3 +++ b/man/std::queue.3 @@ -1,4 +1,7 @@ -.TH std::queue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue \- std::queue + .SH Synopsis Defined in header template< @@ -8,9 +11,8 @@ > class queue; - The std::queue class is a container adapter that gives the programmer the - functionality of a queue - specifically, a FIFO (first-in, first-out) data - structure. + The std::queue class is a container adaptor that gives the functionality of a queue + - specifically, a FIFO (first-in, first-out) data structure. The class template acts as a wrapper to the underlying container - only a specific set of functions is provided. The queue pushes the elements on the back of the @@ -18,16 +20,16 @@ .SH Template parameters - T - The type of the stored elements. + T - The type of the stored elements. The program is ill-formed if T is not + the same type as Container::value_type. The type of the underlying container to use to store the elements. The container must satisfy the requirements of SequenceContainer. Additionally, it must provide the following functions with the usual semantics: - - Container - * back() - * front() - * push_back() - * pop_front() + * back(), e.g., std::deque::back(), + Container - * front(), e.g. std::list::front(), + * push_back(), e.g., std::deque::push_back(), + * pop_front(), e.g., std::list::pop_front(). The standard containers std::deque and std::list satisfy these requirements. @@ -35,55 +37,136 @@ .SH Member types Member type Definition - container_type Container - value_type Container::value_type - size_type Container::size_type - reference Container::reference - const_reference Container::const_reference + container_type Container + value_type Container::value_type + size_type Container::size_type + reference Container::reference + const_reference Container::const_reference + +.SH Member objects + + Member name Definition + Container c the underlying container + \fI(protected member object)\fP .SH Member functions constructor constructs the queue - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the queue - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container adaptor - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access front access the first element - \fI(public member function)\fP + \fI(public member function)\fP back access the last element - \fI(public member function)\fP + \fI(public member function)\fP .SH Capacity - empty checks whether the underlying container is empty - \fI(public member function)\fP + empty checks whether the container adaptor is empty + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers push inserts element at the end - \fI(public member function)\fP + \fI(public member function)\fP + push_range inserts a range of elements at the end + (C++23) \fI(public member function)\fP emplace constructs element in-place at the end - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP pop removes the first element - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP -.SH Member objects - Container c the underlying container - \fI(protected member object)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the queue - operator<= \fI(function template)\fP - operator> + operator< + operator<= lexicographically compares the values of two queues + operator> \fI(function template)\fP operator>= + operator<=> + (C++20) std::swap(std::queue) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes std::uses_allocator specializes the std::uses_allocator type trait - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(class template specialization)\fP + std::formatter formatting support for std::queue + (C++23) \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::queue q; + + q.push(0); // back pushes 0 + q.push(1); // q = 0 1 + q.push(2); // q = 0 1 2 + q.push(3); // q = 0 1 2 3 + + assert(q.front() == 0); + assert(q.back() == 3); + assert(q.size() == 4); + + q.pop(); // removes the front element, 0 + assert(q.size() == 3); + + // Print and remove all elements. Note that std::queue does not + // support begin()/end(), so a range-for-loop cannot be used. + std::cout << "q: "; + for (; !q.empty(); q.pop()) + std::cout << q.front() << ' '; + std::cout << '\\n'; + assert(q.size() == 0); + } + +.SH Output: + + q: 1 2 3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::queue did not support + LWG 307 C++98 containers using proxy supported + reference types^[1] in place of + (const) value_type& + LWG 2566 C++98 Missing the requirement for ill-formed if T is not the same + Container::value_type type as Container::value_type + + 1. ↑ Such as containers similar to std::vector with additional support of + pop_front(). The resolution of this DR + added support of std::vector for std::stack and std::priority_queue. The + changes involving std::queue + are for maintaining consistency. + +.SH See also + + deque double-ended queue + \fI(class template)\fP + list doubly-linked list + \fI(class template)\fP diff --git a/man/std::queue::back.3 b/man/std::queue::back.3 index ec53f1aa7..338a12e0f 100644 --- a/man/std::queue::back.3 +++ b/man/std::queue::back.3 @@ -1,4 +1,7 @@ -.TH std::queue::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::back \- std::queue::back + .SH Synopsis reference back(); const_reference back() const; @@ -12,15 +15,15 @@ .SH Return value - reference to the last element + Reference to the last element. .SH Complexity - Constant + Constant. .SH See also front access the first element - \fI(public member function of std::{{{1}}})\fP + \fI(public member function)\fP push inserts element at the end - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::queue::emplace.3 b/man/std::queue::emplace.3 index 1c99ab4d9..e2dde974b 100644 --- a/man/std::queue::emplace.3 +++ b/man/std::queue::emplace.3 @@ -1,13 +1,18 @@ -.TH std::queue::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::emplace \- std::queue::emplace + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + decltype(auto) emplace( Args&&... args ); - Pushes new element to the end of the queue. The element is constructed in-place, + Pushes a new element to the end of the queue. The element is constructed in-place, i.e. no copy or move operations are performed. The constructor of the element is called with exactly the same arguments as supplied to the function. - Effectively calls c.emplace_back(std::forward(args)...) + Effectively calls c.emplace_back(std::forward(args)...);. .SH Parameters @@ -15,15 +20,56 @@ .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + The value or reference, if any, returned by the above call to \fI(since C++17)\fP + Container::emplace_back. .SH Complexity Identical to the complexity of Container::emplace_back. +.SH Example + + +// Run this code + + #include + #include + + struct S + { + int id; + + S(int i, double d, std::string s) : id{i} + { + std::cout << "S::S(" << i << ", " << d << ", \\"" << s << "\\");\\n"; + } + }; + + int main() + { + std::queue queue; + const S& s = queue.emplace(42, 3.14, "C++"); // for return value C++17 required + std::cout << "id = " << s.id << '\\n'; + } + +.SH Output: + + S::S(42, 3.14, "C++") + id = 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2783 C++17 emplace returned reference, breaking returns decltype(auto) + compatibility with pre-C++17 containers + .SH See also push inserts element at the end - \fI(public member function)\fP + \fI(public member function)\fP pop removes the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::queue::empty.3 b/man/std::queue::empty.3 index 50ee23462..c4285974b 100644 --- a/man/std::queue::empty.3 +++ b/man/std::queue::empty.3 @@ -1,8 +1,12 @@ -.TH std::queue::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::empty \- std::queue::empty + .SH Synopsis - bool empty() const; (since {std}) + bool empty() const; \fI(until C++20)\fP + [[nodiscard]] bool empty() const; \fI(since C++20)\fP - Checks if the underlying container has no elements, i.e. whether c.empty(). + Checks if the underlying container has no elements. Equivalent to return c.empty();. .SH Parameters @@ -10,13 +14,41 @@ .SH Return value - true if the underlying container is empty, false otherwise + true if the underlying container is empty, false otherwise. .SH Complexity - Constant + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::queue queue; + + std::cout << "Initially, queue.empty(): " << queue.empty() << '\\n'; + + queue.push(42); + std::cout << "After adding elements, queue.empty(): " << queue.empty() << '\\n'; + } + +.SH Output: + + Initially, queue.empty(): true + After adding elements, queue.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::queue::front.3 b/man/std::queue::front.3 index e1e7f1223..23bf6e8e3 100644 --- a/man/std::queue::front.3 +++ b/man/std::queue::front.3 @@ -1,4 +1,7 @@ -.TH std::queue::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::front \- std::queue::front + .SH Synopsis reference front(); const_reference front() const; @@ -16,11 +19,11 @@ .SH Complexity - Constant + Constant. .SH See also back access the last element - \fI(public member function)\fP + \fI(public member function)\fP pop removes the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::queue::operator=.3 b/man/std::queue::operator=.3 index b3289f45f..e6652b802 100644 --- a/man/std::queue::operator=.3 +++ b/man/std::queue::operator=.3 @@ -1,16 +1,18 @@ -.TH std::queue::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::operator= \- std::queue::operator= + .SH Synopsis - queue& \fB(1)\fP - operator=( const queue& other ); - queue& \fB(2)\fP \fI(since C++11)\fP - operator=( queue&& other ); + queue& operator=( const queue& other ); \fB(1)\fP (implicitly declared) + queue& operator=( queue&& other ); \fB(2)\fP \fI(since C++11)\fP + (implicitly declared) - Replaces the contents of the container adaptor with those of other. + Replaces the contents of the container adaptor with the contents of given argument. 1) Copy assignment operator. Replaces the contents with a copy of the contents of - other. Effectively calls c = other.c;. (implicitly declared) + other. Effectively calls c = other.c;. 2) Move assignment operator. Replaces the contents with those of other using move - semantics. Effectively calls c = std::move(other.c); (implicitly declared) + semantics. Effectively calls c = std::move(other.c);. .SH Parameters @@ -22,9 +24,17 @@ .SH Complexity - Equivalent to that of operator= of the underlying container. + 1,2) Equivalent to that of operator= of the underlying container. + +.SH Example + + This section is incomplete + Reason: no example .SH See also constructor constructs the queue - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::queue::pop.3 b/man/std::queue::pop.3 index 7690f203c..0dff660bc 100644 --- a/man/std::queue::pop.3 +++ b/man/std::queue::pop.3 @@ -1,8 +1,11 @@ -.TH std::queue::pop 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::pop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::pop \- std::queue::pop + .SH Synopsis - void pop(); (since {std}) + void pop(); - Removes an element from the front of the queue. Effectively calls c.pop_front() + Removes an element from the front of the queue. Effectively calls c.pop_front(). .SH Parameters @@ -16,9 +19,13 @@ Equal to the complexity of Container::pop_front. +.SH Example + .SH See also emplace constructs element in-place at the end - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP push inserts element at the end - \fI(public member function)\fP + \fI(public member function)\fP + front access the first element + \fI(public member function)\fP diff --git a/man/std::queue::push.3 b/man/std::queue::push.3 index 8720c9058..ad03f473e 100644 --- a/man/std::queue::push.3 +++ b/man/std::queue::push.3 @@ -1,12 +1,15 @@ -.TH std::queue::push 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::push 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::push \- std::queue::push + .SH Synopsis - void push( const T& value ); (since {std}) - void push( T&& value ); \fI(since C++11)\fP + void push( const value_type& value ); + void push( value_type&& value ); \fI(since C++11)\fP Pushes the given element value to the end of the queue. - 1) Effectively calls c.push_back(value) - 2) Effectively calls c.push_back(std::move(value)) + 1) Effectively calls c.push_back(value). + 2) Effectively calls c.push_back(std::move(value)). .SH Parameters @@ -20,9 +23,11 @@ Equal to the complexity of Container::push_back. +.SH Example + .SH See also emplace constructs element in-place at the end - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP pop removes the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::queue::push_range.3 b/man/std::queue::push_range.3 new file mode 100644 index 000000000..e36b450fc --- /dev/null +++ b/man/std::queue::push_range.3 @@ -0,0 +1,81 @@ +.TH std::queue::push_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::push_range \- std::queue::push_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void push_range( R&& rg ); + + Inserts a copy of each element of rg in queue, as if by: + + * c.append_range(std::forward(rg)) if that is a valid expression (i.e. the + underlying container c has an appropriate append_range member function), or + * ranges::copy(rg, std::back_inserter(c)) otherwise. + + Each iterator in the range rg is dereferenced exactly once. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Identical to the complexity of c.append_range or ranges::copy(rg, + std::back_inserter(c)) (depending on what function is used internally). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + requires (std::ranges::input_range) + void println(auto, const Adaptor& adaptor) + { + struct Container : Adaptor // gain access to protected Adaptor::Container c; + { + auto const& container() const { return this->c; } + }; + + for (auto const& elem : static_cast(adaptor).container()) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + std::queue adaptor; + const auto rg = {1, 3, 2, 4}; + + #ifdef __cpp_lib_containers_ranges + adaptor.push_range(rg); + #else + std::ranges::for_each(rg, [&adaptor](auto e){ adaptor.push(e); }); + #endif + + println("{}", adaptor); + } + +.SH Output: + + 1 3 2 4 + +.SH See also + + push inserts element at the end + \fI(public member function)\fP diff --git a/man/std::queue::queue.3 b/man/std::queue::queue.3 index 58a048929..6ca94ef21 100644 --- a/man/std::queue::queue.3 +++ b/man/std::queue::queue.3 @@ -1,49 +1,73 @@ -.TH std::queue::queue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::queue \- std::queue::queue + .SH Synopsis - explicit queue( const Container& cont = Container() ); \fI(until C++11)\fP - explicit queue( const Container& cont ); \fI(since C++11)\fP - explicit queue( Container&& cont = Container() ); \fB(2)\fP \fI(since C++11)\fP - queue( const queue& other ); \fB(3)\fP - queue( queue&& other ); \fB(4)\fP \fI(since C++11)\fP - template< class Alloc > \fB(5)\fP \fI(since C++11)\fP + queue() : queue(Container()) {} \fB(1)\fP \fI(since C++11)\fP + explicit queue( const Container& cont = Container() \fI(until C++11)\fP + ); + explicit queue( const Container& cont ); \fI(since C++11)\fP + explicit queue( Container&& cont ); \fB(3)\fP \fI(since C++11)\fP + queue( const queue& other ); \fB(4)\fP (implicitly + declared) + \fI(since C++11)\fP + queue( queue&& other ); \fB(5)\fP (implicitly + declared) + template< class InputIt > \fB(6)\fP (since C++23) + queue( InputIt first, InputIt last ); + template< class Alloc > \fB(7)\fP \fI(since C++11)\fP explicit queue( const Alloc& alloc ); - template< class Alloc > \fB(1)\fP \fB(6)\fP \fI(since C++11)\fP - queue( const Container& cont, const Alloc& alloc ); - template< class Alloc > \fB(7)\fP \fI(since C++11)\fP + template< class Alloc > \fB(8)\fP \fI(since C++11)\fP + queue( const Container& cont, const Alloc& alloc ); \fB(2)\fP + template< class Alloc > \fB(9)\fP \fI(since C++11)\fP queue( Container&& cont, const Alloc& alloc ); - template< class Alloc > \fB(8)\fP \fI(since C++11)\fP + template< class Alloc > \fB(10)\fP \fI(since C++11)\fP queue( const queue& other, const Alloc& alloc ); - template< class Alloc > \fB(9)\fP \fI(since C++11)\fP + template< class Alloc > \fB(11)\fP \fI(since C++11)\fP queue( queue&& other, const Alloc& alloc ); + template< class InputIt, class Alloc > + queue( InputIt first, InputIt last, const Alloc& \fB(12)\fP (since C++23) + alloc ); + template< container-compatible-range R> \fB(13)\fP (since C++23) + queue( std::from_range_t, R&& rg ); + template< container-compatible-range R, class + Alloc > \fB(14)\fP (since C++23) + queue( std::from_range_t, R&& rg, const Alloc& + alloc ); Constructs new underlying container of the container adaptor from a variety of data sources. - 1) Copy-constructs the underlying container c with the contents of cont. - This is also the default constructor + 1) Default constructor. Value-initializes the container. + 2) Copy-constructs the underlying container c with the contents of cont. + This is also the default constructor. \fI(until C++11)\fP - 2) Move-constructs the underlying container c with std::move(cont). - This is also the default constructor - \fI(since C++11)\fP - 3) Copy constructor. The adaptor is copy-constructed with the contents of other.c. - (implicitly declared) - 4) Move constructor. The adaptor is constructed with std::move(other.c). (implicitly - declared) - 5-9) The following constructors are only defined if - std::uses_allocator::value == true, that is, if the - underlying container is an allocator-aware container (true for all standard library - containers). - 5) Constructs the underlying container using alloc as allocator. Effectively calls - c(alloc). - 6) Constructs the underlying container with the contents of cont and using alloc as - allocator. Effectively calls c(cont, alloc). - 7) Constructs the underlying container with the contents of cont using move - semantics while utilising alloc as allocator. Effectively calls c(std::move(cont), - alloc). - 8) Constructs the adaptor with the contents of other.c and using alloc as allocator. - Effectively calls c(athor.c, alloc). - 9) Constructs the adaptor with the contents of other using move semantics while - utilising alloc as allocator. Effectively calls c(std::move(other.c), alloc). + 3) Move-constructs the underlying container c with std::move(cont). + 4) Copy constructor. The adaptor is copy-constructed with the contents of other.c. + 5) Move constructor. The adaptor is constructed with std::move(other.c). + 6) Constructs the underlying container c with the contents of the range + [first, last). This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator. + 7-12) These constructors participate in overload resolution only if + std::uses_allocator::value is true, that is, if the underlying + container is an allocator-aware container (true for all standard library containers + that can be used with queue). + 7) Constructs the underlying container using alloc as allocator, as if by c(alloc). + 8) Constructs the underlying container with the contents of cont and using alloc as + allocator, as if by c(cont, alloc). + 9) Constructs the underlying container with the contents of cont using move + semantics while utilizing alloc as allocator, as if by c(std::move(cont), alloc). + 10) Constructs the adaptor with the contents of other.c and using alloc as + allocator, as if by c(other.c, alloc). + 11) Constructs the adaptor with the contents of other using move semantics while + utilizing alloc as allocator, as if by c(std::move(other.c), alloc). + 12) Constructs the underlying container with the contents of the range [first, last) + using alloc as allocator, as if by c(first, last, alloc). This overload participates + in overload resolution only if InputIt satisfies LegacyInputIterator. + 13) Constructs the underlying container with + ranges::to(std::forward(rg)). + 14) Constructs the underlying container with + ranges::to(std::forward(rg), alloc). .SH Parameters @@ -53,58 +77,97 @@ initialize the underlying container cont - container to be used as source to initialize the underlying container - first, last - range of elements to initialize with + first, last - range of elements [first, last) to initialize with + rg - a container compatible range, that is, an + input_range whose elements are convertible to T .SH Type requirements - Alloc must meet the requirements of Allocator. - - Container must meet the requirements of Container. The constructors (5-10) are only - defined if Container meets the requirements of AllocatorAwareContainer + Container must meet the requirements of Container. The constructors taking an + allocator parameter participate in overload resolution only if Container meets the + requirements of AllocatorAwareContainer. - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1, 3, 5, 6, 8: linear in cont or other + Same as the corresponding operation on the wrapped container. - 2, 4, 7, 9: constant +.SH Notes - This section is incomplete + Feature-test macro Value Std Feature + Iterator pair + constructors for + __cpp_lib_adaptor_iterator_pair_constructor 202106L (C++23) std::queue and + std::stack; overloads + \fB(6)\fP and \fB(12)\fP + Ranges-aware + __cpp_lib_containers_ranges 202202L (C++23) construction and + insertion; overloads + \fB(13)\fP and \fB(14)\fP .SH Example - + // Run this code - #include + #include #include #include - + #include + #include + #include + int main() { std::queue c1; c1.push(5); - std::cout << c1.size() << '\\n'; - + assert(c1.size() == 1); + std::queue c2(c1); - std::cout << c2.size() << '\\n'; - - std::deque deq {3, 1, 4, 1, 5}; - std::queue c3(deq); - std::cout << c3.size() << '\\n'; + assert(c2.size() == 1); + + std::deque deq{3, 1, 4, 1, 5}; + std::queue c3(deq); // overload (2) + assert(c3.size() == 5); + + # ifdef __cpp_lib_adaptor_iterator_pair_constructor + const auto il = {2, 7, 1, 8, 2}; + std::queue c4{il.begin(), il.end()}; // C++23, (6) + assert(c4.size() == 5); + # endif + + # if __cpp_lib_containers_ranges >= 202202L + // C++23, overload (13) + auto c5 = std::queue(std::from_range_t, std::ranges::iota(0, 42)); + assert(c5.size() == 42); + + // the same effect with pipe syntax, internally uses overload (13) + auto c6 = std::ranges::iota(0, 42) | std::ranges::to(); + assert(c6.size() == 42); + + std::allocator alloc; + + // C++23, overload (14) + auto c7 = std::queue(std::from_range_t, std::ranges::iota(0, 42), alloc); + assert(c7.size() == 42); + + // the same effect with pipe syntax, internally uses overload (14) + auto c8 = std::ranges::iota(0, 42) | std::ranges::to(alloc); + assert(c8.size() == 42); + # endif } -.SH Output: + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 1 - 1 - 5 + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit .SH See also operator= assigns values to the container adaptor - \fI(public member function)\fP - -.SH Category: - - * Todo without reason + \fI(public member function)\fP diff --git a/man/std::queue::size.3 b/man/std::queue::size.3 index e6d29fb6a..9eef87b07 100644 --- a/man/std::queue::size.3 +++ b/man/std::queue::size.3 @@ -1,8 +1,12 @@ -.TH std::queue::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::size \- std::queue::size + .SH Synopsis - size_type size() const; (since {std}) + size_type size() const; - Returns the number of elements in the underlying container, that is, c.size(). + Returns the number of elements in the container adaptor. Equivalent to return + c.size(). .SH Parameters @@ -10,13 +14,40 @@ .SH Return value - The number of elements in the container. + The number of elements in the container adaptor. .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::queue queue; + + assert(queue.size() == 0); + + const int count = 8; + + for (int i = 0; i != count; ++i) + queue.push(i); + + assert(queue.size() == count); + } + .SH See also - empty checks whether the underlying container is empty - \fI(public member function)\fP + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::queue::swap.3 b/man/std::queue::swap.3 index fe7dbe202..41614e70f 100644 --- a/man/std::queue::swap.3 +++ b/man/std::queue::swap.3 @@ -1,9 +1,15 @@ -.TH std::queue::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::swap \- std::queue::swap + .SH Synopsis - void swap( queue& other ); (since {std}) + void swap( queue& other ) noexcept(/* see below */); \fI(since C++11)\fP Exchanges the contents of the container adaptor with those of other. Effectively - calls using std::swap; swap(c, other.c); + calls + + using std::swap; + swap(c, other.c); .SH Parameters @@ -15,16 +21,89 @@ .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: \fI(since C++11)\fP (since C++11) - noexcept(noexcept(std::swap(c, other.c))) + noexcept specification: + noexcept(noexcept(swap(c, other.c))) \fI(since C++11)\fP + \fI(until C++17)\fP + In the expression above, the identifier swap is looked up in the same + manner as the one used by the C++17 std::is_nothrow_swappable trait. + noexcept specification: \fI(since C++17)\fP + noexcept(std::is_nothrow_swappable_v) .SH Complexity - Same as underlying container (linear if Container is std::array, constant - otherwise). + Same as underlying container (typically constant). + +.SH Notes + + Some implementations (e.g. libc++) provide the swap member function as an extension + to pre-C++11 modes. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + template + requires (std::ranges::input_range) + void print(std::string_view name, const Adaptor& adaptor) + { + struct Printer : Adaptor // to use protected Adaptor::Container c; + { + void print(std::string_view name) const + { + std::cout << name << " [" << std::size(this->c) << "]: "; + for (auto const& elem : this->c) + std::cout << elem << ' '; + std::cout << '\\n'; + } + }; + + static_cast(adaptor).print(name); + } + + int main() + { + std::vector v1{"1","2","3","4"}, + v2{"Ɐ","B","Ɔ","D","Ǝ"}; + + std::queue s1(std::move(v1)); + std::queue s2(std::move(v2)); + + print("s1", s1); + print("s2", s2); + + s1.swap(s2); + + print("s1", s1); + print("s2", s2); + } + +.SH Output: + + s1 [4]: 4 3 2 1 + s2 [5]: Ǝ D Ɔ B Ɐ + s1 [5]: Ǝ D Ɔ B Ɐ + s2 [4]: 4 3 2 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2456 C++11 the noexcept specification is ill-formed made to work .SH See also std::swap(std::queue) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::queue::~queue.3 b/man/std::queue::~queue.3 index f9b207dbe..80888bb0d 100644 --- a/man/std::queue::~queue.3 +++ b/man/std::queue::~queue.3 @@ -1,11 +1,14 @@ -.TH std::queue::~queue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::queue::~queue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::queue::~queue \- std::queue::~queue + .SH Synopsis - ~queue(); (since {std}) + ~queue(); - Destructs the container adaptor. The destructors of the elements are called and the - used storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. + Destructs the queue. The destructors of the elements are called and the used storage + is deallocated. Note, that if the elements are pointers, the pointed-to objects are + not destroyed. .SH Complexity - Linear in the size of the container adaptor. + Linear in the size of the queue. diff --git a/man/std::quick_exit.3 b/man/std::quick_exit.3 index 6a91d8b6d..ec08e8093 100644 --- a/man/std::quick_exit.3 +++ b/man/std::quick_exit.3 @@ -1,7 +1,10 @@ -.TH std::quick_exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::quick_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::quick_exit \- std::quick_exit + .SH Synopsis Defined in header - [[noreturn]] void quick_exit( int exit_code ); \fI(since C++11)\fP + [[noreturn]] void quick_exit( int exit_code ) noexcept; \fI(since C++11)\fP Causes normal program termination to occur without completely cleaning the resources. @@ -9,7 +12,9 @@ Functions passed to std::at_quick_exit are called in reverse order of their registration. If an exception tries to propagate out of any of the functions, std::terminate is called. After calling the registered functions, calls - std::_Exit(exit_code) + std::_Exit(exit_code). + + Functions passed to std::atexit are not called. .SH Parameters @@ -19,29 +24,59 @@ \fI(none)\fP -.SH Exceptions +.SH Example - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - -.SH Example +// Run this code + + #include + #include + + template + void quick_exit_handler() + { + std::cout << "quick_exit handler #" << N << std::endl; // flush is intended + } + + void at_exit_handler() + { + std::cout << "at_exit handler\\n"; + } + + int main() + { + if (std::at_quick_exit(quick_exit_handler<1>) || + std::at_quick_exit(quick_exit_handler<2>)) + { + std::cerr << "Registration failed\\n"; + return EXIT_FAILURE; + } - This section is incomplete - Reason: no example + std::atexit(at_exit_handler); // the handler will not be called + + struct R { ~R() { std::cout << "destructor\\n"; } } resource; + + /*...*/ + + std::quick_exit(EXIT_SUCCESS); + + std::cout << "This statement is unreachable...\\n"; + } + +.SH Output: + + quick_exit handler #2 + quick_exit handler #1 .SH See also abort causes abnormal program termination (without cleaning up) - \fI(function)\fP + \fI(function)\fP + exit causes normal program termination with cleaning up + \fI(function)\fP atexit registers a function to be called on std::exit() invocation - \fI(function)\fP - at_quick_exit registers a function to be called on quick_exit invocation - \fI(C++11)\fP \fI(function)\fP + \fI(function)\fP + at_quick_exit registers a function to be called on std::quick_exit invocation + \fI(C++11)\fP \fI(function)\fP C documentation for quick_exit - -.SH Category: - - * Todo no example diff --git a/man/std::quoted.3 b/man/std::quoted.3 index f1c87dc92..304737c4a 100644 --- a/man/std::quoted.3 +++ b/man/std::quoted.3 @@ -1,48 +1,68 @@ -.TH std::quoted 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::quoted 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::quoted \- std::quoted + .SH Synopsis Defined in header template< class CharT > - /*unspecified*/ quoted(const CharT* s, \fB(1)\fP \fI(since C++14)\fP + /*unspecified*/ quoted( const CharT* s, \fB(1)\fP \fI(since C++14)\fP - CharT delim=CharT(’"’), CharT - escape=CharT(’\\\\’)); + CharT delim = CharT('"'), CharT escape = + CharT('\\\\') ); template< class CharT, class Traits, class Allocator > - /*unspecified*/ quoted(const std::basic_string& s, \fB(2)\fP \fI(since C++14)\fP - CharT delim=CharT(’"’), CharT - escape=CharT(’\\\\’)); + CharT delim = CharT('"'), CharT escape = + CharT('\\\\') ); + template< class CharT, class Traits> + + /*unspecified*/ quoted( std::basic_string_view s, \fB(3)\fP \fI(since C++17)\fP + + CharT delim = CharT('"'), CharT escape = + CharT('\\\\') ); template< class CharT, class Traits, class Allocator > - /*unspecified*/ quoted(std::basic_string& s, \fB(3)\fP \fI(since C++14)\fP + /*unspecified*/ quoted( std::basic_string& s, \fB(4)\fP \fI(since C++14)\fP - CharT delim=CharT(’"’), CharT - escape=CharT(’\\\\’)); + CharT delim=CharT('"'), CharT + escape=CharT('\\\\') ); Allows insertion and extraction of quoted strings, such as the ones found in CSV or .SH XML. - 1,2) When used in an expression out << quoted(s, delim, escape), inserts into the - output stream out the following characters (using appropriate operator<< overloads): - a) The character delim - b) Every character from s, except if the next character to output equals delim or - equals escape (as determined by operator==), then first outputs an extra copy of - escape - c) In the end, outputs delim once more - 3) When used in an expression in >> quoted(s, delim, escape), extracts characters - from the input stream in, using std::basic_istream::operator>>, according to the - following rules: - a) If the first character extracted does not equal delim (as determined by - operator==), then simply performs in >> s. + 1-3) When used in an expression out << quoted(s, delim, escape), where out is an + output stream with char_type equal to CharT and, for overloads (2,3), traits_type + equal to Traits, behaves as a FormattedOutputFunction, which inserts into out a + sequence of characters seq constructed as follows: + a) First, the character delim is added to the sequence. + b) Then every character from s, except if the next character to output equals delim + or equals escape (as determined by the stream's traits_type::eq), then first appends + an extra copy of escape. + c) In the end, delim is appended to seq once more. + + Then, if seq.size() < out.width(), adds out.width()-seq.size() copies of the fill + character out.fill() either at the end of the sequence (if ios_base::left is set in + out.flags()) or at the beginning of the sequence (in all other cases). + + Finally, outputs each character from the resulting sequence as if by calling + out.rdbuf()->sputn(seq, n), where n=std::max(out.width(), seq.size()) and + out.width\fB(0)\fP to cancel the effects of std::setw, if any. + 4) When used in an expression in >> quoted(s, delim, escape), where in is an input + stream with char_type equal to CharT and traits_type equal to Traits, extracts + characters from in, using std::basic_istream::operator>>, according to the following + rules: + a) If the first character extracted does not equal delim (as determined by the + stream's traits_type::eq), then simply performs in >> s. b) Otherwise (if the first character is the delimiter): - 1) Turns off the skipws flag on the input stream - 2) Empties the destination string by calling s.clear() + 1) Turns off the skipws flag on the input stream. + 2) Empties the destination string by calling s.clear(). 3) Extracts characters from in and appends them to s, except that whenever an escape character is extracted, it is ignored and the next character is appended to s. - Extraction stops when !in==true or when an unescaped delim character is found. + Extraction stops when !in == true or when an unescaped delim character is found. 4) Discards the final (unescaped) delim character. 5) Restores the skipws flag on the input stream to its original value. @@ -60,33 +80,70 @@ Throws std::ios_base::failure if operator>> or operator<< throws. +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_quoted_string_io 201304L \fI(C++14)\fP std::quoted + .SH Example - + // Run this code - #include #include + #include #include - - int main() + + void default_delimiter() { + const std::string in = "std::quoted() quotes this string and embedded \\"quotes\\" too"; std::stringstream ss; - std::string in = "String with spaces, and embedded \\"quotes\\" too"; - std::string out; - ss << std::quoted(in); - std::cout << "in: '" << in << "'\\n" - << "stored as '" << ss.str() << "'\\n"; - + std::string out; ss >> std::quoted(out); - std::cout << "out: '" << out << "'\\n"; + + std::cout << "Default delimiter case:\\n" + "read in [" << in << "]\\n" + "stored as [" << ss.str() << "]\\n" + "written out [" << out << "]\\n\\n"; + } + + void custom_delimiter() + { + const char delim{'$'}; + const char escape{'%'}; + + const std::string in = "std::quoted() quotes this string and embedded $quotes$ $too"; + std::stringstream ss; + ss << std::quoted(in, delim, escape); + std::string out; + ss >> std::quoted(out, delim, escape); + + std::cout << "Custom delimiter case:\\n" + "read in [" << in << "]\\n" + "stored as [" << ss.str() << "]\\n" + "written out [" << out << "]\\n\\n"; + } + + int main() + { + default_delimiter(); + custom_delimiter(); } .SH Output: - in: 'String with spaces, and embedded "quotes" too' - stored as '"String with spaces, and embedded \\"quotes\\" too"' - out: 'String with spaces, and embedded "quotes" too' + Default delimiter case: + read in [std::quoted() quotes this string and embedded "quotes" too] + stored as ["std::quoted() quotes this string and embedded \\"quotes\\" too"] + written out [std::quoted() quotes this string and embedded "quotes" too] + + Custom delimiter case: + read in [std::quoted() quotes this string and embedded $quotes$ $too] + stored as [$std::quoted() quotes this string and embedded %$quotes%$ %$too$] + written out [std::quoted() quotes this string and embedded $quotes$ $too] .SH See also + + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP diff --git a/man/std::raise.3 b/man/std::raise.3 index b649c4756..e65e301a3 100644 --- a/man/std::raise.3 +++ b/man/std::raise.3 @@ -1,4 +1,7 @@ -.TH std::raise 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::raise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raise \- std::raise + .SH Synopsis Defined in header int raise( int sig ); @@ -18,7 +21,7 @@ SIGABRT sig - SIGFPE SIGILL defines signal types - SIGINT (macro constant) + SIGINT (macro constant) SIGSEGV SIGTERM @@ -28,22 +31,22 @@ .SH Example - + // Run this code #include #include - + void signal_handler(int signal) { std::cout << "Received signal " << signal << '\\n'; } - + int main() { // Install a signal handler std::signal(SIGTERM, signal_handler); - + std::cout << "Sending signal " << SIGTERM << '\\n'; std::raise(SIGTERM); } @@ -56,6 +59,6 @@ .SH See also signal sets a signal handler for particular signal - \fI(function)\fP + \fI(function)\fP C documentation for raise diff --git a/man/std::rand.3 b/man/std::rand.3 index 659d573fb..83d27c4c7 100644 --- a/man/std::rand.3 +++ b/man/std::rand.3 @@ -1,17 +1,22 @@ -.TH std::rand 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rand 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rand \- std::rand + .SH Synopsis Defined in header int rand(); - Returns a pseudo-random integral value between 0 and RAND_MAX (0 and RAND_MAX - included). + Returns a pseudo-random integral value from the range [0, RAND_MAX]. std::srand() seeds the pseudo-random number generator used by rand(). If rand() is - used before any calls to srand(), rand() behaves as if it was seeded with srand\fB(1)\fP. + used before any calls to std::srand(), rand() behaves as if it was seeded with + std::srand\fB(1)\fP. + + Each time rand() is seeded with std::srand(), it must produce the same sequence of + values on successive calls. - Each time rand() is seeded with srand(), it must produce the same sequence of values - on successive calls. Other functions in the standard library may call rand, it is - implementation-defined which functions do so. + Other functions in the standard library may call rand. It is implementation-defined + which functions do so. It is implementation-defined whether rand() is thread-safe. @@ -30,35 +35,58 @@ randomness, distribution and period of the sequence produced (in one well-known example, the low-order bit simply alternated between 1 and 0 between calls). - rand() is not recommended for serious random-number generation needs, like - cryptography. + rand() is not recommended for serious random-number generation needs. + It is recommended to use C++11's random number generation facilities to replace + rand(). + \fI(since C++11)\fP .SH Example - + // Run this code #include - #include #include - + #include + int main() { - std::srand(std::time(0)); // use current time as seed for random generator - int random_variable = std::rand(); - std::cout << "Random value on [0 " << RAND_MAX << "]: " - << random_variable << '\\n'; + std::srand(std::time(nullptr)); // use current time as seed for random generator + int random_value = std::rand(); + std::cout << "Random value on [0, " << RAND_MAX << "]: " << random_value << '\\n'; + + for (const int times = 8; const int sides : {2, 4, 6, 8}) + { + std::cout << "Roll " << sides << "-sided dice " << times << " times: "; + for (int n = 0; n != times; ++n) + { + int x = sides + 1; + while (x > sides) + x = 1 + std::rand() / ((RAND_MAX + 1u) / sides); + // Note: 1 + rand() % sides is biased + std::cout << x << ' '; + } + std::cout << '\\n'; + } } .SH Possible output: - Random value on [0 2147483647]: 1373858591 + Random value on [0, 2147483647]: 948298199 + Roll 2-sided dice 8 times: 2 2 1 2 1 1 2 2 + Roll 4-sided dice 8 times: 1 3 4 2 1 3 3 1 + Roll 6-sided dice 8 times: 3 2 1 6 6 4 4 2 + Roll 8-sided dice 8 times: 4 5 6 6 3 6 1 2 .SH See also uniform_int_distribution produces integer values evenly distributed across a range - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP srand seeds pseudo-random number generator - \fI(function)\fP + \fI(function)\fP + RAND_MAX maximum possible value generated by std::rand + (macro constant) + randint generates a random integer in the specified range + \fI(function template)\fP C documentation for rand diff --git a/man/std::random_access_iterator.3 b/man/std::random_access_iterator.3 new file mode 100644 index 000000000..49a02daf9 --- /dev/null +++ b/man/std::random_access_iterator.3 @@ -0,0 +1,76 @@ +.TH std::random_access_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_access_iterator \- std::random_access_iterator + +.SH Synopsis + Defined in header + template< class I > + + concept random_access_iterator = + std::bidirectional_iterator && + std::derived_from, + std::random_access_iterator_tag> && + std::totally_ordered && + std::sized_sentinel_for && + requires(I i, const I j, const std::iter_difference_t n) { \fI(since C++20)\fP + { i += n } -> std::same_as; + { j + n } -> std::same_as; + { n + j } -> std::same_as; + { i -= n } -> std::same_as; + { j - n } -> std::same_as; + { j[n] } -> std::same_as>; + + }; + + The concept random_access_iterator refines bidirectional_iterator by adding support + for constant time advancement with the +=, +, -=, and - operators, constant time + computation of distance with -, and array notation with subscripting []. + +.SH Notes + + Unlike the LegacyRandomAccessIterator requirements, the random_access_iterator + concept does not require dereference to return an lvalue. + +.SH Example + + Demonstrates a possible implementation of std::distance via C++20 concepts. + + +// Run this code + + #include + + namespace cxx20 + { + template + constexpr std::iter_difference_t distance(Iter first, Iter last) + { + if constexpr(std::random_access_iterator) + return last - first; + else + { + std::iter_difference_t result{}; + for (; first != last; ++first) + ++result; + return result; + } + } + } + + int main() + { + static constexpr auto il = {3, 1, 4}; + + static_assert(std::random_access_iterator && + cxx20::distance(il.begin(), il.end()) == 3 && + cxx20::distance(il.end(), il.begin()) == -3); + } + +.SH See also + + bidirectional_iterator specifies that a forward_iterator is a bidirectional + (C++20) iterator, supporting movement backwards + (concept) + contiguous_iterator specifies that a random_access_iterator is a contiguous + (C++20) iterator, referring to elements that are contiguous in memory + (concept) diff --git a/man/std::random_device.3 b/man/std::random_device.3 index 64587b99b..9001fd113 100644 --- a/man/std::random_device.3 +++ b/man/std::random_device.3 @@ -1,4 +1,7 @@ -.TH std::random_device 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_device 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_device \- std::random_device + .SH Synopsis Defined in header class random_device; \fI(since C++11)\fP @@ -6,59 +9,66 @@ std::random_device is a uniformly-distributed integer random number generator that produces non-deterministic random numbers. - Note that std::random_device may be implemented in terms of a pseudo-random number - engine if a non-deterministic source (e.g. a hardware device) is not available to - the implementation. + std::random_device may be implemented in terms of an implementation-defined + pseudo-random number engine if a non-deterministic source (e.g. a hardware device) + is not available to the implementation. In this case each std::random_device object + may generate the same number sequence. .SH Member types - Member type Definition - result_type unsigned int + Member type Definition + result_type \fI(C++11)\fP unsigned int .SH Member functions .SH Construction - constructor constructs the engine - \fI(public member function)\fP - operator= the assignment operator is deleted - (deleted) \fI(public member function)\fP + constructor constructs the engine + \fI(C++11)\fP \fI(public member function)\fP + operator= the assignment operator is deleted + (deleted) \fI(C++11)\fP \fI(public member function)\fP .SH Generation - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - obtains the entropy estimate for the non-deterministic random number - entropy generator - \fI(public member function)\fP - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + entropy obtains the entropy estimate for the non-deterministic random + \fI(C++11)\fP number generator + \fI(public member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + +.SH Notes + + A notable implementation where std::random_device is deterministic in old versions + of MinGW-w64 (bug 338, fixed since GCC 9.2). The latest MinGW-w64 versions can be + downloaded from GCC with the MCF thread model. .SH Example - + // Run this code #include - #include #include #include - + #include + int main() { std::random_device rd; std::map hist; std::uniform_int_distribution dist(0, 9); - for (int n = 0; n < 20000; ++n) { + + for (int n = 0; n != 20000; ++n) ++hist[dist(rd)]; // note: demo only: the performance of many // implementations of random_device degrades sharply // once the entropy pool is exhausted. For practical use // random_device is generally only used to seed // a PRNG such as mt19937 - } - for (auto p : hist) { - std::cout << p.first << " : " << std::string(p.second/100, '*') << '\\n'; - } + + for (auto [x, y] : hist) + std::cout << x << " : " << std::string(y / 100, '*') << '\\n'; } .SH Possible output: diff --git a/man/std::random_device::entropy.3 b/man/std::random_device::entropy.3 index 007bd871f..c02ad4fb2 100644 --- a/man/std::random_device::entropy.3 +++ b/man/std::random_device::entropy.3 @@ -1,47 +1,50 @@ -.TH std::random_device::entropy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_device::entropy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_device::entropy \- std::random_device::entropy + .SH Synopsis - double entropy() const; \fI(since C++11)\fP + double entropy() const noexcept; \fI(since C++11)\fP Obtains an estimate of the random number device entropy, which is a floating-point - value between min() and log - 2(max()+1). If the device has n states whose individual probabilities are P + value between 0 and log + 2(max()+1) (which is equal to std::numeric_limits::digits). If the + device has n states whose individual probabilities are P 0,...,P - n-1, the device probability S is defined as + n-1, the device entropy S is defined as - S = -Σn-1 - i=0P + S = −∑n-1 + i=0 P ilog(P i) A deterministic random number generator (e.g. a pseudo-random engine) has entropy zero. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Return value The value of the device entropy, or zero if not applicable. .SH Notes - This function is not fully implemented in some standard libraries. For example, gcc - and clang always return zero even though the device is non-deterministic. In - comparison, Visual C++ always returns 32, and boost.random returns 10. + This function is not fully implemented in some standard libraries. For example, LLVM + libc++ prior to version 12 always returns zero even though the device is + non-deterministic. In comparison, Microsoft Visual C++ implementation always returns + 32, and boost.random returns 10. + + The entropy of the Linux kernel device /dev/urandom may be obtained using ioctl + RNDGETENTCNT — that is what std::random_device::entropy() in GNU libstdc++ uses as + of version 8.1. .SH Example Example output on one of the implementations - + // Run this code #include #include - + int main() { std::random_device rd; diff --git a/man/std::random_device::max.3 b/man/std::random_device::max.3 index 437f56cb5..b2b4e263f 100644 --- a/man/std::random_device::max.3 +++ b/man/std::random_device::max.3 @@ -1,8 +1,12 @@ -.TH std::random_device::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_device::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_device::max \- std::random_device::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP - Returns the maximum value potentially generated by the random-number engine. + Returns the maximum value potentially generated by the random-number engine. This + value is equal to std::numeric_limits::max(). .SH Parameters @@ -14,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::random_device::min.3 b/man/std::random_device::min.3 index 972617354..00805e99b 100644 --- a/man/std::random_device::min.3 +++ b/man/std::random_device::min.3 @@ -1,8 +1,12 @@ -.TH std::random_device::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_device::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_device::min \- std::random_device::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP - Returns the minimum value potentially generated by the random-number engine. + Returns the minimum value potentially generated by the random-number engine. This + value is equal to 0u. .SH Parameters @@ -10,13 +14,13 @@ .SH Return value - The maximum potentially generated value. + The minimum potentially generated value. .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::random_device::operator().3 b/man/std::random_device::operator().3 index 38e1e4f69..7c6400777 100644 --- a/man/std::random_device::operator().3 +++ b/man/std::random_device::operator().3 @@ -1,4 +1,7 @@ -.TH std::random_device::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_device::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_device::operator() \- std::random_device::operator() + .SH Synopsis result_type operator()(); \fI(since C++11)\fP @@ -19,7 +22,7 @@ .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::random_device::random_device.3 b/man/std::random_device::random_device.3 index 1483480e7..3282f0b66 100644 --- a/man/std::random_device::random_device.3 +++ b/man/std::random_device::random_device.3 @@ -1,51 +1,86 @@ -.TH std::random_device::random_device 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_device::random_device 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_device::random_device \- std::random_device::random_device + .SH Synopsis - explicit random_device(const std::string& token = \fB(1)\fP \fI(since C++11)\fP - /*implementation-defined*/ ); - random_device(const random_device& ) = delete; \fB(2)\fP \fI(since C++11)\fP + random_device() : random_device( /*implementation-defined*/ ) {} \fB(1)\fP \fI(since C++11)\fP + explicit random_device( const std::string& token ); \fB(2)\fP \fI(since C++11)\fP + random_device( const random_device& ) = delete; \fB(3)\fP \fI(since C++11)\fP - 1) Constructs a new std::random_device object, making use of the argument token, if - provided, in implementation-defined manner. - 2) The copy constructor is deleted: std::random_device is not copyable. + 1) Default constructs a new std::random_device object with an implementation-defined + token. + 2) Constructs a new std::random_device object, making use of the argument token in + an implementation-defined manner. + 3) The copy constructor is deleted: std::random_device is not copyable nor movable. .SH Exceptions - Throws an implementation-defined exceptions derived from std::exception on failure. + Throws an implementation-defined exception derived from std::exception on failure. .SH Notes - The implementations in libc++ and libstdc++ expect token to be the name of a - character device that produces random numbers when read from, with the default value - "/dev/urandom", although where the CPU command RDRND is available, libstdc++ uses - that as the default. + The implementation in libstdc++ expects token to name the source of random bytes. + Possible token values include "default", "hw", "rand_s", "rdseed", "rdrand", + "rdrnd", "/dev/urandom", "/dev/random", "mt19937", and integer string specifying the + seed of the mt19937 engine. (Token values other than "default" are only valid for + certain targets.) + + The implementation in libc++, when configured to use character device as the source, + expects token to be the name of a character device that produces random numbers when + read from; otherwise it expects token to be "/dev/urandom". + + Both libstdc++ and libc++ throw an exception if provided an unsupported token. + Microsoft's stdlib ignores the token entirely. .SH Example - Demonstrates the two commonly available types of std::random_device on Linux + Demonstrates commonly available types of std::random_device on Linux. + - // Run this code #include #include - - int main() + + void demo(std::random_device&& rd) { - - std::uniform_int_distribution d(0, 10); - - std::random_device rd1; // uses RDRND or /dev/urandom - for(int n = 0; n < 10; ++n) - std::cout << d(rd1) << ' '; - std::cout << '\\n'; - - std::random_device rd2("/dev/random"); // much slower on Linux - for(int n = 0; n < 10; ++n) - std::cout << d(rd2) << ' '; + static std::uniform_int_distribution d(0, 9); + for (int n = 0; n != 10; ++n) + std::cout << d(rd) << ' '; std::cout << '\\n'; } + int main() + { + // Note: How the supplied token is handled is implementation-defined! + + // Default token for random_device is usually /dev/urandom on Linux + demo(std::random_device {}); + + // Request /dev/random, blocks when entropy is empty + // Works on libstdc++, ignored in msvc++, might throw on libc++ (as of Nov 2022) + demo(std::random_device {"/dev/random"}); + + // Request non-blocking /dev/urandom, ensures that RDRAND is not used + // Works on libstdc++ and libc++, ignored in msvc++ (as of Nov 2022) + demo(std::random_device {"/dev/urandom"}); + + // Request "hw", will use hardware-based random generation like rdrand + // Works on libstdc++, ignored in msvc++, throws on libc++ (as of Nov 2022) + demo(std::random_device {"hw"}); + } + .SH Possible output: - 7 10 7 0 4 4 6 9 4 7 - 2 4 10 6 3 2 0 6 3 7 + 9 5 2 7 5 9 4 1 0 7 + 4 7 6 5 1 5 5 1 8 6 + 3 3 6 1 4 1 4 1 0 2 + 4 6 3 9 1 9 4 0 9 3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::random_shuffle,std::shuffle.3 b/man/std::random_shuffle,std::shuffle.3 index 7dfe519e5..fa8591a83 100644 --- a/man/std::random_shuffle,std::shuffle.3 +++ b/man/std::random_shuffle,std::shuffle.3 @@ -1,118 +1,179 @@ -.TH std::random_shuffle,std::shuffle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::random_shuffle,std::shuffle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::random_shuffle,std::shuffle \- std::random_shuffle,std::shuffle + .SH Synopsis Defined in header - template< class RandomIt > - void random_shuffle( RandomIt first, \fB(1)\fP (deprecated in C++14) + template< class RandomIt > (deprecated in C++14) + void random_shuffle( RandomIt first, \fB(1)\fP (removed in C++17) RandomIt last ); template< class RandomIt, class RandomFunc > \fI(until C++11)\fP void random_shuffle( RandomIt first, RandomIt last, RandomFunc& r ); - template< class RandomIt, class - RandomFunc > \fB(2)\fP \fI(since C++11)\fP - void random_shuffle( RandomIt first, (deprecated in C++14) + template< class RandomIt, class \fI(since C++11)\fP + RandomFunc > \fB(2)\fP (deprecated in C++14) + void random_shuffle( RandomIt first, (removed in C++17) RandomIt last, RandomFunc&& r ); - template< class RandomIt, class URNG + template< class RandomIt, class URBG > \fB(3)\fP \fI(since C++11)\fP void shuffle( RandomIt first, - RandomIt last, URNG&& g ); + RandomIt last, URBG&& g ); Reorders the elements in the given range [first, last) such that each possible permutation of those elements has equal probability of appearance. - 1) The random number generator is implementation-defined, but the function std::rand - is often used. - 2) The random number generator is the function object r. - 3) The random number generator is the function object g. + 1) The source of randomness is implementation-defined, but the function std::rand is + often used. + 2) The source of randomness is the function object r. + If any of the following conditions is satisfied, the behavior is undefined: + * The return type of r is not convertible to + std::iterator_traits::difference_type. + * Given a positive value n of type + std::iterator_traits::difference_type, the result of r(n) is not a + randomly chosen value in the interval [0, n). + 3) The source of randomness is the object g. + Given the type T as std::remove_reference_t, if any of the following + conditions is satisfied, the behavior is undefined: + * T is not a UniformRandomBitGenerator. + + * T::result_type is not convertible to \fI(until C++20)\fP + std::iterator_traits::difference_type. + + If + the type of *first is not Swappable + \fI(until C++11)\fP + RandomIt is not ValueSwappable + \fI(since C++11)\fP, the behavior is undefined. .SH Parameters - first, last - the range of elements to shuffle randomly - function object returning a randomly chosen value of type convertible - r - to iterator_traits::difference_type in the interval [0,n) if - invoked as r(n) - function object returning a randomly chosen value of type - g - URNG::result_type in the interval [g.min(), g.max()] if invoked as g() - (e.g. any of the uniform random number generators from ) + first, last - the range of elements to shuffle randomly + r - function object returning a randomly chosen value + g - generator object returning a randomly chosen value .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. - - - URNG must meet the requirements of UniformRandomNumberGenerator. - -.SH Return value - - \fI(none)\fP + RandomIt must meet the requirements of LegacyRandomAccessIterator. .SH Complexity - Linear in the distance between first and last + Exactly std::distance(first, last) - 1 swaps. .SH Possible implementation -.SH First version + See also the implementations in libstdc++ and libc++. + + random_shuffle \fB(1)\fP + template + void random_shuffle(RandomIt first, RandomIt last) + { + typedef typename std::iterator_traits::difference_type diff_t; + + for (diff_t i = last - first - 1; i > 0; --i) + { + using std::swap; + swap(first[i], first[std::rand() % (i + 1)]); + // rand() % (i + 1) is not actually correct, because the generated number is + // not uniformly distributed for most values of i. The correct code would be + // a variation of the C++11 std::uniform_int_distribution implementation. + } + } + random_shuffle \fB(2)\fP template void random_shuffle(RandomIt first, RandomIt last, RandomFunc&& r) { - typename std::iterator_traits::difference_type i, n; - n = last - first; - for (i = n-1; i > 0; --i) { + typedef typename std::iterator_traits::difference_type diff_t; + + for (diff_t i = last - first - 1; i > 0; --i) + { using std::swap; - swap(first[i], first[r(i+1)]); + swap(first[i], first[r(i + 1)]); } } -.SH Second version - template - void shuffle(RandomIt first, RandomIt last, - UniformRandomNumberGenerator&& g) + shuffle \fB(3)\fP + template + void shuffle(RandomIt first, RandomIt last, URBG&& g) { typedef typename std::iterator_traits::difference_type diff_t; - typedef typename std::make_unsigned::type udiff_t; - typedef typename std::uniform_int_distribution distr_t; + typedef std::uniform_int_distribution distr_t; typedef typename distr_t::param_type param_t; - + distr_t D; - diff_t n = last - first; - for (diff_t i = n-1; i > 0; --i) { + for (diff_t i = last - first - 1; i > 0; --i) + { using std::swap; swap(first[i], first[D(g, param_t(0, i))]); } } +.SH Notes + + Note that the implementation is not dictated by the standard, so even if you use + exactly the same RandomFunc or URBG (Uniform Random Number Generator) you may get + different results with different standard library implementations. + + The reason for removing std::random_shuffle in C++17 is that the iterator-only + version usually depends on std::rand, which is now also discussed for deprecation. + (std::rand should be replaced with the classes of the header, as std::rand + is considered harmful.) In addition, the iterator-only std::random_shuffle version + usually depends on a global state. The std::shuffle's shuffle algorithm is the + preferred replacement, as it uses a URBG as its 3rd parameter. + .SH Example - The following code randomly shuffles the integers 1..10: + Randomly shuffles the sequence [1, 10] of integers: + - // Run this code - #include #include - #include #include - + #include + #include + #include + int main() { - std::vector v = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; - + std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + std::random_device rd; std::mt19937 g(rd()); - + std::shuffle(v.begin(), v.end(), g); - - copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); - std::cout << "\\n"; + + std::copy(v.begin(), v.end(), std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; } .SH Possible output: 8 6 10 4 2 3 7 1 9 5 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the source of randomness of + overload \fB(1)\fP was not specified, it is implementation-defined, + LWG 395 C++98 and and using std::rand is allowed + std::rand could not be the source + due to the C library requirement + LWG 552 r was not required to be the + (N2423) C++98 source required + of randomness of overload \fB(2)\fP^[1] + + 1. ↑ Overload \fB(3)\fP has the same defect, but that part of the resolution is not + applicable to C++98. + .SH See also generates the next greater lexicographic permutation of a range of next_permutation elements - \fI(function template)\fP + \fI(function template)\fP generates the next smaller lexicographic permutation of a range of prev_permutation elements - \fI(function template)\fP + \fI(function template)\fP + ranges::shuffle randomly re-orders elements in a range + (C++20) (niebloid) diff --git a/man/std::range-default-formatter,.3 b/man/std::range-default-formatter,.3 new file mode 100644 index 000000000..44b2e6b85 --- /dev/null +++ b/man/std::range-default-formatter,.3 @@ -0,0 +1,74 @@ +.TH std::range-default-formatter, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::range-default-formatter, \- std::range-default-formatter, + +.SH Synopsis + + Defined in header + template< std::range_format K, ranges::input_range R, class + CharT > + (since C++23) + requires (K == std::range_format::string || K == (exposition only*) + std::range_format::debug_string) + + struct range-default-formatter; + + The class template range-default-formatter for range types is specialized for + formatting range as a string or an escaped string if std::format_kind is either + std::range_format::string or std::range_format::debug_string. + +.SH Member objects + + Member name Definition + the underlying formatter of type + underlying_ (private) std::formatter, CharT> + (exposition-only member object*) + +.SH Member functions + + constructor constructs a range-default-formatter + (implicitly declared) \fI(public member function)\fP + parse parses the format specifier as specified by std-format-spec + \fI(public member function)\fP + format writes the formatted output as specified by std-format-spec + \fI(public member function)\fP + +std::range-default-formatter::parse +std::range-default-formatter::parse + + template< class ParseContext > + constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator; + + Equivalent to: + + auto i = underlying_.parse(ctx); + if constexpr (K == std::range_format::debug_string) + underlying_.set_debug_format(); + return i; + + Returns an iterator past the end of the std-format-spec. + +std::range-default-formatter::format +std::range-default-formatter::format + + template< class FormatContext > + auto format( /* see below */& r, FormatContext& ctx ) const -> + FormatContext::iterator; + + If ranges::input_range is true, the type of r is const R&. Otherwise, the + type is R&. + + Let s be a std::basic_string as if by constructing s with + std::basic_string(std::from_range, r) such that ranges::equal(s, r) is true. + + Equivalent to return underlying_.format(s, ctx);. + + Returns an iterator past the end of the output range. + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP + range_formatter class template that helps implementing std::formatter + (C++23) specializations for range types + \fI(class template)\fP diff --git a/man/std::range-default-formatter.3 b/man/std::range-default-formatter.3 new file mode 100644 index 000000000..21659f5fc --- /dev/null +++ b/man/std::range-default-formatter.3 @@ -0,0 +1,82 @@ +.TH std::range-default-formatter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::range-default-formatter \- std::range-default-formatter + +.SH Synopsis + Defined in header + template< ranges::input_range R, class CharT > (since C++23) + struct range-default-formatter; + + The class template range-default-formatter for range types is specialized for + formatting range as a sequence of elements if std::format_kind is + std::range_format::sequence. + +.SH Member types + + Member type Definition + maybe-const-r (private) /*fmt-maybe-const*/ + (exposition-only member type*) + +.SH Member objects + +Member name Definition + the underlying formatter of type +underlying_ std::range_formatter>, +(private) CharT> + (exposition-only member object*) + +.SH Member functions + + constructor constructs a range-default-formatter + (implicitly declared) \fI(public member function)\fP + set_separator sets a specified separator for the range formatted result + \fI(public member function)\fP + sets a specified opening and closing brackets for the range + set_brackets formatted result + \fI(public member function)\fP + parse parses the format specifier as specified by range-format-spec + \fI(public member function)\fP + writes the range formatted output as specified by + format range-format-spec + \fI(public member function)\fP + +std::range-default-formatter::set_separator + + constexpr void set_separator( std::basic_string_view sep ) noexcept; + + Equivalent to a call to underlying_.set_separator(sep). + +std::range-default-formatter::set_brackets + + constexpr void set_brackets( std::basic_string_view opening, + std::basic_string_view closing ) noexcept; + + Equivalent to a call to underlying_.set_brackets(opening, closing). + +std::range-default-formatter::parse + + template< class ParseContext > + constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator; + + Equivalent to return underlying_.parse(ctx);. + + Returns an iterator past the end of the range-format-spec. + +std::range-default-formatter::format + + template< class FormatContext > + auto format( maybe-const-r& elems, FormatContext& ctx ) const -> + FormatContext::iterator; + + Equivalent to return underlying_.format(elems, ctx);. + + Returns an iterator past the end of the output range. + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP + range_formatter class template that helps implementing std::formatter + (C++23) specializations for range types + \fI(class template)\fP diff --git a/man/std::range_error.3 b/man/std::range_error.3 index dd8b9f927..cd3484dad 100644 --- a/man/std::range_error.3 +++ b/man/std::range_error.3 @@ -1,46 +1,115 @@ -.TH std::range_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::range_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::range_error \- std::range_error + .SH Synopsis Defined in header class range_error; - Defines a type of object to be thrown as exception. It reports errors that arise - because floating point value in some computation could not be represented because it - was too large or too small in magnitude. If the value has integral type, - std::underflow_error or std::overflow_error should be used. + Defines a type of object to be thrown as exception. It can be used to report range + errors (that is, situations where a result of a computation cannot be represented by + the destination type). + + The only standard library components that throw this exception are + std::wstring_convert::from_bytes and std::wstring_convert::to_bytes. + + The mathematical functions in the standard library components do not throw this + exception (mathematical functions report range errors as specified in + math_errhandling). std-range error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP + constructor constructs a new range_error object with the given message + \fI(public member function)\fP + operator= replaces the range_error object + \fI(public member function)\fP - +std::range_error::range_error - std::range_error::range_error + range_error( const std::string& what_arg ); \fB(1)\fP + range_error( const char* what_arg ); \fB(2)\fP + range_error( const range_error& other ); \fB(3)\fP (noexcept since C++11) - explicit range_error( const std::string& what_arg ); \fB(1)\fP - explicit range_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP - - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::range_error then + std::strcmp(what(), other.what()) == 0. No exception can be thrown from the copy + constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::range_error is not permitted to throw exceptions, this message + is typically stored internally as a separately-allocated reference-counted string. + This is also why there is no constructor taking std::string&&: it would have to copy + the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::range_error::operator= + + range_error& operator=( const range_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::range_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::runtime_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const char* added + was missing + the explanatory strings of they are the same as that + LWG 471 C++98 std::range_error's of the + copies were implementation-defined original std::range_error + object diff --git a/man/std::range_format.3 b/man/std::range_format.3 new file mode 100644 index 000000000..7d26375ba --- /dev/null +++ b/man/std::range_format.3 @@ -0,0 +1,40 @@ +.TH std::range_format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::range_format \- std::range_format + +.SH Synopsis + Defined in header + enum class range_format { + + disabled, + map, + set, (since C++23) + sequence, + string, + debug_string + + }; + + Specifies how a range should be formatted. + + Constant Explanation + disabled disallows range default formatter to format range + allows to format range as map representation with modified brackets + map "{", "}" and separator ": " for underlying pair-like types in the + following format: + { key-1 : value-1, ..., key-n : value-n } + allows to format range as set representation with modified brackets "{" + set and "}" in the following format: + { key-1, ..., key-n } + allows to format range as sequence representation with default brackets + sequence "[", "]" and separator ", " in the following format: + [ element-1, ..., element-n ] + string allows to format range as string + debug_string allows to format range as escaped string + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP + format_kind selects a suited std::range_format for a range + (C++23) (variable template) diff --git a/man/std::range_formatter.3 b/man/std::range_formatter.3 new file mode 100644 index 000000000..c87446130 --- /dev/null +++ b/man/std::range_formatter.3 @@ -0,0 +1,124 @@ +.TH std::range_formatter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::range_formatter \- std::range_formatter + +.SH Synopsis + Defined in header + template< class T, class CharT = char > + + requires std::same_as, T> && (since C++23) + std::formattable + + class range_formatter; + + The std::range_formatter is a helper class template for implementing std::formatter + specializations for range types. + +.SH Member objects + + Member name Definition + underlying_ (private) the underlying formatter of type std::formatter + (exposition-only member object*) + a string representing the separator of the range + separator_ (private) formatted result. The default separator is ", ". + (exposition-only member object*) + a string representing the opening bracket of the range + opening-bracket_ (private) formatted result. The default opening bracket is "[". + (exposition-only member object*) + a string representing the closing bracket of the range + closing-bracket_ (private) formatted result. The default closing bracket is "]". + (exposition-only member object*) + +.SH Member functions + + set_separator sets a specified separator for the range formatted result + \fI(public member function)\fP + sets a specified opening and closing brackets for the range formatted + set_brackets result + \fI(public member function)\fP + underlying returns the underlying formatter + \fI(public member function)\fP + parse parses the format specifier as specified by range-format-spec + \fI(public member function)\fP + format writes the range formatted output as specified by range-format-spec + \fI(public member function)\fP + +std::range_formatter::set_separator + + constexpr void set_separator( std::basic_string_view sep ) noexcept; + + Assigns sep to separator_. + +std::range_formatter::set_brackets + + constexpr void set_brackets( std::basic_string_view opening, + std::basic_string_view closing ) noexcept; + + Assigns opening and closing to opening-bracket_ and closing-bracket_, respectively. + +std::range_formatter::underlying + + constexpr std::formatter& underlying(); \fB(1)\fP + constexpr const std::formatter& underlying() const; \fB(2)\fP + + Returns underlying_ (the underlying formatter). + +std::range_formatter::parse + + template< class ParseContext > + constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator; + + Parses the format specifiers as a range-format-spec and stores the parsed specifiers + in the current object. + + Calls underlying_.parse(ctx) to parse format-spec in range-format-spec or, if the + latter is not present, an empty format-spec. + + If range-type or the n option is present, the values of opening-bracket_, + closing-bracket_, and separator_ are modified as required. + + It calls underlying_.set_debug_format() if: + + * the range-type is neither s nor ?s, + * underlying_.set_debug_format() is a valid expression, and + * there is no range-underlying-spec. + + Returns an iterator past the end of the range-format-spec. + +std::range_formatter::format + + template< ranges::input_range R, class FormatContext > + + requires std::formattable, CharT> && + std::same_as>, T> + + auto format( R&& r, FormatContext& ctx ) const -> FormatContext::iterator; + + If the range-type was either s or ?s, it writes the formatted + std::basic_string(std::from_range, r) as a string or an escaped string, + respectively, into ctx.out(). + + Otherwise, it writes the following into ctx.out() as specified by range-format-spec, + in order: + + * opening-bracket_, + * for each formattable element e of the range r: + + * the result of writing e via underlying_, and + * separator_, unless e is the last element of r, and + * closing-bracket_. + + Returns an iterator past the end of the output range. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3892 C++23 the formatting of nested ranges was incorrect corrected + +.SH See also + + formatter defines formatting rules for a given type + (C++20) \fI(class template)\fP diff --git a/man/std::ranges::adjacent_find.3 b/man/std::ranges::adjacent_find.3 new file mode 100644 index 000000000..77d1328fa --- /dev/null +++ b/man/std::ranges::adjacent_find.3 @@ -0,0 +1,150 @@ +.TH std::ranges::adjacent_find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_find \- std::ranges::adjacent_find + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, class + Proj = std::identity, + + std::indirect_binary_predicate< + std::projected, \fB(1)\fP \fI(since C++20)\fP + std::projected> Pred = ranges::equal_to > + constexpr I + + adjacent_find( I first, S last, Pred pred = {}, Proj proj = {} + ); + template< ranges::forward_range R, class Proj = std::identity, + + std::indirect_binary_predicate< + std::projected, Proj>, + std::projected, Proj>> Pred = \fB(2)\fP \fI(since C++20)\fP + ranges::equal_to > + constexpr ranges::borrowed_iterator_t + + adjacent_find( R&& r, Pred pred = {}, Proj proj = {} ); + + Searches the range [first, last) for two consecutive equal elements. + + 1) Elements are compared using pred (after projecting with the projection proj). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of the elements to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator to the first of the first pair of identical elements, that is, the first + iterator it such that bool(std::invoke(pred, std::invoke(proj1, *it), + std::invoke(proj, *(it + 1)))) is true. + + If no such elements are found, an iterator equal to last is returned. + +.SH Complexity + + Exactly min((result - first) + 1, (last - first) - 1) applications of the predicate + and projection where result is the return value. + +.SH Possible implementation + + struct adjacent_find_fn + { + template S, class Proj = std::identity, + std::indirect_binary_predicate< + std::projected, + std::projected> Pred = ranges::equal_to> + constexpr I operator()(I first, S last, Pred pred = {}, Proj proj = {}) const + { + if (first == last) + return first; + auto next = ranges::next(first); + for (; next != last; ++next, ++first) + if (std::invoke(pred, std::invoke(proj, *first), std::invoke(proj, *next))) + return first; + return next; + } + + template, Proj>, + std::projected, Proj>> Pred = ranges::equal_to> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Pred pred = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr adjacent_find_fn adjacent_find; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + constexpr bool some_of(auto&& r, auto&& pred) // some but not all + { + return std::ranges::cend(r) != std::ranges::adjacent_find(r, + [&pred](auto const& x, auto const& y) + { + return pred(x) != pred(y); + }); + } + + // test some_of + constexpr auto a = {0, 0, 0, 0}, b = {1, 1, 1, 0}, c = {1, 1, 1, 1}; + auto is_one = [](auto x){ return x == 1; }; + static_assert(!some_of(a, is_one) && some_of(b, is_one) && !some_of(c, is_one)); + + int main() + { + const auto v = {0, 1, 2, 3, 40, 40, 41, 41, 5}; /* + ^^ ^^ */ + namespace ranges = std::ranges; + + if (auto it = ranges::adjacent_find(v.begin(), v.end()); it == v.end()) + std::cout << "No matching adjacent elements\\n"; + else + std::cout << "The first adjacent pair of equal elements is at [" + << ranges::distance(v.begin(), it) << "] == " << *it << '\\n'; + + if (auto it = ranges::adjacent_find(v, ranges::greater()); it == v.end()) + std::cout << "The entire vector is sorted in ascending order\\n"; + else + std::cout << "The last element in the non-decreasing subsequence is at [" + << ranges::distance(v.begin(), it) << "] == " << *it << '\\n'; + } + +.SH Output: + + The first adjacent pair of equal elements is at [4] == 40 + The last element in the non-decreasing subsequence is at [7] == 41 + +.SH See also + + ranges::unique removes consecutive duplicate elements in a range + (C++20) (niebloid) + finds the first two adjacent items that are equal (or satisfy a given + adjacent_find predicate) + \fI(function template)\fP diff --git a/man/std::ranges::adjacent_transform_view::adjacent_transform_view.3 b/man/std::ranges::adjacent_transform_view::adjacent_transform_view.3 new file mode 100644 index 000000000..bc30f368a --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::adjacent_transform_view.3 @@ -0,0 +1,42 @@ +.TH std::ranges::adjacent_transform_view::adjacent_transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::adjacent_transform_view \- std::ranges::adjacent_transform_view::adjacent_transform_view + +.SH Synopsis + adjacent_transform_view() = default; \fB(1)\fP (since C++23) + constexpr explicit adjacent_transform_view( V base, F fun ); \fB(2)\fP (since C++23) + + Constructs an adjacent_transform_view. + + 1) Default constructor. Default-initializes the underlying data members fun_ and + inner_. + 2) Move constructs the underlying data members: fun_ with std::move(fun) and inner_ + with std::move(base). + +.SH Parameters + + base - the underlying view + fun - the N-ary transformation function + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr static auto v = {1, 2, 3, 4, 5}; + constexpr auto mul = [](auto... x) { return (... * x); }; + constexpr auto view = std::views::adjacent_transform<3>(v, mul); + std::ranges::copy(view, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + +.SH Output: + + 6 24 60 diff --git a/man/std::ranges::adjacent_transform_view::begin.3 b/man/std::ranges::adjacent_transform_view::begin.3 new file mode 100644 index 000000000..5255a1a6c --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::begin.3 @@ -0,0 +1,51 @@ +.TH std::ranges::adjacent_transform_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::begin \- std::ranges::adjacent_transform_view::begin + +.SH Synopsis + constexpr auto begin(); \fB(1)\fP (since C++23) + constexpr auto begin() const + + requires ranges::range && \fB(2)\fP (since C++23) + std::regular_invocable, N)...>; + + Returns an iterator to the first element of the adjacent_transform_view. + + Let inner_ be the underlying ranges::adjacent_view. + + 1) Equivalent to return /*iterator*/(*this, inner_.begin());. + 2) Equivalent to return /*iterator*/(*this, inner_.begin());. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Example + + +// Run this code + + #include + + int main() + { + auto sum = [](auto... args) { return (... + args); }; + + constexpr auto view = std::views::iota(13, 1337) + | std::views::adjacent_transform<3>(sum); + + static_assert(*view.begin() == 42 and 42 == 13 + 14 + 15); + } + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) diff --git a/man/std::ranges::adjacent_transform_view::end.3 b/man/std::ranges::adjacent_transform_view::end.3 new file mode 100644 index 000000000..b2bb782b9 --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::end.3 @@ -0,0 +1,60 @@ +.TH std::ranges::adjacent_transform_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::end \- std::ranges::adjacent_transform_view::end + +.SH Synopsis + constexpr auto end(); \fB(1)\fP (since C++23) + constexpr auto end() const + + requires ranges::range && \fB(2)\fP (since C++23) + std::regular_invocable, N)...>; + + Returns an iterator or a sentinel representing the end of the + adjacent_transform_view. + + Let inner_ be the underlying ranges::adjacent_view. + + 1) Equivalent to: + + if constexpr (ranges::common_range) + return /*iterator*/(*this, inner_.end()); + else + return /*sentinel*/(inner_.end()); + + 2) Equivalent to: + + if constexpr (ranges::common_range) + return /*iterator*/(*this, inner_.end()); + else + return /*sentinel*/(inner_.end()); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the element following the last element, if the underlying view V + models common_range. Otherwise, a sentinel which compares equal to the end iterator. + +.SH Notes + + adjacent_transform_view models common_range whenever the underlying view V + does. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::iterator.3 b/man/std::ranges::adjacent_transform_view::iterator.3 new file mode 100644 index 000000000..e6898d516 --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::iterator.3 @@ -0,0 +1,101 @@ +.TH std::ranges::adjacent_transform_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::iterator \- std::ranges::adjacent_transform_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of adjacent_transform_view::begin, and of + adjacent_transform_view::end when the underlying view V is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + const ranges::adjacent_transform_view, if Const is true. + Parent (private) Otherwise, ranges::adjacent_transform_view. + (exposition-only member type*) + Base (private) const V, if Const is true. Otherwise, V. + (exposition-only member type*) + * std::input_iterator_tag, if + + std::invoke_result_t&, + /*REPEAT*/(ranges::range_reference_t, + N)...> + is not a reference. Otherwise, + * let C denote the type + std::iterator_traits>::iterator_category. + iterator_category * std::random_access_iterator_tag, if + std::derived_from is + true. Otherwise, + * std::bidirectional_iterator_tag, if + std::derived_from is + true. Otherwise, + * std::forward_iterator_tag, if + std::derived_from is true. + Otherwise, + * std::input_iterator_tag. + iterator_concept typename /*inner-iterator*/::iterator_concept;. + std::remove_cvref_t&, + /*REPEAT*/(ranges::range_reference_t, + N)...>>; + difference_type ranges::range_difference_t + + Data members + + Member object Definition + parent_ (private) A pointer of type Parent*. + (exposition-only member object*) + inner_ (private) An iterator of type inner_iterator. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterators + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.27.3 Class template adjacent_transform_view::iterator + [range.adjacent_transform.iterator] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::iterator::iterator.3 b/man/std::ranges::adjacent_transform_view::iterator::iterator.3 new file mode 100644 index 000000000..4a5399512 --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::iterator::iterator.3 @@ -0,0 +1,41 @@ +.TH std::ranges::adjacent_transform_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::iterator::iterator \- std::ranges::adjacent_transform_view::iterator::iterator + +.SH Synopsis + /*iterator*/() = default; \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + /*inner-iterator*/>; + private: + constexpr /*iterator*/( Parent& parent, \fB(3)\fP (exposition only*) + /*inner-iterator*/ inner ); + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying pointer parent_ with + nullptr, and default-initializes the underlying iterator inner_. + 2) Conversion from /*iterator*/ to /*iterator*/. Initializes the + underlying pointer parent_ with i.parent_, and move constructs the underlying + iterator inner_ with std::move(i.inner_). + 3) This iterator also has a private constructor which is used by + ranges::adjacent_transform_view::begin and ranges::adjacent_transform_view::end. + This constructor is not accessible to users. Initializes parent_ with + std::addressof(parent), and move constructs inner_ with std::move(inner). + +.SH Parameters + + i - an /*iterator*/ + parent - an owning object of type adjacent_transform_view + inner - an iterator of type adjacent_transform_view::inner_iterator + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::iterator::operator*.3 b/man/std::ranges::adjacent_transform_view::iterator::operator*.3 new file mode 100644 index 000000000..55d5b95b8 --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::iterator::operator*.3 @@ -0,0 +1,45 @@ +.TH std::ranges::adjacent_transform_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::iterator::operator* \- std::ranges::adjacent_transform_view::iterator::operator* + +.SH Synopsis + constexpr decltype(auto) operator*() const noexcept(/* see below */); (since C++23) + + Returns the current element in the adjacent_transform_view. + + Let parent_ and inner_ be the data members of the iterator. Equivalent to: + + return apply([&](const auto&... iters) -> decltype(auto) + { + return invoke(*parent_->fun_, *iters...); + }, + inner_.current_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Exceptions + + Let Is be the pack 0, 1, ..., (N - 1). + + noexcept specification: + noexcept(std::invoke(*parent_->fun_, *std::get(inner_.current_)...)) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::adjacent_transform_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..0cb4f8ade --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,48 @@ +.TH std::ranges::adjacent_transform_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::iterator::operator++,--,+=,-= \- std::ranges::adjacent_transform_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr /*iterator*/ operator++(int); \fB(2)\fP (since C++23) + constexpr /*iterator*/& operator--() \fB(3)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(5)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let inner_ be the underlying iterator and Base be the exposition-only member type. + + Equivalent to: + + 1) ++inner_; return *this; + 2) auto tmp = *this; ++*this; return tmp; + 3) --inner_; return *this; + 4) auto tmp = *this; --*this; return tmp; + 5) inner_ += n; return *this; + 6) inner_ -= n; return *this; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,3,5,6) *this + 2,4) a copy of *this that was made before the change + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::iterator::operator[].3 b/man/std::ranges::adjacent_transform_view::iterator::operator[].3 new file mode 100644 index 000000000..ec2c4bf15 --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::iterator::operator[].3 @@ -0,0 +1,38 @@ +.TH std::ranges::adjacent_transform_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::iterator::operator[] \- std::ranges::adjacent_transform_view::iterator::operator[] + +.SH Synopsis + constexpr decltype(auto) operator[]( difference_type n ) const (since C++23) + requires ranges::random_access_range; + + Returns an element at specified relative location. + + Let parent_ and inner_ be the data members of the iterator. Equivalent to: + + return apply([&](const auto&... iters) -> decltype(auto) + { + return invoke(*parent_->fun_, iters[n]...); + }, + inner_.current_); + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The element at displacement n relative to the current location. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::sentinel.3 b/man/std::ranges::adjacent_transform_view::sentinel.3 new file mode 100644 index 000000000..304e4c6cb --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::sentinel.3 @@ -0,0 +1,45 @@ +.TH std::ranges::adjacent_transform_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::sentinel \- std::ranges::adjacent_transform_view::sentinel + +.SH Synopsis + template< bool Const > (exposition only*) + class /*sentinel*/; + + The return type of adjacent_transform_view::end when the underlying view is not a + common_range. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from + (C++23) adjacent_transform_view::begin + \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++23) adjacent_transform_view::begin + \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.27.4 Class template adjacent_transform_view::sentinel + [range.adjacent_transform.sentinel] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::sentinel::sentinel.3 b/man/std::ranges::adjacent_transform_view::sentinel::sentinel.3 new file mode 100644 index 000000000..7f01c642b --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::sentinel::sentinel.3 @@ -0,0 +1,37 @@ +.TH std::ranges::adjacent_transform_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::sentinel::sentinel \- std::ranges::adjacent_transform_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + /*inner-sentinel*/>; + private: + constexpr explicit /*sentinel*/( /*inner-sentinel*/ \fB(3)\fP (exposition only*) + inner ); + + Construct a sentinel. + + 1) Default constructor. Default-initializes the underlying sentinel inner_. + 2) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying sentinel inner_ with std::move(i.inner_). + 3) This sentinel also has a private constructor which is used by + ranges::adjacent_transform_view::end. This constructor is not accessible to users. + Initializes the underlying sentinel inner_ with inner. + +.SH Parameters + + i - an /*sentinel*/ + inner - a sentinel of type adjacent_transform_view::inner_sentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_transform_view::size.3 b/man/std::ranges::adjacent_transform_view::size.3 new file mode 100644 index 000000000..f490b87df --- /dev/null +++ b/man/std::ranges::adjacent_transform_view::size.3 @@ -0,0 +1,55 @@ +.TH std::ranges::adjacent_transform_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_transform_view::size \- std::ranges::adjacent_transform_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; (since C++23) + constexpr auto size() const requires ranges::sized_range; + + Returns the number of elements. + + Let inner_ be the underlying object of type InnerView (that is the + ranges::adjacent_view). + + 1,2) Equivalent to return inner_.size();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements, may be 0 if the size of the underlying view V is less than + N. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr static auto v = {1, 2, 3, 4, 5, 6}; + + auto f = [](auto...) { return 0; }; // dummy + + constexpr int width1 {4}; + constexpr auto view1 = v | std::views::adjacent_transform(f); + static_assert(view1.size() == 3); + static_assert(view1.size() == (v.size() - width1 + 1)); + + constexpr int width2 {8}; + constexpr auto view2 = v | std::views::adjacent_transform(f); + // window is too wide, so view2 has no elements: + static_assert(view2.size() == 0); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::adjacent_view::adjacent_view.3 b/man/std::ranges::adjacent_view::adjacent_view.3 new file mode 100644 index 000000000..6ff5675d2 --- /dev/null +++ b/man/std::ranges::adjacent_view::adjacent_view.3 @@ -0,0 +1,57 @@ +.TH std::ranges::adjacent_view::adjacent_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::adjacent_view \- std::ranges::adjacent_view::adjacent_view + +.SH Synopsis + adjacent_view() requires std::default_initializable = default; \fB(1)\fP (since C++23) + constexpr explicit adjacent_view( V base ); \fB(2)\fP (since C++23) + + Constructs an adjacent_view. + + 1) Default constructor. Value-initializes the underlying view. + 2) Initializes the underlying view base_ with std::move(base). + +.SH Parameters + + base - the underlying view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + void print(std::tuple const& tuple) + { + std::apply([&](auto&& arg, auto&&... args) + { + std::cout << arg; + ((std::cout << args), ...); + }, tuple); + std::cout << '\\n'; + } + + int main() + { + const std::string v{"ABCDEF"}; + constexpr int window_size{4}; + + std::cout << "v: " << v << '\\n'; + + auto view = std::views::adjacent(v); // overload (2) + + for (auto const& tuple : view) + print(tuple); + } + +.SH Output: + + v: ABCDEF + ABCD + BCDE + CDEF diff --git a/man/std::ranges::adjacent_view::begin.3 b/man/std::ranges::adjacent_view::begin.3 new file mode 100644 index 000000000..4ec24a1fc --- /dev/null +++ b/man/std::ranges::adjacent_view::begin.3 @@ -0,0 +1,65 @@ +.TH std::ranges::adjacent_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::begin \- std::ranges::adjacent_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__SimpleView); \fB(1)\fP (since C++23) + constexpr auto begin() const requires ranges::range; \fB(2)\fP (since C++23) + + Returns an iterator to the first element of the adjacent_view. + + Let base_ be the underlying view. + + 1) Equivalent to return /*iterator*/(ranges::begin(base_), + ranges::end(base_));. + 2) Equivalent to return /*iterator*/(ranges::begin(base_), + ranges::end(base_));. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr static auto v = {'A', 'B', 'C', 'D', 'E'}; + + constexpr auto view = std::views::adjacent<3>(v); + + constexpr auto tuple = *view.begin(); + + static_assert + ( + std::is_same_v + < + decltype(tuple), + const std::tuple + > + ); + + static_assert + ( + std::get<0>(tuple) == 'A' && + std::get<1>(tuple) == 'B' && + std::get<2>(tuple) == 'C' + ); + } + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) diff --git a/man/std::ranges::adjacent_view::end.3 b/man/std::ranges::adjacent_view::end.3 new file mode 100644 index 000000000..057bf7f46 --- /dev/null +++ b/man/std::ranges::adjacent_view::end.3 @@ -0,0 +1,53 @@ +.TH std::ranges::adjacent_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::end \- std::ranges::adjacent_view::end + +.SH Synopsis + constexpr auto end() requires (!__SimpleView); \fB(1)\fP (since C++23) + constexpr auto end() const requires ranges::range; \fB(2)\fP (since C++23) + + Returns an iterator or a sentinel representing the end of the adjacent_view. + + Let base_ be the underlying view. + + 1) Equivalent to: + + if constexpr (ranges::common_range) + return /*iterator*/(__as_sentinel{}, ranges::begin(base_), ranges::end(base_)); + else + return /*sentinel*/(ranges::end(base_)); + + 2) Equivalent to: + + if constexpr (ranges::common_range) + return /*iterator*/(__as_sentinel{}, ranges::begin(base_), ranges::end(base_)); + else + return /*sentinel*/(ranges::end(base_)); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the element following the last element, if the underlying view V + models common_range. Otherwise, a sentinel which compares equal to the end iterator. + +.SH Notes + + ranges::adjacent_view models common_range whenever the underlying view V does. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_view::iterator.3 b/man/std::ranges::adjacent_view::iterator.3 new file mode 100644 index 000000000..b15683c94 --- /dev/null +++ b/man/std::ranges::adjacent_view::iterator.3 @@ -0,0 +1,84 @@ +.TH std::ranges::adjacent_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::iterator \- std::ranges::adjacent_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of adjacent_view::begin, and of adjacent_view::end when the + underlying view V is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + iterator_category std::input_iterator_tag + * std::random_access_iterator_tag, if Base models + random_access_range. Otherwise, + iterator_concept * std::bidirectional_iterator_tag, if Base models + bidirectional_range. Otherwise, + * std::forward_iterator_tag. + value_type std::tuple, N)...>; + difference_type ranges::range_difference_t + + Data members + + Member object Definition + current_ (private) std::array, N>. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterators + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++23) \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.25.3 Class template adjacent_view::iterator [range.adjacent.iterator] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_view::iterator::iterator.3 b/man/std::ranges::adjacent_view::iterator::iterator.3 new file mode 100644 index 000000000..3e28e1a84 --- /dev/null +++ b/man/std::ranges::adjacent_view::iterator::iterator.3 @@ -0,0 +1,35 @@ +.TH std::ranges::adjacent_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::iterator::iterator \- std::ranges::adjacent_view::iterator::iterator + +.SH Synopsis + /*iterator*/() = default; \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + ranges::convertible_to, + ranges::iterator_t>; + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying array of iterators current_ + to Base, as if by std::array, N>(). + 2) Conversion from /*iterator*/ to /*iterator*/. Move constructs the + underlying current_ member. + + This iterator also has two private constructors which is used by + ranges::adjacent_view::begin and ranges::adjacent_view::end. These constructors are + not accessible to users. + +.SH Parameters + + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_view::iterator::operator*.3 b/man/std::ranges::adjacent_view::iterator::operator*.3 new file mode 100644 index 000000000..3dbd09f63 --- /dev/null +++ b/man/std::ranges::adjacent_view::iterator::operator*.3 @@ -0,0 +1,51 @@ +.TH std::ranges::adjacent_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::iterator::operator* \- std::ranges::adjacent_view::iterator::operator* + +.SH Synopsis + constexpr auto operator*() const; (since C++23) + + Returns the elements into V the underlying array of iterators points to. + + Let current_ be an underlying array of iterators. + + Equivalent to: + + return __tuple_transform([](auto& i) -> decltype(auto) { return *i; }, current_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element, which is a std::tuple of references to underlying elements. + +.SH Notes + + operator-> is not provided. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr static auto v = {0, 1, 2, 3, 4, 5}; + // └──┬──┘ + // └─────────────────┐ + constexpr auto view {v | std::views::adjacent<3>}; // │ + constexpr auto iter {view.begin() + 2}; // │ + // ┌────────────────────┬────────────────┘ + // │ ┌──┴──┐ + static_assert(*iter == std::tuple{2, 3, 4}); + } + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP diff --git a/man/std::ranges::adjacent_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::adjacent_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..b8e1098b1 --- /dev/null +++ b/man/std::ranges::adjacent_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,124 @@ +.TH std::ranges::adjacent_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::iterator::operator++,--,+=,-= \- std::ranges::adjacent_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr /*iterator*/ operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/& operator--() \fB(3)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(5)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let current_ be an underlying array of iterators. + + 1) Equivalent to: + + for (auto& i : current_) + i = std::ranges::next(i); + return *this; + + The behavior is undefined if before the call the current_.back() is not + incrementable. + 2) Equivalent to: + + auto tmp = *this; + ++*this; + return tmp; + + 3) Equivalent to: + + for (auto& i : current_) + i = std::ranges::prev(i); + return *this; + + The behavior is undefined if before the call the current_.front() is not + decrementable. + 4) Equivalent to: + + auto tmp = *this; + --*this; + return tmp; + + 5) Equivalent to: + + for (auto& i : current_) + i = i + n; + return *this; + + The behavior is undefined if before the call the current_.back() + n does not have + well-defined behavior. + 6) Equivalent to: + + for (auto& i : current_) + i = i - n; + return *this; + + The behavior is undefined if before the call the current_.front() - n does not have + well-defined behavior. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,3,5,6) *this + 2,4) A copy of *this that was made before the change. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + [[nodiscard]] + bool operator==(std::pair x, std::pair y) + { + return x.first == y.first and x.second == y.second; + } + + int main() + { + { + auto v = std::vector{0, 1, 2, 3, 4, 5}; + auto i = (v | std::views::pairwise).begin(); + assert((*i == std::pair{0, 1})); + ++i; // overload (1) + assert((*i == std::pair{1, 2})); + --i; // overload (3) + assert((*i == std::pair{0, 1})); + i += 2; // overload (5) + assert((*i == std::pair{2, 3})); + i -= 2; // overload (6) + assert((*i == std::pair{0, 1})); + } + { + auto v = std::list{0, 1, 2, 3, 4, 5}; + auto i = (v | std::views::pairwise).begin(); + assert((*i == std::pair{0, 1})); + ++i; // overload (1) + assert((*i == std::pair{1, 2})); + --i; // overload (3) + assert((*i == std::pair{0, 1})); + // i += 2; // Error: v is not a random_access_range; overload (5) + // i -= 2; // Error: v is not a random_access_range; overload (6) + } + } + +.SH See also + + operator+ performs iterator arithmetic + operator- \fI(public member function)\fP + (C++23) diff --git a/man/std::ranges::adjacent_view::iterator::operator[].3 b/man/std::ranges::adjacent_view::iterator::operator[].3 new file mode 100644 index 000000000..ef3faf2de --- /dev/null +++ b/man/std::ranges::adjacent_view::iterator::operator[].3 @@ -0,0 +1,42 @@ +.TH std::ranges::adjacent_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::iterator::operator[] \- std::ranges::adjacent_view::iterator::operator[] + +.SH Synopsis + constexpr auto operator[]( difference_type n ) const (since C++23) + requires ranges::random_access_range; + + Returns an element at specified relative location. + + Let current_ be an underlying array of iterators. + + Equivalent to: + + return __tuple_transform([&](auto& i) -> decltype(auto) { return i[n]; }, current_); + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The element at displacement n relative to the current location. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr static auto v = {0, 1, 2, 3, 4, 5}; + // └──┬──┘ + // └─────────────────┐ + constexpr auto view = v | std::views::adjacent<3>; // │ + // ┌───────────────────┬──────────────┘ + // │ ┌──┴──┐ + static_assert(view[2] == std::tuple{2, 3, 4}); + } diff --git a/man/std::ranges::adjacent_view::sentinel.3 b/man/std::ranges::adjacent_view::sentinel.3 new file mode 100644 index 000000000..2c71c925c --- /dev/null +++ b/man/std::ranges::adjacent_view::sentinel.3 @@ -0,0 +1,55 @@ +.TH std::ranges::adjacent_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::sentinel \- std::ranges::adjacent_view::sentinel + +.SH Synopsis + template< bool Const > (exposition only*) + class /*sentinel*/; (since C++23) + + The return type of adjacent_view::end when the underlying view is not a + common_range. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + + Data members + + Member object Definition + end_ (private) A sentinel obtained from (possibly const-qualified) V. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from adjacent_view::begin + (C++23) \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++23) adjacent_view::begin + \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.25.4 Class template adjacent_view::sentinel [range.adjacent.sentinel] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_view::sentinel::sentinel.3 b/man/std::ranges::adjacent_view::sentinel::sentinel.3 new file mode 100644 index 000000000..940c0f32d --- /dev/null +++ b/man/std::ranges::adjacent_view::sentinel::sentinel.3 @@ -0,0 +1,34 @@ +.TH std::ranges::adjacent_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::sentinel::sentinel \- std::ranges::adjacent_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel (denoted as end_) + with ranges::sentinel_t(). + 2) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying sentinel end_ with the corresponding member of i. + + This type also has a private constructor which is used by adjacent_view::end. This + constructor is not accessible to users. + +.SH Parameters + + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::adjacent_view::size.3 b/man/std::ranges::adjacent_view::size.3 new file mode 100644 index 000000000..f0ce3e664 --- /dev/null +++ b/man/std::ranges::adjacent_view::size.3 @@ -0,0 +1,54 @@ +.TH std::ranges::adjacent_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::adjacent_view::size \- std::ranges::adjacent_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; (since C++23) + constexpr auto size() const requires ranges::sized_range; (since C++23) + + Returns the number of elements. + + Let base_ be the underlying view. Equivalent to: + + using SizeType = decltype(ranges::size(base_)); + using CommonType = ranges::common_type_t; + auto size = static_cast(ranges::size(base_)); + size -= std::min(size, N - 1); + return static_cast(size); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements, may be 0 if ranges::size(base_) is less than N. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr static auto v = {1, 2, 3, 4, 5, 6}; + + constexpr int width1 {4}; + constexpr auto view1 {std::views::adjacent(v)}; + static_assert(view1.size() == 3); + static_assert(view1.size() == (v.size() - width1 + 1)); + + constexpr int width2 {8}; + constexpr auto view2 {std::views::adjacent(v)}; + // window is too wide, so view2 has no elements: + static_assert(view2.size() == 0); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::advance.3 b/man/std::ranges::advance.3 new file mode 100644 index 000000000..220f08b30 --- /dev/null +++ b/man/std::ranges::advance.3 @@ -0,0 +1,193 @@ +.TH std::ranges::advance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::advance \- std::ranges::advance + +.SH Synopsis + Defined in header + Call signature + template< std::input_or_output_iterator I > \fB(1)\fP \fI(since C++20)\fP + constexpr void advance( I& i, std::iter_difference_t n ); + template< std::input_or_output_iterator I, std::sentinel_for S + > \fB(2)\fP \fI(since C++20)\fP + constexpr void advance( I& i, S bound ); + template< std::input_or_output_iterator I, std::sentinel_for S + > \fB(3)\fP \fI(since C++20)\fP + constexpr std::iter_difference_t advance( I& i, + std::iter_difference_t n, S bound ); + + 1) Increments given iterator i for n times. + 2) Increments given iterator i until i == bound. + 3) Increments given iterator i for n times, or until i == bound, whichever comes + first. + + If n is negative, the iterator is decremented. In this case, I must model + std::bidirectional_iterator, and S must be the same type as I if bound is provided, + otherwise the behavior is undefined. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + i - iterator to be advanced + bound - sentinel denoting the end of the range i is an iterator to + n - number of maximal increments of i + +.SH Return value + + 3) The difference between n and the actual distance i traversed. + +.SH Complexity + + Linear. + + However, if I additionally models std::random_access_iterator, or S models + std::sized_sentinel_for, or I and S model std::assignable_from, complexity + is constant. + +.SH Notes + + The behavior is undefined if the specified sequence of increments or decrements + would require that a non-incrementable iterator (such as the past-the-end iterator) + is incremented, or that a non-decrementable iterator (such as the front iterator or + the singular iterator) is decremented. + +.SH Possible implementation + + struct advance_fn + { + template + constexpr void operator()(I& i, std::iter_difference_t n) const + { + if constexpr (std::random_access_iterator) + i += n; + else + { + while (n > 0) + { + --n; + ++i; + } + + if constexpr (std::bidirectional_iterator) + { + while (n < 0) + { + ++n; + --i; + } + } + } + } + + template S> + constexpr void operator()(I& i, S bound) const + { + if constexpr (std::assignable_from) + i = std::move(bound); + else if constexpr (std::sized_sentinel_for) + (*this)(i, bound - i); + else + while (i != bound) + ++i; + } + + template S> + constexpr std::iter_difference_t + operator()(I& i, std::iter_difference_t n, S bound) const + { + if constexpr (std::sized_sentinel_for) + { + // std::abs is not constexpr until C++23 + auto abs = [](const std::iter_difference_t x) { return x < 0 ? -x : x; }; + + if (const auto dist = abs(n) - abs(bound - i); dist < 0) + { + (*this)(i, bound); + return -dist; + } + + (*this)(i, n); + return 0; + } + else + { + while (n > 0 && i != bound) + { + --n; + ++i; + } + + if constexpr (std::bidirectional_iterator) + { + while (n < 0 && i != bound) + { + ++n; + --i; + } + } + + return n; + } + } + }; + + inline constexpr auto advance = advance_fn(); + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v {3, 1, 4}; + + auto vi = v.begin(); + + std::ranges::advance(vi, 2); + std::cout << "1) value: " << *vi << '\\n' << std::boolalpha; + + std::ranges::advance(vi, v.end()); + std::cout << "2) vi == v.end(): " << (vi == v.end()) << '\\n'; + + std::ranges::advance(vi, -3); + std::cout << "3) value: " << *vi << '\\n'; + + std::cout << "4) diff: " << std::ranges::advance(vi, 2, v.end()) + << ", value: " << *vi << '\\n'; + + std::cout << "5) diff: " << std::ranges::advance(vi, 4, v.end()) + << ", vi == v.end(): " << (vi == v.end()) << '\\n'; + } + +.SH Output: + + 1) value: 4 + 2) vi == v.end(): true + 3) value: 3 + 4) diff: 0, value: 4 + 5) diff: 3, vi == v.end(): true + +.SH See also + + ranges::next increment an iterator by a given distance or to a bound + (C++20) (niebloid) + ranges::prev decrement an iterator by a given distance or to a bound + (C++20) (niebloid) + ranges::distance returns the distance between an iterator and a sentinel, or between + (C++20) the beginning and end of a range + (niebloid) + advance advances an iterator by given distance + \fI(function template)\fP diff --git a/man/std::ranges::all_of,std::ranges::any_of,std::ranges::none_of.3 b/man/std::ranges::all_of,std::ranges::any_of,std::ranges::none_of.3 new file mode 100644 index 000000000..6a86e411b --- /dev/null +++ b/man/std::ranges::all_of,std::ranges::any_of,std::ranges::none_of.3 @@ -0,0 +1,234 @@ +.TH std::ranges::all_of,std::ranges::any_of,std::ranges::none_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::all_of,std::ranges::any_of,std::ranges::none_of \- std::ranges::all_of,std::ranges::any_of,std::ranges::none_of + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(1)\fP \fI(since C++20)\fP + Pred > + constexpr bool + + all_of( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate< + std::projected,Proj>> Pred > \fB(2)\fP \fI(since C++20)\fP + constexpr bool + + all_of( R&& r, Pred pred, Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(3)\fP \fI(since C++20)\fP + Pred > + constexpr bool + + any_of( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate< + std::projected,Proj>> Pred > \fB(4)\fP \fI(since C++20)\fP + constexpr bool + + any_of( R&& r, Pred pred, Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(5)\fP \fI(since C++20)\fP + Pred > + constexpr bool + + none_of( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate< + std::projected,Proj>> Pred > \fB(6)\fP \fI(since C++20)\fP + constexpr bool + + none_of( R&& r, Pred pred, Proj proj = {} ); + + 1) Checks if unary predicate pred returns true for all elements in the range + [first, last) (after projecting with the projection proj). + 3) Checks if unary predicate pred returns true for at least one element in the range + [first, last) (after projecting with the projection proj). + 5) Checks if unary predicate pred returns true for no elements in the range + [first, last) (after projecting with the projection proj). + 2,4,6) Same as (1,3,5), but uses r as the source range, as if using ranges::begin(r) + as first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of the elements to examine + r - the range of the elements to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1,2) true if std::invoke(pred, std::invoke(proj, *i)) != false for every iterator i + in the range, false otherwise. Returns true if the range is empty. + 3,4) true if std::invoke(pred, std::invoke(proj, *i)) != false for at least one + iterator i in the range, false otherwise. Returns false if the range is empty. + 5,6) true if std::invoke(pred, std::invoke(proj, *i)) == false for every iterator i + in the range, false otherwise. Returns true if the range is empty. + + See also Notes below. + +.SH Complexity + + At most last - first applications of the predicate and the projection. + +.SH Possible implementation + + all_of (1,2) + struct all_of_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr bool operator()(I first, S last, Pred pred, Proj proj = {}) const + { + return ranges::find_if_not(first, last, std::ref(pred), std::ref(proj)) == last; + } + + template,Proj>> Pred> + constexpr bool operator()(R&& r, Pred pred, Proj proj = {}) const + { + return operator()(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr all_of_fn all_of; + any_of (3,4) + struct any_of_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr bool operator()(I first, S last, Pred pred, Proj proj = {}) const + { + return ranges::find_if(first, last, std::ref(pred), std::ref(proj)) != last; + } + + template,Proj>> Pred> + constexpr bool operator()(R&& r, Pred pred, Proj proj = {}) const + { + return operator()(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr any_of_fn any_of; + none_of (5,6) + struct none_of_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr bool operator()(I first, S last, Pred pred, Proj proj = {}) const + { + return ranges::find_if(first, last, std::ref(pred), std::ref(proj)) == last; + } + + template,Proj>> Pred> + constexpr bool operator()(R&& r, Pred pred, Proj proj = {}) const + { + return operator()(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr none_of_fn none_of; + +.SH Notes + + The return value represented in the form of the Truth table is: + + input range contains + all true, some true, none true, none true, + none false some false all false none false + (empty range) + 1,2) all_of true false false true + 3,4) any_of true true false false + 5,6) none_of false false true true + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + namespace ranges = std::ranges; + + constexpr bool some_of(auto&& r, auto&& pred) // some but not all + { + return not (ranges::all_of(r, pred) or ranges::none_of(r, pred)); + } + + constexpr auto w = {1, 2, 3}; + static_assert(!some_of(w, [](int x) { return x < 1; })); + static_assert( some_of(w, [](int x) { return x < 2; })); + static_assert(!some_of(w, [](int x) { return x < 4; })); + + int main() + { + std::vector v(10, 2); + std::partial_sum(v.cbegin(), v.cend(), v.begin()); + std::cout << "Among the numbers: "; + ranges::copy(v, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + + if (ranges::all_of(v.cbegin(), v.cend(), [](int i) { return i % 2 == 0; })) + std::cout << "All numbers are even\\n"; + + if (ranges::none_of(v, std::bind(std::modulus(), std::placeholders::_1, 2))) + std::cout << "None of them are odd\\n"; + + auto DivisibleBy = [](int d) + { + return [d](int m) { return m % d == 0; }; + }; + + if (ranges::any_of(v, DivisibleBy(7))) + std::cout << "At least one number is divisible by 7\\n"; + } + +.SH Output: + + Among the numbers: 2 4 6 8 10 12 14 16 18 20 + All numbers are even + None of them are odd + At least one number is divisible by 7 + +.SH See also + + all_of + any_of checks if a predicate is true for all, any or none of the elements in a + none_of range + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP + \fI(C++11)\fP diff --git a/man/std::ranges::basic_istream_view::iterator.3 b/man/std::ranges::basic_istream_view::iterator.3 new file mode 100644 index 000000000..97411876d --- /dev/null +++ b/man/std::ranges::basic_istream_view::iterator.3 @@ -0,0 +1,96 @@ +.TH std::ranges::basic_istream_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::basic_istream_view::iterator \- std::ranges::basic_istream_view::iterator + +.SH Synopsis + struct /*iterator*/; \fI(since C++20)\fP + (exposition only*) + + The return type of basic_istream_view::begin. + + /*iterator*/ is an input_iterator, but does not satisfy LegacyInputIterator, and + thus does not work with pre-C++20 algorithms. + +.SH Member types + + Member type Definition + iterator_concept (C++20) std::input_iterator_tag + difference_type (C++20) std::ptrdiff_t + value_type (C++20) Val + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + operator= the copy assignment operator is deleted; /*iterator*/ is move-only + (C++20) \fI(public member function)\fP + operator++ advances the iterator + (C++20) \fI(public member function)\fP + operator* returns the current element + (C++20) \fI(public member function)\fP + +std::ranges::basic_istream_view::iterator::iterator + + constexpr explicit /*iterator*/( basic_istream_view& parent ); \fB(1)\fP \fI(since C++20)\fP + /*iterator*/( const /*iterator*/& ) = delete; \fB(2)\fP \fI(since C++20)\fP + /*iterator*/( /*iterator*/&& ) = default; \fB(3)\fP \fI(since C++20)\fP + + 1) Constructs an iterator from the parent basic_istream_view. + 2) The copy constructor is deleted. The iterator is not copyable. + 3) The move constructor is defaulted. The iterator is movable. + +std::ranges::basic_istream_view::iterator::operator= + + /*iterator*/& operator=( const /*iterator*/& ) = delete; \fB(1)\fP \fI(since C++20)\fP + /*iterator*/& operator=( /*iterator*/&& ) = default; \fB(2)\fP \fI(since C++20)\fP + + 1) The copy assignment operator is deleted. The iterator is not copyable. + 2) The move assignment operator is defaulted. The iterator is movable. + +std::ranges::basic_istream_view::iterator::operator++ + + /*iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + void operator++(int); \fB(2)\fP \fI(since C++20)\fP + + Reads a value from the underlying stream and stores it into the parent + basic_istream_view. + +.SH Return value + + 1) *this + 2) \fI(none)\fP + +std::ranges::basic_istream_view::iterator::operator* + + Val& operator*() const; \fI(since C++20)\fP + + Returns a reference to the stored value. + +.SH Non-member functions + + operator== compares with a std::default_sentinel_t + (C++20) \fI(public member function)\fP + +operator==(std::ranges::basic_istream_view::iterator, std::default_sentinel) + + friend bool operator==( const /*iterator*/& x, \fI(since C++20)\fP + std::default_sentinel_t ); + + Compares an iterator with std::default_sentinel_t. + + Returns true if *this does not have a parent basic_istream_view, or if an error has + occurred on the underlying stream. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when + std::ranges::basic_istream_view::iterator is an associated class of the arguments. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + default constructor was provided as C++20 removed along with the + P2325R3 C++20 iterators requirement + must be default_initializable diff --git a/man/std::ranges::begin.3 b/man/std::ranges::begin.3 new file mode 100644 index 000000000..541264afd --- /dev/null +++ b/man/std::ranges::begin.3 @@ -0,0 +1,105 @@ +.TH std::ranges::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::begin \- std::ranges::begin + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ begin = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr std::input_or_output_iterator auto begin( + T&& t ); + + Returns an iterator to the first element of the argument. + + range-begin-end.svg + + If the argument is an lvalue or ranges::enable_borrowed_range> + is true, then a call to ranges::begin is expression-equivalent to: + + 1. t + 0 if t has an array type. + * If std::remove_all_extents_t> is incomplete, + then the call to ranges::begin is ill-formed, no diagnostic required. + 2. Otherwise, + decay-copy(t.begin()) + (until C++23) + auto(t.begin()) + (since C++23), if that expression is valid and its type models + std::input_or_output_iterator. + 3. Otherwise, + decay-copy(begin(t)) + (until C++23) + auto(begin(t)) + (since C++23), if T is a class or enumeration type, that expression is valid and + its type models std::input_or_output_iterator, where the meaning of begin is + established as if by performing argument-dependent lookup only. + + In all other cases, a call to ranges::begin is ill-formed, which can result in + substitution failure when the call appears in the immediate context of a template + instantiation. + +.SH Notes + + If the argument is an rvalue (i.e. T is an object type) and + ranges::enable_borrowed_range> is false, the call to + ranges::begin is ill-formed, which also results in substitution failure. + + The return type models std::input_or_output_iterator in all cases. + + The C++20 standard requires that if the underlying begin function call returns a + prvalue, the return value is move-constructed from the materialized temporary + object. All implementations directly return the prvalue instead. The requirement is + corrected by the post-C++20 proposal P0849R8 to match the implementations. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v{3, 1, 4}; + auto vi = std::ranges::begin(v); + auto vci = std::ranges::cbegin(v); + assert(*vi == 3 and *vi == *vci); + ++vi; + ++vci; // OK: vci is modifiable object + *vi = 42; // OK: vi points to mutable element + // *vci = 13; // Error: vci points to immutable element + + int a[]{-5, 10, 15}; + auto ai = std::ranges::begin(a); // works with C-arrays as well + assert(*ai == -5); + *ai = 42; // OK + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2602R2 C++20 there's machinery to prohibit certain removed such machinery + non-member begin found by ADL + +.SH See also + + ranges::cbegin returns an iterator to the beginning of a read-only range + (C++20) (customization point object) + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::bidirectional_range.3 b/man/std::ranges::bidirectional_range.3 new file mode 100644 index 000000000..ff3424960 --- /dev/null +++ b/man/std::ranges::bidirectional_range.3 @@ -0,0 +1,45 @@ +.TH std::ranges::bidirectional_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::bidirectional_range \- std::ranges::bidirectional_range + +.SH Synopsis + Defined in header + template< class T > + + concept bidirectional_range = \fI(since C++20)\fP + + ranges::forward_range && + std::bidirectional_iterator>; + + The bidirectional_range concept is a refinement of range for which ranges::begin + returns a model of bidirectional_iterator. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + static_assert( + std::ranges::bidirectional_range> and + not std::ranges::bidirectional_range> and + std::ranges::bidirectional_range> and + not std::ranges::bidirectional_range> + ); + } + +.SH See also + + ranges::forward_range specifies a range whose iterator type satisfies + (C++20) forward_iterator + (concept) + ranges::random_access_range specifies a range whose iterator type satisfies + (C++20) random_access_iterator + (concept) diff --git a/man/std::ranges::binary_search.3 b/man/std::ranges::binary_search.3 new file mode 100644 index 000000000..d6f6aaf2a --- /dev/null +++ b/man/std::ranges::binary_search.3 @@ -0,0 +1,204 @@ +.TH std::ranges::binary_search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::binary_search \- std::ranges::binary_search + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class T, class Proj = std::identity, + std::indirect_strict_weak_order (since + > Comp = C++20) + ranges::less > (until + constexpr bool binary_search( I first, S last, const T& C++26) + value, + + Comp comp = {}, Proj proj = {} + ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t, + std::indirect_strict_weak_order + > Comp = (since + ranges::less > C++26) + constexpr bool binary_search( I first, S last, const T& + value, + + Comp comp = {}, Proj proj = {} + ); + template< ranges::forward_range R, + \fB(1)\fP + class T, class Proj = std::identity, + std::indirect_strict_weak_order + , C++20) + Proj>> Comp = (until + ranges::less > C++26) + constexpr bool binary_search( R&& r, const T& value, + + Comp comp = {}, Proj proj = {} + ); + template< ranges::forward_range R, \fB(2)\fP + + class Proj = std::identity, + class T = + std::projected_value_t, Proj>, + std::indirect_strict_weak_order + , C++26) + Proj>> Comp = + ranges::less > + constexpr bool binary_search( R&& r, const T& value, + + Comp comp = {}, Proj proj = {} + ); + + 1) Checks if a projected element equivalent to value appears within the range + [first, last). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + For ranges::binary_search to succeed, the range [first, last) must be at least + partially ordered with respect to value, i.e. it must satisfy all of the following + requirements: + + * partitioned with respect to std::invoke(comp, std::invoke(proj, element), value) + (that is, all projected elements for which the expression is true precedes all + elements for which the expression is false). + * partitioned with respect to !std::invoke(comp, value, std::invoke(proj, + element)). + * for all elements, if std::invoke(comp, std::invoke(proj, element), value) is + true then !std::invoke(comp, value, std::invoke(proj, element)) is also true. + + A fully-sorted range meets these criteria. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + value - value to compare the elements to + comp - comparison function to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + true if an element equal to value is found, false otherwise. + +.SH Complexity + + The number of comparisons and projections performed is logarithmic in the distance + between first and last (at most log + 2(last - first) + O(1) comparisons and projections). However, for iterator-sentinel + pair that does not model std::random_access_iterator, number of iterator increments + is linear. + +.SH Notes + + std::ranges::binary_search doesn't return an iterator to the found element when an + element whose projection equals value is found. If an iterator is desired, + std::ranges::lower_bound should be used instead. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Possible implementation + +struct binary_search_fn +{ + template S, + class Proj = std::identity, class T = std::projected_value_t, + std::indirect_strict_weak_order + > Comp = ranges::less> + constexpr bool operator()(I first, S last, const T& value, + Comp comp = {}, Proj proj = {}) const + { + auto x = ranges::lower_bound(first, last, value, comp, proj); + return (!(x == last) && !(std::invoke(comp, value, std::invoke(proj, *x)))); + } + + template, Proj>, + std::indirect_strict_weak_order + , + Proj>> Comp = ranges::less> + constexpr bool operator()(R&& r, const T& value, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, + std::move(comp), std::move(proj)); + } +}; + +inline constexpr binary_search_fn binary_search; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + constexpr static auto haystack = {1, 3, 4, 5, 9}; + static_assert(std::ranges::is_sorted(haystack)); + + for (const int needle : std::views::iota(1) + | std::views::take(3)) + { + std::cout << "Searching for " << needle << ": "; + std::ranges::binary_search(haystack, needle) + ? std::cout << "found " << needle << '\\n' + : std::cout << "no dice!\\n"; + } + + using CD = std::complex; + std::vector nums{{1, 1}, {2, 3}, {4, 2}, {4, 3}}; + auto cmpz = [](CD x, CD y){ return abs(x) < abs(y); }; + #ifdef __cpp_lib_algorithm_default_value_type + assert(std::ranges::binary_search(nums, {4, 2}, cmpz)); + #else + assert(std::ranges::binary_search(nums, CD{4, 2}, cmpz)); + #endif + } + +.SH Output: + + Searching for 1: found 1 + Searching for 2: no dice! + Searching for 3: found 3 + +.SH See also + + ranges::equal_range returns range of elements matching a specific key + (C++20) (niebloid) + ranges::lower_bound returns an iterator to the first element not less than the + (C++20) given value + (niebloid) + ranges::upper_bound returns an iterator to the first element greater than a + (C++20) certain value + (niebloid) + ranges::contains + ranges::contains_subrange checks if the range contains the given element or subrange + (C++23) (niebloid) + (C++23) + determines if an element exists in a partially-ordered + binary_search range + \fI(function template)\fP diff --git a/man/std::ranges::borrowed_iterator_t,std::ranges::borrowed_subrange_t.3 b/man/std::ranges::borrowed_iterator_t,std::ranges::borrowed_subrange_t.3 new file mode 100644 index 000000000..71dbe5c11 --- /dev/null +++ b/man/std::ranges::borrowed_iterator_t,std::ranges::borrowed_subrange_t.3 @@ -0,0 +1,35 @@ +.TH std::ranges::borrowed_iterator_t,std::ranges::borrowed_subrange_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::borrowed_iterator_t,std::ranges::borrowed_subrange_t \- std::ranges::borrowed_iterator_t,std::ranges::borrowed_subrange_t + +.SH Synopsis + Defined in header + template< ranges::range R > \fB(1)\fP \fI(since C++20)\fP + using borrowed_iterator_t = /* see below */; + template< ranges::range R > \fB(2)\fP \fI(since C++20)\fP + using borrowed_subrange_t = /* see below */; + + 1) std::ranges::iterator_t if R models borrowed_range, std::ranges::dangling + otherwise. + 2) std::ranges::subrange> if R models borrowed_range, + std::ranges::dangling otherwise. + + These two alias templates are used by some constrained algorithms to avoid returning + potentially dangling iterators or views. + +.SH Possible implementation + +.SH First version + template< std::ranges::range R > + using borrowed_iterator_t = std::conditional_t, + std::ranges::iterator_t, std::ranges::dangling>; +.SH Second version + template< std::ranges::range R > + using borrowed_subrange_t = std::conditional_t, + std::ranges::subrange>, std::ranges::dangling>; + +.SH See also + + ranges::dangling a placeholder type indicating that an iterator or a subrange should + (C++20) not be returned since it would be dangling + \fI(class)\fP diff --git a/man/std::ranges::borrowed_range,std::ranges::enable_borrowed_range.3 b/man/std::ranges::borrowed_range,std::ranges::enable_borrowed_range.3 new file mode 100644 index 000000000..4eb4a0cb6 --- /dev/null +++ b/man/std::ranges::borrowed_range,std::ranges::enable_borrowed_range.3 @@ -0,0 +1,119 @@ +.TH std::ranges::borrowed_range,std::ranges::enable_borrowed_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::borrowed_range,std::ranges::enable_borrowed_range \- std::ranges::borrowed_range,std::ranges::enable_borrowed_range + +.SH Synopsis + Defined in header + template< class R > + + concept borrowed_range = + ranges::range && \fB(1)\fP \fI(since C++20)\fP + (std::is_lvalue_reference_v || + + ranges::enable_borrowed_range>); + template< class R > \fB(2)\fP \fI(since C++20)\fP + inline constexpr bool enable_borrowed_range = false; + + 1) The concept borrowed_range defines the requirements of a range such that a + function can take it by value and return iterators obtained from it without danger + of dangling. + 2) The enable_borrowed_range variable template is used to indicate whether a range + is a borrowed_range. The primary template is defined as false. + +.SH Specializations + + Specializations of enable_borrowed_range for all specializations of the following + standard templates are defined as true: + + * std::basic_string_view + * std::span + * std::ranges::subrange + * std::ranges::ref_view + * std::ranges::empty_view + * std::ranges::iota_view + + Specialization of enable_borrowed_range for the following standard range adaptors + are defined as true if and only if std::ranges::enable_borrowed_range is true, + where V is the underlying view type: + + * std::ranges::owning_view + * std::ranges::take_view + * std::ranges::drop_view + * std::ranges::drop_while_view + * std::ranges::common_view + * std::ranges::reverse_view + * std::ranges::elements_view + + * std::ranges::adjacent_view (since C++23) + + Specialization for std::ranges::zip_view is defined as true if and + only if (std::ranges::enable_borrowed_range && ...) is true, where (since C++23) + Vs... are all view types it adapts. + + A program may specialize enable_borrowed_range to true for cv-unqualified + program-defined types which model borrowed_range, and false for types which do not. + Such specializations shall be usable in constant expression and have type const + bool. + +.SH Example + + Demonstrates the specializations of enable_borrowed_range for program defined types. + Such specializations protect against potentially dangling results. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + struct MyRange : std::array {}; + + template + inline constexpr bool std::ranges::enable_borrowed_range> = false; + + template + struct MyBorrowedRange : std::span {}; + + template + inline constexpr bool std::ranges::enable_borrowed_range> = true; + + int main() + { + static_assert(std::ranges::range>); + static_assert(std::ranges::borrowed_range> == false); + static_assert(std::ranges::range>); + static_assert(std::ranges::borrowed_range> == true); + + auto getMyRangeByValue = []{ return MyRange{{1, 2, 42, 3}}; }; + auto dangling_iter = std::ranges::max_element(getMyRangeByValue()); + static_assert(std::is_same_v); + // *dangling_iter; // compilation error (i.e. dangling protection works.) + + auto my = MyRange{{1, 2, 42, 3}}; + auto valid_iter = std::ranges::max_element(my); + std::cout << *valid_iter << ' '; // OK: 42 + + auto getMyBorrowedRangeByValue = [] + { + static int sa[4]{1, 2, 42, 3}; + return MyBorrowedRange{sa}; + }; + auto valid_iter2 = std::ranges::max_element(getMyBorrowedRangeByValue()); + std::cout << *valid_iter2 << '\\n'; // OK: 42 + } + +.SH Output: + + 42 42 + +.SH See also + + ranges::dangling a placeholder type indicating that an iterator or a subrange should + (C++20) not be returned since it would be dangling + \fI(class)\fP diff --git a/man/std::ranges::cartesian_product_view::begin.3 b/man/std::ranges::cartesian_product_view::begin.3 new file mode 100644 index 000000000..9e835be47 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::begin.3 @@ -0,0 +1,70 @@ +.TH std::ranges::cartesian_product_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::begin \- std::ranges::cartesian_product_view::begin + +.SH Synopsis + constexpr iterator begin() \fB(1)\fP (since C++23) + requires (!__simple_view || ... || !__simple_view); + constexpr iterator begin() const + requires (ranges::range && ... && \fB(2)\fP (since C++23) + ranges::range); + + Returns an iterator to the first element of the cartesian_product_view. + + Let bases_ be the tuple of underlying views. + + 1) Equivalent to return /*iterator*/(__tuple_transform(ranges::begin, + bases_));. + 2) Equivalent to return /*iterator*/(__tuple_transform(ranges::begin, + bases_));. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the first element. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + using namespace std::literals; + + int main() + { + constexpr auto a = std::array{"Curiously"sv, "Recurring"sv, "Template"sv, "Pattern"sv}; + + constexpr auto v = std::ranges::cartesian_product_view(a[0], a[1], a[2], a[3]); + + constexpr std::tuple first{*v.begin()}; + + std::cout << std::format("{}{}{}{}{}", + std::get<0>(first), + std::get<1>(first), + std::get<2>(first), + std::get<3>(first), + '\\n'); + } + +.SH Output: + + CRTP + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) diff --git a/man/std::ranges::cartesian_product_view::cartesian_product_view.3 b/man/std::ranges::cartesian_product_view::cartesian_product_view.3 new file mode 100644 index 000000000..69cd444dd --- /dev/null +++ b/man/std::ranges::cartesian_product_view::cartesian_product_view.3 @@ -0,0 +1,51 @@ +.TH std::ranges::cartesian_product_view::cartesian_product_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::cartesian_product_view \- std::ranges::cartesian_product_view::cartesian_product_view + +.SH Synopsis + constexpr cartesian_product_view() = default; \fB(1)\fP (since C++23) + constexpr explicit cartesian_product_view( First first_base, Vs... \fB(2)\fP (since C++23) + bases ); + + Constructs an cartesian_product_view. + + 1) Default constructor. Default-initializes the underlying data member base_. + 2) Move constructs the underlying base_ by initializing it with + std::move(first_base), std::move(bases).... + +.SH Parameters + + first_base - the first view object to adapt + bases - the pack of views objects to adapt + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto x = std::array{'A', 'B'}; + auto y = std::vector{1, 2, 3}; + auto z = std::vector{-1, -2, -3}; + + auto v = std::ranges::cartesian_product_view(x, y, z); // overload (2) + + for (int i{1}; auto const& [rx, ry, rz] : v) + std::cout << std::format("({} {} {}){}", rx, ry, rz, (i++ % 3) ? ' ' : '\\n'); + } + +.SH Output: + + (A 1 -1) (A 1 -2) (A 1 -3) + (A 2 -1) (A 2 -2) (A 2 -3) + (A 3 -1) (A 3 -2) (A 3 -3) + (B 1 -1) (B 1 -2) (B 1 -3) + (B 2 -1) (B 2 -2) (B 2 -3) + (B 3 -1) (B 3 -2) (B 3 -3) diff --git a/man/std::ranges::cartesian_product_view::end.3 b/man/std::ranges::cartesian_product_view::end.3 new file mode 100644 index 000000000..253b1a1a1 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::end.3 @@ -0,0 +1,86 @@ +.TH std::ranges::cartesian_product_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::end \- std::ranges::cartesian_product_view::end + +.SH Synopsis + constexpr iterator end() + + requires ((!__simple_view || ... || !__simple_view) \fB(1)\fP (since C++23) + && + + __cartesian_product_is_common); + constexpr iterator end() const + requires __cartesian_product_is_common; + constexpr std::default_sentinel_t end() const noexcept; \fB(3)\fP (since C++23) + + Returns an iterator or a sentinel representing the end of the + cartesian_product_view. + + Let bases_ be the underlying tuple of views. + + 1,2) Let: + * __is_const be true for the const-qualified overload, and false otherwise; + * __is_empty be true if the expression ranges::empty(rng) is true for any rng + among the underlying ranges except the first one and false otherwise; and + * __begin_or_first_end(rng) be expression-equivalent to __is_empty ? + ranges::begin(rng) : __cartesian_common_arg_end(rng) if rng is the first + underlying range and ranges::begin(rng) otherwise. + + Equivalent to: + + auto check = [](auto& rng) { return __begin_or_first_end(rng); }; + return iterator<__is_const>(__tuple_transform(check, bases_)); + + 3) Equivalent to: return std::default_sentinel;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the element following the last element, or a sentinel which compares + equal to the end iterator. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + using namespace std::literals; + + int main() + { + constexpr auto a = std::array{ "bool"sv, "goto"sv, "extern"sv, "long"sv }; /* + ^ ^ ^ ^ */ + constexpr auto v = std::ranges::cartesian_product_view(a[0], a[1], a[2], a[3]); + + constexpr std::tuple last{*(v.end() - 1)}; + + std::cout << std::format("{}{}{}{}{}", + std::get<0>(last), + std::get<1>(last), + std::get<2>(last), + std::get<3>(last), '\\n'); + } + +.SH Output: + + long + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::cartesian_product_view::iterator.3 b/man/std::ranges::cartesian_product_view::iterator.3 new file mode 100644 index 000000000..292b32dfc --- /dev/null +++ b/man/std::ranges::cartesian_product_view::iterator.3 @@ -0,0 +1,103 @@ +.TH std::ranges::cartesian_product_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::iterator \- std::ranges::cartesian_product_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of cartesian_product_view::begin, and of cartesian_product_view::end + when the underlying view V is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + iterator_category std::input_iterator_tag + * std::random_access_iterator_tag, if + /*cartesian-product-is-random-access*/ is + modeled, + * std::bidirectional_iterator_tag, if + iterator_concept /*cartesian-product-is-bidirectional*/ is + modeled, + * std::forward_iterator_tag, if + /*maybe-const*/ models forward_range, + * std::input_iterator_tag otherwise + value_type std::tuple>, + ranges::range_value_t>...>; + std::tuple>, + ranges::range_reference_t>...>; + An implementation-defined signed-integer-like type (maybe the + difference_type smallest of such types), which is sufficiently wide to store the + product of the maximum sizes of all underlying ranges, if such + type exists. + Parent (private) /*maybe-const*/. + (exposition-only member type*) + + Data members + + Member object Definition + parent_ A pointer of type Parent to the parent cartesian_product_view. + (private) (exposition-only member object*) + A tuple of iterators to the current underlying elements of type + current_ std::tuple>, + (private) ranges::iterator_t>...>. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + next advances the iterator + (C++23) (exposition-only member function*) + prev decrements the iterator + (C++23) (exposition-only member function*) + distance_from returns the distance between two iterators + (C++23) (exposition-only member function*) + +.SH Non-member functions + + operator== compares the underlying iterators + operator<=> \fI(function)\fP + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + iter_swap swaps underlying pointed-to elements + (C++23) \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.32.3 Class template cartesian_product_view::iterator + [range.cartesian.iterator] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::cartesian_product_view::iterator::iterator.3 b/man/std::ranges::cartesian_product_view::iterator::iterator.3 new file mode 100644 index 000000000..4e93fe804 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::iterator::iterator.3 @@ -0,0 +1,47 @@ +.TH std::ranges::cartesian_product_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::iterator::iterator \- std::ranges::cartesian_product_view::iterator::iterator + +.SH Synopsis + /*iterator*/() = default; \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && ( + std::convertible_to, + ranges::iterator_t> \fB(2)\fP (since C++23) + && ... && + std::convertible_to, + ranges::iterator_t> + + ); + private: + + constexpr /*iterator*/( + /*Parent*/& parent, \fB(3)\fP (exposition + std::tuple>, only*) + + ranges::iterator_t>...> + current ); + + Construct an iterator. + + 1) Default constructor. Value-initializes the parent_ with nullptr and + default-initializes the current_. + 2) Conversion from /*iterator*/ to /*iterator*/. Initializes parent_ + with i.parent_ and current_ with std::move(i.current_). + 3) A private constructor which is used by cartesian_product_view::begin and + cartesian_product_view::end. This constructor is not accessible to users. + Initializes parent_ with std::addressof(parent) and current_ with + std::move(current). + +.SH Parameters + + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::cartesian_product_view::iterator::next,.3 b/man/std::ranges::cartesian_product_view::iterator::next,.3 new file mode 100644 index 000000000..59b879f32 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::iterator::next,.3 @@ -0,0 +1,92 @@ +.TH std::ranges::cartesian_product_view::iterator::next, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::iterator::next, \- std::ranges::cartesian_product_view::iterator::next, + +.SH Synopsis + std::ranges::cartesian_product_view::iterator::distance_from + + template< std::size_t N = sizeof...(Vs) > (since C++23) + constexpr void /*next*/(); (exposition only*) + + If called with default template parameter, recursively generates the next element + (the tuple of iterators) in cartesian_product_view. + + Let current_ denote the underlying tuple of iterators. Equivalent to: + + auto& it = std::get(current_); + ++it; + if constexpr (N > 0) + { + if (it == ranges::end(std::get(parent_->bases_))) + { + it = ranges::begin(std::get(parent_->bases_)); + next(); + } + } + + Used in the following non-static member functions: + + * ranges::cartesian_product_view::operator+ + +std::ranges::cartesian_product_view::iterator::prev + + template< std::size_t N = sizeof...(Vs) > (since C++23) + constexpr void /*prev*/(); (exposition only*) + + If called with default template parameter, recursively generates the previous + element (the tuple of iterators) in cartesian_product_view. + + Let current_ denote the underlying tuple of iterators. Equivalent to: + + auto& it = std::get(current_); + if constexpr (N > 0) + { + if (it == ranges::begin(std::get(parent_->bases_))) + { + it = /*cartesian-common-arg-end*/(std::get(parent_->bases_)); + prev(); + } + } + --it; + + Used in the following non-static member functions: + + * ranges::cartesian_product_view::operator- + +std::ranges::cartesian_product_view::iterator::distance_from + + template< class Tuple > + (since C++23) + constexpr difference_type (exposition only*) + + /*distance-from*/( const Tuple& t ) const; + + Returns the "distance" (i.e., number of "hops") between two iterators. + + Let: + + * parent_ be the underlying pointer to cartesian_product_view + * /*scaled-size*/(N) be: + * the product of + static_cast(ranges::size(std::get(parent_->bases_))) + and /*scaled-size*/(N + 1) if N ≤ sizeof...(Vs), otherwise + * static_cast\fB(1)\fP; + * /*scaled-distance*/(N) be the product of + static_cast(std::get(current_) - std::get(t)) and + /*scaled-size*/(N + 1); + * /*scaled-sum*/ be the sum of /*scaled-distance*/(N) for every integer 0 ≤ N ≤ + sizeof...(Vs). + + Returns: /*scaled-sum*/. + + The behavior is undefined if /*scaled-sum*/ cannot be represented by + difference_type. + + Used in the following functions: + + * operator-(const /*iterator*/&, const /*iterator*/&) + * operator-(const /*iterator*/&, std::default_sentinel_t) + +.SH Parameters + + t - a tuple of iterators to find the distance to diff --git a/man/std::ranges::cartesian_product_view::iterator::operator*.3 b/man/std::ranges::cartesian_product_view::iterator::operator*.3 new file mode 100644 index 000000000..7d6809280 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::iterator::operator*.3 @@ -0,0 +1,31 @@ +.TH std::ranges::cartesian_product_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::iterator::operator* \- std::ranges::cartesian_product_view::iterator::operator* + +.SH Synopsis + constexpr auto operator*() const; (since C++23) + + Returns the current element in the cartesian_product_view. Equivalent to: + + return /*tuple-transform*/([](auto& i) -> decltype(auto) { return *i; }, current_);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::cartesian_product_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::cartesian_product_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..cc0572be1 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,67 @@ +.TH std::ranges::cartesian_product_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::iterator::operator++,--,+=,-= \- std::ranges::cartesian_product_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/ operator++( int ) \fB(3)\fP (since C++23) + requires ranges::forward_range>; + constexpr /*iterator*/& operator--() + requires /*cartesian-product-is-bidirectional*/; + constexpr /*iterator*/ operator--( int ) + requires /*cartesian-product-is-bidirectional*/; + constexpr /*iterator*/& operator+=( difference_type n ) + requires /*cartesian-product-is-random-access*/; + constexpr /*iterator*/& operator-=( difference_type n ) + requires /*cartesian-product-is-random-access*/; + + Increments or decrements the iterator. + + Let current_ denote the underlying tuple of iterators and parent_ denote the + underlying pointer to cartesian_product_view. + + 1) Equivalent to next(); return *this; + 2) Equivalent to ++*this; + 3) Equivalent to auto tmp = *this; ++*this; return tmp; + 4) Equivalent to prev(); return *this; + 5) Equivalent to auto tmp = *this; --*this; return tmp; + 6) Sets the value of *this to ret, where ret is: + * if n > 0, the value of *this provided that next been called n times. Otherwise, + * if n < 0, the value of *this provided that prev been called -n times. Otherwise, + * the value of *this before the call. + The behavior is undefined if n is not in the range [ranges::distance(*this, + ranges::begin(*parent_)), ranges::distance(*this, ranges::end(*parent_))). + 7) Equivalent to *this += -n; return *this;. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change. + +.SH Complexity + + 6) Constant. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::cartesian_product_view::iterator::operator[].3 b/man/std::ranges::cartesian_product_view::iterator::operator[].3 new file mode 100644 index 000000000..db76d50e8 --- /dev/null +++ b/man/std::ranges::cartesian_product_view::iterator::operator[].3 @@ -0,0 +1,32 @@ +.TH std::ranges::cartesian_product_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::iterator::operator[] \- std::ranges::cartesian_product_view::iterator::operator[] + +.SH Synopsis + constexpr reference operator[]( difference_type n ) const + requires /*cartesian-product-is-random-access*/; + + Returns an element at specified relative location. Equivalent to: return *((*this) + + n);. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The element at displacement n relative to the current location. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::cartesian_product_view::size.3 b/man/std::ranges::cartesian_product_view::size.3 new file mode 100644 index 000000000..45b1e1fbb --- /dev/null +++ b/man/std::ranges::cartesian_product_view::size.3 @@ -0,0 +1,68 @@ +.TH std::ranges::cartesian_product_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cartesian_product_view::size \- std::ranges::cartesian_product_view::size + +.SH Synopsis + constexpr /* see description */ size() \fB(1)\fP (since C++23) + requires __cartesian_product_is_sized; + constexpr /* see description */ size() const + requires __cartesian_product_is_sized; + + Returns the number of elements. The return type is an implementation-defined + unsigned-integer-like type U. + + Let bases_ be the underlying tuple of views, and prod be the product of the sizes of + all the ranges in bases_. + + 1,2) Returns prod. The behavior is undefined if prod cannot be represented by the + return type U. + + Equivalent to: + + return [&](std::index_sequence) + { + auto prod = static_cast\fB(1)\fP; + prod = (static_cast(ranges::size(std::get(bases_))) * ...); + return prod; + } + (std::make_index_sequence<1U + sizeof...(Vs)>{}); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements, that is, the product of the sizes of all the underlying + ranges. + +.SH Notes + + The return type is the smallest unsigned-integer-like type that is sufficiently wide + to store the product of the maximum sizes of all the underlying ranges, if such a + type exists. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr static auto w = {1}; + constexpr static auto x = {2, 3}; + constexpr static auto y = {4, 5, 6}; + constexpr static auto z = {7, 8, 9, 10, 11, 12, 13}; + constexpr auto v = std::ranges::cartesian_product_view(w, x, y, z); + static_assert(v.size() == w.size() * x.size() * y.size() * z.size() and v.size() == 42); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::cbegin.3 b/man/std::ranges::cbegin.3 new file mode 100644 index 000000000..013338380 --- /dev/null +++ b/man/std::ranges::cbegin.3 @@ -0,0 +1,91 @@ +.TH std::ranges::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cbegin \- std::ranges::cbegin + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ cbegin = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ auto cbegin( T&& t ); + + Returns an iterator to the first element of the const-qualified (until C++23) + argument. + Returns a constant iterator to the first element of the argument. (since C++23) + + range-begin-end.svg + + Let CT be + + * const std::remove_reference_t& if the argument is an lvalue (i.e. T is + an lvalue reference type), (until + * const T otherwise. C++23) + + A call to ranges::cbegin is expression-equivalent to + ranges::begin(static_cast(t)). + If the argument is an lvalue or + ranges::enable_borrowed_range> is true, then a call to + ranges::cbegin is expression-equivalent to: + + * std::const_iterator(U) for some expression U equivalent to (since + ranges::begin(/*possibly-const-range*/(t)). C++23) + + In all other cases, a call to ranges::cbegin is ill-formed, which can result + in substitution failure when the call appears in the immediate context of a + template instantiation. + + The return type models std::input_or_output_iterator + and constant-iterator + (since C++23) in all cases. + +.SH Notes + + For an lvalue range e of type T, ranges::cbegin(e) is equivalent to + + ranges::begin(std::as_const(e)). (until C++23) + * ranges::begin(e) if T models constant_range. + * Otherwise, ranges::begin(std::as_const(e)) if const T models (since C++23) + constant_range. + * Otherwise, std::basic_const_iterator(ranges::begin(e)). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v{3, 1, 4}; + auto vi = std::ranges::cbegin(v); + assert(3 == *vi); + ++vi; // OK, constant-iterator object is mutable + assert(1 == *vi); + // *vi = 13; // Error: constant-iterator points to an immutable element + + int a[]{3, 1, 4}; + auto ai = std::ranges::cbegin(a); // cbegin works with C-arrays as well + assert(3 == *ai and *(ai + 1) == 1); + // *ai = 13; // Error: read-only variable is not assignable + } + +.SH See also + + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::cdata.3 b/man/std::ranges::cdata.3 new file mode 100644 index 000000000..df00f1b2c --- /dev/null +++ b/man/std::ranges::cdata.3 @@ -0,0 +1,112 @@ +.TH std::ranges::cdata 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cdata \- std::ranges::cdata + +.SH Synopsis + Defined in header + Defined in header + inline namespace /*unspecified*/ { + + inline constexpr /*unspecified*/ cdata = \fI(since C++20)\fP + /*unspecified*/; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ cdata( T&& t ); + + Returns a pointer to the first element + of constant type + (since C++23) of a contiguous range denoted by a + const-qualified + (until C++23) argument. + + Let CT be + + * const std::remove_reference_t& if the argument is an lvalue (i.e. T is + an lvalue reference type), + * const T otherwise. (until + C++23) + A call to ranges::cdata is expression-equivalent to + ranges::data(static_cast(t)). + + The return type is equivalent to + std::remove_reference_t>*. + + If the argument is an lvalue or + ranges::enable_borrowed_range> is true, then a call to + ranges::cdata is expression-equivalent to: + + * /*as-const-pointer*/(ranges::data(/*possibly-const-range*/(t))). + (since + The return type is equivalent to C++23) + std::remove_reference_t>*. + + In all other cases, a call to ranges::cdata is ill-formed, which can result + in substitution failure when the call appears in the immediate context of a + template instantiation. + + If ranges::cdata(t) is valid, then it returns a pointer to an object + of constant type + (since C++23). + + Customization point objects + + The name ranges::cdata denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __cdata_fn. + + All instances of __cdata_fn are equal. The effects of invoking different instances + of type __cdata_fn on the same arguments are equivalent, regardless of whether the + expression denoting the instance is an lvalue or rvalue, and is const-qualified or + not (however, a volatile-qualified instance is not required to be invocable). Thus, + ranges::cdata can be copied freely and its copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::cdata above, __cdata_fn models + + * std::invocable<__cdata_fn, Args...>, + * std::invocable, + * std::invocable<__cdata_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __cdata_fn participates in overload + resolution. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string src {"hello world!\\n"}; + + // std::ranges::cdata(src)[0] = 'H'; // error, src.data() is treated as read-only + std::ranges::data(src)[0] = 'H'; // OK, src.data() is a non-const storage + + char dst[20]; // storage for a C-style string + std::strcpy(dst, std::ranges::cdata(src)); + // [data(src), data(src) + size(src)] is guaranteed to be an NTBS + + std::cout << dst; + } + +.SH Output: + + Hello world! + +.SH See also + + ranges::data obtains a pointer to the beginning of a contiguous range + (C++20) (customization point object) + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::cend.3 b/man/std::ranges::cend.3 new file mode 100644 index 000000000..6a4e78674 --- /dev/null +++ b/man/std::ranges::cend.3 @@ -0,0 +1,104 @@ +.TH std::ranges::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::cend \- std::ranges::cend + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ cend = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ auto cend( T&& t ); + + Returns a sentinel + for the constant iterator + (since C++23) indicating the end of a + const-qualified + (until C++23) range. + + range-begin-end.svg + + Let CT be + + * const std::remove_reference_t& if the argument is an lvalue (i.e. T is + an lvalue reference type), (until + * const T otherwise. C++23) + + A call to ranges::cend is expression-equivalent to + ranges::end(static_cast(t)). + If the argument is an lvalue or + ranges::enable_borrowed_range> is true, then a call to + ranges::cend is expression-equivalent to: + + * std::const_sentinel(U) for some expression U equivalent to (since + ranges::end(/*possibly-const-range*/(t)). C++23) + + In all other cases, a call to ranges::cend is ill-formed, which can result in + substitution failure when the call appears in the immediate context of a + template instantiation. + + If ranges::cend(e) is valid for an expression e, where decltype((e)) is T, then + CT models std::ranges::range, and + (until C++23) std::sentinel_for is true in all cases, where S is + decltype(ranges::cend(e)), and I is decltype(ranges::cbegin(e)). + Additionally, S models constant-iterator if it models input_iterator. + (since C++23) + + Customization point objects + + The name ranges::cend denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __cend_fn. + + All instances of __cend_fn are equal. The effects of invoking different instances of + type __cend_fn on the same arguments are equivalent, regardless of whether the + expression denoting the instance is an lvalue or rvalue, and is const-qualified or + not (however, a volatile-qualified instance is not required to be invocable). Thus, + ranges::cend can be copied freely and its copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::cend above, __cend_fn models + + * std::invocable<__cend_fn, Args...>, + * std::invocable, + * std::invocable<__cend_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __cend_fn participates in overload + resolution. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector vec{3, 1, 4}; + int arr[]{5, 10, 15}; + + assert(std::ranges::find(vec, 5) == std::ranges::cend(vec)); + assert(std::ranges::find(arr, 5) != std::ranges::cend(arr)); + } + +.SH See also + + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::chunk_by_view::base.3 b/man/std::ranges::chunk_by_view::base.3 new file mode 100644 index 000000000..c758f1470 --- /dev/null +++ b/man/std::ranges::chunk_by_view::base.3 @@ -0,0 +1,29 @@ +.TH std::ranges::chunk_by_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::base \- std::ranges::chunk_by_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns a copy of the underlying view base_. + + 1) Copy constructs the result from the underlying view. Equivalent to: return base_; + 2) Move constructs the result from the underlying view. Equivalent to: return + std::move(base_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::begin.3 b/man/std::ranges::chunk_by_view::begin.3 new file mode 100644 index 000000000..8b69b6abd --- /dev/null +++ b/man/std::ranges::chunk_by_view::begin.3 @@ -0,0 +1,54 @@ +.TH std::ranges::chunk_by_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::begin \- std::ranges::chunk_by_view::begin + +.SH Synopsis + constexpr /*iterator*/ begin(); (since C++23) + + Returns an iterator to the first element of the chunk_by_view. + + Equivalent to: + + ranges::iterator_t iter; + + if (begin_.has_value()) + iter = begin_.value(); + else + { + iter = /*find_next*/(ranges::begin(base())); + begin_ = iter; // caching + } + + return /*iterator*/(*this, ranges::begin(base()), iter); + + The behavior is undefined if the underlying predicate pred_ does not contain a + value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Notes + + In order to provide the amortized constant-time complexity required by the range + concept, this function caches the result within the data member begin_ (the name is + for exposition only) for use on subsequent calls. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::chunk_by_view.3 b/man/std::ranges::chunk_by_view::chunk_by_view.3 new file mode 100644 index 000000000..117889c10 --- /dev/null +++ b/man/std::ranges::chunk_by_view::chunk_by_view.3 @@ -0,0 +1,35 @@ +.TH std::ranges::chunk_by_view::chunk_by_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::chunk_by_view \- std::ranges::chunk_by_view::chunk_by_view + +.SH Synopsis + chunk_by_view() + + requires std::default_initializable && \fB(1)\fP (since C++23) + std::default_initializable + + = default; + constexpr explicit chunk_by_view( V base, Pred pred ); \fB(2)\fP (since C++23) + + Constructs a chunk_by_view. + + 1) Default constructor. Value-initializes the underlying data members via their + respective default member initializers: + * the view base_ via = V(), + * the binary predicate pred_ via = Pred(). + 2) Move constructs the underlying data members: + * the view base_ with std::move(base), + * the binary predicate pred_ with std::move(pred). + +.SH Parameters + + base - the view to split + pred - the function object (a binary predicate) used as a splitting criteria + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::end.3 b/man/std::ranges::chunk_by_view::end.3 new file mode 100644 index 000000000..0fde2df5d --- /dev/null +++ b/man/std::ranges::chunk_by_view::end.3 @@ -0,0 +1,44 @@ +.TH std::ranges::chunk_by_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::end \- std::ranges::chunk_by_view::end + +.SH Synopsis + constexpr auto end(); (since C++23) + + Returns an iterator or a sentinel representing the end of the chunk_by_view. + + Equivalent to: + + if constexpr (ranges::common_range) + return /*iterator*/(*this, ranges::end(base_), ranges::end(base_)); + else + return std::default_sentinel; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the element following the last element, or a sentinel which compares + equal to the end iterator. + +.SH Notes + + end() returns an iterator if and only if the underlying view is a common_range: + chunk_by_view models common_range whenever V does. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::find_next,.3 b/man/std::ranges::chunk_by_view::find_next,.3 new file mode 100644 index 000000000..66156ffcb --- /dev/null +++ b/man/std::ranges::chunk_by_view::find_next,.3 @@ -0,0 +1,64 @@ +.TH std::ranges::chunk_by_view::find_next, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::find_next, \- std::ranges::chunk_by_view::find_next, + +.SH Synopsis + + constexpr ranges::iterator_t (since C++23) + /*find-next*/( ranges::iterator_t current ); (exposition only*) + + Finds the next chunk. + + Let base_ and pred_ be appropriate underlying data-members of chunk_by_view. + + Equivalent to + + return ranges::next + ( + ranges::adjacent_find + ( + current, ranges::end(base_), std::not_fn(std::ref(*pred_)) + ), + 1, ranges::end(base_) + ); + + The behavior is undefined if pred_.has_value() is false before the call to this + function. + + Used in the following non-static member functions: + + * ranges::chunk_by_view::iterator::operator++ + +.SH Parameters + + current - the iterator to current element in adapted view + +std::ranges::chunk_by_view::prev + + constexpr iterator_t + (since C++23) + /*find-prev*/( ranges::iterator_t current ) (exposition only*) + + requires ranges::bidirectional_range; + + Finds the previous chunk. + + Let base_ and pred_ be appropriate underlying data-members of chunk_by_view. + + Returns an iterator i in the range [ranges::begin(base_), current) such that: + + * ranges::adjacent_find(i, current, std::not_fn(std::ref(*pred_))) is equal to + current, and + * if i is not equal to ranges::begin(base_), then bool(std::invoke(*pred_, + *ranges::prev(i), *i)) is false. + + The behavior is undefined if before the call to this function current == + ranges::begin(base_) or pred_.has_value() != true. + + Used in the following non-static member functions: + + * ranges::chunk_by_view::iterator::operator-- + +.SH Parameters + + current - the iterator to current element in adapted view. diff --git a/man/std::ranges::chunk_by_view::iterator.3 b/man/std::ranges::chunk_by_view::iterator.3 new file mode 100644 index 000000000..c062d52fd --- /dev/null +++ b/man/std::ranges::chunk_by_view::iterator.3 @@ -0,0 +1,65 @@ +.TH std::ranges::chunk_by_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::iterator \- std::ranges::chunk_by_view::iterator + +.SH Synopsis + class /*iterator*/ (since C++23) + (exposition only*) + + The return type of chunk_by_view::begin, and of chunk_by_view::end when the + underlying view V is a common_range. + +.SH Member types + + Member type Definition + value_type ranges::subrange> + difference_type ranges::range_difference_t + iterator_category std::input_iterator_tag + * std::bidirectional_iterator_tag, if V models + iterator_concept bidirectional_range, otherwise + * std::forward_iterator_tag. + + Data members + + Member object Definition + parent_ (private) A pointer to the parent chunk_by_view. + (exposition-only member object*) + current_ (private) ranges::iterator_t, an iterator to the begin of current chunk. + (exposition-only member object*) + ranges::iterator_t, an iterator to the begin of next chunk, if + next_ (private) present. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator++ + operator++(int) advances or decrements the underlying iterators + operator-- \fI(public member function)\fP + operator--(int) + (C++23) + +.SH Non-member functions + + operator== compares the underlying iterators + (C++23) \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.30.3 Class chunk_by_view::iterator [range.chunk.by.iter] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::iterator::iterator.3 b/man/std::ranges::chunk_by_view::iterator::iterator.3 new file mode 100644 index 000000000..ac1f79aa8 --- /dev/null +++ b/man/std::ranges::chunk_by_view::iterator::iterator.3 @@ -0,0 +1,37 @@ +.TH std::ranges::chunk_by_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::iterator::iterator \- std::ranges::chunk_by_view::iterator::iterator + +.SH Synopsis + /*iterator*/() = default; \fB(1)\fP (since C++23) + private: + + constexpr /*iterator*/( chunk_by_view& parent, \fB(2)\fP (exposition only*) + ranges::iterator_t current, + + ranges::iterator_t next ); + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying data-members as follows: + * parent_ with nullptr, + * current_ with ranges::iterator_t(), + * next_ with ranges::iterator_t(). + 2) A private constructor which is used by chunk_by_view::begin and + chunk_by_view::end. This constructor is not accessible to users. Initializes: + * parent_ with std::addressof(parent), + * current_ with current, + * next_ with next. + +.SH Parameters + + parent - a parent object + current, next - iterators + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::iterator::operator*.3 b/man/std::ranges::chunk_by_view::iterator::operator*.3 new file mode 100644 index 000000000..dc4136204 --- /dev/null +++ b/man/std::ranges::chunk_by_view::iterator::operator*.3 @@ -0,0 +1,29 @@ +.TH std::ranges::chunk_by_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::iterator::operator* \- std::ranges::chunk_by_view::iterator::operator* + +.SH Synopsis + constexpr value_type operator*() const; (since C++23) + + Returns the current element in the chunk_by_view. + + Equivalent to: return ranges::subrange(current_, next_). + + Before the call to this operator current_ must not be equal to next_, otherwise the + behavior is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_by_view::iterator::operator++,--.3 b/man/std::ranges::chunk_by_view::iterator::operator++,--.3 new file mode 100644 index 000000000..5d31c29ad --- /dev/null +++ b/man/std::ranges::chunk_by_view::iterator::operator++,--.3 @@ -0,0 +1,45 @@ +.TH std::ranges::chunk_by_view::iterator::operator++,-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::iterator::operator++,-- \- std::ranges::chunk_by_view::iterator::operator++,-- + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr /*iterator*/ operator++(int); \fB(2)\fP (since C++23) + constexpr /*iterator*/& operator--() requires \fB(3)\fP (since C++23) + ranges::bidirectional_range; + constexpr /*iterator*/ operator--(int) requires \fB(4)\fP (since C++23) + ranges::bidirectional_range; + + Increments or decrements the iterator. + + Let parent_, current_, and next_ be the appropriate underlying (exposition-only) + data-members of iterator. + + Let find-next and find-prev be appropriate (exposition-only) member functions of + ranges::chunk_by_view. + + 1) Equivalent to: + + current_ = next_; + next_ = parent_->/*find-next*/(current_); + return *this; + + The behavior is undefined if before the call to this operator current_ is equal to + next_. + 2) Equivalent to: auto tmp = *this; ++*this; return tmp; + 3) Equivalent to: + + next_ = current_; + current_ = parent_->/*find-prev*/(next_); + return *this; + + 4) Equivalent to: auto tmp = *this; --*this; return tmp; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) *this + 2,4) a copy of *this that was made before the change. diff --git a/man/std::ranges::chunk_by_view::pred.3 b/man/std::ranges::chunk_by_view::pred.3 new file mode 100644 index 000000000..5fd215c7a --- /dev/null +++ b/man/std::ranges::chunk_by_view::pred.3 @@ -0,0 +1,26 @@ +.TH std::ranges::chunk_by_view::pred 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_by_view::pred \- std::ranges::chunk_by_view::pred + +.SH Synopsis + constexpr const Pred& pred() const; (since C++23) + + Returns a reference to the contained Pred object. Equivalent to return *pred_;. + + The behavior is undefined if pred_ does not contain a value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the contained Pred object. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::base.3 b/man/std::ranges::chunk_view::base.3 new file mode 100644 index 000000000..b9cffa972 --- /dev/null +++ b/man/std::ranges::chunk_view::base.3 @@ -0,0 +1,44 @@ +.TH std::ranges::chunk_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::base \- std::ranges::chunk_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns a copy of the underlying view. + + Let base_ be the underlying view. + + 1) Copy constructs the result from the underlying view. Equivalent to return base_; + 2) Move constructs the result from the underlying view. Equivalent to return + std::move(base_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + A link to test the example online: Compiler Explorer. + + +// Run this code + + #include + #include + + int main() + { + static constexpr auto v = {1, 2, 3, 4}; + constexpr auto w{std::ranges::chunk_view(v, 2)}; + std::println("{}", w.base()); + } + +.SH Output: + + [1, 2, 3, 4] diff --git a/man/std::ranges::chunk_view::begin.3 b/man/std::ranges::chunk_view::begin.3 new file mode 100644 index 000000000..fe6a097ae --- /dev/null +++ b/man/std::ranges::chunk_view::begin.3 @@ -0,0 +1,50 @@ +.TH std::ranges::chunk_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::begin \- std::ranges::chunk_view::begin + +.SH Synopsis + V models only input_range + constexpr __outer_iterator begin(); \fB(1)\fP (since C++23) + V models forward_range + constexpr auto begin() requires (!__simple_view); \fB(2)\fP (since C++23) + constexpr auto begin() const requires ranges::forward_range; + + Returns an iterator to the first element of the chunk_view. + + Let base_ denote the underlying view. + 1) Available only if V models input_range. Equivalent to: + + current_ = ranges::begin(base_); + remainder_ = n_; + return __outer_iterator(*this); + + current_, remainder_, and n_ are underlying exposition only data members of + chunk_view. + 2) Available if V models forward_range. Equivalent to: return iterator(this, + ranges::begin(base_));, where iterator is exposition only nested class. + 3) Available if V models forward_range. Equivalent to: return iterator(this, + ranges::begin(base_));, where iterator is exposition only nested class. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the first element of the chunk_view, as described above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::chunk_view.3 b/man/std::ranges::chunk_view::chunk_view.3 new file mode 100644 index 000000000..b4b1c5d9e --- /dev/null +++ b/man/std::ranges::chunk_view::chunk_view.3 @@ -0,0 +1,53 @@ +.TH std::ranges::chunk_view::chunk_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::chunk_view \- std::ranges::chunk_view::chunk_view + +.SH Synopsis + constexpr explicit chunk_view( V base, ranges::range_difference_t (since C++23) + n ); + + Constructs a chunk_view, initializing the underlying data members: + + * move constructs the base_ with std::move(base), + * initializes the "chunk size" n_ with n. + + In addition, if V models exactly the input_range, the constructor initializes the + following exposition-only data members: + + * initializes the remainder_ with 0, + * default-initializes the current_. + + The behavior is undefined if n is less than or equal to 0. + +.SH Parameters + + base - the adapted view + n - the chunk size + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + auto i = std::views::iota(0, 10); + auto w = std::ranges::chunk_view(i, 4); + + std::ranges::for_each(w, [](auto const v) + { + for (auto e : v) + std::cout << e << ' '; + std::cout << '\\n'; + }); + } + +.SH Output: + + 0 1 2 3 + 4 5 6 7 + 8 9 diff --git a/man/std::ranges::chunk_view::end.3 b/man/std::ranges::chunk_view::end.3 new file mode 100644 index 000000000..b8bf96ca2 --- /dev/null +++ b/man/std::ranges::chunk_view::end.3 @@ -0,0 +1,66 @@ +.TH std::ranges::chunk_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::end \- std::ranges::chunk_view::end + +.SH Synopsis + V models only input_range + constexpr std::default_sentinel_t end() const noexcept; \fB(1)\fP (since C++23) + V models forward_range + constexpr auto end() requires (!__simple_view); \fB(2)\fP (since C++23) + constexpr auto end() const requires ranges::forward_range; + + Returns an iterator or a std::default_sentinel that compares equal to the end + iterator of the chunk_view. + + 1) Available only if V models input_range. Equivalent to: return + std::default_sentinel. + 2,3) Available if V models forward_range. Let base_ denote the underlying adapted + view, n_ denote the stored chunk size, and iterator denote the nested iterator + class. + 2) Equivalent to: + + if constexpr (ranges::common_range && ranges::sized_range) + { + auto missing = (n_ - ranges::distance(base_) % n_) % n_; + return iterator(this, ranges::end(base_), missing); + } + else if constexpr (ranges::common_range && !ranges::bidirectional_range) + return iterator(this, ranges::end(base_)); + else + return std::default_sentinel; + + 3) Equivalent to: + + if constexpr (ranges::common_range && ranges::sized_range) + { + auto missing = (n_ - ranges::distance(base_) % n_) % n_; + return iterator(this, ranges::end(base_), missing); + } + else if constexpr (ranges::common_range && !ranges::bidirectional_range) + return iterator(this, ranges::end(base_)); + else + return std::default_sentinel; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator or sentinel representing the end of the chunk_view, as described above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::inner-iterator.3 b/man/std::ranges::chunk_view::inner-iterator.3 new file mode 100644 index 000000000..a7026c9fe --- /dev/null +++ b/man/std::ranges::chunk_view::inner-iterator.3 @@ -0,0 +1,89 @@ +.TH std::ranges::chunk_view::inner-iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::inner-iterator \- std::ranges::chunk_view::inner-iterator + +.SH Synopsis + class /*inner-iterator*/ (since C++23) + (exposition only*) + + The return type of chunk_view::outer-iterator::value_type::begin if V models + input_range. + +.SH Member types + + Member type Definition + iterator_concept std::input_iterator_tag + difference_type ranges::range_difference_t + value_type ranges::range_value_t + + Data members + + Member object Definition + parent_ (private) A pointer to the "parent object" of type ranges::chunk_view*. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator= move assigns another iterator + (C++23) \fI(public member function)\fP + base returns an iterator to the current element + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator++ increments the iterator + (C++23) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares the iterator with default sentinel + (C++23) \fI(function)\fP + operator- calculates the remained number of elements + (C++23) \fI(function)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++23) \fI(function)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto letters = std::istringstream{"ABCDEFGHIJK"}; + + auto chunks = std::ranges::istream_view(letters) + | std::views::chunk(4); + + for (auto chunk : chunks) + { + // chunk is an object of type chunk_view::outer_iterator::value_type + std::cout << '['; + for (auto inner_iter = chunk.begin(); inner_iter != std::default_sentinel; + ++inner_iter) + std::cout << *inner_iter; + std::cout << "] "; + } + std::cout << '\\n'; + } + +.SH Output: + + [ABCD] [EFGH] [IJK] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.28.5 Class chunk_view::inner-iterator [range.chunk.inner.iter] + +.SH See also diff --git a/man/std::ranges::chunk_view::inner-iterator::base.3 b/man/std::ranges::chunk_view::inner-iterator::base.3 new file mode 100644 index 000000000..e8fac41b2 --- /dev/null +++ b/man/std::ranges::chunk_view::inner-iterator::base.3 @@ -0,0 +1,34 @@ +.TH std::ranges::chunk_view::inner-iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::inner-iterator::base \- std::ranges::chunk_view::inner-iterator::base + +.SH Synopsis + constexpr const ranges::iterator_t& base() const &; (since C++23) + + Returns the underlying cached iterator to current element (in current chunk) in + chunk_view. + + Let parent_ be the underlying pointer to the enclosing chunk_view. + + Equivalent to: return *parent_->current_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::inner-iterator::inner-iterator.3 b/man/std::ranges::chunk_view::inner-iterator::inner-iterator.3 new file mode 100644 index 000000000..2110860b3 --- /dev/null +++ b/man/std::ranges::chunk_view::inner-iterator::inner-iterator.3 @@ -0,0 +1,33 @@ +.TH std::ranges::chunk_view::inner-iterator::inner-iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::inner-iterator::inner-iterator \- std::ranges::chunk_view::inner-iterator::inner-iterator + +.SH Synopsis + /*inner-iterator*/( /*inner-iterator*/&& other ) = default; \fB(1)\fP (since C++23) + private: \fB(2)\fP (exposition only*) + constexpr explicit /*inner-iterator*/( chunk_view& parent ); + + Construct an iterator. + + 1) A move constructor which move-initializes the underlying pointer parent_ with + other.parent_. + 2) A private constructor which is used by chunk_view::begin. This constructor is not + accessible to users. Initializes parent_ with std::addressof(parent). + +.SH Parameters + + other - an iterator + parent - the enclosing ranges::chunk_view object + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= move assigns another iterator + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::inner-iterator::operator*.3 b/man/std::ranges::chunk_view::inner-iterator::operator*.3 new file mode 100644 index 000000000..e07f90420 --- /dev/null +++ b/man/std::ranges::chunk_view::inner-iterator::operator*.3 @@ -0,0 +1,35 @@ +.TH std::ranges::chunk_view::inner-iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::inner-iterator::operator* \- std::ranges::chunk_view::inner-iterator::operator* + +.SH Synopsis + constexpr ranges::range_reference_t operator*() const; (since C++23) + + Returns the current element in current chunk in the chunk_view. + + Let parent_ be the underlying pointer to chunk_view. Equivalent to: return + **parent_->current_;. + + Before invocation of this operator the expression *this == std::default_sentinel + must be false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element in current chunk. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + base returns an iterator to the current element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::inner-iterator::operator++.3 b/man/std::ranges::chunk_view::inner-iterator::operator++.3 new file mode 100644 index 000000000..61243f3d6 --- /dev/null +++ b/man/std::ranges::chunk_view::inner-iterator::operator++.3 @@ -0,0 +1,46 @@ +.TH std::ranges::chunk_view::inner-iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::inner-iterator::operator++ \- std::ranges::chunk_view::inner-iterator::operator++ + +.SH Synopsis + constexpr /*inner-iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + + Increments the iterator. + + Let parent_ be the underlying pointer to enclosing chunk_view. + + 1) Equivalent to: + + ++*parent_->current_; + if (*parent_->current_ == ranges::end(parent_->base_)) + parent_->remainder_ = 0; + else + --parent_->remainder_; + return *this; + + Before invocation of this operator the expression *this == std::default_sentinel + must be false. + 2) Equivalent to ++*this. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) *this + 2) \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator- calculates the number of chunks remained + (C++23) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::inner-iterator::operator=.3 b/man/std::ranges::chunk_view::inner-iterator::operator=.3 new file mode 100644 index 000000000..d44cca118 --- /dev/null +++ b/man/std::ranges::chunk_view::inner-iterator::operator=.3 @@ -0,0 +1,21 @@ +.TH std::ranges::chunk_view::inner-iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::inner-iterator::operator= \- std::ranges::chunk_view::inner-iterator::operator= + +.SH Synopsis + /*inner-iterator*/& operator=( /*inner-iterator*/&& other ) = (since C++23) + default; + + Assigns another iterator. This move assignment operator is generated by the + compiler. + + Moves the underlying pointer other.parent_ to parent_. + +.SH Parameters + + other - an iterator + +.SH See also + + constructor constructs an iterator + (C++23) \fI(public member function)\fP diff --git a/man/std::ranges::chunk_view::iterator.3 b/man/std::ranges::chunk_view::iterator.3 new file mode 100644 index 000000000..36b75e511 --- /dev/null +++ b/man/std::ranges::chunk_view::iterator.3 @@ -0,0 +1,97 @@ +.TH std::ranges::chunk_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::iterator \- std::ranges::chunk_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of chunk_view::begin, and of chunk_view::end when the underlying + view V is a common_range. + + Present only if V models forward_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + Parent (private) const chunk_view if Const is true, otherwise chunk_view. + (exposition-only member type*) + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + iterator_category std::input_iterator_tag + * std::random_access_iterator_tag, if Base models + random_access_range. Otherwise, + iterator_concept * std::bidirectional_iterator_tag, if Base models + bidirectional_range. Otherwise, + * std::forward_iterator_tag. + value_type decltype(views::take(ranges::subrange(current_, end_), n_));. + difference_type ranges::range_difference_t + + Data members + + Member object Definition + ranges::iterator_t, holds an iterator to the first element + current_ (private) of current chunk in the underlying sequence (i.e. the begin of a + chunk). + (exposition-only member object*) + ranges::sentinel_t, holds a sentinel to the end of the + end_ (private) underlying sequence. + (exposition-only member object*) + ranges::range_difference_t, holds initial number of + n_ (private) elements in the chunk (the last chunk can be smaller). + (exposition-only member object*) + ranges::range_difference_t, usually equals to + missing_ (private) ranges::advance(current_, n_, end_);. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + base returns an iterator to current element + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.28.7 Class template chunk_view::iterator for forward ranges + [range.chunk.fwd.iter] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::iterator::base.3 b/man/std::ranges::chunk_view::iterator::base.3 new file mode 100644 index 000000000..0b2ae72f1 --- /dev/null +++ b/man/std::ranges::chunk_view::iterator::base.3 @@ -0,0 +1,26 @@ +.TH std::ranges::chunk_view::iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::iterator::base \- std::ranges::chunk_view::iterator::base + +.SH Synopsis + constexpr ranges::iterator_t base() const; (since C++23) + + Returns the underlying iterator to the begin of current chunk. + + Equivalent to return current_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::iterator::iterator.3 b/man/std::ranges::chunk_view::iterator::iterator.3 new file mode 100644 index 000000000..905bb559e --- /dev/null +++ b/man/std::ranges::chunk_view::iterator::iterator.3 @@ -0,0 +1,58 @@ +.TH std::ranges::chunk_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::iterator::iterator \- std::ranges::chunk_view::iterator::iterator + +.SH Synopsis + /*iterator*/() = default; \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires + Const and + std::convertible_to, \fB(2)\fP (since C++23) + ranges::iterator_t> and + + std::convertible_to, + ranges::sentinel_t>; + private: + + constexpr /*iterator*/( Parent* parent, + ranges::iterator_t current, \fB(3)\fP (exposition only*) + + ranges::range_difference_t + missing = 0 ); + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying data members: + * current_ with ranges::iterator_t(), + * end_ with ranges::sentinel_t(), + * n_ with 0, + * missing_ with 0. + 2) Conversion from /*iterator*/ to /*iterator*/. Initializes the + underlying data members: + * current_ with std::move(i.current_), + * end_ with std::move(i.end_), + * n_ with i.n_, + * missing_ with i.missing_. + 3) A private constructor which is used by ranges::chunk_view::begin and + ranges::chunk_view::end. This constructor is not accessible to users. Initializes + the underlying data members: + * current_ with current, + * end_ with ranges::end(parent->base_), + * n_ with parent->n_, + * missing_ with missing. + +.SH Parameters + + i - an /*iterator*/ + parent - a pointer to owning chunk_view + current - an iterator to the begin of current chunk + missing - a difference between expected (n_) and actual size of current chunk + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::iterator::operator*.3 b/man/std::ranges::chunk_view::iterator::operator*.3 new file mode 100644 index 000000000..59a2a20af --- /dev/null +++ b/man/std::ranges::chunk_view::iterator::operator*.3 @@ -0,0 +1,36 @@ +.TH std::ranges::chunk_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::iterator::operator* \- std::ranges::chunk_view::iterator::operator* + +.SH Synopsis + constexpr value_type operator*() const; (since C++23) + + Returns the current element in the chunk_view. + + Let current_, end_, and n_ be the underlying data members. + + Equivalent to: return views::take(ranges::subrange(current_, end_), n_). + + Before the invocation the expression current_ != end_ must be true, otherwise the + behavior is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element, which is an object of value_type. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::chunk_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..0f85510cb --- /dev/null +++ b/man/std::ranges::chunk_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,77 @@ +.TH std::ranges::chunk_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::iterator::operator++,--,+=,-= \- std::ranges::chunk_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr /*iterator*/ operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/& operator--() \fB(3)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type x ) \fB(5)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type x ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + + Advances or decrements the iterator. + + Let current_, end_, and n_ be the underlying data members of chunk_view::iterator. + + 1) Equivalent to: + + missing_ = ranges::advance(current_, n_, end_); + return *this; + + Before the invocation the expression current_ != end_ must be true, otherwise the + behavior is undefined. + 2) Equivalent to: auto tmp = *this; ++*this; return tmp;. + 3) Equivalent to: + + ranges::advance(current_, missing_ - n_); + missing_ = 0; + return *this; + + 4) Equivalent to: auto tmp = *this; --*this; return tmp;. + 5) Equivalent to: + + if (x > 0) + { + ranges::advance(current_, n_ * (x - 1)); + missing_ = ranges::advance(current_, n_, end_); + } + else if (x < 0) + { + ranges::advance(current_, n_ * x + missing_); + missing_ = 0; + } + return *this; + + If x is positive, then before the invocation the expression + ranges::distance(current_, end_) > n_ * (x - 1) must be true (i.e., informally, the + requested chunk should be "inside" the underlying sequence). If x is negative, this + precondition is always met. + 6) Equivalent to: return *this += -x;. + +.SH Parameters + + x - a position relative to current location + +.SH Return value + + 1,3,5,6) *this + 2,4) a copy of *this that was made before the change + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::iterator::operator[].3 b/man/std::ranges::chunk_view::iterator::operator[].3 new file mode 100644 index 000000000..07b647a77 --- /dev/null +++ b/man/std::ranges::chunk_view::iterator::operator[].3 @@ -0,0 +1,33 @@ +.TH std::ranges::chunk_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::iterator::operator[] \- std::ranges::chunk_view::iterator::operator[] + +.SH Synopsis + constexpr value_type operator[]( difference_type pos ) const (since C++23) + requires ranges::random_access_range; + + Returns an element at specified relative location. + + Equivalent to: return *(*this + pos);. + +.SH Parameters + + pos - position relative to current location + +.SH Return value + + The element (of type value_type) at displacement pos relative to the current + location. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::outer-iterator.3 b/man/std::ranges::chunk_view::outer-iterator.3 new file mode 100644 index 000000000..012fe3653 --- /dev/null +++ b/man/std::ranges::chunk_view::outer-iterator.3 @@ -0,0 +1,102 @@ +.TH std::ranges::chunk_view::outer-iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::outer-iterator \- std::ranges::chunk_view::outer-iterator + +.SH Synopsis + class /*outer-iterator*/ (since C++23) + (exposition only*) + + The return type of chunk_view::begin if V models input_range. + +.SH Member types + + Member type Definition + iterator_concept std::input_iterator_tag + difference_type ranges::range_difference_t + + Data members + + Member object Definition + parent_ (private) A pointer to the "parent object" of type ranges::chunk_view* + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator= move assigns another iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator++ increments the iterator + (C++23) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares the iterator with default sentinel + (C++23) \fI(function)\fP + operator- calculates the number of chunks remaining + (C++23) \fI(function)\fP + + Nested classes + + value_type the value type of /*output-iterator*/ + (C++23) \fI(public member class)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::string source{"ABCDEFGHIJ"}; + + auto letters = std::istringstream{source}; + auto chunks = std::ranges::istream_view(letters) + | std::views::chunk(4); + + for (auto outer_iter = chunks.begin(); outer_iter != std::default_sentinel; + ++outer_iter) + { + auto chunk = *outer_iter; // chunk is an object of type + // chunk_view::outer_iterator::value_type + std::cout << '['; + for (auto inner_iter = chunk.begin(); inner_iter != std::default_sentinel; + ++inner_iter) + std::cout << *inner_iter; + std::cout << "] "; + } + std::cout << '\\n'; + + // The same output using range-for loops + auto letters2 = std::istringstream{source}; + auto chunks2 = std::ranges::istream_view(letters2) + | std::views::chunk(4); + for (auto chunk : chunks2) + { + std::cout << '['; + for (auto ch : chunk) + std::cout << ch; + std::cout << "] "; + } + std::cout << '\\n'; + } + +.SH Output: + + [ABCD] [EFGH] [IJ] + [ABCD] [EFGH] [IJ] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.28.3 Class chunk_view::outer-iterator [range.chunk.outer.iter] + +.SH See also diff --git a/man/std::ranges::chunk_view::outer-iterator::operator*.3 b/man/std::ranges::chunk_view::outer-iterator::operator*.3 new file mode 100644 index 000000000..c58f1408e --- /dev/null +++ b/man/std::ranges::chunk_view::outer-iterator::operator*.3 @@ -0,0 +1,32 @@ +.TH std::ranges::chunk_view::outer-iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::outer-iterator::operator* \- std::ranges::chunk_view::outer-iterator::operator* + +.SH Synopsis + constexpr value_type operator*() const; (since C++23) + + Returns the current chunk in the chunk_view. + + Let parent_ be the underlying pointer, and value_type be a nested class that is the + value type of the iterator. + + Equivalent to: return value_type(*parent_);. + + Before invocation of this operator the expression *this == std::default_sentinel + must be false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element (a chunk). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::outer-iterator::operator++.3 b/man/std::ranges::chunk_view::outer-iterator::operator++.3 new file mode 100644 index 000000000..2464bc1fa --- /dev/null +++ b/man/std::ranges::chunk_view::outer-iterator::operator++.3 @@ -0,0 +1,43 @@ +.TH std::ranges::chunk_view::outer-iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::outer-iterator::operator++ \- std::ranges::chunk_view::outer-iterator::operator++ + +.SH Synopsis + constexpr /*outer-iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + + Increments the iterator. + + Let parent_ be the underlying pointer to enclosing chunk_view. + + 1) Equivalent to: + + ranges::advance(*parent_->current_, parent_->remainder_, ranges::end(parent_->base_)); + parent_->remainder_ = parent_->n_; + return *this; + + Before invocation of this operator the expression *this == std::default_sentinel + must be false. + 2) Equivalent to ++*this. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) *this + 2) \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator- calculates the number of chunks remained + (C++23) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::outer-iterator::operator=.3 b/man/std::ranges::chunk_view::outer-iterator::operator=.3 new file mode 100644 index 000000000..e4ff85ead --- /dev/null +++ b/man/std::ranges::chunk_view::outer-iterator::operator=.3 @@ -0,0 +1,21 @@ +.TH std::ranges::chunk_view::outer-iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::outer-iterator::operator= \- std::ranges::chunk_view::outer-iterator::operator= + +.SH Synopsis + /*outer-iterator*/& operator=( /*outer-iterator*/&& other ) = (since C++23) + default; + + Assigns another iterator. This move assignment operator is generated by the + compiler. + + Moves the underlying pointer other.parent_ to parent_. + +.SH Parameters + + other - an iterator + +.SH See also + + constructor constructs an iterator + (C++23) \fI(public member function)\fP diff --git a/man/std::ranges::chunk_view::outer-iterator::outer-iterator.3 b/man/std::ranges::chunk_view::outer-iterator::outer-iterator.3 new file mode 100644 index 000000000..eb3ce52e1 --- /dev/null +++ b/man/std::ranges::chunk_view::outer-iterator::outer-iterator.3 @@ -0,0 +1,33 @@ +.TH std::ranges::chunk_view::outer-iterator::outer-iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::outer-iterator::outer-iterator \- std::ranges::chunk_view::outer-iterator::outer-iterator + +.SH Synopsis + /*outer-iterator*/( /*outer-iterator*/&& other ) = default; \fB(1)\fP (since C++23) + private: \fB(2)\fP (exposition only*) + constexpr explicit /*outer-iterator*/( chunk_view& parent ); + + Construct an iterator. + + 1) Move constructor. Move-initializes the underlying pointer parent_ with + other.parent_. + 2) A private constructor which is used by chunk_view::begin. This constructor is not + accessible to users. Initializes parent_ with std::addressof(parent). + +.SH Parameters + + other - an iterator + parent - the enclosing ranges::chunk_view object + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= move assigns another iterator + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::chunk_view::outer-iterator::value_type.3 b/man/std::ranges::chunk_view::outer-iterator::value_type.3 new file mode 100644 index 000000000..8cd200659 --- /dev/null +++ b/man/std::ranges::chunk_view::outer-iterator::value_type.3 @@ -0,0 +1,93 @@ +.TH std::ranges::chunk_view::outer-iterator::value_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::outer-iterator::value_type \- std::ranges::chunk_view::outer-iterator::value_type + +.SH Synopsis + Defined in header + struct value_type : view_interface (since C++23) + + A value type of the iterator chunk_view::outer-iterator, formed when V models + input_range. + +.SH Member functions + + constructor constructs an value_type + (C++23) \fI(public member function)\fP + begin returns the beginning chunk_view::inner-iterator + (C++23) \fI(public member function)\fP + end returns the default sentinel + (C++23) \fI(public member function)\fP + size returns the size of the view + (C++23) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::chunk_view::outer-iterator::value_type::value_type + + private: + + // exposition only (since C++23) + + constexpr explicit value_type( chunk_view& parent ); + + Constructs the value_type object so that parent_ is initialized with + std::addressof(parent). + +.SH Parameters + + parent - the chunk_view object + +std::ranges::chunk_view::outer-iterator::value_type::begin + + constexpr /*inner-iterator*/ begin() const noexcept; (since C++23) + + Equivalent to return /*inner-iterator*/(*parent_);. + +std::ranges::chunk_view::outer-iterator::value_type::end + + constexpr std::default_sentinel_t end() const noexcept; (since C++23) + + Equivalent to return std::default_sentinel;. + +std::ranges::chunk_view::outer-iterator::value_type::size + + constexpr auto size() const + requires std::sized_sentinel_for, (since C++23) + ranges::iterator_t>; + + Returns the size of the view. + + Equivalent to + return /*to-unsigned-like*/( + ranges::min(parent_->remainder_, ranges::end(parent_->base_) - + *parent_->current_)); + +.SH Example + + This section is incomplete + Reason: example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.28.4 Class chunk_view::outer-iterator::value_type [range.chunk.outer.value] + +.SH See also + + outer_iterator the output ("chunk-wise") iterator type when V models input_range + (C++23) (exposition-only member class of std::ranges::chunk_view*) + inner_iterator the inner ("element-wise") iterator type when V models input_range + (C++23) (exposition-only member class of std::ranges::chunk_view*) + +.SH Category: + * Todo with reason diff --git a/man/std::ranges::chunk_view::size.3 b/man/std::ranges::chunk_view::size.3 new file mode 100644 index 000000000..2e09f6049 --- /dev/null +++ b/man/std::ranges::chunk_view::size.3 @@ -0,0 +1,43 @@ +.TH std::ranges::chunk_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::chunk_view::size \- std::ranges::chunk_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fB(1)\fP (since C++23) + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP (since C++23) + + Returns the number of elements, which is the smallest integer value that is not less + than the quotient of dividing the size of underlying view base_ by the underlying + data member n_, that holds the number passed to the constructor (0 if default + constructed). Equivalent to + + return __to_unsigned_like(__div_ceil(ranges::distance(base_), n_)); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr static auto v = {1, 2, 3, 4, 5}; + constexpr auto w{ std::ranges::chunk_view(v, 2) }; + static_assert(w.size() == (5 / 2 + (5 % 2 ? 1 : 0))); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::clamp.3 b/man/std::ranges::clamp.3 new file mode 100644 index 000000000..016ac58b4 --- /dev/null +++ b/man/std::ranges::clamp.3 @@ -0,0 +1,170 @@ +.TH std::ranges::clamp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::clamp \- std::ranges::clamp + +.SH Synopsis + Defined in header + Call signature + template< class T, class Proj = std::identity, + + std::indirect_strict_weak_order> + Comp = (since + ranges::less > C++20) + constexpr const T& + + clamp( const T& v, const T& lo, const T& hi, Comp comp = {}, Proj proj + = {} ); + + If the value of v is within [lo, hi], returns v; otherwise returns the nearest + boundary. + + The behavior is undefined if lo is greater than hi. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + v - the value to clamp + lo, hi - the boundaries to clamp v to + comp - the comparison to apply to the projected elements + proj - the projection to apply to v, lo and hi + +.SH Return value + + Reference to lo if the projected value of v is less than the projected value of lo, + reference to hi if the projected value of hi is less than the projected value of v, + otherwise reference to v. + +.SH Complexity + + At most two comparisons and three applications of the projection. + +.SH Possible implementation + + struct clamp_fn + { + template> + Comp = std::ranges::less> + constexpr const T& operator()(const T& v, const T& lo, const T& hi, + Comp comp = {}, Proj proj = {}) const + { + auto&& pv = std::invoke(proj, v); + + if (std::invoke(comp, std::forward(pv), std::invoke(proj, lo))) + return lo; + + if (std::invoke(comp, std::invoke(proj, hi), std::forward(pv))) + return hi; + + return v; + } + }; + + inline constexpr clamp_fn clamp; + +.SH Notes + + + Capturing the result of std::ranges::clamp by reference produces a dangling + reference if one of the parameters is a temporary and that parameter is returned: + + int n = -1; + const int& r = std::ranges::clamp(n, 0, 255); // r is dangling + + If v compares equivalent to either bound, returns a reference to v, not the bound. + + This function should not be used with both a projection the returns by value and + comparator that takes arguments by value unless a move from the projection result + type to the comparator parameter type is equivalent to a copy. If the comparison via + std::invoke would change the result of projection, the behavior is undefined due to + the semantic requirements of std::regular_invocable (subsumed by + std::indirect_strict_weak_order). + + The standard requires that the value category of the result of the projection be + preserved, and proj can only be called on v once, which means that a projection + result that is a prvalue has to be cached and moved from twice for the two calls to + the comparator. + + * libstdc++ does not conform to this and always passes the projection result as an +.SH lvalue. + * libc++ used to run the projection twice, which was corrected in Clang 18. + * MSVC STL used to run the projection twice, which was corrected in VS 2022 17.2. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::literals; + namespace ranges = std::ranges; + + int main() + { + std::cout << "[raw] [" << INT8_MIN << ',' << INT8_MAX << "] " + "[0" << ',' << UINT8_MAX << "]\\n"; + for (int const v : {-129, -128, -1, 0, 42, 127, 128, 255, 256}) + std::cout << std::setw(4) << v + << std::setw(11) << ranges::clamp(v, INT8_MIN, INT8_MAX) + << std::setw(8) << ranges::clamp(v, 0, UINT8_MAX) << '\\n'; + std::cout << std::string(23, '-') << '\\n'; + + // Projection function + const auto stoi = [](std::string s) { return std::stoi(s); }; + + // Same as above, but with strings + for (std::string const v : {"-129", "-128", "-1", "0", "42", + "127", "128", "255", "256"}) + std::cout << std::setw(4) << v + << std::setw(11) << ranges::clamp(v, "-128"s, "127"s, {}, stoi) + << std::setw(8) << ranges::clamp(v, "0"s, "255"s, {}, stoi) + << '\\n'; + } + +.SH Output: + + [raw] [-128,127] [0,255] + -129 -128 0 + -128 -128 0 + -1 -1 0 + 0 0 0 + 42 42 42 + 127 127 127 + 128 127 128 + 255 127 255 + 256 127 255 + ----------------------- + -129 -128 0 + -128 -128 0 + -1 -1 0 + 0 0 0 + 42 42 42 + 127 127 127 + 128 127 128 + 255 127 255 + 256 127 255 + +.SH See also + + ranges::min returns the smaller of the given values + (C++20) (niebloid) + ranges::max returns the greater of the given values + (C++20) (niebloid) + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::common_range.3 b/man/std::ranges::common_range.3 new file mode 100644 index 000000000..edfb2a275 --- /dev/null +++ b/man/std::ranges::common_range.3 @@ -0,0 +1,47 @@ +.TH std::ranges::common_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::common_range \- std::ranges::common_range + +.SH Synopsis + Defined in header + template< class T > + + concept common_range = \fI(since C++20)\fP + + ranges::range && std::same_as, + ranges::sentinel_t>; + + The common_range concept is a refinement of range for which std::ranges::begin() and + std::ranges::end() return the same type (e.g. all standard library containers). + +.SH Example + + +// Run this code + + #include + + struct A { + char* begin(); + char* end(); + }; + static_assert( std::ranges::common_range ); + + struct B { + char* begin(); + bool end(); + }; // not a common_range: begin/end have different types + static_assert( not std::ranges::common_range ); + + struct C { + char* begin(); + }; // not a common_range, not even a range: has no end() + static_assert( not std::ranges::common_range ); + + int main() { } + +.SH See also + + ranges::common_view converts a view into a common_range + views::common \fI(class template)\fP (range adaptor object) + (C++20) diff --git a/man/std::ranges::common_view::base.3 b/man/std::ranges::common_view::base.3 new file mode 100644 index 000000000..9e6b53e15 --- /dev/null +++ b/man/std::ranges::common_view::base.3 @@ -0,0 +1,50 @@ +.TH std::ranges::common_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::common_view::base \- std::ranges::common_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str { "C++20" }; + auto view = std::views::common(str); + + std::string copy_of_str = view.base(); + std::cout << "copy of str: [" << copy_of_str << "]\\n"; + std::cout << "view.base(): [" << view.base() << "]\\n"; + + std::string move_str = std::move(view.base()); + std::cout << "moved str: [" << move_str << "]\\n"; + std::cout << "view.base(): [" << view.base() << "]\\n"; // unspecified + } + +.SH Possible output: + + copy of str: [C++20] + view.base(): [C++20] + moved str: [C++20] + view.base(): [] diff --git a/man/std::ranges::common_view::begin.3 b/man/std::ranges::common_view::begin.3 new file mode 100644 index 000000000..27a3b47dc --- /dev/null +++ b/man/std::ranges::common_view::begin.3 @@ -0,0 +1,67 @@ +.TH std::ranges::common_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::common_view::begin \- std::ranges::common_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__simple_view); \fB(1)\fP \fI(since C++20)\fP + constexpr auto begin() const requires range; \fB(2)\fP \fI(since C++20)\fP + + 1) Returns an iterator to the first element of the common_view, that is: + * ranges::begin(base_), if both ranges::random_access_range and + ranges::sized_range are satisfied, + * std::common_iterator, + ranges::sentinel_t>(ranges::begin(base_)) otherwise. + Here base_ (the name is for exposition only purposes) is the underlying view. + 2) Same as \fB(1)\fP, but V is const-qualified. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the beginning of the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr auto common = std::views::iota(1) + | std::views::take(3) + | std::views::common + ; + + for (int i{}; int e : common) + std::cout << (i++ ? " + " : "") << e; + + std::cout << " = " << std::accumulate(common.begin(), common.end(), 0) << '\\n'; + } + +.SH Output: + + 1 + 2 + 3 = 6 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 4012 C++20 non-const overload missed simple-view check added + +.SH See also + + end returns an iterator to the end + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::common_view::common_view.3 b/man/std::ranges::common_view::common_view.3 new file mode 100644 index 000000000..210b06695 --- /dev/null +++ b/man/std::ranges::common_view::common_view.3 @@ -0,0 +1,34 @@ +.TH std::ranges::common_view::common_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::common_view::common_view \- std::ranges::common_view::common_view + +.SH Synopsis + common_view() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit common_view( V r ); \fB(2)\fP \fI(since C++20)\fP + + Constructs a common_view. + + 1) Default constructor. Value-initializes the underlying view. After construction, + base() returns a copy of V(). + 2) Initializes the underlying view with std::move(r). + +.SH Parameters + + r - underlying view to be adapted into a common-range + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3405 C++20 the redundant converting constructor might removed + cause constraint recursion + +.SH Category: + * Todo no example diff --git a/man/std::ranges::common_view::end.3 b/man/std::ranges::common_view::end.3 new file mode 100644 index 000000000..4d5e32080 --- /dev/null +++ b/man/std::ranges::common_view::end.3 @@ -0,0 +1,70 @@ +.TH std::ranges::common_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::common_view::end \- std::ranges::common_view::end + +.SH Synopsis + constexpr auto end() requires (!__simple_view); \fB(1)\fP \fI(since C++20)\fP + constexpr auto end() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + 1) Returns an iterator representing the end of the common_view, that is: + * ranges::begin(base_) + ranges::size(base_), if both + ranges::random_access_range and ranges::sized_range are satisfied, + * std::common_iterator, + ranges::sentinel_t>(ranges::end(base_)) otherwise. + Here base_ (the name is for exposition purposes only) is the underlying view. + 2) Same as \fB(1)\fP, but V is const-qualified. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator representing the end of the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr int n{4}; + + constexpr auto v1 = std::views::iota(1) + | std::views::take(n) + | std::views::common + ; + constexpr auto v2 = std::views::iota(2) + | std::views::take(n) + ; + const int product = std::inner_product(v1.begin(), v1.end(), + v2.begin(), + 0); + std::cout << product << '\\n'; + } + +.SH Output: + + 40 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 4012 C++20 non-const overload missed simple-view check added + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::common_view::size.3 b/man/std::ranges::common_view::size.3 new file mode 100644 index 000000000..0181e598b --- /dev/null +++ b/man/std::ranges::common_view::size.3 @@ -0,0 +1,49 @@ +.TH std::ranges::common_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::common_view::size \- std::ranges::common_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fB(1)\fP \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP \fI(since C++20)\fP + + Returns the number of elements. + + Equivalent to return ranges::size(base_);, where base_ is the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr static auto v1 = {1, 2, 3, 4, 5}; + constexpr auto common1 { v1 | std::views::common }; + static_assert(common1.size() == 5); + + constexpr auto take3 { v1 | std::views::reverse | std::views::take(3) }; + constexpr auto common2 { take3 | std::views::common }; + static_assert(common2.size() == 3); + + using namespace std::literals; + constexpr static auto v2 = { "∧"sv, "∨"sv, "∃"sv, "∀"sv }; + static_assert(std::ranges::views::common(v2).size() == 4); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::constant_range.3 b/man/std::ranges::constant_range.3 new file mode 100644 index 000000000..d65cf0f74 --- /dev/null +++ b/man/std::ranges::constant_range.3 @@ -0,0 +1,85 @@ +.TH std::ranges::constant_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::constant_range \- std::ranges::constant_range + +.SH Synopsis + Defined in header + template< class T > + + concept constant_range = \fB(1)\fP (since C++23) + ranges::input_range && + + /*constant-iterator*/>; + Helper concepts + template< class T > + + concept /*constant-iterator*/ = + std::input_iterator && \fB(2)\fP (exposition only*) + + std::same_as, + std::iter_reference_t>; + + 1) The constant_range concept is a refinement of range for which ranges::begin + returns a constant iterator. + 2) The exposition-only concept /*constant-iterator*/ is satisfied when the result + of the indirection operation of the input iterator is its const reference type which + implies read-only. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // mechanisms for ensuring the parameter is a constant range + // 1) an overload set where the mutable one defers to the constant one + template + void takes_any_range1(R&& r) + { + // R is definitely a constant range + } + + template + void takes_any_range1(R&& r) + { + takes_any_range1(std::views::as_const(std::forward(r))); + } + + // 2) one function template that shadows its parameter + template + void takes_any_range2(R&& _r) + { + auto r = std::views::as_const(std::forward(_r)); + + // r is definitely a constant range + // never use _r again + } + + // 3) one function template that recursively invokes itself + template + void takes_any_range3(R&& r) + { + if constexpr (std::ranges::constant_range) + { + // R is definitely a constant range + // put implementation here + } + else + takes_any_range3(std::views::as_const(std::forward(r))); + } + + static_assert + ( + std::ranges::constant_range> and + not std::ranges::constant_range> and + std::ranges::constant_range and + not std::ranges::constant_range> and + std::ranges::constant_range> and + not std::ranges::constant_range> + ); + + int main() {} diff --git a/man/std::ranges::construct_at.3 b/man/std::ranges::construct_at.3 new file mode 100644 index 000000000..dc7b80777 --- /dev/null +++ b/man/std::ranges::construct_at.3 @@ -0,0 +1,121 @@ +.TH std::ranges::construct_at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::construct_at \- std::ranges::construct_at + +.SH Synopsis + Defined in header + Call signature + template< class T, class... Args > \fI(since C++20)\fP + constexpr T* construct_at( T* p, Args&&... args ); + + Creates a T object initialized with arguments args... at given address p. + construct_at participates in overload resolution only if + ::new(std::declval()) T(std::declval()...) is well-formed in + unevaluated context. + + Equivalent to + + return ::new (static_cast(p)) T(std::forward(args)...); + + except that construct_at may be used in evaluation of constant expressions. + + When construct_at is called in the evaluation of some constant expression e, the + argument p must point to either storage obtained by std::allocator::allocate or + an object whose lifetime began within the evaluation of e. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + p - pointer to the uninitialized storage on which a T object will be + constructed + args... - arguments used for initialization + +.SH Return value + + p + +.SH Possible implementation + + struct construct_at_fn + { + template + requires + requires (void* vp, Args&&... args) + { ::new (vp) T(static_cast(args)...); } + constexpr T* operator()(T* p, Args&&... args) const + { + return std::construct_at(p, static_cast(args)...); + } + }; + + inline constexpr construct_at_fn construct_at{}; + +.SH Notes + + std::ranges::construct_at behaves exactly same as std::construct_at, except that it + is invisible to argument-dependent lookup. + +.SH Example + + +// Run this code + + #include + #include + + struct S + { + int x; + float y; + double z; + + S(int x, float y, double z) : x{x}, y{y}, z{z} { std::cout << "S::S();\\n"; } + + ~S() { std::cout << "S::~S();\\n"; } + + void print() const + { + std::cout << "S { x=" << x << "; y=" << y << "; z=" << z << "; };\\n"; + } + }; + + int main() + { + alignas(S) unsigned char buf[sizeof(S)]; + + S* ptr = std::ranges::construct_at(reinterpret_cast(buf), 42, 2.71828f, 3.1415); + ptr->print(); + + std::ranges::destroy_at(ptr); + } + +.SH Output: + + S::S(); + S { x=42; y=2.71828; z=3.1415; }; + S::~S(); + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 construct_at could create objects only cv-unqualified types are + of a cv-qualified types permitted + +.SH See also + + ranges::destroy_at destroys an object at a given address + (C++20) (niebloid) + construct_at creates an object at a given address + (C++20) \fI(function template)\fP diff --git a/man/std::ranges::contains,std::ranges::contains_subrange.3 b/man/std::ranges::contains,std::ranges::contains_subrange.3 new file mode 100644 index 000000000..9818c09f0 --- /dev/null +++ b/man/std::ranges::contains,std::ranges::contains_subrange.3 @@ -0,0 +1,251 @@ +.TH std::ranges::contains,std::ranges::contains_subrange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::contains,std::ranges::contains_subrange \- std::ranges::contains,std::ranges::contains_subrange + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + class T, + class Proj = std::identity > (since + requires std::indirect_binary_predicate, (until + const T*> C++26) + + constexpr bool contains( I first, S last, const T& value, + Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t > + requires std::indirect_binary_predicate, C++26) + const T*> + + constexpr bool contains( I first, S last, const T& value, + Proj proj = {} ); + template< ranges::input_range R, + + class T, + class Proj = std::identity > (since + requires std::indirect_binary_predicate, Proj>, C++26) + const T*> + + constexpr bool contains( R&& r, const T& value, Proj proj = + {} ); + template< ranges::input_range R, + + class Proj = std::identity, + class T = + std::projected_value_t, Proj> > + requires std::indirect_binary_predicate, Proj>, + const T*> + + constexpr bool contains( R&& r, const T& value, Proj proj = + {} ); + template< std::forward_iterator I1, std::sentinel_for + S1, + + std::forward_iterator I2, std::sentinel_for \fB(2)\fP + S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = + std::identity > \fB(3)\fP (since + requires std::indirectly_comparable + constexpr bool contains_subrange( I1 first1, S1 last1, I2 + first2, S2 last2, + Pred pred = {}, + + Proj1 proj1 = {}, Proj2 + proj2 = {} ); + template< ranges::forward_range R1, ranges::forward_range + R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = + std::identity > + requires std::indirectly_comparable, \fB(4)\fP (since + ranges::iterator_t, C++23) + Pred, Proj1, Proj2> + constexpr bool contains_subrange( R1&& r1, R2&& r2, Pred + pred = {}, + + Proj1 proj1 = {}, Proj2 + proj2 = {} ); + + 1) Search-based algorithm that checks whether or not a given range contains a value + with iterator-sentinel pairs. + 2) Same as \fB(1)\fP but uses r as the source range, as if using ranges::begin(r) as first + and ranges::end(r) as last. + 3) Search-based algorithm that checks whether or not a given range is a subrange of + another range with iterator-sentinel pairs. + 4) Same as \fB(3)\fP but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of the elements to examine + value - value to compare the elements to + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1,2) : ranges::find(std::move(first), last, value, proj) != last + 3,4) : first2 == last2 || !ranges::search(first1, last1, first2, last2, pred, proj1, + proj2).empty() + +.SH Complexity + + At most last - first applications of the predicate and projection. + +.SH Notes + + Up until C++20, we've had to write std::ranges::find(r, value) != + std::ranges::end(r) to determine if a single value is inside a range. And to check + if a range contains a subrange of interest, we use not std::ranges::search(haystack, + needle).empty(). While this is accurate, it isn't necessarily convenient, and it + hardly expresses intent (especially in the latter case). Being able to say + std::ranges::contains(r, value) addresses both of these points. + + ranges::contains_subrange, same as ranges::search, but as opposed to std::search, + provides no access to Searchers (such as Boyer-Moore). + + Feature-test macro Value Std Feature + __cpp_lib_ranges_contains 202207L (C++23) std::ranges::contains and + ranges::contains_subrange + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Possible implementation + + contains (1,2) + struct __contains_fn + { + template S, + class Proj = std::identity, + class T = std::projected_value_t> + requires std::indirect_binary_predicate, + const T*> + constexpr bool operator()(I first, S last, const T& value, Proj proj = {}) const + { + return ranges::find(std::move(first), last, value, proj) != last; + } + + template, Proj>> + requires std::indirect_binary_predicate, Proj>, + const T*> + constexpr bool operator()(R&& r, const T& value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(value), proj); + } + }; + + inline constexpr __contains_fn contains {}; + contains_subrange (3,4) + struct __contains_subrange_fn + { + template S1, + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr bool operator()(I1 first1, S1 last1, + I2 first2, S2 last2, + Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (first2 == last2) || + !ranges::search(first1, last1, first2, last2, pred, proj1, proj2).empty(); + } + + template + requires std::indirectly_comparable, + ranges::iterator_t, Pred, Proj1, Proj2> + constexpr bool operator()(R1&& r1, R2&& r2, + Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), std::move(pred), + std::move(proj1), std::move(proj2)); + } + }; + + inline constexpr __contains_subrange_fn contains_subrange {}; + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace ranges = std::ranges; + + int main() + { + constexpr auto haystack = std::array{3, 1, 4, 1, 5}; + constexpr auto needle = std::array{1, 4, 1}; + constexpr auto bodkin = std::array{2, 5, 2}; + + static_assert( + ranges::contains(haystack, 4) && + !ranges::contains(haystack, 6) && + ranges::contains_subrange(haystack, needle) && + !ranges::contains_subrange(haystack, bodkin) + ); + + constexpr std::array, 3> nums{{{1, 2}, {3, 4}, {5, 6}}}; + #ifdef __cpp_lib_algorithm_default_value_type + static_assert(ranges::contains(nums, {3, 4})); + #else + static_assert(ranges::contains(nums, std::complex{3, 4})); + #endif + } + +.SH See also + + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::search searches for a range of elements + (C++20) (niebloid) + ranges::binary_search determines if an element exists in a partially-ordered range + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of another + (C++20) (niebloid) + ranges::all_of + ranges::any_of checks if a predicate is true for all, any or none of the + ranges::none_of elements in a range + (C++20) (niebloid) + (C++20) + (C++20) diff --git a/man/std::ranges::contiguous_range.3 b/man/std::ranges::contiguous_range.3 new file mode 100644 index 000000000..a36dfb37f --- /dev/null +++ b/man/std::ranges::contiguous_range.3 @@ -0,0 +1,63 @@ +.TH std::ranges::contiguous_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::contiguous_range \- std::ranges::contiguous_range + +.SH Synopsis + Defined in header + template< class T > + + concept contiguous_range = + ranges::random_access_range && + std::contiguous_iterator> && (since + requires(T& t) { C++20) + { ranges::data(t) } -> + std::same_as>>; + + }; + + The contiguous_range concept is a refinement of range for which ranges::begin + returns a model of contiguous_iterator and the customization point ranges::data is + usable. + + Semantic requirements + + T models contiguous_range only if given an expression e such that decltype((e)) is + T&, std::to_address(ranges::begin(e)) == ranges::data(e). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template concept CR = std::ranges::contiguous_range; + + int main() + { + int a[4]; + static_assert( + CR> and + not CR> and + not CR> and + CR> and + CR and + not CR> and + not CR> and + CR,42>> + ); + } + +.SH See also + + ranges::sized_range specifies that a range knows its size in constant time + (C++20) (concept) + ranges::random_access_range specifies a range whose iterator type satisfies + (C++20) random_access_iterator + (concept) diff --git a/man/std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result,.3 b/man/std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result,.3 new file mode 100644 index 000000000..b23cff8dc --- /dev/null +++ b/man/std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result,.3 @@ -0,0 +1,222 @@ +.TH std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result, \- std::ranges::copy,std::ranges::copy_if,std::ranges::copy_result, + +.SH Synopsis + + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + std::weakly_incrementable O > + + requires std::indirectly_copyable \fB(1)\fP \fI(since C++20)\fP + constexpr copy_result + + copy( I first, S last, O result ); + template< ranges::input_range R, std::weakly_incrementable O > + + requires std::indirectly_copyable, O> \fB(2)\fP \fI(since C++20)\fP + constexpr copy_result, O> + + copy( R&& r, O result ); + template< std::input_iterator I, std::sentinel_for S, + std::weakly_incrementable O, + + class Proj = std::identity, + std::indirect_unary_predicate> + Pred > \fB(3)\fP \fI(since C++20)\fP + requires std::indirectly_copyable + constexpr copy_if_result + + copy_if( I first, S last, O result, Pred pred, Proj proj = {} + ); + template< ranges::input_range R, std::weakly_incrementable O, + + class Proj = std::identity, + std::indirect_unary_predicate< + std::projected, Proj>> Pred > \fB(4)\fP \fI(since C++20)\fP + requires std::indirectly_copyable, O> + constexpr copy_if_result, O> + + copy_if( R&& r, O result, Pred pred, Proj proj = {} ); +.SH Helper types + template< class I, class O > \fB(5)\fP \fI(since C++20)\fP + using copy_result = ranges::in_out_result; + template< class I, class O > \fB(6)\fP \fI(since C++20)\fP + using copy_if_result = ranges::in_out_result; + + Copies the elements in the range, defined by [first, last), to another range + beginning at result. + + 1) Copies all elements in the range [first, last) starting from first and proceeding + to last - 1. The behavior is undefined if result is within the range [first, last). + In this case, ranges::copy_backward may be used instead. + 3) Only copies the elements for which the predicate pred returns true. The relative + order of the elements that are copied is preserved. The behavior is undefined if the + source and the destination ranges overlap. + 2,4) Same as (1,3), but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to copy + r - the range of elements to copy + result - the beginning of the destination range. + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + A ranges::in_out_result containing an input iterator equal to last and an output + iterator past the last element copied. + +.SH Complexity + + 1,2) Exactly last - first assignments. + 3,4) Exactly last - first applications of the predicate and projection, between 0 + and last - first assignments (assignment for every element for which predicate + returns true, dependent on predicate and input data). + +.SH Notes + + In practice, implementations of ranges::copy avoid multiple assignments and use bulk + copy functions such as std::memmove if the value type is TriviallyCopyable and the + iterator types satisfy contiguous_iterator. + + When copying overlapping ranges, ranges::copy is appropriate when copying to the + left (beginning of the destination range is outside the source range) while + ranges::copy_backward is appropriate when copying to the right (end of the + destination range is outside the source range). + +.SH Possible implementation + + copy + struct copy_fn + { + template S, std::weakly_incrementable O> + requires std::indirectly_copyable + constexpr ranges::copy_result operator()(I first, S last, O result) const + { + for (; first != last; ++first, (void)++result) + *result = *first; + return {std::move(first), std::move(result)}; + } + + template + requires std::indirectly_copyable, O> + constexpr ranges::copy_result, O> + operator()(R&& r, O result) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result)); + } + }; + + inline constexpr copy_fn copy; + copy_if + struct copy_if_fn + { + template S, std::weakly_incrementable O, + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + requires std::indirectly_copyable + constexpr ranges::copy_if_result + operator()(I first, S last, O result, Pred pred, Proj proj = {}) const + { + for (; first != last; ++first) + if (std::invoke(pred, std::invoke(proj, *first))) + { + *result = *first; + ++result; + } + return {std::move(first), std::move(result)}; + } + + template, Proj>> Pred> + requires std::indirectly_copyable, O> + constexpr ranges::copy_if_result, O> + operator()(R&& r, O result, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::move(result), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr copy_if_fn copy_if; + +.SH Example + + The following code uses ranges::copy to both copy the contents of one std::vector to + another and to display the resulting std::vector: + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector source(10); + std::iota(source.begin(), source.end(), 0); + + std::vector destination; + + std::ranges::copy(source.begin(), source.end(), + std::back_inserter(destination)); + // or, alternatively, + // std::vector destination(source.size()); + // std::ranges::copy(source.begin(), source.end(), destination.begin()); + // either way is equivalent to + // std::vector destination = source; + + std::cout << "destination contains: "; + + std::ranges::copy(destination, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + + std::cout << "odd numbers in destination are: "; + + std::ranges::copy_if(destination, std::ostream_iterator(std::cout, " "), + [](int x) { return (x % 2) == 1; }); + std::cout << '\\n'; + } + +.SH Output: + + destination contains: 0 1 2 3 4 5 6 7 8 9 + odd numbers in destination are: 1 3 5 7 9 + +.SH See also + + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP diff --git a/man/std::ranges::copy_backward,std::ranges::copy_backward_result.3 b/man/std::ranges::copy_backward,std::ranges::copy_backward_result.3 new file mode 100644 index 000000000..578084370 --- /dev/null +++ b/man/std::ranges::copy_backward,std::ranges::copy_backward_result.3 @@ -0,0 +1,166 @@ +.TH std::ranges::copy_backward,std::ranges::copy_backward_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::copy_backward,std::ranges::copy_backward_result \- std::ranges::copy_backward,std::ranges::copy_backward_result + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I1, std::sentinel_for S1, + + std::bidirectional_iterator I2 > (since + requires std::indirectly_copyable \fB(1)\fP C++20) + constexpr copy_backward_result + + copy_backward( I1 first, S1 last, I2 result ); + template< ranges::bidirectional_range R, std::bidirectional_iterator I > + + requires std::indirectly_copyable, I> \fB(2)\fP (since + constexpr copy_backward_result, I> C++20) + + copy_backward( R&& r, I result ); +.SH Helper types + template< class I1, class I2 > \fB(3)\fP (since + using copy_backward_result = ranges::in_out_result; C++20) + + 1) Copies the elements from the range, defined by [first, last), to another range + [result - N, result), where N = ranges::distance(first, last). The elements are + copied in reverse order (the last element is copied first), but their relative order + is preserved. The behavior is undefined if result is within (first, last]. In such a + case std::ranges::copy can be used instead. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to copy from + last - the end of the range of elements to copy from + r - the range of the elements to copy from + result - the end of the destination range + +.SH Return value + + {last, result - N} + +.SH Complexity + + Exactly N assignments. + +.SH Notes + + When copying overlapping ranges, ranges::copy is appropriate when copying to the + left (beginning of the destination range is outside the source range) while + ranges::copy_backward is appropriate when copying to the right (end of the + destination range is outside the source range). + +.SH Possible implementation + + struct copy_backward_fn + { + template S1, + std::bidirectional_iterator I2> + requires std::indirectly_copyable + constexpr ranges::copy_backward_result + operator()(I1 first, S1 last, I2 result) const + { + I1 last1 {ranges::next(first, std::move(last))}; + for (I1 i {last1}; i != first;) + *--result = *--i; + return {std::move(last1), std::move(result)}; + } + + template + requires std::indirectly_copyable, I> + constexpr ranges::copy_backward_result, I> + operator()(R&& r, I result) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result)); + } + }; + + inline constexpr copy_backward_fn copy_backward{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(std::string_view rem, std::ranges::forward_range auto const& r) + { + for (std::cout << rem << ": "; auto const& elem : r) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + const auto src = {1, 2, 3, 4}; + print("src", src); + + std::vector dst(src.size() + 2); + std::ranges::copy_backward(src, dst.end()); + print("dst", dst); + + std::ranges::fill(dst, 0); + const auto [in, out] = + std::ranges::copy_backward(src.begin(), src.end() - 2, dst.end()); + print("dst", dst); + + std::cout + << "(in - src.begin) == " << std::distance(src.begin(), in) << '\\n' + << "(out - dst.begin) == " << std::distance(dst.begin(), out) << '\\n'; + } + +.SH Output: + + src: 1 2 3 4 + dst: 0 0 1 2 3 4 + dst: 0 0 0 0 1 2 + (in - src.begin) == 2 + (out - dst.begin) == 4 + +.SH See also + + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) + ranges::replace_copy copies a range, replacing elements satisfying specific + ranges::replace_copy_if criteria with another value + (C++20) (niebloid) + (C++20) + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) + ranges::rotate_copy copies and rotate a range of elements + (C++20) (niebloid) + ranges::unique_copy creates a copy of some range of elements that contains no + (C++20) consecutive duplicates + (niebloid) + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards + (C++20) order + (niebloid) + copy_backward copies a range of elements in backwards order + \fI(function template)\fP diff --git a/man/std::ranges::copy_n,std::ranges::copy_n_result.3 b/man/std::ranges::copy_n,std::ranges::copy_n_result.3 new file mode 100644 index 000000000..5a1affc2b --- /dev/null +++ b/man/std::ranges::copy_n,std::ranges::copy_n_result.3 @@ -0,0 +1,143 @@ +.TH std::ranges::copy_n,std::ranges::copy_n_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::copy_n,std::ranges::copy_n_result \- std::ranges::copy_n,std::ranges::copy_n_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::weakly_incrementable O > + + requires std::indirectly_copyable \fB(1)\fP \fI(since C++20)\fP + constexpr copy_n_result + + copy_n( I first, std::iter_difference_t n, O result ); + Helper type + template< class I, class O > \fB(2)\fP \fI(since C++20)\fP + using copy_n_result = ranges::in_out_result; + + 1) Copies exactly n values from the range beginning at first to the range beginning + at result by performing *(result + i) = *(first + i) for each integer in [0, n). The + behavior is undefined if result is within the range [first, first + n) + (ranges::copy_backward might be used instead in this case). + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to copy from + n - number of the elements to copy + result - the beginning of the destination range + +.SH Return value + + ranges::copy_n_result{first + n, result + n} or more formally, a value of type + ranges::in_out_result that contains an std::input_iterator iterator equals to + ranges::next(first, n) and a std::weakly_incrementable iterator equals to + ranges::next(result, n). + +.SH Complexity + + Exactly n assignments. + +.SH Notes + + In practice, implementations of std::ranges::copy_n may avoid multiple assignments + and use bulk copy functions such as std::memmove if the value type is + TriviallyCopyable and the iterator types satisfy contiguous_iterator. Alternatively, + such copy acceleration can be injected during an optimization phase of a compiler. + + When copying overlapping ranges, std::ranges::copy_n is appropriate when copying to + the left (beginning of the destination range is outside the source range) while + std::ranges::copy_backward is appropriate when copying to the right (end of the + destination range is outside the source range). + +.SH Possible implementation + + struct copy_n_fn + { + template + requires std::indirectly_copyable + constexpr ranges::copy_n_result + operator()(I first, std::iter_difference_t n, O result) const + { + for (std::iter_difference_t i {}; i != n; ++i, ++first, ++result) + *result = *first; + return {std::move(first), std::move(result)}; + } + }; + + inline constexpr copy_n_fn copy_n {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + const std::string_view in {"ABCDEFGH"}; + std::string out; + + std::ranges::copy_n(in.begin(), 4, std::back_inserter(out)); + std::cout << std::quoted(out) << '\\n'; + + out = "abcdefgh"; + const auto res = std::ranges::copy_n(in.begin(), 5, out.begin()); + std::cout + << "*(res.in): '" << *(res.in) << "', distance: " + << std::distance(std::begin(in), res.in) << '\\n' + << "*(res.out): '" << *(res.out) << "', distance: " + << std::distance(std::begin(out), res.out) << '\\n'; + } + +.SH Output: + + "ABCD" + *(res.in): 'F', distance: 5 + *(res.out): 'f', distance: 5 + +.SH See also + + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) + ranges::replace_copy copies a range, replacing elements satisfying specific + ranges::replace_copy_if criteria with another value + (C++20) (niebloid) + (C++20) + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) + ranges::rotate_copy copies and rotate a range of elements + (C++20) (niebloid) + ranges::unique_copy creates a copy of some range of elements that contains no + (C++20) consecutive duplicates + (niebloid) + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards + (C++20) order + (niebloid) + copy_n copies a number of elements to a new location + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::count,std::ranges::count_if.3 b/man/std::ranges::count,std::ranges::count_if.3 new file mode 100644 index 000000000..feb05a848 --- /dev/null +++ b/man/std::ranges::count,std::ranges::count_if.3 @@ -0,0 +1,231 @@ +.TH std::ranges::count,std::ranges::count_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::count,std::ranges::count_if \- std::ranges::count,std::ranges::count_if + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + class T, class Proj = std::identity > + requires std::indirect_binary_predicate (since + , C++20) + const T*> (until + constexpr std::iter_difference_t C++26) + + count( I first, S last, const T& value, Proj proj = {} + ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t > + requires std::indirect_binary_predicate (since + , C++26) + const T*> + constexpr std::iter_difference_t + + count( I first, S last, const T& value, Proj proj = {} + ); + template< ranges::input_range R, class T, class Proj = + std::identity > + + requires std::indirect_binary_predicate (since + , Proj>, (until + const T*> C++26) + constexpr ranges::range_difference_t \fB(1)\fP + + count( R&& r, const T& value, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + class T = + std::projected_value_t, Proj> > + requires std::indirect_binary_predicate (since + , Proj>, + const T*> + constexpr ranges::range_difference_t \fB(2)\fP + + count( R&& r, const T& value, Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> Pred > C++20) + constexpr std::iter_difference_t + + count_if( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate< + std::projected, Proj>> \fB(4)\fP (since + Pred > C++20) + constexpr ranges::range_difference_t + + count_if( R&& r, Pred pred, Proj proj = {} ); + + Returns the number of elements in the range [first, last) satisfying specific + criteria. + + 1) Counts the elements that are equal to value. + 3) Counts elements for which predicate p returns true. + 2,4) Same as (1,3), but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of the elements to examine + value - the value to search for + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Number of elements satisfying the condition. + +.SH Complexity + + Exactly last - first comparisons and projection. + +.SH Notes + + For the number of elements in the range without any additional criteria, see + std::ranges::distance. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Possible implementation + + count \fB(1)\fP + struct count_fn + { + template S, + class Proj = std::identity, class T = std::projected_value_t> + requires std::indirect_binary_predicate, const T*> + constexpr std::iter_difference_t + operator()(I first, S last, const T& value, Proj proj = {}) const + { + std::iter_difference_t counter = 0; + for (; first != last; ++first) + if (std::invoke(proj, *first) == value) + ++counter; + return counter; + } + + template, Proj>> + requires std::indirect_binary_predicate, Proj>, + const T*> + constexpr ranges::range_difference_t + operator()(R&& r, const T& value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, std::ref(proj)); + } + }; + + inline constexpr count_fn count; + count_if \fB(3)\fP + struct count_if_fn + { + template S, + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr std::iter_difference_t + operator()(I first, S last, Pred pred, Proj proj = {}) const + { + std::iter_difference_t counter = 0; + for (; first != last; ++first) + if (std::invoke(pred, std::invoke(proj, *first))) + ++counter; + return counter; + } + + template, Proj>> Pred> + constexpr ranges::range_difference_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr count_if_fn count_if; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector v{1, 2, 3, 4, 4, 3, 7, 8, 9, 10}; + + namespace ranges = std::ranges; + + // determine how many integers in a std::vector match a target value. + int target1 = 3; + int target2 = 5; + int num_items1 = ranges::count(v.begin(), v.end(), target1); + int num_items2 = ranges::count(v, target2); + std::cout << "number: " << target1 << " count: " << num_items1 << '\\n'; + std::cout << "number: " << target2 << " count: " << num_items2 << '\\n'; + + // use a lambda expression to count elements divisible by 3. + int num_items3 = ranges::count_if(v.begin(), v.end(), [](int i){ return i % 3 == 0; }); + std::cout << "number divisible by three: " << num_items3 << '\\n'; + + // use a lambda expression to count elements divisible by 11. + int num_items11 = ranges::count_if(v, [](int i){ return i % 11 == 0; }); + std::cout << "number divisible by eleven: " << num_items11 << '\\n'; + + std::vector> nums{{4, 2}, {1, 3}, {4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto c = ranges::count(nums, {4, 2}); + #else + auto c = ranges::count(nums, std::complex{4, 2}); + #endif + assert(c == 2); + } + +.SH Output: + + number: 3 count: 2 + number: 5 count: 0 + number divisible by three: 3 + number divisible by eleven: 0 + +.SH See also + + ranges::distance returns the distance between an iterator and a sentinel, or + (C++20) between the beginning and end of a range + (niebloid) + views::counted creates a subrange from an iterator and a count + (C++20) (customization point object) + ranges::filter_view a view that consists of the elements of a range that satisfies a + views::filter predicate + (C++20) \fI(class template)\fP (range adaptor object) + count returns the number of elements satisfying specific criteria + count_if \fI(function template)\fP diff --git a/man/std::ranges::crbegin.3 b/man/std::ranges::crbegin.3 new file mode 100644 index 000000000..236738e7e --- /dev/null +++ b/man/std::ranges::crbegin.3 @@ -0,0 +1,114 @@ +.TH std::ranges::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::crbegin \- std::ranges::crbegin + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ crbegin = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ auto crbegin( T&& t ); + + Returns an iterator to the first element of the const-qualified (until C++23) + argument that is treated as a reversed sequence. + Returns a constant iterator to the first element of the argument that (since C++23) + is treated as a reversed sequence. + + range-rbegin-rend.svg + + Let CT be + + * const std::remove_reference_t& if the argument is an lvalue (i.e. T is + an lvalue reference type), (until + * const T otherwise. C++23) + + A call to ranges::crbegin is expression-equivalent to + ranges::rbegin(static_cast(t)). + If the argument is an lvalue or + ranges::enable_borrowed_range> is true, then a call to + ranges::crbegin is expression-equivalent to: + + * std::const_iterator(U) for some expression U equivalent to (since + ranges::rbegin(/*possibly-const-range*/(t)). C++23) + + In all other cases, a call to ranges::crbegin is ill-formed, which can result + in substitution failure when the call appears in the immediate context of a + template instantiation. + + The return type models std::input_or_output_iterator + and constant-iterator + (since C++23) in all cases. + + Customization point objects + + The name ranges::crbegin denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __crbegin_fn. + + All instances of __crbegin_fn are equal. The effects of invoking different instances + of type __crbegin_fn on the same arguments are equivalent, regardless of whether the + expression denoting the instance is an lvalue or rvalue, and is const-qualified or + not (however, a volatile-qualified instance is not required to be invocable). Thus, + ranges::crbegin can be copied freely and its copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::crbegin above, __crbegin_fn models + + * std::invocable<__crbegin_fn, Args...>, + * std::invocable, + * std::invocable<__crbegin_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __crbegin_fn participates in overload + resolution. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v{3, 1, 4}; + auto vi = std::ranges::crbegin(v); + assert(*vi == 4); + ++vi; // OK, iterator object is mutable + assert(*vi == 1); + // *vi = 13; // Error: underlying element is read-only + + int a[]{-5, 10, 15}; + auto ai = std::ranges::crbegin(a); + assert(*ai == 15); + + // auto x_x = std::ranges::crbegin(std::vector{6, 6, 6}); + // ill-formed: the argument is an rvalue (see Notes ↑) + + auto si = std::ranges::crbegin(std::span{a}); // OK + assert(*si == 15); + static_assert + ( + std::ranges::enable_borrowed_range> + ); + } + +.SH See also + + ranges::rbegin returns a reverse iterator to a range + (C++20) (customization point object) + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::crend.3 b/man/std::ranges::crend.3 new file mode 100644 index 000000000..86e5331bf --- /dev/null +++ b/man/std::ranges::crend.3 @@ -0,0 +1,115 @@ +.TH std::ranges::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::crend \- std::ranges::crend + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ crend = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ auto crend( T&& t ); + + Returns a sentinel + for the constant iterator + (since C++23) indicating the end of a + const-qualified + (until C++23) range that is treated as a reversed sequence. + + range-rbegin-rend.svg + + Let CT be + + * const std::remove_reference_t& if the argument is an lvalue (i.e. T is + an lvalue reference type), (until + * const T otherwise. C++23) + + A call to ranges::crend is expression-equivalent to + ranges::rend(static_cast(t)). + If the argument is an lvalue or + ranges::enable_borrowed_range> is true, then a call to + ranges::crend is expression-equivalent to: + + * std::const_sentinel(U) for some expression U equivalent to (since + ranges::rend(/*possibly-const-range*/(t)). C++23) + + In all other cases, a call to ranges::crend is ill-formed, which can result + in substitution failure when the call appears in the immediate context of a + template instantiation. + + If ranges::crend(e) is valid for an expression e, where decltype((e)) is T, then + CT models std::ranges::range, and + (until C++23) std::sentinel_for is true in all cases, where S is + decltype(ranges::crend(e)), and I is decltype(ranges::crbegin(e)). + Additionally, S models constant-iterator if it models input_iterator. + (since C++23) + + Customization point objects + + The name ranges::crend denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __crend_fn. + + All instances of __crend_fn are equal. The effects of invoking different instances + of type __crend_fn on the same arguments are equivalent, regardless of whether the + expression denoting the instance is an lvalue or rvalue, and is const-qualified or + not (however, a volatile-qualified instance is not required to be invocable). Thus, + ranges::crend can be copied freely and its copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::crend above, __crend_fn models + + * std::invocable<__crend_fn, Args...>, + * std::invocable, + * std::invocable<__crend_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __crend_fn participates in overload + resolution. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + int a[]{4, 6, -3, 9, 10}; + std::cout << "Array backwards: "; + namespace ranges = std::ranges; + ranges::copy(ranges::rbegin(a), ranges::rend(a), + std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + + std::cout << "Vector backwards: "; + std::vector v{4, 6, -3, 9, 10}; + ranges::copy(ranges::rbegin(v), ranges::rend(v), + std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + +.SH Output: + + Array backwards: 10 9 -3 6 4 + Vector backwards: 10 9 -3 6 4 + +.SH See also + + ranges::rend returns a reverse end iterator to a range + (C++20) (customization point object) + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::dangling.3 b/man/std::ranges::dangling.3 new file mode 100644 index 000000000..dcdcc1e01 --- /dev/null +++ b/man/std::ranges::dangling.3 @@ -0,0 +1,80 @@ +.TH std::ranges::dangling 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::dangling \- std::ranges::dangling + +.SH Synopsis + Defined in header + struct dangling; \fI(since C++20)\fP + + dangling is a placeholder type and an empty class type, used together with the + template aliases ranges::borrowed_iterator_t and ranges::borrowed_subrange_t. + + When some constrained algorithms that usually return an iterator or a subrange of a + range take a particular rvalue range argument that does not model borrowed_range, + dangling will be returned instead to avoid returning potentially dangling results. + +.SH Member functions + +std::ranges::dangling::dangling + + constexpr dangling() noexcept = default; \fB(1)\fP + template \fB(2)\fP + constexpr dangling(Args&&...) noexcept { } + + 1) dangling is trivially default constructible. + 2) dangling can be constructed from arguments of arbitrary number and arbitrary + non-void type. The construction does not have any side-effect itself. + + In other words, after replacing the type (e.g. an iterator type) in a well-formed + non-aggregate initialization with dangling, the resulting initialization is also + well-formed. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto get_array_by_value = [] { return std::array{0, 1, 0, 1}; }; + auto dangling_iter = std::ranges::max_element(get_array_by_value()); + static_assert(std::is_same_v); + // std::cout << *dangling_iter << '\\n'; // compilation error: no match for 'operator*' + // (operand type is 'std::ranges::dangling') + + auto get_persistent_array = []() -> const std::array& { + static constexpr std::array a{0, 1, 0, 1}; + return a; + }; + auto valid_iter = std::ranges::max_element(get_persistent_array()); + static_assert(!std::is_same_v); + std::cout << *valid_iter << ' '; // 1 + + + auto get_string_view = [] { return std::string_view{"alpha"}; }; + auto valid_iter2 = std::ranges::min_element(get_string_view()); + // OK: std::basic_string_view models borrowed_range + static_assert(!std::is_same_v); + std::cout << '\\'' << *valid_iter2 << '\\'' << '\\n'; // 'a' + } + +.SH Output: + + 1 'a' + +.SH See also + + ranges::borrowed_iterator_t obtains iterator type or subrange type of a + ranges::borrowed_subrange_t borrowed_range + (C++20) (alias template) + specifies that a type is a range and iterators obtained + ranges::borrowed_range from an expression of it can be safely returned without + (C++20) danger of dangling + (concept) diff --git a/man/std::ranges::data.3 b/man/std::ranges::data.3 new file mode 100644 index 000000000..7c2e486f4 --- /dev/null +++ b/man/std::ranges::data.3 @@ -0,0 +1,88 @@ +.TH std::ranges::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::data \- std::ranges::data + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ data = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + constexpr std::remove_reference_t< + + ranges::range_reference_t>* data( T&& t ); + + Returns a pointer to the first element of a contiguous range. + + If T is an array type and std::remove_all_extents_t> is + incomplete, then the call to ranges::data is ill-formed, no diagnostic required. + + If the argument is an lvalue or ranges::enable_borrowed_range> + is true, a call to ranges::data is expression-equivalent to: + + 1. decay-copy(t.data()) + (until C++23) + auto(t.data()) + (since C++23), if that expression is valid and its type is a pointer to an + object type. + 2. Otherwise, std::to_address(ranges::begin(t)), if the expression ranges::begin(t) + is valid and its type models std::contiguous_iterator. + + In all other cases, a call to ranges::data is ill-formed, which can result in + substitution failure when ranges::data(e) appears in the immediate context of a + template instantiation. + +.SH Notes + + If the argument is an rvalue (i.e. T is an object type) and + ranges::enable_borrowed_range> is false, the call to + ranges::data is ill-formed, which also results in substitution failure. + + If ranges::data(e) is valid for an expression e, then it returns a pointer to an + object. + + The C++20 standard requires that if the underlying data function call returns a + prvalue, the return value is move-constructed from the materialized temporary + object. All implementations directly return the prvalue instead. The requirement is + corrected by the post-C++20 proposal P0849R8 to match the implementations. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s{"Hello world!\\n"}; + + char a[20]; // storage for a C-style string + std::strcpy(a, std::ranges::data(s)); + // [data(s), data(s) + size(s)] is guaranteed to be an NTBS + + std::cout << a; + } + +.SH Output: + + Hello world! + +.SH See also + + ranges::cdata obtains a pointer to the beginning of a read-only contiguous range + (C++20) (customization point object) + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::destroy.3 b/man/std::ranges::destroy.3 new file mode 100644 index 000000000..0f04a4ced --- /dev/null +++ b/man/std::ranges::destroy.3 @@ -0,0 +1,123 @@ +.TH std::ranges::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::destroy \- std::ranges::destroy + +.SH Synopsis + Defined in header + Call signature + template< no-throw-input-iterator I, no-throw-sentinel-for S > + + requires std::destructible> \fB(1)\fP \fI(since C++20)\fP + + constexpr I destroy( I first, S last ) noexcept; + template< no-throw-input-range R > + + requires std::destructible> \fB(2)\fP \fI(since C++20)\fP + + constexpr ranges::borrowed_iterator_t destroy( R&& r ) + noexcept; + + 1) Destroys the objects in the range [first, last), as if by + + for (; first != last; ++first) + std::ranges::destroy_at(std::addressof(*first)); + return first; + + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range of elements to destroy + r - the range to destroy + +.SH Return value + + An iterator compares equal to last. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Possible implementation + + struct destroy_fn + { + template S> + requires std::destructible> + constexpr I operator()(I first, S last) const noexcept + { + for (; first != last; ++first) + std::ranges::destroy_at(std::addressof(*first)); + return first; + } + + template + requires std::destructible> + constexpr std::ranges::borrowed_iterator_t operator()(R&& r) const noexcept + { + return operator()(std::ranges::begin(r), std::ranges::end(r)); + } + }; + + inline constexpr destroy_fn destroy{}; + +.SH Example + + The following example demonstrates how to use ranges::destroy to destroy a + contiguous sequence of elements. + + +// Run this code + + #include + #include + #include + + struct Tracer + { + int value; + ~Tracer() { std::cout << value << " destructed\\n"; } + }; + + int main() + { + alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 8]; + + for (int i = 0; i < 8; ++i) + new(buffer + sizeof(Tracer) * i) Tracer{i}; //manually construct objects + + auto ptr = std::launder(reinterpret_cast(buffer)); + + std::ranges::destroy(ptr, ptr + 8); + } + +.SH Output: + + 0 destructed + 1 destructed + 2 destructed + 3 destructed + 4 destructed + 5 destructed + 6 destructed + 7 destructed + +.SH See also + + ranges::destroy_n destroys a number of objects in a range + (C++20) (niebloid) + ranges::destroy_at destroys an object at a given address + (C++20) (niebloid) + destroy destroys a range of objects + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::destroy_at.3 b/man/std::ranges::destroy_at.3 new file mode 100644 index 000000000..d98288fa5 --- /dev/null +++ b/man/std::ranges::destroy_at.3 @@ -0,0 +1,109 @@ +.TH std::ranges::destroy_at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::destroy_at \- std::ranges::destroy_at + +.SH Synopsis + Defined in header + Call signature + template< std::destructible T > \fI(since C++20)\fP + constexpr void destroy_at( T* p ) noexcept; + + If T is not an array type, calls the destructor of the object pointed to by p, as if + by p->~T(). Otherwise, recursively destroys elements of *p in order, as if by + calling std::destroy(std::begin(*p), std::end(*p)). + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + p - a pointer to the object to be destroyed + +.SH Return value + + \fI(none)\fP + +.SH Possible implementation + + struct destroy_at_fn + { + template + constexpr void operator()(T *p) const noexcept + { + if constexpr (std::is_array_v) + for (auto &elem : *p) + operator()(std::addressof(elem)); + else + p->~T(); + } + }; + + inline constexpr destroy_at_fn destroy_at{}; + +.SH Notes + + destroy_at deduces the type of object to be destroyed and hence avoids writing it + explicitly in the destructor call. + + When destroy_at is called in the evaluation of some constant expression e, the + argument p must point to an object whose lifetime began within the evaluation of e. + +.SH Example + + The following example demonstrates how to use ranges::destroy_at to destroy a + contiguous sequence of elements. + + +// Run this code + + #include + #include + #include + + struct Tracer + { + int value; + ~Tracer() { std::cout << value << " destructed\\n"; } + }; + + int main() + { + alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 8]; + + for (int i = 0; i < 8; ++i) + new(buffer + sizeof(Tracer) * i) Tracer{i}; //manually construct objects + + auto ptr = std::launder(reinterpret_cast(buffer)); + + for (int i = 0; i < 8; ++i) + std::ranges::destroy_at(ptr + i); + } + +.SH Output: + + 0 destructed + 1 destructed + 2 destructed + 3 destructed + 4 destructed + 5 destructed + 6 destructed + 7 destructed + +.SH See also + + ranges::destroy destroys a range of objects + (C++20) (niebloid) + ranges::destroy_n destroys a number of objects in a range + (C++20) (niebloid) + ranges::construct_at creates an object at a given address + (C++20) (niebloid) + destroy_at destroys an object at a given address + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::destroy_n.3 b/man/std::ranges::destroy_n.3 new file mode 100644 index 000000000..da8655360 --- /dev/null +++ b/man/std::ranges::destroy_n.3 @@ -0,0 +1,106 @@ +.TH std::ranges::destroy_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::destroy_n \- std::ranges::destroy_n + +.SH Synopsis + Defined in header + Call signature + template< no-throw-input-iterator I > + + requires std::destructible> \fI(since C++20)\fP + + constexpr I destroy_n( I first, std::iter_difference_t n ) + noexcept; + + Destroys the n objects in the range starting at first, equivalent to + + return std::ranges::destroy(std::counted_iterator(first, n), std::default_sentinel).base(); + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to destroy + n - the number of elements to destroy + +.SH Return value + + The end of the range of objects that has been destroyed. + +.SH Complexity + + Linear in n. + +.SH Possible implementation + + struct destroy_n_fn + { + template + requires std::destructible> + constexpr I operator()(I first, std::iter_difference_t n) const noexcept + { + for (; n != 0; (void)++first, --n) + std::ranges::destroy_at(std::addressof(*first)); + return first; + } + }; + + inline constexpr destroy_n_fn destroy_n{}; + +.SH Example + + The following example demonstrates how to use ranges::destroy_n to destroy a + contiguous sequence of elements. + + +// Run this code + + #include + #include + #include + + struct Tracer + { + int value; + ~Tracer() { std::cout << value << " destructed\\n"; } + }; + + int main() + { + alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 8]; + + for (int i = 0; i < 8; ++i) + new(buffer + sizeof(Tracer) * i) Tracer{i}; //manually construct objects + + auto ptr = std::launder(reinterpret_cast(buffer)); + + std::ranges::destroy_n(ptr, 8); + } + +.SH Output: + + 0 destructed + 1 destructed + 2 destructed + 3 destructed + 4 destructed + 5 destructed + 6 destructed + 7 destructed + +.SH See also + + ranges::destroy_at destroys an object at a given address + (C++20) (niebloid) + ranges::destroy destroys a range of objects + (C++20) (niebloid) + destroy_n destroys a number of objects in a range + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::distance.3 b/man/std::ranges::distance.3 new file mode 100644 index 000000000..81ad7a920 --- /dev/null +++ b/man/std::ranges::distance.3 @@ -0,0 +1,139 @@ +.TH std::ranges::distance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::distance \- std::ranges::distance + +.SH Synopsis + Defined in header + Call signature + template< class I, std::sentinel_for S > + + requires (!std::sized_sentinel_for) \fB(1)\fP \fI(since C++20)\fP + constexpr std::iter_difference_t + + distance( I first, S last ); + template< class I, std::sized_sentinel_for> S > + + constexpr std::iter_difference_t> \fB(2)\fP \fI(since C++20)\fP + + distance( I&& first, S last ); + template< ranges::range R > + + constexpr ranges::range_difference_t \fB(3)\fP \fI(since C++20)\fP + + distance( R&& r ); + + 1,2) Returns the number of hops from first to last. + 3) Returns the size of r as a signed integer. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - iterator pointing to the first element + last - sentinel denoting the end of the range first is an iterator to + r - range to calculate the distance of + +.SH Return value + + 1) The number of increments needed to go from first to last. + 2) last - static_cast&>(first). + 3) If R models ranges::sized_range, returns ranges::size(r); otherwise + ranges::distance(ranges::begin(r), ranges::end(r)). + +.SH Complexity + + 1) Linear. + 2) Constant. + 3) If R models ranges::sized_range or if + std::sized_sentinel_for, ranges::iterator_t> is modeled, + complexity is constant; otherwise linear. + +.SH Possible implementation + + struct distance_fn + { + template S> + requires (!std::sized_sentinel_for) + constexpr std::iter_difference_t operator()(I first, S last) const + { + std::iter_difference_t result = 0; + while (first != last) + { + ++first; + ++result; + } + return result; + } + + template> S> + constexpr std::iter_difference_t operator()(const I& first, S last) const + { + return last - first; + } + + template + constexpr ranges::range_difference_t operator()(R&& r) const + { + if constexpr (ranges::sized_range>) + return static_cast>(ranges::size(r)); + else + return (*this)(ranges::begin(r), ranges::end(r)); + } + }; + + inline constexpr auto distance = distance_fn{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v{3, 1, 4}; + assert(std::ranges::distance(v.begin(), v.end()) == 3); + assert(std::ranges::distance(v.end(), v.begin()) == -3); + assert(std::ranges::distance(v) == 3); + + std::forward_list l{2, 7, 1}; + // auto size = std::ranges::size(l); // error: not a sizable range + auto size = std::ranges::distance(l); // OK, but aware O(N) complexity + assert(size == 3); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload (1) takes iterator by value, thus + LWG 3392 C++20 move-only added overload (2) + iterator lvalue with a sized sentinel was + rejected + LWG 3664 C++20 the resolution of LWG issue 3392 made accepts them + ranges::distance reject array arguments + +.SH See also + + ranges::advance advances an iterator by given distance or to a given bound + (C++20) (niebloid) + ranges::count + ranges::count_if returns the number of elements satisfying specific criteria + (C++20) (niebloid) + (C++20) + distance returns the distance between two iterators + \fI(function template)\fP diff --git a/man/std::ranges::drop_view::base.3 b/man/std::ranges::drop_view::base.3 new file mode 100644 index 000000000..4c6ebe639 --- /dev/null +++ b/man/std::ranges::drop_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::drop_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_view::base \- std::ranges::drop_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::drop_view::begin.3 b/man/std::ranges::drop_view::begin.3 new file mode 100644 index 000000000..416bdbd09 --- /dev/null +++ b/man/std::ranges::drop_view::begin.3 @@ -0,0 +1,87 @@ +.TH std::ranges::drop_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_view::begin \- std::ranges::drop_view::begin + +.SH Synopsis + constexpr auto begin() + + requires (!(__SimpleView && \fB(1)\fP \fI(since C++20)\fP + ranges::random_access_range && + + ranges::sized_range)); + constexpr auto begin() const + + requires ranges::random_access_range && \fB(2)\fP \fI(since C++20)\fP + + ranges::sized_range; + + Returns an iterator to the first element of the drop_view, that is, an iterator to + the N^th element of the underlying view, or to the end of the underlying view if it + has less than N elements. + + If V is not a random_access_range or a sized_range, in order to provide the + amortized constant time complexity required by the range concept, the overload \fB(1)\fP + caches the result within the drop_view object for use on subsequent calls. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + ranges::next(ranges::begin(base_), count_, ranges::end(base_)), where base_ is the + underlying view, and count_ is the number of elements to skip. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(std::ranges::range auto const& range) + { + for (auto const& elem : range) + std::cout << elem; + std::cout << '\\n'; + } + + int main() + { + std::array hi{'H', 'e', 'l', 'l', 'o', ',', ' ', 'C', '+', '+', '2', '0', '!'}; + println(hi); + + const auto pos = std::distance(hi.begin(), std::ranges::find(hi, 'C')); + auto cxx = std::ranges::drop_view{hi, pos}; + std::cout << "*drop_view::begin() == '" << *cxx.begin() << "'\\n"; + // *cxx.begin() = 'c'; // undefined: 'views' are to be used as observers + println(cxx); + } + +.SH Output: + + Hello, C++20! + *drop_view::begin() == 'C' + C++20! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3482 C++20 the const overload can be called the const overload requires + with unsized ranges sized_range + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::drop_view::drop_view.3 b/man/std::ranges::drop_view::drop_view.3 new file mode 100644 index 000000000..4f54d3118 --- /dev/null +++ b/man/std::ranges::drop_view::drop_view.3 @@ -0,0 +1,64 @@ +.TH std::ranges::drop_view::drop_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_view::drop_view \- std::ranges::drop_view::drop_view + +.SH Synopsis + drop_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit drop_view( V base, \fB(2)\fP \fI(since C++20)\fP + ranges::range_difference_t count ); + + Constructs a drop_view. + + 1) Default constructor. Value-initializes the underlying view and initializes the + count to 0. After construction, base() returns a copy of V() and size() equals to + the size of the underlying view. + 2) Initializes the underlying view with std::move(base) and the count with count. + After construction, base() returns a copy of base and size() returns + ranges::size(base) - count if the size of base is not less than count, or 0 + otherwise. + +.SH Parameters + + base - the underlying view + count - number of elements to skip + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::array hi{'H', 'e', 'l', 'l', 'o', ',', + ' ', 'C', '+', '+', '2', '0'}; + + std::ranges::for_each(hi, [](const char c){ std::cout << c; }); + std::cout << '\\n'; + + constexpr auto n = std::distance(hi.cbegin(), std::ranges::find(hi, 'C')); + + auto cxx = std::ranges::drop_view{hi, n}; + + std::ranges::for_each(cxx, [](const char c){ std::cout << c; }); + std::cout << '\\n'; + } + +.SH Output: + + Hello, C++20 + C++20 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was not made explicit + (P2711R1) explicit diff --git a/man/std::ranges::drop_view::end.3 b/man/std::ranges::drop_view::end.3 new file mode 100644 index 000000000..46ebe1945 --- /dev/null +++ b/man/std::ranges::drop_view::end.3 @@ -0,0 +1,54 @@ +.TH std::ranges::drop_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_view::end \- std::ranges::drop_view::end + +.SH Synopsis + constexpr auto end() requires (!__SimpleView); \fB(1)\fP \fI(since C++20)\fP + constexpr auto end() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + Returns a sentinel or an iterator representing the end of the drop_view. + + Effectively returns ranges::end(base_), where base_ is the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A sentinel or an iterator representing the end of the view. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr char url[]{"https://cppreference.com"}; + + const auto p = std::distance(std::ranges::begin(url), std::ranges::find(url, '/')); + auto site = std::ranges::drop_view{url, p + 2}; // drop the prefix "https://" + + for (auto it = site.begin(); it != site.end(); ++it) + std::cout << *it; // ^^^ + std::cout << '\\n'; + } + +.SH Output: + + cppreference.com + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::drop_view::size.3 b/man/std::ranges::drop_view::size.3 new file mode 100644 index 000000000..699ad8750 --- /dev/null +++ b/man/std::ranges::drop_view::size.3 @@ -0,0 +1,49 @@ +.TH std::ranges::drop_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_view::size \- std::ranges::drop_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fB(1)\fP \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP \fI(since C++20)\fP + + Returns the number of elements. + + Let base_ be the underlying view, count_ be the stored count (usually the number + passed to the constructor, or 0 if *this is default constructed). Equivalent to + + const auto s = ranges::size(base_); + const auto c = static_cast(count_); + return s < c ? 0 : s - c; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::array a{42, 43, 44}; + static_assert(std::ranges::drop_view{std::views::all(a), 0}.size() == 3); + static_assert(std::ranges::drop_view{std::views::all(a), 1}.size() == 2); + static_assert(std::ranges::drop_view{std::views::all(a), 2}.size() == 1); + static_assert(std::ranges::drop_view{std::views::all(a), 3}.size() == 0); + static_assert(std::ranges::drop_view{std::views::all(a), 4}.size() == 0); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::drop_while_view::base.3 b/man/std::ranges::drop_while_view::base.3 new file mode 100644 index 000000000..c1465005c --- /dev/null +++ b/man/std::ranges::drop_while_view::base.3 @@ -0,0 +1,57 @@ +.TH std::ranges::drop_while_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_while_view::base \- std::ranges::drop_while_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(auto first, auto last) + { + for (; first != last; ++first) + std::cout << *first << ' '; + std::cout << '\\n'; + } + + int main() + { + std::array data{1, 2, 3, 4, 5}; + print(data.cbegin(), data.cend()); + + auto func = [](int x) { return x < 3; }; + auto view = std::ranges::drop_while_view{data, func}; + print(view.begin(), view.end()); + + auto base = view.base(); // `base` refers to the `data` + std::ranges::reverse(base); //< changes `data` indirectly + print(data.cbegin(), data.cend()); + } + +.SH Output: + + 1 2 3 4 5 + 3 4 5 + 5 4 3 2 1 diff --git a/man/std::ranges::drop_while_view::begin.3 b/man/std::ranges::drop_while_view::begin.3 new file mode 100644 index 000000000..2bea178f6 --- /dev/null +++ b/man/std::ranges::drop_while_view::begin.3 @@ -0,0 +1,52 @@ +.TH std::ranges::drop_while_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_while_view::begin \- std::ranges::drop_while_view::begin + +.SH Synopsis + constexpr auto begin(); \fI(since C++20)\fP + + Returns an iterator to the first element of the view. + + Effectively returns ranges::find_if_not(base_, std::cref(pred())), where base_ is + the underlying view. The behavior is undefined if *this does not store a predicate. + + In order to provide the amortized constant time complexity required by the range + concept, this function caches the result within the drop_while_view object for use + on subsequent calls. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element of the view. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::array data{ 0, -1, -2, 3, 1, 4, 1, 5 }; + + auto view = std::ranges::drop_while_view{ + data, [](int x) { return x <= 0; } + }; + + std::cout << *view.begin() << '\\n'; + } + +.SH Output: + + 3 + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP diff --git a/man/std::ranges::drop_while_view::drop_while_view.3 b/man/std::ranges::drop_while_view::drop_while_view.3 new file mode 100644 index 000000000..21135c784 --- /dev/null +++ b/man/std::ranges::drop_while_view::drop_while_view.3 @@ -0,0 +1,60 @@ +.TH std::ranges::drop_while_view::drop_while_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_while_view::drop_while_view \- std::ranges::drop_while_view::drop_while_view + +.SH Synopsis + drop_while_view() requires std::default_initializable && + std::default_initializable = \fB(1)\fP \fI(since C++20)\fP + default; + constexpr explicit drop_while_view( V base, Pred pred ); \fB(2)\fP \fI(since C++20)\fP + + Constructs a drop_while_view. + + 1) Default constructor. Value-initializes the underlying view and the predicate. + 2) Move constructs the underlying view from base and the predicate from pred. + +.SH Parameters + + base - underlying view + pred - predicate + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::array data{0, -1, -2, 3, 1, 4, 1, 5}; + + auto view = std::ranges::drop_while_view + { + data, [](int x) { return x <= 0; } + }; + + for (int x : view) + std::cout << x << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 3 1 4 1 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was made explicit + (P2711R1) not explicit + if Pred is not + default_initializable, the default the drop_while_view is also + P2325R3 C++20 constructor not default_initializable + constructs a drop_while_view which + does not contain an Pred diff --git a/man/std::ranges::drop_while_view::end.3 b/man/std::ranges::drop_while_view::end.3 new file mode 100644 index 000000000..6b3ba25be --- /dev/null +++ b/man/std::ranges::drop_while_view::end.3 @@ -0,0 +1,50 @@ +.TH std::ranges::drop_while_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_while_view::end \- std::ranges::drop_while_view::end + +.SH Synopsis + constexpr auto end(); \fI(since C++20)\fP + + Returns a sentinel or an iterator representing the end of the drop_while_view. + + Effectively returns ranges::end(base_), where base_ is the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A sentinel or an iterator representing the end of the view. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::array data{0, -1, -2, 3, 1, 4, 1, 5}; + + auto view = std::ranges::drop_while_view + { + data, [](int x) { return x <= 0; } + }; + + for (auto it = view.begin(); it != view.end(); ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 3 1 4 1 5 + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP diff --git a/man/std::ranges::drop_while_view::pred.3 b/man/std::ranges::drop_while_view::pred.3 new file mode 100644 index 000000000..b0e0b8fd6 --- /dev/null +++ b/man/std::ranges::drop_while_view::pred.3 @@ -0,0 +1,56 @@ +.TH std::ranges::drop_while_view::pred 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::drop_while_view::pred \- std::ranges::drop_while_view::pred + +.SH Synopsis + constexpr const Pred& pred() const; \fI(since C++20)\fP + + Returns a reference to the stored predicate. + + If *this does not store a predicate (e.g. an exception is thrown on the assignment + to *this, which copy-constructs or move-constructs a Pred), the behavior is + undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the stored predicate. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr std::array data{0, -1, -2, 3, 1, 4, 1, 5}; + + auto view = std::ranges::drop_while_view + { + data, [](int x) { return x <= 0; } + }; + + std::cout << std::boolalpha; + for (int x : data) + std::cout << "predicate(" << std::setw(2) << x << ") : " + << view.pred()(x) << '\\n'; + } + +.SH Output: + + predicate( 0) : true + predicate(-1) : true + predicate(-2) : true + predicate( 3) : false + predicate( 1) : false + predicate( 4) : false + predicate( 1) : false + predicate( 5) : false diff --git a/man/std::ranges::elements_of.3 b/man/std::ranges::elements_of.3 new file mode 100644 index 000000000..c9aad7665 --- /dev/null +++ b/man/std::ranges::elements_of.3 @@ -0,0 +1,79 @@ +.TH std::ranges::elements_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_of \- std::ranges::elements_of + +.SH Synopsis + Defined in header + template< ranges::range R, class Allocator = + std::allocator > (since C++23) + struct elements_of; + + Encapsulates a range. Specializations of elements_of act as a tag in overload sets + to disambiguate when a range should be treated as a sequence rather than a single + value. + +.SH Template parameters + + R - a type that satisfies range + Allocator - an allocator type that meets the requirements of Allocator + + Data members + + Member name Definition + range a range of type R + \fI(public member object)\fP + an allocator of type Allocator. It has default member initializer that + allocator value initializes itself + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + + Deduction guide + + template< class R, class Allocator = std::allocator > + elements_of( R&&, Allocator = Allocator() ) -> elements_of; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + std::generator gen(std::ranges::input_range auto&& r) + { + if constexpr (Elementwise) + co_yield std::ranges::elements_of(r); // yield each element of r + else + co_yield r; // yield r as a single value + } + + int main() + { + auto test = std::string_view{"test"}; + + for (std::any a : gen(test)) + std::cout << '[' << std::any_cast(a) << "] "; + std::cout << '\\n'; + + for (std::any a : gen(test)) + std::cout << '[' << std::any_cast(a) << "] "; + std::cout << '\\n'; + } + +.SH Output: + + [t] [e] [s] [t] + [test] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.5.6 Class template elements_of [range.elementsof] diff --git a/man/std::ranges::elements_view::base.3 b/man/std::ranges::elements_view::base.3 new file mode 100644 index 000000000..8ac6a15e2 --- /dev/null +++ b/man/std::ranges::elements_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::elements_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::base \- std::ranges::elements_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::begin.3 b/man/std::ranges::elements_view::begin.3 new file mode 100644 index 000000000..62ac44bbc --- /dev/null +++ b/man/std::ranges::elements_view::begin.3 @@ -0,0 +1,37 @@ +.TH std::ranges::elements_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::begin \- std::ranges::elements_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__SimpleView); \fB(1)\fP \fI(since C++20)\fP + constexpr auto begin() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + Returns an iterator to the first element of the elements_view. + + Let base_ be the underlying view. + + 1) Equivalent to return /*iterator*/(ranges::begin(base_));. + 2) Equivalent to return /*iterator*/(ranges::begin(base_));. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::elements_view.3 b/man/std::ranges::elements_view::elements_view.3 new file mode 100644 index 000000000..8832038f2 --- /dev/null +++ b/man/std::ranges::elements_view::elements_view.3 @@ -0,0 +1,58 @@ +.TH std::ranges::elements_view::elements_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::elements_view \- std::ranges::elements_view::elements_view + +.SH Synopsis + elements_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit elements_view( V base ); \fB(2)\fP \fI(since C++20)\fP + + Constructs an elements_view. + + 1) Default constructor. Value-initializes the underlying view. After construction, + base() returns a copy of V(). + 2) Initializes the underlying view with std::move(base). + +.SH Parameters + + base - the underlying view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void println(auto const& v) + { + for (auto const& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + using namespace std::literals; + + const std::array, 2> vt + { + std::tuple{1, 'A', "α"s}, + std::tuple{2, 'B', "β"s}, + }; + + [[maybe_unused]] + auto empty = std::views::elements<0>; + + println(std::views::elements<0>(vt)); + println(std::views::elements<1>(vt)); + println(std::views::elements<2>(vt)); + } + +.SH Output: + + 1 2 + A B + α β diff --git a/man/std::ranges::elements_view::end.3 b/man/std::ranges::elements_view::end.3 new file mode 100644 index 000000000..6e97534d6 --- /dev/null +++ b/man/std::ranges::elements_view::end.3 @@ -0,0 +1,49 @@ +.TH std::ranges::elements_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::end \- std::ranges::elements_view::end + +.SH Synopsis + constexpr auto end() requires (!__SimpleView && \fB(1)\fP \fI(since C++20)\fP + !ranges::common_range); + constexpr auto end() requires (!__SimpleView && \fB(2)\fP \fI(since C++20)\fP + ranges::common_range); + constexpr auto end() const requires ranges::range; \fB(3)\fP \fI(since C++20)\fP + constexpr auto end() const requires ranges::common_range; \fB(4)\fP \fI(since C++20)\fP + + Returns a sentinel or an iterator representing the end of the elements_view. + + Let base_ be the underlying view: + + 1) Equivalent to return /*sentinel*/{ranges::end(base_)};. + 2) Equivalent to return /*iterator*/{ranges::end(base_)};. + 3) Equivalent to return /*sentinel*/{ranges::end(base_)};. + 4) Equivalent to return /*iterator*/{ranges::end(base_)};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) sentinel which compares equal to the end iterator + 2,4) iterator to the element following the last element + +.SH Notes + + end() returns an iterator if and only if the underlying view is a common_range: + elements_view models common_range whenever V does. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::iterator.3 b/man/std::ranges::elements_view::iterator.3 new file mode 100644 index 000000000..5200249c8 --- /dev/null +++ b/man/std::ranges::elements_view::iterator.3 @@ -0,0 +1,92 @@ +.TH std::ranges::elements_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::iterator \- std::ranges::elements_view::iterator + +.SH Synopsis + template< bool Const > (exposition only*) + class /*iterator*/; + + The return type of elements_view::begin, and of elements_view::end when the + underlying view is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + Denotes: + * std::random_access_iterator_tag, if Base models + random_access_range. Otherwise, + iterator_concept * std::bidirectional_iterator_tag, if Base models + bidirectional_range. Otherwise, + * std::forward_iterator_tag, if Base models forward_range. + Otherwise, + * std::input_iterator_tag. + Not defined, if Base does not model forward_range. Otherwise, + * std::input_iterator_tag, if std::get(*current_) is an + rvalue. Otherwise, let C be the type + iterator_category std::iterator_traits>::iterator_category. + * std::random_access_iterator_tag, if C models + std::derived_from. Otherwise, + * C. + value_type std::remove_cvref_t>> + difference_type ranges::range_difference_t + + Data members + + Member object Definition + An iterator of type ranges::iterator_t to current element + current_ (private) of underlying sequence. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + base returns the underlying iterator + (C++20) \fI(public member function)\fP + operator* accesses the N^th tuple element + (C++20) \fI(public member function)\fP + operator[] accesses an element by index + (C++20) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++20) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++20) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++20) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2259R1 C++20 member iterator_category is always defined only if Base models + defined forward_range + LWG 3555 C++20 the definition of iterator_concept made to consider + ignores const + +.SH See also + + iterator the return type of ranges::transform_view::begin, and of + (C++20) ranges::transform_view::end when the underlying view is a common_range + (private member class template) diff --git a/man/std::ranges::elements_view::iterator::base.3 b/man/std::ranges::elements_view::iterator::base.3 new file mode 100644 index 000000000..0bb0b9d84 --- /dev/null +++ b/man/std::ranges::elements_view::iterator::base.3 @@ -0,0 +1,40 @@ +.TH std::ranges::elements_view::iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::iterator::base \- std::ranges::elements_view::iterator::base + +.SH Synopsis + constexpr const ranges::iterator_t& base() const & noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr ranges::iterator_t base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns the underlying iterator. + + 1) Returns a reference to the underlying iterator. + 2) Move constructs the result from the underlying iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A reference to the underlying iterator. + 1) An iterator move constructed from the underlying iterator. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3533 C++20 the const& overload of base returns a copy returns a reference + of the underlying iterator + LWG 3593 C++20 the const& overload of base might not be made noexcept + noexcept + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::iterator::iterator.3 b/man/std::ranges::elements_view::iterator::iterator.3 new file mode 100644 index 000000000..c090f6a0f --- /dev/null +++ b/man/std::ranges::elements_view::iterator::iterator.3 @@ -0,0 +1,34 @@ +.TH std::ranges::elements_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::iterator::iterator \- std::ranges::elements_view::iterator::iterator + +.SH Synopsis + /*iterator*/() requires (since + std::default_initializable> \fB(1)\fP C++20) + = default; + constexpr explicit /*iterator*/( ranges::iterator_t current ); \fB(2)\fP (since + C++20) + constexpr /*iterator*/( /*iterator*/ i ) requires Const && (since + std::convertible_to, \fB(3)\fP C++20) + ranges::iterator_t>; + + Construct an iterator. + + 1) Value-initializes the underlying iterator current_ via its default member + initializer (= ranges::iterator_t()). + 2) Initializes the underlying iterator current_ with std::move(current). + 3) Conversion from /*iterator*/ to /*iterator*/. Initializes the + underlying iterator current_ with std::move(i.current). + +.SH Parameters + + current - an iterator into (possibly const-qualified) V + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::iterator::operator*.3 b/man/std::ranges::elements_view::iterator::operator*.3 new file mode 100644 index 000000000..023b8f522 --- /dev/null +++ b/man/std::ranges::elements_view::iterator::operator*.3 @@ -0,0 +1,64 @@ +.TH std::ranges::elements_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::iterator::operator* \- std::ranges::elements_view::iterator::operator* + +.SH Synopsis + constexpr decltype(auto) operator*() const; \fI(since C++20)\fP + + Returns the element into V the underlying iterator points to. + + Effectively returns /*get-element*/(this->base()), where for an expression e, + /*get-element*/(e) is + + * std::get(*e), if ranges::range_reference_t is a reference type. + Otherwise, + * static_cast(std::get(*e)), where E is + std::remove_cv_t>>. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Notes + + operator-> is not provided. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using T = std::tuple; + + const auto il = { + T{1, 'A', "α"}, + T{2, 'B', "β"}, + T{3, 'C', "γ"}, + }; + + const auto view {il | std::views::elements<2>}; + + const auto iter {view.begin() + 1}; + + std::cout << *iter << '\\n'; + } + +.SH Output: + + β + +.SH See also + + operator[] accesses an element by index + (C++20) \fI(public member function)\fP diff --git a/man/std::ranges::elements_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::elements_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..d1845283a --- /dev/null +++ b/man/std::ranges::elements_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,39 @@ +.TH std::ranges::elements_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::iterator::operator++,--,+=,-= \- std::ranges::elements_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr void operator++( int ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*iterator*/ operator++( int ) \fB(3)\fP \fI(since C++20)\fP + requires ranges::forward_range; + constexpr /*iterator*/& operator--() \fB(4)\fP \fI(since C++20)\fP + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(5)\fP \fI(since C++20)\fP + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(6)\fP \fI(since C++20)\fP + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(7)\fP \fI(since C++20)\fP + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let current_ be the underlying iterator. + + 1) Equivalent to ++current_; return *this; + 2) Equivalent to ++current_; + 3) Equivalent to auto tmp = *this; ++*this; return tmp; + 4) Equivalent to --current_; return *this; + 5) Equivalent to auto tmp = *this; --*this; return tmp; + 6) Equivalent to current_ += n; return *this; + 7) Equivalent to current_ -= n; return *this; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change diff --git a/man/std::ranges::elements_view::iterator::operator[].3 b/man/std::ranges::elements_view::iterator::operator[].3 new file mode 100644 index 000000000..33040ff0b --- /dev/null +++ b/man/std::ranges::elements_view::iterator::operator[].3 @@ -0,0 +1,58 @@ +.TH std::ranges::elements_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::iterator::operator[] \- std::ranges::elements_view::iterator::operator[] + +.SH Synopsis + constexpr decltype(auto) operator[]( difference_type n ) const \fI(since C++20)\fP + requires ranges::random_access_range; + + Returns an element at specified relative location, as if by + /*get-element*/(this->base() + n), where for an expression e, /*get-element*/(e) is + + * std::get(*e), if ranges::range_reference_t is a reference type. + Otherwise, + * static_cast(std::get(*e)), where E is + std::remove_cv_t>>. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The element at displacement n relative to the current location. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using T = std::tuple; + + const auto il = + { + T{1, 'A', "α"}, + T{2, 'B', "β"}, + T{3, 'C', "γ"}, + }; + + std::cout << std::views::elements<0>(il)[1] << ' ' // 2 + << std::views::elements<1>(il)[1] << ' ' // B + << std::views::elements<2>(il)[1] << '\\n'; // β + } + +.SH Output: + + 2 B β + +.SH See also + + operator* accesses the N^th tuple element + (C++20) \fI(public member function)\fP diff --git a/man/std::ranges::elements_view::sentinel.3 b/man/std::ranges::elements_view::sentinel.3 new file mode 100644 index 000000000..58e76a203 --- /dev/null +++ b/man/std::ranges::elements_view::sentinel.3 @@ -0,0 +1,40 @@ +.TH std::ranges::elements_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::sentinel \- std::ranges::elements_view::sentinel + +.SH Synopsis + template< bool Const > (exposition only*) + class /*sentinel*/; + + The return type of elements_view::end when the underlying view is not a + common_range. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + + Data members + + Member object Definition + end_ (private) A sentinel obtained from (possibly const-qualified) V. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + base returns the underlying sentinel + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from elements_view::begin + (C++20) \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++20) elements_view::begin + \fI(function)\fP diff --git a/man/std::ranges::elements_view::sentinel::base.3 b/man/std::ranges::elements_view::sentinel::base.3 new file mode 100644 index 000000000..7ca02e229 --- /dev/null +++ b/man/std::ranges::elements_view::sentinel::base.3 @@ -0,0 +1,24 @@ +.TH std::ranges::elements_view::sentinel::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::sentinel::base \- std::ranges::elements_view::sentinel::base + +.SH Synopsis + constexpr ranges::sentinel_t base() const; \fI(since C++20)\fP + + Returns the underlying sentinel. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + a copy of the underlying sentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::sentinel::sentinel.3 b/man/std::ranges::elements_view::sentinel::sentinel.3 new file mode 100644 index 000000000..0c69ff799 --- /dev/null +++ b/man/std::ranges::elements_view::sentinel::sentinel.3 @@ -0,0 +1,32 @@ +.TH std::ranges::elements_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::sentinel::sentinel \- std::ranges::elements_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( ranges::sentinel_t end ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && std::convertible_to, \fB(3)\fP \fI(since C++20)\fP + + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel. + 2) Initializes the underlying sentinel with end. + 3) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying sentinel. + +.SH Parameters + + end - a sentinel representing the end of (possibly const-qualified) V + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::elements_view::size.3 b/man/std::ranges::elements_view::size.3 new file mode 100644 index 000000000..fc3f932c1 --- /dev/null +++ b/man/std::ranges::elements_view::size.3 @@ -0,0 +1,33 @@ +.TH std::ranges::elements_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::elements_view::size \- std::ranges::elements_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fI(since C++20)\fP + + Returns the number of elements, i.e. ranges::size(base_), where base_ is the + underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::empty.3 b/man/std::ranges::empty.3 new file mode 100644 index 000000000..74c706a15 --- /dev/null +++ b/man/std::ranges::empty.3 @@ -0,0 +1,136 @@ +.TH std::ranges::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::empty \- std::ranges::empty + +.SH Synopsis + Defined in header + Defined in header + inline namespace /*unspecified*/ { + \fI(since C++20)\fP + inline constexpr auto empty = /*unspecified*/; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr bool empty( T&& t ); + + Determines whether or not t has any elements. + + A call to ranges::empty is expression-equivalent to: + + 1. bool(t.empty()), if that expression is valid. + 2. Otherwise, (ranges::size(t) == 0), if that expression is valid. + 3. Otherwise, bool(ranges::begin(t) == ranges::end(t)), if that expression is valid + and decltype(ranges::begin(t)) models std::forward_iterator. + + In all other cases, a call to ranges::empty is ill-formed, which can result in + substitution failure when ranges::empty(t) appears in the immediate context of a + template instantiation. + + Customization point objects + + The name ranges::empty denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __empty_fn. + + All instances of __empty_fn are equal. The effects of invoking different instances + of type __empty_fn on the same arguments are equivalent, regardless of whether the + expression denoting the instance is an lvalue or rvalue, and is const-qualified or + not (however, a volatile-qualified instance is not required to be invocable). Thus, + ranges::empty can be copied freely and its copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::empty above, __empty_fn models + + * std::invocable<__empty_fn, Args...>, + * std::invocable, + * std::invocable<__empty_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __empty_fn participates in overload + resolution. + +.SH Example + + +// Run this code + + #include + #include + #include + + template + void print(char id, R&& r) + { + if (std::ranges::empty(r)) + { + std::cout << '\\t' << id << ") Empty\\n"; + return; + } + + std::cout << '\\t' << id << ") Elements:"; + for (const auto& element : r) + std::cout << ' ' << element; + std::cout << '\\n'; + } + + int main() + { + { + auto v = std::vector{1, 2, 3}; + std::cout << "(1) ranges::empty uses std::vector::empty:\\n"; + print('a', v); + + v.clear(); + print('b', v); + } + { + std::cout << "(2) ranges::empty uses ranges::size(initializer_list):\\n"; + auto il = {7, 8, 9}; + print('a', il); + + print('b', std::initializer_list{}); + } + { + std::cout << "(2) ranges::empty on a raw array uses ranges::size:\\n"; + int array[] = {4, 5, 6}; // array has a known bound + print('a', array); + } + { + struct Scanty : private std::vector + { + using std::vector::begin; + using std::vector::end; + using std::vector::push_back; + // Note: both empty() and size() are hidden + }; + + std::cout << "(3) calling ranges::empty on an object w/o empty() or size():\\n"; + Scanty y; + print('a', y); + y.push_back(42); + print('b', y); + } + } + +.SH Output: + + \fB(1)\fP ranges::empty uses std::vector::empty: + a) Elements: 1 2 3 + b) Empty + \fB(2)\fP ranges::empty uses ranges::size(initializer_list): + a) Elements: 7 8 9 + b) Empty + \fB(2)\fP ranges::empty on a raw array uses ranges::size: + a) Elements: 4 5 6 + \fB(3)\fP calling ranges::empty on an object w/o empty() or size(): + a) Empty + b) Elements: 42 + +.SH See also + + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::end.3 b/man/std::ranges::end.3 new file mode 100644 index 000000000..0925ff0e2 --- /dev/null +++ b/man/std::ranges::end.3 @@ -0,0 +1,111 @@ +.TH std::ranges::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::end \- std::ranges::end + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + \fI(since C++20)\fP + inline constexpr /* unspecified */ end = /* unspecified (customization point + */; object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr std::sentinel_for> auto end( + T&& t ); + + Returns a sentinel indicating the end of a range. + + range-begin-end.svg + + If the argument is an lvalue or ranges::enable_borrowed_range> + is true, then a call to ranges::end is expression-equivalent to: + + 1. t + std::extent_v if t has an array type of known bound. + * If std::remove_all_extents_t> is incomplete, + then the call to ranges::end is ill-formed, no diagnostic required. + 2. Otherwise, + decay-copy(t.end()) + (until C++23) + auto(t.end()) + (since C++23), if that expression is valid, and its type models + std::sentinel_for>. + 3. Otherwise, + decay-copy(end(t)) + (until C++23) + auto(end(t)) + (since C++23), if T is a class or enumeration type, that expression is valid and + its converted type models std::sentinel_for>, where the + meaning of end is established as if by performing argument-dependent lookup + only. + + In all other cases, a call to ranges::end is ill-formed, which can result in + substitution failure when the call to ranges::end appears in the immediate context + of a template instantiation. + +.SH Notes + + If the argument is an rvalue (i.e. T is an object type) and + ranges::enable_borrowed_range> is false, or if it is of an array + type of unknown bound, the call to ranges::end is ill-formed, which also results in + substitution failure. + + If ranges::end(std::forward(t)) is valid, then + decltype(ranges::end(std::forward(t))) and + decltype(ranges::begin(std::forward(t))) model std::sentinel_for in all cases, + while T models std::ranges::range. + + The C++20 standard requires that if the underlying end function call returns a + prvalue, the return value is move-constructed from the materialized temporary + object. All implementations directly return the prvalue instead. The requirement is + corrected by the post-C++20 proposal P0849R8 to match the implementations. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector vec{3, 1, 4}; + if (std::ranges::find(vec, 5) != std::ranges::end(vec)) + std::cout << "found a 5 in vector vec!\\n"; + + int arr[]{5, 10, 15}; + if (std::ranges::find(arr, 5) != std::ranges::end(arr)) + std::cout << "found a 5 in array arr!\\n"; + } + +.SH Output: + + found a 5 in array arr! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2602R2 C++20 there's machinery to prohibit certain removed such machinery + non-member end found by ADL + +.SH See also + + ranges::cend returns a sentinel indicating the end of a read-only range + (C++20) (customization point object) + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::ends_with.3 b/man/std::ranges::ends_with.3 new file mode 100644 index 000000000..70f4d7e22 --- /dev/null +++ b/man/std::ranges::ends_with.3 @@ -0,0 +1,159 @@ +.TH std::ranges::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::ends_with \- std::ranges::ends_with + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity > + requires (std::forward_iterator || std::sized_sentinel_for) + && \fB(1)\fP (since + (std::forward_iterator || std::sized_sentinel_for) C++23) + && + std::indirectly_comparable + constexpr bool + ends_with( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity > + requires (ranges::forward_range || ranges::sized_range) && + (ranges::forward_range || ranges::sized_range) && (since + std::indirectly_comparable, \fB(2)\fP C++23) + ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr bool + ends_with( R1&& r1, R2&& r2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + + Checks whether the second range matches the suffix of the first range. + + 1) Let N1 and N2 be ranges::distance(first1, last1) and ranges::distance(first2, + last2) respectively. If N1 < N2, returns false. Otherwise, returns true if only if + every element in the range [first2, last2) is equal to the corresponding element in + [first1 + N1 - N2, last1). Comparison is done by applying the binary predicate pred + to elements in two ranges projected by proj1 and proj2 respectively. + 2) Same as \fB(1)\fP, but uses r1 and r2 as the source ranges, as if using + ranges::begin(r1) as first1, ranges:begin(r2) as first2, ranges::end(r1) as last1, + and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the range of elements to examine + r1 - the range of elements to examine + first2, last2 - the range of elements to be used as the suffix + r2 - the range of elements to be used as the suffix + pred - the binary predicate that compares the projected elements + proj1 - the projection to apply to the elements of the range to examine + proj2 - the projection to apply to the elements of the range to be used as + the suffix + +.SH Return value + + true if the second range matches the suffix of the first range, false otherwise. + +.SH Complexity + + Generally linear: at most min(N1, N2) applications of the predicate and both + projections. The predicate and both projections are not applied if N1 < N2. + + If both N1 and N2 can be calculated in constant time (i.e. both iterator-sentinel + type pairs model sized_sentinel_for, or both range types model sized_range) and N1 < + N2, the time complexity is constant. + +.SH Possible implementation + + struct ends_with_fn + { + template S1, + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity> + requires (std::forward_iterator || std::sized_sentinel_for) && + (std::forward_iterator || std::sized_sentinel_for) && + std::indirectly_comparable + constexpr bool operator()(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + const auto n1 = ranges::distance(first1, last1); + const auto n2 = ranges::distance(first2, last2); + if (n1 < n2) + return false; + ranges::advance(first1, n1 - n2); + return ranges::equal(std::move(first1), std::move(last1), + std::move(first2), std::move(last2), + std::move(pred), std::move(proj1), std::move(proj2)); + } + + template + requires (ranges::forward_range || ranges::sized_range) && + (ranges::forward_range || ranges::sized_range) && + std::indirectly_comparable, + ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr bool operator()(R1&& r1, R2&& r2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(pred), std::move(proj1), std::move(proj2)); + } + }; + + inline constexpr ends_with_fn ends_with {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_starts_ends_with 202106L (C++23) std::ranges::starts_with, + std::ranges::ends_with + +.SH Example + + +// Run this code + + #include + #include + + static_assert( + ! std::ranges::ends_with("for", "cast") && + std::ranges::ends_with("dynamic_cast", "cast") && + ! std::ranges::ends_with("as_const", "cast") && + std::ranges::ends_with("bit_cast", "cast") && + ! std::ranges::ends_with("to_underlying", "cast") && + std::ranges::ends_with(std::array{1, 2, 3, 4}, std::array{3, 4}) && + ! std::ranges::ends_with(std::array{1, 2, 3, 4}, std::array{4, 5}) + ); + + int main() {} + +.SH See also + + ranges::starts_with checks whether a range starts with another range + (C++23) (niebloid) + ends_with checks if the string ends with the given suffix + (C++20) \fI\fI(public member\fP function of\fP + std::basic_string) + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::ranges::enumerate_view::base.3 b/man/std::ranges::enumerate_view::base.3 new file mode 100644 index 000000000..8ace5f0f5 --- /dev/null +++ b/man/std::ranges::enumerate_view::base.3 @@ -0,0 +1,29 @@ +.TH std::ranges::enumerate_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::base \- std::ranges::enumerate_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. Equivalent to return base_; + 2) Move constructs the result from the underlying view. Equivalent to return + std::move(base_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::begin.3 b/man/std::ranges::enumerate_view::begin.3 new file mode 100644 index 000000000..efd6d0349 --- /dev/null +++ b/man/std::ranges::enumerate_view::begin.3 @@ -0,0 +1,38 @@ +.TH std::ranges::enumerate_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::begin \- std::ranges::enumerate_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto begin() const requires \fB(2)\fP (since C++23) + /*range-with-movable-references*/; + + Returns an iterator to the first element of the enumerate_view. + + Let base_ denote the underlying view. + + 1) Equivalent to return /*iterator*/(ranges::begin(base_), 0);. + 2) Equivalent to return /*iterator*/(ranges::begin(base_), 0);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::end.3 b/man/std::ranges::enumerate_view::end.3 new file mode 100644 index 000000000..f2d8d87c8 --- /dev/null +++ b/man/std::ranges::enumerate_view::end.3 @@ -0,0 +1,65 @@ +.TH std::ranges::enumerate_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::end \- std::ranges::enumerate_view::end + +.SH Synopsis + constexpr auto end() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto end() const requires \fB(2)\fP (since C++23) + /*range-with-movable-references*/; + + Returns an iterator or a sentinel that compares equal to the end iterator of the + enumerate_view. + + Let base_ denote the underlying view. + + 1) Equivalent to: + + if constexpr (ranges::forward_range and + ranges::common_range and + ranges::sized_range) + return /*iterator*/(ranges::end(base_), ranges::distance(base_)); + else + return /*sentinel*/(ranges::end(base_)); + + 2) Equivalent to: + + if constexpr (ranges::forward_range and + ranges::common_range and + ranges::sized_range) + return /*iterator*/(ranges::end(base_), ranges::distance(base_)); + else + return /*sentinel*/(ranges::end(base_)); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator or a sentinel representing the end of the enumerate_view, as described + above. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + ranges::distance may invoke UB for sentinel type is returned + LWG 3919 C++23 sized common for such ranges + non-forward underlying ranges + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::enumerate_view.3 b/man/std::ranges::enumerate_view::enumerate_view.3 new file mode 100644 index 000000000..31423fc13 --- /dev/null +++ b/man/std::ranges::enumerate_view::enumerate_view.3 @@ -0,0 +1,25 @@ +.TH std::ranges::enumerate_view::enumerate_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::enumerate_view \- std::ranges::enumerate_view::enumerate_view + +.SH Synopsis + enumerate_view() requires std::default_initializable = default; \fB(1)\fP (since C++23) + constexpr explicit enumerate_view( V base ); \fB(2)\fP (since C++23) + + Constructs a enumerate_view. + + 1) Default constructor. Value-initializes the underlying view base_. After + construction, base() returns a copy of V(). + 2) Initializes the underlying view base_ with std::move(base). + +.SH Parameters + + base - the underlying view + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::iterator.3 b/man/std::ranges::enumerate_view::iterator.3 new file mode 100644 index 000000000..99432003e --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator.3 @@ -0,0 +1,85 @@ +.TH std::ranges::enumerate_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator \- std::ranges::enumerate_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /* iterator */ (exposition only*) + + The return type of enumerate_view::begin, and of enumerate_view::end when the + underlying view V is a common_range. + + The type /* iterator */ is returned by the const-qualified overloads. The type + /* iterator */ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + iterator_category std::input_iterator_tag + * std::random_access_iterator_tag, if Base models + random_access_range. + * Otherwise std::bidirectional_iterator_tag, if Base + iterator_concept models bidirectional_range. + * Otherwise std::forward_iterator_tag, if Base models + forward_range. + * Otherwise std::input_iterator_tag. + difference_type ranges::range_difference_t + value_type std::tuple> + std::tuple> + (exposition-only member type*) + + Data members + + An iterator to the current element of type + current_ (private) ranges::iterator_t + (exposition-only member object*) + pos_ (private) A current index of type difference_type + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + base returns an iterator to current element + (C++23) \fI(public member function)\fP + index returns current index + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== compares the underlying iterators + operator<=> \fI(function)\fP + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.23.3 Class template enumerate_view::iterator [range.enumerate.iterator] +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::iterator::base.3 b/man/std::ranges::enumerate_view::iterator::base.3 new file mode 100644 index 000000000..e0c65d6eb --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::enumerate_view::iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator::base \- std::ranges::enumerate_view::iterator::base + +.SH Synopsis + constexpr const ranges::iterator_t& base() const& noexcept; \fB(1)\fP (since C++23) + constexpr ranges::iterator_t base() &&; \fB(2)\fP (since C++23) + + Returns the underlying iterator. Let current_ be the underlying iterator. + + 1) Equivalent to: return current_;. + 2) Equivalent to: return std::move(current_);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the current element in enumerate_view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::iterator::index.3 b/man/std::ranges::enumerate_view::iterator::index.3 new file mode 100644 index 000000000..9665c5f60 --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator::index.3 @@ -0,0 +1,21 @@ +.TH std::ranges::enumerate_view::iterator::index 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator::index \- std::ranges::enumerate_view::iterator::index + +.SH Synopsis + constexpr difference_type index() const noexcept; (since C++23) + + Returns the underlying index pos_ of the current element. Equivalent to: return + pos_;. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::iterator::iterator.3 b/man/std::ranges::enumerate_view::iterator::iterator.3 new file mode 100644 index 000000000..feb8d7771 --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator::iterator.3 @@ -0,0 +1,42 @@ +.TH std::ranges::enumerate_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator::iterator \- std::ranges::enumerate_view::iterator::iterator + +.SH Synopsis + /*iterator*/() + requires std::default_initializable> \fB(1)\fP (since C++23) + = default; + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + ranges::iterator_t>; + private: + + constexpr explicit /*iterator*/( ranges::iterator_t \fB(3)\fP (exposition + current, only*) + + difference_type pos); + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying iterator current_ with + ranges::iterator_t() and the underlying index pos_ with 0. + 2) Conversion from /*iterator*/ to /*iterator*/. Initializes current_ + with std::move(i.current_) and pos_ with i.pos_. + 3) A private constructor which is used by enumerate_view::begin and + enumerate_view::end. This constructor is not accessible to users. Initializes + current_ with std::move(current) and pos_ with pos. + +.SH Parameters + + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::iterator::operator*.3 b/man/std::ranges::enumerate_view::iterator::operator*.3 new file mode 100644 index 000000000..35ca53244 --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator::operator*.3 @@ -0,0 +1,31 @@ +.TH std::ranges::enumerate_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator::operator* \- std::ranges::enumerate_view::iterator::operator* + +.SH Synopsis + constexpr auto operator*() const; (since C++23) + + Returns the current element in the enumerate_view. + + Equivalent to: return reference-type(pos_, *current_);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::enumerate_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..920713409 --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,45 @@ +.TH std::ranges::enumerate_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator::operator++,--,+=,-= \- std::ranges::enumerate_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/ operator++( int ) \fB(3)\fP (since C++23) + requires ranges::forward_range; + constexpr /*iterator*/& operator--() \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(5)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(7)\fP (since C++23) + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let current_ be the underlying iterator and pos_ be the underlying index. + + 1) Equivalent to ++current_; ++pos_; return *this; + 2) Equivalent to ++current_; + 3) Equivalent to auto tmp = *this; ++*this; return tmp; + 4) Equivalent to --current_; --pos_; return *this; + 5) Equivalent to auto tmp = *this; --*this; return tmp; + 6) Equivalent to current_ += n; pos_ += n; return *this; + 7) Equivalent to current_ -= n; pos_ -= n; return *this; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change + +.SH See also + + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) diff --git a/man/std::ranges::enumerate_view::iterator::operator[].3 b/man/std::ranges::enumerate_view::iterator::operator[].3 new file mode 100644 index 000000000..5f9accbfe --- /dev/null +++ b/man/std::ranges::enumerate_view::iterator::operator[].3 @@ -0,0 +1,31 @@ +.TH std::ranges::enumerate_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::iterator::operator[] \- std::ranges::enumerate_view::iterator::operator[] + +.SH Synopsis + constexpr auto operator[]( difference_type n ) const (since C++23) + requires ranges::random_access_range + + Returns an element at specified relative location. Equivalent to: + return reference-type(pos_ + n, current_[n]);. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The element at displacement n relative to the current location. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::sentinel.3 b/man/std::ranges::enumerate_view::sentinel.3 new file mode 100644 index 000000000..c67345b40 --- /dev/null +++ b/man/std::ranges::enumerate_view::sentinel.3 @@ -0,0 +1,57 @@ +.TH std::ranges::enumerate_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::sentinel \- std::ranges::enumerate_view::sentinel + +.SH Synopsis + template< bool Const > (since C++23) + class /*sentinel*/; (exposition only*) + + The return type of enumerate_view::end when the underlying view is not a + common_range. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + + Data members + + Member object Definition + end_ (private) A sentinel of type ranges::sentinel_t + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + base returns a sentinel indicating the end of a range + (C++23) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from enumerate_view::begin + (C++23) \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++23) enumerate_view::begin + \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.23.4 Class template enumerate_view::sentinel [range.enumerate.sentinel] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::sentinel::base.3 b/man/std::ranges::enumerate_view::sentinel::base.3 new file mode 100644 index 000000000..cf9dbbee6 --- /dev/null +++ b/man/std::ranges::enumerate_view::sentinel::base.3 @@ -0,0 +1,24 @@ +.TH std::ranges::enumerate_view::sentinel::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::sentinel::base \- std::ranges::enumerate_view::sentinel::base + +.SH Synopsis + constexpr ranges::sentinel_t base() const; (since C++23) + + Returns the underlying sentinel. Equivalent to return end_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying sentinel. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::sentinel::sentinel.3 b/man/std::ranges::enumerate_view::sentinel::sentinel.3 new file mode 100644 index 000000000..6b37e3f8f --- /dev/null +++ b/man/std::ranges::enumerate_view::sentinel::sentinel.3 @@ -0,0 +1,36 @@ +.TH std::ranges::enumerate_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::sentinel::sentinel \- std::ranges::enumerate_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + ranges::sentinel_t>; + private: + constexpr explicit /*sentinel*/( ranges::sentinel_t end \fB(3)\fP (exposition only*) + ); + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel with + ranges::sentinel_t(). + 2) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying sentinel end_ with std::move(other.end_). + 3) A private constructor which is used by enumerate_view::end. Move constructs the + end_ with std::move(end) This constructor is not accessible to users. + +.SH Parameters + + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::enumerate_view::size.3 b/man/std::ranges::enumerate_view::size.3 new file mode 100644 index 000000000..aab6117f0 --- /dev/null +++ b/man/std::ranges::enumerate_view::size.3 @@ -0,0 +1,50 @@ +.TH std::ranges::enumerate_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::enumerate_view::size \- std::ranges::enumerate_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fB(1)\fP (since C++23) + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP (since C++23) + + Returns the number of elements. Equivalent to return ranges::size(base_);, where + base_ is the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr static auto v1 = {1, 2, 3, 4, 5}; + constexpr auto ev1{v1 | std::views::enumerate}; + static_assert(ev1.size() == 5); + static_assert(std::ranges::sized_range); + + auto v2 = std::forward_list{1, 2, 3, 4, 5}; + auto ev2 {v2 | std::views::enumerate}; + static_assert(not std::ranges::sized_range); + // auto size = ev2.size(); // Error: v2 is not a sized range + assert(std::ranges::distance(v2) == 5); // OK, distance does not require sized + // range, but has O(N) complexity here + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::equal.3 b/man/std::ranges::equal.3 new file mode 100644 index 000000000..1b40d7e1a --- /dev/null +++ b/man/std::ranges::equal.3 @@ -0,0 +1,189 @@ +.TH std::ranges::equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::equal \- std::ranges::equal + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity > \fB(1)\fP (since + requires std::indirectly_comparable C++20) + constexpr bool + equal( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::indirectly_comparable, (since + ranges::iterator_t, \fB(2)\fP C++20) + Pred, Proj1, Proj2> + constexpr bool + + equal( R1&& r1, R2&& r2, Pred pred = {}, Proj1 proj1 = {}, Proj2 + proj2 = {} ); + + 1) Returns true if the projected values of the range [first1, last1) are equal to + the projected values of the range [first2, last2), and false otherwise. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + Two ranges are considered equal if they have the same number of elements and every + pair of corresponding projected elements satisfies pred. That is, std::invoke(pred, + std::invoke(proj1, *first1), std::invoke(proj2, *first2)) returns true for all pairs + of corresponding elements in both ranges. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - an iterator-sentinel pair denoting the first range of the elements + to compare + r1 - the first range of the elements to compare + first2, last2 - an iterator-sentinel pair denoting the second range of the elements + to compare + r2 - the second range of the elements to compare + pred - predicate to apply to the projected elements + proj1 - projection to apply to the first range of elements + proj2 - projection to apply to the second range of elements + +.SH Return value + + If the length of the range [first1, last1) does not equal the length of the range + [first2, last2), returns false. + + If the elements in the two ranges are equal after projection, returns true. + + Otherwise returns false. + +.SH Notes + + ranges::equal should not be used to compare the ranges formed by the iterators from + std::unordered_set, std::unordered_multiset, std::unordered_map, or + std::unordered_multimap because the order in which the elements are stored in those + containers may be different even if the two containers store the same elements. + + When comparing entire containers for equality, operator== for the corresponding + container are usually preferred. + +.SH Complexity + + At most min(last1 - first1, last2 - first2) applications of the predicate and + corresponding projections. + + However, if S1 and S2 both model std::sized_sentinel_for their respective iterators, + and last1 - first1 != last2 - first2 then no applications of the predicate are made + (size mismatch is detected without looking at any elements). + +.SH Possible implementation + +struct equal_fn +{ + template S1, + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr bool + operator()(I1 first1, S1 last1, I2 first2, S2 last2, + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + if constexpr (std::sized_sentinel_for and std::sized_sentinel_for) + if (std::ranges::distance(first1, last1) != std::ranges::distance(first2, last2)) + return false; + + for (; first1 != last1; ++first1, (void)++first2) + if (!std::invoke(pred, std::invoke(proj1, *first1), std::invoke(proj2, *first2))) + return false; + return true; + } + + template + requires std::indirectly_comparable, ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr bool + operator()(R1&& r1, R2&& r2, Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::ref(pred), std::ref(proj1), std::ref(proj2)); + } +}; + +inline constexpr equal_fn equal; + +.SH Example + + The following code uses ranges::equal to test if a string is a palindrome. + + +// Run this code + + #include + #include + #include + #include + #include + + constexpr bool is_palindrome(const std::string_view s) + { + namespace views = std::views; + auto forward = s | views::take(s.size() / 2); + auto backward = s | views::reverse | views::take(s.size() / 2); + return std::ranges::equal(forward, backward); + } + + void test(const std::string_view s) + { + std::cout << std::quoted(s) << " is " + << (is_palindrome(s) ? "" : "not ") + << "a palindrome\\n"; + } + + int main() + { + test("radar"); + test("hello"); + static_assert(is_palindrome("ABBA") and not is_palindrome("AC/DC")); + } + +.SH Output: + + "radar" is a palindrome + "hello" is not a palindrome + +.SH See also + + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::lexicographical_compare returns true if one range is lexicographically less + (C++20) than another + (niebloid) + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + ranges::equal_range returns range of elements matching a specific key + (C++20) (niebloid) + equal_to function object implementing x == y + \fI(class template)\fP + equal determines if two sets of elements are the same + \fI(function template)\fP diff --git a/man/std::ranges::equal_range.3 b/man/std::ranges::equal_range.3 new file mode 100644 index 000000000..26cc07ecb --- /dev/null +++ b/man/std::ranges::equal_range.3 @@ -0,0 +1,245 @@ +.TH std::ranges::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::equal_range \- std::ranges::equal_range + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class T, class Proj = std::identity, + std::indirect_strict_weak_order (since + > Comp = C++20) + ranges::less > (until + constexpr ranges::subrange equal_range( I first, S last, C++26) + const T& value, + + Comp comp = {}, + Proj proj = {} ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t, + std::indirect_strict_weak_order + > Comp = (since + ranges::less > C++26) + constexpr ranges::subrange equal_range( I first, S last, + const T& value, + + Comp comp = {}, + Proj proj = {} ); + template< ranges::forward_range R, + \fB(1)\fP + class T, class Proj = std::identity, + std::indirect_strict_weak_order + , C++20) + Proj>> Comp = (until + ranges::less > C++26) + constexpr ranges::borrowed_subrange_t + + equal_range( R&& r, const T& value, Comp comp = {}, Proj + proj = {} ); + template< ranges::forward_range R, \fB(2)\fP + + class Proj = std::identity, + class T = + std::projected_value_t, Proj>, + std::indirect_strict_weak_order + , C++26) + Proj>> Comp = + ranges::less > + constexpr ranges::borrowed_subrange_t + + equal_range( R&& r, const T& value, Comp comp = {}, Proj + proj = {} ); + + 1) Returns a view containing all elements equivalent to value in the range + [first, last). + + The range [first, last) must be at least partially ordered with respect to value, + i.e. it must satisfy all of the following requirements: + + * partitioned with respect to element < value or comp(element, value) (that is, + all elements for which the expression is true precedes all elements for which + the expression is false). + * partitioned with respect to !(value < element) or !comp(value, element). + * for all elements, if element < value or comp(element, value) is true then + !(value < element) or !comp(value, element) is also true. + + A fully-sorted range meets these criteria. + + The returned view is constructed from two iterators, one pointing to the first + element that is not less than value and another pointing to the first element + greater than value. The first iterator may be alternatively obtained with + std::ranges::lower_bound(), the second - with std::ranges::upper_bound(). + + 2) Same as \fB(1)\fP, but uses r as the source range, as if using the range + ranges::begin(r) as first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of the elements to examine + value - value to compare the elements to + comp - if the first argument is less than (i.e. is ordered before) the second + proj - projection to apply to the elements + +.SH Return value + + std::ranges::subrange containing a pair of iterators defining the wanted range, the + first pointing to the first element that is not less than value and the second + pointing to the first element greater than value. + + If there are no elements not less than value, the last iterator (iterator that is + equal to last or ranges::end(r)) is returned as the first element. Similarly if + there are no elements greater than value, the last iterator is returned as the + second element. + +.SH Complexity + + The number of comparisons performed is logarithmic in the distance between first and + last (at most 2 * log + 2(last - first) + O(1) comparisons). However, for an iterator that does not model + random_access_iterator, the number of iterator increments is linear. + +.SH Possible implementation + + struct equal_range_fn + { + template S, + class Proj = std::identity, class T = std::projected_value_t, + std::indirect_strict_weak_order + > Comp = ranges::less> + constexpr ranges::subrange + operator()(I first, S last, const T& value, Comp comp = {}, Proj proj = {}) const + { + return ranges::subrange + ( + ranges::lower_bound(first, last, value, std::ref(comp), std::ref(proj)), + ranges::upper_bound(first, last, value, std::ref(comp), std::ref(proj)) + ); + } + + template, Proj>, + std::indirect_strict_weak_order + , + Proj>> Comp = ranges::less> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, const T& value, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, + std::ref(comp), std::ref(proj)); + } + }; + + inline constexpr equal_range_fn equal_range; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct S + { + int number {}; + char name {}; + // note: name is ignored by these comparison operators + friend bool operator== (const S s1, const S s2) { return s1.number == s2.number; } + friend auto operator<=>(const S s1, const S s2) { return s1.number <=> s2.number; } + friend std::ostream& operator<<(std::ostream& os, S o) + { + return os << '{' << o.number << ", '" << o.name << "'}"; + } + }; + + void println(auto rem, const auto& v) + { + for (std::cout << rem; const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + // note: not ordered, only partitioned w.r.t. S defined below + std::vector vec + { + {1,'A'}, {2,'B'}, {2,'C'}, {2,'D'}, {4, 'D'}, {4,'G'}, {3,'F'} + }; + + const S value{2, '?'}; + + namespace ranges = std::ranges; + + auto a = ranges::equal_range(vec, value); + println("1. ", a); + + auto b = ranges::equal_range(vec.begin(), vec.end(), value); + println("2. ", b); + + auto c = ranges::equal_range(vec, 'D', ranges::less {}, &S::name); + println("3. ", c); + + auto d = ranges::equal_range(vec.begin(), vec.end(), 'D', ranges::less {}, &S::name); + println("4. ", d); + + using CD = std::complex; + std::vector nums{{1, 0}, {2, 2}, {2, 1}, {3, 0}, {3, 1}}; + auto cmpz = [](CD x, CD y) { return x.real() < y.real(); }; + #ifdef __cpp_lib_algorithm_default_value_type + auto p3 = ranges::equal_range(nums, {2, 0}, cmpz); + #else + auto p3 = ranges::equal_range(nums, CD{2, 0}, cmpz); + #endif + println("5. ", p3); + } + +.SH Output: + + 1. {2, 'B'} {2, 'C'} {2, 'D'} + 2. {2, 'B'} {2, 'C'} {2, 'D'} + 3. {2, 'D'} {4, 'D'} + 4. {2, 'D'} {4, 'D'} + 5. (2,2) (2,1) + +.SH See also + + ranges::lower_bound returns an iterator to the first element not less than the + (C++20) given value + (niebloid) + ranges::upper_bound returns an iterator to the first element greater than a + (C++20) certain value + (niebloid) + ranges::binary_search determines if an element exists in a partially-ordered range + (C++20) (niebloid) + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::equal determines if two sets of elements are the same + (C++20) (niebloid) + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::ranges::equal_to.3 b/man/std::ranges::equal_to.3 new file mode 100644 index 000000000..3b53e10b7 --- /dev/null +++ b/man/std::ranges::equal_to.3 @@ -0,0 +1,67 @@ +.TH std::ranges::equal_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::equal_to \- std::ranges::equal_to + +.SH Synopsis + Defined in header + struct equal_to; \fI(since C++20)\fP + + Function object for performing comparisons. The parameter types of the function call + operator (but not the return type) are deduced from the arguments. + +.SH Member functions + + operator() checks if the arguments are equal + \fI(public member function)\fP + +std::ranges::equal_to::operator() + + template< class T, class U > + constexpr bool operator()( T&& t, U&& u ) const; + + Given the expression std::forward(t) == std::forward(u) as expr: + + * If expr results in a call to built-in operator== comparing pointers, given the + composite pointer type of t and u as P: + + * For the two converted pointers (of type P), if one pointer precedes the other in + the implementation-defined strict total order over pointers, returns false, + otherwise returns true. + * If the conversion sequence from T to P or the conversion sequence from U to P is + not equality-preserving, the behavior is undefined. + * Otherwise: + + * Returns the result of expr. + * If std::equality_comparable_with is not modeled, the behavior is + undefined. + + This overload participates in overload resolution only if + std::equality_comparable_with is satisfied. + +.SH Notes + + Compared to std::equal_to, std::ranges::equal_to additionally requires != to be + valid, and that both argument types are required to be (homogeneously) comparable + with themselves (via the equality_comparable_with constraint). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + equal_to function object implementing x == y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::fill.3 b/man/std::ranges::fill.3 new file mode 100644 index 000000000..d4c33f167 --- /dev/null +++ b/man/std::ranges::fill.3 @@ -0,0 +1,151 @@ +.TH std::ranges::fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fill \- std::ranges::fill + +.SH Synopsis + Defined in header + Call signature + template< class T, std::output_iterator O, std::sentinel_for S > \fI(since C++20)\fP + constexpr O fill( O first, S last, const T& (until C++26) + value ); + template< class O, std::sentinel_for S, class + T = std::iter_value_t > + + requires std::output_iterator (since C++26) + + constexpr O fill( O first, S last, const T& + value ); \fB(1)\fP + template< class T, ranges::output_range R > \fI(since C++20)\fP + constexpr ranges::borrowed_iterator_t fill( (until C++26) + R&& r, const T& value ); + template< class R, class T = + std::range_value_t > \fB(2)\fP + + requires ranges::output_range (since C++26) + + constexpr ranges::borrowed_iterator_t fill( + R&& r, const T& value ); + + 1) Assigns the given value to the elements in the range [first, last). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to modify + r - the range of elements to modify + value - the value to be assigned + +.SH Return value + + An output iterator that compares equal to last. + +.SH Complexity + + Exactly last - first assignments. + +.SH Possible implementation + + struct fill_fn + { + template S, class T = std::iter_value_t> + requires std::output_iterator + constexpr O operator()(O first, S last, const T& value) const + { + while (first != last) + *first++ = value; + + return first; + } + + template> + requires ranges::output_range + constexpr ranges::borrowed_iterator_t operator()(R&& r, const T& value) const + { + return (*this)(ranges::begin(r), ranges::end(r), value); + } + }; + + inline constexpr fill_fn fill; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void println(const auto& seq) + { + for (const auto& e : seq) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + std::vector v{0, 1, 2, 3, 4, 5}; + + // set all elements to -1 using overload (1) + std::ranges::fill(v.begin(), v.end(), -1); + println(v); + + // set all element to 10 using overload (2) + std::ranges::fill(v, 10); + println(v); + + std::vector> nums{{1, 3}, {2, 2}, {4, 8}}; + println(nums); + #ifdef __cpp_lib_algorithm_default_value_type + std::ranges::fill(nums, {4, 2}); // T gets deduced + #else + std::ranges::fill(nums, std::complex{4, 2}); + #endif + println(nums); + } + +.SH Output: + + -1 -1 -1 -1 -1 -1 + 10 10 10 10 10 10 + (1,3) (2,2) (4,8) + (4,2) (4,2) (4,2) + +.SH See also + + ranges::fill_n assigns a value to a number of elements + (C++20) (niebloid) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::generate saves the result of a function in a range + (C++20) (niebloid) + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + ranges::generate_random fills a range with random numbers from a uniform random bit + (C++26) generator + (niebloid) + fill copy-assigns the given value to every element in a range + \fI(function template)\fP diff --git a/man/std::ranges::fill_n.3 b/man/std::ranges::fill_n.3 new file mode 100644 index 000000000..78dbc5ca6 --- /dev/null +++ b/man/std::ranges::fill_n.3 @@ -0,0 +1,125 @@ +.TH std::ranges::fill_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fill_n \- std::ranges::fill_n + +.SH Synopsis + Defined in header + Call signature + template< class T, std::output_iterator O > \fI(since C++20)\fP + constexpr O fill_n( O first, std::iter_difference_t n, const T& (until C++26) + value ); + template< class O, class T = std::iter_value_t > + + requires std::output_iterator (since C++26) + + constexpr O fill_n( O first, std::iter_difference_t n, const T& + value ); + + Assigns the given value to all elements in the range [first, first + n). + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to modify + n - number of elements to modify + value - the value to be assigned + +.SH Return value + + An output iterator that compares equal to first + n. + +.SH Complexity + + Exactly n assignments. + +.SH Possible implementation + + struct fill_n_fn + { + template> + requires std::output_iterator + constexpr O operator()(O first, std::iter_difference_t n, const T& value) const + { + for (std::iter_difference_t i {}; i != n; ++first, ++i) + *first = value; + return first; + } + }; + + inline constexpr fill_n_fn fill_n {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(const auto& v) + { + for (const auto& elem : v) + std::cout << ' ' << elem; + std::cout << '\\n'; + } + + int main() + { + constexpr auto n{8}; + + std::vector v(n, "▓▓░░"); + println(v); + + std::ranges::fill_n(v.begin(), n, "░░▓▓"); + println(v); + + std::vector> nums{{1, 3}, {2, 2}, {4, 8}}; + println(nums); + #ifdef __cpp_lib_algorithm_default_value_type + std::ranges::fill_n(nums.begin(), 2, {4, 2}); + #else + std::ranges::fill_n(nums.begin(), 2, std::complex{4, 2}); + #endif + println(nums); + } + +.SH Output: + + ▓▓░░ ▓▓░░ ▓▓░░ ▓▓░░ ▓▓░░ ▓▓░░ ▓▓░░ ▓▓░░ + ░░▓▓ ░░▓▓ ░░▓▓ ░░▓▓ ░░▓▓ ░░▓▓ ░░▓▓ ░░▓▓ + (1,3) (2,2) (4,8) + (4,2) (4,2) (4,8) + +.SH See also + + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) + ranges::generate saves the result of a function in a range + (C++20) (niebloid) + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + ranges::generate_random fills a range with random numbers from a uniform random bit + (C++26) generator + (niebloid) + fill_n copy-assigns the given value to N elements in a range + \fI(function template)\fP diff --git a/man/std::ranges::filter_view::iterator.3 b/man/std::ranges::filter_view::iterator.3 new file mode 100644 index 000000000..ea0538fb2 --- /dev/null +++ b/man/std::ranges::filter_view::iterator.3 @@ -0,0 +1,193 @@ +.TH std::ranges::filter_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::filter_view::iterator \- std::ranges::filter_view::iterator + +.SH Synopsis + class /*iterator*/; \fI(since C++20)\fP + (exposition only*) + + The return type of filter_view::begin. + + This is a bidirectional_iterator if V models bidirectional_range, a forward_iterator + if V models forward_range, and input_iterator otherwise. + + Modification of the element denoted by this iterator is permitted, but results in + undefined behavior if the resulting value does not satisfy the filter's predicate. + +.SH Member types + + Member type Definition + * std::bidirectional_iterator_tag, if V models + iterator_concept bidirectional_range, + * std::forward_iterator_tag, if V models forward_iterator, + * std::input_iterator_tag otherwise. + Defined if and only if V models forward_range. Let C be the type + std::iterator_traits>::iterator_category. + + iterator_category * std::bidirectional_iterator_tag, if C models + std::derived_from, + * std::forward_iterator_tag, if C models + std::derived_from, + * C otherwise. + value_type ranges::range_value_t + difference_type ranges::range_difference_t + + Data members + + Member name Definition + An iterator of type ranges::iterator_t into the underlying + current_ (private) view. + (exposition-only member object*) + A pointer of type ranges::filter_view* to the parent + parent_ (private) filter_view object. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + base returns the underlying iterator + (C++20) \fI(public member function)\fP + operator* forwards to the underlying iterator + operator-> \fI(public member function)\fP + (C++20) + operator++ advances the iterator + operator++(int) \fI(public member function)\fP + (C++20) + operator-- decrements the iterator + operator--(int) \fI(public member function)\fP + (C++20) + +std::ranges::filter_view::iterator::iterator + + /*iterator*/() (since + requires std::default_initializable> = \fB(1)\fP C++20) + default; + constexpr /*iterator*/( filter_view& parent, \fB(2)\fP (since + ranges::iterator_t current ); C++20) + + 1) Initializes current_ and parent_ with their default member initializers, which + are = ranges::iterator_t() and = nullptr respectively. + 2) Initializes current_ with std::move(current) and parent_ with + std::addressof(parent). + +std::ranges::filter_view::iterator::base + + constexpr const ranges::iterator_t& base() const & noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr ranges::iterator_t base() &&; \fB(2)\fP \fI(since C++20)\fP + + 1) Equivalent to return current_;. + 2) Equivalent to return std::move(current_);. + +std::ranges::filter_view::iterator::operator*,-> + + constexpr ranges::range_reference_t operator*() const; \fB(1)\fP \fI(since C++20)\fP + constexpr ranges::iterator_t operator->() const + + requires /*has-arrow*/> && \fB(2)\fP \fI(since C++20)\fP + + std::copyable>; + + 1) Equivalent to return *current_;. + 2) Equivalent to return current_;. + For a type I, /*has-arrow*/ is modeled or satisfied, if and only if I models or + satisfies input_iterator respectively, and either I is a pointer type or requires(I + i){ i.operator->();} is true. + +std::ranges::filter_view::iterator::operator++ + + constexpr /*iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr void operator++( int ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*iterator*/ operator++( int ) \fB(3)\fP \fI(since C++20)\fP + requires ranges::forward_range; + + 1) Equivalent to + current_ = ranges::find_if(std::move(++current_), ranges::end(parent_->base_), + + std::ref(*parent_->pred_)); + + return *this;. + 2) Equivalent to ++*this;. + 3) Equivalent to auto tmp = *this; ++*this; return tmp;. + +std::ranges::filter_view::iterator::operator-- + + constexpr /*iterator*/& operator--() \fB(1)\fP \fI(since C++20)\fP + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(2)\fP \fI(since C++20)\fP + requires ranges::bidirectional_range; + + 1) Equivalent to + do + + --current_; + while (!std::invoke(*parent_->pred_, *current_)); + + return *this;. + 2) Equivalent to auto tmp = *this; --*this; return tmp;. + +.SH Non-member functions + + operator== compares the underlying iterators + (C++20) \fI(function)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function)\fP + +operator==(std::ranges::filter_view::iterator) + + friend constexpr bool operator==( const /*iterator*/& x, const + /*iterator*/& y ) \fI(since C++20)\fP + requires std::equality_comparable>; + + Equivalent to return x.current_ == y.current_;. + + The != operator is synthesized from operator==. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::ranges::filter_view::iterator + is an associated class of the arguments. + +iter_move(std::ranges::filter_view::iterator) + + friend constexpr ranges::range_rvalue_reference_t + + iter_move( const /*iterator*/& i ) \fI(since C++20)\fP + + noexcept(noexcept(ranges::iter_move(i.current_))); + + Equivalent to return ranges::iter_move(i.current_);. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::ranges::filter_view::iterator + is an associated class of the arguments. + +iter_swap(std::ranges::filter_view::iterator) + + friend constexpr void iter_swap( const /*iterator*/& x, const + /*iterator*/& y ) + \fI(since C++20)\fP + noexcept(noexcept(ranges::iter_swap(x.current_, y.current_))) + + requires std::indirectly_swappable>; + + Equivalent to ranges::iter_swap(x.current_, y.current_). + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::ranges::filter_view::iterator + is an associated class of the arguments. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2259R1 C++20 member type iterator_category was defined only if V is a + always defined forward_range + LWG 3533 C++20 the const& overload of base copied returns a reference to it + the underlying iterator + LWG 3593 C++20 the const& overload of base might not made noexcept + be noexcept diff --git a/man/std::ranges::filter_view::sentinel.3 b/man/std::ranges::filter_view::sentinel.3 new file mode 100644 index 000000000..18eef52b0 --- /dev/null +++ b/man/std::ranges::filter_view::sentinel.3 @@ -0,0 +1,51 @@ +.TH std::ranges::filter_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::filter_view::sentinel \- std::ranges::filter_view::sentinel + +.SH Synopsis + class /*sentinel*/; \fI(since C++20)\fP + (exposition only*) + + The return type of filter_view::end when the underlying view type (V) does not model + common_range. + +.SH Member functions + + constructor constructs a sentinel + (C++20) \fI(public member function)\fP + base returns the underlying sentinel + (C++20) \fI(public member function)\fP + +std::ranges::filter_view::sentinel::sentinel + + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( filter_view& parent ); \fB(2)\fP \fI(since C++20)\fP + + 1) Value-initializes end_ via its default member initializer (= + ranges::sentinel_t()). + 2) Initializes end_ with ranges::end(parent.base_). + +std::ranges::filter_view::sentinel::base + + constexpr ranges::sentinel_t base() const; \fI(since C++20)\fP + + Equivalent to return end_;. + +.SH Non-member functions + + operator== compares the underlying iterator and the underlying sentinel + (C++20) \fI(function)\fP + +operator==(std::ranges::filter_view::iterator, std::ranges::filter_view::sentinel) + + friend constexpr bool operator==( const /*iterator*/& x, \fI(since C++20)\fP + const /*sentinel*/& y ); + + Equivalent to return x.current_ == y.end_;, where current_ is the underlying + iterator wrapped in filter_view::iterator. + + The != operator is synthesized from operator==. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::ranges::filter_view::sentinel + is an associated class of the arguments. diff --git a/man/std::ranges::find,std::ranges::find_if,std::ranges::find_if_not.3 b/man/std::ranges::find,std::ranges::find_if,std::ranges::find_if_not.3 new file mode 100644 index 000000000..fcceb46d2 --- /dev/null +++ b/man/std::ranges::find,std::ranges::find_if,std::ranges::find_if_not.3 @@ -0,0 +1,324 @@ +.TH std::ranges::find,std::ranges::find_if,std::ranges::find_if_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::find,std::ranges::find_if,std::ranges::find_if_not \- std::ranges::find,std::ranges::find_if,std::ranges::find_if_not + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + class T, class Proj = std::identity > (since + requires std::indirect_binary_predicate C++20) + , (until + const T*> C++26) + + constexpr I find( I first, S last, const T& value, Proj proj + = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t > + requires std::indirect_binary_predicate (since + , C++26) + const T*> + + constexpr I find( I first, S last, const T& value, Proj proj + = {} ); + template< ranges::input_range R, class T, class Proj = + std::identity > + + requires std::indirect_binary_predicate (since + , Proj>, (until + const T*> C++26) + constexpr ranges::borrowed_iterator_t + + find( R&& r, const T& value, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + class T = + std::projected_value_t, Proj> > + requires std::indirect_binary_predicate (since + , Proj>, \fB(1)\fP + const T*> + constexpr ranges::borrowed_iterator_t + + find( R&& r, const T& value, Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> Pred > C++20) + \fB(2)\fP + constexpr I find_if( I first, S last, Pred pred, Proj proj = + {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate + , Proj>> \fB(4)\fP (since + Pred > C++20) + constexpr ranges::borrowed_iterator_t + + find_if( R&& r, Pred pred, Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> Pred > C++20) + + constexpr I find_if_not( I first, S last, Pred pred, Proj + proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate + , Proj>> \fB(6)\fP (since + Pred > C++20) + constexpr ranges::borrowed_iterator_t + + find_if_not( R&& r, Pred pred, Proj proj = {} ); + + Returns the first element in the range [first, last) that satisfies specific + criteria: + + 1) find searches for an element equal to value. + 3) find_if searches for an element for which predicate pred returns true. + 5) find_if_not searches for an element for which predicate pred returns false. + 2,4,6) Same as (1,3,5), but uses r as the source range, as if using ranges::begin(r) + as first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of the elements to examine + value - value to compare the elements to + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Iterator to the first element satisfying the condition or iterator equal to last if + no such element is found. + +.SH Complexity + + At most last - first applications of the predicate and projection. + +.SH Possible implementation + + find + struct find_fn + { + template S, + class Proj = std::identity, + class T = std::projected_value_t> + requires std::indirect_binary_predicate + , const T*> + constexpr I operator()(I first, S last, const T& value, Proj proj = {}) const + { + for (; first != last; ++first) + if (std::invoke(proj, *first) == value) + return first; + return first; + } + + template + requires std::indirect_binary_predicate, Proj>, const T*> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, const T& value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, std::ref(proj)); + } + }; + + inline constexpr find_fn find; + find_if + struct find_if_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr I operator()(I first, S last, Pred pred, Proj proj = {}) const + { + for (; first != last; ++first) + if (std::invoke(pred, std::invoke(proj, *first))) + return first; + return first; + } + + template, Proj>> Pred> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr find_if_fn find_if; + find_if_not + struct find_if_not_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr I operator()(I first, S last, Pred pred, Proj proj = {}) const + { + for (; first != last; ++first) + if (!std::invoke(pred, std::invoke(proj, *first))) + return first; + return first; + } + + template, Proj>> Pred> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr find_if_not_fn find_if_not; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + void projector_example() + { + struct folk_info + { + unsigned uid; + std::string name, position; + }; + + std::vector folks + { + {0, "Ana", "dev"}, + {1, "Bob", "devops"}, + {2, "Eve", "ops"} + }; + + const auto who{"Eve"}; + if (auto it = std::ranges::find(folks, who, &folk_info::name); it != folks.end()) + std::cout << std::format("Profile:\\n" + " UID: {}\\n" + " Name: {}\\n" + " Position: {}\\n\\n", + it->uid, it->name, it->position); + } + + int main() + { + namespace ranges = std::ranges; + + projector_example(); + + const int n1 = 3; + const int n2 = 5; + const auto v = {4, 1, 3, 2}; + + if (ranges::find(v, n1) != v.end()) + std::cout << "v contains: " << n1 << '\\n'; + else + std::cout << "v does not contain: " << n1 << '\\n'; + + if (ranges::find(v.begin(), v.end(), n2) != v.end()) + std::cout << "v contains: " << n2 << '\\n'; + else + std::cout << "v does not contain: " << n2 << '\\n'; + + auto is_even = [](int x) { return x % 2 == 0; }; + + if (auto result = ranges::find_if(v.begin(), v.end(), is_even); result != v.end()) + std::cout << "First even element in v: " << *result << '\\n'; + else + std::cout << "No even elements in v\\n"; + + if (auto result = ranges::find_if_not(v, is_even); result != v.end()) + std::cout << "First odd element in v: " << *result << '\\n'; + else + std::cout << "No odd elements in v\\n"; + + auto divides_13 = [](int x) { return x % 13 == 0; }; + + if (auto result = ranges::find_if(v, divides_13); result != v.end()) + std::cout << "First element divisible by 13 in v: " << *result << '\\n'; + else + std::cout << "No elements in v are divisible by 13\\n"; + + if (auto result = ranges::find_if_not(v.begin(), v.end(), divides_13); + result != v.end()) + std::cout << "First element indivisible by 13 in v: " << *result << '\\n'; + else + std::cout << "All elements in v are divisible by 13\\n"; + + std::vector> nums{{4, 2}}; + #ifdef __cpp_lib_algorithm_default_value_type + // T gets deduced in (2) making list-initialization possible + const auto it = ranges::find(nums, {4, 2}); + #else + const auto it = ranges::find(nums, std::complex{4, 2}); + #endif + assert(it == nums.begin()); + } + +.SH Output: + + Profile: + UID: 2 + Name: Eve + Position: ops + + v contains: 3 + v does not contain: 5 + First even element in v: 4 + First odd element in v: 1 + No elements in v are divisible by 13 + First element indivisible by 13 in v: 4 + +.SH See also + + ranges::adjacent_find finds the first two adjacent items that are equal (or satisfy + (C++20) a given predicate) + (niebloid) + ranges::find_end finds the last sequence of elements in a certain range + (C++20) (niebloid) + ranges::find_first_of searches for any one of a set of elements + (C++20) (niebloid) + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + find + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP + \fI(C++11)\fP diff --git a/man/std::ranges::find_end.3 b/man/std::ranges::find_end.3 new file mode 100644 index 000000000..08804c96d --- /dev/null +++ b/man/std::ranges::find_end.3 @@ -0,0 +1,226 @@ +.TH std::ranges::find_end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::find_end \- std::ranges::find_end + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I1, std::sentinel_for S1, + + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, (since + class Proj2 = std::identity > \fB(1)\fP C++20) + requires std::indirectly_comparable + constexpr ranges::subrange + find_end( I1 first1, S1 last1, I2 first2, S2 last2, + + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::forward_range R1, ranges::forward_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, + class Proj2 = std::identity > + requires std::indirectly_comparable, \fB(2)\fP (since + ranges::iterator_t, C++20) + Pred, Proj1, Proj2> + constexpr ranges::borrowed_subrange_t + find_end( R1&& r1, R2&& r2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + + 1) Searches for the last occurrence of the sequence [first2, last2) in the range + [first1, last1), after projection with proj1 and proj2 respectively. The projected + elements are compared using the binary predicate pred. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the range of elements to examine (aka haystack) + first2, last2 - the range of elements to search for (aka needle) + r1 - the range of elements to examine (aka haystack) + r2 - the range of elements to search for (aka needle) + pred - binary predicate to compare the elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + 1) ranges::subrange{} value initialized with expression {i, i + (i == last1 ? 0 + : ranges::distance(first2, last2))} that denotes the last occurrence of the sequence + [first2, last2) in range [first1, last1) (after projections with proj1 and proj2). + If [first2, last2) is empty or if no such sequence is found, the return value is + effectively initialized with {last1, last1}. + 2) Same as \fB(1)\fP, except that the return type is ranges::borrowed_subrange_t. + +.SH Complexity + + At most \\(\\scriptsize S\\cdot(N-S+1)\\)S·(N-S+1) applications of the corresponding + predicate and each projection, where \\(\\scriptsize S\\)S is ranges::distance(first2, + last2) and \\(\\scriptsize N\\)N is ranges::distance(first1, last1) for \fB(1)\fP, or + \\(\\scriptsize S\\)S is ranges::distance(r2) and \\(\\scriptsize N\\)N is + ranges::distance(r1) for \fB(2)\fP. + +.SH Notes + + An implementation can improve efficiency of the search if the input iterators model + std::bidirectional_iterator by searching from the end towards the begin. Modelling + the std::random_access_iterator may improve the comparison speed. All this however + does not change the theoretical complexity of the worst case. + +.SH Possible implementation + + struct find_end_fn + { + template S1, + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr ranges::subrange + operator()(I1 first1, S1 last1, + I2 first2, S2 last2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + if (first2 == last2) + { + auto last_it = ranges::next(first1, last1); + return {last_it, last_it}; + } + auto result = ranges::search( + std::move(first1), last1, first2, last2, pred, proj1, proj2); + + if (result.empty()) + return result; + + for (;;) + { + auto new_result = ranges::search( + std::next(result.begin()), last1, first2, last2, pred, proj1, proj2); + if (new_result.empty()) + return result; + else + result = std::move(new_result); + } + } + + template + requires std::indirectly_comparable, + ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr ranges::borrowed_subrange_t + operator()(R1&& r1, R2&& r2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(pred), + std::move(proj1), std::move(proj2)); + } + }; + + inline constexpr find_end_fn find_end {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(const auto haystack, const auto needle) + { + const auto pos = std::distance(haystack.begin(), needle.begin()); + std::cout << "In \\""; + for (const auto c : haystack) + std::cout << c; + std::cout << "\\" found \\""; + for (const auto c : needle) + std::cout << c; + std::cout << "\\" at position [" << pos << ".." << pos + needle.size() << ")\\n" + << std::string(4 + pos, ' ') << std::string(needle.size(), '^') << '\\n'; + } + + int main() + { + using namespace std::literals; + constexpr auto secret{"password password word..."sv}; + constexpr auto wanted{"password"sv}; + + constexpr auto found1 = std::ranges::find_end( + secret.cbegin(), secret.cend(), wanted.cbegin(), wanted.cend()); + print(secret, found1); + + constexpr auto found2 = std::ranges::find_end(secret, "word"sv); + print(secret, found2); + + const auto found3 = std::ranges::find_end(secret, "ORD"sv, + [](const char x, const char y) { // uses a binary predicate + return std::tolower(x) == std::tolower(y); + }); + print(secret, found3); + + const auto found4 = std::ranges::find_end(secret, "SWORD"sv, {}, {}, + [](char c) { return std::tolower(c); }); // projects the 2nd range + print(secret, found4); + + static_assert(std::ranges::find_end(secret, "PASS"sv).empty()); // => not found + } + +.SH Output: + + In "password password word..." found "password" at position [9..17) + ^^^^^^^^ + In "password password word..." found "word" at position [18..22) + ^^^^ + In "password password word..." found "ord" at position [19..22) + ^^^ + In "password password word..." found "sword" at position [12..17) + ^^^^^ + +.SH See also + + ranges::find_last + ranges::find_last_if + ranges::find_last_if_not finds the last element satisfying specific criteria + (C++23) (niebloid) + (C++23) + (C++23) + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::find_first_of searches for any one of a set of elements + (C++20) (niebloid) + ranges::adjacent_find finds the first two adjacent items that are equal (or + (C++20) satisfy a given predicate) + (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + ranges::search_n searches for a number consecutive copies of an element in a + (C++20) range + (niebloid) + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP diff --git a/man/std::ranges::find_first_of.3 b/man/std::ranges::find_first_of.3 new file mode 100644 index 000000000..57021d522 --- /dev/null +++ b/man/std::ranges::find_first_of.3 @@ -0,0 +1,176 @@ +.TH std::ranges::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::find_first_of \- std::ranges::find_first_of + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, + class Proj2 = std::identity > \fB(1)\fP (since + requires std::indirectly_comparable C++20) + constexpr I1 + find_first_of( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = + {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::forward_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, + class Proj2 = std::identity > + requires std::indirectly_comparable, \fB(2)\fP (since + ranges::iterator_t, C++20) + Pred, Proj1, Proj2> + constexpr ranges::borrowed_iterator_t + find_first_of( R1&& r1, R2&& r2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + + 1) Searches the range [first1, last1) for any of the elements in the range + [first2, last2), after projecting the ranges with proj1 and proj2 respectively. The + projected elements are compared using the binary predicate pred. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the range of elements to examine (aka haystack) + first2, last2 - the range of elements to search for (aka needles) + r1 - the range of elements to examine (aka haystack) + r2 - the range of elements to search for (aka needles) + pred - binary predicate to compare the elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + Iterator to the first element in the range [first1, last1) that is equal to an + element from the range [first2, last2) after projection. If no such element is + found, an iterator comparing equal to last1 is returned. + +.SH Complexity + + At most S * N applications of the predicate and each projection, where + \fB(1)\fP S = ranges::distance(first2, last2) and N = ranges::distance(first1, last1); + \fB(2)\fP S = ranges::distance(r2) and N = ranges::distance(r1). + +.SH Possible implementation + +struct find_first_of_fn +{ + template S1, + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, + class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr I1 operator()(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; first1 != last1; ++first1) + for (auto i = first2; i != last2; ++i) + if (std::invoke(pred, std::invoke(proj1, *first1), std::invoke(proj2, *i))) + return first1; + return first1; + } + + template + requires std::indirectly_comparable, + ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr ranges::borrowed_iterator_t + operator()(R1&& r1, R2&& r2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(pred), std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr find_first_of_fn find_first_of {}; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + namespace rng = std::ranges; + + constexpr static auto haystack = {1, 2, 3, 4}; + constexpr static auto needles = {0, 3, 4, 3}; + + constexpr auto found1 = rng::find_first_of(haystack.begin(), haystack.end(), + needles.begin(), needles.end()); + static_assert(std::distance(haystack.begin(), found1) == 2); + + constexpr auto found2 = rng::find_first_of(haystack, needles); + static_assert(std::distance(haystack.begin(), found2) == 2); + + constexpr static auto negatives = {-6, -3, -4, -3}; + constexpr auto not_found = rng::find_first_of(haystack, negatives); + static_assert(not_found == haystack.end()); + + constexpr auto found3 = rng::find_first_of(haystack, negatives, + [](int x, int y) { return x == -y; }); // uses a binary comparator + static_assert(std::distance(haystack.begin(), found3) == 2); + + struct P { int x, y; }; + constexpr static auto p1 = {P{1, -1}, P{2, -2}, P{3, -3}, P{4, -4}}; + constexpr static auto p2 = {P{5, -5}, P{6, -3}, P{7, -5}, P{8, -3}}; + + // Compare only P::y data members by projecting them: + const auto found4 = rng::find_first_of(p1, p2, {}, &P::y, &P::y); + std::cout << "First equivalent element {" << found4->x << ", " << found4->y + << "} was found at position " << std::distance(p1.begin(), found4) + << ".\\n"; + } + +.SH Output: + + First equivalent element {3, -3} was found at position 2. + +.SH See also + + find_first_of searches for any one of a set of elements + \fI(function template)\fP + ranges::adjacent_find finds the first two adjacent items that are equal (or satisfy + (C++20) a given predicate) + (niebloid) + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::find_end finds the last sequence of elements in a certain range + (C++20) (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + ranges::search_n searches for a number consecutive copies of an element in a + (C++20) range + (niebloid) diff --git a/man/std::ranges::find_last,std::ranges::find_last_if,std::ranges::find_last_if_not.3 b/man/std::ranges::find_last,std::ranges::find_last_if,std::ranges::find_last_if_not.3 new file mode 100644 index 000000000..1f076baf7 --- /dev/null +++ b/man/std::ranges::find_last,std::ranges::find_last_if,std::ranges::find_last_if_not.3 @@ -0,0 +1,358 @@ +.TH std::ranges::find_last,std::ranges::find_last_if,std::ranges::find_last_if_not 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::find_last,std::ranges::find_last_if,std::ranges::find_last_if_not \- std::ranges::find_last,std::ranges::find_last_if,std::ranges::find_last_if_not + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class T, + class Proj = std::identity > (since + requires std::indirect_binary_predicate, (until + const T*> C++26) + constexpr ranges::subrange + + find_last( I first, S last, const T& value, Proj proj = {} ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t > + requires std::indirect_binary_predicate, C++26) + const T*> + constexpr ranges::subrange + + find_last( I first, S last, const T& value, Proj proj = {} ); + template< ranges::forward_range R, + + class T, + class Proj = std::identity > (since + requires std::indirect_binary_predicate, Proj>, C++26) + const T*> + constexpr ranges::borrowed_subrange_t + + find_last( R&& r, const T& value, Proj proj = {} ); + template< ranges::forward_range R, + + class Proj = std::identity, + class T = std::projected_value_t, Proj> > + requires std::indirect_binary_predicate, Proj>, \fB(1)\fP + const T*> + constexpr ranges::borrowed_subrange_t + + find_last( R&& r, const T& value, Proj proj = {} ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(3)\fP (since + Pred > C++23) + constexpr ranges::subrange \fB(2)\fP + + find_last_if( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + + std::indirect_unary_predicate, (since + Proj>> \fB(4)\fP C++23) + Pred > + constexpr ranges::borrowed_subrange_t + + find_last_if( R&& r, Pred pred, Proj proj = {} ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(5)\fP (since + Pred > C++23) + constexpr ranges::subrange + + find_last_if_not( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + + std::indirect_unary_predicate, (since + Proj>> \fB(6)\fP C++23) + Pred > + constexpr ranges::borrowed_subrange_t + + find_last_if_not( R&& r, Pred pred, Proj proj = {} ); + + Returns the last element in the range [first, last) that satisfies specific + criteria: + + 1) find_last searches for an element equal to value. + 3) find_last_if searches for the last element in the range [first, last) for which + predicate pred returns true. + 5) find_last_if_not searches for the last element in the range [first, last) for + which predicate pred returns false. + 2,4,6) Same as (1,3,5), but uses r as the source range, as if using ranges::begin(r) + as first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of the elements to examine + value - value to compare the elements to + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1,2,3) Let i be the last iterator in the range [first, last) for which E is true. + Returns ranges::subrange{i, last}, or ranges::subrange{last, last} if no such + iterator is found. + 2,4,6) Same as (1,2,3) but the return type is ranges::borrowed_subrange_t. + +.SH Complexity + + At most last - first applications of the predicate and projection. + +.SH Notes + + ranges::find_last, ranges::find_last_if, ranges::find_last_if_not have better + efficiency on common implementations if I models bidirectional_iterator or (better) + random_access_iterator. + + Feature-test macro Value Std Feature + ranges::find_last, + __cpp_lib_ranges_find_last 202207L (C++23) ranges::find_last_if, + ranges::find_last_if_not + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Possible implementation + + These implementations only show the slower algorithm used when I models + forward_iterator. + + find_last (1-2) + struct find_last_fn + { + template S, + class Proj = std::identity, + class T = std::projected_value_t, Proj>> + requires std::indirect_binary_predicate, + const T*> + constexpr ranges::subrange + operator()(I first, S last, const T &value, Proj proj = {}) const + { + // Note: if I is mere forward_iterator, we may only go from begin to end. + I found {}; + for (; first != last; ++first) + if (std::invoke(proj, *first) == value) + found = first; + + if (found == I {}) + return {first, first}; + + return {found, std::ranges::next(found, last)}; + } + + template, Proj>> + requires std::indirect_binary_predicate, Proj>, + const T*> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, const T &value, Proj proj = {}) const + { + return this->operator()(ranges::begin(r), ranges::end(r), value, std::ref(proj)); + } + }; + + inline constexpr find_last_fn find_last; + find_last_if (3-4) + struct find_last_if_fn + { + template S, + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr ranges::subrange + operator()(I first, S last, Pred pred, Proj proj = {}) const + { + // Note: if I is mere forward_iterator, we may only go from begin to end. + I found {}; + for (; first != last; ++first) + if (std::invoke(pred, std::invoke(proj, *first))) + found = first; + + if (found == I {}) + return {first, first}; + + return {found, std::ranges::next(found, last)}; + } + + template, Proj>> + Pred> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return this->operator()(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr find_last_if_fn find_last_if; + find_last_if_not (5-6) + struct find_last_if_not_fn + { + template S, + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr ranges::subrange + operator()(I first, S last, Pred pred, Proj proj = {}) const + { + // Note: if I is mere forward_iterator, we may only go from begin to end. + I found {}; + for (; first != last; ++first) + if (!std::invoke(pred, std::invoke(proj, *first))) + found = first; + + if (found == I {}) + return {first, first}; + + return {found, std::ranges::next(found, last)}; + } + + template, Proj>> + Pred> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return this->operator()(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr find_last_if_not_fn find_last_if_not; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + constexpr static auto v = {1, 2, 3, 1, 2, 3, 1, 2}; + + { + constexpr auto i1 = ranges::find_last(v.begin(), v.end(), 3); + constexpr auto i2 = ranges::find_last(v, 3); + static_assert(ranges::distance(v.begin(), i1.begin()) == 5); + static_assert(ranges::distance(v.begin(), i2.begin()) == 5); + } + { + constexpr auto i1 = ranges::find_last(v.begin(), v.end(), -3); + constexpr auto i2 = ranges::find_last(v, -3); + static_assert(i1.begin() == v.end()); + static_assert(i2.begin() == v.end()); + } + + auto abs = [](int x) { return x < 0 ? -x : x; }; + + { + auto pred = [](int x) { return x == 3; }; + constexpr auto i1 = ranges::find_last_if(v.begin(), v.end(), pred, abs); + constexpr auto i2 = ranges::find_last_if(v, pred, abs); + static_assert(ranges::distance(v.begin(), i1.begin()) == 5); + static_assert(ranges::distance(v.begin(), i2.begin()) == 5); + } + { + auto pred = [](int x) { return x == -3; }; + constexpr auto i1 = ranges::find_last_if(v.begin(), v.end(), pred, abs); + constexpr auto i2 = ranges::find_last_if(v, pred, abs); + static_assert(i1.begin() == v.end()); + static_assert(i2.begin() == v.end()); + } + + { + auto pred = [](int x) { return x == 1 or x == 2; }; + constexpr auto i1 = ranges::find_last_if_not(v.begin(), v.end(), pred, abs); + constexpr auto i2 = ranges::find_last_if_not(v, pred, abs); + static_assert(ranges::distance(v.begin(), i1.begin()) == 5); + static_assert(ranges::distance(v.begin(), i2.begin()) == 5); + } + { + auto pred = [](int x) { return x == 1 or x == 2 or x == 3; }; + constexpr auto i1 = ranges::find_last_if_not(v.begin(), v.end(), pred, abs); + constexpr auto i2 = ranges::find_last_if_not(v, pred, abs); + static_assert(i1.begin() == v.end()); + static_assert(i2.begin() == v.end()); + } + + using P = std::pair; + std::forward_list

list + { + {"one", 1}, {"two", 2}, {"three", 3}, + {"one", 4}, {"two", 5}, {"three", 6}, + }; + auto cmp_one = [](const std::string_view &s) { return s == "one"; }; + + // find latest element that satisfy the comparator, and projecting pair::first + const auto subrange = ranges::find_last_if(list, cmp_one, &P::first); + + // print the found element and the "tail" after it + for (P const& e : subrange) + std::cout << '{' << std::quoted(e.first) << ", " << e.second << "} "; + std::cout << '\\n'; + + #if __cpp_lib_algorithm_default_value_type + const auto i3 = ranges::find_last(list, {"three", 3}); // (2) C++26 + #else + const auto i3 = ranges::find_last(list, P{"three", 3}); // (2) C++23 + #endif + assert(i3.begin()->first == "three" && i3.begin()->second == 3); + } + +.SH Output: + + {"one", 4} {"two", 5} {"three", 6} + +.SH See also + + ranges::find_end finds the last sequence of elements in a certain range + (C++20) (niebloid) + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::search searches for a range of elements + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of another + (C++20) (niebloid) + ranges::binary_search determines if an element exists in a partially-ordered + (C++20) range + (niebloid) + ranges::contains + ranges::contains_subrange checks if the range contains the given element or subrange + (C++23) (niebloid) + (C++23) diff --git a/man/std::ranges::fold_left.3 b/man/std::ranges::fold_left.3 new file mode 100644 index 000000000..5a0ad59c1 --- /dev/null +++ b/man/std::ranges::fold_left.3 @@ -0,0 +1,259 @@ +.TH std::ranges::fold_left 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fold_left \- std::ranges::fold_left + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for + S, class T, + (since + /* indirectly-binary-left-foldable */ C++23) + F > (until + C++26) + constexpr auto fold_left( I first, S last, T init, F + f ); + template< std::input_iterator I, std::sentinel_for + S, + + class T = std::iter_value_t, (since + /* indirectly-binary-left-foldable */ C++26) + F > + + constexpr auto fold_left( I first, S last, T init, F + f ); \fB(1)\fP + template< ranges::input_range R, class T, + + /* indirectly-binary-left-foldable */ (since C++23) + > F > (until C++26) + + constexpr auto fold_left( R&& r, T init, F f ); + template< ranges::input_range R, class T = + ranges::range_value_t, + \fB(2)\fP + /* indirectly-binary-left-foldable */ (since C++26) + > F > + + constexpr auto fold_left( R&& r, T init, F f ); + Helper concepts + template< class F, class T, class I > (exposition + concept /* indirectly-binary-left-foldable */ = /* \fB(3)\fP only*) + see description */; + + Left-folds the elements of given range, that is, returns the result of evaluation of + the chain expression: + f(f(f(f(init, x[1]), x[2]), ...), x[n]), where x[1], x[2], ..., x[n] are elements of + the range. + + Informally, ranges::fold_left behaves like std::accumulate's overload that accepts a + binary predicate. + + The behavior is undefined if [first, last) is not a valid range. + + 1) The range is [first, last). Equivalent to return + ranges::fold_left_with_iter(std::move(first), last, std::move(init), f).value. + 2) Same as \fB(1)\fP, except that uses r as the range, as if by using ranges::begin(r) as + first and ranges::end(r) as last. + 3) Equivalent to: + + Helper concepts + template< class F, class T, class I, class U > + + concept /*indirectly-binary-left-foldable-impl*/ = + std::movable && + std::movable && + std::convertible_to && (3A) (exposition only*) + std::invocable> && + std::assignable_from>>; + template< class F, class T, class I > + + concept /*indirectly-binary-left-foldable*/ = + std::copy_constructible && + std::indirectly_readable && + std::invocable> && + std::convertible_to>, + std::decay_t>>> && + /*indirectly-binary-left-foldable-impl*/>>>; + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to fold + r - the range of elements to fold + init - the initial value of the fold + f - the binary function object + +.SH Return value + + An object of type U that contains the result of left-fold of the given range over f, + where U is equivalent to std::decay_t>>. + + If the range is empty, U(std::move(init)) is returned. + +.SH Possible implementations + +struct fold_left_fn +{ + template S, class T = std::iter_value_t, + /* indirectly-binary-left-foldable */ F> + constexpr auto operator()(I first, S last, T init, F f) const + { + using U = std::decay_t>>; + if (first == last) + return U(std::move(init)); + U accum = std::invoke(f, std::move(init), *first); + for (++first; first != last; ++first) + accum = std::invoke(f, std::move(accum), *first); + return std::move(accum); + } + + template, + /* indirectly-binary-left-foldable */> F> + constexpr auto operator()(R&& r, T init, F f) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(init), std::ref(f)); + } +}; + +inline constexpr fold_left_fn fold_left; + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the function object f. + +.SH Notes + + The following table compares all constrained folding algorithms: + + Fold function template Starts Initial Return type + from value + ranges::fold_left left init U + ranges::fold_left_first left first std::optional + element + ranges::fold_right right init U + ranges::fold_right_last right last std::optional + element + \fB(1)\fP ranges::in_value_result + + ranges::fold_left_with_iter left init \fB(2)\fP ranges::in_value_result, + + where BR is + ranges::borrowed_iterator_t + \fB(1)\fP ranges::in_value_result> + + ranges::fold_left_first_with_iter left first \fB(2)\fP ranges::in_value_result> + + where BR is + ranges::borrowed_iterator_t + + Feature-test macro Value Std Feature + __cpp_lib_ranges_fold 202207L (C++23) std::ranges fold algorithms + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + std::vector v{1, 2, 3, 4, 5, 6, 7, 8}; + + int sum = ranges::fold_left(v.begin(), v.end(), 0, std::plus()); // (1) + std::cout << "sum: " << sum << '\\n'; + + int mul = ranges::fold_left(v, 1, std::multiplies()); // (2) + std::cout << "mul: " << mul << '\\n'; + + // get the product of the std::pair::second of all pairs in the vector: + std::vector> data {{'A', 2.f}, {'B', 3.f}, {'C', 3.5f}}; + float sec = ranges::fold_left + ( + data | ranges::views::values, 2.0f, std::multiplies<>() + ); + std::cout << "sec: " << sec << '\\n'; + + // use a program defined function object (lambda-expression): + std::string str = ranges::fold_left + ( + v, "A", [](std::string s, int x) { return s + ':' + std::to_string(x); } + ); + std::cout << "str: " << str << '\\n'; + + using CD = std::complex; + std::vector nums{{1, 1}, {2, 0}, {3, 0}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto res = ranges::fold_left(nums, {7, 0}, std::multiplies{}); // (2) + #else + auto res = ranges::fold_left(nums, CD{7, 0}, std::multiplies{}); // (2) + #endif + std::cout << "res: " << res << '\\n'; + } + +.SH Output: + + sum: 36 + mul: 40320 + sec: 42 + str: A:1:2:3:4:5:6:7:8 + res: (42,42) + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.6.18 Fold [alg.fold] + +.SH See also + + ranges::fold_left_first left-folds a range of elements using the first + (C++23) element as an initial value + (niebloid) + ranges::fold_right right-folds a range of elements + (C++23) (niebloid) + ranges::fold_right_last right-folds a range of elements using the last + (C++23) element as an initial value + (niebloid) + ranges::fold_left_with_iter left-folds a range of elements, and returns a pair + (C++23) (iterator, value) + (niebloid) + left-folds a range of elements using the first + ranges::fold_left_first_with_iter element as an initial value, and returns a pair + (C++23) (iterator, optional) + (niebloid) + accumulate sums up or folds a range of elements + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::fold_left_first.3 b/man/std::ranges::fold_left_first.3 new file mode 100644 index 000000000..d4142fcba --- /dev/null +++ b/man/std::ranges::fold_left_first.3 @@ -0,0 +1,238 @@ +.TH std::ranges::fold_left_first 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fold_left_first \- std::ranges::fold_left_first + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + + /*indirectly-binary-left-foldable*/, I> F > + requires std::constructible_from, \fB(1)\fP (since C++23) + std::iter_reference_t> + constexpr auto + + fold_left_first( I first, S last, F f ); + template< ranges::input_range R, + + /*indirectly-binary-left-foldable*/< + ranges::range_value_t, ranges::iterator_t> + F > + requires std::constructible_from< \fB(2)\fP (since C++23) + ranges::range_value_t, + ranges::range_reference_t> + constexpr auto + + fold_left_first( R&& r, F f ); + Helper concepts + template< class F, class T, class I > (exposition + concept /*indirectly-binary-left-foldable*/ = /* see description \fB(3)\fP only*) + */; + + Left-folds the elements of given range, that is, returns the result of evaluation of + the chain expression: + f(f(f(f(x[1], x[2]), x[3]), ...), x[n]), where x[1], x[2], ..., x[n] are elements of + the range. + + Informally, ranges::fold_left_first behaves like std::accumulate's overload that + accepts a binary predicate, except that the *first is used internally as an initial + element. + + The behavior is undefined if [first, last) is not a valid range. + + 1) The range is [first, last). Equivalent to return + ranges::fold_left_first_with_iter(std::move(first), last, f).value. + 2) Same as \fB(1)\fP, except that uses r as the range, as if by using ranges::begin(r) as + first and ranges::end(r) as last. + 3) Equivalent to: + + Helper concepts + template< class F, class T, class I, class U > + + concept /*indirectly-binary-left-foldable-impl*/ = + std::movable && + std::movable && + std::convertible_to && (3A) (exposition only*) + std::invocable> && + std::assignable_from>>; + template< class F, class T, class I > + + concept /*indirectly-binary-left-foldable*/ = + std::copy_constructible && + std::indirectly_readable && + std::invocable> && + std::convertible_to>, + std::decay_t>>> && + /*indirectly-binary-left-foldable-impl*/>>>; + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to fold + r - the range of elements to fold + f - the binary function object + +.SH Return value + + An object of type std::optional that contains the result of left-fold of the + given range over f, where U is equivalent to + decltype(ranges::fold_left(std::move(first), last, std::iter_value_t(*first), + f)). + + If the range is empty, std::optional() is returned. + +.SH Possible implementations + + struct fold_left_first_fn + { + template S, + /*indirectly-binary-left-foldable*/, I> F> + requires + std::constructible_from, std::iter_reference_t> + constexpr auto operator()(I first, S last, F f) const + { + using U = decltype( + ranges::fold_left(std::move(first), last, std::iter_value_t(*first), f) + ); + if (first == last) + return std::optional(); + std::optional init(std::in_place, *first); + for (++first; first != last; ++first) + *init = std::invoke(f, std::move(*init), *first); + return std::move(init); + } + + template, ranges::iterator_t> F> + requires + std::constructible_from, ranges::range_reference_t> + constexpr auto operator()(R&& r, F f) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(f)); + } + }; + + inline constexpr fold_left_first_fn fold_left_first; + +.SH Complexity + + Exactly ranges::distance(first, last) - 1 (assuming the range is not empty) + applications of the function object f. + +.SH Notes + + The following table compares all constrained folding algorithms: + + Fold function template Starts Initial Return type + from value + ranges::fold_left left init U + ranges::fold_left_first left first std::optional + element + ranges::fold_right right init U + ranges::fold_right_last right last std::optional + element + \fB(1)\fP ranges::in_value_result + + ranges::fold_left_with_iter left init \fB(2)\fP ranges::in_value_result, + + where BR is + ranges::borrowed_iterator_t + \fB(1)\fP ranges::in_value_result> + + ranges::fold_left_first_with_iter left first \fB(2)\fP ranges::in_value_result> + + where BR is + ranges::borrowed_iterator_t + + Feature-test macro Value Std Feature + __cpp_lib_ranges_fold 202207L (C++23) std::ranges fold algorithms + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::vector v{1, 2, 3, 4, 5, 6, 7, 8}; + + auto sum = std::ranges::fold_left_first(v.begin(), v.end(), std::plus()); // (1) + std::cout << "*sum: " << sum.value() << '\\n'; + + auto mul = std::ranges::fold_left_first(v, std::multiplies()); // (2) + std::cout << "*mul: " << mul.value() << '\\n'; + + // get the product of the std::pair::second of all pairs in the vector: + std::vector> data {{'A', 3.f}, {'B', 3.5f}, {'C', 4.f}}; + auto sec = std::ranges::fold_left_first + ( + data | std::ranges::views::values, std::multiplies<>() + ); + std::cout << "*sec: " << *sec << '\\n'; + + // use a program defined function object (lambda-expression): + auto val = std::ranges::fold_left_first(v, [](int x, int y) { return x + y + 13; }); + std::cout << "*val: " << *val << '\\n'; + } + +.SH Output: + + *sum: 36 + *mul: 40320 + *sec: 42 + *val: 127 + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.6.18 Fold [alg.fold] + +.SH See also + + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) + ranges::fold_right right-folds a range of elements + (C++23) (niebloid) + ranges::fold_right_last right-folds a range of elements using the last + (C++23) element as an initial value + (niebloid) + ranges::fold_left_with_iter left-folds a range of elements, and returns a pair + (C++23) (iterator, value) + (niebloid) + left-folds a range of elements using the first + ranges::fold_left_first_with_iter element as an initial value, and returns a pair + (C++23) (iterator, optional) + (niebloid) + accumulate sums up or folds a range of elements + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::fold_left_first_with_iter,std::ranges::fold_left_first_with_iter_result.3 b/man/std::ranges::fold_left_first_with_iter,std::ranges::fold_left_first_with_iter_result.3 new file mode 100644 index 000000000..b66596c2b --- /dev/null +++ b/man/std::ranges::fold_left_first_with_iter,std::ranges::fold_left_first_with_iter_result.3 @@ -0,0 +1,264 @@ +.TH std::ranges::fold_left_first_with_iter,std::ranges::fold_left_first_with_iter_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fold_left_first_with_iter,std::ranges::fold_left_first_with_iter_result \- std::ranges::fold_left_first_with_iter,std::ranges::fold_left_first_with_iter_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + + /*indirectly-binary-left-foldable*/, I> F > + requires std::constructible_from< \fB(1)\fP (since C++23) + std::iter_value_t, std::iter_reference_t> + constexpr /* see description */ + + fold_left_first_with_iter( I first, S last, F f ); + template< ranges::input_range R, + + /*indirectly-binary-left-foldable*/< + ranges::range_value_t, ranges::iterator_t> F + > + requires std::constructible_from< \fB(2)\fP (since C++23) + ranges::range_value_t, + ranges::range_reference_t> + constexpr /* see description */ + + fold_left_first_with_iter( R&& r, F f ); + Helper concepts + template< class F, class T, class I > (exposition + concept /*indirectly-binary-left-foldable*/ = /* see description \fB(3)\fP only*) + */; + Helper class template + template< class I, class T > + using fold_left_first_with_iter_result = \fB(4)\fP (since C++23) + ranges::in_value_result; + + Left-folds the elements of given range, that is, returns the result of evaluation of + the chain expression: + f(f(f(f(x[1], x[2]), x[3]), ...), x[n]), where x[1], x[2], ..., x[n] are elements of + the range. + + Informally, ranges::fold_left_first_with_iter behaves like std::accumulate's + overload that accepts a binary predicate, except that the *first is used internally + as an initial element. + + The behavior is undefined if [first, last) is not a valid range. + + 1) The range is [first, last). + 2) Same as \fB(1)\fP, except that uses r as the range, as if by using ranges::begin(r) as + first and ranges::end(r) as last. + 3) Equivalent to: + + Helper concepts + template< class F, class T, class I, class U > + + concept /*indirectly-binary-left-foldable-impl*/ = + std::movable && + std::movable && + std::convertible_to && (3A) (exposition only*) + std::invocable> && + std::assignable_from>>; + template< class F, class T, class I > + + concept /*indirectly-binary-left-foldable*/ = + std::copy_constructible && + std::indirectly_readable && + std::invocable> && + std::convertible_to>, + std::decay_t>>> && + /*indirectly-binary-left-foldable-impl*/>>>; + + 4) The return type alias. See "Return value" section for details. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to fold + r - the range of elements to fold + f - the binary function object + +.SH Return value + + Let U be decltype(ranges::fold_left(std::move(first), last, + std::iter_value_t(*first), f)). + + 1) An object of type ranges::fold_left_first_with_iter_result>. + * The member ranges::in_value_result::in holds an iterator to the end of the + range. + * The member ranges::in_value_result::value holds the result of the left-fold of + given range over f. + If the range is empty, the return value is {std::move(first), std::optional()}. + 2) Same as \fB(1)\fP except that the return type is + ranges::fold_left_first_with_iter_result, + std::optional>. + +.SH Possible implementations + + class fold_left_first_with_iter_fn + { + template + constexpr auto impl(I&& first, S&& last, F f) const + { + using U = decltype( + ranges::fold_left(std::move(first), last, std::iter_value_t(*first), f) + ); + using Ret = ranges::fold_left_first_with_iter_result>; + if (first == last) + return Ret{std::move(first), std::optional()}; + std::optional init(std::in_place, *first); + for (++first; first != last; ++first) + *init = std::invoke(f, std::move(*init), *first); + return Ret{std::move(first), std::move(init)}; + } + + public: + template S, + /*indirectly-binary-left-foldable*/, I> F> + requires std::constructible_from, std::iter_reference_t> + constexpr auto operator()(I first, S last, F f) const + { + return impl(std::move(first), std::move(last), std::ref(f)); + } + + template, ranges::iterator_t> F> + requires + std::constructible_from, ranges::range_reference_t> + constexpr auto operator()(R&& r, F f) const + { + return impl>( + ranges::begin(r), ranges::end(r), std::ref(f) + ); + } + }; + + inline constexpr fold_left_first_with_iter_fn fold_left_first_with_iter; + +.SH Complexity + + Exactly ranges::distance(first, last) - 1 (assuming the range is not empty) + applications of the function object f. + +.SH Notes + + The following table compares all constrained folding algorithms: + + Fold function template Starts Initial Return type + from value + ranges::fold_left left init U + ranges::fold_left_first left first std::optional + element + ranges::fold_right right init U + ranges::fold_right_last right last std::optional + element + \fB(1)\fP ranges::in_value_result + + ranges::fold_left_with_iter left init \fB(2)\fP ranges::in_value_result, + + where BR is + ranges::borrowed_iterator_t + \fB(1)\fP ranges::in_value_result> + + ranges::fold_left_first_with_iter left first \fB(2)\fP ranges::in_value_result> + + where BR is + ranges::borrowed_iterator_t + + Feature-test macro Value Std Feature + __cpp_lib_ranges_fold 202207L (C++23) std::ranges fold algorithms + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + std::vector v{1, 2, 3, 4, 5, 6, 7, 8}; + + auto sum = std::ranges::fold_left_first_with_iter + ( + v.begin(), v.end(), std::plus() + ); + std::cout << "sum: " << sum.value.value() << '\\n'; + assert(sum.in == v.end()); + + auto mul = std::ranges::fold_left_first_with_iter(v, std::multiplies()); + std::cout << "mul: " << mul.value.value() << '\\n'; + assert(mul.in == v.end()); + + // get the product of the std::pair::second of all pairs in the vector: + std::vector> data {{'A', 2.f}, {'B', 3.f}, {'C', 7.f}}; + auto sec = std::ranges::fold_left_first_with_iter + ( + data | std::ranges::views::values, std::multiplies<>() + ); + std::cout << "sec: " << sec.value.value() << '\\n'; + + // use a program defined function object (lambda-expression): + auto lambda = [](int x, int y) { return x + y + 2; }; + auto val = std::ranges::fold_left_first_with_iter(v, lambda); + std::cout << "val: " << val.value.value() << '\\n'; + assert(val.in == v.end()); + } + +.SH Output: + + sum: 36 + mul: 40320 + sec: 42 + val: 50 + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.6.18 Fold [alg.fold] + +.SH See also + + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) + ranges::fold_left_first left-folds a range of elements using the first element + (C++23) as an initial value + (niebloid) + ranges::fold_right right-folds a range of elements + (C++23) (niebloid) + ranges::fold_right_last right-folds a range of elements using the last element + (C++23) as an initial value + (niebloid) + ranges::fold_left_with_iter left-folds a range of elements, and returns a pair + (C++23) (iterator, value) + (niebloid) + accumulate sums up or folds a range of elements + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::fold_left_with_iter,std::ranges::fold_left_with_iter_result.3 b/man/std::ranges::fold_left_with_iter,std::ranges::fold_left_with_iter_result.3 new file mode 100644 index 000000000..d9d4df68f --- /dev/null +++ b/man/std::ranges::fold_left_with_iter,std::ranges::fold_left_with_iter_result.3 @@ -0,0 +1,275 @@ +.TH std::ranges::fold_left_with_iter,std::ranges::fold_left_with_iter_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fold_left_with_iter,std::ranges::fold_left_with_iter_result \- std::ranges::fold_left_with_iter,std::ranges::fold_left_with_iter_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for + S, class T, + (since + /* indirectly-binary-left-foldable */ C++23) + F > (until + constexpr /* see description */ C++26) + + fold_left_with_iter( I first, S last, T init, F f + ); + template< std::input_iterator I, std::sentinel_for + S, + + class T = std::iter_value_t, + /* indirectly-binary-left-foldable */ (since + F > C++26) + constexpr /* see description */ + + fold_left_with_iter( I first, S last, T init, F f + ); + template< ranges::input_range R, class T, + \fB(1)\fP + /* indirectly-binary-left-foldable */ (since C++23) + > F > (until C++26) + constexpr /* see description */ + + fold_left_with_iter( R&& r, T init, F f ); + template< ranges::input_range R, class T = + ranges::range_value_t, + + /* indirectly-binary-left-foldable */ (since C++26) + > F > \fB(2)\fP + constexpr /* see description */ + + fold_left_with_iter( R&& r, T init, F f ); + Helper concepts + template< class F, class T, class I > (exposition + concept /* indirectly-binary-left-foldable */ = /* \fB(3)\fP only*) + see description */; + Helper class template + template< class I, class T > + using fold_left_with_iter_result = \fB(4)\fP (since C++23) + ranges::in_value_result; + + Left-folds the elements of given range, that is, returns the result of evaluation of + the chain expression: + f(f(f(f(init, x[1]), x[2]), ...), x[n]), where x[1], x[2], ..., x[n] are elements of + the range. + + Informally, ranges::fold_left_with_iter behaves like std::accumulate's overload that + accepts a binary predicate. + + The behavior is undefined if [first, last) is not a valid range. + + 1) The range is [first, last). + 2) Same as \fB(1)\fP, except that uses r as the range, as if by using ranges::begin(r) as + first and ranges::end(r) as last. + 3) Equivalent to: + + Helper concepts + template< class F, class T, class I, class U > + + concept /*indirectly-binary-left-foldable-impl*/ = + std::movable && + std::movable && + std::convertible_to && (3A) (exposition only*) + std::invocable> && + std::assignable_from>>; + template< class F, class T, class I > + + concept /*indirectly-binary-left-foldable*/ = + std::copy_constructible && + std::indirectly_readable && + std::invocable> && + std::convertible_to>, + std::decay_t>>> && + /*indirectly-binary-left-foldable-impl*/>>>; + + 4) The return type alias. See "Return value" section for details. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to fold + r - the range of elements to fold + init - the initial value of the fold + f - the binary function object + +.SH Return value + + Let U be std::decay_t>>. + + 1) An object of type ranges::fold_left_with_iter_result. + * The member ranges::in_value_result::in holds an iterator to the end of the + range. + * The member ranges::in_value_result::value holds the result of the left-fold of + given range over f. + If the range is empty, the return value is obtained via the expression equivalent to + return {std::move(first), U(std::move(init))};. + 2) Same as \fB(1)\fP except that the return type is + ranges::fold_left_with_iter_result, U>. + +.SH Possible implementations + +class fold_left_with_iter_fn +{ + template + constexpr auto impl(I&& first, S&& last, T&& init, F f) const + { + using U = std::decay_t>>; + using Ret = ranges::fold_left_with_iter_result; + if (first == last) + return Ret{std::move(first), U(std::move(init))}; + U accum = std::invoke(f, std::move(init), *first); + for (++first; first != last; ++first) + accum = std::invoke(f, std::move(accum), *first); + return Ret{std::move(first), std::move(accum)}; + } +public: + template S, class T = std::iter_value_t, + /* indirectly-binary-left-foldable */ F> + constexpr auto operator()(I first, S last, T init, F f) const + { + return impl(std::move(first), std::move(last), std::move(init), std::ref(f)); + } + + template, + /* indirectly-binary-left-foldable */> F> + constexpr auto operator()(R&& r, T init, F f) const + { + return impl> + ( + ranges::begin(r), ranges::end(r), std::move(init), std::ref(f) + ); + } +}; + +inline constexpr fold_left_with_iter_fn fold_left_with_iter; + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the function object f. + +.SH Notes + + The following table compares all constrained folding algorithms: + + Fold function template Starts Initial Return type + from value + ranges::fold_left left init U + ranges::fold_left_first left first std::optional + element + ranges::fold_right right init U + ranges::fold_right_last right last std::optional + element + \fB(1)\fP ranges::in_value_result + + ranges::fold_left_with_iter left init \fB(2)\fP ranges::in_value_result, + + where BR is + ranges::borrowed_iterator_t + \fB(1)\fP ranges::in_value_result> + + ranges::fold_left_first_with_iter left first \fB(2)\fP ranges::in_value_result> + + where BR is + ranges::borrowed_iterator_t + + Feature-test macro Value Std Feature + __cpp_lib_ranges_fold 202207L (C++23) std::ranges fold algorithms + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + std::vector v{1, 2, 3, 4, 5, 6, 7, 8}; + + auto sum = ranges::fold_left_with_iter(v.begin(), v.end(), 6, std::plus()); + assert(sum.value == 42); + assert(sum.in == v.end()); + + auto mul = ranges::fold_left_with_iter(v, 0X69, std::multiplies()); + assert(mul.value == 4233600); + assert(mul.in == v.end()); + + // Get the product of the std::pair::second of all pairs in the vector: + std::vector> data {{'A', 2.f}, {'B', 3.f}, {'C', 3.5f}}; + auto sec = ranges::fold_left_with_iter + ( + data | ranges::views::values, 2.0f, std::multiplies<>() + ); + assert(sec.value == 42); + + // Use a program defined function object (lambda-expression): + auto lambda = [](int x, int y){ return x + 0B110 + y; }; + auto val = ranges::fold_left_with_iter(v, -42, lambda); + assert(val.value == 42); + assert(val.in == v.end()); + + using CD = std::complex; + std::vector nums{{1, 1}, {2, 0}, {3, 0}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto res = ranges::fold_left_with_iter(nums, {7, 0}, std::multiplies{}); + #else + auto res = ranges::fold_left_with_iter(nums, CD{7, 0}, std::multiplies{}); + #endif + assert((res.value == CD{42, 42})); + } + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.6.18 Fold [alg.fold] + +.SH See also + + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) + ranges::fold_left_first left-folds a range of elements using the first + (C++23) element as an initial value + (niebloid) + ranges::fold_right right-folds a range of elements + (C++23) (niebloid) + ranges::fold_right_last right-folds a range of elements using the last + (C++23) element as an initial value + (niebloid) + left-folds a range of elements using the first + ranges::fold_left_first_with_iter element as an initial value, and returns a pair + (C++23) (iterator, optional) + (niebloid) + accumulate sums up or folds a range of elements + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::fold_right.3 b/man/std::ranges::fold_right.3 new file mode 100644 index 000000000..ded6f1bed --- /dev/null +++ b/man/std::ranges::fold_right.3 @@ -0,0 +1,286 @@ +.TH std::ranges::fold_right 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fold_right \- std::ranges::fold_right + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, + std::sentinel_for S, class T, + (since + /* indirectly-binary-right-foldable */ F > (until + C++26) + constexpr auto fold_right( I first, S last, T init, F + f ); + template< std::bidirectional_iterator I, + std::sentinel_for S, + + class T = std::iter_value_t, (since + /* indirectly-binary-right-foldable */ F > + + constexpr auto fold_right( I first, S last, T init, F + f ); + template< ranges::bidirectional_range R, class T, + \fB(1)\fP + /* indirectly-binary-right-foldable */ (since C++23) + > F > (until C++26) + + constexpr auto fold_right( R&& r, T init, F f ); + template< ranges::bidirectional_range R, class T = + ranges::range_value_t, + + /* indirectly-binary-right-foldable */ \fB(2)\fP (since C++26) + > F > + + constexpr auto fold_right( R&& r, T init, F f ); + Helper concepts + template< class F, class T, class I > (exposition + concept /* indirectly-binary-left-foldable */ = /* \fB(3)\fP only*) + see description */; + template< class F, class T, class I > (exposition + concept /* indirectly-binary-right-foldable */ = /* \fB(4)\fP only*) + see description */; + + Right-folds the elements of given range, that is, returns the result of evaluation + of the chain expression: + f(x[1], f(x[2], ...f(x[n], init))), where x[1], x[2], ..., x[n] are elements of the + range. + + Informally, ranges::fold_right behaves like std::fold_left(ranges::reverse(r), init, + /* flipped */(f)). + + The behavior is undefined if [first, last) is not a valid range. + + 1) The range is [first, last). + 2) Same as \fB(1)\fP, except that uses r as the range, as if by using ranges::begin(r) as + first and ranges::end(r) as last. + 3) Equivalent to: + + Helper concepts + template< class F, class T, class I, class U > + + concept /*indirectly-binary-left-foldable-impl*/ = + std::movable && + std::movable && + std::convertible_to && (3A) (exposition only*) + std::invocable> && + std::assignable_from>>; + template< class F, class T, class I > + + concept /*indirectly-binary-left-foldable*/ = + std::copy_constructible && + std::indirectly_readable && + std::invocable> && + std::convertible_to>, + std::decay_t>>> && + /*indirectly-binary-left-foldable-impl*/>>>; + + 4) Equivalent to: + + Helper concepts + template< class F, class T, class I > + (exposition + concept /*indirectly-binary-right-foldable*/ = (4A) only*) + + /*indirectly-binary-left-foldable*/, T, I>; + Helper class templates + template< class F > + + class /*flipped*/ + { + F f; // exposition only (exposition + public: (4B) only*) + template< class T, class U > + requires std::invocable + std::invoke_result_t operator()( T&&, U&& ); + + }; + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to fold + r - the range of elements to fold + init - the initial value of the fold + f - the binary function object + +.SH Return value + + An object of type U that contains the result of right-fold of the given range over + f, where U is equivalent to std::decay_t, T>>;. + + If the range is empty, U(std::move(init)) is returned. + +.SH Possible implementations + + struct fold_right_fn + { + template S, + class T = std::iter_value_t, + /* indirectly-binary-right-foldable */ F> + constexpr auto operator()(I first, S last, T init, F f) const + { + using U = std::decay_t, T>>; + if (first == last) + return U(std::move(init)); + I tail = ranges::next(first, last); + U accum = std::invoke(f, *--tail, std::move(init)); + while (first != tail) + accum = invoke(f, *--tail, std::move(accum)); + return accum; + } + + template, + /* indirectly-binary-right-foldable */> F> + constexpr auto operator()(R&& r, T init, F f) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(init), std::ref(f)); + } + }; + + inline constexpr fold_right_fn fold_right; + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the function object f. + +.SH Notes + + The following table compares all constrained folding algorithms: + + Fold function template Starts Initial Return type + from value + ranges::fold_left left init U + ranges::fold_left_first left first std::optional + element + ranges::fold_right right init U + ranges::fold_right_last right last std::optional + element + \fB(1)\fP ranges::in_value_result + + ranges::fold_left_with_iter left init \fB(2)\fP ranges::in_value_result, + + where BR is + ranges::borrowed_iterator_t + \fB(1)\fP ranges::in_value_result> + + ranges::fold_left_first_with_iter left first \fB(2)\fP ranges::in_value_result> + + where BR is + ranges::borrowed_iterator_t + + Feature-test macro Value Std Feature + __cpp_lib_ranges_fold 202207L (C++23) std::ranges fold algorithms + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + using namespace std::literals; + namespace ranges = std::ranges; + + int main() + { + auto v = {1, 2, 3, 4, 5, 6, 7, 8}; + std::vector vs{"A", "B", "C", "D"}; + + auto r1 = ranges::fold_right(v.begin(), v.end(), 6, std::plus<>()); // (1) + std::cout << "r1: " << r1 << '\\n'; + + auto r2 = ranges::fold_right(vs, "!"s, std::plus<>()); // (2) + std::cout << "r2: " << r2 << '\\n'; + + // Use a program defined function object (lambda-expression): + std::string r3 = ranges::fold_right + ( + v, "A", [](int x, std::string s) { return s + ':' + std::to_string(x); } + ); + std::cout << "r3: " << r3 << '\\n'; + + // Get the product of the std::pair::second of all pairs in the vector: + std::vector> data{{'A', 2.f}, {'B', 3.f}, {'C', 3.5f}}; + float r4 = ranges::fold_right + ( + data | ranges::views::values, 2.0f, std::multiplies<>() + ); + std::cout << "r4: " << r4 << '\\n'; + + using CD = std::complex; + std::vector nums{{1, 1}, {2, 0}, {3, 0}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto r5 = ranges::fold_right(nums, {7, 0}, std::multiplies{}); + #else + auto r5 = ranges::fold_right(nums, CD{7, 0}, std::multiplies{}); + #endif + std::cout << "r5: " << r5 << '\\n'; + } + +.SH Output: + + r1: 42 + r2: ABCD! + r3: A:8:7:6:5:4:3:2:1 + r4: 42 + r5: (42,42) + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.6.18 Fold [alg.fold] + +.SH See also + + ranges::fold_right_last right-folds a range of elements using the last + (C++23) element as an initial value + (niebloid) + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) + ranges::fold_left_first left-folds a range of elements using the first + (C++23) element as an initial value + (niebloid) + ranges::fold_left_with_iter left-folds a range of elements, and returns a pair + (C++23) (iterator, value) + (niebloid) + left-folds a range of elements using the first + ranges::fold_left_first_with_iter element as an initial value, and returns a pair + (C++23) (iterator, optional) + (niebloid) + accumulate sums up or folds a range of elements + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::fold_right_last.3 b/man/std::ranges::fold_right_last.3 new file mode 100644 index 000000000..312c69aa0 --- /dev/null +++ b/man/std::ranges::fold_right_last.3 @@ -0,0 +1,266 @@ +.TH std::ranges::fold_right_last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::fold_right_last \- std::ranges::fold_right_last + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for S, + + + /*indirectly-binary-right-foldable*/, I> F > + requires std::constructible_from< \fB(1)\fP (since C++23) + std::iter_value_t, std::iter_reference_t> + constexpr auto + + fold_right_last( I first, S last, F f ); + template< ranges::bidirectional_range R, + + /*indirectly-binary-right-foldable*/< + ranges::range_value_t, ranges::iterator_t> F + > + requires std::constructible_from< \fB(2)\fP (since C++23) + ranges::range_value_t, + ranges::range_reference_t> + constexpr auto + + fold_right_last( R&& r, F f ); + Helper concepts + template< class F, class T, class I > (exposition + concept /*indirectly-binary-left-foldable*/ = /* see description \fB(3)\fP only*) + */; + template< class F, class T, class I > (exposition + concept /*indirectly-binary-right-foldable*/ = /* see description \fB(4)\fP only*) + */; + + Right-folds the elements of given range, that is, returns the result of evaluation + of the chain expression: + f(x[1], f(x[2], ...f(x[n-1], x[n]))), where x[1], x[2], ..., x[n] are elements of + the range. + + Informally, ranges::fold_right_last behaves like std::fold_left(ranges::reverse(r), + *--last, /*flipped*/(f)) (assuming the range is not empty). + + The behavior is undefined if [first, last) is not a valid range. + + 1) The range is [first, last). Given U as decltype(ranges::fold_right(first, last, + std::iter_value_t(*first), f)), equivalent to: + + if (first == last) + return std::optional(); + I tail = ranges::prev(ranges::next(first, std::move(last))); + return std::optional(std::in_place, ranges::fold_right(std::move(first), tail, + std::iter_value_t(*tail), std::move(f))); + + 2) Same as \fB(1)\fP, except that uses r as the range, as if by using ranges::begin(r) as + first and ranges::end(r) as last. + 3) Equivalent to: + + Helper concepts + template< class F, class T, class I, class U > + + concept /*indirectly-binary-left-foldable-impl*/ = + std::movable && + std::movable && + std::convertible_to && (3A) (exposition only*) + std::invocable> && + std::assignable_from>>; + template< class F, class T, class I > + + concept /*indirectly-binary-left-foldable*/ = + std::copy_constructible && + std::indirectly_readable && + std::invocable> && + std::convertible_to>, + std::decay_t>>> && + /*indirectly-binary-left-foldable-impl*/>>>; + + 4) Equivalent to: + + Helper concepts + template< class F, class T, class I > + (exposition + concept /*indirectly-binary-right-foldable*/ = (4A) only*) + + /*indirectly-binary-left-foldable*/, T, I>; + Helper class templates + template< class F > + + class /*flipped*/ + { + F f; // exposition only (exposition + public: (4B) only*) + template< class T, class U > + requires std::invocable + std::invoke_result_t operator()( T&&, U&& ); + + }; + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to fold + r - the range of elements to fold + f - the binary function object + +.SH Return value + + An object of type std::optional that contains the result of right-fold of the + given range over f. + + If the range is empty, std::optional() is returned. + +.SH Possible implementations + + struct fold_right_last_fn + { + template S, + /*indirectly-binary-right-foldable*/, I> F> + requires + std::constructible_from, std::iter_reference_t> + constexpr auto operator()(I first, S last, F f) const + { + using U = decltype( + ranges::fold_right(first, last, std::iter_value_t(*first), f)); + + if (first == last) + return std::optional(); + I tail = ranges::prev(ranges::next(first, std::move(last))); + return std::optional(std::in_place, + ranges::fold_right(std::move(first), tail, std::iter_value_t(*tail), + std::move(f))); + } + + template, ranges::iterator_t> F> + requires + std::constructible_from, ranges::range_reference_t> + constexpr auto operator()(R&& r, F f) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(f)); + } + }; + + inline constexpr fold_right_last_fn fold_right_last; + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the function object f. + +.SH Notes + + The following table compares all constrained folding algorithms: + + Fold function template Starts Initial Return type + from value + ranges::fold_left left init U + ranges::fold_left_first left first std::optional + element + ranges::fold_right right init U + ranges::fold_right_last right last std::optional + element + \fB(1)\fP ranges::in_value_result + + ranges::fold_left_with_iter left init \fB(2)\fP ranges::in_value_result, + + where BR is + ranges::borrowed_iterator_t + \fB(1)\fP ranges::in_value_result> + + ranges::fold_left_first_with_iter left first \fB(2)\fP ranges::in_value_result> + + where BR is + ranges::borrowed_iterator_t + + Feature-test macro Value Std Feature + __cpp_lib_ranges_fold 202207L (C++23) std::ranges fold algorithms + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto v = {1, 2, 3, 4, 5, 6, 7, 8}; + std::vector vs {"A", "B", "C", "D"}; + + auto r1 = std::ranges::fold_right_last(v.begin(), v.end(), std::plus<>()); // (1) + std::cout << "*r1: " << *r1 << '\\n'; + + auto r2 = std::ranges::fold_right_last(vs, std::plus<>()); // (2) + std::cout << "*r2: " << *r2 << '\\n'; + + // Use a program defined function object (lambda-expression): + auto r3 = std::ranges::fold_right_last(v, [](int x, int y) { return x + y + 99; }); + std::cout << "*r3: " << *r3 << '\\n'; + + // Get the product of the std::pair::second of all pairs in the vector: + std::vector> data {{'A', 3.f}, {'B', 3.5f}, {'C', 4.f}}; + auto r4 = std::ranges::fold_right_last + ( + data | std::ranges::views::values, std::multiplies<>() + ); + std::cout << "*r4: " << *r4 << '\\n'; + } + +.SH Output: + + *r1: 36 + *r2: ABCD + *r3: 729 + *r4: 42 + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 27.6.18 Fold [alg.fold] + +.SH See also + + ranges::fold_right right-folds a range of elements + (C++23) (niebloid) + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) + ranges::fold_left_first left-folds a range of elements using the first + (C++23) element as an initial value + (niebloid) + ranges::fold_left_with_iter left-folds a range of elements, and returns a pair + (C++23) (iterator, value) + (niebloid) + left-folds a range of elements using the first + ranges::fold_left_first_with_iter element as an initial value, and returns a pair + (C++23) (iterator, optional) + (niebloid) + accumulate sums up or folds a range of elements + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::for_each,std::ranges::for_each_result.3 b/man/std::ranges::for_each,std::ranges::for_each_result.3 new file mode 100644 index 000000000..731c9daa1 --- /dev/null +++ b/man/std::ranges::for_each,std::ranges::for_each_result.3 @@ -0,0 +1,159 @@ +.TH std::ranges::for_each,std::ranges::for_each_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::for_each,std::ranges::for_each_result \- std::ranges::for_each,std::ranges::for_each_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, class Proj = + std::identity, + (since + std::indirectly_unary_invocable> Fun > \fB(1)\fP C++20) + constexpr for_each_result + + for_each( I first, S last, Fun f, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirectly_unary_invocable< (since + std::projected, Proj>> Fun > \fB(2)\fP C++20) + constexpr for_each_result, Fun> + + for_each( R&& r, Fun f, Proj proj = {} ); +.SH Helper types + template< class I, class F > \fB(3)\fP (since + using for_each_result = ranges::in_fun_result; C++20) + + 1) Applies the given function object f to the result of the value projected by each + iterator in the range [first, last), in order. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + For both overloads, if the iterator type is mutable, f may modify the elements of + the range through the dereferenced iterator. If f returns a result, the result is + ignored. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range to apply the function to + r - the range of elements to apply the function to + f - the function to apply to the projected range + proj - projection to apply to the elements + +.SH Return value + + {std::ranges::next(std::move(first), last), std::move(f)} + +.SH Complexity + + Exactly last - first applications of f and proj. + +.SH Possible implementation + + struct for_each_fn + { + template S, class Proj = std::identity, + std::indirectly_unary_invocable> Fun> + constexpr ranges::for_each_result + operator()(I first, S last, Fun f, Proj proj = {}) const + { + for (; first != last; ++first) + std::invoke(f, std::invoke(proj, *first)); + return {std::move(first), std::move(f)}; + } + + template, + Proj>> Fun> + constexpr ranges::for_each_result, Fun> + operator()(R&& r, Fun f, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(f), std::ref(proj)); + } + }; + + inline constexpr for_each_fn for_each; + +.SH Example + + The following example uses a lambda expression to increment all of the elements of a + vector and then uses an overloaded operator() in a functor to compute their sum. + Note that to compute the sum, it is recommended to use the dedicated algorithm + std::accumulate. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + struct Sum + { + void operator()(int n) { sum += n; } + int sum {0}; + }; + + int main() + { + std::vector nums {3, 4, 2, 8, 15, 267}; + + auto print = [](const auto& n) { std::cout << ' ' << n; }; + + namespace ranges = std::ranges; + std::cout << "before:"; + ranges::for_each(std::as_const(nums), print); + print('\\n'); + + ranges::for_each(nums, [](int& n) { ++n; }); + + // calls Sum::operator() for each number + auto [i, s] = ranges::for_each(nums.begin(), nums.end(), Sum()); + assert(i == nums.end()); + + std::cout << "after: "; + ranges::for_each(nums.cbegin(), nums.cend(), print); + + std::cout << "\\n" "sum: " << s.sum << '\\n'; + + using pair = std::pair; + std::vector pairs {{1,"one"}, {2,"two"}, {3,"tree"}}; + + std::cout << "project the pair::first: "; + ranges::for_each(pairs, print, [](const pair& p) { return p.first; }); + + std::cout << "\\n" "project the pair::second:"; + ranges::for_each(pairs, print, &pair::second); + print('\\n'); + } + +.SH Output: + + before: 3 4 2 8 15 267 + after: 4 5 3 9 16 268 + sum: 305 + project the pair::first: 1 2 3 + project the pair::second: one two tree + +.SH See also + + range-for loop\fI(C++11)\fP executes loop over range + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + ranges::for_each_n applies a function object to the first N elements of a + (C++20) sequence + (niebloid) + for_each applies a function to a range of elements + \fI(function template)\fP diff --git a/man/std::ranges::for_each_n,std::ranges::for_each_n_result.3 b/man/std::ranges::for_each_n,std::ranges::for_each_n_result.3 new file mode 100644 index 000000000..b6107824d --- /dev/null +++ b/man/std::ranges::for_each_n,std::ranges::for_each_n_result.3 @@ -0,0 +1,132 @@ +.TH std::ranges::for_each_n,std::ranges::for_each_n_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::for_each_n,std::ranges::for_each_n_result \- std::ranges::for_each_n,std::ranges::for_each_n_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, class Proj = std::identity, + + std::indirectly_unary_invocable> Fun > (since + constexpr for_each_n_result \fB(1)\fP C++20) + + for_each_n( I first, std::iter_difference_t n, Fun f, Proj proj = + {}); +.SH Helper types + template< class I, class F > \fB(2)\fP (since + using for_each_n_result = ranges::in_fun_result; C++20) + + 1) Applies the given function object f to the projected result by proj of + dereferencing each iterator in the range [first, first + n), in order. + + If the iterator type is mutable, f may modify the elements of the range through the + dereferenced iterator. If f returns a result, the result is ignored. If n is less + than zero, the behavior is undefined. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - iterator denoting the begin of the range to apply the function to + n - the number of elements to apply the function to + f - the function to apply to the projected range [first, first + n) + proj - projection to apply to the elements + +.SH Return value + + An object {first + n, std::move(f)}, where first + n may be evaluated as + std::ranges::next(std::move(first), n) depending on iterator category. + +.SH Complexity + + Exactly n applications of f and proj. + +.SH Possible implementation + + struct for_each_n_fn + { + template> Fun> + constexpr for_each_n_result + operator()(I first, std::iter_difference_t n, Fun fun, Proj proj = Proj{}) const + { + for (; n-- > 0; ++first) + std::invoke(fun, std::invoke(proj, *first)); + return {std::move(first), std::move(fun)}; + } + }; + + inline constexpr for_each_n_fn for_each_n {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct P + { + int first; + char second; + friend std::ostream& operator<<(std::ostream& os, const P& p) + { + return os << '{' << p.first << ",'" << p.second << "'}"; + } + }; + + auto print = [](std::string_view name, auto const& v) + { + std::cout << name << ": "; + for (auto n = v.size(); const auto& e : v) + std::cout << e << (--n ? ", " : "\\n"); + }; + + int main() + { + std::array a {1, 2, 3, 4, 5}; + print("a", a); + // Negate first three numbers: + std::ranges::for_each_n(a.begin(), 3, [](auto& n) { n *= -1; }); + print("a", a); + + std::array s { P{1,'a'}, P{2, 'b'}, P{3, 'c'}, P{4, 'd'} }; + print("s", s); + // Negate data members 'P::first' using projection: + std::ranges::for_each_n(s.begin(), 2, [](auto& x) { x *= -1; }, &P::first); + print("s", s); + // Capitalize data members 'P::second' using projection: + std::ranges::for_each_n(s.begin(), 3, [](auto& c) { c -= 'a'-'A'; }, &P::second); + print("s", s); + } + +.SH Output: + + a: 1, 2, 3, 4, 5 + a: -1, -2, -3, 4, 5 + s: {1,'a'}, {2,'b'}, {3,'c'}, {4,'d'} + s: {-1,'a'}, {-2,'b'}, {3,'c'}, {4,'d'} + s: {-1,'A'}, {-2,'B'}, {3,'C'}, {4,'d'} + +.SH See also + + range-for loop\fI(C++11)\fP executes loop over range + ranges::for_each applies a function to a range of elements + (C++20) (niebloid) + for_each_n applies a function object to the first N elements of a + \fI(C++17)\fP sequence + \fI(function template)\fP + for_each applies a function to a range of elements + \fI(function template)\fP diff --git a/man/std::ranges::forward_range.3 b/man/std::ranges::forward_range.3 new file mode 100644 index 000000000..c4516d938 --- /dev/null +++ b/man/std::ranges::forward_range.3 @@ -0,0 +1,42 @@ +.TH std::ranges::forward_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::forward_range \- std::ranges::forward_range + +.SH Synopsis + Defined in header + template< class T > + + concept forward_range = \fI(since C++20)\fP + + ranges::input_range && + std::forward_iterator>; + + The forward_range concept is a refinement of range for which ranges::begin returns a + model of forward_iterator. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const char* str{"not a forward range"}; + const char str2[] = "a forward range"; + static_assert( + std::ranges::forward_range && + !std::ranges::forward_range && + std::ranges::forward_range && + !std::ranges::forward_range> && + std::ranges::forward_range> && + !std::ranges::forward_range>> && + std::ranges::forward_range> && + !std::ranges::forward_range> && + ""); + + int main() {} diff --git a/man/std::ranges::generate.3 b/man/std::ranges::generate.3 new file mode 100644 index 000000000..12dc7f29d --- /dev/null +++ b/man/std::ranges::generate.3 @@ -0,0 +1,142 @@ +.TH std::ranges::generate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::generate \- std::ranges::generate + +.SH Synopsis + Defined in header + Call signature + template< std::input_or_output_iterator O, std::sentinel_for S, + + std::copy_constructible F > + requires std::invocable && std::indirectly_writable> + constexpr O + + generate( O first, S last, F gen ); + template< class R, std::copy_constructible F > + + requires std::invocable && ranges::output_range> \fB(2)\fP \fI(since C++20)\fP + constexpr ranges::borrowed_iterator_t + + generate( R&& r, F gen ); + + 1) Assigns the result of successive invocations of the function object gen to each + element in the range [first, last). + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to modify + r - the range of elements to modify + gen - the generator function object + +.SH Return value + + An output iterator that compares equal to last. + +.SH Complexity + + Exactly ranges::distance(first, last) invocations of gen() and assignments. + +.SH Possible implementation + + struct generate_fn + { + template S, + std::copy_constructible F> + requires std::invocable && std::indirectly_writable> + constexpr O operator()(O first, S last, F gen) const + { + for (; first != last; *first = std::invoke(gen), ++first) + {} + return first; + } + + template + requires std::invocable && ranges::output_range> + constexpr ranges::borrowed_iterator_t operator()(R&& r, F gen) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(gen)); + } + }; + + inline constexpr generate_fn generate {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + auto dice() + { + static std::uniform_int_distribution distr {1, 6}; + static std::random_device device; + static std::mt19937 engine {device()}; + return distr(engine); + } + + void iota(auto& v, int n) + { + std::ranges::generate(v, [&n]() mutable { return n++; }); + } + + void print(std::string_view comment, const auto& v) + { + for (std::cout << comment; int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::array v; + + std::ranges::generate(v.begin(), v.end(), dice); + print("dice: ", v); + std::ranges::generate(v, dice); + print("dice: ", v); + + iota(v, 1); + print("iota: ", v); + } + +.SH Possible output: + + dice: 4 3 1 6 6 4 5 5 + dice: 4 2 5 3 6 2 6 2 + iota: 1 2 3 4 5 6 7 8 + +.SH See also + + ranges::generate_n saves the result of N applications of a function + (C++20) (niebloid) + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) + ranges::fill_n assigns a value to a number of elements + (C++20) (niebloid) + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + ranges::generate_random fills a range with random numbers from a uniform random bit + (C++26) generator + (niebloid) + assigns the results of successive function calls to every + generate element in a range + \fI(function template)\fP diff --git a/man/std::ranges::generate_n.3 b/man/std::ranges::generate_n.3 new file mode 100644 index 000000000..684da74c6 --- /dev/null +++ b/man/std::ranges::generate_n.3 @@ -0,0 +1,118 @@ +.TH std::ranges::generate_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::generate_n \- std::ranges::generate_n + +.SH Synopsis + Defined in header + Call signature + template< std::input_or_output_iterator O, std::copy_constructible F + > + + requires std::invocable && std::indirectly_writable> + constexpr O + + generate_n( O first, std::iter_difference_t n, F gen ); + + Assigns the result of successive invocations of the function object gen to each + element in the range [first, first + n), if 0 < n. Does nothing otherwise. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to modify + n - number of elements to modify + gen - the generator function object. + +.SH Return value + + Iterator one past the last element assigned if 0 < count, first otherwise. + +.SH Complexity + + Exactly n invocations of gen() and assignments. + +.SH Possible implementation + + struct generate_n_fn + { + template + requires std::invocable && std::indirectly_writable> + constexpr O operator()(O first, std::iter_difference_t n, F gen) const + { + for (; n-- > 0; *first = std::invoke(gen), ++first) + {} + return first; + } + }; + + inline constexpr generate_n_fn generate_n {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + auto dice() + { + static std::uniform_int_distribution distr {1, 6}; + static std::random_device engine; + static std::mt19937 noise {engine()}; + return distr(noise); + } + + void print(const auto& v, std::string_view comment) + { + for (int i : v) + std::cout << i << ' '; + std::cout << '(' << comment << ")\\n"; + } + + int main() + { + std::array v; + + std::ranges::generate_n(v.begin(), v.size(), dice); + print(v, "dice"); + + std::ranges::generate_n(v.begin(), v.size(), [n {0}] mutable { return n++; }); + // same effect as std::iota(v.begin(), v.end(), 0); + print(v, "iota"); + } + +.SH Possible output: + + 5 5 2 2 6 6 3 5 (dice) + 0 1 2 3 4 5 6 7 (iota) + +.SH See also + + ranges::generate saves the result of a function in a range + (C++20) (niebloid) + ranges::generate_random fills a range with random numbers from a uniform random bit + (C++26) generator + (niebloid) + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) + ranges::fill_n assigns a value to a number of elements + (C++20) (niebloid) + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + assigns the results of successive function calls to N + generate_n elements in a range + \fI(function template)\fP diff --git a/man/std::ranges::generate_random.3 b/man/std::ranges::generate_random.3 new file mode 100644 index 000000000..9c7dc5292 --- /dev/null +++ b/man/std::ranges::generate_random.3 @@ -0,0 +1,134 @@ +.TH std::ranges::generate_random 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::generate_random \- std::ranges::generate_random + +.SH Synopsis + Defined in header + Call signature + template< class R, class G > + + requires ranges::output_range> && (since + std::uniform_random_bit_generator> \fB(1)\fP C++26) + constexpr ranges::borrowed_iterator_t + + generate_random( R&& r, G&& g ); + template< class G, std::output_iterator> O, + + std::sentinel_for S > (since + requires std::uniform_random_bit_generator> \fB(2)\fP C++26) + constexpr O + + generate_random( O first, S last, G&& g ); + template< class R, class G, class D > + + requires ranges::output_range> && + std::invocable && \fB(3)\fP (since + std::uniform_random_bit_generator> C++26) + constexpr ranges::borrowed_iterator_t + + generate_random( R&& r, G&& g, D&& d ); + template< class G, class D, + std::output_iterator> O, + + std::sentinel_for S > (since + requires std::invocable && \fB(4)\fP C++26) + std::uniform_random_bit_generator> + constexpr O + + generate_random( O first, S last, G&& g, D&& d ); + + Attempts to generate random numbers with the generate_random member function of the + random number generator or the distribution, which is expected to be more efficient. + Falls back to element-wise generation if no generate_random member function is + available. + + Let fallback operation be calling ranges::generate(std::forward(r), std::ref(g)) + or ranges::generate(std::forward(r), [&d, &g] { return std::invoke(d, g); }) for + \fB(1)\fP or \fB(3)\fP respectively. + + 1) Calls g.generate_random(std::forward(r)) if this expression is well-formed. + Otherwise, let I be std::invoke_result_t. If R models sized_range, fills r with + ranges::size(r) values of I by performing an unspecified number of invocations of + the form g() or g.generate_random(s), if such an expression is well-formed for a + value N and an object s of type std::span. + Otherwise, performs the fallback operation. + 3) Calls d.generate_random(std::forward(r), g) if this expression is well-formed. + Otherwise, let I be std::invoke_result_t. If R models sized_range, fills r + with ranges::size(r) values of type I by performing an unspecified number of + invocations of the form std::invoke(d, g) or d.generate_random(s, g), if such an + expression is well-formed for a value N and an object s of type std::span. + Otherwise, performs the fallback operation. + 2,4) Equivalent to (1,3) respectively, where r is obtained from ranges::subrange(std::move(first), last). + + If the effects of \fB(1)\fP or \fB(3)\fP are not equivalent to those of the corresponding + fallback operation, the behavior is undefined. + + The value of N can differ between invocations. Implementations may select smaller + values for shorter ranges. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair that denotes the range to which random numbers + are written + r - range to which random numbers are written + g - uniform random bit generator + d - random number distribution object + +.SH Notes + + At the time of the standardization of std::ranges::generate_random, there is no + random number generator or distribution in the standard library that provides a + generate_random member function. + + std::ranges::generate_random can be more efficient when used with a user-defined + random number generator that wraps an underlying vectorized API. + + Feature-test macro Value Std Feature + __cpp_lib_ranges_generate_random 202403L (C++26) std::ranges::generate_random + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::default_random_engine eng; + std::default_random_engine::result_type rs[16]{}; + std::ranges::generate_random(rs, eng); + + std::cout << std::left; + for (int i{}; auto n : rs) + std::cout << std::setw(11) << n << (++i % 4 ? ' ' : '\\n'); + } + +.SH Possible output: + + 16807 282475249 1622650073 984943658 + 1144108930 470211272 101027544 1457850878 + 1458777923 2007237709 823564440 1115438165 + 1784484492 74243042 114807987 1137522503 + +.SH See also + + ranges::generate saves the result of a function in a range + (C++20) (niebloid) + uniform_random_bit_generator specifies that a type qualifies as a uniform random bit + (C++20) generator + (concept) diff --git a/man/std::ranges::get(std::ranges::subrange).3 b/man/std::ranges::get(std::ranges::subrange).3 new file mode 100644 index 000000000..4bd23ef65 --- /dev/null +++ b/man/std::ranges::get(std::ranges::subrange).3 @@ -0,0 +1,106 @@ +.TH std::ranges::get(std::ranges::subrange) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::get(std::ranges::subrange) \- std::ranges::get(std::ranges::subrange) + +.SH Synopsis + Defined in header + template< std::size_t N, class I, class S, ranges::subrange_kind K + > + \fB(1)\fP \fI(since C++20)\fP + requires ((N == 0 && std::copyable) || N == 1) + + constexpr auto get( const ranges::subrange& r ); + template< std::size_t N, class I, class S, ranges::subrange_kind K + > + \fB(2)\fP \fI(since C++20)\fP + requires (N < 2) + + constexpr auto get( ranges::subrange&& r ); + namespace std { using ranges::get; } \fB(3)\fP \fI(since C++20)\fP + + 1) Obtains the iterator or sentinel from a subrange lvalue (or a const rvalue) when + N == 0 or N == 1, respectively. It is mainly provided for structured binding + support. + 2) Same as \fB(1)\fP, except that it takes a non-const subrange rvalue. + 3) (1,2) are imported into namespace std, which simplifies their usage and makes + every subrange with a copyable iterator a pair-like type. + +.SH Parameters + + r - a subrange + +.SH Return value + + 1) An iterator or sentinel copy constructed from the stored one when N == 0 or N == + 1, respectively. + 2) Same as \fB(1)\fP, except that the iterator is move constructed if N == 0 and I does + not satisfy copyable. + +.SH Possible implementation + + template + requires ((N == 0 && std::copyable) || N == 1) + constexpr auto get(const std::ranges::subrange& r) + { + if constexpr (N == 0) + return r.begin(); + else + return r.end(); + } + + template + requires (N < 2) + constexpr auto get(std::ranges::subrange&& r) + { + if constexpr (N == 0) + return r.begin(); // may perform move construction + else + return r.end(); + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::array a{1, -2, 3, -4}; + + std::ranges::subrange sub_a{std::next(a.begin()), std::prev(a.end())}; + std::cout << *std::ranges::get<0>(sub_a) << ' ' // == *(begin(a) + 1) + << *get<1>(sub_a) << '\\n'; // == *(end(a) - 1) + + *get<0>(sub_a) = 42; // OK + // *get<2>(sub_a) = 13; // hard error: index can only be 0 or 1 + } + +.SH Output: + + -2 -4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the overload for const lvalue was it is removed from the + LWG 3589 C++20 ill-formed if N == 0 overload set + and I does not model copyable + +.SH See also + + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple + elements of the initializer + get(std::tuple) tuple accesses specified element + \fI(C++11)\fP \fI(function template)\fP + get(std::pair) accesses an element of a pair + \fI(C++11)\fP \fI(function template)\fP + get(std::array) accesses an element of an array + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::greater.3 b/man/std::ranges::greater.3 new file mode 100644 index 000000000..970c16866 --- /dev/null +++ b/man/std::ranges::greater.3 @@ -0,0 +1,53 @@ +.TH std::ranges::greater 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::greater \- std::ranges::greater + +.SH Synopsis + Defined in header + struct greater; \fI(since C++20)\fP + + Function object for performing comparisons. Deduces the parameter types of the + function call operator from the arguments (but not the return type). + +.SH Member functions + + operator() checks if the first argument is greater than the second + \fI(public member function)\fP + +std::ranges::greater::operator() + + template< class T, class U > + constexpr bool operator()( T&& t, U&& u ) const; + + Equivalent to return ranges::less{}(std::forward(u), std::forward(t));. + + This overload participates in overload resolution only if + std::totally_ordered_with is satisfied. + +.SH Notes + + Unlike std::greater, std::ranges::greater requires all six comparison operators <, + <=, >, >=, == and != to be valid (via the totally_ordered_with constraint) and is + entirely defined in terms of std::ranges::less. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + greater function object implementing x > y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::greater_equal.3 b/man/std::ranges::greater_equal.3 new file mode 100644 index 000000000..8a933e0ec --- /dev/null +++ b/man/std::ranges::greater_equal.3 @@ -0,0 +1,53 @@ +.TH std::ranges::greater_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::greater_equal \- std::ranges::greater_equal + +.SH Synopsis + Defined in header + struct greater_equal; \fI(since C++20)\fP + + Function object for performing comparisons. Deduces the parameter types of the + function call operator from the arguments (but not the return type). + +.SH Member functions + + operator() checks if the first argument is greater than or equal to the second + \fI(public member function)\fP + +std::ranges::greater_equal::operator() + + template< class T, class U > + constexpr bool operator()( T&& t, U&& u ) const; + + Equivalent to return !ranges::less{}(std::forward(t), std::forward(u));. + + This overload participates in overload resolution only if + std::totally_ordered_with is satisfied. + +.SH Notes + + Unlike std::greater_equal, std::ranges::greater_equal requires all six comparison + operators <, <=, >, >=, == and != to be valid (via the totally_ordered_with + constraint) and is entirely defined in terms of std::ranges::less. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + greater_equal function object implementing x >= y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::in_found_result.3 b/man/std::ranges::in_found_result.3 new file mode 100644 index 000000000..b2046e256 --- /dev/null +++ b/man/std::ranges::in_found_result.3 @@ -0,0 +1,139 @@ +.TH std::ranges::in_found_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_found_result \- std::ranges::in_found_result + +.SH Synopsis + Defined in header + template< class I > \fI(since C++20)\fP + struct in_found_result; + + ranges::in_found_result is a class template that provides a way to store an iterator + and a boolean flag as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I - the type of the iterator that the ranges::in_found_result stores. + + Data members + + Member name Definition + a value (that is supposed to be an iterator) of type I. It is declared + in with [[no_unique_address]] attribute. + \fI(public member object)\fP + a boolean flag (that may show whether an appropriate range can be found) + found of type bool. + \fI(public member object)\fP + +.SH Member functions + +std::ranges::in_found_result::operator in_found_result + + template + + requires std::convertible_to \fB(1)\fP + + constexpr operator in_found_result() const &; + template + + requires std::convertible_to \fB(2)\fP + + constexpr operator in_found_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in, found};. + 2) Equivalent to return {std::move(in), found};. + +.SH Standard library + + The following standard library functions use ranges::in_found_result as the return + type: + + Algorithm functions + ranges::next_permutation generates the next greater lexicographic permutation of a + (C++20) range of elements + (niebloid) + ranges::prev_permutation generates the next smaller lexicographic permutation of a + (C++20) range of elements + (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_found_result + { + [[no_unique_address]] I in; + bool found; + + template + requires std::convertible_to + constexpr operator in_found_result() const & + { + return {in, found}; + } + + template + requires std::convertible_to + constexpr operator in_found_result() && + { + return {std::move(in), found}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + int v[] {1, 2, 3}; + + const auto result = std::ranges::next_permutation(v); + + std::ranges::for_each(std::cbegin(v), result.in, [](int e) {std::cout << e << ' ';}); + + std::cout << std::boolalpha << "\\n" "result.found: " << result.found << '\\n'; + } + +.SH Output: + + 1 3 2 + result.found = true + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::in_fun_result.3 b/man/std::ranges::in_fun_result.3 new file mode 100644 index 000000000..a9877b024 --- /dev/null +++ b/man/std::ranges::in_fun_result.3 @@ -0,0 +1,150 @@ +.TH std::ranges::in_fun_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_fun_result \- std::ranges::in_fun_result + +.SH Synopsis + Defined in header + template< class I, class F > \fI(since C++20)\fP + struct in_fun_result; + + ranges::in_fun_result is a class template that provides a way to store an iterator + and a function object as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I - the type of the iterator that the ranges::in_fun_result stores. + F - the type of the function object that the ranges::in_fun_result stores. + + Data members + + Member name Definition + in a value (that is supposed to be an iterator) of type I. + \fI(public member object)\fP + fun a value (that is supposed to be a function object) of type F. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::in_fun_result::operator in_fun_result + + template + + requires std::convertible_to && std::convertible_to \fB(1)\fP + + constexpr operator in_fun_result() const &; + template + + requires std::convertible_to && std::convertible_to \fB(2)\fP + + constexpr operator in_fun_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in, fun};. + 2) Equivalent to return {std::move(in), std::move(fun)};. + +.SH Standard library + + The following standard library functions use ranges::in_fun_result as the return + type: + + Algorithm functions + ranges::for_each applies a function to a range of elements + (C++20) (niebloid) + ranges::for_each_n applies a function object to the first N elements of a sequence + (C++20) (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_fun_result + { + [[no_unique_address]] I in; + [[no_unique_address]] F fun; + + template + requires std::convertible_to && std::convertible_to + constexpr operator in_fun_result() const & + { + return {in, fun}; + } + + template + requires std::convertible_to && std::convertible_to + constexpr operator in_fun_result() && + { + return {std::move(in), std::move(fun)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + int v[]{1, 2, 3}; + + const std::ranges::in_fun_result res1 = std::ranges::for_each_n( + v, std::size(v), + [](int& x) { return x = -x; } // negating lambda + ); + assert(res1.in == std::end(v)); + + const std::ranges::in_fun_result res2 = std::ranges::for_each( + std::begin(v), + res1.in, + [](int x) { std::cout << x << ' '; } // printing lambda + ); + + std::cout << "│ "; + + std::ranges::for_each(v, res1.fun); // uses negating lambda + std::ranges::for_each(v, res2.fun); // uses printing lambda + std::cout << '\\n'; + } + +.SH Output: + + -1 -2 -3 │ 1 2 3 + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::in_in_out_result.3 b/man/std::ranges::in_in_out_result.3 new file mode 100644 index 000000000..8e6e771d7 --- /dev/null +++ b/man/std::ranges::in_in_out_result.3 @@ -0,0 +1,164 @@ +.TH std::ranges::in_in_out_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_in_out_result \- std::ranges::in_in_out_result + +.SH Synopsis + Defined in header + template< class I1, class I2, class O > \fI(since C++20)\fP + struct in_in_out_result; + + ranges::in_in_out_result is a class template that provides a way to store three + iterators as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I1, I2, O - the types of the iterators that the ranges::in_in_out_result stores. + + Data members + + Member name Definition + in1 a value (that is supposed to be an iterator) of type I1. + \fI(public member object)\fP + in2 a value (that is supposed to be an iterator) of type I2. + \fI(public member object)\fP + out a value (that is supposed to be an iterator) of type O. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::in_in_out_result::operator in_in_out_result + + template + + requires std::convertible_to && + std::convertible_to && \fB(1)\fP + std::convertible_to + + constexpr operator in_in_out_result() const &; + template + + requires std::convertible_to && + std::convertible_to && \fB(2)\fP + std::convertible_to + + constexpr operator in_in_out_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in1, in2, out};. + 2) Equivalent to return {std::move(in1), std::move(in2), std::move(out)};. + +.SH Standard library + + The following standard library functions use ranges::in_in_out_result as the return + type: + + Algorithm functions + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + ranges::merge merges two sorted ranges + (C++20) (niebloid) + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::set_intersection computes the intersection of two sets + (C++20) (niebloid) + ranges::set_symmetric_difference computes the symmetric difference between two sets + (C++20) (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_in_out_result + { + [[no_unique_address]] I1 in1; + [[no_unique_address]] I2 in2; + [[no_unique_address]] O out; + + template + requires std::convertible_to && + std::convertible_to && + std::convertible_to + constexpr operator in_in_out_result() const & + { + return {in1, in2, out}; + } + + template + requires std::convertible_to && + std::convertible_to && + std::convertible_to + constexpr operator in_in_out_result() && + { + return {std::move(in1), std::move(in2), std::move(out)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto rem, auto first, auto last) + { + for (std::cout << rem << ": "; first != last; ++first) + std::cout << *first << ' '; + std::cout << '\\n'; + } + + int main() + { + constexpr static auto in1 = {1, 2, 3, 4, 5, 5}; + constexpr static auto in2 = {3, 4, 5, 6, 7}; + std::array out; + + const auto result = std::ranges::merge(in1, in2, out.begin()); + print("in1", in1.begin(), result.in1); + print("in2", in2.begin(), result.in2); + print("out", out.begin(), result.out); + } + +.SH Output: + + in1: 1 2 3 4 5 5 + in2: 3 4 5 6 7 + out: 1 2 3 3 4 4 5 5 5 6 7 + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::in_in_result.3 b/man/std::ranges::in_in_result.3 new file mode 100644 index 000000000..7c5815b29 --- /dev/null +++ b/man/std::ranges::in_in_result.3 @@ -0,0 +1,132 @@ +.TH std::ranges::in_in_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_in_result \- std::ranges::in_in_result + +.SH Synopsis + Defined in header + template< class I1, class I2 > \fI(since C++20)\fP + struct in_in_result; + + ranges::in_in_result is a class template that provides a way to store two iterators + as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I1, I2 - the types of the iterators that the ranges::in_in_result stores. + + Data members + + Member name Definition + in1 a value (that is supposed to be an iterator) of type I1. + \fI(public member object)\fP + in2 a value (that is supposed to be an iterator) of type I2. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::in_in_result::operator in_in_result + + template + + requires std::convertible_to && std::convertible_to + + constexpr operator in_in_result() const &; + template + + requires std::convertible_to && std::convertible_to \fB(2)\fP + + constexpr operator in_in_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in1, in2};. + 2) Equivalent to return {std::move(in1), std::move(in2)};. + +.SH Standard library + + The following standard library functions use ranges::in_in_result as the return + type: + + Algorithm functions + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) + ranges::swap_ranges swaps two ranges of elements + (C++20) (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_in_result + { + [[no_unique_address]] I1 in1; + [[no_unique_address]] I2 in2; + + template + requires std::convertible_to && std::convertible_to + constexpr operator in_in_result() const & + { + return {in1, in2}; + } + + template + requires std::convertible_to && std::convertible_to + constexpr operator in_in_result() && + { + return {std::move(in1), std::move(in2)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr static auto in1 = {1, 2, 3, 4}; + constexpr static auto in2 = {1, 2, 4, 5}; + + constexpr auto result {std::ranges::mismatch(in1, in2)}; + + static_assert(2 == std::ranges::distance(in1.begin(), result.in1)); + static_assert(2 == std::ranges::distance(in2.begin(), result.in2)); + } + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::in_out_out_result.3 b/man/std::ranges::in_out_out_result.3 new file mode 100644 index 000000000..d0737e969 --- /dev/null +++ b/man/std::ranges::in_out_out_result.3 @@ -0,0 +1,159 @@ +.TH std::ranges::in_out_out_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_out_out_result \- std::ranges::in_out_out_result + +.SH Synopsis + Defined in header + template< class I, class O1, class O2 > \fI(since C++20)\fP + struct in_out_out_result; + + ranges::in_out_out_result is a class template that provides a way to store three + iterators as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I, O1, O2 - the types of the objects that the ranges::in_out_out_result stores. + + Data members + + Member name Definition + in a value (that is supposed to be an iterator) of type I. + \fI(public member object)\fP + out1 a value (that is supposed to be an iterator) of type O1. + \fI(public member object)\fP + out2 a value (that is supposed to be an iterator) of type O2. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::in_out_out_result::operator in_out_out_result + + template + + requires std::convertible_to && + std::convertible_to && \fB(1)\fP + std::convertible_to + + constexpr operator in_out_out_result() const &; + template + + requires std::convertible_to && + std::convertible_to && \fB(2)\fP + std::convertible_to + + constexpr operator in_out_out_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in, out1, out2};. + 2) Equivalent to return {std::move(in), std::move(out1), std::move(out2)};. + +.SH Standard library + + The following standard library functions use ranges::in_out_out_result as the return + type: + + Algorithm functions + ranges::partition_copy copies a range dividing the elements into two groups + (C++20) (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_out_out_result + { + [[no_unique_address]] I in; + [[no_unique_address]] O1 out1; + [[no_unique_address]] O2 out2; + + template + requires std::convertible_to && + std::convertible_to && + std::convertible_to + constexpr operator in_out_out_result() const & + { + return {in, out1, out2}; + } + + template + requires std::convertible_to && + std::convertible_to && + std::convertible_to + constexpr operator in_out_out_result() && + { + return {std::move(in), std::move(out1), std::move(out2)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(std::string_view rem, auto first, auto last) + { + for (std::cout << rem << ": { "; first != last; ++first) + std::cout << *first << ' '; + std::cout << "}\\n"; + } + + int main() + { + constexpr std::string_view in {"TvEeNcStOoRr"}; + std::array o1, o2; + + const auto result = std::ranges::partition_copy(in, o1.begin(), o2.begin(), + [](char c) { return std::isupper(c); }); + + print("in", in.begin(), result.in); + print("o1", o1.begin(), result.out1); + print("o2", o2.begin(), result.out2); + } + +.SH Output: + + in: { T v E e N c S t O o R r } + o1: { T E N S O R } + o2: { v e c t o r } + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::in_out_result.3 b/man/std::ranges::in_out_result.3 new file mode 100644 index 000000000..7f05fe4a8 --- /dev/null +++ b/man/std::ranges::in_out_result.3 @@ -0,0 +1,183 @@ +.TH std::ranges::in_out_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_out_result \- std::ranges::in_out_result + +.SH Synopsis + Defined in header + template< class I, class O > \fI(since C++20)\fP + struct in_out_result; + + ranges::in_out_result is a class template that provides a way to store two iterators + as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I, O - the types of the objects that the ranges::in_out_result stores. + + Data members + + Member name Definition + in a value (that is supposed to be an iterator) of type I. + \fI(public member object)\fP + out a value (that is supposed to be an iterator) of type O. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::in_out_result::operator in_out_result + + template + + requires std::convertible_to && std::convertible_to \fB(1)\fP + + constexpr operator in_out_result() const &; + template + + requires std::convertible_to && std::convertible_to \fB(2)\fP + + constexpr operator in_out_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in, out};. + 2) Equivalent to return {std::move(in), std::move(out)};. + +.SH Standard library + + The following standard library functions use ranges::in_out_result as the return + type: + + Algorithm functions + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in + (C++20) backwards order + (niebloid) + ranges::transform applies a function to a range of elements + (C++20) (niebloid) + ranges::replace_copy copies a range, replacing elements satisfying specific + ranges::replace_copy_if criteria with another value + (C++20) (niebloid) + (C++20) + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) + ranges::unique_copy creates a copy of some range of elements that contains + (C++20) no consecutive duplicates + (niebloid) + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) + ranges::rotate_copy copies and rotate a range of elements + (C++20) (niebloid) + ranges::partial_sort_copy copies and partially sorts a range of elements + (C++20) (niebloid) + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) + Memory functions + ranges::uninitialized_copy copies a range of objects to an uninitialized area of + (C++20) memory + (niebloid) + ranges::uninitialized_copy_n copies a number of objects to an uninitialized area of + (C++20) memory + (niebloid) + ranges::uninitialized_move moves a range of objects to an uninitialized area of + (C++20) memory + (niebloid) + ranges::uninitialized_move_n moves a number of objects to an uninitialized area of + (C++20) memory + (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_out_result + { + [[no_unique_address]] I in; + [[no_unique_address]] O out; + + template + requires std::convertible_to && std::convertible_to + constexpr operator in_out_result() const & + { + return {in, out}; + } + + template + requires std::convertible_to && std::convertible_to + constexpr operator in_out_result() && + { + return {std::move(in), std::move(out)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr char in[] = "transform" "\\n"; + std::array out; + + const auto result = std::ranges::transform(in, out.begin(), + [](char c) { return std::toupper(c); }); + + auto print = [](char c) { std::cout << c; }; + std::ranges::for_each(std::cbegin(in), result.in, print); + std::ranges::for_each(out.cbegin(), result.out, print); + } + +.SH Output: + + transform + TRANSFORM + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::in_value_result.3 b/man/std::ranges::in_value_result.3 new file mode 100644 index 000000000..76094a6f8 --- /dev/null +++ b/man/std::ranges::in_value_result.3 @@ -0,0 +1,131 @@ +.TH std::ranges::in_value_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::in_value_result \- std::ranges::in_value_result + +.SH Synopsis + Defined in header + template< class I, class T > (since C++23) + struct in_value_result; + + ranges::in_value_result is a class template that provides a way to store an iterator + and a value as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + I, T - the types of the objects that the ranges::in_value_result stores. + + Data members + + Member name Definition + in a value (that is supposed to be an iterator) of type I. + \fI(public member object)\fP + value a value (that is supposed to be a stored value) of type T. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::in_value_result::operator in_value_result + + template + + requires convertible_to && convertible_to \fB(1)\fP + + constexpr operator in_value_result() const &; + template + + requires convertible_to && convertible_to \fB(2)\fP + + constexpr operator in_value_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {in, value};. + 2) Equivalent to return {std::move(in), std::move(value)};. + +.SH Standard library + + The following standard library functions use ranges::in_value_result as the return + type: + + Algorithm functions + ranges::fold_left_with_iter left-folds a range of elements, and returns a pair + (C++23) (iterator, value) + (niebloid) + left-folds a range of elements using the first + ranges::fold_left_first_with_iter element as an initial value, and returns a pair + (C++23) (iterator, optional) + (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct in_value_result + { + [[no_unique_address]] I in; + [[no_unique_address]] T value; + + template + requires convertible_to && convertible_to + constexpr operator in_value_result() const & + { + return {in, value}; + } + + template + requires convertible_to && convertible_to + constexpr operator in_value_result() && + { + return {std::move(in), std::move(value)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto v = {1, 2, 3}; + const auto ret = std::ranges::fold_left_with_iter(v, 4, std::plus<>()); + assert(ret.in == v.end()); + assert(ret.value == 1 + 2 + 3 + 4); + } + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::includes.3 b/man/std::ranges::includes.3 new file mode 100644 index 000000000..9853119df --- /dev/null +++ b/man/std::ranges::includes.3 @@ -0,0 +1,184 @@ +.TH std::ranges::includes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::includes \- std::ranges::includes + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + class Proj1 = std::identity, class Proj2 = + std::identity, + std::indirect_strict_weak_order< \fB(1)\fP \fI(since C++20)\fP + std::projected, + std::projected> Comp = ranges::less > + constexpr bool + includes( I1 first1, S1 last1, I2 first2, S2 last2, + + Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {} ) + template< ranges::input_range R1, ranges::input_range R2, + + class Proj1 = std::identity, class Proj2 = + std::identity, + std::indirect_strict_weak_order< + std::projected, Proj1>, \fB(2)\fP \fI(since C++20)\fP + std::projected, Proj2>> Comp + = ranges::less > + constexpr bool + + includes( R1&& r1, R2&& r2, Comp comp = {}, Proj1 proj1 = {}, + Proj2 proj2 = {} ) + + 1) Returns true if the projections of the sorted range [first2, last2) is a + subsequence of the projections of the sorted range [first1, last1). + 2) Same as \fB(1)\fP, but uses r1 and r2 as the source ranges, as if by using + ranges::begin(r1) and ranges::begin(r2) as first1 and first2 respectively, and + ranges::end(r1) and ranges::end(r2) as last1 and last2 respectively. + + Both ranges must be sorted with the given comparison function comp. A subsequence + need not be contiguous. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the sorted range of elements to examine + r1 - the sorted range of elements to examine + first2, last2 - the sorted range of elements to search for + r2 - the sorted range of elements to search for + comp - comparison function to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + true if [first2, last2) is a subsequence of [first1, last1); otherwise false. + +.SH Complexity + + At most \\(\\scriptsize 2 \\cdot (N_1+N_2-1)\\)2·(N[1]+N[2]-1) comparisons, where + \\(\\scriptsize N_1\\)N[1] is ranges::distance(r1) and \\(\\scriptsize N_2\\)N[2] is + ranges::distance(r2). + +.SH Possible implementation + + struct includes_fn + { + template S1, + std::input_iterator I2, std::sentinel_for S2, + class Proj1 = std::identity, class Proj2 = std::identity, + std::indirect_strict_weak_order< + std::projected, + std::projected> Comp = ranges::less> + constexpr bool operator()(I1 first1, S1 last1, I2 first2, S2 last2, + Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; first2 != last2; ++first1) + { + if (first1 == last1 || comp(*first2, *first1)) + return false; + if (!comp(*first1, *first2)) + ++first2; + } + return true; + } + + template, Proj1>, + std::projected, Proj2>> Comp = ranges::less> + constexpr bool operator()(R1&& r1, R2&& r2, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::ref(comp), std::ref(proj1), std::ref(proj2)); + } + }; + + inline constexpr auto includes = includes_fn {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + std::ostream& operator<<(std::ostream& os, std::initializer_list const& list) + { + for (os << "{ "; auto const& elem : list) + os << elem << ' '; + return os << "} "; + } + + struct true_false : std::numpunct + { + std::string do_truename() const { return "? Yes\\n"; } + std::string do_falsename() const { return "? No\\n"; } + }; + + int main() + { + std::cout.imbue(std::locale(std::cout.getloc(), new true_false)); + + auto ignore_case = [](char a, char b) { return std::tolower(a) < std::tolower(b); }; + + const auto + a = {'a', 'b', 'c'}, + b = {'a', 'c'}, + c = {'a', 'a', 'b'}, + d = {'g'}, + e = {'a', 'c', 'g'}, + f = {'A', 'B', 'C'}, + z = {'a', 'b', 'c', 'f', 'h', 'x'}; + + std::cout + << z << "includes\\n" << std::boolalpha + << a << std::ranges::includes(z.begin(), z.end(), a.begin(), a.end()) + << b << std::ranges::includes(z, b) + << c << std::ranges::includes(z, c) + << d << std::ranges::includes(z, d) + << e << std::ranges::includes(z, e) + << f << std::ranges::includes(z, f, ignore_case); + } + +.SH Output: + + { a b c f h x } includes + { a b c } ? Yes + { a c } ? Yes + { a a b } ? No + { g } ? No + { a c g } ? No + { A B C } ? Yes + +.SH See also + + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + ranges::contains + ranges::contains_subrange checks if the range contains the given element or subrange + (C++23) (niebloid) + (C++23) + includes returns true if one sequence is a subsequence of another + \fI(function template)\fP diff --git a/man/std::ranges::inplace_merge.3 b/man/std::ranges::inplace_merge.3 new file mode 100644 index 000000000..8ed297b4d --- /dev/null +++ b/man/std::ranges::inplace_merge.3 @@ -0,0 +1,230 @@ +.TH std::ranges::inplace_merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::inplace_merge \- std::ranges::inplace_merge + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for + S, + + class Comp = ranges::less, class Proj = std::identity \fI(since C++20)\fP + > \fB(1)\fP (constexpr since + requires std::sortable C++26) + I inplace_merge( I first, I middle, S last, + + Comp comp = {}, Proj proj = {} ); + template< ranges::bidirectional_range R, class Comp = + ranges::less, + + class Proj = std::identity > \fI(since C++20)\fP + requires std::sortable, Comp, Proj> \fB(2)\fP (constexpr since + ranges::borrowed_iterator_t C++26) + inplace_merge( R&& r, ranges::iterator_t middle, + + Comp comp = {}, Proj proj = {} ); + + Merges two consecutive sorted ranges [first, middle) and [middle, last) into one + sorted range [first, last). + + A sequence is said to be sorted with respect to the comparator comp and projection + proj if for any iterator it pointing to the sequence and any non-negative integer n + such that it + n is a valid iterator pointing to an element of the sequence, + std::invoke(comp, std::invoke(proj, *(it + n)), std::invoke(proj, *it))) evaluates + to false. + + This merge function is stable, which means that for equivalent elements in the + original two ranges, the elements from the first range (preserving their original + order) precede the elements from the second range (preserving their original order). + + 1) Elements are compared using the given binary comparison function comp and + projection object proj, and the ranges must be sorted with respect to the same. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first, and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the first sorted range + middle - the end of the first range and the beginning of the second range + last - the end of the second sorted range + r - the range of elements to merge inplace + comp - comparison to apply to the projected elements + proj - projection to apply to the elements in the range + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Exactly N − 1 comparisons, if additional memory buffer is available, where N = + ranges::distance(first, last). Otherwise, \\(\\scriptsize + \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N*log(N)) comparisons. Additionally, twice as many + projections as comparisons in both cases. + +.SH Notes + + This function attempts to allocate a temporary buffer. If the allocation fails, the + less efficient algorithm is chosen. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_algorithms 202306L constexpr stable sorting + +.SH Possible implementation + + This implementation only shows the slower algorithm used when no additional memory + is available. See also the implementation in MSVC STL and libstdc++. + +struct inplace_merge_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr I operator()(I first, I middle, S last, Comp comp = {}, Proj proj = {}) const + { + I last_it = ranges::next(middle, last); + inplace_merge_slow(first, middle, last_it, + ranges::distance(first, middle), + ranges::distance(middle, last_it), + std::ref(comp), std::ref(proj)); + return last_it; + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, ranges::iterator_t middle, + Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), std::move(middle), ranges::end(r), + std::move(comp), std::move(proj)); + } + +private: + template + static constexpr void inplace_merge_slow(I first, I middle, I last, + std::iter_difference_t n1, + std::iter_difference_t n2, + Comp comp, Proj proj) + { + if (n1 == 0 || n2 == 0) + return; + if (n1 + n2 == 2 && comp(proj(*middle), proj(*first))) + { + ranges::iter_swap(first, middle); + return; + } + + I cut1 = first, cut2 = middle; + std::iter_difference_t d1{}, d2{}; + + if (n1 > n2) + { + d1 = n1 / 2; + ranges::advance(cut1, d1); + cut2 = ranges::lower_bound(middle, last, *cut1, + std::ref(comp), std::ref(proj)); + d2 = ranges::distance(middle, cut2); + } + else + { + d2 = n2 / 2; + ranges::advance(cut2, d2); + cut1 = ranges::upper_bound(first, middle, *cut2, + std::ref(comp), std::ref(proj)); + d1 = ranges::distance(first, cut1); + } + + I new_middle = ranges::rotate(cut1, middle, cut2); + inplace_merge_slow(first, cut1, new_middle, d1, d2, + std::ref(comp), std::ref(proj)); + inplace_merge_slow(new_middle, cut2, last, n1 - d1, n2 - d2, + std::ref(comp), std::ref(proj)); + } +}; + +inline constexpr inplace_merge_fn inplace_merge {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(auto const& v, auto const& rem, int middle = -1) + { + for (int i{}; auto n : v) + std::cout << (i++ == middle ? "│ " : "") << n << ' '; + std::cout << rem << '\\n'; + } + + template S> + requires std::sortable + void merge_sort(I first, S last) + { + if (last - first > 1) + { + I middle{first + (last - first) / 2}; + merge_sort(first, middle); + merge_sort(middle, last); + std::ranges::inplace_merge(first, middle, last); + } + } + + int main() + { + // custom merge-sort demo + std::vector v{8, 2, 0, 4, 9, 8, 1, 7, 3}; + print(v, ": before sort"); + merge_sort(v.begin(), v.end()); + print(v, ": after sort\\n"); + + // merging with comparison function object and projection + using CI = std::complex; + std::vector r{{0,1}, {0,2}, {0,3}, {1,1}, {1,2}}; + const auto middle{std::ranges::next(r.begin(), 3)}; + auto comp{std::ranges::less{}}; + auto proj{[](CI z) { return z.imag(); }}; + + print(r, ": before merge", middle - r.begin()); + std::ranges::inplace_merge(r, middle, comp, proj); + print(r, ": after merge"); + } + +.SH Output: + + 8 2 0 4 9 8 1 7 3 : before sort + 0 1 2 3 4 7 8 8 9 : after sort + + (0,1) (0,2) (0,3) │ (1,1) (1,2) : before merge + (0,1) (1,1) (0,2) (1,2) (0,3) : after merge + +.SH See also + + ranges::merge merges two sorted ranges + (C++20) (niebloid) + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::is_sorted checks whether a range is sorted into ascending order + (C++20) (niebloid) + ranges::sort sorts a range into ascending order + (C++20) (niebloid) + inplace_merge merges two ordered ranges in-place + \fI(function template)\fP diff --git a/man/std::ranges::input_range.3 b/man/std::ranges::input_range.3 new file mode 100644 index 000000000..e60e2fa59 --- /dev/null +++ b/man/std::ranges::input_range.3 @@ -0,0 +1,14 @@ +.TH std::ranges::input_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::input_range \- std::ranges::input_range + +.SH Synopsis + Defined in header + template< class T > + + concept input_range = \fI(since C++20)\fP + + ranges::range && std::input_iterator>; + + The input_range concept is a refinement of range for which ranges::begin returns a + model of input_iterator. diff --git a/man/std::ranges::iota,std::ranges::iota_result.3 b/man/std::ranges::iota,std::ranges::iota_result.3 new file mode 100644 index 000000000..b84add150 --- /dev/null +++ b/man/std::ranges::iota,std::ranges::iota_result.3 @@ -0,0 +1,149 @@ +.TH std::ranges::iota,std::ranges::iota_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::iota,std::ranges::iota_result \- std::ranges::iota,std::ranges::iota_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_or_output_iterator O, std::sentinel_for S, + + std::weakly_incrementable T > + requires std::indirectly_writable \fB(1)\fP (since C++23) + constexpr iota_result + + iota( O first, S last, T value ); + template< std::weakly_incrementable T, ranges::output_range R > + \fB(2)\fP (since C++23) + constexpr iota_result, T> + + iota( R&& r, T value ); +.SH Helper types + template< class O, class T > \fB(3)\fP (since C++23) + using iota_result = ranges::out_value_result; + + Fills the range [first, last) with sequentially increasing values, starting with + value and repetitively evaluating ++value. + + Equivalent operation: + + *(first) = value; + *(first + 1) = ++value; + *(first + 2) = ++value; + *(first + 3) = ++value; + ... + +.SH Parameters + + first, last - the range of elements to fill with sequentially increasing values + starting with value + value - initial value to store; the expression ++value must be well-formed + +.SH Return value + + {last, value + ranges::distance(first, last)} + +.SH Complexity + + Exactly last - first increments and assignments. + +.SH Possible implementation + + struct iota_fn + { + template S, + std::weakly_incrementable T> + requires std::indirectly_writable + constexpr iota_result operator()(O first, S last, T value) const + { + while (first != last) + { + *first = as_const(value); + ++first; + ++value; + } + return {std::move(first), std::move(value)}; + } + + template R> + constexpr iota_result, T> + operator()(R&& r, T value) const + { + return (*this)(std::ranges::begin(r), std::ranges::end(r), std::move(value)); + } + }; + + inline constexpr iota_fn iota; + +.SH Notes + + The function is named after the integer function ⍳ from the programming language + APL. + + Feature-test macro Value Std Feature + __cpp_lib_ranges_iota 202202L (C++23) std::ranges::iota + +.SH Example + + Uses the vector of iterators (std::vector::iterator>) as a proxy to + shuffle the elements of the std::list, because ranges::shuffle cannot be applied to + the std::list directly. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + void println(auto comment, std::ranges::input_range auto&& range, Proj proj = {}) + { + for (std::cout << comment; auto const &element : range) + std::cout << proj(element) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::list list(8); + + // Fill the list with ascending values: 0, 1, 2, ..., 7 + std::ranges::iota(list, 0); + println("List: ", list); + + // A vector of iterators (see the comment to Example) + std::vector::iterator> vec(list.size()); + + // Fill with iterators to consecutive list's elements + std::ranges::iota(vec.begin(), vec.end(), list.begin()); + + std::ranges::shuffle(vec, std::mt19937 {std::random_device {}()}); + println("List viewed via vector: ", vec, [](auto it) { return *it; }); + } + +.SH Possible output: + + List: 0 1 2 3 4 5 6 7 + List viewed via vector: 5 7 6 0 1 3 4 2 + +.SH See also + + fill copy-assigns the given value to every element in a range + \fI(function template)\fP + ranges::fill assigns a range of elements a certain value + (C++20) (niebloid) + assigns the results of successive function calls to every element + generate in a range + \fI(function template)\fP + ranges::generate saves the result of a function in a range + (C++20) (niebloid) + ranges::iota_view a view consisting of a sequence generated by repeatedly + views::iota incrementing an initial value + (C++20) \fI(class template)\fP (customization point object) + iota fills a range with successive increments of the starting value + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::iota_view::iterator.3 b/man/std::ranges::iota_view::iterator.3 new file mode 100644 index 000000000..9f0c0d65e --- /dev/null +++ b/man/std::ranges::iota_view::iterator.3 @@ -0,0 +1,234 @@ +.TH std::ranges::iota_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::iota_view::iterator \- std::ranges::iota_view::iterator + +.SH Synopsis + struct /*iterator*/; \fB(1)\fP \fI(since C++20)\fP + (exposition only*) + Helper alias templates + template< class I > \fB(2)\fP (exposition only*) + using /*iota-diff-t*/ = /* see below */; + Helper concepts + template< class I > + + concept /*decrementable*/ = + std::incrementable && requires(I i) { \fB(3)\fP (exposition only*) + { --i } -> std::same_as; + { i-- } -> std::same_as; + + }; + template< class I > + + concept /*advanceable*/ = + /*decrementable*/ && std::totally_ordered && + requires(I i, const I j, const /*iota-diff-t*/ n) { + { i += n } -> std::same_as; + { i -= n } -> std::same_as; \fB(4)\fP (exposition only*) + I(j + n); + I(n + j); + I(j - n); + { j - j } -> std::convertible_to>; + + }; + + 1) The return type of iota_view::begin. + 2) The alias template /*iota-diff-t*/ calculates the difference type for both + iterator types and integer-like types. + * If W is not an integral type, or if it is an integral type and + sizeof(std::iter_difference_t) is greater than sizeof(I), then + /*iota-diff-t*/ is std::iter_difference_t. + * Otherwise, /*iota-diff-t*/ is a signed integer type of width greater than the + width of I if such a type exists. + * Otherwise, I is one of the widest integral types, and /*iota-diff-t*/ is an + unspecified signed-integer-like type of width not less than the width of I. It + is unspecified whether /*iota-diff-t*/ models weakly_incrementable in this + case. + 3) The concept decrementable specifies that a type is incrementable, and pre- and + post- operator-- for the type have common meaning. + 4) The concept advanceable specifies that a type is both decrementable and + totally_ordered, and operator+=, operator-=, operator+, and operator- among the type + and its different type have common meaning. + +.SH Member types + + Member type Definition + * std::random_access_iterator_tag if W models advanceable. + Otherwise, + * std::bidirectional_iterator_tag if W models decrementable. + iterator_concept Otherwise, + * std::forward_iterator_tag if W models incrementable. + Otherwise, + * std::input_iterator_tag. + iterator_category std::input_iterator_tag if W models incrementable. + Otherwise, there is no member type iterator_category. + value_type W + difference_type /*iota-diff-t*/ + + Notes: /*iterator*/ is + + * random_access_iterator if W models advanceable, + * bidirectional_iterator if W models decrementable, + * forward_iterator if W models incrementable, and + * input_iterator otherwise. + + However, it only satisfies LegacyInputIterator if W models incrementable, and does + not satisfy LegacyInputIterator otherwise. + + Data members + + Member name Definition + value_ (private) The value of type W used for dereferencing. + (exposition-only member object*) + +.SH Member functions + +std::ranges::iota_view::iterator::iterator + + /*iterator*/() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*iterator*/( W value ); \fB(2)\fP \fI(since C++20)\fP + + 1) Value initializes the data member value_ via its default member initializer (= + W()). + 2) Initializes the data member value_ with value. This value will be returned by + operator* and incremented by operator++. + +std::ranges::iota_view::iterator::operator* + + constexpr W operator*() const \fI(since C++20)\fP + noexcept(std::is_nothrow_copy_constructible_v); + + Returns the current value, by value (in other words, this is a read-only view). + +std::ranges::iota_view::iterator::operator++ + + constexpr /*iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr void operator++(int); \fB(2)\fP \fI(since C++20)\fP + constexpr /*iterator*/ operator++(int) requires \fB(3)\fP \fI(since C++20)\fP + std::incrementable; + + 1) Equivalent to ++value_; return *this;. + 2) Equivalent to ++value_;. + 3) Equivalent to auto tmp = *this; ++value_; return tmp;. + +std::ranges::iota_view::iterator::operator-- + + constexpr /*iterator*/& operator--() requires \fB(1)\fP \fI(since C++20)\fP + /*decrementable*/; + constexpr /*iterator*/operator--(int) requires \fB(2)\fP \fI(since C++20)\fP + /*decrementable*/; + + 1) Equivalent to --value_; return *this;. + 2) Equivalent to auto tmp = *this; --value_; return tmp;. + +std::ranges::iota_view::iterator::operator+= + + constexpr /*iterator*/& operator+=( difference_type n ) \fI(since C++20)\fP + requires /*advanceable*/; + + If W is unsigned-integer-like, performs value_ += static_cast(n) if n is + non-negative, value -= static_cast(-n) otherwise, and then returns *this. + + Otherwise, equivalent to value_ += n; return *this;. + +std::ranges::iota_view::iterator::operator-= + + constexpr /*iterator*/& operator-=( difference_type n ) \fI(since C++20)\fP + requires /*advanceable*/; + + If W is unsigned-integer-like, performs value_ -= static_cast(n) if n is + non-negative, or value += static_cast(-n) otherwise, and then returns *this. + + Otherwise, equivalent to value_ -= n; return *this;. + +std::ranges::iota_view::iterator::operator[] + + constexpr W operator[]( difference_type n ) const \fI(since C++20)\fP + requires /*advanceable*/; + + Equivalent to return W(value_ + n);. + +.SH Non-member functions + +operator==, <, >, <=, >=, <=>(std::ranges::iota_view::iterator) + + friend constexpr bool operator== ( const /*iterator*/& x, const + /*iterator*/& y ) \fB(1)\fP \fI(since C++20)\fP + requires std::equality_comparable; + friend constexpr bool operator< ( const /*iterator*/& x, const + /*iterator*/& y ) \fB(2)\fP \fI(since C++20)\fP + requires std::totally_ordered; + friend constexpr bool operator> ( const /*iterator*/& x, const + /*iterator*/& y ) \fB(3)\fP \fI(since C++20)\fP + requires std::totally_ordered; + friend constexpr bool operator<= ( const /*iterator*/& x, const + /*iterator*/& y ) \fB(4)\fP \fI(since C++20)\fP + requires std::totally_ordered; + friend constexpr bool operator>= ( const /*iterator*/& x, const + /*iterator*/& y ) \fB(5)\fP \fI(since C++20)\fP + requires std::totally_ordered; + friend constexpr bool operator<=>( const /*iterator*/& x, const + /*iterator*/& y ) \fB(6)\fP \fI(since C++20)\fP + requires std::totally_ordered && + std::three_way_comparable; + + 1) Equivalent to return x.value_ == y.value_;. + 2) Equivalent to return x.value_ < y.value_;. + 3) Equivalent to return y < x;. + 4) Equivalent to return !(y < x);. + 5) Equivalent to return !(x < y);. + 6) Equivalent to return x.value_ <=> y.value_;. + + The != operator is synthesized from operator==. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when iterator is an associated class of + the arguments. + +operator+(std::ranges::iota_view::iterator) + + friend constexpr /*iterator*/ operator+( /*iterator*/ i, + difference_type n ) \fB(1)\fP \fI(since C++20)\fP + requires /*advanceable*/; + friend constexpr /*iterator*/ operator+( difference_type n, + /*iterator*/ i ) \fB(2)\fP \fI(since C++20)\fP + requires /*advanceable*/; + + Equivalent to i += n; return i;. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when iterator is an associated class of + the arguments. + +operator-(std::ranges::iota_view::iterator) + + friend constexpr /*iterator*/ operator-( /*iterator*/ i, + difference_type n ) \fB(1)\fP \fI(since C++20)\fP + requires /*advanceable*/; + friend constexpr difference_type operator-( const /*iterator*/& x, + + const /*iterator*/& y \fB(2)\fP \fI(since C++20)\fP + ) + + requires /*advanceable*/; + + 1) Equivalent to i -= n; return i;. + 2) Let D be difference_type. + * If W is signed-integer-like, equivalent to return D(D(x.value_) - D(y.value_));. + * Otherwise, if W is unsigned-integer-like, equivalent to return y.value_ > + x.value_ ? D(-D(y.value_ - x.value_)) : D(x.value_ - y.value_);. + * Otherwise, equivalent to return x.value_ - y.value_;. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when iterator is an associated class of + the arguments. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2259R1 C++20 member iterator_category is always defined only if W satisfies + defined incrementable + LWG 3580 C++20 bodies of operator+ and operator- made suitable for implicit + rule out implicit move move diff --git a/man/std::ranges::iota_view::sentinel.3 b/man/std::ranges::iota_view::sentinel.3 new file mode 100644 index 000000000..694e08e89 --- /dev/null +++ b/man/std::ranges::iota_view::sentinel.3 @@ -0,0 +1,58 @@ +.TH std::ranges::iota_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::iota_view::sentinel \- std::ranges::iota_view::sentinel + +.SH Synopsis + struct /*sentinel*/; \fI(since C++20)\fP + (exposition only*) + + The return type of iota_view::end, used when the iota_view is bounded (i.e. Bound is + not std::unreachable_sentinel_t) and Bound and W are not the same type. + +.SH Member functions + +std::ranges::iota_view::sentinel::sentinel + + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( Bound bound ); \fB(2)\fP \fI(since C++20)\fP + + 1) Value-initializes bound_ via its default member initializer (= Bound()). + 2) Initializes bound_ with bound. + +.SH Non-member functions + + In the following descriptions, value_ is an underlying data member of iterator from + which its operator* copies. + +operator==(std::ranges::iota_view::iterator, std::ranges::iota_view::sentinel) + + friend constexpr bool operator==( const /*iterator*/& x, \fI(since C++20)\fP + const /*sentinel*/& y ); + + Equivalent to: return x.value_ == y.bound_;. + + The != operator is synthesized from operator==. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when sentinel is an associated class of + the arguments. + +operator-(std::ranges::iota_view::iterator, std::ranges::iota_view::sentinel) + + friend constexpr std::iter_difference_t + + operator-(const /*iterator*/& x, const /*sentinel*/& y) \fB(1)\fP \fI(since C++20)\fP + + requires std::sized_sentinel_for; + friend constexpr std::iter_difference_t + + operator-(const /*sentinel*/& x, const /*iterator*/& y) \fB(2)\fP \fI(since C++20)\fP + + requires std::sized_sentinel_for; + + 1) Equivalent to return x.value_ - y.bound_;. + 2) Equivalent to return -(y.value_ - x.bound_);. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when sentinel is an associated class of + the arguments. diff --git a/man/std::ranges::is_heap.3 b/man/std::ranges::is_heap.3 new file mode 100644 index 000000000..19d11587f --- /dev/null +++ b/man/std::ranges::is_heap.3 @@ -0,0 +1,197 @@ +.TH std::ranges::is_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::is_heap \- std::ranges::is_heap + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Proj = std::identity, std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(1)\fP C++20) + constexpr bool + + is_heap( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Proj = std::identity, + + + std::indirect_strict_weak_order, (since + Proj>> \fB(2)\fP C++20) + Comp = ranges::less > + constexpr bool + + is_heap( R&& r, Comp comp = {}, Proj proj = {} ); + + Checks if the elements in range [first, last) are a max heap. + + 1) Elements are compared using the given binary comparison function comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + true if the range is max heap, false otherwise. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Notes + + A max heap is a range of elements [f, l), arranged with respect to comparator comp + and projection proj, that has the following properties: + + * With N = l - f, p = f[(i - 1) / 2], and q = f[i], for all 0 < i < N, the + expression std::invoke(comp, std::invoke(proj, p), std::invoke(proj, q)) + evaluates to false. + * A new element can be added using ranges::push_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + * The first element can be removed using ranges::pop_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + +.SH Possible implementation + + struct is_heap_fn + { + template S, + class Proj = std::identity, std::indirect_strict_weak_order< + std::projected> Comp = ranges::less> + constexpr bool operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + return (last == ranges::is_heap_until(first, last, + std::move(comp), std::move(proj))); + } + + template, Proj>> + Comp = ranges::less> + constexpr bool operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::move(comp), std::move(proj)); + } + }; + + inline constexpr is_heap_fn is_heap {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void out(const auto& what, int n = 1) + { + while (n-- > 0) + std::cout << what; + } + + void draw_heap(auto const& v) + { + auto bails = [](int n, int w) + { + auto b = [](int w) { out("┌"), out("─", w), out("┴"), out("─", w), out("┐"); }; + n /= 2; + if (!n) + return; + for (out(' ', w); n-- > 0;) + b(w), out(' ', w + w + 1); + out('\\n'); + }; + auto data = [](int n, int w, auto& first, auto last) + { + for (out(' ', w); n-- > 0 && first != last; ++first) + out(*first), out(' ', w + w + 1); + out('\\n'); + }; + auto tier = [&](int t, int m, auto& first, auto last) + { + const int n{1 << t}; + const int w{(1 << (m - t - 1)) - 1}; + bails(n, w), data(n, w, first, last); + }; + const int m{static_cast(std::ceil(std::log2(1 + v.size())))}; + auto first{v.cbegin()}; + for (int i{}; i != m; ++i) + tier(i, m, first, v.cend()); + } + + int main() + { + std::vector v{3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5, 8, 9, 7, 9, 3, 2, 3, 8}; + + out("initially, v:\\n"); + for (auto i : v) + std::cout << i << ' '; + out('\\n'); + + if (!std::ranges::is_heap(v)) + { + out("making heap...\\n"); + std::ranges::make_heap(v); + } + + out("after make_heap, v:\\n"); + for (auto t{1U}; auto i : v) + std::cout << i << (std::has_single_bit(++t) ? " │ " : " "); + + out("\\n" "corresponding binary tree is:\\n"); + draw_heap(v); + } + +.SH Output: + + initially, v: + 3 1 4 1 5 9 2 6 5 3 5 8 9 7 9 3 2 3 8 + making heap... + after make_heap, v: + 9 │ 8 9 │ 6 5 8 9 │ 3 5 3 5 3 4 7 2 │ 1 2 3 1 + corresponding binary tree is: + 9 + ┌───────┴───────┐ + 8 9 + ┌───┴───┐ ┌───┴───┐ + 6 5 8 9 + ┌─┴─┐ ┌─┴─┐ ┌─┴─┐ ┌─┴─┐ + 3 5 3 5 3 4 7 2 + ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ + 1 2 3 1 + +.SH See also + + ranges::is_heap_until finds the largest subrange that is a max heap + (C++20) (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) + is_heap checks if the given range is a max heap + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::is_heap_until.3 b/man/std::ranges::is_heap_until.3 new file mode 100644 index 000000000..d1aecfc9d --- /dev/null +++ b/man/std::ranges::is_heap_until.3 @@ -0,0 +1,204 @@ +.TH std::ranges::is_heap_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::is_heap_until \- std::ranges::is_heap_until + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Proj = std::identity, std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(1)\fP C++20) + constexpr I + + is_heap_until( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Proj = std::identity, + + + std::indirect_strict_weak_order, (since + Proj>> \fB(2)\fP C++20) + Comp = ranges::less > + constexpr ranges::borrowed_iterator_t + + is_heap_until( R&& r, Comp comp = {}, Proj proj = {} ); + + Examines the range [first, last) and finds the largest range beginning at first + which is a max heap. + + 1) Elements are compared using the given binary comparison function comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine + r - the range of elements to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + The upper bound of the largest range beginning at first which is a max heap. That + is, the last iterator it for which range [first, it) is a max heap with respect to + comp and proj. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Notes + + A max heap is a range of elements [f, l), arranged with respect to comparator comp + and projection proj, that has the following properties: + + * With N = l - f, p = f[(i - 1) / 2], and q = f[i], for all 0 < i < N, the + expression std::invoke(comp, std::invoke(proj, p), std::invoke(proj, q)) + evaluates to false. + * A new element can be added using ranges::push_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + * The first element can be removed using ranges::pop_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + +.SH Possible implementation + +struct is_heap_until_fn +{ + template S, + class Proj = std::identity, std::indirect_strict_weak_order< + std::projected> Comp = ranges::less> + constexpr I + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + std::iter_difference_t n{ranges::distance(first, last)}, dad{0}, son{1}; + for (; son != n; ++son) + { + if (std::invoke(comp, std::invoke(proj, *(first + dad)), + std::invoke(proj, *(first + son)))) + return first + son; + else if ((son % 2) == 0) + ++dad; + } + return first + n; + } + + template, Proj>> + Comp = ranges::less> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(comp), std::move(proj)); + } +}; + +inline constexpr is_heap_until_fn is_heap_until {}; + +.SH Example + + The example renders a given vector as a (balanced) Binary tree. + + +// Run this code + + #include + #include + #include + #include + #include + + void out(const auto& what, int n = 1) + { + while (n-- > 0) + std::cout << what; + } + + void draw_bin_tree(auto first, auto last) + { + auto bails = [](int n, int w) + { + auto b = [](int w) { out("┌"), out("─", w), out("┴"), out("─", w), out("┐"); }; + n /= 2; + if (!n) + return; + for (out(' ', w); n-- > 0;) + b(w), out(' ', w + w + 1); + out('\\n'); + }; + auto data = [](int n, int w, auto& first, auto last) + { + for (out(' ', w); n-- > 0 && first != last; ++first) + out(*first), out(' ', w + w + 1); + out('\\n'); + }; + auto tier = [&](int t, int m, auto& first, auto last) + { + const int n{1 << t}; + const int w{(1 << (m - t - 1)) - 1}; + bails(n, w), data(n, w, first, last); + }; + const auto size{std::ranges::distance(first, last)}; + const int m{static_cast(std::ceil(std::log2(1 + size)))}; + for (int i{}; i != m; ++i) + tier(i, m, first, last); + } + + int main() + { + std::vector v{3, 1, 4, 1, 5, 9}; + std::ranges::make_heap(v); + + // probably mess up the heap + v.push_back(2); + v.push_back(6); + + out("v after make_heap and push_back:\\n"); + draw_bin_tree(v.begin(), v.end()); + + out("the max-heap prefix of v:\\n"); + const auto heap_end = std::ranges::is_heap_until(v); + draw_bin_tree(v.begin(), heap_end); + } + +.SH Output: + + v after make_heap and push_back: + 9 + ┌───┴───┐ + 5 4 + ┌─┴─┐ ┌─┴─┐ + 1 1 3 2 + ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ + 6 + the max-heap prefix of v: + 9 + ┌─┴─┐ + 5 4 + ┌┴┐ ┌┴┐ + 1 1 3 2 + +.SH See also + + ranges::is_heap checks if the given range is a max heap + (C++20) (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) + is_heap_until finds the largest subrange that is a max heap + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::is_partitioned.3 b/man/std::ranges::is_partitioned.3 new file mode 100644 index 000000000..263376d29 --- /dev/null +++ b/man/std::ranges::is_partitioned.3 @@ -0,0 +1,134 @@ +.TH std::ranges::is_partitioned 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::is_partitioned \- std::ranges::is_partitioned + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(1)\fP \fI(since C++20)\fP + Pred > + constexpr bool + + is_partitioned( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_unary_predicate< + std::projected, Proj>> Pred > \fB(2)\fP \fI(since C++20)\fP + constexpr bool + + is_partitioned( R&& r, Pred pred, Proj proj = {} ); + + 1) Returns true if all elements in the range [first, last) that satisfy the + predicate pred after projection appear before all elements that don't. Also returns + true if [first, last) is empty. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range of elements to examine + r - the range of elements to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + true if the range [first, last) is empty or is partitioned by pred, false otherwise. + +.SH Complexity + + At most ranges::distance(first, last) applications of pred and proj. + +.SH Possible implementation + +struct is_partitioned_fn +{ + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr bool operator()(I first, S last, Pred pred, Proj proj = {}) const + { + for (; first != last; ++first) + if (!std::invoke(pred, std::invoke(proj, *first))) + break; + + for (; first != last; ++first) + if (std::invoke(pred, std::invoke(proj, *first))) + return false; + + return true; + } + + template, Proj>> Pred> + constexpr bool operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(pred), std::ref(proj)); + } +}; + +inline constexpr auto is_partitioned = is_partitioned_fn(); + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::array v; + + auto print = [&v](bool o) + { + for (int x : v) + std::cout << x << ' '; + std::cout << (o ? "=> " : "=> not ") << "partitioned\\n"; + }; + + auto is_even = [](int i) { return i % 2 == 0; }; + + std::iota(v.begin(), v.end(), 1); // or std::ranges::iota(v, 1); + print(std::ranges::is_partitioned(v, is_even)); + + std::ranges::partition(v, is_even); + print(std::ranges::is_partitioned(std::as_const(v), is_even)); + + std::ranges::reverse(v); + print(std::ranges::is_partitioned(v.cbegin(), v.cend(), is_even)); + print(std::ranges::is_partitioned(v.crbegin(), v.crend(), is_even)); + } + +.SH Output: + + 1 2 3 4 5 6 7 8 9 => not partitioned + 2 4 6 8 5 3 7 1 9 => partitioned + 9 1 7 3 5 8 6 4 2 => not partitioned + 9 1 7 3 5 8 6 4 2 => partitioned + +.SH See also + + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::partition_point locates the partition point of a partitioned range + (C++20) (niebloid) + is_partitioned determines if the range is partitioned by the given + \fI(C++11)\fP predicate + \fI(function template)\fP diff --git a/man/std::ranges::is_permutation.3 b/man/std::ranges::is_permutation.3 new file mode 100644 index 000000000..dfc0a4bb0 --- /dev/null +++ b/man/std::ranges::is_permutation.3 @@ -0,0 +1,209 @@ +.TH std::ranges::is_permutation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::is_permutation \- std::ranges::is_permutation + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I1, std::sentinel_for S1, + + std::forward_iterator I2, std::sentinel_for S2, + class Proj1 = std::identity, class Proj2 = std::identity, + std::indirect_equivalence_relation, + std::projected> (since + Pred = ranges::equal_to \fB(1)\fP C++20) + > + constexpr bool + is_permutation( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred + = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::forward_range R1, ranges::forward_range R2, + + class Proj1 = std::identity, class Proj2 = std::identity, + std::indirect_equivalence_relation< + std::projected, Proj1>, (since + std::projected, Proj2>> \fB(2)\fP C++20) + Pred = ranges::equal_to > + constexpr bool + is_permutation( R1&& r1, R2&& r2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + + 1) Returns true if there exists a permutation of the elements in range + [first1, last1) that makes the range equal to [first2, last2) (after application of + corresponding projections Proj1, Proj2, and using the binary predicate Pred as a + comparator). Otherwise returns false. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the first range of the elements + first2, last2 - the second range of the elements + r1 - the first range of the elements + r2 - the second range of the elements + pred - predicate to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + true if the range [first1, last1) is a permutation of the range [first2, last2). + +.SH Complexity + + At most \\(\\scriptsize \\mathcal{O}(N^2)\\)O(N^2) applications of the predicate and + each projection, or exactly \\(\\scriptsize N\\)N if the sequences are already equal, + where \\(\\scriptsize N\\)N is ranges::distance(first1, last1). However if + ranges::distance(first1, last1) != ranges::distance(first2, last2), no applications + of the predicate and projections are made. + +.SH Notes + + The permutation relation is an equivalence relation. + + The ranges::is_permutation can be used in testing, e.g. to check the correctness of + rearranging algorithms such as sorting, shuffling, partitioning. If p is an original + sequence and q is a "mutated" sequence, then ranges::is_permutation(p, q) == true + means that q consist of "the same" elements (maybe permuted) as p. + +.SH Possible implementation + +struct is_permutation_fn +{ + template S1, + std::forward_iterator I2, std::sentinel_for S2, + class Proj1 = std::identity, class Proj2 = std::identity, + std::indirect_equivalence_relation, + std::projected> + Pred = ranges::equal_to> + constexpr bool operator()(I1 first1, S1 last1, I2 first2, S2 last2, + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + // skip common prefix + auto ret = std::ranges::mismatch(first1, last1, first2, last2, + std::ref(pred), std::ref(proj1), std::ref(proj2)); + first1 = ret.in1, first2 = ret.in2; + + // iterate over the rest, counting how many times each element + // from [first1, last1) appears in [first2, last2) + for (auto i {first1}; i != last1; ++i) + { + const auto i_proj {std::invoke(proj1, *i)}; + auto i_cmp = [&](T&& t) + { + return std::invoke(pred, i_proj, std::forward(t)); + }; + + if (i != ranges::find_if(first1, i, i_cmp, proj1)) + continue; // this *i has been checked + + if (const auto m {ranges::count_if(first2, last2, i_cmp, proj2)}; + m == 0 or m != ranges::count_if(i, last1, i_cmp, proj1)) + return false; + } + return true; + } + + template, Proj1>, + std::projected, Proj2>> + Pred = ranges::equal_to> + constexpr bool operator()(R1&& r1, R2&& r2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(pred), std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr is_permutation_fn is_permutation {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + auto& operator<<(auto& os, std::ranges::forward_range auto const& v) + { + os << "{ "; + for (const auto& e : v) + os << e << ' '; + return os << "}"; + } + + int main() + { + static constexpr auto r1 = {1, 2, 3, 4, 5}; + static constexpr auto r2 = {3, 5, 4, 1, 2}; + static constexpr auto r3 = {3, 5, 4, 1, 1}; + + static_assert( + std::ranges::is_permutation(r1, r1) && + std::ranges::is_permutation(r1, r2) && + std::ranges::is_permutation(r2, r1) && + std::ranges::is_permutation(r1.begin(), r1.end(), r2.begin(), r2.end())); + + std::cout + << std::boolalpha + << "is_permutation(" << r1 << ", " << r2 << "): " + << std::ranges::is_permutation(r1, r2) << '\\n' + << "is_permutation(" << r1 << ", " << r3 << "): " + << std::ranges::is_permutation(r1, r3) << '\\n' + + << "is_permutation with custom predicate and projections: " + << std::ranges::is_permutation( + std::array {-14, -11, -13, -15, -12}, // 1st range + std::array {'F', 'E', 'C', 'B', 'D'}, // 2nd range + [](int x, int y) { return abs(x) == abs(y); }, // predicate + [](int x) { return x + 10; }, // projection for 1st range + [](char y) { return int(y - 'A'); }) // projection for 2nd range + << '\\n'; + } + +.SH Output: + + is_permutation({ 1 2 3 4 5 }, { 3 5 4 1 2 }): true + is_permutation({ 1 2 3 4 5 }, { 3 5 4 1 1 }): false + is_permutation with custom predicate and projections: true + +.SH See also + + ranges::next_permutation generates the next greater lexicographic permutation of a + (C++20) range of elements + (niebloid) + ranges::prev_permutation generates the next smaller lexicographic permutation of a + (C++20) range of elements + (niebloid) + is_permutation determines if a sequence is a permutation of another + \fI(C++11)\fP sequence + \fI(function template)\fP + generates the next greater lexicographic permutation of a + next_permutation range of elements + \fI(function template)\fP + generates the next smaller lexicographic permutation of a + prev_permutation range of elements + \fI(function template)\fP + equivalence_relation specifies that a relation imposes an equivalence relation + (C++20) (concept) diff --git a/man/std::ranges::is_sorted.3 b/man/std::ranges::is_sorted.3 new file mode 100644 index 000000000..d17b025fd --- /dev/null +++ b/man/std::ranges::is_sorted.3 @@ -0,0 +1,138 @@ +.TH std::ranges::is_sorted 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::is_sorted \- std::ranges::is_sorted + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_strict_weak_order> \fB(1)\fP \fI(since C++20)\fP + Comp = ranges::less > + constexpr bool + + is_sorted( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> \fB(2)\fP \fI(since C++20)\fP + Comp = ranges::less > + constexpr bool + + is_sorted( R&& r, Comp comp = {}, Proj proj = {} ); + + Checks if the elements in range [first, last) are sorted in non-descending order. + + A sequence is sorted with respect to a comparator comp if for any iterator it + pointing to the sequence and any non-negative integer n such that it + n is a valid + iterator pointing to an element of the sequence, std::invoke(comp, std::invoke(proj, + *(it + n)), std::invoke(proj, *it)) evaluates to false. + + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the range to check if it is sorted + r - the range to check if it is sorted + comp - comparison function to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + true if the elements in the range are sorted according to comp. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Possible implementation + + struct is_sorted_fn + { + template S, + class Proj = std::identity, + std::indirect_strict_weak_order> + Comp = ranges::less> + constexpr bool operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + return ranges::is_sorted_until(first, last, comp, proj) == last; + } + + template, Proj>> + Comp = ranges::less> + constexpr bool operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(comp), std::ref(proj)); + } + }; + + inline constexpr is_sorted_fn is_sorted; + +.SH Notes + + ranges::is_sorted returns true for empty ranges and ranges of length one. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + std::array digits {3, 1, 4, 1, 5}; + + ranges::copy(digits, std::ostream_iterator(std::cout, " ")); + ranges::is_sorted(digits) + ? std::cout << ": sorted\\n" + : std::cout << ": not sorted\\n"; + + ranges::sort(digits); + + ranges::copy(digits, std::ostream_iterator(std::cout, " ")); + ranges::is_sorted(ranges::begin(digits), ranges::end(digits)) + ? std::cout << ": sorted\\n" + : std::cout << ": not sorted\\n"; + + ranges::reverse(digits); + + ranges::copy(digits, std::ostream_iterator(std::cout, " ")); + ranges::is_sorted(digits, ranges::greater {}) + ? std::cout << ": sorted (with 'greater')\\n" + : std::cout << ": not sorted\\n"; + } + +.SH Output: + + 3 1 4 1 5 : not sorted + 1 1 3 4 5 : sorted + 5 4 3 1 1 : sorted (with 'greater') + +.SH See also + + ranges::is_sorted_until finds the largest sorted subrange + (C++20) (niebloid) + is_sorted checks whether a range is sorted into ascending order + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::is_sorted_until.3 b/man/std::ranges::is_sorted_until.3 new file mode 100644 index 000000000..32ddbced7 --- /dev/null +++ b/man/std::ranges::is_sorted_until.3 @@ -0,0 +1,145 @@ +.TH std::ranges::is_sorted_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::is_sorted_until \- std::ranges::is_sorted_until + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, class Proj = + std::identity, + + std::indirect_strict_weak_order> Comp \fB(1)\fP (since + = ranges::less > C++20) + constexpr I + + is_sorted_until( I first, S last, Comp comp = {}, Proj proj = {} ); + template< std::forward_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = \fB(2)\fP (since + ranges::less > C++20) + constexpr ranges::borrowed_iterator_t + + is_sorted_until( R&& r, Comp comp = {}, Proj proj = {} ); + + Examines the range [first, last) and finds the largest range beginning at first in + which the elements are sorted in non-descending order. + + A sequence is sorted with respect to a comparator comp if for any iterator it + pointing to the sequence and any non-negative integer n such that it + n is a valid + iterator pointing to an element of the sequence, std::invoke(comp, std::invoke(proj, + *(it + n)), std::invoke(proj, *it)) evaluates to false. + + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the range to find its sorted upper bound + r - the range to find its sorted upper bound + comp - comparison function to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + The upper bound of the largest range beginning at first in which the elements are + sorted in non-descending order. That is, the last iterator it for which range + [first, it) is sorted. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Possible implementation + +struct is_sorted_until_fn +{ + template S, class Proj = std::identity, + std::indirect_strict_weak_order> Comp = ranges::less> + constexpr I operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + if (first == last) + return first; + + for (auto next = first; ++next != last; first = next) + if (std::invoke(comp, std::invoke(proj, *next), std::invoke(proj, *first))) + return next; + + return first; + } + + template, Proj>> Comp = ranges::less> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(comp), std::ref(proj)); + } +}; + +inline constexpr is_sorted_until_fn is_sorted_until; + +.SH Notes + + ranges::is_sorted_until returns an iterator equal to last for empty ranges and + ranges of length one. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::random_device rd; + std::mt19937 g {rd()}; + std::array nums {3, 1, 4, 1, 5, 9}; + + constexpr int min_sorted_size = 4; + int sorted_size = 0; + do + { + std::ranges::shuffle(nums, g); + const auto sorted_end = std::ranges::is_sorted_until(nums); + sorted_size = std::ranges::distance(nums.begin(), sorted_end); + + std::ranges::copy(nums, std::ostream_iterator(std::cout, " ")); + std::cout << " : " << sorted_size << " leading sorted element(s)\\n"; + } + while (sorted_size < min_sorted_size); + } + +.SH Possible output: + + 4 1 9 5 1 3 : 1 leading sorted element(s) + 4 5 9 3 1 1 : 3 leading sorted element(s) + 9 3 1 4 5 1 : 1 leading sorted element(s) + 1 3 5 4 1 9 : 3 leading sorted element(s) + 5 9 1 1 3 4 : 2 leading sorted element(s) + 4 9 1 5 1 3 : 2 leading sorted element(s) + 1 1 4 9 5 3 : 4 leading sorted element(s) + +.SH See also + + ranges::is_sorted checks whether a range is sorted into ascending order + (C++20) (niebloid) + is_sorted_until finds the largest sorted subrange + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::iter_move.3 b/man/std::ranges::iter_move.3 new file mode 100644 index 000000000..61b2e2065 --- /dev/null +++ b/man/std::ranges::iter_move.3 @@ -0,0 +1,78 @@ +.TH std::ranges::iter_move 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::iter_move \- std::ranges::iter_move + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ iter_move = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr decltype(auto) iter_move( T&& t ) + noexcept(/* see below */); + + Obtains an rvalue reference or a prvalue temporary from a given iterator. + + A ranges::iter_move(t) is expression-equivalent to: + + 1. iter_move(t), if t has a class or enumeration type and the expression is + well-formed when treated as an unevaluated operand, where the overload + resolution of iter_move is performed only with the candidates found by + argument-dependent lookup. + 2. Otherwise, std::move(*t) if *t is well-formed and is an lvalue. + 3. Otherwise, *t if *t is well-formed and is an rvalue. + + In all other cases, a call to ranges::iter_move is ill-formed, which can result in + substitution failure when ranges::iter_move(e) appears in the immediate context of a + template instantiation. + + If ranges::iter_move(e) is not equal to *e, the program is ill-formed, no diagnostic + required. + + Customization point objects + + The name ranges::iter_move denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __iter_move_fn. + + All instances of __iter_move_fn are equal. The effects of invoking different + instances of type __iter_move_fn on the same arguments are equivalent, regardless of + whether the expression denoting the instance is an lvalue or rvalue, and is + const-qualified or not (however, a volatile-qualified instance is not required to be + invocable). Thus, ranges::iter_move can be copied freely and its copies can be used + interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::iter_move above, __iter_move_fn models + + * std::invocable<__iter_move_fn, Args...>, + * std::invocable, + * std::invocable<__iter_move_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __iter_move_fn participates in overload + resolution. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + iter_move casts the result of dereferencing the adjusted underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::iter_swap.3 b/man/std::ranges::iter_swap.3 new file mode 100644 index 000000000..382d81918 --- /dev/null +++ b/man/std::ranges::iter_swap.3 @@ -0,0 +1,98 @@ +.TH std::ranges::iter_swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::iter_swap \- std::ranges::iter_swap + +.SH Synopsis + Defined in header + namespace ranges { + + inline namespace /* unspecified */ { \fI(since C++20)\fP + inline constexpr /* unspecified */ (customization + iter_swap = /* unspecified */; point object) + } + + } + Call signature + template< class I1, class I2 > + constexpr void iter_swap( I1&& i1, I2&& i2 ) noexcept(/* see below \fI(since C++20)\fP + */); + Helper function + template< class X, class Y > + + constexpr std::iter_value_t + iter-exchange-move( X&& x, Y&& y ) (exposition + only*) + noexcept(noexcept(std::iter_value_t(std::ranges::iter_move(x))) + && + + noexcept(*x = std::ranges::iter_move(y))); + + Swaps values denoted by two iterators. + + The effect of the exposition-only helper function iter-exchange-move is equivalent + to + + std::iter_value_t old(std::ranges::iter_move(x)); + *x = std::ranges::iter_move(y); + return old; + + ranges::iter_swap(i1, i2) is expression-equivalent to: + + 1. (void)iter_swap(i1, i2), if i1 or i2 has a class or enumeration type and the + expression is well-formed, where the overload resolution of iter_swap is + performed with the additional candidate void iter_swap(auto, auto) = + delete;^[1], excluding std::ranges::iter_swap itself. + * If the selected overload does not exchange the value denoted by i1 and i2, + the program is ill-formed, no diagnostic required. + 2. Otherwise, ranges::swap(*i1, *i2) if both I1 and I2 model indirectly_readable + and if std::iter_reference_t and std::iter_reference_t model + swappable_with. + 3. Otherwise, (void)(*i1 = iter-exchange-move(i2, i1)), if + std::indirectly_movable_storable and + std::indirectly_movable_storable are both modeled, except that i1 is + only evaluated once. + 4. Otherwise, ranges::iter_swap(i1, i2) is ill-formed, which can result in + substitution failure when ranges::iter_swap(i1, i2) appears in the immediate + context of a template instantiation. + 1. ↑ This precludes calling unconstrained std::iter_swap. + + Customization point objects + + The name ranges::iter_swap denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __iter_swap_fn. + + All instances of __iter_swap_fn are equal. The effects of invoking different + instances of type __iter_swap_fn on the same arguments are equivalent, regardless of + whether the expression denoting the instance is an lvalue or rvalue, and is + const-qualified or not (however, a volatile-qualified instance is not required to be + invocable). Thus, ranges::iter_swap can be copied freely and its copies can be used + interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::iter_swap above, __iter_swap_fn models + + * std::invocable<__iter_swap_fn, Args...>, + * std::invocable, + * std::invocable<__iter_swap_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __iter_swap_fn participates in overload + resolution. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + iter_swap swaps the objects pointed to by two adjusted underlying iterators + (C++20) \fI(function template)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::iterator_t,std::ranges::const_iterator_t,std::ranges::sentinel_t,.3 b/man/std::ranges::iterator_t,std::ranges::const_iterator_t,std::ranges::sentinel_t,.3 new file mode 100644 index 000000000..3d28dc61b --- /dev/null +++ b/man/std::ranges::iterator_t,std::ranges::const_iterator_t,std::ranges::sentinel_t,.3 @@ -0,0 +1,88 @@ +.TH std::ranges::iterator_t,std::ranges::const_iterator_t,std::ranges::sentinel_t, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::iterator_t,std::ranges::const_iterator_t,std::ranges::sentinel_t, \- std::ranges::iterator_t,std::ranges::const_iterator_t,std::ranges::sentinel_t, + +.SH Synopsis + std::ranges::range_value_t, std::ranges::range_reference_t + + Defined in header + template< class T > \fB(1)\fP (since + using iterator_t = decltype(ranges::begin(std::declval())); C++20) + template< ranges::range R > \fB(2)\fP (since + using const_iterator_t = decltype(ranges::cbegin(std::declval())); C++23) + template< ranges::range R > \fB(3)\fP (since + using sentinel_t = decltype(ranges::end(std::declval())); C++20) + template< ranges::range R > \fB(4)\fP (since + using const_sentinel_t = decltype(ranges::cend(std::declval())); C++23) + template< ranges::sized_range R > \fB(5)\fP (since + using range_size_t = decltype(ranges::size(std::declval())); C++20) + template< ranges::range R > (since + using range_difference_t = \fB(6)\fP C++20) + std::iter_difference_t>; + template< ranges::range R > \fB(7)\fP (since + using range_value_t = std::iter_value_t>; C++20) + template< ranges::range R > \fB(8)\fP (since + using range_reference_t = std::iter_reference_t>; C++20) + template< ranges::range R > + (since + using range_const_reference_t = \fB(9)\fP C++23) + + std::iter_const_reference_t>; + template< ranges::range R > + (since + using range_rvalue_reference_t = \fB(10)\fP C++20) + + std::iter_rvalue_reference_t>; + template< ranges::range R > + (since + using range_common_reference_t = \fB(11)\fP C++20) + + std::iter_common_reference_t>; + + 1) Used to obtain the iterator type of the type T. + 2) Used to obtain the constant iterator type of the range type R. + 3) Used to obtain the sentinel type of the range type R. + 4) Used to obtain the constant sentinel type of the range type R. + 5) Used to obtain the size type of the sized_range type R. + 6) Used to obtain the difference type of the iterator type of range type R. + 7) Used to obtain the value type of the iterator type of range type R. + 8) Used to obtain the reference type of the iterator type of range type R. + 9) Used to obtain the constant reference type of the iterator type of range type R. + 10) Used to obtain the rvalue reference type of the iterator type of range type R. + 11) Used to obtain the common reference type of the iterator type of range type R. + +.SH Template parameters + + T - a type that can be used in std::ranges::begin + R - a range type or a sized_range type + +.SH Notes + + iterator_t can be applied to non-range types, e.g. arrays with unknown bound. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3860 C++20 range_common_reference_t was missing added + const_iterator_t and const_sentinel_t were + LWG 3946 C++23 inconsistent tweaked + with the result of ranges::cbegin and + ranges::cend respectively + +.SH See also + + iter_value_t + iter_reference_t + iter_const_reference_t + iter_difference_t + iter_rvalue_reference_t + iter_common_reference_t computes the associated types of an iterator + (C++20) (alias template) + (C++20) + (C++23) + (C++20) + (C++20) + (C++20) diff --git a/man/std::ranges::join_view::base.3 b/man/std::ranges::join_view::base.3 new file mode 100644 index 000000000..7b4def81a --- /dev/null +++ b/man/std::ranges::join_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::join_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::base \- std::ranges::join_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_view::begin.3 b/man/std::ranges::join_view::begin.3 new file mode 100644 index 000000000..6792ba374 --- /dev/null +++ b/man/std::ranges::join_view::begin.3 @@ -0,0 +1,51 @@ +.TH std::ranges::join_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::begin \- std::ranges::join_view::begin + +.SH Synopsis + constexpr auto begin(); \fB(1)\fP (since + C++20) + constexpr auto begin() const + + requires ranges::input_range && \fB(2)\fP (since + C++20) + std::is_reference_v>; + + Returns an iterator to the first element of the join_view. Given base_ is the + underlying view, + + 1) Equivalent to return /*iterator*/{*this, ranges::begin(base_)}; if + __SimpleView is satisfied and ranges::range_reference_t is reference type. + Otherwise, equivalent to return /*iterator*/{*this, ranges::begin(base_)};. + 2) Equivalent to return /*iterator*/{*this, ranges::begin(base_)};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Notes + + When ranges::range_reference_t is not a reference type, that is, deferencing an + iterator of V returns a prvalue temporary, the join_view is only an input_range, in + which case only single-pass iteration is supported, and repeated calls to begin() + may not give meaningful results. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_view::end.3 b/man/std::ranges::join_view::end.3 new file mode 100644 index 000000000..810448b42 --- /dev/null +++ b/man/std::ranges::join_view::end.3 @@ -0,0 +1,63 @@ +.TH std::ranges::join_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::end \- std::ranges::join_view::end + +.SH Synopsis + constexpr auto end(); \fB(1)\fP (since + C++20) + constexpr auto end() const + + requires ranges::input_range && \fB(2)\fP (since + C++20) + std::is_reference_v>; + + Returns a sentinel or an iterator representing the end of the join_view. + + Let base_ be the underlying view: + + 1) Equivalent to + + if constexpr (ranges::forward_range && + std::is_reference_v> && + ranges::forward_range> && + ranges::common_range && + ranges::common_range>) + return /*iterator*/<__SimpleView>{*this, ranges::end(base_)}; + else + return /*sentinel*/<__SimpleView>{*this}; + + 2) Equivalent to + + if constexpr (ranges::forward_range && + std::is_reference_v> && + ranges::forward_range> && + ranges::common_range && + ranges::common_range>) + return /*iterator*/{*this, ranges::end(base_)}; + else + return /*sentinel*/{*this}; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) sentinel which compares equal to the end iterator. + 2) iterator to the element following the last element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_view::iterator.3 b/man/std::ranges::join_view::iterator.3 new file mode 100644 index 000000000..c502a408a --- /dev/null +++ b/man/std::ranges::join_view::iterator.3 @@ -0,0 +1,82 @@ +.TH std::ranges::join_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::iterator \- std::ranges::join_view::iterator + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + class /*iterator*/ (exposition only*) + + The return type of join_view::begin, and of join_view::end when both the outer range + V and the inner range ranges::range_reference_t satisfy common_range and the + parent join_view is a forward_range. + + If V is not a simple view (e.g. if ranges::iterator_t is invalid or + different from ranges::iterator_t), Const is true for iterators returned from the + const overloads, and false otherwise. If V is a simple view, Const is true if and + only if ranges::range_reference_t is a reference. + +.SH Member types + +Member type Definition +Parent const join_view if Const is true, otherwise join_view + (exposition-only member type*) +Base const V if Const is true, otherwise V + (exposition-only member type*) +OuterIter ranges::iterator_t + (exposition-only member type*) +InnerIter ranges::iterator_t> + (exposition-only member type*) + * std::bidirectional_iterator_tag, if ranges::range_reference_t is a reference type, + and Base and ranges::range_reference_t each model bidirectional_range; +iterator_concept * std::forward_iterator_tag, if ranges::range_reference_t is a reference type, and + Base and ranges::range_reference_t each model forward_range; + * std::input_iterator_tag otherwise. + Defined only if iterator::iterator_concept (see above) denotes std::forward_iterator_tag. + + Let OUTERC be std::iterator_traits>::iterator_category, and let + INNERC be + std::iterator_traits>>::iterator_category. +iterator_category + * std::bidirectional_iterator_tag, if OUTERC and INNERC each model + std::derived_from; + * std::forward_iterator_tag, if OUTERC and INNERC each model + std::derived_from; + * std::input_iterator_tag otherwise. +value_type ranges::range_value_t> +difference_type std::common_type_t, + ranges::range_difference_t>> + +.SH Member objects + + Member name Definition + outer_ (private) An object of type OuterIter + (exposition-only member object*) + inner_ (private) An object of type InnerIter + (exposition-only member object*) + parent_ (private) An object of type Parent + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + operator* accesses the element + operator-> \fI(public member function)\fP + (C++20) + operator++ + operator++(int) advances or decrements the underlying iterators + operator-- \fI(public member function)\fP + operator--(int) + (C++20) + satisfy skips over empty inner ranges + (C++20) (exposition-only member function*) + +.SH Non-member functions + + operator== compares the underlying iterators + (C++20) \fI(function)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function)\fP diff --git a/man/std::ranges::join_view::iterator::iterator.3 b/man/std::ranges::join_view::iterator::iterator.3 new file mode 100644 index 000000000..ffee2fd58 --- /dev/null +++ b/man/std::ranges::join_view::iterator::iterator.3 @@ -0,0 +1,39 @@ +.TH std::ranges::join_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::iterator::iterator \- std::ranges::join_view::iterator::iterator + +.SH Synopsis + /*iterator*/() requires std::default_initializable && \fB(1)\fP (since + std::default_initializable = default; C++20) + constexpr /*iterator*/( Parent& parent, OuterIter outer ); \fB(2)\fP (since + C++20) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(3)\fP (since + std::convertible_to, OuterIter> && C++20) + + std::convertible_to, InnerIter>; + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying iterators, and initializes + the pointer to parent ranges::join_view with nullptr. + 2) Initializes the underlying outer_ iterator with std::move(outer), and the pointer + to parent parent_ with std::addressof(parent); then calls satisfy(). + 3) Conversion from /*iterator*/ to /*iterator*/. Move constructs the + underlying iterators outer_ with std::move(i.outer_), inner_ with + std::move(i.inner_), and underlying pointer to parent parent_ with i.parent_. + +.SH Parameters + + parent - a (possibly const-qualified) ranges::join_view + outer - an iterator into (possibly const-qualified) ranges::iterator_t + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_view::iterator::operator*,->.3 b/man/std::ranges::join_view::iterator::operator*,->.3 new file mode 100644 index 000000000..c17b39796 --- /dev/null +++ b/man/std::ranges::join_view::iterator::operator*,->.3 @@ -0,0 +1,29 @@ +.TH std::ranges::join_view::iterator::operator*,-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::iterator::operator*,-> \- std::ranges::join_view::iterator::operator*,-> + +.SH Synopsis + constexpr decltype(auto) operator*() const; \fB(1)\fP \fI(since C++20)\fP + constexpr InnerIter operator->() const \fB(2)\fP \fI(since C++20)\fP + requires /*has-arrow*/ && std::copyable; + + Returns the element the underlying iterator inner_ points to. + + 1) Equivalent to return *inner_;. + 2) Equivalent to return inner_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_view::iterator::operator++,--.3 b/man/std::ranges::join_view::iterator::operator++,--.3 new file mode 100644 index 000000000..76031023d --- /dev/null +++ b/man/std::ranges::join_view::iterator::operator++,--.3 @@ -0,0 +1,79 @@ +.TH std::ranges::join_view::iterator::operator++,-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::iterator::operator++,-- \- std::ranges::join_view::iterator::operator++,-- + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since + C++20) + constexpr void operator++( int ); \fB(2)\fP (since + C++20) + constexpr /*iterator*/ operator++( int ) + (since + requires /*ref-is-glvalue*/ && ranges::forward_range && \fB(3)\fP C++20) + + ranges::forward_range>; + constexpr iterator& operator--() + + requires /*ref-is-glvalue*/ && ranges::bidirectional_range && (since + ranges::bidirectional_range> \fB(4)\fP C++20) + && + + ranges::common_range>; + constexpr /*iterator*/ operator--( int ) + + requires /*ref-is-glvalue*/ && ranges::bidirectional_range && (since + ranges::bidirectional_range> \fB(5)\fP C++20) + && + + ranges::common_range>; + + Increments or decrements the underlying iterator. + + Let inner_ and outer_ be the underlying iterators, and parent_ be the pointer to + parent ranges::join_view, the constant /*ref-is-glvalue*/ be + std::is_reference_v>. + + 1) Let /*inner-range*/ be: + * *outer_, if /*ref-is-glvalue*/ == true; + * *parent_->inner_ otherwise. + + Equivalent to: + + auto&& inner_rng = /*inner-range*/; + if (++inner_ == ranges::end(inner_rng)) { + ++outer_; + satisfy(); + } + return *this; + + 2) Equivalent to: ++*this. + 3) Equivalent to: + + auto tmp = *this; + ++*this; + return tmp; + + 4) Equivalent to: + + if (outer_ == ranges::end(parent_->base_)) + inner_ = ranges::end(*--outer_); + while (inner_ == ranges::begin(*outer_)) + inner_ = ranges::end(*--outer_); + --inner_; + return *this; + + 5) Equivalent to: + + auto tmp = *this; + --*this; + return tmp; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,4) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change diff --git a/man/std::ranges::join_view::iterator::satisfy.3 b/man/std::ranges::join_view::iterator::satisfy.3 new file mode 100644 index 000000000..ac7fd0066 --- /dev/null +++ b/man/std::ranges::join_view::iterator::satisfy.3 @@ -0,0 +1,41 @@ +.TH std::ranges::join_view::iterator::satisfy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::iterator::satisfy \- std::ranges::join_view::iterator::satisfy + +.SH Synopsis + constexpr void satisfy(); \fI(since C++20)\fP + (exposition only*) + + Skips over empty inner ranges and initializes the underlying iterator inner_. + + Let the constant /*ref-is-glvalue*/ be + std::is_reference_v>. + + The function body is equivalent to + + auto update_inner = [this](const ranges::iterator_t& x) -> auto&& + { + if constexpr (/*ref-is-glvalue*/) // *x is a reference + return *x; + else + return parent_->inner_./*emplace-deref*/(x); + }; + + for (; outer_ != ranges::end(parent_->base_); ++outer_) + { + auto&& inner = update_inner(outer_); + inner_ = ranges::begin(inner); + if (inner_ != ranges::end(inner)) + return; + } + + if constexpr (/*ref-is-glvalue*/) + inner_ = InnerIter(); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP diff --git a/man/std::ranges::join_view::join_view.3 b/man/std::ranges::join_view::join_view.3 new file mode 100644 index 000000000..e5bfd68ec --- /dev/null +++ b/man/std::ranges::join_view::join_view.3 @@ -0,0 +1,25 @@ +.TH std::ranges::join_view::join_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::join_view \- std::ranges::join_view::join_view + +.SH Synopsis + join_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit join_view( V base ); \fB(2)\fP \fI(since C++20)\fP + + Constructs a join_view. + + 1) Default constructor. Value-initializes the underlying view. After construction, + base() returns a copy of V(). + 2) Initializes the underlying view with std::move(base). + +.SH Parameters + + base - a view of ranges to be flattened + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_view::sentinel.3 b/man/std::ranges::join_view::sentinel.3 new file mode 100644 index 000000000..42c700252 --- /dev/null +++ b/man/std::ranges::join_view::sentinel.3 @@ -0,0 +1,40 @@ +.TH std::ranges::join_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::sentinel \- std::ranges::join_view::sentinel + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + class /*sentinel*/ (exposition only*) + + The return type of join_view::end when either of the underlying ranges (V or + ranges::range_reference_t) is not a common_range, or when the parent join_view is + not a forward_range. + + If V is not a simple view, Const is true for sentinels returned from the const + overloads, and false otherwise. If V is a simple view, Const is true. + +.SH Member types + + Member type Definition + const ranges::join_view if Const is true, otherwise + Parent (private) ranges::join_view + (exposition-only member type*) + Base (private) const V if Const is true, otherwise V + (exposition-only member type*) + + Data members + + Member object Definition + A sentinel of type std::sentinel_t obtained from (possibly + end_ (private) const-qualified) V. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from join_view::begin + (C++20) \fI(function)\fP diff --git a/man/std::ranges::join_view::sentinel::sentinel.3 b/man/std::ranges::join_view::sentinel::sentinel.3 new file mode 100644 index 000000000..e76d15ce9 --- /dev/null +++ b/man/std::ranges::join_view::sentinel::sentinel.3 @@ -0,0 +1,33 @@ +.TH std::ranges::join_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_view::sentinel::sentinel \- std::ranges::join_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( Parent& parent ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(3)\fP \fI(since C++20)\fP + + std::convertible_to, + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel. + 2) Initializes the underlying sentinel end_ with ranges::end(parent.base_). + 3) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying sentinel end_ with std::move(i.end_). + +.SH Parameters + + parent - a (possibly const-qualified) ranges::join_view + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::base.3 b/man/std::ranges::join_with_view::base.3 new file mode 100644 index 000000000..d9759bbea --- /dev/null +++ b/man/std::ranges::join_with_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::join_with_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::base \- std::ranges::join_with_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::begin.3 b/man/std::ranges::join_with_view::begin.3 new file mode 100644 index 000000000..66fe860f8 --- /dev/null +++ b/man/std::ranges::join_with_view::begin.3 @@ -0,0 +1,46 @@ +.TH std::ranges::join_with_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::begin \- std::ranges::join_with_view::begin + +.SH Synopsis + constexpr auto begin(); \fB(1)\fP (since + C++23) + constexpr auto begin() const + + requires ranges::input_range && \fB(2)\fP (since + ranges::forward_range && C++23) + + std::is_reference_v>; + + Returns an iterator to the first element of the join_with_view. + + Let base_ denote the underlying view: + + 1) Equivalent to return /*iterator*/{*this, ranges::begin(base_)}; if V and + Pattern each model __SimpleView and ranges::range_reference_t is a reference + type; otherwise equivalent to return /*iterator*/{*this, + ranges::begin(base_)};. + 2) Equivalent to return /*iterator*/{*this, ranges::begin(base_)};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the first element of the join_with_view, as described above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::end.3 b/man/std::ranges::join_with_view::end.3 new file mode 100644 index 000000000..fe751d087 --- /dev/null +++ b/man/std::ranges::join_with_view::end.3 @@ -0,0 +1,63 @@ +.TH std::ranges::join_with_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::end \- std::ranges::join_with_view::end + +.SH Synopsis + constexpr auto end(); \fB(1)\fP (since + C++23) + constexpr auto end() const + + requires ranges::input_range && \fB(2)\fP (since + ranges::forward_range && C++23) + + std::is_reference_v>; + + Returns an iterator or a sentinel that compares equal to the end iterator of the + join_with_view. + + Let base_ denote the underlying view: + + 1) Equivalent to: + + if constexpr (ranges::forward_range && + std::is_reference_v> && + ranges::forward_range> && + ranges::common_range && + ranges::common_range>) + return /*iterator*/<__SimpleView && __SimpleView>{*this, ranges::end(base_)}; + else + return /*sentinel*/<__SimpleView && __SimpleView>{*this}; + + 2) Equivalent to: + + if constexpr (ranges::forward_range && + ranges::forward_range> && + ranges::common_range && + ranges::common_range>) + return /*iterator*/{*this, ranges::end(base_)}; + else + return /*sentinel*/{*this}; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator or sentinel representing the end of the join_with_view, as described + above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::iterator.3 b/man/std::ranges::join_with_view::iterator.3 new file mode 100644 index 000000000..e828444c9 --- /dev/null +++ b/man/std::ranges::join_with_view::iterator.3 @@ -0,0 +1,83 @@ +.TH std::ranges::join_with_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::iterator \- std::ranges::join_with_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of join_with_view::begin, and of join_with_view::end when both the + outer range V and the inner range ranges::range_reference_t satisfy common_range + and the parent join_with_view is a forward_range. + + If either V or Pattern is not a simple view, Const is true for iterators returned + from the const overloads, and false otherwise. If V and Pattern are simple views, + Const is true if and only if ranges::range_reference_t is a reference. + +.SH Member types + +Member type Definition +Parent const join_view if Const is true, otherwise join_view + (exposition-only member type*) +Base const V if Const is true, otherwise V + (exposition-only member type*) +InnerBase ranges::range_reference_t + (exposition-only member type*) +PatternBase const Pattern if Const is true, otherwise Pattern + (exposition-only member type*) + * std::bidirectional_iterator_tag, if + * ranges::range_reference_t is a reference type, + * Base, InnerBase and PatternBase each model bidirectional_range, + and +iterator_concept * InnerBase and PatternBase each model common_range; + * std::forward_iterator_tag, if + * ranges::range_reference_t is a reference type, and + * Base and InnerBase each model forward_range; + * std::input_iterator_tag otherwise. + Defined only if iterator::iterator_concept (see above) denotes + std::forward_iterator_tag. Let OUTERC be + std::iterator_traits>::iterator_category, INNERC + be + std::iterator_traits>::iterator_category, + and PATTERNC be + std::iterator_traits>::iterator_category. + + * std::input_iterator_tag, if +iterator_category std::common_reference_t, + ranges::range_reference_t> + is not a reference type; + * std::bidirectional_iterator_tag, if: + * OUTERC, INNERC, and PATTERNC each model + std::derived_from and + * ranges::range_reference_t and PatternBase each model + common_range; + * std::forward_iterator_tag, if OUTERC, INNERC, and PATTERNC each model + std::derived_from; + * std::input_iterator_tag otherwise. +value_type std::common_type_t, + ranges::range_value_t> + std::common_type_t, +difference_type ranges::range_difference_t, + ranges::range_difference_t> + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator++ + operator++(int) advances or decrements the underlying iterator + operator-- \fI(public member function)\fP + operator--(int) + (C++23) + +.SH Non-member functions + + operator== compares the underlying iterators + (C++23) \fI(function)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++23) \fI(function)\fP diff --git a/man/std::ranges::join_with_view::iterator::iterator.3 b/man/std::ranges::join_with_view::iterator::iterator.3 new file mode 100644 index 000000000..78ededbba --- /dev/null +++ b/man/std::ranges::join_with_view::iterator::iterator.3 @@ -0,0 +1,41 @@ +.TH std::ranges::join_with_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::iterator::iterator \- std::ranges::join_with_view::iterator::iterator + +.SH Synopsis + /*iterator*/() requires \fB(1)\fP (since + std::default_initializable> = default; C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && + std::convertible_to, ranges::iterator_t> + && (since + \fB(2)\fP C++23) + std::convertible_to>, + ranges::iterator_t> && + + std::convertible_to, + ranges::iterator_t>; + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying iterator to Base and the + iterator to PatternBase, and initializes the pointer to parent join_with_view with + nullptr. + 2) Conversion from /*iterator*/ to /*iterator*/. Move constructs + corresponding members. + + This iterator also has a private constructor which is used by join_with_view::begin + and join_with_view::end. This constructor is not accessible to users. + +.SH Parameters + + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::iterator::operator*.3 b/man/std::ranges::join_with_view::iterator::operator*.3 new file mode 100644 index 000000000..6cb325ec6 --- /dev/null +++ b/man/std::ranges::join_with_view::iterator::operator*.3 @@ -0,0 +1,29 @@ +.TH std::ranges::join_with_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::iterator::operator* \- std::ranges::join_with_view::iterator::operator* + +.SH Synopsis + constexpr decltype(auto) operator*() const; (since C++23) + + Returns the current element in the joined view. + + The return type is: + + std::common_reference_t, + ranges::range_reference_t> + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::iterator::operator++,--.3 b/man/std::ranges::join_with_view::iterator::operator++,--.3 new file mode 100644 index 000000000..6720e5dd5 --- /dev/null +++ b/man/std::ranges::join_with_view::iterator::operator++,--.3 @@ -0,0 +1,72 @@ +.TH std::ranges::join_with_view::iterator::operator++,-- 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::iterator::operator++,-- \- std::ranges::join_with_view::iterator::operator++,-- + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/ operator++( int ) + + requires std::is_reference_v && \fB(3)\fP (since C++23) + ranges::forward_range && + + ranges::forward_range; + constexpr /*iterator*/& operator--() + + requires std::is_reference_v && + ranges::bidirectional_range && + ranges::bidirectional_range && \fB(4)\fP (since C++23) + ranges::common_range && + ranges::bidirectional_range && + + ranges::common_range; + constexpr /*iterator*/ operator--( int ) + + requires std::is_reference_v && + ranges::bidirectional_range && + ranges::bidirectional_range && \fB(5)\fP (since C++23) + ranges::common_range && + ranges::bidirectional_range && + + ranges::common_range; + + Increments or decrements the iterator. + + 1) Increments the stored inner iterator. (The inner iterator may point to either + InnerBase or PatternBase.) + * If the incremented inner iterator reaches the end of the pattern range, it is + destroyed, and an iterator to the beginning of the next inner range is + constructed. + * If the incremented inner iterator reaches the end of the inner range, the outer + iterator is incremented, and if the outer iterator is not the end iterator, the + inner iterator is destroyed and an iterator to the beginning of the pattern + range is constructed. + * The above steps may be repeated (e.g. if the pattern is empty), until either the + inner range is not empty, or the outer iterator reaches the end. + 2) Equivalent to ++*this; + 3) Equivalent to auto tmp = *this; ++*this; return tmp; + 4) If the outer iterator is the end iterator, it is decremented. Then: + * If the stored inner iterator refers to the beginning of the inner range, it is + destroyed, and an iterator to the end of the pattern range is constructed. + * If the stored inner iterator refers to the beginning of the pattern range, it is + destroyed, the outer iterator is decremented, and an iterator to end of the + inner range is constructed. + * The above steps may be repeated (e.g. if the pattern is empty), until the inner + range is not empty. + Finally, the inner iterator is decremented. + 5) Equivalent to auto tmp = *this; --*this; return tmp; + + If InnerBase is not a reference, the inner range is stored in the parent + join_with_view for iteration. The inner range need not be movable. + + If InnerBase is a reference, and the outer iterator reaches the end, the inner + iterator points to the beginning of the pattern range. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,4) *this + 3,5) A copy of *this that was made before the change. diff --git a/man/std::ranges::join_with_view::join_with_view.3 b/man/std::ranges::join_with_view::join_with_view.3 new file mode 100644 index 000000000..8463d8680 --- /dev/null +++ b/man/std::ranges::join_with_view::join_with_view.3 @@ -0,0 +1,44 @@ +.TH std::ranges::join_with_view::join_with_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::join_with_view \- std::ranges::join_with_view::join_with_view + +.SH Synopsis + join_with_view() + + requires std::default_initializable && \fB(1)\fP (since C++23) + + std::default_initializable = default; + constexpr explicit join_with_view( V base, Pattern pattern ); \fB(2)\fP (since C++23) + template< ranges::input_range R > + + requires std::constructible_from> && + std::constructible_from>>> + constexpr explicit + join_with_view( R&& r, ranges::range_value_t< + + ranges::range_reference_t> e ); + + Constructs a join_with_view. + + 1) Default constructor. Value-initializes the underlying view and the pattern. + 2) Initializes the underlying view with std::move(base) and the stored pattern with + std::move(pattern). + 3) Initializes the underlying view with views::all(std::forward(r)) and the + stored pattern with views::single(std::move(e)). + +.SH Parameters + + base - a view of ranges to be flattened + pattern - view to be used as the delimiter + e - element to be used as the delimiter + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::join_with_view::sentinel.3 b/man/std::ranges::join_with_view::sentinel.3 new file mode 100644 index 000000000..1cb8391ea --- /dev/null +++ b/man/std::ranges::join_with_view::sentinel.3 @@ -0,0 +1,25 @@ +.TH std::ranges::join_with_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::sentinel \- std::ranges::join_with_view::sentinel + +.SH Synopsis + template< bool Const > (since C++23) + class /*sentinel*/ (exposition only*) + + The return type of join_with_view::end when either of the underlying ranges (V or + ranges::range_reference_t) is not a common_range, or when the parent + join_with_view is not a forward_range. + + If either V or Pattern is not a simple view, Const is true for sentinels returned + from the const overloads, and false otherwise. If V and Pattern are simple views, + Const is true. + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from join_with_view::begin + (C++23) \fI(function)\fP diff --git a/man/std::ranges::join_with_view::sentinel::sentinel.3 b/man/std::ranges::join_with_view::sentinel::sentinel.3 new file mode 100644 index 000000000..5e2277ac4 --- /dev/null +++ b/man/std::ranges::join_with_view::sentinel::sentinel.3 @@ -0,0 +1,33 @@ +.TH std::ranges::join_with_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::join_with_view::sentinel::sentinel \- std::ranges::join_with_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel. + 2) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying sentinel with the corresponding member of i. + + This type also has a private constructor which is used by join_with_view::end. This + constructor is not accessible to users. + +.SH Parameters + + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::lazy_split_view::base.3 b/man/std::ranges::lazy_split_view::base.3 new file mode 100644 index 000000000..ea9e465d6 --- /dev/null +++ b/man/std::ranges::lazy_split_view::base.3 @@ -0,0 +1,56 @@ +.TH std::ranges::lazy_split_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::base \- std::ranges::lazy_split_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(std::string_view rem, auto const& r, std::string_view post = "\\n") { + for (std::cout << rem; auto const& e : r) + std::cout << e; + std::cout << post; + } + + int main() + { + constexpr std::string_view keywords{ "this,..throw,..true,..try,.." }; + constexpr std::string_view pattern{",.."}; + constexpr std::ranges::lazy_split_view lazy_split_view{keywords, pattern}; + print("base() = [", lazy_split_view.base(), "]\\n" + "substrings: "); + for (auto const& split: lazy_split_view) + print("[", split, "] "); + } + +.SH Output: + + base() = [this,..throw,..true,..try,..] + substrings: [this] [throw] [true] [try] [] + +.SH See also + + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function of std::ranges::split_view)\fP diff --git a/man/std::ranges::lazy_split_view::begin.3 b/man/std::ranges::lazy_split_view::begin.3 new file mode 100644 index 000000000..656900557 --- /dev/null +++ b/man/std::ranges::lazy_split_view::begin.3 @@ -0,0 +1,49 @@ +.TH std::ranges::lazy_split_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::begin \- std::ranges::lazy_split_view::begin + +.SH Synopsis + constexpr auto begin(); \fB(1)\fP \fI(since C++20)\fP + constexpr auto begin() const + requires ranges::forward_range && ranges::forward_range; + + Returns an outer_iterator to the first element of the lazy_split_view. + + Let base_ be the underlying view. + + 1) Equivalent to + + constexpr auto begin() { + if constexpr (ranges::forward_range) + return /*outer_iterator*/>{*this, ranges::begin(base_)}; + else { + current_ = ranges::begin(base_); + return /*outer_iterator*/{*this}; + } + } + + 2) Equivalent to return /*outer_iterator*/{*this, ranges::begin(base_)};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + outer_iterator to the first element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::lazy_split_view::end.3 b/man/std::ranges::lazy_split_view::end.3 new file mode 100644 index 000000000..b888e7f06 --- /dev/null +++ b/man/std::ranges::lazy_split_view::end.3 @@ -0,0 +1,64 @@ +.TH std::ranges::lazy_split_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::end \- std::ranges::lazy_split_view::end + +.SH Synopsis + constexpr auto end() requires ranges::forward_range && \fB(1)\fP \fI(since C++20)\fP + ranges::common_range; + constexpr auto end() const; \fB(2)\fP \fI(since C++20)\fP + + 1) Returns an iterator representing the end of the view. + + Equivalent to: + + return /*outer_iterator*/>{*this, ranges::end(base_)};. + 2) Returns an outer_iterator or a std::default_sentinel representing the end of the + view. + + Equivalent to: + + if constexpr (ranges::forward_range && ranges::forward_range && + ranges::common_range) + return /*outer_iterator*/{*this, ranges::end(base_)}; + else + return std::default_sentinel; + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An outer_iterator or a std::default_sentinel representing the end of the view. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view keywords{ "false float for friend" }; + std::ranges::lazy_split_view kw{ keywords, ' ' }; + const auto count = std::ranges::distance(kw.begin(), kw.end()); + std::cout << "Words count: " << count << '\\n'; + } + +.SH Output: + + Words count: 4 + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function of std::ranges::split_view)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::lazy_split_view::inner_iterator.3 b/man/std::ranges::lazy_split_view::inner_iterator.3 new file mode 100644 index 000000000..3acba6182 --- /dev/null +++ b/man/std::ranges::lazy_split_view::inner_iterator.3 @@ -0,0 +1,211 @@ +.TH std::ranges::lazy_split_view::inner_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::inner_iterator \- std::ranges::lazy_split_view::inner_iterator + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + struct /*inner_iterator*/; (exposition only*) + + The return type of lazy_split_view::outer_iterator::value_type::begin(). + + Const matches the template argument of outer_iterator. + +.SH Member types + + Member type Definition + Base const V if Const is true, otherwise V + (exposition-only member type*) + iterator_concept equivalent to /*outer_iterator*/::iterator_concept, that is + (C++20) std::forward_iterator_tag if Base models forward_range, or + std::input_iterator_tag otherwise. + * Not present if Base does not model forward_range. + * std::forward_iterator_tag if + iterator_category std::iterator_traits>::iterator_category + (C++20) models std::derived_from. + * std::iterator_traits>::iterator_category + otherwise. + value_type ranges::range_value_t. + (C++20) + difference_type ranges::range_difference_t. + (C++20) + + Data members + + Member object Definition + An iterator of type /*outer_iterator*/ into the + i_ (private) underlying view of the parent lazy_split_view. + (exposition-only member object*) + A boolean flag that indicates whether the operator++ was + incremented_ (private) invoked on this object at least once. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + base returns the underlying iterator + (C++20) \fI(public member function)\fP + operator* returns the current element + (C++20) \fI(public member function)\fP + operator++ advances the iterator + operator++(int) \fI(public member function)\fP + (C++20) + +.SH Member functions + +std::ranges::lazy_split_view::inner_iterator::inner_iterator + + /*inner_iterator*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*inner_iterator*/( /*outer_iterator*/ i \fB(2)\fP \fI(since C++20)\fP + ); + + 1) Value initializes data member i_ via its default member initializer (= + /*outer_iterator*/()). + 2) Initializes i_ with std::move(i). + + The data member incremented_ is initialized with its default member initializer to + false. + +std::ranges::lazy_split_view::inner_iterator::base + + constexpr const ranges::iterator_t& base() const & noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr ranges::iterator_t base() && \fB(2)\fP \fI(since C++20)\fP + requires ranges::forward_range; + + Returns a copy of the underlying iterator. + + 1) Copy constructs the result from the underlying iterator. Equivalent to return + i_./*cur*/();. + 2) Move constructs the result from the underlying iterator. Equivalent to return + std::move(i_./*cur*/());. + +std::ranges::lazy_split_view::inner_iterator::operator* + + constexpr decltype(auto) operator*() const; \fI(since C++20)\fP + + Returns the element the underlying iterator points to. + + Equivalent to return *i_./*cur*/();. + +std::ranges::lazy_split_view::inner_iterator::operator++ + + constexpr /*inner_iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr decltype(auto) operator++(int); \fB(2)\fP \fI(since C++20)\fP + + 1) The function body is equivalent to + incremented_ = true; + + if constexpr (!ranges::forward_range) + { + if constexpr (Pattern::size() == 0) + return *this; + } + ++i_./*cur*/(); + + return *this; + 2) Equivalent to + if constexpr (ranges::forward_range) + + { + auto tmp = *this; + ++*this; + return tmp; + } + else + ++*this; // no return statement + +.SH Non-member functions + + operator== compares the iterators or the iterator and std::default_sentinel + (C++20) \fI(function)\fP + iter_move casts the result of dereferencing the underlying iterator to its + (C++20) associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two underlying iterators + (C++20) \fI(function)\fP + +operator==(std::ranges::split_view::inner_iterator) + + friend constexpr bool operator==( const /*inner_iterator*/& x, + + const /*inner_iterator*/& y ) \fB(1)\fP \fI(since C++20)\fP + + requires forward_range; + friend constexpr bool operator==( const /*inner_iterator*/& x, \fB(2)\fP \fI(since C++20)\fP + std::default_sentinel_t ); + + 1) Equivalent to return x.i_./*cur*/() == y.i_./*cur*/();. + 2) The function body is equivalent to + + auto [pcur, pend] = ranges::subrange{x.i_.parent_->pattern_}; + auto end = ranges::end(x.i_.parent_->base_); + if constexpr (/*tiny_range*/) + { + const auto& cur = x.i_./*cur*/(); + if (cur == end) + return true; + if (pcur == pend) + return x.incremented_; + return *cur == *pcur; + } + else + { + auto cur = x.i_./*cur*/(); + if (cur == end) + return true; + if (pcur == pend) + return x.incremented_; + do + { + if (*cur != *pcur) + return false; + if (++pcur == pend) + return true; + } + while (++cur != end); + return false; + } + + The != operator is synthesized from operator==. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when + std::ranges::split_view::inner_iterator is an associated class of the arguments. + +iter_move(std::ranges::split_view::inner_iterator) + + friend constexpr decltype(auto) iter_move( const /*inner_iterator*/& i (since + ) C++20) + noexcept(noexcept(ranges::iter_move(i.i_./*cur*/()))); + + Equivalent to return ranges::iter_move(i.i_./*cur*/());. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when + std::ranges::split_view::inner_iterator is an associated class of the arguments. + +iter_swap(std::ranges::split_view::inner_iterator) + + friend constexpr void iter_swap( const /*inner_iterator*/& x, + + const /*inner_iterator*/& y ) \fI(since C++20)\fP + noexcept(noexcept(ranges::iter_swap(x.i_.current, y.i_.current))) + + requires std::indirectly_swappable>; + + Equivalent to ranges::iter_swap(x.i_./*cur*/(), y.i_./*cur*/()). + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when + std::ranges::split_view::inner_iterator is an associated class of the arguments. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3591 C++20 the && overload of base might invalidate outer constraints added + iterators + LWG 3593 C++20 the const& overload of base returns a made noexcept + reference but might not be noexcept diff --git a/man/std::ranges::lazy_split_view::lazy_split_view.3 b/man/std::ranges::lazy_split_view::lazy_split_view.3 new file mode 100644 index 000000000..cc717a77c --- /dev/null +++ b/man/std::ranges::lazy_split_view::lazy_split_view.3 @@ -0,0 +1,51 @@ +.TH std::ranges::lazy_split_view::lazy_split_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::lazy_split_view \- std::ranges::lazy_split_view::lazy_split_view + +.SH Synopsis + lazy_split_view() + + requires std::default_initializable && \fB(1)\fP \fI(since C++20)\fP + + std::default_initializable = default; + constexpr explicit lazy_split_view( V base, Pattern pattern ); \fB(2)\fP \fI(since C++20)\fP + template< ranges::input_range R > + + requires std::constructible_from> && + std::constructible_from>> + + constexpr explicit lazy_split_view( R&& r, + ranges::range_value_t e ); + + Constructs a lazy_split_view. + + 1) Default constructor. Value-initializes the underlying view and the delimiter. + 2) Initializes the underlying view with std::move(base) and the delimiter with + std::move(pattern). + 3) Initializes the underlying view with views::all(std::forward(r)) and the + delimiter with ranges::single_view{std::move(e)}. + +.SH Parameters + + base - the underlying view (to be split) + pattern - view to be used as the delimiter + e - element to be used as the delimiter + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was not made explicit + (P2711R1) explicit + +.SH Category: + * Todo no example diff --git a/man/std::ranges::lazy_split_view::outer_iterator.3 b/man/std::ranges::lazy_split_view::outer_iterator.3 new file mode 100644 index 000000000..ad52491b0 --- /dev/null +++ b/man/std::ranges::lazy_split_view::outer_iterator.3 @@ -0,0 +1,208 @@ +.TH std::ranges::lazy_split_view::outer_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::outer_iterator \- std::ranges::lazy_split_view::outer_iterator + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + struct /* outer_iterator */; (exposition only*) + + The return type of lazy_split_view::begin, and of lazy_split_view::end when the + underlying view is a common_range and forward_range. + + If either V or Pattern is not a simple view (e.g. if ranges::iterator_t is + invalid or different from ranges::iterator_t), Const is true for iterators + returned from the const overloads, and false otherwise. If V is a simple view, Const + is true if and only if V is a forward_range. + +.SH Member types + + Member type Definition + const ranges::lazy_split_view if Const is true, otherwise + Parent ranges::lazy_split_view + (exposition-only member type*) + Base const V if Const is true, otherwise V + (exposition-only member type*) + iterator_concept (C++20) std::forward_iterator_tag if Base models forward_range, + otherwise std::input_iterator_tag + iterator_category (C++20) std::input_iterator_tag if Base models forward_range. Not + present otherwise. + value_type (C++20) ranges::lazy_iterator_view + ::/* outer_iterator */::value_type + difference_type (C++20) ranges::range_difference_t. + + Data members + + Member name Definition + A pointer of type Parent* to the parent lazy_split_view + parent_ (private) object + (exposition-only member object*) + An iterator of type ranges::iterator_t into the + current_ (private) underlying view; present only if V models forward_range + (exposition-only member object*) + A boolean flag that indicates whether an empty trailing + trailing_empty_ (private) subrange (if any) was reached + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + operator* returns the current subrange + (C++20) \fI(public member function)\fP + operator++ advances the iterator + operator++(int) \fI(public member function)\fP + (C++20) + cur returns conditionally a reference to the current_ (if present) or to + (C++20) the *parent_->current_ + (exposition-only member function*) + +.SH Member functions + +std::ranges::lazy_split_view::outer_iterator ::outer_iterator + + /* outer_iterator */() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /* outer_iterator */( Parent& parent ) \fB(2)\fP \fI(since C++20)\fP + requires (!ranges::forward_range); + constexpr /* outer_iterator */( Parent& parent, + + ranges::iterator_t current ) \fB(3)\fP \fI(since C++20)\fP + + requires ranges::forward_range; + constexpr /* outer_iterator */( /* outer_iterator */ i ) + + requires Const && std::convertible_to, \fB(4)\fP \fI(since C++20)\fP + + ranges::iterator_t>; + + 1) Value initializes the non-static data members with their default member + initializer, that is: + * parent_ = nullptr;, + * current_ = iterator_t(); (present only if V models forward_range), + 2) Initializes parent_ with std::addressof(parent). + 3) Initializes parent_ with std::addressof(parent) and current_ with + std::move(current). + 4) Initializes parent_ with i.parent_, current_ with std::move(i.current_), and + trailing_empty_ with t.trailing_empty_. + + The trailing_empty_ is initialized with its default member initializer to false. + +std::ranges::lazy_split_view::outer_iterator ::operator* + + constexpr value_type operator*() const; \fI(since C++20)\fP + + Equivalent to return value_type{*this};. + +std::ranges::lazy_split_view::outer_iterator ::operator++ + + constexpr /* outer_iterator */& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr decltype(auto) operator++(int); \fB(2)\fP \fI(since C++20)\fP + + 1) The function body is equivalent to + + const auto end = ranges::end(parent_->base_); + if (/* cur */() == end) + { + trailing_empty_ = false; + return *this; + } + const auto [pbegin, pend] = ranges::subrange{parent_->pattern_}; + if (pbegin == pend) + ++/* cur */(); + else if constexpr (/* tiny_range */) + { + /* cur */() = ranges::find(std::move(/* cur */()), end, *pbegin); + if (/* cur */() != end) + { + ++/* cur */(); + if (/* cur */() == end) + trailing_empty_ = true; + } + } + else + { + do + { + auto [b, p] = ranges::mismatch(/* cur */(), end, pbegin, pend); + if (p == pend) + { + /* cur */() = b; + if (/* cur */() == end) + trailing_empty_ = true; + break; // The pattern matched; skip it + } + } while (++/* cur */() != end); + } + return *this; + + 2) Equivalent to + + if constexpr (ranges::forward_range) + { + auto tmp = *this; + ++*this; + return tmp; + } + else + { + ++*this; // no return statement + } + +std::ranges::lazy_split_view::outer_iterator ::cur () + + constexpr auto& /* cur */() noexcept; \fB(1)\fP \fI(since C++20)\fP + (exposition only*) + constexpr auto& /* cur */() const noexcept; \fB(2)\fP \fI(since C++20)\fP + (exposition only*) + + This convenience member function is referred to from /* outer_iterator + */::operator++(), from the non-member operator==(const /* outer_iterator */&, + std::default_sentinel_t), and from some member functions of the possible + implementation of inner_iterator. + + 1,2) Equivalent to + + if constexpr (ranges::forward_range) + return current_; + else + return *parent->current_; + +.SH Non-member functions + + operator== compares the underlying iterators or the underlying iterator and + (C++20) std::default_sentinel + \fI(function)\fP + +operator==(std::ranges::split_view::outer_iterator) + + friend constexpr bool operator==( const /* outer_iterator */& x, + + const /* outer_iterator */& y ) \fB(1)\fP \fI(since C++20)\fP + + requires forward_range; + friend constexpr bool operator==( const /* outer_iterator */& x, \fB(2)\fP \fI(since C++20)\fP + std::default_sentinel_t ); + + 1) Equivalent to return x.current_ == y.current_ and x.trailing_empty_ == + y.trailing_empty_;. + 2) Equivalent to return x./* cur */() == ranges::end(x.parent_->base_) and + !x.trailing_empty_;. + + The != operator is synthesized from operator==. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when + std::ranges::split_view::outer_iterator is an associated class of the arguments. + + Nested classes + + value_type the value type of the outer_iterator + (C++20) \fI(public member class)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3904 C++20 trailing_empty_ was not initialized in initialized + constructor overload \fB(4)\fP diff --git a/man/std::ranges::lazy_split_view::outer_iterator::value_type.3 b/man/std::ranges::lazy_split_view::outer_iterator::value_type.3 new file mode 100644 index 000000000..1b880d0c7 --- /dev/null +++ b/man/std::ranges::lazy_split_view::outer_iterator::value_type.3 @@ -0,0 +1,64 @@ +.TH std::ranges::lazy_split_view::outer_iterator::value_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lazy_split_view::outer_iterator::value_type \- std::ranges::lazy_split_view::outer_iterator::value_type + +.SH Synopsis + struct value_type : ranges::view_interface \fI(since C++20)\fP + + The value type of the iterator ranges::lazy_split_view::/*outer_iterator*/. + +.SH Member functions + + constructor constructs a value_type object + (C++20) \fI(public member function)\fP + begin returns an inner_iterator to the beginning of the inner range + (C++20) \fI(public member function)\fP + end returns a std::default_sentinel + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + +.SH Member functions + +std::ranges::lazy_split_view::outer_iterator::value_type::value_type + + value_type() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit value_type(/*outer_iterator*/ i); \fB(2)\fP \fI(since C++20)\fP + + 1) Value initializes the i_ via its default member initializer (= + /*outer_iterator*/()). + 2) Initializes i_ with std::move(i). + +std::ranges::lazy_split_view::outer_iterator::value_type::begin + + constexpr /*inner_iterator*/ begin() const; \fI(since C++20)\fP + + Equivalent to return /*inner_iterator*/{i_};. + +std::ranges::lazy_split_view::outer_iterator::value_type::end + + constexpr std::default_sentinel_t end() const noexcept; \fI(since C++20)\fP + + Returns std::default_sentinel. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3593 C++20 end always returns std::default_sentinel but made noexcept + might not be noexcept diff --git a/man/std::ranges::less.3 b/man/std::ranges::less.3 new file mode 100644 index 000000000..e0afb0a55 --- /dev/null +++ b/man/std::ranges::less.3 @@ -0,0 +1,76 @@ +.TH std::ranges::less 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::less \- std::ranges::less + +.SH Synopsis + Defined in header + struct less; \fI(since C++20)\fP + + Function object for performing comparisons. Deduces the parameter types of the + function call operator from the arguments (but not the return type). + +.SH Member functions + + operator() checks if the first argument is less than the second + \fI(public member function)\fP + +std::ranges::less::operator() + + template< class T, class U > + constexpr bool operator()( T&& t, U&& u ) const; + + Given the expression std::forward(t) < std::forward(u) as expr: + + * If expr results in a call to built-in operator< comparing pointers, given the + composite pointer type of t and u as P: + + * If the converted t precedes the converted u (both are of type P) in the + implementation-defined strict total order over pointers, returns true, otherwise + returns false. + * If the conversion sequence from T to P or the conversion sequence from U to P is + not equality-preserving, the behavior is undefined. + * Otherwise: + + * Returns the result of expr. + * If std::totally_ordered_with is not modeled, the behavior is undefined. + + This overload participates in overload resolution only if + std::totally_ordered_with is satisfied. + + If there exists an expression expr1 of type T and an expression expr2 of U, such + that the comparison results of expr1 and expr2 violate strict total ordering (rules + are defined below), the behavior is undefined. + + The comparison results of expr1 and expr2 follow strict total ordering only if + exactly one of the following expressions is true: + + * std::ranges::less{}(expr1, expr2) + * std::ranges::less{}(expr2, expr1) + * std::ranges::equal_to{}(expr1, expr2) + +.SH Notes + + Unlike std::less, std::ranges::less requires all six comparison operators <, <=, >, + >=, == and != to be valid (via the totally_ordered_with constraint). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + less function object implementing x < y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::less_equal.3 b/man/std::ranges::less_equal.3 new file mode 100644 index 000000000..bbe08b316 --- /dev/null +++ b/man/std::ranges::less_equal.3 @@ -0,0 +1,53 @@ +.TH std::ranges::less_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::less_equal \- std::ranges::less_equal + +.SH Synopsis + Defined in header + struct less_equal; \fI(since C++20)\fP + + Function object for performing comparisons. Deduces the parameter types of the + function call operator from the arguments (but not the return type). + +.SH Member functions + + operator() checks if the first argument is less than or equal to the second + \fI(public member function)\fP + +std::ranges::less_equal::operator() + + template< class T, class U > + constexpr bool operator()( T&& t, U&& u ) const; + + Equivalent to return !ranges::less{}(std::forward(u), std::forward(t));. + + This overload participates in overload resolution only if + std::totally_ordered_with is satisfied. + +.SH Notes + + Unlike std::less_equal, std::ranges::less_equal requires all six comparison + operators <, <=, >, >=, == and != to be valid (via the totally_ordered_with + constraint) and is entirely defined in terms of std::ranges::less. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + less_equal function object implementing x <= y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::lexicographical_compare.3 b/man/std::ranges::lexicographical_compare.3 new file mode 100644 index 000000000..d0f36b90d --- /dev/null +++ b/man/std::ranges::lexicographical_compare.3 @@ -0,0 +1,173 @@ +.TH std::ranges::lexicographical_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lexicographical_compare \- std::ranges::lexicographical_compare + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + class Proj1 = std::identity, class Proj2 = + std::identity, + std::indirect_strict_weak_order< + std::projected, \fB(1)\fP \fI(since C++20)\fP + std::projected> Comp = ranges::less > + constexpr bool + lexicographical_compare( I1 first1, S1 last1, I2 first2, S2 + last2, + + Comp comp = {}, Proj1 proj1 = {}, + Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + class Proj1 = std::identity, class Proj2 = + std::identity, + std::indirect_strict_weak_order< + std::projected, Proj1>, \fB(2)\fP \fI(since C++20)\fP + std::projected, Proj2>> Comp + = ranges::less > + constexpr bool + lexicographical_compare( R1&& r1, R2&& r2, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + + Checks if the first range [first1, last1) is lexicographically less than the second + range [first2, last2). + + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + Lexicographical comparison is an operation with the following properties: + + * Two ranges are compared element by element. + * The first mismatching element defines which range is lexicographically less or + greater than the other. + * If one range is a prefix of another, the shorter range is lexicographically less + than the other. + * If two ranges have equivalent elements and are of the same length, then the + ranges are lexicographically equal. + * An empty range is lexicographically less than any non-empty range. + * Two empty ranges are lexicographically equal. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the first range of elements to examine + r1 - the first range of elements to examine + first2, last2 - the second range of elements to examine + r2 - the second range of elements to examine + comp - comparison function to apply to the projected elements + proj1 - projection to apply to the first range of elements + proj2 - projection to apply to the second range of elements + +.SH Return value + + true if the first range is lexicographically less than the second. + +.SH Complexity + + At most 2·min(N1, N2) applications of the comparison and corresponding projections, + where N1 = ranges::distance(first1, last1) and N2 = ranges::distance(first2, last2). + +.SH Possible implementation + +struct lexicographical_compare_fn +{ + template S1, + std::input_iterator I2, std::sentinel_for S2, + class Proj1 = std::identity, class Proj2 = std::identity, + std::indirect_strict_weak_order< + std::projected, + std::projected> Comp = ranges::less> + constexpr bool operator()(I1 first1, S1 last1, I2 first2, S2 last2, + Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; (first1 != last1) && (first2 != last2); ++first1, (void) ++first2) + { + if (std::invoke(comp, std::invoke(proj1, *first1), std::invoke(proj2, *first2))) + return true; + + if (std::invoke(comp, std::invoke(proj2, *first2), std::invoke(proj1, *first1))) + return false; + } + return (first1 == last1) && (first2 != last2); + } + + template, Proj1>, + std::projected, Proj2>> Comp = ranges::less> + constexpr bool operator()(R1&& r1, R2&& r2, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::ref(comp), std::ref(proj1), std::ref(proj2)); + } +}; + +inline constexpr lexicographical_compare_fn lexicographical_compare; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector v1 {'a', 'b', 'c', 'd'}; + std::vector v2 {'a', 'b', 'c', 'd'}; + + namespace ranges = std::ranges; + auto os = std::ostream_iterator(std::cout, " "); + + std::mt19937 g {std::random_device {}()}; + while (not ranges::lexicographical_compare(v1, v2)) + { + ranges::copy(v1, os); + std::cout << ">= "; + ranges::copy(v2, os); + std::cout << '\\n'; + + ranges::shuffle(v1, g); + ranges::shuffle(v2, g); + } + + ranges::copy(v1, os); + std::cout << "< "; + ranges::copy(v2, os); + std::cout << '\\n'; + } + +.SH Possible output: + + a b c d >= a b c d + d a b c >= c b d a + b d a c >= a d c b + a c d b < c d a b + +.SH See also + + ranges::equal determines if two sets of elements are the same + (C++20) (niebloid) + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP diff --git a/man/std::ranges::lower_bound.3 b/man/std::ranges::lower_bound.3 new file mode 100644 index 000000000..05d2febba --- /dev/null +++ b/man/std::ranges::lower_bound.3 @@ -0,0 +1,224 @@ +.TH std::ranges::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::lower_bound \- std::ranges::lower_bound + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class T, class Proj = std::identity, (since + std::indirect_strict_weak_order C++20) + > Comp = (until + ranges::less > C++26) + constexpr I lower_bound( I first, S last, const T& value, + + Comp comp = {}, Proj proj = {} ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t, + std::indirect_strict_weak_order (since + > Comp = C++26) + ranges::less > + constexpr I lower_bound( I first, S last, const T& value, + + Comp comp = {}, Proj proj = {} ); + template< ranges::forward_range R, + + class T, class Proj = std::identity, + std::indirect_strict_weak_order \fB(1)\fP + , C++20) + Proj>> Comp = (until + ranges::less > C++26) + constexpr ranges::borrowed_iterator_t + + lower_bound( R&& r, const T& value, Comp comp = {}, Proj + proj = {} ); + template< ranges::forward_range R, \fB(2)\fP + + class Proj = std::identity, + class T = + std::projected_value_t, Proj> + std::indirect_strict_weak_order + , C++26) + Proj>> Comp = + ranges::less > + constexpr ranges::borrowed_iterator_t + + lower_bound( R&& r, const T& value, Comp comp = {}, Proj + proj = {} ); + + 1) Returns an iterator pointing to the first element in the range [first, last) that + is not less than (i.e. greater or equal to) value, or last if no such element is + found. The range [first, last) must be partitioned with respect to the expression + std::invoke(comp, std::invoke(proj, element), value), i.e., all elements for which + the expression is true must precede all elements for which the expression is false. + A fully-sorted range meets this criterion. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair defining the partially-ordered range to examine + r - the partially-ordered range to examine + value - value to compare the projected elements to + comp - comparison predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Iterator pointing to the first element that is not less than value, or last if no + such element is found. + +.SH Complexity + + The number of comparisons and applications of the projection performed are + logarithmic in the distance between first and last (at most log + 2(last - first) + O(1) comparisons and applications of the projection). However, for + an iterator that does not model random_access_iterator, the number of iterator + increments is linear. + +.SH Notes + + On a range that's fully sorted (or more generally, partially ordered with respect to + value) after projection, std::ranges::lower_bound implements the binary search + algorithm. Therefore, std::ranges::binary_search can be implemented in terms of it. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Possible implementation + + struct lower_bound_fn + { + template S, class Proj = std::identity, + class T = std::projected_value_t, + std::indirect_strict_weak_order + > Comp = ranges::less> + constexpr I operator()(I first, S last, const T& value, + Comp comp = {}, Proj proj = {}) const + { + I it; + std::iter_difference_t count, step; + count = std::ranges::distance(first, last); + + while (count > 0) + { + it = first; + step = count / 2; + ranges::advance(it, step, last); + if (comp(std::invoke(proj, *it), value)) + { + first = ++it; + count -= step + 1; + } + else + count = step; + } + return first; + } + + template, Proj> + std::indirect_strict_weak_order + , + Proj>> Comp = ranges::less> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, const T& value, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, + std::ref(comp), std::ref(proj)); + } + }; + + inline constexpr lower_bound_fn lower_bound; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + namespace ranges = std::ranges; + + template S, class T, + class Proj = std::identity, + std::indirect_strict_weak_order + > Comp = ranges::less> + constexpr I binary_find(I first, S last, const T& value, Comp comp = {}, Proj proj = {}) + { + first = ranges::lower_bound(first, last, value, comp, proj); + return first != last && !comp(value, proj(*first)) ? first : last; + } + + int main() + { + std::vector data{1, 2, 2, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 5}; + // ^^^^^^^^^^ + auto lower = ranges::lower_bound(data, 4); + auto upper = ranges::upper_bound(data, 4); + + std::cout << "found a range [" << ranges::distance(data.cbegin(), lower) + << ", " << ranges::distance(data.cbegin(), upper) << ") = { "; + ranges::copy(lower, upper, std::ostream_iterator(std::cout, " ")); + std::cout << "}\\n"; + + // classic binary search, returning a value only if it is present + + data = {1, 2, 4, 8, 16}; + // ^ + auto it = binary_find(data.cbegin(), data.cend(), 8); // '5' would return end() + + if (it != data.cend()) + std::cout << *it << " found at index "<< ranges::distance(data.cbegin(), it); + + using CD = std::complex; + std::vector nums{{1, 0}, {2, 2}, {2, 1}, {3, 0}}; + auto cmpz = [](CD x, CD y) { return x.real() < y.real(); }; + #ifdef __cpp_lib_algorithm_default_value_type + auto it2 = ranges::lower_bound(nums, {2, 0}, cmpz); + #else + auto it2 = ranges::lower_bound(nums, CD{2, 0}, cmpz); + #endif + assert((*it2 == CD{2, 2})); + } + +.SH Output: + + found a range [6, 10) = { 4 4 4 4 } + 8 found at index 3 + +.SH See also + + ranges::equal_range returns range of elements matching a specific key + (C++20) (niebloid) + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::partition_point locates the partition point of a partitioned range + (C++20) (niebloid) + ranges::upper_bound returns an iterator to the first element greater than a + (C++20) certain value + (niebloid) + returns an iterator to the first element not less than the + lower_bound given value + \fI(function template)\fP diff --git a/man/std::ranges::make_heap.3 b/man/std::ranges::make_heap.3 new file mode 100644 index 000000000..7cc19ef2e --- /dev/null +++ b/man/std::ranges::make_heap.3 @@ -0,0 +1,177 @@ +.TH std::ranges::make_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::make_heap \- std::ranges::make_heap + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + make_heap( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Comp = + ranges::less, + + class Proj = std::identity > \fB(2)\fP \fI(since C++20)\fP + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + + make_heap( R&& r, Comp comp = {}, Proj proj = {} ); + + Constructs a max heap in the range [first, last). + + 1) Elements are compared using the given binary comparison function comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to make the heap from + r - the range of elements to make the heap from + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Given N = ranges::distance(first, last), at most \\(\\scriptsize 3\\cdot N\\)3*N + comparisons and \\(\\scriptsize 6\\cdot N\\)6*N projections. + +.SH Notes + + A max heap is a range of elements [f, l), arranged with respect to comparator comp + and projection proj, that has the following properties: + + * With N = l - f, p = f[(i - 1) / 2], and q = f[i], for all 0 < i < N, the + expression std::invoke(comp, std::invoke(proj, p), std::invoke(proj, q)) + evaluates to false. + * A new element can be added using ranges::push_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + * The first element can be removed using ranges::pop_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void out(const auto& what, int n = 1) + { + while (n-- > 0) + std::cout << what; + } + + void print(auto rem, auto const& v) + { + out(rem); + for (auto e : v) + out(e), out(' '); + out('\\n'); + } + + void draw_heap(auto const& v) + { + auto bails = [](int n, int w) + { + auto b = [](int w) { out("┌"), out("─", w), out("┴"), out("─", w), out("┐"); }; + if (!(n /= 2)) + return; + for (out(' ', w); n-- > 0;) + b(w), out(' ', w + w + 1); + out('\\n'); + }; + + auto data = [](int n, int w, auto& first, auto last) + { + for (out(' ', w); n-- > 0 && first != last; ++first) + out(*first), out(' ', w + w + 1); + out('\\n'); + }; + + auto tier = [&](int t, int m, auto& first, auto last) + { + const int n{1 << t}; + const int w{(1 << (m - t - 1)) - 1}; + bails(n, w), data(n, w, first, last); + }; + + const int m{static_cast(std::ceil(std::log2(1 + v.size())))}; + auto first{v.cbegin()}; + for (int i{}; i != m; ++i) + tier(i, m, first, v.cend()); + } + + int main() + { + std::vector h{1, 6, 1, 8, 0, 3, 3, 9, 8, 8, 7, 4, 9, 8, 9}; + print("source: ", h); + + std::ranges::make_heap(h); + print("\\n" "max-heap: ", h); + draw_heap(h); + + std::ranges::make_heap(h, std::greater{}); + print("\\n" "min-heap: ", h); + draw_heap(h); + } + +.SH Output: + + source: 1 6 1 8 0 3 3 9 8 8 7 4 9 8 9 + + max-heap: 9 8 9 8 8 4 9 6 1 0 7 1 3 8 3 + 9 + ┌───┴───┐ + 8 9 + ┌─┴─┐ ┌─┴─┐ + 8 8 4 9 + ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ + 6 1 0 7 1 3 8 3 + + min-heap: 0 1 1 8 6 3 3 9 8 8 7 4 9 8 9 + 0 + ┌───┴───┐ + 1 1 + ┌─┴─┐ ┌─┴─┐ + 8 6 3 3 + ┌┴┐ ┌┴┐ ┌┴┐ ┌┴┐ + 9 8 8 7 4 9 8 9 + +.SH See also + + ranges::is_heap checks if the given range is a max heap + (C++20) (niebloid) + ranges::is_heap_until finds the largest subrange that is a max heap + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) + make_heap creates a max heap out of a range of elements + \fI(function template)\fP diff --git a/man/std::ranges::max.3 b/man/std::ranges::max.3 new file mode 100644 index 000000000..689daf4fb --- /dev/null +++ b/man/std::ranges::max.3 @@ -0,0 +1,166 @@ +.TH std::ranges::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::max \- std::ranges::max + +.SH Synopsis + Defined in header + Call signature + template< class T, class Proj = std::identity, + + std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(1)\fP C++20) + constexpr const T& + + max( const T& a, const T& b, Comp comp = {}, Proj proj = {} ); + template< std::copyable T, class Proj = std::identity, + + std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(2)\fP C++20) + constexpr T + + max( std::initializer_list r, Comp comp = {}, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = + ranges::less > \fB(3)\fP (since + requires std::indirectly_copyable_storable, C++20) + ranges::range_value_t*> + constexpr ranges::range_value_t + + max( R&& r, Comp comp = {}, Proj proj = {} ); + + Returns the greater of the given projected values. + + 1) Returns the greater of a and b. + 2) Returns the first greatest value in the initializer list r. + 3) Returns the first greatest value in the range r. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + a, b - the values to compare + r - the range of values to compare + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1) The greater of a and b, according to their respective projected values. If they + are equivalent, returns a. + 2,3) The greatest value in r, according to the projection. If several values are + equivalent to the greatest, returns the leftmost one. If the range is empty (as + determined by ranges::distance(r)), the behavior is undefined. + +.SH Complexity + + 1) Exactly one comparison. + 2,3) Exactly ranges::distance(r) - 1 comparisons. + +.SH Possible implementation + + struct max_fn + { + template> Comp = ranges::less> + constexpr + const T& operator()(const T& a, const T& b, Comp comp = {}, Proj proj = {}) const + { + return std::invoke(comp, std::invoke(proj, a), std::invoke(proj, b)) ? b : a; + } + + template> Comp = ranges::less> + constexpr + T operator()(std::initializer_list r, Comp comp = {}, Proj proj = {}) const + { + return *ranges::max_element(r, std::ref(comp), std::ref(proj)); + } + + template, Proj>> Comp = ranges::less> + requires std::indirectly_copyable_storable, + ranges::range_value_t*> + constexpr + ranges::range_value_t operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + using V = ranges::range_value_t; + if constexpr (ranges::forward_range) + return + static_cast(*ranges::max_element(r, std::ref(comp), std::ref(proj))); + else + { + auto i = ranges::begin(r); + auto s = ranges::end(r); + V m(*i); + while (++i != s) + if (std::invoke(comp, std::invoke(proj, m), std::invoke(proj, *i))) + m = *i; + return m; + } + } + }; + + inline constexpr max_fn max; + +.SH Notes + + Capturing the result of std::ranges::max by reference produces a dangling reference + if one of the parameters is a temporary and that parameter is returned: + + int n = -1; + const int& r = std::ranges::max(n + 2, n * 2); // r is dangling + +.SH Example + + +// Run this code + + #include + #include + #include + + static_assert(std::ranges::max({0B10, 0X10, 010, 10}) == 16); // overload (2) + + int main() + { + namespace ranges = std::ranges; + using namespace std::string_view_literals; + + std::cout << "larger of 1 and 9999: " << ranges::max(1, 9999) << '\\n' + << "larger of 'a', and 'b': '" << ranges::max('a', 'b') << "'\\n" + << "longest of \\"foo\\", \\"bar\\", and \\"hello\\": \\"" + << ranges::max({"foo"sv, "bar"sv, "hello"sv}, {}, + &std::string_view::size) << "\\"\\n"; + } + +.SH Output: + + larger of 1 and 9999: 9999 + larger of 'a', and 'b': 'b' + longest of "foo", "bar", and "hello": "hello" + +.SH See also + + ranges::min returns the smaller of the given values + (C++20) (niebloid) + ranges::minmax returns the smaller and larger of two elements + (C++20) (niebloid) + ranges::max_element returns the largest element in a range + (C++20) (niebloid) + ranges::clamp clamps a value between a pair of boundary values + (C++20) (niebloid) + max returns the greater of the given values + \fI(function template)\fP diff --git a/man/std::ranges::max_element.3 b/man/std::ranges::max_element.3 new file mode 100644 index 000000000..7666c568e --- /dev/null +++ b/man/std::ranges::max_element.3 @@ -0,0 +1,124 @@ +.TH std::ranges::max_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::max_element \- std::ranges::max_element + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, class Proj = + std::identity, + + std::indirect_strict_weak_order> Comp \fB(1)\fP (since + = ranges::less > C++20) + constexpr I + + max_element( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = \fB(2)\fP (since + ranges::less > C++20) + constexpr ranges::borrowed_iterator_t + + max_element( R&& r, Comp comp = {}, Proj proj = {} ); + + 1) Finds the greatest element in the range [first, last). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range to examine + r - the range to examine + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Iterator to the greatest element in the range [first, last). If several elements in + the range are equivalent to the greatest element, returns the iterator to the first + such element. Returns last if the range is empty (i.e. if first == last). + +.SH Complexity + + Exactly max(N - 1, 0) comparisons, where N = ranges::distance(first, last). + +.SH Possible implementation + +struct max_element_fn +{ + template S, class Proj = std::identity, + std::indirect_strict_weak_order> Comp = ranges::less> + constexpr I operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + if (first == last) + return last; + + auto largest = first; + while (++first != last) + if (std::invoke(comp, std::invoke(proj, *largest), std::invoke(proj, *first))) + largest = first; + return largest; + } + + template, Proj>> Comp = ranges::less> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(comp), std::ref(proj)); + } +}; + +inline constexpr max_element_fn max_element; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + const auto v = {3, 1, -14, 1, 5, 9, -14, 9}; + + auto result = ranges::max_element(v.begin(), v.end()); + std::cout << "Max element at pos " << ranges::distance(v.begin(), result) << '\\n'; + + auto abs_compare = [](int a, int b) { return std::abs(a) < std::abs(b); }; + result = ranges::max_element(v, abs_compare); + std::cout << "Absolute max element at pos " + << ranges::distance(v.begin(), result) << '\\n'; + } + +.SH Output: + + Max element at pos 5 + Absolute max element at pos 2 + +.SH See also + + ranges::min_element returns the smallest element in a range + (C++20) (niebloid) + ranges::minmax_element returns the smallest and the largest elements in a range + (C++20) (niebloid) + ranges::max returns the greater of the given values + (C++20) (niebloid) + max_element returns the largest element in a range + \fI(function template)\fP diff --git a/man/std::ranges::merge,std::ranges::merge_result.3 b/man/std::ranges::merge,std::ranges::merge_result.3 new file mode 100644 index 000000000..35b5a0717 --- /dev/null +++ b/man/std::ranges::merge,std::ranges::merge_result.3 @@ -0,0 +1,206 @@ +.TH std::ranges::merge,std::ranges::merge_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::merge,std::ranges::merge_result \- std::ranges::merge,std::ranges::merge_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity + > \fB(1)\fP \fI(since C++20)\fP + requires std::mergeable + constexpr merge_result + merge( I1 first1, S1 last1, I2 first2, S2 last2, O result, + Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity + > + requires std::mergeable, + ranges::iterator_t, \fB(2)\fP \fI(since C++20)\fP + O, Comp, Proj1, Proj2> + constexpr merge_result, + ranges::borrowed_iterator_t, O> + merge( R1&& r1, R2&& r2, O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I1, class I2, class O > \fB(3)\fP \fI(since C++20)\fP + using merge_result = ranges::in_in_out_result; + + Merges two sorted ranges [[first1, last1) and [first2, last2) into one sorted range + beginning at result. + + A sequence is said to be sorted with respect to the comparator comp if for any + iterator it pointing to the sequence and any non-negative integer n such that it + n + is a valid iterator pointing to an element of the sequence, std::invoke(comp, + std::invoke(proj2, *(it + n)), std::invoke(proj1, *it))) evaluates to false. + + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r1 as the first range and r2 as the second range, as if + using ranges::begin(r1) as first1, ranges::end(r1) as last1, ranges::begin(r2) as + first2, and ranges::end(r2) as last2. + + The behavior is undefined if the destination range overlaps either of the input + ranges (the input ranges may overlap each other). + + This merge function is stable, which means that for equivalent elements in the + original two ranges, the elements from the first range (preserving their original + order) precede the elements from the second range (preserving their original order). + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the first input sorted range + first2, last2 - the second input sorted range + result - the beginning of the output range + comp - comparison to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + {last1, last2, result_last}, where result_last is the end of the constructed range. + +.SH Complexity + + At most N − 1 comparisons and applications of each projection, where N = + ranges::distance(first1, last1) + ranges::distance(first2, last12). + +.SH Notes + + This algorithm performs a similar task as ranges::set_union does. Both consume two + sorted input ranges and produce a sorted output with elements from both inputs. The + difference between these two algorithms is with handling values from both input + ranges which compare equivalent (see notes on LessThanComparable). If any equivalent + values appeared n times in the first range and m times in the second, ranges::merge + would output all n + m occurrences whereas ranges::set_union would output max(n, m) + ones only. So ranges::merge outputs exactly N values and ranges::set_union may + produce fewer. + +.SH Possible implementation + +struct merge_fn +{ + template S1, + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::mergeable + constexpr ranges::merge_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; !(first1 == last1 or first2 == last2); ++result) + { + if (std::invoke(comp, std::invoke(proj2, *first2), std::invoke(proj1, *first1))) + *result = *first2, ++first2; + else + *result = *first1, ++first1; + } + auto ret1{ranges::copy(std::move(first1), std::move(last1), std::move(result))}; + auto ret2{ranges::copy(std::move(first2), std::move(last2), std::move(ret1.out))}; + return {std::move(ret1.in), std::move(ret2.in), std::move(ret2.out)}; + } + + template + requires std::mergeable, ranges::iterator_t, + O, Comp, Proj1, Proj2> + constexpr ranges::merge_result, + ranges::borrowed_iterator_t, O> + operator()(R1&& r1, R2&& r2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(result), std::move(comp), + std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr merge_fn merge {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(const auto& in1, const auto& in2, auto first, auto last) + { + std::cout << "{ "; + for (const auto& e : in1) + std::cout << e << ' '; + std::cout << "} +\\n{ "; + for (const auto& e : in2) + std::cout << e << ' '; + std::cout << "} =\\n{ "; + while (!(first == last)) + std::cout << *first++ << ' '; + std::cout << "}\\n\\n"; + } + + int main() + { + std::vector in1, in2, out; + + in1 = {1, 2, 3, 4, 5}; + in2 = {3, 4, 5, 6, 7}; + out.resize(in1.size() + in2.size()); + const auto ret = std::ranges::merge(in1, in2, out.begin()); + print(in1, in2, out.begin(), ret.out); + + in1 = {1, 2, 3, 4, 5, 5, 5}; + in2 = {3, 4, 5, 6, 7}; + out.clear(); + out.reserve(in1.size() + in2.size()); + std::ranges::merge(in1, in2, std::back_inserter(out)); + print(in1, in2, out.cbegin(), out.cend()); + } + +.SH Output: + + { 1 2 3 4 5 } + + { 3 4 5 6 7 } = + { 1 2 3 3 4 4 5 5 6 7 } + + { 1 2 3 4 5 5 5 } + + { 3 4 5 6 7 } = + { 1 2 3 3 4 4 5 5 5 5 6 7 } + +.SH See also + + ranges::inplace_merge merges two ordered ranges in-place + (C++20) (niebloid) + ranges::is_sorted checks whether a range is sorted into ascending order + (C++20) (niebloid) + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::sort sorts a range into ascending order + (C++20) (niebloid) + ranges::stable_sort sorts a range of elements while preserving order between equal + (C++20) elements + (niebloid) + merge merges two sorted ranges + \fI(function template)\fP diff --git a/man/std::ranges::min.3 b/man/std::ranges::min.3 new file mode 100644 index 000000000..fdfc6c60f --- /dev/null +++ b/man/std::ranges::min.3 @@ -0,0 +1,164 @@ +.TH std::ranges::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::min \- std::ranges::min + +.SH Synopsis + Defined in header + Call signature + template< class T, class Proj = std::identity, + + std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(1)\fP C++20) + constexpr const T& + + min( const T& a, const T& b, Comp comp = {}, Proj proj = {} ); + template< std::copyable T, class Proj = std::identity, + + std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(2)\fP C++20) + constexpr T + + min( std::initializer_list r, Comp comp = {}, Proj proj = {} ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = + ranges::less > \fB(3)\fP (since + requires std::indirectly_copyable_storable, C++20) + ranges::range_value_t*> + constexpr ranges::range_value_t + + min( R&& r, Comp comp = {}, Proj proj = {} ); + + Returns the smaller of the given projected elements. + + 1) Returns the smaller of a and b. + 2) Returns the first smallest element in the initializer list r. + 3) Returns the first smallest value in the range r. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + a, b - the values to compare + r - the range of values to compare + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1) The smaller of a and b, according to the projection. If they are equivalent, + returns a. + 2,3) The smallest element in r, according to the projection. If several values are + equivalent to the smallest, returns the leftmost one. If the range is empty (as + determined by ranges::distance(r)), the behavior is undefined. + +.SH Complexity + + 1) Exactly one comparison. + 2,3) Exactly ranges::distance(r) - 1 comparisons. + +.SH Possible implementation + + struct min_fn + { + template> Comp = ranges::less> + constexpr + const T& operator()(const T& a, const T& b, Comp comp = {}, Proj proj = {}) const + { + return std::invoke(comp, std::invoke(proj, b), std::invoke(proj, a)) ? b : a; + } + + template> Comp = ranges::less> + constexpr + T operator()(std::initializer_list r, Comp comp = {}, Proj proj = {}) const + { + return *ranges::min_element(r, std::ref(comp), std::ref(proj)); + } + + template, Proj>> Comp = ranges::less> + requires std::indirectly_copyable_storable, + ranges::range_value_t*> + constexpr + ranges::range_value_t operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + using V = ranges::range_value_t; + if constexpr (ranges::forward_range) + return + static_cast(*ranges::min_element(r, std::ref(comp), std::ref(proj))); + else + { + auto i = ranges::begin(r); + auto s = ranges::end(r); + V m(*i); + while (++i != s) + if (std::invoke(comp, std::invoke(proj, *i), std::invoke(proj, m))) + m = *i; + return m; + } + } + }; + + inline constexpr min_fn min; + +.SH Notes + + Capturing the result of std::ranges::min by reference produces a dangling reference + if one of the parameters is a temporary and that parameter is returned: + + int n = -1; + const int& r = std::ranges::min(n + 2, n * 2); // r is dangling + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + using namespace std::string_view_literals; + + std::cout << "smaller of 1 and 9999: " << ranges::min(1, 9999) << '\\n' + << "smaller of 'a', and 'b': '" << ranges::min('a', 'b') << "'\\n" + << "shortest of \\"foo\\", \\"bar\\", and \\"hello\\": \\"" + << ranges::min({"foo"sv, "bar"sv, "hello"sv}, {}, + &std::string_view::size) << "\\"\\n"; + } + +.SH Output: + + smaller of 1 and 9999: 1 + smaller of 'a', and 'b': 'a' + shortest of "foo", "bar", and "hello": "foo" + +.SH See also + + ranges::max returns the greater of the given values + (C++20) (niebloid) + ranges::minmax returns the smaller and larger of two elements + (C++20) (niebloid) + ranges::min_element returns the smallest element in a range + (C++20) (niebloid) + ranges::clamp clamps a value between a pair of boundary values + (C++20) (niebloid) + min returns the smaller of the given values + \fI(function template)\fP diff --git a/man/std::ranges::min_element.3 b/man/std::ranges::min_element.3 new file mode 100644 index 000000000..bd0c15f83 --- /dev/null +++ b/man/std::ranges::min_element.3 @@ -0,0 +1,125 @@ +.TH std::ranges::min_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::min_element \- std::ranges::min_element + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, class Proj = + std::identity, + + std::indirect_strict_weak_order> Comp \fB(1)\fP (since + = ranges::less > C++20) + constexpr I + + min_element( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = \fB(2)\fP (since + ranges::less > C++20) + constexpr ranges::borrowed_iterator_t + + min_element( R&& r, Comp comp = {}, Proj proj = {} ); + + 1) Finds the smallest element in the range [first, last). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range to examine + r - the range to examine + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Iterator to the smallest element in the range [first, last). If several elements in + the range are equivalent to the smallest element, returns the iterator to the first + such element. Returns last if the range is empty (i.e., first == last). + +.SH Complexity + + Exactly max(N - 1, 0) comparisons, where N = ranges::distance(first, last). + +.SH Possible implementation + +struct min_element_fn +{ + template S, class Proj = std::identity, + std::indirect_strict_weak_order> Comp = ranges::less> + constexpr I operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + if (first == last) + return last; + auto smallest = first; + while (++first != last) + if (std::invoke(comp, std::invoke(proj, *first), std::invoke(proj, *smallest))) + smallest = first; + return smallest; + } + + template, Proj>> Comp = ranges::less> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(comp), std::ref(proj)); + } +}; + +inline constexpr min_element_fn min_element; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + std::array v{3, 1, -13, 1, 3, 7, -13}; + + auto iterator = ranges::min_element(v.begin(), v.end()); + auto position = ranges::distance(v.begin(), iterator); + std::cout << "min element is v[" << position << "] == " << *iterator << '\\n'; + + auto abs_compare = [](int a, int b) { return (std::abs(a) < std::abs(b)); }; + iterator = ranges::min_element(v, abs_compare); + position = ranges::distance(v.begin(), iterator); + std::cout << "|min| element is v[" << position << "] == " << *iterator << '\\n'; + } + +.SH Output: + + min element is v[2] == -13 + |min| element is v[1] == 1 + +.SH See also + + ranges::max_element returns the largest element in a range + (C++20) (niebloid) + ranges::minmax_element returns the smallest and the largest elements in a range + (C++20) (niebloid) + ranges::max returns the greater of the given values + (C++20) (niebloid) + min_element returns the smallest element in a range + \fI(function template)\fP diff --git a/man/std::ranges::min_max_result.3 b/man/std::ranges::min_max_result.3 new file mode 100644 index 000000000..9cecba1c2 --- /dev/null +++ b/man/std::ranges::min_max_result.3 @@ -0,0 +1,134 @@ +.TH std::ranges::min_max_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::min_max_result \- std::ranges::min_max_result + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + struct min_max_result; + + ranges::min_max_result is a class template that provides a way to store two objects + or references of the same type as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + T - the type of the objects or references that the ranges::min_max_result stores. + + Data members + + Member name Definition + may be a reference to, a copy of, or an iterator of type T to a minimum + min element in a range. + \fI(public member object)\fP + may be a reference to, a copy of, or an iterator of type T to a maximum + max element in a range + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::min_max_result::operator min_max_result + + template + + requires std::convertible_to \fB(1)\fP + + constexpr operator min_max_result() const &; + template + + requires std::convertible_to \fB(2)\fP + + constexpr operator min_max_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {min, max};. + 2) Equivalent to return {std::move(min), std::move(max)};. + +.SH Standard library + + The following standard library functions use ranges::min_max_result as the return + type: + + Algorithm functions + ranges::minmax returns the smaller and larger of two elements + (C++20) (niebloid) + ranges::minmax_element returns the smallest and the largest elements in a range + (C++20) (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct min_max_result + { + [[no_unique_address]] T min; + [[no_unique_address]] T max; + + template + requires std::convertible_to + constexpr operator min_max_result() const & + { + return {min, max}; + } + + template + requires std::convertible_to + constexpr operator min_max_result() && + { + return {std::move(min), std::move(max)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr static auto v = {3, 1, 4, 1, 5, 9, 2}; + { + constexpr auto result = std::ranges::minmax(v); + static_assert(1 == result.min && 9 == result.max); + } + { + constexpr auto result = std::ranges::minmax_element(v); + static_assert(1 == *result.min && 9 == *result.max); + } + } + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::minmax,std::ranges::minmax_result.3 b/man/std::ranges::minmax,std::ranges::minmax_result.3 new file mode 100644 index 000000000..3ddb61ca3 --- /dev/null +++ b/man/std::ranges::minmax,std::ranges::minmax_result.3 @@ -0,0 +1,184 @@ +.TH std::ranges::minmax,std::ranges::minmax_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::minmax,std::ranges::minmax_result \- std::ranges::minmax,std::ranges::minmax_result + +.SH Synopsis + Defined in header + Call signature + template< class T, class Proj = std::identity, + + std::indirect_strict_weak_order< (since + std::projected> Comp = ranges::less > \fB(1)\fP C++20) + constexpr ranges::minmax_result + + minmax( const T& a, const T& b, Comp comp = {}, Proj proj = {} ); + template< std::copyable T, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected> Comp = ranges::less > \fB(2)\fP (since + constexpr ranges::minmax_result C++20) + + minmax( std::initializer_list r, Comp comp = {}, Proj proj = {} + ); + template< ranges::input_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = + ranges::less > \fB(3)\fP (since + requires std::indirectly_copyable_storable, C++20) + ranges::range_value_t*> + constexpr ranges::minmax_result> + + minmax( R&& r, Comp comp = {}, Proj proj = {} ); +.SH Helper types + template< class T > \fB(4)\fP (since + using minmax_result = ranges::min_max_result; C++20) + + Returns the smallest and the greatest of the given projected values. + + 1) Returns references to the smaller and the greater of a and b. + 2) Returns the smallest and the greatest of the values in the initializer list r. + 3) Returns the smallest and the greatest of the values in the range r. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + a, b - the values to compare + r - a non-empty range of values to compare + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1) {b, a} if, according to their respective projected value, b is smaller than a; + otherwise it returns {a, b}. + 2,3) {s, l}, where s and l are respectively the smallest and largest values in r, + according to their projected value. If several values are equivalent to the smallest + and largest, returns the leftmost smallest value, and the rightmost largest value. + If the range is empty (as determined by ranges::distance(r)), the behavior is + undefined. + +.SH Complexity + + 1) Exactly one comparison and two applications of the projection. + 2,3) At most 3 / 2 * ranges::distance(r) comparisons and twice as many applications + of the projection. + +.SH Possible implementation + + struct minmax_fn + { + template> Comp = ranges::less> + constexpr ranges::minmax_result + operator()(const T& a, const T& b, Comp comp = {}, Proj proj = {}) const + { + if (std::invoke(comp, std::invoke(proj, b), std::invoke(proj, a))) + return {b, a}; + + return {a, b}; + } + + template> Comp = ranges::less> + constexpr ranges::minmax_result + operator()(std::initializer_list r, Comp comp = {}, Proj proj = {}) const + { + auto result = ranges::minmax_element(r, std::ref(comp), std::ref(proj)); + return {*result.min, *result.max}; + } + + template, Proj>> Comp = ranges::less> + requires std::indirectly_copyable_storable, + ranges::range_value_t*> + constexpr ranges::minmax_result> + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + auto result = ranges::minmax_element(r, std::ref(comp), std::ref(proj)); + return {std::move(*result.min), std::move(*result.max)}; + } + }; + + inline constexpr minmax_fn minmax; + +.SH Notes + + For overload \fB(1)\fP, if one of the parameters is a temporary, the reference returned + becomes a dangling reference at the end of the full expression that contains the + call to minmax: + + int n = 1; + auto p = std::ranges::minmax(n, n + 1); + int m = p.min; // ok + int x = p.max; // undefined behavior + + // Note that structured bindings have the same issue + auto [mm, xx] = std::ranges::minmax(n, n + 1); + xx; // undefined behavior + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + constexpr std::array v{3, 1, 4, 1, 5, 9, 2, 6, 5}; + + std::random_device rd; + std::mt19937_64 generator(rd()); + std::uniform_int_distribution<> distribution(0, ranges::distance(v)); // [0..9] + + // auto bounds = ranges::minmax(distribution(generator), distribution(generator)); + // UB: dangling references: bounds.min and bounds.max have the type `const int&`. + + const int x1 = distribution(generator); + const int x2 = distribution(generator); + auto bounds = ranges::minmax(x1, x2); // OK: got references to lvalues x1 and x2 + + std::cout << "v[" << bounds.min << ":" << bounds.max << "]: "; + for (int i = bounds.min; i < bounds.max; ++i) + std::cout << v[i] << ' '; + std::cout << '\\n'; + + auto [min, max] = ranges::minmax(v); + std::cout << "smallest: " << min << ", " << "largest: " << max << '\\n'; + } + +.SH Possible output: + + v[3:9]: 1 5 9 2 6 5 + smallest: 1, largest: 9 + +.SH See also + + ranges::min returns the smaller of the given values + (C++20) (niebloid) + ranges::max returns the greater of the given values + (C++20) (niebloid) + ranges::minmax_element returns the smallest and the largest elements in a range + (C++20) (niebloid) + ranges::clamp clamps a value between a pair of boundary values + (C++20) (niebloid) + minmax returns the smaller and larger of two elements + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::minmax_element,std::ranges::minmax_element_result.3 b/man/std::ranges::minmax_element,std::ranges::minmax_element_result.3 new file mode 100644 index 000000000..226911d9b --- /dev/null +++ b/man/std::ranges::minmax_element,std::ranges::minmax_element_result.3 @@ -0,0 +1,167 @@ +.TH std::ranges::minmax_element,std::ranges::minmax_element_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::minmax_element,std::ranges::minmax_element_result \- std::ranges::minmax_element,std::ranges::minmax_element_result + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, class Proj = + std::identity, + + std::indirect_strict_weak_order> Comp \fB(1)\fP (since + = ranges::less > C++20) + constexpr minmax_element_result + + minmax_element( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + std::indirect_strict_weak_order< + std::projected, Proj>> Comp = \fB(2)\fP (since + ranges::less > C++20) + constexpr minmax_element_result> + + minmax_element( R&& r, Comp comp = {}, Proj proj = {} ); +.SH Helper types + template< class I > \fB(3)\fP (since + using minmax_element_result = ranges::min_max_result; C++20) + + 1) Finds the smallest and largest elements in the range [first, last). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range to examine + r - the range to examine + comp - comparison to apply to the projected elements + proj - projection to apply to the elements. + +.SH Return value + + An object consisting of an iterator to the smallest element as the first element and + an iterator to the greatest element as the second. Returns {first, first} if the + range is empty. If several elements are equivalent to the smallest element, the + iterator to the first such element is returned. If several elements are equivalent + to the largest element, the iterator to the last such element is returned. + +.SH Complexity + + At most std::max(std::floor(1.5 * (N − 1)), 0.0) applications of the comparison and + twice as many applications of the projection, where N = ranges::distance(first, + last). + +.SH Possible implementation + +struct minmax_element_fn +{ + template S, class Proj = std::identity, + std::indirect_strict_weak_order> Comp = ranges::less> + constexpr ranges::minmax_element_result + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + auto min = first, max = first; + + if (first == last || ++first == last) + return {min, max}; + + if (std::invoke(comp, std::invoke(proj, *first), + std::invoke(proj, *min))) + min = first; + else + max = first; + + while (++first != last) + { + auto i = first; + if (++first == last) + { + if (std::invoke(comp, std::invoke(proj, *i), + std::invoke(proj, *min))) + min = i; + else if (!(std::invoke(comp, std::invoke(proj, *i), + std::invoke(proj, *max)))) + max = i; + break; + } + else + { + if (std::invoke(comp, std::invoke(proj, *first), + std::invoke(proj, *i))) + { + if (std::invoke(comp, std::invoke(proj, *first), + std::invoke(proj, *min))) + min = first; + if (!(std::invoke(comp, std::invoke(proj, *i), + std::invoke(proj, *max)))) + max = i; + } + else + { + if (std::invoke(comp, std::invoke(proj, *i), + std::invoke(proj, *min))) + min = i; + if (!(std::invoke(comp, std::invoke(proj, *first), + std::invoke(proj, *max)))) + max = first; + } + } + } + return {min, max}; + } + + template, Proj>> Comp = ranges::less> + constexpr ranges::minmax_element_result> + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::ref(comp), std::ref(proj)); + } +}; + +inline constexpr minmax_element_fn minmax_element; + +.SH Example + + +// Run this code + + #include + #include + #include + namespace ranges = std::ranges; + + int main() + { + const auto v = {3, 9, 1, 4, 1, 2, 5, 9}; + const auto [min, max] = ranges::minmax_element(v); + std::cout + << "min = " << *min << ", at [" << ranges::distance(v.begin(), min) << "]\\n" + << "max = " << *max << ", at [" << ranges::distance(v.begin(), max) << "]\\n"; + } + +.SH Output: + + min = 1, at [2] + max = 9, at [7] + +.SH See also + + ranges::min_element returns the smallest element in a range + (C++20) (niebloid) + ranges::max_element returns the largest element in a range + (C++20) (niebloid) + ranges::minmax returns the smaller and larger of two elements + (C++20) (niebloid) + minmax_element returns the smallest and the largest elements in a range + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::mismatch,std::ranges::mismatch_result.3 b/man/std::ranges::mismatch,std::ranges::mismatch_result.3 new file mode 100644 index 000000000..9bb4a3a1a --- /dev/null +++ b/man/std::ranges::mismatch,std::ranges::mismatch_result.3 @@ -0,0 +1,175 @@ +.TH std::ranges::mismatch,std::ranges::mismatch_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::mismatch,std::ranges::mismatch_result \- std::ranges::mismatch,std::ranges::mismatch_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity + > \fB(1)\fP \fI(since C++20)\fP + requires std::indirectly_comparable + constexpr mismatch_result + mismatch( I1 first1, S1 last1, I2 first2, S2 last2, + + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {} + ); + template< ranges::input_range R1, ranges::input_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity + > + requires std::indirectly_comparable< + ranges::iterator_t, ranges::iterator_t, Pred, \fB(2)\fP \fI(since C++20)\fP + Proj1, Proj2> + constexpr mismatch_result, + ranges::borrowed_iterator_t> + mismatch( R1&& r1, R2&& r2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I1, class I2 > \fB(3)\fP \fI(since C++20)\fP + using mismatch_result = ranges::in_in_result; + + Returns the first mismatching pair of projected elements from two ranges: one + defined by [first1, last1) or r1 and another defined by [first2, last2) or r2. + + 1) Elements are compared using the given binary predicate p. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - an iterator-sentinel pair denoting the first range of the elements + to compare + r1 - the first range of the elements to compare + first2, last2 - an iterator-sentinel pair denoting the second range of the elements + to compare + r2 - the second range of the elements to compare + pred - predicate to apply to the projected elements + proj1 - projection to apply to the first range of elements + proj2 - projection to apply to the second range of elements + +.SH Return value + + ranges::mismatch_result with iterators to the first two non-equal elements. + + If no mismatches are found when the comparison reaches last1 or last2, whichever + happens first, the object holds the end iterator and the corresponding iterator from + the other range. + +.SH Complexity + + At most std::min(last1 - first1, last2 - first2) applications of the predicate and + corresponding projections. + +.SH Possible implementation + + struct mismatch_fn + { + template S1, + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr std::mismatch_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; first1 != last1 && first2 != last2; ++first1, (void)++first2) + if (not std::invoke(pred, std::invoke(proj1, *first1), + std::invoke(proj2, *first2))) + break; + + return {first1, first2}; + } + + template + requires std::indirectly_comparable, ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr ranges::mismatch_result, + ranges::borrowed_iterator_t> + operator()(R1&& r1, R2&& r2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::ref(pred), std::ref(proj1), std::ref(proj2)); + } + }; + + inline constexpr mismatch_fn mismatch; + +.SH Example + + This program determines the longest substring that is simultaneously found at the + very beginning and at the very end of the given string, in reverse order (possibly + overlapping). + + +// Run this code + + #include + #include + #include + #include + + [[nodiscard]] + constexpr std::string_view mirror_ends(const std::string_view in) + { + const auto end = std::ranges::mismatch(in, in | std::views::reverse).in1; + return {in.cbegin(), end}; + } + + int main() + { + std::cout << mirror_ends("abXYZba") << '\\n' + << mirror_ends("abca") << '\\n' + << mirror_ends("ABBA") << '\\n' + << mirror_ends("level") << '\\n'; + + using namespace std::literals::string_view_literals; + + static_assert("123"sv == mirror_ends("123!@#321")); + static_assert("radar"sv == mirror_ends("radar")); + } + +.SH Output: + + ab + a + ABBA + level + +.SH See also + + ranges::equal determines if two sets of elements are the same + (C++20) (niebloid) + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::lexicographical_compare returns true if one range is lexicographically less + (C++20) than another + (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + mismatch finds the first position where two ranges differ + \fI(function template)\fP diff --git a/man/std::ranges::move,std::ranges::move_result.3 b/man/std::ranges::move,std::ranges::move_result.3 new file mode 100644 index 000000000..0b370555c --- /dev/null +++ b/man/std::ranges::move,std::ranges::move_result.3 @@ -0,0 +1,148 @@ +.TH std::ranges::move,std::ranges::move_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::move,std::ranges::move_result \- std::ranges::move,std::ranges::move_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + std::weakly_incrementable O > + + requires std::indirectly_movable \fB(1)\fP \fI(since C++20)\fP + constexpr move_result + + move( I first, S last, O result ); + template< ranges::input_range R, std::weakly_incrementable O > + + requires std::indirectly_movable, O> \fB(2)\fP \fI(since C++20)\fP + constexpr move_result, O> + + move( R&& r, O result ); +.SH Helper types + template< class I, class O > \fB(3)\fP \fI(since C++20)\fP + using move_result = ranges::in_out_result; + + 1) Moves the elements in the range, defined by [first, last), to another range + beginning at result. The behavior is undefined if result is within the range + [first, last). In such a case, ranges::move_backward may be used instead. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The elements in the moved-from range will still contain valid values of the + appropriate type, but not necessarily the same values as before the move. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to move + last - the end of the range of elements to move + r - the range of the elements to move + result - the beginning of the destination range + +.SH Return value + + {last, result + N}, where + + 1) N = ranges::distance(first, last). + 2) N = ranges::distance(r). + +.SH Complexity + + Exactly N move assignments. + +.SH Notes + + When moving overlapping ranges, ranges::move is appropriate when moving to the left + (beginning of the destination range is outside the source range) while + ranges::move_backward is appropriate when moving to the right (end of the + destination range is outside the source range). + +.SH Possible implementation + + struct move_fn + { + template S, std::weakly_incrementable O> + requires std::indirectly_movable + constexpr ranges::move_result + operator()(I first, S last, O result) const + { + for (; first != last; ++first, ++result) + *result = ranges::iter_move(first); + return {std::move(first), std::move(result)}; + } + template + requires std::indirectly_movable, O> + constexpr ranges::move_result, O> + operator()(R&& r, O result) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result)); + } + }; + + inline constexpr move_fn move {}; + +.SH Example + + The following code moves thread objects (which themselves are non copyable) from one + container to another. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + using namespace std::literals::chrono_literals; + + void f(std::chrono::milliseconds n) + { + std::this_thread::sleep_for(n); + std::cout << "thread with n=" << n.count() << "ms ended" << std::endl; + } + + int main() + { + std::vector v; + v.emplace_back(f, 400ms); + v.emplace_back(f, 600ms); + v.emplace_back(f, 800ms); + + std::list l; + + // std::ranges::copy() would not compile, because std::jthread is non-copyable + std::ranges::move(v, std::back_inserter(l)); + } + +.SH Output: + + thread with n=400ms ended + thread with n=600ms ended + thread with n=800ms ended + +.SH See also + + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) + move moves a range of elements to a new location + \fI(C++11)\fP \fI(function template)\fP + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::move_backward,std::ranges::move_backward_result.3 b/man/std::ranges::move_backward,std::ranges::move_backward_result.3 new file mode 100644 index 000000000..c069c2716 --- /dev/null +++ b/man/std::ranges::move_backward,std::ranges::move_backward_result.3 @@ -0,0 +1,170 @@ +.TH std::ranges::move_backward,std::ranges::move_backward_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::move_backward,std::ranges::move_backward_result \- std::ranges::move_backward,std::ranges::move_backward_result + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I1, std::sentinel_for S1, + + std::bidirectional_iterator I2 > (since + requires std::indirectly_movable \fB(1)\fP C++20) + constexpr move_backward_result + + move_backward( I1 first, S1 last, I2 result ); + template< ranges::bidirectional_range R, std::bidirectional_iterator I > + + requires std::indirectly_movable, I> \fB(2)\fP (since + constexpr move_backward_result, I> C++20) + + move_backward( R&& r, I result ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using move_backward_result = ranges::in_out_result; C++20) + + 1) Moves the elements in the range, defined by [first, last), to another range + [result - N, result), where N = ranges::distance(first, last). The elements are + moved in reverse order (the last element is moved first), but their relative order + is preserved. The behavior is undefined if result is within (first, last]. In such a + case, ranges::move may be used instead. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The elements in the moved-from range will still contain valid values of the + appropriate type, but not necessarily the same values as before the move, as if + using *(result - n) = ranges::iter_move(last - n) for each integer n, where 0 ≤ n < + N. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to move + last - the end of the range of elements to move + r - the range of the elements to move + result - the end of the destination range + +.SH Return value + + {last, result - N}. + +.SH Complexity + + 1) Exactly N move assignments. + 2) Exactly ranges::distance(r) move assignments. + +.SH Notes + + When moving overlapping ranges, ranges::move is appropriate when moving to the left + (beginning of the destination range is outside the source range) while + ranges::move_backward is appropriate when moving to the right (end of the + destination range is outside the source range). + +.SH Possible implementation + + struct move_backward_fn + { + template S1, + std::bidirectional_iterator I2> + requires std::indirectly_movable + constexpr ranges::move_backward_result + operator()(I1 first, S1 last, I2 result) const + { + auto i {last}; + for (; i != first; *--result = ranges::iter_move(--i)) + {} + return {std::move(last), std::move(result)}; + } + + template + requires std::indirectly_movable, I> + constexpr ranges::move_backward_result, I> + operator()(R&& r, I result) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result)); + } + }; + + inline constexpr move_backward_fn move_backward {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using Vec = std::vector; + + void print(std::string_view rem, Vec const& vec) + { + std::cout << rem << "[" << vec.size() << "]: "; + for (const std::string& s : vec) + std::cout << (s.size() ? s : std::string{"·"}) << ' '; + std::cout << '\\n'; + } + + int main() + { + Vec a{"▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"}; + Vec b(a.size()); + + print("Before move:\\n" "a", a); + print("b", b); + + std::ranges::move_backward(a, b.end()); + + print("\\n" "Move a >> b:\\n" "a", a); + print("b", b); + + std::ranges::move_backward(b.begin(), b.end(), a.end()); + print("\\n" "Move b >> a:\\n" "a", a); + print("b", b); + + std::ranges::move_backward(a.begin(), a.begin()+3, a.end()); + print("\\n" "Overlapping move a[0, 3) >> a[5, 8):\\n" "a", a); + } + +.SH Possible output: + + Before move: + a[8]: ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ + b[8]: · · · · · · · · + + Move a >> b: + a[8]: · · · · · · · · + b[8]: ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ + + Move b >> a: + a[8]: ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ + b[8]: · · · · · · · · + + Overlapping move a[0, 3) >> a[5, 8): + a[8]: · · · ▄ ▅ ▁ ▂ ▃ + +.SH See also + + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) + move moves a range of elements to a new location + \fI(C++11)\fP \fI(function template)\fP + move obtains an rvalue reference + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::next.3 b/man/std::ranges::next.3 new file mode 100644 index 000000000..5f41f633e --- /dev/null +++ b/man/std::ranges::next.3 @@ -0,0 +1,134 @@ +.TH std::ranges::next 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::next \- std::ranges::next + +.SH Synopsis + Defined in header + Call signature + template< std::input_or_output_iterator I > \fB(1)\fP \fI(since C++20)\fP + constexpr I next( I i ); + template< std::input_or_output_iterator I > \fB(2)\fP \fI(since C++20)\fP + constexpr I next( I i, std::iter_difference_t n ); + template< std::input_or_output_iterator I, std::sentinel_for S + > \fB(3)\fP \fI(since C++20)\fP + constexpr I next( I i, S bound ); + template< std::input_or_output_iterator I, std::sentinel_for S + > \fB(4)\fP \fI(since C++20)\fP + constexpr I next( I i, std::iter_difference_t n, S bound ); + + Return the n^th successor of iterator i. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + i - an iterator + n - number of elements to advance + bound - sentinel denoting the end of the range i points to + +.SH Return value + + 1) The successor of iterator i. + 2) The n^th successor of iterator i. + 3) The first iterator equivalent to bound. + 4) The n^th successor of iterator i, or the first iterator equivalent to bound, + whichever is first. + +.SH Complexity + + 1) Constant. + 2) Constant if I models std::random_access_iterator; otherwise linear. + 3) Constant if I and S models both std::random_access_iterator and + std::sized_sentinel_for, or if I and S models std::assignable_from; + otherwise linear. + 4) Constant if I and S models both std::random_access_iterator and + std::sized_sentinel_for; otherwise linear. + +.SH Possible implementation + + struct next_fn + { + template + constexpr I operator()(I i) const + { + ++i; + return i; + } + + template + constexpr I operator()(I i, std::iter_difference_t n) const + { + ranges::advance(i, n); + return i; + } + + template S> + constexpr I operator()(I i, S bound) const + { + ranges::advance(i, bound); + return i; + } + + template S> + constexpr I operator()(I i, std::iter_difference_t n, S bound) const + { + ranges::advance(i, n, bound); + return i; + } + }; + + inline constexpr auto next = next_fn(); + +.SH Notes + + Although the expression ++x.begin() often compiles, it is not guaranteed to do so: + x.begin() is an rvalue expression, and there is no requirement that specifies that + increment of an rvalue is guaranteed to work. In particular, when iterators are + implemented as pointers or its operator++ is lvalue-ref-qualified, ++x.begin() does + not compile, while ranges::next(x.begin()) does. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto v = {3, 1, 4}; + { + auto n = std::ranges::next(v.begin()); + assert(*n == 1); + } + { + auto n = std::ranges::next(v.begin(), 2); + assert(*n == 4); + } + { + auto n = std::ranges::next(v.begin(), v.end()); + assert(n == v.end()); + } + { + auto n = std::ranges::next(v.begin(), 42, v.end()); + assert(n == v.end()); + } + } + +.SH See also + + ranges::prev decrement an iterator by a given distance or to a bound + (C++20) (niebloid) + ranges::advance advances an iterator by given distance or to a given bound + (C++20) (niebloid) + next increment an iterator + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::next_permutation,std::ranges::next_permutation_result.3 b/man/std::ranges::next_permutation,std::ranges::next_permutation_result.3 new file mode 100644 index 000000000..b5893eed3 --- /dev/null +++ b/man/std::ranges::next_permutation,std::ranges::next_permutation_result.3 @@ -0,0 +1,230 @@ +.TH std::ranges::next_permutation,std::ranges::next_permutation_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::next_permutation,std::ranges::next_permutation_result \- std::ranges::next_permutation,std::ranges::next_permutation_result + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > (since + requires std::sortable \fB(1)\fP C++20) + constexpr next_permutation_result + + next_permutation( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::bidirectional_range R, class Comp = ranges::less, + + class Proj = std::identity > (since + requires std::sortable, Comp, Proj> \fB(2)\fP C++20) + constexpr next_permutation_result> + + next_permutation( R&& r, Comp comp = {}, Proj proj = {} ); + Helper type + template< class I > \fB(3)\fP (since + using next_permutation_result = ranges::in_found_result; C++20) + + 1) Transforms the range [first, last) into the next permutation, where the set of + all permutations is ordered lexicographically with respect to binary comparison + function object comp and projection function object proj. Returns {last, true} if + such a "next permutation" exists; otherwise transforms the range into the + lexicographically first permutation as if by ranges::sort(first, last, comp, proj), + and returns {last, false}. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to permute + r - the range of elements to permute + comp - comparison function object which returns true if the first argument is + less than the second + proj - projection to apply to the elements + +.SH Return value + + 1) ranges::next_permutation_result{last, true} if the new permutation is + lexicographically greater than the old one. ranges::next_permutation_result{last, + false} if the last permutation was reached and the range was reset to the first + permutation. + 2) Same as \fB(1)\fP except that the return type is + ranges::next_permutation_result>. + +.SH Exceptions + + Any exceptions thrown from iterator operations or the element swap. + +.SH Complexity + + At most \\(\\scriptsize N/2\\)N / 2 swaps, where \\(\\scriptsize N\\)N is + ranges::distance(first, last) in case \fB(1)\fP or ranges::distance(r) in case \fB(2)\fP. + Averaged over the entire sequence of permutations, typical implementations use about + 3 comparisons and 1.5 swaps per call. + +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + models contiguous_iterator and swapping its value type calls neither non-trivial + special member function nor ADL-found swap. + +.SH Possible implementation + +struct next_permutation_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr ranges::next_permutation_result + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + // check that the sequence has at least two elements + if (first == last) + return {std::move(first), false}; + I i_last{ranges::next(first, last)}; + I i{i_last}; + if (first == --i) + return {std::move(i_last), false}; + // main "permutating" loop + for (;;) + { + I i1{i}; + if (std::invoke(comp, std::invoke(proj, *--i), std::invoke(proj, *i1))) + { + I j{i_last}; + while (!std::invoke(comp, std::invoke(proj, *i), std::invoke(proj, *--j))) + {} + std::iter_swap(i, j); + std::reverse(i1, i_last); + return {std::move(i_last), true}; + } + // permutation "space" is exhausted + if (i == first) + { + std::reverse(first, i_last); + return {std::move(i_last), false}; + } + } + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::next_permutation_result> + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::move(comp), std::move(proj)); + } +}; + +inline constexpr next_permutation_fn next_permutation {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + struct S + { + char c; + int i; + auto operator<=>(const S&) const = default; + friend std::ostream& operator<<(std::ostream& os, const S& s) + { + return os << "{'" << s.c << "', " << s.i << "}"; + } + }; + + auto print = [](auto const& v, char term = ' ') + { + std::cout << "{ "; + for (const auto& e : v) + std::cout << e << ' '; + std::cout << '}' << term; + }; + + int main() + { + std::cout << "Generate all permutations (iterators case):\\n"; + std::string s{"abc"}; + do + { + print(s); + } + while (std::ranges::next_permutation(s.begin(), s.end()).found); + + std::cout << "\\n" "Generate all permutations (range case):\\n"; + std::array a{'a', 'b', 'c'}; + do + { + print(a); + } + while (std::ranges::next_permutation(a).found); + + std::cout << "\\n" "Generate all permutations using comparator:\\n"; + using namespace std::literals; + std::array z{"█"s, "▄"s, "▁"s}; + do + { + print(z); + } + while (std::ranges::next_permutation(z, std::greater()).found); + + std::cout << "\\n" "Generate all permutations using projection:\\n"; + std::array r{S{'A',3}, S{'B',2}, S{'C',1}}; + do + { + print(r, '\\n'); + } + while (std::ranges::next_permutation(r, {}, &S::c).found); + } + +.SH Output: + + Generate all permutations (iterators case): + { a b c } { a c b } { b a c } { b c a } { c a b } { c b a } + Generate all permutations (range case): + { a b c } { a c b } { b a c } { b c a } { c a b } { c b a } + Generate all permutations using comparator: + { █ ▄ ▁ } { █ ▁ ▄ } { ▄ █ ▁ } { ▄ ▁ █ } { ▁ █ ▄ } { ▁ ▄ █ } + Generate all permutations using projection: + { {'A', 3} {'B', 2} {'C', 1} } + { {'A', 3} {'C', 1} {'B', 2} } + { {'B', 2} {'A', 3} {'C', 1} } + { {'B', 2} {'C', 1} {'A', 3} } + { {'C', 1} {'A', 3} {'B', 2} } + { {'C', 1} {'B', 2} {'A', 3} } + +.SH See also + + ranges::prev_permutation generates the next smaller lexicographic permutation of a + (C++20) range of elements + (niebloid) + ranges::is_permutation determines if a sequence is a permutation of another + (C++20) sequence + (niebloid) + generates the next greater lexicographic permutation of a + next_permutation range of elements + \fI(function template)\fP + generates the next smaller lexicographic permutation of a + prev_permutation range of elements + \fI(function template)\fP + is_permutation determines if a sequence is a permutation of another + \fI(C++11)\fP sequence + \fI(function template)\fP diff --git a/man/std::ranges::not_equal_to.3 b/man/std::ranges::not_equal_to.3 new file mode 100644 index 000000000..20953c4a7 --- /dev/null +++ b/man/std::ranges::not_equal_to.3 @@ -0,0 +1,53 @@ +.TH std::ranges::not_equal_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::not_equal_to \- std::ranges::not_equal_to + +.SH Synopsis + Defined in header + struct not_equal_to; \fI(since C++20)\fP + + Function object for performing comparisons. Deduces the parameter types of the + function call operator from the arguments (but not the return type). + +.SH Member functions + + operator() checks if the arguments are not equal + \fI(public member function)\fP + +std::ranges::not_equal_to::operator() + + template< class T, class U > + constexpr bool operator()( T&& t, U&& u ) const; + + Equivalent to return !ranges::equal_to{}(std::forward(t), std::forward(u));. + + This overload participates in overload resolution only if + std::equality_comparable_with is satisfied. + +.SH Notes + + Unlike std::not_equal_to, std::ranges::not_equal_to requires both == and != to be + valid (via the equality_comparable_with constraint), and is entirely defined in + terms of std::ranges::equal_to. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3530 C++20 syntactic checks were relaxed only semantic requirements are + while comparing pointers relaxed + +.SH See also + + not_equal_to function object implementing x != y + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::nth_element.3 b/man/std::ranges::nth_element.3 new file mode 100644 index 000000000..358a7739f --- /dev/null +++ b/man/std::ranges::nth_element.3 @@ -0,0 +1,147 @@ +.TH std::ranges::nth_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::nth_element \- std::ranges::nth_element + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + nth_element( I first, I nth, S last, Comp comp = {}, Proj proj + = {} ); + template< ranges::random_access_range R, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable, Comp, Proj> \fB(2)\fP \fI(since C++20)\fP + constexpr ranges::borrowed_iterator_t + + nth_element( R&& r, iterator_t nth, Comp comp = {}, Proj + proj = {} ); + + Reorders the elements in [first, last) such that: + + * The element pointed at by nth is changed to whatever element would occur in that + position if [first, last) were sorted with respect to comp and proj. + * All of the elements before this new nth element are less than or equal to the + elements after the new nth element. That is, for every iterator i, j in the + ranges [first, nth), [nth, last) respectively, the expression std::invoke(comp, + std::invoke(proj, *j), std::invoke(proj, *i)) evaluates to false. + * If nth == last then the function has no effect. + 1) Elements are compared using the given binary comparison function object comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to reorder + r - the range of elements to reorder + nth - the iterator defining the partition point + comp - comparator used to compare the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1) An iterator equal to last. + 2) Same as \fB(1)\fP if r is an lvalue or of a borrowed_range type. Otherwise returns + std::ranges::dangling. + +.SH Complexity + + Linear in ranges::distance(first, last) on average. + +.SH Notes + + The algorithm used is typically introselect although other selection algorithms with + suitable average-case complexity are allowed. + +.SH Possible implementation + + See also the implementation in msvc stl, libstdc++, and libc++: \fB(1)\fP / \fB(2)\fP. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(std::string_view rem, std::ranges::input_range auto const& a) + { + for (std::cout << rem; const auto e : a) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + std::array v{5, 6, 4, 3, 2, 6, 7, 9, 3}; + print("Before nth_element: ", v); + + std::ranges::nth_element(v, v.begin() + v.size() / 2); + print("After nth_element: ", v); + std::cout << "The median is: " << v[v.size() / 2] << '\\n'; + + std::ranges::nth_element(v, v.begin() + 1, std::greater()); + print("After nth_element: ", v); + std::cout << "The second largest element is: " << v[1] << '\\n'; + std::cout << "The largest element is: " << v[0] << "\\n\\n"; + + using namespace std::literals; + std::array names + { + "Diva"sv, "Cornelius"sv, "Munro"sv, "Rhod"sv, + "Zorg"sv, "Korben"sv, "Bender"sv, "Leeloo"sv, + }; + print("Before nth_element: ", names); + auto fifth_element{std::ranges::next(names.begin(), 4)}; + std::ranges::nth_element(names, fifth_element); + print("After nth_element: ", names); + std::cout << "The 5th element is: " << *fifth_element << '\\n'; + } + +.SH Output: + + Before nth_element: 5 6 4 3 2 6 7 9 3 + After nth_element: 2 3 3 4 5 6 6 7 9 + The median is: 5 + After nth_element: 9 7 6 6 5 4 3 3 2 + The second largest element is: 7 + The largest element is: 9 + + Before nth_element: Diva Cornelius Munro Rhod Zorg Korben Bender Leeloo + After nth_element: Diva Cornelius Bender Korben Leeloo Rhod Munro Zorg + The 5th element is: Leeloo + +.SH See also + + ranges::max_element returns the largest element in a range + (C++20) (niebloid) + ranges::min_element returns the smallest element in a range + (C++20) (niebloid) + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::partial_sort sorts the first N elements of a range + (C++20) (niebloid) + partially sorts the given range making sure that it is + nth_element partitioned by the given element + \fI(function template)\fP diff --git a/man/std::ranges::out_value_result.3 b/man/std::ranges::out_value_result.3 new file mode 100644 index 000000000..0eb43c3ba --- /dev/null +++ b/man/std::ranges::out_value_result.3 @@ -0,0 +1,130 @@ +.TH std::ranges::out_value_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::out_value_result \- std::ranges::out_value_result + +.SH Synopsis + Defined in header + template< class O, class T > (since C++23) + struct out_value_result; + + ranges::out_value_result is a class template that provides a way to store an + iterator and a value as a single unit. + + This class template has no base classes or declared members other than those shown + below. Thus it is suitable for use with structured bindings. + + All special member functions of this class template are implicitly declared, which + makes specializations be aggregate classes, and propagate triviality, + potentially-throwing-ness, and constexpr-ness of corresponding operations on data + members. + +.SH Template parameters + + O, T - the types of the objects that the ranges::out_value_result stores. + + Data members + + Member name Definition + out a value (that is supposed to be an iterator) of type O. + \fI(public member object)\fP + value a value (that is supposed to be a stored value) of type T. + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute. + +.SH Member functions + +std::ranges::out_value_result::operator out_value_result + + template + + requires convertible_to && convertible_to \fB(1)\fP + + constexpr operator out_value_result() const &; + template + + requires convertible_to && convertible_to \fB(2)\fP + + constexpr operator out_value_result() &&; + + Converts *this to the result by constructing every data member of the result from + the corresponding member of *this. + + 1) Equivalent to return {out, value};. + 2) Equivalent to return {std::move(out), std::move(value)};. + +.SH Standard library + + The following standard library functions use ranges::out_value_result as the return + type: + + Algorithm functions + ranges::iota fills a range with successive increments of the starting value + (C++23) (niebloid) + +.SH Synopsis + + namespace std::ranges + { + template + struct out_value_result + { + [[no_unique_address]] O out; + [[no_unique_address]] T value; + + template + requires convertible_to && convertible_to + constexpr operator out_value_result() const & + { + return {out, value}; + } + + template + requires convertible_to && convertible_to + constexpr operator out_value_result() && + { + return {std::move(out), std::move(value)}; + } + }; + } + +.SH Notes + + Each standard library algorithm that uses this family of return types declares a new + alias type, e.g. using merge_result = in_in_out_result;. + + The names for such aliases are formed by adding the suffix "_result" to the + algorithm's name. So, the return type of std::ranges::merge can be named as + std::ranges::merge_result. + + Unlike std::pair and std::tuple, this class template has data members of meaningful + names. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::array a{}; + constexpr std::array expected{2, 3, 4, 5}; + const auto result = std::ranges::iota(a, 2); + assert(std::ranges::distance(a.cbegin(), result.out) == 4); + assert(result.value == 6); + assert(a == expected); + } + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP + tuple implements fixed size container, which holds elements of possibly different + \fI(C++11)\fP types + \fI(class template)\fP diff --git a/man/std::ranges::output_range.3 b/man/std::ranges::output_range.3 new file mode 100644 index 000000000..3d629fb96 --- /dev/null +++ b/man/std::ranges::output_range.3 @@ -0,0 +1,15 @@ +.TH std::ranges::output_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::output_range \- std::ranges::output_range + +.SH Synopsis + Defined in header + template + + concept output_range = \fI(since C++20)\fP + + ranges::range && std::output_iterator, + T>; + + The output_range concept is a refinement of range for which ranges::begin returns a + model of output_iterator. diff --git a/man/std::ranges::owning_view.3 b/man/std::ranges::owning_view.3 new file mode 100644 index 000000000..c955c811d --- /dev/null +++ b/man/std::ranges::owning_view.3 @@ -0,0 +1,203 @@ +.TH std::ranges::owning_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::owning_view \- std::ranges::owning_view + +.SH Synopsis + Defined in header + template< ranges::range R > + + requires std::movable && (!/*is-initializer-list*/) \fI(since C++20)\fP + class owning_view + + : public ranges::view_interface> + + owning_view is a view that has unique ownership of a range. It is move-only and + stores that range within it. + + The constant /*is-initializer-list*/ in the requires-clause is true if and only + if std::remove_cvref_t is a specialization of std::initializer_list. + +.SH Member functions + + constructor constructs an owning_view by value-initializing or move-constructing + (C++20) the stored range + \fI(public member function)\fP + operator= move-assigns the stored range + (C++20) \fI(public member function)\fP + base returns a reference to the stored range + (C++20) \fI(public member function)\fP + begin returns the beginning iterator of the stored range + (C++20) \fI(public member function)\fP + end returns the sentinel of the stored range + (C++20) \fI(public member function)\fP + empty checks whether the stored range is empty + (C++20) \fI(public member function)\fP + size returns the size of the stored sized_range + (C++20) \fI(public member function)\fP + data returns the pointer to the beginning of the stored contiguous_range + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::owning_view::owning_view + + owning_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + owning_view( owning_view&& other ) = default; \fB(2)\fP \fI(since C++20)\fP + constexpr owning_view( R&& t ); \fB(3)\fP \fI(since C++20)\fP + owning_view( const owning_view& ) = delete; \fB(4)\fP \fI(since C++20)\fP + + 1) Default constructor. Value-initializes the stored range by its default member + initializer (= R()). + 2) Move constructor. Move constructs the stored range from that of other. + 3) Move constructs the stored range from t. + 4) Copy constructor is deleted. owning_view is move-only. + +.SH Parameters + + other - another owning_view to move from + t - range to move from + +std::ranges::owning_view::operator= + + owning_view& operator=( owning_view&& other ) = default; \fB(1)\fP \fI(since C++20)\fP + owning_view& operator=( const owning_view& ) = delete; \fB(2)\fP \fI(since C++20)\fP + + 1) Move assignment operator. Move assigns the stored range from that of other. + 2) Copy assignment operator is deleted. owning_view is move-only. + +.SH Parameters + + other - another owning_view to move from + +.SH Return value + + *this + +std::ranges::owning_view::base + + constexpr R& base() & noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr const R& base() const & noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr R&& base() && noexcept; \fB(3)\fP \fI(since C++20)\fP + constexpr const R&& base() const && noexcept; \fB(4)\fP \fI(since C++20)\fP + + Returns a reference to the stored range, keeping value category and + const-qualification. + + 1,2) Equivalent to return r_;. + 3,4) Equivalent to return std::move(r_);. + +std::ranges::owning_view::begin + + constexpr ranges::iterator_t begin(); \fB(1)\fP \fI(since C++20)\fP + constexpr auto begin() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + Equivalent to return ranges::begin(r_);. + +std::ranges::owning_view::end + + constexpr ranges::sentinel_t end(); \fB(1)\fP \fI(since C++20)\fP + constexpr auto end() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + Equivalent to return ranges::end(r_);. + +std::ranges::owning_view::empty + + constexpr bool empty() requires requires { ranges::empty(r_); }; \fB(1)\fP \fI(since C++20)\fP + constexpr bool empty() const requires requires { \fB(2)\fP \fI(since C++20)\fP + ranges::empty(r_); }; + + Equivalent to return ranges::empty(r_);. + +std::ranges::owning_view::size + + constexpr auto size() requires ranges::sized_range; \fB(1)\fP \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP \fI(since C++20)\fP + + Equivalent to return ranges::size(r_);. + +std::ranges::owning_view::data + + constexpr auto data() requires ranges::contiguous_range; \fB(1)\fP \fI(since C++20)\fP + constexpr auto data() const requires \fB(2)\fP \fI(since C++20)\fP + ranges::contiguous_range; + + Equivalent to return ranges::data(r_);. + + Helper templates + + template< class T > + + inline constexpr bool \fI(since C++20)\fP + enable_borrowed_range> = + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes owning_view satisfy + borrowed_range when the underlying range satisfies it. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + std::ranges::owning_view ov{"cosmos"s}; // the deduced type of R is std::string; + // `ov` is the only owner of this string + assert( + ov.empty() == false && + ov.size() == 6 && + ov.size() == ov.base().size() && + ov.front() == 'c' && + ov.front() == *ov.begin() && + ov.back() == 's' && + ov.back() == *(ov.end() - 1) && + ov.data() == ov.base() + ); + + std::cout << "sizeof(ov): " << sizeof ov << '\\n' // typically equal to sizeof(R) + << "range-for: "; + for (const char ch : ov) + std::cout << ch; + std::cout << '\\n'; + + std::ranges::owning_view ov2; + assert(ov2.empty()); + // ov2 = ov; // compile-time error: copy assignment operator is deleted + ov2 = std::move(ov); // OK + assert(ov2.size() == 6); + } + +.SH Possible output: + + sizeof(ov): 32 + range-for: cosmos + +.SH See also + + ranges::ref_view a view of the elements of some other range + (C++20) \fI(class template)\fP + views::all_t a view that includes all elements of a range + views::all (alias template) (range adaptor object) + (C++20) diff --git a/man/std::ranges::partial_sort.3 b/man/std::ranges::partial_sort.3 new file mode 100644 index 000000000..c555c8b6a --- /dev/null +++ b/man/std::ranges::partial_sort.3 @@ -0,0 +1,175 @@ +.TH std::ranges::partial_sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::partial_sort \- std::ranges::partial_sort + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + partial_sort( I first, I middle, S last, Comp comp = {}, Proj + proj = {} ); + template< ranges::random_access_range R, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t \fB(2)\fP \fI(since C++20)\fP + partial_sort( R&& r, ranges::iterator_t middle, Comp comp = + {}, + + Proj proj = {} ); + + 1) Rearranges elements such that the range [first, middle) contains the sorted + middle - first smallest elements in the range [first, last). + The order of equal elements is not guaranteed to be preserved. The order of the + remaining elements in the range [middle, last) is unspecified. + The elements are compared using the given binary comparison function comp and + projected using proj function object. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the range to sort + r - the range to sort + middle - the iterator defining the last element to be sorted + comp - comparator to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(M)})\\)𝓞(N·log(M)) comparisons and twice as + many projections, where \\(\\scriptsize N\\)N is ranges::distance(first, last), + \\(\\scriptsize M\\)M is ranges::distance(first, middle). + +.SH Possible implementation + +struct partial_sort_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr I + operator()(I first, I middle, S last, Comp comp = {}, Proj proj = {}) const + { + if (first == middle) + return ranges::next(first, last); + ranges::make_heap(first, middle, comp, proj); + auto it {middle}; + for (; it != last; ++it) + { + if (std::invoke(comp, std::invoke(proj, *it), std::invoke(proj, *first))) + { + ranges::pop_heap(first, middle, comp, proj); + ranges::iter_swap(middle - 1, it); + ranges::push_heap(first, middle, comp, proj); + } + } + ranges::sort_heap(first, middle, comp, proj); + return it; + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, ranges::iterator_t middle, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), std::move(middle), ranges::end(r), + std::move(comp), std::move(proj)); + } +}; + +inline constexpr partial_sort_fn partial_sort {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(const auto& v) + { + for (const char e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + void underscore(int n) + { + while (n-- > 0) + std::cout << "^ "; + std::cout << '\\n'; + } + + int main() + { + static_assert('A' < 'a'); + std::vector v {'x', 'P', 'y', 'C', 'z', 'w', 'P', 'o'}; + print(v); + const int m {3}; + std::ranges::partial_sort(v, v.begin() + m); + print(v), underscore(m); + + static_assert('1' < 'a'); + std::string s {"3a1b41c5"}; + print(s); + std::ranges::partial_sort(s.begin(), s.begin() + m, s.end(), std::greater {}); + print(s), underscore(m); + } + +.SH Output: + + x P y C z w P o + C P P y z x w o + ^ ^ ^ + 3 a 1 b 4 1 c 5 + c b a 1 3 1 4 5 + ^ ^ ^ + +.SH See also + + ranges::partial_sort_copy copies and partially sorts a range of elements + (C++20) (niebloid) + ranges::sort sorts a range into ascending order + (C++20) (niebloid) + ranges::stable_sort sorts a range of elements while preserving order between + (C++20) equal elements + (niebloid) + ranges::nth_element partially sorts the given range making sure that it is + (C++20) partitioned by the given element + (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in + (C++20) ascending order + (niebloid) + partial_sort sorts the first N elements of a range + \fI(function template)\fP diff --git a/man/std::ranges::partial_sort_copy,std::ranges::partial_sort_copy_result.3 b/man/std::ranges::partial_sort_copy,std::ranges::partial_sort_copy_result.3 new file mode 100644 index 000000000..8d0cfc66d --- /dev/null +++ b/man/std::ranges::partial_sort_copy,std::ranges::partial_sort_copy_result.3 @@ -0,0 +1,225 @@ +.TH std::ranges::partial_sort_copy,std::ranges::partial_sort_copy_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::partial_sort_copy,std::ranges::partial_sort_copy_result \- std::ranges::partial_sort_copy,std::ranges::partial_sort_copy_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::random_access_iterator I2, std::sentinel_for S2, + class Comp = ranges::less, class Proj1 = std::identity, + class Proj2 = std::identity > + requires std::indirectly_copyable && + std::sortable && + std::indirect_strict_weak_order, C++20) + std::projected> + constexpr partial_sort_copy_result + partial_sort_copy( I1 first, S1 last, I2 result_first, S2 + result_last, + + Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = + {} ); + template< ranges::input_range R1, ranges::random_access_range R2, + + class Comp = ranges::less, class Proj1 = std::identity, + class Proj2 = std::identity > + requires std::indirectly_copyable, + ranges::iterator_t> && + std::sortable, Comp, Proj2> && + std::indirect_strict_weak_order, C++20) + Proj1>, std::projected, Proj2>> + constexpr partial_sort_copy_result, + ranges::borrowed_iterator_t> + partial_sort_copy( R1&& r, R2&& result_r, + + Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = + {} ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using partial_sort_copy_result = ranges::in_out_result; C++20) + + Copies the first N elements from the source range [first, last), as if it was + partially sorted with respect to comp and proj1, into the destination range + [result_first, result_first + N), where \\(\\scriptsize N = \\min{(L_1, L_2)}\\)N = + min(L₁, L₂), \\(\\scriptsize L_1\\)L₁ is equal to ranges::distance(first, last), and + \\(\\scriptsize L_2\\)L₂ is equal to ranges::distance(result_first, result_last). + + The order of equal elements is not guaranteed to be preserved. + + 1) The source range elements are projected using the function object proj1, and the + destination elements are projected using the function object proj2. + 2) Same as \fB(1)\fP, but uses r as the source range and result_r as the destination + range, as if using ranges::begin(r) as first, ranges::end(r) as last, + ranges::begin(result_r) as result_first, and ranges::end(result_r) as result_last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the source range to copy from + r - the source range to copy from + result_first, result_last - iterator-sentinel defining the destination range + result_r - the destination range + comp - comparison to apply to the projected elements + proj1 - projection to apply to the elements of source range + proj2 - projection to apply to the elements of destination range + +.SH Return value + + An object equal to {last, result_first + N}. + +.SH Complexity + + At most \\(\\scriptsize L_1 \\cdot \\log{(N)}\\)L₁*log(N) comparisons and \\(\\scriptsize 2 + \\cdot L_1 \\cdot \\log{(N)}\\)2*L₁*log(N) projections. + +.SH Possible implementation + + struct partial_sort_copy_fn + { + template S1, + std::random_access_iterator I2, std::sentinel_for S2, + class Comp = ranges::less, class Proj1 = std::identity, + class Proj2 = std::identity> + requires std::indirectly_copyable && std::sortable && + std::indirect_strict_weak_order, + std::projected> + constexpr ranges::partial_sort_copy_result + operator()(I1 first, S1 last, I2 result_first, S2 result_last, + Comp comp = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + if (result_first == result_last) + return {std::move(ranges::next(std::move(first), std::move(last))), + std::move(result_first)}; + + auto out_last{result_first}; + // copy first N elements + for (; !(first == last or out_last == result_last); ++out_last, ++first) + *out_last = *first; + + // convert N copied elements into a max-heap + ranges::make_heap(result_first, out_last, comp, proj2); + + // process the rest of the input range (if any), preserving the heap property + for (; first != last; ++first) + { + if (std::invoke(comp, std::invoke(proj1, *first), + std::invoke(proj2, *result_first))) + { + // pop out the biggest item and push in a newly found smaller one + ranges::pop_heap(result_first, out_last, comp, proj2); + *(out_last - 1) = *first; + ranges::push_heap(result_first, out_last, comp, proj2); + } + } + + // first N elements in the output range is still + // a heap - convert it into a sorted range + ranges::sort_heap(result_first, out_last, comp, proj2); + + return {std::move(first), std::move(out_last)}; + } + + template + requires std::indirectly_copyable, ranges::iterator_t> && + std::sortable, Comp, Proj2> && + std::indirect_strict_weak_order, + Proj1>, std::projected, Proj2>> + constexpr ranges::partial_sort_copy_result, + ranges::borrowed_iterator_t> + operator()(R1&& r, R2&& result_r, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + ranges::begin(result_r), ranges::end(result_r), + std::move(comp), std::move(proj1), std::move(proj2)); + } + }; + + inline constexpr partial_sort_copy_fn partial_sort_copy {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(std::string_view rem, std::ranges::input_range auto const& v) + { + for (std::cout << rem; const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + const std::forward_list source{4, 2, 5, 1, 3}; + + print("Write to the smaller vector in ascending order: ", ""); + + std::vector dest1{10, 11, 12}; + print("const source list: ", source); + print("destination range: ", dest1); + std::ranges::partial_sort_copy(source, dest1); + print("partial_sort_copy: ", dest1); + + print("Write to the larger vector in descending order:", ""); + + std::vector dest2{10, 11, 12, 13, 14, 15, 16}; + print("const source list: ", source); + print("destination range: ", dest2); + std::ranges::partial_sort_copy(source, dest2, std::greater{}); + print("partial_sort_copy: ", dest2); + } + +.SH Output: + + Write to the smaller vector in ascending order: + const source list: 4 2 5 1 3 + destination range: 10 11 12 + partial_sort_copy: 1 2 3 + Write to the larger vector in descending order: + const source list: 4 2 5 1 3 + destination range: 10 11 12 13 14 15 16 + partial_sort_copy: 5 4 3 2 1 15 16 + +.SH See also + + ranges::partial_sort sorts the first N elements of a range + (C++20) (niebloid) + ranges::sort sorts a range into ascending order + (C++20) (niebloid) + ranges::stable_sort sorts a range of elements while preserving order between equal + (C++20) elements + (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + partial_sort_copy copies and partially sorts a range of elements + \fI(function template)\fP diff --git a/man/std::ranges::partition.3 b/man/std::ranges::partition.3 new file mode 100644 index 000000000..4c701a9b6 --- /dev/null +++ b/man/std::ranges::partition.3 @@ -0,0 +1,181 @@ +.TH std::ranges::partition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::partition \- std::ranges::partition + +.SH Synopsis + Defined in header + Call signature + template< std::permutable I, std::sentinel_for S, class Proj = + std::identity, + + std::indirect_unary_predicate> \fB(1)\fP \fI(since C++20)\fP + Pred > + constexpr ranges::subrange + + partition( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + std::indirect_unary_predicate< + std::projected, Proj>> Pred > \fB(2)\fP \fI(since C++20)\fP + requires std::permutable> + constexpr ranges::borrowed_subrange_t + + partition( R&& r, Pred pred, Proj proj = {} ); + + 1) Reorders the elements in the range [first, last) in such a way that the + projection proj of all elements for which the predicate pred returns true precede + the projection proj of elements for which predicate pred returns false. Relative + order of elements is not preserved. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to reorder + r - the range of elements to reorder + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + A subrange starting with an iterator to the first element of the second group and + finishing with an iterator equal to last. \fB(2)\fP returns std::ranges::dangling if r is + an rvalue of non-borrowed_range type. + +.SH Complexity + + Given N = ranges::distance(first, last), exactly N applications of the predicate and + projection. At most N / 2 swaps if I models ranges::bidirectional_iterator, and at + most N swaps otherwise. + +.SH Possible implementation + + struct partition_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr ranges::subrange + operator()(I first, S last, Pred pred, Proj proj = {}) const + { + first = ranges::find_if_not(first, last, std::ref(pred), std::ref(proj)); + if (first == last) + return {first, first}; + + for (auto i = ranges::next(first); i != last; ++i) + { + if (std::invoke(pred, std::invoke(proj, *i))) + { + ranges::iter_swap(i, first); + ++first; + } + } + return {std::move(first), std::move(last)}; + } + + template, Proj>> Pred> + requires std::permutable> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::ref(pred), std::ref(proj)); + } + }; + + inline constexpr partition_fn partition; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + namespace ranges = std::ranges; + + template S, class Cmp = ranges::less> + requires std::sortable + void quicksort(I first, S last, Cmp cmp = Cmp {}) + { + using reference = std::iter_reference_t; + + if (first == last) + return; + + auto size = ranges::distance(first, last); + auto pivot = ranges::next(first, size - 1); + ranges::iter_swap(pivot, ranges::next(first, size / 2)); + + auto tail = ranges::partition(first, pivot, [=](reference em) + { + return std::invoke(cmp, em, *pivot); // em < pivot + }); + + ranges::iter_swap(pivot, tail.begin()); + quicksort(first, tail.begin(), std::ref(cmp)); + quicksort(ranges::next(tail.begin()), last, std::ref(cmp)); + } + + int main() + { + std::ostream_iterator cout {std::cout, " "}; + + std::vector v {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + std::cout << "Original vector: \\t"; + ranges::copy(v, cout); + + auto tail = ranges::partition(v, [](int i) { return i % 2 == 0; }); + + std::cout << "\\nPartitioned vector: \\t"; + ranges::copy(ranges::begin(v), ranges::begin(tail), cout); + std::cout << "│ "; + ranges::copy(tail, cout); + + std::forward_list fl {1, 30, -4, 3, 5, -4, 1, 6, -8, 2, -5, 64, 1, 92}; + std::cout << "\\nUnsorted list: \\t\\t"; + ranges::copy(fl, cout); + + quicksort(ranges::begin(fl), ranges::end(fl), ranges::greater {}); + std::cout << "\\nQuick-sorted list: \\t"; + ranges::copy(fl, cout); + + std::cout << '\\n'; + } + +.SH Possible output: + + Original vector: 0 1 2 3 4 5 6 7 8 9 + Partitioned vector: 0 8 2 6 4 │ 5 3 7 1 9 + Unsorted list: 1 30 -4 3 5 -4 1 6 -8 2 -5 64 1 92 + Quick-sorted list: 92 64 30 6 5 3 2 1 1 1 -4 -4 -5 -8 + +.SH See also + + ranges::partition_copy copies a range dividing the elements into two groups + (C++20) (niebloid) + ranges::is_partitioned determines if the range is partitioned by the given + (C++20) predicate + (niebloid) + ranges::stable_partition divides elements into two groups while preserving their + (C++20) relative order + (niebloid) + partition divides a range of elements into two groups + \fI(function template)\fP diff --git a/man/std::ranges::partition_copy,std::ranges::partition_copy_result.3 b/man/std::ranges::partition_copy,std::ranges::partition_copy_result.3 new file mode 100644 index 000000000..9c79bf980 --- /dev/null +++ b/man/std::ranges::partition_copy,std::ranges::partition_copy_result.3 @@ -0,0 +1,164 @@ +.TH std::ranges::partition_copy,std::ranges::partition_copy_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::partition_copy,std::ranges::partition_copy_result \- std::ranges::partition_copy,std::ranges::partition_copy_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + std::weakly_incrementable O1, std::weakly_incrementable O2, + class Proj = std::identity, + std::indirect_unary_predicate> Pred > (since + requires std::indirectly_copyable && \fB(1)\fP C++20) + std::indirectly_copyable + constexpr partition_copy_result + partition_copy( I first, S last, O1 out_true, O2 out_false, + + Pred pred, Proj proj = {} ); + template< ranges::input_range R, + + std::weakly_incrementable O1, std::weakly_incrementable O2, + class Proj = std::identity, + std::indirect_unary_predicate, + Proj>> Pred > \fB(2)\fP (since + requires std::indirectly_copyable, O1> && C++20) + std::indirectly_copyable, O2> + constexpr partition_copy_result, O1, O2> + partition_copy( R&& r, O1 out_true, O2 out_false, + + Pred pred, Proj proj = {} ); +.SH Helper types + template< class I, class O1, class O2 > \fB(3)\fP (since + using partition_copy_result = ranges::in_out_out_result; C++20) + + 1) Copies the elements from the input range [first, last) to two different output + ranges depending on the value returned by the predicate pred. The elements that + satisfy the predicate pred after projection by proj are copied to the range + beginning at out_true. The rest of the elements are copied to the range beginning at + out_false. The behavior is undefined if the input range overlaps either of the + output ranges. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the input range of elements to copy from + r - the input range of elements to copy from + out_true - the beginning of the output range for the elements that satisfy pred + out_false - the beginning of the output range for the elements that do not satisfy + pred + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + {last, o1, o2}, where o1 and o2 are the ends of the output ranges respectively, + after the copying is complete. + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the corresponding predicate + comp and any projection proj. + +.SH Possible implementation + + struct partition_copy_fn + { + template S, + std::weakly_incrementable O1, std::weakly_incrementable O2, + class Proj = std::identity, std::indirect_unary_predicate< + std::projected> Pred> + requires std::indirectly_copyable && std::indirectly_copyable + constexpr ranges::partition_copy_result + operator()(I first, S last, O1 out_true, O2 out_false, + Pred pred, Proj proj = {}) const + { + for (; first != last; ++first) + if (!!std::invoke(pred, std::invoke(proj, *first))) + *out_true = *first, ++out_true; + else + *out_false = *first, ++out_false; + return {std::move(first), std::move(out_true), std::move(out_false)}; + } + + template, Proj>> Pred> + requires std::indirectly_copyable, O1> && + std::indirectly_copyable, O2> + constexpr ranges::partition_copy_result, O1, O2> + operator()(R&& r, O1 out_true, O2 out_false, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(out_true), + std::move(out_false), std::move(pred), std::move(proj)); + } + }; + + inline constexpr partition_copy_fn partition_copy {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + const auto in = {'N', '3', 'U', 'M', '1', 'B', '4', 'E', '1', '5', 'R', '9'}; + + std::vector o1(size(in)), o2(size(in)); + + auto pred = [](char c) { return std::isalpha(c); }; + + auto ret = std::ranges::partition_copy(in, o1.begin(), o2.begin(), pred); + + std::ostream_iterator cout {std::cout, " "}; + std::cout << "in = "; + std::ranges::copy(in, cout); + std::cout << "\\no1 = "; + std::copy(o1.begin(), ret.out1, cout); + std::cout << "\\no2 = "; + std::copy(o2.begin(), ret.out2, cout); + std::cout << '\\n'; + } + +.SH Output: + + in = N 3 U M 1 B 4 E 1 5 R 9 + o1 = N U M B E R + o2 = 3 1 4 1 5 9 + +.SH See also + + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::stable_partition divides elements into two groups while preserving their + (C++20) relative order + (niebloid) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) + partition_copy copies a range dividing the elements into two groups + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::partition_point.3 b/man/std::ranges::partition_point.3 new file mode 100644 index 000000000..10a045b71 --- /dev/null +++ b/man/std::ranges::partition_point.3 @@ -0,0 +1,113 @@ +.TH std::ranges::partition_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::partition_point \- std::ranges::partition_point + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> \fB(1)\fP \fI(since C++20)\fP + Pred > + constexpr I + + partition_point( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::forward_range R, + + class Proj = std::identity, + std::indirect_unary_predicate< \fB(2)\fP \fI(since C++20)\fP + std::projected, Proj>> Pred > + constexpr ranges::borrowed_iterator_t + + partition_point( R&& r, Pred pred, Proj proj = {} ); + + Examines the partitioned (as if by ranges::partition) range [first, last) or r and + locates the end of the first partition, that is, the projected element that does not + satisfy pred or last if all projected elements satisfy pred. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the partially-ordered range to examine + r - the partially-ordered range to examine + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + The iterator past the end of the first partition within [first, last) or the + iterator equal to last if all projected elements satisfy pred. + +.SH Complexity + + Given N = ranges::distance(first, last), performs O(log N) applications of the + predicate pred and projection proj. + + However, if sentinels don't model std::sized_sentinel_for, the number of iterator + increments is O(N). + +.SH Notes + + This algorithm is a more general form of ranges::lower_bound, which can be expressed + in terms of ranges::partition_point with the predicate [&](auto const& e) { return + std::invoke(pred, e, value); });. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + auto print_seq = [](auto rem, auto first, auto last) + { + for (std::cout << rem; first != last; std::cout << *first++ << ' ') {} + std::cout << '\\n'; + }; + + int main() + { + std::array v {1, 2, 3, 4, 5, 6, 7, 8, 9}; + + auto is_even = [](int i) { return i % 2 == 0; }; + + std::ranges::partition(v, is_even); + print_seq("After partitioning, v: ", v.cbegin(), v.cend()); + + const auto pp = std::ranges::partition_point(v, is_even); + const auto i = std::ranges::distance(v.cbegin(), pp); + std::cout << "Partition point is at " << i << "; v[" << i << "] = " << *pp << '\\n'; + + print_seq("First partition (all even elements): ", v.cbegin(), pp); + print_seq("Second partition (all odd elements): ", pp, v.cend()); + } + +.SH Possible output: + + After partitioning, v: 2 4 6 8 5 3 7 1 9 + Partition point is at 4; v[4] = 5 + First partition (all even elements): 2 4 6 8 + Second partition (all odd elements): 5 3 7 1 9 + +.SH See also + + ranges::is_sorted checks whether a range is sorted into ascending order + (C++20) (niebloid) + ranges::lower_bound returns an iterator to the first element not less than the given + (C++20) value + (niebloid) + partition_point locates the partition point of a partitioned range + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::pop_heap.3 b/man/std::ranges::pop_heap.3 new file mode 100644 index 000000000..143288829 --- /dev/null +++ b/man/std::ranges::pop_heap.3 @@ -0,0 +1,140 @@ +.TH std::ranges::pop_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::pop_heap \- std::ranges::pop_heap + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + pop_heap( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Comp = + ranges::less, + + class Proj = std::identity > \fB(2)\fP \fI(since C++20)\fP + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + + pop_heap( R&& r, Comp comp = {}, Proj proj = {} ); + + Swaps the value in the position first and the value in the position last - 1 and + makes the subrange [first, last - 1) into a max heap. This has the effect of + removing the first element from the heap defined by the range [first, last). + + 1) Elements are compared using the given binary comparison function comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements defining the valid nonempty heap to modify + r - the range of elements defining the valid nonempty heap to modify + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Given N = ranges::distance(first, last), at most \\(\\scriptsize 2\\log{(N)}\\)2log(N) + comparisons and \\(\\scriptsize 4\\log{(N)}\\)4log(N) projections. + +.SH Notes + + A max heap is a range of elements [f, l), arranged with respect to comparator comp + and projection proj, that has the following properties: + + * With N = l - f, p = f[(i - 1) / 2], and q = f[i], for all 0 < i < N, the + expression std::invoke(comp, std::invoke(proj, p), std::invoke(proj, q)) + evaluates to false. + * A new element can be added using ranges::push_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + * The first element can be removed using ranges::pop_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void print(std::string_view rem, I first = {}, I last = {}, + std::string_view term = "\\n") + { + for (std::cout << rem; first != last; ++first) + std::cout << *first << ' '; + std::cout << term; + } + + int main() + { + std::array v {3, 1, 4, 1, 5, 9, 2, 6, 5, 3}; + print("initially, v: ", v.cbegin(), v.cend()); + + std::ranges::make_heap(v); + print("make_heap, v: ", v.cbegin(), v.cend()); + + print("convert heap into sorted array:"); + for (auto n {std::ssize(v)}; n >= 0; --n) + { + std::ranges::pop_heap(v.begin(), v.begin() + n); + print("[ ", v.cbegin(), v.cbegin() + n, "] "); + print("[ ", v.cbegin() + n, v.cend(), "]\\n"); + } + } + +.SH Output: + + initially, v: 3 1 4 1 5 9 2 6 5 3 + make_heap, v: 9 6 4 5 5 3 2 1 1 3 + convert heap into sorted array: + [ 6 5 4 3 5 3 2 1 1 9 ] [ ] + [ 5 5 4 3 1 3 2 1 6 ] [ 9 ] + [ 5 3 4 1 1 3 2 5 ] [ 6 9 ] + [ 4 3 3 1 1 2 5 ] [ 5 6 9 ] + [ 3 2 3 1 1 4 ] [ 5 5 6 9 ] + [ 3 2 1 1 3 ] [ 4 5 5 6 9 ] + [ 2 1 1 3 ] [ 3 4 5 5 6 9 ] + [ 1 1 2 ] [ 3 3 4 5 5 6 9 ] + [ 1 1 ] [ 2 3 3 4 5 5 6 9 ] + [ 1 ] [ 1 2 3 3 4 5 5 6 9 ] + [ ] [ 1 1 2 3 3 4 5 5 6 9 ] + +.SH See also + + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::is_heap checks if the given range is a max heap + (C++20) (niebloid) + ranges::is_heap_until finds the largest subrange that is a max heap + (C++20) (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) + pop_heap removes the largest element from a max heap + \fI(function template)\fP diff --git a/man/std::ranges::prev.3 b/man/std::ranges::prev.3 new file mode 100644 index 000000000..17f7d5e66 --- /dev/null +++ b/man/std::ranges::prev.3 @@ -0,0 +1,117 @@ +.TH std::ranges::prev 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::prev \- std::ranges::prev + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I > \fB(1)\fP \fI(since C++20)\fP + constexpr I prev( I i ); + template< std::bidirectional_iterator I > \fB(2)\fP \fI(since C++20)\fP + constexpr I prev( I i, std::iter_difference_t n ); + template< std::bidirectional_iterator I > \fB(3)\fP \fI(since C++20)\fP + constexpr I prev( I i, std::iter_difference_t n, I bound ); + + Return the n^th predecessor of iterator i. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + i - an iterator + n - number of elements i should be descended + bound - iterator denoting the beginning of the range i points to + +.SH Return value + + 1) The predecessor of i. + 2) The n^th predecessor of iterator i. + 3) The n^th predecessor of iterator i, or the first iterator that compares equal to + bound, whichever is first. + +.SH Complexity + + 1) Constant. + 2,3) Constant if I models std::random_access_iterator; otherwise linear. + +.SH Possible implementation + + struct prev_fn + { + template + constexpr I operator()(I i) const + { + --i; + return i; + } + + template + constexpr I operator()(I i, std::iter_difference_t n) const + { + ranges::advance(i, -n); + return i; + } + + template + constexpr I operator()(I i, std::iter_difference_t n, I bound) const + { + ranges::advance(i, -n, bound); + return i; + } + }; + + inline constexpr auto prev = prev_fn(); + +.SH Notes + + Although the expression --r.end() often compiles for containers, it is not + guaranteed to do so: r.end() is an rvalue expression, and there is no iterator + requirement that specifies that decrement of an rvalue is guaranteed to work. In + particular, when iterators are implemented as pointers or its operator-- is + lvalue-ref-qualified, --r.end() does not compile, while ranges::prev(r.end()) does. + + This is further exacerbated by ranges that do not model ranges::common_range. For + example, for some underlying ranges, ranges::transform_view::end doesn't have the + same return type as ranges::transform_view::begin, and so --r.end() won't compile. + This isn't something that ranges::prev can aid with, but there are workarounds. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v{3, 1, 4}; + auto pv = std::ranges::prev(v.end(), 2); + std::cout << *pv << '\\n'; + + pv = std::ranges::prev(pv, 42, v.begin()); + std::cout << *pv << '\\n'; + } + +.SH Output: + + 1 + 3 + +.SH See also + + ranges::next increment an iterator by a given distance or to a bound + (C++20) (niebloid) + ranges::advance advances an iterator by given distance or to a given bound + (C++20) (niebloid) + prev decrement an iterator + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::ranges::prev_permutation,std::ranges::prev_permutation_result.3 b/man/std::ranges::prev_permutation,std::ranges::prev_permutation_result.3 new file mode 100644 index 000000000..149a2c650 --- /dev/null +++ b/man/std::ranges::prev_permutation,std::ranges::prev_permutation_result.3 @@ -0,0 +1,227 @@ +.TH std::ranges::prev_permutation,std::ranges::prev_permutation_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::prev_permutation,std::ranges::prev_permutation_result \- std::ranges::prev_permutation,std::ranges::prev_permutation_result + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > (since + requires std::sortable \fB(1)\fP C++20) + constexpr prev_permutation_result + + prev_permutation( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::bidirectional_range R, class Comp = ranges::less, + + class Proj = std::identity > (since + requires std::sortable, Comp, Proj> \fB(2)\fP C++20) + constexpr prev_permutation_result> + + prev_permutation( R&& r, Comp comp = {}, Proj proj = {} ); + Helper type + template< class I > \fB(3)\fP (since + using prev_permutation_result = ranges::in_found_result; C++20) + + 1) Transforms the range [first, last) into the previous permutation, where the set + of all permutations is ordered lexicographically with respect to binary comparison + function object comp and projection function object proj. + Returns: + * {last, true} if "previous" permutation exists. Otherwise, + * {last, false}, and transforms the range into the (lexicographically) last + permutation, as if by + + ranges::sort(first, last, comp, proj); + ranges::reverse(first, last); + + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to "permute" + r - the range of elements to "permute" + comp - comparison function object which returns true if the first argument is + less than the second + proj - projection to apply to the elements + +.SH Return value + + 1) ranges::prev_permutation_result{last, true} if the new permutation is + lexicographically less than the old one. ranges::prev_permutation_result{last, + false} if the first permutation was reached and the range was reset to the last + permutation. + 2) Same as \fB(1)\fP except that the return type is + ranges::prev_permutation_result>. + +.SH Exceptions + + Any exceptions thrown from iterator operations or the element swap. + +.SH Complexity + + At most \\(\\scriptsize N/2\\)N / 2 swaps, where \\(\\scriptsize N\\)N is + ranges::distance(first, last) in case \fB(1)\fP or ranges::distance(r) in case \fB(2)\fP. + Averaged over the entire sequence of permutations, typical implementations use about + 3 comparisons and 1.5 swaps per call. + +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + models contiguous_iterator and swapping its value type calls neither non-trivial + special member function nor ADL-found swap. + +.SH Possible implementation + +struct prev_permutation_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr ranges::prev_permutation_result + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + // check that the sequence has at least two elements + if (first == last) + return {std::move(first), false}; + auto i{first}; + ++i; + if (i == last) + return {std::move(i), false}; + auto i_last{ranges::next(first, last)}; + i = i_last; + --i; + // main "permutating" loop + for (;;) + { + auto i1{i}; + --i; + if (std::invoke(comp, std::invoke(proj, *i1), std::invoke(proj, *i))) + { + auto j{i_last}; + while (!std::invoke(comp, std::invoke(proj, *--j), std::invoke(proj, *i))) + ; + ranges::iter_swap(i, j); + ranges::reverse(i1, last); + return {std::move(i_last), true}; + } + // permutation "space" is exhausted + if (i == first) + { + ranges::reverse(first, last); + return {std::move(i_last), false}; + } + } + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::prev_permutation_result> + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::move(comp), std::move(proj)); + } +}; + +inline constexpr prev_permutation_fn prev_permutation {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + struct S + { + char c{}; + int i{}; + auto operator<=>(const S&) const = default; + friend std::ostream& operator<<(std::ostream& os, const S& s) + { + return os << "{'" << s.c << "', " << s.i << "}"; + } + }; + + auto print = [](auto const& v, char term = ' ') + { + std::cout << "{ "; + for (const auto& e : v) + std::cout << e << ' '; + std::cout << '}' << term; + }; + + int main() + { + std::cout << "Generate all permutations (iterators case):\\n"; + std::string s{"cba"}; + do print(s); + while (std::ranges::prev_permutation(s.begin(), s.end()).found); + + std::cout << "\\nGenerate all permutations (range case):\\n"; + std::array a{'c', 'b', 'a'}; + do print(a); + while (std::ranges::prev_permutation(a).found); + + std::cout << "\\nGenerate all permutations using comparator:\\n"; + using namespace std::literals; + std::array z{"▁"s, "▄"s, "█"s}; + do print(z); + while (std::ranges::prev_permutation(z, std::greater()).found); + + std::cout << "\\nGenerate all permutations using projection:\\n"; + std::array r{S{'C',1}, S{'B',2}, S{'A',3}}; + do print(r, '\\n'); + while (std::ranges::prev_permutation(r, {}, &S::c).found); + } + +.SH Output: + + Generate all permutations (iterators case): + { c b a } { c a b } { b c a } { b a c } { a c b } { a b c } + Generate all permutations (range case): + { c b a } { c a b } { b c a } { b a c } { a c b } { a b c } + Generate all permutations using comparator: + { ▁ ▄ █ } { ▁ █ ▄ } { ▄ ▁ █ } { ▄ █ ▁ } { █ ▁ ▄ } { █ ▄ ▁ } + Generate all permutations using projection: + { {'C', 1} {'B', 2} {'A', 3} } + { {'C', 1} {'A', 3} {'B', 2} } + { {'B', 2} {'C', 1} {'A', 3} } + { {'B', 2} {'A', 3} {'C', 1} } + { {'A', 3} {'C', 1} {'B', 2} } + { {'A', 3} {'B', 2} {'C', 1} } + +.SH See also + + ranges::next_permutation generates the next greater lexicographic permutation of a + (C++20) range of elements + (niebloid) + ranges::is_permutation determines if a sequence is a permutation of another + (C++20) sequence + (niebloid) + generates the next greater lexicographic permutation of a + next_permutation range of elements + \fI(function template)\fP + generates the next smaller lexicographic permutation of a + prev_permutation range of elements + \fI(function template)\fP + is_permutation determines if a sequence is a permutation of another + \fI(C++11)\fP sequence + \fI(function template)\fP diff --git a/man/std::ranges::push_heap.3 b/man/std::ranges::push_heap.3 new file mode 100644 index 000000000..ce76255a3 --- /dev/null +++ b/man/std::ranges::push_heap.3 @@ -0,0 +1,227 @@ +.TH std::ranges::push_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::push_heap \- std::ranges::push_heap + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + push_heap( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Comp = + ranges::less, + + class Proj = std::identity > \fB(2)\fP \fI(since C++20)\fP + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + + push_heap( R&& r, Comp comp = {}, Proj proj = {} ); + + Inserts the element at the position last - 1 into the max heap defined by the range + [first, last - 1). + + 1) Elements are compared using the given binary comparison function comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements defining the heap to modify + r - the range of elements defining the heap to modify + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Given N = ranges::distance(first, last), at most \\(\\scriptsize \\log{(N)}\\)log(N) + comparisons and \\(\\scriptsize 2\\log{(N)}\\)2log(N) projections. + +.SH Notes + + A max heap is a range of elements [f, l), arranged with respect to comparator comp + and projection proj, that has the following properties: + + * With N = l - f, p = f[(i - 1) / 2], and q = f[i], for all 0 < i < N, the + expression std::invoke(comp, std::invoke(proj, p), std::invoke(proj, q)) + evaluates to false. + * A new element can be added using ranges::push_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + * The first element can be removed using ranges::pop_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + +.SH Possible implementation + +struct push_heap_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr I + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + const auto n{ranges::distance(first, last)}; + const auto length{n}; + if (n > 1) + { + I last{first + n}; + n = (n - 2) / 2; + I i{first + n}; + if (std::invoke(comp, std::invoke(proj, *i), std::invoke(proj, *--last))) + { + std::iter_value_t v {ranges::iter_move(last)}; + do + { + *last = ranges::iter_move(i); + last = i; + if (n == 0) + break; + n = (n - 1) / 2; + i = first + n; + } + while (std::invoke(comp, std::invoke(proj, *i), std::invoke(proj, v))); + *last = std::move(v); + } + } + return first + length; + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(comp), std::move(proj)); + } +}; + +inline constexpr push_heap_fn push_heap {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void out(const auto& what, int n = 1) + { + while (n-- > 0) + std::cout << what; + } + + void print(auto rem, auto const& v) + { + out(rem); + for (auto e : v) + out(e), out(' '); + out('\\n'); + } + + void draw_heap(auto const& v) + { + auto bails = [](int n, int w) + { + auto b = [](int w) { out("┌"), out("─", w), out("┴"), out("─", w), out("┐"); }; + if (!(n /= 2)) + return; + for (out(' ', w); n-- > 0;) + b(w), out(' ', w + w + 1); + out('\\n'); + }; + auto data = [](int n, int w, auto& first, auto last) + { + for (out(' ', w); n-- > 0 && first != last; ++first) + out(*first), out(' ', w + w + 1); + out('\\n'); + }; + auto tier = [&](int t, int m, auto& first, auto last) + { + const int n{1 << t}; + const int w{(1 << (m - t - 1)) - 1}; + bails(n, w), data(n, w, first, last); + }; + const int m{static_cast(std::ceil(std::log2(1 + v.size())))}; + auto first{v.cbegin()}; + for (int i{}; i != m; ++i) + tier(i, m, first, v.cend()); + } + + int main() + { + std::vector v{1, 6, 1, 8, 0, 3,}; + print("source vector v: ", v); + + std::ranges::make_heap(v); + print("after make_heap: ", v); + draw_heap(v); + + v.push_back(9); + + print("before push_heap: ", v); + draw_heap(v); + + std::ranges::push_heap(v); + print("after push_heap: ", v); + draw_heap(v); + } + +.SH Output: + + source vector v: 1 6 1 8 0 3 + after make_heap: 8 6 3 1 0 1 + 8 + ┌─┴─┐ + 6 3 + ┌┴┐ ┌┴┐ + 1 0 1 + before push_heap: 8 6 3 1 0 1 9 + 8 + ┌─┴─┐ + 6 3 + ┌┴┐ ┌┴┐ + 1 0 1 9 + after push_heap: 9 6 8 1 0 1 3 + 9 + ┌─┴─┐ + 6 8 + ┌┴┐ ┌┴┐ + 1 0 1 3 + +.SH See also + + ranges::is_heap checks if the given range is a max heap + (C++20) (niebloid) + ranges::is_heap_until finds the largest subrange that is a max heap + (C++20) (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) + push_heap adds an element to a max heap + \fI(function template)\fP diff --git a/man/std::ranges::random_access_range.3 b/man/std::ranges::random_access_range.3 new file mode 100644 index 000000000..94ac4a212 --- /dev/null +++ b/man/std::ranges::random_access_range.3 @@ -0,0 +1,53 @@ +.TH std::ranges::random_access_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::random_access_range \- std::ranges::random_access_range + +.SH Synopsis + Defined in header + template< class T > + + concept random_access_range = \fI(since C++20)\fP + + ranges::bidirectional_range && + std::random_access_iterator>; + + The random_access_range concept is a refinement of range for which ranges::begin + returns a model of random_access_iterator. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template concept RAR = std::ranges::random_access_range; + + int main() + { + int a[4]; + static_assert( + RAR> and + RAR> and + RAR> and + RAR> and + RAR and + not RAR> and + not RAR> and + RAR,42>> + ); + } + +.SH See also + + ranges::sized_range specifies that a range knows its size in constant time + (C++20) (concept) + ranges::contiguous_range specifies a range whose iterator type satisfies + (C++20) contiguous_iterator + (concept) diff --git a/man/std::ranges::range.3 b/man/std::ranges::range.3 new file mode 100644 index 000000000..a9fbbc84a --- /dev/null +++ b/man/std::ranges::range.3 @@ -0,0 +1,65 @@ +.TH std::ranges::range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::range \- std::ranges::range + +.SH Synopsis + Defined in header + template< class T > + + concept range = requires( T& t ) { + ranges::begin(t); // equality-preserving for forward iterators \fI(since C++20)\fP + ranges::end (t); + + }; + + The range concept defines the requirements of a type that allows iteration over its + elements by providing an iterator and sentinel that denote the elements of the + range. + +.SH Notes + + A typical range class only needs to provide two functions: + + 1. A member function begin() whose return type models input_or_output_iterator. + 2. A member function end() whose return type models sentinel_for, where It is + the return type of begin(). + + Alternatively, they can be non-member functions, to be found by argument-dependent + lookup. + +.SH Example + + #include + + // A minimum range + struct SimpleRange + { + int* begin(); + int* end(); + }; + static_assert(std::ranges::range); + + // not a range: no begin/end + struct NotRange + { + int t {}; + }; + static_assert(!std::ranges::range); + + // not a range: begin does not return an input_or_output_iterator + struct NotRange2 + { + void* begin(); + int* end(); + }; + static_assert(!std::ranges::range); + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + ranges::begin(t) and ranges::end(t) removed the + LWG 3915 C++20 did not require implicit expression redundant description + variations diff --git a/man/std::ranges::range_adaptor_closure.3 b/man/std::ranges::range_adaptor_closure.3 new file mode 100644 index 000000000..9b8187e2e --- /dev/null +++ b/man/std::ranges::range_adaptor_closure.3 @@ -0,0 +1,61 @@ +.TH std::ranges::range_adaptor_closure 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::range_adaptor_closure \- std::ranges::range_adaptor_closure + +.SH Synopsis + Defined in header + template< class D > + + requires std::is_object_v && std::same_as> + + class range_adaptor_closure {}; + + std::ranges::range_adaptor_closure is a helper class template for defining a + RangeAdaptorClosureObject. + + Let t be the object of type T, the implementation ensures that t is a range adaptor + closure object if all the requirements are met: + + * t is a unary function object that takes one range argument. + * T has exactly one public base class ranges::range_adaptor_closure, and T has + no base classes of type ranges::range_adaptor_closure for any other type U. + * T does not satisfy range. + +.SH Example + + +// Run this code + + #include + #include + + // Define Slice as a range adaptor closure + struct Slice : std::ranges::range_adaptor_closure + { + std::size_t start = 0; + std::size_t end = std::string_view::npos; + + constexpr std::string_view operator()(std::string_view sv) const + { + return sv.substr(start, end - start); + } + }; + + int main() + { + constexpr std::string_view str = "01234567"; + + constexpr Slice slicer{.start = 1, .end = 6}; + + constexpr auto sv1 = slicer(str); // use slicer as a normal function object + constexpr auto sv2 = str | slicer; // use slicer as a range adaptor closure object + static_assert(sv1 == "12345"); + static_assert(sv2 == "12345"); + + // range adaptor closures can be composed + constexpr auto slice_and_drop + = slicer + | std::views::drop_while([](char ch) { return ch != '3'; }); + static_assert(std::string_view(str | slice_and_drop) == "345"); + } diff --git a/man/std::ranges::rbegin.3 b/man/std::ranges::rbegin.3 new file mode 100644 index 000000000..b2ce0c0f3 --- /dev/null +++ b/man/std::ranges::rbegin.3 @@ -0,0 +1,116 @@ +.TH std::ranges::rbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::rbegin \- std::ranges::rbegin + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ rbegin = /* \fI(since C++20)\fP + unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr std::input_or_output_iterator auto rbegin( + T&& t ); + + Returns an iterator to the last element of the argument. + + range-rbegin-rend.svg + + If T is an array type and std::remove_all_extents_t> is + incomplete, then the call to ranges::rbegin is ill-formed, no diagnostic required. + + If the argument is an lvalue or ranges::enable_borrowed_range> + is true, then a call to ranges::rbegin is expression-equivalent to: + + 1. decay-copy(t.rbegin()) + (until C++23) + auto(t.rbegin()) + (since C++23), if that expression is valid and its type models + std::input_or_output_iterator. + 2. Otherwise, + decay-copy(rbegin(t)) + (until C++23) + auto(rbegin(t)) + (since C++23), if T is a class or enumeration type, that expression is valid and + its type models std::input_or_output_iterator, where the meaning of rbegin is + established as if by performing argument-dependent lookup only. + 3. Otherwise, std::make_reverse_iterator(ranges::end(t)) if both ranges::begin(t) + and ranges::end(t) are valid expressions, have the same type, and that type + models std::bidirectional_iterator. + + In all other cases, a call to ranges::rbegin is ill-formed, which can result in + substitution failure when ranges::rbegin(t) appears in the immediate context of a + template instantiation. + +.SH Notes + + If the argument is an rvalue (i.e. T is an object type) and + ranges::enable_borrowed_range> is false, the call to + ranges::rbegin is ill-formed, which also results in substitution failure. + + The return type models std::input_or_output_iterator in all cases. + + The C++20 standard requires that if the underlying rbegin function call returns a + prvalue, the return value is move-constructed from the materialized temporary + object. All implementations directly return the prvalue instead. The requirement is + corrected by the post-C++20 proposal P0849R8 to match the implementations. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v = {3, 1, 4}; + auto vi = std::ranges::rbegin(v); + std::cout << *vi << '\\n'; + *vi = 42; // OK + + int a[] = {-5, 10, 15}; + auto ai = std::ranges::rbegin(a); + std::cout << *ai << '\\n'; + *ai = 42; // OK + + // auto x_x = std::ranges::rbegin(std::vector{6, 6, 6}); + // ill-formed: the argument is an rvalue (see Notes ↑) + + auto si = std::ranges::rbegin(std::span{a}); // OK + static_assert(std::ranges::enable_borrowed_range< + std::remove_cv_t>); + *si = 42; // OK + } + +.SH Output: + + 4 + 15 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2602R2 C++20 there's machinery to prohibit certain removed such machinery + non-member rbegin found by ADL + +.SH See also + + ranges::crbegin returns a reverse iterator to a read-only range + (C++20) (customization point object) + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::ref_view.3 b/man/std::ranges::ref_view.3 new file mode 100644 index 000000000..6cb0a43f1 --- /dev/null +++ b/man/std::ranges::ref_view.3 @@ -0,0 +1,182 @@ +.TH std::ranges::ref_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::ref_view \- std::ranges::ref_view + +.SH Synopsis + Defined in header + template< ranges::range R > + + requires std::is_object_v \fI(since C++20)\fP + class ref_view + + : public ranges::view_interface> + + ref_view is a view of the elements of some other range. It wraps a reference to that + range. + +.SH Member functions + + constructor constructs a ref_view that references to the given range + (C++20) \fI(public member function)\fP + base returns the references to the referenced range + (C++20) \fI(public member function)\fP + begin returns the beginning iterator of the referenced range + (C++20) \fI(public member function)\fP + end returns the sentinel of the referenced range + (C++20) \fI(public member function)\fP + empty checks whether the referenced range is empty + (C++20) \fI(public member function)\fP + size returns the size of the referenced sized_range + (C++20) \fI(public member function)\fP + data returns the pointer to the beginning of the referenced + (C++20) contiguous_range + \fI(public member function)\fP + Inherited from std::ranges::view_interface + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::ref_view::ref_view + + template< /*different-from*/ T > + + requires std::convertible_to && requires { \fI(since C++20)\fP + _FUN(std::declval()); } + + constexpr ref_view( T&& t ); + + Initializes r_ with std::addressof(static_cast(std::forward(t))). + + /*different-from*/ is satisfied if and only if std::remove_cvref_t and + std::remove_cvref_t are not the same type, and overloads of _FUN are declared as + void _FUN(R&); void _FUN(R&&) = delete;. + +.SH Parameters + + t - range to reference + +std::ranges::ref_view::base + + constexpr R& base() const; \fI(since C++20)\fP + + Equivalent to return *r_;. + +std::ranges::ref_view::begin + + constexpr ranges::iterator_t begin() const; \fI(since C++20)\fP + + Equivalent to return ranges::begin(*r_);. + +std::ranges::ref_view::end + + constexpr ranges::sentinel_t end() const; \fI(since C++20)\fP + + Equivalent to return ranges::end(*r_);. + +std::ranges::ref_view::empty + + constexpr bool empty() const \fI(since C++20)\fP + requires requires { ranges::empty(*r_); }; + + Equivalent to return ranges::empty(*r_);. + +std::ranges::ref_view::size + + constexpr auto size() const \fI(since C++20)\fP + requires ranges::sized_range; + + Equivalent to return ranges::size(*r_);. + +std::ranges::ref_view::data + + constexpr auto data() const \fI(since C++20)\fP + requires ranges::contiguous_range; + + Equivalent to return ranges::data(*r_);. + + Deduction guides + + template< class R > \fI(since C++20)\fP + ref_view( R& ) -> ref_view; + + Helper templates + + template< class T > + inline constexpr bool enable_borrowed_range> = \fI(since C++20)\fP + true; + + This specialization of std::ranges::enable_borrowed_range makes ref_view satisfy + borrowed_range. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string s{"cosmos"}; + + const std::ranges::take_view tv{s, 3}; + const std::ranges::ref_view rv{tv}; + + std::cout + << std::boolalpha + << "call empty() : " << rv.empty() << '\\n' + << "call size() : " << rv.size() << '\\n' + << "call begin() : " << *rv.begin() << '\\n' + << "call end() : " << *(rv.end() - 1) << '\\n' + << "call data() : " << rv.data() << '\\n' + << "call base() : " << rv.base().size() << '\\n' // ~> tv.size() + << "range-for : "; + + for (const auto c : rv) + std::cout << c; + std::cout << '\\n'; + } + +.SH Output: + + call empty() : false + call size() : 3 + call begin() : c + call end() : s + call data() : cosmos + call base() : 3 + range-for : cos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + default constructor was provided as removed along with the + P2325R3 C++20 view requirement + must be default_initializable + +.SH See also + + reference_wrapper CopyConstructible and CopyAssignable reference wrapper + \fI(C++11)\fP \fI(class template)\fP + ranges::owning_view a view with unique ownership of some range + (C++20) \fI(class template)\fP + views::all_t a view that includes all elements of a range + views::all (alias template) (range adaptor object) + (C++20) diff --git a/man/std::ranges::remove,std::ranges::remove_if.3 b/man/std::ranges::remove,std::ranges::remove_if.3 new file mode 100644 index 000000000..48fa66a3a --- /dev/null +++ b/man/std::ranges::remove,std::ranges::remove_if.3 @@ -0,0 +1,292 @@ +.TH std::ranges::remove,std::ranges::remove_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::remove,std::ranges::remove_if \- std::ranges::remove,std::ranges::remove_if + +.SH Synopsis + Defined in header + Call signature + template< std::permutable I, std::sentinel_for S, + + class T, class Proj = std::identity > + requires std::indirect_binary_predicate (since + , C++20) + const T*> (until + constexpr ranges::subrange C++26) + + remove( I first, S last, const T& value, Proj proj = {} + ); + template< std::permutable I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t > + requires std::indirect_binary_predicate (since + , C++26) + const T*> + constexpr ranges::subrange + + remove( I first, S last, const T& value, Proj proj = {} + ); + template< ranges::forward_range R, + + class T, class Proj = std::identity > + requires std::permutable> && (since + std::indirect_binary_predicate C++20) + , Proj>, C++26) + const T*> + constexpr ranges::borrowed_subrange_t + + remove( R&& r, const T& value, Proj proj = {} ); \fB(1)\fP + template< ranges::forward_range R, + + class Proj = std::identity, + class T = + std::projected_value_t, Proj> > + requires std::permutable> && (since + std::indirect_binary_predicate C++26) + , Proj>, + const T*> \fB(2)\fP + constexpr ranges::borrowed_subrange_t + + remove( R&& r, const T& value, Proj proj = {} ); + template< std::permutable I, std::sentinel_for S, + + class Proj = std::identity, + std::indirect_unary_predicate> Pred > C++20) + constexpr ranges::subrange + + remove_if( I first, S last, Pred pred, Proj proj = {} ); + template< ranges::forward_range R, + + class Proj = std::identity, + std::indirect_unary_predicate + , Proj>> \fB(4)\fP (since + Pred > C++20) + requires std::permutable> + constexpr ranges::borrowed_subrange_t + + remove_if( R&& r, Pred pred, Proj proj = {} ); + + Removes all elements satisfying specific criteria from the range [first, last) and + returns a subrange [ret, last), where ret is a past-the-end iterator for the new end + of the range. + + 1) Removes all elements that are equal to value, using std::invoke(proj, *i) == + value to compare. + 3) Removes all elements for which std::invoke(pred, std::invoke(proj, *i)) returns + true. + 2,4) Same as (1,3), but uses r as the range, as if using ranges::begin(r) as first + and ranges::end(r) as last. + + Removing is done by shifting (by means of move assignment) the elements in the range + in such a way that the elements that are not to be removed appear in the beginning + of the range. Relative order of the elements that remain is preserved and the + physical size of the container is unchanged. Iterators pointing to an element + between the new logical end and the physical end of the range are still + dereferenceable, but the elements themselves have unspecified values (as per + MoveAssignable post-condition). + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to process + r - the range of elements to process + value - the value of elements to remove + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + {ret, last}, where [first, ret) is the resulting subrange after removal, and the + elements in subrange [ret, last) are all in valid but unspecified state, i.e. + [ret, last) is the subrange to be erased. + +.SH Complexity + + Exactly N applications of the corresponding predicate and any projection, where N = + ranges::distance(first, last), and N - 1 move operations at worst. + +.SH Notes + + A call to ranges::remove is typically followed by a call to a container's erase + member function, which erases the unspecified values and reduces the physical size + of the container to match its new logical size. These two invocations together + constitute a so-called Erase-remove idiom, which can be achieved by the free + function std::erase that has overloads for all standard sequence containers, or + std::erase_if that has overloads for all standard containers. + + The similarly-named container member functions list::remove, list::remove_if, + forward_list::remove, and forward_list::remove_if erase the removed elements. + + These algorithms usually cannot be used with associative containers such as std::set + and std::map because their iterator types do not dereference to MoveAssignable types + (the keys in these containers are not modifiable). + + Because ranges::remove takes value by reference, it can have unexpected behavior if + it is a reference to an element of the range [first, last). + +.SH Possible implementation + + remove + struct remove_fn + { + template S, class Proj = std::identity, + class T = std::projected_value_t> + requires std::indirect_binary_predicate + , const T*> + constexpr ranges::subrange + operator()(I first, S last, const T& value, Proj proj = {}) const + { + first = ranges::find(std::move(first), last, value, proj); + if (first != last) + { + for (I i{std::next(first)}; i != last; ++i) + if (value != std::invoke(proj, *i)) + { + *first = ranges::iter_move(i); + ++first; + } + } + return {first, last}; + } + + template, Proj>> + requires std::permutable> && + std::indirect_binary_predicate + , Proj>, const T*> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, const T& value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, std::move(proj)); + } + }; + + inline constexpr remove_fn remove {}; + remove_if + struct remove_if_fn + { + template S, class Proj = std::identity, + std::indirect_unary_predicate> Pred> + constexpr ranges::subrange + operator()(I first, S last, Pred pred, Proj proj = {}) const + { + first = ranges::find_if(std::move(first), last, pred, proj); + if (first != last) + { + for (I i{std::next(first)}; i != last; ++i) + if (!std::invoke(pred, std::invoke(proj, *i))) + { + *first = ranges::iter_move(i); + ++first; + } + } + return {first, last}; + } + + template, Proj>> Pred> + requires std::permutable> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), pred, std::move(proj)); + } + }; + + inline constexpr remove_if_fn remove_if {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + #include + + int main() + { + std::string v1{"No - Diagnostic - Required"}; + std::cout << std::quoted(v1) << " (v1, size: " << v1.size() << ")\\n"; + const auto ret = std::ranges::remove(v1, ' '); + std::cout << std::quoted(v1) << " (v1 after `remove`, size: " << v1.size() << ")\\n"; + std::cout << ' ' << std::string(std::distance(v1.begin(), ret.begin()), '^') << '\\n'; + v1.erase(ret.begin(), ret.end()); + std::cout << std::quoted(v1) << " (v1 after `erase`, size: " << v1.size() << ")\\n\\n"; + + // remove_if with custom unary predicate: + auto rm = [](char c) { return !std::isupper(c); }; + std::string v2{"Substitution Failure Is Not An Error"}; + std::cout << std::quoted(v2) << " (v2, size: " << v2.size() << ")\\n"; + const auto [first, last] = std::ranges::remove_if(v2, rm); + std::cout << std::quoted(v2) << " (v2 after `remove_if`, size: " << v2.size() << ")\\n"; + std::cout << ' ' << std::string(std::distance(v2.begin(), first), '^') << '\\n'; + v2.erase(first, last); + std::cout << std::quoted(v2) << " (v2 after `erase`, size: " << v2.size() << ")\\n\\n"; + + // creating a view into a container that is modified by `remove_if`: + for (std::string s : {"Small Object Optimization", "Non-Type Template Parameter"}) + std::cout << std::quoted(s) << " => " + << std::string_view{begin(s), std::ranges::remove_if(s, rm).begin()} << '\\n'; + + std::vector> nums{{2, 2}, {1, 3}, {4, 8}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto e = std::ranges::remove(nums, {1, 3}); // T gets deduced + #else + auto e = std::ranges::remove(nums, std::complex{1, 3}); + #endif + nums.erase(e.begin(), e.end()); + assert((nums == std::vector>{{2, 2}, {4, 8}})); + } + +.SH Possible output: + + "No _ Diagnostic _ Required" (v1, size: 26) + "No_Diagnostic_Requiredired" (v1 after `remove`, size: 26) + ^^^^^^^^^^^^^^^^^^^^^^ + "No_Diagnostic_Required" (v1 after `erase`, size: 22) + + "Substitution Failure Is Not An Error" (v2, size: 36) + "SFINAEtution Failure Is Not An Error" (v2 after `remove_if`, size: 36) + ^^^^^^ + "SFINAE" (v2 after `erase`, size: 6) + + "Small Object Optimization" => SOO + "Non-Type Template Parameter" => NTTP + +.SH See also + + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) + ranges::unique removes consecutive duplicate elements in a range + (C++20) (niebloid) + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP diff --git a/man/std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result,.3 b/man/std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result,.3 new file mode 100644 index 000000000..4e52505d7 --- /dev/null +++ b/man/std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result,.3 @@ -0,0 +1,315 @@ +.TH std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result, \- std::ranges::remove_copy,std::ranges::remove_copy_if,std::ranges::remove_copy_result, + +.SH Synopsis + + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + std::weakly_incrementable O, class T, class Proj = + std::identity > + requires std::indirectly_copyable && (since + std::indirect_binary_predicate C++20) + , (until + const T*> C++26) + constexpr remove_copy_result + + remove_copy( I first, S last, O result, const T& value, + Proj proj = {} ); + template< std::input_iterator I, std::sentinel_for S, + + std::weakly_incrementable O, class Proj = + std::identity, + class T = std::projected_value_t > + requires std::indirectly_copyable && (since + std::indirect_binary_predicate C++26) + , + const T*> + constexpr remove_copy_result + + remove_copy( I first, S last, O result, const T& value, + Proj proj = {} ); + template< ranges::input_range R, + + std::weakly_incrementable O, class T, class Proj = + std::identity > + requires std::indirectly_copyable, O> + && (since + std::indirect_binary_predicate C++20) + , Proj>, C++26) + const T*> + constexpr remove_copy_result, + O> + + remove_copy( R&& r, O result, const T& value, Proj proj + = {} ); + template< ranges::input_range R, + + std::weakly_incrementable O, class Proj = \fB(1)\fP + std::identity, + class T = + std::projected_value_t, Proj> > + requires std::indirectly_copyable, O> + && (since + std::indirect_binary_predicate C++26) + , Proj>, + const T*> + constexpr remove_copy_result, + O> + + remove_copy( R&& r, O result, const T& value, Proj proj \fB(2)\fP + = {} ); + template< std::input_iterator I, std::sentinel_for S, + + std::weakly_incrementable O, class Proj = + std::identity, + std::indirect_unary_predicate> Pred > \fB(3)\fP C++20) + requires std::indirectly_copyable + constexpr remove_copy_if_result + + remove_copy_if( I first, S last, O result, Pred pred, + Proj proj = {} ); + template< ranges::input_range R, + + std::weakly_incrementable O, class Proj = + std::identity, + std::indirect_unary_predicate< + std::projected, Proj>> (since + Pred > \fB(4)\fP C++20) + requires std::indirectly_copyable, O> + constexpr + remove_copy_if_result, O> + + remove_copy_if( R&& r, O result, Pred pred, Proj proj = + {} ); +.SH Helper types + template< class I, class O > \fB(5)\fP (since + using remove_copy_result = ranges::in_out_result; C++20) + template< class I, class O > \fB(6)\fP (since + using remove_copy_if_result = ranges::in_out_result; C++20) + + Copies elements from the source range [first, last), to the destination range + beginning at result, omitting the elements which (after being projected by proj) + satisfy specific criteria. The behavior is undefined if the source and destination + ranges overlap. + + 1) Ignores all elements that are equal to value. + 3) Ignores all elements for which predicate pred returns true. + 2,4) Same as (1,3), but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the source range of elements + r - the source range of elements + result - the beginning of the destination range + value - the value of the elements not to copy + comp - the binary predicate to compare the projected elements + proj - the projection to apply to the elements + +.SH Return value + + {last, result + N}, where N is the number of elements copied. + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the corresponding predicate + comp and any projection proj. + +.SH Notes + + The algorithm is stable, i.e. preserves the relative order of the copied elements. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Possible implementation + + remove_copy + struct remove_copy_fn + { + template S, + std::weakly_incrementable O, class Proj = std::identity, + class T = std::projected_value_t> + requires std::indirectly_copyable && + std::indirect_binary_predicate, const T*> + constexpr ranges::remove_copy_result + operator()(I first, S last, O result, const T& value, Proj proj = {}) const + { + for (; !(first == last); ++first) + if (value != std::invoke(proj, *first)) + { + *result = *first; + ++result; + } + return {std::move(first), std::move(result)}; + } + + template, Proj>> + requires std::indirectly_copyable, O> && + std::indirect_binary_predicate, Proj>, const T*> + constexpr ranges::remove_copy_result, O> + operator()(R&& r, O result, const T& value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result), value, + std::move(proj)); + } + }; + + inline constexpr remove_copy_fn remove_copy {}; + remove_copy_if + struct remove_copy_if_fn + { + template S, std::weakly_incrementable O, + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + requires std::indirectly_copyable + constexpr ranges::remove_copy_if_result + operator()(I first, S last, O result, Pred pred, Proj proj = {}) const + { + for (; first != last; ++first) + if (false == std::invoke(pred, std::invoke(proj, *first))) + { + *result = *first; + ++result; + } + return {std::move(first), std::move(result)}; + } + + template, Proj>> Pred> + requires std::indirectly_copyable, O> + constexpr ranges::remove_copy_if_result, O> + operator()(R&& r, O result, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result), + std::move(pred), std::move(proj)); + } + }; + + inline constexpr remove_copy_if_fn remove_copy_if {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + void println(const auto rem, const auto& v) + { + std::cout << rem << ' '; + for (const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + // Filter out the hash symbol from the given string. + const std::string_view str{"#Small #Buffer #Optimization"}; + std::cout << "before: " << std::quoted(str) << '\\n'; + + std::cout << "after: \\""; + std::ranges::remove_copy(str.begin(), str.end(), + std::ostream_iterator(std::cout), '#'); + std::cout << "\\"\\n"; + + // Copy only the complex numbers with positive imaginary part. + using Ci = std::complex; + constexpr std::array source + { + Ci{1, 0}, Ci{0, 1}, Ci{2, -1}, Ci{3, 2}, Ci{4, -3} + }; + std::vector> target; + + std::ranges::remove_copy_if + ( + source, + std::back_inserter(target), + [](int imag) { return imag <= 0; }, + [](Ci z) { return z.imag(); } + ); + + println("source:", source); + println("target:", target); + + std::vector> nums{{2, 2}, {1, 3}, {4, 8}, {1, 3}}; + std::vector> outs; + #ifdef __cpp_lib_algorithm_default_value_type + std::remove_copy(nums.cbegin(), nums.cend(), std::back_inserter(outs), + {1, 3}); // T gets deduced to std::complex + #else + std::remove_copy(nums.cbegin(), nums.cend(), std::back_inserter(outs), + std::complex{1, 3}); + #endif + println("nums: ", nums); + println("outs: ", outs); + } + +.SH Output: + + before: "#Small #Buffer #Optimization" + after: "Small Buffer Optimization" + source: (1,0) (0,1) (2,-1) (3,2) (4,-3) + target: (0,1) (3,2) + nums: (2,2) (1,3) (4,8) (1,3) + outs: (2,2) (4,8) + +.SH See also + + ranges::remove + ranges::remove_if removes elements satisfying specific criteria + (C++20) (niebloid) + (C++20) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) + ranges::copy_backward copies a range of elements in backwards order + (C++20) (niebloid) + ranges::replace_copy copies a range, replacing elements satisfying specific + ranges::replace_copy_if criteria with another value + (C++20) (niebloid) + (C++20) + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) + ranges::rotate_copy copies and rotate a range of elements + (C++20) (niebloid) + ranges::unique_copy creates a copy of some range of elements that contains no + (C++20) consecutive duplicates + (niebloid) + remove_copy copies a range of elements omitting those that satisfy + remove_copy_if specific criteria + \fI(function template)\fP diff --git a/man/std::ranges::rend.3 b/man/std::ranges::rend.3 new file mode 100644 index 000000000..1ee959fb3 --- /dev/null +++ b/man/std::ranges::rend.3 @@ -0,0 +1,114 @@ +.TH std::ranges::rend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::rend \- std::ranges::rend + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + \fI(since C++20)\fP + inline constexpr /* unspecified */ rend = /* unspecified (customization point + */; object) + + } + Call signature + template< class T > + + requires /* see below */ + constexpr std::sentinel_for< \fI(since C++20)\fP + + decltype(ranges::rbegin(std::declval()))> auto rend( + T&& t ); + + Returns a sentinel indicating the end of a reversed range. + + range-rbegin-rend.svg + + If T is an array type and std::remove_all_extents_t> is + incomplete, then the call to ranges::rend is ill-formed, no diagnostic required. + + If the argument is an lvalue or ranges::enable_borrowed_range> + is true, then a call to ranges::rend is expression-equivalent to: + + 1. decay-copy(t.rend()) + (until C++23) + auto(t.rend()) + (since C++23), if that expression is valid and its type models + std::sentinel_for()))>. + 2. Otherwise, + decay-copy(rend(t)) + (until C++23) + auto(rend(t)) + (since C++23), if T is a class or enumeration type, that expression is valid and + its type models std::sentinel_for()))>, + where the meaning of rend is established as if by performing argument-dependent + lookup only. + 3. Otherwise, std::make_reverse_iterator(ranges::begin(t)) if both ranges::begin(t) + and ranges::end(t) are valid expressions, have the same type, and that type + models std::bidirectional_iterator. + + In all other cases, a call to ranges::rend is ill-formed, which can result in + substitution failure when ranges::rend(t) appears in the immediate context of a + template instantiation. + +.SH Notes + + If the argument is an rvalue (i.e. T is an object type) and + ranges::enable_borrowed_range> is false, or if it is of an array + type of unknown bound, the call to ranges::rend is ill-formed, which also results in + substitution failure. + + If ranges::rend(std::forward(t)) is valid, then + decltype(ranges::rend(std::forward(t))) and + decltype(ranges::begin(std::forward(t))) model std::sentinel_for in all cases, + while T models std::ranges::range. + + The C++20 standard requires that if the underlying rend function call returns a + prvalue, the return value is move-constructed from the materialized temporary + object. All implementations directly return the prvalue instead. The requirement is + corrected by the post-C++20 proposal P0849R8 to match the implementations. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v = {3, 1, 4}; + namespace ranges = std::ranges; + if (ranges::find(ranges::rbegin(v), ranges::rend(v), 5) != ranges::rend(v)) + std::cout << "found a 5 in vector v!\\n"; + + int a[] = {5, 10, 15}; + if (ranges::find(ranges::rbegin(a), ranges::rend(a), 5) != ranges::rend(a)) + std::cout << "found a 5 in array a!\\n"; + } + +.SH Output: + + found a 5 in array a! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2602R2 C++20 there's machinery to prohibit certain removed such machinery + non-member rend found by ADL + +.SH See also + + ranges::crend returns a reverse end iterator to a read-only range + (C++20) (customization point object) + ranges::rbegin returns a reverse iterator to a range + (C++20) (customization point object) + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::ranges::repeat_view::iterator.3 b/man/std::ranges::repeat_view::iterator.3 new file mode 100644 index 000000000..c41ffb725 --- /dev/null +++ b/man/std::ranges::repeat_view::iterator.3 @@ -0,0 +1,162 @@ +.TH std::ranges::repeat_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::repeat_view::iterator \- std::ranges::repeat_view::iterator + +.SH Synopsis + struct /*iterator*/; (since C++23) + (exposition only*) + + The return type of repeat_view::begin. + +.SH Member types + + Member type Definition + * std::ptrdiff_t, if Bound is the same as + index-type std::unreachable_sentinel_t. Otherwise, + * Bound. + (exposition-only member type*) + iterator_concept std::random_access_iterator_tag + iterator_category std::random_access_iterator_tag + value_type W + * /*index-type*/, if /*is-signed-like*/ is true, + difference_type * /*iota-diff-t*/(/*index-type*/) otherwise, where + /*iota-diff-t*/ has the same meaning as in iota_view. + + Data members + + Member name Definition + A pointer of type const W* that holds the pointer to the value to + value_ (private) repeat. + (exposition-only member object*) + current_ (private) An object of type /*index-type*/ that holds the current position. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* returns the current subrange + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +std::ranges::repeat_view::iterator::iterator + + /*iterator*/() = default; \fB(1)\fP (since C++23) + constexpr explicit /*iterator*/( \fB(2)\fP (since C++23) + const W* value, /*index-type*/ b = /*index-type*/() ); (exposition only*) + + 1) Value initializes the data members: + * value_ with nullptr_t via its default member initializer; + * index_ via its default member initializer (= /*index-type*/()). + 2) Value initializes value_ with value and bound_ with b. If Bound is not + std::unreachable_sentinel_t then b must be non-negative. This constructor is not a + part of the public interface. + +std::ranges::repeat_view::iterator::operator* + + constexpr const W& operator*() const noexcept; (since C++23) + + Equivalent to return *value_;. + +std::ranges::repeat_view::iterator::operator[] + + constexpr const W& operator[]( difference_type n ) const noexcept; (since C++23) + + Equivalent to return *(*this + n);. + +std::ranges::repeat_view::iterator::operator++ + + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++(int); \fB(2)\fP (since C++23) + + 1) Equivalent to ++current_; return *this;. + 2) Equivalent to auto tmp = *this; ++*this; return tmp;. + +std::ranges::repeat_view::iterator::operator-- + + constexpr /*iterator*/& operator--(); \fB(1)\fP (since C++23) + constexpr /*iterator*/ operator--(int); \fB(2)\fP (since C++23) + + 1) Equivalent to --current_; return *this;. If Bound is not + std::unreachable_sentinel_t then bound_ must be positive. + 2) Equivalent to auto tmp = *this; --*this; return tmp;. + +std::ranges::repeat_view::iterator::operator+= + + constexpr /*iterator*/& operator+=( difference_type n ); (since C++23) + + Equivalent to current_ += n; return *this;. If Bound is not + std::unreachable_sentinel_t then (bound_ + n) must be non-negative. + +std::ranges::repeat_view::iterator::operator-= + + constexpr /*iterator*/& operator-=( difference_type n ); (since C++23) + + Equivalent to current_ -= n; return *this;. If Bound is not + std::unreachable_sentinel_t, then (bound_ - n) must be non-negative. + +.SH Non-member functions + + operator== compares the underlying iterators + operator<=> \fI(function)\fP + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +operator==, <=>(std::ranges::repeat_view::iterator) + + friend constexpr bool operator==( const /*iterator*/& x, const \fB(1)\fP (since C++23) + /*iterator*/& y ); + friend constexpr auto operator<=>( const /*iterator*/& x, const \fB(2)\fP (since C++23) + /*iterator*/& y ); + + 1) Equivalent to x.current_ == y.current_. + 2) Equivalent to x.current_ <=> y.current_. + + The != operator is synthesized from operator==. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when iterator is an associated class of + the arguments. + +operator+(std::ranges::repeat_view::iterator) + + friend constexpr /*iterator*/ operator+( /*iterator*/ i, \fB(1)\fP (since C++23) + difference_type n ); + friend constexpr /*iterator*/ operator+( difference_type n, \fB(2)\fP (since C++23) + /*iterator*/ i ); + + Equivalent to i += n; return i;. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when iterator is an associated class of + the arguments. + +operator-(std::ranges::repeat_view::iterator) + + friend constexpr /*iterator*/ operator-( /*iterator*/ i, \fB(1)\fP (since C++23) + difference_type n ); + friend constexpr difference_type operator-( const /*iterator*/& x, + const /*iterator*/& y \fB(2)\fP (since C++23) + ); + + 1) Equivalent to i -= n; return i;. + 2) Equivalent to return static_cast(x.current_) - + static_cast(y.current_);. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when iterator is an associated class of + the arguments. + +.SH Notes + + iterator is always random_access_iterator. diff --git a/man/std::ranges::replace,std::ranges::replace_if.3 b/man/std::ranges::replace,std::ranges::replace_if.3 new file mode 100644 index 000000000..39b52aa0b --- /dev/null +++ b/man/std::ranges::replace,std::ranges::replace_if.3 @@ -0,0 +1,308 @@ +.TH std::ranges::replace,std::ranges::replace_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::replace,std::ranges::replace_if \- std::ranges::replace,std::ranges::replace_if + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, + std::sentinel_for S, + + class T1, class T2, class Proj = + std::identity > + requires std::indirectly_writable (since + && C++20) + std::indirect_binary_predicate (until + , const T1*> + constexpr I replace( I first, S last, const T1& + old_value, + + const T2& new_value, Proj + proj = {} ); + template< std::input_iterator I, + std::sentinel_for S, + + class Proj = std::identity, + class T1 = std::projected_value_t, class T2 = T1 > + requires std::indirectly_writable + && (since + std::indirect_binary_predicate C++26) + , const T1*> + constexpr I replace( I first, S last, const T1& + old_value, + + const T2& new_value, Proj + proj = {} ); + template< ranges::input_range R, + + class T1, class T2, class Proj = + std::identity > + requires + std::indirectly_writable, + const T2&> && (since + std::indirect_binary_predicate C++20) + , Proj>, + const T1*> + constexpr ranges::borrowed_iterator_t + replace( R&& r, const T1& old_value, + + const T2& new_value, Proj proj = {} + ); + template< ranges::input_range R, + + class Proj = std::identity, + class T1 = + std::projected_value_t, + Proj>, + class T2 = T1 > + requires + std::indirectly_writable, + const T2&> && (since + std::indirect_binary_predicate C++26) + , Proj>, + const T1*> + constexpr ranges::borrowed_iterator_t \fB(1)\fP + replace( R&& r, const T1& old_value, + + const T2& new_value, Proj proj = {} + ); + template< std::input_iterator I, + std::sentinel_for S, + + class T, class Proj = std::identity, + (since + std::indirect_unary_predicate> Pred > (until + requires std::indirectly_writable C++26) + constexpr I replace_if( I first, S last, Pred + pred, + \fB(2)\fP + const T& new_value, Proj + proj = {} ); + template< std::input_iterator I, + std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t, + (since + std::indirect_unary_predicate> Pred > + requires std::indirectly_writable + constexpr I replace_if( I first, S last, Pred + pred, + + const T& new_value, Proj + proj = {} ); + template< ranges::input_range R, class T, class + Proj = std::identity, \fB(3)\fP + + std::indirect_unary_predicate< + + std::projected, Proj>> (since + Pred > C++20) + requires (until + std::indirectly_writable, C++26) + const T&> + constexpr ranges::borrowed_iterator_t + + replace_if( R&& r, Pred pred, const T& + new_value, Proj proj = {} ); + template< ranges::input_range R, class Proj = + std::identity, \fB(4)\fP + + class T = + std::projected_value_t, + Proj>, + std::indirect_unary_predicate< + (since + std::projected, Proj>> C++26) + Pred > + requires + std::indirectly_writable, + const T&> + constexpr ranges::borrowed_iterator_t + + replace_if( R&& r, Pred pred, const T& + new_value, Proj proj = {} ); + + Replaces all elements satisfying specific criteria with new_value in the range + [first, last). + + 1) Replaces all elements that are equal to old_value, using std::invoke(proj, *i) == + old_value to compare. + 3) Replaces all elements for which the predicate pred evaluates to true, where + evaluating expression is std::invoke(pred, std::invoke(proj, *i)). + 2,4) Same as (1,3), but uses r as the range, as if using ranges::begin(r) as first + and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to process + r - the range of elements to process + old_value - the value of elements to replace + new_value - the value to use as a replacement + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Exactly ranges::distance(first, last) applications of the corresponding predicate + comp and any projection proj. + +.SH Notes + + Because the algorithm takes old_value and new_value by reference, it may have + unexpected behavior if either is a reference to an element of the range + [first, last). + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1-4) + +.SH Possible implementation + + replace + struct replace_fn + { + template S, class Proj = std::identity, + class T1 = std::projected_value_t, class T2 = T1> + requires std::indirectly_writable && + std::indirect_binary_predicate + , const T1*> + constexpr I operator()(I first, S last, const T1& old_value, + const T2& new_value, Proj proj = {}) const + { + for (; first != last; ++first) + if (old_value == std::invoke(proj, *first)) + *first = new_value; + return first; + } + + template, Proj>, + class T2 = T1> + requires std::indirectly_writable, const T2&> && + std::indirect_binary_predicate, Proj>, const T1*> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, const T1& old_value, + const T2& new_value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), old_value, + new_value, std::move(proj)); + } + }; + + inline constexpr replace_fn replace {}; + replace_if + struct replace_if_fn + { + template S, + class Proj = std::identity, class T = std::projected_value_t, + std::indirect_unary_predicate> Pred> + requires std::indirectly_writable + constexpr I operator()(I first, S last, Pred pred, + const T& new_value, Proj proj = {}) const + { + for (; first != last; ++first) + if (!!std::invoke(pred, std::invoke(proj, *first))) + *first = new_value; + return std::move(first); + } + + template, Proj> + std::indirect_unary_predicate + , Proj>> Pred> + requires std::indirectly_writable, const T&> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Pred pred, const T& new_value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(pred), + new_value, std::move(proj)); + } + }; + + inline constexpr replace_if_fn replace_if {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void println(const auto& v) + { + for (const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + namespace ranges = std::ranges; + + std::array p{1, 6, 1, 6, 1, 6}; + println(p); + ranges::replace(p, 6, 9); + println(p); + + std::array q{1, 2, 3, 6, 7, 8, 4, 5}; + println(q); + ranges::replace_if(q, [](int x) { return 5 < x; }, 5); + println(q); + + std::array, 2> nums{{{1, 3}, {1, 3}}}; + println(nums); + #ifdef __cpp_lib_algorithm_default_value_type + ranges::replace(nums, {1, 3}, {4, 2}); + #else + ranges::replace(nums, std::complex{1, 3}, std::complex{4, 2}); + #endif + println(nums); + } + +.SH Output: + + 1 6 1 6 1 6 + 1 9 1 9 1 9 + 1 2 3 6 7 8 4 5 + 1 2 3 5 5 5 4 5 + (1,3) (1,3) + (4,2) (4,2) + +.SH See also + + ranges::replace_copy copies a range, replacing elements satisfying specific + ranges::replace_copy_if criteria with another value + (C++20) (niebloid) + (C++20) + replace replaces all values satisfying specific criteria with + replace_if another value + \fI(function template)\fP diff --git a/man/std::ranges::replace_copy,std::ranges::replace_copy_if,std::ranges::replace_copy_result,.3 b/man/std::ranges::replace_copy,std::ranges::replace_copy_if,std::ranges::replace_copy_result,.3 new file mode 100644 index 000000000..5c05bf0ea --- /dev/null +++ b/man/std::ranges::replace_copy,std::ranges::replace_copy_if,std::ranges::replace_copy_result,.3 @@ -0,0 +1,354 @@ +.TH std::ranges::replace_copy,std::ranges::replace_copy_if,std::ranges::replace_copy_result, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::replace_copy,std::ranges::replace_copy_if,std::ranges::replace_copy_result, \- std::ranges::replace_copy,std::ranges::replace_copy_if,std::ranges::replace_copy_result, + +.SH Synopsis + +Defined in header +Call signature +template< std::input_iterator I, std::sentinel_for +S, class T1, class T2, + + std::output_iterator O, class +Proj = std::identity > +requires std::indirectly_copyable && (since + std::indirect_binary_predicate C++20) + , const T1*> C++26) +constexpr replace_copy_result + replace_copy( I first, S last, O result, const T1& +old_value, + + const T2& new_value, Proj proj = {} +); +template< std::input_iterator I, std::sentinel_for +S, + + class O, class Proj = std::identity, + class T1 = std::projected_value_t, + class T2 = std::iter_value_t > +requires std::indirectly_copyable && + std::indirect_binary_predicate (since + , const T1*> && + std::output_iterator +constexpr replace_copy_result + replace_copy( I first, S last, O result, const T1& +old_value, + + const T2& new_value, Proj proj = {} +); +template< ranges::input_range R, class T1, class T2, + + std::output_iterator O, class +Proj = std::identity > +requires +std::indirectly_copyable, O> && + std::indirect_binary_predicate (since + , (until +Proj>, const T1*> C++26) +constexpr +replace_copy_result, O> + replace_copy( R&& r, O result, const T1& +old_value, + + const T2& new_value, Proj proj = {} +); +template< ranges::input_range R, + + class O, class Proj = std::identity, + class T1 = +std::projected_value_t, Proj>, + class T2 = std::iter_value_t > +requires +std::indirectly_copyable, O> && + std::indirect_binary_predicate + , C++26) +Proj>, const T1*> && + std::output_iterator +constexpr +replace_copy_result, O> + replace_copy( R&& r, O result, const T1& +old_value, + + const T2& new_value, Proj proj = {} +); +template< std::input_iterator I, std::sentinel_for \fB(1)\fP +S, + + class T, std::output_iterator O, + class Proj = std::identity, + (since +std::indirect_unary_predicate> C++20) +Pred > (until +requires std::indirectly_copyable C++26) +constexpr replace_copy_if_result + replace_copy_if( I first, S last, O result, Pred +pred, + + const T& new_value, Proj proj = +{} ); +template< std::input_iterator I, std::sentinel_for +S, \fB(2)\fP + + class O, class T = std::iter_value_t + class Proj = std::identity, + +std::indirect_unary_predicate> +Pred > (since +requires std::indirectly_copyable && C++26) +std::output_iterator +constexpr replace_copy_if_result + replace_copy_if( I first, S last, O result, Pred +pred, + + const T& new_value, Proj proj = +{} ); +template< ranges::input_range R, + + class T, std::output_iterator O, + class Proj = std::identity, + std::indirect_unary_predicate \fB(3)\fP + , +Proj>> Pred > (since +requires C++20) +std::indirectly_copyable, O> (until +constexpr C++26) +replace_copy_if_result, +O> + replace_copy_if( R&& r, O result, Pred pred, + + const T& new_value, Proj proj = +{} ); +template< ranges::input_range R, + + class O, class T = std::iter_value_t + class Proj = std::identity, \fB(4)\fP + std::indirect_unary_predicate + , +Proj>> Pred > +requires (since +std::indirectly_copyable, O> && C++26) + std::output_iterator +constexpr +replace_copy_if_result, +O> + replace_copy_if( R&& r, O result, Pred pred, + + const T& new_value, Proj proj = +{} ); +.SH Helper types +template< class I, class O > (since +using replace_copy_result = ranges::in_out_result; +template< class I, class O > (since +using replace_copy_if_result = \fB(6)\fP C++20) +ranges::in_out_result; + + Copies the elements from the source range [first, last) to the destination range + beginning at result, replacing all elements satisfying specific criteria with + new_value. The behavior is undefined if the source and destination ranges overlap. + + 1) Replaces all elements that are equal to old_value, using std::invoke(proj, + *(first + (i - result))) == old_value to compare. + 3) Replaces all elements for which the predicate pred evaluates to true, where the + evaluating expression is std::invoke(pred, std::invoke(proj, *(first + (i - + result)))). + 2,4) Same as (1,3), but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to copy + r - the range of elements to copy + result - the beginning of the destination range + old_value - the value of elements to replace + new_value - the value to use as a replacement + pred - predicate to apply to the projected elements + proj - projection to apply to the elements. + +.SH Return value + + {last, result + N}, where + + 1,3) N = ranges::distance(first, last); + 2,4) N = ranges::distance(r). + +.SH Complexity + + Exactly N applications of the corresponding predicate comp and any projection proj. + +.SH Possible implementation + + replace_copy (1,2) + struct replace_copy_fn + { + template S, + class O, class Proj = std::identity, + class T1 = std::projected_value_t, + class T2 = std::iter_value_t> + requires std::indirectly_copyable && + std::indirect_binary_predicate + , const T1*> && + std::output_iterator + constexpr ranges::replace_copy_result + operator()(I first, S last, O result, const T1& old_value, + const T2& new_value, Proj proj = {}) const + { + for (; first != last; ++first, ++result) + *result = (std::invoke(proj, *first) == old_value) ? new_value : *first; + return {std::move(first), std::move(result)}; + } + + template, Proj>, + class T2 = std::iter_value_t> + requires std::indirectly_copyable, O> && + std::indirect_binary_predicate + , Proj>, const T1*> + constexpr ranges::replace_copy_result, O> + operator()(R&& r, O result, const T1& old_value, + const T2& new_value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result), + old_value, new_value, std::move(proj)); + } + }; + + inline constexpr replace_copy_fn replace_copy {}; + replace_copy_if (3,4) + struct replace_copy_if_fn + { + template S, + class O, class T = std::iter_value_t + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + requires std::indirectly_copyable && std::output_iterator + constexpr ranges::replace_copy_if_result + operator()(I first, S last, O result, Pred pred, + const T& new_value, Proj proj = {}) const + { + for (; first != last; ++first, ++result) + *result = std::invoke(pred, std::invoke(proj, *first)) ? new_value : *first; + return {std::move(first), std::move(result)}; + } + + template + class Proj = std::identity, + std::indirect_unary_predicate + , Proj>> Pred> + requires std::indirectly_copyable, O> && + std::output_iterator + constexpr ranges::replace_copy_if_result, O> + operator()(R&& r, O result, Pred pred, + const T& new_value, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result), + std::move(pred), new_value, std::move(proj)); + } + }; + + inline constexpr replace_copy_if_fn replace_copy_if {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) list-initialization for + algorithms (1-4) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void println(const auto rem, const auto& v) + { + for (std::cout << rem << ": "; const auto& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + std::vector o; + + std::array p{1, 6, 1, 6, 1, 6}; + o.resize(p.size()); + println("p", p); + std::ranges::replace_copy(p, o.begin(), 6, 9); + println("o", o); + + std::array q{1, 2, 3, 6, 7, 8, 4, 5}; + o.resize(q.size()); + println("q", q); + std::ranges::replace_copy_if(q, o.begin(), [](int x) { return 5 < x; }, 5); + println("o", o); + + std::vector> r{{1, 3}, {2, 2}, {4, 8}}; + std::vector> s(r.size()); + println("r", r); + #ifdef __cpp_lib_algorithm_default_value_type + std::ranges::replace_copy(r, s.begin(), + {1, 3}, // T1 gets deduced + {2.2, 4.8}); // T2 gets deduced + #else + std::ranges::replace_copy(r, s.begin(), + std::complex{1, 3}, + std::complex{2.2, 4.8}); + #endif + println("s", s); + + std::vector> b{{1, 3}, {2, 2}, {4, 8}}, + d(b.size()); + println("b", b); + #ifdef __cpp_lib_algorithm_default_value_type + std::ranges::replace_copy_if(b, d.begin(), + [](std::complex z){ return std::abs(z) < 5; }, + {4, 2}); // Possible, since the T is deduced. + #else + std::ranges::replace_copy_if(b, d.begin(), + [](std::complex z){ return std::abs(z) < 5; }, + std::complex{4, 2}); + #endif + println("d", d); + } + +.SH Output: + + p: 1 6 1 6 1 6 + o: 1 9 1 9 1 9 + q: 1 2 3 6 7 8 4 5 + o: 1 2 3 5 5 5 4 5 + r: (1,3) (2,2) (4,8) + s: (2.2,4.8) (2,2) (4,8) + b: (1,3) (2,2) (4,8) + d: (4,2) (4,2) (4,8) + +.SH See also + + ranges::replace replaces all values satisfying specific criteria with another + ranges::replace_if value + (C++20) (niebloid) + (C++20) + replace_copy copies a range, replacing elements satisfying specific criteria + replace_copy_if with another value + \fI(function template)\fP diff --git a/man/std::ranges::reverse.3 b/man/std::ranges::reverse.3 new file mode 100644 index 000000000..c0c74593a --- /dev/null +++ b/man/std::ranges::reverse.3 @@ -0,0 +1,124 @@ +.TH std::ranges::reverse 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::reverse \- std::ranges::reverse + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for S > + + requires std::permutable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + reverse( I first, S last ); + template< ranges::bidirectional_range R > + + requires std::permutable> \fB(2)\fP \fI(since C++20)\fP + constexpr ranges::borrowed_iterator_t + + reverse( R&& r ); + + 1) Reverses the order of the elements in the range [first, last). + Behaves as if applying ranges::iter_swap to every pair of iterators first + i, last + - i - 1 for each integer i, where 0 ≤ i < (last - first) / 2. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to reverse + r - the range of elements to reverse + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Exactly (last - first) / 2 swaps. + +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + models contiguous_iterator and swapping its value type calls neither non-trivial + special member function nor ADL-found swap. + +.SH Possible implementation + + See also implementations in libstdc++ and MSVC STL. + + struct reverse_fn + { + template S> + requires std::permutable + constexpr I operator()(I first, S last) const + { + auto last2 {ranges::next(first, last)}; + for (auto tail {last2}; !(first == tail or first == --tail); ++first) + ranges::iter_swap(first, tail); + return last2; + } + + template + requires std::permutable> + constexpr ranges::borrowed_iterator_t + operator()(R&& r) const + { + return (*this)(ranges::begin(r), ranges::end(r)); + } + }; + + inline constexpr reverse_fn reverse {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s {"ABCDEF"}; + std::cout << s << " → "; + std::ranges::reverse(s.begin(), s.end()); + std::cout << s << " → "; + std::ranges::reverse(s); + std::cout << s << " │ "; + + std::array a {1, 2, 3, 4, 5}; + for (auto e : a) + std::cout << e << ' '; + std::cout << "→ "; + std::ranges::reverse(a); + for (auto e : a) + std::cout << e << ' '; + std::cout << '\\n'; + } + +.SH Output: + + ABCDEF → FEDCBA → ABCDEF │ 1 2 3 4 5 → 5 4 3 2 1 + +.SH See also + + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) + ranges::reverse_view a view that iterates over the elements of another bidirectional + views::reverse view in reverse order + (C++20) \fI(class template)\fP (range adaptor object) + reverse reverses the order of elements in a range + \fI(function template)\fP diff --git a/man/std::ranges::reverse_copy,std::ranges::reverse_copy_result.3 b/man/std::ranges::reverse_copy,std::ranges::reverse_copy_result.3 new file mode 100644 index 000000000..8623f67fe --- /dev/null +++ b/man/std::ranges::reverse_copy,std::ranges::reverse_copy_result.3 @@ -0,0 +1,120 @@ +.TH std::ranges::reverse_copy,std::ranges::reverse_copy_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::reverse_copy,std::ranges::reverse_copy_result \- std::ranges::reverse_copy,std::ranges::reverse_copy_result + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for S, + + std::weakly_incrementable O > (since + requires std::indirectly_copyable \fB(1)\fP C++20) + constexpr reverse_copy_result + + reverse_copy( I first, S last, O result ); + template< ranges::bidirectional_range R, std::weakly_incrementable + O > + (since + requires std::indirectly_copyable, O> \fB(2)\fP C++20) + constexpr reverse_copy_result, O> + + reverse_copy( R&& r, O result ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using reverse_copy_result = ranges::in_out_result; C++20) + + 1) Copies the elements from the source range [first, last) to the destination range + [result, result + N), where N is ranges::distance(first, last), in such a way that + the elements in the new range are in reverse order. Behaves as if by executing the + assignment *(result + N - 1 - i) = *(first + i) once for each integer i in [0, N). + The behavior is undefined if the source and destination ranges overlap. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to copy + r - the range of elements to copy + result - the beginning of the destination range. + +.SH Return value + + {last, result + N}. + +.SH Complexity + + Exactly N assignments. + +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the both iterator + types model contiguous_iterator and have the same value type, and the value type is + TriviallyCopyable. + +.SH Possible implementation + + See also the implementations in MSVC STL and libstdc++. + + struct reverse_copy_fn + { + template S, + std::weakly_incrementable O> + requires std::indirectly_copyable + constexpr ranges::reverse_copy_result + operator()(I first, S last, O result) const + { + auto ret = ranges::next(first, last); + for (; last != first; *result = *--last, ++result); + return {std::move(ret), std::move(result)}; + } + + template + requires std::indirectly_copyable, O> + constexpr ranges::reverse_copy_result, O> + operator()(R&& r, O result) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result)); + } + }; + + inline constexpr reverse_copy_fn reverse_copy {}; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string x {"12345"}, y(x.size(), ' '); + std::cout << x << " → "; + std::ranges::reverse_copy(x.begin(), x.end(), y.begin()); + std::cout << y << " → "; + std::ranges::reverse_copy(y, x.begin()); + std::cout << x << '\\n'; + } + +.SH Output: + + 12345 → 54321 → 12345 + +.SH See also + + ranges::reverse reverses the order of elements in a range + (C++20) (niebloid) + reverse_copy creates a copy of a range that is reversed + \fI(function template)\fP diff --git a/man/std::ranges::rotate.3 b/man/std::ranges::rotate.3 new file mode 100644 index 000000000..5696d266f --- /dev/null +++ b/man/std::ranges::rotate.3 @@ -0,0 +1,234 @@ +.TH std::ranges::rotate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::rotate \- std::ranges::rotate + +.SH Synopsis + Defined in header + Call signature + template< std::permutable I, std::sentinel_for S > + + constexpr ranges::subrange \fB(1)\fP \fI(since C++20)\fP + + rotate( I first, I middle, S last ); + template< ranges::forward_range R > + + requires std::permutable> \fB(2)\fP \fI(since C++20)\fP + constexpr ranges::borrowed_subrange_t + + rotate( R&& r, ranges::iterator_t middle ); + + 1) Performs a left rotation on a range of elements. Specifically, ranges::rotate + swaps the elements in the range [first, last) in such a way that the element *middle + becomes the first element of the new range and *(middle - 1) becomes the last + element. + The behavior is undefined if [first, last) is not a valid range or middle is not in + [first, last). + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to rotate + r - the range of elements to rotate + middle - the iterator to the element that should appear at the beginning of the + rotated range + +.SH Return value + + {new_first, last}, where new_first compares equal to ranges::next(first, + ranges::distance(middle, last)) and designates a new location of the element pointed + by first. + +.SH Complexity + + Linear at worst: ranges::distance(first, last) swaps. + +.SH Notes + + ranges::rotate has better efficiency on common implementations if I models + bidirectional_iterator or (better) random_access_iterator. + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + models contiguous_iterator and swapping its value type calls neither non-trivial + special member function nor ADL-found swap. + +.SH Possible implementation + + See also the implementations in libstdc++ and MSVC STL. + + struct rotate_fn + { + template S> + constexpr ranges::subrange + operator()(I first, I middle, S last) const + { + if (first == middle) + { + auto last_it = ranges::next(first, last); + return {last_it, last_it}; + } + if (middle == last) + return {std::move(first), std::move(middle)}; + + if constexpr (std::bidirectional_iterator) + { + ranges::reverse(first, middle); + auto last_it = ranges::next(first, last); + ranges::reverse(middle, last_it); + + if constexpr (std::random_access_iterator) + { + ranges::reverse(first, last_it); + return {first + (last_it - middle), std::move(last_it)}; + } + else + { + auto mid_last = last_it; + do + { + ranges::iter_swap(first, --mid_last); + ++first; + } + while (first != middle && mid_last != middle); + ranges::reverse(first, mid_last); + + if (first == middle) + return {std::move(mid_last), std::move(last_it)}; + else + return {std::move(first), std::move(last_it)}; + } + } + else + { // I is merely a forward_iterator + auto next_it = middle; + do + { // rotate the first cycle + ranges::iter_swap(first, next_it); + ++first; + ++next_it; + if (first == middle) + middle = next_it; + } + while (next_it != last); + + auto new_first = first; + while (middle != last) + { // rotate subsequent cycles + next_it = middle; + do + { + ranges::iter_swap(first, next_it); + ++first; + ++next_it; + if (first == middle) + middle = next_it; + } + while (next_it != last); + } + + return {std::move(new_first), std::move(middle)}; + } + } + + template + requires std::permutable> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, ranges::iterator_t middle) const + { + return (*this)(ranges::begin(r), std::move(middle), ranges::end(r)); + } + }; + + inline constexpr rotate_fn rotate {}; + +.SH Example + + ranges::rotate is a common building block in many algorithms. This example + demonstrates insertion sort. + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string s(16, ' '); + + for (int k {}; k != 5; ++k) + { + std::iota(s.begin(), s.end(), 'A'); + std::ranges::rotate(s, s.begin() + k); + std::cout << "Rotate left (" << k << "): " << s << '\\n'; + } + std::cout << '\\n'; + + for (int k {}; k != 5; ++k) + { + std::iota(s.begin(), s.end(), 'A'); + std::ranges::rotate(s, s.end() - k); + std::cout << "Rotate right (" << k << "): " << s << '\\n'; + } + + std::cout << "\\nInsertion sort using `rotate`, step-by-step:\\n"; + + s = {'2', '4', '2', '0', '5', '9', '7', '3', '7', '1'}; + + for (auto i = s.begin(); i != s.end(); ++i) + { + std::cout << "i = " << std::ranges::distance(s.begin(), i) << ": "; + std::ranges::rotate(std::ranges::upper_bound(s.begin(), i, *i), i, i + 1); + std::cout << s << '\\n'; + } + std::cout << (std::ranges::is_sorted(s) ? "Sorted!" : "Not sorted.") << '\\n'; + } + +.SH Output: + + Rotate left \fB(0)\fP: ABCDEFGHIJKLMNOP + Rotate left \fB(1)\fP: BCDEFGHIJKLMNOPA + Rotate left \fB(2)\fP: CDEFGHIJKLMNOPAB + Rotate left \fB(3)\fP: DEFGHIJKLMNOPABC + Rotate left \fB(4)\fP: EFGHIJKLMNOPABCD + + Rotate right \fB(0)\fP: ABCDEFGHIJKLMNOP + Rotate right \fB(1)\fP: PABCDEFGHIJKLMNO + Rotate right \fB(2)\fP: OPABCDEFGHIJKLMN + Rotate right \fB(3)\fP: NOPABCDEFGHIJKLM + Rotate right \fB(4)\fP: MNOPABCDEFGHIJKL + + Insertion sort using `rotate`, step-by-step: + i = 0: 2420597371 + i = 1: 2420597371 + i = 2: 2240597371 + i = 3: 0224597371 + i = 4: 0224597371 + i = 5: 0224597371 + i = 6: 0224579371 + i = 7: 0223457971 + i = 8: 0223457791 + i = 9: 0122345779 + Sorted! + +.SH See also + + ranges::rotate_copy copies and rotate a range of elements + (C++20) (niebloid) + ranges::reverse reverses the order of elements in a range + (C++20) (niebloid) + rotate rotates the order of elements in a range + \fI(function template)\fP diff --git a/man/std::ranges::rotate_copy,std::ranges::rotate_copy_result.3 b/man/std::ranges::rotate_copy,std::ranges::rotate_copy_result.3 new file mode 100644 index 000000000..d67a7d37e --- /dev/null +++ b/man/std::ranges::rotate_copy,std::ranges::rotate_copy_result.3 @@ -0,0 +1,136 @@ +.TH std::ranges::rotate_copy,std::ranges::rotate_copy_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::rotate_copy,std::ranges::rotate_copy_result \- std::ranges::rotate_copy,std::ranges::rotate_copy_result + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + std::weakly_incrementable O > + requires std::indirectly_copyable \fB(1)\fP \fI(since C++20)\fP + constexpr rotate_copy_result + + rotate_copy( I first, I middle, S last, O result ); + template< ranges::forward_range R, std::weakly_incrementable O > + + requires std::indirectly_copyable, O> \fB(2)\fP \fI(since C++20)\fP + constexpr rotate_copy_result, O> + + rotate_copy( R&& r, ranges::iterator_t middle, O result ); +.SH Helper types + template< class I, class O > \fB(3)\fP \fI(since C++20)\fP + using rotate_copy_result = in_out_result; + + 1) Copies the elements from the source range [first, last), to the destination range + beginning at result in such a way, that the element *middle becomes the first + element of the destination range and *(middle - 1) becomes the last element. The + result is that the destination range contains a left rotated copy of the source + range. + The behavior is undefined if either [first, middle) or [middle, last) is not a valid + range, or the source and destination ranges overlap. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the source range of elements to copy from + r - the source range of elements to copy from + middle - the iterator to the element that should appear at the beginning of the + destination range + result - beginning of the destination range + +.SH Return value + + {last, result + N}, where N = ranges::distance(first, last). + +.SH Complexity + + Linear: exactly N assignments. + +.SH Notes + + If the value type is TriviallyCopyable and the iterator types satisfy + contiguous_iterator, implementations of ranges::rotate_copy usually avoid multiple + assignments by using a "bulk copy" function such as std::memmove. + +.SH Possible implementation + + See also the implementations in libstdc++ and MSVC STL. + +struct rotate_copy_fn +{ + template S, std::weakly_incrementable O> + requires std::indirectly_copyable + constexpr ranges::rotate_copy_result + operator()(I first, I middle, S last, O result) const + { + auto c1 {ranges::copy(middle, std::move(last), std::move(result))}; + auto c2 {ranges::copy(std::move(first), std::move(middle), std::move(c1.out))}; + return {std::move(c1.in), std::move(c2.out)}; + } + + template + requires std::indirectly_copyable, O> + constexpr ranges::rotate_copy_result, O> + operator()(R&& r, ranges::iterator_t middle, O result) const + { + return (*this)(ranges::begin(r), std::move(middle), + ranges::end(r), std::move(result)); + } +}; + +inline constexpr rotate_copy_fn rotate_copy {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector src {1, 2, 3, 4, 5}; + std::vector dest(src.size()); + auto pivot = std::ranges::find(src, 3); + + std::ranges::rotate_copy(src, pivot, dest.begin()); + for (int i : dest) + std::cout << i << ' '; + std::cout << '\\n'; + + // copy the rotation result directly to the std::cout + pivot = std::ranges::find(dest, 1); + std::ranges::rotate_copy(dest, pivot, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + +.SH Output: + + 3 4 5 1 2 + 1 2 3 4 5 + +.SH See also + + ranges::rotate rotates the order of elements in a range + (C++20) (niebloid) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + rotate_copy copies and rotate a range of elements + \fI(function template)\fP diff --git a/man/std::ranges::sample.3 b/man/std::ranges::sample.3 new file mode 100644 index 000000000..3f8295989 --- /dev/null +++ b/man/std::ranges::sample.3 @@ -0,0 +1,182 @@ +.TH std::ranges::sample 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::sample \- std::ranges::sample + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + + std::weakly_incrementable O, class Gen > + requires (std::forward_iterator || std::random_access_iterator) && + std::indirectly_copyable && \fB(1)\fP (since + C++20) + std::uniform_random_bit_generator> + + O sample( I first, S last, O out, std::iter_difference_t n, Gen&& gen + ); + template< ranges::input_range R, std::weakly_incrementable O, class Gen + > + + requires (ranges::forward_range || std::random_access_iterator) && (since + std::indirectly_copyable, O> && \fB(2)\fP C++20) + + std::uniform_random_bit_generator> + + O sample( R&& r, O out, ranges::range_difference_t n, Gen&& gen ); + + 1) Selects M = min(n, last - first) elements from the sequence [first, last) + (without replacement) such that each possible sample has equal probability of + appearance, and writes those selected elements into the range beginning at out. + The algorithm is stable (preserves the relative order of the selected elements) only + if I models std::forward_iterator. + The behavior is undefined if out is in [first, last). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first, and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the range from which to make the sampling (the population) + r - the range from which to make the sampling (the population) + out - the output iterator where the samples are written + n - number of samples to take + gen - the random number generator used as the source of randomness + +.SH Return value + + An iterator equal to out + M, that is the end of the resulting sample range. + +.SH Complexity + + Linear: 𝓞(last - first). + +.SH Notes + + This function may implement selection sampling or reservoir sampling. + +.SH Possible implementation + + struct sample_fn + { + template S, + std::weakly_incrementable O, class Gen> + requires (std::forward_iterator or + std::random_access_iterator) && + std::indirectly_copyable && + std::uniform_random_bit_generator> + O operator()(I first, S last, O out, std::iter_difference_t n, Gen&& gen) const + { + using diff_t = std::iter_difference_t; + using distrib_t = std::uniform_int_distribution; + using param_t = typename distrib_t::param_type; + distrib_t D{}; + + if constexpr (std::forward_iterator) + { + // this branch preserves "stability" of the sample elements + auto rest{ranges::distance(first, last)}; + for (n = ranges::min(n, rest); n != 0; ++first) + if (D(gen, param_t(0, --rest)) < n) + { + *out++ = *first; + --n; + } + return out; + } + else + { + // O is a random_access_iterator + diff_t sample_size{}; + // copy [first, first + M) elements to "random access" output + for (; first != last && sample_size != n; ++first) + out[sample_size++] = *first; + // overwrite some of the copied elements with randomly selected ones + for (auto pop_size{sample_size}; first != last; ++first, ++pop_size) + { + const auto i{D(gen, param_t{0, pop_size})}; + if (i < n) + out[i] = *first; + } + return out + sample_size; + } + } + + template + requires (ranges::forward_range or std::random_access_iterator) && + std::indirectly_copyable, O> && + std::uniform_random_bit_generator> + O operator()(R&& r, O out, ranges::range_difference_t n, Gen&& gen) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(out), n, + std::forward(gen)); + } + }; + + inline constexpr sample_fn sample {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(auto const& rem, auto const& v) + { + std::cout << rem << " = [" << std::size(v) << "] { "; + for (auto const& e : v) + std::cout << e << ' '; + std::cout << "}\\n"; + } + + int main() + { + const auto in = {1, 2, 3, 4, 5, 6}; + print("in", in); + + std::vector out; + const int max = in.size() + 2; + auto gen = std::mt19937{std::random_device{}()}; + + for (int n{}; n != max; ++n) + { + out.clear(); + std::ranges::sample(in, std::back_inserter(out), n, gen); + std::cout << "n = " << n; + print(", out", out); + } + } + +.SH Possible output: + + in = [6] { 1 2 3 4 5 6 } + n = 0, out = [0] { } + n = 1, out = [1] { 5 } + n = 2, out = [2] { 4 5 } + n = 3, out = [3] { 2 3 5 } + n = 4, out = [4] { 2 4 5 6 } + n = 5, out = [5] { 1 2 3 5 6 } + n = 6, out = [6] { 1 2 3 4 5 6 } + n = 7, out = [6] { 1 2 3 4 5 6 } + +.SH See also + + ranges::shuffle randomly re-orders elements in a range + (C++20) (niebloid) + sample selects N random elements from a sequence + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::search.3 b/man/std::ranges::search.3 new file mode 100644 index 000000000..990b74838 --- /dev/null +++ b/man/std::ranges::search.3 @@ -0,0 +1,225 @@ +.TH std::ranges::search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::search \- std::ranges::search + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I1, std::sentinel_for S1, + + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, (since + class Proj2 = std::identity > \fB(1)\fP C++20) + requires std::indirectly_comparable + constexpr ranges::subrange + search( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::forward_range R1, ranges::forward_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, + class Proj2 = std::identity> + requires std::indirectly_comparable, \fB(2)\fP (since + ranges::iterator_t, Pred, Proj1, C++20) + Proj2> + constexpr ranges::borrowed_subrange_t + + search( R1&& r1, R2&& r2, Pred pred = {}, Proj1 proj1 = {}, Proj2 + proj2 = {} ); + + 1) Searches for the first occurrence of the sequence of elements [first2, last2) in + the range [first1, last1). Elements are compared using binary predicate pred after + being projected with proj2 and proj1, respectively. + 2) Same as \fB(1)\fP, but uses r1 as the first source range and r2 as the second source + range, as if using ranges::begin(r1) as first1, ranges::end(r1) as last1, + ranges::begin(r2) as first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the range of elements to examine (aka haystack) + first2, last2 - the range of elements to search for (aka needle) + r1 - the range of elements to examine (aka haystack) + r2 - the range of elements to search for (aka needle) + pred - binary predicate to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + 1) Returns a ranges::subrange value that is the first occurrence of the sequence + [first2, last2) (aka needle) in the range [first1, last1) (aka haystack), after + application of the projections proj1 and proj2 to the elements of both sequences + respectively with consequencing application of the binary predicate pred to compare + projected elements. + + If no such occurrence is found, ranges::subrange{last1, last1} is returned. + + If the range to search for (aka needle) is empty, that is first2 == last2, then the + ranges::subrange{first1, first1} is returned. + 2) Same as \fB(1)\fP but the return type is ranges::borrowed_subrange_t. + +.SH Complexity + + At most S * N applications of the corresponding predicate and each projection, where + \fB(1)\fP S = ranges::distance(first2, last2) and N = ranges::distance(first1, last1); + \fB(2)\fP S = ranges::distance(r2) and N = ranges::distance(r1). + +.SH Possible implementation + +struct search_fn +{ + template S1, + std::forward_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, + class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr ranges::subrange + operator()(I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (;; ++first1) + { + I1 it1 = first1; + for (I2 it2 = first2;; ++it1, ++it2) + { + if (it2 == last2) + return {first1, it1}; + if (it1 == last1) + return {it1, it1}; + if (!std::invoke(pred, std::invoke(proj1, *it1), std::invoke(proj2, *it2))) + break; + } + } + } + + template + requires std::indirectly_comparable, + ranges::iterator_t, Pred, Proj1, Proj2> + constexpr ranges::borrowed_subrange_t + operator()(R1&& r1, R2&& r2, Pred pred = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(pred), std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr search_fn search {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::literals; + + void print(int id, const auto& haystack, const auto& needle, const auto& found) + { + std::cout << id << ") search(\\"" << haystack << "\\", \\"" << needle << "\\"); "; + const auto first = std::distance(haystack.begin(), found.begin()); + const auto last = std::distance(haystack.begin(), found.end()); + if (found.empty()) + std::cout << "not found;"; + else + { + std::cout << "found: \\""; + for (const auto x : found) + std::cout << x; + std::cout << "\\";"; + } + std::cout << " subrange: {" << first << ", " << last << "}\\n"; + } + + int main() + { + constexpr auto haystack {"abcd abcd"sv}; + constexpr auto needle {"bcd"sv}; + + // the search uses iterator pairs begin()/end(): + constexpr auto found1 = std::ranges::search( + haystack.begin(), haystack.end(), + needle.begin(), needle.end()); + print(1, haystack, needle, found1); + + // the search uses ranges r1, r2: + constexpr auto found2 = std::ranges::search(haystack, needle); + print(2, haystack, needle, found2); + + // 'needle' range is empty: + constexpr auto none {""sv}; + constexpr auto found3 = std::ranges::search(haystack, none); + print(3, haystack, none, found3); + + // 'needle' will not be found: + constexpr auto awl {"efg"sv}; + constexpr auto found4 = std::ranges::search(haystack, awl); + print(4, haystack, awl, found4); + + // the search uses custom comparator and projections: + constexpr auto bodkin {"234"sv}; + auto found5 = std::ranges::search(haystack, bodkin, + [](const int x, const int y) { return x == y; }, // pred + [](const int x) { return std::toupper(x); }, // proj1 + [](const int y) { return y + 'A' - '1'; }); // proj2 + print(5, haystack, bodkin, found5); + } + +.SH Output: + + 1) search("abcd abcd", "bcd"); found: "bcd"; subrange: {1, 4} + 2) search("abcd abcd", "bcd"); found: "bcd"; subrange: {1, 4} + 3) search("abcd abcd", ""); not found; subrange: {0, 0} + 4) search("abcd abcd", "efg"); not found; subrange: {9, 9} + 5) search("abcd abcd", "234"); found: "bcd"; subrange: {1, 4} + +.SH See also + + ranges::adjacent_find finds the first two adjacent items that are equal (or + (C++20) satisfy a given predicate) + (niebloid) + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::find_end finds the last sequence of elements in a certain range + (C++20) (niebloid) + ranges::find_first_of searches for any one of a set of elements + (C++20) (niebloid) + ranges::contains + ranges::contains_subrange checks if the range contains the given element or subrange + (C++23) (niebloid) + (C++23) + ranges::includes returns true if one sequence is a subsequence of another + (C++20) (niebloid) + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) + ranges::search_n searches for a number consecutive copies of an element in + (C++20) a range + (niebloid) + search searches for a range of elements + \fI(function template)\fP diff --git a/man/std::ranges::search_n.3 b/man/std::ranges::search_n.3 new file mode 100644 index 000000000..cd318797a --- /dev/null +++ b/man/std::ranges::search_n.3 @@ -0,0 +1,262 @@ +.TH std::ranges::search_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::search_n \- std::ranges::search_n + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + class T, + + class Pred = ranges::equal_to, class Proj = + std::identity > (since + requires std::indirectly_comparable C++20) + constexpr ranges::subrange (until + search_n( I first, S last, std::iter_difference_t C++26) + count, + + const T& value, Pred pred = {}, Proj proj = {} + ); + template< std::forward_iterator I, std::sentinel_for S, + + class Pred = ranges::equal_to, class Proj = + std::identity, + class T = std::projected_value_t > + requires std::indirectly_comparable (since + constexpr ranges::subrange C++26) + search_n( I first, S last, std::iter_difference_t + count, + + const T& value, Pred pred = {}, Proj proj = {} + ); \fB(1)\fP + template< ranges::forward_range R, class T, + + class Pred = ranges::equal_to, class Proj = + std::identity > (since + requires std::indirectly_comparable C++20) + , const T*, Pred, Proj> (until + constexpr ranges::borrowed_subrange_t C++26) + search_n( R&& r, ranges::range_difference_t count, + + const T& value, Pred pred = {}, Proj proj = {} + ); + template< ranges::forward_range R, \fB(2)\fP + + class Pred = ranges::equal_to, class Proj = + std::identity, + class T = + std::projected_value_t, Proj> > (since + requires std::indirectly_comparable C++26) + , const T*, Pred, Proj> + constexpr ranges::borrowed_subrange_t + search_n( R&& r, ranges::range_difference_t count, + + const T& value, Pred pred = {}, Proj proj = {} + ); + + 1) Searches the range [first, last) for the first sequence of count elements whose + projected values are each equal to the given value according to the binary predicate + pred. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to examine (aka haystack) + r - the range of elements to examine (aka haystack) + count - the length of the sequence to search for + value - the value to search for (aka needle) + pred - the binary predicate that compares the projected elements with value + proj - the projection to apply to the elements of the range to examine + +.SH Return value + + 1) Returns std::ranges::subrange object that contains a pair of iterators in the + range [first, last) that designate the found subsequence. + + If no such subsequence is found, returns std::ranges::subrange{last, last}. + + If count <= 0, returns std::ranges::subrange{first, first}. + 2) Same as \fB(1)\fP but the return type is ranges::borrowed_subrange_t. + +.SH Complexity + + Linear: at most ranges::distance(first, last) applications of the predicate and the + projection. + +.SH Notes + + An implementation can improve efficiency of the search in average if the iterators + model std::random_access_iterator. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms + +.SH Possible implementation + + struct search_n_fn + { + template S, + class Pred = ranges::equal_to, class Proj = std::identity, + class T = std::projected_value_t> + requires std::indirectly_comparable + constexpr ranges::subrange + operator()(I first, S last, std::iter_difference_t count, + const T& value, Pred pred = {}, Proj proj = {}) const + { + if (count <= 0) + return {first, first}; + for (; first != last; ++first) + if (std::invoke(pred, std::invoke(proj, *first), value)) + { + I start = first; + std::iter_difference_t n{1}; + for (;;) + { + if (n++ == count) + return {start, std::next(first)}; // found + if (++first == last) + return {first, first}; // not found + if (!std::invoke(pred, std::invoke(proj, *first), value)) + break; // not equ to value + } + } + return {first, first}; + } + + template, Proj>> + requires std::indirectly_comparable, const T*, Pred, Proj> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, ranges::range_difference_t count, + const T& value, Pred pred = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::move(count), value, + std::move(pred), std::move(proj)); + } + }; + + inline constexpr search_n_fn search_n {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + static constexpr auto nums = {1, 2, 2, 3, 4, 1, 2, 2, 2, 1}; + constexpr int count{3}; + constexpr int value{2}; + typedef int count_t, value_t; + + constexpr auto result1 = ranges::search_n + ( + nums.begin(), nums.end(), count, value + ); + static_assert // found + ( + result1.size() == count && + std::distance(nums.begin(), result1.begin()) == 6 && + std::distance(nums.begin(), result1.end()) == 9 + ); + + constexpr auto result2 = ranges::search_n(nums, count, value); + static_assert // found + ( + result2.size() == count && + std::distance(nums.begin(), result2.begin()) == 6 && + std::distance(nums.begin(), result2.end()) == 9 + ); + + constexpr auto result3 = ranges::search_n(nums, count, value_t{5}); + static_assert // not found + ( + result3.size() == 0 && + result3.begin() == result3.end() && + result3.end() == nums.end() + ); + + constexpr auto result4 = ranges::search_n(nums, count_t{0}, value_t{1}); + static_assert // not found + ( + result4.size() == 0 && + result4.begin() == result4.end() && + result4.end() == nums.begin() + ); + + constexpr char symbol{'B'}; + auto to_ascii = [](const int z) -> char { return 'A' + z - 1; }; + auto is_equ = [](const char x, const char y) { return x == y; }; + + std::cout << "Find a sub-sequence " << std::string(count, symbol) << " in the "; + std::ranges::transform(nums, std::ostream_iterator(std::cout, ""), to_ascii); + std::cout << '\\n'; + + auto result5 = ranges::search_n(nums, count, symbol, is_equ, to_ascii); + if (not result5.empty()) + std::cout << "Found at position " + << ranges::distance(nums.begin(), result5.begin()) << '\\n'; + + std::vector> nums2{{4, 2}, {4, 2}, {1, 3}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto it = ranges::search_n(nums2, 2, {4, 2}); + #else + auto it = ranges::search_n(nums2, 2, std::complex{4, 2}); + #endif + assert(it.size() == 2); + } + +.SH Output: + + Find a sub-sequence BBB in the ABBCDABBBA + Found at position 6 + +.SH See also + + ranges::adjacent_find finds the first two adjacent items that are equal (or satisfy + (C++20) a given predicate) + (niebloid) + ranges::find + ranges::find_if + ranges::find_if_not finds the first element satisfying specific criteria + (C++20) (niebloid) + (C++20) + (C++20) + ranges::find_end finds the last sequence of elements in a certain range + (C++20) (niebloid) + ranges::find_first_of searches for any one of a set of elements + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of another + (C++20) (niebloid) + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) + ranges::search searches for a range of elements + (C++20) (niebloid) + searches a range for a number of consecutive copies of an + search_n element + \fI(function template)\fP diff --git a/man/std::ranges::set_difference,std::ranges::set_difference_result.3 b/man/std::ranges::set_difference,std::ranges::set_difference_result.3 new file mode 100644 index 000000000..f23e3af8b --- /dev/null +++ b/man/std::ranges::set_difference,std::ranges::set_difference_result.3 @@ -0,0 +1,217 @@ +.TH std::ranges::set_difference,std::ranges::set_difference_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::set_difference,std::ranges::set_difference_result \- std::ranges::set_difference,std::ranges::set_difference_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity > (since + requires std::mergeable \fB(1)\fP C++20) + constexpr set_difference_result + set_difference( I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::mergeable, (since + ranges::iterator_t, \fB(2)\fP C++20) + O, Comp, Proj1, Proj2> + constexpr set_difference_result, O> + set_difference( R1&& r1, R2&& r2, O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using set_difference_result = ranges::in_out_result; C++20) + + Copies the elements from the sorted input range [first1, last1) which are not found + in the sorted input range [first2, last2) to the output range beginning at result. + + The behavior is undefined if + + * the input ranges are not sorted with respect to comp and proj1 or proj2, + respectively, or + * the resulting range overlaps with either of the input ranges. + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r1 as the first range and r2 as the second range, as if + using ranges::begin(r1) as first1, ranges::end(r1) as last1, ranges::begin(r2) as + first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - iterator-sentinel pair denoting the first sorted input range + first2, last2 - iterator-sentinel pair denoting the second sorted input range + r1 - the first sorted input range + r2 - the second sorted input range + result - the beginning of the output range + comp - comparator to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + {last1, result_last}, where result_last is the end of the constructed range. + +.SH Complexity + + At most \\(\\scriptsize 2\\cdot(N_1+N_2)-1\\)2·(N + 1+N + 2)-1 comparisons and applications of each projection, where \\(\\scriptsize N_1\\)N + 1 and \\(\\scriptsize N_2\\)N + 2 are ranges::distance(first1, last1) and ranges::distance(first2, last2), + respectively. + +.SH Possible implementation + +struct set_difference_fn +{ + template S1, + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::mergeable + constexpr ranges::set_difference_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + while (!(first1 == last1 or first2 == last2)) + { + if (std::invoke(comp, std::invoke(proj1, *first1), std::invoke(proj2, *first2))) + { + *result = *first1; + ++first1; + ++result; + } + else if (std::invoke(comp, std::invoke(proj2, *first2), + std::invoke(proj1, *first1))) + ++first2; + else + { + ++first1; + ++first2; + } + } + return ranges::copy(std::move(first1), std::move(last1), std::move(result)); + } + + template + requires std::mergeable, ranges::iterator_t, + O, Comp, Proj1, Proj2> + constexpr ranges::set_difference_result, O> + operator()(R1&& r1, R2&& r2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(result), std::move(comp), + std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr set_difference_fn set_difference {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + auto print = [](const auto& v, std::string_view end = "") + { + std::cout << "{ "; + for (auto n{v.size()}; auto i : v) + std::cout << i << (--n ? ", " : " "); + std::cout << "} " << end; + }; + + struct Order // a struct with some very interesting data + { + int order_id{}; + + friend std::ostream& operator<<(std::ostream& os, const Order& ord) + { + return os << '{' << ord.order_id << '}'; + } + }; + + int main() + { + const auto v1 = {1, 2, 5, 5, 5, 9}; + const auto v2 = {2, 5, 7}; + std::vector diff{}; + + std::ranges::set_difference(v1, v2, std::back_inserter(diff)); + print(v1, "∖ "); + print(v2, "= "); + print(diff, "\\n\\n"); + + // We want to know which orders "cut" between old and new states: + const std::vector old_orders{{1}, {2}, {5}, {9}}; + const std::vector new_orders{{2}, {5}, {7}}; + std::vector cut_orders(old_orders.size() + new_orders.size()); + + auto [old_orders_end, cut_orders_last] = + std::ranges::set_difference(old_orders, new_orders, + cut_orders.begin(), {}, + &Order::order_id, &Order::order_id); + assert(old_orders_end == old_orders.end()); + + std::cout << "old orders = "; + print(old_orders, "\\n"); + std::cout << "new orders = "; + print(new_orders, "\\n"); + std::cout << "cut orders = "; + print(cut_orders, "\\n"); + cut_orders.erase(cut_orders_last, end(cut_orders)); + std::cout << "cut orders = "; + print(cut_orders, "\\n"); + } + +.SH Output: + + { 1, 2, 5, 5, 5, 9 } ∖ { 2, 5, 7 } = { 1, 5, 5, 9 } + + old orders = { {1}, {2}, {5}, {9} } + new orders = { {2}, {5}, {7} } + cut orders = { {1}, {9}, {0}, {0}, {0}, {0}, {0} } + cut orders = { {1}, {9} } + +.SH See also + + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::set_intersection computes the intersection of two sets + (C++20) (niebloid) + ranges::set_symmetric_difference computes the symmetric difference between two sets + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of + (C++20) another + (niebloid) + set_difference computes the difference between two sets + \fI(function template)\fP diff --git a/man/std::ranges::set_intersection,std::ranges::set_intersection_result.3 b/man/std::ranges::set_intersection,std::ranges::set_intersection_result.3 new file mode 100644 index 000000000..2441cc39e --- /dev/null +++ b/man/std::ranges::set_intersection,std::ranges::set_intersection_result.3 @@ -0,0 +1,179 @@ +.TH std::ranges::set_intersection,std::ranges::set_intersection_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::set_intersection,std::ranges::set_intersection_result \- std::ranges::set_intersection,std::ranges::set_intersection_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity > (since + requires std::mergeable \fB(1)\fP C++20) + constexpr set_intersection_result + set_intersection( I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::mergeable, + ranges::iterator_t, \fB(2)\fP (since + O, Comp, Proj1, Proj2> C++20) + constexpr set_intersection_result, + ranges::borrowed_iterator_t, O> + set_intersection( R1&& r1, R2&& r2, O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I1, class I2, class O > \fB(3)\fP (since + using set_intersection_result = ranges::in_in_out_result; C++20) + + Constructs a sorted range beginning at result consisting of elements that are found + in both sorted input ranges [first1, last1) and [first2, last2). If some element is + found m times in [first1, last1) and n times in [first2, last2), the first min(m, n) + elements will be copied from the first range to result. The order of equivalent + elements is preserved. + + The behavior is undefined if + + * the input ranges are not sorted with respect to comp and proj1 or proj2, + respectively, or + * the resulting range overlaps with either of the input ranges. + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r1 as the first range and r2 as the second range, as if + using ranges::begin(r1) as first1, ranges::end(r1) as last1, ranges::begin(r2) as + first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - iterator-sentinel pair denoting the first input sorted range + first2, last2 - iterator-sentinel pair denoting the second input sorted range + r1 - the first sorted input range + r2 - the second sorted input range + result - the beginning of the output range + comp - comparison to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + {last1, last2, result_last}, where result_last is the end of the constructed range. + +.SH Complexity + + At most \\(\\scriptsize 2\\cdot(N_1+N_2)-1\\)2·(N + 1+N + 2)-1 comparisons and applications of each projection, where \\(\\scriptsize N_1\\)N + 1 and \\(\\scriptsize N_2\\)N + 2 are ranges::distance(first1, last1) and ranges::distance(first2, last2), + respectively. + +.SH Possible implementation + + struct set_intersection_fn + { + template S1, + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::mergeable + constexpr ranges::set_union_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + while (!(first1 == last1 or first2 == last2)) + { + if (std::invoke(comp, std::invoke(proj1, *first1), + std::invoke(proj2, *first2))) + ++first1; + else if (std::invoke(comp, std::invoke(proj2, *first2), + std::invoke(proj1, *first1))) + ++first2; + else + *result = *first1, ++first1, ++first2, ++result; + } + return {ranges::next(std::move(first1), std::move(last1)), + ranges::next(std::move(first2), std::move(last2)), + std::move(result)}; + } + + template + requires std::mergeable, ranges::iterator_t, + O, Comp, Proj1, Proj2> + constexpr ranges::set_intersection_result, + ranges::borrowed_iterator_t, O> + operator()(R1&& r1, R2&& r2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(result), std::move(comp), + std::move(proj1), std::move(proj2)); + } + }; + + inline constexpr set_intersection_fn set_intersection {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(const auto& v, const auto& rem) + { + std::cout << "{ "; + for (const auto& e : v) + std::cout << e << ' '; + std::cout << '}' << rem; + } + + int main() + { + const auto in1 = {1, 2, 2, 3, 4, 5, 6}; + const auto in2 = {2, 2, 3, 3, 5, 7}; + std::vector out {}; + + std::ranges::set_intersection(in1, in2, std::back_inserter(out)); + + print(in1, " ∩ "), print(in2, " = "), print(out, "\\n"); + } + +.SH Output: + + { 1 2 2 3 4 5 6 } ∩ { 2 2 3 3 5 7 } = { 2 2 3 5 } + +.SH See also + + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) + ranges::set_symmetric_difference computes the symmetric difference between two sets + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of + (C++20) another + (niebloid) + set_intersection computes the intersection of two sets + \fI(function template)\fP diff --git a/man/std::ranges::set_symmetric_difference,std::ranges::set_symmetric_difference_result.3 b/man/std::ranges::set_symmetric_difference,std::ranges::set_symmetric_difference_result.3 new file mode 100644 index 000000000..fc895e84e --- /dev/null +++ b/man/std::ranges::set_symmetric_difference,std::ranges::set_symmetric_difference_result.3 @@ -0,0 +1,201 @@ +.TH std::ranges::set_symmetric_difference,std::ranges::set_symmetric_difference_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::set_symmetric_difference,std::ranges::set_symmetric_difference_result \- std::ranges::set_symmetric_difference,std::ranges::set_symmetric_difference_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity > (since + requires std::mergeable \fB(1)\fP C++20) + constexpr set_symmetric_difference_result + set_symmetric_difference( I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::mergeable, ranges::iterator_t, + O, Comp, Proj1, Proj2> + constexpr \fB(2)\fP (since + set_symmetric_difference_result, C++20) + + ranges::borrowed_iterator_t, O> + set_symmetric_difference( R1&& r1, R2&& r2, O result, Comp comp = + {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I1, class I2, class O > (since + using set_symmetric_difference_result = ranges::in_in_out_result; + + Computes symmetric difference of two sorted ranges: the elements that are found in + either of the ranges, but not in both of them are copied to the range beginning at + result. The resulting range is also sorted. + + If some element is found m times in [first1, last1) and n times in [first2, last2), + it will be copied to result exactly │m - n│ times. If m > n, then the last m - n of + those elements are copied from [first1, last1), otherwise the last n - m elements + are copied from [first2, last2). The resulting range cannot overlap with either of + the input ranges. + + The behavior is undefined if + + * the input ranges are not sorted with respect to comp and proj1 or proj2, + respectively, or + * the resulting range overlaps with either of the input ranges. + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r1 as the first range and r2 as the second range, as if + using ranges::begin(r1) as first1, ranges::end(r1) as last1, ranges::begin(r2) as + first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - iterator-sentinel pair denoting the first input sorted range + first2, last2 - iterator-sentinel pair denoting the second input sorted range + r1 - the first sorted input range + r2 - the second sorted input range + result - the beginning of the output range + comp - comparison to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + {last1, last2, result_last}, where result_last is the end of the constructed range. + +.SH Complexity + + At most \\(\\scriptsize 2\\cdot(N_1+N_2)-1\\)2·(N + 1+N + 2)-1 comparisons and applications of each projection, where \\(\\scriptsize N_1\\)N + 1 and \\(\\scriptsize N_2\\)N + 2 are ranges::distance(first1, last1) and ranges::distance(first2, last2), + respectively. + +.SH Possible implementation + +struct set_symmetric_difference_fn +{ + template S1, + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::mergeable + constexpr ranges::set_symmetric_difference_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + while (!(first1 == last1 or first2 == last2)) + { + if (std::invoke(comp, std::invoke(proj1, *first1), std::invoke(proj2, *first2))) + { + *result = *first1; + ++first1; + ++result; + } + else if (std::invoke(comp, std::invoke(proj2, *first2), + std::invoke(proj1, *first1))) + { + *result = *first2; + ++first2; + ++result; + } + else + { + ++first1; + ++first2; + } + } + auto res1 {ranges::copy(std::move(first1), std::move(last1), std::move(result))}; + auto res2 {ranges::copy(std::move(first2), std::move(last2), std::move(res1.out))}; + return {std::move(res1.in), std::move(res2.in), std::move(res2.out)}; + } + + template + requires std::mergeable, ranges::iterator_t, + O, Comp, Proj1, Proj2> + constexpr ranges::set_symmetric_difference_result< + ranges::borrowed_iterator_t, ranges::borrowed_iterator_t, O> + operator()(R1&& r1, R2&& r2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(result), std::move(comp), + std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr set_symmetric_difference_fn set_symmetric_difference {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void visualize_this(const auto& v, int min = 1, int max = 9) + { + for (auto i {min}; i <= max; ++i) + { + std::ranges::binary_search(v, i) ? std::cout << i : std::cout << '.'; + std::cout << ' '; + } + std::cout << '\\n'; + } + + int main() + { + const auto in1 = {1, 3, 4, 6, 7, 9}; + const auto in2 = {1, 4, 5, 6, 9}; + + std::vector out {}; + + std::ranges::set_symmetric_difference(in1, in2, std::back_inserter(out)); + + visualize_this(in1); + visualize_this(in2); + visualize_this(out); + } + +.SH Output: + + 1 . 3 4 . 6 7 . 9 + 1 . . 4 5 6 . . 9 + . . 3 . 5 . 7 . . + +.SH See also + + ranges::set_union computes the union of two sets + (C++20) (niebloid) + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) + ranges::set_intersection computes the intersection of two sets + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of another + (C++20) (niebloid) + set_symmetric_difference computes the symmetric difference between two sets + \fI(function template)\fP diff --git a/man/std::ranges::set_union,std::ranges::set_union_result.3 b/man/std::ranges::set_union,std::ranges::set_union_result.3 new file mode 100644 index 000000000..046d9ba3b --- /dev/null +++ b/man/std::ranges::set_union,std::ranges::set_union_result.3 @@ -0,0 +1,224 @@ +.TH std::ranges::set_union,std::ranges::set_union_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::set_union,std::ranges::set_union_result \- std::ranges::set_union,std::ranges::set_union_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity + > \fB(1)\fP (since + requires std::mergeable C++20) + constexpr set_union_result + set_union( I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity + > + requires std::mergeable, (since + ranges::iterator_t, \fB(2)\fP C++20) + O, Comp, Proj1, Proj2> + constexpr set_union_result, + ranges::borrowed_iterator_t, O> + set_union( R1&& r1, R2&& r2, O result, Comp comp = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I1, class I2, class O > \fB(3)\fP (since + using set_union_result = ranges::in_in_out_result; C++20) + + Constructs a sorted union beginning at result consisting of the set of elements + present in one or both sorted input ranges [first1, last1) and [first2, last2). + + If some element is found m times in [first1, last1) and n times in [first2, last2), + then all m elements will be copied from [first1, last1) to result, preserving order, + and then exactly max(n - m, 0) elements will be copied from [first2, last2) to + result, also preserving order. + + The behavior is undefined if + + * the input ranges are not sorted with respect to comp and proj1 or proj2, + respectively, or + * the resulting range overlaps with either of the input ranges. + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r1 as the first range and r2 as the second range, as if + using ranges::begin(r1) as first1, ranges::end(r1) as last1, ranges::begin(r2) as + first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - iterator-sentinel pair denoting the first input sorted range + first2, last2 - iterator-sentinel pair denoting the second input sorted range + r1 - the first input sorted range + r2 - the second input sorted range + result - the beginning of the output range + comp - comparison to apply to the projected elements + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + {last1, last2, result_last}, where result_last is the end of the constructed range. + +.SH Complexity + + At most \\(\\scriptsize 2\\cdot(N_1+N_2)-1\\)2·(N + 1+N + 2)-1 comparisons and applications of each projection, where \\(\\scriptsize N_1\\)N + 1 and \\(\\scriptsize N_2\\)N + 2 are ranges::distance(first1, last1) and ranges::distance(first2, last2), + respectively. + +.SH Notes + + This algorithm performs a similar task as ranges::merge does. Both consume two + sorted input ranges and produce a sorted output with elements from both inputs. The + difference between these two algorithms is with handling values from both input + ranges which compare equivalent (see notes on LessThanComparable). If any equivalent + values appeared n times in the first range and m times in the second, ranges::merge + would output all n+m occurrences whereas ranges::set_union would output std::max(n, + m) ones only. So ranges::merge outputs exactly \\(\\scriptsize (N_1+N_2)\\)(N + 1+N + 2) values and ranges::set_union may produce less. + +.SH Possible implementation + +struct set_union_fn +{ + template S1, + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, class Comp = ranges::less, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::mergeable + constexpr ranges::set_union_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, + O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; !(first1 == last1 or first2 == last2); ++result) + { + if (std::invoke(comp, std::invoke(proj1, *first1), + std::invoke(proj2, *first2))) + { + *result = *first1; + ++first1; + } + else if (std::invoke(comp, std::invoke(proj2, *first2), + std::invoke(proj1, *first1))) + { + *result = *first2; + ++first2; + } + else + { + *result = *first1; + ++first1; + ++first2; + } + } + auto res1 = ranges::copy(std::move(first1), std::move(last1), std::move(result)); + auto res2 = ranges::copy(std::move(first2), std::move(last2), std::move(res1.out)); + return {std::move(res1.in), std::move(res2.in), std::move(res2.out)}; + } + + template + requires std::mergeable, ranges::iterator_t, + O, Comp, Proj1, Proj2> + constexpr ranges::set_union_result, + ranges::borrowed_iterator_t, O> + operator()(R1&& r1, R2&& r2, O result, Comp comp = {}, + Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(result), std::move(comp), + std::move(proj1), std::move(proj2)); + } +}; + +inline constexpr set_union_fn set_union {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(const auto& in1, const auto& in2, auto first, auto last) + { + std::cout << "{ "; + for (const auto& e : in1) + std::cout << e << ' '; + std::cout << "} ∪ { "; + for (const auto& e : in2) + std::cout << e << ' '; + std::cout << "} =\\n{ "; + while (!(first == last)) + std::cout << *first++ << ' '; + std::cout << "}\\n\\n"; + } + + int main() + { + std::vector in1, in2, out; + + in1 = {1, 2, 3, 4, 5}; + in2 = { 3, 4, 5, 6, 7}; + out.resize(in1.size() + in2.size()); + const auto ret = std::ranges::set_union(in1, in2, out.begin()); + print(in1, in2, out.begin(), ret.out); + + in1 = {1, 2, 3, 4, 5, 5, 5}; + in2 = { 3, 4, 5, 6, 7}; + out.clear(); + out.reserve(in1.size() + in2.size()); + std::ranges::set_union(in1, in2, std::back_inserter(out)); + print(in1, in2, out.cbegin(), out.cend()); + } + +.SH Output: + + { 1 2 3 4 5 } ∪ { 3 4 5 6 7 } = + { 1 2 3 4 5 6 7 } + + { 1 2 3 4 5 5 5 } ∪ { 3 4 5 6 7 } = + { 1 2 3 4 5 5 5 6 7 } + +.SH See also + + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) + ranges::set_intersection computes the intersection of two sets + (C++20) (niebloid) + ranges::set_symmetric_difference computes the symmetric difference between two sets + (C++20) (niebloid) + ranges::merge merges two sorted ranges + (C++20) (niebloid) + ranges::includes returns true if one sequence is a subsequence of + (C++20) another + (niebloid) + set_union computes the union of two sets + \fI(function template)\fP diff --git a/man/std::ranges::shift_left,std::ranges::shift_right.3 b/man/std::ranges::shift_left,std::ranges::shift_right.3 new file mode 100644 index 000000000..6673b248f --- /dev/null +++ b/man/std::ranges::shift_left,std::ranges::shift_right.3 @@ -0,0 +1,194 @@ +.TH std::ranges::shift_left,std::ranges::shift_right 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::shift_left,std::ranges::shift_right \- std::ranges::shift_left,std::ranges::shift_right + +.SH Synopsis + Defined in header + Call signature + template< std::permutable I, std::sentinel_for S > + + constexpr ranges::subrange \fB(1)\fP (since C++23) + + shift_left( I first, S last, std::iter_difference_t n ); + template< ranges::forward_range R > + + requires std::permutable> \fB(2)\fP (since C++23) + constexpr ranges::borrowed_subrange_t + + shift_left( R&& r, ranges::range_difference_t n ); + template< std::permutable I, std::sentinel_for S > + + constexpr ranges::subrange \fB(3)\fP (since C++23) + + shift_right( I first, S last, std::iter_difference_t n ); + template< ranges::forward_range R > + + requires std::permutable> \fB(4)\fP (since C++23) + constexpr ranges::borrowed_subrange_t + + shift_right( R&& r, ranges::range_difference_t n ); + + Shifts the elements in the range [first, last) or r by n positions. The behavior is + undefined if [first, last) is not a valid range. + + 1) Shifts the elements towards the beginning of the range: + * If n == 0 || n >= last - first, there are no effects. + * If n < 0, the behavior is undefined. + * Otherwise, for every integer i in [0, last - first - n), moves the element + originally at position first + n + i to position first + i. The moves are + performed in increasing order of i starting from 0. + 3) Shifts the elements towards the end of the range: + * If n == 0 || n >= last - first, there are no effects. + * If n < 0, the behavior is undefined. + * Otherwise, for every integer i in [0, last - first - n), moves the element + originally at position first + i to position first + n + i. If I models + bidirectional_iterator, then the moves are performed in decreasing order of i + starting from last - first - n - 1. + 2,4) Same as \fB(1)\fP or \fB(3)\fP respectively, but uses r as the range, as if using + ranges::begin(r) as first and ranges::end(r) as last. + + Elements that are in the original range but not the new range are left in a valid + but unspecified state. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the original range + last - the end of the original range + r - the range of elements to shift + n - the number of positions to shift + +.SH Return value + + 1,2) {first, /*NEW_LAST*/}, where NEW_LAST is the end of the resulting range and + equivalent to: + * first + (last - first - n), if n is less than last - first; + * first otherwise. + 3,4) {/*NEW_FIRST*/, last}, where NEW_FIRST is the beginning of the resulting range + and equivalent to: + * first + n, if n is less than last - first; + * last otherwise. + +.SH Complexity + + 1,2) At most ranges::distance(first, last) - n assignments. + 3,4) At most ranges::distance(first, last) - n assignment or swaps. + +.SH Notes + + ranges::shift_left / ranges::shift_right has better efficiency on common + implementations if I models bidirectional_iterator or (better) + random_access_iterator. + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + models contiguous_iterator and swapping its value type calls neither non-trivial + special member function nor ADL-found swap. + + Feature-test macro Value Std Feature + __cpp_lib_shift 202202L (C++23) std::ranges::shift_left and + std::ranges::shift_right + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct S + { + int value{0}; + bool specified_state{true}; + + S(int v = 0) : value{v} {} + S(S const& rhs) = default; + S(S&& rhs) { *this = std::move(rhs); } + S& operator=(S const& rhs) = default; + S& operator=(S&& rhs) + { + if (this != &rhs) + { + value = rhs.value; + specified_state = rhs.specified_state; + rhs.specified_state = false; + } + return *this; + } + }; + + template + std::ostream& operator<<(std::ostream& os, std::vector const& v) + { + for (const auto& s : v) + { + if constexpr (std::is_same_v) + s.specified_state ? os << s.value << ' ' : os << ". "; + else if constexpr (std::is_same_v) + os << (s.empty() ? "." : s) << ' '; + else + os << s << ' '; + } + return os; + } + + int main() + { + std::cout << std::left; + + std::vector a{1, 2, 3, 4, 5, 6, 7}; + std::vector b{1, 2, 3, 4, 5, 6, 7}; + std::vector c{"α", "β", "γ", "δ", "ε", "ζ", "η"}; + + std::cout << "vector \\tvector \\tvector\\n"; + std::cout << a << " " << b << " " << c << '\\n'; + + std::ranges::shift_left(a, 3); + std::ranges::shift_left(b, 3); + std::ranges::shift_left(c, 3); + std::cout << a << " " << b << " " << c << '\\n'; + + std::ranges::shift_right(a, 2); + std::ranges::shift_right(b, 2); + std::ranges::shift_right(c, 2); + std::cout << a << " " << b << " " << c << '\\n'; + + std::ranges::shift_left(a, 8); // has no effect: n >= last - first + std::ranges::shift_left(b, 8); // ditto + std::ranges::shift_left(c, 8); // ditto + std::cout << a << " " << b << " " << c << '\\n'; + + // std::ranges::shift_left(a, -3); // UB + } + +.SH Possible output: + + vector vector vector + 1 2 3 4 5 6 7 1 2 3 4 5 6 7 α β γ δ ε ζ η + 4 5 6 7 . . . 4 5 6 7 5 6 7 δ ε ζ η . . . + . . 4 5 6 7 . 4 5 4 5 6 7 5 . . δ ε ζ η . + . . 4 5 6 7 . 4 5 4 5 6 7 5 . . δ ε ζ η . + +.SH See also + + ranges::move moves a range of elements to a new location + (C++20) (niebloid) + ranges::move_backward moves a range of elements to a new location in backwards order + (C++20) (niebloid) + ranges::rotate rotates the order of elements in a range + (C++20) (niebloid) + shift_left shifts elements in a range + shift_right \fI(function template)\fP + (C++20) diff --git a/man/std::ranges::shuffle.3 b/man/std::ranges::shuffle.3 new file mode 100644 index 000000000..a2aece519 --- /dev/null +++ b/man/std::ranges::shuffle.3 @@ -0,0 +1,132 @@ +.TH std::ranges::shuffle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::shuffle \- std::ranges::shuffle + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, class + Gen > + (since + requires std::permutable && \fB(1)\fP C++20) + std::uniform_random_bit_generator> + + I shuffle( I first, S last, Gen&& gen ); + template< ranges::random_access_range R, class Gen > + + requires std::permutable> && (since + std::uniform_random_bit_generator> \fB(2)\fP C++20) + ranges::borrowed_iterator_t + + shuffle( R&& r, Gen&& gen ); + + 1) Reorders the elements in the given range [first, last) such that each possible + permutation of those elements has equal probability of appearance. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to shuffle randomly + r - the range of elements to shuffle randomly + gen - the random number generator + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Exactly (last - first) - 1 swaps. + +.SH Possible implementation + + struct shuffle_fn + { + template S, class Gen> + requires std::permutable && + std::uniform_random_bit_generator> + I operator()(I first, S last, Gen&& gen) const + { + using diff_t = std::iter_difference_t; + using distr_t = std::uniform_int_distribution; + using param_t = typename distr_t::param_type; + distr_t D; + const auto n {last - first}; + for (diff_t i {1}; i < n; ++i) + ranges::iter_swap(first + i, first + D(gen, param_t(0, i))); + return ranges::next(first, last); + } + + template + requires std::permutable> && + std::uniform_random_bit_generator> + ranges::borrowed_iterator_t operator()(R&& r, Gen&& gen) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::forward(gen)); + } + }; + + inline constexpr shuffle_fn shuffle {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(const auto& a) + { + for (const auto e : a) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + std::array a {'A', 'B', 'C', 'D', 'E', 'F'}; + print(a); + + std::random_device rd; + std::mt19937 gen {rd()}; + + for (int i {}; i != 3; ++i) + { + std::ranges::shuffle(a, gen); + print(a); + } + } + +.SH Possible output: + + A B C D E F + F E A C D B + E C B F A D + B A E C F D + +.SH See also + + ranges::next_permutation generates the next greater lexicographic permutation of a + (C++20) range of elements + (niebloid) + ranges::prev_permutation generates the next smaller lexicographic permutation of a + (C++20) range of elements + (niebloid) + random_shuffle + shuffle randomly re-orders elements in a range + \fI(until C++17)\fP \fI(function template)\fP + \fI(C++11)\fP diff --git a/man/std::ranges::size.3 b/man/std::ranges::size.3 new file mode 100644 index 000000000..fd6433fdf --- /dev/null +++ b/man/std::ranges::size.3 @@ -0,0 +1,118 @@ +.TH std::ranges::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::size \- std::ranges::size + +.SH Synopsis + Defined in header + Defined in header + inline namespace /* unspecified */ { + \fI(since C++20)\fP + inline constexpr auto size = /* unspecified */; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr auto size( T&& t ); + + Calculates the number of elements in t in constant time. + + A call to ranges::size is expression-equivalent to: + + 1. decay-copy(std::extent_v) + (until C++23) + auto(std::extent_v) + (since C++23), if T is an array type with a known bound. + 2. Otherwise, + decay-copy(t.size()) + (until C++23) + auto(t.size()) + (since C++23), if ranges::disable_sized_range> is false, and + that expression is valid and has an integer-like type. + 3. Otherwise, + decay-copy(size(t)) + (until C++23) + auto(size(t)) + (since C++23), if ranges::disable_sized_range> is false, and + the converted expression is valid and has an integer-like type, where the + meaning of size is established as if by performing argument-dependent lookup + only. + 4. Otherwise, /* to-unsigned-like */(ranges::end(t) - ranges::begin(t)), if T + models ranges::forward_range and ranges::sentinel_t models + std::sized_sentinel_for>, + + where /* to-unsigned-like */ denotes an explicit conversion to an + unsigned-integer-like type. + + In all other cases, a call to ranges::size is ill-formed, which can result in + substitution failure when ranges::size(t) appears in the immediate context of a + template instantiation. + +.SH Notes + + Whenever ranges::size(e) is valid for an expression e, the return type is + integer-like. + + The C++20 standard requires that if the underlying size function call returns a + prvalue, the return value is move-constructed from the materialized temporary + object. All implementations directly return the prvalue instead. The requirement is + corrected by the post-C++20 proposal P0849R8 to match the implementations. + + The expression ranges::distance(e) can also be used to determine the size of a range + e. Unlike ranges::size(e), ranges::distance(e) works even if e is an unsized range, + at the cost of having linear complexity in that case. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto v = std::vector{}; + std::cout << "ranges::size(v) == " << std::ranges::size(v) << '\\n'; + + auto il = {7}; // std::initializer_list + std::cout << "ranges::size(il) == " << std::ranges::size(il) << '\\n'; + + int array[]{4, 5}; // array has a known bound + std::cout << "ranges::size(array) == " << std::ranges::size(array) << '\\n'; + + static_assert(std::is_signed_v == false); + } + +.SH Output: + + ranges::size(v) == 0 + ranges::size(il) == 1 + ranges::size(array) == 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2602R2 C++20 there's machinery to prohibit certain removed such machinery + non-member size found by ADL + +.SH See also + + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) + ranges::sized_range specifies that a range knows its size in constant time + (C++20) (concept) + ranges::distance returns the distance between an iterator and a sentinel, or + (C++20) between the beginning and end of a range + (niebloid) + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::ranges::sized_range,std::ranges::disable_sized_range.3 b/man/std::ranges::sized_range,std::ranges::disable_sized_range.3 new file mode 100644 index 000000000..357f3b6bd --- /dev/null +++ b/man/std::ranges::sized_range,std::ranges::disable_sized_range.3 @@ -0,0 +1,56 @@ +.TH std::ranges::sized_range,std::ranges::disable_sized_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::sized_range,std::ranges::disable_sized_range \- std::ranges::sized_range,std::ranges::disable_sized_range + +.SH Synopsis + Defined in header + template< class T > + + concept sized_range = ranges::range && + requires(T& t) { \fB(1)\fP \fI(since C++20)\fP + ranges::size(t); + + }; + template< class > \fB(2)\fP \fI(since C++20)\fP + inline constexpr bool disable_sized_range = false; + + 1) The sized_range concept specifies the requirements of a range type that knows its + size in constant time with the size function. + 2) disable_sized_range exists to allow use of range types that provide a size + function (either as a member or as a non-member) but do not in fact model + sized_range. Users may specialize disable_sized_range for cv-unqualified + program-defined types. Such specializations shall be usable in constant expressions + and have type const bool. + +.SH Notes + + disable_sized_range cannot be used to opt-out a range whose iterator and sentinel + satisfy sized_sentinel_for; std::disable_sized_sentinel_for must be used instead. + + disable_sized_range cannot be specialized for array types or reference types. + +.SH Example + + +// Run this code + + #include + #include + #include + + static_assert + ( + std::ranges::sized_range> and + not std::ranges::sized_range> + ); + + int main() {} + +.SH See also + + ranges::random_access_range specifies a range whose iterator type satisfies + (C++20) random_access_iterator + (concept) + ranges::contiguous_range specifies a range whose iterator type satisfies + (C++20) contiguous_iterator + (concept) diff --git a/man/std::ranges::slide_view::begin.3 b/man/std::ranges::slide_view::begin.3 new file mode 100644 index 000000000..4aa965063 --- /dev/null +++ b/man/std::ranges::slide_view::begin.3 @@ -0,0 +1,67 @@ +.TH std::ranges::slide_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::begin \- std::ranges::slide_view::begin + +.SH Synopsis + constexpr auto begin() + requires (!(__simple_view && __slide_caches_nothing)); + constexpr auto begin() const \fB(2)\fP (since C++23) + requires __slide_caches_nothing; + + Returns an iterator to the first element of the slide_view. + + 1) If V models __slide_caches_first, equivalent to: + + return iterator( + ranges::begin(base_), + ranges::next(ranges::begin(base_), n_ - 1, ranges::end(base_)), + n_ + ); + + Otherwise, equivalent to: return iterator(ranges::begin(base_), n_);. + If V models __slide_caches_first this function caches the result within the + slide_view::cached_begin_ for use on subsequent calls. This is necessary to provide + the amortized constant-time complexity required by the range. + 2) Equivalent to: return iterator(ranges::begin(base_), n_);. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the first element of slide_view, which points to the n_-sized + subrange of the possibly const-qualified underlying view type – V for overload \fB(1)\fP + or const V for overload \fB(2)\fP. + +.SH Example + + +// Run this code + + #include + #include + #include + using namespace std::literals; + + int main() + { + static constexpr auto source = {"∀x"sv, "∃y"sv, "ε"sv, "δ"sv}; + auto view{std::ranges::slide_view(source, 2)}; + const auto subrange{*(view.begin())}; + for (std::string_view const s : subrange) + std::cout << s << ' '; + std::cout << '\\n'; + } + +.SH Output: + + ∀x ∃y + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + operator== compares a sentinel with an iterator returned from slide_view::begin + (C++23) \fI(function)\fP diff --git a/man/std::ranges::slide_view::end.3 b/man/std::ranges::slide_view::end.3 new file mode 100644 index 000000000..455deab32 --- /dev/null +++ b/man/std::ranges::slide_view::end.3 @@ -0,0 +1,69 @@ +.TH std::ranges::slide_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::end \- std::ranges::slide_view::end + +.SH Synopsis + constexpr auto end() + requires (!(__simple_view && __slide_caches_nothing)); + constexpr auto end() const \fB(2)\fP (since C++23) + requires __slide_caches_nothing; + + Returns a sentinel or an iterator representing the end of the slide_view. + + 1) Let base_ and n_ be the underlying data members. Equivalent to: + * If V models __slide_caches_nothing, return iterator(ranges::begin(base_) + + ranges::range_difference_t(size()), n_);. + * Otherwise, if V models __slide_caches_last, return + iterator(ranges::prev(ranges::end(base_), n_ - 1, ranges::begin(base_)), + n_);. + * Otherwise, if V models common_range, return iterator(ranges::end(base_), + ranges::end(base_), n_);. + * Otherwise, return sentinel(ranges::end(base_));. + If V models __slide_caches_last, this function caches the result within the + slide_view::cached_end_ for use on subsequent calls. This is necessary to provide + the amortized constant-time complexity required by the range. + 2) Equivalent to begin() + ranges::range_difference_t(size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A sentinel or an iterator representing the end of the slide_view. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + static constexpr auto source = {'A', 'B', 'C', 'D'}; + + for (const auto subrange: source | std::views::slide(3)) + { + std::cout << "[ "; + for (auto it = subrange.begin(); it != subrange.end(); ++it) + std::cout << *it << ' '; + std::cout << "]\\n"; + } + } + +.SH Output: + + [ A B C ] + [ B C D ] + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::slide_view::iterator.3 b/man/std::ranges::slide_view::iterator.3 new file mode 100644 index 000000000..0ad3e02bc --- /dev/null +++ b/man/std::ranges::slide_view::iterator.3 @@ -0,0 +1,87 @@ +.TH std::ranges::slide_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::iterator \- std::ranges::slide_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of slide_view::begin, and of slide_view::end when the underlying + view V is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + iterator_category std::input_iterator_tag + * std::random_access_iterator_tag, if Base models + random_access_range. Otherwise, + iterator_concept * std::bidirectional_iterator_tag, if Base models + bidirectional_range. Otherwise, + * std::forward_iterator_tag. + value_type decltype(views::counted(current_, n_)) + difference_type ranges::range_difference_t + + Data members + + Member type Definition + ranges::iterator_t, holds an iterator to the first + current_ (private) underlying element of the current window in slide_view + (exposition-only member object*) + ranges::iterator_t, holds an iterator to the one-past-end + last_ele_ (private) underlying element of the current window in slide_view. Present + (optional) only if Base models /*slide-caches-first*/. + (exposition-only member object*) + ranges::range_difference_t, holds the window width of + n_ (private) slide_view. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterators + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.29.3 Class template slide_view::iterator [range.slide.iterator] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::iterator::iterator.3 b/man/std::ranges::slide_view::iterator::iterator.3 new file mode 100644 index 000000000..023a92a67 --- /dev/null +++ b/man/std::ranges::slide_view::iterator::iterator.3 @@ -0,0 +1,67 @@ +.TH std::ranges::slide_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::iterator::iterator \- std::ranges::slide_view::iterator::iterator + +.SH Synopsis + /*iterator*/(); \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + ranges::iterator_t> + private: + + constexpr /*iterator*/( ranges::iterator_t current, \fB(3)\fP (exposition only*) + ranges::range_difference_t n ) + + requires (!/*slide-caches-first*/); + private: + + constexpr /*iterator*/( ranges::iterator_t current, + ranges::iterator_t last_ele, \fB(4)\fP (exposition only*) + ranges::range_difference_t n ) + + requires /*slide-caches-first*/; + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying data members: + * current_ with ranges::iterator_t(), + * last_ele_ with ranges::iterator_t() (note that this member may not be + present), + * n_ with 0. + 2) Conversion from /*iterator*/ to /*iterator*/. Initializes the + underlying data members: + * current_ with std::move(i.current_), + * n_ with i.n_. + Note that /*iterator*/ can only be formed when Base models + /*slide-caches-nothing*/, in which case last_ele_ is not present. + 3) A private constructor which is used by ranges::slide_view::begin and + ranges::slide_view::end. This constructor is not accessible to users. Initializes + the underlying data members: + * current_ with current, + * n_ with n. + Note that this overload can only be present if last_ele_ is not present. + 4) A private constructor which is used by ranges::slide_view::begin and + ranges::slide_view::end. This constructor is not accessible to users. Initializes + the underlying data members: + * current_ with current, + * last_ele_ with last_ele (note that this data member is present due to + /*slide-caches-first*/ requirement), + * n_ with n. + +.SH Parameters + + i - an /*iterator*/ + current - an iterator to current element of slide_view + last_ele - an iterator to last element of slide_view + n - the slide window width of slide_view + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::iterator::operator*.3 b/man/std::ranges::slide_view::iterator::operator*.3 new file mode 100644 index 000000000..8d1133c40 --- /dev/null +++ b/man/std::ranges::slide_view::iterator::operator*.3 @@ -0,0 +1,32 @@ +.TH std::ranges::slide_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::iterator::operator* \- std::ranges::slide_view::iterator::operator* + +.SH Synopsis + constexpr auto operator*() const; (since C++23) + + Returns the current element in the slide_view. + + Let current_ and n_ be the underlying data members. Equivalent to: return + views::counted(current_, n_). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element, which is an object of value_type. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::slide_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..ff882653d --- /dev/null +++ b/man/std::ranges::slide_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,78 @@ +.TH std::ranges::slide_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::iterator::operator++,--,+=,-= \- std::ranges::slide_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr /*iterator*/ operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/& operator--() \fB(3)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(5)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + + Advances or decrements the iterator. + + Let current_ and last_ele_ be the underlying iterators to the begin and end of the + sliding window. + + 1) Equivalent to: + + current_ = ranges::next(current_); + last_ele_ = ranges::next(last_ele_); // if last_ele_ is present + return *this; + + Before the invocation, the current_ and last_ele_ (if present) must be + incrementable. + 2) Equivalent to: auto tmp = *this; ++*this; return tmp; + 3) Equivalent to: + + current_ = ranges::prev(current_); + last_ele_ = ranges::prev(last_ele_); // if last_ele_ is present + return *this; + + Before the invocation, the current_ and last_ele_ (if present) must be + decrementable. + 4) Equivalent to: auto tmp = *this; --*this; return tmp; + 5) Equivalent to: + + current_ = current_ + n; + last_ele_ = last_ele_ + n; // if last_ele_ is present + return *this; + + Before the invocation, the expressions current_ + n and last_ele_ + n (if last_ele_ + is present) must have well-defined behavior. + 6) Equivalent to: + + current_ = current_ - n; + last_ele_ = last_ele_ - n; // if last_ele_ is present + return *this; + + Before the invocation, the expressions current_ - n and last_ele_ - n (if last_ele_ + is present) must have well-defined behavior. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,3,5,6) *this + 2,4) a copy of *this that was made before the change + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::iterator::operator[].3 b/man/std::ranges::slide_view::iterator::operator[].3 new file mode 100644 index 000000000..f7cabc64d --- /dev/null +++ b/man/std::ranges::slide_view::iterator::operator[].3 @@ -0,0 +1,34 @@ +.TH std::ranges::slide_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::iterator::operator[] \- std::ranges::slide_view::iterator::operator[] + +.SH Synopsis + constexpr auto operator[]( difference_type pos ) const (since C++23) + requires ranges::random_access_range; + + Returns an element at specified relative location. + + Let current_ and n_ be the underlying data members. Equivalent to: return + views::counted(current_ + pos, n_);. + +.SH Parameters + + pos - position relative to current location + +.SH Return value + + The element (of type value_type) at displacement pos relative to the current + location. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator* accesses the element + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::sentinel.3 b/man/std::ranges::slide_view::sentinel.3 new file mode 100644 index 000000000..f33f839cf --- /dev/null +++ b/man/std::ranges::slide_view::sentinel.3 @@ -0,0 +1,41 @@ +.TH std::ranges::slide_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::sentinel \- std::ranges::slide_view::sentinel + +.SH Synopsis + class /*sentinel*/; (since C++23) + (exposition only*) + + The return type of slide_view::end when the underlying view is not a common_range. + + The /*sentinel*/ is used only when /*slide-caches-first*/ is true. + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from slide_view::begin + (C++23) \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++23) slide_view::begin + \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.29.4 Class slide_view::sentinel [range.slide.sentinel] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::sentinel::sentinel.3 b/man/std::ranges::slide_view::sentinel::sentinel.3 new file mode 100644 index 000000000..d0b3bbf7b --- /dev/null +++ b/man/std::ranges::slide_view::sentinel::sentinel.3 @@ -0,0 +1,27 @@ +.TH std::ranges::slide_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::sentinel::sentinel \- std::ranges::slide_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + private: \fB(2)\fP (exposition only*) + constexpr /*sentinel*/( ranges::sentinel_t end ); + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel end_ with + ranges::sentinel_t(). + 2) A private constructor which is used by slide_view::end. This constructor is not + accessible to users. Initializes end_ with end. + +.SH Parameters + + end - a sentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::slide_view::size.3 b/man/std::ranges::slide_view::size.3 new file mode 100644 index 000000000..5985494bf --- /dev/null +++ b/man/std::ranges::slide_view::size.3 @@ -0,0 +1,73 @@ +.TH std::ranges::slide_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::size \- std::ranges::slide_view::size + +.SH Synopsis + constexpr auto size() (since C++23) + requires ranges::sized_range; + constexpr auto size() const (since C++23) + requires ranges::sized_range; + + Returns the number of elements. + + Let base_ and n_ be the underlying view and "window size" respectively. + + Equivalent to: + + auto sz = ranges::distance(base_) - n_ + 1; + if (sz < 0) + sz = 0; + return __to_unsigned_like(sz); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. Equals to 0, if the number of elements (ranges::size(base_)) + in underlying view base_ is less than "window size" n_. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr static auto v = {1, 2, 3, 4, 5, 6}; + + constexpr int width1{4}; + constexpr auto view1{std::views::slide(v, width1)}; + static_assert(view1.size() == 3); + static_assert(view1.size() == (v.size() - width1 + 1)); + + constexpr int width2{8}; + constexpr auto view2{std::views::slide(v, width2)}; + // window is too wide, so view2 has no elements: + static_assert(view2.size() == 0); + + std::forward_list forward_list = v; + const auto view3{std::views::slide(forward_list, width1)}; + // auto x = view3.size(); // error: sized_range constraint is not satisfied + + std::list list = v; + const auto view4{std::views::slide(list, width1)}; + std::cout << view4.size() << '\\n'; // prints 3 + } + +.SH Output: + + 3 + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::slide_view::slide_view.3 b/man/std::ranges::slide_view::slide_view.3 new file mode 100644 index 000000000..564c10da8 --- /dev/null +++ b/man/std::ranges::slide_view::slide_view.3 @@ -0,0 +1,43 @@ +.TH std::ranges::slide_view::slide_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::slide_view::slide_view \- std::ranges::slide_view::slide_view + +.SH Synopsis + constexpr explicit slide_view( V base, ranges::range_difference_t (since C++23) + n ); + + Constructs a slide_view initializing the underlying data members: + + * move construct the underlying view base_ with std::move(base), + * the "window size" n_ with n. + +.SH Parameters + + base - the source view + n - the "sliding window" size + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto source = {1, 2, 3, 4}; + + auto slide = std::views::slide(source, 3); + + std::ranges::for_each(slide, [](std::ranges::viewable_range auto&& w) + { + std::cout << '[' << w[0] << ' ' << w[1] << ' ' << w[2] << "]\\n"; + }); + } + +.SH Output: + + [1 2 3] + [2 3 4] diff --git a/man/std::ranges::sort.3 b/man/std::ranges::sort.3 new file mode 100644 index 000000000..c043b0a86 --- /dev/null +++ b/man/std::ranges::sort.3 @@ -0,0 +1,200 @@ +.TH std::ranges::sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::sort \- std::ranges::sort + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + sort( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Comp = + ranges::less, + + class Proj = std::identity > \fB(2)\fP \fI(since C++20)\fP + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + + sort( R&& r, Comp comp = {}, Proj proj = {} ); + + Sorts the elements in the range [first, last) in non-descending order. The order of + equivalent elements is not guaranteed to be preserved. + + A sequence is sorted with respect to a comparator comp if for any iterator it + pointing to the sequence and any non-negative integer n such that it + n is a valid + iterator pointing to an element of the sequence, std::invoke(comp, std::invoke(proj, + *(it + n)), std::invoke(proj, *it)) evaluates to false. + + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the range to sort + r - the range to sort + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + \\(\\scriptsize \\mathcal{O}(N\\cdot\\log{(N)})\\)𝓞(N·log(N)) comparisons and projections, + where N = ranges::distance(first, last). + +.SH Possible implementation + + Note that typical implementations use Introsort. See also the implementation in MSVC + STL and libstdc++. + +struct sort_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr I + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + if (first == last) + return first; + + I last_iter = ranges::next(first, last); + ranges::make_heap(first, last_iter, std::ref(comp), std::ref(proj)); + ranges::sort_heap(first, last_iter, std::ref(comp), std::ref(proj)); + + return last_iter; + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(comp), std::move(proj)); + } +}; + +inline constexpr sort_fn sort {}; + +.SH Notes + + std::sort uses std::iter_swap to swap elements, whereas ranges::sort instead uses + ranges::iter_swap (which performs ADL for iter_swap, unlike std::iter_swap) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto comment, auto const& seq, char term = ' ') + { + for (std::cout << comment << '\\n'; auto const& elem : seq) + std::cout << elem << term; + std::cout << '\\n'; + } + + struct Particle + { + std::string name; double mass; // MeV + template friend + Os& operator<<(Os& os, Particle const& p) + { + return os << std::left << std::setw(8) << p.name << " : " << p.mass << ' '; + } + }; + + int main() + { + std::array s {5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; + + namespace ranges = std::ranges; + + ranges::sort(s); + print("Sort using the default operator<", s); + + ranges::sort(s, ranges::greater()); + print("Sort using a standard library compare function object", s); + + struct + { + bool operator()(int a, int b) const { return a < b; } + } customLess; + ranges::sort(s.begin(), s.end(), customLess); + print("Sort using a custom function object", s); + + ranges::sort(s, [](int a, int b) { return a > b; }); + print("Sort using a lambda expression", s); + + Particle particles[] + { + {"Electron", 0.511}, {"Muon", 105.66}, {"Tau", 1776.86}, + {"Positron", 0.511}, {"Proton", 938.27}, {"Neutron", 939.57} + }; + ranges::sort(particles, {}, &Particle::name); + print("\\nSort by name using a projection", particles, '\\n'); + ranges::sort(particles, {}, &Particle::mass); + print("Sort by mass using a projection", particles, '\\n'); + } + +.SH Output: + + Sort using the default operator< + 0 1 2 3 4 5 6 7 8 9 + Sort using a standard library compare function object + 9 8 7 6 5 4 3 2 1 0 + Sort using a custom function object + 0 1 2 3 4 5 6 7 8 9 + Sort using a lambda expression + 9 8 7 6 5 4 3 2 1 0 + + Sort by name using a projection + Electron : 0.511 + Muon : 105.66 + Neutron : 939.57 + Positron : 0.511 + Proton : 938.27 + Tau : 1776.86 + + Sort by mass using a projection + Electron : 0.511 + Positron : 0.511 + Muon : 105.66 + Proton : 938.27 + Neutron : 939.57 + Tau : 1776.86 + +.SH See also + + ranges::partial_sort sorts the first N elements of a range + (C++20) (niebloid) + ranges::stable_sort sorts a range of elements while preserving order between equal + (C++20) elements + (niebloid) + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + sort sorts a range into ascending order + \fI(function template)\fP diff --git a/man/std::ranges::sort_heap.3 b/man/std::ranges::sort_heap.3 new file mode 100644 index 000000000..cbc68390a --- /dev/null +++ b/man/std::ranges::sort_heap.3 @@ -0,0 +1,148 @@ +.TH std::ranges::sort_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::sort_heap \- std::ranges::sort_heap + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for S, + + class Comp = ranges::less, class Proj = std::identity > + requires std::sortable \fB(1)\fP \fI(since C++20)\fP + constexpr I + + sort_heap( I first, S last, Comp comp = {}, Proj proj = {} ); + template< ranges::random_access_range R, class Comp = + ranges::less, + + class Proj = std::identity > \fB(2)\fP \fI(since C++20)\fP + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + + sort_heap( R&& r, Comp comp = {}, Proj proj = {} ); + + Converts the max heap [first, last) into a sorted range in ascending order. The + resulting range no longer has the heap property. + + 1) Elements are compared using the given binary comparison function comp and + projection object proj. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to sort + r - the range of elements to sort + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Given N = ranges::distance(first, last), at most \\(\\scriptsize 2N\\log{(N)}\\)2Nlog(N) + comparisons and \\(\\scriptsize 4N\\log{(N)}\\)4Nlog(N) projections. + +.SH Notes + + A max heap is a range of elements [f, l), arranged with respect to comparator comp + and projection proj, that has the following properties: + + * With N = l - f, p = f[(i - 1) / 2], and q = f[i], for all 0 < i < N, the + expression std::invoke(comp, std::invoke(proj, p), std::invoke(proj, q)) + evaluates to false. + * A new element can be added using ranges::push_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + * The first element can be removed using ranges::pop_heap, in \\(\\scriptsize + \\mathcal{O}(\\log N)\\)𝓞(log N) time. + +.SH Possible implementation + +struct sort_heap_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr I + operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + auto ret {ranges::next(first, last)}; + for (; first != last; --last) + ranges::pop_heap(first, last, comp, proj); + return ret; + } + + template + requires std::sortable, Comp, Proj> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(comp), std::move(proj)); + } +}; + +inline constexpr sort_heap_fn sort_heap {}; + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(auto const& rem, auto const& v) + { + std::cout << rem; + for (const auto i : v) + std::cout << i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::array v {3, 1, 4, 1, 5, 9}; + print("original array: ", v); + + std::ranges::make_heap(v); + print("after make_heap: ", v); + + std::ranges::sort_heap(v); + print("after sort_heap: ", v); + } + +.SH Output: + + original array: 3 1 4 1 5 9 + after make_heap: 9 5 4 1 1 3 + after sort_heap: 1 1 3 4 5 9 + +.SH See also + + ranges::is_heap checks if the given range is a max heap + (C++20) (niebloid) + ranges::is_heap_until finds the largest subrange that is a max heap + (C++20) (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + turns a max heap into a range of elements sorted in ascending + sort_heap order + \fI(function template)\fP diff --git a/man/std::ranges::split_view::base.3 b/man/std::ranges::split_view::base.3 new file mode 100644 index 000000000..4a835d8f9 --- /dev/null +++ b/man/std::ranges::split_view::base.3 @@ -0,0 +1,61 @@ +.TH std::ranges::split_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::base \- std::ranges::split_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view base_. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A copy of the underlying view. + 2) A view move-constructed from the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr std::string_view keywords{"this throw true try typedef typeid"}; + std::ranges::split_view split_view{keywords, ' '}; + std::cout << "base() = " << std::quoted(split_view.base()) << "\\n" + "substrings: "; + for (auto split : split_view) + std::cout << std::quoted(std::string_view{split}) << ' '; + std::cout << '\\n'; + } + +.SH Output: + + base() = "this throw true try typedef typeid" + substrings: "this" "throw" "true" "try" "typedef" "typeid" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3590 C++20 the const& overload additionally required constraints relaxed + validity of copy-assignment + +.SH See also + + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function of std::ranges::lazy_split_view)\fP diff --git a/man/std::ranges::split_view::begin.3 b/man/std::ranges::split_view::begin.3 new file mode 100644 index 000000000..d9cc502d9 --- /dev/null +++ b/man/std::ranges::split_view::begin.3 @@ -0,0 +1,79 @@ +.TH std::ranges::split_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::begin \- std::ranges::split_view::begin + +.SH Synopsis + constexpr /*iterator*/ begin(); \fI(since C++20)\fP + + Returns an iterator to the first found subrange. + + In order to provide the amortized constant time complexity required by the range + concept, this function caches the result within the split_view for use on subsequent + calls. Equivalent to + + constexpr /*iterator*/ begin() + { + if (!cached_begin_.has_value()) + cached_begin_ = this->find_next(ranges::begin(base_)); + return {*this, ranges::begin(base_), cached_begin_.value()}; + } + + Exposition only data members base_ and cached_begin_ are described here. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator. + +.SH Complexity + + Amortized \\(\\scriptsize \\mathcal{O}(1)\\)O(1). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr std::string_view sentence{"Keep..moving..forward.."}; + constexpr std::string_view delim{".."}; + std::ranges::split_view words{sentence, delim}; + + std::cout << "begin(): " << std::quoted(std::string_view{*words.begin()}) + << "\\nSubstrings: "; + for (std::string_view word : words) + std::cout << std::quoted(word) << ' '; + + std::ranges::split_view letters{sentence, std::string_view{""}}; + std::cout << "\\nbegin(): " << std::quoted(std::string_view{*letters.begin()}) + << "\\nLetters: "; + for (std::string_view letter : letters) + std::cout << letter << ' '; + std::cout << '\\n'; + } + +.SH Output: + + begin(): "Keep" + Substrings: "Keep" "moving" "forward" "" + begin(): "K" + Letters: K e e p . . m o v i n g . . f o r w a r d . . + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function of std::ranges::lazy_split_view)\fP + + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) diff --git a/man/std::ranges::split_view::end.3 b/man/std::ranges::split_view::end.3 new file mode 100644 index 000000000..57c4c66ee --- /dev/null +++ b/man/std::ranges::split_view::end.3 @@ -0,0 +1,57 @@ +.TH std::ranges::split_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::end \- std::ranges::split_view::end + +.SH Synopsis + constexpr auto end() const; \fI(since C++20)\fP + + Returns an iterator or a sentinel representing the end of the resulting subrange. + + Equivalent to: + + constexpr auto end() + { + if constexpr (ranges::common_range) + return /*iterator*/{*this, ranges::end(base_), {}}; + else + return /*sentinel*/{*this}; + } + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator or a sentinel. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view keywords{"bitand bitor bool break"}; + std::ranges::split_view kw{keywords, ' '}; + const auto count = std::ranges::distance(kw.begin(), kw.end()); + std::cout << "Words count: " << count << '\\n'; + } + +.SH Output: + + Words count: 4 + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function of std::ranges::lazy_split_view)\fP + + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) diff --git a/man/std::ranges::split_view::find_next.3 b/man/std::ranges::split_view::find_next.3 new file mode 100644 index 000000000..87f6db731 --- /dev/null +++ b/man/std::ranges::split_view::find_next.3 @@ -0,0 +1,31 @@ +.TH std::ranges::split_view::find_next 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::find_next \- std::ranges::split_view::find_next + +.SH Synopsis + constexpr ranges::subrange> (exposition only*) + /*find_next*/( ranges::iterator_t it ); + + Searches for the next occurrence of pattern in the underlying view. This function is + for exposition only and its name is not normative. + + Equivalent to: + + auto [b, e] = ranges::search(ranges::subrange(it, ranges::end(base_)), pattern_); + + if (b != ranges::end(base_) and ranges::empty(pattern_)) + { + ++b; + ++e; + } + + return {b, e}; + +.SH Parameters + + it - an iterator to the position at which to start the search + +.SH Return value + + A subrange that represents the next position of the pattern, if it was found. An + empty subrange otherwise. diff --git a/man/std::ranges::split_view::iterator.3 b/man/std::ranges::split_view::iterator.3 new file mode 100644 index 000000000..91370efac --- /dev/null +++ b/man/std::ranges::split_view::iterator.3 @@ -0,0 +1,123 @@ +.TH std::ranges::split_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::iterator \- std::ranges::split_view::iterator + +.SH Synopsis + class /*iterator*/; \fI(since C++20)\fP + (exposition only*) + + The return type of split_view::begin. This is a forward_iterator, so it is expected + that V models at least forward_range. + +.SH Member types + + Member type Definition + iterator_concept std::forward_iterator_tag + iterator_category std::input_iterator_tag + value_type ranges::subrange> + difference_type ranges::range_difference_t + + Data members + + Member name Definition + A pointer of type ranges::split_view* to the + parent_ (private) parent split_view object. + (exposition-only member object*) + An iterator of type ranges::iterator_t into the + cur_ (private) underlying view that points to the begin of a current + subrange. + (exposition-only member object*) + A subrange of type ranges::subrange> + next_ (private) to the position of the pattern next to the current + subrange. + (exposition-only member object*) + A boolean flag that indicates whether an empty trailing + trailing_empty_ (private) subrange (if any) was reached. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + base returns the underlying iterator + (C++20) \fI(public member function)\fP + operator* returns the current subrange + (C++20) \fI(public member function)\fP + operator++ advances the iterator + operator++(int) \fI(public member function)\fP + (C++20) + +std::ranges::split_view::iterator::iterator + + /*iterator*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr /*iterator*/( split_view& parent, ranges::iterator_t + current, \fB(2)\fP \fI(since C++20)\fP + ranges::subrange> + next ); + + 1) Value-initializes non-static data members with their default member initializers, + that is + * ranges::split_view* parent_ = nullptr;, + * ranges::iterator_t cur_ = ranges::iterator_t();, + * ranges::subrange> next_ = + ranges::subrange>();, and + * bool trailing_empty_ = false;. + 2) Initializes non-static data members: + * ranges::split_view* parent_ = std::addressof(parent);, + * ranges::iterator_t cur_ = std::move(current);, + * ranges::subrange> next_ = std::move(next);, and + * bool trailing_empty_ = false;. + +std::ranges::split_view::iterator::base + + constexpr const ranges::iterator_t base() const; \fI(since C++20)\fP + + Equivalent to return cur_;. + +std::ranges::split_view::iterator::operator* + + constexpr ranges::range_reference_t operator*() const; \fI(since C++20)\fP + + Equivalent to return {cur_, next_.begin()};. + +std::ranges::split_view::iterator::operator++ + + constexpr /*iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr void operator++( int ); \fB(2)\fP \fI(since C++20)\fP + + 1) Equivalent to + cur_ = next_.begin(); + + if (cur_ != ranges::end(parent_->base_)) + { + if (cur_ = next_.end(); cur_ == ranges::end(parent_->base_)) + { + trailing_empty_ = true; + next_ = {cur_, cur_}; + } + else + next_ = parent_->find_next(cur_); + } + else + trailing_empty_ = false; + + return *this; + 2) Equivalent to auto tmp = *this; ++*this; return tmp;. + +.SH Non-member functions + + operator== compares the underlying iterators + (C++20) \fI(function)\fP + +operator==(std::ranges::split_view::iterator, std::ranges::split_view::iterator) + + friend constexpr bool operator==( const /*iterator*/& x, const \fI(since C++20)\fP + /*iterator*/& y ); + + Equivalent to return x.cur_ == y.cur_ and x.trailing_empty_ == y.trailing_empty_;. + + The != operator is synthesized from operator==. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::ranges::split_view::iterator is + an associated class of the arguments. diff --git a/man/std::ranges::split_view::sentinel.3 b/man/std::ranges::split_view::sentinel.3 new file mode 100644 index 000000000..db5288368 --- /dev/null +++ b/man/std::ranges::split_view::sentinel.3 @@ -0,0 +1,42 @@ +.TH std::ranges::split_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::sentinel \- std::ranges::split_view::sentinel + +.SH Synopsis + class /*sentinel*/; \fI(since C++20)\fP + (exposition only*) + + The return type of split_view::end when the underlying view type (V) does not models + common_range. + +.SH Member functions + + constructor constructs a sentinel + (C++20) \fI(public member function)\fP + +std::ranges::split_view::sentinel::sentinel + + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( ranges::split_view& parent ); \fB(2)\fP \fI(since C++20)\fP + + 1) Value-initializes end_ via its default member initializer (= + ranges::sentinel_t()). + 2) Initializes end_ with ranges::end(parent.base_). + +.SH Non-member functions + + operator== compares the underlying iterator and the underlying sentinel + (C++20) \fI(function)\fP + +operator==(std::ranges::split_view::iterator, std::ranges::split_view::sentinel) + + friend constexpr bool operator==( const /*iterator*/& x, \fI(since C++20)\fP + const /*sentinel*/& y ); + + Equivalent to return x.cur_ == y.end_ and !x.trailing_empty_;. + + The != operator is synthesized from operator==. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::ranges::split_view::sentinel is + an associated class of the arguments. diff --git a/man/std::ranges::split_view::split_view.3 b/man/std::ranges::split_view::split_view.3 new file mode 100644 index 000000000..f15ececf7 --- /dev/null +++ b/man/std::ranges::split_view::split_view.3 @@ -0,0 +1,118 @@ +.TH std::ranges::split_view::split_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::split_view::split_view \- std::ranges::split_view::split_view + +.SH Synopsis + Defined in header + split_view() + + requires std::default_initializable && \fB(1)\fP \fI(since C++20)\fP + + std::default_initializable = default; + constexpr explicit split_view( V base, Pattern pattern ); \fB(2)\fP \fI(since C++20)\fP + template< ranges::forward_range R > + + requires std::constructible_from> && + std::constructible_from>> + + constexpr explicit split_view( R&& r, ranges::range_value_t e + ); + + Constructs a split_view. + + Let base_ be the underlying view and pattern_ be the delimiter. + + 1) Default constructor. Value-initializes base_ and pattern_ with their default + member initializers respectively. + 2) Initializes base_ with std::move(base) and pattern_ with std::move(pattern). + 3) Initializes base_ with views::all(std::forward(r)) and pattern_ with + ranges::single_view{std::move(e)}. + +.SH Parameters + + base - the view (to be split) + pattern - view to be used as the delimiter + e - element to be used as the delimiter + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + int main() + { + { + auto view = std::views::iota(1, 20) + | std::views::transform([](int x) { return x % 5; }); + auto splitts = std::views::split(view, 0); // (2) + for (const auto& split : splitts) + { + std::cout << "{ "; + std::ranges::copy(split, std::ostream_iterator(std::cout, " ")); + std::cout << "} "; + } + } + std::cout << '\\n'; + + { + const std::vector nums{1, -1, -1, 2, 3, -1, -1, 4, 5, 6}; + const std::array delim{-1, -1}; + auto splitter = std::views::split(nums, delim); // (3) + for (const auto& split : splitter) + { + std::cout << "{ "; + std::ranges::copy(split, std::ostream_iterator(std::cout, " ")); + std::cout << "} "; + } + } + std::cout << '\\n'; + + { + constexpr std::string_view JupiterMoons + { + "Callisto, Europa, Ganymede, Io, and 91 more" + }; + constexpr std::string_view delim{", "}; + std::ranges::split_view moons_extractor{JupiterMoons, delim}; // (3) + auto is_moon = std::views::filter([](auto str) + { + return std::isupper(str[0]); + }); + std::cout << "Some moons of Jupiter: "; + for (const auto moon : moons_extractor | is_moon) + std::cout << std::string_view(moon) << ' '; + } + std::cout << '\\n'; + } + +.SH Output: + + { 1 2 3 4 } { 1 2 3 4 } { 1 2 3 4 } { 1 2 3 4 } + { 1 } { 2 3 } { 4 5 6 } + Some moons of Jupiter: Callisto Europa Ganymede Io + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was not made explicit + (P2711R1) explicit + +.SH See also + + constructor constructs a lazy_split_view + (C++20) \fI(public member function of std::ranges::lazy_split_view)\fP + diff --git a/man/std::ranges::ssize.3 b/man/std::ranges::ssize.3 new file mode 100644 index 000000000..b2020fb09 --- /dev/null +++ b/man/std::ranges::ssize.3 @@ -0,0 +1,98 @@ +.TH std::ranges::ssize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::ssize \- std::ranges::ssize + +.SH Synopsis + Defined in header + Defined in header + inline namespace /*unspecified*/ { + + inline constexpr /*unspecified*/ ssize = \fI(since C++20)\fP + /*unspecified*/; (customization point object) + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /*signed-integer-like*/ ssize( T&& t ); + + Returns the size of a range converted to a signed type. + + If ranges::size(t) is well-formed, a call to ranges::ssize is expression-equivalent + to static_cast(ranges::size(t)), where MadeSigned denotes + + * the corresponding signed version of decltype(ranges::size(t)), if it is wider + than std::ptrdiff_t, or + * std::ptrdiff_t otherwise. + + If ranges::size(t) is ill-formed, a call to ranges::ssize is also ill-formed, which + can result in substitution failure when ranges::ssize(t) appears in the immediate + context of a template instantiation. + +.SH Notes + + If ranges::ssize(e) is valid for an expression e, the return type is a + signed-integer-like type, i.e. an integer type for which std::is_signed_v is true, + or a signed-integer-class type. + + The width of integer-like types can be detected by std::numeric_limits::digits. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::array arr{1, 2, 3, 4, 5}; + auto s = std::ranges::ssize(arr); + + std::cout << "ranges::ssize(arr) = " << s << '\\n' + << "ranges::ssize is " + << (std::is_signed_v ? "signed" : "unsigned") + << '\\n'; + + std::cout << "reversed arr: "; + + for (--s; s >= 0; --s) + std::cout << arr[s] << ' '; + + std::cout << "\\n" "s = " << s << '\\n'; + } + +.SH Output: + + ranges::ssize(arr) = 5 + ranges::ssize is signed + reversed arr: 5 4 3 2 1 + s = -1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3403 C++20 ranges::size worked for some non-range types made work + but ranges::ssize didn't + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::sized_range specifies that a range knows its size in constant time + (C++20) (concept) + ranges::distance returns the distance between an iterator and a sentinel, or + (C++20) between the beginning and end of a range + (niebloid) + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::ranges::stable_partition.3 b/man/std::ranges::stable_partition.3 new file mode 100644 index 000000000..86d459884 --- /dev/null +++ b/man/std::ranges::stable_partition.3 @@ -0,0 +1,199 @@ +.TH std::ranges::stable_partition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stable_partition \- std::ranges::stable_partition + +.SH Synopsis + Defined in header + Call signature + template< std::bidirectional_iterator I, std::sentinel_for + S, + + class Proj = std::identity, + std::indirect_unary_predicate> Pred > \fB(1)\fP (constexpr since + requires std::permutable C++26) + ranges::subrange + + stable_partition( I first, S last, Pred pred, Proj proj = + {} ); + template< ranges::bidirectional_range R, class Proj = + std::identity, + + std::indirect_unary_predicate< \fI(since C++20)\fP + std::projected, Proj>> Pred \fB(2)\fP (constexpr since + > C++26) + requires std::permutable> + ranges::borrowed_subrange_t + + stable_partition( R&& r, Pred pred, Proj proj = {} ); + + 1) Reorders the elements in the range [first, last) in such a way that the + projection proj of all elements for which the predicate pred returns true precede + the projection proj of elements for which predicate pred returns false. The + algorithms is stable, i.e. the relative order of elements is preserved. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to reorder + r - the range of elements to reorder + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + 1) An object equal to {pivot, last}, where pivot is an iterator to the first element + of the second group. + 2) Same as \fB(1)\fP if r is an lvalue or of a borrowed_range type. Otherwise returns + std::ranges::dangling. + +.SH Complexity + + Given N = ranges::distance(first, last), the complexity is at worst \\(\\scriptsize + N\\cdot\\log{(N)}\\)N·log(N) swaps, and only \\(\\scriptsize \\mathcal{O}(N)\\)𝓞(N) swaps + in case an extra memory buffer is used. Exactly \\(\\scriptsize N\\)N applications of + the predicate pred and projection proj. + +.SH Notes + + This function attempts to allocate a temporary buffer. If the allocation fails, the + less efficient algorithm is chosen. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_algorithms 202306L constexpr stable sorting + +.SH Possible implementation + + This implementation does not use extra memory buffer and as such can be less + efficient. See also the implementation in MSVC STL and libstdc++. + +struct stable_partition_fn +{ + template S, + class Proj = std::identity, + std::indirect_unary_predicate> Pred> + requires std::permutable + constexpr ranges::subrange + operator()(I first, S last, Pred pred, Proj proj = {}) const + { + first = ranges::find_if_not(first, last, pred, proj); + I mid = first; + while (mid != last) + { + mid = ranges::find_if(mid, last, pred, proj); + if (mid == last) + break; + I last2 = ranges::find_if_not(mid, last, pred, proj); + ranges::rotate(first, mid, last2); + first = ranges::next(first, ranges::distance(mid, last2)); + mid = last2; + } + return {std::move(first), std::move(mid)}; + } + + template, Proj>> Pred> + requires std::permutable> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, Pred pred, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(pred), std::move(proj)); + } +}; + +inline constexpr stable_partition_fn stable_partition {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + namespace rng = std::ranges; + + template S> + constexpr void stable_sort(I first, S last) + { + if (first == last) + return; + + auto pivot = *rng::next(first, rng::distance(first, last) / 2, last); + auto left = [pivot](const auto& em) { return em < pivot; }; + auto tail1 = rng::stable_partition(first, last, left); + auto right = [pivot](const auto& em) { return !(pivot < em); }; + auto tail2 = rng::stable_partition(tail1, right); + + stable_sort(first, tail1.begin()); + stable_sort(tail2.begin(), tail2.end()); + } + + void print(const auto rem, auto first, auto last, bool end = true) + { + std::cout << rem; + for (; first != last; ++first) + std::cout << *first << ' '; + std::cout << (end ? "\\n" : ""); + } + + int main() + { + const auto original = {9, 6, 5, 2, 3, 1, 7, 8}; + + std::vector vi {}; + auto even = [](int x) { return 0 == (x % 2); }; + + print("Original vector:\\t", original.begin(), original.end(), "\\n"); + + vi = original; + const auto ret1 = rng::stable_partition(vi, even); + print("Stable partitioned:\\t", vi.begin(), ret1.begin(), 0); + print("│ ", ret1.begin(), ret1.end()); + + vi = original; + const auto ret2 = rng::partition(vi, even); + print("Partitioned:\\t\\t", vi.begin(), ret2.begin(), 0); + print("│ ", ret2.begin(), ret2.end()); + + + vi = {16, 30, 44, 30, 15, 24, 10, 18, 12, 35}; + print("Unsorted vector: ", vi.begin(), vi.end()); + + stable_sort(rng::begin(vi), rng::end(vi)); + print("Sorted vector: ", vi.begin(), vi.end()); + } + +.SH Possible output: + + Original vector: 9 6 5 2 3 1 7 8 + Stable partitioned: 6 2 8 │ 9 5 3 1 7 + Partitioned: 8 6 2 │ 5 3 1 7 9 + Unsorted vector: 16 30 44 30 15 24 10 18 12 35 + Sorted vector: 10 12 15 16 18 24 30 30 35 44 + +.SH See also + + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + ranges::partition_copy copies a range dividing the elements into two groups + (C++20) (niebloid) + ranges::is_partitioned determines if the range is partitioned by the given predicate + (C++20) (niebloid) + divides elements into two groups while preserving their + stable_partition relative order + \fI(function template)\fP diff --git a/man/std::ranges::stable_sort.3 b/man/std::ranges::stable_sort.3 new file mode 100644 index 000000000..2a8bd75a1 --- /dev/null +++ b/man/std::ranges::stable_sort.3 @@ -0,0 +1,217 @@ +.TH std::ranges::stable_sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stable_sort \- std::ranges::stable_sort + +.SH Synopsis + Defined in header + Call signature + template< std::random_access_iterator I, std::sentinel_for + S, + + class Comp = ranges::less, class Proj = std::identity \fI(since C++20)\fP + > \fB(1)\fP (constexpr since + requires std::sortable C++26) + + I stable_sort( I first, S last, Comp comp = {}, Proj proj = + {} ); + template< ranges::random_access_range R, class Comp = + ranges::less, + \fI(since C++20)\fP + class Proj = std::identity > \fB(2)\fP (constexpr since + requires std::sortable, Comp, Proj> C++26) + ranges::borrowed_iterator_t + + stable_sort( R&& r, Comp comp = {}, Proj proj = {} ); + + Sorts the elements in the range [first, last) in non-descending order. The order of + equivalent elements is stable, i.e. guaranteed to be preserved. + + A sequence is sorted with respect to a comparator comp if for any iterator it + pointing to the sequence and any non-negative integer n such that it + n is a valid + iterator pointing to an element of the sequence, std::invoke(comp, std::invoke(proj, + *(it + n)), std::invoke(proj, *it) evaluates to false. + + 1) Elements are compared using the given binary comparison function comp. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the range to sort + r - the range to sort + comp - comparison to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + \\(\\scriptsize N\\cdot\\log{(N)}\\)N·log(N) comparisons, if extra memory is available; + where \\(\\scriptsize N\\)N is ranges::distance(first, last). \\(\\scriptsize + N\\cdot\\log^2{(N)}\\)N·log²(N) comparisons otherwise. Twice as many projections as the + number of comparisons in both cases. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_algorithms 202306L constexpr stable sorting + +.SH Possible implementation + + This implementation only shows the slower algorithm used when no additional memory + is available. See also implementation in MSVC STL and libstdc++. + +struct stable_sort_fn +{ + template S, + class Comp = ranges::less, class Proj = std::identity> + requires std::sortable + constexpr //< since C++26 + I operator()(I first, S last, Comp comp = {}, Proj proj = {}) const + { + auto count = ranges::distance(first, last); + auto mid = first + count / 2; + auto last_it = first + count; + + if (count <= 1) + return last_it; + + (*this)(first, mid, std::ref(comp), std::ref(proj)); + (*this)(mid, last_it, std::ref(comp), std::ref(proj)); + + ranges::inplace_merge(first, mid, last_it); + + return last_it; + } + + template + requires std::sortable, Comp, Proj> + constexpr //< since C++26 + ranges::borrowed_iterator_t operator()(R&& r, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(comp), std::move(proj)); + } +}; + +inline constexpr stable_sort_fn stable_sort {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto const& seq) + { + for (auto const& elem : seq) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + struct Particle + { + std::string name; double mass; // MeV + friend std::ostream& operator<<(std::ostream& os, Particle const& p) + { + return os << '\\n' << std::left << std::setw(8) << p.name << " : " << p.mass; + } + }; + + int main() + { + std::array s {5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; + + // sort using the default operator< + std::ranges::stable_sort(s); + print(s); + + // sort using a standard library compare function object + std::ranges::stable_sort(s, std::ranges::greater()); + print(s); + + // sort using a custom function object + struct + { + bool operator()(int a, int b) const + { + return a < b; + } + } customLess; + std::ranges::stable_sort(s.begin(), s.end(), customLess); + print(s); + + // sort using a lambda expression + std::ranges::stable_sort(s, [](int a, int b) { return a > b; }); + print(s); + + // sort with projection + Particle particles[] + { + {"Electron", 0.511}, {"Muon", 105.66}, {"Tau", 1776.86}, + {"Positron", 0.511}, {"Proton", 938.27}, {"Neutron", 939.57} + }; + print(particles); + std::ranges::stable_sort(particles, {}, &Particle::name); //< sort by name + print(particles); + std::ranges::stable_sort(particles, {}, &Particle::mass); //< sort by mass + print(particles); + } + +.SH Output: + + 0 1 2 3 4 5 6 7 8 9 + 9 8 7 6 5 4 3 2 1 0 + 0 1 2 3 4 5 6 7 8 9 + 9 8 7 6 5 4 3 2 1 0 + + Electron : 0.511 + Muon : 105.66 + Tau : 1776.86 + Positron : 0.511 + Proton : 938.27 + Neutron : 939.57 + + Electron : 0.511 + Muon : 105.66 + Neutron : 939.57 + Positron : 0.511 + Proton : 938.27 + Tau : 1776.86 + + Electron : 0.511 + Positron : 0.511 + Muon : 105.66 + Proton : 938.27 + Neutron : 939.57 + Tau : 1776.86 + +.SH See also + + ranges::sort sorts a range into ascending order + (C++20) (niebloid) + ranges::partial_sort sorts the first N elements of a range + (C++20) (niebloid) + ranges::stable_partition divides elements into two groups while preserving their + (C++20) relative order + (niebloid) + sorts a range of elements while preserving order between + stable_sort equal elements + \fI(function template)\fP diff --git a/man/std::ranges::starts_with.3 b/man/std::ranges::starts_with.3 new file mode 100644 index 000000000..a4c68c16d --- /dev/null +++ b/man/std::ranges::starts_with.3 @@ -0,0 +1,171 @@ +.TH std::ranges::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::starts_with \- std::ranges::starts_with + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity > (since + requires std::indirectly_comparable \fB(1)\fP C++23) + constexpr bool + starts_with( I1 first1, S1 last1, I2 first2, S2 last2, Pred pred = + {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, ranges::input_range R2, + + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::indirectly_comparable, (since + ranges::iterator_t, \fB(2)\fP C++23) + Pred, Proj1, Proj2> + constexpr bool + starts_with( R1&& r1, R2&& r2, Pred pred = {}, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); + + Checks whether the second range matches the prefix of the first range. + + 1) Let N1 and N2 denote the size of ranges [first1, last1) and [first2, last2) + respectively. If N1 < N2, returns false. Otherwise, returns true only if every + element in the range [first2, last2) is equal to the corresponding element in + [first1, first1 + N2). Comparison is done by applying the binary predicate pred to + elements in two ranges projected by proj1 and proj2 respectively. + 2) Same as \fB(1)\fP, but uses r1 and r2 as the source ranges, as if using + ranges::begin(r1) as first1, ranges:begin(r2) as first2, ranges::end(r1) as last1, + and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the range of elements to examine + r1 - the range of elements to examine + first2, last2 - the range of elements to be used as the prefix + r2 - the range of elements to be used as the prefix + pred - the binary predicate that compares the projected elements + proj1 - the projection to apply to the elements of the range to examine + proj2 - the projection to apply to the elements of the range to be used as + the prefix + +.SH Return value + + true if the second range matches the prefix of the first range, false otherwise. + +.SH Complexity + + Linear: at most min(N1, N2) applications of the predicate and both projections. + +.SH Possible implementation + + struct starts_with_fn + { + template S1, + std::input_iterator I2, std::sentinel_for S2, + class Pred = ranges::equal_to, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::indirectly_comparable + constexpr bool operator()(I1 first1, S1 last1, I2 first2, S2 last2, + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return ranges::mismatch(std::move(first1), last1, std::move(first2), last2, + std::move(pred), std::move(proj1), std::move(proj2) + ).in2 == last2; + } + + template + requires std::indirectly_comparable, + ranges::iterator_t, + Pred, Proj1, Proj2> + constexpr bool operator()(R1&& r1, R2&& r2, + Pred pred = {}, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + std::move(pred), std::move(proj1), std::move(proj2)); + } + }; + + inline constexpr starts_with_fn starts_with {}; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_starts_ends_with 202106L (C++23) std::ranges::starts_with, + std::ranges::ends_with + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + constexpr auto ascii_upper = [](char8_t c) + { + return u8'a' <= c && c <= u8'z' ? static_cast(c + u8'A' - u8'a') : c; + }; + + constexpr auto cmp_ignore_case = [=](char8_t x, char8_t y) + { + return ascii_upper(x) == ascii_upper(y); + }; + + static_assert(std::ranges::starts_with("const_cast", "const"sv)); + static_assert(std::ranges::starts_with("constexpr", "const"sv)); + static_assert(!std::ranges::starts_with("volatile", "const"sv)); + + std::cout << std::boolalpha + << std::ranges::starts_with(u8"Constantinopolis", u8"constant"sv, + {}, ascii_upper, ascii_upper) << ' ' + << std::ranges::starts_with(u8"Istanbul", u8"constant"sv, + {}, ascii_upper, ascii_upper) << ' ' + << std::ranges::starts_with(u8"Metropolis", u8"metro"sv, + cmp_ignore_case) << ' ' + << std::ranges::starts_with(u8"Acropolis", u8"metro"sv, + cmp_ignore_case) << '\\n'; + + constexpr static auto v = { 1, 3, 5, 7, 9 }; + constexpr auto odd = [](int x) { return x % 2; }; + static_assert(std::ranges::starts_with(v, std::views::iota(1) + | std::views::filter(odd) + | std::views::take(3))); + } + +.SH Output: + + true false true false + +.SH See also + + ranges::ends_with checks whether a range ends with another range + (C++23) (niebloid) + ranges::mismatch finds the first position where two ranges differ + (C++20) (niebloid) + starts_with checks if the string starts with the given prefix + (C++20) \fI\fI(public member\fP function of\fP + std::basic_string) + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::ranges::stride_view::base.3 b/man/std::ranges::stride_view::base.3 new file mode 100644 index 000000000..cef72cdab --- /dev/null +++ b/man/std::ranges::stride_view::base.3 @@ -0,0 +1,51 @@ +.TH std::ranges::stride_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::base \- std::ranges::stride_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns a copy of the underlying view base_. + + 1) Copy constructs the result from the underlying view. Equivalent to: return base_; + 2) Move constructs the result from the underlying view. Equivalent to: return + std::move(base_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(std::ranges::viewable_range auto&& v) + { + std::ranges::for_each(v, [](auto x) { std::cout << ' ' << x; }).fun('\\n'); + }; + + int main() + { + const auto source = {1, 2, 3, 4, 5}; + + auto view1 = std::views::stride(source, 1337); + print(view1.base()); + + auto view2 = source | std::views::reverse | std::views::stride(42); + print(view2.base()); + } + +.SH Output: + + 1 2 3 4 5 + 5 4 3 2 1 diff --git a/man/std::ranges::stride_view::begin.3 b/man/std::ranges::stride_view::begin.3 new file mode 100644 index 000000000..badcf1b2b --- /dev/null +++ b/man/std::ranges::stride_view::begin.3 @@ -0,0 +1,51 @@ +.TH std::ranges::stride_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::begin \- std::ranges::stride_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto begin() const requires ranges::range; \fB(2)\fP (since C++23) + + Returns an iterator to the first element of the stride_view. + + 1) Equivalent to return iterator(this, ranges::begin(base_));. + 2) Equivalent to return iterator(this, ranges::begin(base_));. + + Overload \fB(1)\fP does not participate in overload resolution if V is a simple view (that + is, if V and const V are views with the same iterator and sentinel types). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element of the view. + +.SH Example + + A link to test: Compiler Explorer. + + +// Run this code + + #include + #include + + int main() + { + constexpr auto v = {'A', 'B', 'C'}; + const auto x = v | std::views::stride(2); + const auto y = v | std::views::reverse | std::views::stride(2); + const auto z = v | std::views::stride(2) | std::views::reverse; + std::println("{} {} {}", *x.begin(), *y.begin(), *z.begin()); + } + +.SH Output: + + A C C + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP diff --git a/man/std::ranges::stride_view::end.3 b/man/std::ranges::stride_view::end.3 new file mode 100644 index 000000000..8fb67a8f6 --- /dev/null +++ b/man/std::ranges::stride_view::end.3 @@ -0,0 +1,62 @@ +.TH std::ranges::stride_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::end \- std::ranges::stride_view::end + +.SH Synopsis + constexpr auto end() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto end() const requires ranges::range \fB(2)\fP (since C++23) + + Returns an iterator or a sentinel representing the end of the stride_view. + + Let base_ and stride_ be the underlying data members. + + 1) Let Const be defined as using Const = false; and Base as using Base = V;. + 2) Let Const be defined as using Const = true; and Base as using Base = const V;. + + Equivalent to: + + if constexpr (ranges::common_range && + ranges::sized_range && + ranges::forward_range) + { + auto missing = (stride_ - ranges::distance(base_) % stride_) % stride_; + return iterator(this, ranges::end(base_), missing); + } + else if constexpr (ranges::common_range && + !ranges::bidirectional_range) + { + return iterator(this, ranges::end(base_)); + } + else + { + return std::default_sentinel; + } + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator to the element following the last element, if the underlying view V + models common_range. Otherwise, the std::default_sentinel which compares equal to + the end iterator. + +.SH Notes + + stride_view models common_range whenever the underlying view V does. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::stride_view::iterator.3 b/man/std::ranges::stride_view::iterator.3 new file mode 100644 index 000000000..13ca78a1d --- /dev/null +++ b/man/std::ranges::stride_view::iterator.3 @@ -0,0 +1,106 @@ +.TH std::ranges::stride_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::iterator \- std::ranges::stride_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/ (exposition only*) + + The return type of stride_view::begin, and of stride_view::end when the underlying + view V is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + const ranges::stride_view if Const is true, otherwise + Parent (private) ranges::stride_view. + (exposition-only member type*) + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + difference_type ranges::range_difference_t + value_type ranges::range_value_t + * std::random_access_iterator_tag, if Base models + random_access_range. Otherwise, + * std::bidirectional_iterator_tag, if Base models + iterator_concept bidirectional_range. Otherwise, + * std::forward_iterator_tag, if Base models forward_range. + Otherwise, + * std::input_iterator_tag. + Defined if and only if Base models forward_range. + + Let C denote the type + iterator_category iterator_traits>::iterator_category. Then: + + * std::random_access_iterator_tag, if C models + std::derived_from. Otherwise, + * C. + + Data members + + Member object Definition + ranges::iterator_t, holds an iterator to the current + current_ (private) element. + (exposition-only member object*) + end_ (private) ranges::sentinel_t, holds a sentinel to the end. + (exposition-only member object*) + stride_ (private) ranges::range_difference_t, holds the stride value. + (exposition-only member object*) + ranges::range_difference_t, usually holds the result of + missing_ (private) ranges::advance(current_, stride_, end_). + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + base returns an iterator to current element + (C++23) \fI(public member function)\fP + operator* accesses the element + (C++23) \fI(public member function)\fP + operator[] accesses an element by index + (C++23) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++23) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + iter_move casts the result of dereferencing the underlying iterator to its + (C++23) associated rvalue reference type + \fI(function)\fP + iter_swap swaps underlying pointed-to elements + (C++23) \fI(function)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.31.3 Class template stride_view::iterator [range.stride.iterator] + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::stride_view::iterator::base.3 b/man/std::ranges::stride_view::iterator::base.3 new file mode 100644 index 000000000..f3964c8bb --- /dev/null +++ b/man/std::ranges::stride_view::iterator::base.3 @@ -0,0 +1,24 @@ +.TH std::ranges::stride_view::iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::iterator::base \- std::ranges::stride_view::iterator::base + +.SH Synopsis + constexpr ranges::iterator_t base() &&; \fB(1)\fP (since C++23) + constexpr const ranges::iterator_t& base() const& noexcept; \fB(2)\fP (since C++23) + + Returns the underlying iterator. Let current_ be the underlying iterator. + + 1) Equivalent to: return std::move(current_);. + 2) Equivalent to: return current_;. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::stride_view::iterator::iterator.3 b/man/std::ranges::stride_view::iterator::iterator.3 new file mode 100644 index 000000000..0f8e0fe87 --- /dev/null +++ b/man/std::ranges::stride_view::iterator::iterator.3 @@ -0,0 +1,54 @@ +.TH std::ranges::stride_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::iterator::iterator \- std::ranges::stride_view::iterator::iterator + +.SH Synopsis + /*iterator*/() + requires std::default_initializable> \fB(1)\fP (since C++23) + = default; + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const and + std::convertible_to, \fB(2)\fP (since C++23) + ranges::iterator_t> and + + std::convertible_to, + ranges::sentinel_t>; + private: + + constexpr /*iterator*/( /*Parent*/& parent, (exposition + ranges::iterator_t current, \fB(3)\fP only*) + + ranges::range_difference_t missing + = 0 ); + + Constructs an iterator. + + 1) Default constructor. Value-initializes: + * current_ with ranges::iterator_t(), + * end_ with ranges::sentinel_t(), + * stride_ with 0, + * missing_ with 0. + 2) Conversion from /*iterator*/ to /*iterator*/. Initializes: + * current_ with std::move(i.current_), + * end_ with std::move(i.end_), + * stride_ with i.stride_, + * missing_ with i.missing_. + 3) A private constructor which is used by stride_view::begin and stride_view::end. + This constructor is not accessible to users. Initializes + * current_ with std::move(current), + * end_ with ranges::end(parent->base_), + * stride_ with parent->stride_, + * missing_ with missing. + +.SH Parameters + + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::stride_view::iterator::operator*.3 b/man/std::ranges::stride_view::iterator::operator*.3 new file mode 100644 index 000000000..981c727eb --- /dev/null +++ b/man/std::ranges::stride_view::iterator::operator*.3 @@ -0,0 +1,43 @@ +.TH std::ranges::stride_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::iterator::operator* \- std::ranges::stride_view::iterator::operator* + +.SH Synopsis + constexpr decltype(auto) operator*() const; (since C++23) + + Returns the elements into V the underlying iterator current_ points to. + + Equivalent to: return *current_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current element. + +.SH Notes + + operator-> is not provided. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr static auto v = {'a', 'b', 'c', 'd', 'e'}; + constexpr auto view{v | std::views::stride(2)}; + constexpr auto iter{view.begin() + 1}; + static_assert(*iter == 'c'); + static_assert(*(view.begin() + 2) == 'e'); + } + +.SH See also + + operator[] accesses an element by index + (C++23) \fI(public member function)\fP diff --git a/man/std::ranges::stride_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::stride_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..c7c3c8b80 --- /dev/null +++ b/man/std::ranges::stride_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,82 @@ +.TH std::ranges::stride_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::iterator::operator++,--,+=,-= \- std::ranges::stride_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/ operator++( int ) \fB(3)\fP (since C++23) + requires ranges::forward_range; + constexpr /*iterator*/& operator--() \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(5)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(7)\fP (since C++23) + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let current_, end_, stride_, and missing_ be the data members of the iterator. + + 1) Equivalent to + + missing_ = ranges::advance(current_, stride_, end_); + return *this + + Before the call current_ should not be equal to end_. + 2) Equivalent to ++*this;. + 3) Equivalent to auto tmp = *this; ++*this; return tmp;. + 4) Equivalent to + + ranges::advance(current_, missing_ - stride_); + missing_ = 0; + return *this; + + 5) Equivalent to auto tmp = *this; --*this; return tmp;. + 6) Equivalent to + + if (n > 0) + { + ranges::advance(current_, stride_ * (n - 1)); + missing_ = ranges::advance(current_, stride_, end_); + } + else if (n < 0) + { + ranges::advance(current_, stride_ * n + missing_); + missing_ = 0; + } + + return *this; + + If n > 0, then before the call to this function the ranges::distance(current_, end_) + must be greater than stride_ * (n - 1). + + Note that if n < 0, the ranges::distance(current_, end_) is always greater than + (non-positive) stride_ * (n - 1). + 7) Equivalent to return *this += -n; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++23) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::stride_view::iterator::operator[].3 b/man/std::ranges::stride_view::iterator::operator[].3 new file mode 100644 index 000000000..82223746b --- /dev/null +++ b/man/std::ranges::stride_view::iterator::operator[].3 @@ -0,0 +1,41 @@ +.TH std::ranges::stride_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::iterator::operator[] \- std::ranges::stride_view::iterator::operator[] + +.SH Synopsis + constexpr decltype(auto) operator[]( difference_type n ) const (since C++23) + requires ranges::random_access_range + + Returns an element at specified relative location. + + Equivalent to: return *(*this + n);. + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The element at displacement n relative to the current location. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr static auto v = {'a', 'b', 'c', 'd', 'e'}; + constexpr auto view{v | std::views::stride(2)}; + constexpr auto iter{view.begin() + 1}; + static_assert(*iter == 'c'); + static_assert(iter[0] == 'c'); + static_assert(iter[1] == 'e'); + } + +.SH See also + + operator* accesses an element + (C++23) \fI(public member function)\fP diff --git a/man/std::ranges::stride_view::size.3 b/man/std::ranges::stride_view::size.3 new file mode 100644 index 000000000..c1507a89f --- /dev/null +++ b/man/std::ranges::stride_view::size.3 @@ -0,0 +1,57 @@ +.TH std::ranges::stride_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::size \- std::ranges::stride_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; (since C++23) + constexpr auto size() const requires ranges::sized_range; (since C++23) + + Returns the number of elements. + + Let base_ be the underlying view and stride_ be the stored stride value. Equivalent + to: + + return __to_unsigned_like(__div_ceil(ranges::distance(base_), stride_)); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. The returned value is calculated as if by expression + + (ranges::size(base_) / stride_) + ((ranges::size(base_) % stride_ ? 1 : 0). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + namespace vs = std::views; + constexpr static auto v = {1, 2, 3, 4, 5}; + static_assert + ( + vs::stride(v, 1).size() == 5 and + vs::stride(v, 2).size() == 3 and + vs::stride(v, 3).size() == 2 and + vs::stride(v, 4).size() == 2 and + vs::stride(v, 5).size() == 1 and + vs::stride(v, 6).size() == 1 + ); + + std::forward_list list{v}; + // auto s = vs::stride(list, 2).size(); // Error: not a sized_range + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::stride_view::stride.3 b/man/std::ranges::stride_view::stride.3 new file mode 100644 index 000000000..023baea9d --- /dev/null +++ b/man/std::ranges::stride_view::stride.3 @@ -0,0 +1,31 @@ +.TH std::ranges::stride_view::stride 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::stride \- std::ranges::stride_view::stride + +.SH Synopsis + constexpr ranges::range_difference_t<_Vp> stride() const noexcept; (since C++23) + + Returns a copy of the underlying stride object stride_. Equivalent to return + stride_;. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The stride value. + +.SH Example + + +// Run this code + + #include + + int main() + { + constexpr auto view = std::views::iota(1337) + | std::views::stride(42); + static_assert(view.stride() == 42); + } diff --git a/man/std::ranges::stride_view::stride_view.3 b/man/std::ranges::stride_view::stride_view.3 new file mode 100644 index 000000000..369a9e878 --- /dev/null +++ b/man/std::ranges::stride_view::stride_view.3 @@ -0,0 +1,60 @@ +.TH std::ranges::stride_view::stride_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::stride_view::stride_view \- std::ranges::stride_view::stride_view + +.SH Synopsis + constexpr explicit stride_view( V base, ranges::range_difference_t (since C++23) + stride ); + + Constructs a stride_view initializing the underlying data members: + + * move construct the underlying view base_ with std::move(base), + * construct the stride_ with stride. + + If stride < 1 the behavior is undefined. + +.SH Parameters + + base - the source view + stride - the stride value + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(std::string_view rem, auto v, std::string_view term = "\\n") + { + std::cout << rem << ": "; + std::ranges::copy(v, std::ostream_iterator(std::cout, " ")); + std::cout << term; + }; + + int main() + { + auto source = std::views::iota(1, 10); + print("source", source); + + for (int stride_value : std::views::iota(1, 6)) + { + auto strided_view = std::views::stride(source, stride_value); + + print("stride", std::views::single(stride_value), "-> "); + print("result", strided_view); + } + } + +.SH Output: + + source: 1 2 3 4 5 6 7 8 9 + stride: 1 -> result: 1 2 3 4 5 6 7 8 9 + stride: 2 -> result: 1 3 5 7 9 + stride: 3 -> result: 1 4 7 + stride: 4 -> result: 1 5 9 + stride: 5 -> result: 1 6 diff --git a/man/std::ranges::subrange.3 b/man/std::ranges::subrange.3 new file mode 100644 index 000000000..c3965dcff --- /dev/null +++ b/man/std::ranges::subrange.3 @@ -0,0 +1,149 @@ +.TH std::ranges::subrange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange \- std::ranges::subrange + +.SH Synopsis + Defined in header + template< + + std::input_or_output_iterator I, + std::sentinel_for S = I, + ranges::subrange_kind K = std::sized_sentinel_for ? + ranges::subrange_kind::sized : ranges::subrange_kind::unsized \fI(since C++20)\fP + > + requires (K == ranges::subrange_kind::sized || + !std::sized_sentinel_for) + + class subrange : public ranges::view_interface> + + The subrange class template combines together an iterator and a sentinel into a + single view. + + Additionally, the subrange is a sized_range whenever the final template parameter is + subrange_kind::sized (which happens when std::sized_sentinel_for is satisfied + or when size is passed explicitly as a constructor argument). The size record is + needed to be stored if and only if std::sized_sentinel_for is false and K is + subrange_kind::sized. + +.SH Member functions + + constructor creates a new subrange + (C++20) \fI(public member function)\fP + operator PairLike converts the subrange to a pair-like type + (C++20) \fI(public member function)\fP +.SH Observers + begin obtains the iterator + (C++20) \fI(public member function)\fP + end obtains the sentinel + (C++20) \fI(public member function)\fP + empty checks whether the subrange is empty + (C++20) \fI(public member function)\fP + size obtains the size of the subrange + (C++20) \fI(public member function)\fP +.SH Iterator operations + advance advances the iterator by given distance + (C++20) \fI(public member function)\fP + prev obtains a copy of the subrange with its iterator decremented by a + (C++20) given distance + \fI(public member function)\fP + next obtains a copy of the subrange with its iterator advanced by a + (C++20) given distance + \fI(public member function)\fP + Inherited from std::ranges::view_interface + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator + (C++20) type satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it + (C++20) satisfies bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it + (C++20) satisfies random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + +.SH Non-member functions + + get(std::ranges::subrange) obtains iterator or sentinel from a std::ranges::subrange + (C++20) \fI(function template)\fP + +.SH Helper types + + ranges::subrange_kind specifies whether a std::ranges::subrange + (C++20) models std::ranges::sized_range + \fI(enum)\fP + std::tuple_size obtains the number of components of a + (C++20) std::ranges::subrange + \fI(class template specialization)\fP + std::tuple_element obtains the type of the iterator or the + (C++20) sentinel of a std::ranges::subrange + \fI(class template specialization)\fP + + Helper templates + + template< class I, class S, ranges::subrange_kind K > + inline constexpr bool enable_borrowed_range> = true; + + This specialization of std::ranges::enable_borrowed_range makes subrange satisfy + borrowed_range. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + void mutate(V& v) + { + v += 'A' - 'a'; + } + + template + void mutate_map_values(std::multimap& m, K k) + { + auto [first, last] = m.equal_range(k); + for (auto& [_, v] : std::ranges::subrange(first, last)) + mutate(v); + } + + int main() + { + auto print = [](std::string_view rem, auto const& mm) + { + std::cout << rem << "{ "; + for (const auto& [k, v] : mm) + std::cout << '{' << k << ",'" << v << "'} "; + std::cout << "}\\n"; + }; + + std::multimap mm{{4,'a'}, {3,'-'}, {4,'b'}, {5,'-'}, {4,'c'}}; + print("Before: ", mm); + mutate_map_values(mm, 4); + print("After: ", mm); + } + +.SH Output: + + Before: { {3,'-'} {4,'a'} {4,'b'} {4,'c'} {5,'-'} } + After: { {3,'-'} {4,'A'} {4,'B'} {4,'C'} {5,'-'} } + +.SH See also + + ranges::view_interface helper class template for defining a view, using the + (C++20) curiously recurring template pattern + \fI(class template)\fP diff --git a/man/std::ranges::subrange::advance.3 b/man/std::ranges::subrange::advance.3 new file mode 100644 index 000000000..8cf2e4699 --- /dev/null +++ b/man/std::ranges::subrange::advance.3 @@ -0,0 +1,94 @@ +.TH std::ranges::subrange::advance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::advance \- std::ranges::subrange::advance + +.SH Synopsis + constexpr subrange& advance( std::iter_difference_t n ); \fI(since C++20)\fP + + If n >= 0, increments the stored iterator for n times, or until it is equal to the + stored sentinel, whichever comes first. Otherwise, decrements the stored iterator + for -n times. + + The stored size, if any, is adjusted accordingly (increased by -n if n < 0, + decreased by m otherwise, where m is the number of increments actually applied to + the iterator). + + The behavior is undefined if + + * I does not model bidirectional_iterator and n < 0, or + * the stored iterator is decremented after becoming a non-decrementable value. + +.SH Parameters + + n - number of maximal increments of the iterator + +.SH Return value + + *this + +.SH Complexity + + Generally min(n, size()) increments or -n decrements on the iterator, when n >= 0 or + n < 0 respectively. + + Constant if I models random_access_iterator, and either n < 0 or + std::sized_sentinel_for is modeled. + +.SH Notes + + The stored size presents if and only if K == ranges::subrange_kind::sized but + std::sized_sentinel_for is not satisfied. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto name, auto const sub) { + std::cout << name << ".size() == " << sub.size() << "; { "; + std::ranges::for_each(sub, [](int x) { std::cout << x << ' '; }); + std::cout << "}\\n"; + }; + + int main() + { + std::array arr{1,2,3,4,5,6,7}; + std::ranges::subrange sub{ std::next(arr.begin()), std::prev(arr.end()) }; + print("1) sub", sub); + print("2) sub", sub.advance(3)); + print("3) sub", sub.advance(-2)); + } + +.SH Output: + + 1) sub.size() == 5; { 2 3 4 5 6 } + 2) sub.size() == 2; { 5 6 } + 3) sub.size() == 4; { 3 4 5 6 } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3433 C++20 the specification mishandled the cases when n < corrected + 0 + +.SH See also + + next obtains a copy of the subrange with its iterator advanced by a given + (C++20) distance + \fI(public member function)\fP + prev obtains a copy of the subrange with its iterator decremented by a + (C++20) given distance + \fI(public member function)\fP + advance advances an iterator by given distance + \fI(function template)\fP + ranges::advance advances an iterator by given distance or to a given bound + (C++20) (niebloid) diff --git a/man/std::ranges::subrange::begin.3 b/man/std::ranges::subrange::begin.3 new file mode 100644 index 000000000..93832a718 --- /dev/null +++ b/man/std::ranges::subrange::begin.3 @@ -0,0 +1,49 @@ +.TH std::ranges::subrange::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::begin \- std::ranges::subrange::begin + +.SH Synopsis + constexpr I begin() const requires std::copyable; \fB(1)\fP \fI(since C++20)\fP + [[nodiscard]] constexpr I begin() requires (!std::copyable); \fB(2)\fP \fI(since C++20)\fP + + Obtains the iterator to the first element of the subrange, or the end iterator if + the view is empty. + + range-begin-end.svg + + 1) Returns a copy of the stored iterator if the iterator type is copyable. + 2) Returns an iterator move-constructed from the stored iterator if the iterator + type is not copyable. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) An iterator copy-constructed from the stored iterator. + 2) An iterator move-constructed from the stored iterator. + +.SH Notes + + A call to \fB(2)\fP may leave the stored iterator in a valid but unspecified state, + depending on the behavior of the move constructor of I. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end obtains the sentinel + (C++20) \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange::empty.3 b/man/std::ranges::subrange::empty.3 new file mode 100644 index 000000000..eb5ab9fb4 --- /dev/null +++ b/man/std::ranges::subrange::empty.3 @@ -0,0 +1,34 @@ +.TH std::ranges::subrange::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::empty \- std::ranges::subrange::empty + +.SH Synopsis + constexpr bool empty() const; \fI(since C++20)\fP + + Checks whether the subrange is empty, i.e. the stored iterator and sentinel compare + equal. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stored iterator and sentinel compare equal, false otherwise. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + size obtains the size of the subrange + (C++20) \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + ranges::empty checks whether a range is empty + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange::end.3 b/man/std::ranges::subrange::end.3 new file mode 100644 index 000000000..5f3125e5e --- /dev/null +++ b/man/std::ranges::subrange::end.3 @@ -0,0 +1,37 @@ +.TH std::ranges::subrange::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::end \- std::ranges::subrange::end + +.SH Synopsis + constexpr S end() const; \fI(since C++20)\fP + + Returns the sentinel indicating the end of the subrange. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A sentinel copy-constructed from the stored sentinel. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin obtains the iterator + (C++20) \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange::next.3 b/man/std::ranges::subrange::next.3 new file mode 100644 index 000000000..a18fd0fae --- /dev/null +++ b/man/std::ranges::subrange::next.3 @@ -0,0 +1,61 @@ +.TH std::ranges::subrange::next 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::next \- std::ranges::subrange::next + +.SH Synopsis + [[nodiscard]] constexpr subrange next(std::iter_difference_t n + = 1) const& \fB(1)\fP \fI(since C++20)\fP + requires std::forward_iterator; + [[nodiscard]] constexpr subrange next(std::iter_difference_t n \fB(2)\fP \fI(since C++20)\fP + = 1) &&; + + 1) Obtains a subrange whose iterator is incremented by min(n, size()) times or + decremented by -n times respect to that of *this, when n >= 0 or n < 0 respectively. + Equivalent to auto tmp = *this; tmp.advance(n); return tmp;. + 2) Increments the stored iterator by min(n, size()) times or decremented it by -n + times, when n >= 0 or n < 0 respectively, and then move-constructs the result from + *this. Equivalent to advance(n); return std::move(*this);. + + The behavior is undefined if: + + * I does not model bidirectional_iterator and n < 0, or + * the stored iterator is decremented after becoming a non-decrementable value. + +.SH Return value + + A subrange whose iterator is incremented by min(n, size()) times or decremented by + -n times respect to the original value of that of *this, when n >= 0 or n < 0 + respectively. + +.SH Complexity + + Generally min(n, size()) increments or -n decrements on the iterator, when n >= 0 or + n < 0 respectively. + + Constant if I models random_access_iterator, and either n < 0 or + std::sized_sentinel_for is modeled. + +.SH Notes + + A call to \fB(2)\fP may leave *this in a valid but unspecified state, depending on the + behavior of the move constructor of I and S. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + prev obtains a copy of the subrange with its iterator decremented by a given + (C++20) distance + \fI(public member function)\fP + advance advances the iterator by given distance + (C++20) \fI(public member function)\fP + next increment an iterator + \fI(C++11)\fP \fI(function template)\fP + ranges::next increment an iterator by a given distance or to a bound + (C++20) (niebloid) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange::operatorPairLike.3 b/man/std::ranges::subrange::operatorPairLike.3 new file mode 100644 index 000000000..66251e977 --- /dev/null +++ b/man/std::ranges::subrange::operatorPairLike.3 @@ -0,0 +1,153 @@ +.TH std::ranges::subrange::operatorPairLike 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::operatorPairLike \- std::ranges::subrange::operatorPairLike + +.SH Synopsis + template< /* see below */ PairLike > + + requires pair-like-convertible-from + + constexpr operator PairLike() const; + Helper concepts + template< class T > + + concept pair-like = + !std::is_reference_v && requires(T t) { + typename std::tuple_size::type; // + ensures std::tuple_size + // is + complete + requires + std::derived_from, + (until C++23) + std::integral_constant>; \fB(2)\fP (exposition + typename std::tuple_element_t<0, only*) + std::remove_const_t>; + typename std::tuple_element_t<1, + std::remove_const_t>; + { std::get<0>(t) } -> std::convertible_to< + const + std::tuple_element_t<0, T>&>; + { std::get<1>(t) } -> std::convertible_to< + const + std::tuple_element_t<1, T>&>; + + }; + template< class T, class U, class V > + + concept pair-like-convertible-from = + !ranges::range && pair-like && (until C++23) + std::constructible_from && (exposition + convertible-to-non-slicing> && + + std::convertible_to>; + template< class T, class U, class V > \fB(3)\fP + + concept pair-like-convertible-from = + !ranges::range && !std::is_reference_v + && pair-like && (since C++23) + std::constructible_from && (exposition + convertible-to-non-slicing> && + + std::convertible_to>; + + 1) Converts subrange to a pair-like type (i.e. a type models + the helper concept pair-like defined below + (until C++23) + pair-like + (since C++23)). Equivalent to return PairLike(i_, s_);, where i_ and s_ are the + stored iterator and sentinel respectively. + PairLike is constrained that std::same_as, subrange> + is false. + This conversion function has additional constraints imposed by pair-like-convertible + (see below). + 2) The exposition-only concept pair-like specifies a type is pair-like. Generally, + an expression e of a pair-like type can be used for structured binding (i.e. auto + const& [x, y] = e; is generally well-formed). + This concept is replaced by the library-wide exposition-only concept pair-like. + (since C++23) + 3) The exposition-only concept pair-like-convertible-from refines pair-like. It + * rejects + reference types and + (since C++23)range types, + * requires that U and V are convertible to the first and second element type of T + respectively, and + * requires the conversion from U (which will be replaced by const I&) to the first + element type to be non-slicing (see convertible-to-non-slicing). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A PairLike value direct-initialized with the stored iterator and sentinel. + +.SH Notes + + Following types in the standard library are pair-like: + + * std::pair + * std::tuple + * std::array + * std::ranges::subrange + + * std::complex (since C++26) + + A program-defined type derived from one of these types can be a + pair-like type, if + + * std::tuple_size and std::tuple_element are correctly specialized (until C++23) + for it, and + * calls to std::get<0> and std::get<1> for its value are + well-formed. + + Since subrange specializations are range types, conversion to them are not performed + via this conversion function. + + std::array specializations cannot be converted from subrange, since they are range + types. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + using striter = std::string::const_iterator; + + using legacy_strview = std::pair; + + void legacy_print(legacy_strview p) + { + for (; p.first != p.second; ++p.first) + std::cout << *p.first << ' '; + std::cout << '\\n'; + } + + int main() + { + std::string dat{"ABCDE"}; + for (auto v{std::ranges::subrange{dat}}; v; v = {v.begin(), v.end() - 1}) + { + /*...*/ + legacy_print(legacy_strview{v}); + } + } + +.SH Output: + + A B C D E + A B C D + A B C + A B + A diff --git a/man/std::ranges::subrange::prev.3 b/man/std::ranges::subrange::prev.3 new file mode 100644 index 000000000..4216b5913 --- /dev/null +++ b/man/std::ranges::subrange::prev.3 @@ -0,0 +1,51 @@ +.TH std::ranges::subrange::prev 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::prev \- std::ranges::subrange::prev + +.SH Synopsis + [[nodiscard]] constexpr subrange prev( std::iter_difference_t n = + 1 ) const \fI(since C++20)\fP + requires std::bidirectional_iterator; + + Obtains a subrange whose iterator is decremented by n times or incremented by + min(-n, size()) times respect to that of *this, when n >= 0 or n < 0 respectively. + + Equivalent to auto tmp = *this; tmp.advance(-n); return tmp;. The behavior is + undefined if the iterator is decremented after being a non-decrementable value. + +.SH Parameters + + n - number of minimal decrements of the iterator + +.SH Return value + + A subrange whose iterator is decremented by n times or incremented by min(-n, + size()) times respect to that of *this, when n >= 0 or n < 0 respectively. + +.SH Complexity + + Generally n decrements or min(-n, size()) increments on the iterator, when n >= 0 or + n < 0 respectively. + + Constant if I models random_access_iterator, and either n >= 0 or + std::sized_sentinel_for is modeled. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + next obtains a copy of the subrange with its iterator advanced by a given + (C++20) distance + \fI(public member function)\fP + advance advances the iterator by given distance + (C++20) \fI(public member function)\fP + prev decrement an iterator + \fI(C++11)\fP \fI(function template)\fP + ranges::prev decrement an iterator by a given distance or to a bound + (C++20) (niebloid) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange::size.3 b/man/std::ranges::subrange::size.3 new file mode 100644 index 000000000..65f30314b --- /dev/null +++ b/man/std::ranges::subrange::size.3 @@ -0,0 +1,46 @@ +.TH std::ranges::subrange::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::size \- std::ranges::subrange::size + +.SH Synopsis + constexpr /* see below */ size() const \fI(since C++20)\fP + requires (K == ranges::subrange_kind::sized); + + Obtains the number of elements in the subrange. + + The return type is the corresponding unsigned version of std::iter_difference_t. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + s_ - i_ explicitly converted to the return type, where i_ and s_ are the stored + iterator and sentinel respectively, if the size is not stored. + + Otherwise, the stored size. + +.SH Notes + + The size is stored into a subrange if and only if K == ranges::subrange_kind::sized + but std::sized_sentinel_for is not satisfied. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + empty checks whether the subrange is empty + (C++20) \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange::subrange.3 b/man/std::ranges::subrange::subrange.3 new file mode 100644 index 000000000..334233c89 --- /dev/null +++ b/man/std::ranges::subrange::subrange.3 @@ -0,0 +1,104 @@ +.TH std::ranges::subrange::subrange 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange::subrange \- std::ranges::subrange::subrange + +.SH Synopsis + subrange() requires std::default_initializable = default; \fB(1)\fP (since + C++20) + constexpr subrange( /*convertible-to-non-slicing*/ auto i, S s ) \fB(2)\fP (since + requires (!/*store-size*/); C++20) + constexpr subrange( /*convertible-to-non-slicing*/ auto i, S s, + + /*make-unsigned-like-t*/> \fB(3)\fP (since + n ) C++20) + + requires (K == ranges::subrange_kind::sized); + template< /*different-from*/ R > + + requires ranges::borrowed_range && + /*convertible-to-non-slicing*/, I> && \fB(4)\fP (since + std::convertible_to, S> C++20) + + constexpr subrange( R&& r ) requires (!/*store-size*/ || + ranges::sized_range); + template< ranges::borrowed_range R> + + requires /*convertible-to-non-slicing*/, I> && + std::convertible_to, S> + constexpr subrange( R&& r, \fB(5)\fP (since + /*make-unsigned-like-t*/> n ) C++20) + requires (K == ranges::subrange_kind::sized) + : subrange{ranges::begin(r), ranges::end(r), n} + + {} + + Constructs a subrange. + + If K == ranges::subrange_kind::sized && !std::sized_sentinel_for, the size of + the range is stored into the subrange, as if stored by a member subobject of type + /*make-unsigned-like-t*/>, where make-unsigned-like-t is + an exposition-only alias template that maps each integer-like type to its + corresponding unsigned version. Otherwise, the size is not stored. The constant + store-size is true if the size is stored, false otherwise. + + 1) Default constructor. Value-initializes the stored iterator and sentinel as if by + default member initializers = I() and = S(), respectively. If the size is stored, it + is initialized with 0 as if by the default member initializer = 0. + 2) Constructs a subrange from an iterator-sentinel pair. Initializes the stored + iterator and sentinel with std::move(i) and s respectively. The behavior is + undefined if [i, s) is not a valid range. + 3) Constructs a subrange from an iterator-sentinel pair and a size hint. Initializes + the stored iterator and sentinel with std::move(i) and s respectively. If the size + is stored, it is initialized with n. The behavior is undefined if [i, s) is not a + valid range, or n is not equal to ranges::distance(i, s) explicitly converted to its + type. + 4) Constructs a subrange from a range. Equivalent to subrange(r, + static_cast>>(ranges::size(r))) + if the size is stored. Otherwise, equivalent to subrange(ranges::begin(r), + ranges::end(r)). + 5) Constructs a subrange from a range and a size hint. The behavior is undefined if + n is not equal to ranges::distance(ranges::begin(r), ranges::end(r)) explicitly + converted to its type. + + The exposition only concept different-from is modeled by types T and U if and only + if std::decay_t and std::decay_t are different types. + + The exposition only concept convertible-to-non-slicing is satisfied or modeled by + From and To if and only if std::convertible_to is satisfied or modeled + respectively, and any of following conditions is satisfied: + + * either std::decay_t or std::decay_t is not a pointer type, + * std::remove_pointer_t(*)[] is implicitly convertible to + std::remove_pointer_t(*)[], i.e., the conversion from From to To is at most + a qualification conversion. + +.SH Parameters + + i - iterator that denotes the beginning of the range + s - sentinel that denotes the end of the range + r - range + n - size hint, must be equal to the size of the range + +.SH Notes + + The exposition-only concept convertible-to-non-slicing forbids the conversion from + the pointer to derived class to the pointer to base class. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3470 C++20 convertible-to-non-slicing rejected some valid made accepted + qualification conversions + P2393R1 C++20 implicit conversion to an integer-class type made explicit + might be invalid + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::subrange_kind.3 b/man/std::ranges::subrange_kind.3 new file mode 100644 index 000000000..04b1fbfd1 --- /dev/null +++ b/man/std::ranges::subrange_kind.3 @@ -0,0 +1,18 @@ +.TH std::ranges::subrange_kind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::subrange_kind \- std::ranges::subrange_kind + +.SH Synopsis + Defined in header + enum class subrange_kind : bool { + + unsized, \fI(since C++20)\fP + sized + + }; + + Specifies if a std::ranges::subrange models std::ranges::sized_range or not. + + Constant Explanation + unsized specifies that the subrange does not model sized_range + sized specifies that the subrange does model sized_range diff --git a/man/std::ranges::swap.3 b/man/std::ranges::swap.3 new file mode 100644 index 000000000..db08c0fe2 --- /dev/null +++ b/man/std::ranges::swap.3 @@ -0,0 +1,174 @@ +.TH std::ranges::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::swap \- std::ranges::swap + +.SH Synopsis + Defined in header + namespace ranges { + + inline namespace /* unspecified */ { + inline constexpr /* unspecified */ swap = /* \fI(since C++20)\fP + unspecified */; (customization point object) + } + + } + Call signature + template< class T, class U > + constexpr void ranges::swap( T&& t, U&& u ) \fI(since C++20)\fP + noexcept(/* see below */); + + Exchanges the values referenced by t and u. + + ranges::swap(t, u) is expression-equivalent to: + + 1. (void)swap(t, u), if t or u has class or enumeration type, and that expression + is valid, where the overload resolution is performed within namespace + std::ranges with the additional candidate template void swap(T&, T&) = + delete;. + * If the function selected by overload resolution does not exchange the + values referenced by t and u, the program is ill-formed; no diagnostic + required. + 2. Otherwise, (void)ranges::swap_ranges(t, u), if t and u are lvalue arrays of + equal extent (but possibly different element types) and ranges::swap(*t, *u) is + a valid expression, except that noexcept((void)ranges::swap_ranges(t, u)) is + equal to noexcept(ranges::swap(*t, *u)). + 3. Otherwise, an expression which exchanges the referenced values of t and u, if + they are both lvalues of the same type V that models std::move_constructible + and std::assignable_from. + * The result of applying the noexcept operator to that expression is equal to + std::is_nothrow_move_constructible_v && + std::is_nothrow_move_assignable_v. + * That expression is a constant expression if + * V is a LiteralType, + * both t = std::move(u)) and u = std::move(t) are constant + subexpressions, and + * the full-expressions of the initializers in the following declarations + are constant subexpressions: + * V v1(std::move(t)); + * V v2(std::move(u)); + 4. Otherwise, ranges::swap(t, u) is ill-formed, which can result in substitution + failure when ranges::swap(t, u) appears in the immediate context of a template + instantiation. + + Customization point objects + + The name ranges::swap denotes a customization point object, which is a const + function object of a literal semiregular class type. For exposition purposes, the + cv-unqualified version of its type is denoted as __swap_fn. + + All instances of __swap_fn are equal. The effects of invoking different instances of + type __swap_fn on the same arguments are equivalent, regardless of whether the + expression denoting the instance is an lvalue or rvalue, and is const-qualified or + not (however, a volatile-qualified instance is not required to be invocable). Thus, + ranges::swap can be copied freely and its copies can be used interchangeably. + + Given a set of types Args..., if std::declval()... meet the requirements for + arguments to ranges::swap above, __swap_fn models + + * std::invocable<__swap_fn, Args...>, + * std::invocable, + * std::invocable<__swap_fn&, Args...>, and + * std::invocable. + + Otherwise, no function call operator of __swap_fn participates in overload + resolution. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(std::string_view name, + std::ranges::common_range auto const& p, + std::ranges::common_range auto const& q) + { + std::cout << name << "1{ "; + for (auto const& i : p) + std::cout << i << ' '; + std::cout << "}, " << name << "2{ "; + for (auto const& i : q) + std::cout << i << ' '; + std::cout << "}\\n"; + } + + void print(std::string_view name, int p, int q) + { + std::cout << name << "1 = " << p << ", " << name << "2 = " << q << '\\n'; + } + + struct IntLike + { + int v; + }; + + void swap(IntLike& lhs, int& rhs) + { + std::swap(lhs.v, rhs); + } + + void swap(int& lhs, IntLike& rhs) + { + std::swap(lhs, rhs.v); + } + + std::ostream& operator<<(std::ostream& out, IntLike i) + { + return out << i.v; + } + + int main() + { + std::vector a1{10, 11, 12}, a2{13, 14}; + std::ranges::swap(a1, a2); + print("a", a1, a2); + + std::array b1{15, 16, 17}, b2{18, 19, 20}; + std::ranges::swap(b1, b2); + print("b", b1, b2); + + // std::array c1{1, 2, 3}; std::array c2{4, 5}; + // std::ranges::swap(c1, c2); // error: no swap found by ADL + + int d1[]{21, 22, 23}, d2[]{24, 25, 26}; + std::ranges::swap(d1, d2); + print("d", d1, d2); + + // int e1[]{1, 2, 3}, e2[]{4, 5}; + // std::ranges::swap(e1, e2); // error: extents mismatch + + // char f1[]{1, 2, 3}; + // int f2[]{4, 5, 6}; + // std::ranges::swap(f1, f2); // error: no swap(*f1, *f2) found by ADL + + IntLike g1[]{1, 2, 3}; + int g2[]{4, 5, 6}; + std::ranges::swap(g1, g2); // heterogeneous swap supported + print("g", g1, g2); + + int h1{27}, h2{28}; + std::ranges::swap(h1, h2); + print("h", h1, h2); + } + +.SH Output: + + a1{ 13 14 }, a2{ 10 11 12 } + b1{ 18 19 20 }, b2{ 15 16 17 } + d1{ 24 25 26 }, d2{ 21 22 23 } + g1{ 4 5 6 }, g2{ 1 2 3 } + h1 = 28, h2 = 27 + +.SH See also + + swappable specifies that a type can be swapped or that two types can be swapped + swappable_with with each other + (C++20) (concept) + swap swaps the values of two objects + \fI(function template)\fP diff --git a/man/std::ranges::swap_ranges,std::ranges::swap_ranges_result.3 b/man/std::ranges::swap_ranges,std::ranges::swap_ranges_result.3 new file mode 100644 index 000000000..44c490dae --- /dev/null +++ b/man/std::ranges::swap_ranges,std::ranges::swap_ranges_result.3 @@ -0,0 +1,158 @@ +.TH std::ranges::swap_ranges,std::ranges::swap_ranges_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::swap_ranges,std::ranges::swap_ranges_result \- std::ranges::swap_ranges,std::ranges::swap_ranges_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2 > (since + requires std::indirectly_swappable \fB(1)\fP C++20) + constexpr swap_ranges_result + + swap_ranges( I1 first1, S1 last1, I2 first2, S2 last2 ); + template< ranges::input_range R1, ranges::input_range R2 > + + requires std::indirectly_swappable, + ranges::iterator_t> \fB(2)\fP (since + constexpr swap_ranges_result, C++20) + ranges::borrowed_iterator_t> + + swap_ranges( R1&& r1, R2&& r2 ); +.SH Helper types + template< class I1, class I2 > \fB(3)\fP (since + using swap_ranges_result = ranges::in_in_result; C++20) + + 1) Exchanges elements between first range [first1, first1 + M) and second range + [first2, first2 + M) via ranges::iter_swap(first1 + i, first2 + i), where M = + ranges::min(ranges::distance(first1, last1), ranges::distance(first2, last2)). + The ranges [first1, last1) and [first2, last2) must not overlap. + 2) Same as \fB(1)\fP, but uses r1 as the first range and r2 as the second range, as if + using ranges::begin(r1) as first1, ranges::end(r1) as last1, ranges::begin(r2) as + first2, and ranges::end(r2) as last2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the first range of elements to swap + first2, last2 - the second range of elements to swap + r1 - the first range of elements to swap + r2 - the second range of elements to swap. + +.SH Return value + + {first1 + M, first2 + M}. + +.SH Complexity + + Exactly M swaps. + +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + models contiguous_iterator and swapping its value type calls neither non-trivial + special member function nor ADL-found swap. + +.SH Possible implementation + + struct swap_ranges_fn + { + template S1, + std::input_iterator I2, std::sentinel_for S2> + requires std::indirectly_swappable + constexpr ranges::swap_ranges_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2) const + { + for (; !(first1 == last1 or first2 == last2); ++first1, ++first2) + ranges::iter_swap(first1, first2); + return {std::move(first1), std::move(first2)}; + } + + template + requires std::indirectly_swappable, ranges::iterator_t> + constexpr ranges::swap_ranges_result, + ranges::borrowed_iterator_t> + operator()(R1&& r1, R2&& r2) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2)); + } + }; + + inline constexpr swap_ranges_fn swap_ranges {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + auto print(std::string_view name, auto const& seq, std::string_view term = "\\n") + { + std::cout << name << " : "; + for (const auto& elem : seq) + std::cout << elem << ' '; + std::cout << term; + } + + int main() + { + std::vector p {'A', 'B', 'C', 'D', 'E'}; + std::list q {'1', '2', '3', '4', '5', '6'}; + + print("p", p); + print("q", q, "\\n\\n"); + + // swap p[0, 2) and q[1, 3): + std::ranges::swap_ranges(p.begin(), + p.begin() + 4, + std::ranges::next(q.begin(), 1), + std::ranges::next(q.begin(), 3)); + print("p", p); + print("q", q, "\\n\\n"); + + // swap p[0, 5) and q[0, 5): + std::ranges::swap_ranges(p, q); + + print("p", p); + print("q", q); + } + +.SH Output: + + p : A B C D E + q : 1 2 3 4 5 6 + + p : 2 3 C D E + q : 1 A B 4 5 6 + + p : 1 A B 4 5 + q : 2 3 C D E 6 + +.SH See also + + iter_swap swaps the values referenced by two dereferenceable objects + (C++20) (customization point object) + ranges::swap swaps the values of two objects + (C++20) (customization point object) + swap_ranges swaps two ranges of elements + \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + swap swaps the values of two objects + \fI(function template)\fP diff --git a/man/std::ranges::take_view::base.3 b/man/std::ranges::take_view::base.3 new file mode 100644 index 000000000..d3ec99a38 --- /dev/null +++ b/man/std::ranges::take_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::take_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::base \- std::ranges::take_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_view::begin.3 b/man/std::ranges::take_view::begin.3 new file mode 100644 index 000000000..0d0e56eba --- /dev/null +++ b/man/std::ranges::take_view::begin.3 @@ -0,0 +1,101 @@ +.TH std::ranges::take_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::begin \- std::ranges::take_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__SimpleView); \fB(1)\fP \fI(since C++20)\fP + constexpr auto begin() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + Returns an iterator to the first element of the take_view. + + 1) Returns a std::counted_iterator or a ranges::iterator_t. + 2) Returns a std::counted_iterator or a ranges::iterator_t. + + Overload \fB(1)\fP does not participate in overload resolution if V is a simple view (that + is, if V and const V are views with the same iterator and sentinel types). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The result depends on the concepts satisfied by possibly const-qualified underlying + view type Base_, which is V (for overload \fB(1)\fP) or const V (for overload \fB(2)\fP). + + Let base_ be the underlying view, count_ be the number passed to the constructor (0 + if default initialized). + + The underlying random_access_range + view satisfies + ... yes no + std::counted_iterator(ranges::begin(base_), + yes ranges::begin(base_) + sized_range + ranges::range_difference_t(this->size())) + no std::counted_iterator(ranges::begin(base_), count_) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + using namespace std::literals; + + int main() + { + { + static constexpr auto v = {"∀x"sv, "∃y"sv, "ε"sv, "δ"sv}; + auto view = std::ranges::take_view(v, 8); + auto iter = view.begin(); + std::cout << *iter << '\\n'; + static_assert( + std::ranges::sized_range and + std::ranges::random_access_range and + std::is_same_v + ); + } + + { + std::forward_list v = {"Ax"sv, "Ey"sv, "p"sv, "q"sv}; + auto view = std::ranges::take_view(v, 8); + auto iter = view.begin(); + std::cout << *iter << '\\n'; + static_assert( + not std::ranges::sized_range and + not std::ranges::random_access_range and + std::is_same_v::iterator>> + ); + } + } + +.SH Output: + + ∀x + Ax + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2393R1 C++20 implicit conversions between signed and unsigned made explicit + integer-class types might fail + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + counted_iterator iterator adaptor that tracks the distance to the end of the range + (C++20) \fI(class template)\fP + operator== compares a sentinel with an iterator returned from take_view::begin + (C++20) \fI(function)\fP diff --git a/man/std::ranges::take_view::end.3 b/man/std::ranges::take_view::end.3 new file mode 100644 index 000000000..5a67cd96a --- /dev/null +++ b/man/std::ranges::take_view::end.3 @@ -0,0 +1,94 @@ +.TH std::ranges::take_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::end \- std::ranges::take_view::end + +.SH Synopsis + constexpr auto end() requires (!__SimpleView); \fB(1)\fP \fI(since C++20)\fP + constexpr auto end() const requires ranges::range; \fB(2)\fP \fI(since C++20)\fP + + Returns a sentinel or an iterator representing the end of the take_view. The end of + the take_view is either one past the count-th element in the underlying range, or + the end of the underlying range if the latter has less than count elements. + + 1) Returns a take_view::/*sentinel*/, a std::default_sentinel_t, or a + ranges::iterator_t. + 2) Returns a take_view::/*sentinel*/, a std::default_sentinel_t, or a + ranges::iterator_t. + + Overload \fB(1)\fP does not participate in overload resolution if V is a simple view (that + is, if V and const V are views with the same iterator and sentinel types). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The result depends on the concepts satisfied by possibly const-qualified underlying + view type Base_, that is V (for overload \fB(1)\fP) or const V (for overload \fB(2)\fP). + + Let base_ be the underlying view. + + The underlying random_access_range + view satisfies + ... yes no + ranges::begin(base_) + + yes std::default_sentinel + sized_range ranges::range_difference_t(this->size()) + no 1) /*sentinel*/{ranges::end(base_)} + 2) /*sentinel*/{ranges::end(base_)} + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + const auto list1 = {3, 1, 4, 1, 5}; + const auto seq1 = list1 | std::views::take(4); + static_assert(std::ranges::sized_range && + std::ranges::random_access_range && + std::is_same_v); + for (auto it = seq1.begin(); it != seq1.end(); ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + + std::list list2 = {2, 7, 1, 8, 2}; + const auto seq2 = list2 | std::views::take(4); + static_assert(std::ranges::sized_range && + not std::ranges::random_access_range && + std::is_same_v); + for (auto it = seq2.begin(); it != std::default_sentinel; ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 3 1 4 1 + 2 7 1 8 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2393R1 C++20 implicit conversions between signed and unsigned made explicit + integer-class types might fail + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + counted_iterator iterator adaptor that tracks the distance to the end of the range + (C++20) \fI(class template)\fP + operator== compares a sentinel with an iterator returned from take_view::begin + (C++20) \fI(function)\fP diff --git a/man/std::ranges::take_view::sentinel.3 b/man/std::ranges::take_view::sentinel.3 new file mode 100644 index 000000000..30d77875c --- /dev/null +++ b/man/std::ranges::take_view::sentinel.3 @@ -0,0 +1,37 @@ +.TH std::ranges::take_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::sentinel \- std::ranges::take_view::sentinel + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + class /*sentinel*/ (exposition only*) + + The return type of take_view::end when the underlying view is not a sized_range. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + + Data members + + Member object Definition + A sentinel of type std::sentinel_t obtained from (possibly + end_ (private) const-qualified) V. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + base returns the underlying sentinel + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from take_view::begin + (C++20) \fI(function)\fP diff --git a/man/std::ranges::take_view::sentinel::base.3 b/man/std::ranges::take_view::sentinel::base.3 new file mode 100644 index 000000000..ed28adaaa --- /dev/null +++ b/man/std::ranges::take_view::sentinel::base.3 @@ -0,0 +1,24 @@ +.TH std::ranges::take_view::sentinel::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::sentinel::base \- std::ranges::take_view::sentinel::base + +.SH Synopsis + constexpr ranges::sentinel_t base() const; \fI(since C++20)\fP + + Returns the underlying sentinel. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + a copy of the underlying sentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_view::sentinel::sentinel.3 b/man/std::ranges::take_view::sentinel::sentinel.3 new file mode 100644 index 000000000..f8fd5986a --- /dev/null +++ b/man/std::ranges::take_view::sentinel::sentinel.3 @@ -0,0 +1,33 @@ +.TH std::ranges::take_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::sentinel::sentinel \- std::ranges::take_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( ranges::sentinel_t end ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*sentinel*/( /*sentinel*/ s ) + + requires Const && \fB(3)\fP \fI(since C++20)\fP + + std::convertible_to, + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel. + 2) Initializes the underlying sentinel with end. + 3) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs + corresponding members. + +.SH Parameters + + end - a sentinel representing the end of (possibly const-qualified) V + s - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_view::size.3 b/man/std::ranges::take_view::size.3 new file mode 100644 index 000000000..2cdb1408a --- /dev/null +++ b/man/std::ranges::take_view::size.3 @@ -0,0 +1,55 @@ +.TH std::ranges::take_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::size \- std::ranges::take_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fB(1)\fP \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP \fI(since C++20)\fP + + Returns the number of elements, which is the smaller of the count passed to the + constructor and the size of the underlying view. + + Let base_ be the underlying view, count_ be the number passed to the constructor (0 + if default constructed). Equivalent to + + auto n = ranges::size(base_); + return ranges::min(n, static_cast(count_)); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr int arr[]{1, 2, 3}; + + for (int i = 0; i != 6; ++i) + { + const auto tv = std::ranges::take_view{arr, i}; + std::cout << tv.size() << ' '; + } + std::cout << '\\n'; + } + +.SH Output: + + 0 1 2 3 3 3 + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::take_view::take_view.3 b/man/std::ranges::take_view::take_view.3 new file mode 100644 index 000000000..53137bb05 --- /dev/null +++ b/man/std::ranges::take_view::take_view.3 @@ -0,0 +1,100 @@ +.TH std::ranges::take_view::take_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_view::take_view \- std::ranges::take_view::take_view + +.SH Synopsis + take_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit take_view( V base, \fB(2)\fP \fI(since C++20)\fP + ranges::range_difference_t count ); + + Constructs a take_view. + + 1) Default constructor. Value-initializes the underlying view and initializes the + count to 0. After construction, base() returns a copy of V() and size() returns 0. + 2) Initializes the underlying view with std::move(base) and the count with count. + After construction, base() returns a copy of base and size() returns the smaller of + count and ranges::size(base). + +.SH Parameters + + base - the underlying view + count - number of elements to take + +.SH Example + + Prints first n prime numbers that are generated using Sieve of Eratosthenes method. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + constexpr unsigned clog2(auto x) // ~ ⌈ log₂(x) ⌉ + { + return std::numeric_limits::digits - std::countl_zero(x); + } + + template + struct FirstPrimes + { + static constexpr int count = Count; + + constexpr bool operator()(int n) // is prime? + { + return n < 2 ? false : + n == 2 ? true : + n % 2 == 0 or bits_.test(n / 2) ? false : true; + } + private: + consteval static auto init() + { + std::bitset bits; + for (int n{3}; n < size_; n += 2) + for (int i{n}, j{3}, k{}; (k = i * j) < size_; j += 2) + bits.set(k / 2); + return bits; + } + + // Keep only odd numbers; 0 means it is a prime + constexpr static auto bits_ { init() }; + + // a(n) <= n * (log(n) + log(log(n))) + static constexpr int size_ = Count * (clog2(Count) + clog2(clog2(Count))); + }; + + int main() + { + constexpr FirstPrimes<42> primes; + + auto primes_view = std::ranges::take_view{ std::views::iota(1) + | std::views::filter(primes) + , primes.count }; + + std::cout << "First " << primes.count << " prime numbers are:\\n"; + for (int new_line{1}; const int prime : primes_view) + std::cout << std::setw(3) << prime << (new_line++ % 7 ? ' ' : '\\n'); + } + +.SH Output: + + First 42 prime numbers are: + 2 3 5 7 11 13 17 + 19 23 29 31 37 41 43 + 47 53 59 61 67 71 73 + 79 83 89 97 101 103 107 + 109 113 127 131 137 139 149 + 151 157 163 167 173 179 181 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was not made explicit + (P2711R1) explicit diff --git a/man/std::ranges::take_while_view::base.3 b/man/std::ranges::take_while_view::base.3 new file mode 100644 index 000000000..e42bb8f4d --- /dev/null +++ b/man/std::ranges::take_while_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::take_while_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::base \- std::ranges::take_while_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_while_view::begin.3 b/man/std::ranges::take_while_view::begin.3 new file mode 100644 index 000000000..17b65456e --- /dev/null +++ b/man/std::ranges::take_while_view::begin.3 @@ -0,0 +1,50 @@ +.TH std::ranges::take_while_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::begin \- std::ranges::take_while_view::begin + +.SH Synopsis + constexpr auto begin() requires (!__SimpleView); \fB(1)\fP \fI(since C++20)\fP + constexpr auto begin() const requires + + ranges::range && \fB(2)\fP \fI(since C++20)\fP + + std::indirect_unary_predicate>; + + Returns an iterator to the first element of the view. Effectively calls + ranges::begin on the underlying view. + + Overload \fB(1)\fP does not participate in overload resolution if V is a simple view (that + is, if V and const V are views with the same iterator and sentinel types). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + ranges::begin(base_), where base_ is the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3450 C++20 the const overload might return an iterator constrained + non-comparable to the sentinel + +.SH See also + + end returns a sentinel representing the end + (C++20) \fI(public member function)\fP + operator== compares a sentinel with an iterator returned from take_while_view::begin + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_while_view::end.3 b/man/std::ranges::take_while_view::end.3 new file mode 100644 index 000000000..c00d919d0 --- /dev/null +++ b/man/std::ranges::take_while_view::end.3 @@ -0,0 +1,56 @@ +.TH std::ranges::take_while_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::end \- std::ranges::take_while_view::end + +.SH Synopsis + constexpr auto end() requires (!__SimpleView); \fB(1)\fP \fI(since C++20)\fP + constexpr auto end() const requires + + ranges::range && \fB(2)\fP \fI(since C++20)\fP + + std::indirect_unary_predicate>; + + Returns a sentinel representing the end of the view. + + Let base_ denote the underlying view. + + 1) Effectively returns /*sentinel*/(ranges::end(base_), + std::addressof(pred())). + 2) Effectively returns /*sentinel*/(ranges::end(base_), + std::addressof(pred())). + + Overload \fB(1)\fP does not participate in overload resolution if V is a simple view (that + is, if V and const V are views with the same iterator and sentinel types). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A sentinel representing the end of the view. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3450 C++20 the const overload might return a sentinel constrained + non-comparable to the iterator + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + operator== compares a sentinel with an iterator returned from take_while_view::begin + (C++20) \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_while_view::pred.3 b/man/std::ranges::take_while_view::pred.3 new file mode 100644 index 000000000..e10e47943 --- /dev/null +++ b/man/std::ranges::take_while_view::pred.3 @@ -0,0 +1,28 @@ +.TH std::ranges::take_while_view::pred 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::pred \- std::ranges::take_while_view::pred + +.SH Synopsis + constexpr const Pred& pred() const; \fI(since C++20)\fP + + Returns a reference to the stored predicate. + + If *this does not store a predicate (e.g. an exception is thrown on the assignment + to *this, which copy-constructs or move-constructs a Pred), the behavior is + undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the stored predicate. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_while_view::sentinel.3 b/man/std::ranges::take_while_view::sentinel.3 new file mode 100644 index 000000000..e203ddd67 --- /dev/null +++ b/man/std::ranges::take_while_view::sentinel.3 @@ -0,0 +1,39 @@ +.TH std::ranges::take_while_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::sentinel \- std::ranges::take_while_view::sentinel + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + class /*sentinel*/; (exposition only*) + + The return type of take_while_view::end. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member types + + Member type Definition + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + + Data members + + Member object Definition + A sentinel of type std::sentinel_t that represents the end + end_ (private) of the underlying view. + (exposition-only member object*) + parent_ (private) A pointer Pred* to the predicate. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + base returns the underlying sentinel + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from take_while_view::begin + (C++20) \fI(function)\fP diff --git a/man/std::ranges::take_while_view::sentinel::base.3 b/man/std::ranges::take_while_view::sentinel::base.3 new file mode 100644 index 000000000..491eb0d31 --- /dev/null +++ b/man/std::ranges::take_while_view::sentinel::base.3 @@ -0,0 +1,24 @@ +.TH std::ranges::take_while_view::sentinel::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::sentinel::base \- std::ranges::take_while_view::sentinel::base + +.SH Synopsis + constexpr ranges::sentinel_t base() const; \fI(since C++20)\fP + + Returns the underlying sentinel. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + a copy of the underlying sentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_while_view::sentinel::sentinel.3 b/man/std::ranges::take_while_view::sentinel::sentinel.3 new file mode 100644 index 000000000..4c13e713d --- /dev/null +++ b/man/std::ranges::take_while_view::sentinel::sentinel.3 @@ -0,0 +1,37 @@ +.TH std::ranges::take_while_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::sentinel::sentinel \- std::ranges::take_while_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( ranges::sentinel_t end, \fB(2)\fP \fI(since C++20)\fP + const Pred* pred ); + constexpr /*sentinel*/( /*sentinel*/ s ) + + requires Const && \fB(3)\fP \fI(since C++20)\fP + + std::convertible_to, + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel and the pointer to + predicate. + 2) Initializes the underlying sentinel with end and the pointer to predicate with + pred. + 3) Conversion from /*sentinel*/ to /*sentinel*/. Copy constructs + corresponding members. + +.SH Parameters + + end - a sentinel representing the end of (possibly const-qualified) V + pred - a pointer to predicate + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::take_while_view::take_while_view.3 b/man/std::ranges::take_while_view::take_while_view.3 new file mode 100644 index 000000000..1522f1033 --- /dev/null +++ b/man/std::ranges::take_while_view::take_while_view.3 @@ -0,0 +1,41 @@ +.TH std::ranges::take_while_view::take_while_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::take_while_view::take_while_view \- std::ranges::take_while_view::take_while_view + +.SH Synopsis + take_while_view() requires std::default_initializable && + std::default_initializable = \fB(1)\fP \fI(since C++20)\fP + default; + constexpr explicit take_while_view( V base, Pred pred ); \fB(2)\fP \fI(since C++20)\fP + + Constructs a take_while_view. + + 1) Default constructor. Value-initializes the underlying view and the predicate. + 2) Move constructs the underlying view from base and the predicate from pred. + +.SH Parameters + + base - underlying view + fun - predicate + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was made explicit + (P2711R1) not explicit + if Pred is not + default_initializable, the default the take_while_view is also + P2325R3 C++20 constructor not default_initializable + constructs a take_while_view which + does not contain an Pred + +.SH Category: + * Todo no example diff --git a/man/std::ranges::to.3 b/man/std::ranges::to.3 new file mode 100644 index 000000000..ed90c1567 --- /dev/null +++ b/man/std::ranges::to.3 @@ -0,0 +1,303 @@ +.TH std::ranges::to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::to \- std::ranges::to + +.SH Synopsis + Defined in header + template< class C, ranges::input_range R, class... Args > + + requires (!ranges::view) \fB(1)\fP (since C++23) + + constexpr C to( R&& r, Args&&... args ); + template< template< class... > class C, ranges::input_range R, + class... Args > \fB(2)\fP (since C++23) + constexpr auto to( R&& r, Args&&... args ); + template< class C, class... Args > + + requires (!ranges::view) \fB(3)\fP (since C++23) + + constexpr /*range adaptor closure*/ to( Args&&... args ); + template< template< class... > class C, class... Args > \fB(4)\fP (since C++23) + constexpr /*range adaptor closure*/ to( Args&&... args ); + Helper templates + template< class Container > + + constexpr bool /*reservable-container*/ = + ranges::sized_range && + requires (Container& c, ranges::range_size_t n) (exposition + { \fB(5)\fP only*) + c.reserve(n); + { c.capacity() } -> std::same_as; + { c.max_size() } -> std::same_as; + + }; + template< class Container, class Reference > + + constexpr bool /*container-appendable*/ = requires (Container& c, + Reference&& ref) + { + requires (requires { + c.emplace_back(std::forward(ref)); } || (exposition + requires { \fB(6)\fP only*) + c.push_back(std::forward(ref)); } || + requires { c.emplace(c.end(), + std::forward(ref); } || + requires { c.insert(c.end(), + std::forward(ref)); }); + + }; + template< class Reference, class C > + + constexpr auto /*container-appender*/( C& c ) + { + return [&c](Reference&& ref) + { + if constexpr (requires { + c.emplace_back(std::declval()); }) + c.emplace_back(std::forward(ref)); + else if constexpr (requires { (exposition + c.push_back(std::declval()); }) \fB(7)\fP only*) + c.push_back(std::forward(ref)); + else if constexpr (requires { c.emplace(c.end(), + + std::declval()); }) + c.emplace(c.end(), std::forward(ref)); + else + c.insert(c.end(), std::forward(ref)); + }; + + } + template< class R, class T > + + concept /*container-compatible-range*/ = \fB(8)\fP (exposition + ranges::input_range && only*) + + std::convertible_to, T>; + + The overloads of the range conversion function construct a new non-view object from + a source range as its first argument by calling a constructor taking a range, a + std::from_range_t tagged ranged constructor, a constructor taking an + iterator-sentinel pair, or by back inserting each element of the source range into + the arguments-constructed object. + + 1) Constructs an object of type C from the elements of r in the following: + a) If C does not satisfy input_range or + std::convertible_to, ranges::range_value_t> is true: + 1) Constructing a non-view object as if direct-initializing (but not + direct-list-initializing) an object of type C from the source range + std::forward(r) and the rest of the functional arguments + std::forward(args)... if std::constructible_from is true. + 2) Otherwise, constructing a non-view object as if direct-initializing (but not + direct-list-initializing) an object of type C from additional disambiguation tag + std::from_range, the source range std::forward(r) and the rest of the functional + arguments std::forward(args)... if std::constructible_from is true. + 3) Otherwise, constructing a non-view object as if direct-initializing (but not + direct-list-initializing) an object of type C from the iterator-sentinel pair + (ranges::begin(r) as an iterator and ranges::end(r) as sentinel, where iterator and + sentinel have the same type. In other words, the source range must be a common + range), and the rest of function arguments std::forward(args)... if all of the + conditions below are true: + * ranges::common_range + * If std::iterator_traits>::iterator_category is valid and + denotes a type that satisfies std::derived_from + * std::constructible_from, ranges::sentinel_t, + Args...> + 4) Otherwise, constructing a non-view range object as if direct-initializing (but + not direct-list-initializing) an object of type C from the rest of the function + arguments std::forward(args)... with the following equivalent call below after + the construction: + + if constexpr (ranges::sized_range && /*reservable-container*/) + c.reserve(static_cast>(ranges::size(r))); + ranges::for_each(r, /*container-appender*/(c)); + If the R satisfies sized_range and C satisfies /*reservable-container*/, the + constructed object c of type C is able to reserve storage with the initial storage + size ranges::size(r) to prevent additional allocations during inserting new + elements. Each element of r is appended to c. The operations above are valid if both + of the conditions below are true: + + * std::constructible_from + * /*container-appendable*/> + b) Otherwise, the return expression is equivalent to: + + to(ranges::ref_view(r) | views::transform([](auto&& elem) + { + return to>(std::forward(elem)); + }), std::forward(args)...) + Which allows nested range constructions within the range if + ranges::input_range> is true. + + Otherwise, the program is ill-formed. + 2) Constructs an object of deduced type from the elements of r. + + Let /*input-iterator*/ be an exposition only type that satisfies + LegacyInputIterator: + + struct /*input-iterator*/ + + { + using iterator_category = std::input_iterator_tag; + using value_type = ranges::range_value_t; + using difference_type = std::ptrdiff_t; + using pointer = + std::add_pointer_t>; + using reference = ranges::range_reference_t; + reference operator*() const; // not + defined (exposition only*) + pointer operator->() const; // not + defined + /*input-iterator*/& operator++(); // not + defined + /*input-iterator*/ operator++(int); // not + defined + bool operator==(const /*input-iterator*/&) const; // not + defined + + }; + + Let /*DEDUCE-EXPR*/ be defined as follows: + + * C(std::declval(), std::declval()...), if that expression is valid. + * Otherwise, C(std::from_range, std::declval(), std::declval()...), if + that expression is valid. + * Otherwise, C(std::declval(), + std::declval(), std::declval()...), if that expression + is valid. + * Otherwise, the program is ill-formed. + The call is equivalent to to(std::forward(r), + std::forward(args)...). + 3,4) Returns a perfect forwarding call wrapper that is also a + RangeAdaptorClosureObject. + 5) The exposition-only variable template /*reservable-container*/ is true + if it satisfies ranges::sized_range and is eligible to be reservable. + 6) The exposition-only variable template /*container-appendable*/ is true if one element of type Reference can be appended to Container + through a member function call emplace_back, push_back, emplace or insert. + 7) The exposition-only function template /*container-appender*/ returns a function + object where a call to the returned function object is expression-equivalent to + appending one element to a container. + 8) The exposition-only concept /*container-compatible-range*/ is used in the + definition of containers in constructing an input range R whose range reference type + must be convertible to T. + +.SH Parameters + + r - a source range object + args - list of the arguments to (1,2) construct a range or (3,4) bind to the last + parameters of range adaptor closure object +.SH Type requirements + - + C must be cv-unqualified class type (1,3) + +.SH Return value + + 1,2) A constructed non-view object. + 3,4) A range adaptor closure object of unspecified type, with the following + properties: + +ranges::to return type + + The return type is derived from ranges::range_adaptor_closure. + +.SH Member objects + + The returned object behaves as if it has no target object, and an std::tuple object + tup constructed with std::tuple...>(std::forward(args)...), + except that the returned object's assignment behavior is unspecified and the names + are for exposition only. + + Constructors + + The return type of ranges::to (3-4) behaves as if its copy/move constructors perform + a memberwise copy/move. It is CopyConstructible if all of its member objects + (specified above) are CopyConstructible, and is MoveConstructible otherwise. + +.SH Member function operator() + + Given an object G obtained from an earlier call to range::to(args...), when a glvalue g designating G is invoked in a function call + expression g(r), an invocation of the stored object takes place, as if by + + * ranges::to(r, std::get(g.tup)...), where + + * r is a source range object that must satisfy input_range. + * Ns is an integer pack 0, 1, ..., (sizeof...(Args) - 1). + * g is an lvalue in the call expression if it is an lvalue in the call expression, + and is an rvalue otherwise. Thus std::move(g)(r) can move the bound arguments + into the call, where g(r) would copy. + * The specified template argument is \fB(3)\fP C or \fB(4)\fP the deduced type from a class + template C that must not satisfy view. + + The program is ill-formed if g has volatile-qualified type. + +.SH Exceptions + + Only throws if construction of a non-view object throws. + +.SH Notes + + The insertion of elements into the container may involve copy which can be less + efficient than move because lvalue references are produced during the indirection + call. Users can opt-in to use views::as_rvalue to adapt the range in order for their + elements to always produce an rvalue reference during the indirection call which + implies move. + + The parentheses are mandatory when using the pipe syntax. + + auto vec = r | std::ranges::to; // error + auto vec = r | std::ranges::to(); // OK + + Feature-test macro Value Std Feature + __cpp_lib_ranges_to_container 202202L (C++23) std::ranges::to + +.SH Example + + A preview link: Compiler Explorer + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto vec = std::views::iota(1, 5) + | std::views::transform([](auto const v){ return v * 2; }) + | std::ranges::to(); + + static_assert(std::same_as>); + std::println("{}", vec); + + auto lst = vec | std::views::take(3) | std::ranges::to>(); + std::println("{}", lst); + } + +.SH Output: + + [2, 4, 6, 8] + [2, 4, 6] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.5.7 Range conversions [range.utility.conv] + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the nested construction branch of + LWG 3984 C++23 ranges::to made well-formed + resulted to program ill-formed if R& + does not model viewable_range + the container insertion branch of replaced with direct + LWG 4016 C++23 ranges::to involved use of appending + insert iterators of elements to container diff --git a/man/std::ranges::transform,std::ranges::unary_transform_result,.3 b/man/std::ranges::transform,std::ranges::unary_transform_result,.3 new file mode 100644 index 000000000..fffb1fc95 --- /dev/null +++ b/man/std::ranges::transform,std::ranges::unary_transform_result,.3 @@ -0,0 +1,263 @@ +.TH std::ranges::transform,std::ranges::unary_transform_result, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform,std::ranges::unary_transform_result, \- std::ranges::transform,std::ranges::unary_transform_result, + +.SH Synopsis + + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + std::weakly_incrementable O, + + std::copy_constructible F, class Proj = std::identity > + requires std::indirectly_writable>> + constexpr unary_transform_result + + transform( I first1, S last1, O result, F op, Proj proj = {} ); + template< ranges::input_range R, std::weakly_incrementable O, + + std::copy_constructible F, class Proj = std::identity > + requires std::indirectly_writable, Proj>>> + constexpr unary_transform_result, O> + + transform( R&& r, O result, F op, Proj proj = {} ); + template< std::input_iterator I1, std::sentinel_for S1, + + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, + std::copy_constructible F, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::indirectly_writable, + std::projected>> + constexpr binary_transform_result + transform( I1 first1, S1 last1, I2 first2, S2 last2, O result, + + F binary_op, Proj1 proj1 = {}, Proj2 proj2 = {} ); + template< ranges::input_range R1, + + ranges::input_range R2, + std::weakly_incrementable O, + std::copy_constructible F, + class Proj1 = std::identity, class Proj2 = std::identity > + requires std::indirectly_writable, Proj1>, + std::projected, Proj2>>> + constexpr binary_transform_result, + ranges::borrowed_iterator_t, O> + transform( R1&& r1, R2&& r2, O result, F binary_op, + + Proj1 proj1 = {}, Proj2 proj2 = {} ); +.SH Helper types + template< class I, class O > \fB(5)\fP (since + using unary_transform_result = ranges::in_out_result; C++20) + template< class I1, class I2, class O > \fB(6)\fP (since + using binary_transform_result = ranges::in_in_out_result; C++20) + + Applies the given function to a range and stores the result in another range, + beginning at result. + + 1) The unary operation op is applied to the range defined by [first1, last1) (after + projecting with the projection proj). + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + 3) The binary operation binary_op is applied to pairs of elements from two ranges: + one defined by [first1, last1) and the other defined by [first2, last2) (after + respectively projecting with the projections proj1 and proj2). + 4) Same as \fB(3)\fP, but uses r1 as the first source range, as if using ranges::begin(r1) + as first1 and ranges::end(r1) as last1, and similarly for r2. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first1, last1 - the first range of elements to transform + r, r1 - the first range of elements to transform + first2, last2 - the second range of elements to transform + r2 - the second range of elements to transform + result - the beginning of the destination range, may be equal to first1 or + first2 + op, binary_op - operation to apply to the projected element(s) + proj1 - projection to apply to the elements in the first range + proj2 - projection to apply to the elements in the second range + +.SH Return value + + 1,2) A unary_transform_result contains an input iterator equal to last and an output + iterator to the element past the last element transformed. + 3,4) A binary_transform_result contains input iterators to last transformed elements + from ranges [first1, last1) and [first2, last2) as in1 and in2 respectively, and the + output iterator to the element past the last element transformed as out. + +.SH Complexity + + 1,2) Exactly ranges::distance(first1, last1) applications of op and proj. + 3,4) Exactly ranges::min(ranges::distance(first1, last1), ranges::distance(first2, + last2)) applications of binary_op and projections. + +.SH Possible implementation + + struct transform_fn + { + // First version + template S, std::weakly_incrementable O, + std::copy_constructible F, class Proj = std::identity> + requires std::indirectly_writable>> + constexpr ranges::unary_transform_result + operator()(I first1, S last1, O result, F op, Proj proj = {}) const + { + for (; first1 != last1; ++first1, (void)++result) + *result = std::invoke(op, std::invoke(proj, *first1)); + + return {first1, result}; + } + + // Second version + template + requires std::indirectly_writable, Proj>>> + constexpr ranges::unary_transform_result, O> + operator()(R&& r, O result, F op, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), result, + std::ref(op), std::ref(proj)); + } + + // Third version + template S1, + std::input_iterator I2, std::sentinel_for S2, + std::weakly_incrementable O, + std::copy_constructible F, + class Proj1 = std::identity, class Proj2 = std::identity> + requires std::indirectly_writable, + std::projected>> + constexpr ranges::binary_transform_result + operator()(I1 first1, S1 last1, I2 first2, S2 last2, O result, + F binary_op, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + for (; first1 != last1 && first2 != last2; + ++first1, (void)++first2, (void)++result) + *result = std::invoke(binary_op, + std::invoke(proj1, *first1), + std::invoke(proj2, *first2)); + + return {first1, first2, result}; + } + + // Fourth version + template + requires std::indirectly_writable, Proj1>, + std::projected, Proj2>>> + constexpr ranges::binary_transform_result, + ranges::borrowed_iterator_t, O> + operator()(R1&& r1, R2&& r2, O result, + F binary_op, Proj1 proj1 = {}, Proj2 proj2 = {}) const + { + return (*this)(ranges::begin(r1), ranges::end(r1), + ranges::begin(r2), ranges::end(r2), + result, std::ref(binary_op), + std::ref(proj1), std::ref(proj2)); + } + }; + + inline constexpr transform_fn transform; + +.SH Notes + + ranges::transform does not guarantee in-order application of op or binary_op. To + apply a function to a sequence in-order or to apply a function that modifies the + elements of a sequence, use ranges::for_each. + +.SH Example + + The following code uses ranges::transform to convert a string in place to uppercase + using the std::toupper function and then transforms each char to its ordinal value. + Then ranges::transform with a projection is used to transform elements of + std::vector into chars to fill a std::string. + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::string s{"hello"}; + auto op = [](unsigned char c) -> unsigned char { return std::toupper(c); }; + + namespace ranges = std::ranges; + + // uppercase the string in-place + ranges::transform(s.begin(), s.end(), s.begin(), op ); + + std::vector ordinals; + // convert each char to size_t + ranges::transform(s, std::back_inserter(ordinals), + [](unsigned char c) -> std::size_t { return c; }); + + std::cout << s << ':'; + for (auto ord : ordinals) + std::cout << ' ' << ord; + + // double each ordinal + ranges::transform(ordinals, ordinals, ordinals.begin(), std::plus {}); + + std::cout << '\\n'; + for (auto ord : ordinals) + std::cout << ord << ' '; + std::cout << '\\n'; + + struct Foo + { + char bar; + }; + const std::vector f = {{'h'},{'e'},{'l'},{'l'},{'o'}}; + std::string result; + // project, then uppercase + ranges::transform(f, std::back_inserter(result), op, &Foo::bar); + std::cout << result << '\\n'; + } + +.SH Output: + + HELLO: 72 69 76 76 79 + 144 138 152 152 158 + HELLO + +.SH See also + + ranges::for_each applies a function to a range of elements + (C++20) (niebloid) + ranges::transform_view a view of a sequence that applies a transformation function + views::transform to each element + (C++20) \fI(class template)\fP (range adaptor object) + applies a function to a range of elements, storing results in + transform a destination range + \fI(function template)\fP diff --git a/man/std::ranges::transform_view::base.3 b/man/std::ranges::transform_view::base.3 new file mode 100644 index 000000000..9cb8c3c36 --- /dev/null +++ b/man/std::ranges::transform_view::base.3 @@ -0,0 +1,28 @@ +.TH std::ranges::transform_view::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::base \- std::ranges::transform_view::base + +.SH Synopsis + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns a copy of the underlying view. + + 1) Copy constructs the result from the underlying view. + 2) Move constructs the result from the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A copy of the underlying view. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::begin.3 b/man/std::ranges::transform_view::begin.3 new file mode 100644 index 000000000..d99325c94 --- /dev/null +++ b/man/std::ranges::transform_view::begin.3 @@ -0,0 +1,42 @@ +.TH std::ranges::transform_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::begin \- std::ranges::transform_view::begin + +.SH Synopsis + constexpr /*iterator*/ begin(); \fB(1)\fP \fI(since C++20)\fP + constexpr /*iterator*/ begin() const + + requires ranges::range && \fB(2)\fP \fI(since C++20)\fP + + std::regular_invocable>; + + Returns an iterator to the first element of the transform_view. + + 1) Equivalent to return /*iterator*/{*this, ranges::begin(base_)};, where + base_ is the underlying view. + 2) Equivalent to return /*iterator*/{*this, ranges::begin(base_)};, where + base_ is the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::end.3 b/man/std::ranges::transform_view::end.3 new file mode 100644 index 000000000..98bc42bf6 --- /dev/null +++ b/man/std::ranges::transform_view::end.3 @@ -0,0 +1,58 @@ +.TH std::ranges::transform_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::end \- std::ranges::transform_view::end + +.SH Synopsis + constexpr /*sentinel*/ end(); \fB(1)\fP \fI(since C++20)\fP + constexpr /*iterator*/ end() requires \fB(2)\fP \fI(since C++20)\fP + ranges::common_range; + constexpr /*sentinel*/ end() const + + requires ranges::range && \fB(3)\fP \fI(since C++20)\fP + + std::regular_invocable>; + constexpr /*iterator*/ end() const + + requires ranges::common_range && \fB(4)\fP \fI(since C++20)\fP + + std::regular_invocable>; + + Returns a sentinel or an iterator representing the end of the transform_view. + + Let base_ be the underlying view: + + 1) Equivalent to return /*sentinel*/{ranges::end(base_)};. + 2) Equivalent to return /*iterator*/{*this, ranges::end(base_)};. + 3) Equivalent to return /*sentinel*/{ranges::end(base_)};. + 4) Equivalent to return /*iterator*/{*this, ranges::end(base_)};. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1,3) sentinel which compares equal to the end iterator + 2,4) iterator to the element following the last element + +.SH Notes + + end() returns an iterator if and only if the underlying view is a common_range: + transform_view models common_range whenever V does. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::iterator.3 b/man/std::ranges::transform_view::iterator.3 new file mode 100644 index 000000000..d4844136b --- /dev/null +++ b/man/std::ranges::transform_view::iterator.3 @@ -0,0 +1,94 @@ +.TH std::ranges::transform_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::iterator \- std::ranges::transform_view::iterator + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + class /*iterator*/ (exposition only*) + + The return type of transform_view::begin, and of transform_view::end when the + underlying view is a common_range. + + The type /*iterator*/ is returned by the const-qualified overloads. The type + /*iterator*/ is returned by the non-const-qualified overloads. + +.SH Member types + + Member type Definition + const ranges::transform_view if Const is true, otherwise + Parent (private) ranges::transform_view. + (exposition-only member type*) + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + std::random_access_iterator_tag if Base models + random_access_range, + iterator_concept std::bidirectional_iterator_tag if Base models + bidirectional_range, + std::forward_iterator_tag if Base models forward_range, + std::input_iterator_tag otherwise. + Not defined if Base does not model forward_range. + Otherwise, if std::invoke_result_t> is not a reference, + std::input_iterator_tag. + iterator_category + Else, let C be + std::iterator_traits>::iterator_category. + If C is std::contiguous_iterator_tag, the type is + std::random_access_iterator_tag; otherwise, the type is C. + value_type std::remove_cvref_t>> + difference_type ranges::range_difference_t + + Data members + + Member object Definition + current_ (private) An iterator into (possibly const-qualified) V. + (exposition-only member object*) + parent_ (private) A pointer to parent transform_view. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++20) \fI(public member function)\fP + base returns the underlying iterator + (C++20) \fI(public member function)\fP + operator* accesses the transformed element + (C++20) \fI(public member function)\fP + operator[] accesses an element by index + (C++20) \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++20) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++20) + operator+ performs iterator arithmetic + operator- \fI(function)\fP + (C++20) + iter_move obtains an rvalue reference to the transformed element + (C++20) \fI(function)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2259R1 C++20 member iterator_category is always defined defined only if Base + models forward_range + LWG 3555 C++20 the definition of iterator_concept ignores made to consider + const + LWG 3798 C++20 iterator_category is input-only if may have a stronger + transformation result is rvalue reference category diff --git a/man/std::ranges::transform_view::iterator::base.3 b/man/std::ranges::transform_view::iterator::base.3 new file mode 100644 index 000000000..3f5c09d69 --- /dev/null +++ b/man/std::ranges::transform_view::iterator::base.3 @@ -0,0 +1,60 @@ +.TH std::ranges::transform_view::iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::iterator::base \- std::ranges::transform_view::iterator::base + +.SH Synopsis + constexpr const ranges::iterator_t& base() const & noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr ranges::iterator_t base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns the underlying iterator. + + 1) Returns a reference to the underlying iterator. + 2) Move constructs the result from the underlying iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A reference to the underlying iterator. + 2) An iterator move constructed from the underlying iterator. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto v = { 0, 1, 2, 3, 4 }; + auto x2 = [](int x) { return x << 1; }; + std::ranges::transform_view tv{ v, x2 }; + std::ostream_iterator ostr{ std::cout, " " }; + + std::ranges::copy(v, ostr), std::cout << '\\n'; + std::ranges::copy(tv.base(), ostr), std::cout << '\\n'; + std::ranges::copy(tv, ostr), std::cout << '\\n'; + } + +.SH Output: + + 0 1 2 3 4 + 0 1 2 3 4 + 0 2 4 6 8 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3533 C++20 the const& overload of base returns a copy returns a reference + of the underlying iterator + LWG 3593 C++20 the const& overload of base might not be made noexcept + noexcept diff --git a/man/std::ranges::transform_view::iterator::iterator.3 b/man/std::ranges::transform_view::iterator::iterator.3 new file mode 100644 index 000000000..94069c6a1 --- /dev/null +++ b/man/std::ranges::transform_view::iterator::iterator.3 @@ -0,0 +1,38 @@ +.TH std::ranges::transform_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::iterator::iterator \- std::ranges::transform_view::iterator::iterator + +.SH Synopsis + /*iterator*/() requires \fB(1)\fP (since + std::default_initializable> = default; C++20) + constexpr /*iterator*/( Parent& parent, ranges::iterator_t current \fB(2)\fP (since + ); C++20) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(3)\fP (since + C++20) + std::convertible_to, + ranges::iterator_t>; + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying iterator, and initializes + the pointer to parent transform_view with nullptr. + 2) Initializes the underlying iterator with std::move(current), and the pointer to + parent with std::addressof(parent). + 3) Conversion from /*iterator*/ to /*iterator*/. Move constructs + corresponding members. + +.SH Parameters + + parent - a (possibly const-qualified) std::ranges::transform_view + current - an iterator into (possibly const-qualified) V + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::iterator::operator*.3 b/man/std::ranges::transform_view::iterator::operator*.3 new file mode 100644 index 000000000..7e96eb9b4 --- /dev/null +++ b/man/std::ranges::transform_view::iterator::operator*.3 @@ -0,0 +1,39 @@ +.TH std::ranges::transform_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::iterator::operator* \- std::ranges::transform_view::iterator::operator* + +.SH Synopsis + constexpr decltype(auto) operator*() const; \fI(since C++20)\fP + + Returns the transformed element. + + Effectively returns std::invoke(*parent_->fun_, *current_), where *parent_->fun_ is + the transformation function stored in the parent transform_view, and current_ is the + underlying iterator into V. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The transformed element. + +.SH Notes + + operator-> is not provided. + + The behavior is undefined if the pointer to parent transform_view is null (e.g. if + *this is default constructed). + + If *current_ is a prvalue, its lifetime ends before this function returns. If the + transformation function returns a reference or pointer to it, the result would + dangle. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::transform_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..ebd3c4761 --- /dev/null +++ b/man/std::ranges::transform_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,38 @@ +.TH std::ranges::transform_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::iterator::operator++,--,+=,-= \- std::ranges::transform_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP \fI(since C++20)\fP + constexpr void operator++( int ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*iterator*/ operator++( int ) \fB(3)\fP \fI(since C++20)\fP + requires ranges::forward_range; + constexpr /*iterator*/& operator--() \fB(4)\fP \fI(since C++20)\fP + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(5)\fP \fI(since C++20)\fP + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(6)\fP \fI(since C++20)\fP + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(7)\fP \fI(since C++20)\fP + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let current_ be the underlying iterator. + + 1) Equivalent to ++current_; return *this; + 2) Equivalent to ++current_; + 3) Equivalent to auto tmp = *this; ++*this; return tmp; + 4) Equivalent to --current_; return *this; + 5) Equivalent to auto tmp = *this; --*this; return tmp; + 6) Equivalent to current_ += n; return *this; + 7) Equivalent to current_ -= n; return *this; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 3,5) a copy of *this that was made before the change diff --git a/man/std::ranges::transform_view::iterator::operator[].3 b/man/std::ranges::transform_view::iterator::operator[].3 new file mode 100644 index 000000000..33ab708e5 --- /dev/null +++ b/man/std::ranges::transform_view::iterator::operator[].3 @@ -0,0 +1,29 @@ +.TH std::ranges::transform_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::iterator::operator[] \- std::ranges::transform_view::iterator::operator[] + +.SH Synopsis + constexpr decltype(auto) operator[]( difference_type n ) const \fI(since C++20)\fP + requires ranges::random_access_range; + + Returns the element at specified relative location, after transformation. + + Effectively returns std::invoke(*parent_->fun_, current_[n]), where *parent_->fun_ + is the transformation function stored in the parent transform_view, and current_ is + the underlying iterator into V. + +.SH Parameters + + n - position relative to current location. + +.SH Return value + + the transformed element + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::sentinel.3 b/man/std::ranges::transform_view::sentinel.3 new file mode 100644 index 000000000..5f81a5b6e --- /dev/null +++ b/man/std::ranges::transform_view::sentinel.3 @@ -0,0 +1,44 @@ +.TH std::ranges::transform_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::sentinel \- std::ranges::transform_view::sentinel + +.SH Synopsis + template< bool Const > \fI(since C++20)\fP + class /*sentinel*/ (exposition only*) + + The return type of transform_view::end when the underlying view is not a + common_range. + + The type /*sentinel*/ is returned by the const-qualified overload. The type + /*sentinel*/ is returned by the non-const-qualified overload. + +.SH Member types + + Member type Definition + const transform_view if Const is true, otherwise + Parent (private) transform_view. + (exposition-only member type*) + Base (private) const V if Const is true, otherwise V. + (exposition-only member type*) + + Data members + + Member object Definition + A sentinel of type std::sentinel_t obtained from (possibly + end_ (private) const-qualified) V. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + base returns the underlying sentinel + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from transform_view::begin + (C++20) \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++20) transform_view::begin + \fI(function)\fP diff --git a/man/std::ranges::transform_view::sentinel::base.3 b/man/std::ranges::transform_view::sentinel::base.3 new file mode 100644 index 000000000..eb00ab6da --- /dev/null +++ b/man/std::ranges::transform_view::sentinel::base.3 @@ -0,0 +1,24 @@ +.TH std::ranges::transform_view::sentinel::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::sentinel::base \- std::ranges::transform_view::sentinel::base + +.SH Synopsis + constexpr ranges::sentinel_t base() const; \fI(since C++20)\fP + + Returns the underlying sentinel. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + a copy of the underlying sentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::sentinel::sentinel.3 b/man/std::ranges::transform_view::sentinel::sentinel.3 new file mode 100644 index 000000000..a11a2b401 --- /dev/null +++ b/man/std::ranges::transform_view::sentinel::sentinel.3 @@ -0,0 +1,33 @@ +.TH std::ranges::transform_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::sentinel::sentinel \- std::ranges::transform_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit /*sentinel*/( ranges::sentinel_t end ); \fB(2)\fP \fI(since C++20)\fP + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(3)\fP \fI(since C++20)\fP + + std::convertible_to, + ranges::sentinel_t>; + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying sentinel. + 2) Initializes the underlying sentinel with end. + 3) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs + corresponding members. + +.SH Parameters + + end - a sentinel representing the end of (possibly const-qualified) V + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::transform_view::size.3 b/man/std::ranges::transform_view::size.3 new file mode 100644 index 000000000..46e647cc8 --- /dev/null +++ b/man/std::ranges::transform_view::size.3 @@ -0,0 +1,58 @@ +.TH std::ranges::transform_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::size \- std::ranges::transform_view::size + +.SH Synopsis + constexpr auto size() requires ranges::sized_range; \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fI(since C++20)\fP + + Returns the number of elements. + + Returns ranges::size(base_), where base_ is the underlying view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements. + +.SH Notes + + If V does not model forward_range, size() might not be well-defined after a call to + begin(). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s{"The length of this string is 42 characters"}; + auto tv = std::ranges::transform_view{s, [](char c) -> char + { + return std::toupper(c); + }}; + for (auto x : tv) + std::cout << x; + std::cout << "\\nsize = " << tv.size() << '\\n'; + } + +.SH Output: + + THE LENGTH OF THIS STRING IS 42 CHARACTERS + size = 42 + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::transform_view::transform_view.3 b/man/std::ranges::transform_view::transform_view.3 new file mode 100644 index 000000000..0dc11d6c5 --- /dev/null +++ b/man/std::ranges::transform_view::transform_view.3 @@ -0,0 +1,75 @@ +.TH std::ranges::transform_view::transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::transform_view::transform_view \- std::ranges::transform_view::transform_view + +.SH Synopsis + transform_view() requires std::default_initializable && \fB(1)\fP \fI(since C++20)\fP + std::default_initializable = default; + constexpr explicit transform_view( V base, F fun ); \fB(2)\fP \fI(since C++20)\fP + + Constructs a transform_view. + + 1) Default constructor. Value-initializes the underlying view and the transformation + function. + 2) Move constructs the underlying view from base and the transformation function + from fun. + +.SH Parameters + + base - view + fun - transformation function + +.SH Example + + Demonstrates π approximation using serial expansion of arc tangent of 1: + atan(1) = π/4 ~ 1 - 1/3 + 1/5 - 1/7 + 1/9 - 1/11 + ... + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::cout << std::setprecision(15) << std::fixed; + auto atan1term = std::ranges::views::transform( + [](int n) { return ((n % 2) ? -1 : 1) * 1.0 / (2 * n + 1); } + ); + for (const int iterations : {1, 2, 3, 4, 5, 10, 100, 1000, 1'000'000}) + { + auto seq = std::ranges::views::iota(0, iterations) | atan1term; + const double accum = std::accumulate(seq.begin(), seq.end(), 0.0); + std::cout << "π ~ " << 4 * accum << " (iterations: " << iterations << ")\\n"; + } + std::cout << "π ~ " << std::numbers::pi << " (std::numbers::pi)\\n"; + } + +.SH Possible output: + + π ~ 4.000000000000000 (iterations: 1) + π ~ 2.666666666666667 (iterations: 2) + π ~ 3.466666666666667 (iterations: 3) + π ~ 2.895238095238096 (iterations: 4) + π ~ 3.339682539682540 (iterations: 5) + π ~ 3.041839618929403 (iterations: 10) + π ~ 3.131592903558554 (iterations: 100) + π ~ 3.140592653839794 (iterations: 1000) + π ~ 3.141591653589774 (iterations: 1000000) + π ~ 3.141592653589793 (std::numbers::pi) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was made explicit + (P2711R1) not explicit + if F is not default_initializable, + P2325R3 C++20 the default constructor the transform_view is also + constructs a transform_view which not default_initializable + does not contain an F diff --git a/man/std::ranges::uninitialized_copy,std::ranges::uninitialized_copy_result.3 b/man/std::ranges::uninitialized_copy,std::ranges::uninitialized_copy_result.3 new file mode 100644 index 000000000..7d4fcba55 --- /dev/null +++ b/man/std::ranges::uninitialized_copy,std::ranges::uninitialized_copy_result.3 @@ -0,0 +1,180 @@ +.TH std::ranges::uninitialized_copy,std::ranges::uninitialized_copy_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_copy,std::ranges::uninitialized_copy_result \- std::ranges::uninitialized_copy,std::ranges::uninitialized_copy_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S1, + + no-throw-forward-iterator O, no-throw-sentinel-for S2 > + requires std::constructible_from, \fB(1)\fP (since + std::iter_reference_t> C++20) + uninitialized_copy_result + + uninitialized_copy( I ifirst, S1 ilast, O ofirst, S2 olast ); + template< ranges::input_range IR, no-throw-forward-range OR > + + requires std::constructible_from, + ranges::range_reference_t> \fB(2)\fP (since + uninitialized_copy_result, C++20) + ranges::borrowed_iterator_t> + + uninitialized_copy( IR&& in_range, OR&& out_range ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using uninitialized_copy_result = ranges::in_out_result; C++20) + + 1) Let \\(\\scriptsize N\\)N be ranges::min(ranges::distance(ifirst, ilast), + ranges::distance(ofirst, olast)), constructs \\(\\scriptsize N\\)N elements in the + output range [ofirst, olast), which is an uninitialized memory area, from the + elements in the input range [ifirst, ilast). + The input and output ranges must not overlap. + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + The function has the effect equal to: + + for (; !(ifirst == ilast || ofirst == olast); ++ofirst, ++ifirst) + { + ::new (static_cast(std::addressof(*ofirst))) + std::remove_reference_t>(*ifirst); + } + + 2) Same as \fB(1)\fP, but uses in_range as the first range and out_range as the second + range, as if using ranges::begin(in_range) as ifirst, ranges::end(in_range) as + ilast, ranges::begin(out_range) as ofirst, and ranges::end(out_range) as olast. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + ifirst, ilast - iterator-sentinel pair denoting the range of elements to copy from + in_range - the range of elements to copy from + ofirst, olast - iterator-sentinel pair denoting the destination range + out_range - the destination range + +.SH Return value + + {ifirst + N, ofirst + N} + +.SH Complexity + + \\(\\scriptsize\\mathcal{O}(N)\\)𝓞(N). + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of ranges::uninitialized_copy if the + value type of the output range is TrivialType. + +.SH Possible implementation + + struct uninitialized_copy_fn + { + template S1, + no-throw-forward-iterator O, no-throw-sentinel-for S2> + requires std::constructible_from, std::iter_reference_t> + ranges::uninitialized_copy_result + operator()(I ifirst, S1 ilast, O ofirst, S2 olast) const + { + O current{ofirst}; + try + { + for (; !(ifirst == ilast or current == olast); ++ifirst, ++current) + ranges::construct_at(std::addressof(*current), *ifirst); + return {std::move(ifirst), std::move(current)}; + } + catch (...) // rollback: destroy constructed elements + { + for (; ofirst != current; ++ofirst) + ranges::destroy_at(std::addressof(*ofirst)); + throw; + } + } + + template + requires std::constructible_from, + ranges::range_reference_t> + ranges::uninitialized_copy_result, + ranges::borrowed_iterator_t> + operator()(IR&& in_range, OR&& out_range) const + { + return (*this)(ranges::begin(in_range), ranges::end(in_range), + ranges::begin(out_range), ranges::end(out_range)); + } + }; + + inline constexpr uninitialized_copy_fn uninitialized_copy{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + const char* v[]{"This", "is", "an", "example"}; + + if (const auto sz{std::size(v)}; + void* pbuf = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz)) + { + try + { + auto first{static_cast(pbuf)}; + auto last{first + sz}; + std::ranges::uninitialized_copy(std::begin(v), std::end(v), first, last); + + std::cout << "{"; + for (auto it{first}; it != last; ++it) + std::cout << (it == first ? "" : ", ") << std::quoted(*it); + std::cout << "};\\n"; + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "uninitialized_copy exception\\n"; + } + std::free(pbuf); + } + } + +.SH Output: + + {"This", "is", "an", "example"}; + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + ranges::uninitialized_copy_n copies a number of objects to an uninitialized area of + (C++20) memory + (niebloid) + copies a range of objects to an uninitialized area of + uninitialized_copy memory + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_copy_n,std::ranges::uninitialized_copy_n_result.3 b/man/std::ranges::uninitialized_copy_n,std::ranges::uninitialized_copy_n_result.3 new file mode 100644 index 000000000..300d93876 --- /dev/null +++ b/man/std::ranges::uninitialized_copy_n,std::ranges::uninitialized_copy_n_result.3 @@ -0,0 +1,147 @@ +.TH std::ranges::uninitialized_copy_n,std::ranges::uninitialized_copy_n_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_copy_n,std::ranges::uninitialized_copy_n_result \- std::ranges::uninitialized_copy_n,std::ranges::uninitialized_copy_n_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, no-throw-input-iterator O, + no-throw-sentinel-for S > + + requires std::constructible_from, + std::iter_reference_t> \fB(1)\fP \fI(since C++20)\fP + uninitialized_copy_n_result + uninitialized_copy_n( I ifirst, std::iter_difference_t + count, + + O ofirst, S olast ); +.SH Helper types + template< class I, class O > \fB(2)\fP \fI(since C++20)\fP + using uninitialized_copy_n_result = ranges::in_out_result; + + Let \\(\\scriptsize N\\)N be ranges::min(count, ranges::distance(ofirst, olast)), + constructs \\(\\scriptsize N\\)N elements in the output range [ofirst, olast), which is + an uninitialized memory area, from the elements in the input range beginning at + ifirst. + + The input range [ifirst, ifirst + count) must not overlap with the output range + [ofirst, olast). + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + + The function has the effect equivalent to: + + auto ret = ranges::uninitialized_copy(std::counted_iterator(ifirst, count), + std::default_sentinel, ofirst, olast); + return {std::move(ret.in).base(), ret.out}; + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + ifirst - the beginning of the range of elements to copy from + count - the number of elements to copy + ofirst, olast - iterator-sentinel pair denoting the destination range + +.SH Return value + + {ifirst + N, ofirst + N} + +.SH Complexity + + \\(\\scriptsize\\mathcal{O}(N)\\)𝓞(N). + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the ranges::uninitialized_copy_n, by + using e.g. ranges::copy_n, if the value type of the output range is TrivialType. + +.SH Possible implementation + +struct uninitialized_copy_n_fn +{ + template S> + requires std::constructible_from, std::iter_reference_t> + ranges::uninitialized_copy_n_result + operator()(I ifirst, std::iter_difference_t count, O ofirst, S olast) const + { + O current{ofirst}; + try + { + for (; count > 0 && current != olast; ++ifirst, ++current, --count) + ranges::construct_at(std::addressof(*current), *ifirst); + return {std::move(ifirst), std::move(current)}; + } + catch (...) // rollback: destroy constructed elements + { + for (; ofirst != current; ++ofirst) + ranges::destroy_at(std::addressof(*ofirst)); + throw; + } + } +}; + +inline constexpr uninitialized_copy_n_fn uninitialized_copy_n{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const char* stars[]{"Procyon", "Spica", "Pollux", "Deneb", "Polaris"}; + + constexpr int n{4}; + alignas(alignof(std::string)) char out[n * sizeof(std::string)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last{first + n}; + auto ret{std::ranges::uninitialized_copy_n(std::begin(stars), n, first, last)}; + + std::cout << '{'; + for (auto it{first}; it != ret.out; ++it) + std::cout << (it == first ? "" : ", ") << std::quoted(*it); + std::cout << "};\\n"; + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "uninitialized_copy_n exception\\n"; + } + } + +.SH Output: + + {"Procyon", "Spica", "Pollux", "Deneb"}; + +.SH See also + + ranges::uninitialized_copy copies a range of objects to an uninitialized area of + (C++20) memory + (niebloid) + uninitialized_copy_n copies a number of objects to an uninitialized area of + \fI(C++11)\fP memory + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_default_construct.3 b/man/std::ranges::uninitialized_default_construct.3 new file mode 100644 index 000000000..9ab5fd5f3 --- /dev/null +++ b/man/std::ranges::uninitialized_default_construct.3 @@ -0,0 +1,190 @@ +.TH std::ranges::uninitialized_default_construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_default_construct \- std::ranges::uninitialized_default_construct + +.SH Synopsis + Defined in header + Call signature + template< no-throw-forward-iterator I, no-throw-sentinel-for S > + (since + requires std::default_initializable> \fB(1)\fP C++20) + + I uninitialized_default_construct( I first, S last ); + template< no-throw-forward-range R > + + requires std::default_initializable> \fB(2)\fP (since + ranges::borrowed_iterator_t C++20) + + uninitialized_default_construct( R&& r ); + + 1) Constructs objects of type std::iter_value_t in the uninitialized storage + designated by the range [first, last) by default-initialization, as if by + + for (; first != last; ++first) + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>; + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first, and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range of the elements to + initialize + r - the range of the elements to initialize + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may skip the objects construction (without changing the observable + effect) if no non-trivial default constructor is called while default-initializing a + std::iter_value_t object, which can be detected by + std::is_trivially_default_constructible_v. + +.SH Possible implementation + + struct uninitialized_default_construct_fn + { + template S> + requires std::default_initializable> + I operator()(I first, S last) const + { + using ValueType = std::remove_reference_t>; + if constexpr (std::is_trivially_default_constructible_v) + return ranges::next(first, last); // skip initialization + I rollback{first}; + try + { + for (; !(first == last); ++first) + ::new (const_cast(static_cast + (std::addressof(*first)))) ValueType; + return first; + } + catch (...) // rollback: destroy constructed elements + { + for (; rollback != first; ++rollback) + ranges::destroy_at(std::addressof(*rollback)); + throw; + } + } + + template + requires std::default_initializable> + ranges::borrowed_iterator_t + operator()(R&& r) const + { + return (*this)(ranges::begin(r), ranges::end(r)); + } + }; + + inline constexpr uninitialized_default_construct_fn uninitialized_default_construct{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + struct S { std::string m{"▄▀▄▀▄▀▄▀"}; }; + + constexpr int n{4}; + alignas(alignof(S)) char out[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last{first + n}; + + std::ranges::uninitialized_default_construct(first, last); + + auto count{1}; + for (auto it{first}; it != last; ++it) + std::cout << count++ << ' ' << it->m << '\\n'; + + std::ranges::destroy(first, last); + } + catch (...) { std::cout << "Exception!\\n"; } + + // Notice that for "trivial types" the uninitialized_default_construct + // generally does not zero-fill the given uninitialized memory area. + constexpr char sample[]{'A', 'B', 'C', 'D', '\\n'}; + char v[]{'A', 'B', 'C', 'D', '\\n'}; + std::ranges::uninitialized_default_construct(std::begin(v), std::end(v)); + if (std::memcmp(v, sample, sizeof(v)) == 0) + { + std::cout << " "; + // Maybe undefined behavior, pending CWG 1997: + // for (const char c : v) { std::cout << c << ' '; } + for (const char c : sample) + std::cout << c << ' '; + } + else + std::cout << "Unspecified\\n"; + } + +.SH Possible output: + + 1 ▄▀▄▀▄▀▄▀ + 2 ▄▀▄▀▄▀▄▀ + 3 ▄▀▄▀▄▀▄▀ + 4 ▄▀▄▀▄▀▄▀ + A B C D + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by + ranges::uninitialized_default_construct_n default-initialization in an uninitialized + (C++20) area of memory, defined by a start and + count + (niebloid) + constructs objects by value-initialization + ranges::uninitialized_value_construct in an uninitialized area of memory, + (C++20) defined by a range + (niebloid) + constructs objects by value-initialization + ranges::uninitialized_value_construct_n in an uninitialized area of memory, + (C++20) defined by a start and a count + (niebloid) + constructs objects by + uninitialized_default_construct default-initialization in an uninitialized + \fI(C++17)\fP area of memory, defined by a range + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_default_construct_n.3 b/man/std::ranges::uninitialized_default_construct_n.3 new file mode 100644 index 000000000..335248435 --- /dev/null +++ b/man/std::ranges::uninitialized_default_construct_n.3 @@ -0,0 +1,174 @@ +.TH std::ranges::uninitialized_default_construct_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_default_construct_n \- std::ranges::uninitialized_default_construct_n + +.SH Synopsis + Defined in header + Call signature + template< no-throw-forward-iterator I > + + requires std::default_initializable> \fI(since C++20)\fP + + I uninitialized_default_construct_n( I first, + std::iter_difference_t n ); + + Constructs n objects of type std::iter_value_t in the uninitialized memory area + starting at first by default-initialization, as if by + + for (; n-- > 0; ++first) + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>; + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to initialize + n - the number of elements to construct + +.SH Return value + + The end of the range of objects (i.e., ranges::next(first, n)). + +.SH Complexity + + Linear in n. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may skip the objects construction (without changing the observable + effect) if no non-trivial default constructor is called while default-initializing a + std::iter_value_t object, which can be detected by + std::is_trivially_default_constructible_v. + +.SH Possible implementation + +struct uninitialized_default_construct_n_fn +{ + template + requires std::default_initializable> + I operator()(I first, std::iter_difference_t n) const + { + using ValueType = std::remove_reference_t>; + if constexpr (std::is_trivially_default_constructible_v) + return ranges::next(first, n); // skip initialization + I rollback{first}; + try + { + for (; n-- > 0; ++first) + ::new (const_cast(static_cast + (std::addressof(*first)))) ValueType; + return first; + } + catch (...) // rollback: destroy constructed elements + { + for (; rollback != first; ++rollback) + ranges::destroy_at(std::addressof(*rollback)); + throw; + } + } +}; + +inline constexpr uninitialized_default_construct_n_fn uninitialized_default_construct_n{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + struct S { std::string m{"█▓▒░ █▓▒░ "}; }; + + constexpr int n{4}; + alignas(alignof(S)) char out[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last = std::ranges::uninitialized_default_construct_n(first, n); + + auto count{1}; + for (auto it{first}; it != last; ++it) + std::cout << count++ << ' ' << it->m << '\\n'; + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_default_construct_n + // generally does not zero-fill the given uninitialized memory area. + constexpr int sample[]{1, 2, 3, 4, 5, 6}; + int v[]{1, 2, 3, 4, 5, 6}; + std::ranges::uninitialized_default_construct_n(std::begin(v), std::size(v)); + if (std::memcmp(v, sample, sizeof(v)) == 0) + { + // Maybe undefined behavior, pending CWG 1997: + // for (const int i : v) { std::cout << i << ' '; } + for (const int i : sample) + std::cout << i << ' '; + } + else + std::cout << "Unspecified!"; + std::cout << '\\n'; + } + +.SH Possible output: + + 1 █▓▒░ █▓▒░ + 2 █▓▒░ █▓▒░ + 3 █▓▒░ █▓▒░ + 4 █▓▒░ █▓▒░ + 1 2 3 4 5 6 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by default-initialization + ranges::uninitialized_default_construct in an uninitialized area of memory, defined + (C++20) by a range + (niebloid) + constructs objects by value-initialization + ranges::uninitialized_value_construct in an uninitialized area of memory, defined + (C++20) by a range + (niebloid) + constructs objects by value-initialization + ranges::uninitialized_value_construct_n in an uninitialized area of memory, defined + (C++20) by a start and a count + (niebloid) + constructs objects by default-initialization + uninitialized_default_construct_n in an uninitialized area of memory, defined + \fI(C++17)\fP by a start and a count + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_fill.3 b/man/std::ranges::uninitialized_fill.3 new file mode 100644 index 000000000..dd4de7b71 --- /dev/null +++ b/man/std::ranges::uninitialized_fill.3 @@ -0,0 +1,160 @@ +.TH std::ranges::uninitialized_fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_fill \- std::ranges::uninitialized_fill + +.SH Synopsis + Defined in header + Call signature + template< no-throw-forward-iterator I, no-throw-sentinel-for S, class + T > + \fB(1)\fP (since + requires std::constructible_from, const T&> C++20) + + I uninitialized_fill( I first, S last, const T& x ); + template< no-throw-forward-range R, class T > + + requires std::constructible_from, const T&> \fB(2)\fP (since + ranges::borrowed_iterator_t C++20) + + uninitialized_fill( R&& r, const T& x ); + + 1) Constructs \\(\\scriptsize N\\)N copies of the given value x in an uninitialized + memory area, designated by the range [first, last), where \\(\\scriptsize N\\)N is + ranges::distance(first, last). + The function has the effect equivalent to: + + for (; first != last; ++first) + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>(x); + return first; + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first, and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range of elements to initialize + r - the range of the elements to initialize + value - the value to construct the elements with + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + \\(\\scriptsize\\mathcal{O}(N)\\)𝓞(N). + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the ranges::uninitialized_fill, e.g. + by using ranges::fill, if the value type of the output range is TrivialType. + +.SH Possible implementation + + struct uninitialized_fill_fn + { + template S, class T> + requires std::constructible_from, const T&> + I operator()(I first, S last, const T& x) const + { + I rollback{first}; + try + { + for (; !(first == last); ++first) + ranges::construct_at(std::addressof(*first), x); + return first; + } + catch (...) + { + // rollback: destroy constructed elements + for (; rollback != first; ++rollback) + ranges::destroy_at(std::addressof(*rollback)); + throw; + } + } + + template + requires std::constructible_from, const T&> + ranges::borrowed_iterator_t + operator()(R&& r, const T& x) const + { + return (*this)(ranges::begin(r), ranges::end(r), x); + } + }; + + inline constexpr uninitialized_fill_fn uninitialized_fill{}; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr int n{4}; + alignas(alignof(std::string)) char out[n * sizeof(std::string)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last{first + n}; + std::ranges::uninitialized_fill(first, last, "▄▀▄▀▄▀▄▀"); + + int count{1}; + for (auto it{first}; it != last; ++it) + std::cout << count++ << ' ' << *it << '\\n'; + + std::ranges::destroy(first, last); + } + catch(...) + { + std::cout << "Exception!\\n"; + } + } + +.SH Output: + + 1 ▄▀▄▀▄▀▄▀ + 2 ▄▀▄▀▄▀▄▀ + 3 ▄▀▄▀▄▀▄▀ + 4 ▄▀▄▀▄▀▄▀ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + ranges::uninitialized_fill_n copies an object to an uninitialized area of memory, + (C++20) defined by a start and a count + (niebloid) + copies an object to an uninitialized area of memory, + uninitialized_fill defined by a range + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_fill_n.3 b/man/std::ranges::uninitialized_fill_n.3 new file mode 100644 index 000000000..0bef80019 --- /dev/null +++ b/man/std::ranges::uninitialized_fill_n.3 @@ -0,0 +1,138 @@ +.TH std::ranges::uninitialized_fill_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_fill_n \- std::ranges::uninitialized_fill_n + +.SH Synopsis + Defined in header + Call signature + template< no-throw-forward-range I, class T > + + requires std::constructible_from, const T&> \fI(since C++20)\fP + + I uninitialized_fill_n( I first, std::iter_difference_t n, const + T& x ); + + Constructs n copies of the given value x in an uninitialized memory area, designated + by the range [first, first + n), as if by + + for (; n--; ++first) { + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>(x); + } + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of the elements to initialize + n - number of elements to construct + x - the value to construct the elements with + +.SH Return value + + An iterator equal to first + n. + +.SH Complexity + + Linear in n. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the ranges::uninitialized_fill_n, + e.g. by using ranges::fill_n, if the value type of the output range is TrivialType. + +.SH Possible implementation + + struct uninitialized_fill_n_fn + { + template + requires std::constructible_from, const T&> + I operator()(I first, std::iter_difference_t n, const T& x) const + { + I rollback{first}; + try + { + for (; n-- > 0; ++first) + ranges::construct_at(std::addressof(*first), x); + return first; + } + catch (...) // rollback: destroy constructed elements + { + for (; rollback != first; ++rollback) + ranges::destroy_at(std::addressof(*rollback)); + throw; + } + } + }; + + inline constexpr uninitialized_fill_n_fn uninitialized_fill_n{}; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr int n{3}; + alignas(alignof(std::string)) char out[n * sizeof(std::string)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last = std::ranges::uninitialized_fill_n(first, n, "cppreference"); + + for (auto it{first}; it != last; ++it) + std::cout << *it << '\\n'; + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + } + +.SH Output: + + cppreference + cppreference + cppreference + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + ranges::uninitialized_fill copies an object to an uninitialized area of memory, + (C++20) defined by a range + (niebloid) + copies an object to an uninitialized area of memory, + uninitialized_fill_n defined by a start and a count + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_move,std::ranges::uninitialized_move_result.3 b/man/std::ranges::uninitialized_move,std::ranges::uninitialized_move_result.3 new file mode 100644 index 000000000..b586c8734 --- /dev/null +++ b/man/std::ranges::uninitialized_move,std::ranges::uninitialized_move_result.3 @@ -0,0 +1,190 @@ +.TH std::ranges::uninitialized_move,std::ranges::uninitialized_move_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_move,std::ranges::uninitialized_move_result \- std::ranges::uninitialized_move,std::ranges::uninitialized_move_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S1, + + no-throw-forward-iterator O, no-throw-sentinel-for S2 > + requires std::constructible_from, \fB(1)\fP (since + std::iter_rvalue_reference_t> C++20) + uninitialized_move_result + + uninitialized_move( I ifirst, S1 ilast, O ofirst, S2 olast ); + template< ranges::input_range IR, no-throw-forward-range OR > + + requires std::constructible_from, + ranges::range_rvalue_reference_t> \fB(2)\fP (since + uninitialized_move_result, C++20) + ranges::borrowed_iterator_t> + + uninitialized_move( IR&& in_range, OR&& out_range ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using uninitialized_move_result = ranges::in_out_result; C++20) + + 1) Moves N elements from the input range [ifirst, ilast) to the output range + [ofirst, olast) (that is an uninitialized memory area), where N is + min(ranges::distance(ifirst, ilast), ranges::distance(ofirst, olast)). + The effect is equivalent to: + + for (; ifirst != ilast && ofirst != olast; ++ofirst, ++ifirst) + ::new (static_cast(std::addressof(*ofirst))) + std::remove_reference_t>(ranges::iter_move(ifirst)); + + If an exception is thrown during the initialization then the objects that already + constructed in [ofirst, olast) are destroyed in an unspecified order. Also, the + objects in [ifirst, ilast) that were already moved, are left in a valid but + unspecified state. + 2) Same as \fB(1)\fP, but uses in_range as the first range and out_range as the second + range, as if using ranges::begin(in_range) as ifirst, ranges::end(in_range) as + ilast, ranges::begin(out_range) as ofirst, and ranges::end(out_range) as olast. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + ifirst, ilast - iterator-sentinel pair denoting the input range of elements to move + from + in_range - the input range of elements to move from + ofirst, olast - iterator-sentinel pair denoting the output range to initialize + out_range - the output range to initialize + +.SH Return value + + {ifirst + N, ofirst + N} + +.SH Complexity + + Linear in N. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the ranges::uninitialized_move, e.g. + by using ranges::copy_n, if the value type of the output range is TrivialType. + +.SH Possible implementation + + struct uninitialized_move_fn + { + template S1, + no-throw-forward-iterator O, no-throw-sentinel-for S2> + requires std::constructible_from, + std::iter_rvalue_reference_t> + ranges::uninitialized_move_result + operator()(I ifirst, S1 ilast, O ofirst, S2 olast) const + { + O current{ofirst}; + try + { + for (; !(ifirst == ilast or current == olast); ++ifirst, ++current) + ::new (const_cast(static_cast + (std::addressof(*current)))) std::remove_reference_t< + std::iter_reference_t>(ranges::iter_move(ifirst)); + return {std::move(ifirst), std::move(current)}; + } + catch (...) // rollback: destroy constructed elements + { + for (; ofirst != current; ++ofirst) + ranges::destroy_at(std::addressof(*ofirst)); + throw; + } + } + + template + requires std::constructible_from, + ranges::range_rvalue_reference_t> + ranges::uninitialized_move_result, + ranges::borrowed_iterator_t> + operator()(IR&& in_range, OR&& out_range) const + { + return (*this)(ranges::begin(in_range), ranges::end(in_range), + ranges::begin(out_range), ranges::end(out_range)); + } + }; + + inline constexpr uninitialized_move_fn uninitialized_move{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto rem, auto first, auto last) + { + for (std::cout << rem; first != last; ++first) + std::cout << std::quoted(*first) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::string in[]{"Home", "World"}; + print("initially, in: ", std::begin(in), std::end(in)); + + if (constexpr auto sz = std::size(in); + void* out = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz)) + { + try + { + auto first{static_cast(out)}; + auto last{first + sz}; + std::ranges::uninitialized_move(std::begin(in), std::end(in), first, last); + + print("after move, in: ", std::begin(in), std::end(in)); + print("after move, out: ", first, last); + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + std::free(out); + } + } + +.SH Possible output: + + initially, in: "Home" "World" + after move, in: "" "" + after move, out: "Home" "World" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + ranges::uninitialized_move_n moves a number of objects to an uninitialized area of + (C++20) memory + (niebloid) + uninitialized_move moves a range of objects to an uninitialized area of + \fI(C++17)\fP memory + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_move_n,std::ranges::uninitialized_move_n_result.3 b/man/std::ranges::uninitialized_move_n,std::ranges::uninitialized_move_n_result.3 new file mode 100644 index 000000000..50453622d --- /dev/null +++ b/man/std::ranges::uninitialized_move_n,std::ranges::uninitialized_move_n_result.3 @@ -0,0 +1,171 @@ +.TH std::ranges::uninitialized_move_n,std::ranges::uninitialized_move_n_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_move_n,std::ranges::uninitialized_move_n_result \- std::ranges::uninitialized_move_n,std::ranges::uninitialized_move_n_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, no-throw-forward-iterator O, + + no-throw-sentinel-for S > + requires std::constructible_from, + std::iter_rvalue_reference_t> \fB(1)\fP \fI(since C++20)\fP + uninitialized_move_n_result + + uninitialized_move_n( I ifirst, std::iter_difference_t n, O + ofirst, S olast ); +.SH Helper types + template< class I, class O > \fB(2)\fP \fI(since C++20)\fP + using uninitialized_move_n_result = ranges::in_out_result; + + Moves N elements from the input range beginning at ifirst to the uninitialized + storage designated by the range [ofirst, olast), where N is min(n, + ranges::distance(ofirst, olast)). + + The effect is equivalent to: + + for (; n-- > 0 && ofirst != olast; ++ifirst, ++ofirst) + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>(ranges::iter_move(ifirst)); + + If an exception is thrown during the initialization then the objects that already + constructed in [ofirst, olast) are destroyed in an unspecified order. Also, the + objects in the input range beginning at ifirst, that were already moved, are left in + a valid but unspecified state. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + ifirst - the beginning of the input range of elements to move from + ofirst, olast - iterator-sentinel pair denoting the output range of elements to + initialize + n - the number of elements to move + +.SH Return value + + {ifirst + N, ofirst + N}. + +.SH Complexity + + Linear in N. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the ranges::uninitialized_move_n, + e.g. by using ranges::copy_n, if the value type of the output range is TrivialType. + +.SH Possible implementation + + struct uninitialized_move_n_fn + { + template S> + requires std::constructible_from, + std::iter_rvalue_reference_t> + ranges::uninitialized_move_n_result + operator()(I ifirst, std::iter_difference_t n, O ofirst, S olast) const + { + O current{ofirst}; + try + { + for (; n-- > 0 && current != olast; ++ifirst, ++current) + ::new (const_cast(static_cast + (std::addressof(*current)))) std::remove_reference_t< + std::iter_reference_t>(ranges::iter_move(ifirst)); + return {std::move(ifirst), std::move(current)}; + } + catch (...) // rollback: destroy constructed elements + { + for (; ofirst != current; ++ofirst) + ranges::destroy_at(std::addressof(*ofirst)); + throw; + } + } + }; + + inline constexpr uninitialized_move_n_fn uninitialized_move_n{}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto rem, auto first, auto last) + { + for (std::cout << rem; first != last; ++first) + std::cout << std::quoted(*first) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::string in[]{ "No", "Diagnostic", "Required", }; + print("initially, in: ", std::begin(in), std::end(in)); + + if ( + constexpr auto sz = std::size(in); + void* out = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz) + ) + { + try + { + auto first{static_cast(out)}; + auto last{first + sz}; + std::ranges::uninitialized_move_n(std::begin(in), sz, first, last); + + print("after move, in: ", std::begin(in), std::end(in)); + print("after move, out: ", first, last); + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + std::free(out); + } + } + +.SH Possible output: + + initially, in: "No" "Diagnostic" "Required" + after move, in: "" "" "" + after move, out: "No" "Diagnostic" "Required" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + ranges::uninitialized_move moves a range of objects to an uninitialized area of + (C++20) memory + (niebloid) + uninitialized_move_n moves a number of objects to an uninitialized area of + \fI(C++17)\fP memory + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_value_construct.3 b/man/std::ranges::uninitialized_value_construct.3 new file mode 100644 index 000000000..cbbfc8de1 --- /dev/null +++ b/man/std::ranges::uninitialized_value_construct.3 @@ -0,0 +1,188 @@ +.TH std::ranges::uninitialized_value_construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_value_construct \- std::ranges::uninitialized_value_construct + +.SH Synopsis + Defined in header + Call signature + template< no-throw-forward-iterator I, no-throw-sentinel-for S > + (since + requires std::default_initializable> \fB(1)\fP C++20) + + I uninitialized_value_construct( I first, S last ); + template< no-throw-forward-range R > + + requires std::default_initializable> \fB(2)\fP (since + ranges::borrowed_iterator_t C++20) + + uninitialized_value_construct( R&& r ); + + 1) Constructs objects of type std::iter_value_t in the uninitialized storage + designated by the range [first, last) by value-initialization, as if by + + for (; first != last; ++first) + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>(); + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first, and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel pair denoting the range of elements to + value-initialize + r - the range of the elements to value-initialize + +.SH Return value + + An iterator equal to last. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the + ranges::uninitialized_value_construct, e.g. by using ranges::fill, if the value type + of the range is TrivialType and CopyAssignable. + +.SH Possible implementation + + struct uninitialized_value_construct_fn + { + template S> + requires std::default_initializable> + I operator()(I first, S last) const + { + using T = std::remove_reference_t>; + if constexpr (std::is_trivial_v && std::is_copy_assignable_v) + return ranges::fill(first, last, T()); + I rollback{first}; + try + { + for (; !(first == last); ++first) + ::new (const_cast(static_cast + (std::addressof(*first)))) T(); + return first; + } + catch (...) // rollback: destroy constructed elements + { + for (; rollback != first; ++rollback) + ranges::destroy_at(std::addressof(*rollback)); + throw; + } + } + + template + requires std::default_initializable> + ranges::borrowed_iterator_t + operator()(R&& r) const + { + return (*this)(ranges::begin(r), ranges::end(r)); + } + }; + + inline constexpr uninitialized_value_construct_fn uninitialized_value_construct{}; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + struct S { std::string m{"▄▀▄▀▄▀▄▀"}; }; + + constexpr int n{4}; + alignas(alignof(S)) char out[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last{first + n}; + + std::ranges::uninitialized_value_construct(first, last); + + auto count{1}; + for (auto it{first}; it != last; ++it) + std::cout << count++ << ' ' << it->m << '\\n'; + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_value_construct + // zero-fills the given uninitialized memory area. + int v[]{0, 1, 2, 3}; + std::cout << ' '; + for (const int i : v) + std::cout << ' ' << static_cast(i + 'A'); + std::cout << "\\n "; + std::ranges::uninitialized_value_construct(std::begin(v), std::end(v)); + for (const int i : v) + std::cout << ' ' << static_cast(i + 'A'); + std::cout << '\\n'; + } + +.SH Output: + + 1 ▄▀▄▀▄▀▄▀ + 2 ▄▀▄▀▄▀▄▀ + 3 ▄▀▄▀▄▀▄▀ + 4 ▄▀▄▀▄▀▄▀ + A B C D + A A A A + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by value-initialization + ranges::uninitialized_value_construct_n in an uninitialized area of memory, + (C++20) defined by a start and a count + (niebloid) + constructs objects by + ranges::uninitialized_default_construct default-initialization in an uninitialized + (C++20) area of memory, defined by a range + (niebloid) + constructs objects by + ranges::uninitialized_default_construct_n default-initialization in an uninitialized + (C++20) area of memory, defined by a start and + count + (niebloid) + constructs objects by value-initialization + uninitialized_value_construct in an uninitialized area of memory, + \fI(C++17)\fP defined by a range + \fI(function template)\fP diff --git a/man/std::ranges::uninitialized_value_construct_n.3 b/man/std::ranges::uninitialized_value_construct_n.3 new file mode 100644 index 000000000..8724fea19 --- /dev/null +++ b/man/std::ranges::uninitialized_value_construct_n.3 @@ -0,0 +1,169 @@ +.TH std::ranges::uninitialized_value_construct_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::uninitialized_value_construct_n \- std::ranges::uninitialized_value_construct_n + +.SH Synopsis + Defined in header + Call signature + template< no-throw-forward-iterator I > + + requires std::default_initializable> \fI(since C++20)\fP + + I uninitialized_value_construct_n( I first, std::iter_difference_t + n ); + + Constructs n objects of type std::iter_value_t in the uninitialized memory area + starting at first by value-initialization, as if by + for (; n-- > 0; ++first) + ::new (static_cast(std::addressof(*first))) + std::remove_reference_t>(); + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first - the beginning of the range of elements to initialize + n - the number of elements to construct + +.SH Return value + + The end of the range of objects (i.e., ranges::next(first, n)). + +.SH Complexity + + Linear in n. + +.SH Exceptions + + The exception thrown on construction of the elements in the destination range, if + any. + +.SH Notes + + An implementation may improve the efficiency of the + ranges::uninitialized_value_construct_n, e.g. by using ranges::fill_n, if the value + type of the range is TrivialType and CopyAssignable. + +.SH Possible implementation + + struct uninitialized_value_construct_n_fn + { + template + requires std::default_initializable> + I operator()(I first, std::iter_difference_t n) const + { + using T = std::remove_reference_t>; + if constexpr (std::is_trivial_v && std::is_copy_assignable_v) + return ranges::fill_n(first, n, T()); + I rollback{first}; + try + { + for (; n-- > 0; ++first) + ::new (const_cast(static_cast + (std::addressof(*first)))) T(); + return first; + } + catch (...) // rollback: destroy constructed elements + { + for (; rollback != first; ++rollback) + ranges::destroy_at(std::addressof(*rollback)); + throw; + } + } + }; + + inline constexpr uninitialized_value_construct_n_fn uninitialized_value_construct_n{}; + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + struct S { std::string m{"█▓▒░ █▓▒░ █▓▒░ "}; }; + + constexpr int n{4}; + alignas(alignof(S)) char out[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(out)}; + auto last = std::ranges::uninitialized_value_construct_n(first, n); + + auto count{1}; + for (auto it{first}; it != last; ++it) + std::cout << count++ << ' ' << it->m << '\\n'; + + std::ranges::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_value_construct_n + // zero-initializes the given uninitialized memory area. + int v[]{1, 2, 3, 4, 5, 6, 7, 8}; + std::cout << ' '; + for (const int i : v) + std::cout << i << ' '; + std::cout << "\\n "; + std::ranges::uninitialized_value_construct_n(std::begin(v), std::size(v)); + for (const int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 █▓▒░ █▓▒░ █▓▒░ + 2 █▓▒░ █▓▒░ █▓▒░ + 3 █▓▒░ █▓▒░ █▓▒░ + 4 █▓▒░ █▓▒░ █▓▒░ + 1 2 3 4 5 6 7 8 + 0 0 0 0 0 0 0 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by value-initialization + ranges::uninitialized_value_construct in an uninitialized area of memory, + (C++20) defined by a range + (niebloid) + constructs objects by + ranges::uninitialized_default_construct default-initialization in an uninitialized + (C++20) area of memory, defined by a range + (niebloid) + constructs objects by + ranges::uninitialized_default_construct_n default-initialization in an uninitialized + (C++20) area of memory, defined by a start and + count + (niebloid) + constructs objects by value-initialization + uninitialized_value_construct_n in an uninitialized area of memory, + \fI(C++17)\fP defined by a start and a count + \fI(function template)\fP diff --git a/man/std::ranges::unique.3 b/man/std::ranges::unique.3 new file mode 100644 index 000000000..9136b2706 --- /dev/null +++ b/man/std::ranges::unique.3 @@ -0,0 +1,198 @@ +.TH std::ranges::unique 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::unique \- std::ranges::unique + +.SH Synopsis + Defined in header + Call signature + template< std::permutable I, std::sentinel_for S, class Proj = + std::identity, + + std::indirect_equivalence_relation> \fB(1)\fP (since + C = ranges::equal_to > C++20) + constexpr ranges::subrange + + unique( I first, S last, C comp = {}, Proj proj = {} ); + template< ranges::forward_range R, class Proj = std::identity, + + + std::indirect_equivalence_relation, + Proj>> \fB(2)\fP (since + C = ranges::equal_to > C++20) + requires std::permutable> + constexpr ranges::borrowed_subrange_t + + unique( R&& r, C comp = {}, Proj proj = {} ); + + 1) Eliminates all except the first element from every consecutive group of + equivalent elements from the range [first, last) and returns a subrange [ret, last), + where ret is a past-the-end iterator for the new end of the range. + Two consecutive elements *(i - 1) and *i are considered equivalent if + std::invoke(comp, std::invoke(proj, *(i - 1)), std::invoke(proj, *i)) == true, where + i is an iterator in the range [first + 1, last). + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first, and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the range of elements to process + r - the range of elements to process + comp - the binary predicate to compare the projected elements + proj - the projection to apply to the elements + +.SH Return value + + Returns {ret, last}, where ret is a past-the-end iterator for the new end of the + range. + +.SH Complexity + + For nonempty ranges, exactly ranges::distance(first, last) - 1 applications of the + corresponding predicate comp and no more that twice as many applications of any + projection proj. + +.SH Notes + + Removing is done by shifting (by means of move assignment) the elements in the range + in such a way that the elements that are not to be removed appear in the beginning + of the range. Relative order of the elements that remain is preserved and the + physical size of the container is unchanged. Iterators in [ret, last) (if any) are + still dereferenceable, but the elements themselves have unspecified values (as per + MoveAssignable post-condition). + + A call to ranges::unique is sometimes followed by a call to a container’s erase + member function, which erases the unspecified values and reduces the physical size + of the container to match its new logical size. These two invocations together model + the Erase–remove idiom. + +.SH Possible implementation + +struct unique_fn +{ + template S, class Proj = std::identity, + std::indirect_equivalence_relation> + C = ranges::equal_to> + constexpr ranges::subrange + operator()(I first, S last, C comp = {}, Proj proj = {}) const + { + first = ranges::adjacent_find(first, last, comp, proj); + if (first == last) + return {first, first}; + auto i {first}; + ++first; + while (++first != last) + if (!std::invoke(comp, std::invoke(proj, *i), std::invoke(proj, *first))) + *++i = ranges::iter_move(first); + return {++i, first}; + } + + template, Proj>> + C = ranges::equal_to> + requires std::permutable> + constexpr ranges::borrowed_subrange_t + operator()(R&& r, C comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), + std::move(comp), std::move(proj)); + } +}; + +inline constexpr unique_fn unique {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct id { + int i; + explicit id(int i) : i {i} {} + }; + + void print(id i, const auto& v) + { + std::cout << i.i << ") "; + std::ranges::for_each(v, [](auto const& e) { std::cout << e << ' '; }); + std::cout << '\\n'; + } + + int main() + { + // a vector containing several duplicated elements + std::vector v {1, 2, 1, 1, 3, 3, 3, 4, 5, 4}; + + print(id {1}, v); + + // remove consecutive (adjacent) duplicates + const auto ret = std::ranges::unique(v); + // v now holds {1 2 1 3 4 5 4 x x x}, where 'x' is indeterminate + v.erase(ret.begin(), ret.end()); + print(id {2}, v); + + // sort followed by unique, to remove all duplicates + std::ranges::sort(v); // {1 1 2 3 4 4 5} + print(id {3}, v); + + const auto [first, last] = std::ranges::unique(v.begin(), v.end()); + // v now holds {1 2 3 4 5 x x}, where 'x' is indeterminate + v.erase(first, last); + print(id {4}, v); + + // unique with custom comparison and projection + std::vector> vc { {1, 1}, {-1, 2}, {-2, 3}, {2, 4}, {-3, 5} }; + print(id {5}, vc); + + const auto ret2 = std::ranges::unique(vc, + // consider two complex nums equal if their real parts are equal by module: + [](int x, int y) { return std::abs(x) == std::abs(y); }, // comp + [](std::complex z) { return z.real(); } // proj + ); + vc.erase(ret2.begin(), ret2.end()); + print(id {6}, vc); + } + +.SH Output: + + 1) 1 2 1 1 3 3 3 4 5 4 + 2) 1 2 1 3 4 5 4 + 3) 1 1 2 3 4 4 5 + 4) 1 2 3 4 5 + 5) (1,1) (-1,2) (-2,3) (2,4) (-3,5) + 6) (1,1) (-2,3) (-3,5) + +.SH See also + + ranges::unique_copy creates a copy of some range of elements that contains no + (C++20) consecutive duplicates + (niebloid) + ranges::adjacent_find finds the first two adjacent items that are equal (or satisfy + (C++20) a given predicate) + (niebloid) + ranges::remove + ranges::remove_if removes elements satisfying specific criteria + (C++20) (niebloid) + (C++20) + unique removes consecutive duplicate elements in a range + \fI(function template)\fP + unique removes consecutive duplicate elements + \fI(public member function of std::list)\fP + removes consecutive duplicate elements + unique \fI(public member function of std::forward_list)\fP + diff --git a/man/std::ranges::unique_copy,std::ranges::unique_copy_result.3 b/man/std::ranges::unique_copy,std::ranges::unique_copy_result.3 new file mode 100644 index 000000000..577dbd740 --- /dev/null +++ b/man/std::ranges::unique_copy,std::ranges::unique_copy_result.3 @@ -0,0 +1,202 @@ +.TH std::ranges::unique_copy,std::ranges::unique_copy_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::unique_copy,std::ranges::unique_copy_result \- std::ranges::unique_copy,std::ranges::unique_copy_result + +.SH Synopsis + Defined in header + Call signature + template< std::input_iterator I, std::sentinel_for S, + std::weakly_incrementable O, + + class Proj = std::identity, + std::indirect_equivalence_relation> C = + ranges::equal_to > + requires std::indirectly_copyable && (std::forward_iterator || (since + (std::input_iterator && \fB(1)\fP C++20) + std::same_as, + std::iter_value_t>) || + std::indirectly_copyable_storable) + constexpr unique_copy_result + + unique_copy( I first, S last, O result, C comp = {}, Proj proj = {} + ); + template< ranges::input_range R, std::weakly_incrementable O, class Proj + = std::identity, + + + std::indirect_equivalence_relation, + Proj>> C = ranges::equal_to > + requires std::indirectly_copyable, O> && (since + (std::forward_iterator> || \fB(2)\fP C++20) + (std::input_iterator && + std::same_as, + std::iter_value_t>) || + std::indirectly_copyable_storable, O>) + constexpr unique_copy_result, O> + + unique_copy( R&& r, O result, C comp = {}, Proj proj = {} ); +.SH Helper types + template< class I, class O > \fB(3)\fP (since + using unique_copy_result = ranges::in_out_result; C++20) + + 1) Copies the elements from the source range [first, last), to the destination range + beginning at result in such a way that there are no consecutive equal elements. Only + the first element of each group of equal elements is copied. + The ranges [first, last) and [result, result + N) must not overlap. N = + ranges::distance(first, last). + Two consecutive elements *(i - 1) and *i are considered equivalent if + std::invoke(comp, std::invoke(proj, *(i - 1)), std::invoke(proj, *i)) == true, where + i is an iterator in the range [first + 1, last). + 2) Same as \fB(1)\fP, but uses r as the range, as if using ranges::begin(r) as first, and + ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - the source range of elements + r - the source range of elements + result - the destination range of elements + comp - the binary predicate to compare the projected elements + proj - the projection to apply to the elements + +.SH Return value + + {last, result + N} + +.SH Complexity + + Exactly N - 1 applications of the corresponding predicate comp and no more than + twice as many applications of any projection proj. + +.SH Possible implementation + + See also the implementations in libstdc++ and MSVC STL (and third-party libraries: + cmcstl2, NanoRange, and range-v3). + +struct unique_copy_fn +{ + template S, std::weakly_incrementable O, + class Proj = std::identity, + std::indirect_equivalence_relation> C = ranges::equal_to> + requires std::indirectly_copyable && (std::forward_iterator || + (std::input_iterator && std::same_as, + std::iter_value_t>) || std::indirectly_copyable_storable) + constexpr ranges::unique_copy_result + operator()(I first, S last, O result, C comp = {}, Proj proj = {}) const + { + if (!(first == last)) + { + std::iter_value_t value = *first; + *result = value; + ++result; + while (!(++first == last)) + { + auto&& value2 = *first; + if (!std::invoke(comp, std::invoke(proj, value2), + std::invoke(proj, value))) + { + value = std::forward(value2); + *result = value; + ++result; + } + } + } + + return {std::move(first), std::move(result)}; + } + + template, + Proj>> C = ranges::equal_to> + requires std::indirectly_copyable, O> && + (std::forward_iterator> || + (std::input_iterator && std::same_as, + std::iter_value_t>) || + std::indirectly_copyable_storable, O>) + constexpr ranges::unique_copy_result, O> + operator()(R&& r, O result, C comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), std::move(result), + std::move(comp), std::move(proj)); + } +}; + +inline constexpr unique_copy_fn unique_copy {}; + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(const auto& rem, const auto& v) + { + using V = std::remove_cvref_t; + constexpr bool sep{std::is_same_v}; + std::cout << rem << std::showpos; + for (const auto& e : v) + std::cout << e << (sep ? " " : ""); + std::cout << '\\n'; + } + + int main() + { + std::string s1{"The string with many spaces!"}; + print("s1: ", s1); + + std::string s2; + std::ranges::unique_copy( + s1.begin(), s1.end(), std::back_inserter(s2), + [](char c1, char c2) { return c1 == ' ' && c2 == ' '; } + ); + print("s2: ", s2); + + const auto v1 = {-1, +1, +2, -2, -3, +3, -3}; + print("v1: ", v1); + std::list v2; + std::ranges::unique_copy( + v1, std::back_inserter(v2), + {}, // default comparator std::ranges::equal_to + [](int x) { return std::abs(x); } // projection + ); + print("v2: ", v2); + } + +.SH Output: + + s1: The string with many spaces! + s2: The string with many spaces! + v1: -1 +1 +2 -2 -3 +3 -3 + v2: -1 +2 -3 + +.SH See also + + ranges::unique removes consecutive duplicate elements in a range + (C++20) (niebloid) + ranges::copy + ranges::copy_if copies a range of elements to a new location + (C++20) (niebloid) + (C++20) + ranges::adjacent_find finds the first two adjacent items that are equal (or satisfy + (C++20) a given predicate) + (niebloid) + creates a copy of some range of elements that contains no + unique_copy consecutive duplicates + \fI(function template)\fP diff --git a/man/std::ranges::upper_bound.3 b/man/std::ranges::upper_bound.3 new file mode 100644 index 000000000..12fdd8642 --- /dev/null +++ b/man/std::ranges::upper_bound.3 @@ -0,0 +1,205 @@ +.TH std::ranges::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::upper_bound \- std::ranges::upper_bound + +.SH Synopsis + Defined in header + Call signature + template< std::forward_iterator I, std::sentinel_for S, + + class T, class Proj = std::identity, (since + std::indirect_strict_weak_order C++20) + > Comp = (until + ranges::less > C++26) + constexpr I upper_bound( I first, S last, const T& value, + + Comp comp = {}, Proj proj = {} ); + template< std::forward_iterator I, std::sentinel_for S, + + class Proj = std::identity, + class T = std::projected_value_t, + std::indirect_strict_weak_order (since + > Comp = C++26) + ranges::less > + constexpr I upper_bound( I first, S last, const T& value, + + Comp comp = {}, Proj proj = {} ); + template< ranges::forward_range R, + + class T, class Proj = std::identity, + std::indirect_strict_weak_order \fB(1)\fP + , C++20) + Proj>> Comp = (until + ranges::less > C++26) + constexpr ranges::borrowed_iterator_t + + upper_bound( R&& r, const T& value, Comp comp = {}, Proj + proj = {} ); + template< ranges::forward_range R, \fB(2)\fP + + class Proj = std::identity, + class T = + std::projected_value_t, Proj>, + std::indirect_strict_weak_order + , C++26) + Proj>> Comp = + ranges::less > + constexpr ranges::borrowed_iterator_t + + upper_bound( R&& r, const T& value, Comp comp = {}, Proj + proj = {} ); + + 1) Returns an iterator pointing to the first element in the range [first, last) that + is greater than value, or last if no such element is found. The range [first, last) + must be partitioned with respect to the expression or !comp(value, element), i.e., + all elements for which the expression is true must precede all elements for which + the expression is false. A fully-sorted range meets this criterion. + 2) Same as \fB(1)\fP, but uses r as the source range, as if using ranges::begin(r) as + first and ranges::end(r) as last. + + The function-like entities described on this page are niebloids, that is: + + * Explicit template argument lists cannot be specified when calling any of them. + * None of them are visible to argument-dependent lookup. + * When any of them are found by normal unqualified lookup as the name to the left + of the function-call operator, argument-dependent lookup is inhibited. + + In practice, they may be implemented as function objects, or with special compiler + extensions. + +.SH Parameters + + first, last - iterator-sentinel defining the partially-ordered range to examine + r - the partially-ordered range to examine + value - value to compare the elements to + pred - predicate to apply to the projected elements + proj - projection to apply to the elements + +.SH Return value + + Iterator pointing to the first element that is greater than value, or last if no + such element is found. + +.SH Complexity + + The number of comparisons and applications of the projection performed are + logarithmic in the distance between first and last (at most log + 2(last - first) + O(1) comparisons and applications of the projection). However, for + an iterator that does not model random_access_iterator, the number of iterator + increments is linear. + +.SH Possible implementation + + struct upper_bound_fn + { + template S, + class Proj = std::identity, class T = std::projected_value_t, + std::indirect_strict_weak_order + > Comp = ranges::less> + constexpr I operator()(I first, S last, const T& value, + Comp comp = {}, Proj proj = {}) const + { + I it; + std::iter_difference_t count, step; + count = ranges::distance(first, last); + + while (count > 0) + { + it = first; + step = count / 2; + ranges::advance(it, step, last); + if (!comp(value, std::invoke(proj, *it))) + { + first = ++it; + count -= step + 1; + } + else + count = step; + } + return first; + } + + template, Proj>, + std::indirect_strict_weak_order + , + Proj>> Comp = ranges::less> + constexpr ranges::borrowed_iterator_t + operator()(R&& r, const T& value, Comp comp = {}, Proj proj = {}) const + { + return (*this)(ranges::begin(r), ranges::end(r), value, + std::ref(comp), std::ref(proj)); + } + }; + + inline constexpr upper_bound_fn upper_bound; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + namespace ranges = std::ranges; + + std::vector data{1, 1, 2, 3, 3, 3, 3, 4, 4, 4, 5, 5, 6}; + + { + auto lower = ranges::lower_bound(data.begin(), data.end(), 4); + auto upper = ranges::upper_bound(data.begin(), data.end(), 4); + + ranges::copy(lower, upper, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + { + auto lower = ranges::lower_bound(data, 3); + auto upper = ranges::upper_bound(data, 3); + + ranges::copy(lower, upper, std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + + using CD = std::complex; + std::vector nums{{1, 0}, {2, 2}, {2, 1}, {3, 0}, {3, 1}}; + auto cmpz = [](CD x, CD y) { return x.real() < y.real(); }; + #ifdef __cpp_lib_algorithm_default_value_type + auto it = ranges::upper_bound(nums, {2, 0}, cmpz); + #else + auto it = ranges::upper_bound(nums, CD{2, 0}, cmpz); + #endif + assert((*it == CD{3, 0})); + } + +.SH Output: + + 4 4 4 + 3 3 3 3 + +.SH See also + + ranges::equal_range returns range of elements matching a specific key + (C++20) (niebloid) + ranges::lower_bound returns an iterator to the first element not less than the given + (C++20) value + (niebloid) + ranges::partition divides a range of elements into two groups + (C++20) (niebloid) + returns an iterator to the first element greater than a certain + upper_bound value + \fI(function template)\fP diff --git a/man/std::ranges::view,std::ranges::enable_view,std::ranges::view_base.3 b/man/std::ranges::view,std::ranges::enable_view,std::ranges::view_base.3 new file mode 100644 index 000000000..755b99e82 --- /dev/null +++ b/man/std::ranges::view,std::ranges::enable_view,std::ranges::view_base.3 @@ -0,0 +1,76 @@ +.TH std::ranges::view,std::ranges::enable_view,std::ranges::view_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view,std::ranges::enable_view,std::ranges::view_base \- std::ranges::view,std::ranges::enable_view,std::ranges::view_base + +.SH Synopsis + Defined in header + template + concept view = ranges::range && std::movable && \fB(1)\fP \fI(since C++20)\fP + ranges::enable_view; + template + + inline constexpr bool enable_view = \fB(2)\fP \fI(since C++20)\fP + + std::derived_from || + /*is-derived-from-view-interface*/; + struct view_base { }; \fB(3)\fP \fI(since C++20)\fP + + 1) The view concept specifies the requirements of a range type that has suitable + semantic properties for use in constructing range adaptor pipelines. + 2) The enable_view variable template is used to indicate whether a range is a view. + /*is-derived-from-view-interface*/ is true if and only if T has exactly one + public base class ranges::view_interface for some type U, and T has no base + classes of type ranges::view_interface for any other type V. + Users may specialize enable_view to true for cv-unqualified program-defined types + which model view, and false for types which do not. Such specializations must be + usable in constant expressions and have type const bool. + 3) Deriving from view_base enables range types to model view. + +.SH Notes + + Examples of view types are: + + * A range type that wraps a pair of iterators, e.g., std::ranges::subrange. + * A range type that holds its elements by std::shared_ptr and shares ownership + with all its copies. + * A range type that generates its elements on demand, e.g., + std::ranges::iota_view. + + A copyable container such as std::vector generally does not meet the + semantic requirements of view since copying the container copies all of the + elements, which cannot be done in constant time. + + While views were originally described as cheaply copyable and non-owning ranges, a + type is not required to be copyable or non-owning for it to model view. However, it + must still be cheap to copy (if it is copyable), move, assign, and destroy, so that + range adaptors will not have unexpected complexity. + + By default, a type modeling movable and range is considered a view if it is publicly + and unambiguously derived from view_base, or exactly one specialization of + std::ranges::view_interface. + +.SH Example + + A minimum view. + + #include + + struct ArchetypalView : std::ranges::view_interface + { + int* begin(); + int* end(); + }; + + static_assert(std::ranges::view); + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2325R3 C++20 view required default_initializable does not require + LWG 3549 C++20 enable_view did not detect inheritance from detects + view_interface + P2415R2 C++20 the restriction on the time complexity of relaxed + destruction was too strict diff --git a/man/std::ranges::view_interface.3 b/man/std::ranges::view_interface.3 new file mode 100644 index 000000000..7c6979e03 --- /dev/null +++ b/man/std::ranges::view_interface.3 @@ -0,0 +1,123 @@ +.TH std::ranges::view_interface 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface \- std::ranges::view_interface + +.SH Synopsis + Defined in header + template< class D > + + requires std::is_class_v && std::same_as> + + class view_interface; + + std::ranges::view_interface is a helper class template for defining a view + interface. + + view_interface is typically used with CRTP: + + class my_view : public std::ranges::view_interface + { + public: + auto begin() const { /*...*/ } + auto end() const { /*...*/ } + // empty() is provided if begin() returns a forward iterator + // and end() returns a sentinel for it. + }; + +.SH Member functions + + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function)\fP + returns the number of elements in the derived view. Provided if it + size satisfies forward_range and its sentinel and iterator type satisfy + (C++20) sized_sentinel_for. + \fI(public member function)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + template + class VectorView : public std::ranges::view_interface> + { + public: + VectorView() = default; + + VectorView(const std::vector& vec) : + m_begin(vec.cbegin()), m_end(vec.cend()) + {} + + auto begin() const { return m_begin; } + + auto end() const { return m_end; } + + private: + typename std::vector::const_iterator m_begin{}, m_end{}; + }; + + int main() + { + std::vector v = {1, 4, 9, 16}; + + VectorView view_over_v{v}; + + // We can iterate with begin() and end(). + for (int n : view_over_v) + std::cout << n << ' '; + std::cout << '\\n'; + + // We get operator[] for free when inheriting from view_interface + // since we satisfy the random_access_range concept. + for (std::ptrdiff_t i = 0; i != view_over_v.size(); ++i) + std::cout << "v[" << i << "] = " << view_over_v[i] << '\\n'; + } + +.SH Output: + + 1 4 9 16 + v[0] = 1 + v[1] = 4 + v[2] = 9 + v[3] = 16 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + view_interface was required to be derived + LWG 3549 C++20 from view_base, inheritance removed + which sometimes required multiple view_base + subobjects in a view + +.SH See also + + ranges::subrange combines an iterator-sentinel pair into a view + (C++20) \fI(class template)\fP diff --git a/man/std::ranges::view_interface::back.3 b/man/std::ranges::view_interface::back.3 new file mode 100644 index 000000000..3f4696bb8 --- /dev/null +++ b/man/std::ranges::view_interface::back.3 @@ -0,0 +1,63 @@ +.TH std::ranges::view_interface::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::back \- std::ranges::view_interface::back + +.SH Synopsis + constexpr decltype(auto) back() + requires ranges::bidirectional_range && \fB(1)\fP \fI(since C++20)\fP + ranges::common_range; + constexpr decltype(auto) back() const + requires ranges::bidirectional_range && \fB(2)\fP \fI(since C++20)\fP + ranges::common_range; + + The default implementation of back() member function returns the last element in the + view of the derived type. Whether the element is returned by value or by reference + depends on the operator* of the iterator type. + + 1) Let derived be static_cast(*this). Equivalent to return + *ranges::prev(ranges::end(derived));. The behavior is undefined if empty() is true + (i.e. the beginning iterator compares equal to the sentinel), even if the iterator + obtained in the same way is dereferenceable. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The last element in the view. + +.SH Notes + + In C++20, no type derived from std::ranges::view_interface in the standard library + provides their own back() member function. + + However, following derived types cannot use the default implementations, as they + never satisfy neither bidirectional_range nor common_range: + + * std::ranges::basic_istream_view + * std::ranges::lazy_split_view + * std::ranges::split_view + * std::ranges::take_while_view + + The inherited back() member function is available for std::ranges::empty_view, but a + call to it always results in undefined behavior. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP + ranges::rbegin returns a reverse iterator to a range + (C++20) (customization point object) + ranges::crbegin returns a reverse iterator to a read-only range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::view_interface::cbegin.3 b/man/std::ranges::view_interface::cbegin.3 new file mode 100644 index 000000000..548231442 --- /dev/null +++ b/man/std::ranges::view_interface::cbegin.3 @@ -0,0 +1,46 @@ +.TH std::ranges::view_interface::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::cbegin \- std::ranges::view_interface::cbegin + +.SH Synopsis + constexpr auto cbegin(); \fB(1)\fP (since C++23) + constexpr auto cbegin() const requires ranges::range; \fB(2)\fP (since C++23) + + The default implementation of cbegin() member function returns a constant beginning + iterator of the range. + + range-begin-end.svg + + 1) Let derived be a reference bound to static_cast(*this). + Equivalent to return ranges::cbegin(derived);. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A constant beginning iterator of the range. + +.SH Notes + + All range adaptors and range factories in the standard library and + std::ranges::subrange use the default implementation of cbegin. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::cbegin returns an iterator to the beginning of a read-only range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::view_interface::cend.3 b/man/std::ranges::view_interface::cend.3 new file mode 100644 index 000000000..c64631e16 --- /dev/null +++ b/man/std::ranges::view_interface::cend.3 @@ -0,0 +1,46 @@ +.TH std::ranges::view_interface::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::cend \- std::ranges::view_interface::cend + +.SH Synopsis + constexpr auto cend(); \fB(1)\fP (since C++23) + constexpr auto cend() const requires ranges::range; \fB(2)\fP (since C++23) + + The default implementation of cend() member function returns the sentinel for the + constant iterator of the range. + + range-begin-end.svg + + 1) Let derived be a reference bound to static_cast(*this). Equivalent to return + ranges::cend(derived);. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The sentinel for the constant iterator of the range. + +.SH Notes + + All range adaptors and range factories in the standard library and + std::ranges::subrange use the default implementation of cend. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::cend returns a sentinel indicating the end of a read-only range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::view_interface::data.3 b/man/std::ranges::view_interface::data.3 new file mode 100644 index 000000000..6d2e4b6f5 --- /dev/null +++ b/man/std::ranges::view_interface::data.3 @@ -0,0 +1,88 @@ +.TH std::ranges::view_interface::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::data \- std::ranges::view_interface::data + +.SH Synopsis + constexpr auto data() \fB(1)\fP \fI(since C++20)\fP + requires std::contiguous_iterator>; + constexpr auto data() const + + requires ranges::range && \fB(2)\fP \fI(since C++20)\fP + + std::contiguous_iterator>; + + The default implementation of data() member function obtains the address denoted by + the beginning iterator via std::to_address, which is also the lowest address of the + contiguous storage (implied by contiguous_iterator) referenced by the view of the + derived type when the view is not empty. + + 1) Let derived be static_cast(*this). Equivalent to return + std::to_address(ranges::begin(derived));. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The address denoted by the beginning iterator. + +.SH Notes + + Following derived types may use the default implementation of data(): + + * std::ranges::common_view + * std::ranges::drop_view + * std::ranges::drop_while_view + * std::ranges::ref_view + * std::ranges::subrange + * std::ranges::take_view + * std::ranges::take_while_view + + Following types are derived from std::ranges::view_interface and do not declare + their own data() member function, but they cannot use the default implementation, + because their iterator types never satisfy contiguous_iterator: + + * std::ranges::basic_istream_view + * std::ranges::elements_view + * std::ranges::filter_view + * std::ranges::iota_view + * std::ranges::join_view + * std::ranges::lazy_split_view + * std::ranges::reverse_view + * std::ranges::split_view + * std::ranges::transform_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() { + constexpr std::string_view str { "Hello, C++20!" }; + std::cout << (str | std::views::drop(7)).data() << '\\n'; + constexpr static std::array a { 1,2,3,4,5 }; + constexpr auto v { a | std::views::take(3) }; + static_assert( &a[0] == v.data() ); + } + +.SH Output: + + C++20! + +.SH See also + + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP + ranges::data obtains a pointer to the beginning of a contiguous range + (C++20) (customization point object) + ranges::cdata obtains a pointer to the beginning of a read-only contiguous range + (C++20) (customization point object) + to_address obtains a raw pointer from a pointer-like type + (C++20) \fI(function template)\fP diff --git a/man/std::ranges::view_interface::empty.3 b/man/std::ranges::view_interface::empty.3 new file mode 100644 index 000000000..74140bed3 --- /dev/null +++ b/man/std::ranges::view_interface::empty.3 @@ -0,0 +1,102 @@ +.TH std::ranges::view_interface::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::empty \- std::ranges::view_interface::empty + +.SH Synopsis + constexpr bool empty() \fB(1)\fP \fI(since C++20)\fP + requires ranges::sized_range || ranges::forward_range; + constexpr bool empty() const + requires ranges::sized_range || \fB(2)\fP \fI(since C++20)\fP + ranges::forward_range; + + The default implementation of empty() member function checks whether the object of + the derived type's size is 0 (if valid), or whether the beginning iterator and the + sentinel compare equal. + + 1) Let derived be a reference bound to static_cast(*this). Equivalent to return + ranges::size(derived) == 0; if D satisfies sized_range. Otherwise, equivalent to + return ranges::begin(derived) == ranges::end(derived);. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the size of the object of the derived type is 0 (if D satisfies + std::ranges::sized_range), or its beginning iterator and the sentinel compare equal, + false otherwise. + +.SH Notes + + Following derived types may use the default implementation of empty: + + * std::ranges::common_view + * std::ranges::drop_view + * std::ranges::drop_while_view + * std::ranges::elements_view + * std::ranges::filter_view + * std::ranges::join_view + * std::ranges::lazy_split_view + * std::ranges::reverse_view + * std::ranges::single_view + * std::ranges::split_view + * std::ranges::take_view + * std::ranges::take_while_view + * std::ranges::transform_view + + * std::ranges::adjacent_transform_view + * std::ranges::adjacent_view + * std::ranges::as_const_view + * std::ranges::as_rvalue_view + * std::ranges::cartesian_product_view + * std::ranges::chunk_view + * std::ranges::chunk_by_view (since C++23) + * std::ranges::join_with_view + * std::ranges::repeat_view + * std::ranges::slide_view + * std::ranges::stride_view + * std::ranges::zip_view + * std::ranges::zip_transform_view + + Although std::ranges::basic_istream_view inherits from std::ranges::view_interface + and does not declare the empty() member function, it cannot use the default + implementation, because it never satisfies neither std::ranges::sized_range nor + std::ranges::forward_range. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::array a{0, 1, 2, 3, 4}; + static_assert(!std::ranges::single_view(a).empty()); + static_assert((a | std::views::take(0)).empty()); + static_assert(!(a | std::views::take(5)).empty()); + static_assert((a | std::views::drop(5)).empty()); + static_assert(!(a | std::views::drop(3)).empty()); + static_assert(std::views::iota(0,0).empty()); + static_assert(!std::views::iota(0).empty()); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3715 C++20 empty() only supported sized_range-only types are also + forward_range types supported + +.SH See also + + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + ranges::empty checks whether a range is empty + (C++20) (customization point object) diff --git a/man/std::ranges::view_interface::front.3 b/man/std::ranges::view_interface::front.3 new file mode 100644 index 000000000..d1e1ac67f --- /dev/null +++ b/man/std::ranges::view_interface::front.3 @@ -0,0 +1,58 @@ +.TH std::ranges::view_interface::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::front \- std::ranges::view_interface::front + +.SH Synopsis + constexpr decltype(auto) front() \fB(1)\fP \fI(since C++20)\fP + requires ranges::forward_range; + constexpr decltype(auto) front() const \fB(2)\fP \fI(since C++20)\fP + requires ranges::forward_range; + + The default implementation of front() member function returns the first element in + the view of the derived type. Whether the element is returned by value or by + reference depends on the operator* of the iterator type. + + 1) Let derived be static_cast(*this). Equivalent to return + *ranges::begin(derived);. The behavior is undefined if empty() is true (i.e. the + beginning iterator compares equal to the sentinel), even if the iterator obtained in + the same way is dereferenceable. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The first element in the view. + +.SH Notes + + In C++20, no type derived from std::ranges::view_interface in the standard library + provides their own front() member function. Almost all of these types use the + default implementation. + + A notable exception is std::ranges::basic_istream_view. For it never satisfies + forward_range, the view cannot use the inherited front(). + + The inherited front() member function is available for std::ranges::empty_view, but + a call to it always results in undefined behavior. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + ranges::cbegin returns an iterator to the beginning of a read-only range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::view_interface::operator[].3 b/man/std::ranges::view_interface::operator[].3 new file mode 100644 index 000000000..6f22690be --- /dev/null +++ b/man/std::ranges::view_interface::operator[].3 @@ -0,0 +1,52 @@ +.TH std::ranges::view_interface::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::operator[] \- std::ranges::view_interface::operator[] + +.SH Synopsis + template + constexpr decltype(auto) operator[]( ranges::range_difference_t \fB(1)\fP \fI(since C++20)\fP + n ); + template + constexpr decltype(auto) operator[]( ranges::range_difference_t \fB(2)\fP \fI(since C++20)\fP + n ) const; + + The default implementation of operator[] member function obtains the element at the + specified offset relative to the beginning iterator, reusing the operator[] of the + iterator type. + + 1) Let derived be static_cast(*this). Equivalent to return + ranges::begin(derived)[n];. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + n - position of the element to return + +.SH Return value + + The element at offset n relative to the beginning iterator. + +.SH Notes + + In C++20, no type derived from std::ranges::view_interface in the standard library + provides their own operator[] member function. + + However, following derived types cannot use the default implementations, as they + never satisfy random_access_range: + + * std::ranges::basic_istream_view + * std::ranges::filter_view + * std::ranges::join_view + * std::ranges::lazy_split_view + * std::ranges::split_view + + The inherited operator[] member function is available for std::ranges::empty_view, + but a call to it always results in undefined behavior. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::view_interface::operatorbool.3 b/man/std::ranges::view_interface::operatorbool.3 new file mode 100644 index 000000000..95c0f8510 --- /dev/null +++ b/man/std::ranges::view_interface::operatorbool.3 @@ -0,0 +1,67 @@ +.TH std::ranges::view_interface::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::operatorbool \- std::ranges::view_interface::operatorbool + +.SH Synopsis + constexpr explicit operator bool() requires /* see below */; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit operator bool() const requires /* see below */; \fB(2)\fP \fI(since C++20)\fP + + The default implementation of operator bool member function checks whether the view + is non-empty. It makes the derived type contextually convertible to bool. + + 1) Let derived be static_cast(*this). The expression in the requires-clause is + equal to requires { ranges::empty(derived); }, and the function body is equivalent + to return !ranges::empty(derived);. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + false if the value of the derived type is empty (determined by std::ranges::empty), + true otherwise. + +.SH Notes + + In C++20, no type derived from std::ranges::view_interface in the standard library + provides their own operator bool. Almost all of these types use the default + implementation. + + A notable exception is std::ranges::basic_istream_view. For its iterator type never + satisfies forward_iterator, the view cannot use the inherited operator bool. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const std::array ints {0, 1, 2, 3, 4}; + auto odds = ints | std::views::filter([](int i) { return 0 != i % 2; }); + auto negs = ints | std::views::filter([](int i) { return i < 0; }); + std::cout << std::boolalpha + << "Has odd numbers: " << (!!odds) << ' ' << '\\n' + << "Has negative numbers: " << (!!negs) << ' ' << '\\n'; + } + +.SH Output: + + Has odd numbers: true + Has negative numbers: false + +.SH See also + + ranges::empty checks whether a range is empty + (C++20) (customization point object) + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::ranges::view_interface::size.3 b/man/std::ranges::view_interface::size.3 new file mode 100644 index 000000000..f97670903 --- /dev/null +++ b/man/std::ranges::view_interface::size.3 @@ -0,0 +1,71 @@ +.TH std::ranges::view_interface::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::view_interface::size \- std::ranges::view_interface::size + +.SH Synopsis + constexpr auto size() requires ranges::forward_range && + + std::sized_sentinel_for, \fB(1)\fP \fI(since C++20)\fP + + ranges::iterator_t>; + constexpr auto size() const requires ranges::forward_range && + \fB(2)\fP \fI(since C++20)\fP + std::sized_sentinel_for, + + ranges::iterator_t>; + + The default implementation of size() member function obtains the size of the range + by calculating the difference between the sentinel and the beginning iterator. + + 1) Let derived be static_cast(*this). Equivalent to return + /*to-unsigned-like*/(ranges::end(derived) - ranges::begin(derived));, where the + exposition-only function template to-unsigned-like performs the explicit cast from + the argument type to its corresponding unsigned type. + 2) Same as \fB(1)\fP, except that derived is static_cast(*this). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The difference between the sentinel and the beginning iterator of the value of the + derived type, converted to its corresponding unsigned type. + +.SH Notes + + Following derived types may use the default implementation of size(): + + * std::ranges::drop_while_view + + Following types are derived from std::ranges::view_interface and do not declare + their own size() member function, but they cannot use the default implementation, + because their iterator and sentinel types never satisfy sized_sentinel_for: + + * std::ranges::basic_istream_view + * std::ranges::filter_view + * std::ranges::join_view + * std::ranges::lazy_split_view + * std::ranges::split_view + * std::ranges::take_while_view + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3646 C++20 the default implementations of size they return unsigned + functions returned a signed type type + +.SH See also + + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::viewable_range.3 b/man/std::ranges::viewable_range.3 new file mode 100644 index 000000000..d0d6dbea7 --- /dev/null +++ b/man/std::ranges::viewable_range.3 @@ -0,0 +1,84 @@ +.TH std::ranges::viewable_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::viewable_range \- std::ranges::viewable_range + +.SH Synopsis + Defined in header + template< class T > + + concept viewable_range = + ranges::range && + ((ranges::view> && + std::constructible_from, T>) || \fI(since C++20)\fP + (!ranges::view> && + (std::is_lvalue_reference_v || + + (std::movable> && + !/*is-initializer-list*/)))); + + The viewable_range concept is a refinement of range that describes a range that can + be converted into a view through views::all. + + The constant /*is-initializer-list*/ is true if and only if + std::remove_cvref_t is a specialization of std::initializer_list. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct valid_result {}; + struct invalid_result {}; + + template + concept valid_viewable_range = std::same_as; + + template + concept invalid_viewable_range = std::same_as; + + auto test_viewable_range(std::ranges::viewable_range auto &&) -> valid_result; + auto test_viewable_range(auto&&) -> invalid_result; + + int main() + { + auto il = {1, 2, 3}; + int arr []{1, 2, 3}; + std::vector vec{1, 2, 3}; + std::ranges::ref_view r{arr}; + std::ranges::owning_view o{std::string("Hello")}; + + static_assert(requires { + { test_viewable_range(il) } -> valid_viewable_range; + { test_viewable_range(std::move(il)) } -> invalid_viewable_range; + { test_viewable_range(arr) } -> valid_viewable_range; + { test_viewable_range(std::move(arr)) } -> invalid_viewable_range; + { test_viewable_range(vec) } -> valid_viewable_range; + { test_viewable_range(std::move(vec)) } -> valid_viewable_range; + { test_viewable_range(r) } -> valid_viewable_range; + { test_viewable_range(std::move(r)) } -> valid_viewable_range; + { test_viewable_range(o) } -> invalid_viewable_range; + { test_viewable_range(std::move(o)) } -> valid_viewable_range; + { test_viewable_range(std::ranges::ref_view(o)) } -> valid_viewable_range; + }); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3481 C++20 viewable_range accepted an lvalue of a rejects + move-only view + P2415R2 C++20 viewable_range only accepted non-view rvalues accepts more types + that are borrowed_range + +.SH See also + + views::all_t a view that includes all elements of a range + views::all (alias template) (range adaptor object) + (C++20) diff --git a/man/std::ranges::views::adjacent,std::ranges::adjacent_view,std::ranges::views::pairwise.3 b/man/std::ranges::views::adjacent,std::ranges::adjacent_view,std::ranges::views::pairwise.3 new file mode 100644 index 000000000..3cce26f31 --- /dev/null +++ b/man/std::ranges::views::adjacent,std::ranges::adjacent_view,std::ranges::views::pairwise.3 @@ -0,0 +1,176 @@ +.TH std::ranges::views::adjacent,std::ranges::adjacent_view,std::ranges::views::pairwise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::adjacent,std::ranges::adjacent_view,std::ranges::views::pairwise \- std::ranges::views::adjacent,std::ranges::adjacent_view,std::ranges::views::pairwise + +.SH Synopsis + Defined in header + template< ranges::forward_range V, std::size_t N > + + requires ranges::view && (N > 0) \fB(1)\fP (since C++23) + class adjacent_view + + : public ranges::view_interface> + namespace views { + + template< std::size_t N > + inline constexpr /* unspecified */ adjacent = /* unspecified \fB(2)\fP (since C++23) + */ ; + + } + namespace views { + + inline constexpr auto pairwise = adjacent<2>; \fB(3)\fP (since C++23) + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ (since C++23) + + constexpr ranges::view auto adjacent( R&& r ); + + 1) adjacent_view is a range adaptor that takes a view, and produces a view whose + i^th element (a "window") is a std::tuple that holds N references to the elements of + the original view, from i^th up to i + N - 1^th inclusively. + Let S be the size of the original view. Then the size of produced view is: + * S - N + 1, if S >= N, + * 0 otherwise, and the resulting view is empty. + 2) The name views::adjacent denotes a RangeAdaptorObject. Given a subexpression e + and a constant expression N, the expression views::adjacent(e) is + expression-equivalent to + * ((void)e, auto(views::empty>)) if N is equal to 0, + * adjacent_view, N>(e) otherwise. + 3) The name views::pairwise denotes a RangeAdaptorObject that behaves exactly as + views::adjacent<2>. + + adjacent_view always models forward_range, and models bidirectional_range, + random_access_range, or sized_range if adapted view type models the corresponding + concept. + +.SH Member functions + + constructor constructs a adjacent_view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + \fI(none)\fP + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type used when adjacent_view is not a common_range + (C++23) (exposition-only member class template*) + + Helper templates + + template< class V, size_t N > + + inline constexpr bool ranges::enable_borrowed_range> = + + ranges::enable_borrowed_range; + + This specialization of ranges::enable_borrowed_range makes adjacent_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Notes + + There are similarities between ranges::adjacent_view and ranges::slide_view: + + * Both create a "sliding window" of size N. + * Both have the same size S - N + 1, where S is the size of an adapted view such + that S >= N > 0. + + The differences between these adapters are: + + View adaptor value_type The window size N + ranges::adjacent_view A std::tuple object A template parameter + ranges::slide_view A range A runtime parameter + + Feature-test macro Value Std Feature + std::ranges::zip_view, + __cpp_lib_ranges_zip 202110L (C++23) std::ranges::zip_transform_view, + std::ranges::adjacent_view, + std::ranges::adjacent_transform_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::array v{1, 2, 3, 4, 5, 6}; + std::cout << "v = [1 2 3 4 5 6]\\n"; + + for (int i{}; std::tuple t : v | std::views::adjacent<3>) + { + auto [t0, t1, t2] = t; + std::cout << std::format("e = {:<{}}[{} {} {}]\\n", "", 2 * i++, t0, t1, t2); + } + } + +.SH Output: + + v = [1 2 3 4 5 6] + e = [1 2 3] + e = [2 3 4] + e = [3 4 5] + e = [4 5 6] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.25 Adjacent view [range.adjacent] + +.SH See also + + ranges::adjacent_transform_view a view consisting of tuples of results of + views::adjacent_transform application of a transformation function to adjacent + (C++23) elements of the adapted view + \fI(class template)\fP (range adaptor object) + ranges::slide_view a view whose M^th element is a view over the M^th + views::slide through (M + N - 1)^th elements of another view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::chunk_view a range of views that are N-sized non-overlapping + views::chunk successive chunks of the elements of another view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::stride_view a view consisting of elements of another view, + views::stride advancing over N elements at a time + (C++23) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::adjacent_transform,std::ranges::adjacent_transform_view,.3 b/man/std::ranges::views::adjacent_transform,std::ranges::adjacent_transform_view,.3 new file mode 100644 index 000000000..3a353e441 --- /dev/null +++ b/man/std::ranges::views::adjacent_transform,std::ranges::adjacent_transform_view,.3 @@ -0,0 +1,193 @@ +.TH std::ranges::views::adjacent_transform,std::ranges::adjacent_transform_view, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::adjacent_transform,std::ranges::adjacent_transform_view, \- std::ranges::views::adjacent_transform,std::ranges::adjacent_transform_view, + +.SH Synopsis + + Defined in header + template< ranges::forward_range V, std::move_constructible F, + std::size_t N > + + requires ranges::view && (N > 0) && std::is_object_v && + std::regular_invocable, N)...> && \fB(1)\fP C++23) + /*can-reference*/, N)...>> + class adjacent_transform_view + + : public ranges::view_interface> + namespace views { + + template< std::size_t N > (since + inline constexpr /* unspecified */ adjacent_transform = /* \fB(2)\fP C++23) + unspecified */; + + } + namespace views { + (since + inline constexpr auto pairwise_transform = adjacent_transform<2>; \fB(3)\fP C++23) + + } + Call signature + template< ranges::viewable_range R, class F > + (since + requires /* see below */ C++23) + + constexpr ranges::view auto adjacent_transform( R&& r, F&& fun ); + template< class F > (since + constexpr /*range adaptor closure*/ adjacent_transform( F&& fun ); C++23) + + 1) adjacent_transform_view is a range adaptor that takes a view and an invocable + object fun, and produces a view whose i^th element is a value that is the result of + applying fun to each element in [i, i + N) of the original view. F always has arity + N. + Let S be the size of the original view. Then the size of produced view is: + * S - N + 1, if S >= N, + * 0 otherwise, and the resulting view is empty. + 2) The name views::adjacent_transform denotes a RangeAdaptorObject. Given + subexpressions e and f, and a constant expression N, the expression + views::adjacent_transform(e, f) is expression-equivalent to: + * ((void)e, views::zip_transform(f)), if N is equal to 0 (except that the + evaluations of e and f are indeterminately sequenced), + * adjacent_transform_view, + std::decay_t, N>(e, f) otherwise. + 3) The name views::pairwise_transform denotes a RangeAdaptorObject that behaves + exactly as views::adjacent_transform<2>. In particular, the arity of F is also 2 and + fun is a binary invocable object. + + adjacent_transform_view always models forward_range, and models bidirectional_range, + random_access_range, or sized_range, if adapted view type models the corresponding + concept. + +.SH Member functions + + constructor constructs a adjacent_transform_view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + \fI(none)\fP + +.SH Member types + + Member type Definition + InnerView (private) ranges::adjacent_view. + (exposition-only member type*) + * ranges::iterator_t, if Const is true. + inner_iterator (private) Otherwise, + * ranges::iterator_t. + (exposition-only member type*) + * ranges::sentinel_t, if Const is true. + inner_sentinel (private) Otherwise, + * ranges::sentinel_t. + (exposition-only member type*) + + Data members + + Member object Definition + fun_ (private) /*movable-box*/ + (exposition-only member object*) + inner_ (private) ranges::adjacent_view + (exposition-only member object*) + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type used when adjacent_transform_view is not a common_range + (C++23) (exposition-only member class template*) + +.SH Notes + + Feature-test macro Value Std Feature + std::ranges::zip_view, + __cpp_lib_ranges_zip 202110L (C++23) std::ranges::zip_transform_view, + std::ranges::adjacent_view, + std::ranges::adjacent_transform_view + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr static std::array data{1, 2, 3, 4, 5, 6}; + constexpr int window{3}; + + auto Fun = [](auto... ints) { return (... + ints); }; + // Alternatively, the Fun could be any ternary (if window == 3) callable, e.g.: + // auto Fun = [](int x, int y, int z) { return x + y + z; }; + + constexpr auto view = data | std::views::adjacent_transform(Fun); + + static_assert( + view.size() == (data.size() - window + 1) + && std::array{6, 9, 12, 15} + == std::array{view[0], view[1], view[2], view[3]} + && view[0] == Fun(data[0], data[1], data[2]) + && view[1] == Fun(data[1], data[2], data[3]) + && view[2] == Fun(data[2], data[3], data[4]) + && view[3] == Fun(data[3], data[4], data[5]) + ); + + for (int x : view) + std::cout << x << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 6 9 12 15 + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.27 Adjacent transform view [range.adjacent.transform] + +.SH See also + + ranges::adjacent_view a view consisting of tuples of references to adjacent + views::adjacent elements of the adapted view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::transform_view a view of a sequence that applies a transformation + views::transform function to each element + (C++20) \fI(class template)\fP (range adaptor object) + ranges::zip_transform_view a view consisting of tuples of results of application of + views::zip_transform a transformation function to corresponding elements of + (C++23) the adapted views + \fI(class template)\fP (customization point object) + ranges::transform applies a function to a range of elements + (C++20) (niebloid) diff --git a/man/std::ranges::views::all,std::ranges::views::all_t.3 b/man/std::ranges::views::all,std::ranges::views::all_t.3 new file mode 100644 index 000000000..8e1d79559 --- /dev/null +++ b/man/std::ranges::views::all,std::ranges::views::all_t.3 @@ -0,0 +1,84 @@ +.TH std::ranges::views::all,std::ranges::views::all_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::all,std::ranges::views::all_t \- std::ranges::views::all,std::ranges::views::all_t + +.SH Synopsis + Defined in header + inline constexpr /* unspecified */ all = /* unspecified */; \fB(1)\fP \fI(since C++20)\fP + template< ranges::viewable_range R > \fB(2)\fP \fI(since C++20)\fP + using all_t = decltype(views::all(std::declval())); + + 1) A RangeAdaptorObject (also a RangeAdaptorClosureObject) that returns a view that + includes all elements of its range argument. + Given an expression e of type R, the expression views::all(e) is + expression-equivalent to: + * Implicitly converting e to a std::decay_t prvalue, if std::decay_t models + view. + * Otherwise, std::ranges::ref_view{e} if that expression is well-formed. + * Otherwise, std::ranges::owning_view{e}. + 2) Calculates the suitable view type of a viewable_range type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector v{0, 1, 2, 3, 4, 5}; + for (int n : std::views::all(v) | std::views::take(2)) + std::cout << n << ' '; + std::cout << '\\n'; + + static_assert(std::is_same< + decltype(std::views::single(42)), + std::ranges::single_view + >{}); + + static_assert(std::is_same< + decltype(std::views::all(v)), + std::ranges::ref_view>> + >{}); + + int a[]{1, 2, 3, 4}; + static_assert(std::is_same< + decltype(std::views::all(a)), + std::ranges::ref_view + >{}); + + static_assert(std::is_same< + decltype(std::ranges::subrange{std::begin(a) + 1, std::end(a) - 1}), + std::ranges::subrange + >{}); + } + +.SH Output: + + 0 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3724 C++20 views::all might result in hard it gets well-constrained + error for some move-only views + P2415R2 C++20 views::all returned a subrange for returns an owning_view for it + a non-view rvalue range + +.SH See also + + ranges::empty_view an empty view with no elements + views::empty \fI(class template)\fP (variable template) + (C++20) + ranges::single_view a view that contains a single element of a specified value + views::single \fI(class template)\fP (customization point object) + (C++20) + ranges::owning_view a view with unique ownership of some range + (C++20) \fI(class template)\fP diff --git a/man/std::ranges::views::as_const,std::ranges::as_const_view.3 b/man/std::ranges::views::as_const,std::ranges::as_const_view.3 new file mode 100644 index 000000000..7bb72fa10 --- /dev/null +++ b/man/std::ranges::views::as_const,std::ranges::as_const_view.3 @@ -0,0 +1,188 @@ +.TH std::ranges::views::as_const,std::ranges::as_const_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::as_const,std::ranges::as_const_view \- std::ranges::views::as_const,std::ranges::as_const_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + requires ranges::input_range \fB(1)\fP (since C++23) + class as_const_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ as_const = /* unspecified \fB(2)\fP (since C++23) + */; + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ (since C++23) + + constexpr ranges::view auto as_const( R&& r ); + + 1) A range adaptor that represents a view of underlying view that is also a + constant_range. An as_const_view always has read-only elements (if not empty). + 2) RangeAdaptorObject. Let e be a subexpression, let T be decltype((e)), and let U + be std::remove_cvref_t. Then the expression views::as_const(e) is + expression-equivalent to: + * views::all(e), if it is a well-formed expression and views::all_t models + constant_range; + * otherwise, std::span(e) for some type X and some extent Extent + if U denotes std::span; + * otherwise, ranges::ref_view(static_cast(e.base())) if U denotes + ranges::ref_view for some type X and const X models constant_range; + * otherwise, ranges::ref_view(static_cast(e)) if e is an lvalue, const U + models constant_range, and U does not model view. + * otherwise, as_const_view{e}. + + as_const_view always models constant_range, and it models the contiguous_range, + random_access_range, bidirectional_range, forward_range, borrowed_range, + common_range, and sized_range when the underlying view V models respective concepts. + +.SH Member functions + + constructor constructs an as_const_view + \fI(public member function)\fP + base returns the underlying view V + \fI(public member function)\fP + begin returns the beginning iterator of the as_const_view + \fI(public member function)\fP + end returns the end iterator of the as_const_view + \fI(public member function)\fP + size returns the size of the view if it is bounded + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::as_const_view::as_const_view + + as_const_view() requires std::default_initializable = default; \fB(1)\fP (since C++23) + constexpr explicit as_const_view( V base ); \fB(2)\fP (since C++23) + + 1) Value-initializes base_ via its default member initializer (= V()). + 2) Initializes base_ with std::move(base). + +.SH Parameters + + base - a view + +std::ranges::as_const_view::base + + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns the underlying view. + + 1) Copy-constructs the result from the underlying view. Equivalent to return base_;. + 2) Move-constructs the result from the underlying view. Equivalent to return + std::move(base_);. + +std::ranges::as_const_view::begin + + constexpr auto begin() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto begin() const requires ranges::range; \fB(2)\fP (since C++23) + + Returns the constant iterator of the view. + + 1,2) Equivalent to return ranges::cbegin(base_); + +std::ranges::as_const_view::end + + constexpr auto end() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto end() const requires ranges::range; \fB(2)\fP (since C++23) + + Returns the constant sentinel of the view. + + 1,2) Equivalent to return ranges::cend(base_); + +std::ranges::as_const_view::size + + constexpr auto size() requires ranges::sized_range; \fB(1)\fP (since C++23) + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP (since C++23) + + Returns the size of the view if the view is bounded. + + 1,2) Equivalent to return ranges::size(base_); + + Deduction guides + + template< class R > (since C++23) + as_const_view( R&& ) -> as_const_view>; + + Helper templates + + template< class T > + + inline constexpr bool enable_borrowed_range> (since + = C++23) + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes as_const_view + satisfy borrowed_range when the underlying view satisfies it. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_as_const 202207L (C++23) std::ranges::as_const_view, + std::const_iterator + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int x[]{1, 2, 3, 4, 5}; + + auto v1 = x | std::views::drop(2); + assert(v1.back() == 5); + v1[0]++; // OK, can modify non-const element + + auto v2 = x | std::views::drop(2) | std::views::as_const; + assert(v2.back() == 5); + // v2[0]++; // Compile-time error, cannot modify read-only element + } + +.SH See also + + ranges::as_rvalue_view a view of a sequence that casts each element to an rvalue + views::as_rvalue \fI(class template)\fP (range adaptor object) + (C++23) + ranges::cbegin returns an iterator to the beginning of a read-only range + (C++20) (customization point object) + ranges::cend returns a sentinel indicating the end of a read-only range + (C++20) (customization point object) + as_const obtains a reference to const to its argument + \fI(C++17)\fP \fI(function template)\fP + basic_const_iterator iterator adaptor that converts an iterator into a constant + (C++23) iterator + \fI(class template)\fP diff --git a/man/std::ranges::views::as_rvalue,std::ranges::as_rvalue_view.3 b/man/std::ranges::views::as_rvalue,std::ranges::as_rvalue_view.3 new file mode 100644 index 000000000..bdc912745 --- /dev/null +++ b/man/std::ranges::views::as_rvalue,std::ranges::as_rvalue_view.3 @@ -0,0 +1,155 @@ +.TH std::ranges::views::as_rvalue,std::ranges::as_rvalue_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::as_rvalue,std::ranges::as_rvalue_view \- std::ranges::views::as_rvalue,std::ranges::as_rvalue_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + requires ranges::input_range \fB(1)\fP (since C++23) + class as_rvalue_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ as_rvalue = /* unspecified \fB(2)\fP (since C++23) + */; + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ (since C++23) + + constexpr ranges::view auto as_rvalue( R&& r ); + + 1) A range adaptor that represents a view of underlying view whose elements are + rvalues. + 2) RangeAdaptorObject. Let e be a subexpression and let T be decltype((e)). Then the + expression views::as_rvalue(e) is expression-equivalent to: + * views::all(e), if it is a well-formed expression and + std::same_as, ranges::range_reference_t> + is true; + * as_rvalue_view{e} otherwise. + +.SH Member functions + + constructor constructs an as_rvalue_view + \fI(public member function)\fP + base returns the underlying view V + \fI(public member function)\fP + begin returns the beginning iterator of the as_rvalue_view + \fI(public member function)\fP + end returns the end iterator of the as_rvalue_view + \fI(public member function)\fP + size returns the size of the view if it is bounded + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::as_rvalue_view::as_rvalue_view + + as_rvalue_view() requires std::default_initializable = default; \fB(1)\fP (since C++23) + constexpr explicit as_rvalue_view( V base ); \fB(2)\fP (since C++23) + + 1) Value-initializes base_ via its default member initializer (= V()). + 2) Initializes base_ with std::move(base). + +.SH Parameters + + base - a view + +std::ranges::as_rvalue_view::base + + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP (since C++23) + constexpr V base() &&; \fB(2)\fP (since C++23) + + Returns the underlying view. + + 1) Copy-constructs the result from the underlying view. Equivalent to return base_;. + 2) Move-constructs the result from the underlying view. Equivalent to return + std::move(base_);. + +std::ranges::as_rvalue_view::begin + + constexpr auto begin() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto begin() const requires ranges::range; \fB(2)\fP (since C++23) + + 1,2) Returns std::move_iterator(ranges::begin(base_)). + +std::ranges::as_rvalue_view::end + + constexpr auto end() requires (!__simple_view); \fB(1)\fP (since C++23) + constexpr auto end() const requires ranges::range; \fB(2)\fP (since C++23) + + 1) Returns std::move_iterator(ranges::end(base_)) if V models common_range, + otherwise std::move_sentinel(ranges::end(base_)). + 2) Returns std::move_iterator(ranges::end(base_)) if const V models common_range, + otherwise std::move_sentinel(ranges::end(base_)). + +std::ranges::as_rvalue_view::size + + constexpr auto size() requires ranges::sized_range; \fB(1)\fP (since C++23) + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP (since C++23) + + Returns the size of the view if the view is bounded. + + 1,2) Equivalent to return ranges::size(base_); + + Deduction guides + + template< class R > (since C++23) + as_rvalue_view( R&& ) -> as_rvalue_view>; + + Helper templates + + template< class T > + + inline constexpr bool enable_borrowed_range> (since + = C++23) + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes as_rvalue_view + satisfy borrowed_range when the underlying view satisfies it. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_as_rvalue 202207L (C++23) std::ranges::as_rvalue_view + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + move_iterator iterator adaptor which dereferences to an rvalue + \fI(C++11)\fP \fI(class template)\fP + move_sentinel sentinel adaptor for use with std::move_iterator + (C++20) \fI(class template)\fP + ranges::as_const_view converts a view into a constant_range + views::as_const \fI(class template)\fP (range adaptor object) + (C++23) + +.SH Category: + * Todo with reason diff --git a/man/std::ranges::views::cartesian_product,std::ranges::cartesian_product_view.3 b/man/std::ranges::views::cartesian_product,std::ranges::cartesian_product_view.3 new file mode 100644 index 000000000..d8bb9e838 --- /dev/null +++ b/man/std::ranges::views::cartesian_product,std::ranges::cartesian_product_view.3 @@ -0,0 +1,209 @@ +.TH std::ranges::views::cartesian_product,std::ranges::cartesian_product_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::cartesian_product,std::ranges::cartesian_product_view \- std::ranges::views::cartesian_product,std::ranges::cartesian_product_view + +.SH Synopsis + Defined in header + template< ranges::input_range First, ranges::forward_range... Vs + > + + requires (ranges::view && ... && ranges::view) \fB(1)\fP (since C++23) + class cartesian_product_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /*unspecified*/ cartesian_product = \fB(2)\fP (since C++23) + /*unspecified*/; + + } + Call signature + template< ranges::viewable_range... Rs > + + requires /* see below */ (since C++23) + + constexpr auto cartesian_product( Rs&&... rs ); + Helper concepts + template< bool Const, class First, class... Vs > + + concept __cartesian_product_is_random_access = + (ranges::random_access_range<__maybe_const> && \fB(3)\fP (exposition + ... && only*) + (ranges::random_access_range<__maybe_const> && + + ranges::sized_range<__maybe_const>)); + template< class R > + + concept __cartesian_product_common_arg = (exposition + ranges::common_range || \fB(4)\fP only*) + + (ranges::sized_range && + ranges::random_access_range); + template< bool Const, class First, class... Vs > + + concept __cartesian_product_is_bidirectional = + (ranges::bidirectional_range<__maybe_const> && (exposition + ... && \fB(5)\fP only*) + (ranges::bidirectional_range<__maybe_const> && + + __cartesian_product_common_arg<__maybe_const>)); + template< class First, class... Vs > + (exposition + concept __cartesian_product_is_common = \fB(6)\fP only*) + + __cartesian_product_common_arg; + template< class... Vs > + (exposition + concept __cartesian_product_is_sized = \fB(7)\fP only*) + + (ranges::sized_range && ...); + template< bool Const, template class FirstSent, class + First, class... Vs > + + concept __cartesian_is_sized_sentinel = + (ranges::sized_sentinel_for>, + ranges::iterator_t<__maybe_const>> && ... \fB(8)\fP (exposition + && only*) + (ranges::sized_range<__maybe_const> && + + ranges::sized_sentinel_for>, + + ranges::iterator_t<__maybe_const>>)); + Helper function templates + template< __cartesian_product_common_arg R > + + constexpr auto __cartesian_common_arg_end( R& r ) { + if constexpr (ranges::common_range) (exposition + return ranges::end(r); \fB(9)\fP only*) + else + return ranges::begin(r) + ranges::distance(r); + + } + + 1) cartesian_product_view is a range adaptor that takes n views, where n > 0, and + produces a view of tuples calculated by the n-ary cartesian product of the provided + ranges. The size of produced view is a multiple of sizes of provided ranges, while + each element is a tuple (of references) of the size n. + 2) views::cartesian_product is a customization point object. + * When calling with no argument, views::cartesian_product() is + expression-equivalent to views::single(std::tuple()). + * Otherwise, views::cartesian_product(rs...) is expression-equivalent to + ranges::cartesian_product_view...>(rs...). + 3) Determines if cartesian_product is a random access range (see also + random_access_range). + 4) Determines if cartesian_product is a common range (see also common_range). + 5) Determines if cartesian_product is a bidirectional range (see also + bidirectional_range). + 6) Determines if cartesian_product satisfies the helper concept + __cartesian_product_is_common (see also common_range). + 7) Determines if cartesian_product is a sized range (see also sized_range). + 8) Determines if cartesian_product uses sized sentinel. + 9) Returns the end of the produced view. Participates in overload resolution only if + cartesian_product satisfies the helper concept __cartesian_product_common_arg. + + The First range passed to cartesian_product_view is treated specially, since it is + only passed through a single time. As a result, several constrains are relaxed on + it: + + * First is an input_range instead of forward_range; + * First does not have to be a sized_range in order for the cartesian_product_view + to be random_access_range or common_range; + * First does not have to be common_range in order for the cartesian_product_view + to be bidirectional_range. + +.SH Member functions + + constructor constructs a cartesian_product_view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_cartesian_product 202207L (C++23) std::ranges::cartesian_product_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void print(std::tuple t, int pos) + { + const auto& [a, b, c] = t; + std::cout << '(' << a << ' ' << b << ' ' << c << ')' << (pos % 4 ? " " : "\\n"); + } + + int main() + { + const auto x = std::array{'A', 'B'}; + const auto y = std::vector{1, 2, 3}; + const auto z = std::list{"α", "β", "γ", "δ"}; + + for (int i{1}; auto const& tuple : std::views::cartesian_product(x, y, z)) + print(tuple, i++); + } + +.SH Output: + + (A 1 α) (A 1 β) (A 1 γ) (A 1 δ) + (A 2 α) (A 2 β) (A 2 γ) (A 2 δ) + (A 3 α) (A 3 β) (A 3 γ) (A 3 δ) + (B 1 α) (B 1 β) (B 1 γ) (B 1 δ) + (B 2 α) (B 2 β) (B 2 γ) (B 2 δ) + (B 3 α) (B 3 β) (B 3 γ) (B 3 δ) + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.31 Cartesian product view [range.stride] + +.SH See also + + ranges::zip_view a view consisting of tuples of references to corresponding elements + views::zip of the adapted views + (C++23) \fI(class template)\fP (customization point object) diff --git a/man/std::ranges::views::chunk,std::ranges::chunk_view.3 b/man/std::ranges::views::chunk,std::ranges::chunk_view.3 new file mode 100644 index 000000000..e11b5cd4e --- /dev/null +++ b/man/std::ranges::views::chunk,std::ranges::chunk_view.3 @@ -0,0 +1,193 @@ +.TH std::ranges::views::chunk,std::ranges::chunk_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::chunk,std::ranges::chunk_view \- std::ranges::views::chunk,std::ranges::chunk_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + requires ranges::input_range \fB(1)\fP (since C++23) + class chunk_view + + : public ranges::view_interface> + template< ranges::view V > + + requires ranges::forward_range \fB(2)\fP (since C++23) + class chunk_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ chunk = /* unspecified \fB(3)\fP (since C++23) + */; + + } + Call signature + template< ranges::viewable_range R > + constexpr ranges::view auto chunk( R&& r, (since C++23) + ranges::range_difference_t n ); + template< class DifferenceType > + constexpr /*range adaptor closure*/ chunk( DifferenceType&& n (since C++23) + ); + Helper templates + template< class I > \fB(4)\fP (exposition only*) + constexpr I __div_ceil( I num, I denom ); + + chunk_view takes a view and a number n and produces a range of views (the chunks) of + the original view, such that each chunk, except maybe the last one, has the size n. + These chunks are non-overlapping, successive sub-ranges of the elements of the + original view, in order. + + Let s be the size of the original view. If s is not the multiple of n, the size of + the last produced view is exactly s % n (the remainder). Otherwise, the size of each + chunk, including the last one, is n. + + The size of produced view is __div_ceil(s). + + If the n is not greater than 0 the behavior is undefined. + + 1) An implementation that supports the underlying view V that models only + input_range. + 2) A partial specialization that supports the underlying view V that models + forward_range or stronger. Models common_range if the underlying view V is + forward_range, common_range, and either sized_range or non bidirectional_range. + 3) The name views::chunk denotes a RangeAdaptorObject. Given subexpressions e and n, + the expression views::chunk(e, n) is expression-equivalent to chunk_view(e, n). + 4) Computes the smallest integer value that is not less than the quotient of + dividing num by denom. Equivalent to: + + I r = num / denom; + if (num % denom) + ++r; + return r; + +.SH Member functions + + constructor constructs a chunk_view + (C++23) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + outer_iterator the output ("chunk-wise") iterator type when V models input_range \fB(1)\fP + (C++23) (exposition-only member class*) + inner_iterator the inner ("element-wise") iterator type when V models input_range + (C++23) \fB(1)\fP + (exposition-only member class*) + iterator the iterator type when V models forward_range \fB(2)\fP + (C++23) (exposition-only member class template*) + + Helper templates + + template< class V > + + inline constexpr bool ranges::enable_borrowed_range> = (since C++23) + + ranges::forward_range && ranges::enable_borrowed_range; + + This specialization of ranges::enable_borrowed_range makes chunk_view satisfy + borrowed_range when the underlying view V satisfies both, the forward_range and the + borrowed_range. + +.SH Notes + + If V models input_range \fB(1)\fP, chunk_view's iterator has a dedicated type: + outer_iterator::value_type that is itself an input view. + + If V models forward_range or stronger \fB(2)\fP, chunk_view defers to views::take for its + value_type. + + If V models bidirectional_range or stronger ranges \fB(2)\fP, the need to calculate size + the last chunk correctly (from the end iterator) requires the underlying range type + V to be sized_range. + + Feature-test macro Value Std Feature + __cpp_lib_ranges_chunk 202202L (C++23) std::ranges::chunk_view + +.SH Example + + +// Run this code + + #include + #include + #include + + auto print_subrange = [](std::ranges::viewable_range auto&& r) + { + std::cout << '['; + for (int pos{}; auto elem : r) + std::cout << (pos++ ? " " : "") << elem; + std::cout << "] "; + }; + + int main() + { + const auto v = {1, 2, 3, 4, 5, 6}; + + for (const unsigned width : std::views::iota(1U, 2U + v.size())) + { + auto const chunks = v | std::views::chunk(width); + std::cout << "chunk(" << width << "): "; + std::ranges::for_each(chunks, print_subrange); + std::cout << '\\n'; + } + } + +.SH Output: + + chunk\fB(1)\fP: [1] [2] [3] [4] [5] [6] + chunk\fB(2)\fP: [1 2] [3 4] [5 6] + chunk\fB(3)\fP: [1 2 3] [4 5 6] + chunk\fB(4)\fP: [1 2 3 4] [5 6] + chunk\fB(5)\fP: [1 2 3 4 5] [6] + chunk\fB(6)\fP: [1 2 3 4 5 6] + chunk\fB(7)\fP: [1 2 3 4 5 6] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.28 Chunk view [range.chunk] + +.SH See also + + ranges::chunk_by_view splits the view into subranges between each pair of adjacent + views::chunk_by elements for which the given predicate returns false + (C++23) \fI(class template)\fP (range adaptor object) + ranges::adjacent_view a view consisting of tuples of references to adjacent elements + views::adjacent of the adapted view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::slide_view a view whose M^th element is a view over the M^th through (M + + views::slide N - 1)^th elements of another view + (C++23) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::chunk_by,std::ranges::chunk_by_view.3 b/man/std::ranges::views::chunk_by,std::ranges::chunk_by_view.3 new file mode 100644 index 000000000..b46fa245f --- /dev/null +++ b/man/std::ranges::views::chunk_by,std::ranges::chunk_by_view.3 @@ -0,0 +1,161 @@ +.TH std::ranges::views::chunk_by,std::ranges::chunk_by_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::chunk_by,std::ranges::chunk_by_view \- std::ranges::views::chunk_by,std::ranges::chunk_by_view + +.SH Synopsis + Defined in header + template< ranges::forward_range V, + std::indirect_binary_predicate, + + ranges::iterator_t> Pred > \fB(1)\fP (since C++23) + requires ranges::view && std::is_object_v + class chunk_by_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ chunk_by = /* unspecified \fB(2)\fP (since C++23) + */ ; + + } + Call signature + template< ranges::viewable_range R, class Pred > + + requires /* see below */ (since C++23) + + constexpr ranges::view auto chunk_by( R&& r, Pred&& pred ); + template< class Pred > (since C++23) + constexpr /*range adaptor closure*/ chunk_by( Pred&& pred ); + + 1) chunk_by_view is a range adaptor that takes a view and an invocable object pred + (the binary predicate), and produces a view of subranges (chunks), by splitting the + underlying view between each pair of adjacent elements for which pred returns false. + The first element of each such pair belongs to the previous chunk, and the second + element belongs to the next chunk. + 2) The name views::chunk_by denotes a RangeAdaptorObject. Given a subexpression e + and f, the expression views::chunk_by(e, f) is expression-equivalent to + chunk_by_view(e, f). + + chunk_by_view always models forward_range, and models bidirectional_range and/or + common_range, if adapted view type models the corresponding concepts. chunk_by_view + never models borrowed_range or sized_range. + +.SH Member functions + + constructor constructs a chunk_by_view + (C++23) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++23) \fI(public member function)\fP + pred returns a reference to the stored predicate + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + find_next returns an iterator to the begin of the next subrange + (C++23) (exposition-only member function*) + find_prev returns an iterator to the begin of the previous subrange + (C++23) (exposition-only member function*) + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + +.SH Notes + + In order to provide the amortized constant time complexity required by the range + concept, the result of begin() is cached within the chunk_by_view object. If the + underlying range is modified after the first call to begin(), subsequent uses of the + chunk_by_view object might have unintuitive behavior. + + Feature-test macro Value Std Feature + __cpp_lib_ranges_chunk_by 202202L (C++23) std::ranges::chunk_by_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print_chunks(auto view, std::string_view separator = ", ") + { + for (auto const subrange : view) + { + std::cout << '['; + for (std::string_view prefix; auto const& elem : subrange) + std::cout << prefix << elem, prefix = separator; + std::cout << "] "; + } + std::cout << '\\n'; + } + + int main() + { + { + auto v = std::vector{1, 2, 3, 1, 2, 3, 3, 3, 1, 2, 3}; + auto fun = std::ranges::less{}; + auto view = v | std::views::chunk_by(fun); + print_chunks(view); + } + { + auto v = std::vector{1, 2, 3, 4, 4, 0, 2, 3, 3, 3, 2, 1}; + auto fun = std::not_fn(std::ranges::equal_to{}); // or ranges::not_equal_to + auto view = v | std::views::chunk_by(fun); + print_chunks(view); + } + { + std::string v = "__cpp_lib_ranges_chunk_by"; + auto fun = [](char x, char y) { return not(x == '_' or y == '_'); }; + auto view = v | std::views::chunk_by(fun); + print_chunks(view, ""); + } + } + +.SH Output: + + [1, 2, 3] [1, 2, 3] [3] [3] [1, 2, 3] + [1, 2, 3, 4] [4, 0, 2, 3] [3] [3, 2, 1] + [_] [_] [cpp] [_] [lib] [_] [ranges] [_] [chunk] [_] [by] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.30 Chunk by view [range.chunk.by] + +.SH See also + + ranges::chunk_view a range of views that are N-sized non-overlapping successive + views::chunk chunks of the elements of another view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::slide_view a view whose M^th element is a view over the M^th through (M + N + views::slide - 1)^th elements of another view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::stride_view a view consisting of elements of another view, advancing over N + views::stride elements at a time + (C++23) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::common,std::ranges::common_view.3 b/man/std::ranges::views::common,std::ranges::common_view.3 new file mode 100644 index 000000000..025bae878 --- /dev/null +++ b/man/std::ranges::views::common,std::ranges::common_view.3 @@ -0,0 +1,157 @@ +.TH std::ranges::views::common,std::ranges::common_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::common,std::ranges::common_view \- std::ranges::views::common,std::ranges::common_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + requires (not ranges::common_range and + std::copyable>) \fB(1)\fP \fI(since C++20)\fP + class common_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ common = /* unspecified */; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto common( R&& r ); + + 1) Adapts a given view with different types for iterator/sentinel pair into a view + that is also a common_range. A common_view always has the same iterator/sentinel + type. + 2) RangeAdaptorObject. Let e be a subexpression. Then the expression + views::common(e) is expression-equivalent to: + * views::all(e), if it is a well-formed expression and decltype((e)) models + common_range; + * common_view{e} otherwise. + +.SH Member functions + + constructor constructs a common_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator to the end + (C++20) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++20) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Helper templates + + template< class T > + + inline constexpr bool \fI(since C++20)\fP + enable_borrowed_range> = + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes common_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Notes + + common_view can be useful for working with legacy algorithms that expect the + iterator and sentinel are of the same type. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto v1 = {1, 2, 3, 4, 5}; + auto i1 = std::counted_iterator{v1.begin(), std::ssize(v1)}; + auto r1 = std::ranges::subrange{i1, std::default_sentinel}; + // auto e1 = std::accumulate(r1.begin(), r1.end(), 0); // error: "common range" required + auto c1 = std::ranges::common_view{r1}; + std::cout << "accumulate: " << std::accumulate(c1.begin(), c1.end(), 0) << '\\n'; + + // inherited from ranges::view_interface: + std::cout << "c1.front(): " << c1.front() << '\\n'; + std::cout << "c1.back(): " << c1.back() << '\\n'; + std::cout << "c1.data(): " << c1.data() << '\\n'; + std::cout << "c1[0]: " << c1[0] << '\\n'; + + auto v2 = std::list{1, 2, 3, 4, 5}; + auto i2 = std::counted_iterator{v2.begin(), std::ssize(v2)}; + auto r2 = std::ranges::subrange{i2, std::default_sentinel}; + // auto e2 = std::accumulate(r2.begin(), r2.end(), 0); // error: "common range" required + auto c2 = std::ranges::common_view{ r2 }; + std::cout << "accumulate: " << std::accumulate(c2.begin(), c2.end(), 0) << '\\n'; + + // inherited from ranges::view_interface: + std::cout << "c2.front(): " << c2.front() << '\\n'; + // auto e3 = c2.back(); // error: "bidirectional range" required + // auto e4 = c2.data(); // error: "contiguous range" required + // auto e5 = c2[0]; // error: "random access range" required + } + +.SH Possible output: + + accumulate: 15 + c1.front(): 1 + c1.back(): 5 + c1.data(): 0x7f19937f00d0 + c1[0]: 1 + accumulate: 15 + c2.front(): 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3494 C++20 common_view was never a it is a borrowed_range if its underlying + borrowed_range view is + +.SH See also + + ranges::common_range specifies that a range has identical iterator and sentinel + (C++20) types + (concept) + common_iterator adapts an iterator type and its sentinel into a common iterator + (C++20) type + \fI(class template)\fP diff --git a/man/std::ranges::views::counted.3 b/man/std::ranges::views::counted.3 new file mode 100644 index 000000000..f54f0c73c --- /dev/null +++ b/man/std::ranges::views::counted.3 @@ -0,0 +1,93 @@ +.TH std::ranges::views::counted 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::counted \- std::ranges::views::counted + +.SH Synopsis + Defined in header + inline constexpr /*unspecified*/ counted = /*unspecified*/; \fI(since C++20)\fP + Call signature + template< class Iterator, class DifferenceType > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /*span-or-subrange*/ counted( Iterator&& it, + DifferenceType&& count ); + + A counted view presents a view of the elements of the counted range [i, n) for some + iterator i and non-negative integer n. + + A counted range [i, n) is the n elements starting with the element pointed to by i + and up to but not including the element, if any, pointed to by the result of n + applications of ++i. + + If n == 0, the counted range is valid and empty. Otherwise, the counted range is + only valid if n is positive, i is dereferenceable, and [++i, --n) is a valid counted + range. + + Formally, if it and count are expressions, T is std::decay_t, and D + is std::iter_difference_t, then + + if T models input_or_output_iterator and decltype((count)) models + std::convertible_to, + * if T models contiguous_iterator, then views::counted(it, count) is + expression-equivalent to std::span(std::to_address(it), + static_cast(static_cast(count))), + * otherwise, if T models random_access_iterator, then views::counted(it, count) is + expression-equivalent to ranges::subrange(it, it + static_cast(count)), + * otherwise, views::counted(it, count) is expression-equivalent to + ranges::subrange(std::counted_iterator(it, count), std::default_sentinel). + Otherwise, views::counted(it, count) is ill-formed. + +.SH Notes + + views::counted does not check if the range is long enough to provide all count + elements: use views::take if that check is necessary. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const int a[]{1, 2, 3, 4, 5, 6, 7}; + for (int i : std::views::counted(a, 3)) + std::cout << i << ' '; + std::cout << '\\n'; + + const auto il = {1, 2, 3, 4, 5}; + for (int i : std::views::counted(il.begin() + 1, 3)) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 + 2 3 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2393R1 C++20 implicit conversion from an integer-class type made explicit + to std::size_t might be invalid + +.SH See also + + ranges::take_view a view consisting of the first N elements of another view + views::take \fI(class template)\fP (range adaptor object) + (C++20) + ranges::subrange combines an iterator-sentinel pair into a view + (C++20) \fI(class template)\fP + counted_iterator iterator adaptor that tracks the distance to the end of the range + (C++20) \fI(class template)\fP + ranges::count + ranges::count_if returns the number of elements satisfying specific criteria + (C++20) (niebloid) + (C++20) diff --git a/man/std::ranges::views::drop,std::ranges::drop_view.3 b/man/std::ranges::views::drop,std::ranges::drop_view.3 new file mode 100644 index 000000000..09f412f94 --- /dev/null +++ b/man/std::ranges::views::drop,std::ranges::drop_view.3 @@ -0,0 +1,177 @@ +.TH std::ranges::views::drop,std::ranges::drop_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::drop,std::ranges::drop_view \- std::ranges::views::drop,std::ranges::drop_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + class drop_view \fB(1)\fP \fI(since C++20)\fP + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ drop = /* unspecified */; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ \fI(since C++20)\fP + constexpr ranges::view auto + + drop( R&& r, ranges::range_difference_t count ); + template< class DifferenceType > + constexpr /* range adaptor closure */ drop( DifferenceType&& count \fI(since C++20)\fP + ); + + 1) A range adaptor consisting of elements of the underlying sequence, skipping the + first N elements. + 2) RangeAdaptorObject. Given T is std::remove_cvref_t and D is + ranges::range_difference_t), the expression views::drop(e, f) is + expression-equivalent to: + * ((void)f, decay-copy(e)), if T is a ranges::empty_view, except that the + evaluations of e and f are indeterminately sequenced; + * otherwise, T(ranges::begin(e) + inc, ranges::end(e), + /* to-unsigned-like */(ranges::distance(e) - inc)), if T is a specialization + of ranges::subrange that models both random_access_range and sized_range, and T + needs to store the size (see ranges::subrange::subrange for details), where inc + is std::min(ranges::distance(e), f); + * otherwise, U(ranges::begin(e) + inc, ranges::end(e)), if T is a specialization + of std::span, std::basic_string_view, ranges::iota_view, or ranges::subrange + that models both random_access_range and sized_range, where U is + + * std::span, if T is a specialization of std::span; + * T otherwise; + + * otherwise, if T is a specialization of ranges::repeat_view: + + * views::repeat(*e.value_, ranges::distance(e) - inc), if T models (since C++23) + sized_range; in such case e is evaluated only once; + * ((void)e, auto(f)) otherwise, except that the evaluations of e and + f are indeterminately sequenced; + + * otherwise, drop_view(e, f). + In all cases, decltype((f)) must model std::convertible_to. + + drop_view models the concepts contiguous_range, random_access_range, + bidirectional_range, forward_range, input_range, common_range, and sized_range when + the underlying view V models respective concepts. + +.SH Member functions + + constructor constructs a drop_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++20) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Helper templates + + template + + inline constexpr bool \fI(since C++20)\fP + enable_borrowed_range> = + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes drop_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto nums = {1, 2, 3, 4, 5, 6, 7}; + + std::cout << "drop " << 2 << ": "; + for (int i : std::ranges::drop_view{nums, 2}) + std::cout << i << ' '; + std::cout << '\\n'; + + std::cout << "drop " << 3 << ": "; + for (int i : nums | std::views::drop(3)) + std::cout << i << ' '; + std::cout << '\\n'; + + std::cout << "drop " << 4 << ": "; + for (int i : std::views::iota(1, 8) | std::views::drop(4)) + std::cout << i << ' '; + std::cout << '\\n'; + + // Note that dropping more than the number of elements is OK: + for (int dp : {5, 6, 7, 890, 100500}) + { + std::cout << "drop " << dp << ": "; + for (int i : std::views::iota(1, 8) | std::views::drop(dp)) + std::cout << i << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + drop 2: 3 4 5 6 7 + drop 3: 4 5 6 7 + drop 4: 5 6 7 + drop 5: 6 7 + drop 6: 7 + drop 7: + drop 890: + drop 100500: + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + views::drop sometimes fails to the construction is adjusted + LWG 3407 C++20 construct a sized random so that it is always valid + access range + LWG 3494 C++20 drop_view was never a it is a borrowed_range if its + borrowed_range underlying view is + +.SH See also + + ranges::drop_while_view a view consisting of the elements of another view, skipping + views::drop_while the initial subsequence of elements until the first element + (C++20) where the predicate returns false + \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::drop_while,std::ranges::drop_while_view.3 b/man/std::ranges::views::drop_while,std::ranges::drop_while_view.3 new file mode 100644 index 000000000..9c20fcd48 --- /dev/null +++ b/man/std::ranges::views::drop_while,std::ranges::drop_while_view.3 @@ -0,0 +1,174 @@ +.TH std::ranges::views::drop_while,std::ranges::drop_while_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::drop_while,std::ranges::drop_while_view \- std::ranges::views::drop_while,std::ranges::drop_while_view + +.SH Synopsis + Defined in header + template< ranges::view V, class Pred > + + requires ranges::input_range && + std::is_object_v && + std::indirect_unary_predicate> + class drop_while_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ drop_while = /* unspecified \fB(2)\fP \fI(since C++20)\fP + */; + + } + Call signature + template< ranges::viewable_range R, class Pred > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto drop_while( R&& r, Pred&& pred ); + template< class Pred > \fI(since C++20)\fP + constexpr /*range adaptor closure*/ drop_while( Pred&& pred ); + + 1) A range adaptor that represents view of elements from an underlying sequence, + beginning at the first element for which the predicate returns false. + 2) RangeAdaptorObject. The expression views::drop_while(e, f) is + expression-equivalent to drop_while_view(e, f) for any suitable subexpressions e and + f. + + drop_while_view models the concepts contiguous_range, random_access_range, + bidirectional_range, forward_range, input_range, and common_range when the + underlying view V models respective concepts. It also models sized_range if + ranges::forward_range and std::sized_sentinel_for, + ranges::iterator_t> are modeled. + +.SH Member functions + + constructor constructs a drop_while_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + pred returns a reference to the stored predicate + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + returns the number of elements in the derived view. Provided if it + size satisfies forward_range and its sentinel and iterator type satisfy + (C++20) sized_sentinel_for. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Helper templates + + template< class T, class Pred > + + inline constexpr bool enable_borrowed_range> = C++20) + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes drop_while_view + satisfy borrowed_range when the underlying view satisfies it. + +.SH Notes + + In order to provide the amortized constant time complexity required by the range + concept, the result of begin is cached within the drop_while_view object. If the + underlying range is modified after the first call to begin(), subsequent uses of the + drop_while_view object might have unintuitive behavior. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + using std::operator""sv; + + [[nodiscard]] + constexpr bool is_space(char q) noexcept + { + static constexpr auto ws = {' ', '\\t', '\\n', '\\v', '\\r', '\\f'}; + return std::ranges::any_of(ws, [q](auto p) { return p == q; }); + }; + + [[nodiscard]] + constexpr std::string trim_left(std::string_view const in) noexcept + { + auto view = in | std::views::drop_while(is_space); + return {view.begin(), view.end()}; + } + + [[nodiscard]] + constexpr std::string trim(std::string_view const in) + { + auto view = in + | std::views::drop_while(is_space) | std::views::reverse + | std::views::drop_while(is_space) | std::views::reverse + ; + return {view.begin(), view.end()}; + } + + int main() + { + static_assert(trim_left(" \\n C++23") == "C++23"sv); + constexpr std::string_view src = " \\f\\n\\t\\r\\vHello, C++20!\\f\\n\\t\\r\\v "; + + const auto s = trim(src); + std::cout << "s = " << std::quoted(s) << '\\n'; + + static constexpr auto v = {0, 1, 2, 3, 4, 5}; + for (int n : v | std::views::drop_while([](int i) { return i < 3; })) + std::cout << n << ' '; + std::cout << '\\n'; + } + +.SH Output: + + s = "Hello, C++20!" + 3 4 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3494 C++20 drop_while_view was never a it is a borrowed_range if its + borrowed_range underlying view is + +.SH See also + + ranges::drop_view a view consisting of elements of another view, skipping the first + views::drop N elements + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::elements,std::ranges::elements_view.3 b/man/std::ranges::views::elements,std::ranges::elements_view.3 new file mode 100644 index 000000000..627abdd30 --- /dev/null +++ b/man/std::ranges::views::elements,std::ranges::elements_view.3 @@ -0,0 +1,196 @@ +.TH std::ranges::views::elements,std::ranges::elements_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::elements,std::ranges::elements_view \- std::ranges::views::elements,std::ranges::elements_view + +.SH Synopsis + Defined in header + template< ranges::input_range V, std::size_t N > + + requires ranges::view && + has-tuple-element, + N> && + has-tuple-element>, N> && + + returnable-element, N> + + class elements_view : public + ranges::view_interface>; + namespace views { + + template< std::size_t N > (since + inline constexpr /* unspecified */ elements = /* \fB(2)\fP C++20) + unspecified */; + + } + Call signature + template< ranges::viewable_range R > + (since + requires /* see below */ C++20) + + constexpr ranges::view auto elements( R&& r ); + Helper concepts + template< class T, std::size_t N > + + concept has-tuple-element = + requires(T t) { + typename std::tuple_size::type; (until C++23) + requires N < std::tuple_size_v; (exposition + typename std::tuple_element_t; only*) + { std::get(t) } -> std::convertible_to< + const + std::tuple_element_t&>; + + }; \fB(3)\fP + template< class T, std::size_t N > + (since C++23) + concept has-tuple-element = (exposition + only*) + tuple-like && N < std::tuple_size_v + template< class T, std::size_t N > + + concept returnable-element = (exposition + std::is_reference_v || std::move_constructible< \fB(4)\fP only*) + + + std::tuple_element_t>; + + 1) Accepts a view of tuple-like values, and issues a view with a value type of the + N-th element of the adapted view's value-type. + 2) Every specialization of views::elements is a RangeAdaptorObject. The expression + views::elements(e) is expression-equivalent to + elements_view, M>{e} for any suitable subexpression e + and constant expression M. + 3) Ensures that the elements of the underlying view are tuple-like values + , see tuple-like + (since C++23). + 4) Ensures that dangling references cannot be returned. + + elements_view models the concepts random_access_range, bidirectional_range, + forward_range, input_range, common_range, and sized_range when the underlying view V + models respective concepts. + +.SH Member functions + + constructor constructs a elements_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++20) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Nested classes + + iterator the iterator type + (C++20) (exposition-only member class template*) + sentinel the sentinel type + (C++20) (exposition-only member class template*) + + Helper templates + + template + + inline constexpr bool \fI(since C++20)\fP + enable_borrowed_range> = + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes elements_view + satisfy borrowed_range when the underlying view satisfies it. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + const std::vector> vt + { + {1, 'A', "α"}, + {2, 'B', "β"}, + {3, 'C', "γ"}, + {4, 'D', "δ"}, + {5, 'E', "ε"}, + }; + + for (int const e : std::views::elements<0>(vt)) + std::cout << e << ' '; + std::cout << '\\n'; + + for (char const e : vt | std::views::elements<1>) + std::cout << e << ' '; + std::cout << '\\n'; + + for (std::string const& e : std::views::elements<2>(vt)) + std::cout << e << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 + A B C D E + α β γ δ ε + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3494 C++20 elements_view was never a it is a borrowed_range + borrowed_range if its underlying view is + LWG 3502 C++20 dangling reference could be obtained such usage is forbidden + from elements_view + +.SH See also + + ranges::keys_view takes a view consisting of pair-like values and produces + views::keys a view of the first elements of each pair + (C++20) \fI(class template)\fP (range adaptor object) + ranges::values_view takes a view consisting of pair-like values and produces + views::values a view of the second elements of each pair + (C++20) \fI(class template)\fP (range adaptor object) + ranges::zip_view a view consisting of tuples of references to + views::zip corresponding elements of the adapted views + (C++23) \fI(class template)\fP (customization point object) + ranges::zip_transform_view a view consisting of tuples of results of application of + views::zip_transform a transformation function to corresponding elements of + (C++23) the adapted views + \fI(class template)\fP (customization point object) + BLAS-like slice of a valarray: starting index, length, + slice stride + \fI(class)\fP diff --git a/man/std::ranges::views::empty,std::ranges::empty_view.3 b/man/std::ranges::views::empty,std::ranges::empty_view.3 new file mode 100644 index 000000000..ff45e1d30 --- /dev/null +++ b/man/std::ranges::views::empty,std::ranges::empty_view.3 @@ -0,0 +1,124 @@ +.TH std::ranges::views::empty,std::ranges::empty_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::empty,std::ranges::empty_view \- std::ranges::views::empty,std::ranges::empty_view + +.SH Synopsis + Defined in header + template + + requires std::is_object_v \fB(1)\fP \fI(since C++20)\fP + + class empty_view : public ranges::view_interface> + namespace views { + + template inline constexpr empty_view empty{}; \fB(2)\fP \fI(since C++20)\fP + + } + + 1) A range factory that produces a view of no elements of a particular type. + 2) Variable template for empty_view. + +.SH Member functions + + begin returns nullptr + \fB[static]\fP (C++20) \fI(public static member function)\fP + end returns nullptr + \fB[static]\fP (C++20) \fI(public static member function)\fP + data returns nullptr + \fB[static]\fP (C++20) \fI(public static member function)\fP + size returns 0 (zero) + \fB[static]\fP (C++20) \fI(public static member function)\fP + empty returns true + \fB[static]\fP (C++20) \fI(public static member function)\fP + Inherited from std::ranges::view_interface + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it + (C++20) satisfies bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it + (C++20) satisfies random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::empty_view::begin + + static constexpr T* begin() noexcept { return nullptr; } \fI(since C++20)\fP + + empty_view does not reference any element. + +std::ranges::empty_view::end + + static constexpr T* end() noexcept { return nullptr; } \fI(since C++20)\fP + + empty_view does not reference any element. + +std::ranges::empty_view::data + + static constexpr T* data() noexcept { return nullptr; } \fI(since C++20)\fP + + empty_view does not reference any element. + +std::ranges::empty_view::size + + static constexpr std::size_t size() noexcept { return 0; } \fI(since C++20)\fP + + empty_view is always empty. + +std::ranges::empty_view::empty + + static constexpr bool empty() noexcept { return true; } \fI(since C++20)\fP + + empty_view is always empty. + + Helper templates + + template + inline constexpr bool enable_borrowed_range> = \fI(since C++20)\fP + true; + + This specialization of std::ranges::enable_borrowed_range makes empty_view satisfy + borrowed_range. + +.SH Notes + + Although empty_view obtains front, back, and operator[] member functions from + view_interface, calls to them always result in undefined behavior since an + empty_view is always empty. + + The inherited operator bool conversion function always returns false. + +.SH Example + + +// Run this code + + #include + + int main() + { + std::ranges::empty_view e; + static_assert(std::ranges::empty(e)); + static_assert(0 == e.size()); + static_assert(nullptr == e.data()); + static_assert(nullptr == e.begin()); + static_assert(nullptr == e.end()); + } + +.SH See also + + ranges::single_view a view that contains a single element of a specified value + views::single \fI(class template)\fP (customization point object) + (C++20) + views::all_t a view that includes all elements of a range + views::all (alias template) (range adaptor object) + (C++20) + ranges::ref_view a view of the elements of some other range + (C++20) \fI(class template)\fP diff --git a/man/std::ranges::views::enumerate,std::ranges::enumerate_view.3 b/man/std::ranges::views::enumerate,std::ranges::enumerate_view.3 new file mode 100644 index 000000000..284357ebb --- /dev/null +++ b/man/std::ranges::views::enumerate,std::ranges::enumerate_view.3 @@ -0,0 +1,170 @@ +.TH std::ranges::views::enumerate,std::ranges::enumerate_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::enumerate,std::ranges::enumerate_view \- std::ranges::views::enumerate,std::ranges::enumerate_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + requires /*range-with-movable-references*/ \fB(1)\fP (since C++23) + class enumerate_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ enumerate = /* unspecified \fB(2)\fP (since C++23) + */; + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ (since C++23) + + constexpr /* see below */ enumerate( R&& r ); + Helper concepts + template< class R > + + concept /*range-with-movable-references*/ = + ranges::input_range && \fB(3)\fP (exposition + std::move_constructible> && only*) + + + std::move_constructible>; + + 1) enumerate_view is a range adaptor that takes a view and produces a view of + tuples. i^th element (the tuple) of the resulting sequence holds: + * the value equal to i, which is a zero-based index of the element of underlying + sequence, and + * the reference to the underlying element. + 2) The name views::enumerate denotes a RangeAdaptorObject. Given a subexpression e, + the expression views::enumerate(e) is expression-equivalent to + enumerate_view>(e) for any suitable subexpression e. + 3) Ensures that the reference type of the underlying type can be moved. + + enumerate_view models the concepts random_access_range, bidirectional_range, + forward_range, input_range, common_range, and sized_range when the underlying view V + models respective concepts. + +.SH Member functions + + constructor constructs a enumerate_view + (C++23) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type + (C++23) (exposition-only member class template*) + + Helper templates + + template< class View > + + constexpr bool enable_borrowed_range> = (since C++23) + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes enumerate_view + satisfy borrowed_range when the underlying view satisfies it. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_enumerate 202302L (C++23) std::ranges::enumerate_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr static auto v = {'A', 'B', 'C', 'D'}; + + for (auto const [index, letter] : std::views::enumerate(v)) + std::cout << '(' << index << ':' << letter << ") "; + std::cout << '\\n'; + + #if __cpp_lib_ranges_to_container + // create a map using the position of each element as key + auto m = v | std::views::enumerate | std::ranges::to(); + + for (auto const [key, value] : m) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << '\\n'; + #endif + + std::vector numbers{1, 3, 5, 7}; + + // num is mutable even with const, which does not propagate to reference + // to make it const, use `std::views::enumerate(numbers) | std::views::as_const` + // or `std::views::enumerate(std::as_const(numbers))` + for (auto const [index, num] : std::views::enumerate(numbers)) + { + ++num; // the type is int& + std::cout << numbers[index] << ' '; + } + std::cout << '\\n'; + } + +.SH Possible output: + + (0:A) (1:B) (2:C) (3:D) + [0]:A [1]:B [2]:C [3]:D + 2 4 6 8 + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.23 Enumerate view [range.enumerate] + +.SH See also + + ranges::iota_view a view consisting of a sequence generated by repeatedly + views::iota incrementing an initial value + (C++20) \fI(class template)\fP (customization point object) + ranges::zip_view a view consisting of tuples of references to corresponding + views::zip elements of the adapted views + (C++23) \fI(class template)\fP (customization point object) + ranges::elements_view takes a view consisting of tuple-like values and a number N + views::elements and produces a view of N^th element of each tuple + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::filter,std::ranges::filter_view.3 b/man/std::ranges::views::filter,std::ranges::filter_view.3 new file mode 100644 index 000000000..0f2e58069 --- /dev/null +++ b/man/std::ranges::views::filter,std::ranges::filter_view.3 @@ -0,0 +1,182 @@ +.TH std::ranges::views::filter,std::ranges::filter_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::filter,std::ranges::filter_view \- std::ranges::views::filter,std::ranges::filter_view + +.SH Synopsis + Defined in header + template< ranges::input_range V, + + std::indirect_unary_predicate> Pred + > \fB(1)\fP (since + requires ranges::view && std::is_object_v C++20) + class filter_view + + : public ranges::view_interface> + namespace views { + (since + inline constexpr /* unspecified */ filter = /* unspecified */; \fB(2)\fP C++20) + + } + Call signature + template< ranges::viewable_range R, class Pred > + (since + requires /* see below */ C++20) + + constexpr ranges::view auto filter( R&& r, Pred&& pred ); + template< class Pred > (since + constexpr /* range adaptor closure */ filter( Pred&& pred ); C++20) + + 1) A range adaptor that represents view of an underlying sequence without the + elements that fail to satisfy a predicate. + 2) RangeAdaptorObject. The expression views::filter(e, p) is expression-equivalent + to filter_view(e, p) for any suitable subexpressions e and p. + + filter_view models the concepts bidirectional_range, forward_range, input_range, and + common_range when the underlying view V models respective concepts. + +.SH Member functions + + constructor constructs a filter_view + (C++20) \fI(public member function)\fP + base returns the underlying view V + (C++20) \fI(public member function)\fP + pred returns a reference to the predicate stored within filter_view + (C++20) \fI(public member function)\fP + begin returns the beginning iterator of the filter_view + (C++20) \fI(public member function)\fP + end returns the sentinel of the filter_view + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::filter_view::filter_view + + filter_view() requires std::default_initializable && \fB(1)\fP \fI(since C++20)\fP + std::default_initializable = default; + constexpr explicit filter_view( V base, Pred pred ); \fB(2)\fP \fI(since C++20)\fP + + 1) Value-initializes base_ via its default member initializer (= V()) and + default-initializes pred_ (which value-initializes the contained Pred). + 2) Initializes base_ with std::move(base) and initializes pred_ with + std::move(pred). + +.SH Parameters + + base - range to filter + pred - predicate to filter out elements + +std::ranges::filter_view::base + + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + 1) Equivalent to return base_;. + 2) Equivalent to return std::move(base_);. + +std::ranges::filter_view::pred + + constexpr const Pred& pred() const; \fI(since C++20)\fP + + Returns a reference to the contained Pred object. The behavior is undefined if pred_ + does not contain a value. + +std::ranges::filter_view::begin + + constexpr /* iterator */ begin(); (exposition only*) + + In order to provide the amortized constant time complexity required by the range + concept, this function caches the result within the filter_view object for use on + subsequent calls. Equivalent to + + if constexpr (!ranges::forward_range) + return /* iterator */{*this, ranges::find_if(base_, std::ref(*pred_))}; + else + { + if (!begin_.has_value()) + begin_ = ranges::find_if(base_, std::ref(*pred_)); // caching + return /* iterator */{*this, begin_.value())}; + } + + The behavior is undefined if pred_ does not contain a value. + +std::ranges::filter_view::end + + constexpr auto end(); \fI(since C++20)\fP + + Returns an iterator to the end. Equivalent to + + if constexpr (ranges::common_range) + return /* iterator */{*this, ranges::end(base_)}; + else + return /* sentinel */{*this}; + + Deduction guides + + template< class R, class Pred > \fI(since C++20)\fP + filter_view( R&&, Pred ) -> filter_view, Pred>; + + Nested classes + + iterator the iterator type of filter_view + (C++20) (exposition-only member class*) + sentinel the sentinel type of filter_view when the underlying view is not a + (C++20) common_range + (exposition-only member class*) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto even = [](int i) { return 0 == i % 2; }; + auto square = [](int i) { return i * i; }; + + for (int i : std::views::iota(0, 6) + | std::views::filter(even) + | std::views::transform(square)) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 0 4 16 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3714 C++20 the multi-parameter constructor was made explicit + (P2711R1) not explicit + if Pred is not default_initializable, + P2325R3 C++20 the default constructor the filter_view is also + constructs a filter_view which does not default_initializable + not contain a Pred + +.SH See also + + ranges::take_while_view a view consisting of the initial elements of another view, + views::take_while until the first element on which a predicate returns false + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::iota,std::ranges::iota_view.3 b/man/std::ranges::views::iota,std::ranges::iota_view.3 new file mode 100644 index 000000000..16160a20f --- /dev/null +++ b/man/std::ranges::views::iota,std::ranges::iota_view.3 @@ -0,0 +1,270 @@ +.TH std::ranges::views::iota,std::ranges::iota_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::iota,std::ranges::iota_view \- std::ranges::views::iota,std::ranges::iota_view + +.SH Synopsis + Defined in header + template< std::weakly_incrementable W, + + std::semiregular Bound = std::unreachable_sentinel_t > + requires __WeaklyEqualityComparableWith && \fB(1)\fP \fI(since C++20)\fP + std::copyable + class iota_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ iota = /* unspecified */; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< class W > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ iota( W&& value ); + template< class W, class Bound > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /* see below */ iota( W&& value, Bound&& bound ); + + 1) A range factory that generates a sequence of elements by repeatedly incrementing + an initial value. Can be either bounded or unbounded (infinite). + 2) views::iota(e) and views::iota(e, f) are expression-equivalent to iota_view(e) + and iota_view(e, f) respectively for any suitable subexpressions e and f. + +.SH Member functions + + constructor creates an iota_view + (C++20) \fI(public member function)\fP + begin obtains the beginning iterator of an iota_view + (C++20) \fI(public member function)\fP + end obtains the sentinel denoting the end of an iota_view + (C++20) \fI(public member function)\fP + empty tests whether the iota_view is empty, i.e. the iterator and the + (C++20) sentinel compare equal + \fI(public member function)\fP + size obtains the size of an iota_view if it is sized + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::iota_view::iota_view + + iota_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr explicit iota_view( W value ); \fB(2)\fP \fI(since C++20)\fP + constexpr explicit iota_view( std::type_identity_t value, \fB(3)\fP \fI(since C++20)\fP + std::type_identity_t bound ); + constexpr explicit iota_view( /* iterator */ first, /* see below \fB(4)\fP \fI(since C++20)\fP + */ last ); + + 1) Value-initializes value_ and bound_ via their default member initializers (= W() + and = Bound()). + 2) Initializes value_ with value and value-initializes bound_. This constructor is + used to create unbounded iota_views, e.g. iota\fB(0)\fP yields numbers 0,1,2..., + infinitely. + 3) Initializes value_ with value and bound_ with bound. The behavior is undefined if + std::totally_ordered_with is modeled and bool(value <= bound) is false. + This constructor is used to create bounded iota views, e.g. iota(10, 20) yields + numbers from 10 to 19. + 4) Same as \fB(3)\fP, except that value_ is initialized with the W value stored in first, + and + * if W and Bound are the same type, then the type of last is /* iterator */ and + bound_ initialized with the W value stored in last, + * otherwise, if the iota_view is unbounded (i.e. Bound is + std::unreachable_sentinel_t), then the type of last is + std::unreachable_sentinel_t and bound_ initialized with + std::unreachable_sentinel. + * otherwise, the type of last is /* sentinel */ and bound_ initialized with the + Bound value stored in last. + In any case, the type of last is same as decltype(end()). + + For \fB(2)\fP, \fB(3)\fP, and \fB(4)\fP, the behavior is undefined if the iota_view is bounded (i.e. + Bound is not std::unreachable_sentinel_t) and bound_ is initialized to a value + unreachable from value_. + +.SH Parameters + + value - the starting value + bound - the bound + first - the iterator denoting the starting value + last - the iterator or sentinel denoting the bound + +std::ranges::iota_view::begin + + constexpr /* iterator */ begin() const; \fI(since C++20)\fP + + Returns an iterator initialized with value_. + +std::ranges::iota_view::end + + constexpr auto end() const; \fB(1)\fP \fI(since C++20)\fP + constexpr /* iterator */ end() const requires std::same_as; + + 1) Returns a sentinel of a specific type (shown as /* sentinel */ here) initialized + with bound_ if this view is bounded, or std::unreachable_sentinel if this view is + unbounded. + 2) Returns an iterator initialized with bound_. + +std::ranges::iota_view::empty + + constexpr bool empty() const; \fI(since C++20)\fP + + Equivalent to return value_ == bound_;. + +std::ranges::iota_view::size + + constexpr auto size() const + + requires (std::same_as && /* advanceable */) + || (/* is-integer-like */ && /* is-integer-like */) + || std::sized_sentinel_for + { + if constexpr (/* is-integer-like */ && /* is-integer-like + */) + return (value_ < 0) + ? ((bound_ < 0) \fI(since C++20)\fP + ? /* to-unsigned-like */(-value_) + - /* to-unsigned-like */(-bound_) + : /* to-unsigned-like */(bound_) + + /* to-unsigned-like */(-value_)) + : /* to-unsigned-like */(bound_) - /* to-unsigned-like + */(value_); + else + return /* to-unsigned-like */(bound_ - value_); + + } + + Returns the size of the view if the view is bounded. + + The exposition-only concept advanceable is described in this page. + + The exposition-only function template to-unsigned-like converts its argument (which + must be integer-like) to the corresponding unsigned version of the argument type. + + Deduction guides + + template< class W, class Bound > + + requires (!/* is-integer-like */ + || !/* is-integer-like */ \fI(since C++20)\fP + || /* is-signed-integer-like */ + == /* is-signed-integer-like */) + + iota_view( W, Bound ) -> iota_view; + + For any type T, /* is-integer-like */ is true if and only if T is integer-like, + and /* is-signed-integer-like */ is true if and only if T is integer-like and + capable of representing negative values. + + Note that the guide protects itself against signed/unsigned mismatch bugs, like + views::iota(0, v.size()), where 0 is a (signed) int and v.size() is an (unsigned) + std::size_t. + + Nested classes + + iterator the iterator type + (C++20) (exposition-only member class*) + sentinel the sentinel type used when the iota_view is bounded and Bound and W are + (C++20) not the same type + (exposition-only member class*) + + Helper templates + + template< std::weakly_incrementable W, std::semiregular Bound > + inline constexpr bool enable_borrowed_range> = true; + + This specialization of std::ranges::enable_borrowed_range makes iota_view satisfy + borrowed_range. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Bound + { + int bound; + bool operator==(int x) const { return x == bound; } + }; + + int main() + { + for (int i : std::ranges::iota_view{1, 10}) + std::cout << i << ' '; + std::cout << '\\n'; + + for (int i : std::views::iota(1, 10)) + std::cout << i << ' '; + std::cout << '\\n'; + + for (int i : std::views::iota(1, Bound{10})) + std::cout << i << ' '; + std::cout << '\\n'; + + for (int i : std::views::iota(1) | std::views::take(9)) + std::cout << i << ' '; + std::cout << '\\n'; + + std::ranges::for_each(std::views::iota(1, 10), [](int i) + { + std::cout << i << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3523 C++20 iterator-sentinel pair constructor might corrected + use wrong sentinel type + LWG 3610 C++20 size might reject integer-class types accept if possible + LWG 4001 C++20 the inherited member empty function was not empty is always + always valid provided + P2325R3 C++20 iota_view required that W is semiregular only requires that W + as view required default_initializable is copyable + P2711R1 C++20 the multi-parameter constructors were not made explicit + explicit + +.SH See also + + iota fills a range with successive increments of the starting value + \fI(C++11)\fP \fI(function template)\fP + ranges::iota fills a range with successive increments of the starting value + (C++23) (niebloid) + ranges::repeat_view a view consisting of a generated sequence by repeatedly + views::repeat producing the same value + (C++23) \fI(class template)\fP (customization point object) diff --git a/man/std::ranges::views::istream,std::ranges::basic_istream_view,std::ranges::istream_view,.3 b/man/std::ranges::views::istream,std::ranges::basic_istream_view,std::ranges::istream_view,.3 new file mode 100644 index 000000000..3b2bca1a5 --- /dev/null +++ b/man/std::ranges::views::istream,std::ranges::basic_istream_view,std::ranges::istream_view,.3 @@ -0,0 +1,143 @@ +.TH std::ranges::views::istream,std::ranges::basic_istream_view,std::ranges::istream_view, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::istream,std::ranges::basic_istream_view,std::ranges::istream_view, \- std::ranges::views::istream,std::ranges::basic_istream_view,std::ranges::istream_view, + +.SH Synopsis + + Defined in header + template< std::movable Val, class CharT, class Traits = + std::char_traits > + + requires std::default_initializable && + /*stream-extractable*/ \fB(1)\fP \fI(since C++20)\fP + class basic_istream_view + + : public + ranges::view_interface> + Helper templates + template< class Val > \fB(2)\fP \fI(since C++20)\fP + using istream_view = ranges::basic_istream_view; + template< class Val > \fB(3)\fP \fI(since C++20)\fP + using wistream_view = ranges::basic_istream_view; + Customization point objects + namespace views { + + template< class T > \fB(4)\fP \fI(since C++20)\fP + inline constexpr /*unspecified*/ istream = /*unspecified*/; + + } + Helper concepts + template< class Val, class CharT, class Traits > + + concept /*stream-extractable*/ = (exposition + requires(std::basic_istream& is, Val& t) { \fB(5)\fP only*) + is >> t; + + }; + + 1) A range factory that generates a sequence of elements by repeatedly calling + operator>>. + 2,3) Convenience alias templates for character types char and wchar_t. + 4) views::istream(e) is expression-equivalent to (has the same effect as) + ranges::basic_istream_view(e) for + any suitable subexpressions e, where U is std::remove_reference_t. The + program is ill-formed if U is not both publicly and unambiguously derived from + std::basic_istream, which may result + in a substitution failure. + 5) The exposition-only concept /*stream-extractable*/ is satisfied + when lvalue of Val can be extracted from lvalue of std::basic_istream. + + The iterator type of basic_istream_view is move-only: it does not meet the + LegacyIterator requirements, and thus does not work with pre-C++20 algorithms. + +.SH Member functions + + constructor constructs a basic_istream_view + \fI(public member function)\fP + begin returns an iterator + \fI(public member function)\fP + end returns std::default_sentinel + \fI(public member function)\fP + Inherited from std::ranges::view_interface + although basic_istream_view is derived from + \fI(none)\fP std::ranges::view_interface, it cannot use any of inherited member + functions. + +std::ranges::basic_istream_view::basic_istream_view + + constexpr explicit \fI(since C++20)\fP + basic_istream_view( std::basic_istream& stream ); + + Initializes the stored pointer to stream with std::addressof(stream), and + value-initializes the stored value of Val. + +std::ranges::basic_istream_view::begin + + constexpr auto begin(); \fI(since C++20)\fP + + Equivalent to *stream_ >> value_; return /*iterator*/{*this};, where stream_ is the + stored pointer to stream and value_ is the stored value of Val. + +std::ranges::basic_istream_view::end + + constexpr std::default_sentinel_t end() const noexcept; \fI(since C++20)\fP + + Equivalent to return std::default_sentinel;. + + Nested classes + + iterator the iterator type of basic_istream_view + (C++20) (exposition-only member class*) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + auto words = std::istringstream{"today is yesterday’s tomorrow"}; + for (const auto& s : std::views::istream(words)) + std::cout << std::quoted(s, '/') << ' '; + std::cout << '\\n'; + + auto floats = std::istringstream{"1.1 2.2\\t3.3\\v4.4\\f55\\n66\\r7.7 8.8"}; + std::ranges::copy( + std::views::istream(floats), + std::ostream_iterator{std::cout, ", "} + ); + std::cout << '\\n'; + } + +.SH Output: + + /today/ /is/ /yesterday’s/ /tomorrow/ + 1.1, 2.2, 3.3, 4.4, 55, 66, 7.7, 8.8, + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + default constructor was provided as removed along with the + P2325R3 C++20 view requirement + must be default_initializable + LWG 3568 C++20 P2325R3 accidentally made the stored restored to + value default-initialized value-initialization + ranges::istream_view was a function made an alias template; + P2432R1 C++20 template and customization point objects + did not follow the naming convention added + +.SH See also + + istream_iterator input iterator that reads from std::basic_istream + \fI(class template)\fP diff --git a/man/std::ranges::views::join,std::ranges::join_view.3 b/man/std::ranges::views::join,std::ranges::join_view.3 new file mode 100644 index 000000000..b4f7f1cf7 --- /dev/null +++ b/man/std::ranges::views::join,std::ranges::join_view.3 @@ -0,0 +1,148 @@ +.TH std::ranges::views::join,std::ranges::join_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::join,std::ranges::join_view \- std::ranges::views::join,std::ranges::join_view + +.SH Synopsis + Defined in header + template< ranges::input_range V > + + requires ranges::view and + ranges::input_range> \fB(1)\fP \fI(since C++20)\fP + class join_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ join = /* unspecified */; \fB(2)\fP \fI(since C++20)\fP + + } + + 1) A range adaptor that represents view consisting of the sequence obtained from + flattening a view of ranges. + 2) RangeAdaptorObject (and also RangeAdaptorClosureObject). The expression + views::join(e) is expression-equivalent to join_view>{e} + for any suitable subexpressions e. + + join_view models input_range. + + join_view models forward_range when: + + * ranges::range_reference_t is a reference type, and + * V and ranges::range_reference_t each model forward_range. + + join_view models bidirectional_range when: + + * ranges::range_reference_t is a reference type, + * V models bidirectional_range, and + * ranges::range_reference_t models both bidirectional_range and common_range. + + join_view models common_range when: + + * ranges::range_reference_t is a reference type, and + * V and ranges::range_reference_t each model forward_range and common_range. + +.SH Member functions + + constructor constructs a join_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++20) (exposition-only member class template*) + sentinel the sentinel type + (C++20) (exposition-only member class template*) + +.SH Notes + + Before P2328R1 was adopted, the inner range type (ranges::range_reference_t) + cannot be a container type (but can be reference to container). For example, it was + not allowed to join a transform_view of std::string prvalue. + + struct Person { int age; std::string name; }; + + auto f(std::vector& v) { + // return v | std::views::transform([](auto& p){ return p.name; }) + // | std::views::join; // error before P2328R1 + return v | std::views::transform([](auto& p) -> std::string& { return p.name; }) + | std::views::join; // OK + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto bits = {"https:"sv, "//"sv, "cppreference"sv, "."sv, "com"sv}; + for (char const c : bits | std::views::join) + std::cout << c; + std::cout << '\\n'; + + const std::vector> v{{1, 2}, {3, 4, 5}, {6}, {7, 8, 9}}; + auto jv = std::ranges::join_view(v); + for (int const e : jv) + std::cout << e << ' '; + std::cout << '\\n'; + } + +.SH Output: + + https://cppreference.com + 1 2 3 4 5 6 7 8 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3474 C++20 views::join(e) returned a copy of e when e is returns a nested + a join_view join_view + P2328R1 C++20 non-view range prvalues could not be joined by made joinable + join_view + +.SH See also + + ranges::join_with_view a view consisting of the sequence obtained from flattening a + views::join_with view of ranges, with the delimiter in between elements + (C++23) \fI(class template)\fP (range adaptor object) + ranges::split_view a view over the subranges obtained from splitting another + views::split view using a delimiter + (C++20) \fI(class template)\fP (range adaptor object) + ranges::lazy_split_view a view over the subranges obtained from splitting another + views::lazy_split view using a delimiter + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::join_with,std::ranges::join_with_view.3 b/man/std::ranges::views::join_with,std::ranges::join_with_view.3 new file mode 100644 index 000000000..425ddee4a --- /dev/null +++ b/man/std::ranges::views::join_with,std::ranges::join_with_view.3 @@ -0,0 +1,136 @@ +.TH std::ranges::views::join_with,std::ranges::join_with_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::join_with,std::ranges::join_with_view \- std::ranges::views::join_with,std::ranges::join_with_view + +.SH Synopsis + Defined in header + template< ranges::input_range V, ranges::forward_range Pattern > + + requires ranges::view and + ranges::input_range> and + ranges::view and \fB(1)\fP (since + /* ranges::range_reference_t and Pattern C++23) + have compatible elements (see below) */ + class join_with_view + + : ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ join_with = /* unspecified \fB(2)\fP (since + */; C++23) + + } + Call signature + template< ranges::viewable_range R, class Pattern > + (since + requires /* see below */ C++23) + + constexpr ranges::view auto join_with( R&& r, Pattern&& pattern ); + template< class Pattern > (since + constexpr /* range adaptor closure */ join_with( Pattern&& pattern C++23) + ); + + 1) A range adaptor that represents view consisting of the sequence obtained from + flattening a view of ranges, with every element of the delimiter inserted in between + elements of the view. The delimiter can be a single element or a view of elements. + 2) RangeAdaptorObject. The expression views::join_with(e, f) is + expression-equivalent to join_with_view(e, f) for any suitable subexpressions e and + f. + + ranges::range_reference_t and Pattern have compatible elements if all of the + following concepts are modeled: + + * std::common_with>, + ranges::range_value_t> + * std::common_reference_with>, + ranges::range_reference_t> + * std::common_reference_with>, + ranges::range_rvalue_reference_t> + + join_with_view models input_range. + + join_with_view models forward_range when: + + * ranges::range_reference_t is a reference, and + * V and ranges::range_reference_t each model forward_range. + + join_with_view models bidirectional_range when: + + * ranges::range_reference_t is a reference, + * V, ranges::range_reference_t, and Pattern each models bidirectional_range, + and + * ranges::range_reference_t and Pattern each model common_range. + + join_with_view models common_range when: + + * ranges::range_reference_t is a reference, and + * V and ranges::range_reference_t each model forward_range and common_range. + +.SH Member functions + + constructor constructs a join_with_view + (C++23) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type + (C++23) (exposition-only member class template*) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + std::vector v{"This"sv, "is"sv, "a"sv, "test."sv}; + auto joined = v | std::views::join_with(' '); + + for (auto c : joined) + std::cout << c; + std::cout << '\\n'; + } + +.SH Output: + + This is a test. + +.SH See also + + ranges::join_view a view consisting of the sequence obtained from flattening a view + views::join of ranges + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::keys,std::ranges::keys_view.3 b/man/std::ranges::views::keys,std::ranges::keys_view.3 new file mode 100644 index 000000000..7358896f7 --- /dev/null +++ b/man/std::ranges::views::keys,std::ranges::keys_view.3 @@ -0,0 +1,97 @@ +.TH std::ranges::views::keys,std::ranges::keys_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::keys,std::ranges::keys_view \- std::ranges::views::keys,std::ranges::keys_view + +.SH Synopsis + Defined in header + template< class R > \fB(1)\fP \fI(since C++20)\fP + using keys_view = ranges::elements_view; + namespace views { + + inline constexpr auto keys = ranges::elements<0>; \fB(2)\fP \fI(since C++20)\fP + + } + + Takes a view of tuple-like values (e.g. std::tuple or std::pair), and produces a + view with a value-type of the first element of the adapted view's value-type. + + 1) An alias for ranges::elements_view. + 2) RangeAdaptorObject (and also RangeAdaptorClosureObject). The expression + views::keys(e) is expression-equivalent to keys_view>{e} + for any suitable subexpression e. + +.SH Notes + + keys_view can be useful for extracting keys from associative containers, e.g. + + std::map map{{"one", 1}, {"two", 2}}; + + for (auto const& key : std::views::keys(map)) + std::cout << key << ' '; + // prints: one two + +.SH Example + + Displays values for each type of quark in particle physics. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + int main() + { + const std::vector> quark_mass_charge + { + // name, MeV/c², has positive electric-charge: + {"up", 2.3, true}, {"down", 4.8, false}, + {"charm", 1275, true}, {"strange", 95, false}, + {"top", 173'210, true}, {"bottom", 4'180, false}, + }; + + std::cout.imbue(std::locale("en_US.utf8")); + std::cout << "Quark name: │ "; + for (std::string const& name : std::views::keys(quark_mass_charge)) + std::cout << std::setw(9) << name << " │ "; + + std::cout << "\\n" "Mass MeV/c²: │ "; + for (const double mass : std::views::values(quark_mass_charge)) + std::cout << std::setw(9) << mass << " │ "; + + std::cout << "\\n" "E-charge: │ "; + for (const bool pos : std::views::elements<2>(quark_mass_charge)) + std::cout << std::setw(9) << (pos ? "+2/3" : "-1/3") << " │ "; + std::cout << '\\n'; + } + +.SH Output: + + Quark name: │ up │ down │ charm │ strange │ top │ bottom │ + Mass MeV/c²: │ 2.3 │ 4.8 │ 1,275 │ 95 │ 173,210 │ 4,180 │ + E-charge: │ +2/3 │ -1/3 │ +2/3 │ -1/3 │ +2/3 │ -1/3 │ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3563 C++20 keys_view is unable to participate in CTAD views::all_t removed + due to its use of views::all_t + +.SH See also + + ranges::values_view takes a view consisting of pair-like values and produces a + views::values view of the second elements of each pair + (C++20) \fI(class template)\fP (range adaptor object) + ranges::elements_view takes a view consisting of tuple-like values and a number N + views::elements and produces a view of N^th element of each tuple + (C++20) \fI(class template)\fP (range adaptor object) + slice BLAS-like slice of a valarray: starting index, length, stride + \fI(class)\fP diff --git a/man/std::ranges::views::lazy_split,std::ranges::lazy_split_view.3 b/man/std::ranges::views::lazy_split,std::ranges::lazy_split_view.3 new file mode 100644 index 000000000..37f7b65e1 --- /dev/null +++ b/man/std::ranges::views::lazy_split,std::ranges::lazy_split_view.3 @@ -0,0 +1,166 @@ +.TH std::ranges::views::lazy_split,std::ranges::lazy_split_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::lazy_split,std::ranges::lazy_split_view \- std::ranges::views::lazy_split,std::ranges::lazy_split_view + +.SH Synopsis + Defined in header + template< ranges::input_range V, ranges::forward_range Pattern > + + requires ranges::view && + ranges::view && + std::indirectly_comparable, + ranges::iterator_t, \fB(1)\fP \fI(since C++20)\fP + ranges::equal_to> && + (ranges::forward_range || /*tiny-range*/) + class lazy_split_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ lazy_split = /* \fB(2)\fP \fI(since C++20)\fP + unspecified */; + + } + Call signature + template< ranges::viewable_range R, class Pattern > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto lazy_split( R&& r, Pattern&& pattern + ); + template< class Pattern > + constexpr /* range adaptor closure */ lazy_split( Pattern&& \fI(since C++20)\fP + pattern ); + Helper concepts + template< class R > + + concept /*tiny-range*/ = (exposition + ranges::sized_range && \fB(3)\fP only*) + requires { /* is-statically-constexpr-sized */; } && + + (std::remove_reference_t::size() <= 1); + + 1) lazy_split_view takes a view and a delimiter, and splits the view into subranges + on the delimiter. + + Two major scenarios are supported: + + * The view is an input_range, the delimiter is a single element (wrapped in a + single_view). + * The view is a forward_range, the delimiter is a view of elements. + 2) A RangeAdaptorObject. The expression views::lazy_split(e, f) is + expression-equivalent to lazy_split_view(e, f). + 3) The exposition-only concept /*tiny-range*/ is satisfied if Pattern + satisfies sized_range, Pattern::size() is a constant expression and suitable as a + template non-type argument, and the value of Pattern::size() is less than or equal + to 1. Notably, empty_view and single_view satisfy this concept. + + lazy_split_view models the concepts forward_range and input_range when the + underlying view V models respective concepts, and models common_range when V models + both forward_range and common_range. + + The inner range (ranges::range_reference_t) models the concepts + forward_range and input_range when the underlying view V models respective concepts. + It does not model common_range, and cannot be used with algorithms that expect a + bidirectional_range or higher. + +.SH Member functions + + constructor constructs a lazy_split_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + + Nested classes + + outer_iterator the iterator type + (C++20) (exposition-only member class template*) + inner_iterator the iterator type of the inner range + (C++20) (exposition-only member class template*) + + Deduction guides + +.SH Notes + + The name lazy_split_view is introduced by the post-C++20 defect report P2210R2. It + has the same lazy mechanism as that of the old split_view before change. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + auto print = [](auto const& view) + { + // `view` is of std::views::lazy_split_view::__outer_iterator::value_type + + for (std::cout << "{ "; const auto element : view) + std::cout << element << ' '; + std::cout << "} "; + }; + + int main() + { + constexpr static auto source = {0, 1, 0, 2, 3, 0, 4, 5, 6, 0, 7, 8, 9}; + constexpr int delimiter{0}; + constexpr std::ranges::lazy_split_view outer_view{source, delimiter}; + std::cout << "splits[" << std::ranges::distance(outer_view) << "]: "; + for (auto const& inner_view: outer_view) + print(inner_view); + + constexpr std::string_view hello{"Hello C++ 20 !"}; + std::cout << "\\n" "substrings: "; + std::ranges::for_each(hello | std::views::lazy_split(' '), print); + + constexpr std::string_view text{"Hello-+-C++-+-20-+-!"}; + constexpr std::string_view delim{"-+-"}; + std::cout << "\\n" "substrings: "; + std::ranges::for_each(text | std::views::lazy_split(delim), print); + } + +.SH Output: + + splits[5]: { } { 1 } { 2 3 } { 4 5 6 } { 7 8 9 } + substrings: { H e l l o } { C + + } { 2 0 } { ! } + substrings: { H e l l o } { C + + } { 2 0 } { ! } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2210R2 C++20 the old split_view was too lazy to be moves its functionality to + easily used lazy_split_view + +.SH See also + + ranges::split_view a view over the subranges obtained from splitting another view + views::split using a delimiter + (C++20) \fI(class template)\fP (range adaptor object) + ranges::join_view a view consisting of the sequence obtained from flattening a view + views::join of ranges + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::repeat,std::ranges::repeat_view.3 b/man/std::ranges::views::repeat,std::ranges::repeat_view.3 new file mode 100644 index 000000000..8acbc0e4d --- /dev/null +++ b/man/std::ranges::views::repeat,std::ranges::repeat_view.3 @@ -0,0 +1,179 @@ +.TH std::ranges::views::repeat,std::ranges::repeat_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::repeat,std::ranges::repeat_view \- std::ranges::views::repeat,std::ranges::repeat_view + +.SH Synopsis + Defined in header + template< std::move_constructible W, + + std::semiregular Bound = std::unreachable_sentinel_t > + requires (std::is_object_v && std::same_as> && \fB(1)\fP (since C++23) + (/*is-integer-like*/ || + std::same_as)) + + class repeat_view : public ranges::view_interface> + namespace views { + + inline constexpr /*unspecified*/ repeat = /*unspecified*/; \fB(2)\fP (since C++23) + + } + Call signature + template< class W > + + requires /* see below */ (since C++23) + + constexpr /* see below */ repeat( W&& value ); + template< class W, class Bound > + + requires /* see below */ (since C++23) + + constexpr /* see below */ repeat( W&& value, Bound&& bound ); + + 1) A range factory that generates a sequence of elements by repeatedly producing the + same value. Can be either bounded or unbounded (infinite). + 2) views::repeat(e) and views::repeat(e, f) are expression-equivalent to (has the + same effect as) repeat_view(e) and repeat_view(e, f) respectively for any suitable + subexpressions e and f. + + repeat_view models random_access_range. If Bound is not std::unreachable_sentinel_t, + repeat_view also models sized_range and common_range. + +.SH Member functions + + constructor creates a repeat_view + \fI(public member function)\fP + begin obtains the beginning iterator of a repeat_view + \fI(public member function)\fP + end obtains the sentinel denoting the end of a repeat_view + \fI(public member function)\fP + size obtains the size of a repeat_view if it is sized + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::repeat_view::repeat_view + + repeat_view() requires std::default_initializable = default; \fB(1)\fP (since C++23) + constexpr explicit repeat_view( const W& value, Bound bound = \fB(2)\fP (since C++23) + Bound() ); + constexpr explicit repeat_view( W&& value, Bound bound = Bound() \fB(3)\fP (since C++23) + ); + template < class... WArgs, class... BoundArgs > + + requires std::constructible_from + && std::constructible_from + constexpr explicit repeat( std::piecewise_construct_t, \fB(4)\fP (since C++23) + std::tuple value_args, + + std::tuple bound_args = + std::tuple<>{} ); + + 1) Value-initializes value_ and bound_ via their default member initializers (= W() + and = Bound()). + 2) Initializes value_ with value and initializes bound_ with bound. The behavior is + undefined if Bound is not std::unreachable_sentinel_t and bool(bound >= 0) is false. + 3) Initializes value_ with std::move(value) and initializes bound_ with bound. The + behavior is undefined if Bound is not std::unreachable_sentinel_t and bool(bound >= + 0) is false. + 4) Initializes value_ and bound_ through piecewise construction. + +.SH Parameters + + value - the value to be repeatedly produced + bound - the bound + +std::ranges::repeat_view::begin + + constexpr /*iterator*/ begin() const; (since C++23) + + Returns an iterator initialized with std::addressof(*value_). + +std::ranges::repeat_view::end + + constexpr /*iterator*/ end() const \fB(1)\fP (since C++23) + requires (!std::same_as); + constexpr std::unreachable_sentinel_t end() const; \fB(2)\fP (since C++23) + + 1) Returns an iterator initialized with std::addressof(*value_) and bound_. + 2) Returns an std::unreachable_sentinel. + +std::ranges::repeat_view::size + + constexpr auto size() const (since C++23) + requires (!std::same_as); + + Returns the size of the view if the view is bounded. Equivalent to return + /*to-unsigned-like*/(bound_);. + + The exposition-only function template to-unsigned-like converts its argument (which + must be integer-like) to the corresponding unsigned version of the argument type. + + Deduction guides + + template< class W, class Bound > (since C++23) + repeat_view( W, Bound ) -> repeat_view; + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class*) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_repeat 202207L (C++23) std::ranges::repeat_view + +.SH Example + + +// Run this code + + #include + #include + #include + using namespace std::literals; + + int main() + { + // bounded overload + for (auto s : std::views::repeat("C++"sv, 3)) + std::cout << s << ' '; + std::cout << '\\n'; + + // unbounded overload + for (auto s : std::views::repeat("I know that you know that"sv) + | std::views::take(3)) + std::cout << s << ' '; + std::cout << "...\\n"; + } + +.SH Output: + + C++ C++ C++ + I know that you know that I know that you know that I know that you know that ... + +.SH See also + + ranges::iota_view a view consisting of a sequence generated by repeatedly + views::iota incrementing an initial value + (C++20) \fI(class template)\fP (customization point object) diff --git a/man/std::ranges::views::reverse,std::ranges::reverse_view.3 b/man/std::ranges::views::reverse,std::ranges::reverse_view.3 new file mode 100644 index 000000000..5d446fb2d --- /dev/null +++ b/man/std::ranges::views::reverse,std::ranges::reverse_view.3 @@ -0,0 +1,197 @@ +.TH std::ranges::views::reverse,std::ranges::reverse_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::reverse,std::ranges::reverse_view \- std::ranges::views::reverse,std::ranges::reverse_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + requires ranges::bidirectional_range \fB(1)\fP \fI(since C++20)\fP + class reverse_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ reverse = /* unspecified \fB(2)\fP \fI(since C++20)\fP + */; + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto reverse( R&& r ); + + 1) A range adaptor that represents a view of underlying view with reversed order. + 2) RangeAdaptorObject. The expression views::reverse(e) is expression-equivalent to + one of the following expressions, except that e is evaluated only once: + * e.base(), if the type of e is a (possibly cv-qualified) specialization of + reverse_view; + * otherwise, if the type of e is (possibly cv-qualified) + ranges::subrange, std::reverse_iterator, K> for some + iterator type I and value K of type ranges::subrange_kind: + + * ranges::subrange(e.end().base(), e.begin().base(), e.size()), if K is + ranges::subrange_kind::sized; + * otherwise ranges::subrange(e.end().base(), e.begin().base()); + * otherwise ranges::reverse_view{e}. + In other words, views::reverse unwraps reversed views if possible. + + A reverse_view always models bidirectional_range and common_range, and it models + borrowed_range, sized_range, or random_access_range if the underlying view type V + models the corresponding concept. + +.SH Member functions + + constructor constructs a reverse_view + (C++20) \fI(public member function)\fP + base returns the underlying view V + (C++20) \fI(public member function)\fP + begin returns the beginning iterator of the reverse_view + (C++20) \fI(public member function)\fP + end returns the end iterator of the reverse_view + (C++20) \fI(public member function)\fP + size returns the size of the view if it is bounded + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::reverse_view::reverse_view + + reverse_view() requires std::default_initializable = default; \fB(1)\fP \fI(since C++20)\fP + constexpr reverse_view( V r ); \fB(2)\fP \fI(since C++20)\fP + + 1) Value-initializes base_ via its default member initializer (= V()). + 2) Initializes base_ with std::move(r). + +.SH Parameters + + r - range to reverse + +std::ranges::reverse_view::base + + constexpr V base() const& requires std::copy_constructible; \fB(1)\fP \fI(since C++20)\fP + constexpr V base() &&; \fB(2)\fP \fI(since C++20)\fP + + Returns the underlying view. + + 1) Copy-constructs the result from the underlying view. Equivalent to return base_;. + 2) Move-constructs the result from the underlying view. Equivalent to return + std::move(base_);. + +std::ranges::reverse_view::begin + + constexpr std::reverse_iterator> begin(); \fB(1)\fP \fI(since C++20)\fP + constexpr std::reverse_iterator> begin() \fB(2)\fP \fI(since C++20)\fP + requires ranges::common_range; + constexpr auto begin() const requires ranges::common_range; + + 1) Returns std::make_reverse_iterator(ranges::next(ranges::begin(base_), + ranges::end(base_))). In order to provide the amortized constant time complexity + required by the range concept, this function caches the result within the cache + object for use on subsequent calls. + 2,3) Equivalent to return std::make_reverse_iterator(ranges::end(base_));. + +std::ranges::reverse_view::end + + constexpr std::reverse_iterator> end(); \fB(1)\fP \fI(since C++20)\fP + constexpr auto end() const requires ranges::common_range; \fB(2)\fP \fI(since C++20)\fP + + Equivalent to return std::make_reverse_iterator(ranges::begin(base_));. + +std::ranges::reverse_view::size + + constexpr auto size() requires ranges::sized_range; \fB(1)\fP \fI(since C++20)\fP + constexpr auto size() const requires ranges::sized_range; \fB(2)\fP \fI(since C++20)\fP + + Returns the size of the view if the view is bounded. + + 1,2) Equivalent to return ranges::size(base_);. + + Deduction guides + + template< class R > \fI(since C++20)\fP + reverse_view( R&& ) -> reverse_view>; + + Helper templates + + template< class T > + + inline constexpr bool \fI(since C++20)\fP + enable_borrowed_range> = + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes reverse_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + static constexpr auto il = {3, 1, 4, 1, 5, 9}; + + std::ranges::reverse_view rv{il}; + for (int i : rv) + std::cout << i << ' '; + std::cout << '\\n'; + + for (int i : il | std::views::reverse) + std::cout << i << ' '; + std::cout << '\\n'; + + // operator[] is inherited from std::view_interface + for (auto i{0U}; i != rv.size(); ++i) + std::cout << rv[i] << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 9 5 1 4 1 3 + 9 5 1 4 1 3 + 9 5 1 4 1 3 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3494 C++20 reverse_view was never a it is a borrowed_range if its + borrowed_range underlying view is + +.SH See also + + reverse_iterator iterator adaptor for reverse-order traversal + \fI(class template)\fP + ranges::reverse reverses the order of elements in a range + (C++20) (niebloid) + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) diff --git a/man/std::ranges::views::single,std::ranges::single_view.3 b/man/std::ranges::views::single,std::ranges::single_view.3 new file mode 100644 index 000000000..319e66acd --- /dev/null +++ b/man/std::ranges::views::single,std::ranges::single_view.3 @@ -0,0 +1,203 @@ +.TH std::ranges::views::single,std::ranges::single_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::single,std::ranges::single_view \- std::ranges::views::single,std::ranges::single_view + +.SH Synopsis + Defined in header + template< std::copy_constructible T > + + requires std::is_object_v \fI(since C++20)\fP + class single_view (until C++23) + + : public ranges::view_interface> + template< std::move_constructible T > + + requires std::is_object_v (since C++23) + class single_view + + : public ranges::view_interface> \fB(1)\fP + namespace views { + + inline constexpr /*unspecified*/ single = /*unspecified*/; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< class T > + + requires /* see below */ \fI(since C++20)\fP + + constexpr /*see below*/ single( T&& t ); + + 1) Produces a view that contains exactly one element of a specified value. + 2) The expression views::single(e) is expression-equivalent to + single_view>(e) for any suitable subexpression e. + + The lifetime of the element is bound to the parent single_view. Copying single_view + makes a copy of the element. + +.SH Member functions + + constructor constructs a single_view + (C++20) \fI(public member function)\fP + begin returns a pointer to the element + (C++20) \fI(public member function)\fP + end returns a pointer past the element + (C++20) \fI(public member function)\fP + size returns 1 (one) + \fB[static]\fP (C++20) \fI(public static member function)\fP + data returns a pointer to the element + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it + (C++20) satisfies bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it + (C++20) satisfies random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + +std::ranges::single_view::single_view + + single_view() requires std::default_initializable \fB(1)\fP \fI(since C++20)\fP + = default; + constexpr explicit single_view( const T& t ); \fI(since C++20)\fP + (until C++23) + constexpr explicit single_view( const T& t ) (since C++23) + requires std::copy_constructible; + constexpr explicit single_view( T&& t ); \fB(3)\fP \fI(since C++20)\fP + template< class... Args > \fB(2)\fP + + requires std::constructible_from \fB(4)\fP \fI(since C++20)\fP + + constexpr explicit single_view( std::in_place_t, + Args&&... args ); + + Constructs a single_view. + + 1) Default initializes value_, which value-initializes its contained value. + 2) Initializes value_ with t. + 3) Initializes value_ with std::move(t). + 4) Initializes value_ as if by value_{std::in_place, std::forward(args)...}. + +std::ranges::single_view::begin + + constexpr T* begin() noexcept; \fI(since C++20)\fP + constexpr const T* begin() const noexcept; + + Equivalent to return data();. + +std::ranges::single_view::end + + constexpr T* end() noexcept; \fI(since C++20)\fP + constexpr const T* end() const noexcept; + + Equivalent to return data() + 1;. + +std::ranges::single_view::size + + static constexpr std::size_t size() noexcept; \fI(since C++20)\fP + + Equivalent to return 1;. + + This is a static function. This makes single_view model /*tiny-range*/ as required + by split_view. + +std::ranges::single_view::data + + constexpr T* data() noexcept; \fI(since C++20)\fP + constexpr const T* data() const noexcept; + + Returns a pointer to the contained value of value_. The behavior is undefined if + value_ does not contains a value. + + Deduction guides + + template< class T > \fI(since C++20)\fP + single_view( T ) -> single_view; + +.SH Notes + + For a single_view, the inherited empty member function always returns false, and the + inherited operator bool conversion function always returns true. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::ranges::single_view sv1{3.1415}; // uses (const T&) constructor + static_assert(sv1); + static_assert(not sv1.empty()); + + std::cout << "1) *sv1.data(): " << *sv1.data() << '\\n' + << "2) *sv1.begin(): " << *sv1.begin() << '\\n' + << "3) sv1.size(): " << sv1.size() << '\\n' + << "4) distance: " << std::distance(sv1.begin(), sv1.end()) << '\\n'; + + std::string str{"C++20"}; + std::cout << "5) str = " << std::quoted(str) << '\\n'; + std::ranges::single_view sv2{std::move(str)}; // uses (T&&) constructor + std::cout << "6) *sv2.data(): " << std::quoted(*sv2.data()) << '\\n' + << "7) str = " << std::quoted(str) << '\\n'; + + std::ranges::single_view> + sv3{std::in_place, 42, 3.14, "😄"}; // uses (std::in_place_t, Args&&... args) + + std::cout << "8) sv3 holds a tuple: { " + << std::get<0>(sv3[0]) << ", " + << std::get<1>(sv3[0]) << ", " + << std::get<2>(sv3[0]) << " }\\n"; + } + +.SH Output: + + 1) *sv1.data(): 3.1415 + 2) *sv1.begin(): 3.1415 + 3) sv1.size(): 1 + 4) distance: 1 + 5) str = "C++20" + 6) *sv2.data(): "C++20" + 7) str = "" + 8) sv3 holds a tuple: { 42, 3.14, 😄 } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3428 C++20 single_view was convertible from the constructor is made + std::in_place_t explicit + deduction guides for single_view + P2367R0 C++20 failed to decay the argument; a decaying guide provided; + views::single copied but not wrapped made always wrapping + a single_view + +.SH See also + + ranges::empty_view an empty view with no elements + views::empty \fI(class template)\fP (variable template) + (C++20) + ranges::split_view a view over the subranges obtained from splitting another view + views::split using a delimiter + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::slide,std::ranges::slide_view.3 b/man/std::ranges::views::slide,std::ranges::slide_view.3 new file mode 100644 index 000000000..ffd825f3b --- /dev/null +++ b/man/std::ranges::views::slide,std::ranges::slide_view.3 @@ -0,0 +1,183 @@ +.TH std::ranges::views::slide,std::ranges::slide_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::slide,std::ranges::slide_view \- std::ranges::views::slide,std::ranges::slide_view + +.SH Synopsis + Defined in header + template< ranges::forward_range V > + + requires ranges::view \fB(1)\fP (since C++23) + class slide_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ slide = /* unspecified \fB(2)\fP (since C++23) + */; + + } + Call signature + template< ranges::viewable_range R > + constexpr ranges::view auto slide( R&& r, (since C++23) + ranges::range_difference_t n ); + template< class DifferenceType > + constexpr /* range adaptor object */ slide( DifferenceType&& (since C++23) + n ); + Helper concepts + template< class V > + + concept __slide_caches_nothing = \fB(3)\fP (exposition only*) + + ranges::random_access_range && ranges::sized_range; + template< class V > + + concept __slide_caches_last = + !__slide_caches_nothing && \fB(4)\fP (exposition only*) + + ranges::bidirectional_range && + ranges::common_range; + template< class V > + + concept __slide_caches_first = \fB(5)\fP (exposition only*) + + !__slide_caches_nothing && !__slide_caches_last; + + 1) slide_view is a range adaptor that takes a view and a number n and produces a + view whose m ^th element (a "window") is a view over the m ^th through (m + n - + 1) ^th elements of the original view. + Let s be the size of the original view. Then the size of produced view is: + * s - n + 1, if s >= n, + * 0 otherwise, and the resulting view is empty. + 2) The name views::slide denotes a RangeAdaptorObject. Given subexpressions e and n, + the expression views::slide(e, n) is expression-equivalent to slide_view(e, n). + + If n is not greater than 0, the behavior is undefined. + + slide_view always models forward_range, and models bidirectional_range, + random_access_range, or sized_range if adapted view type models the corresponding + concept. + +.SH Member functions + + constructor constructs a slide_view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type used when slide_view is not a common_range + (C++23) (exposition-only member class template*) + + Helper templates + + template< class V > + + inline constexpr bool ranges::enable_borrowed_range> = (since C++23) + + ranges::enable_borrowed_range; + + This specialization of ranges::enable_borrowed_range makes slide_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Notes + + There are similarities between ranges::adjacent_view and ranges::slide_view: + + * Both create a "sliding window" of size N. + * Both have the same size S - N + 1, where S is the size of an adapted view such + that S >= N > 0. + + The differences between these adapters are: + + View adaptor value_type The window size N + ranges::adjacent_view A std::tuple object A template parameter + ranges::slide_view A range A runtime parameter + + Feature-test macro Value Std Feature + __cpp_lib_ranges_slide 202202L (C++23) std::ranges::slide_view + +.SH Example + + +// Run this code + + #include + #include + #include + + auto print_subrange = [](std::ranges::viewable_range auto&& r) + { + std::cout << '['; + for (char space[]{0,0}; auto elem : r) + std::cout << space << elem, *space = ' '; + std::cout << "] "; + }; + + int main() + { + const auto v = {1, 2, 3, 4, 5, 6}; + + std::cout << "All sliding windows of width:\\n"; + for (const unsigned width : std::views::iota(1U, 1U + v.size())) + { + auto const windows = v | std::views::slide(width); + std::cout << "W = " << width << ": "; + std::ranges::for_each(windows, print_subrange); + std::cout << '\\n'; + } + } + +.SH Output: + + All sliding windows of width W: + W = 1: [1] [2] [3] [4] [5] [6] + W = 2: [1 2] [2 3] [3 4] [4 5] [5 6] + W = 3: [1 2 3] [2 3 4] [3 4 5] [4 5 6] + W = 4: [1 2 3 4] [2 3 4 5] [3 4 5 6] + W = 5: [1 2 3 4 5] [2 3 4 5 6] + W = 6: [1 2 3 4 5 6] + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.29 Slide view [range.slide] + +.SH See also + + ranges::adjacent_view a view consisting of tuples of references to adjacent elements + views::adjacent of the adapted view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::chunk_view a range of views that are N-sized non-overlapping successive + views::chunk chunks of the elements of another view + (C++23) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::split,std::ranges::split_view.3 b/man/std::ranges::views::split,std::ranges::split_view.3 new file mode 100644 index 000000000..10af0423c --- /dev/null +++ b/man/std::ranges::views::split,std::ranges::split_view.3 @@ -0,0 +1,136 @@ +.TH std::ranges::views::split,std::ranges::split_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::split,std::ranges::split_view \- std::ranges::views::split,std::ranges::split_view + +.SH Synopsis + Defined in header + template< ranges::forward_range V, ranges::forward_range Pattern > + + requires ranges::view && + ranges::view && + std::indirectly_comparable, \fB(1)\fP \fI(since C++20)\fP + ranges::iterator_t, + ranges::equal_to> + class split_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ split = /* unspecified */; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< ranges::viewable_range R, class Pattern > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto split( R&& r, Pattern&& pattern ); + template< class Pattern > \fI(since C++20)\fP + constexpr /* range adaptor closure */ split( Pattern&& pattern ); + + 1) split_view takes a view and a delimiter, and splits the view into subranges on + the delimiter. + 2) RangeAdaptorObject. The expression views::split(e, p) is expression-equivalent to + split_view(e, p) for any suitable subexpressions e and p. + + split_view models the concepts forward_range, and common_range when the underlying + view V models respective concepts. + + The inner range (ranges::range_reference_t) is a + ranges::subrange>, which models common_range, models + sized_range when ranges::iterator_t models + std::sized_sentinel_for>, and models contiguous_range, + random_access_range, bidirectional_range, and forward_range when V models respective + concepts. + +.SH Member functions + + constructor constructs a split_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + find_next searches for the next occurrence of the pattern + (C++20) (exposition-only member function*) + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + + Nested classes + + iterator the iterator type + (C++20) (exposition-only member class*) + sentinel the sentinel type + (C++20) (exposition-only member class*) + + Deduction guides + +.SH Notes + + Before P2210R2, split_view used a lazy mechanism for splitting, and thus could not + keep the bidirectional, random access, or contiguous properties of the underlying + view, or make the iterator type of the inner range same as that of the underlying + view. Consequently, it is redesigned by P2210R2, and the lazy mechanism is moved to + lazy_split_view. + + The delimiter pattern generally should not be an ordinary string literal, as it will + consider the null terminator to be necessary part of the delimiter; therefore, it is + advisable to use a std::string_view literal instead. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using std::operator""sv; + constexpr auto words{"Hello^_^C++^_^20^_^!"sv}; + constexpr auto delim{"^_^"sv}; + + for (const auto word : std::views::split(words, delim)) + // with string_view's C++23 range constructor: + std::cout << std::quoted(std::string_view(word)) << ' '; + std::cout << '\\n'; + } + +.SH Output: + + "Hello" "C++" "20" "!" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2210R2 C++20 the old split_view was too lazy to be easily it is redesigned + used + +.SH See also + + ranges::lazy_split_view a view over the subranges obtained from splitting another + views::lazy_split view using a delimiter + (C++20) \fI(class template)\fP (range adaptor object) + ranges::join_view a view consisting of the sequence obtained from flattening a + views::join view of ranges + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::stride,std::ranges::stride_view.3 b/man/std::ranges::views::stride,std::ranges::stride_view.3 new file mode 100644 index 000000000..654ebc01f --- /dev/null +++ b/man/std::ranges::views::stride,std::ranges::stride_view.3 @@ -0,0 +1,158 @@ +.TH std::ranges::views::stride,std::ranges::stride_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::stride,std::ranges::stride_view \- std::ranges::views::stride,std::ranges::stride_view + +.SH Synopsis + Defined in header + template< ranges::input_range V > + + requires ranges::view \fB(1)\fP (since C++23) + class stride_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ stride = /* unspecified */; \fB(2)\fP (since C++23) + + } + Call signature + template< ranges::viewable_range R > + constexpr ranges::view auto stride( R&& r, (since C++23) + ranges::range_difference_t n ); + template< class DifferenceType > (since C++23) + constexpr /*range adaptor closure*/ stride( DifferenceType&& n ); + Helper templates + + 1) stride_view is a range adaptor that takes a view and a number n and produces a + view, that consists of elements of the original view by advancing over n elements at + a time. This means that each m^th element of the produced view is (n * i)^th element + of the original view, for some non-negative index i. The elements of the original + view, whose "index" is not a multiple of n, are not present in the produced view. + Let S be the size of the original view. Then the size of produced view is: + * (S / n) + (S % n ? 1 : 0), if S >= n; otherwise, + * 1, if S > 0; otherwise, + * 0, and the resulting view is empty. + 2) The name views::stride denotes a RangeAdaptorObject. Given subexpressions e and + n, the expression views::stride(e, n) is expression-equivalent to stride_view(e, n). + The n must be greater than 0, otherwise the behavior is undefined. + + stride_view always models input_range, and models forward_range, + bidirectional_range, random_access_range, and/or sized_range, if adapted view type V + models the corresponding concept. stride_view models common_range whenever the + underlying view V does. + +.SH Member functions + + constructor constructs a stride_view + (C++23) \fI(public member function)\fP + stride returns the stored stride value + (C++23) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + + Helper templates + + template< class V > + + inline constexpr bool ranges::enable_borrowed_range> = (since C++23) + + ranges::enable_borrowed_range; + + This specialization of ranges::enable_borrowed_range makes stride_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ranges_stride 202207L (C++23) std::ranges::stride_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + using namespace std::literals; + + void print(std::ranges::viewable_range auto&& v, std::string_view separator = " ") + { + for (auto const& x : v) + std::cout << x << separator; + std::cout << '\\n'; + } + + int main() + { + print(std::views::iota(1, 13) | std::views::stride(3)); + print(std::views::iota(1, 13) | std::views::stride(3) | std::views::reverse); + print(std::views::iota(1, 13) | std::views::reverse | std::views::stride(3)); + + print("0x0!133713337*x//42/A$@"sv | std::views::stride(0B11) | + std::views::transform([](char O) -> char { return 0100 | O; }), + ""); + } + +.SH Output: + + 1 4 7 10 + 10 7 4 1 + 12 9 6 3 + password + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 26.7.31 Stride view [range.stride] + +.SH See also + + ranges::slide_view a view whose M^th element is a view over the M^th through (M + + views::slide N - 1)^th elements of another view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::chunk_view a range of views that are N-sized non-overlapping successive + views::chunk chunks of the elements of another view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::adjacent_view a view consisting of tuples of references to adjacent elements + views::adjacent of the adapted view + (C++23) \fI(class template)\fP (range adaptor object) + ranges::filter_view a view that consists of the elements of a range that satisfies + views::filter a predicate + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::take,std::ranges::take_view.3 b/man/std::ranges::views::take,std::ranges::take_view.3 new file mode 100644 index 000000000..7a28b6cd0 --- /dev/null +++ b/man/std::ranges::views::take,std::ranges::take_view.3 @@ -0,0 +1,173 @@ +.TH std::ranges::views::take,std::ranges::take_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::take,std::ranges::take_view \- std::ranges::views::take,std::ranges::take_view + +.SH Synopsis + Defined in header + template< ranges::view V > + + class take_view \fB(1)\fP \fI(since C++20)\fP + + : public ranges::view_interface> + namespace views { + + inline constexpr /* unspecified */ take = /* unspecified */; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< ranges::viewable_range R > + + requires /* see below */ \fI(since C++20)\fP + constexpr ranges::view auto + + take( R&& r, ranges::range_difference_t count ); + template< class DifferenceType > + constexpr /* range adaptor closure */ take( DifferenceType&& count \fI(since C++20)\fP + ); + + 1) A range adaptor that represents view of the elements from an underlying sequence, + starting at the beginning and ending at a given bound. + 2) views::take is a RangeAdaptorObject. The expression views::take(e, f) results in + a view that represents the first f elements from e. The result is not necessarily a + take_view. + + views::take(e, f) is expression-equivalent to (where T is + std::remove_cvref_t and D is + ranges::range_difference_t): + + * ((void)f, decay-copy(e)), if T is a ranges::empty_view, except that the + evaluations of e and f are indeterminately sequenced; + * U(ranges::begin(e), ranges::begin(e) + std::min(ranges::distance(e), f)), if + T is a specialization of std::span, std::basic_string_view, or ranges::subrange + that models both random_access_range and sized_range, where U is + + * std::span, if T is a specialization of std::span; + * T, if T is a specialization of std::basic_string_view; + * ranges::subrange>, if T is a specialization of + ranges::subrange; + * ranges::iota_view(*ranges::begin(e), + *(ranges::begin(e) + std::min(ranges::distance(e), f))), if + T is a specialization of ranges::iota_view that models both random_access_range + and sized_range; + + * otherwise, if T is a specialization of ranges::repeat_view: + + * views::repeat(*e.value_, std::min(ranges::distance(e), f)), if (since C++23) + T models sized_range; is such case e is evaluated only once; + * views::repeat(*e.value_, static_cast(e)) otherwise; + + * otherwise, take_view(e, f). + In all cases, decltype((f)) must model std::convertible_to. + + take_view models the concepts contiguous_range, random_access_range, + bidirectional_range, forward_range, input_range, and sized_range when the underlying + view V models respective concepts. It models common_range when the underlying view V + models both random_access_range and sized_range. + +.SH Member functions + + constructor constructs a take_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++20) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + sentinel the sentinel type + (C++20) (exposition-only member class template*) + + Helper templates + + template< class T > + + inline constexpr bool \fI(since C++20)\fP + enable_borrowed_range> = + + std::ranges::enable_borrowed_range; + + This specialization of std::ranges::enable_borrowed_range makes take_view satisfy + borrowed_range when the underlying view satisfies it. + +.SH Example + + +// Run this code + + #include + #include + #include + + auto print = [](char x){ std::cout << x; }; + + int main() + { + constexpr char pi[]{'3', '.', '1', '4', '1', '5', '9', '2'}; + + std::ranges::for_each(pi | std::ranges::views::take(6), print); + std::cout << '\\n'; + + // safely takes 8 chars only, i.e. min(pi.size(), 42) + std::ranges::for_each(std::ranges::take_view{pi, 42}, print); + + std::cout << '\\n'; + } + +.SH Output: + + 3.1415 + 3.141592 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + views::take sometimes failed + LWG 3407 C++20 to the result type is adjusted so + construct a sized random that construction is always valid + access range + LWG 3494 C++20 take_view was never a it is a borrowed_range if its + borrowed_range underlying view is + +.SH See also + + views::counted creates a subrange from an iterator and a count + (C++20) (customization point object) + ranges::take_while_view a view consisting of the initial elements of another view, + views::take_while until the first element on which a predicate returns false + (C++20) \fI(class template)\fP (range adaptor object) + ranges::copy_n copies a number of elements to a new location + (C++20) (niebloid) diff --git a/man/std::ranges::views::take_while,std::ranges::take_while_view.3 b/man/std::ranges::views::take_while,std::ranges::take_while_view.3 new file mode 100644 index 000000000..f0f5ce1e1 --- /dev/null +++ b/man/std::ranges::views::take_while,std::ranges::take_while_view.3 @@ -0,0 +1,115 @@ +.TH std::ranges::views::take_while,std::ranges::take_while_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::take_while,std::ranges::take_while_view \- std::ranges::views::take_while,std::ranges::take_while_view + +.SH Synopsis + Defined in header + template< ranges::view V, class Pred > + + requires ranges::input_range && + std::is_object_v && + std::indirect_unary_predicate> + class take_while_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /*unspecified*/ take_while = /*unspecified*/; \fB(2)\fP \fI(since C++20)\fP + + } + Call signature + template< ranges::viewable_range R, class Pred > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto take_while( R&& r, Pred&& pred ); + template< class Pred > \fI(since C++20)\fP + constexpr /*range adaptor closure*/ take_while( Pred&& pred ); + + 1) A range adaptor that represents view of the elements from an underlying sequence, + starting at the beginning and ending at the first element for which the predicate + returns false. + 2) RangeAdaptorObject. The expression views::take_while(e, f) is + expression-equivalent to take_while_view(e, f) for any suitable subexpressions e and + f. + + take_while_view models the concepts contiguous_range, random_access_range, + bidirectional_range, forward_range, and input_range when the underlying view V + models respective concepts. + +.SH Member functions + + constructor constructs a take_while_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + pred returns a reference to the stored predicate + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns a sentinel representing the end + (C++20) \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + data gets the address of derived view's data. Provided if its iterator type + (C++20) satisfies contiguous_iterator. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + sentinel the sentinel type + (exposition-only member class template*) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (int year : std::views::iota(2020) + | std::views::take_while([](int y) { return y <= 2023; })) + std::cout << year << ' '; + std::cout << '\\n'; + + const char idea[] {"Today is yesterday's tomorrow!..."}; + for (char x : std::ranges::take_while_view(idea, [](char c) { return c != '.'; })) + std::cout << x; + std::cout << '\\n'; + } + +.SH Output: + + 2020 2021 2022 2023 + Today is yesterday's tomorrow! + +.SH See also + + ranges::take_view a view consisting of the first N elements of another view + views::take \fI(class template)\fP (range adaptor object) + (C++20) + ranges::drop_while_view a view consisting of the elements of another view, skipping + views::drop_while the initial subsequence of elements until the first element + (C++20) where the predicate returns false + \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::transform,std::ranges::transform_view.3 b/man/std::ranges::views::transform,std::ranges::transform_view.3 new file mode 100644 index 000000000..a587d0a93 --- /dev/null +++ b/man/std::ranges::views::transform,std::ranges::transform_view.3 @@ -0,0 +1,150 @@ +.TH std::ranges::views::transform,std::ranges::transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::transform,std::ranges::transform_view \- std::ranges::views::transform,std::ranges::transform_view + +.SH Synopsis + Defined in header + template< ranges::input_range V, + + std::copy_constructible F > + requires ranges::view && + std::is_object_v && + std::regular_invocable> && (until C++23) + /* invoke_result_t>& is + a valid type */ + class transform_view + + : public ranges::view_interface> + template< ranges::input_range V, + + std::move_constructible F > + requires ranges::view && + std::is_object_v && + std::regular_invocable> && \fB(1)\fP + /* invoke_result_t>& is + a valid type */ + class transform_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /*unspecified*/ transform = \fB(2)\fP \fI(since C++20)\fP + /*unspecified*/; + + } + Call signature + template< ranges::viewable_range R, class F > + + requires /* see below */ \fI(since C++20)\fP + + constexpr ranges::view auto transform( R&& r, F&& fun ); + template< class F > \fI(since C++20)\fP + constexpr /*range adaptor closure*/ transform( F&& fun ); + + 1) A range adaptor that represents view of an underlying sequence after applying a + transformation function to each element. + 2) RangeAdaptorObject. The expression views::transform(e, f) is + expression-equivalent to transform_view(e, f) for any suitable subexpressions e and + f. + + transform_view models the concepts random_access_range, bidirectional_range, + forward_range, input_range, common_range, and sized_range when the underlying view V + models respective concepts. + +.SH Member functions + + constructor constructs a transform_view + (C++20) \fI(public member function)\fP + base returns a copy of the underlying (adapted) view + (C++20) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++20) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++20) \fI(public member function)\fP + size returns the number of elements. Provided only if the underlying + (C++20) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++20) (exposition-only member class template*) + sentinel the sentinel type + (C++20) (exposition-only member class template*) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + char rot13a(const char x, const char a) + { + return a + (x - a + 13) % 26; + } + + char rot13(const char x) + { + if ('Z' >= x and x >= 'A') + return rot13a(x, 'A'); + + if ('z' >= x and x >= 'a') + return rot13a(x, 'a'); + + return x; + } + + int main() + { + auto show = [](const unsigned char x) { std::putchar(x); }; + + std::string in{"cppreference.com\\n"}; + std::ranges::for_each(in, show); + std::ranges::for_each(in | std::views::transform(rot13), show); + + std::string out; + std::ranges::copy(std::views::transform(in, rot13), std::back_inserter(out)); + std::ranges::for_each(out, show); + std::ranges::for_each(out | std::views::transform(rot13), show); + } + +.SH Output: + + cppreference.com + pccersrerapr.pbz + pccersrerapr.pbz + cppreference.com + +.SH See also + + ranges::transform applies a function to a range of elements + (C++20) (niebloid) diff --git a/man/std::ranges::views::values,std::ranges::values_view.3 b/man/std::ranges::views::values,std::ranges::values_view.3 new file mode 100644 index 000000000..362204f55 --- /dev/null +++ b/man/std::ranges::views::values,std::ranges::values_view.3 @@ -0,0 +1,79 @@ +.TH std::ranges::views::values,std::ranges::values_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::values,std::ranges::values_view \- std::ranges::views::values,std::ranges::values_view + +.SH Synopsis + Defined in header + template< class R > \fB(1)\fP \fI(since C++20)\fP + using values_view = ranges::elements_view; + namespace views { + + inline constexpr auto values = ranges::elements<1>; \fB(2)\fP \fI(since C++20)\fP + + } + + Takes a view of tuple-like values (e.g. std::tuple or std::pair), and produces a + view with a value-type of the second element of the adapted view's value-type. + + 1) An alias for ranges::elements_view. + 2) RangeAdaptorObject (and also RangeAdaptorClosureObject). The expression + views::values(e) is expression-equivalent to + values_view>{e} for any suitable subexpression e. + +.SH Notes + + values_view can be useful for extracting values from associative containers, e.g. + + std::map map{{1, "alpha"}, {2, "beta"}}; + for (auto const& value : std::views::values(map)) + std::cout << value << ' '; + // prints: alpha beta + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto list = {std::pair{1, 11.1}, {2, 22.2}, {3, 33.3}}; + std::cout << "pair::second values in the list: "; + for (double value : list | std::views::values) + std::cout << value << ' '; + + std::map map{{'A', 1}, {'B', 2}, {'C', 3}, {'D', 4}, {'E', 5}}; + auto odd = [](int x) { return 0 != (x & 1); }; + std::cout << "\\nodd values in the map: "; + for (int value : map | std::views::values | std::views::filter(odd)) + std::cout << value << ' '; + std::cout << '\\n'; + } + +.SH Output: + + pair::second values in the list: 11.1 22.2 33.3 + odd values in the map: 1 3 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3563 C++20 keys_view is unable to participate in CTAD views::all_t removed + due to its use of views::all_t + +.SH See also + + ranges::keys_view takes a view consisting of pair-like values and produces a + views::keys view of the first elements of each pair + (C++20) \fI(class template)\fP (range adaptor object) + ranges::elements_view takes a view consisting of tuple-like values and a number N + views::elements and produces a view of N^th element of each tuple + (C++20) \fI(class template)\fP (range adaptor object) + slice BLAS-like slice of a valarray: starting index, length, stride + \fI(class)\fP diff --git a/man/std::ranges::views::zip,std::ranges::zip_view.3 b/man/std::ranges::views::zip,std::ranges::zip_view.3 new file mode 100644 index 000000000..fa3181e7d --- /dev/null +++ b/man/std::ranges::views::zip,std::ranges::zip_view.3 @@ -0,0 +1,178 @@ +.TH std::ranges::views::zip,std::ranges::zip_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::zip,std::ranges::zip_view \- std::ranges::views::zip,std::ranges::zip_view + +.SH Synopsis + Defined in header + template< ranges::input_range... Views > + + requires (ranges::view && ...) && (sizeof...(Views) > + 0) \fB(1)\fP (since C++23) + class zip_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /*unspecified*/ zip = /*unspecified*/; \fB(2)\fP (since C++23) + + } + Call signature + template< ranges::viewable_range... Rs > + + requires /* see below */ (since C++23) + + constexpr auto zip( Rs&&... rs ); + + 1) zip_view is a range adaptor that takes one or more views, and produces a view + whose ith element is a tuple-like value consisting of the i^th elements of all + views. The size of produced view is the minimum of sizes of all adapted views. + 2) views::zip is a customization point object. + + When calling with no argument, views::zip() is expression-equivalent to + auto(views::empty>). + + Otherwise, views::zip(rs...) is expression-equivalent to + ranges::zip_view...>(rs...). + + zip_view always models input_range, and models forward_range, bidirectional_range, + random_access_range, or sized_range if all adapted view types model the + corresponding concept. + + zip_view models common_range if + + * sizeof...(Views) is equal to 1, and the only adapted view type models + common_range, or + * at least one adapted view type does not model bidirectional_range, and every + adapted view type models common_range, or + * every adapted view type models both random_access_range and sized_range. + +.SH Member functions + + constructor constructs a zip_view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if each underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type used when zip_view is not a common_range + (C++23) (exposition-only member class template*) + + Helper templates + + template< class... Views > + + inline constexpr bool (since C++23) + enable_borrowed_range> = + + (ranges::enable_borrowed_range && ...); + + This specialization of ranges::enable_borrowed_range makes zip_view satisfy + borrowed_range when each underlying view satisfies it. + +.SH Notes + + Feature-test macro Value Std Feature + std::ranges::zip_view, + __cpp_lib_ranges_zip 202110L (C++23) std::ranges::zip_transform_view, + std::ranges::adjacent_view, + std::ranges::adjacent_transform_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(auto const rem, auto const& range) + { + for (std::cout << rem; auto const& elem : range) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto x = std::vector{1, 2, 3, 4}; + auto y = std::list{"α", "β", "γ", "δ", "ε"}; + auto z = std::array{'A', 'B', 'C', 'D', 'E', 'F'}; + + print("Source views:", ""); + print("x: ", x); + print("y: ", y); + print("z: ", z); + + print("\\nzip(x,y,z):", ""); + + for (std::tuple elem : std::views::zip(x, y, z)) + { + std::cout << std::get<0>(elem) << ' ' + << std::get<1>(elem) << ' ' + << std::get<2>(elem) << '\\n'; + + std::get(elem) += ('a' - 'A'); // modifies the element of z + } + + print("\\nAfter modification, z: ", z); + } + +.SH Output: + + Source views: + x: 1 2 3 4 + y: α β γ δ ε + z: A B C D E F + + zip(x,y,z): + 1 α A + 2 β B + 3 γ C + 4 δ D + + After modification, z: a b c d E F + +.SH See also + + ranges::zip_transform_view a view consisting of tuples of results of application of + views::zip_transform a transformation function to corresponding elements of + (C++23) the adapted views + \fI(class template)\fP (customization point object) + ranges::elements_view takes a view consisting of tuple-like values and a number + views::elements N and produces a view of N^th element of each tuple + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::views::zip_transform,std::ranges::zip_transform_view.3 b/man/std::ranges::views::zip_transform,std::ranges::zip_transform_view.3 new file mode 100644 index 000000000..7ad542f8f --- /dev/null +++ b/man/std::ranges::views::zip_transform,std::ranges::zip_transform_view.3 @@ -0,0 +1,180 @@ +.TH std::ranges::views::zip_transform,std::ranges::zip_transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::views::zip_transform,std::ranges::zip_transform_view \- std::ranges::views::zip_transform,std::ranges::zip_transform_view + +.SH Synopsis + Defined in header + template< std::move_constructible F, ranges::input_range... Views + > + + requires (ranges::view && ...) && (sizeof...(Views) > + 0) && + std::is_object_v && std::regular_invocable< + F&, ranges::range_reference_t...> && \fB(1)\fP (since C++23) + /*can-reference*/...>> + class zip_transform_view + + : public ranges::view_interface> + namespace views { + + inline constexpr /*unspecified*/ zip_transform = \fB(2)\fP (since C++23) + /*unspecified*/; + + } + Call signature + template< class F, ranges::viewable_range... Rs > + + requires /* see below */ (since C++23) + + constexpr auto zip_transform( F&& f, Rs&&... rs ); + + 1) zip_transform_view is a range adaptor that takes an invocable object and one or + more views, and produces a view whose i^th element is the result of applying the + invocable object to the i^th elements of all views. + A type T models the exposition-only concept /*can-reference*/ if and only if T& is a + valid type. + 2) views::zip_transform is a customization point object. + + When calling with one argument f, let FD be std::decay_t, if: + + * FD models copy_constructible, + * FD& models regular_invocable, and + * std::invoke_result_t is an object type, + + then views::zip_transform(f) is expression-equivalent to ((void)f, + auto(views::empty>>)). Otherwise, the call to + views::zip_transform is ill-formed. + + When calling with more than one arguments f and rs..., views::zip_transform(f, + rs...) is expression-equivalent to ranges::zip_transform_view(f, rs...). + + zip_transform_view models the concepts random_access_range, bidirectional_range, + forward_range, input_range, common_range, and sized_range when the underlying + ranges::zip_view models respective concepts. + +.SH Member functions + + constructor constructs a zip_transform_view + (C++23) \fI(public member function)\fP + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + size returns the number of elements. Provided only if each underlying + (C++23) (adapted) range satisfies sized_range. + \fI(public member function)\fP + Inherited from std::ranges::view_interface + empty returns whether the derived view is empty. Provided if it satisfies + (C++20) sized_range or forward_range. + \fI(public member function of std::ranges::view_interface)\fP + cbegin returns a constant iterator to the beginning of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + cend returns a sentinel for the constant iterator of the range. + (C++23) \fI(public member function of std::ranges::view_interface)\fP + operator bool returns whether the derived view is not empty. Provided if + (C++20) ranges::empty is applicable to it. + \fI(public member function of std::ranges::view_interface)\fP + front returns the first element in the derived view. Provided if it + (C++20) satisfies forward_range. + \fI(public member function of std::ranges::view_interface)\fP + back returns the last element in the derived view. Provided if it satisfies + (C++20) bidirectional_range and common_range. + \fI(public member function of std::ranges::view_interface)\fP + operator[] returns the n^th element in the derived view. Provided if it satisfies + (C++20) random_access_range. + \fI(public member function of std::ranges::view_interface)\fP + + Deduction guides + +.SH Member types + + Member type Definition + InnerView (private) ranges::zip_view. + (exposition-only member type*) + * ranges::iterator_t if Const is true, + ziperator (private) otherwise + * ranges::iterator_t. + (exposition-only member type*) + * ranges::sentinel_t if Const is true, + zentinel (private) otherwise + * ranges::sentinel_t. + (exposition-only member type*) + + Data members + + Member object Definition + zip_ (private) An underlying view object of type InnerView + (exposition-only member object*) + fun_ (private) A wrapped invocable object of type movable-box + (exposition-only member object*) + + Nested classes + + iterator the iterator type + (C++23) (exposition-only member class template*) + sentinel the sentinel type used when the underlying zip_view is not a common_range + (C++23) (exposition-only member class template*) + +.SH Notes + + Feature-test macro Value Std Feature + std::ranges::zip_view, + __cpp_lib_ranges_zip 202110L (C++23) std::ranges::zip_transform_view, + std::ranges::adjacent_view, + std::ranges::adjacent_transform_view + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto const rem, auto const& r) + { + std::cout << rem << '{'; + for (char o[]{0,' ',0}; auto const& e : r) + std::cout << o << e, *o = ','; + std::cout << "}\\n"; + } + + int main() + { + auto v1 = std::vector{1, 2, 3}; + auto v2 = std::list{1, 2, 3, 4}; + auto v3 = std::to_array({1, 2, 3, 4, 5}); + + auto add = [](auto a, auto b, auto c) { return a + b + c; }; + + auto sum = std::views::zip_transform(add, v1, v2, v3); + + print("v1: ", v1); + print("v2: ", v2); + print("v3: ", v3); + print("sum: ", sum); + } + +.SH Output: + + v1: {1, 2, 3} + v2: {1, 2, 3, 4} + v3: {1, 2, 3, 4, 5} + sum: {3, 6, 9} + +.SH See also + + ranges::zip_view a view consisting of tuples of references to corresponding + views::zip elements of the adapted views + (C++23) \fI(class template)\fP (customization point object) + ranges::transform_view a view of a sequence that applies a transformation function + views::transform to each element + (C++20) \fI(class template)\fP (range adaptor object) + ranges::elements_view takes a view consisting of tuple-like values and a number N + views::elements and produces a view of N^th element of each tuple + (C++20) \fI(class template)\fP (range adaptor object) diff --git a/man/std::ranges::zip_transform_view::begin.3 b/man/std::ranges::zip_transform_view::begin.3 new file mode 100644 index 000000000..22e0a6050 --- /dev/null +++ b/man/std::ranges::zip_transform_view::begin.3 @@ -0,0 +1,41 @@ +.TH std::ranges::zip_transform_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::begin \- std::ranges::zip_transform_view::begin + +.SH Synopsis + constexpr auto begin(); \fB(1)\fP (since C++23) + constexpr auto begin() const \fB(2)\fP (since C++23) + requires ranges::range>; + + Obtains the beginning iterator of zip_transform_view. + + 1) Equivalent to return /*iterator*/(*this, zip_.begin());. + 2) Equivalent to return /*iterator*/(*this, zip_.begin());. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Notes + + ranges::range> is modeled if and only if for every + type Vi in Views..., const Vi models range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::end.3 b/man/std::ranges::zip_transform_view::end.3 new file mode 100644 index 000000000..f611d63d7 --- /dev/null +++ b/man/std::ranges::zip_transform_view::end.3 @@ -0,0 +1,56 @@ +.TH std::ranges::zip_transform_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::end \- std::ranges::zip_transform_view::end + +.SH Synopsis + constexpr auto end(); \fB(1)\fP (since C++23) + constexpr auto end() const + + requires ranges::range && \fB(2)\fP (since C++23) + std::regular_invocable...>; + + Returns an iterator or a sentinel that compares equal to the end iterator of the + zip_transform_view. + + Let zip_ denote the underlying tuple of views: + + 1) Equivalent to: + if constexpr (ranges::common_range) + + return /*iterator*/(*this, zip_.end()); + else + + return /*sentinel*/(zip_.end()); + 2) Equivalent to: + if constexpr (ranges::common_range) + + return /*iterator*/(*this, zip_.end()); + else + + return /*sentinel*/(zip_.end()); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator or sentinel representing the end of the zip_transform_view, as described + above. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::iterator.3 b/man/std::ranges::zip_transform_view::iterator.3 new file mode 100644 index 000000000..61d6189c7 --- /dev/null +++ b/man/std::ranges::zip_transform_view::iterator.3 @@ -0,0 +1,108 @@ +.TH std::ranges::zip_transform_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::iterator \- std::ranges::zip_transform_view::iterator + +.SH Synopsis + template< bool Const > (since C++23) + class /*iterator*/; (exposition only*) + + The iterator type of a possibly const-qualified zip_transform_view, returned by + zip_transform_view::begin and in certain cases by zip_transform_view::end. + + The type /*iterator*/ or /*iterator*/ treats the underlying views as + const-qualified or non-const-qualified respectively. + +.SH Member types + + Member type Definition + zip_transform_view if Const is false, const zip_transform_view + Parent (private) otherwise. + (exposition-only member type*) + Base (private) InnerView if Const is false, const InnerView otherwise. + (exposition-only member type*) + Let /*maybe-const*/& denote const F& if Const is true, + F& otherwise. + Let /*maybe-const*/ denote const Views if Const is + true, Views otherwise. + + Let /*POT*/ denote the pack of types + std::iterator_traits>>::iterator_category... + + If /*Base*/ models forward_range, then iterator_category denotes: + + * std::input_iterator_tag, if + std::invoke_result_t&, + ranges::range_reference_t>...> + + iterator_category is not a reference. + (optional) * Otherwise, + + * std::random_access_iterator_tag, if + + (std::derived_from && + ...) is true. + * Otherwise, std::bidirectional_iterator_tag, if + + (std::derived_from && + ...) is true. + * Otherwise, std::forward_iterator_tag, if + + (std::derived_from && ...) is + true. + * Otherwise, std::input_iterator_tag. + + Not present if /*Base*/ does not model forward_range. + iterator_concept /*ziperator*/::iterator_concept + Let /*RREF*/ be ranges::range_reference_t..., + and /*CRREF*/ be ranges::range_reference_t.... Then: + + value_type * std::remove_cvref_t> if + Const is false, + * std::remove_cvref_t> + otherwise. + difference_type range::range_difference_t + + Data members + + Member object Definition + parent_ (private) A pointer Parent* to the parent object + (exposition-only member object*) + inner_ (private) An iterator of type ziperator. + (exposition-only member type*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* obtains the result of applying the invocable object to the + (C++23) underlying poined-to elements + \fI(public member function)\fP + operator[] obtains the result of applying the invocable object to the + (C++23) underlying elements at given offset + \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterator + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== compares the underlying iterators + operator<=> \fI(function)\fP + (C++23) + operator+ performs iterator arithmetic on underlying iterators + operator- \fI(function)\fP + (C++23) + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::iterator::iterator.3 b/man/std::ranges::zip_transform_view::iterator::iterator.3 new file mode 100644 index 000000000..2e647e7f3 --- /dev/null +++ b/man/std::ranges::zip_transform_view::iterator::iterator.3 @@ -0,0 +1,39 @@ +.TH std::ranges::zip_transform_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::iterator::iterator \- std::ranges::zip_transform_view::iterator::iterator + +.SH Synopsis + /*iterator*/iterator() = default; \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + /*ziperator*/>; + constexpr /*iterator*/( Parent& parent, /*ziperator*/ \fB(3)\fP (exposition only*) + inner ); + + Construct an iterator. + + 1) Default constructor. Default-initializes the underlying iterators, and + value-initializes the pointer to parent ranges::zip_transform_view with nullptr. + 2) Conversion from /*iterator*/ to /*iterator*/. Move constructs the + underlying pointer to parent parent_ with i.parent_ and inner_ with + std::move(i.inner_). + 3) Initializes the pointer to parent parent_ with std::addressof(parent), and the + underlying inner_ iterator with std::move(inner). This constructor is not accessible + to users. + +.SH Parameters + + i - an /*iterator*/ + parent - a (possibly const-qualified) ranges::zip_transform_view + inner - an iterator of type ziperator + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::iterator::operator*.3 b/man/std::ranges::zip_transform_view::iterator::operator*.3 new file mode 100644 index 000000000..97904c4b8 --- /dev/null +++ b/man/std::ranges::zip_transform_view::iterator::operator*.3 @@ -0,0 +1,57 @@ +.TH std::ranges::zip_transform_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::iterator::operator* \- std::ranges::zip_transform_view::iterator::operator* + +.SH Synopsis + constexpr decltype(auto) operator*() const (since C++23) + noexcept(/* see description */); + + Returns the transformed element obtained by application of the invocable object of + type F to the underlying poined-to elements. + + Equivalent to + + return + std::apply + ( + [&](auto const&... iters) -> decltype(auto) + { + return std::invoke(*parent_->fun_, *iters...); + }, + inner_.current_ + ); + + where *parent_->fun_ is the transformation function stored in the parent + ranges::zip_transform_view, and current_ is the underlying tuple of iterators into + Views.... + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The element which is the result of transformation (mapping). + +.SH Exceptions + + noexcept specification: + noexcept(std::invoke(*parent_->fun_, *std::get(inner_.current_)...)) + + where INTS is the pack of integers 0, 1, ..., (sizeof...(Views)-1). + +.SH Notes + + operator-> is not provided. + + The behavior is undefined if the parent_ pointer to parent + ranges::zip_transform_view is null (e.g. if *this is default constructed). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::ranges::zip_transform_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::zip_transform_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..5c670676d --- /dev/null +++ b/man/std::ranges::zip_transform_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,52 @@ +.TH std::ranges::zip_transform_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::iterator::operator++,--,+=,-= \- std::ranges::zip_transform_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/ operator++( int ) \fB(3)\fP (since C++23) + requires ranges::forward_range; + constexpr /*iterator*/& operator--() \fB(4)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/ operator--( int ) \fB(5)\fP (since C++23) + requires ranges::bidirectional_range; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(6)\fP (since C++23) + requires ranges::random_access_range; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(7)\fP (since C++23) + requires ranges::random_access_range; + + Increments or decrements the iterator. + + Let inner_ be the underlying iterator and Base be the exposition-only member type. + + Equivalent to: + + 1) ++inner_; return *this; + 2) ++*this; + 3) auto tmp = *this; ++*this; return tmp; + 4) --inner_; return *this; + 5) auto tmp = *this; --*this; return tmp; + 6) inner_ += n; return *this; + 7) inner_ -= n; return *this; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::iterator::operator[].3 b/man/std::ranges::zip_transform_view::iterator::operator[].3 new file mode 100644 index 000000000..a0a5dd5f1 --- /dev/null +++ b/man/std::ranges::zip_transform_view::iterator::operator[].3 @@ -0,0 +1,46 @@ +.TH std::ranges::zip_transform_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::iterator::operator[] \- std::ranges::zip_transform_view::iterator::operator[] + +.SH Synopsis + constexpr decltype(auto) operator[]( difference_type n ) const (since C++23) + requires ranges::random_access_range; + + Returns the element at specified relative location, after transformation. + + Equivalent to + + return + std::apply + ( + [&](const Is&... iters) -> decltype(auto) + { + return std::invoke(*parent_->fun_, iters[std::iter_difference_t(n)]...); + }, + inner_.current_ + ); + + where *parent_->fun_ is the transformation function of type F stored in the parent + ranges::zip_transform_view, and current_ is the underlying tuple of iterators into + Views.... + +.SH Parameters + + n - position relative to current location. + +.SH Return value + + The element which is the result of transformation (mapping). + +.SH Notes + + The behavior is undefined if the parent_ pointer to parent + ranges::zip_transform_view is null (e.g. if *this is default constructed). + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::sentinel.3 b/man/std::ranges::zip_transform_view::sentinel.3 new file mode 100644 index 000000000..6185fea33 --- /dev/null +++ b/man/std::ranges::zip_transform_view::sentinel.3 @@ -0,0 +1,33 @@ +.TH std::ranges::zip_transform_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::sentinel \- std::ranges::zip_transform_view::sentinel + +.SH Synopsis + template< bool Const > (since C++23) + class /*sentinel*/; (exposition only*) + + The return type of zip_transform_view::end when the underlying view is not a + common_range. + + The type /*sentinel*/ or /*sentinel*/ treats the underlying view as + const-qualified or non-const-qualified respectively. + + Data members + + Member object Definition + inner_ (private) A sentinel of type zentinel + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from + (C++23) zip_transform_view::begin + \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++23) zip_transform_view::begin + \fI(function)\fP diff --git a/man/std::ranges::zip_transform_view::sentinel::sentinel.3 b/man/std::ranges::zip_transform_view::sentinel::sentinel.3 new file mode 100644 index 000000000..045537120 --- /dev/null +++ b/man/std::ranges::zip_transform_view::sentinel::sentinel.3 @@ -0,0 +1,34 @@ +.TH std::ranges::zip_transform_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::sentinel::sentinel \- std::ranges::zip_transform_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && \fB(2)\fP (since C++23) + + std::convertible_to, + /*zentinel*/>; + constexpr explicit /*sentinel*/( /*zentinel*/ inner ); \fB(3)\fP (exposition only*) + + Constructs a sentinel. + + 1) Default constructor. Default-initializes the underlying sentinel object inner_. + 2) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying object inner_ with std::move(i.inner_). + 3) Value-initializes the underlying object inner_ with inner. This constructor is + not accessible to users. + +.SH Parameters + + i - a /*sentinel*/ + inner - an underlying object of type zentinel + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_transform_view::size.3 b/man/std::ranges::zip_transform_view::size.3 new file mode 100644 index 000000000..086f194c2 --- /dev/null +++ b/man/std::ranges::zip_transform_view::size.3 @@ -0,0 +1,65 @@ +.TH std::ranges::zip_transform_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::size \- std::ranges::zip_transform_view::size + +.SH Synopsis + constexpr auto size() \fB(1)\fP (since C++23) + requires ranges::sized_range; + constexpr auto size() const \fB(2)\fP (since C++23) + requires ranges::sized_range + + Returns the number of elements in the zip_transform_view. Provided only if each + underlying (adapted) range satisfies sized_range. + + 1,2) Equivalent to: return zip_.size();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements, which is the minimum size among all sizes of adapted views. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + int main() + { + auto x = std::vector{1, 2, 3, 4, 5}; + auto y = std::deque{10, 20, 30}; + auto z = std::forward_list{100., 200.}; + + auto v1 = std::views::zip_transform(std::plus{}, x, y); + assert(v1.size() == std::min(x.size(), y.size())); + assert(v1.size() == 3); + for (int i : v1) + std::cout << i << ' '; + std::cout << '\\n'; + + [[maybe_unused]] auto v2 = std::views::zip_transform(std::plus{}, x, z); + // auto sz = v2.size(); // Error: z doesn't have size(), so neither does v2 + static_assert(not std::ranges::sized_range); + } + +.SH Output: + + 11 22 33 + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::zip_transform_view::zip_transform_view.3 b/man/std::ranges::zip_transform_view::zip_transform_view.3 new file mode 100644 index 000000000..e87dd3e23 --- /dev/null +++ b/man/std::ranges::zip_transform_view::zip_transform_view.3 @@ -0,0 +1,30 @@ +.TH std::ranges::zip_transform_view::zip_transform_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_transform_view::zip_transform_view \- std::ranges::zip_transform_view::zip_transform_view + +.SH Synopsis + zip_transform_view() = default; \fB(1)\fP (since C++23) + constexpr zip_transform_view( F fun, Views... views ); \fB(2)\fP (since C++23) + + 1) Default constructor. Value-initializes the stored invocable object and all + adapted view objects. + + The default constructor is deleted if + + * F does not satisfy default_initializable, or + * std::is_default_constructible_v is false for at least one type in Views.... + 2) Move constructs the stored invocable object from fun and every adapted view + object from the corresponding view in views.... + +.SH Parameters + + f - invocable object used for generation of elements of zip_transform_view + views - view objects to adapt + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::begin.3 b/man/std::ranges::zip_view::begin.3 new file mode 100644 index 000000000..3551159f2 --- /dev/null +++ b/man/std::ranges::zip_view::begin.3 @@ -0,0 +1,44 @@ +.TH std::ranges::zip_view::begin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::begin \- std::ranges::zip_view::begin + +.SH Synopsis + constexpr auto begin() \fB(1)\fP (since C++23) + requires (!(/*simple-view*/ && ...)); + constexpr auto begin() const \fB(2)\fP (since C++23) + requires (ranges::range && ...); + + Obtains the beginning iterator of zip_view. + + 1) Equivalent to return /*iterator*/(/*tuple-transform*/(ranges::begin, + views_));. + 2) Equivalent to return /*iterator*/(/*tuple-transform*/(ranges::begin, + views_));. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Notes + + ranges::range> is modeled if and only if for every + type Vi in Views..., const Vi models range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + end returns an iterator or a sentinel to the end + (C++23) \fI(public member function)\fP + ranges::begin returns an iterator to the beginning of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::end.3 b/man/std::ranges::zip_view::end.3 new file mode 100644 index 000000000..a68fc9cb8 --- /dev/null +++ b/man/std::ranges::zip_view::end.3 @@ -0,0 +1,70 @@ +.TH std::ranges::zip_view::end 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::end \- std::ranges::zip_view::end + +.SH Synopsis + constexpr auto end() \fB(1)\fP (since C++23) + requires (!(/*simple-view*/ && ...); + constexpr auto end() const \fB(2)\fP (since C++23) + requires (ranges::range && ...); + template< class... Rs > + + concept /*zip-is-common*/ = + (sizeof...(Rs) == 1 && (ranges::common_range && ...)) + || + (!(ranges::bidirectional_range && ...) && \fB(3)\fP (exposition only*) + (ranges::common_range && ...)) + || + + ((ranges::random_access_range && ...) && + (ranges::sized_range && ...)); + + Returns a sentinel or an iterator that compares equal to the end iterator of the + std::zip_view. + + Let views_ denote the underlying tuple of views. + + 1) Equivalent to: + * return /*sentinel*/(/*tuple-transform*/(ranges::end, views_));, + + if /*zip-is-common*/ evaluates to false. Otherwise, + * return begin() + std::iter_difference_t>(size());, + + if (ranges::random_access_range && ...) evaluates to true. Otherwise, + * return /*iterator*/(/*tuple-transform*/(ranges::end, views_));. + 2) Equivalent to: + * return /*sentinel*/(/*tuple-transform*/(ranges::end, views_));, + + if /*zip-is-common*/ evaluates to false. Otherwise, + * return begin() + std::iter_difference_t>(size());, + + if ranges::random_access_range && ... evaluates to true. Otherwise, + * return /*iterator*/(/*tuple-transform*/(ranges::end, views_));. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator or sentinel representing the end of the zip_view, as described above. + +.SH Notes + + ranges::range> is modeled if and only if for every + type Vi in Views..., const Vi models range. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + begin returns an iterator to the beginning + (C++23) \fI(public member function)\fP + ranges::end returns a sentinel indicating the end of a range + (C++20) (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::iterator.3 b/man/std::ranges::zip_view::iterator.3 new file mode 100644 index 000000000..de7e398b9 --- /dev/null +++ b/man/std::ranges::zip_view::iterator.3 @@ -0,0 +1,97 @@ +.TH std::ranges::zip_view::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::iterator \- std::ranges::zip_view::iterator + +.SH Synopsis + template< bool Const > \fB(1)\fP (exposition + class /*iterator*/; only*) + Helper concepts + template< bool C, class... Views > + + concept /*all-forward*/ = \fB(2)\fP (exposition + only*) + (ranges::forward_range> && ...); + template< bool C, class... Views > + + concept /*all-bidirectional*/ = \fB(3)\fP (exposition + only*) + (ranges::bidirectional_range> && ...); + template< bool C, class... Views > + + concept /*all-random-access*/ = \fB(4)\fP (exposition + only*) + (ranges::random_access_range> && ...); + + The iterator type of a possibly const-qualified zip_view, returned by + zip_view::begin and in certain cases by zip_view::end. + + The type /*iterator*/ or /*iterator*/ treats the underlying views as + const-qualified or non-const-qualified respectively. + +.SH Member types + + Member type Definition + * std::random_access_iterator_tag if + /*all-random-access*/ is true, otherwise + * std::bidirectional_iterator_tag if + iterator_concept /*all-bidirectional*/ is true, otherwise + * std::forward_iterator_tag if /*all-forward*/ + is true, otherwise + * std::input_iterator_tag + * std::input_iterator_tag if /*all-forward*/ is + iterator_category true, + * not defined otherwise + value_type * std::tuple...> if Const is false, + * std::tuple...> otherwise. + * std::common_type_t...> if + difference_type Const is false, + * std::common_type_t...> + otherwise. + + Data members + + Member object Definition + A tuple of underlying iterators of type + std::tuple...> or + current_ (private) std::tuple...> when Const is + false or true respectively. + (exposition-only member object*) + +.SH Member functions + + constructor constructs an iterator + (C++23) \fI(public member function)\fP + operator* obtains a tuple-like value that consists of underlying pointed-to + (C++23) elements + \fI(public member function)\fP + operator[] obtains a tuple-like value that consists of underlying elements at + (C++23) given offset + \fI(public member function)\fP + operator++ + operator++(int) + operator-- advances or decrements the underlying iterators + operator--(int) \fI(public member function)\fP + operator+= + operator-= + (C++23) + +.SH Non-member functions + + operator== + operator< + operator> compares the underlying iterators + operator<= \fI(function)\fP + operator>= + operator<=> + (C++23) + operator+ performs iterator arithmetic on underlying iterators + operator- \fI(function)\fP + (C++23) + iter_move obtains a tuple-like value that denotes underlying pointed-to elements + (C++23) to be moved + \fI(function)\fP + iter_swap swaps underlying pointed-to elements + (C++23) \fI(function)\fP diff --git a/man/std::ranges::zip_view::iterator::iterator.3 b/man/std::ranges::zip_view::iterator::iterator.3 new file mode 100644 index 000000000..5a7dde414 --- /dev/null +++ b/man/std::ranges::zip_view::iterator::iterator.3 @@ -0,0 +1,35 @@ +.TH std::ranges::zip_view::iterator::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::iterator::iterator \- std::ranges::zip_view::iterator::iterator + +.SH Synopsis + /*iterator*/() = default; \fB(1)\fP (since C++23) + constexpr /*iterator*/( /*iterator*/ i ) + + requires Const && + (std::convertible_to, \fB(2)\fP (since C++23) + + + ranges::iterator_t>> && ...); + + Construct an iterator. + + 1) Default constructor. Value-initializes the underlying tuple of iterators to their + default values. + 2) Conversion from /*iterator*/ to /*iterator*/. Move constructs the + underlying tuple of iterators current_ with std::move(i.current). + + This iterator also has a private constructor which is used by zip_view::begin and + zip_view::end. This constructor is not accessible to users. + +.SH Parameters + + i - an /*iterator*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::iterator::operator*.3 b/man/std::ranges::zip_view::iterator::operator*.3 new file mode 100644 index 000000000..315e9021c --- /dev/null +++ b/man/std::ranges::zip_view::iterator::operator*.3 @@ -0,0 +1,33 @@ +.TH std::ranges::zip_view::iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::iterator::operator* \- std::ranges::zip_view::iterator::operator* + +.SH Synopsis + constexpr auto operator*() const; (since C++23) + + Returns a std::tuple that consists of underlying pointed-to elements. + + Let current_ denote the underlying tuple-like object that holds iterators to + elements of adapted views. Equivalent to: + + return /*tuple-transform*/([](auto& i) -> decltype(auto) { return *i; }, current_); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current tuple-like element. + +.SH Notes + + operator-> is not provided. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::iterator::operator++,--,+=,-=.3 b/man/std::ranges::zip_view::iterator::operator++,--,+=,-=.3 new file mode 100644 index 000000000..46e07bab4 --- /dev/null +++ b/man/std::ranges::zip_view::iterator::operator++,--,+=,-=.3 @@ -0,0 +1,48 @@ +.TH std::ranges::zip_view::iterator::operator++,--,+=,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::iterator::operator++,--,+=,-= \- std::ranges::zip_view::iterator::operator++,--,+=,-= + +.SH Synopsis + constexpr /*iterator*/& operator++(); \fB(1)\fP (since C++23) + constexpr void operator++( int ); \fB(2)\fP (since C++23) + constexpr /*iterator*/ operator++( int ) \fB(3)\fP (since C++23) + requires /*all-forward*/; + constexpr /*iterator*/& operator--() \fB(4)\fP (since C++23) + requires /*all-bidirectional*/; + constexpr /*iterator*/ operator--( int ) \fB(5)\fP (since C++23) + requires /*all-bidirectional*/; + constexpr /*iterator*/& operator+=( difference_type n ) \fB(6)\fP (since C++23) + requires /*all-random-access*/; + constexpr /*iterator*/& operator-=( difference_type n ) \fB(7)\fP (since C++23) + requires /*all-random-access*/; + + Increments or decrements each of the underlying is_... iterators in the underlying + tuple-like object current_. + + 1) Equivalent to /*tuple-for-each*/([](auto& i) { ++i; }, current_); return *this; + 2) Equivalent to ++*this; + 3) Equivalent to auto tmp = *this; ++*this; return tmp; + 4) Equivalent to /*tuple-for-each*/([](auto& i) { --i; }, current_); return *this; + 5) Equivalent to auto tmp = *this; --*this; return tmp; + 6) Equivalent to /*tuple-for-each*/([&](I& i) { i += + iter_difference_t(x); }, current_); return *this; + 7) Equivalent to /*tuple-for-each*/([&](I& i) { i -= + iter_difference_t(x); }, current_); return *this; + +.SH Parameters + + n - position relative to current location + +.SH Return value + + 1,4,6,7) *this + 2) \fI(none)\fP + 3,5) a copy of *this that was made before the change + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::iterator::operator[].3 b/man/std::ranges::zip_view::iterator::operator[].3 new file mode 100644 index 000000000..5107d3997 --- /dev/null +++ b/man/std::ranges::zip_view::iterator::operator[].3 @@ -0,0 +1,32 @@ +.TH std::ranges::zip_view::iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::iterator::operator[] \- std::ranges::zip_view::iterator::operator[] + +.SH Synopsis + constexpr auto operator[]( difference_type n ) const (since C++23) + requires /*all-random-access*/; + + Obtains a std::tuple that consists of underlying pointed-to elements at given offset + relative to current location. + + Equivalent to: + + return /*tuple-transform*/([&](I& i) -> decltype(auto) { + return i[iter_difference_t(n)]; + }, current_); + +.SH Parameters + + n - position relative to current location + +.SH Return value + + The obtained tuple-like element. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::sentinel.3 b/man/std::ranges::zip_view::sentinel.3 new file mode 100644 index 000000000..a5916fd37 --- /dev/null +++ b/man/std::ranges::zip_view::sentinel.3 @@ -0,0 +1,32 @@ +.TH std::ranges::zip_view::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::sentinel \- std::ranges::zip_view::sentinel + +.SH Synopsis + template< bool Const > (since C++23) + class /*sentinel*/; (exposition only*) + + The return type of zip_view::end when the underlying view is not a common_range. + + The type /*sentinel*/ or /*sentinel*/ treats the underlying view as + const-qualified or non-const-qualified respectively. + + Data members + + Member name Definition + * std::tuple...> if Const is false, or + end_ (private) * std::tuple...> if Const is true. + (exposition-only member object*) + +.SH Member functions + + constructor constructs a sentinel + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares a sentinel with an iterator returned from zip_view::begin + (C++23) \fI(function)\fP + operator- computes the distance between a sentinel and an iterator returned from + (C++23) zip_view::begin + \fI(function)\fP diff --git a/man/std::ranges::zip_view::sentinel::sentinel.3 b/man/std::ranges::zip_view::sentinel::sentinel.3 new file mode 100644 index 000000000..facae25b5 --- /dev/null +++ b/man/std::ranges::zip_view::sentinel::sentinel.3 @@ -0,0 +1,32 @@ +.TH std::ranges::zip_view::sentinel::sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::sentinel::sentinel \- std::ranges::zip_view::sentinel::sentinel + +.SH Synopsis + /*sentinel*/() = default; \fB(1)\fP (since C++23) + constexpr /*sentinel*/( /*sentinel*/ i ) + + requires Const && + (std::convertible_to< \fB(2)\fP (since C++23) + ranges::sentinel_t, + + ranges::sentinel_t>> && + ...); + + Constructs a sentinel. + + 1) Default constructor. Value-initializes the underlying tuple of sentinels end_. + 2) Conversion from /*sentinel*/ to /*sentinel*/. Move constructs the + underlying tuple of sentinels end_ with std::move(i.end_). + +.SH Parameters + + i - a /*sentinel*/ + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ranges::zip_view::size.3 b/man/std::ranges::zip_view::size.3 new file mode 100644 index 000000000..2834fd877 --- /dev/null +++ b/man/std::ranges::zip_view::size.3 @@ -0,0 +1,66 @@ +.TH std::ranges::zip_view::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::size \- std::ranges::zip_view::size + +.SH Synopsis + constexpr auto size() \fB(1)\fP (since C++23) + requires (ranges::sized_range && ...); + constexpr auto size() const \fB(2)\fP (since C++23) + requires (ranges::sized_range && ...); + + Returns the number of elements in the zip_view. Provided only if each underlying + (adapted) range satisfies sized_range. + + Equivalent to: + + return std::apply + ( + [](auto... sizes) + { + using CT = /*make-unsigned-like-t*/>; + return ranges::min({CT(sizes)...}); + }, + /*tuple-transform*/(ranges::size, views_) + ); + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements, which is the minimum size among all sizes of adapted views. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto x = std::vector{1, 2, 3, 4, 5}; + auto y = std::deque{'a', 'b', 'c'}; + auto z = std::forward_list{1., 2.}; + + auto v1 = std::views::zip(x, y); + assert(v1.size() == std::min(x.size(), y.size())); + assert(v1.size() == 3); + + [[maybe_unused]] auto v2 = std::views::zip(x, z); + // auto sz = v2.size(); // Error, v2 does not have size(): + static_assert(not std::ranges::sized_range); + } + +.SH See also + + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::ranges::zip_view::zip_view.3 b/man/std::ranges::zip_view::zip_view.3 new file mode 100644 index 000000000..4817f5469 --- /dev/null +++ b/man/std::ranges::zip_view::zip_view.3 @@ -0,0 +1,25 @@ +.TH std::ranges::zip_view::zip_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ranges::zip_view::zip_view \- std::ranges::zip_view::zip_view + +.SH Synopsis + zip_view() = default; \fB(1)\fP (since C++23) + constexpr zip_view( Views... views ); \fB(2)\fP (since C++23) + + 1) Default constructor. Value-initializes all adapted view objects. + The default constructor is deleted if std::is_default_constructible_v is false for + at least one type in Views.... + 2) Move constructs every adapted view object from the corresponding view in + views.... + +.SH Parameters + + views - view objects to adapt + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::rank.3 b/man/std::rank.3 index 2e55499a5..6313fca80 100644 --- a/man/std::rank.3 +++ b/man/std::rank.3 @@ -1,4 +1,7 @@ -.TH std::rank 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rank 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rank \- std::rank + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -7,6 +10,10 @@ If T is an array type, provides the member constant value equal to the number of dimensions of the array. For any other type, value is 0. + If the program adds specializations for std::rank + or std::rank_v + \fI(since C++17)\fP, the behavior is undefined. + .SH Member constants value the number of dimensions of T or zero @@ -16,6 +23,8 @@ operator std::size_t converts the object to std::size_t, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,42 +35,45 @@ .SH Possible implementation template - struct rank : std::integral_constant {}; - + struct rank : public std::integral_constant {}; + template struct rank : public std::integral_constant::value + 1> {}; - - template + + template struct rank : public std::integral_constant::value + 1> {}; .SH Example - + // Run this code - #include #include - + int main() { - std::cout << std::rank::value << '\\n'; - std::cout << std::rank::value << '\\n'; - std::cout << std::rank::value << '\\n'; + static_assert( + std::rank{} == 0 + && std::rank{} == 1 + && std::rank{} == 2 + && std::rank{} == 3 ); + + [[maybe_unused]] int ary[][3] = {{1, 2, 3}}; + // The reason of rank of "ary[0]" is calculated as 0 + static_assert(std::rank_v == 0); + // is that rank cannot deal with reference type. i.e. int(&)[3] + static_assert(std::is_same_v); + // The solution is to remove reference type + static_assert(std::rank_v> == 1); } -.SH Output: - - 3 - 4 - 0 - .SH See also is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP extent obtains the size of an array type along a specified dimension - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_extent removes one extent from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_all_extents removes all extents from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::ratio.3 b/man/std::ratio.3 index 7736df9c0..f47d7e038 100644 --- a/man/std::ratio.3 +++ b/man/std::ratio.3 @@ -1,4 +1,7 @@ -.TH std::ratio 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio \- std::ratio + .SH Synopsis Defined in header template< @@ -11,50 +14,71 @@ The class template std::ratio provides compile-time rational arithmetic support. Each instantiation of this template exactly represents any finite rational number as long as its numerator Num and denominator Denom are representable as compile-time - constants of type std::intmax_t. In addition, Denom may not be zero and may not be - equal to the most negative value. Both numerator and denominator are automatically - reduced to the lowest terms. + constants of type std::intmax_t. In addition, Denom may not be zero and both Num and + Denom may not be equal to the most negative value. + + The static data members num and den representing the numerator and denominator are + calculated by dividing Num and Denom by their greatest common divisor. However, two + std::ratio with different Num or Denom are distinct types even if they represent the + same rational number (after reduction). A std::ratio type can be reduced to the + lowest terms via its type member: std::ratio<3, 6>::type is std::ratio<1, 2>. - Several convenience typedefs that correspond to the SI ratios are provided by the - standard library: + The following convenience typedefs that correspond to the SI ratios are provided by + the standard library: Defined in header - Type Definition - yocto std::ratio<1, 1000000000000000000000000>, if std::intmax_t can represent the - denominator - zepto std::ratio<1, 1000000000000000000000>, if std::intmax_t can represent the - denominator - atto std::ratio<1, 1000000000000000000> - femto std::ratio<1, 1000000000000000> - pico std::ratio<1, 1000000000000> - nano std::ratio<1, 1000000000> - micro std::ratio<1, 1000000> - milli std::ratio<1, 1000> - centi std::ratio<1, 100> - deci std::ratio<1, 10> - deca std::ratio<10, 1> - hecto std::ratio<100, 1> - kilo std::ratio<1000, 1> - mega std::ratio<1000000, 1> - giga std::ratio<1000000000, 1> - tera std::ratio<1000000000000, 1> - peta std::ratio<1000000000000000, 1> - exa std::ratio<1000000000000000000, 1> - zetta std::ratio<1000000000000000000000, 1>, if std::intmax_t can represent the - numerator - yotta std::ratio<1000000000000000000000000, 1>, if std::intmax_t can represent the - numerator - -.SH Member types - - Member type Definition - type std::ratio - -.SH Member objects - - constexpr intmax_t num constexpr value of type std::intmax_t equal to sign(Num) * - \fB[static]\fP sign(Denom) * abs(Num) / gcd(Num, Denom) - \fI(public static member constant)\fP - constexpr intmax_t den constexpr value of type std::intmax_t equal to abs(Denom) / - \fB[static]\fP gcd(Num, Denom) - \fI(public static member constant)\fP + Type Definition + quecto (since C++26) std::ratio<1, 1000000000000000000000000000000> (10^-30)^[1] + ronto (since C++26) std::ratio<1, 1000000000000000000000000000> (10^-27)^[1] + yocto std::ratio<1, 1000000000000000000000000> (10^-24)^[1] + zepto std::ratio<1, 1000000000000000000000> (10^-21)^[1] + atto std::ratio<1, 1000000000000000000> (10^-18) + femto std::ratio<1, 1000000000000000> (10^-15) + pico std::ratio<1, 1000000000000> (10^-12) + nano std::ratio<1, 1000000000> (10^-9) + micro std::ratio<1, 1000000> (10^-6) + milli std::ratio<1, 1000> (10^-3) + centi std::ratio<1, 100> (10^-2) + deci std::ratio<1, 10> (10^-1) + deca std::ratio<10, 1> (10^1) + hecto std::ratio<100, 1> (10^2) + kilo std::ratio<1000, 1> (10^3) + mega std::ratio<1000000, 1> (10^6) + giga std::ratio<1000000000, 1> (10^9) + tera std::ratio<1000000000000, 1> (10^12) + peta std::ratio<1000000000000000, 1> (10^15) + exa std::ratio<1000000000000000000, 1> (10^18) + zetta std::ratio<1000000000000000000000, 1> (10^21)^[2] + yotta std::ratio<1000000000000000000000000, 1> (10^24)^[2] + ronna (since C++26) std::ratio<1000000000000000000000000000, 1> (10^27)^[2] + quetta (since C++26) std::ratio<1000000000000000000000000000000, 1> (10^30)^[2] + + 1. ↑ ^1.0 ^1.1 ^1.2 ^1.3 These typedefs are only defined if std::intmax_t can + represent the denominator. + 2. ↑ ^2.0 ^2.1 ^2.2 ^2.3 These typedefs are only defined if std::intmax_t can + represent the numerator. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_ratio 202306L (C++26) Adding the new 2022 SI prefixes: quecto, quetta, + ronto, ronna + +.SH Example + + +// Run this code + + #include + + static_assert + ( + std::ratio_equal_v, std::kilo> + ); + + int main() {} + +.SH See also + + Mathematical constants (C++20) provides several mathematical constants, such as + std::numbers::e for e diff --git a/man/std::ratio_add.3 b/man/std::ratio_add.3 index f2a1eb675..0d33494ab 100644 --- a/man/std::ratio_add.3 +++ b/man/std::ratio_add.3 @@ -1,44 +1,52 @@ -.TH std::ratio_add 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_add 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_add \- std::ratio_add + .SH Synopsis Defined in header - template< class R1, class R2 > - using ratio_add = /* unspecified */; + template< class R1, class R2 > \fI(since C++11)\fP + using ratio_add = /* see below */; - The template alias std::ratio_add denotes the result of adding two exact rational - fractions represented by the std::ratio instances R1 and R2. The result a std::ratio - instance std::ratio where Num == R1::num * R2::den + R2::num * R1::den - and Denom == R1::den * R2::den. + The alias template std::ratio_add denotes the result of adding two exact rational + fractions represented by the std::ratio specializations R1 and R2. -.SH Member types + The result is a std::ratio specialization std::ratio, such that given Num == + R1::num * R2::den + R2::num * R1::den and Denom == R1::den * R2::den (computed + without arithmetic overflow), U is std::ratio::num and V is + std::ratio::den. - Member type Definition - type std::ratio +.SH Notes -.SH Member constants + If U or V is not representable in std::intmax_t, the program is ill-formed. If Num + or Denom is not representable in std::intmax_t, the program is ill-formed unless the + implementation yields correct values for U and V. - num constexpr value of type std::intmax_t equal to sign(Num) * sign(Denom) * - \fB[static]\fP abs(Num) / gcd(Num, Denom) - \fI(public static member constant)\fP - den constexpr value of type std::intmax_t equal to abs(Denom) / gcd(Num, Denom) - \fB[static]\fP \fI(public static member constant)\fP + The above definition requires that the result of std::ratio_add be already + reduced to lowest terms; for example, std::ratio_add, std::ratio<1, + 6>> is the same type as std::ratio<1, 2>. .SH Example - + // Run this code #include #include - + int main() { - typedef std::ratio<2, 3> two_third; - typedef std::ratio<1, 6> one_sixth; - - typedef std::ratio_add sum; + using two_third = std::ratio<2, 3>; + using one_sixth = std::ratio<1, 6>; + using sum = std::ratio_add; + std::cout << "2/3 + 1/6 = " << sum::num << '/' << sum::den << '\\n'; } .SH Output: 2/3 + 1/6 = 5/6 + +.SH See also + + ratio_subtract subtracts two ratio objects at compile-time + \fI(C++11)\fP (alias template) diff --git a/man/std::ratio_divide.3 b/man/std::ratio_divide.3 index 6af5d4a34..c5eef8bd4 100644 --- a/man/std::ratio_divide.3 +++ b/man/std::ratio_divide.3 @@ -1,43 +1,51 @@ -.TH std::ratio_divide 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_divide 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_divide \- std::ratio_divide + .SH Synopsis Defined in header - template< class R1, class R2 > - using ratio_divide = /* unspecified */; + template< class R1, class R2 > \fI(since C++11)\fP + using ratio_divide = /* see below */; - The template alias std::ratio_divide denotes the result of dividing two exact - rational fractions represented by the std::ratio instances R1 and R2. The result a - std::ratio instance std::ratio where Num == R1::num * R2::den and Denom - == R1::den * R2::num. + The alias template std::ratio_divide denotes the result of dividing two exact + rational fractions represented by the std::ratio specializations R1 and R2. -.SH Member types + The result is a std::ratio specialization std::ratio, such that given Num == + R1::num * R2::den and Denom == R1::den * R2::num (computed without arithmetic + overflow), U is std::ratio::num and V is std::ratio::den. - Member type Definition - type std::ratio +.SH Notes -.SH Member constants + If U or V is not representable in std::intmax_t, the program is ill-formed. If Num + or Denom is not representable in std::intmax_t, the program is ill-formed unless the + implementation yields correct values for U and V. - num constexpr value of type std::intmax_t equal to sign(Num) * sign(Denom) * - \fB[static]\fP abs(Num) / gcd(Num, Denom) - \fI(public static member constant)\fP - den constexpr value of type std::intmax_t equal to abs(Denom) / gcd(Num, Denom) - \fB[static]\fP \fI(public static member constant)\fP + The above definition requires that the result of std::ratio_divide be + already reduced to lowest terms; for example, std::ratio_divide, + std::ratio<1, 6>> is the same type as std::ratio<1, 2>. .SH Example - + // Run this code #include #include - + int main() { - typedef std::ratio<2, 3> two_third; - typedef std::ratio<1, 6> one_sixth; - typedef std::ratio_divide r; - std::cout << "2/3 / 1/6 = " << r::num << '/' << r::den << '\\n'; + using two_third = std::ratio<2, 3>; + using one_sixth = std::ratio<1, 6>; + using quotient = std::ratio_divide; + static_assert(std::ratio_equal_v>); + std::cout << "(2/3) / (1/6) = " << quotient::num << '/' << quotient::den << '\\n'; } .SH Output: - 2/3 / 1/6 = 4/1 + (2/3) / (1/6) = 4/1 + +.SH See also + + ratio_multiply multiplies two ratio objects at compile-time + \fI(C++11)\fP (alias template) diff --git a/man/std::ratio_equal.3 b/man/std::ratio_equal.3 index 43d61b71c..2611fd3e1 100644 --- a/man/std::ratio_equal.3 +++ b/man/std::ratio_equal.3 @@ -1,21 +1,27 @@ -.TH std::ratio_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_equal \- std::ratio_equal + .SH Synopsis Defined in header template< class R1, class R2 > - struct ratio_equal : std::integral_constant; + struct ratio_equal : std::integral_constant { \fI(since C++11)\fP + }; If the ratios R1 and R2 are equal, provides the member constant value equal true. Otherwise, value is false. .SH Member constants - value true if R1::num == R2::num && R1::den == R2::den , false otherwise + value true if R1::num == R2::num && R1::den == R2::den, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -33,21 +39,25 @@ .SH Example - + // Run this code #include #include - + int main() { - if(std::ratio_equal, std::ratio<4,6>>::value) { - std::cout << "2/3 == 4/6\\n"; - } else { - std::cout << "2/3 != 4/6\\n"; - } + constexpr bool equ = std::ratio_equal_v, + std::ratio<4,6>>; + static_assert(equ == true); + std::cout << "2/3 " << (equ ? "==" : "!=") << " 4/6\\n"; } .SH Output: 2/3 == 4/6 + +.SH See also + + ratio_not_equal compares two ratio objects for inequality at compile-time + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::ratio_greater.3 b/man/std::ratio_greater.3 index 49f6e44d3..994b83bc4 100644 --- a/man/std::ratio_greater.3 +++ b/man/std::ratio_greater.3 @@ -1,22 +1,28 @@ -.TH std::ratio_greater 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_greater 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_greater \- std::ratio_greater + .SH Synopsis Defined in header template< class R1, class R2 > - struct ratio_greater : std::integral_constant; + struct ratio_greater : std::integral_constant \fI(since C++11)\fP + { }; - If the ratio R1 is greater than than the ratio R2, provides the member constant - value equal true. Otherwise, value is false. + If the ratio R1 is greater than the ratio R2, provides the member constant value + equal true. Otherwise, value is false. .SH Member constants value true if R1::num * R2::den > R2::num * R1::den, or equivalent expression - \fB[static]\fP that avoids overflow , false otherwise + \fB[static]\fP that avoids overflow, false otherwise \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,9 +32,34 @@ .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + + int main() + { + static_assert(std::ratio_greater, std::ratio<1, 2>>::value, + "3/4 > 1/2"); + + if (std::ratio_greater, std::ratio<10, 11>>::value) + std::cout << "11/12 > 10/11" "\\n"; + + // Since C++17 + static_assert(std::ratio_greater_v, std::ratio<11, 12>>); + + if constexpr (std::ratio_greater_v, std::ratio<11, 12>>) + std::cout << "12/13 > 11/12" "\\n"; + } + +.SH Output: + + 11/12 > 10/11 + 12/13 > 11/12 + +.SH See also - * Todo no example + ratio_greater_equal compares two ratio objects for greater than or equal to at + \fI(C++11)\fP compile-time + \fI(class template)\fP diff --git a/man/std::ratio_greater_equal.3 b/man/std::ratio_greater_equal.3 index 2fdfc41bf..d8df770ee 100644 --- a/man/std::ratio_greater_equal.3 +++ b/man/std::ratio_greater_equal.3 @@ -1,8 +1,12 @@ -.TH std::ratio_greater_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_greater_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_greater_equal \- std::ratio_greater_equal + .SH Synopsis Defined in header template< class R1, class R2 > - struct ratio_greater_equal : std::integral_constant; + struct ratio_greater_equal : std::integral_constant { }; If the ratio R1 is greater than or equal to the ratio R2, provides the member constant value equal true. Otherwise, value is false. @@ -10,13 +14,15 @@ .SH Member constants value true if R1::num * R2::den >= R2::num * R1::den, or equivalent expression - \fB[static]\fP that avoids overflow , false otherwise + \fB[static]\fP that avoids overflow, false otherwise \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,9 +32,52 @@ .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + + int main() + { + static_assert(std::ratio_greater_equal< + std::ratio<2, 3>, + std::ratio<2, 3>>::value, "2/3 >= 2/3"); + + if (std::ratio_greater_equal< + std::ratio<2,1>, std::ratio<1, 2>>::value) + std::cout << "2/1 >= 1/2" "\\n"; + + if (std::ratio_greater_equal< + std::ratio<1,2>, std::ratio<1, 2>>::value) + std::cout << "1/2 >= 1/2" "\\n"; + + // Since C++17 + static_assert(std::ratio_greater_equal_v< + std::ratio<999'999, 1'000'000>, + std::ratio<999'998, 999'999>> ); + + if constexpr (std::ratio_greater_equal_v< + std::ratio<999'999, 1'000'000>, + std::ratio<999'998, 999'999>>) + std::cout << "999'999/1'000'000 >= 999'998/999'999" "\\n"; + + if constexpr (std::ratio_greater_equal_v< + std::ratio<999'999, 1'000'000>, + std::ratio<999'999, 1'000'000>>) + std::cout << "999'999/1'000'000 >= 999'999/1'000'000" "\\n"; + } + +.SH Output: + + 2/1 >= 1/2 + 1/2 >= 1/2 + 999'999/1'000'000 >= 999'998/999'999 + 999'999/1'000'000 >= 999'999/1'000'000 + +.SH See also - * Todo no example + ratio_equal compares two ratio objects for equality at compile-time + \fI(C++11)\fP \fI(class template)\fP + ratio_less compares two ratio objects for less than at compile-time + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::ratio_less.3 b/man/std::ratio_less.3 index 605a29a5b..bc7db88f2 100644 --- a/man/std::ratio_less.3 +++ b/man/std::ratio_less.3 @@ -1,8 +1,12 @@ -.TH std::ratio_less 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_less 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_less \- std::ratio_less + .SH Synopsis Defined in header template< class R1, class R2 > - struct ratio_less : std::integral_constant; + struct ratio_less : std::integral_constant { \fI(since C++11)\fP + }; If the ratio R1 is less than the ratio R2, provides the member constant value equal true. Otherwise, value is false. @@ -10,13 +14,15 @@ .SH Member constants value true if R1::num * R2::den < R2::num * R1::den, or equivalent expression - \fB[static]\fP that avoids overflow , false otherwise + \fB[static]\fP that avoids overflow, false otherwise \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,19 +32,27 @@ .SH Example - + // Run this code #include #include - + int main() { - if (std::ratio_less, std::ratio<57,90>>::value) { - std::cout << "23/37 < 57/90\\n"; - } + using x = std::ratio<69, 90>; + using y = std::ratio<70, 90>; + + if constexpr (std::ratio_less_v) + std::cout << x::num << '/' << x::den << " < " + << y::num << '/' << y::den << '\\n'; } .SH Output: - 23/37 < 57/90 + 23/30 < 7/9 + +.SH See also + + ratio_greater compares two ratio objects for greater than at compile-time + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::ratio_less_equal.3 b/man/std::ratio_less_equal.3 index 53bfc0ebc..7725cae87 100644 --- a/man/std::ratio_less_equal.3 +++ b/man/std::ratio_less_equal.3 @@ -1,8 +1,12 @@ -.TH std::ratio_less_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_less_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_less_equal \- std::ratio_less_equal + .SH Synopsis Defined in header template< class R1, class R2 > - struct ratio_less_equal : std::integral_constant; + struct ratio_less_equal : std::integral_constant { }; If the ratio R1 is less than or equal to the ratio R2, provides the member constant value equal true. Otherwise, value is false. @@ -10,13 +14,15 @@ .SH Member constants value true if R1::num * R2::den <= R2::num * R1::den, or equivalent expression - \fB[static]\fP that avoids overflow , false otherwise + \fB[static]\fP that avoids overflow, false otherwise \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -26,9 +32,34 @@ .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + + int main() + { + static_assert(std::ratio_less_equal, std::ratio<3, 4>>::value, + "1/2 <= 3/4"); + + if (std::ratio_less_equal, std::ratio<11,12>>::value) + std::cout << "10/11 <= 11/12" "\\n"; + + static_assert(std::ratio_less_equal_v, std::ratio<11, 12>>); + + if constexpr (std::ratio_less_equal_v, std::ratio<11, 12>>) + std::cout << "11/12 <= 12/13" "\\n"; + } + +.SH Output: + + 10/11 <= 11/12 + 11/12 <= 12/13 + +.SH See also - * Todo no example + ratio_equal compares two ratio objects for equality at compile-time + \fI(C++11)\fP \fI(class template)\fP + ratio_not_equal compares two ratio objects for inequality at compile-time + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::ratio_multiply.3 b/man/std::ratio_multiply.3 index 0bf2fcb9b..d58a612bc 100644 --- a/man/std::ratio_multiply.3 +++ b/man/std::ratio_multiply.3 @@ -1,43 +1,51 @@ -.TH std::ratio_multiply 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_multiply 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_multiply \- std::ratio_multiply + .SH Synopsis Defined in header - template< class R1, class R2 > - using ratio_multiply = /* unspecified */; + template< class R1, class R2 > \fI(since C++11)\fP + using ratio_multiply = /* see below */; - The template alias std::ratio_multiply denotes the result of multiplying two exact - rational fractions represented by the std::ratio instances R1 and R2. The result a - std::ratio instance std::ratio where Num == R1::num * R2::num and Denom - == R1::den * R2::den. + The alias template std::ratio_multiply denotes the result of multiplying two exact + rational fractions represented by the std::ratio specializations R1 and R2. -.SH Member types + The result is a std::ratio specialization std::ratio, such that given Num == + R1::num * R2::num and Denom == R1::den * R2::den (computed without arithmetic + overflow), U is std::ratio::num and V is std::ratio::den. - Member type Definition - type std::ratio +.SH Notes -.SH Member constants + If U or V is not representable in std::intmax_t, the program is ill-formed. If Num + or Denom is not representable in std::intmax_t, the program is ill-formed unless the + implementation yields correct values for U and V. - num constexpr value of type std::intmax_t equal to sign(Num) * sign(Denom) * - \fB[static]\fP abs(Num) / gcd(Num, Denom) - \fI(public static member constant)\fP - den constexpr value of type std::intmax_t equal to abs(Denom) / gcd(Num, Denom) - \fB[static]\fP \fI(public static member constant)\fP + The above definition requires that the result of std::ratio_multiply be + already reduced to lowest terms; for example, std::ratio_multiply, + std::ratio<4, 5>> is the same type as std::ratio<2, 15>. .SH Example - + // Run this code #include #include - + int main() { - typedef std::ratio<2, 3> two_third; - typedef std::ratio<1, 6> one_sixth; - typedef std::ratio_multiply r; - std::cout << "2/3 * 1/6 = " << r::num << '/' << r::den << '\\n'; + using two_third = std::ratio<2, 3>; + using one_sixth = std::ratio<1, 6>; + using product = std::ratio_multiply; + static_assert(std::ratio_equal_v>); + std::cout << "2/3 * 1/6 = " << product::num << '/' << product::den << '\\n'; } .SH Output: 2/3 * 1/6 = 1/9 + +.SH See also + + ratio_divide divides two ratio objects at compile-time + \fI(C++11)\fP (alias template) diff --git a/man/std::ratio_not_equal.3 b/man/std::ratio_not_equal.3 index e3708dcaa..59c5e4de9 100644 --- a/man/std::ratio_not_equal.3 +++ b/man/std::ratio_not_equal.3 @@ -1,21 +1,27 @@ -.TH std::ratio_not_equal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_not_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_not_equal \- std::ratio_not_equal + .SH Synopsis Defined in header template< class R1, class R2 > - struct ratio_not_equal : std::integral_constant; + struct ratio_not_equal : std::integral_constant { }; If the ratios R1 and R2 are not equal, provides the member constant value equal true. Otherwise, value is false. .SH Member constants - value true if R1::num != R2::num || R1::den != R2::den , false otherwise + value true if R1::num != R2::num || R1::den != R2::den, false otherwise \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -33,21 +39,24 @@ .SH Example - + // Run this code #include #include - + int main() { - if(std::ratio_not_equal, std::ratio<1,3>>::value) { - std::cout << "2/3 != 1/3\\n"; - } else { - std::cout << "2/3 == 1/3\\n"; - } + std::ratio_not_equal_v, std::ratio<1, 3>> + ? std::cout << "2/3 != 1/3\\n" + : std::cout << "2/3 == 1/3\\n"; } .SH Output: 2/3 != 1/3 + +.SH See also + + ratio_equal compares two ratio objects for equality at compile-time + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::ratio_subtract.3 b/man/std::ratio_subtract.3 index d7255e05d..fdcc26137 100644 --- a/man/std::ratio_subtract.3 +++ b/man/std::ratio_subtract.3 @@ -1,44 +1,53 @@ -.TH std::ratio_subtract 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ratio_subtract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ratio_subtract \- std::ratio_subtract + .SH Synopsis Defined in header - template< class R1, class R2 > - using ratio_subtract = /* unspecified */; + template< class R1, class R2 > \fI(since C++11)\fP + using ratio_subtract = /* see below */; - The template alias std::ratio_subtract denotes the result of subtracting two exact - rational fractions represented by the std::ratio instances R1 and R2. The result a - std::ratio instance std::ratio where Num == R1::num * R2::den - R2::num - * R1::den and Denom == R1::den * R2::den. + The alias template std::ratio_subtract denotes the result of subtracting two exact + rational fractions represented by the std::ratio specializations R1 and R2. -.SH Member types + The result is a std::ratio specialization std::ratio, such that given Num == + R1::num * R2::den - R2::num * R1::den and Denom == R1::den * R2::den (computed + without arithmetic overflow), U is std::ratio::num and V is + std::ratio::den. - Member type Definition - type std::ratio +.SH Notes -.SH Member constants + If U or V is not representable in std::intmax_t, the program is ill-formed. If Num + or Denom is not representable in std::intmax_t, the program is ill-formed unless the + implementation yields correct values for U and V. - num constexpr value of type std::intmax_t equal to sign(Num) * sign(Denom) * - \fB[static]\fP abs(Num) / gcd(Num, Denom) - \fI(public static member constant)\fP - den constexpr value of type std::intmax_t equal to abs(Denom) / gcd(Num, Denom) - \fB[static]\fP \fI(public static member constant)\fP + The above definition requires that the result of std::ratio_subtract be + already reduced to lowest terms; for example, std::ratio_subtract, + std::ratio<1, 6>> is the same type as std::ratio<1, 3>. .SH Example - + // Run this code #include #include - + int main() { - typedef std::ratio<2, 3> two_third; - typedef std::ratio<1, 6> one_sixth; - - typedef std::ratio_subtract diff; + using two_third = std::ratio<2, 3>; + using one_sixth = std::ratio<1, 6>; + using diff = std::ratio_subtract; + static_assert(std::ratio_equal_v>); + std::cout << "2/3 - 1/6 = " << diff::num << '/' << diff::den << '\\n'; } .SH Output: 2/3 - 1/6 = 1/2 + +.SH See also + + ratio_add adds two ratio objects at compile-time + \fI(C++11)\fP (alias template) diff --git a/man/std::raw_storage_iterator.3 b/man/std::raw_storage_iterator.3 index 4f019c3d0..25196ede0 100644 --- a/man/std::raw_storage_iterator.3 +++ b/man/std::raw_storage_iterator.3 @@ -1,70 +1,91 @@ -.TH std::raw_storage_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::raw_storage_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raw_storage_iterator \- std::raw_storage_iterator + .SH Synopsis Defined in header template< class OutputIt, class T > - class raw_storage_iterator + class raw_storage_iterator \fI(until C++17)\fP - : public std::iterator; + : public std::iterator; + template< class OutputIt, class T > \fI(since C++17)\fP + class raw_storage_iterator; (deprecated in C++17) + (removed in C++20) The output iterator std::raw_storage_iterator makes it possible for standard algorithms to store results in uninitialized memory. Whenever the algorithm writes an object of type T to the dereferenced iterator, the object is copy-constructed into the location in the uninitialized storage pointed to by the iterator. The - template parameter OutputIt is any type that meets thee requirements of - OutputIterator and has operator* defined to return an object, for which operator& - returns an object of type T*. Usually, the type T* is used as OutputIt. + template parameter OutputIt is any type that meets the requirements of + LegacyOutputIterator and has operator* defined to return an object, for which + operator& returns an object of type T*. Usually, the type T* is used as OutputIt. .SH Type requirements - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. .SH Member functions constructor creates a new raw_storage_iterator - \fI(public member function)\fP - operator= copy-constructs an object at the pointed-to location in the buffer - \fI(public member function)\fP + \fI(public member function)\fP + operator= constructs an object at the pointed-to location in the buffer + \fI(public member function)\fP operator* dereferences the iterator - \fI(public member function)\fP + \fI(public member function)\fP operator++ advances the iterator - operator++(int) \fI(public member function)\fP - -Inherited from std::iterator + operator++(int) \fI(public member function)\fP + base provides access to the wrapped iterator + \fI(since C++17)\fP \fI(public member function)\fP .SH Member types Member type Definition + iterator_category std::output_iterator_tag value_type void - difference_type void + difference_type void \fI(until C++20)\fP + std::ptrdiff_t \fI(since C++20)\fP pointer void reference void - iterator_category std::output_iterator_tag + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. + +.SH Note + + std::raw_storage_iterator was deprecated primarily because of its exception-unsafe + behavior. Unlike std::uninitialized_copy, it doesn't handle exceptions during + operations like std::copy safely, potentially leading to resource leaks due to a + lack of tracking the number of successfully constructed objects and their proper + destruction in the presence of exceptions. .SH Example - + // Run this code + #include #include - #include #include - #include - + #include + int main() { const std::string s[] = {"This", "is", "a", "test", "."}; - std::string* p = std::get_temporary_buffer(5).first; - + std::string* p = std::allocator().allocate(5); + std::copy(std::begin(s), std::end(s), std::raw_storage_iterator(p)); - - for(std::string* i = p; i!=p+5; ++i) { + + for (std::string* i = p; i != p + 5; ++i) + { std::cout << *i << '\\n'; i->~basic_string(); } - std::return_temporary_buffer(p); + std::allocator().deallocate(p, 5); } .SH Output: @@ -78,9 +99,9 @@ Inherited from std::iterator .SH See also allocator_traits provides information about allocator types - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP scoped_allocator_adaptor implements multi-level allocator for multi-level containers - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP uses_allocator checks if the specified type supports uses-allocator \fI(C++11)\fP construction - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::raw_storage_iterator::base.3 b/man/std::raw_storage_iterator::base.3 new file mode 100644 index 000000000..8a868a4b3 --- /dev/null +++ b/man/std::raw_storage_iterator::base.3 @@ -0,0 +1,17 @@ +.TH std::raw_storage_iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raw_storage_iterator::base \- std::raw_storage_iterator::base + +.SH Synopsis + OutputIt base() const; \fI(since C++17)\fP + + Provides access to the iterator passed in the constructor of this + raw_storage_iterator. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An iterator pointing at the same object as *this. diff --git a/man/std::raw_storage_iterator::operator*.3 b/man/std::raw_storage_iterator::operator*.3 index 10c2abe16..9e39cc080 100644 --- a/man/std::raw_storage_iterator::operator*.3 +++ b/man/std::raw_storage_iterator::operator*.3 @@ -1,4 +1,7 @@ -.TH std::raw_storage_iterator::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::raw_storage_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raw_storage_iterator::operator* \- std::raw_storage_iterator::operator* + .SH Synopsis raw_storage_iterator& operator*(); diff --git a/man/std::raw_storage_iterator::operator++,operator++(int).3 b/man/std::raw_storage_iterator::operator++,operator++(int).3 index a88a7d042..eb9364de4 100644 --- a/man/std::raw_storage_iterator::operator++,operator++(int).3 +++ b/man/std::raw_storage_iterator::operator++,operator++(int).3 @@ -1,7 +1,10 @@ -.TH std::raw_storage_iterator::operator++,operator++(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::raw_storage_iterator::operator++,operator++(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raw_storage_iterator::operator++,operator++(int) \- std::raw_storage_iterator::operator++,operator++(int) + .SH Synopsis raw_storage_iterator& operator++(); - raw_storage_iterator operator++(int); + raw_storage_iterator operator++( int ); Advances the iterator. diff --git a/man/std::raw_storage_iterator::operator=.3 b/man/std::raw_storage_iterator::operator=.3 index 4ccee2b04..7cbfa6ad7 100644 --- a/man/std::raw_storage_iterator::operator=.3 +++ b/man/std::raw_storage_iterator::operator=.3 @@ -1,12 +1,17 @@ -.TH std::raw_storage_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::raw_storage_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raw_storage_iterator::operator= \- std::raw_storage_iterator::operator= + .SH Synopsis - raw_storage_iterator& operator=( const T& el ); + raw_storage_iterator& operator=( const T& el ); \fB(1)\fP + raw_storage_iterator& operator=( T&& el ); \fB(2)\fP \fI(since C++17)\fP - Constructs a value at the location the iterator points to from el. + 1) Constructs a value at the location the iterator points to from el. + 2) Constructs a value at the location the iterator points to from std::move(el). .SH Parameters - el - the value to copy + el - the value to copy or move from .SH Return value diff --git a/man/std::raw_storage_iterator::raw_storage_iterator.3 b/man/std::raw_storage_iterator::raw_storage_iterator.3 index 2b0a3065d..1b6dbc2d0 100644 --- a/man/std::raw_storage_iterator::raw_storage_iterator.3 +++ b/man/std::raw_storage_iterator::raw_storage_iterator.3 @@ -1,4 +1,7 @@ -.TH std::raw_storage_iterator::raw_storage_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::raw_storage_iterator::raw_storage_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::raw_storage_iterator::raw_storage_iterator \- std::raw_storage_iterator::raw_storage_iterator + .SH Synopsis explicit raw_storage_iterator( OutputIt it ); diff --git a/man/std::rbegin(std::initializer_list).3 b/man/std::rbegin(std::initializer_list).3 deleted file mode 100644 index e589ee2cc..000000000 --- a/man/std::rbegin(std::initializer_list).3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH std::rbegin(std::initializer_list) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template - std::reverse_iterator rbegin( std::initializer_list il \fI(since C++14)\fP - ); - - The overload of std::rbegin for initializer_list returns an std::reverse_iterator - pointing at the last element of il. - -.SH Parameters - - il - an initializer_list - -.SH Return value - - std::reverse_iterator(il.end()). - -.SH Exceptions - - \fI(none)\fP - -.SH Notes - - This overload is necessary because std::initializer_list does not have a member - function rbegin. No overload is needed for std::crbegin because it is implemented in - terms of std::rbegin. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - rbegin returns a reverse iterator to a container or array - crbegin \fI(function)\fP - \fI(C++14)\fP - rend returns a reverse end iterator for a container or array - crend \fI(function)\fP - \fI(C++14)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::rbegin,std::crbegin.3 b/man/std::rbegin,std::crbegin.3 new file mode 100644 index 000000000..5a847360b --- /dev/null +++ b/man/std::rbegin,std::crbegin.3 @@ -0,0 +1,157 @@ +.TH std::rbegin,std::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rbegin,std::crbegin \- std::rbegin,std::crbegin + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + template< class C > (since + auto rbegin( C& c ) -> C++14) + decltype(c.rbegin()); (until + C++17) + template< class C > (since + constexpr auto rbegin( C& c ) -> C++17) + decltype(c.rbegin()); + template< class C > (since + auto rbegin( const C& c ) -> C++14) + decltype(c.rbegin()); (until + C++17) + template< class C > (since + constexpr auto rbegin( const C& c ) C++17) + -> decltype(c.rbegin()); + template< class T, std::size_t N > (since + std::reverse_iterator rbegin( T C++14) + (&array)[N] ); (until + C++17) + template< class T, std::size_t N > (since + constexpr std::reverse_iterator \fB(1)\fP C++17) + rbegin( T (&array)[N] ); + template< class T > (since + std::reverse_iterator \fB(2)\fP C++14) + rbegin( std::initializer_list il (until + ); C++17) + template< class T > + \fB(3)\fP + constexpr (since + std::reverse_iterator C++17) + \fB(4)\fP + rbegin( std::initializer_list + il ); + template< class C > (since + auto crbegin( const C& c ) -> C++14) + decltype(std::rbegin(c)); (until + \fB(5)\fP C++17) + template< class C > (since + constexpr auto crbegin( const C& c ) C++17) + -> decltype(std::rbegin(c)); + + Returns an iterator to the reverse-beginning of the given range. + + 1,2) Returns c.begin(), which is typically an iterator to the beginning of the + sequence represented by c. + 1) If C is a standard Container, returns a C::reverse_iterator object. + 2) If C is a standard Container, returns a C::const_reverse_iterator object. + 3) Returns a std::reverse_iterator object to the reverse-beginning of array. + 4) Returns a std::reverse_iterator object to the reverse-beginning of il. + 5) Returns std::rbegin(c), with c always treated as const-qualified. + If C is a standard Container, returns a C::const_reverse_iterator object. + + range-rbegin-rend.svg + +.SH Parameters + + c - a container or view with a rbegin member function + array - an array of arbitrary type + il - an std::initializer_list + +.SH Return value + + 1,2) c.rbegin() + 3) std::reverse_iterator(array + N) + 4) std::reverse_iterator(il.end()) + 5) c.rbegin() + +.SH Exceptions + + May throw implementation-defined exceptions. + + Overloads + + Custom overloads of rbegin may be provided for classes and enumerations that do not + expose a suitable rbegin() member function, yet can be iterated. + + Overloads of rbegin found by argument-dependent lookup can be used to + customize the behavior of std::ranges::rbegin and \fI(since C++20)\fP + std::ranges::crbegin. + +.SH Notes + + The overload for std::initializer_list is necessary because it does not have a + member function rbegin. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector v = {3, 1, 4}; + auto vi = std::rbegin(v); // the type of “vi” is std::vector::reverse_iterator + std::cout << "*vi = " << *vi << '\\n'; + + *std::rbegin(v) = 42; // OK: after assignment v[2] == 42 + // *std::crbegin(v) = 13; // error: the location is read-only + + int a[] = {-5, 10, 15}; + auto ai = std::rbegin(a); // the type of “ai” is std::reverse_iterator + std::cout << "*ai = " << *ai << '\\n'; + + auto il = {3, 1, 4}; + // the type of “it” below is std::reverse_iterator: + for (auto it = std::rbegin(il); it != std::rend(il); ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + } + +.SH Output: + + *vi = 4 + *ai = 15 + 4 1 3 + +.SH See also + + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP + ranges::rbegin returns a reverse iterator to a range + (C++20) (customization point object) + ranges::crbegin returns a reverse iterator to a read-only range + (C++20) (customization point object) diff --git a/man/std::rbegin.3 b/man/std::rbegin.3 deleted file mode 100644 index 3a9bac963..000000000 --- a/man/std::rbegin.3 +++ /dev/null @@ -1,85 +0,0 @@ -.TH std::rbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class C > \fB(1)\fP \fI(since C++14)\fP - auto rbegin( C& c ) -> decltype(c.rbegin()); - template< class C > \fB(1)\fP \fI(since C++14)\fP - auto rbegin( const C& c ) -> decltype(c.rbegin()); - template< class T, size_t N > \fB(2)\fP \fI(since C++14)\fP - reverse_iterator rbegin( T (&array)[N] ); - template< class C > \fB(3)\fP \fI(since C++14)\fP - auto crbegin( const C& c ) -> decltype(std::rbegin(c)); - - Returns an iterator to the reverse-beginning of the given container c or array - array. - - 1) Returns a possibly const-qualified iterator to the reverse-beginning of the - container c. - 2) Returns std::reverse_iterator to the reverse-beginning of the array array. - 3) Returns a const-qualified iterator to the reverse-beginning of the container c. - - range-rbegin-rend.svg - -.SH Parameters - - c - a container with a rbegin method - array - an array of arbitrary type - -.SH Return value - - An iterator to the reverse-beginning of c or array - -.SH Notes - - In addition to being included in , std::rbegin is guaranteed to become - available if any of the following headers are included: , , - , , , , , , , - , and . - -.SH Specializations - - Custom specializations of std::rbegin may be provided for classes that do not expose - a suitable rbegin() member function, yet can be iterated. The following - specialization is already provided by the standard library: - - rbegin(std::initializer_list) specializes std::rbegin - \fI(C++14)\fP \fI(function)\fP - -.SH Example - - -// Run this code - - #include - #include - #include - - int main() - { - std::vector v = { 3, 1, 4 }; - auto vi = std::rbegin(v); - std::cout << *vi << '\\n'; - - int a[] = { -5, 10, 15 }; - auto ai = std::rbegin(a); - std::cout << *ai << '\\n'; - } - -.SH Output: - - 4 - 15 - -.SH See also - - begin - cbegin returns an iterator to the beginning of a container or array - \fI(C++11)\fP \fI(function)\fP - \fI(C++14)\fP - end - cend returns an iterator to the end of a container or array - \fI(C++11)\fP \fI(function)\fP - \fI(C++14)\fP - rend returns a reverse end iterator for a container or array - crend \fI(function)\fP - \fI(C++14)\fP diff --git a/man/std::real(std::complex).3 b/man/std::real(std::complex).3 index f31e5e881..1fa9cc39d 100644 --- a/man/std::real(std::complex).3 +++ b/man/std::real(std::complex).3 @@ -1,34 +1,74 @@ -.TH std::real(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::real(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::real(std::complex) \- std::real(std::complex) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(until C++14)\fP - T real( const complex& z ); - template< class T > \fB(1)\fP \fI(since C++14)\fP - constexpr T real( const complex& z ); - long double real( long double z ); \fB(2)\fP \fI(since C++11)\fP - template< class DoubleOrIngeter > \fB(3)\fP \fI(since C++11)\fP - double real( DoubleOrInteger z ); - float real( float z ); \fB(4)\fP \fI(since C++11)\fP + template< class T > + T real( const std::complex& z \fI(until C++14)\fP + ); + template< class T > + constexpr T real( const \fI(since C++14)\fP + std::complex& z ); + Additional overloads \fI(since C++11)\fP + Defined in header + float real( float f ); + + double real( double f ); \fI(until C++14)\fP + + long double real( long double f ); + constexpr float real( float + f ); \fB(1)\fP - Returns the real component of the complex number z, i.e. z.real(). + constexpr double real( double \fI(since C++14)\fP + f ); (until C++23) + (A) + constexpr long double real( long + double f ); + template< class FloatingPoint > + constexpr FloatingPoint real( (since C++23) + FloatingPoint f ); + template< class Integer > \fI(until C++14)\fP + double real( Integer i ); + template< class Integer > (B) + constexpr double real( Integer i \fI(since C++14)\fP + ); - Additional overloads are provided for float, double, long double, and all integer - types, which are treated as complex numbers with zero imaginary component. - \fI(since C++11)\fP + 1) Returns the real part of the complex number z, i.e. z.real(). + + A,B) Additional overloads are provided for all integer and + floating-point types, which are treated as complex numbers with zero \fI(since C++11)\fP + imaginary part. .SH Parameters z - complex value + f - floating-point value + i - integer value .SH Return value - the real component of z + 1) The real part of z. + A) f. + B) static_cast(i). + +.SH Notes + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num: + + * If num has a + standard + (until C++23) floating-point type T, then std::real(num) has the same effect as + std::real(std::complex(num)). + * Otherwise, if num has an integer type, then std::real(num) has the same effect + as std::real(std::complex(num)). .SH See also real accesses the real part of the complex number - \fI(public member function)\fP - imag accesses the imaginary part of the complex number - \fI(public member function)\fP - imag returns the imaginary component - \fI(function template)\fP + \fI(public member function)\fP + imag returns the imaginary part + \fI(function template)\fP + C documentation for + creal diff --git a/man/std::realloc.3 b/man/std::realloc.3 index 18c743c8a..4290d9d9f 100644 --- a/man/std::realloc.3 +++ b/man/std::realloc.3 @@ -1,11 +1,14 @@ -.TH std::realloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::realloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::realloc \- std::realloc + .SH Synopsis Defined in header void* realloc( void* ptr, std::size_t new_size ); - Reallocates the given area of memory. It must be previously allocated by - std::malloc(), std::calloc() or std::realloc() and not yet freed with std::free(), - otherwise, the results are undefined. + Reallocates the given area of memory (implicitly creating objects in the destination + area). It must be previously allocated by std::malloc, std::calloc or std::realloc + and not yet freed with std::free, otherwise, the results are undefined. The reallocation is done by either: @@ -15,20 +18,29 @@ b) allocating a new memory block of size new_size bytes, copying memory area with size equal the lesser of the new and the old sizes, and freeing the old block. - If there is not enough memory, the old memory block is not freed and null-pointer is + If there is not enough memory, the old memory block is not freed and null pointer is returned. - If ptr is NULL, the behavior is the same as calling std::malloc(new_size). + If ptr is a null pointer, the behavior is the same as calling std::malloc(new_size). - If new_size is zero, the behavior is implementation defined (null pointer may be - returned, or some non-null pointer may be returned that may not be used to access - storage). + If new_size is zero, the behavior is implementation defined: null pointer may be + returned (in which case the old memory block may or may not be freed) or some + non-null pointer may be returned that may not be used to access storage. + Such usage is deprecated (via C DR 400). + \fI(since C++20)\fP -.SH Notes + The following functions are required to be thread-safe: - Because reallocation may involve bytewise copying (regardless of whether it's to - expand or to contract), only the objects of TriviallyCopyable types are safe to - access in the preserved part of the memory block after a call to realloc. + * The library versions of operator new and operator delete + * User replacement versions of global operator new and operator + delete + * std::calloc, std::malloc, std::realloc \fI(since C++11)\fP + , std::aligned_alloc + \fI(since C++17)\fP, std::free + + Calls to these functions that allocate or deallocate a particular unit + of storage occur in a single total order, and each such deallocation + call happens-before the next allocation (if any) in this order. .SH Parameters @@ -37,19 +49,82 @@ .SH Return value - Pointer to the beginning of newly allocated memory or NULL if error has occurred. - The pointer must be deallocated with std::free(). + On success, returns a pointer to the beginning of newly allocated memory. To avoid a + memory leak, the returned pointer must be deallocated with std::free or + std::realloc. The original pointer ptr is invalidated and any access to it is + undefined behavior (even if reallocation was in-place). + + On failure, returns a null pointer. The original pointer ptr remains valid and may + need to be deallocated with std::free. + +.SH Notes + + Because reallocation may involve bytewise copying (regardless of whether it expands + or contracts the area), it is necessary (but not sufficient) for those objects to be + of TriviallyCopyable type. + + Some non-standard libraries define a type trait "BitwiseMovable" or "Relocatable", + which describes a type that does not have: + + * external references (e.g. nodes of a list or a tree that holds reference to + another element), and + * internal references (e.g. member pointer which might hold the address of another + member). + + Objects of such type can be accessed after their storage is reallocated even if + their copy constructors are not trivial. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + class MallocDynamicBuffer + { + char* p; + public: + explicit MallocDynamicBuffer(std::size_t initial = 0) : p(nullptr) + { + resize(initial); + } + + ~MallocDynamicBuffer() { std::free(p); } + + void resize(std::size_t newSize) + { + if (newSize == 0) // this check is not strictly needed, + { + std::free(p); // but zero-size realloc is deprecated in C + p = nullptr; + } + else + { + if (void* mem = std::realloc(p, newSize)) + p = static_cast(mem); + else + throw std::bad_alloc(); + } + } + + char& operator[](size_t n) { return p[n]; } + char operator[](size_t n) const { return p[n]; } + }; + + int main() + { + MallocDynamicBuffer buf1(1024); + buf1[5] = 'f'; + buf1.resize(10); // shrink + assert(buf1[5] == 'f'); + buf1.resize(1024); // grow + assert(buf1[5] == 'f'); + } .SH See also C documentation for realloc - -.SH Category: - - * Todo no example diff --git a/man/std::recursive_mutex.3 b/man/std::recursive_mutex.3 index 310a6e7e8..b6a6c251c 100644 --- a/man/std::recursive_mutex.3 +++ b/man/std::recursive_mutex.3 @@ -1,4 +1,7 @@ -.TH std::recursive_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex \- std::recursive_mutex + .SH Synopsis Defined in header class recursive_mutex; \fI(since C++11)\fP @@ -20,29 +23,83 @@ calls to try_lock will return false. The behavior of a program is undefined if a recursive_mutex is destroyed while still - owned by some thread. The recursive_mutex class satisfies all requiremenets of Mutex + owned by some thread. The recursive_mutex class satisfies all requirements of Mutex and StandardLayoutType. .SH Member types - Member type Definition - native_handle_type implementation-defined + Member type Definition + native_handle_type (optional*) implementation-defined .SH Member functions constructor constructs the mutex - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys the mutex - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP .SH Locking lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Native handle - native_handle returns the underlying implementation-defined thread handle - \fI(public member function)\fP + native_handle returns the underlying implementation-defined native handle object + \fI(public member function)\fP + +.SH Example + + One use case for recursive_mutex is protecting shared state in a class whose member + functions may call each other. + + +// Run this code + + #include + #include + #include + + class X + { + std::recursive_mutex m; + std::string shared; + public: + void fun1() + { + std::lock_guard lk(m); + shared = "fun1"; + std::cout << "in fun1, shared variable is now " << shared << '\\n'; + } + void fun2() + { + std::lock_guard lk(m); + shared = "fun2"; + std::cout << "in fun2, shared variable is now " << shared << '\\n'; + fun1(); // recursive lock becomes useful here + std::cout << "back in fun2, shared variable is " << shared << '\\n'; + } + }; + + int main() + { + X x; + std::thread t1(&X::fun1, &x); + std::thread t2(&X::fun2, &x); + t1.join(); + t2.join(); + } + +.SH Possible output: + + in fun1, shared variable is now fun1 + in fun2, shared variable is now fun2 + in fun1, shared variable is now fun1 + back in fun2, shared variable is fun1 + +.SH See also + + mutex provides basic mutual exclusion facility + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::recursive_mutex::lock.3 b/man/std::recursive_mutex::lock.3 index 36398dd5b..0e8a369b6 100644 --- a/man/std::recursive_mutex::lock.3 +++ b/man/std::recursive_mutex::lock.3 @@ -1,4 +1,7 @@ -.TH std::recursive_mutex::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex::lock \- std::recursive_mutex::lock + .SH Synopsis void lock(); \fI(since C++11)\fP @@ -11,7 +14,7 @@ The maximum number of levels of ownership is unspecified. An exception of type std::system_error will be thrown if this number is exceeded. - Prior unlock() operation on the same mutex synchronizes-with (as defined in + Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation. .SH Parameters @@ -30,56 +33,60 @@ .SH Notes - lock() is usually not called directly: std::unique_lock and std::lock_guard are used - to manage exclusive locking. + lock() is usually not called directly: std::unique_lock, std::scoped_lock, and + std::lock_guard are used to manage exclusive locking. .SH Example This example shows how lock and unlock can be used to protect shared data. - + // Run this code - #include #include - #include + #include #include - - int g_num = 0; // protected by g_num_mutex + #include + + int g_num = 0; // protected by g_num_mutex std::mutex g_num_mutex; - + void slow_increment(int id) { - for (int i = 0; i < 3; ++i) { + for (int i = 0; i < 3; ++i) + { g_num_mutex.lock(); ++g_num; - std::cout << id << " => " << g_num << '\\n'; + // note, that the mutex also syncronizes the output + std::cout << "id: " << id << ", g_num: " << g_num << '\\n'; g_num_mutex.unlock(); - - std::this_thread::sleep_for(std::chrono::seconds(1)); + + std::this_thread::sleep_for(std::chrono::milliseconds(234)); } } - + int main() { - std::thread t1(slow_increment, 0); - std::thread t2(slow_increment, 1); + std::thread t1{slow_increment, 0}; + std::thread t2{slow_increment, 1}; t1.join(); t2.join(); } .SH Possible output: - 0 => 1 - 1 => 2 - 0 => 3 - 1 => 4 - 0 => 5 - 1 => 6 + id: 0, g_num: 1 + id: 1, g_num: 2 + id: 1, g_num: 3 + id: 0, g_num: 4 + id: 0, g_num: 5 + id: 1, g_num: 6 .SH See also try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_lock diff --git a/man/std::recursive_mutex::native_handle.3 b/man/std::recursive_mutex::native_handle.3 index d68a67e9b..e8bc3b757 100644 --- a/man/std::recursive_mutex::native_handle.3 +++ b/man/std::recursive_mutex::native_handle.3 @@ -1,6 +1,10 @@ -.TH std::recursive_mutex::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex::native_handle \- std::recursive_mutex::native_handle + .SH Synopsis native_handle_type native_handle(); \fI(since C++11)\fP + (not always present) Returns the underlying implementation-defined native handle object. @@ -14,14 +18,12 @@ .SH Exceptions - This section is incomplete + Implementation-defined. .SH Example This section is incomplete Reason: no example - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::recursive_mutex::recursive_mutex.3 b/man/std::recursive_mutex::recursive_mutex.3 index 4c9b96cfe..e459ba5bc 100644 --- a/man/std::recursive_mutex::recursive_mutex.3 +++ b/man/std::recursive_mutex::recursive_mutex.3 @@ -1,4 +1,7 @@ -.TH std::recursive_mutex::recursive_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex::recursive_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex::recursive_mutex \- std::recursive_mutex::recursive_mutex + .SH Synopsis recursive_mutex(); \fB(1)\fP \fI(since C++11)\fP recursive_mutex( const recursive_mutex& ) = delete; \fB(2)\fP \fI(since C++11)\fP @@ -13,3 +16,8 @@ .SH Exceptions std::system_error if the construction is unsuccessful. + +.SH See also + + C documentation for + mtx_init diff --git a/man/std::recursive_mutex::try_lock.3 b/man/std::recursive_mutex::try_lock.3 index 8ebd6c808..d14cd8e64 100644 --- a/man/std::recursive_mutex::try_lock.3 +++ b/man/std::recursive_mutex::try_lock.3 @@ -1,6 +1,9 @@ -.TH std::recursive_mutex::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex::try_lock \- std::recursive_mutex::try_lock + .SH Synopsis - bool try_lock(); \fI(since C++11)\fP + bool try_lock() noexcept; \fI(since C++11)\fP Tries to lock the mutex. Returns immediately. On successful lock acquisition returns true, otherwise returns false. @@ -9,7 +12,7 @@ not currently locked by any other thread. A thread may call try_lock on a recursive mutex repeatedly. Successful calls to - try_lock increment the ownsership count: the mutex will only be released after the + try_lock increment the ownership count: the mutex will only be released after the thread makes a matching number of calls to unlock. The maximum number of levels of ownership is unspecified. A call to try_lock will @@ -29,44 +32,51 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example - - + + // Run this code #include #include - + int main() { - std::mutex test; - if (test.try_lock()==true) { - std::cout << "lock acquired" << std::endl; - test.unlock(); //now unlock the mutex - } else { - std::cout << "lock not acquired" << std::endl; + std::recursive_mutex test; + if (test.try_lock()) + { + std::cout << "lock acquired\\n"; + test.unlock(); } - - test.lock(); //to lock it again - if (test.try_lock()) { //true can be left out - std::cout << "lock acquired" << std::endl; - } else { - std::cout << "lock not acquired" << std::endl; + else + std::cout << "lock not acquired\\n"; + + test.lock(); + // non-recursive mutex would return false from try_lock now + if (test.try_lock()) + { + std::cout << "lock acquired\\n"; + test.unlock(); } + else + std::cout << "lock not acquired\\n"; + test.unlock(); } .SH Output: lock acquired - lock not acquired + lock acquired .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_trylock diff --git a/man/std::recursive_mutex::unlock.3 b/man/std::recursive_mutex::unlock.3 index 591fa9725..22e21c4ac 100644 --- a/man/std::recursive_mutex::unlock.3 +++ b/man/std::recursive_mutex::unlock.3 @@ -1,4 +1,7 @@ -.TH std::recursive_mutex::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex::unlock \- std::recursive_mutex::unlock + .SH Synopsis void unlock(); \fI(since C++11)\fP @@ -22,7 +25,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes @@ -37,10 +40,11 @@ .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_unlock .SH Category: - * Todo no example diff --git a/man/std::recursive_mutex::~recursive_mutex.3 b/man/std::recursive_mutex::~recursive_mutex.3 index f2640730c..e181e09fa 100644 --- a/man/std::recursive_mutex::~recursive_mutex.3 +++ b/man/std::recursive_mutex::~recursive_mutex.3 @@ -1,4 +1,7 @@ -.TH std::recursive_mutex::~recursive_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_mutex::~recursive_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_mutex::~recursive_mutex \- std::recursive_mutex::~recursive_mutex + .SH Synopsis ~recursive_mutex(); @@ -6,3 +9,8 @@ The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex. + +.SH See also + + C documentation for + mtx_destroy diff --git a/man/std::recursive_timed_mutex.3 b/man/std::recursive_timed_mutex.3 index 25e73f297..e82a0b2e0 100644 --- a/man/std::recursive_timed_mutex.3 +++ b/man/std::recursive_timed_mutex.3 @@ -1,4 +1,7 @@ -.TH std::recursive_timed_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex \- std::recursive_timed_mutex + .SH Synopsis Defined in header class recursive_timed_mutex; \fI(since C++11)\fP @@ -6,40 +9,40 @@ The recursive_timed_mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. - In a manner similar to std::thread::recursive_mutex, recursive_timed_mutex provides + In a manner similar to std::recursive_mutex, recursive_timed_mutex provides exclusive, recursive ownership semantics. In addition, recursive_timed_mutex provides the ability to attempt to claim ownership of a recursive_timed_mutex with a - timeout via the try_lock_for and try_lock_until methods. + timeout via the try_lock_for and try_lock_until member functions. The recursive_timed_mutex class satisfies all requirements of TimedMutex and StandardLayoutType. .SH Member types - Member type Definition - native_handle_type implementation-defined + Member type Definition + native_handle_type (optional*) implementation-defined .SH Member functions constructor constructs the mutex - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys the mutex - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP .SH Locking lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Native handle - native_handle returns the underlying implementation-defined thread handle - \fI(public member function)\fP + native_handle returns the underlying implementation-defined native handle object + \fI(public member function)\fP diff --git a/man/std::recursive_timed_mutex::lock.3 b/man/std::recursive_timed_mutex::lock.3 index 2ab7635fb..038cef679 100644 --- a/man/std::recursive_timed_mutex::lock.3 +++ b/man/std::recursive_timed_mutex::lock.3 @@ -1,4 +1,7 @@ -.TH std::recursive_timed_mutex::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::lock \- std::recursive_timed_mutex::lock + .SH Synopsis void lock(); \fI(since C++11)\fP @@ -11,7 +14,7 @@ The maximum number of levels of ownership is unspecified. An exception of type std::system_error will be thrown if this number is exceeded. - Prior unlock() operation on the same mutex synchronizes-with (as defined in + Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation. .SH Parameters @@ -30,62 +33,66 @@ .SH Notes - lock() is usually not called directly: std::unique_lock and std::lock_guard are used - to manage exclusive locking. + lock() is usually not called directly: std::unique_lock, std::scoped_lock, and + std::lock_guard are used to manage exclusive locking. .SH Example This example shows how lock and unlock can be used to protect shared data. - + // Run this code - #include #include - #include + #include #include - - int g_num = 0; // protected by g_num_mutex + #include + + int g_num = 0; // protected by g_num_mutex std::mutex g_num_mutex; - + void slow_increment(int id) { - for (int i = 0; i < 3; ++i) { + for (int i = 0; i < 3; ++i) + { g_num_mutex.lock(); ++g_num; - std::cout << id << " => " << g_num << '\\n'; + // note, that the mutex also syncronizes the output + std::cout << "id: " << id << ", g_num: " << g_num << '\\n'; g_num_mutex.unlock(); - - std::this_thread::sleep_for(std::chrono::seconds(1)); + + std::this_thread::sleep_for(std::chrono::milliseconds(234)); } } - + int main() { - std::thread t1(slow_increment, 0); - std::thread t2(slow_increment, 1); + std::thread t1{slow_increment, 0}; + std::thread t2{slow_increment, 1}; t1.join(); t2.join(); } .SH Possible output: - 0 => 1 - 1 => 2 - 0 => 3 - 1 => 4 - 0 => 5 - 1 => 6 + id: 0, g_num: 1 + id: 1, g_num: 2 + id: 1, g_num: 3 + id: 0, g_num: 4 + id: 0, g_num: 5 + id: 1, g_num: 6 .SH See also try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_lock diff --git a/man/std::recursive_timed_mutex::native_handle.3 b/man/std::recursive_timed_mutex::native_handle.3 index bfb238835..75e11d68f 100644 --- a/man/std::recursive_timed_mutex::native_handle.3 +++ b/man/std::recursive_timed_mutex::native_handle.3 @@ -1,6 +1,10 @@ -.TH std::recursive_timed_mutex::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::native_handle \- std::recursive_timed_mutex::native_handle + .SH Synopsis native_handle_type native_handle(); \fI(since C++11)\fP + (not always present) Returns the underlying implementation-defined native handle object. @@ -14,14 +18,12 @@ .SH Exceptions - This section is incomplete + Implementation-defined. .SH Example This section is incomplete Reason: no example - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::recursive_timed_mutex::recursive_timed_mutex.3 b/man/std::recursive_timed_mutex::recursive_timed_mutex.3 index f303b31f1..75d273201 100644 --- a/man/std::recursive_timed_mutex::recursive_timed_mutex.3 +++ b/man/std::recursive_timed_mutex::recursive_timed_mutex.3 @@ -1,4 +1,7 @@ -.TH std::recursive_timed_mutex::recursive_timed_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::recursive_timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::recursive_timed_mutex \- std::recursive_timed_mutex::recursive_timed_mutex + .SH Synopsis recursive_timed_mutex(); \fB(1)\fP \fI(since C++11)\fP recursive_timed_mutex( const recursive_timed_mutex& ) = delete; \fB(2)\fP \fI(since C++11)\fP @@ -13,3 +16,8 @@ .SH Exceptions std::system_error if the construction is unsuccessful. + +.SH See also + + C documentation for + mtx_init diff --git a/man/std::recursive_timed_mutex::try_lock.3 b/man/std::recursive_timed_mutex::try_lock.3 index a99a1c714..4c8636b3c 100644 --- a/man/std::recursive_timed_mutex::try_lock.3 +++ b/man/std::recursive_timed_mutex::try_lock.3 @@ -1,6 +1,9 @@ -.TH std::recursive_timed_mutex::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::try_lock \- std::recursive_timed_mutex::try_lock + .SH Synopsis - bool try_lock(); \fI(since C++11)\fP + bool try_lock() noexcept; \fI(since C++11)\fP Tries to lock the mutex. Returns immediately. On successful lock acquisition returns true, otherwise returns false. @@ -9,7 +12,7 @@ not currently locked by any other thread. A thread may call try_lock on a recursive mutex repeatedly. Successful calls to - try_lock increment the ownsership count: the mutex will only be released after the + try_lock increment the ownership count: the mutex will only be released after the thread makes a matching number of calls to unlock. The maximum number of levels of ownership is unspecified. A call to try_lock will @@ -29,11 +32,11 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example - + This section is incomplete Reason: no example @@ -41,16 +44,17 @@ .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_trylock .SH Category: - * Todo no example diff --git a/man/std::recursive_timed_mutex::try_lock_for.3 b/man/std::recursive_timed_mutex::try_lock_for.3 index 10a5b9e5f..8fe15e515 100644 --- a/man/std::recursive_timed_mutex::try_lock_for.3 +++ b/man/std::recursive_timed_mutex::try_lock_for.3 @@ -1,18 +1,25 @@ -.TH std::recursive_timed_mutex::try_lock_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::try_lock_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::try_lock_for \- std::recursive_timed_mutex::try_lock_for + .SH Synopsis template< class Rep, class Period > - bool try_lock_for( const std::chrono::duration& \fI(since C++11)\fP + bool try_lock_for( const std::chrono::duration& \fI(since C++11)\fP timeout_duration ); - Tries to lock the mutex. Blocks until specified timeout_duration has elapsed or the - lock is acquired, whichever comes first. On successful lock acquisition returns - true, otherwise returns false. + Tries to lock the mutex. Blocks until the specified duration timeout_duration has + elapsed (timeout) or the lock is acquired (owns the mutex), whichever comes first. + On successful lock acquisition returns true, otherwise returns false. If timeout_duration is less or equal timeout_duration.zero(), the function behaves like try_lock(). - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. + + The standard recommends that a std::steady_clock is used to measure the duration. If + an implementation uses a std::system_clock instead, the wait time may also be + sensitive to clock adjustments. As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point during @@ -23,14 +30,14 @@ A thread may call try_lock_for on a recursive mutex repeatedly. Successful calls to try_lock_for increment the ownership count: the mutex will only be released after - the thread makes a matching number of calls to unlock. + the thread makes a matching number of calls to unlock(). The maximum number of levels of ownership is unspecified. A call to try_lock_for will return false if this number is exceeded. .SH Parameters - timeout_duration - maximum duration to block for + timeout_duration - minimum duration to block for .SH Return value @@ -38,53 +45,56 @@ .SH Exceptions - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + Any exception thrown by timeout_duration (durations provided by the standard library + never throw). .SH Example - + // Run this code + #include #include #include + #include #include #include - #include - + + using namespace std::chrono_literals; + std::mutex cout_mutex; // control access to std::cout std::timed_mutex mutex; - + void job(int id) { - using Ms = std::chrono::milliseconds; std::ostringstream stream; - - for (int i = 0; i < 3; ++i) { - if (mutex.try_lock_for(Ms(100))) { + + for (int i = 0; i < 3; ++i) + { + if (mutex.try_lock_for(100ms)) + { stream << "success "; - std::this_thread::sleep_for(Ms(100)); + std::this_thread::sleep_for(100ms); mutex.unlock(); - } else { - stream << "failed "; } - std::this_thread::sleep_for(Ms(100)); + else + stream << "failed "; + + std::this_thread::sleep_for(100ms); } - - std::lock_guard lock(cout_mutex); - std::cout << "[" << id << "] " << stream.str() << "\\n"; + + std::lock_guard lock{cout_mutex}; + std::cout << '[' << id << "] " << stream.str() << '\\n'; } - + int main() { std::vector threads; - for (int i = 0; i < 4; ++i) { + for (int i{0}; i < 4; ++i) threads.emplace_back(job, i); - } - - for (auto& i: threads) { - i.join(); - } + + for (auto& th : threads) + th.join(); } .SH Possible output: @@ -94,14 +104,22 @@ [2] failed success failed [1] success failed success + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 try_lock_for threw nothing throws timeout-related exceptions + .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::recursive_timed_mutex::try_lock_until.3 b/man/std::recursive_timed_mutex::try_lock_until.3 index a3464e8ec..d6bb5244d 100644 --- a/man/std::recursive_timed_mutex::try_lock_until.3 +++ b/man/std::recursive_timed_mutex::try_lock_until.3 @@ -1,21 +1,28 @@ -.TH std::recursive_timed_mutex::try_lock_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::try_lock_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::try_lock_until \- std::recursive_timed_mutex::try_lock_until + .SH Synopsis template< class Clock, class Duration > - bool try_lock_until( const std::chrono::time_point& \fI(since C++11)\fP + bool try_lock_until( const std::chrono::time_point& \fI(since C++11)\fP timeout_time ); - Tries to lock the mutex. Blocks until specified timeout_time has been reached or the - lock is acquired, whichever comes first. On successful lock acquisition returns - true, otherwise returns false. + Tries to lock the mutex. Blocks until specified timeout_time has been reached + (timeout) or the lock is acquired (owns the mutex), whichever comes first. On + successful lock acquisition returns true, otherwise returns false. If timeout_time has already passed, this function behaves like try_lock(). - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might, but might - not, be less or more than timeout_time - Clock::now() at the time of the call, - depending on the direction of the adjustment. The function also may block for longer - than until after timeout_time has been reached due to scheduling or resource - contention delays. + Clock must meet the Clock requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP + + The standard recommends that the clock tied to timeout_time be used, in which case + adjustments of the clock may be taken into account. Thus, the duration of the block + might be more or less than timeout_time - Clock::now() at the time of the call, + depending on the direction of the adjustment and whether it is honored by the + implementation. The function also may block until after timeout_time has been + reached due to process scheduling or resource contention delays. As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point before @@ -41,45 +48,35 @@ .SH Exceptions - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + Any exception thrown by timeout_time (clocks, time points, and durations provided by + the standard library never throw). .SH Example - This example shows a 10 seconds block - - -// Run this code - - #include - #include - #include - #include - - std::recursive_timed_mutex test_mutex; - - void f() - { - auto now=std::chrono::steady_clock::now(); - test_mutex.try_lock_until(now + std::chrono::seconds(10)); - std::cout << "hello world\\n"; - } - - int main() - { - std::lock_guard l(test_mutex); - std::thread t(f); - t.join(); - } + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 try_lock_until threw nothing throws timeout-related exceptions .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_timedlock + +.SH Category: + * Todo no example diff --git a/man/std::recursive_timed_mutex::unlock.3 b/man/std::recursive_timed_mutex::unlock.3 index 1c0111834..797e71fd3 100644 --- a/man/std::recursive_timed_mutex::unlock.3 +++ b/man/std::recursive_timed_mutex::unlock.3 @@ -1,4 +1,7 @@ -.TH std::recursive_timed_mutex::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::unlock \- std::recursive_timed_mutex::unlock + .SH Synopsis void unlock(); \fI(since C++11)\fP @@ -22,7 +25,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes @@ -37,16 +40,17 @@ .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_unlock .SH Category: - * Todo no example diff --git a/man/std::recursive_timed_mutex::~recursive_timed_mutex.3 b/man/std::recursive_timed_mutex::~recursive_timed_mutex.3 index 7cecb3104..769ae6354 100644 --- a/man/std::recursive_timed_mutex::~recursive_timed_mutex.3 +++ b/man/std::recursive_timed_mutex::~recursive_timed_mutex.3 @@ -1,4 +1,7 @@ -.TH std::recursive_timed_mutex::~recursive_timed_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::recursive_timed_mutex::~recursive_timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::recursive_timed_mutex::~recursive_timed_mutex \- std::recursive_timed_mutex::~recursive_timed_mutex + .SH Synopsis ~recursive_timed_mutex(); @@ -6,3 +9,8 @@ The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex. + +.SH See also + + C documentation for + mtx_destroy diff --git a/man/std::reduce.3 b/man/std::reduce.3 new file mode 100644 index 000000000..903b141f0 --- /dev/null +++ b/man/std::reduce.3 @@ -0,0 +1,207 @@ +.TH std::reduce 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reduce \- std::reduce + +.SH Synopsis + Defined in header + template< class InputIt > + \fI(since C++17)\fP + typename std::iterator_traits::value_type \fB(1)\fP (constexpr since + C++20) + reduce( InputIt first, InputIt last ); + template< class ExecutionPolicy, class ForwardIt > + + typename std::iterator_traits::value_type \fB(2)\fP \fI(since C++17)\fP + reduce( ExecutionPolicy&& policy, + + ForwardIt first, ForwardIt last ); + template< class InputIt, class T > \fI(since C++17)\fP + T reduce( InputIt first, InputIt last, T init ); \fB(3)\fP (constexpr since + C++20) + template< class ExecutionPolicy, class ForwardIt, class T > + + T reduce( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, T init ); + template< class InputIt, class T, class BinaryOp > \fI(since C++17)\fP + T reduce( InputIt first, InputIt last, T init, BinaryOp op ); \fB(5)\fP (constexpr since + C++20) + template< class ExecutionPolicy, + + class ForwardIt, class T, class BinaryOp > + T reduce( ExecutionPolicy&& policy, \fB(6)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, T init, BinaryOp op + ); + + 1) Equivalent to reduce(first, last, typename + std::iterator_traits::value_type{}). + 3) Equivalent to reduce(first, last, init, std::plus<>()). + 5) Reduces the range [first, last), possibly permuted and aggregated in unspecified + manner, along with the initial value init over op. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + Given binary_op as the actual binary operation: + + * The result is non-deterministic if the binary_op is not associative or not + commutative (such as floating-point addition). + * If any of the following values is not convertible to T, the program is + ill-formed: + + * binary_op(init, *first) + * binary_op(*first, init) + * binary_op(init, init) + * binary_op(*first, *first) + * If any of the following conditions is satisfied, the behavior is undefined: + + * T is not MoveConstructible. + * binary_op modifies any element of [first, last). + * binary_op invalidates any iterator or subrange of [first, last]. + +.SH Parameters + + first, last - the range of elements to apply the algorithm to + init - the initial value of the generalized sum + policy - the execution policy to use. See execution policy for details. + binary FunctionObject that will be applied in unspecified order to the + op - result of dereferencing the input iterators, the results of other op + and init. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + +.SH Return value + + 1-4) The generalized sum of init and the elements of [first, last) over + std::plus<>(). + 5,6) The generalized sum of init and the elements of [first, last) over op. + + The generalized sum of a group of elements over an binary operation binary_op is + defined as follows: + + * If the group only has one element, the sum is the value of the element. + * Otherwise, performs the following operations in order: + 1. Takes any two elements elem1 and elem2 from the group. + 2. Calculates binary_op(elem1, elem2) and puts the result back to the group. + 3. Repeats steps 1 and 2 until there is only one element in the group. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1-4) \\(\\scriptsize O(N)\\)O(N) applications of std::plus<>(). + 5,6) \\(\\scriptsize O(N)\\)O(N) applications of op. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + std::reduce behaves like std::accumulate except the elements of the range may be + grouped and rearranged in arbitrary order. + +.SH Example + + side-by-side comparison between std::reduce and std::accumulate: + + +// Run this code + + #if PARALLEL + #include + #define SEQ std::execution::seq, + #define PAR std::execution::par, + #else + #define SEQ + #define PAR + #endif + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::fixed << std::setprecision(1); + + auto eval = [](auto fun) + { + const auto t1 = std::chrono::high_resolution_clock::now(); + const auto [name, result] = fun(); + const auto t2 = std::chrono::high_resolution_clock::now(); + const std::chrono::duration ms = t2 - t1; + std::cout << std::setw(28) << std::left << name << "sum: " + << result << '\\t' << "time: " << ms.count() << " ms\\n"; + }; + + { + const std::vector v(100'000'007, 0.1); + + eval([&v]{ return std::pair{"std::accumulate (double)", + std::accumulate(v.cbegin(), v.cend(), 0.0)}; }); + eval([&v]{ return std::pair{"std::reduce (seq, double)", + std::reduce(SEQ v.cbegin(), v.cend())}; }); + eval([&v]{ return std::pair{"std::reduce (par, double)", + std::reduce(PAR v.cbegin(), v.cend())}; }); + } + + { + const std::vector v(100'000'007, 1); + + eval([&v]{ return std::pair{"std::accumulate (long)", + std::accumulate(v.cbegin(), v.cend(), 0l)}; }); + eval([&v]{ return std::pair{"std::reduce (seq, long)", + std::reduce(SEQ v.cbegin(), v.cend())}; }); + eval([&v]{ return std::pair{"std::reduce (par, long)", + std::reduce(PAR v.cbegin(), v.cend())}; }); + } + } + +.SH Possible output: + + // POSIX: g++ -std=c++23 ./example.cpp -ltbb -O3; ./a.out + std::accumulate (double) sum: 10,000,000.7 time: 356.9 ms + std::reduce (seq, double) sum: 10,000,000.7 time: 140.1 ms + std::reduce (par, double) sum: 10,000,000.7 time: 140.1 ms + std::accumulate (long) sum: 100,000,007 time: 46.0 ms + std::reduce (seq, long) sum: 100,000,007 time: 67.3 ms + std::reduce (par, long) sum: 100,000,007 time: 63.3 ms + + // POSIX: g++ -std=c++23 ./example.cpp -ltbb -O3 -DPARALLEL; ./a.out + std::accumulate (double) sum: 10,000,000.7 time: 353.4 ms + std::reduce (seq, double) sum: 10,000,000.7 time: 140.7 ms + std::reduce (par, double) sum: 10,000,000.7 time: 24.7 ms + std::accumulate (long) sum: 100,000,007 time: 42.4 ms + std::reduce (seq, long) sum: 100,000,007 time: 52.0 ms + std::reduce (par, long) sum: 100,000,007 time: 23.1 ms + +.SH See also + + accumulate sums up or folds a range of elements + \fI(function template)\fP + applies a function to a range of elements, storing results in a + transform destination range + \fI(function template)\fP + transform_reduce applies an invocable, then reduces out of order + \fI(C++17)\fP \fI(function template)\fP + ranges::fold_left left-folds a range of elements + (C++23) (niebloid) diff --git a/man/std::ref,std::cref.3 b/man/std::ref,std::cref.3 index 34b45e188..09988092e 100644 --- a/man/std::ref,std::cref.3 +++ b/man/std::ref,std::cref.3 @@ -1,24 +1,58 @@ -.TH std::ref,std::cref 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ref,std::cref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ref,std::cref \- std::ref,std::cref + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - std::reference_wrapper ref(T& t); - template< class T > \fB(2)\fP \fI(since C++11)\fP - std::reference_wrapper ref( std::reference_wrapper t ); - template \fB(3)\fP \fI(since C++11)\fP - void ref(const T&&) = delete; - template< class T > \fB(4)\fP \fI(since C++11)\fP - std::reference_wrapper cref( const T& t ); + template< class T > (since + std::reference_wrapper ref( T& t ) C++11) + noexcept; (until + C++20) + template< class T > (since + constexpr std::reference_wrapper ref( T& C++20) + t ) noexcept; + template< class T > + (since + std::reference_wrapper C++11) + (until + ref( std::reference_wrapper t ) C++20) + noexcept; + template< class T > + + constexpr std::reference_wrapper (since + C++20) + ref( std::reference_wrapper t ) + noexcept; + template< class T > \fB(3)\fP (since + void ref( const T&& ) = delete; \fB(1)\fP C++11) + template< class T > (since + std::reference_wrapper cref( const C++11) + T& t ) noexcept; (until + \fB(2)\fP C++20) + template< class T > (since + constexpr std::reference_wrapper C++20) + cref( const T& t ) noexcept; template< class T > - std::reference_wrapper cref( std::reference_wrapper t \fB(5)\fP \fI(since C++11)\fP - ) - template \fB(6)\fP \fI(since C++11)\fP - void cref(const T&&) = delete; + (since + std::reference_wrapper C++11) + \fB(4)\fP (until + cref( std::reference_wrapper t ) C++20) + noexcept; + template< class T > \fB(5)\fP + + constexpr std::reference_wrapper (since + C++20) + cref( std::reference_wrapper t ) + noexcept; + template< class T > \fB(6)\fP (since + void cref( const T&& ) = delete; C++11) Function templates ref and cref are helper functions that generate an object of type std::reference_wrapper, using template argument deduction to determine the template argument of the result. + T may be an incomplete type. \fI(since C++20)\fP + .SH Parameters t - lvalue reference to object that needs to be wrapped or an instance of @@ -27,24 +61,19 @@ .SH Return value 1) std::reference_wrapper(t) - 2) ref(t.get()) + 2) t 4) std::reference_wrapper(t) - 5) cref(t.get()) - -.SH Exeptions - - noexcept specification: - noexcept - + 5) t + 3,6) rvalue reference wrapper is deleted. .SH Example - + // Run this code #include #include - + void f(int& n1, int& n2, const int& n3) { std::cout << "In function: " << n1 << ' ' << n2 << ' ' << n3 << '\\n'; @@ -52,7 +81,7 @@ ++n2; // increments the main()'s n2 // ++n3; // compile error } - + int main() { int n1 = 1, n2 = 2, n3 = 3; @@ -71,7 +100,15 @@ In function: 1 11 12 After function: 10 12 12 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3146 C++11 unwrapping overloads sometimes led to error made always valid + .SH See also reference_wrapper CopyConstructible and CopyAssignable reference wrapper - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::reference_constructs_from_temporary.3 b/man/std::reference_constructs_from_temporary.3 new file mode 100644 index 000000000..80a946fb7 --- /dev/null +++ b/man/std::reference_constructs_from_temporary.3 @@ -0,0 +1,85 @@ +.TH std::reference_constructs_from_temporary 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_constructs_from_temporary \- std::reference_constructs_from_temporary + +.SH Synopsis + Defined in header + template< class T, class U > (since C++23) + struct reference_constructs_from_temporary; + + Let V be std::remove_cv_t if U is a scalar type or cv void, or U otherwise. If T + is a reference type, and given a hypothetic expression e such that decltype(e) is V, + the variable definition T ref(e); is well-formed and binds a temporary object to + ref, then provides the member constant value equal to true. Otherwise, value is + false. + + If T is an lvalue reference type to a const- but not volatile-qualified object type + or an rvalue reference type, both std::remove_reference_t and + std::remove_reference_t shall be complete types, cv void, or an arrays of unknown + bound; otherwise the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for std::reference_constructs_from_temporary or + std::reference_constructs_from_temporary_v, the behavior is undefined. + +.SH Member constants + + true if T is a reference type, a U value can be bound to T in + value direct-initialization, and a temporary object would be bound to the + \fB[static]\fP reference, false otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + std::reference_constructs_from_temporary can be used for rejecting some cases that + always produce dangling references. + + It is also possible to use member initializer list to reject binding a temporary + object to a reference if the compiler has implemented CWG1696. + +.SH Example + + +// Run this code + + #include + + static_assert(std::reference_constructs_from_temporary_v == true); + static_assert(std::reference_constructs_from_temporary_v == true); + static_assert(std::reference_constructs_from_temporary_v == false); + static_assert(std::reference_constructs_from_temporary_v == false); + static_assert(std::reference_constructs_from_temporary_v == true); + static_assert(std::reference_constructs_from_temporary_v == true); + + int main() {} + +.SH See also + + is_constructible + is_trivially_constructible + is_nothrow_constructible checks if a type has a constructor for specific arguments + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + constructor constructs a new tuple + \fI(public member function of std::tuple)\fP + constructor constructs new pair + \fI(public member function of std::pair)\fP + make_from_tuple construct an object with a tuple of arguments + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::reference_converts_from_temporary.3 b/man/std::reference_converts_from_temporary.3 new file mode 100644 index 000000000..9866e4377 --- /dev/null +++ b/man/std::reference_converts_from_temporary.3 @@ -0,0 +1,90 @@ +.TH std::reference_converts_from_temporary 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_converts_from_temporary \- std::reference_converts_from_temporary + +.SH Synopsis + Defined in header + template< class T, class U > (since C++23) + struct reference_converts_from_temporary; + + Let V be std::remove_cv_t if U is a scalar type or cv void, or U otherwise. If T + is a reference type, and given a hypothetic expression e such that decltype(e) is V, + the variable definition T ref = e; is well-formed and binds a temporary object to + ref, then provides the member constant value equal to true. Otherwise, value is + false. + + If T is an lvalue reference type to a const- but not volatile-qualified object type + or an rvalue reference type, both std::remove_reference_t and + std::remove_reference_t shall be complete types, cv void, or an arrays of unknown + bound; otherwise the behavior is undefined. + + If an instantiation of a template above depends, directly or indirectly, on an + incomplete type, and that instantiation could yield a different result if that type + were hypothetically completed, the behavior is undefined. + + If the program adds specializations for std::reference_converts_from_temporary or + std::reference_converts_from_temporary_v, the behavior is undefined. + +.SH Member constants + + true if T is a reference type, a U value can be bound to T in + value copy-initialization, and a temporary object would be bound to the + \fB[static]\fP reference, false otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Notes + + std::reference_converts_from_temporary can be used for rejecting some cases that + always produce dangling references. + +.SH Example + + +// Run this code + + #include + + int main() {} + + static_assert(std::reference_converts_from_temporary_v == true); + static_assert(std::reference_converts_from_temporary_v == true); + static_assert(std::reference_converts_from_temporary_v == false); + static_assert(std::reference_converts_from_temporary_v == false); + static_assert(std::reference_converts_from_temporary_v == true); + static_assert(std::reference_converts_from_temporary_v == true); + +.SH See also + + is_convertible + is_nothrow_convertible checks if a type can be converted to the other type + \fI(C++11)\fP \fI(class template)\fP + (C++20) + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP + bind binds one or more arguments to a function object + \fI(C++11)\fP \fI(function template)\fP + visit calls the provided functor with the arguments held by one or + \fI(C++17)\fP more variants + \fI(function template)\fP + constructor constructs a new std::function instance + \fI(public member function of std::function)\fP + constructor constructs a new std::move_only_function object + (C++23) \fI(public member function of std::move_only_function)\fP + constructs the task object + constructor \fI(public member function of std::packaged_task)\fP + diff --git a/man/std::reference_wrapper.3 b/man/std::reference_wrapper.3 index b7e7b4843..e83dd1808 100644 --- a/man/std::reference_wrapper.3 +++ b/man/std::reference_wrapper.3 @@ -1,13 +1,14 @@ -.TH std::reference_wrapper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reference_wrapper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_wrapper \- std::reference_wrapper + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP class reference_wrapper; std::reference_wrapper is a class template that wraps a reference in a copyable, - assignable object. It is frequently used as a mechanism to store references inside - standard containers (like std::vector or std::pair) which can not normally hold - references. + assignable object. Specifically, std::reference_wrapper is a CopyConstructible and CopyAssignable wrapper around a reference to object or reference to function of type T. Instances @@ -15,108 +16,192 @@ but they are implicitly convertible to T&, so that they can be used as arguments with the functions that take the underlying type by reference. + If the stored reference is Callable, std::reference_wrapper is callable with the + same arguments. + Helper functions std::ref and std::cref are often used to generate std::reference_wrapper objects. - std::reference_wrapper is also used to pass objects to std::bind or to the - constructor of std::thread by reference. + std::reference_wrapper is used to pass objects by reference to std::bind, the + constructor of std::thread, or the helper functions std::make_pair and + std::make_tuple. It can also be used as a mechanism to store references inside + standard containers (like std::vector) that cannot normally hold references. + + std::reference_wrapper is guaranteed to be TriviallyCopyable. \fI(since C++17)\fP + + T may be an incomplete type. \fI(since C++20)\fP .SH Member types - type definition - type T - result_type The return type of T if T is a function. Otherwise, not defined - 1) if T is a function or pointer to function that takes one - argument of type A1, then argument_type is A1. - - argument_type 2) if T is a pointer to member function of class T0 that takes - no arguments, then argument_type is T0*, possibly cv-qualified - 3) if T is a class type with a member type T::argument_type, - then argument_type is an alias of that - 1) if T is a function or pointer to function that takes two - arguments of type s A1 and A2, then first_argument_type is A1. - - 2) if T is a pointer to member function of class T0 that takes - first_argument_type one argument, then first_argument_type is T0*, possibly - cv-qualified - 3) if T is a class type with a member type - T::first_argument_type, then first_argument_type is an alias of - that - 1) if T is a function or pointer to function that takes two - arguments of type s A1 and A2, then second_argument_type is A2. - - 2) if T is a pointer to member function of class T0 that takes - second_argument_type one argument A1, then second_argument_type is A1, possibly - cv-qualified - 3) if T is a class type with a member type - T::second_argument_type, then second_argument_type is an alias - of that + type definition + type T + result_type The return type of T if T is a function. Otherwise, + (deprecated in C++17)(removed in not defined + C++20) + * if T is a function or pointer to function that + takes one argument of type A1, then + argument_type is A1 + argument_type * if T is a pointer to member function of class + (deprecated in C++17)(removed in T0 that takes no arguments, then argument_type + C++20) is T0*, possibly cv-qualified + * if T is a class type with a member type + T::argument_type, then argument_type is an + alias of that + * if T is a function or pointer to function that + takes two arguments of types A1 and A2, then + first_argument_type is A1 + first_argument_type * if T is a pointer to member function of class + (deprecated in C++17)(removed in T0 that takes one argument, then + C++20) first_argument_type is T0*, possibly + cv-qualified + * if T is a class type with a member type + T::first_argument_type, then + first_argument_type is an alias of that + * if T is a function or pointer to function that + takes two arguments of type s A1 and A2, then + second_argument_type is A2 + second_argument_type * if T is a pointer to member function of class + (deprecated in C++17)(removed in T0 that takes one argument A1, then + C++20) second_argument_type is A1, possibly + cv-qualified + * if T is a class type with a member type + T::second_argument_type, then + second_argument_type is an alias of that .SH Member functions constructor stores a reference in a new std::reference_wrapper object - \fI(public member function)\fP + \fI(public member function)\fP operator= rebinds a std::reference_wrapper - \fI(public member function)\fP + \fI(public member function)\fP get accesses the stored reference - operator T& \fI(public member function)\fP + operator T& \fI(public member function)\fP operator() calls the stored function - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares reference_wrapper objects as their stored references + operator<=> \fI(function)\fP + (C++26) + + Deduction guides\fI(since C++17)\fP + +.SH Helper classes + + determines the common reference + std::basic_common_reference type of reference_wrapper and + (C++23) non-reference_wrapper + \fI(class template specialization)\fP + + +.SH Possible implementation + + namespace detail + { + template constexpr T& FUN(T& t) noexcept { return t; } + template void FUN(T&&) = delete; + } + + template + class reference_wrapper + { + public: + // types + using type = T; + + // construct/copy/destroy + template(std::declval()), + std::enable_if_t>>() + )> + constexpr reference_wrapper(U&& u) + noexcept(noexcept(detail::FUN(std::forward(u)))) + : _ptr(std::addressof(detail::FUN(std::forward(u)))) {} + + reference_wrapper(const reference_wrapper&) noexcept = default; + + // assignment + reference_wrapper& operator=(const reference_wrapper& x) noexcept = default; + + // access + constexpr operator T& () const noexcept { return *_ptr; } + constexpr T& get() const noexcept { return *_ptr; } + + template + constexpr std::invoke_result_t + operator() (ArgTypes&&... args ) const + noexcept(std::is_nothrow_invocable_v) + { + return std::invoke(get(), std::forward(args)...); + } + + private: + T* _ptr; + }; + + // deduction guides + template + reference_wrapper(T&) -> reference_wrapper; .SH Example - Demonstrates the use of reference_wrapper as a container of references, which makes - it possible to access the same container using multiple indexes + Demonstrates the use of std::reference_wrapper as a container of references, which + makes it possible to access the same container using multiple indices. + - // Run this code #include + #include + #include #include + #include + #include #include - #include - #include - + + void println(auto const rem, std::ranges::range auto const& v) + { + for (std::cout << rem; auto const& e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { - std::list l = {-4, -3, -2, -1, 0, 1, 2, 3, 4}; - + std::list l(10); + std::iota(l.begin(), l.end(), -4); + + // can't use shuffle on a list (requires random access), but can use it on a vector std::vector> v(l.begin(), l.end()); - std::random_shuffle(v.begin(), v.end()); - - std::vector> v2(v.begin(), v.end()); - std::partition(v2.begin(), v2.end(), [](int n){return n<0;}); - - std::cout << "Contents of the list: "; - for(int n: l) { - std::cout << n << ' '; - } - std::cout << '\\n'; - - std::cout << "Contents of the list, shuffled: "; - for(int i: v) { - std::cout << i << ' '; - } - std::cout << '\\n'; - - std::cout << "Shuffled elements, partitioned: "; - for(int i: v2) { - std::cout << i << ' '; - } - std::cout << '\\n'; + + std::ranges::shuffle(v, std::mt19937{std::random_device{}()}); + + println("Contents of the list: ", l); + println("Contents of the list, as seen through a shuffled vector: ", v); + + std::cout << "Doubling the values in the initial list...\\n"; + std::ranges::for_each(l, [](int& i) { i *= 2; }); + + println("Contents of the list, as seen through a shuffled vector: ", v); } -.SH Output: +.SH Possible output: - Contents of the list: -4 -3 -2 -1 0 1 2 3 4 - Contents of the list, shuffled: 0 -1 3 4 -4 1 -2 -3 2 - Shuffled elements, partitioned: -3 -1 -2 -4 4 1 3 0 2 + Contents of the list: -4 -3 -2 -1 0 1 2 3 4 5 + Contents of the list, as seen through a shuffled vector: -1 2 -2 1 5 0 3 -3 -4 4 + Doubling the values in the initial list... + Contents of the list, as seen through a shuffled vector: -2 4 -4 2 10 0 6 -6 -8 8 .SH See also - ref - cref creates a std::reference_wrapper with a type deduced from its argument - \fI(C++11)\fP \fI(function template)\fP + ref creates a std::reference_wrapper with a type deduced from its + cref argument + \fI(C++11)\fP \fI(function template)\fP \fI(C++11)\fP - bind binds one or more arguments to a function object - \fI(C++11)\fP \fI(function template)\fP + bind binds one or more arguments to a function object + \fI(C++11)\fP \fI(function template)\fP + unwrap_reference + unwrap_ref_decay get the reference type wrapped in std::reference_wrapper + (C++20) \fI(class template)\fP + (C++20) diff --git a/man/std::reference_wrapper::get,std::reference_wrapper::operatorT&.3 b/man/std::reference_wrapper::get,std::reference_wrapper::operatorT&.3 index 35872a805..69164cb3b 100644 --- a/man/std::reference_wrapper::get,std::reference_wrapper::operatorT&.3 +++ b/man/std::reference_wrapper::get,std::reference_wrapper::operatorT&.3 @@ -1,7 +1,12 @@ -.TH std::reference_wrapper::get,std::reference_wrapper::operatorT& 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reference_wrapper::get,std::reference_wrapper::operatorT& 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_wrapper::get,std::reference_wrapper::operatorT& \- std::reference_wrapper::get,std::reference_wrapper::operatorT& + .SH Synopsis - operator T& () const; \fI(since C++11)\fP - T& get() const; \fI(since C++11)\fP + operator T& () const noexcept; \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++20) + T& get() const noexcept; \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++20) Returns the stored reference. @@ -13,14 +18,39 @@ The stored reference. -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using Map = std::map; + using Opt = std::optional>; + + Opt find(Map& m, std::string_view s) + { + auto it = m.find(s); + return it == m.end() ? Opt{} : Opt{*it}; + } + + int main() + { + Map m{{"A", 1}, {"B", 2}, {"C", 3}}; + + if (auto opt = find(m, "C"); opt) + opt->get().second = 42; + // std::optional::operator->() returns reference to std::reference_wrapper, then + // reference_wrapper::get() returns reference to map::value_type, i.e. std::pair - 1-2) - noexcept specification: - noexcept - + assert(m["C"] == 42); + } .SH See also operator() calls the stored function - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::reference_wrapper::operator().3 b/man/std::reference_wrapper::operator().3 index d8159a082..587dbf4a5 100644 --- a/man/std::reference_wrapper::operator().3 +++ b/man/std::reference_wrapper::operator().3 @@ -1,13 +1,25 @@ -.TH std::reference_wrapper::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reference_wrapper::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_wrapper::operator() \- std::reference_wrapper::operator() + .SH Synopsis template< class... ArgTypes > - - typename std::result_of::type \fI(since C++11)\fP + \fI(since C++11)\fP + typename std::result_of::type \fI(until C++17)\fP operator() ( ArgTypes&&... args ) const; + template< class... ArgTypes > + \fI(since C++17)\fP + std::invoke_result_t (constexpr since + C++20) + operator() ( ArgTypes&&... args ) const noexcept(/* see below + */); + + Calls the Callable object, reference to which is stored, as if by INVOKE(get(), + std::forward(args)...). This function is available only if the stored + reference points to a Callable object. - Calls the Callable object, reference to which is stored. This function is available - only if the stored reference points to a Callable object. + T must be a complete type. .SH Parameters @@ -19,35 +31,39 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. \fI(since C++11)\fP + \fI(until C++17)\fP + noexcept specification: \fI(since C++17)\fP + noexcept(std::is_nothrow_invocable_v) .SH Example - + // Run this code - #include #include - + #include + void f1() { std::cout << "reference to function called\\n"; } + void f2(int n) { std::cout << "bind expression called with " << n << " as the argument\\n"; } - + int main() { std::reference_wrapper ref1 = std::ref(f1); ref1(); - + auto b = std::bind(f2, std::placeholders::_1); auto ref2 = std::ref(b); ref2(7); - - auto c = []{std::cout << "lambda function called\\n"; }; + + auto c = []{ std::cout << "lambda function called\\n"; }; auto ref3 = std::ref(c); ref3(); } @@ -58,7 +74,18 @@ bind expression called with 7 as the argument lambda function called + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3764 C++17 operator() is not noexcept propagate noexcept + .SH See also get accesses the stored reference - operator T& \fI(public member function)\fP + operator T& \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::reference_wrapper::operator=.3 b/man/std::reference_wrapper::operator=.3 index 84a30c5ea..d69fa7148 100644 --- a/man/std::reference_wrapper::operator=.3 +++ b/man/std::reference_wrapper::operator=.3 @@ -1,6 +1,10 @@ -.TH std::reference_wrapper::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reference_wrapper::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_wrapper::operator= \- std::reference_wrapper::operator= + .SH Synopsis - reference_wrapper& operator=( const reference_wrapper& other ); \fI(since C++11)\fP + reference_wrapper& operator=( const reference_wrapper& \fI(since C++11)\fP + other ) noexcept; (constexpr since C++20) Copy assignment operator. Drops the current reference and stores a reference to other.get(). @@ -9,12 +13,6 @@ other - reference wrapper to copy -.SH Return values +.SH Return value *this - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::reference_wrapper::reference_wrapper.3 b/man/std::reference_wrapper::reference_wrapper.3 index d987afa37..dc2b281f7 100644 --- a/man/std::reference_wrapper::reference_wrapper.3 +++ b/man/std::reference_wrapper::reference_wrapper.3 @@ -1,16 +1,25 @@ -.TH std::reference_wrapper::reference_wrapper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reference_wrapper::reference_wrapper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reference_wrapper::reference_wrapper \- std::reference_wrapper::reference_wrapper + .SH Synopsis - reference_wrapper( T& x ); \fI(since C++11)\fP - reference_wrapper( T&& x ) = delete; \fI(since C++11)\fP - reference_wrapper( const reference_wrapper& other ); \fI(since C++11)\fP + template< class U > \fB(1)\fP \fI(since C++11)\fP + reference_wrapper( U&& x ) noexcept(/*see below*/) ; (constexpr since C++20) + reference_wrapper( const reference_wrapper& other ) \fB(2)\fP \fI(since C++11)\fP + noexcept; (constexpr since C++20) Constructs a new reference wrapper. - 1) Stores a reference to x. + 1) Converts x to T& as if by T& t = std::forward(x);, then stores a reference to + t. This overload participates in overload resolution only if typename + std::decay::type is not the same type as reference_wrapper and the expression + FUN(std::declval()) is well-formed, where FUN names the set of imaginary + functions - 2) Construction from a temporary object is not allowed. + void FUN(T&) noexcept; + void FUN(T&&) = delete; - 3) Copy constructor. Stores a reference to other.get(). + 2) Copy constructor. Stores a reference to other.get(). .SH Parameters @@ -19,6 +28,26 @@ .SH Exceptions - noexcept specification: - noexcept - + 1) + noexcept specification: + noexcept(noexcept(FUN(std::declval()))) + where FUN is the set of imaginary functions described in the description above. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + deleted reference_wrapper(T&&) constructor replaced with a + LWG 2993 C++11 interferes constructor template + with overload resolution in some cases + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/std::regex.3 b/man/std::regex.3 deleted file mode 120000 index 9a17ed1ed..000000000 --- a/man/std::regex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex.3 \ No newline at end of file diff --git a/man/std::regex.3 b/man/std::regex.3 new file mode 100644 index 000000000..f9b104d69 --- /dev/null +++ b/man/std::regex.3 @@ -0,0 +1,101 @@ +.TH std::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex \- std::basic_regex + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++11)\fP + class Traits = std::regex_traits + + > class basic_regex; + + The class template basic_regex provides a general framework for holding regular + expressions. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::regex std::basic_regex + std::wregex std::basic_regex + +.SH Member types + + Member type Definition + value_type CharT + traits_type Traits + string_type Traits::string_type + locale_type Traits::locale_type + flag_type std::regex_constants::syntax_option_type + +.SH Member functions + + constructor constructs the regex object + \fI(public member function)\fP + destructor destructs the regex object + \fI(public member function)\fP + operator= assigns the contents + \fI(public member function)\fP + assign assigns the contents + \fI(public member function)\fP +.SH Observers + returns the number of marked sub-expressions within the regular + mark_count expression + \fI(public member function)\fP + flags returns the syntax flags + \fI(public member function)\fP +.SH Locale + getloc get locale information + \fI(public member function)\fP + imbue set locale information + \fI(public member function)\fP +.SH Modifiers + swap swaps the contents + \fI(public member function)\fP +.SH Constants + + Grammar option Effect(s) + ECMAScript Use the Modified ECMAScript regular expression grammar. + basic Use the basic POSIX regular expression grammar (grammar + documentation). + extended Use the extended POSIX regular expression grammar (grammar + documentation). + awk Use the regular expression grammar used by the awk utility in + POSIX (grammar documentation). + Use the regular expression grammar used by the grep utility in + grep POSIX. This is effectively the same as the basic option with the + addition of newline '\\n' as an alternation separator. + Use the regular expression grammar used by the grep utility, with + egrep the -E option, in POSIX. This is effectively the same as the + extended option with the addition of newline '\\n' as an + alternation separator in addition to '|'. + Grammar variation Effect(s) + icase Character matching should be performed without regard to case. + When performing matches, all marked sub-expressions (expr) are + nosubs treated as non-marking sub-expressions (?:expr). No matches are + stored in the supplied std::regex_match structure and mark_count() + is zero. + Instructs the regular expression engine to make matching faster, + optimize with the potential cost of making construction slower. For + example, this might mean converting a non-deterministic FSA to a + deterministic FSA. + collate Character ranges of the form "[a-b]" will be locale sensitive. + multiline \fI(C++17)\fP Specifies that ^ shall match the beginning of a line and $ shall + match the end of a line, if the ECMAScript engine is selected. + + At most one grammar option can be chosen out of ECMAScript, basic, extended, awk, + grep, egrep. If no grammar is chosen, ECMAScript is assumed to be selected. The + other options serve as variations, such that std::regex("meow", std::regex::icase) + is equivalent to std::regex("meow", std::regex::ECMAScript|std::regex::icase). + + The member constants in basic_regex are duplicates of the syntax_option_type + constants defined in the namespace std::regex_constants. + +.SH Non-member functions + + std::swap(std::basic_regex) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + + Deduction guides\fI(since C++17)\fP diff --git a/man/std::regex::assign.3 b/man/std::regex::assign.3 deleted file mode 120000 index 560822a86..000000000 --- a/man/std::regex::assign.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::assign.3 \ No newline at end of file diff --git a/man/std::regex::assign.3 b/man/std::regex::assign.3 new file mode 100644 index 000000000..839482ea8 --- /dev/null +++ b/man/std::regex::assign.3 @@ -0,0 +1,78 @@ +.TH std::basic_regex::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::assign \- std::basic_regex::assign + +.SH Synopsis + basic_regex& assign( const basic_regex& other ); \fB(1)\fP \fI(since C++11)\fP + basic_regex& assign( basic_regex&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + basic_regex& assign( const CharT* s, + flag_type f = \fB(3)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + basic_regex& assign( const CharT* ptr, std::size_t count, + flag_type f = \fB(4)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + template< class ST, class SA > + + basic_regex& assign( const std::basic_string& str, \fB(5)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + template< class InputIt > + + basic_regex& assign( InputIt first, InputIt last, \fB(6)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + basic_regex& assign( std::initializer_list ilist, + flag_type f = \fB(7)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + + Assigns the contents to the regular expression. + + 1) Assigns the contents of other. flags() and mark_count() are equivalent to the + values of other.flags() and other.mark_count() after the call. + 2) Assigns the contents of other using move semantics. flags() and mark_count() are + equivalent to the values of other.flags() and other.mark_count() before the + assignment. After the call, other is in a valid, but unspecified state. + 3-7) Assigns a sequence of characters to the regular expression. The syntax flags + are set to f. mark_count() returns the number of marked subexpressions within the + resulting subexpression after the call. + 3) Assigns a null-terminated string pointed to by s. + 4) Assigns a sequence of count characters, pointed to by s. + 5) Assigns the string str. + 6) Assigns the characters in the range [first, last). + 7) Assigns the characters in the initializer list ilist. + +.SH Parameters + + other - another regular expression to assign + s - pointer to a character sequence to assign + str - string to assign + first, last - the range of characters to assign + ilist - initializer list containing characters to assign +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 3-7) std::regex_error if the supplied regular expression is not valid. The object is + not modified in that case. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns the contents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::regex::basic_regex.3 b/man/std::regex::basic_regex.3 deleted file mode 120000 index f094a24b8..000000000 --- a/man/std::regex::basic_regex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::basic_regex.3 \ No newline at end of file diff --git a/man/std::regex::basic_regex.3 b/man/std::regex::basic_regex.3 new file mode 100644 index 000000000..79d139c71 --- /dev/null +++ b/man/std::regex::basic_regex.3 @@ -0,0 +1,172 @@ +.TH std::basic_regex::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::basic_regex \- std::basic_regex::basic_regex + +.SH Synopsis + basic_regex(); \fB(1)\fP \fI(since C++11)\fP + explicit basic_regex( const CharT* s, + flag_type f = \fB(2)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + basic_regex( const CharT* s, std::size_t count, \fB(3)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( const basic_regex& other ); \fB(4)\fP \fI(since C++11)\fP + basic_regex( basic_regex&& other ) noexcept; \fB(5)\fP \fI(since C++11)\fP + template< class ST, class SA > + + explicit basic_regex( const std::basic_string& str, \fB(6)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + template< class ForwardIt > + + basic_regex( ForwardIt first, ForwardIt last, \fB(7)\fP \fI(since C++11)\fP + + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( std::initializer_list init, \fB(8)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + + Constructs a new regular expression from a sequence of characters interpreted + according to the flags f. + + 1) Default constructor. Constructs an empty regular expression which will match + nothing. + 2) Constructs a regex from a null-terminated string s. + 3) Constructs a regex from a sequence of count characters, pointed to by s. + 4) Copy constructor. Constructs a regex by copying other. + 5) Move constructor. Constructs a regex with the contents of other using move + semantics. + 6) Constructs a regex from a string str. + 7) Range constructor. Constructs the string with the contents of the range + [first, last). + 8) Initializer list constructor. Constructs the string with the contents of the + initializer list init. + +.SH Parameters + + s - pointer to a null-terminated string + count - length of a character sequence used to initialize the regex + first, last - range of a character sequence used to initialize the regex + str - a basic_string used as a source used to initialize the regex + other - another regex to use as source to initialize the regex + init - initializer list used to initialize the regex + f - flags used to guide the interpretation of the character sequence as a + regular expression +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 2,3) std::regex_error if the supplied regular expression is not valid. + 4) May throw implementation-defined exceptions. + 6-8) std::regex_error if the supplied regular expression is not valid. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void match_and_print(const std::string& text, const std::regex& pattern) + { + std::sregex_iterator it(text.begin(), text.end(), pattern), it_end; + int count = 0; + for (; it != it_end; ++it) + { + const std::smatch& match = *it; + std::cout << ++count << ". " << std::quoted(match.str()) << '\\n'; + } + std::cout << (count ? "\\n" : "no match found\\n\\n"); + } + + int main() + { + const std::string text = "Hello, World! 12345"; + + // Matches one or more digits + std::string pattern_text = "\\\\d+"; + std::cout << "digits (" << pattern_text << "):\\n"; + auto pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[^\\\\s]+"; + std::cout << "words (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[a-zA-Z]+"; + std::cout << "words without symbols and digits (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one non digits, non alphabet + pattern_text = "[^0-9A-Za-z]"; + std::cout << "symbol (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase + pattern_text = "[a-z]+"; + std::cout << "lowercase (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase with std::regex::icase flag + pattern_text = "[a-z]+"; + std::cout << "lowercase with ignore case flag (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::icase); + match_and_print(text, pattern); + + // Matches basic POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "basic POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::basic); + match_and_print(text, pattern); + + // Matches extended POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "extended POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::extended); + match_and_print(text, pattern); + } + +.SH Output: + + digits (\\d+): + 1. "12345" + + words ([^\\s]+): + 1. "Hello," + 2. "World!" + 3. "12345" + + words without symbols and digits ([a-zA-Z]+): + 1. "Hello" + 2. "World" + + symbol ([^0-9A-Za-z]): + 1. "," + 2. " " + 3. "!" + 4. " " + + lowercase ([a-z]+): + 1. "ello" + 2. "orld" + + lowercase with ignore case flag ([a-z]+): + 1. "Hello" + 2. "World" + + basic POSIX regex ([[:digit:]]+): + no match found + + extended POSIX regex ([[:digit:]]+): + 1. "12345" diff --git a/man/std::regex::flags.3 b/man/std::regex::flags.3 deleted file mode 120000 index d03d4186c..000000000 --- a/man/std::regex::flags.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::flags.3 \ No newline at end of file diff --git a/man/std::regex::flags.3 b/man/std::regex::flags.3 new file mode 100644 index 000000000..f8f95a215 --- /dev/null +++ b/man/std::regex::flags.3 @@ -0,0 +1,29 @@ +.TH std::basic_regex::flags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::flags \- std::basic_regex::flags + +.SH Synopsis + flag_type flags() const; \fI(since C++11)\fP + + Returns the regular expression syntax flags as set in the constructor or the last + call to assign(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Current regular expression syntax flags. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::regex::getloc.3 b/man/std::regex::getloc.3 deleted file mode 120000 index ea5268cf9..000000000 --- a/man/std::regex::getloc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::getloc.3 \ No newline at end of file diff --git a/man/std::regex::getloc.3 b/man/std::regex::getloc.3 new file mode 100644 index 000000000..360a83e07 --- /dev/null +++ b/man/std::regex::getloc.3 @@ -0,0 +1,36 @@ +.TH std::basic_regex::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::getloc \- std::basic_regex::getloc + +.SH Synopsis + locale_type getloc() const; \fI(since C++11)\fP + + Returns the current locale associated with the regular expression. + + Effectively calls traits_i.getloc() where traits_i is a default initialized instance + of the type Traits, stored within the regular expression object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current locale associated with the regular expression. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + imbue set locale information + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::regex::imbue.3 b/man/std::regex::imbue.3 deleted file mode 120000 index d967c1b28..000000000 --- a/man/std::regex::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::imbue.3 \ No newline at end of file diff --git a/man/std::regex::imbue.3 b/man/std::regex::imbue.3 new file mode 100644 index 000000000..bf4ad79d2 --- /dev/null +++ b/man/std::regex::imbue.3 @@ -0,0 +1,38 @@ +.TH std::basic_regex::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::imbue \- std::basic_regex::imbue + +.SH Synopsis + locale_type imbue( locale_type loc ); \fI(since C++11)\fP + + Replaces the current locale with loc. The regular expression does not match any + character sequence after the call. + + Effectively calls traits_i.imbue(loc) where traits_i is a default initialized + instance of the type Traits stored within the regular expression object. + +.SH Parameters + + loc - new locale to use + +.SH Return value + + The locale before the call to this function. Effectively returns the result of + expression traits_i.imbue(loc). + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + getloc get locale information + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::regex::mark_count.3 b/man/std::regex::mark_count.3 deleted file mode 120000 index 1d852fd08..000000000 --- a/man/std::regex::mark_count.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::mark_count.3 \ No newline at end of file diff --git a/man/std::regex::mark_count.3 b/man/std::regex::mark_count.3 new file mode 100644 index 000000000..20b3a9bf6 --- /dev/null +++ b/man/std::regex::mark_count.3 @@ -0,0 +1,68 @@ +.TH std::basic_regex::mark_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::mark_count \- std::basic_regex::mark_count + +.SH Synopsis + unsigned mark_count() const; \fI(since C++11)\fP + + Returns the number of marked sub-expressions (also known as capture groups) within + the regular expression. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of marked sub-expressions within the regular expression. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::regex r1{"abcde"}; + std::cout << "r1 has " << r1.mark_count() << " subexpressions" << '\\n'; + // Expected: 0 + + std::regex r2{"ab(c)de"}; + std::cout << "r2 has " << r2.mark_count() << " subexpressions" << '\\n'; + // Expected: 1 + + std::regex r3{"a(bc)d(e)"}; + std::cout << "r3 has " << r3.mark_count() << " subexpressions" << '\\n'; + // Expected: 2 + + // Nested sub-expressions + std::regex r4{"abc(de(fg))"}; + std::cout << "r4 has " << r4.mark_count() << " subexpressions" << '\\n'; + // Expected: 2 + + // Escaped parentheses + std::regex r5{"a(bc\\\\(\\\\)de)"}; + std::cout << "r5 has " << r5.mark_count() << " subexpressions" << '\\n'; + // Expected: 1 + + // Using nosubs flag + std::regex r6{"ab(c)de", std::regex_constants::nosubs}; + std::cout << "r6 has " << r6.mark_count() << " subexpressions" << '\\n'; + // Expected: 0 + } + +.SH Output: + + r1 has 0 subexpressions + r2 has 1 subexpressions + r3 has 2 subexpressions + r4 has 2 subexpressions + r5 has 1 subexpressions + r6 has 0 subexpressions diff --git a/man/std::regex::operator=.3 b/man/std::regex::operator=.3 deleted file mode 120000 index 2d634b06c..000000000 --- a/man/std::regex::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::operator=.3 \ No newline at end of file diff --git a/man/std::regex::operator=.3 b/man/std::regex::operator=.3 new file mode 100644 index 000000000..160225b20 --- /dev/null +++ b/man/std::regex::operator=.3 @@ -0,0 +1,46 @@ +.TH std::basic_regex::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::operator= \- std::basic_regex::operator= + +.SH Synopsis + Defined in header + basic_regex& operator=( const basic_regex& other ); \fB(1)\fP \fI(since C++11)\fP + basic_regex& operator=( basic_regex&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + basic_regex& operator=( const CharT* ptr ); \fB(3)\fP \fI(since C++11)\fP + basic_regex& operator=( std::initializer_list il ); \fB(4)\fP \fI(since C++11)\fP + template< class ST, class SA > \fB(5)\fP \fI(since C++11)\fP + basic_regex& operator=( const std::basic_string& p ); + + Assigns the contents. + + 1) Copy assignment operator. Assigns the contents of other. Equivalent to + assign(other);. + 2) Move assignment operator. Assigns the contents of other using move semantics. + other is in valid, but unspecified state after the operation. Equivalent to + assign(other);. + 3) Assigns a null-terminated character string pointed to by ptr. Equivalent to + assign(ptr);. + 4) Assigns characters contained in initializer list il. Equivalent to assign(il);. + 5) Assigns the contents of the string p. Equivalent to assign(p);. + +.SH Parameters + + other - another regex object + ptr - pointer to a null-terminated character string + il - initializer list containing characters to assign + p - string containing characters to assign + +.SH Return value + + *this + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 3-5) std::regex_error if the supplied regular expression is not valid. The object is + not modified in that case. + +.SH See also + + assign assigns the contents + \fI(public member function)\fP diff --git a/man/std::regex::regex.3 b/man/std::regex::regex.3 deleted file mode 120000 index f094a24b8..000000000 --- a/man/std::regex::regex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::basic_regex.3 \ No newline at end of file diff --git a/man/std::regex::regex.3 b/man/std::regex::regex.3 new file mode 100644 index 000000000..79d139c71 --- /dev/null +++ b/man/std::regex::regex.3 @@ -0,0 +1,172 @@ +.TH std::basic_regex::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::basic_regex \- std::basic_regex::basic_regex + +.SH Synopsis + basic_regex(); \fB(1)\fP \fI(since C++11)\fP + explicit basic_regex( const CharT* s, + flag_type f = \fB(2)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + basic_regex( const CharT* s, std::size_t count, \fB(3)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( const basic_regex& other ); \fB(4)\fP \fI(since C++11)\fP + basic_regex( basic_regex&& other ) noexcept; \fB(5)\fP \fI(since C++11)\fP + template< class ST, class SA > + + explicit basic_regex( const std::basic_string& str, \fB(6)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + template< class ForwardIt > + + basic_regex( ForwardIt first, ForwardIt last, \fB(7)\fP \fI(since C++11)\fP + + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( std::initializer_list init, \fB(8)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + + Constructs a new regular expression from a sequence of characters interpreted + according to the flags f. + + 1) Default constructor. Constructs an empty regular expression which will match + nothing. + 2) Constructs a regex from a null-terminated string s. + 3) Constructs a regex from a sequence of count characters, pointed to by s. + 4) Copy constructor. Constructs a regex by copying other. + 5) Move constructor. Constructs a regex with the contents of other using move + semantics. + 6) Constructs a regex from a string str. + 7) Range constructor. Constructs the string with the contents of the range + [first, last). + 8) Initializer list constructor. Constructs the string with the contents of the + initializer list init. + +.SH Parameters + + s - pointer to a null-terminated string + count - length of a character sequence used to initialize the regex + first, last - range of a character sequence used to initialize the regex + str - a basic_string used as a source used to initialize the regex + other - another regex to use as source to initialize the regex + init - initializer list used to initialize the regex + f - flags used to guide the interpretation of the character sequence as a + regular expression +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 2,3) std::regex_error if the supplied regular expression is not valid. + 4) May throw implementation-defined exceptions. + 6-8) std::regex_error if the supplied regular expression is not valid. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void match_and_print(const std::string& text, const std::regex& pattern) + { + std::sregex_iterator it(text.begin(), text.end(), pattern), it_end; + int count = 0; + for (; it != it_end; ++it) + { + const std::smatch& match = *it; + std::cout << ++count << ". " << std::quoted(match.str()) << '\\n'; + } + std::cout << (count ? "\\n" : "no match found\\n\\n"); + } + + int main() + { + const std::string text = "Hello, World! 12345"; + + // Matches one or more digits + std::string pattern_text = "\\\\d+"; + std::cout << "digits (" << pattern_text << "):\\n"; + auto pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[^\\\\s]+"; + std::cout << "words (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[a-zA-Z]+"; + std::cout << "words without symbols and digits (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one non digits, non alphabet + pattern_text = "[^0-9A-Za-z]"; + std::cout << "symbol (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase + pattern_text = "[a-z]+"; + std::cout << "lowercase (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase with std::regex::icase flag + pattern_text = "[a-z]+"; + std::cout << "lowercase with ignore case flag (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::icase); + match_and_print(text, pattern); + + // Matches basic POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "basic POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::basic); + match_and_print(text, pattern); + + // Matches extended POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "extended POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::extended); + match_and_print(text, pattern); + } + +.SH Output: + + digits (\\d+): + 1. "12345" + + words ([^\\s]+): + 1. "Hello," + 2. "World!" + 3. "12345" + + words without symbols and digits ([a-zA-Z]+): + 1. "Hello" + 2. "World" + + symbol ([^0-9A-Za-z]): + 1. "," + 2. " " + 3. "!" + 4. " " + + lowercase ([a-z]+): + 1. "ello" + 2. "orld" + + lowercase with ignore case flag ([a-z]+): + 1. "Hello" + 2. "World" + + basic POSIX regex ([[:digit:]]+): + no match found + + extended POSIX regex ([[:digit:]]+): + 1. "12345" diff --git a/man/std::regex::swap.3 b/man/std::regex::swap.3 deleted file mode 120000 index 1506664fd..000000000 --- a/man/std::regex::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::swap.3 \ No newline at end of file diff --git a/man/std::regex::swap.3 b/man/std::regex::swap.3 new file mode 100644 index 000000000..7742099ee --- /dev/null +++ b/man/std::regex::swap.3 @@ -0,0 +1,29 @@ +.TH std::basic_regex::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::swap \- std::basic_regex::swap + +.SH Synopsis + void swap( basic_regex& other ) noexcept; \fI(since C++11)\fP + + Exchanges the contents of two regular expressions. + +.SH Parameters + + other - the regular expression to swap with + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::basic_regex) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::regex::~basic_regex.3 b/man/std::regex::~basic_regex.3 deleted file mode 120000 index 538571dc5..000000000 --- a/man/std::regex::~basic_regex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::~basic_regex.3 \ No newline at end of file diff --git a/man/std::regex::~basic_regex.3 b/man/std::regex::~basic_regex.3 new file mode 100644 index 000000000..310ecee74 --- /dev/null +++ b/man/std::regex::~basic_regex.3 @@ -0,0 +1,8 @@ +.TH std::basic_regex::~basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::~basic_regex \- std::basic_regex::~basic_regex + +.SH Synopsis + ~basic_regex(); \fI(since C++11)\fP + + Destroys the regular expression object. diff --git a/man/std::regex_constants::error_type.3 b/man/std::regex_constants::error_type.3 index dd2e0728b..83b2db76b 100644 --- a/man/std::regex_constants::error_type.3 +++ b/man/std::regex_constants::error_type.3 @@ -1,24 +1,68 @@ -.TH std::regex_constants::error_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_constants::error_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_constants::error_type \- std::regex_constants::error_type + .SH Synopsis Defined in header - typedef /*implementation defined*/ error_type; \fI(since C++11)\fP - constexpr error_type error_collate = /*unspecified*/; - - constexpr error_type error_ctype = /*unspecified*/; - constexpr error_type error_escape = /*unspecified*/; - constexpr error_type error_backref = /*unspecified*/; - constexpr error_type error_brack = /*unspecified*/; - constexpr error_type error_paren = /*unspecified*/; - constexpr error_type error_brace = /*unspecified*/; \fI(since C++11)\fP - constexpr error_type error_badbrace = /*unspecified*/; - constexpr error_type error_range = /*unspecified*/; - constexpr error_type error_space = /*unspecified*/; - constexpr error_type error_badrepeat = /*unspecified*/; - constexpr error_type error_complexity = /*unspecified*/; - - constexpr error_type error_stack = /*unspecified*/; - - The error_type is a type that describes errors that may occur during regular + using error_type = /* implementation-defined */; \fB(1)\fP \fI(since C++11)\fP + constexpr error_type error_collate = /* + unspecified */; + + constexpr error_type error_ctype = /* + unspecified */; + constexpr error_type error_escape = /* + unspecified */; + constexpr error_type error_backref = /* + unspecified */; + constexpr error_type error_brack = /* + unspecified */; + constexpr error_type error_paren = /* + unspecified */; + constexpr error_type error_brace = /* \fI(since C++11)\fP + unspecified */; \fI(until C++17)\fP + constexpr error_type error_badbrace = /* + unspecified */; + constexpr error_type error_range = /* + unspecified */; + constexpr error_type error_space = /* + unspecified */; + constexpr error_type error_badrepeat = /* + unspecified */; + constexpr error_type error_complexity = /* + unspecified */; + + constexpr error_type error_stack = /* + unspecified */; \fB(2)\fP + inline constexpr error_type error_collate = /* + unspecified */; + + inline constexpr error_type error_ctype = /* + unspecified */; + inline constexpr error_type error_escape = /* + unspecified */; + inline constexpr error_type error_backref = /* + unspecified */; + inline constexpr error_type error_brack = /* + unspecified */; + inline constexpr error_type error_paren = /* + unspecified */; + inline constexpr error_type error_brace = /* \fI(since C++17)\fP + unspecified */; + inline constexpr error_type error_badbrace = /* + unspecified */; + inline constexpr error_type error_range = /* + unspecified */; + inline constexpr error_type error_space = /* + unspecified */; + inline constexpr error_type error_badrepeat = /* + unspecified */; + inline constexpr error_type error_complexity = /* + unspecified */; + + inline constexpr error_type error_stack = /* + unspecified */; + + 1) The error_type is a type that describes errors that may occur during regular expression parsing. .SH Constants @@ -36,16 +80,123 @@ error_range the expression contains an invalid character range (e.g. [b-a]) error_space there was not enough memory to convert the expression into a finite state machine - error_badrepeat one of *?+{ was not preceded by a valid regular expression + error_badrepeat '*', '?', '+' or '{' was not preceded by a valid regular expression error_complexity the complexity of an attempted match exceeded a predefined level error_stack there was not enough memory to perform a match -.SH Notes +.SH Example + + Implements regular expressions checker: + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void regular_expression_checker(const std::string& text, + const std::string& regex, + const std::regex::flag_type flags) + { + std::cout << "Text: " << std::quoted(text) << '\\n' + << "Regex: " << std::quoted(regex) << '\\n'; + + try + { + const std::regex re{regex, flags}; + const bool matched = std::regex_match(text, re); + + std::stringstream out; + out << (matched ? "MATCH!\\n" : "DOES NOT MATCH!\\n"); + + std::smatch m; + if (std::regex_search(text, m, re); !m.empty()) + { + out << "prefix = [" << m.prefix().str().data() << "]\\n"; + + for (std::size_t i{}; i != m.size(); ++i) + out << " m[" << i << "] = [" << m[i].str().data() << "]\\n"; + + out << "suffix = [" << m.suffix().str().data() << "]\\n"; + } + std::cout << out.str() << '\\n'; + } + catch (std::regex_error& e) + { + std::cout << "Error: " << e.what() << ".\\n\\n"; + } + } + + int main() + { + constexpr std::regex::flag_type your_flags + = std::regex::flag_type{0} + // Choose one of the supported grammars: + | std::regex::ECMAScript + // | std::regex::basic + // | std::regex::extended + // | std::regex::awk + // | std::regex::grep + // | std::regex::egrep + // Choose any of the next options: + // | std::regex::icase + // | std::regex::nosubs + // | std::regex::optimize + // | std::regex::collate + // | std::regex::multiline + ; + + const std::string your_text = "Hello regular expressions."; + const std::string your_regex = R"(([a-zA-Z]+) ([a-z]+) ([a-z]+)\\.)"; + regular_expression_checker(your_text, your_regex, your_flags); + + regular_expression_checker("Invalid!", R"(((.)(.))", your_flags); + regular_expression_checker("Invalid!", R"([.)", your_flags); + regular_expression_checker("Invalid!", R"([.]{})", your_flags); + regular_expression_checker("Invalid!", R"([1-0])", your_flags); + } + +.SH Possible output: + + Text: "Hello regular expressions." + Regex: "([a-zA-Z]+) ([a-z]+) ([a-z]+)\\\\." + MATCH! + prefix = [] + m[0] = [Hello regular expressions.] + m[1] = [Hello] + m[2] = [regular] + m[3] = [expressions] + suffix = [] + + Text: "Invalid!" + Regex: "((.)(.)" + Error: Mismatched '(' and ')' in regular expression. + + Text: "Invalid!" + Regex: "[." + Error: Unexpected character within '[...]' in regular expression. + + Text: "Invalid!" + Regex: "[.]{}" + Error: Invalid range in '{}' in regular expression. + + Text: "Invalid!" + Regex: "[1-0]" + Error: Invalid range in bracket expression.. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - In C++11, these constants were specified with redundant keyword static, which was - removed by C++14 via LWG issue 2053 + DR Applied to Behavior as published Correct behavior + LWG 2053 C++11 the constants were declared static removed the static specifier .SH See also regex_error reports errors generated by the regular expressions library - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::regex_constants::match_flag_type.3 b/man/std::regex_constants::match_flag_type.3 index b95c42d9a..45482fbb3 100644 --- a/man/std::regex_constants::match_flag_type.3 +++ b/man/std::regex_constants::match_flag_type.3 @@ -1,24 +1,67 @@ -.TH std::regex_constants::match_flag_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_constants::match_flag_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_constants::match_flag_type \- std::regex_constants::match_flag_type + .SH Synopsis Defined in header - typedef /*unspecified*/ match_flag_type; - - constexpr match_flag_type match_default = 0; - constexpr match_flag_type match_not_bol = /*unspecified*/; - constexpr match_flag_type match_not_eol = /*unspecified*/; - constexpr match_flag_type match_not_bow = /*unspecified*/; - constexpr match_flag_type match_not_eow = /*unspecified*/; - constexpr match_flag_type match_any = /*unspecified*/; - constexpr match_flag_type match_not_null = /*unspecified*/; - constexpr match_flag_type match_continuous = /*unspecified*/; - constexpr match_flag_type match_prev_avail = /*unspecified*/; - constexpr match_flag_type format_default = 0; - constexpr match_flag_type format_sed = /*unspecified*/; - constexpr match_flag_type format_no_copy = /*unspecified*/; - - constexpr match_flag_type format_first_only = /*unspecified*/; - - match_flag_type is a BitmaskType that specifies additional regular expression + using match_flag_type = /* implementation-defined \fB(1)\fP \fI(since C++11)\fP + */; + constexpr match_flag_type match_default = {}; + + constexpr match_flag_type match_not_bol = /* + unspecified */; + constexpr match_flag_type match_not_eol = /* + unspecified */; + constexpr match_flag_type match_not_bow = /* + unspecified */; + constexpr match_flag_type match_not_eow = /* + unspecified */; + constexpr match_flag_type match_any = /* + unspecified */; + constexpr match_flag_type match_not_null = /* \fI(since C++11)\fP + unspecified */; \fI(until C++17)\fP + constexpr match_flag_type match_continuous = /* + unspecified */; + constexpr match_flag_type match_prev_avail = /* + unspecified */; + constexpr match_flag_type format_default = {}; + constexpr match_flag_type format_sed = /* + unspecified */; + constexpr match_flag_type format_no_copy = /* + unspecified */; + + constexpr match_flag_type format_first_only = /* + unspecified */; + inline constexpr match_flag_type match_default = \fB(2)\fP + {}; + + inline constexpr match_flag_type match_not_bol = + /* unspecified */; + inline constexpr match_flag_type match_not_eol = + /* unspecified */; + inline constexpr match_flag_type match_not_bow = + /* unspecified */; + inline constexpr match_flag_type match_not_eow = + /* unspecified */; + inline constexpr match_flag_type match_any = + /* unspecified */; + inline constexpr match_flag_type match_not_null = \fI(since C++17)\fP + /* unspecified */; + inline constexpr match_flag_type match_continuous = + /* unspecified */; + inline constexpr match_flag_type match_prev_avail = + /* unspecified */; + inline constexpr match_flag_type format_default = + {}; + inline constexpr match_flag_type format_sed = + /* unspecified */; + inline constexpr match_flag_type format_no_copy = + /* unspecified */; + + inline constexpr match_flag_type format_first_only = + /* unspecified */; + + 1) match_flag_type is a BitmaskType that specifies additional regular expression matching options. .SH Constants @@ -26,37 +69,47 @@ Note: [first, last) refers to the character sequence being matched. Constant Explanation - The first character in [first,last) will be treated as if it is - match_not_bol not at the beginning of a line (i.e. ^ will not match - [first,first) - match_not_eol The last character in [first,last) will be treated as if it is not - at the end of a line (i.e. $ will not match [last,last) - match_not_bow "\\b" will not match [first,first) - match_not_eow "\\b" will not match [last,last) + The first character in [first, last) will be treated as if it is + match_not_bol not at the beginning of a line + (i.e. ^ will not match [first, first)). + The last character in [first, last) will be treated as if it is + match_not_eol not at the end of a line + (i.e. $ will not match [last, last)). + match_not_bow \\b will not match [first, first). + match_not_eow \\b will not match [last, last). match_any If more than one match is possible, then any match is an - acceptable result - match_not_null Do not match empty sequences - match_continuous Only match a sub-sequence that begins at first - match_prev_avail --first is a valid iterator position. When set, causes - match_not_bol and match_not_bow to be ignored + acceptable result. + match_not_null Do not match empty sequences. + match_continuous Only match a sub-sequence that begins at first. + match_prev_avail --first is a valid iterator position. + When set, causes match_not_bol and match_not_bow to be ignored. format_default Use ECMAScript rules to construct strings in std::regex_replace - (syntax documentation) - format_sed Use POSIX sed utility rules in std::regex_replace. (syntax - documentation) - format_no_copy Do not copy un-matched strings to the output in std::regex_replace - format_first_only Only replace the first match in std::regex_replace + (syntax documentation). + format_sed Use POSIX sed utility rules in std::regex_replace (syntax + documentation). + format_no_copy Do not copy un-matched strings to the output in + std::regex_replace. + format_first_only Only replace the first match in std::regex_replace. + + All constants, except for match_default and format_default, are bitmask elements. + The match_default and format_default constants are empty bitmasks. + + Defect reports -.SH Notes + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - In C++11, these constants were specified with redundant keyword static, which was - removed by C++14 via LWG issue 2053 + DR Applied to Behavior as published Correct behavior + 1. the constants were declared static 1. removed the static + LWG 2053 C++11 2. match_default and format_default were specifier + initialized from 0 2. initialized from {} .SH See also regex_match attempts to match a regular expression to an entire character \fI(C++11)\fP sequence - \fI(function template)\fP + \fI(function template)\fP syntax_option_type general options controlling regex behavior - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP error_type describes different types of matching errors - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP diff --git a/man/std::regex_constants::syntax_option_type.3 b/man/std::regex_constants::syntax_option_type.3 index f92ea8387..c84b58271 100644 --- a/man/std::regex_constants::syntax_option_type.3 +++ b/man/std::regex_constants::syntax_option_type.3 @@ -1,49 +1,98 @@ -.TH std::regex_constants::syntax_option_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_constants::syntax_option_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_constants::syntax_option_type \- std::regex_constants::syntax_option_type + .SH Synopsis Defined in header - typedef /*unspecified*/ syntax_option_type; - - constexpr syntax_option_type icase = /*unspecified*/; - constexpr syntax_option_type nosubs = /*unspecified*/; - constexpr syntax_option_type optimize = /*unspecified*/; - constexpr syntax_option_type collate = /*unspecified*/; - constexpr syntax_option_type ECMAScript = /*unspecified*/; - constexpr syntax_option_type basic = /*unspecified*/; - constexpr syntax_option_type extended = /*unspecified*/; - constexpr syntax_option_type awk = /*unspecified*/; - constexpr syntax_option_type grep = /*unspecified*/; - - constexpr syntax_option_type egrep = /*unspecified*/; - - The syntax_option_type is a BitmaskType that contains options that govern how + using syntax_option_type = /* implementation-defined \fB(1)\fP \fI(since C++11)\fP + */; + constexpr syntax_option_type icase = /* + unspecified */; + + constexpr syntax_option_type nosubs = /* + unspecified */; + constexpr syntax_option_type optimize = /* + unspecified */; + constexpr syntax_option_type collate = /* + unspecified */; + constexpr syntax_option_type ECMAScript = /* + unspecified */; \fI(since C++11)\fP + constexpr syntax_option_type basic = /* \fI(until C++17)\fP + unspecified */; + constexpr syntax_option_type extended = /* + unspecified */; + constexpr syntax_option_type awk = /* + unspecified */; + constexpr syntax_option_type grep = /* + unspecified */; + + constexpr syntax_option_type egrep = /* + unspecified */; + inline constexpr syntax_option_type icase = /* \fB(2)\fP + unspecified */; + + inline constexpr syntax_option_type nosubs = /* + unspecified */; + inline constexpr syntax_option_type optimize = /* + unspecified */; + inline constexpr syntax_option_type collate = /* + unspecified */; + inline constexpr syntax_option_type ECMAScript = /* + unspecified */; \fI(since C++17)\fP + inline constexpr syntax_option_type basic = /* + unspecified */; + inline constexpr syntax_option_type extended = /* + unspecified */; + inline constexpr syntax_option_type awk = /* + unspecified */; + inline constexpr syntax_option_type grep = /* + unspecified */; + + inline constexpr syntax_option_type egrep = /* + unspecified */; + inline constexpr syntax_option_type multiline = /* \fB(3)\fP \fI(since C++17)\fP + unspecified */; + + 1) The syntax_option_type is a BitmaskType that contains options that govern how regular expressions behave. - - The possible values for this type (icase, optimize, etc.) are duplicated inside + 2,3) The possible values (icase, optimize, etc.) for type \fB(1)\fP are duplicated inside std::basic_regex. .SH Constants - Value Effect(s) - icase Character matching should be performed without regard to case. - nosubs When performing matches, no sub-expression matches should be stored in - the supplied std::regex_match structure. - Instructs the regular expression engine to make matching faster, with the - optimize potential cost of making construction slower. For example, this might - mean converting a non-deterministic FSA to a deterministic FSA. - collate Character ranges of the form "[a-b]" will be locale sensitive. - ECMAScript Use the Modified ECMAScript regular expression grammar - basic Use the basic POSIX regular expression grammar (grammar documentation). - extended Use the extended POSIX regular expression grammar (grammar - documentation). - awk Use the regular expression grammar used by the awk utility in POSIX - (grammar documentation) - Use the regular expression grammar used by the grep utility in POSIX. - grep This is effectively the same as the basic option with the addition of - newline '\\n' as an alternation separator. - Use the regular expression grammar used by the grep utility, with the -E - egrep option, in POSIX. This is effectively the same as the extended option - with the addition of newline '\\n' as an alternation separator in addtion - to '|'. + Grammar option Effect(s) + ECMAScript Use the Modified ECMAScript regular expression grammar. + basic Use the basic POSIX regular expression grammar (grammar + documentation). + extended Use the extended POSIX regular expression grammar (grammar + documentation). + awk Use the regular expression grammar used by the awk utility in + POSIX (grammar documentation). + Use the regular expression grammar used by the grep utility in + grep POSIX. This is effectively the same as the basic option with the + addition of newline '\\n' as an alternation separator. + Use the regular expression grammar used by the grep utility, with + egrep the -E option, in POSIX. This is effectively the same as the + extended option with the addition of newline '\\n' as an + alternation separator in addition to '|'. + Grammar variation Effect(s) + icase Character matching should be performed without regard to case. + When performing matches, all marked sub-expressions (expr) are + nosubs treated as non-marking sub-expressions (?:expr). No matches are + stored in the supplied std::regex_match structure and mark_count() + is zero. + Instructs the regular expression engine to make matching faster, + optimize with the potential cost of making construction slower. For + example, this might mean converting a non-deterministic FSA to a + deterministic FSA. + collate Character ranges of the form "[a-b]" will be locale sensitive. + multiline \fI(C++17)\fP Specifies that ^ shall match the beginning of a line and $ shall + match the end of a line, if the ECMAScript engine is selected. + + At most one grammar option can be chosen out of ECMAScript, basic, extended, awk, + grep, egrep. If no grammar is chosen, ECMAScript is assumed to be selected. The + other options serve as variations, such that std::regex("meow", std::regex::icase) + is equivalent to std::regex("meow", std::regex::ECMAScript|std::regex::icase). .SH Notes @@ -51,46 +100,51 @@ subsequence is matched, and if there are several such subsequences, the first one is matched), it is not suitable, for example, for parsing markup languages: a POSIX regex such as "]*>.*" would match everything from the first "", including every "" and "" inbetween. On the other + the last "", including every "" and "" in-between. On the other hand, ECMAScript supports non-greedy matches, and the ECMAScript regex "]*>.*?" would match only until the first closing tag. - In C++11, these constants were specified with redundant keyword static, which was - removed by C++14 via LWG issue 2053 - .SH Example Illustrates the difference in the matching algorithm between ECMAScript and POSIX - regular expressions + regular expressions: + - // Run this code #include - #include #include - + #include + int main() { std::string str = "zzxayyzz"; std::regex re1(".*(a|xayy)"); // ECMA std::regex re2(".*(a|xayy)", std::regex::extended); // POSIX - + std::cout << "Searching for .*(a|xayy) in zzxayyzz:\\n"; std::smatch m; std::regex_search(str, m, re1); - std::cout << " ECMA (depth first search) match: " << m[0] << '\\n'; + std::cout << " ECMA (depth first search) match: " << m[0] << '\\n'; std::regex_search(str, m, re2); - std::cout << " POSIX (leftmost longest) match: " << m[0] << '\\n'; + std::cout << " POSIX (leftmost longest) match: " << m[0] << '\\n'; } .SH Output: Searching for .*(a|xayy) in zzxayyzz: - ECMA (depth first search) match: zzxa - POSIX (leftmost longest) match: zzxayy + ECMA (depth first search) match: zzxa + POSIX (leftmost longest) match: zzxayy + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2053 C++11 the constants were declared static removed the static specifier .SH See also basic_regex regular expression object - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::regex_error.3 b/man/std::regex_error.3 index dccebff87..af269458a 100644 --- a/man/std::regex_error.3 +++ b/man/std::regex_error.3 @@ -1,61 +1,61 @@ -.TH std::regex_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_error \- std::regex_error + .SH Synopsis Defined in header - class regex_error : public std::runtime_error { - - public: - explicit regex_error(std::regex_constants::error_type ecode); \fI(since C++11)\fP - std::regex_constants::error_type code() const; - - }; + class regex_error; \fI(since C++11)\fP Defines the type of exception object thrown to report errors in the regular expressions library. std-regex error-inheritance.svg - About this image Inheritance diagram .SH Member functions constructor constructs a regex_error object - \fI(public member function)\fP + \fI(public member function)\fP + operator= replaces the regex_error object + \fI(public member function)\fP code gets the std::regex_constants::error_type for a regex_error - \fI(public member function)\fP + \fI(public member function)\fP + +Inherited from std::runtime_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code - #include #include - + #include + int main() { - try { + try + { std::regex re("[a-b][a"); } - - catch (const std::regex_error& e) { + catch (const std::regex_error& e) + { std::cout << "regex_error caught: " << e.what() << '\\n'; - if (e.code() == std::regex_constants::error_brack) { + if (e.code() == std::regex_constants::error_brack) std::cout << "The code was error_brack\\n"; - } } } -.SH Output: +.SH Possible output: regex_error caught: The expression contained mismatched [ and ]. The code was error_brack diff --git a/man/std::regex_error::code.3 b/man/std::regex_error::code.3 index 048077093..21c77b8c8 100644 --- a/man/std::regex_error::code.3 +++ b/man/std::regex_error::code.3 @@ -1,4 +1,7 @@ -.TH std::regex_error::code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_error::code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_error::code \- std::regex_error::code + .SH Synopsis Defined in header std::regex_constants::error_type code() const; \fI(since C++11)\fP @@ -6,9 +9,9 @@ Returns the std::regex_constants::error_type that was passed to the std::regex_error constructor. -.SH See Also +.SH See also error_type describes different types of matching errors - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP constructor constructs a regex_error object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::regex_error::operator=.3 b/man/std::regex_error::operator=.3 new file mode 100644 index 000000000..cd6dc656f --- /dev/null +++ b/man/std::regex_error::operator=.3 @@ -0,0 +1,25 @@ +.TH std::regex_error::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_error::operator= \- std::regex_error::operator= + +.SH Synopsis + regex_error& operator=( const regex_error& other ) noexcept; \fI(since C++11)\fP + + Assigns the contents with those of other. If *this and other both have dynamic type + std::regex_error then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another regex_error object to assign with + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::regex_error::regex_error.3 b/man/std::regex_error::regex_error.3 index 3fb3a2387..c03167612 100644 --- a/man/std::regex_error::regex_error.3 +++ b/man/std::regex_error::regex_error.3 @@ -1,12 +1,24 @@ -.TH std::regex_error::regex_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_error::regex_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_error::regex_error \- std::regex_error::regex_error + .SH Synopsis Defined in header - regex_error(std::regex_constants::error_type ecode); \fI(since C++11)\fP + regex_error( std::regex_constants::error_type ecode ); \fB(1)\fP \fI(since C++11)\fP + regex_error( const regex_error& other ); \fB(2)\fP \fI(since C++11)\fP + + 1) Constructs a regex_error with a given ecode of type + std::regex_constants::error_type. + 2) Copy constructor. Initializes the contents with those of other. If *this and + other both have dynamic type std::regex_error then std::strcmp(what(), other.what()) + == 0. + +.SH Parameters - Constructs a regex_error with a given ecode of type std::regex_constants::error_type - . + ecode - error code indicating the error raised in regular expression parsing + other - another regex_error object to copy -.SH See Also +.SH See also error_type describes different types of matching errors - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP diff --git a/man/std::regex_iterator.3 b/man/std::regex_iterator.3 index a65f216c4..b608ba10e 100644 --- a/man/std::regex_iterator.3 +++ b/man/std::regex_iterator.3 @@ -1,18 +1,24 @@ -.TH std::regex_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_iterator \- std::regex_iterator + .SH Synopsis + Defined in header template< - class BidirIt, - class CharT = typename std::iterator_traits::value_type, \fI(since C++11)\fP - class Traits = std::regex_traits + class BidirIt, + class CharT = typename std::iterator_traits::value_type, \fI(since C++11)\fP + class Traits = std::regex_traits > class regex_iterator - std::regex_iterator is a read-only ForwardIterator that accesses the individual - matches of a regular expression within the underlying character sequence. + std::regex_iterator is a read-only iterator that accesses the individual matches of + a regular expression within the underlying character sequence. It meets the + requirements of a LegacyForwardIterator, except that for dereferenceable values a + and b with a == b, *a and *b will not be bound to the same object. On construction, and on every increment, it calls std::regex_search and remembers - the result (that is, saves a copy of the value std::match_results). The + the result (that is, saves a copy of the std::match_results value). The first object may be read when the iterator is constructed or when the first dereferencing is done. Otherwise, dereferencing only returns a copy of the most recently obtained regex match. @@ -24,45 +30,36 @@ A typical implementation of std::regex_iterator holds the begin and the end iterators for the underlying sequence (two instances of BidirIt), a pointer to the - regular expression (const regex_type*) and the match flags + regular expression (const regex_type*), the match flags (std::regex_constants::match_flag_type), and the current match (std::match_results). -.SH Contents - - * 1 Type requirements - * 2 Specializations - * 3 Member types - * 4 Member functions - * 5 Notes - * 6 Example - * 7 See also - .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Specializations Several specializations for common character sequence types are defined: Defined in header - Type Definition - cregex_iterator regex_iterator - wcregex_iterator regex_iterator - sregex_iterator regex_iterator - wsregex_iterator regex_iterator + Type Definition + std::cregex_iterator std::regex_iterator + std::wcregex_iterator std::regex_iterator + std::sregex_iterator std::regex_iterator + std::wsregex_iterator std::regex_iterator .SH Member types - Member type Definition - value_type std::match_results - difference_type std::ptrdiff_t - pointer const value_type* - reference const value_type& - iterator_category std::forward_iterator_tag - regex_type basic_regex + Member type Definition + value_type std::match_results + difference_type std::ptrdiff_t + pointer const value_type* + reference const value_type& + iterator_category std::forward_iterator_tag + iterator_concept (C++20) std::input_iterator_tag + regex_type std::basic_regex .SH Member functions @@ -74,6 +71,7 @@ \fI(public member function)\fP operator== compares two regex_iterators operator!= \fI(public member function)\fP + (removed in C++20) operator* accesses the current match operator-> \fI(public member function)\fP operator++ advances the iterator to the next match @@ -92,12 +90,12 @@ .SH Example - + // Run this code - #include - #include #include + #include + #include #include int main() @@ -105,15 +103,13 @@ const std::string s = "Quick brown fox."; std::regex words_regex("[^\\\\s]+"); - auto words_begin = - std::sregex_iterator(s.begin(), s.end(), words_regex); + auto words_begin = std::sregex_iterator(s.begin(), s.end(), words_regex); auto words_end = std::sregex_iterator(); - std::cout << "Found " - << std::distance(words_begin, words_end) - << " words:\\n"; + std::cout << "Found " << std::distance(words_begin, words_end) << " words:\\n"; - for (std::sregex_iterator i = words_begin; i != words_end; ++i) { + for (std::sregex_iterator i = words_begin; i != words_end; ++i) + { std::smatch match = *i; std::string match_str = match.str(); std::cout << match_str << '\\n'; @@ -127,11 +123,23 @@ brown fox. -.SH See also + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + DR Applied to Behavior as published Correct behavior + LWG 3698 C++20 regex_iterator was a forward_iterator made input_iterator^[1] + (P2770R0) while being a stashing iterator + + 1. ↑ iterator_category was unchanged by the resolution, because changing it to + std::input_iterator_tag might break too much existing code. + +.SH See also match_results identifies one regular expression match, including all sub-expression \fI(C++11)\fP matches \fI(class template)\fP - regex_search check if a regular expression occurs anywhere within a string - \fI(C++11)\fP \fI(function template)\fP + regex_search attempts to match a regular expression to any part of a character + \fI(C++11)\fP sequence + \fI(function template)\fP diff --git a/man/std::regex_iterator::operator*,operator->.3 b/man/std::regex_iterator::operator*,operator->.3 index eb983477f..128d9cf33 100644 --- a/man/std::regex_iterator::operator*,operator->.3 +++ b/man/std::regex_iterator::operator*,operator->.3 @@ -1,18 +1,37 @@ -.TH std::regex_iterator::operator*,operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_iterator::operator*,operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_iterator::operator*,operator-> \- std::regex_iterator::operator*,operator-> + .SH Synopsis const value_type& operator*() const; \fB(1)\fP \fI(since C++11)\fP const value_type* operator->() const; \fB(2)\fP \fI(since C++11)\fP - Extracts the current std::regex_match from a regex_iterator: + Extracts the current std::match_results from a regex_iterator. + +.SH Return value - 1) Returns a reference to the current std::regex_match. - 2) Returns a pointer to the current std::regex_match. + 1) Returns a reference to the current std::match_results. + 2) Returns a pointer to the current std::match_results. .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + + int main() + { + std::string hay{"1.1a2b3cjk34"}; + std::regex needle("[1234]"); + using Ri = std::regex_iterator; + for (Ri it{hay.begin(), hay.end(), needle}, last{}; it != last; ++it) + std::cout << it->str(); + std::cout << '\\n'; + } + +.SH Output: - * Todo no example + 112334 diff --git a/man/std::regex_iterator::operator++,operator++(int).3 b/man/std::regex_iterator::operator++,operator++(int).3 index d1f9148c9..06ebbeda1 100644 --- a/man/std::regex_iterator::operator++,operator++(int).3 +++ b/man/std::regex_iterator::operator++,operator++(int).3 @@ -1,7 +1,10 @@ -.TH std::regex_iterator::operator++,operator++(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_iterator::operator++,operator++(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_iterator::operator++,operator++(int) \- std::regex_iterator::operator++,operator++(int) + .SH Synopsis - regex_iterator& operator++(); \fI(since C++11)\fP - regex_iterator operator++(int); \fI(since C++11)\fP + regex_iterator& operator++(); \fI(since C++11)\fP + regex_iterator operator++( int ); \fI(since C++11)\fP Advances the iterator on the next match. @@ -18,8 +21,8 @@ following: regex_search(start, end, match, *pregex, - flags | regex_constants::match_not_null | - regex_constants::match_continuous); + flags | regex_constants::match_not_null | + regex_constants::match_continuous); If the call returns true, the function returns. @@ -58,5 +61,4 @@ 1) *this 2) The previous value of the iterator. .SH Category: - * Todo with reason diff --git a/man/std::regex_iterator::operator=.3 b/man/std::regex_iterator::operator=.3 index 5fc51cbdd..33949109f 100644 --- a/man/std::regex_iterator::operator=.3 +++ b/man/std::regex_iterator::operator=.3 @@ -1,4 +1,7 @@ -.TH std::regex_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_iterator::operator= \- std::regex_iterator::operator= + .SH Synopsis regex_iterator& operator=( const regex_iterator& other ); \fI(since C++11)\fP @@ -10,4 +13,4 @@ .SH Return value - *this. + *this diff --git a/man/std::regex_iterator::operator==,operator!=.3 b/man/std::regex_iterator::operator==,operator!=.3 index a9293edfa..244b299f4 100644 --- a/man/std::regex_iterator::operator==,operator!=.3 +++ b/man/std::regex_iterator::operator==,operator!=.3 @@ -1,10 +1,22 @@ -.TH std::regex_iterator::operator==,operator!= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_iterator::operator==,operator!= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_iterator::operator==,operator!= \- std::regex_iterator::operator==,operator!= + .SH Synopsis - bool operator==(const regex_iterator& rhs) const; \fB(1)\fP \fI(since C++11)\fP - bool operator!=(const regex_iterator& rhs) const; \fB(2)\fP \fI(since C++11)\fP + bool operator==( const regex_iterator& rhs ) const; \fB(1)\fP \fI(since C++11)\fP + bool operator!=( const regex_iterator& rhs ) const; \fB(2)\fP \fI(since C++11)\fP + \fI(until C++20)\fP Compares two regex_iterators. + The != operator is synthesized from operator==. \fI(since C++20)\fP + +.SH Parameters + + rhs - a regex_iterator to compare to + +.SH Return value + For the sake of exposition, assume that regex_iterator contains the following members: @@ -13,21 +25,14 @@ * const regex_type *pregex; * std::regex_constants::match_flag_type flags; * std::match_results match; - 1) Returns true if *this and rhs are both end-of-sequence iterators, or if all of the following conditions are true: - * begin == rhs.begin * end == rhs.end * pregex == rhs.pregex * flags == rhs.flags * match[0] == rhs.match[0] - - 2) Returns !(*this == rhs) - -.SH Parameters - - rhs - a regex_iterator to compare to + 2) Returns !(*this == rhs). .SH Example @@ -35,5 +40,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::regex_iterator::regex_iterator.3 b/man/std::regex_iterator::regex_iterator.3 index 125b8dd3d..d97e1e083 100644 --- a/man/std::regex_iterator::regex_iterator.3 +++ b/man/std::regex_iterator::regex_iterator.3 @@ -1,13 +1,23 @@ -.TH std::regex_iterator::regex_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_iterator::regex_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_iterator::regex_iterator \- std::regex_iterator::regex_iterator + .SH Synopsis - regex_iterator(); \fB(1)\fP \fI(since C++11)\fP - regex_iterator(BidirIt a, BidirIt b, + regex_iterator(); \fB(1)\fP \fI(since C++11)\fP + regex_iterator( BidirIt a, BidirIt b, + + const regex_type& re, \fB(2)\fP \fI(since C++11)\fP + std::regex_constants::match_flag_type m = + + std::regex_constants::match_default ); + regex_iterator( const regex_iterator& ); \fB(3)\fP \fI(since C++11)\fP + regex_iterator( BidirIt, BidirIt, - const regex_type& re, \fB(2)\fP \fI(since C++11)\fP - std::regex_constants::match_flag_type m = + const regex_type&&, + std::regex_constants::match_flag_type = \fB(4)\fP \fI(since C++11)\fP - std::regex_constants::match_default); - regex_iterator(const regex_iterator&); \fB(3)\fP \fI(since C++11)\fP + std::regex_constants::match_default ) = + delete; Constructs a new regex_iterator: @@ -17,19 +27,58 @@ performs an initial call to std::regex_search with this data. If the result of this initial call is false, *this is set to an end-of-sequence iterator. 3) Copies a regex_iterator. + 4) The overload \fB(2)\fP is not allowed to be called with a temporary regex, since the + returned iterator would be immediately invalidated. .SH Parameters - a - BidirIt to the beginning of the target character sequence - b - BidirIt to the end of the targe character sequence + a - LegacyBidirectionalIterator to the beginning of the target character sequence + b - LegacyBidirectionalIterator to the end of the target character sequence re - regular expression used to search the target character sequence m - flags that govern the behavior of re .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view str{R"( + #ONE: *p = &Mass; + #Two: MOV %rd, 42 + )"}; + const std::regex re("[a-w]"); + + // create regex_iterator, overload (2) + auto it = std::regex_iterator + { + str.cbegin(), str.cend(), + re // re is lvalue; if an immediate expression was used + // instead, e.g. std::regex{"[a-z]"}, this would + // produce an error since overload (4) is deleted + }; + + for (decltype(it) last /* overload (1) */; it != last; ++it) + std::cout << (*it).str(); + std::cout << '\\n'; + } + +.SH Output: + + password + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo no example + DR Applied to Behavior as published Correct behavior + a regex_iterator constructed + LWG 2332 C++11 from a temporary such construction is disallowed via + basic_regex became invalid a deleted overload + immediately diff --git a/man/std::regex_match.3 b/man/std::regex_match.3 index d84046a8a..3e18cf479 100644 --- a/man/std::regex_match.3 +++ b/man/std::regex_match.3 @@ -1,72 +1,97 @@ -.TH std::regex_match 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_match 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_match \- std::regex_match + .SH Synopsis Defined in header template< class BidirIt, class Alloc, class CharT, class Traits > - bool regex_match( BidirIt first, BidirIt last, (since - std::match_results& m, \fB(1)\fP C++11) - const std::basic_regex& e, + bool regex_match( BidirIt first, BidirIt last, + std::match_results& m, \fB(1)\fP \fI(since C++11)\fP + const std::basic_regex& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); template< class BidirIt, class CharT, class Traits > - bool regex_match( BidirIt first, BidirIt last, \fB(2)\fP (since - const std::basic_regex& e, C++11) + bool regex_match( BidirIt first, BidirIt last, \fB(2)\fP \fI(since C++11)\fP + const std::basic_regex& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); template< class CharT, class Alloc, class Traits > bool regex_match( const CharT* str, - std::match_results& m, \fB(3)\fP (since - const std::basic_regex& e, C++11) + std::match_results& m, \fB(3)\fP \fI(since C++11)\fP + const std::basic_regex& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); template< class STraits, class SAlloc, class Alloc, class CharT, class Traits > - bool regex_match( const std::basic_string& s, + bool regex_match( const std::basic_string& + s, std::match_results< - typename (since - std::basic_string::const_iterator, \fB(4)\fP C++11) - Alloc - >& m, - const std::basic_regex& e, + typename std::basic_string:: + const_iterator, + Alloc>& m, + const std::basic_regex& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); template< class CharT, class Traits > - bool regex_match( const CharT* str, (since - const std::basic_regex& e, \fB(5)\fP C++11) + bool regex_match( const CharT* str, + const std::basic_regex& e, \fB(5)\fP \fI(since C++11)\fP std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); template< class STraits, class SAlloc, class CharT, class Traits > - bool regex_match( const std::basic_string& s, \fB(6)\fP (since - const std::basic_regex& e, C++11) + bool regex_match( const std::basic_string& + s, \fB(6)\fP \fI(since C++11)\fP + const std::basic_regex& e, std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); + template< class STraits, class SAlloc, + + class Alloc, class CharT, class Traits > + bool regex_match( const std::basic_string&&, + std::match_results< + typename std::basic_string:: \fB(7)\fP \fI(since C++11)\fP + const_iterator, + Alloc>&, + const std::basic_regex&, + std::regex_constants::match_flag_type flags = + + std::regex_constants::match_default ) = + delete; - Determines if the regular expression el matches the given target. + Determines if the regular expression e matches the entire target character sequence, + which may be specified as std::string, a C-string, or an iterator pair. 1) Determines if there is a match between the regular expression e and the entire - target character sequence [first,last), taking into account the effect of flags. - Match results are returned in m. + target character sequence [first, last), taking into account the effect of flags. + When determining if there is a match, only potential matches that match the entire + character sequence are considered. Match results are returned in m. 2) Behaves as \fB(1)\fP above, omitting the match results. - 3) Returns std::regex_match(str, str + std::char_traits::length(str), m, e, + 3) Returns std::regex_match(str, str + std::char_traits::length(str), m, e, flags). 4) Returns std::regex_match(s.begin(), s.end(), m, e, flags). - 5) Returns std::regex_match(str, str + std::char_traits::length(str), e, + 5) Returns std::regex_match(str, str + std::char_traits::length(str), e, flags). 6) Returns std::regex_match(s.begin(), s.end(), e, flags). + 7) The overload \fB(4)\fP is prohibited from accepting temporary strings, otherwise this + function populates match_results m with string iterators that become invalid + immediately. Note that regex_match will only successfully match a regular expression to an entire character sequence, whereas std::regex_search will successfully match subsequences. @@ -81,7 +106,7 @@ flags - flags used to determine how the match will be performed .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Return value @@ -98,7 +123,8 @@ m.ready() true m.empty() false - m.size() number of subexpressions plus 1, that is, 1+e.mark_count() + m.size() number of marked subexpressions plus 1, that is, 1 + + e.mark_count() m.prefix().first first m.prefix().second first m.prefix().matched false (the match prefix is empty) @@ -108,62 +134,74 @@ m[0].first first m[0].second last m[0].matched true (the entire sequence is matched) - m[n].first the start of the sequence that matched sub-expression n, or last - if the subexpression did not participate in the match - m[n].second the end of the sequence that matched sub-expression n, or last if - the subexpression did not participate in the match + m[n].first the start of the sequence that matched marked sub-expression n, + or last if the subexpression did not participate in the match + m[n].second the end of the sequence that matched marked sub-expression n, or + last if the subexpression did not participate in the match m[n].matched true if sub-expression n participated in the match, false otherwise +.SH Notes + + Because regex_match only considers full matches, the same regex may give different + matches between regex_match and std::regex_search: + + std::regex re("Get|GetValue"); + std::cmatch m; + std::regex_search("GetValue", m, re); // returns true, and m[0] contains "Get" + std::regex_match ("GetValue", m, re); // returns true, and m[0] contains "GetValue" + std::regex_search("GetValues", m, re); // returns true, and m[0] contains "Get" + std::regex_match ("GetValues", m, re); // returns false + .SH Example - + // Run this code + #include #include - #include #include - + #include + int main() { // Simple regular expression matching - std::string fnames[] = {"foo.txt", "bar.txt", "baz.dat", "zoidberg"}; - std::regex txt_regex("[a-z]+\\\\.txt"); - - for (const auto &fname : fnames) { + const std::string fnames[] = {"foo.txt", "bar.txt", "baz.dat", "zoidberg"}; + const std::regex txt_regex("[a-z]+\\\\.txt"); + + for (const auto& fname : fnames) std::cout << fname << ": " << std::regex_match(fname, txt_regex) << '\\n'; - } - + // Extraction of a sub-match - std::regex base_regex("([a-z]+)\\\\.txt"); + const std::regex base_regex("([a-z]+)\\\\.txt"); std::smatch base_match; - - for (const auto &fname : fnames) { - if (std::regex_match(fname, base_match, base_regex)) { + + for (const auto& fname : fnames) + if (std::regex_match(fname, base_match, base_regex)) // The first sub_match is the whole string; the next // sub_match is the first parenthesized expression. - if (base_match.size() == 2) { + if (base_match.size() == 2) + { std::ssub_match base_sub_match = base_match[1]; std::string base = base_sub_match.str(); std::cout << fname << " has a base of " << base << '\\n'; } - } - } - + // Extraction of several sub-matches - std::regex pieces_regex("([a-z]+)\\\\.([a-z]+)"); + const std::regex pieces_regex("([a-z]+)\\\\.([a-z]+)"); std::smatch pieces_match; - - for (const auto &fname : fnames) { - if (std::regex_match(fname, pieces_match, pieces_regex)) { + + for (const auto& fname : fnames) + if (std::regex_match(fname, pieces_match, pieces_regex)) + { std::cout << fname << '\\n'; - for (size_t i = 0; i < pieces_match.size(); ++i) { + for (std::size_t i = 0; i < pieces_match.size(); ++i) + { std::ssub_match sub_match = pieces_match[i]; std::string piece = sub_match.str(); std::cout << " submatch " << i << ": " << piece << '\\n'; } } - } } .SH Output: @@ -187,13 +225,23 @@ submatch 1: baz submatch 2: dat + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + basic_string rvalues were accepted, which rejected via a deleted + LWG 2329 C++11 was likely to result in dangling overload + iterators + .SH See also basic_regex regular expression object - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP match_results identifies one regular expression match, including all sub-expression \fI(C++11)\fP matches - \fI(class template)\fP + \fI(class template)\fP regex_search attempts to match a regular expression to any part of a character \fI(C++11)\fP sequence - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::regex_replace.3 b/man/std::regex_replace.3 index 5b2b1850e..35e3dbabe 100644 --- a/man/std::regex_replace.3 +++ b/man/std::regex_replace.3 @@ -1,4 +1,7 @@ -.TH std::regex_replace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_replace \- std::regex_replace + .SH Synopsis Defined in header template< class OutputIt, class BidirIt, @@ -71,29 +74,31 @@ regex_replace uses a regular expression to perform substitution on a sequence of characters: - 1) Copies characters in the range [first,last) to out, replacing any sequences that + 1) Copies characters in the range [first, last) to out, replacing any sequences that match re with characters formatted by fmt. In other words: * Constructs a std::regex_iterator object i as if by std::regex_iterator i(first, last, re, flags), and uses it to step through every - match of re within the sequence [first,last). + match of re within the sequence [first, last). * For each such match m, copies the non-matched subsequence (m.prefix()) into out - as-is and then replaces the matched subsequence with the formatted replacement - string as if by calling m.format(out, fmt, flags). + as if by out = std::copy(m.prefix().first, m.prefix().second, out) and then + replaces the matched subsequence with the formatted replacement string as if by + calling out = m.format(out, fmt, flags). * When no more matches are found, copies the remaining non-matched characters to - out. - * If there are no matches, copies the entire sequence into out as-is. + out as if by out = std::copy(last_m.suffix().first, last_m.suffix().second, out) + where last_m is a copy of the last match found. + * If there are no matches, copies the entire sequence into out as-is, by out = + std::copy(first, last, out). * If flags contains std::regex_constants::format_no_copy, the non-matched subsequences are not copied into out. * If flags contains std::regex_constants::format_first_only, only the first match is replaced. - - 2) same as 1), but the formatted replacement is performed as if by calling - m.format(out, fmt, fmt + char_traits::length(fmt), flags) - 3-4) Constructs an empty string result of type std::basic_string and + 2) Same as \fB(1)\fP, but the formatted replacement is performed as if by calling out = + m.format(out, fmt, fmt + char_traits::length(fmt), flags). + 3,4) Constructs an empty string result of type std::basic_string and calls std::regex_replace(std::back_inserter(result), s.begin(), s.end(), re, fmt, flags). - 5-6) Constructs an empty string result of type std::basic_string and calls + 5,6) Constructs an empty string result of type std::basic_string and calls std::regex_replace(std::back_inserter(result), s, s + std::char_traits::length(s), re, fmt, flags). @@ -103,19 +108,19 @@ s - the input character sequence, represented as std::basic_string or character array re - the std::basic_regex that will be matched against the input sequence - flags - the match flags of type std::regex_constants::match_flag_type fmt - the regex replacement format string, exact syntax depends on the value of flags + flags - the match flags of type std::regex_constants::match_flag_type out - output iterator to store the result of the replacement .SH Type requirements - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Return value - 1-2) Returns a copy of the output iterator out. + 1,2) Returns a copy of the output iterator out after all the insertions. 3-6) Returns the string result which contains the output. .SH Exceptions @@ -124,23 +129,23 @@ .SH Example - + // Run this code #include #include #include #include - + int main() { std::string text = "Quick brown fox"; std::regex vowel_re("a|e|i|o|u"); - + // write the results to an output iterator std::regex_replace(std::ostreambuf_iterator(std::cout), text.begin(), text.end(), vowel_re, "*"); - + // construct a string holding the results std::cout << '\\n' << std::regex_replace(text, vowel_re, "[$&]") << '\\n'; } @@ -154,6 +159,9 @@ regex_search attempts to match a regular expression to any part of a character \fI(C++11)\fP sequence - \fI(function template)\fP + \fI(function template)\fP match_flag_type options specific to matching - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP + replaces specified portion of a string + replace \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::regex_search.3 b/man/std::regex_search.3 index a60fae5b4..1f6bd6c3e 100644 --- a/man/std::regex_search.3 +++ b/man/std::regex_search.3 @@ -1,4 +1,7 @@ -.TH std::regex_search 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_search \- std::regex_search + .SH Synopsis Defined in header template< class BidirIt, @@ -10,10 +13,10 @@ std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); - template< class Alloc, class CharT, class Traits > + template< class CharT, class Alloc, class Traits > bool regex_search( const CharT* str, - std::match_results& m, \fB(2)\fP (since + std::match_results& m, \fB(2)\fP (since const std::basic_regex& e, C++11) std::regex_constants::match_flag_type flags = @@ -54,15 +57,31 @@ std::regex_constants::match_flag_type flags = std::regex_constants::match_default ); + template< class STraits, class SAlloc, + + class Alloc, class CharT, class Traits > + bool regex_search( const std::basic_string&&, + std::match_results< + typename (since + std::basic_string::const_iterator, \fB(7)\fP C++11) + Alloc + >&, + const std::basic_regex&, + std::regex_constants::match_flag_type flags = + + std::regex_constants::match_default ) = delete; Determines if there is a match between the regular expression e and some subsequence in the target character sequence. - 1) Analyzes generic range [first,last). Match results are returned in m. - 2) Analyzes a null-terminates string pointed to by str. Match results are returned + 1) Analyzes generic range [first, last). Match results are returned in m. + 2) Analyzes a null-terminated string pointed to by str. Match results are returned in m. 3) Analyzes a string s. Match results are returned in m. 4-6) Equivalent to (1-3), just omits the match results. + 7) The overload \fB(3)\fP is prohibited from accepting temporary strings, otherwise this + function populates match_results m with string iterators that become invalid + immediately. regex_search will successfully match any subsequence of the given sequence, whereas std::regex_match will only return true if the regular expression matches the entire @@ -78,7 +97,7 @@ flags - std::regex_constants::match_flag_type governing search behavior .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. - Alloc must meet the requirements of Allocator. @@ -97,7 +116,8 @@ m.ready() true m.empty() false - m.size() number of subexpressions plus 1, that is, 1+e.mark_count() + m.size() number of marked subexpressions plus 1, that is, 1 + + e.mark_count() m.prefix().first first m.prefix().second m[0].first m.prefix().matched m.prefix().first != m.prefix().second @@ -106,73 +126,124 @@ m.suffix().matched m.suffix().first != m.suffix().second m[0].first the start of the matching sequence m[0].second the end of the matching sequence - m[0].matched true if a match was found, false otherwise - m[n].first the start of the sequence that matched sub-expression n, or last - if the subexpression did not participate in the match - m[n].second the end of the sequence that matched sub-expression n, or last if - the subexpression did not participate in the match + m[0].matched true + m[n].first the start of the sequence that matched marked sub-expression n, + or last if the subexpression did not participate in the match + m[n].second the end of the sequence that matched marked sub-expression n, or + last if the subexpression did not participate in the match m[n].matched true if sub-expression n participated in the match, false otherwise +.SH Notes + + In order to examine all matches within the target sequence, std::regex_search may be + called in a loop, restarting each time from m[0].second of the previous call. + std::regex_iterator offers an easy interface to this iteration. + .SH Example - + // Run this code + #include #include - #include #include - + #include + int main() { std::string lines[] = {"Roses are #ff0000", "violets are #0000ff", "all of my base are belong to you"}; - + std::regex color_regex("#([a-f0-9]{2})" "([a-f0-9]{2})" "([a-f0-9]{2})"); - - for (const auto &line : lines) { - std::cout << line << ": " + + // simple match + for (const auto& line : lines) + std::cout << line << ": " << std::boolalpha << std::regex_search(line, color_regex) << '\\n'; - } - + std::cout << '\\n'; + + // show contents of marked subexpressions within each match std::smatch color_match; - for (const auto &line : lines) { - std::regex_search(line, color_match, color_regex); - std::cout << "matches for '" << line << "'\\n"; - for (size_t i = 0; i < color_match.size(); ++i) { - std::ssub_match sub_match = color_match[i]; - std::string sub_match_str = sub_match.str(); - std::cout << i << ": " << sub_match_str << '\\n'; + for (const auto& line : lines) + if (std::regex_search(line, color_match, color_regex)) + { + std::cout << "matches for '" << line << "'\\n"; + std::cout << "Prefix: '" << color_match.prefix() << "'\\n"; + for (std::size_t i = 0; i < color_match.size(); ++i) + std::cout << i << ": " << color_match[i] << '\\n'; + std::cout << "Suffix: '" << color_match.suffix() << "\\'\\n\\n"; } + + // repeated search (see also std::regex_iterator) + std::string log(R"( + Speed: 366 + Mass: 35 + Speed: 378 + Mass: 32 + Speed: 400 + Mass: 30)"); + std::regex r(R"(Speed:\\t\\d*)"); + for (std::smatch sm; regex_search(log, sm, r);) + { + std::cout << sm.str() << '\\n'; + log = sm.suffix(); } + + // C-style string demo + std::cmatch cm; + if (std::regex_search("this is a test", cm, std::regex("test"))) + std::cout << "\\nFound " << cm[0] << " at position " + << cm.prefix().length() << '\\n'; } .SH Output: - Roses are #ff0000: 1 - violets are #0000ff: 1 - all of my base are belong to you: 0 + Roses are #ff0000: true + violets are #0000ff: true + all of my base are belong to you: false + matches for 'Roses are #ff0000' + Prefix: 'Roses are ' 0: #ff0000 1: ff 2: 00 3: 00 + Suffix: '' + matches for 'violets are #0000ff' + Prefix: 'violets are ' 0: #0000ff 1: 00 2: 00 3: ff - matches for 'all of my base are belong to you' + Suffix: '' + + Speed: 366 + Speed: 378 + Speed: 400 + + Found test at position 10 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + basic_string rvalues were accepted, which rejected via a deleted + LWG 2329 C++11 was likely to result in dangling overload + iterators .SH See also basic_regex regular expression object - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP match_results identifies one regular expression match, including all sub-expression \fI(C++11)\fP matches - \fI(class template)\fP + \fI(class template)\fP regex_match attempts to match a regular expression to an entire character sequence - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::regex_token_iterator.3 b/man/std::regex_token_iterator.3 index e4343b82f..7feda2845 100644 --- a/man/std::regex_token_iterator.3 +++ b/man/std::regex_token_iterator.3 @@ -1,4 +1,7 @@ -.TH std::regex_token_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_token_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_token_iterator \- std::regex_token_iterator + .SH Synopsis Defined in header template< @@ -9,14 +12,14 @@ > class regex_token_iterator - std::regex_token_iterator is a read-only ForwardIterator that accesses the + std::regex_token_iterator is a read-only LegacyForwardIterator that accesses the individual sub-matches of every match of a regular expression within the underlying character sequence. It can also be used to access the parts of the sequence that were not matched by the given regular expression (e.g. as a tokenizer). On construction, it constructs an std::regex_iterator and on every increment it steps through the requested sub-matches from the current match_results, incrementing - the underlying regex_iterator when incrementing away from the last submatch. + the underlying std::regex_iterator when incrementing away from the last submatch. The default-constructed std::regex_token_iterator is the end-of-sequence iterator. When a valid std::regex_token_iterator is incremented after reaching the last @@ -25,13 +28,13 @@ Just before becoming the end-of-sequence iterator, a std::regex_token_iterator may become a suffix iterator, if the index -1 (non-matched fragment) appears in the list - of the requested submatch indexes. Such iterator, if dereferenced, returns a + of the requested submatch indices. Such iterator, if dereferenced, returns a match_results corresponding to the sequence of characters between the last match and the end of sequence. A typical implementation of std::regex_token_iterator holds the underlying std::regex_iterator, a container (e.g. std::vector) of the requested submatch - indexes, the internal counter equal to the index of the submatch, a pointer to + indices, the internal counter equal to the index of the submatch, a pointer to std::sub_match, pointing at the current submatch of the current match, and a std::match_results object containing the last non-matched character sequence (used in tokenizer mode). @@ -39,43 +42,45 @@ .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Specializations Several specializations for common character sequence types are defined: Defined in header - Type Definition - cregex_token_iterator regex_token_iterator - wcregex_token_iterator regex_token_iterator - sregex_token_iterator regex_token_iterator - wsregex_token_iterator regex_token_iterator + Type Definition + std::cregex_token_iterator std::regex_token_iterator + std::wcregex_token_iterator std::regex_token_iterator + std::sregex_token_iterator std::regex_token_iterator + std::wsregex_token_iterator std::regex_token_iterator .SH Member types - Member type Definition - value_type std::sub_match - difference_type std::ptrdiff_t - pointer const value_type* - reference const value_type& - iterator_category std::forward_iterator_tag - regex_type basic_regex + Member type Definition + value_type std::sub_match + difference_type std::ptrdiff_t + pointer const value_type* + reference const value_type& + iterator_category std::forward_iterator_tag + iterator_concept (C++20) std::input_iterator_tag + regex_type std::basic_regex .SH Member functions constructor constructs a new regex_token_iterator - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs a regex_token_iterator, including the cached value - (implicitly declared) \fI(public member function)\fP + (implicitly declared) \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP operator== compares two regex_token_iterators - operator!= \fI(public member function)\fP + operator!= \fI(public member function)\fP + (removed in C++20) operator* accesses current submatch - operator-> \fI(public member function)\fP + operator-> \fI(public member function)\fP operator++ advances the iterator to the next submatch - operator++(int) \fI(public member function)\fP + operator++(int) \fI(public member function)\fP .SH Notes @@ -86,31 +91,33 @@ .SH Example - + // Run this code + #include #include #include - #include #include #include - + int main() { - std::string text = "Quick brown fox."; - // tokenization (non-matched fragments) - // Note that regex is matched only two times: when the third value is obtained - // the iterator is a suffix iterator. - std::regex ws_re("\\\\s+"); // whitespace - std::copy( std::sregex_token_iterator(text.begin(), text.end(), ws_re, -1), + // Tokenization (non-matched fragments) + // Note that regex is matched only two times; when the third value is obtained + // the iterator is a suffix iterator. + const std::string text = "Quick brown fox."; + const std::regex ws_re("\\\\s+"); // whitespace + std::copy(std::sregex_token_iterator(text.begin(), text.end(), ws_re, -1), std::sregex_token_iterator(), std::ostream_iterator(std::cout, "\\n")); - - // iterating the first submatches - std::string html = "

google " - "< a HREF =\\"http://cppreference.com\\">cppreference\\n

"; - std::regex url_re("<\\\\s*A\\\\s+[^>]*href\\\\s*=\\\\s*\\"([^\\"]*)\\"", std::regex::icase); - std::copy( std::sregex_token_iterator(html.begin(), html.end(), url_re, 1), + + std::cout << '\\n'; + + // Iterating the first submatches + const std::string html = R"(

google )" + R"(< a HREF ="http://cppreference.com">cppreference\\n

)"; + const std::regex url_re(R"!!(<\\s*A\\s+[^>]*href\\s*=\\s*"([^"]*)")!!", std::regex::icase); + std::copy(std::sregex_token_iterator(html.begin(), html.end(), url_re, 1), std::sregex_token_iterator(), std::ostream_iterator(std::cout, "\\n")); } @@ -120,5 +127,19 @@ Quick brown fox. + http://google.com http://cppreference.com + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3698 regex_token_iterator was a + (P2770R0) C++20 forward_iterator made input_iterator^[1] + while being a stashing iterator + + 1. ↑ iterator_category was unchanged by the resolution, because changing it to + std::input_iterator_tag might break too much existing code. diff --git a/man/std::regex_token_iterator::operator*,operator->.3 b/man/std::regex_token_iterator::operator*,operator->.3 index 9dba7d3d9..15ab9c177 100644 --- a/man/std::regex_token_iterator::operator*,operator->.3 +++ b/man/std::regex_token_iterator::operator*,operator->.3 @@ -1,16 +1,16 @@ -.TH std::regex_token_iterator::operator*,operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_token_iterator::operator*,operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_token_iterator::operator*,operator-> \- std::regex_token_iterator::operator*,operator-> + .SH Synopsis - const value_type& operator*() const; \fI(since C++11)\fP - const value_type* operator->() const; \fI(since C++11)\fP + const value_type& operator*() const; \fB(1)\fP \fI(since C++11)\fP + const value_type* operator->() const; \fB(2)\fP \fI(since C++11)\fP Returns a pointer or reference to the current match. - The behavior is undefined if the iterator is end-of-sequence iterator. - -.SH Parameters - - other - regex iterator to assign - .SH Return value - A pointer or reference to the current match. + 1) Returns a reference to the current match. + 2) Returns a pointer to the current match. + + The behavior is undefined if the iterator is end-of-sequence iterator. diff --git a/man/std::regex_token_iterator::operator++,operator++(int).3 b/man/std::regex_token_iterator::operator++,operator++(int).3 index 39dbb36af..f09f5520a 100644 --- a/man/std::regex_token_iterator::operator++,operator++(int).3 +++ b/man/std::regex_token_iterator::operator++,operator++(int).3 @@ -1,12 +1,16 @@ -.TH std::regex_token_iterator::operator++,operator++(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_token_iterator::operator++,operator++(int) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_token_iterator::operator++,operator++(int) \- std::regex_token_iterator::operator++,operator++(int) + .SH Synopsis - regex_token_iterator& operator++(); \fI(since C++11)\fP - regex_token_iterator operator++(int); \fI(since C++11)\fP + regex_token_iterator& operator++(); \fI(since C++11)\fP + regex_token_iterator operator++( int ); \fI(since C++11)\fP Advances the iterator on the next sub match. This section is incomplete - Reason: explain better + Reason: Explain better. For example, subs is an exposition-only vector of matched + sub-expressions. If *this is a suffix iterator, sets *this to an end-of-sequence iterator. @@ -34,5 +38,4 @@ 1) *this 2) The previous value of the iterator. .SH Category: - * Todo with reason diff --git a/man/std::regex_token_iterator::operator=.3 b/man/std::regex_token_iterator::operator=.3 index 9db77e41e..4047f6964 100644 --- a/man/std::regex_token_iterator::operator=.3 +++ b/man/std::regex_token_iterator::operator=.3 @@ -1,4 +1,7 @@ -.TH std::regex_token_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_token_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_token_iterator::operator= \- std::regex_token_iterator::operator= + .SH Synopsis regex_token_iterator& operator=( const regex_token_iterator& other ); \fI(since C++11)\fP @@ -6,8 +9,8 @@ .SH Parameters - other - regex iterator to assign + other - regex token iterator to assign .SH Return value - *this. + *this diff --git a/man/std::regex_token_iterator::operator==,operator!=.3 b/man/std::regex_token_iterator::operator==,operator!=.3 new file mode 100644 index 000000000..6f22d37a1 --- /dev/null +++ b/man/std::regex_token_iterator::operator==,operator!=.3 @@ -0,0 +1,40 @@ +.TH std::regex_token_iterator::operator==,operator!= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_token_iterator::operator==,operator!= \- std::regex_token_iterator::operator==,operator!= + +.SH Synopsis + bool operator==( const regex_token_iterator& other ) const; \fB(1)\fP \fI(since C++11)\fP + bool operator!=( const regex_token_iterator& other ) const; \fB(2)\fP \fI(since C++11)\fP + \fI(until C++20)\fP + + Checks whether *this and other are equivalent. + + Two regex token iterators are equal if: + + a) They are both end-of-sequence iterators. + b) They are both suffix iterators and the suffixes are equal. + c) Neither of them is end-of-sequence or suffix iterator and: + + * position == other.position + * N == other.N + * subs == other.subs + + 1) Checks whether *this is equal to other. + 2) Checks whether *this is not equal to other. + + The != operator is synthesized from operator==. \fI(since C++20)\fP + + This section is incomplete + Reason: Explain better. For example, subs is an exposition-only vector of matched + sub-expressions. + +.SH Parameters + + other - another regex token iterator to compare to + +.SH Return value + + 1) true if *this is equal to other, false otherwise. + 2) true if *this is not equal to other, false otherwise. +.SH Category: + * Todo with reason diff --git a/man/std::regex_token_iterator::regex_token_iterator.3 b/man/std::regex_token_iterator::regex_token_iterator.3 index 5503362a6..abdb85ec0 100644 --- a/man/std::regex_token_iterator::regex_token_iterator.3 +++ b/man/std::regex_token_iterator::regex_token_iterator.3 @@ -1,40 +1,72 @@ -.TH std::regex_token_iterator::regex_token_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_token_iterator::regex_token_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_token_iterator::regex_token_iterator \- std::regex_token_iterator::regex_token_iterator + .SH Synopsis - regex_token_iterator(); \fB(1)\fP \fI(since C++11)\fP - regex_token_iterator( BidirectionalIterator a, - BidirectionalIterator b, + regex_token_iterator(); \fB(1)\fP \fI(since C++11)\fP + regex_token_iterator( BidirIt a, BidirIt b, - const regex_type& re, \fB(2)\fP \fI(since C++11)\fP - int submatch = 0, + const regex_type& re, + int submatch = 0, \fB(2)\fP \fI(since C++11)\fP std::regex_constants::match_flag_type m = std::regex_constants::match_default ); - regex_token_iterator( BidirectionalIterator a, - BidirectionalIterator b, + regex_token_iterator( BidirIt a, BidirIt b, - const regex_type& re, \fB(3)\fP \fI(since C++11)\fP - const std::vector& submatches, + const regex_type& re, + const std::vector& submatches, \fB(3)\fP \fI(since C++11)\fP std::regex_constants::match_flag_type m = std::regex_constants::match_default ); - regex_token_iterator( BidirectionalIterator a, - BidirectionalIterator b, + regex_token_iterator( BidirIt a, BidirIt b, - const regex_type& re, \fB(4)\fP \fI(since C++11)\fP - std::initializer_list submatches, + const regex_type& re, + std::initializer_list submatches, \fB(4)\fP \fI(since C++11)\fP std::regex_constants::match_flag_type m = std::regex_constants::match_default ); - template + template< std::size_t N > - regex_token_iterator( BidirectionalIterator a, - BidirectionalIterator b, - const regex_type& re, \fB(5)\fP \fI(since C++11)\fP + regex_token_iterator( BidirIt a, BidirIt b, + const regex_type& re, \fB(5)\fP \fI(since C++11)\fP const int (&submatches)[N], std::regex_constants::match_flag_type m = std::regex_constants::match_default ); - regex_token_iterator( const regex_token_iterator& other ); \fB(6)\fP \fI(since C++11)\fP + regex_token_iterator( const regex_token_iterator& other ); \fB(6)\fP \fI(since C++11)\fP + regex_token_iterator( BidirIt a, BidirIt b, + + const regex_type&& re, + int submatch = 0, \fB(7)\fP \fI(since C++11)\fP + std::regex_constants::match_flag_type m = + + std::regex_constants::match_default ) = + delete; + regex_token_iterator( BidirIt a, BidirIt b, + + const regex_type&& re, + const std::vector& submatches, \fB(8)\fP \fI(since C++11)\fP + std::regex_constants::match_flag_type m = + + std::regex_constants::match_default ) = + delete; + regex_token_iterator( BidirIt a, BidirIt b, + + const regex_type&& re, + std::initializer_list submatches, \fB(9)\fP \fI(since C++11)\fP + std::regex_constants::match_flag_type m = + + std::regex_constants::match_default ) = + delete; + template< std::size_t N > + + regex_token_iterator( BidirIt a, BidirIt b, + const regex_type&& re, + const int (&submatches)[N], \fB(10)\fP \fI(since C++11)\fP + std::regex_constants::match_flag_type m = + + std::regex_constants::match_default ) = + delete; Constructs a new regex_token_iterator: @@ -44,13 +76,12 @@ member std::regex_iterator by passing a, b, re, and m to its four-argument constructor (that constructor performs the initial call to std::regex_search) and sets the internal counter of submatches to zero. - * If, after construction, the member regex_iterator is not an end-of-sequence iterator, sets the member pointer to the address of the current std::sub_match. * Otherwise (if the member regex_iterator is an end-of-sequence iterator), but the value -1 is one of the values in submatches/submatch, turns *this into a suffix - iterator pointing at the range [a,b) (the entire string is the non-matched - suffix) + iterator pointing at the range [a, b) (the entire string is the non-matched + suffix). * Otherwise (if -1 is not in the list of submatches), turns *this into the end-of-sequence iterator. @@ -58,15 +89,18 @@ 6) Copy constructor: performs member-wise copy (including making a copy of the member regex_iterator and the member pointer to current sub_match). + 7-10) The overloads (2-5) are prohibited from being called with a temporary regex + since otherwise the returned iterator would be immediately invalidated. .SH Parameters - a - BidirectionalIterator to the beginning of the target character sequence - b - BidirectionalIterator to the end of the target character sequence + a - LegacyBidirectionalIterator to the beginning of the target character + sequence + b - LegacyBidirectionalIterator to the end of the target character sequence re - regular expression used to search the target character sequence the index of the submatch that should be returned. "0" represents the submatch - entire match, and "-1" represents the parts that are not matched (e.g, - the stuff between matches). + the stuff between matches) the sequence of submatch indices that should be iterated over within submatches - each match, may include the special value -1 for the non-matched fragments @@ -77,6 +111,16 @@ This section is incomplete Reason: no example -.SH Category: + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + DR Applied to Behavior as published Correct behavior + a regex_token_iterator constructed such construction is + LWG 2332 C++11 from a disallowed via deleted + temporary basic_regex became overloads + invalid immediately + +.SH Category: * Todo no example diff --git a/man/std::regex_traits.3 b/man/std::regex_traits.3 index 356e8b842..dd433fade 100644 --- a/man/std::regex_traits.3 +++ b/man/std::regex_traits.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits \- std::regex_traits + .SH Synopsis Defined in header template< class CharT > \fI(since C++11)\fP @@ -19,9 +22,9 @@ std::regex_traits These specializations make it possible to use std::basic_regex (aka - std::regex) and std::basic_regex (aka std::wregex), but in order to use, - for example, std::basic_regex, user-provided specializtion - std::regex_traits needs to be defined. + std::regex) and std::basic_regex (aka std::wregex). To use std::basic_regex + with other character types (for example, char32_t), a user-provided trait class must + be used. .SH Member types @@ -37,29 +40,29 @@ .SH Member functions constructor constructs the regex_traits object - \fI(public member function)\fP + \fI(public member function)\fP length calculates the length of a null-terminated character string - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP translate determines the equivalence key for a character - \fI(public member function)\fP + \fI(public member function)\fP translate_nocase determines the case-insensitive equivalence key for a character - \fI(public member function)\fP + \fI(public member function)\fP determines the sort key for the given string, used to provide transform collation order - \fI(public member function)\fP + \fI(public member function)\fP determines the primary sort key for the character sequence, used transform_primary to determine equivalence class - \fI(public member function)\fP + \fI(public member function)\fP lookup_collatename gets a collation element by name - \fI(public member function)\fP + \fI(public member function)\fP lookup_classname gets a character class by name - \fI(public member function)\fP + \fI(public member function)\fP isctype indicates membership in a localized character class - \fI(public member function)\fP + \fI(public member function)\fP translates the character representing a numeric digit into an value integral value - \fI(public member function)\fP + \fI(public member function)\fP imbue sets the locale - \fI(public member function)\fP + \fI(public member function)\fP getloc gets the locale - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::regex_traits::getloc.3 b/man/std::regex_traits::getloc.3 index aeaf6ce30..861572759 100644 --- a/man/std::regex_traits::getloc.3 +++ b/man/std::regex_traits::getloc.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::getloc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::getloc \- std::regex_traits::getloc + .SH Synopsis locale_type getloc() const; \fI(since C++11)\fP @@ -24,8 +27,7 @@ .SH See also imbue sets the locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::regex_traits::imbue.3 b/man/std::regex_traits::imbue.3 index 1e746c820..5003b6a31 100644 --- a/man/std::regex_traits::imbue.3 +++ b/man/std::regex_traits::imbue.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::imbue 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::imbue \- std::regex_traits::imbue + .SH Synopsis locale_type imbue( locale_type loc ); \fI(since C++11)\fP @@ -27,8 +30,7 @@ .SH See also getloc gets the locale - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::regex_traits::isctype.3 b/man/std::regex_traits::isctype.3 index fea409843..72037fe45 100644 --- a/man/std::regex_traits::isctype.3 +++ b/man/std::regex_traits::isctype.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::isctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::isctype 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::isctype \- std::regex_traits::isctype + .SH Synopsis bool isctype( CharT c, char_class_type f ) const; @@ -9,15 +12,16 @@ The version of this function provided in the standard library specializations of std::regex_traits does the following: - 1) First converts f to some temporary value m of type std::ctype_base::mask in - implementation-defined manner + 1) First converts f to a value m of type std::ctype_base::mask. + For each std::ctype category listed in the table in the page lookup_classname(), if + the bits in f corresponding to the category are set, the corresponding bits in m + will also be set. 2) Then attempts to classify the character in the imbued locale by calling - std::use_facet>(getloc()).is(m, c). If that returned true, true is - returned by isctype(). - 3) Otherwise, checks whether c equals '_' and the bitmask f includes the result of - calling lookup_classname() for the character class [:w:], in which case true is - returned. - 4) Otherwise, false is returned. + std::use_facet>(getloc()).is(m, c). + * If that returns true, isctype() will also return true. + * Otherwise, if c equals '_', and f includes the result of calling + lookup_classname() for the character class [:w:], true is returned, otherwise + false is returned. .SH Parameters @@ -28,20 +32,15 @@ true if c is classified by f, false otherwise. -.SH Notes - - The description above summarizes C++14; the C++11 phrasing required this function to - return true for '_' in all cases (LWG issue 2018) - .SH Example - + // Run this code #include - #include #include - + #include + int main() { std::regex_traits t; @@ -61,41 +60,45 @@ true false false false - demonstraits a custom regex_traits implementation of lookup_classname/isctype + Demonstrates a custom regex traits implementation of lookup_classname() / isctype(): + - // Run this code + #include #include #include #include - #include - - // This custom regex traits uses wctype/iswctype to implement lookup_classname/isctype + + // This custom regex traits uses wctype/iswctype to implement lookup_classname/isctype. struct wctype_traits : std::regex_traits { using char_class_type = std::wctype_t; + template - char_class_type lookup_classname(It first, It last, bool=false) const { + char_class_type lookup_classname(It first, It last, bool = false) const + { return std::wctype(std::string(first, last).c_str()); } - bool isctype(wchar_t c, char_class_type f) const { + + bool isctype(wchar_t c, char_class_type f) const + { return std::iswctype(c, f); } }; - + int main() { std::locale::global(std::locale("ja_JP.utf8")); std::wcout.sync_with_stdio(false); std::wcout.imbue(std::locale()); - + std::wsmatch m; std::wstring in = L"風の谷のナウシカ"; // matches all characters (they are classified as alnum) std::regex_search(in, m, std::wregex(L"([[:alnum:]]+)")); std::wcout << "alnums: " << m[1] << '\\n'; // prints "風の谷のナウシカ" - // matches only the kanji + // matches only the katakana std::regex_search(in, m, std::basic_regex(L"([[:jkata:]]+)")); std::wcout << "katakana: " << m[1] << '\\n'; // prints "ナウシカ" @@ -106,12 +109,21 @@ alnums: 風の谷のナウシカ katakana: ナウシカ + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2018 C++11 the value of m was matches lookup_classname()'s minimal + unspecified support + .SH See also lookup_classname gets a character class by name - \fI(public member function)\fP + \fI(public member function)\fP do_is classifies a character or a character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP classifies a wide character according to the specified LC_CTYPE iswctype category - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::regex_traits::length.3 b/man/std::regex_traits::length.3 index dae5ec811..e3860abb3 100644 --- a/man/std::regex_traits::length.3 +++ b/man/std::regex_traits::length.3 @@ -1,12 +1,15 @@ -.TH std::regex_traits::length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::length \- std::regex_traits::length + .SH Synopsis - static std::size_t length(const char_type* p); + static std::size_t length( const char_type* p ); Calculates the length of a null-terminated character sequence, that is, the smallest - i such that p[i]==0. + i such that p[i] == 0. Standard library specializations of std::regex_traits execute - std::char_traits::length(p); + std::char_traits::length(p);. .SH Parameters @@ -18,15 +21,15 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { - std::cout << std::regex_traits::length(u8"Кошка") << '\\n' + std::cout << std::regex_traits::length("Кошка") << '\\n' << std::regex_traits::length(L"Кошка") << '\\n'; } diff --git a/man/std::regex_traits::lookup_classname.3 b/man/std::regex_traits::lookup_classname.3 index 8044978e0..5e193e76a 100644 --- a/man/std::regex_traits::lookup_classname.3 +++ b/man/std::regex_traits::lookup_classname.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::lookup_classname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::lookup_classname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::lookup_classname \- std::regex_traits::lookup_classname + .SH Synopsis template< class ForwardIt > @@ -14,37 +17,40 @@ If the parameter icase is true, the character class ignores character case, e.g. the regex [:lower:] with std::regex_constants::icase generates a call to - regex_traits<>::lookup_classname() with [first, last) indicating the string "lower" - and icase == true. This call returns the same bitmask as the call generated by the - regex [:alpha:] with icase == false. - - The following character classes are always recognized, in both narrow and wide - character forms, and the classifications returned (with icase == false) correspond - to the matching classifications obtained by the std::ctype facet of the imbued - locale, as follows: - - character class std::ctype classification - "alnum" std::ctype_base::alnum - "alpha" std::ctype_base::alpha - "blank" std::ctype_base::blank - "cntrl" std::ctype_base::cntrl - "digit" std::ctype_base::digit - "graph" std::ctype_base::graph - "lower" std::ctype_base::lower - "print" std::ctype_base::print - "punct" std::ctype_base::punct - "space" std::ctype_base::space - "upper" std::ctype_base::upper - "xdigit" std::ctype_base::xdigit - "d" std::ctype_base::digit - "s" std::ctype_base::space - "w" std::ctype_base::alnum with '_' optionally added + std::regex_traits<>::lookup_classname() with [first, last) indicating the string + "lower" and icase == true. This call returns the same bitmask as the call generated + by the regex [:alpha:] with icase == false. + + The following narrow and wide character class names are always recognized by + std::regex_traits and std::regex_traits respectively, and the + classifications returned (with icase == false) correspond to the matching + classifications obtained by the std::ctype facet of the imbued locale, as follows: + + Character class name std::ctype classification + Narrow Wide + "alnum" L"alnum" std::ctype_base::alnum + "alpha" L"alpha" std::ctype_base::alpha + "blank" L"blank" std::ctype_base::blank + "cntrl" L"cntrl" std::ctype_base::cntrl + "digit" L"digit" std::ctype_base::digit + "graph" L"graph" std::ctype_base::graph + "lower" L"lower" std::ctype_base::lower + "print" L"print" std::ctype_base::print + "punct" L"punct" std::ctype_base::punct + "space" L"space" std::ctype_base::space + "upper" L"upper" std::ctype_base::upper + "xdigit" L"xdigit" std::ctype_base::xdigit + "d" L"d" std::ctype_base::digit + "s" L"s" std::ctype_base::space + "w" L"w" std::ctype_base::alnum + with '_' optionally added The classification returned for the string "w" may be exactly the same as "alnum", in which case isctype() adds '_' explicitly. Additional classifications such as "jdigit" or "jkanji" may be provided by - system-supplied locales (in which case they are also accessible through std::wctype) + system-supplied locales (in which case they are also accessible through + std::wctype). .SH Parameters @@ -54,50 +60,54 @@ classification .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value The bitmask representing the character classification determined by the given - character class, or zero if the class is unknown. + character class, or char_class_type() if the class is unknown. .SH Example - demonstraits a custom regex_traits implementation of lookup_classname/isctype + Demonstrates a custom regex traits implementation of lookup_classname() / isctype(): + - // Run this code + #include #include #include #include - #include - - // This custom regex traits uses wctype/iswctype to implement lookup_classname/isctype + + // This custom regex traits uses wctype/iswctype to implement lookup_classname/isctype. struct wctype_traits : std::regex_traits { using char_class_type = std::wctype_t; + template - char_class_type lookup_classname(It first, It last, bool=false) const { + char_class_type lookup_classname(It first, It last, bool = false) const + { return std::wctype(std::string(first, last).c_str()); } - bool isctype(wchar_t c, char_class_type f) const { + + bool isctype(wchar_t c, char_class_type f) const + { return std::iswctype(c, f); } }; - + int main() { std::locale::global(std::locale("ja_JP.utf8")); std::wcout.sync_with_stdio(false); std::wcout.imbue(std::locale()); - + std::wsmatch m; std::wstring in = L"風の谷のナウシカ"; // matches all characters (they are classified as alnum) std::regex_search(in, m, std::wregex(L"([[:alnum:]]+)")); std::wcout << "alnums: " << m[1] << '\\n'; // prints "風の谷のナウシカ" - // matches only the kanji + // matches only the katakana std::regex_search(in, m, std::basic_regex(L"([[:jkata:]]+)")); std::wcout << "katakana: " << m[1] << '\\n'; // prints "ナウシカ" @@ -113,4 +123,4 @@ isctype indicates membership in a character class \fI(public member function)\fP wctype looks up a character classification category in the current C locale - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::regex_traits::lookup_collatename.3 b/man/std::regex_traits::lookup_collatename.3 index 38de316b4..c048e3046 100644 --- a/man/std::regex_traits::lookup_collatename.3 +++ b/man/std::regex_traits::lookup_collatename.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::lookup_collatename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::lookup_collatename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::lookup_collatename \- std::regex_traits::lookup_collatename + .SH Synopsis template< class ForwardIt > string_type lookup_collatename( ForwardIt first, ForwardIt last ) const; @@ -19,7 +22,7 @@ represents a collating element name .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value @@ -27,17 +30,18 @@ .SH Example - + // Run this code #include - #include #include - - struct noisy_traits : std::regex_traits { - - template< class Iter > - string_type lookup_collatename( Iter first, Iter last ) const { + #include + + struct noisy_traits : std::regex_traits + { + template + string_type lookup_collatename(Iter first, Iter last) const + { string_type result = regex_traits::lookup_collatename(first, last); std::cout << "regex_traits<>::lookup_collatename(\\"" << string_type(first, last) @@ -45,7 +49,7 @@ return result; } }; - + int main() { std::string str = "z|}a"; // C locale collation order: x,y,z,{,|,},~ @@ -53,7 +57,7 @@ std::cout << std::boolalpha << std::regex_match(str, re) << '\\n'; } -.SH Output: +.SH Possible output: regex_traits<>::lookup_collatename("tilde") returns "~" true diff --git a/man/std::regex_traits::regex_traits.3 b/man/std::regex_traits::regex_traits.3 index 0243736b1..434993d39 100644 --- a/man/std::regex_traits::regex_traits.3 +++ b/man/std::regex_traits::regex_traits.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::regex_traits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::regex_traits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::regex_traits \- std::regex_traits::regex_traits + .SH Synopsis regex_traits(); @@ -15,12 +18,12 @@ .SH Example - + // Run this code #include #include - + int main() { std::locale::global(std::locale("en_US.utf8")); diff --git a/man/std::regex_traits::transform.3 b/man/std::regex_traits::transform.3 index ed1c6d9da..d3575177c 100644 --- a/man/std::regex_traits::transform.3 +++ b/man/std::regex_traits::transform.3 @@ -1,31 +1,34 @@ -.TH std::regex_traits::transform 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::transform 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::transform \- std::regex_traits::transform + .SH Synopsis template< class ForwardIt > - string_type transform( ForwardIt first, ForwardIt last) const + string_type transform( ForwardIt first, ForwardIt last) const; Obtains the sort key for the character sequence [first, last), such that if a sort key compares less than another sort key with operator<, then the character sequence that produced the first sort key comes before the character sequence that produced the second sort key, in the currently imbued locale's collation order. - For example when the regex flag std::regex_constants::collate is set, then the + For example, when the regex flag std::regex_constants::collate is set, then the sequence [a-b] would match some character c1 if traits.transform("a") <= traits.transform(c1) <= traits.transform("b"). Note that this function takes a - character sequence as the argument to accomodate to the ranges defined like + character sequence as the argument to accommodate to the ranges defined like [[.ae.]-d]. Standard library specializations of std::regex_traits return - std::use_facet>(getloc()).transform(&*str.begin(), &*str.begin() - + str.length()) for some temporary string str constructed as string_type str(first, + std::use_facet>(getloc()).transform(str.data(), str.data() + + str.length()) for some temporary string str constructed as string_type str(first, last). .SH Parameters - first, last - a pair of ForwardIterators which determines the sequence of characters - to compare + first, last - a pair of LegacyForwardIterators which determines the sequence of + characters to compare .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value @@ -38,5 +41,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::regex_traits::transform_primary.3 b/man/std::regex_traits::transform_primary.3 index 355774dfb..d03f33cd6 100644 --- a/man/std::regex_traits::transform_primary.3 +++ b/man/std::regex_traits::transform_primary.3 @@ -1,7 +1,10 @@ -.TH std::regex_traits::transform_primary 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::transform_primary 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::transform_primary \- std::regex_traits::transform_primary + .SH Synopsis template< class ForwardIt > - string_type transform_primary( ForwardIt first, ForwardIt last ) const + string_type transform_primary( ForwardIt first, ForwardIt last ) const; For the character sequence [first, last), obtains the primary sort key in the imbued locale's collating order, that is, the sort key that is based on the positions of @@ -25,7 +28,7 @@ std::regex_traits. Standard library specializations of std::regex_traits return an empty string unless the std::collate facet of the currently-imbued locale was not replaced by the user, and still matches the system-supplied std::collate facet), in - which case std::collate_byname::transform(first, last) is executed and the + which case std::collate_byname::transform(first, last) is executed and the sort key it produces is converted to the expected primary sort key using a locale-specific conversion. @@ -35,7 +38,7 @@ compare .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value @@ -44,14 +47,14 @@ .SH Example - Demonstrates the regex feature that works through transform_primary() + Demonstrates the regex feature that works through transform_primary(). + - // Run this code #include #include - + int main() { std::locale::global(std::locale("en_US.UTF-8")); @@ -60,7 +63,7 @@ std::cout << std::boolalpha << std::regex_match(str, re) << '\\n'; } -.SH Output: +.SH Possible output: true @@ -69,5 +72,4 @@ transform_primary .SH Category: - * Todo with reason diff --git a/man/std::regex_traits::translate.3 b/man/std::regex_traits::translate.3 index 49a4fe5a6..c9f94459d 100644 --- a/man/std::regex_traits::translate.3 +++ b/man/std::regex_traits::translate.3 @@ -1,6 +1,9 @@ -.TH std::regex_traits::translate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::translate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::translate \- std::regex_traits::translate + .SH Synopsis - CharT translate(CharT c) const; + CharT translate( CharT c ) const; Obtains the comparison key for the character c, such that all characters that are equivalent to this character in the imbued locale produce the same key. @@ -25,5 +28,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::regex_traits::translate_nocase.3 b/man/std::regex_traits::translate_nocase.3 index 3bfa35fea..df6fc66f7 100644 --- a/man/std::regex_traits::translate_nocase.3 +++ b/man/std::regex_traits::translate_nocase.3 @@ -1,6 +1,9 @@ -.TH std::regex_traits::translate_nocase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::translate_nocase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::translate_nocase \- std::regex_traits::translate_nocase + .SH Synopsis - CharT translate_nocase(CharT c) const; + CharT translate_nocase( CharT c ) const; Obtains the comparison key for the character c, such that all characters that are equivalent to this character in the imbued locale, ignoring the case differences, if @@ -28,5 +31,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::regex_traits::value.3 b/man/std::regex_traits::value.3 index c2a84f3cb..039a2dd39 100644 --- a/man/std::regex_traits::value.3 +++ b/man/std::regex_traits::value.3 @@ -1,4 +1,7 @@ -.TH std::regex_traits::value 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::regex_traits::value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regex_traits::value \- std::regex_traits::value + .SH Synopsis int value( CharT ch, int radix ) const; \fI(since C++11)\fP @@ -19,19 +22,20 @@ .SH Example - + // Run this code #include #include - #include #include - + #include + // This custom regex traits allows japanese numerals struct jnum_traits : std::regex_traits { static std::map data; - int value(wchar_t ch, int radix ) const { + int value(wchar_t ch, int radix) const + { wchar_t up = std::toupper(ch, getloc()); return data.count(up) ? data[up] : regex_traits::value(ch, radix); } @@ -42,18 +46,19 @@ {L'九',9}, {L'Ａ',10}, {L'Ｂ',11}, {L'Ｃ',12}, {L'Ｄ',13}, {L'Ｅ',14}, {L'Ｆ',15}}; + int main() { std::locale::global(std::locale("ja_JP.utf8")); std::wcout.sync_with_stdio(false); std::wcout.imbue(std::locale()); - + std::wstring in = L"風"; - - if(std::regex_match(in, std::wregex(L"\\\\u98a8"))) + + if (std::regex_match(in, std::wregex(L"\\\\u98a8"))) std::wcout << "\\\\u98a8 matched " << in << '\\n'; - - if(std::regex_match(in, std::basic_regex(L"\\\\u九八ａ八"))) + + if (std::regex_match(in, std::basic_regex(L"\\\\u九八ａ八"))) std::wcout << L"\\\\u九八ａ八 with custom traits matched " << in << '\\n'; } diff --git a/man/std::regular.3 b/man/std::regular.3 new file mode 100644 index 000000000..e7c5587a8 --- /dev/null +++ b/man/std::regular.3 @@ -0,0 +1,50 @@ +.TH std::regular 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::regular \- std::regular + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + concept regular = std::semiregular && std::equality_comparable; + + The regular concept specifies that a type is regular, that is, it is copyable, + default constructible, and equality comparable. It is satisfied by types that behave + similarly to built-in types like int, and that are comparable with ==. + +.SH Example + + +// Run this code + + #include + #include + + template + struct Single + { + T value; + friend bool operator==(const Single&, const Single&) = default; + }; + + int main() + { + Single myInt1{4}; + Single myInt2; + myInt2 = myInt1; + + if (myInt1 == myInt2) + std::cout << "Equal\\n"; + + std::cout << myInt1.value << ' ' << myInt2.value << '\\n'; + } + +.SH Output: + + Equal + 4 4 + +.SH See also + + semiregular specifies that an object of a type can be copied, moved, swapped, and + (C++20) default constructed + (concept) diff --git a/man/std::rel_ops::operator!=,>,<=,>=.3 b/man/std::rel_ops::operator!=,>,<=,>=.3 deleted file mode 100644 index 4a5abf638..000000000 --- a/man/std::rel_ops::operator!=,>,<=,>=.3 +++ /dev/null @@ -1,118 +0,0 @@ -.TH std::rel_ops::operator!=,>,<=,>= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T > \fB(1)\fP - bool operator!=( const T& lhs, const T& rhs ); - template< class T > \fB(2)\fP - bool operator>( const T& lhs, const T& rhs ); - template< class T > \fB(3)\fP - bool operator<=( const T& lhs, const T& rhs ); - template< class T > \fB(4)\fP - bool operator>=( const T& lhs, const T& rhs ); - - Given a user-defined operator== and operator< for objects of type T, implements the - usual semantics of other comparison operators. - - 1) Implements operator!= in terms of operator==. - - 2) Implements operator> in terms of operator<. - - 3) Implements operator<= in terms of operator<. - - 4) Implements operator>= in terms of operator<. - -.SH Parameters - - lhs - left-hand argument - rhs - right-hand argument - -.SH Return value - - 1) Returns true if lhs is not equal to rhs. - - 2) Returns true if lhs is greater than rhs. - - 3) Returns true if lhs is less or equal to rhs. - - 4) Returns true if lhs is greater or equal to rhs. - -.SH Possible implementation - -.SH First version - namespace rel_ops { - template< class T > - bool operator!=( const T& lhs, const T& rhs ) - { - return !(lhs == rhs); - } - } -.SH Second version - namespace rel_ops { - template< class T > - bool operator>( const T& lhs, const T& rhs ) - { - return rhs < lhs; - } - } - Third version - namespace rel_ops { - template< class T > - bool operator<=( const T& lhs, const T& rhs ) - { - return !(rhs < lhs); - } - } - Fourth version - namespace rel_ops { - template< class T > - bool operator>=( const T& lhs, const T& rhs ) - { - return !(lhs < rhs); - } - } - -.SH Notes - - Boost.operators provides a more versatile alternative to std::rel_ops - -.SH Example - - -// Run this code - - #include - #include - - struct Foo { - int n; - }; - - bool operator==(const Foo& lhs, const Foo& rhs) - { - return lhs.n == rhs.n; - } - - bool operator<(const Foo& lhs, const Foo& rhs) - { - return lhs.n < rhs.n; - } - - int main() - { - Foo f1 = {1}; - Foo f2 = {2}; - using namespace std::rel_ops; - - std::cout << std::boolalpha; - std::cout << "not equal? : " << (f1 != f2) << '\\n'; - std::cout << "greater? : " << (f1 > f2) << '\\n'; - std::cout << "less equal? : " << (f1 <= f2) << '\\n'; - std::cout << "greater equal? : " << (f1 >= f2) << '\\n'; - } - -.SH Output: - - not equal? : true - greater? : false - less equal? : true - greater equal? : false diff --git a/man/std::rel_ops::operator!=,>,=.3 b/man/std::rel_ops::operator!=,>,=.3 new file mode 100644 index 000000000..b66402bbe --- /dev/null +++ b/man/std::rel_ops::operator!=,>,=.3 @@ -0,0 +1,122 @@ +.TH std::rel_ops::operator!=,>,= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rel_ops::operator!=,>,= \- std::rel_ops::operator!=,>,= + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP (deprecated in C++20) + bool operator!=( const T& lhs, const T& rhs ); + template< class T > \fB(2)\fP (deprecated in C++20) + bool operator>( const T& lhs, const T& rhs ); + template< class T > \fB(3)\fP (deprecated in C++20) + bool operator<=( const T& lhs, const T& rhs ); + template< class T > \fB(4)\fP (deprecated in C++20) + bool operator>=( const T& lhs, const T& rhs ); + + Given a user-defined operator== and operator< for objects of type T, implements the + usual semantics of other comparison operators. + + 1) Implements operator!= in terms of operator==. + 2) Implements operator> in terms of operator<. + 3) Implements operator<= in terms of operator<. + 4) Implements operator>= in terms of operator<. + +.SH Parameters + + lhs - left-hand argument + rhs - right-hand argument + +.SH Return value + + 1) Returns true if lhs is not equal to rhs. + 2) Returns true if lhs is greater than rhs. + 3) Returns true if lhs is less or equal to rhs. + 4) Returns true if lhs is greater or equal to rhs. + +.SH Possible implementation + + \fB(1)\fP operator!= + namespace rel_ops + { + template + bool operator!=(const T& lhs, const T& rhs) + { + return !(lhs == rhs); + } + } + \fB(2)\fP operator> + namespace rel_ops + { + template + bool operator>(const T& lhs, const T& rhs) + { + return rhs < lhs; + } + } + \fB(3)\fP operator<= + namespace rel_ops + { + template + bool operator<=(const T& lhs, const T& rhs) + { + return !(rhs < lhs); + } + } + \fB(4)\fP operator>= + namespace rel_ops + { + template + bool operator>=(const T& lhs, const T& rhs) + { + return !(lhs < rhs); + } + } + +.SH Notes + + Boost.operators provides a more versatile alternative to std::rel_ops. + + As of C++20, std::rel_ops are deprecated in favor of operator<=>. + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + int n; + }; + + bool operator==(const Foo& lhs, const Foo& rhs) + { + return lhs.n == rhs.n; + } + + bool operator<(const Foo& lhs, const Foo& rhs) + { + return lhs.n < rhs.n; + } + + int main() + { + Foo f1 = {1}; + Foo f2 = {2}; + using namespace std::rel_ops; + + std::cout << std::boolalpha + << "{1} != {2} : " << (f1 != f2) << '\\n' + << "{1} > {2} : " << (f1 > f2) << '\\n' + << "{1} <= {2} : " << (f1 <= f2) << '\\n' + << "{1} >= {2} : " << (f1 >= f2) << '\\n'; + } + +.SH Output: + + {1} != {2} : true + {1} > {2} : false + {1} <= {2} : true + {1} >= {2} : false diff --git a/man/std::relation.3 b/man/std::relation.3 new file mode 100644 index 000000000..ad09d8267 --- /dev/null +++ b/man/std::relation.3 @@ -0,0 +1,15 @@ +.TH std::relation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::relation \- std::relation + +.SH Synopsis + Defined in header + template< class R, class T, class U > + + concept relation = \fB(1)\fP \fI(since C++20)\fP + std::predicate && std::predicate && + + std::predicate && std::predicate; + + The concept relation specifies that R defines a binary relation over the + set of expressions whose type and value category are those encoded by either T or U. diff --git a/man/std::remainder,std::remainderf,std::remainderl.3 b/man/std::remainder,std::remainderf,std::remainderl.3 new file mode 100644 index 000000000..222ef15d8 --- /dev/null +++ b/man/std::remainder,std::remainderf,std::remainderl.3 @@ -0,0 +1,173 @@ +.TH std::remainder,std::remainderf,std::remainderl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remainder,std::remainderf,std::remainderl \- std::remainder,std::remainderf,std::remainderl + +.SH Synopsis + Defined in header + float remainder ( float x, float y ); + + double remainder ( double x, double y ); (until C++23) + + long double remainder ( long double x, long double y + ); + constexpr /* floating-point-type */ + + remainder ( /* floating-point-type */ x, (since C++23) + \fB(1)\fP + /* floating-point-type */ y + ); + float remainderf( float x, float y ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double remainderl( long double x, long double y \fB(3)\fP \fI(since C++11)\fP + ); (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double remainder ( Integer x, Integer y ); + + 1-3) Computes the IEEE remainder of the floating point division operation x / y. + The library provides overloads of std::remainder for all cv-unqualified + floating-point types as the type of the parameters. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + + The IEEE floating-point remainder of the division operation x / y calculated by this + function is exactly the value x - quo * y, where the value quo is the integral value + nearest the exact value x / y. When |quo - x / y| = ½, the value quo is chosen to be + even. + + In contrast to std::fmod, the returned value is not guaranteed to have the same sign + as x. + + If the returned value is zero, it will have the same sign as x. + +.SH Parameters + + x, y - floating-point or integer values + +.SH Return value + + If successful, returns the IEEE floating-point remainder of the division x / y as + defined above. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result is returned. + + If y is zero, but the domain error does not occur, zero is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error may occur if y is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * The current rounding mode has no effect. + * FE_INEXACT is never raised, the result is always exact. + * If x is ±∞ and y is not NaN, NaN is returned and FE_INVALID is raised. + * If y is ±0 and x is not NaN, NaN is returned and FE_INVALID is raised. + * If either argument is NaN, NaN is returned. + +.SH Notes + + POSIX requires that a domain error occurs if x is infinite or y is zero. + + std::fmod, but not std::remainder is useful for doing silent wrapping of + floating-point types to unsigned integer types: (0.0 <= (y = std::fmod(std::rint(x), + 65536.0)) ? y : 65536.0 + y) is in the range [-0.0, 65535.0], which corresponds to + unsigned short, but std::remainder(std::rint(x), 65536.0) is in the range + [-32767.0, +32768.0], which is outside of the range of signed short. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::remainder(num1, + num2) has the same effect as std::remainder(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::remainder(num1, num2) has the same effect as (until C++23) + std::remainder(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::remainder(num1, num2) has the same effect as + std::remainder(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::remainder(num1, + num2) has the same effect as std::remainder(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "remainder(+5.1, +3.0) = " << std::remainder(5.1, 3) << '\\n' + << "remainder(-5.1, +3.0) = " << std::remainder(-5.1, 3) << '\\n' + << "remainder(+5.1, -3.0) = " << std::remainder(5.1, -3) << '\\n' + << "remainder(-5.1, -3.0) = " << std::remainder(-5.1, -3) << '\\n'; + + // special values + std::cout << "remainder(-0.0, 1.0) = " << std::remainder(-0.0, 1) << '\\n' + << "remainder(5.1, Inf) = " << std::remainder(5.1, INFINITY) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + std::cout << "remainder(+5.1, 0) = " << std::remainder(5.1, 0) << '\\n'; + if (fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + remainder(+5.1, +3.0) = -0.9 + remainder(-5.1, +3.0) = 0.9 + remainder(+5.1, -3.0) = -0.9 + remainder(-5.1, -3.0) = 0.9 + remainder(-0.0, 1.0) = -0 + remainder(5.1, Inf) = 5.1 + remainder(+5.1, 0) = -nan + FE_INVALID raised + +.SH See also + + div(int) + ldiv computes quotient and remainder of integer division + lldiv \fI(function)\fP + \fI(C++11)\fP + fmod + fmodf remainder of the floating point division operation + fmodl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remquo + remquof + remquol signed remainder as well as the three last bits of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + remainder diff --git a/man/std::remainder.3 b/man/std::remainder.3 deleted file mode 100644 index 738e8cd60..000000000 --- a/man/std::remainder.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH std::remainder 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float remainder( float x, float y ); \fB(1)\fP \fI(since C++11)\fP - double remainder( double x, double y ); \fB(2)\fP \fI(since C++11)\fP - long double remainder( long double x, long double y ); \fB(3)\fP \fI(since C++11)\fP - Promoted remainder( Arithmetic1 x, Arithmetic2 y ); \fB(4)\fP \fI(since C++11)\fP - - Computes the signed remainder of the floating point division operation x/y. - - Specifically, the returned value is x - n*y, where n is x/y rounded to the nearest - integer, or the nearest even integer if x/y is halfway between two integers. - - In contrast to std::fmod(), the returned value is not guaranteed to have the same - sign as x. - - If the returned value is 0, it will have the same sign as x. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double - -.SH Parameters - - x, y - values of floating-point or integral types - -.SH Return value - - Remainder of dividing arguments. - -.SH See also - - fmod remainder of the floating point division operation - \fI(function)\fP - div - ldiv the quotient and remainder of integer division - lldiv \fI(function)\fP - imaxdiv - \fI(C++11)\fP - C documentation for - remainder diff --git a/man/std::remove,std::remove_if.3 b/man/std::remove,std::remove_if.3 index 56656902f..af236ec06 100644 --- a/man/std::remove,std::remove_if.3 +++ b/man/std::remove,std::remove_if.3 @@ -1,125 +1,267 @@ -.TH std::remove,std::remove_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove,std::remove_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove,std::remove_if \- std::remove,std::remove_if + .SH Synopsis Defined in header - template< class ForwardIt, class T > \fB(1)\fP - ForwardIt remove( ForwardIt first, ForwardIt last, const T& value ); - template< class ForwardIt, class UnaryPredicate > \fB(2)\fP - ForwardIt remove_if( ForwardIt first, ForwardIt last, UnaryPredicate p ); + template< class ForwardIt, class T > (constexpr since + ForwardIt remove( ForwardIt first, C++20) + ForwardIt last, const T& value ); (until C++26) + template< class ForwardIt, class T = + typename std::iterator_traits + + + ::value_type > (since C++26) + constexpr ForwardIt remove( ForwardIt + first, ForwardIt last, + + const T& value + ); + template< class ExecutionPolicy, class + ForwardIt, class T > + + ForwardIt remove( ExecutionPolicy&& \fI(since C++17)\fP + policy, (until C++26) + + ForwardIt first, + ForwardIt last, const T& value ); + template< class ExecutionPolicy, class + ForwardIt, \fB(1)\fP + + class T = typename + std::iterator_traits + (since C++26) + ::value_type > + ForwardIt remove( ExecutionPolicy&& \fB(2)\fP + policy, + + ForwardIt first, + ForwardIt last, const T& value ); + template< class ForwardIt, class UnaryPred + > \fB(3)\fP (constexpr since + ForwardIt remove_if( ForwardIt first, C++20) + ForwardIt last, UnaryPred p ); + template< class ExecutionPolicy, class + ForwardIt, class UnaryPred > + + ForwardIt remove_if( ExecutionPolicy&& \fB(4)\fP \fI(since C++17)\fP + policy, + + ForwardIt first, + ForwardIt last, UnaryPred p ); Removes all elements satisfying specific criteria from the range [first, last) and returns a past-the-end iterator for the new end of the range. - The first version removes all elements that are equal to value, the second version - removes all elements for which predicate p returns true. + 1) Removes all elements that are equal to value (using operator==). + 3) Removes all elements for which predicate p returns true. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If the value type of ForwardIt is not CopyAssignable, the behavior is \fI(until C++11)\fP + undefined. + If the type of *first is not MoveAssignable, the behavior is \fI(since C++11)\fP + undefined. + +.SH Explanation - Removing is done by shifting the elements in the range in such a way that elements - to be erased are overwritten. Relative order of the elements that remain is - preserved and the physical size of the container is unchanged. Iterators pointing to - an element between the new logical end and the physical end of the range are still - dereferenceable, but the elements themselves have unspecified values. A call to - remove is typically followed by a call to a container's erase method, which erases - the unspecified values and reduces the physical size of the container to match its - new logical size. + Removing is done by shifting the elements in the range in such a way that the + elements that are not to be removed appear in the beginning of the range. + + * Shifting is done by + copy assignment + \fI(until C++11)\fP + move assignment + \fI(since C++11)\fP. + * The removing operation is stable: the relative order of the elements not to be + removed stays the same. + * The underlying sequence of [first, last) is not shortened by the removing + operation. Given result as the returned iterator: + + * All iterators in [result, last) are still dereferenceable. + + * Each element of [result, last) has a valid but unspecified state, + because move assignment can eliminate elements by moving from \fI(since C++11)\fP + elements that were originally in that range. .SH Parameters first, last - the range of elements to process value - the value of elements to remove + policy - the execution policy to use. See execution policy for details. unary predicate which returns true if the element should be removed. - The signature of the predicate function should be equivalent to the - following: - - p - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type ForwardIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of ForwardIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. - - - The type of dereferenced ForwardIt must meet the requirements of MoveAssignable. + ForwardIt must meet the requirements of LegacyForwardIterator. - UnaryPredicate must meet the requirements of Predicate. .SH Return value - Iterator to the new end of the range + Past-the-end iterator for the new range of values (if this is not end, then it + points to an unspecified value, and so do iterators to any values between this + iterator and end). .SH Complexity - Exactly std::distance(first, last) applications of the predicate. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize N\\)N comparisons using operator==. + 3,4) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + remove \fB(1)\fP + template::value_type> + ForwardIt remove(ForwardIt first, ForwardIt last, const T& value) + { + first = std::find(first, last, value); + if (first != last) + for (ForwardIt i = first; ++i != last;) + if (!(*i == value)) + *first++ = std::move(*i); + return first; + } + remove_if \fB(3)\fP + template + ForwardIt remove_if(ForwardIt first, ForwardIt last, UnaryPred p) + { + first = std::find_if(first, last, p); + if (first != last) + for (ForwardIt i = first; ++i != last;) + if (!p(*i)) + *first++ = std::move(*i); + return first; + } .SH Notes + A call to remove is typically followed by a call to a container's erase member + function to actually remove elements from the container. These two invocations + together constitute a so-called Erase-remove idiom. + + The same effect can also be achieved by the following non-member + functions: + \fI(since C++20)\fP + * std::erase, which has overloads for all standard sequence + containers. + * std::erase_if, which has overloads for all standard containers. + The similarly-named container member functions list::remove, list::remove_if, forward_list::remove, and forward_list::remove_if erase the removed elements. -.SH Possible implementation + These algorithms cannot be used with associative containers such as std::set and + std::map because their iterator types do not dereference to MoveAssignable types + (the keys in these containers are not modifiable). -.SH First version - template< class ForwardIt, class T > - ForwardIt remove(ForwardIt first, ForwardIt last, const T& value) - { - first = std::find(first, last, value); - if (first != last) - for(ForwardIt i = first; ++i != last; ) - if (!(*i == value)) - *first++ = std::move(*i); - return first; - } -.SH Second version - template - ForwardIt remove_if(ForwardIt first, ForwardIt last, UnaryPredicate p) - { - first = std::find_if(first, last, p); - if (first != last) - for(ForwardIt i = first; ++i != last; ) - if (!p(*i)) - *first++ = std::move(*i); - return first; - } - -.SH Examples + The standard library also defines an overload of std::remove in , which + takes a const char* and is used to delete files. + + Because std::remove takes value by reference, it can have unexpected behavior if it + is a reference to an element of the range [first, last). + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + +.SH Example The following code removes all spaces from a string by shifting all non-space characters to the left and then erasing the extra. This is an example of - erase-remove idiom. + Erase-remove idiom. + - // Run this code #include - #include - #include + #include #include - + #include + #include + #include + #include + #include + int main() { - std::string str1 = "Text with some spaces"; - str1.erase(std::remove(str1.begin(), str1.end(), ' '), - str1.end()); - std::cout << str1 << '\\n'; - + std::string str1{"Text with some spaces"}; + + auto noSpaceEnd = std::remove(str1.begin(), str1.end(), ' '); + + // The spaces are removed from the string only logically. + // Note, we use view, the original string is still not shrunk: + std::cout << std::string_view(str1.begin(), noSpaceEnd) + << " size: " << str1.size() << '\\n'; + + str1.erase(noSpaceEnd, str1.end()); + + // The spaces are removed from the string physically. + std::cout << str1 << " size: " << str1.size() << '\\n'; + std::string str2 = "Text\\n with\\tsome \\t whitespaces\\n\\n"; str2.erase(std::remove_if(str2.begin(), str2.end(), - [](char x){return std::isspace(x);}), + [](unsigned char x) { return std::isspace(x); }), str2.end()); std::cout << str2 << '\\n'; + + std::vector> nums{{2, 2}, {1, 3}, {4, 8}}; + #ifdef __cpp_lib_algorithm_default_value_type + nums.erase(std::remove(nums.begin(), nums.end(), {1, 3}), nums.end()); + #else + nums.erase(std::remove(nums.begin(), nums.end(), std::complex{1, 3}), + nums.end()); + #endif + assert((nums == std::vector>{{2, 2}, {4, 8}})); } .SH Output: - Textwithsomespaces + Textwithsomespaces size: 23 + Textwithsomespaces size: 18 Textwithsomewhitespaces + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be required the value type of + LWG 283 C++98 EqualityComparable, but ForwardIt + the value type of ForwardIt is not to be CopyAssignable instead + always T + .SH See also - remove_copy copies a range of elements omitting those that satisfy specific - remove_copy_if criteria - \fI(function template)\fP - unique removes consecutive duplicate elements in a range - \fI(function template)\fP + remove_copy copies a range of elements omitting those that satisfy specific + remove_copy_if criteria + \fI(function template)\fP + unique removes consecutive duplicate elements in a range + \fI(function template)\fP + ranges::remove + ranges::remove_if removes elements satisfying specific criteria + (C++20) (niebloid) + (C++20) diff --git a/man/std::remove.3 b/man/std::remove.3 index 349bdbdbf..31e3cdf96 100644 --- a/man/std::remove.3 +++ b/man/std::remove.3 @@ -1,14 +1,23 @@ -.TH std::remove 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove \- std::remove + .SH Synopsis Defined in header - int remove( const char *fname ); + int remove( const char* pathname ); + + Deletes the file identified by the character string pointed to by pathname. - Deletes the file identified by character string pointed to by fname. + If the file is currently open by any process, the behavior of this function is + implementation-defined. POSIX systems unlink the file name (directory entry), but + the filesystem space used by the file is not reclaimed while it is open in any + process and while other hard links to the file exist. Windows does not allow the + file to be deleted in such cases. .SH Parameters - fname - pointer to a null-terminated string containing the path identifying the file - to delete + pathname - pointer to a null-terminated string containing the path identifying the + file to delete .SH Return value @@ -16,34 +25,53 @@ .SH Notes - In POSIX the behavior for file types other than regular files is unspecified. + POSIX specifies many additional details for the behavior of this function. + + The standard library also defines a function template std::remove taking a pair of + iterators and a value, this overload is one of the standard algorithms. .SH Example - + // Run this code #include + #include + #include #include - + int main() { - const char* file_name = "C:\\\\file.txt"; - int ret_code = std::remove(file_name); - if (ret_code == 0) { - std::cout << "File was successfully deleted\\n"; - } else { - std::cerr << "Error during the deletion: " << ret_code << '\\n'; + // create a file, check success using operator! of temporary stream object + if (!std::ofstream("file1.txt").put('a')) + { + std::perror("Error creating file1.txt"); + return EXIT_FAILURE; + } + std::cout << std::ifstream("file1.txt").rdbuf() << '\\n'; // print file + + std::remove("file1.txt"); // delete file + + if (!std::ifstream{"file1.txt"}) // uses operator! of temporary stream object + { + std::perror("Error opening deleted file"); + return EXIT_FAILURE; } + return EXIT_SUCCESS; } .SH Possible output: - Error during the deletion: 1 + a + Error opening deleted file: No such file or directory .SH See also - rename renames a file - \fI(function)\fP + remove removes a file or empty directory + remove_all removes a file or directory and all its contents, recursively + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + rename renames a file + \fI(function)\fP C documentation for remove diff --git a/man/std::remove_all_extents.3 b/man/std::remove_all_extents.3 index 01ee83e49..d1d45529b 100644 --- a/man/std::remove_all_extents.3 +++ b/man/std::remove_all_extents.3 @@ -1,4 +1,7 @@ -.TH std::remove_all_extents 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove_all_extents 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_all_extents \- std::remove_all_extents + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -7,6 +10,9 @@ If T is a multidimensional array of some type X, provides the member typedef type equal to X, otherwise type is T. + If the program adds specializations for std::remove_all_extents, the behavior is + undefined. + .SH Member types Name Definition @@ -20,61 +26,70 @@ .SH Possible implementation template - struct remove_all_extents { typedef T type;}; - + struct remove_all_extents { typedef T type; }; + template struct remove_all_extents { typedef typename remove_all_extents::type type; }; - - template + + template struct remove_all_extents { typedef typename remove_all_extents::type type; }; .SH Example - + // Run this code #include #include #include - + template - void foo(const A&) + void info(const A&) { typedef typename std::remove_all_extents::type Type; std::cout << "underlying type: " << typeid(Type).name() << '\\n'; } - + int main() { + float a0; float a1[1][2][3]; - int a2[3][2]; - float a3[1][1][1][1][2]; - double a4[2][3]; - - foo(a1); - foo(a2); - foo(a3); - foo(a4); + float a2[1][1][1][1][2]; + float* a3; + int a4[3][2]; + double a5[2][3]; + struct X { int m; } x0[3][3]; + + info(a0); + info(a1); + info(a2); + info(a3); + info(a4); + info(a5); + info(x0); } -.SH Output: +.SH Possible output: - underlying type: f - underlying type: i - underlying type: f - underlying type: d + underlying type: float + underlying type: float + underlying type: float + underlying type: float* + underlying type: int + underlying type: double + underlying type: main::X .SH See also is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP rank obtains the number of dimensions of an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP extent obtains the size of an array type along a specified dimension - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_extent removes one extent from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::remove_copy,std::remove_copy_if.3 b/man/std::remove_copy,std::remove_copy_if.3 index db665d05e..53f9497d1 100644 --- a/man/std::remove_copy,std::remove_copy_if.3 +++ b/man/std::remove_copy,std::remove_copy_if.3 @@ -1,34 +1,110 @@ -.TH std::remove_copy,std::remove_copy_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove_copy,std::remove_copy_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_copy,std::remove_copy_if \- std::remove_copy,std::remove_copy_if + .SH Synopsis Defined in header - template< class InputIt, class OutputIt, class T > + template< class InputIt, class OutputIt, + class T > + (constexpr since + OutputIt remove_copy( InputIt first, C++20) + InputIt last, (until C++26) + + OutputIt d_first, + const T& value ); + template< class InputIt, class OutputIt, + + class T = typename + std::iterator_traits + + ::value_type > (since C++26) + constexpr OutputIt remove_copy( InputIt + first, InputIt last, + + OutputIt + d_first, const T& value ); + template< class ExecutionPolicy, + + class ForwardIt1, class + ForwardIt2, class T > + ForwardIt2 remove_copy( ExecutionPolicy&& \fI(since C++17)\fP + policy, (until C++26) + ForwardIt1 first, + ForwardIt1 last, + + ForwardIt2 + d_first, const T& value ); + template< class ExecutionPolicy, + \fB(1)\fP + class ForwardIt1, class + ForwardIt2, + class T = typename + std::iterator_traits + + ::value_type > (since C++26) + ForwardIt2 remove_copy( ExecutionPolicy&& + policy, + ForwardIt1 first, + ForwardIt1 last, \fB(2)\fP + + ForwardIt2 + d_first, const T& value ); + template< class InputIt, class OutputIt, + class UnaryPred > + + OutputIt remove_copy_if( InputIt first, \fB(3)\fP (constexpr since + InputIt last, C++20) + + OutputIt d_first, + UnaryPred p ); + template< class ExecutionPolicy, + + class ForwardIt1, class + ForwardIt2, class UnaryPred > + ForwardIt2 remove_copy_if( + ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 + first, ForwardIt1 last, + + ForwardIt2 + d_first, UnaryPred p ); - OutputIt remove_copy( InputIt first, InputIt last, OutputIt d_first, \fB(1)\fP + Copies elements from the range [first, last), to another range beginning at d_first, + omitting the elements which satisfy specific criteria. - const T& value ); - template< class InputIt, class OutputIt, class UnaryPredicate > + 1) Ignores all elements that are equal to value (using operator==). + 3) Ignores all elements for which predicate p returns true. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if - OutputIt remove_copy_if( InputIt first, InputIt last, OutputIt d_first, \fB(2)\fP + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) - UnaryPredicate p ); + If + *d_first = *first is invalid + \fI(until C++20)\fP + *first is not writable to d_first + \fI(since C++20)\fP, the program is ill-formed. - Copies elements from the range [first, last), to another range beginning at d_first, - omitting the elements which satisfy specific criteria. The first version ignores the - elements that are equal to value, the second version ignores the elements for which - predicate p returns true. Source and destination ranges cannot overlap. + If source and destination ranges overlap, the behavior is undefined. .SH Parameters - first, last - the range of elements to copy - d_first - the beginning of the destination range. - value - the value of the elements not to copy + first, last - the range of elements to copy + d_first - the beginning of the destination range + value - the value of the elements not to copy + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - UnaryPredicate must meet the requirements of Predicate. + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + UnaryPred must meet the requirements of Predicate. .SH Return value @@ -36,63 +112,115 @@ .SH Complexity - Exactly last - first applications of the predicate. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize N\\)N comparisons with value using operator==. + 3,4) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + + For the overloads with an ExecutionPolicy, there may be a performance cost if + ForwardIt1's value_type is not MoveConstructible. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - OutputIt remove_copy(InputIt first, InputIt last, - OutputIt d_first, const T& value) + remove_copy \fB(1)\fP + template::value_type> + constexpr OutputIt remove_copy(InputIt first, InputIt last, + OutputIt d_first, const T& value) { - for (; first != last; ++first) { - if (!(*first == value)) { + for (; first != last; ++first) + if (!(*first == value)) *d_first++ = *first; - } - } return d_first; } -.SH Second version - template - OutputIt remove_copy_if(InputIt first, InputIt last, - OutputIt d_first, UnaryPredicate p) + remove_copy_if \fB(3)\fP + template + constexpr OutputIt remove_copy_if(InputIt first, InputIt last, + OutputIt d_first, UnaryPred p) { - for (; first != last; ++first) { - if (!p(*first)) { + for (; first != last; ++first) + if (!p(*first)) *d_first++ = *first; - } - } return d_first; } +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) + .SH Example - The following code outputs a string while erasing the spaces on the fly. - // Run this code #include + #include + #include + #include #include #include - #include + #include + int main() { - std::string str = "Text with some spaces"; - std::cout << "before: " << str << "\\n"; - - std::cout << "after: "; + // Erase the hash characters '#' on the fly. + std::string str = "#Return #Value #Optimization"; + std::cout << "before: " << std::quoted(str) << '\\n'; + + std::cout << "after: \\""; std::remove_copy(str.begin(), str.end(), - std::ostream_iterator(std::cout), ' '); - std::cout << '\\n'; + std::ostream_iterator(std::cout), '#'); + std::cout << "\\"\\n"; + + // Erase {1, 3} value on the fly. + std::vector> nums{{2, 2}, {1, 3}, {4, 8}, {1, 3}}; + std::remove_copy(nums.begin(), nums.end(), + std::ostream_iterator>(std::cout), + #ifdef __cpp_lib_algorithm_default_value_type + {1, 3}); // T gets deduced + #else + std::complex{1, 3}); + #endif } .SH Output: - before: Text with some spaces - after: Textwithsomespaces + before: "#Return #Value #Optimization" + after: "Return Value Optimization" + (2,2)(4,8) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, but required *d_first = + LWG 779 C++98 the value type of ForwardIt is not always T *first + to be valid instead .SH See also - remove removes elements satisfying specific criteria - remove_if \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + partition_copy copies a range dividing the elements into two groups + \fI(C++11)\fP \fI(function template)\fP + ranges::remove_copy copies a range of elements omitting those that satisfy + ranges::remove_copy_if specific criteria + (C++20) (niebloid) + (C++20) diff --git a/man/std::remove_cv,std::remove_const,std::remove_volatile.3 b/man/std::remove_cv,std::remove_const,std::remove_volatile.3 index bad8237bf..cd698ef1b 100644 --- a/man/std::remove_cv,std::remove_const,std::remove_volatile.3 +++ b/man/std::remove_cv,std::remove_const,std::remove_volatile.3 @@ -1,4 +1,7 @@ -.TH std::remove_cv,std::remove_const,std::remove_volatile 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove_cv,std::remove_const,std::remove_volatile 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_cv,std::remove_const,std::remove_volatile \- std::remove_cv,std::remove_const,std::remove_volatile + .SH Synopsis Defined in header template< class T > \fB(1)\fP \fI(since C++11)\fP @@ -11,11 +14,12 @@ Provides the member typedef type which is the same as T, except that its topmost cv-qualifiers are removed. - 1) removes the topmost const, the topmost volatile, or both, if present. - - 2) removes the topmost const + 1) Removes the topmost const, or the topmost volatile, or both, if present. + 2) Removes the topmost const. + 3) Removes the topmost volatile. - 3) removes the topmost volatile + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. .SH Member types @@ -25,66 +29,64 @@ .SH Helper types template< class T > \fI(since C++14)\fP - using remove_cv_t = typename remove_cv::type; + using remove_cv_t = typename remove_cv::type; template< class T > \fI(since C++14)\fP - using remove_const_t = typename remove_const::type; + using remove_const_t = typename remove_const::type; template< class T > \fI(since C++14)\fP using remove_volatile_t = typename remove_volatile::type; .SH Possible implementation -template< class T > -struct remove_cv { - typedef typename std::remove_volatile::type>::type type; -}; - -template< class T > struct remove_const { typedef T type; }; -template< class T > struct remove_const { typedef T type; }; - -template< class T > struct remove_volatile { typedef T type; }; -template< class T > struct remove_volatile { typedef T type; }; + template struct remove_cv { typedef T type; }; + template struct remove_cv { typedef T type; }; + template struct remove_cv { typedef T type; }; + template struct remove_cv { typedef T type; }; + + template struct remove_const { typedef T type; }; + template struct remove_const { typedef T type; }; + + template struct remove_volatile { typedef T type; }; + template struct remove_volatile { typedef T type; }; .SH Example - Removing const/volatile from const volatile int * does not modify the type, because + Removing const/volatile from const volatile int* does not modify the type, because the pointer itself is neither const nor volatile. - + // Run this code - #include #include - - int main() { - typedef std::remove_cv::type type1; - typedef std::remove_cv::type type2; - typedef std::remove_cv::type type3; - typedef std::remove_cv::type type4; - typedef std::remove_cv::type type5; - - std::cout << "test1 " << (std::is_same::value - ? "passed" : "failed") << '\\n'; - std::cout << "test2 " << (std::is_same::value - ? "passed" : "failed") << '\\n'; - std::cout << "test3 " << (std::is_same::value - ? "passed" : "failed") << '\\n'; - std::cout << "test4 " << (std::is_same::value - ? "passed" : "failed") << '\\n'; - std::cout << "test5 " << (std::is_same::value - ? "passed" : "failed") << '\\n'; - } - -.SH Output: - - test1 passed - test2 passed - test3 passed - test4 passed - test5 passed + + template + constexpr bool same = std::is_same_v; + + static_assert + ( + same, int> && + same, int> && + same, int> && + same, int> && + // remove_cv only works on types, not on pointers + not same, int*> && + same, const volatile int*> && + same, const int*> && + same, int*> + ); + + int main() {} .SH See also - is_const checks if a type is const-qualified - \fI(C++11)\fP \fI(class template)\fP - is_volatile checks if a type is volatile-qualified - \fI(C++11)\fP \fI(class template)\fP + is_const checks if a type is const-qualified + \fI(C++11)\fP \fI(class template)\fP + is_volatile checks if a type is volatile-qualified + \fI(C++11)\fP \fI(class template)\fP + add_cv + add_const + add_volatile adds const and/or volatile specifiers to the given type + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remove_cvref combines std::remove_cv and std::remove_reference + (C++20) \fI(class template)\fP diff --git a/man/std::remove_cvref.3 b/man/std::remove_cvref.3 new file mode 100644 index 000000000..cd429a747 --- /dev/null +++ b/man/std::remove_cvref.3 @@ -0,0 +1,71 @@ +.TH std::remove_cvref 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_cvref \- std::remove_cvref + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + struct remove_cvref; + + If the type T is a reference type, provides the member typedef type which is the + type referred to by T with its topmost cv-qualifiers removed. Otherwise type is T + with its topmost cv-qualifiers removed. + + If the program adds specializations for std::remove_cvref, the behavior is + undefined. + +.SH Member types + + Name Definition + type the type referred by T or T itself if it is not a reference, with top-level + cv-qualifiers removed + +.SH Helper types + + template< class T > \fI(since C++20)\fP + using remove_cvref_t = remove_cvref::type; + +.SH Possible implementation + + template + struct remove_cvref + { + using type = std::remove_cv_t>; + }; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_remove_cvref 201711L (C++20) std::remove_cvref + +.SH Example + + +// Run this code + + #include + + int main() + { + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, int[2]>); + static_assert(std::is_same_v, int[2]>); + static_assert(std::is_same_v, int(int)>); + } + +.SH See also + + remove_cv + remove_const + remove_volatile removes const and/or volatile specifiers from the given type + \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remove_reference removes a reference from the given type + \fI(C++11)\fP \fI(class template)\fP + decay applies type transformations as when passing a function argument by + \fI(C++11)\fP value + \fI(class template)\fP diff --git a/man/std::remove_extent.3 b/man/std::remove_extent.3 index 1e259dcfe..3a9808d99 100644 --- a/man/std::remove_extent.3 +++ b/man/std::remove_extent.3 @@ -1,4 +1,7 @@ -.TH std::remove_extent 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove_extent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_extent \- std::remove_extent + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -8,6 +11,9 @@ otherwise type is T. Note that if T is a multidimensional array, only the first dimension is removed. + If the program adds specializations for std::remove_extent, the behavior is + undefined. + .SH Member types Name Definition @@ -21,36 +27,36 @@ .SH Possible implementation template - struct remove_extent { typedef T type; }; - + struct remove_extent { using type = T; }; + template - struct remove_extent { typedef T type; }; - + struct remove_extent { using type = T; }; + template - struct remove_extent { typedef T type;}; + struct remove_extent { using type = T; }; .SH Example - + // Run this code + #include #include #include - #include #include - + template - typename std::enable_if< std::rank::value == 1 >::type + std::enable_if_t == 1> print_1d(const A& a) { - copy(a, a+std::extent::value, - std::ostream_iterator::type>(std::cout, " ")); + std::copy(a, a + std::extent_v, + std::ostream_iterator>(std::cout, " ")); std::cout << '\\n'; } - + int main() { - int a[][3] = {{1,2,3},{4,5,6}}; + int a[][3] = {{1, 2, 3}, {4, 5, 6}}; // print_1d(a); // compile-time error print_1d(a[1]); } @@ -62,10 +68,10 @@ .SH See also is_array checks if a type is an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP rank obtains the number of dimensions of an array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP extent obtains the size of an array type along a specified dimension - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP remove_all_extents removes all extents from the given array type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::remove_pointer.3 b/man/std::remove_pointer.3 index c19691d20..1c951bd82 100644 --- a/man/std::remove_pointer.3 +++ b/man/std::remove_pointer.3 @@ -1,4 +1,7 @@ -.TH std::remove_pointer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove_pointer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_pointer \- std::remove_pointer + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -7,6 +10,9 @@ Provides the member typedef type which is the type pointed to by T, or, if T is not a pointer, then type is the same as T. + If the program adds specializations for std::remove_pointer, the behavior is + undefined. + .SH Member types Name Definition @@ -19,69 +25,37 @@ .SH Possible implementation - template< class T > struct remove_pointer {typedef T type;}; - template< class T > struct remove_pointer {typedef T type;}; - template< class T > struct remove_pointer {typedef T type;}; - template< class T > struct remove_pointer {typedef T type;}; - template< class T > struct remove_pointer {typedef T type;}; + template struct remove_pointer { typedef T type; }; + template struct remove_pointer { typedef T type; }; + template struct remove_pointer { typedef T type; }; + template struct remove_pointer { typedef T type; }; + template struct remove_pointer { typedef T type; }; .SH Example - + // Run this code - #include #include - - template - void print_is_same() - { - std::cout << std::is_same() << '\\n'; - } - - void print_separator() - { - std::cout << "-----\\n"; - } - - int main() - { - std::cout << std::boolalpha; - - print_is_same(); // true - print_is_same(); // false - print_is_same(); // false - - print_separator(); - - print_is_same::type>(); // true - print_is_same::type>(); // true - print_is_same::type>(); // false - - print_separator(); - - print_is_same::type>(); // true - print_is_same::type>(); // true - print_is_same::type>(); // true - } - -.SH Output: - - true - false - false - ----- - true - true - false - ----- - true - true - true + + static_assert + ( + std::is_same_v == true && + std::is_same_v == false && + std::is_same_v == false && + std::is_same_v> == true && + std::is_same_v> == true && + std::is_same_v> == false && + std::is_same_v> == true && + std::is_same_v> == true && + std::is_same_v> == true + ); + + int main() {} .SH See also is_pointer checks if a type is a pointer type - \fI(C++11)\fP \fI(class template)\fP - add_pointer adds pointer to the given type - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP + add_pointer adds a pointer to the given type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::remove_reference.3 b/man/std::remove_reference.3 index 3bf6933a2..3d4465026 100644 --- a/man/std::remove_reference.3 +++ b/man/std::remove_reference.3 @@ -1,4 +1,7 @@ -.TH std::remove_reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::remove_reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remove_reference \- std::remove_reference + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -7,6 +10,9 @@ If the type T is a reference type, provides the member typedef type which is the type referred to by T. Otherwise type is T. + If the program adds specializations for std::remove_reference, the behavior is + undefined. + .SH Member types Name Definition @@ -19,49 +25,48 @@ .SH Possible implementation - template< class T > struct remove_reference {typedef T type;}; - template< class T > struct remove_reference {typedef T type;}; - template< class T > struct remove_reference {typedef T type;}; + template struct remove_reference { typedef T type; }; + template struct remove_reference { typedef T type; }; + template struct remove_reference { typedef T type; }; .SH Example - + // Run this code - #include // std::cout - #include // std::is_same - - template - void print_is_same() { - std::cout << std::is_same() << '\\n'; - } - - int main() { - std::cout << std::boolalpha; - - print_is_same(); // true - print_is_same(); // false - print_is_same(); // false - - print_is_same::type>(); // true - print_is_same::type>(); // true - print_is_same::type>(); // true + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::cout << "std::remove_reference::type is int? " + << std::is_same::type>::value << '\\n'; + std::cout << "std::remove_reference::type is int? " + << std::is_same::type>::value << '\\n'; + std::cout << "std::remove_reference::type is int? " + << std::is_same::type>::value << '\\n'; + std::cout << "std::remove_reference::type is const int? " + << std::is_same::type>::value << '\\n'; } .SH Output: - true - false - false - true - true - true + std::remove_reference::type is int? true + std::remove_reference::type is int? true + std::remove_reference::type is int? true + std::remove_reference::type is const int? true .SH See also - is_reference checks if a type is either lvalue reference or rvalue reference - \fI(C++11)\fP \fI(class template)\fP + is_reference checks if a type is either an lvalue reference or rvalue + \fI(C++11)\fP reference + \fI(class template)\fP add_lvalue_reference - add_rvalue_reference adds lvalue or rvalue reference to the given type - \fI(C++11)\fP \fI(class template)\fP + add_rvalue_reference adds an lvalue or rvalue reference to the given type + \fI(C++11)\fP \fI(class template)\fP \fI(C++11)\fP + remove_cvref combines std::remove_cv and std::remove_reference + (C++20) \fI(class template)\fP diff --git a/man/std::remquo,std::remquof,std::remquol.3 b/man/std::remquo,std::remquof,std::remquol.3 new file mode 100644 index 000000000..35f3a942c --- /dev/null +++ b/man/std::remquo,std::remquof,std::remquol.3 @@ -0,0 +1,222 @@ +.TH std::remquo,std::remquof,std::remquol 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::remquo,std::remquof,std::remquol \- std::remquo,std::remquof,std::remquol + +.SH Synopsis + Defined in header + float remquo ( float x, float y, int* quo ); + + double remquo ( double x, double y, int* quo ); \fI(since C++11)\fP + (until C++23) + long double remquo ( long double x, long double y, + int* quo ); + constexpr /* floating-point-type */ + + remquo ( /* floating-point-type */ x, (since C++23) + + /* floating-point-type */ y, + int* quo ); \fB(1)\fP + float remquof( float x, float y, int* quo ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double remquol( long double x, long double y, \fB(3)\fP \fI(since C++11)\fP + int* quo ); (constexpr since C++23) + Additional overloads + Defined in header + template< class Arithmetic1, class Arithmetic2 > + + /* common-floating-point-type */ (A) \fI(since C++11)\fP + (constexpr since C++23) + remquo( Arithmetic1 x, Arithmetic2 y, int* quo + ); + + 1-3) Computes the floating-point remainder of the division operation x / y as the + std::remainder() function does. Additionally, the sign and at least the three of the + last bits of x / y will be stored in quo, sufficient to determine the octant of the + result within a period. + The library provides overloads of std::remquo for all cv-unqualified floating-point + types as the type of the parameters x and y. + (since C++23) + A) Additional overloads are provided for all other combinations of arithmetic types. + +.SH Parameters + + x, y - floating-point or integer values + quo - pointer to int to store the sign and some bits of x / y + +.SH Return value + + If successful, returns the floating-point remainder of the division x / y as defined + in std::remainder, and stores, in *quo, the sign and at least three of the least + significant bits of x / y (formally, stores a value whose sign is the sign of x / y + and whose magnitude is congruent modulo 2n + to the magnitude of the integral quotient of x / y, where n is an + implementation-defined integer greater than or equal to 3). + + If y is zero, the value stored in *quo is unspecified. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result is returned if + subnormals are supported. + + If y is zero, but the domain error does not occur, zero is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error may occur if y is zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * The current rounding mode has no effect. + * FE_INEXACT is never raised. + * If x is ±∞ and y is not NaN, NaN is returned and FE_INVALID is raised. + * If y is ±0 and x is not NaN, NaN is returned and FE_INVALID is raised. + * If either x or y is NaN, NaN is returned. + +.SH Notes + + POSIX requires that a domain error occurs if x is infinite or y is zero. + + This function is useful when implementing periodic functions with the period exactly + representable as a floating-point value: when calculating sin(πx) for a very large + x, calling std::sin directly may result in a large error, but if the function + argument is first reduced with std::remquo, the low-order bits of the quotient may + be used to determine the sign and the octant of the result within the period, while + the remainder may be used to calculate the value with high precision. + + On some platforms this operation is supported by hardware (and, for example, on + Intel CPUs, FPREM1 leaves exactly 3 bits of precision in the quotient when + complete). + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their first argument num1 and second + argument num2: + + * If num1 or num2 has type long double, then std::remquo(num1, num2, + quo) has the same effect as std::remquo(static_cast(num1), + static_cast(num2), quo). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::remquo(num1, num2, quo) has the same effect as (until C++23) + std::remquo(static_cast(num1), + static_cast(num2), quo). + * Otherwise, if num1 or num2 has type float, then std::remquo(num1, + num2, quo) has the same effect as + std::remquo(static_cast(num1), + static_cast(num2), quo). + If num1 and num2 have arithmetic types, then std::remquo(num1, num2, + quo) has the same effect as std::remquo(static_cast(num1), + static_cast(num2), quo), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + #ifndef __GNUC__ + #pragma STDC FENV_ACCESS ON + #endif + + const double pi = std::acos(-1); // or std::numbers::pi since C++20 + + double cos_pi_x_naive(double x) + { + return std::cos(pi * x); + } + + // the period is 2, values are (0;0.5) positive, (0.5;1.5) negative, (1.5,2) positive + double cos_pi_x_smart(double x) + { + int quadrant; + double rem = std::remquo(x, 1, &quadrant); + quadrant = static_cast(quadrant) % 2; // The period is 2. + return quadrant == 0 ? std::cos(pi * rem) + : -std::cos(pi * rem); + } + + int main() + { + std::cout << std::showpos + << "naive:\\n" + << " cos(pi * 0.25) = " << cos_pi_x_naive(0.25) << '\\n' + << " cos(pi * 1.25) = " << cos_pi_x_naive(1.25) << '\\n' + << " cos(pi * 2.25) = " << cos_pi_x_naive(2.25) << '\\n' + << "smart:\\n" + << " cos(pi * 0.25) = " << cos_pi_x_smart(0.25) << '\\n' + << " cos(pi * 1.25) = " << cos_pi_x_smart(1.25) << '\\n' + << " cos(pi * 2.25) = " << cos_pi_x_smart(2.25) << '\\n' + << "naive:\\n" + << " cos(pi * 1000000000000.25) = " + << cos_pi_x_naive(1000000000000.25) << '\\n' + << " cos(pi * 1000000000001.25) = " + << cos_pi_x_naive(1000000000001.25) << '\\n' + << "smart:\\n" + << " cos(pi * 1000000000000.25) = " + << cos_pi_x_smart(1000000000000.25) << '\\n' + << " cos(pi * 1000000000001.25) = " + << cos_pi_x_smart(1000000000001.25) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + int quo; + std::cout << "remquo(+Inf, 1) = " << std::remquo(INFINITY, 1, &quo) << '\\n'; + if (fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + naive: + cos(pi * 0.25) = +0.707107 + cos(pi * 1.25) = -0.707107 + cos(pi * 2.25) = +0.707107 + smart: + cos(pi * 0.25) = +0.707107 + cos(pi * 1.25) = -0.707107 + cos(pi * 2.25) = +0.707107 + naive: + cos(pi * 1000000000000.25) = +0.707123 + cos(pi * 1000000000001.25) = -0.707117 + smart: + cos(pi * 1000000000000.25) = +0.707107 + cos(pi * 1000000000001.25) = -0.707107 + remquo(+Inf, 1) = -nan + FE_INVALID raised + +.SH See also + + div(int) + ldiv computes quotient and remainder of integer division + lldiv \fI(function)\fP + \fI(C++11)\fP + fmod + fmodf remainder of the floating point division operation + fmodl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + remainder + remainderf + remainderl signed remainder of the division operation + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + remquo diff --git a/man/std::remquo.3 b/man/std::remquo.3 deleted file mode 100644 index cf6ce4329..000000000 --- a/man/std::remquo.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH std::remquo 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float remquo( float x, float y, int *quo ); \fB(1)\fP \fI(since C++11)\fP - double remquo( double x, double y, int *quo ); \fB(2)\fP \fI(since C++11)\fP - long double remquo( long double x, long double y, int *quo ); \fB(3)\fP \fI(since C++11)\fP - Promoted remquo( Arithmetic1 x, Arithmetic2 y, int *quo ); \fB(4)\fP \fI(since C++11)\fP - - Computes the remainder of the floating point division operation x/y as the - std::remainder() function does. Additionally, the sign and at least the three of the - last bits of x/y will be stored in quo. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double - -.SH Parameters - - x, y - floating point values - quo - pointer to an integer value to store some bits of x/y in - -.SH Return value - - Remainder of dividing arguments. - -.SH Notes - - This function is useful when implementing periodic functions with the period exactly - representable as a floating-point value: when calculating sin(πx) for a very large - x, calling std::sin directly may result in a large error, but if the function - argument is first reduced with std::remquo, the low-order bits of the quotient may - be used to determine the sign and the remainder may be used to calculate the value - with high precision. - -.SH See also - - remainder signed remainder of the division operation - \fI(C++11)\fP \fI(function)\fP - fmod remainder of the floating point division operation - \fI(function)\fP - div - ldiv the quotient and remainder of integer division - lldiv \fI(function)\fP - imaxdiv - \fI(C++11)\fP - C documentation for - remquo diff --git a/man/std::rename.3 b/man/std::rename.3 index 86e2c537a..e06cc4386 100644 --- a/man/std::rename.3 +++ b/man/std::rename.3 @@ -1,12 +1,17 @@ -.TH std::rename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rename \- std::rename + .SH Synopsis Defined in header - int rename( const char *old_filename, const char *new_filename ); + int rename( const char* old_filename, const char* new_filename ); Changes the filename of a file. The file is identified by character string pointed to by old_filename. The new filename is identified by character string pointed to by new_filename. + If new_filename exists, the behavior is implementation-defined. + .SH Parameters old_filename - pointer to a null-terminated string containing the path identifying @@ -18,18 +23,48 @@ 0 upon success or non-zero value on error. +.SH Notes + + POSIX specifies many additional details on the semantics of this function, which are + reproduced in C++ by std::filesystem::rename. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + if (!std::ofstream("from.txt").put('a')) // create and write to file + { + std::perror("Error creating from.txt"); + return EXIT_FAILURE; + } + + if (std::rename("from.txt", "to.txt")) + { + std::perror("Error renaming"); + return EXIT_FAILURE; + } + + std::cout << std::ifstream("to.txt").rdbuf() << '\\n'; // print file + return EXIT_SUCCESS; + } + +.SH Output: + + a .SH See also - remove erases a file - \fI(function)\fP + rename moves or renames a file or directory + \fI(C++17)\fP \fI(function)\fP + remove erases a file + \fI(function)\fP C documentation for rename - -.SH Category: - - * Todo no example diff --git a/man/std::rend(std::initializer_list).3 b/man/std::rend(std::initializer_list).3 deleted file mode 100644 index 392eee1c5..000000000 --- a/man/std::rend(std::initializer_list).3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH std::rend(std::initializer_list) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template \fI(since C++14)\fP - std::reverse_iterator rend( std::initializer_list il ); - - The overload of std::rend for initializer_list returns an std::reverse_iterator - pointing at the first element of il. - -.SH Parameters - - il - an initializer_list - -.SH Return value - - std::reverse_iterator(il.begin()). - -.SH Exceptions - - \fI(none)\fP - -.SH Notes - - This overload is necessary because std::initializer_list does not have a member - function rend. No overload is needed for std::crend because it is implemented in - terms of std::rend. - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - rbegin returns a reverse iterator to a container or array - crbegin \fI(function)\fP - \fI(C++14)\fP - rend returns a reverse end iterator for a container or array - crend \fI(function)\fP - \fI(C++14)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::rend,std::crend.3 b/man/std::rend,std::crend.3 new file mode 100644 index 000000000..52450a237 --- /dev/null +++ b/man/std::rend,std::crend.3 @@ -0,0 +1,150 @@ +.TH std::rend,std::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rend,std::crend \- std::rend,std::crend + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + template< class C > (since + auto rend( C& c ) -> C++14) + decltype(c.rend()); (until + C++17) + template< class C > (since + constexpr auto rend( C& c ) -> C++17) + decltype(c.rend()); + template< class C > (since + auto rend( const C& c ) -> C++14) + decltype(c.rend()); (until + C++17) + template< class C > (since + constexpr auto rend( const C& c ) -> C++17) + decltype(c.rend()); + template< class T, std::size_t N > (since + std::reverse_iterator rend( T C++14) + (&array)[N] ); (until + \fB(1)\fP C++17) + template< class T, std::size_t N > (since + constexpr std::reverse_iterator C++17) + rend( T (&array)[N] ); + template< class T > \fB(2)\fP (since + std::reverse_iterator C++14) + rend( std::initializer_list il ); (until + \fB(3)\fP C++17) + template< class T > + constexpr (since + std::reverse_iterator C++17) + rend( std::initializer_list il ); \fB(4)\fP + template< class C > (since + auto crend( const C& c ) -> C++14) + decltype(std::rend(c)); (until + \fB(5)\fP C++17) + template< class C > (since + constexpr auto crend( const C& c ) C++17) + -> decltype(std::rend(c)); + + Returns an iterator to the reverse-end of the given range. + + 1,2) Returns c.rend(), which is typically an iterator one past the reverse-end of + the sequence represented by c. + 1) If C is a standard Container, returns a C::reverse_iterator object. + 2) If C is a standard Container, returns a C::const_reverse_iterator object. + 3) Returns an std::reverse_iterator object to the reverse-end of array. + 4) Returns an std::reverse_iterator object to the reverse-end of il. + 5) Returns std::end(c), with c always treated as const-qualified. + If C is a standard Container, returns a C::const_reverse_iterator object. + + range-rbegin-rend.svg + +.SH Parameters + + c - a container or view with a rend member function + array - an array of arbitrary type + il - an std::initializer_list + +.SH Return value + + 1,2) c.rend() + 3) std::reverse_iterator(array) + 4) std::reverse_iterator(il.begin()) + 5) c.rend() + +.SH Exceptions + + May throw implementation-defined exceptions. + + Overloads + + Custom overloads of rend may be provided for classes and enumerations that do not + expose a suitable rend() member function, yet can be iterated. + + Overloads of rend found by argument-dependent lookup can be used to \fI(since C++20)\fP + customize the behavior of std::ranges::rend and std::ranges::crend. + +.SH Notes + + The overload for std::initializer_list is necessary because it does not have a + member function rend. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + int a[]{4, 6, -3, 9, 10}; + std::cout << "C-style array `a` backwards: "; + std::copy(std::rbegin(a), std::rend(a), std::ostream_iterator(std::cout, " ")); + + auto il = {3, 1, 4}; + std::cout << "\\nstd::initializer_list `il` backwards: "; + std::copy(std::rbegin(il), std::rend(il), std::ostream_iterator(std::cout, " ")); + + std::vector v{4, 6, -3, 9, 10}; + std::cout << "\\nstd::vector `v` backwards: "; + std::copy(std::rbegin(v), std::rend(v), std::ostream_iterator(std::cout, " ")); + std::cout << '\\n'; + } + +.SH Output: + + C-style array `a` backwards: 10 9 -3 6 4 + std::initializer_list `il` backwards: 4 1 3 + std::vector `v` backwards: 10 9 -3 6 4 + +.SH See also + + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP + ranges::rend returns a reverse end iterator to a range + (C++20) (customization point object) + ranges::crend returns a reverse end iterator to a read-only range + (C++20) (customization point object) diff --git a/man/std::rend.3 b/man/std::rend.3 deleted file mode 100644 index 09f05ebb9..000000000 --- a/man/std::rend.3 +++ /dev/null @@ -1,68 +0,0 @@ -.TH std::rend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class C > \fB(1)\fP \fI(since C++14)\fP - auto rend( C& c ) -> decltype(c.rend()); - template< class C > \fB(1)\fP \fI(since C++14)\fP - auto rend( const C& c ) -> decltype(c.rend()); - template< class T, size_t N > \fB(2)\fP \fI(since C++14)\fP - reverse_iterator rend( T (&array)[N] ); - template< class C > \fB(3)\fP \fI(since C++14)\fP - auto crend( const C& c ) -> decltype(std::rend(c)); - - Returns an iterator to the reverse-end of the given container c or array array. - - 1) Returns a possibly const-qualified iterator to the reverse-end of the container - c. - 2) Returns std::reverse_iterator to the reverse-end of the array array. - 3) Returns a const-qualified iterator to the reverse-end of the container c. - - range-rbegin-rend.svg - -.SH Parameters - - c - a container with a rend method - array - an array of arbitrary type - -.SH Return value - - An iterator to the reverse-end of c or array - -.SH Notes - - In addition to being included in , std::rend is guaranteed to become - available if any of the following headers are included: , , - , , , , , , , - , and . - -.SH Specializations - - Custom specializations of std::rend may be provided for classes that do not expose a - suitable rend() member function, yet can be iterated. The following specializations - are already provided by the standard library: - - rend(std::initializer_list) specializes std::rend - \fI(C++14)\fP \fI(function)\fP - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - end - cend returns an iterator to the end of a container or array - \fI(C++11)\fP \fI(function)\fP - \fI(C++14)\fP - rbegin returns a reverse iterator to a container or array - crbegin \fI(function)\fP - \fI(C++14)\fP - begin - cbegin returns an iterator to the beginning of a container or array - \fI(C++11)\fP \fI(function)\fP - \fI(C++14)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::replace,std::replace_if.3 b/man/std::replace,std::replace_if.3 index 3f39804e2..5e207ed9d 100644 --- a/man/std::replace,std::replace_if.3 +++ b/man/std::replace,std::replace_if.3 @@ -1,43 +1,138 @@ -.TH std::replace,std::replace_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::replace,std::replace_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::replace,std::replace_if \- std::replace,std::replace_if + .SH Synopsis Defined in header - template< class ForwardIt, class T > + template< class ForwardIt, class + T > + (constexpr + void replace( ForwardIt first, since C++20) + ForwardIt last, (until C++26) + + const T& old_value, + const T& new_value ); + template< class ForwardIt, class + T = typename std::iterator_traits + + + ::value_type > (since C++26) + constexpr void replace( ForwardIt + first, ForwardIt last, + + const T& + old_value, const T& new_value ); + template< class ExecutionPolicy, + class ForwardIt, class T > + + void replace( ExecutionPolicy&& (since + policy, C++17) + ForwardIt first, (until + ForwardIt last, C++26) + + const T& old_value, + const T& new_value ); + template< class ExecutionPolicy, + class ForwardIt, + + class T = typename + std::iterator_traits + + ::value_type > (since + void replace( ExecutionPolicy&& C++26) + policy, + ForwardIt first, + ForwardIt last, + + const T& old_value, + const T& new_value ); + template< class ForwardIt, class + UnaryPred, class T > + \fB(1)\fP (constexpr + void replace_if( ForwardIt first, since C++20) + ForwardIt last, (until + C++26) + UnaryPred p, + const T& new_value ); + template< class ForwardIt, class + UnaryPred, - void replace( ForwardIt first, ForwardIt last, \fB(1)\fP + class T = typename \fB(2)\fP + std::iterator_traits + (since + ::value_type> > C++26) + constexpr void replace_if( + ForwardIt first, ForwardIt last, - const T& old_value, const T& new_value ); - template< class ForwardIt, class UnaryPredicate, class T > - void replace_if( ForwardIt first, ForwardIt last, \fB(2)\fP + UnaryPred p, const T& new_value + ); + template< class ExecutionPolicy, - UnaryPredicate p, const T& new_value ); + class ForwardIt, class \fB(3)\fP + UnaryPred, class T > (since + void replace_if( C++17) + ExecutionPolicy&& policy, (until + ForwardIt first, C++26) + ForwardIt last, - Replaces all elements satisfying specific criteria with new_value in the range - [first, last). The first version replaces the elements that are equal to old_value, - the second version replaces elements for which predicate p returns true. + UnaryPred p, + const T& new_value ); + template< class ExecutionPolicy, + \fB(4)\fP + class ForwardIt, class + UnaryPred, + class T = typename + std::iterator_traits + (since + ::value_type> > C++26) + void replace_if( + ExecutionPolicy&& policy, + ForwardIt first, + ForwardIt last, + + UnaryPred p, + const T& new_value ); + + Replaces all elements in the range [first, last) with new_value if they satisfy + specific criteria. + + 1) Replaces all elements that are equal to old_value (using operator==). + 3) Replaces all elements for which predicate p returns true. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If + *first = new_value is invalid + \fI(until C++20)\fP + new_value is not writable to first + \fI(since C++20)\fP, the program is ill-formed. .SH Parameters first, last - the range of elements to process old_value - the value of elements to replace + policy - the execution policy to use. See execution policy for details. unary predicate which returns true if the element value should be replaced. - The signature of the predicate function should be equivalent to the - following: - p - - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type ForwardIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of ForwardIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. new_value - the value to use as replacement .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value @@ -45,72 +140,120 @@ .SH Complexity - Exactly last - first applications of the predicate. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize N\\)N comparisons using operator==. + 3,4) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + Because the algorithm takes old_value and new_value by reference, it can have + unexpected behavior if either is a reference to an element of the range + [first, last). + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1-4) .SH Possible implementation -.SH First version - template + replace + template::value_type> void replace(ForwardIt first, ForwardIt last, const T& old_value, const T& new_value) { - for (; first != last; ++first) { - if (*first == old_value) { + for (; first != last; ++first) + if (*first == old_value) *first = new_value; - } - } } -.SH Second version - template + replace_if + template::value_type> void replace_if(ForwardIt first, ForwardIt last, - UnaryPredicate p, const T& new_value) + UnaryPred p, const T& new_value) { - for (; first != last; ++first) { - if(p(*first)) { + for (; first != last; ++first) + if (p(*first)) *first = new_value; - } - } } .SH Example - The following code at first replaces all occurrences of 8 with 88 in a vector of - integers. Then it replaces all values less than 5 with 55. - // Run this code #include #include - #include + #include #include - + #include + + void println(const auto& seq) + { + for (const auto& e : seq) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { std::array s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; - + + // Replace all occurrences of 8 with 88. std::replace(s.begin(), s.end(), 8, 88); - - for (int a : s) { - std::cout << a << " "; - } - std::cout << '\\n'; - + println(s); + + // Replace all values less than 5 with 55. std::replace_if(s.begin(), s.end(), std::bind(std::less(), std::placeholders::_1, 5), 55); - for (int a : s) { - std::cout << a << " "; - } - std::cout << '\\n'; + println(s); + + std::array, 2> nums{{{1, 3}, {1, 3}}}; + #ifdef __cpp_lib_algorithm_default_value_type + std::replace(nums.begin(), nums.end(), {1, 3}, {4, 2}); + #else + std::replace(nums.begin(), nums.end(), std::complex{1, 3}, + std::complex{4, 2}); + #endif + println(nums); } .SH Output: 5 7 4 2 88 6 1 9 0 3 - 5 7 55 55 99 6 55 9 55 55 + 5 7 55 55 88 6 55 9 55 55 + (4,2), (4,2) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be CopyAssignable (and + EqualityComparable required *first = + LWG 283 C++98 for replace), but the value type of new_value + ForwardIt is not to be valid instead + always T and T is not always writable to + ForwardIt .SH See also - replace_copy copies a range, replacing elements satisfying specific criteria with - replace_copy_if another value - \fI(function template)\fP + replace_copy copies a range, replacing elements satisfying specific criteria + replace_copy_if with another value + \fI(function template)\fP + ranges::replace replaces all values satisfying specific criteria with another + ranges::replace_if value + (C++20) (niebloid) + (C++20) diff --git a/man/std::replace_copy,std::replace_copy_if.3 b/man/std::replace_copy,std::replace_copy_if.3 index 3256dcd9f..3ec19124c 100644 --- a/man/std::replace_copy,std::replace_copy_if.3 +++ b/man/std::replace_copy,std::replace_copy_if.3 @@ -1,46 +1,113 @@ -.TH std::replace_copy,std::replace_copy_if 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::replace_copy,std::replace_copy_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::replace_copy,std::replace_copy_if \- std::replace_copy,std::replace_copy_if + .SH Synopsis Defined in header - template< class InputIt, class OutputIt, class T > - - OutputIt replace_copy( InputIt first, InputIt last, OutputIt d_first, \fB(1)\fP - - const T& old_value, const T& new_value ); - template< class InputIt, class OutputIt, class UnaryPredicate, class T > - - OutputIt replace_copy_if( InputIt first, InputIt last, OutputIt d_first, \fB(2)\fP - - UnaryPredicate p, const T& new_value ); - - Copies the all elements from the range [first, last) to another range beginning at - d_first replacing all elements satisfying specific criteria with new_value. The - first version replaces the elements that are equal to old_value, the second version - replaces elements for which predicate p returns true. The source and destination - ranges cannot overlap. + template< class InputIt, class OutputIt, + class T > + + OutputIt replace_copy( InputIt first, \fB(1)\fP (constexpr since + InputIt last, OutputIt d_first, C++20) + + const T& + old_value, const T& new_value ); + template< class ExecutionPolicy, + + class ForwardIt1, class + ForwardIt2, class T > + ForwardIt2 replace_copy + ( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + ForwardIt2 d_first, + + const T& old_value, const T& + new_value ); + template< class InputIt, class OutputIt, + class UnaryPred, class T > + (constexpr + OutputIt replace_copy_if since C++20) + ( InputIt first, InputIt last, (until C++26) + OutputIt d_first, + + UnaryPred p, const T& new_value ); + template< class InputIt, class OutputIt, + class UnaryPred, + + class T = typename + std::iterator_traits + (since C++26) + ::value_type > + constexpr OutputIt replace_copy_if + ( InputIt first, InputIt last, + OutputIt d_first, + + UnaryPred p, const T& new_value ); + template< class ExecutionPolicy, class + ForwardIt1, class ForwardIt2, \fB(3)\fP + + class UnaryPred, class T > (since + ForwardIt2 replace_copy_if C++17) + ( ExecutionPolicy&& policy, (until + ForwardIt1 first, ForwardIt1 last, C++26) + ForwardIt2 d_first, + + UnaryPred p, const T& new_value ); + template< class ExecutionPolicy, class + ForwardIt1, class ForwardIt2, \fB(4)\fP + + class UnaryPred, class T = + typename std::iterator_traits + (since + ::value_type > C++26) + ForwardIt2 replace_copy_if + ( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 last, + ForwardIt2 d_first, + + UnaryPred p, const T& new_value ); + + Copies the elements from the range [first, last) to another range beginning at + d_first, while replacing all elements satisfying specific criteria with new_value. + + 1) Replaces all elements that are equal to old_value (using operator==). + 3) Replaces all elements for which predicate p returns true. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the results of the expressions *first and new_value is not writable to + d_first, the program is ill-formed. + + If the source and destination ranges overlap, the behavior is undefined. .SH Parameters first, last - the range of elements to copy d_first - the beginning of the destination range old_value - the value of elements to replace + policy - the execution policy to use. See execution policy for details. unary predicate which returns true if the element value should be replaced. - The signature of the predicate function should be equivalent to the - following: - p - - bool pred(const Type &a); - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of InputIt, + regardless of value category, and must not modify v. Thus, a parameter + type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. new_value - the value to use as replacement .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value @@ -48,59 +115,126 @@ .SH Complexity - Exactly last - first applications of the predicate. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize N\\)N comparisons using operator==. + 3,4) Exactly \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + replace_copy template OutputIt replace_copy(InputIt first, InputIt last, OutputIt d_first, const T& old_value, const T& new_value) { - for (; first != last; ++first) { + for (; first != last; ++first) *d_first++ = (*first == old_value) ? new_value : *first; - } return d_first; } -.SH Second version - template + replace_copy_if + template::value_type> OutputIt replace_copy_if(InputIt first, InputIt last, OutputIt d_first, - UnaryPredicate p, const T& new_value) + UnaryPred p, const T& new_value) { - for (; first != last; ++first) { - *d_first++ = p( *first ) ? new_value : *first; - } + for (; first != last; ++first) + *d_first++ = p(*first) ? new_value : *first; return d_first; } +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (3,4) + .SH Example - The following copy prints a vector, replacing all values over 5 with 99 on the fly. - // Run this code #include - #include + #include #include - #include - #include - - int main() + #include + + void println(const auto& seq) { - std::vector v{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; - std::replace_copy_if(v.begin(), v.end(), - std::ostream_iterator(std::cout, " "), - [](int n){return n > 5;}, 99); + for (const auto& e : seq) + std::cout << e << ' '; std::cout << '\\n'; } + int main() + { + std::vector src{3, 1, 4, 1, 5, 9, 2, 6, 5}; + println(src); + std::vector dst(src.size()); + std::replace_copy_if(src.cbegin(), src.cend(), + dst.begin(), + [](short n){ return n > 5; }, 0); + println(dst); + + std::vector> src2{{1, 3}, {2, 4}, {3, 5}}, + dst2(src2.size()); + println(src2); + #ifdef __cpp_lib_algorithm_default_value_type + std::replace_copy_if(src2.cbegin(), src2.cend(), dst2.begin(), + [](std::complex z){ return std::abs(z) < 5; }, + {4, 2}); // Possible, since the T is deduced. + #else + std::replace_copy_if(src2.cbegin(), src2.cend(), dst2.begin(), + [](std::complex z){ return std::abs(z) < 5; }, + std::complex{4, 2}); + #endif + println(dst2); + } + .SH Output: - 5 99 4 2 99 99 1 99 0 3 + 3 1 4 1 5 9 2 6 5 + 3 1 4 1 5 0 2 0 5 + (1,3) (2,4) (3,5) + (4,2) (4,2) (3,5) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be CopyAssignable (and + LWG 283 C++98 EqualityComparable for removed the requirement + replace_copy), but the value type of + InputIt is not always T + replace_copy_if only required InputIt to corrected to + LWG 337 C++98 meet the requirements of LegacyInputIterator + LegacyIterator^[1] + + 1. ↑ The actual defect in the C++ standard is that the template parameter + InputIterator was misspecified as Iterator. This affects the type requirements + because the C++ standard states that for the function templates in the + algorithms library, the template type parameters whose name ends with Iterator + imply the type requirements of the corresponding iterator categories. .SH See also - remove removes elements satisfying specific criteria - remove_if \fI(function template)\fP + replace replaces all values satisfying specific criteria with + replace_if another value + \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + ranges::replace_copy copies a range, replacing elements satisfying specific + ranges::replace_copy_if criteria with another value + (C++20) (niebloid) + (C++20) diff --git a/man/std::resetiosflags.3 b/man/std::resetiosflags.3 index 71df02be8..44eb58cf3 100644 --- a/man/std::resetiosflags.3 +++ b/man/std::resetiosflags.3 @@ -1,7 +1,10 @@ -.TH std::resetiosflags 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::resetiosflags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::resetiosflags \- std::resetiosflags + .SH Synopsis Defined in header - /*unspecified*/ resetiosflags( std::ios_base::fmt_flags mask ); + /*unspecified*/ resetiosflags( std::ios_base::fmtflags mask ); When used in an expression out << resetiosflags(mask) or in >> resetiosflags(mask), clears all format flags of the stream out or in as specified by the mask. @@ -12,42 +15,69 @@ .SH Return value - Returns an object of unspecified type such that if str is the name of an output - stream of type std::basic_ostream or std::basic_istream, then the expression str << resetiosflags(mask) or str >> - resetiosflags(mask) behaves as if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << resetiosflags(mask) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, mask) + * if in is an object of type std::basic_istream, the expression in + >> resetiosflags(mask) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, mask) + + where the function f is defined as: - str.setf(std::ios_base::fmtflags\fB(0)\fP, mask); + void f(std::ios_base& str, std::ios_base::fmtflags mask) + { + // reset specified flags + str.setf(ios_base::fmtflags\fB(0)\fP, mask); + } .SH Example - + // Run this code - #include - #include #include + #include + #include + int main() { std::istringstream in("10 010 10 010 10 010"); int n1, n2; + in >> std::oct >> n1 >> n2; - std::cout << "Parsing \\"10 010\\" with std::oct gives: " << n1 << ' ' << n2 << '\\n'; + std::cout << "Parsing \\"10 010\\" with std::oct gives: " << n1 << ' ' << n2 << '\\n'; + in >> std::dec >> n1 >> n2; - std::cout << "Parsing \\"10 010\\" with std::dec gives: " << n1 << ' ' << n2 << '\\n'; + std::cout << "Parsing \\"10 010\\" with std::dec gives: " << n1 << ' ' << n2 << '\\n'; + in >> std::resetiosflags(std::ios_base::basefield) >> n1 >> n2; std::cout << "Parsing \\"10 010\\" with autodetect gives: " << n1 << ' ' << n2 << '\\n'; } .SH Output: - Parsing "10 010" with std::oct gives: 8 8 - Parsing "10 010" with std::dec gives: 10 10 + Parsing "10 010" with std::oct gives: 8 8 + Parsing "10 010" with std::dec gives: 10 10 Parsing "10 010" with autodetect gives: 10 8 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 183 C++98 resetiosflags could only be used with usable with any + streams of type std::ostream or std::istream character stream + .SH See also setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::result_of,std::invoke_result.3 b/man/std::result_of,std::invoke_result.3 new file mode 100644 index 000000000..d842fd022 --- /dev/null +++ b/man/std::result_of,std::invoke_result.3 @@ -0,0 +1,230 @@ +.TH std::result_of,std::invoke_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::result_of,std::invoke_result \- std::result_of,std::invoke_result + +.SH Synopsis + Defined in header + template< class > + + class result_of; // not defined \fI(since C++11)\fP + \fB(1)\fP (deprecated in C++17) + template< class F, class... ArgTypes > (removed in C++20) + + class result_of; + template< class F, class... ArgTypes > \fB(2)\fP \fI(since C++17)\fP + class invoke_result; + + Deduces the return type of an INVOKE expression at compile time. + + F must be a callable type, reference to function, or reference to \fI(since C++11)\fP + callable type. Invoking F with ArgTypes... must be a well-formed \fI(until C++14)\fP + expression. + F and all types in ArgTypes can be any complete type, array of unknown \fI(since C++14)\fP + bound, or (possibly cv-qualified) void. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + +.SH Member types + + Member type Definition + the return type of the Callable type F if invoked with the arguments + ArgTypes.... + type Only defined if F can be called with the arguments ArgTypes... in + unevaluated context. + \fI(since C++14)\fP + +.SH Helper types + + template< class T > \fI(since C++14)\fP + using result_of_t = typename result_of::type; \fB(1)\fP (deprecated in C++17) + (removed in C++20) + template< class F, class... ArgTypes > + using invoke_result_t = typename invoke_result::type; + +.SH Possible implementation + + namespace detail + { + template + struct is_reference_wrapper : std::false_type {}; + template + struct is_reference_wrapper> : std::true_type {}; + + template + struct invoke_impl + { + template + static auto call(F&& f, Args&&... args) + -> decltype(std::forward(f)(std::forward(args)...)); + }; + + template + struct invoke_impl + { + template::type, + class = typename std::enable_if::value>::type> + static auto get(T&& t) -> T&&; + + template::type, + class = typename std::enable_if::value>::type> + static auto get(T&& t) -> decltype(t.get()); + + template::type, + class = typename std::enable_if::value>::type, + class = typename std::enable_if::value>::type> + static auto get(T&& t) -> decltype(*std::forward(t)); + + template::value>::type> + static auto call(MT1 B::*pmf, T&& t, Args&&... args) + -> decltype((invoke_impl::get( + std::forward(t)).*pmf)(std::forward(args)...)); + + template + static auto call(MT B::*pmd, T&& t) + -> decltype(invoke_impl::get(std::forward(t)).*pmd); + }; + + template::type> + auto INVOKE(F&& f, Args&&... args) + -> decltype(invoke_impl::call(std::forward(f), + std::forward(args)...)); + } // namespace detail + + // Minimal C++11 implementation: + template struct result_of; + template + struct result_of + { + using type = decltype(detail::INVOKE(std::declval(), std::declval()...)); + }; + + // Conforming C++14 implementation (is also a valid C++11 implementation): + namespace detail + { + template + struct invoke_result {}; + template + struct invoke_result< + decltype(void(detail::INVOKE(std::declval(), std::declval()...))), + F, Args...> + { + using type = decltype(detail::INVOKE(std::declval(), std::declval()...)); + }; + } // namespace detail + + template struct result_of; + template + struct result_of : detail::invoke_result {}; + + template + struct invoke_result : detail::invoke_result {}; + +.SH Notes + + As formulated in C++11, the behavior of std::result_of is undefined when + INVOKE(std::declval(), std::declval()...) is ill-formed (e.g. when F is + not a callable type at all). C++14 changes that to a SFINAE (when F is not callable, + std::result_of simply doesn't have the type member). + + The motivation behind std::result_of is to determine the result of invoking a + Callable, in particular if that result type is different for different sets of + arguments. + + F(Args...) is a function type with Args... being the argument types and F being the + return type. As such, std::result_of suffers from several quirks that led to its + deprecation in favor of std::invoke_result in C++17: + + * F cannot be a function type or an array type (but can be a reference to them); + * if any of the Args has type "array of T" or a function type T, it is + automatically adjusted to T*; + * neither F nor any of Args... can be an abstract class type; + * if any of Args... has a top-level cv-qualifier, it is discarded; + * none of Args... may be of type void. + + To avoid these quirks, result_of is often used with reference types as F and + Args.... For example: + + template + std::result_of_t // instead of std::result_of_t, which is wrong + my_invoke(F&& f, Args&&... args) + { + /* implementation */ + } + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_result_of_sfinae 201210L \fI(C++14)\fP std::result_of and SFINAE + __cpp_lib_is_invocable 201703L \fI(C++17)\fP std::is_invocable, std::invoke_result + +.SH Examples + + +// Run this code + + #include + #include + + struct S + { + double operator()(char, int&); + float operator()(int) { return 1.0; } + }; + + template + typename std::result_of::type f(T& t) + { + std::cout << "overload of f for callable T\\n"; + return t(0); + } + + template + int f(U u) + { + std::cout << "overload of f for non-callable T\\n"; + return u; + } + + int main() + { + // the result of invoking S with char and int& arguments is double + std::result_of::type d = 3.14; // d has type double + static_assert(std::is_same::value, ""); + + // std::invoke_result uses different syntax (no parentheses) + std::invoke_result::type b = 3.14; + static_assert(std::is_same::value, ""); + + // the result of invoking S with int argument is float + std::result_of::type x = 3.14; // x has type float + static_assert(std::is_same::value, ""); + + // result_of can be used with a pointer to member function as follows + struct C { double Func(char, int&); }; + std::result_of::type g = 3.14; + static_assert(std::is_same::value, ""); + + f(1); // may fail to compile in C++11; calls the non-callable overload in C++14 + } + +.SH Output: + + overload of f for non-callable T + +.SH See also + + invoke invokes any Callable object with given arguments + invoke_r and possibility to specify return type + \fI(C++17)\fP (since C++23) + (C++23) \fI(function template)\fP + is_invocable + is_invocable_r checks if a type can be invoked (as if by std::invoke) with + is_nothrow_invocable the given argument types + is_nothrow_invocable_r \fI(class template)\fP + \fI(C++17)\fP + declval obtains a reference to its argument for use in unevaluated + \fI(C++11)\fP context + \fI(function template)\fP diff --git a/man/std::result_of.3 b/man/std::result_of.3 deleted file mode 100644 index 593e5bf55..000000000 --- a/man/std::result_of.3 +++ /dev/null @@ -1,120 +0,0 @@ -.TH std::result_of 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class > \fB(1)\fP \fI(since C++11)\fP - class result_of; //not defined - template< class F, class... ArgTypes > \fB(2)\fP \fI(since C++11)\fP - class result_of; - - Deduces the return type of a function call expression at compile time. - - F must be a callable type, reference to function, or reference to - callable type. Invoking F with ArgTypes... must be a well-formed \fI(since C++11)\fP - expression - F and all types in ArgTypes can be any complete type, array of unknown \fI(since C++14)\fP - bound, or (cv-qualified) void - -.SH Member types - - Member type Definition - the return type of the Callable type F if invoked with the arguments - ArgTypes.... - type Only defined if F can be called with the arguments ArgTypes... in - unevaluated context. - \fI(since C++14)\fP - -.SH Helper types - - template< class T > \fI(since C++14)\fP - using result_of_t = typename result_of::type; - -.SH Possible implementation - - template - struct result_of; - - // C++11 implementation, does not satisfy C++14 requirements - template - struct result_of - { - typedef decltype( - std::declval()(std::declval()...) - ) type; - }; - -.SH Notes - - As formulated in C++11, std::result_of would fail to compile when F(ArgTypes...) is - ill-formed (e.g. when F is not a callable type at all). C++14 changes that to a - SFINAE (when F is not callable, std::result_of simply doesn't have the - type member). - -.SH Examples - - std::result_of can be used to determine the result of invoking a functor, in - particular if the result type is different for different sets of arguments: - - -// Run this code - - #include - - struct S { - double operator()(char, int&); - float operator()(int); - }; - - struct C { - double Func(char, int&); - }; - - int main() - { - // the result of invoking S with char and int& arguments is double - std::result_of::type f = 3.14; // f has type double - static_assert(std::is_same::value, ""); - - // the result of invoking S with int argument is float - std::result_of::type d = 3.14; // f has type float - static_assert(std::is_same::value, ""); - - // result_of can be used with a pointer to member function as follows - std::result_of::type g = 3.14; - static_assert(std::is_same::value, ""); - } - - demonstrates the C++14 changes to result_of requirements - - -// Run this code - - #include - #include - - template - typename std::result_of::type - f(T& t) - { - std::cout << "overload of f for callable T\\n"; - return t(0); - } - - template - int f(U u) - { - std::cout << "overload of f for non-callable T\\n"; - return u; - } - - struct S {}; - - int main() { - f(1); // fails to compile in C++11, calls the non-callable overload in C++14 - } - output= - overload of f for non-callable T - -.SH See also - - declval obtains the type of expression in unevaluated context - \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::rethrow_exception.3 b/man/std::rethrow_exception.3 index f3a670a08..226a518f1 100644 --- a/man/std::rethrow_exception.3 +++ b/man/std::rethrow_exception.3 @@ -1,10 +1,18 @@ -.TH std::rethrow_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rethrow_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rethrow_exception \- std::rethrow_exception + .SH Synopsis Defined in header - [[noreturn]] void rethrow_exception( std::exception_ptr p ) \fI(since C++11)\fP + [[noreturn]] void rethrow_exception( std::exception_ptr p ); \fI(since C++11)\fP + + Throws the previously captured exception object referred-to by the exception pointer + p, or a copy of that object. + + It is unspecified whether a copy is made. If a copy is made, the storage for it is + allocated in an unspecified way. - Throws the previously captured exception object, referred to by the exception - pointer p. + The behavior is undefined if p is null. .SH Parameters @@ -14,46 +22,70 @@ \fI(none)\fP +.SH Exceptions + + The exception object referred-to by p if no copy is made. + + Otherwise, a copy of such exception object if the implementation successfully copied + the exception object. + + Otherwise, std::bad_alloc or the exception thrown when copying the exception object, + if allocation or copying fails, respectively. + +.SH Notes + + Before P1675R2, rethrow_exception was not allowed to copy the exception object, + which is unimplementable on some platforms where exception objects are allocated on + the stack. + .SH Example - - + + // Run this code - #include - #include #include + #include #include - + #include + void handle_eptr(std::exception_ptr eptr) // passing by value is ok { - try { - if (eptr != std::exception_ptr()) { + try + { + if (eptr) std::rethrow_exception(eptr); - } - } catch(const std::exception& e) { - std::cout << "Caught exception \\"" << e.what() << "\\"\\n"; + } + catch(const std::exception& e) + { + std::cout << "Caught exception: '" << e.what() << "'\\n"; } } - + int main() { std::exception_ptr eptr; - try { - std::string().at(1); // this generates an std::out_of_range - } catch(...) { + + try + { + std::string().at(1); // this generates a std::out_of_range + } + catch(...) + { eptr = std::current_exception(); // capture } + handle_eptr(eptr); + } // destructor for std::out_of_range called here, when the eptr is destructed -.SH Output: +.SH Possible output: - Caught exception "basic_string::at" + Caught exception: 'basic_string::at: __n (which is 1) >= this->size() (which is 0)' .SH See also exception_ptr shared pointer type for handling exception objects - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP current_exception captures the current exception in a std::exception_ptr - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::rethrow_if_nested.3 b/man/std::rethrow_if_nested.3 index 439001d40..742e54be1 100644 --- a/man/std::rethrow_if_nested.3 +++ b/man/std::rethrow_if_nested.3 @@ -1,12 +1,19 @@ -.TH std::rethrow_if_nested 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rethrow_if_nested 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rethrow_if_nested \- std::rethrow_if_nested + .SH Synopsis Defined in header template< class E > \fI(since C++11)\fP void rethrow_if_nested( const E& e ); - If E is a type that is unambiguously derived from std::nested_exception, extracts - and throws the nested exception as if by calling dynamic_cast(e).rethrow_nested(). Otherwise, does nothing. + If E is not a polymorphic class type, or if std::nested_exception is an inaccessible + or ambiguous base class of E, there is no effect. + + Otherwise, performs + + if (auto p = dynamic_cast(std::addressof(e))) + p->rethrow_nested(); .SH Parameters @@ -16,65 +23,112 @@ \fI(none)\fP +.SH Notes + + Unlike many related functions, this function is not intended to be called with a + std::exception_ptr but rather an actual exception reference. + +.SH Possible implementation + + namespace details + { + template + struct can_dynamic_cast + : std::integral_constant::value && + (!std::is_base_of::value || + std::is_convertible::value) + > {}; + + template + void rethrow_if_nested_impl(const T& e, std::true_type) + { + if (auto nep = dynamic_cast(std::addressof(e))) + nep->rethrow_nested(); + } + + template + void rethrow_if_nested_impl(const T&, std::false_type) {} + } + + template + void rethrow_if_nested(const T& t) + { + details::rethrow_if_nested_impl(t, details::can_dynamic_cast()); + } + .SH Example - - Demonstrates construction and recursion through a nested exception object - + Demonstrates construction and recursion through a nested exception object. + + // Run this code + #include + #include #include #include - #include #include - #include - + // prints the explanatory string of an exception. If the exception is nested, // recurses to print the explanatory of the exception it holds void print_exception(const std::exception& e, int level = 0) { std::cerr << std::string(level, ' ') << "exception: " << e.what() << '\\n'; - try { + try + { std::rethrow_if_nested(e); - } catch(const std::exception& e) { - print_exception(e, level+1); - } catch(...) {} + } + catch (const std::exception& nestedException) + { + print_exception(nestedException, level + 1); + } + catch (...) {} } - + // sample function that catches an exception and wraps it in a nested exception void open_file(const std::string& s) { - try { + try + { std::ifstream file(s); file.exceptions(std::ios_base::failbit); - } catch(...) { - std::throw_with_nested( std::runtime_error("Couldn't open " + s) ); + } + catch (...) + { + std::throw_with_nested(std::runtime_error("Couldn't open " + s)); } } - + // sample function that catches an exception and wraps it in a nested exception void run() { - try { + try + { open_file("nonexistent.file"); - } catch(...) { - std::throw_with_nested( std::runtime_error("run() failed") ); + } + catch (...) + { + std::throw_with_nested(std::runtime_error("run() failed")); } } - + // runs the sample function above and prints the caught exception int main() { - try { + try + { run(); - } catch(const std::exception& e) { + } + catch (const std::exception& e) + { print_exception(e); } } -.SH Output: +.SH Possible output: exception: run() failed exception: Couldn't open nonexistent.file @@ -83,6 +137,6 @@ .SH See also nested_exception a mixin type to capture and store current exceptions - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP throw_with_nested throws its argument with std::nested_exception mixed in - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::return_temporary_buffer.3 b/man/std::return_temporary_buffer.3 index 77c70152f..06976ac55 100644 --- a/man/std::return_temporary_buffer.3 +++ b/man/std::return_temporary_buffer.3 @@ -1,43 +1,71 @@ -.TH std::return_temporary_buffer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::return_temporary_buffer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::return_temporary_buffer \- std::return_temporary_buffer + .SH Synopsis Defined in header - template< class T > - void return_temporary_buffer( T* p ) + template< class T > (deprecated in C++17) + void return_temporary_buffer( T* p ); (removed in C++20) + + Deallocates the storage referenced by p. - Deallocates storage previously allocated with std::get_temporary_buffer. + If p is not a pointer value returned by an earlier call to + std::get_temporary_buffer, or has been invalidated by an intervening + std::return_temporary_buffer call, the behavior is undefined. .SH Parameters - p - the pointer previously returned by std::get_temporary_buffer + p - the pointer referring to the storage to be declloated .SH Return value \fI(none)\fP +.SH Exceptions + + Throws nothing. + .SH Example - - + + // Run this code #include #include + #include #include #include - + int main() { const std::string s[] = {"string", "1", "test", "..."}; - std::string* p = std::get_temporary_buffer(4).first; - - std::copy(std::begin(s), std::end(s), - std::raw_storage_iterator(p)); - - for (std::string* i = p; i != p+4; ++i) { - std::cout << *i << '\\n'; - i->~basic_string(); - } - std::return_temporary_buffer(p); + const auto p = std::get_temporary_buffer(4); + // requires that p.first is passed to return_temporary_buffer + // (beware of early exit points and exceptions), or better use: + std::unique_ptr on_exit(p.first, + [](std::string* p) + { + std::cout << "returning temporary buffer...\\n"; + std::return_temporary_buffer(p); + }); + + std::copy(s, s + p.second, + std::raw_storage_iterator(p.first)); + // has same effect as: std::uninitialized_copy(s, s + p.second, p.first); + // requires that each string in p is individually destroyed + // (beware of early exit points and exceptions) + + std::copy(p.first, p.first + p.second, + std::ostream_iterator{std::cout, "\\n"}); + + std::for_each(p.first, p.first + p.second, [](std::string& e) + { + e.~basic_string(); + }); // same as: std::destroy(p.first, p.first + p.second); + + // manually reclaim memory if unique_ptr-like technique is not used: + // std::return_temporary_buffer(p.first); } .SH Output: @@ -46,8 +74,20 @@ 1 test ... + returning temporary buffer... + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the storage allocated by the behavior is + LWG 2072 C++98 std::get_temporary_buffer undefined in this + could be deallocated multiple times case .SH See also - get_temporary_buffer obtains uninitialized storage - \fI(function template)\fP + get_temporary_buffer obtains uninitialized storage + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) diff --git a/man/std::reverse.3 b/man/std::reverse.3 index 1024d1d21..ba412ff41 100644 --- a/man/std::reverse.3 +++ b/man/std::reverse.3 @@ -1,67 +1,132 @@ -.TH std::reverse 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse \- std::reverse + .SH Synopsis Defined in header - template< class BidirIt > + template< class BidirIt > \fB(1)\fP (constexpr since C++20) void reverse( BidirIt first, BidirIt last ); - - Reverses the order of the elements in the range [first, last) - - Behaves as if applying std::iter_swap to every pair of iterators first+i, (last-i) - - 1 for each non-negative i < (last-first)/2 + template< class ExecutionPolicy, class BidirIt > + void reverse( ExecutionPolicy&& policy, BidirIt first, \fB(2)\fP \fI(since C++17)\fP + BidirIt last ); + + 1) Reverses the order of the elements in the range [first, last). + Behaves as if applying std::iter_swap to every pair of iterators first + i and (last + - i) - 1 for each integer i in [0, std::distance(first, last) / 2). + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If + *first is not Swappable + \fI(until C++20)\fP + BidirIt is not ValueSwappable + \fI(since C++20)\fP, the behavior is undefined. .SH Parameters - first, last - the range of elements to reverse + first, last - the range of elements to reverse + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. - - - The type of dereferenced BidirIt must meet the requirements of Swappable. + BidirIt must meet the requirements of LegacyBidirectionalIterator. + +.SH Complexity + + Exactly std::distance(first, last) / 2 swaps. -.SH Return value +.SH Exceptions - \fI(none)\fP + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation + See also the implementations in libstdc++, libc++, and MSVC STL. + template + constexpr // since C++20 void reverse(BidirIt first, BidirIt last) { - while ((first != last) && (first != --last)) { - std::swap(*first++, *last); + using iter_cat = typename std::iterator_traits::iterator_category; + + // Tag dispatch, e.g. calling reverse_impl(first, last, iter_cat()), + // can be used in C++14 and earlier modes. + if constexpr (std::is_base_of_v) + { + if (first == last) + return; + + for (--last; first < last; (void)++first, --last) + std::iter_swap(first, last); } + else + while (first != last && first != --last) + std::iter_swap(first++, last); } +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + satisfies LegacyContiguousIterator and swapping its value type calls neither + non-trivial special member function nor ADL-found swap. + .SH Example - + // Run this code - #include - #include #include - + #include + #include + #include + + void println(auto rem, auto const& v) + { + for (std::cout << rem; auto e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + int main() { - std::vector v({1,2,3}); - std::reverse(std::begin(v), std::end(v)); - std::cout << v[0] << v[1] << v[2] << '\\n'; - + std::vector v {1, 2, 3}; + std::reverse(v.begin(), v.end()); + println("after reverse, v = ", v); + int a[] = {4, 5, 6, 7}; - std::reverse(&a[0], &a[4]); - std::cout << a[0] << a[1] << a[2] << a[3] << '\\n'; + std::reverse(std::begin(a), std::end(a)); + println("after reverse, a = ", a); } .SH Output: - 321 - 7654 + after reverse, v = 3 2 1 + after reverse, a = 7 6 5 4 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - linear in the distance between first and last + DR Applied to Behavior as published Correct behavior + LWG 223 C++98 std::swap was applied to each pair of applies std::iter_swap + iterators instead + LWG 2039 C++98 std::iter_swap was also applied when i not applied + equals std::distance(first, last) / 2 .SH See also - reverse_copy creates a copy of a range that is reversed - \fI(function template)\fP + reverse_copy creates a copy of a range that is reversed + \fI(function template)\fP + ranges::reverse reverses the order of elements in a range + (C++20) (niebloid) diff --git a/man/std::reverse_copy.3 b/man/std::reverse_copy.3 index 1fed8b224..ca33ff99a 100644 --- a/man/std::reverse_copy.3 +++ b/man/std::reverse_copy.3 @@ -1,78 +1,140 @@ -.TH std::reverse_copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_copy \- std::reverse_copy + .SH Synopsis Defined in header template< class BidirIt, class OutputIt > - OutputIt reverse_copy( BidirIt first, BidirIt last, OutputIt d_first ); - Copies the elements from the range [first, last) to another range beginning at - d_first in such a way that the elements in the new range are in reverse order. + OutputIt reverse_copy( BidirIt first, BidirIt last, \fB(1)\fP (constexpr since C++20) + + OutputIt d_first ); + template< class ExecutionPolicy, class BidirIt, class + ForwardIt > + + ForwardIt reverse_copy( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + BidirIt first, BidirIt last, - Behaves as if by executing the assignment *(d_first + (last - first) - 1 - i) = - *(first + i) once for each non-negative i < (last - first) + ForwardIt d_first ); - If the source and destination ranges (that is, [first, last) and [d_first, - d_first+(last-first)) respectively) overlap, the behavior is undefined. + 1) Given \\(\\scriptsize N\\)N as std::distance(first, last). Copies the elements from + the range [first, last) (source range) to another range of \\(\\scriptsize N\\)N + elements beginning at d_first (destination range) in such a way that the elements in + the destination range are in reverse order. + Behaves as if by executing the assignment *(d_first + N - 1 - i) = *(first + i)^[1] + once for each integer i in [0, N). + If source and destination ranges overlap, the behavior is undefined. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first, last - the range of elements to copy - d_first - the beginning of the destination range + first, last - the range of elements to copy + d_first - the beginning of the destination range .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. - - OutputIt must meet the requirements of OutputIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value Output iterator to the element past the last element copied. +.SH Complexity + + Exactly \\(\\scriptsize N\\)N assignments. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + .SH Possible implementation + See also the implementations in libstdc++, libc++, and MSVC STL. + template + constexpr // since C++20 OutputIt reverse_copy(BidirIt first, BidirIt last, OutputIt d_first) { - while (first != last) { - *(d_first++) = *(--last); - } + for (; first != last; ++d_first) + *d_first = *(--last); return d_first; } +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the both iterator + types satisfy LegacyContiguousIterator and have the same value type, and the value + type is TriviallyCopyable. + .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { - std::vector v({1,2,3}); - for (const auto& value : v) { - std::cout << value << " "; - } - std::cout << '\\n'; - - std::vector destiny(3); - std::reverse_copy(std::begin(v), std::end(v), std::begin(destiny)); - for (const auto& value : destiny) { - std::cout << value << " "; - } - std::cout << '\\n'; + auto print = [](const std::vector& v) + { + for (const auto& value : v) + std::cout << value << ' '; + std::cout << '\\n'; + }; + + std::vector v{1, 2, 3}; + print(v); + + std::vector destination(3); + std::reverse_copy(std::begin(v), std::end(v), std::begin(destination)); + print(destination); + + std::reverse_copy(std::rbegin(v), std::rend(v), std::begin(destination)); + print(destination); } .SH Output: 1 2 3 3 2 1 + 1 2 3 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + for each i, the assignment was corrected to + LWG 2074 C++98 *(d_first + N - i) = *(first + i)^[1] *(d_first + N - 1 - i) = + *(first + i)^[1] + LWG 2150 C++98 only one element was required to be corrected the requirement + assigned - Linear in the distance between first and last + 1. ↑ ^1.0 ^1.1 ^1.2 LegacyOutputIterator is not required to support binary + and -. + The usages of + and - here are exposition-only: the actual computation does not + need to use them. .SH See also - reverse reverses the order elements in a range - \fI(function template)\fP + reverse reverses the order of elements in a range + \fI(function template)\fP + ranges::reverse_copy creates a copy of a range that is reversed + (C++20) (niebloid) diff --git a/man/std::reverse_iterator.3 b/man/std::reverse_iterator.3 index 7ac7a4716..4aa38b396 100644 --- a/man/std::reverse_iterator.3 +++ b/man/std::reverse_iterator.3 @@ -1,26 +1,23 @@ -.TH std::reverse_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator \- std::reverse_iterator + .SH Synopsis Defined in header - template< class Iterator > - - class reverse_iterator : public std::iterator< - typename - std::iterator_traits::iterator_category, - typename std::iterator_traits::value_type, - typename - std::iterator_traits::difference_type, - typename std::iterator_traits::pointer, - - typename std::iterator_traits::reference > + template< class Iter > + class reverse_iterator; std::reverse_iterator is an iterator adaptor that reverses the direction of a given - iterator. In other words, when provided with a bidirectional iterator, + iterator, which must be at least a LegacyBidirectionalIterator + or model bidirectional_iterator + \fI(since C++20)\fP. In other words, when provided with a bidirectional iterator, std::reverse_iterator produces a new iterator that moves from the end to the beginning of the sequence defined by the underlying bidirectional iterator. For a reverse iterator r constructed from an iterator i, the relationship &*r == - &*(i-1) is always true; thus a reverse iterator constructed from a one-past-the-end - iterator dereferences to the last element in a sequence. + &*(i - 1) is always true (as long as r is dereferenceable); thus a reverse iterator + constructed from a one-past-the-end iterator dereferences to the last element in a + sequence. This is the iterator returned by member functions rbegin() and rend() of the standard library containers. @@ -29,29 +26,54 @@ .SH Member types - Member type Definition - iterator_type Iterator - difference_type std::iterator_traits::difference_type - pointer std::iterator_traits::pointer - reference std::iterator_traits::reference + Member type Definition + iterator_type Iter + iterator_category std::iterator_traits::iterator_category (until + value_type std::iterator_traits::value_type C++20) + difference_type std::iterator_traits::difference_type + pointer std::iterator_traits::pointer + reference std::iterator_traits::reference + Member type Definition + iterator_type Iter + If Iter models std::random_access_iterator, this is + iterator_concept std::random_access_iterator_tag. Otherwise, this is + std::bidirectional_iterator_tag + If std::iterator_traits::iterator_category models (since + iterator_category std::derived_from, this is C++20) + std::random_access_iterator_tag. Otherwise, this is + std::iterator_traits::iterator_category + value_type std::iter_value_t + difference_type std::iter_difference_t + pointer std::iterator_traits::pointer + reference std::iter_reference_t + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from + std::iterator< + std::iterator_traits::iterator_category, + std::iterator_traits::value_type, \fI(until C++17)\fP + std::iterator_traits::difference_type, + std::iterator_traits::pointer, + std::iterator_traits::reference + >. .SH Member functions constructor constructs a new iterator adaptor - \fI(public member function)\fP - operator= assigns another iterator - \fI(public member function)\fP + \fI(public member function)\fP + operator= assigns another iterator adaptor + \fI(public member function)\fP base accesses the underlying iterator - \fI(public member function)\fP + \fI(public member function)\fP operator* accesses the pointed-to element - operator-> \fI(public member function)\fP - operator[] obtains rvalue reference to indexed element - \fI(public member function)\fP + operator-> \fI(public member function)\fP + operator[] accesses an element by index + \fI(public member function)\fP operator++ operator++(int) operator+= operator+ advances or decrements the iterator - operator-- \fI(public member function)\fP + operator-- \fI(public member function)\fP operator--(int) operator-= operator- @@ -59,56 +81,136 @@ .SH Member objects Member name Definition - current (protected) a copy of the base() iterator + current (protected) the underlying iterator of which base() returns a copy .SH Non-member functions operator== operator!= - operator< compares the underlying iterators - operator<= \fI(function template)\fP - operator> + operator< + operator<= compares the underlying iterators + operator> \fI(function template)\fP operator>= - operator+ advances the iterator - \fI(function template)\fP - operator- computes the distance between two iterator adaptors - \fI(function template)\fP - -Inherited from std::iterator - -.SH Member types - - Member type Definition - value_type std::iterator_traits::value_type - difference_type std::iterator_traits::difference_type - pointer std::iterator_traits::pointer - reference std::iterator_traits::reference - iterator_category std::iterator_traits::iterator_category + operator<=> + (C++20) + operator+ advances the iterator + \fI(function template)\fP + operator- computes the distance between two iterator adaptors + \fI(function template)\fP + iter_move casts the result of dereferencing the adjusted underlying + (C++20) iterator to its associated rvalue reference type + \fI(function)\fP + iter_swap swaps the objects pointed to by two adjusted underlying + (C++20) iterators + \fI(function template)\fP + make_reverse_iterator creates a std::reverse_iterator of type inferred from the + \fI(C++14)\fP argument + \fI(function template)\fP + + Helper templates + + template< class Iterator1, class Iterator2 > + + requires (!std::sized_sentinel_for) + inline constexpr bool disable_sized_sentinel_for< \fI(since C++20)\fP + std::reverse_iterator, + + std::reverse_iterator> = true; + + This partial specialization of std::disable_sized_sentinel_for prevents + specializations of reverse_iterator from satisfying sized_sentinel_for if their + underlying iterators do not satisfy the concept. + +.SH Possible implementation + + Below is a partial implementation focusing on the way the inner iterator is stored, + calling std::prev only when the content is fetched via operator*. + +template +class reverse_iterator +{ +protected: + It current = It(); +public: + reverse_iterator() = default; + constexpr explicit reverse_iterator(It itr) : current(itr) {} + template + requires (!std::is_same_v && std::convertible_to) + constexpr explicit reverse_iterator(const U& other) : current(other.base()) {} + + constexpr decltype(auto) operator*() const + { + return *std::prev(current); // <== returns the content of prev + } + + constexpr reverse_iterator& operator++() { --current; return *this; } + constexpr reverse_iterator operator++(int) { auto tmp = *this; ++(*this); return tmp; } + + constexpr reverse_iterator& operator--() { ++current; return *this; } + constexpr reverse_iterator operator--(int) { auto tmp = *this; --(*this); return tmp; } + + constexpr It base() const { return current; } + + // Other member functions, friend functions, and member typedefs are not shown here. +}; + +.SH Notes + + std::reverse_iterator does not work with iterators whose dereference returns a + reference to a member of *this (so-called "stashing iterators"). An example of a + stashing iterator is MSVC STL's std::filesystem::path::iterator. .SH Example - + // Run this code + #include #include - #include #include - + + template + class Stack + { + T arr[SIZE]; + std::size_t pos = 0; + public: + T pop() + { + return arr[--pos]; + } + + Stack& push(const T& t) + { + arr[pos++] = t; + return *this; + } + + // we wish that looping on Stack would be in LIFO order + // thus we use std::reverse_iterator as an adaptor to existing iterators + // (which are in this case the simple pointers: [arr, arr + pos) + auto begin() { return std::reverse_iterator(arr + pos); } + auto end() { return std::reverse_iterator(arr); } + }; + int main() { - std::string s = "Hello, world"; - std::reverse_iterator r = s.rbegin(); - r[7] = 'O'; // replaces 'o' with 'O' - r += 7; // iterator now points at 'O' - std::string rev(r, s.rend()); - std::cout << rev << '\\n'; + Stack s; + s.push(5).push(15).push(25).push(35); + for (int val : s) + std::cout << val << ' '; + std::cout << '\\n'; } .SH Output: - OlleH + 35 25 15 5 .SH See also - iterator the basic iterator - \fI(class template)\fP + make_reverse_iterator creates a std::reverse_iterator of type inferred from the + \fI(C++14)\fP argument + \fI(function template)\fP + iterator base class to ease the definition of required types for simple + (deprecated in C++17) iterators + \fI(class template)\fP diff --git a/man/std::reverse_iterator::base.3 b/man/std::reverse_iterator::base.3 index 683475868..62a097adb 100644 --- a/man/std::reverse_iterator::base.3 +++ b/man/std::reverse_iterator::base.3 @@ -1,12 +1,17 @@ -.TH std::reverse_iterator::base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator::base \- std::reverse_iterator::base + .SH Synopsis - Iterator base() const; + iterator_type base() const; \fI(until C++17)\fP + constexpr iterator_type base() const; \fI(since C++17)\fP - Returns the underlying base iterator. + Returns the underlying base iterator. That is std::reverse_iterator(it).base() == + it. - The base iterator refers to the element that is next to the element the - reverse_iterator is currently pointing to. That is std::reverse_iterator(it).base() - == std::next(it). + The base iterator refers to the element that is next (from the + std::reverse_iterator::iterator_type perspective) to the element the + reverse_iterator is currently pointing to. That is &*(rit.base() - 1) == &*rit. .SH Parameters @@ -18,36 +23,53 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - + // Run this code #include #include #include - + int main() { - std::vector v = { 0, 1, 2, 3, 4, 5 }; - + std::vector v = {0, 1, 2, 3, 4, 5}; + using RevIt = std::reverse_iterator::iterator>; - RevIt r_end(v.begin()); - RevIt r_begin(v.end()); - - for (auto it = r_end.base(); it != r_begin.base(); ++it) { - std::cout << *it << " "; - } - std::cout << "\\n"; + + const auto it = v.begin() + 3; + RevIt r_it{it}; + + std::cout << "*it == " << *it << '\\n' + << "*r_it == " << *r_it << '\\n' + << "*r_it.base() == " << *r_it.base() << '\\n' + << "*(r_it.base()-1) == " << *(r_it.base() - 1) << '\\n'; + + RevIt r_end{v.begin()}; + RevIt r_begin{v.end()}; + + for (auto it = r_end.base(); it != r_begin.base(); ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + + for (auto it = r_begin; it != r_end; ++it) + std::cout << *it << ' '; + std::cout << '\\n'; } .SH Output: + *it == 3 + *r_it == 2 + *r_it.base() == 3 + *(r_it.base()-1) == 2 0 1 2 3 4 5 + 5 4 3 2 1 0 .SH See also operator* accesses the pointed-to element - operator-> \fI(public member function)\fP + operator-> \fI(public member function)\fP diff --git a/man/std::reverse_iterator::operator*,->.3 b/man/std::reverse_iterator::operator*,->.3 index 12cdb6992..9f0225025 100644 --- a/man/std::reverse_iterator::operator*,->.3 +++ b/man/std::reverse_iterator::operator*,->.3 @@ -1,12 +1,27 @@ -.TH std::reverse_iterator::operator*,-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator::operator*,-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator::operator*,-> \- std::reverse_iterator::operator*,-> + .SH Synopsis - reference operator*() const; \fB(1)\fP - pointer operator->() const; \fB(2)\fP + reference operator*() const; \fI(until C++17)\fP + constexpr reference operator*() const; \fI(since C++17)\fP + pointer operator->() const; \fI(until C++17)\fP + constexpr pointer operator->() const; \fI(since C++17)\fP + \fI(until C++20)\fP + constexpr pointer operator->() const \fB(1)\fP + \fB(2)\fP + requires (std::is_pointer_v || \fI(since C++20)\fP + + requires (const Iter i) { + i.operator->(); }); Returns a reference or pointer to the element previous to current. - 1) Equivalent to Iterator tmp = current; return *--tmp; - 2) Equivalent to &(operator*()). + 1) Equivalent to Iter tmp = current; return *--tmp;. + + 2) Equivalent to return std::addressof(operator*());. \fI(until C++20)\fP + 2) Equivalent to return current - 1; if Iter is a pointer type. \fI(since C++20)\fP + Otherwise, equivalent to return std::prev(current).operator->();. .SH Parameters @@ -16,22 +31,44 @@ Reference or pointer to the element previous to current. -.SH Notes +.SH Example - Prior to the introduction of multithreading in C++11, implementations of - reverse_iterator commonly stored a decremented copy of current as a member, see - defect 2360. -.SH Example +// Run this code - This section is incomplete - Reason: no example + #include + #include + #include + #include -.SH See also + int main() + { + using RI0 = std::reverse_iterator; + int a[]{0, 1, 2, 3}; + RI0 r0{std::rbegin(a)}; + std::cout << "*r0 = " << *r0 << '\\n'; + *r0 = 42; + std::cout << "a[3] = " << a[3] << '\\n'; + + using RI1 = std::reverse_iterator::iterator>; + std::vector vi{0, 1, 2, 3}; + RI1 r1{vi.rend() - 2}; + std::cout << "*r1 = " << *r1 << '\\n'; + + using RI2 = std::reverse_iterator>::iterator>; + std::vector> vc{{1,2}, {3,4}, {5,6}, {7,8}}; + RI2 r2{vc.rbegin() + 1}; + std::cout << "vc[2] = (" << r2->real() << ',' << r2->imag() << ")\\n"; + } - operator[] obtains rvalue reference to indexed element - \fI(public member function)\fP +.SH Output: -.SH Category: + *r0 = 3 + a[3] = 42 + *r1 = 1 + vc[2] = (5,6) + +.SH See also - * Todo no example + operator[] accesses an element by index + \fI(public member function)\fP diff --git a/man/std::reverse_iterator::operator++,+,+=,--,-,-=.3 b/man/std::reverse_iterator::operator++,+,+=,--,-,-=.3 index 669746816..22d5ff2fd 100644 --- a/man/std::reverse_iterator::operator++,+,+=,--,-,-=.3 +++ b/man/std::reverse_iterator::operator++,+,+=,--,-,-=.3 @@ -1,39 +1,125 @@ -.TH std::reverse_iterator::operator++,+,+=,--,-,-= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator::operator++,+,+=,--,-,-= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator::operator++,+,+=,--,-,-= \- std::reverse_iterator::operator++,+,+=,--,-,-= + .SH Synopsis - reverse_iterator& operator++(); \fB(1)\fP - reverse_iterator& operator--(); \fB(2)\fP - reverse_iterator operator++( int ); \fB(3)\fP - reverse_iterator operator--( int ); \fB(4)\fP - reverse_iterator operator+( difference_type n ) const; \fB(5)\fP - reverse_iterator operator-( difference_type n ) const; \fB(6)\fP - reverse_iterator& operator+=( difference_type n ) const; \fB(7)\fP - reverse_iterator& operator-=( difference_type n ) const; \fB(8)\fP + reverse_iterator& (until + operator++(); C++17) + constexpr (since + reverse_iterator& C++17) + operator++(); + reverse_iterator& (until + operator--(); C++17) + constexpr (since + reverse_iterator& C++17) + operator--(); + reverse_iterator (until + operator++( int ); C++17) + constexpr (since + reverse_iterator C++17) + operator++( int ); + reverse_iterator (until + operator--( int ); C++17) + constexpr (since + reverse_iterator C++17) + operator--( int ); + reverse_iterator + operator+( (until + difference_type n C++17) + ) const; + constexpr + reverse_iterator (since + operator+( C++17) + difference_type n \fB(1)\fP + ) const; + reverse_iterator + operator-( \fB(2)\fP (until + difference_type n C++17) + ) const; \fB(3)\fP + constexpr + reverse_iterator (since + operator-( \fB(4)\fP C++17) + difference_type n + ) const; \fB(5)\fP + reverse_iterator& + operator+=( (until + difference_type n C++17) + ); + constexpr \fB(6)\fP + reverse_iterator& (since + operator+=( C++17) + difference_type n + ); \fB(7)\fP + reverse_iterator& + operator-=( (until + difference_type n C++17) + ); + constexpr \fB(8)\fP + reverse_iterator& (since + operator-=( C++17) + difference_type n + ); Increments or decrements the iterator. Inverse operations are applied to the underlying operator because of the reverse order. - 1-2) Pre-increments or pre-decrements by one respectively. - 3-4) Post-increments or post-decrements by one respectively. - 5-6) Returns an iterator which is advanced by n or -n positions respectively. - 7-8) Advances the iterator by n or -n positions respectively. + 1,2) Pre-increments or pre-decrements by one respectively. + 3,4) Post-increments or post-decrements by one respectively. + 5,6) Returns an iterator which is advanced by n or -n positions respectively. + 7,8) Advances the iterator by n or -n positions respectively. + +.SH Parameters + + n - position relative to current location .SH Return value - 1) *this - 2) a copy of *this that was made before the change - 3) reverse_iterator(base()-n) or reverse_iterator(base()+n) respectively. - 4) *this + 1,2) *this + 3,4) A copy of *this that was made before the change. + 5,6) reverse_iterator(base()-n) or reverse_iterator(base()+n) respectively. + 7,8) *this .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - operator+ advances the iterator - \fI(function template)\fP + #include + #include + #include + #include + + int main() + { + std::vector v{0, 1, 2, 3, 4}; + auto rv = std::reverse_iterator{v.rbegin()}; + std::cout << *(++rv) << ' '; // 3 + std::cout << *(--rv) << ' '; // 4 + std::cout << *(rv + 3) << ' '; // 1 + rv += 3; + std::cout << rv[0] << ' '; // 1 + rv -= 3; + std::cout << rv[0] << '\\n'; // 4 -.SH Category: + std::list l{5, 6, 7, 8}; + auto rl = std::reverse_iterator{l.rbegin()}; + std::cout << *(++rl) << ' '; // OK: 3 + std::cout << *(--rl) << '\\n'; // OK: 4 + // The following statements raise compilation error because the + // underlying iterator does not model the random access iterator: + // *(rl + 3) = 13; + // rl += 3; + // rl -= 3; + } - * Todo no example +.SH Output: + + 3 4 1 1 4 + 7 8 + +.SH See also + + operator+ advances the iterator + \fI(function template)\fP + operator- computes the distance between two iterator adaptors + \fI(function template)\fP diff --git a/man/std::reverse_iterator::operator=.3 b/man/std::reverse_iterator::operator=.3 index 02425abf6..326354f68 100644 --- a/man/std::reverse_iterator::operator=.3 +++ b/man/std::reverse_iterator::operator=.3 @@ -1,10 +1,20 @@ -.TH std::reverse_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator::operator= \- std::reverse_iterator::operator= + .SH Synopsis - template< class U > + template< class U > \fI(until C++17)\fP reverse_iterator& operator=( const reverse_iterator& other ); + template< class U > + constexpr reverse_iterator& operator=( const reverse_iterator& \fI(since C++17)\fP + other ); + + The underlying iterator is assigned the value of the underlying iterator of other, + i.e. other.base(). - Copy assignment operator. The underlying iterator is assigned the value of the - underlying iterator of other, i.e. other.base(). + This overload participates in overload resolution only if U is not the + same type as Iter and std::convertible_to and \fI(since C++20)\fP + std::assignable_from are modeled. .SH Parameters @@ -16,14 +26,46 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - constructor constructs a new iterator adaptor - \fI(public member function)\fP + #include + #include + + int main() + { + const int a1[]{0, 1, 2}; + int a2[]{0, 1, 2, 3}; + short a3[]{40, 41, 42}; + + std::reverse_iterator it1{std::crbegin(a1)}; + it1 = std::reverse_iterator{std::rbegin(a2)}; // OK + // it1 = std::reverse_iterator{std::rbegin(a3)}; // compilation error: + // incompatible pointer types + std::reverse_iterator it2{nullptr}; + it2 = std::rbegin(a3); // OK + // it2 = std::begin(a3); // compilation error: no viable overloaded '=' + std::cout << *it2 << '\\n'; + } -.SH Category: +.SH Output: - * Todo no example + 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + a std::reverse_iterator could be constructed, + LWG 280 C++98 but not assigned, from also allowed + another std::reverse_iterator with a different assignment + underlying iterator type + LWG 3435 C++20 the converting assignment operator was not constrained + constrained + +.SH See also + + constructor constructs a new iterator adaptor + \fI(public member function)\fP diff --git a/man/std::reverse_iterator::operator[].3 b/man/std::reverse_iterator::operator[].3 index 2d189cbaa..3517f3d2b 100644 --- a/man/std::reverse_iterator::operator[].3 +++ b/man/std::reverse_iterator::operator[].3 @@ -1,27 +1,81 @@ -.TH std::reverse_iterator::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator::operator[] \- std::reverse_iterator::operator[] + .SH Synopsis - /*unspecified*/ operator[]( difference_type n ) const; + /* unspecified */ operator[]( difference_type n ) const; \fI(until C++17)\fP + constexpr /* unspecified */ operator[]( difference_type n ) const; \fI(since C++17)\fP Returns a reference to the element at specified relative location. .SH Parameters - n - position relative to current location. + n - position relative to current location .SH Return value - A reference to the element at relative location, that is, current[-n-1]. + A reference to the element at relative location, that is, base()[-n - 1]. -.SH Examples +.SH Notes - This section is incomplete - Reason: no example + The return type was changed by LWG386 to be unspecified because the return type of + the underlying iterator's operator[] was also unspecified at the time. However, as + of N3066, the return type of a LegacyRandomAccessIterator's operator[] is required + to be convertible to reference. In all common implementations, the return type of + reverse_iterator::operator[] is declared to be reference. See also LWG2595. -.SH See also +.SH Example - operator* accesses the pointed-to element - operator-> \fI(public member function)\fP -.SH Category: +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + int a[]{0, 1, 2, 3}; + std::reverse_iterator iter1{std::rbegin(a)}; + for (std::size_t i{}; i != std::size(a); ++i) + std::cout << iter1[i] << ' '; // decltype(iter1[i]) is `int&` + std::cout << '\\n'; + + std::vector v{0, 1, 2, 3}; + std::reverse_iterator::iterator> iter2{std::rbegin(v)}; + for (std::size_t i{}; i != std::size(v); ++i) + std::cout << iter2[i] << ' '; // decltype(iter2[i]) is `int&` + std::cout << '\\n'; + + // constexpr context + constexpr static std::array z{0, 1, 2, 3}; + constexpr std::reverse_iterator iter3{std::crbegin(z)}; + static_assert(iter3[1] == 2); + + std::list li{0, 1, 2, 3}; + std::reverse_iterator::iterator> iter4{std::rbegin(li)}; + *iter4 = 42; // OK + // iter4[0] = 13; // compilation error: the underlying iterator + // does not model the random access iterator + } - * Todo no example +.SH Output: + + 3 2 1 0 + 3 2 1 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 386 C++98 the return type was reference made unspecified + +.SH See also + + operator* accesses the pointed-to element + operator-> \fI(public member function)\fP diff --git a/man/std::reverse_iterator::reverse_iterator.3 b/man/std::reverse_iterator::reverse_iterator.3 index 7cd418371..7430f0d0a 100644 --- a/man/std::reverse_iterator::reverse_iterator.3 +++ b/man/std::reverse_iterator::reverse_iterator.3 @@ -1,16 +1,31 @@ -.TH std::reverse_iterator::reverse_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::reverse_iterator::reverse_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::reverse_iterator::reverse_iterator \- std::reverse_iterator::reverse_iterator + .SH Synopsis - reverse_iterator(); \fB(1)\fP - explicit reverse_iterator( Iterator x ); \fB(2)\fP - template< class U > \fB(3)\fP - reverse_iterator( const reverse_iterator& other ); + reverse_iterator(); \fI(until C++17)\fP + constexpr reverse_iterator(); \fI(since C++17)\fP + explicit reverse_iterator( iterator_type \fI(until C++17)\fP + x ); + constexpr explicit reverse_iterator( \fI(since C++17)\fP + iterator_type x ); \fB(1)\fP + template< class U > \fB(2)\fP (until + reverse_iterator( const C++17) + reverse_iterator& other ); \fB(3)\fP + template< class U > (since + constexpr reverse_iterator( const C++17) + reverse_iterator& other ); Constructs a new iterator adaptor. - 1) Default constructor. current is value-initialized. This makes sense only if - operations on an value-initialized Iterator make also sense. - 2) current is initialized with x. - 3) Copy constructor. The underlying iterator is initialized with that of other. + 1) Default constructor. The underlying iterator is value-initialized. Operations on + the resulting iterator have defined behavior if and only if the corresponding + operations on a value-initialized Iter also have defined behavior. + 2) The underlying iterator is initialized with x. + 3) The underlying iterator is initialized with that of other. + This overload participates in overload resolution only if U is not the same type as + Iter and std::convertible_to is modeled + \fI(since C++20)\fP. .SH Parameters @@ -22,11 +37,26 @@ This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 235 C++98 the effect of the default constructor specified + was not specified + LWG 1012 C++98 the underlying iterator was it is value-initialized + default-initialized + LWG 3435 C++20 the converting constructor from another constrained + reverse_iterator was not constrained + .SH See also - operator= assigns another iterator - \fI(public member function)\fP + operator= assigns another iterator adaptor + \fI(public member function)\fP + make_reverse_iterator creates a std::reverse_iterator of type inferred from the + \fI(C++14)\fP argument + \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::rewind.3 b/man/std::rewind.3 index 1c952712f..bd4834e42 100644 --- a/man/std::rewind.3 +++ b/man/std::rewind.3 @@ -1,4 +1,7 @@ -.TH std::rewind 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rewind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rewind \- std::rewind + .SH Synopsis Defined in header void rewind( std::FILE* stream ); @@ -20,36 +23,45 @@ .SH Example - + // Run this code + #include #include - + int main() { - std::FILE *f; - char ch; - char str[20]; - - f = std::fopen("file.txt", "w"); - for (ch = '0'; ch <= '9'; ch++) { + std::FILE* f = std::fopen("file.txt", "w"); + for (char ch = '0'; ch <= '9'; ch++) std::fputc(ch, f); - } - std::fclose(f); - - std::fopen("file.txt", "r"); - std::fread(str, 1, 10, f); - std::puts(str); - - std::rewind(f); - std::fread(str, 1, 10, f); - std::puts(str); std::fclose(f); + + std::array str; + std::FILE* f2 = std::fopen("file.txt", "r"); + + const unsigned size1 = std::fread(str.data(), 1, str.size(), f2); + std::puts(str.data()); + std::printf("size1 = %u\\n", size1); + + std::rewind(f2); + + const unsigned size2 = std::fread(str.data(), 1, str.size(), f2); + std::puts(str.data()); + std::printf("size2 = %u", size2); + + std::fclose(f2); } +.SH Output: + + 0123456789 + size1 = 10 + 0123456789 + size2 = 10 + .SH See also fseek moves the file position indicator to a specific location in a file - \fI(function)\fP + \fI(function)\fP C documentation for rewind diff --git a/man/std::riemann_zeta,std::riemann_zetaf,std::riemann_zetal.3 b/man/std::riemann_zeta,std::riemann_zetaf,std::riemann_zetal.3 new file mode 100644 index 000000000..645be2597 --- /dev/null +++ b/man/std::riemann_zeta,std::riemann_zetaf,std::riemann_zetal.3 @@ -0,0 +1,99 @@ +.TH std::riemann_zeta,std::riemann_zetaf,std::riemann_zetal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::riemann_zeta,std::riemann_zetaf,std::riemann_zetal \- std::riemann_zeta,std::riemann_zetaf,std::riemann_zetal + +.SH Synopsis + double riemann_zeta( double arg ); + + double riemann_zeta( float arg ); + double riemann_zeta( long double arg ); \fB(1)\fP + float riemann_zetaf( float arg ); + + long double riemann_zetal( long double arg ); + double riemann_zeta( IntegralType arg ); \fB(2)\fP + + 1) Computes the Riemann zeta function of arg. + 2) A set of overloads or a function template accepting an argument of any integral + type. Equivalent to \fB(1)\fP after casting the argument to double. + + As all special functions, riemann_zeta is only guaranteed to be available in + if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least + 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any + standard library headers. + +.SH Parameters + + arg - value of a floating-point or integral type + +.SH Return value + + If no errors occur, value of the Riemann zeta function of arg, ζ(arg), defined for + the entire real axis: + + * For arg > 1, Σ∞ + n=1n-arg + . + * For 0 ≤ arg ≤ 1, + + 1 + 1 - 21-arg + + Σ∞ + n=1(-1)n-1 + n-arg + . + * For arg < 0, 2arg + πarg-1 + sin( + + πarg + 2 + + )Γ(1 − arg)ζ(1 − arg). + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + +.SH Notes + + Implementations that do not support TR 29124 but support TR 19768, provide this + function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + +.SH Example + + (works as shown with gcc 6.0) + + +// Run this code + + #define __STDCPP_WANT_MATH_SPEC_FUNCS__ 1 + #include + #include + + int main() + { + // spot checks for well-known values + std::cout << "ζ(-1) = " << std::riemann_zeta(-1) << '\\n' + << "ζ(0) = " << std::riemann_zeta(0) << '\\n' + << "ζ(1) = " << std::riemann_zeta(1) << '\\n' + << "ζ(0.5) = " << std::riemann_zeta(0.5) << '\\n' + << "ζ(2) = " << std::riemann_zeta(2) << ' ' + << "(π²/6 = " << std::pow(std::acos(-1), 2) / 6 << ")\\n"; + } + +.SH Output: + + ζ(-1) = -0.0833333 + ζ\fB(0)\fP = -0.5 + ζ\fB(1)\fP = inf + ζ(0.5) = -1.46035 + ζ\fB(2)\fP = 1.64493 (π²/6 = 1.64493) + +.SH External links + + Weisstein, Eric W. "Riemann Zeta Function." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::rint,std::lrint,std::llrint.3 b/man/std::rint,std::lrint,std::llrint.3 deleted file mode 100644 index 5d6ad49e4..000000000 --- a/man/std::rint,std::lrint,std::llrint.3 +++ /dev/null @@ -1,112 +0,0 @@ -.TH std::rint,std::lrint,std::llrint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float rint( float arg ); \fI(since C++11)\fP - double rint( double arg ); \fI(since C++11)\fP - long double rint( long double arg ); \fI(since C++11)\fP - double rint( Integral arg ); \fI(since C++11)\fP - long lrint( float arg ); \fI(since C++11)\fP - long lrint( double arg ); \fI(since C++11)\fP - long lrint( long double arg ); \fI(since C++11)\fP - long lrint( Integral arg ); \fI(since C++11)\fP - long long llrint( float arg ); \fI(since C++11)\fP - long long llrint( double arg ); \fI(since C++11)\fP - long long llrint( long double arg ); \fI(since C++11)\fP - long long llrint( Integral arg ); \fI(since C++11)\fP - - Rounds the floating-point argument arg to an integer value in floating-point format, - using the current rounding mode. If the result differs from arg (i.e., arg was not - an integer value already), the floating-point exception FE_INEXACT is raised. - -.SH Parameters - - arg - floating point value - -.SH Return value - - The integer result of rounding arg - -.SH Notes - - The only difference between std::nearbyint and std::rint is that std::rint may raise - the FE_INEXACT floating-point exception, while std::nearbyint never raises it. - -.SH Example - - -// Run this code - - #include - #include - #include - int main() - { - #pragma STDC FENV_ACCESS ON - std::fesetround(FE_DOWNWARD); - std::cout << "rounding using FE_DOWNWARD:\\n" << std::fixed - << " 12.0 -> " << std::rint(12.0) << '\\n' - << " 12.1 -> " << std::rint(12.1) << '\\n' - << "-12.1 -> " << std::rint(-12.1) << '\\n' - << " 12.5 -> " << std::rint(12.5) << '\\n' - << " 12.9 -> " << std::rint(12.9) << '\\n' - << "-12.9 -> " << std::rint(-12.9) << '\\n' - << " 13.0 -> " << std::rint(13.0) << '\\n'; - std::fesetround(FE_TONEAREST); - std::cout << "rounding using FE_TONEAREST: \\n" - << " 12.0 -> " << std::rint(12.0) << '\\n' - << " 12.1 -> " << std::rint(12.1) << '\\n' - << "-12.1 -> " << std::rint(-12.1) << '\\n' - << " 12.5 -> " << std::rint(12.5) << '\\n' - << " 12.9 -> " << std::rint(12.9) << '\\n' - << "-12.9 -> " << std::rint(-12.9) << '\\n' - << " 13.0 -> " << std::rint(13.0) << '\\n'; - - std::cout << "When rounding 12.0 "; - std::feclearexcept(FE_ALL_EXCEPT); - std::rint(12.0); - if(std::fetestexcept(FE_ALL_EXCEPT) & FE_INEXACT) { - std::cout << "inexact result reported\\n"; - } else { - std::cout << "inexact result not reported\\n"; - } - - std::cout << "When rounding 12.1 "; - std::rint(12.1); - if(std::fetestexcept(FE_ALL_EXCEPT) & FE_INEXACT) { - std::cout << "inexact result reported\\n"; - } else { - std::cout << "inexact result not reported\\n"; - } - } - -.SH Output: - - rounding using FE_DOWNWARD: - 12.0 -> 12.000000 - 12.1 -> 12.000000 - -12.1 -> -13.000000 - 12.5 -> 12.000000 - 12.9 -> 12.000000 - -12.9 -> -13.000000 - 13.0 -> 13.000000 - rounding using FE_TONEAREST: - 12.0 -> 12.000000 - 12.1 -> 12.000000 - -12.1 -> -12.000000 - 12.5 -> 12.000000 - 12.9 -> 13.000000 - -12.9 -> -13.000000 - 13.0 -> 13.000000 - When rounding 12.0 inexact result not reported - When rounding 12.1 inexact result reported - -.SH See also - - nearbyint nearest integer using current rounding mode - \fI(C++11)\fP \fI(function)\fP - trunc nearest integer not greater in magnitude than the given value - \fI(C++11)\fP \fI(function)\fP - fegetround - fesetround gets or sets rounding direction - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP diff --git a/man/std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,.3 b/man/std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,.3 new file mode 100644 index 000000000..673819ec7 --- /dev/null +++ b/man/std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,.3 @@ -0,0 +1,233 @@ +.TH std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint, \- std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint, + +.SH Synopsis + + Defined in header + Rounding to floating-point types + float rint ( float num ); + + double rint ( double num ); \fI(since C++11)\fP + (until C++23) + long double rint ( long double num + ); + /* floating-point-type */ rint( /* (since C++23) + floating-point-type */ num ); + float rintf( float num ); \fB(2)\fP \fI(since C++11)\fP + long double rintl( long double num \fB(3)\fP \fI(since C++11)\fP + ); + Rounding to long + long lrint ( float num ); + \fI(since C++11)\fP + long lrint ( double num ); (until C++23) + + long lrint ( long double num ); + long lrint ( /* (since C++23) + floating-point-type */ num ); + long lrintf( float num ); \fB(5)\fP \fI(since C++11)\fP + long lrintl( long double num ); \fB(1)\fP \fB(6)\fP \fI(since C++11)\fP + Rounding to long long + long long llrint ( float num ); + + long long llrint ( double num ); \fI(since C++11)\fP + (until C++23) + long long llrint ( long double num \fB(4)\fP + ); + long long llrint ( /* (since C++23) + floating-point-type */ num ); + long long llrintf( float num ); \fB(8)\fP \fI(since C++11)\fP + long long llrintl( long double num \fB(7)\fP \fB(9)\fP \fI(since C++11)\fP + ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + double rint( Integer num ); + template< class Integer > (B) \fI(since C++11)\fP + long lrint( Integer num ); + template< class Integer > (C) \fI(since C++11)\fP + long long llrint( Integer num ); + + 1-3) Rounds the floating-point argument num to an integer value (in floating-point + format), using the current rounding mode. + The library provides overloads of std::rint for all cv-unqualified floating-point + types as the type of the parameter num. + (since C++23) + 4-9) Rounds the floating-point argument num to an integer value, using the current + rounding mode. + The library provides overloads of std::lrint and std::llrint for all cv-unqualified + floating-point types as the type of the parameter num. + (since C++23) + A-C) Additional overloads are provided for all integer types, which are treated as + double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the nearest integer value to num, according to the current + rounding mode, is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the result of std::lrint or std::llrint is outside the range representable by the + return type, a domain error or a range error may occur. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + For the std::rint function: + * If num is ±∞, it is returned, unmodified. + * If num is ±0, it is returned, unmodified. + * If num is NaN, NaN is returned. + + For std::lrint and std::llrint functions: + * If num is ±∞, FE_INVALID is raised and an implementation-defined value is + returned. + * If the result of the rounding is outside the range of the return type, + FE_INVALID is raised and an implementation-defined value is returned. + * If num is NaN, FE_INVALID is raised and an implementation-defined value is + returned. + +.SH Notes + + POSIX specifies that all cases where std::lrint or std::llrint raise FE_INEXACT are + domain errors. + + As specified in math_errhandling, FE_INEXACT may be (but isn't required to be on + non-IEEE floating-point platforms) raised by std::rint when rounding a non-integer + finite value. + + The only difference between std::rint and std::nearbyint is that std::nearbyint + never raises FE_INEXACT. + + The largest representable floating-point values are exact integers in all standard + floating-point formats, so std::rint never overflows on its own; however the result + may overflow any integer type (including std::intmax_t), when stored in an integer + variable. + + If the current rounding mode is: + + * FE_DOWNWARD, then std::rint is equivalent to std::floor. + * FE_UPWARD, then std::rint is equivalent to std::ceil. + * FE_TOWARDZERO, then std::rint is equivalent to std::trunc. + * FE_TONEAREST, then std::rint differs from std::round in that halfway cases are + rounded to even rather than away from zero. + + The additional overloads are not required to be provided exactly as (A-C). They only + need to be sufficient to ensure that for their argument num of integer type: + + * std::rint(num) has the same effect as std::rint(static_cast(num)). + * std::lrint(num) has the same effect as std::lrint(static_cast(num)). + * std::llrint(num) has the same effect as std::llrint(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::fesetround(FE_TONEAREST); + std::cout << "Rounding to nearest (halfway cases to even):\\n" + << " rint(+2.3) = " << std::rint(2.3) << '\\n' + << " rint(+2.5) = " << std::rint(2.5) << '\\n' + << " rint(+3.5) = " << std::rint(3.5) << '\\n' + << " rint(-2.3) = " << std::rint(-2.3) << '\\n' + << " rint(-2.5) = " << std::rint(-2.5) << '\\n' + << " rint(-3.5) = " << std::rint(-3.5) << '\\n'; + + std::fesetround(FE_DOWNWARD); + std::cout << "Rounding down:\\n" + << " rint(+2.3) = " << std::rint(2.3) << '\\n' + << " rint(+2.5) = " << std::rint(2.5) << '\\n' + << " rint(+3.5) = " << std::rint(3.5) << '\\n' + << " rint(-2.3) = " << std::rint(-2.3) << '\\n' + << " rint(-2.5) = " << std::rint(-2.5) << '\\n' + << " rint(-3.5) = " << std::rint(-3.5) << '\\n' + << "Rounding down with lrint:\\n" + << " lrint(+2.3) = " << std::lrint(2.3) << '\\n' + << " lrint(+2.5) = " << std::lrint(2.5) << '\\n' + << " lrint(+3.5) = " << std::lrint(3.5) << '\\n' + << " lrint(-2.3) = " << std::lrint(-2.3) << '\\n' + << " lrint(-2.5) = " << std::lrint(-2.5) << '\\n' + << " lrint(-3.5) = " << std::lrint(-3.5) << '\\n' + << "Special values:\\n" + << " lrint(-0.0) = " << std::lrint(-0.0) << '\\n' + << std::hex << std::showbase + << " lrint(-Inf) = " << std::lrint(-INFINITY) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "std::rint(0.1) = " << std::rint(.1) << '\\n'; + if (std::fetestexcept(FE_INEXACT)) + std::cout << " FE_INEXACT was raised\\n"; + + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "std::lrint(LONG_MIN-2048.0) = " + << std::lrint(LONG_MIN - 2048.0) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID was raised\\n"; + } + +.SH Possible output: + + Rounding to nearest (halfway cases to even): + rint(+2.3) = 2 + rint(+2.5) = 2 + rint(+3.5) = 4 + rint(-2.3) = -2 + rint(-2.5) = -2 + rint(-3.5) = -4 + Rounding down: + rint(+2.3) = 2 + rint(+2.5) = 2 + rint(+3.5) = 4 + rint(-2.3) = -2 + rint(-2.5) = -2 + rint(-3.5) = -4 + Rounding down with lrint: + lrint(+2.3) = 2 + lrint(+2.5) = 2 + lrint(+3.5) = 3 + lrint(-2.3) = -3 + lrint(-2.5) = -3 + lrint(-3.5) = -4 + Special values: + lrint(-0.0) = 0 + lrint(-Inf) = 0x8000000000000000 + std::rint(0.1) = 0 + std::lrint(LONG_MIN-2048.0) = 0x8000000000000000 + FE_INVALID was raised + +.SH See also + + trunc + truncf + truncl nearest integer not greater in magnitude than the given value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + nearbyint + nearbyintf + nearbyintl nearest integer using current rounding mode + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + fegetround + fesetround gets or sets rounding direction + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + C documentation for + rint diff --git a/man/std::rotate.3 b/man/std::rotate.3 index 49fe44648..61f6c2c4a 100644 --- a/man/std::rotate.3 +++ b/man/std::rotate.3 @@ -1,116 +1,166 @@ -.TH std::rotate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rotate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rotate \- std::rotate + .SH Synopsis Defined in header - template< class ForwardIt > \fI(until C++11)\fP - void rotate( ForwardIt first, ForwardIt n_first, ForwardIt last ); template< class ForwardIt > - ForwardIt rotate( ForwardIt first, ForwardIt n_first, ForwardIt last \fI(since C++11)\fP - ); + ForwardIt rotate( ForwardIt first, ForwardIt middle, \fB(1)\fP (constexpr since C++20) + ForwardIt last ); + template< class ExecutionPolicy, class ForwardIt > + + ForwardIt rotate( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP - Performs a left rotation on a range of elements. + ForwardIt first, ForwardIt middle, + ForwardIt last ); + 1) Performs a left rotation on a range of elements. Specifically, std::rotate swaps the elements in the range [first, last) in such a - way that the element n_first becomes the first element of the new range and n_first - - 1 becomes the last element. + way that the elements in [first, middle) are placed after the elements in + [middle, last) while the orders of the elements in both ranges are preserved. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) - A precondition of this function is that [first, n_first) and [n_first, last) are - valid ranges. + If any of the following conditions is satisfied, the behavior is undefined: + + * [first, middle) or [middle, last) is not a valid range. + + * The type of *first is not Swappable. \fI(until C++11)\fP + * ForwardIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first - the beginning of the original range - n_first - the element that should appear at the beginning of the - rotated range - last - the end of the original range + first - the beginning of the original range + middle - the element that should appear at the beginning of the rotated range + last - the end of the original range + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - ForwardIt must meet the requirements of ValueSwappable and ForwardIterator. - - - The type of dereferenced ForwardIt must meet the requirements of MoveAssignable and - MoveConstructible. + ForwardIt must meet the requirements of LegacyForwardIterator. .SH Return value - \fI(none)\fP \fI(until C++11)\fP - The iterator equal to first + (last - n_first) \fI(since C++11)\fP + The iterator to the element originally referenced by *first, i.e. the + std::distance(middle, last) + th next iterator of first. .SH Complexity - Linear in the distance between first and last + At most std::distance(first, last) swaps. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template - void rotate(ForwardIt first, ForwardIt n_first, ForwardIt last) + See also the implementations in libstdc++, libc++, and MSVC STL. + + template + constexpr // since C++20 + ForwardIt rotate(ForwardIt first, ForwardIt middle, ForwardIt last) { - ForwardIt next = n_first; - while (first != next) { - std::iter_swap(first++, next++); - if (next == last) { - next = n_first; - } else if (first == n_first) { - n_first = next; - } + if (first == middle) + return last; + + if (middle == last) + return first; + + ForwardIt write = first; + ForwardIt next_read = first; // read position for when “read” hits “last” + + for (ForwardIt read = middle; read != last; ++write, ++read) + { + if (write == next_read) + next_read = read; // track where “first” went + std::iter_swap(write, read); } + + // rotate the remaining sequence into place + rotate(write, next_read, last); + return write; } +.SH Notes + + std::rotate has better efficiency on common implementations if ForwardIt satisfies + LegacyBidirectionalIterator or (better) LegacyRandomAccessIterator. + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + satisfies LegacyContiguousIterator and swapping its value type calls neither + non-trivial special member function nor ADL-found swap. + .SH Example std::rotate is a common building block in many algorithms. This example demonstrates - insertion sort: + insertion sort. + - // Run this code - #include - #include #include - - int main() + #include + #include + + auto print = [](const auto remark, const auto& v) { - std::vector v{2, 4, 2, 0, 5, 10, 7, 3, 7, 1}; - - std::cout << "before sort: "; - for (int n: v) + std::cout << remark; + for (auto n : v) std::cout << n << ' '; std::cout << '\\n'; - + }; + + int main() + { + std::vector v{2, 4, 2, 0, 5, 10, 7, 3, 7, 1}; + print("before sort:\\t\\t", v); + // insertion sort - for (auto i = v.begin(); i != v.end(); ++i) { - std::rotate(std::upper_bound(v.begin(), i, *i), i, i+1); - } - - std::cout << "after sort: "; - for (int n: v) - std::cout << n << ' '; - std::cout << '\\n'; - + for (auto i = v.begin(); i != v.end(); ++i) + std::rotate(std::upper_bound(v.begin(), i, *i), i, i + 1); + print("after sort:\\t\\t", v); + // simple rotation to the left std::rotate(v.begin(), v.begin() + 1, v.end()); - - std::cout << "simple rotate left : "; - for (int n: v) - std::cout << n << ' '; - std::cout << '\\n'; - + print("simple rotate left:\\t", v); + // simple rotation to the right std::rotate(v.rbegin(), v.rbegin() + 1, v.rend()); - - std::cout << "simple rotate right : "; - for (int n: v) - std::cout << n << ' '; - std::cout << '\\n'; - + print("simple rotate right:\\t", v); } .SH Output: - before sort: 2 4 2 0 5 10 7 3 7 1 - after sort: 0 1 2 2 3 4 5 7 7 10 - simple rotate left : 1 2 2 3 4 5 7 7 10 0 - simple rotate right: 0 1 2 2 3 4 5 7 7 10 + before sort: 2 4 2 0 5 10 7 3 7 1 + after sort: 0 1 2 2 3 4 5 7 7 10 + simple rotate left: 1 2 2 3 4 5 7 7 10 0 + simple rotate right: 0 1 2 2 3 4 5 7 7 10 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 488 C++98 the new location of the element pointed by first returned + was not returned .SH See also - rotate_copy copies and rotate a range of elements - \fI(function template)\fP + rotate_copy copies and rotate a range of elements + \fI(function template)\fP + ranges::rotate rotates the order of elements in a range + (C++20) (niebloid) diff --git a/man/std::rotate_copy.3 b/man/std::rotate_copy.3 index 8a2695fe8..f6fa25c28 100644 --- a/man/std::rotate_copy.3 +++ b/man/std::rotate_copy.3 @@ -1,15 +1,41 @@ -.TH std::rotate_copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::rotate_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rotate_copy \- std::rotate_copy + .SH Synopsis Defined in header template< class ForwardIt, class OutputIt > - OutputIt rotate_copy( ForwardIt first, ForwardIt n_first, + OutputIt rotate_copy( ForwardIt first, ForwardIt + n_first, \fB(1)\fP (constexpr since C++20) + + ForwardIt last, OutputIt d_first + ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + ForwardIt2 rotate_copy( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 \fB(2)\fP \fI(since C++17)\fP + n_first, + + ForwardIt1 last, ForwardIt2 + d_first ); - ForwardIt last, OutputIt d_first ); + 1) Copies the elements from the range [first, last), to another range beginning at + d_first in such a way, that the element *(n_first) becomes the first element of the + new range and *(n_first - 1) becomes the last element. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if - Copies the elements from the range [first, last), to another range beginning at - d_first in such a way, that the element n_first becomes the first element of the new - range and n_first - 1 becomes the last element. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the behavior is undefined: + + * [first, n_first) or [n_first, last) is not a valid range. + * The source and destination ranges overlap. .SH Parameters @@ -17,21 +43,40 @@ n_first - an iterator to an element in [first, last) that should appear at the beginning of the new range d_first - beginning of the destination range + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt, ForwardIt1, ForwardIt2 must meet the requirements of + LegacyForwardIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. .SH Return value Output iterator to the element past the last element copied. +.SH Complexity + + Exactly std::distance(first, last) assignments. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + .SH Possible implementation + See also the implementations in libstdc++, libc++, and MSVC STL. + template + constexpr // since C++20 OutputIt rotate_copy(ForwardIt first, ForwardIt n_first, - ForwardIt last, OutputIt d_first) + ForwardIt last, OutputIt d_first) { d_first = std::copy(n_first, last, d_first); return std::copy(first, n_first, d_first); @@ -39,36 +84,40 @@ .SH Example - + // Run this code #include - #include #include - + #include + #include + int main() { - std::vector src = {1, 2, 3, 4, 5}; - auto pivot = std::find(src.begin(), src.end(), 3); + std::vector src{1, 2, 3, 4, 5}; std::vector dest(src.size()); - + auto pivot = std::find(src.begin(), src.end(), 3); + std::rotate_copy(src.begin(), pivot, src.end(), dest.begin()); - - for (const auto &i : dest) { + for (int i : dest) std::cout << i << ' '; - } + std::cout << '\\n'; + + // copy the rotation result directly to the std::cout + pivot = std::find(dest.begin(), dest.end(), 1); + std::rotate_copy(dest.begin(), pivot, dest.end(), + std::ostream_iterator(std::cout, " ")); std::cout << '\\n'; } .SH Output: 3 4 5 1 2 - -.SH Complexity - - linear in the distance between first and last + 1 2 3 4 5 .SH See also - rotate rotates the order of elements in a range - \fI(function template)\fP + rotate rotates the order of elements in a range + \fI(function template)\fP + ranges::rotate_copy copies and rotate a range of elements + (C++20) (niebloid) diff --git a/man/std::rotl.3 b/man/std::rotl.3 new file mode 100644 index 000000000..db0a112a7 --- /dev/null +++ b/man/std::rotl.3 @@ -0,0 +1,74 @@ +.TH std::rotl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rotl \- std::rotl + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + [[nodiscard]] constexpr T rotl( T x, int s ) noexcept; + + Computes the result of bitwise left-rotating the value of x by s positions. This + operation is also known as a left circular shift. + + Formally, let N be std::numeric_limits::digits, r be s % N. + + * If r is 0, returns x; + * if r is positive, returns (x << r) | (x >> (N - r)); + * if r is negative, returns std::rotr(x, -r). + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + s - number of positions to shift + +.SH Return value + + The result of bitwise left-rotating x by s positions. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::uint8_t i = 0b00011101; + std::cout << "i = " << std::bitset<8>(i) << '\\n'; + std::cout << "rotl(i,0) = " << std::bitset<8>(std::rotl(i, 0)) << '\\n'; + std::cout << "rotl(i,1) = " << std::bitset<8>(std::rotl(i, 1)) << '\\n'; + std::cout << "rotl(i,4) = " << std::bitset<8>(std::rotl(i, 4)) << '\\n'; + std::cout << "rotl(i,9) = " << std::bitset<8>(std::rotl(i, 9)) << '\\n'; + std::cout << "rotl(i,-1) = " << std::bitset<8>(std::rotl(i, -1)) << '\\n'; + } + +.SH Output: + + i = 00011101 + rotl(i,0) = 00011101 + rotl(i,1) = 00111010 + rotl(i,4) = 11010001 + rotl(i,9) = 00111010 + rotl(i,-1) = 10001110 + +.SH See also + + rotr computes the result of bitwise right-rotation + (C++20) \fI(function template)\fP + operator<<= + operator>>= performs binary shift left and shift right + operator<< \fI(public member function of std::bitset)\fP + operator>> diff --git a/man/std::rotr.3 b/man/std::rotr.3 new file mode 100644 index 000000000..de4dbba58 --- /dev/null +++ b/man/std::rotr.3 @@ -0,0 +1,72 @@ +.TH std::rotr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::rotr \- std::rotr + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + [[nodiscard]] constexpr T rotr( T x, int s ) noexcept; + + Computes the result of bitwise right-rotating the value of x by s positions. This + operation is also known as a right circular shift. + + Formally, let N be std::numeric_limits::digits, r be s % N. + + * If r is 0, returns x; + * if r is positive, returns (x >> r) | (x << (N - r)); + * if r is negative, returns std::rotl(x, -r). + + This overload participates in overload resolution only if T is an unsigned integer + type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned + long long, or an extended unsigned integer type). + +.SH Parameters + + x - value of unsigned integer type + s - number of positions to shift + +.SH Return value + + The result of bitwise right-rotating x by s positions. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_bitops 201907L (C++20) Bit operations + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::uint8_t i = 0b00011101; + std::cout << "i = " << std::bitset<8>(i) << '\\n'; + std::cout << "rotr(i,0) = " << std::bitset<8>(std::rotr(i, 0)) << '\\n'; + std::cout << "rotr(i,1) = " << std::bitset<8>(std::rotr(i, 1)) << '\\n'; + std::cout << "rotr(i,9) = " << std::bitset<8>(std::rotr(i, 9)) << '\\n'; + std::cout << "rotr(i,-1) = " << std::bitset<8>(std::rotr(i, -1)) << '\\n'; + } + +.SH Output: + + i = 00011101 + rotr(i,0) = 00011101 + rotr(i,1) = 10001110 + rotr(i,9) = 10001110 + rotr(i,-1) = 00111010 + +.SH See also + + rotl computes the result of bitwise left-rotation + (C++20) \fI(function template)\fP + operator<<= + operator>>= performs binary shift left and shift right + operator<< \fI(public member function of std::bitset)\fP + operator>> diff --git a/man/std::round,std::lround,std::llround.3 b/man/std::round,std::lround,std::llround.3 deleted file mode 100644 index c52d390ad..000000000 --- a/man/std::round,std::lround,std::llround.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::round,std::lround,std::llround 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float round( float arg ); \fI(since C++11)\fP - double round( double arg ); \fI(since C++11)\fP - long double round( long double arg ); \fI(since C++11)\fP - double round( Integral arg ); \fI(since C++11)\fP - long lround( float arg ); \fI(since C++11)\fP - long lround( double arg ); \fI(since C++11)\fP - long lround( long double arg ); \fI(since C++11)\fP - long lround( Integral arg ); \fI(since C++11)\fP - long long llround( float arg ); \fI(since C++11)\fP - long long llround( double arg ); \fI(since C++11)\fP - long long llround( long double arg ); \fI(since C++11)\fP - long long llround( Integral arg ); \fI(since C++11)\fP - - Computes nearest integer to arg. Number is rounded away from zero in halfway cases - -.SH Parameters - - arg - floating point value - -.SH Return value - - Nearest integer to arg. - -.SH Return value - math-round away zero.svg - Argument - -.SH See also - - floor nearest integer not greater than the given value - \fI(function)\fP - ceil nearest integer not less than the given value - \fI(function)\fP - trunc nearest integer not greater in magnitude than the given value - \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl,.3 b/man/std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl,.3 new file mode 100644 index 000000000..2586dfa87 --- /dev/null +++ b/man/std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl,.3 @@ -0,0 +1,266 @@ +.TH std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl, \- std::round,std::roundf,std::roundl,std::lround,std::lroundf,std::lroundl, + +.SH Synopsis + + Defined in header + Rounding to floating-point + types + float round ( float num + ); + + double round ( double num \fI(since C++11)\fP + ); (until C++23) + + long double round ( long double + num ); + constexpr /* + floating-point-type */ (since C++23) + round ( /* + floating-point-type */ num ); + float roundf( float num \fI(since C++11)\fP + ); \fB(2)\fP (constexpr + since C++23) + long double roundl( long double \fI(since C++11)\fP + num ); \fB(3)\fP (constexpr + since C++23) + Rounding to long + long lround ( float num ); + + long lround ( double num ); \fI(since C++11)\fP + (until C++23) + long lround ( long double num + ); + constexpr long lround( /* (since C++23) + floating-point-type */ num ); + \fI(since C++11)\fP + long lroundf( float num ); \fB(5)\fP (constexpr + since C++23) + long lroundl( long double num \fB(1)\fP \fI(since C++11)\fP + ); \fB(6)\fP (constexpr + since C++23) + Rounding to long long + long long llround ( float num + ); + + long long llround ( double num \fI(since C++11)\fP + ); (until C++23) + \fB(4)\fP + long long llround ( long double + num ); + constexpr long long llround( /* (since C++23) + floating-point-type */ num ); + long long llroundf( float num \fI(since C++11)\fP + ); \fB(8)\fP (constexpr + since C++23) + long long llroundl( long double \fB(7)\fP \fI(since C++11)\fP + num ); \fB(9)\fP (constexpr + since C++23) + Additional overloads + Defined in header + template< class Integer > \fI(since C++11)\fP + double round( Integer num ); (A) (constexpr + since C++23) + template< class Integer > \fI(since C++11)\fP + long lround( Integer num ); (B) (constexpr + since C++23) + template< class Integer > \fI(since C++11)\fP + long long llround( Integer num (C) (constexpr + ); since C++23) + + 1-3) Computes the nearest integer value to num (in floating-point format), rounding + halfway cases away from zero, regardless of the current rounding mode. + The library provides overloads of std::round for all cv-unqualified floating-point + types as the type of the parameter num. + (since C++23) + 4-9) Computes the nearest integer value to num (in integer format), rounding halfway + cases away from zero, regardless of the current rounding mode. + The library provides overloads of std::lround and std::llround for all + cv-unqualified floating-point types as the type of the parameter num. + (since C++23) + A-C) Additional overloads are provided for all integer types, which are treated as + double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the nearest integer value to num, rounding halfway cases away + from zero, is returned. + +.SH Return value + math-round away zero.svg + num + + If a domain error occurs, an implementation-defined value is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the result of std::lround or std::llround is outside the range representable by + the return type, a domain error or a range error may occur. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + For the std::round function: + * The current rounding mode has no effect. + * If num is ±∞, it is returned, unmodified. + * If num is ±0, it is returned, unmodified. + * If num is NaN, NaN is returned. + For std::lround and std::llround functions: + * FE_INEXACT is never raised. + * The current rounding mode has no effect. + * If num is ±∞, FE_INVALID is raised and an implementation-defined value is + returned. + * If the result of the rounding is outside the range of the return type, + FE_INVALID is raised and an implementation-defined value is returned. + * If num is NaN, FE_INVALID is raised and an implementation-defined value is + returned. + +.SH Notes + + FE_INEXACT may be (but is not required to be) raised by std::round when rounding a + non-integer finite value. + + The largest representable floating-point values are exact integers in all standard + floating-point formats, so std::round never overflows on its own; however the result + may overflow any integer type (including std::intmax_t), when stored in an integer + variable. + + POSIX specifies that all cases where std::lround or std::llround raise FE_INEXACT + are domain errors. + + The double version of std::round behaves as if implemented as follows: + + #include + #include + + #pragma STDC FENV_ACCESS ON + + double round(double x) + { + const int save_round = std::fegetround(); + std::fesetround(FE_TOWARDZERO); + const double result = std::rint(std::copysign(0.5 + std::fabs(x), x)); + std::fesetround(save_round); + return result; + } + + The additional overloads are not required to be provided exactly as (A-C). They only + need to be sufficient to ensure that for their argument num of integer type: + + * std::round(num) has the same effect as std::round(static_cast(num)). + * std::lround(num) has the same effect as std::lround(static_cast(num)). + * std::llround(num) has the same effect as std::llround(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + double custom_round(double x) + { + const int save_round = std::fegetround(); + std::fesetround(FE_TOWARDZERO); + const double result = std::rint(std::copysign(0.5 + std::fabs(x), x)); + std::fesetround(save_round); + return result; + } + + void test_custom_round() + { + for (const double x : + { + 0.0, 0.3, + 0.5 - DBL_EPSILON / 2, + 0.5, + 0.5 + DBL_EPSILON / 2, + 0.7, 1.0, 2.3, 2.5, 2.7, 3.0, + static_cast(INFINITY) + }) + assert(round(+x) == custom_round(+x) && round(-x) == custom_round(-x)); + } + + int main() + { + test_custom_round(); + + std::cout << std::showpos; + + // round + std::cout << "round(+2.3) = " << std::round(2.3) + << " round(+2.5) = " << std::round(2.5) + << " round(+2.7) = " << std::round(2.7) << '\\n' + << "round(-2.3) = " << std::round(-2.3) + << " round(-2.5) = " << std::round(-2.5) + << " round(-2.7) = " << std::round(-2.7) << '\\n'; + + std::cout << "round(-0.0) = " << std::round(-0.0) << '\\n' + << "round(-Inf) = " << std::round(-INFINITY) << '\\n'; + + // lround + std::cout << "lround(+2.3) = " << std::lround(2.3) + << " lround(+2.5) = " << std::lround(2.5) + << " lround(+2.7) = " << std::lround(2.7) << '\\n' + << "lround(-2.3) = " << std::lround(-2.3) + << " lround(-2.5) = " << std::lround(-2.5) + << " lround(-2.7) = " << std::lround(-2.7) << '\\n'; + + std::cout << "lround(-0.0) = " << std::lround(-0.0) << '\\n' + << "lround(-Inf) = " << std::lround(-INFINITY) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "std::lround(LONG_MAX+1.5) = " + << std::lround(LONG_MAX + 1.5) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID was raised\\n"; + } + +.SH Possible output: + + round(+2.3) = +2 round(+2.5) = +3 round(+2.7) = +3 + round(-2.3) = -2 round(-2.5) = -3 round(-2.7) = -3 + round(-0.0) = -0 + round(-Inf) = -inf + lround(+2.3) = +2 lround(+2.5) = +3 lround(+2.7) = +3 + lround(-2.3) = -2 lround(-2.5) = -3 lround(-2.7) = -3 + lround(-0.0) = +0 + lround(-Inf) = -9223372036854775808 + std::lround(LONG_MAX+1.5) = -9223372036854775808 + FE_INVALID was raised + +.SH See also + + floor + floorf nearest integer not greater than the given value + floorl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ceil + ceilf nearest integer not less than the given value + ceill \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + trunc + truncf + truncl nearest integer not greater in magnitude than the given value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + round diff --git a/man/std::runtime_error.3 b/man/std::runtime_error.3 index 6709e46a0..b9d08fb00 100644 --- a/man/std::runtime_error.3 +++ b/man/std::runtime_error.3 @@ -1,4 +1,7 @@ -.TH std::runtime_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::runtime_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::runtime_error \- std::runtime_error + .SH Synopsis Defined in header class runtime_error; @@ -6,39 +9,114 @@ Defines a type of object to be thrown as exception. It reports errors that are due to events beyond the scope of the program and can not be easily predicted. + Exceptions of type std::runtime_error are thrown by the following standard library + components: std::locale::locale and std::locale::combine. + + In addition, the following standard exception types are derived from + std::runtime_error: + + * std::range_error + * std::overflow_error + * std::underflow_error + + * std::regex_error \fI(since C++11)\fP + * std::system_error + + * std::chrono::ambiguous_local_time + * std::chrono::nonexistent_local_time \fI(since C++20)\fP + * std::format_error + std-runtime error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP + constructor constructs a new runtime_error object with the given message + \fI(public member function)\fP + operator= replaces the runtime_error object + \fI(public member function)\fP - +std::runtime_error::runtime_error - std::runtime_error::runtime_error + runtime_error( const std::string& what_arg ); \fB(1)\fP + runtime_error( const char* what_arg ); \fB(2)\fP + runtime_error( const runtime_error& other ); \fB(3)\fP (noexcept since C++11) - explicit runtime_error( const std::string& what_arg ); \fB(1)\fP - explicit runtime_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP - - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::runtime_error + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::runtime_error is not permitted to throw exceptions, this + message is typically stored internally as a separately-allocated reference-counted + string. This is also why there is no constructor taking std::string&&: it would have + to copy the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::runtime_error::operator= + + runtime_error& operator=( const runtime_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::runtime_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const added + char* was missing + the explanatory strings of they are the same as that of + LWG 471 C++98 std::runtime_error's the + copies were implementation-defined original std::runtime_error + object diff --git a/man/std::runtime_format.3 b/man/std::runtime_format.3 new file mode 100644 index 000000000..3ccc84b3c --- /dev/null +++ b/man/std::runtime_format.3 @@ -0,0 +1,105 @@ +.TH std::runtime_format 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::runtime_format \- std::runtime_format + +.SH Synopsis + Defined in header + /*runtime-format-string*/ runtime_format( std::string_view \fB(1)\fP (since C++26) + fmt ) noexcept; + /*runtime-format-string*/ runtime_format( \fB(2)\fP (since C++26) + std::wstring_view fmt ) noexcept; + + Returns an object that stores a runtime format string directly usable in + user-oriented formatting functions and can be implicitly converted to + std::basic_format_string. + +.SH Parameters + + fmt - a string view + +.SH Return value + + An object holding the runtime format string of the exposition-only type: + +Class template runtime-format-string + + template< class CharT > (exposition only*) + struct /*runtime-format-string*/; + +.SH Member objects + + The returned object contains an exposition-only non-static data member str of type + std::basic_string_view. + + Constructors and assignments + + /*runtime-format-string*/( std::basic_string_view s ) noexcept; \fB(1)\fP + /*runtime-format-string*/( const /*runtime-format-string*/& ) = delete; \fB(2)\fP + /*runtime-format-string*/& operator=( const /*runtime-format-string*/& ) = \fB(3)\fP + delete; + + 1) Initializes str with s. + 2) Copy constructor is explicitly deleted. The type is neither copyable nor movable. + 3) The assignment is explicitly deleted. + +.SH Notes + + Since the return type of runtime_format is neither copyable nor movable, an attempt + of passing runtime_fmt as glvalue inhibits the construction of + std::basic_format_string which results in program ill-formed. To construct + std::basic_format_string with runtime_format, the returned value of runtime_format + is passed directly on std::basic_format_string as prvalue where copy elision is + guaranteed. + + auto runtime_fmt = std::runtime_format("{}"); + + auto s0 = std::format(runtime_fmt, 1); // error + auto s1 = std::format(std::move(runtime_fmt), 1); // still error + auto s2 = std::format(std::runtime_format("{}"), 1); // ok + + Feature-test macro Value Std Feature + __cpp_lib_format 202311L (C++26) Runtime format strings + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::print("Hello {}!\\n", "world"); + + std::string fmt; + for (int i{}; i != 3; ++i) + { + fmt += "{} "; // constructs the formatting string + std::print("{} : ", fmt); + std::println(std::runtime_format(fmt), "alpha", 'Z', 3.14, "unused"); + } + } + +.SH Output: + + Hello world! + {} : alpha + {} {} : alpha Z + {} {} {} : alpha Z 3.14 + +.SH See also + + format stores formatted representation of the arguments in a new string + (C++20) \fI(function template)\fP + vformat non-template variant of std::format using type-erased argument + (C++20) representation + \fI(function)\fP + basic_format_string + format_string class template that performs compile-time format string checks + wformat_string at construction time + (C++20) \fI(class template)\fP + (C++20) + (C++20) diff --git a/man/std::same_as.3 b/man/std::same_as.3 new file mode 100644 index 000000000..126bcf7c5 --- /dev/null +++ b/man/std::same_as.3 @@ -0,0 +1,57 @@ +.TH std::same_as 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::same_as \- std::same_as + +.SH Synopsis + Defined in header + template< class T, class U > \fI(since C++20)\fP + concept same_as = /* see below */; + + The concept same_as is satisfied if and only if T and U denote the same type. + + std::same_as subsumes std::same_as and vice versa. + +.SH Possible implementation + + namespace detail + { + template< class T, class U > + concept SameHelper = std::is_same_v; + } + + template< class T, class U > + concept same_as = detail::SameHelper && detail::SameHelper; + +.SH Example + + +// Run this code + + #include + #include + + template + concept IsAnyOf = (std::same_as || ...); + + template + concept IsPrintable = std::integral || std::floating_point || + IsAnyOf>>, char, wchar_t>; + + void println(IsPrintable auto const ... arguments) + { + (std::wcout << ... << arguments) << '\\n'; + } + + int main() + { + println("Example: ", 3.14, " : ", 42, " : [", 'a', L'-', L"Z]"); + } + +.SH Output: + + Example: 3.14 : 42 : [a-Z] + +.SH See also + + is_same checks if two types are the same + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::sample.3 b/man/std::sample.3 new file mode 100644 index 000000000..fe9979877 --- /dev/null +++ b/man/std::sample.3 @@ -0,0 +1,111 @@ +.TH std::sample 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sample \- std::sample + +.SH Synopsis + Defined in header + template< class PopulationIt, class SampleIt, class Distance, class + URBG > + \fI(since C++17)\fP + SampleIterator sample( PopulationIt first, PopulationIt last, + + SampleIt out, Distance n, URBG&& g ); + + Selects n elements from the sequence [first, last) (without replacement) such that + each possible sample has equal probability of appearance, and writes those selected + elements into the output iterator out. Random numbers are generated using the random + number generator g. + + If n is greater than the number of elements in the sequence, selects all elements in + the sequence. + + The algorithm is stable (preserves the relative order of the selected elements) only + if PopulationIt meets the requirements of LegacyForwardIterator. + + If + the value type of first + \fI(until C++20)\fP + *first + \fI(since C++20)\fP is not writable to out, the program is ill-formed. + + If any of the following conditions is satisfied, the behavior is undefined: + + * out is in [first, last). + * PopulationIt does not meet the requirements of LegacyInputIterator. + * SampleIt does not meet the requirements of LegacyOutputIterator. + * All following conditions are satisfied: + + * PopulationIt does not meet the requirements of (until C++23) + LegacyForwardIterator. + * PopulationIt does not model forward_iterator. (since C++23) + + * SampleIt does not meet the requirements of LegacyRandomAccessIterator. + * Given the type T as std::remove_reference_t, any of the following + conditions is satisfied: + + * T does not meet the requirements of UniformRandomBitGenerator. + + * The return type of T is not convertible to Distance. \fI(until C++20)\fP + +.SH Parameters + + first, last - pair of iterators forming the range from which to make the sampling + (the population) + out - the output iterator where the samples are written + n - number of samples to make + g - the random number generator used as the source of randomness +.SH Type requirements + - + Distance must be an integer type. + +.SH Return value + + Returns a copy of out after the last sample that was output, that is, end of the + sample range. + +.SH Complexity + + Linear in std::distance(first, last). + +.SH Possible implementation + + See the implementations in libstdc++, libc++ and MSVC STL. + +.SH Notes + + This function may implement selection sampling or reservoir sampling. + + Feature-test macro Value Std Feature + __cpp_lib_sample 201603L \fI(C++17)\fP std::sample + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string in {"ABCDEFGHIJK"}, out; + std::sample(in.begin(), in.end(), std::back_inserter(out), 4, + std::mt19937 {std::random_device{}()}); + std::cout << "Four random letters out of " << in << " : " << out << '\\n'; + } + +.SH Possible output: + + Four random letters out of ABCDEFGHIJK: EFGK + +.SH See also + + random_shuffle + shuffle randomly re-orders elements in a range + \fI(until C++17)\fP \fI(function template)\fP + \fI(C++11)\fP + ranges::sample selects N random elements from a sequence + (C++20) (niebloid) diff --git a/man/std::saturate_cast.3 b/man/std::saturate_cast.3 new file mode 100644 index 000000000..0adc3d3f3 --- /dev/null +++ b/man/std::saturate_cast.3 @@ -0,0 +1,76 @@ +.TH std::saturate_cast 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::saturate_cast \- std::saturate_cast + +.SH Synopsis + Defined in header + template< class T, class U > (since C++26) + constexpr T saturate_cast( U x ) noexcept; + + Converts the value x to a value of type T, clamping x between the minimum and + maximum values of type T. + + It is a compile-time error if either T or U is not a signed or unsigned integer type + (including standard integer type and extended integer type). + +.SH Parameters + + x - an integer value + +.SH Return value + + * x, if x is representable as a value of type T. Otherwise, + * either the largest or smallest representable value of type T, whichever is + closer to the value of x. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic + +.SH Possible implementation + + See libstdc++ (gcc). + +.SH Example + + Can be previewed on Compiler Explorer. + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::int16_t x1{696}; + + constexpr std::int8_t x2 = std::saturate_cast(x1); + static_assert(x2 == std::numeric_limits::max()); + + constexpr std::uint8_t x3 = std::saturate_cast(x1); + static_assert(x3 == std::numeric_limits::max()); + + constexpr std::int16_t y1{-696}; + + constexpr std::int8_t y2 = std::saturate_cast(y1); + static_assert(y2 == std::numeric_limits::min()); + + constexpr std::uint8_t y3 = std::saturate_cast(y1); + static_assert(y3 == 0); + } + +.SH See also + + bit_cast reinterpret the object representation of one type as that of another + (C++20) \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP diff --git a/man/std::scalbn,std::scalbln.3 b/man/std::scalbn,std::scalbln.3 deleted file mode 100644 index ece132be0..000000000 --- a/man/std::scalbn,std::scalbln.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::scalbn,std::scalbln 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float scalbn( float x, int exp ); \fI(since C++11)\fP - double scalbn( double x, int exp ); \fI(since C++11)\fP - long double scalbn( long double x, int exp ); \fI(since C++11)\fP - double scalbn( Integral x, int exp ); \fI(since C++11)\fP - float scalbln( float x, long exp ); \fI(since C++11)\fP - double scalbln( double x, long exp ); \fI(since C++11)\fP - long double scalbln( long double x, long exp ); \fI(since C++11)\fP - double scalbln( Integral x, long exp ); \fI(since C++11)\fP - - Multiplies an floating point value x by FLT_RADIX raised to power exp. On binary - system it is equivalent to std::ldexp() - -.SH Parameters - - arg - floating point value - exp - integer value - -.SH Return value - - Returns x×FLT_RADIX^exp. - - If the result is too large for the underlying type, range error occurs and HUGE_VAL - is returned. - -.SH See also - - frexp decomposes a number into significand and a power of 2 - \fI(function)\fP - ldexp multiplies a number by 2 raised to a power - \fI(function)\fP diff --git a/man/std::scalbn,std::scalbnf,std::scalbnl,std::scalbln,std::scalblnf,std::scalblnl.3 b/man/std::scalbn,std::scalbnf,std::scalbnl,std::scalbln,std::scalblnf,std::scalblnl.3 new file mode 100644 index 000000000..a9ef29eec --- /dev/null +++ b/man/std::scalbn,std::scalbnf,std::scalbnl,std::scalbln,std::scalblnf,std::scalblnl.3 @@ -0,0 +1,175 @@ +.TH std::scalbn,std::scalbnf,std::scalbnl,std::scalbln,std::scalblnf,std::scalblnl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scalbn,std::scalbnf,std::scalbnl,std::scalbln,std::scalblnf,std::scalblnl \- std::scalbn,std::scalbnf,std::scalbnl,std::scalbln,std::scalblnf,std::scalblnl + +.SH Synopsis + Defined in header + int exponent + float scalbn ( float num, int exp ); + + double scalbn ( double num, int exp \fI(since C++11)\fP + ); (until C++23) + + long double scalbn ( long double num, int + exp ); + constexpr /* floating-point-type */ + scalbn ( /* (since C++23) + floating-point-type */ num, int exp ); + \fI(since C++11)\fP + float scalbnf( float num, int exp ); \fB(2)\fP (constexpr since + C++23) + long double scalbnl( long double num, int \fI(since C++11)\fP + exp ); \fB(3)\fP (constexpr since + C++23) + long exponent + float scalbln ( float num, long exp + ); + + double scalbln ( double num, long exp \fB(1)\fP \fI(since C++11)\fP + ); (until C++23) + + long double scalbln ( long double num, + long exp ); + constexpr /* floating-point-type */ + scalbln ( /* (since C++23) + floating-point-type */ num, long exp ); + float scalblnf( float num, long exp \fI(since C++11)\fP + ); \fB(4)\fP \fB(5)\fP (constexpr since + C++23) + long double scalblnl( long double num, \fI(since C++11)\fP + long exp ); \fB(6)\fP (constexpr since + C++23) + Additional overloads + Defined in header + template< class Integer > \fI(since C++11)\fP + double scalbn( Integer num, int exp ); (A) (constexpr since + C++23) + template< class Integer > \fI(since C++11)\fP + double scalbln( Integer num, long exp ); (B) (constexpr since + C++23) + + 1-6) Multiplies a floating point value num by FLT_RADIX raised to power exp. + The library provides overloads of std::scalbn and std::scalbln for all + cv-unqualified floating-point types as the type of the parameter num. + (since C++23) + A,B) Additional overloads are provided for all integer types, which are treated as + double. + +.SH Parameters + + num - floating-point or integer value + exp - integer value + +.SH Return value + + If no errors occur, num multiplied by FLT_RADIX to the power of exp + (num×FLT_RADIXexp + ) is returned. + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned. + + If a range error due to underflow occurs, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * Unless a range error occurs, FE_INEXACT is never raised (the result is exact). + * Unless a range error occurs, the current rounding mode is ignored. + * If num is ±0, it is returned, unmodified. + * If num is ±∞, it is returned, unmodified. + * If exp is 0, then num is returned, unmodified. + * If num is NaN, NaN is returned. + +.SH Notes + + On binary systems (where FLT_RADIX is 2), std::scalbn is equivalent to std::ldexp. + + Although std::scalbn and std::scalbln are specified to perform the operation + efficiently, on many implementations they are less efficient than multiplication or + division by a power of two using arithmetic operators. + + The function name stands for "new scalb", where scalb was an older non-standard + function whose second argument had floating-point type. + + The std::scalbln function is provided because the factor required to scale from the + smallest positive floating-point value to the largest finite one may be greater than + 32767, the standard-guaranteed INT_MAX. In particular, for the 80-bit long double, + the factor is 32828. + + The GNU implementation does not set errno regardless of math_errhandling. + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num of integer type: + + * std::scalbn(num, exp) has the same effect as + std::scalbn(static_cast(num), exp). + * std::scalbln(num, exp) has the same effect as + std::scalbln(static_cast(num), exp). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "scalbn(7, -4) = " << std::scalbn(7, -4) << '\\n' + << "scalbn(1, -1074) = " << std::scalbn(1, -1074) + << " (minimum positive subnormal double)\\n" + << "scalbn(nextafter(1,0), 1024) = " + << std::scalbn(std::nextafter(1,0), 1024) + << " (largest finite double)\\n"; + + // special values + std::cout << "scalbn(-0, 10) = " << std::scalbn(-0.0, 10) << '\\n' + << "scalbn(-Inf, -1) = " << std::scalbn(-INFINITY, -1) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "scalbn(1, 1024) = " << std::scalbn(1, 1024) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Possible output: + + scalbn(7, -4) = 0.4375 + scalbn(1, -1074) = 4.94066e-324 (minimum positive subnormal double) + scalbn(nextafter(1,0), 1024) = 1.79769e+308 (largest finite double) + scalbn(-0, 10) = -0 + scalbn(-Inf, -1) = -inf + scalbn(1, 1024) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + frexp + frexpf decomposes a number into significand and base-2 exponent + frexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ldexp + ldexpf multiplies a number by 2 raised to an integral power + ldexpl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + scalbn diff --git a/man/std::scanf,std::fscanf,std::sscanf.3 b/man/std::scanf,std::fscanf,std::sscanf.3 index 84d34ddff..e5ce7be7a 100644 --- a/man/std::scanf,std::fscanf,std::sscanf.3 +++ b/man/std::scanf,std::fscanf,std::sscanf.3 @@ -1,190 +1,311 @@ -.TH std::scanf,std::fscanf,std::sscanf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scanf,std::fscanf,std::sscanf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scanf,std::fscanf,std::sscanf \- std::scanf,std::fscanf,std::sscanf + .SH Synopsis Defined in header - int scanf( const char* format, ... ); \fB(1)\fP + int scanf( const char* format, ... ); \fB(1)\fP int fscanf( std::FILE* stream, const char* format, ... ); \fB(2)\fP int sscanf( const char* buffer, const char* format, ... ); \fB(3)\fP - Reads data from the a variety of sources, interprets it according to format and - stores the results into given locations. + Reads data from a variety of sources, interprets it according to format and stores + the results into given locations. - 1) Reads the data from stdin - 2) Reads the data from file stream stream - 3) Reads the data from null-terminated character string buffer + 1) Reads the data from stdin. + 2) Reads the data from file stream stream. + 3) Reads the data from null-terminated character string buffer. .SH Parameters -stream - input file stream to read from -buffer - pointer to a null-terminated character string to read from - pointer to a null-terminated character string specifying how to read the input. - - The format string consists of whitespace characters (any single whitespace character in the format string consumes - all available consecutive whitespace characters from the input), non-whitespace characters except % (each such - character in the format string consumes exactly one identical character from the input) and conversion - specifications. Each conversion specification has the following format: - - * introductory % character - - * (optional) assignment-suppressing character *. If this option is present, the function does not assign the - result of the conversion to any receiving argument. - - * (optional) integer number (greater than zero) that specifies maximum field width, that is, the maximum number of - characters that the function is allowed to consume when doing the conversion specified by the current conversion - specification. Note that %s and %[ may lead to buffer overflow if the width is not provided. - - * (optional) length modifier that specifies the size of the receiving argument, that is, the actual destination - type. This affects the conversion accuracy and overflow rules. The default destination type is different for - each conversion type (see table below). - - * conversion format specifier - - The following format specifiers are available: - - Conversion Explanation Argument type - specifier - length modifier hh h \fI(none)\fP l ll j z t L - % matches literal % N/A N/A N/A N/A N/A N/A N/A N/A N/A - c matches a single - character - matches a character - s string (a sequence of - non-whitespace - characters) - matches a non-empty - sequence of character - from set of - characters. N/A N/A char* wchar_t* N/A N/A N/A N/A N/A - - If the first character - [set] of the set is ^, then - all characters not in - the set are matched. - If the set begins with - ] or ^] then the ] - character is also - included into the set. - matches a decimal - integer. - - d The format of the - number is the same as - expected by strtol() - with the value 10 for - the base argument - matches a decimal - integer. - - i The format of the - number is the same as - expected by strtol() - with the value 0 for -format - the base argument - matches a unsigned - decimal integer. - - u The format of the - number is the same as - expected by strtoul() - with the value 0 for signed - the base argument signed signed signed signed long - matches an octal char* or short* int* or long* or long* or intmax_t* - integer. unsigned or unsigned unsigned unsigned or size_t* ptrdiff_t* N/A - char* unsigned int* long* long uintmax_t* - o The format of the short* long* - number is the same as - expected by strtol() - with the value 8 for - the base argument - matches an hexadecimal - integer. - - x The format of the - number is the same as - expected by strtol() - with the value 16 for - the base argument - returns the number of - characters read so - far. - - No input is consumed. - n Does not increment the - assignment count. If - the specifier has - assignment-suppressing - operator defined, the - behavior is undefined - matches a - a, A floating-point number. - e, E N/A N/A float* double* N/A N/A N/A N/A long - f, F The format of the double* - g, G number is the same as - expected by strtof() - matches implementation - defined character - sequence defining a - pointer. - p N/A N/A void** N/A N/A N/A N/A N/A N/A - printf family of - functions should - produce the same - sequence using %p - format specifier - - All conversion specifiers other than [, c, and n consume and discard all leading whitespace characters before - attempting to parse the input. These consumed characters do not count towards the specified maximum field width. - - The conversion specifiers lc, ls, and l[ perform multibyte-to-wide character conversion as if by calling - std::mbrtowc with an std::mbstate_t object initialized to zero before the first character is converted. - - The conversion specifiers s and [ always store the null terminator in addition to the matched characters. The size - of the destination array must be at least one greater than the specified field width. - - The correct conversion specifications for the fixed-width character types (std:int8_t, etc) are defined in the - header . -... - receiving arguments + stream - input file stream to read from + buffer - pointer to a null-terminated character string to read from + format - pointer to a null-terminated character string specifying how to read the + input + ... - receiving arguments + + The format string consists of + + * non-whitespace multibyte characters except %: each such character in the format + string consumes exactly one identical character from the input stream, or causes + the function to fail if the next character on the stream does not compare equal. + * whitespace characters: any single whitespace character in the format string + consumes all available consecutive whitespace characters from the input + (determined as if by calling isspace in a loop). Note that there is no + difference between "\\n", " ", "\\t\\t", or other whitespace in the format string. + * conversion specifications. Each conversion specification has the following + format: + + * introductory % character. + + * (optional) assignment-suppressing character *. If this option is present, the + function does not assign the result of the conversion to any receiving argument. + + * (optional) integer number (greater than zero) that specifies maximum field + width, that is, the maximum number of characters that the function is allowed to + consume when doing the conversion specified by the current conversion + specification. Note that %s and %[ may lead to buffer overflow if the width is + not provided. + + * (optional) length modifier that specifies the size of the receiving argument, + that is, the actual destination type. This affects the conversion accuracy and + overflow rules. The default destination type is different for each conversion + type (see table below). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Argument type +specifier + hh ll j z t + Length modifier → h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + % Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A + Matches a character or + a sequence of + characters. + + If a width specifier + is used, matches + exactly width + c characters (the + argument must be a + pointer to an array + with sufficient room). + Unlike %s and %[, does + not append the null + character to the + array. + Matches a sequence of + non-whitespace + characters (a string). + + If width specifier is + used, matches up to + width or until the + first whitespace + s character, whichever + appears first. Always + stores a null + character in addition + to the characters + matched (so the + argument array must + have room for at least + width+1 characters) N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + Matches a non-empty + sequence of character + from set of + characters. + + If the first character + of the set is ^, then + all characters not in + the set are matched. + If the set begins with + ] or ^] then the ] + character is also + included into the set. + It is + implementation-defined + [set] whether the character + - in the non-initial + position in the + scanset may be + indicating a range, as + in [0-9]. If width + specifier is used, + matches only up to + width. Always stores a + null character in + addition to the + characters matched (so + the argument array + must have room for at + least width+1 + characters) + Matches a decimal + integer. + + d The format of the + number is the same as + expected by strtol + with the value 10 for + the base argument + Matches an integer. + + The format of the + number is the same as + i expected by strtol + with the value 0 for + the base argument + (base is determined by + the first characters + parsed) + Matches an unsigned + decimal integer. + + u The format of the + number is the same as + expected by strtoul signed + with the value 10 for signed signed signed signed long + the base argument. char* or short* int* or long* or long* or intmax_t* + Matches an unsigned unsigned or unsigned unsigned unsigned or size_t* ptrdiff_t* N/A + octal integer. char* unsigned int* long* long uintmax_t* + short* long* + o The format of the + number is the same as + expected by strtoul + with the value 8 for + the base argument + Matches an unsigned + hexadecimal integer. + + x, X The format of the + number is the same as + expected by strtoul + with the value 16 for + the base argument + Returns the number of + characters read so + far. + + No input is consumed. + n Does not increment the + assignment count. If + the specifier has + assignment-suppressing + operator defined, the + behavior is undefined + a, Matches a + A\fI(C++11)\fP floating-point number. + e, E N/A N/A float* double* N/A N/A N/A N/A long + f, F The format of the double* + g, G number is the same as + expected by strtof + Matches implementation + defined character + sequence defining a + pointer. + p N/A N/A void** N/A N/A N/A N/A N/A N/A + printf family of + functions should + produce the same + sequence using %p + format specifier + + For every conversion specifier other than n, the longest sequence of input + characters which does not exceed any specified field width and which either is + exactly what the conversion specifier expects or is a prefix of a sequence it would + expect, is what's consumed from the stream. The first character, if any, after this + consumed sequence remains unread. If the consumed sequence has length zero or if the + consumed sequence cannot be converted as specified above, the matching failure + occurs unless end-of-file, an encoding error, or a read error prevented input from + the stream, in which case it is an input failure. + + All conversion specifiers other than [, c, and n consume and discard all leading + whitespace characters (determined as if by calling isspace) before attempting to + parse the input. These consumed characters do not count towards the specified + maximum field width. + + The conversion specifiers lc, ls, and l[ perform multibyte-to-wide character + conversion as if by calling mbrtowc with an mbstate_t object initialized to zero + before the first character is converted. + + The conversion specifiers s and [ always store the null terminator in addition to + the matched characters. The size of the destination array must be at least one + greater than the specified field width. The use of %s or %[, without specifying the + destination array size, is as unsafe as std::gets. + + The correct conversion specifications for the fixed-width integer types (int8_t, + etc) are defined in the header (although SCNdMAX, SCNuMAX, etc is + synonymous with %jd, %ju, etc). + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple fields in the same "sink" variable. + + When parsing an incomplete floating-point value that ends in the exponent with no + digits, such as parsing "100er" with the conversion specifier %f, the sequence + "100e" (the longest prefix of a possibly valid floating-point number) is consumed, + resulting in a matching error (the consumed sequence cannot be converted to a + floating-point number), with "r" remaining. Some existing implementations do not + follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug + 1765. .SH Return value - Number of receiving arguments successfully assigned, or EOF if read failure occurs - before the first receiving argument was assigned. + Number of receiving arguments successfully assigned (which may be zero in case a + matching failure occurred before the first receiving argument was assigned), or EOF + if input failure occurs before the first receiving argument was assigned. + +.SH Complexity + + Not guaranteed. Notably, some implementations of std::sscanf are O(N), where N = + std::strlen(buffer) [1]. For performant string parsing, see std::from_chars. + +.SH Notes + + Because most conversion specifiers first consume all consecutive whitespace, code + such as + + std::scanf("%d", &a); + std::scanf("%d", &b); + + will read two integers that are entered on different lines (second %d will consume + the newline left over by the first) or on the same line, separated by spaces or tabs + (second %d will consume the spaces or tabs). + + The conversion specifiers that do not consume leading whitespace, such as %c, can be + made to do so by using a whitespace character in the format string: + + std::scanf("%d", &a); + std::scanf(" %c", &c); // ignore the endline after %d, then read a char + + Note that some implementations of std::sscanf involve a call to std::strlen, which + makes their runtime linear on the length of the entire string. This means that if + std::sscanf is called in a loop to repeatedly parse values from the front of a + string, your code might run in quadratic time (example). .SH Example - + // Run this code - #include #include #include - + #include + int main() { int i, j; float x, y; char str1[10], str2[4]; wchar_t warr[2]; - - char input[] = u8"25 54.32E-1 Thompson 56789 0123 56ß水"; - - // parse as follows: - // an integer, a floating-point value, a word, - // two-digit integer (digits 5 and 6) - // a floating-point value (digits 7, 8, 9) - // an integer which isn't stored anywhere - // a string of integers (digits 5 and 6) - // two wide characters, using multibyte to wide conversion - std::setlocale(LC_ALL, "en_US.utf8"); - int ret = std::sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc", - &i, &x, str1, &j, &y, str2, warr); - + + char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水"; + // parse as follows: + // %d: an integer + // %f: a floating-point value + // %9s: a string of at most 9 non-whitespace characters + // %2d: two-digit integer (digits 5 and 6) + // %f: a floating-point value (digits 7, 8, 9) + // %*d an integer which isn't stored anywhere + // ' ': all consecutive whitespace + // %3[0-9]: a string of at most 3 digits (digits 5 and 6) + // %2lc: two wide characters, using multibyte to wide conversion + const int ret = std::sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc", + &i, &x, str1, &j, &y, str2, warr); + std::cout << "Converted " << ret << " fields:\\n" - << "i = " << i << "\\nx = " << x << '\\n' - << "str1 = " << str1 << "\\nj = " << j << '\\n' - << "y = " << y << "\\nstr2 = " << str2 << '\\n' - << std::hex << "warr[0] = U+" << warr[0] - << " warr[1] = U+" << warr[1] << '\\n'; + "i = " << i << "\\n" + "x = " << x << "\\n" + "str1 = " << str1 << "\\n" + "j = " << j << "\\n" + "y = " << y << "\\n" + "str2 = " << str2 << std::hex << "\\n" + "warr[0] = U+" << (int)warr[0] << "\\n" + "warr[1] = U+" << (int)warr[1] << '\\n'; } .SH Output: @@ -196,23 +317,26 @@ format - the base argument j = 56 y = 789 str2 = 56 - warr[0] = U+df warr[1] = U+6c34 + warr[0] = U+df + warr[1] = U+6c34 .SH See also vscanf - vfscanf reads formatted input from stdin, a file stream or a buffer - vsscanf using variable argument list - \fI(C++11)\fP \fI(function)\fP + vfscanf reads formatted input from stdin, a file stream or a buffer + vsscanf using variable argument list + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP - fgets gets a character string from a file stream - \fI(function)\fP + fgets gets a character string from a file stream + \fI(function)\fP printf - fprintf prints formatted output to stdout, a file stream or a buffer - sprintf \fI(function)\fP + fprintf prints formatted output to stdout, a file stream or a buffer + sprintf \fI(function)\fP snprintf \fI(C++11)\fP + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP C documentation for scanf, fscanf, diff --git a/man/std::scoped_allocator_adaptor.3 b/man/std::scoped_allocator_adaptor.3 index a2d1ad757..7164d77e2 100644 --- a/man/std::scoped_allocator_adaptor.3 +++ b/man/std::scoped_allocator_adaptor.3 @@ -1,8 +1,14 @@ -.TH std::scoped_allocator_adaptor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor \- std::scoped_allocator_adaptor + .SH Synopsis Defined in header - template< class OuterAlloc, class... InnerAlloc > \fI(since C++11)\fP - class scoped_allocator_adaptor : public OuterAlloc; + template< class OuterAlloc, class... InnerAllocs > + + class scoped_allocator_adaptor \fI(since C++11)\fP + + : public OuterAlloc; The std::scoped_allocator_adaptor class template is an allocator which can be used with multilevel containers (vector of sets of lists of tuples of maps, etc). It is @@ -14,6 +20,12 @@ If there are more levels to the container than there are inner allocators, the last inner allocator is reused for all further nested containers. + The purpose of this adaptor is to correctly initialize stateful allocators in nested + containers, such as when all levels of a nested container must be placed in the same + shared memory segment. The adaptor's constructor takes the arguments for all + allocators in the list, and each nested container obtains its allocator's state from + the adaptor as needed. + For the purpose of scoped_allocator_adaptor, if the next inner allocator is A, any class T for which std::uses_allocator::value == true participates in the recursion as if it was a container. Additionally, std::pair is treated as such a @@ -22,20 +34,24 @@ Typical implementation holds an instance of a std::scoped_allocator_adaptor as a member object. + Note that std::pmr::polymorphic allocators propagate to nested containers following + uses-allocator construction and do not need (and do not work with) + std::scoped_allocator_adaptor. + .SH Member types - Type Definition - outer_allocator_type OuterAlloc - scoped_allocator_adaptor or, if - inner_allocator_type sizeof...(InnerAllocs) == 0, - scoped_allocator_adaptor - value_type std::allocator_traits::value_type - size_type std::allocator_traits::size_type - difference_type std::allocator_traits::difference_type - pointer std::allocator_traits::pointer - const_pointer std::allocator_traits::const_pointer - void_pointer std::allocator_traits::void_pointer - const_void_pointer std::allocator_traits::const_void_pointer + Type Definition + outer_allocator_type OuterAlloc + scoped_allocator_adaptor or, if + inner_allocator_type sizeof...(InnerAllocs) == 0, + scoped_allocator_adaptor + value_type std::allocator_traits::value_type + size_type std::allocator_traits::size_type + difference_type std::allocator_traits::difference_type + pointer std::allocator_traits::pointer + const_pointer std::allocator_traits::const_pointer + void_pointer std::allocator_traits::void_pointer + const_void_pointer std::allocator_traits::const_void_pointer propagate_on_container_copy_assignment std::true_type if @@ -50,10 +66,15 @@ std::true_type if std::allocator_traits::propagate_on_container_swap::value is true for at least one allocator A among OuterAlloc and InnerAlloc... + is_always_equal + + std::true_type if std::allocator_traits::is_always_equal::value is true for every + allocator A among OuterAlloc and InnerAlloc... rebind - template< class T > - struct rebind { + template< class T > + struct rebind + { typedef scoped_allocator_adaptor< std::allocator_traits::template rebind_alloc, InnerAllocs... @@ -64,41 +85,90 @@ creates a new scoped_allocator_adaptor constructor instance - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs a scoped_allocator_adaptor instance - \fI(public member function)\fP + \fI(public member function)\fP + operator= assigns a scoped_allocator_adaptor + \fI(public member function)\fP inner_allocator obtains an inner_allocator reference - \fI(public member function)\fP + \fI(public member function)\fP outer_allocator obtains an outer_allocator reference - \fI(public member function)\fP + \fI(public member function)\fP allocates uninitialized storage using the allocate outer allocator - \fI(public member function)\fP - deallocate allocates storage using the outer allocator - \fI(public member function)\fP + \fI(public member function)\fP + deallocate deallocates storage using the outer allocator + \fI(public member function)\fP returns the largest allocation size supported max_size by the outer allocator - \fI(public member function)\fP + \fI(public member function)\fP constructs an object in allocated storage, construct passing the inner allocator to its constructor if appropriate - \fI(public member function)\fP - destroy desrtucts an object in allocated storage - \fI(public member function)\fP + \fI(public member function)\fP + destroy destructs an object in allocated storage + \fI(public member function)\fP copies the state of scoped_allocator_adaptor select_on_container_copy_construction and all its allocators - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - operator== compares two scoped_allocator_adaptor instances - operator!= \fI(public member function)\fP + operator== compares two scoped_allocator_adaptor instances + operator!= \fI(function template)\fP + (removed in C++20) + + Deduction guides\fI(since C++17)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + namespace bi = boost::interprocess; + + template using alloc = bi::adaptive_pool; + using ipc_row = std::vector>; + using ipc_matrix = std::vector>>; + + int main () + { + bi::managed_shared_memory s(bi::create_only, "Demo", 65536); + + // create vector of vectors in shared memory + ipc_matrix v(s.get_segment_manager()); + + // for all these additions, the inner vectors obtain their allocator arguments + // from the outer vector's scoped_allocator_adaptor + v.resize(1); + v[0].push_back(1); + v.emplace_back(2); + std::vector local_row = {1, 2, 3}; + v.emplace_back(local_row.begin(), local_row.end()); + + bi::shared_memory_object::remove("Demo"); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2108 C++11 there was no way to show if is_always_equal + scoped_allocator_adaptor is stateless provided .SH See also allocator_traits provides information about allocator types - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP allocator the default allocator - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::scoped_allocator_adaptor::.3 b/man/std::scoped_allocator_adaptor::.3 new file mode 100644 index 000000000..4c4aa0977 --- /dev/null +++ b/man/std::scoped_allocator_adaptor::.3 @@ -0,0 +1,29 @@ +.TH std::scoped_allocator_adaptor:: 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor:: \- std::scoped_allocator_adaptor:: + +.SH Synopsis + + Defined in header + scoped_allocator_adaptor select_on_container_copy_construction() \fI(since C++11)\fP + const; + + Creates a new instance of std::scoped_allocator_adaptor, where the outer allocator + base class and each inner allocator subobject are obtained by calling + std::allocator_traits::select_on_container_copy_construction(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A new std::scoped_allocator_adaptor object, constructed from correctly copied + allocators. + +.SH See also + + obtains the allocator to use after copying a + select_on_container_copy_construction standard container + \fB[static]\fP \fI\fI(public static member\fP function of\fP + std::allocator_traits) diff --git a/man/std::scoped_allocator_adaptor::allocate.3 b/man/std::scoped_allocator_adaptor::allocate.3 index 77bc03450..38351f6c8 100644 --- a/man/std::scoped_allocator_adaptor::allocate.3 +++ b/man/std::scoped_allocator_adaptor::allocate.3 @@ -1,14 +1,22 @@ -.TH std::scoped_allocator_adaptor::allocate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::allocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::allocate \- std::scoped_allocator_adaptor::allocate + .SH Synopsis Defined in header - pointer allocate( size_type n ); \fB(1)\fP \fI(since C++11)\fP - pointer allocate( size_type n, const_void_pointer hint ); \fB(2)\fP \fI(since C++11)\fP + pointer allocate( size_type n ); \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] pointer allocate( size_type n ); \fI(since C++20)\fP + pointer allocate( size_type n, \fB(1)\fP \fI(since C++11)\fP + const_void_pointer hint ); \fB(2)\fP \fI(until C++20)\fP + [[nodiscard]] pointer allocate( size_type n, \fI(since C++20)\fP + const_void_pointer hint ); Uses the outer allocator to allocate uninitialized storage. - 1) Calls std::allocator_traits::allocate(outer_allocator(), n) + 1) Calls std::allocator_traits::allocate(outer_allocator(), n). 2) Additionally provides memory locality hint, by calling - std::allocator_traits::allocate(outer_allocator(), n, hint) + std::allocator_traits::allocate(outer_allocator(), n, hint). .SH Parameters @@ -17,11 +25,11 @@ .SH Return value - The pointer to the allocated storage + The pointer to the allocated storage. .SH See also allocate allocates uninitialized storage - \fI(public member function of std::allocator)\fP + \fI(public member function of std::allocator)\fP allocate allocates uninitialized storage using the allocator - \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP diff --git a/man/std::scoped_allocator_adaptor::construct.3 b/man/std::scoped_allocator_adaptor::construct.3 index c03ce5de5..206c9bc83 100644 --- a/man/std::scoped_allocator_adaptor::construct.3 +++ b/man/std::scoped_allocator_adaptor::construct.3 @@ -1,133 +1,136 @@ -.TH std::scoped_allocator_adaptor::construct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::construct \- std::scoped_allocator_adaptor::construct + .SH Synopsis Defined in header - template < class T, class... Args > \fB(1)\fP - void construct( T* p, Args&&... args ) + template< class T, class... Args > \fB(1)\fP + void construct( T* p, Args&&... args ); template< class T1, class T2, class... Args1, class... Args2 > void construct( std::pair* p, - std::piecewise_construct_t, \fB(2)\fP + std::piecewise_construct_t, \fB(2)\fP \fI(until C++20)\fP std::tuple x, - std::tuple y ) - template< class T1, class T2 > \fB(3)\fP - void construct( std::pair* p ) - template< class T1, class T2, class U, class V > \fB(4)\fP - void construct( std::pair* p, U&& x, V&& y ) - template< class T1, class T2, class U, class V > \fB(5)\fP - void construct( std::pair* p, const std::pair& xy ) - template< class T1, class T2, class U, class V > \fB(6)\fP + std::tuple y ); + template< class T1, class T2 > \fB(3)\fP \fI(until C++20)\fP + void construct( std::pair* p ); + template< class T1, class T2, class U, class V > \fB(4)\fP \fI(until C++20)\fP + void construct( std::pair* p, U&& x, V&& y ); + template< class T1, class T2, class U, class V > \fB(5)\fP \fI(until C++20)\fP + void construct( std::pair* p, const std::pair& xy ); + template< class T1, class T2, class U, class V > \fB(6)\fP \fI(until C++20)\fP void construct( std::pair* p, std::pair&& xy ); + template< class T1, class T2, class NonPair > \fB(7)\fP \fI(until C++20)\fP + void construct( std::pair* p, NonPair&& non_pair ); Constructs an object in allocated, but not initialized storage pointed to by p using OuterAllocator and the provided constructor arguments. If the object is of type that itself uses allocators, or if it is std::pair, passes InnerAllocator down to the constructed object. - First, determines the outermost allocator type OUTERMOST: it is the type that would - be returned by calling this->outer_allocator(), and then calling the - outer_allocator() member function recursively on the result of this call until - reaching the type that has no such member function. That type is the outermost - allocator. - - Then: - - 1) If std::uses_allocator::value==false (the type T does - not use allocators) and if std::is_constructible::value==true, then - calls - - std::allocator_traits::construct( OUTERMOST(*this), - p, - std::forward(args)... ); - - Otherwise, if std::uses_allocator::value==true (the type T - uses allocators, e.g. it is a container) and if std::is_constructible::value==true, then calls - - std::allocator_traits::construct( OUTERMOST(*this), - p, - std::allocator_arg, - inner_allocator(), - std::forward(args)... ); - - Otherwise, std::uses_allocator::value==true (the type T - uses allocators, e.g. it is a container) and if std::is_constructible::value==true, then calls - - std::allocator_traits::construct( OUTERMOST(*this), - p, - std::forward(args)..., - inner_allocator()); - - Otherwise, compilation error is issued because although std::uses_allocator - claimed that T is allocator-aware, it lacks either form of allocator-accepting - constructors. - - 2) First, if either T1 or T2 is allocator-aware, modifies the tuples x and y to - include the appropriate inner allocator, resulting in the two new tuples xprime and - yprime, according to the following three rules: - - 2a) if T1 is not allocator-aware (std::uses_allocator::value==false, then xprime is x, unmodified. (it is also - required that std::is_constructible::value==true) - + First, retrieve the outermost allocator OUTERMOST by calling + this->outer_allocator(), and then calling the outer_allocator() member function + recursively on the result of this call until reaching an allocator that has no such + member function. + + Define OUTERMOST_ALLOC_TRAITS(x) as + std::allocator_traits> + + 1) Creates an object of the given type T by means of uses-allocator construction at + the uninitialized memory location indicated by p, using OUTERMOST as the allocator. + After adjustment for uses-allocator convention expected by T's constructor, calls + OUTERMOST_ALLOC_TRAITS(*this)::construct. + + This overload participates in overload resolution only if U is not a \fI(until C++20)\fP + specialization of std::pair. + Equivalent to + std::apply( + + [p, this](auto&&... newargs) + { + OUTERMOST_ALLOC_TRAITS(*this)::construct( + OUTERMOST(*this), p, \fI(since C++20)\fP + std::forward(newargs)...); + }, + std::uses_allocator_construction_args( + inner_allocator(), + std::forward(args)... + ) + ); + + 2) First, if either T1 or T2 is allocator-aware, modifies the tuples x and y + to include the appropriate inner allocator, resulting in the two new tuples + xprime and yprime, according to the following three rules: + 2a) if T1 is not allocator-aware + (std::uses_allocator::value == false), then xprime + is std::tuple(std::move(x)). (It is also required that + std::is_constructible::value == true). 2b) if T1 is allocator-aware (std::uses_allocator::value==true), and its constructor takes an allocator tag - (std::is_constructible::value==true, then xprime is std::tuple_cat( - std::tuple( std::allocator_arg, - - inner_allocator() - ), - std::move(x)) - - 2c) if T1 is allocator-aware (std::uses_allocator::value==true), and its constructor takes the allocator as the - last argument (std::is_constructible::value==true), then xprime is std::tuple_cat(std::move(x), - std::tuple(inner_allocator())). + inner_allocator_type>::value == true), and its constructor takes an allocator + tag - Same rules apply to T2 and the replacement of y with yprime - - Once xprime and yprime are constructed (this also requires that all types in - Args1... and Args2... are CopyConstructible), constructs the pair p in allocated - storage by calling - - std::allocator_traits::construct( OUTERMOST(*this), - p, - std::piecewise_construct, - std::move(xprime), - std::move(yprime)); - - 3) Equivalent to construct(p, std::piecewise_construct, std::tuple<>(), - std::tuple<>()), that is, passes the inner allocator on to the pair's member types - if they accept them. + std::is_constructible::value == true, + then xprime is + std::tuple_cat(std::tuple( + std::allocator_arg, inner_allocator() + ), + std::tuple(std::move(x))) + 2c) if T1 is allocator-aware (std::uses_allocator::value == true), and its constructor takes the + allocator as the last argument + + std::is_constructible::value == true, + then xprime is + + std::tuple_cat(std::tuple(std::move(x)), + std::tuple(inner_allocator())). + Same rules apply to T2 and the replacement of y with yprime. + Once xprime and yprime are constructed, constructs the pair p in allocated + storage by calling (until + std::allocator_traits::construct(OUTERMOST, C++20) + p, + std::piecewise_construct, + std::move(xprime), + std::move(yprime)); + 3) Equivalent to + + construct(p, std::piecewise_construct, std::tuple<>(), std::tuple<>()), + + that is, passes the inner allocator on to the pair's member types if they + accept them. 4) Equivalent to + construct(p, std::piecewise_construct, + std::forward_as_tuple(std::forward(x)), - construct(p, std::piecewise_construct, std::forward_as_tuple(std::forward(x)), - std::forward_as_tuple(std::forward(y))) - 5) Equivalent to - construct(p, std::piecewise_construct, std::forward_as_tuple(xy.first), - std::forward_as_tuple(xy.second)) - + std::forward_as_tuple(xy.second)) 6) Equivalent to - construct(p, std::piecewise_construct, - std::forward_as_tuple(std::forward(xy.first)), - - std::forward_as_tuple(std::forward(xy.second))) + std::forward_as_tuple(std::forward(xy.first)), + std::forward_as_tuple(std::forward(xy.second))) + 7) This overload participates in overload resolution only if given the + exposition-only function template + + template + void /*deduce-as-pair*/(const std::pair&);, + /*deduce-as-pair*/(non_pair) is ill-formed when considered as an unevaluated + operand. + + Equivalent to construct(p, std::forward(non_pair));. .SH Parameters - p - pointer to allocated, but not initialized storage - args... - the constructor arguments to pass to the constructor of T - x - the constructor arguments to pass to the constructor of T1 - y - the constructor arguments to pass to the constructor of T2 - xy - the pair whose two members are the constructor arguments for T1 and T2 + p - pointer to allocated, but not initialized storage + args... - the constructor arguments to pass to the constructor of T + x - the constructor arguments to pass to the constructor of T1 + y - the constructor arguments to pass to the constructor of T2 + xy - the pair whose two members are the constructor arguments for T1 and T2 + non_pair - non-pair argument to convert to pair for further construction .SH Return value @@ -142,9 +145,23 @@ allocator-aware objects constructed through this function start constructing their own members. + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + first overload is mistakenly used constrained to not accept + LWG 2975 C++11 for pair construction in some pairs + cases + P0475R1 C++11 pair piecewise construction may transformed to tuples of + copy the arguments references to avoid copy + LWG 3525 C++11 no overload could handle non-pair reconstructing overload added + types convertible to pair + .SH See also - construct constructs an object in the allocated storage - \fB[static]\fP \fI(function template)\fP - construct constructs an object in allocated storage - \fI(public member function of std::allocator)\fP + construct constructs an object in the allocated storage + \fB[static]\fP \fI(function template)\fP + construct constructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP diff --git a/man/std::scoped_allocator_adaptor::deallocate.3 b/man/std::scoped_allocator_adaptor::deallocate.3 index 3ef0a0dfd..1ea19d273 100644 --- a/man/std::scoped_allocator_adaptor::deallocate.3 +++ b/man/std::scoped_allocator_adaptor::deallocate.3 @@ -1,10 +1,13 @@ -.TH std::scoped_allocator_adaptor::deallocate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::deallocate \- std::scoped_allocator_adaptor::deallocate + .SH Synopsis Defined in header - void deallocate( pointer p, size_type n ) \fI(since C++11)\fP + void deallocate( pointer p, size_type n ) noexcept; \fI(since C++11)\fP Uses the outer allocator to deallocate the storage referenced by p, by calling - std::allocator_traits::deallocate(outer_allocator(), p, n) + std::allocator_traits::deallocate(outer_allocator(), p, n). .SH Parameters @@ -15,15 +18,9 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also deallocate deallocates storage - \fI(public member function of std::allocator)\fP + \fI(public member function of std::allocator)\fP deallocate deallocates storage using the allocator - \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP diff --git a/man/std::scoped_allocator_adaptor::destroy.3 b/man/std::scoped_allocator_adaptor::destroy.3 index 874ca7c5b..9fa4df45a 100644 --- a/man/std::scoped_allocator_adaptor::destroy.3 +++ b/man/std::scoped_allocator_adaptor::destroy.3 @@ -1,4 +1,7 @@ -.TH std::scoped_allocator_adaptor::destroy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::destroy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::destroy \- std::scoped_allocator_adaptor::destroy + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -24,7 +27,7 @@ .SH See also - destroy destructs an object stored in the allocated storage - \fB[static]\fP \fI(function template)\fP - destroy destructs an object in allocated storage - \fI(public member function of std::allocator)\fP + destroy destructs an object stored in the allocated storage + \fB[static]\fP \fI(function template)\fP + destroy destructs an object in allocated storage + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP diff --git a/man/std::scoped_allocator_adaptor::inner_allocator.3 b/man/std::scoped_allocator_adaptor::inner_allocator.3 index 631ef28df..5036db5a1 100644 --- a/man/std::scoped_allocator_adaptor::inner_allocator.3 +++ b/man/std::scoped_allocator_adaptor::inner_allocator.3 @@ -1,8 +1,11 @@ -.TH std::scoped_allocator_adaptor::inner_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::inner_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::inner_allocator \- std::scoped_allocator_adaptor::inner_allocator + .SH Synopsis Defined in header - inner_allocator_type& inner_allocator() \fB(1)\fP \fI(since C++11)\fP - const inner_allocator_type& inner_allocator() const \fB(2)\fP \fI(since C++11)\fP + inner_allocator_type& inner_allocator() noexcept; \fB(1)\fP \fI(since C++11)\fP + const inner_allocator_type& inner_allocator() const noexcept; \fB(2)\fP \fI(since C++11)\fP Obtains a reference to the inner allocator used to declare this scoped_allocator_adaptor. @@ -21,14 +24,7 @@ A reference to the inner allocator, which is itself a std::scoped_allocator_adaptor. -.SH Exceptions - - 1-2) - noexcept specification: - noexcept - - .SH See also outer_allocator obtains an outer_allocator reference - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::scoped_allocator_adaptor::max_size.3 b/man/std::scoped_allocator_adaptor::max_size.3 index f178bd0a8..e5ae2c79b 100644 --- a/man/std::scoped_allocator_adaptor::max_size.3 +++ b/man/std::scoped_allocator_adaptor::max_size.3 @@ -1,10 +1,13 @@ -.TH std::scoped_allocator_adaptor::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::max_size \- std::scoped_allocator_adaptor::max_size + .SH Synopsis Defined in header - size_type max_size() const \fI(since C++11)\fP + size_type max_size() const; \fI(since C++11)\fP Reports the maximum allocation size supported by the outer allocator, by calling - std::allocator_traits::max_size(outer_allocator()) + std::allocator_traits::max_size(outer_allocator()). .SH Parameters @@ -16,7 +19,7 @@ .SH See also - max_size returns the largest supported allocation size - \fI(public member function of std::allocator)\fP - max_size returns the maximum object size supported by the allocator - \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP + max_size returns the largest supported allocation size + \fI(until C++20)\fP \fI(public member function of std::allocator)\fP + max_size returns the maximum object size supported by the allocator + \fB[static]\fP \fI(public static member function of std::allocator_traits)\fP diff --git a/man/std::scoped_allocator_adaptor::operator=.3 b/man/std::scoped_allocator_adaptor::operator=.3 new file mode 100644 index 000000000..636a2a0cf --- /dev/null +++ b/man/std::scoped_allocator_adaptor::operator=.3 @@ -0,0 +1,19 @@ +.TH std::scoped_allocator_adaptor::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::operator= \- std::scoped_allocator_adaptor::operator= + +.SH Synopsis + Defined in header + scoped_allocator_adaptor& operator=( const scoped_allocator_adaptor& other ) = \fB(1)\fP + default; + scoped_allocator_adaptor& operator=( scoped_allocator_adaptor&& other ) = \fB(2)\fP + default; + + 1) Explicitly defaulted copy assignment operator that copy assigns the base class + (OuterAlloc, the outer allocator) and all inner allocators. + 2) Explicitly defaulted move assignment operator that move assigns the base class + (OuterAlloc, the outer allocator) and all inner allocators. + +.SH Parameters + + other - another std::scoped_allocator_adaptor diff --git a/man/std::scoped_allocator_adaptor::outer_allocator.3 b/man/std::scoped_allocator_adaptor::outer_allocator.3 index 79dbe4524..6da769dec 100644 --- a/man/std::scoped_allocator_adaptor::outer_allocator.3 +++ b/man/std::scoped_allocator_adaptor::outer_allocator.3 @@ -1,14 +1,16 @@ -.TH std::scoped_allocator_adaptor::outer_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::outer_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::outer_allocator \- std::scoped_allocator_adaptor::outer_allocator + .SH Synopsis Defined in header - outer_allocator_type& outer_allocator() \fB(1)\fP \fI(since C++11)\fP - const outer_allocator_type& outer_allocator() const \fB(2)\fP \fI(since C++11)\fP + outer_allocator_type& outer_allocator() noexcept; \fB(1)\fP \fI(since C++11)\fP + const outer_allocator_type& outer_allocator() const noexcept; \fB(2)\fP \fI(since C++11)\fP Obtains a reference to the outer allocator used to declare this class. - 1) returns static_cast(*this) - - 2) returns static_cast(*this) + 1) Returns static_cast(*this). + 2) Returns static_cast(*this). .SH Parameters @@ -16,16 +18,9 @@ .SH Return value - A reference to OuterAlloc - -.SH Exceptions - - 1-2) - noexcept specification: - noexcept - + A reference to OuterAlloc. .SH See also inner_allocator obtains an inner_allocator reference - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::scoped_allocator_adaptor::scoped_allocator_adaptor.3 b/man/std::scoped_allocator_adaptor::scoped_allocator_adaptor.3 index 7c016caf9..d1aa81343 100644 --- a/man/std::scoped_allocator_adaptor::scoped_allocator_adaptor.3 +++ b/man/std::scoped_allocator_adaptor::scoped_allocator_adaptor.3 @@ -1,35 +1,54 @@ -.TH std::scoped_allocator_adaptor::scoped_allocator_adaptor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::scoped_allocator_adaptor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::scoped_allocator_adaptor \- std::scoped_allocator_adaptor::scoped_allocator_adaptor + .SH Synopsis Defined in header - scoped_allocator_adaptor() \fB(1)\fP \fI(since C++11)\fP + scoped_allocator_adaptor(); \fB(1)\fP \fI(since C++11)\fP template< class OuterA2 > - scoped_allocator_adaptor( OuterA2&& outerAlloc, const \fB(2)\fP \fI(since C++11)\fP - InnerAllocs&... innerAllocs) - scoped_allocator_adaptor( const scoped_allocator_adaptor& other ) \fB(3)\fP \fI(since C++11)\fP - scoped_allocator_adaptor( scoped_allocator_adaptor&& other ) \fB(4)\fP \fI(since C++11)\fP + + scoped_allocator_adaptor( \fB(2)\fP \fI(since C++11)\fP + OuterA2&& outerAlloc, const InnerAllocs&... innerAllocs + + ) noexcept; + scoped_allocator_adaptor( + + const scoped_allocator_adaptor& other \fB(3)\fP \fI(since C++11)\fP + + ) noexcept; + scoped_allocator_adaptor( + + scoped_allocator_adaptor&& other \fB(4)\fP \fI(since C++11)\fP + + ) noexcept; template< class OuterA2 > - scoped_allocator_adaptor( const scoped_allocator_adaptor& other ) + + scoped_allocator_adaptor( \fB(5)\fP \fI(since C++11)\fP + const scoped_allocator_adaptor& other + + ) noexcept; template< class OuterA2 > - scoped_allocator_adaptor( scoped_allocator_adaptor&& other ) + + scoped_allocator_adaptor( \fB(6)\fP \fI(since C++11)\fP + scoped_allocator_adaptor&& other + + ) noexcept; 1) Default constructor: value-initializes the OuterAlloc base class and the inner allocator member object, if used by the implementation. - 2) Constructs the base class OuterAlloc from std::forward(outerAlloc), and - the inner allocators with innerAllocs.... - + the inner allocators with innerAllocs.... This overload participates in overload + resolution only if std::is_constructible::value is true. 3) Copy-constructor: initializes each allocator from the corresponding allocator of - other - + other. 4) Move-constructor: moves each allocator from the corresponding allocator of other - into *this - - 5) Initializes each allocator from the corresponding allocator of other - + into *this. + 5) Initializes each allocator from the corresponding allocator of other. This + overload participates in overload resolution only if + std::is_constructible::value is true. 6) Initializes each allocator from the corresponding allocator of other, using move - semantics. + semantics. This overload participates in overload resolution only if + std::is_constructible::value is true. .SH Parameters @@ -37,17 +56,19 @@ innerAllocs... - constructor arguments for the inner allocators other - another std::scoped_allocator_adaptor -.SH Exceptions + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 2-6) - noexcept specification: - noexcept - + DR Applied to Behavior as published Correct behavior + LWG 2782 C++11 constructors taking OuterA2 weren't constraint added + constrained, interfering with metaprogramming .SH See also allocate allocates uninitialized storage using the outer allocator - \fI(public member function)\fP + \fI(public member function)\fP constructs an object in allocated storage, passing the inner allocator to construct its constructor if appropriate - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::scoped_allocator_adaptor::select_on_container_copy_construction.3 b/man/std::scoped_allocator_adaptor::select_on_container_copy_construction.3 deleted file mode 100644 index 43726a048..000000000 --- a/man/std::scoped_allocator_adaptor::select_on_container_copy_construction.3 +++ /dev/null @@ -1,25 +0,0 @@ -.TH std::scoped_allocator_adaptor::select_on_container_copy_construction 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - scoped_allocator_adaptor select_on_container_copy_construction() \fI(since C++11)\fP - const - - Creates a new instance of std::scoped_allocator_adaptor, where the outer allocator - base class and each inner allocator subobject are obtained by calling - std::allocator_traits::select_on_container_copy_construction(). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - A new std::scoped_allocator_adaptor object, constructed from correctly copied - allocators. - -.SH See also - - obtains the allocator to use after copying a - select_on_container_copy_construction standard container - \fB[static]\fP \fI\fI(public static member\fP function of\fP - std::allocator_traits) diff --git a/man/std::scoped_allocator_adaptor::~scoped_allocator_adaptor.3 b/man/std::scoped_allocator_adaptor::~scoped_allocator_adaptor.3 index f4b62e305..29d301782 100644 --- a/man/std::scoped_allocator_adaptor::~scoped_allocator_adaptor.3 +++ b/man/std::scoped_allocator_adaptor::~scoped_allocator_adaptor.3 @@ -1,4 +1,7 @@ -.TH std::scoped_allocator_adaptor::~scoped_allocator_adaptor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::scoped_allocator_adaptor::~scoped_allocator_adaptor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_allocator_adaptor::~scoped_allocator_adaptor \- std::scoped_allocator_adaptor::~scoped_allocator_adaptor + .SH Synopsis ~scoped_allocator_adaptor(); \fI(since C++11)\fP diff --git a/man/std::scoped_lock.3 b/man/std::scoped_lock.3 new file mode 100644 index 000000000..85c5afd45 --- /dev/null +++ b/man/std::scoped_lock.3 @@ -0,0 +1,172 @@ +.TH std::scoped_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_lock \- std::scoped_lock + +.SH Synopsis + Defined in header + template< class... MutexTypes > \fI(since C++17)\fP + class scoped_lock; + + The class scoped_lock is a mutex wrapper that provides a convenient RAII-style + mechanism for owning zero or more mutexes for the duration of a scoped block. + + When a scoped_lock object is created, it attempts to take ownership of the mutexes + it is given. When control leaves the scope in which the scoped_lock object was + created, the scoped_lock is destructed and the mutexes are released. If several + mutexes are given, deadlock avoidance algorithm is used as if by std::lock. + + The scoped_lock class is non-copyable. + +.SH Template parameters + + the types of the mutexes to lock. The types must meet the Lockable + MutexTypes - requirements unless sizeof...(MutexTypes)==1, in which case the only + type must meet BasicLockable + +.SH Member types + + Member type Definition + mutex_type (ifsizeof...(MutexTypes)==1) Mutex, the sole type in MutexTypes... + +.SH Member functions + + constructor constructs a scoped_lock, optionally locking the given mutexes + \fI(public member function)\fP + destructor destructs the scoped_lock object, unlocks the underlying mutexes + \fI(public member function)\fP + operator= not copy-assignable + [deleted] \fI(public member function)\fP + +.SH Notes + + A common beginner error is to "forget" to give a scoped_lock variable a name, e.g. + std::scoped_lock(mtx); (which default constructs a scoped_lock variable named mtx) + or std::scoped_lock{mtx}; (which constructs a prvalue object that is immediately + destroyed), thereby not actually constructing a lock that holds a mutex for the rest + of the scope. + + Feature-test macro Value Std Feature + __cpp_lib_scoped_lock 201703L \fI(C++17)\fP std::scoped_lock + +.SH Example + + The following example uses std::scoped_lock to lock pairs of mutexes without + deadlock and is RAII-style. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + using namespace std::chrono_literals; + + struct Employee + { + std::vector lunch_partners; + std::string id; + std::mutex m; + Employee(std::string id) : id(id) {} + std::string partners() const + { + std::string ret = "Employee " + id + " has lunch partners: "; + for (int count{}; const auto& partner : lunch_partners) + ret += (count++ ? ", " : "") + partner; + return ret; + } + }; + + void send_mail(Employee&, Employee&) + { + // Simulate a time-consuming messaging operation + std::this_thread::sleep_for(1s); + } + + void assign_lunch_partner(Employee& e1, Employee& e2) + { + static std::mutex io_mutex; + { + std::lock_guard lk(io_mutex); + std::cout << e1.id << " and " << e2.id << " are waiting for locks" << std::endl; + } + + { + // Use std::scoped_lock to acquire two locks without worrying about + // other calls to assign_lunch_partner deadlocking us + // and it also provides a convenient RAII-style mechanism + + std::scoped_lock lock(e1.m, e2.m); + + // Equivalent code 1 (using std::lock and std::lock_guard) + // std::lock(e1.m, e2.m); + // std::lock_guard lk1(e1.m, std::adopt_lock); + // std::lock_guard lk2(e2.m, std::adopt_lock); + + // Equivalent code 2 (if unique_locks are needed, e.g. for condition variables) + // std::unique_lock lk1(e1.m, std::defer_lock); + // std::unique_lock lk2(e2.m, std::defer_lock); + // std::lock(lk1, lk2); + { + std::lock_guard lk(io_mutex); + std::cout << e1.id << " and " << e2.id << " got locks" << std::endl; + } + e1.lunch_partners.push_back(e2.id); + e2.lunch_partners.push_back(e1.id); + } + + send_mail(e1, e2); + send_mail(e2, e1); + } + + int main() + { + Employee alice("Alice"), bob("Bob"), christina("Christina"), dave("Dave"); + + // Assign in parallel threads because mailing users about lunch assignments + // takes a long time + std::vector threads; + threads.emplace_back(assign_lunch_partner, std::ref(alice), std::ref(bob)); + threads.emplace_back(assign_lunch_partner, std::ref(christina), std::ref(bob)); + threads.emplace_back(assign_lunch_partner, std::ref(christina), std::ref(alice)); + threads.emplace_back(assign_lunch_partner, std::ref(dave), std::ref(bob)); + + for (auto& thread : threads) + thread.join(); + std::cout << alice.partners() << '\\n' << bob.partners() << '\\n' + << christina.partners() << '\\n' << dave.partners() << '\\n'; + } + +.SH Possible output: + + Alice and Bob are waiting for locks + Alice and Bob got locks + Christina and Bob are waiting for locks + Christina and Alice are waiting for locks + Dave and Bob are waiting for locks + Dave and Bob got locks + Christina and Alice got locks + Christina and Bob got locks + Employee Alice has lunch partners: Bob, Christina + Employee Bob has lunch partners: Alice, Dave, Christina + Employee Christina has lunch partners: Alice, Bob + Employee Dave has lunch partners: Bob + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2981 C++17 redundant deduction guide from removed + scoped_lock was provided + +.SH See also + + unique_lock implements movable mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + lock_guard implements a strictly scope-based mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::scoped_lock::scoped_lock.3 b/man/std::scoped_lock::scoped_lock.3 new file mode 100644 index 000000000..8408420e7 --- /dev/null +++ b/man/std::scoped_lock::scoped_lock.3 @@ -0,0 +1,38 @@ +.TH std::scoped_lock::scoped_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_lock::scoped_lock \- std::scoped_lock::scoped_lock + +.SH Synopsis + explicit scoped_lock( MutexTypes&... m ); \fB(1)\fP \fI(since C++17)\fP + scoped_lock( std::adopt_lock_t, MutexTypes&... m ); \fB(2)\fP \fI(since C++17)\fP + scoped_lock( const scoped_lock& ) = delete; \fB(3)\fP \fI(since C++17)\fP + + Acquires ownership of the given mutexes m. + + 1) If sizeof...(MutexTypes) == 0, does nothing. Otherwise, if sizeof...(MutexTypes) + == 1, effectively calls m.lock(). Otherwise, effectively calls std::lock(m...). + 2) Acquires ownership of the mutexes m... without attempting to lock any of them. + The behavior is undefined unless the current thread holds a non-shared lock (i.e., a + lock acquired by lock, try_lock, try_lock_for, or try_lock_until) on each object in + m.... + 3) Copy constructor is deleted. + + The behavior is undefined if m is destroyed before the scoped_lock object is. + +.SH Parameters + + m - mutexes to acquire ownership of + +.SH Exceptions + + 1) Throws any exceptions thrown by m.lock(). + 2) Throws nothing. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0739R0 C++17 adopt_lock_t parameter was last, impeding class moved to first + template argument deduction diff --git a/man/std::scoped_lock::~scoped_lock.3 b/man/std::scoped_lock::~scoped_lock.3 new file mode 100644 index 000000000..cf87590e6 --- /dev/null +++ b/man/std::scoped_lock::~scoped_lock.3 @@ -0,0 +1,11 @@ +.TH std::scoped_lock::~scoped_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::scoped_lock::~scoped_lock \- std::scoped_lock::~scoped_lock + +.SH Synopsis + ~scoped_lock(); \fI(since C++17)\fP + + Releases the ownership of the owned mutexes. + + Effectively calls unlock() on every mutex from the pack of mutexes passed to the + scoped_lock's constructor. diff --git a/man/std::search.3 b/man/std::search.3 index 73704f0f5..61177c6ca 100644 --- a/man/std::search.3 +++ b/man/std::search.3 @@ -1,25 +1,81 @@ -.TH std::search 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::search 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::search \- std::search + .SH Synopsis Defined in header template< class ForwardIt1, class ForwardIt2 > - ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, \fB(1)\fP + ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, \fB(1)\fP (constexpr since C++20) + + ForwardIt2 s_first, ForwardIt2 s_last + ); + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > + + ForwardIt1 search( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + + ForwardIt2 s_first, ForwardIt2 s_last + ); + template< class ForwardIt1, class ForwardIt2, class + BinaryPred > + + ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, \fB(3)\fP (constexpr since C++20) + ForwardIt2 s_first, ForwardIt2 + s_last, + + BinaryPred p ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + BinaryPred > + ForwardIt1 search( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first, ForwardIt1 last, + ForwardIt2 s_first, ForwardIt2 + s_last, - ForwardIt2 s_first, ForwardIt2 s_last ); - template< class ForwardIt1, class ForwardIt2, class BinaryPredicate > + BinaryPred p ); + template< class ForwardIt, class Searcher > + \fI(since C++17)\fP + ForwardIt search( ForwardIt first, ForwardIt last, \fB(5)\fP (constexpr since C++20) - ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, \fB(2)\fP + const Searcher& searcher ); - ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p ); + 1-4) Searches for the first occurrence of the sequence of elements [s_first, s_last) + in the range [first, last). + 1) Elements are compared using operator==. + 3) Elements are compared using the given binary predicate p. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if - Searches for the first occurrence of the subsequence of elements [s_first, s_last) - in the range [first, last - (s_last - s_first)). The first version uses operator== - to compare the elements, the second version uses the given binary predicate p. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + 5) Searches the range [first, last) for the pattern specified in the constructor of + searcher. + + The standard library provides the following searchers: + + default_searcher standard C++ library search algorithm + \fI(C++17)\fP implementation + \fI(class template)\fP + boyer_moore_searcher Boyer-Moore search algorithm \fI(since C++17)\fP + \fI(C++17)\fP implementation + \fI(class template)\fP + boyer_moore_horspool_searcher Boyer-Moore-Horspool search algorithm + \fI(C++17)\fP implementation + \fI(class template)\fP .SH Parameters first, last - the range of elements to examine s_first, s_last - the range of elements to search for + policy - the execution policy to use. See execution policy for details. + searcher - the searcher encapsulating the search algorithm and the pattern to + look for binary predicate which returns true if the elements should be treated as equal. @@ -27,125 +83,189 @@ the following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must - not modify the objects passed to it. + + p - While the signature does not need to have const &, the function + must not modify the objects passed to it and must be able to + accept all values of type (possibly const) Type1 and Type2 + regardless of value category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types ForwardIt1 and ForwardIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively. - - .SH Type requirements - - ForwardIt1, ForwardIt2 must meet the requirements of ForwardIterator. + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + - + BinaryPred must meet the requirements of BinaryPredicate. .SH Return value - Iterator to the beginning of first subsequence [s_first, s_last) in the range - [first, last - (s_last - s_first)). If no such subsequence is found, last is - returned. - If [s_first, s_last) is empty, first is returned. \fI(since C++11)\fP + 1-4) Iterator to the beginning of first occurrence of the sequence [s_first, s_last) + in the range [first, last). If no such occurrence is found, last is returned. + If [s_first, s_last) is empty, first is returned. + 5) searcher(first, last).first. .SH Complexity - At most S*N comparisons where S = std::distance(s_first, s_last) and N = - std::distance(first, last). + 1-4) Given \\(\\scriptsize N\\)N as std::distance(first, last) and \\(\\scriptsize S\\)S + as std::distance(s_first, s_last): + 1,2) At most \\(\\scriptsize N\\cdot S\\)N·S comparisons using operator==. + 3,4) At most \\(\\scriptsize N\\cdot S\\)N·S applications of the predicate p. + 5) Depends on searcher. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + search \fB(1)\fP template + constexpr //< since C++20 ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, - ForwardIt2 s_first, ForwardIt2 s_last) + ForwardIt2 s_first, ForwardIt2 s_last) { - for (; ; ++first) { + while (true) + { ForwardIt1 it = first; - for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) { - if (s_it == s_last) { + for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) + { + if (s_it == s_last) return first; - } - if (it == last) { + if (it == last) return last; - } - if (!(*it == *s_it)) { + if (!(*it == *s_it)) break; - } } + ++first; } } -.SH Second version - template + search \fB(3)\fP + template + constexpr //< since C++20 ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, - ForwardIt2 s_first, ForwardIt2 s_last, - BinaryPredicate p) + ForwardIt2 s_first, ForwardIt2 s_last, BinaryPred p) { - for (; ; ++first) { + while (true) + { ForwardIt1 it = first; - for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) { - if (s_it == s_last) { + for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) + { + if (s_it == s_last) return first; - } - if (it == last) { + if (it == last) return last; - } - if (!p(*it, *s_it)) { + if (!p(*it, *s_it)) break; - } } + ++first; } } .SH Example - + // Run this code - #include #include + #include + #include + #include #include - - template - bool in_quote(const Container& cont, const std::string& s) + #include + #include + #include + + using namespace std::literals; + + bool contains(const auto& cont, std::string_view s) { + // str.find() (or str.contains(), since C++23) can be used as well return std::search(cont.begin(), cont.end(), s.begin(), s.end()) != cont.end(); } - + int main() { - std::string str = "why waste time learning, when ignorance is instantaneous?"; - // str.find() can be used as well - std::cout << std::boolalpha << in_quote(str, "learning") << '\\n' - << in_quote(str, "lemming") << '\\n'; - - std::vector vec(str.begin(), str.end()); - std::cout << std::boolalpha << in_quote(vec, "learning") << '\\n' - << in_quote(vec, "lemming") << '\\n'; + const auto str{"why waste time learning, when ignorance is instantaneous?"sv}; + assert(contains(str, "learning")); + assert(not contains(str, "lemming")); + + const std::vector vec(str.begin(), str.end()); + assert(contains(vec, "learning")); + assert(not contains(vec, "leaning")); + + // The C++17 overload with searchers demo: + constexpr auto quote + { + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed " + "do eiusmod tempor incididunt ut labore et dolore magna aliqua"sv + }; + + for (const auto word : {"pisci"sv, "Pisci"sv}) + { + std::cout << "The string " << std::quoted(word) << ' '; + const std::boyer_moore_searcher searcher(word.begin(), word.end()); + const auto it = std::search(quote.begin(), quote.end(), searcher); + if (it == quote.end()) + std::cout << "not found\\n"; + else + std::cout << "found at offset " << std::distance(quote.begin(), it) << '\\n'; + } } .SH Output: - true - false - true - false + The string "pisci" found at offset 43 + The string "Pisci" not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1205 C++98 the return value was unclear if returns first in this + [s_first, s_last) is empty case + the resolution of LWG issue 1205 was + LWG 1338 C++98 incorrectly applied, returns last in this + making first to be returned if no case + occurence is found + LWG 2150 C++98 the condition of “sequence occurence” was corrected + incorrect .SH See also - find_end finds the last sequence of elements in a certain range - \fI(function template)\fP - includes returns true if one set is a subset of another - \fI(function template)\fP - equal determines if two sets of elements are the same - \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP + returns true if one sequence is a subsequence of + includes another + \fI(function template)\fP + equal determines if two sets of elements are the same + \fI(function template)\fP find - find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP \fI(C++11)\fP - returns true if one range is lexicographically less than - lexicographical_compare another - \fI(function template)\fP - mismatch finds the first position where two ranges differ - \fI(function template)\fP - searches for a number consecutive copies of an element in a - search_n range - \fI(function template)\fP + returns true if one range is lexicographically less + lexicographical_compare than another + \fI(function template)\fP + mismatch finds the first position where two ranges differ + \fI(function template)\fP + searches a range for a number of consecutive copies of + search_n an element + \fI(function template)\fP + default_searcher standard C++ library search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP + boyer_moore_searcher Boyer-Moore search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP + boyer_moore_horspool_searcher Boyer-Moore-Horspool search algorithm implementation + \fI(C++17)\fP \fI(class template)\fP + ranges::search searches for a range of elements + (C++20) (niebloid) diff --git a/man/std::search_n.3 b/man/std::search_n.3 index a67bcf75e..f95882bfe 100644 --- a/man/std::search_n.3 +++ b/man/std::search_n.3 @@ -1,25 +1,123 @@ -.TH std::search_n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::search_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::search_n \- std::search_n + .SH Synopsis Defined in header - template< class ForwardIt, class Size, class T > - ForwardIt1 search_n( ForwardIt first, ForwardIt last, Size count, const T& \fB(1)\fP - value ); - template< class ForwardIt, class Size, class T, class BinaryPredicate > + template< class ForwardIt, class + Size, class T > + (constexpr + ForwardIt search_n( ForwardIt since C++20) + first, ForwardIt last, (until C++26) + + Size count, + const T& value ); + template< class ForwardIt, class +.SH Size, + + class T = typename + std::iterator_traits + (since C++26) + ::value_type > + constexpr ForwardIt search_n( + ForwardIt first, ForwardIt last, + + + Size count, const T& value ); + template< class ExecutionPolicy, + + class ForwardIt, class + Size, class T > (since + ForwardIt search_n( C++17) + ExecutionPolicy&& policy, (until + ForwardIt C++26) + first, ForwardIt last, + + Size count, + const T& value ); + template< class ExecutionPolicy, - ForwardIt1 search_n( ForwardIt first, ForwardIt last, Size count, const T& \fB(2)\fP - value, + class ForwardIt, class +.SH Size, + class T = typename + std::iterator_traits + (since + ::value_type > C++26) + ForwardIt search_n( + ExecutionPolicy&& policy, + ForwardIt + first, ForwardIt last, - BinaryPredicate p ); + Size count, + const T& value ); + template< class ForwardIt, class \fB(1)\fP + Size, class T, class BinaryPred > + (constexpr + ForwardIt search_n( ForwardIt since C++20) + first, ForwardIt last, (until + C++26) + Size count, + const T& value, BinaryPred p ); + template< class ForwardIt, class +.SH Size, + \fB(2)\fP + class T = typename + std::iterator_traits + (since + ::value_type, C++26) + class BinaryPred > + constexpr ForwardIt search_n( + ForwardIt first, ForwardIt last, + + Size count, + const T& value, BinaryPred p ); + template< class ExecutionPolicy, + class ForwardIt, class Size, + \fB(3)\fP + class T, class + BinaryPred > (since + ForwardIt search_n( C++17) + ExecutionPolicy&& policy, (until + ForwardIt C++26) + first, ForwardIt last, + + Size count, + const T& value, BinaryPred p ); + template< class ExecutionPolicy, + class ForwardIt, class Size, \fB(4)\fP + + class T = typename + std::iterator_traits + + ::value_type, (since + class BinaryPred > C++26) + ForwardIt search_n( + ExecutionPolicy&& policy, + ForwardIt + first, ForwardIt last, + + Size count, + const T& value, BinaryPred p ); Searches the range [first, last) for the first sequence of count identical elements, - each equal to the given value value. The first version uses operator== to compare - the elements, the second version uses the given binary predicate p. + each equal to the given value. + + 1) Elements are compared using operator==. + 3) Elements are compared using the given binary predicate p. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters first, last - the range of elements to examine count - the length of the sequence to search for value - the value of the elements to search for + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -27,133 +125,198 @@ following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must not - modify the objects passed to it. + + p - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The type Type1 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to Type1. The type Type2 must be such that an object of type T can be implicitly converted to Type2. - - .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + BinaryPred must meet the requirements of BinaryPredicate. + - + Size must be convertible to an integral type. .SH Return value - Iterator to the beginning of the found sequence in the range [first, last). If no - such sequence is found, last is returned. + If count is positive, returns an iterator to the beginning of the first sequence + found in the range [first, last). Each iterator it in the sequence should satisfy + the following condition: + + 1,2) *it == value is true. + 3,4) p(*it, value) != false is true. + + If no such sequence is found, last is returned. + + If count is zero or negative, first is returned. .SH Complexity - At most last - first applications of the predicate. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) At most \\(\\scriptsize N\\)N comparisons using operator==. + 3,4) At most \\(\\scriptsize N\\)N applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - ForwardIt1 search_n(ForwardIt first, ForwardIt last, - Size count, const T& value) + search_n \fB(1)\fP + template::value_type> + ForwardIt search_n(ForwardIt first, ForwardIt last, Size count, const T& value) { - for(; first != last; ++first) { - if (!(*first == value)) { + if (count <= 0) + return first; + + for (; first != last; ++first) + { + if (!(*first == value)) continue; - } - + ForwardIt candidate = first; - Size cur_count = 0; - - while (true) { - ++cur_count; - if (cur_count == count) { - // success - return candidate; - } + + for (Size cur_count = 1; true; ++cur_count) + { + if (cur_count >= count) + return candidate; // success + ++first; - if (first == last) { - // exhausted the list - return last; - } - if (!(*first == value)) { - // too few in a row - break; - } + if (first == last) + return last; // exhausted the list + + if (!(*first == value)) + break; // too few in a row } } return last; } -.SH Second version - template - ForwardIt1 search_n(ForwardIt first, ForwardIt last, - Size count, const T& value, BinaryPredicate p) + search_n \fB(3)\fP + template::value_type, + class BinaryPred> + ForwardIt search_n(ForwardIt first, ForwardIt last, Size count, const T& value, + BinaryPred p) { - for(; first != last; ++first) { - if (!p(*first, value)) { + if (count <= 0) + return first; + + for (; first != last; ++first) + { + if (!p(*first, value)) continue; - } - + ForwardIt candidate = first; - Size cur_count = 0; - - while (true) { - ++cur_count; - if (cur_count == count) { - // success - return candidate; - } + + for (Size cur_count = 1; true; ++cur_count) + { + if (cur_count >= count) + return candidate; // success + ++first; - if (first == last) { - // exhausted the list - return last; - } - if (!p(*first, value)) { - // too few in a row - break; - } + if (first == last) + return last; // exhausted the list + + if (!p(*first, value)) + break; // too few in a row } } return last; } +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1-4) + .SH Example - + // Run this code - #include #include + #include + #include + #include #include - - template - bool consecutive_values(const Container& c, Size count, const T& v) + #include + + template + constexpr bool consecutive_values(const Container& c, Size count, const T& v) { - return std::search_n(std::begin(c),std::end(c),count,v) != std::end(c); + return std::search_n(std::begin(c), std::end(c), count, v) != std::end(c); } - + int main() { - const char sequence[] = "1001010100010101001010101"; - - std::cout << std::boolalpha; - std::cout << "Has 4 consecutive zeros: " - << consecutive_values(sequence,4,'0') << '\\n'; - std::cout << "Has 3 consecutive zeros: " - << consecutive_values(sequence,3,'0') << '\\n'; + constexpr char sequence[] = ".0_0.000.0_0."; + + static_assert(consecutive_values(sequence, 3, '0')); + + for (int n : {4, 3, 2}) + std::cout << std::boolalpha + << "Has " << n << " consecutive zeros: " + << consecutive_values(sequence, n, '0') << '\\n'; + + std::vector> nums{{4, 2}, {4, 2}, {1, 3}}; + #ifdef __cpp_lib_algorithm_default_value_type + auto it = std::search_n(nums.cbegin(), nums.cend(), 2, {4, 2}); + #else + auto it = std::search_n(nums.cbegin(), nums.cend(), 2, std::complex{4, 2}); + #endif + assert(it == nums.begin()); } .SH Output: Has 4 consecutive zeros: false Has 3 consecutive zeros: true + Has 2 consecutive zeros: true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was required to be EqualityComparable, removed the + LWG 283 C++98 but requirement + the value type of InputIt is not always T + the complexity upper limit was N·count, the upper limit is 0 + LWG 426 C++98 it is negative if count is negative if count is + non-positive + if count > 0, the complexity upper limit changed the upper + LWG 714 C++98 was N·count, but in limit to N in this + the worst case the number of case + comparisons/operations is always N + LWG 2150 C++98 the condition of “sequence occurence” was corrected + incorrect .SH See also - find_end finds the last sequence of elements in a certain range - \fI(function template)\fP + find_end finds the last sequence of elements in a certain range + \fI(function template)\fP find - find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if finds the first element satisfying specific criteria + find_if_not \fI(function template)\fP \fI(C++11)\fP - search searches for a range of elements - \fI(function template)\fP + search searches for a range of elements + \fI(function template)\fP + ranges::search_n searches for a number consecutive copies of an element in a range + (C++20) (niebloid) diff --git a/man/std::seed_seq.3 b/man/std::seed_seq.3 index 4a2337edf..24754fafe 100644 --- a/man/std::seed_seq.3 +++ b/man/std::seed_seq.3 @@ -1,4 +1,7 @@ -.TH std::seed_seq 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::seed_seq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::seed_seq \- std::seed_seq + .SH Synopsis Defined in header class seed_seq; \fI(since C++11)\fP @@ -16,42 +19,41 @@ .SH Member types - Member type Definition - result_type std::uint_least32_t + Member type Definition + result_type \fI(C++11)\fP std::uint_least32_t .SH Member functions - constructor constructs and seeds the std::seed_seq object - \fI(public member function)\fP - operator= not copy-assignable - (deleted) \fI(public member function)\fP - generate calculates the bias-eliminated, evenly distributed 32-bit values - \fI(public member function)\fP - size obtains the number of 32-bit values stored in std::seed_seq - \fI(public member function)\fP - param obtains the 32-bit values stored in std::seed_seq - \fI(public member function)\fP + constructor constructs and seeds the std::seed_seq object + \fI(C++11)\fP \fI(public member function)\fP + operator= seed_seq is not assignable + [deleted] \fI(C++11)\fP \fI(public member function)\fP + generate calculates the bias-eliminated, evenly distributed 32-bit values + \fI(C++11)\fP \fI(public member function)\fP + size obtains the number of 32-bit values stored in std::seed_seq + \fI(C++11)\fP \fI(public member function)\fP + param obtains the 32-bit values stored in std::seed_seq + \fI(C++11)\fP \fI(public member function)\fP .SH Example - + // Run this code - #include #include #include - + #include + int main() { - std::seed_seq seq{1,2,3,4,5}; + std::seed_seq seq{1, 2, 3, 4, 5}; std::vector seeds(10); seq.generate(seeds.begin(), seeds.end()); - for (std::uint32_t n : seeds) { + for (std::uint32_t n : seeds) std::cout << n << '\\n'; - } } -.SH Output: +.SH Possible output: 4204997637 4246533866 diff --git a/man/std::seed_seq::generate.3 b/man/std::seed_seq::generate.3 index f9f2d9103..6c74d02ca 100644 --- a/man/std::seed_seq::generate.3 +++ b/man/std::seed_seq::generate.3 @@ -1,4 +1,7 @@ -.TH std::seed_seq::generate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::seed_seq::generate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::seed_seq::generate \- std::seed_seq::generate + .SH Synopsis template< class RandomIt > \fI(since C++11)\fP void generate( RandomIt begin, RandomIt end ); @@ -13,38 +16,37 @@ the improvements made by Mutsuo Saito in 2007) * If begin == end, do nothing. Otherwise, - - * First, set each element of the output range to the value 0x8b8b8b8b - + * First, set each element of the output range to the value 0x8b8b8b8b. * Transform the elements of the output range according to the following algorithm: - For k = 0,..., m-1 + For k = 0,..., m - 1 - where m=max(s+1, n) - and n=end-begin - and s=v.size() + where m = max(s + 1, n) + and n = end - begin + and s = v.size() and v is the private container holding the values originally provided by the constructor of this seed_seq object, - 1. begin[k+p] += r1 - 2. begin[k+q] += r2 + 1. begin[k + p] += r1 + 2. begin[k + q] += r2 3. begin[k] = r2, - where p=(n-t)/2 - and q=p+t - and t=(n >= 623) ? 11 : (n >= 68) ? 7 : (n >= 39) ? 5 : (n >= 7) ? 3 : (n - 1) / 2 - and r1=1664525 * T(begin[k]^begin[k+p]^begin[k−1]) + where p = (n - t) / 2 + and q = p + t + and t = (n >= 623) ? 11 : (n >= 68) ? 7 : (n >= 39) ? 5 : (n >= 7) ? 3 : (n - 1) / 2 + and r1 = 1664525 * T(begin[k] ^ begin[k + p] ^ begin[k − 1]) and T(x) = x ^ (x >> 27) - and r2=r1+s if k==0, r2=r1 + k%n + v[k-1] if 0s. + and r2 = r1 + s if k == 0, r2 = r1 + k % n + v[k - 1] if 0 < k <=s, r2 = r1 + k % n + if k > s. - For k = m,..., m+n-1, + For k = m,..., m + n - 1, - 1. begin[k+p] ^= r3 - 2. begin[k+q] ^= r4 - 3. begin[k]=r4 + 1. begin[k + p] ^= r3 + 2. begin[k + q] ^= r4 + 3. begin[k] = r4 - where r3 = 1566083941 * T(begin[k]+begin[k+p]+begin[k-1]) - and r4=r3 - k%n + where r3 = 1566083941 * T(begin[k] + begin[k + p] + begin[k - 1]) + and r4 = r3 - k % n where all calculations are performed modulo 232 and where the indexing of the output range (begin[x]) is taken modulo n. @@ -56,11 +58,11 @@ for storing 32-bit values .SH Type requirements - - RandomIt must meet the requirements of RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. .SH Return value - none, the results are written to the [begin, end) range. + None, the results are written to the [begin, end) range. .SH Exceptions @@ -68,62 +70,132 @@ .SH Example - + // Run this code - #include + #include + #include + #include #include - + #include + + // Prototyping the main part of std::seed_seq... + struct seed_seq + { + std::vector v; + + seed_seq(std::initializer_list const il) : v{il} {} + + template + void generate(RandomIt first, RandomIt last) + { + if (first == last) + return; + // + // Assuming v = {1,2,3,4,5} and distance(first, last) == 10. + // + // Step 1: fill with 0x8b8b8b8b + // seeds = {2341178251, 2341178251, 2341178251, 2341178251, 2341178251, + // 2341178251, 2341178251, 2341178251, 2341178251, 2341178251 } + // + std::fill(first, last, 0x8b8b8b8b); + // + // Step 2: + // n = 10, s = 5, t = 3, p = 3, q = 6, m = 10 + // + const std::uint32_t n = last - first; + const std::uint32_t s = v.size(); + const std::uint32_t t = (n < 7) ? (n - 1) / 2 + : (n < 39) ? 3 + : (n < 68) ? 5 + : (n < 623) ? 7 + : 11; + const std::uint32_t p = (n - t) / 2; + const std::uint32_t q = p + t; + const std::uint32_t m = std::max(s + 1, n); + // + // First iteration, k = 0; r1 = 1371501266, r2 = 1371501271 + // + // seeds = {1371501271, 2341178251, 2341178251, 3712679517, 2341178251, + // 2341178251, 3712679522, 2341178251, 2341178251, 2341178251 } + // + // Iterations from k = 1 to k = 5 (r2 = r1 + k % n + v[k - 1]) + // + // r1 = 2786190137, 3204727651, 4173325571, 1979226628, 401983366 + // r2 = 2786190139, 3204727655, 4173325577, 1979226636, 401983376 + // + // seeds = {3350727907, 3188173515, 3204727655, 4173325577, 1979226636, + // 401983376, 3591037797, 2811627722, 1652921976, 2219536532 } + // + // Iterations from k = 6 to k = 9 (r2 = r1 + k % n) + // + // r1 = 2718637909, 1378394210, 2297813071, 1608643617 + // r2 = 2718637915, 1378394217, 2297813079, 1608643626 + // + // seeds = { 434154821, 1191019290, 3237041891, 1256752498, 4277039715, + // 2010627002, 2718637915, 1378394217, 2297813079, 1608643626 } + // + auto begin_mod = [first, n](std::uint32_t u) -> decltype(*first)& + { + return first[u % n]; // i.e. begin[x] is taken modulo n + }; + auto T = [](std::uint32_t x) { return x ^ (x >> 27); }; + + for (std::uint32_t k = 0, r1, r2; k < m; ++k) + { + r1 = 1664525 * T(begin_mod(k) ^ begin_mod(k + p) ^ begin_mod(k - 1)); + r2 = (k == 0) ? r1 + s + : (k <= s) ? r1 + k % n + v[k - 1] + : r1 + k % n; + begin_mod(k + p) += r1; + begin_mod(k + q) += r2; + begin_mod(k) = r2; + } + // + // Step 3 + // iterations from k = 10 to k = 19, using ^= to modify the output + // + // r1 = 1615303485, 3210438310, 893477041, 2884072672, 1918321961, + // r2 = 1615303485, 3210438309, 893477039, 2884072669, 1918321957 + // + // seeds = { 303093272, 3210438309, 893477039, 2884072669, 1918321957, + // 1117182731, 1772877958, 2669970405, 3182737656, 4094066935 } + // + // r1 = 423054846, 46783064, 3904109085, 1534123446, 1495905687 + // r2 = 423054841, 46783058, 3904109078, 1534123438, 1495905678 + // + // seeds = { 4204997637, 4246533866, 1856049002, 1129615051, 690460811, + // 1075771511, 46783058, 3904109078, 1534123438, 1495905678 } + // + for (std::uint32_t k = m, r3, r4; k < m + n; ++k) + { + r3 = 1566083941 * T(begin_mod(k) + begin_mod(k + p) + begin_mod(k - 1)); + r4 = r3 - k % n; + begin_mod(k+p) ^= r3; + begin_mod(k+q) ^= r4; + begin_mod(k) = r4; + } + } + }; + int main() { - std::seed_seq seq({1,2,3,4,5}); - std::vector seeds(10); + const auto input = std::initializer_list{1,2,3,4,5}; + const auto output_size = 10; + + // using std version of seed_seq + std::seed_seq seq(input); + std::vector seeds(output_size); seq.generate(seeds.begin(), seeds.end()); - // Step 1: fill with 0x8b8b8b8b - // seeds = {2341178251, 2341178251, 2341178251, 2341178251, 2341178251, - // 2341178251, 2341178251, 2341178251, 2341178251, 2341178251 } - // - // Step 2: - // n = 10, s = 5, t = 3, p = 3, q = 6, m = 10 - // - // First iteration, k = 0; r1 = 1371501266, r2 = 1371501271 - // - // seeds = {1371501271, 2341178251, 2341178251, 3712679517, 2341178251, - // 2341178251, 3712679522, 2341178251, 2341178251, 2341178251 } - // - // Iterations from k = 1 to k = 5 (r2 = r1 + k%n + v[k-1]) - // - // r1 = 2786190137, 3204727651, 4173325571, 1979226628, 401983366 - // r2 = 2786190139, 3204727655, 4173325577, 1979226636, 401983376 - // - // seeds = {3350727907, 3188173515, 3204727655, 4173325577, 1979226636, - // 401983376, 3591037797, 2811627722, 1652921976, 2219536532 } - // - // Iterations from k = 6 to k = 9 (r2 = r1 + k%n) - // - // r1 = 2718637909, 1378394210, 2297813071, 1608643617 - // r2 = 2718637915, 1378394217, 2297813079, 1608643626 - // - // seeds = { 434154821, 1191019290, 3237041891, 1256752498, 4277039715, - // 2010627002, 2718637915, 1378394217, 2297813079, 1608643626 } - // - // Step 3 - // iterations from k = 10 to k = 19, using ^= to modify the output - // - // r1 = 1615303485, 3210438310, 893477041, 2884072672, 1918321961, - // r2 = 1615303485, 3210438309, 893477039, 2884072669, 1918321957 - // - // seeds = { 303093272, 3210438309, 893477039, 2884072669, 1918321957, - // 1117182731, 1772877958, 2669970405, 3182737656, 4094066935 } - // - // r1 = 423054846, 46783064, 3904109085, 1534123446, 1495905687 - // r2 = 423054841, 46783058, 3904109078, 1534123438, 1495905678 - // - // seeds = { 4204997637, 4246533866, 1856049002, 1129615051, 690460811, - // 1075771511, 46783058, 3904109078, 1534123438, 1495905678 } - - for(std::uint32_t n : seeds) + for (const std::uint32_t n : seeds) std::cout << n << '\\n'; + + // using custom version of seed_seq + seed_seq seq2(input); + std::vector seeds2(output_size); + seq2.generate(seeds2.begin(), seeds2.end()); + + assert(seeds == seeds2); } .SH Output: diff --git a/man/std::seed_seq::param.3 b/man/std::seed_seq::param.3 index b7b29e3ba..9167812f1 100644 --- a/man/std::seed_seq::param.3 +++ b/man/std::seed_seq::param.3 @@ -1,4 +1,7 @@ -.TH std::seed_seq::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::seed_seq::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::seed_seq::param \- std::seed_seq::param + .SH Synopsis template< class OutputIt > \fI(since C++11)\fP void param( OutputIt dest ) const; @@ -7,11 +10,11 @@ .SH Parameters - dest - output iterator such that the expression *dest=rt is valid for a value rt of - result_type + dest - output iterator such that the expression *dest = rt is valid for a value rt + of result_type .SH Type requirements - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. .SH Return value @@ -23,12 +26,13 @@ .SH Example - + // Run this code - #include #include #include + #include + int main() { std::seed_seq s1 = {-1, 0, 1}; diff --git a/man/std::seed_seq::seed_seq.3 b/man/std::seed_seq::seed_seq.3 index 33396cd7b..cc106af45 100644 --- a/man/std::seed_seq::seed_seq.3 +++ b/man/std::seed_seq::seed_seq.3 @@ -1,6 +1,9 @@ -.TH std::seed_seq::seed_seq 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::seed_seq::seed_seq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::seed_seq::seed_seq \- std::seed_seq::seed_seq + .SH Synopsis - seed_seq(); \fB(1)\fP \fI(since C++11)\fP + seed_seq() noexcept; \fB(1)\fP \fI(since C++11)\fP seed_seq( const seed_seq& ) = delete; \fB(2)\fP \fI(since C++11)\fP template< class InputIt > \fB(3)\fP \fI(since C++11)\fP seed_seq( InputIt begin, InputIt end ); @@ -13,32 +16,34 @@ 3) Constructs a std::seed_seq with the initial seed sequence obtained by iterating over the range [begin, end) and copying the values obtained by dereferencing the iterator, modulo 232 - (that is, the lower 32 bits are copied) + (that is, the lower 32 bits are copied). 4) Equivalent to seed_seq(il.begin(), il.end()). This constructor enables - list-initialization. + list-initialization from the list of seed values. This overload participates in + overload resolution only if T is an integer type. .SH Parameters begin, end - the initial seed sequence represented as a pair of input iterators whose std::iterator_traits<>::value_type is an integer type - il - std::initializer_list of objects of integer type, providing the iniial + il - std::initializer_list of objects of integer type, providing the initial seed sequence .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Exceptions - 1) Does not throw + 3,4) Throws std::bad_alloc on allocation failure. .SH Example - + // Run this code + #include #include #include - #include + int main() { std::seed_seq s1; // default-constructible @@ -50,3 +55,14 @@ std::istream_iterator beg(buf), end; std::seed_seq s5(beg, end); // even stream input iterators } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default constructor never fails but might + LWG 3422 C++11 be not noexcept; made noexcept; + the initializer list constructor disabled constrained + list-initialization from iterator pairs diff --git a/man/std::seed_seq::size.3 b/man/std::seed_seq::size.3 index f923ba15b..a8796886a 100644 --- a/man/std::seed_seq::size.3 +++ b/man/std::seed_seq::size.3 @@ -1,6 +1,9 @@ -.TH std::seed_seq::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::seed_seq::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::seed_seq::size \- std::seed_seq::size + .SH Synopsis - std::size_t size() const \fI(since C++11)\fP + std::size_t size() const noexcept; \fI(since C++11)\fP Returns the size of the stored initial seed sequence. @@ -16,17 +19,14 @@ Constant time. -.SH Exeptions - - Does not throw - .SH Example - + // Run this code - #include #include + #include + int main() { std::seed_seq s1 = {-1, 0, 1}; @@ -36,3 +36,11 @@ .SH Output: 3 + + Defect report + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2440 C++11 seed_seq::size was not required to be noexcept required diff --git a/man/std::semiregular.3 b/man/std::semiregular.3 new file mode 100644 index 000000000..e2c9ee6ac --- /dev/null +++ b/man/std::semiregular.3 @@ -0,0 +1,75 @@ +.TH std::semiregular 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::semiregular \- std::semiregular + +.SH Synopsis + Defined in header + template< class T > + concept semiregular = std::copyable && \fI(since C++20)\fP + std::default_initializable; + + The semiregular concept specifies that a type is both copyable and default + constructible. It is satisfied by types that behave similarly to built-in types like + int, except that they need not support comparison with ==. + +.SH Example + + +// Run this code + + #include + #include + + template + // Credit Alexander Stepanov + // concepts are requirements on T + // Requirement on T: T is semiregular + // T a(b); or T a = b; => copy constructor + // T a; => default constructor + // a = b; => assignment + struct Single + { + T value; + // Aggregation initialization for Single behaves like following constructor: + // explicit Single(const T& x) : value(x) {} + + // Implicitly declared special member functions behave like following definitions, + // except that they may have additional properties: + // Single(const Single& x) : value(x.value) {} + // Single() {} + // ~Single() {} + // Single& operator=(const Single& x) { value = x.value; return *this; } + // comparison operator is not defined; it is not required by `semiregular` concept + // bool operator==(Single const& other) const = delete; + }; + + void print(std::semiregular auto x) + { + std::cout << x.value << '\\n'; + } + + int main() + { + Single myInt1{4}; // aggregate initialization: myInt1.value = 4 + Single myInt2(myInt1); // copy constructor + Single myInt3; // default constructor + myInt3 = myInt2; // copy assignment operator + // myInt1 == myInt2; // Error: operator== is not defined + + print(myInt1); // ok: Single is a `semiregular` type + print(myInt2); + print(myInt3); + + } // Single variables are destroyed here + +.SH Output: + + 4 + 4 + 4 + +.SH See also + + regular specifies that a type is regular, that is, it is both semiregular and + (C++20) equality_comparable + (concept) diff --git a/man/std::sentinel_for.3 b/man/std::sentinel_for.3 new file mode 100644 index 000000000..8909874b0 --- /dev/null +++ b/man/std::sentinel_for.3 @@ -0,0 +1,50 @@ +.TH std::sentinel_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sentinel_for \- std::sentinel_for + +.SH Synopsis + Defined in header + template< class S, class I > + + concept sentinel_for = + std::semiregular && \fI(since C++20)\fP + std::input_or_output_iterator && + + __WeaklyEqualityComparableWith; + + The sentinel_for concept specifies the relationship between an + input_or_output_iterator type and a semiregular type whose values denote a range. + The exposition-only concept __WeaklyEqualityComparableWith is described in + equality_comparable. + + Semantic requirements + + Let s and i be values of type S and I, respectively, such that [i, s) denotes a + range. sentinel_for is modeled only if: + + * i == s is well-defined. + * If bool(i != s) then i is dereferenceable and [++i, s) denotes a range. + * std::assignable_from is either modeled or not satisfied. + + The domain of == can change over time. Given an iterator i and sentinel s such that + [i, s) denotes a range and i != s, [i, s) is not required to continue to denote a + range after incrementing any iterator equal to i (and so i == s is no longer + required to be well-defined after such an increment). + +.SH Notes + + A sentinel type and its corresponding iterator type are not required to model + equality_comparable_with, because the sentinel type may not be comparable with + itself, and they are not required to have a common reference type. + + It has been permitted to use a sentinel type different from the iterator type in the + range-based for loop since C++17. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3453 C++20 semantic requirements for sentinel_for were too strengthened + loose for ranges::advance diff --git a/man/std::set.3 b/man/std::set.3 index e52f5719c..f66267685 100644 --- a/man/std::set.3 +++ b/man/std::set.3 @@ -1,117 +1,206 @@ -.TH std::set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set \- std::set + .SH Synopsis Defined in header template< class Key, - class Compare = std::less, + class Compare = std::less, \fB(1)\fP class Allocator = std::allocator > class set; + namespace pmr { + + template< + class Key, + class Compare = std::less \fB(2)\fP \fI(since C++17)\fP + > using set = std::set>; + + } std::set is an associative container that contains a sorted set of unique objects of type Key. Sorting is done using the key comparison function Compare. Search, removal, and insertion operations have logarithmic complexity. Sets are usually - implemented as red-black trees. + implemented as Red–black trees. + + Everywhere the standard library uses the Compare requirements, uniqueness is + determined by using the equivalence relation. In imprecise terms, two objects a and + b are considered equivalent if neither compares less than the other: !comp(a, b) && + !comp(b, a). std::set meets the requirements of Container, AllocatorAwareContainer, AssociativeContainer and ReversibleContainer. +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - value_type Key - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - key_compare Compare - value_compare Compare - allocator_type Allocator - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP - pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP - const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator BidirectionalIterator \fI(until C++11)\fP - Constant bidirectional iterator \fI(since C++11)\fP - const_iterator Constant bidirectional iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + Member type Definition + key_type Key + value_type Key + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + key_compare Compare + value_compare Compare + allocator_type Allocator + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer (until + C++11) + const_pointer std::allocator_traits::const_pointer (since + C++11) + + + iterator Constant LegacyBidirectionalIterator to value_type + const_iterator LegacyBidirectionalIterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node + type describing the result of inserting a node_type, a + specialization of + + template + struct /*unspecified*/ + insert_return_type (since { + C++17) Iter position; + bool inserted; + NodeType node; + }; + instantiated with template arguments iterator and + node_type. .SH Member functions constructor constructs the set - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the set - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP + \fI(C++11)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + \fI(C++11)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP .SH Observers key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the set - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two sets + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::set) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase_if(std::set) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP .SH Notes - The member types iterator and const_iterator may be aliases to the same type. Since - iterator is convertible to const_iterator, const_iterator should be used in function - parameter lists to avoid violations of the One Definition Rule. + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 103 C++98 iterator allows modification of keys iterator made constant + Key was not required to be + LWG 230 C++98 CopyConstructible Key is also required to + (a key of type Key might not be able to be CopyConstructible + be constructed) + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::set::begin,std::set::cbegin.3 b/man/std::set::begin,std::set::cbegin.3 index 636cc01cb..91b7f9543 100644 --- a/man/std::set::begin,std::set::cbegin.3 +++ b/man/std::set::begin,std::set::cbegin.3 @@ -1,12 +1,15 @@ -.TH std::set::begin,std::set::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::begin,std::set::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::begin,std::set::cbegin \- std::set::begin,std::set::cbegin + .SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin(); \fB(1)\fP (noexcept since C++11) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the set. - If the container is empty, the returned iterator will be equal to end(). + If the set is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,20 +19,49 @@ .SH Return value - Iterator to the first element + Iterator to the first element. -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Constant. -.SH Complexity +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::set set{3, 1, 4, 1, 5, 9, 2, 6, 5}; + std::for_each(set.cbegin(), set.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: - Constant + 1 2 3 4 5 6 9 .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::set::clear.3 b/man/std::set::clear.3 index cf8ca95a6..512045d4e 100644 --- a/man/std::set::clear.3 +++ b/man/std::set::clear.3 @@ -1,11 +1,14 @@ -.TH std::set::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::clear \- std::set::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterator remains valid. .SH Parameters @@ -15,18 +18,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::set& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::set container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + LWG 224 C++98 the complexity was log(size()) + N, but N corrected to 'linear in + was not defined size()' .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::set::contains.3 b/man/std::set::contains.3 new file mode 100644 index 000000000..413ed5d2e --- /dev/null +++ b/man/std::set::contains.3 @@ -0,0 +1,60 @@ +.TH std::set::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::contains \- std::set::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::set example{1, 2, 3, 4}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::set::count.3 b/man/std::set::count.3 index 492de0fce..d4fa9b1a9 100644 --- a/man/std::set::count.3 +++ b/man/std::set::count.3 @@ -1,15 +1,21 @@ -.TH std::set::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::count \- std::set::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP template< class K > \fB(2)\fP \fI(since C++14)\fP size_type count( const K& x ) const; - 1) Returns the number of elements with key key, which is either 1 or 0 since this - container does not allow duplicates + Returns the number of elements with key that compares equivalent to the specified + argument. + + 1) Returns the number of elements with key key. This is either 1 or 0 since this + container does not allow duplicates. 2) Returns the number of elements with key that compares equivalent to the value x. - These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -18,15 +24,73 @@ .SH Return value - Number of elements with key key, that is either 1 or 0 + Number of elements with key that compares equivalent to key or x, which, for + overload \fB(1)\fP, is either 1 or 0. .SH Complexity - Logarithmic in the size of the container. + Logarithmic in the size of the container plus linear in the number of elements + found. + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + struct S + { + int x; + S(int i) : x{i} { std::cout << "S{" << i << "} "; } + bool operator<(S const& s) const { return x < s.x; } + }; + + struct R + { + int x; + R(int i) : x{i} { std::cout << "R{" << i << "} "; } + bool operator<(R const& r) const { return x < r.x; } + }; + + bool operator<(R const& r, int i) { return r.x < i; } + bool operator<(int i, R const& r) { return i < r.x; } + + int main() + { + std::set t{3, 1, 4, 1, 5}; + std::cout << t.count(1) << ", " << t.count(2) << ".\\n"; + + std::set s{3, 1, 4, 1, 5}; + std::cout << ": " << s.count(1) << ", " << s.count(2) << ".\\n"; + // Two temporary objects S{1} and S{2} were created. + // Comparison function object is defaulted std::less, + // which is not transparent (has no is_transparent member type). + + std::set> r{3, 1, 4, 1, 5}; + std::cout << ": " << r.count(1) << ", " << r.count(2) << ".\\n"; + // C++14 heterogeneous lookup; temporary objects were not created. + // Comparator std::less has predefined is_transparent. + } + +.SH Output: + + 1, 0. + S{3} S{1} S{4} S{1} S{5} : S{1} 1, S{2} 0. + R{3} R{1} R{4} R{1} R{5} : 1, 0. .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::set::emplace.3 b/man/std::set::emplace.3 index 03d977262..719a670d1 100644 --- a/man/std::set::emplace.3 +++ b/man/std::set::emplace.3 @@ -1,15 +1,21 @@ -.TH std::set::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::emplace \- std::set::emplace + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - std::pair emplace( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + std::pair emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args, + if there is no element with the key in the container. - Inserts a new element into the container by constructing it in-place with the given - args. + The constructor of the new element is called with exactly the same arguments as + supplied to emplace, forwarded via std::forward(args).... The element may be + constructed even if there already is an element with the key in the container, in + which case the newly constructed element will be destroyed immediately. Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element is called - with exactly the same arguments as supplied to emplace, forwarded via - std::forward(args).... + unnecessary copy or move operations. No iterators or references are invalidated. @@ -19,13 +25,14 @@ .SH Return value - Returns a pair consisting of a bool denoting whether the insertion took place and an - iterator to the inserted element, or the already-existing element if no insertion - happened. + A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -33,16 +40,92 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + class Dew + { + private: + int a, b, c; + + public: + Dew(int _a, int _b, int _c) + : a(_a), b(_b), c(_c) + {} + + bool operator<(const Dew& other) const + { + return (a < other.a) || + (a == other.a && b < other.b) || + (a == other.a && b == other.b && c < other.c); + } + }; + + constexpr int nof_operations{101}; + + std::size_t set_emplace() + { + std::set set; + for (int i = 0; i < nof_operations; ++i) + for (int j = 0; j < nof_operations; ++j) + for (int k = 0; k < nof_operations; ++k) + set.emplace(i, j, k); + + return set.size(); + } + + std::size_t set_insert() + { + std::set set; + for (int i = 0; i < nof_operations; ++i) + for (int j = 0; j < nof_operations; ++j) + for (int k = 0; k < nof_operations; ++k) + set.insert(Dew(i, j, k)); + + return set.size(); + } + + void time_it(std::function set_test, std::string what = "") + { + const auto start = std::chrono::system_clock::now(); + const auto the_size = set_test(); + const auto stop = std::chrono::system_clock::now(); + const std::chrono::duration time = stop - start; + if (!what.empty() && the_size) + std::cout << std::fixed << std::setprecision(2) + << time << " for " << what << '\\n'; + } + + int main() + { + time_it(set_insert, "cache warming..."); + time_it(set_insert, "insert"); + time_it(set_insert, "insert"); + time_it(set_emplace, "emplace"); + time_it(set_emplace, "emplace"); + } + +.SH Possible output: + + 630.58ms for cache warming... + 577.16ms for insert + 560.84ms for insert + 547.10ms for emplace + 549.44ms for emplace .SH See also emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::set::emplace_hint.3 b/man/std::set::emplace_hint.3 index 39a10c15f..f06371e64 100644 --- a/man/std::set::emplace_hint.3 +++ b/man/std::set::emplace_hint.3 @@ -1,37 +1,143 @@ -.TH std::set::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::emplace_hint \- std::set::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container as close as possible to the position just + before hint. - The constructor of the element is called with exactly the same arguments as supplied - to the function, forwarded with std::forward(args).... + The constructors of the key and mapped value are called with exactly the same + arguments as supplied to the function, forwarded with std::forward(args).... No iterators or references are invalidated. .SH Parameters - hint - iterator, used as a suggestion as to where to insert the new element + hint - iterator to the position before which the new element will be inserted args - arguments to forward to the constructor of the element .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element, or to the element that prevented the insertion. + +.SH Exceptions - If the insertion failed because the element already exists, returns an iterator to - the already existing element with the equivalent key. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Logarithmic in the size of the container in general, but amortized constant if the new element is inserted just before hint. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const int n_operations = 100'500'0; + + std::size_t set_emplace() + { + std::set set; + for (int i = 0; i < n_operations; ++i) + set.emplace(i); + return set.size(); + } + + std::size_t set_emplace_hint() + { + std::set set; + auto it = set.begin(); + for (int i = 0; i < n_operations; ++i) + { + set.emplace_hint(it, i); + it = set.end(); + } + return set.size(); + } + + std::size_t set_emplace_hint_wrong() + { + std::set set; + auto it = set.begin(); + for (int i = n_operations; i > 0; --i) + { + set.emplace_hint(it, i); + it = set.end(); + } + return set.size(); + } + + std::size_t set_emplace_hint_corrected() + { + std::set set; + auto it = set.begin(); + for (int i = n_operations; i > 0; --i) + { + set.emplace_hint(it, i); + it = set.begin(); + } + return set.size(); + } + + std::size_t set_emplace_hint_closest() + { + std::set set; + auto it = set.begin(); + for (int i = 0; i < n_operations; ++i) + it = set.emplace_hint(it, i); + return set.size(); + } + + double time_it(std::function set_test, + const char* what = nullptr, + double ratio = 0.0) + { + const auto start = std::chrono::system_clock::now(); + const std::size_t setsize = set_test(); + const auto stop = std::chrono::system_clock::now(); + const std::chrono::duration time = stop - start; + if (what != nullptr && setsize > 0) + std::cout << std::setw(8) << time << " for " << what << " (ratio: " + << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\\n"; + return time.count(); + } + + int main() + { + std::cout << std::fixed << std::setprecision(2); + time_it(set_emplace); // cache warmup + const auto x = time_it(set_emplace, "plain emplace"); + time_it(set_emplace_hint, "emplace with correct hint", x); + time_it(set_emplace_hint_wrong, "emplace with wrong hint", x); + time_it(set_emplace_hint_corrected, "corrected emplace", x); + time_it(set_emplace_hint_closest, "emplace using returned iterator", x); + } + +.SH Possible output: + + 392.25ms for plain emplace (ratio: 1.00) + 97.15ms for emplace with correct hint (ratio: 4.04) + 387.52ms for emplace with wrong hint (ratio: 1.01) + 84.80ms for corrected emplace (ratio: 4.63) + 83.67ms for emplace using returned iterator (ratio: 4.69) + .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::set::empty.3 b/man/std::set::empty.3 index 4d1728994..306c9c0e0 100644 --- a/man/std::set::empty.3 +++ b/man/std::set::empty.3 @@ -1,6 +1,12 @@ -.TH std::set::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::empty \- std::set::empty + .SH Synopsis - bool empty() const; + bool empty() const; \fI(until C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +16,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,32 +24,35 @@ .SH Example - + The following code uses empty to check if a std::set contains any elements: - + // Run this code - #include #include - + #include + int main() { std::set numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.insert(42); - numbers.insert(13317); + numbers.insert(19937); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; } .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::set::end,std::set::cend.3 b/man/std::set::end,std::set::cend.3 index 58da9679a..67c4dffbd 100644 --- a/man/std::set::end,std::set::cend.3 +++ b/man/std::set::end,std::set::cend.3 @@ -1,10 +1,13 @@ -.TH std::set::end,std::set::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::end,std::set::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::end,std::set::cend \- std::set::end,std::set::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fB(1)\fP (noexcept since C++11) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the set. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +22,47 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::set set{3, 1, 4, 1, 5, 9, 2, 6, 5}; + std::for_each(set.cbegin(), set.cend(), [](int x) + { + std::cout << x << ' '; + }); + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 6 9 + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::set::equal_range.3 b/man/std::set::equal_range.3 index 3cc469977..90c3bcfbb 100644 --- a/man/std::set::equal_range.3 +++ b/man/std::set::equal_range.3 @@ -1,27 +1,27 @@ -.TH std::set::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::equal_range \- std::set::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fB(1)\fP - std::pair equal_range( const Key& \fB(2)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP + std::pair equal_range( const Key& \fB(2)\fP key ) const; template< class K > \fB(3)\fP \fI(since C++14)\fP - std::pair equal_range( const K& x ); + std::pair equal_range( const K& x ); template< class K > - std::pair equal_range( const K& x ) \fB(4)\fP \fI(since C++14)\fP - const; + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++14)\fP + ) const; Returns a range containing all elements with the given key in the container. The range is defined by two iterators, one pointing to the first element that is not - less than key and another pointing to the first element greater than key. The first - iterator may be alternatively obtained with lower_bound(), the second - with - upper_bound(). - - 1-2) Compares the keys to key. - 3,4) Compares the keys to the value x. These templates only participate in overload - resolution if the type Compare::is_transparent exists. They allow calling this - function without constructing an instance of Key. + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). - This section is incomplete - Reason: explain better + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. .SH Parameters @@ -42,21 +42,71 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + template + void print_equal_range(I first, I lb, I ub, I last) + { + for (I i{first}; i != lb; ++i) + std::cout << *i << ' '; + std::cout << "[ "; + + for (I i{lb}; i != ub; ++i) + std::cout << *i << ' '; + std::cout << ") "; + + for (I i{ub}; i != last; ++i) + std::cout << *i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::set c{4, 3, 2, 1, 3, 3}; + std::cout << "c = "; + print_equal_range(begin(c), begin(c), end(c), end(c)); + for (int key{}; key != 6; ++key) + { + std::cout << "key = " << key << "; equal range = "; + const auto [lb, ub] = c.equal_range(key); + print_equal_range(begin(c), lb, ub, end(c)); + } + } + +.SH Output: + + c = [ 1 2 3 4 ) + key = 0; equal range = [ ) 1 2 3 4 + key = 1; equal range = [ 1 ) 2 3 4 + key = 2; equal range = 1 [ 2 ) 3 4 + key = 3; equal range = 1 2 [ 3 ) 4 + key = 4; equal range = 1 2 3 [ 4 ) + key = 5; equal range = 1 2 3 4 [ ) .SH See also find finds element with specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - - Categories: - - * Todo with reason - * Todo no example + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::set::erase.3 b/man/std::set::erase.3 index 7c3ace0d7..c2da0789b 100644 --- a/man/std::set::erase.3 +++ b/man/std::set::erase.3 @@ -1,49 +1,128 @@ -.TH std::set::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::erase \- std::set::erase + .SH Synopsis - void erase( iterator pos ); \fI(until C++11)\fP - iterator erase( const_iterator pos ); \fI(since C++11)\fP - void erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP - iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP - const_iterator last ); - size_type erase( const key_type& key ); \fB(3)\fP + iterator erase( iterator pos ); (until C++23) + iterator erase( iterator pos ) + requires(!std::same_as); + iterator erase( const_iterator pos ); \fB(2)\fP \fI(since C++11)\fP + iterator erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP + iterator erase( const_iterator first, \fI(since C++11)\fP + const_iterator last ); \fB(3)\fP + size_type erase( const Key& key ); \fB(4)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); Removes specified elements from the container. - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. + 1,2) Removes the element at pos. + Only one overload is provided if iterator and const_iterator are the same type. + \fI(since C++11)\fP + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes the element (if one exists) with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed (0 or 1). + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. .SH Complexity Given an instance c of set: - 1) Amortized constant - 2) log(c.size()) + std::distance(first, last) - 3) log(c.size()) + c.count(k) + 1,2) Amortized constant + 3) log(c.size()) + std::distance(first, last) + 4) log(c.size()) + c.count(key) + 5) log(c.size()) + c.count(x) + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::set c = {1, 2, 3, 4, 1, 2, 3, 4}; + + auto print = [&c] + { + std::cout << "c = { "; + for (int n : c) + std::cout << n << ' '; + std::cout << "}\\n"; + }; + print(); + + std::cout << "Erase all odd numbers:\\n"; + for (auto it = c.begin(); it != c.end();) + { + if (*it % 2 != 0) + it = c.erase(it); + else + ++it; + } + print(); + + std::cout << "Erase 1, erased count: " << c.erase(1) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + print(); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the return type of overloads (1) and (3) + LWG 130 C++98 was void (it is not corrected to iterator + consistent with the erase() requirement + on sequence containers) + LWG 2059 C++11 replacing overload (1) with overload (2) added overload (1) back + introduced new ambiguity .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::set::extract.3 b/man/std::set::extract.3 new file mode 100644 index 000000000..5adb5b65d --- /dev/null +++ b/man/std::set::extract.3 @@ -0,0 +1,118 @@ +.TH std::set::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::extract \- std::set::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains that element from the container and returns a node handle that owns it. + Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if the + qualified-id Compare::is_transparent is valid and denotes a type, and neither + iterator nor const_iterator is implicitly convertible from K. It allows calling this + function without constructing an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed (rebalancing may occur, as with erase()). + + Extracting a node invalidates only the iterators to the extracted element. Pointers + and references to the extracted element remain valid, but cannot be used while + element is owned by a node handle: they become usable if the element is inserted + into a container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Compare object. + +.SH Complexity + + 1) Amortized constant. + 2,3) log(size()) + +.SH Notes + + extract is the only way to take a move-only object out of a set: + + std::set s; + s.emplace(...); + move_only_type mot = std::move(s.extract(s.begin()).value()); + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto datum : data) + std::cout << ' ' << datum; + + std::cout << '\\n'; + } + + int main() + { + std::set cont{1, 2, 3}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.value() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Output: + + Start: 1 2 3 + After extract and before insert: 2 3 + End: 2 3 4 + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::set::find.3 b/man/std::set::find.3 index 3361176b1..c49437fb0 100644 --- a/man/std::set::find.3 +++ b/man/std::set::find.3 @@ -1,15 +1,20 @@ -.TH std::set::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::find \- std::set::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP - template< class K > iterator find( const K& x ); \fB(3)\fP \fI(since C++14)\fP - template< class K > const_iterator find( const K& x ) const; \fB(4)\fP \fI(since C++14)\fP + iterator find( const Key& key ); \fB(1)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator find( const K& x ) const; 1,2) Finds an element with key equivalent to key. - 3,4) Finds an element with key that compares equivalent to the value x. These - templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -18,25 +23,74 @@ .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + + int main() + { + // Simple comparison demo. + std::set example{1, 2, 3, 4}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << (*search) << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::set> example2{{1, {}}, {2, {}}, {3, {}}, {4, {}}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->x << '\\n'; + else + std::cout << "Not found\\n"; + } + +.SH Output: + + Found 2 + Found 2 .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::set::get_allocator.3 b/man/std::set::get_allocator.3 index 0bb2cb9f2..625aa9fec 100644 --- a/man/std::set::get_allocator.3 +++ b/man/std::set::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::set::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::get_allocator \- std::set::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) Returns the allocator associated with the container. diff --git a/man/std::set::insert.3 b/man/std::set::insert.3 index f882bdf2a..1275c8c4b 100644 --- a/man/std::set::insert.3 +++ b/man/std::set::insert.3 @@ -1,98 +1,183 @@ -.TH std::set::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::insert \- std::set::insert + .SH Synopsis - std::pair insert( const value_type& \fB(1)\fP + std::pair insert( const value_type& \fB(1)\fP value ); - std::pair insert( value_type&& value \fB(2)\fP \fI(since C++11)\fP + std::pair insert( value_type&& value \fB(2)\fP \fI(since C++11)\fP ); - iterator insert( iterator hint, const value_type& \fI(until C++11)\fP + iterator insert( iterator pos, const value_type& \fI(until C++11)\fP value ); - iterator insert( const_iterator hint, const \fI(since C++11)\fP + iterator insert( const_iterator pos, const \fI(since C++11)\fP value_type& value ); - iterator insert( const_iterator hint, value_type&& \fB(3)\fP \fB(4)\fP \fI(since C++11)\fP + iterator insert( const_iterator pos, value_type&& \fB(4)\fP \fI(since C++11)\fP value ); template< class InputIt > \fB(5)\fP void insert( InputIt first, InputIt last ); - void insert( std::initializer_list ilist \fB(6)\fP \fI(since C++11)\fP + void insert( std::initializer_list ilist \fB(3)\fP \fB(6)\fP \fI(since C++11)\fP + ); + insert_return_type insert( node_type&& nh ); \fB(7)\fP \fI(since C++17)\fP + iterator insert( const_iterator pos, node_type&& nh \fB(8)\fP \fI(since C++17)\fP ); + template< class K > \fB(9)\fP (since C++23) + std::pair insert( K&& x ); + template< class K > \fB(10)\fP (since C++23) + iterator insert( const_iterator pos, K&& x ); Inserts element(s) into the container, if the container doesn't already contain an element with an equivalent key. - 1-2) inserts value. - 3-4) inserts value in the position as close as possible, just prior\fI(since C++11)\fP, to - hint. - 5) Inserts elements from range [first, last). - 6) Inserts elements from initializer list ilist. + 1,2) Inserts value. + 3,4) Inserts value in the position as close as possible to the position just prior + to pos. + 5) Inserts elements from range [first, last). If multiple elements in the range have + keys that compare equivalent, it is unspecified which element is inserted (pending + LWG2844). + 6) Inserts elements from initializer list ilist. If multiple elements in the range + have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). + 7) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container , if the container doesn't already contain an element with + a key equivalent to nh.key(). The behavior is undefined if nh is not empty and + get_allocator() != nh.get_allocator(). + 8) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, if the container + doesn't already contain an element with a key equivalent to nh.key(), and returns + the iterator pointing to the element with key equivalent to nh.key()(regardless of + whether the insert succeeded or failed). If the insertion succeeds, nh is moved + from, otherwise it retains ownership of the element. The element is inserted as + close as possible to the position just prior to pos. The behavior is undefined if nh + is not empty and get_allocator() != nh.get_allocator(). + 9) If *this already contains an element which transparently compares equivalent to + x, does nothing. Otherwise, constructs an object u of the value_type with + std::forward(x) and then inserts u into *this. If equal_range(u) == + equal_range(x) is false, the behavior is undefined. The value_type must be + EmplaceConstructible into set from std::forward(x). This overload participates in + overload resolution only if the qualified-id Compare::is_transparent is valid and + denotes a type. It allows calling this function without constructing an instance of + Key. + 10) If *this already contains an element which transparently compares equivalent to + x, does nothing. Otherwise, constructs an object u of the value_type with + std::forward(x) and then inserts u into *this in the position as close as + possible to the position just prior to pos. If equal_range(u) == equal_range(x) is + false, the behavior is undefined. The value_type must be EmplaceConstructible into + set from std::forward(x). This overload participates in overload resolution only + if: + * std::is_convertible_v and std::is_convertible_v are both false, and + * the qualified-id Compare::is_transparent is valid and denotes a type, + which together allows calling this function without constructing an instance of Key. No iterators or references are invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters - hint - iterator, used as a suggestion as to where to insert the content + pos - iterator to the position before which the new element will be inserted value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle + x - a value of any type that can be transparently compared with a key .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-2) Returns a pair consisting of an iterator to the inserted element (or to the - element that prevented the insertion) and a bool denoting whether the insertion took - place. - 3-4) Returns an iterator to the inserted element, or to the element that prevented - the insertion. - 5-6) \fI(none)\fP + 1,2) A pair consisting of an iterator to the inserted element (or to the element + that prevented the insertion) and a bool value set to true if and only if the + insertion took place. + 3,4) An iterator to the inserted element, or to the element that prevented the + insertion. + 5,6) \fI(none)\fP + 7) An object of insert_return_type with the members initialized as follows: + * If nh is empty, inserted is false, position is end(), and node is empty. + * Otherwise if the insertion took place, inserted is true, position points to the + inserted element, and node is empty. + * If the insertion failed, inserted is false, node has the previous value of nh, + and position points to an element with a key equivalent to nh.key(). + 8) End iterator if nh was empty, iterator pointing to the inserted element if + insertion took place, and iterator pointing to an element with a key equivalent to + nh.key() if it failed. + 9) A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. + 10) An iterator to the inserted element, or to the element that prevented the + insertion. .SH Exceptions 1-4) If an exception is thrown by any operation, the insertion has no effect. This section is incomplete - Reason: cases 5-6 + Reason: cases 5-8, 9, 10 .SH Complexity - 1-2) Logarithmic in the size of the container, O(log(size())). - - 3-4) Amortized constant if the insertion happens in the position just \fI(until C++11)\fP - after the hint, logarithmic in the size of the container otherwise. - 3-4) Amortized constant if the insertion happens in the position just \fI(since C++11)\fP - before the hint, logarithmic in the size of the container otherwise. - - 5-6) O(N*log(size() + N)), where N is the number of elements to insert. + 1,2) Logarithmic in the size of the container, O(log(size())). + 3,4) Amortized constant if the insertion happens in the position just + after + \fI(until C++11)\fP + before + \fI(since C++11)\fP pos, logarithmic in the size of the container otherwise. + 5,6) O(N·log(size() + N)), where N is the number of elements to insert. + 7) Logarithmic in the size of the container, O(log(size())). + 8) Amortized constant if the insertion happens in the position just before pos, + logarithmic in the size of the container otherwise. + 9) Logarithmic in the size of the container, O(log(size())). + 10) Amortized constant if the insertion happens in the position just before pos, + logarithmic in the size of the container otherwise. .SH Notes - The overloads (5-6) are often implemented as a loop that calls the overload \fB(3)\fP with + The hinted insert (3,4) does not return a boolean in order to be + signature-compatible with positional insert on sequential containers, such as + std::vector::insert. This makes it possible to create generic inserters such as + std::inserter. One way to check success of a hinted insert is to compare size() + before and after. + + The overloads (5,6) are often implemented as a loop that calls the overload \fB(3)\fP with end() as the hint; they are optimized for appending a sorted sequence (such as - another set) whose smallest element is greater than the last element in *this + another std::set) whose smallest element is greater than the last element in *this. + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. (9,10) .SH Example - + // Run this code - #include #include #include - + #include + int main() { - std::set set; - - auto result_1 = set.insert(3); - assert(result_1.first != set.end()); // it's a valid iterator - assert(*result_1.first == 3); - if (result_1.second) - std::cout << "insert done\\n"; - - auto result_2 = set.insert(3); - assert(result_2.first == result_1.first); // same iterator - assert(*result_2.first == 3); - if (!result_2.second) - std::cout << "no insertion\\n"; + std::set set; + + auto result_1 = set.insert(3); + assert(result_1.first != set.end()); // it is a valid iterator + assert(*result_1.first == 3); + if (result_1.second) + std::cout << "insert done\\n"; + + auto result_2 = set.insert(3); + assert(result_2.first == result_1.first); // same iterator + assert(*result_2.first == 3); + if (!result_2.second) + std::cout << "no insertion\\n"; } .SH Output: @@ -100,13 +185,34 @@ insert done no insertion + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the insertion is required + pos was just a hint, it could be to + LWG 233 C++98 totally ignored be as close as possible to + the + position just prior to pos + the complexity of overload \fB(5)\fP was removed the linear + LWG 264 C++98 required to be linear if requirement + the range [first, last) is sorted in this special case + according to Compare + in the return value of overload \fB(1)\fP, + LWG 316 C++98 it was not specified success is + which bool value indicates a indicated by true + successful insertion + .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP .SH Category: - * Todo with reason diff --git a/man/std::set::insert_range.3 b/man/std::set::insert_range.3 new file mode 100644 index 000000000..bcf9cb1e7 --- /dev/null +++ b/man/std::set::insert_range.3 @@ -0,0 +1,75 @@ +.TH std::set::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::insert_range \- std::set::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg if and only if there is no element + with key equivalent to the key of that element in *this. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + No iterators or references are invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose + elements are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into set from *ranges::begin(rg). Otherwise, + the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N·log(a.size() + N), where N is ranges::distance(rg). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + + void println(auto, auto const& container) + { + for (const auto& elem : container) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::set{1, 3, 2, 4}; + const auto rg = {-1, 3, -2}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + -2 -1 1 2 3 4 + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::set::key_comp.3 b/man/std::set::key_comp.3 index ac324d699..71757b22a 100644 --- a/man/std::set::key_comp.3 +++ b/man/std::set::key_comp.3 @@ -1,4 +1,7 @@ -.TH std::set::key_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::key_comp \- std::set::key_comp + .SH Synopsis key_compare key_comp() const; @@ -17,7 +20,56 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::set cont{1, 2, 3, 4, 5}; + + auto comp_func = cont.key_comp(); + + for (const int key : cont) + { + const bool before = comp_func(key, 100); + const bool after = comp_func(100, key); + + std::cout << '(' << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + .SH See also value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::set::lower_bound.3 b/man/std::set::lower_bound.3 index 01d28b38e..d3d81e7e7 100644 --- a/man/std::set::lower_bound.3 +++ b/man/std::set::lower_bound.3 @@ -1,17 +1,21 @@ -.TH std::set::lower_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::lower_bound \- std::set::lower_bound + .SH Synopsis iterator lower_bound( const Key& key ); \fB(1)\fP - const_iterator lower_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP - iterator lower_bound(const K& x); - template< class K > \fB(2)\fP \fI(since C++14)\fP - const_iterator lower_bound(const K& x) const; - - 1) Returns an iterator pointing to the first element that is not less than key. - 2) Returns an iterator pointing to the first element that compares not less to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. .SH Parameters @@ -27,9 +31,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::set::max_size.3 b/man/std::set::max_size.3 index c2ca915e0..478d36759 100644 --- a/man/std::set::max_size.3 +++ b/man/std::set::max_size.3 @@ -1,6 +1,9 @@ -.TH std::set::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::max_size \- std::set::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,25 +17,45 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::set p; + std::set q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 461,168,601,842,738,790 = 0x666,666,666,666,666 + q.max_size() = 461,168,601,842,738,790 = 0x666,666,666,666,666 + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::set::merge.3 b/man/std::set::merge.3 new file mode 100644 index 000000000..f7d9caffc --- /dev/null +++ b/man/std::set::merge.3 @@ -0,0 +1,87 @@ +.TH std::set::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::merge \- std::set::merge + +.SH Synopsis + template< class C2 > \fB(1)\fP \fI(since C++17)\fP + void merge( std::set& source ); + template< class C2 > \fB(2)\fP \fI(since C++17)\fP + void merge( std::set&& source ); + template< class C2 > \fB(3)\fP \fI(since C++17)\fP + void merge( std::multiset& source ); + template< class C2 > \fB(4)\fP \fI(since C++17)\fP + void merge( std::multiset&& source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the comparison object of *this. If there is an element in *this with key equivalent + to the key of an element from source, then that element is not extracted from + source. No elements are copied or moved, only the internal pointers of the container + nodes are repointed. All pointers and references to the transferred elements remain + valid, but now refer into *this, not into source. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Does not throw unless comparison throws. + +.SH Complexity + + N * log(size() + N)), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + + // print out a container + template + Os& operator<<(Os& os, const std::set& v) + { + os << '[' << v.size() << "] {"; + bool o{}; + for (const auto& e : v) + os << (o ? ", " : (o = 1, " ")) << e; + return os << " }\\n"; + } + + int main() + { + std::set + p{'C', 'B', 'B', 'A'}, + q{'E', 'D', 'E', 'C'}; + + std::cout << "p: " << p << "q: " << q; + + p.merge(q); + + std::cout << "p.merge(q);\\n" << "p: " << p << "q: " << q; + } + +.SH Output: + + p: [3] { A, B, C } + q: [3] { C, D, E } + p.merge(q); + p: [5] { A, B, C, D, E } + q: [1] { C } + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::set::operator=.3 b/man/std::set::operator=.3 index 2c9a155dd..59d7cdc19 100644 --- a/man/std::set::operator=.3 +++ b/man/std::set::operator=.3 @@ -1,27 +1,39 @@ -.TH std::set::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::operator= \- std::set::operator= + .SH Synopsis set& operator=( const set& other ); \fB(1)\fP - set& operator=( set&& other ); \fB(2)\fP \fI(since C++11)\fP - set& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + set& operator=( set&& other ); \fI(since C++11)\fP + \fB(2)\fP \fI(until C++17)\fP + set& operator=( set&& other ) noexcept(/* see below */); \fI(since C++17)\fP + set& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,66 +47,97 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) O(NlogN) in general, where N is size() + ilist.size(). Linear if ilist is sorted + with respect to value_comp(). + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::set to another: - The following code uses to assign one std::set to another: - // Run this code - #include + #include #include - - void display_sizes(const std::set &nums1, - const std::set &nums2, - const std::set &nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::set nums1 {3, 1, 4, 6, 5, 9}; - std::set nums2; - std::set nums3; - + std::set x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 1, 2, 3 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 1, 2, 3 } + y = { 1, 2, 3 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 1, 2, 3 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 4, 5, 6, 7 } .SH See also constructor constructs the set - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::set::rbegin,std::set::crbegin.3 b/man/std::set::rbegin,std::set::crbegin.3 index 9cdc47b03..9e6511599 100644 --- a/man/std::set::rbegin,std::set::crbegin.3 +++ b/man/std::set::rbegin,std::set::crbegin.3 @@ -1,11 +1,15 @@ -.TH std::set::rbegin,std::set::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::rbegin,std::set::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::rbegin,std::set::crbegin \- std::set::rbegin,std::set::crbegin + .SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. + Returns a reverse iterator to the first element of the reversed set. It corresponds + to the last element of the non-reversed set. If the set is empty, the returned + iterator is equal to rend(). range-rbegin-rend.svg @@ -17,18 +21,53 @@ Reverse iterator to the first element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::set rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ + .SH See also - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::set::rend,std::set::crend.3 b/man/std::set::rend,std::set::crend.3 index e92830a0b..d29873451 100644 --- a/man/std::set::rend,std::set::crend.3 +++ b/man/std::set::rend,std::set::crend.3 @@ -1,13 +1,16 @@ -.TH std::set::rend,std::set::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::rend,std::set::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::rend,std::set::crend \- std::set::rend,std::set::crend + .SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. + set. It corresponds to the element preceding the first element of the non-reversed + set. This element acts as a placeholder, attempting to access it results in + undefined behavior. range-rbegin-rend.svg @@ -19,18 +22,50 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::set rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::set::set.3 b/man/std::set::set.3 index 961fb0b58..9fb1fd900 100644 --- a/man/std::set::set.3 +++ b/man/std::set::set.3 @@ -1,58 +1,85 @@ -.TH std::set::set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::set \- std::set::set + .SH Synopsis - explicit set( const Compare& comp = Compare(), (until - const Allocator& alloc = Allocator() C++14) - ); - set : set( Compare() ) {} - - explicit set( const Compare& comp, (since - C++14) - const Allocator& alloc = Allocator() - ); - explicit set( const Allocator& alloc ); \fB(1)\fP (since - C++11) + set(); \fI(until C++11)\fP + set() \fI(since C++11)\fP + : set(Compare()) {} + explicit set( const Compare& comp, \fB(2)\fP + const Allocator& alloc = Allocator() ); + explicit set( const Allocator& alloc ); \fB(3)\fP \fI(since C++11)\fP template< class InputIt > - set( InputIt first, InputIt last, + set( InputIt first, InputIt last, \fB(4)\fP const Compare& comp = Compare(), const Allocator& alloc = Allocator() ); - template< class InputIt > \fB(1)\fP - (since - set( InputIt first, InputIt last, C++14) + template< class InputIt > + + set( InputIt first, InputIt last, \fB(5)\fP \fI(since C++14)\fP + const Allocator& alloc ) + + : set(first, last, Compare(), alloc) {} + set( const set& other ); \fB(6)\fP + set( const set& other, const Allocator& alloc ); \fB(7)\fP \fI(since C++11)\fP + set( set&& other ); \fB(8)\fP \fI(since C++11)\fP + set( set&& other, const Allocator& alloc ); \fB(9)\fP \fI(since C++11)\fP + set( std::initializer_list init, \fB(1)\fP + + const Compare& comp = Compare(), \fB(10)\fP \fI(since C++11)\fP const Allocator& alloc = Allocator() ); - set( const set& other ); \fB(3)\fP - set( const set& other, const Allocator& alloc ); \fB(2)\fP \fB(3)\fP (since - C++11) - set( set&& other ); \fB(4)\fP (since - C++11) - set( set&& other, const Allocator& alloc ); \fB(4)\fP (since - C++11) set( std::initializer_list init, - (since - const Compare& comp = Compare(), C++11) - \fB(5)\fP - const Allocator& alloc = Allocator() ); - set( std::initializer_list init, (since - const Allocator& alloc = Allocator() ); C++14) - Constructs new container from a variety of data sources and optionally using user - supplied allocator alloc or comparison function object comp. + const Allocator& alloc ) \fB(11)\fP \fI(since C++14)\fP + + : set(init, Compare(), alloc) {} + template< container-compatible-range R > - 1) Default constructor. Constructs empty container. + set( std::from_range_t, R&& rg, \fB(12)\fP (since C++23) + const Compare& comp = Compare(), + + const Allocator& alloc = Allocator() ); + template< container-compatible-range R > - 2) Constructs the container with the contents of the range [first, last). + set( std::from_range_t, R&& rg, + const Allocator& alloc ) \fB(13)\fP (since C++23) - 3) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). + : set(std::from_range, std::forward(rg), Compare(), + alloc) {} - 4) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. + Constructs new container from a variety of data sources and optionally using user + supplied allocator alloc or comparison function object comp. - 5) Constructs the container with the contents of the initializer list init. + 1-3) Constructs an empty container. + 4,5) Constructs the container with the contents of the range [first, last). If + multiple elements in the range have keys that compare equivalent, it is unspecified + which element is inserted (pending LWG2844). + If [first, last) is not a valid range, the behavior is undefined. + 6,7) Copy constructor. Constructs the container with the copy of the contents of + other. + + If alloc is not provided, allocator is obtained by calling (since + std::allocator_traits:: C++11) + select_on_container_copy_construction(other.get_allocator()). + During class template argument deduction, only the first argument contributes (since + to the deduction of the container's Allocator template parameter. C++23) + + 8,9) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 10,11) Initializer-list constructor. Constructs the container with the contents of + the initializer list init.If multiple elements in the range have keys that compare + equivalent, it is unspecified which element is inserted (pending LWG2844). + 12,13) Constructs the container with the contents of rg. If multiple elements in the + range have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). .SH Parameters @@ -62,9 +89,11 @@ other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - Compare must meet the requirements of Compare. - @@ -72,163 +101,135 @@ .SH Complexity - 1) Constant + 1-3) Constant. + 4,5) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + std::distance(first, last) in general, linear in \\(\\scriptsize N\\)N if [first, last) + is already sorted by value_comp(). + 6,7) Linear in size of other. + 8,9) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 10,11) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + init.size() in general, linear in \\(\\scriptsize N\\)N if init is already sorted by + value_comp(). + 12,13) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + ranges::distance(rg) in general, linear in \\(\\scriptsize N\\)N if rg is already + sorted by value_comp(). - 2) N log(N) where N = std::distance(first, last) in general, linear in N if the - range is already sorted by value_comp(). +.SH Exceptions - 3) Linear in size of other + Calls to Allocator::allocate may throw. - 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. +.SH Notes - 5) N log(N) where N = init.size()) in general, linear in N if init is already sorted - by value_comp(). + After container move construction (overload (8,9)), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Although not formally required until C++23, some implementations has already put the + template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (12,13) .SH Example - + // Run this code + #include #include - #include - #include - - //declare printers for maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - - int main() + #include + #include + + struct Point { double x, y; }; + + struct PointCmp { - typedef std::string Key; - typedef int Mapped; - - // (1) Default constructor - std::map map; - map["something"] = 69; - map["anything"] = 199; - map["that thing"] = 50; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (2) Iterator constructor - std::map iter(map.find("anything"), map.end()); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "iter = " << iter << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (3) Copy constructor - std::map copy(map); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "copy = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (4) Move constructor - std::map moved(std::move(map)); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "moved = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (5) Initializer list constructor - const std::map init { - {"this", 100}, - {"can", 100}, - {"be", 100}, - {"const", 100}, - }; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "init = " << init << '\\n'; - } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ':' << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A specialization for Key strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":" << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; + bool operator()(const Point& lhs, const Point& rhs) const + { + return std::hypot(lhs.x, lhs.y) < std::hypot(rhs.x, rhs.y); + } + }; + + std::ostream& operator<<(std::ostream& os, Point pt) + { + return os << '(' << pt.x << ',' << pt.x << ')'; } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; + + void println(auto rem, const auto& seq) + { + std::cout << rem << '{'; + for (auto n{seq.size()}; const auto& elm : seq) + std::cout << elm << (--n ? ", " : ""); + std::cout << "}\\n"; } - - // A specialization for Key and Mapped strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; + + int main() + { + // (1) Default constructor + std::set a; + a.insert("horse"); + a.insert("cat"); + a.insert("dog"); + println("1) a: ", a); + + // (4) Range constructor + std::set b(a.find("dog"), a.end()); + println("2) b: ", b); + + // (6) Copy constructor + std::set c(a); + c.insert("another horse"); + println("3) c: ", c); + + // (8) Move constructor + std::set d(std::move(a)); + println("4) d: ", d); + println("5) a: ", a); + + // (10) Initializer list constructor + std::set e{"one", "two", "three", "five", "eight"}; + println("6) e: ", e); + + // Custom comparison + std::set f = {{2, 5}, {3, 4}, {1, 1}}; + f.insert({1, -1}); // This fails because the magnitude of (1,-1) equals (1,1) + println("7) f: ", f); + + // (12) Range constructor + const auto w = {"Eurybia", "Theia", "Rhea", "Aura", "Mnemosyne", "Mnemosyne"}; + #if __cpp_lib_containers_ranges + std::set g(std::from_range, w); // overload (12) + #else + std::set g(w.begin(), w.end()); // fallback to (4) + #endif + println("8) g: ", g); } -.SH Output: - - -------------------------------------------------------------------------------- - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - iter = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - copy = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - moved = {"anything":199, "something":69, "that thing":50} - map = {} - -------------------------------------------------------------------------------- - init = {"be":100, "can":100, "const":100, "this":100} - - This section is incomplete - Reason: cleanup/shorten this example +.SH Possible output: -.SH See also + 1) a: {cat, dog, horse} + 2) b: {dog, horse} + 3) c: {another horse, cat, dog, horse} + 4) d: {cat, dog, horse} + 5) a: {} + 6) e: {eight, five, one, three, two} + 7) f: {(1,1), (3,3), (2,2)} + 8) g: {Aura, Eurybia, Mnemosyne, Rhea, Theia} - operator= assigns values to the container - \fI(public member function)\fP + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo with reason + DR Applied to Behavior as published Correct behavior + LWG 2076 C++11 overload \fB(4)\fP conditionally required Key to be not required + CopyInsertable into *this + LWG 2193 C++11 the default constructor was explicit made non-explicit + +.SH See also + + operator= assigns values to the container + \fI(public member function)\fP diff --git a/man/std::set::size.3 b/man/std::set::size.3 index bcd2cd916..e80f6419e 100644 --- a/man/std::set::size.3 +++ b/man/std::set::size.3 @@ -1,6 +1,9 @@ -.TH std::set::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::size \- std::set::size + .SH Synopsis - size_type size() const; + size_type size() const; (noexcept since C++11) Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,26 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::set: - + // Run this code - #include #include - + #include + int main() { - std::set nums {1, 3, 5, 7}; - + std::set nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +45,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::set::swap.3 b/man/std::set::swap.3 index 49063a0e8..fb153a478 100644 --- a/man/std::set::swap.3 +++ b/man/std::set::swap.3 @@ -1,19 +1,23 @@ -.TH std::set::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::swap \- std::set::swap + .SH Synopsis - void swap( set& other ); + void swap( set& other ); \fI(until C++17)\fP + void swap( set& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. + + The Compare objects must be Swappable, and they are exchanged using unqualified call + to non-member swap. - The Pred objects must be Swappable, and they are exchanged using unqualified call to - non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +29,77 @@ .SH Exceptions - Any exception thrown by the swap of the Compare objects. + Any exception thrown by the swap of the Compare objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::set a1{3, 1, 3, 2}, a2{5, 4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + const int& ref1 = *(a1.begin()); + const int& ref2 = *(a2.begin()); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that every iterator referring to an element in one container before the swap + // refers to the same element in the other container after the swap. Same is true + // for references. + + struct Cmp : std::less + { + int id{}; + Cmp(int i) : id{i} {} + }; + + std::set s1{{2, 2, 1, 1}, Cmp{6}}, s2{{4, 4, 3, 3}, Cmp{9}}; + + std::cout << s1 << s2 << s1.key_comp().id << ' ' << s2.key_comp().id << '\\n'; + s1.swap(s2); + std::cout << s1 << s2 << s1.key_comp().id << ' ' << s2.key_comp().id << '\\n'; + + // So, comparator objects (Cmp) are also exchanged after the swap. + } + +.SH Output: + + { 1 2 3 } { 4 5 } 2 5 1 4 + { 4 5 } { 1 2 3 } 2 5 1 4 + { 1 2 } { 3 4 } 6 9 + { 3 4 } { 1 2 } 9 6 + .SH See also std::swap(std::set) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::set::upper_bound.3 b/man/std::set::upper_bound.3 index 23cf4ad17..c8eff6478 100644 --- a/man/std::set::upper_bound.3 +++ b/man/std::set::upper_bound.3 @@ -1,17 +1,20 @@ -.TH std::set::upper_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::upper_bound \- std::set::upper_bound + .SH Synopsis iterator upper_bound( const Key& key ); \fB(1)\fP - const_iterator upper_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP iterator upper_bound( const K& x ); - template< class K > \fB(2)\fP \fI(since C++14)\fP + template< class K > \fB(4)\fP \fI(since C++14)\fP const_iterator upper_bound( const K& x ) const; - 1) Returns an iterator pointing to the first element that is greater than key. - 2) Returns an iterator pointing to the first element that compares greater to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -27,9 +30,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::set::value_comp.3 b/man/std::set::value_comp.3 index e271af89f..ecf4dc731 100644 --- a/man/std::set::value_comp.3 +++ b/man/std::set::value_comp.3 @@ -1,4 +1,7 @@ -.TH std::set::value_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::value_comp \- std::set::value_comp + .SH Synopsis std::set::value_compare value_comp() const; @@ -16,7 +19,57 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::set cont{1, 2, 3, 4, 5}; + + // Same behaviour as key_comp() + auto comp_func = cont.value_comp(); + + for (const int val{100}; const int key : cont) + { + const bool before = comp_func(key, val); + const bool after = comp_func(val, key); + + std::cout << "Key (" << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val << ")\\n"; + else if (before) + std::cout << "goes before key (" << val << ")\\n"; + else if (after) + std::cout << "goes after key (" << val << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + .SH See also key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::set::~set.3 b/man/std::set::~set.3 index 3a1961aab..1b2cb934d 100644 --- a/man/std::set::~set.3 +++ b/man/std::set::~set.3 @@ -1,11 +1,14 @@ -.TH std::set::~set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set::~set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set::~set \- std::set::~set + .SH Synopsis ~set(); - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. + Destructs the set. The destructors of the elements are called and the used storage + is deallocated. Note, that if the elements are pointers, the pointed-to objects are + not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the set. diff --git a/man/std::set_difference.3 b/man/std::set_difference.3 index 53d1492ea..465a73eca 100644 --- a/man/std::set_difference.3 +++ b/man/std::set_difference.3 @@ -1,55 +1,113 @@ -.TH std::set_difference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_difference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_difference \- std::set_difference + .SH Synopsis Defined in header - template< class InputIt1, class InputIt2, class OutputIt > + template< class InputIt1, class InputIt2, class OutputIt + > - OutputIt set_difference( InputIt1 first1, InputIt1 last1, \fB(1)\fP - InputIt2 first2, InputIt2 last2, + OutputIt set_difference( InputIt1 first1, InputIt1 + last1, \fB(1)\fP (constexpr since C++20) + InputIt2 first2, InputIt2 + last2, OutputIt d_first ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + ForwardIt3 > + ForwardIt3 set_difference( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 \fB(2)\fP \fI(since C++17)\fP + last1, + ForwardIt2 first2, ForwardIt2 + last2, + + ForwardIt3 d_first ); template< class InputIt1, class InputIt2, class OutputIt, class Compare > - OutputIt set_difference( InputIt1 first1, InputIt1 last1, \fB(2)\fP - InputIt2 first2, InputIt2 last2, + OutputIt set_difference( InputIt1 first1, InputIt1 + last1, \fB(3)\fP (constexpr since C++20) + InputIt2 first2, InputIt2 + last2, + + OutputIt d_first, Compare comp + ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class ForwardIt3, class Compare > + ForwardIt3 set_difference( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 \fB(4)\fP \fI(since C++17)\fP + last1, + ForwardIt2 first2, ForwardIt2 + last2, - OutputIt d_first, Compare comp ); + ForwardIt3 d_first, Compare + comp ); Copies the elements from the sorted range [first1, last1) which are not found in the - sorted range [first2, last2) to the range beginning at d_first. + sorted range [first2, last2) to the range beginning at d_first. The output range is + also sorted. - The resulting range is also sorted. The first version expects both input ranges to - be sorted with operator<, the second version expects them to be sorted with the - given comparison function comp. Equivalent elements are treated individually, that - is, if some element is found m times in [first1, last1) and n times in [first2, - last2), it will be copied to d_first exactly std::max(m-n, 0) times. The resulting - range cannot overlap with either of the input ranges. + If [first1, last1) contains m elements that are equivalent to each other and + [first2, last2) contains n elements that are equivalent to them, the final + std::max(m - n, 0) elements will be copied from [first1, last1) to the output range, + preserving order. + + 1) If [first1, last1) or [first2, last2) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first1, last1) or [first2, last2) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If the output range overlaps with [first1, last1) or [first2, last2), the behavior + is undefined. .SH Parameters first1, last1 - the range of elements to examine first2, last2 - the range of elements to search for + d_first - the beginning of the output range + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. + converted to both Type1 and Type2. .SH Type requirements - - InputIt1 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. - - InputIt2 must meet the requirements of InputIterator. + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. - - OutputIt must meet the requirements of OutputIterator. + Compare must meet the requirements of Compare. .SH Return value @@ -57,87 +115,153 @@ .SH Complexity - At most 2·(N[1]+N[2]-1) comparisons, where N[1] = std::distance(first1, last1) and - N[2] = std::distance(first2, last2). + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - OutputIt set_difference(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first) - { - while (first1 != last1) { - if (first2 == last2) return std::copy(first1, last1, d_first); - - if (*first1 < *first2) { - *d_first++ = *first1++; - } else { - if (! (*first2 < *first1)) { - ++first1; - } - ++first2; - } - } - return d_first; - } -.SH Second version - template - OutputIt set_difference( InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first, Compare comp) - { - while (first1 != last1) { - if (first2 == last2) return std::copy(first1, last1, d_first); - - if (comp(*first1, *first2)) { - *d_first++ = *first1++; - } else { - if (!comp(*first2, *first1)) { - ++first1; - } - ++first2; - } - } - return d_first; - } + set_difference \fB(1)\fP + template + OutputIt set_difference(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first) + { + while (first1 != last1) + { + if (first2 == last2) + return std::copy(first1, last1, d_first); + + if (*first1 < *first2) + *d_first++ = *first1++; + else + { + if (! (*first2 < *first1)) + ++first1; + ++first2; + } + } + return d_first; + } + set_difference \fB(3)\fP + template + OutputIt set_difference(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp) + { + while (first1 != last1) + { + if (first2 == last2) + return std::copy(first1, last1, d_first); + + if (comp(*first1, *first2)) + *d_first++ = *first1++; + else + { + if (!comp(*first2, *first1)) + ++first1; + ++first2; + } + } + return d_first; + } .SH Example - + // Run this code - #include #include - #include + #include #include - - int main() { - std::vector v1 {1, 2, 5, 5, 5, 9}; - std::vector v2 {2, 5, 7}; + #include + + template + std::ostream& operator<<(std::ostream& os, const std::vector& v) + { + os << '{'; + for (auto n{v.size()}; const auto& e : v) + os << e << (--n ? ", " : ""); + return os << '}'; + } + + struct Order // a struct with very interesting data + { + int order_id{}; + + friend std::ostream& operator<<(std::ostream& os, const Order& ord) + { + return os << ord.order_id; + } + }; + + int main() + { + const std::vector v1{1, 2, 5, 5, 5, 9}; + const std::vector v2{2, 5, 7}; std::vector diff; - + std::set_difference(v1.begin(), v1.end(), v2.begin(), v2.end(), std::inserter(diff, diff.begin())); - - for (auto i : v1) std::cout << i << ' '; - std::cout << "minus "; - for (auto i : v2) std::cout << i << ' '; - std::cout << "is: "; - - for (auto i : diff) std::cout << i << ' '; - std::cout << '\\n'; + + std::cout << v1 << " ∖ " << v2 << " == " << diff << "\\n\\n"; + + // we want to know which orders "cut" between old and new states: + std::vector old_orders{{1}, {2}, {5}, {9}}; + std::vector new_orders{{2}, {5}, {7}}; + std::vector cut_orders; + + std::set_difference(old_orders.begin(), old_orders.end(), + new_orders.begin(), new_orders.end(), + std::back_inserter(cut_orders), + [](auto& a, auto& b) { return a.order_id < b.order_id; }); + + std::cout << "old orders: " << old_orders << '\\n' + << "new orders: " << new_orders << '\\n' + << "cut orders: " << cut_orders << '\\n'; } .SH Output: - 1 2 5 5 5 9 minus 2 5 7 is: 1 5 5 9 + {1, 2, 5, 5, 5, 9} ∖ {2, 5, 7} == {1, 5, 5, 9} + + old orders: {1, 2, 5, 9} + new orders: {2, 5, 7} + cut orders: {1, 9} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 291 C++98 it was unspecified how to handle equivalent specified + elements in the input ranges .SH See also - includes returns true if one set is a subset of another - \fI(function template)\fP + includes returns true if one sequence is a subsequence of another + \fI(function template)\fP set_symmetric_difference computes the symmetric difference between two sets - \fI(function template)\fP + \fI(function template)\fP + ranges::set_difference computes the difference between two sets + (C++20) (niebloid) diff --git a/man/std::set_intersection.3 b/man/std::set_intersection.3 index 830ba5990..de201b31b 100644 --- a/man/std::set_intersection.3 +++ b/man/std::set_intersection.3 @@ -1,54 +1,112 @@ -.TH std::set_intersection 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_intersection 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_intersection \- std::set_intersection + .SH Synopsis Defined in header - template< class InputIt1, class InputIt2, class OutputIt > + template< class InputIt1, class InputIt2, class OutputIt + > - OutputIt set_intersection( InputIt1 first1, InputIt1 last1, \fB(1)\fP - InputIt2 first2, InputIt2 last2, + OutputIt set_intersection( InputIt1 first1, InputIt1 + last1, \fB(1)\fP (constexpr since C++20) + InputIt2 first2, InputIt2 + last2, OutputIt d_first ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + ForwardIt3 > + ForwardIt3 set_intersection( ExecutionPolicy&& policy, + ForwardIt1 first1, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 last1, + ForwardIt2 first2, + ForwardIt2 last2, + + ForwardIt3 d_first ); template< class InputIt1, class InputIt2, class OutputIt, class Compare > - OutputIt set_intersection( InputIt1 first1, InputIt1 last1, \fB(2)\fP - InputIt2 first2, InputIt2 last2, - - OutputIt d_first, Compare comp ); + OutputIt set_intersection( InputIt1 first1, InputIt1 + last1, \fB(3)\fP (constexpr since C++20) + InputIt2 first2, InputIt2 + last2, + + OutputIt d_first, Compare + comp ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class ForwardIt3, class Compare > + ForwardIt3 set_intersection( ExecutionPolicy&& policy, + ForwardIt1 first1, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 last1, + ForwardIt2 first2, + ForwardIt2 last2, + + ForwardIt3 d_first, Compare + comp ); Constructs a sorted range beginning at d_first consisting of elements that are found - in both sorted ranges [first1, last1) and [first2, last2). The first version expects - both input ranges to be sorted with operator<, the second version expects them to be - sorted with the given comparison function comp. If some element is found m times in - [first1, last1) and n times in [first2, last2), the first std::min(m, n) elements - will be copied from the first range to the destination range. The order of - equivalent elements is preserved. The resulting range cannot overlap with either of - the input ranges. + in both sorted ranges [first1, last1) and [first2, last2). + + If [first1, last1) contains m elements that are equivalent to each other and + [first2, last2) contains n elements that are equivalent to them, the first + std::min(m, n) elements will be copied from [first1, last1) to the output range, + preserving order. + + 1) If [first1, last1) or [first2, last2) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first1, last1) or [first2, last2) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If the output range overlaps with [first1, last1) or [first2, last2), the behavior + is undefined. .SH Parameters first1, last1 - the first range of elements to examine first2, last2 - the second range of elements to examine + d_first - the beginning of the output range + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. + converted to both Type1 and Type2. .SH Type requirements - - InputIt1 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. - - InputIt2 must meet the requirements of InputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - OutputIt must meet the requirements of OutputIterator. + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. + - + Compare must meet the requirements of Compare. .SH Return value @@ -56,79 +114,112 @@ .SH Complexity - At most 2·(N[1]+N[2]-1) comparisons, where N[1] = std::distance(first1, last1) and - N[2] = std::distance(first2, last2). + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - OutputIt set_intersection(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first) - { - while (first1 != last1 && first2 != last2) { - if (*first1 < *first2) { - ++first1; - } else { - if (!(*first2 < *first1)) { - *d_first++ = *first1++; - } - ++first2; - } - } - return d_first; - } -.SH Second version - template - OutputIt set_intersection(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first, Compare comp) - { - while (first1 != last1 && first2 != last2) { - if (comp(*first1, *first2)) { - ++first1; - } else { - if (!comp(*first2, *first1)) { - *d_first++ = *first1++; - } - ++first2; - } - } - return d_first; - } + set_intersection \fB(1)\fP +template +OutputIt set_intersection(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first) +{ + while (first1 != last1 && first2 != last2) + { + if (*first1 < *first2) + ++first1; + else + { + if (!(*first2 < *first1)) + *d_first++ = *first1++; // *first1 and *first2 are equivalent. + ++first2; + } + } + return d_first; +} + set_intersection \fB(3)\fP +template +OutputIt set_intersection(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp) +{ + while (first1 != last1 && first2 != last2) + { + if (comp(*first1, *first2)) + ++first1; + else + { + if (!comp(*first2, *first1)) + *d_first++ = *first1++; // *first1 and *first2 are equivalent. + ++first2; + } + } + return d_first; +} .SH Example - + // Run this code - #include - #include #include + #include #include + #include + int main() { - std::vector v1{1,2,3,4,5,6,7,8}; - std::vector v2{ 5, 7, 9,10}; + std::vector v1{7, 2, 3, 4, 5, 6, 7, 8}; + std::vector v2{5, 7, 9, 7}; std::sort(v1.begin(), v1.end()); std::sort(v2.begin(), v2.end()); - + std::vector v_intersection; - - std::set_intersection(v1.begin(), v1.end(), - v2.begin(), v2.end(), + std::set_intersection(v1.begin(), v1.end(), v2.begin(), v2.end(), std::back_inserter(v_intersection)); - for(int n : v_intersection) + + for (int n : v_intersection) std::cout << n << ' '; + std::cout << '\\n'; } .SH Output: - 5 7 + 5 7 7 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 291 C++98 it was unspecified how to handle equivalent specified + elements in the input ranges .SH See also - set_union computes the union of two sets - \fI(function template)\fP + set_union computes the union of two sets + \fI(function template)\fP + ranges::set_intersection computes the intersection of two sets + (C++20) (niebloid) diff --git a/man/std::set_new_handler.3 b/man/std::set_new_handler.3 index 749398a16..c1b24b877 100644 --- a/man/std::set_new_handler.3 +++ b/man/std::set_new_handler.3 @@ -1,7 +1,11 @@ -.TH std::set_new_handler 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_new_handler 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_new_handler \- std::set_new_handler + .SH Synopsis Defined in header - std::new_handler set_new_handler( std::new_handler new_p ) + std::new_handler set_new_handler( std::new_handler new_p ) throw(); \fI(until C++11)\fP + std::new_handler set_new_handler( std::new_handler new_p ) noexcept; \fI(since C++11)\fP Makes new_p the new global new-handler function and returns the previously installed new-handler. @@ -9,11 +13,11 @@ The new-handler function is the function called by allocation functions whenever a memory allocation attempt fails. Its intended purpose is one of three things: - 1) make more memory available - 2) terminate the program (e.g. by calling std::terminate) + 1) make more memory available, + 2) terminate the program (e.g. by calling std::terminate), 3) throw exception of type std::bad_alloc or derived from std::bad_alloc. - The default implementation throws std::bad_alloc. The user can install his own + The default implementation throws std::bad_alloc. The user can install their own new-handler, which may offer behavior different than the default one. If new-handler returns, the allocation function repeats the previously-failed @@ -24,6 +28,10 @@ At program startup, new-handler is a null pointer. + This function is thread-safe. Every call to std::set_new_handler + synchronizes-with (see std::memory_order) the subsequent \fI(since C++11)\fP + std::set_new_handler and std::get_new_handler calls. + .SH Parameters new_p - pointer to function of type std::new_handler, or null pointer @@ -32,40 +40,37 @@ The previously-installed new handler, or a null pointer value if none was installed. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Example - + // Run this code #include #include - + void handler() { std::cout << "Memory allocation failed, terminating\\n"; std::set_new_handler(nullptr); } - + int main() { std::set_new_handler(handler); - try { - while (true) { - new int[100000000ul]; + try + { + while (true) + { + new int[1000'000'000ul](); } - } catch (const std::bad_alloc& e) { + } + catch (const std::bad_alloc& e) + { std::cout << e.what() << '\\n'; } } -.SH Output: +.SH Possible output: Memory allocation failed, terminating std::bad_alloc @@ -73,10 +78,10 @@ .SH See also operator new allocation functions - operator new[] \fI(function)\fP - set_new_handler registers a new handler - \fI(function)\fP + operator new[] \fI(function)\fP + get_new_handler obtains the current new handler + \fI(C++11)\fP \fI(function)\fP new_handler function pointer type of the new handler - \fI(typedef)\fP + \fI(typedef)\fP bad_alloc exception thrown when memory allocation fails - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::set_symmetric_difference.3 b/man/std::set_symmetric_difference.3 index 993ba74f9..bcef69e77 100644 --- a/man/std::set_symmetric_difference.3 +++ b/man/std::set_symmetric_difference.3 @@ -1,57 +1,108 @@ -.TH std::set_symmetric_difference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_symmetric_difference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_symmetric_difference \- std::set_symmetric_difference + .SH Synopsis Defined in header - template< class InputIt1, class InputIt2, class OutputIt > + template< class InputIt1, class InputIt2, class OutputIt + > + + OutputIt set_symmetric_difference \fB(1)\fP (constexpr since C++20) + ( InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, - OutputIt set_symmetric_difference( InputIt1 first1, InputIt1 last1, \fB(1)\fP - InputIt2 first2, InputIt2 last2, + OutputIt d_first ); + template< class ExecutionPolicy, - OutputIt d_first ); + class ForwardIt1, class ForwardIt2, class + ForwardIt3 > + ForwardIt3 set_symmetric_difference \fB(2)\fP \fI(since C++17)\fP + ( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, + ForwardIt2 first2, ForwardIt2 last2, + + ForwardIt3 d_first ); template< class InputIt1, class InputIt2, class OutputIt, class Compare > - OutputIt set_symmetric_difference( InputIt1 first1, InputIt1 last1, \fB(2)\fP - InputIt2 first2, InputIt2 last2, + OutputIt set_symmetric_difference \fB(3)\fP (constexpr since C++20) + ( InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, + + OutputIt d_first, Compare comp ); + template< class ExecutionPolicy, - OutputIt d_first, Compare comp ); + class ForwardIt1, class ForwardIt2, + class ForwardIt3, class Compare > + ForwardIt3 set_symmetric_difference \fB(4)\fP \fI(since C++17)\fP + ( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 last1, + ForwardIt2 first2, ForwardIt2 last2, + + ForwardIt3 d_first, Compare comp ); Computes symmetric difference of two sorted ranges: the elements that are found in either of the ranges, but not in both of them are copied to the range beginning at - d_first. The resulting range is also sorted. - - The first version expects both input ranges to be sorted with operator<, the second - version expects them to be sorted with the given comparison function comp. If some - element is found m times in [first1, last1) and n times in [first2, last2), it will - be copied to d_first exactly std::abs(m-n) times. If m>n, then the last m-n of those - elements are copied from [first1,last1), otherwise the last n-m elements are copied - from [first2,last2). The resulting range cannot overlap with either of the input - ranges. + d_first. The output range is also sorted. + + If [first1, last1) contains m elements that are equivalent to each other and + [first2, last2) contains n elements that are equivalent to them, then std::abs(m - + n) of those elements will be copied to the output range, preserving order: + + * if m > n, the final m - n of these elements from [first1, last1). + * if m < n, the final n - m of these elements from [first2, last2). + 1) If [first1, last1) or [first2, last2) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first1, last1) or [first2, last2) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If the output range overlaps with [first1, last1) or [first2, last2), the behavior + is undefined. .SH Parameters first1, last1 - the first sorted range of elements first2, last2 - the second sorted range of elements + d_first - the beginning of the output range + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. + converted to both Type1 and Type2. .SH Type requirements - - InputIt1 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. - - InputIt2 must meet the requirements of InputIterator. + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. - - OutputIt must meet the requirements of OutputIterator. + Compare must meet the requirements of Compare. .SH Return value @@ -59,51 +110,75 @@ .SH Complexity - At most 2·(N[1]+N[2]-1) comparisons, where N[1] = std::distance(first1, last1) and - N[2] = std::distance(first2, last2). + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + set_symmetric_difference \fB(1)\fP template - OutputIt set_difference(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first) + OutputIt set_symmetric_difference(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first) { - while (first1 != last1) { - if (first2 == last2) return std::copy(first1, last1, d_first); - - if (*first1 < *first2) { + while (first1 != last1) + { + if (first2 == last2) + return std::copy(first1, last1, d_first); + + if (*first1 < *first2) *d_first++ = *first1++; - } else { - if (*first2 < *first1) { + else + { + if (*first2 < *first1) *d_first++ = *first2; - } else { + else ++first1; - } ++first2; } } return std::copy(first2, last2, d_first); } -.SH Second version - template - OutputIt set_difference(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first, Compare comp) + set_symmetric_difference \fB(3)\fP + template + OutputIt set_symmetric_difference(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, + OutputIt d_first, Compare comp) { - while (first1 != last1) { - if (first2 == last2) return std::copy(first1, last1, d_first); - - if (comp(*first1, *first2)) { + while (first1 != last1) + { + if (first2 == last2) + return std::copy(first1, last1, d_first); + + if (comp(*first1, *first2)) *d_first++ = *first1++; - } else { - if (comp(*first2, *first1)) { + else + { + if (comp(*first2, *first1)) *d_first++ = *first2; - } else { + else ++first1; - } ++first2; } } @@ -112,42 +187,54 @@ .SH Example - + // Run this code - #include - #include #include + #include #include + #include + int main() { - std::vector v1{1,2,3,4,5,6,7,8 }; - std::vector v2{ 5, 7, 9,10}; + std::vector v1{1, 2, 3, 4, 5, 6, 7, 8}; + std::vector v2{5, 7, 9, 10}; std::sort(v1.begin(), v1.end()); std::sort(v2.begin(), v2.end()); - + std::vector v_symDifference; - - std::set_symmetric_difference( - v1.begin(), v1.end(), - v2.begin(), v2.end(), - std::back_inserter(v_symDifference)); - - for(int n : v_symDifference) + + std::set_symmetric_difference(v1.begin(), v1.end(), v2.begin(), v2.end(), + std::back_inserter(v_symDifference)); + + for (int n : v_symDifference) std::cout << n << ' '; + std::cout << '\\n'; } .SH Output: 1 2 3 4 6 8 9 10 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 291 C++98 it was unspecified how to handle equivalent specified + elements in the input ranges + .SH See also - includes returns true if one set is a subset of another - \fI(function template)\fP - set_difference computes the difference between two sets - \fI(function template)\fP - set_union computes the union of two sets - \fI(function template)\fP - set_intersection computes the intersection of two sets - \fI(function template)\fP + returns true if one sequence is a subsequence of + includes another + \fI(function template)\fP + set_difference computes the difference between two sets + \fI(function template)\fP + set_union computes the union of two sets + \fI(function template)\fP + set_intersection computes the intersection of two sets + \fI(function template)\fP + ranges::set_symmetric_difference computes the symmetric difference between two sets + (C++20) (niebloid) diff --git a/man/std::set_terminate.3 b/man/std::set_terminate.3 index 230144d12..4674eb437 100644 --- a/man/std::set_terminate.3 +++ b/man/std::set_terminate.3 @@ -1,10 +1,21 @@ -.TH std::set_terminate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_terminate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_terminate \- std::set_terminate + .SH Synopsis Defined in header - std::terminate_handler set_terminate( std::terminate_handler f ) + std::terminate_handler set_terminate( std::terminate_handler f ) \fI(until C++11)\fP + throw(); + std::terminate_handler set_terminate( std::terminate_handler f ) \fI(since C++11)\fP + noexcept; Makes f the new global terminate handler function and returns the previously - installed std::terminate_handler. + installed std::terminate_handler. f shall terminate execution of the program without + returning to its caller, otherwise the behavior is undefined. + + This function is thread-safe. Every call to std::set_terminate + synchronizes-with (see std::memory_order) subsequent calls to \fI(since C++11)\fP + std::set_terminate and std::get_terminate. .SH Parameters @@ -15,18 +26,136 @@ The previously-installed terminate handler, or a null pointer value if none was installed. -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::set_terminate([]() + { + std::cout << "Unhandled exception\\n" << std::flush; + std::abort(); + }); + throw 1; + } + +.SH Possible output: + + Unhandled exception + bash: line 7: 7743 Aborted (core dumped) ./a.out + + The terminate handler will also work for launched threads, so it can be used as an + alternative to wrapping the thread function with a try/catch block. In the following + example, since the exception is unhandled, std::terminate will be called. + + +// Run this code + + #include + #include + + void run() + { + throw std::runtime_error("Thread failure"); + } + + int main() + { + try + { + std::thread t{run}; + t.join(); + return EXIT_SUCCESS; + } + catch (const std::exception& exc) + { + std::cerr << "Exception: " << exc.what() << '\\n'; + } + catch (...) + { + std::cerr << "Unknown exception caught\\n"; + } + return EXIT_FAILURE; + } + +.SH Possible output: + + terminate called after throwing an instance of 'std::runtime_error' + what(): Thread failure + Aborted (core dumped) + + With the introduction of the terminate handler, the exception thrown from the + non-main thread can be analyzed, and exit can be gracefully performed. + + +// Run this code + + #include + #include + + class foo + { + public: + foo() { std::cerr << "foo::foo()\\n"; } + ~foo() { std::cerr << "foo::~foo()\\n"; } + }; + + // Static object, expecting destructor on exit + foo f; + + void run() + { + throw std::runtime_error("Thread failure"); + } + + int main() + { + std::set_terminate([]() + { + try + { + std::exception_ptr eptr{std::current_exception()}; + if (eptr) + { + std::rethrow_exception(eptr); + } + else + { + std::cerr << "Exiting without exception\\n"; + } + } + catch (const std::exception& exc) + { + std::cerr << "Exception: " << exc.what() << '\\n'; + } + catch (...) + { + std::cerr << "Unknown exception caught\\n"; + } + std::exit(EXIT_FAILURE); + }); + + std::thread t{run}; + t.join(); + } + +.SH Output: - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + foo::foo() + Exception: Thread failure + foo::~foo() .SH See also terminate function called when exception handling fails - \fI(function)\fP + \fI(function)\fP get_terminate obtains the current terminate_handler - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP terminate_handler the type of the function called by std::terminate - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::set_unexpected.3 b/man/std::set_unexpected.3 index 74b42c3f3..c6061ba65 100644 --- a/man/std::set_unexpected.3 +++ b/man/std::set_unexpected.3 @@ -1,11 +1,22 @@ -.TH std::set_unexpected 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_unexpected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_unexpected \- std::set_unexpected + .SH Synopsis Defined in header - std::unexpected_handler set_unexpected( std::unexpected_handler f ) + std::unexpected_handler set_unexpected( std::unexpected_handler \fI(until C++11)\fP + f ) throw(); + std::unexpected_handler set_unexpected( std::unexpected_handler \fI(since C++11)\fP + f ) noexcept; \fB(deprecated)\fP + (removed in C++17) Makes f the new global std::unexpected_handler and returns the previously installed std::unexpected_handler. + This function is thread-safe. Every call to std::set_unexpected + synchronizes-with (see std::memory_order) the subsequent calls to \fI(since C++11)\fP + std::set_unexpected and std::get_unexpected + .SH Parameters f - pointer to function of type std::unexpected_handler, or null pointer @@ -15,18 +26,12 @@ The previously-installed unexpected handler, or a null pointer value if none was installed. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH See also - unexpected function called when dynamic exception specification is violated - \fB(deprecated)\fP \fI(function)\fP - get_unexpected obtains the current unexpected_handler - \fI(C++11)\fP\fB(deprecated)\fP \fI(function)\fP - unexpected_handler the type of the function called by std::unexpected - \fB(deprecated)\fP \fI(typedef)\fP + unexpected function called when dynamic exception specification is + (removed in C++17) violated + \fI(function)\fP + get_unexpected obtains the current unexpected_handler + \fI(C++11)\fP(removed in C++17) \fI(function)\fP + unexpected_handler the type of the function called by std::unexpected + (removed in C++17) \fI(typedef)\fP diff --git a/man/std::set_union.3 b/man/std::set_union.3 index 7ab80596f..bcf71cc6e 100644 --- a/man/std::set_union.3 +++ b/man/std::set_union.3 @@ -1,58 +1,108 @@ -.TH std::set_union 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::set_union 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::set_union \- std::set_union + .SH Synopsis Defined in header - template< class InputIt1, class InputIt2, class OutputIt > + template< class InputIt1, class InputIt2, class OutputIt + > - OutputIt set_union( InputIt1 first1, InputIt1 last1, \fB(1)\fP + OutputIt set_union( InputIt1 first1, InputIt1 last1, \fB(1)\fP (constexpr since C++20) InputIt2 first2, InputIt2 last2, OutputIt d_first ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + ForwardIt3 > + ForwardIt3 set_union( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 \fB(2)\fP \fI(since C++17)\fP + last1, + ForwardIt2 first2, ForwardIt2 + last2, + + ForwardIt3 d_first ); template< class InputIt1, class InputIt2, class OutputIt, class Compare > - OutputIt set_union( InputIt1 first1, InputIt1 last1, \fB(2)\fP + OutputIt set_union( InputIt1 first1, InputIt1 last1, \fB(3)\fP (constexpr since C++20) InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class ForwardIt3, class Compare > + ForwardIt3 set_union( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 \fB(4)\fP \fI(since C++17)\fP + last1, + ForwardIt2 first2, ForwardIt2 + last2, + + ForwardIt3 d_first, Compare comp + ); - Constructs a sorted range beginning at d_first consisting of all elements present in - one or both sorted ranges [first1, last1) and [first2, last2). + Constructs a sorted union beginning at d_first consisting of the set of elements + present in one or both sorted ranges [first1, last1) and [first2, last2). - 1) Expects both input ranges to be sorted with operator< - 2) Expects them to be sorted with the given comparison function comp + If [first1, last1) contains m elements that are equivalent to each other and + [first2, last2) contains n elements that are equivalent to them, then all m elements + will be copied from [first1, last1) to the output range, preserving order, and then + the final std::max(n - m, 0) elements will be copied from [first2, last2) to the + output range, also preserving order. - If some element is found m times in [first1, last1) and n times in [first2, last2), - then all m elements will be copied from [first1, last1) to d_first, preserving - order, and then exactly std::max(n-m, 0) elements will be copied from [first2, - last2) to d_first, also preserving order. + 1) If [first1, last1) or [first2, last2) is not sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, the behavior is undefined. + 3) If [first1, last1) or [first2, last2) is not sorted with respect to comp, the + behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if - The resulting range cannot overlap with either of the input ranges. + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If the output range overlaps with [first1, last1) or [first2, last2), the behavior + is undefined. .SH Parameters first1, last1 - the first input sorted range first2, last2 - the second input sorted range + d_first - the beginning of the output range + policy - the execution policy to use. See execution policy for details. comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument - is less (i.e. is ordered before) the second element. + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. The signature of the comparison function should be equivalent to the following: - comp - - bool cmp(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. + converted to both Type1 and Type2. .SH Type requirements - - InputIt1 must meet the requirements of InputIterator. + InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. + - + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. - - InputIt2 must meet the requirements of InputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - OutputIt must meet the requirements of OutputIterator. + Compare must meet the requirements of Compare. .SH Return value @@ -60,93 +110,156 @@ .SH Complexity - At most 2·(N[1]+N[2]-1) comparisons, where N[1] = std::distance(first1, last1) and - N[2] = std::distance(first2, last2). + Given \\(\\scriptsize N_1\\)N + 1 as std::distance(first1, last1) and \\(\\scriptsize N_2\\)N + 2 as std::distance(first2, last2): + + 1,2) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) At most \\(\\scriptsize 2 \\cdot (N_1+N_2)-1\\)2⋅(N + 1+N + 2)-1 applications of the comparison function comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - OutputIt set_union(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first) - { - for (; first1 != last1; ++d_first) { - if (first2 == last2) - return std::copy(first1, last1, d_first); - if (*first2 < *first1) { - *d_first = *first2++; - } else { - *d_first = *first1; - if (!(*first1 < *first2)) - ++first2; - ++first1; - } - } - return std::copy(first2, last2, d_first); - } -.SH Second version - template - OutputIt set_union(InputIt1 first1, InputIt1 last1, - InputIt2 first2, InputIt2 last2, - OutputIt d_first, Compare comp) - { - for (; first1 != last1; ++d_first) { - if (first2 == last2) - return std::copy(first1, last1, d_first); - if (comp(*first2, *first1)) { - *d_first = *first2++; - } else { - *d_first = *first1; - if (!comp(*first1, *first2)) - ++first2; - ++first1; - } - } - return std::copy(first2, last2, d_first); - } + set_union \fB(1)\fP + template + OutputIt set_union(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first) + { + for (; first1 != last1; ++d_first) + { + if (first2 == last2) + return std::copy(first1, last1, d_first); + + if (*first2 < *first1) + *d_first = *first2++; + else + { + *d_first = *first1; + if (!(*first1 < *first2)) + ++first2; + ++first1; + } + } + return std::copy(first2, last2, d_first); + } + set_union \fB(3)\fP + template + OutputIt set_union(InputIt1 first1, InputIt1 last1, + InputIt2 first2, InputIt2 last2, OutputIt d_first, Compare comp) + { + for (; first1 != last1; ++d_first) + { + if (first2 == last2) + // Finished range 2, include the rest of range 1: + return std::copy(first1, last1, d_first); + + if (comp(*first2, *first1)) + *d_first = *first2++; + else + { + *d_first = *first1; + if (!comp(*first1, *first2)) // Equivalent => don't need to include *first2. + ++first2; + ++first1; + } + } + // Finished range 1, include the rest of range 2: + return std::copy(first2, last2, d_first); + } + +.SH Notes + + This algorithm performs a similar task as std::merge does. Both consume two sorted + input ranges and produce a sorted output with elements from both inputs. The + difference between these two algorithms is with handling values from both input + ranges which compare equivalent (see notes on LessThanComparable). If any equivalent + values appeared n times in the first range and m times in the second, std::merge + would output all n + m occurrences whereas std::set_union would output std::max(n, + m) ones only. So std::merge outputs exactly std::distance(first1, last1) + + std::distance(first2, last2) values and std::set_union may produce fewer. .SH Example - Example with vectors : - // Run this code - #include - #include - #include #include + #include #include - - int main() + #include + + void println(const std::vector& v) { - std::vector v1 = {1, 2, 3, 4, 5}; - std::vector v2 = { 3, 4, 5, 6, 7}; - std::vector dest1; - - std::set_union(v1.begin(), v1.end(), - v2.begin(), v2.end(), - std::back_inserter(dest1)); - - for (const auto &i : dest1) { + for (int i : v) std::cout << i << ' '; - } std::cout << '\\n'; } + int main() + { + std::vector v1, v2, dest; + + v1 = {1, 2, 3, 4, 5}; + v2 = {3, 4, 5, 6, 7}; + + std::set_union(v1.cbegin(), v1.cend(), + v2.cbegin(), v2.cend(), + std::back_inserter(dest)); + println(dest); + + dest.clear(); + + v1 = {1, 2, 3, 4, 5, 5, 5}; + v2 = {3, 4, 5, 6, 7}; + + std::set_union(v1.cbegin(), v1.cend(), + v2.cbegin(), v2.cend(), + std::back_inserter(dest)); + println(dest); + } + .SH Output: 1 2 3 4 5 6 7 + 1 2 3 4 5 5 5 6 7 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 291 C++98 it was unspecified how to handle equivalent specified + elements in the input ranges .SH See also - includes returns true if one set is a subset of another - \fI(function template)\fP + includes returns true if one sequence is a subsequence of another + \fI(function template)\fP + merge merges two sorted ranges + \fI(function template)\fP set_difference computes the difference between two sets - \fI(function template)\fP + \fI(function template)\fP set_intersection computes the intersection of two sets - \fI(function template)\fP + \fI(function template)\fP set_symmetric_difference computes the symmetric difference between two sets - \fI(function template)\fP + \fI(function template)\fP + ranges::set_union computes the union of two sets + (C++20) (niebloid) diff --git a/man/std::setbase.3 b/man/std::setbase.3 index 47b4a7ffc..9009d3753 100644 --- a/man/std::setbase.3 +++ b/man/std::setbase.3 @@ -1,4 +1,7 @@ -.TH std::setbase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setbase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setbase \- std::setbase + .SH Synopsis Defined in header /*unspecified*/ setbase( int base ); @@ -7,8 +10,8 @@ or in >> setbase(base), changes the basefield flag of the stream out or in, depending on the value of base: - * the value 16 sets basefield to std::ios_base::hex - * the value 8 sets std::ios_base::oct + * the value 16 sets basefield to std::ios_base::hex. + * the value 8 sets std::ios_base::oct. * the value 10 sets std::ios_base::dec. Values of base other than 8, 10, or 16 reset basefield to zero, which corresponds to @@ -20,39 +23,55 @@ .SH Return value - Returns an object of unspecified type such that if str is the name of an output - stream of type std::basic_ostream or std::basic_istream, then the expression str << setbase(base) or str >> setbase(base) behaves as - if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << setbase(base) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, base) + * if in is an object of type std::basic_istream, the expression in + >> setbase(base) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, base) + + where the function f is defined as: - str.setf(base == 8 ? std::ios_base::oct : - base == 10 ? std::ios_base::dec : - base == 16 ? std::ios_base::hex : - std::ios_base::fmtflags\fB(0)\fP, - std::ios_base::basefield); + void f(std::ios_base& str, int base) + { + // set basefield + str.setf(base == 8 ? std::ios_base::oct : + base == 10 ? std::ios_base::dec : + base == 16 ? std::ios_base::hex : + std::ios_base::fmtflags\fB(0)\fP, std::ios_base::basefield); + } .SH Example - + // Run this code + #include #include #include - #include + int main() { std::cout << "Parsing string \\"10 0x10 010\\"\\n"; - + int n1, n2, n3; std::istringstream s("10 0x10 010"); + s >> std::setbase(16) >> n1 >> n2 >> n3; std::cout << "hexadecimal parse: " << n1 << ' ' << n2 << ' ' << n3 << '\\n'; - + s.clear(); s.seekg(0); + s >> std::setbase(0) >> n1 >> n2 >> n3; std::cout << "prefix-dependent parse: " << n1 << ' ' << n2 << ' ' << n3 << '\\n'; - + std::cout << "hex output: " << std::setbase(16) << std::showbase << n1 << ' ' << n2 << ' ' << n3 << '\\n'; } @@ -64,10 +83,19 @@ prefix-dependent parse: 10 16 8 hex output: 0xa 0x10 0x8 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 183 C++98 setbase could only be used with streams usable with any + of type std::ostream or std::istream character stream + .SH See also dec changes the base used for integer I/O - hex \fI(function)\fP + hex \fI(function)\fP oct showbase controls whether prefix is used to indicate numeric base - noshowbase \fI(function)\fP + noshowbase \fI(function)\fP diff --git a/man/std::setbuf.3 b/man/std::setbuf.3 index f98dd01b3..a5761d61b 100644 --- a/man/std::setbuf.3 +++ b/man/std::setbuf.3 @@ -1,29 +1,78 @@ -.TH std::setbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setbuf \- std::setbuf + .SH Synopsis Defined in header void setbuf( std::FILE* stream, char* buffer ); Sets the internal buffer to use for I/O operations performed on the C stream stream. - If buffer is not null, equivalent to std::setvbuf(stream, buffer, _IOFBF, BUFSIZ) + If buffer is not null, equivalent to std::setvbuf(stream, buffer, _IOFBF, BUFSIZ). - If buffer is null, equivalent to std::setvbuf(stream, NULL, _IONBF, 0), which turns - off buffering. + If buffer is null, equivalent to std::setvbuf(stream, nullptr, _IONBF, 0), which + turns off buffering. .SH Parameters - stream - the file stream to set the buffer to. - pointer to a buffer for the stream to use. If NULL is supplied, the - buffer - buffering is turned off. If not null, must be able to hold at least BUFSIZ - characters + stream - the file stream to set the buffer to + pointer to a buffer for the stream to use. If a null pointer is supplied, + buffer - the buffering is turned off. If not null, must be able to hold at least + BUFSIZ characters .SH Return value \fI(none)\fP +.SH Notes + + If BUFSIZ is not the appropriate buffer size, std::setvbuf can be used to change it. + + std::setvbuf should also be used to detect errors, since std::setbuf does not + indicate success or failure. + + This function may only be used after stream has been associated with an open file, + but before any other operation (other than a failed call to + std::setbuf/std::setvbuf). + + A common error is setting the buffer of stdin or stdout to an array whose lifetime + ends before the program terminates: + + int main() + { + char buf[BUFSIZ]; + std::setbuf(stdin, buf); + } // lifetime of buf ends, undefined behavior + +.SH Example + + std::setbuf may be used to disable buffering on streams that require immediate + output. + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::chrono_literals; + + std::setbuf(stdout, nullptr); // unbuffered stdout + std::putchar('a'); // appears immediately on unbuffered stream + std::this_thread::sleep_for(1s); + std::putchar('b'); + } + +.SH Output: + + ab + .SH See also setvbuf sets the buffer and its size for a file stream - \fI(function)\fP + \fI(function)\fP C documentation for setbuf diff --git a/man/std::setfill.3 b/man/std::setfill.3 index 6f79ceb64..45f4d741e 100644 --- a/man/std::setfill.3 +++ b/man/std::setfill.3 @@ -1,4 +1,7 @@ -.TH std::setfill 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setfill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setfill \- std::setfill + .SH Synopsis Defined in header template< class CharT > @@ -13,37 +16,62 @@ .SH Return value - Returns an object of unspecified type such that if out is the name of an output - stream of type std::basic_ostream, then the expression out << - setfill(n) behaves as if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << setfill(c) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, c) + + where the function f is defined as: + + template + void f(std::basic_ios& str, CharT c) + { + // set fill character + str.fill(c); + } + +.SH Notes - out.fill(n); + The current fill character may be obtained with std::ostream::fill. .SH Example - + // Run this code - #include #include + #include + int main() { - std::cout << "default fill: " << std::setw(10) << 42 << '\\n' - << "setfill('*'): " << std::setfill('*') - << std::setw(10) << 42 << '\\n'; + std::cout << "default fill: [" << std::setw(10) << 42 << "]\\n" + << "setfill('*'): [" << std::setfill('*') + << std::setw(10) << 42 << "]\\n"; } .SH Output: - default fill: 42 - setfill('*'): ********42 + default fill: [ 42] + setfill('*'): [********42] + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 183 C++98 setbase could only be used with usable with any output + streams of type std::ostream character stream .SH See also fill manages the fill character - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP internal sets the placement of fill characters - left \fI(function)\fP + left \fI(function)\fP right setw changes the width of the next input/output field - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::setiosflags.3 b/man/std::setiosflags.3 index a96b6f12c..49c691c9b 100644 --- a/man/std::setiosflags.3 +++ b/man/std::setiosflags.3 @@ -1,7 +1,10 @@ -.TH std::setiosflags 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setiosflags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setiosflags \- std::setiosflags + .SH Synopsis Defined in header - /*unspecified*/ setiosflags( std::ios_base::fmt_flags mask ); + /*unspecified*/ setiosflags( std::ios_base::fmtflags mask ); When used in an expression out << setiosflags(mask) or in >> setiosflags(mask), sets all format flags of the stream out or in as specified by the mask. @@ -12,36 +15,59 @@ .SH Return value - Returns an object of unspecified type such that if str is the name of an output - stream of type std::basic_ostream or std::basic_istream, then the expression str << setiosflags(mask) or str >> setiosflags(mask) - behaves as if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << setiosflags(mask) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, mask) + * if in is an object of type std::basic_istream, the expression in + >> setiosflags(mask) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, mask) + + where the function f is defined as: - str.setf(mask); + void f(std::ios_base& str, std::ios_base::fmtflags mask) + { + // set specified flags + str.setf(mask); + } .SH Example - + // Run this code - #include #include - + #include + int main() { - std::cout << std::resetiosflags(std::ios_base::dec) - << std::setiosflags( std::ios_base::hex - | std::ios_base::uppercase - | std::ios_base::showbase) << 42 << '\\n'; + std::cout << std::resetiosflags(std::ios_base::dec) + << std::setiosflags( std::ios_base::hex + | std::ios_base::uppercase + | std::ios_base::showbase) << 42 << '\\n'; } .SH Output: 0X2A + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 183 C++98 setiosflags could only be used with streams usable with any + of type std::ostream or std::istream character stream + .SH See also setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::setlocale.3 b/man/std::setlocale.3 index 38fc92f92..7b1167ff9 100644 --- a/man/std::setlocale.3 +++ b/man/std::setlocale.3 @@ -1,7 +1,10 @@ -.TH std::setlocale 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setlocale 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setlocale \- std::setlocale + .SH Synopsis Defined in header - char* setlocale( int category, const char* locale); + char* setlocale( int category, const char* locale ); The setlocale function installs the specified system locale or its portion as the new C locale. The modifications remain in effect and influences the execution of all @@ -19,6 +22,10 @@ Pointer to a narrow null-terminated string identifying the C locale after applying the changes, if any, or null pointer on failure. + A copy of the returned string along with the category used in this call to + std::setlocale may be used later in the program to restore the locale back to the + state at the end of this call. + .SH Notes During program startup, the equivalent of std::setlocale(LC_ALL, "C"); is executed @@ -39,45 +46,72 @@ std::strerror, std::wcstombs, std::isgraph, std::iswcntrl, std::iswxdigit, std::strtod, std::wcsxfrm, std::islower, std::iswctype, std::isxdigit. + POSIX also defines a locale named "POSIX", which is always accessible and is exactly + equivalent to the default minimal "C" locale. + + POSIX also specifies that the returned pointer, not just the contents of the + pointed-to string, may be invalidated by subsequent calls to setlocale. + .SH Example - + // Run this code - #include #include + #include #include #include - + #include + #include + int main() { - // the C locale will be UTF-8 enabled English; - // decimal dot will be German - // date and time formatting will be Japanese - std::setlocale(LC_ALL, "en_US.UTF-8"); - std::setlocale(LC_NUMERIC, "de_DE"); - std::setlocale(LC_TIME, "ja_JP"); - - wchar_t str[100]; - std::time_t t = std::time(NULL); - std::wcsftime(str, 100, L"%A %c", std::localtime(&t)); - std::wprintf(L"Number: %.2f\\nDate: %Ls\\n", 3.14, str); + // Make a "deep copy" of current locale name. + std::string prev_loc = std::setlocale(LC_ALL, nullptr); + + // The C locale will be UTF-8 enabled English, + // decimal dot will be German, + // date and time formatting will be Japanese. + if (const char* loc = std::setlocale(LC_ALL, "en_US.UTF-8")) + std::wprintf(L"New LC_ALL locale: %s\\n", loc); + if (const char* loc = std::setlocale(LC_NUMERIC, "de_DE.UTF-8")) + std::wprintf(L"New LC_NUMERIC locale: %s\\n", loc); + if (const char* loc = std::setlocale(LC_TIME, "ja_JP.UTF-8")) + std::wprintf(L"New LC_TIME locale: %s\\n", loc); + + wchar_t buf[100]; + std::time_t t = std::time(nullptr); + std::wcsftime(buf, std::size(buf), L"%A %c", std::localtime(&t)); + std::wprintf(L"Number: %.2f\\nDate: %Ls\\n", 3.14, buf); + + // Restore the previous locale. + if (const char* loc = std::setlocale(LC_ALL, prev_loc.c_str())) + std::wprintf(L"Restorred LC_ALL locale: %s\\n", loc); } -.SH Output: +.SH Possible output: + New LC_ALL locale: en_US.UTF-8 + New LC_NUMERIC locale: de_DE.UTF-8 + New LC_TIME locale: ja_JP.UTF-8 Number: 3,14 - Date: 月曜日 2011年12月19日 18時04分40秒 + Date: 日曜日 2022年11月06日 20時40分59秒 + Restorred LC_ALL locale: C .SH See also LC_ALL LC_COLLATE LC_CTYPE locale categories for std::setlocale - LC_MONETARY (macro constant) + LC_MONETARY (macro constant) LC_NUMERIC LC_TIME locale set of polymorphic facets that encapsulate cultural differences - \fI(class)\fP + \fI(class)\fP C documentation for setlocale + +.SH External links + + 1. List of Windows locale names. + 2. List of Linux locale names. diff --git a/man/std::setprecision.3 b/man/std::setprecision.3 index 1dd2184c8..7c960f6f3 100644 --- a/man/std::setprecision.3 +++ b/man/std::setprecision.3 @@ -1,4 +1,7 @@ -.TH std::setprecision 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setprecision 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setprecision \- std::setprecision + .SH Synopsis Defined in header /*unspecified*/ setprecision( int n ); @@ -12,43 +15,97 @@ .SH Return value - Returns an object of unspecified type such that if str is the name of an output - stream of type std::basic_ostream or an input stream of type - std::basic_istream, then the expression str << setprecision(n) or str - >> setprecision(n) behaves as if the following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << setprecision(n) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, n) + * if in is an object of type std::basic_istream, the expression in + >> setprecision(n) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, n) + + where the function f is defined as: - str.precision(n); + void f(std::ios_base& str, int n) + { + // set precision + str.precision(n); + } .SH Example - + // Run this code - #include #include - #include + #include #include + #include + int main() { - const long double pi = std::acos(-1.L); - std::cout << "default precision (6): " << pi << '\\n' - << "std::precision(10): " << std::setprecision(10) << pi << '\\n' - << "max precision: " - << std::setprecision(std::numeric_limits::digits10) - << pi << '\\n'; + constexpr long double pi{std::numbers::pi_v}; + + const auto default_precision{std::cout.precision()}; + constexpr auto max_precision{std::numeric_limits::digits10 + 1}; + + std::cout << "default precision: " << default_precision << '\\n' + << "maximum precision: " << max_precision << "\\n\\n" + "precision: pi:\\n"; + + for (int p{0}; p <= max_precision; ++p) + std::cout << std::setw(2) << p << " " << std::setprecision(p) << pi << '\\n'; + + std::cout << std::setprecision(default_precision); // restore defaults } .SH Output: - default precision \fB(6)\fP: 3.14159 - std::precision\fB(10)\fP: 3.141592654 - max precision: 3.14159265358979324 + default precision: 6 + maximum precision: 19 + + precision: pi: + 0 3 + 1 3 + 2 3.1 + 3 3.14 + 4 3.142 + 5 3.1416 + 6 3.14159 + 7 3.141593 + 8 3.1415927 + 9 3.14159265 + 10 3.141592654 + 11 3.1415926536 + 12 3.14159265359 + 13 3.14159265359 + 14 3.1415926535898 + 15 3.14159265358979 + 16 3.141592653589793 + 17 3.1415926535897932 + 18 3.14159265358979324 + 19 3.141592653589793239 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 183 C++98 setprecision could only be used with streams usable with any + of type std::ostream or std::istream character stream .SH See also fixed scientific hexfloat changes formatting used for floating-point I/O - defaultfloat \fI(function)\fP + defaultfloat \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP diff --git a/man/std::setvbuf.3 b/man/std::setvbuf.3 index 41d562e4f..d3c0fdea7 100644 --- a/man/std::setvbuf.3 +++ b/man/std::setvbuf.3 @@ -1,14 +1,26 @@ -.TH std::setvbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setvbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setvbuf \- std::setvbuf + .SH Synopsis Defined in header int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size ); - Sets the internal buffer of the given file stream stream. + Changes the buffering mode of the given file stream stream as indicated by the + argument mode. In addition, + + * If buffer is a null pointer, resizes the internal buffer to size. + * If buffer is not a null pointer, instructs the stream to use the user-provided + buffer of size size beginning at buffer. The stream must be closed (with + std::fclose) before the lifetime of the array pointed to by buffer ends. The + contents of the array after a successful call to std::setvbuf are indeterminate + and any attempt to use it is undefined behavior. .SH Parameters stream - the file stream to set the buffer to - buffer - pointer to a buffer for the stream to use + buffer - pointer to a buffer for the stream to use or null pointer to change size + and mode only buffering mode to use. It can be one of the following values: mode - _IOFBF full buffering @@ -23,15 +35,81 @@ .SH Notes This function may only be used after stream has been associated with an open file, - but before any other operation. + but before any other operation (other than a failed call to + std::setbuf/std::setvbuf). + + Not all size bytes will necessarily be used for buffering: the actual buffer size is + usually rounded down to a multiple of 2, a multiple of page size, etc. + + On many implementations, line buffering is only available for terminal input + streams. + + A common error is setting the buffer of stdin or stdout to an array whose lifetime + ends before the program terminates: + + int main() + { + char buf[BUFSIZ]; + std::setbuf(stdin, buf); + } // lifetime of buf ends, undefined behavior + + The default buffer size BUFSIZ is expected to be the most efficient buffer size for + file I/O on the implementation, but POSIX fstat often provides a better estimate. + +.SH Example + + One use case for changing buffer size is when a better size is known. + - buffer may be null, in which case this call only resizes the internal buffer. +// Run this code + + #include + #include + #include + #include + + int main() + { + std::FILE* fp = std::fopen("/tmp/test.txt", "w+"); + if (!fp) + { + std::perror("fopen"); + return EXIT_FAILURE; + } + + struct stat stats; + if (fstat(fileno(fp), &stats) == -1) // POSIX only + { + std::perror("fstat"); + return EXIT_FAILURE; + } + + std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is " + << stats.st_blksize << '\\n'; + if (std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0) + { + std::perror("setvbuf failed"); // POSIX version sets errno + return EXIT_FAILURE; + } + + // Read entire file: use truss/strace to observe the read(2) syscalls used + for (int ch; (ch = std::fgetc(fp)) != EOF;) + {} + + std::fclose(fp); + return EXIT_SUCCESS; + } + +.SH Possible output: + + BUFSIZ is 8192, but optimal block size is 65536 .SH See also setbuf sets the buffer for a file stream - \fI(function)\fP + \fI(function)\fP setbuf provides user-supplied buffer or turns this filebuf unbuffered - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + C documentation for setvbuf diff --git a/man/std::setw.3 b/man/std::setw.3 index 155c6af6c..93fef1483 100644 --- a/man/std::setw.3 +++ b/man/std::setw.3 @@ -1,10 +1,16 @@ -.TH std::setw 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::setw 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::setw \- std::setw + .SH Synopsis Defined in header - /*unspecified*/ setw( int n ); + /* unspecified */ setw( int n ); + + When used in an expression out << std::setw(n) or in >> std::setw(n), sets the width + parameter of the stream out or in to exactly n. - When used in an expression out << setw(n) or in >> setw(n), sets the width parameter - of the stream out or in to exactly n. + Some operations reset the width to zero (see below), so std::setw may need to be + repeatedly called to set the width for multiple operations. .SH Parameters @@ -12,12 +18,26 @@ .SH Return value - Returns an object of unspecified type such that if str is the name of an output - stream of type std::basic_ostream or std::basic_istream, then the expression str << setw(n) or str >> setw(n) behaves as if the - following code was executed: + An object of unspecified type such that + + * if out is an object of type std::basic_ostream, the expression + out << setw(n) + * has type std::basic_ostream& + * has value out + * behaves as if it called f(out, n) + * if in is an object of type std::basic_istream, the expression in + >> setw(n) + * has type std::basic_istream& + * has value in + * behaves as if it called f(in, n) - str.width(n); + where the function f is defined as: + + void f(std::ios_base& str, int n) + { + // set width + str.width(n); + } .SH Notes @@ -27,31 +47,39 @@ * Input * operator>>(basic_istream&, basic_string&) - * operator>>(basic_ostream&, char*) - + * operator>>(basic_istream&, char*) * Output - * Overloads 1-7 of basic_ostream::operator<<() (at Stage 3 of num_put::put()) + * Overloads of basic_ostream::operator<<() that take arithmetic types or void + pointers (at Stage 3 of num_put::put()) * operator<<(basic_ostream&, char) and operator<<(basic_ostream&, char*) - * operator<<(basic_osteam&, basic_string&) + * operator<<(basic_ostream&, basic_string&) * std::put_money (inside money_put::put()) + * std::quoted (when used with an output stream) + + The exact effects this modifier has on the input and output vary between the + individual I/O functions and are described at each operator<< and operator>> + overload page individually. .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { - std::cout << "no setw:" << 42 << '\\n' - << "setw(6):" << std::setw(6) << 42 << '\\n' - << "setw(6), several elements: " << 89 << std::setw(6) << 12 << 34 << '\\n'; + std::cout << "no setw: [" << 42 << "]\\n" + << "setw(6): [" << std::setw(6) << 42 << "]\\n" + << "no setw, several elements: [" << 89 << 12 << 34 << "]\\n" + << "setw(6), several elements: [" << 89 << std::setw(6) << 12 << 34 << "]\\n"; + std::istringstream is("hello, world"); char arr[10]; + is >> std::setw(6) >> arr; std::cout << "Input from \\"" << is.str() << "\\" with setw(6) gave \\"" << arr << "\\"\\n"; @@ -59,14 +87,29 @@ .SH Output: - no setw:42 - setw\fB(6)\fP: 42 - setw\fB(6)\fP, several elements: 89 1234 + no setw: [42] + setw\fB(6)\fP: [ 42] + no setw, several elements: [891234] + setw\fB(6)\fP, several elements: [89 1234] Input from "hello, world" with setw\fB(6)\fP gave "hello" + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 183 C++98 setw could only be used with streams of usable with any + type std::ostream or std::istream character stream + .SH See also - width manages field width - \fI(public member function of std::ios_base)\fP - setfill changes the fill character - \fI(function template)\fP + width manages field width + \fI(public member function of std::ios_base)\fP + setfill changes the fill character + \fI(function template)\fP + internal sets the placement of fill characters + left \fI(function)\fP + right + showbase controls whether prefix is used to indicate numeric base + noshowbase \fI(function)\fP diff --git a/man/std::shared_future.3 b/man/std::shared_future.3 index e1f705df0..bf7a5a11c 100644 --- a/man/std::shared_future.3 +++ b/man/std::shared_future.3 @@ -1,11 +1,22 @@ -.TH std::shared_future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future \- std::shared_future + .SH Synopsis Defined in header - template< class T > class shared_future; \fB(1)\fP \fI(since C++11)\fP - template< class T > class shared_future; \fB(2)\fP \fI(since C++11)\fP - template<> class shared_future; \fB(3)\fP \fI(since C++11)\fP + template< class T > class shared_future; \fB(1)\fP \fI(since C++11)\fP + template< class T > class shared_future; \fB(2)\fP \fI(since C++11)\fP + template<> class shared_future; \fB(3)\fP \fI(since C++11)\fP + + The class template std::shared_future provides a mechanism to access the result of + asynchronous operations, similar to std::future, except that multiple threads are + allowed to wait for the same shared state. Unlike std::future, which is only + moveable (so only one instance can refer to any particular asynchronous result), + std::shared_future is copyable and multiple shared future objects may refer to the + same shared state. - This section is incomplete + Access to the same shared state from multiple threads is safe if each thread does it + through its own copy of a shared_future object. .SH Member functions @@ -17,66 +28,69 @@ \fI(public member function)\fP .SH Getting the result get returns the result - \fI(public member function)\fP + \fI(public member function)\fP .SH State valid checks if the future has a shared state - \fI(public member function)\fP + \fI(public member function)\fP wait waits for the result to become available - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available until specified wait_until time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP .SH Example A shared_future may be used to signal multiple threads simultaneously, similar to - std::condition_variable::notify_all() + std::condition_variable::notify_all(). + - // Run this code - #include - #include #include - + #include + #include + int main() { std::promise ready_promise, t1_ready_promise, t2_ready_promise; std::shared_future ready_future(ready_promise.get_future()); - + std::chrono::time_point start; - - auto fun1 = [&]() -> std::chrono::duration + + auto fun1 = [&, ready_future]() -> std::chrono::duration { t1_ready_promise.set_value(); ready_future.wait(); // waits for the signal from main() return std::chrono::high_resolution_clock::now() - start; }; - - - auto fun2 = [&]() -> std::chrono::duration + + + auto fun2 = [&, ready_future]() -> std::chrono::duration { t2_ready_promise.set_value(); ready_future.wait(); // waits for the signal from main() return std::chrono::high_resolution_clock::now() - start; }; - + + auto fut1 = t1_ready_promise.get_future(); + auto fut2 = t2_ready_promise.get_future(); + auto result1 = std::async(std::launch::async, fun1); auto result2 = std::async(std::launch::async, fun2); - + // wait for the threads to become ready - t1_ready_promise.get_future().wait(); - t2_ready_promise.get_future().wait(); - + fut1.wait(); + fut2.wait(); + // the threads are ready, start the clock start = std::chrono::high_resolution_clock::now(); - + // signal the threads to go ready_promise.set_value(); - + std::cout << "Thread 1 received the signal " << result1.get().count() << " ms after start\\n" << "Thread 2 received the signal " @@ -88,6 +102,10 @@ Thread 1 received the signal 0.072 ms after start Thread 2 received the signal 0.041 ms after start -.SH Category: +.SH See also - * Todo without reason + async runs a function asynchronously (potentially in a new thread) and returns a + \fI(C++11)\fP std::future that will hold the result + \fI(function template)\fP + future waits for a value that is set asynchronously + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::shared_future::get.3 b/man/std::shared_future::get.3 index 1e362a020..171a232eb 100644 --- a/man/std::shared_future::get.3 +++ b/man/std::shared_future::get.3 @@ -1,32 +1,27 @@ -.TH std::shared_future::get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - const T& get() const; \fB(1)\fP (member only of generic shared_future template) - \fI(since C++11)\fP - T& get() const; \fB(2)\fP (member only of shared_future template specialization) - \fI(since C++11)\fP - (member only of shared_future template - void get() const; \fB(3)\fP specialization) - \fI(since C++11)\fP - - The get method waits until the shared_future has a valid result and (depending on - which template is used) retrieves it. It effectively calls wait() in order to wait - for the result. - - The generic template and two template specializations each contain a single version - of get. The three versions of get differ only in the return type. +.TH std::shared_future::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::get \- std::shared_future::get - The behavior is undefined if valid() is false before the call to this function. +.SH Synopsis + Main template + const T& get() const; \fB(1)\fP \fI(since C++11)\fP + std::shared_future specializations + T& get() const; \fB(2)\fP \fI(since C++11)\fP + std::shared_future specialization + void get() const; \fB(3)\fP \fI(since C++11)\fP -.SH Parameters + The get member function waits (by calling wait()) until the shared state is ready, + then retrieves the value stored in the shared state (if any). - \fI(none)\fP + If valid() is false before the call to this function, the behavior is undefined. .SH Return value - 1) Const reference to the value stored in the shared state. Accessing the value - through this reference is undefined after the shared state has been destroyed. - 2) Reference to the value in the shared state. - 3) Nothing. + 1) A const reference to the value stored in the shared state. The behavior of + accessing the value through this reference after the shared state has been destroyed + is undefined. + 2) The reference stored as value in the shared state. + 3) \fI(none)\fP .SH Exceptions @@ -35,8 +30,8 @@ .SH Notes - The implementations are encouraged to detect the case when valid() is false before - the call and throw a std::future_error with an error condition of + The C++ standard recommends the implementations to detect the case when valid() is + false before the call and throw a std::future_error with an error condition of std::future_errc::no_state. .SH Example @@ -47,8 +42,7 @@ .SH See also valid checks if the future has a shared state - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_future::operator=.3 b/man/std::shared_future::operator=.3 index 77b6c8cec..c134e081a 100644 --- a/man/std::shared_future::operator=.3 +++ b/man/std::shared_future::operator=.3 @@ -1,12 +1,26 @@ -.TH std::shared_future::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::operator= \- std::shared_future::operator= + .SH Synopsis - shared_future& operator=(const shared_future& rhs); \fB(1)\fP \fI(since C++11)\fP - shared_future& operator=(shared_future&& rhs) noexcept; \fB(2)\fP \fI(since C++11)\fP - shared_future& operator=(future&& other); \fB(3)\fP \fI(since C++11)\fP - shared_future& operator=(shared_future&& other); \fB(4)\fP \fI(since C++11)\fP + shared_future& operator=( const shared_future& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + shared_future& operator=( const shared_future& other ) \fB(1)\fP \fI(since C++17)\fP + noexcept; + shared_future& operator=( shared_future&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + + Assigns the contents of another shared_future. + + 1) Releases any shared state and assigns the contents of other to *this. After the + assignment, this->valid() == other.valid(). + 2) Releases any shared state and move-assigns the contents of other to *this. After + the assignment, other.valid() == false and this->valid() will yield the same value + as other.valid() before the assignment. + +.SH Parameters - This section is incomplete + other - a std::shared_future that will transfer state to *this -.SH Category: +.SH Return value - * Todo without reason + *this diff --git a/man/std::shared_future::shared_future.3 b/man/std::shared_future::shared_future.3 index 7a51d81e2..32cd061e4 100644 --- a/man/std::shared_future::shared_future.3 +++ b/man/std::shared_future::shared_future.3 @@ -1,33 +1,26 @@ -.TH std::shared_future::shared_future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::shared_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::shared_future \- std::shared_future::shared_future + .SH Synopsis - shared_future(); \fB(1)\fP \fI(since C++11)\fP - shared_future( const shared_future& other ); \fB(2)\fP \fI(since C++11)\fP - shared_future( future&& other ); \fB(3)\fP \fI(since C++11)\fP - shared_future( shared_future&& other ); \fB(4)\fP \fI(since C++11)\fP + shared_future() noexcept; \fB(1)\fP \fI(since C++11)\fP + shared_future( const shared_future& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + shared_future( const shared_future& other ) \fB(2)\fP \fI(since C++17)\fP + noexcept; + shared_future( std::future&& other ) noexcept; \fB(3)\fP \fI(since C++11)\fP + shared_future( shared_future&& other ) noexcept; \fB(4)\fP \fI(since C++11)\fP Constructs a new shared_future. - begin) 1) Default constructor. Constructs an empty shared future, that doesn't refer to a shared state, that is valid() == false. - 2) Constructs a shared future that refers to the same shared state, as other, if - there's any. - 3-4) Move constructor. Transfers the shared state held by other to *this. After the - construction, other->valid() == false, also valid() returns the same value as - other.valid() would have returned before the construction. + 2) Constructs a shared future that refers to the same shared state, if any, as + other. + 3,4) Transfers the shared state held by other to *this. After the construction, + other.valid() == false, and this->valid() returns the same value as other.valid() + would have returned before the construction. .SH Parameters other - another future object to initialize with - -.SH Exceptions - - 1) - noexcept specification: - noexcept - - 2) \fI(none)\fP - 3-4) - noexcept specification: - noexcept - diff --git a/man/std::shared_future::valid.3 b/man/std::shared_future::valid.3 index 5227f40ba..fbc0b4554 100644 --- a/man/std::shared_future::valid.3 +++ b/man/std::shared_future::valid.3 @@ -1,10 +1,21 @@ -.TH std::shared_future::valid 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::valid 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::valid \- std::shared_future::valid + .SH Synopsis - bool valid() const; \fI(since C++11)\fP + bool valid() const noexcept; \fI(since C++11)\fP + + Checks if the future refers to a shared state. + + This is the case only for futures that were not default-constructed or moved from. + Unlike std::future, std::shared_future's shared state is not invalidated when get() + is called. - Checks if the future refers to a shared state. This is the case only for futures - returned by std::promise::get_future(), std::packaged_task::get_future() or - std::async() until the first time get() is called. + The behavior is undefined if any member function other than the destructor, the + copy-assignment operator, the move-assignment operator, or valid is called on a + shared_future that does not refer to shared state (although implementations are + encouraged to throw std::future_error indicating no_state in this case). It is valid + to move or copy from a shared_future object for which valid() is false. .SH Parameters @@ -14,22 +25,35 @@ true if *this refers to a shared state, otherwise false. -.SH Exceptions +.SH Example - noexcept specification: - noexcept - -.SH Example +// Run this code - This section is incomplete - Reason: no example + #include + #include -.SH See also + int main() + { + std::promise p; + std::shared_future f = p.get_future(); - wait waits for the result to become available - \fI(public member function)\fP + std::cout << std::boolalpha; + + std::cout << f.valid() << '\\n'; + p.set_value(); + std::cout << f.valid() << '\\n'; + f.get(); + std::cout << f.valid() << '\\n'; + } + +.SH Output: -.SH Category: + true + true + true - * Todo no example +.SH See also + + wait waits for the result to become available + \fI(public member function)\fP diff --git a/man/std::shared_future::wait.3 b/man/std::shared_future::wait.3 index c9a8c1c38..66cad64d6 100644 --- a/man/std::shared_future::wait.3 +++ b/man/std::shared_future::wait.3 @@ -1,10 +1,13 @@ -.TH std::shared_future::wait 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::wait 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::wait \- std::shared_future::wait + .SH Synopsis void wait() const; \fI(since C++11)\fP Blocks until the result becomes available. valid() == true after the call. - The behavior is undefined if valid()== false before the call to this function. + The behavior is undefined if valid() == false before the call to this function. .SH Parameters @@ -16,57 +19,65 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes - The implementations are encouraged to detect the case when valid == false before the - call and throw a std::future_error with an error condition of + The implementations are encouraged to detect the case when valid() == false before + the call and throw a std::future_error with an error condition of std::future_errc::no_state. + Calling wait on the same std::shared_future from multiple threads is not safe; the + intended use is for each thread that waits on the same shared state to have a copy + of a std::shared_future. + .SH Example - + // Run this code - #include + #include #include + #include #include - + int fib(int n) { - if (n < 3) return 1; - else return fib(n-1) + fib(n-2); + if (n < 3) + return 1; + else + return fib(n - 1) + fib(n - 2); } - + int main() { - std::shared_future f1 = std::async(std::launch::async, [](){ - return fib(20); - }); - std::shared_future f2 = std::async(std::launch::async, [](){ - return fib(25); - }); - - std::cout << "waiting...\\n"; + std::shared_future f1 = std::async(std::launch::async, []() { return fib(40); }); + std::shared_future f2 = std::async(std::launch::async, []() { return fib(43); }); + + std::cout << "waiting... " << std::flush; + const auto start = std::chrono::system_clock::now(); + f1.wait(); f2.wait(); - + + const auto diff = std::chrono::system_clock::now() - start; + std::cout << std::chrono::duration(diff).count() << " seconds\\n"; + std::cout << "f1: " << f1.get() << '\\n'; std::cout << "f2: " << f2.get() << '\\n'; } -.SH Output: +.SH Possible output: - waiting... - f1: 6765 - f2: 75025 + waiting... 1.61803 seconds + f1: 102334155 + f2: 433494437 .SH See also waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available until specified time wait_until point has been reached - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::shared_future::wait_for.3 b/man/std::shared_future::wait_for.3 index b6cf0f358..9649023f5 100644 --- a/man/std::shared_future::wait_for.3 +++ b/man/std::shared_future::wait_for.3 @@ -1,17 +1,27 @@ -.TH std::shared_future::wait_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::wait_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::wait_for \- std::shared_future::wait_for + .SH Synopsis template< class Rep, class Period > std::future_status wait_for( const std::chrono::duration& \fI(since C++11)\fP timeout_duration ) const; Waits for the result to become available. Blocks until specified timeout_duration - has elapsed or the result becomes available, whichever comes first. Returns value + has elapsed or the result becomes available, whichever comes first. The return value identifies the state of the result. - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + If the future is the result of a call to std::async that used lazy evaluation, this + function returns immediately without waiting. + + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. - The behavior is undefined if valid()== false before the call to this function. + The standard recommends that a steady clock is used to measure the duration. If an + implementation uses a system clock instead, the wait time may also be sensitive to + clock adjustments. + + The behavior is undefined if valid() is false before the call to this function. .SH Parameters @@ -20,51 +30,62 @@ .SH Return value Constant Explanation - future_status::deferred The function to calculate the result has not been started - yet + The shared state contains a deferred function using lazy + future_status::deferred evaluation, so the result will be computed only when + explicitly requested future_status::ready The result is ready future_status::timeout The timeout has expired .SH Exceptions Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + time points, and durations provided by the standard library never throw). .SH Notes The implementations are encouraged to detect the case when valid == false before the - call and throw a future_error with an error condition of future_errc::no_state. + call and throw a std::future_error with an error condition of + std::future_errc::no_state. .SH Example - + // Run this code - #include + #include #include + #include #include - #include - + using namespace std::chrono_literals; + int main() { - std::shared_future future = std::async(std::launch::async, [](){ - std::this_thread::sleep_for(std::chrono::seconds(3)); + std::shared_future future = std::async(std::launch::async, []() + { + std::this_thread::sleep_for(3s); return 8; }); - + std::cout << "waiting...\\n"; std::future_status status; - do { - status = future.wait_for(std::chrono::seconds(1)); - if (status == std::future_status::deferred) { - std::cout << "deferred\\n"; - } else if (status == std::future_status::timeout) { - std::cout << "timeout\\n"; - } else if (status == std::future_status::ready) { - std::cout << "ready!\\n"; + + do + { + switch (status = future.wait_for(1s); status) + { + case std::future_status::deferred: + std::cout << "deferred\\n"; + break; + case std::future_status::timeout: + std::cout << "timeout\\n"; + break; + case std::future_status::ready: + std::cout << "ready!\\n"; + break; } - } while (status != std::future_status::ready); - + } + while (status != std::future_status::ready); + std::cout << "result is " << future.get() << '\\n'; } @@ -73,13 +94,14 @@ waiting... timeout timeout + timeout ready! result is 8 .SH See also wait waits for the result to become available - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available until specified time wait_until point has been reached - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::shared_future::wait_until.3 b/man/std::shared_future::wait_until.3 index 8dc5103ff..6d4852f2c 100644 --- a/man/std::shared_future::wait_until.3 +++ b/man/std::shared_future::wait_until.3 @@ -1,4 +1,7 @@ -.TH std::shared_future::wait_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::wait_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::wait_until \- std::shared_future::wait_until + .SH Synopsis template< class Clock, class Duration > std::future_status wait_until( const \fI(since C++11)\fP @@ -8,15 +11,13 @@ timeout_time has been reached or the result becomes available, whichever comes first. The return value indicates why wait_until returned. - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might differ from - timeout_time - Clock::now() at the time of the call, depending on the direction of - the adjustment. - - The function also may block for longer than until after timeout_time has been - reached due to scheduling or resource contention delays. + If the future is the result of a call to async that used lazy evaluation, this + function returns immediately without waiting. - The behavior is undefined if valid()== false before the call to this function. + The behavior is undefined if valid() is false before the call to this function, or + Clock does not meet the Clock requirements. + The programs is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP .SH Parameters @@ -25,20 +26,31 @@ .SH Return value Constant Explanation - future_status::deferred The function to calculate the result has not been started - yet + The shared state contains a deferred function using lazy + future_status::deferred evaluation, so the result will be computed only when + explicitly requested future_status::ready The result is ready future_status::timeout The timeout has expired .SH Exceptions Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + time points, and durations provided by the standard library never throw). .SH Notes - The implementations are encouraged to detect the case when valid == false before the - call and throw a future_error with an error condition of future_errc::no_state. + The implementations are encouraged to detect the case when valid() == false before + the call and throw a std::future_error with an error condition of + future_errc::no_state. + + The standard recommends that the clock tied to timeout_time be used to measure time; + that clock is not required to be a monotonic clock. There are no guarantees + regarding the behavior of this function if the clock is adjusted discontinuously, + but the existing implementations convert timeout_time from Clock to + std::chrono::system_clock and delegate to POSIX pthread_cond_timedwait so that the + wait honors adjustments to the system clock, but not to the user-provided Clock. In + any case, the function also may wait for longer than until after timeout_time has + been reached due to scheduling or resource contention delays. .SH Example @@ -48,11 +60,10 @@ .SH See also wait waits for the result to become available - \fI(public member function)\fP + \fI(public member function)\fP waits for the result, returns if it is not available for the specified wait_for timeout duration - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_future::~shared_future.3 b/man/std::shared_future::~shared_future.3 index 178042070..7a3f3d3a8 100644 --- a/man/std::shared_future::~shared_future.3 +++ b/man/std::shared_future::~shared_future.3 @@ -1,4 +1,7 @@ -.TH std::shared_future::~shared_future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_future::~shared_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_future::~shared_future \- std::shared_future::~shared_future + .SH Synopsis ~shared_future(); \fI(since C++11)\fP diff --git a/man/std::shared_lock.3 b/man/std::shared_lock.3 index f22314df1..b88f128c0 100644 --- a/man/std::shared_lock.3 +++ b/man/std::shared_lock.3 @@ -1,20 +1,30 @@ -.TH std::shared_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock \- std::shared_lock + .SH Synopsis - Defined in header - template< class Mutex > \fI(since C++14)\fP + Defined in header + template< class Mutex > \fI(since C++14)\fP class shared_lock; The class shared_lock is a general-purpose shared mutex ownership wrapper allowing deferred locking, timed locking and transfer of lock ownership. Locking a shared_lock locks the associated shared mutex in shared mode (to lock it in - exclusive mode, std::unique_lock can be used) + exclusive mode, std::unique_lock can be used). - The shared_lock class is movable, but not copyable -- it meets the requirements of + The shared_lock class is movable, but not copyable – it meets the requirements of MoveConstructible and MoveAssignable but not of CopyConstructible or CopyAssignable. + shared_lock meets the Lockable requirements. If Mutex meets the SharedTimedLockable + requirements, shared_lock also meets TimedLockable requirements. + + In order to wait in a shared mutex in shared ownership mode, + std::condition_variable_any can be used (std::condition_variable requires + std::unique_lock and so can only wait in unique ownership mode). + .SH Template parameters - Mutex - the type of the shared mutex to lock. The type must meet the SharedMutex + Mutex - the type of the shared mutex to lock. The type must meet the SharedLockable requirements .SH Member types @@ -25,36 +35,45 @@ .SH Member functions constructor constructs a shared_lock, optionally locking the supplied mutex - \fI(public member function)\fP + \fI(public member function)\fP destructor unlocks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP operator= unlocks the mutex, if owned, and acquires ownership of another - \fI(public member function)\fP + \fI(public member function)\fP .SH Shared locking lock locks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP try_lock_for tries to lock the associated mutex, for the specified duration - \fI(public member function)\fP + \fI(public member function)\fP try_lock_until tries to lock the associated mutex, until a specified time point - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers swap swaps the data members with another shared_lock - \fI(public member function)\fP + \fI(public member function)\fP release disassociates the mutex without unlocking - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers mutex returns a pointer to the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP owns_lock tests whether the lock owns its associated mutex - \fI(public member function)\fP + \fI(public member function)\fP operator bool tests whether the lock owns its associated mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::shared_lock) specialization of std::swap for shared_lock - \fI(function template)\fP + \fI(C++14)\fP \fI(function template)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2981 C++17 redundant deduction guide from removed + shared_lock was provided diff --git a/man/std::shared_lock::lock.3 b/man/std::shared_lock::lock.3 index 7819eb8f5..6fd45a2df 100644 --- a/man/std::shared_lock::lock.3 +++ b/man/std::shared_lock::lock.3 @@ -1,11 +1,11 @@ -.TH std::shared_lock::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::lock \- std::shared_lock::lock + .SH Synopsis void lock(); \fI(since C++14)\fP - Locks the associated mutex. Effectively calls mutex()->lock_shared(). - - std::system_error is thrown if there is no associated mutex or if the mutex is - already locked. + Locks the associated mutex in shared mode. Effectively calls mutex()->lock_shared(). .SH Parameters @@ -17,26 +17,84 @@ .SH Exceptions - * Any exceptions thrown by mutex()->lock_shared() - + * Any exceptions thrown by mutex()->lock_shared(). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - - * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::operation_not_permitted. + * If the associated mutex is already locked by this shared_lock (that is, + owns_lock returns true), std::system_error with an error code of + std::errc::resource_deadlock_would_occur. .SH Example This section is incomplete - Reason: no example + Reason: show a meaningful use of shared_lock::lock + + +// Run this code + + #include + #include + #include + #include + #include + + std::string file = "Original content."; // Simulates a file + std::mutex output_mutex; // mutex that protects output operations. + std::shared_mutex file_mutex; // reader/writer mutex + + void read_content(int id) + { + std::string content; + { + std::shared_lock lock(file_mutex, std::defer_lock); // Do not lock it first. + lock.lock(); // Lock it here. + content = file; + } + std::lock_guard lock(output_mutex); + std::cout << "Contents read by reader #" << id << ": " << content << '\\n'; + } + + void write_content() + { + { + std::lock_guard file_lock(file_mutex); + file = "New content"; + } + std::lock_guard output_lock(output_mutex); + std::cout << "New content saved.\\n"; + } + + int main() + { + std::cout << "Two readers reading from file.\\n" + << "A writer competes with them.\\n"; + std::thread reader1{read_content, 1}; + std::thread reader2{read_content, 2}; + std::thread writer{write_content}; + reader1.join(); + reader2.join(); + writer.join(); + std::cout << "The first few operations to file are done.\\n"; + reader1 = std::thread{read_content, 3}; + reader1.join(); + } + +.SH Possible output: + + Two readers reading from file. + A writer competes with them. + Contents read by reader #1: Original content. + Contents read by reader #2: Original content. + New content saved. + The first few operations to file are done. + Contents read by reader #3: New content .SH See also try_lock tries to lock the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - - * Todo no example + * Todo with reason diff --git a/man/std::shared_lock::mutex.3 b/man/std::shared_lock::mutex.3 index 90b606d33..8af1a206a 100644 --- a/man/std::shared_lock::mutex.3 +++ b/man/std::shared_lock::mutex.3 @@ -1,6 +1,9 @@ -.TH std::shared_lock::mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::mutex \- std::shared_lock::mutex + .SH Synopsis - mutex_type* mutex() const; \fI(since C++14)\fP + mutex_type* mutex() const noexcept; \fI(since C++14)\fP Returns a pointer to the associated mutex, or a null pointer if there is no associated mutex. @@ -13,17 +16,10 @@ Pointer to the associated mutex or a null pointer if there is no associated mutex. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete Reason: no example .SH Category: - * Todo no example diff --git a/man/std::shared_lock::operator=.3 b/man/std::shared_lock::operator=.3 index 3a661a927..bd45305ba 100644 --- a/man/std::shared_lock::operator=.3 +++ b/man/std::shared_lock::operator=.3 @@ -1,6 +1,9 @@ -.TH std::shared_lock::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::operator= \- std::shared_lock::operator= + .SH Synopsis - shared_lock& operator=( shared_lock&& other ); \fI(since C++14)\fP + shared_lock& operator=( shared_lock&& other ) noexcept; \fI(since C++14)\fP Move assignment operator. Replaces the contents with those of other using move semantics. @@ -18,9 +21,3 @@ .SH Return value *this - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::shared_lock::operatorbool.3 b/man/std::shared_lock::operatorbool.3 index 5615892f5..f2b903df6 100644 --- a/man/std::shared_lock::operatorbool.3 +++ b/man/std::shared_lock::operatorbool.3 @@ -1,6 +1,9 @@ -.TH std::shared_lock::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::operatorbool \- std::shared_lock::operatorbool + .SH Synopsis - explicit operator bool() const; \fI(since C++14)\fP + explicit operator bool() const noexcept; \fI(since C++14)\fP Checks whether *this owns a locked mutex or not. Effectively calls owns_lock(). @@ -13,13 +16,7 @@ true if *this has an associated mutex and has acquired shared ownership of it, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also owns_lock tests whether the lock owns its associated mutex - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::shared_lock::owns_lock.3 b/man/std::shared_lock::owns_lock.3 index 74be43da2..3e1f0c1fd 100644 --- a/man/std::shared_lock::owns_lock.3 +++ b/man/std::shared_lock::owns_lock.3 @@ -1,6 +1,9 @@ -.TH std::shared_lock::owns_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::owns_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::owns_lock \- std::shared_lock::owns_lock + .SH Synopsis - bool owns_lock() const; \fI(since C++14)\fP + bool owns_lock() const noexcept; \fI(since C++14)\fP Checks whether *this owns a locked mutex or not. @@ -13,13 +16,7 @@ true if *this has an associated mutex and has acquired shared ownership of it, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also operator bool tests whether the lock owns its associated mutex - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::shared_lock::release.3 b/man/std::shared_lock::release.3 index c817482a8..186c1ac6b 100644 --- a/man/std::shared_lock::release.3 +++ b/man/std::shared_lock::release.3 @@ -1,6 +1,9 @@ -.TH std::shared_lock::release 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::release \- std::shared_lock::release + .SH Synopsis - mutex_type* release(); \fI(since C++14)\fP + mutex_type* release() noexcept; \fI(since C++14)\fP Breaks the association of the associated mutex, if any, and *this. @@ -13,13 +16,7 @@ .SH Return value - Pointer to the associated mutex or NULL if there was no associated mutex. - -.SH Exceptions - - noexcept specification: - noexcept - + Pointer to the associated mutex or a null pointer if there was no associated mutex. .SH Example @@ -29,10 +26,10 @@ .SH See also unlock unlocks the associated mutex - \fI(public member function)\fP - release disassociates the associated mutex without unlocking it - \fI(public member function of std::unique_lock)\fP + \fI(public member function)\fP + disassociates the associated mutex without unlocking (i.e., releasing + release ownership of) it + \fI(public member function of std::unique_lock)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_lock::shared_lock.3 b/man/std::shared_lock::shared_lock.3 index e10b7e083..0aeb52560 100644 --- a/man/std::shared_lock::shared_lock.3 +++ b/man/std::shared_lock::shared_lock.3 @@ -1,9 +1,12 @@ -.TH std::shared_lock::shared_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::shared_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::shared_lock \- std::shared_lock::shared_lock + .SH Synopsis - shared_lock(); \fB(1)\fP \fI(since C++14)\fP - shared_lock( shared_lock&& other ); \fB(2)\fP \fI(since C++14)\fP + shared_lock() noexcept; \fB(1)\fP \fI(since C++14)\fP + shared_lock( shared_lock&& other ) noexcept; \fB(2)\fP \fI(since C++14)\fP explicit shared_lock( mutex_type& m ); \fB(3)\fP \fI(since C++14)\fP - shared_lock( mutex_type& m, std::defer_lock_t t ); \fB(4)\fP \fI(since C++14)\fP + shared_lock( mutex_type& m, std::defer_lock_t t ) noexcept; \fB(4)\fP \fI(since C++14)\fP shared_lock( mutex_type& m, std::try_to_lock_t t ); \fB(5)\fP \fI(since C++14)\fP shared_lock( mutex_type& m, std::adopt_lock_t t ); \fB(6)\fP \fI(since C++14)\fP template< class Rep, class Period > @@ -25,23 +28,23 @@ 2) Move constructor. Initializes the shared_lock with the contents of other. Leaves other with no associated mutex. 3-8) Constructs a shared_lock with m as the associated mutex. Additionally: - 3) Locks the associated mutex in shared mode by calling m.lock_shared(). The - behavior is undefined if this thread already owns the mutex in any mode. + 3) Locks the associated mutex in shared mode by calling m.lock_shared(). 4) Does not lock the associated mutex. - 5) Tries to lock the associated mutexin shared mode without blocking by calling - m.try_lock_shared(). The behavior is undefined if this thread already owns the mutex - in any mode. - 5) Assumes the calling thread already owns m in shared mode. + 5) Tries to lock the associated mutex in shared mode without blocking by calling + m.try_lock_shared(). + 6) Assumes the calling thread already holds a shared lock (i.e., a lock acquired by + lock_shared, try_lock_shared, try_lock_shared_for, or try_lock_shared_until) on m. + The behavior is undefined if not so. 7) Tries to lock the associated mutex in shared mode by calling - m.try_lock_shared_until(timeout_duration), which blocks until specified + m.try_lock_shared_for(timeout_duration), which blocks until specified timeout_duration has elapsed or the lock is acquired, whichever comes first. May - block for longer than timeout_duration. The behavior is undefined if this thread - already owns the mutex in any mode. + block for longer than timeout_duration. The behavior is undefined if Mutex does not + meet the SharedTimedLockable requirements. 8) Tries to lock the associated mutex in shared mode by calling - m.try_lock_shared_for(timeout_time), which blocks until specified timeout_time has + m.try_lock_shared_until(timeout_time), which blocks until specified timeout_time has been reached or the lock is acquired, whichever comes first. May block for longer - than until timeout_time has been reached. The behavior is undefined if this thread - already owns the mutex in any mode. + than until timeout_time has been reached. The behavior is undefined if Mutex does + not meet the SharedTimedLockable requirements. .SH Parameters @@ -53,18 +56,43 @@ timeout_duration - maximum duration to block for timeout_time - maximum time point to block until -.SH Exceptions +.SH Example + - 1,2,4) - noexcept specification: - noexcept - +// Run this code -.SH Example + #include + #include + #include + #include + #include + + std::shared_timed_mutex m; + int i = 10; + + void read_shared_var(int id) + { + // both the threads get access to the integer i + std::shared_lock slk(m); + const int ii = i; // reads global i + + std::osyncstream(std::cout) << '#' << id << " read i as " << ii << "...\\n"; + std::this_thread::sleep_for(std::chrono::milliseconds(10)); + std::osyncstream(std::cout) << '#' << id << " woke up..." << std::endl; + } + + int main() + { + std::thread r1{read_shared_var, 1}; + std::thread r2{read_shared_var, 2}; - This section is incomplete - Reason: no example + r1.join(); + r2.join(); + } -.SH Category: +.SH Possible output: - * Todo no example + #2 read i as 10... + #1 read i as 10... + #2 woke up... + #1 woke up... diff --git a/man/std::shared_lock::swap.3 b/man/std::shared_lock::swap.3 index bc4a0533c..601d2c81d 100644 --- a/man/std::shared_lock::swap.3 +++ b/man/std::shared_lock::swap.3 @@ -1,7 +1,10 @@ -.TH std::shared_lock::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::swap \- std::shared_lock::swap + .SH Synopsis - template< class Mutex > \fI(since C++14)\fP - void swap( shared_lock& other ); + template< class Mutex > \fI(since C++14)\fP + void swap( shared_lock& other ) noexcept; Exchanges the internal states of the lock objects. @@ -13,12 +16,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -27,8 +24,7 @@ .SH See also std::swap(std::shared_lock) specialization of std::swap for shared_lock - \fI(function template)\fP + \fI(C++14)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_lock::try_lock.3 b/man/std::shared_lock::try_lock.3 index 0f1be3a6d..b920ff9a0 100644 --- a/man/std::shared_lock::try_lock.3 +++ b/man/std::shared_lock::try_lock.3 @@ -1,4 +1,7 @@ -.TH std::shared_lock::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::try_lock \- std::shared_lock::try_lock + .SH Synopsis bool try_lock(); \fI(since C++14)\fP @@ -18,13 +21,11 @@ .SH Exceptions - * Any exceptions thrown by mutex()->try_lock_shared() - + * Any exceptions thrown by mutex()->try_lock_shared(). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - + std::errc::operation_not_permitted. * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::resource_deadlock_would_occur. .SH Example @@ -33,17 +34,17 @@ .SH See also - try_lock tries to lock the associated mutex - \fI(public member function)\fP lock locks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated mutex without + try_lock blocking + \fI(public member function of std::unique_lock)\fP try_lock_for tries to lock the associated mutex, for the specified duration - \fI(public member function)\fP + \fI(public member function)\fP try_lock_until tries to lock the associated mutex, until a specified time point - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_lock::try_lock_for.3 b/man/std::shared_lock::try_lock_for.3 index be95f0e12..a0b6e2df3 100644 --- a/man/std::shared_lock::try_lock_for.3 +++ b/man/std::shared_lock::try_lock_for.3 @@ -1,4 +1,7 @@ -.TH std::shared_lock::try_lock_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::try_lock_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::try_lock_for \- std::shared_lock::try_lock_for + .SH Synopsis template< class Rep, class Period > bool try_lock_for( const std::chrono::duration& \fI(since C++14)\fP @@ -9,12 +12,19 @@ successful lock acquisition returns true, otherwise returns false. Effectively calls mutex()->try_lock_shared_for(timeout_duration). - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. + + The standard recommends that a steady clock is used to measure the duration. If an + implementation uses a system clock instead, the wait time may also be sensitive to + clock adjustments. std::system_error is thrown if there is no associated mutex or if the mutex is already locked. + The behavior is undefined if Mutex does not meet the SharedTimedLockable + requirements. + .SH Parameters timeout_duration - maximum duration to block for @@ -25,13 +35,11 @@ .SH Exceptions - * Any exceptions thrown by mutex()->try_lock_shared_for(timeout_duration) - + * Any exceptions thrown by mutex()->try_lock_shared_for(timeout_duration). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - + std::errc::operation_not_permitted. * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::resource_deadlock_would_occur. .SH Example @@ -40,18 +48,18 @@ .SH See also - attempts to lock the associated TimedLockable mutex, returns if the - try_lock_for mutex has been unavailable for the specified time duration - \fI(public member function of std::unique_lock)\fP + attempts to lock (i.e., takes ownership of) the associated + try_lock_for TimedLockable mutex, returns if the mutex has been unavailable for + the specified time duration + \fI(public member function of std::unique_lock)\fP lock locks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP try_lock_until tries to lock the associated mutex, until a specified time point - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_lock::try_lock_until.3 b/man/std::shared_lock::try_lock_until.3 index be4357614..c5dfbf68e 100644 --- a/man/std::shared_lock::try_lock_until.3 +++ b/man/std::shared_lock::try_lock_until.3 @@ -1,4 +1,7 @@ -.TH std::shared_lock::try_lock_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::try_lock_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::try_lock_until \- std::shared_lock::try_lock_until + .SH Synopsis template< class Clock, class Duration > bool try_lock_until( const std::chrono::time_point& \fI(since C++14)\fP @@ -9,11 +12,16 @@ successful lock acquisition returns true, otherwise returns false. May block for longer than until timeout_time has been reached. - Effectively calls mutex()->try_lock_shared_until(timeout_time) + Effectively calls mutex()->try_lock_shared_until(timeout_time). std::system_error is thrown if there is no associated mutex or if the mutex is already locked. + Clock must meet the Clock requirements. The behavior is undefined if Mutex does not + meet the SharedTimedLockable requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP + .SH Parameters timeout_time - maximum time point to block until @@ -24,13 +32,11 @@ .SH Exceptions - * Any exceptions thrown by mutex()->try_lock_shared_for(timeout_time) - + * Any exceptions thrown by mutex()->try_lock_shared_for(timeout_time). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - + std::errc::operation_not_permitted. * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::resource_deadlock_would_occur. .SH Example @@ -40,18 +46,17 @@ .SH See also lock locks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP try_lock_for tries to lock the associated mutex, for the specified duration - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the associated mutex - \fI(public member function)\fP - tries to lock the associated TimedLockable mutex, returns if the - try_lock_until mutex has been unavailable until specified time point has been - reached - \fI(public member function of std::unique_lock)\fP + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated TimedLockable + try_lock_until mutex, returns if the mutex has been unavailable until specified time + point has been reached + \fI(public member function of std::unique_lock)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_lock::unlock.3 b/man/std::shared_lock::unlock.3 index 6903bb282..251dac150 100644 --- a/man/std::shared_lock::unlock.3 +++ b/man/std::shared_lock::unlock.3 @@ -1,9 +1,12 @@ -.TH std::shared_lock::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::unlock \- std::shared_lock::unlock + .SH Synopsis void unlock(); \fI(since C++14)\fP Unlocks the associated mutex from shared mode. Effectively calls - mutex()->unlock_shared() + mutex()->unlock_shared(). std::system_error is thrown if there is no associated mutex or if the mutex is not locked. @@ -18,10 +21,9 @@ .SH Exceptions - * Any exceptions thrown by mutex()->unlock_shared() - + * Any exceptions thrown by mutex()->unlock_shared(). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted + std::errc::operation_not_permitted. .SH Example @@ -31,10 +33,9 @@ .SH See also lock locks the associated mutex - \fI(public member function)\fP + \fI(public member function)\fP release disassociates the mutex without unlocking - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_lock::~shared_lock.3 b/man/std::shared_lock::~shared_lock.3 index 07867c29d..0ecdd82f8 100644 --- a/man/std::shared_lock::~shared_lock.3 +++ b/man/std::shared_lock::~shared_lock.3 @@ -1,4 +1,7 @@ -.TH std::shared_lock::~shared_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_lock::~shared_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_lock::~shared_lock \- std::shared_lock::~shared_lock + .SH Synopsis ~shared_lock(); \fI(since C++14)\fP diff --git a/man/std::shared_mutex.3 b/man/std::shared_mutex.3 index f31bce451..4c82c67dd 100644 --- a/man/std::shared_mutex.3 +++ b/man/std::shared_mutex.3 @@ -1,7 +1,10 @@ -.TH std::shared_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex \- std::shared_mutex + .SH Synopsis - Defined in header - class shared_mutex; \fI(since C++14)\fP + Defined in header + class shared_mutex; \fI(since C++17)\fP The shared_mutex class is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads. In contrast to @@ -9,85 +12,147 @@ of access: * shared - several threads can share ownership of the same mutex. - * exclusive - only one thread can own the mutex. - Shared mutexes are usually used in situations, when multiple readers can access the - same resource at the same time without causing data races, but only one writer can - do so. + If one thread has acquired the exclusive lock (through lock, try_lock), no other + threads can acquire the lock (including the shared). + + If one thread has acquired the shared lock (through lock_shared, try_lock_shared), + no other thread can acquire the exclusive lock, but can acquire the shared lock. + + Only when the exclusive lock has not been acquired by any thread, the shared lock + can be acquired by multiple threads. - In a manner similar to timed_mutex, shared_mutex provides the ability to attempt to - claim ownership of a shared_mutex with a timeout via the try_lock_for(), - try_lock_until(), try_lock_shared_for(), try_lock_shared_until() methods. + Within one thread, only one lock (shared or exclusive) can be acquired at the same + time. + + Shared mutexes are especially useful when shared data can be safely read by any + number of threads simultaneously, but a thread may only write the same data when no + other thread is reading or writing at the same time. The shared_mutex class satisfies all requirements of SharedMutex and StandardLayoutType. +.SH Member types + + Member type Definition + native_handle_type (optional*) implementation-defined + .SH Member functions - constructor constructs the mutex - \fI(public member function)\fP - destructor destroys the mutex - \fI(public member function)\fP - operator= not copy-assignable - [deleted] \fI(public member function)\fP + constructor constructs the mutex + \fI(public member function)\fP + destructor destroys the mutex + \fI(public member function)\fP + operator= not copy-assignable + [deleted] \fI(public member function)\fP Exclusive locking - lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP - try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP - tries to lock the mutex, returns if the mutex has been - try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP - tries to lock the mutex, returns if the mutex has been - try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP - unlock unlocks the mutex - \fI(public member function)\fP + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP .SH Shared locking - locks the mutex for shared ownership, blocks if the mutex is - lock_shared not available - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the - try_lock_shared mutex is not available - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the - try_lock_shared_for mutex has been - unavailable for the specified timeout duration - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the - try_lock_shared_until mutex has been - unavailable until specified time point has been reached - \fI(public member function)\fP - unlock_shared unlocks the mutex (shared ownership) - \fI(public member function)\fP - - This section is incomplete - Reason: build a motivating example - - A copy assignment operator for a class that holds resources that can handle multiple - readers, but only one writer - - + locks the mutex for shared ownership, blocks if the mutex is not + lock_shared available + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the mutex + try_lock_shared is not available + \fI(public member function)\fP + unlock_shared unlocks the mutex (shared ownership) + \fI(public member function)\fP +.SH Native handle + native_handle returns the underlying implementation-defined native handle object + \fI(public member function)\fP + +.SH Example + + The output below was generated on a single-core machine. When thread1 starts, it + enters the loop for the first time and calls increment() followed by get(). However, + before it can print the returned value to std::cout, the scheduler puts thread1 to + sleep and wakes up thread2, which obviously has time enough to run all three loop + iterations at once. Back to thread1, still in the first loop iteration, it finally + prints its local copy of the counter's value, which is 1, to std::cout and then runs + the remaining two loop iterations. On a multi-core machine, none of the threads is + put to sleep and the output is more likely to be in ascending order. + + // Run this code - class R + #include + #include + #include + #include + #include + + class ThreadSafeCounter { - mutable std::shared_mutex m; - /* data */ public: - R& operator=(const R& other) + ThreadSafeCounter() = default; + + // Multiple threads/readers can read the counter's value at the same time. + unsigned int get() const + { + std::shared_lock lock(mutex_); + return value_; + } + + // Only one thread/writer can increment/write the counter's value. + void increment() { - // requires exclusive ownership to write to *this - std::unique_lock lhs(mut, std::defer_lock); - // requires shared ownership to read from other - std::shared_lock rhs(other.mut, std::defer_lock); - lock(lhs, rhs); - /* assign data */ - return *this; + std::unique_lock lock(mutex_); + ++value_; } + + // Only one thread/writer can reset/write the counter's value. + void reset() + { + std::unique_lock lock(mutex_); + value_ = 0; + } + + private: + mutable std::shared_mutex mutex_; + unsigned int value_{}; + }; + + int main() + { + ThreadSafeCounter counter; + + auto increment_and_print = [&counter]() + { + for (int i{}; i != 3; ++i) + { + counter.increment(); + std::osyncstream(std::cout) + << std::this_thread::get_id() << ' ' << counter.get() << '\\n'; + } + }; + + std::thread thread1(increment_and_print); + std::thread thread2(increment_and_print); + + thread1.join(); + thread2.join(); } -.SH Category: +.SH Possible output: + + 123084176803584 2 + 123084176803584 3 + 123084176803584 4 + 123084185655040 1 + 123084185655040 5 + 123084185655040 6 + +.SH See also - * Todo with reason + shared_timed_mutex provides shared mutual exclusion facility and implements locking + \fI(C++14)\fP with a timeout + \fI(class)\fP + shared_lock implements movable shared mutex ownership wrapper + \fI(C++14)\fP \fI(class template)\fP + unique_lock implements movable mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::shared_mutex::lock.3 b/man/std::shared_mutex::lock.3 index dc27b164b..92ec0af77 100644 --- a/man/std::shared_mutex::lock.3 +++ b/man/std::shared_mutex::lock.3 @@ -1,14 +1,18 @@ -.TH std::shared_mutex::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - void lock(); \fI(since C++14)\fP +.TH std::shared_mutex::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::lock \- std::shared_mutex::lock - Locks the mutex. If another thread has already locked the mutex, a call to lock will - block execution until the lock is acquired. +.SH Synopsis + void lock(); \fI(since C++17)\fP - Templated information. See page source. + Acquires an exclusive ownership of the shared_mutex. If another thread is holding an + exclusive lock or a shared lock on the same shared_mutex the a call to lock will + block execution until all such locks are released. While shared_mutex is locked in + an exclusive mode, no other lock of any kind can also be held. - Prior unlock() operation on the same mutex synchronizes-with (as defined in - std::memory_order) this operation. + If lock is called by a thread that already owns the shared_mutex in any mode + (exclusive or shared), the behavior is undefined. A prior unlock() operation on the + same mutex synchronizes-with (as defined in std::memory_order) this operation. .SH Parameters @@ -26,61 +30,104 @@ .SH Notes - lock() is usually not called directly: std::unique_lock and std::lock_guard are used - to manage exclusive locking. - - shared_ptr does not support direct transition from shared to unique ownership mode: - the shared lock has to be relinquished with unlock_shared() before exclusive - ownership may be obtained with lock(). boost::upgrade_mutex may be used for this - purpose. + lock() is usually not called directly: std::unique_lock, std::scoped_lock, and + std::lock_guard are used to manage exclusive locking. .SH Example - This example shows how lock and unlock can be used to protect shared data. - // Run this code - #include #include - #include + #include #include - - int g_num = 0; // protected by g_num_mutex - std::mutex g_num_mutex; - - void slow_increment(int id) + #include + #include + #include + #include + + std::mutex stream_mutx; + void print(auto const& v) { - for (int i = 0; i < 3; ++i) { - g_num_mutex.lock(); - ++g_num; - std::cout << id << " => " << g_num << '\\n'; - g_num_mutex.unlock(); - - std::this_thread::sleep_for(std::chrono::seconds(1)); - } + std::unique_lock lock(stream_mutx); + std::cout << std::this_thread::get_id() << " saw: "; + for (auto e : v) + std::cout << e << ' '; + std::cout << '\\n'; } - + int main() { - std::thread t1(slow_increment, 0); - std::thread t2(slow_increment, 1); - t1.join(); - t2.join(); + using namespace std::chrono_literals; + constexpr int N_READERS = 5; + constexpr int LAST = -999; + + std::shared_mutex smtx; + int product = 0; + + auto writer = [&smtx, &product](int start, int end) + { + for (int i = start; i < end; ++i) + { + auto data = i; + { + std::unique_lock lock(smtx); // better than: + // smtx.lock(); + product = data; + } + std::this_thread::sleep_for(3ms); + } + + smtx.lock(); // lock manually + product = LAST; + smtx.unlock(); + }; + + auto reader = [&smtx, &product] + { + int data = 0; + std::vector seen; + do + { + { + // better to use: + std::shared_lock lock(smtx); // smtx.lock_shared(); + data = product; + } // smtx.unlock_shared(); + + seen.push_back(data); + std::this_thread::sleep_for(2ms); + } + while (data != LAST); + + print(seen); + }; + + std::vector threads; + threads.emplace_back(writer, 1, 13); + threads.emplace_back(writer, 42, 52); + + for (int i = 0; i < N_READERS; ++i) + threads.emplace_back(reader); + + for (auto&& t : threads) + t.join(); } .SH Possible output: - 0 => 1 - 1 => 2 - 0 => 3 - 1 => 4 - 0 => 5 - 1 => 6 + 127755840 saw: 43 3 3 4 46 5 6 7 7 8 9 51 10 11 11 12 -999 + 144541248 saw: 2 44 3 4 46 5 6 7 7 8 9 51 10 11 11 12 -999 + 110970432 saw: 42 2 3 45 4 5 47 6 7 8 8 9 10 11 11 12 -999 + 119363136 saw: 42 2 3 4 46 5 6 7 7 8 9 9 10 11 11 12 12 -999 + 136148544 saw: 2 44 3 4 46 5 6 48 7 8 9 51 10 11 11 12 12 -999 .SH See also - try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP - unlock unlocks the mutex - \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP + locks the mutex for shared ownership, blocks if the mutex is not + lock_shared available + \fI(public member function)\fP diff --git a/man/std::shared_mutex::lock_shared.3 b/man/std::shared_mutex::lock_shared.3 index 60bd6c9e5..b2629ce41 100644 --- a/man/std::shared_mutex::lock_shared.3 +++ b/man/std::shared_mutex::lock_shared.3 @@ -1,6 +1,9 @@ -.TH std::shared_mutex::lock_shared 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::lock_shared 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::lock_shared \- std::shared_mutex::lock_shared + .SH Synopsis - void lock_shared(); \fI(since C++14)\fP + void lock_shared(); \fI(since C++17)\fP Acquires shared ownership of the mutex. If another thread is holding the mutex in exclusive ownership, a call to lock_shared will block execution until shared @@ -14,7 +17,7 @@ shared owners is reduced. The maximum number of owners is guaranteed to be at least 10000. - Prior unlock() operation on the same mutex synchronizes-with (as defined in + A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation. .SH Parameters @@ -38,19 +41,98 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + std::mutex stream_mutx; + void print(auto v) + { + std::unique_lock lock(stream_mutx); + std::cout << std::this_thread::get_id() << " saw: "; + for (auto e : v) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + using namespace std::chrono_literals; + constexpr int N_READERS = 5; + constexpr int LAST = -999; + + std::shared_mutex smtx; + int product = 0; + + auto writer = [&smtx, &product](int start, int end) + { + for (int i = start; i < end; ++i) + { + auto data = i; + { + std::unique_lock lock(smtx); + product = data; + } + std::this_thread::sleep_for(3ms); + } + + smtx.lock(); // lock manually + product = LAST; + smtx.unlock(); + }; + + auto reader = [&smtx, &product]() + { + int data = 0; + std::vector seen; + do + { + { + smtx.lock_shared(); // better to use: std::shared_lock lock(smtx); + data = product; + smtx.unlock_shared(); + } + + seen.push_back(data); + std::this_thread::sleep_for(2ms); + } + while (data != LAST); + + print(seen); + }; + + std::vector threads; + threads.emplace_back(writer, 1, 13); + threads.emplace_back(writer, 42, 52); + + for (int i = 0; i < N_READERS; ++i) + threads.emplace_back(reader); + + for (auto&& t : threads) + t.join(); + } + +.SH Possible output: + + 127755840 saw: 43 3 3 4 46 5 6 7 7 8 9 51 10 11 11 12 -999 + 144541248 saw: 2 44 3 4 46 5 6 7 7 8 9 51 10 11 11 12 -999 + 110970432 saw: 42 2 3 45 4 5 47 6 7 8 8 9 10 11 11 12 -999 + 119363136 saw: 42 2 3 4 46 5 6 7 7 8 9 9 10 11 11 12 12 -999 + 136148544 saw: 2 44 3 4 46 5 6 48 7 8 9 51 10 11 11 12 12 -999 .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex for shared ownership, returns if the mutex try_lock_shared is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock_shared unlocks the mutex (shared ownership) - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::shared_mutex::native_handle.3 b/man/std::shared_mutex::native_handle.3 new file mode 100644 index 000000000..ca78a118d --- /dev/null +++ b/man/std::shared_mutex::native_handle.3 @@ -0,0 +1,29 @@ +.TH std::shared_mutex::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::native_handle \- std::shared_mutex::native_handle + +.SH Synopsis + native_handle_type native_handle(); \fI(since C++17)\fP + (not always present) + + Returns the underlying implementation-defined native handle object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Implementation-defined native handle object. + +.SH Exceptions + + Implementation-defined. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::shared_mutex::shared_mutex.3 b/man/std::shared_mutex::shared_mutex.3 index 6a0f59aa9..cd6e25ea2 100644 --- a/man/std::shared_mutex::shared_mutex.3 +++ b/man/std::shared_mutex::shared_mutex.3 @@ -1,7 +1,10 @@ -.TH std::shared_mutex::shared_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::shared_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::shared_mutex \- std::shared_mutex::shared_mutex + .SH Synopsis - shared_mutex(); \fB(1)\fP \fI(since C++14)\fP - shared_mutex( const shared_mutex& ) = delete; \fB(2)\fP \fI(since C++14)\fP + shared_mutex(); \fB(1)\fP \fI(since C++17)\fP + shared_mutex( const shared_mutex& ) = delete; \fB(2)\fP \fI(since C++17)\fP 1) Constructs the mutex. The mutex is in unlocked state after the call. 2) Copy constructor is deleted. @@ -13,3 +16,8 @@ .SH Exceptions std::system_error if the construction is unsuccessful. + +.SH See also + + C documentation for + mtx_init diff --git a/man/std::shared_mutex::try_lock.3 b/man/std::shared_mutex::try_lock.3 index baac7959c..2287dac44 100644 --- a/man/std::shared_mutex::try_lock.3 +++ b/man/std::shared_mutex::try_lock.3 @@ -1,6 +1,9 @@ -.TH std::shared_mutex::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::try_lock \- std::shared_mutex::try_lock + .SH Synopsis - bool try_lock(); \fI(since C++14)\fP + bool try_lock(); \fI(since C++17)\fP Tries to lock the mutex. Returns immediately. On successful lock acquisition returns true, otherwise returns false. @@ -8,7 +11,8 @@ This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread. - Templated information. See page source. + If try_lock is called by a thread that already owns the mutex in any mode (shared or + exclusive), the behavior is undefined. Prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. Note that prior lock() does @@ -24,16 +28,23 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example - - Template:cpp/thread/shared mutex/example try lock + + + This section is incomplete + Reason: no example .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_trylock + +.SH Category: + * Todo no example diff --git a/man/std::shared_mutex::try_lock_for.3 b/man/std::shared_mutex::try_lock_for.3 deleted file mode 100644 index 3679eb107..000000000 --- a/man/std::shared_mutex::try_lock_for.3 +++ /dev/null @@ -1,102 +0,0 @@ -.TH std::shared_mutex::try_lock_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class Rep, class Period > - bool try_lock_for( const std::chrono::duration& \fI(since C++14)\fP - timeout_duration ); - - Tries to lock the mutex. Blocks until specified timeout_duration has elapsed or the - lock is acquired, whichever comes first. On successful lock acquisition returns - true, otherwise returns false. - - If timeout_duration is less or equal timeout_duration.zero(), the function behaves - like try_lock(). - - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. - - As with try_lock(), this function is allowed to fail spuriously and return false - even if the mutex was not locked by any other thread at some point during - timeout_duration. - - Prior unlock() operation on the same mutex synchronizes-with (as defined in - std::memory_order) this operation if it returns true. - - Templated information. See page source. - -.SH Parameters - - timeout_duration - maximum duration to block for - -.SH Return value - - true if the lock was acquired successfully, otherwise false. - -.SH Exceptions - - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) - -.SH Example - - -// Run this code - - #include - #include - #include - #include - #include - - std::mutex cout_mutex; // control access to std::cout - std::timed_mutex mutex; - - void job(int id) - { - using Ms = std::chrono::milliseconds; - std::ostringstream stream; - - for (int i = 0; i < 3; ++i) { - if (mutex.try_lock_for(Ms(100))) { - stream << "success "; - std::this_thread::sleep_for(Ms(100)); - mutex.unlock(); - } else { - stream << "failed "; - } - std::this_thread::sleep_for(Ms(100)); - } - - std::lock_guard lock(cout_mutex); - std::cout << "[" << id << "] " << stream.str() << "\\n"; - } - - int main() - { - std::vector threads; - for (int i = 0; i < 4; ++i) { - threads.emplace_back(job, i); - } - - for (auto& i: threads) { - i.join(); - } - } - -.SH Possible output: - - [0] failed failed failed - [3] failed failed success - [2] failed success failed - [1] success failed success - -.SH See also - - lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP - try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP - tries to lock the mutex, returns if the mutex has been - try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP - unlock unlocks the mutex - \fI(public member function)\fP diff --git a/man/std::shared_mutex::try_lock_shared.3 b/man/std::shared_mutex::try_lock_shared.3 index e972e5bef..4b6ec7350 100644 --- a/man/std::shared_mutex::try_lock_shared.3 +++ b/man/std::shared_mutex::try_lock_shared.3 @@ -1,6 +1,9 @@ -.TH std::shared_mutex::try_lock_shared 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::try_lock_shared 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::try_lock_shared \- std::shared_mutex::try_lock_shared + .SH Synopsis - void try_lock_shared(); \fI(since C++14)\fP + bool try_lock_shared(); \fI(since C++17)\fP Tries to lock the mutex in shared mode. Returns immediately. On successful lock acquisition returns true, otherwise returns false. @@ -8,7 +11,7 @@ This function is allowed to fail spuriously and return false even if the mutex is not currenly exclusively locked by any other thread. - Prior unlock() operation on the same mutex synchronizes-with (as defined in + A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. The behavior is undefined if the calling thread already owns the mutex in any mode. @@ -23,7 +26,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example @@ -32,14 +35,12 @@ .SH See also - lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the mutex - try_lock_shared is not available - \fI(public member function)\fP - unlock_shared unlocks the mutex (shared ownership) - \fI(public member function)\fP + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + unlock_shared unlocks the mutex (shared ownership) + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_mutex::try_lock_shared_for.3 b/man/std::shared_mutex::try_lock_shared_for.3 deleted file mode 100644 index 23204785d..000000000 --- a/man/std::shared_mutex::try_lock_shared_for.3 +++ /dev/null @@ -1,60 +0,0 @@ -.TH std::shared_mutex::try_lock_shared_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class Rep, class Period > - bool try_lock_shared_for( const std::chrono::duration& \fI(since C++14)\fP - timeout_duration ); - - Tries to lock the mutex in shared mode. Blocks until specified timeout_duration has - elapsed or the shared lock is acquired, whichever comes first. On successful lock - acquisition returns true, otherwise returns false. - - If timeout_duration is less or equal timeout_duration.zero(), the function behaves - like try_lock_shared(). - - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. - - As with try_lock_shared(), this function is allowed to fail spuriously and return - false even if the mutex was not locked by any other thread at some point during - timeout_duration. - - Prior unlock() operation on the same mutex synchronizes-with (as defined in - std::memory_order) this operation if it returns true. - - If try_lock_shared_for is called by a thread that already owns the mutex in any mode - (shared or exclusive), the behavior is undefined. - -.SH Parameters - - timeout_duration - maximum duration to block for - -.SH Return value - - true if the lock was acquired successfully, otherwise false. - -.SH Exceptions - - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - tries to lock the mutex for shared ownership, returns if the - try_lock_shared mutex is not available - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the - try_lock_shared_until mutex has been - unavailable until specified time point has been reached - \fI(public member function)\fP - tries to lock the mutex, returns if the mutex has been - try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::shared_mutex::try_lock_shared_until.3 b/man/std::shared_mutex::try_lock_shared_until.3 deleted file mode 100644 index 26e314c8a..000000000 --- a/man/std::shared_mutex::try_lock_shared_until.3 +++ /dev/null @@ -1,63 +0,0 @@ -.TH std::shared_mutex::try_lock_shared_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class Clock, class Duration > - bool try_lock_shared_until( const \fI(since C++14)\fP - std::chrono::time_point& timeout_time ); - - Tries to lock the mutex in shared mode. Blocks until specified timeout_time has been - reached or the lock is acquired, whichever comes first. On successful lock - acquisition returns true, otherwise returns false. - - If timeout_time has already passed, this function behaves like try_lock_shared(). - - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might, but might - not, be less or more than timeout_time - Clock::now() at the time of the call, - depending on the direction of the adjustment. The function also may block for longer - than until after timeout_time has been reached due to scheduling or resource - contention delays. - - As with try_lock_shared(), this function is allowed to fail spuriously and return - false even if the mutex was not locked by any other thread at some point before - timeout_time. - - Prior unlock() operation on the same mutex synchronizes-with (as defined in - std::memory_order) this operation if it returns true. - - If try_lock_shared_until is called by a thread that already owns the mutex in any - mode (shared or exclusive), the behavior is undefined. - -.SH Parameters - - timeout_time - maximum time point to block until - -.SH Return value - - true if the shared lock ownership was acquired successfully, otherwise false. - -.SH Exceptions - - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - tries to lock the mutex, returns if the mutex has been - try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the - try_lock_shared mutex is not available - \fI(public member function)\fP - tries to lock the mutex for shared ownership, returns if the - try_lock_shared_for mutex has been - unavailable for the specified timeout duration - \fI(public member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::shared_mutex::try_lock_until.3 b/man/std::shared_mutex::try_lock_until.3 deleted file mode 100644 index c87f29487..000000000 --- a/man/std::shared_mutex::try_lock_until.3 +++ /dev/null @@ -1,80 +0,0 @@ -.TH std::shared_mutex::try_lock_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class Clock, class Duration > - bool try_lock_until( const std::chrono::time_point& \fI(since C++14)\fP - timeout_time ); - - Tries to lock the mutex. Blocks until specified timeout_time has been reached or the - lock is acquired, whichever comes first. On successful lock acquisition returns - true, otherwise returns false. - - If timeout_time has already passed, this function behaves like try_lock(). - - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might, but might - not, be less or more than timeout_time - Clock::now() at the time of the call, - depending on the direction of the adjustment. The function also may block for longer - than until after timeout_time has been reached due to scheduling or resource - contention delays. - - As with try_lock(), this function is allowed to fail spuriously and return false - even if the mutex was not locked by any other thread at some point before - timeout_time. - - Prior unlock() operation on the same mutex synchronizes-with (as defined in - std::memory_order) this operation if it returns true. - - Templated information. See page source. - -.SH Parameters - - timeout_time - maximum time point to block until - -.SH Return value - - true if the lock was acquired successfully, otherwise false. - -.SH Exceptions - - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) - -.SH Example - - This example shows a 10 seconds block - - -// Run this code - - #include - #include - #include - #include - - std::shared_mutex test_mutex; - - void f() - { - auto now=std::chrono::steady_clock::now(); - test_mutex.try_lock_until(now + std::chrono::seconds(10)); - std::cout << "hello world\\n"; - } - - int main() - { - std::lock_guard l(test_mutex); - std::thread t(f); - t.join(); - } - -.SH See also - - lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP - try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP - tries to lock the mutex, returns if the mutex has been - try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP - unlock unlocks the mutex - \fI(public member function)\fP diff --git a/man/std::shared_mutex::unlock.3 b/man/std::shared_mutex::unlock.3 index 68e461f1c..c7e7c87c4 100644 --- a/man/std::shared_mutex::unlock.3 +++ b/man/std::shared_mutex::unlock.3 @@ -1,6 +1,9 @@ -.TH std::shared_mutex::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::unlock \- std::shared_mutex::unlock + .SH Synopsis - void unlock(); \fI(since C++14)\fP + void unlock(); \fI(since C++17)\fP Unlocks the mutex. @@ -20,7 +23,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes @@ -29,46 +32,17 @@ .SH Example - This example shows lock, try_lock and unlock in action: - - -// Run this code - - #include - #include - - int main() - { - std::mutex test; - if (test.try_lock()) { - std::cout << "first try_lock successful\\n"; - } else { - std::cout << "first try_lock NOT successful\\n"; - return 0; - } - - test.unlock(); - test.lock(); - - if (test.try_lock()) { - std::cout << "second try_lock successful\\n"; - } else { - std::cout << "second try_lock NOT successful\\n"; - } - - test.lock(); // trying to lock an already-locked std::mutex will - // block program execution, so we'll hang here - } - -.SH Possible output: - - first try_lock successful - second try_lock NOT successful - (program hangs) + This section is incomplete + Reason: no example .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_unlock + +.SH Category: + * Todo no example diff --git a/man/std::shared_mutex::unlock_shared.3 b/man/std::shared_mutex::unlock_shared.3 index 03a487f28..f4a64115d 100644 --- a/man/std::shared_mutex::unlock_shared.3 +++ b/man/std::shared_mutex::unlock_shared.3 @@ -1,10 +1,14 @@ -.TH std::shared_mutex::unlock_shared 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::unlock_shared 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::unlock_shared \- std::shared_mutex::unlock_shared + .SH Synopsis - void unlock_shared(); \fI(since C++14)\fP + void unlock_shared(); \fI(since C++17)\fP + + Releases the mutex from shared ownership by the calling thread. - Releases the mutex from shared ownership by the calling thread. . The mutex must be - locked by the current thread of execution in shared mode, otherwise, the behavior is - undefined. + The mutex must be locked by the current thread of execution in shared mode, + otherwise, the behavior is undefined. This operation synchronizes-with (as defined in std::memory_order) any subsequent lock() operation that obtains ownership of the same mutex. @@ -19,12 +23,12 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes unlock_shared() is usually not called directly: std::shared_lock is used to manage - exclusive locking. + shared locking. .SH Example @@ -35,10 +39,9 @@ locks the mutex for shared ownership, blocks if the mutex is not lock_shared available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::shared_mutex::~shared_mutex.3 b/man/std::shared_mutex::~shared_mutex.3 index 21c6d7622..942c2ab47 100644 --- a/man/std::shared_mutex::~shared_mutex.3 +++ b/man/std::shared_mutex::~shared_mutex.3 @@ -1,4 +1,7 @@ -.TH std::shared_mutex::~shared_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_mutex::~shared_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_mutex::~shared_mutex \- std::shared_mutex::~shared_mutex + .SH Synopsis ~shared_mutex(); @@ -6,3 +9,8 @@ The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex. + +.SH See also + + C documentation for + mtx_destroy diff --git a/man/std::shared_ptr.3 b/man/std::shared_ptr.3 index 98a382072..7fd1719d9 100644 --- a/man/std::shared_ptr.3 +++ b/man/std::shared_ptr.3 @@ -1,4 +1,7 @@ -.TH std::shared_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr \- std::shared_ptr + .SH Synopsis Defined in header template< class T > class shared_ptr; \fI(since C++11)\fP @@ -7,8 +10,7 @@ through a pointer. Several shared_ptr objects may own the same object. The object is destroyed and its memory deallocated when either of the following happens: - * the last remaining shared_ptr owning the object is destroyed. - + * the last remaining shared_ptr owning the object is destroyed; * the last remaining shared_ptr owning the object is assigned another pointer via operator= or reset(). @@ -17,91 +19,123 @@ A shared_ptr can share ownership of an object while storing a pointer to another object. This feature can be used to point to member objects while owning the object - they belong to. + they belong to. The stored pointer is the one accessed by get(), the dereference and + the comparison operators. The managed pointer is the one passed to the deleter when + use count reaches zero. - A shared_ptr may also own no objects, in which case it is called empty. + A shared_ptr may also own no objects, in which case it is called empty (an empty + shared_ptr may have a non-null stored pointer if the aliasing constructor was used + to create it). - shared_ptr meets the requirements of CopyConstructible and CopyAssignable. + All specializations of shared_ptr meet the requirements of CopyConstructible, + CopyAssignable, and LessThanComparable and are contextually convertible to bool. All member functions (including copy constructor and copy assignment) can be called - by multiple threads on different instances of shared_ptr without additional - synchronization even if these instances are copies and share ownership of the same - object. + by multiple threads on different shared_ptr objects without additional + synchronization even if these objects are copies and share ownership of the same + object. If multiple threads of execution access the same shared_ptr object without + synchronization and any of those accesses uses a non-const member function of + shared_ptr then a data race will occur; the std::atomic can be used to + prevent the data race. .SH Member types - Member type Definition - element_type T + Member type Definition + element_type T \fI(until C++17)\fP + std::remove_extent_t \fI(since C++17)\fP + weak_type \fI(since C++17)\fP std::weak_ptr .SH Member functions constructor constructs new shared_ptr - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the owned object if no more shared_ptrs link to it - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the shared_ptr - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers reset replaces the managed object - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the managed objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers - get returns a pointer to the managed object - \fI(public member function)\fP - operator* dereferences pointer to the managed object - operator-> \fI(public member function)\fP + get returns the stored pointer + \fI(public member function)\fP + operator* dereferences the stored pointer + operator-> \fI(public member function)\fP + operator[] provides indexed access to the stored array + \fI(C++17)\fP \fI(public member function)\fP returns the number of shared_ptr objects referring to the same managed use_count object - \fI(public member function)\fP - checks whether the managed object is managed only by the current - unique shared_ptr instance - \fI(public member function)\fP - operator bool checks if there is associated managed object - \fI(public member function)\fP + \fI(public member function)\fP + unique checks whether the managed object is managed only by the current + \fI(until C++20)\fP shared_ptr object + \fI(public member function)\fP + operator bool checks if the stored pointer is not null + \fI(public member function)\fP owner_before provides owner-based ordering of shared pointers - \fI(public member function)\fP + \fI(public member function)\fP + owner_hash provides owner-based hashing of shared pointers + (C++26) \fI(public member function)\fP + owner_equal provides owner-based equal comparison of shared pointers + (C++26) \fI(public member function)\fP .SH Non-member functions - make_shared creates a shared pointer that manages a new object - \fI(function template)\fP - creates a shared pointer that manages a new object - allocate_shared allocated using an allocator - \fI(function template)\fP - static_pointer_cast applies static_cast, dynamic_cast or const_cast to the - dynamic_pointer_cast type of the managed object - const_pointer_cast \fI(function template)\fP - get_deleter returns the deleter of specified type, if owned - \fI(function template)\fP + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + allocate_shared creates a shared pointer that manages a new object + allocate_shared_for_overwrite allocated using an allocator + (C++20) \fI(function template)\fP + static_pointer_cast + dynamic_pointer_cast applies static_cast, dynamic_cast, const_cast, or + const_pointer_cast reinterpret_cast to the stored pointer + reinterpret_pointer_cast \fI(function template)\fP + \fI(C++17)\fP + get_deleter returns the deleter of specified type, if owned + \fI(function template)\fP operator== operator!= - operator< compares with another shared_ptr or with nullptr - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= - outputs the value of the managed pointer to an output - operator<< stream - \fI(function template)\fP - std::swap(std::shared_ptr) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + operator>= compares with another shared_ptr or with nullptr + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + outputs the value of the stored pointer to an output + operator<<(std::shared_ptr) stream + \fI(function template)\fP + std::swap(std::shared_ptr) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP std::atomic_is_lock_free(std::shared_ptr) std::atomic_load(std::shared_ptr) std::atomic_load_explicit(std::shared_ptr) - std::atomic_store(std::shared_ptr) specializes atomic - std::atomic_store_explicit(std::shared_ptr) operations - std::atomic_exchange(std::shared_ptr) \fI(function template)\fP - std::atomic_exchange_explicit(std::shared_ptr) - std::atomic_compare_exchange_weak(std::shared_ptr) + std::atomic_store(std::shared_ptr) + std::atomic_store_explicit(std::shared_ptr) specializes atomic + std::atomic_exchange(std::shared_ptr) operations for + std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr + std::atomic_compare_exchange_weak(std::shared_ptr) \fI(function template)\fP std::atomic_compare_exchange_strong(std::shared_ptr) std::atomic_compare_exchange_weak_explicit(std::shared_ptr) std::atomic_compare_exchange_strong_explicit(std::shared_ptr) + (deprecated in C++20) + (removed in C++26) .SH Helper classes - std::hash hash support for std::shared_ptr - \fI(C++11)\fP \fI(class template specialization)\fP + std::atomic atomic shared pointer + (C++20) \fI(class template specialization)\fP + std::hash hash support for std::shared_ptr + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP .SH Notes @@ -110,20 +144,39 @@ shared_ptr using the raw underlying pointer owned by another shared_ptr leads to undefined behavior. + std::shared_ptr may be used with an incomplete type T. However, the constructor from + a raw pointer (template shared_ptr(Y*)) and the template void + reset(Y*) member function may only be called with a pointer to a complete type (note + that std::unique_ptr may be constructed from a raw pointer to an incomplete type). + + The T in std::shared_ptr may be a function type: in this case it manages a + pointer to function, rather than an object pointer. This is sometimes used to keep a + dynamic library or a plugin loaded as long as any of its functions are referenced: + + void del(void(*)()) {} + + void fun() {} + + int main() + { + std::shared_ptr ee(fun, del); + (*ee)(); + } + .SH Implementation notes - In a typical implementation, std::shared_ptr holds only two pointers: + In a typical implementation, shared_ptr holds only two pointers: - * a pointer to the managed object - * a pointer to control block + * the stored pointer (one returned by get()); + * a pointer to control block. The control block is a dynamically-allocated object that holds: - * either a pointer to the managed object or the managed object itself - * the deleter (type-erased) - * the allocator (type-erased) - * the number of shared_ptrs that own the managed object - * the number of weak_ptrs that refer to the managed object + * either a pointer to the managed object or the managed object itself; + * the deleter (type-erased); + * the allocator (type-erased); + * the number of shared_ptrs that own the managed object; + * the number of weak_ptrs that refer to the managed object. When shared_ptr is created by calling std::make_shared or std::allocate_shared, the memory for both the control block and the managed object is created with a single @@ -141,6 +194,234 @@ managed object. The control block does not deallocate itself until the std::weak_ptr counter reaches zero as well. + In existing implementations, the number of weak pointers is incremented ([1], [2]) + if there is a shared pointer to the same control block. + To satisfy thread safety requirements, the reference counters are typically - incremented and decremented using std::atomic::fetch_add with - std::memory_order_relaxed. + incremented using an equivalent of std::atomic::fetch_add with + std::memory_order_relaxed (decrementing requires stronger ordering to safely destroy + the control block). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + struct Base + { + Base() { std::cout << "Base::Base()\\n"; } + + // Note: non-virtual destructor is OK here + ~Base() { std::cout << "Base::~Base()\\n"; } + }; + + struct Derived : public Base + { + Derived() { std::cout << "Derived::Derived()\\n"; } + + ~Derived() { std::cout << "Derived::~Derived()\\n"; } + }; + + void print(auto rem, std::shared_ptr const& sp) + { + std::cout << rem << "\\n\\tget() = " << sp.get() + << ", use_count() = " << sp.use_count() << '\\n'; + } + + void thr(std::shared_ptr p) + { + std::this_thread::sleep_for(987ms); + std::shared_ptr lp = p; // thread-safe, even though the + // shared use_count is incremented + { + static std::mutex io_mutex; + std::lock_guard lk(io_mutex); + print("Local pointer in a thread:", lp); + } + } + + int main() + { + std::shared_ptr p = std::make_shared(); + + print("Created a shared Derived (as a pointer to Base)", p); + + std::thread t1{thr, p}, t2{thr, p}, t3{thr, p}; + p.reset(); // release ownership from main + + print("Shared ownership between 3 threads and released ownership from main:", p); + + t1.join(); + t2.join(); + t3.join(); + + std::cout << "All threads completed, the last one deleted Derived.\\n"; + } + +.SH Possible output: + + Base::Base() + Derived::Derived() + Created a shared Derived (as a pointer to Base) + get() = 0x118ac30, use_count() = 1 + Shared ownership between 3 threads and released ownership from main: + get() = 0, use_count() = 0 + Local pointer in a thread: + get() = 0x118ac30, use_count() = 5 + Local pointer in a thread: + get() = 0x118ac30, use_count() = 4 + Local pointer in a thread: + get() = 0x118ac30, use_count() = 2 + Derived::~Derived() + Base::~Base() + All threads completed, the last one deleted Derived. + +.SH Example + + +// Run this code + + #include + #include + + struct MyObj + { + MyObj() { std::cout << "MyObj constructed\\n"; } + + ~MyObj() { std::cout << "MyObj destructed\\n"; } + }; + + struct Container : std::enable_shared_from_this // note: public inheritance + { + std::shared_ptr memberObj; + + void CreateMember() { memberObj = std::make_shared(); } + + std::shared_ptr GetAsMyObj() + { + // Use an alias shared ptr for member + return std::shared_ptr(shared_from_this(), memberObj.get()); + } + }; + + #define COUT(str) std::cout << '\\n' << str << '\\n' + + #define DEMO(...) std::cout << #__VA_ARGS__ << " = " << __VA_ARGS__ << '\\n' + + int main() + { + COUT("Creating shared container"); + std::shared_ptr cont = std::make_shared(); + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + + COUT("Creating member"); + cont->CreateMember(); + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + + COUT("Creating another shared container"); + std::shared_ptr cont2 = cont; + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + DEMO(cont2.use_count()); + DEMO(cont2->memberObj.use_count()); + + COUT("GetAsMyObj"); + std::shared_ptr myobj1 = cont->GetAsMyObj(); + DEMO(myobj1.use_count()); + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + DEMO(cont2.use_count()); + DEMO(cont2->memberObj.use_count()); + + COUT("Copying alias obj"); + std::shared_ptr myobj2 = myobj1; + DEMO(myobj1.use_count()); + DEMO(myobj2.use_count()); + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + DEMO(cont2.use_count()); + DEMO(cont2->memberObj.use_count()); + + COUT("Resetting cont2"); + cont2.reset(); + DEMO(myobj1.use_count()); + DEMO(myobj2.use_count()); + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + + COUT("Resetting myobj2"); + myobj2.reset(); + DEMO(myobj1.use_count()); + DEMO(cont.use_count()); + DEMO(cont->memberObj.use_count()); + + COUT("Resetting cont"); + cont.reset(); + DEMO(myobj1.use_count()); + DEMO(cont.use_count()); + } + +.SH Output: + + Creating shared container + cont.use_count() = 1 + cont->memberObj.use_count() = 0 + + Creating member + MyObj constructed + cont.use_count() = 1 + cont->memberObj.use_count() = 1 + + Creating another shared container + cont.use_count() = 2 + cont->memberObj.use_count() = 1 + cont2.use_count() = 2 + cont2->memberObj.use_count() = 1 + + GetAsMyObj + myobj1.use_count() = 3 + cont.use_count() = 3 + cont->memberObj.use_count() = 1 + cont2.use_count() = 3 + cont2->memberObj.use_count() = 1 + + Copying alias obj + myobj1.use_count() = 4 + myobj2.use_count() = 4 + cont.use_count() = 4 + cont->memberObj.use_count() = 1 + cont2.use_count() = 4 + cont2->memberObj.use_count() = 1 + + Resetting cont2 + myobj1.use_count() = 3 + myobj2.use_count() = 3 + cont.use_count() = 3 + cont->memberObj.use_count() = 1 + + Resetting myobj2 + myobj1.use_count() = 2 + cont.use_count() = 2 + cont->memberObj.use_count() = 1 + + Resetting cont + myobj1.use_count() = 1 + cont.use_count() = 0 + MyObj destructed + +.SH See also + + unique_ptr smart pointer with unique object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + weak_ptr weak reference to an object managed by std::shared_ptr + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::shared_ptr::get.3 b/man/std::shared_ptr::get.3 index 1af748a9f..09fb3e09c 100644 --- a/man/std::shared_ptr::get.3 +++ b/man/std::shared_ptr::get.3 @@ -1,8 +1,12 @@ -.TH std::shared_ptr::get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::get \- std::shared_ptr::get + .SH Synopsis - T* get() const; \fI(since C++11)\fP + T* get() const noexcept; \fI(until C++17)\fP + element_type* get() const noexcept; \fI(since C++17)\fP - Returns a pointer to the managed object. + Returns the stored pointer. .SH Parameters @@ -10,42 +14,71 @@ .SH Return value - A pointer to the managed object. + The stored pointer. + +.SH Notes + + A shared_ptr may share ownership of an object while storing a pointer to another + object. get() returns the stored pointer, not the managed pointer. .SH Example - + // Run this code #include #include - #include - - typedef std::shared_ptr IntPtr; - - void output(const std::string& msg, int* pInt) - { - std::cout << msg << *pInt << "\\n"; - } - + #include + int main() { + auto output = [](std::string_view msg, int const* pInt) + { + std::cout << msg << *pInt << " in " << pInt << '\\n'; + }; + int* pInt = new int(42); - IntPtr pShared(new int(42)); - - output("Naked pointer ", pInt); - // output("Shared pointer ", pShared); // compiler error - output("Shared pointer with get() ", pShared.get()); - + std::shared_ptr pShared = std::make_shared(42); + + output("Naked pointer: ", pInt); + // output("Shared pointer: ", pShared); // compiler error + output("Shared pointer: ", &*pShared); // OK, calls operator*, then takes addr + output("Shared pointer with get(): ", pShared.get()); + delete pInt; + + std::cout << "\\nThe shared_ptr's aliasing constructor demo.\\n"; + struct Base1 { int i1{}; }; + struct Base2 { int i2{}; }; + struct Derived : Base1, Base2 { int i3{}; }; + + std::shared_ptr p(new Derived()); + std::shared_ptr q(p, static_cast(p.get())); + std::cout << "q shares ownership with p, but points to Base2 subobject:\\n" + << "p.get(): " << p.get() << '\\n' + << "q.get(): " << q.get() << '\\n' + << "&(p->i1): " << &(p->i1) << '\\n' + << "&(p->i2): " << &(p->i2) << '\\n' + << "&(p->i3): " << &(p->i3) << '\\n' + << "&(q->i2): " << &(q->i2) << '\\n'; } -.SH Output: +.SH Possible output: + + Naked pointer: 42 in 0xacac20 + Shared pointer: 42 in 0xacac50 + Shared pointer with get(): 42 in 0xacac50 - Naked pointer 42 - Shared pointer with get() 42 + The shared_ptr's aliasing constructor demo. + q shares ownership with p, but points to Base2 subobject: + p.get(): 0xacac20 + q.get(): 0xacac24 + &(p->i1): 0xacac20 + &(p->i2): 0xacac24 + &(p->i3): 0xacac28 + &(q->i2): 0xacac24 .SH See also - operator* dereferences pointer to the managed object - operator-> \fI(public member function)\fP + operator* dereferences the stored pointer + operator-> \fI(public member function)\fP diff --git a/man/std::shared_ptr::operator*,std::shared_ptr::operator->.3 b/man/std::shared_ptr::operator*,std::shared_ptr::operator->.3 index 014fbe160..7a69b7e47 100644 --- a/man/std::shared_ptr::operator*,std::shared_ptr::operator->.3 +++ b/man/std::shared_ptr::operator*,std::shared_ptr::operator->.3 @@ -1,9 +1,13 @@ -.TH std::shared_ptr::operator*,std::shared_ptr::operator-> 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::operator*,std::shared_ptr::operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::operator*,std::shared_ptr::operator-> \- std::shared_ptr::operator*,std::shared_ptr::operator-> + .SH Synopsis - T& operator*() const; \fB(1)\fP - T* operator->() const; \fB(2)\fP + T& operator*() const noexcept; \fB(1)\fP \fI(since C++11)\fP + T* operator->() const noexcept; \fB(2)\fP \fI(since C++11)\fP - Dereferences pointer to the managed object. + Dereferences the stored pointer. The behavior is undefined if the stored pointer is + null. .SH Parameters @@ -11,20 +15,53 @@ .SH Return value - 1) reference to the managed object. + 1) The result of dereferencing the stored pointer, i.e., *get(). + 2) The stored pointer, i.e., get(). + + Remarks + + When T is + an array type or (possibly cv-qualified) + \fI(since C++17)\fP void, it is unspecified whether function \fB(1)\fP is declared. If it is + declared, it is unspecified what its return type is, except that the declaration + (although not necessarily the definition) of the function shall be well formed. This + makes it possible to instantiate std::shared_ptr - 2) pointer to the managed object. + When T is an array type, it is unspecified whether function \fB(2)\fP is + declared. If it is declared, it is unspecified what its return type \fI(since C++17)\fP + is, except that the declaration of the function shall be well-formed. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include - get returns a pointer to the managed object - \fI(public member function)\fP + struct Foo + { + Foo(int in) : a(in) {} + void print() const + { + std::cout << "a = " << a << '\\n'; + } + int a; + }; -.SH Category: + int main() + { + auto ptr = std::make_shared(10); + ptr->print(); + (*ptr).print(); + } + +.SH Output: + + a = 10 + a = 10 + +.SH See also - * Todo no example + get returns the stored pointer + \fI(public member function)\fP diff --git a/man/std::shared_ptr::operator<<.3 b/man/std::shared_ptr::operator<<.3 index aa60a2b13..fdf55cf83 100644 --- a/man/std::shared_ptr::operator<<.3 +++ b/man/std::shared_ptr::operator<<.3 @@ -1,10 +1,13 @@ -.TH std::shared_ptr::operator<< 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::operator<< 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::operator<< \- std::shared_ptr::operator<< + .SH Synopsis - template - basic_ostream& operator<<(basic_ostream& os, const shared_ptr& - ptr); + template< class T, class U, class V > + std::basic_ostream& operator<<( std::basic_ostream& os, const + std::shared_ptr& ptr ); - Inserts a shared_ptr into a std::basic_ostream. + Inserts the value of the pointer stored in ptr into the output stream os. Equivalent to os << ptr.get(). @@ -19,19 +22,19 @@ .SH Example - + // Run this code #include #include - + class Foo {}; - + int main() { auto sp = std::make_shared(); - std::cout << sp << std::endl; - std::cout << sp.get() << std::endl; + std::cout << sp << '\\n'; + std::cout << sp.get() << '\\n'; } .SH Possible output: @@ -41,5 +44,5 @@ .SH See also - get returns a pointer to the managed object - \fI(public member function)\fP + get returns the stored pointer + \fI(public member function)\fP diff --git a/man/std::shared_ptr::operator=.3 b/man/std::shared_ptr::operator=.3 index 4d56910a3..55b8a770c 100644 --- a/man/std::shared_ptr::operator=.3 +++ b/man/std::shared_ptr::operator=.3 @@ -1,35 +1,36 @@ -.TH std::shared_ptr::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::operator= \- std::shared_ptr::operator= + .SH Synopsis - shared_ptr& operator=( const shared_ptr& r ); \fB(1)\fP - template< class Y > \fB(1)\fP - shared_ptr& operator=( const shared_ptr& r ); - shared_ptr& operator=( shared_ptr&& r ); \fB(2)\fP - template< class Y > \fB(2)\fP - shared_ptr& operator=( shared_ptr&& r ); - template< class Y > \fB(3)\fP - shared_ptr& operator=( std::auto_ptr&& r ); - template< class Y, class Deleter > \fB(4)\fP - shared_ptr& operator=( std::unique_ptr&& r ); + shared_ptr& operator=( const shared_ptr& r ) noexcept; \fB(1)\fP + template< class Y > \fB(2)\fP + shared_ptr& operator=( const shared_ptr& r ) noexcept; + shared_ptr& operator=( shared_ptr&& r ) noexcept; \fB(3)\fP + template< class Y > \fB(4)\fP + shared_ptr& operator=( shared_ptr&& r ) noexcept; + template< class Y > \fB(5)\fP (deprecated in C++11) + shared_ptr& operator=( std::auto_ptr&& r ); (removed in C++17) + template< class Y, class Deleter > \fB(6)\fP + shared_ptr& operator=( std::unique_ptr&& r ); Replaces the managed object with the one managed by r. - 1) Shares ownership of the object managed by r. If r manages no object, *this - manages no object too. The templated overload doesn't participate in the overload - resolution if Y* is not implicitly convertible to T*. Equivalent to shared_ptr - p(r).swap(*this). - - 2) Move-assigns a shared_ptr from r. After the assignment, *this contains a copy of - the previous state of r, r is empty. The templated overload doesn't participate in - the overload resolution if Y* is not implicitly convertible to T*. Equivalent to - shared_ptr p(std::move(r)).swap(*this). - - 3) - - This section is incomplete - - 4) Transfers the ownership of the object managed by r to *this. The deleter + If *this already owns an object and it is the last shared_ptr owning it, and r is + not the same as *this, the object is destroyed through the owned deleter. + + 1,2) Shares ownership of the object managed by r. If r manages no object, *this + manages no object too. Equivalent to shared_ptr(r).swap(*this). + 3,4) Move-assigns a shared_ptr from r. After the assignment, *this contains a copy + of the previous state of r, and r is empty. Equivalent to + shared_ptr(std::move(r)).swap(*this). + 5) Transfers the ownership of the object managed by r to *this. If r manages no + object, *this manages no object too. After the assignment, *this contains the + pointer previously held by r, and use_count() == 1; also r is empty. Equivalent to + shared_ptr(r).swap(*this). + 6) Transfers the ownership of the object managed by r to *this. The deleter associated to r is stored for future deletion of the managed object. r manages no - object after the call. Equivalent to shared_ptr p(std::move(r)).swap(*this). + object after the call. Equivalent to shared_ptr(std::move(r)).swap(*this). .SH Parameters @@ -46,17 +47,7 @@ .SH Exceptions - 1-2) - noexcept specification: - noexcept - - - 3) \fI(none)\fP - - 4-5) - noexcept specification: - noexcept - + 5,6) May throw implementation-defined exceptions. .SH Example @@ -66,9 +57,7 @@ .SH See also reset replaces the managed object - \fI(public member function)\fP - - Categories: + \fI(public member function)\fP - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::shared_ptr::operator==,!=,<,<=,>,>=.3 b/man/std::shared_ptr::operator==,!=,<,<=,>,>=.3 deleted file mode 100644 index a3fe90e90..000000000 --- a/man/std::shared_ptr::operator==,!=,<,<=,>,>=.3 +++ /dev/null @@ -1,105 +0,0 @@ -.TH std::shared_ptr::operator==,!=,<,<=,>,>= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Compare two shared_ptr objects - template < class T, class U > - bool operator==( const shared_ptr& lhs, const shared_ptr& \fB(1)\fP \fI(since C++11)\fP - rhs ); - template< class T, class U > - bool operator!=( const shared_ptr& lhs, const shared_ptr& \fB(2)\fP \fI(since C++11)\fP - rhs ); - template< class T, class U > - bool operator<( const shared_ptr& lhs, const shared_ptr& \fB(3)\fP \fI(since C++11)\fP - rhs ); - template< class T, class U > - bool operator>( const shared_ptr& lhs, const shared_ptr& \fB(4)\fP \fI(since C++11)\fP - rhs ); - template< class T, class U > - bool operator<=( const shared_ptr& lhs, const shared_ptr& \fB(5)\fP \fI(since C++11)\fP - rhs ); - template< class T, class U > - bool operator>=( const shared_ptr& lhs, const shared_ptr& \fB(6)\fP \fI(since C++11)\fP - rhs ); - Compare a shared_ptr with a null pointer - template< class T > \fB(7)\fP \fI(since C++11)\fP - bool operator==( const shared_ptr& lhs, std::nullptr_t rhs ); - template< class T > \fB(8)\fP \fI(since C++11)\fP - bool operator==( std::nullptr_t lhs, const shared_ptr& rhs ); - template< class T > \fB(9)\fP \fI(since C++11)\fP - bool operator!=( const shared_ptr& lhs, std::nullptr_t rhs ); - template< class T > \fB(10)\fP \fI(since C++11)\fP - bool operator!=( std::nullptr_t lhs, const shared_ptr& rhs ); - template< class T > \fB(11)\fP \fI(since C++11)\fP - bool operator<( const shared_ptr& lhs, std::nullptr_t rhs ); - template< class T > \fB(12)\fP \fI(since C++11)\fP - bool operator<( std::nullptr_t lhs, const shared_ptr& rhs ); - template< class T > \fB(13)\fP \fI(since C++11)\fP - bool operator<=( const shared_ptr& lhs, std::nullptr_t rhs ); - template< class T > \fB(14)\fP \fI(since C++11)\fP - bool operator<=( std::nullptr_t lhs, const shared_ptr& rhs ); - template< class T > \fB(15)\fP \fI(since C++11)\fP - bool operator>( const shared_ptr& lhs, std::nullptr_t rhs ); - template< class T > \fB(16)\fP \fI(since C++11)\fP - bool operator>( std::nullptr_t lhs, const shared_ptr& rhs ); - template< class T > \fB(17)\fP \fI(since C++11)\fP - bool operator>=( const shared_ptr& lhs, std::nullptr_t rhs ); - template< class T > \fB(18)\fP \fI(since C++11)\fP - bool operator>=( std::nullptr_t lhs, const shared_ptr& rhs ); - - Compares two shared_ptr objects or compares shared_ptr with a null pointer. - - Note that the comparison operators for shared_ptr simply compare pointer values; the - actual objects pointed to are not compared. Having operator< defined for shared_ptr - allows shared_ptrs to be used as keys in associative containers, like std::map and - std::set. - -.SH Parameters - - lhs - the left-hand shared_ptr to compare - rhs - the right-hand shared_ptr to compare - -.SH Return value - - 1) lhs.get() == rhs.get() - 2) !(lhs == rhs) - 3) std::less()(lhs.get(), rhs.get()), where V is the composite pointer type - - This section is incomplete - Reason: needs definition from §5.9/2) - - of T* and U* - 4) rhs < lhs - 5) !(rhs < lhs) - 6) !(lhs < rhs) - 7) !lhs - 8) !rhs - 9) (bool)lhs - 10) (bool)rhs - 11) std::less()(lhs.get(), nullptr) - 12) std::less()(nullptr, rhs.get()) - 13) nullptr < lhs - 14) rhs < nullptr - 15) !(nullptr < lhs) - 16) !(rhs < nullptr) - 17) !(lhs < nullptr) - 18) !(nullptr < rhs) - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - get returns a pointer to the managed object - \fI(public member function)\fP - - Categories: - - * Todo with reason - * Todo no example diff --git a/man/std::shared_ptr::operator[].3 b/man/std::shared_ptr::operator[].3 new file mode 100644 index 000000000..93ad44165 --- /dev/null +++ b/man/std::shared_ptr::operator[].3 @@ -0,0 +1,59 @@ +.TH std::shared_ptr::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::operator[] \- std::shared_ptr::operator[] + +.SH Synopsis + element_type& operator[]( std::ptrdiff_t idx ) const; \fI(since C++17)\fP + + Index into the array pointed to by the stored pointer. + + The behavior is undefined if the stored pointer is null or if idx is negative. + + If T (the template parameter of shared_ptr) is an array type U[N], idx must be less + than N, otherwise the behavior is undefined. + +.SH Parameters + + idx - the array index + +.SH Return value + + A reference to the idx-th element of the array, i.e., get()[idx]. + +.SH Exceptions + + Throws nothing. + + Remarks + + When T is not an array type, it is unspecified whether this function is declared. If + the function is declared, it is unspecified what its return type is, except that the + declaration (although not necessarily the definition) of the function is guaranteed + to be legal. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const std::size_t arr_size = 10; + std::shared_ptr pis(new int[10]{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}); + for (std::size_t i = 0; i < arr_size; ++i) + std::cout << pis[i] << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 0 1 2 3 4 5 6 7 8 9 + +.SH See also + + get returns the stored pointer + \fI(public member function)\fP diff --git a/man/std::shared_ptr::operatorbool.3 b/man/std::shared_ptr::operatorbool.3 index d8bcaa6ce..6aeb99ea9 100644 --- a/man/std::shared_ptr::operatorbool.3 +++ b/man/std::shared_ptr::operatorbool.3 @@ -1,8 +1,11 @@ -.TH std::shared_ptr::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::operatorbool \- std::shared_ptr::operatorbool + .SH Synopsis - explicit operator bool() const; + explicit operator bool() const noexcept; - Checks if *this manages an object, i.e. whether get() != 0. + Checks if *this stores a non-null pointer, i.e. whether get() != nullptr. .SH Parameters @@ -10,39 +13,35 @@ .SH Return value - true if *this manages an object, false otherwise. + true if *this stores a pointer, false otherwise. -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + An empty shared_ptr (where use_count() == 0) may store a non-null pointer accessible + by get(), e.g. if it were created using the aliasing constructor. .SH Example - + // Run this code #include #include - - typedef std::shared_ptr IntPtr; - - void report(IntPtr ptr) + + void report(std::shared_ptr ptr) { - if (ptr) { + if (ptr) std::cout << "*ptr=" << *ptr << "\\n"; - } else { + else std::cout << "ptr is not a valid pointer.\\n"; - } } - + int main() { - IntPtr ptr; + std::shared_ptr ptr; report(ptr); - - ptr = IntPtr(new int(7)); + + ptr = std::make_shared(7); report(ptr); } @@ -53,5 +52,5 @@ .SH See also - get returns a pointer to the managed object - \fI(public member function)\fP + get returns the stored pointer + \fI(public member function)\fP diff --git a/man/std::shared_ptr::owner_before.3 b/man/std::shared_ptr::owner_before.3 index a6e1aa093..9afff9e5b 100644 --- a/man/std::shared_ptr::owner_before.3 +++ b/man/std::shared_ptr::owner_before.3 @@ -1,15 +1,18 @@ -.TH std::shared_ptr::owner_before 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::owner_before 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::owner_before \- std::shared_ptr::owner_before + .SH Synopsis - template< class T > - bool owner_before( const shared_ptr& other) const; - template< class T > - bool owner_before( const std::weak_ptr& other) const; + template< class Y > + bool owner_before( const shared_ptr& other ) const noexcept; + template< class Y > + bool owner_before( const std::weak_ptr& other ) const noexcept; Checks whether this shared_ptr precedes other in implementation defined owner-based (as opposed to value-based) order. The order is such that two smart pointers compare equivalent only if they are both empty or if they both own the same object, even if the values of the pointers obtained by get() are different (e.g. because they point - at different subobjects within the same object) + at different subobjects within the same object). This ordering is used to make shared and weak pointers usable as keys in associative containers, typically through std::owner_less. @@ -25,37 +28,38 @@ .SH Example - + // Run this code #include #include - - struct Foo { + + struct Foo + { int n1; int n2; Foo(int a, int b) : n1(a), n2(b) {} }; + int main() { auto p1 = std::make_shared(1, 2); std::shared_ptr p2(p1, &p1->n1); std::shared_ptr p3(p1, &p1->n2); - + std::cout << std::boolalpha << "p2 < p3 " << (p2 < p3) << '\\n' << "p3 < p2 " << (p3 < p2) << '\\n' << "p2.owner_before(p3) " << p2.owner_before(p3) << '\\n' << "p3.owner_before(p2) " << p3.owner_before(p2) << '\\n'; - + std::weak_ptr w2(p2); std::weak_ptr w3(p3); std::cout - // << "w2 < w3 " << (w2 < w3) << '\\n' // won't compile - // << "w3 < w2 " << (w3 < w2) << '\\n' // won't compile + // << "w2 < w3 " << (w2 < w3) << '\\n' // won't compile + // << "w3 < w2 " << (w3 < w2) << '\\n' // won't compile << "w2.owner_before(w3) " << w2.owner_before(w3) << '\\n' << "w3.owner_before(w2) " << w3.owner_before(w2) << '\\n'; - } .SH Output: @@ -67,7 +71,15 @@ w2.owner_before(w3) false w3.owner_before(w2) false + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2873 C++11 owner_before was not declared noexcept declared noexcept + .SH See also owner_less provides mixed-type owner-based ordering of shared and weak pointers - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::shared_ptr::owner_equal.3 b/man/std::shared_ptr::owner_equal.3 new file mode 100644 index 000000000..464c31bfe --- /dev/null +++ b/man/std::shared_ptr::owner_equal.3 @@ -0,0 +1,52 @@ +.TH std::shared_ptr::owner_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::owner_equal \- std::shared_ptr::owner_equal + +.SH Synopsis + template< class Y > + bool owner_equal( const std::shared_ptr& other ) const \fB(1)\fP (since C++26) + noexcept; + template< class Y > \fB(2)\fP (since C++26) + bool owner_equal( const std::weak_ptr& other ) const noexcept; + + Checks whether this shared_ptr and other share ownership or are both empty. The + comparison is such that two smart pointers compare equivalent only if they are both + empty or if they both own the same object, even if the values of the pointers + obtained by get() are different (e.g. because they point at different subobjects + within the same object). + + The member function owner_equal is an equivalence relation such that + !owner_before(other) && !other.owner_before(*this) is true if and only if + owner_equal(other) is true. + + This ordering is used to make shared and weak pointers usable as keys in unordered + associative containers, typically through std::owner_equal. + +.SH Parameters + + other - the std::shared_ptr or std::weak_ptr to be compared + +.SH Return value + + true if *this and other share ownership or are both empty. Otherwise, returns false. + +.SH Notes + + Feature-test macro Value Std Feature + Enabling the use of + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) std::shared_ptr as keys in + unordered associative containers + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + owner_equal provides mixed-type owner-based equal comparisons of shared and weak + (C++26) pointers + \fI(class)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::shared_ptr::owner_hash.3 b/man/std::shared_ptr::owner_hash.3 new file mode 100644 index 000000000..eb37970bf --- /dev/null +++ b/man/std::shared_ptr::owner_hash.3 @@ -0,0 +1,37 @@ +.TH std::shared_ptr::owner_hash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::owner_hash \- std::shared_ptr::owner_hash + +.SH Synopsis + std::size_t owner_hash() const noexcept; (since C++26) + + Returns an unspecified value such that for any object other where owner_equal(other) + is true, owner_hash() == other.owner_hash() is true. + + This hashing is used to make shared and weak pointers usable as keys in unordered + associative containers, typically through std::owner_hash. + +.SH Return value + + A value that is identical for any std::shared_ptr or std::weak_ptr object sharing + the same ownership. + +.SH Notes + + Feature-test macro Value Std Feature + Enabling the use of + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) std::shared_ptr as keys in + unordered associative containers + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + owner_hash provides owner-based hashing for shared and weak pointers + (C++26) \fI(class)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::shared_ptr::reset.3 b/man/std::shared_ptr::reset.3 index 66eab0e27..f93606b06 100644 --- a/man/std::shared_ptr::reset.3 +++ b/man/std::shared_ptr::reset.3 @@ -1,6 +1,9 @@ -.TH std::shared_ptr::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::reset \- std::shared_ptr::reset + .SH Synopsis - void reset(); \fB(1)\fP \fI(since C++11)\fP + void reset() noexcept; \fB(1)\fP \fI(since C++11)\fP template< class Y > \fB(2)\fP \fI(since C++11)\fP void reset( Y* ptr ); template< class Y, class Deleter > \fB(3)\fP \fI(since C++11)\fP @@ -17,23 +20,24 @@ If *this already owns an object and it is the last shared_ptr owning it, the object is destroyed through the owned deleter. - If the object pointed to by ptr is already owned, the function results in undefined - behavior. + If the object pointed to by ptr is already owned, the function generally results in + undefined behavior. 1) Releases the ownership of the managed object, if any. After the call, *this - manages no object. Equivalent to shared_ptr().swap(*this); + manages no object. Equivalent to shared_ptr().swap(*this);. 2-4) Replaces the managed object with an object pointed to by ptr. Y must be a complete type and implicitly convertible to T. Additionally: 2) Uses the delete expression as the deleter. A valid delete expression must be available, i.e. delete ptr must be well formed, have well-defined behavior and not - throw any exceptions. Effectively calls shared_ptr(ptr).swap(*this);. + throw any exceptions. Equivalent to shared_ptr(ptr).swap(*this);. 3) Uses the specified deleter d as the deleter. Deleter must be callable for the type T, i.e. d(ptr) must be well formed, have well-defined behavior and not throw - any exceptions. Deleter must be CopyConstructible. Effectively calls - shared_ptr(ptr, d).swap(*this);. + any exceptions. Deleter must be CopyConstructible, and its copy constructor and + destructor must not throw exceptions. Equivalent to shared_ptr(ptr, + d).swap(*this);. 4) Same as \fB(3)\fP, but additionally uses a copy of alloc for allocation of data for - internal use. Alloc must be a Allocator. The copy constructor and destructor must - not throw exceptions. Effectively calls shared_ptr(ptr, d, alloc).swap(*this);. + internal use. Alloc must be an Allocator. The copy constructor and destructor must + not throw exceptions. Equivalent to shared_ptr(ptr, d, alloc).swap(*this);. .SH Parameters @@ -47,27 +51,127 @@ .SH Exceptions - 1) - noexcept specification: - noexcept - - 2-4) As specified by the relevant constructor - - This section is incomplete - - . + 2) std::bad_alloc if required additional memory could not be obtained. May throw + implementation-defined exception for other errors. delete ptr is called if an + exception occurs. + 3,4) std::bad_alloc if required additional memory could not be obtained. May throw + implementation-defined exception for other errors. d(ptr) is called if an exception + occurs. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + struct Foo + { + Foo(int n = 0) noexcept : bar(n) + { + std::cout << "Foo::Foo(), bar = " << bar << " @ " << this << '\\n'; + } + ~Foo() + { + std::cout << "Foo::~Foo(), bar = " << bar << " @ " << this << '\\n'; + } + int getBar() const noexcept { return bar; } + private: + int bar; + }; + + int main() + { + std::cout << "1) unique ownership\\n"; + { + std::shared_ptr sptr = std::make_shared(100); + + std::cout << "Foo::bar = " << sptr->getBar() << ", use_count() = " + << sptr.use_count() << '\\n'; + + // Reset the shared_ptr without handing it a fresh instance of Foo. + // The old instance will be destroyed after this call. + std::cout << "call sptr.reset()...\\n"; + sptr.reset(); // calls Foo's destructor here + std::cout << "After reset(): use_count() = " << sptr.use_count() + << ", sptr = " << sptr << '\\n'; + } // No call to Foo's destructor, it was done earlier in reset(). + + std::cout << "\\n2) unique ownership\\n"; + { + std::shared_ptr sptr = std::make_shared(200); + + std::cout << "Foo::bar = " << sptr->getBar() << ", use_count() = " + << sptr.use_count() << '\\n'; + + // Reset the shared_ptr, hand it a fresh instance of Foo. + // The old instance will be destroyed after this call. + std::cout << "call sptr.reset()...\\n"; + sptr.reset(new Foo{222}); + std::cout << "After reset(): use_count() = " << sptr.use_count() + << ", sptr = " << sptr << "\\nLeaving the scope...\\n"; + } // Calls Foo's destructor. + + std::cout << "\\n3) multiple ownership\\n"; + { + std::shared_ptr sptr1 = std::make_shared(300); + std::shared_ptr sptr2 = sptr1; + std::shared_ptr sptr3 = sptr2; + + std::cout << "Foo::bar = " << sptr1->getBar() << ", use_count() = " + << sptr1.use_count() << '\\n'; + + // Reset the shared_ptr sptr1, hand it a fresh instance of Foo. + // The old instance will stay shared between sptr2 and sptr3. + std::cout << "call sptr1.reset()...\\n"; + sptr1.reset(new Foo{333}); + + std::cout << "After reset():\\n" + << "sptr1.use_count() = " << sptr1.use_count() + << ", sptr1 @ " << sptr1 << '\\n' + << "sptr2.use_count() = " << sptr2.use_count() + << ", sptr2 @ " << sptr2 << '\\n' + << "sptr3.use_count() = " << sptr3.use_count() + << ", sptr3 @ " << sptr3 << '\\n' + << "Leaving the scope...\\n"; + } // Calls two destructors of: 1) Foo owned by sptr1, + // 2) Foo shared between sptr2/sptr3. + } + +.SH Possible output: + + 1) unique ownership + Foo::Foo(), bar = 100 @ 0x23c5040 + Foo::bar = 100, use_count() = 1 + call sptr.reset()... + Foo::~Foo(), bar = 100 @ 0x23c5040 + After reset(): use_count() = 0, sptr = 0 + + 2) unique ownership + Foo::Foo(), bar = 200 @ 0x23c5040 + Foo::bar = 200, use_count() = 1 + call sptr.reset()... + Foo::Foo(), bar = 222 @ 0x23c5050 + Foo::~Foo(), bar = 200 @ 0x23c5040 + After reset(): use_count() = 1, sptr = 0x23c5050 + Leaving the scope... + Foo::~Foo(), bar = 222 @ 0x23c5050 + + 3) multiple ownership + Foo::Foo(), bar = 300 @ 0x23c5080 + Foo::bar = 300, use_count() = 3 + call sptr1.reset()... + Foo::Foo(), bar = 333 @ 0x23c5050 + After reset(): + sptr1.use_count() = 1, sptr1 @ 0x23c5050 + sptr2.use_count() = 2, sptr2 @ 0x23c5080 + sptr3.use_count() = 2, sptr3 @ 0x23c5080 + Leaving the scope... + Foo::~Foo(), bar = 300 @ 0x23c5080 + Foo::~Foo(), bar = 333 @ 0x23c5050 .SH See also constructor constructs new shared_ptr - \fI(public member function)\fP - - Categories: - - * Todo without reason - * Todo no example + \fI(public member function)\fP diff --git a/man/std::shared_ptr::shared_ptr.3 b/man/std::shared_ptr::shared_ptr.3 index 828836123..f02ec67cd 100644 --- a/man/std::shared_ptr::shared_ptr.3 +++ b/man/std::shared_ptr::shared_ptr.3 @@ -1,90 +1,126 @@ -.TH std::shared_ptr::shared_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::shared_ptr \- std::shared_ptr::shared_ptr + .SH Synopsis - constexpr shared_ptr(); \fB(1)\fP - template< class Y > \fB(2)\fP + constexpr shared_ptr() noexcept; \fB(1)\fP + constexpr shared_ptr( std::nullptr_t ) noexcept; \fB(2)\fP + template< class Y > \fB(3)\fP explicit shared_ptr( Y* ptr ); - template< class Y, class Deleter > \fB(3)\fP + template< class Y, class Deleter > \fB(4)\fP shared_ptr( Y* ptr, Deleter d ); - template< class Y, class Deleter, class Alloc > \fB(4)\fP + template< class Deleter > \fB(5)\fP + shared_ptr( std::nullptr_t ptr, Deleter d ); + template< class Y, class Deleter, class Alloc > \fB(6)\fP shared_ptr( Y* ptr, Deleter d, Alloc alloc ); - constexpr shared_ptr( std::nullptr_t ); \fB(5)\fP - template< class Deleter > \fB(6)\fP - shared_ptr( std::nullptr_t, Deleter d ); - template< class Deleter, class Alloc > \fB(7)\fP - shared_ptr( std::nullptr_t, Deleter d, Alloc alloc ); - template< class Y > \fB(8)\fP - shared_ptr( const shared_ptr& r, T *ptr ); - shared_ptr( const shared_ptr& r ); \fB(9)\fP - template< class Y > \fB(9)\fP - shared_ptr( const shared_ptr& r ); - shared_ptr( shared_ptr&& r ); \fB(10)\fP - template< class Y > \fB(10)\fP - shared_ptr( shared_ptr&& r ); - template< class Y > \fB(11)\fP + template< class Deleter, class Alloc > \fB(7)\fP + shared_ptr( std::nullptr_t ptr, Deleter d, Alloc alloc ); + template< class Y > + shared_ptr( const shared_ptr& r, element_type* ptr ) \fB(8)\fP + noexcept; + template< class Y > \fB(8)\fP \fI(since C++20)\fP + shared_ptr( shared_ptr&& r, element_type* ptr ) noexcept; + shared_ptr( const shared_ptr& r ) noexcept; \fB(9)\fP + template< class Y > \fB(9)\fP + shared_ptr( const shared_ptr& r ) noexcept; + shared_ptr( shared_ptr&& r ) noexcept; \fB(10)\fP + template< class Y > \fB(10)\fP + shared_ptr( shared_ptr&& r ) noexcept; + template< class Y > \fB(11)\fP explicit shared_ptr( const std::weak_ptr& r ); - template< class Y > \fB(12)\fP + template< class Y > \fB(12)\fP (removed in C++17) shared_ptr( std::auto_ptr&& r ); - template< class Y, class Deleter > \fB(13)\fP - shared_ptr( std::unique_ptr&& r ); + template< class Y, class Deleter > \fB(13)\fP + shared_ptr( std::unique_ptr&& r ); Constructs new shared_ptr from a variety of pointer types that refer to an object to manage. - An optional deleter d can be supplied that is later used to destroy the object when - no shared_ptr objects own it. By default, a delete-expression for type Y is used as - the deleter. - - 1) Default constructor constructs a shared_ptr with no managed object, i.e. empty - shared_ptr - 2-4) Constructs a shared_ptr with ptr as the pointer to the managed object. Y must - be a complete type and ptr must be convertible to T*. Additionally: - 2) Uses the delete expression as the deleter. A valid delete expression must be - available, i.e. delete ptr must be well formed, have well-defined behavior and not - throw any exceptions. - 3) Uses the specified deleter d as the deleter. Deleter must be callable for the - type T, i.e. d(ptr) must be well formed, have well-defined behavior and not throw - any exceptions. Deleter must be CopyConstructible. The copy constructor and the - destructor must not throw exceptions. - 4) Same as \fB(3)\fP, but additionally uses a copy of alloc for allocation of data for - internal use. Alloc must be a Allocator. The copy constructor and destructor must - not throw exceptions. - 5-7) Analogous to \fB(2)\fP, \fB(3)\fP, \fB(4)\fP respectively, but constructs a shared_ptr with no - managed object, i.e. empty shared_ptr. - 8) Constructs a shared_ptr which shares ownership information with r, but holds an - unrelated and unmanaged pointer ptr. Even if this shared_ptr is the last of the - group to go out of scope, it will call the destructor for the object originally - managed by r. However, calling get() on this will always return a copy of ptr. It is - the responsibility of the programmer to make sure that this ptr remains valid as - long as this shared_ptr exists, such as in the typical use cases where ptr is a - member of the object managed by r or is an alias (e.g., downcast) of r.get() + For the purposes of the description below, a pointer type Y* is said + to be compatible with a pointer type T* if either Y* is convertible to \fI(since C++17)\fP + T* or Y is the array type U[N] and T is U cv [] (where cv is some set + of cv-qualifiers). + + 1,2) Constructs a shared_ptr with no managed object, i.e. empty shared_ptr. + 3-7) Constructs a shared_ptr with ptr as the pointer to the managed object. + + For (3,4,6), Y* must be convertible to T*. \fI(until C++17)\fP + If T is an array type U[N], (3,4,6) do not participate in overload + resolution if Y(*)[N] is an invalid type or not convertible to T*. If + T is an array type U[], (3,4,6) do not participate in overload \fI(since C++17)\fP + resolution if Y(*)[] is an invalid type or not convertible to T*. + Otherwise, (3,4,6) do not participate in overload resolution if Y* is + not convertible to T*. + + Additionally: + 3) Uses the delete-expression delete ptr + if T is not an array type; delete[] ptr if T is an array type + \fI(since C++17)\fP as the deleter. Y must be a complete type. The delete expression must + be well-formed, have well-defined behavior and not throw any exceptions. + This constructor additionally does not participate in overload resolution if the + delete expression is not well-formed. + \fI(since C++17)\fP + 4,5) Uses the specified deleter d as the deleter. The expression d(ptr) must be well + formed, have well-defined behavior and not throw any exceptions. The construction of + d and of the stored deleter copied from it must not throw exceptions. + + Deleter must be CopyConstructible. \fI(until C++17)\fP + These constructors additionally do not participate in overload + resolution if the expression d(ptr) is not well-formed, or if \fI(since C++17)\fP + std::is_move_constructible_v is false. + + 6,7) Same as (4,5), but additionally uses a copy of alloc for allocation of data for + internal use. Alloc must be an Allocator. + 8) The aliasing constructor: constructs a shared_ptr which shares ownership + information with the initial value of r, but holds an unrelated and unmanaged + pointer ptr. If this shared_ptr is the last of the group to go out of scope, it will + call the stored deleter for the object originally managed by r. However, calling + get() on this shared_ptr will always return a copy of ptr. It is the responsibility + of the programmer to make sure that this ptr remains valid as long as this + shared_ptr exists, such as in the typical use cases where ptr is a member of the + object managed by r or is an alias (e.g., downcast) of r.get() + For the second overload taking an rvalue, r is empty and r.get() == nullptr after + the call. + \fI(since C++20)\fP 9) Constructs a shared_ptr which shares ownership of the object managed by r. If r - manages no object, *this manages no object too. The templated overload doesn't - participate in the overload resolution if Y* is not implicitly convertible to T*. + manages no object, *this manages no object either. The template overload doesn't + participate in overload resolution if Y* is not + implicitly convertible to + \fI(until C++17)\fP + compatible with + \fI(since C++17)\fP T*. 10) Move-constructs a shared_ptr from r. After the construction, *this contains a - copy of the previous state of r, r is empty. The templated overload doesn't - participate in the overload resolution if Y* is not implicitly convertible to T*. - 11) Constructs a shared_ptr which shares ownership of the object managed by r. Y* - must be convertible to T*. Note that r.lock() may be used for the same purpose: the - difference is that this constructor throws an exception if the argument is empty, - while std::weak_ptr::lock() constructs an empty std::shared_ptr in that case. + copy of the previous state of r, r is empty and its stored pointer is null. The + template overload doesn't participate in overload resolution if Y* is not + implicitly convertible to + \fI(until C++17)\fP + compatible with + \fI(since C++17)\fP T*. + 11) Constructs a shared_ptr which shares ownership of the object managed by r. + Y* must be implicitly convertible to T*. + \fI(until C++17)\fP + This overload participates in overload resolution only if Y* is compatible with T*. + \fI(since C++17)\fP Note that r.lock() may be used for the same purpose: the difference is + that this constructor throws an exception if the argument is empty, while + std::weak_ptr::lock() constructs an empty std::shared_ptr in that case. 12) Constructs a shared_ptr that stores and owns the object formerly owned by r. Y* must be convertible to T*. After construction, r is empty. 13) Constructs a shared_ptr which manages the object currently managed by r. The - deleter associated to r is stored for future deletion of the managed object. r - manages no object after the call. Y* must be convertible to T*. + deleter associated with r is stored for future deletion of the managed object. r + manages no object after the call. -.SH Notes + This overload doesn't participate in overload resolution if + std::unique_ptr::pointer is not compatible with T*. If \fI(since C++17)\fP + r.get() is a null pointer, this overload is equivalent to the default + constructor \fB(1)\fP. - When constructing a shared_ptr from a raw pointer to an object of a type derived - from std::enable_shared_from_this, the constructors of shared_ptr update the private - weak_ptr member of the std::enable_shared_from_this base so that future calls to - shared_from_this() would share ownership with the shared_ptr created by this raw - pointer constructor. + If Deleter is a reference type, it is equivalent to shared_ptr(r.release(), + std::ref(r.get_deleter()). Otherwise, it is equivalent to shared_ptr(r.release(), + std::move(r.get_deleter())). - Constructing a shared_ptr using the raw pointer overload for an object that is - already managed by a shared_ptr leads to undefined behavior, even if the object is - of a type derived from std::enable_shared_from_this (in other words, raw pointer - overloads assume ownership of the pointed-to object). + When T is not an array type, the overloads (3,4,6) enable shared_from_this with ptr, + and the overload \fB(13)\fP enables shared_from_this with the pointer returned by + r.release(). .SH Parameters @@ -96,92 +132,151 @@ .SH Exceptions - 1) - noexcept specification: - noexcept - - 2) std::bad_alloc if required additional memory could not be obtained. May throw - implementation-defined exception for other errors. delete ptr is called if an - exception occurs. - 3-4) std::bad_alloc if required additional memory could not be obtained. May throw + 3) std::bad_alloc if required additional memory could not be obtained. May throw + implementation-defined exception for other errors. If an exception occurs, this + calls delete ptr + if T is not an array type, and calls delete[] ptr otherwise + \fI(since C++17)\fP. + 4-7) std::bad_alloc if required additional memory could not be obtained. May throw implementation-defined exception for other errors. d(ptr) is called if an exception occurs. - 5) - noexcept specification: - noexcept - - 6-7) std::bad_alloc if required additional memory could not be obtained. May throw - implementation-defined exception for other errors. If an exception is thrown, d(ptr) - is executed. - 8-10) - noexcept specification: - noexcept - - 11) std::bad_weak_ptr if r.expired == true. The constructor has no effect in this + 11) std::bad_weak_ptr if r.expired() == true. The constructor has no effect in this case. 12) std::bad_alloc if required additional memory could not be obtained. May throw implementation-defined exception for other errors. This constructor has no effect if an exception occurs. 13) If an exception is thrown, the constructor has no effects. +.SH Notes + + A constructor enables shared_from_this with a pointer ptr of type U* means that it + determines if U has an + unambiguous and accessible + \fI(since C++17)\fP base class that is a specialization of std::enable_shared_from_this, + and if so, the constructor evaluates the statement: + + if (ptr != nullptr && ptr->weak_this.expired()) + ptr->weak_this = std::shared_ptr>( + *this, const_cast*>(ptr)); + + Where weak_this is the hidden mutable std::weak_ptr member of + std::enable_shared_from_this. The assignment to the weak_this member is not atomic + and conflicts with any potentially concurrent access to the same object. This + ensures that future calls to shared_from_this() would share ownership with the + std::shared_ptr created by this raw pointer constructor. + + The test ptr->weak_this.expired() in the exposition code above makes sure that + weak_this is not reassigned if it already indicates an owner. This test is required + as of C++17. + + The raw pointer overloads assume ownership of the pointed-to object. Therefore, + constructing a shared_ptr using the raw pointer overload for an object that is + already managed by a shared_ptr, such as by shared_ptr(ptr.get()) is likely to lead + to undefined behavior, even if the object is of a type derived from + std::enable_shared_from_this. + + Because the default constructor is constexpr, static shared_ptrs are initialized as + part of static non-local initialization, before any dynamic non-local initialization + begins. This makes it safe to use a shared_ptr in a constructor of any static + object. + + In C++11 and C++14 it is valid to construct a std::shared_ptr from a + std::unique_ptr: + + std::unique_ptr arr(new int[1]); + std::shared_ptr ptr(std::move(arr)); + + Since the shared_ptr obtains its deleter (a std::default_delete object) from + the std::unique_ptr, the array will be correctly deallocated. + + This is no longer allowed in C++17. Instead the array form std::shared_ptr + should be used. + .SH Example - + // Run this code - #include #include - - struct Foo { - Foo() { std::cout << "Foo...\\n"; } - ~Foo() { std::cout << "~Foo...\\n"; } + #include + + struct Foo + { + int id{0}; + Foo(int i = 0) : id{i} { std::cout << "Foo::Foo(" << i << ")\\n"; } + ~Foo() { std::cout << "Foo::~Foo(), id=" << id << '\\n'; } }; - - struct D { - void operator()(Foo* p) const { - std::cout << "Call delete for Foo object...\\n"; + + struct D + { + void operator()(Foo* p) const + { + std::cout << "Call delete from function object. Foo::id=" << p->id << '\\n'; delete p; } }; - + int main() { { - std::cout << "constructor with no managed object\\n"; + std::cout << "1) constructor with no managed object\\n"; std::shared_ptr sh1; } - + { - std::cout << "constructor with object\\n"; - std::shared_ptr sh2(new Foo); + std::cout << "2) constructor with object\\n"; + std::shared_ptr sh2(new Foo{10}); + std::cout << "sh2.use_count(): " << sh2.use_count() << '\\n'; std::shared_ptr sh3(sh2); - std::cout << sh2.use_count() << '\\n'; - std::cout << sh3.use_count() << '\\n'; + std::cout << "sh2.use_count(): " << sh2.use_count() << '\\n'; + std::cout << "sh3.use_count(): " << sh3.use_count() << '\\n'; } - + { - std::cout << "constructor with object and deleter\\n"; - std::shared_ptr sh4(new Foo, D()); + std::cout << "3) constructor with object and deleter\\n"; + std::shared_ptr sh4(new Foo{11}, D()); + std::shared_ptr sh5(new Foo{12}, [](auto p) + { + std::cout << "Call delete from lambda... p->id=" << p->id << '\\n'; + delete p; + }); } } .SH Output: - constructor with no managed object - constructor with object - Foo... - 2 - 2 - ~Foo... - constructor with object and deleter - Foo... - Call delete for Foo object... - ~Foo... + 1) constructor with no managed object + 2) constructor with object + Foo::Foo\fB(10)\fP + sh2.use_count(): 1 + sh2.use_count(): 2 + sh3.use_count(): 2 + Foo::~Foo(), id=10 + 3) constructor with object and deleter + Foo::Foo\fB(11)\fP + Foo::Foo\fB(12)\fP + Call delete from lambda... p->id=12 + Foo::~Foo(), id=12 + Call delete from function object. Foo::id=11 + Foo::~Foo(), id=11 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3548 C++11 the constructor from unique_ptr move-constructs instead + copy-constructed the deleter .SH See also - make_shared creates a shared pointer that manages a new object - \fI(function template)\fP - creates a shared pointer that manages a new object allocated using - allocate_shared an allocator - \fI(function template)\fP + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) + allocate_shared creates a shared pointer that manages a new object + allocate_shared_for_overwrite allocated using an allocator + (C++20) \fI(function template)\fP + enable_shared_from_this allows an object to create a shared_ptr referring to + \fI(C++11)\fP itself + \fI(class template)\fP diff --git a/man/std::shared_ptr::swap.3 b/man/std::shared_ptr::swap.3 index 6677bf273..9f806d241 100644 --- a/man/std::shared_ptr::swap.3 +++ b/man/std::shared_ptr::swap.3 @@ -1,8 +1,12 @@ -.TH std::shared_ptr::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::swap \- std::shared_ptr::swap + .SH Synopsis - void swap( shared_ptr& r ); + void swap( shared_ptr& r ) noexcept; \fI(since C++11)\fP - Exchanges the contents of *this and r + Exchanges the stored pointer values and the ownerships of *this and r. Reference + counts, if any, are not adjusted. .SH Parameters @@ -12,8 +16,51 @@ \fI(none)\fP -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo + { + Foo(int _val) : val(_val) { std::cout << "Foo...\\n"; } + ~Foo() { std::cout << "~Foo...\\n"; } + std::string print() { return std::to_string(val); } + int val; + }; + + int main() + { + std::shared_ptr p1 = std::make_shared(100); + std::shared_ptr p2 = std::make_shared(200); + auto print = [&]() + { + std::cout << " p1=" << (p1 ? p1->print() : "nullptr"); + std::cout << " p2=" << (p2 ? p2->print() : "nullptr") << '\\n'; + }; + print(); + + p1.swap(p2); + print(); + + p1.reset(); + print(); + + p1.swap(p2); + print(); + } + +.SH Output: - noexcept specification: - noexcept - + Foo... + Foo... + p1=100 p2=200 + p1=200 p2=100 + ~Foo... + p1=nullptr p2=100 + p1=100 p2=nullptr + ~Foo... diff --git a/man/std::shared_ptr::unique.3 b/man/std::shared_ptr::unique.3 index 0e877f1a6..b966b4aa2 100644 --- a/man/std::shared_ptr::unique.3 +++ b/man/std::shared_ptr::unique.3 @@ -1,6 +1,10 @@ -.TH std::shared_ptr::unique 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::unique 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::unique \- std::shared_ptr::unique + .SH Synopsis - bool unique() const; + bool unique() const noexcept; (deprecated in C++17) + (removed in C++20) Checks if *this is the only shared_ptr instance managing the current object, i.e. whether use_count() == 1. @@ -14,21 +18,27 @@ true if *this is the only shared_ptr instance managing the current object, false otherwise. +.SH Notes + + This function was deprecated in C++17 and removed in C++20 because use_count is only + an approximation in multithreaded environment (see Notes in use_count). + .SH Example - + // Run this code - #include #include - + #include + int main() { - std::shared_ptr sp1 {std::make_shared(5)}; - std::cout << "sp1.unique() == " << std::boolalpha << sp1.unique() << std::endl; - - std::shared_ptr sp2 {sp1}; - std::cout << "sp1.unique() == " << std::boolalpha << sp1.unique() << std::endl; + auto sp1 = std::make_shared(5); + std::cout << std::boolalpha; + std::cout << "sp1.unique() == " << sp1.unique() << '\\n'; + + std::shared_ptr sp2 = sp1; + std::cout << "sp1.unique() == " << sp1.unique() << '\\n'; } .SH Output: @@ -40,4 +50,4 @@ returns the number of shared_ptr objects referring to the same managed use_count object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::shared_ptr::use_count.3 b/man/std::shared_ptr::use_count.3 index 5a839af88..6b5b21eac 100644 --- a/man/std::shared_ptr::use_count.3 +++ b/man/std::shared_ptr::use_count.3 @@ -1,47 +1,70 @@ -.TH std::shared_ptr::use_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::use_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::use_count \- std::shared_ptr::use_count + .SH Synopsis - long use_count() const; + long use_count() const noexcept; Returns the number of different shared_ptr instances (this included) managing the current object. If there is no managed object, 0 is returned. + In multithreaded environment, the value returned by use_count is approximate + (typical implementations use a memory_order_relaxed load). + .SH Parameters \fI(none)\fP .SH Return value - the number of shared_ptr instances managing the current object or 0 if there is no - managed object. + The number of std::shared_ptr instances managing the current object or 0 if there is + no managed object. + +.SH Notes + + Common use cases include + + * comparison with 0. If use_count returns zero, the shared pointer is empty and + manages no objects (whether or not its stored pointer is nullptr). + * comparison with 1. If use_count returns 1, there are no other owners. + The + deprecated + \fI(since C++17)\fP member function unique() is provided for this use case. + \fI(until C++20)\fP In multithreaded environment, this does not imply that the object + is safe to modify because accesses to the managed object by former shared owners + may not have completed, and because new shared owners may be introduced + concurrently, such as by std::weak_ptr::lock. .SH Example - + // Run this code - #include #include - + #include + void fun(std::shared_ptr sp) { - std::cout << "fun: sp.use_count() == " << sp.use_count() << std::endl; + std::cout << "in fun(): sp.use_count() == " << sp.use_count() + << " (object @ " << sp << ")\\n"; } - + int main() { - std::shared_ptr sp1 {std::make_shared(5)}; - std::cout << "sp1.use_count() == " << sp1.use_count() << std::endl; - + auto sp1 = std::make_shared(5); + std::cout << "in main(): sp1.use_count() == " << sp1.use_count() + << " (object @ " << sp1 << ")\\n"; + fun(sp1); } -.SH Output: +.SH Possible output: - sp1.use_count() == 1 - fun: sp.use_count() == 2 + in main(): sp1.use_count() == 1 (object @ 0x20eec30) + in fun(): sp.use_count() == 2 (object @ 0x20eec30) .SH See also - checks whether the managed object is managed only by the current shared_ptr - unique instance - \fI(public member function)\fP + unique checks whether the managed object is managed only by the current + \fI(until C++20)\fP shared_ptr object + \fI(public member function)\fP diff --git a/man/std::shared_ptr::~shared_ptr.3 b/man/std::shared_ptr::~shared_ptr.3 index a6bf447a0..251c30411 100644 --- a/man/std::shared_ptr::~shared_ptr.3 +++ b/man/std::shared_ptr::~shared_ptr.3 @@ -1,18 +1,80 @@ -.TH std::shared_ptr::~shared_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shared_ptr::~shared_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_ptr::~shared_ptr \- std::shared_ptr::~shared_ptr + .SH Synopsis ~shared_ptr(); If *this owns an object and it is the last shared_ptr owning it, the object is - destroyed through the owned deleter. Otherwise does nothing. + destroyed through the owned deleter. + + After the destruction, the smart pointers that shared ownership with *this, if any, + will report a use_count() that is one less than its previous value. + +.SH Notes + + Unlike std::unique_ptr, the deleter of std::shared_ptr is invoked even if the + managed pointer is null. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + + struct S + { + S() { std::cout << "S::S()\\n"; } + ~S() { std::cout << "S::~S()\\n"; } + struct Deleter + { + void operator()(S* s) const + { + std::cout << "S::Deleter()\\n"; + delete s; + } + }; + }; + int main() + { + auto sp = std::shared_ptr{new S, S::Deleter{}}; -.SH Category: + auto use_count = [&sp](char c) + { + std::cout << c << ") use_count(): " << sp.use_count() << '\\n'; + }; + + use_count('A'); + { + auto sp2 = sp; + use_count('B'); + { + auto sp3 = sp; + use_count('C'); + } + use_count('D'); + } + use_count('E'); + + // sp.reset(); + // use_count('F'); // would print "F) use_count(): 0" + } + +.SH Output: + + S::S() + A) use_count(): 1 + B) use_count(): 2 + C) use_count(): 3 + D) use_count(): 2 + E) use_count(): 1 + S::Deleter() + S::~S() + +.SH See also - * Todo no example + destructor destroys a weak_ptr + \fI(public member function of std::weak_ptr)\fP diff --git a/man/std::shared_timed_mutex.3 b/man/std::shared_timed_mutex.3 new file mode 100644 index 000000000..aa4e09e91 --- /dev/null +++ b/man/std::shared_timed_mutex.3 @@ -0,0 +1,110 @@ +.TH std::shared_timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex \- std::shared_timed_mutex + +.SH Synopsis + Defined in header + class shared_timed_mutex; \fI(since C++14)\fP + + The shared_timed_mutex class is a synchronization primitive that can be used to + protect shared data from being simultaneously accessed by multiple threads. In + contrast to other mutex types which facilitate exclusive access, a + shared_timed_mutex has two levels of access: + + * exclusive - only one thread can own the mutex. + * shared - several threads can share ownership of the same mutex. + + Shared mutexes are usually used in situations when multiple readers can access the + same resource at the same time without causing data races, but only one writer can + do so. + + In a manner similar to timed_mutex, shared_timed_mutex provides the ability to + attempt to claim ownership of a shared_timed_mutex with a timeout via the + try_lock_for(), try_lock_until(), try_lock_shared_for(), try_lock_shared_until() + member functions. + + The shared_timed_mutex class satisfies all requirements of SharedTimedMutex and + StandardLayoutType. + +.SH Member functions + + constructor constructs the mutex + \fI(public member function)\fP + destructor destroys the mutex + \fI(public member function)\fP + operator= not copy-assignable + [deleted] \fI(public member function)\fP + Exclusive locking + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_for unavailable for the specified timeout duration + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_until unavailable until specified time point has been reached + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP +.SH Shared locking + locks the mutex for shared ownership, blocks if the mutex is + lock_shared not available + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the + try_lock_shared mutex is not available + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the + try_lock_shared_for mutex has been + unavailable for the specified timeout duration + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the + try_lock_shared_until mutex has been + unavailable until specified time point has been reached + \fI(public member function)\fP + unlock_shared unlocks the mutex (shared ownership) + \fI(public member function)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_shared_timed_mutex 201402L \fI(C++14)\fP std::shared_timed_mutex + +.SH Example + + This section is incomplete + Reason: build a motivating example + + A copy assignment operator for a class that holds resources that can handle multiple + readers, but only one writer. + + +// Run this code + + #include + #include + + class R + { + mutable std::shared_timed_mutex mut; + /* data */ + public: + R& operator=(const R& other) + { + // requires exclusive ownership to write to *this + std::unique_lock lhs(mut, std::defer_lock); + // requires shared ownership to read from other + std::shared_lock rhs(other.mut, std::defer_lock); + std::lock(lhs, rhs); + /* assign data */ + return *this; + } + }; + + int main() + { + R r; + } + +.SH Category: + * Todo with reason diff --git a/man/std::shared_timed_mutex::lock.3 b/man/std::shared_timed_mutex::lock.3 new file mode 100644 index 000000000..758358c67 --- /dev/null +++ b/man/std::shared_timed_mutex::lock.3 @@ -0,0 +1,94 @@ +.TH std::shared_timed_mutex::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::lock \- std::shared_timed_mutex::lock + +.SH Synopsis + void lock(); \fI(since C++14)\fP + + Locks the mutex. If another thread has already locked the mutex, a call to lock will + block execution until the lock is acquired. + + If lock is called by a thread that already owns the mutex in any mode (shared or + exclusive), the behavior is undefined. + + Prior unlock() operations on the same mutex synchronize-with (as defined in + std::memory_order) this operation. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error when errors occur, including errors from the underlying + operating system that would prevent lock from meeting its specifications. The mutex + is not locked in the case of any exception being thrown. + +.SH Notes + + lock() is usually not called directly: std::unique_lock, std::scoped_lock, and + std::lock_guard are used to manage exclusive locking. + + Shared mutexes do not support direct transition from shared to unique ownership + mode: the shared lock has to be relinquished with unlock_shared() before exclusive + ownership may be obtained with lock(). boost::upgrade_mutex may be used for this + purpose. + +.SH Example + + This example shows how lock and unlock can be used to protect shared data. + + +// Run this code + + #include + #include + #include + #include + + int g_num = 0; // protected by g_num_mutex + std::mutex g_num_mutex; + + void slow_increment(int id) + { + for (int i = 0; i < 3; ++i) + { + g_num_mutex.lock(); + ++g_num; + // note, that the mutex also syncronizes the output + std::cout << "id: " << id << ", g_num: " << g_num << '\\n'; + g_num_mutex.unlock(); + + std::this_thread::sleep_for(std::chrono::milliseconds(234)); + } + } + + int main() + { + std::thread t1{slow_increment, 0}; + std::thread t2{slow_increment, 1}; + t1.join(); + t2.join(); + } + +.SH Possible output: + + id: 0, g_num: 1 + id: 1, g_num: 2 + id: 1, g_num: 3 + id: 0, g_num: 4 + id: 0, g_num: 5 + id: 1, g_num: 6 + +.SH See also + + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP + C documentation for + mtx_lock diff --git a/man/std::shared_timed_mutex::lock_shared.3 b/man/std::shared_timed_mutex::lock_shared.3 new file mode 100644 index 000000000..80097e0fb --- /dev/null +++ b/man/std::shared_timed_mutex::lock_shared.3 @@ -0,0 +1,58 @@ +.TH std::shared_timed_mutex::lock_shared 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::lock_shared \- std::shared_timed_mutex::lock_shared + +.SH Synopsis + void lock_shared(); \fI(since C++14)\fP + + Acquires shared ownership of the mutex. If another thread is holding the mutex in + exclusive ownership, a call to lock_shared will block execution until shared + ownership can be acquired. + + If lock_shared is called by a thread that already owns the mutex in any mode + (exclusive or shared), the behavior is undefined. + + If more than the implementation-defined maximum number of shared owners already + locked the mutex in shared mode, lock_shared blocks execution until the number of + shared owners is reduced. The maximum number of owners is guaranteed to be at least + 10000. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::system_error when errors occur, including errors from the underlying + operating system that would prevent lock from meeting its specifications. The mutex + is not locked in the case of any exception being thrown. + +.SH Notes + + lock_shared() is usually not called directly: std::shared_lock is used to manage + shared locking. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the mutex + try_lock_shared is not available + \fI(public member function)\fP + unlock_shared unlocks the mutex (shared ownership) + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::shared_timed_mutex.3 b/man/std::shared_timed_mutex::shared_timed_mutex.3 new file mode 100644 index 000000000..fe985fe5f --- /dev/null +++ b/man/std::shared_timed_mutex::shared_timed_mutex.3 @@ -0,0 +1,23 @@ +.TH std::shared_timed_mutex::shared_timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::shared_timed_mutex \- std::shared_timed_mutex::shared_timed_mutex + +.SH Synopsis + shared_timed_mutex(); \fB(1)\fP \fI(since C++14)\fP + shared_timed_mutex( const shared_timed_mutex& ) = delete; \fB(2)\fP \fI(since C++14)\fP + + 1) Constructs the mutex. The mutex is in unlocked state after the call. + 2) Copy constructor is deleted. + +.SH Parameters + + \fI(none)\fP + +.SH Exceptions + + std::system_error if the construction is unsuccessful. + +.SH See also + + C documentation for + mtx_init diff --git a/man/std::shared_timed_mutex::try_lock.3 b/man/std::shared_timed_mutex::try_lock.3 new file mode 100644 index 000000000..fc343c38a --- /dev/null +++ b/man/std::shared_timed_mutex::try_lock.3 @@ -0,0 +1,56 @@ +.TH std::shared_timed_mutex::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::try_lock \- std::shared_timed_mutex::try_lock + +.SH Synopsis + bool try_lock(); \fI(since C++14)\fP + + Tries to lock the mutex. Returns immediately. On successful lock acquisition returns + true, otherwise returns false. + + This function is allowed to fail spuriously and return false even if the mutex is + not currently locked by any other thread. + + If try_lock is called by a thread that already owns the mutex in any mode (shared or + exclusive), the behavior is undefined. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation if it returns true. Note that prior lock() does + not synchronize with this operation if it returns false. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the lock was acquired successfully, otherwise false. + +.SH Exceptions + + Throws nothing. + +.SH Example + + + + This section is incomplete + Reason: no example + +.SH See also + + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_for unavailable for the specified timeout duration + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_until unavailable until specified time point has been reached + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP + C documentation for + mtx_trylock + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::try_lock_for.3 b/man/std::shared_timed_mutex::try_lock_for.3 new file mode 100644 index 000000000..6aee928a0 --- /dev/null +++ b/man/std::shared_timed_mutex::try_lock_for.3 @@ -0,0 +1,113 @@ +.TH std::shared_timed_mutex::try_lock_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::try_lock_for \- std::shared_timed_mutex::try_lock_for + +.SH Synopsis + template< class Rep, class Period > + bool try_lock_for( const std::chrono::duration& \fI(since C++14)\fP + timeout_duration ); + + Tries to lock the mutex. Blocks until the specified duration timeout_duration has + elapsed (timeout) or the lock is acquired (owns the mutex), whichever comes first. + On successful lock acquisition returns true, otherwise returns false. + + If timeout_duration is less or equal timeout_duration.zero(), the function behaves + like try_lock(). + + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. + + The standard recommends that a std::steady_clock is used to measure the duration. If + an implementation uses a std::system_clock instead, the wait time may also be + sensitive to clock adjustments. + + As with try_lock(), this function is allowed to fail spuriously and return false + even if the mutex was not locked by any other thread at some point during + timeout_duration. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation if it returns true. + + If try_lock_for is called by a thread that already owns the mutex in any mode + (shared or exclusive), the behavior is undefined. + +.SH Parameters + + timeout_duration - minimum duration to block for + +.SH Return value + + true if the lock was acquired successfully, otherwise false. + +.SH Exceptions + + Any exception thrown by timeout_duration (durations provided by the standard library + never throw). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + std::mutex cout_mutex; // control access to std::cout + std::timed_mutex mutex; + + void job(int id) + { + std::ostringstream stream; + + for (int i = 0; i < 3; ++i) + { + if (mutex.try_lock_for(100ms)) + { + stream << "success "; + std::this_thread::sleep_for(100ms); + mutex.unlock(); + } + else + stream << "failed "; + + std::this_thread::sleep_for(100ms); + } + + std::lock_guard lock{cout_mutex}; + std::cout << '[' << id << "] " << stream.str() << '\\n'; + } + + int main() + { + std::vector threads; + for (int i{0}; i < 4; ++i) + threads.emplace_back(job, i); + + for (auto& th : threads) + th.join(); + } + +.SH Possible output: + + [0] failed failed failed + [3] failed failed success + [2] failed success failed + [1] success failed success + +.SH See also + + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_until unavailable until specified time point has been reached + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP diff --git a/man/std::shared_timed_mutex::try_lock_shared.3 b/man/std::shared_timed_mutex::try_lock_shared.3 new file mode 100644 index 000000000..901f6c7b3 --- /dev/null +++ b/man/std::shared_timed_mutex::try_lock_shared.3 @@ -0,0 +1,46 @@ +.TH std::shared_timed_mutex::try_lock_shared 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::try_lock_shared \- std::shared_timed_mutex::try_lock_shared + +.SH Synopsis + bool try_lock_shared(); \fI(since C++14)\fP + + Tries to lock the mutex in shared mode. Returns immediately. On successful lock + acquisition returns true, otherwise returns false. + + This function is allowed to fail spuriously and return false even if the mutex is + not currenly exclusively locked by any other thread. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation if it returns true. + + The behavior is undefined if the calling thread already owns the mutex in any mode. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the lock was acquired successfully, otherwise false. + +.SH Exceptions + + Throws nothing. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + unlock_shared unlocks the mutex (shared ownership) + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::try_lock_shared_for.3 b/man/std::shared_timed_mutex::try_lock_shared_for.3 new file mode 100644 index 000000000..7a3386ea7 --- /dev/null +++ b/man/std::shared_timed_mutex::try_lock_shared_for.3 @@ -0,0 +1,66 @@ +.TH std::shared_timed_mutex::try_lock_shared_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::try_lock_shared_for \- std::shared_timed_mutex::try_lock_shared_for + +.SH Synopsis + template< class Rep, class Period > + bool try_lock_shared_for( const std::chrono::duration& \fI(since C++14)\fP + timeout_duration ); + + Tries to lock the mutex in shared mode. Blocks until specified timeout_duration has + elapsed or the shared lock is acquired, whichever comes first. On successful lock + acquisition returns true, otherwise returns false. + + If timeout_duration is less or equal timeout_duration.zero(), the function behaves + like try_lock_shared(). + + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. + + The standard recommends that a steady clock is used to measure the duration. If an + implementation uses a system clock instead, the wait time may also be sensitive to + clock adjustments. + + As with try_lock_shared(), this function is allowed to fail spuriously and return + false even if the mutex was not locked by any other thread at some point during + timeout_duration. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation if it returns true. + + If try_lock_shared_for is called by a thread that already owns the mutex in any mode + (shared or exclusive), the behavior is undefined. + +.SH Parameters + + timeout_duration - maximum duration to block for + +.SH Return value + + true if the lock was acquired successfully, otherwise false. + +.SH Exceptions + + Any exception thrown by clock, time_point, or duration during the execution (clocks, + time points, and durations provided by the standard library never throw). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + tries to lock the mutex for shared ownership, returns if the + try_lock_shared mutex is not available + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the + try_lock_shared_until mutex has been + unavailable until specified time point has been reached + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_for unavailable for the specified timeout duration + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::try_lock_shared_until.3 b/man/std::shared_timed_mutex::try_lock_shared_until.3 new file mode 100644 index 000000000..3d3999013 --- /dev/null +++ b/man/std::shared_timed_mutex::try_lock_shared_until.3 @@ -0,0 +1,69 @@ +.TH std::shared_timed_mutex::try_lock_shared_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::try_lock_shared_until \- std::shared_timed_mutex::try_lock_shared_until + +.SH Synopsis + template< class Clock, class Duration > + bool try_lock_shared_until( const \fI(since C++14)\fP + std::chrono::time_point& timeout_time ); + + Tries to lock the mutex in shared mode. Blocks until specified timeout_time has been + reached or the lock is acquired, whichever comes first. On successful lock + acquisition returns true, otherwise returns false. + + If timeout_time has already passed, this function behaves like try_lock_shared(). + + Clock must meet the Clock requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP + + The standard recommends that the clock tied to timeout_time be used, in which case + adjustments of the clock may be taken into account. Thus, the duration of the block + might be more or less than timeout_time - Clock::now() at the time of the call, + depending on the direction of the adjustment and whether it is honored by the + implementation. The function also may block until after timeout_time has been + reached due to process scheduling or resource contention delays. + + As with try_lock_shared(), this function is allowed to fail spuriously and return + false even if the mutex was not locked by any other thread at some point before + timeout_time. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation if it returns true. + + If try_lock_shared_until is called by a thread that already owns the mutex in any + mode (shared or exclusive), the behavior is undefined. + +.SH Parameters + + timeout_time - maximum time point to block until + +.SH Return value + + true if the shared lock ownership was acquired successfully, otherwise false. + +.SH Exceptions + + Any exception thrown by clock, time_point, or duration during the execution (clocks, + time points, and durations provided by the standard library never throw). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + tries to lock the mutex, returns if the mutex has been + try_lock_until unavailable until specified time point has been reached + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the + try_lock_shared mutex is not available + \fI(public member function)\fP + tries to lock the mutex for shared ownership, returns if the + try_lock_shared_for mutex has been + unavailable for the specified timeout duration + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::try_lock_until.3 b/man/std::shared_timed_mutex::try_lock_until.3 new file mode 100644 index 000000000..19b7c8b3d --- /dev/null +++ b/man/std::shared_timed_mutex::try_lock_until.3 @@ -0,0 +1,70 @@ +.TH std::shared_timed_mutex::try_lock_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::try_lock_until \- std::shared_timed_mutex::try_lock_until + +.SH Synopsis + template< class Clock, class Duration > + bool try_lock_until( const std::chrono::time_point& \fI(since C++14)\fP + timeout_time ); + + Tries to lock the mutex. Blocks until specified timeout_time has been reached + (timeout) or the lock is acquired (owns the mutex), whichever comes first. On + successful lock acquisition returns true, otherwise returns false. + + If timeout_time has already passed, this function behaves like try_lock(). + + Clock must meet the Clock requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP + + The standard recommends that the clock tied to timeout_time be used, in which case + adjustments of the clock may be taken into account. Thus, the duration of the block + might be more or less than timeout_time - Clock::now() at the time of the call, + depending on the direction of the adjustment and whether it is honored by the + implementation. The function also may block until after timeout_time has been + reached due to process scheduling or resource contention delays. + + As with try_lock(), this function is allowed to fail spuriously and return false + even if the mutex was not locked by any other thread at some point before + timeout_time. + + Prior unlock() operation on the same mutex synchronizes-with (as defined in + std::memory_order) this operation if it returns true. + + If try_lock_until is called by a thread that already owns the mutex in any mode + (shared or exclusive), the behavior is undefined. + +.SH Parameters + + timeout_time - maximum time point to block until + +.SH Return value + + true if the lock was acquired successfully, otherwise false. + +.SH Exceptions + + Any exception thrown by timeout_time (clocks, time points, and durations provided by + the standard library never throw). + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_for unavailable for the specified timeout duration + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP + C documentation for + mtx_timedlock + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::unlock.3 b/man/std::shared_timed_mutex::unlock.3 new file mode 100644 index 000000000..4349c9e19 --- /dev/null +++ b/man/std::shared_timed_mutex::unlock.3 @@ -0,0 +1,54 @@ +.TH std::shared_timed_mutex::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::unlock \- std::shared_timed_mutex::unlock + +.SH Synopsis + void unlock(); \fI(since C++14)\fP + + Unlocks the mutex. + + The mutex must be locked by the current thread of execution, otherwise, the behavior + is undefined. + + This operation synchronizes-with (as defined in std::memory_order) any subsequent + lock operation that obtains ownership of the same mutex. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. + +.SH Notes + + unlock() is usually not called directly: std::unique_lock and std::lock_guard are + used to manage exclusive locking. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + lock locks the mutex, blocks if the mutex is not available + \fI(public member function)\fP + try_lock tries to lock the mutex, returns if the mutex is not available + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_for unavailable for the specified timeout duration + \fI(public member function)\fP + tries to lock the mutex, returns if the mutex has been + try_lock_until unavailable until specified time point has been reached + \fI(public member function)\fP + C documentation for + mtx_unlock + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::unlock_shared.3 b/man/std::shared_timed_mutex::unlock_shared.3 new file mode 100644 index 000000000..739293412 --- /dev/null +++ b/man/std::shared_timed_mutex::unlock_shared.3 @@ -0,0 +1,47 @@ +.TH std::shared_timed_mutex::unlock_shared 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::unlock_shared \- std::shared_timed_mutex::unlock_shared + +.SH Synopsis + void unlock_shared(); \fI(since C++14)\fP + + Releases the mutex from shared ownership by the calling thread. + + The mutex must be locked by the current thread of execution in shared mode, + otherwise, the behavior is undefined. + + This operation synchronizes-with (as defined in std::memory_order) any subsequent + lock() operation that obtains ownership of the same mutex. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. + +.SH Notes + + unlock_shared() is usually not called directly: std::shared_lock is used to manage + shared locking. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + locks the mutex for shared ownership, blocks if the mutex is not + lock_shared available + \fI(public member function)\fP + unlock unlocks the mutex + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::shared_timed_mutex::~shared_timed_mutex.3 b/man/std::shared_timed_mutex::~shared_timed_mutex.3 new file mode 100644 index 000000000..77a53ead7 --- /dev/null +++ b/man/std::shared_timed_mutex::~shared_timed_mutex.3 @@ -0,0 +1,16 @@ +.TH std::shared_timed_mutex::~shared_timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shared_timed_mutex::~shared_timed_mutex \- std::shared_timed_mutex::~shared_timed_mutex + +.SH Synopsis + ~shared_timed_mutex(); + + Destroys the mutex. + + The behavior is undefined if the mutex is owned by any thread or if any thread + terminates while holding any ownership of the mutex. + +.SH See also + + C documentation for + mtx_destroy diff --git a/man/std::shift_left,std::shift_right.3 b/man/std::shift_left,std::shift_right.3 new file mode 100644 index 000000000..a331c2d6b --- /dev/null +++ b/man/std::shift_left,std::shift_right.3 @@ -0,0 +1,199 @@ +.TH std::shift_left,std::shift_right 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shift_left,std::shift_right \- std::shift_left,std::shift_right + +.SH Synopsis + Defined in header + template< class ForwardIt > + + constexpr ForwardIt shift_left( ForwardIt first, ForwardIt last, + typename \fB(1)\fP \fI(since C++20)\fP + std::iterator_traits:: + + difference_type n ); + template< class ExecutionPolicy, class ForwardIt > + + ForwardIt shift_left( ExecutionPolicy&& policy, + ForwardIt first, ForwardIt last, \fB(2)\fP \fI(since C++20)\fP + typename std::iterator_traits:: + + difference_type n ); + template< class ForwardIt > + + constexpr ForwardIt shift_right( ForwardIt first, ForwardIt last, + typename \fB(3)\fP \fI(since C++20)\fP + std::iterator_traits:: + + difference_type n ); + template< class ExecutionPolicy, class ForwardIt > + + ForwardIt shift_right( ExecutionPolicy&& policy, + ForwardIt first, ForwardIt last, \fB(4)\fP \fI(since C++20)\fP + typename std::iterator_traits:: + + difference_type n ); + + Shifts the elements in the range [first, last) by n positions. + + 1) Shifts the elements towards the beginning of the range. + * If n == 0 || n >= last - first, there are no effects. + * Otherwise, for every integer i in [0, last - first - n), moves the element + originally at position first + n + i to position first + i. + The moves are performed in increasing order of i starting from 0. + 3) Shifts the elements towards the end of the range. + * If n == 0 || n >= last - first, there are no effects. + * Otherwise, for every integer i in [0, last - first - n), moves the element + originally at position first + i to position first + n + i. + If ForwardIt meets the LegacyBidirectionalIterator requirements, then the moves are + performed in decreasing order of i starting from last - first - n - 1. + 2,4) Same as \fB(1)\fP and \fB(3)\fP, respectively, but executed according to policy and the + moves may be performed in any order. + These overloads participate in overload resolution only if + std::is_execution_policy_v> is true. + + Elements that are in the original range but not the new range are left in a valid + but unspecified state. + + If any of the following conditions is satisfied, the behavior is undefined: + + * n >= 0 is not true. + * The type of *first is not MoveAssignable. + * For shift_right, ForwardIt is neither LegacyBidirectionalIterator nor + ValueSwappable. + +.SH Parameters + + first - the beginning of the original range + last - the end of the original range + n - the number of positions to shift + policy - the execution policy to use. See execution policy for details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + +.SH Return value + + 1,2) The end of the resulting range. + * If n is less than std::distance(first, last), returns an iterator equal to + std::next(first, (std::distance(first, last) - n)). + * Otherwise, returns first. + 3,4) The beginning of the resulting range. + * If n is less than std::distance(first, last), returns an iterator equal to + std::next(first, n). + * Otherwise, returns last. + +.SH Complexity + + 1,2) At most std::distance(first, last) - n assignments. + 3,4) At most std::distance(first, last) - n assignment or swaps. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_shift 201806L (C++20) std::shift_left and std::shift_right + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct S + { + int value{0}; + bool specified_state{true}; + + S(int v = 0) : value{v} {} + S(S const& rhs) = default; + S(S&& rhs) { *this = std::move(rhs); } + S& operator=(S const& rhs) = default; + S& operator=(S&& rhs) + { + if (this != &rhs) + { + value = rhs.value; + specified_state = rhs.specified_state; + rhs.specified_state = false; + } + return *this; + } + }; + + template + std::ostream& operator<<(std::ostream& os, std::vector const& v) + { + for (const auto& s : v) + { + if constexpr (std::is_same_v) + s.specified_state ? os << s.value << ' ' : os << ". "; + else if constexpr (std::is_same_v) + os << (s.empty() ? "." : s) << ' '; + else + os << s << ' '; + } + return os; + } + + int main() + { + std::cout << std::left; + + std::vector a{1, 2, 3, 4, 5, 6, 7}; + std::vector b{1, 2, 3, 4, 5, 6, 7}; + std::vector c{"α", "β", "γ", "δ", "ε", "ζ", "η"}; + + std::cout << "vector \\tvector \\tvector\\n"; + std::cout << a << " " << b << " " << c << '\\n'; + + std::shift_left(begin(a), end(a), 3); + std::shift_left(begin(b), end(b), 3); + std::shift_left(begin(c), end(c), 3); + std::cout << a << " " << b << " " << c << '\\n'; + + std::shift_right(begin(a), end(a), 2); + std::shift_right(begin(b), end(b), 2); + std::shift_right(begin(c), end(c), 2); + std::cout << a << " " << b << " " << c << '\\n'; + + std::shift_left(begin(a), end(a), 8); // has no effect: n >= last - first + std::shift_left(begin(b), end(b), 8); // ditto + std::shift_left(begin(c), end(c), 8); // ditto + std::cout << a << " " << b << " " << c << '\\n'; + + // std::shift_left(begin(a), end(a), -3); // UB, e.g. segfault + } + +.SH Possible output: + + vector vector vector + 1 2 3 4 5 6 7 1 2 3 4 5 6 7 α β γ δ ε ζ η + 4 5 6 7 . . . 4 5 6 7 5 6 7 δ ε ζ η . . . + . . 4 5 6 7 . 4 5 4 5 6 7 5 . . δ ε ζ η . + . . 4 5 6 7 . 4 5 4 5 6 7 5 . . δ ε ζ η . + +.SH See also + + move moves a range of elements to a new location + \fI(C++11)\fP \fI(function template)\fP + move_backward moves a range of elements to a new location in backwards order + \fI(C++11)\fP \fI(function template)\fP + rotate rotates the order of elements in a range + \fI(function template)\fP + ranges::shift_left shifts elements in a range + ranges::shift_right (niebloid) + (C++23) diff --git a/man/std::showbase,std::noshowbase.3 b/man/std::showbase,std::noshowbase.3 index 446fc05d2..5dcb0ac48 100644 --- a/man/std::showbase,std::noshowbase.3 +++ b/man/std::showbase,std::noshowbase.3 @@ -1,43 +1,56 @@ -.TH std::showbase,std::noshowbase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::showbase,std::noshowbase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::showbase,std::noshowbase \- std::showbase,std::noshowbase + .SH Synopsis Defined in header std::ios_base& showbase( std::ios_base& str ); \fB(1)\fP std::ios_base& noshowbase( std::ios_base& str ); \fB(2)\fP - 1) enables the showbase flag in the stream str as if by calling - str.setf(std::ios_base::showbase) - - 2) disables the showbase flag in the stream str as if by calling - str.unsetf(std::ios_base::showbase) + 1) Enables the showbase flag in the stream str as if by calling + str.setf(std::ios_base::showbase). + 2) Disables the showbase flag in the stream str as if by calling + str.unsetf(std::ios_base::showbase). This is an I/O manipulator, it may be called with an expression such as out << std::showbase for any out of type std::basic_ostream or with an expression such as in >> std::showbase for any in of type std::basic_istream. + The showbase flag affects the behavior of integer output (see std::num_put::put), + monetary input (see std::money_get::get) and monetary output (see + std::money_put::put). + .SH Parameters str - reference to I/O stream .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). + +.SH Notes + + As specifed in std::num_put::put, the showbase flag in integer output acts like the + # format specifier in std::printf, which means the numeric base prefix is not added + when outputting the value zero. .SH Example - + // Run this code - #include - #include - #include #include + #include + #include + #include + int main() { // showbase affects the output of octals and hexadecimals std::cout << std::hex << "showbase: " << std::showbase << 42 << '\\n' << "noshowbase: " << std::noshowbase << 42 << '\\n'; - + // and both input and output of monetary values std::locale::global(std::locale("en_US.utf8")); long double val = 0; @@ -59,6 +72,6 @@ .SH See also resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::showpoint,std::noshowpoint.3 b/man/std::showpoint,std::noshowpoint.3 index bb09e363f..963b921ce 100644 --- a/man/std::showpoint,std::noshowpoint.3 +++ b/man/std::showpoint,std::noshowpoint.3 @@ -1,4 +1,7 @@ -.TH std::showpoint,std::noshowpoint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::showpoint,std::noshowpoint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::showpoint,std::noshowpoint \- std::showpoint,std::noshowpoint + .SH Synopsis Defined in header std::ios_base& showpoint( std::ios_base& str ); \fB(1)\fP @@ -7,30 +10,34 @@ Enables or disables the unconditional inclusion of the decimal point character in floating-point output. Has no effect on input. - 1) enables the showpoint flag in the stream str as if by calling - str.setf(std::ios_base::showpoint) - - 2) disables the showpoint flag in the stream str as if by calling - str.unsetf(std::ios_base::showpoint) + 1) Enables the showpoint flag in the stream str as if by calling + str.setf(std::ios_base::showpoint). + 2) Disables the showpoint flag in the stream str as if by calling + str.unsetf(std::ios_base::showpoint). This is an I/O manipulator, it may be called with an expression such as out << std::showpoint for any out of type std::basic_ostream or with an expression such as in >> std::showpoint for any in of type std::basic_istream. + The character to use as decimal point character is determined by the numpunct facet + of the locale imbued in the stream at the time of output, as described in + std::num_put::put. + .SH Parameters str - reference to I/O stream .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code #include + int main() { std::cout << "1.0 with showpoint: " << std::showpoint << 1.0 << '\\n' @@ -45,6 +52,6 @@ .SH See also resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::showpos,std::noshowpos.3 b/man/std::showpos,std::noshowpos.3 index 103c865d5..d6f1372c4 100644 --- a/man/std::showpos,std::noshowpos.3 +++ b/man/std::showpos,std::noshowpos.3 @@ -1,4 +1,7 @@ -.TH std::showpos,std::noshowpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::showpos,std::noshowpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::showpos,std::noshowpos \- std::showpos,std::noshowpos + .SH Synopsis Defined in header std::ios_base& showpos( std::ios_base& str ); \fB(1)\fP @@ -7,11 +10,10 @@ Enables or disables the display of the plus sign '+' in non-negative integer output. Has no effect on input. - 1) enables the showpos flag in the stream str as if by calling - str.setf(std::ios_base::showpos) - - 2) disables the showpos flag in the stream str as if by calling - str.unsetf(std::ios_base::showpos) + 1) Enables the showpos flag in the stream str as if by calling + str.setf(std::ios_base::showpos). + 2) Disables the showpos flag in the stream str as if by calling + str.unsetf(std::ios_base::showpos). This is an I/O manipulator, it may be called with an expression such as out << std::showpos for any out of type std::basic_ostream or with an expression such as in @@ -23,18 +25,20 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code #include + int main() { - std::cout << "showpos: " << std::showpos << 42 << ' ' << 3.14 << ' ' << 0 << '\\n' - << "noshowpos: " << std::noshowpos << 42 << ' ' << 3.14 << ' ' << 0 << '\\n'; + std::cout + << "showpos: " << std::showpos << 42 << ' ' << 3.14 << ' ' << 0 << '\\n' + << "noshowpos: " << std::noshowpos << 42 << ' ' << 3.14 << ' ' << 0 << '\\n'; } .SH Output: @@ -45,6 +49,6 @@ .SH See also resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::shuffle_order_engine.3 b/man/std::shuffle_order_engine.3 index 9c5172fd3..956bb9755 100644 --- a/man/std::shuffle_order_engine.3 +++ b/man/std::shuffle_order_engine.3 @@ -1,4 +1,7 @@ -.TH std::shuffle_order_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine \- std::shuffle_order_engine + .SH Synopsis Defined in header template< @@ -17,52 +20,63 @@ parameter set: Defined in header - Type Definition - knuth_b std::shuffle_order_engine + Type Definition + knuth_b \fI(C++11)\fP std::shuffle_order_engine .SH Template parameters Engine - the type of the wrapped engine - K - the size of the internal table. Must be greater than 0 + K - the size of the internal table. Must be greater than 0. .SH Type requirements - Engine must meet the requirements of RandomNumberEngine. .SH Member types - Member type Definition - result_type typename Engine::result_type + Member type Definition + result_type \fI(C++11)\fP Engine::result_type .SH Member functions - constructor constructs the engine adaptor - \fI(public member function)\fP - seed sets the state of the underlying engine - \fI(public member function)\fP - base returns the underlying engine - \fI(public member function)\fP + constructor constructs the engine adaptor + \fI(C++11)\fP \fI(public member function)\fP + seed sets the state of the underlying engine + \fI(C++11)\fP \fI(public member function)\fP + base returns the underlying engine + \fI(C++11)\fP \fI(public member function)\fP .SH Generation - advances the state of the underlying engine and returns the generated - operator() value - \fI(public member function)\fP - discard advances the adaptor's state by a specified amount - \fI(public member function)\fP + operator() advances the state of the underlying engine and returns the + \fI(C++11)\fP generated value + \fI(public member function)\fP + discard advances the adaptor's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - min gets the smallest possible value in the output range of the underlying - \fB[static]\fP engine. - \fI(public static member function)\fP - max gets the largest possible value in the output range of the underlying - \fB[static]\fP engine. - \fI(public static member function)\fP + min gets the smallest possible value in the output range of the + \fB[static]\fP \fI(C++11)\fP underlying engine. + \fI(public static member function)\fP + max gets the largest possible value in the output range of the + \fB[static]\fP \fI(C++11)\fP underlying engine. + \fI(public static member function)\fP .SH Non-member functions - operator== compares the internal states of the adaptors and underlying engines - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number engine adaptor - operator>> \fI(function)\fP + operator== compares the internal states of the adaptors and + operator!= underlying engines + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> engine adaptor + \fI(C++11)\fP \fI(function)\fP .SH Member objects constexpr size_t table_size the size of the internal table, K - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(C++11)\fP \fI(public static member constant)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::shuffle_order_engine::base.3 b/man/std::shuffle_order_engine::base.3 index 49543afbc..b3a7f0582 100644 --- a/man/std::shuffle_order_engine::base.3 +++ b/man/std::shuffle_order_engine::base.3 @@ -1,6 +1,9 @@ -.TH std::shuffle_order_engine::base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine::base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::base \- std::shuffle_order_engine::base + .SH Synopsis - const Engine& base() const; \fI(since C++11)\fP + const Engine& base() const noexcept; \fI(since C++11)\fP Returns the underlying engine. @@ -11,9 +14,3 @@ .SH Return value The underlying engine. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::shuffle_order_engine::discard.3 b/man/std::shuffle_order_engine::discard.3 index f8ac31638..d1a688143 100644 --- a/man/std::shuffle_order_engine::discard.3 +++ b/man/std::shuffle_order_engine::discard.3 @@ -1,4 +1,7 @@ -.TH std::shuffle_order_engine::discard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine::discard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::discard \- std::shuffle_order_engine::discard + .SH Synopsis void discard( unsigned long long z ); \fI(since C++11)\fP @@ -16,10 +19,10 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH See also - advances the state of the underlying engine and returns the generated - operator() value - \fI(public member function)\fP + operator() advances the state of the underlying engine and returns the generated + \fI(C++11)\fP value + \fI(public member function)\fP diff --git a/man/std::shuffle_order_engine::max.3 b/man/std::shuffle_order_engine::max.3 index 645dbe309..c2bd5173c 100644 --- a/man/std::shuffle_order_engine::max.3 +++ b/man/std::shuffle_order_engine::max.3 @@ -1,4 +1,7 @@ -.TH std::shuffle_order_engine::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::max \- std::shuffle_order_engine::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP @@ -15,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::shuffle_order_engine::min.3 b/man/std::shuffle_order_engine::min.3 index 6ef337f90..b975e566c 100644 --- a/man/std::shuffle_order_engine::min.3 +++ b/man/std::shuffle_order_engine::min.3 @@ -1,4 +1,7 @@ -.TH std::shuffle_order_engine::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::min \- std::shuffle_order_engine::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP @@ -15,9 +18,9 @@ .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::shuffle_order_engine::operator().3 b/man/std::shuffle_order_engine::operator().3 new file mode 100644 index 000000000..91a4329f3 --- /dev/null +++ b/man/std::shuffle_order_engine::operator().3 @@ -0,0 +1,26 @@ +.TH std::shuffle_order_engine::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::operator() \- std::shuffle_order_engine::operator() + +.SH Synopsis + result_type operator()(); \fI(since C++11)\fP + + Generates a random value. The state of the underlying engine is advanced one or more + times. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pseudo-random number in [min(), max()]. + +.SH Exceptions + + Throws nothing. + +.SH See also + + discard advances the adaptor's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::shuffle_order_engine::seed.3 b/man/std::shuffle_order_engine::seed.3 index ba7dabc39..b227d08e5 100644 --- a/man/std::shuffle_order_engine::seed.3 +++ b/man/std::shuffle_order_engine::seed.3 @@ -1,4 +1,7 @@ -.TH std::shuffle_order_engine::seed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine::seed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::seed \- std::shuffle_order_engine::seed + .SH Synopsis void seed(); \fB(1)\fP \fI(since C++11)\fP void seed( result_type value ); \fB(2)\fP \fI(since C++11)\fP @@ -12,7 +15,10 @@ 2) Seeds the underlying engine with the seed value s. Effectively calls e.seed(value), where e is the underlying engine. 3) Seeds the underlying engine with the seed sequence seq. Effectively calls - e.seed(seq), where e is the underlying engine. + e.seed(seq), where e is the underlying engine. This template only participate in + overload resolution if Sseq qualifies as a SeedSequence. In particular, this + template does not participate in overload resolution if Sseq is implicitly + convertible to result_type. .SH Parameters @@ -27,4 +33,4 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. diff --git a/man/std::shuffle_order_engine::shuffle_order_engine.3 b/man/std::shuffle_order_engine::shuffle_order_engine.3 index 2d2f80487..c13662bc1 100644 --- a/man/std::shuffle_order_engine::shuffle_order_engine.3 +++ b/man/std::shuffle_order_engine::shuffle_order_engine.3 @@ -1,20 +1,31 @@ -.TH std::shuffle_order_engine::shuffle_order_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::shuffle_order_engine::shuffle_order_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::shuffle_order_engine::shuffle_order_engine \- std::shuffle_order_engine::shuffle_order_engine + .SH Synopsis shuffle_order_engine(); \fB(1)\fP \fI(since C++11)\fP - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP + explicit shuffle_order_engine( result_type s ); \fB(2)\fP \fI(since C++11)\fP + template< class Sseq > \fB(3)\fP \fI(since C++11)\fP explicit shuffle_order_engine( Sseq& seq ); - explicit shuffle_order_engine( const Engine& e ); \fB(3)\fP \fI(since C++11)\fP - explicit shuffle_order_engine( Engine&& e ); \fB(4)\fP \fI(since C++11)\fP + explicit shuffle_order_engine( const Engine& e ); \fB(4)\fP \fI(since C++11)\fP + explicit shuffle_order_engine( Engine&& e ); \fB(5)\fP \fI(since C++11)\fP Constructs new pseudo-random engine adaptor. 1) Default constructor. The underlying engine is also default-constructed. - 2) Constructs the underlying engine with seed sequence seq. - 3) Constructs the underlying engine with a copy of e. - 4) Move-constructs the underlying engine with e. e holds unspecified, but valid + 2) Constructs the underlying engine with s. + 3) Constructs the underlying engine with seed sequence seq. This constructor only + participate in overload resolution if Sseq qualifies as a SeedSequence. In + particular, this constructor does not participate in overload resolution if Sseq is + implicitly convertible to result_type. + 4) Constructs the underlying engine with a copy of e. + 5) Move-constructs the underlying engine with e. e holds unspecified, but valid state afterwards. .SH Parameters + s - integer value to construct the underlying engine with seq - seed sequence to construct the underlying engine with e - pseudo-random number engine to initialize with + +.SH Example diff --git a/man/std::sig_atomic_t.3 b/man/std::sig_atomic_t.3 index 2d71912d7..a8c702999 100644 --- a/man/std::sig_atomic_t.3 +++ b/man/std::sig_atomic_t.3 @@ -1,4 +1,7 @@ -.TH std::sig_atomic_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sig_atomic_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sig_atomic_t \- std::sig_atomic_t + .SH Synopsis Defined in header typedef /* unspecified */ sig_atomic_t; @@ -15,9 +18,9 @@ .SH See also signal sets a signal handler for particular signal - \fI(function)\fP - C documentation for - sig_atomic_t + \fI(function)\fP atomic_signal_fence fence between a thread and a signal handler executed in the same \fI(C++11)\fP thread - \fI(function)\fP + \fI(function)\fP + C documentation for + sig_atomic_t diff --git a/man/std::signal.3 b/man/std::signal.3 index e74e4b844..4a5aaa987 100644 --- a/man/std::signal.3 +++ b/man/std::signal.3 @@ -1,10 +1,15 @@ -.TH std::signal 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::signal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::signal \- std::signal + .SH Synopsis Defined in header - void (*signal( int sig, void (*handler) (int))) (int); + /* signal-handler */* signal( int sig, /* signal-handler */* \fB(1)\fP + handler ); + extern "C" using /* signal-handler */ = void(int); \fB(2)\fP (exposition only*) - Sets the error handler for signal sig. The signal handler can be set so that default - handling will occur, signal is ignored, or an user-defined function is called. + Changes handling of the signal sig. Depending on handler, the signal can be ignored, + set to default, or handled by a user-defined function. When signal handler is set to a function and a signal occurs, it is implementation defined whether std::signal(sig, SIG_DFL) will be executed immediately before the @@ -15,6 +20,9 @@ the startup of the program. For the rest, the implementation must call std::signal(sig, SIG_DFL). + (Note: POSIX introduced sigaction to standardize these implementation-defined + behaviors) + .SH Parameters the signal to set the signal handler to. It can be an @@ -23,17 +31,16 @@ SIGABRT sig - SIGFPE SIGILL defines signal types - SIGINT (macro constant) + SIGINT (macro constant) SIGSEGV SIGTERM the signal handler. This must be one of the following: - * SIG_DFL macro. The signal handler is set to default signal handler. - handler - * SIG_IGN macro. The signal is ignored. - * pointer to a function. The signature of the function must be + * SIG_IGN macro. The signal is ignored. + handler - * A pointer to a function. The signature of the function must be equivalent to the following: - void fun(int sig); + extern "C" void fun(int sig); .SH Return value @@ -45,35 +52,107 @@ The following limitations are imposed on the user-defined function that is installed as a signal handler. + If the signal handler is called NOT as a result of std::abort or + std::raise (asynchronous signal), the behavior is undefined if + + * the signal handler calls any function within the standard library, + except + + * std::abort + * std::_Exit \fI(until C++17)\fP + * std::quick_exit + * std::signal with the first argument being the number of the signal + currently handled (async handler can re-register itself, but not + other signals). + * the signal handler refers to any object with static storage + duration that is not + std::atomic or + \fI(since C++11)\fPvolatile std::sig_atomic_t. + A plain lock-free atomic operation is an invocation of a function f + from + or + (since C++23), such that: + + * f is the function std::atomic_is_lock_free, + * f is the member function is_lock_free (e.g. + std::atomic::is_lock_free()), + * f is a non-static member function of std::atomic_flag, + * f is a non-member function, and the first parameter of f has type + cv std::atomic_flag*, + * f is a non-static member function invoked on an object obj, such + that obj.is_lock_free() yields true, or + * f is a non-member function, and for every pointer-to-atomic + argument arg passed to f, std::atomic_is_lock_free(arg) yields + true. + + The behavior is undefined if any signal handler performs any of the + following: + + * call to any library function, except for plain lock-free atomic + operations and the following signal-safe functions (note, in + particular, dynamic allocation is not signal-safe): \fI(since C++17)\fP + + * std::signal with the first argument being the number of the signal + currently handled (signal handler can re-register itself, but not + other signals). + * member functions of std::numeric_limits + * std::_Exit + * std::abort + * std::quick_exit + * The member functions of std::initializer_list and the + std::initializer_list overloads of std::begin and std::end + * std::forward, std::move, std::move_if_noexcept + * All functions from + * std::memcpy and std::memmove + * access to an object with thread storage duration + * a dynamic_cast expression + * a throw expression + * entry to a try block + * initialization of a static variable that performs dynamic + non-local initialization (including delayed until first ODR-use) + * waits for completion of initialization of any variable with static + storage duration due to another thread concurrently initializing + it + If the user defined function returns when handling SIGFPE, SIGILL, SIGSEGV or any other implementation-defined signal specifying a computational exception, the behavior is undefined. - If the signal handler is called as a result of std::abort or std::raise, the - behavior is undefined if the signal handler calls std::raise. - - If the signal handler is called NOT as a result of std::abort or std::raise, the - behavior is undefined if - - * the signal handler calls any function within the standard library, except - std::abort, std::_Exit, std::quick_exit, or std::signal with the first argument - not being the number of the signal currently handled. - * the signal handler refers to any object with static or thread-local\fI(since C++11)\fP - storage duration that is not std::atomic\fI(since C++11)\fP or volatile - std::sig_atomic_t. + If the signal handler is called as a result of std::abort or std::raise (synchronous + signal), the behavior is undefined if the signal handler calls std::raise. - On entry to the signal handler, the state of the floating-point environment and the - values of all objects is unspecified, except for + On entry to the signal handler, the state of the floating-point + environment and the values of all objects is unspecified, except for * objects of type volatile std::sig_atomic_t - * objects of std::atomic types \fI(since C++11)\fP - * side effects made visible through std::atomic_signal_fence \fI(since C++11)\fP - On return from a signal handler, the value of any object modified by the signal - handler that is not volatile std::sig_atomic_t or std::atomic is undefined. - - The behavior is undefined if std::signal is used in a multithreaded program. It is - not required to be thread-safe. + * objects of lock-free std::atomic types \fI(until C++14)\fP + * side effects made visible through \fI(since C++11)\fP + std::atomic_signal_fence + + On return from a signal handler, the value of any object modified by + the signal handler that is not volatile std::sig_atomic_t or lock-free + std::atomic is indeterminate. + A call to the function signal() synchronizes-with any resulting + invocation of the signal handler. + + If a signal handler is executed as a result of a call to std::raise + (synchronously), then the execution of the handler is sequenced-after + the invocation of std::raise and sequenced-before the return from it + and runs on the same thread as std::raise. Execution of the handlers + for other signals is unsequenced with respect to the rest of the + program and runs on an unspecified thread. + \fI(since C++14)\fP + Two accesses to the same object of type volatile std::sig_atomic_t do + not result in a data race if both occur in the same thread, even if + one or more occurs in a signal handler. For each signal handler + invocation, evaluations performed by the thread invoking a signal + handler can be divided into two groups A and B, such that no + evaluations in B happen-before evaluations in A, and the evaluations + of such volatile std::sig_atomic_t objects take values as though all + evaluations in A happened-before the execution of the signal handler + and the execution of the signal handler happened-before all + evaluations in B. .SH Notes @@ -81,50 +160,71 @@ library functions that may be called from any signal handler. Signal handlers are expected to have C linkage and, in general, only use the - features from the common subset of C and C++. It is implementation-defined if a - function with C++ linkage can be used as a signal handler. + features from the common subset of C and C++. However, common implementations allow + a function with C++ linkage to be used as a signal handler. .SH Example - + // Run this code #include #include - + namespace { - volatile sig_atomic_t gSignalStatus = 0; + volatile std::sig_atomic_t gSignalStatus; } - + void signal_handler(int signal) { - gSignalStatus = signal; + gSignalStatus = signal; } - + int main() { - // Install a signal handler - std::signal(SIGINT, signal_handler); - - std::cout << "SignalValue: " << gSignalStatus << '\\n'; - std::cout << "Sending signal " << SIGINT << '\\n'; - std::raise(SIGINT); - std::cout << "SignalValue: " << gSignalStatus << '\\n'; + // Install a signal handler + std::signal(SIGINT, signal_handler); + + std::cout << "SignalValue: " << gSignalStatus << '\\n'; + std::cout << "Sending signal: " << SIGINT << '\\n'; + std::raise(SIGINT); + std::cout << "SignalValue: " << gSignalStatus << '\\n'; } .SH Possible output: SignalValue: 0 - Sending signal 2 + Sending signal: 2 SignalValue: 2 +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 17.13.5 Signal handlers [support.signal] + * C++20 standard (ISO/IEC 14882:2020): + + * 17.13.5 Signal handlers [support.signal] + * C++17 standard (ISO/IEC 14882:2017): + + * 21.10.4 Signal handlers [support.signal] + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3756 C++17 it was unclear whether std::atomic_flag is it is + signal-safe + .SH See also raise runs the signal handler for particular signal - \fI(function)\fP - C documentation for - signal + \fI(function)\fP atomic_signal_fence fence between a thread and a signal handler executed in the same \fI(C++11)\fP thread - \fI(function)\fP + \fI(function)\fP + C documentation for + signal diff --git a/man/std::signbit.3 b/man/std::signbit.3 index 0d830a21a..3f2ad4240 100644 --- a/man/std::signbit.3 +++ b/man/std::signbit.3 @@ -1,23 +1,87 @@ -.TH std::signbit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::signbit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::signbit \- std::signbit + .SH Synopsis Defined in header - bool signbit( float arg ); \fI(since C++11)\fP - bool signbit( double arg ); \fI(since C++11)\fP - bool signbit( long double arg ); \fI(since C++11)\fP + bool signbit( float num ); + \fI(since C++11)\fP + bool signbit( double num ); (until C++23) + + bool signbit( long double num ); + constexpr bool signbit( /* floating-point-type */ \fB(1)\fP (since C++23) + num ); + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++11)\fP + bool signbit( Integer num ); (constexpr since C++23) - Determines if the given floating point number arg is negative. + 1) Determines if the given floating point number num is negative. + The library provides overloads for all cv-unqualified floating-point types as the + type of the parameter num. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. .SH Parameters - arg - floating point value + num - floating-point or integer value .SH Return value - true if arg is negative, false otherwise + true if num is negative, false otherwise. + +.SH Notes + + This function detects the sign bit of zeroes, infinities, and NaNs. Along with + std::copysign, std::signbit is one of the only two portable ways to examine the sign + of a NaN. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::signbit(num) has the same effect as std::signbit(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha + << "signbit(+0.0) = " << std::signbit(+0.0) << '\\n' + << "signbit(-0.0) = " << std::signbit(-0.0) << '\\n' + << "signbit(+nan) = " << std::signbit(+NAN) << '\\n' + << "signbit(-nan) = " << std::signbit(-NAN) << '\\n' + << "signbit(+inf) = " << std::signbit(+INFINITY) << '\\n' + << "signbit(-inf) = " << std::signbit(-INFINITY) << '\\n'; + } + +.SH Output: + + signbit(+0.0) = false + signbit(-0.0) = true + signbit(+nan) = false + signbit(-nan) = true + signbit(+inf) = false + signbit(-inf) = true .SH See also - abs(float) absolute value of a floating point value (|x|) - fabs \fI(function)\fP - copysign copies the sign of a floating point value - \fI(C++11)\fP \fI(function)\fP + abs(float) + fabs + fabsf absolute value of a floating point value (\\(\\small{|x|}\\)|x|) + fabsl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + copysign + copysignf + copysignl copies the sign of a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + signbit diff --git a/man/std::signed_integral.3 b/man/std::signed_integral.3 new file mode 100644 index 000000000..9de1ddc0e --- /dev/null +++ b/man/std::signed_integral.3 @@ -0,0 +1,66 @@ +.TH std::signed_integral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::signed_integral \- std::signed_integral + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + concept signed_integral = std::integral && std::is_signed_v; + + The concept signed_integral is satisfied if and only if T is an integral type and + std::is_signed_v is true. + +.SH Notes + + signed_integral may be satisfied by a type that is not a signed integer type, for + example, char (on a system where char is signed). + +.SH Example + + +// Run this code + + #include + #include + #include + + void test(std::signed_integral auto x, std::string_view text = "") + { + std::cout << text << " (" + (text == "") << x << ") is a signed integral\\n"; + } + + void test(std::unsigned_integral auto x, std::string_view text = "") + { + std::cout << text << " (" + (text == "") << x << ") is an unsigned integral\\n"; + } + + void test(auto x, std::string_view text = "") + { + std::cout << text << " (" + (text == "") << x << ") is non-integral\\n"; + } + + int main() + { + test(42); // signed + test(0xFULL, "0xFULL"); // unsigned + test('A'); // platform-dependent + test(true, "true"); // unsigned + test(4e-2, "4e-2"); // non-integral (hex-float) + test("∫∫"); // non-integral + } + +.SH Possible output: + + \fB(42)\fP is a signed integral + 0xFULL \fB(15)\fP is an unsigned integral + (A) is a signed integral + true \fB(1)\fP is an unsigned integral + 4e-2 (0.04) is non-integral + (∫∫) is non-integral + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::sin(std::complex).3 b/man/std::sin(std::complex).3 index 3839aef4e..12c48db76 100644 --- a/man/std::sin(std::complex).3 +++ b/man/std::sin(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::sin(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sin(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sin(std::complex) \- std::sin(std::complex) + .SH Synopsis Defined in header template< class T > @@ -12,11 +15,64 @@ .SH Return value - Complex sine of z. + If no errors occur, the complex sine of z is returned. + + Errors and special cases are handled as if the operation is implemented by -i + * std::sinh(i * z), where i is the imaginary unit. + +.SH Notes + + The sine is an entire function on the complex plane, and has no branch cuts. + + Mathematical definition of the sine is sin z = + + eiz + -e-iz + 2i + + . + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z(1.0, 0.0); // behaves like real sine along the real line + std::cout << "sin" << z << " = " << std::sin(z) + << " ( sin(1) = " << std::sin(1) << ")\\n"; + + std::complex z2(0.0, 1.0); // behaves like sinh along the imaginary line + std::cout << "sin" << z2 << " = " << std::sin(z2) + << " (sinh(1) = " << std::sinh(1) << ")\\n"; + } + +.SH Output: + + sin(1.000000,0.000000) = (0.841471,0.000000) ( sin\fB(1)\fP = 0.841471) + sin(0.000000,1.000000) = (0.000000,1.175201) (sinh\fB(1)\fP = 1.175201) .SH See also - cos(std::complex) computes cosine of a complex number (cos(z)) - \fI(function template)\fP - tan(std::complex) computes tangent of a complex number (tan(z)) - \fI(function template)\fP + cos(std::complex) computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z)) + \fI(function template)\fP + tan(std::complex) computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z)) + \fI(function template)\fP + asin(std::complex) computes arc sine of a complex number + \fI(C++11)\fP (\\({\\small\\arcsin{z}}\\)arcsin(z)) + \fI(function template)\fP + sin + sinf computes sine (\\({\\small\\sin{x}}\\)sin(x)) + sinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sin(std::valarray) applies the function std::sin to each element of valarray + \fI(function template)\fP + C documentation for + csin diff --git a/man/std::sin(std::valarray).3 b/man/std::sin(std::valarray).3 index ee590e343..ef48f0f2f 100644 --- a/man/std::sin(std::valarray).3 +++ b/man/std::sin(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::sin(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sin(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sin(std::valarray) \- std::sin(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (sin) is used to perform the computation. If such function is - not available, std::sin is used due to argument dependent lookup. + not available, std::sin is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,27 +43,28 @@ valarray sin(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = sin(i); - } + + return other; // proxy object may be returned } .SH Example - + // Run this code + #include #include + #include #include - #include - - const double pi = std::acos(-1); + int main() { std::valarray v1 = {0, 0.25, 0.5, 0.75, 1}; - std::valarray v2 = std::sin(v1 * pi); - - for(double n : v2) + std::valarray v2 = std::sin(v1 * std::numbers::pi); + + for (double n : v2) std::cout << std::fixed << n << ' '; std::cout << '\\n'; } @@ -66,3 +72,22 @@ .SH Output: 0.000000 0.707107 1.000000 0.707107 0.000000 + +.SH See also + + cos(std::valarray) applies the function std::cos to each element of valarray + \fI(function template)\fP + tan(std::valarray) applies the function std::tan to each element of valarray + \fI(function template)\fP + asin(std::valarray) applies the function std::asin to each element of valarray + \fI(function template)\fP + sin + sinf computes sine (\\({\\small\\sin{x}}\\)sin(x)) + sinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sin(std::complex) computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z)) + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::sin,std::sinf,std::sinl.3 b/man/std::sin,std::sinf,std::sinl.3 new file mode 100644 index 000000000..3ae89bb88 --- /dev/null +++ b/man/std::sin,std::sinf,std::sinl.3 @@ -0,0 +1,154 @@ +.TH std::sin,std::sinf,std::sinl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sin,std::sinf,std::sinl \- std::sin,std::sinf,std::sinl + +.SH Synopsis + Defined in header + float sin ( float num ); + + double sin ( double num ); (until C++23) + + long double sin ( long double num ); + /* floating-point-type */ (since C++23) + sin ( /* floating-point-type */ num ); (constexpr since C++26) + float sinf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double sinl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double sin ( Integer num ); + + 1-3) Computes the sine of num (measured in radians). + The library provides overloads of std::sin for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value representing angle in radians + +.SH Return value + + If no errors occur, the sine of num (sin(num)) in the range [-1, +1], is returned. + + The result may have little or no significance if the magnitude of num \fI(until C++11)\fP + is large. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0, it is returned unmodified. + * if the argument is ±∞, NaN is returned and FE_INVALID is raised. + * if the argument is NaN, NaN is returned. + +.SH Notes + + The case where the argument is infinite is not specified to be a domain error in C + (to which C++ defers), but it is defined as a domain error in POSIX. + + POSIX also specifies that in case of underflow, num is returned unmodified, and if + that is not supported, an implementation-defined value no greater than DBL_MIN, + FLT_MIN, and LDBL_MIN is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::sin(num) has the same effect as std::sin(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + + const double pi = std::acos(-1); // or std::numbers::pi since C++20 + + constexpr double your_sin(double x) + { + double sin{0}, pow{x}; + for (auto fac{1LLU}, n{1ULL}; n != 20; fac *= ++n, pow *= x) + if (n & 1) + sin += (n & 2 ? -pow : pow) / fac; + return sin; + } + + int main() + { + std::cout << std::setprecision(10) << std::showpos + << "Typical usage:\\n" + << "std::sin(pi/6) = " << std::sin(pi / 6) << '\\n' + << "your sin(pi/6) = " << your_sin(pi / 6) << '\\n' + << "std::sin(pi/2) = " << std::sin(pi / 2) << '\\n' + << "your sin(pi/2) = " << your_sin(pi / 2) << '\\n' + << "std::sin(-3*pi/4) = " << std::sin(-3 * pi / 4) << '\\n' + << "your sin(-3*pi/4) = " << your_sin(-3 * pi / 4) << '\\n' + << "Special values:\\n" + << "std::sin(+0) = " << std::sin(0.0) << '\\n' + << "std::sin(-0) = " << std::sin(-0.0) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "std::sin(INFINITY) = " << std::sin(INFINITY) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + Typical usage: + std::sin(pi/6) = +0.5 + your sin(pi/6) = +0.5 + std::sin(pi/2) = +1 + your sin(pi/2) = +1 + std::sin(-3*pi/4) = -0.7071067812 + your sin(-3*pi/4) = -0.7071067812 + Special values: + std::sin(+0) = +0 + std::sin(-0) = -0 + std::sin(INFINITY) = -nan + FE_INVALID raised + +.SH See also + + cos + cosf computes cosine (\\({\\small\\cos{x}}\\)cos(x)) + cosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tan + tanf computes tangent (\\({\\small\\tan{x}}\\)tan(x)) + tanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + asin + asinf computes arc sine (\\({\\small\\arcsin{x}}\\)arcsin(x)) + asinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sin(std::complex) computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z)) + \fI(function template)\fP + sin(std::valarray) applies the function std::sin to each element of valarray + \fI(function template)\fP + C documentation for + sin diff --git a/man/std::sin.3 b/man/std::sin.3 deleted file mode 100644 index f54bc393d..000000000 --- a/man/std::sin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::sin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float sin( float arg ); - double sin( double arg ); - long double sin( long double arg ); - double sin( Integral arg ); \fI(since C++11)\fP - - Computes sine of arg. - -.SH Parameters - - arg - value representing angle in radians, of a floating-point or Integral type - -.SH Return value - - Sine of arg in the range [-1 ; +1]. - - Domain error occurs if arg is infinite. NAN is returned in that case. - -.SH See also - - cos computes cosine (cos(x)) - \fI(function)\fP - tan computes tangent (tan(x)) - \fI(function)\fP - asin computes arc sine (arcsin(x)) - \fI(function)\fP - sin(std::complex) computes sine of a complex number (sin(z)) - \fI(function template)\fP - sin(std::valarray) applies the function std::sin to each element of valarray - \fI(function template)\fP - C documentation for - sin diff --git a/man/std::sinh(std::complex).3 b/man/std::sinh(std::complex).3 index c4c3722df..350b1510f 100644 --- a/man/std::sinh(std::complex).3 +++ b/man/std::sinh(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::sinh(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sinh(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sinh(std::complex) \- std::sinh(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -12,11 +15,93 @@ .SH Return value - Complex hyperbolic sine of z + If no errors occur, complex hyperbolic sine of z is returned. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::sinh(std::conj(z)) == std::conj(std::sinh(z)) + * std::sinh(z) == -std::sinh(-z) + * If z is (+0,+0), the result is (+0,+0) + * If z is (+0,+∞), the result is (±0,NaN) (the sign of the real part is + unspecified) and FE_INVALID is raised + * If z is (+0,NaN), the result is (±0,NaN) + * If z is (x,+∞) (for any positive finite x), the result is (NaN,NaN) and + FE_INVALID is raised + * If z is (x,NaN) (for any positive finite x), the result is (NaN,NaN) and + FE_INVALID may be raised + * If z is (+∞,+0), the result is (+∞,+0) + * If z is (+∞,y) (for any positive finite y), the result is +∞cis(y) + * If z is (+∞,+∞), the result is (±∞,NaN) (the sign of the real part is + unspecified) and FE_INVALID is raised + * If z is (+∞,NaN), the result is (±∞,NaN) (the sign of the real part is + unspecified) + * If z is (NaN,+0), the result is (NaN,+0) + * If z is (NaN,y) (for any finite nonzero y), the result is (NaN,NaN) and + FE_INVALID may be raised + * If z is (NaN,NaN), the result is (NaN,NaN) + + where cis(y) is cos(y) + i sin(y). + +.SH Notes + + Mathematical definition of hyperbolic sine is sinh z = + + ez + -e-z + 2 + + . + + Hyperbolic sine is an entire function in the complex plane and has no branch cuts. + It is periodic with respect to the imaginary component, with period 2πi. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z(1.0, 0.0); // behaves like real sinh along the real line + std::cout << "sinh" << z << " = " << std::sinh(z) + << " (sinh(1) = " << std::sinh(1) << ")\\n"; + + std::complex z2(0.0, 1.0); // behaves like sine along the imaginary line + std::cout << "sinh" << z2 << " = " << std::sinh(z2) + << " ( sin(1) = " << std::sin(1) << ")\\n"; + } + +.SH Output: + + sinh(1.000000,0.000000) = (1.175201,0.000000) (sinh\fB(1)\fP = 1.175201) + sinh(0.000000,1.000000) = (0.000000,0.841471) ( sin\fB(1)\fP = 0.841471) .SH See also - sin(std::complex) computes sine of a complex number (sin(z)) - \fI(function template)\fP - asin(std::complex) computes arc sine of a complex number (arcsin(z)) - \fI(C++11)\fP \fI(function template)\fP + computes hyperbolic cosine of a complex number + cosh(std::complex) (\\({\\small\\cosh{z}}\\)cosh(z)) + \fI(function template)\fP + computes hyperbolic tangent of a complex number + tanh(std::complex) (\\({\\small\\tanh{z}}\\)tanh(z)) + \fI(function template)\fP + asinh(std::complex) computes area hyperbolic sine of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{arsinh}{z}}\\)arsinh(z)) + \fI(function template)\fP + sinh + sinhf computes hyperbolic sine (\\({\\small\\sinh{x}}\\)sinh(x)) + sinhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + sinh(std::valarray) applies the function std::sinh to each element of valarray + \fI(function template)\fP + C documentation for + csinh diff --git a/man/std::sinh(std::valarray).3 b/man/std::sinh(std::valarray).3 index 9deb27dfb..2855dc32d 100644 --- a/man/std::sinh(std::valarray).3 +++ b/man/std::sinh(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::sinh(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sinh(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sinh(std::valarray) \- std::sinh(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (sinh) is used to perform the computation. If such function is - not available, std::sinh is used due to argument dependent lookup. + not available, std::sinh is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,21 +43,79 @@ valarray sinh(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = sinh(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + #include + #include + + template + void show(char const* title, const std::valarray& va) + { + std::cout << title << " : " << std::right; + for (T x : va) + std::cout << std::fixed << x << ' '; + std::cout << '\\n'; + } + + template + void sinh_for(std::valarray const& z) + { + // Hyperbolic sine is sinh(z) = (eᶻ - e⁻ᶻ) / 2. + + const std::valarray sinh_z{std::sinh(z)}; + const std::valarray e_z{std::exp(z)}; + const std::valarray e_neg_z{std::exp(-z)}; + const std::valarray sinh_def{(e_z - e_neg_z) / 2.0f}; - sinh computes hyperbolic sine (sh(x)) - \fI(function)\fP + show("n ", z); + show("sinh(n) ", sinh_z); + show("(eⁿ-e⁻ⁿ)/2", sinh_def); -.SH Category: + std::cout.put('\\n'); + } + + int main() + { + sinh_for(std::valarray{-.2f, -.1f, 0.f, .1f, .2f, INFINITY}); + sinh_for(std::valarray>{{-.2,-.1}, {.2,.1}}); + } + +.SH Output: + + n : -0.200000 -0.100000 0.000000 0.100000 0.200000 inf + sinh(n) : -0.201336 -0.100167 0.000000 0.100167 0.201336 inf + (eⁿ-e⁻ⁿ)/2 : -0.201336 -0.100167 0.000000 0.100167 0.201336 inf + + n : (-0.200000,-0.100000) (0.200000,0.100000) + sinh(n) : (-0.200330,-0.101837) (0.200330,0.101837) + (eⁿ-e⁻ⁿ)/2 : (-0.200330,-0.101837) (0.200330,0.101837) + +.SH See also - * Todo no example + cosh(std::valarray) applies the function std::cosh to each element of valarray + \fI(function template)\fP + tanh(std::valarray) applies the function std::tanh to each element of valarray + \fI(function template)\fP + sinh + sinhf computes hyperbolic sine (\\({\\small\\sinh{x}}\\)sinh(x)) + sinhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes hyperbolic sine of a complex number + sinh(std::complex) (\\({\\small\\sinh{z}}\\)sinh(z)) + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::sinh,std::sinhf,std::sinhl.3 b/man/std::sinh,std::sinhf,std::sinhl.3 new file mode 100644 index 000000000..11e1e0c79 --- /dev/null +++ b/man/std::sinh,std::sinhf,std::sinhl.3 @@ -0,0 +1,142 @@ +.TH std::sinh,std::sinhf,std::sinhl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sinh,std::sinhf,std::sinhl \- std::sinh,std::sinhf,std::sinhl + +.SH Synopsis + Defined in header + float sinh ( float num ); + + double sinh ( double num ); (until C++23) + + long double sinh ( long double num ); + /* floating-point-type */ (since C++23) + sinh ( /* floating-point-type */ num ); (constexpr since C++26) + float sinhf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double sinhl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double sinh ( Integer num ); + + 1-3) Computes the hyperbolic sine of num. + The library provides overloads of std::sinh for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the hyperbolic sine of num (sinh(num), or + + enum + -e-num + 2 + + ) is returned. + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0 or ±∞, it is returned unmodified. + * if the argument is NaN, NaN is returned. + +.SH Notes + + POSIX specifies that in case of underflow, num is returned unmodified, and if that + is not supported, and implementation-defined value no greater than DBL_MIN, FLT_MIN, + and LDBL_MIN is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::sinh(num) has the same effect as std::sinh(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + const double x = 42; + + std::cout << "sinh(1) = " << std::sinh(1) << '\\n' + << "sinh(-1) = " << std::sinh(-1) << '\\n' + << "log(sinh(" << x << ")+cosh(" << x << ")) = " + << std::log(std::sinh(x) + std::cosh(x)) << '\\n'; + + // special values + std::cout << "sinh(+0) = " << std::sinh(0.0) << '\\n' + << "sinh(-0) = " << std::sinh(-0.0) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "sinh(710.5) = " << std::sinh(710.5) << '\\n'; + + if (errno == ERANGE) + std::cout << " errno == ERANGE: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " FE_OVERFLOW raised\\n"; + } + +.SH Output: + + sinh\fB(1)\fP = 1.1752 + sinh(-1) = -1.1752 + log(sinh\fB(42)\fP+cosh(42)) = 42 + sinh(+0) = 0 + sinh(-0) = -0 + sinh(710.5) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised + +.SH See also + + cosh + coshf computes hyperbolic cosine (\\({\\small\\cosh{x}}\\)cosh(x)) + coshl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tanh + tanhf computes hyperbolic tangent (\\({\\small\\tanh{x}}\\)tanh(x)) + tanhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + asinh + asinhf computes the inverse hyperbolic sine + asinhl (\\({\\small\\operatorname{arsinh}{x}}\\)arsinh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes hyperbolic sine of a complex number + sinh(std::complex) (\\({\\small\\sinh{z}}\\)sinh(z)) + \fI(function template)\fP + sinh(std::valarray) applies the function std::sinh to each element of valarray + \fI(function template)\fP + C documentation for + sinh diff --git a/man/std::sinh.3 b/man/std::sinh.3 deleted file mode 100644 index 248577c48..000000000 --- a/man/std::sinh.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::sinh 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float sinh( float arg ); - double sinh( double arg ); - long double sinh( long double arg ); - double sinh( Integral arg ); \fI(since C++11)\fP - - Computes hyperbolic sine of arg - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Hyperbolic sine of arg. - -.SH See also - - cosh computes hyperbolic cosine (ch(x)) - \fI(function)\fP - tanh hyperbolic tangent - \fI(function)\fP - asinh area hyperbolic sine - \fI(C++11)\fP \fI(function)\fP - sinh(std::complex) computes hyperbolic sine of a complex number (sh(z)) - \fI(function template)\fP - sinh(std::valarray) applies the function std::sinh to each element of valarray - \fI(function template)\fP - C documentation for - sinh diff --git a/man/std::size,std::ssize.3 b/man/std::size,std::ssize.3 new file mode 100644 index 000000000..085d16f4c --- /dev/null +++ b/man/std::size,std::ssize.3 @@ -0,0 +1,168 @@ +.TH std::size,std::ssize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::size,std::ssize \- std::size,std::ssize + +.SH Synopsis + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + Defined in header + template< class C > \fB(1)\fP \fI(since C++17)\fP + constexpr auto size( const C& c ) -> decltype(c.size()); + template< class C > + + constexpr auto ssize( const C& c ) \fB(2)\fP \fI(since C++20)\fP + -> std::common_type_t>; + template< class T, std::size_t N > \fB(3)\fP \fI(since C++17)\fP + constexpr std::size_t size( const T (&array)[N] ) noexcept; + template< class T, std::ptrdiff_t N > \fB(4)\fP \fI(since C++20)\fP + constexpr std::ptrdiff_t ssize( const T (&array)[N] ) noexcept; + + Returns the size of the given range. + + 1,2) Returns c.size(), converted to the return type if necessary. + 3,4) Returns N. + +.SH Parameters + + c - a container or view with a size member function + array - an array of arbitrary type + +.SH Return value + + 1) c.size() + 2) static_cast>>(c.size()) + 3,4) N + +.SH Exceptions + + 1,2) May throw implementation-defined exceptions. + + Overloads + + Custom overloads of size may be provided for classes and enumerations that do not + expose a suitable size() member function, yet can be detected. + + Overloads of size found by argument-dependent lookup can be used to + customize the behavior of std::ranges::size, std::ranges::ssize, and \fI(since C++20)\fP + std::ranges::empty. + +.SH Possible implementation + + size \fB(1)\fP + template + constexpr auto size(const C& c) -> decltype(c.size()) + { + return c.size(); + } + ssize \fB(2)\fP + template + constexpr auto ssize(const C& c) + -> std::common_type_t> + { + using R = std::common_type_t>; + return static_cast(c.size()); + } + size \fB(3)\fP + template + constexpr std::size_t size(const T (&array)[N]) noexcept + { + return N; + } + ssize \fB(4)\fP + template + constexpr std::ptrdiff_t ssize(const T (&array)[N]) noexcept + { + return N; + } + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_nonmember_container_access 201411L \fI(C++17)\fP std::size(), std::data and + std::empty + __cpp_lib_ssize 201902L (C++20) std::ssize() (2,4) and unsigned + std::span::size() + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + // Works with containers + std::vector v{3, 1, 4}; + assert(std::size(v) == 3); + + // And works with built-in arrays too + int a[]{-5, 10, 15}; + // Returns the number of elements (not bytes) as opposed to sizeof + assert(std::size(a) == 3); + std::cout << "size of a[]: " << sizeof a << '\\n'; // 12, if sizeof(int) == 4 + + // Provides a safe way (compared to sizeof) of getting string buffer size + const char str[] = "12345"; + // These are fine and give the correct result + assert(std::size(str) == 6); + assert(sizeof(str) == 6); + + // But use of sizeof here is a common source of bugs + const char* str_decayed = "12345"; + // std::cout << std::size(str_decayed) << '\\n'; // Usefully fails to compile + std::cout << sizeof(str_decayed) << '\\n'; // Prints the size of the pointer! + + // Since C++20 the signed size (std::ssize) is available + auto i = std::ssize(v); + for (--i; i != -1; --i) + std::cout << v[i] << (i ? ' ' : '\\n'); + assert(i == -1); + + // Note that the string literal includes the ending null character, which + // will be part of the constructed characters array. This makes std::size + // behave differently from std::strlen and std::string::size: + constexpr char symbols[] = "0123456789"; + + static_assert(std::size(symbols) == 11); + static_assert(std::string(symbols).size() == 10); + assert(std::strlen(symbols) == 10); + } + +.SH Possible output: + + size of a[]: 12 + 8 + 4 1 3 + +.SH See also + + ptrdiff_t signed integer type returned when subtracting two pointers + \fI(typedef)\fP + size_t unsigned integer type returned by the sizeof operator + \fI(typedef)\fP + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) + ranges::ssize returns a signed integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::size_t.3 b/man/std::size_t.3 index ddec46cf9..c90d7e228 100644 --- a/man/std::size_t.3 +++ b/man/std::size_t.3 @@ -1,21 +1,30 @@ -.TH std::size_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::size_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::size_t \- std::size_t + .SH Synopsis Defined in header Defined in header + Defined in header Defined in header Defined in header + Defined in header \fI(since C++17)\fP Defined in header typedef /*implementation-defined*/ size_t; - std::size_t is the unsigned integer type of the result of the sizeof operator and - the alignof operator. + std::size_t is the unsigned integer type of the result of the sizeof operator + as well as the sizeof... operator and the alignof operator + \fI(since C++11)\fP. + + The bit width of std::size_t is not less than 16. \fI(since C++11)\fP .SH Notes std::size_t can store the maximum size of a theoretically possible object of any - type (including array). On many platforms (an exception are systems with segmented - addressing) std::size_t can safely store the value of any non-member pointer, in - which case it is synonymous with std::uintptr_t. + type (including array). A type whose size cannot be represented by std::size_t is + ill-formed. On many platforms (an exception is systems with segmented addressing) + std::size_t can safely store the value of any non-member pointer, in which case it + is synonymous with std::uintptr_t. std::size_t is commonly used for array indexing and loop counting. Programs that use other types, such as unsigned int, for array indexing may fail on, e.g. 64-bit @@ -26,28 +35,111 @@ type is the member typedef size_type provided by such containers. It is usually defined as a synonym for std::size_t. + It is unspecified whether the declaration of std::size_t is available in any other + standard library header. An implementation may avoid introducing this name even when + the standard requires std::size_t to be used. + + The integer literal suffix for std::size_t is any combination of z or (since C++23) + Z with u or U (i.e. zu, zU, Zu, ZU, uz, uZ, Uz, or UZ). + +.SH Possible implementation + + using size_t = decltype(sizeof\fB(0)\fP); // valid since C++11 + .SH Example - + // Run this code + #include #include - + #include + int main() { - const std::size_t N = 100; - int* a = new int[N]; - - for (std::size_t n = 0; n < N; ++n) - a[n] = n; - - delete[] a; + std::array a; + + // Example with C++23 size_t literal + for (auto i = 0uz; i != a.size(); ++i) + std::cout << (a[i] = i) << ' '; + std::cout << '\\n'; + + // Example of decrementing loop + for (std::size_t i = a.size(); i--;) + std::cout << a[i] << ' '; + std::cout << '\\n'; + + // Note the naive decrementing loop: + // for (std::size_t i = a.size() - 1; i >= 0; --i) ... + // is an infinite loop, because unsigned numbers are always non-negative } +.SH Output: + + 0 1 2 3 4 5 6 7 8 9 + 9 8 7 6 5 4 3 2 1 0 + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 6.8.4 Compound types [basic.compound] (p: 79-80) + + * 7.6.2.5 Sizeof [expr.sizeof] (p: 136) + + * 7.6.2.6 Alignof [expr.alignof] (p: 136) + + * 17.2.4 Sizes, alignments, and offsets [support.types.layout] (p: 504-505) + * C++20 standard (ISO/IEC 14882:2020): + + * 6.8.3 Compound types [basic.compound] (p: 75-76) + + * 7.6.2.5 Sizeof [expr.sizeof] (p: 129-130) + + * 7.6.2.6 Alignof [expr.alignof] (p: 130) + + * 17.2.4 Sizes, alignments, and offsets [support.types.layout] (p: 507-508) + * C++17 standard (ISO/IEC 14882:2017): + + * 6.9.2 Compound types [basic.compound] (p: 81-82) + + * 8.3.3 Sizeof [expr.sizeof] (p: 121-122) + + * 8.3.6 Alignof [expr.alignof] (p: 129) + + * 21.2.4 Sizes, alignments, and offsets [support.types.layout] (p: 479) + * C++14 standard (ISO/IEC 14882:2014): + + * 3.9.2 Compound types [basic.compound] (p: 73-74) + + * 5.3.3 Sizeof [expr.sizeof] (p: 109-110) + + * 5.3.6 Alignof [expr.alignof] (p: 116) + + * 18.2 Types [support.types] (p: 443-444) + * C++11 standard (ISO/IEC 14882:2011): + + * 5.3.3 Sizeof [expr.sizeof] (p: 111) + + * 5.3.6 Alignof [expr.alignof] (p: 116) + + * 18.2 Types [support.types] (p: 454-455) + * C++03 standard (ISO/IEC 14882:2003): + + * 5.3.3 Sizeof [expr.sizeof] (p: 79) + * C++98 standard (ISO/IEC 14882:1998): + + * 5.3.3 Sizeof [expr.sizeof] (p: 77) + .SH See also - ptrdiff_t signed integer type returned when subtracting two pointers - \fI(typedef)\fP - byte offset from the beginning of a standard-layout type to specified - offsetof member - \fI(function macro)\fP + ptrdiff_t signed integer type returned when subtracting two pointers + \fI(typedef)\fP + byte offset from the beginning of a standard-layout type to + offsetof specified member + \fI(function macro)\fP + binary, + integer literals \fI(since C++14)\fP decimal, octal, or hexadecimal numbers of integer + type + C documentation for + size_t diff --git a/man/std::sized_sentinel_for,std::disable_sized_sentinel_for.3 b/man/std::sized_sentinel_for,std::disable_sized_sentinel_for.3 new file mode 100644 index 000000000..08806c63f --- /dev/null +++ b/man/std::sized_sentinel_for,std::disable_sized_sentinel_for.3 @@ -0,0 +1,36 @@ +.TH std::sized_sentinel_for,std::disable_sized_sentinel_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sized_sentinel_for,std::disable_sized_sentinel_for \- std::sized_sentinel_for,std::disable_sized_sentinel_for + +.SH Synopsis + Defined in header + template< class S, class I > + + concept sized_sentinel_for = + std::sentinel_for && + !std::disable_sized_sentinel_for, + std::remove_cv_t> && \fB(1)\fP \fI(since C++20)\fP + requires(const I& i, const S& s) { + { s - i } -> std::same_as>; + { i - s } -> std::same_as>; + + }; + template< class S, class I > \fB(2)\fP \fI(since C++20)\fP + inline constexpr bool disable_sized_sentinel_for = false; + + 1) The sized_sentinel_for concept specifies that an object of the iterator type I + and an object of the sentinel type S can be subtracted to compute the distance + between them in constant time. + 2) The disable_sized_sentinel_for variable template can be used to prevent iterators + and sentinels that can be subtracted but do not actually model sized_sentinel_for + from satisfying the concept. + A program may specialize disable_sized_sentinel_for for cv-unqualified non-array + object type S and I, as long as at least one of which is a program-defined type. + Such specializations are usable in constant expressions and have type const bool. + +.SH See also + + ranges::sized_range specifies that a range knows its size in constant time + (C++20) (concept) + ranges::size returns an integer equal to the size of a range + (C++20) (customization point object) diff --git a/man/std::skipws,std::noskipws.3 b/man/std::skipws,std::noskipws.3 index d805dbf48..48b74959a 100644 --- a/man/std::skipws,std::noskipws.3 +++ b/man/std::skipws,std::noskipws.3 @@ -1,4 +1,7 @@ -.TH std::skipws,std::noskipws 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::skipws,std::noskipws 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::skipws,std::noskipws \- std::skipws,std::noskipws + .SH Synopsis Defined in header std::ios_base& skipws( std::ios_base& str ); \fB(1)\fP @@ -7,11 +10,10 @@ Enables or disables skipping of leading whitespace by the formatted input functions (enabled by default). Has no effect on output. - 1) enables the skipws flag in the stream str as if by calling - str.setf(std::ios_base::skipws) - - 2) disables the skipws flag in the stream str as if by calling - str.unsetf(std::ios_base::skipws) + 1) Enables the skipws flag in the stream str as if by calling + str.setf(std::ios_base::skipws). + 2) Disables the skipws flag in the stream str as if by calling + str.unsetf(std::ios_base::skipws). The whitespace skipping is performed by the constructor of std::basic_istream::sentry, which reads and discards the characters classified as @@ -27,22 +29,29 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code #include #include + int main() { char c1, c2, c3; std::istringstream("a b c") >> c1 >> c2 >> c3; - std::cout << "Default behavior: c1 = " << c1 << " c2 = " << c2 << " c3 = " << c3 << '\\n'; + std::cout << "Default behavior:" + " c1 = " << c1 << + " c2 = " << c2 << + " c3 = " << c3 << '\\n'; std::istringstream("a b c") >> std::noskipws >> c1 >> c2 >> c3; - std::cout << "noskipws behavior: c1 = " << c1 << " c2 = " << c2 << " c3 = " << c3 << '\\n'; + std::cout << "noskipws behavior:" + " c1 = " << c1 << + " c2 = " << c2 << + " c3 = " << c3 << '\\n'; } .SH Output: @@ -53,6 +62,8 @@ .SH See also resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP + ws consumes whitespace + \fI(function template)\fP diff --git a/man/std::slice.3 b/man/std::slice.3 index 76c087efe..62daea97e 100644 --- a/man/std::slice.3 +++ b/man/std::slice.3 @@ -1,4 +1,7 @@ -.TH std::slice 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::slice 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::slice \- std::slice + .SH Synopsis Defined in header class slice; @@ -6,7 +9,7 @@ std::slice is the selector class that identifies a subset of std::valarray similar to BLAS slice. An object of type std::slice holds three values: the starting index, the stride, and the total number of values in the subset. Objects of type std::slice - can be used as indexes with valarray's operator[]. + can be used as indices with valarray's operator[]. .SH Member functions @@ -16,11 +19,11 @@ size \fI(public member function)\fP stride - std::slice::slice +std::slice::slice - slice() - slice( std::size_t start, std::size_t size, std::size_t stride ); - slice( const slice& other ); + slice() \fB(1)\fP + slice( std::size_t start, std::size_t size, std::size_t stride ); \fB(2)\fP + slice( const slice& other ); \fB(3)\fP Constructs a new slice. @@ -28,10 +31,10 @@ to allow construction of arrays of slices. 2) Constructs a new slice with parameters start, size, stride. This slice will refer to size number of elements, each with the position: - start + 0*stride - start + 1*stride + start + 0 * stride + start + 1 * stride ... - start + (size-1)*stride + start + (size - 1) * stride 3) Constructs a copy of other. .SH Parameters @@ -41,7 +44,7 @@ stride - the number of positions between successive elements in the slice other - another slice to copy - std::slice::start, size, stride +std::slice::start, size, stride std::size_t start() const; \fB(1)\fP std::size_t size() const; \fB(2)\fP @@ -62,31 +65,59 @@ Constant. +.SH Non-member functions + + operator==(std::slice) checks if two slices are equal + (C++20) \fI(function)\fP + +operator==(std::slice) + + friend bool operator==( const slice& lhs, const slice& rhs ); \fI(since C++20)\fP + + Checks if the parameters of lhs and rhs - start, size and stride are equal + respectively. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::slice is an associated class of + the arguments. + + The != operator is synthesized from operator==. + +.SH Parameters + + lhs, rhs - slices to compare + +.SH Return value + + lhs.start() == rhs.start() && lhs.size() == rhs.size() && lhs.stride() == + rhs.stride() + .SH Example Barebones valarray-backed Matrix class with a trace calculating function. - + // Run this code #include #include - class Matrix { + + class Matrix + { std::valarray data; int dim; - public: + public: Matrix(int r, int c) : data(r*c), dim(c) {} - int& operator()(int r, int c) {return data[r*dim + c];} - int trace() const { - return data[std::slice(0, dim, dim+1)].sum(); - } + int& operator()(int r, int c) { return data[r * dim + c]; } + int trace() const { return data[std::slice(0, dim, dim + 1)].sum(); } }; + int main() { - Matrix m(3,3); + Matrix m(3, 3); int n = 0; - for(int r=0; r<3; ++r) - for(int c=0; c<3; ++c) + for (int r = 0; r < 3; ++r) + for (int c = 0; c < 3; ++c) m(r, c) = ++n; std::cout << "Trace of the matrix (1,2,3) (4,5,6) (7,8,9) is " << m.trace() << '\\n'; } @@ -95,12 +126,21 @@ Trace of the matrix (1,2,3) (4,5,6) (7,8,9) is 15 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 543 C++98 it was unclear whether a default it is usable (as an empty + constructed slice is usable subset) + .SH See also operator[] get/set valarray element, slice, or mask - \fI(public member function)\fP + \fI(public member function)\fP generalized slice of a valarray: starting index, set of lengths, set of gslice strides - \fI(class)\fP + \fI(class)\fP slice_array proxy to a subset of a valarray after applying a slice - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::slice_array.3 b/man/std::slice_array.3 index b437684e8..6ae6c3eb1 100644 --- a/man/std::slice_array.3 +++ b/man/std::slice_array.3 @@ -1,10 +1,14 @@ -.TH std::slice_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::slice_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::slice_array \- std::slice_array + .SH Synopsis Defined in header template< class T > class slice_array; - std::slice_array is a helper template used by std::slice subscript operator. It has - reference semantics to a subset of the array specified by the std::slice object. + std::slice_array is a helper template used by the valarray subscript operator with + std::slice argument. It has reference semantics to a subset of the array specified + by the std::slice object. .SH Member types @@ -14,17 +18,17 @@ .SH Member functions constructor constructs a slice_array - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a slice_array - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns contents - \fI(public member function)\fP + \fI(public member function)\fP operator+= operator-= operator*= operator/= operator%= performs arithmetic operation on the array referred by slice. - operator&= \fI(public member function)\fP + operator&= \fI(public member function)\fP operator|= operator^= operator<<= @@ -32,14 +36,115 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - gslice_array proxy to a subset of a valarray after applying a gslice - \fI(class template)\fP + #include + #include + + class Matrix + { + int dim; + std::valarray data; + public: + explicit Matrix(int dim, int init = 0) + : dim{dim}, data(init, dim*dim) {} + void clear(int value = 0) { data = value; } + void identity() { clear(); diagonal() = 1; } + int& operator()(int x, int y) { return data[dim * y + x]; } + + std::slice_array diagonal() + { + return data[std::slice(0, dim, dim + 1)]; + } + std::slice_array secondary_diagonal() + { + return data[std::slice(dim - 1, dim, dim - 1)]; + } + std::slice_array row(std::size_t row) + { + return data[std::slice(dim * row, dim, 1)]; + } + std::slice_array column(std::size_t col) + { + return data[std::slice(col, dim, dim)]; + } + template friend class MatrixStack; + }; + + template class MatrixStack + { + std::valarray stack; + unsigned count = 0; + public: + MatrixStack() : stack(dim * dim * max) {} + void print_all() const + { + std::valarray row(dim*count); + for (unsigned r = 0; r != dim; ++r) // screen row + { + row = stack[std::gslice(r * dim, {count, dim}, {dim * dim, 1})]; + for (unsigned i = 0; i != row.size(); ++i) + std::cout << row[i] << ((i + 1) % dim ? " " : " │ "); + std::cout << '\\n'; + } + } + void push_back(Matrix const& m) + { + if (count < max) + { + stack[std::slice(count * dim * dim, dim * dim, 1)] + = m.data[std::slice(0, dim * dim, 1)]; + ++count; + } + } + }; + + int main() + { + constexpr int dim = 3; + Matrix m{dim}; + MatrixStack stack; + + m.identity(); + stack.push_back(m); + + m.clear(1); + m.secondary_diagonal() = 3; + stack.push_back(m); -.SH Category: + for (int i = 0; i != dim; ++i) + { + m.clear(); + m.row(i) = i + 1; + stack.push_back(m); + } - * Todo no example + for (int i = 0; i != dim; ++i) + { + m.clear(); + m.column(i) = i + 1; + stack.push_back(m); + } + + m.clear(); + m.row(1) = std::valarray{4, 5, 6}; + stack.push_back(m); + + m.clear(); + m.column(1) = std::valarray{7, 8, 9}; + stack.push_back(m); + + stack.print_all(); + } + +.SH Output: + + 1 0 0 │ 1 1 3 │ 1 1 1 │ 0 0 0 │ 0 0 0 │ 1 0 0 │ 0 2 0 │ 0 0 3 │ 0 0 0 │ 0 7 0 │ + 0 1 0 │ 1 3 1 │ 0 0 0 │ 2 2 2 │ 0 0 0 │ 1 0 0 │ 0 2 0 │ 0 0 3 │ 4 5 6 │ 0 8 0 │ + 0 0 1 │ 3 1 1 │ 0 0 0 │ 0 0 0 │ 3 3 3 │ 1 0 0 │ 0 2 0 │ 0 0 3 │ 0 0 0 │ 0 9 0 │ + +.SH See also + + gslice_array proxy to a subset of a valarray after applying a gslice + \fI(class template)\fP diff --git a/man/std::slice_array::operator=.3 b/man/std::slice_array::operator=.3 index 466916de4..85df2d8b2 100644 --- a/man/std::slice_array::operator=.3 +++ b/man/std::slice_array::operator=.3 @@ -1,35 +1,116 @@ -.TH std::slice_array::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::slice_array::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::slice_array::operator= \- std::slice_array::operator= + .SH Synopsis - void operator=( const T& value ) const; \fB(1)\fP - void operator=( const std::valarray& val_arr ) const; \fB(2)\fP - const slice_array& operator=( const slice_array& sl_arr) const; \fB(3)\fP \fI(since C++11)\fP + void operator=( const T& value ) const; \fB(1)\fP + void operator=( const std::valarray& val_arr ) const; \fB(2)\fP + const slice_array& operator=( const slice_array& other_arr ) const; \fB(3)\fP Assigns values to all referred elements. 1) Assigns value to all of the elements. 2) Assigns the elements of val_arr to the referred to elements of *this. - 3) Assigns the selected elements from sl_arr to the referred to elements of *this. + 3) Assigns the selected elements from other_arr to the referred to elements of + *this. .SH Parameters - value - a value to assign to all of the referred elements - val_arr - std::valarray to assign - sl_arr - std::slice_array to assign + value - a value to assign to all of the referred elements + val_arr - std::valarray to assign + other_arr - std::slice_array to assign .SH Return value - 1-2) \fI(none)\fP + 1,2) \fI(none)\fP 3) *this -.SH Exceptions +.SH Example + - \fI(none)\fP +// Run this code -.SH Example + #include + #include + + void print(char const* remark, std::valarray const& v = {}) + { + std::cout << remark; + if (v.size() != 0) + { + std::cout << ':'; + for (int e : v) + std::cout << ' ' << e; + } + std::cout << '\\n'; + } + + int main() + { + std::valarray v1{1, 2, 3, 4, 5, 6, 7, 8}; + std::slice_array s1 = v1[std::slice(1, 4, 2)]; + print("v1", v1); + print("s1", s1); + + print("\\n(1) operator=( const T& )"); + print("s1 = 42"); + s1 = 42; // (1) + print("s1", s1); + print("v1", v1); + + print("\\n(2) operator=( const std::valarray& )"); + std::valarray v2{10, 11, 12, 13, 14, 15}; + print("v2", v2); + print("s1 = v2"); + s1 = v2; // (2) + print("s1", s1); + print("v1", v1); + + print("\\n(3) operator=( const slice_array& )"); + v1 = {1, 2, 3, 4, 5, 6, 7, 8}; + std::slice_array s2 = v1[std::slice(0, 4, 1)]; + std::slice_array s3 = v2[std::slice(1, 4, 1)]; + print("v1", v1); + print("v2", v2); + print("s2", s2); + print("s3", s3); + print("s2 = s3"); + s2 = s3; // (3) Note: LHS and RHS must have same size. + print("s2", s2); + print("v1", v1); + } + +.SH Output: + + v1: 1 2 3 4 5 6 7 8 + s1: 2 4 6 8 + + \fB(1)\fP operator=( const T& ) + s1 = 42 + s1: 42 42 42 42 + v1: 1 42 3 42 5 42 7 42 + + \fB(2)\fP operator=( const std::valarray& ) + v2: 10 11 12 13 14 15 + s1 = v2 + s1: 10 11 12 13 + v1: 1 10 3 11 5 12 7 13 + + \fB(3)\fP operator=( const slice_array& ) + v1: 1 2 3 4 5 6 7 8 + v2: 10 11 12 13 14 15 + s2: 1 2 3 4 + s3: 11 12 13 14 + s2 = s3 + s2: 11 12 13 14 + v1: 11 12 13 14 5 6 7 8 - This section is incomplete - Reason: no example + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo no example + DR Applied to Behavior as published Correct behavior + LWG 123 C++98 overload \fB(2)\fP was non-const made const + LWG 253 C++98 the copy assignment operator was private made public + LWG 621 C++98 the copy assignment operator was non-const made const diff --git a/man/std::slice_array::slice_array.3 b/man/std::slice_array::slice_array.3 index fdaae97e9..45aeada7d 100644 --- a/man/std::slice_array::slice_array.3 +++ b/man/std::slice_array::slice_array.3 @@ -1,12 +1,30 @@ -.TH std::slice_array::slice_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::slice_array::slice_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::slice_array::slice_array \- std::slice_array::slice_array + .SH Synopsis - slice_array( const slice_array& other ); + private: \fI(until C++11)\fP + slice_array(); + public: \fB(1)\fP \fI(since C++11)\fP slice_array() = delete; + public: \fB(2)\fP + slice_array( const slice_array& other ); - Constructs a slice_array from another slice_array other. - - The default constructor is implicitly deleted. + 1) The default constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: slice_array is not DefaultConstructible. + 2) Constructs a slice_array from another slice_array other. .SH Parameters other - slice_array to initialize with + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 253 C++98 the copy constructor was private made public diff --git a/man/std::slice_array::~slice_array.3 b/man/std::slice_array::~slice_array.3 index fe8ae54ea..921a550cc 100644 --- a/man/std::slice_array::~slice_array.3 +++ b/man/std::slice_array::~slice_array.3 @@ -1,6 +1,9 @@ -.TH std::slice_array::~slice_array 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::slice_array::~slice_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::slice_array::~slice_array \- std::slice_array::~slice_array + .SH Synopsis ~slice_array(); - Destroys the indexes in the array. The elements referred to by the object are not + Destroys the indices in the array. The elements referred to by the object are not modified. diff --git a/man/std::sort.3 b/man/std::sort.3 index 561c57312..8c1c4bfeb 100644 --- a/man/std::sort.3 +++ b/man/std::sort.3 @@ -1,112 +1,183 @@ -.TH std::sort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sort \- std::sort + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP + template< class RandomIt > \fB(1)\fP (constexpr since C++20) void sort( RandomIt first, RandomIt last ); - template< class RandomIt, class Compare > \fB(2)\fP - void sort( RandomIt first, RandomIt last, Compare comp ); + template< class ExecutionPolicy, class RandomIt > - Sorts the elements in the range [first, last) in ascending order. The order of equal - elements is not guaranteed to be preserved. The first version uses operator< to - compare the elements, the second version uses the given comparison function object - comp. + void sort( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last ); + template< class RandomIt, class Compare > + void sort( RandomIt first, RandomIt last, Compare comp \fB(3)\fP (constexpr since C++20) + ); + template< class ExecutionPolicy, class RandomIt, class + Compare > + + void sort( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last, Compare comp + ); + + Sorts the elements in the range [first, last) in non-descending order. The order of + equal elements is not guaranteed to be preserved. + + 1) Elements are sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the behavior is undefined: + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements to sort - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + first, last - the range of elements to sort + policy - the execution policy to use. See execution policy for details. + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. - - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - Compare must meet the requirements of Compare. -.SH Return value +.SH Complexity - \fI(none)\fP + Given \\(\\scriptsize N\\)N as last - first: -.SH Complexity + 1,2) \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N·log(N)) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3,4) \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N·log(N)) applications of the comparator + comp. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation - O(N·log(N)), where N = std::distance(first, last) comparisons on \fI(until C++11)\fP - average. - O(N·log(N)), where N = std::distance(first, last) comparisons. \fI(since C++11)\fP + See also the implementations in libstdc++ and libc++. + +.SH Notes + + Before LWG713, the complexity requirement allowed sort() to be implemented using + only Quicksort, which may need \\(\\scriptsize O(N^2)\\)O(N2 + ) comparisons in the worst case. + + Introsort can handle all cases with \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N·log(N)) + comparisons (without incurring additional overhead in the average case), and thus is + usually used for implementing sort(). + + libc++ has not implemented the corrected time complexity requirement until LLVM 14. .SH Example - + // Run this code #include - #include #include + #include #include - + #include + int main() { - std::array s = {5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; - - // sort using the default operator< + std::array s{5, 7, 4, 2, 8, 6, 1, 9, 0, 3}; + + auto print = [&s](std::string_view const rem) + { + for (auto a : s) + std::cout << a << ' '; + std::cout << ": " << rem << '\\n'; + }; + std::sort(s.begin(), s.end()); - for (int a : s) { - std::cout << a << " "; - } - std::cout << '\\n'; - - // sort using a standard library compare function object + print("sorted with the default operator<"); + std::sort(s.begin(), s.end(), std::greater()); - for (int a : s) { - std::cout << a << " "; + print("sorted with the standard library compare function object"); + + struct + { + bool operator()(int a, int b) const { return a < b; } } - std::cout << '\\n'; - - // sort using a custom function object - struct { - bool operator()(int a, int b) - { - return a < b; - } - } customLess; + customLess; + std::sort(s.begin(), s.end(), customLess); - for (int a : s) { - std::cout << a << " "; - } - std::cout << '\\n'; - - // sort using a lambda expression - std::sort(s.begin(), s.end(), [](int a, int b) { - return b < a; - }); - for (int a : s) { - std::cout << a << " "; - } - std::cout << '\\n'; + print("sorted with a custom function object"); + + std::sort(s.begin(), s.end(), [](int a, int b) + { + return a > b; + }); + print("sorted with a lambda expression"); } .SH Output: - 0 1 2 3 4 5 6 7 8 9 - 9 8 7 6 5 4 3 2 1 0 - 0 1 2 3 4 5 6 7 8 9 - 9 8 7 6 5 4 3 2 1 0 + 0 1 2 3 4 5 6 7 8 9 : sorted with the default operator< + 9 8 7 6 5 4 3 2 1 0 : sorted with the standard library compare function object + 0 1 2 3 4 5 6 7 8 9 : sorted with a custom function object + 9 8 7 6 5 4 3 2 1 0 : sorted with a lambda expression + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the \\(\\scriptsize O(N \\cdot it is required for + LWG 713 C++98 \\log(N))\\)O(N·log(N)) time complexity was only the worst case + required on the average .SH See also partial_sort sorts the first N elements of a range - \fI(function template)\fP + \fI(function template)\fP stable_sort sorts a range of elements while preserving order between equal elements - \fI(function template)\fP + \fI(function template)\fP + ranges::sort sorts a range into ascending order + (C++20) (niebloid) diff --git a/man/std::sort_heap.3 b/man/std::sort_heap.3 index 0f3abc0c4..b329a1f90 100644 --- a/man/std::sort_heap.3 +++ b/man/std::sort_heap.3 @@ -1,70 +1,89 @@ -.TH std::sort_heap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sort_heap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sort_heap \- std::sort_heap + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP + template< class RandomIt > \fB(1)\fP (constexpr since C++20) void sort_heap( RandomIt first, RandomIt last ); - template< class RandomIt, class Compare > \fB(2)\fP - void sort_heap( RandomIt first, RandomIt last, Compare comp ); + template< class RandomIt, class Compare > + void sort_heap( RandomIt first, RandomIt last, Compare \fB(2)\fP (constexpr since C++20) + comp ); + + Converts the heap [first, last) into a sorted range. The heap property is no longer + maintained. + + 1) The heap is with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, and will be sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) The heap is with respect to comp, and will be sorted with respect to comp. - Converts the max heap [first, last) into a sorted range in ascending order. The - resulting range no longer has the heap property. + If any of the following conditions is satisfied, the behavior is undefined: - The first version of the function uses operator< to compare the elements, the second - uses the given comparison function comp. + * [first, last) is not a heap. + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements to sort - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the heap to be sorted + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. - -.SH Return value - - \fI(none)\fP + Compare must meet the requirements of Compare. .SH Complexity - At most N×log(N) comparisons where N=std::distance(first, last). - -.SH Notes - - A max heap is a range of elements [f,l) that has the following properties: - - * *f is the largest element in the range - * a new element can be added using std::push_heap() - * the first element can be removed using std::pop_heap() + Given \\(\\scriptsize N\\)N as std::distance(first, last): - The actual arrangement of the elements is implementation defined. + 1) At most \\(\\scriptsize 2N \\cdot \\log(N)\\)2N⋅log(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize 2N \\cdot \\log(N)\\)2N⋅log(N) applications of the comparison + function comp. .SH Possible implementation -.SH First version - template< class RandomIt > - void sort_heap( RandomIt first, RandomIt last ); + sort_heap \fB(1)\fP + template + void sort_heap(RandomIt first, RandomIt last) { while (first != last) std::pop_heap(first, last--); } -.SH Second version - template< class RandomIt, class Compare > - void sort_heap( RandomIt first, RandomIt last, Compare comp ); + sort_heap \fB(2)\fP + template + void sort_heap(RandomIt first, RandomIt last, Compare comp) { while (first != last) std::pop_heap(first, last--, comp); @@ -72,39 +91,59 @@ .SH Example - + // Run this code #include - #include #include - + #include + #include + + void println(std::string_view fmt, const auto& v) + { + for (std::cout << fmt; const auto &i : v) + std::cout << i << ' '; + std::cout << '\\n'; + } + int main() { - std::vector v = {3, 1, 4, 1, 5, 9}; - + std::vector v{3, 1, 4, 1, 5, 9}; + std::make_heap(v.begin(), v.end()); - - std::cout << "heap:\\t"; - for (const auto &i : v) { - std::cout << i << ' '; - } - + println("after make_heap, v: ", v); + std::sort_heap(v.begin(), v.end()); - - std::cout << "\\nsorted:\\t"; - for (const auto &i : v) { - std::cout << i << ' '; - } - std::cout << '\\n'; + println("after sort_heap, v: ", v); } .SH Output: - heap: 9 4 5 1 1 3 - sorted: 1 1 3 4 5 9 + after make_heap, v: 9 4 5 1 1 3 + after sort_heap, v: 1 1 3 4 5 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + at most \\(\\scriptsize N \\cdot increased to \\(\\scriptsize 2N + LWG 2444 C++98 \\log(N)\\)N⋅log(N) comparisons were \\cdot \\log(N)\\)2N⋅log(N) + allowed .SH See also - make_heap creates a max heap out of a range of elements - \fI(function template)\fP + is_heap checks if the given range is a max heap + \fI(C++11)\fP \fI(function template)\fP + is_heap_until finds the largest subrange that is a max heap + \fI(C++11)\fP \fI(function template)\fP + make_heap creates a max heap out of a range of elements + \fI(function template)\fP + pop_heap removes the largest element from a max heap + \fI(function template)\fP + push_heap adds an element to a max heap + \fI(function template)\fP + ranges::sort_heap turns a max heap into a range of elements sorted in ascending + (C++20) order + (niebloid) diff --git a/man/std::sortable.3 b/man/std::sortable.3 new file mode 100644 index 000000000..7a48993c8 --- /dev/null +++ b/man/std::sortable.3 @@ -0,0 +1,51 @@ +.TH std::sortable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sortable \- std::sortable + +.SH Synopsis + Defined in header + template< class I, class Comp = ranges::less, class Proj = + std::identity > + + concept sortable = \fI(since C++20)\fP + std::permutable && + + std::indirect_strict_weak_order>; + + The sortable concept specifies the requirements for algorithms that permute a range + into an ordered range according to Comp. + + Semantic requirements + + std::sortable is modeled only if all concepts it subsumes are + modeled. + +.SH See also + + ranges::sort sorts a range into ascending order + (C++20) (niebloid) + ranges::stable_sort sorts a range of elements while preserving order between + (C++20) equal elements + (niebloid) + ranges::partial_sort sorts the first N elements of a range + (C++20) (niebloid) + ranges::nth_element partially sorts the given range making sure that it is + (C++20) partitioned by the given element + (niebloid) + ranges::inplace_merge merges two ordered ranges in-place + (C++20) (niebloid) + ranges::push_heap adds an element to a max heap + (C++20) (niebloid) + ranges::pop_heap removes the largest element from a max heap + (C++20) (niebloid) + ranges::make_heap creates a max heap out of a range of elements + (C++20) (niebloid) + ranges::sort_heap turns a max heap into a range of elements sorted in + (C++20) ascending order + (niebloid) + ranges::next_permutation generates the next greater lexicographic permutation of a + (C++20) range of elements + (niebloid) + ranges::prev_permutation generates the next smaller lexicographic permutation of a + (C++20) range of elements + (niebloid) diff --git a/man/std::sorted_equivalent_t,std::sorted_equivalent.3 b/man/std::sorted_equivalent_t,std::sorted_equivalent.3 new file mode 100644 index 000000000..33d66e089 --- /dev/null +++ b/man/std::sorted_equivalent_t,std::sorted_equivalent.3 @@ -0,0 +1,43 @@ +.TH std::sorted_equivalent_t,std::sorted_equivalent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sorted_equivalent_t,std::sorted_equivalent \- std::sorted_equivalent_t,std::sorted_equivalent + +.SH Synopsis + Defined in header + Defined in header + struct sorted_equivalent_t { explicit sorted_equivalent_t() = \fB(1)\fP (since C++23) + default; }; + inline constexpr sorted_equivalent_t sorted_equivalent{}; \fB(2)\fP (since C++23) + + 1) The type std::sorted_equivalent_t can be used in the function's (including + constructor's) parameter list to match the intended tag. + 2) The corresponding std::sorted_equivalent instance of \fB(1)\fP is a disambiguation tag + that can be passed to the functions of std::flat_multimap and std::flat_multiset to + indicate that the input range or container is sorted (with respect to the comparator + used in flat container adaptor), whilst uniqueness of elements is not required. + +.SH Standard library + + The following standard library container adaptors use (1,2) as disambiguation tags: + + flat_multimap adapts two containers to provide a collection of key-value pairs, + (C++23) sorted by keys + \fI(class template)\fP + flat_multiset adapts a container to provide a collection of keys, sorted by keys + (C++23) \fI(class template)\fP + +.SH See also + + sorted_unique indicates that elements of a range are sorted and unique + sorted_unique_t (tag) + (C++23) + from_range_t from-range construction tag + from_range (tag) + (C++23) + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP diff --git a/man/std::sorted_unique_t,std::sorted_unique.3 b/man/std::sorted_unique_t,std::sorted_unique.3 new file mode 100644 index 000000000..0f5ff8f3d --- /dev/null +++ b/man/std::sorted_unique_t,std::sorted_unique.3 @@ -0,0 +1,42 @@ +.TH std::sorted_unique_t,std::sorted_unique 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sorted_unique_t,std::sorted_unique \- std::sorted_unique_t,std::sorted_unique + +.SH Synopsis + Defined in header + Defined in header + struct sorted_unique_t { explicit sorted_unique_t() = default; }; \fB(1)\fP (since C++23) + inline constexpr sorted_unique_t sorted_unique{}; \fB(2)\fP (since C++23) + + 1) The type std::sorted_unique_t can be used in the function's (including + constructor's) parameter list to match the intended tag. + 2) The corresponding std::sorted_unique instance of \fB(1)\fP is a disambiguation tag that + can be passed to the functions of std::flat_map and std::flat_set to indicate that + the input range or container is sorted (with respect to the comparator used in flat + container adaptor) and all elements of such container or range are unique. + +.SH Standard library + + The following standard library container adaptors use (1,2) as disambiguation tags: + + flat_map adapts two containers to provide a collection of key-value pairs, sorted by + (C++23) unique keys + \fI(class template)\fP + flat_set adapts a container to provide a collection of unique keys, sorted by keys + (C++23) \fI(class template)\fP + +.SH See also + + sorted_equivalent indicates that elements of a range are sorted (uniqueness is not + sorted_equivalent_t required) + (C++23) (tag) + from_range_t from-range construction tag + from_range (tag) + (C++23) + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP diff --git a/man/std::source_location.3 b/man/std::source_location.3 new file mode 100644 index 000000000..312139f3c --- /dev/null +++ b/man/std::source_location.3 @@ -0,0 +1,100 @@ +.TH std::source_location 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location \- std::source_location + +.SH Synopsis + Defined in header + struct source_location; \fI(since C++20)\fP + + The std::source_location class represents certain information about the source code, + such as file names, line numbers, and function names. Previously, functions that + desire to obtain this information about the call site (for logging, testing, or + debugging purposes) must use macros so that predefined macros like __LINE__ and + __FILE__ are expanded in the context of the caller. The std::source_location class + provides a better alternative. + + std::source_location meets the DefaultConstructible, CopyConstructible, + CopyAssignable and Destructible requirements. Lvalue of std::source_location meets + the Swappable requirement. + + Additionally, the following conditions are true: + + * std::is_nothrow_move_constructible_v, + * std::is_nothrow_move_assignable_v, and + * std::is_nothrow_swappable_v. + + It is intended that std::source_location has a small size and can be copied + efficiently. + + It is unspecified whether the copy/move constructors and the copy/move assignment + operators of std::source_location are trivial and/or constexpr. + +.SH Member functions + + Creation + constructor constructs a new source_location with implementation-defined values + \fI(public member function)\fP + current constructs a new source_location corresponding to the location of the + \fB[static]\fP call site + \fI(public static member function)\fP + Field access + line return the line number represented by this object + \fI(public member function)\fP + column return the column number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_source_location 201907L (C++20) Source-code information capture + (std::source_location) + +.SH Example + + +// Run this code + + #include + #include + #include + + void log(const std::string_view message, + const std::source_location location = + std::source_location::current()) + { + std::clog << "file: " + << location.file_name() << '(' + << location.line() << ':' + << location.column() << ") `" + << location.function_name() << "`: " + << message << '\\n'; + } + + template + void fun(T x) + { + log(x); // line 20 + } + + int main(int, char*[]) + { + log("Hello world!"); // line 25 + fun("Hello C++20!"); + } + +.SH Possible output: + + file: main.cpp(25:8) `int main(int, char**)`: Hello world! + file: main.cpp(20:8) `void fun(T) [with T = const char*]`: Hello C++20! + +.SH See also + + changes the source code's line number and, optionally, the current + #line file name + (preprocessing directive) + stacktrace_entry representation of an evaluation in a stacktrace + (C++23) \fI(class)\fP diff --git a/man/std::source_location::column.3 b/man/std::source_location::column.3 new file mode 100644 index 000000000..8b01f017e --- /dev/null +++ b/man/std::source_location::column.3 @@ -0,0 +1,63 @@ +.TH std::source_location::column 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location::column \- std::source_location::column + +.SH Synopsis + constexpr std::uint_least32_t column() const noexcept; \fI(since C++20)\fP + + Returns an implementation-defined value representing some offset from the start of + the line represented by this object (i.e., the column number). Column numbers are + presumed to be 1-indexed. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + An implementation-defined value representing some offset from the start of the line + represented by this object (i.e., the column number). + + An implementation is encouraged to use 0 when the column number is unknown. + +.SH Example + + +// Run this code + + #include + #include + + template + inline void pos(const T& location = T::current()) + { + std::cout + << "(" + << location.line() + << ':' + << location.column() + << ") "; + } + + int main() + { + // ↓: column #9 + pos(); std::cout << "Proxima\\n"; // row #18 + pos(); std::cout << "Centauri\\n"; // row #19 + // ↑: column #11 + } + +.SH Possible output: + + (18:9) Proxima + (19:11) Centauri + +.SH See also + + line return the line number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + Filename and line information diff --git a/man/std::source_location::current.3 b/man/std::source_location::current.3 new file mode 100644 index 000000000..7154836ed --- /dev/null +++ b/man/std::source_location::current.3 @@ -0,0 +1,104 @@ +.TH std::source_location::current 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location::current \- std::source_location::current + +.SH Synopsis + static consteval source_location current() noexcept; \fI(since C++20)\fP + + Constructs a new source_location object corresponding to the location of the call + site. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If current() is invoked directly (via a function call that names current()), it + returns a source_location object with implementation-defined values representing the + location of the call. The values should be affected by the #line preprocessor + directive in the same manner as the predefined macros __LINE__ and __FILE__. + + If current() is used in a default member initializer, the return value corresponds + to the location of the constructor definition or aggregate initialization that + initializes the data member. + + If current() is used in a default argument, the return value corresponds to the + location of the call to current() at the call site. + + If current() is invoked in any other manner, the return value is unspecified. + +.SH Notes + + std::source_location::current typically requires compiler's built-in implementation. + +.SH Example + + +// Run this code + + #include + #include + + struct src_rec { + std::source_location srcl = std::source_location::current(); + int dummy = 0; + + src_rec(std::source_location loc = std::source_location::current()) : + srcl(loc) // values of member refer to the location of the calling function + {} + src_rec(int i) : // values of member refer to this location + dummy(i) + {} + src_rec(double) // values of member refer to this location + {} + }; + + std::source_location src_clone(std::source_location a = std::source_location::current()) + { + return a; + } + + std::source_location src_make() + { + std::source_location b = std::source_location::current(); + return b; + } + + int main() + { + src_rec srec0; + src_rec srec1(0); + src_rec srec2(0.0); + auto s0 = std::source_location::current(); + auto s1 = src_clone(s0); + auto s2 = src_clone(); + auto s3 = src_make(); + + std::cout + << srec0.srcl.line() << ' ' << srec0.srcl.function_name() << '\\n' + << srec1.srcl.line() << ' ' << srec1.srcl.function_name() << '\\n' + << srec2.srcl.line() << ' ' << srec2.srcl.function_name() << '\\n' + << s0.line() << ' ' << s0.function_name() << '\\n' + << s1.line() << ' ' << s1.function_name() << '\\n' + << s2.line() << ' ' << s2.function_name() << '\\n' + << s3.line() << ' ' << s3.function_name() << '\\n'; + } + +.SH Possible output: + + 31 int main() + 12 src_rec::src_rec(int) + 15 src_rec::src_rec(double) + 34 int main() + 34 int main() + 36 int main() + 25 std::source_location src_make() + +.SH See also + + constructor constructs a new source_location with implementation-defined values + \fI(public member function)\fP + current obtains the current stacktrace or its given part + \fB[static]\fP \fI(public static member function of std::basic_stacktrace)\fP + diff --git a/man/std::source_location::file_name.3 b/man/std::source_location::file_name.3 new file mode 100644 index 000000000..22e961d4d --- /dev/null +++ b/man/std::source_location::file_name.3 @@ -0,0 +1,57 @@ +.TH std::source_location::file_name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location::file_name \- std::source_location::file_name + +.SH Synopsis + constexpr const char* file_name() const noexcept; \fI(since C++20)\fP + + Returns the name of the current source file represented by this object, represented + as a null-terminated byte string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The name of the current source file represented by this object, represented as a + null-terminated byte string. + +.SH Example + + +// Run this code + + #include + #include + + void print_this_file_name( + std::source_location location = std::source_location::current()) + { + // Name of file that contains the call site of this function. + std::cout << "File: " << location.file_name() << '\\n'; + } + + int main() + { + #line 1 "cppreference.cpp" + print_this_file_name(); + } + +.SH Output: + + File: cppreference.cpp + +.SH See also + + line return the line number represented by this object + \fI(public member function)\fP + column return the column number represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + gets the name of the source file that lexically contains the + source_file expression or statement whose evaluation is represented by the + (C++23) stacktrace_entry + \fI(public member function of std::stacktrace_entry)\fP + Filename and line information diff --git a/man/std::source_location::function_name.3 b/man/std::source_location::function_name.3 new file mode 100644 index 000000000..f61c6081d --- /dev/null +++ b/man/std::source_location::function_name.3 @@ -0,0 +1,89 @@ +.TH std::source_location::function_name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location::function_name \- std::source_location::function_name + +.SH Synopsis + constexpr const char* function_name() const noexcept; \fI(since C++20)\fP + + Returns the name of the function associated with the position represented by this + object, if any. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If this object represents a position in a body of a function, returns an + implementation-defined null-terminated byte string corresponding to the name of the + function. + + Otherwise, an empty string is returned. + +.SH Example + + std::source_location::function_name may help to obtain the names of functions + (including the special functions) alongside with their signatures. + + +// Run this code + + #include + #include + #include + + inline void print_function_name( + const std::source_location& location = std::source_location::current()) + { + std::puts(location.function_name()); // prints the name of the caller + } + + void foo(double &&) { print_function_name(); } + + namespace bar { void baz() { print_function_name(); } } + + template auto pub(T) { print_function_name(); return 42; } + + struct S { + S() { print_function_name(); } + S(int) { print_function_name(); } + ~S() { print_function_name(); } + S& operator=(S const&) { print_function_name(); return *this; } + S& operator=(S&&) { print_function_name(); return *this; } + }; + + int main(int, char const* const[]) + { + print_function_name(); + foo(3.14); + bar::baz(); + pub(0xFULL); + S p; + S q{42}; + p = q; + p = std::move(q); + [] { print_function_name(); }(); + } + +.SH Possible output: + + int main(int, const char* const*) + void foo(double&&) + void bar::baz() + auto pub(T) [with T = long long unsigned int] + S::S() + S::S(int) + S& S::operator=(const S&) + S& S::operator=(S&&) + main(int, const char* const*):: + S::~S() + S::~S() + +.SH See also + + line return the line number represented by this object + \fI(public member function)\fP + column return the column number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP diff --git a/man/std::source_location::line.3 b/man/std::source_location::line.3 new file mode 100644 index 000000000..4b02ba190 --- /dev/null +++ b/man/std::source_location::line.3 @@ -0,0 +1,65 @@ +.TH std::source_location::line 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location::line \- std::source_location::line + +.SH Synopsis + constexpr std::uint_least32_t line() const noexcept; \fI(since C++20)\fP + + Returns the line number represented by this object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The line number represented by this object. + + An implementation is encouraged to return 0 when the line number is unknown. + +.SH Example + + +// Run this code + + #include + #include + #include + + inline void cur_line( + const std::string_view message = "", + const std::source_location& location = std::source_location::current()) + { + std::cout + << location.line() // <- the line # of a call site + << ") " + << message; + } + + int main() + { + cur_line("++\\n"); + cur_line(); std::cout << "Hello,\\n"; + cur_line(); std::cout << "C++20!\\n"; + cur_line("--\\n"); + } + +.SH Output: + + 17) ++ + 18) Hello, + 19) C++20! + 20) -- + +.SH See also + + column return the column number represented by this object + \fI(public member function)\fP + file_name return the file name represented by this object + \fI(public member function)\fP + function_name return the name of the function represented by this object, if any + \fI(public member function)\fP + source_line gets the line number that lexically relates the evaluation represented + (C++23) by the stacktrace_entry + \fI(public member function of std::stacktrace_entry)\fP + Filename and line information diff --git a/man/std::source_location::source_location.3 b/man/std::source_location::source_location.3 new file mode 100644 index 000000000..24adbd99b --- /dev/null +++ b/man/std::source_location::source_location.3 @@ -0,0 +1,103 @@ +.TH std::source_location::source_location 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::source_location::source_location \- std::source_location::source_location + +.SH Synopsis + constexpr source_location() noexcept; \fB(1)\fP \fI(since C++20)\fP + source_location( const source_location& other ); \fB(2)\fP \fI(since C++20)\fP + source_location( source_location&& other ) noexcept; \fB(3)\fP \fI(since C++20)\fP + + 1) Constructs a source_location object of unspecified value. + 2,3) Copy and move constructors. It is unspecified whether they are trivial and/or + constexpr. + +.SH Parameters + + other - another source_location to copy or move from + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + // GCC specific type name printer + #if (__GNUG__ >= 11) + template + auto type_name_helper(const std::source_location s = std::source_location::current()) + { + using std::operator""sv; + const std::string_view fun_name{s.function_name()}; + constexpr auto prefix{"[with T = "sv}; + const auto type_name_begin{fun_name.find(prefix)}; + if (""sv.npos == type_name_begin) + return ""sv; + const std::size_t first{type_name_begin + prefix.length()}; + return std::string_view{fun_name.cbegin() + first, fun_name.cend() - 1}; + } + + template + auto type_name() { return type_name_helper(); } + #endif + + void print(std::string_view const comment, std::source_location const l) + { + std::cout << comment << ":\\n" + << " file_name : " << std::quoted(l.file_name()) << '\\n' + << " function_name : " << std::quoted(l.function_name()) << '\\n' + << " line : " << l.line() << '\\n' + << " column : " << l.column() << '\\n'; + } + + int main() + { + constexpr std::source_location default_constructed; + print("default constructed", default_constructed); + + constexpr std::source_location current = std::source_location::current(); + print("current", current); + + #if (__GNUG__ >= 11) + const std::vector> v{{1,2}, {3,4,5}, {6}}; + auto jv = std::ranges::join_view(v); + std::cout << '\\n' + << '[' << type_name() << "]\\n" + << '[' << type_name() << "]\\n" + << '[' << type_name() << "]\\n" + << '[' << type_name())>() << "]\\n" + << '[' << type_name() << "]\\n"; + #endif + } + +.SH Possible output: + + default constructed: + file_name : "" + function_name : "" + line : 0 + column : 0 + current: + file_name : "main.cpp" + function_name : "int main()" + line : 39 + column : 75 + + [int] + [double*] + [main()::] + [std::basic_string_view] + [std::ranges::join_view > > >] + +.SH See also + + current constructs a new source_location corresponding to the location of the + \fB[static]\fP call site + \fI(public static member function)\fP + constructor constructs a new stacktrace_entry + (C++23) \fI(public member function of std::stacktrace_entry)\fP diff --git a/man/std::span.3 b/man/std::span.3 new file mode 100644 index 000000000..5a2e9198d --- /dev/null +++ b/man/std::span.3 @@ -0,0 +1,254 @@ +.TH std::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span \- std::span + +.SH Synopsis + Defined in header + template< + + class T, \fI(since C++20)\fP + std::size_t Extent = std::dynamic_extent + + > class span; + + The class template span describes an object that can refer to a contiguous sequence + of objects with the first element of the sequence at position zero. A span can + either have a static extent, in which case the number of elements in the sequence is + known at compile-time and encoded in the type, or a dynamic extent. + + For a span s, pointers, iterators, and references to elements of s are invalidated + when an operation invalidates a pointer in the range [s.data(), s.data() + + s.size()). + + Every specialization of std::span is a TriviallyCopyable type. (since C++23) + + A typical implementation holds a pointer to T, if the extent is dynamic, the + implementation also holds a size. + +.SH Template parameters + + T - element type; must be a complete object type that is not an abstract class + type + Extent - the number of elements in the sequence, or std::dynamic_extent if dynamic + +.SH Member types + + Member type Definition + element_type T + value_type std::remove_cv_t + size_type std::size_t + difference_type std::ptrdiff_t + pointer T* + const_pointer const T* + reference T& + const_reference const T& + implementation-defined LegacyRandomAccessIterator, + iterator ConstexprIterator, and contiguous_iterator whose + value_type is value_type + const_iterator (since C++23) std::const_iterator + reverse_iterator std::reverse_iterator + const_reverse_iterator (since std::const_iterator + C++23) + + Note: iterator is a mutable iterator if T is not const-qualified. + + All requirements on the iterator types of a Container apply to the iterator type of + span as well. + + Member constant + + static constexpr std::size_t extent = Extent; \fI(since C++20)\fP + +.SH Member functions + + constructor constructs a span + \fI(public member function)\fP + operator= assigns a span + \fI(public member function)\fP + destructor destructs a span + (implicitly declared) \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + (C++23) + end returns an iterator to the end + cend \fI(public member function)\fP + (C++23) + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + (C++23) + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + (C++23) +.SH Element access + front access the first element + \fI(public member function)\fP + back access the last element + \fI(public member function)\fP + at access specified element with bounds checking + (C++26) \fI(public member function)\fP + operator[] access specified element + \fI(public member function)\fP + data direct access to the underlying contiguous storage + \fI(public member function)\fP +.SH Observers + size returns the number of elements + \fI(public member function)\fP + size_bytes returns the size of the sequence in bytes + \fI(public member function)\fP + empty checks if the sequence is empty + \fI(public member function)\fP + Subviews + obtains a subspan consisting of the first N elements of the + first sequence + \fI(public member function)\fP + obtains a subspan consisting of the last N elements of the + last sequence + \fI(public member function)\fP + subspan obtains a subspan + \fI(public member function)\fP + +.SH Non-member functions + + as_bytes converts a span into a view of its underlying bytes + as_writable_bytes \fI(function template)\fP + (C++20) + + Non-member constant + + dynamic_extent a constant of type std::size_t signifying that the span has dynamic + (C++20) extent + (constant) + + Helper templates + + template< class T, std::size_t Extent > + inline constexpr bool ranges::enable_borrowed_range> = true; + + This specialization of ranges::enable_borrowed_range makes span satisfy + borrowed_range. + + template< class T, std::size_t Extent > + inline constexpr bool ranges::enable_view> = \fI(since C++20)\fP + true; + + This specialization of ranges::enable_view makes span satisfy view. + + Deduction guides + +.SH Notes + + Specializations of std::span are already trivially copyable types in all existing + implementations, even before the formal requirement introduced in C++23. + + Feature-test macro Value Std Feature + __cpp_lib_span 202002L (C++20) std::span + 202311L (C++26) std::span::at + __cpp_lib_span_initializer_list 202311L (C++26) Constructing std::span from a + std::initializer_list + +.SH Example + + The example uses std::span to implement some algorithms on contiguous ranges. + + +// Run this code + + #include + #include + #include + #include + + template + [[nodiscard]] + constexpr auto slide(std::span s, std::size_t offset, std::size_t width) + { + return s.subspan(offset, offset + width <= s.size() ? width : 0U); + } + + template + constexpr bool starts_with(std::span data, std::span prefix) + { + return data.size() >= prefix.size() + && std::equal(prefix.begin(), prefix.end(), data.begin()); + } + + template + constexpr bool ends_with(std::span data, std::span suffix) + { + return data.size() >= suffix.size() + && std::equal(data.end() - suffix.size(), data.end(), + suffix.end() - suffix.size()); + } + + template + constexpr bool contains(std::span span, std::span sub) + { + return std::ranges::search(span, sub).begin() != span.end(); + } + + void println(const auto& seq) + { + for (const auto& elem : seq) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + constexpr int a[]{0, 1, 2, 3, 4, 5, 6, 7, 8}; + constexpr int b[]{8, 7, 6}; + constexpr static std::size_t width{6}; + + for (std::size_t offset{}; ; ++offset) + if (auto s = slide(std::span{a}, offset, width); !s.empty()) + println(s); + else + break; + + static_assert("" + && starts_with(std::span{a}, std::span{a, 4}) + && starts_with(std::span{a + 1, 4}, std::span{a + 1, 3}) + && !starts_with(std::span{a}, std::span{b}) + && !starts_with(std::span{a, 8}, std::span{a + 1, 3}) + && ends_with(std::span{a}, std::span{a + 6, 3}) + && !ends_with(std::span{a}, std::span{a + 6, 2}) + && contains(std::span{a}, std::span{a + 1, 4}) + && !contains(std::span{a, 8}, std::span{a, 9}) + ); + } + +.SH Output: + + 0 1 2 3 4 5 + 1 2 3 4 5 6 + 2 3 4 5 6 7 + 3 4 5 6 7 8 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear when the pointers, + LWG 3203 C++20 iterators, and made clear + references to elements of span are + invalidated + LWG 3903 C++20 the declaration of span's destructor was removed the declaration + unnucessary + P2325R3 C++20 a span of non-zero static extents was any span is a view + not a view + +.SH See also + + mdspan a multi-dimensional non-owning array view + (C++23) \fI(class template)\fP + ranges::subrange combines an iterator-sentinel pair into a view + (C++20) \fI(class template)\fP + initializer_list creates a temporary array in list-initialization and then + \fI(C++11)\fP references it + \fI(class template)\fP + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP diff --git a/man/std::span::at.3 b/man/std::span::at.3 new file mode 100644 index 000000000..090f0d411 --- /dev/null +++ b/man/std::span::at.3 @@ -0,0 +1,91 @@ +.TH std::span::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::at \- std::span::at + +.SH Synopsis + constexpr reference at( size_type pos ) const; (since C++26) + + Returns a reference to the element at specified location pos, with bounds checking. + + If pos is not within the range of the span, an exception of type std::out_of_range + is thrown. + +.SH Parameters + + pos - position of the element to return + +.SH Return value + + Reference to the requested element, i.e. *(data() + pos). + +.SH Exceptions + + std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_span 202311L (C++26) std::span::at + +.SH Example + + +// Run this code + + #include + #include + #include + + #ifdef __GNUG__ + [[gnu::noinline]] + #endif + unsigned int runtime_six() // Emulate runtime input + { + return 6u; + } + + int main() + { + int x[]{1, 2, 4, 5, 5, 6}; + std::span data(x); + + // Set element 1 + data.at(1) = 88; + + // Read element 2 + std::cout << "Element at index 2 has value " << data.at(2) << '\\n'; + + std::cout << "data size = " << data.size() << '\\n'; + + try + { + // Set element 6, where the index is determined at runtime + data.at(runtime_six()) = 666; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + + // Print final values + std::cout << "data:"; + for (int elem : data) + std::cout << ' ' << elem; + std::cout << '\\n'; + } + +.SH Possible output: + + Element at index 2 has value 4 + data size = 6 + std::out_of_range: pos >= size() + data: 1 88 4 5 5 6 + +.SH See also + + operator[] access specified element + \fI(public member function)\fP diff --git a/man/std::span::back.3 b/man/std::span::back.3 new file mode 100644 index 000000000..747994628 --- /dev/null +++ b/man/std::span::back.3 @@ -0,0 +1,65 @@ +.TH std::span::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::back \- std::span::back + +.SH Synopsis + constexpr reference back() const; \fI(since C++20)\fP + + Returns a reference to the last element in the span. + + Calling back on an empty span results in undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the back element. + +.SH Complexity + + Constant. + +.SH Notes + + For a span c, the expression c.back() is equivalent to *(c.end() - 1). + +.SH Example + + +// Run this code + + #include + #include + + void print_forward(std::span const span) + { + for (auto n{span.size()}; n != 0; --n) + std::cout << span.last(n).front() << ' '; + std::cout << '\\n'; + } + + void print_backward(std::span const span) + { + for (auto n{span.size()}; n != 0; --n) + std::cout << span.first(n).back() << ' '; + std::cout << '\\n'; + } + + int main() + { + constexpr int numbers[]{0, 1, 2, 3, 4}; + print_forward(numbers); + print_backward(numbers); + } + +.SH Output: + + 0 1 2 3 4 + 4 3 2 1 0 + +.SH See also + + front access the first element + \fI(public member function)\fP diff --git a/man/std::span::begin,std::span::cbegin.3 b/man/std::span::begin,std::span::cbegin.3 new file mode 100644 index 000000000..fc04d0902 --- /dev/null +++ b/man/std::span::begin,std::span::cbegin.3 @@ -0,0 +1,76 @@ +.TH std::span::begin,std::span::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::begin,std::span::cbegin \- std::span::begin,std::span::cbegin + +.SH Synopsis + constexpr iterator begin() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr const_iterator cbegin() const noexcept; \fB(2)\fP (since C++23) + + Returns an iterator to the first element of the span. + + If the span is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + void print(std::span array) + { + std::cout << "array = "; + for (auto it = array.begin(); it != array.end(); ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + } + + void set_first_element(std::span sp, int new_value) + { + if (!sp.empty()) + { + std::cout << "old *begin = " << *sp.begin() << '\\n'; + *sp.begin() = new_value; + std::cout << "new *begin = " << *sp.begin() << '\\n'; + } + } + + int main() + { + int array[]{1, 3, 4, 5}; + print(array); + set_first_element(array, 2); + print(array); + } + +.SH Output: + + array = 1 3 4 5 + old *begin = 1 + new *begin = 2 + array = 2 3 4 5 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + (C++23) + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::span::data.3 b/man/std::span::data.3 new file mode 100644 index 000000000..d660af152 --- /dev/null +++ b/man/std::span::data.3 @@ -0,0 +1,44 @@ +.TH std::span::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::data \- std::span::data + +.SH Synopsis + constexpr pointer data() const noexcept; \fI(since C++20)\fP + + Returns a pointer to the beginning of the sequence. + +.SH Return value + + A pointer to the beginning of the sequence. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr char str[] = "ABCDEF\\n"; + + const std::span sp{str}; + + for (auto n{sp.size()}; n != 2; --n) + std::cout << sp.last(n).data(); + } + +.SH Output: + + ABCDEF + BCDEF + CDEF + DEF + EF + F + +.SH See also + + constructor constructs a span + \fI(public member function)\fP diff --git a/man/std::span::empty.3 b/man/std::span::empty.3 new file mode 100644 index 000000000..ca1144a17 --- /dev/null +++ b/man/std::span::empty.3 @@ -0,0 +1,51 @@ +.TH std::span::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::empty \- std::span::empty + +.SH Synopsis + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the span is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the span is empty (i.e., size() == 0); false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::span span{"ABCDEF"}; + + while (!span.empty()) + { + std::cout << std::quoted(span.data()) << '\\n'; + span = span.last(span.size() - 1); + } + } + +.SH Output: + + "ABCDEF" + "BCDEF" + "CDEF" + "DEF" + "EF" + "F" + "" + +.SH See also + + size returns the number of elements in the sequence + (C++20) \fI(public member function)\fP diff --git a/man/std::span::end,std::span::cend.3 b/man/std::span::end,std::span::cend.3 new file mode 100644 index 000000000..089e8ddfa --- /dev/null +++ b/man/std::span::end,std::span::cend.3 @@ -0,0 +1,77 @@ +.TH std::span::end,std::span::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::end,std::span::cend \- std::span::end,std::span::cend + +.SH Synopsis + constexpr iterator end() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr const_iterator cend() const noexcept; \fB(2)\fP (since C++23) + + Returns an iterator to the element following the last element of the span. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + void print(std::span array) + { + std::cout << "array = "; + for (auto it = array.begin(); it != array.end(); ++it) + std::cout << *it << ' '; + std::cout << '\\n'; + } + + void set_first_element(std::span sp, int new_value) + { + if (!sp.empty()) + { + std::cout << "old *begin = " << *sp.begin() << '\\n'; + *sp.begin() = new_value; + std::cout << "new *begin = " << *sp.begin() << '\\n'; + } + } + + int main() + { + int array[]{1, 3, 4, 5}; + print(array); + set_first_element(array, 2); + print(array); + } + +.SH Output: + + array = 1 3 4 5 + old *begin = 1 + new *begin = 2 + array = 2 3 4 5 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + (C++23) + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::span::first.3 b/man/std::span::first.3 new file mode 100644 index 000000000..d639a2842 --- /dev/null +++ b/man/std::span::first.3 @@ -0,0 +1,70 @@ +.TH std::span::first 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::first \- std::span::first + +.SH Synopsis + template< std::size_t Count > \fI(since C++20)\fP + constexpr std::span first() const; + constexpr std::span first( \fI(since C++20)\fP + size_type Count ) const; + + Obtains a span that is a view over the first Count elements of this span. The + program is ill-formed if Count > Extent. The behavior is undefined if Count > + size(). + +.SH Return value + + A span r that is a view over the first Count elements of *this, such that r.data() + == this->data() && r.size() == Count. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view const title, + std::ranges::forward_range auto const& container) + { + auto size{std::size(container)}; + std::cout << title << '[' << size << "]{"; + for (auto const& elem : container) + std::cout << elem << (--size ? ", " : ""); + std::cout << "};\\n"; + } + + void run_game(std::span span) + { + print("span: ", span); + + std::span span_first = span.first<5>(); + print("span.first<5>(): ", span_first); + + std::span span_first_dynamic = span.first(4); + print("span.first(4): ", span_first_dynamic); + } + + int main() + { + int a[8]{1, 2, 3, 4, 5, 6, 7, 8}; + print("int a", a); + run_game(a); + } + +.SH Output: + + int a[8]{1, 2, 3, 4, 5, 6, 7, 8}; + span: [8]{1, 2, 3, 4, 5, 6, 7, 8}; + span.first<5>(): [5]{1, 2, 3, 4, 5}; + span.first\fB(4)\fP: [4]{1, 2, 3, 4}; + +.SH See also + + last obtains a subspan consisting of the last N elements of the sequence + \fI(public member function)\fP + subspan obtains a subspan + \fI(public member function)\fP diff --git a/man/std::span::front.3 b/man/std::span::front.3 new file mode 100644 index 000000000..dac9de5fe --- /dev/null +++ b/man/std::span::front.3 @@ -0,0 +1,56 @@ +.TH std::span::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::front \- std::span::front + +.SH Synopsis + constexpr reference front() const; \fI(since C++20)\fP + + Returns a reference to the first element in the span. + + Calling front on an empty span results in undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + For a span c, the expression c.front() is equivalent to *c.begin(). + +.SH Example + + +// Run this code + + #include + #include + + void print(std::span const data) + { + for (auto offset{0U}; offset != data.size(); ++offset) + std::cout << data.subspan(offset).front() << ' '; + std::cout << '\\n'; + } + + int main() + { + constexpr int data[]{0, 1, 2, 3, 4, 5, 6}; + print({data, 4}); + } + +.SH Output: + + 0 1 2 3 + +.SH See also + + back access the last element + \fI(public member function)\fP diff --git a/man/std::span::last.3 b/man/std::span::last.3 new file mode 100644 index 000000000..641a52b22 --- /dev/null +++ b/man/std::span::last.3 @@ -0,0 +1,66 @@ +.TH std::span::last 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::last \- std::span::last + +.SH Synopsis + template< std::size_t Count > \fB(1)\fP \fI(since C++20)\fP + constexpr std::span last() const; + constexpr std::span last( \fB(2)\fP \fI(since C++20)\fP + size_type Count ) const; + + Obtains a span that is a view over the last Count elements of this span. The program + is ill-formed if Count > Extent. The behavior is undefined if Count > size(). + +.SH Return value + + A span r that is a view over the last Count elements of *this, such that r.data() == + this->data() + (this->size() - Count) && r.size() == Count. + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(std::string_view const title, auto const& container) + { + std::cout << title << '[' << std::size(container) << "]{ "; + for (auto const& elem : container) + std::cout << elem << ", "; + std::cout << "};\\n"; + }; + + void run(std::span span) + { + println("span: ", span); + + std::span span_last = span.last<3>(); + println("span.last<3>(): ", span_last); + + std::span span_last_dynamic = span.last(2); + println("span.last(2): ", span_last_dynamic); + } + + int main() + { + int a[8]{1, 2, 3, 4, 5, 6, 7, 8}; + println("int a", a); + run(a); + } + +.SH Output: + + int a[8]{ 1, 2, 3, 4, 5, 6, 7, 8, }; + span: [8]{ 1, 2, 3, 4, 5, 6, 7, 8, }; + span.last<3>(): [3]{ 6, 7, 8, }; + span.last\fB(2)\fP: [2]{ 7, 8, }; + +.SH See also + + first obtains a subspan consisting of the first N elements of the sequence + \fI(public member function)\fP + subspan obtains a subspan + \fI(public member function)\fP diff --git a/man/std::span::operator=.3 b/man/std::span::operator=.3 new file mode 100644 index 000000000..9e6c2a5b7 --- /dev/null +++ b/man/std::span::operator=.3 @@ -0,0 +1,134 @@ +.TH std::span::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::operator= \- std::span::operator= + +.SH Synopsis + constexpr span& operator=( const span& other ) noexcept = default; \fI(since C++20)\fP + + Assigns other to *this. This defaulted assignment operator performs a shallow copy + of the data pointer and the size, i.e., after a call to this function, data() == + other.data() and size() == other.size(). + +.SH Parameters + + other - another span to copy from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + void print(std::string_view info = "", std::span span = {}, + std::size_t extent = 0, std::size_t size_of = 0) + { + if (span.empty()) + { + std::cout << info << '\\n'; + return; + } + + std::cout << info << '[' << span.size() << "] {"; + std::ranges::for_each(span, [](const int x) { std::cout << ' ' << x; }); + std::cout << " }"; + + if (extent) + { + std::cout << " extent = "; + if (extent == std::dynamic_extent) + std::cout << "dynamic"; + else + std::cout << extent; + } + + if (size_of) + std::cout << ", sizeof = " << size_of; + + std::cout << '\\n'; + } + + int main() + { + std::array a1; + std::array a2; + a1.fill(3); + a2.fill(4); + + auto s1 = std::span(a1); + auto s2 = std::span(a2); + print("s1", s1, s1.extent, sizeof(s1)); + print("s2", s2, s2.extent, sizeof(s2)); + + // Check that assignment performs a shallow copy. + s1 = s2; + (s1.data() == s2.data() && s1.size() == s2.size()) + ? print("s1 = s2; is a shallow copy!") + : print("s1 = s2; is a deep copy!"); + print("s1", s1); + + print("Fill s1 with 5:"); + std::ranges::fill(s1, 5); + // s2 is also 'updated' since s1 and s2 point to the same data + assert(std::ranges::equal(s1, s2)); + print("s1", s1); + print("s2", s2); + print(); + + int a3[]{1, 2, 3, 4}; + int a4[]{2, 3, 4, 5}; + int a5[]{3, 4, 5}; + + std::span dynamic_1{a3}; + std::span dynamic_2{a4, 3}; + std::span static_1{a3}; + std::span static_2{a4}; + std::span static_3{a5}; + + print("dynamic_1", dynamic_1, dynamic_1.extent, sizeof(dynamic_1)); + print("dynamic_2", dynamic_2, dynamic_2.extent, sizeof(dynamic_2)); + print("static_1", static_1, static_1.extent, sizeof(static_1)); + print("static_2", static_2, static_2.extent, sizeof(static_2)); + print("static_3", static_3, static_3.extent, sizeof(static_3)); + + dynamic_1 = dynamic_2; // OK + dynamic_1 = static_1; // OK + // static_1 = dynamic_1; // ERROR: no match for ‘operator=’ + static_1 = static_2; // OK: same extents = 4 + // static_1 = static_3; // ERROR: different extents: 4 and 3 + } + +.SH Output: + + s1[6] { 3 3 3 3 3 3 } extent = 6, sizeof = 8 + s2[6] { 4 4 4 4 4 4 } extent = 6, sizeof = 8 + s1 = s2; is a shallow copy! + s1[6] { 4 4 4 4 4 4 } + Fill s1 with 5: + s1[6] { 5 5 5 5 5 5 } + s2[6] { 5 5 5 5 5 5 } + + dynamic_1[4] { 1 2 3 4 } extent = dynamic, sizeof = 16 + dynamic_2[3] { 2 3 4 } extent = dynamic, sizeof = 16 + static_1[4] { 1 2 3 4 } extent = 4, sizeof = 8 + static_2[4] { 2 3 4 5 } extent = 4, sizeof = 8 + static_3[3] { 3 4 5 } extent = 3, sizeof = 8 + +.SH See also + + constructor constructs the span + \fI(public member function)\fP + data direct access to the underlying contiguous storage + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP diff --git a/man/std::span::operator[].3 b/man/std::span::operator[].3 new file mode 100644 index 000000000..92ace8824 --- /dev/null +++ b/man/std::span::operator[].3 @@ -0,0 +1,72 @@ +.TH std::span::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::operator[] \- std::span::operator[] + +.SH Synopsis + constexpr reference operator[]( size_type idx ) const; \fI(since C++20)\fP + + Returns a reference to the idx^th element of the sequence. The behavior is undefined + if idx is out of range (i.e., if it is greater than or equal to size()). + +.SH Parameters + + idx - the index of the element to access + +.SH Return value + + A reference to the idx^th element of the sequence, i.e., data()[idx]. + +.SH Exceptions + + Throws nothing. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void reverse(std::span span) + { + for (std::size_t i = 0, j = std::size(span); i < j; ++i) + { + --j; + std::swap(span[i], span[j]); + } + } + + void print(std::span const span) + { + for (int element : span) + std::cout << element << ' '; + std::cout << '\\n'; + } + + int main() + { + int data[]{1, 2, 3, 4, 5}; + print(data); + reverse(data); + print(data); + } + +.SH Output: + + 1 2 3 4 5 + 5 4 3 2 1 + +.SH See also + + at access specified element with bounds checking + (C++26) \fI(public member function)\fP + data direct access to the underlying contiguous storage + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + as_bytes converts a span into a view of its underlying bytes + as_writable_bytes \fI(function template)\fP + (C++20) diff --git a/man/std::span::rbegin,std::span::crbegin.3 b/man/std::span::rbegin,std::span::crbegin.3 new file mode 100644 index 000000000..f6e804e75 --- /dev/null +++ b/man/std::span::rbegin,std::span::crbegin.3 @@ -0,0 +1,65 @@ +.TH std::span::rbegin,std::span::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::rbegin,std::span::crbegin \- std::span::rbegin,std::span::crbegin + +.SH Synopsis + constexpr reverse_iterator rbegin() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr const_reverse_iterator crbegin() const noexcept; \fB(2)\fP (since C++23) + + Returns a reverse iterator to the first element of the reversed span. It corresponds + to the last element of the non-reversed span. If the span is empty, the returned + iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + constexpr std::span code{"@droNE_T0P_w$s@s#_SECRET_a,p^42!"}; + + auto hack = [](const unsigned O) { return O - 0141 < 120; }; + + std::copy_if(code.rbegin(), code.rend(), + std::ostream_iterator(std::cout), hack); + + std::cout << '\\n'; + } + +.SH Output: + + password + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + (C++23) + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::span::rend,std::span::crend.3 b/man/std::span::rend,std::span::crend.3 new file mode 100644 index 000000000..09d01ed92 --- /dev/null +++ b/man/std::span::rend,std::span::crend.3 @@ -0,0 +1,72 @@ +.TH std::span::rend,std::span::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::rend,std::span::crend \- std::span::rend,std::span::crend + +.SH Synopsis + constexpr reverse_iterator rend() const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr const_reverse_iterator crend() const noexcept; \fB(2)\fP (since C++23) + + Returns a reverse iterator to the element following the last element of the reversed + span. It corresponds to the element preceding the first element of the non-reversed + span. This element acts as a placeholder, attempting to access it results in + undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void ascending(const std::span data, + const std::string_view term) + { + std::for_each(data.begin(), data.end(), + [](const std::string_view x) { std::cout << x << ' '; }); + std::cout << term; + } + + void descending(const std::span data, + const std::string_view term) + { + std::for_each(data.rbegin(), data.rend(), + [](const std::string_view x) { std::cout << x << ' '; }); + std::cout << term; + } + + int main() + { + constexpr std::string_view bars[]{"▁","▂","▃","▄","▅","▆","▇","█"}; + ascending(bars, " "); + descending(bars, "\\n"); + } + +.SH Output: + + ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ █ ▇ ▆ ▅ ▄ ▃ ▂ ▁ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + (C++23) + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::span::size.3 b/man/std::span::size.3 new file mode 100644 index 000000000..19f988bfe --- /dev/null +++ b/man/std::span::size.3 @@ -0,0 +1,59 @@ +.TH std::span::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::size \- std::span::size + +.SH Synopsis + constexpr size_type size() const noexcept; \fI(since C++20)\fP + + Returns the number of elements in the span. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of elements in the span. + +.SH Note + + Feature-test macro Value Std Feature + __cpp_lib_ssize 201902L (C++20) std::ssize and unsigned std::span::size + +.SH Example + + +// Run this code + + #include + #include + + void show_sizes(std::span span) + { + std::cout + << span .size() << ' ' // 8 + << span.first(7) .size() << ' ' // 7 + << span.first<6>() .size() << ' ' // 6 + << span.last(5) .size() << ' ' // 5 + << span.last<4>() .size() << ' ' // 4 + << span.subspan(2, 3) .size() << ' ' // 3 + << span.subspan<3, 2>() .size() << ' ' // 2 + << '\\n'; + } + + int main() + { + int antique_array[]{1, 2, 3, 4, 5, 6, 7, 8}; + show_sizes(antique_array); + } + +.SH Output: + + 8 7 6 5 4 3 2 + +.SH See also + + constructor constructs a span + \fI(public member function)\fP + size_bytes returns the size of the sequence in bytes + \fI(public member function)\fP diff --git a/man/std::span::size_bytes.3 b/man/std::span::size_bytes.3 new file mode 100644 index 000000000..d047c1026 --- /dev/null +++ b/man/std::span::size_bytes.3 @@ -0,0 +1,44 @@ +.TH std::span::size_bytes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::size_bytes \- std::span::size_bytes + +.SH Synopsis + constexpr size_type size_bytes() const noexcept; \fI(since C++20)\fP + + Returns the size of the sequence in bytes. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The size of the sequence in bytes, i.e., size() * sizeof(element_type). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr static std::int32_t a[]{1, 2, 3, 4, 5}; + constexpr static std::span s{a}; + + static_assert + ( + sizeof(int32_t) == 4 && + std::size(a) == 5 && + sizeof a == 20 && + s.size() == 5 && + s.size_bytes() == 20 + ); + } + +.SH See also + + size returns the number of elements in the sequence + (C++20) \fI(public member function)\fP diff --git a/man/std::span::span.3 b/man/std::span::span.3 new file mode 100644 index 000000000..0fae803a4 --- /dev/null +++ b/man/std::span::span.3 @@ -0,0 +1,181 @@ +.TH std::span::span 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::span \- std::span::span + +.SH Synopsis + constexpr span() noexcept; \fB(1)\fP \fI(since C++20)\fP + template< class It > + + explicit(extent != std::dynamic_extent) \fB(2)\fP \fI(since C++20)\fP + + constexpr span( It first, size_type count ); + template< class It, class End > + + explicit(extent != std::dynamic_extent) \fB(3)\fP \fI(since C++20)\fP + + constexpr span( It first, End last ); + template< std::size_t N > + constexpr span( std::type_identity_t (&arr)[N] ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + template< class U, std::size_t N > \fB(5)\fP \fI(since C++20)\fP + constexpr span( std::array& arr ) noexcept; + template< class U, std::size_t N > \fB(6)\fP \fI(since C++20)\fP + constexpr span( const std::array& arr ) noexcept; + template< class R > + + explicit(extent != std::dynamic_extent) \fB(7)\fP \fI(since C++20)\fP + + constexpr span( R&& range ); + explicit(extent != std::dynamic_extent) \fB(8)\fP (since C++26) + constexpr span( std::initializer_list il ) noexcept; + template< class U, std::size_t N > + + explicit(extent != std::dynamic_extent && N == \fB(9)\fP \fI(since C++20)\fP + std::dynamic_extent) + + constexpr span( const std::span& source ) noexcept; + constexpr span( const span& other ) noexcept = default; \fB(10)\fP \fI(since C++20)\fP + + Constructs a span. + + 1) Constructs an empty span whose data() == nullptr and size() == 0. + * This overload participates in overload resolution only if extent == 0 || extent + == std::dynamic_extent. + 2) Constructs a span that is a view over the range [first, first + count); the + resulting span has data() == std::to_address(first) and size() == count. + * The behavior is undefined if [first, first + count) is not a valid range, if It + does not actually model contiguous_iterator, or if extent != std::dynamic_extent + && count != extent. + * This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * the conversion from std::iter_reference_t to element_type is at most a + qualification conversion. + 3) Constructs a span that is a view over the range [first, last); the resulting span + has data() == std::to_address(first) and size() == last-first. + * The behavior is undefined if [first, last) is not a valid range, if It does not + actually model contiguous_iterator, if End does not actually model + sized_sentinel_for for It, or if extent != std::dynamic_extent && last-first != + extent. + * This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * the conversion from std::iter_reference_t to element_type is at most a + qualification conversion, and + * std::is_convertible_v is false. + 4-6) Constructs a span that is a view over the array arr; the resulting span has + size() == N and data() == std::data(arr). + * These overloads participate in overload resolution only if extent == + std::dynamic_extent || N == extent is true and the conversion from + std::remove_pointer_t to element_type is at most a + qualification conversion. + 7) Constructs a span that is a view over the range range; the resulting span has + size() == std::ranges::size(range) and data() == std::ranges::data(range). + * The behavior is undefined if R does not actually model contiguous_range and + sized_range or if R does not model borrowed_range while element_type is + non-const or both extent != dynamic_extent and std::ranges::size(range) != + extent are true. + * This overload participates in overload resolution only if + + * R satisfies contiguous_range and sized_range, + * either R satisfies borrowed_range or std::is_const_v is true, + * std::remove_cvref_t is not a specialization of std::span, + * std::remove_cvref_t is not a specialization of std::array, + * std::is_array_v> is false, and + * the conversion from std::ranges::range_reference_t to element_type is at most + a qualification conversion. + 8) Constructs a span that is a view over the initializer list il; the resulting span + has size() == il.size() and data() == il.begin(). + * The behavior is undefined if both extent != dynamic_extent and il.size() != + extent are true. + * This overload participates in overload resolution only if + std::is_const_v is true. + 9) Converting constructor from another span source; the resulting span has size() == + source.size() and data() == source.data(). + * The behavior is undefined if both extent != dynamic_extent and source.size() != + extent are true. + * This overload participates in overload resolution only if at least one of extent + == std::dynamic_extent, N == std::dynamic_extent and N == extent is true and the + conversion from U to element_type is at most a qualification conversion. + 10) Defaulted copy constructor copies the size and data pointer; the resulting span + has size() == other.size() and data() == other.data(). + +.SH Parameters + + first - iterator to the first element of the sequence + count - number of elements in the sequence + last - iterator past the last element of the sequence or another sentinel + arr - array to construct a view for + range - range to construct a view for + source - another span to convert from + other - another span to copy from + +.SH Exceptions + + 2) Throws nothing. + 3) Throws what and when last - first throws. + 7) Throws what and when std::ranges::size(r) and std::ranges::data(r) throw. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_span_initializer_list 202311L (C++26) Constructing std::span from a + std::initializer_list, \fB(8)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print_span(std::span s) + { + for (int n : s) + std::cout << n << ' '; + std::cout << '\\n'; + } + + int main() + { + int c[]{1, 2, 3}; + print_span(c); // constructs from array + + std::array a{4, 5, 6}; + print_span(a); // constructs from std::array + + std::vector v{7, 8, 9}; + print_span(v); // constructs from std::vector + + #if __cpp_lib_span_initializer_list + print_span({0, 1, 2}); // constructs from initializer_list + #else + print_span({{0, 1, 2}}); // ditto, a workaround + #endif + } + +.SH Output: + + 1 2 3 + 4 5 6 + 7 8 9 + 0 1 2 + +.SH See also + + data direct access to the underlying contiguous storage + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + operator= assigns a span + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::span::subspan.3 b/man/std::span::subspan.3 new file mode 100644 index 000000000..d85ffcf2c --- /dev/null +++ b/man/std::span::subspan.3 @@ -0,0 +1,87 @@ +.TH std::span::subspan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::span::subspan \- std::span::subspan + +.SH Synopsis + template< std::size_t Offset, + + std::size_t Count = std::dynamic_extent > \fB(1)\fP \fI(since C++20)\fP + constexpr std::span + + subspan() const; + constexpr std::span + + subspan( size_type Offset, \fB(2)\fP \fI(since C++20)\fP + + size_type Count = std::dynamic_extent ) const; + + Obtains a span that is a view over the Count elements of this span starting at + offset Offset. If Count is std::dynamic_extent, the number of elements in the + subspan is size() - offset (i.e., it ends at the end of *this). + + 1) Is ill-formed if + * Offset is greater than Extent, or + * Count is not std::dynamic_extent and Count is greater than Extent - Offset. + + The behavior is undefined if either Offset or Count is out of range. This happens if + + * Offset is greater than size(), or + * Count is not std::dynamic_extent and Count is greater than size() - Offset. + + The extent E of the span returned by \fB(1)\fP is determined as follows: + + * If Count is not std::dynamic_extent, Count; + * Otherwise, if Extent is not std::dynamic_extent, Extent - Offset; + * Otherwise, std::dynamic_extent. + +.SH Return value + + The requested subspan r, such that r.data() == this->data() + Offset. If Count is + std::dynamic_extent, r.size() == this->size() - Offset; otherwise r.size() == Count. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void display(std::span abc) + { + const auto columns{20U}; + const auto rows{abc.size() - columns + 1}; + + for (auto offset{0U}; offset < rows; ++offset) + { + std::ranges::for_each(abc.subspan(offset, columns), std::putchar); + std::putchar('\\n'); + } + } + + int main() + { + char abc[26]; + std::iota(std::begin(abc), std::end(abc), 'A'); + display(abc); + } + +.SH Output: + + ABCDEFGHIJKLMNOPQRST + BCDEFGHIJKLMNOPQRSTU + CDEFGHIJKLMNOPQRSTUV + DEFGHIJKLMNOPQRSTUVW + EFGHIJKLMNOPQRSTUVWX + FGHIJKLMNOPQRSTUVWXY + GHIJKLMNOPQRSTUVWXYZ + +.SH See also + + first obtains a subspan consisting of the first N elements of the sequence + \fI(public member function)\fP + last obtains a subspan consisting of the last N elements of the sequence + \fI(public member function)\fP diff --git a/man/std::sph_bessel,std::sph_besself,std::sph_bessell.3 b/man/std::sph_bessel,std::sph_besself,std::sph_bessell.3 new file mode 100644 index 000000000..d6ed096bb --- /dev/null +++ b/man/std::sph_bessel,std::sph_besself,std::sph_bessell.3 @@ -0,0 +1,109 @@ +.TH std::sph_bessel,std::sph_besself,std::sph_bessell 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sph_bessel,std::sph_besself,std::sph_bessell \- std::sph_bessel,std::sph_besself,std::sph_bessell + +.SH Synopsis + Defined in header + float sph_bessel ( unsigned int n, float x ); + \fI(since C++17)\fP + double sph_bessel ( unsigned int n, double x ); (until C++23) + + long double sph_bessel ( unsigned int n, long double x ); + /* floating-point-type */ sph_bessel( unsigned int n, + /* floating-point-type \fB(1)\fP (since C++23) + */ x ); + float sph_besself( unsigned int n, float x ); \fB(2)\fP \fI(since C++17)\fP + long double sph_bessell( unsigned int n, long double x ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++17)\fP + double sph_bessel ( unsigned int n, Integer x ); + + 1-3) Computes the spherical Bessel function of the first kind of n and x. + The library provides overloads of std::sph_bessel for all cv-unqualified + floating-point types as the type of the parameter x. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. + +.SH Parameters + + n - the order of the function + x - the argument of the function + +.SH Return value + + If no errors occur, returns the value of the spherical Bessel function of the first + kind of n and x, that is j + n(x) = (π/2x)1/2 + J + n+1/2(x) where J + n(x) is std::cyl_bessel_j(n, x) and x≥0. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If n≥128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::sph_bessel(int_num, num) has the same effect as std::sph_bessel(int_num, + static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // spot check for n == 1 + double x = 1.2345; + std::cout << "j_1(" << x << ") = " << std::sph_bessel(1, x) << '\\n'; + + // exact solution for j_1 + std::cout << "sin(x)/x² - cos(x)/x = " + << std::sin(x) / (x * x) - std::cos(x) / x << '\\n'; + } + +.SH Output: + + j_1(1.2345) = 0.352106 + sin(x)/x² - cos(x)/x = 0.352106 + +.SH See also + + cyl_bessel_j + cyl_bessel_jf + cyl_bessel_jl cylindrical Bessel functions (of the first kind) + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + sph_neumann + sph_neumannf + sph_neumannl spherical Neumann functions + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Spherical Bessel Function of the First Kind." From MathWorld — A + Wolfram Web Resource. diff --git a/man/std::sph_legendre,std::sph_legendref,std::sph_legendrel.3 b/man/std::sph_legendre,std::sph_legendref,std::sph_legendrel.3 new file mode 100644 index 000000000..81014b4c0 --- /dev/null +++ b/man/std::sph_legendre,std::sph_legendref,std::sph_legendrel.3 @@ -0,0 +1,127 @@ +.TH std::sph_legendre,std::sph_legendref,std::sph_legendrel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sph_legendre,std::sph_legendref,std::sph_legendrel \- std::sph_legendre,std::sph_legendref,std::sph_legendrel + +.SH Synopsis + Defined in header + float sph_legendre ( unsigned l, unsigned m, float theta + ); + + double sph_legendre ( unsigned l, unsigned m, double \fI(since C++17)\fP + theta ); (until C++23) + + long double sph_legendre ( unsigned l, unsigned m, long double + theta ); + /* floating-point-type */ sph_legendre( unsigned l, unsigned + m, (since C++23) + /* floating-point-type \fB(1)\fP + */ theta ); + float sph_legendref( unsigned l, unsigned m, float theta \fB(2)\fP \fI(since C++17)\fP + ); + long double sph_legendrel( unsigned l, unsigned m, long double \fB(3)\fP \fI(since C++17)\fP + theta ); + Additional overloads + Defined in header + template< class Integer > + double sph_legendre ( unsigned l, unsigned m, Integer (A) \fI(since C++17)\fP + theta ); + + 1-3) Computes the spherical associated Legendre function of degree l, order m, and + polar angle theta. + The library provides overloads of std::sph_legendre for all cv-unqualified + floating-point types as the type of the parameter theta. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. + +.SH Parameters + + l - degree + m - order + theta - polar angle, measured in radians + +.SH Return value + + If no errors occur, returns the value of the spherical associated Legendre function + (that is, spherical harmonic with ϕ = 0) of l, m, and theta, where the spherical + harmonic function is defined as Ym + l(theta,ϕ) = (-1)m + [ + + (2l+1)(l-m)! + 4π(l+m)! + + ]1/2 + Pm + l(cos(theta))eimϕ + where Pm + l(x) is std::assoc_legendre(l, m, x)) and |m|≤l. + + Note that the Condon-Shortley phase term (-1)m + is included in this definition because it is omitted from the definition of Pm + l in std::assoc_legendre. + +.SH Error handling + + Errors may be reported as specified in math_errhandling. + + * If the argument is NaN, NaN is returned and domain error is not reported. + * If l≥128, the behavior is implementation-defined. + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of the spherical harmonic function is available in boost.math, and + it reduces to this function when called with the parameter phi set to zero. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::sph_legendre(int_num1, int_num2, num) has the same effect as + std::sph_legendre(int_num1, int_num2, static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // spot check for l=3, m=0 + double x = 1.2345; + std::cout << "Y_3^0(" << x << ") = " << std::sph_legendre(3, 0, x) << '\\n'; + + // exact solution + std::cout << "exact solution = " + << 0.25 * std::sqrt(7 / std::numbers::pi) + * (5 * std::pow(std::cos(x), 3) - 3 * std::cos(x)) + << '\\n'; + } + +.SH Output: + + Y_3^0(1.2345) = -0.302387 + exact solution = -0.302387 + +.SH See also + + assoc_legendre + assoc_legendref + assoc_legendrel associated Legendre polynomials + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Spherical Harmonic." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::sph_neumann,std::sph_neumannf,std::sph_neumannl.3 b/man/std::sph_neumann,std::sph_neumannf,std::sph_neumannl.3 new file mode 100644 index 000000000..00178043f --- /dev/null +++ b/man/std::sph_neumann,std::sph_neumannf,std::sph_neumannl.3 @@ -0,0 +1,110 @@ +.TH std::sph_neumann,std::sph_neumannf,std::sph_neumannl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sph_neumann,std::sph_neumannf,std::sph_neumannl \- std::sph_neumann,std::sph_neumannf,std::sph_neumannl + +.SH Synopsis + Defined in header + float sph_neumann ( unsigned n, float x ); + \fI(since C++17)\fP + double sph_neumann ( unsigned n, double x ); (until C++23) + + long double sph_neumann ( unsigned n, long double x ); + /* floating-point-type */ sph_neumann( unsigned n, + /* floating-point-type \fB(1)\fP (since C++23) + */ x ); + float sph_neumannf( unsigned n, float x ); \fB(2)\fP \fI(since C++17)\fP + long double sph_neumannl( unsigned n, long double x ); \fB(3)\fP \fI(since C++17)\fP + Additional overloads + Defined in header + template< class Integer > (A) \fI(since C++17)\fP + double sph_neumann ( unsigned n, Integer x ); + + 1-3) Computes the spherical Bessel function of the second kind, also known as the + spherical Neumann function, of n and x. + The library provides overloads of std::sph_neumann for all cv-unqualified + floating-point types as the type of the parameter x. + (since C++23) + A) Additional overloads are provided for all integer types, which are treated as + double. + +.SH Parameters + + n - the order of the function + x - the argument of the function + +.SH Return value + + If no errors occur, returns the value of the spherical Bessel function of the second + kind (spherical Neumann function) of n and x, that is n + n(x) = (π/2x)1/2 + N + n+1/2(x) where N + n(x) is std::cyl_neumann(n, x) and x≥0. + +.SH Error handling + + Errors may be reported as specified in math_errhandling + + * If the argument is NaN, NaN is returned and domain error is not reported + * If n≥128, the behavior is implementation-defined + +.SH Notes + + Implementations that do not support C++17, but support ISO 29124:2010, provide this + function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value + at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before + including any standard library headers. + + Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), + provide this function in the header tr1/cmath and namespace std::tr1. + + An implementation of this function is also available in boost.math. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::sph_neumann(int_num, num) has the same effect as std::sph_neumann(int_num, + static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // spot check for n == 1 + double x = 1.2345; + std::cout << "n_1(" << x << ") = " << std::sph_neumann(1, x) << '\\n'; + + // exact solution for n_1 + std::cout << "-cos(x)/x² - sin(x)/x = " + << -std::cos(x) / (x * x) - std::sin(x) / x << '\\n'; + } + +.SH Output: + + n_1(1.2345) = -0.981201 + -cos(x)/x² - sin(x)/x = -0.981201 + +.SH See also + + cyl_neumann + cyl_neumannf + cyl_neumannl cylindrical Neumann functions + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + sph_bessel + sph_besself + sph_bessell spherical Bessel functions (of the first kind) + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + +.SH External links + + Weisstein, Eric W. "Spherical Bessel Function of the Second Kind." From MathWorld — + A Wolfram Web Resource. diff --git a/man/std::sqrt(std::complex).3 b/man/std::sqrt(std::complex).3 index 8f4d551c1..4793492ed 100644 --- a/man/std::sqrt(std::complex).3 +++ b/man/std::sqrt(std::complex).3 @@ -1,24 +1,91 @@ -.TH std::sqrt(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sqrt(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sqrt(std::complex) \- std::sqrt(std::complex) + .SH Synopsis Defined in header template< class T > - complex sqrt( const complex& x ); - - Computes the square root of the complex number x. + std::complex sqrt( const std::complex& z ); - The branch cuts are along the negative real axis. sqrt computes the square root in - the range of the right half-plane. If x is a negative real number, the return value - will lie on the positive imaginary axis. + Computes the square root of the complex number z with a branch cut along the + negative real axis. .SH Parameters - x - complex number to take the square root of + z - complex number to take the square root of .SH Return value - the square root of x. + If no errors occur, returns the square root of z, in the range of the right + half-plane, including the imaginary axis ([0; +∞) along the real axis and (−∞; +∞) + along the imaginary axis). + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * The function is continuous onto the branch cut taking into account the sign of + imaginary part + * std::sqrt(std::conj(z)) == std::conj(std::sqrt(z)) + * If z is (±0,+0), the result is (+0,+0) + * If z is (x,+∞), the result is (+∞,+∞) even if x is NaN + * If z is (x,NaN), the result is (NaN,NaN) (unless x is ±∞) and FE_INVALID may be + raised + * If z is (-∞,y), the result is (+0,+∞) for finite positive y + * If z is (+∞,y), the result is (+∞,+0) for finite positive y + * If z is (-∞,NaN), the result is (NaN,∞) (sign of imaginary part unspecified) + * If z is (+∞,NaN), the result is (+∞,NaN) + * If z is (NaN,y), the result is (NaN,NaN) and FE_INVALID may be raised + * If z is (NaN,NaN), the result is (NaN,NaN) + +.SH Notes + + The semantics of this function are intended to be consistent with the C function + csqrt. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "Square root of -4 is " + << std::sqrt(std::complex(-4.0, 0.0)) << '\\n' + << "Square root of (-4,-0) is " + << std::sqrt(std::complex(-4.0, -0.0)) + << " (the other side of the cut)\\n"; + } + +.SH Output: + + Square root of -4 is (0,2) + Square root of (-4,-0) is (0,-2) (the other side of the cut) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2597 C++98 specification mishandles signed zero erroneous requirement + imaginary parts removed .SH See also - pow(std::complex) complex power, one or both arguments may be a complex number - \fI(function template)\fP + pow(std::complex) complex power, one or both arguments may be a complex number + \fI(function template)\fP + sqrt computes square root (\\(\\small{\\sqrt{x}}\\) + sqrtf √ + sqrtl x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + sqrt(std::valarray) applies the function std::sqrt to each element of valarray + \fI(function template)\fP + C documentation for + csqrt diff --git a/man/std::sqrt(std::valarray).3 b/man/std::sqrt(std::valarray).3 index f59ac7de6..00bdfd3be 100644 --- a/man/std::sqrt(std::valarray).3 +++ b/man/std::sqrt(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::sqrt(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sqrt(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sqrt(std::valarray) \- std::sqrt(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (sqrt) is used to perform the computation. If such function is - not available, std::sqrt is used due to argument dependent lookup. + not available, std::sqrt is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,46 +43,125 @@ valarray sqrt(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = sqrt(i); - } - return other; + + return other; // proxy object may be returned } .SH Example - Finds real roots of multiple quadratic equations. + Finds all three roots (two of which can be complex conjugates) of several Cubic + equations at once. + - // Run this code - #include + #include + #include + #include #include - + #include + #include + + using CD = std::complex; + using VA = std::valarray; + + // return all n complex roots out of a given complex number x + VA root(CD x, unsigned n) + { + const double mag = std::pow(std::abs(x), 1.0 / n); + const double step = 2.0 * std::numbers::pi / n; + double phase = std::arg(x) / n; + VA v(n); + for (std::size_t i{}; i != n; ++i, phase += step) + v[i] = std::polar(mag, phase); + return v; + } + + // return n complex roots of each element in v; in the output valarray first + // goes the sequence of all n roots of v[0], then all n roots of v[1], etc. + VA root(VA v, unsigned n) + { + VA o(v.size() * n); + VA t(n); + for (std::size_t i = 0; i != v.size(); ++i) + { + t = root(v[i], n); + for (unsigned j = 0; j != n; ++j) + o[n * i + j] = t[j]; + } + return o; + } + + // floating-point numbers comparator that tolerates given rounding error + inline bool is_equ(CD x, CD y, double tolerance = 0.000'000'001) + { + return std::abs(std::abs(x) - std::abs(y)) < tolerance; + } + int main() { - std::valarray a(1, 8); - std::valarray b{1, 2, 3, 4, 5, 6, 7, 8}; - std::valarray c = -b; - // literals must also be of type T (double in this case) - std::valarray d = std::sqrt((b * b - 4.0 * a * c)); - std::valarray x1 = (-b - d) / (2.0 * a); - std::valarray x2 = (-b + d) / (2.0 * a); - std::cout << "quadratic equation root 1, root 2" << "\\n"; - for (size_t i = 0; i < a.size(); ++i) { - std::cout << a[i] << "x\\u00B2 + " << b[i] << "x + " << c[i] << " = 0 "; - std::cout << x1[i] << ", " << x2[i] << "\\n"; + // input coefficients for polynomial x³ + p·x + q + const VA p{1, 2, 3, 4, 5, 6, 7, 8}; + const VA q{1, 2, 3, 4, 5, 6, 7, 8}; + + // the solver + const VA d = std::sqrt(std::pow(q / 2, 2) + std::pow(p / 3, 3)); + const VA u = root(-q / 2 + d, 3); + const VA n = root(-q / 2 - d, 3); + + // allocate memory for roots: 3 * number of input cubic polynomials + VA x[3]; + for (std::size_t t = 0; t != 3; ++t) + x[t].resize(p.size()); + + auto is_proper_root = [](CD a, CD b, CD p) { return is_equ(a * b + p / 3.0, 0.0); }; + + // sieve out 6 out of 9 generated roots, leaving only 3 proper roots (per polynomial) + for (std::size_t i = 0; i != p.size(); ++i) + for (std::size_t j = 0, r = 0; j != 3; ++j) + for (std::size_t k = 0; k != 3; ++k) + if (is_proper_root(u[3 * i + j], n[3 * i + k], p[i])) + x[r++][i] = u[3 * i + j] + n[3 * i + k]; + + std::cout << "Depressed cubic equation: Root 1: \\t\\t Root 2: \\t\\t Root 3:\\n"; + for (std::size_t i = 0; i != p.size(); ++i) + { + std::cout << "x³ + " << p[i] << "·x + " << q[i] << " = 0 " + << std::fixed << x[0][i] << " " << x[1][i] << " " << x[2][i] + << std::defaultfloat << '\\n'; + + assert(is_equ(std::pow(x[0][i], 3) + x[0][i] * p[i] + q[i], 0.0)); + assert(is_equ(std::pow(x[1][i], 3) + x[1][i] * p[i] + q[i], 0.0)); + assert(is_equ(std::pow(x[2][i], 3) + x[2][i] * p[i] + q[i], 0.0)); } } .SH Output: - quadratic equation root 1, root 2 - 1x² + 1x + -1 = 0 -1.61803, 0.618034 - 1x² + 2x + -2 = 0 -2.73205, 0.732051 - 1x² + 3x + -3 = 0 -3.79129, 0.791288 - 1x² + 4x + -4 = 0 -4.82843, 0.828427 - 1x² + 5x + -5 = 0 -5.8541, 0.854102 - 1x² + 6x + -6 = 0 -6.87298, 0.872983 - 1x² + 7x + -7 = 0 -7.88748, 0.887482 - 1x² + 8x + -8 = 0 -8.89898, 0.898979 + Depressed cubic equation: Root 1: Root 2: Root 3: + x³ + (1,0)·x + (1,0) = 0 (-0.682328,0.000000) (0.341164,1.161541) (0.341164,-1.161541) + x³ + (2,0)·x + (2,0) = 0 (-0.770917,0.000000) (0.385458,1.563885) (0.385458,-1.563885) + x³ + (3,0)·x + (3,0) = 0 (-0.817732,0.000000) (0.408866,1.871233) (0.408866,-1.871233) + x³ + (4,0)·x + (4,0) = 0 (-0.847708,0.000000) (0.423854,2.130483) (0.423854,-2.130483) + x³ + (5,0)·x + (5,0) = 0 (-0.868830,0.000000) (0.434415,2.359269) (0.434415,-2.359269) + x³ + (6,0)·x + (6,0) = 0 (-0.884622,0.000000) (0.442311,2.566499) (0.442311,-2.566499) + x³ + (7,0)·x + (7,0) = 0 (-0.896922,0.000000) (0.448461,2.757418) (0.448461,-2.757418) + x³ + (8,0)·x + (8,0) = 0 (-0.906795,0.000000) (0.453398,2.935423) (0.453398,-2.935423) + +.SH See also + + applies the function std::pow to two valarrays or a valarray and + pow(std::valarray) a value + \fI(function template)\fP + sqrt computes square root (\\(\\small{\\sqrt{x}}\\) + sqrtf √ + sqrtl x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + sqrt(std::complex) complex square root in the range of the right half-plane + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::sqrt,std::sqrtf,std::sqrtl.3 b/man/std::sqrt,std::sqrtf,std::sqrtl.3 new file mode 100644 index 000000000..810f00f61 --- /dev/null +++ b/man/std::sqrt,std::sqrtf,std::sqrtl.3 @@ -0,0 +1,147 @@ +.TH std::sqrt,std::sqrtf,std::sqrtl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sqrt,std::sqrtf,std::sqrtl \- std::sqrt,std::sqrtf,std::sqrtl + +.SH Synopsis + Defined in header + float sqrt ( float num ); + + double sqrt ( double num ); (until C++23) + + long double sqrt ( long double num ); + /* floating-point-type */ (since C++23) + sqrt ( /* floating-point-type */ num ); (constexpr since C++26) + float sqrtf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double sqrtl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double sqrt ( Integer num ); + + 1-3) Computes the square root of num. + The library provides overloads of std::sqrt for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, square root of num (\\({\\small \\sqrt{num} }\\) + √ + num), is returned. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + Domain error occurs if num is less than zero. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is less than -0, FE_INVALID is raised and NaN is returned. + * If the argument is +∞ or ±0, it is returned, unmodified. + * If the argument is NaN, NaN is returned. + +.SH Notes + + std::sqrt is required by the IEEE standard to be correctly rounded from the + infinitely precise result. In particular, the exact result is produced if it can be + represented in the floating-point type. The only other operations which require this + are the arithmetic operators and the function std::fma. Other functions, including + std::pow, are not so constrained. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::sqrt(num) has the same effect as std::sqrt(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + // normal use + std::cout << "sqrt(100) = " << std::sqrt(100) << '\\n' + << "sqrt(2) = " << std::sqrt(2) << '\\n' + << "golden ratio = " << (1 + std::sqrt(5)) / 2 << '\\n'; + + // special values + std::cout << "sqrt(-0) = " << std::sqrt(-0.0) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "sqrt(-1.0) = " << std::sqrt(-1) << '\\n'; + if (errno == EDOM) + std::cout << " errno = EDOM " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + sqrt(100) = 10 + sqrt\fB(2)\fP = 1.41421 + golden ratio = 1.61803 + sqrt(-0) = -0 + sqrt(-1.0) = -nan + errno = EDOM Numerical argument out of domain + FE_INVALID raised + +.SH See also + + pow + powf raises a number to the given power (\\(\\small{x^y}\\)x^y) + powl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cbrt computes cube root (\\(\\small{\\sqrt[3]{x}}\\) + cbrtf 3 + cbrtl √ + \fI(C++11)\fP x) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + computes square root of the sum of the squares of two + or three + \fI(since C++17)\fP given numbers (\\(\\scriptsize{\\sqrt{x^2+y^2}}\\) + √ + hypot x2 + hypotf +y2 + hypotl ) + \fI(C++11)\fP , (\\(\\scriptsize{\\sqrt{x^2+y^2+z^2}}\\) + \fI(C++11)\fP √ + \fI(C++11)\fP x2 + +y2 + +z2 + ) + \fI(since C++17)\fP + \fI(function)\fP + sqrt(std::complex) complex square root in the range of the right half-plane + \fI(function template)\fP + sqrt(std::valarray) applies the function std::sqrt to each element of valarray + \fI(function template)\fP + C documentation for + sqrt diff --git a/man/std::sqrt.3 b/man/std::sqrt.3 deleted file mode 100644 index 6c91278c7..000000000 --- a/man/std::sqrt.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::sqrt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float sqrt( float arg ); \fB(1)\fP - double sqrt( double arg ); \fB(2)\fP - long double sqrt( long double arg ); \fB(3)\fP - double sqrt( Integral arg ); \fB(4)\fP \fI(since C++11)\fP - - Computes the square root of arg. - -.SH Parameters - - arg - Value of a floating-point or Integral type - -.SH Return value - - Square root of arg. - - Domain error occurs if arg is negative. NAN is returned in that case. - -.SH See also - - computes cubic root ( - cbrt 3 - \fI(C++11)\fP √ - x) - \fI(function)\fP - pow raises a number to the given power (x^y) - \fI(function)\fP - sqrt(std::complex) complex square root in the range of the right half-plane - \fI(function template)\fP - sqrt(std::valarray) applies the function std::sqrt to each element of valarray - \fI(function template)\fP - C documentation for - sqrt diff --git a/man/std::srand.3 b/man/std::srand.3 index 420725568..b92f04435 100644 --- a/man/std::srand.3 +++ b/man/std::srand.3 @@ -1,12 +1,17 @@ -.TH std::srand 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::srand 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::srand \- std::srand + .SH Synopsis Defined in header void srand( unsigned seed ); Seeds the pseudo-random number generator used by std::rand() with the value seed. - If rand() is used before any calls to srand(), rand() behaves as if it was seeded - with srand\fB(1)\fP. Each time rand() is seeded with srand(), it must produce the same + If std::rand() is used before any calls to srand(), std::rand() behaves as if it was + seeded with srand\fB(1)\fP. + + Each time std::rand() is seeded with the same seed, it must produce the same sequence of values. srand() is not guaranteed to be thread-safe. @@ -22,39 +27,41 @@ .SH Notes Generally speaking, the pseudo-random number generator should only be seeded once, - before any calls to rand(), and the start of the program. It should not be - repeatedly seeded, or reseeded every time you wish to generate a new batch of - pseudo-random numbers. + before any calls to rand(), at the start of the program. It should not be repeatedly + seeded, or reseeded every time you wish to generate a new batch of pseudo-random + numbers. - Standard practice is to use the result of a call to time\fB(0)\fP as the seed. However, - time() returns a time_t value, and time_t is not guaranteed to be an integral type. - In practice, though, every major implementation defines time_t to be an integral - type, and this is also what POSIX requires. + Standard practice is to use the result of a call to std::time\fB(0)\fP as the seed. + However, std::time returns a std::time_t value, and std::time_t is not guaranteed to + be an integral type. In practice, though, every major implementation defines + std::time_t to be an integral type, and this is also what POSIX requires. .SH Example - + // Run this code #include - #include #include - + #include + int main() { - std::srand(std::time(0)); //use current time as seed for random generator - int random_variable = std::rand(); - std::cout << "Random value on [0 " << RAND_MAX << "]: " - << random_variable << '\\n'; + std::srand(std::time(0)); // use current time as seed for random generator + std::cout << "Random value on [0, " << RAND_MAX << "]: " << std::rand() << '\\n'; } .SH Possible output: - Random value on [0 2147483647]: 1373858591 + Random value on [0, 2147483647]: 1373858591 .SH See also - rand generates a pseudo-random number - \fI(function)\fP + rand generates a pseudo-random number + \fI(function)\fP + RAND_MAX maximum possible value generated by std::rand + (macro constant) + reseed reseeds the per-thread random engine + \fI(function)\fP C documentation for srand diff --git a/man/std::stable_partition.3 b/man/std::stable_partition.3 index 95545cb50..780c7bc97 100644 --- a/man/std::stable_partition.3 +++ b/man/std::stable_partition.3 @@ -1,70 +1,130 @@ -.TH std::stable_partition 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stable_partition 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stable_partition \- std::stable_partition + .SH Synopsis Defined in header - template< class BidirIt, class UnaryPredicate > - BidirIt stable_partition( BidirIt first, BidirIt last, UnaryPredicate p ); + template< class BidirIt, class UnaryPred > + BidirIt stable_partition( BidirIt first, BidirIt last, \fB(1)\fP (constexpr since C++26) + UnaryPred p ); + template< class ExecutionPolicy, class BidirIt, class + UnaryPred > + + BidirIt stable_partition( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + BidirIt first, BidirIt last, + UnaryPred p ); - Reorders the elements in the range [first, last) in such a way that all elements for - which the predicate p returns true precede the elements for which predicate p + 1) Reorders the elements in the range [first, last) in such a way that all elements + for which the predicate p returns true precede the elements for which predicate p returns false. Relative order of the elements is preserved. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if -.SH Parameters + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the behavior is undefined: - first, last - the range of elements to reorder - unary predicate which returns true if the element should be ordered - before other elements. + * The type of *first is not Swappable. \fI(until C++11)\fP + * BidirIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. - The signature of the predicate function should be equivalent to the - following: - p - - bool pred(const Type &a); +.SH Parameters - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The type Type must be such that an object of type BidirIt can be - dereferenced and then implicitly converted to Type. + first, last - the range of elements to reorder + policy - the execution policy to use. See execution policy for details. + unary predicate which returns true if the element should be ordered + before other elements. + + The expression p(v) must be convertible to bool for every argument v + p - of type (possibly const) VT, where VT is the value type of BidirIt, + regardless of value category, and must not modify v. Thus, a + parameter type of VT&is not allowed + , nor is VT unless for VT a move is equivalent to a copy + \fI(since C++11)\fP. .SH Type requirements - - BidirIt must meet the requirements of ValueSwappable and BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. - - The type of dereferenced BidirIt must meet the requirements of MoveAssignable and - MoveConstructible. - - - UnaryPredicate must meet the requirements of Predicate. + UnaryPred must meet the requirements of Predicate. .SH Return value - Iterator to the first element of the second group + Iterator to the first element of the second group. .SH Complexity - Exactly last-first applications of the predicate and at most - (last-first)*log(last-first) swaps if there is insufficient memory or linear number - of swaps if sufficient memory is available. + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) Exactly \\(\\scriptsize N\\)N applications of p. + \\(\\scriptsize O(N)\\)O(N) swaps if there is enough extra memory, otherwise at most + \\(\\scriptsize N \\cdot log_{2}(N)\\)N⋅log + 2(N) swaps. + 2) \\(\\scriptsize O(N)\\)O(N) applications of p. + \\(\\scriptsize N \\cdot log(N)\\)N⋅log(N) swaps. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + This function attempts to allocate a temporary buffer. If the allocation fails, the + less efficient algorithm is chosen. + + Implementations in libc++ and libstdc++ also accept ranges denoted by + LegacyForwardIterators as an extension. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_algorithms 202306L constexpr stable sorting .SH Example - + // Run this code - #include #include - + #include + #include + int main() { - std::vector v{0, 0, 3, 0, 2, 4, 5, 0, 7}; - std::stable_partition(v.begin(), v.end(), [](int n){return n>0;}); - for (int n : v) { + std::vector v{0, 0, 3, -1, 2, 4, 5, 0, 7}; + std::stable_partition(v.begin(), v.end(), [](int n) { return n > 0; }); + for (int n : v) std::cout << n << ' '; - } std::cout << '\\n'; } .SH Output: - 3 2 4 5 7 0 0 0 0 + 3 2 4 5 7 0 0 -1 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::stable_partition was only required to + LWG 2150 C++98 place one corrected the + element satisfying p before one element not requirement + satisfying p .SH See also - partition divides a range of elements into two groups - \fI(function template)\fP + partition divides a range of elements into two groups + \fI(function template)\fP + ranges::stable_partition divides elements into two groups while preserving their + (C++20) relative order + (niebloid) diff --git a/man/std::stable_sort.3 b/man/std::stable_sort.3 index 160ea8abd..c16f93246 100644 --- a/man/std::stable_sort.3 +++ b/man/std::stable_sort.3 @@ -1,86 +1,158 @@ -.TH std::stable_sort 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stable_sort 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stable_sort \- std::stable_sort + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP + template< class RandomIt > \fB(1)\fP (constexpr since C++26) void stable_sort( RandomIt first, RandomIt last ); - template< class RandomIt, class Compare > \fB(2)\fP - void stable_sort( RandomIt first, RandomIt last, Compare comp ); + template< class ExecutionPolicy, class RandomIt > + + void stable_sort( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last ); + template< class RandomIt, class Compare > + void stable_sort( RandomIt first, RandomIt last, Compare \fB(3)\fP (constexpr since C++26) + comp ); + template< class ExecutionPolicy, class RandomIt, class + Compare > + + void stable_sort( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + RandomIt first, RandomIt last, Compare + comp ); + + Sorts the elements in the range [first, last) in non-descending order. The order of + equivalent elements is guaranteed to be preserved. + + 1) Elements are sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) - Sorts the elements in the range [first, last) in ascending order. The order of equal - elements is guaranteed to be preserved. The first version uses operator< to compare - the elements, the second version uses the given comparison function comp. + If any of the following conditions is satisfied, the behavior is undefined: + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - the range of elements to sort - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + first, last - the range of elements to sort + policy - the execution policy to use. See execution policy for details. + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. + Compare must meet the requirements of Compare. -.SH Return value +.SH Complexity - \fI(none)\fP + Given \\(\\scriptsize N\\)N as last - first: -.SH Complexity + 1,2) \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N·log(N)) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP if enough extra memory is available, otherwise \\(\\scriptsize O(N \\cdot + \\log^{2}(N))\\)O(N·log2 + (N)) comparisons. + 3,4) \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N·log(N)) applications of the comparator + comp if enough extra memory is available, otherwise \\(\\scriptsize O(N \\cdot + \\log^{2}(N))\\)O(N·log2 + (N)) applications. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: - O(N·log^2(N)), where N = std::distance(first, last) applications of cmp. If - additional memory is available, then the complexity is O(N·log(N)). + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + See also the implementations in libstdc++ and libc++. .SH Notes This function attempts to allocate a temporary buffer equal in size to the sequence - to be sorted, typically by calling std::get_temporary_buffer. If the allocation - fails, the less efficient algorithm is chosen. + to be sorted. If the allocation fails, the less efficient algorithm is chosen. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_algorithms 202306L (C++26) constexpr stable sorting, overloads + \fB(1)\fP, \fB(3)\fP .SH Example - + // Run this code #include + #include #include #include #include - - struct Employee { - Employee(int age, std::string name) : age(age), name(name) { } + + struct Employee + { int age; - std::string name; // Does not particpate in comparisons + std::string name; // Does not participate in comparisons }; - - bool operator<(const Employee &lhs, const Employee &rhs) { + + bool operator<(const Employee& lhs, const Employee& rhs) + { return lhs.age < rhs.age; } - + + #if __cpp_lib_constexpr_algorithms >= 202306L + consteval auto get_sorted() + { + auto v = std::array{3, 1, 4, 1, 5, 9}; + std::stable_sort(v.begin(), v.end()); + return v; + } + static_assert(std::ranges::is_sorted(get_sorted())); + #endif + int main() { - std::vector v = { - Employee(108, "Zaphod"), - Employee(32, "Arthur"), - Employee(108, "Ford"), - }; - + std::vector v{{108, "Zaphod"}, {32, "Arthur"}, {108, "Ford"}}; + std::stable_sort(v.begin(), v.end()); - - for (const Employee &e : v) { + + for (const Employee& e : v) std::cout << e.age << ", " << e.name << '\\n'; - } } .SH Output: @@ -91,7 +163,13 @@ .SH See also - partial_sort sorts the first N elements of a range - \fI(function template)\fP - sort sorts a range into ascending order - \fI(function template)\fP + sort sorts a range into ascending order + \fI(function template)\fP + partial_sort sorts the first N elements of a range + \fI(function template)\fP + divides elements into two groups while preserving their relative + stable_partition order + \fI(function template)\fP + ranges::stable_sort sorts a range of elements while preserving order between equal + (C++20) elements + (niebloid) diff --git a/man/std::stack.3 b/man/std::stack.3 index dc412810e..3e6559c65 100644 --- a/man/std::stack.3 +++ b/man/std::stack.3 @@ -1,4 +1,7 @@ -.TH std::stack 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack \- std::stack + .SH Synopsis Defined in header template< @@ -8,8 +11,8 @@ > class stack; - The std::stack class is a container adapter that gives the programmer the - functionality of a stack - specifically, a FILO (first-in, last-out) data structure. + The std::stack class is a container adaptor that gives the programmer the + functionality of a stack - specifically, a LIFO (last-in, first-out) data structure. The class template acts as a wrapper to the underlying container - only a specific set of functions is provided. The stack pushes and pops the element from the back of @@ -17,69 +20,118 @@ .SH Template parameters - T - The type of the stored elements. + T - The type of the stored elements. The program is ill-formed if T is not + the same type as Container::value_type. The type of the underlying container to use to store the elements. The container must satisfy the requirements of SequenceContainer. Additionally, it must provide the following functions with the usual semantics: + * back(), e.g., std::vector::back(), + Container - * push_back(), e.g., std::deque::push_back(), + * pop_back(), e.g., std::list::pop_back(). - Container - * back() - * push_back() - * pop_back() - - The standard containers std::vector, std::deque and std::list satisfy - these requirements. + The standard containers std::vector (including std::vector), + std::deque and std::list satisfy these requirements. By default, if no + container class is specified for a particular stack class instantiation, + the standard container std::deque is used. .SH Member types Member type Definition - container_type Container - value_type Container::value_type - size_type Container::size_type - reference Container::reference - const_reference Container::const_reference + container_type Container + value_type Container::value_type + size_type Container::size_type + reference Container::reference + const_reference Container::const_reference + +.SH Member objects + + Member name Definition + Container c the underlying container + \fI(protected member object)\fP .SH Member functions constructor constructs the stack - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the stack - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container adaptor - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access top accesses the top element - \fI(public member function)\fP + \fI(public member function)\fP .SH Capacity - empty checks whether the underlying container is empty - \fI(public member function)\fP + empty checks whether the container adaptor is empty + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers push inserts element at the top - \fI(public member function)\fP + \fI(public member function)\fP + push_range inserts a range of elements at the top + (C++23) \fI(public member function)\fP emplace constructs element in-place at the top - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP -.SH Member objects - Container c the underlying container - \fI(protected member object)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the stack - operator<= \fI(function template)\fP - operator> + operator< + operator<= lexicographically compares the values of two stacks + operator> \fI(function template)\fP operator>= + operator<=> + (C++20) std::swap(std::stack) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes std::uses_allocator specializes the std::uses_allocator type trait - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(class template specialization)\fP + std::formatter formatting support for std::stack + (C++23) \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 307 C++98 Container could not be allowed + std::vector + LWG 2566 C++98 Missing the requirement for ill-formed if T is not the same type + Container::value_type as Container::value_type + +.SH See also + + vector dynamic contiguous array + \fI(class template)\fP + vector space-efficient dynamic bitset + \fI(class template specialization)\fP + deque double-ended queue + \fI(class template)\fP + list doubly-linked list + \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::stack::emplace.3 b/man/std::stack::emplace.3 index 3f55968cc..e21b6125e 100644 --- a/man/std::stack::emplace.3 +++ b/man/std::stack::emplace.3 @@ -1,13 +1,18 @@ -.TH std::stack::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::emplace \- std::stack::emplace + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + decltype(auto) emplace( Args&&... args ); - Pushes new element on top of the stack. The element is constructed in-place, i.e. no - copy or move operations are performed. The constructor of the element is called with - exactly the same arguments as supplied to the function. + Pushes a new element on top of the stack. The element is constructed in-place, i.e. + no copy or move operations are performed. The constructor of the element is called + with exactly the same arguments as supplied to the function. - Effectively calls c.emplace_back(std::forward(args)...) + Effectively calls c.emplace_back(std::forward(args)...);. .SH Parameters @@ -15,15 +20,56 @@ .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + The value or reference, if any, returned by the above call to \fI(since C++17)\fP + Container::emplace_back. .SH Complexity Identical to the complexity of Container::emplace_back. +.SH Example + + +// Run this code + + #include + #include + + struct S + { + int id; + + S(int i, double d, std::string s) : id{i} + { + std::cout << "S::S(" << i << ", " << d << ", \\"" << s << "\\");\\n"; + } + }; + + int main() + { + std::stack stack; + const S& s = stack.emplace(42, 3.14, "C++"); // for return value C++17 required + std::cout << "id = " << s.id << '\\n'; + } + +.SH Output: + + S::S(42, 3.14, "C++") + id = 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2783 C++17 emplace returned reference, breaking returns decltype(auto) + compatibility with pre-C++17 containers + .SH See also push inserts element at the top - \fI(public member function)\fP + \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::stack::empty.3 b/man/std::stack::empty.3 index 1782c0654..37f6e2b38 100644 --- a/man/std::stack::empty.3 +++ b/man/std::stack::empty.3 @@ -1,8 +1,12 @@ -.TH std::stack::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::empty \- std::stack::empty + .SH Synopsis - bool empty() const; (since {std}) + bool empty() const; \fI(until C++20)\fP + [[nodiscard]] bool empty() const; \fI(since C++20)\fP - Checks if the underlying container has no elements, i.e. whether c.empty(). + Checks if the underlying container has no elements. Equivalent to return c.empty();. .SH Parameters @@ -10,13 +14,41 @@ .SH Return value - true if the underlying container is empty, false otherwise + true if the underlying container is empty, false otherwise. .SH Complexity - Constant + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::stack stack; + + std::cout << "Initially, stack.empty(): " << stack.empty() << '\\n'; + + stack.push(42); + std::cout << "After adding elements, stack.empty(): " << stack.empty() << '\\n'; + } + +.SH Output: + + Initially, stack.empty(): true + After adding elements, stack.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::stack::operator=.3 b/man/std::stack::operator=.3 index 8d2041be3..256e109f4 100644 --- a/man/std::stack::operator=.3 +++ b/man/std::stack::operator=.3 @@ -1,16 +1,18 @@ -.TH std::stack::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::operator= \- std::stack::operator= + .SH Synopsis - stack& \fB(1)\fP - operator=( const stack& other ); - stack& \fB(2)\fP \fI(since C++11)\fP - operator=( stack&& other ); + stack& operator=( const stack& other ); \fB(1)\fP (implicitly declared) + stack& operator=( stack&& other ); \fB(2)\fP \fI(since C++11)\fP + (implicitly declared) - Replaces the contents of the container adaptor with those of other. + Replaces the contents of the container adaptor with the contents of given argument. 1) Copy assignment operator. Replaces the contents with a copy of the contents of - other. Effectively calls c = other.c;. (implicitly declared) + other. Effectively calls c = other.c;. 2) Move assignment operator. Replaces the contents with those of other using move - semantics. Effectively calls c = std::move(other.c); (implicitly declared) + semantics. Effectively calls c = std::move(other.c);. .SH Parameters @@ -22,9 +24,17 @@ .SH Complexity - Equivalent to that of operator= of the underlying container. + 1,2) Equivalent to that of operator= of the underlying container. + +.SH Example + + This section is incomplete + Reason: no example .SH See also constructor constructs the stack - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::stack::pop.3 b/man/std::stack::pop.3 index e402216dc..b86c1e40b 100644 --- a/man/std::stack::pop.3 +++ b/man/std::stack::pop.3 @@ -1,8 +1,11 @@ -.TH std::stack::pop 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::pop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::pop \- std::stack::pop + .SH Synopsis - void pop(); (since {std}) + void pop(); - Removes the top element from the stack. Effectively calls c.pop_back() + Removes the top element from the stack. Effectively calls c.pop_back(). .SH Parameters @@ -16,9 +19,13 @@ Equal to the complexity of Container::pop_back. +.SH Example + .SH See also emplace constructs element in-place at the top - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP push inserts element at the top - \fI(public member function)\fP + \fI(public member function)\fP + top accesses the top element + \fI(public member function)\fP diff --git a/man/std::stack::push.3 b/man/std::stack::push.3 index af773353e..bccf0842a 100644 --- a/man/std::stack::push.3 +++ b/man/std::stack::push.3 @@ -1,12 +1,15 @@ -.TH std::stack::push 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::push 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::push \- std::stack::push + .SH Synopsis - void push( const T& value ); (since {std}) - void push( T&& value ); \fI(since C++11)\fP + void push( const value_type& value ); + void push( value_type&& value ); \fI(since C++11)\fP Pushes the given element value to the top of the stack. - 1) Effectively calls c.push_back(value) - 2) Effectively calls c.push_back(std::move(value)) + 1) Effectively calls c.push_back(value). + 2) Effectively calls c.push_back(std::move(value)). .SH Parameters @@ -20,9 +23,118 @@ Equal to the complexity of Container::push_back. +.SH Example + + This program implements the BrainHack DSL, when the use of std::stack is an + idiomatic way to process paired brackets. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + class BrainHackInterpreter + { + std::map open_brackets, close_brackets; + unsigned program_pos_{0}; + std::array data_; + int data_pos_{0}; + + void collect_brackets_positions(const std::string_view program) + { + std::stack brackets_stack; + + for (auto pos{0U}; pos != program.length(); ++pos) + { + const char c{program[pos]}; + if ('[' == c) + brackets_stack.push(pos); + else if (']' == c) + { + if (brackets_stack.empty()) + throw std::runtime_error("brackets [] do not match!"); + else + { + open_brackets[brackets_stack.top()] = pos; + close_brackets[pos] = brackets_stack.top(); + brackets_stack.pop(); + } + } + } + + if (!brackets_stack.empty()) + throw std::runtime_error("brackets [] do not match!"); + } + + void check_data_pos(int pos) + { + if (pos < 0 || pos >= static_cast(data_.size())) + throw std::out_of_range{"data pointer out of bound"}; + } + + public: + BrainHackInterpreter(const std::string_view program) + { + collect_brackets_positions(program); + data_.fill(0); + + for (; program_pos_ < program.length(); ++program_pos_) + switch (program[program_pos_]) + { + case '<': + check_data_pos(--data_pos_); + break; + case '>': + check_data_pos(++data_pos_); + break; + case '-': + --data_[data_pos_]; + break; + case '+': + ++data_[data_pos_]; + break; + case '.': + std::cout << data_[data_pos_]; + break; + case ',': + std::cin >> data_[data_pos_]; + break; + case '[': + if (data_[data_pos_] == 0) + program_pos_ = open_brackets[program_pos_]; + break; + case ']': + if (data_[data_pos_] != 0) + program_pos_ = close_brackets[program_pos_]; + break; + } + } + }; + + int main() + { + BrainHackInterpreter + { + "++++++++[>++>>++>++++>++++<<<<<-]>[<+++>>+++<-]>[<+" + "+>>>+<<-]<[>+>+<<-]>>>--------.<<+++++++++.<<----.>" + ">>>>.<<<------.>..++.<++.+.-.>.<.>----.<--.++.>>>+." + }; + std::cout << '\\n'; + } + +.SH Output: + + Hi, cppreference! + .SH See also emplace constructs element in-place at the top - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::stack::push_range.3 b/man/std::stack::push_range.3 new file mode 100644 index 000000000..9ac10c319 --- /dev/null +++ b/man/std::stack::push_range.3 @@ -0,0 +1,81 @@ +.TH std::stack::push_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::push_range \- std::stack::push_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void push_range( R&& rg ); + + Inserts a copy of each element of rg in stack, as if by: + + * c.append_range(std::forward(rg)) if that is a valid expression (i.e. the + underlying container c has an appropriate append_range member function), or + * ranges::copy(rg, std::back_inserter(c)) otherwise. + + Each iterator in the range rg is dereferenced exactly once. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements are + convertible to T + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Identical to the complexity of c.append_range or ranges::copy(rg, + std::back_inserter(c)) (depending on what function is used internally). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + requires (std::ranges::input_range) + void println(auto, const Adaptor& adaptor) + { + struct Container : Adaptor // gain access to protected Adaptor::Container c; + { + auto const& container() const { return this->c; } + }; + + for (auto const& elem : static_cast(adaptor).container()) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + std::stack adaptor; + const auto rg = {1, 3, 2, 4}; + + #ifdef __cpp_lib_containers_ranges + adaptor.push_range(rg); + #else + std::ranges::for_each(rg, [&adaptor](auto e){ adaptor.push(e); }); + #endif + + println("{}", adaptor); + } + +.SH Output: + + 1 3 2 4 + +.SH See also + + push inserts element at the top + \fI(public member function)\fP diff --git a/man/std::stack::size.3 b/man/std::stack::size.3 index 77a6068ed..4c22f9dd2 100644 --- a/man/std::stack::size.3 +++ b/man/std::stack::size.3 @@ -1,8 +1,12 @@ -.TH std::stack::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::size \- std::stack::size + .SH Synopsis - size_type size() const; (since {std}) + size_type size() const; - Returns the number of elements in the underlying container, that is, c.size(). + Returns the number of elements in the container adaptor. Equivalent to return + c.size(). .SH Parameters @@ -10,13 +14,40 @@ .SH Return value - The number of elements in the container. + The number of elements in the container adaptor. .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::stack stack; + + assert(stack.size() == 0); + + const int count = 8; + + for (int i = 0; i != count; ++i) + stack.push(i); + + assert(stack.size() == count); + } + .SH See also - empty checks whether the underlying container is empty - \fI(public member function)\fP + empty checks whether the container adaptor is empty + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::stack::stack.3 b/man/std::stack::stack.3 index 0f8c89d98..362e8de49 100644 --- a/man/std::stack::stack.3 +++ b/man/std::stack::stack.3 @@ -1,49 +1,73 @@ -.TH std::stack::stack 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::stack 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::stack \- std::stack::stack + .SH Synopsis - explicit stack( const Container& cont = Container() ); \fI(until C++11)\fP - explicit stack( const Container& cont ); \fI(since C++11)\fP - explicit stack( Container&& cont = Container() ); \fB(2)\fP \fI(since C++11)\fP - stack( const stack& other ); \fB(3)\fP - stack( stack&& other ); \fB(4)\fP \fI(since C++11)\fP - template< class Alloc > \fB(5)\fP \fI(since C++11)\fP + stack() : stack(Container()) {} \fB(1)\fP \fI(since C++11)\fP + explicit stack( const Container& cont = Container() \fI(until C++11)\fP + ); + explicit stack( const Container& cont ); \fI(since C++11)\fP + explicit stack( Container&& cont ); \fB(3)\fP \fI(since C++11)\fP + stack( const stack& other ); \fB(4)\fP (implicitly + declared) + \fI(since C++11)\fP + stack( stack&& other ); \fB(5)\fP (implicitly + declared) + template< class InputIt > \fB(6)\fP (since C++23) + stack( InputIt first, InputIt last ); + template< class Alloc > \fB(7)\fP \fI(since C++11)\fP explicit stack( const Alloc& alloc ); - template< class Alloc > \fB(1)\fP \fB(6)\fP \fI(since C++11)\fP - stack( const Container& cont, const Alloc& alloc ); - template< class Alloc > \fB(7)\fP \fI(since C++11)\fP + template< class Alloc > \fB(8)\fP \fI(since C++11)\fP + stack( const Container& cont, const Alloc& alloc ); \fB(2)\fP + template< class Alloc > \fB(9)\fP \fI(since C++11)\fP stack( Container&& cont, const Alloc& alloc ); - template< class Alloc > \fB(8)\fP \fI(since C++11)\fP + template< class Alloc > \fB(10)\fP \fI(since C++11)\fP stack( const stack& other, const Alloc& alloc ); - template< class Alloc > \fB(9)\fP \fI(since C++11)\fP + template< class Alloc > \fB(11)\fP \fI(since C++11)\fP stack( stack&& other, const Alloc& alloc ); + template< class InputIt, class Alloc > + stack( InputIt first, InputIt last, const Alloc& \fB(12)\fP (since C++23) + alloc ); + template< container-compatible-range R> \fB(13)\fP (since C++23) + stack( std::from_range_t, R&& rg ); + template< container-compatible-range R, class + Alloc > \fB(14)\fP (since C++23) + stack( std::from_range_t, R&& rg, const Alloc& + alloc ); Constructs new underlying container of the container adaptor from a variety of data sources. - 1) Copy-constructs the underlying container c with the contents of cont. - This is also the default constructor + 1) Default constructor. Value-initializes the container. + 2) Copy-constructs the underlying container c with the contents of cont. + This is also the default constructor. \fI(until C++11)\fP - 2) Move-constructs the underlying container c with std::move(cont). - This is also the default constructor - \fI(since C++11)\fP - 3) Copy constructor. The adaptor is copy-constructed with the contents of other.c. - (implicitly declared) - 4) Move constructor. The adaptor is constructed with std::move(other.c). (implicitly - declared) - 5-9) The following constructors are only defined if - std::uses_allocator::value == true, that is, if the - underlying container is an allocator-aware container (true for all standard library - containers). - 5) Constructs the underlying container using alloc as allocator. Effectively calls - c(alloc). - 6) Constructs the underlying container with the contents of cont and using alloc as - allocator. Effectively calls c(cont, alloc). - 7) Constructs the underlying container with the contents of cont using move - semantics while utilising alloc as allocator. Effectively calls c(std::move(cont), - alloc). - 8) Constructs the adaptor with the contents of other.c and using alloc as allocator. - Effectively calls c(athor.c, alloc). - 9) Constructs the adaptor with the contents of other using move semantics while - utilising alloc as allocator. Effectively calls c(std::move(other.c), alloc). + 3) Move-constructs the underlying container c with std::move(cont). + 4) Copy constructor. The adaptor is copy-constructed with the contents of other.c. + 5) Move constructor. The adaptor is constructed with std::move(other.c). + 6) Constructs the underlying container c with the contents of the range + [first, last). This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator. + 7-12) These constructors participate in overload resolution only if + std::uses_allocator::value is true, that is, if the underlying + container is an allocator-aware container (true for all standard library containers + that can be used with stack). + 7) Constructs the underlying container using alloc as allocator, as if by c(alloc). + 8) Constructs the underlying container with the contents of cont and using alloc as + allocator, as if by c(cont, alloc). + 9) Constructs the underlying container with the contents of cont using move + semantics while utilizing alloc as allocator, as if by c(std::move(cont), alloc). + 10) Constructs the adaptor with the contents of other.c and using alloc as + allocator, as if by c(other.c, alloc). + 11) Constructs the adaptor with the contents of other using move semantics while + utilizing alloc as allocator, as if by c(std::move(other.c), alloc). + 12) Constructs the underlying container with the contents of the range [first, last) + using alloc as allocator, as if by c(first, last, alloc). This overload participates + in overload resolution only if InputIt satisfies LegacyInputIterator. + 13) Constructs the underlying container with + ranges::to(std::forward(rg)). + 14) Constructs the underlying container with + ranges::to(std::forward(rg), alloc). .SH Parameters @@ -53,58 +77,97 @@ initialize the underlying container cont - container to be used as source to initialize the underlying container - first, last - range of elements to initialize with + first, last - range of elements [first, last) to initialize with + rg - a container compatible range, that is, an + input_range whose elements are convertible to T .SH Type requirements - Alloc must meet the requirements of Allocator. - - Container must meet the requirements of Container. The constructors (5-10) are only - defined if Container meets the requirements of AllocatorAwareContainer + Container must meet the requirements of Container. The constructors taking an + allocator parameter participate in overload resolution only if Container meets the + requirements of AllocatorAwareContainer. - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1, 3, 5, 6, 8: linear in cont or other + Same as the corresponding operation on the wrapped container. - 2, 4, 7, 9: constant +.SH Notes - This section is incomplete + Feature-test macro Value Std Feature + Iterator pair + constructors for + __cpp_lib_adaptor_iterator_pair_constructor 202106L (C++23) std::queue and + std::stack; overloads + \fB(6)\fP and \fB(12)\fP + Ranges-aware + __cpp_lib_containers_ranges 202202L (C++23) construction and + insertion; overloads + \fB(13)\fP and \fB(14)\fP .SH Example - + // Run this code - #include + #include #include #include - + #include + #include + #include + int main() { std::stack c1; c1.push(5); - std::cout << c1.size() << '\\n'; - + assert(c1.size() == 1); + std::stack c2(c1); - std::cout << c2.size() << '\\n'; - - std::deque deq {3, 1, 4, 1, 5}; - std::stack c3(deq); - std::cout << c3.size() << '\\n'; + assert(c2.size() == 1); + + std::deque deq{3, 1, 4, 1, 5}; + std::stack c3(deq); // overload (2) + assert(c3.size() == 5); + + # ifdef __cpp_lib_adaptor_iterator_pair_constructor + const auto il = {2, 7, 1, 8, 2}; + std::stack c4{il.begin(), il.end()}; // C++23, (6) + assert(c4.size() == 5); + # endif + + # if __cpp_lib_containers_ranges >= 202202L + // C++23, overload (13) + auto c5 = std::stack(std::from_range_t, std::ranges::iota(0, 42)); + assert(c5.size() == 42); + + // the same effect with pipe syntax, internally uses overload (13) + auto c6 = std::ranges::iota(0, 42) | std::ranges::to(); + assert(c6.size() == 42); + + std::allocator alloc; + + // C++23, overload (14) + auto c7 = std::stack(std::from_range_t, std::ranges::iota(0, 42), alloc); + assert(c7.size() == 42); + + // the same effect with pipe syntax, internally uses overload (14) + auto c8 = std::ranges::iota(0, 42) | std::ranges::to(alloc); + assert(c8.size() == 42); + # endif } -.SH Output: + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 1 - 1 - 5 + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit .SH See also operator= assigns values to the container adaptor - \fI(public member function)\fP - -.SH Category: - - * Todo without reason + \fI(public member function)\fP diff --git a/man/std::stack::swap.3 b/man/std::stack::swap.3 index 156294284..f82bbba78 100644 --- a/man/std::stack::swap.3 +++ b/man/std::stack::swap.3 @@ -1,9 +1,15 @@ -.TH std::stack::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::swap \- std::stack::swap + .SH Synopsis - void swap( stack& other ); (since {std}) + void swap( stack& other ) noexcept(/* see below */); \fI(since C++11)\fP Exchanges the contents of the container adaptor with those of other. Effectively - calls using std::swap; swap(c, other.c); + calls + + using std::swap; + swap(c, other.c); .SH Parameters @@ -15,16 +21,89 @@ .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: \fI(since C++11)\fP (since C++11) - noexcept(noexcept(std::swap(c, other.c))) + noexcept specification: + noexcept(noexcept(swap(c, other.c))) \fI(since C++11)\fP + \fI(until C++17)\fP + In the expression above, the identifier swap is looked up in the same + manner as the one used by the C++17 std::is_nothrow_swappable trait. + noexcept specification: \fI(since C++17)\fP + noexcept(std::is_nothrow_swappable_v) .SH Complexity - Same as underlying container (linear if Container is std::array, constant - otherwise). + Same as underlying container (typically constant). + +.SH Notes + + Some implementations (e.g. libc++) provide the swap member function as an extension + to pre-C++11 modes. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + template + requires (std::ranges::input_range) + void print(std::string_view name, const Adaptor& adaptor) + { + struct Printer : Adaptor // to use protected Adaptor::Container c; + { + void print(std::string_view name) const + { + std::cout << name << " [" << std::size(this->c) << "]: "; + for (auto const& elem : this->c) + std::cout << elem << ' '; + std::cout << '\\n'; + } + }; + + static_cast(adaptor).print(name); + } + + int main() + { + std::vector v1{"1","2","3","4"}, + v2{"Ɐ","B","Ɔ","D","Ǝ"}; + + std::stack s1(std::move(v1)); + std::stack s2(std::move(v2)); + + print("s1", s1); + print("s2", s2); + + s1.swap(s2); + + print("s1", s1); + print("s2", s2); + } + +.SH Output: + + s1 [4]: 4 3 2 1 + s2 [5]: Ǝ D Ɔ B Ɐ + s1 [5]: Ǝ D Ɔ B Ɐ + s2 [4]: 4 3 2 1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2456 C++11 the noexcept specification is ill-formed made to work .SH See also std::swap(std::stack) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::stack::top.3 b/man/std::stack::top.3 index acc6d5389..80aec168d 100644 --- a/man/std::stack::top.3 +++ b/man/std::stack::top.3 @@ -1,4 +1,7 @@ -.TH std::stack::top 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::top 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::top \- std::stack::top + .SH Synopsis reference top(); const_reference top() const; @@ -13,38 +16,46 @@ .SH Return value - Reference to the last element + Reference to the last element. .SH Complexity - Constant + Constant. .SH Example - + // Run this code - #include #include - - int main() + #include + + void reportStackSize(const std::stack& s) { - std::stack s; - - s.push( 2 ); - s.push( 6 ); - s.push( 51 ); - - std::cout << s.size() << " elements on stack\\n"; - std::cout << "Top element: " - << s.top() // Leaves element on stack - << "\\n"; std::cout << s.size() << " elements on stack\\n"; + } + + void reportStackTop(const std::stack& s) + { + // Leaves element on stack + std::cout << "Top element: " << s.top() << '\\n'; + } + + int main() + { + std::stack s; + s.push(2); + s.push(6); + s.push(51); + + reportStackSize(s); + reportStackTop(s); + + reportStackSize(s); s.pop(); - std::cout << s.size() << " elements on stack\\n"; - std::cout << "Top element: " << s.top() << "\\n"; - - return 0; + + reportStackSize(s); + reportStackTop(s); } .SH Output: @@ -58,6 +69,6 @@ .SH See also push inserts element at the top - \fI(public member function)\fP + \fI(public member function)\fP pop removes the top element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::stack::~stack.3 b/man/std::stack::~stack.3 index 821a7f4f6..69395749e 100644 --- a/man/std::stack::~stack.3 +++ b/man/std::stack::~stack.3 @@ -1,11 +1,14 @@ -.TH std::stack::~stack 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stack::~stack 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stack::~stack \- std::stack::~stack + .SH Synopsis - ~stack(); (since {std}) + ~stack(); - Destructs the container adaptor. The destructors of the elements are called and the - used storage is deallocated. Note, that if the elements are pointers, the pointed-to - objects are not destroyed. + Destructs the stack. The destructors of the elements are called and the used storage + is deallocated. Note, that if the elements are pointers, the pointed-to objects are + not destroyed. .SH Complexity - Linear in the size of the container adaptor. + Linear in the size of the stack. diff --git a/man/std::stacktrace_entry.3 b/man/std::stacktrace_entry.3 new file mode 100644 index 000000000..aa944c528 --- /dev/null +++ b/man/std::stacktrace_entry.3 @@ -0,0 +1,85 @@ +.TH std::stacktrace_entry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry \- std::stacktrace_entry + +.SH Synopsis + Defined in header + class stacktrace_entry; (since C++23) + + The stacktrace_entry class provides operations for querying information about an + evaluation in a stacktrace. Each stacktrace_entry object is either empty, or + represents an evaluation in a stacktrace. + + stacktrace_entry models std::regular and + std::three_way_comparable. + +.SH Member types + + native_handle_type(C++23) implementation-defined native handle type + +.SH Member functions + + constructor constructs a new stacktrace_entry + (C++23) \fI(public member function)\fP + destructor destroys the stacktrace_entry + (C++23) \fI(public member function)\fP + operator= assigns the contents of one stacktrace_entry to another + (C++23) \fI(public member function)\fP +.SH Observers + native_handle gets the implementation-defined native handle of the stacktrace_entry + (C++23) \fI(public member function)\fP + operator bool checks whether the stacktrace_entry is empty + (C++23) \fI(public member function)\fP + Query + description gets the description of the evaluation represented by the + (C++23) stacktrace_entry + \fI(public member function)\fP + gets the name of the source file that lexically contains the + source_file expression or statement whose evaluation is represented by the + (C++23) stacktrace_entry + \fI(public member function)\fP + source_line gets the line number that lexically relates the evaluation represented + (C++23) by the stacktrace_entry + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares two stacktrace_entry values + operator<=> \fI(function)\fP + (C++23) + to_string returns a string with a description of the stacktrace_entry + (C++23) \fI(function)\fP + operator<< performs stream output of stacktrace_entry + (C++23) \fI(function template)\fP + +.SH Helper classes + + std::hash hash support for std::stacktrace_entry + (C++23) \fI(class template specialization)\fP + std::formatter formatting support for stacktrace_entry + (C++23) \fI(class template specialization)\fP + +.SH Notes + + boost::stacktrace::frame (available in Boost.Stacktrace) can be used instead when + std::stacktrace_entry is not available. + + Feature-test macro Value Std Feature + __cpp_lib_stacktrace 202011L (C++23) Stacktrace library + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + basic_stacktrace approximate representation of an invocation sequence consists of + (C++23) stacktrace entries + \fI(class template)\fP + source_location a class representing information about the source code, such as + (C++20) file names, line numbers, and function names + \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::stacktrace_entry::description.3 b/man/std::stacktrace_entry::description.3 new file mode 100644 index 000000000..f443544d4 --- /dev/null +++ b/man/std::stacktrace_entry::description.3 @@ -0,0 +1,39 @@ +.TH std::stacktrace_entry::description 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::description \- std::stacktrace_entry::description + +.SH Synopsis + std::string description() const; (since C++23) + + Returns a description of the evaluation represented by *this on success, or an empty + string on failure other than allocation failure, e.g. when *this is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A description of the represented evaluation on success, an empty string on failure + other than allocation failure. + +.SH Exceptions + + Throws std::bad_alloc if memory for the internal data structures or the resulting + string cannot be allocated. + +.SH Notes + + Custom allocators support for this function is not provided, because the + implementations usually require platform specific allocations, system calls and a + lot of CPU intensive work, while a custom allocator does not provide benefits for + this function as the platform specific operations take an order of magnitude more + time than the allocation. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stacktrace_entry::native_handle.3 b/man/std::stacktrace_entry::native_handle.3 new file mode 100644 index 000000000..6bde87b5c --- /dev/null +++ b/man/std::stacktrace_entry::native_handle.3 @@ -0,0 +1,27 @@ +.TH std::stacktrace_entry::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::native_handle \- std::stacktrace_entry::native_handle + +.SH Synopsis + constexpr native_handle_type native_handle() const noexcept; (since C++23) + + Returns the implementation-defined underlying native handle. Successive invocations + of this function for an unchanged stacktrace_entry object return identical values. + + The semantics of this function is implementation-defined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Underlying native handle. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stacktrace_entry::operator=.3 b/man/std::stacktrace_entry::operator=.3 new file mode 100644 index 000000000..25dd013b9 --- /dev/null +++ b/man/std::stacktrace_entry::operator=.3 @@ -0,0 +1,17 @@ +.TH std::stacktrace_entry::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::operator= \- std::stacktrace_entry::operator= + +.SH Synopsis + constexpr stacktrace_entry& operator=( const stacktrace_entry& other (since C++23) + ) noexcept; + + Copy assignment operator. Replaces the contents of *this with those of other. + +.SH Parameters + + other - another stacktrace_entry to assign from + +.SH Return value + + *this. diff --git a/man/std::stacktrace_entry::operatorbool.3 b/man/std::stacktrace_entry::operatorbool.3 new file mode 100644 index 000000000..ea3293192 --- /dev/null +++ b/man/std::stacktrace_entry::operatorbool.3 @@ -0,0 +1,32 @@ +.TH std::stacktrace_entry::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::operatorbool \- std::stacktrace_entry::operatorbool + +.SH Synopsis + constexpr explicit operator bool() const noexcept; (since C++23) + + Checks whether the stacktrace_entry is non-empty, i.e. it represents an evaluation + in a stacktrace. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stacktrace_entry is non-empty, false otherwise. + +.SH Notes + + A non-empty stacktrace_entry can be obtained from a std::basic_stacktrace created by + std::basic_stacktrace::current or a copy of such std::basic_stacktrace. + + An empty stacktrace_entry can be created by the default constructor. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stacktrace_entry::source_file.3 b/man/std::stacktrace_entry::source_file.3 new file mode 100644 index 000000000..f2794a89c --- /dev/null +++ b/man/std::stacktrace_entry::source_file.3 @@ -0,0 +1,56 @@ +.TH std::stacktrace_entry::source_file 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::source_file \- std::stacktrace_entry::source_file + +.SH Synopsis + std::string source_file() const; (since C++23) + + Returns the presumed or actual name of the source file that lexically contains the + expression or statement whose evaluation is represented by *this, or an empty string + on failure other than allocation failure, e.g. when *this is empty. + + Either source_file returns the presumed source file name and source_line returns the + presumed line number, or source_file returns the actual source file name and + source_line returns the actual line number. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The name of the source file specified above on success, an empty string on failure + other than allocation failure. + +.SH Exceptions + + Throws std::bad_alloc if memory for the internal data structures or the resulting + string cannot be allocated. + +.SH Notes + + The presumed name of the source file is what the predefined macro __FILE__ expands + to, and can be changed by the #line directive. + + This section is incomplete + Reason: definition of "actual name" is missing (LWG issue 3507) + + Custom allocators support for this function is not provided, because the + implementations usually require platform specific allocations, system calls and a + lot of CPU intensive work, while a custom allocator does not provide benefits for + this function as the platform specific operations take an order of magnitude more + time than the allocation. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + file_name return the file name represented by this object + \fI(public member function of std::source_location)\fP + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::stacktrace_entry::source_line.3 b/man/std::stacktrace_entry::source_line.3 new file mode 100644 index 000000000..9e8b33b77 --- /dev/null +++ b/man/std::stacktrace_entry::source_line.3 @@ -0,0 +1,52 @@ +.TH std::stacktrace_entry::source_line 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::source_line \- std::stacktrace_entry::source_line + +.SH Synopsis + std::uint_least32_t source_line() const; (since C++23) + + Returns a 1-based line number that lexically relates to the evaluation represented + by *this, or 0 on failure other than allocation failure, e.g. when *this is empty. + + Either source_file returns the presumed source file name and source_line returns the + presumed line number, or source_file returns the actual source file name and + source_line returns the actual line number. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The line number specified above on success, 0 on failure other than allocation + failure. + +.SH Exceptions + + Throws std::bad_alloc if memory for the internal data structures cannot be + allocated. + +.SH Notes + + The presumed line number is what the predefined macro __LINE__ expands to, and can + be changed by the #line directive. + + This section is incomplete + Reason: definition of "actual line number" is missing (LWG issue 3507) + + This function is not required to be noexcept because getting source line requires + allocation on some platforms. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + line return the line number represented by this object + \fI(public member function of std::source_location)\fP + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::stacktrace_entry::stacktrace_entry.3 b/man/std::stacktrace_entry::stacktrace_entry.3 new file mode 100644 index 000000000..405a963da --- /dev/null +++ b/man/std::stacktrace_entry::stacktrace_entry.3 @@ -0,0 +1,33 @@ +.TH std::stacktrace_entry::stacktrace_entry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stacktrace_entry::stacktrace_entry \- std::stacktrace_entry::stacktrace_entry + +.SH Synopsis + constexpr stacktrace_entry() noexcept; \fB(1)\fP (since C++23) + constexpr stacktrace_entry( const stacktrace_entry& other ) \fB(2)\fP (since C++23) + noexcept; + + 1) Default constructor. Creates an empty stacktrace_entry. + 2) Copy constructor. Creates a copy of other. + +.SH Parameters + + other - another stacktrace_entry to copy from + +.SH Notes + + A non-empty stacktrace_entry can be obtained from a std::basic_stacktrace created by + std::basic_stacktrace::current or a copy of such std::basic_stacktrace. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a new source_location with implementation-defined values + \fI(public member function of std::source_location)\fP + +.SH Category: + * Todo no example diff --git a/man/std::start_lifetime_as,std::start_lifetime_as_array.3 b/man/std::start_lifetime_as,std::start_lifetime_as_array.3 new file mode 100644 index 000000000..7a7754178 --- /dev/null +++ b/man/std::start_lifetime_as,std::start_lifetime_as_array.3 @@ -0,0 +1,127 @@ +.TH std::start_lifetime_as,std::start_lifetime_as_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::start_lifetime_as,std::start_lifetime_as_array \- std::start_lifetime_as,std::start_lifetime_as_array + +.SH Synopsis + Defined in header + start_lifetime_as + template< class T > \fB(1)\fP (since C++23) + T* start_lifetime_as( void* p ) noexcept; + template< class T > \fB(2)\fP (since C++23) + const T* start_lifetime_as( const void* p ) noexcept; + template< class T > \fB(3)\fP (since C++23) + volatile T* start_lifetime_as( volatile void* p ) noexcept; + template< class T > + const volatile T* start_lifetime_as( const volatile void* p ) \fB(4)\fP (since C++23) + noexcept; + start_lifetime_as_array + template< class T > \fB(5)\fP (since C++23) + T* start_lifetime_as_array( void* p, std::size_t n ) noexcept; + template< class T > + + const T* start_lifetime_as_array( const void* p, \fB(6)\fP (since C++23) + + std::size_t n ) noexcept; + template< class T > + + volatile T* start_lifetime_as_array( volatile void* p, \fB(7)\fP (since C++23) + + std::size_t n ) noexcept; + template< class T > + + const volatile T* start_lifetime_as_array( const volatile void* p, \fB(8)\fP (since C++23) + + std::size_t n ) + noexcept; + + 1-4) Implicitly creates a complete object of type T (whose address is p) and objects + nested within it. The value of each created object obj of TriviallyCopyable type U + is determined in the same manner as for a call to std::bit_cast(E) except that + the storage is not actually accessed, where E is the lvalue of type U denoting obj. + Otherwise, the values of such created objects are unspecified. + * T shall be an ImplicitLifetimeType and shall be a complete type. Otherwise, the + program is ill-formed. + * The behavior is undefined if: + + * [p, (char*)p + sizeof(T)) does not denote a region of allocated storage that is + a subset of the region of storage reachable through p, or + * the region is not suitably aligned for the T. + * Note that the unspecified value can be indeterminate. + 5-8) Implicitly creates an array with element type T and length n. To be precise, if + n > 0 is true, it is equivalent to std::start_lifetime_as(p) where U is the type + "array of n Ts". Otherwise, the function has no effects. + * T shall be a complete type. Otherwise, the program is ill-formed. + * The behavior is undefined if: + + * Non-null p is not suitably aligned for an array of T, or + * n <= std::size_t(-1) / sizeof(T) is false, or + * n > 0 and [(char*)p, (char*)p + (n * sizeof(T))) does not denote a region of + allocated storage that is a subset of the region of storage reachable through p. + +.SH Parameters + + p - the address of the region consisting objects + n - the number of the element of the array to be created + +.SH Return value + + 1-4) A pointer to the complete object as described above. + 5-8) A pointer to the first element of the created array, if any; otherwise, a + pointer that compares equal to p. + +.SH Notes + + new (void_ptr) unsigned char[size] or new (void_ptr) std::byte[size] works as an + untyped version of std::start_lifetime_as, but it does not keep the object + representation. + + std::start_lifetime_as handles non-array types as well as arrays of known bound, + while std::start_lifetime_as_array handles arrays of unknown bound. + + Feature-test macro Value Std Feature + __cpp_lib_start_lifetime_as 202207L (C++23) Explicit lifetime management + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + alignas(std::complex) unsigned char network_data[sizeof(std::complex)]{ + 0xcd, 0xcc, 0xcc, 0x3d, 0xcd, 0xcc, 0x4c, 0x3e + }; + + // auto d = *reinterpret_cast*>(network_data); + // std::cout << d << '\\n'; // UB: network_data does not point to a complex + + // auto d = *std::launder(reinterpret_cast*>(network_data)); + // std::cout << d << '\\n'; // Possible UB, related to CWG1997: + // the implicitly created complex may hold indeterminate value + + auto d = *std::start_lifetime_as>(network_data); + std::cout << d << '\\n'; // OK + } + +.SH Possible output: + + (0.1,0.2) + +.SH References + + * C++23 standard (ISO/IEC 14882:2023): + + * 20.2.6 Explicit lifetime management [obj.lifetime] + +.SH See also + + bit_cast reinterpret the object representation of one type as that of + (C++20) another + \fI(function template)\fP + as_bytes converts a span into a view of its underlying bytes + as_writable_bytes \fI(function template)\fP + (C++20) diff --git a/man/std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast,.3 b/man/std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast,.3 new file mode 100644 index 000000000..adca4ff33 --- /dev/null +++ b/man/std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast,.3 @@ -0,0 +1,171 @@ +.TH std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast, \- std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast, + +.SH Synopsis + + Defined in header + template< class T, class U > + std::shared_ptr static_pointer_cast( const std::shared_ptr& \fB(1)\fP \fI(since C++11)\fP + r ) noexcept; + template< class T, class U > + std::shared_ptr static_pointer_cast( std::shared_ptr&& r ) \fB(2)\fP \fI(since C++20)\fP + noexcept; + template< class T, class U > + std::shared_ptr dynamic_pointer_cast( const std::shared_ptr& \fB(3)\fP \fI(since C++11)\fP + r ) noexcept; + template< class T, class U > + std::shared_ptr dynamic_pointer_cast( std::shared_ptr&& r ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + template< class T, class U > + std::shared_ptr const_pointer_cast( const std::shared_ptr& r \fB(5)\fP \fI(since C++11)\fP + ) noexcept; + template< class T, class U > + std::shared_ptr const_pointer_cast( std::shared_ptr&& r ) \fB(6)\fP \fI(since C++20)\fP + noexcept; + template< class T, class U > + std::shared_ptr reinterpret_pointer_cast( const \fB(7)\fP \fI(since C++17)\fP + std::shared_ptr& r ) noexcept; + template< class T, class U > + std::shared_ptr reinterpret_pointer_cast( std::shared_ptr&& \fB(8)\fP \fI(since C++20)\fP + r ) noexcept; + + Creates a new instance of std::shared_ptr whose stored pointer is obtained from r's + stored pointer using a cast expression. + + If r is empty, so is the new shared_ptr (but its stored pointer is not necessarily + null). Otherwise, the new shared_ptr will share ownership with the initial value of + r, except that it is empty if the dynamic_cast performed by dynamic_pointer_cast + returns a null pointer. + + Let Y be typename std::shared_ptr::element_type, then the resulting + std::shared_ptr's stored pointer will be obtained by evaluating, respectively: + + 1,2) static_cast(r.get()) + 3,4) dynamic_cast(r.get()). If the result of the dynamic_cast is a null pointer + value, the returned shared_ptr will be empty. + 5,6) const_cast(r.get()) + 7,8) reinterpret_cast(r.get()) + + The behavior of these functions is undefined unless the corresponding cast from U* + to T* is well formed: + + 1,2) The behavior is undefined unless static_cast((U*)nullptr) is well formed. + 3,4) The behavior is undefined unless dynamic_cast((U*)nullptr) is well formed. + 5,6) The behavior is undefined unless const_cast((U*)nullptr) is well formed. + 7,8) The behavior is undefined unless reinterpret_cast((U*)nullptr) is well + formed. + + After calling the rvalue overloads (2,4,6,8), r is empty and r.get() + == nullptr, except that r is not modified for dynamic_pointer_cast \fB(4)\fP \fI(since C++20)\fP + if the dynamic_cast fails. + +.SH Parameters + + r - the pointer to convert + +.SH Notes + + The expressions std::shared_ptr(static_cast(r.get())), + std::shared_ptr(dynamic_cast(r.get())) and + std::shared_ptr(const_cast(r.get())) might seem to have the same effect, but + they all will likely result in undefined behavior, attempting to delete the same + object twice! + +.SH Possible implementation + + static_pointer_cast + template + std::shared_ptr static_pointer_cast(const std::shared_ptr& r) noexcept + { + auto p = static_cast::element_type*>(r.get()); + return std::shared_ptr{r, p}; + } + dynamic_pointer_cast + template + std::shared_ptr dynamic_pointer_cast(const std::shared_ptr& r) noexcept + { + if (auto p = dynamic_cast::element_type*>(r.get())) + return std::shared_ptr{r, p}; + else + return std::shared_ptr{}; + } + const_pointer_cast + template + std::shared_ptr const_pointer_cast(const std::shared_ptr& r) noexcept + { + auto p = const_cast::element_type*>(r.get()); + return std::shared_ptr{r, p}; + } + reinterpret_pointer_cast + template + std::shared_ptr reinterpret_pointer_cast(const std::shared_ptr& r) noexcept + { + auto p = reinterpret_cast::element_type*>(r.get()); + return std::shared_ptr{r, p}; + } + +.SH Example + + +// Run this code + + #include + #include + + class Base + { + public: + int a; + virtual void f() const { std::cout << "I am base!\\n"; } + virtual ~Base() {} + }; + + class Derived : public Base + { + public: + void f() const override { std::cout << "I am derived!\\n"; } + ~Derived() {} + }; + + int main() + { + auto basePtr = std::make_shared(); + std::cout << "Base pointer says: "; + basePtr->f(); + + auto derivedPtr = std::make_shared(); + std::cout << "Derived pointer says: "; + derivedPtr->f(); + + // static_pointer_cast to go up class hierarchy + basePtr = std::static_pointer_cast(derivedPtr); + std::cout << "Base pointer to derived says: "; + basePtr->f(); + + // dynamic_pointer_cast to go down/across class hierarchy + auto downcastedPtr = std::dynamic_pointer_cast(basePtr); + if (downcastedPtr) + { + std::cout << "Downcasted pointer says: "; + downcastedPtr->f(); + } + + // All pointers to derived share ownership + std::cout << "Pointers to underlying derived: " + << derivedPtr.use_count() + << '\\n'; + } + +.SH Output: + + Base pointer says: I am base! + Derived pointer says: I am derived! + Base pointer to derived says: I am derived! + Downcasted pointer says: I am derived! + Pointers to underlying derived: 3 + +.SH See also + + constructor constructs new shared_ptr + \fI(public member function)\fP diff --git a/man/std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast.3 b/man/std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast.3 deleted file mode 100644 index 34febe482..000000000 --- a/man/std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH std::static_pointer_cast,std::dynamic_pointer_cast,std::const_pointer_cast 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class T, class U > \fB(1)\fP \fI(since C++11)\fP - shared_ptr static_pointer_cast( const shared_ptr& r ); - template< class T, class U > \fB(2)\fP \fI(since C++11)\fP - shared_ptr dynamic_pointer_cast( const shared_ptr& r ); - template< class T, class U > \fB(3)\fP \fI(since C++11)\fP - shared_ptr const_pointer_cast( const shared_ptr& r ); - - Creates a new instance of std::shared_ptr whose managed object type is obtained from - the r's managed object type using a cast expression. Both smart pointers will share - the ownership of the managed object. - - The resulting std::shared_ptr's managed object will be obtained by calling (in - respective order): - - 1) static_cast(r.get()). - 2) dynamic_cast(r.get()) (If the result of the dynamic_cast is 0, the returned - shared_ptr will be empty). - 3) const_cast(r.get()). - - In any case, if the parameter r is an empty std::shared_ptr the result will be a new - empty std::shared_ptr. - -.SH Parameters - - r - The pointer to convert - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::stof,std::stod,std::stold.3 b/man/std::stof,std::stod,std::stold.3 index 6e2ad5d4c..8d0ff06e6 100644 --- a/man/std::stof,std::stod,std::stold.3 +++ b/man/std::stof,std::stod,std::stold.3 @@ -1,56 +1,75 @@ -.TH std::stof,std::stod,std::stold 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stof,std::stod,std::stold 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stof,std::stod,std::stold \- std::stof,std::stod,std::stold + .SH Synopsis Defined in header - float stof( const std::string& str, size_t *pos = 0 ); \fB(1)\fP \fI(since C++11)\fP - double stod( const std::string& str, size_t *pos = 0 ); \fB(2)\fP \fI(since C++11)\fP - long double stold( const std::string& str, size_t *pos = 0 ); \fB(3)\fP \fI(since C++11)\fP + float stof ( const std::string& str, std::size_t* pos = \fB(1)\fP \fI(since C++11)\fP + nullptr ); + float stof ( const std::wstring& str, std::size_t* pos = \fB(2)\fP \fI(since C++11)\fP + nullptr ); + double stod ( const std::string& str, std::size_t* pos = \fB(3)\fP \fI(since C++11)\fP + nullptr ); + double stod ( const std::wstring& str, std::size_t* pos = \fB(4)\fP \fI(since C++11)\fP + nullptr ); + long double stold( const std::string& str, std::size_t* pos = \fB(5)\fP \fI(since C++11)\fP + nullptr ); + long double stold( const std::wstring& str, std::size_t* pos = \fB(6)\fP \fI(since C++11)\fP + nullptr ); Interprets a floating point value in a string str. - 1) calls std::strtod(str.c_str(), pos) - 2) calls std::strtod(str.c_str(), pos) - 3) calls std::strtold(str.c_str(), pos) + Let ptr be an internal (to the conversion functions) pointer of type char* (1,3,5) + or wchar_t* (2,4,6), accordingly. + + 1) Calls std::strtof(str.c_str(), &ptr). + 2) Calls std::wcstof(str.c_str(), &ptr). + 3) Calls std::strtod(str.c_str(), &ptr). + 4) Calls std::wcstod(str.c_str(), &ptr). + 5) Calls std::strtold(str.c_str(), &ptr). + 6) Calls std::wcstold(str.c_str(), &ptr). - Function discards any whitespace characters (as determined by std::isspace()) until + Function discards any whitespace characters (as determined by std::isspace) until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid floating point representation and converts them to floating - point value. The valid floating point value can be one of the following: + possible to form a valid floating-point representation and converts them to a + floating-point value. The valid floating-point value can be one of the following: - * decimal floating point expression. It consists of the following parts: + * decimal floating-point expression. It consists of the following parts: * (optional) plus or minus sign - * nonempty sequence of decimal digits optionally containing a decimal point - character (defines significand) + * nonempty sequence of decimal digits optionally containing decimal-point + character (as determined by the current C locale) (defines significand) * (optional) e or E followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) - - * binary floating point expression. It consists of the following parts: + sequence of decimal digits (defines exponent to base 10) + * hexadecimal floating-point expression. It consists of the following parts: * (optional) plus or minus sign * 0x or 0X - * nonempty sequence of hexadecimal digits optionally containing a decimal point - character (defines significand) + * nonempty sequence of hexadecimal digits optionally containing a decimal-point + character (as determined by the current C locale) (defines significand) * (optional) p or P followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) - + sequence of decimal digits (defines exponent to base 2) * infinity expression. It consists of the following parts: * (optional) plus or minus sign * INF or INFINITY ignoring case - * not-a-number expression. It consists of the following parts: * (optional) plus or minus sign * NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only - contain alphanumeric characters. The result is a quiet NaN floating point value. + contain digits, Latin letters, and underscores. The result is a quiet NaN + floating-point value. + * any other expression that may be accepted by the currently installed C locale - The index of the first unconverted character is stored in pos. If NULL is passed as - pos, it is ignored. + If pos is not a null pointer, then ptr will receive the address of the first + unconverted character in str.c_str(), and the index of that character will be + calculated and stored in *pos, giving the number of characters that were processed + by the conversion. .SH Parameters str - the string to convert - pos - address of integer to store the index of the first unconverted character + pos - address of an integer to store the number of characters processed .SH Return value @@ -58,20 +77,44 @@ .SH Exceptions - std::invalid_argument if no conversion could be performed + std::invalid_argument if no conversion could be performed. std::out_of_range if the converted value would fall out of the range of the result - type or if the underlying function (strtod or strtold) sets errno to ERANGE. + type or if the underlying function (std::strtof, std::strtod or std::strtold) sets + errno to ERANGE. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::out_of_range would not be thrown + LWG 2009 C++11 if the converted will throw + value would fall out of the range of + the result type + LWG 2403 C++11 stof called std::strtod or std::wcstod stof calls std::strtof or + std::wcstof .SH See also stoi stol - stoll converts a string to a signed integer - \fI(C++11)\fP \fI(function)\fP + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP stoul - stoull converts a string to an unsigned integer - \fI(C++11)\fP \fI(function)\fP + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::stoi,std::stol,std::stoll.3 b/man/std::stoi,std::stol,std::stoll.3 index f0ef86848..1c62fb26e 100644 --- a/man/std::stoi,std::stol,std::stoll.3 +++ b/man/std::stoi,std::stol,std::stoll.3 @@ -1,24 +1,38 @@ -.TH std::stoi,std::stol,std::stoll 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stoi,std::stol,std::stoll 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stoi,std::stol,std::stoll \- std::stoi,std::stol,std::stoll + .SH Synopsis Defined in header - int stoi( const std::string& str, size_t *pos = 0, int base \fB(1)\fP \fI(since C++11)\fP - = 10 ); - long stol( const std::string& str, size_t *pos = 0, int base \fB(2)\fP \fI(since C++11)\fP - = 10 ); - long long stoll( const std::string& str, size_t *pos = 0, int base \fB(3)\fP \fI(since C++11)\fP - = 10 ); + int stoi ( const std::string& str, \fB(1)\fP \fI(since C++11)\fP + std::size_t* pos = nullptr, int base = 10 ); + int stoi ( const std::wstring& str, \fB(2)\fP \fI(since C++11)\fP + std::size_t* pos = nullptr, int base = 10 ); + long stol ( const std::string& str, \fB(3)\fP \fI(since C++11)\fP + std::size_t* pos = nullptr, int base = 10 ); + long stol ( const std::wstring& str, \fB(4)\fP \fI(since C++11)\fP + std::size_t* pos = nullptr, int base = 10 ); + long long stoll( const std::string& str, \fB(5)\fP \fI(since C++11)\fP + std::size_t* pos = nullptr, int base = 10 ); + long long stoll( const std::wstring& str, \fB(6)\fP \fI(since C++11)\fP + std::size_t* pos = nullptr, int base = 10 ); Interprets a signed integer value in the string str. - 1) calls std::strtol(str.c_str(), &ptr, base) - 2) calls std::strtol(str.c_str(), &ptr, base) - 3) calls std::strtoll(str.c_str(), &ptr, base) + Let ptr be an internal (to the conversion functions) pointer of type char* (1,3,5) + or wchar_t* (2,4,6), accordingly. + + 1) Calls std::strtol(str.c_str(), &ptr, base). + 2) Calls std::wcstol(str.c_str(), &ptr, base). + 3) Calls std::strtol(str.c_str(), &ptr, base). + 4) Calls std::wcstol(str.c_str(), &ptr, base). + 5) Calls std::strtoll(str.c_str(), &ptr, base). + 6) Calls std::wcstoll(str.c_str(), &ptr, base). - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid base-n (where n=base) integer number representation and - converts them to an integer value. The valid integer value consists of the following - parts: + Discards any whitespace characters (as identified by calling std::isspace) until the + first non-whitespace character is found, then takes as many characters as possible + to form a valid base-n (where n=base) integer number representation and converts + them to an integer value. The valid integer value consists of the following parts: * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or @@ -27,83 +41,159 @@ base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. - If pos is passed a value other than 0 or nullptr, then a pointer ptr - internal to - the conversion functions - will receive the address of the first unconverted - character, and the index of that character will be calculated and stored in *pos. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type. + + If pos is not a null pointer, then ptr will receive an address of the first + unconverted character in str.c_str(), and the index of that character will be + calculated and stored in *pos, giving the number of characters that were processed + by the conversion. .SH Parameters str - the string to convert - pos - address of an integer to store the index of the first unconverted character + pos - address of an integer to store the number of characters processed base - the number base .SH Return value - The string converted to the specified signed integer type. + Integer value corresponding to the content of str. .SH Exceptions - * std::invalid_argument if no conversion could be performed + * std::invalid_argument if no conversion could be performed. * std::out_of_range if the converted value would fall out of the range of the result type or if the underlying function (std::strtol or std::strtoll) sets errno to ERANGE. .SH Example - + // Run this code + #include #include + #include #include - + #include + int main() { - std::string str1 = "45"; - std::string str2 = "3.14159"; - std::string str3 = "31337 with words"; - std::string str4 = "words and 2"; - - int myint1 = std::stoi(str1); - int myint2 = std::stoi(str2); - int myint3 = std::stoi(str3); - // error: 'std::invalid_argument' - // int myint4 = std::stoi(str4); - - std::cout << "std::stoi(\\"" << str1 << "\\") is " << myint1 << '\\n'; - std::cout << "std::stoi(\\"" << str2 << "\\") is " << myint2 << '\\n'; - std::cout << "std::stoi(\\"" << str3 << "\\") is " << myint3 << '\\n'; - //std::cout << "std::stoi(\\"" << str4 << "\\") is " << myint4 << '\\n'; + const auto data = + { + "45", + "+45", + " -45", + "3.14159", + "31337 with words", + "words and 2", + "12345678901", + }; + + for (const std::string s : data) + { + std::size_t pos{}; + try + { + std::cout << "std::stoi(" << std::quoted(s) << "): "; + const int i{std::stoi(s, &pos)}; + std::cout << i << "; pos: " << pos << '\\n'; + } + catch (std::invalid_argument const& ex) + { + std::cout << "std::invalid_argument::what(): " << ex.what() << '\\n'; + } + catch (std::out_of_range const& ex) + { + std::cout << "std::out_of_range::what(): " << ex.what() << '\\n'; + const long long ll{std::stoll(s, &pos)}; + std::cout << "std::stoll(" << std::quoted(s) << "): " << ll + << "; pos: " << pos << '\\n'; + } + } + + std::cout << "\\nCalling with different radixes:\\n"; + for (const auto& [s, base] : {std::pair + {"11", 2}, {"22", 3}, {"33", 4}, {"77", 8}, + {"99", 10}, {"FF", 16}, {"jJ", 20}, {"Zz", 36}}) + { + const int i{std::stoi(s, nullptr, base)}; + std::cout << "std::stoi(" << std::quoted(s) + << ", nullptr, " << base << "): " << i << '\\n'; + } } -.SH Output: - - std::stoi("45") is 45 - std::stoi("3.14159") is 3 - std::stoi("31337 with words") is 31337 +.SH Possible output: + + std::stoi("45"): 45; pos: 2 + std::stoi("+45"): 45; pos: 3 + std::stoi(" -45"): -45; pos: 4 + std::stoi("3.14159"): 3; pos: 1 + std::stoi("31337 with words"): 31337; pos: 5 + std::stoi("words and 2"): std::invalid_argument::what(): stoi + std::stoi("12345678901"): std::out_of_range::what(): stoi + std::stoll("12345678901"): 12345678901; pos: 11 + + Calling with different radixes: + std::stoi("11", nullptr, 2): 3 + std::stoi("22", nullptr, 3): 8 + std::stoi("33", nullptr, 4): 15 + std::stoi("77", nullptr, 8): 63 + std::stoi("99", nullptr, 10): 99 + std::stoi("FF", nullptr, 16): 255 + std::stoi("jJ", nullptr, 20): 399 + std::stoi("Zz", nullptr, 36): 1295 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::out_of_range would not be thrown if + LWG 2009 C++11 std::strtol or std::strtoll sets errno to will throw + ERANGE .SH See also - atoi converts a byte string to an integer value - atol \fI(function)\fP - atoll stoul - stoull converts a string to an unsigned integer - \fI(C++11)\fP \fI(function)\fP + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP stof stod - stold converts a string to a floating point value - \fI(C++11)\fP \fI(function)\fP + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + strtol converts a byte string to an integer value + strtoll \fI(function)\fP + \fI(C++11)\fP + strtoul converts a byte string to an unsigned integer value + strtoull \fI(function)\fP + \fI(C++11)\fP + strtoimax + strtoumax converts a byte string to std::intmax_t or std::uintmax_t + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + atoi + atol converts a byte string to an integer value + atoll \fI(function)\fP \fI(C++11)\fP - to_string converts an integral or floating point value to string - \fI(C++11)\fP \fI(function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::stop_callback.3 b/man/std::stop_callback.3 new file mode 100644 index 000000000..384405b81 --- /dev/null +++ b/man/std::stop_callback.3 @@ -0,0 +1,146 @@ +.TH std::stop_callback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_callback \- std::stop_callback + +.SH Synopsis + Defined in header + template< class Callback > \fI(since C++20)\fP + class stop_callback; + + The stop_callback class template provides an RAII object type that registers a + callback function for an associated std::stop_token object, such that the callback + function will be invoked when the std::stop_token's associated std::stop_source is + requested to stop. + + Callback functions registered via stop_callback's constructor are invoked either in + the same thread that successfully invokes request_stop() for a std::stop_source of + the stop_callback's associated std::stop_token; or if stop has already been + requested prior to the constructor's registration, then the callback is invoked in + the thread constructing the stop_callback. + + More than one stop_callback can be created for the same std::stop_token, from the + same or different threads concurrently. No guarantee is provided for the order in + which they will be executed, but they will be invoked synchronously; except for + stop_callback(s) constructed after stop has already been requested for the + std::stop_token, as described previously. + + If an invocation of a callback exits via an exception then std::terminate is called. + + std::stop_callback is not CopyConstructible, CopyAssignable, MoveConstructible, nor + MoveAssignable. + + The template param Callback type must be both invocable and destructible. Any return + value is ignored. + +.SH Member types + + Type Definition + callback_type Callback + +.SH Member functions + + constructor constructs new stop_callback object + \fI(public member function)\fP + destructor destructs the stop_callback object + \fI(public member function)\fP + operator= stop_callback is not assignable + [deleted] \fI(public member function)\fP + + Deduction guides + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + // Use a helper class for atomic std::cout streaming. + class Writer + { + std::ostringstream buffer; + public: + ~Writer() + { + std::cout << buffer.str(); + } + Writer& operator<<(auto input) + { + buffer << input; + return *this; + } + }; + + int main() + { + // A worker thread. + // It will wait until it is requested to stop. + std::jthread worker([] (std::stop_token stoken) + { + Writer() << "Worker thread's id: " << std::this_thread::get_id() << '\\n'; + std::mutex mutex; + std::unique_lock lock(mutex); + std::condition_variable_any().wait(lock, stoken, + [&stoken] { return stoken.stop_requested(); }); + }); + + // Register a stop callback on the worker thread. + std::stop_callback callback(worker.get_stop_token(), [] + { + Writer() << "Stop callback executed by thread: " + << std::this_thread::get_id() << '\\n'; + }); + + // Stop_callback objects can be destroyed prematurely to prevent execution. + { + std::stop_callback scoped_callback(worker.get_stop_token(), [] + { + // This will not be executed. + Writer() << "Scoped stop callback executed by thread: " + << std::this_thread::get_id() << '\\n'; + }); + } + + // Demonstrate which thread executes the stop_callback and when. + // Define a stopper function. + auto stopper_func = [&worker] + { + if (worker.request_stop()) + Writer() << "Stop request executed by thread: " + << std::this_thread::get_id() << '\\n'; + else + Writer() << "Stop request not executed by thread: " + << std::this_thread::get_id() << '\\n'; + }; + + // Let multiple threads compete for stopping the worker thread. + std::jthread stopper1(stopper_func); + std::jthread stopper2(stopper_func); + stopper1.join(); + stopper2.join(); + + // After a stop has already been requested, + // a new stop_callback executes immediately. + Writer() << "Main thread: " << std::this_thread::get_id() << '\\n'; + std::stop_callback callback_after_stop(worker.get_stop_token(), [] + { + Writer() << "Stop callback executed by thread: " + << std::this_thread::get_id() << '\\n'; + }); + } + +.SH Possible output: + + Worker thread's id: 140460265039616 + Stop callback executed by thread: 140460256646912 + Stop request executed by thread: 140460256646912 + Stop request not executed by thread: 140460248254208 + Main thread: 140460265043776 + Stop callback executed by thread: 140460265043776 diff --git a/man/std::stop_callback::stop_callback.3 b/man/std::stop_callback::stop_callback.3 new file mode 100644 index 000000000..6d7e97466 --- /dev/null +++ b/man/std::stop_callback::stop_callback.3 @@ -0,0 +1,49 @@ +.TH std::stop_callback::stop_callback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_callback::stop_callback \- std::stop_callback::stop_callback + +.SH Synopsis + template< class C > + explicit stop_callback( const std::stop_token& st, C&& cb ) \fB(1)\fP \fI(since C++20)\fP + noexcept(/*see below*/); + template< class C > + explicit stop_callback( std::stop_token&& st, C&& cb ) \fB(2)\fP \fI(since C++20)\fP + noexcept(/*see below*/); + stop_callback( const stop_callback& ) = delete; \fB(3)\fP \fI(since C++20)\fP + stop_callback( stop_callback&& ) = delete; \fB(4)\fP \fI(since C++20)\fP + + Constructs a new stop_callback object, saving and registering the cb callback + function into the given std::stop_token's associated stop-state, for later + invocation if stop is requested on the associated std::stop_source. + + 1) Constructs a stop_callback for the given st std::stop_token (copied), with the + given invocable callback function cb. + 2) Constructs a stop_callback for the given st std::stop_token (moved), with the + given invocable callback function cb. + 3,4) stop_callback is neither CopyConstructible nor MoveConstructible. + + Both constructors participate overload resolution only if Callback and C satisfy + constructible_from of std::constructible_from. If Callback and C + satisfy the concept but fail to satisfy its semantic requirement, the behavior is + undefined. + +.SH Parameters + + st - a std::stop_token object to register this stop_callback object with + cb - the type to invoke if stop is requested + +.SH Exceptions + + 1,2) + noexcept specification: + noexcept(std::is_nothrow_constructible_v) + Any exception thrown by constructor-initializing the given callback into the + stop_callback object. + +.SH Notes + + If st.stop_requested() == true for the passed-in std::stop_token, then the callback + function is invoked in the current thread before the constructor returns. + +.SH Category: + * conditionally noexcept diff --git a/man/std::stop_callback::~stop_callback.3 b/man/std::stop_callback::~stop_callback.3 new file mode 100644 index 000000000..5586805ed --- /dev/null +++ b/man/std::stop_callback::~stop_callback.3 @@ -0,0 +1,32 @@ +.TH std::stop_callback::~stop_callback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_callback::~stop_callback \- std::stop_callback::~stop_callback + +.SH Synopsis + ~stop_callback(); \fI(since C++20)\fP + + Destroys the stop_callback object. + + If *this has a stop_token with associated stop-state, deregisters the callback from + it. + + If the callback function is being invoked concurrently on another thread, the + destructor does not complete until the callback function invocation is complete. If + the callback function is being invoked on the same thread the destructor is being + invoked on, then the destructor returns without waiting for callback invocation to + complete (see Notes). + +.SH Notes + + The stop_callback destructor is designed to prevent race conditions and deadlocks. + If another thread is currently invoking the callback, then the destructor cannot + return until that completes, or else the function object could potentially be + destroyed while it is being executed. The callback function is not required to be + neither copyable nor movable - it lives in the stop_callback object itself even + after registration. + + On the other hand, if the current thread invoking the destructor is the same thread + that is invoking the callback, then the destructor cannot wait or else a deadlock + would occur. It is possible and valid for the same thread to be destroying the + stop_callback while it is invoking its callback function, because the callback + function might itself destroy the stop_callback, directly or indirectly. diff --git a/man/std::stop_source.3 b/man/std::stop_source.3 new file mode 100644 index 000000000..5ddd5b7ef --- /dev/null +++ b/man/std::stop_source.3 @@ -0,0 +1,140 @@ +.TH std::stop_source 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source \- std::stop_source + +.SH Synopsis + Defined in header + class stop_source; \fI(since C++20)\fP + + The stop_source class provides the means to issue a stop request, such as for + std::jthread cancellation. A stop request made for one stop_source object is visible + to all stop_sources and std::stop_tokens of the same associated stop-state; any + std::stop_callback(s) registered for associated std::stop_token(s) will be invoked, + and any std::condition_variable_any objects waiting on associated std::stop_token(s) + will be awoken. + + Once a stop is requested, it cannot be withdrawn. Additional stop requests have no + effect. + +.SH Member functions + + constructor constructs new stop_source object + \fI(public member function)\fP + destructor destructs the stop_source object + \fI(public member function)\fP + operator= assigns the stop_source object + \fI(public member function)\fP +.SH Modifiers + request_stop makes a stop request for the associated stop-state, if any + \fI(public member function)\fP + swap swaps two stop_source objects + \fI(public member function)\fP +.SH Observers + get_token returns a stop_token for the associated stop-state + \fI(public member function)\fP + stop_requested checks whether the associated stop-state has been requested to stop + \fI(public member function)\fP + stop_possible checks whether associated stop-state can be requested to stop + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares two std::stop_source objects + \fI(function)\fP + swap(std::stop_source) specializes the std::swap algorithm + (C++20) \fI(function)\fP + + Helper constants + + nostopstate a std::nostopstate_t instance for use in stop_source constructor + (C++20) (constant) + +.SH Helper classes + + nostopstate_t placeholder type for use in stop_source constructor + (C++20) \fI(class)\fP + +.SH Notes + + For the purposes of std::jthread cancellation the stop_source object should be + retrieved from the std::jthread object using get_stop_source(); or stop should be + requested directly from the std::jthread object using request_stop(). This will then + use the same associated stop-state as that passed into the std::jthread's invoked + function argument (i.e., the function being executed on its thread). + + For other uses, however, a stop_source can be constructed separately using the + default constructor, which creates new stop-state. + + Feature-test macro Value Std Feature + __cpp_lib_jthread 201911L (C++20) Stop token and joining thread + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + using namespace std::chrono_literals; + + void worker_fun(int id, std::stop_source stop_source) + { + std::stop_token stoken = stop_source.get_token(); + for (int i = 10; i; --i) + { + std::this_thread::sleep_for(300ms); + if (stoken.stop_requested()) + { + std::printf(" worker%d is requested to stop\\n", id); + return; + } + std::printf(" worker%d goes back to sleep\\n", id); + } + } + + int main() + { + std::jthread threads[4]; + std::cout << std::boolalpha; + auto print = [](const std::stop_source& source) + { + std::printf("stop_source stop_possible = %s, stop_requested = %s\\n", + source.stop_possible() ? "true" : "false", + source.stop_requested() ? "true" : "false"); + }; + + // Common source + std::stop_source stop_source; + + print(stop_source); + + // Create worker threads + for (int i = 0; i < 4; ++i) + threads[i] = std::jthread(worker_fun, i + 1, stop_source); + + std::this_thread::sleep_for(500ms); + + std::puts("Request stop"); + stop_source.request_stop(); + + print(stop_source); + + // Note: destructor of jthreads will call join so no need for explicit calls + } + +.SH Possible output: + + stop_source stop_possible = true, stop_requested = false + worker2 goes back to sleep + worker3 goes back to sleep + worker1 goes back to sleep + worker4 goes back to sleep + Request stop + stop_source stop_possible = true, stop_requested = true + worker3 is requested to stop + worker1 is requested to stop + worker2 is requested to stop + worker4 is requested to stop diff --git a/man/std::stop_source::get_token.3 b/man/std::stop_source::get_token.3 new file mode 100644 index 000000000..a3cdc535d --- /dev/null +++ b/man/std::stop_source::get_token.3 @@ -0,0 +1,26 @@ +.TH std::stop_source::get_token 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::get_token \- std::stop_source::get_token + +.SH Synopsis + [[nodiscard]] std::stop_token get_token() const noexcept; \fI(since C++20)\fP + + Returns a stop_token object associated with the stop_source's stop-state, if the + stop_source has stop-state; otherwise returns a default-constructed (empty) + stop_token. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A stop_token object, which will be empty if this->stop_possible() == false. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stop_source::operator=.3 b/man/std::stop_source::operator=.3 new file mode 100644 index 000000000..e1993e0f1 --- /dev/null +++ b/man/std::stop_source::operator=.3 @@ -0,0 +1,21 @@ +.TH std::stop_source::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::operator= \- std::stop_source::operator= + +.SH Synopsis + std::stop_source& operator=( const std::stop_source& other ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + std::stop_source& operator=( std::stop_source&& other ) noexcept; \fB(2)\fP \fI(since C++20)\fP + + Replaces the stop-state with that of other. + + 1) Copy-assigns the stop-state of other to that of *this. Equivalent to + stop_source(other).swap(*this). + 2) Move-assigns the stop-state of other to that of *this. After the assignment, + *this contains the previous stop-state of other, and other has no stop-state. + Equivalent to stop_source(std::move(other)).swap(*this). + +.SH Parameters + + other - another stop_source object to share the stop-state with to or acquire the + stop-state from diff --git a/man/std::stop_source::request_stop.3 b/man/std::stop_source::request_stop.3 new file mode 100644 index 000000000..d14737c0e --- /dev/null +++ b/man/std::stop_source::request_stop.3 @@ -0,0 +1,57 @@ +.TH std::stop_source::request_stop 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::request_stop \- std::stop_source::request_stop + +.SH Synopsis + bool request_stop() noexcept; \fI(since C++20)\fP + + Issues a stop request to the stop-state, if the stop_source object has a stop-state + and it has not yet already had stop requested. + + The determination is made atomically, and if stop was requested, the stop-state is + atomically updated to avoid race conditions, such that: + + * stop_requested() and stop_possible() can be concurrently invoked on other + stop_tokens and stop_sources of the same stop-state; + * request_stop() can be concurrently invoked on other stop_source objects, and + only one will actually perform the stop request. + + However, see the Notes section. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stop_source object has a stop-state and this invocation made a stop + request, otherwise false. + +.SH Postconditions + + stop_possible() is false or stop_requested() is true. + +.SH Notes + + If the request_stop() does issue a stop request (i.e., returns true), then any + stop_callbacks registered for the same associated stop-state will be invoked + synchronously, on the same thread request_stop() is issued on. If an invocation of a + callback exits via an exception, std::terminate is called. + + If the stop_source object has a stop-state but a stop request has already been made, + this function returns false. However there is no guarantee that another stop_source + object which has just (successfully) requested stop is not still in the middle of + invoking a stop_callback function. + + If the request_stop() does issue a stop request (i.e., returns true), then all + condition variables of base type std::condition_variable_any registered with an + interruptible wait for stop_tokens associated with the stop_source's stop-state will + be notified. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stop_source::stop_possible.3 b/man/std::stop_source::stop_possible.3 new file mode 100644 index 000000000..73099c1e2 --- /dev/null +++ b/man/std::stop_source::stop_possible.3 @@ -0,0 +1,29 @@ +.TH std::stop_source::stop_possible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::stop_possible \- std::stop_source::stop_possible + +.SH Synopsis + [[nodiscard]] bool stop_possible() const noexcept; \fI(since C++20)\fP + + Checks if the stop_source object has a stop-state. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stop_source object has a stop-state, otherwise false. + +.SH Notes + + If the stop_source object has a stop-state and a stop request has already been made, + this function still returns true. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stop_source::stop_requested.3 b/man/std::stop_source::stop_requested.3 new file mode 100644 index 000000000..2624c745f --- /dev/null +++ b/man/std::stop_source::stop_requested.3 @@ -0,0 +1,26 @@ +.TH std::stop_source::stop_requested 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::stop_requested \- std::stop_source::stop_requested + +.SH Synopsis + [[nodiscard]] bool stop_requested() const noexcept; \fI(since C++20)\fP + + Checks if the stop_source object has a stop-state and that state has received a stop + request. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stop_token object has a stop-state and it has received a stop request, + false otherwise. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stop_source::stop_source.3 b/man/std::stop_source::stop_source.3 new file mode 100644 index 000000000..d0594e6d8 --- /dev/null +++ b/man/std::stop_source::stop_source.3 @@ -0,0 +1,35 @@ +.TH std::stop_source::stop_source 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::stop_source \- std::stop_source::stop_source + +.SH Synopsis + stop_source(); \fB(1)\fP \fI(since C++20)\fP + explicit stop_source( std::nostopstate_t nss ) noexcept; \fB(2)\fP \fI(since C++20)\fP + stop_source( const stop_source& other ) noexcept; \fB(3)\fP \fI(since C++20)\fP + stop_source( stop_source&& other ) noexcept; \fB(4)\fP \fI(since C++20)\fP + + Constructs a new stop_source object. + + 1) Constructs a stop_source with new stop-state. + 2) Constructs an empty stop_source with no associated stop-state. + 3) Copy constructor. Constructs a stop_source whose associated stop-state is the + same as that of other. + 4) Move constructor. Constructs a stop_source whose associated stop-state is the + same as that of other; other is left empty. + +.SH Parameters + + nss - an std::nostopstate_t placeholder object to construct an empty stop_source + other - another stop_source object to construct this stop_source object with + +.SH Postconditions + + 1) stop_possible() is true and stop_requested() is false. + 2) stop_possible() and stop_requested() are both false. + 3) *this and other share the same associated stop-state and compare equal. + 4) *this has other's previously associated stop-state, and other.stop_possible() is + false. + +.SH Exceptions + + 1) std::bad_alloc if memory could not be allocated for the stop-state. diff --git a/man/std::stop_source::swap.3 b/man/std::stop_source::swap.3 new file mode 100644 index 000000000..5dc1dfcf8 --- /dev/null +++ b/man/std::stop_source::swap.3 @@ -0,0 +1,16 @@ +.TH std::stop_source::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::swap \- std::stop_source::swap + +.SH Synopsis + void swap( std::stop_source& other ) noexcept; \fI(since C++20)\fP + + Exchanges the stop-state of *this and other. + +.SH Parameters + + other - stop_source to exchange the contents with + +.SH Return value + + \fI(none)\fP diff --git a/man/std::stop_source::~stop_source.3 b/man/std::stop_source::~stop_source.3 new file mode 100644 index 000000000..7d94a0e32 --- /dev/null +++ b/man/std::stop_source::~stop_source.3 @@ -0,0 +1,10 @@ +.TH std::stop_source::~stop_source 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_source::~stop_source \- std::stop_source::~stop_source + +.SH Synopsis + ~stop_source(); \fI(since C++20)\fP + + Destroys the stop_source object. + + If *this has associated stop-state, releases ownership of it. diff --git a/man/std::stop_token.3 b/man/std::stop_token.3 new file mode 100644 index 000000000..59fc4c072 --- /dev/null +++ b/man/std::stop_token.3 @@ -0,0 +1,81 @@ +.TH std::stop_token 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token \- std::stop_token + +.SH Synopsis + Defined in header + class stop_token; \fI(since C++20)\fP + + The stop_token class provides the means to check if a stop request has been made or + can be made, for its associated std::stop_source object. It is essentially a + thread-safe "view" of the associated stop-state. + + The stop_token can also be passed to the constructor of std::stop_callback, such + that the callback will be invoked if the stop_token's associated std::stop_source is + requested to stop. And stop_token can be passed to the interruptible waiting + functions of std::condition_variable_any, to interrupt the condition variable's wait + if stop is requested. + +.SH Member functions + + constructor constructs new stop_token object + \fI(public member function)\fP + destructor destructs the stop_token object + \fI(public member function)\fP + operator= assigns the stop_token object + \fI(public member function)\fP +.SH Modifiers + swap swaps two stop_token objects + \fI(public member function)\fP +.SH Observers + stop_requested checks whether the associated stop-state has been requested to stop + \fI(public member function)\fP + stop_possible checks whether associated stop-state can be requested to stop + \fI(public member function)\fP + +.SH Non-member functions + + operator== compares two std::stop_token objects + \fI(function)\fP + swap(std::stop_token) specializes the std::swap algorithm + (C++20) \fI(function)\fP + +.SH Notes + + A stop_token object is not generally constructed independently, but rather retrieved + from a std::jthread or std::stop_source. This makes it share the same associated + stop-state as the std::jthread or std::stop_source. + + Feature-test macro Value Std Feature + __cpp_lib_jthread 201911L (C++20) Stop token and joining thread + +.SH Example + + +// Run this code + + #include + #include + + using namespace std::literals::chrono_literals; + + void f(std::stop_token stop_token, int value) + { + while (!stop_token.stop_requested()) + { + std::cout << value++ << ' ' << std::flush; + std::this_thread::sleep_for(200ms); + } + std::cout << std::endl; + } + + int main() + { + std::jthread thread(f, 5); // prints 5 6 7 8... for approximately 3 seconds + std::this_thread::sleep_for(3s); + // The destructor of jthread calls request_stop() and join(). + } + +.SH Possible output: + + 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 diff --git a/man/std::stop_token::operator=.3 b/man/std::stop_token::operator=.3 new file mode 100644 index 000000000..55dbe2949 --- /dev/null +++ b/man/std::stop_token::operator=.3 @@ -0,0 +1,22 @@ +.TH std::stop_token::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token::operator= \- std::stop_token::operator= + +.SH Synopsis + std::stop_token& operator=( const std::stop_token& other ) \fB(1)\fP \fI(since C++20)\fP + noexcept; + std::stop_token& operator=( std::stop_token&& other ) noexcept; \fB(2)\fP \fI(since C++20)\fP + + Replaces the associated stop-state with that of other. + + 1) Copy-assigns the associated stop-state of other to that of *this. Equivalent to + stop_token(other).swap(*this). + 2) Move-assigns the associated stop-state of other to that of *this. After the + assignment, *this contains the previous associated stop-state of other, and other + has no associated stop-state. Equivalent to + stop_token(std::move(other)).swap(*this). + +.SH Parameters + + other - another stop_token object to share the stop-state with to or acquire the + stop-state from diff --git a/man/std::stop_token::stop_possible.3 b/man/std::stop_token::stop_possible.3 new file mode 100644 index 000000000..d0b27efc0 --- /dev/null +++ b/man/std::stop_token::stop_possible.3 @@ -0,0 +1,123 @@ +.TH std::stop_token::stop_possible 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token::stop_possible \- std::stop_token::stop_possible + +.SH Synopsis + [[nodiscard]] bool stop_possible() const noexcept; \fI(since C++20)\fP + + Checks if the stop_token object has associated stop-state, and that state either has + already had a stop requested or it has associated std::stop_source object(s). + + A default constructed stop_token has no associated stop-state, and thus cannot be + stopped; the associated stop-state for which no std::stop_source object(s) exist can + also not be stopped if such a request has not already been made. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + false if the stop_token object has no associated stop-state, or it did not yet + receive a stop request and there are no associated std::stop_source object(s); true + otherwise. + +.SH Notes + + If the stop_token object has associated stop-state and a stop request has already + been made, this function still returns true. + + If the stop_token object has associated stop-state from a std::jthread—for example, + the stop_token was retrieved by invoking get_stop_token() on a std::jthread + object—then this function always returns true. A std::jthread always has an internal + std::stop_source object, even if the thread's invoking function does not check it. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + using namespace std::chrono_literals; + + int main() + { + std::cout << std::boolalpha; + auto print = [](std::string_view name, const std::stop_token& token) + { + std::cout << std::format("{}: stop_possible = {:s}, stop_requested = {:s}\\n", + name, token.stop_possible(), token.stop_requested() + ); + }; + + // A worker thread that will listen to stop requests + auto stop_worker = std::jthread([](std::stop_token stoken) + { + for (int i = 10; i; --i) + { + std::this_thread::sleep_for(300ms); + if (stoken.stop_requested()) + { + std::cout << " Sleepy worker is requested to stop\\n"; + return; + } + std::cout << " Sleepy worker goes back to sleep\\n"; + } + }); + + // A worker thread that will only stop when completed + auto inf_worker = std::jthread([]() + { + for (int i = 5; i; --i) + { + std::this_thread::sleep_for(300ms); + std::cout << " Run as long as we want\\n"; + } + }); + + std::stop_token def_token; + std::stop_token stop_token = stop_worker.get_stop_token(); + std::stop_token inf_token = inf_worker.get_stop_token(); + print("def_token ", def_token); + print("stop_token", stop_token); + print("inf_token ", inf_token); + + std::cout << "\\nRequest and join stop_worker:\\n"; + stop_worker.request_stop(); + stop_worker.join(); + + std::cout << "\\nRequest and join inf_worker:\\n"; + inf_worker.request_stop(); + inf_worker.join(); + std::cout << '\\n'; + + print("def_token ", def_token); + print("stop_token", stop_token); + print("inf_token ", inf_token); + } + +.SH Possible output: + + def_token : stop_possible = false, stop_requested = false + stop_token: stop_possible = true, stop_requested = false + inf_token : stop_possible = true, stop_requested = false + + Request and join stop_worker: + Run as long as we want + Sleepy worker is requested to stop + + Request and join inf_worker: + Run as long as we want + Run as long as we want + Run as long as we want + Run as long as we want + + def_token : stop_possible = false, stop_requested = false + stop_token: stop_possible = true, stop_requested = true + inf_token : stop_possible = true, stop_requested = true diff --git a/man/std::stop_token::stop_requested.3 b/man/std::stop_token::stop_requested.3 new file mode 100644 index 000000000..8cb28fd7a --- /dev/null +++ b/man/std::stop_token::stop_requested.3 @@ -0,0 +1,107 @@ +.TH std::stop_token::stop_requested 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token::stop_requested \- std::stop_token::stop_requested + +.SH Synopsis + [[nodiscard]] bool stop_requested() const noexcept; \fI(since C++20)\fP + + Checks if the stop_token object has associated stop-state and that state has + received a stop request. A default constructed stop_token has no associated + stop-state, and thus has not had stop requested. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stop_token object has associated stop-state and it received a stop + request, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + using namespace std::chrono_literals; + + int main() + { + std::cout << std::boolalpha; + auto print = [](std::string_view name, const std::stop_token& token) + { + std::cout << name << ": stop_possible = " << token.stop_possible(); + std::cout << ", stop_requested = " << token.stop_requested() << '\\n'; + }; + + // A worker thread that will listen to stop requests + auto stop_worker = std::jthread([](std::stop_token stoken) + { + for (int i = 10; i; --i) + { + std::this_thread::sleep_for(300ms); + if (stoken.stop_requested()) + { + std::cout << " Sleepy worker is requested to stop\\n"; + return; + } + std::cout << " Sleepy worker goes back to sleep\\n"; + } + }); + + // A worker thread that will only stop when completed + auto inf_worker = std::jthread([]() + { + for (int i = 5; i; --i) + { + std::this_thread::sleep_for(300ms); + std::cout << " Run as long as we want\\n"; + } + }); + + std::stop_token def_token; + std::stop_token stop_token = stop_worker.get_stop_token(); + std::stop_token inf_token = inf_worker.get_stop_token(); + print("def_token ", def_token); + print("stop_token", stop_token); + print("inf_token ", inf_token); + + std::cout << "\\nRequest and join stop_worker:\\n"; + stop_worker.request_stop(); + stop_worker.join(); + + std::cout << "\\nRequest and join inf_worker:\\n"; + inf_worker.request_stop(); + inf_worker.join(); + std::cout << '\\n'; + + print("def_token ", def_token); + print("stop_token", stop_token); + print("inf_token ", inf_token); + } + +.SH Possible output: + + def_token : stop_possible = false, stop_requested = false + stop_token: stop_possible = true, stop_requested = false + inf_token : stop_possible = true, stop_requested = false + + Request and join stop_worker: + Run as long as we want + Sleepy worker is requested to stop + + Request and join inf_worker: + Run as long as we want + Run as long as we want + Run as long as we want + Run as long as we want + + def_token : stop_possible = false, stop_requested = false + stop_token: stop_possible = true, stop_requested = true + inf_token : stop_possible = true, stop_requested = true diff --git a/man/std::stop_token::stop_token.3 b/man/std::stop_token::stop_token.3 new file mode 100644 index 000000000..5d3d581b2 --- /dev/null +++ b/man/std::stop_token::stop_token.3 @@ -0,0 +1,27 @@ +.TH std::stop_token::stop_token 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token::stop_token \- std::stop_token::stop_token + +.SH Synopsis + stop_token() noexcept; \fB(1)\fP \fI(since C++20)\fP + stop_token( const stop_token& other ) noexcept; \fB(2)\fP \fI(since C++20)\fP + stop_token( stop_token&& other ) noexcept; \fB(3)\fP \fI(since C++20)\fP + + Constructs a new stop_token object. + + 1) Constructs an empty stop_token with no associated stop-state. + 2) Copy constructor. Constructs a stop_token whose associated stop-state is the same + as that of other. + 3) Move constructor. Constructs a stop_token whose associated stop-state is the same + as that of other; other is left empty. + +.SH Parameters + + other - another stop_token object to construct this stop_token object with + +.SH Postconditions + + 1) stop_possible() and stop_requested() are both false. + 2) *this and other share the same associated stop-state and compare equal. + 3) *this has other's previously associated stop-state, and other.stop_possible() is + false. diff --git a/man/std::stop_token::swap.3 b/man/std::stop_token::swap.3 new file mode 100644 index 000000000..d50f29559 --- /dev/null +++ b/man/std::stop_token::swap.3 @@ -0,0 +1,16 @@ +.TH std::stop_token::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token::swap \- std::stop_token::swap + +.SH Synopsis + void swap( std::stop_token& other ) noexcept; \fI(since C++20)\fP + + Exchanges the associated stop-state of *this and other. + +.SH Parameters + + other - stop_token to exchange the contents with + +.SH Return value + + \fI(none)\fP diff --git a/man/std::stop_token::~stop_token.3 b/man/std::stop_token::~stop_token.3 new file mode 100644 index 000000000..d76c410ce --- /dev/null +++ b/man/std::stop_token::~stop_token.3 @@ -0,0 +1,10 @@ +.TH std::stop_token::~stop_token 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stop_token::~stop_token \- std::stop_token::~stop_token + +.SH Synopsis + ~stop_token(); \fI(since C++20)\fP + + Destroys the stop_token object. + + If *this has associated stop-state, releases ownership of it. diff --git a/man/std::stoul,std::stoull.3 b/man/std::stoul,std::stoull.3 index 322426bdd..94ef5af1f 100644 --- a/man/std::stoul,std::stoull.3 +++ b/man/std::stoul,std::stoull.3 @@ -1,44 +1,69 @@ -.TH std::stoul,std::stoull 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::stoul,std::stoull 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::stoul,std::stoull \- std::stoul,std::stoull + .SH Synopsis Defined in header - unsigned long stoul( const std::string& str, size_t *pos = 0, \fB(1)\fP \fI(since C++11)\fP - int base = 10 ); - unsigned long long stoull( const std::string& str, size_t *pos = \fB(2)\fP \fI(since C++11)\fP - 0, int base = 10 ); + unsigned long stoul ( const std::string& str, + std::size_t* pos = nullptr, int base = \fB(1)\fP \fI(since C++11)\fP + 10 ); + unsigned long stoul ( const std::wstring& str, + std::size_t* pos = nullptr, int base = \fB(2)\fP \fI(since C++11)\fP + 10 ); + unsigned long long stoull( const std::string& str, + std::size_t* pos = nullptr, int base = \fB(3)\fP \fI(since C++11)\fP + 10 ); + unsigned long long stoull( const std::wstring& str, + std::size_t* pos = nullptr, int base = \fB(4)\fP \fI(since C++11)\fP + 10 ); Interprets an unsigned integer value in the string str. - 1) calls std::strtoul(str.c_str(), pos, base) - 2) calls std::strtoull(str.c_str(), pos, base) + Let ptr be an internal (to the conversion functions) pointer of type char* (1,3) or + wchar_t* (2,4), accordingly. + + 1) Calls std::strtoul(str.c_str(), &ptr, base). + 2) Calls std::wcstoul(str.c_str(), &ptr, base). + 3) Calls std::strtoull(str.c_str(), &ptr, base). + 4) Calls std::wcstoull(str.c_str(), &ptr, base). - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid base-n (where n=base) unsigned integer number - representation and converts them to an integer value. The valid unsigned integer - value consists of the following parts: + Discards any whitespace characters (as identified by calling std::isspace) until the + first non-whitespace character is found, then takes as many characters as possible + to form a valid base-n (where n=base) unsigned integer number representation and + converts them to an integer value. The valid unsigned integer value consists of the + following parts: + * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or 0) * (optional) prefix (0x or 0X) indicating hexadecimal base (applies only when the base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. - The index of the first unconverted character is stored in pos. If NULL is passed as - pos, it is ignored. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type, which + applies unsigned integer wraparound rules. + + If pos is not a null pointer, then ptr will receive the address of the first + unconverted character in str.c_str(), and the index of that character will be + calculated and stored in *pos, giving the number of characters that were processed + by the conversion. .SH Parameters str - the string to convert - pos - address of an integer to store the index of the first unconverted character + pos - address of an integer to store the number of characters processed base - the number base .SH Return value @@ -47,22 +72,40 @@ .SH Exceptions - * std::invalid_argument if no conversion could be performed + * std::invalid_argument if no conversion could be performed. * std::out_of_range if the converted value would fall out of the range of the result type or if the underlying function (std::strtoul or std::strtoull) sets errno to ERANGE. +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + std::out_of_range would not be thrown if + LWG 2009 C++11 std::strtoul or std::strtoull sets errno to will throw + ERANGE + .SH See also stoi stol stoll converts a string to a signed integer - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP stof stod stold converts a string to a floating point value - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP + +.SH Category: + * Todo no example diff --git a/man/std::strcat.3 b/man/std::strcat.3 index db4333897..fcc8ff4e8 100644 --- a/man/std::strcat.3 +++ b/man/std::strcat.3 @@ -1,13 +1,17 @@ -.TH std::strcat 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strcat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strcat \- std::strcat + .SH Synopsis Defined in header - char *strcat( char *dest, const char *src ); + char* strcat( char* dest, const char* src ); - Appends a byte string pointed to by src to a byte string pointed to by dest. The - resulting byte string is null-terminated. + Appends a copy of the character string pointed to by src to the end of the character + string pointed to by dest. The character src[0] replaces the null terminator at the + end of dest. The resulting byte string is null-terminated. - The destination byte string must have enough space for the contents of both dest and - src, plus the terminating null character. + The behavior is undefined if the destination array is not large enough for the + contents of both src and dest and the terminating null character. The behavior is undefined if the strings overlap. @@ -20,14 +24,19 @@ dest +.SH Notes + + Because strcat needs to seek to the end of dest on each call, it is inefficient to + concatenate many strings into one using strcat. + .SH Example - + // Run this code - #include #include - + #include + int main() { char str[50] = "Hello "; @@ -44,8 +53,8 @@ .SH See also strncat concatenates a certain amount of characters of two strings - \fI(function)\fP + \fI(function)\fP strcpy copies one string to another - \fI(function)\fP + \fI(function)\fP C documentation for strcat diff --git a/man/std::strchr.3 b/man/std::strchr.3 index 4a8b4e3eb..aa71a665d 100644 --- a/man/std::strchr.3 +++ b/man/std::strchr.3 @@ -1,12 +1,17 @@ -.TH std::strchr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strchr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strchr \- std::strchr + .SH Synopsis Defined in header const char* strchr( const char* str, int ch ); char* strchr( char* str, int ch ); - Finds the first occurrence of the character ch in the byte string pointed to by str. + Finds the first occurrence of the character static_cast(ch) in the byte string + pointed to by str. - The terminating null character is considered to be a part of the string. + The terminating null character is considered to be a part of the string and can be + found if searching for '\\0'. .SH Parameters @@ -15,26 +20,49 @@ .SH Return value - Pointer to the found character in str, or NULL if no such character is found. + Pointer to the found character in str, or a null pointer if no such character is + found. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + const char* str = "Try not. Do, or do not. There is no try."; + char target = 'T'; + const char* result = str; + + while ((result = std::strchr(result, target)) != nullptr) + { + std::cout << "Found '" << target + << "' starting at '" << result << "'\\n"; + + // Increment result, otherwise we'll find target at the same location + ++result; + } + } + +.SH Output: + + Found 'T' starting at 'Try not. Do, or do not. There is no try.' + Found 'T' starting at 'There is no try.' .SH See also - find find characters in the string - \fI(public member function of std::basic_string)\fP + memchr searches an array for the first occurrence of a character + \fI(function)\fP + find finds the first occurrence of the given substring + \fI(public member function of std::basic_string)\fP wcschr finds the first occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP strrchr finds the last occurrence of a character - \fI(function)\fP - strpbrk finds the first location of any character in one string, in another string - \fI(function)\fP + \fI(function)\fP + strpbrk finds the first location of any character from a set of separators + \fI(function)\fP C documentation for strchr - -.SH Category: - - * Todo no example diff --git a/man/std::strcmp.3 b/man/std::strcmp.3 index e4aaa4677..fa47ceb52 100644 --- a/man/std::strcmp.3 +++ b/man/std::strcmp.3 @@ -1,11 +1,18 @@ -.TH std::strcmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strcmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strcmp \- std::strcmp + .SH Synopsis Defined in header - int strcmp( const char *lhs, const char *rhs ); + int strcmp( const char* lhs, const char* rhs ); + + Compares two null-terminated byte strings lexicographically. - Compares two null-terminated byte strings. The comparison is done lexicographically. + The sign of the result is the sign of the difference between the values of the first + pair of characters (both interpreted as unsigned char) that differ in the strings + being compared. - Both lhs and rhs should point to valid strings. + The behavior is undefined if lhs or rhs are not pointers to null-terminated strings. .SH Parameters @@ -13,32 +20,32 @@ .SH Return value - Negative value if lhs is less than rhs. + Negative value if lhs appears before rhs in lexicographical order. - 0 if lhs is equal to rhs. + Zero if lhs and rhs compare equal. - Positive value if lhs is greater than rhs. + Positive value if lhs appears after rhs in lexicographical order. .SH Example - + // Run this code - #include - #include #include + #include #include - + #include + int main() { - std::vector cats {"Heathcliff", "Snagglepuss", "Hobbes", "Garfield"}; - std::sort(cats.begin(), cats.end(), [](const char *strA, const char *strB) { + std::vector cats{"Heathcliff", "Snagglepuss", "Hobbes", "Garfield"}; + std::sort(cats.begin(), cats.end(), [](const char* strA, const char* strB) + { return std::strcmp(strA, strB) < 0; }); - - for (const char *cat : cats) { + + for (const char* cat : cats) std::cout << cat << '\\n'; - } } .SH Output: @@ -50,11 +57,13 @@ .SH See also - strncmp compares a certain amount of characters of two strings - \fI(function)\fP + strncmp compares a certain number of characters from two strings + \fI(function)\fP + wcscmp compares two wide strings + \fI(function)\fP memcmp compares two buffers - \fI(function)\fP + \fI(function)\fP strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP C documentation for strcmp diff --git a/man/std::strcoll.3 b/man/std::strcoll.3 index 6496b75bc..e705a35ec 100644 --- a/man/std::strcoll.3 +++ b/man/std::strcoll.3 @@ -1,4 +1,7 @@ -.TH std::strcoll 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strcoll 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strcoll \- std::strcoll + .SH Synopsis Defined in header int strcoll( const char* lhs, const char* rhs ); @@ -12,11 +15,9 @@ .SH Return value - Negative value if lhs is less than (precedes) rhs. - - 0 if lhs is equal to rhs. - - Positive value if lhs is greater than (follows) rhs. + * Negative value if lhs is less than (precedes) rhs. + * 0 if lhs is equal to rhs. + * Positive value if lhs is greater than (follows) rhs. .SH Notes @@ -30,31 +31,34 @@ .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { - std::setlocale(LC_COLLATE, "cs_CZ.iso88592"); - + std::setlocale(LC_COLLATE, "cs_CZ.utf8"); + // Alternatively, ISO-8859-2 (a.k.a. Latin-2) + // may also work on some OS: + // std::setlocale(LC_COLLATE, "cs_CZ.iso88592"); + const char* s1 = "hrnec"; const char* s2 = "chrt"; - + std::cout << "In the Czech locale: "; - if(std::strcoll(s1, s2) < 0) - std::cout << s1 << " before " << s2 << '\\n'; + if (std::strcoll(s1, s2) < 0) + std::cout << s1 << " before " << s2 << '\\n'; else - std::cout << s2 << " before " << s1 << '\\n'; - + std::cout << s2 << " before " << s1 << '\\n'; + std::cout << "In lexicographical comparison: "; - if(std::strcmp(s1, s2) < 0) - std::cout << s1 << " before " << s2 << '\\n'; + if (std::strcmp(s1, s2) < 0) + std::cout << s1 << " before " << s2 << '\\n'; else - std::cout << s2 << " before " << s1 << '\\n'; + std::cout << s2 << " before " << s1 << '\\n'; } .SH Output: @@ -65,11 +69,11 @@ .SH See also wcscoll compares two wide strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP do_compare compares two strings using this facet's collation rules - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP transform a string so that strcmp would produce the same result as strxfrm strcoll - \fI(function)\fP + \fI(function)\fP C documentation for strcoll diff --git a/man/std::strcpy.3 b/man/std::strcpy.3 index 8c49ecd74..66e8bb2ee 100644 --- a/man/std::strcpy.3 +++ b/man/std::strcpy.3 @@ -1,15 +1,20 @@ -.TH std::strcpy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strcpy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strcpy \- std::strcpy + .SH Synopsis Defined in header char* strcpy( char* dest, const char* src ); - Copies the byte string pointed to by src to byte string, pointed to by dest. + Copies the character string pointed to by src, including the null terminator, to the + character array whose first element is pointed to by dest. - If the strings overlap, the behavior is undefined. + The behavior is undefined if the dest array is not large enough. The behavior is + undefined if the strings overlap. .SH Parameters - dest - pointer to the byte string to copy to + dest - pointer to the character array to write to src - pointer to the null-terminated byte string to copy from .SH Return value @@ -18,29 +23,33 @@ .SH Example - + // Run this code - #include #include - + #include + #include + int main() { - char *str = new char[100]; - std::strcpy(str, "I am string!"); - std::cout << str; - delete[] str; + const char* src = "Take the test."; + // src[0] = 'M'; // can't modify string literal + auto dst = std::make_unique(std::strlen(src) + 1); // +1 for null terminator + std::strcpy(dst.get(), src); + dst[0] = 'M'; + std::cout << src << '\\n' << dst.get() << '\\n'; } .SH Output: - I am string! + Take the test. + Make the test. .SH See also strncpy copies a certain amount of characters from one string to another - \fI(function)\fP + \fI(function)\fP memcpy copies one buffer to another - \fI(function)\fP + \fI(function)\fP C documentation for strcpy diff --git a/man/std::strcspn.3 b/man/std::strcspn.3 index dea467cd6..c77d3eced 100644 --- a/man/std::strcspn.3 +++ b/man/std::strcspn.3 @@ -1,12 +1,17 @@ -.TH std::strcspn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strcspn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strcspn \- std::strcspn + .SH Synopsis Defined in header - size_t strcspn( const char *dest, const char *src ); + std::size_t strcspn( const char *dest, const char *src ); Returns the length of the maximum initial segment of the byte string pointed to by dest, that consists of only the characters not found in byte string pointed to by src. + The function name stands for "complementary span". + .SH Parameters dest - pointer to the null-terminated byte string to be analyzed @@ -16,23 +21,51 @@ .SH Return value The length of the maximum initial segment that contains only characters not found in - the byte string pointed to by src + the byte string pointed to by src. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string s = "abcde312$#@"; + const char* invalid = "*$#"; + + const std::size_t valid_len = std::strcspn(s.c_str(), invalid); + if (valid_len != s.size()) + { + std::cout << std::quoted(s) + << " contains invalid chars starting at position " + << valid_len << '\\n' + << std::string(valid_len + 1, '-') << "^\\n"; + } + } + +.SH Output: + + "abcde312$#@" contains invalid chars starting at position 8 + ---------^ .SH See also - returns the length of the maximum initial segment that consists - strspn of only the characters found in another byte string - \fI(function)\fP - strpbrk finds the first location of any character in one string, in another string - \fI(function)\fP + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + returns the length of the maximum initial segment that consists + wcscspn of only the wide not found in another wide string + \fI(function)\fP + strpbrk finds the first location of any character from a set of separators + \fI(function)\fP + find first occurrence of characters + find_first_of \fI(public member function of std::basic_string)\fP + C documentation for strcspn - -.SH Category: - - * Todo no example diff --git a/man/std::streambuf.3 b/man/std::streambuf.3 deleted file mode 120000 index bfae638a6..000000000 --- a/man/std::streambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf.3 \ No newline at end of file diff --git a/man/std::streambuf.3 b/man/std::streambuf.3 new file mode 100644 index 000000000..9c01629e8 --- /dev/null +++ b/man/std::streambuf.3 @@ -0,0 +1,194 @@ +.TH std::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf \- std::basic_streambuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_streambuf; + + The class basic_streambuf controls input and output to a character sequence. It + includes and provides access to + + 1. The controlled character sequence, also called the buffer, which may contain + input sequence (also called get area) for buffering the input operations and/or + output sequence (also called put area) for buffering the output operations. + 2. The associated character sequence, also called source (for input) or sink (for + output). This may be an entity that is accessed through OS API (file, TCP + socket, serial port, other character device), or it may be an object + (std::vector, array, string literal), that can be interpreted as a character + source or sink. + + The I/O stream objects std::basic_istream and std::basic_ostream, as well as all + objects derived from them (std::ofstream, std::stringstream, etc), are implemented + entirely in terms of std::basic_streambuf. + + The controlled character sequence is an array of CharT which, at all times, + represents a subsequence, or a "window" into the associated character sequence. Its + state is described by three pointers: + + 1. The beginning pointer, always points at the lowest element of the buffer. + 2. The next pointer, points at the element that is the next candidate for reading + or writing. + 3. The end pointer, points one past the end of the buffer. + + A basic_streambuf object may support input (in which case the buffer described by + the beginning, next, and end pointers is called get area), output (put area), or + input and output simultaneously. In latter case, six pointers are tracked, which may + all point to elements of the same character array or two individual arrays. + + If the next pointer is less than the end pointer in the put area, a write position + is available. The next pointer can be dereferenced and assigned to. + + If the next pointer is less than the end pointer in the get area, a read position is + available. The next pointer can be dereferenced and read from. + + If the next pointer is greater than the beginning pointer in a get area, a putback + position is available, and the next pointer may be decremented, dereferenced, and + assigned to, in order to put a character back into the get area. + + The character representation and encoding in the controlled sequence may be + different from the character representations in the associated sequence, in which + case a std::codecvt locale facet is typically used to perform the conversion. Common + examples are UTF-8 (or other multibyte) files accessed through std::wfstream + objects: the controlled sequence consists of wchar_t characters, but the associated + sequence consists of bytes. + + Typical implementation of the std::basic_streambuf base class holds only the six + CharT* pointers and a copy of std::locale as data members. In addition, + implementations may keep cached copies of locale facets, which are invalidated + whenever imbue() is called. The concrete buffers such as std::basic_filebuf or + std::basic_stringbuf are derived from std::basic_streambuf. + + std-streambuf.svg + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::streambuf std::basic_streambuf + std::wstreambuf std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI(virtual public member function)\fP +.SH Locales + pubimbue invokes imbue() + \fI(public member function)\fP + getloc obtains a copy of the associated locale + \fI(public member function)\fP +.SH Positioning + pubsetbuf invokes setbuf() + \fI(public member function)\fP + pubseekoff invokes seekoff() + \fI(public member function)\fP + pubseekpos invokes seekpos() + \fI(public member function)\fP + pubsync invokes sync() + \fI(public member function)\fP +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function)\fP + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function)\fP + sgetn invokes xsgetn() + \fI(public member function)\fP +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function)\fP + sputn invokes xsputn() + \fI(public member function)\fP +.SH Putback + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP +.SH Protected member functions + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function)\fP +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output + \fB[virtual]\fP sequence, or both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output + \fB[virtual]\fP sequence, or both using absolute addressing + \fI(virtual protected member function)\fP + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP +.SH Get area + showmanyc obtains the number of characters available for input in the + \fB[virtual]\fP associated input sequence, if known + \fI(virtual protected member function)\fP + underflow reads characters from the associated input sequence to the get + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + uflow reads characters from the associated input sequence to the get + \fB[virtual]\fP area and advances the next pointer + \fI(virtual protected member function)\fP + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + eback returns a pointer to the beginning, current character and the end + gptr of the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + pbase returns a pointer to the beginning, current character and the end + pptr of the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + pbackfail puts a character back into the input sequence, possibly modifying + \fB[virtual]\fP the input sequence + \fI(virtual protected member function)\fP + +.SH See also + + object type, capable of holding all information needed to control a C I/O + FILE stream + \fI(typedef)\fP diff --git a/man/std::streambuf::basic_streambuf.3 b/man/std::streambuf::basic_streambuf.3 deleted file mode 120000 index 463e017b7..000000000 --- a/man/std::streambuf::basic_streambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::basic_streambuf.3 \ No newline at end of file diff --git a/man/std::streambuf::basic_streambuf.3 b/man/std::streambuf::basic_streambuf.3 new file mode 100644 index 000000000..caf4b3077 --- /dev/null +++ b/man/std::streambuf::basic_streambuf.3 @@ -0,0 +1,49 @@ +.TH std::basic_streambuf::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::basic_streambuf \- std::basic_streambuf::basic_streambuf + +.SH Synopsis + protected: \fB(1)\fP + basic_streambuf(); + protected: \fB(2)\fP \fI(since C++11)\fP + basic_streambuf(const basic_streambuf& rhs); + + 1) Constructs the basic_streambuf object, initializes the six pointer members + (eback(), gptr(), egptr(), pbase(), pptr(), and epptr()) to null pointer values, and + the locale member to std::locale(), a copy of the global C++ locale at the time of + construction. + 2) Constructs a copy of rhs, initializing the six pointers and the locale object + with the copies of the values held by rhs. Note that this is a shallow copy: the + pointers of the newly-constructed basic_streambuf are pointing into the same + character array as the pointers of rhs. + + Both constructors are protected, and are only called by the concrete streambuf + classes, such as std::basic_filebuf, std::basic_stringbuf, or std::strstreambuf. + +.SH Parameters + + rhs - a streambuf object to copy + +.SH Notes + + Until C++11, it was unspecified whether basic_streambuf or any of its derived + classes is CopyConstructible (LWG issue 421), and different C++ library + implementations provided different options. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function of std::basic_filebuf)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) + constructor constructs a strstreambuf object + \fI(public member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::eback,gptr,egptr.3 b/man/std::streambuf::eback,gptr,egptr.3 deleted file mode 120000 index 9272ab2e5..000000000 --- a/man/std::streambuf::eback,gptr,egptr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::eback,gptr,egptr.3 \ No newline at end of file diff --git a/man/std::streambuf::eback,gptr,egptr.3 b/man/std::streambuf::eback,gptr,egptr.3 new file mode 100644 index 000000000..f20ec2496 --- /dev/null +++ b/man/std::streambuf::eback,gptr,egptr.3 @@ -0,0 +1,48 @@ +.TH std::basic_streambuf::eback,gptr,egptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::eback,gptr,egptr \- std::basic_streambuf::eback,gptr,egptr + +.SH Synopsis + char_type* eback() const; \fB(1)\fP + char_type* gptr() const; \fB(2)\fP + char_type* egptr() const; \fB(3)\fP + + Returns pointers defining the get area. + + 1) Returns the pointer to the beginning of the get area. + + 2) Returns the pointer to the current character (get pointer) in the get area. + + 3) Returns the pointer one past the end of the get area. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The pointer to the beginning of the get area. + + 2) The pointer to the current character (get pointer) in the get area. + + 3) The pointer one past the end of the get area. + +.SH Notes + + While the names "gptr" and "egptr" refer to the get area, the name "eback" refers to + the end of the putback area: stepping backwards from gptr, characters can be put + back until eback. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pbase returns a pointer to the beginning, current character and the end of the put + pptr area + epptr \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::gbump.3 b/man/std::streambuf::gbump.3 deleted file mode 120000 index 6139613fb..000000000 --- a/man/std::streambuf::gbump.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::gbump.3 \ No newline at end of file diff --git a/man/std::streambuf::gbump.3 b/man/std::streambuf::gbump.3 new file mode 100644 index 000000000..232521c5f --- /dev/null +++ b/man/std::streambuf::gbump.3 @@ -0,0 +1,47 @@ +.TH std::basic_streambuf::gbump 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::gbump \- std::basic_streambuf::gbump + +.SH Synopsis + protected: + void gbump( int count ); + + Skips count characters in the get area. This is done by adding count to the get + pointer. No checks are done for underflow. + +.SH Parameters + + count - number of characters to skip + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Because this function takes an int, it cannot manipulate buffers larger than + std::numeric_limits::max() characters (LWG issue 255). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether gbump can be implemented + LWG 59 C++98 as only add count + calling sbumpc count times (which may check to the get pointer + underflow) + +.SH See also + + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::getloc.3 b/man/std::streambuf::getloc.3 deleted file mode 120000 index a48ea6737..000000000 --- a/man/std::streambuf::getloc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::getloc.3 \ No newline at end of file diff --git a/man/std::streambuf::getloc.3 b/man/std::streambuf::getloc.3 new file mode 100644 index 000000000..c8569e47a --- /dev/null +++ b/man/std::streambuf::getloc.3 @@ -0,0 +1,33 @@ +.TH std::basic_streambuf::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::getloc \- std::basic_streambuf::getloc + +.SH Synopsis + std::locale getloc() const; + + Returns the associated locale. + + The associated locale is the value supplied to pubimbue() on the last call, or, if + that function has not been called, the value of the global locale (std::locale) at + the time of the construction of the streambuf. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated locale. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pubimbue invokes imbue() + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::in_avail.3 b/man/std::streambuf::in_avail.3 deleted file mode 120000 index 5303abddb..000000000 --- a/man/std::streambuf::in_avail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::in_avail.3 \ No newline at end of file diff --git a/man/std::streambuf::in_avail.3 b/man/std::streambuf::in_avail.3 new file mode 100644 index 000000000..48555272e --- /dev/null +++ b/man/std::streambuf::in_avail.3 @@ -0,0 +1,44 @@ +.TH std::basic_streambuf::in_avail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::in_avail \- std::basic_streambuf::in_avail + +.SH Synopsis + std::streamsize in_avail(); + + Returns the number of characters available in the get area. If a read position is + available, effectively returns egptr() - gptr(), the size of the get area. In this + case, the number of bytes returned is the number of bytes that can be extracted from + the buffer without calling underflow(). + + If the get area is empty, calls showmanyc() to determine the number of bytes + available in the associated character sequence. In this case, the value returned is + the number of bytes that can be extracted from the buffer while it's guaranteed that + underflow() would not return Traits::eof. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters available for non-blocking read (either the size of the get + area or the number of characters ready for reading from the associated character + sequence), or -1 if no characters are available in the associated sequence as far as + showmanyc() can tell. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + optionally provides the number of characters available for input from the + showmanyc file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::operator=.3 b/man/std::streambuf::operator=.3 deleted file mode 120000 index 617c89cf6..000000000 --- a/man/std::streambuf::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::operator=.3 \ No newline at end of file diff --git a/man/std::streambuf::operator=.3 b/man/std::streambuf::operator=.3 new file mode 100644 index 000000000..948add624 --- /dev/null +++ b/man/std::streambuf::operator=.3 @@ -0,0 +1,28 @@ +.TH std::basic_streambuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::operator= \- std::basic_streambuf::operator= + +.SH Synopsis + basic_streambuf& operator=( const basic_streambuf& other ); \fI(since C++11)\fP + + Assigns the data members of other to *this. + +.SH Parameters + + other - stream buffer to assign + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::overflow.3 b/man/std::streambuf::overflow.3 deleted file mode 120000 index 6516fb5c8..000000000 --- a/man/std::streambuf::overflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::overflow.3 \ No newline at end of file diff --git a/man/std::streambuf::overflow.3 b/man/std::streambuf::overflow.3 new file mode 100644 index 000000000..bf2dc6d77 --- /dev/null +++ b/man/std::streambuf::overflow.3 @@ -0,0 +1,130 @@ +.TH std::basic_streambuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::overflow \- std::basic_streambuf::overflow + +.SH Synopsis + protected: + virtual int_type overflow( int_type ch = Traits::eof() ); + + Ensures that there is space at the put area for at least one character by saving + some initial subsequence of characters starting at pbase() to the output sequence + and updating the pointers to the put area (if needed). If ch is not Traits::eof() + (i.e. Traits::eq_int_type(ch, Traits::eof()) != true), it is either put to the put + area or directly saved to the output sequence. + + The function may update pptr, epptr and pbase pointers to define the location to + write more data. On failure, the function ensures that either pptr() == nullptr or + pptr() == epptr. + + The base class version of the function does nothing. The derived classes may + override this function to allow updates to the put area in the case of exhaustion. + +.SH Parameters + + ch - the character to store in the put area + +.SH Return value + + Returns unspecified value not equal to Traits::eof() on success, Traits::eof() on + failure. + + The base class version of the function returns Traits::eof(). + +.SH Note + + The sputc() and sputn() call this function in case of an overflow (pptr() == nullptr + or pptr() >= epptr()). + +.SH Example + + +// Run this code + + #include + #include + #include + + // Buffer for std::ostream implemented by std::array + template + struct ArrayedStreamBuffer : std::basic_streambuf + { + using Base = std::basic_streambuf; + using char_type = typename Base::char_type; + using int_type = typename Base::int_type; + + ArrayedStreamBuffer() + { + // put area pointers to work with 'buffer' + Base::setp(buffer.data(), buffer.data() + size); + } + + int_type overflow(int_type ch) + { + std::cout << "overflow\\n"; + return Base::overflow(ch); + } + + void print_buffer() + { + for (char_type i : buffer) + { + if (i == 0) + std::cout << "\\\\0"; + else + std::cout << i; + std::cout << ' '; + } + std::cout << '\\n'; + } + + private: + std::array buffer{}; // value-initialize buffer + }; + + int main() + { + ArrayedStreamBuffer<10> streambuf; + std::ostream stream(&streambuf); + + stream << "hello"; + streambuf.print_buffer(); + if (stream.good()) + std::cout << "stream is good\\n"; + + stream << "world"; + streambuf.print_buffer(); + if (stream.good()) + std::cout << "stream is good\\n"; + + stream << "!"; + streambuf.print_buffer(); + if (!stream.good()) + std::cout << "stream is not good\\n"; + } + +.SH Output: + + h e l l o \\0 \\0 \\0 \\0 \\0 + stream is good + h e l l o w o r l d + stream is good + overflow + h e l l o w o r l d + stream is not good + +.SH See also + + uflow reads characters from the associated input sequence to the get area and + \fB[virtual]\fP advances the next pointer + \fI(virtual protected member function)\fP + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + overflow appends a character to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + overflow appends a character to the output sequence, may reallocate or initially + \fB[virtual]\fP allocate the buffer if dynamic and not frozen + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::streambuf::pbackfail.3 b/man/std::streambuf::pbackfail.3 deleted file mode 120000 index 61b5c6712..000000000 --- a/man/std::streambuf::pbackfail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pbackfail.3 \ No newline at end of file diff --git a/man/std::streambuf::pbackfail.3 b/man/std::streambuf::pbackfail.3 new file mode 100644 index 000000000..e44f8b8d1 --- /dev/null +++ b/man/std::streambuf::pbackfail.3 @@ -0,0 +1,78 @@ +.TH std::basic_streambuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbackfail \- std::basic_streambuf::pbackfail + +.SH Synopsis + protected: + virtual int_type pbackfail( int_type c = Traits::eof() ); + + This function can only be called if any of the following condition is satisfied: + + * gptr() is null, + * gptr() == eback(), or + * traits::eq(traits::to_char_type(c), gptr()[-1]) returns false. + + This function is called by the public functions sungetc() and sputbackc() (which, in + turn, are called by basic_istream::unget and basic_istream::putback) when either: + + 1) There is no putback position in the get area (pbackfail() is called with no + arguments). In this situation, the purpose of pbackfail() is to back up the get area + by one character, if the associated character sequence allows this (e.g. a + file-backed streambuf may reload the buffer from a file, starting one character + earlier). + 2) The caller attempts to putback a different character from the one retrieved + earlier (pbackfail() is called with the character that needs to be put back). In + this situation, the purpose of pbackfail() is to place the character c into the get + area at the position just before basic_streambuf::gptr(), and, if possible, to + modify the associated character sequence to reflect this change. This may involve + backing up the get area as in the first variant. + + The default base class version of this function does nothing and returns + Traits::eof() in all situations. This function is overridden by the derived classes: + basic_stringbuf::pbackfail, basic_filebuf::pbackfail, strstreambuf::pbackfail, and + is expected to be overridden by user-defined and third-party library stream classes. + +.SH Parameters + + ch - character to put back or Traits::eof() if only back out is requested + +.SH Return value + + Traits::eof() in case of failure, some other value to indicate success. The base + class version always fails. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct + behavior + the calling condition corrected to + LWG 32 C++98 'traits::eq(*gptr(),traits::to_char_type(c)) match + returns false' did not match the description of the + sputbackc() description + +.SH See also + + backs out the input sequence to unget a character, not affecting the + pbackfail associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + pbackfail puts a character back into the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + pbackfail backs out the input sequence to unget a character + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::pbase,std::basic_streambuf::pptr,.3 b/man/std::streambuf::pbase,std::basic_streambuf::pptr,.3 new file mode 100644 index 000000000..16799c237 --- /dev/null +++ b/man/std::streambuf::pbase,std::basic_streambuf::pptr,.3 @@ -0,0 +1,46 @@ +.TH std::basic_streambuf::pbase,std::basic_streambuf::pptr, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbase,std::basic_streambuf::pptr, \- std::basic_streambuf::pbase,std::basic_streambuf::pptr, + +.SH Synopsis + + protected: \fB(1)\fP + char_type* pbase() const; + protected: \fB(2)\fP + char_type* pptr() const; + protected: \fB(3)\fP + char_type* epptr() const; + + Returns pointers defining the put area. + + 1) Returns the pointer to the beginning ("base") of the put area. + + 2) Returns the pointer to the current character (put pointer) in the put area. + + 3) Returns the pointer one past the end of the put area. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The pointer to the beginning of the put area. + + 2) The pointer to the current character (put pointer) in the put area. + + 3) The pointer one past the end of the put area. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + eback returns a pointer to the beginning, current character and the end of the get + gptr area + egptr \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 b/man/std::streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 deleted file mode 120000 index 5ba1fb9b8..000000000 --- a/man/std::streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 \ No newline at end of file diff --git a/man/std::streambuf::pbump.3 b/man/std::streambuf::pbump.3 deleted file mode 120000 index a149359c2..000000000 --- a/man/std::streambuf::pbump.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pbump.3 \ No newline at end of file diff --git a/man/std::streambuf::pbump.3 b/man/std::streambuf::pbump.3 new file mode 100644 index 000000000..cc71e077b --- /dev/null +++ b/man/std::streambuf::pbump.3 @@ -0,0 +1,67 @@ +.TH std::basic_streambuf::pbump 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbump \- std::basic_streambuf::pbump + +.SH Synopsis + protected: + void pbump( int count ); + + Repositions the put pointer (pptr()) by count characters, where count may be + positive or negative. No checks are done for moving the pointer outside the put area + [pbase(), epptr()). + + If the pointer is advanced and then overflow() is called to flush the put area to + the associated character sequence, the effect is that extra count characters with + undefined values are output. + +.SH Parameters + + count - number to add to the put pointer + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Because this function takes an int, it cannot manipulate buffers larger than + std::numeric_limits::max() characters (LWG issue 255). + +.SH Example + + +// Run this code + + #include + #include + #include + + struct showput_streambuf : std::filebuf + { + using std::filebuf::pbump; // expose protected + std::string showput() const + { + return std::string(pbase(), pptr()); + } + }; + + int main() + { + showput_streambuf mybuf; + mybuf.open("test.txt", std::ios_base::out); + std::ostream str(&mybuf); + str << "This is a test" << std::flush << "1234"; + std::cout << "The put area contains: " << mybuf.showput() << '\\n'; + mybuf.pbump(10); + std::cout << "after pbump(10), it contains " << mybuf.showput() << '\\n'; + } + +.SH Output: + + The put area contains: 1234 + after pbump\fB(10)\fP, it contains 1234 is a test + +.SH See also + + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP diff --git a/man/std::streambuf::pubimbue,std::basic_streambuf::imbue.3 b/man/std::streambuf::pubimbue,std::basic_streambuf::imbue.3 deleted file mode 120000 index 47873c26f..000000000 --- a/man/std::streambuf::pubimbue,std::basic_streambuf::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubimbue,std::basic_streambuf::imbue.3 \ No newline at end of file diff --git a/man/std::streambuf::pubimbue,std::basic_streambuf::imbue.3 b/man/std::streambuf::pubimbue,std::basic_streambuf::imbue.3 new file mode 100644 index 000000000..c84c38d7a --- /dev/null +++ b/man/std::streambuf::pubimbue,std::basic_streambuf::imbue.3 @@ -0,0 +1,37 @@ +.TH std::basic_streambuf::pubimbue,std::basic_streambuf::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubimbue,std::basic_streambuf::imbue \- std::basic_streambuf::pubimbue,std::basic_streambuf::imbue + +.SH Synopsis + std::locale pubimbue( const std::locale& loc ); \fB(1)\fP + protected: \fB(2)\fP + virtual void imbue( const std::locale& loc ); + + Changes the associated locale. + + 1) Sets loc as the associated locale. Calls imbue(loc) of the most derived class + + 2) The base class version of this function has no effect. The derived classes may + override this function in order to be informed about the changes of the locale. The + derived class may cache the locale and member facets between calls to imbue(). + +.SH Parameters + + loc - locale object to associate + +.SH Return value + + 1) Previous associated locale. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + getloc obtains a copy of the associated locale + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::pubseekoff,.3 b/man/std::streambuf::pubseekoff,.3 new file mode 100644 index 000000000..6fddf66cc --- /dev/null +++ b/man/std::streambuf::pubseekoff,.3 @@ -0,0 +1,84 @@ +.TH std::basic_streambuf::pubseekoff, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubseekoff, \- std::basic_streambuf::pubseekoff, + +.SH Synopsis + + pos_type pubseekoff( off_type off, std::ios_base::seekdir dir, + std::ios_base::openmode which = ios_base::in | \fB(1)\fP + ios_base::out ); + protected: + + virtual pos_type seekoff( off_type off, std::ios_base::seekdir dir, \fB(2)\fP + + std::ios_base::openmode which = ios_base::in | + ios_base::out ); + + Sets the position indicator of the input and/or output sequence relative to some + other position. + + 1) Calls seekoff(off, dir, which) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow relative positioning of the position indicator. + +.SH Parameters + + off - relative position to set the position indicator to. + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Note + + Not all combinations of parameters may be valid, see the derived versions of seekoff + for details. + +.SH Return value + + 1) The return value of seekoff(off, dir, which) + 2) The resulting absolute position as defined by the position indicator. The base + class version returns pos_type(off_type(-1)). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the base class version of seekoff + LWG 55 C++98 returned returns pos_type(off_type(-1)) + an undefined invalid stream + position + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::pubseekoff,std::basic_streambuf::seekoff.3 b/man/std::streambuf::pubseekoff,std::basic_streambuf::seekoff.3 deleted file mode 120000 index bfc3586fb..000000000 --- a/man/std::streambuf::pubseekoff,std::basic_streambuf::seekoff.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubseekoff,std::basic_streambuf::seekoff.3 \ No newline at end of file diff --git a/man/std::streambuf::pubseekpos,.3 b/man/std::streambuf::pubseekpos,.3 new file mode 100644 index 000000000..ed46050b4 --- /dev/null +++ b/man/std::streambuf::pubseekpos,.3 @@ -0,0 +1,72 @@ +.TH std::basic_streambuf::pubseekpos, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubseekpos, \- std::basic_streambuf::pubseekpos, + +.SH Synopsis + + pos_type pubseekpos( pos_type pos, + std::ios_base::openmode which = std::ios_base::in | \fB(1)\fP + std::ios_base::out ); + protected: + + virtual pos_type seekpos( pos_type pos, \fB(2)\fP + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Sets the position indicator of the input and/or output sequence to an absolute + position. + + 1) Calls seekpos(pos, which) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow absolute positioning of the position indicator. + +.SH Parameters + + pos - absolute position to set the position indicator to + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + 1) The return value of seekpos(pos, which). + 2) The resulting absolute position as defined by the position indicator. The base + class version returns pos_type(off_type(-1)). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the base class version of seekpos + LWG 55 C++98 returned returns pos_type(off_type(-1)) + an undefined invalid stream + position + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::pubseekpos,std::basic_streambuf::seekpos.3 b/man/std::streambuf::pubseekpos,std::basic_streambuf::seekpos.3 deleted file mode 120000 index e1c6dedfd..000000000 --- a/man/std::streambuf::pubseekpos,std::basic_streambuf::seekpos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubseekpos,std::basic_streambuf::seekpos.3 \ No newline at end of file diff --git a/man/std::streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 b/man/std::streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 deleted file mode 120000 index a3e744500..000000000 --- a/man/std::streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 \ No newline at end of file diff --git a/man/std::streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 b/man/std::streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 new file mode 100644 index 000000000..96e049f19 --- /dev/null +++ b/man/std::streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 @@ -0,0 +1,81 @@ +.TH std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf \- std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf + +.SH Synopsis + public: \fB(1)\fP + basic_streambuf* pubsetbuf( char_type* s, std::streamsize n ) + protected: + virtual basic_streambuf* setbuf( char_type* s, std::streamsize n \fB(2)\fP + ) + + 1) Calls setbuf(s, n) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow removal or replacement of the controlled character + sequence (the buffer) with a user-provided array, or for any other + implementation-specific purpose. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer + n - the number of CharT elements in the user-provided buffer + +.SH Return value + + 1) The return value of setbuf(s, n). + 2) this + +.SH Example + + Provides a 10k buffer for reading. On linux, the strace utility may be used to + observe the actual number of bytes read. + + +// Run this code + + #include + #include + #include + + int main() + { + int cnt = 0; + std::ifstream file; + char buf[1024 * 10 + 1]; + + file.rdbuf()->pubsetbuf(buf, sizeof buf); + + file.open("/usr/share/dict/words"); + + for (std::string line; getline(file, line);) + ++cnt; + + std::cout << cnt << '\\n'; + } + +.SH Possible output: + + 356010 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default behavior of setbuf was only specified as no-op + LWG 158 C++98 specified for all cases + if gptr() is not null and not equal to egptr() + +.SH See also + + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + setbuf provides user-supplied buffer or turns this filebuf unbuffered + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + setbuf sets the buffer for a file stream + \fI(function)\fP diff --git a/man/std::streambuf::pubsync,std::basic_streambuf::sync.3 b/man/std::streambuf::pubsync,std::basic_streambuf::sync.3 deleted file mode 120000 index 31fe3b450..000000000 --- a/man/std::streambuf::pubsync,std::basic_streambuf::sync.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubsync,std::basic_streambuf::sync.3 \ No newline at end of file diff --git a/man/std::streambuf::pubsync,std::basic_streambuf::sync.3 b/man/std::streambuf::pubsync,std::basic_streambuf::sync.3 new file mode 100644 index 000000000..d35616600 --- /dev/null +++ b/man/std::streambuf::pubsync,std::basic_streambuf::sync.3 @@ -0,0 +1,49 @@ +.TH std::basic_streambuf::pubsync,std::basic_streambuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubsync,std::basic_streambuf::sync \- std::basic_streambuf::pubsync,std::basic_streambuf::sync + +.SH Synopsis + int pubsync(); \fB(1)\fP + protected: \fB(2)\fP + virtual int sync(); + + Synchronizes the controlled character sequence (the buffers) with the associated + character sequence. + + 1) Calls sync() of the most derived class + + 2) The base class version of this function has no effect. The derived classes may + override this function to allow synchronizing the underlying device with the + buffers. + + For output streams, this typically results in writing the contents of the put area + into the associated sequence, i.e. flushing of the output buffer. For input streams, + this typically empties the get area and forces a re-read from the associated + sequence to pick up recent changes. The default behavior (found, for example, in + std::basic_stringbuf), is to do nothing. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The return value of sync(). + + 2) Returns 0 on success, -1 otherwise. The base class version returns 0. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + sync writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::sbumpc,std::basic_streambuf::stossc.3 b/man/std::streambuf::sbumpc,std::basic_streambuf::stossc.3 new file mode 100644 index 000000000..b93e84b61 --- /dev/null +++ b/man/std::streambuf::sbumpc,std::basic_streambuf::stossc.3 @@ -0,0 +1,38 @@ +.TH std::basic_streambuf::sbumpc,std::basic_streambuf::stossc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sbumpc,std::basic_streambuf::stossc \- std::basic_streambuf::sbumpc,std::basic_streambuf::stossc + +.SH Synopsis + int_type sbumpc(); \fB(1)\fP + void stossc(); \fB(2)\fP (deprecated in C++98) + (removed in C++17) + + Reads one character and advances the input sequence by one character. + + 1) If the input sequence read position is not available, returns uflow(). Otherwise + returns Traits::to_int_type(*gptr()). + 2) Same as \fB(1)\fP, but discards the result. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The value of the character pointed to by the get pointer, or Traits::eof() if the + read position is not available. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function)\fP + snextc advances the input sequence, then reads one character without advancing again + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::sbumpc.3 b/man/std::streambuf::sbumpc.3 deleted file mode 120000 index 94f27458a..000000000 --- a/man/std::streambuf::sbumpc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sbumpc.3 \ No newline at end of file diff --git a/man/std::streambuf::setg.3 b/man/std::streambuf::setg.3 deleted file mode 120000 index 8f615ec72..000000000 --- a/man/std::streambuf::setg.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::setg.3 \ No newline at end of file diff --git a/man/std::streambuf::setg.3 b/man/std::streambuf::setg.3 new file mode 100644 index 000000000..3d6119311 --- /dev/null +++ b/man/std::streambuf::setg.3 @@ -0,0 +1,79 @@ +.TH std::basic_streambuf::setg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::setg \- std::basic_streambuf::setg + +.SH Synopsis + protected: + void setg( char_type* gbeg, char_type* gcurr, char_type* gend ); + + Sets the values of the pointers defining the get area. Specifically, after the call + eback() == gbeg, gptr() == gcurr, egptr() == gend. + +.SH Parameters + + gbeg - pointer to the new beginning of the get area + gcurr - pointer to the new current character (get pointer) in the get area + gend - pointer to the new end of the get area + +.SH Return value + + \fI(none)\fP + +.SH Example + + + +// Run this code + + #include + #include + + class null_filter_buf : public std::streambuf + { + std::streambuf* src; + char ch; // single-byte buffer + protected: + int underflow() + { + traits_type::int_type i; + while ((i = src->sbumpc()) == '\\0') + ; // skip zeroes + if (!traits_type::eq_int_type(i, traits_type::eof())) + { + ch = traits_type::to_char_type(i); + setg(&ch, &ch, &ch+1); // make one read position available + } + return i; + } + public: + null_filter_buf(std::streambuf* buf) : src(buf) + { + setg(&ch, &ch + 1, &ch + 1); // buffer is initially full + } + }; + + void filtered_read(std::istream& in) + { + std::streambuf* orig = in.rdbuf(); + null_filter_buf buf(orig); + in.rdbuf(&buf); + for (char c; in.get(c);) + std::cout << c; + in.rdbuf(orig); + } + + int main() + { + char a[] = "This i\\0s \\0an e\\0\\0\\0xample"; + std::istringstream in(std::string(std::begin(a), std::end(a))); + filtered_read(in); + } + +.SH Output: + + This is an example + +.SH See also + + setp repositions the beginning, next, and end pointers of the output sequence + \fI(protected member function)\fP diff --git a/man/std::streambuf::setp.3 b/man/std::streambuf::setp.3 deleted file mode 120000 index 125480274..000000000 --- a/man/std::streambuf::setp.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::setp.3 \ No newline at end of file diff --git a/man/std::streambuf::setp.3 b/man/std::streambuf::setp.3 new file mode 100644 index 000000000..e0abc3f69 --- /dev/null +++ b/man/std::streambuf::setp.3 @@ -0,0 +1,78 @@ +.TH std::basic_streambuf::setp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::setp \- std::basic_streambuf::setp + +.SH Synopsis + protected: + void setp( char_type* pbeg, char_type* pend ); + + Sets the values of the pointers defining the put area. Specifically, after the call + pbase() == pbeg, pptr() == pbeg, epptr() == pend. + +.SH Parameters + + pbeg - pointer to the new beginning of the put area + pend - pointer to the new end of the put area + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + // Buffer for std::ostream implemented by std::array + template + struct ArrayedStreamBuffer : std::basic_streambuf + { + using Base = std::basic_streambuf; + using char_type = typename Base::char_type; + + ArrayedStreamBuffer() + { + // put area pointers to work with 'buffer' + Base::setp(buffer.data(), buffer.data() + size); + } + + void print_buffer() + { + for (char_type i : buffer) + { + if (i == 0) + std::cout << "\\\\0"; + else + std::cout << i; + std::cout << ' '; + } + std::cout << '\\n'; + } + + private: + std::array buffer{}; // value-initialize buffer + }; + + int main() + { + ArrayedStreamBuffer<10> streambuf; + std::ostream stream(&streambuf); + + stream << "hello"; + stream << ","; + + streambuf.print_buffer(); + } + +.SH Output: + + h e l l o , \\0 \\0 \\0 \\0 + +.SH See also + + setg repositions the beginning, next, and end pointers of the input sequence + \fI(protected member function)\fP diff --git a/man/std::streambuf::sgetc.3 b/man/std::streambuf::sgetc.3 deleted file mode 120000 index c3fce3cc0..000000000 --- a/man/std::streambuf::sgetc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sgetc.3 \ No newline at end of file diff --git a/man/std::streambuf::sgetc.3 b/man/std::streambuf::sgetc.3 new file mode 100644 index 000000000..d51db4251 --- /dev/null +++ b/man/std::streambuf::sgetc.3 @@ -0,0 +1,50 @@ +.TH std::basic_streambuf::sgetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sgetc \- std::basic_streambuf::sgetc + +.SH Synopsis + int_type sgetc(); + + Reads one character from the input sequence. + + If the input sequence read position is not available, returns underflow(). Otherwise + returns Traits::to_int_type(*gptr()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character pointed to by the get pointer. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream stream("Hello, world"); + std::cout << "sgetc() returned '" << (char)stream.rdbuf()->sgetc() << "'\\n"; + std::cout << "peek() returned '" << (char)stream.peek() << "'\\n"; + std::cout << "get() returned '" << (char)stream.get() << "'\\n"; + } + +.SH Output: + + sgetc() returned 'H' + peek() returned 'H' + get() returned 'H' + +.SH See also + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function)\fP diff --git a/man/std::streambuf::sgetn,std::basic_streambuf::xsgetn.3 b/man/std::streambuf::sgetn,std::basic_streambuf::xsgetn.3 deleted file mode 120000 index af58d04b6..000000000 --- a/man/std::streambuf::sgetn,std::basic_streambuf::xsgetn.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn.3 \ No newline at end of file diff --git a/man/std::streambuf::sgetn,std::basic_streambuf::xsgetn.3 b/man/std::streambuf::sgetn,std::basic_streambuf::xsgetn.3 new file mode 100644 index 000000000..4efc4c3c8 --- /dev/null +++ b/man/std::streambuf::sgetn,std::basic_streambuf::xsgetn.3 @@ -0,0 +1,45 @@ +.TH std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn \- std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn + +.SH Synopsis + std::streamsize sgetn( char_type* s, std::streamsize count ); \fB(1)\fP + protected: \fB(2)\fP + virtual std::streamsize xsgetn( char_type* s, std::streamsize count ); + + 1) Calls xsgetn(s, count) of the most derived class. + 2) Reads count characters from the input sequence and stores them into a character + array pointed to by s. The characters are read as if by repeated calls to sbumpc(). + That is, if less than count characters are immediately available, the function calls + uflow() to provide more until Traits::eof() is returned. + Classes derived from std::basic_streambuf are permitted to provide more efficient + implementations of this function. + +.SH Parameters + + s - pointer to the beginning of a char_type array + count - maximum number of characters to read. + +.SH Return value + + The number of characters successfully read. If it is less than count the input + sequence has reached the end. + +.SH Notes + + The rule about "more efficient implementations" permits bulk I/O without + intermediate buffering: that's how std::ifstream::read simply passes the pointer to + the POSIX read() system call in some implementations of iostreams + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sputn invokes xsputn() + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::showmanyc.3 b/man/std::streambuf::showmanyc.3 deleted file mode 120000 index 0f1588d58..000000000 --- a/man/std::streambuf::showmanyc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::showmanyc.3 \ No newline at end of file diff --git a/man/std::streambuf::showmanyc.3 b/man/std::streambuf::showmanyc.3 new file mode 100644 index 000000000..86c6f8ff7 --- /dev/null +++ b/man/std::streambuf::showmanyc.3 @@ -0,0 +1,58 @@ +.TH std::basic_streambuf::showmanyc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::showmanyc \- std::basic_streambuf::showmanyc + +.SH Synopsis + protected: + virtual std::streamsize showmanyc(); + + Estimates the number of characters available for input in the associated character + sequence. underflow() is guaranteed not to return Traits::eof() or throw an + exception until at least that many characters are extracted. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters that are certainly available in the associated character + sequence, or -1 if showmanyc can determine, without blocking, that no characters are + available. If showmanyc returns -1, underflow() and uflow() will definitely return + Traits::eof or throw. + + The base class version returns 0, which has the meaning of "unsure if there are + characters available in the associated sequence". + +.SH Notes + + The name of this function stands for "stream: how many characters?", so it is + pronounced "S how many C", rather than "show many C". + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + underflow() is guaranteed not to extended the guarantee to allow + LWG 159 C++98 fail until at least + at least showmanyc() characters showmanyc() characters to be + are supplied extracted + +.SH See also + + in_avail obtains the number of characters immediately available in the get area + \fI(public member function)\fP + optionally provides the number of characters available for input from the + showmanyc file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::snextc.3 b/man/std::streambuf::snextc.3 deleted file mode 120000 index 4670d9216..000000000 --- a/man/std::streambuf::snextc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::snextc.3 \ No newline at end of file diff --git a/man/std::streambuf::snextc.3 b/man/std::streambuf::snextc.3 new file mode 100644 index 000000000..222009afc --- /dev/null +++ b/man/std::streambuf::snextc.3 @@ -0,0 +1,39 @@ +.TH std::basic_streambuf::snextc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::snextc \- std::basic_streambuf::snextc + +.SH Synopsis + int_type snextc(); + + Advances the input sequence by one character and reads one character. + + The function calls sbumpc() to advance the input sequence. If that function returns + Traits::eof() meaning that input sequence has been exhausted and uflow() could not + retrieve more data, Traits::eof() is returned. Otherwise sgetc() is called in order + to read the character. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the next character. If the input sequence has been exhausted, + Traits::eof() is returned. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::sputbackc.3 b/man/std::streambuf::sputbackc.3 deleted file mode 120000 index 8a11fd0b6..000000000 --- a/man/std::streambuf::sputbackc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sputbackc.3 \ No newline at end of file diff --git a/man/std::streambuf::sputbackc.3 b/man/std::streambuf::sputbackc.3 new file mode 100644 index 000000000..f2e362010 --- /dev/null +++ b/man/std::streambuf::sputbackc.3 @@ -0,0 +1,73 @@ +.TH std::basic_streambuf::sputbackc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputbackc \- std::basic_streambuf::sputbackc + +.SH Synopsis + int_type sputbackc( char_type c ); + + Puts back a character back to the get area. + + If a putback position is available in the get area (gptr() > eback()), and the + character c is equal to the character one position to the left of gptr() (as + determined by Traits::eq(c, gptr()[-1]), then simply decrements the next pointer + (gptr()). + + Otherwise, calls pbackfail(Traits::to_int_type(c)) to either back up the get area or + to modify both the get area and possibly the associated character sequence. + + The I/O stream function basic_istream::putback is implemented in terms of this + function. + +.SH Parameters + + c - character to put back + +.SH Return value + + If putback position was available, returns the character that the next pointer is + now pointing at, converted to int_type with Traits::to_int_type(*gptr()). The next + single-character input from this streambuf will return this character. + + If putback position was not available, returns what pbackfail() returns, which is + Traits::eof() on failure. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream s("abcdef"); // gptr() points to 'a' in "abcdef" + std::cout << "Before putback, string holds " << s.str() << '\\n'; + char c1 = s.get(); // c1 = 'a', gptr() now points to 'b' in "abcdef" + char c2 = s.rdbuf()->sputbackc('z'); // same as s.putback('z') + // gptr() now points to 'z' in "zbcdef" + std::cout << "After putback, string holds " << s.str() << '\\n'; + char c3 = s.get(); // c3 = 'z', gptr() now points to 'b' in "zbcdef" + char c4 = s.get(); // c4 = 'b', gptr() now points to 'c' in "zbcdef" + std::cout << c1 << c2 << c3 << c4 << '\\n'; + + s.rdbuf()->sputbackc('b'); // gptr() now points to 'b' in "zbcdef" + s.rdbuf()->sputbackc('z'); // gptr() now points to 'z' in "zbcdef" + int eof = s.rdbuf()->sputbackc('x'); // nothing to unget: pbackfail() fails + if (eof == EOF) + std::cout << "No room to putback after 'z'\\n"; + } + +.SH Output: + + Before putback, string holds abcdef + After putback, string holds zbcdef + azzb + No room to putback after 'z' + +.SH See also + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::streambuf::sputc.3 b/man/std::streambuf::sputc.3 deleted file mode 120000 index dd8115ff7..000000000 --- a/man/std::streambuf::sputc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sputc.3 \ No newline at end of file diff --git a/man/std::streambuf::sputc.3 b/man/std::streambuf::sputc.3 new file mode 100644 index 000000000..dbfddb2b6 --- /dev/null +++ b/man/std::streambuf::sputc.3 @@ -0,0 +1,46 @@ +.TH std::basic_streambuf::sputc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputc \- std::basic_streambuf::sputc + +.SH Synopsis + int_type sputc( char_type ch ); + + Writes one character to the output sequence. + + If the output sequence write position is not available (the buffer is full), then + calls overflow(ch). + +.SH Parameters + + ch - character to write + +.SH Return value + + The written character, converted to int_type with Traits::to_int_type(ch) on + success. + + Traits::eof() (as returned by overflow()) on failure. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream s; + s.rdbuf()->sputc('a'); + std::cout << s.str() << '\\n'; + } + +.SH Output: + + a + +.SH See also + + sputn invokes xsputn() + \fI(public member function)\fP diff --git a/man/std::streambuf::sputn,std::basic_streambuf::xsputn.3 b/man/std::streambuf::sputn,std::basic_streambuf::xsputn.3 deleted file mode 120000 index 642a06778..000000000 --- a/man/std::streambuf::sputn,std::basic_streambuf::xsputn.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sputn,std::basic_streambuf::xsputn.3 \ No newline at end of file diff --git a/man/std::streambuf::sputn,std::basic_streambuf::xsputn.3 b/man/std::streambuf::sputn,std::basic_streambuf::xsputn.3 new file mode 100644 index 000000000..fe40c149b --- /dev/null +++ b/man/std::streambuf::sputn,std::basic_streambuf::xsputn.3 @@ -0,0 +1,72 @@ +.TH std::basic_streambuf::sputn,std::basic_streambuf::xsputn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputn,std::basic_streambuf::xsputn \- std::basic_streambuf::sputn,std::basic_streambuf::xsputn + +.SH Synopsis + std::streamsize sputn( const char_type* s, std::streamsize count ); \fB(1)\fP + protected: \fB(2)\fP + virtual std::streamsize xsputn( const char_type* s, std::streamsize count ); + + 1) Calls xsputn(s, count) of the most derived class. + 2) Writes count characters to the output sequence from the character array whose + first element is pointed to by s. The characters are written as if by repeated calls + to sputc(). Writing stops when either count characters are written or a call to + sputc() would have returned Traits::eof(). + + If the put area becomes full (pptr() == epptr()), it is unspecified whether + overflow() is actually called or its effect is achieved by other means. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters successfully written. + +.SH Notes + + "achieved by other means" permits bulk I/O without intermediate buffering: that is + how std::ofstream::write() simply passes the pointer to the suitable system call in + some implementations. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream s1; + std::streamsize sz = s1.rdbuf()->sputn("This is a test", 14); + s1 << '\\n'; + std::cout << "The call to sputn() returned " << sz << '\\n' + << "The output sequence contains " << s1.str(); + + std::istringstream s2; + sz = s2.rdbuf()->sputn("This is a test", 14); + std::cout << "The call to sputn() on an input stream returned " << sz << '\\n'; + } + +.SH Output: + + The call to sputn() returned 14 + The output sequence contains This is a test + The call to sputn() on an input stream returned 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 565 C++98 xsputn() always called overflow() if it does not actually need to + pptr() == epptr() be called + +.SH See also + + sgetn invokes xsgetn() + \fI(public member function)\fP diff --git a/man/std::streambuf::streambuf.3 b/man/std::streambuf::streambuf.3 deleted file mode 120000 index 463e017b7..000000000 --- a/man/std::streambuf::streambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::basic_streambuf.3 \ No newline at end of file diff --git a/man/std::streambuf::streambuf.3 b/man/std::streambuf::streambuf.3 new file mode 100644 index 000000000..caf4b3077 --- /dev/null +++ b/man/std::streambuf::streambuf.3 @@ -0,0 +1,49 @@ +.TH std::basic_streambuf::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::basic_streambuf \- std::basic_streambuf::basic_streambuf + +.SH Synopsis + protected: \fB(1)\fP + basic_streambuf(); + protected: \fB(2)\fP \fI(since C++11)\fP + basic_streambuf(const basic_streambuf& rhs); + + 1) Constructs the basic_streambuf object, initializes the six pointer members + (eback(), gptr(), egptr(), pbase(), pptr(), and epptr()) to null pointer values, and + the locale member to std::locale(), a copy of the global C++ locale at the time of + construction. + 2) Constructs a copy of rhs, initializing the six pointers and the locale object + with the copies of the values held by rhs. Note that this is a shallow copy: the + pointers of the newly-constructed basic_streambuf are pointing into the same + character array as the pointers of rhs. + + Both constructors are protected, and are only called by the concrete streambuf + classes, such as std::basic_filebuf, std::basic_stringbuf, or std::strstreambuf. + +.SH Parameters + + rhs - a streambuf object to copy + +.SH Notes + + Until C++11, it was unspecified whether basic_streambuf or any of its derived + classes is CopyConstructible (LWG issue 421), and different C++ library + implementations provided different options. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function of std::basic_filebuf)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) + constructor constructs a strstreambuf object + \fI(public member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::sungetc.3 b/man/std::streambuf::sungetc.3 deleted file mode 120000 index 135031de4..000000000 --- a/man/std::streambuf::sungetc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sungetc.3 \ No newline at end of file diff --git a/man/std::streambuf::sungetc.3 b/man/std::streambuf::sungetc.3 new file mode 100644 index 000000000..c2e60e2b9 --- /dev/null +++ b/man/std::streambuf::sungetc.3 @@ -0,0 +1,64 @@ +.TH std::basic_streambuf::sungetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sungetc \- std::basic_streambuf::sungetc + +.SH Synopsis + int_type sungetc(); + + If a putback position is available in the get area (gptr() > eback()), then + decrements the next pointer (gptr()) and returns the character it now points to. + + If a putback position is not available, then calls pbackfail() to back up the input + sequence if possible. + + The I/O stream function basic_istream::unget is implemented in terms of this + function. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If putback position was available, returns the character that the next pointer is + now pointing at, converted to int_type with Traits::to_int_type(*gptr()). The next + single-character input from this streambuf will return this character. + + If putback position was not available, returns what pbackfail() returns, which is + Traits::eof() on failure. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream s("abcdef"); // gptr() points to 'a' + char c1 = s.get(); // c = 'a', gptr() now points to 'b' + char c2 = s.rdbuf()->sungetc(); // same as s.unget(): gptr() points to 'a' again + char c3 = s.get(); // c3 = 'a', gptr() now points to 'b' + char c4 = s.get(); // c4 = 'b', gptr() now points to 'c' + std::cout << c1 << c2 << c3 << c4 << '\\n'; + + s.rdbuf()->sungetc(); // back to 'b' + s.rdbuf()->sungetc(); // back to 'a' + int eof = s.rdbuf()->sungetc(); // nothing to unget: pbackfail() fails + if (eof == EOF) + std::cout << "Nothing to unget after 'a'\\n"; + } + +.SH Output: + + aaab + Nothing to unget after 'a' + +.SH See also + + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::streambuf::swap.3 b/man/std::streambuf::swap.3 deleted file mode 120000 index aaf781c01..000000000 --- a/man/std::streambuf::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::swap.3 \ No newline at end of file diff --git a/man/std::streambuf::swap.3 b/man/std::streambuf::swap.3 new file mode 100644 index 000000000..ff8261ca1 --- /dev/null +++ b/man/std::streambuf::swap.3 @@ -0,0 +1,28 @@ +.TH std::basic_streambuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::swap \- std::basic_streambuf::swap + +.SH Synopsis + void swap( basic_streambuf& other ); \fI(since C++11)\fP + + Exchanges the contents of the stream buffer with those of other. + +.SH Parameters + + other - stream buffer to exchange contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::uflow.3 b/man/std::streambuf::uflow.3 deleted file mode 120000 index 429f3d765..000000000 --- a/man/std::streambuf::uflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::uflow.3 \ No newline at end of file diff --git a/man/std::streambuf::uflow.3 b/man/std::streambuf::uflow.3 new file mode 100644 index 000000000..07f656738 --- /dev/null +++ b/man/std::streambuf::uflow.3 @@ -0,0 +1,52 @@ +.TH std::basic_streambuf::uflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::uflow \- std::basic_streambuf::uflow + +.SH Synopsis + protected: + virtual int_type uflow(); + + Ensures that at least one character is available in the input area by updating the + pointers to the input area (if needed). On success returns the value of that + character and advances the value of the get pointer by one character. On failure + returns traits::eof(). + + The function may update gptr, egptr and eback pointers to define the location of + newly loaded data (if any). On failure, the function ensures that either gptr() == + nullptr or gptr() == egptr. + + The base class version of the function calls underflow() and increments gptr(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character that was pointed to by the get pointer before it was + advanced by one, or traits::eof() otherwise. + + The base class version of the function returns the value returned by underflow(). + +.SH Note + + The public functions of std::streambuf call this function only if gptr() == nullptr + or gptr() >= egptr(). + + The custom streambuf classes that do not use the get area and do not set the get + area pointers in basic_streambuf are required to override this function. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::streambuf::underflow.3 b/man/std::streambuf::underflow.3 deleted file mode 120000 index 00b12c654..000000000 --- a/man/std::streambuf::underflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::underflow.3 \ No newline at end of file diff --git a/man/std::streambuf::underflow.3 b/man/std::streambuf::underflow.3 new file mode 100644 index 000000000..29e00974b --- /dev/null +++ b/man/std::streambuf::underflow.3 @@ -0,0 +1,106 @@ +.TH std::basic_streambuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::underflow \- std::basic_streambuf::underflow + +.SH Synopsis + protected: + virtual int_type underflow(); + + Ensures that at least one character is available in the input area by updating the + pointers to the input area (if needed) and reading more data in from the input + sequence (if applicable). Returns the value of that character (converted to int_type + with Traits::to_int_type(c)) on success or Traits::eof() on failure. + + The function may update gptr, egptr and eback pointers to define the location of + newly loaded data (if any). On failure, the function ensures that either gptr() == + nullptr or gptr() == egptr. + + The base class version of the function does nothing. The derived classes may + override this function to allow updates to the get area in the case of exhaustion. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character pointed to by the get pointer after the call on success, + or Traits::eof() otherwise. + + The base class version of the function returns traits::eof(). + +.SH Note + + The public functions of std::streambuf call this function only if gptr() == nullptr + or gptr() >= egptr(). + +.SH Example + + + +// Run this code + + #include + #include + + class null_filter_buf : public std::streambuf + { + std::streambuf* src; + char ch; // single-byte buffer + protected: + int underflow() + { + traits_type::int_type i; + while ((i = src->sbumpc()) == '\\0') + ; // skip zeroes + if (!traits_type::eq_int_type(i, traits_type::eof())) + { + ch = traits_type::to_char_type(i); + setg(&ch, &ch, &ch+1); // make one read position available + } + return i; + } + public: + null_filter_buf(std::streambuf* buf) : src(buf) + { + setg(&ch, &ch + 1, &ch + 1); // buffer is initially full + } + }; + + void filtered_read(std::istream& in) + { + std::streambuf* orig = in.rdbuf(); + null_filter_buf buf(orig); + in.rdbuf(&buf); + for (char c; in.get(c);) + std::cout << c; + in.rdbuf(orig); + } + + int main() + { + char a[] = "This i\\0s \\0an e\\0\\0\\0xample"; + std::istringstream in(std::string(std::begin(a), std::end(a))); + filtered_read(in); + } + +.SH Output: + + This is an example + +.SH See also + + uflow reads characters from the associated input sequence to the get area and + \fB[virtual]\fP advances the next pointer + \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + underflow reads a character from the input sequence without advancing the next + \fB[virtual]\fP pointer + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::streambuf::~basic_streambuf.3 b/man/std::streambuf::~basic_streambuf.3 deleted file mode 120000 index 4941deda0..000000000 --- a/man/std::streambuf::~basic_streambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::~basic_streambuf.3 \ No newline at end of file diff --git a/man/std::streambuf::~basic_streambuf.3 b/man/std::streambuf::~basic_streambuf.3 new file mode 100644 index 000000000..1e6a28839 --- /dev/null +++ b/man/std::streambuf::~basic_streambuf.3 @@ -0,0 +1,55 @@ +.TH std::basic_streambuf::~basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::~basic_streambuf \- std::basic_streambuf::~basic_streambuf + +.SH Synopsis + virtual ~basic_streambuf(); + + This destructor has no effect: the members of this basic_streambuf (the pointers and + the locale) are destructed in accordance with the usual object destruction sequence + after this destructor returns. However, since it is declared public virtual, it + allows the objects that are derived from std::basic_streambuf to be deleted through + a pointer to base class. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::filebuf* fbp = new std::filebuf; + fbp->open("test.txt", std::ios_base::out); + fbp->sputn("Hello\\n", 6); + + std::streambuf* sbp = fbp; + delete sbp; // the file is closed, output flushed and written + + std::ifstream f("test.txt"); + std::cout << f.rdbuf(); // proof + } + +.SH Output: + + Hello + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 54 C++98 the effect of the destructor was not specified as no effect + specified + +.SH See also + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP diff --git a/man/std::streamoff.3 b/man/std::streamoff.3 index fa678695e..44e0ace8e 100644 --- a/man/std::streamoff.3 +++ b/man/std::streamoff.3 @@ -1,26 +1,29 @@ -.TH std::streamoff 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::streamoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::streamoff \- std::streamoff + .SH Synopsis Defined in header - typedef /*unspecified*/ streamoff; + typedef /*implementation-defined*/ streamoff; - The type std::streamoff is a signed integral type of sufficient size to represent - the maximum possible file size supported by the operating system. Typically, this is - a typedef to long long. + The type std::streamoff is an implementation-defined + signed integral + \fI(since C++11)\fP type of sufficient size to represent the maximum possible file size + supported by the operating system. + Typically, this is an alias for long long. + \fI(since C++11)\fP It is used to represent offsets from stream positions (values of type std::fpos). A - std::streamoff value of -1 is also used to represent error conditions by some of the - I/O library functions. + std::streamoff value constructed from -1 is also used to represent error conditions + by some of the I/O library functions. Relationship with std::fpos * the difference between two std::fpos objects is a value of type std::streamoff - * a value of type std::streamoff may be added or subtracted from std::fpos yielding a different std::fpos. - * a value of type std::fpos is implicitly convertible to std::streamoff (the conversion result is the offset from the beginning of the file). - * a value of type std::fpos is constructible from a value of type std::streamoff .SH See also @@ -28,6 +31,6 @@ fpos represents absolute position in a stream or a file \fI(class template)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::streamsize.3 b/man/std::streamsize.3 index 061120f15..15057a68e 100644 --- a/man/std::streamsize.3 +++ b/man/std::streamsize.3 @@ -1,11 +1,15 @@ -.TH std::streamsize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::streamsize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::streamsize \- std::streamsize + .SH Synopsis Defined in header - typedef /*unspecified*/ streamsize; + typedef /*implementation-defined*/ streamsize; - The type std::streamsize is a signed integral type used to represent the number of - characters transferred in an I/O operation or the size of an I/O buffer. It is used - as a signed counterpart of std::size_t, similar to the POSIX type ssize_t. + The type std::streamsize is an implementation-defined signed integral type used to + represent the number of characters transferred in an I/O operation or the size of an + I/O buffer. It is used as a signed counterpart of std::size_t, similar to the POSIX + type ssize_t. Except in the constructors of std::strstreambuf, negative values of std::streamsize are never used. @@ -13,10 +17,10 @@ .SH See also gcount returns number of characters extracted by last unformatted input operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::strerror.3 b/man/std::strerror.3 index aa02f36d3..3ec18f708 100644 --- a/man/std::strerror.3 +++ b/man/std::strerror.3 @@ -1,48 +1,77 @@ -.TH std::strerror 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strerror 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strerror \- std::strerror + .SH Synopsis Defined in header char* strerror( int errnum ); - Returns text version of the error code errnum. errnum is usually acquired from the - errno variable, however the function accepts any value of type int. The message is - locale-specific. + Returns a pointer to the textual description of the system error code errnum, + identical to the description that would be printed by std::perror(). + + errnum is usually acquired from the errno variable, however the function accepts any + value of type int. The contents of the string are locale-specific. - The returned byte string must not be modified by the program, but may be overwritten - by a subsequent call to the strerror function. + The returned string must not be modified by the program, but may be overwritten by a + subsequent call to the strerror function. strerror is not required to be + thread-safe. Implementations may be returning different pointers to static read-only + string literals or may be returning the same pointer over and over, pointing at a + static buffer in which strerror places the string. .SH Parameters - errnum - integral value referring to a error code + errnum - integer value referring to an error code .SH Return value - Pointer to a null-terminated byte string corresponding to the error code errnum. + Pointer to a null-terminated byte string corresponding to the errno error code + errnum. + +.SH Notes + + POSIX allows subsequent calls to strerror to invalidate the pointer value returned + by an earlier call. It also specifies that it is the LC_MESSAGES locale facet that + controls the contents of these messages. + + POSIX has a thread-safe version called strerror_r defined. Glibc defines an + incompatible version. .SH Example - + // Run this code - #include - #include #include + #include + #include #include - + #include + int main() { - double not_a_number = std::log(-1.0); - if (errno == EDOM) { + const double not_a_number = std::log(-1.0); + std::cout << not_a_number << '\\n'; + + if (errno == EDOM) + { std::cout << "log(-1) failed: " << std::strerror(errno) << '\\n'; + std::setlocale(LC_MESSAGES, "de_DE.utf8"); + std::cout << "Or, in German, " << std::strerror(errno) << '\\n'; } } -.SH Output: +.SH Possible output: + nan log(-1) failed: Numerical argument out of domain + Or, in German, Das numerische Argument ist ausserhalb des Definitionsbereiches .SH See also + displays a character string corresponding of the current + perror error to stderr + \fI(function)\fP E2BIG, EACCES, ..., EXDEV macros for standard POSIX-compatible error conditions - (macro constant) + (macro constant) C documentation for strerror diff --git a/man/std::strftime.3 b/man/std::strftime.3 index 577b5e393..7793c51be 100644 --- a/man/std::strftime.3 +++ b/man/std::strftime.3 @@ -1,10 +1,13 @@ -.TH std::strftime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strftime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strftime \- std::strftime + .SH Synopsis Defined in header - std::size_t strftime( char* str, std::size_t count, const char* format, std::tm* - time ); + std::size_t strftime( char* str, std::size_t count, const char* format, const + std::tm* tp ); - Converts the date and time information from a given calendar time time to a + Converts the date and time information from a given calendar time tp to a null-terminated multibyte character string str according to format string format. Up to count bytes are written. @@ -12,226 +15,233 @@ str - pointer to the first element of the char array for output count - maximum number of bytes to write - pointer to a null-terminated multibyte character string specifying the - format of conversion. - - The format string consists of zero or more conversion specifiers and - ordinary characters (except %). All ordinary characters, including the - terminating null character, are copied to the output string without - modification. Each conversion specification begins with % character, - optionally followed by E or O modifier (ignored if unsupported by the - locale), followed by the character that determines the behavior of the - specifier. The following format specifiers are available: - - Conversion Explanation Used fields - specifier - % writes literal %. The full conversion - specification must be %%. - n writes newline character - \fI(C++11)\fP - t writes horizontal tab character - \fI(C++11)\fP - Year - Y writes year as a 4 digit decimal number tm_year - EY writes year in the alternative representation, - \fI(C++11)\fP e.g.平成23年 (year Heisei 23) instead of 2011 tm_year - 年 (year 2011) in ja_JP locale - y writes last 2 digits of year as a decimal tm_year - number (range [00,99]) - Oy writes last 2 digits of year using the - \fI(C++11)\fP alternative numeric system, e.g. 十一 instead tm_year - of 11 in ja_JP locale - Ey writes year as offset from locale's - \fI(C++11)\fP alternative calendar period %EC tm_year - (locale-dependent) - C writes first 2 digits of year as a decimal tm_year - \fI(C++11)\fP number (range [00,99]) - EC writes name of the base year (period) in the - \fI(C++11)\fP locale's alternative representation, e.g. 平成 tm_year - (Heisei era) in ja_JP - writes ISO 8601 week-based year, i.e. the year - that contains the specified week. - - G In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - writes last 2 digits of ISO 8601 week-based - year, i.e. the year that contains the - specified week (range [00,99]). - - g In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - Month - b writes abbreviated month name, e.g. Oct tm_mon - (locale dependent) - h synonym of b tm_mon - \fI(C++11)\fP - B writes full month name, e.g. October (locale tm_mon - dependent) - m writes month as a decimal number (range tm_mon - [01,12]) - Om writes month using the alternative numeric - \fI(C++11)\fP system, e.g. 十二 instead of 12 in ja_JP tm_mon - locale - Week - writes week of the year as a decimal number tm_year, tm_wday, - U (Sunday is the first day of the week) (range tm_yday - [00,53]) - OU writes week of the year, as by %U, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - writes week of the year as a decimal number tm_year, tm_wday, - W (Monday is the first day of the week) (range tm_yday - [00,53]) - OW writes week of the year, as by %W, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - writes ISO 8601 week of the year (range - [01,53]). - - V In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - format - OV writes week of the year, as by %V, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - Day of the year/month - j writes day of the year as a decimal number tm_yday - (range [001,366]) - d writes day of the month as a decimal number tm_mday - (range [01,31]) - writes zero-based day of the month using the - Od alternative numeric system, e.g 二十七 instead - \fI(C++11)\fP of 23 in ja_JP locale tm_mday - - Single character is preceded by a space. - writes day of the month as a decimal number - e (range [1,31]). tm_mday - \fI(C++11)\fP - Single digit is preceded by a space. - writes one-based day of the month using the - Oe alternative numeric system, e.g. 二十七 - \fI(C++11)\fP instead of 27 in ja_JP locale tm_mday - - Single character is preceded by a space. - Day of the week - a writes abbreviated weekday name, e.g. Fri tm_wday - (locale dependent) - A writes full weekday name, e.g. Friday (locale tm_wday - dependent) - w writes weekday as a decimal number, where tm_wday - Sunday is 0 (range [0-6]) - Ow writes weekday, where Sunday is 0, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead of tm_wday - 2 in ja_JP locale - u writes weekday as a decimal number, where tm_wday - \fI(C++11)\fP Monday is 1 (ISO 8601 format) (range [1-7]) - Ou writes weekday, where Monday is 1, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead of tm_wday - 2 in ja_JP locale - Hour, minute, second - H writes hour as a decimal number, 24 hour clock tm_hour - (range [00-23]) - OH writes hour from 24-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 十八 instead tm_hour - of 18 in ja_JP locale - I writes hour as a decimal number, 12 hour clock tm_hour - (range [01,12]) - OI writes hour from 12-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 六 instead of tm_hour - 06 in ja_JP locale - M writes minute as a decimal number (range tm_min - [00,59]) - OM writes minute using the alternative numeric - \fI(C++11)\fP system, e.g. 二十五 instead of 25 in ja_JP tm_min - locale - S writes second as a decimal number (range tm_sec - [00,60]) - OS writes second using the alternative numeric - \fI(C++11)\fP system, e.g. 二十四 instead of 24 in ja_JP tm_sec - locale + format - pointer to a null-terminated multibyte character string specifying the + format of conversion + tp - pointer to the object containing date and time information to be converted + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters (except %). All ordinary characters, including the terminating null + character, are copied to the output string without modification. Each conversion + specification begins with % character, optionally followed by E or O modifier + (ignored if unsupported by the locale), followed by the character that determines + the behavior of the specifier. The following format specifiers are available: + + Conversion Explanation Used fields + specifier + % writes literal %. The full conversion specification + must be %%. + n writes newline character + \fI(C++11)\fP + t writes horizontal tab character + \fI(C++11)\fP + Year + Y writes year as a decimal number, e.g. 2017 tm_year + EY writes year in the alternative representation, e.g.平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) tm_year + in ja_JP locale + y writes last 2 digits of year as a decimal number (range tm_year + [00,99]) + Oy writes last 2 digits of year using the alternative tm_year + \fI(C++11)\fP numeric system, e.g. 十一 instead of 11 in ja_JP locale + Ey writes year as offset from locale's alternative tm_year + \fI(C++11)\fP calendar period %EC (locale-dependent) + C writes first 2 digits of year as a decimal number tm_year + \fI(C++11)\fP (range [00,99]) + EC writes name of the base year (period) in the locale's + \fI(C++11)\fP alternative representation, e.g. 平成 (Heisei era) in tm_year + ja_JP + writes ISO 8601 week-based year, i.e. the year that + contains the specified week. + + G In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + writes last 2 digits of ISO 8601 week-based year, i.e. + the year that contains the specified week (range + [00,99]). + g tm_year, tm_wday, + \fI(C++11)\fP In ISO 8601 weeks begin with Monday and the first week tm_yday + of the year must satisfy the following requirements: + + * Includes January 4 + * Includes first Thursday of the year + Month + b writes abbreviated month name, e.g. Oct (locale tm_mon + dependent) + h synonym of b tm_mon + \fI(C++11)\fP + B writes full month name, e.g. October (locale dependent) tm_mon + m writes month as a decimal number (range [01,12]) tm_mon + Om writes month using the alternative numeric system, e.g. tm_mon + \fI(C++11)\fP 十二 instead of 12 in ja_JP locale + Week + U writes week of the year as a decimal number (Sunday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OU writes week of the year, as by %U, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + W writes week of the year as a decimal number (Monday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OW writes week of the year, as by %W, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + writes ISO 8601 week of the year (range [01,53]). + + V In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + OV writes week of the year, as by %V, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + Day of the year/month + j writes day of the year as a decimal number (range tm_yday + [001,366]) + d writes day of the month as a decimal number (range tm_mday + [01,31]) + writes zero-based day of the month using the + Od alternative numeric system, e.g. 二十七 instead of 27 + \fI(C++11)\fP in ja_JP locale tm_mday + + Single character is preceded by a space. + writes day of the month as a decimal number (range + e [1,31]). tm_mday + \fI(C++11)\fP + Single digit is preceded by a space. + writes one-based day of the month using the alternative + Oe numeric system, e.g. 二十七 instead of 27 in ja_JP + \fI(C++11)\fP locale tm_mday + + Single character is preceded by a space. + Day of the week + a writes abbreviated weekday name, e.g. Fri (locale tm_wday + dependent) + A writes full weekday name, e.g. Friday (locale tm_wday + dependent) + w writes weekday as a decimal number, where Sunday is 0 tm_wday + (range [0-6]) + Ow writes weekday, where Sunday is 0, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + u writes weekday as a decimal number, where Monday is 1 tm_wday + \fI(C++11)\fP (ISO 8601 format) (range [1-7]) + Ou writes weekday, where Monday is 1, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + Hour, minute, second + H writes hour as a decimal number, 24 hour clock (range tm_hour + [00-23]) + OH writes hour from 24-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 十八 instead of 18 in ja_JP locale + I writes hour as a decimal number, 12 hour clock (range tm_hour + [01,12]) + OI writes hour from 12-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 六 instead of 06 in ja_JP locale + M writes minute as a decimal number (range [00,59]) tm_min + OM writes minute using the alternative numeric system, tm_min + \fI(C++11)\fP e.g. 二十五 instead of 25 in ja_JP locale + S writes second as a decimal number (range [00,60]) tm_sec + OS writes second using the alternative numeric system, tm_sec + \fI(C++11)\fP e.g. 二十四 instead of 24 in ja_JP locale .SH Other - c writes standard date and time string, e.g. Sun all - Oct 17 04:41:13 2010 (locale dependent) - Ec writes alternative date and time string, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of all - 2011年 (year 2011) in ja_JP locale - x writes localized date representation (locale all - dependent) - Ex writes alternative date representation, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of all - 2011年 (year 2011) in ja_JP locale - X writes localized time representation (locale all - dependent) - EX writes alternative time representation (locale all - \fI(C++11)\fP dependent) - D equivalent to "%m/%d/%y" tm_mon, tm_mday, - \fI(C++11)\fP tm_year - F equivalent to "%Y-%m-%d" (the ISO 8601 date tm_mon, tm_mday, - \fI(C++11)\fP format) tm_year - r writes localized 12-hour clock time (locale tm_hour, tm_min, - \fI(C++11)\fP dependent) tm_sec - R equivalent to "%H:%M" tm_hour, tm_min - \fI(C++11)\fP - T equivalent to "%H:%M:%S" (the ISO 8601 time tm_hour, tm_min, - \fI(C++11)\fP format) tm_sec - p writes localized a.m. or p.m. (locale tm_hour - dependent) - z writes offset from UTC in the ISO 8601 format - \fI(C++11)\fP (e.g. -0430), or no characters if the time tm_isdst - zone information is not available - writes time zone name or abbreviation, or no - Z characters if the time zone information is not tm_isdst - available (locale dependent) + c writes standard date and time string, e.g. Sun Oct 17 all + 04:41:13 2010 (locale dependent) + Ec writes alternative date and time string, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + x writes localized date representation (locale dependent) all + Ex writes alternative date representation, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + X writes localized time representation, e.g. 18:40:20 or all + 6:40:20 PM (locale dependent) + EX writes alternative time representation (locale all + \fI(C++11)\fP dependent) + D equivalent to "%m/%d/%y" tm_mon, tm_mday, + \fI(C++11)\fP tm_year + F equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday, + \fI(C++11)\fP tm_year + r writes localized 12-hour clock time (locale dependent) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + R equivalent to "%H:%M" tm_hour, tm_min + \fI(C++11)\fP + T equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + p writes localized a.m. or p.m. (locale dependent) tm_hour + z writes offset from UTC in the ISO 8601 format (e.g. + \fI(C++11)\fP -0430), or no characters if the time zone information tm_isdst + is not available + writes locale-dependent time zone name or abbreviation, + Z or no characters if the time zone information is not tm_isdst + available .SH Return value The number of bytes written into the character array pointed to by str not including the terminating '\\0' on success. If count was reached before the entire string could - be stored, 0 is returned and the contents are undefined. + be stored, 0 is returned and the contents are indeterminate. .SH Example - + // Run this code #include #include + #include #include - + + void utcExample() + { + // Example of the very popular RFC 3339 format UTC time + std::time_t time = std::time({}); + char timeString[std::size("yyyy-mm-ddThh:mm:ssZ")]; + std::strftime(std::data(timeString), std::size(timeString), + "%FT%TZ", std::gmtime(&time)); + std::cout << timeString << '\\n'; + } + int main() { - std::locale::global(std::locale("ja_JP.utf8")); - std::time_t t = std::time(NULL); + std::time_t t = std::time(nullptr); char mbstr[100]; - if (std::strftime(mbstr, sizeof(mbstr), "%A %c", std::localtime(&t))) { + + if (std::strftime(mbstr, sizeof(mbstr), "%A %c", std::localtime(&t))) + std::cout << mbstr << '\\n'; + + std::locale::global(std::locale("ja_JP.utf8")); + if (std::strftime(mbstr, sizeof(mbstr), "%A %c", std::localtime(&t))) std::cout << mbstr << '\\n'; - } + + utcExample(); } -.SH Output: +.SH Possible output: - 火曜日 2011年12月27日 17時39分03秒 + Tuesday Tue Sep 7 19:40:35 2021 + 火曜日 2021年09月07日 19時40分35秒 + 2021-09-07T19:40:35Z .SH See also - asctime converts a tm object to a textual representation - \fI(function)\fP - ctime converts a time_t object to a textual representation - \fI(function)\fP - wcsftime converts a tm object to custom wide string textual representation - \fI(function)\fP - put_time formats and outputs a date/time value according to the specified format - \fI(C++11)\fP \fI(function template)\fP + converts a std::tm object to a textual + asctime representation + \fI(function)\fP + converts a std::time_t object to a textual + ctime representation + \fI(function)\fP + converts a std::tm object to custom wide + wcsftime string textual representation + \fI(function)\fP + put_time formats and outputs a date/time value + \fI(C++11)\fP according to the specified format + \fI(function template)\fP + std::formatter formatting support for hh_mm_ss + (C++20) \fI(class template specialization)\fP C documentation for strftime diff --git a/man/std::strict_weak_order.3 b/man/std::strict_weak_order.3 new file mode 100644 index 000000000..78a1ac7bc --- /dev/null +++ b/man/std::strict_weak_order.3 @@ -0,0 +1,32 @@ +.TH std::strict_weak_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strict_weak_order \- std::strict_weak_order + +.SH Synopsis + Defined in header + template< class R, class T, class U > \fI(since C++20)\fP + concept strict_weak_order = std::relation; + + The concept strict_weak_order specifies that the relation R imposes a + strict weak ordering on its arguments. + + Semantic requirements + + A relation r is a strict weak ordering if + + * it is irreflexive: for all x, r(x, x) is false; + * it is transitive: for all a, b and c, if r(a, b) and r(b, c) are both true then + r(a, c) is true; + * let e(a, b) be !r(a, b) && !r(b, a), then e is transitive: e(a, b) && e(b, c) + implies e(a, c). + + Under these conditions, it can be shown that e is an equivalence relation, and r + induces a strict total ordering on the equivalence classes determined by e. + +.SH Notes + + The distinction between relation and strict_weak_order is purely semantic. + +.SH See also + + * LessThanComparable diff --git a/man/std::strided_slice.3 b/man/std::strided_slice.3 new file mode 100644 index 000000000..f0349c02c --- /dev/null +++ b/man/std::strided_slice.3 @@ -0,0 +1,142 @@ +.TH std::strided_slice 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strided_slice \- std::strided_slice + +.SH Synopsis + Defined in header + template< class OffsetType, class ExtentType, class StrideType > (since C++26) + struct strided_slice; + + An instance of every specialization of strided_slice is a slice specifier used in + std::submdspan to select a subset of elements using a set of regularly spaced + indices at a specified dimension in std::mdspan. It provides three values: the + offset index, the extent, and the stride. + + Given that stride is greater than zero, let N be the number of selected indices + which is determined by 1 + (extent - 1) / stride if extent is nonzero, otherwise 0. + The indices are selected from half-open interval [offset, offset + extent). Hence, + the selected indices are offset, ..., offset + (N - 1) * stride. + + This class template has no base classes or declared members other than those shown + below. + +.SH Template parameters + + OffsetType the types of offset, extent, and stride, + ExtentType - respectively. + StrideType +.SH Type requirements + - + All template parameters must be unsigned or signed integer types or must satisfy + integral-constant-like + + The program is ill-formed if the type requirement is not satisfied. + +.SH Member types + + Member type Definition + offset_type OffsetType + extent_type ExtentType + stride_type StrideType + + Data members + + + Member name Definition + offset a starting index of type offset_type + \fI(public member object)\fP + a value of type extent_type added to offset used to define the upper + extent bound of indices + \fI(public member object)\fP + an increment value of type stride_type which is equivalent to the + stride distance between two indices + \fI(public member object)\fP + + All these members are declared with [[no_unique_address]] attribute and have default + member initializers where each data member is value initialized. + +.SH Notes + + Every specialization of strided_slice is an aggregate class which allows aggregate + initialization (including designated initialization) of data members (for instance, + std::strided_slice { .offset = 2, .extent = 10, .stride = 3 }). + + The slice specification of strided_slice takes advantage of the data member extent, + as opposed to other slice specifications that use end to indicate the upper bound + value. This is because it can directly generate a static extent for subview of + std::mdspan if both extent and stride are of types that satisfy + integral-constant-like. This enables efficient extraction of subviews with static + extents by mixing compile time values with a runtime value of offset. + +.SH Example + + +// Run this code + + #include + #include + + template + requires (View::extents_type::rank() == 1) + void print_sliced_view(View v, std::strided_slice s) + { + using index_type = View::index_type; + auto subview = std::submdspan(v, s); + const auto& submap = subview.mapping(); + + std::print("["); + bool uses_comma = false; + for (index_type i = 0; i < subview.extent(0); ++i) + { + if (uses_comma) + std::print(", "); + std::print("{}", subview[i]); + uses_comma = true; + } + uses_comma = false; + std::print("] extracted from indices ["); + for (index_type i = 0; i < subview.extent(0); ++i) + { + if (uses_comma) + std::print(", "); + std::print("{}", submap(i) + s.offset); + uses_comma = true; + } + std::println("]"); + } + + int main() + { + static constexpr char letters [] { + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', + 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', + 'U', 'V', 'W', 'X', 'Y', 'Z' + }; + constexpr std::mdspan md (letters, 26); + print_sliced_view(md, {.offset = 0, .extent = 10, .stride = 1}); + print_sliced_view(md, {.offset = 2, .extent = 10, .stride = 1}); + print_sliced_view(md, {.offset = 0, .extent = 5, .stride = 1}); + print_sliced_view(md, {.offset = 2, .extent = 5, .stride = 1}); + print_sliced_view(md, {.offset = 0, .extent = 10, .stride = 2}); + print_sliced_view(md, {.offset = 2, .extent = 10, .stride = 3}); + print_sliced_view(md, {.offset = 0, .extent = 15, .stride = 5}); + print_sliced_view(md, {.offset = 6, .extent = 15, .stride = 5}); + } + +.SH Output: + + [A, B, C, D, E, F, G, H, I, J] extracted from indices [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + [C, D, E, F, G, H, I, J, K, L] extracted from indices [2, 3, 4, 5, 6, 7, 8, 9, 10, 11] + [A, B, C, D, E] extracted from indices [0, 1, 2, 3, 4] + [C, D, E, F, G] extracted from indices [2, 3, 4, 5, 6] + [A, C, E, G, I] extracted from indices [0, 2, 4, 6, 8] + [C, F, I, L] extracted from indices [2, 5, 8, 11] + [A, F, K] extracted from indices [0, 5, 10] + [G, L, Q] extracted from indices [6, 11, 16] + +.SH See also + + slice BLAS-like slice of a valarray: starting index, length, stride + \fI(class)\fP + submdspan returns a view of a subset of an existing mdspan + (C++26) \fI(function template)\fP diff --git a/man/std::string.3 b/man/std::string.3 deleted file mode 120000 index 51b9e0d1f..000000000 --- a/man/std::string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string.3 \ No newline at end of file diff --git a/man/std::string.3 b/man/std::string.3 new file mode 100644 index 000000000..ba00dc78d --- /dev/null +++ b/man/std::string.3 @@ -0,0 +1,397 @@ +.TH std::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string \- std::basic_string + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, \fB(1)\fP + class Allocator = std::allocator + + > class basic_string; + namespace pmr { + + template< + class CharT, + class Traits = std::char_traits \fB(2)\fP \fI(since C++17)\fP + > using basic_string = + std::basic_string>; + + } + + The class template basic_string stores and manipulates sequences of character-like + objects, which are non-array objects of TrivialType and StandardLayoutType. The + class is dependent neither on the character type nor on the nature of operations on + that type. The definitions of the operations are supplied via the Traits template + parameter - a specialization of std::char_traits or a compatible traits class. + + The elements of a basic_string are stored contiguously, that is, for a basic_string + s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()) + , and *(s.begin() + s.size()) has value CharT() (a null terminator) + \fI(since C++11)\fP; or, equivalently, a pointer to s[0] can be passed to functions that + expect a pointer to the first element of + an array + \fI(until C++11)\fP + a null-terminated array + \fI(since C++11)\fP of CharT. + + std::basic_string satisfies the requirements of AllocatorAwareContainer (except that + customized construct/destroy are not used for construction/destruction of elements), + SequenceContainer + and ContiguousContainer + \fI(since C++17)\fP. + + If any of Traits::char_type and Allocator::char_type is different from CharT, the + program is ill-formed. + + Member functions of std::basic_string are constexpr: it is possible to + create and use std::string objects in the evaluation of a constant + expression. + \fI(since C++20)\fP + However, std::string objects generally cannot be constexpr, because + any dynamically allocated storage must be released in the same + evaluation of constant expression. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string std::basic_string + std::wstring std::basic_string + std::u8string (C++20) std::basic_string + std::u16string \fI(C++11)\fP std::basic_string + std::u32string \fI(C++11)\fP std::basic_string + std::pmr::string \fI(C++17)\fP std::pmr::basic_string + std::pmr::wstring \fI(C++17)\fP std::pmr::basic_string + std::pmr::u8string (C++20) std::pmr::basic_string + std::pmr::u16string \fI(C++17)\fP std::pmr::basic_string + std::pmr::u32string \fI(C++17)\fP std::pmr::basic_string + +.SH Template parameters + + CharT - character type + Traits - traits class specifying the operations on the character type + Allocator - Allocator type used to allocate internal storage + +.SH Member types + + Member type Definition + traits_type Traits + value_type CharT + allocator_type Allocator + Allocator::size_type \fI(until C++11)\fP + size_type std::allocator_traits::size_type \fI(since C++11)\fP + + + Allocator::difference_type (until + C++11) + difference_type std::allocator_traits::difference_type (since + C++11) + + + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP + const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator, + iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator, + const_iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + +.SH Member functions + + constructor constructs a basic_string + \fI(public member function)\fP + destroys the string, deallocating internal storage if + destructor used + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP +.SH Element access + at accesses the specified character with bounds checking + \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP + returns a non-modifiable standard C character array + c_str version of the string + \fI(public member function)\fP + operator basic_string_view returns a non-modifiable string_view into the entire + \fI(C++17)\fP string + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP +.SH Capacity + empty checks whether the string is empty + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + returns the number of characters that can be held in + capacity currently allocated storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP +.SH Modifiers + clear clears the contents + \fI(public member function)\fP + insert inserts characters + \fI(public member function)\fP + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP + pop_back removes the last character + (DR*) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + replace replaces specified portion of a string + \fI(public member function)\fP + replace_with_range replaces specified portion of a string with a range of + (C++23) characters + \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP + changes the number of characters stored and possibly + resize_and_overwrite overwrites indeterminate contents via user-provided + (C++23) operation + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Search + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Operations + compare compares two strings + \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string contains the given substring or + (C++23) character + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator+ concatenates two strings or a string and a char + \fI(function template)\fP + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + std::swap(std::basic_string) specializes the std::swap algorithm + \fI(function template)\fP + erase(std::basic_string) erases all elements satisfying specific criteria + erase_if(std::basic_string) \fI(function template)\fP + (C++20) +.SH Input/output + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + getline read data from an I/O stream into a string + \fI(function template)\fP +.SH Numeric conversions + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + stof + stod + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_literals + operator""s converts a character array literal to basic_string + \fI(C++14)\fP \fI(function)\fP + +.SH Helper classes + + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Although it is required that customized construct or destroy is used when + constructing or destroying elements of std::basic_string until C++23, all + implementations only used the default mechanism. The requirement is corrected by + P1072R10 to match existing practice. + + Feature-test macro Value Std Feature + __cpp_lib_string_udls 201304L \fI(C++14)\fP User-defined literals for + string types + __cpp_lib_starts_ends_with 201711L (C++20) starts_with, ends_with + __cpp_lib_constexpr_string 201907L (C++20) Constexpr for + std::basic_string + __cpp_lib_char8_t 201907L (C++20) std::u8string + __cpp_lib_erase_if 202002L (C++20) erase, erase_if + __cpp_lib_string_contains 202011L (C++23) contains + __cpp_lib_string_resize_and_overwrite 202110L (C++23) resize_and_overwrite + Member functions for + __cpp_lib_containers_ranges 202202L (C++23) construction, insertion, and + replacement that accept + container compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + // Creating a string from const char* + std::string str1 = "hello"; + + // Creating a string using string literal + auto str2 = "world"s; + + // Concatenating strings + std::string str3 = str1 + " " + str2; + + // Print out the result + std::cout << str3 << '\\n'; + + std::string::size_type pos = str3.find(" "); + str1 = str3.substr(pos + 1); // the part after the space + str2 = str3.substr(0, pos); // the part till the space + + std::cout << str1 << ' ' << str2 << '\\n'; + + // Accessing an element using subscript operator[] + std::cout << str1[0] << '\\n'; + str1[0] = 'W'; + std::cout << str1 << '\\n'; + } + +.SH Output: + + hello world + world hello + w + World + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + contiguity of the storage for elements of + LWG 530 C++98 basic_string required again + was accidently made not required by LWG259 + the behavior is undefined if any of the program is + LWG 2994 C++98 Traits::char_type^[1] ill-formed in this + (P1148R0) and Allocator::char_type is different from case + CharT + + 1. ↑ The Traits::char_type case is fixed in P1148R0. + +.SH See also + + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP + +.SH External links + + C++ string handling + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::string::append.3 b/man/std::string::append.3 deleted file mode 120000 index b50ac7eda..000000000 --- a/man/std::string::append.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::append.3 \ No newline at end of file diff --git a/man/std::string::append.3 b/man/std::string::append.3 new file mode 100644 index 000000000..dfcb8cb7a --- /dev/null +++ b/man/std::string::append.3 @@ -0,0 +1,185 @@ +.TH std::basic_string::append 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append \- std::basic_string::append + +.SH Synopsis + basic_string& append( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& append( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& append( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& append( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos ); C++20) + basic_string& append( const CharT* s, \fB(4)\fP (constexpr since + size_type count ); C++20) + basic_string& append( const CharT* s ); \fB(5)\fP (constexpr since + C++20) + template< class InputIt > (constexpr since + basic_string& append( InputIt first, InputIt \fB(6)\fP C++20) + last ); \fB(3)\fP + basic_string& append( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(7)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& append( const StringViewLike& t \fB(8)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& append( const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos ); + + Appends additional characters to the string. + + 1) Appends count copies of character ch. + 2) Appends string str. + 3) Appends a substring [pos, pos + count) of str. + * If the requested substring lasts past the end of the string, or if count == + npos, the appended substring is [pos, size()). + * If pos > str.size(), std::out_of_range is thrown. + 4) Appends characters in the range [s, s + count). This range can contain null + characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 5) Appends the null-terminated character string pointed to by s, as if by append(s, + Traits::length(s)). + 6) Appends characters in the range [first, last). + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload only participates in overload resolution if InputIt \fI(since C++11)\fP + qualifies as a LegacyInputIterator. + + 7) Appends characters from the initializer list ilist. + 8) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends all characters from sv as if by append(sv.data(), + sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends the characters from the subview [pos, pos + count) of + sv. + * If the requested subview extends past the end of sv, or if count == npos, the + appended subview is [pos, sv.size()). + * If pos >= sv.size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - number of characters to append + pos - the index of the first character to append + ch - character value to append + first, last - range of characters to append + str - string to append + s - pointer to the character string to append + ilist - initializer list with the characters to append + t - object convertible to std::basic_string_view with the characters to + append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::basic_string str = "string"; + const char* cptr = "C-string"; + const char carr[] = "Two and one"; + + std::string output; + + // 1) Append a char 3 times. + // Notice, this is the only overload accepting chars. + output.append(3, '*'); + std::cout << "1) " << output << '\\n'; + + // 2) Append a whole string + output.append(str); + std::cout << "2) " << output << '\\n'; + + // 3) Append part of a string (last 3 letters, in this case) + output.append(str, 3, 3); + std::cout << "3) " << output << '\\n'; + + // 4) Append part of a C-string + // Notice, because `append` returns *this, we can chain calls together + output.append(1, ' ').append(carr, 4); + std::cout << "4) " << output << '\\n'; + + // 5) Append a whole C-string + output.append(cptr); + std::cout << "5) " << output << '\\n'; + + // 6) Append range + output.append(&carr[3], std::end(carr)); + std::cout << "6) " << output << '\\n'; + + // 7) Append initializer list + output.append({' ', 'l', 'i', 's', 't'}); + std::cout << "7) " << output << '\\n'; + } + +.SH Output: + + 1) *** + 2) ***string + 3) ***stringing + 4) ***stringing Two + 5) ***stringing Two C-string + 6) ***stringing Two C-string and one + 7) ***stringing Two C-string and one list + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(8)\fP causes ambiguity in avoided by making it a + some cases template + +.SH See also + + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + strcat concatenates two strings + \fI(function)\fP + strncat concatenates a certain amount of characters of two strings + \fI(function)\fP + wcscat appends a copy of one wide string to another + \fI(function)\fP + appends a certain amount of wide characters from one wide string to + wcsncat another + \fI(function)\fP diff --git a/man/std::string::append_range.3 b/man/std::string::append_range.3 new file mode 100644 index 000000000..ede115277 --- /dev/null +++ b/man/std::string::append_range.3 @@ -0,0 +1,65 @@ +.TH std::basic_string::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append_range \- std::basic_string::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& append_range( R&& rg ); + + Appends all characters from the range rg. + + Equivalent to + + return append(std::basic_string( std::from_range, std::forward(rg), get_allocator())); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string head{"long long"}; + const auto tail = {' ', 'i', 'n', 't'}; + + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.append(tail.begin(), tail.end()); + #endif + + assert(head == "long long int"); + } + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::string::assign.3 b/man/std::string::assign.3 deleted file mode 120000 index b4f3ab165..000000000 --- a/man/std::string::assign.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::assign.3 \ No newline at end of file diff --git a/man/std::string::assign.3 b/man/std::string::assign.3 new file mode 100644 index 000000000..afbe7a690 --- /dev/null +++ b/man/std::string::assign.3 @@ -0,0 +1,210 @@ +.TH std::basic_string::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign \- std::basic_string::assign + +.SH Synopsis + basic_string& assign( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& assign( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& assign( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& assign( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos); C++20) + basic_string& assign( basic_string&& str ) \fI(since C++11)\fP + noexcept(/* see below */); \fB(4)\fP (constexpr since + C++20) + basic_string& assign( const CharT* s, \fB(5)\fP (constexpr since + size_type count ); C++20) + basic_string& assign( const CharT* s ); \fB(6)\fP (constexpr since + C++20) + template< class InputIt > \fB(3)\fP (constexpr since + basic_string& assign( InputIt first, InputIt \fB(7)\fP C++20) + last ); + basic_string& assign( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(8)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t \fB(9)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t, \fB(10)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos); + + Replaces the contents of the string. + + 1) Replaces the contents with count copies of character ch. + 2) Replaces the contents with a copy of str. Equivalent to *this = str;. + In particular, allocator propagation may take place. + \fI(since C++11)\fP + 3) Replaces the contents with a substring [pos, pos + count) of str. If the + requested substring lasts past the end of the string, or if count == npos, the + resulting substring is [pos, str.size()). If pos > str.size(), std::out_of_range is + thrown. + 4) Replaces the contents with those of str using move semantics. Equivalent to *this + = std::move(str). In particular, allocator propagation may take place. + 5) Replaces the contents with copies of the characters in the range [s, s + count). + This range can contain null characters. + 6) Replaces the contents with those of null-terminated character string pointed to + by s. The length of the string is determined by the first null character using + Traits::length(s). + 7) Replaces the contents with copies of the characters in the range [first, last). + This overload does not participate in overload resolution if InputIt does not + satisfy LegacyInputIterator. + \fI(since C++11)\fP + 8) Replaces the contents with those of the initializer list ilist. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of sv, as if by + assign(sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with the characters from the subview + [pos, pos + count) of sv. If the requested subview lasts past the end of sv, or if + count == npos, the resulting subview is [pos, sv.size()). If pos > sv.size(), + std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - size of the resulting string + pos - index of the first character to take + ch - value to initialize characters of the string with + first, last - range to copy the characters from + str - string to be used as source to initialize the characters with + s - pointer to a character string to use as source to initialize the + string with + ilist - std::initializer_list to initialize the characters of the string with + t - object (convertible to std::basic_string_view) to initialize the + characters of the string with +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in count. + 2) Linear in size of str. + 3) Linear in count. + 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 5) Linear in count. + 6) Linear in size of s. + 7) Linear in distance between first and last. + 8) Linear in size of ilist. + 9) Linear in size of t. + +.SH Exceptions + + 4) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + // assign(size_type count, CharT ch) + s.assign(4, '='); + std::cout << s << '\\n'; // "====" + + std::string const c("Exemplary"); + // assign(const basic_string& str) + s.assign(c); + std::cout << c << " == " << s << '\\n'; // "Exemplary == Exemplary" + + // assign(const basic_string& str, size_type pos, size_type count) + s.assign(c, 0, c.length() - 1); + std::cout << s << '\\n'; // "Exemplar"; + + // assign(basic_string&& str) + s.assign(std::string("C++ by ") + "example"); + std::cout << s << '\\n'; // "C++ by example" + + // assign(const CharT* s, size_type count) + s.assign("C-style string", 7); + std::cout << s << '\\n'; // "C-style" + + // assign(const CharT* s) + s.assign("C-style\\0string"); + std::cout << s << '\\n'; // "C-style" + + char mutable_c_str[] = "C-style string"; + // assign(InputIt first, InputIt last) + s.assign(std::begin(mutable_c_str), std::end(mutable_c_str) - 1); + std::cout << s << '\\n'; // "C-style string" + + // assign(std::initializer_list ilist) + s.assign({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << s << '\\n'; // "C-style" + } + +.SH Output: + + ==== + Exemplary == Exemplary + Exemplar + C++ by example +.SH C-style +.SH C-style + C-style string +.SH C-style + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + non-normative note stated that swap + LWG 2063 C++11 is corrected to require move + a valid implementation of assignment + move-assign + LWG 2579 C++11 assign(const basic_string&) made to propagate allocators + did not propagate allocators if needed + LWG 2946 C++17 overload \fB(9)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::assign_range.3 b/man/std::string::assign_range.3 new file mode 100644 index 000000000..7bfd17959 --- /dev/null +++ b/man/std::string::assign_range.3 @@ -0,0 +1,74 @@ +.TH std::basic_string::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign_range \- std::basic_string::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& assign_range( R&& rg ); + + Replaces the contents of the string with the values in the range rg. + + Equivalent to + + return assign( + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto source = {'s', 'o', 'u', 'r', 'c', 'e'}; + std::string destination{"destination"}; + + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.begin(), source.end()); + #endif + + assert(destination == "source"); + } + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP diff --git a/man/std::string::at.3 b/man/std::string::at.3 deleted file mode 120000 index 1f402dba2..000000000 --- a/man/std::string::at.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::at.3 \ No newline at end of file diff --git a/man/std::string::at.3 b/man/std::string::at.3 new file mode 100644 index 000000000..36e5a7e1d --- /dev/null +++ b/man/std::string::at.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::at \- std::basic_string::at + +.SH Synopsis + CharT& at( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& at( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("message"); // for capacity + + s = "abc"; + s.at(2) = 'x'; // OK + std::cout << s << '\\n'; + + std::cout << "string size = " << s.size() << '\\n'; + std::cout << "string capacity = " << s.capacity() << '\\n'; + + try + { + // This will throw since the requested offset is greater than the current size. + s.at(3) = 'x'; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + } + +.SH Possible output: + + abx + string size = 3 + string capacity = 7 + basic_string::at + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::back.3 b/man/std::string::back.3 deleted file mode 120000 index 33e85e2c2..000000000 --- a/man/std::string::back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::back.3 \ No newline at end of file diff --git a/man/std::string::back.3 b/man/std::string::back.3 new file mode 100644 index 000000000..5dd0d47ca --- /dev/null +++ b/man/std::string::back.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::back \- std::basic_string::back + +.SH Synopsis + CharT& back(); \fB(1)\fP (constexpr since C++20) + const CharT& back() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the last character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& back1 = s.back(); + back1 = 's'; + std::cout << s << '\\n'; // "Exemplars" + + std::string const c("Exemplary"); + char const& back2 = c.back(); + std::cout << back2 << '\\n'; // 'y' + } + +.SH Output: + + Exemplars + y + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function back() + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::basic_string.3 b/man/std::string::basic_string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::string::basic_string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::string::basic_string.3 b/man/std::string::basic_string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::string::basic_string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::string::begin,.3 b/man/std::string::begin,.3 new file mode 100644 index 000000000..a9b49707a --- /dev/null +++ b/man/std::string::begin,.3 @@ -0,0 +1,69 @@ +.TH std::basic_string::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::begin, \- std::basic_string::begin, + +.SH Synopsis + + iterator begin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the first character of the string. + + begin() returns a mutable or constant iterator, depending on the constness of *this. + + cbegin() always returns a constant iterator. It is equivalent to const_cast(*this).begin(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplar"); + *s.begin() = 'e'; + std::cout << s << '\\n'; + + auto i = s.cbegin(); + std::cout << *i << '\\n'; + // *i = 'E'; // error: i is a constant iterator + } + +.SH Output: + + exemplar + e + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::begin,std::basic_string::cbegin.3 b/man/std::string::begin,std::basic_string::cbegin.3 deleted file mode 120000 index aaa6194e9..000000000 --- a/man/std::string::begin,std::basic_string::cbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::begin,std::basic_string::cbegin.3 \ No newline at end of file diff --git a/man/std::string::c_str.3 b/man/std::string::c_str.3 deleted file mode 120000 index 3a01af623..000000000 --- a/man/std::string::c_str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::c_str.3 \ No newline at end of file diff --git a/man/std::string::c_str.3 b/man/std::string::c_str.3 new file mode 100644 index 000000000..e1a3268f3 --- /dev/null +++ b/man/std::string::c_str.3 @@ -0,0 +1,88 @@ +.TH std::basic_string::c_str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::c_str \- std::basic_string::c_str + +.SH Synopsis + const CharT* c_str() const; (noexcept since C++11) + (constexpr since C++20) + + Returns a pointer to a null-terminated character array with data equivalent to those + stored in the string. + + The pointer is such that the range [c_str(), c_str() + size()] is valid and the + values in it correspond to the values stored in the string with an additional null + character after the last position. + + The pointer obtained from c_str() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string + , excluding operator[], at(), front(), back(), begin(), rbegin(), end() and + rend() + \fI(since C++11)\fP. + + Writing to the character array accessed through c_str() is undefined behavior. + + c_str() and data() perform the same function. \fI(since C++11)\fP + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying character storage. + + c_str()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + c_str() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Notes + + The pointer obtained from c_str() may only be treated as a pointer to a + null-terminated character string if the string object does not contain other null + characters. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + extern "C" void c_func(const char* c_str) + { + printf("c_func called with '%s'\\n", c_str); + } + + int main() + { + std::string const s("Emplary"); + const char* p = s.c_str(); + assert(s.size() == std::strlen(p)); + assert(std::equal(s.begin(), s.end(), p)); + assert(std::equal(p, p + s.size(), s.begin())); + assert('\\0' == *(p + s.size())); + + c_func(s.c_str()); + } + +.SH Output: + + c_func called with 'Emplary' + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP diff --git a/man/std::string::capacity.3 b/man/std::string::capacity.3 deleted file mode 120000 index 6045777da..000000000 --- a/man/std::string::capacity.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::capacity.3 \ No newline at end of file diff --git a/man/std::string::capacity.3 b/man/std::string::capacity.3 new file mode 100644 index 000000000..32f50b319 --- /dev/null +++ b/man/std::string::capacity.3 @@ -0,0 +1,93 @@ +.TH std::basic_string::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::capacity \- std::basic_string::capacity + +.SH Synopsis + size_type capacity() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the number of characters that the string has currently allocated space for. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Capacity of the currently allocated storage, i.e. the storage available for storing + elements. + +.SH Complexity + + Constant. + +.SH Notes + + Memory locations obtained from the allocator but not available for storing any + element are not counted in the allocated storage. Note that the null terminator is + not an element of the std::basic_string. + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_capacity(std::string const& s) + { + std::cout << std::quoted(s) << " has capacity " << s.capacity() << ".\\n"; + } + + int main() + { + std::string s{"Exemplar"}; + show_capacity(s); + + s += " is an example string."; + show_capacity(s); + + s.clear(); + show_capacity(s); + + std::cout << "\\nDemonstrate the capacity's growth policy." + "\\nSize: Capacity: Ratio:\\n" << std::left; + + std::string g; + auto old_cap{g.capacity()}; + + for (int mark{}; mark != 5; ++mark) + { + while (old_cap == g.capacity()) + g.push_back('.'); + + std::cout << std::setw( 7) << g.size() + << std::setw(11) << g.capacity() + << std::setw(10) << g.capacity() / static_cast(old_cap) << '\\n'; + + old_cap = g.capacity(); + } + } + +.SH Possible output: + + "Exemplar" has capacity 15. + "Exemplar is an example string." has capacity 30. + "" has capacity 30. + + Demonstrate the capacity's growth policy. + Size: Capacity: Ratio: + 16 30 2 + 31 60 2 + 61 120 2 + 121 240 2 + 241 480 2 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP diff --git a/man/std::string::clear.3 b/man/std::string::clear.3 deleted file mode 120000 index df77a9b91..000000000 --- a/man/std::string::clear.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::clear.3 \ No newline at end of file diff --git a/man/std::string::clear.3 b/man/std::string::clear.3 new file mode 100644 index 000000000..a1e021b20 --- /dev/null +++ b/man/std::string::clear.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::clear \- std::basic_string::clear + +.SH Synopsis + void clear(); (noexcept since C++11) + (constexpr since C++20) + + Removes all characters from the string as if by executing erase(begin(), end()). + + All pointers, references, and iterators are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Unlike for std::vector::clear, the C++ standard does not explicitly require that + capacity is unchanged by this function, but existing implementations do not change + capacity. This means that they do not release the allocated memory (see also + shrink_to_fit). + +.SH Complexity + + Linear in the size of the string, although existing implementations operate in + constant time. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s{"Exemplar"}; + std::string::size_type const capacity = s.capacity(); + + s.clear(); + assert(s.capacity() == capacity); // <- not guaranteed + assert(s.empty()); + assert(s.size() == 0); + } + +.SH See also + + erase removes characters + \fI(public member function)\fP diff --git a/man/std::string::compare.3 b/man/std::string::compare.3 deleted file mode 120000 index abd41e671..000000000 --- a/man/std::string::compare.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::compare.3 \ No newline at end of file diff --git a/man/std::string::compare.3 b/man/std::string::compare.3 new file mode 100644 index 000000000..890b367f1 --- /dev/null +++ b/man/std::string::compare.3 @@ -0,0 +1,285 @@ +.TH std::basic_string::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::compare \- std::basic_string::compare + +.SH Synopsis + (noexcept since + int compare( const basic_string& str ) const; \fB(1)\fP C++11) + (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(2)\fP (constexpr since + const basic_string& str ) const; C++20) + int compare( size_type pos1, size_type count1, + + const basic_string& str, \fI(until C++14)\fP + + size_type pos2, size_type count2 + ) const; + int compare( size_type pos1, size_type count1, + \fI(since C++14)\fP + const basic_string& str, (constexpr since + C++20) + size_type pos2, size_type count2 + = npos ) const; + int compare( const CharT* s ) const; \fB(4)\fP (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(5)\fP (constexpr since + const CharT* s ) const; C++20) + int compare( size_type pos1, size_type count1, \fB(3)\fP (constexpr since + const CharT* s, size_type count2 \fB(6)\fP C++20) + ) const; + template< class StringViewLike > \fI(since C++17)\fP + int compare( const StringViewLike& t ) const \fB(7)\fP (constexpr since + noexcept(/* see below */); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + int compare( size_type pos1, size_type count1, \fB(8)\fP (constexpr since + C++20) + const StringViewLike& t ) const; + template< class StringViewLike > + + int compare( size_type pos1, size_type count1, \fI(since C++17)\fP + const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos2, size_type count2 + = npos) const; + + Compares two character sequences. + + 1) Compares this string to str. + 2) Compares a [pos1, pos1 + count1) substring of this string to str. + * If count1 > size() - pos1, the substring is [pos1, size()). + 3) Compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of str. + * If count1 > size() - pos1, the first substring is [pos1, size()). + * If count2 > str.size() - pos2, the second substring is [pos2, str.size()). + 4) Compares this string to the null-terminated character sequence beginning at the + character pointed to by s with length Traits::length(s). + 5) Compares a [pos1, pos1 + count1) substring of this string to the null-terminated + character sequence beginning at the character pointed to by s with length + Traits::length(s). + * If count1 > size() - pos1, the substring is [pos1, size()). + 6) Compares a [pos1, pos1 + count1) substring of this string to the characters in + the range [s, s + count2). The characters in [s, s + count2) may include null + characters. + * If count1 > size() - pos1, the substring is [pos1, size()). + 7-9) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then + 7) compares this string to sv; + 8) compares a [pos1, pos1 + count1) substring of this string to sv, as if by + std::basic_string_view(*this).substr(pos1, count1).compare(sv); + 9) compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of sv, as if by std::basic_string_view(*this) + .substr(pos1, count1).compare(sv.substr(pos2, count2)). + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false.. + + A character sequence consisting of count1 characters starting at data1 is compared + to a character sequence consisting of count2 characters starting at data2 as + follows: + + * First, calculate the number of characters to compare, as if by size_type rlen = + std::min(count1, count2). + * Then compare the sequences by calling Traits::compare(data1, data2, rlen). For + standard strings this function performs character-by-character lexicographical + comparison. If the result is zero (the character sequences are equal so far), + then their sizes are compared as follows: + + Condition Result Return value + Traits::compare(data1, data2, rlen) < 0 data1 is less than <0 + data2 + size1 < size2 data1 is less than <0 + data2 + Traits::compare(data1, data2, rlen) == size1 == data1 is equal to 0 + 0 size2 data2 + size1 > size2 data1 is greater >0 + than data2 + Traits::compare(data1, data2, rlen) > 0 data1 is greater >0 + than data2 + +.SH Parameters + + str - other string to compare to + s - pointer to the character string to compare to + count1 - number of characters of this string to compare + pos1 - position of the first character in this string to compare + count2 - number of characters of the given string to compare + pos2 - position of the first character of the given string to compare + t - object (convertible to std::basic_string_view) to compare to + +.SH Return value + + * Negative value if *this appears before the character sequence specified by the + arguments, in lexicographical order. + * Zero if both character sequences compare equivalent. + * Positive value if *this appears after the character sequence specified by the + arguments, in lexicographical order. + +.SH Exceptions + + The overloads taking parameters named pos1 or pos2 throws std::out_of_range if the + argument is out of range. + + 7) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + 8,9) Throws anything thrown by the conversion to std::basic_string_view. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Possible implementation + + overload \fB(1)\fP + template + int std::basic_string::compare + (const std::basic_string& s) const noexcept + { + size_type lhs_sz = size(); + size_type rhs_sz = s.size(); + int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz)); + if (result != 0) + return result; + if (lhs_sz < rhs_sz) + return -1; + if (lhs_sz > rhs_sz) + return 1; + return 0; + } + +.SH Notes + + For the situations when three-way comparison is not required, std::basic_string + provides the usual relational operators (<, <=, ==, >, etc). + + By default (with the default std::char_traits), this function is not + locale-sensitive. See std::collate::compare for locale-aware three-way string + comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print_compare_result(std::string_view str1, + std::string_view str2, + int compare_result) + { + if (compare_result < 0) + std::cout << std::quoted(str1) << " comes before " + << std::quoted(str2) << ".\\n"; + else if (compare_result > 0) + std::cout << std::quoted(str2) << " comes before " + << std::quoted(str1) << ".\\n"; + else + std::cout << std::quoted(str1) << " and " + << std::quoted(str2) << " are the same.\\n"; + } + + int main() + { + std::string batman{"Batman"}; + std::string superman{"Superman"}; + int compare_result{0}; + + // 1) Compare with other string + compare_result = batman.compare(superman); + std::cout << "1) "; + print_compare_result("Batman", "Superman", compare_result); + + // 2) Compare substring with other string + compare_result = batman.compare(3, 3, superman); + std::cout << "2) "; + print_compare_result("man", "Superman", compare_result); + + // 3) Compare substring with other substring + compare_result = batman.compare(3, 3, superman, 5, 3); + std::cout << "3) "; + print_compare_result("man", "man", compare_result); + + // Compare substring with other substring + // defaulting to end of other string + assert(compare_result == batman.compare(3, 3, superman, 5)); + + // 4) Compare with char pointer + compare_result = batman.compare("Superman"); + std::cout << "4) "; + print_compare_result("Batman", "Superman", compare_result); + + // 5) Compare substring with char pointer + compare_result = batman.compare(3, 3, "Superman"); + std::cout << "5) "; + print_compare_result("man", "Superman", compare_result); + + // 6) Compare substring with char pointer substring + compare_result = batman.compare(0, 3, "Superman", 5); + std::cout << "6) "; + print_compare_result("Bat", "Super", compare_result); + } + +.SH Output: + + 1) "Batman" comes before "Superman". + 2) "Superman" comes before "man". + 3) "man" and "man" are the same. + 4) "Batman" comes before "Superman". + 5) "Superman" comes before "man". + 6) "Bat" comes before "Super". + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the parameter count2 of overload default argument removed, + LWG 5 C++98 \fB(6)\fP split to overloads \fB(5)\fP and + had a default argument npos \fB(6)\fP + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(7)\fP caused ambiguity in avoided by making it a + some cases template + noexcept for overload \fB(7)\fP was + P1148R0 C++17 accidentally restored + dropped by the resolution of + LWG2946 + +.SH See also + + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + substr returns a substring + \fI(public member function)\fP + collate defines lexicographical comparison and hashing of strings + \fI(class template)\fP + strcoll compares two strings in accordance to the current locale + \fI(function)\fP + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + compares two views + compare \fI\fI(public member\fP function of\fP + std::basic_string_view) + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::contains.3 b/man/std::string::contains.3 new file mode 100644 index 000000000..a6b202311 --- /dev/null +++ b/man/std::string::contains.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::contains \- std::basic_string::contains + +.SH Synopsis + constexpr bool + contains( std::basic_string_view sv ) const \fB(1)\fP (since C++23) + noexcept; + constexpr bool \fB(2)\fP (since C++23) + contains( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP (since C++23) + contains( const CharT* s ) const; + + Checks if the string contains the given substring. The substring may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void test_substring(const std::string& str, SubstrType subs) + { + constexpr char delim = std::is_scalar_v ? '\\'' : '\\"'; + std::cout << std::quoted(str) + << (str.contains(subs) ? " contains " + : " does not contain ") + << std::quoted(std::string{subs}, delim) << '\\n'; + } + + int main() + { + using namespace std::literals; + + auto helloWorld = "hello world"s; + + test_substring(helloWorld, "hello"sv); + test_substring(helloWorld, "goodbye"sv); + test_substring(helloWorld, 'w'); + test_substring(helloWorld, 'x'); + } + +.SH Output: + + "hello world" contains "hello" + "hello world" does not contain "goodbye" + "hello world" contains 'w' + "hello world" does not contain 'x' + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::copy.3 b/man/std::string::copy.3 deleted file mode 120000 index 18592fc3f..000000000 --- a/man/std::string::copy.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::copy.3 \ No newline at end of file diff --git a/man/std::string::copy.3 b/man/std::string::copy.3 new file mode 100644 index 000000000..5258bb301 --- /dev/null +++ b/man/std::string::copy.3 @@ -0,0 +1,81 @@ +.TH std::basic_string::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::copy \- std::basic_string::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos (constexpr since C++20) + = 0 ) const; + + Copies a substring [pos, pos + count) to character string pointed to by dest. If the + requested substring lasts past the end of the string, or if count == npos, the + copied substring is [pos, size()). + + The resulting character string is not null-terminated. + +.SH Parameters + + dest - pointer to the destination character string + count - length of the substring + pos - position of the first character to include + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string foo("WINE"); + + // brace-initialization initializes all characters to 0, + // providing a null-terminator + char bar[4]{}; + + // do not copy the last char, to guarantee null-termination + foo.copy(bar, sizeof bar - 1); + + std::cout << bar << '\\n'; // requires bar to be null-terminated + } + +.SH Output: + + WIN + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string_view)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::string::data.3 b/man/std::string::data.3 deleted file mode 120000 index e88dffdcc..000000000 --- a/man/std::string::data.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::data.3 \ No newline at end of file diff --git a/man/std::string::data.3 b/man/std::string::data.3 new file mode 100644 index 000000000..e081790d6 --- /dev/null +++ b/man/std::string::data.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::data \- std::basic_string::data + +.SH Synopsis + const CharT* data() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + CharT* data() noexcept; \fB(2)\fP \fI(since C++17)\fP + (constexpr since C++20) + + Returns a pointer to the underlying array serving as character storage. The pointer + is such that the range + + [data(), data() + size()) \fI(until C++11)\fP + [data(), data() + size()] \fI(since C++11)\fP + + is valid and the values in it correspond to the values stored in the string. + + The returned array is not required to be null-terminated. + \fI(until C++11)\fP + If empty() returns true, the pointer is a non-null pointer that should + not be dereferenced. + The returned array is null-terminated, that is, data() and c_str() + perform the same function. + \fI(since C++11)\fP + If empty() returns true, the pointer points to a single null + character. + + The pointer obtained from data() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string, excluding operator[](), at(), + front(), back(), begin(), end(), rbegin(), rend(). + 1) Modifying the character array accessed through the const overload of data has + undefined behavior. + 2) Modifying the past-the-end null terminator stored at data() + size() to any value + other than CharT() has undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character storage. + + data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + data() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string const s("Emplary"); + assert(s.size() == std::strlen(s.data())); + assert(std::equal(s.begin(), s.end(), s.data())); + assert(std::equal(s.data(), s.data() + s.size(), s.begin())); + assert('\\0' == *(s.data() + s.size())); + } + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + c_str returns a non-modifiable standard C character array version of the string + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::empty.3 b/man/std::string::empty.3 deleted file mode 120000 index 57ffefac4..000000000 --- a/man/std::string::empty.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::empty.3 \ No newline at end of file diff --git a/man/std::string::empty.3 b/man/std::string::empty.3 new file mode 100644 index 000000000..515c30654 --- /dev/null +++ b/man/std::string::empty.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::empty \- std::basic_string::empty + +.SH Synopsis + bool empty() const; (noexcept since C++11) + (constexpr since C++20) + + Checks if the string has no characters, i.e. whether begin() == end(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the string is empty, false otherwise + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::boolalpha(std::cout); + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = "Exemplar"; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = ""; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + } + +.SH Output: + + s.empty():true s:'' + s.empty():false s:'Exemplar' + s.empty():true s:'' + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + empty checks whether the view is empty + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::end,.3 b/man/std::string::end,.3 new file mode 100644 index 000000000..a29f4fa07 --- /dev/null +++ b/man/std::string::end,.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::end, \- std::basic_string::end, + +.SH Synopsis + + iterator end(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the character following the last character of the string. + This character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemparl"); + std::next_permutation(s.begin(), s.end()); + + std::string c; + std::copy(s.cbegin(), s.cend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "Exemplar" + } + +.SH Output: + + Exemplar + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::end,std::basic_string::cend.3 b/man/std::string::end,std::basic_string::cend.3 deleted file mode 120000 index 8e6f5e8ed..000000000 --- a/man/std::string::end,std::basic_string::cend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::end,std::basic_string::cend.3 \ No newline at end of file diff --git a/man/std::string::ends_with.3 b/man/std::string::ends_with.3 new file mode 100644 index 000000000..daa271fc6 --- /dev/null +++ b/man/std::string::ends_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::ends_with \- std::basic_string::ends_with + +.SH Synopsis + constexpr bool + ends_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + ends_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + ends_with( const CharT* s ) const; + + Checks if the string ends with the given suffix. The suffix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).ends_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.ends_with("C++20!"sv) // (1) + && !str.ends_with("c++20!"sv) // (1) + && str.ends_with("C++20!"s) // (1) implicit conversion string to string_view + && !str.ends_with("c++20!"s) // (1) implicit conversion string to string_view + && str.ends_with('!') // (2) + && !str.ends_with('?') // (2) + && str.ends_with("C++20!") // (3) + && !str.ends_with("c++20!") // (3) + ); + } + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::string::erase.3 b/man/std::string::erase.3 deleted file mode 120000 index 533c91687..000000000 --- a/man/std::string::erase.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::erase.3 \ No newline at end of file diff --git a/man/std::string::erase.3 b/man/std::string::erase.3 new file mode 100644 index 000000000..caa61fc84 --- /dev/null +++ b/man/std::string::erase.3 @@ -0,0 +1,109 @@ +.TH std::basic_string::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::erase \- std::basic_string::erase + +.SH Synopsis + basic_string& erase( (constexpr since + size_type index = 0, \fB(1)\fP C++20) + size_type count = npos ); + iterator erase( iterator \fI(until C++11)\fP + position ); + iterator erase( \fI(since C++11)\fP + const_iterator position ); (constexpr since + \fB(2)\fP C++20) + iterator erase( iterator \fI(until C++11)\fP + first, iterator last ); + iterator erase( \fB(3)\fP \fI(since C++11)\fP + const_iterator first, (constexpr since + const_iterator last ); C++20) + + Removes specified characters from the string. + + 1) Removes std::min(count, size() - index) characters starting at index. + 2) Removes the character at position. + If position is not a dereferenceable iterator on *this, the behavior is undefined. + 3) Removes the characters in the range [first, last). + If first or last is not a valid iterator on *this, or [first, last) is not a valid + range, the behavior is undefined. + +.SH Parameters + + index - first character to remove + count - number of characters to remove + position - iterator to the character to remove + first, last - range of the characters to remove + +.SH Return value + + 1) *this + 2) Iterator pointing to the character immediately following the character erased, or + end() if no such character exists. + 3) Iterator pointing to the character last pointed to before the erase, or end() if + no such character exists. + +.SH Exceptions + + 1) std::out_of_range if index > size(). + 2,3) Throws nothing. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s = "This Is An Example"; + std::cout << "1) " << s << '\\n'; + + s.erase(7, 3); // erases " An" using overload (1) + std::cout << "2) " << s << '\\n'; + + s.erase(std::find(s.begin(), s.end(), ' ')); // erases first ' '; overload (2) + std::cout << "3) " << s << '\\n'; + + s.erase(s.find(' ')); // trims from ' ' to the end of the string; overload (1) + std::cout << "4) " << s << '\\n'; + + auto it = std::next(s.begin(), s.find('s')); // obtains iterator to the first 's' + s.erase(it, std::next(it, 2)); // erases "sI"; overload (3) + std::cout << "5) " << s << '\\n'; + } + +.SH Output: + + 1) This Is An Example + 2) This Is Example + 3) ThisIs Example + 4) ThisIs + 5) This + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(3)\fP did not erase the character returns an iterator + LWG 27 C++98 last pointed to, but it returned pointing to that + the iterator pointing to the character character + immediately following that character + overload \fB(2)\fP explicitly required position + LWG 428 C++98 to be valid, but removed the + SequenceContainer requires it to be explicit requirement + dereferenceable (stricter) + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + +.SH See also + + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::string::find.3 b/man/std::string::find.3 deleted file mode 120000 index 6675f6f1b..000000000 --- a/man/std::string::find.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find.3 \ No newline at end of file diff --git a/man/std::string::find.3 b/man/std::string::find.3 new file mode 100644 index 000000000..6ae3d060f --- /dev/null +++ b/man/std::string::find.3 @@ -0,0 +1,171 @@ +.TH std::basic_string::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find \- std::basic_string::find + +.SH Synopsis + size_type find( const basic_string& str, size_type pos = \fB(1)\fP (noexcept since C++11) + 0 ) const; (constexpr since C++20) + size_type find( const CharT* s, size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find( const CharT* s, size_type pos = 0 ) \fB(3)\fP (constexpr since C++20) + const; + size_type find( CharT ch, size_type pos = 0 ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type find( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first substring equal to the given character sequence. Search begins at + pos, i.e. the found substring must not begin in a position preceding pos. + + 1) Finds the first substring equal to str. + 2) Finds the first substring equal to the range [s, s + count). This range may + contain null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character ch (treated as a single-character substring by the + formal rules below). + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first substring equal to sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + Formally, a substring str is said to be found at position xpos if all of the + following are true: + + * xpos >= pos + * xpos + str.size() <= size() + * for all positions n in str, Traits::eq(at(xpos + n), str.at(n)). + + In particular, this implies that + + * a substring can be found only if pos <= size() - str.size() + * an empty substring is found at pos if and only if pos <= size() + * for a non-empty substring, if pos >= size(), the function always returns npos. + +.SH Parameters + + str - string to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(int id, std::string::size_type n, std::string const& s) + { + std::cout << id << ") "; + if (std::string::npos == n) + std::cout << "not found! n == npos\\n"; + else + std::cout << "found @ n = " << n << ", substr(" << n << ") = " + << std::quoted(s.substr(n)) << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; /* + ^ ^ ^ + 1 2 3 */ + + // search from beginning of string + n = s.find("is"); + print(1, n, s); + + // search from position 5 + n = s.find("is", 5); + print(2, n, s); + + // find a single character + n = s.find('a'); + print(3, n, s); + + // find a single character + n = s.find('q'); + print(4, n, s); + } + +.SH Output: + + 1) found @ n = 2, substr\fB(2)\fP = "is is a string" + 2) found @ n = 5, substr\fB(5)\fP = "is a string" + 3) found @ n = 8, substr\fB(8)\fP = "a string" + 4) not found! n == npos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + strstr finds the first occurrence of a substring of characters + \fI(function)\fP + finds the first occurrence of a wide string within another wide + wcsstr string + \fI(function)\fP + strchr finds the first occurrence of a character + \fI(function)\fP + wcschr finds the first occurrence of a wide character in a wide string + \fI(function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find characters in the view + find \fI(public member function of std::basic_string_view)\fP + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::find_first_not_of.3 b/man/std::string::find_first_not_of.3 deleted file mode 120000 index 7cd66aee2..000000000 --- a/man/std::string::find_first_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_not_of.3 \ No newline at end of file diff --git a/man/std::string::find_first_not_of.3 b/man/std::string::find_first_not_of.3 new file mode 100644 index 000000000..795a2e7ce --- /dev/null +++ b/man/std::string::find_first_not_of.3 @@ -0,0 +1,141 @@ +.TH std::basic_string::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_not_of \- std::basic_string::find_first_not_of + +.SH Synopsis + size_type find_first_not_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_first_not_of( const CharT* s, \fB(3)\fP (constexpr since C++20) + size_type pos = 0 ) const; + size_type find_first_not_of( CharT ch, size_type pos = 0 \fB(4)\fP (noexcept since C++11) + ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const + noexcept(/* see below */); + + Finds the first character equal to none of the characters in the given character + sequence. The search considers only the range [pos, size()). If all characters in + the range can be found in the given character sequence, npos will be returned. + + 1) Finds the first character equal to none of characters in str. + 2) Finds the first character equal to none of characters in range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position for the search to start from + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or std::string::npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Permit uppercase letters, lowercase letters and numbers in macro names + const char* pattern = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "abcdefghijklmnopqrstuvwxyz" + "0123456789"; + + std::string data = "1) %FIX, 2) %HACK, and 3) %TODO"; + const std::string replacement = "%DONE%"; + + std::cout << "Before: " << data << '\\n'; + + for (std::string::size_type first{}, last{}; + (first = data.find('%', first)) != std::string::npos; + first += replacement.size()) + { + last = data.find_first_not_of(pattern, first + 1); + if (last == std::string::npos) + last = data.length(); + + // Now first at '%' and last is one past end of the found substring + data.replace(first, last - first, replacement); + } + + std::cout << "After: " << data << '\\n'; + } + +.SH Output: + + Before: 1) %FIX, 2) %HACK, and 3) %TODO + After: 1) %DONE%, 2) %DONE%, and 3) %DONE% + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::find_first_of.3 b/man/std::string::find_first_of.3 deleted file mode 120000 index 497a89646..000000000 --- a/man/std::string::find_first_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_of.3 \ No newline at end of file diff --git a/man/std::string::find_first_of.3 b/man/std::string::find_first_of.3 new file mode 100644 index 000000000..e6263f90c --- /dev/null +++ b/man/std::string::find_first_of.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_of \- std::basic_string::find_first_of + +.SH Synopsis + size_type find_first_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_of( const CharT* s, + size_type pos, size_type count \fB(2)\fP (constexpr since C++20) + ) const; + size_type find_first_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + 0 ) const; + size_type find_first_of( CharT ch, size_type pos = 0 ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first character equal to one of the characters in the given character + sequence. The search considers only the range [pos, size()). If none of the + characters in the given character sequence is present in the range, npos will be + returned. + + 1) Finds the first character equal to one of the characters in str. + 2) Finds the first character equal to one of the characters in the range [s, s + + count). This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to one of the characters in character string + pointed to by s. The length of the string is determined by the first null character + using Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to one of the characters in + sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to begin searching + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Traits::eq() is used to perform the comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + std::string::size_type sz; + + // (1) + sz = "alignas"s.find_first_of("klmn"s); + // └────────────────────────┘ + assert(sz == 1); + + sz = "alignof"s.find_first_of("wxyz"s); + // no match + assert(sz == std::string::npos); + + // (2) + sz = "consteval"s.find_first_of("xyzabc", 0, 3); + // no match (× are not targets) ××× + assert(sz == std::string::npos); + + sz = "consteval"s.find_first_of("xyzabc", 0, 6); + // └───────────────────────────────┘ + assert(sz == 0); + + // (3) + sz = "decltype"s.find_first_of("xyzabc"); + // └────────────────────────────┘ + assert(sz == 2); + + // (4) + sz = "co_await"s.find_first_of('a'); + // └──────────────────────┘ + assert(sz == 3); + + // (5) + sz = "constinit"s.find_first_of("int"sv); + // └─────────────────────────┘ + assert(sz == 2); + + std::cout << "All tests passed.\\n"; + } + +.SH Output: + + All tests passed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI(public member function of std::basic_string_view)\fP + + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::find_last_not_of.3 b/man/std::string::find_last_not_of.3 deleted file mode 120000 index 85f8838a9..000000000 --- a/man/std::string::find_last_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_not_of.3 \ No newline at end of file diff --git a/man/std::string::find_last_not_of.3 b/man/std::string::find_last_not_of.3 new file mode 100644 index 000000000..b325c1428 --- /dev/null +++ b/man/std::string::find_last_not_of.3 @@ -0,0 +1,160 @@ +.TH std::basic_string::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_not_of \- std::basic_string::find_last_not_of + +.SH Synopsis + size_type find_last_not_of( const basic_string& str, (noexcept since C++11) + size_type pos = npos ) \fB(1)\fP (constexpr since C++20) + const; + size_type find_last_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_last_not_of( const CharT* s, size_type \fB(3)\fP (constexpr since C++20) + pos = npos ) const; + size_type find_last_not_of( CharT ch, size_type pos = \fB(4)\fP (noexcept since C++11) + npos ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to none of the characters in the given character + sequence. The search considers only the range [0, pos]. If all characters in the + range can be found in the given character sequence, npos will be returned. + + 1) Finds the last character equal to none of characters in str. + 2) Finds the last character equal to none of characters in the range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to end search + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v< + const T&, std::basic_string_view>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + void show_pos(const std::string& str, std::string::size_type found) + { + if (found != std::string::npos) + std::cout << '[' << found << "] = \\'" << str[found] << "\\'\\n"; + else + std::cout << "not found\\n"; + } + + int main() + { + std::string str{"abc_123"}; + char const* skip_set{"0123456789"}; + std::string::size_type str_last_pos{std::string::npos}; + + show_pos(str, str.find_last_not_of(skip_set)); // [3] = '_' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of(skip_set, str_last_pos)); // [2] = 'c' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of('c', str_last_pos)); // [1] = 'b' + + const char arr[]{'3', '4', '5'}; + show_pos(str, str.find_last_not_of(arr)); // [5] = '2' + + str_last_pos = 2; + std::string::size_type skip_set_size{4}; + show_pos(str, str.find_last_not_of(skip_set, + str_last_pos, + skip_set_size)); // [2] = 'c' + + show_pos(str, str.find_last_not_of("abc")); // [6] = '3' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of("abc", str_last_pos)); // not found + } + +.SH Output: + + [3] = '_' + [2] = 'c' + [1] = 'b' + [5] = '2' + [2] = 'c' + [6] = '3' + not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::find_last_of.3 b/man/std::string::find_last_of.3 deleted file mode 120000 index 18ea1b60d..000000000 --- a/man/std::string::find_last_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_of.3 \ No newline at end of file diff --git a/man/std::string::find_last_of.3 b/man/std::string::find_last_of.3 new file mode 100644 index 000000000..e3ff59859 --- /dev/null +++ b/man/std::string::find_last_of.3 @@ -0,0 +1,126 @@ +.TH std::basic_string::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_of \- std::basic_string::find_last_of + +.SH Synopsis + size_type find_last_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = npos ) const; (constexpr since C++20) + size_type find_last_of( const CharT* s, + size_type pos, size_type count ) \fB(2)\fP (constexpr since C++20) + const; + size_type find_last_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + npos ) const; + size_type find_last_of( CharT ch, size_type pos = npos ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to one of characters in the given character sequence. + The exact search algorithm is not specified. The search considers only the range + [0, pos]. If none of the characters in the given character sequence is present in + the range, npos will be returned. + + 1) Finds the last character equal to one of characters in str. + 2) Finds the last character equal to one of characters in range [s, s + count). This + range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to one of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to one of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which the search is to finish + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string path = "/root/config"; + auto const pos = path.find_last_of('/'); + const auto leaf = path.substr(pos + 1); + + std::cout << leaf << '\\n'; + } + +.SH Output: + + config + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::front.3 b/man/std::string::front.3 deleted file mode 120000 index 6e46155d2..000000000 --- a/man/std::string::front.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::front.3 \ No newline at end of file diff --git a/man/std::string::front.3 b/man/std::string::front.3 new file mode 100644 index 000000000..978ec6830 --- /dev/null +++ b/man/std::string::front.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::front \- std::basic_string::front + +.SH Synopsis + CharT& front(); \fB(1)\fP (constexpr since C++20) + const CharT& front() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the first character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, front() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& f1 = s.front(); + f1 = 'e'; + std::cout << s << '\\n'; // "exemplary" + + std::string const c("Exemplary"); + char const& f2 = c.front(); + std::cout << &f2 << '\\n'; // "Exemplary" + } + +.SH Output: + + exemplary + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function front() + +.SH See also + + back accesses the last character + (DR*) \fI(public member function)\fP + front accesses the first character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::get_allocator.3 b/man/std::string::get_allocator.3 deleted file mode 120000 index a59c7178f..000000000 --- a/man/std::string::get_allocator.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::get_allocator.3 \ No newline at end of file diff --git a/man/std::string::get_allocator.3 b/man/std::string::get_allocator.3 new file mode 100644 index 000000000..52b590226 --- /dev/null +++ b/man/std::string::get_allocator.3 @@ -0,0 +1,30 @@ +.TH std::basic_string::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::get_allocator \- std::basic_string::get_allocator + +.SH Synopsis + allocator_type get_allocator() const; (noexcept since C++20) + (constexpr since C++20) + + Returns the allocator associated with the string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated allocator. + +.SH Complexity + + Constant. + +.SH See also + + allocator the default allocator + \fI(class template)\fP + allocator_traits provides information about allocator types + \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::string::insert.3 b/man/std::string::insert.3 deleted file mode 120000 index 06d0b9ef6..000000000 --- a/man/std::string::insert.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::insert.3 \ No newline at end of file diff --git a/man/std::string::insert.3 b/man/std::string::insert.3 new file mode 100644 index 000000000..28be988e6 --- /dev/null +++ b/man/std::string::insert.3 @@ -0,0 +1,228 @@ +.TH std::basic_string::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert \- std::basic_string::insert + +.SH Synopsis + basic_string& insert( (constexpr + size_type index, size_type \fB(1)\fP since + count, CharT ch ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(2)\fP since + CharT* s ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(3)\fP since + CharT* s, size_type count ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(4)\fP since + basic_string& str ); C++20) + basic_string& insert( + size_type index, const + basic_string& str, (until + C++14) + size_type s_index, size_type + count ); + basic_string& insert( (since + size_type index, const C++14) + basic_string& str, (constexpr + since + size_type s_index, size_type C++20) + count = npos ); + iterator insert( iterator (until + pos, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, CharT ch (constexpr + ); since + C++20) + void insert( iterator pos, (until + size_type count, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, (constexpr + size_type count, CharT ch ); since + C++20) + template< class InputIt > + void insert( iterator pos, \fB(5)\fP (until + InputIt first, InputIt last C++11) + ); + template< class InputIt > (since + iterator insert( C++11) + const_iterator pos, InputIt (constexpr + first, InputIt last ); \fB(6)\fP since + C++20) + iterator insert( (since + const_iterator pos, \fB(7)\fP C++11) + std::initializer_list \fB(9)\fP (constexpr + ilist ); since + C++20) + template< class \fB(8)\fP (since + StringViewLike > C++17) + basic_string& insert( \fB(10)\fP (constexpr + size_type index, const since + StringViewLike& t ); C++20) + template< class + StringViewLike > + (since + basic_string& insert( C++17) + size_type index, const \fB(11)\fP (constexpr + StringViewLike& t, since + C++20) + + size_type t_index, size_type + count = npos ); + + Inserts characters into the string. + + 1) Inserts count copies of character ch at the position index. + 2) Inserts null-terminated character string pointed to by s at the position index. + The length of the string is determined by the first null character using + Traits::length(s). + 3) Inserts the characters in the range [s, s + count) at the position index. The + range can contain null characters. + 4) Inserts string str at the position index. + 5) Inserts a string, obtained by str.substr(s_index, count) at the position index. + 6) Inserts character ch before the character pointed by pos. + 7) Inserts count copies of character ch before the element (if any) pointed by pos. + 8) Inserts characters from the range [first, last) before the element (if any) + pointed by pos, as if by insert(pos - begin(), basic_string(first, last, + get_allocator())). + + This overload does not participate in overload resolution if InputIt \fI(since C++11)\fP + does not satisfy LegacyInputIterator. + + 9) Inserts elements from initializer list ilist before the element (if any) pointed + by pos. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts the elements from sv before the element (if any) + pointed by index, as if by insert(index, sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 11) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts, before the element (if any) pointed by index, the + characters from the subview [t_index, t_index + count) of sv. + * If the requested subview lasts past the end of sv, or if count == npos, the + resulting subview is [t_index, sv.size()). + * If t_index > sv.size(), or if index > size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + index - position at which the content will be inserted + pos - iterator before which the characters will be inserted + ch - character to insert + count - number of characters to insert + s - pointer to the character string to insert + str - string to insert + first, last - range defining characters to insert + s_index - position of the first character in str to insert + ilist - std::initializer_list to insert the characters from + t - object (convertible to std::basic_string_view) to insert the + characters from + t_index - position of the first character in t to insert +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1-5) *this + 6-9) An iterator which refers to the copy of the first inserted character or pos if + no characters were inserted (count == 0 or first == last or ilist.size() == 0) + 10,11) *this + +.SH Exceptions + + 1-4,10) Throws std::out_of_range if index > size(). + 5) Throws std::out_of_range if index > size() or if s_index > str.size(). + 11) Throws std::out_of_range if index > size() or if t_index > sv.size(). + + In all cases, throws std::length_error if size() + ins_count > max_size() where + ins_count is the number of characters that will be inserted. + + In all cases, if std::allocator_traits::allocate throws an \fI(since C++20)\fP + exception, it is rethrown. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::string_literals; + + int main() + { + std::string s = "xmplr"; + + // insert(size_type index, size_type count, char ch) + s.insert(0, 1, 'E'); + assert("Exmplr" == s); + + // insert(size_type index, const char* s) + s.insert(2, "e"); + assert("Exemplr" == s); + + // insert(size_type index, string const& str) + s.insert(6, "a"s); + assert("Exemplar" == s); + + // insert(size_type index, string const& str, + // size_type s_index, size_type count) + s.insert(8, " is an example string."s, 0, 14); + assert("Exemplar is an example" == s); + + // insert(const_iterator pos, char ch) + s.insert(s.cbegin() + s.find_first_of('n') + 1, ':'); + assert("Exemplar is an: example" == s); + + // insert(const_iterator pos, size_type count, char ch) + s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '='); + assert("Exemplar is an:== example" == s); + + // insert(const_iterator pos, InputIt first, InputIt last) + { + std::string seq = " string"; + s.insert(s.begin() + s.find_last_of('e') + 1, + std::begin(seq), std::end(seq)); + assert("Exemplar is an:== example string" == s); + } + + // insert(const_iterator pos, std::initializer_list) + s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'}); + assert("Exemplar is an:== example string." == s); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 7 C++98 overload (8) referred to a non-existing refers to overload (4) + overload correctly + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2946 C++17 overload (10) caused ambiguity in some avoided by making it a + cases template + +.SH See also + + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP diff --git a/man/std::string::insert_range.3 b/man/std::string::insert_range.3 new file mode 100644 index 000000000..172031ebb --- /dev/null +++ b/man/std::string::insert_range.3 @@ -0,0 +1,84 @@ +.TH std::basic_string::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert_range \- std::basic_string::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr iterator insert_range( const_iterator pos, R&& rg ); + + Inserts characters from the range rg before the element (if any) pointed by pos. + + Equivalent to + + return insert(pos - begin(), + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + pos - iterator before which the characters will be inserted + rg - a container compatible range + +.SH Return value + + An iterator which refers to the first inserted character, or pos if no characters + were inserted because rg was empty. + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If std::allocator_traits::allocate throws an exception, it is rethrown. + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto source = {'l', 'i', 'b', '_'}; + std::string target{"__cpp_containers_ranges"}; + // ^insertion will occur + // before this position + + const auto pos = target.find("container"); + assert(pos != target.npos); + auto iter = std::next(target.begin(), pos); + + #ifdef __cpp_lib_containers_ranges + target.insert_range(iter, source); + #else + target.insert(iter, source.begin(), source.end()); + #endif + + assert(target == "__cpp_lib_containers_ranges"); + // ^^^^ + } + +.SH See also + + insert inserts characters + \fI(public member function)\fP diff --git a/man/std::string::max_size.3 b/man/std::string::max_size.3 deleted file mode 120000 index 450f8a80c..000000000 --- a/man/std::string::max_size.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::max_size.3 \ No newline at end of file diff --git a/man/std::string::max_size.3 b/man/std::string::max_size.3 new file mode 100644 index 000000000..806a1dd4a --- /dev/null +++ b/man/std::string::max_size.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::max_size \- std::basic_string::max_size + +.SH Synopsis + size_type max_size() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the maximum number of elements the string is able to hold due to system or + library implementation limitations, i.e. std::distance(begin(), end()) for the + largest string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + #include + + template + void print_basic_string_max_size() + { + std::basic_string s; + auto max_size = s.max_size(); + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "basic_string<" << boost::core::demangle(typeid(T).name()) + << ">:\\n\\t" << max_size << " = "; + std::cout << std::setprecision(3) << (double) max_size << " = "; + std::cout.imbue(std::locale("C")); + std::cout << std::hex << std::setfill('0') << "0x" + << std::setw(sizeof(typename decltype(s)::size_type) << 1) + << max_size << '\\n' << std::dec; + }; + + int main() + { + std::cout << "Pointer size: " << CHAR_BIT * sizeof(void*) << " bits\\n" + "Maximum sizes:\\n"; + + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + + using CharT = std::array; + print_basic_string_max_size(); + } + +.SH Possible output: + + Pointer size: 64 bits + Maximum sizes: + basic_string: + 9,223,372,036,854,775,807 = 9.22e+18 = 0x7fffffffffffffff + basic_string: + 4,611,686,018,427,387,903 = 4.61e+18 = 0x3fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 1,152,921,504,606,846,975 = 1.15e+18 = 0x0fffffffffffffff + basic_string>: + 13,848,906,962,244,407 = 1.38e+16 = 0x00313381ec031337 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::npos.3 b/man/std::string::npos.3 deleted file mode 120000 index 4582d0216..000000000 --- a/man/std::string::npos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::npos.3 \ No newline at end of file diff --git a/man/std::string::npos.3 b/man/std::string::npos.3 new file mode 100644 index 000000000..cb8bcc779 --- /dev/null +++ b/man/std::string::npos.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::npos \- std::basic_string::npos + +.SH Synopsis + static const size_type npos = -1; + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of string indicator by the functions that expect a string index or as the error + indicator by the functions that return a string index. + +.SH Note + + Although the definition uses -1, size_type is an unsigned integer type, and the + value of npos is the largest positive value it can hold, due to signed-to-unsigned + implicit conversion. This is a portable way to specify the largest value of any + unsigned type. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // string search functions return npos if nothing is found + std::string s = "test"; + if (s.find('a') == s.npos) + std::cout << "no 'a' in 'test'\\n"; + + // functions that take string subsets as arguments + // use npos as the "all the way to the end" indicator + std::string s2(s, 2, std::string::npos); + std::cout << s2 << '\\n'; + + std::bitset<5> b("aaabb", std::string::npos, 'a', 'b'); + std::cout << b << '\\n'; + } + +.SH Output: + + no 'a' in 'test' + st + 00011 + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant of std::basic_string_view)\fP + diff --git a/man/std::string::operator+=.3 b/man/std::string::operator+=.3 deleted file mode 120000 index 54ff82159..000000000 --- a/man/std::string::operator+=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator+=.3 \ No newline at end of file diff --git a/man/std::string::operator+=.3 b/man/std::string::operator+=.3 new file mode 100644 index 000000000..6f5ea9049 --- /dev/null +++ b/man/std::string::operator+=.3 @@ -0,0 +1,120 @@ +.TH std::basic_string::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator+= \- std::basic_string::operator+= + +.SH Synopsis + basic_string& operator+=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator+=( CharT ch ); \fB(2)\fP (constexpr since C++20) + basic_string& operator+=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator+=( std::initializer_list \fB(4)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template< class StringViewLike > \fB(5)\fP \fI(since C++17)\fP + basic_string& operator+=( const StringViewLike& t ); (constexpr since C++20) + + Appends additional characters to the string. + + 1) Appends string str. + 2) Appends character ch. + 3) Appends the null-terminated character string pointed to by s. + 4) Appends characters in the initializer list ilist. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends characters in the string view sv as if by append(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string to append + ch - character value to append + s - pointer to a null-terminated character string to append + ilist - std::initializer_list with the characters to append + t - object (convertible to std::basic_string_view) with the characters to append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Overload \fB(2)\fP can accept any types that are implicitly convertible to CharT. For + std::string, where CharT is char, the set of acceptable types includes all + arithmetic types. This may have unintended effects. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str; + + // reserve sufficient storage space to avoid memory reallocation + str.reserve(50); + + std::cout << std::quoted(str) << '\\n'; // empty string + + str += "This"; + std::cout << std::quoted(str) << '\\n'; + + str += std::string(" is "); + std::cout << std::quoted(str) << '\\n'; + + str += 'a'; + std::cout << std::quoted(str) << '\\n'; + + str += {' ', 's', 't', 'r', 'i', 'n', 'g', '.'}; + std::cout << std::quoted(str) << '\\n'; + + str += 69.96; // Equivalent to str += static_cast(69.96); + // 'E' (ASCII code 69) is appended by overload (2), + // which might not be the intent. + + // To add a numeric value, consider std::to_string(): + str += std::to_string(1729); + + std::cout << std::quoted(str) << '\\n'; + } + +.SH Output: + + "" + "This" + "This is " + "This is a" + "This is a string." + "This is a string.E1729" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::string::operator=.3 b/man/std::string::operator=.3 deleted file mode 120000 index 5505d7126..000000000 --- a/man/std::string::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator=.3 \ No newline at end of file diff --git a/man/std::string::operator=.3 b/man/std::string::operator=.3 new file mode 100644 index 000000000..70b37150d --- /dev/null +++ b/man/std::string::operator=.3 @@ -0,0 +1,153 @@ +.TH std::basic_string::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator= \- std::basic_string::operator= + +.SH Synopsis + basic_string& operator=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator=( basic_string&& str ) \fB(2)\fP \fI(since C++11)\fP + noexcept(/* see below */); (constexpr since C++20) + basic_string& operator=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator=( CharT ch ); \fB(4)\fP (constexpr since C++20) + basic_string& operator=( std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template \fB(6)\fP \fI(since C++17)\fP + basic_string& operator=( const StringViewLike& t ); (constexpr since C++20) + basic_string& operator=( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + Replaces the contents of the string. + + 1) Replaces the contents with a copy of str. If *this and str are the same object, + this function has no effect. + 2) Replaces the contents with those of str using SequenceContainer's move assignment + semantics. + Unlike other sequence container move assignments, references, pointers, and + iterators to elements of str may be invalidated. + 3) Replaces the contents with those of null-terminated character string pointed to + by s as if by assign(s, Traits::length(s)). + 4) Replaces the contents with character ch as if by assign(std::addressof(ch), 1). + 5) Replaces the contents with those of the initializer list ilist as if by + assign(ilist.begin(), ilist.size()). + 6) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of the sv as if by + assign(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 7) std::basic_string cannot be assigned from nullptr. + +.SH Parameters + + ch - value to initialize characters of the string with + str - string to be used as source to initialize the string with + s - pointer to a null-terminated character string to use as source to initialize + the string with + ilist - std::initializer_list to initialize the string with + t - object convertible to std::basic_string_view to initialize the string with + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in size of str. + 2) Linear in the size of *this (formally, each CharT has to be destroyed). If + allocators do not compare equal and do not propagate, then also linear in the size + of str (copy must be made). + 3) Linear in size of s. + 4) Constant. + 5) Linear in size of ilist. + 6) Linear in size of t. + +.SH Exceptions + + 2) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str1; + std::string str2{"alpha"}; + + // (1) operator=(const basic_string&); + str1 = str2; + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "alpha" + + // (2) operator=(basic_string&&); + str1 = std::move(str2); + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "" or "alpha" (unspecified) + + // (3) operator=(const CharT*); + str1 = "beta"; + std::cout << std::quoted(str1) << '\\n'; // "beta" + + // (4) operator=(CharT); + str1 = '!'; + std::cout << std::quoted(str1) << '\\n'; // "!" + + // (5) operator=(std::initializer_list); + str1 = {'g', 'a', 'm', 'm', 'a'}; + std::cout << std::quoted(str1) << '\\n'; // "gamma" + + // (6) operator=(const T&); + str1 = 35U; // equivalent to str1 = static_cast(35U); + std::cout << std::quoted(str1) << '\\n'; // "#" (ASCII = 35) + } + +.SH Possible output: + + "alpha" "alpha" + "alpha" "" + "beta" + "!" + "gamma" + "#" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + the move assignment operator did not + LWG 2063 C++11 follow follows + SequenceContainer's semantic requirement + LWG 2946 C++17 overload \fB(6)\fP caused ambiguity in some avoided by making it a + cases template + +.SH See also + + constructor constructs a basic_string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assigns a view + operator= \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::operator[].3 b/man/std::string::operator[].3 deleted file mode 120000 index 05791619e..000000000 --- a/man/std::string::operator[].3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator[].3 \ No newline at end of file diff --git a/man/std::string::operator[].3 b/man/std::string::operator[].3 new file mode 100644 index 000000000..8fa941e51 --- /dev/null +++ b/man/std::string::operator[].3 @@ -0,0 +1,83 @@ +.TH std::basic_string::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator[] \- std::basic_string::operator[] + +.SH Synopsis + CharT& operator[]( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& operator[]( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos if pos < size(), or a + reference to CharT() if pos == size(). No bounds checking is performed. + + If pos > size(), the behavior is undefined. + + For overload \fB(1)\fP, if pos == size(), the behavior is undefined + if the object referred by the returned reference is modified to any value other than + CharT() + \fI(since C++11)\fP. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + *(begin() + pos) if pos < size(), or a reference to CharT() if pos == size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string e("Exemplar"); + for (unsigned i = e.length() - 1; i != 0; i /= 2) + std::cout << e[i]; + std::cout << '\\n'; + + const char* c = &e[0]; + std::cout << c << '\\n'; // print as a C string + + // Change the last character of s into a 'y' + std::string s("Exemplar "); + s[s.size() - 1] = 'y'; // equivalent to s.back() = 'y'; + std::cout << s << '\\n'; + } + +.SH Output: + + rmx + Exemplar + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 259 C++98 non-const overload could return const lvalue changed to return + data()[pos], which was ill-formed *(begin() + pos) + if pos == size(), the behavior of modifying + LWG 2475 C++11 the well-defined if + object referred by the returned reference modified to CharT() + was undefined + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::operatorbasic_string_view.3 b/man/std::string::operatorbasic_string_view.3 new file mode 100644 index 000000000..7860d59f8 --- /dev/null +++ b/man/std::string::operatorbasic_string_view.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::operatorbasic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operatorbasic_string_view \- std::basic_string::operatorbasic_string_view + +.SH Synopsis + operator std::basic_string_view() const \fI(since C++17)\fP + noexcept; (constexpr since C++20) + + Returns a std::basic_string_view, constructed as if by std::basic_string_view(data(), size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A string view representing the entire contents of the string. + +.SH Notes + + It is the programmer's responsibility to ensure that the resulting string view does + not outlive the string. + + std::string get_string(); + int f(std::string_view sv); + + int x = f(get_string()); // OK + std::string_view sv = get_string(); // Bad: holds a dangling pointer + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_wstring_size(std::wstring_view wcstr_v) + { + std::cout << wcstr_v.size() << " code points\\n"; + } + + int main() + { + std::string cppstr = "ラーメン"; // narrow string + std::wstring wcstr = L"ラーメン"; // wide string + + // Implicit conversion from string to string_view + // via std::string::operator string_view: + std::string_view cppstr_v = cppstr; + + std::cout << cppstr_v << '\\n' + << cppstr_v.size() << " code units\\n"; + + // Implicit conversion from wstring to wstring_view + // via std::wstring::operator wstring_view: + show_wstring_size(wcstr); + } + +.SH Output: + + ラーメン + 12 code units + 4 code points + +.SH See also + + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::string::pop_back.3 b/man/std::string::pop_back.3 deleted file mode 120000 index 92b01df6a..000000000 --- a/man/std::string::pop_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::pop_back.3 \ No newline at end of file diff --git a/man/std::string::pop_back.3 b/man/std::string::pop_back.3 new file mode 100644 index 000000000..1ef904042 --- /dev/null +++ b/man/std::string::pop_back.3 @@ -0,0 +1,75 @@ +.TH std::basic_string::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::pop_back \- std::basic_string::pop_back + +.SH Synopsis + void pop_back(); (constexpr since C++20) + + Removes the last character from the string. + + Equivalent to erase(end() - 1). The behavior is undefined if the string is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + In libstdc++, pop_back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string str("Short string!"); + std::cout << "before=" << std::quoted(str) << '\\n'; + assert(str.size() == 13); + + str.pop_back(); + std::cout << " after=" << std::quoted(str) << '\\n'; + assert(str.size() == 12); + + str.clear(); + // str.pop_back(); // undefined behavior + } + +.SH Output: + + before="Short string!" + after="Short string" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function pop_back() + +.SH See also + + push_back appends a character to the end + \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP diff --git a/man/std::string::push_back.3 b/man/std::string::push_back.3 deleted file mode 120000 index fde2976b5..000000000 --- a/man/std::string::push_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::push_back.3 \ No newline at end of file diff --git a/man/std::string::push_back.3 b/man/std::string::push_back.3 new file mode 100644 index 000000000..122b1e8fe --- /dev/null +++ b/man/std::string::push_back.3 @@ -0,0 +1,68 @@ +.TH std::basic_string::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::push_back \- std::basic_string::push_back + +.SH Synopsis + void push_back( CharT ch ); (constexpr since C++20) + + Appends the given character ch to the end of the string. + +.SH Parameters + + ch - the character to append + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Amortized constant. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str{"Short string"}; + std::cout << "1) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + + str.push_back('!'); + std::cout << "2) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + } + +.SH Output: + + 1) "Short string", size: 12 + 2) "Short string!", size: 13 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + \fB(1)\fP the description was missing in + LWG 7 C++98 the C++ standard \fB(1)\fP description added + \fB(2)\fP the parameter type was const (2) changed to CharT + CharT + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + pop_back removes the last character + (DR*) \fI(public member function)\fP diff --git a/man/std::string::rbegin,.3 b/man/std::string::rbegin,.3 new file mode 100644 index 000000000..eecaa5142 --- /dev/null +++ b/man/std::string::rbegin,.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rbegin, \- std::basic_string::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the first character of the reversed string. It + corresponds to the last character of the non-reversed string. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemplar!"); + *s.rbegin() = 'y'; + std::cout << s << '\\n'; // "Exemplary" + + std::string c; + std::copy(s.crbegin(), s.crend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "yralpmexE" + } + +.SH Output: + + Exemplary + yralpmexE + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::rbegin,std::basic_string::crbegin.3 b/man/std::string::rbegin,std::basic_string::crbegin.3 deleted file mode 120000 index e36abe435..000000000 --- a/man/std::string::rbegin,std::basic_string::crbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rbegin,std::basic_string::crbegin.3 \ No newline at end of file diff --git a/man/std::string::rend,.3 b/man/std::string::rend,.3 new file mode 100644 index 000000000..c28ff3818 --- /dev/null +++ b/man/std::string::rend,.3 @@ -0,0 +1,70 @@ +.TH std::basic_string::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rend, \- std::basic_string::rend, + +.SH Synopsis + + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the character following the last character of the + reversed string. It corresponds to the character preceding the first character of + the non-reversed string. This character acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string p("[A man, a plan, a canal: Panama]"); + std::string q; + + std::copy(p.crbegin(), p.crend(), std::back_inserter(q)); + std::cout << "q = " << q << '\\n'; + + std::copy(q.crbegin(), q.crend(), p.rbegin()); + std::cout << "p = " << p << '\\n'; + } + +.SH Output: + + q = ]amanaP :lanac a ,nalp a ,nam A[ + p = ]amanaP :lanac a ,nalp a ,nam A[ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::rend,std::basic_string::crend.3 b/man/std::string::rend,std::basic_string::crend.3 deleted file mode 120000 index 600152427..000000000 --- a/man/std::string::rend,std::basic_string::crend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rend,std::basic_string::crend.3 \ No newline at end of file diff --git a/man/std::string::replace.3 b/man/std::string::replace.3 deleted file mode 120000 index 3a94b3a6f..000000000 --- a/man/std::string::replace.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::replace.3 \ No newline at end of file diff --git a/man/std::string::replace.3 b/man/std::string::replace.3 new file mode 100644 index 000000000..7b1e79fc7 --- /dev/null +++ b/man/std::string::replace.3 @@ -0,0 +1,184 @@ +.TH std::basic_string::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace \- std::basic_string::replace + +.SH Synopsis + basic_string& replace( size_type pos, + size_type count, \fB(1)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(2)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( size_type pos, + size_type count, + + const basic_string& \fI(until C++14)\fP + str, + + size_type pos2, + size_type count2 ); + basic_string& replace( size_type pos, + size_type count, + \fI(since C++14)\fP + const basic_string& (constexpr since + str, C++20) + + size_type pos2, + size_type count2 = npos ); + basic_string& replace( size_type pos, + size_type count, \fB(4)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(5)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( size_type pos, (constexpr since + size_type count, \fB(6)\fP C++20) + const CharT* cstr ); + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(7)\fP C++20) + const CharT* cstr ); + basic_string& replace( size_type pos, + size_type count, \fB(8)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(3)\fP \fB(9)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + template< class InputIt > + + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(10)\fP C++20) + + InputIt first2, InputIt + last2 ); + basic_string& replace( const_iterator first, \fI(since C++11)\fP + const_iterator last, \fB(11)\fP (constexpr since + C++20) + std::initializer_list ilist ); + template< class StringViewLike > + + basic_string& replace( size_type pos, \fI(since C++17)\fP + size_type count, \fB(12)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( const_iterator first, \fI(since C++17)\fP + const_iterator last, \fB(13)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( size_type pos, + size_type count, \fI(since C++17)\fP + const StringViewLike& \fB(14)\fP (constexpr since + t, C++20) + + size_type pos2, + size_type count2 = npos ); + + Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count, + size())) or [first, last) with given characters. + + 1,2) Those characters are replaced with str. + 3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2, + str.size())) of str. + 4,5) Those characters are replaced with the characters in the range [cstr, cstr + + count2). + If [cstr, cstr + count2) is not a valid range, the behavior is undefined. + 6,7) Those characters are replaced with the characters in the range [cstr, cstr + + Traits::length(cstr)). + 8,9) Those characters are replaced with count2 copies of ch. + 10) Those characters are replaced with the characters in the range [first2, last2) + as if by replace(first, last, basic_string(first2, last2, get_allocator())). + 11) Those characters are replaced with the characters in ilist. + 12,13) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then those characters are replaced + with the characters from sv. + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 14) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then those characters are replaced with the characters from the + subview sv.substr(pos2, count2). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If [begin(), first) or [first, last) is not a valid range, the behavior is + undefined. + +.SH Parameters + + pos - start of the substring that is going to be replaced + count - length of the substring that is going to be replaced + first, last - range of characters that is going to be replaced + str - string to use for replacement + pos2 - start of the substring to replace with + count2 - number of characters to replace with + cstr - pointer to the character string to use for replacement + ch - character value to use for replacement + first2, last2 - range of characters to use for replacement + ilist - initializer list with the characters to use for replacement + t - object (convertible to std::basic_string_view) with the characters + to use for replacement +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this. + +.SH Exceptions + + 1) Throws std::out_of_range if pos > size(). + 3) Throws std::out_of_range if pos > size() or pos2 > str.size(). + 4,6,8) Throws std::out_of_range if pos > size(). + 12,14) Throws std::out_of_range if pos > size(). + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 1323 C++98 the types of first and last changed to const_iterator + were iterator + LWG 2946 C++17 overloads (12,13) caused avoided by making them templates + ambiguity in some cases + +.SH See also + + replace_with_range replaces specified portion of a string with a range of characters + (C++23) \fI(public member function)\fP + regex_replace replaces occurrences of a regular expression with formatted + \fI(C++11)\fP replacement text + \fI(function template)\fP + replace replaces all values satisfying specific criteria with another + replace_if value + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::string::replace_with_range.3 b/man/std::string::replace_with_range.3 new file mode 100644 index 000000000..a06106cbc --- /dev/null +++ b/man/std::string::replace_with_range.3 @@ -0,0 +1,91 @@ +.TH std::basic_string::replace_with_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace_with_range \- std::basic_string::replace_with_range + +.SH Synopsis + template< container-compatible-range R > + + constexpr std::basic_string& replace_with_range( const_iterator + first, (since C++23) + const_iterator last, + + R&& rg ); + + Replaces the characters in the range [first, last) with the characters from the + range rg. + + Equivalent to + + return replace(first, + last, + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + first, last - range of characters that is going to be replaced + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + auto s{"Today is today!"s}; + constexpr auto today{"today"sv}; + constexpr auto tomorrow{"tomorrow's yesterday"sv}; + std::forward_list rg; + std::ranges::reverse_copy(tomorrow, std::front_inserter(rg)); + + const auto pos{s.rfind(today)}; + assert(pos != s.npos); + const auto first{std::next(s.begin(), pos)}; + const auto last{std::next(first, today.length())}; + + #ifdef __cpp_lib_containers_ranges + s.replace_range(first, last, rg); + #else + s.replace(first, last, rg.cbegin(), rg.cend()); + #endif + + assert("Today is tomorrow's yesterday!" == s); + } + +.SH See also + + replace replaces specified portion of a string + \fI(public member function)\fP diff --git a/man/std::string::reserve.3 b/man/std::string::reserve.3 deleted file mode 120000 index 8af41bde6..000000000 --- a/man/std::string::reserve.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::reserve.3 \ No newline at end of file diff --git a/man/std::string::reserve.3 b/man/std::string::reserve.3 new file mode 100644 index 000000000..3f0d1423a --- /dev/null +++ b/man/std::string::reserve.3 @@ -0,0 +1,112 @@ +.TH std::basic_string::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::reserve \- std::basic_string::reserve + +.SH Synopsis + void reserve( size_type new_cap = 0 ); \fI(until C++20)\fP + constexpr void reserve( size_type new_cap ); \fI(since C++20)\fP + \fB(1)\fP \fI(since C++20)\fP + void reserve(); \fB(2)\fP (deprecated in C++20) + (removed in C++26) + + 1) Informs a std::basic_string object of a planned change in size, so that it can + manage the storage allocation appropriately. + * If new_cap is greater than the current capacity(), new storage is allocated, and + capacity() is made equal or greater than new_cap. + + * If new_cap is less than the current capacity(), this is a + non-binding shrink request. + * If new_cap is less than the current size(), this is a non-binding \fI(until C++20)\fP + shrink-to-fit request + equivalent to shrink_to_fit() + \fI(since C++11)\fP. + * If new_cap is less than or equal to the current capacity(), there \fI(since C++20)\fP + is no effect. + + If a capacity change takes place, all iterators and references, including the + past-the-end iterator, are invalidated. + 2) A non-binding shrink-to-fit request. After this call, capacity() has an + unspecified value greater than or equal to size(). + +.SH Parameters + + new_cap - new capacity of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::length_error if new_cap is greater than max_size(). + + May throw any exceptions thrown by std::allocator_traits::allocate(), + such as std::bad_alloc. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + At most linear in the size() of the string. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + std::cout << "1) Initially: " << s.capacity() << '\\n'; + + const std::string::size_type new_cap{101u}; + s.reserve(new_cap); + assert(s.capacity() >= new_cap); + std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\\n'; + + // observing the capacity growth factor + auto cap{s.capacity()}; + for (int check{}; check != 4; ++check) + { + while (cap == s.capacity()) + s += '$'; + cap = s.capacity(); + std::cout << (3) + check << ") Capacity: " << cap << '\\n'; + } + + // s.reserve(); // deprecated/removed in C++20/26, use: + s.shrink_to_fit(); + std::cout << "7) After shrink_to_fit: " << s.capacity() << '\\n'; + } + +.SH Possible output: + + 1) Initially: 15 + 2) After reserve(101): 101 + 3) Capacity: 202 + 4) Capacity: 404 + 5) Capacity: 808 + 6) Capacity: 1616 + 7) After shrink_to_fit: 809 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::string::resize.3 b/man/std::string::resize.3 deleted file mode 120000 index 15f0e17b9..000000000 --- a/man/std::string::resize.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::resize.3 \ No newline at end of file diff --git a/man/std::string::resize.3 b/man/std::string::resize.3 new file mode 100644 index 000000000..3b4c7a8b6 --- /dev/null +++ b/man/std::string::resize.3 @@ -0,0 +1,140 @@ +.TH std::basic_string::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize \- std::basic_string::resize + +.SH Synopsis + void resize( size_type count ); \fB(1)\fP (constexpr since C++20) + void resize( size_type count, CharT ch ); \fB(2)\fP (constexpr since C++20) + + Resizes the string to contain count characters. + + If the current size is less than count, additional characters are appended: + + 1) Initializes appended characters to CharT() ('\\0' if CharT is char). + 2) Initializes appended characters to ch. + + If the current size is greater than count, the string is reduced to its first count + elements. + +.SH Parameters + + count - new size of the string + ch - character to initialize the new characters with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > max_size(). Any exceptions thrown by corresponding + Allocator. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const unsigned desired_length{8}; + std::string long_string("Where is the end?"); + std::string short_string("H"); + + std::cout << "Basic functionality:\\n" + << "Shorten:\\n" + << "1. Before: " << std::quoted(long_string) << '\\n'; + long_string.resize(desired_length); + std::cout << "2. After: " << std::quoted(long_string) << '\\n'; + + std::cout << "Lengthen with a given value 'a':\\n" + << "3. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length, 'a'); + std::cout << "4. After: " << std::quoted(short_string) << '\\n'; + + std::cout << "Lengthen with char() == " << static_cast(char()) << '\\n' + << "5. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length + 3); + std::cout << "6. After: \\""; + for (char c : short_string) + std::cout << (c == char() ? '@' : c); + std::cout << "\\"\\n\\n"; + + std::cout << "Errors:\\n"; + std::string s; + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size() - 1, 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "1. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size(), 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "2. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is BAD, throw length_error + s.resize(s.max_size() + 1, 'x'); + } + catch (const std::length_error& ex) + { + std::cout << "3. Length error: " << ex.what() << '\\n'; + } + } + +.SH Possible output: + + Basic functionality: + Shorten: + 1. Before: "Where is the end?" + 2. After: "Where is" + Lengthen with a given value 'a': + 3. Before: "H" + 4. After: "Haaaaaaa" + Lengthen with char() == 0 + 5. Before: "Haaaaaaa" + 6. After: "Haaaaaaa@@@" + + Errors: + 1. Exception: std::bad_alloc + 2. Exception: std::bad_alloc + 3. Length error: basic_string::_M_replace_aux + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP diff --git a/man/std::string::resize_and_overwrite.3 b/man/std::string::resize_and_overwrite.3 new file mode 100644 index 000000000..192feef8a --- /dev/null +++ b/man/std::string::resize_and_overwrite.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::resize_and_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize_and_overwrite \- std::basic_string::resize_and_overwrite + +.SH Synopsis + template< class Operation > (since C++23) + constexpr void resize_and_overwrite( size_type count, Operation op ); + + Resizes the string to contain at most count characters, using the user-provided + operation op to modify the possibly indeterminate contents and set the length. This + avoids the cost of initializing a suitably-sized std::string when it is intended to + be used as a char array to be populated by, e.g., a C API call. + + This function performs following steps: + + 1. Obtains contiguous storage that contains count + 1 characters, and makes its + first k characters equal to the first k characters of *this, where k is the + smaller of count and the result of this->size() before the call to + resize_and_overwrite. Let p denote the pointer to the first character in the + storage. + * The equality is determined as if by checking this->compare(0, k, p, k) == + 0. + * The characters in [p + k, p + count] may have indeterminate values. + 2. Evaluates std::move(op)(p, count). Let r be the return value of std::move(op)(p, + count). + 3. Replaces the contents of *this with [p, p + r) (which sets the length of *this + to r). Invalidates all pointers and references to the range [p, p + count]. + + The program is ill-formed if r does not have an integer-like type. The behavior is + undefined if std::move(op)(p, count) throws an exception or modifies p or count, r + is not in the range [0, count], or any character in range [p, p + r) has an + indeterminate value. + + Implementations are recommended to avoid unnecessary copies and allocations by, + e.g., making p equal to the pointer to beginning of storage of characters allocated + for *this after the call, which can be identical to the existing storage of *this if + count is less than or equal to this->capacity(). + +.SH Parameters + + count - the maximal possible new size of the string + op - the function object used for setting the new contents of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > this->max_size(). Any exceptions thrown by + corresponding Allocator. + + If an exception is thrown from std::move(op)(p, count), the behavior is undefined. + Otherwise, if an exception is thrown, this function has no effect. + +.SH Notes + + resize_and_overwrite invalidates all iterators, pointers, and references into *this, + regardless whether reallocation occurs. Implementations may assume that the contents + of the string are not aliased after the call to resize_and_overwrite. + + Feature-test macro Value Std Feature +__cpp_lib_string_resize_and_overwrite 202110L (C++23) std::basic_string::resize_and_overwrite + +.SH Example + + Link to test the example: compiler explorer. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + static_assert(__cpp_lib_string_resize_and_overwrite); + + constexpr std::string_view fruits[]{"apple", "banana", "coconut", "date", "elderberry"}; + + int main() + { + // A simple case, append only fruits[0]. The string size will be increased. + std::string s{"Food: "}; + s.resize_and_overwrite(16, [sz = s.size()](char* buf, std::size_t buf_size) noexcept + { + const auto to_copy = std::min(buf_size - sz, fruits[0].size()); + std::memcpy(buf + sz, fruits[0].data(), to_copy); + return sz + to_copy; + }); + std::cout << "1. " << std::quoted(s) << '\\n'; + + // The size shrinking case. Note, that the user's lambda is always invoked. + s.resize_and_overwrite(10, [](char* buf, int n) noexcept + { + return std::find(buf, buf + n, ':') - buf; + }); + std::cout << "2. " << std::quoted(s) << '\\n'; + + std::cout << "3. Copy data until the buffer is full. Print data and sizes.\\n"; + std::string food{"Food:"}; + const auto resize_to{27}; + std::cout << "Initially, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", resize_to: " << resize_to + << ", food: " << std::quoted(food) << '\\n'; + + food.resize_and_overwrite( + resize_to, + [food_size = food.size()](char* p, std::size_t n) noexcept -> std::size_t + { + // p[0]..p[n] is the assignable range + // p[0]..p[min(n, food_size) - 1] is the readable range + // (contents initially equal to the original string) + + // Debug print: + std::cout << "In Operation(); n: " << n << '\\n'; + + // Copy fruits to the buffer p while there is enough space. + char* first = p + food_size; + + for (char* const end = p + n; const std::string_view fruit : fruits) + { + char* last = first + fruit.size() + 1; + if (last > end) + break; + *first++ = ' '; + std::ranges::copy(fruit, first); + first = last; + } + + const auto final_size{static_cast(first - p)}; + + // Debug print: + std::cout << "In Operation(); final_size: " << final_size << '\\n'; + + assert(final_size <= n); + return final_size; // Return value is the actual new length + // of the string, must be in range 0..n + }); + + std::cout << "Finally, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", food: " << std::quoted(food) << '\\n'; + } + +.SH Possible output: + + 1. "Food: apple" + 2. "Food" + 3. Copy data until the buffer is full. Print data and sizes. + Initially, food.size: 5, food.capacity: 15, resize_to: 27, food: "Food:" + In Operation(); n: 27 + In Operation(); final_size: 26 + Finally, food.size: 26, food.capacity: 30, food: "Food: apple banana coconut" + +.SH See also + + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::string::rfind.3 b/man/std::string::rfind.3 deleted file mode 120000 index 6ca6348d9..000000000 --- a/man/std::string::rfind.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rfind.3 \ No newline at end of file diff --git a/man/std::string::rfind.3 b/man/std::string::rfind.3 new file mode 100644 index 000000000..6baebe7ca --- /dev/null +++ b/man/std::string::rfind.3 @@ -0,0 +1,161 @@ +.TH std::basic_string::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rfind \- std::basic_string::rfind + +.SH Synopsis + size_type rfind( const basic_string& str, size_type pos \fB(1)\fP (noexcept since C++11) + = npos ) const; (constexpr since C++20) + size_type rfind( const CharT* s, size_type pos, \fB(2)\fP (constexpr since C++20) + size_type count ) const; + size_type rfind( const CharT* s, size_type pos = npos ) \fB(3)\fP (constexpr since C++20) + const; + size_type rfind( CharT ch, size_type pos = npos ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type rfind( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last substring equal to str. + 2) Finds the last substring equal to the range [s, s + count). This range can + include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last substring equal to the contents of sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string to search for + pos - position at which to begin searching + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. Note that this is an offset from the start of the string, not the end. + + If searching for an empty string (i.e., str.size(), count, or Traits::length(s) is + zero), the empty string is found immediately and rfind returns: + + * pos, if pos < size(); + * size() otherwise, including the case where pos == npos. + + Otherwise, if size() is zero, npos is always returned. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(std::string::size_type n, + std::string::size_type len, + std::string const &s) + { + if (n == std::string::npos) + std::cout << "not found\\n"; + else + std::cout << "found: " << std::quoted(s.substr(n, len)) << " at " << n << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; + + // search backwards from end of string + n = s.rfind("is"); + print(n, 2, s); + + // search backwards from position 4 + n = s.rfind("is", 4); + print(n, 2, s); + + // find a single character + n = s.rfind('s'); + print(n, 1, s); + + // find a single character + n = s.rfind('q'); + print(n, 1, s); + + // find the prefix (see also s.starts_with("This")) + n = s.rfind("This", 0); + print(n, 4, s); + } + +.SH Output: + + found: "is" at 5 + found: "is" at 2 + found: "s" at 10 + not found + found: "This" at 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::shrink_to_fit.3 b/man/std::string::shrink_to_fit.3 deleted file mode 120000 index af19637a3..000000000 --- a/man/std::string::shrink_to_fit.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::shrink_to_fit.3 \ No newline at end of file diff --git a/man/std::string::shrink_to_fit.3 b/man/std::string::shrink_to_fit.3 new file mode 100644 index 000000000..506b08ea9 --- /dev/null +++ b/man/std::string::shrink_to_fit.3 @@ -0,0 +1,95 @@ +.TH std::basic_string::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::shrink_to_fit \- std::basic_string::shrink_to_fit + +.SH Synopsis + void shrink_to_fit(); (constexpr since C++20) + + Requests the removal of unused capacity. + + It is a non-binding request to reduce capacity() to size(). It depends on the + implementation if the request is fulfilled. + + If (and only if) reallocation takes place, all pointers, references, and iterators + are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + (unspecified) \fI(until C++17)\fP + Linear in the size of the string. \fI(since C++17)\fP + +.SH Notes + + In libstdc++, shrink_to_fit() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::cout << "Size of std::string is " << sizeof s << " bytes\\n" + << "Default-constructed capacity is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + for (int i = 0; i < 42; i++) + s.append(" 42 "); + std::cout << "Capacity after 42 appends is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.clear(); + std::cout << "Capacity after clear() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.shrink_to_fit(); + std::cout << "Capacity after shrink_to_fit() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + } + +.SH Possible output: + + GCC output: + Size of std::string is 32 bytes + Default-constructed capacity is 15 and size 0 + Capacity after 42 appends is 240 and size 168 + Capacity after clear() is 240 and size 0 + Capacity after shrink_to_fit() is 15 and size 0 + + clang output (with -stdlib=libc++): + Size of std::string is 24 bytes + Default-constructed capacity is 22 and size is 0 + Capacity after 42 appends is 191 and size is 168 + Capacity after clear() is 191 and size is 0 + Capacity after shrink_to_fit() is 22 and size is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 755 C++98 std::string lacked explicit shrink-to-fit provided + operations + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::string::size,.3 b/man/std::string::size,.3 new file mode 100644 index 000000000..46f96cd93 --- /dev/null +++ b/man/std::string::size,.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::size, \- std::basic_string::size, + +.SH Synopsis + + size_type size() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + size_type length() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + + Returns the number of CharT elements in the string, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the string. + +.SH Complexity + + Unspecified \fI(until C++11)\fP + Constant \fI(since C++11)\fP + +.SH Notes + + For std::string, the elements are bytes (objects of type char), which are not the + same as characters if a multibyte encoding such as UTF-8 is used. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("Exemplar"); + assert(8 == s.size()); + assert(s.size() == s.length()); + assert(s.size() == static_cast( + std::distance(s.begin(), s.end()))); + + std::u32string a(U"ハロー・ワールド"); // 8 code points + assert(8 == a.size()); // 8 code units in UTF-32 + + std::u16string b(u"ハロー・ワールド"); // 8 code points + assert(8 == b.size()); // 8 code units in UTF-16 + + std::string c("ハロー・ワールド"); // 8 code points + assert(24 == c.size()); // 24 code units in UTF-8 + + #if __cplusplus >= 202002 + std::u8string d(u8"ハロー・ワールド"); // 8 code points + assert(24 == d.size()); // 24 code units in UTF-8 + #endif + } + +.SH See also + + empty checks whether the string is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::size,std::basic_string::length.3 b/man/std::string::size,std::basic_string::length.3 deleted file mode 120000 index dbf50666e..000000000 --- a/man/std::string::size,std::basic_string::length.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::size,std::basic_string::length.3 \ No newline at end of file diff --git a/man/std::string::starts_with.3 b/man/std::string::starts_with.3 new file mode 100644 index 000000000..54b219105 --- /dev/null +++ b/man/std::string::starts_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::starts_with \- std::basic_string::starts_with + +.SH Synopsis + constexpr bool + starts_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + starts_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + starts_with( const CharT* s ) const; + + Checks if the string begins with the given prefix. The prefix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).starts_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.starts_with("He"sv) // (1) + && !str.starts_with("he"sv) // (1) + && str.starts_with("He"s) // (1) implicit conversion string to string_view + && !str.starts_with("he"s) // (1) implicit conversion string to string_view + && str.starts_with('H') // (2) + && !str.starts_with('h') // (2) + && str.starts_with("He") // (3) + && !str.starts_with("he") // (3) + ); + } + +.SH See also + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::string::string.3 b/man/std::string::string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::string::string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::string::string.3 b/man/std::string::string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::string::string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::string::substr.3 b/man/std::string::substr.3 deleted file mode 120000 index 3a94fd2cd..000000000 --- a/man/std::string::substr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::substr.3 \ No newline at end of file diff --git a/man/std::string::substr.3 b/man/std::string::substr.3 new file mode 100644 index 000000000..f263d4824 --- /dev/null +++ b/man/std::string::substr.3 @@ -0,0 +1,113 @@ +.TH std::basic_string::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::substr \- std::basic_string::substr + +.SH Synopsis + basic_string substr( size_type pos = 0, size_type (until C++23) + count = npos ) const; (constexpr since C++20) + constexpr basic_string + substr( size_type pos = 0, size_type count = \fB(1)\fP (since C++23) + npos ) const&; + constexpr basic_string substr( size_type pos = 0, \fB(2)\fP (since C++23) + size_type count = npos ) &&; + + Returns a substring [pos, pos + count). If the requested substring extends past the + end of the string, i.e. the count is greater than size() - pos (e.g. if count == + npos), the returned substring is [pos, size()). + + 1) Equivalent to return basic_string(*this, pos, count);. + 2) Equivalent to return basic_string(std::move(*this), pos, count);. + +.SH Parameters + + pos - position of the first character to include + count - length of the substring + +.SH Return value + + String containing the substring [pos, pos + count) or [pos, size()). + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Notes + + The allocator of the returned string is default-constructed: the new allocator might + not be a copy of get_allocator(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "0123456789abcdefghij"; + + // count is npos, returns [pos, size()) + std::string sub1 = a.substr(10); + std::cout << sub1 << '\\n'; + + // both pos and pos + count are within bounds, returns [pos, pos + count) + std::string sub2 = a.substr(5, 3); + std::cout << sub2 << '\\n'; + + // pos is within bounds, pos + count is not, returns [pos, size()) + std::string sub4 = a.substr(a.size() - 3, 50); + // this is effectively equivalent to + // std::string sub4 = a.substr(17, 3); + // since a.size() == 20, pos == a.size() - 3 == 17, and a.size() - pos == 3 + + std::cout << sub4 << '\\n'; + + try + { + // pos is out of bounds, throws + std::string sub5 = a.substr(a.size() + 3, 50); + std::cout << sub5 << '\\n'; + } + catch (const std::out_of_range& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + abcdefghij + 567 + hij + basic_string::substr: __pos (which is 23) > this->size() (which is 20) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + copy copies characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + substr returns a substring + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::string::swap.3 b/man/std::string::swap.3 deleted file mode 120000 index bc1277047..000000000 --- a/man/std::string::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::swap.3 \ No newline at end of file diff --git a/man/std::string::swap.3 b/man/std::string::swap.3 new file mode 100644 index 000000000..07e64dbec --- /dev/null +++ b/man/std::string::swap.3 @@ -0,0 +1,96 @@ +.TH std::basic_string::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::swap \- std::basic_string::swap + +.SH Synopsis + void swap( basic_string& other ); \fI(until C++17)\fP + void swap( basic_string& other ) noexcept(/* see below */); \fI(since C++17)\fP + (constexpr since C++20) + + Exchanges the contents of the string with those of other. All iterators and + references may be invalidated. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + +.SH Parameters + + other - string to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + No exception is thrown. \fI(until C++11)\fP + Exceptions can only be thrown in the case where the behavior is + undefined (see above). + \fI(since C++11)\fP + If an exception is thrown for any reason, this function has no effect + (strong exception safety guarantee). + + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_swap::value (since + || C++17) + std::allocator_traits::is_always_equal::value) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "AAA"; + std::string b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 403 C++98 swap() might throw an exception no exception is thrown + LWG 535 C++98 swapping strings did not preserve the orders are also preserved + character orders + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swap swaps the contents + \fI(public member function of std::basic_string_view)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::string::~basic_string.3 b/man/std::string::~basic_string.3 new file mode 100644 index 000000000..631cdb44e --- /dev/null +++ b/man/std::string::~basic_string.3 @@ -0,0 +1,13 @@ +.TH std::basic_string::~basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::~basic_string \- std::basic_string::~basic_string + +.SH Synopsis + ~basic_string(); (constexpr since C++20) + + Destructs the basic_string. The destructors of the elements are called and the used + storage is deallocated. + +.SH Complexity + + Typically constant (formally linear). diff --git a/man/std::string_view.3 b/man/std::string_view.3 new file mode 100644 index 000000000..df2b6eb62 --- /dev/null +++ b/man/std::string_view.3 @@ -0,0 +1,277 @@ +.TH std::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view \- std::basic_string_view + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++17)\fP + class Traits = std::char_traits + + > class basic_string_view; + + The class template basic_string_view describes an object that can refer to a + constant contiguous sequence of CharT with the first element of the sequence at + position zero. + + For a basic_string_view str, pointers, iterators, and references to elements of str + are invalidated when an operation invalidates a pointer in the range + [str.data(), str.data() + str.size()). + + Every specialization of std::basic_string_view is a TriviallyCopyable (since C++23) + type. + + A typical implementation holds only two members: a pointer to constant CharT and a + size. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string_view \fI(C++17)\fP std::basic_string_view + std::wstring_view \fI(C++17)\fP std::basic_string_view + std::u8string_view (C++20) std::basic_string_view + std::u16string_view \fI(C++17)\fP std::basic_string_view + std::u32string_view \fI(C++17)\fP std::basic_string_view + +.SH Template parameters + + CharT - character type + CharTraits class specifying the operations on the character type. Like for + Traits - std::basic_string, Traits::char_type must name the same type as CharT or + the program is ill-formed. + + Nested types + + Nested type Definition + traits_type Traits + value_type CharT + pointer CharT* + const_pointer const CharT* + reference CharT& + const_reference const CharT& + implementation-defined constant LegacyRandomAccessIterator, + + const_iterator and LegacyContiguousIterator \fI(until C++20)\fP + ConstexprIterator, and contiguous_iterator \fI(since C++20)\fP + + whose value_type is CharT + iterator const_iterator + const_reverse_iterator std::reverse_iterator + reverse_iterator const_reverse_iterator + size_type std::size_t + difference_type std::ptrdiff_t + + Note: iterator and const_iterator are the same type because string views are views + into constant character sequences. + + All requirements on the iterator types of a Container applies to the iterator and + const_iterator types of basic_string_view as well. + +.SH Member functions + + Constructors and assignment + constructor constructs a basic_string_view + \fI(public member function)\fP + operator= assigns a view + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Element access + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function)\fP +.SH Capacity + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP +.SH Modifiers + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Operations + copy copies characters + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string view contains the given substring or + (C++23) character + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) +.SH Input/output + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_view_literals + operator""sv creates a string view of a character array literal + \fI(C++17)\fP \fI(function)\fP + +.SH Helper classes + + std::hash + std::hash + std::hash + std::hash + std::hash hash support for string views + \fI(C++17)\fP \fI(class template specialization)\fP + \fI(C++17)\fP + (C++20) + \fI(C++17)\fP + \fI(C++17)\fP + + Helper templates + + template< class CharT, class Traits > + + inline constexpr bool (since + C++20) + ranges::enable_borrowed_range> = + true; + + This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy + borrowed_range. + + template< class CharT, class Traits > + + inline constexpr bool \fI(since C++20)\fP + + ranges::enable_view> = + true; + + This specialization of ranges::enable_view makes basic_string_view satisfy view. + + Deduction guides \fI(since C++20)\fP + +.SH Notes + + It is the programmer's responsibility to ensure that std::string_view does not + outlive the pointed-to character array: + + std::string_view good{"a string literal"}; + // "Good" case: `good` points to a static array. + // String literals reside in persistent data storage. + + std::string_view bad{"a temporary string"s}; + // "Bad" case: `bad` holds a dangling pointer since the std::string temporary, + // created by std::operator""s, will be destroyed at the end of the statement. + + Specializations of std::basic_string_view are already trivially copyable types in + all existing implementations, even before the formal requirement introduced in + C++23. + + Feature-test macro Value Std Feature + __cpp_lib_string_view 201606L \fI(C++17)\fP std::string_view + 201803L (C++20) ConstexprIterator + __cpp_lib_string_contains 202011L (C++23) contains + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view unicode[]{"▀▄─", "▄▀─", "▀─▄", "▄─▀"}; + + for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4)) + { + for (int x{}; x != 16; ++x) + std::cout << unicode[p]; + std::cout << '\\n'; + } + } + +.SH Output: + + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ + ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀ + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + only pointers, iterators, and all pointers, iterators, and + references references + LWG 3203 C++17 returned from the member functions to elements of + of basic_string_view + basic_string_view might be may be invalidated + invalidated + +.SH See also + + basic_string stores and manipulates sequences of characters + \fI(class template)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + initializer_list creates a temporary array in list-initialization and then + \fI(C++11)\fP references it + \fI(class template)\fP diff --git a/man/std::string_view::at.3 b/man/std::string_view::at.3 new file mode 100644 index 000000000..65f8fa91d --- /dev/null +++ b/man/std::string_view::at.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::at \- std::basic_string_view::at + +.SH Synopsis + constexpr const_reference at( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. Bounds + checking is performed, exception of type std::out_of_range will be thrown on invalid + access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string_view str_view("abcdef"); + + try + { + for (std::size_t i = 0; true; ++i) + std::cout << i << ": " << str_view.at(i) << '\\n'; + } + catch (const std::out_of_range& e) + { + std::cout << "Whooops. Index is out of range.\\n"; + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + 0: a + 1: b + 2: c + 3: d + 4: e + 5: f + 6: Whooops. Index is out of range. + basic_string_view::at: __pos (which is 6) >= this->size() (which is 6) + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + accesses the specified character with bounds checking + at \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::back.3 b/man/std::string_view::back.3 new file mode 100644 index 000000000..7fd79d7b3 --- /dev/null +++ b/man/std::string_view::back.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::back \- std::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; \fI(since C++17)\fP + + Returns reference to the last character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_suffix(1)) + std::cout << str.back() << ' ' << str << '\\n'; + } + +.SH Output: + + F ABCDEF + E ABCDE + D ABCD + C ABC + B AB + A A + +.SH See also + + front accesses the first character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::string_view::basic_string_view.3 b/man/std::string_view::basic_string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::string_view::basic_string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::begin,std::basic_string_view::cbegin.3 b/man/std::string_view::begin,std::basic_string_view::cbegin.3 new file mode 100644 index 000000000..83667f3e5 --- /dev/null +++ b/man/std::string_view::begin,std::basic_string_view::cbegin.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::begin,std::basic_string_view::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::begin,std::basic_string_view::cbegin \- std::basic_string_view::begin,std::basic_string_view::cbegin + +.SH Synopsis + constexpr const_iterator begin() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cbegin() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + + constexpr auto begin = str_view.begin(); + constexpr auto cbegin = str_view.cbegin(); + static_assert( + *begin == 'a' and + *cbegin == 'a' and + *begin == *cbegin and + begin == cbegin and + std::same_as); + } + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::string_view::compare.3 b/man/std::string_view::compare.3 new file mode 100644 index 000000000..8087ec4ef --- /dev/null +++ b/man/std::string_view::compare.3 @@ -0,0 +1,95 @@ +.TH std::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::compare \- std::basic_string_view::compare + +.SH Synopsis + constexpr int compare( basic_string_view v ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(2)\fP \fI(since C++17)\fP + basic_string_view v ) const; + constexpr int compare( size_type pos1, size_type count1, + basic_string_view v, \fB(3)\fP \fI(since C++17)\fP + size_type pos2, size_type count2 ) const; + constexpr int compare( const CharT* s ) const; \fB(4)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(5)\fP \fI(since C++17)\fP + const CharT* s ) const; + constexpr int compare( size_type pos1, size_type count1, \fB(6)\fP \fI(since C++17)\fP + const CharT* s, size_type count2 ) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less < 0 + than v + size() < this is less < 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater > 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater > 0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + Negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH Example + + +// Run this code + + #include + + int main() + { + using std::operator""sv; + static_assert("abc"sv.compare("abcd"sv) < 0); + static_assert("abcd"sv.compare("abc"sv) > 0); + static_assert("abc"sv.compare("abc"sv) == 0); + static_assert(""sv.compare(""sv) == 0); + } + +.SH See also + + compares two strings + compare \fI\fI(public member\fP function of\fP + std::basic_string) + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) diff --git a/man/std::string_view::contains.3 b/man/std::string_view::contains.3 new file mode 100644 index 000000000..8c655ade3 --- /dev/null +++ b/man/std::string_view::contains.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::contains \- std::basic_string_view::contains + +.SH Synopsis + constexpr bool contains( basic_string_view sv ) const noexcept; \fB(1)\fP (since C++23) + constexpr bool contains( CharT c ) const noexcept; \fB(2)\fP (since C++23) + constexpr bool contains( const CharT* s ) const; \fB(3)\fP (since C++23) + + Checks if the string view contains the given substring, where + + 1) the substring is a string view. + 2) the substring is a single character. + 3) the substring is a null-terminated character string. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view + c - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + static_assert + ( + // bool contains(basic_string_view x) const noexcept; + "https://cppreference.com"sv.contains("cpp"sv) == true and + "https://cppreference.com"sv.contains("php"sv) == false and + + // bool contains(CharT x) const noexcept; + "C++23"sv.contains('+') == true and + "C++23"sv.contains('-') == false and + + // bool contains(const CharT* x) const; + std::string_view("basic_string_view").contains("string") == true and + std::string_view("basic_string_view").contains("String") == false + ); + + int main() {} + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::copy.3 b/man/std::string_view::copy.3 new file mode 100644 index 000000000..50e77b7be --- /dev/null +++ b/man/std::string_view::copy.3 @@ -0,0 +1,88 @@ +.TH std::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::copy \- std::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos \fI(since C++17)\fP + = 0 ) const; (constexpr since C++20) + + Copies the substring [pos, pos + rcount) to the character array pointed to by dest, + where rcount is the smaller of count and size() - pos. + + Equivalent to Traits::copy(dest, data() + pos, rcount). + +.SH Parameters + + dest - pointer to the destination character string + count - requested substring length + pos - position of the first character + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::basic_string_view source{"ABCDEF"}; + std::array dest; + std::size_t count{}, pos{}; + + dest.fill('\\0'); + source.copy(dest.data(), count = 4); // pos = 0 + std::cout << dest.data() << '\\n'; // ABCD + + dest.fill('\\0'); + source.copy(dest.data(), count = 4, pos = 1); + std::cout << dest.data() << '\\n'; // BCDE + + dest.fill('\\0'); + source.copy(dest.data(), count = 42, pos = 2); // ok, count -> 4 + std::cout << dest.data() << '\\n'; // CDEF + + try + { + source.copy(dest.data(), count = 1, pos = 666); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Output: + + ABCD + BCDE + CDEF + basic_string_view::copy: __pos (which is 666) > __size (which is 6) + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::string_view::data.3 b/man/std::string_view::data.3 new file mode 100644 index 000000000..29290d3ff --- /dev/null +++ b/man/std::string_view::data.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::data \- std::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; \fI(since C++17)\fP + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::data() and string literals, std::basic_string_view::data() + returns a pointer to a buffer that is not necessarily null-terminated, for example a + substring view (e.g. from remove_suffix). Therefore, it is typically a mistake to + pass data() to a routine that takes just a const CharT* and expects a + null-terminated string. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::wstring_view wcstr_v = L"xyzzy"; + std::cout << std::wcslen(wcstr_v.data()) << '\\n'; + // OK: the underlying character array is null-terminated + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, sizeof array); + // std::cout << std::strlen(array_v.data()) << '\\n'; + // error: the underlying character array is not null-terminated + + std::string str(array_v.data(), array_v.size()); // OK + std::cout << std::strlen(str.data()) << '\\n'; + // OK: the underlying character array of a std::string is always null-terminated + } + +.SH Output: + + 5 + 3 + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function of std::basic_string)\fP diff --git a/man/std::string_view::empty.3 b/man/std::string_view::empty.3 new file mode 100644 index 000000000..185b498eb --- /dev/null +++ b/man/std::string_view::empty.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::empty \- std::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + checks whether the string is empty + empty \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::end,std::basic_string_view::cend.3 b/man/std::string_view::end,std::basic_string_view::cend.3 new file mode 100644 index 000000000..465ae8a3e --- /dev/null +++ b/man/std::string_view::end,std::basic_string_view::cend.3 @@ -0,0 +1,54 @@ +.TH std::basic_string_view::end,std::basic_string_view::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::end,std::basic_string_view::cend \- std::basic_string_view::end,std::basic_string_view::cend + +.SH Synopsis + constexpr const_iterator end() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cend() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + constexpr auto end = str_view.end(); + constexpr auto cend = str_view.cend(); + + static_assert + ( + *std::prev(end) == 'd' && 'd' == *std::prev(cend) and end == cend + ); + } + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::string_view::ends_with.3 b/man/std::string_view::ends_with.3 new file mode 100644 index 000000000..ad6eecb60 --- /dev/null +++ b/man/std::string_view::ends_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::ends_with \- std::basic_string_view::ends_with + +.SH Synopsis + constexpr bool ends_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool ends_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool ends_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view ends with the given suffix, where + + 1) the suffix is a string view. Effectively returns size() >= sv.size() && + compare(size() - sv.size(), npos, sv) == 0. + 2) the suffix is a single character. Effectively returns !empty() && + Traits::eq(back(), ch). + 3) the suffix is a null-terminated character string. Effectively returns + ends_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) ends_with( basic_string_view sv ) + && std::string_view("https://cppreference.com").ends_with(".com"sv) == true + && std::string_view("https://cppreference.com").ends_with(".org"sv) == false + + // (2) ends_with( CharT c ) + && std::string_view("C++20").ends_with('0') == true + && std::string_view("C++20").ends_with('3') == false + + // (3) ends_with( const CharT* s ) + && std::string_view("string_view").ends_with("view") == true + && std::string_view("string_view").ends_with("View") == false + ); + } + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::string_view::find.3 b/man/std::string_view::find.3 new file mode 100644 index 000000000..8882c44bb --- /dev/null +++ b/man/std::string_view::find.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find \- std::basic_string_view::find + +.SH Synopsis + constexpr size_type find( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type find( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type find( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type find( const CharT* s, size_type pos = 0 ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + + constexpr auto str{" long long int;"sv}; + + static_assert( + 1 == str.find("long"sv) && "<- find(v , pos = 0)" && + 6 == str.find("long"sv, 2) && "<- find(v , pos = 2)" && + 0 == str.find(' ') && "<- find(ch, pos = 0)" && + 2 == str.find('o', 1) && "<- find(ch, pos = 1)" && + 2 == str.find("on") && "<- find(s , pos = 0)" && + 6 == str.find("long double", 5, 4) && "<- find(s , pos = 5, count = 4)" + ); + + static_assert(str.npos == str.find("float")); + } + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + finds the first occurrence of the given substring + find \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::string_view::find_first_not_of.3 b/man/std::string_view::find_first_not_of.3 new file mode 100644 index 000000000..6ad069029 --- /dev/null +++ b/man/std::string_view::find_first_not_of.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_not_of \- std::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type + find_first_not_of( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_first_not_of( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_first_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_not_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or std::string_view::npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + int main() + { + static_assert(2 == "BCDEF"sv.find_first_not_of("ABC")); + // ^ + static_assert(4 == "BCDEF"sv.find_first_not_of("ABC", 4)); + // ^ + static_assert(1 == "BCDEF"sv.find_first_not_of('B')); + // ^ + static_assert(3 == "BCDEF"sv.find_first_not_of('D', 2)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::string_view::find_first_of.3 b/man/std::string_view::find_first_of.3 new file mode 100644 index 000000000..c6b35518c --- /dev/null +++ b/man/std::string_view::find_first_of.3 @@ -0,0 +1,100 @@ +.TH std::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_of \- std::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type + find_first_of( basic_string_view v, size_type pos = 0 ) const \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_first_of( CharT ch, size_type pos = 0 ) const noexcept; + constexpr size_type + find_first_of( const CharT* s, size_type pos, size_type count \fB(3)\fP \fI(since C++17)\fP + ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurrence of any of the characters of v in this view, starting + at position pos. + 2) Equivalent to find_first_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + constexpr bool is_white_space(const char c) + { + return " \\t\\n\\f\\r\\v"sv.find_first_of(c) != N; + }; + + static_assert( + 1 == "alignas"sv.find_first_of("klmn"sv) && + // └─────────────────────────┘ + N == "alignof"sv.find_first_of("wxyz"sv) && + // + 3 == "concept"sv.find_first_of("bcde"sv, /* pos= */ 1) && + // └───────────────────────┘ + N == "consteval"sv.find_first_of("oxyz"sv, /* pos= */ 2) && + // + 6 == "constexpr"sv.find_first_of('x') && + // └─────────────────────┘ + N == "constinit"sv.find_first_of('x') && + // + 6 == "const_cast"sv.find_first_of('c', /* pos= */ 4) && + // └──────────────────────┘ + N == "continue"sv.find_first_of('c', /* pos= */ 42) && + // + 5 == "co_await"sv.find_first_of("cba", /* pos= */ 4) && + // └───────────────────────┘ + 7 == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 2) && + // └────────────────────┘ + N == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 1) && + // + is_white_space(' ') && is_white_space('\\r') && !is_white_space('\\a') + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::string_view::find_last_not_of.3 b/man/std::string_view::find_last_not_of.3 new file mode 100644 index 000000000..1f593444d --- /dev/null +++ b/man/std::string_view::find_last_not_of.3 @@ -0,0 +1,79 @@ +.TH std::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_not_of \- std::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type + find_last_not_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_last_not_of( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last character not equal to any of the characters in the given character + sequence. The search considers only the interval [0, pos]. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using std::operator""sv; + + int main() + { + static_assert(1 == "BCDEF"sv.find_last_not_of("DEF")); + // ^ + static_assert(2 == "BCDEFG"sv.find_last_not_of("EFG", 3)); + // ^ + static_assert(2 == "ABBA"sv.find_last_not_of('A')); + // ^ + static_assert(1 == "ABBA"sv.find_last_not_of('A', 1)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::string_view::find_last_of.3 b/man/std::string_view::find_last_of.3 new file mode 100644 index 000000000..0203b94f0 --- /dev/null +++ b/man/std::string_view::find_last_of.3 @@ -0,0 +1,92 @@ +.TH std::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_of \- std::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type + find_last_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_last_of( CharT ch, size_type pos = npos ) const noexcept; + constexpr size_type + find_last_of( const CharT* s, size_type pos, size_type count ) \fB(3)\fP \fI(since C++17)\fP + const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_last_of( const CharT* s, size_type pos = npos ) const; + + Finds the last character equal to one of characters in the given character sequence. + Exact search algorithm is not specified. The search considers only the interval + [0, pos]. If the character is not present in the interval, npos will be returned. + + 1) Finds the last occurence of any of the characters of v in this view, ending at + position pos. + 2) Equivalent to find_last_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which the search is to finish + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert( + 5 == "delete"sv.find_last_of("cdef"sv) && + // └────────────────────┘ + N == "double"sv.find_last_of("fghi"sv) && + // + 0 == "else"sv.find_last_of("bcde"sv, 2 /* pos [0..2]: "els" */) && + // └────────────────────────┘ + N == "explicit"sv.find_last_of("abcd"sv, 4 /* pos [0..4]: "expli" */) && + // + 3 == "extern"sv.find_last_of('e') && + // └────────────────────┘ + N == "false"sv.find_last_of('x') && + // + 0 == "inline"sv.find_last_of('i', 2 /* pos [0..2]: "inl" */) && + // └───────────────────────┘ + N == "mutable"sv.find_last_of('a', 2 /* pos [0..2]: "mut" */) && + // + 3 == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 3 /* "cde" */) && + // └─────────────────────────┘ + N == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 2 /* "cd" */) + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::string_view::front.3 b/man/std::string_view::front.3 new file mode 100644 index 000000000..475c3cb67 --- /dev/null +++ b/man/std::string_view::front.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::front \- std::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; \fI(since C++17)\fP + + Returns reference to the first character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_prefix(1)) + std::cout << str.front() << ' ' << str << '\\n'; + } + +.SH Output: + + A ABCDEF + B BCDEF + C CDEF + D DEF + E EF + F F + +.SH See also + + back accesses the last character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::string_view::max_size.3 b/man/std::string_view::max_size.3 new file mode 100644 index 000000000..c3f42d911 --- /dev/null +++ b/man/std::string_view::max_size.3 @@ -0,0 +1,66 @@ +.TH std::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::max_size \- std::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; \fI(since C++17)\fP + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::numeric_limits::max() + << " <- numeric_limits::max()\\n" + << std::string_view{}.max_size() + << " <- string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::wstring_view{}.max_size() + << " <- wstring_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n"; + } + +.SH Possible output: + + 9223372036854775807 <- numeric_limits::max() + 4611686018427387899 <- string_view::max_size() + 4611686018427387899 <- basic_string_view::max_size() + 2305843009213693949 <- basic_string_view::max_size() + 1152921504606846974 <- wstring_view::max_size() + 1152921504606846974 <- basic_string_view::max_size() + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + returns the maximum number of characters + max_size \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::npos.3 b/man/std::string_view::npos.3 new file mode 100644 index 000000000..c3ba3b575 --- /dev/null +++ b/man/std::string_view::npos.3 @@ -0,0 +1,39 @@ +.TH std::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::npos \- std::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); \fI(since C++17)\fP + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Example + + +// Run this code + + #include + + constexpr bool + contains(std::string_view const what, std::string_view const where) noexcept + { + return std::string_view::npos != where.find(what); + } + + int main() + { + using namespace std::literals; + + static_assert(contains("water", "in a bottle of water")); + static_assert(!contains("wine", "in a bottle of champagne")); + static_assert(""sv.npos == "haystack"sv.find("needle")); + } + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI\fI(public static member\fP constant of\fP + std::basic_string) diff --git a/man/std::string_view::operator=.3 b/man/std::string_view::operator=.3 new file mode 100644 index 000000000..dba80aad4 --- /dev/null +++ b/man/std::string_view::operator=.3 @@ -0,0 +1,48 @@ +.TH std::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator= \- std::basic_string_view::operator= + +.SH Synopsis + constexpr basic_string_view& operator=( const basic_string_view& view \fI(since C++17)\fP + ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + assigns values to the string + operator= \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::operator[].3 b/man/std::string_view::operator[].3 new file mode 100644 index 000000000..c1d7e55fb --- /dev/null +++ b/man/std::string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator[] \- std::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[]( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Does not throw. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], std::basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string str = "Exemplar"; + std::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + accesses the specified character + operator[] \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::rbegin,.3 b/man/std::string_view::rbegin,.3 new file mode 100644 index 000000000..8f17b98bf --- /dev/null +++ b/man/std::string_view::rbegin,.3 @@ -0,0 +1,60 @@ +.TH std::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rbegin, \- std::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crbegin() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), std::next(str_view.rbegin(), 3), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), std::next(str_view.crbegin(), 3), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fed + fed + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::string_view::remove_prefix.3 b/man/std::string_view::remove_prefix.3 new file mode 100644 index 000000000..31ef25b47 --- /dev/null +++ b/man/std::string_view::remove_prefix.3 @@ -0,0 +1,74 @@ +.TH std::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_prefix \- std::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix( size_type n ); \fI(since C++17)\fP + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::literals; + + [[nodiscard("a pure function")]] + constexpr std::size_t count_substrings(std::string_view hive, std::string_view const bee) + { + if (hive.empty() || bee.empty()) + return 0U; + + std::size_t buzz{}; + while (bee.size() <= hive.size()) + { + const auto pos = hive.find(bee); + if (pos == hive.npos) + break; + ++buzz; + hive.remove_prefix(pos + bee.size()); + } + return buzz; + } + + int main() + { + std::string str = " trim me"; + std::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + + constexpr auto hive{"bee buzz bee buzz bee"}; + std::cout << "There are " << count_substrings(hive, "bee") << " bees in this hive.\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + There are 3 bees in this hive. + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP diff --git a/man/std::string_view::remove_suffix.3 b/man/std::string_view::remove_suffix.3 new file mode 100644 index 000000000..01bee81f3 --- /dev/null +++ b/man/std::string_view::remove_suffix.3 @@ -0,0 +1,51 @@ +.TH std::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_suffix \- std::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); \fI(since C++17)\fP + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP diff --git a/man/std::string_view::rend,std::basic_string_view::crend.3 b/man/std::string_view::rend,std::basic_string_view::crend.3 new file mode 100644 index 000000000..5f201fac0 --- /dev/null +++ b/man/std::string_view::rend,std::basic_string_view::crend.3 @@ -0,0 +1,61 @@ +.TH std::basic_string_view::rend,std::basic_string_view::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rend,std::basic_string_view::crend \- std::basic_string_view::rend,std::basic_string_view::crend + +.SH Synopsis + constexpr const_reverse_iterator rend() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crend() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), str_view.rend(), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), str_view.crend(), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fedcba + fedcba + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::string_view::rfind.3 b/man/std::string_view::rfind.3 new file mode 100644 index 000000000..684090010 --- /dev/null +++ b/man/std::string_view::rfind.3 @@ -0,0 +1,81 @@ +.TH std::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rfind \- std::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind( basic_string_view v, size_type pos = \fB(1)\fP \fI(since C++17)\fP + npos ) const noexcept; + constexpr size_type rfind( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type rfind( const CharT* s, size_type pos, \fB(3)\fP \fI(since C++17)\fP + size_type count ) const; + constexpr size_type rfind( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last occurrence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert(true + && (6 == "AB AB AB"sv.rfind("AB")) + && (6 == "AB AB AB"sv.rfind("ABCD", N, 2)) + && (3 == "AB AB AB"sv.rfind("AB", 5)) + && (0 == "AB CD EF"sv.rfind("AB", 0)) + && (2 == "B AB AB "sv.rfind("AB", 2)) + && (N == "B AB AB "sv.rfind("AB", 1)) + && (5 == "B AB AB "sv.rfind('A')) + && (4 == "AB AB AB"sv.rfind('B', 4)) + && (N == "AB AB AB"sv.rfind('C')) + ); + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::string_view::size,std::basic_string_view::length.3 b/man/std::string_view::size,std::basic_string_view::length.3 new file mode 100644 index 000000000..8f96ca90c --- /dev/null +++ b/man/std::string_view::size,std::basic_string_view::length.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::size,std::basic_string_view::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::size,std::basic_string_view::length \- std::basic_string_view::size,std::basic_string_view::length + +.SH Synopsis + constexpr size_type size() const noexcept; \fI(since C++17)\fP + constexpr size_type length() const noexcept; \fI(since C++17)\fP + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::starts_with.3 b/man/std::string_view::starts_with.3 new file mode 100644 index 000000000..9c8fd78c7 --- /dev/null +++ b/man/std::string_view::starts_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::starts_with \- std::basic_string_view::starts_with + +.SH Synopsis + constexpr bool starts_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool starts_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool starts_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view begins with the given prefix, where + + 1) the prefix is a string view. Effectively returns basic_string_view(data(), + std::min(size(), sv.size())) == sv. + 2) the prefix is a single character. Effectively returns !empty() && + Traits::eq(front(), ch). + 3) the prefix is a null-terminated character string. Effectively returns + starts_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) starts_with( basic_string_view ) + && "https://cppreference.com"sv.starts_with("http"sv) == true + && "https://cppreference.com"sv.starts_with("ftp"sv) == false + + // (2) starts_with( CharT ) + && "C++20"sv.starts_with('C') == true + && "C++20"sv.starts_with('J') == false + + // (3) starts_with( const CharT* ) + && std::string_view("string_view").starts_with("string") == true + && std::string_view("string_view").starts_with("String") == false + ); + } + +.SH See also + + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::string_view::string_view.3 b/man/std::string_view::string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::string_view::string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::string_view::substr.3 b/man/std::string_view::substr.3 new file mode 100644 index 000000000..d7edf51b7 --- /dev/null +++ b/man/std::string_view::substr.3 @@ -0,0 +1,76 @@ +.TH std::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::substr \- std::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view substr( size_type pos = 0, \fI(since C++17)\fP + size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rlen), where rlen is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rlen). + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + typedef std::size_t count_t, pos_t; + + constexpr std::string_view data{"ABCDEF"}; + + std::cout << data.substr() << '\\n'; // ABCDEF, i.e. data[0, 5] that is [0, 6) + std::cout << data.substr(pos_t(1)) << '\\n'; // BCDEF, i.e. [1, 6) + std::cout << data.substr(pos_t(2), count_t(3)) << '\\n'; // CDE, i.e. [2, 2 + 3) + std::cout << data.substr(pos_t(4), count_t(42)) << '\\n'; // EF, i.e. [4, 6) + + try + { + [[maybe_unused]] + auto sub = data.substr(pos_t(666), count_t(1)); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + ABCDEF + BCDEF + CDE + EF + basic_string_view::substr: __pos (which is 666) > __size (which is 6) + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function of std::basic_string)\fP diff --git a/man/std::string_view::swap.3 b/man/std::string_view::swap.3 new file mode 100644 index 000000000..c6b397cfe --- /dev/null +++ b/man/std::string_view::swap.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::swap \- std::basic_string_view::swap + +.SH Synopsis + constexpr void swap( basic_string_view& v ) noexcept; \fI(since C++17)\fP + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view a = "AAA"; + std::string_view b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swaps the contents + swap \fI(public member function of std::basic_string)\fP + diff --git a/man/std::stringbuf.3 b/man/std::stringbuf.3 deleted file mode 120000 index 0d28e7b96..000000000 --- a/man/std::stringbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf.3 \ No newline at end of file diff --git a/man/std::stringbuf.3 b/man/std::stringbuf.3 new file mode 100644 index 000000000..2d38ec8f0 --- /dev/null +++ b/man/std::stringbuf.3 @@ -0,0 +1,248 @@ +.TH std::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf \- std::basic_stringbuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + > class basic_stringbuf + + : public std::basic_streambuf + + std::basic_stringbuf is a std::basic_streambuf whose associated character sequence + is a memory-resident sequence of arbitrary characters, which can be initialized from + or made available as an instance of std::basic_string. + + Typical implementations of std::basic_stringbuf hold an object of type + std::basic_string or equivalent resizable sequence container directly as a data + member and use it as both the controlled character sequence (the array where the six + pointers of std::basic_streambuf are pointing to) and as the associated character + sequence (the source of characters for all input operations and the target for the + output). + + In addition, a typical implementation holds a data member of type + std::ios_base::openmode to indicate the I/O mode of the associated stream + (input-only, output-only, input/output, at-end, etc). + + If over-allocation strategy is used by overflow(), an additional + high-watermark pointer may be stored to track the last initialized \fI(since C++11)\fP + character. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::stringbuf std::basic_stringbuf + std::wstringbuf std::basic_stringbuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + the std::basic_string used as the underlying + buf buffer + (exposition-only member object*) + mode the std::ios_base::openmode of the associated stream + (exposition-only member object*) + init_buf_ptrs initializes the input and output sequences + (exposition-only member function*) + +.SH Public member functions + + constructor constructs a basic_stringbuf object + \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function)\fP + destructor destructs a basic_stringbuf object and the string it + \fB[virtual]\fP (implicitly declared) holds + \fI(virtual public member function)\fP + replaces or obtains a copy of the associated + str character string + \fI(public member function)\fP + get_allocator obtains a copy of the allocator associated with the + (C++20) internal sequence container + \fI(public member function)\fP + view obtains a view over the underlying character + (C++20) sequence + \fI(public member function)\fP + +.SH Protected member functions + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + pbackfail puts a character back into the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow appends a character to the output sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function)\fP + +.SH Non-member functions + + std::swap(std::basic_stringbuf) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) +.SH Locales + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + +.SH Positioning + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + +.SH Putback + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + + +.SH Protected member functions + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Get area + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + eback returns a pointer to the beginning, current character and the end of + gptr the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + pbase returns a pointer to the beginning, current character and the end of + pptr the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) diff --git a/man/std::stringbuf::basic_stringbuf.3 b/man/std::stringbuf::basic_stringbuf.3 deleted file mode 120000 index 305998a5b..000000000 --- a/man/std::stringbuf::basic_stringbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::basic_stringbuf.3 \ No newline at end of file diff --git a/man/std::stringbuf::basic_stringbuf.3 b/man/std::stringbuf::basic_stringbuf.3 new file mode 100644 index 000000000..496a0651e --- /dev/null +++ b/man/std::stringbuf::basic_stringbuf.3 @@ -0,0 +1,240 @@ +.TH std::basic_stringbuf::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::basic_stringbuf \- std::basic_stringbuf::basic_stringbuf + +.SH Synopsis + explicit basic_stringbuf( std::ios_base::openmode which = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringbuf( std::ios_base::openmode which ); \fI(since C++11)\fP + basic_stringbuf() + : basic_stringbuf( std::ios_base::in | std::ios_base::out \fB(2)\fP \fI(since C++11)\fP + ) {} + explicit + + basic_stringbuf( const std::basic_string& s, \fB(3)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); + explicit basic_stringbuf( std::basic_string&& s, + + std::ios_base::openmode which = \fB(4)\fP \fI(since C++20)\fP + + std::ios_base::in | + std::ios_base::out ); + basic_stringbuf( std::ios_base::openmode which, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + explicit basic_stringbuf( const Allocator& a ) + : basic_stringbuf( std::ios_base::in | \fB(6)\fP \fI(since C++20)\fP + std::ios_base::out, a ) {} + template< class SAlloc > + + explicit basic_stringbuf( const std::basic_string& s, \fB(7)\fP \fI(since C++20)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); \fB(1)\fP + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(8)\fP \fI(since C++20)\fP + + std::ios_base::openmode which, const + Allocator& a ); + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(9)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringbuf( s, std::ios_base::in | + std::ios_base::out, a ) {} + template< class StringViewLike > + + explicit basic_stringbuf( const StringViewLike& t, + std::ios_base::openmode which = \fB(10)\fP (since C++26) + + std::ios_base::in | + std::ios_base::out ); + template< class StringViewLike > + + basic_stringbuf( const StringViewLike& t, \fB(11)\fP (since C++26) + + std::ios_base::openmode which, const + Allocator& a ); + template< class StringViewLike > + basic_stringbuf( const StringViewLike& t, const Allocator& a \fB(12)\fP (since C++26) + ); + basic_stringbuf( basic_stringbuf&& rhs ); \fB(13)\fP \fI(since C++11)\fP + basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a ); \fB(14)\fP \fI(since C++20)\fP + basic_stringbuf( const basic_stringbuf& rhs ) = delete; \fB(15)\fP \fI(since C++11)\fP + + The std::basic_streambuf base and the exposition-only data members buf and mode are + initialized as follows. + + After initializing these subobjects, overloads (3-12) initialize the input and + output sequences as if by calling init_buf_ptrs(). + + Overload std::basic_streambuf buf mode + base + \fB(1)\fP which + implementation-defined std::ios_base::in | + \fB(2)\fP (see below) + std::ios_base::out + \fB(3)\fP s + \fB(4)\fP std::move(s) which + \fB(5)\fP + a std::ios_base::in | + \fB(6)\fP + default-initialized std::ios_base::out + \fB(7)\fP s which + \fB(8)\fP + {s, a} std::ios_base::in | + \fB(9)\fP + std::ios_base::out + \fB(10)\fP {sv, Allocator()} which + \fB(11)\fP + {sv, a} std::ios_base::in | + \fB(12)\fP + std::ios_base::out + \fB(13)\fP rhs std::move(rhs).str() + \fB(14)\fP (copy constructed) {std::move(rhs).str(), rhs.mode + a} + + 1,2) Overload + \fB(1)\fP + \fI(until C++11)\fP + \fB(2)\fP + \fI(since C++11)\fP is the default constructor. It is implementation-defined whether the + sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are + initialized to null pointers. + 5,6) When the construction is complete, str.empty() is true. + 7) This overload participates in overload resolution only if std::is_same_v is false. + 10-12) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then it is used as above in the + table. + These overloads participate in overload resolution only if + std::is_convertible_v> is true. + 13,14) Overload \fB(13)\fP is the move constructor. It is implementation-defined whether + the six sequence pointers in *this obtain the values which rhs had. + When the construction is complete, rhs is empty but usable, and + * Let rhs_p refer to the state of rhs just prior to this construction, the + following expressions will evaluate to true: + + * str() == rhs_p.str() + * getloc() == rhs_p.getloc() + * gptr() - eback() == rhs_p.gptr() - rhs_p.eback() + * egptr() - eback() == rhs_p.egptr() - rhs_p.eback() + * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase() + * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase() + * Let rhs_a refer to the state of rhs just after this construction, the following + expressions will evaluate to true: + + * !eback() || eback() != rhs_a.eback() + * !gptr() || gptr() != rhs_a.gptr() + * !egptr() || egptr() != rhs_a.egptr() + * !pbase() || pbase() != rhs_a.pbase() + * !pptr() || pptr() != rhs_a.pptr() + * !epptr() || epptr() != rhs_a.epptr() + 15) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible. + +.SH Parameters + + s - a std::basic_string used to initialize the buffer + t - an object (convertible to std::basic_string_view) used to initialize the + buffer + a - another allocator used to construct the internal std::basic_string + rhs - another basic_stringbuf + specifies stream open mode. It is bitmask type, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + which - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Notes + + Typically called by the constructor of std::basic_stringstream. + + The level of support for the open modes other than std::ios_base::in and + std::ios_base::out varies among implementations. C++11 explicitly specifies the + support for std::ios_base::ate in str() and in this constructor, but + std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different + effects on different implementations. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + +.SH Example + + Demonstrates calling the constructor of std::basic_stringbuf directly: + + +// Run this code + + #include + #include + + int main() + { + // default constructor (mode = in | out) + std::stringbuf buf1; + buf1.sputc('1'); + std::cout << &buf1 << '\\n'; + + // string constructor in at-end mode \fI(C++11)\fP + std::stringbuf buf2("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::ate); + buf2.sputc('1'); + std::cout << &buf2 << '\\n'; + + // append mode test (results differ among compilers) + std::stringbuf buf3("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::app); + buf3.sputc('1'); + buf3.pubseekpos(1); + buf3.sputc('2'); + std::cout << &buf3 << '\\n'; + } + +.SH Output: + + 1 + test1 + est12 (Sun Studio) 2st1 (GCC) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP allocated no array object 1. removed the + LWG 432 C++98 2. overload \fB(3)\fP did not specify how the limitation + input 2. specified + and output sequences are initialized + overload \fB(3)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(which & beyond that position + std::ios_base::out) == true + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + constructs the string stream + constructor \fI\fI(public member\fP function of\fP + std::basic_stringstream) diff --git a/man/std::stringbuf::get_allocator.3 b/man/std::stringbuf::get_allocator.3 new file mode 100644 index 000000000..7857c70ac --- /dev/null +++ b/man/std::stringbuf::get_allocator.3 @@ -0,0 +1,22 @@ +.TH std::basic_stringbuf::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::get_allocator \- std::basic_stringbuf::get_allocator + +.SH Synopsis + allocator_type get_allocator() const noexcept; \fI(since C++20)\fP + + Returns the allocator associated with the internal sequence container. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + the associated allocator + +.SH See also + + returns the associated allocator + get_allocator \fI(public member function of std::basic_string)\fP + diff --git a/man/std::stringbuf::init_buf_ptrs.3 b/man/std::stringbuf::init_buf_ptrs.3 new file mode 100644 index 000000000..40e0a6044 --- /dev/null +++ b/man/std::stringbuf::init_buf_ptrs.3 @@ -0,0 +1,39 @@ +.TH std::basic_stringbuf::init_buf_ptrs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::init_buf_ptrs \- std::basic_stringbuf::init_buf_ptrs + +.SH Synopsis + void init_buf_ptrs(); (exposition only*) + + Initializes the input and output sequences from buf according to mode. buf and mode + are exposition-only data members of *this. + + Immediately after this function returns: + + * If std::ios_base::out is set in mode, pbase() points to buf.front() and epptr() + >= pbase() + buf.size() is true; + * in addition, if std::ios_base::ate is set in mode, pptr() == pbase() + + buf.size() is true, + * otherwise pptr() == pbase() is true. + * If std::ios_base::in is set in mode, eback() points to buf.front(), and gptr() + == eback() && egptr() == eback() + buf.size() is true. + +.SH Notes + + For efficiency reasons, stream buffer operations can violate invariants of buf while + it is held encapsulated in the std::basic_stringbuf, e.g., by writing to characters + in the range [buf.data() + buf.size(), buf.data() + buf.capacity()). + + All operations retrieving a std::basic_string from buf ensure that the + std::basic_string invariants hold on the returned value. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + calling init_buf_ptrs() made makes + LWG 1448 C++98 pptr() == pbase() + buf.data() pptr() == pbase() + + for streams that are both input and output buf.size() + streams for append streams diff --git a/man/std::stringbuf::operator=.3 b/man/std::stringbuf::operator=.3 deleted file mode 120000 index 58e2db92a..000000000 --- a/man/std::stringbuf::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::operator=.3 \ No newline at end of file diff --git a/man/std::stringbuf::operator=.3 b/man/std::stringbuf::operator=.3 new file mode 100644 index 000000000..2dedd1bb3 --- /dev/null +++ b/man/std::stringbuf::operator=.3 @@ -0,0 +1,56 @@ +.TH std::basic_stringbuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::operator= \- std::basic_stringbuf::operator= + +.SH Synopsis + std::basic_stringbuf& operator=( std::basic_stringbuf&& rhs ); \fB(1)\fP \fI(since C++11)\fP + std::basic_stringbuf& operator=( const std::basic_stringbuf& rhs ) \fB(2)\fP + = delete; + + 1) Move assignment operator: Moves the contents of rhs into *this. After the move, + *this has the associated string, the open mode, the locale, and all other state + formerly held by rhs. The six pointers of std::basic_streambuf in *this are + guaranteed to be different from the corresponding pointers in the moved-from rhs + unless null. + 2) The copy assignment operator is deleted; basic_stringbuf is not CopyAssignable. + +.SH Parameters + + rhs - another basic_stringbuf that will be moved from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream one("one"); + std::ostringstream two("two"); + + std::cout << "Before move, one = \\"" << one.str() << '"' + << " two = \\"" << two.str() << "\\"\\n"; + + *one.rdbuf() = std::move(*two.rdbuf()); + + std::cout << "After move, one = \\"" << one.str() << '"' + << " two = \\"" << two.str() << "\\"\\n"; + } + +.SH Output: + + Before move, one = "one" two = "two" + After move, one = "two" two = "" + +.SH See also + + constructor constructs a basic_stringbuf object + \fI(public member function)\fP diff --git a/man/std::stringbuf::overflow.3 b/man/std::stringbuf::overflow.3 deleted file mode 120000 index 59bc8dfab..000000000 --- a/man/std::stringbuf::overflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::overflow.3 \ No newline at end of file diff --git a/man/std::stringbuf::overflow.3 b/man/std::stringbuf::overflow.3 new file mode 100644 index 000000000..0f3394815 --- /dev/null +++ b/man/std::stringbuf::overflow.3 @@ -0,0 +1,136 @@ +.TH std::basic_stringbuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::overflow \- std::basic_stringbuf::overflow + +.SH Synopsis + protected: + virtual int_type overflow( int_type c = Traits::eof() ); + + Appends the character c to the output character sequence. + + If c is the end-of-file indicator (traits::eq_int_type(c, traits::eof()) == true), + then there is no character to append. The function does nothing and returns an + unspecified value other than traits::eof(). + + Otherwise, if the output sequence has a write position available or this function + can successfully make a write position available, then calls sputc(c) and returns c. + + This function can make a write position available if the std::stringbuf is open for + output ((mode & ios_base::out) != 0): in this case, it reallocates (or initially + allocates) the buffer big enough to hold the entire current buffer plus at least one + more character. If the std::stringbuf is also open for input ((mode & ios_base::in) + != 0), then overflow also increases the size of the get area by moving egptr() to + point just past the new write position. + +.SH Parameters + + c - the character to store in the put area + +.SH Return value + + Traits::eof() to indicate failure, c if the character c was successfully appended, + or some value other than Traits::eof() if called with Traits::eof() as the argument. + +.SH Notes + + This function is different from a typical overflow() which moves the contents of the + buffer to the associated character sequence because for a std::basic_stringbuf, the + buffer and the associated sequence are one and the same. + +.SH Example + + In the implementation used to execute this example (e.g. GCC-4.9), overflow() + over-allocates the put area to 512 bytes: a call to str() would only return the four + initialized bytes, but the next 508 calls to sputc() would not require new calls to + overflow(). + + +// Run this code + + #include + #include + + struct mybuf : std::stringbuf + { + mybuf(const std::string& new_str, + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out) + : std::stringbuf(new_str, which) {} + + int_type overflow(int_type c = EOF) override + { + std::cout << "stringbuf::overflow('" << char(c) << "') called\\n" + << "Before: size of get area: " << egptr() - eback() << '\\n' + << " size of put area: " << epptr() - pbase() << '\\n'; + + int_type ret = std::stringbuf::overflow(c); + + std::cout << "After : size of get area: " << egptr() - eback() << '\\n' + << " size of put area: " << epptr() - pbase() << '\\n'; + + return ret; + } + }; + + int main() + { + std::cout << "read-write stream:\\n"; + mybuf sbuf(" "); // read-write stream + std::iostream stream(&sbuf); + stream << 1234; + std::cout << sbuf.str() << '\\n'; + + std::cout << "\\nread-only stream:\\n"; + mybuf ro_buf(" ", std::ios_base::in); // read-only stream + std::iostream ro_stream(&ro_buf); + ro_stream << 1234; + + std::cout << "\\nwrite-only stream:\\n"; + mybuf wr_buf(" ", std::ios_base::out); // write-only stream + std::iostream wr_stream(&wr_buf); + wr_stream << 1234; + } + +.SH Possible output: + + read-write stream: + stringbuf::overflow('4') called + Before: size of get area: 3 + size of put area: 3 + After : size of get area: 4 + size of put area: 512 + 1234 + + read-only stream: + stringbuf::overflow('1') called + Before: size of get area: 3 + size of put area: 0 + After : size of get area: 3 + size of put area: 0 + + write-only stream: + stringbuf::overflow('4') called + Before: size of get area: 0 + size of put area: 3 + After : size of get area: 0 + size of put area: 512 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 169 C++98 the buffer (re)allocated could only hold one allows more extra + extra character characters + overflow moved epptr() to point just past the + LWG 432 C++98 new it is not moved + write position if the std::stringbuf is open + for input + +.SH See also + + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::stringbuf::pbackfail.3 b/man/std::stringbuf::pbackfail.3 deleted file mode 120000 index 01255a607..000000000 --- a/man/std::stringbuf::pbackfail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::pbackfail.3 \ No newline at end of file diff --git a/man/std::stringbuf::pbackfail.3 b/man/std::stringbuf::pbackfail.3 new file mode 100644 index 000000000..c8b1ffd10 --- /dev/null +++ b/man/std::stringbuf::pbackfail.3 @@ -0,0 +1,64 @@ +.TH std::basic_stringbuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::pbackfail \- std::basic_stringbuf::pbackfail + +.SH Synopsis + protected: + virtual int_type pbackfail( int_type c = Traits::eof() ) + + This protected virtual function is called by the public functions + basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called + by basic_istream::unget and basic_istream::putback). + + 1) The caller is requesting that the get area is backed up by one character + (pbackfail() is called with no arguments or with Traits::eof() as the argument) + a) First, checks if there is a putback position, and if there really isn't, fails. + (stringbuf has no external character source to re-read) + b) If the caller was wrong and the putback position is in fact available, simply + decrements basic_streambuf::gptr(), e.g. by calling gbump(-1). + 2) The caller attempts to putback a different character from the one retrieved + earlier (pbackfail() is called with the character that needs to be put back), in + which case + a) First, checks if there is a putback position, and if there isn't, fails. + b) Then checks what character is in the putback position. If the character held + there is already equal to c, as determined by Traits::eq(to_char_type(c), + gptr()[-1]), then simply decrements basic_streambuf::gptr(). + c) Otherwise, if the buffer is open for reading only, fails. + d) Otherwise, if the buffer is open for writing (mode && std::ios_base::out is + nonzero), then decrements basic_streambuf::gptr() and writes c to the location + pointed to gptr() after adjustment. + +.SH Parameters + + c - the character to put back, or Traits::eof() to indicate that backing up of the + get area is requested + +.SH Return value + + c on success except if c was Traits::eof(), in which case Traits::not_eof(c) is + returned. + + Traits::eof() on failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function of std::basic_streambuf)\fP + sputbackc puts one character back in the input sequence + \fI(public member function of std::basic_streambuf)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::stringbuf::seekoff.3 b/man/std::stringbuf::seekoff.3 deleted file mode 120000 index 870684814..000000000 --- a/man/std::stringbuf::seekoff.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::seekoff.3 \ No newline at end of file diff --git a/man/std::stringbuf::seekoff.3 b/man/std::stringbuf::seekoff.3 new file mode 100644 index 000000000..a8a742258 --- /dev/null +++ b/man/std::stringbuf::seekoff.3 @@ -0,0 +1,157 @@ +.TH std::basic_stringbuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::seekoff \- std::basic_stringbuf::seekoff + +.SH Synopsis + protected: + + virtual pos_type seekoff( off_type off, + std::ios_base::seekdir dir, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if + possible, to the position that corresponds to exactly off characters from beginning, + end, or current position of the get and/or put area of the buffer. + + * If which includes std::ios_base::in and this buffer is open for reading (that + is, if (which & std::ios_base::in) == std::ios_base::in), then repositions the + read pointer std::basic_streambuf::gptr inside the get area as described below + * If which includes std::ios_base::out and this buffer is open for writing (that + is, (which & std::ios_base::out) == std::ios_base::out), then repositions the + write pointer std::basic_streambuf::pptr inside the put area as described below + * If which includes both std::ios_base::in and std::ios_base::out and the buffer + is open for both reading and writing (that is, (which & (std::ios_base::in | + std::ios_base::out)) == (std::ios_base::in | std::ios_base::out)), and dir is + either std::ios_base::beg or std::ios_base::end, then repositions both read and + write pointers as described below. + * Otherwise, this function fails. + + If gptr and/or pptr is repositioned, it is done as follows: + + 1) The new pointer offset newoff of type off_type is determined + a) if dir == std::ios_base::beg, then newoff is zero + b) if dir == std::ios_base::cur, then newoff is the current position of the pointer + (gptr() - eback() or pptr() - pbase()) + c) if dir == std::ios_base::end, then newoff is the length of the entire initialized + part of the buffer (if over-allocation is used, the high watermark pointer minus the + beginning pointer) + 2) If the pointer to be repositioned is a null pointer and newoff would be non-zero, + this function fails. + 3) If newoff + off < 0 (the repositioning would move the pointer to before the + beginning of the buffer) or if newoff + off would point past the end of the buffer + (or past the last initialized character in the buffer if over-allocation is used), + the function fails. + 4) Otherwise, the pointer is assigned as if by gptr() = eback() + newoff + off or + pptr() = pbase() + newoff + off. + +.SH Parameters + + off - relative position to set the next pointer(s) to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines whether the input sequences, the output sequence, or both are + affected. It can be one or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + pos_type(newoff) on success, pos_type(off_type(-1)) on failure or if pos_type cannot + represent the resulting stream position. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream ss("123"); // in/out + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + // absolute positioning both pointers + ss.rdbuf()->pubseekoff(1, std::ios_base::beg); // move both 1 forward + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + // try to move both pointers 1 forward from current position + if (-1 == ss.rdbuf()->pubseekoff(1, std::ios_base::cur)) + std::cout << "moving both pointers from current position failed\\n"; + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + // move the write pointer 1 forward, but not the read pointer + // can also be called as ss.seekp(1, std::ios_base::cur); + ss.rdbuf()->pubseekoff(1, std::ios_base::cur, std::ios_base::out); + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + ss << 'a'; // write at put position + std::cout << "Wrote 'a' at put position, the buffer is now " << ss.str() << '\\n'; + + char ch; + ss >> ch; + std::cout << "reading at get position gives '" << ch << "'\\n"; + } + +.SH Output: + + put pos = 0 get pos = 0 + put pos = 1 get pos = 1 + moving both pointers from current position failed + put pos = 1 get pos = 1 + put pos = 2 get pos = 1 + Wrote 'a' at put position, the buffer is now 12a + reading at get position gives '2' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + static constant members of + LWG 375 C++98 std::ios_base were corrected + misspecified as members of + std::basic_ios + seekoff might succeed even if newoff + LWG 432 C++98 + off seekoff fails + would point past the last initialized in this case + character + repositioning null gptr() and/or null + LWG 453 C++98 pptr() it can succeed in this case + with a new offset of zero always + failed + the end pointer could not be used to + LWG 563 C++98 calculate newoff because it could use the high watermark + not be precisely controlled by the pointer instead + program after resolving LWG issue 432 + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::stringbuf::seekpos.3 b/man/std::stringbuf::seekpos.3 deleted file mode 120000 index 97415d273..000000000 --- a/man/std::stringbuf::seekpos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::seekpos.3 \ No newline at end of file diff --git a/man/std::stringbuf::seekpos.3 b/man/std::stringbuf::seekpos.3 new file mode 100644 index 000000000..2a5102900 --- /dev/null +++ b/man/std::stringbuf::seekpos.3 @@ -0,0 +1,105 @@ +.TH std::basic_stringbuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::seekpos \- std::basic_stringbuf::seekpos + +.SH Synopsis + protected: + + virtual pos_type seekpos( pos_type sp, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if + possible, to the position indicated by sp. + + Effectively executes seekoff(off_type(sp), std::ios_base::beg, which). + +.SH Parameters + + sp - stream position, such as one obtained by seekoff() or seekpos() + defines whether the input sequences, the output sequence, or both are + affected. It can be one or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + sp on success or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the + single-argument versions of std::basic_istream::seekg() and + std::basic_ostream::seekp(). + +.SH Example + + +// Run this code + + #include + #include + + struct mybuf : std::stringbuf + { + mybuf(const std::string& str) : std::stringbuf(str) {} + + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::stringbuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + return rc; + } + }; + + int main() + { + mybuf buf("12345"); + std::iostream stream(&buf); + stream.seekg(2); + } + +.SH Output: + + Before seekpos\fB(2)\fP, size of the get area is 5 with 5 read positions available. + seekpos() returns 2. + After the call, size of the get area is 5 with 3 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + static constant members of std::ios_base + LWG 375 C++98 were corrected + misspecified as members of + std::basic_ios + LWG 564 C++98 if was unclear how to reposition gptr they are repositioned by + and/or pptr seekoff() + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::stringbuf::setbuf.3 b/man/std::stringbuf::setbuf.3 deleted file mode 120000 index 0876df772..000000000 --- a/man/std::stringbuf::setbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::setbuf.3 \ No newline at end of file diff --git a/man/std::stringbuf::setbuf.3 b/man/std::stringbuf::setbuf.3 new file mode 100644 index 000000000..d311331a5 --- /dev/null +++ b/man/std::stringbuf::setbuf.3 @@ -0,0 +1,62 @@ +.TH std::basic_stringbuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::setbuf \- std::basic_stringbuf::setbuf + +.SH Synopsis + protected: + virtual std::basic_streambuf* setbuf( char_type* s, std::streamsize + n ) + + If s is a null pointer and n is zero, this function has no effect. + + Otherwise, the effect is implementation-defined: some implementations do nothing, + while some implementations clear the std::string member currently used as the buffer + and begin using the user-supplied character array of size n, whose first element is + pointed to by s, as the buffer and the input/output character sequence. + + This function is protected virtual, it may only be called through pubsetbuf() or + from member functions of a user-defined class derived from std::basic_stringbuf. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer or null + n - the number of CharT elements in the user-provided buffer or zero + +.SH Return value + + this + +.SH Notes + + The deprecated stream buffer std::strstreambuf or the boost.IOStreams device + boost::basic_array may be used to implement I/O buffering over a user-provided char + array in portable manner. + +.SH Example + + Test for the stringstream's setbuf functionality. + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream ss; + char c[1024] = {}; + ss.rdbuf()->pubsetbuf(c, 1024); + ss << 3.14 << '\\n'; + std::cout << c << '\\n'; + } + +.SH Output: + + 3.14 (on GNU g++/libstdc++ and SunPro C++/roguewave) + (on MS Visual Studio 2010, SunPro C++/stlport4, CLang++/libc++) + +.SH See also + + pubsetbuf invokes setbuf() + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::stringbuf::str.3 b/man/std::stringbuf::str.3 deleted file mode 120000 index 4ad9797b5..000000000 --- a/man/std::stringbuf::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::str.3 \ No newline at end of file diff --git a/man/std::stringbuf::str.3 b/man/std::stringbuf::str.3 new file mode 100644 index 000000000..ba2785791 --- /dev/null +++ b/man/std::stringbuf::str.3 @@ -0,0 +1,141 @@ +.TH std::basic_stringbuf::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::str \- std::basic_stringbuf::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Gets and sets the underlying string. + + In the descriptions below, buf and mode are exposition-only data members of *this. + + 1) Creates and returns a std::basic_string object containing a copy of this + std::basic_stringbuf's underlying character sequence. For input-only streams, the + returned string contains the characters from the range [eback(), egptr()). For + input/output or output-only streams, contains the characters from pbase() to the + last character in the sequence regardless of egptr() and epptr(). + + The member character sequence in a buffer open for writing can be over-allocated for + efficiency purposes. In that case, only the initialized characters are returned: + these characters are the ones that were obtained from the string argument of the + constructor, the string argument of the most recent call to a setter overload of + str(), or from a write operation. A typical implementation that uses over-allocation + maintains a high-watermark pointer to track the end of the initialized part of the + buffer and this overload returns the characters from pbase() to the high-watermark + pointer. + + Equivalent to return std::basic_string(view(), get_allocator());. + + 2) Same as \fB(1)\fP, except that a is used to construct the returned std::basic_string. + Equivalent to return std::basic_string(view(), a);. + This overload participates in overload resolution only if SAlloc meets the + requirements of Allocator. + 3) Creates a std::basic_string object as if by move constructing it from *this's + underlying character sequence in buf. buf may need to be adjusted to contain the + same content as in \fB(1)\fP at first. After that, sets buf to empty and calls + init_buf_ptrs(), then returns the std::basic_string object. + 4) Replaces the underlying character sequence as if by buf = s, then calls + init_buf_ptrs(). + 5) Same as \fB(4)\fP, except the type of s's allocator is not Allocator. + This overload participates in overload resolution only if std::is_same_v is false. + 6) Replaces the underlying character sequence as if by buf = std::move(s), then + calls init_buf_ptrs(). + 7) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the underlying character sequence as if by buf = sv, + then calls init_buf_ptrs(). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + +.SH Parameters + + s - a std::basic_string object holding the replacement character sequence + t - an object (convertible to std::basic_string_view) holding the replacement + character sequence + a - allocator to use for all memory allocations of the returned std::basic_string + +.SH Return value + + 1-3) A std::basic_string object holding this buffer's underlying character sequence. + 4-7) \fI(none)\fP + +.SH Notes + + This function is typically accessed through std::basic_istringstream::str(), + std::basic_ostringstream::str(), or std::basic_stringstream::str(). + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.rdbuf()->str("1 2"); // set the get area + in >> n; + std::cout << "after reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.rdbuf()->str() << "\\"\\n"; // or in.str() + + std::ostringstream out("1 2"); + out << 3; + std::cout << "after writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); // C++11 + ate << 3; + std::cout << "after writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + after reading the first int from "1 2", the int is 1, str() = "1 2" + after writing the int '3' to output stream "1 2", str() = "3 2" + after writing the int '3' to append stream "1 2", str() = "1 23" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP did not specify the content + LWG 432 C++98 of the underlying character sequence both specified + 2. overload \fB(4)\fP did not specify how the + input and output sequences are initialized + overload \fB(4)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(mode & std::ios_base::out) beyond that position + == true + +.SH See also + + gets or sets the contents of underlying string device object + str \fI(public member function of std::basic_stringstream)\fP + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function)\fP diff --git a/man/std::stringbuf::stringbuf.3 b/man/std::stringbuf::stringbuf.3 deleted file mode 120000 index 305998a5b..000000000 --- a/man/std::stringbuf::stringbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::basic_stringbuf.3 \ No newline at end of file diff --git a/man/std::stringbuf::stringbuf.3 b/man/std::stringbuf::stringbuf.3 new file mode 100644 index 000000000..496a0651e --- /dev/null +++ b/man/std::stringbuf::stringbuf.3 @@ -0,0 +1,240 @@ +.TH std::basic_stringbuf::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::basic_stringbuf \- std::basic_stringbuf::basic_stringbuf + +.SH Synopsis + explicit basic_stringbuf( std::ios_base::openmode which = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringbuf( std::ios_base::openmode which ); \fI(since C++11)\fP + basic_stringbuf() + : basic_stringbuf( std::ios_base::in | std::ios_base::out \fB(2)\fP \fI(since C++11)\fP + ) {} + explicit + + basic_stringbuf( const std::basic_string& s, \fB(3)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); + explicit basic_stringbuf( std::basic_string&& s, + + std::ios_base::openmode which = \fB(4)\fP \fI(since C++20)\fP + + std::ios_base::in | + std::ios_base::out ); + basic_stringbuf( std::ios_base::openmode which, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + explicit basic_stringbuf( const Allocator& a ) + : basic_stringbuf( std::ios_base::in | \fB(6)\fP \fI(since C++20)\fP + std::ios_base::out, a ) {} + template< class SAlloc > + + explicit basic_stringbuf( const std::basic_string& s, \fB(7)\fP \fI(since C++20)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); \fB(1)\fP + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(8)\fP \fI(since C++20)\fP + + std::ios_base::openmode which, const + Allocator& a ); + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(9)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringbuf( s, std::ios_base::in | + std::ios_base::out, a ) {} + template< class StringViewLike > + + explicit basic_stringbuf( const StringViewLike& t, + std::ios_base::openmode which = \fB(10)\fP (since C++26) + + std::ios_base::in | + std::ios_base::out ); + template< class StringViewLike > + + basic_stringbuf( const StringViewLike& t, \fB(11)\fP (since C++26) + + std::ios_base::openmode which, const + Allocator& a ); + template< class StringViewLike > + basic_stringbuf( const StringViewLike& t, const Allocator& a \fB(12)\fP (since C++26) + ); + basic_stringbuf( basic_stringbuf&& rhs ); \fB(13)\fP \fI(since C++11)\fP + basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a ); \fB(14)\fP \fI(since C++20)\fP + basic_stringbuf( const basic_stringbuf& rhs ) = delete; \fB(15)\fP \fI(since C++11)\fP + + The std::basic_streambuf base and the exposition-only data members buf and mode are + initialized as follows. + + After initializing these subobjects, overloads (3-12) initialize the input and + output sequences as if by calling init_buf_ptrs(). + + Overload std::basic_streambuf buf mode + base + \fB(1)\fP which + implementation-defined std::ios_base::in | + \fB(2)\fP (see below) + std::ios_base::out + \fB(3)\fP s + \fB(4)\fP std::move(s) which + \fB(5)\fP + a std::ios_base::in | + \fB(6)\fP + default-initialized std::ios_base::out + \fB(7)\fP s which + \fB(8)\fP + {s, a} std::ios_base::in | + \fB(9)\fP + std::ios_base::out + \fB(10)\fP {sv, Allocator()} which + \fB(11)\fP + {sv, a} std::ios_base::in | + \fB(12)\fP + std::ios_base::out + \fB(13)\fP rhs std::move(rhs).str() + \fB(14)\fP (copy constructed) {std::move(rhs).str(), rhs.mode + a} + + 1,2) Overload + \fB(1)\fP + \fI(until C++11)\fP + \fB(2)\fP + \fI(since C++11)\fP is the default constructor. It is implementation-defined whether the + sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are + initialized to null pointers. + 5,6) When the construction is complete, str.empty() is true. + 7) This overload participates in overload resolution only if std::is_same_v is false. + 10-12) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then it is used as above in the + table. + These overloads participate in overload resolution only if + std::is_convertible_v> is true. + 13,14) Overload \fB(13)\fP is the move constructor. It is implementation-defined whether + the six sequence pointers in *this obtain the values which rhs had. + When the construction is complete, rhs is empty but usable, and + * Let rhs_p refer to the state of rhs just prior to this construction, the + following expressions will evaluate to true: + + * str() == rhs_p.str() + * getloc() == rhs_p.getloc() + * gptr() - eback() == rhs_p.gptr() - rhs_p.eback() + * egptr() - eback() == rhs_p.egptr() - rhs_p.eback() + * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase() + * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase() + * Let rhs_a refer to the state of rhs just after this construction, the following + expressions will evaluate to true: + + * !eback() || eback() != rhs_a.eback() + * !gptr() || gptr() != rhs_a.gptr() + * !egptr() || egptr() != rhs_a.egptr() + * !pbase() || pbase() != rhs_a.pbase() + * !pptr() || pptr() != rhs_a.pptr() + * !epptr() || epptr() != rhs_a.epptr() + 15) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible. + +.SH Parameters + + s - a std::basic_string used to initialize the buffer + t - an object (convertible to std::basic_string_view) used to initialize the + buffer + a - another allocator used to construct the internal std::basic_string + rhs - another basic_stringbuf + specifies stream open mode. It is bitmask type, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + which - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Notes + + Typically called by the constructor of std::basic_stringstream. + + The level of support for the open modes other than std::ios_base::in and + std::ios_base::out varies among implementations. C++11 explicitly specifies the + support for std::ios_base::ate in str() and in this constructor, but + std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different + effects on different implementations. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + +.SH Example + + Demonstrates calling the constructor of std::basic_stringbuf directly: + + +// Run this code + + #include + #include + + int main() + { + // default constructor (mode = in | out) + std::stringbuf buf1; + buf1.sputc('1'); + std::cout << &buf1 << '\\n'; + + // string constructor in at-end mode \fI(C++11)\fP + std::stringbuf buf2("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::ate); + buf2.sputc('1'); + std::cout << &buf2 << '\\n'; + + // append mode test (results differ among compilers) + std::stringbuf buf3("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::app); + buf3.sputc('1'); + buf3.pubseekpos(1); + buf3.sputc('2'); + std::cout << &buf3 << '\\n'; + } + +.SH Output: + + 1 + test1 + est12 (Sun Studio) 2st1 (GCC) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP allocated no array object 1. removed the + LWG 432 C++98 2. overload \fB(3)\fP did not specify how the limitation + input 2. specified + and output sequences are initialized + overload \fB(3)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(which & beyond that position + std::ios_base::out) == true + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + constructs the string stream + constructor \fI\fI(public member\fP function of\fP + std::basic_stringstream) diff --git a/man/std::stringbuf::swap.3 b/man/std::stringbuf::swap.3 deleted file mode 120000 index 925518804..000000000 --- a/man/std::stringbuf::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::swap.3 \ No newline at end of file diff --git a/man/std::stringbuf::swap.3 b/man/std::stringbuf::swap.3 new file mode 100644 index 000000000..60e1e3222 --- /dev/null +++ b/man/std::stringbuf::swap.3 @@ -0,0 +1,76 @@ +.TH std::basic_stringbuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::swap \- std::basic_stringbuf::swap + +.SH Synopsis + void swap( basic_stringbuf& rhs ); \fI(since C++11)\fP + \fI(until C++20)\fP + void swap( basic_stringbuf& rhs ) noexcept(/* see below */); \fI(since C++20)\fP + + Swaps the state and the contents of *this and rhs. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + +.SH Parameters + + rhs - another basic_stringbuf + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + (since + May throw implementation-defined exceptions. C++11) + (until + C++20) + noexcept specification: (since + noexcept(std::allocator_traits::propagate_on_container_swap::value C++20) + || std::allocator_traits::is_always_equal::value) + +.SH Notes + + This function is called automatically when swapping std::stringstream objects. It is + rarely necessary to call it directly. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::istringstream one("one"); + std::ostringstream two("two"); + + std::cout << "Before swap: one = " << std::quoted(one.str()) + << ", two = " << std::quoted(two.str()) << ".\\n"; + + one.rdbuf()->swap(*two.rdbuf()); + + std::cout << "After swap: one = " << std::quoted(one.str()) + << ", two = " << std::quoted(two.str()) << ".\\n"; + } + +.SH Output: + + Before swap: one = "one", two = "two". + After swap: one = "two", two = "one". + +.SH See also + + constructor constructs a basic_stringbuf object + \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI\fI(public member\fP function of\fP + std::basic_stringstream) + +.SH Category: + * conditionally noexcept diff --git a/man/std::stringbuf::underflow.3 b/man/std::stringbuf::underflow.3 deleted file mode 120000 index 5313ba532..000000000 --- a/man/std::stringbuf::underflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::underflow.3 \ No newline at end of file diff --git a/man/std::stringbuf::underflow.3 b/man/std::stringbuf::underflow.3 new file mode 100644 index 000000000..e5d49cc92 --- /dev/null +++ b/man/std::stringbuf::underflow.3 @@ -0,0 +1,139 @@ +.TH std::basic_stringbuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::underflow \- std::basic_stringbuf::underflow + +.SH Synopsis + protected: + virtual int_type underflow() + + Reads the next character from the get area of the buffer. + + Specifically: + + 1) If the input sequence has a read position available (egptr() > gptr()), returns + Traits::to_int_type(*gptr()) + 2) Otherwise, if pptr() > egptr() (some characters were inserted into the stream + since the last time overflow() changed egptr()) then extends the end of the get area + to include the most recently inserted characters, by changing egptr() to equal + pptr(), and then returns Traits::to_int_type(*gptr()) + 3) Otherwise, returns Traits::eof(). + + Any character in the buffer which has been initialized, regardless of whether it + originated from the string passed in the constructor or was appended by overflow(), + is considered to be part of the input sequence. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Traits::to_int_type(*gptr()) (the next character to read in the get area) in case of + success, or Traits::eof() in case of failure. + +.SH Example + + +// Run this code + + #include + #include + + struct mybuf : std::stringbuf + { + mybuf(const std::string& new_str, + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out) + : std::stringbuf(new_str, which) {} + + int_type overflow(int_type c) + { + std::cout << "Before overflow(): get area size is " << egptr() - eback() + << ", the put area size is " << epptr() - pbase() << '\\n'; + int_type rc = std::stringbuf::overflow(c); + std::cout << "After overflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + return rc; + } + + int_type underflow() + { + std::cout << "Before underflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + int_type ch = std::stringbuf::underflow(); + std::cout << "After underflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + + if (ch == EOF) + std::cout << "underflow() returns EOF\\n"; + else + std::cout << "underflow() returns '" << char(ch) << "'\\n"; + return ch; + } + }; + + int main() + { + mybuf sbuf("123"); // read-write stream + std::iostream stream(&sbuf); + int n; + stream >> n; // calls sgetc() four times + // three calls return the characters '1', '2', '3' + // the fourth call, gptr() == egptr() and underflow() is called + // underflow returns EOF + std::cout << "n = " << n << '\\n'; + stream.clear(); // clear the eofbit + + stream << "123456"; // sputc() is called 6 times + // first three calls store "123" in the existing buffer + // 4th call finds that pptr() == epptr() and calls overflow() + // overflow() grows the buffer and sets egptr() to 4 + // 5th and 6th calls store '5' and '6', advancing pptr() + + stream >> n; // calls sgetc() 4 times + // 1st call returns the '4' that was made available by overflow() + // on the 2nd call, egptr() == egptr() and underflow() is called + // underflow advances egptr() to equal pptr() (which is 6) + // 3rd sgetc() returns '6' + // 4th sgetc() finds gptr() == egptr(), calls underflow() + // underflow() returns EOF + + std::cout << "n = " << n << '\\n'; + } + +.SH Possible output: + + Before underflow(): get area size is 3, put area size is 15 + After underflow(): get area size is 3, put area size is 15 + underflow() returns EOF + n = 123 + Before underflow(): get area size is 3, put area size is 15 + After underflow(): get area size is 6, put area size is 15 + underflow() returns '4' + Before underflow(): get area size is 6, put area size is 15 + After underflow(): get area size is 6, put area size is 15 + underflow() returns EOF + n = 456 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether characters appended by + LWG 432 C++98 overflow() made clear + are considered to be part of the input sequence + +.SH See also + + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + underflow reads a character from the input sequence without advancing the next + \fB[virtual]\fP pointer + \fI(virtual protected member function of std::strstreambuf)\fP + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::stringbuf::view.3 b/man/std::stringbuf::view.3 new file mode 100644 index 000000000..eb1842d18 --- /dev/null +++ b/man/std::stringbuf::view.3 @@ -0,0 +1,50 @@ +.TH std::basic_stringbuf::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::view \- std::basic_stringbuf::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Creates and returns a std::basic_string_view over the underlying character sequence. + + * For input-only streams, the returned view represents the range [eback(), + egptr()). + * For input/output or output-only streams, references the characters from pbase() + to the last character in the sequence regardless of egptr() and epptr(). + * If the stream is neither input nor output, returns std::basic_string_view{}. + + The member character sequence in a buffer open for writing can be over-allocated for + efficiency purposes. In that case, only the initialized characters are referenced: + these characters are the ones that were obtained from the string argument of the + constructor, the string argument used by the most recent call to a setter overload + of str(), or from a write operation. A typical implementation that uses + over-allocation maintains a high-watermark pointer to track the end of the + initialized part of the buffer and the returned view references the characters from + pbase() to the high-watermark pointer. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A view over the underlying character sequence. + +.SH Notes + + Using of the return value is undefined behavior if the underlying character sequence + is destroyed or invalidated, unless the return value is empty. + + This function is typically accessed through std::basic_istringstream::view(), + std::basic_ostringstream::view(), or std::basic_stringstream::view(). + +.SH See also + + replaces or obtains a copy of the associated character + str string + \fI(public member function)\fP + returns a non-modifiable string_view into the entire + operator basic_string_view string + \fI(C++17)\fP \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::stringstream.3 b/man/std::stringstream.3 deleted file mode 120000 index 5f0585c2e..000000000 --- a/man/std::stringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream.3 \ No newline at end of file diff --git a/man/std::stringstream.3 b/man/std::stringstream.3 new file mode 100644 index 000000000..1d773afdb --- /dev/null +++ b/man/std::stringstream.3 @@ -0,0 +1,318 @@ +.TH std::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream \- std::basic_stringstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + > class basic_stringstream + + : public basic_iostream; + + The class template std::basic_stringstream implements input and output operations on + string based streams. It effectively stores an instance of std::basic_string and + performs the input and output operations on it. + + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_iostream. The + complete interface to unique std::basic_stringbuf members is provided. + + std-basic stringstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::stringstream std::basic_stringstream + std::wstringstream std::basic_stringstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) + +.SH Member functions + + constructor constructs the string stream + \fI(public member function)\fP + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP +.SH String operations + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_istringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::stringstream::basic_stringstream.3 b/man/std::stringstream::basic_stringstream.3 deleted file mode 120000 index 8593426e8..000000000 --- a/man/std::stringstream::basic_stringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::basic_stringstream.3 \ No newline at end of file diff --git a/man/std::stringstream::basic_stringstream.3 b/man/std::stringstream::basic_stringstream.3 new file mode 100644 index 000000000..c017c138f --- /dev/null +++ b/man/std::stringstream::basic_stringstream.3 @@ -0,0 +1,181 @@ +.TH std::basic_stringstream::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::basic_stringstream \- std::basic_stringstream::basic_stringstream + +.SH Synopsis + explicit basic_stringstream( std::ios_base::openmode mode = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_stringstream() + : basic_stringstream(std::ios_base::in | \fB(2)\fP \fI(since C++11)\fP + std::ios_base::out) {} + explicit basic_stringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + explicit basic_stringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + basic_stringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_stringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + \fB(1)\fP + basic_stringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringstream(str, std::ios_base::in | + std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_stringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + explicit basic_stringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + basic_stringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_stringstream( const StringViewLike& t, const Allocator& \fB(11)\fP (since C++26) + a ); + basic_stringstream( basic_stringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_iostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_iostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_iostream base sb + load + \fB(1)\fP buf_type(mode) + \fB(2)\fP buf_type(std::ios_base::in | + std::ios_base::out) + \fB(3)\fP buf_type(str, mode) + \fB(4)\fP base_type(std::addressof(sb))^[1] buf_type(std::move(str), mode) + \fB(5)\fP buf_type(mode, a) + \fB(6)\fP buf_type(str, mode, a) + \fB(7)\fP buf_type(str, std::ios_base::in | + std::ios_base::out, a) + \fB(8)\fP buf_type(str, mode) + \fB(9)\fP {t, mode, Allocator()} + \fB(10)\fP std::addressof(sb) {t, mode, a} + \fB(11)\fP {t, std::ios_base::in | + std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_iostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_stringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::stringstream::operator=.3 b/man/std::stringstream::operator=.3 deleted file mode 120000 index b0a017836..000000000 --- a/man/std::stringstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::operator=.3 \ No newline at end of file diff --git a/man/std::stringstream::operator=.3 b/man/std::stringstream::operator=.3 new file mode 100644 index 000000000..11454b1f2 --- /dev/null +++ b/man/std::stringstream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_stringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::operator= \- std::basic_stringstream::operator= + +.SH Synopsis + basic_stringstream& operator=( basic_stringstream&& other ); \fI(since C++11)\fP + + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_iostream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. + +.SH Parameters + + other - string stream to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::stringstream::rdbuf.3 b/man/std::stringstream::rdbuf.3 deleted file mode 120000 index 05bbb1c9c..000000000 --- a/man/std::stringstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::stringstream::rdbuf.3 b/man/std::stringstream::rdbuf.3 new file mode 100644 index 000000000..f35cd4f29 --- /dev/null +++ b/man/std::stringstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_stringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::rdbuf \- std::basic_stringstream::rdbuf + +.SH Synopsis + std::basic_stringbuf* rdbuf() const; + + Returns pointer to the underlying raw string device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw string device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::stringstream::str.3 b/man/std::stringstream::str.3 deleted file mode 120000 index 91d48274a..000000000 --- a/man/std::stringstream::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::str.3 \ No newline at end of file diff --git a/man/std::stringstream::str.3 b/man/std::stringstream::str.3 new file mode 100644 index 000000000..1202dfdad --- /dev/null +++ b/man/std::stringstream::str.3 @@ -0,0 +1,99 @@ +.TH std::basic_stringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::str \- std::basic_stringstream::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Manages the contents of the underlying string object. + + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. + +.SH Parameters + + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string + +.SH Return value + + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP + +.SH Notes + + The copy of the underlying string returned by str is a temporary object that will be + destructed at the end of the expression, so directly calling c_str() on the result + of str() (for example in auto *ptr = out.str().c_str();) results in a dangling + pointer. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.str("1 2"); + in >> n; + std::cout << "After reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.str() << "\\"\\n"; + + std::ostringstream out("1 2"); + out << 3; + std::cout << "After writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); + ate << 3; + std::cout << "After writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" + +.SH See also + + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::stringstream::stringstream.3 b/man/std::stringstream::stringstream.3 deleted file mode 120000 index 8593426e8..000000000 --- a/man/std::stringstream::stringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::basic_stringstream.3 \ No newline at end of file diff --git a/man/std::stringstream::stringstream.3 b/man/std::stringstream::stringstream.3 new file mode 100644 index 000000000..c017c138f --- /dev/null +++ b/man/std::stringstream::stringstream.3 @@ -0,0 +1,181 @@ +.TH std::basic_stringstream::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::basic_stringstream \- std::basic_stringstream::basic_stringstream + +.SH Synopsis + explicit basic_stringstream( std::ios_base::openmode mode = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_stringstream() + : basic_stringstream(std::ios_base::in | \fB(2)\fP \fI(since C++11)\fP + std::ios_base::out) {} + explicit basic_stringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + explicit basic_stringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + basic_stringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_stringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + \fB(1)\fP + basic_stringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringstream(str, std::ios_base::in | + std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_stringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + explicit basic_stringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + basic_stringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_stringstream( const StringViewLike& t, const Allocator& \fB(11)\fP (since C++26) + a ); + basic_stringstream( basic_stringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_iostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_iostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_iostream base sb + load + \fB(1)\fP buf_type(mode) + \fB(2)\fP buf_type(std::ios_base::in | + std::ios_base::out) + \fB(3)\fP buf_type(str, mode) + \fB(4)\fP base_type(std::addressof(sb))^[1] buf_type(std::move(str), mode) + \fB(5)\fP buf_type(mode, a) + \fB(6)\fP buf_type(str, mode, a) + \fB(7)\fP buf_type(str, std::ios_base::in | + std::ios_base::out, a) + \fB(8)\fP buf_type(str, mode) + \fB(9)\fP {t, mode, Allocator()} + \fB(10)\fP std::addressof(sb) {t, mode, a} + \fB(11)\fP {t, std::ios_base::in | + std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_iostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_stringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::stringstream::swap.3 b/man/std::stringstream::swap.3 deleted file mode 120000 index b4d190d2c..000000000 --- a/man/std::stringstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::swap.3 \ No newline at end of file diff --git a/man/std::stringstream::swap.3 b/man/std::stringstream::swap.3 new file mode 100644 index 000000000..cbf486e13 --- /dev/null +++ b/man/std::stringstream::swap.3 @@ -0,0 +1,39 @@ +.TH std::basic_stringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::swap \- std::basic_stringstream::swap + +.SH Synopsis + void swap( basic_stringstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_iostream::swap(other) and + rdbuf()->swap(*other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::stringstream::view.3 b/man/std::stringstream::view.3 new file mode 100644 index 000000000..bb7272455 --- /dev/null +++ b/man/std::stringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_stringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::view \- std::basic_stringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::strlen.3 b/man/std::strlen.3 index d90d9e06d..b8a4d8e60 100644 --- a/man/std::strlen.3 +++ b/man/std::strlen.3 @@ -1,9 +1,15 @@ -.TH std::strlen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strlen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strlen \- std::strlen + .SH Synopsis Defined in header std::size_t strlen( const char* str ); - Returns the length of the given byte string. + Returns the length of the given byte string, that is, the number of characters in a + character array whose first element is pointed to by str up to and not including the + first null character. The behavior is undefined if there is no null character in the + character array pointed to by str. .SH Parameters @@ -13,28 +19,43 @@ The length of the null-terminated string str. +.SH Possible implementation + + std::size_t strlen(const char* start) + { + // NB: start is not checked for nullptr! + const char* end = start; + while (*end != '\\0') + ++end; + return end - start; + } + .SH Example - + // Run this code #include #include - + int main() { - const char str[] = "How many characters contains this string?"; - - std::cout << "without null character: " << std::strlen(str) << '\\n' - << "with null character: " << sizeof(str) << '\\n'; + const char str[] = "dog cat\\0mouse"; + + std::cout << "without null character: " << std::strlen(str) << '\\n' + << "with null character: " << sizeof str << '\\n'; } .SH Output: - without null character: 41 - with null character: 42 + without null character: 7 + with null character: 14 .SH See also + wcslen returns the length of a wide string + \fI(function)\fP + mblen returns the number of bytes in the next multibyte character + \fI(function)\fP C documentation for strlen diff --git a/man/std::strncat.3 b/man/std::strncat.3 index 62ad1a004..4e5b3e51a 100644 --- a/man/std::strncat.3 +++ b/man/std::strncat.3 @@ -1,7 +1,10 @@ -.TH std::strncat 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strncat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strncat \- std::strncat + .SH Synopsis Defined in header - char *strncat( char *dest, const char *src, std::size_t count ); + char* strncat( char* dest, const char* src, std::size_t count ); Appends a byte string pointed to by src to a byte string pointed to by dest. At most count characters are copied. The resulting byte string is null-terminated. @@ -22,20 +25,25 @@ dest +.SH Notes + + Because std::strncat needs to seek to the end of dest on each call, it is + inefficient to concatenate many strings into one using std::strncat. + .SH Example - + // Run this code - #include #include - + #include + int main() { char str[50] = "Hello "; - char str2[50] = "World!"; + const char str2[50] = "World!"; std::strcat(str, str2); - std::strncat(str, " Goodbye World!", 3); + std::strncat(str, " Goodbye World!", 3); // may issue "truncated output" warning std::puts(str); } @@ -46,8 +54,8 @@ .SH See also strcat concatenates two strings - \fI(function)\fP + \fI(function)\fP strcpy copies one string to another - \fI(function)\fP + \fI(function)\fP C documentation for strncat diff --git a/man/std::strncmp.3 b/man/std::strncmp.3 index b8b92cfbb..619142f64 100644 --- a/man/std::strncmp.3 +++ b/man/std::strncmp.3 @@ -1,66 +1,85 @@ -.TH std::strncmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strncmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strncmp \- std::strncmp + .SH Synopsis Defined in header - int strncmp( const char* lhs, const char* rhs, size_t count ); + int strncmp( const char* lhs, const char* rhs, std::size_t count ); + + Compares at most count characters of two possibly null-terminated arrays. The + comparison is done lexicographically. Characters following the null character are + not compared. + + The sign of the result is the sign of the difference between the values of the first + pair of characters (both interpreted as unsigned char) that differ in the arrays + being compared. - Compares at most count characters of two null-terminated byte strings. The - comparison is done lexicographically. + The behavior is undefined when access occurs past the end of either array lhs or + rhs. The behavior is undefined when either lhs or rhs is the null pointer. .SH Parameters - lhs, rhs - pointers to the null-terminated byte strings to compare + lhs, rhs - pointers to the possibly null-terminated arrays to compare count - maximum number of characters to compare .SH Return value - Negative value if lhs is less than rhs. + Negative value if lhs appears before rhs in lexicographical order. - 0 if lhs is equal to rhs. + Zero if lhs and rhs compare equal, or if count is zero. - Positive value if lhs is greater than rhs. + Positive value if lhs appears after rhs in lexicographical order. + +.SH Notes + + This function is not locale-sensitive, unlike std::strcoll and std::strxfrm. .SH Example - + // Run this code - #include #include - + #include + + void demo(const char* lhs, const char* rhs, int sz) + { + const int rc = std::strncmp(lhs, rhs, sz); + if (rc < 0) + std::cout << "First " << sz << " chars of [" + << lhs << "] precede [" << rhs << "]\\n"; + else if (rc > 0) + std::cout << "First " << sz << " chars of [" + << lhs << "] follow [" << rhs << "]\\n"; + else + std::cout << "First " << sz << " chars of [" + << lhs << "] equal [" << rhs << "]\\n"; + } + int main() { - const char world[] = "Hello, world!"; - const char everybody[] = "Hello, everybody!"; - const char somebody[] = "Hello, somebody!"; - - // Compares 13 characters of "Hello, world!" and "Hello, everybody!" - std::cout << std::strncmp(world, everybody, sizeof(world) - 1) << '\\n'; - - // Compares 13 characters of "Hello, everybody!" and "Hello, world!" - std::cout << std::strncmp(everybody, world, sizeof(world) - 1) << '\\n'; - - // Compares 8 characters of "Hello, everybody!" and "Hello, world!" - std::cout << std::strncmp(everybody, world, sizeof("Hello, ") - 1) << '\\n'; - - // Compares 5 characters of "Hello, everybody!" and "Hello, somebody!" - // ^ ^ - std::cout << std::strncmp(&everybody[12], &somebody[11], sizeof("body!") - 1) << '\\n'; + demo("Hello, world!", "Hello, everybody!", 13); + demo("Hello, everybody!", "Hello, world!", 13); + demo("Hello, everybody!", "Hello, world!", 7); + demo("Hello, everybody!" + 12, "Hello, somebody!" + 11, 5); } .SH Output: - 1 - -1 - 0 - 0 + First 13 chars of [Hello, world!] follow [Hello, everybody!] + First 13 chars of [Hello, everybody!] precede [Hello, world!] + First 7 chars of [Hello, everybody!] equal [Hello, world!] + First 5 chars of [body!] equal [body!] .SH See also strcmp compares two strings - \fI(function)\fP + \fI(function)\fP + wcsncmp compares a certain amount of characters from two wide strings + \fI(function)\fP memcmp compares two buffers - \fI(function)\fP + \fI(function)\fP strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP C documentation for strncmp diff --git a/man/std::strncpy.3 b/man/std::strncpy.3 index 63809ad2b..fdfb4ea14 100644 --- a/man/std::strncpy.3 +++ b/man/std::strncpy.3 @@ -1,7 +1,10 @@ -.TH std::strncpy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strncpy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strncpy \- std::strncpy + .SH Synopsis Defined in header - char *strncpy( char *dest, const char *src, std::size_t count ); + char* strncpy( char* dest, const char* src, std::size_t count ); Copies at most count characters of the byte string pointed to by src (including the terminating null character) to character array pointed to by dest. @@ -27,25 +30,25 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { const char* src = "hi"; - char dest[6] = {'a', 'b', 'c', 'd', 'e', 'f'};; + char dest[6] = {'a', 'b', 'c', 'd', 'e', 'f'}; std::strncpy(dest, src, 5); - + std::cout << "The contents of dest are: "; - for (char c : dest) { - if (c) { + for (char c : dest) + { + if (c) std::cout << c << ' '; - } else { + else std::cout << "\\\\0" << ' '; - } } std::cout << '\\n'; } @@ -57,8 +60,8 @@ .SH See also strcpy copies one string to another - \fI(function)\fP + \fI(function)\fP memcpy copies one buffer to another - \fI(function)\fP + \fI(function)\fP C documentation for strncpy diff --git a/man/std::strong_order.3 b/man/std::strong_order.3 new file mode 100644 index 000000000..b1b79879e --- /dev/null +++ b/man/std::strong_order.3 @@ -0,0 +1,67 @@ +.TH std::strong_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strong_order \- std::strong_order + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ strong_order = /* unspecified \fI(since C++20)\fP + */; + + } + Call signature + template< class T, class U > + + requires /* see below */ + + constexpr std::strong_ordering strong_order( T&& t, U&& u ) + noexcept(/* see below */); + + Compares two values using 3-way comparison and produces a result of type + std::strong_ordering. + + Let t and u be expressions and T and U denote decltype((t)) and decltype((u)) + respectively, std::strong_order(t, u) is expression-equivalent to: + + * If std::is_same_v, std::decay_t> is true: + * std::strong_ordering(strong_order(t, u)), if it is a well-formed expression + with overload resolution performed in a context that does not include a + declaration of std::strong_order, + * otherwise, if T is a floating-point type: + * if std::numeric_limits::is_iec559 is true, performs the + ISO/IEC/IEEE 60559 totalOrder comparison of floating-point values and + returns that result as a value of type std::strong_ordering (note: + this comparison can distinguish between the positive and negative zero + and between the NaNs with different representations), + * otherwise, yields a value of type std::strong_ordering that is + consistent with the ordering observed by T's comparison operators, + * otherwise, std::strong_ordering(std::compare_three_way()(t, u)) if it is + well-formed. + * In all other cases, the expression is ill-formed, which can result in + substitution failure when it appears in the immediate context of a template + instantiation. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + strong_ordering the result type of 3-way comparison that supports all + (C++20) 6 operators and is substitutable + \fI(class)\fP + weak_order performs 3-way comparison and produces a result of + (C++20) type std::weak_ordering + (customization point object) + partial_order performs 3-way comparison and produces a result of + (C++20) type std::partial_ordering + (customization point object) + performs 3-way comparison and produces a result of + compare_strong_order_fallback type std::strong_ordering, even if operator<=> is + (C++20) unavailable + (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::strong_ordering.3 b/man/std::strong_ordering.3 new file mode 100644 index 000000000..59294fd54 --- /dev/null +++ b/man/std::strong_ordering.3 @@ -0,0 +1,267 @@ +.TH std::strong_ordering 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strong_ordering \- std::strong_ordering + +.SH Synopsis + Defined in header + class strong_ordering; \fI(since C++20)\fP + + The class type std::strong_ordering is the result type of a three-way comparison + that: + + * Admits all six relational operators (==, !=, <, <=, >, >=). + * Implies substitutability: if a is equivalent to b, f(a) is also equivalent to + f(b), where f denotes a function that reads only comparison-salient state that + is accessible via the argument's public const members. In other words, + equivalent values are indistinguishable. + * Does not allow incomparable values: exactly one of a < b, a == b, or a > b must + be true. + +.SH Constants + + The type std::strong_ordering has four valid values, implemented as const static + data members of its type: + + Member constant Definition + less(inline constexpr) a valid value of the type std::strong_ordering + \fB[static]\fP indicating less-than (ordered before) relationship + \fI(public static member constant)\fP + a valid value of the type std::strong_ordering + equivalent(inline constexpr) indicating equivalence (neither ordered before nor + \fB[static]\fP ordered after), the same as equal + \fI(public static member constant)\fP + a valid value of the type std::strong_ordering + equal(inline constexpr) indicating equivalence (neither ordered before nor + \fB[static]\fP ordered after), the same as equivalent + \fI(public static member constant)\fP + greater(inline constexpr) a valid value of the type std::strong_ordering + \fB[static]\fP indicating greater-than (ordered after) relationship + \fI(public static member constant)\fP + +.SH Conversions + + std::strong_ordering is the strongest of the three comparison categories: it is not + implicitly-convertible from any other category and is implicitly-convertible to the + other two. + + operator partial_ordering implicit conversion to std::partial_ordering + \fI(public member function)\fP + +std::strong_ordering::operator partial_ordering + + constexpr operator partial_ordering() const noexcept; + +.SH Return value + + std::partial_ordering::less if v is less, std::partial_ordering::greater if v is + greater, std::partial_ordering::equivalent if v is equal or equivalent. + + operator weak_ordering implicit conversion to std::weak_ordering + \fI(public member function)\fP + +std::strong_ordering::operator weak_ordering + + constexpr operator weak_ordering() const noexcept; + +.SH Return value + + std::weak_ordering::less if v is less, std::weak_ordering::greater if v is greater, + std::weak_ordering::equivalent if v is equal or equivalent. + +.SH Comparisons + + Comparison operators are defined between values of this type and literal 0. This + supports the expressions a <=> b == 0 or a <=> b < 0 that can be used to convert the + result of a three-way comparison operator to a boolean relationship; see std::is_eq, + std::is_lt, etc. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::strong_ordering is an + associated class of the arguments. + + The behavior of a program that attempts to compare a strong_ordering with anything + other than the integer literal 0 is undefined. + + operator== + operator< + operator> compares with zero or a strong_ordering + operator<= \fI(function)\fP + operator>= + operator<=> + +operator== + + friend constexpr bool \fB(1)\fP + operator==( strong_ordering v, /*unspecified*/ u ) noexcept; + friend constexpr bool \fB(2)\fP + operator==( strong_ordering v, strong_ordering w ) noexcept = default; + +.SH Parameters + + v, w - std::strong_ordering values to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is equivalent or equal, false if v is less or greater + 2) true if both parameters hold the same value, false otherwise. Note that equal is + the same as equivalent. + +operator< + + friend constexpr bool operator<( strong_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator<( /*unspecified*/ u, strong_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::strong_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is less, and false if v is greater, equivalent, or equal + 2) true if v is greater, and false if v is less, equivalent, or equal + +operator<= + + friend constexpr bool operator<=( strong_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator<=( /*unspecified*/ u, strong_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::strong_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is less, equivalent, or equal, and false if v is greater + 2) true if v is greater, equivalent, or equal, and false if v is less + +operator> + + friend constexpr bool operator>( strong_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator>( /*unspecified*/ u, strong_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::strong_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is greater, and false if v is less, equivalent, or equal + 2) true if v is less, and false if v is greater, equivalent, or equal + +operator>= + + friend constexpr bool operator>=( strong_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator>=( /*unspecified*/ u, strong_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::strong_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is greater, equivalent, or equal, and false if v is less + 2) true if v is less, equivalent, or equal, and false if v is greater + +operator<=> + + friend constexpr strong_ordering \fB(1)\fP + operator<=>( strong_ordering v, /*unspecified*/ u ) noexcept; + friend constexpr strong_ordering \fB(2)\fP + operator<=>( /*unspecified*/ u, strong_ordering v ) noexcept; + +.SH Parameters + + v - a std::strong_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) v. + 2) greater if v is less, less if v is greater, otherwise v. + +.SH Example + + +// Run this code + + #include + #include + + struct Point + { + int x{}, y{}; + + friend constexpr std::strong_ordering operator<=>(Point lhs, Point rhs) + { + if (lhs.x < rhs.x or (lhs.x == rhs.x and lhs.y < rhs.y)) + return std::strong_ordering::less; + if (lhs.x > rhs.x or (lhs.x == rhs.x and lhs.y > rhs.y)) + return std::strong_ordering::greater; + return std::strong_ordering::equivalent; + } + + friend std::ostream& operator<<(std::ostream& os, Point s) + { + return os << '(' << s.x << ',' << s.y << ')'; + } + }; + + void print_three_way_comparison(const auto& p, const auto& q) + { + const auto cmp{p <=> q}; + std::cout << p + << (cmp < 0 ? " < " : cmp > 0 ? " > " : " == " ) // compares with 0 + << q << '\\n'; + } + + void print_two_way_comparison(const auto& p, const auto& q) + { + std::cout << p + << (p < q ? " < " : p > q ? " > " : " == ") // compares p and q + << q << '\\n'; + } + + int main() + { + const Point p1{0, 1}, p2{0, 1}, p3{0, 2}; + + print_three_way_comparison(p1, p2); + print_two_way_comparison(p1, p2); + + print_three_way_comparison(p2, p3); + print_two_way_comparison(p2, p3); + + print_three_way_comparison(p3, p2); + print_two_way_comparison(p3, p2); + } + +.SH Output: + + (0,1) == (0,1) + (0,1) == (0,1) + (0,1) < (0,2) + (0,1) < (0,2) + (0,2) > (0,1) + (0,2) > (0,1) + +.SH See also + + weak_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is not substitutable + \fI(class)\fP + partial_ordering the result type of 3-way comparison that supports all 6 operators, + (C++20) is not substitutable, and allows incomparable values + \fI(class)\fP diff --git a/man/std::strpbrk.3 b/man/std::strpbrk.3 index 6730891fe..8bf8b12cc 100644 --- a/man/std::strpbrk.3 +++ b/man/std::strpbrk.3 @@ -1,60 +1,79 @@ -.TH std::strpbrk 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strpbrk 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strpbrk \- std::strpbrk + .SH Synopsis Defined in header - const char* strpbrk( const char* dest, const char* str ); - char* strpbrk( char* dest, const char* str ); + const char* strpbrk( const char* dest, const char* breakset ); + char* strpbrk( char* dest, const char* breakset ); - Finds the first character in byte string pointed to by dest, that is also in byte - string pointed to by str. + Scans the null-terminated byte string pointed to by dest for any character from the + null-terminated byte string pointed to by breakset, and returns a pointer to that + character. .SH Parameters - dest - pointer to the null-terminated byte string to be analyzed - str - pointer to the null-terminated byte string that contains the characters to - search for + dest - pointer to the null-terminated byte string to be analyzed + breakset - pointer to the null-terminated byte string that contains the characters + to search for .SH Return value - Pointer to the first character in dest, that is also in str, or NULL if no such - character exists. + Pointer to the first character in dest, that is also in breakset, or null pointer if + no such character exists. + +.SH Notes + + The name stands for "string pointer break", because it returns a pointer to the + first of the separator ("break") characters. .SH Example - + // Run this code - #include #include - + #include + #include + int main() { - char* input = "hello world friend of mine"; - char* space = " "; - char* pos = input; - int word_counter = 0; - - do { - pos = std::strpbrk(pos, space); - word_counter++; - pos ? pos++ : pos; - std::printf("%d\\n", word_counter); - } while (pos != NULL); - }; + const char* str = "hello world, friend of mine!"; + const char* sep = " ,!"; + + unsigned int cnt = 0; + do + { + str = std::strpbrk(str, sep); // find separator + std::cout << std::quoted(str) << '\\n'; + if (str) + str += std::strspn(str, sep); // skip separator + ++cnt; // increment word count + } while (str && *str); + + std::cout << "There are " << cnt << " words\\n"; + } .SH Output: - 1 - 2 - 3 - 4 - 5 + " world, friend of mine!" + ", friend of mine!" + " of mine!" + " mine!" + "!" + There are 5 words .SH See also returns the length of the maximum initial segment that consists strcspn of only the characters not found in another byte string - \fI(function)\fP + \fI(function)\fP + strtok finds the next token in a byte string + \fI(function)\fP strchr finds the first occurrence of a character - \fI(function)\fP + \fI(function)\fP + finds the first location of any wide character in one wide string, in + wcspbrk another wide string + \fI(function)\fP C documentation for strpbrk diff --git a/man/std::strrchr.3 b/man/std::strrchr.3 index 665a7ab03..71dead662 100644 --- a/man/std::strrchr.3 +++ b/man/std::strrchr.3 @@ -1,4 +1,7 @@ -.TH std::strrchr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strrchr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strrchr \- std::strrchr + .SH Synopsis Defined in header const char* strrchr( const char* str, int ch ); @@ -20,18 +23,18 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { char input[] = "/home/user/hello.c"; char* output = std::strrchr(input, '/'); - if(output) - std::cout << output+1 << '\\n'; + if (output) + std::cout << output + 1 << '\\n'; } .SH Output: @@ -41,10 +44,10 @@ .SH See also strchr finds the first occurrence of a character - \fI(function)\fP + \fI(function)\fP wcsrchr finds the last occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP rfind find the last occurrence of a substring - \fI(public member function of std::basic_string)\fP + \fI(public member function of std::basic_string)\fP C documentation for strrchr diff --git a/man/std::strspn.3 b/man/std::strspn.3 index 75a799d74..002c936ef 100644 --- a/man/std::strspn.3 +++ b/man/std::strspn.3 @@ -1,10 +1,14 @@ -.TH std::strspn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strspn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strspn \- std::strspn + .SH Synopsis Defined in header - size_t strspn( const char *dest, const char *src ); + size_t strspn( const char* dest, const char* src ); - Returns the length of the maximum initial segment of the byte string pointed to by - dest, that consists of only the characters found in byte string pointed to by src. + Returns the length of the maximum initial segment (span) of the byte string pointed + to by dest, that consists of only the characters found in byte string pointed to by + src. .SH Parameters @@ -15,23 +19,42 @@ .SH Return value The length of the maximum initial segment that contains only characters from byte - string pointed to by src + string pointed to by src. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + const char* low_alpha = "qwertyuiopasdfghjklzxcvbnm"; + + int main() + { + std::string s = "abcde312$#@"; + + std::size_t spnsz = std::strspn(s.c_str(), low_alpha); + std::cout << "After skipping initial lowercase letters from '" << s + << "'\\nThe remainder is '" << s.substr(spnsz) << "'\\n"; + } + +.SH Output: + + After skipping initial lowercase letters from 'abcde312$#@' + The remainder is '312$#@' .SH See also returns the length of the maximum initial segment that consists strcspn of only the characters not found in another byte string - \fI(function)\fP - strpbrk finds the first location of any character in one string, in another string - \fI(function)\fP + \fI(function)\fP + returns the length of the maximum initial segment that consists + wcsspn of only the wide characters found in another wide string + \fI(function)\fP + strpbrk finds the first location of any character from a set of separators + \fI(function)\fP C documentation for strspn - -.SH Category: - - * Todo no example diff --git a/man/std::strstr.3 b/man/std::strstr.3 index 48c91a866..73565353c 100644 --- a/man/std::strstr.3 +++ b/man/std::strstr.3 @@ -1,40 +1,45 @@ -.TH std::strstr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstr \- std::strstr + .SH Synopsis Defined in header - const char* strstr( const char* str, const char* target ); - char* strstr( char* str, const char* target ); + const char* strstr( const char* haystack, const char* needle ); + char* strstr( char* haystack, const char* needle ); - Finds the first occurrence of the byte string target in the byte string pointed to - by str. The terminating null characters are not compared. + Finds the first occurrence of the byte string needle in the byte string pointed to + by haystack. The terminating null characters are not compared. .SH Parameters - str - pointer to the null-terminated byte string to examine - target - pointer to the null-terminated byte string to search for + haystack - pointer to the null-terminated byte string to examine + needle - pointer to the null-terminated byte string to search for .SH Return value - Pointer to the first character of the found substring in str, or NULL if no such - character is found. If target points to an empty string, str is returned. + Pointer to the first character of the found substring in haystack, or a null pointer + if no such character is found. If needle points to an empty string, haystack is + returned. .SH Example - + // Run this code - #include #include - + #include + int main() { - const char *str = "Try not. Do, or do not. There is no try."; - const char *target = "not"; - const char *result = str; - - while ((result = std::strstr(result, target)) != NULL) { + const char* str = "Try not. Do, or do not. There is no try."; + const char* target = "not"; + const char* result = str; + + while ((result = std::strstr(result, target))) + { std::cout << "Found '" << target << "' starting at '" << result << "'\\n"; - + // Increment result, otherwise we'll find target at the same location ++result; } @@ -47,13 +52,13 @@ .SH See also - find find characters in the string - \fI(public member function of std::basic_string)\fP + find finds the first occurrence of the given substring + \fI(public member function of std::basic_string)\fP wcsstr finds the first occurrence of a wide string within another wide string - \fI(function)\fP + \fI(function)\fP strchr finds the first occurrence of a character - \fI(function)\fP + \fI(function)\fP strrchr finds the last occurrence of a character - \fI(function)\fP + \fI(function)\fP C documentation for strstr diff --git a/man/std::strstream.3 b/man/std::strstream.3 index b312c32ec..672ecc986 100644 --- a/man/std::strstream.3 +++ b/man/std::strstream.3 @@ -1,7 +1,11 @@ -.TH std::strstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream \- std::strstream + .SH Synopsis Defined in header - class strstream : public std::iostream \fB(deprecated)\fP + class strstream : public std::iostream (deprecated in C++98) + (removed in C++26) The class strstream implements input and output operations on array-backed streams. It essentially wraps a raw array I/O device implementation (std::strstreambuf) into @@ -15,23 +19,27 @@ After any call to str(), a call to freeze(false) is required to allow the destructor to deallocate the buffer as necessary. - strstream has been deprecated since C++98, std::stringstream and - boost::iostreams::array are the recommended replacements. + Before any call to str() that uses the result as a C-string, the buffer must be + null-terminated, typically with std::ends. + + strstream has been deprecated since C++98 and removed since C++26. std::stringstream + , std::spanstream + (since C++23), and boost::iostreams::array are the recommended replacements. .SH Member functions - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function)\fP - destructor destructs a strstream, optionally deallocating the buffer - \fB[virtual]\fP \fI(virtual public member function)\fP + constructor constructs a strstream object, optionally allocating the buffer + \fI(public member function)\fP + destructor destructs a strstream object, optionally deallocating the buffer + \fB[virtual]\fP \fI(virtual public member function)\fP rdbuf obtains a pointer to the associated strstreambuf - \fI(public member function)\fP + \fI(public member function)\fP str accesses the output buffer - \fI(public member function)\fP + \fI(public member function)\fP freeze disables/enables automatic reallocation - \fI(public member function)\fP + \fI(public member function)\fP pcount obtains the number of characters written - \fI(public member function)\fP + \fI(public member function)\fP Inherited from std::basic_istream @@ -39,66 +47,66 @@ Inherited from std::basic_istream .SH Formatted input operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Unformatted input get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP peek reads the next character without extracting it - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP getline extracts characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP read extracts blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP readsome extracts already available blocks of characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP returns number of characters extracted by last unformatted input gcount operation - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Positioning tellg returns the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP seekg sets the input position indicator - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Miscellaneous sync synchronizes with the underlying storage device - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for input operations - \fI(public member class of std::basic_istream)\fP + \fI(public member class of std::basic_istream)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -111,45 +119,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -157,40 +165,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -198,76 +206,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::strstream::freeze.3 b/man/std::strstream::freeze.3 index feaa765c6..ab84587f8 100644 --- a/man/std::strstream::freeze.3 +++ b/man/std::strstream::freeze.3 @@ -1,16 +1,20 @@ -.TH std::strstream::freeze 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream::freeze 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream::freeze \- std::strstream::freeze + .SH Synopsis - void freeze(bool flag = true); + void freeze( bool flag = true ); (deprecated in C++98) + (removed in C++26) If the stream is using a dynamically-allocated array for output, disables (flag == true) or enables (flag == false) automatic allocation/deallocation of the buffer. - Effectively calls rdbuf()->pcount() + Effectively calls rdbuf()->freeze(flag). .SH Notes After a call to str(), dynamic streams become frozen automatically. A call to freeze(false) is required before exiting the scope in which this strstream object - was created. otherwise the destructor will leak memory. Also, additional output to a + was created, otherwise the destructor will leak memory. Also, additional output to a frozen stream may be truncated once it reaches the end of the allocated buffer. .SH Parameters @@ -23,32 +27,42 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::strstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; - std::cout << "The output stream contains \\"" << dyn.str() << "\\"\\n"; - - dyn << "Test: " << 1.23; - std::cout << "The output stream contains \\"" << dyn.str() << "\\"\\n"; + dyn << "Test: " << 1.23; // note: no std::ends to demonstrate appending + std::cout << "The output stream contains \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; // the stream is now frozen due to str() - dyn << " More text"; - std::cout << "The output stream contains \\"" << dyn.str() << "\\"\\n"; - dyn.freeze(false); + dyn << " More text"; // output to a frozen stream may be truncated + std::cout << "The output stream contains \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; + dyn.freeze(false); // freeze(false) must be called or the destructor will leak + + std::strstream dyn2; // dynamically-allocated output buffer + dyn2 << "Test: " << 1.23; // note: no std::ends + std::cout << "The output stream contains \\""; + std::cout.write(dyn2.str(), dyn2.pcount()) << "\\"\\n"; + dyn2.freeze(false); // unfreeze the stream after str() + dyn2 << " More text" << std::ends; // output will not be truncated (buffer grows) + std::cout << "The output stream contains \\"" << dyn2.str() << "\\"\\n"; + dyn2.freeze(false); // freeze(false) must be called or the destructor will leak } .SH Possible output: The output stream contains "Test: 1.23" The output stream contains "Test: 1.23 More " + The output stream contains "Test: 1.23" + The output stream contains "Test: 1.23 More text" .SH See also freeze sets/clears the frozen state of the buffer - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP diff --git a/man/std::strstream::pcount.3 b/man/std::strstream::pcount.3 index fa818ce13..e2900c166 100644 --- a/man/std::strstream::pcount.3 +++ b/man/std::strstream::pcount.3 @@ -1,9 +1,13 @@ -.TH std::strstream::pcount 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream::pcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream::pcount \- std::strstream::pcount + .SH Synopsis - int pcount() const; + int pcount() const; (deprecated in C++98) + (removed in C++26) Returns the number of characters that were output in the put area of the associated - std::strstreambuf. Effectively calls rdbuf()->pcount() + std::strstreambuf. Effectively calls rdbuf()->pcount(). .SH Parameters @@ -15,20 +19,20 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::strstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; + dyn << "Test: " << 1.23 << std::ends; std::cout << "The size of the output is " << dyn.pcount() << " and it holds \\"" << dyn.str() << "\\"\\n"; dyn.freeze(false); - + char buf[10]; std::strstream user(buf, 10); // user-provided output buffer user << 1.23; // note: no std::ends @@ -38,11 +42,11 @@ .SH Output: - The size of the output is 10 and it holds "Test: 1.23" + The size of the output is 11 and it holds "Test: 1.23" 1.23 .SH See also returns the next pointer minus the beginning pointer in the output sequence: pcount the number of characters written - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP diff --git a/man/std::strstream::rdbuf.3 b/man/std::strstream::rdbuf.3 index 6915a791f..20a894d37 100644 --- a/man/std::strstream::rdbuf.3 +++ b/man/std::strstream::rdbuf.3 @@ -1,9 +1,13 @@ -.TH std::strstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream::rdbuf \- std::strstream::rdbuf + .SH Synopsis - strstreambuf* rdbuf() const; + strstreambuf* rdbuf() const; (deprecated in C++98) + (removed in C++26) Returns a pointer to the associated std::strstreambuf, casting away its constness - (despite the const qualifier on the member function) + (despite the const qualifier on the member function). .SH Parameters @@ -11,16 +15,17 @@ .SH Return value - Pointer to the associated std::strsteambuf, with constness cast away. + Pointer to the associated std::strstreambuf, with constness cast away. .SH Example - + // Run this code #include + int main() { - const std::strstream buf; + const std::strstream buf; std::strstreambuf* ptr = buf.rdbuf(); } diff --git a/man/std::strstream::str.3 b/man/std::strstream::str.3 index 7bfad1e00..8be1059c1 100644 --- a/man/std::strstream::str.3 +++ b/man/std::strstream::str.3 @@ -1,16 +1,13 @@ -.TH std::strstream::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream::str \- std::strstream::str + .SH Synopsis - char* str(); + char* str(); (deprecated in C++98) + (removed in C++26) Returns the pointer to the beginning of the buffer, after freezing it. Effectively - calls rdbuf()->str() - -.SH Notes - - After a call to str(), dynamic streams become frozen. A call to freeze(false) is - required before exiting the scope in which this strstream object was created. - otherwise the destructor will leak memory. Also, additional output to a frozen - stream may be truncated once it reaches the end of the allocated buffer. + calls rdbuf()->str(). .SH Parameters @@ -18,28 +15,40 @@ .SH Return value - Pointer to the beginning of the buffer in the associated std::strsteambuf or NULL if - no buffer is available. + Pointer to the beginning of the buffer in the associated std::strstreambuf or a null + pointer if no buffer is available. + +.SH Notes + + Before a call to str() that uses the result as a C-string, the stream buffer must be + null-terminated. Regular output such as with stream << 1.2 does not store a null + terminator, it must be appended explicitly, typically with the manipulator + std::ends. + + After a call to str(), dynamic streams become frozen. A call to freeze(false) is + required before exiting the scope in which this strstream object was created. + otherwise the destructor will leak memory. Also, additional output to a frozen + stream may be truncated once it reaches the end of the allocated buffer, which may + leave the buffer not null-terminated. .SH Example - + // Run this code - #include #include - + #include + int main() { std::strstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; - std::cout << "The output stream holds \\"" << dyn.str() << "\\"\\n"; - - dyn << "Test: " << 1.23; - std::cout << "The output stream holds \\"" << dyn.str() << "\\"\\n"; + dyn << "Test: " << 1.23; // not adding std::ends to demonstrate append behavior + std::cout << "The output stream holds \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; // the stream is now frozen due to str() - dyn << " More text"; - std::cout << "The output stream holds \\"" << dyn.str() << "\\"\\n"; + dyn << " More text" << std::ends; + std::cout << "The output stream holds \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; dyn.freeze(false); } @@ -51,4 +60,4 @@ .SH See also str marks the buffer frozen and returns the beginning pointer of the input sequence - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP diff --git a/man/std::strstream::strstream.3 b/man/std::strstream::strstream.3 index 79a9f5b50..aebec45b9 100644 --- a/man/std::strstream::strstream.3 +++ b/man/std::strstream::strstream.3 @@ -1,8 +1,13 @@ -.TH std::strstream::strstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream::strstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream::strstream \- std::strstream::strstream + .SH Synopsis - strstream(); \fB(1)\fP - strstream(char* s, int n, std::ios_base::openmode mode \fB(2)\fP - = std::ios_base::in | std::ios_base::out); + strstream(); \fB(1)\fP (deprecated in C++98) + (removed in C++26) + strstream( char* s, int n, std::ios_base::openmode mode = (deprecated in C++98) + std::ios_base::in | \fB(2)\fP (removed in C++26) + std::ios_base::out ); Constructs new input/output strstream and its underlying std::strstreambuf. @@ -12,13 +17,13 @@ 2) Initialized the base class with the address of the underlying std::strstreambuf member, which is initialized in one of the two possible ways, both of which use a user-provided fixed-size array: - a) if the app bit is not set in mode, constructs the buffer by calling - strstreambuf(s, n, s). The behavior is undefined if there are less than n elements - in the array whose first element is pointed to by s - b) if the app bit is set in mode, constructs the buffer by calling strstreambuf(s, - n, s + std::strlen(s)). The behavior is undefined if there are less than n elements - in the array whose first element is pointed to by s or if the array does not contain - a valid null-terminated character sequence. + a) if (mode & app) == 0 (the app bit is not set in mode), constructs the buffer by + calling strstreambuf(s, n, s). The behavior is undefined if there are less than n + elements in the array whose first element is pointed to by s. + b) if (mode & app) != 0 (the app bit is set in mode), constructs the buffer by + calling strstreambuf(s, n, s + std::strlen(s)). The behavior is undefined if there + are less than n elements in the array whose first element is pointed to by s or if + the array does not contain a valid null-terminated character sequence. .SH Parameters @@ -27,60 +32,73 @@ specifies stream open mode. It is a bitmask type, the following constants are defined (although only app is used): - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Example - + // Run this code #include + #include #include - + int main() { // dynamic buffer - std::strstream s1; // dynamic buffer + std::strstream s1; s1 << 1 << ' ' << 3.14 << " example" << std::ends; - std::cout << "buffer holds '" << s1.str() << "'\\n"; + std::cout << "Buffer holds: '" << s1.str() << "'\\n"; s1.freeze(false); - - int n; double d; + + int n; + double d; std::string w; s1 >> n >> d >> w; std::cout << "Read back: n = " << n - << " d = " << d - << " w = '" << w << "'\\n"; - + << ", d = " << d + << ", w = '" << w << "'\\n"; + // static buffer char arr[20] = "-1 -3.14 "; std::strstream s2(arr, sizeof arr, std::ios_base::app); s2 << "another" << std::ends; - std::cout << "buffer holds: '" << s2.str() << "'\\n"; + std::cout << "Buffer holds: '" << s2.str() << "'\\n"; s2 >> n >> d >> w; std::cout << "Read back: n = " << n - << " d = " << d - << " w = '" << w << "'\\n"; + << ", d = " << d + << ", w = '" << w << "'\\n"; } .SH Output: - buffer holds '1 3.14 example' - Read back: n = 1 d = 3.14 w = 'example' - buffer holds: '-1 -3.14 another' - Read back: n = -1 d = -3.14 w = 'another' + Buffer holds: '1 3.14 example' + Read back: n = 1, d = 3.14, w = 'example' + Buffer holds: '-1 -3.14 another' + Read back: n = -1, d = -3.14, w = 'another' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(2)\fP only considered the case considers cases (mode & + LWG 115 C++98 mode & app == 0 (== has higher precedence app) == 0 + than &) and (mode & app) != 0 .SH See also constructor constructs a strstreambuf object - \fI(public member function of std::strstreambuf)\fP - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function of std::istrstream)\fP - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function of std::ostrstream)\fP + \fI(public member function of std::strstreambuf)\fP + constructor constructs an istrstream object, optionally allocating the buffer + \fI(public member function of std::istrstream)\fP + constructor constructs an ostrstream object, optionally allocating the buffer + \fI(public member function of std::ostrstream)\fP diff --git a/man/std::strstream::~strstream.3 b/man/std::strstream::~strstream.3 index 41e54136f..784189789 100644 --- a/man/std::strstream::~strstream.3 +++ b/man/std::strstream::~strstream.3 @@ -1,6 +1,10 @@ -.TH std::strstream::~strstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstream::~strstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstream::~strstream \- std::strstream::~strstream + .SH Synopsis - virtual ~strstream(); + virtual ~strstream(); (deprecated in C++98) + (removed in C++26) Destroys a std::strstream object, which also destroys the member std::strstreambuf, which may call the deallocation function if the underlying buffer was @@ -17,28 +21,28 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { { std::ostrstream s; // dynamic buffer - s << 1.23; + s << 1.23 << std::ends; std::cout << s.str() << '\\n'; s.freeze(false); } // destructor called, buffer deallocated - + { std::ostrstream s; - s << 1.23; + s << 1.23 << std::ends; std::cout << s.str() << '\\n'; - // buf.freeze(false); + // buf.freeze(false); } // destructor called, memory leaked - + { std::istrstream s("1.23"); // constant buffer double d; diff --git a/man/std::strstreambuf.3 b/man/std::strstreambuf.3 index c970ad03f..3cf55cc49 100644 --- a/man/std::strstreambuf.3 +++ b/man/std::strstreambuf.3 @@ -1,12 +1,16 @@ -.TH std::strstreambuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf \- std::strstreambuf + .SH Synopsis Defined in header - class strstreambuf : public std::basic_streambuf \fB(deprecated)\fP + class strstreambuf : public std::basic_streambuf (deprecated in C++98) + (removed in C++26) std::strstreambuf is a std::basic_streambuf whose associated character sequence is a - character array, which may be constant (e.g. a string literal), modifyable but not + character array, which may be constant (e.g. a string literal), modifiable but not dynamic (e.g. a stack-allocated array), or dynamic, in which case the - std::strstreambuf may be allowed to reallocate the array as necessary to accomodate + std::strstreambuf may be allowed to reallocate the array as necessary to accommodate output (e.g. by calling delete[] and new[] or user-provided functions). Typical implementation of a std::strstreambuf holds four private data members: @@ -26,39 +30,43 @@ is required to allow the strstreambuf destructor to deallocate the buffer when necessary. + strstreambuf has been deprecated since C++98 and removed since C++26 + . The recommended replacement is std::spanbuf + (since C++23). + .SH Member functions .SH Public member functions constructor constructs a strstreambuf object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs a strstreambuf object, optionally deallocating the character \fB[virtual]\fP array - \fI(virtual public member function)\fP + \fI(virtual public member function)\fP freeze sets/clears the frozen state of the buffer - \fI(public member function)\fP + \fI(public member function)\fP marks the buffer frozen and returns the beginning pointer of the input str sequence - \fI(public member function)\fP + \fI(public member function)\fP returns the next pointer minus the beginning pointer in the output pcount sequence: the number of characters written - \fI(public member function)\fP + \fI(public member function)\fP .SH Protected member functions underflow reads a character from the input sequence without advancing the next \fB[virtual]\fP pointer - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP pbackfail backs out the input sequence to unget a character - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP overflow appends a character to the output sequence, may reallocate or \fB[virtual]\fP initially allocate the buffer if dynamic and not frozen - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP setbuf attempts to replace the controlled character sequence with an array - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP seekoff repositions the next pointer in the input sequence, output sequence, \fB[virtual]\fP or both, using relative addressing - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP seekpos repositions the next pointer in the input sequence, output sequence, \fB[virtual]\fP or both using absolute addressing - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP Inherited from std::basic_streambuf @@ -66,111 +74,140 @@ Inherited from std::basic_streambuf Member type Definition char_type CharT - traits_type Traits + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. int_type Traits::int_type pos_type Traits::pos_type off_type Traits::off_type .SH Member functions - destructor destructs the basic_streambuf object - \fB[virtual]\fP \fI(virtual public member function of std::basic_streambuf)\fP + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) .SH Locales - pubimbue invokes imbue() - \fI(public member function of std::basic_streambuf)\fP - getloc obtains a copy of the associated locale - \fI(public member function of std::basic_streambuf)\fP + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + .SH Positioning - pubsetbuf invokes setbuf() - \fI(public member function of std::basic_streambuf)\fP - pubseekoff invokes seekoff() - \fI(public member function of std::basic_streambuf)\fP - pubseekpos invokes seekpos() - \fI(public member function of std::basic_streambuf)\fP - pubsync invokes sync() - \fI(public member function of std::basic_streambuf)\fP + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + .SH Get area - in_avail obtains the number of characters immediately available in the get area - \fI(public member function of std::basic_streambuf)\fP - advances the input sequence, then reads one character without advancing - snextc again - \fI(public member function of std::basic_streambuf)\fP - sbumpc reads one character from the input sequence and advances the sequence - \fI(public member function of std::basic_streambuf)\fP - stossc advances the input sequence as if by calling sbumpc() and discarding - \fB(deprecated)\fP the result - \fI(public member function)\fP - reads one character from the input sequence without advancing the - sgetc sequence - \fI(public member function of std::basic_streambuf)\fP - sgetn invokes xsgetn() - \fI(public member function of std::basic_streambuf)\fP + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + .SH Put area - sputc writes one character to the put area and advances the next pointer - \fI(public member function of std::basic_streambuf)\fP - sputn invokes xsputn() - \fI(public member function of std::basic_streambuf)\fP + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + .SH Putback - sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP - sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + .SH Protected member functions constructor constructs a basic_streambuf object - \fI(protected member function)\fP + \fI(protected member function)\fP operator= replaces a basic_streambuf object - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP swap swaps two basic_streambuf objects - \fI(C++11)\fP \fI(protected member function)\fP + \fI(C++11)\fP \fI(protected member function)\fP .SH Locales imbue changes the associated locale - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) .SH Positioning setbuf replaces the buffer with user-defined array, if permitted - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both, using relative addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekpos repositions the next pointer in the input sequence, output sequence, - \fB[virtual]\fP or both using absolute addressing - \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) sync synchronizes the buffers with the associated character sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) .SH Get area - showmanyc obtains the number of characters available for input in the associated - \fB[virtual]\fP input sequence, if known - \fI(virtual protected member function of std::basic_streambuf)\fP + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP - uflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP and advances the next pointer - \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) xsgetn reads multiple characters from the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) eback returns a pointer to the beginning, current character and the end of gptr the get area - egptr \fI(protected member function)\fP + egptr \fI(protected member function)\fP gbump advances the next pointer in the input sequence - \fI(protected member function)\fP + \fI(protected member function)\fP repositions the beginning, next, and end pointers of the input setg sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Put area xsputn writes multiple characters to the output sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) pbase returns a pointer to the beginning, current character and the end of pptr the put area - epptr \fI(protected member function)\fP + epptr \fI(protected member function)\fP pbump advances the next pointer of the output sequence - \fI(protected member function)\fP + \fI(protected member function)\fP repositions the beginning, next, and end pointers of the output setp sequence - \fI(protected member function)\fP + \fI(protected member function)\fP .SH Putback - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function of std::basic_streambuf)\fP + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) diff --git a/man/std::strstreambuf::freeze.3 b/man/std::strstreambuf::freeze.3 index 3c86e6b1d..acf26505c 100644 --- a/man/std::strstreambuf::freeze.3 +++ b/man/std::strstreambuf::freeze.3 @@ -1,6 +1,10 @@ -.TH std::strstreambuf::freeze 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::freeze 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::freeze \- std::strstreambuf::freeze + .SH Synopsis - void freeze(bool freezefl = true); + void freeze( bool freezefl = true ); (deprecated in C++98) + (removed in C++26) If the buffer uses dynamic allocation, sets the frozen status of the stream to freezefl. @@ -24,37 +28,39 @@ .SH Example - in this example, initial allocation of the underlying array was for 16 bytes + In this example, initial allocation of the underlying array was for 16 bytes. + - // Run this code - #include #include - + #include + int main() { { std::strstream dyn; // dynamically-allocated read/write buffer - dyn << "Test: " << 1.23; - std::cout << "dynamic buffer holds " - << dyn.pcount() << " characters: '" << dyn.str() << "'\\n"; + dyn << "Test: " << 1.23; // note: no std::ends to demonstrate append behavior + std::cout << "dynamic buffer holds " << dyn.pcount() << " characters: '"; + std::cout.write(dyn.str(), dyn.pcount()) << "'\\n"; // the buffer is now frozen, further output will not make the buffer grow - dyn << "more output, hopefully enough to run out of the allocated space"; + dyn << "more output, hopefully enough to run out of the allocated space" + << std::ends; std::cout << "After more output, it holds " << dyn.pcount() << " characters: '" << dyn.str() << "'\\n"; dyn.freeze(false); // unfreeze before destructor } // memory freed by the destructor - + { char arr[20]; std::ostrstream st(arr, sizeof arr); // fixed-size buffer - st << 1.23; + st << 1.23; // note: no std::ends to demonstrate append behavior std::cout << "static buffer holds " << st.pcount() << " characters: '"; std::cout.write(st.str(), st.pcount()); std::cout << "'\\n"; - st << "more output, hopefully enough to run out of the allocated space"; + st << "more output, hopefully enough to run out of the allocated space" + << std::ends; std::cout << "static buffer holds " << st.pcount() << " characters: '"; std::cout.write(st.str(), st.pcount()); @@ -72,12 +78,12 @@ .SH See also freeze disables/enables automatic reallocation - \fI(public member function of std::strstream)\fP + \fI(public member function of std::strstream)\fP freeze disables/enables automatic reallocation - \fI(public member function of std::ostrstream)\fP + \fI(public member function of std::ostrstream)\fP destructor destructs a strstreambuf object, optionally deallocating the character \fB[virtual]\fP array - \fI(virtual public member function)\fP + \fI(virtual public member function)\fP overflow appends a character to the output sequence, may reallocate or initially \fB[virtual]\fP allocate the buffer if dynamic and not frozen - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP diff --git a/man/std::strstreambuf::overflow.3 b/man/std::strstreambuf::overflow.3 index 4ee947219..40b99e184 100644 --- a/man/std::strstreambuf::overflow.3 +++ b/man/std::strstreambuf::overflow.3 @@ -1,19 +1,22 @@ -.TH std::strstreambuf::overflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::overflow \- std::strstreambuf::overflow + .SH Synopsis - protected: - virtual int_type overflow (int_type c = EOF); + protected: (deprecated in C++98) + virtual int_type overflow( int_type c = EOF ); (removed in C++26) Appends the character c to the put area of the buffer, reallocating if possible. - 1) If c==EOF, does nothing + 1) If c == EOF, does nothing. 2) Otherwise, if the put area has a write position available (pptr() < epptr()), - stores the character as if by *pptr()++ = c + stores the character as if by *pptr()++ = c. 3) Otherwise, if the stream buffer mode is not dynamic or the stream buffer is - currently frozen, the function fails and returns EOF + currently frozen, the function fails and returns EOF. 4) Otherwise, the function reallocates (or initially allocates) a dynamic array large enough to hold the contents of the current dynamic array (if any) plus at - least one additional write position. If a pointer to the allocator function palloc - was used in the constructor, that function is called with (*palloc)[n] where n is + least one additional write position. If a pointer to the allocating function palloc + was used in the constructor, that function is called with (*palloc)(n) where n is the number of bytes to allocate, otherwise new char[n] is used. If a pointer to the deallocating function pfree was used in the constructor, that function is called with (*pfree)(p) to deallocate the previous array, if needed, otherwise delete[] p @@ -25,17 +28,17 @@ .SH Return value - If c==EOF, returns some value other than EOF. Otherwise, returns (unsigned char)(c) - on success, EOF on failure. + If c == EOF, returns some value other than EOF. Otherwise, returns (unsigned + char)(c) on success, EOF on failure. .SH Example - + // Run this code - #include #include - + #include + struct mybuf : std::strstreambuf { int_type overflow(int_type c) @@ -48,12 +51,12 @@ return rc; } }; - + int main() { mybuf sbuf; // read-write dynamic strstreambuf std::iostream stream(&sbuf); - + stream << "Sufficiently long string to overflow the initial allocation, at least " << " on some systems."; } @@ -70,12 +73,15 @@ .SH See also overflow writes characters to the associated output sequence from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + overflow appends a character to the output sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) overflow writes characters to the associated file from the put area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + sputc writes one character to the put area and advances the next pointer - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::strstreambuf::pbackfail.3 b/man/std::strstreambuf::pbackfail.3 index 110ca9634..aa9b8797d 100644 --- a/man/std::strstreambuf::pbackfail.3 +++ b/man/std::strstreambuf::pbackfail.3 @@ -1,7 +1,10 @@ -.TH std::strstreambuf::pbackfail 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::pbackfail \- std::strstreambuf::pbackfail + .SH Synopsis - protected: - virtual int_type pbackfail( int_type c = EOF ); + protected: (deprecated in C++98) + virtual int_type pbackfail( int_type c = EOF ); (removed in C++26) This protected virtual function is called by the public functions basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called @@ -9,8 +12,8 @@ 1) The caller is requesting that the get area is backed up by one character (pbackfail() is called with no arguments or with EOF as the argument) - a) First, checks if there is a putback position, and if there really isn't, fails. - (strstreambuf has no external character source to re-read) + a) First, checks if there is a putback position, and if there really isn't, fails + (strstreambuf has no external character source to re-read). b) If the caller was wrong and the putback position is in fact available, simply decrements basic_streambuf::gptr(), e.g. by calling gbump(-1). 2) The caller attempts to putback a different character from the one retrieved @@ -43,18 +46,18 @@ .SH See also - pbackfail puts a character back into the input sequence, possibly modifying the - \fB[virtual]\fP input sequence - \fI(virtual protected member function of std::basic_streambuf)\fP + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + sungetc moves the next pointer in the input sequence back by one - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP sputbackc puts one character back in the input sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP unget unextracts a character - \fI(public member function of std::basic_istream)\fP - putback puts character into input stream - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP .SH Category: - * Todo no example diff --git a/man/std::strstreambuf::pcount.3 b/man/std::strstreambuf::pcount.3 index d13b4fc80..85ee2746a 100644 --- a/man/std::strstreambuf::pcount.3 +++ b/man/std::strstreambuf::pcount.3 @@ -1,6 +1,10 @@ -.TH std::strstreambuf::pcount 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::pcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::pcount \- std::strstreambuf::pcount + .SH Synopsis - int pcount() const; + int pcount() const; (deprecated in C++98) + (removed in C++26) Returns the number of characters written to the output sequence. @@ -8,7 +12,7 @@ returns zero. Otherwise, returns the next pointer in the put area minus the beginning pointer in - the put area, that is pptr() - pbase() + the put area, that is pptr() - pbase(). .SH Parameters @@ -20,29 +24,29 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::strstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; + dyn << "Test: " << 1.23 << std::ends; std::strstreambuf* buf = dyn.rdbuf(); std::cout << "The size of the output is " << buf->pcount() // or just buf.pcount() << " and it holds \\"" << dyn.str() << "\\"\\n"; dyn.freeze(false); // after calling .str() on a dynamic strstream - + char arr[10]; std::ostrstream user(arr, 10); // user-provided output buffer buf = user.rdbuf(); user << 1.23; // note: no std::ends std::cout.write(arr, buf->pcount()); // or just user.pcount() std::cout << '\\n'; - + std::istrstream lit("1 2 3"); // read-only fixed-size buffer buf = lit.rdbuf(); // istrstream has no member pcount(), so lit.pcount() won't work @@ -51,13 +55,13 @@ .SH Output: - The size of the output is 10 and it holds "Test: 1.23" + The size of the output is 11 and it holds "Test: 1.23" 1.23 Input-only pcount() = 0 .SH See also pcount obtains the number of characters written - \fI(public member function of std::strstream)\fP + \fI(public member function of std::strstream)\fP pcount obtains the number of characters written - \fI(public member function of std::ostrstream)\fP + \fI(public member function of std::ostrstream)\fP diff --git a/man/std::strstreambuf::seekoff.3 b/man/std::strstreambuf::seekoff.3 index 3e4229be2..ae22e150a 100644 --- a/man/std::strstreambuf::seekoff.3 +++ b/man/std::strstreambuf::seekoff.3 @@ -1,11 +1,15 @@ -.TH std::strstreambuf::seekoff 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::seekoff \- std::strstreambuf::seekoff + .SH Synopsis protected: - virtual pos_type seekoff(off_type off, - ios_base::seekdir way, + virtual pos_type seekoff( off_type off, (deprecated in C++98) + ios_base::seekdir way, (removed in C++26) - ios_base::openmode which = ios_base::in | ios_base::out); + ios_base::openmode which = + ios_base::in | ios_base::out ); Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if possible, to the position that corresponds to exactly off characters from beginning, @@ -13,13 +17,13 @@ * If which includes ios_base::in and this buffer is open for reading, then repositions the read pointer std::basic_streambuf::gptr inside the get area as - described below + described below. * If which includes ios_base::out and this buffer is open for writing, then repositions the write pointer std::basic_streambuf::pptr inside the put area as - described below + described below. * If which includes both ios_base::in and ios_base::out and the buffer is open for - both reading and writing, and when is either ios_base::beg or ios_base::end, - then repositions both read and write pointers as described below. + both reading and writing, and way is either ios_base::beg or ios_base::end, then + repositions both read and write pointers as described below. * Otherwise, this function fails. If the pointer (either gptr or pptr or both) is repositioned, it is done as follows: @@ -29,7 +33,7 @@ 2) The new pointer offset newoff of type off_type is determined a) if way == ios_base::beg, then newoff is zero b) if way == ios_base::cur, then newoff is the current position of the pointer - (gptr()-eback() or pptr()-pbase()) + (gptr() - eback() or pptr() - pbase()) c) if way == ios_base::end, then newoff is the length of the entire initialized part of the buffer (if overallocation is used, the high watermark pointer minus the beginning pointer) @@ -44,7 +48,7 @@ defines base position to apply the relative offset to. It can be one of the following constants: - dir - Constant Explanation + way - Constant Explanation beg the beginning of a stream end the ending of a stream cur the current position of stream position indicator @@ -62,40 +66,41 @@ .SH Example - + // Run this code #include #include - + int main() { char a[] = "123"; std::strstream ss(a, sizeof a); // in/out std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + // absolute positioning both pointers ss.rdbuf()->pubseekoff(1, std::ios_base::beg); // move both forward std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + // try to move both pointers 1 forward from current position - if(-1 == ss.rdbuf()->pubseekoff(1, std::ios_base::cur)) + if (-1 == ss.rdbuf()->pubseekoff(1, std::ios_base::cur)) std::cout << "moving both pointers from current position failed\\n"; std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + // move the write pointer 1 forward, but not the read pointer // can also be called as ss.seekp(1, std::ios_base::cur); ss.rdbuf()->pubseekoff(1, std::ios_base::cur, std::ios_base::out); std::cout << "put pos = " << ss.tellp() << " get pos = " << ss.tellg() << '\\n'; - + ss << 'a'; // write at put position std::cout << "Wrote 'a' at put position, the buffer is now: '"; std::cout.write(a, sizeof a); std::cout << "'\\n"; + char ch; ss >> ch; std::cout << "reading at get position gives '" << ch << "'\\n"; @@ -111,16 +116,28 @@ Wrote 'a' at put position, the buffer is now: '12a' reading at get position gives '2' + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + .SH See also seekpos repositions the next pointer in the input sequence, output sequence, or \fB[virtual]\fP both using absolute addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, or - \fB[virtual]\fP both, using relative addressing - \fI(virtual protected member function of std::basic_streambuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, or - \fB[virtual]\fP both, using relative addressing - \fI(virtual protected member function of std::basic_stringbuf)\fP + \fI(virtual protected member function)\fP + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) seekoff repositions the file position, using relative addressing - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + diff --git a/man/std::strstreambuf::seekpos.3 b/man/std::strstreambuf::seekpos.3 index 9e6d250a3..30c699f92 100644 --- a/man/std::strstreambuf::seekpos.3 +++ b/man/std::strstreambuf::seekpos.3 @@ -1,14 +1,18 @@ -.TH std::strstreambuf::seekpos 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::seekpos \- std::strstreambuf::seekpos + .SH Synopsis protected: - virtual pos_type seekpos(pos_type sp, + virtual pos_type seekpos( pos_type sp, (deprecated in C++98) + std::ios_base::openmode which = (removed in C++26) - std::ios_base::openmode which = std::ios_base::in | + std::ios_base::in | std::ios_base::out ); Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if - possible, to the position indicated by sp + possible, to the position indicated by sp. If std::ios_base::in is set in which, attempts to reposition gptr() (the next pointer in the get area). If std::ios_base::out is set in which, attempts to @@ -17,12 +21,12 @@ Each next pointer is repositioned as follows: - 1) If the next pointer is null, the operation fails - 2) Otherwise, the new offset newoff (of type off_type) is determined by calling - sp.offset(). If newoff is negative, out of bounds of the buffer, or invalid, the - operation fails. - 3) Otherwise, the next pointer is assigned as if by gptr() = eback()+newoff or - pptr() = pbase()+newoff. + * If the next pointer is null, the operation fails. + * Otherwise, the new offset newoff (of type off_type) is determined by calling + sp.offset(). If newoff is negative, out of bounds of the buffer, or invalid, the + operation fails. + * Otherwise, the next pointer is assigned as if by gptr() = eback() + newoff or + pptr() = pbase() + newoff. .SH Parameters @@ -43,33 +47,38 @@ seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the single-argument versions of std::basic_istream::seekg() and - std::basic_ostream::seekp() + std::basic_ostream::seekp(). .SH Example - + // Run this code - #include #include #include - + #include + struct mybuf : std::strstreambuf { mybuf(const char* str) : std::strstreambuf(str, std::strlen(str)) {} - pos_type seekpos(pos_type sp, std::ios_base::openmode which) { - std::cout << "Before seekpos(" << sp << "), size of the get area is " - << egptr()-eback() << " with " - << egptr()-gptr() << " read positions available\\n"; - pos_type rc = std::strstreambuf::seekpos(sp, which); - std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " - << "size of the get area is " - << egptr()-eback() << " with " - << egptr()-gptr() << " read positions available\\n"; + + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::strstreambuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + return rc; } }; - + int main() { mybuf buf("12345"); @@ -79,19 +88,32 @@ .SH Output: - Before seekpos\fB(2)\fP, size of the get area is 5 with 5 read positions available + Before seekpos\fB(2)\fP, size of the get area is 5 with 5 read positions available. seekpos() returns 2. - After the call, size of the get area is 5 with 3 read positions available + After the call, size of the get area is 5 with 3 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekpos returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure .SH See also - pubseekpos invokes seekpos() - \fI(public member function of std::basic_streambuf)\fP - seekpos repositions the next pointer in the input sequence, output sequence, or - \fB[virtual]\fP both using absolute addressing - \fI(virtual protected member function of std::basic_stringbuf)\fP - seekpos repositions the file position, using absolute addressing - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP - seekoff repositions the next pointer in the input sequence, output sequence, or - \fB[virtual]\fP both, using relative addressing - \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function)\fP + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + diff --git a/man/std::strstreambuf::setbuf.3 b/man/std::strstreambuf::setbuf.3 new file mode 100644 index 000000000..a3e873a3d --- /dev/null +++ b/man/std::strstreambuf::setbuf.3 @@ -0,0 +1,77 @@ +.TH std::strstreambuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::setbuf \- std::strstreambuf::setbuf + +.SH Synopsis + protected: (deprecated in C++98) + virtual streambuf* setbuf( char* s, std::streamsize n ); (removed in C++26) + + If s is a null pointer and n is zero, this function has no effect. + + Otherwise, the effect is implementation-defined: some implementations do nothing, + while some implementations deallocate the dynamic member array used as the buffer + and begin using the user-supplied character array of size n, whose first element is + pointed to by s. + + This function is protected virtual, it may only be called through pubsetbuf() or + from member functions of a user-defined class derived from std::strstreambuf. + +.SH Parameters + + s - pointer to the first byte in the user-provided buffer + n - the number of bytes in the user-provided buffer + +.SH Return value + + this + +.SH Example + + Implementation test to check if setbuf() is supported on a dynamic strstream (output + obtained with Sun Studio): + + +// Run this code + + #include + #include + + int main() + { + char a[100] = {}; + std::strstream str; + str.rdbuf()->pubsetbuf(a, sizeof a); + str << "Test string" << std::ends; + std::cout << "user-provided buffer holds \\"" << a << "\\"\\n"; + } + +.SH Possible output: + + user-provided buffer holds "Test string" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the effect of setbuf() was "performs an + operation that is + LWG 66 C++98 defined separately for each class derived the effect is + from strstreambuf", implementation-defined + but there are no classes derived from + strstreambuf + +.SH See also + + pubsetbuf invokes setbuf() + \fI(public member function of std::basic_streambuf)\fP + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + setbuf provides user-supplied buffer or turns this filebuf unbuffered + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + diff --git a/man/std::strstreambuf::str.3 b/man/std::strstreambuf::str.3 index f9165e09b..66dec570a 100644 --- a/man/std::strstreambuf::str.3 +++ b/man/std::strstreambuf::str.3 @@ -1,6 +1,10 @@ -.TH std::strstreambuf::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::str \- std::strstreambuf::str + .SH Synopsis - char* str() const; + char* str(); (deprecated in C++98) + (removed in C++26) Calls freeze(), then returns a copy of start pointer of the get area, std::streambuf::eback(). @@ -29,45 +33,45 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::strstream dyn; // dynamically-allocated read/write buffer - dyn << "Test: " << 1.23; + dyn << "Test: " << 1.23 << std::ends; std::strstreambuf* buf = dyn.rdbuf(); - std::cout << "R/W buffer holds \\"" << buf->str() // or dyn.str() - << "\\"\\n"; + std::cout << "R/W buffer holds [" << buf->str() // or dyn.str() + << "]\\n"; dyn.freeze(false); // after calling .str() on a dynamic strstream - + char arr[10]; std::ostrstream user(arr, 10); // fixed-size write-only buffer buf = user.rdbuf(); user << 1.23 << std::ends; - std::cout << "Write-only buffer holds \\"" << buf->str() // or user.str() - << "\\"\\n"; - + std::cout << "Write-only buffer holds [" << buf->str() // or user.str() + << "]\\n"; + std::istrstream lit("1 2 3"); // fixed-size read-only buffer buf = lit.rdbuf(); - std::cout << "Read-only buffer holds \\"" << buf->str() // or lit.str() - << "\\"\\n"; + std::cout << "Read-only buffer holds [" << buf->str() // or lit.str() + << "]\\n"; } .SH Output: - R/W buffer holds "Test: 1.23" - Write-only buffer holds "1.23" - Read-only buffer holds "1 2 31 2 3" + R/W buffer holds [Test: 1.23] + Write-only buffer holds [1.23] + Read-only buffer holds [1 2 31 2 3] .SH See also str accesses the output buffer - \fI(public member function of std::strstream)\fP + \fI(public member function of std::strstream)\fP str accesses the output buffer - \fI(public member function of std::ostrstream)\fP + \fI(public member function of std::ostrstream)\fP str accesses the output buffer - \fI(public member function of std::istrstream)\fP + \fI(public member function of std::istrstream)\fP diff --git a/man/std::strstreambuf::strstreambuf.3 b/man/std::strstreambuf::strstreambuf.3 index aed5ab223..b3ab3e0fb 100644 --- a/man/std::strstreambuf::strstreambuf.3 +++ b/man/std::strstreambuf::strstreambuf.3 @@ -1,38 +1,50 @@ -.TH std::strstreambuf::strstreambuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::strstreambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::strstreambuf \- std::strstreambuf::strstreambuf + .SH Synopsis - explicit strstreambuf( std::streamsize alsize = 0 ); \fB(1)\fP - strstreambuf( void* (*palloc)(std::size_t), void (*pfree)(void*) ); \fB(2)\fP - strstreambuf( char* gnext, std::streamsize n, char* pbeg = 0 ); \fB(3)\fP - strstreambuf( signed char* gnext, std::streamsize n, signed char* pbeg = 0 ); \fB(4)\fP - strstreambuf( unsigned char* gnext, std::streamsize n, unsigned char* pbeg = 0 \fB(5)\fP - ); - strstreambuf( const char* gnext, std::streamsize n ); \fB(6)\fP - strstreambuf( const signed char* gnext, std::streamsize n); \fB(7)\fP - strstreambuf( const unsigned char* gnext, std::streamsize n ); \fB(8)\fP + explicit strstreambuf( std::streamsize alsize = 0 (deprecated in C++98) + ); \fI(until C++11)\fP + strstreambuf() : strstreambuf\fB(0)\fP {} \fI(since C++11)\fP(removed in + explicit strstreambuf( std::streamsize alsize ); C++26) + strstreambuf( void* (*palloc)(std::size_t), void \fB(2)\fP (deprecated in C++98) + (*pfree)(void*) ); (removed in C++26) + strstreambuf( char* gnext, std::streamsize n, char* \fB(3)\fP (deprecated in C++98) + pbeg = 0 ); (removed in C++26) + strstreambuf( signed char* gnext, std::streamsize \fB(1)\fP \fB(4)\fP (deprecated in C++98) + n, signed char* pbeg = 0 ); (removed in C++26) + strstreambuf( unsigned char* gnext, std::streamsize \fB(5)\fP (deprecated in C++98) + n, unsigned char* pbeg = 0 ); (removed in C++26) + strstreambuf( const char* gnext, std::streamsize n \fB(6)\fP (deprecated in C++98) + ); (removed in C++26) + strstreambuf( const signed char* gnext, \fB(7)\fP (deprecated in C++98) + std::streamsize n ); (removed in C++26) + strstreambuf( const unsigned char* gnext, \fB(8)\fP (deprecated in C++98) + std::streamsize n ); (removed in C++26) 1) Constructs a std::strstreambuf object: initializes the base class by calling the default constructor of std::streambuf, initializes the buffer state to "dynamic" (the buffer will be allocated as needed), initializes allocated size to the provided alsize, initializes the allocation and the deallocation functions to null (will use - new[] and delete[]) + new[] and delete[]). 2) Constructs a std::strstreambuf object: initializes the base class by calling the default constructor of std::streambuf, initializes the buffer state to "dynamic" (the buffer will be allocated as needed), initializes allocated size to unspecified value, initializes the allocation function to palloc and the deallocation function - to pfree + to pfree. 3-5) Constructs a std::strstreambuf object in following steps: - a) Initializes the base class by calling the default constructor of std::streambuf + a) Initializes the base class by calling the default constructor of std::streambuf. b) Initializes the buffer state to "constant" (the buffer is a user-provided - fixed-size buffer) + fixed-size buffer). c) Determines the number of elements in the user-provided array as follows: if n is greater than zero, n is used. If n is zero, std::strlen(gnext) is executed to determine the buffer size. If n is negative, INT_MAX is used. d) Configures the std::basic_streambuf pointers as follows: If pbeg is a null pointer, calls setg(gnext, gnext, gnext + N). If pbeg is not a null pointer, - executes setg(gnext, gnext, pbeg) and setp(pbeg, pbeg+N), where N is the number of + executes setg(gnext, gnext, pbeg) and setp(pbeg, pbeg + N), where N is the number of elements in the array as determined earlier. 6-8) Same as strstreambuf((char*)gnext, n), except the "constant" bit is set in the - buffer state bitmask (output to this buffer is not allowed) + buffer state bitmask (output to this buffer is not allowed). .SH Parameters @@ -46,29 +58,38 @@ .SH Notes - These constructors are typically called by the constructors of std::strstream + These constructors are typically called by the constructors of std::strstream. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit .SH Example - + // Run this code - #include #include - + #include + int main() { std::strstreambuf dyn; // dynamic std::strstream dyn_s; // equivalent stream - dyn_s << 1.23; - std::cout << dyn_s.str() << '\\n'; dyn_s.freeze(false); - + dyn_s << 1.23 << std::ends; + std::cout << dyn_s.str() << '\\n'; + dyn_s.freeze(false); + char buf[10]; std::strstreambuf user(buf, 10, buf); // user-provided output buffer std::ostrstream user_s(buf, 10); // equivalent stream user_s << 1.23 << std::ends; std::cout << buf << '\\n'; - + std::strstreambuf lit("1 2 3", 5); // constant std::istrstream lit_s("1 2 3"); // equivalent stream int i, j, k; @@ -84,5 +105,5 @@ .SH See also - constructor constructs an strstream, optionally allocating the buffer + constructor constructs a strstream object, optionally allocating the buffer \fI(public member function of std::strstream)\fP diff --git a/man/std::strstreambuf::underflow.3 b/man/std::strstreambuf::underflow.3 index 322edc2fd..d1fc0354a 100644 --- a/man/std::strstreambuf::underflow.3 +++ b/man/std::strstreambuf::underflow.3 @@ -1,7 +1,10 @@ -.TH std::strstreambuf::underflow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::underflow \- std::strstreambuf::underflow + .SH Synopsis - protected: - virtual int_type underflow(); + protected: (deprecated in C++98) + virtual int_type underflow(); (removed in C++26) Reads the next character from the get area of the buffer. @@ -22,49 +25,48 @@ .SH Return value The next character in the get area, (unsigned char)(*gptr()) on success, EOF on - failure + failure. .SH Example - + // Run this code - #include #include - + #include + struct mybuf : std::strstreambuf { int_type overflow(int_type c) { - std::cout << "Before overflow(): size of the get area is " << egptr()-eback() << ' ' + std::cout << "Before overflow(): size of the get area is " << egptr()-eback() << " size of the put area is " << epptr()-pbase() << '\\n'; int_type rc = std::strstreambuf::overflow(c); - std::cout << "After overflow(): size of the get area is " << egptr()-eback() << ' ' + std::cout << "After overflow(): size of the get area is " << egptr()-eback() << " size of the put area is " << epptr()-pbase() << '\\n'; return rc; } - + int_type underflow() { - std::cout << "Before underflow(): size of the get area is " << egptr()-eback() << ' ' + std::cout << "Before underflow(): size of the get area is " << egptr()-eback() << " size of the put area is " << epptr()-pbase() << '\\n'; int_type ch = std::strstreambuf::underflow(); - std::cout << "After underflow(): size of the get area is " << egptr()-eback() << ' ' + std::cout << "After underflow(): size of the get area is " << egptr()-eback() << " size of the put area is " << epptr()-pbase() << '\\n'; - if (ch == EOF) { + if (ch == EOF) std::cout << "underflow() returns EOF\\n"; - } else { + else std::cout << "underflow() returns '" << char(ch) << "'\\n"; - } return ch; } }; - + int main() { mybuf sbuf; // read-write dynamic strstreambuf std::iostream stream(&sbuf); - + int n; stream >> n; stream.clear(); @@ -75,28 +77,31 @@ .SH Possible output: - Before underflow(): size of the get area is 0 size of the put area is 0 - After underflow(): size of the get area is 0 size of the put area is 0 + Before underflow(): size of the get area is 0 size of the put area is 0 + After underflow(): size of the get area is 0 size of the put area is 0 underflow() returns EOF - Before overflow(): size of the get area is 0 size of the put area is 0 - After overflow(): size of the get area is 0 size of the put area is 32 - Before underflow(): size of the get area is 0 size of the put area is 32 - After underflow(): size of the get area is 3 size of the put area is 32 + Before overflow(): size of the get area is 0 size of the put area is 0 + After overflow(): size of the get area is 0 size of the put area is 32 + Before underflow(): size of the get area is 0 size of the put area is 32 + After underflow(): size of the get area is 3 size of the put area is 32 underflow() returns '1' - Before underflow(): size of the get area is 3 size of the put area is 32 - After underflow(): size of the get area is 3 size of the put area is 32 + Before underflow(): size of the get area is 3 size of the put area is 32 + After underflow(): size of the get area is 3 size of the put area is 32 underflow() returns EOF 123 .SH See also underflow reads characters from the associated input sequence to the get area - \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + underflow returns the next character available in the input sequence - \fB[virtual]\fP \fI(virtual protected member function of std::basic_stringbuf)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) underflow reads from the associated file - \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + sgetc reads one character from the input sequence without advancing the sequence - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP get extracts characters - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::strstreambuf::~strstreambuf.3 b/man/std::strstreambuf::~strstreambuf.3 index 17f6e711a..f69b5a0a1 100644 --- a/man/std::strstreambuf::~strstreambuf.3 +++ b/man/std::strstreambuf::~strstreambuf.3 @@ -1,6 +1,10 @@ -.TH std::strstreambuf::~strstreambuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strstreambuf::~strstreambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strstreambuf::~strstreambuf \- std::strstreambuf::~strstreambuf + .SH Synopsis - virtual ~strstreambuf(); + virtual ~strstreambuf(); (deprecated in C++98) + (removed in C++26) Destroys a std::strstreambuf object. if the object is managing a dynamically-allocated buffer (the buffer state is "allocated") and if the object is @@ -9,51 +13,51 @@ .SH Parameters - (none0 + \fI(none)\fP .SH Notes - This destructor is typically called by the destructor of std::strstream + This destructor is typically called by the destructor of std::strstream. If str() was called on a dynamic strstream and freeze(false) was not called after that, this destructor leaks memory. .SH Example - + // Run this code - #include #include - + #include + void* my_alloc(size_t n) { std::cout << "my_alloc(" << n << ") called\\n"; return new char[n]; } - + void my_free(void* p) { std::cout << "my_free() called\\n"; delete[] (char*)p; } - + int main() { { std::strstreambuf buf(my_alloc, my_free); std::ostream s(&buf); - s << 1.23; + s << 1.23 << std::ends; std::cout << buf.str() << '\\n'; buf.freeze(false); } // destructor called here, buffer deallocated - + { std::strstreambuf buf(my_alloc, my_free); std::ostream s(&buf); - s << 1.23; + s << 1.23 << std::ends; std::cout << buf.str() << '\\n'; - // buf.freeze(false); + // buf.freeze(false); } // destructor called here, memory leak! } diff --git a/man/std::strtof,std::strtod,std::strtold.3 b/man/std::strtof,std::strtod,std::strtold.3 index 417a46e23..a8d005890 100644 --- a/man/std::strtof,std::strtod,std::strtold.3 +++ b/man/std::strtof,std::strtod,std::strtold.3 @@ -1,4 +1,7 @@ -.TH std::strtof,std::strtod,std::strtold 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strtof,std::strtod,std::strtold 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strtof,std::strtod,std::strtold \- std::strtof,std::strtod,std::strtold + .SH Synopsis Defined in header float strtof( const char* str, char** str_end ); \fI(since C++11)\fP @@ -7,41 +10,44 @@ Interprets a floating point value in a byte string pointed to by str. - Function discards any whitespace characters (as determined by std::isspace()) until + Function discards any whitespace characters (as determined by std::isspace) until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid floating point representation and converts them to floating - point value. The valid floating point value can be one of the following: + possible to form a valid floating-point representation and converts them to a + floating-point value. The valid floating-point value can be one of the following: - * decimal floating point expression. It consists of the following parts: + * decimal floating-point expression. It consists of the following parts: * (optional) plus or minus sign - * nonempty sequence of decimal digits optionally containing a decimal point - character (defines significand) + * nonempty sequence of decimal digits optionally containing decimal-point + character (as determined by the current C locale) (defines significand) * (optional) e or E followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) + sequence of decimal digits (defines exponent to base 10) - * binary floating point expression. It consists of the following parts: + * hexadecimal floating-point expression. It consists of the + following parts: * (optional) plus or minus sign * 0x or 0X - * nonempty sequence of hexadecimal digits optionally containing a decimal point - character (defines significand) - * (optional) p or P followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) - + * nonempty sequence of hexadecimal digits optionally containing a + decimal-point character (as determined by the current C locale) + (defines significand) + * (optional) p or P followed with optional minus or plus sign and + nonempty sequence of decimal digits (defines exponent to base 2) \fI(since C++11)\fP * infinity expression. It consists of the following parts: * (optional) plus or minus sign * INF or INFINITY ignoring case - * not-a-number expression. It consists of the following parts: * (optional) plus or minus sign - * NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only - contain alphanumeric characters. The result is a quiet NaN floating point value. + * NAN or NAN(char_sequence) ignoring case of the NAN part. + char_sequence can only contain digits, Latin letters, and + underscores. The result is a quiet NaN floating-point value. + + * any other expression that may be accepted by the currently installed C locale The functions sets the pointer pointed to by str_end to point to the character past - the last character interpreted. If str_end is NULL, it is ignored. + the last character interpreted. If str_end is a null pointer, it is ignored. .SH Parameters @@ -53,44 +59,66 @@ Floating point value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs and HUGE_VAL, HUGE_VALF or HUGE_VALL is returned. If no conversion can be performed, - 0 is returned. + 0 is returned and *str_end is set to str. .SH Example - + // Run this code + #include + #include #include #include - + #include + int main() { - std::cout << std::strtod("0.0000000123", nullptr) << "\\n"; - - // the second arg of strto* is non-const. We must copy the string - char src[] = "0.012 15e16 -0x1afp-2 inF Nan"; - char* c = src; - - std::cout << std::strtod(c, &c) << "\\n"; - std::cout << std::strtod(c, &c) << "\\n"; - std::cout << std::strtod(c, &c) << "\\n"; - std::cout << std::strtod(c, &c) << "\\n"; - std::cout << std::strtod(c, &c) << "\\n"; + const char* p = "111.11 -2.22 0X1.BC70A3D70A3D7P+6 -Inf 1.18973e+4932zzz"; + char* end{}; + std::cout << "Parsing \\"" << p << "\\":\\n"; + errno = 0; + for (double f = std::strtod(p, &end); p != end; f = std::strtod(p, &end)) + { + std::cout << " '" << std::string(p, end - p) << "' -> "; + p = end; + if (errno == ERANGE) + { + std::cout << "range error, got "; + errno = 0; + } + std::cout << f << '\\n'; + } + + if (std::setlocale(LC_NUMERIC, "de_DE.utf8")) + { + std::cout << "With de_DE.utf8 locale:\\n"; + std::cout << " '123.45' -> " << std::strtod("123.45", 0) << '\\n'; + std::cout << " '123,45' -> " << std::strtod("123,45", 0) << '\\n'; + } } -.SH Output: +.SH Possible output: - 1.23e-08 - 0.012 - 1.5e+17 - -107.75 - inf - nan + Parsing "111.11 -2.22 0X1.BC70A3D70A3D7P+6 -Inf 1.18973e+4932zzz": + '111.11' -> 111.11 + ' -2.22' -> -2.22 + ' 0X1.BC70A3D70A3D7P+6' -> 111.11 + ' -Inf' -> -inf + ' 1.18973e+4932' -> range error, got inf + With de_DE.utf8 locale: + '123.45' -> 123 + '123,45' -> 123.45 .SH See also - atof converts a byte string to a floating point value - \fI(function)\fP + atof converts a byte string to a floating point value + \fI(function)\fP + wcstof converts a wide string to a floating-point value + wcstod \fI(function)\fP + wcstold + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP C documentation for strtof, strtod, diff --git a/man/std::strtoimax,std::strtoumax.3 b/man/std::strtoimax,std::strtoumax.3 index 6965ebbb3..f72c97c18 100644 --- a/man/std::strtoimax,std::strtoumax.3 +++ b/man/std::strtoimax,std::strtoumax.3 @@ -1,17 +1,20 @@ -.TH std::strtoimax,std::strtoumax 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strtoimax,std::strtoumax 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strtoimax,std::strtoumax \- std::strtoimax,std::strtoumax + .SH Synopsis Defined in header - std::intmax_t strtoimax( const char* nptr, char** endptr, int base ); \fI(since C++11)\fP - std::uintmax_t strtoumax( const char* nptr, char** endptr, int base \fI(since C++11)\fP + std::intmax_t strtoimax( const char* nptr, char** endptr, int base \fB(1)\fP \fI(since C++11)\fP ); + std::uintmax_t strtoumax( const char* nptr, char** endptr, int \fB(2)\fP \fI(since C++11)\fP + base ); Interprets an integer value in a byte string pointed to by nptr. - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid base-n (where n=base) integer number representation and - converts them to an integer value. The valid integer value consists of the following - parts: + Discards any whitespace characters (as identified by calling std::isspace) until the + first non-whitespace character is found, then takes as many characters as possible + to form a valid base-n (where n=base) integer number representation and converts + them to an integer value. The valid integer value consists of the following parts: * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or @@ -20,21 +23,26 @@ base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type. + The functions sets the pointer pointed to by endptr to point to the character past - the last character interpreted. If endptr is NULL, it is ignored. + the last character interpreted. If endptr is a null pointer, it is ignored. If the nptr is empty or does not have the expected form, no conversion is performed, - and (if enptr is not NULL) the value of nptr is stored in the object pointed to by - endptr. + and (if enptr is not a null pointer) the value of nptr is stored in the object + pointed to by endptr. .SH Parameters @@ -53,41 +61,62 @@ .SH Example - + // Run this code + #include #include #include - #include - + int main() { std::string str = "helloworld"; std::intmax_t val = std::strtoimax(str.c_str(), nullptr, 36); std::cout << str << " in base 36 is " << val << " in base 10\\n"; - + char* nptr; val = std::strtoimax(str.c_str(), &nptr, 30); - if(nptr != &str[0] + str.size()) + if (nptr != &str[0] + str.size()) std::cout << str << " in base 30 is invalid." - << " The first invalid digit is " << *nptr << '\\n'; + << " The first invalid digit is '" << *nptr << "'\\n"; } .SH Output: helloworld in base 36 is 1767707668033969 in base 10 - helloworld in base 30 is invalid. The first invalid digit is w + helloworld in base 30 is invalid. The first invalid digit is 'w' .SH See also + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + strtol converts a byte string to an integer value + strtoll \fI(function)\fP + \fI(C++11)\fP + strtoul converts a byte string to an unsigned integer value + strtoull \fI(function)\fP + \fI(C++11)\fP wcstoimax - wcstoumax converts a wide string to std::intmax_t or std::uintmax_t - \fI(C++11)\fP \fI(function)\fP + wcstoumax converts a wide string to std::intmax_t or std::uintmax_t + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + strtof converts a byte string to a floating-point value + strtod \fI(function)\fP + strtold + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + atoi + atol converts a byte string to an integer value + atoll \fI(function)\fP \fI(C++11)\fP - strtol converts a byte string to an integer value - strtoll \fI(function)\fP - strtoul converts a byte string to an unsigned integer value - strtoull \fI(function)\fP C documentation for strtoimax, strtoumax diff --git a/man/std::strtok.3 b/man/std::strtok.3 index ed52240f3..5d566be86 100644 --- a/man/std::strtok.3 +++ b/man/std::strtok.3 @@ -1,4 +1,7 @@ -.TH std::strtok 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strtok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strtok \- std::strtok + .SH Synopsis Defined in header char* strtok( char* str, const char* delim ); @@ -7,29 +10,27 @@ separator characters are identified by null-terminated byte string pointed to by delim. - This function is designed to be called multiples times to obtain successive tokens + This function is designed to be called multiple times to obtain successive tokens from the same string. - * If str != NULL, the call is treated as the first call to strtok for this - particular string. The function searches for the first character which is not - contained in delim. + * If str is not a null pointer, the call is treated as the first call to strtok + for this particular string. The function searches for the first character which + is not contained in delim. * If no such character was found, there are no tokens in str at all, and the function returns a null pointer. - * If such character was found, is it the beginning of the token. The function then + * If such character was found, it is the beginning of the token. The function then searches from that point on for the first character that is contained in delim. * If no such character was found, str has only one token, and the future calls to - strtok will return a null pointer + strtok will return a null pointer. * If such character was found, it is replaced by the null character '\\0' and the pointer to the following character is stored in a static location for subsequent invocations. - - * The function then returns the pointer to the beginning of the token - - * If str == NULL, the call is treated as a subsequent calls to strtok: the - function continues from where it left in previous invocation. The behavior is - the same as if the previously stored pointer is passed as str. + * The function then returns the pointer to the beginning of the token. + * If str is a null pointer, the call is treated as a subsequent call to strtok: + the function continues from where it left in previous invocation. The behavior + is the same as if the previously stored pointer is passed as str. .SH Parameters @@ -38,47 +39,97 @@ .SH Return value - Pointer to the beginning of the next token or NULL if there are no more tokens. + Pointer to the beginning of the next token or a nullptr if there are no more tokens. .SH Notes This function is destructive: it writes the '\\0' characters in the elements of the string str. In particular, a string literal cannot be used as the first argument of - strtok. + std::strtok. Each call to this function modifies a static variable: is not thread safe. - Unlike most other tokenizers, the delimiters in strtok can be different for each - subsequent token, and can even depend on the contents of the previous tokens. + Unlike most other tokenizers, the delimiters in std::strtok can be different for + each subsequent token, and can even depend on the contents of the previous tokens. + +.SH Possible implementation + + char* strtok(char* str, const char* delim) + { + static char* buffer; + + if (str != nullptr) + buffer = str; + + buffer += std::strspn(buffer, delim); + + if (*buffer == '\\0') + return nullptr; + + char* const tokenBegin = buffer; + + buffer += std::strcspn(buffer, delim); + + if (*buffer != '\\0') + *buffer++ = '\\0'; + + return tokenBegin; + } + + Actual C++ library implementations of this function delegate to the C library, where + it may be implemented directly (as in MUSL libc), or in terms of its reentrant + version (as in GNU libc). .SH Example - + // Run this code #include + #include #include - + int main() { - char input[100] = "A bird came down the walk"; - char *token = std::strtok(input, " "); - while (token != NULL) { - std::cout << token << '\\n'; - token = std::strtok(NULL, " "); + char input[] = "one + two * (three - four)!"; + const char* delimiters = "! +- (*)"; + char* token = std::strtok(input, delimiters); + while (token) + { + std::cout << std::quoted(token) << ' '; + token = std::strtok(nullptr, delimiters); + } + + std::cout << "\\nContents of the input string now:\\n\\""; + for (std::size_t n = 0; n < sizeof input; ++n) + { + if (const char c = input[n]; c != '\\0') + std::cout << c; + else + std::cout << "\\\\0"; } + std::cout << "\\"\\n"; } .SH Output: - A - bird - came - down - the - walk + "one" "two" "three" "four" + Contents of the input string now: + "one\\0+ two\\0* (three\\0- four\\0!\\0" .SH See also + finds the first location of any character from a set of + strpbrk separators + \fI(function)\fP + returns the length of the maximum initial segment that consists + strcspn of only the characters not found in another byte string + \fI(function)\fP + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + ranges::split_view a view over the subranges obtained from splitting another view + views::split using a delimiter + (C++20) \fI(class template)\fP (range adaptor object) C documentation for strtok diff --git a/man/std::strtol,std::strtoll.3 b/man/std::strtol,std::strtoll.3 index 0745f560b..4b66435b1 100644 --- a/man/std::strtol,std::strtoll.3 +++ b/man/std::strtol,std::strtoll.3 @@ -1,16 +1,18 @@ -.TH std::strtol,std::strtoll 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strtol,std::strtoll 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strtol,std::strtoll \- std::strtol,std::strtoll + .SH Synopsis Defined in header - long strtol( const char *str, char **str_end, int base ); - long long strtoll( const char *str, char **str_end, int base ); \fI(since C++11)\fP + long strtol( const char* str, char** str_end, int base ); \fB(1)\fP + long long strtoll( const char* str, char** str_end, int base ); \fB(2)\fP \fI(since C++11)\fP Interprets an integer value in a byte string pointed to by str. - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid base-n (where n=base) integer number representation and - converts them to an integer value. The valid integer value consists of the following - parts: + Discards any whitespace characters (as identified by calling std::isspace) until the + first non-whitespace character is found, then takes as many characters as possible + to form a valid base-n (where n=base) integer number representation and converts + them to an integer value. The valid integer value consists of the following parts: * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or @@ -19,26 +21,31 @@ base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. - The functions sets the pointer pointed to by str_end to point to the character past - the last character interpreted. If str_end is NULL, it is ignored. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type. + + The function sets the pointer pointed to by str_end to point to the character past + the last character interpreted. If str_end is a null pointer, it is ignored. If the str is empty or does not have the expected form, no conversion is performed, - and (if str_end is not NULL) the value of str is stored in the object pointed to by - str_end. + and (if str_end is not a null pointer) the value of str is stored in the object + pointed to by str_end. .SH Parameters str - pointer to the null-terminated byte string to be interpreted - str_end - pointer to a pointer to character. + str_end - pointer to a pointer to character base - base of the interpreted integer value .SH Return value @@ -46,26 +53,85 @@ * If successful, an integer value corresponding to the contents of str is returned. * If the converted value falls out of range of corresponding return type, a range - error occurs (setting [[cpp/error/errno|errno]] to ERANGE) and LONG_MAX, - LONG_MIN, LLONG_MAX or LLONG_MIN is returned. + error occurs (setting errno to ERANGE) and LONG_MAX, LONG_MIN, LLONG_MAX or + LLONG_MIN is returned. * If no conversion can be performed, 0 is returned. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + const char* p = "10 200000000000000000000000000000 30 -40"; + std::cout << "Parsing " << std::quoted(p) << ":\\n"; + + for (;;) + { + // errno can be set to any non-zero value by a library function call + // regardless of whether there was an error, so it needs to be cleared + // in order to check the error set by strtol + errno = 0; + char* p_end{}; + const long i = std::strtol(p, &p_end, 10); + if (p == p_end) + break; + + const bool range_error = errno == ERANGE; + const std::string extracted(p, p_end - p); + p = p_end; + + std::cout << "Extracted " << std::quoted(extracted) + << ", strtol returned " << i << '.'; + if (range_error) + std::cout << "\\n Range error occurred."; + + std::cout << '\\n'; + } + } + +.SH Possible output: + + Parsing "10 200000000000000000000000000000 30 -40": + Extracted "10", strtol returned 10. + Extracted " 200000000000000000000000000000", strtol returned 9223372036854775807. + Range error occurred. + Extracted " 30", strtol returned 30. + Extracted " -40", strtol returned -40. .SH See also - atoi converts a byte string to an integer value - atol \fI(function)\fP - atoll - strtoul converts a byte string to an unsigned integer value - strtoull \fI(function)\fP + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + strtoul converts a byte string to an unsigned integer value + strtoull \fI(function)\fP + \fI(C++11)\fP + strtoimax + strtoumax converts a byte string to std::intmax_t or std::uintmax_t + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + wcstol converts a wide string to an integer value + wcstoll \fI(function)\fP + strtof converts a byte string to a floating-point value + strtod \fI(function)\fP + strtold + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + atoi + atol converts a byte string to an integer value + atoll \fI(function)\fP + \fI(C++11)\fP C documentation for strtol, strtoll - -.SH Category: - - * Todo no example diff --git a/man/std::strtoul,std::strtoull.3 b/man/std::strtoul,std::strtoull.3 index 651b32116..4d2e7db70 100644 --- a/man/std::strtoul,std::strtoull.3 +++ b/man/std::strtoul,std::strtoull.3 @@ -1,66 +1,125 @@ -.TH std::strtoul,std::strtoull 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strtoul,std::strtoull 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strtoul,std::strtoull \- std::strtoul,std::strtoull + .SH Synopsis Defined in header - unsigned long strtoul( const char *str, char **str_end, int base - ); - unsigned long long strtoull( const char *str, char **str_end, int \fI(since C++11)\fP + unsigned long strtoul ( const char* str, char** str_end, int \fB(1)\fP + base ); + unsigned long long strtoull( const char* str, char** str_end, int \fB(2)\fP \fI(since C++11)\fP base ); Interprets an unsigned integer value in a byte string pointed to by str. - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid base-n (where n=base) unsigned integer number - representation and converts them to an integer value. The valid unsigned integer - value consists of the following parts: + Discards any whitespace characters (as identified by calling std::isspace) until the + first non-whitespace character is found, then takes as many characters as possible + to form a valid base-n (where n=base) unsigned integer number representation and + converts them to an integer value. The valid unsigned integer value consists of the + following parts: + * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or 0) * (optional) prefix (0x or 0X) indicating hexadecimal base (applies only when the base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type, which + applies unsigned integer wraparound rules. + The functions sets the pointer pointed to by str_end to point to the character past - the last character interpreted. If str_end is NULL, it is ignored. + the last character interpreted. If str_end is a null pointer, it is ignored. .SH Parameters str - pointer to the null-terminated byte string to be interpreted - str_end - pointer to a pointer to character. + str_end - pointer to a pointer to character, might be set to a position past the + last character interpreted base - base of the interpreted integer value .SH Return value Integer value corresponding to the contents of str on success. If the converted - value falls out of range of corresponding return type, range error occurs and - ULONG_MAX or ULLONG_MAX is returned. If no conversion can be performed, 0 is - returned. + value falls out of range of corresponding return type, range error occurs (errno is + set to ERANGE) and ULONG_MAX or ULLONG_MAX is returned. If no conversion can be + performed, 0 is returned. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + const char* p = "10 200000000000000000000000000000 30 -40 - 42"; + char* end = nullptr; + std::cout << "Parsing '" << p << "':\\n"; + for (unsigned long i = std::strtoul(p, &end, 10); + p != end; + i = std::strtoul(p, &end, 10)) + { + std::cout << "'" << std::string(p, end - p) << "' -> "; + p = end; + if (errno == ERANGE) + { + errno = 0; + std::cout << "range error, got "; + } + std::cout << i << '\\n'; + } + std::cout << "After the loop p points to '" << p << "'\\n"; + } + +.SH Possible output: + + Parsing '10 200000000000000000000000000000 30 -40 - 42': + '10' -> 10 + ' 200000000000000000000000000000' -> range error, got 18446744073709551615 + ' 30' -> 30 + ' -40' -> 18446744073709551576 + After the loop p points to ' - 42' .SH See also - atoi converts a byte string to an integer value - atol \fI(function)\fP - atoll - strtol converts a byte string to an integer value - strtoll \fI(function)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + strtol converts a byte string to an integer value + strtoll \fI(function)\fP + \fI(C++11)\fP + strtoimax + strtoumax converts a byte string to std::intmax_t or std::uintmax_t + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + wcstoul converts a wide string to an unsigned integer value + wcstoull \fI(function)\fP + strtof converts a byte string to a floating-point value + strtod \fI(function)\fP + strtold + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + atoi + atol converts a byte string to an integer value + atoll \fI(function)\fP + \fI(C++11)\fP C documentation for strtoul, strtoull - -.SH Category: - - * Todo no example diff --git a/man/std::strxfrm.3 b/man/std::strxfrm.3 index ce8cd0f85..d8b97b43d 100644 --- a/man/std::strxfrm.3 +++ b/man/std::strxfrm.3 @@ -1,4 +1,7 @@ -.TH std::strxfrm 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::strxfrm 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::strxfrm \- std::strxfrm + .SH Synopsis Defined in header std::size_t strxfrm( char* dest, const char* src, std::size_t count ); @@ -12,12 +15,20 @@ including the terminating null character, and the length of the full transformed string is returned, excluding the terminating null character. + The behavior is undefined if the dest array is not large enough. The behavior is + undefined if dest and src overlap. + If count is 0, then dest is allowed to be a null pointer. .SH Notes - The correct length of the buffer that can receive the entire transformed string is - 1+std::strxfrm(NULL, src, 0) + The correct length of the buffer that can receive the entire transformed string is 1 + + std::strxfrm(nullptr, src, 0). + + This function is used when making multiple locale-dependent comparisons using the + same string or set of strings, because it is more efficient to use std::strxfrm to + transform all the strings just once, and subsequently compare the transformed + strings with std::strcmp. .SH Parameters @@ -32,40 +43,42 @@ .SH Example - + // Run this code - #include - #include + #include #include - + #include + #include + #include + int main() { - std::setlocale(LC_COLLATE, "cs_CZ.iso88592"); - + char* loc = std::setlocale(LC_COLLATE, "cs_CZ.iso88592"); + assert(loc); + std::string in1 = "hrnec"; - std::string out1(1+std::strxfrm(nullptr, in1.c_str(), 0), ' '); + std::string out1(1 + std::strxfrm(nullptr, in1.c_str(), 0), ' '); std::string in2 = "chrt"; - std::string out2(1+std::strxfrm(nullptr, in2.c_str(), 0), ' '); - + std::string out2(1 + std::strxfrm(nullptr, in2.c_str(), 0), ' '); + std::strxfrm(&out1[0], in1.c_str(), out1.size()); std::strxfrm(&out2[0], in2.c_str(), out2.size()); - + std::cout << "In the Czech locale: "; - if(out1 < out2) - std::cout << in1 << " before " << in2 << '\\n'; + if (out1 < out2) + std::cout << in1 << " before " << in2 << '\\n'; else - std::cout << in2 << " before " << in1 << '\\n'; - + std::cout << in2 << " before " << in1 << '\\n'; + std::cout << "In lexicographical comparison: "; - if(in1 < in2) - std::cout << in1 << " before " << in2 << '\\n'; + if (in1 < in2) + std::cout << in1 << " before " << in2 << '\\n'; else - std::cout << in2 << " before " << in1 << '\\n'; - + std::cout << in2 << " before " << in1 << '\\n'; } -.SH Output: +.SH Possible output: In the Czech locale: hrnec before chrt In lexicographical comparison: chrt before hrnec @@ -74,10 +87,10 @@ transform a wide string so that wcscmp would produce the same result as wcsxfrm wcscoll - \fI(function)\fP + \fI(function)\fP do_transform transforms a string so that collation can be replaced by comparison - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP C documentation for strxfrm diff --git a/man/std::student_t_distribution.3 b/man/std::student_t_distribution.3 index 6b6043e4e..e88ad511b 100644 --- a/man/std::student_t_distribution.3 +++ b/man/std::student_t_distribution.3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution \- std::student_t_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -7,7 +10,9 @@ Produces random floating-point values x, distributed according to probability density function: - P(x|n) = + \\(p(x|n) = \\frac{1}{\\sqrt{n\\pi} } \\cdot + \\frac{\\Gamma(\\frac{n+1}{2})}{\\Gamma(\\frac{n}{2})} \\cdot + (1+\\frac{x^2}{n})^{-\\frac{n+1}{2} } \\)p(x|n) = 1 √ @@ -43,53 +48,144 @@ 2 where n is known as the number of degrees of freedom. This distribution is used when - estimating the mean of an unknown normally distributed value given n+1 independent + estimating the mean of an unknown normally distributed value given n + 1 independent measurements, each with additive errors of unknown standard deviation, as in physical measurements. Or, alternatively, when estimating the unknown mean of a - normal distribution with unknown standard deviation, given n+1 samples. + normal distribution with unknown standard deviation, given n + 1 samples. + + std::student_t_distribution satisfies all requirements of RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics n returns the n distribution parameter (degrees of freedom) - \fI(public member function)\fP + \fI(public member function)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + template + void draw_vbars(Seq&& s, const bool DrawMinMax = true) + { + static_assert(0 < Height and 0 < BarWidth and 0 <= Padding and 0 <= Offset); + + auto cout_n = [](auto&& v, int n = 1) + { + while (n-- > 0) + std::cout << v; + }; + + const auto [min, max] = std::minmax_element(std::cbegin(s), std::cend(s)); + + std::vector qr; + for (typedef decltype(*std::cbegin(s)) V; V e : s) + qr.push_back(std::div(std::lerp(V(0), 8 * Height, + (e - *min) / (*max - *min)), 8)); + + for (auto h{Height}; h-- > 0; cout_n('\\n')) + { + cout_n(' ', Offset); + + for (auto dv : qr) + { + const auto q{dv.quot}, r{dv.rem}; + unsigned char d[]{0xe2, 0x96, 0x88, 0}; // Full Block: '█' + q < h ? d[0] = ' ', d[1] = 0 : q == h ? d[2] -= (7 - r) : 0; + cout_n(d, BarWidth), cout_n(' ', Padding); + } + + if (DrawMinMax && Height > 1) + Height - 1 == h ? std::cout << "┬ " << *max: + h ? std::cout << "│ " + : std::cout << "┴ " << *min; + } + } + + int main() + { + std::random_device rd{}; + std::mt19937 gen{rd()}; + + std::student_t_distribution<> d{10.0f}; + + const int norm = 10'000; + const float cutoff = 0.000'3f; + + std::map hist{}; + for (int n = 0; n != norm; ++n) + ++hist[std::round(d(gen))]; + + std::vector bars; + std::vector indices; + for (const auto& [n, p] : hist) + if (float x = p * (1.0f / norm); cutoff < x) + { + bars.push_back(x); + indices.push_back(n); + } + + for (draw_vbars<8, 5>(bars); const int n : indices) + std::cout << " " << std::setw(2) << n << " "; + std::cout << '\\n'; + } + +.SH Possible output: + + █████ ┬ 0.3753 + █████ │ + ▁▁▁▁▁ █████ │ + █████ █████ ▆▆▆▆▆ │ + █████ █████ █████ │ + █████ █████ █████ │ + ▄▄▄▄▄ █████ █████ █████ ▄▄▄▄▄ │ + ▁▁▁▁▁ ▃▃▃▃▃ █████ █████ █████ █████ █████ ▃▃▃▃▃ ▁▁▁▁▁ ▁▁▁▁▁ ┴ 0.0049 + -4 -3 -2 -1 0 1 2 3 4 5 .SH External links - Weisstein, Eric W. "Student's t-Distribution." From MathWorld--A Wolfram Web + Weisstein, Eric W. "Student's t-Distribution." From MathWorld — A Wolfram Web Resource. - -.SH Category: - - * Todo no example diff --git a/man/std::student_t_distribution::max.3 b/man/std::student_t_distribution::max.3 index 3e5afd608..d901fd5d2 100644 --- a/man/std::student_t_distribution::max.3 +++ b/man/std::student_t_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::max \- std::student_t_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::student_t_distribution::min.3 b/man/std::student_t_distribution::min.3 index 057f9e91c..4a84994c7 100644 --- a/man/std::student_t_distribution::min.3 +++ b/man/std::student_t_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::min \- std::student_t_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::student_t_distribution::n.3 b/man/std::student_t_distribution::n.3 index 7d438ef69..30d0feb34 100644 --- a/man/std::student_t_distribution::n.3 +++ b/man/std::student_t_distribution::n.3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution::n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::n \- std::student_t_distribution::n + .SH Synopsis RealType n() const; \fI(since C++11)\fP @@ -11,9 +14,9 @@ .SH Return value - Floating point value identifying the degrees of freedom of the distribution + Floating point value identifying the degrees of freedom of the distribution. .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::student_t_distribution::operator().3 b/man/std::student_t_distribution::operator().3 index 1ee45c299..b79282f78 100644 --- a/man/std::student_t_distribution::operator().3 +++ b/man/std::student_t_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::operator() \- std::student_t_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::student_t_distribution::param.3 b/man/std::student_t_distribution::param.3 index efdae0793..943564268 100644 --- a/man/std::student_t_distribution::param.3 +++ b/man/std::student_t_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::param \- std::student_t_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::student_t_distribution::reset.3 b/man/std::student_t_distribution::reset.3 index 2eaa9bea9..55bc8c848 100644 --- a/man/std::student_t_distribution::reset.3 +++ b/man/std::student_t_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::student_t_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::reset \- std::student_t_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::student_t_distribution::student_t_distribution.3 b/man/std::student_t_distribution::student_t_distribution.3 index 4ce600dfa..5019b23a3 100644 --- a/man/std::student_t_distribution::student_t_distribution.3 +++ b/man/std::student_t_distribution::student_t_distribution.3 @@ -1,12 +1,26 @@ -.TH std::student_t_distribution::student_t_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::student_t_distribution::student_t_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::student_t_distribution::student_t_distribution \- std::student_t_distribution::student_t_distribution + .SH Synopsis - explicit student_t_distribution( RealType n = 1 ); \fB(1)\fP \fI(since C++11)\fP - explicit student_t_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + student_t_distribution() : student_t_distribution\fB(1)\fP {} (1) \fI(since C++11)\fP + explicit student_t_distribution( RealType n ); \fB(2)\fP \fI(since C++11)\fP + explicit student_t_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs new distribution object. The first version uses n as the distribution - parameter, the second version uses params as the distribution parameter. + 2) Uses n as the distribution parameter. + 3) Uses params as the distribution parameter. .SH Parameters n - the n distribution parameter (degrees of freedom) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::sub_match.3 b/man/std::sub_match.3 index 408cb8402..1f077d35c 100644 --- a/man/std::sub_match.3 +++ b/man/std::sub_match.3 @@ -1,43 +1,43 @@ -.TH std::sub_match 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sub_match 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sub_match \- std::sub_match + .SH Synopsis Defined in header - template< - - class BidirIt \fI(since C++11)\fP - - > class sub_match; + template< class BidirIt > \fI(since C++11)\fP + class sub_match; - The class template sub_match is used by the regular expression engine to denote + The class template std::sub_match is used by the regular expression engine to denote sequences of characters matched by marked sub-expressions. A match is a [begin, end) pair within the target range matched by the regular expression, but with additional observer functions to enhance code clarity. - Only the default constructor is publicly accessible. Instances of sub_match are + Only the default constructor is publicly accessible. Instances of std::sub_match are normally constructed and populated as a part of a std::match_results container during the processing of one of the regex algorithms. The member functions return defined default values unless the matched member is true. - sub_match inherits from std::pair, although it cannot be treated - as a std::pair object because member functions such as swap and assignment will not + std::sub_match inherits from std::pair, although it cannot be + treated as a std::pair object because member functions such as assignment will not work as expected. .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Specializations Several specializations for common character sequence types are provided: Defined in header - Type Definition - csub_match sub_match - wcsub_match sub_match - ssub_match sub_match - wssub_match sub_match + Type Definition + std::csub_match std::sub_match + std::wcsub_match std::sub_match + std::ssub_match std::sub_match + std::wssub_match std::sub_match .SH Member types @@ -49,37 +49,54 @@ .SH Member objects - matched Indicates if this match was successful. + bool matched Indicates if this match was successful + \fI(public member object)\fP Inherited from std::pair - first Start of the match sequence. - second One-past-the-end of the match sequence. + BidirIt first Start of the match sequence. + \fI(public member object)\fP + BidirIt second One-past-the-end of the match sequence. + \fI(public member object)\fP .SH Member functions + This section is incomplete + Reason: Apply LWG 3204, add the swap() member function + constructor constructs the match object - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers length returns the length of the match (if any) - \fI(public member function)\fP + \fI(public member function)\fP str converts to the underlying string type - operator string_type \fI(public member function)\fP + operator string_type \fI(public member function)\fP compare compares matched subsequence (if any) - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< compares two sub_match objects - operator<= \fI(function)\fP + operator< + operator<= operator> - operator>= - operator<< outputs the matched character subsequence - \fI(function template)\fP + operator>= compares a sub_match with another sub_match, a string, or a + operator<=> character + (removed in C++20) \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + operator<< outputs the matched character subsequence + \fI(function template)\fP .SH See also - regex_token_iterator iterates through regex submatches - \fI(C++11)\fP \fI(class template)\fP + regex_token_iterator iterates through the specified sub-expressions within all regex + \fI(C++11)\fP matches in a given string or through unmatched substrings + \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::sub_match::compare.3 b/man/std::sub_match::compare.3 index b471b11e6..535967025 100644 --- a/man/std::sub_match::compare.3 +++ b/man/std::sub_match::compare.3 @@ -1,307 +1,33 @@ -.TH std::sub_match::compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - Direct comparison - template< class BidirIt > - - bool operator==( const sub_match& lhs, \fB(1)\fP \fI(since C++11)\fP - - const sub_match& rhs ); - template< class BidirIt > - - bool operator!=( const sub_match& lhs, \fB(2)\fP \fI(since C++11)\fP - - const sub_match& rhs ); - template< class BidirIt > - - bool operator<( const sub_match& lhs, \fB(3)\fP \fI(since C++11)\fP - - const sub_match& rhs ); - template< class BidirIt > - - bool operator<=( const sub_match& lhs, \fB(4)\fP \fI(since C++11)\fP - - const sub_match& rhs ); - template< class BidirIt > - - bool operator>( const sub_match& lhs, \fB(5)\fP \fI(since C++11)\fP - - const sub_match& rhs ); - template< class BidirIt > - - bool operator>=( const sub_match& lhs, \fB(6)\fP \fI(since C++11)\fP - - const sub_match& rhs ); - std::basic_string and std::sub_match - template< class BidirIt, class Traits, class Alloc > - - bool operator==( const std::basic_string< - typename \fB(7)\fP \fI(since C++11)\fP - std::iterator_traits::value_type, - Traits,Alloc>& lhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator!=( const std::basic_string< - typename \fB(8)\fP \fI(since C++11)\fP - std::iterator_traits::value_type, - Traits,Alloc>& lhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<( const std::basic_string< - typename \fB(9)\fP \fI(since C++11)\fP - std::iterator_traits::value_type, - Traits,Alloc>& lhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<=( const std::basic_string< - typename \fB(10)\fP \fI(since C++11)\fP - std::iterator_traits::value_type, - Traits,Alloc>& lhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>( const std::basic_string< - typename \fB(11)\fP \fI(since C++11)\fP - std::iterator_traits::value_type, - Traits,Alloc>& lhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>=( const std::basic_string< - typename \fB(12)\fP \fI(since C++11)\fP - std::iterator_traits::value_type, - Traits,Alloc>& lhs, - - const sub_match& rhs ); - std::sub_match and std::basic_string - template< class BidirIt, class Traits, class Alloc > - - bool operator==( const sub_match& lhs, - const std::basic_string< \fB(13)\fP \fI(since C++11)\fP - typename - std::iterator_traits::value_type, - - Traits,Alloc>& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator!=( const sub_match& lhs, - const std::basic_string< \fB(14)\fP \fI(since C++11)\fP - typename - std::iterator_traits::value_type, - - Traits,Alloc>& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<( const sub_match& lhs, - const std::basic_string< \fB(15)\fP \fI(since C++11)\fP - typename - std::iterator_traits::value_type, - - Traits,Alloc>& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<=( const sub_match& lhs, - const std::basic_string< \fB(16)\fP \fI(since C++11)\fP - typename - std::iterator_traits::value_type, - - Traits,Alloc>& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>( const sub_match& lhs, - const std::basic_string< \fB(17)\fP \fI(since C++11)\fP - typename - std::iterator_traits::value_type, - - Traits,Alloc>& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>=( const sub_match& lhs, - const std::basic_string< \fB(18)\fP \fI(since C++11)\fP - typename - std::iterator_traits::value_type, - - Traits,Alloc>& rhs ); - std::iterator_traits::value_type* and std::sub_match - template< class BidirIt, class Traits, class Alloc > - - bool operator==( const typename \fB(19)\fP \fI(since C++11)\fP - std::iterator_traits::value_type* rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator!=( const typename \fB(20)\fP \fI(since C++11)\fP - std::iterator_traits::value_type* rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<( const typename \fB(21)\fP \fI(since C++11)\fP - std::iterator_traits::value_type* rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<=( const typename \fB(22)\fP \fI(since C++11)\fP - std::iterator_traits::value_type* rhs, +.TH std::sub_match::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sub_match::compare \- std::sub_match::compare - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>( const typename \fB(23)\fP \fI(since C++11)\fP - std::iterator_traits::value_type* rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>=( const typename \fB(24)\fP \fI(since C++11)\fP - std::iterator_traits::value_type* rhs, - - const sub_match& rhs ); - std::sub_match and std::iterator_traits::value_type* - template< class BidirIt, class Traits, class Alloc > - - bool operator==( const sub_match& lhs, \fB(25)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type* rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator!=( const sub_match& lhs, \fB(26)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type* rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<( const sub_match& lhs, \fB(27)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type* rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<=( const sub_match& lhs, \fB(28)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type* rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>( const sub_match& lhs, \fB(29)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type* rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>=( const sub_match& lhs, \fB(30)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type* rhs ); - std::iterator_traits::value_type& and std::sub_match - template< class BidirIt, class Traits, class Alloc > - - bool operator==( const typename \fB(31)\fP \fI(since C++11)\fP - std::iterator_traits::value_type& rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator!=( const typename \fB(32)\fP \fI(since C++11)\fP - std::iterator_traits::value_type& rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<( const typename \fB(33)\fP \fI(since C++11)\fP - std::iterator_traits::value_type& rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<=( const typename \fB(34)\fP \fI(since C++11)\fP - std::iterator_traits::value_type& rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>( const typename \fB(35)\fP \fI(since C++11)\fP - std::iterator_traits::value_type& rhs, - - const sub_match& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>=( const typename \fB(36)\fP \fI(since C++11)\fP - std::iterator_traits::value_type& rhs, - - const sub_match& rhs ); - std::sub_match and std::iterator_traits::value_type& - template< class BidirIt, class Traits, class Alloc > - - bool operator==( const sub_match& lhs, \fB(37)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator!=( const sub_match& lhs, \fB(38)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<( const sub_match& lhs, \fB(39)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator<=( const sub_match& lhs, \fB(40)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>( const sub_match& lhs, \fB(41)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type& rhs ); - template< class BidirIt, class Traits, class Alloc > - - bool operator>=( const sub_match& lhs, \fB(42)\fP \fI(since C++11)\fP - - const typename - std::iterator_traits::value_type& rhs ); - - Compares a sub_match to another sub_match, a string, a null-terminated character - sequence or a character. +.SH Synopsis + int compare( const sub_match& m ) const; \fB(1)\fP \fI(since C++11)\fP + int compare( const string_type& s ) const; \fB(2)\fP \fI(since C++11)\fP + int compare( const value_type* c ) const; \fB(3)\fP \fI(since C++11)\fP - 1-6) Compares two sub_match directly by comparing their underlying character - sequences. Implemented using lhs.str().compare(rhs.str()) - 7-18) Compares a sub_match with a std::basic_string. Implemented using - sm.str().compare(st), where sm is a sub_match and st is a basic_string. - 19-30) Compares a sub_match with a null-terminated string. Implemented using - sm.str().compare(s), where sm is a sub_match and s is a pointer to a null-terminated - character string. - 31-42) Compares a sub_match with a character. Implemented using the following: + 1) Compares two sub_match directly by comparing their underlying character + sequences. Equivalent to str().compare(m.str()). + 2) Compares a sub_match with a std::basic_string. Equivalent to str().compare(s). + 3) Compares a sub_match with a null-terminated sequence of the underlying character + type pointed to by s. Equivalent to str().compare(c). - sm.str().compare(typename sub_match::string_type(1, ch)), where sm is a - sub_match and ch is a character. + This function is infrequently used directly by application code. Instead, one of the + non-member comparison operators is used. .SH Parameters - lhs, rhs - a sub_match, basic_string, pointer to a null-terminated string or a - character to compare + m - a reference to another sub_match + s - a reference to a string to compare to + c - a pointer to a null-terminated character sequence of the underlying value_type + to compare to .SH Return value - true if the corresponding comparison holds as defined by compare(), false otherwise. + A value less than zero if this sub_match is less than the other character sequence, + zero if the both underlying character sequences are equal, greater than zero if this + sub_match is greater than the other character sequence. .SH Example @@ -310,9 +36,24 @@ .SH See also - compare compares matched subsequence (if any) - \fI(public member function)\fP + compares two strings + compare \fI\fI(public member\fP function of\fP + std::basic_string) + str converts to the underlying string type + operator string_type \fI(public member function)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= compares a sub_match with another sub_match, a string, or a + operator<=> character + (removed in C++20) \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) .SH Category: - * Todo no example diff --git a/man/std::sub_match::length.3 b/man/std::sub_match::length.3 index 34c9a3b9c..efe4133a1 100644 --- a/man/std::sub_match::length.3 +++ b/man/std::sub_match::length.3 @@ -1,4 +1,7 @@ -.TH std::sub_match::length 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sub_match::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sub_match::length \- std::sub_match::length + .SH Synopsis difference_type length() const; @@ -13,4 +16,4 @@ .SH Complexity - Constant + Constant. diff --git a/man/std::sub_match::operatorstring_type,std::sub_match::str.3 b/man/std::sub_match::operatorstring_type,std::sub_match::str.3 index fef2e0ce5..e6f13d478 100644 --- a/man/std::sub_match::operatorstring_type,std::sub_match::str.3 +++ b/man/std::sub_match::operatorstring_type,std::sub_match::str.3 @@ -1,4 +1,7 @@ -.TH std::sub_match::operatorstring_type,std::sub_match::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sub_match::operatorstring_type,std::sub_match::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sub_match::operatorstring_type,std::sub_match::str \- std::sub_match::operatorstring_type,std::sub_match::str + .SH Synopsis operator string_type() const; \fB(1)\fP string_type str() const; \fB(2)\fP @@ -14,7 +17,7 @@ .SH Return value Returns the matched character sequence as an object of the underlying - std::basic_string type. If the matched member is false then the empty string is + std::basic_string type. If the matched member is false, then the empty string is returned. .SH Complexity @@ -23,13 +26,31 @@ .SH Example - + // Run this code - std::ssub_match sm; - std::string s = sm; // implicit conversion - std::cout << s.length() << '\\n'; + #include + #include + #include + #include + + int main() + { + const std::string html{R"(")"}; + const std::regex re{"(http|https|ftp)://([a-z]+)\\\\.([a-z]{3})"}; + std::smatch parts; + std::regex_search(html, parts, re); + for (std::ssub_match const& sub : parts) + { + const std::string s = sub; // (1) implicit conversion + assert(s == sub.str()); // (2) + std::cout << s << '\\n'; + } + } .SH Output: - 0 + https://cppreference.com + https + cppreference + com diff --git a/man/std::sub_match::sub_match.3 b/man/std::sub_match::sub_match.3 index 8cb790b89..4b9a33cf9 100644 --- a/man/std::sub_match::sub_match.3 +++ b/man/std::sub_match::sub_match.3 @@ -1,9 +1,12 @@ -.TH std::sub_match::sub_match 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::sub_match::sub_match 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sub_match::sub_match \- std::sub_match::sub_match + .SH Synopsis - constexpr sub_match(); + constexpr sub_match(); \fI(since C++11)\fP Default constructs a std::sub_match. The matched member is set to false and the - value of other members is undefined. + inherited members first and second are value-initialized. This is the only publicly accessible and defined constructor. diff --git a/man/std::sub_sat.3 b/man/std::sub_sat.3 new file mode 100644 index 000000000..bb349954f --- /dev/null +++ b/man/std::sub_sat.3 @@ -0,0 +1,98 @@ +.TH std::sub_sat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::sub_sat \- std::sub_sat + +.SH Synopsis + Defined in header + template< class T > (since C++26) + constexpr T sub_sat( T x, T y ) noexcept; + + Computes the saturating subtraction x - y. This operation (unlike built-in + arithmetic operations on integers) behaves as-if it is a mathematical operation with + an infinite range. Let q denote the result of such operation. Returns: + + * q, if q is representable as a value of type T. Otherwise, + * the largest or smallest value of type T, whichever is closer to the q. + + This overload participates in overload resolution only if T is an integer type, that + is: signed char, short, int, long, long long, an extended signed integer type, or an + unsigned version of such types. In particular, T must not be (possibly cv-qualified) + bool, char, wchar_t, char8_t, char16_t, and char32_t, as these types are not + intended for arithmetic. + +.SH Parameters + + x, y - integer values + +.SH Return value + + Saturated x - y. + +.SH Exceptions + + Throws no exceptions. + +.SH Notes + + Unlike the built-in arithmetic operators on integers, the integral promotion does + not apply to the x and y arguments. + + If two arguments of different type are passed, the call fails to compile, i.e. the + behavior relative to template argument deduction is the same as for std::min or + std::max. + + Most modern hardware architectures have efficient support for saturation arithmetic + on SIMD vectors, including SSE2 for x86 and NEON for ARM. + + Feature-test macro Value Std Feature + __cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic + +.SH Possible implementation + + See libstdc++ (gcc). + +.SH Example + + Can be previewed on Compiler Explorer + + +// Run this code + + #include + #include + + static_assert + ("" + && (std::sub_sat(INT_MIN + 4, 3) == INT_MIN + 1) // not saturated + && (std::sub_sat(INT_MIN + 4, 5) == INT_MIN) // saturated + && (std::sub_sat(INT_MAX - 4, -3) == INT_MAX - 1) // not saturated + && (std::sub_sat(INT_MAX - 4, -5) == INT_MAX) // saturated + && (std::sub_sat(4, 3) == 1) // not saturated + && (std::sub_sat(4, 5) == 0) // saturated + ); + + int main() {} + +.SH See also + + add_sat saturating addition operation on two integers + (C++26) \fI(function template)\fP + mul_sat saturating multiplication operation on two integers + (C++26) \fI(function template)\fP + div_sat saturating division operation on two integers + (C++26) \fI(function template)\fP + saturate_cast returns an integer value clamped to the range of a another integer + (C++26) type + \fI(function template)\fP + clamp clamps a value between a pair of boundary values + \fI(C++17)\fP \fI(function template)\fP + in_range checks if an integer value is in the range of a given integer type + (C++20) \fI(function template)\fP + min returns the smallest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + max returns the largest finite value of the given type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + +.SH External links + + 1. A branch-free implementation of saturation arithmetic — Locklessinc.com, 2012 diff --git a/man/std::submdspan_mapping_result.3 b/man/std::submdspan_mapping_result.3 new file mode 100644 index 000000000..fc6626803 --- /dev/null +++ b/man/std::submdspan_mapping_result.3 @@ -0,0 +1,51 @@ +.TH std::submdspan_mapping_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::submdspan_mapping_result \- std::submdspan_mapping_result + +.SH Synopsis + Defined in header + template< class LayoutMapping > (since C++26) + struct submdspan_mapping_result; + + Specializations of submdspan_mapping_result are result types returned by overloads + of submdspan_mapping. + + This class template has no base classes or declared members other than those shown + below. + +.SH Template parameters + + LayoutMapping - a layout mapping type that meets the requirements of LayoutMapping + + Data members + + Member name Definition + calculated mapping of type LayoutMapping. It is declared with + mapping [[no_unique_address]] attribute. + \fI(public member object)\fP + offset calculated offset of type std::size_t. + \fI(public member object)\fP + + All these members have default member initializers where each data member is value + initialized. + +.SH See also + + submdspan returns a view of a subset of an + (C++26) existing mdspan + \fI(function template)\fP + calculates the mapping and data + submdspan_mapping(std::layout_left::mapping) handle offset used for subdmspan + (C++26) \fI\fI(public member\fP function of\fP + std::layout_left::mapping) + + calculates the mapping and data + submdspan_mapping(std::layout_right::mapping) handle offset used for subdmspan + (C++26) \fI\fI(public member\fP function of\fP + std::layout_right::mapping) + + calculates the mapping and data + submdspan_mapping(std::layout_stride::mapping) handle offset used for subdmspan + (C++26) \fI\fI(public member\fP function of\fP + std::layout_stride::mapping) + diff --git a/man/std::subtract_with_carry_engine.3 b/man/std::subtract_with_carry_engine.3 index b2d33603e..d59e96d86 100644 --- a/man/std::subtract_with_carry_engine.3 +++ b/man/std::subtract_with_carry_engine.3 @@ -1,72 +1,124 @@ -.TH std::subtract_with_carry_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine \- std::subtract_with_carry_engine + .SH Synopsis Defined in header template< - class UIntType, \fI(since C++11)\fP - size_t w, size_t s, size_t r + class UIntType, \fI(since C++11)\fP + std::size_t w, std::size_t s, std::size_t r > class subtract_with_carry_engine; - subtract_with_carry_engine is a random number engine that uses subtract with carry - algorithm. + Is a random number engine that uses subtract with carry algorithm. - This section is incomplete +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + UIntType - this is not one of unsigned short, unsigned int, unsigned long, or + unsigned long long. + w - the word size, in bits, of the state sequence + s - the short lag + r - the long lag + + If w is not in [1, std::numeric_limits::digits], or s is not in [1, r), + the program is ill-formed. + + Generator properties + + The size of the states of subtract_with_carry_engine is \\(O(r)\\)O(r), each of them + consists of two parts: + + * A sequence X of r integer values, where each value is in [0, 2w + ). + * An integer c (known as the carry ), whose value is either 0 or 1. + + Given that \\(X_j\\)X + j stands for the \\(j\\mod r\\)j mod rth value (starting from 0) of X, the transition + algorithm of subtract_with_carry_engine (\\(TA(x_i)\\)TA(x + i)) is defined as follows: + + 1. Let Y be \\(X_{i-s}-X_{i-r}-c\\)X + i-s-X + i-r-c. + 2. Let y be \\(Y\\mod 2^w\\)Y mod 2w + , and set \\(X_i\\)X + i to y. + 3. If Y is negative, set c to 1, otherwise set c to 0. + + The generation algorithm of subtract_with_carry_engine is \\(GA(x_i) = y\\)GA(x + i) = y, where y is the value produced in step 2 of the transition algorithm. - The following typedefs define the random number engine with two commonly used + Predefined specializations + + The following specializations define the random number engine with two commonly used parameter sets: Defined in header - Type Definition - ranlux24_base std::subtract_with_carry_engine - ranlux48_base std::subtract_with_carry_engine + Type Definition + ranlux24_base std::subtract_with_carry_engine + ranlux48_base std::subtract_with_carry_engine + + Nested types + + Type Definition + result_type UIntType -.SH Member types + Data members - Member type Definition - result_type The integral type generated by the engine. Results are undefined if this - is not an unsigned integral type. + constexpr std::size_t word_size w + \fB[static]\fP \fI(public static member constant)\fP + constexpr std::size_t short_lag s + \fB[static]\fP \fI(public static member constant)\fP + constexpr std::size_t long_lag r + \fB[static]\fP \fI(public static member constant)\fP + constexpr std::uint_least32_t default_seed 19780503u + \fB[static]\fP \fI(public static member constant)\fP .SH Member functions .SH Construction and Seeding - constructor constructs the engine - \fI(public member function)\fP - seed sets the current state of the engine - \fI(public member function)\fP + constructor constructs the engine + \fI(C++11)\fP \fI(public member function)\fP + seed sets the current state of the engine + \fI(C++11)\fP \fI(public member function)\fP .SH Generation - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP - discard advances the engine's state by a specified amount - \fI(public member function)\fP + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP + discard advances the engine's state by a specified amount + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP .SH Non-member functions - operator== compares the internal states of two pseudo-random number engines - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number engine - operator>> \fI(function)\fP - -.SH Member objects - - constexpr size_t word_size This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t short_lag This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr size_t long_lag This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP - constexpr UIntType default_seed This section is incomplete - \fB[static]\fP - \fI(public static member constant)\fP + operator== compares the internal states of two pseudo-random number + operator!= engines + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> engine + \fI(C++11)\fP \fI(function template)\fP -.SH Category: +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo without reason + DR Applied to Behavior as published Correct behavior + LWG 3809 C++11 default_seed might not be changed its type to + representable with result_type std::uint_least32_t + +.SH Category: + * Todo no example diff --git a/man/std::subtract_with_carry_engine::discard.3 b/man/std::subtract_with_carry_engine::discard.3 index 0c2951847..a04737fa1 100644 --- a/man/std::subtract_with_carry_engine::discard.3 +++ b/man/std::subtract_with_carry_engine::discard.3 @@ -1,9 +1,12 @@ -.TH std::subtract_with_carry_engine::discard 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine::discard 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine::discard \- std::subtract_with_carry_engine::discard + .SH Synopsis void discard( unsigned long long z ); \fI(since C++11)\fP Advances the internal state by z times. Equivalent to calling operator() z times and - discarding the result + discarding the result. .SH Parameters @@ -15,13 +18,15 @@ .SH Complexity - This section is incomplete + No worse than the complexity of z consecutive calls to operator(). -.SH See also +.SH Notes - operator() advances the engine's state and returns the generated value - \fI(public member function)\fP + For some engines, "fast jump" algorithms are known, which advance the state by many + steps (order of millions) without calculating intermediate state transitions, + although not necessarily in constant time. -.SH Category: +.SH See also - * Todo without reason + operator() advances the engine's state and returns the generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::subtract_with_carry_engine::max.3 b/man/std::subtract_with_carry_engine::max.3 index d7a50d565..793168418 100644 --- a/man/std::subtract_with_carry_engine::max.3 +++ b/man/std::subtract_with_carry_engine::max.3 @@ -1,8 +1,13 @@ -.TH std::subtract_with_carry_engine::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine::max \- std::subtract_with_carry_engine::max + .SH Synopsis static constexpr result_type max(); \fI(since C++11)\fP - Returns the maximum value potentially generated by the random-number engine. + Returns the maximum value potentially generated by the random-number engine. This + value is equal to 2w + - 1, where w is the template parameter also accessible as static member word_size. .SH Parameters @@ -14,9 +19,9 @@ .SH Complexity - Constant + Constant. .SH See also - min gets the smallest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + min gets the smallest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::subtract_with_carry_engine::min.3 b/man/std::subtract_with_carry_engine::min.3 index 684d1a201..34002def3 100644 --- a/man/std::subtract_with_carry_engine::min.3 +++ b/man/std::subtract_with_carry_engine::min.3 @@ -1,8 +1,12 @@ -.TH std::subtract_with_carry_engine::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine::min \- std::subtract_with_carry_engine::min + .SH Synopsis static constexpr result_type min(); \fI(since C++11)\fP - Returns the minimum value potentially generated by the random-number engine. + Returns the minimum value potentially generated by the random-number engine. This + value is equal to 0u. .SH Parameters @@ -10,13 +14,13 @@ .SH Return value - The maximum potentially generated value. + The minimum potentially generated value. .SH Complexity - Constant + Constant. .SH See also - max gets the largest possible value in the output range - \fB[static]\fP \fI(public static member function)\fP + max gets the largest possible value in the output range + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::subtract_with_carry_engine::operator().3 b/man/std::subtract_with_carry_engine::operator().3 index 9bde303f3..5414bdf0a 100644 --- a/man/std::subtract_with_carry_engine::operator().3 +++ b/man/std::subtract_with_carry_engine::operator().3 @@ -1,4 +1,7 @@ -.TH std::subtract_with_carry_engine::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine::operator() \- std::subtract_with_carry_engine::operator() + .SH Synopsis result_type operator()(); \fI(since C++11)\fP @@ -22,8 +25,7 @@ .SH See also discard advances the engine's state by a specified amount - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo without reason diff --git a/man/std::subtract_with_carry_engine::seed.3 b/man/std::subtract_with_carry_engine::seed.3 index 2cf01f0ac..4827f085d 100644 --- a/man/std::subtract_with_carry_engine::seed.3 +++ b/man/std::subtract_with_carry_engine::seed.3 @@ -1,26 +1,37 @@ -.TH std::subtract_with_carry_engine::seed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine::seed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine::seed \- std::subtract_with_carry_engine::seed + .SH Synopsis - void seed( result_type value = default_seed ); \fB(1)\fP \fI(since C++11)\fP - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP - void seed( Sseq& seq ); + void seed( result_type value = 0u ); \fB(1)\fP \fI(since C++11)\fP + template< class SeedSeq > \fB(2)\fP \fI(since C++11)\fP + void seed( SeedSeq& seq ); - Reinitializes the internal state of the random-number engine using new seed value. + Sets the state of the random-number engine. - This section is incomplete + 1) Right after the state is set, *this == std::subtract_with_carry_engine(value) is + true. + 2) Right after the state is set, *this == std::subtract_with_carry_engine(seq) is + true. .SH Parameters - value - seed value to use in the initialization of the internal state - seq - seed sequence to use in the initialization of the internal state + value - seed value to use to set the state + seq - seed sequence to use to set the state .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Complexity - This section is incomplete + 1) Same as std::subtract_with_carry_engine(value). + 2) Same as std::subtract_with_carry_engine(seq). + + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo without reason + DR Applied to Behavior as published Correct behavior + LWG 3809 C++11 the default argument of value was default_seed changed to 0u diff --git a/man/std::subtract_with_carry_engine::subtract_with_carry_engine.3 b/man/std::subtract_with_carry_engine::subtract_with_carry_engine.3 index 1e9902baf..4da63c416 100644 --- a/man/std::subtract_with_carry_engine::subtract_with_carry_engine.3 +++ b/man/std::subtract_with_carry_engine::subtract_with_carry_engine.3 @@ -1,28 +1,78 @@ -.TH std::subtract_with_carry_engine::subtract_with_carry_engine 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::subtract_with_carry_engine::subtract_with_carry_engine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::subtract_with_carry_engine::subtract_with_carry_engine \- std::subtract_with_carry_engine::subtract_with_carry_engine + .SH Synopsis - explicit subtract_with_carry_engine( result_type value = \fB(1)\fP \fI(since C++11)\fP - default_seed ); - template< class Sseq > \fB(2)\fP \fI(since C++11)\fP - explicit subtract_with_carry_engine( Sseq& s ); + subtract_with_carry_engine() : \fB(1)\fP \fI(since C++11)\fP + subtract_with_carry_engine(0u) {} + explicit subtract_with_carry_engine( result_type value ); \fB(2)\fP \fI(since C++11)\fP + template< class SeedSeq > \fB(3)\fP \fI(since C++11)\fP + explicit subtract_with_carry_engine( SeedSeq& seq ); + subtract_with_carry_engine( const \fB(4)\fP \fI(since C++11)\fP + subtract_with_carry_engine& other ); (implicitly declared) Constructs the pseudo-random number engine. - This section is incomplete + 1) The default constructor. + 2) Constructs the engine with a seed value value. The sequence X of the engine's + initial state is determined as follows: + 1. Constructs a std::linear_congruential_engine object e with argument value == 0u ? default_seed : value. + 2. Let n be std::size_t(w / 32) + 1. + 3. Sets the values of \\(X_{-r}\\)X + -r, ..., \\(X_{-1}\\)X + -1, in that order. Each value \\(X_i\\)X + i is set as specified below: + + 1. Successively calls e for n times, the return values are denoted as \\(z_0\\)z + 0 ... \\(z_{n-1}\\)z + n-1. + 2. Sets \\(X_i\\)X + i to \\((\\sum^{n-1}_{j=0} z_j \\cdot 2^{32j}) \\mod m\\)(∑n-1 + j=0 z + j·232j + ) mod m. + If \\(X_{-1}\\)X + -1 is 0, sets the carry value c of the engine's initial state to 1. Otherwise, sets + c to 0. + 3) Constructs the engine with a seed sequence seq. Given std::size_t(w / 32) + 1 as + k, the sequence X of the engine's initial state is determined as follows: + 1. Creates an invented array object a of length r * k. + 2. Calls seq.generate(a + 0, a + r * k). + 3. For each integer i in [-r, -1], sets \\(X_{i}\\)X + i to \\((\\sum^{k-1}_{j=0} a_{k(i+r)+j} \\cdot 2^{32j}) \\mod m\\)(∑k-1 + j=0 a + k(i+r)+j·232j + ) mod m. + If \\(X_{-1}\\)X + -1 is 0, sets the carry value c of the engine's initial state to 1. Otherwise, sets + c to 0. + This overload participates in overload resolution only if SeedSeq meets the + requirements of SeedSequence. + 4) The copy constructor. Upon construction, *this == other is true. .SH Parameters value - seed value to use in the initialization of the internal state - s - seed sequence to use in the initialization of the internal state + seq - seed sequence to use in the initialization of the internal state .SH Complexity - This section is incomplete + 1,2) (std::size_t(w / 32) + 1) * r invocations of e. + 3) Same as the complexity of the seq.generate call. + 4) \\(\\small{O(r)}\\)O(r). -.SH See also + Defect reports - seed sets the current state of the engine - \fI(public member function)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + LWG 3809 C++11 e could not be constructed if e can be constructed in + result_type is std::uint16_t this case + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also - * Todo without reason + seed sets the current state of the engine + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::suspend_always.3 b/man/std::suspend_always.3 new file mode 100644 index 000000000..035bb59ba --- /dev/null +++ b/man/std::suspend_always.3 @@ -0,0 +1,52 @@ +.TH std::suspend_always 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::suspend_always \- std::suspend_always + +.SH Synopsis + Defined in header + struct suspend_always; \fI(since C++20)\fP + + suspend_always is an empty class which can be used to indicate that an await + expression always suspends and does not produce a value. + +.SH Member functions + + await_ready indicates that an await expression always suspends + (C++20) \fI(public member function)\fP + await_suspend no-op + (C++20) \fI(public member function)\fP + await_resume no-op + (C++20) \fI(public member function)\fP + +std::suspend_always::await_ready + + constexpr bool await_ready() const noexcept { return false; } \fI(since C++20)\fP + + Always returns false, indicating that an await expression always suspends. + +std::suspend_always::await_suspend + + constexpr void await_suspend( std::coroutine_handle<> ) const \fI(since C++20)\fP + noexcept {} + + Does nothing. + +std::suspend_always::await_resume + + constexpr void await_resume() const noexcept {} \fI(since C++20)\fP + + Does nothing. An await expression does not produce a value if suspend_always is + used. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + suspend_never indicates that an await-expression should never suspend + (C++20) \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::suspend_never.3 b/man/std::suspend_never.3 new file mode 100644 index 000000000..9bc3950f0 --- /dev/null +++ b/man/std::suspend_never.3 @@ -0,0 +1,51 @@ +.TH std::suspend_never 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::suspend_never \- std::suspend_never + +.SH Synopsis + Defined in header + struct suspend_never; \fI(since C++20)\fP + + suspend_never is an empty class which can be used to indicate that an await + expression never suspends and does not produce a value. + +.SH Member functions + + await_ready indicates that an await expression never suspends + (C++20) \fI(public member function)\fP + await_suspend no-op + (C++20) \fI(public member function)\fP + await_resume no-op + (C++20) \fI(public member function)\fP + +std::suspend_never::await_ready + + constexpr bool await_ready() const noexcept { return true; } \fI(since C++20)\fP + + Always returns true, indicating that an await expression never suspends. + +std::suspend_never::await_suspend + + constexpr void await_suspend( std::coroutine_handle<> ) const \fI(since C++20)\fP + noexcept {} + + Does nothing. + +std::suspend_never::await_resume + + constexpr void await_resume() const noexcept {} \fI(since C++20)\fP + + Does nothing. An await expression does not produce a value if suspend_never is used. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + suspend_always indicates that an await-expression should always suspend + (C++20) \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::any).3 b/man/std::swap(std::any).3 new file mode 100644 index 000000000..46838a150 --- /dev/null +++ b/man/std::swap(std::any).3 @@ -0,0 +1,23 @@ +.TH std::swap(std::any) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::any) \- std::swap(std::any) + +.SH Synopsis + Defined in header + void swap( any& lhs, any& rhs ) noexcept; \fI(since C++17)\fP + + Overloads the std::swap algorithm for std::any. Swaps the content of two any objects + by calling lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - objects to swap + +.SH Return value + + \fI(none)\fP + +.SH See also + + swap swaps two any objects + \fI(public member function)\fP diff --git a/man/std::swap(std::array).3 b/man/std::swap(std::array).3 index 03d7b6dab..74b542c70 100644 --- a/man/std::swap(std::array).3 +++ b/man/std::swap(std::array).3 @@ -1,14 +1,27 @@ -.TH std::swap(std::array) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::array) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::array) \- std::swap(std::array) + .SH Synopsis + Defined in header + template< class T, std::size_t N > + \fI(since C++11)\fP + void swap( std::array& lhs, \fI(until C++17)\fP + + std::array& rhs ); template< class T, std::size_t N > - void swap( array& lhs, \fI(since C++11)\fP + void swap( std::array& lhs, \fI(since C++17)\fP + std::array& rhs ) (constexpr since C++20) - array& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::array. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). + This overload participates in overload resolution only if N == 0 or \fI(since C++17)\fP + std::is_swappable_v is true. + .SH Parameters lhs, rhs - containers whose contents to swap @@ -21,7 +34,57 @@ Linear in size of the container. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::array alice{1, 2, 3}; + std::array bob{7, 8, 9}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 + -- SWAP + Alice: 7 8 9 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::basic_filebuf).3 b/man/std::swap(std::basic_filebuf).3 index 520b3ff97..ecf34f1b9 100644 --- a/man/std::swap(std::basic_filebuf).3 +++ b/man/std::swap(std::basic_filebuf).3 @@ -1,4 +1,7 @@ -.TH std::swap(std::basic_filebuf) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_filebuf) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_filebuf) \- std::swap(std::basic_filebuf) + .SH Synopsis template< class CharT, class Traits > @@ -25,10 +28,9 @@ .SH See also swap swaps two basic_filebuf objects - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps the values of two objects - \fI(function template)\fP + \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::basic_fstream).3 b/man/std::swap(std::basic_fstream).3 index 448347321..52fea5373 100644 --- a/man/std::swap(std::basic_fstream).3 +++ b/man/std::swap(std::basic_fstream).3 @@ -1,7 +1,10 @@ -.TH std::swap(std::basic_fstream) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_fstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_fstream) \- std::swap(std::basic_fstream) + .SH Synopsis - template< class T > - void swap( basic_fstream &lhs, basic_fstream &rhs ); + template< class CharT, class Traits > + void swap( basic_fstream& lhs, basic_fstream& rhs ); Specializes the std::swap algorithm for std::basic_fstream. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -16,18 +19,46 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + #include + #include + #include + + bool create_stream(std::fstream& fs) + { + try + { + std::string some_name = "/tmp/test_file.txt"; + std::ios_base::openmode some_flags = fs.trunc; // | other flags -.SH Category: + if (std::fstream ts{some_name, some_flags}; ts.is_open()) + { + std::swap(ts, fs); // stream objects are not copyable => swap + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } - * Todo no example + int main() + { + if (std::fstream fs; create_stream(fs)) + { + // use fs stream + } + } + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::swap(std::basic_ifstream).3 b/man/std::swap(std::basic_ifstream).3 index 9b6cefe7e..190ada5c1 100644 --- a/man/std::swap(std::basic_ifstream).3 +++ b/man/std::swap(std::basic_ifstream).3 @@ -1,7 +1,11 @@ -.TH std::swap(std::basic_ifstream) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_ifstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_ifstream) \- std::swap(std::basic_ifstream) + .SH Synopsis - template< class T > - void swap( basic_ifstream &lhs, basic_ifstream &rhs ); + template< class CharT, class Traits > + void swap( basic_ifstream& lhs, basic_ifstream& rhs + ); Specializes the std::swap algorithm for std::basic_ifstream. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -16,18 +20,46 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + #include + #include + #include + + bool create_stream(std::ifstream& fs) + { + try + { + std::string some_name = "/tmp/test_file.txt"; + std::ios_base::openmode some_flags = fs.trunc; // | other flags -.SH Category: + if (std::ifstream ts{some_name, some_flags}; ts.is_open()) + { + std::swap(ts, fs); // stream objects are not copyable => swap + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } - * Todo no example + int main() + { + if (std::ifstream fs; create_stream(fs)) + { + // use fs stream + } + } + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::swap(std::basic_ispanstream).3 b/man/std::swap(std::basic_ispanstream).3 new file mode 100644 index 000000000..2440c5f7b --- /dev/null +++ b/man/std::swap(std::basic_ispanstream).3 @@ -0,0 +1,39 @@ +.TH std::swap(std::basic_ispanstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_ispanstream) \- std::swap(std::basic_ispanstream) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + void swap( std::basic_ispanstream& lhs, (since C++23) + + std::basic_ispanstream& rhs ); + + Overloads the std::swap algorithm for std::basic_ispanstream. Exchanges the state of + lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - streams whose state to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_ispanstream objects + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::basic_istringstream).3 b/man/std::swap(std::basic_istringstream).3 index 3fa75436b..87590057d 100644 --- a/man/std::swap(std::basic_istringstream).3 +++ b/man/std::swap(std::basic_istringstream).3 @@ -1,10 +1,17 @@ -.TH std::swap(std::basic_istringstream) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_istringstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_istringstream) \- std::swap(std::basic_istringstream) + .SH Synopsis - template< class T > - void swap( basic_istringstream& lhs, basic_istringstream& rhs ); + Defined in header + template< class CharT, class Traits, class Alloc > + + void swap( std::basic_istringstream& lhs, \fI(since C++11)\fP + + std::basic_istringstream& rhs ); - Specializes the std::swap algorithm for std::basic_istringstream. Exchanges the - state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + Overloads the std::swap algorithm for std::basic_istringstream. Exchanges the state + of lhs with that of rhs. Effectively calls lhs.swap(rhs). .SH Parameters @@ -16,7 +23,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -26,8 +33,7 @@ .SH See also swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::basic_ofstream).3 b/man/std::swap(std::basic_ofstream).3 index 141c9a33a..9990a35f3 100644 --- a/man/std::swap(std::basic_ofstream).3 +++ b/man/std::swap(std::basic_ofstream).3 @@ -1,7 +1,11 @@ -.TH std::swap(std::basic_ofstream) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_ofstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_ofstream) \- std::swap(std::basic_ofstream) + .SH Synopsis - template< class T > - void swap( basic_ofstream &lhs, basic_ofstream &rhs ); + template< class CharT, class Traits > + void swap( basic_ofstream& lhs, basic_ofstream& rhs + ); Specializes the std::swap algorithm for std::basic_ofstream. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -16,18 +20,46 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - swap swaps two file streams - \fI(C++11)\fP \fI(public member function)\fP + #include + #include + #include + + bool create_stream(std::ofstream& fs) + { + try + { + std::string some_name = "/tmp/test_file.txt"; + std::ios_base::openmode some_flags = fs.trunc; // | other flags -.SH Category: + if (std::ofstream ts{some_name, some_flags}; ts.is_open()) + { + std::swap(ts, fs); // stream objects are not copyable => swap + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } - * Todo no example + int main() + { + if (std::ofstream fs; create_stream(fs)) + { + // use fs stream + } + } + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::swap(std::basic_ospanstream).3 b/man/std::swap(std::basic_ospanstream).3 new file mode 100644 index 000000000..71a7e8ec1 --- /dev/null +++ b/man/std::swap(std::basic_ospanstream).3 @@ -0,0 +1,39 @@ +.TH std::swap(std::basic_ospanstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_ospanstream) \- std::swap(std::basic_ospanstream) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + void swap( std::basic_ospanstream& lhs, (since C++23) + + std::basic_ospanstream& rhs ); + + Overloads the std::swap algorithm for std::basic_ospanstream. Exchanges the state of + lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - streams whose state to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_ospanstream objects + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::basic_ostringstream).3 b/man/std::swap(std::basic_ostringstream).3 index e402dd766..89930d6f1 100644 --- a/man/std::swap(std::basic_ostringstream).3 +++ b/man/std::swap(std::basic_ostringstream).3 @@ -1,10 +1,17 @@ -.TH std::swap(std::basic_ostringstream) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_ostringstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_ostringstream) \- std::swap(std::basic_ostringstream) + .SH Synopsis - template< class T > - void swap( basic_ostringstream& lhs, basic_ostringstream& rhs ); + Defined in header + template< class CharT, class Traits, class Alloc > + + void swap( std::basic_ostringstream& lhs, \fI(since C++11)\fP + + std::basic_ostringstream& rhs ); - Specializes the std::swap algorithm for std::basic_ostringstream. Exchanges the - state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + Overloads the std::swap algorithm for std::basic_ostringstream. Exchanges the state + of lhs with that of rhs. Effectively calls lhs.swap(rhs). .SH Parameters @@ -16,7 +23,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -26,8 +33,7 @@ .SH See also swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::basic_regex).3 b/man/std::swap(std::basic_regex).3 index 7ac39d262..0ce75f784 100644 --- a/man/std::swap(std::basic_regex).3 +++ b/man/std::swap(std::basic_regex).3 @@ -1,8 +1,11 @@ -.TH std::swap(std::basic_regex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_regex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_regex) \- std::swap(std::basic_regex) + .SH Synopsis template< class CharT, class Traits > - void swap( basic_regex &lhs, basic_regex \fI(since C++11)\fP - &rhs ); + void swap( basic_regex& lhs, basic_regex& rhs ) noexcept; Overloads the std::swap algorithm for std::basic_regex. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -15,12 +18,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -29,8 +26,7 @@ .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::basic_spanbuf).3 b/man/std::swap(std::basic_spanbuf).3 new file mode 100644 index 000000000..4f1336254 --- /dev/null +++ b/man/std::swap(std::basic_spanbuf).3 @@ -0,0 +1,41 @@ +.TH std::swap(std::basic_spanbuf) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_spanbuf) \- std::swap(std::basic_spanbuf) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + void swap( std::basic_spanbuf& lhs, (since C++23) + + std::basic_spanbuf& rhs ); + + Overloads the std::swap algorithm for std::basic_spanbuf. Exchanges the state of lhs + with that of rhs. Equivalent to lhs.swap(rhs);. + +.SH Parameters + + lhs, rhs - std::basic_spanbuf objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_spanbuf objects + (C++23) \fI(public member function)\fP + swap swaps the values of two objects + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::basic_spanstream).3 b/man/std::swap(std::basic_spanstream).3 new file mode 100644 index 000000000..1eaa3efba --- /dev/null +++ b/man/std::swap(std::basic_spanstream).3 @@ -0,0 +1,39 @@ +.TH std::swap(std::basic_spanstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_spanstream) \- std::swap(std::basic_spanstream) + +.SH Synopsis + Defined in header + template< class CharT, class Traits > + + void swap( std::basic_spanstream& lhs, (since C++23) + + std::basic_spanstream& rhs ); + + Overloads the std::swap algorithm for std::basic_spanstream. Exchanges the state of + lhs with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - streams whose state to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_spanstream objects + (C++23) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::basic_stacktrace).3 b/man/std::swap(std::basic_stacktrace).3 new file mode 100644 index 000000000..664dc0402 --- /dev/null +++ b/man/std::swap(std::basic_stacktrace).3 @@ -0,0 +1,40 @@ +.TH std::swap(std::basic_stacktrace) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_stacktrace) \- std::swap(std::basic_stacktrace) + +.SH Synopsis + Defined in header + template< class Allocator > + + void swap( std::basic_stacktrace& lhs, (since C++23) + std::basic_stacktrace& rhs ) + + noexcept(noexcept(lhs.swap(rhs))); + + Specializes the std::swap algorithm for std::basic_stacktrace. Swaps the contents of + lhs and rhs. Equivalent to lhs.swap(rhs);. + +.SH Parameters + + lhs, rhs - stacktraces whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps the contents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::basic_string).3 b/man/std::swap(std::basic_string).3 index 2574f9d70..7e1823aa4 100644 --- a/man/std::swap(std::basic_string).3 +++ b/man/std::swap(std::basic_string).3 @@ -1,11 +1,25 @@ -.TH std::swap(std::basic_string) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_string) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_string) \- std::swap(std::basic_string) + .SH Synopsis - template< class T, class Traits, class Alloc > - void swap( basic_string &lhs, basic_string - &rhs ); + Defined in header + template< class CharT, class Traits, class Alloc > + + void swap( std::basic_string& lhs, \fI(until C++17)\fP + + std::basic_string& rhs ); + template< class CharT, class Traits, class Alloc > + + void swap( std::basic_string& lhs, \fI(since C++17)\fP + (constexpr since C++20) + std::basic_string& rhs ) + noexcept(/* see below */); Specializes the std::swap algorithm for std::basic_string. Swaps the contents of lhs - and rhs. Equivalent to lhs.swap(rhs). + and rhs. + + Equivalent to lhs.swap(rhs). .SH Parameters @@ -19,7 +33,58 @@ Constant. +.SH Exceptions + \fI(since C++17)\fP + noexcept specification: + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "AAA"; + std::string b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + std::swap(a, b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2064 C++11 non-member swap was noexcept and inconsistent noexcept removed + with member swap + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::basic_stringbuf).3 b/man/std::swap(std::basic_stringbuf).3 index 7bcf9c85e..b2c3e31ce 100644 --- a/man/std::swap(std::basic_stringbuf).3 +++ b/man/std::swap(std::basic_stringbuf).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::basic_stringbuf) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_stringbuf) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_stringbuf) \- std::swap(std::basic_stringbuf) + .SH Synopsis - template< class CharT, class Traits > + Defined in header + template< class CharT, class Traits, class Alloc > + \fI(since C++11)\fP + void swap( std::basic_stringbuf& lhs, \fI(until C++20)\fP + + std::basic_stringbuf& rhs ); + template< class CharT, class Traits, class Alloc > - void swap( std::basic_stringbuf& lhs, \fI(since C++11)\fP + void swap( std::basic_stringbuf& lhs, \fI(since C++20)\fP + std::basic_stringbuf& rhs ) - std::basic_stringbuf& rhs ); + noexcept(noexcept(lhs.swap(rhs))); Overloads the std::swap algorithm for std::basic_stringbuf. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -25,10 +35,9 @@ .SH See also swap swaps two basic_stringbuf objects - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP swap swaps the values of two objects - \fI(function template)\fP + \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::basic_stringstream).3 b/man/std::swap(std::basic_stringstream).3 index 8bdcfc5df..0efb7d722 100644 --- a/man/std::swap(std::basic_stringstream).3 +++ b/man/std::swap(std::basic_stringstream).3 @@ -1,9 +1,16 @@ -.TH std::swap(std::basic_stringstream) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::basic_stringstream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_stringstream) \- std::swap(std::basic_stringstream) + .SH Synopsis - template< class T > - void swap( basic_stringstream& lhs, basic_stringstream& rhs ); + Defined in header + template< class CharT, class Traits, class Alloc > + + void swap( std::basic_stringstream& lhs, \fI(since C++11)\fP + + std::basic_stringstream& rhs ); - Specializes the std::swap algorithm for std::basic_stringstream. Exchanges the state + Overloads the std::swap algorithm for std::basic_stringstream. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). .SH Parameters @@ -16,7 +23,7 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example @@ -26,8 +33,7 @@ .SH See also swap swaps two string streams - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::basic_syncbuf).3 b/man/std::swap(std::basic_syncbuf).3 new file mode 100644 index 000000000..1135c2a6a --- /dev/null +++ b/man/std::swap(std::basic_syncbuf).3 @@ -0,0 +1,36 @@ +.TH std::swap(std::basic_syncbuf) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::basic_syncbuf) \- std::swap(std::basic_syncbuf) + +.SH Synopsis + template< class CharT, class Traits, class Allocator > + + void swap( std::basic_syncbuf& lhs, \fI(since C++20)\fP + + std::basic_syncbuf& rhs ); + + Overloads the std::swap algorithm for std::basic_syncbuf. Exchanges the state of lhs + with that of rhs. Effectively calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - std::basic_syncbuf objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two basic_syncbuf objects + \fI(public member function)\fP + swap swaps the values of two objects + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::swap(std::deque).3 b/man/std::swap(std::deque).3 index 5290d2bf4..2c0bddf2c 100644 --- a/man/std::swap(std::deque).3 +++ b/man/std::swap(std::deque).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::deque) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::deque) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::deque) \- std::swap(std::deque) + .SH Synopsis + Defined in header template< class T, class Alloc > - void swap( deque& lhs, + void swap( std::deque& lhs, \fI(until C++17)\fP + + std::deque& rhs ); + template< class T, class Alloc > - deque& rhs ); + void swap( std::deque& lhs, \fI(since C++17)\fP + std::deque& rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::deque. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::deque alice{1, 2, 3}; + std::deque bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::experimental::optional).3 b/man/std::swap(std::experimental::optional).3 deleted file mode 100644 index 1af7bb0de..000000000 --- a/man/std::swap(std::experimental::optional).3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::swap(std::experimental::optional) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T > (library fundamentals TS) - void swap( optional& lhs, optional& rhs ); - - Overloads the std::swap algorithm for std::experimental::optional. Exchanges the - state of lhs with that of rhs. Effectively calls lhs.swap(rhs). - -.SH Parameters - - lhs, rhs - optional objects whose states to swap - -.SH Return value - - \fI(none)\fP - -.SH Exceptions - - noexcept specification: \fI(since C++11)\fP - noexcept(lhs.swap(rhs)) - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - swap exchanges the contents - \fI(public member function)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::swap(std::flat_map).3 b/man/std::swap(std::flat_map).3 new file mode 100644 index 000000000..5d3e7d6c4 --- /dev/null +++ b/man/std::swap(std::flat_map).3 @@ -0,0 +1,72 @@ +.TH std::swap(std::flat_map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::flat_map) \- std::swap(std::flat_map) + +.SH Synopsis + Defined in header + friend void swap( std::flat_map& lhs, std::flat_map& rhs ) noexcept; (since C++23) + + Specializes the std::swap algorithm for std::flat_map. Swaps the contents of lhs and + rhs. Calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - containers whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Same as swapping the underlying containers. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_map alice{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + std::flat_map bob{{7, 'Z'}, {8, 'Y'}, {9, 'X'}, {10, 'W'}}; + + auto print = [](std::pair& n) + { + std::cout << ' ' << n.first << ':' << n.second; + }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1:a 2:b 3:c + Bob : 7:Z 8:Y 9:X 10:W + -- SWAP + Alice: 7:Z 8:Y 9:X 10:W + Bob : 1:a 2:b 3:c + +.SH See also + + swap swaps the contents + \fI(public member function)\fP diff --git a/man/std::swap(std::flat_multimap).3 b/man/std::swap(std::flat_multimap).3 new file mode 100644 index 000000000..4294f6e51 --- /dev/null +++ b/man/std::swap(std::flat_multimap).3 @@ -0,0 +1,73 @@ +.TH std::swap(std::flat_multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::flat_multimap) \- std::swap(std::flat_multimap) + +.SH Synopsis + Defined in header + friend void swap( std::flat_multimap& lhs, std::flat_multimap& rhs ) (since C++23) + noexcept; + + Specializes the std::swap algorithm for std::flat_multimap. Swaps the contents of + lhs and rhs. Calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - containers whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Same as swapping the underlying containers. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multimap alice{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + std::flat_multimap bob{{7, 'Z'}, {8, 'Y'}, {9, 'X'}, {10, 'W'}}; + + auto print = [](std::pair& n) + { + std::cout << ' ' << n.first << ':' << n.second; + }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1:a 2:b 3:c + Bob : 7:Z 8:Y 9:X 10:W + -- SWAP + Alice: 7:Z 8:Y 9:X 10:W + Bob : 1:a 2:b 3:c + +.SH See also + + swap swaps the contents + \fI(public member function)\fP diff --git a/man/std::swap(std::flat_multiset).3 b/man/std::swap(std::flat_multiset).3 new file mode 100644 index 000000000..da20c197e --- /dev/null +++ b/man/std::swap(std::flat_multiset).3 @@ -0,0 +1,70 @@ +.TH std::swap(std::flat_multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::flat_multiset) \- std::swap(std::flat_multiset) + +.SH Synopsis + Defined in header + friend void swap( std::flat_multiset& lhs, std::flat_multiset& rhs ) (since C++23) + noexcept; + + Specializes the std::swap algorithm for std::flat_multiset. Swaps the contents of + lhs and rhs. Calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - containers whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Same as swapping the underlying container. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_multiset alice{1, 2, 3}; + std::flat_multiset bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + +.SH See also + + swap swaps the contents + \fI(public member function)\fP diff --git a/man/std::swap(std::flat_set).3 b/man/std::swap(std::flat_set).3 new file mode 100644 index 000000000..ff00c2cac --- /dev/null +++ b/man/std::swap(std::flat_set).3 @@ -0,0 +1,69 @@ +.TH std::swap(std::flat_set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::flat_set) \- std::swap(std::flat_set) + +.SH Synopsis + Defined in header + friend void swap( std::flat_set& lhs, std::flat_set& rhs ) noexcept; (since C++23) + + Specializes the std::swap algorithm for std::flat_set. Swaps the contents of lhs and + rhs. Calls lhs.swap(rhs). + +.SH Parameters + + lhs, rhs - containers whose contents to swap + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Same as swapping the underlying container. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::flat_set alice{1, 2, 3}; + std::flat_set bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + +.SH See also + + swap swaps the contents + \fI(public member function)\fP diff --git a/man/std::swap(std::forward_list).3 b/man/std::swap(std::forward_list).3 index bc0133a42..5e70b8341 100644 --- a/man/std::swap(std::forward_list).3 +++ b/man/std::swap(std::forward_list).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::forward_list) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::forward_list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::forward_list) \- std::swap(std::forward_list) + .SH Synopsis + Defined in header + template< class T, class Alloc > + \fI(since C++11)\fP + void swap( std::forward_list& lhs, \fI(until C++17)\fP + + std::forward_list& rhs ); template< class T, class Alloc > - void swap( forward_list& lhs, \fI(since C++11)\fP + void swap( std::forward_list& lhs, \fI(since C++17)\fP + std::forward_list& rhs ) - forward_list& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::forward_list. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::forward_list alice{1, 2, 3}; + std::forward_list bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::fs::path).3 b/man/std::swap(std::fs::path).3 deleted file mode 100644 index 56f1db15d..000000000 --- a/man/std::swap(std::fs::path).3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::swap(std::fs::path) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - void swap( path& lhs, path& rhs ); (filesystem TS) - - Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). - -.SH Parameters - - lhs, rhs - paths whose states to swap - -.SH Return value - - \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - swap swaps two paths - \fI(public member function)\fP diff --git a/man/std::swap(std::function).3 b/man/std::swap(std::function).3 index 2d6be6cfe..1d5b8b6e3 100644 --- a/man/std::swap(std::function).3 +++ b/man/std::swap(std::function).3 @@ -1,7 +1,12 @@ -.TH std::swap(std::function) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::function) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::function) \- std::swap(std::function) + .SH Synopsis - template< class R, class Args... > - void swap( function &lhs, function &rhs ); + Defined in header + template< class R, class... Args > + void swap( std::function& lhs, std::function& \fI(since C++11)\fP + rhs ) noexcept; Overloads the std::swap algorithm for std::function. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -14,20 +19,59 @@ \fI(none)\fP -.SH Exceptions +.SH Example - \fI(none)\fP -.SH Example +// Run this code - This section is incomplete - Reason: no example + #include + #include -.SH See also + void foo(const char* str, int x) + { + std::cout << "foo(\\"" << str << "\\", " << x << ")\\n"; + } + + void bar(const char* str, int x) + { + std::cout << "bar(\\"" << str << "\\", " << x << ")\\n"; + } + + int main() + { + std::function f1{foo}; + std::function f2{bar}; + + f1("f1", 1); + f2("f2", 2); - swap swaps the contents - \fI(public member function)\fP + std::cout << "std::swap(f1, f2);\\n"; + std::swap(f1, f2); -.SH Category: + f1("f1", 1); + f2("f2", 2); + } + +.SH Output: + + foo("f1", 1) + bar("f2", 2) + std::swap(f1, f2); + bar("f1", 1) + foo("f2", 2) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2062 C++11 overload of swap for function was not required required + to be noexcept + +.SH See also - * Todo no example + swap swaps the contents + \fI(public member function)\fP + swap(std::move_only_function) overloads the std::swap algorithm + (C++23) \fI(function)\fP diff --git a/man/std::swap(std::list).3 b/man/std::swap(std::list).3 index 63bb5d1df..473d5c4dd 100644 --- a/man/std::swap(std::list).3 +++ b/man/std::swap(std::list).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::list) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::list) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::list) \- std::swap(std::list) + .SH Synopsis + Defined in header template< class T, class Alloc > - void swap( list& lhs, + void swap( std::list& lhs, \fI(until C++17)\fP + + std::list& rhs ); + template< class T, class Alloc > - list& rhs ); + void swap( std::list& lhs, \fI(since C++17)\fP + std::list& rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::list. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::list alice{1, 2, 3}; + std::list bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::map).3 b/man/std::swap(std::map).3 index 1ed6790cc..5f81a5e15 100644 --- a/man/std::swap(std::map).3 +++ b/man/std::swap(std::map).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::map) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::map) \- std::swap(std::map) + .SH Synopsis + Defined in header template< class Key, class T, class Compare, class Alloc > - void swap( map& lhs, + void swap( std::map& lhs, \fI(until C++17)\fP + + std::map& rhs ); + template< class Key, class T, class Compare, class Alloc > - map& rhs ); + void swap( std::map& lhs, \fI(since C++17)\fP + std::map& rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::map. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,60 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::map alice{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + std::map bob{{7, 'Z'}, {8, 'Y'}, {9, 'X'}, {10, 'W'}}; + + auto print = [](std::pair& n) + { + std::cout << ' ' << n.first << ':' << n.second; + }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1:a 2:b 3:c + Bob : 7:Z 8:Y 9:X 10:W + -- SWAP + Alice: 7:Z 8:Y 9:X 10:W + Bob : 1:a 2:b 3:c + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::match_results).3 b/man/std::swap(std::match_results).3 index 58b7464ac..42acb87c3 100644 --- a/man/std::swap(std::match_results).3 +++ b/man/std::swap(std::match_results).3 @@ -1,21 +1,24 @@ -.TH std::swap(std::match_results) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::match_results) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::match_results) \- std::swap(std::match_results) + .SH Synopsis Defined in header template< class BidirIt, class Alloc > - void swap( match_results& x1, \fI(since C++11)\fP + void swap( match_results& x1, \fI(since C++11)\fP - match_results& x2 ); + match_results& x2 ) noexcept; Specializes the std::swap algorithm for std::match_results. Exchanges the contents of x1 with those of x2. Effectively calls x1.swap(x2). .SH Parameters - x1, x2 - the match_results objects whose contents will be swapped + x1, x2 - the match_results objects whose contents will be swapped .SH Type requirements - - BidirIt must meet the requirements of BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. - Alloc must meet the requirements of Allocator. @@ -23,12 +26,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -37,8 +34,7 @@ .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::mdspan).3 b/man/std::swap(std::mdspan).3 new file mode 100644 index 000000000..91b629b55 --- /dev/null +++ b/man/std::swap(std::mdspan).3 @@ -0,0 +1,37 @@ +.TH std::swap(std::mdspan) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::mdspan) \- std::swap(std::mdspan) + +.SH Synopsis + Defined in header + friend constexpr void swap( mdspan& x, mdspan& y ) noexcept; (since C++23) + + Overloads the std::swap algorithm for std::mdspan. Exchanges the state of x with + that of y. + + Given ptr_, map_, and acc_ as exposition-only data members, equivalent to: + + std::swap(x.ptr_, y.ptr_); + std::swap(x.map_, y.map_); + std::swap(x.acc_, y.acc_); + +.SH Parameters + + x, y - mdspan objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + This section is incomplete + +.SH Categories: + * Todo no example + * Todo without reason diff --git a/man/std::swap(std::multimap).3 b/man/std::swap(std::multimap).3 index e89c98afc..6260433e9 100644 --- a/man/std::swap(std::multimap).3 +++ b/man/std::swap(std::multimap).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::multimap) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::multimap) \- std::swap(std::multimap) + .SH Synopsis + Defined in header template< class Key, class T, class Compare, class Alloc > - void swap( multimap& lhs, + void swap( std::multimap& lhs, \fI(until C++17)\fP + + std::multimap& rhs ); + template< class Key, class T, class Compare, class Alloc > - multimap& rhs ); + void swap( std::multimap& lhs, \fI(since C++17)\fP + std::multimap& rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::multimap. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,60 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::multimap alice{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + std::multimap bob{{7, 'Z'}, {8, 'Y'}, {9, 'X'}, {10, 'W'}}; + + auto print = [](std::pair& n) + { + std::cout << ' ' << n.first << ':' << n.second; + }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1:a 2:b 3:c + Bob : 7:Z 8:Y 9:X 10:W + -- SWAP + Alice: 7:Z 8:Y 9:X 10:W + Bob : 1:a 2:b 3:c + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::multiset).3 b/man/std::swap(std::multiset).3 index 3b918aa6b..97208dee5 100644 --- a/man/std::swap(std::multiset).3 +++ b/man/std::swap(std::multiset).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::multiset) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::multiset) \- std::swap(std::multiset) + .SH Synopsis + Defined in header template< class Key, class Compare, class Alloc > - void swap( multiset& lhs, + void swap( std::multiset& lhs, \fI(until C++17)\fP + + std::multiset& rhs ); + template< class Key, class Compare, class Alloc > - multiset& rhs ); + void swap( std::multiset& lhs, \fI(since C++17)\fP + std::multiset& rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::multiset. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::multiset alice{1, 2, 3}; + std::multiset bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::optional).3 b/man/std::swap(std::optional).3 new file mode 100644 index 000000000..79992da8d --- /dev/null +++ b/man/std::swap(std::optional).3 @@ -0,0 +1,85 @@ +.TH std::swap(std::optional) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::optional) \- std::swap(std::optional) + +.SH Synopsis + Defined in header + template< class T > + + void swap( std::optional& lhs, \fI(since C++17)\fP + (constexpr since C++20) + std::optional& rhs ) noexcept(/* see below + */); + + Overloads the std::swap algorithm for std::optional. Exchanges the state of lhs with + that of rhs. Effectively calls lhs.swap(rhs). + + This overload participates in overload resolution only if + std::is_move_constructible_v and std::is_swappable_v are both true. + +.SH Parameters + + lhs, rhs - optional objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::optional a{"██████"}, b{"▒▒▒▒▒▒"}; + + auto print = [&](auto const& s) + { + std::cout << s << "\\t" + "a = " << a.value_or("(null)") << " " + "b = " << b.value_or("(null)") << '\\n'; + }; + + print("Initially:"); + std::swap(a, b); + print("swap(a, b):"); + a.reset(); + print("\\n""a.reset():"); + std::swap(a, b); + print("swap(a, b):"); + } + +.SH Output: + + Initially: a = ██████ b = ▒▒▒▒▒▒ + swap(a, b): a = ▒▒▒▒▒▒ b = ██████ + + a.reset(): a = (null) b = ██████ + swap(a, b): a = ██████ b = (null) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 swap was not constexpr while the required made constexpr + operations can be constexpr in C++20 + +.SH See also + + swap exchanges the contents + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::packaged_task).3 b/man/std::swap(std::packaged_task).3 index 99929943a..3550f1b80 100644 --- a/man/std::swap(std::packaged_task).3 +++ b/man/std::swap(std::packaged_task).3 @@ -1,10 +1,13 @@ -.TH std::swap(std::packaged_task) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::packaged_task) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::packaged_task) \- std::swap(std::packaged_task) + .SH Synopsis - template< class Function, class Args... > + template< class Function, class... Args > - void swap( packaged_task &lhs, \fI(since C++11)\fP + void swap( packaged_task &lhs, \fI(since C++11)\fP - packaged_task &rhs ); + packaged_task &rhs ) noexcept; Specializes the std::swap algorithm for std::packaged_task. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -17,12 +20,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -31,8 +28,7 @@ .SH See also swap swaps two task objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::pair).3 b/man/std::swap(std::pair).3 index 85a9bd8ee..955a47ca0 100644 --- a/man/std::swap(std::pair).3 +++ b/man/std::swap(std::pair).3 @@ -1,13 +1,39 @@ -.TH std::swap(std::pair) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::pair) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::pair) \- std::swap(std::pair) + .SH Synopsis + Defined in header + template< class T1, class T2 > + \fI(since C++11)\fP + void swap( std::pair& x, std::pair& y ) \fI(until C++20)\fP + + noexcept(/* see below */); + template< class T1, class T2 > + + constexpr void swap( std::pair& x, std::pair& y \fI(since C++20)\fP + ) \fB(1)\fP + + noexcept(/* see below */); template< class T1, class T2 > - void swap( pair& lhs, pair& rhs ); - Swaps the contents of lhs and rhs. Equivalent to lhs.swap(rhs). + constexpr void swap( const std::pair& x, const \fB(2)\fP (since C++23) + std::pair& y ) + + noexcept(/* see below */); + + Swaps the contents of x and y. Equivalent to x.swap(y). + + 1) This overload participates in overload resolution only if + std::is_swappable_v && std::is_swappable_v is + true. \fI(since C++17)\fP + 2) This overload participates in overload resolution only if + std::is_swappable_v && std::is_swappable_v is true. .SH Parameters - lhs, rhs - pairs whose contents to swap + x, y - pairs whose contents to swap .SH Return value @@ -15,8 +41,49 @@ .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: \fI(since C++11)\fP (since C++11) + noexcept specification: noexcept(noexcept(x.swap(y))) +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto p1 = std::make_pair(10, 3.14); + auto p2 = std::pair(12, 1.23); // CTAD, since C++17 + + auto print_p1_p2 = [&](auto msg) { + std::cout << msg + << "p1 = {" << std::get<0>(p1) + << ", " << std::get<1>(p1) << "}, " + << "p2 = {" << std::get<0>(p2) + << ", " << std::get<1>(p2) << "}\\n"; + }; + + print_p1_p2("Before p1.swap(p2): "); + p1.swap(p2); + print_p1_p2("After p1.swap(p2): "); + std::swap(p1, p2); + print_p1_p2("After swap(p1, p2): "); + } + +.SH Output: + + Before p1.swap(p2): p1 = {10, 3.14}, p2 = {12, 1.23} + After p1.swap(p2): p1 = {12, 1.23}, p2 = {10, 3.14} + After swap(p1, p2): p1 = {10, 3.14}, p2 = {12, 1.23} + .SH See also + + swap swaps the values of two objects + \fI(function template)\fP + std::swap(std::tuple) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::priority_queue).3 b/man/std::swap(std::priority_queue).3 index 44bee18ae..c0817f6bf 100644 --- a/man/std::swap(std::priority_queue).3 +++ b/man/std::swap(std::priority_queue).3 @@ -1,14 +1,28 @@ -.TH std::swap(std::priority_queue) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::priority_queue) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::priority_queue) \- std::swap(std::priority_queue) + .SH Synopsis + Defined in header + template< class T, class Container, class Compare > + \fI(since C++11)\fP + void swap( std::priority_queue& lhs, \fI(until C++17)\fP + + std::priority_queue& rhs ); template< class T, class Container, class Compare > - void swap( priority_queue& lhs, (since {std}) + void swap( std::priority_queue& lhs, \fI(since C++17)\fP + std::priority_queue& rhs ) - priority_queue& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::priority_queue. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). + This overload participates in overload resolution only if + std::is_swappable_v and std::is_swappable_v are \fI(since C++17)\fP + both true. + .SH Parameters lhs, rhs - containers whose contents to swap @@ -21,7 +35,67 @@ Same as swapping the underlying container. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Notes + + Although the overloads of std::swap for container adaptors are introduced in C++11, + container adaptors can already be swapped by std::swap in C++98. Such calls to + std::swap usually have linear time complexity, but better complexity may be + provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::priority_queue alice; + std::priority_queue bob; + + auto print = [](const auto& title, const auto& cont) + { + std::cout << title << " size=" << cont.size(); + std::cout << " top=" << cont.top() << '\\n'; + }; + + for (int i = 1; i < 4; ++i) + alice.push(i); + for (int i = 7; i < 11; ++i) + bob.push(i); + + // Print state before swap + print("Alice:", alice); + print("Bob :", bob); + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + print("Alice:", alice); + print("Bob :", bob); + } + +.SH Output: + + Alice: size=3 top=3 + Bob : size=4 top=10 + -- SWAP + Alice: size=4 top=10 + Bob : size=3 top=3 + .SH See also - swap swaps the contents - \fI(public member function)\fP + swap swaps the contents + \fI(C++11)\fP \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::promise).3 b/man/std::swap(std::promise).3 index a38424ece..9a0ecc968 100644 --- a/man/std::swap(std::promise).3 +++ b/man/std::swap(std::promise).3 @@ -1,8 +1,11 @@ -.TH std::swap(std::promise) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::promise) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::promise) \- std::swap(std::promise) + .SH Synopsis Defined in header - template< class R > \fI(since C++11)\fP - void swap( promise &lhs, promise &rhs ); + template< class R > \fI(since C++11)\fP + void swap( promise& lhs, promise& rhs ) noexcept; Specializes the std::swap algorithm for std::promise. Exchanges the shared state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -15,12 +18,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -29,8 +26,7 @@ .SH See also swap swaps two promise objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::queue).3 b/man/std::swap(std::queue).3 index 6461ef4e9..441cde28e 100644 --- a/man/std::swap(std::queue).3 +++ b/man/std::swap(std::queue).3 @@ -1,14 +1,27 @@ -.TH std::swap(std::queue) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::queue) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::queue) \- std::swap(std::queue) + .SH Synopsis + Defined in header + template< class T, class Container > + \fI(since C++11)\fP + void swap( std::queue& lhs, \fI(until C++17)\fP + + std::queue& rhs ); template< class T, class Container > - void swap( queue& lhs, (since {std}) + void swap( std::queue& lhs, \fI(since C++17)\fP + std::queue& rhs ) - queue& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::queue. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). + This overload participates in overload resolution only if \fI(since C++17)\fP + std::is_swappable_v is true. + .SH Parameters lhs, rhs - containers whose contents to swap @@ -21,7 +34,68 @@ Same as swapping the underlying container. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Notes + + Although the overloads of std::swap for container adaptors are introduced in C++11, + container adaptors can already be swapped by std::swap in C++98. Such calls to + std::swap usually have linear time complexity, but better complexity may be + provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::queue alice; + std::queue bob; + + auto print = [](const auto& title, const auto& cont) + { + std::cout << title << " size=" << cont.size(); + std::cout << " front=" << cont.front(); + std::cout << " back=" << cont.back() << '\\n'; + }; + + for (int i = 1; i < 4; ++i) + alice.push(i); + for (int i = 7; i < 11; ++i) + bob.push(i); + + // Print state before swap + print("Alice:", alice); + print("Bob :", bob); + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + print("Alice:", alice); + print("Bob :", bob); + } + +.SH Output: + + Alice: size=3 front=1 back=3 + Bob : size=4 front=7 back=10 + -- SWAP + Alice: size=4 front=7 back=10 + Bob : size=3 front=1 back=3 + .SH See also - swap swaps the contents - \fI(public member function)\fP + swap swaps the contents + \fI(C++11)\fP \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::set).3 b/man/std::swap(std::set).3 index 6cc1e9895..43702356e 100644 --- a/man/std::swap(std::set).3 +++ b/man/std::swap(std::set).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::set) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::set) \- std::swap(std::set) + .SH Synopsis + Defined in header template< class Key, class Compare, class Alloc > - void swap( set& lhs, + void swap( std::set& lhs, \fI(until C++17)\fP + + std::set& rhs ); + template< class Key, class Compare, class Alloc > - set& rhs ); + void swap( std::set& lhs, \fI(since C++17)\fP + std::set& rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::set. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::set alice{1, 2, 3}; + std::set bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::shared_lock).3 b/man/std::swap(std::shared_lock).3 index b434c6f31..b9997fab7 100644 --- a/man/std::swap(std::shared_lock).3 +++ b/man/std::swap(std::shared_lock).3 @@ -1,10 +1,13 @@ -.TH std::swap(std::shared_lock) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::shared_lock) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::shared_lock) \- std::swap(std::shared_lock) + .SH Synopsis template< class Mutex > - void swap( shared_lock& lhs, \fI(since C++14)\fP + void swap( shared_lock& lhs, \fI(since C++14)\fP - shared_lock& rhs ); + shared_lock& rhs ) noexcept; Specializes the std::swap algorithm for std::shared_lock. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -17,12 +20,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -31,8 +28,7 @@ .SH See also swap swaps the data members with another shared_lock - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::shared_ptr).3 b/man/std::swap(std::shared_ptr).3 index be053750d..6d4ebbe1c 100644 --- a/man/std::swap(std::shared_ptr).3 +++ b/man/std::swap(std::shared_ptr).3 @@ -1,9 +1,14 @@ -.TH std::swap(std::shared_ptr) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::shared_ptr) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::shared_ptr) \- std::swap(std::shared_ptr) + .SH Synopsis - template< class T > \fI(since C++11)\fP - void swap( shared_ptr &lhs, shared_ptr &rhs ); + Defined in header + template< class T > + void swap( std::shared_ptr& lhs, std::shared_ptr& rhs ) \fI(since C++11)\fP + noexcept; - Specializes the std::swap algorithm for std::shared_ptr. Swaps the pointers of lhs + Specializes the std::swap algorithm for std::shared_ptr. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). .SH Parameters @@ -16,9 +21,58 @@ .SH Complexity - Constant + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo { + Foo(int _val) : val(_val) { std::cout << "Foo...\\n"; } + ~Foo() { std::cout << "~Foo...\\n"; } + std::string print() { return std::to_string(val); } + int val; + }; + + int main() + { + std::shared_ptr p1 = std::make_shared(100); + std::shared_ptr p2 = std::make_shared(200); + auto print = [&]() { + std::cout << " p1=" << (p1 ? p1->print() : "nullptr"); + std::cout << " p2=" << (p2 ? p2->print() : "nullptr") << '\\n'; + }; + print(); + + std::swap(p1, p2); + print(); + + p1.reset(); + print(); + + std::swap(p1, p2); + print(); + } + +.SH Output: + + Foo... + Foo... + p1=100 p2=200 + p1=200 p2=100 + ~Foo... + p1=nullptr p2=100 + p1=100 p2=nullptr + ~Foo... .SH See also + swap swaps the values of two objects + \fI(function template)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::swap(std::stack).3 b/man/std::swap(std::stack).3 index ea01a1ceb..4bdb8e5fa 100644 --- a/man/std::swap(std::stack).3 +++ b/man/std::swap(std::stack).3 @@ -1,14 +1,27 @@ -.TH std::swap(std::stack) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::stack) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::stack) \- std::swap(std::stack) + .SH Synopsis + Defined in header + template< class T, class Container > + \fI(since C++11)\fP + void swap( std::stack& lhs, \fI(until C++17)\fP + + std::stack& rhs ); template< class T, class Container > - void swap( stack& lhs, (since {std}) + void swap( std::stack& lhs, \fI(since C++17)\fP + std::stack& rhs ) - stack& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::stack. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). + This overload participates in overload resolution only if \fI(since C++17)\fP + std::is_swappable_v is true. + .SH Parameters lhs, rhs - containers whose contents to swap @@ -21,7 +34,67 @@ Same as swapping the underlying container. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Notes + + Although the overloads of std::swap for container adaptors are introduced in C++11, + container adaptors can already be swapped by std::swap in C++98. Such calls to + std::swap usually have linear time complexity, but better complexity may be + provided. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::stack alice; + std::stack bob; + + auto print = [](const auto& title, const auto& cont) + { + std::cout << title << " size=" << cont.size(); + std::cout << " top=" << cont.top() << '\\n'; + }; + + for (int i = 1; i < 4; ++i) + alice.push(i); + for (int i = 7; i < 11; ++i) + bob.push(i); + + // Print state before swap + print("Alice:", alice); + print("Bob :", bob); + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + print("Alice:", alice); + print("Bob :", bob); + } + +.SH Output: + + Alice: size=3 top=3 + Bob : size=4 top=10 + -- SWAP + Alice: size=4 top=10 + Bob : size=3 top=3 + .SH See also - swap swaps the contents - \fI(public member function)\fP + swap swaps the contents + \fI(C++11)\fP \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::thread).3 b/man/std::swap(std::thread).3 index 40ab4550a..3fb18373d 100644 --- a/man/std::swap(std::thread).3 +++ b/man/std::swap(std::thread).3 @@ -1,6 +1,9 @@ -.TH std::swap(std::thread) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::thread) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::thread) \- std::swap(std::thread) + .SH Synopsis - void swap( thread &lhs, thread &rhs ); \fI(since C++11)\fP + void swap( std::thread& lhs, std::thread& rhs ) noexcept; \fI(since C++11)\fP Overloads the std::swap algorithm for std::thread. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -13,56 +16,52 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code + #include #include #include - #include - + void foo() { std::this_thread::sleep_for(std::chrono::seconds(1)); } - + void bar() { std::this_thread::sleep_for(std::chrono::seconds(1)); } - + int main() { + using std::swap; + std::thread t1(foo); std::thread t2(bar); - - std::cout << "thread 1 id: " << t1.get_id() << std::endl; - std::cout << "thread 2 id: " << t2.get_id() << std::endl; - - std::swap(t1, t2); - - std::cout << "after std::swap(t1, t2):" << std::endl; - std::cout << "thread 1 id: " << t1.get_id() << std::endl; - std::cout << "thread 2 id: " << t2.get_id() << std::endl; - + + std::cout << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + swap(t1, t2); + + std::cout << "after std::swap(t1, t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + t1.swap(t2); - - std::cout << "after t1.swap(t2):" << std::endl; - std::cout << "thread 1 id: " << t1.get_id() << std::endl; - std::cout << "thread 2 id: " << t2.get_id() << std::endl; - + + std::cout << "after t1.swap(t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + t1.join(); t2.join(); } -.SH Output: +.SH Possible output: thread 1 id: 1892 thread 2 id: 2584 @@ -76,4 +75,4 @@ .SH See also swap swaps two thread objects - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::swap(std::tuple).3 b/man/std::swap(std::tuple).3 index 8adb01f7b..a153c704a 100644 --- a/man/std::swap(std::tuple).3 +++ b/man/std::swap(std::tuple).3 @@ -1,10 +1,36 @@ -.TH std::swap(std::tuple) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::tuple) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::tuple) \- std::swap(std::tuple) + .SH Synopsis - template< class... Types > \fI(since C++11)\fP - void swap( tuple& lhs, tuple& rhs ); + Defined in header + template< class... Types > + + void swap( std::tuple& lhs, \fI(since C++11)\fP + \fI(until C++20)\fP + std::tuple& rhs ) noexcept(/* see below + */); + template< class... Types > + + constexpr void swap( std::tuple& lhs, \fB(1)\fP \fI(since C++20)\fP + + std::tuple& rhs ) noexcept(/* + see below */); + template< class... Types > + + constexpr void swap( const std::tuple& lhs, \fB(2)\fP (since C++23) + + const std::tuple& rhs ) + noexcept(/* see below */); Swaps the contents of lhs and rhs. Equivalent to lhs.swap(rhs). + 1) This overload participates in overload resolution only if + std::is_swappable_v is true for all i from 0 to sizeof...(Types). + 2) This overload participates in overload resolution only if \fI(since C++17)\fP + std::is_swappable_v is true for all i from 0 to + sizeof...(Types). + .SH Parameters lhs, rhs - tuples whose contents to swap @@ -15,7 +41,53 @@ .SH Exceptions - noexcept specification: \fI(since C++11)\fP + noexcept specification: noexcept(noexcept(lhs.swap(rhs))) +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::tuple p1{42, "ABCD", 2.71}, p2; + p2 = std::make_tuple(10, "1234", 3.14); + + auto print_p1_p2 = [&](auto rem) + { + std::cout << rem + << "p1 = {" << std::get<0>(p1) + << ", " << std::get<1>(p1) + << ", " << std::get<2>(p1) << "}, " + << "p2 = {" << std::get<0>(p2) + << ", " << std::get<1>(p2) + << ", " << std::get<2>(p2) << "}\\n"; + }; + + print_p1_p2("Before p1.swap(p2): "); + p1.swap(p2); + print_p1_p2("After p1.swap(p2): "); + swap(p1, p2); + print_p1_p2("After swap(p1, p2): "); + } + +.SH Output: + + Before p1.swap(p2): p1 = {42, ABCD, 2.71}, p2 = {10, 1234, 3.14} + After p1.swap(p2): p1 = {10, 1234, 3.14}, p2 = {42, ABCD, 2.71} + After swap(p1, p2): p1 = {42, ABCD, 2.71}, p2 = {10, 1234, 3.14} + .SH See also + + swap swaps the contents of two tuples + \fI(public member function)\fP + std::swap(std::pair) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::unique_lock).3 b/man/std::swap(std::unique_lock).3 index 68ecaaed1..229f17f22 100644 --- a/man/std::swap(std::unique_lock).3 +++ b/man/std::swap(std::unique_lock).3 @@ -1,10 +1,13 @@ -.TH std::swap(std::unique_lock) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::unique_lock) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::unique_lock) \- std::swap(std::unique_lock) + .SH Synopsis template< class Mutex > - void swap( unique_lock& lhs, \fI(since C++11)\fP + void swap( unique_lock& lhs, \fI(since C++11)\fP - unique_lock& rhs ); + unique_lock& rhs ) noexcept; Specializes the std::swap algorithm for std::unique_lock. Exchanges the state of lhs with that of rhs. Effectively calls lhs.swap(rhs). @@ -17,12 +20,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete @@ -31,8 +28,7 @@ .SH See also swap swaps state with another std::unique_lock - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::swap(std::unique_ptr).3 b/man/std::swap(std::unique_ptr).3 index d1ba521ac..0f55d313e 100644 --- a/man/std::swap(std::unique_ptr).3 +++ b/man/std::swap(std::unique_ptr).3 @@ -1,11 +1,19 @@ -.TH std::swap(std::unique_ptr) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::unique_ptr) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::unique_ptr) \- std::swap(std::unique_ptr) + .SH Synopsis - template< class T, class Deleter > \fI(since C++11)\fP - void swap( unique_ptr &lhs, unique_ptr &rhs ); + Defined in header + template< class T, class D > \fI(since C++11)\fP + void swap( std::unique_ptr& lhs, std::unique_ptr& rhs ) noexcept; - Specializes the std::swap algorithm for std::unique_ptr. Swaps the pointers of lhs + Specializes the std::swap algorithm for std::unique_ptr. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). + This function does not participate in overload resolution unless \fI(since C++17)\fP + std::is_swappable_v is true. + .SH Parameters lhs, rhs - smart pointers whose contents to swap @@ -16,9 +24,58 @@ .SH Complexity - Constant + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo { + Foo(int _val) : val(_val) { std::cout << "Foo...\\n"; } + ~Foo() { std::cout << "~Foo...\\n"; } + std::string print() { return std::to_string(val); } + int val; + }; + + int main() + { + std::unique_ptr p1 = std::make_unique(100); + std::unique_ptr p2 = std::make_unique(200); + auto print = [&]() { + std::cout << " p1=" << (p1 ? p1->print() : "nullptr"); + std::cout << " p2=" << (p2 ? p2->print() : "nullptr") << '\\n'; + }; + print(); + + std::swap(p1, p2); + print(); + + p1.reset(); + print(); + + std::swap(p1, p2); + print(); + } + +.SH Output: + + Foo... + Foo... + p1=100 p2=200 + p1=200 p2=100 + ~Foo... + p1=nullptr p2=100 + p1=100 p2=nullptr + ~Foo... .SH See also + swap swaps the values of two objects + \fI(function template)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::swap(std::unordered_map).3 b/man/std::swap(std::unordered_map).3 index c541e601d..925f1fe7c 100644 --- a/man/std::swap(std::unordered_map).3 +++ b/man/std::swap(std::unordered_map).3 @@ -1,11 +1,22 @@ -.TH std::swap(std::unordered_map) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::unordered_map) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::unordered_map) \- std::swap(std::unordered_map) + .SH Synopsis + Defined in header template< class Key, class T, class Hash, class KeyEqual, class Alloc > \fI(since C++11)\fP - void swap( unordered_map& lhs, + void swap( std::unordered_map& lhs, \fI(until C++17)\fP + + std::unordered_map& rhs ); + template< class Key, class T, class Hash, class KeyEqual, class Alloc + > + + void swap( std::unordered_map& lhs, \fI(since C++17)\fP + std::unordered_map& rhs ) - unordered_map& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::unordered_map. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -22,7 +33,60 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_map alice{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + std::unordered_map bob{{7, 'Z'}, {8, 'Y'}, {9, 'X'}, {10, 'W'}}; + + auto print = [](std::pair& n) + { + std::cout << ' ' << n.first << ':' << n.second; + }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Possible output: + + Alice: 1:a 2:b 3:c + Bob : 7:Z 8:Y 9:X 10:W + -- SWAP + Alice: 7:Z 8:Y 9:X 10:W + Bob : 1:a 2:b 3:c + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::unordered_multimap).3 b/man/std::swap(std::unordered_multimap).3 index c6abb8326..0485f7e18 100644 --- a/man/std::swap(std::unordered_multimap).3 +++ b/man/std::swap(std::unordered_multimap).3 @@ -1,11 +1,26 @@ -.TH std::swap(std::unordered_multimap) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::unordered_multimap) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::unordered_multimap) \- std::swap(std::unordered_multimap) + .SH Synopsis + Defined in header + template< class Key, class T, class Hash, class KeyEqual, class Alloc + > + + void swap( std::unordered_multimap& \fI(since C++11)\fP + lhs, \fI(until C++17)\fP + + std::unordered_multimap& + rhs ); template< class Key, class T, class Hash, class KeyEqual, class Alloc > - \fI(since C++11)\fP - void swap( unordered_multimap& lhs, - unordered_multimap& rhs ); + void swap( std::unordered_multimap& + lhs, \fI(since C++17)\fP + std::unordered_multimap& + rhs ) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::unordered_multimap. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -22,7 +37,60 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_multimap alice{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + std::unordered_multimap bob{{7, 'Z'}, {8, 'Y'}, {9, 'X'}, {10, 'W'}}; + + auto print = [](std::pair& n) + { + std::cout << ' ' << n.first << ':' << n.second; + }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Possible output: + + Alice: 1:a 2:b 3:c + Bob : 7:Z 8:Y 9:X 10:W + -- SWAP + Alice: 7:Z 8:Y 9:X 10:W + Bob : 1:a 2:b 3:c + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::unordered_multiset).3 b/man/std::swap(std::unordered_multiset).3 index c01c024cb..f99a61c22 100644 --- a/man/std::swap(std::unordered_multiset).3 +++ b/man/std::swap(std::unordered_multiset).3 @@ -1,10 +1,21 @@ -.TH std::swap(std::unordered_multiset) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::unordered_multiset) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::unordered_multiset) \- std::swap(std::unordered_multiset) + .SH Synopsis + Defined in header + template< class Key, class Hash, class KeyEqual, class Alloc > + + void swap( std::unordered_multiset& lhs, \fI(since C++11)\fP + \fI(until C++17)\fP + std::unordered_multiset& rhs + ); template< class Key, class Hash, class KeyEqual, class Alloc > - void swap( unordered_multiset& lhs, \fI(since C++11)\fP + void swap( std::unordered_multiset& lhs, \fI(since C++17)\fP + std::unordered_multiset& rhs ) - unordered_multiset& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::unordered_multiset. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +32,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_multiset alice{1, 2, 3}; + std::unordered_multiset bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Possible output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::unordered_set).3 b/man/std::swap(std::unordered_set).3 index 64b04bb00..c776da327 100644 --- a/man/std::swap(std::unordered_set).3 +++ b/man/std::swap(std::unordered_set).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::unordered_set) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::unordered_set) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::unordered_set) \- std::swap(std::unordered_set) + .SH Synopsis + Defined in header + template< class Key, class Hash, class KeyEqual, class Alloc > + \fI(since C++11)\fP + void swap( std::unordered_set& lhs, \fI(until C++17)\fP + + std::unordered_set& rhs ); template< class Key, class Hash, class KeyEqual, class Alloc > - void swap( unordered_set& lhs, \fI(since C++11)\fP + void swap( std::unordered_set& lhs, \fI(since C++17)\fP + std::unordered_set& rhs ) - unordered_set& rhs ); + noexcept(/* see below */); Specializes the std::swap algorithm for std::unordered_set. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_set alice{1, 2, 3}; + std::unordered_set bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Possible output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::valarray).3 b/man/std::swap(std::valarray).3 index edf41f346..9c075edf9 100644 --- a/man/std::swap(std::valarray).3 +++ b/man/std::swap(std::valarray).3 @@ -1,7 +1,11 @@ -.TH std::swap(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::valarray) \- std::swap(std::valarray) + .SH Synopsis - template< class T > - void swap( valarray &lhs, valarray &rhs ); + Defined in header + template< class T > \fI(since C++11)\fP + void swap( std::valarray& lhs, std::valarray& rhs ) noexcept; Specializes the std::swap algorithm for std::valarray. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -18,7 +22,46 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + + void print(auto rem, const std::valarray& v) + { + std::cout << rem << '{'; + for (char sep[]{0, ' ', 0}; auto elem : v) + std::cout << sep << elem, *sep = ','; + std::cout << "}\\n"; + } + + int main() + { + std::valarray x{3, 1, 4, 1, 5}; + std::valarray y{2, 7, 1, 8}; + + print("Before swap:\\n" "x: ", x); + print("y: ", y); + + std::swap(x, y); + + print("After swap:\\n" "x: ", x); + print("y: ", y); + } + +.SH Output: + + Before swap: + x: {3, 1, 4, 1, 5} + y: {2, 7, 1, 8} + After swap: + x: {2, 7, 1, 8} + y: {3, 1, 4, 1, 5} + .SH See also swap swaps with another valarray - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::swap(std::variant).3 b/man/std::swap(std::variant).3 new file mode 100644 index 000000000..e92a41f15 --- /dev/null +++ b/man/std::swap(std::variant).3 @@ -0,0 +1,86 @@ +.TH std::swap(std::variant) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::variant) \- std::swap(std::variant) + +.SH Synopsis + Defined in header + template + \fI(since C++17)\fP + void swap( std::variant& lhs, \fI(until C++20)\fP + + std::variant& rhs ) noexcept(/* see below */); + template + + constexpr void swap( std::variant& lhs, \fI(since C++20)\fP + + std::variant& rhs ) noexcept(/* see + below */); + + Overloads the std::swap algorithm for std::variant. Effectively calls lhs.swap(rhs). + + This overload participates in overload resolution only if + std::is_move_constructible_v and std::is_swappable_v are both true for all + T_i in Types... + +.SH Parameters + + lhs, rhs - variant objects whose values to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + auto print = [](auto const& v, char term = '\\n') { + std::visit([](auto&& o) { std::cout << o; }, v); + std::cout << term; + }; + + int main() + { + std::variant v1{123}, v2{"XYZ"}; + print(v1, ' '); + print(v2); + + std::swap(v1, v2); + print(v1, ' '); + print(v2); + + std::variant v3{3.14}; + // std::swap(v1, v3); // ERROR: ~ inconsistent parameter packs + } + +.SH Output: + + 123 XYZ + XYZ 123 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 swap was not constexpr while the required made constexpr + operations can be constexpr in C++20 + +.SH See also + + swap swaps with another variant + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::vector).3 b/man/std::swap(std::vector).3 index 600ef4267..21bfb2f1e 100644 --- a/man/std::swap(std::vector).3 +++ b/man/std::swap(std::vector).3 @@ -1,10 +1,20 @@ -.TH std::swap(std::vector) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::vector) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::vector) \- std::swap(std::vector) + .SH Synopsis + Defined in header template< class T, class Alloc > - void swap( vector& lhs, + void swap( std::vector& lhs, \fI(until C++17)\fP + + std::vector& rhs ); + template< class T, class Alloc > - vector& rhs ); + void swap( std::vector& lhs, \fI(since C++17)\fP + std::vector& rhs ) (constexpr since C++20) + + noexcept(/* see below */); Specializes the std::swap algorithm for std::vector. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). @@ -21,7 +31,57 @@ Constant. +.SH Exceptions + + noexcept specification: \fI(since C++17)\fP + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector alice{1, 2, 3}; + std::vector bob{7, 8, 9, 10}; + + auto print = [](const int& n) { std::cout << ' ' << n; }; + + // Print state before swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + + std::cout << "-- SWAP\\n"; + std::swap(alice, bob); + + // Print state after swap + std::cout << "Alice:"; + std::for_each(alice.begin(), alice.end(), print); + std::cout << "\\n" "Bob :"; + std::for_each(bob.begin(), bob.end(), print); + std::cout << '\\n'; + } + +.SH Output: + + Alice: 1 2 3 + Bob : 7 8 9 10 + -- SWAP + Alice: 7 8 9 10 + Bob : 1 2 3 + .SH See also swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap(std::weak_ptr).3 b/man/std::swap(std::weak_ptr).3 index a08e73bd4..737f4a2c5 100644 --- a/man/std::swap(std::weak_ptr).3 +++ b/man/std::swap(std::weak_ptr).3 @@ -1,9 +1,13 @@ -.TH std::swap(std::weak_ptr) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap(std::weak_ptr) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap(std::weak_ptr) \- std::swap(std::weak_ptr) + .SH Synopsis - template< class T > \fI(since C++11)\fP - void swap( weak_ptr &lhs, weak_ptr &rhs ); + Defined in header + template< class T > \fI(since C++11)\fP + void swap( std::weak_ptr& lhs, std::weak_ptr& rhs ) noexcept; - Specializes the std::swap algorithm for std::weak_ptr. Swaps the pointers of lhs and + Specializes the std::swap algorithm for std::weak_ptr. Swaps the contents of lhs and rhs. Calls lhs.swap(rhs). .SH Parameters @@ -16,9 +20,62 @@ .SH Complexity - Constant + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo { + Foo(int _val) : val(_val) { std::cout << "Foo...\\n"; } + ~Foo() { std::cout << "~Foo...\\n"; } + std::string print() { return std::to_string(val); } + int val; + }; + + int main() + { + std::shared_ptr sp1 = std::make_shared(100); + std::shared_ptr sp2 = std::make_shared(200); + std::weak_ptr wp1 = sp1; + std::weak_ptr wp2 = sp2; + auto print = [&]() { + auto p1 = wp1.lock(); + auto p2 = wp2.lock(); + std::cout << " p1=" << (p1 ? p1->print() : "nullptr"); + std::cout << " p2=" << (p2 ? p2->print() : "nullptr") << '\\n'; + }; + print(); + + std::swap(wp1, wp2); + print(); + + wp1.reset(); + print(); + + std::swap(wp1, wp2); + print(); + } + +.SH Output: + + Foo... + Foo... + p1=100 p2=200 + p1=200 p2=100 + p1=nullptr p2=100 + p1=100 p2=nullptr + ~Foo... + ~Foo... .SH See also + swap swaps the values of two objects + \fI(function template)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::swap.3 b/man/std::swap.3 index 974c80698..8fc131183 100644 --- a/man/std::swap.3 +++ b/man/std::swap.3 @@ -1,24 +1,49 @@ -.TH std::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap \- std::swap + .SH Synopsis - Defined in header \fI(until C++11)\fP - Defined in header \fI(since C++11)\fP - template< class T > \fB(1)\fP + Defined in header \fI(until C++11)\fP + Defined in header \fI(since C++11)\fP + Defined in header + template< class T > \fI(until C++11)\fP void swap( T& a, T& b ); - template< class T2, size_t N > \fB(2)\fP \fI(since C++11)\fP - void swap( T2 (&a)[N], T2 (&b)[N]); + template< class T > \fI(since C++11)\fP + void swap( T& a, T& b ) (constexpr since + noexcept(/* see below */); C++20) + template< class T2, std::size_t + N > \fB(1)\fP \fI(until C++11)\fP + void swap( T2 (&a)[N], T2 + (&b)[N] ); + template< class T2, std::size_t \fB(2)\fP + N > \fI(since C++11)\fP + void swap( T2 (&a)[N], T2 (constexpr since + (&b)[N] ) noexcept(/* see below C++20) + */); Exchanges the given values. 1) Swaps the values a and b. - 2) Swaps the arrays a and b. In effect calls std::swap_ranges(a, a+N, b). + This overload participates in overload resolution only if + std::is_move_constructible_v && std::is_move_assignable_v is \fI(since C++17)\fP + true. + + 2) Swaps the arrays a and b. In effect calls std::swap_ranges(a, a + N, b). + + This overload participates in overload resolution only if \fI(since C++17)\fP + std::is_swappable_v is true. .SH Parameters - a, b - the values to be swapped + a, b - the values to be swapped .SH Type requirements - - T must meet the requirements of MoveAssignable and MoveConstructible. + T must meet the requirements of + CopyConstructible and CopyAssignable + \fI(until C++11)\fP + MoveConstructible and MoveAssignable + \fI(since C++11)\fP - T2 must meet the requirements of Swappable. @@ -29,139 +54,231 @@ .SH Exceptions 1) - noexcept specification: \fI(since C++11)\fP - noexcept(noexcept( - std::is_nothrow_move_constructible::value && + \fI(none)\fP \fI(until C++11)\fP + noexcept specification: + noexcept( + + std::is_nothrow_move_constructible::value && \fI(since C++11)\fP std::is_nothrow_move_assignable::value - )) + ) + 2) - noexcept specification: \fI(since C++11)\fP + + noexcept specification: noexcept(noexcept(swap(*a, *b))) + The lookup for the identifier swap in the exception specification \fI(since C++11)\fP + finds this function template in addition to anything found by the \fI(until C++17)\fP + usual lookup rules, making the exception specification equivalent to + C++17 std::is_nothrow_swappable. + noexcept specification: \fI(since C++17)\fP + noexcept(std::is_nothrow_swappable_v) .SH Complexity - 1) Constant - - 2) Linear in N + 1) Constant. + 2) Linear in N. .SH Specializations - Both custom specializations and overloads of the std::swap algorithm are allowed, - but the overloads are generally preferred since specializations of a function - template aren't allowed for template classes. Library functions always use the - user-provided overloads when swapping, if they are found by argument-dependent - lookup (as per Swappable concept). + std::swap may be specialized in namespace std for program-defined + types, but such specializations are not found by ADL (the namespace \fI(until C++20)\fP + std is not the associated namespace for the program-defined type). + + The expected way to make a program-defined type swappable is to provide a non-member + function swap in the same namespace as the type: see Swappable for details. The following overloads are already provided by the standard library: std::swap(std::pair) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::tuple) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::shared_ptr) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::weak_ptr) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::unique_ptr) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::function) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_string) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::array) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::deque) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::forward_list) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::list) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::vector) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::map) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::multimap) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::set) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::multiset) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP std::swap(std::unordered_map) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::unordered_multimap) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::unordered_set) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::unordered_multiset) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::queue) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::priority_queue) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::stack) specializes the std::swap algorithm - \fI(function template)\fP - std::swap(std::valarray) specializes the std::swap() algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + std::swap(std::valarray) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_stringbuf) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_istringstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_ostringstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_stringstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_filebuf) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_ifstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_ofstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::basic_fstream) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + std::swap(std::basic_syncbuf) specializes the std::swap algorithm + (C++20) \fI(function template)\fP + std::swap(std::basic_spanbuf) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + std::swap(std::basic_ispanstream) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + std::swap(std::basic_ospanstream) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + std::swap(std::basic_spanstream) specializes the std::swap algorithm + (C++23) \fI(function template)\fP std::swap(std::basic_regex) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP - std::swap(std::match_results) specializes the std::swap() algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + std::swap(std::match_results) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP std::swap(std::thread) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function)\fP std::swap(std::unique_lock) specialization of std::swap for unique_lock - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + std::swap(std::shared_lock) specialization of std::swap for shared_lock + \fI(C++14)\fP \fI(function template)\fP std::swap(std::promise) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP std::swap(std::packaged_task) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + std::swap(std::optional) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function template)\fP + std::swap(std::any) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function)\fP + std::swap(std::variant) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function template)\fP + std::swap(std::basic_stacktrace) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + swap(std::filesystem::path) swaps two paths + \fI(C++17)\fP \fI(function)\fP + swap(std::expected) specializes the std::swap algorithm + (C++23) \fI(function)\fP + swap(std::jthread) specializes the std::swap algorithm + (C++20) \fI(function)\fP + swap(std::move_only_function) overloads the std::swap algorithm + (C++23) \fI(function)\fP + swap(std::stop_source) specializes the std::swap algorithm + (C++20) \fI(function)\fP + swap(std::stop_token) specializes the std::swap algorithm + (C++20) \fI(function)\fP .SH Example - + // Run this code #include #include - + + namespace Ns + { + class A + { + int id {}; + + friend void swap(A& lhs, A& rhs) + { + std::cout << "swap(" << lhs << ", " << rhs << ")\\n"; + std::swap(lhs.id, rhs.id); + } + + friend std::ostream& operator<<(std::ostream& os, A const& a) + { + return os << "A::id=" << a.id; + } + + public: + A(int i) : id {i} {} + A(A const&) = delete; + A& operator = (A const&) = delete; + }; + } + int main() { - int a = 5, b = 3; - - // before - std::cout << a << ' ' << b << '\\n'; - - std::swap(a,b); - - // after - std::cout << a << ' ' << b << '\\n'; + int a = 5, b = 3; + std::cout << a << ' ' << b << '\\n'; + std::swap(a, b); + std::cout << a << ' ' << b << '\\n'; + + Ns::A p {6}, q {9}; + std::cout << p << ' ' << q << '\\n'; + // std::swap(p, q); // error, type requirements are not satisfied + swap(p, q); // OK, ADL finds the appropriate friend `swap` + std::cout << p << ' ' << q << '\\n'; } .SH Output: 5 3 3 5 + A::id=6 A::id=9 + swap(A::id=6, A::id=9) + A::id=9 A::id=6 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + T was not required to be CopyConstructible + LWG 227 C++98 or DefaultConstructible T is also required to + (a temporary object of type T might not be be CopyConstructible + able to be constructed) + LWG 809 C++98 arrays could not be swapped added overload \fB(2)\fP + swapping multi-dimensional arrays can + LWG 2554 C++11 never made to work + be noexcept due to name lookup problems .SH See also - iter_swap swaps the elements pointed to by two iterators - \fI(function template)\fP - swap_ranges swaps two ranges of elements - \fI(function template)\fP + ranges::swap swaps the values of two objects + (C++20) (customization point object) + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + exchange replaces the argument with a new value and returns its previous value + \fI(C++14)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::swap_ranges.3 b/man/std::swap_ranges.3 index 60ca9d75c..86ca606fc 100644 --- a/man/std::swap_ranges.3 +++ b/man/std::swap_ranges.3 @@ -1,79 +1,134 @@ -.TH std::swap_ranges 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::swap_ranges 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swap_ranges \- std::swap_ranges + .SH Synopsis Defined in header template< class ForwardIt1, class ForwardIt2 > - ForwardIt2 swap_ranges( ForwardIt1 first1, ForwardIt1 last1, ForwardIt2 first2 ) - Exchanges elements between range [first1, last1) and another range starting at - first2. + ForwardIt2 swap_ranges( ForwardIt1 first1, ForwardIt1 \fB(1)\fP (constexpr since C++20) + last1, + + ForwardIt2 first2 ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2 > + ForwardIt2 swap_ranges( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 + last1, + + ForwardIt2 first2 ); + + 1) Exchanges elements between range [first1, last1) and another range of + std::distance(first1, last1) elements starting at first2. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the behavior is undefined: + + * The two ranges overlap. + * There exists a pair of corresponding iterators iter1 and iter2 in the two ranges + such that *iter1 is not Swappable with *iter2. .SH Parameters - first1, last1 - the first range of elements to swap - first2 - beginning of the second range of elements to swap + first1, last1 - the first range of elements to swap + first2 - beginning of the second range of elements to swap + policy - the execution policy to use. See execution policy for details. .SH Type requirements - - ForwardIt1, ForwardIt2 must meet the requirements of ForwardIterator. - - - The types of dereferenced ForwardIt1 and ForwardIt2 must meet the requirements of - Swappable + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value Iterator to the element past the last element exchanged in the range beginning with first2. +.SH Complexity + + Exactly std::distance(first1, last1) swaps. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + satisfies LegacyContiguousIterator and swapping its value type calls neither + non-trivial special member function nor ADL-found swap. + .SH Possible implementation template - ForwardIt2 swap_ranges(ForwardIt1 first1, - ForwardIt1 last1, - ForwardIt2 first2) + constexpr //< since C++20 + ForwardIt2 swap_ranges(ForwardIt1 first1, ForwardIt1 last1, ForwardIt2 first2) { - while (first1 != last1) { - std::iter_swap(first1++, first2++); - } + for (; first1 != last1; ++first1, ++first2) + std::iter_swap(first1, first2); + return first2; } .SH Example - Demonstrates swapping of subranges from different containers + Demonstrates swapping of subranges from different containers. + - // Run this code #include + #include #include #include - #include - int main() + + auto print = [](auto comment, auto const& seq) { - std::vector v = {1, 2, 3, 4, 5}; - std::list l = {-1, -2, -3, -4, -5}; - - std::swap_ranges(v.begin(), v.begin()+3, l.begin()); - - for(int n : v) - std::cout << n << ' '; + std::cout << comment; + for (const auto& e : seq) + std::cout << e << ' '; std::cout << '\\n'; - for(int n : l) - std::cout << n << ' '; - std::cout << '\\n'; - } + }; -.SH Output: + int main() + { + std::vector v{'a', 'b', 'c', 'd', 'e'}; + std::list l{'1', '2', '3', '4', '5'}; - -1 -2 -3 4 5 - 1 2 3 -4 -5 + print("Before swap_ranges:\\n" "v: ", v); + print("l: ", l); -.SH Complexity + std::swap_ranges(v.begin(), v.begin() + 3, l.begin()); + + print("After swap_ranges:\\n" "v: ", v); + print("l: ", l); + } + +.SH Output: - linear in the distance between first and last + Before swap_ranges: + v: a b c d e + l: 1 2 3 4 5 + After swap_ranges: + v: 1 2 3 d e + l: a b c 4 5 .SH See also - iter_swap swaps the elements pointed to by two iterators - \fI(function template)\fP - swap swaps the values of two objects - \fI(function template)\fP + iter_swap swaps the elements pointed to by two iterators + \fI(function template)\fP + swap swaps the values of two objects + \fI(function template)\fP + ranges::swap_ranges swaps two ranges of elements + (C++20) (niebloid) diff --git a/man/std::swappable,std::swappable_with.3 b/man/std::swappable,std::swappable_with.3 new file mode 100644 index 000000000..20659b8c9 --- /dev/null +++ b/man/std::swappable,std::swappable_with.3 @@ -0,0 +1,37 @@ +.TH std::swappable,std::swappable_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::swappable,std::swappable_with \- std::swappable,std::swappable_with + +.SH Synopsis + Defined in header + template< class T > + + concept swappable = + requires(T& a, T& b) { \fB(1)\fP \fI(since C++20)\fP + ranges::swap(a, b); + + }; + template< class T, class U > + + concept swappable_with = + std::common_reference_with && + requires(T&& t, U&& u) { + ranges::swap(std::forward(t), std::forward(t)); \fB(2)\fP \fI(since C++20)\fP + ranges::swap(std::forward(u), std::forward(u)); + ranges::swap(std::forward(t), std::forward(u)); + ranges::swap(std::forward(u), std::forward(t)); + + }; + + The concept swappable specifies that lvalues of type T are swappable. + + The concept swappable_with specifies that expressions of the type and value + category encoded by T and U are swappable with each other. swappable_with is + satisfied only if a call to ranges::swap(t, u) exchanges the value of t and u, that + is, given distinct objects t2 equal to t and u2 equal to u, after evaluating either + ranges::swap(t, u) or ranges::swap(u, t), t2 is equal to u and u2 is equal to t. + + Equality preservation + + Expressions declared in requires expressions of the standard library concepts are + required to be equality-preserving (except where stated otherwise). diff --git a/man/std::system.3 b/man/std::system.3 index 552a2e52b..f7e880c6d 100644 --- a/man/std::system.3 +++ b/man/std::system.3 @@ -1,44 +1,61 @@ -.TH std::system 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::system 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system \- std::system + .SH Synopsis Defined in header - int system( const char *command ); + int system( const char* command ); - Calls the host environment's command processor with command parameter. Returns - implementation-defined value (usually the value that the invoked program returns). + Calls the host environment's command processor (e.g. /bin/sh, cmd.exe) with the + parameter command. Returns an implementation-defined value (usually the value that + the invoked program returns). - If command is the NULL pointer, checks if host environment has a command processor - and returns nonzero value only if the command processor exists. + If command is a null pointer, checks if the host environment has a command processor + and returns a nonzero value if and only if the command processor exists. .SH Parameters character string identifying the command to be run in the command - command - processor. If NULL pointer is given, command processor is checked for + command - processor. If a null pointer is given, command processor is checked for existence .SH Return value - Implementation-defined value. If command is NULL returns nonzero value only if - command processor exists. + Implementation-defined value. If command is a null pointer, returns a nonzero value + if and only if the command processor exists. .SH Notes - Related POSIX function popen makes the output generated by command available to the - caller. + On POSIX systems, the return value can be decomposed using WEXITSTATUS and WSTOPSIG. + + The related POSIX function popen makes the output generated by command available to + the caller. + + An explicit flush of std::cout is also necessary before a call to std::system, if + the spawned process performs any screen I/O. .SH Example - In this example there is a system call of the unix command ls -l >test.txt: - // Run this code #include - + #include + #include + int main() { - std::system("ls -l >test.txt"); + std::system("ls -l >test.txt"); // executes the UNIX command "ls -l >test.txt" + std::cout << std::ifstream("test.txt").rdbuf(); } +.SH Possible output: + + total 16 + -rwxr-xr-x 1 2001 2000 8859 Sep 30 20:52 a.out + -rw-rw-rw- 1 2001 2000 161 Sep 30 20:52 main.cpp + -rw-r--r-- 1 2001 2000 0 Sep 30 20:52 test.txt + .SH See also C documentation for diff --git a/man/std::system_category.3 b/man/std::system_category.3 index cf8d9b2d6..80fe47ace 100644 --- a/man/std::system_category.3 +++ b/man/std::system_category.3 @@ -1,13 +1,17 @@ -.TH std::system_category 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::system_category 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system_category \- std::system_category + .SH Synopsis Defined in header - const std::error_category& system_category(); \fI(since C++11)\fP + const std::error_category& system_category() noexcept; \fI(since C++11)\fP Obtains a reference to the static error category object for errors reported by the operating system. The object is required to override the virtual function - error_category::name() to return a pointer to the string "system". It is also - required to override the virtual function error_category::default_error_condition() - to map the error codes that match POSIX errno values to std::generic_category. + std::error_category::name() to return a pointer to the string "system". It is also + required to override the virtual function + std::error_category::default_error_condition() to map the error codes that match + POSIX errno values to std::generic_category. .SH Parameters @@ -18,48 +22,49 @@ A reference to the static object of unspecified runtime type, derived from std::error_category. -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + On Windows, system_category() typically maps some Windows error codes to POSIX ones. + On POSIX, system_category() tends to be equivalent to std::generic_category() except + for the name. .SH Example - + // Run this code - #include - #include #include + #include #include - + #include + int main() { - std::error_condition econd = std::system_category().default_error_condition(EDOM); - std::cout << "Category: " << econd.category().name() << '\\n' - << "Value: " << econd.value() << '\\n' - << "Message: " << econd.message() << '\\n'; - - econd = std::system_category().default_error_condition(10001); - std::cout << "Category: " << econd.category().name() << '\\n' - << "Value: " << econd.value() << '\\n' - << "Message: " << econd.message() << '\\n'; + for (int const code : {EDOM, 10001}) + { + const std::error_condition econd = + std::system_category().default_error_condition(code); + + std::cout << "Category: " << econd.category().name() << '\\n' + << "Value: " << econd.value() << '\\n' + << "Message: " << econd.message() << "\\n\\n"; + } } -.SH Output: +.SH Possible output: Category: generic - Value: 33 - Message: Numerical argument out of domain + Value: 33 + Message: Numerical argument out of domain + Category: system - Value: 10001 - Message: Unknown error 10001 + Value: 10001 + Message: Unknown error 10001 .SH See also generic_category identifies the generic error category - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP errc the std::error_condition enumeration listing all standard \fI(C++11)\fP macro constants - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::system_error.3 b/man/std::system_error.3 index 62eacc5d4..0b51f4375 100644 --- a/man/std::system_error.3 +++ b/man/std::system_error.3 @@ -1,55 +1,63 @@ -.TH std::system_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::system_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system_error \- std::system_error + .SH Synopsis Defined in header class system_error; \fI(since C++11)\fP std::system_error is the type of the exception thrown by various library functions (typically the functions that interface with the OS facilities, e.g. the constructor - of std::thread), when the exception has an associated std::error_code which needs to - be reported. + of std::thread) when the exception has an associated std::error_code, which may be + reported. std-system error-inheritance.svg - About this image Inheritance diagram .SH Member functions constructor constructs the system_error object - \fI(public member function)\fP + \fI(public member function)\fP + operator= replaces the system_error object + \fI(public member function)\fP code returns error code - \fI(public member function)\fP - what returns explanatory string - \fB[virtual]\fP \fI(virtual public member function)\fP + \fI(public member function)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function)\fP Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP .SH Example - + // Run this code - #include #include #include - + #include + int main() { - try { + try + { std::thread().detach(); // attempt to detach a non-thread - } catch(const std::system_error& e) { - std::cout << "Caught system_error with code " << e.code() - << " meaning " << e.what() << '\\n'; + } + catch(const std::system_error& e) + { + std::cout << "Caught system_error with code " + "[" << e.code() << "] meaning " + "[" << e.what() << "]\\n"; } } -.SH Output: +.SH Possible output: - Caught system_error with code generic:22 meaning Invalid argument + Caught system_error with code [generic:22] meaning [Invalid argument] diff --git a/man/std::system_error::code.3 b/man/std::system_error::code.3 index 9dea90475..f8f12b311 100644 --- a/man/std::system_error::code.3 +++ b/man/std::system_error::code.3 @@ -1,6 +1,9 @@ -.TH std::system_error::code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::system_error::code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system_error::code \- std::system_error::code + .SH Synopsis - const std::error_code& code() const; \fI(since C++11)\fP + const std::error_code& code() const noexcept; \fI(since C++11)\fP Returns the stored error code. @@ -12,13 +15,7 @@ The stored error code. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also - what returns explanatory string - \fB[virtual]\fP \fI(virtual public member function)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function)\fP diff --git a/man/std::system_error::operator=.3 b/man/std::system_error::operator=.3 new file mode 100644 index 000000000..f0a892c8a --- /dev/null +++ b/man/std::system_error::operator=.3 @@ -0,0 +1,61 @@ +.TH std::system_error::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system_error::operator= \- std::system_error::operator= + +.SH Synopsis + system_error& operator=( const system_error& other ) noexcept; \fI(since C++11)\fP + + Assigns the contents with those of other. If *this and other both have dynamic type + std::system_error then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another system_error object to assign with + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(const std::system_error& e) + { + std::cout << "code: [" << e.code() << "]\\n" + "message: [" << e.code().message() << "]\\n" + "what: [" << e.what() << "]\\n\\n"; + } + + int main() + { + std::system_error e1(EDOM, std::generic_category(), "Error info #1"); + print(e1); + + std::system_error e2(EIO, std::system_category(), "Error info #2"); + print(e2); + + e1 = e2; + assert(std::strcmp(e1.what(), e2.what()) == 0); + print(e1); + } + +.SH Possible output: + + code: [generic:33] + message: [Numerical argument out of domain] + what: [Error info #1: Numerical argument out of domain] + + code: [system:5] + message: [Input/output error] + what: [Error info #2: Input/output error] + + code: [system:5] + message: [Input/output error] + what: [Error info #2: Input/output error] diff --git a/man/std::system_error::system_error.3 b/man/std::system_error::system_error.3 index d0c5a26e3..0f0ebbf5a 100644 --- a/man/std::system_error::system_error.3 +++ b/man/std::system_error::system_error.3 @@ -1,54 +1,66 @@ -.TH std::system_error::system_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::system_error::system_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system_error::system_error \- std::system_error::system_error + .SH Synopsis system_error( std::error_code ec ); \fB(1)\fP \fI(since C++11)\fP system_error( std::error_code ec, const std::string& what_arg ); \fB(2)\fP \fI(since C++11)\fP system_error( std::error_code ec, const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP system_error( int ev, const std::error_category& ecat ); \fB(3)\fP \fI(since C++11)\fP system_error( int ev, const std::error_category& ecat, \fB(4)\fP \fI(since C++11)\fP - const std::string& what_arg); + const std::string& what_arg ); system_error( int ev, const std::error_category& ecat, \fB(4)\fP \fI(since C++11)\fP - const char* what_arg); + const char* what_arg ); + system_error( const system_error& other ) noexcept; \fB(5)\fP \fI(since C++11)\fP Constructs new system error object. - 1) Constructs with error code ec + 1) Constructs with error code ec. 2) Constructs with error code ec and explanation string what_arg. The string - returned by what() is guaranteed to contain what_arg. + returned by what() is guaranteed to contain what_arg as a substring. 3) Constructs with underlying error code ev and associated error category ecat. 4) Constructs with underlying error code ev, associated error category ecat and explanatory string what_arg. The string returned by what() is guaranteed to contain - what_arg. + what_arg as a substring (assuming that it doesn't contain an embedded null + character). + 5) Copy constructor. Initializes the contents with those of other. If *this and + other both have dynamic type std::system_error then std::strcmp(what(), + other.what()) == 0. .SH Parameters ec - error code - ev - error code in base encoding + ev - underlying error code in the enumeration associated with ecat ecat - the category of error what_arg - explanatory string + other - another system_error to copy .SH Example - Demonstrates how to create a system_error exception from a errno value + Demonstrates how to create a system_error exception from an errno value. + - // Run this code #include #include - + int main() { try { - throw std::system_error(EDOM, std::system_category()); + throw std::system_error(EDOM, std::generic_category(), "FIX ME"); } - catch (const std::system_error& error) + catch (const std::system_error& ex) { - std::cout << "Error: " << error.code() - << " - " << error.code().message() << '\\n'; + std::cout << "code: [" << ex.code() << "]\\n" + "message: [" << ex.code().message() << "]\\n" + "what: [" << ex.what() << "]\\n"; } } -.SH Output: +.SH Possible output: - Error: system:33 - Numerical argument out of domain + code: [generic:33] + message: [Numerical argument out of domain] + what: [FIX ME: Numerical argument out of domain] diff --git a/man/std::system_error::what.3 b/man/std::system_error::what.3 index 13cb65ee4..04d1a13e7 100644 --- a/man/std::system_error::what.3 +++ b/man/std::system_error::what.3 @@ -1,6 +1,9 @@ -.TH std::system_error::what 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::system_error::what 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::system_error::what \- std::system_error::what + .SH Synopsis - virtual const char* what() const; \fI(since C++11)\fP + virtual const char* what() const noexcept; \fI(since C++11)\fP Returns the explanatory string. @@ -12,13 +15,7 @@ Pointer to a null-terminated string with explanatory information. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also code returns error code - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::tan(std::complex).3 b/man/std::tan(std::complex).3 index 83e997cc4..34066d4da 100644 --- a/man/std::tan(std::complex).3 +++ b/man/std::tan(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::tan(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tan(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tan(std::complex) \- std::tan(std::complex) + .SH Synopsis Defined in header template< class T > @@ -12,11 +15,70 @@ .SH Return value - Complex tangent of z. + If no errors occur, the complex tangent of z is returned. + + Errors and special cases are handled as if the operation is implemented by -i + * std::tanh(i * z), where i is the imaginary unit. + +.SH Notes + + Tangent is an analytical function on the complex plain and has no branch cuts. It is + periodic with respect to the real component, with period πi, and has poles of the + first order along the real line, at coordinates (π(1/2 + n), 0). However no common + floating-point representation is able to represent π/2 exactly, thus there is no + value of the argument for which a pole error occurs. + + Mathematical definition of the tangent is tan z = + + i(e-iz + -eiz + ) + e-iz + +eiz + + . + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z(1.0, 0.0); // behaves like real tangent along the real line + std::cout << "tan" << z << " = " << std::tan(z) + << " ( tan(1) = " << std::tan(1) << ")\\n"; + + std::complex z2(0.0, 1.0); // behaves like tanh along the imaginary line + std::cout << "tan" << z2 << " = " << std::tan(z2) + << " (tanh(1) = " << std::tanh(1) << ")\\n"; + } + +.SH Output: + + tan(1.000000,0.000000) = (1.557408,0.000000) ( tan\fB(1)\fP = 1.557408) + tan(0.000000,1.000000) = (0.000000,0.761594) (tanh\fB(1)\fP = 0.761594) .SH See also - sin(std::complex) computes sine of a complex number (sin(z)) - \fI(function template)\fP - cos(std::complex) computes cosine of a complex number (cos(z)) - \fI(function template)\fP + sin(std::complex) computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z)) + \fI(function template)\fP + cos(std::complex) computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z)) + \fI(function template)\fP + atan(std::complex) computes arc tangent of a complex number + \fI(C++11)\fP (\\({\\small\\arctan{z}}\\)arctan(z)) + \fI(function template)\fP + tan + tanf computes tangent (\\({\\small\\tan{x}}\\)tan(x)) + tanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tan(std::valarray) applies the function std::tan to each element of valarray + \fI(function template)\fP + C documentation for + ctan diff --git a/man/std::tan(std::valarray).3 b/man/std::tan(std::valarray).3 index 7e0480b70..28f87c814 100644 --- a/man/std::tan(std::valarray).3 +++ b/man/std::tan(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::tan(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tan(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tan(std::valarray) \- std::tan(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (tan) is used to perform the computation. If such function is - not available, std::tan is used due to argument dependent lookup. + not available, std::tan is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,16 +43,61 @@ valarray tan(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = tan(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH Category: +// Run this code + + #include + #include + #include + + auto show = [](char const* title, const std::valarray& va) + { + std::cout << title << " :"; + for (auto x : va) + std::cout << " " << std::fixed << x; + std::cout << '\\n'; + }; + + int main() + { + const std::valarray x = {.0, .1, .2, .3}; + const std::valarray y = std::tan(x); + const std::valarray z = std::atan(y); + + show("x ", x); + show("y = tan(x) ", y); + show("z = atan(y)", z); + } + +.SH Output: + + x : 0.000000 0.100000 0.200000 0.300000 + y = tan(x) : 0.000000 0.100335 0.202710 0.309336 + z = atan(y) : 0.000000 0.100000 0.200000 0.300000 + +.SH See also + + sin(std::valarray) applies the function std::sin to each element of valarray + \fI(function template)\fP + cos(std::valarray) applies the function std::cos to each element of valarray + \fI(function template)\fP + atan(std::valarray) applies the function std::atan to each element of valarray + \fI(function template)\fP + tan + tanf computes tangent (\\({\\small\\tan{x}}\\)tan(x)) + tanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tan(std::complex) computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z)) + \fI(function template)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::tan,std::tanf,std::tanl.3 b/man/std::tan,std::tanf,std::tanl.3 new file mode 100644 index 000000000..2b74bb4dd --- /dev/null +++ b/man/std::tan,std::tanf,std::tanl.3 @@ -0,0 +1,137 @@ +.TH std::tan,std::tanf,std::tanl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tan,std::tanf,std::tanl \- std::tan,std::tanf,std::tanl + +.SH Synopsis + Defined in header + float tan ( float num ); + + double tan ( double num ); (until C++23) + + long double tan ( long double num ); + /* floating-point-type */ (since C++23) + tan ( /* floating-point-type */ num ); (constexpr since C++26) + float tanf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double tanl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double tan ( Integer num ); + + 1-3) Computes the tangent of num (measured in radians). + The library provides overloads of std::tan for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value representing angle in radians + +.SH Return value + + If no errors occur, the tangent of num (tan(num)) is returned. + + The result may have little or no significance if the magnitude of num \fI(until C++11)\fP + is large. + + If a domain error occurs, an implementation-defined value is returned (NaN where + supported). + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0, it is returned unmodified. + * if the argument is ±∞, NaN is returned and FE_INVALID is raised. + * if the argument is NaN, NaN is returned. + +.SH Notes + + The case where the argument is infinite is not specified to be a domain error in C + (to which C++ defers), but it is defined as a domain error in POSIX. + + The function has mathematical poles at π(1/2 + n); however no common floating-point + representation is able to represent π/2 exactly, thus there is no value of the + argument for which a pole error occurs. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::tan(num) has the same effect as std::tan(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // #pragma STDC FENV_ACCESS ON + const double pi = std::acos(-1); // or C++20's std::numbers::pi + + int main() + { + // typical usage + std::cout << "tan(1*pi/4) = " << std::tan(1*pi/4) << '\\n' // 45° + << "tan(3*pi/4) = " << std::tan(3*pi/4) << '\\n' // 135° + << "tan(5*pi/4) = " << std::tan(5*pi/4) << '\\n' // -135° + << "tan(7*pi/4) = " << std::tan(7*pi/4) << '\\n'; // -45° + + // special values + std::cout << "tan(+0) = " << std::tan(0.0) << '\\n' + << "tan(-0) = " << std::tan(-0.0) << '\\n'; + + // error handling + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "tan(INFINITY) = " << std::tan(INFINITY) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + tan(1*pi/4) = 1 + tan(3*pi/4) = -1 + tan(5*pi/4) = 1 + tan(7*pi/4) = -1 + tan(+0) = 0 + tan(-0) = -0 + tan(INFINITY) = -nan + FE_INVALID raised + +.SH See also + + sin + sinf computes sine (\\({\\small\\sin{x}}\\)sin(x)) + sinl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cos + cosf computes cosine (\\({\\small\\cos{x}}\\)cos(x)) + cosl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atan + atanf computes arc tangent (\\({\\small\\arctan{x}}\\)arctan(x)) + atanl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tan(std::complex) computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z)) + \fI(function template)\fP + tan(std::valarray) applies the function std::tan to each element of valarray + \fI(function template)\fP + C documentation for + tan diff --git a/man/std::tan.3 b/man/std::tan.3 deleted file mode 100644 index a1b846d4d..000000000 --- a/man/std::tan.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::tan 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float tan( float arg ); - double tan( double arg ); - long double tan( long double arg ); - double tan( Integral arg ); \fI(since C++11)\fP - - Computes tangent of arg. - -.SH Parameters - - arg - value representing angle in radians, of a floating-point or Integral type - -.SH Return value - - Tangent of arg. - - Domain error occurs if arg is infinite. NAN is returned in that case. - -.SH See also - - sin computes sine (sin(x)) - \fI(function)\fP - cos computes cosine (cos(x)) - \fI(function)\fP - atan computes arc tangent (arctan(x)) - \fI(function)\fP - tan(std::complex) computes tangent of a complex number (tan(z)) - \fI(function template)\fP - tan(std::valarray) applies the function std::tan to each element of valarray - \fI(function template)\fP - C documentation for - tan diff --git a/man/std::tanh(std::complex).3 b/man/std::tanh(std::complex).3 index 368c9d96a..2a51c860b 100644 --- a/man/std::tanh(std::complex).3 +++ b/man/std::tanh(std::complex).3 @@ -1,4 +1,7 @@ -.TH std::tanh(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tanh(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tanh(std::complex) \- std::tanh(std::complex) + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP @@ -12,11 +15,95 @@ .SH Return value - Complex hyperbolic tangent of z + If no errors occur, complex hyperbolic tangent of z is returned. + + Error handling and special values + + Errors are reported consistent with math_errhandling. + + If the implementation supports IEEE floating-point arithmetic, + + * std::tanh(std::conj(z)) == std::conj(std::tanh(z)). + * std::tanh(-z) == -std::tanh(z). + * If z is (+0,+0), the result is (+0,+0). + * If z is (x,+∞) (for any^[1] finite x), the result is (NaN,NaN) and FE_INVALID is + raised. + * If z is (x,NaN) (for any^[2] finite x), the result is (NaN,NaN) and FE_INVALID + may be raised. + * If z is (+∞,y) (for any finite positive y), the result is (1,+0). + * If z is (+∞,+∞), the result is (1,±0) (the sign of the imaginary part is + unspecified). + * If z is (+∞,NaN), the result is (1,±0) (the sign of the imaginary part is + unspecified). + * If z is (NaN,+0), the result is (NaN,+0). + * If z is (NaN,y) (for any non-zero y), the result is (NaN,NaN) and FE_INVALID may + be raised. + * If z is (NaN,NaN), the result is (NaN,NaN). + 1. ↑ per C11 DR471, this only holds for non-zero x. If z is (0,∞), the result + should be (0,NaN). + 2. ↑ per C11 DR471, this only holds for non-zero x. If z is (0,NaN), the result + should be (0,NaN). + +.SH Notes + + Mathematical definition of hyperbolic tangent is tanh z = + + ez + -e-z + ez + +e-z + + . + + Hyperbolic tangent is an analytical function on the complex plane and has no branch + cuts. It is periodic with respect to the imaginary component, with period πi, and + has poles of the first order along the imaginary line, at coordinates (0, π(1/2 + + n)). However no common floating-point representation is able to represent π/2 + exactly, thus there is no value of the argument for which a pole error occurs. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::cout << std::fixed; + std::complex z(1.0, 0.0); // behaves like real tanh along the real line + std::cout << "tanh" << z << " = " << std::tanh(z) + << " (tanh(1) = " << std::tanh(1) << ")\\n"; + + std::complex z2(0.0, 1.0); // behaves like tangent along the imaginary line + std::cout << "tanh" << z2 << " = " << std::tanh(z2) + << " ( tan(1) = " << std::tan(1) << ")\\n"; + } + +.SH Output: + + tanh(1.000000,0.000000) = (0.761594,0.000000) (tanh\fB(1)\fP = 0.761594) + tanh(0.000000,1.000000) = (0.000000,1.557408) ( tan\fB(1)\fP = 1.557408) .SH See also - tan(std::complex) computes tangent of a complex number (tan(z)) - \fI(function template)\fP - atan(std::complex) computes arc tangent of a complex number (arctan(z)) - \fI(C++11)\fP \fI(function template)\fP + computes hyperbolic sine of a complex number + sinh(std::complex) (\\({\\small\\sinh{z}}\\)sinh(z)) + \fI(function template)\fP + computes hyperbolic cosine of a complex number + cosh(std::complex) (\\({\\small\\cosh{z}}\\)cosh(z)) + \fI(function template)\fP + atanh(std::complex) computes area hyperbolic tangent of a complex number + \fI(C++11)\fP (\\({\\small\\operatorname{artanh}{z}}\\)artanh(z)) + \fI(function template)\fP + tanh + tanhf computes hyperbolic tangent (\\({\\small\\tanh{x}}\\)tanh(x)) + tanhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + tanh(std::valarray) applies the function std::tanh to each element of valarray + \fI(function template)\fP + C documentation for + ctanh diff --git a/man/std::tanh(std::valarray).3 b/man/std::tanh(std::valarray).3 index c1015a80c..00365bc69 100644 --- a/man/std::tanh(std::valarray).3 +++ b/man/std::tanh(std::valarray).3 @@ -1,4 +1,7 @@ -.TH std::tanh(std::valarray) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tanh(std::valarray) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tanh(std::valarray) \- std::tanh(std::valarray) + .SH Synopsis Defined in header template< class T > @@ -17,7 +20,7 @@ .SH Notes Unqualified function (tanh) is used to perform the computation. If such function is - not available, std::tanh is used due to argument dependent lookup. + not available, std::tanh is used due to argument-dependent lookup. The function can be implemented with the return type different from std::valarray. In this case, the replacement type has the following properties: @@ -25,10 +28,12 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. @@ -38,21 +43,69 @@ valarray tanh(const valarray& va) { valarray other = va; - for (T &i : other) { + for (T& i : other) i = tanh(i); - } + + return other; // proxy object may be returned } .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include + #include + + auto show = [](char const* title, const std::valarray& va) + { + std::cout << title << " :"; + for (auto x : va) + std::cout << " " << std::fixed << x; + std::cout << '\\n'; + }; + + int main() + { + const std::valarray x = {.0, .1, .2, .3}; + const std::valarray sinh = std::sinh(x); + const std::valarray cosh = std::cosh(x); + const std::valarray tanh = std::tanh(x); + const std::valarray tanh_by_def = sinh / cosh; + const std::valarray tanh_2x = std::tanh(2.0 * x); + const std::valarray tanh_2x_by_def = + (2.0 * tanh) / (1.0 + std::pow(tanh, 2.0)); + + show("x ", x); + show("tanh(x) ", tanh); + show("tanh(x) (def) ", tanh_by_def); + show("tanh(2*x) ", tanh_2x); + show("tanh(2*x) (def)", tanh_2x_by_def); + } + +.SH Output: + + x : 0.000000 0.100000 0.200000 0.300000 + tanh(x) : 0.000000 0.099668 0.197375 0.291313 + tanh(x) (def) : 0.000000 0.099668 0.197375 0.291313 + tanh(2*x) : 0.000000 0.197375 0.379949 0.537050 + tanh(2*x) (def) : 0.000000 0.197375 0.379949 0.537050 - tanh hyperbolic tangent - \fI(function)\fP - -.SH Category: +.SH See also - * Todo no example + sinh(std::valarray) applies the function std::sinh to each element of valarray + \fI(function template)\fP + cosh(std::valarray) applies the function std::cosh to each element of valarray + \fI(function template)\fP + tanh + tanhf computes hyperbolic tangent (\\({\\small\\tanh{x}}\\)tanh(x)) + tanhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes hyperbolic tangent of a complex number + tanh(std::complex) (\\({\\small\\tanh{z}}\\)tanh(z)) + \fI(function template)\fP + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::tanh,std::tanhf,std::tanhl.3 b/man/std::tanh,std::tanhf,std::tanhl.3 new file mode 100644 index 000000000..698a33b2e --- /dev/null +++ b/man/std::tanh,std::tanhf,std::tanhl.3 @@ -0,0 +1,131 @@ +.TH std::tanh,std::tanhf,std::tanhl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tanh,std::tanhf,std::tanhl \- std::tanh,std::tanhf,std::tanhl + +.SH Synopsis + Defined in header + float tanh ( float num ); + + double tanh ( double num ); (until C++23) + + long double tanh ( long double num ); + /* floating-point-type */ (since C++23) + tanh ( /* floating-point-type */ num ); (constexpr since C++26) + float tanhf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double tanhl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double tanh ( Integer num ); + + 1-3) Computes the hyperbolic tangent of num. + The library provides overloads of std::tanh for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the hyperbolic tangent of num (tanh(num), or + + enum + -e-num + enum + +e-num + + ) is returned. + + If a range error occurs due to underflow, the correct result (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if the argument is ±0, ±0 is returned. + * if the argument is ±∞, ±1 is returned. + * if the argument is NaN, NaN is returned. + +.SH Notes + + POSIX specifies that in case of underflow, num is returned unmodified, and if that + is not supported, and implementation-defined value no greater than DBL_MIN, FLT_MIN, + and LDBL_MIN is returned. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::tanh(num) has the same effect as std::tanh(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + double get_random_between(double min, double max) + { + std::random_device rd; + std::mt19937 gen(rd()); + return std::uniform_real_distribution<>(min, max)(gen); + } + + int main() + { + const double x = get_random_between(-1.0, 1.0); + + std::cout << std::showpos + << "tanh(+1) = " << std::tanh(+1) << '\\n' + << "tanh(-1) = " << std::tanh(-1) << '\\n' + << "tanh(x)*sinh(2*x)-cos(2*x) = " + << std::tanh(x) * std::sinh(2 * x) - std::cosh(2 * x) << '\\n' + // special values: + << "tanh(+0) = " << std::tanh(+0.0) << '\\n' + << "tanh(-0) = " << std::tanh(-0.0) << '\\n'; + } + +.SH Output: + + tanh(+1) = +0.761594 + tanh(-1) = -0.761594 + tanh(x)*sinh(2*x)-cos(2*x) = -1 + tanh(+0) = +0 + tanh(-0) = -0 + +.SH See also + + sinh + sinhf computes hyperbolic sine (\\({\\small\\sinh{x}}\\)sinh(x)) + sinhl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + cosh + coshf computes hyperbolic cosine (\\({\\small\\cosh{x}}\\)cosh(x)) + coshl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + atanh + atanhf computes the inverse hyperbolic tangent + atanhl (\\({\\small\\operatorname{artanh}{x}}\\)artanh(x)) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + computes hyperbolic tangent of a complex number + tanh(std::complex) (\\({\\small\\tanh{z}}\\)tanh(z)) + \fI(function template)\fP + tanh(std::valarray) applies the function std::tanh to each element of valarray + \fI(function template)\fP + C documentation for + tanh diff --git a/man/std::tanh.3 b/man/std::tanh.3 deleted file mode 100644 index 461dade87..000000000 --- a/man/std::tanh.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::tanh 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float tanh( float arg ); - double tanh( double arg ); - long double tanh( long double arg ); - double tanh( Integral arg ); \fI(since C++11)\fP - - Computes hyperbolic tangent of arg - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - Hyperbolic tangent of arg. - -.SH See also - - sinh computes hyperbolic sine (sh(x)) - \fI(function)\fP - cosh computes hyperbolic cosine (ch(x)) - \fI(function)\fP - atanh area hyperbolic tangent - \fI(C++11)\fP \fI(function)\fP - tanh(std::complex) computes hyperbolic tangent of a complex number - \fI(function template)\fP - tanh(std::valarray) applies the function std::tanh to each element of valarray - \fI(function template)\fP - C documentation for - tanh diff --git a/man/std::terminate.3 b/man/std::terminate.3 index 890175edf..846373745 100644 --- a/man/std::terminate.3 +++ b/man/std::terminate.3 @@ -1,52 +1,88 @@ -.TH std::terminate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::terminate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::terminate \- std::terminate + .SH Synopsis Defined in header - void terminate(); \fI(until C++11)\fP - [[noreturn]] void terminate(); \fI(since C++11)\fP - - std::terminate() is called by the C++ runtime when exception handling fails for any - of the following reasons: - - 1) an exception is thrown and not caught (it is implementation-defined whether any - stack unwinding is done in this case) - 2) an exception is thrown during exception handling (e.g. from a destructor of some - local object, or from a function that had to be called during exception handling) - 3) the constructor or the destructor of a static or thread-local object throws an - exception - 4) a function registered with std::atexit or std::at_quick_exit throws an exception - 5) a noexcept specification is violated (it is implementation-defined whether any - stack unwinding is done in this case) - 6) a dynamic exception specification is violated and the default handler for - std::unexpected is executed - 7) a non-default handler for std::unexpected throws an exception that violates the - previously violated dynamic exception specification, if the specification does not - include std::bad_exception - 8) std::nested_exception::rethrow_nested is called for an object that isn't holding - a captured exception - 9) an exception is thrown from the initial function of std::thread - 10) a joinable std::thread is destroyed or assigned to + void terminate(); \fI(until C++11)\fP + [[noreturn]] void terminate() noexcept; \fI(since C++11)\fP + + std::terminate() is called by the C++ runtime when the program cannot continue for + any of the following reasons: + + 1) An exception is thrown and not caught (it is implementation-defined whether any + stack unwinding is done in this case). + 2) A function directly invoked by the exception handling mechanism while handling an + exception that has not yet been caught exits via an exception (e.g. a destructor of + some local object, or a copy constructor constructing a catch-clause parameter). + 3) The constructor or the destructor of a static + or thread-local + \fI(since C++11)\fP object throws an exception. + 4) A function registered with std::atexit + or std::at_quick_exit + \fI(since C++11)\fP throws an exception. + + 5) A dynamic exception specification is violated and the default + handler for std::unexpected is executed. + 6) A non-default handler for std::unexpected throws an exception that \fI(until C++17)\fP + violates the previously violated dynamic exception specification, if + the specification does not include std::bad_exception. + + 7) A noexcept specification is violated (it is implementation-defined + whether any stack unwinding is done in this case). + 8) std::nested_exception::rethrow_nested is called for an object that + isn't holding a captured exception. + 9) An exception is thrown from the initial function of std::thread. \fI(since C++11)\fP + 10) A joinable std::thread is destroyed or assigned to. + 11) std::condition_variable::wait, + std::condition_variable::wait_until, or + std::condition_variable::wait_for fails to reach its postcondition + (e.g. if relocking the mutex throws). + + 12) A function invoked by a parallel algorithm exits via an uncaught \fI(since C++17)\fP + exception and the execution policy specifies termination. std::terminate() may also be called directly from the program. + When std::terminate is called due to a thrown exception, an implicit try/catch + handler is considered active. Thus, calling std::current_exception will return the + thrown exception. + In any case, std::terminate calls the currently installed std::terminate_handler. The default std::terminate_handler calls std::abort. -.SH Parameters + If a destructor reset the terminate handler during stack unwinding and + the unwinding later led to terminate being called, the handler that + was installed at the end of the throw expression is the one that will \fI(until C++11)\fP + be called. (note: it was ambiguous whether re-throwing applied the new + handlers) + If a destructor reset the terminate handler during stack unwinding, it + is unspecified which handler is called if the unwinding later led to \fI(since C++11)\fP + terminate being called. + +.SH Notes - \fI(none)\fP + If the handler mechanism is not wanted, e.g. because it requires atomic operations + which may bloat binary size, a direct call to std::abort is preferred when + terminating the program abnormally. -.SH Return value + Some compiler intrinsics, e.g. __builtin_trap (gcc, clang, and icc) or __debugbreak + (msvc), can be used to terminate the program as fast as possible. - \fI(none)\fP + Defect reports -.SH Exceptions + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + DR Applied to Behavior as published Correct behavior + effect of calling std::set_terminate during + LWG 2111 C++11 stack made unspecified + unwinding differs from C++98 and breaks some + ABIs .SH See also terminate_handler the type of the function called by std::terminate - \fI(typedef)\fP + \fI(typedef)\fP + abort causes abnormal program termination (without cleaning up) + \fI(function)\fP diff --git a/man/std::terminate_handler.3 b/man/std::terminate_handler.3 index bf4cb052b..69e0bf02b 100644 --- a/man/std::terminate_handler.3 +++ b/man/std::terminate_handler.3 @@ -1,4 +1,7 @@ -.TH std::terminate_handler 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::terminate_handler 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::terminate_handler \- std::terminate_handler + .SH Synopsis Defined in header typedef void (*terminate_handler)(); @@ -7,6 +10,9 @@ no arguments and returns void), which is installed and queried by the functions std::set_terminate and std::get_terminate and called by std::terminate. + A std::terminate_handler shall terminate execution of the program without returning + to the caller, otherwise the behavior is undefined. + The C++ implementation provides a default std::terminate_handler function, which calls std::abort(). If the null pointer value is installed (by means of std::set_terminate), the implementation may restore the default handler instead. @@ -14,8 +20,8 @@ .SH See also terminate function called when exception handling fails - \fI(function)\fP + \fI(function)\fP set_terminate changes the function to be called by std::terminate - \fI(function)\fP + \fI(function)\fP get_terminate obtains the current terminate_handler - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::tgamma,std::tgammaf,std::tgammal.3 b/man/std::tgamma,std::tgammaf,std::tgammal.3 new file mode 100644 index 000000000..55887e5a6 --- /dev/null +++ b/man/std::tgamma,std::tgammaf,std::tgammal.3 @@ -0,0 +1,156 @@ +.TH std::tgamma,std::tgammaf,std::tgammal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tgamma,std::tgammaf,std::tgammal \- std::tgamma,std::tgammaf,std::tgammal + +.SH Synopsis + Defined in header + float tgamma ( float num ); + + double tgamma ( double num ); (until C++23) + + long double tgamma ( long double num ); + /* floating-point-type */ (since C++23) + tgamma ( /* floating-point-type */ num (constexpr since C++26) + ); \fB(1)\fP + float tgammaf( float num ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++26) + long double tgammal( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++26) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++26) + double tgamma ( Integer num ); + + 1-3) Computes the gamma function of num. + The library provides overloads of std::tgamma for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the value of the gamma function of num, that is + \\(\\Gamma(\\mathtt{num}) = \\displaystyle\\int_0^\\infty\\!\\! t^{\\mathtt{num}-1} e^{-t}\\, + dt\\)∫∞ + 0tnum-1 + e^-t dt, is returned. + + If a domain error occurs, an implementation-defined value (NaN where supported) is + returned. + + If a pole error occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is returned. + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned. + + If a range error due to underflow occurs, the correct value (after rounding) is + returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If num is zero or is an integer less than zero, a pole error or a domain error may + occur. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * If the argument is ±0, ±∞ is returned and FE_DIVBYZERO is raised. + * If the argument is a negative integer, NaN is returned and FE_INVALID is raised. + * If the argument is -∞, NaN is returned and FE_INVALID is raised. + * If the argument is +∞, +∞ is returned. + * If the argument is NaN, NaN is returned. + +.SH Notes + + If num is a natural number, std::tgamma(num) is the factorial of num - 1. Many + implementations calculate the exact integer-domain factorial if the argument is a + sufficiently small integer. + + For IEEE-compatible type double, overflow happens if 0 < num && num < 1 / DBL_MAX or + if num > 171.7. + + POSIX requires that a pole error occurs if the argument is zero, but a domain error + occurs when the argument is a negative integer. It also specifies that in future, + domain errors may be replaced by pole errors for negative integer arguments (in + which case the return value in those cases would change from NaN to ±∞). + + There is a non-standard function named gamma in various implementations, but its + definition is inconsistent. For example, glibc and 4.2BSD version of gamma executes + lgamma, but 4.4BSD version of gamma executes tgamma. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::tgamma(num) has the same effect as std::tgamma(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + // #pragma STDC FENV_ACCESS ON + + int main() + { + std::cout << "tgamma(10) = " << std::tgamma(10) + << ", 9! = " << 2 * 3 * 4 * 5 * 6 * 7 * 8 * 9 << '\\n' + << "tgamma(0.5) = " << std::tgamma(0.5) + << ", sqrt(pi) = " << std::sqrt(std::acos(-1)) << '\\n'; + + // special values + std::cout << "tgamma(1) = " << std::tgamma(1) << '\\n' + << "tgamma(+Inf) = " << std::tgamma(INFINITY) << '\\n'; + + // error handling + errno = 0; + std::feclearexcept(FE_ALL_EXCEPT); + + std::cout << "tgamma(-1) = " << std::tgamma(-1) << '\\n'; + + if (errno == EDOM) + std::cout << " errno == EDOM: " << std::strerror(errno) << '\\n'; + if (std::fetestexcept(FE_INVALID)) + std::cout << " FE_INVALID raised\\n"; + } + +.SH Possible output: + + tgamma\fB(10)\fP = 362880, 9! = 362880 + tgamma(0.5) = 1.77245, sqrt(pi) = 1.77245 + tgamma\fB(1)\fP = 1 + tgamma(+Inf) = inf + tgamma(-1) = nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised + +.SH See also + + lgamma + lgammaf + lgammal natural logarithm of the gamma function + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + beta + betaf + betal beta function + \fI(C++17)\fP \fI(function)\fP + \fI(C++17)\fP + \fI(C++17)\fP + C documentation for + tgamma + +.SH External links + + Weisstein, Eric W. "Gamma Function." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::tgamma.3 b/man/std::tgamma.3 deleted file mode 100644 index 6c77a2cdd..000000000 --- a/man/std::tgamma.3 +++ /dev/null @@ -1,67 +0,0 @@ -.TH std::tgamma 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float tgamma( float arg ); \fI(since C++11)\fP - double tgamma( double arg ); \fI(since C++11)\fP - long double tgamma( long double arg ); \fI(since C++11)\fP - double tgamma( Integral arg ); \fI(since C++11)\fP - - Computes the gamma function of arg. - -.SH Parameters - - arg - value of a floating-point or Integral type - -.SH Return value - - The value of the gamma function of arg, that is ∫∞ - 0targ-1 - e^-t dt. - - If arg is a natural number, std::tgamma(arg) is the factorial of arg-1. - -.SH Exceptions - - If arg is negative, domain error may occur and FE_INVALID may be raised. - - If arg is zero, pole error may occur and FE_DIVBYZERO may be raised. - - If arg is too large, range error may occur and FE_OVERFLOW may be raised. - - If arg is too small, range error may occur and FE_UNDERFLOW may be raised. - -.SH Notes - - Many implementations calculate the exact integer-domain factorial if the argument is - a sufficiently small integer. - -.SH Example - - -// Run this code - - #include - #include - double factorial(double arg) - { - return std::tgamma(arg + 1); - } - int main() - { - std::cout << "The factorial of 5 is " << factorial(5) << '\\n' - << "The factorial of 100 is " << factorial(100) << '\\n'; - } - -.SH Output: - - The factorial of 5 is 120 - The factorial of 100 is 9.33262e+157 - -.SH See also - - lgamma natural logarithm of the gamma function - \fI(C++11)\fP \fI(function)\fP - -.SH External links - - Weisstein, Eric W. "Gamma Function." From MathWorld--A Wolfram Web Resource. diff --git a/man/std::this_thread::get_id.3 b/man/std::this_thread::get_id.3 index a7b0abbe3..2ad3f58c9 100644 --- a/man/std::this_thread::get_id.3 +++ b/man/std::this_thread::get_id.3 @@ -1,7 +1,10 @@ -.TH std::this_thread::get_id 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::this_thread::get_id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::this_thread::get_id \- std::this_thread::get_id + .SH Synopsis Defined in header - std::thread::id get_id(); \fI(since C++11)\fP + std::thread::id get_id() noexcept; \fI(since C++11)\fP Returns the id of the current thread. @@ -11,46 +14,42 @@ .SH Return value - id of the current thread + id of the current thread. .SH Example - + // Run this code + #include #include + #include #include - #include - #include - - std::mutex g_display_mutex; - + using namespace std::chrono_literals; + void foo() { std::thread::id this_id = std::this_thread::get_id(); - - g_display_mutex.lock(); - std::cout << "thread " << this_id << " sleeping...\\n"; - g_display_mutex.unlock(); - - std::this_thread::sleep_for(std::chrono::seconds(1)); + + std::osyncstream(std::cout) << "thread " << this_id << " sleeping...\\n"; + + std::this_thread::sleep_for(500ms); } - + int main() { - std::thread t1(foo); - std::thread t2(foo); - - t1.join(); - t2.join(); + std::jthread t1{foo}; + std::jthread t2{foo}; } .SH Possible output: - thread 0x2384b312 sleeping... - thread 0x228a10fc sleeping... + thread 140113018054400 sleeping... + thread 140113009661696 sleeping... .SH See also get_id returns the id of the thread - \fI(public member function of std::thread)\fP + \fI(public member function of std::thread)\fP + C documentation for + thrd_current diff --git a/man/std::this_thread::sleep_for.3 b/man/std::this_thread::sleep_for.3 index 7664abcbb..2effcf05b 100644 --- a/man/std::this_thread::sleep_for.3 +++ b/man/std::this_thread::sleep_for.3 @@ -1,15 +1,22 @@ -.TH std::this_thread::sleep_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::this_thread::sleep_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::this_thread::sleep_for \- std::this_thread::sleep_for + .SH Synopsis Defined in header template< class Rep, class Period > - void sleep_for( const std::chrono::duration& \fI(since C++11)\fP + void sleep_for( const std::chrono::duration& \fI(since C++11)\fP sleep_duration ); Blocks the execution of the current thread for at least the specified sleep_duration. - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + This function may block for longer than sleep_duration due to scheduling or resource + contention delays. + + The standard recommends that a steady clock is used to measure the duration. If an + implementation uses a system clock instead, the wait time may also be sensitive to + clock adjustments. .SH Parameters @@ -22,31 +29,37 @@ .SH Exceptions Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + time points, and durations provided by the standard library never throw). .SH Example - + // Run this code - #include #include + #include #include - + int main() { - std::cout << "Hello waiter" << std::endl; - std::chrono::milliseconds dura( 2000 ); - std::this_thread::sleep_for( dura ); - std::cout << "Waited 2000 ms\\n"; + using namespace std::chrono_literals; + + std::cout << "Hello waiter\\n" << std::flush; + + const auto start = std::chrono::high_resolution_clock::now(); + std::this_thread::sleep_for(2000ms); + const auto end = std::chrono::high_resolution_clock::now(); + const std::chrono::duration elapsed = end - start; + + std::cout << "Waited " << elapsed << '\\n'; } -.SH Output: +.SH Possible output: Hello waiter - Waited 2000 ms + Waited 2000.13 ms .SH See also sleep_until stops the execution of the current thread until a specified time point - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::this_thread::sleep_until.3 b/man/std::this_thread::sleep_until.3 index 6c9f35e06..a65738489 100644 --- a/man/std::this_thread::sleep_until.3 +++ b/man/std::this_thread::sleep_until.3 @@ -1,18 +1,26 @@ -.TH std::this_thread::sleep_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::this_thread::sleep_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::this_thread::sleep_until \- std::this_thread::sleep_until + .SH Synopsis Defined in header template< class Clock, class Duration > - void sleep_until( const std::chrono::time_point& \fI(since C++11)\fP + void sleep_until( const std::chrono::time_point& \fI(since C++11)\fP sleep_time ); Blocks the execution of the current thread until specified sleep_time has been reached. - The clock tied to sleep_time is used, which means that adjustments of the clock are - taken into account. Thus, the duration of the block might, but might not, be less or - more than sleep_time - Clock::now() at the time of the call, depending on the - direction of the adjustment. The function also may block for longer than until after - sleep_time has been reached due to scheduling or resource contention delays. + Clock must meet the Clock requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP + + The standard recommends that the clock tied to sleep_time be used, in which case + adjustments of the clock may be taken into account. Thus, the duration of the block + might be more or less than sleep_time - Clock::now() at the time of the call, + depending on the direction of the adjustment and whether it is honored by the + implementation. The function also may block until after sleep_time has been reached + due to process scheduling or resource contention delays. .SH Parameters @@ -25,9 +33,42 @@ .SH Exceptions Any exception thrown by Clock or Duration (clocks and durations provided by the - standard library never throw) + standard library never throw). + +.SH Example + + +// Run this code + + #include + #include + #include + + auto now() { return std::chrono::steady_clock::now(); } + + auto awake_time() + { + using std::chrono::operator""ms; + return now() + 2000ms; + } + + int main() + { + std::cout << "Hello, waiter...\\n" << std::flush; + const auto start{now()}; + std::this_thread::sleep_until(awake_time()); + std::chrono::duration elapsed{now() - start}; + std::cout << "Waited " << elapsed.count() << " ms\\n"; + } + +.SH Possible output: + + Hello, waiter... + Waited 2000.17 ms .SH See also sleep_for stops the execution of the current thread for a specified time duration - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP + C documentation for + thrd_sleep diff --git a/man/std::this_thread::yield.3 b/man/std::this_thread::yield.3 index b69cdc20b..4c2f80223 100644 --- a/man/std::this_thread::yield.3 +++ b/man/std::this_thread::yield.3 @@ -1,7 +1,10 @@ -.TH std::this_thread::yield 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::this_thread::yield 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::this_thread::yield \- std::this_thread::yield + .SH Synopsis Defined in header - void yield(); \fI(since C++11)\fP + void yield() noexcept; \fI(since C++11)\fP Provides a hint to the implementation to reschedule the execution of threads, allowing other threads to run. @@ -25,30 +28,32 @@ .SH Example - + // Run this code - #include #include + #include #include - + // "busy sleep" while suggesting that other threads run // for a small amount of time void little_sleep(std::chrono::microseconds us) { auto start = std::chrono::high_resolution_clock::now(); auto end = start + us; - do { + do + { std::this_thread::yield(); - } while (std::chrono::high_resolution_clock::now() < end); + } + while (std::chrono::high_resolution_clock::now() < end); } - + int main() { auto start = std::chrono::high_resolution_clock::now(); - + little_sleep(std::chrono::microseconds(100)); - + auto elapsed = std::chrono::high_resolution_clock::now() - start; std::cout << "waited for " << std::chrono::duration_cast(elapsed).count() @@ -58,3 +63,8 @@ .SH Possible output: waited for 128 microseconds + +.SH See also + + C documentation for + thrd_yield diff --git a/man/std::thread.3 b/man/std::thread.3 index 67602adbd..5c04d8ec3 100644 --- a/man/std::thread.3 +++ b/man/std::thread.3 @@ -1,51 +1,75 @@ -.TH std::thread 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread \- std::thread + .SH Synopsis Defined in header class thread; \fI(since C++11)\fP The class thread represents a single thread of execution. Threads allow multiple - pieces of code to run asynchronously and simultaneously. + functions to execute concurrently. + + Threads begin execution immediately upon construction of the associated thread + object (pending any OS scheduling delays), starting at the top-level function + provided as a constructor argument. The return value of the top-level function is + ignored and if it terminates by throwing an exception, std::terminate is called. The + top-level function may communicate its return value or an exception to the caller + via std::promise or by modifying shared variables (which may require + synchronization, see std::mutex and std::atomic). + + std::thread objects may also be in the state that does not represent any thread + (after default construction, move from, detach, or join), and a thread of execution + may not be associated with any thread objects (after detach). + + No two std::thread objects may represent the same thread of execution; std::thread + is not CopyConstructible or CopyAssignable, although it is MoveConstructible and + MoveAssignable. .SH Member types - Member type Definition - native_handle_type implementation-defined + Member type Definition + native_handle_type (optional*) implementation-defined .SH Member classes id represents the id of a thread - \fI(public member class)\fP + \fI(public member class)\fP .SH Member functions constructor constructs new thread object - \fI(public member function)\fP + \fI(public member function)\fP destructs the thread object, underlying thread must be joined destructor or detached - \fI(public member function)\fP + \fI(public member function)\fP operator= moves the thread object - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers checks whether the thread is joinable, i.e. potentially running joinable in parallel context - \fI(public member function)\fP + \fI(public member function)\fP get_id returns the id of the thread - \fI(public member function)\fP + \fI(public member function)\fP native_handle returns the underlying implementation-defined thread handle - \fI(public member function)\fP + \fI(public member function)\fP hardware_concurrency returns the number of concurrent threads supported by the \fB[static]\fP implementation - \fI(public static member function)\fP + \fI(public static member function)\fP .SH Operations - join waits for a thread to finish its execution - \fI(public member function)\fP + join waits for the thread to finish its execution + \fI(public member function)\fP permits the thread to execute independently from the thread detach handle - \fI(public member function)\fP + \fI(public member function)\fP swap swaps two thread objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::thread) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function)\fP + +.SH See also + + jthread std::thread with support for auto-joining and cancellation + (C++20) \fI(class)\fP diff --git a/man/std::thread::detach.3 b/man/std::thread::detach.3 index ca1f69ffb..12c2fd73a 100644 --- a/man/std::thread::detach.3 +++ b/man/std::thread::detach.3 @@ -1,4 +1,7 @@ -.TH std::thread::detach 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::detach 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::detach \- std::thread::detach + .SH Synopsis void detach(); \fI(since C++11)\fP @@ -15,13 +18,9 @@ \fI(none)\fP -.SH Preconditions - - joinable is true - .SH Postconditions - joinable is false + joinable is false. .SH Exceptions @@ -29,20 +28,20 @@ .SH Example - + // Run this code - #include #include + #include #include - + void independentThread() { std::cout << "Starting concurrent thread.\\n"; std::this_thread::sleep_for(std::chrono::seconds(2)); std::cout << "Exiting concurrent thread.\\n"; } - + void threadCaller() { std::cout << "Starting thread caller.\\n"; @@ -51,7 +50,7 @@ std::this_thread::sleep_for(std::chrono::seconds(1)); std::cout << "Exiting thread caller.\\n"; } - + int main() { threadCaller(); @@ -65,16 +64,30 @@ Exiting thread caller. Exiting concurrent thread. -.SH See also +.SH References - join waits for a thread to finish its execution - \fI(public member function)\fP - checks whether the thread is joinable, i.e. potentially running in parallel - joinable context - \fI(public member function)\fP + * C++23 standard (ISO/IEC 14882:2023): -.SH References + * 33.4.3.6 Members [thread.thread.member] + * C++20 standard (ISO/IEC 14882:2020): + * 32.4.2.5 Members [thread.thread.member] + * C++17 standard (ISO/IEC 14882:2017): + + * 33.3.2.5 thread members [thread.thread.member] + * C++14 standard (ISO/IEC 14882:2014): + + * 30.3.1.5 thread members [thread.thread.member] * C++11 standard (ISO/IEC 14882:2011): * 30.3.1.5 thread members [thread.thread.member] + +.SH See also + + join waits for the thread to finish its execution + \fI(public member function)\fP + checks whether the thread is joinable, i.e. potentially running in parallel + joinable context + \fI(public member function)\fP + C documentation for + thrd_detach diff --git a/man/std::thread::get_id.3 b/man/std::thread::get_id.3 index 4d61d8e66..18b0ea4c8 100644 --- a/man/std::thread::get_id.3 +++ b/man/std::thread::get_id.3 @@ -1,6 +1,9 @@ -.TH std::thread::get_id 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::get_id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::get_id \- std::thread::get_id + .SH Synopsis - std::thread::id get_id() const; \fI(since C++11)\fP + std::thread::id get_id() const noexcept; \fI(since C++11)\fP Returns a value of std::thread::id identifying the thread associated with *this. @@ -13,50 +16,49 @@ A value of type std::thread::id identifying the thread associated with *this. If there is no thread associated, default constructed std::thread::id is returned. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code + #include #include #include - #include - + void foo() { std::this_thread::sleep_for(std::chrono::seconds(1)); } - + int main() { std::thread t1(foo); std::thread::id t1_id = t1.get_id(); - + std::thread t2(foo); std::thread::id t2_id = t2.get_id(); - + std::cout << "t1's id: " << t1_id << '\\n'; std::cout << "t2's id: " << t2_id << '\\n'; - + t1.join(); t2.join(); + + std::cout << "t1's id after join: " << t1.get_id() << '\\n'; + std::cout << "t2's id after join: " << t2.get_id() << '\\n'; } .SH Possible output: - t1's id: 0x35a7210f - t2's id: 0x35a311c4 + t1's id: 140146221688576 + t2's id: 140146213295872 + t1's id after join: thread::id of a non-executing thread + t2's id after join: thread::id of a non-executing thread .SH See also id represents the id of a thread - \fI(public member class)\fP + \fI(public member class)\fP checks whether the thread is joinable, i.e. potentially running in parallel joinable context - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::thread::hardware_concurrency.3 b/man/std::thread::hardware_concurrency.3 index f156f81af..dbb4d8470 100644 --- a/man/std::thread::hardware_concurrency.3 +++ b/man/std::thread::hardware_concurrency.3 @@ -1,8 +1,11 @@ -.TH std::thread::hardware_concurrency 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::hardware_concurrency 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::hardware_concurrency \- std::thread::hardware_concurrency + .SH Synopsis - static unsigned hardware_concurrency(); \fI(since C++11)\fP + static unsigned int hardware_concurrency() noexcept; \fI(since C++11)\fP - Returns number of concurrent threads supported by the implementation. The value + Returns the number of concurrent threads supported by the implementation. The value should be considered only a hint. .SH Parameters @@ -11,24 +14,19 @@ .SH Return value - number of concurrent threads supported. If the value is not well defined or not + Number of concurrent threads supported. If the value is not well defined or not computable, returns 0. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - - int main() { + + int main() + { unsigned int n = std::thread::hardware_concurrency(); std::cout << n << " concurrent threads are supported.\\n"; } @@ -36,3 +34,9 @@ .SH Possible output: 4 concurrent threads are supported. + +.SH See also + + hardware_destructive_interference_size min offset to avoid false sharing + hardware_constructive_interference_size max offset to promote true sharing + \fI(C++17)\fP (constant) diff --git a/man/std::thread::id.3 b/man/std::thread::id.3 index b1103219c..67099e85c 100644 --- a/man/std::thread::id.3 +++ b/man/std::thread::id.3 @@ -1,10 +1,15 @@ -.TH std::thread::id 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::id \- std::thread::id + .SH Synopsis Defined in header class thread::id; \fI(since C++11)\fP The class thread::id is a lightweight, trivially copyable class that serves as a - unique identifier of std::thread objects. + unique identifier of std::thread + and std::jthread + \fI(since C++20)\fP objects. Instances of this class may also hold the special distinct value that does not represent any thread. Once a thread has finished, the value of std::thread::id may @@ -22,19 +27,30 @@ operator== operator!= - operator< compares two thread::id objects - operator<= \fI(function)\fP + operator< + operator<= operator> - operator>= - operator<< serializes a thread::id object - \fI(function template)\fP + operator>= compares two thread::id objects + operator<=> \fI(function)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + operator<< serializes a thread::id object + \fI(function template)\fP .SH Helper classes - std::hash specializes std::hash - \fI(class template specialization)\fP + std::hash hash support for std::thread::id + \fI(C++11)\fP \fI(class template specialization)\fP + std::formatter formatting support for thread::id + (C++23) \fI(class template specialization)\fP .SH See also - get_id returns the id of the thread - \fI(public member function)\fP + get_id returns the id of the thread + \fI(public member function)\fP + get_id returns the thread id of the current thread + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::thread::id::id.3 b/man/std::thread::id::id.3 index e68eb363a..e0ccf6d18 100644 --- a/man/std::thread::id::id.3 +++ b/man/std::thread::id::id.3 @@ -1,6 +1,9 @@ -.TH std::thread::id::id 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::id::id 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::id::id \- std::thread::id::id + .SH Synopsis - id(); \fI(since C++11)\fP + id() noexcept; \fI(since C++11)\fP Default-constructs a new thread identifier. The identifier does not represent a thread. @@ -8,9 +11,3 @@ .SH Parameters \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::thread::join.3 b/man/std::thread::join.3 index 8ea4372b7..1ff9fb067 100644 --- a/man/std::thread::join.3 +++ b/man/std::thread::join.3 @@ -1,10 +1,20 @@ -.TH std::thread::join 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::join 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::join \- std::thread::join + .SH Synopsis void join(); \fI(since C++11)\fP Blocks the current thread until the thread identified by *this finishes its execution. + The completion of the thread identified by *this synchronizes with the corresponding + successful return from join(). + + No synchronization is performed on *this itself. Concurrently calling join() on the + same thread object from multiple threads constitutes a data race that results in + undefined behavior. + .SH Parameters \fI(none)\fP @@ -13,58 +23,54 @@ \fI(none)\fP -.SH Preconditions - - joinable is true - .SH Postconditions - joinable is false + joinable() is false. .SH Exceptions std::system_error if an error occurs. -.SH Error Conditions + Error conditions * resource_deadlock_would_occur if this->get_id() == std::this_thread::get_id() - \fI(deadlock detected)\fP - * no_such_process if the thread is not valid - * invalid_argument if joinable is false + \fI(deadlock detected)\fP. + * no_such_process if the thread is not valid. + * invalid_argument if joinable() is false. .SH Example - + // Run this code + #include #include #include - #include - + void foo() { // simulate expensive operation std::this_thread::sleep_for(std::chrono::seconds(1)); } - + void bar() { // simulate expensive operation std::this_thread::sleep_for(std::chrono::seconds(1)); } - + int main() { std::cout << "starting first helper...\\n"; std::thread helper1(foo); - + std::cout << "starting second helper...\\n"; std::thread helper2(bar); - + std::cout << "waiting for helpers to finish..." << std::endl; helper1.join(); helper2.join(); - + std::cout << "done!\\n"; } @@ -75,16 +81,30 @@ waiting for helpers to finish... done! -.SH See also +.SH References - detach permits the thread to execute independently from the thread handle - \fI(public member function)\fP - checks whether the thread is joinable, i.e. potentially running in parallel - joinable context - \fI(public member function)\fP + * C++23 standard (ISO/IEC 14882:2023): -.SH References + * 33.4.3.6 Members [thread.thread.member] + * C++20 standard (ISO/IEC 14882:2020): + + * 32.4.2.5 Members [thread.thread.member] + * C++17 standard (ISO/IEC 14882:2017): + + * 33.3.2.5 thread members [thread.thread.member] + * C++14 standard (ISO/IEC 14882:2014): + * 30.3.1.5 thread members [thread.thread.member] * C++11 standard (ISO/IEC 14882:2011): * 30.3.1.5 thread members [thread.thread.member] + +.SH See also + + detach permits the thread to execute independently from the thread handle + \fI(public member function)\fP + checks whether the thread is joinable, i.e. potentially running in parallel + joinable context + \fI(public member function)\fP + C documentation for + thrd_join diff --git a/man/std::thread::joinable.3 b/man/std::thread::joinable.3 index 41f306154..23b0c8844 100644 --- a/man/std::thread::joinable.3 +++ b/man/std::thread::joinable.3 @@ -1,10 +1,13 @@ -.TH std::thread::joinable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::joinable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::joinable \- std::thread::joinable + .SH Synopsis - bool joinable() const; \fI(since C++11)\fP + bool joinable() const noexcept; \fI(since C++11)\fP - Checks if the thread object identifies an active thread of execution. Specifically, - returns true if get_id() != std::thread::id(). So a default constructed thread is - not joinable. + Checks if the std::thread object identifies an active thread of execution. + Specifically, returns true if get_id() != std::thread::id(). So a default + constructed thread is not joinable. A thread that has finished executing code, but has not yet been joined is still considered an active thread of execution and is therefore joinable. @@ -15,55 +18,72 @@ .SH Return value - true if the thread object identifies an active thread of execution, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the thread object identifies an active thread of execution, false otherwise. .SH Example - + // Run this code + #include #include #include - #include - + using namespace std::chrono_literals; + void foo() { - std::this_thread::sleep_for(std::chrono::seconds(1)); + std::this_thread::sleep_for(500ms); } - + int main() { + std::cout << std::boolalpha; + std::thread t; std::cout << "before starting, joinable: " << t.joinable() << '\\n'; - - t = std::thread(foo); + + t = std::thread{foo}; std::cout << "after starting, joinable: " << t.joinable() << '\\n'; - + t.join(); + std::cout << "after joining, joinable: " << t.joinable() << '\\n'; + + t = std::thread{foo}; + t.detach(); + std::cout << "after detaching, joinable: " << t.joinable() << '\\n'; + std::this_thread::sleep_for(1500ms); } .SH Output: - before starting, joinable: 0 - after starting, joinable: 1 + before starting, joinable: false + after starting, joinable: true + after joining, joinable: false + after detaching, joinable: false -.SH See also +.SH References - get_id returns the id of the thread - \fI(public member function)\fP - join waits for a thread to finish its execution - \fI(public member function)\fP - detach permits the thread to execute independently from the thread handle - \fI(public member function)\fP + * C++23 standard (ISO/IEC 14882:2023): -.SH References + * 33.4.3.6 Members [thread.thread.member] + * C++20 standard (ISO/IEC 14882:2020): + + * 32.4.2.5 Members [thread.thread.member] + * C++17 standard (ISO/IEC 14882:2017): + + * 33.3.2.5 thread members [thread.thread.member] + * C++14 standard (ISO/IEC 14882:2014): + * 30.3.1.5 thread members [thread.thread.member] * C++11 standard (ISO/IEC 14882:2011): * 30.3.1.5 thread members [thread.thread.member] + +.SH See also + + get_id returns the id of the thread + \fI(public member function)\fP + join waits for the thread to finish its execution + \fI(public member function)\fP + detach permits the thread to execute independently from the thread handle + \fI(public member function)\fP diff --git a/man/std::thread::native_handle.3 b/man/std::thread::native_handle.3 index 086a7708c..099a5f182 100644 --- a/man/std::thread::native_handle.3 +++ b/man/std::thread::native_handle.3 @@ -1,6 +1,10 @@ -.TH std::thread::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::native_handle \- std::thread::native_handle + .SH Synopsis native_handle_type native_handle(); \fI(since C++11)\fP + (not always present) Returns the implementation defined underlying thread handle. @@ -10,51 +14,50 @@ .SH Return value - implementation defined handle type representing the thread. + Implementation defined handle type representing the thread. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Example - Uses native_handle to enable realtime scheduling of C++ threads on a POSIX system + Uses native_handle to enable realtime scheduling of C++ threads on a POSIX system. + - // Run this code - #include - #include - #include #include #include + #include + #include #include - + #include + std::mutex iomutex; void f(int num) { std::this_thread::sleep_for(std::chrono::seconds(1)); - - sched_param sch; - int policy; - pthread_getschedparam(pthread_self(), &policy, &sch); - std::lock_guard lk(iomutex); - std::cout << "Thread " << num << " is executing at priority " - << sch.sched_priority << '\\n'; + + sched_param sch; + int policy; + pthread_getschedparam(pthread_self(), &policy, &sch); + std::lock_guard lk(iomutex); + std::cout << "Thread " << num << " is executing at priority " + << sch.sched_priority << '\\n'; } - + int main() { std::thread t1(f, 1), t2(f, 2); - + sched_param sch; int policy; pthread_getschedparam(t1.native_handle(), &policy, &sch); sch.sched_priority = 20; - if(pthread_setschedparam(t1.native_handle(), SCHED_FIFO, &sch)) { + if (pthread_setschedparam(t1.native_handle(), SCHED_FIFO, &sch)) std::cout << "Failed to setschedparam: " << std::strerror(errno) << '\\n'; - } - + t1.join(); t2.join(); } diff --git a/man/std::thread::operator=.3 b/man/std::thread::operator=.3 index 0e8633aed..605ec732e 100644 --- a/man/std::thread::operator=.3 +++ b/man/std::thread::operator=.3 @@ -1,11 +1,16 @@ -.TH std::thread::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::operator= \- std::thread::operator= + .SH Synopsis - thread& operator=( thread&& other ); \fI(since C++11)\fP + thread& operator=( thread&& other ) noexcept; \fI(since C++11)\fP - Assigns the state of other to *this using move semantics. + If *this still has an associated running thread (i.e. joinable() == true), calls + std::terminate(). Otherwise, assigns the state of other to *this and sets other to a + default constructed state. - If *this still has an associated running thread (i.e. joinable() == true), - std::terminate() is called. + After this call, this->get_id() is equal to the value of other.get_id() prior to the + call, and other no longer represents a thread of execution. .SH Parameters @@ -14,9 +19,3 @@ .SH Return value *this - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::thread::swap.3 b/man/std::thread::swap.3 index 72d5f95ac..1256c8523 100644 --- a/man/std::thread::swap.3 +++ b/man/std::thread::swap.3 @@ -1,6 +1,9 @@ -.TH std::thread::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::swap \- std::thread::swap + .SH Synopsis - void swap( thread& other ); \fI(since C++11)\fP + void swap( std::thread& other ) noexcept; \fI(since C++11)\fP Exchanges the underlying handles of two thread objects. @@ -12,67 +15,61 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code + #include #include #include - #include - + void foo() { std::this_thread::sleep_for(std::chrono::seconds(1)); } - + void bar() { std::this_thread::sleep_for(std::chrono::seconds(1)); } - + int main() { std::thread t1(foo); std::thread t2(bar); - - std::cout << "thread 1 id: " << t1.get_id() << std::endl; - std::cout << "thread 2 id: " << t2.get_id() << std::endl; - + + std::cout << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + std::swap(t1, t2); - - std::cout << "after std::swap(t1, t2):" << std::endl; - std::cout << "thread 1 id: " << t1.get_id() << std::endl; - std::cout << "thread 2 id: " << t2.get_id() << std::endl; - + + std::cout << "after std::swap(t1, t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + t1.swap(t2); - - std::cout << "after t1.swap(t2):" << std::endl; - std::cout << "thread 1 id: " << t1.get_id() << std::endl; - std::cout << "thread 2 id: " << t2.get_id() << std::endl; - + + std::cout << "after t1.swap(t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + t1.join(); t2.join(); } .SH Possible output: - thread 1 id: 1892 - thread 2 id: 2584 + thread 1 id: 140185268262656 + thread 2 id: 140185259869952 after std::swap(t1, t2): - thread 1 id: 2584 - thread 2 id: 1892 + thread 1 id: 140185259869952 + thread 2 id: 140185268262656 after t1.swap(t2): - thread 1 id: 1892 - thread 2 id: 2584 + thread 1 id: 140185268262656 + thread 2 id: 140185259869952 .SH See also std::swap(std::thread) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::thread::thread.3 b/man/std::thread::thread.3 index d1dea01d5..6eca01221 100644 --- a/man/std::thread::thread.3 +++ b/man/std::thread::thread.3 @@ -1,84 +1,83 @@ -.TH std::thread::thread 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::thread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::thread \- std::thread::thread + .SH Synopsis - thread(); \fB(1)\fP \fI(since C++11)\fP - thread( thread&& other ); \fB(2)\fP \fI(since C++11)\fP - template< class Function, class... Args > \fB(3)\fP \fI(since C++11)\fP - explicit thread( Function&& f, Args&&... args ); - thread(const thread&) = delete; \fB(4)\fP \fI(since C++11)\fP + thread() noexcept; \fB(1)\fP \fI(since C++11)\fP + thread( thread&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + template< class F, class... Args > \fB(3)\fP \fI(since C++11)\fP + explicit thread( F&& f, Args&&... args ); + thread( const thread& ) = delete; \fB(4)\fP \fI(since C++11)\fP - Constructs new thread object. + Constructs a new std::thread object. - 1) Creates new thread object which does not represent a thread. - 2) Move constructor. Constructs the thread object to represent the thread of + 1) Creates a new std::thread object which does not represent a thread. + 2) Move constructor. Constructs the std::thread object to represent the thread of execution that was represented by other. After this call other no longer represents a thread of execution. - 3) Creates new std::thread object and associates it with a thread of execution. - First the constructor copies/moves all arguments args... to thread-accessible - storage as if by the function: - - template - typename decay::type decay_copy(T&& v) { - return std::forward(v); - } - - Any exceptions thrown during evaluation and copying/moving of the arguments are - thrown in the current thread, not the new thread. - The code that will be run in the new thread is defined as follows. Let's refer to - value_args as t1, t2, ..., tN, where N is sizeof...(value_args)and value_args is the - result of calling decay_copy as defined above. The following code will be run in the - new thread: - - * If f is pointer to a member function of class T, then it is called. The return - value is ignored. Effectively, the following code is executed: - - * (t1.*f)(t2, ..., tN) if the type of t1 is either T, reference to T or reference - to type derived from T. - * ((*t1).*f)(t2, ..., tN) otherwise. - - * If N == 1 and f is pointer to a member data object of a class, then it is - accessed. The value of the object is ignored. Effectively, the following code is - executed: - - * t1.*f if and the type of t1 is either T, reference to T or reference to type - derived from T. - * (*t1).*f otherwise. - - * f is called as a pointer to a non-member function in all other cases. The return - value is ignored. Effectively, f(t1, t2, ..., tN) is executed. - - \fI(C++14)\fP This constructor does not participate in overload resolution if - std::decay::type is the same type as std::thread. + 3) Creates a new std::thread object and associates it with a thread of execution. + The new thread of execution starts executing: + + INVOKE(decay-copy(std::forward(f)), (until C++23) + decay-copy(std::forward(args))...) + std::invoke(auto(std::forward(f)), (since C++23) + auto(std::forward(args))...) + + The calls of decay-copy are evaluated + (until C++23) + The values produced by auto are materialized + (since C++23) in the current thread, so that any exceptions thrown during evaluation + and copying/moving of the arguments are thrown in the current thread, without + starting the new thread. + This overload participates in overload resolution only if + std::decay::type + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP is not the same type as std::thread. + + If any of the following conditions is satisfied, the program is + ill-formed: + + * F is not MoveConstructible. \fI(until C++20)\fP + * Any type in Args is not MoveConstructible. + * INVOKE(decay-copy(std::forward(f)), + decay-copy(std::forward(args))...) is not a valid + expression. + If any of the following is false, the program is ill-formed: + + * std::is_constructible_v, F> \fI(since C++20)\fP + * (std::is_constructible_v, Args> && ...) + * std::is_invocable_v, std::decay_t...> + + The completion of the invocation of the constructor synchronizes with the beginning + of the invocation of the copy of f on the new thread of execution. 4) The copy constructor is deleted; threads are not copyable. No two std::thread objects may represent the same thread of execution. .SH Parameters - other - another thread object to construct this thread object with - f - Callable object to execute in the new thread - args... - arguments to pass to the new function + other - another thread object to construct this thread object with + f - Callable object to execute in the new thread + args - arguments to pass to the new function .SH Postconditions - 1) get_id() equal to std::thread::id() (i.e. joinable is false) + 1) get_id() equal to std::thread::id() (i.e. joinable() is false). 2) other.get_id() equal to std::thread::id() and get_id() returns the value of - other.get_id() prior to the start of construction - 3) get_id() not equal to std::thread::id() (i.e. joinable is true) + other.get_id() prior to the start of construction. + 3) get_id() not equal to std::thread::id() (i.e. joinable() is true). .SH Exceptions - 1-2) - noexcept specification: - noexcept - 3) std::system_error if the thread could not be started. The exception may represent the error condition std::errc::resource_unavailable_try_again or another implementation-specific error condition. .SH Notes - The arguments to the thread function are copied by value. If a reference argument - needs to be passed to the thread function, it has to be wrapped (e.g. with std::ref - or std::cref). + The arguments to the thread function are moved or copied by value. If a reference + argument needs to be passed to the thread function, it has to be wrapped (e.g., with + std::ref or std::cref). Any return value from the function is ignored. If the function throws an exception, std::terminate is called. In order to pass return values or exceptions back to the @@ -86,62 +85,146 @@ .SH Example - + // Run this code + #include #include - #include #include - #include - #include - #include - + #include + void f1(int n) { - for (int i = 0; i < 5; ++i) { + for (int i = 0; i < 5; ++i) + { std::cout << "Thread 1 executing\\n"; ++n; std::this_thread::sleep_for(std::chrono::milliseconds(10)); } } - + void f2(int& n) { - for (int i = 0; i < 5; ++i) { + for (int i = 0; i < 5; ++i) + { std::cout << "Thread 2 executing\\n"; ++n; std::this_thread::sleep_for(std::chrono::milliseconds(10)); } } - + + class foo + { + public: + void bar() + { + for (int i = 0; i < 5; ++i) + { + std::cout << "Thread 3 executing\\n"; + ++n; + std::this_thread::sleep_for(std::chrono::milliseconds(10)); + } + } + int n = 0; + }; + + class baz + { + public: + void operator()() + { + for (int i = 0; i < 5; ++i) + { + std::cout << "Thread 4 executing\\n"; + ++n; + std::this_thread::sleep_for(std::chrono::milliseconds(10)); + } + } + int n = 0; + }; + int main() { int n = 0; + foo f; + baz b; std::thread t1; // t1 is not a thread std::thread t2(f1, n + 1); // pass by value std::thread t3(f2, std::ref(n)); // pass by reference std::thread t4(std::move(t3)); // t4 is now running f2(). t3 is no longer a thread + std::thread t5(&foo::bar, &f); // t5 runs foo::bar() on object f + std::thread t6(b); // t6 runs baz::operator() on a copy of object b t2.join(); t4.join(); + t5.join(); + t6.join(); std::cout << "Final value of n is " << n << '\\n'; + std::cout << "Final value of f.n (foo::n) is " << f.n << '\\n'; + std::cout << "Final value of b.n (baz::n) is " << b.n << '\\n'; } .SH Possible output: Thread 1 executing Thread 2 executing + Thread 3 executing + Thread 4 executing + Thread 3 executing Thread 1 executing Thread 2 executing - Thread 1 executing + Thread 4 executing Thread 2 executing + Thread 3 executing Thread 1 executing + Thread 4 executing + Thread 3 executing Thread 2 executing - Thread 2 executing Thread 1 executing + Thread 4 executing + Thread 3 executing + Thread 1 executing + Thread 2 executing + Thread 4 executing Final value of n is 5 + Final value of f.n (foo::n) is 5 + Final value of b.n (baz::n) is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2097 C++11 for overload \fB(3)\fP, F could be std::thread F is constrained + overload \fB(3)\fP directly required (the decayed + LWG 3476 C++20 types of) removed these + F and the argument types to be move requirements^[1] + constructible + + 1. ↑ The move-constructibility is already indirectly required by + std::is_constructible_v. .SH References + * C++23 standard (ISO/IEC 14882:2023): + + * 33.4.3.3 thread constructors [thread.thread.constr] + * C++20 standard (ISO/IEC 14882:2020): + + * 32.4.2.2 thread constructors [thread.thread.constr] + * C++17 standard (ISO/IEC 14882:2017): + + * 33.3.2.2 thread constructors [thread.thread.constr] + * C++14 standard (ISO/IEC 14882:2014): + + * 30.3.1.2 thread constructors [thread.thread.constr] * C++11 standard (ISO/IEC 14882:2011): * 30.3.1.2 thread constructors [thread.thread.constr] + +.SH See also + + constructor constructs new jthread object + \fI(public member function of std::jthread)\fP + C documentation for + thrd_create diff --git a/man/std::thread::~thread.3 b/man/std::thread::~thread.3 index 050c1833d..1146a39b3 100644 --- a/man/std::thread::~thread.3 +++ b/man/std::thread::~thread.3 @@ -1,6 +1,43 @@ -.TH std::thread::~thread 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::thread::~thread 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::thread::~thread \- std::thread::~thread + .SH Synopsis ~thread(); \fI(since C++11)\fP - Destroys the thread object. If *this still has an associated running thread (i.e. - joinable() == true), std::terminate() is called. + Destroys the thread object. + + If *this has an associated thread (joinable() == true), std::terminate() is called. + +.SH Notes + + A thread object does not have an associated thread (and is safe to destroy) after + + * it was default-constructed. + * it was moved from. + * join() has been called. + * detach() has been called. + +.SH Example + + +// Run this code + + #include + using namespace std::chrono_literals; + + int main() + { + auto bleah = std::thread{[]{ std::this_thread::sleep_for(13ms); }}; + + } // ~thread calls std::terminate() + +.SH Possible output: + + terminate called without an active exception + +.SH See also + + if the thread is joinable, then a stop is requested and the thread + destructor joins + \fI(public member function of std::jthread)\fP diff --git a/man/std::three_way_comparable,std::three_way_comparable_with.3 b/man/std::three_way_comparable,std::three_way_comparable_with.3 new file mode 100644 index 000000000..ad8963a08 --- /dev/null +++ b/man/std::three_way_comparable,std::three_way_comparable_with.3 @@ -0,0 +1,60 @@ +.TH std::three_way_comparable,std::three_way_comparable_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::three_way_comparable,std::three_way_comparable_with \- std::three_way_comparable,std::three_way_comparable_with + +.SH Synopsis + Defined in header + template< class T, class Cat = std::partial_ordering > + + concept three_way_comparable = + __WeaklyEqualityComparableWith && + __PartiallyOrderedWith && \fB(1)\fP \fI(since C++20)\fP + requires(const std::remove_reference_t& a, + const std::remove_reference_t& b) { + { a <=> b } -> __ComparesAs; + + }; + template< class T, class U, class Cat = std::partial_ordering > + + concept three_way_comparable_with = + std::three_way_comparable && + std::three_way_comparable && + __ComparisonCommonTypeWith && + std::three_way_comparable< + std::common_reference_t< + const std::remove_reference_t&, \fB(2)\fP \fI(since C++20)\fP + const std::remove_reference_t&>, Cat> && + __WeaklyEqualityComparableWith && + __PartiallyOrderedWith && + requires(const std::remove_reference_t& t, + const std::remove_reference_t& u) { + { t <=> u } -> __ComparesAs; + { u <=> t } -> __ComparesAs; + + }; + template< class T, class Cat > + (exposition + concept __ComparesAs = \fB(3)\fP only*) + + std::same_as, Cat>; + + 1) The concept std::three_way_comparable specifies that the three way comparison + operator <=> on T yield results consistent with the comparison category implied by + Cat. + 2) The concept std::three_way_comparable_with specifies that the three way + comparison operator <=> on (possibly mixed) T and U operands yield results + consistent with the comparison category implied by Cat. Comparing mixed operands + yields results equivalent to comparing the operands converted to their common type. + + __WeaklyEqualityComparableWith, __PartiallyOrderedWith, and + __ComparisonCommonTypeWith are exposition-only concepts. See descriptions of + equality_comparable and totally_ordered. + +.SH See also + + equality_comparable specifies that operator == is an equivalence relation + equality_comparable_with (concept) + (C++20) + totally_ordered specifies that the comparison operators on the type yield a + totally_ordered_with total order + (C++20) (concept) diff --git a/man/std::throw_with_nested.3 b/man/std::throw_with_nested.3 index 95149249d..97eb65b1d 100644 --- a/man/std::throw_with_nested.3 +++ b/man/std::throw_with_nested.3 @@ -1,19 +1,22 @@ -.TH std::throw_with_nested 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::throw_with_nested 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::throw_with_nested \- std::throw_with_nested + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP [[noreturn]] void throw_with_nested( T&& t ); - Throws an exception of unspecified type that is derived from both - std::nested_exception and from std::remove_reference::type, and constructed from - std::forward(t). The default constructor of the nested_exception parent calls - std::current_exception, capturing the currently handled exception object, if any, in - std::exception_ptr. + If std::decay::type is a non-final non-union class type that is neither + std::nested_exception nor derived from std::nested_exception, throws an exception of + an unspecified type that is publicly derived from both std::nested_exception and + from std::decay::type, and constructed from std::forward(t). The default + constructor of the nested_exception base class calls std::current_exception, + capturing the currently handled exception object, if any, in a std::exception_ptr. - If std::remove_reference::type is already derived from std::nested_exception, - simply throws std::forward(t). + Otherwise, throws std::forward(t). - Requires that std::remove_reference::type is CopyConstructible + Requires that std::decay::type is CopyConstructible. .SH Parameters @@ -25,63 +28,76 @@ .SH Example - - Demonstrates construction and recursion through a nested exception object - + Demonstrates construction and recursion through a nested exception object. + + // Run this code + #include + #include #include #include - #include #include - #include - + // prints the explanatory string of an exception. If the exception is nested, // recurses to print the explanatory of the exception it holds void print_exception(const std::exception& e, int level = 0) { std::cerr << std::string(level, ' ') << "exception: " << e.what() << '\\n'; - try { + try + { std::rethrow_if_nested(e); - } catch(const std::exception& e) { - print_exception(e, level+1); - } catch(...) {} + } + catch (const std::exception& nestedException) + { + print_exception(nestedException, level + 1); + } + catch (...) {} } - + // sample function that catches an exception and wraps it in a nested exception void open_file(const std::string& s) { - try { + try + { std::ifstream file(s); file.exceptions(std::ios_base::failbit); - } catch(...) { - std::throw_with_nested( std::runtime_error("Couldn't open " + s) ); + } + catch (...) + { + std::throw_with_nested(std::runtime_error("Couldn't open " + s)); } } - + // sample function that catches an exception and wraps it in a nested exception void run() { - try { + try + { open_file("nonexistent.file"); - } catch(...) { - std::throw_with_nested( std::runtime_error("run() failed") ); + } + catch (...) + { + std::throw_with_nested(std::runtime_error("run() failed")); } } - + // runs the sample function above and prints the caught exception int main() { - try { + try + { run(); - } catch(const std::exception& e) { + } + catch (const std::exception& e) + { print_exception(e); } } -.SH Output: +.SH Possible output: exception: run() failed exception: Couldn't open nonexistent.file @@ -90,6 +106,6 @@ .SH See also nested_exception a mixin type to capture and store current exceptions - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP rethrow_if_nested throws the exception from a std::nested_exception - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::tie.3 b/man/std::tie.3 index e579dc4ae..1b5bea35b 100644 --- a/man/std::tie.3 +++ b/man/std::tie.3 @@ -1,77 +1,111 @@ -.TH std::tie 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tie 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tie \- std::tie + .SH Synopsis Defined in header - template< class... Types > \fI(since C++11)\fP - tuple tie( Types&... args ); \fI(until C++14)\fP - template< class... Types > \fI(since C++14)\fP - constexpr tuple tie( Types&... args ); + template< class... Types > \fI(since C++11)\fP + std::tuple tie( Types&... args ) noexcept; (constexpr since C++14) Creates a tuple of lvalue references to its arguments or instances of std::ignore. .SH Parameters - args - zero or more lvalue arguments to construct the tuple from + args - zero or more lvalue arguments to construct the tuple from. .SH Return value A std::tuple object containing lvalue references. -.SH Exceptions +.SH Possible implementation + + template + constexpr // since C++14 + std::tuple tie(Args&... args) noexcept + { + return {args...}; + } + +.SH Notes - noexcept specification: - noexcept - + std::tie may be used to unpack a std::pair because std::tuple has a converting + assignment from pairs: + + bool result; + std::tie(std::ignore, result) = set.insert(value); .SH Example - std::tie can be used to introduce lexicographical comparison to a struct or to - unpack a tuple: + 1) std::tie can be used to introduce lexicographical comparison to a struct or to + unpack a tuple; + 2) std::tie can work with structured bindings: + - // Run this code + #include #include - #include #include + #include #include - - struct S { + + struct S + { int n; std::string s; float d; - bool operator<(const S& rhs) const + + friend bool operator<(const S& lhs, const S& rhs) noexcept { - // compares n to rhs.n, - // then s to rhs.s, - // then d to rhs.d - return std::tie(n, s, d) < std::tie(rhs.n, rhs.s, rhs.d); + // compares lhs.n to rhs.n, + // then lhs.s to rhs.s, + // then lhs.d to rhs.d + // in that order, first non-equal result is returned + // or false if all elements are equal + return std::tie(lhs.n, lhs.s, lhs.d) < std::tie(rhs.n, rhs.s, rhs.d); } }; - + int main() { - std::set set_of_s; // S is LessThanComparable - + // Lexicographical comparison demo: + std::set set_of_s; + S value{42, "Test", 3.14}; std::set::iterator iter; - bool inserted; - - // unpacks the return value of insert into iter and inserted - std::tie(iter, inserted) = set_of_s.insert(value); - - if (inserted) - std::cout << "Value was inserted successfully\\n"; - } + bool is_inserted; + + // Unpack a pair: + std::tie(iter, is_inserted) = set_of_s.insert(value); + assert(is_inserted); + -.SH Output: + // std::tie and structured bindings: + auto position = [](int w) { return std::tuple(1 * w, 2 * w); }; + + auto [x, y] = position(1); + assert(x == 1 && y == 2); + std::tie(x, y) = position(2); // reuse x, y with tie + assert(x == 2 && y == 4); + + + // Implicit conversions are permitted: + std::tuple coordinates(6, 9); + std::tie(x, y) = coordinates; + assert(x == 6 && y == 9); + } - Value was inserted successfully +.SH See also - make_tuple creates a tuple object of the type defined by the argument types - \fI(function template)\fP - forward_as_tuple creates a tuple of rvalue references - \fI(function template)\fP - tuple_cat creates a tuple by concatenating any number of tuples - \fI(function template)\fP - ignore placeholder to skip an element when unpacking a tuple using tie - (constant) + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or tuple + elements of the initializer + make_tuple creates a tuple object of the type defined by the + \fI(C++11)\fP argument types + \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP + tuple_cat creates a tuple by concatenating any number of tuples + \fI(C++11)\fP \fI(function template)\fP + ignore placeholder to skip an element when unpacking a tuple + \fI(C++11)\fP using tie + (constant) diff --git a/man/std::time.3 b/man/std::time.3 index bc0cc9b75..057abe625 100644 --- a/man/std::time.3 +++ b/man/std::time.3 @@ -1,55 +1,67 @@ -.TH std::time 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time \- std::time + .SH Synopsis Defined in header - std::time_t time( std::time_t *time ); + std::time_t time( std::time_t* arg ); - Returns the current calendar time encoded as a std::time_t object. + Returns the current calendar time encoded as a std::time_t object, and also stores + it in the object pointed to by arg, unless arg is a null pointer. .SH Parameters - time - pointer to a std::time_t object to store the time in or NULL + arg - pointer to a std::time_t object to store the time, or a null pointer .SH Return value Current calendar time encoded as std::time_t object on success, (std::time_t)(-1) on - error. If the argument is not NULL, the return value is also set to the object - pointed by time. + error. If arg is not null, the return value is also stored in the object pointed to + by arg. .SH Notes The encoding of calendar time in std::time_t is unspecified, but most systems - conform to POSIX specification and return a value of integral type holding the - number of seconds since the Epoch. Implementations in which std::time_t is a 32-bit - signed integer (many historical implementations) fail in the year 2038. + conform to the POSIX specification and return a value of integral type holding 86400 + times the number of calendar days since the Epoch plus the number of seconds that + have passed since the last midnight UTC. Most notably, POSIX time does not (and can + not) take leap seconds into account, so that this integral value is not equal to the + number of S.I. seconds that have passed since the epoch, but rather is reduced with + the number of leap seconds that have occurred since the epoch. Implementations in + which std::time_t is a 32-bit signed integer (many historical implementations) fail + in the year 2038. .SH Example - + // Run this code #include #include - + int main() { - std::time_t result = std::time(NULL); + std::time_t result = std::time(nullptr); std::cout << std::asctime(std::localtime(&result)) << result << " seconds since the Epoch\\n"; } -.SH Output: +.SH Possible output: Wed Sep 21 10:27:52 2011 1316615272 seconds since the Epoch .SH See also + timespec_get returns the calendar time in seconds and nanoseconds based on a given + \fI(C++17)\fP time base + \fI(function)\fP localtime converts time since epoch to calendar time expressed as local time - \fI(function)\fP + \fI(function)\fP converts time since epoch to calendar time expressed as Universal gmtime Coordinated Time - \fI(function)\fP + \fI(function)\fP system_clock wall clock time from the system-wide realtime clock - \fI(C++11)\fP \fI(class)\fP + \fI(C++11)\fP \fI(class)\fP C documentation for time diff --git a/man/std::time_base.3 b/man/std::time_base.3 index 455b96826..7b1bfd6fa 100644 --- a/man/std::time_base.3 +++ b/man/std::time_base.3 @@ -1,4 +1,7 @@ -.TH std::time_base 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_base 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_base \- std::time_base + .SH Synopsis Defined in header class time_base; @@ -15,12 +18,14 @@ no_order Unspecified order dmy Day, month, year (european) order mdy Month, day, year (american) order - ymd Year, month, day + ymd Year, month, day (asian) order ydm Year, day, month .SH See also do_date_order obtains preferred ordering of day, month, and year - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + do_get_date extracts month, day, and year from input stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + diff --git a/man/std::time_get.3 b/man/std::time_get.3 index 525233a73..ae7ce149d 100644 --- a/man/std::time_get.3 +++ b/man/std::time_get.3 @@ -1,4 +1,7 @@ -.TH std::time_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get \- std::time_get + .SH Synopsis Defined in header template< @@ -13,31 +16,27 @@ convert text input to a std::tm object. std-time get-inheritance.svg - About this image Inheritance diagram -.SH Type requirements - - - - InputIt must meet the requirements of InputIterator. + If a std::time_get specialization is not guaranteed to be provided by the standard + library (see below), the behaviors of its member functions (except the constructor + and destructor) are not guaranteed as specified. .SH Specializations - Two standalone (locale-independent) full specializations and two partial - specializations are provided by the standard library: + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header - std::time_get parses narrow string representations of date and - time - std::time_get parses wide string representations of date and time - std::time_get parses narrow string representations of date and - time using custom input iterator - std::time_get parses wide string representations of date and time - using custom input iterator + std::time_get parses narrow string representations of date and time + std::time_get parses wide string representations of date and time - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. + In addition, the standard library is also guaranteed to provide every specialization + that satisfies the following type requirements: + + * CharT is one of char and wchar_t, and + * InputIt must meet the requirements of LegacyInputIterator. .SH Member types @@ -52,19 +51,19 @@ destructor destructs a time_get facet \fI(protected member function)\fP date_order invokes do_date_order - \fI(public member function)\fP + \fI(public member function)\fP get_time invokes do_get_time - \fI(public member function)\fP + \fI(public member function)\fP get_date invokes do_get_date - \fI(public member function)\fP + \fI(public member function)\fP get_weekday invokes do_get_weekday - \fI(public member function)\fP + \fI(public member function)\fP get_monthname invokes do_get_monthname - \fI(public member function)\fP + \fI(public member function)\fP get_year invokes do_get_year - \fI(public member function)\fP + \fI(public member function)\fP get invokes do_get - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Member objects @@ -74,20 +73,20 @@ .SH Protected member functions do_date_order obtains preferred ordering of day, month, and year - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_get_time extracts hours, minutes, and seconds from input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_get_date extracts month, day, and year from input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_get_weekday extracts the name of a day of the week from input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP - do_get_monthname extacts a month name from input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_get_monthname extracts a month name from input stream + \fB[virtual]\fP \fI(virtual protected member function)\fP do_get_year extracts a year from input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_get extracts date/time components from input stream, according to the \fB[virtual]\fP \fI(C++11)\fP specified format - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP Inherited from std::time_base @@ -97,32 +96,37 @@ Inherited from std::time_base .SH Example - + Note: choose clang to observe the output. libstdc++ does not correctly implement + the %b specifier: bug 78714. + + // Run this code + #include #include - #include - #include #include - #include - #include + #include + int main() { - std::wstring input = L"2011-Februar-18 23:12:34"; - std::tm t; - std::wistringstream ss(input); - ss.imbue(std::locale("de_DE")); - ss >> std::get_time(&t, L"%Y-%b-%d %H:%M:%S"); // uses std::time_get - std::cout << std::asctime(&t); + std::tm t = {}; + std::istringstream ss("2011-Februar-18 23:12:34"); + ss.imbue(std::locale("de_DE.utf-8")); + + ss >> std::get_time(&t, "%Y-%b-%d %H:%M:%S"); + if (ss.fail()) + std::cout << "Parse failed\\n"; + else + std::cout << std::put_time(&t, "%c") << '\\n'; } -.SH Output: +.SH Possible output: Sun Feb 18 23:12:34 2011 .SH See also - time_put formats contents of struct std::tm for output as character sequence + time_put formats contents of std::tm for output as character sequence \fI(class template)\fP get_time parses a date/time value of specified format \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::date_order,std::time_get::do_date_order.3 b/man/std::time_get::date_order,std::time_get::do_date_order.3 index 334440c1b..237db60e9 100644 --- a/man/std::time_get::date_order,std::time_get::do_date_order.3 +++ b/man/std::time_get::date_order,std::time_get::do_date_order.3 @@ -1,4 +1,7 @@ -.TH std::time_get::date_order,std::time_get::do_date_order 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::date_order,std::time_get::do_date_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::date_order,std::time_get::do_date_order \- std::time_get::date_order,std::time_get::do_date_order + .SH Synopsis Defined in header public: \fB(1)\fP @@ -27,7 +30,7 @@ .SH Return value - A value of type dateorder + A value of type dateorder. .SH Notes @@ -35,43 +38,55 @@ .SH Example - + The output below was obtained using clang (libc++). + + // Run this code #include #include - + void show_date_order() { std::time_base::dateorder d = std::use_facet>( - std::locale() + std::locale() ).date_order(); switch (d) { - case std::time_base::no_order: std::cout << "no_order\\n"; break; - case std::time_base::dmy: std::cout << "day, month, year\\n"; break; - case std::time_base::mdy: std::cout << "month, day, year\\n"; break; - case std::time_base::ymd: std::cout << "year, month, day\\n"; break; - case std::time_base::ydm: std::cout << "year, day, month\\n"; break; + case std::time_base::no_order: + std::cout << "no_order\\n"; + break; + case std::time_base::dmy: + std::cout << "day, month, year\\n"; + break; + case std::time_base::mdy: + std::cout << "month, day, year\\n"; + break; + case std::time_base::ymd: + std::cout << "year, month, day\\n"; + break; + case std::time_base::ydm: + std::cout << "year, day, month\\n"; + break; } } - + int main() { std::locale::global(std::locale("en_US.utf8")); std::cout << "In U.S. locale, the default date order is: "; show_date_order(); - + std::locale::global(std::locale("ja_JP.utf8")); std::cout << "In Japanese locale, the default date order is: "; show_date_order(); - + std::locale::global(std::locale("de_DE.utf8")); std::cout << "In German locale, the default date order is: "; show_date_order(); } -.SH Output: +.SH Possible output: In U.S. locale, the default date order is: month, day, year In Japanese locale, the default date order is: year, month, day @@ -80,6 +95,6 @@ .SH See also do_get_date extracts month, day, and year from input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP time_base defines date format constants - \fI(class)\fP + \fI(class)\fP diff --git a/man/std::time_get::get,std::time_get::do_get.3 b/man/std::time_get::get,std::time_get::do_get.3 index 8a55dabe0..b8a11dfdb 100644 --- a/man/std::time_get::get,std::time_get::do_get.3 +++ b/man/std::time_get::get,std::time_get::do_get.3 @@ -1,20 +1,23 @@ -.TH std::time_get::get,std::time_get::do_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::get,std::time_get::do_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::get,std::time_get::do_get \- std::time_get::get,std::time_get::do_get + .SH Synopsis Defined in header public: - iter_type get(iter_type beg, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, std::tm* t, \fB(1)\fP \fI(since C++11)\fP + iter_type get( iter_type beg, iter_type end, std::ios_base& str, + std::ios_base::iostate& err, std::tm* t, \fB(1)\fP \fI(since C++11)\fP - const char_type* fmtbeg, const char_type* fmtend) + const char_type* fmtbeg, const char_type* fmtend ) const; protected: - virtual iter_type do_get(iter_type neg, iter_type end, + virtual iter_type do_get( iter_type beg, iter_type end, std::ios_base& str, \fB(2)\fP \fI(since C++11)\fP - std::ios_base::iostate& err, std::tm *t, + std::ios_base::iostate& err, std::tm *t, - char format, char modifier) const; + char format, char modifier ) const; 1) Parses the date and time from the input character sequence [beg, end) according to the format provided in the character sequence [fmtbeg, fmtend). The format is @@ -23,13 +26,13 @@ the following: First, clears the error bits in err by executing err = std::ios_base::goodbit. Then enters a loop, which terminates whenever any of the following conditions becomes true (checked in this order): - a) All characters have been read from the format string (fmtbeg == fmtend) - b) There was a parsing error (err != std::ios_base::goodbit) + a) All characters have been read from the format string (fmtbeg == fmtend). + b) There was a parsing error (err != std::ios_base::goodbit). c) All characters have been read from the input sequence (beg == end. If this - condition terminates the loop, the function sets both eofbit and failbit in err + condition terminates the loop, the function sets both eofbit and failbit in err. In the body of the loop, the following steps take place: - a) if the next character in the format string is '%', followed by one or two + a) If the next character in the format string is '%', followed by one or two characters that form a valid std::get_time conversion specifier (see below), these characters are used in the call do_get(beg, end, str, err, t, format, modifier), where format is the primary conversion specifier character, and modifier is the @@ -74,151 +77,131 @@ errors t - pointer to the std::tm object that will hold the result of this function call - pointer to the first character of a sequence of char_type characters + fmtbeg - pointer to the first character of a sequence of char_type characters + specifying the conversion format (see below) + fmtend - pointer one past the last character of a sequence of char_type characters specifying the conversion format + format - the character that names a conversion specifier + modifier - the optional modifier that may appear between % and the conversion + specifier - The format string consists of zero or more conversion specifiers, - whitespace characters, and ordinary characters (except %). Each ordinary - character is expected to match one character in the input stream in - case-insensitive comparison. Each whitespace character matches arbitrary - whitespace in the input string. Each conversion specification begins with - % character, optionally followed by E or O modifier (ignored if - unsupported by the locale), followed by the character that determines the - behavior of the specifier. The format specifiers match the POSIX function - strptime(): + The format string consists of zero or more conversion specifiers, whitespace + characters, and ordinary characters (except %). Each ordinary character is expected + to match one character in the input stream in case-insensitive comparison. Each + whitespace character matches arbitrary whitespace in the input string. Each + conversion specification begins with % character, optionally followed by E or O + modifier (ignored if unsupported by the locale), followed by the character that + determines the behavior of the specifier. The format specifiers match the POSIX + function strptime(): - Conversion Explanation Writes to fields - specifier - % matches a literal %. The full conversion \fI(none)\fP - specification must be %%. - t matches any whitespace. \fI(none)\fP - n matches any whitespace. \fI(none)\fP - Year - parses full year as a 4 digit decimal - Y number, leading zeroes permitted but not tm_year - required - parses year in the alternative - EY representation, e.g.平成23年 (year Heisei tm_year - 23) which writes 2011 to tm_year in ja_JP - locale - parses last 2 digits of year as a decimal - y number. Range [69,99] results in values 1969 tm_year - to 1999, range [00,68] results in 2000-2068 - parses last 2 digits of year using the - Oy alternative numeric system, e.g. 十一 is tm_year - parsed as 11 in ja_JP locale - Ey parses year as offset from locale's tm_year - alternative calendar period %EC - C parses the first 2 digits of year as a tm_year - decimal number (range [00,99]) - parses the name of the base year (period) in - EC the locale's alternative representation, tm_year - e.g. 平成 (Heisei era) in ja_JP - Month - b parses the month name, either full or tm_mon - abbreviated, e.g. Oct - h synonym of b tm_mon - B synonym of b tm_mon - parses the month as a decimal number (range - m [01,12]), leading zeroes permitted but not tm_mon - required - parses the month using the alternative - Om numeric system, e.g. 十二 parses as 12 in tm_mon - ja_JP locale - Week - parses the week of the year as a decimal - U number (Sunday is the first day of the week) tm_year, tm_wday, - (range [00,53]), leading zeroes permitted tm_yday - but not required - parses the week of the year, as by %U, using tm_year, tm_wday, - OU the alternative numeric system, e.g. 五十二 tm_yday - parses as 52 in ja_JP locale - parses the week of the year as a decimal - W number (Monday is the first day of the week) tm_year, tm_wday, - (range [00,53]), leading zeroes permitted tm_yday - but not required - parses the week of the year, as by %W, using tm_year, tm_wday, - OW the alternative numeric system, e.g. 五十二 tm_yday - parses as 52 in ja_JP locale - Day of the year/month - parses day of the year as a decimal number - j (range [001,366]), leading zeroes permitted tm_yday - fmtbeg - but not required - parses the day of the month as a decimal - d number (range [01,31]), leading zeroes tm_mday - permitted but not required - parses the day of the month using the - Od alternative numeric system, e.g 二十七 tm_mday - parses as 23 in ja_JP locale, leading zeroes - permitted but not required - e synonym of d tm_mday - Oe synonym of Od tm_mday - Day of the week - a parses the name of the day of the week, tm_wday - either full or abbreviated, e.g. Fri - A synonym of a tm_wday - w parses weekday as a decimal number, where tm_wday - Sunday is 0 (range [0-6]) - parses weekday as a decimal number, where - Ow Sunday is 0, using the alternative numeric tm_wday - system, e.g. 二 parses as 2 in ja_JP locale - Hour, minute, second - parses the hour as a decimal number, 24 hour - H clock (range [00-23]), leading zeroes tm_hour - permitted but not required - parses hour from 24-hour clock using the - OH alternative numeric system, e.g. 十八 parses tm_hour - as 18 in ja_JP locale - parses hour as a decimal number, 12 hour - I clock (range [01,12]), leading zeroes tm_hour - permitted but not required - parses hour from 12-hour clock using the - OI alternative numeric system, e.g. 六 reads as tm_hour - 06 in ja_JP locale - parses minute as a decimal number (range - M [00,59]), leading zeroes permitted but not tm_min - required - parses minute using the alternative numeric - OM system, e.g. 二十五 parses as 25 in ja_JP tm_min - locale - parses second as a decimal number (range - S [00,60]), leading zeroes permitted but not tm_sec - required - parses second using the alternative numeric - OS system, e.g. 二十四 parses as 24 in ja_JP tm_sec - locale + Conversion Explanation Writes to fields + specifier + % matches a literal %. The full conversion specification \fI(none)\fP + must be %% + t matches any whitespace \fI(none)\fP + n matches any whitespace \fI(none)\fP + Year + Y parses full year as a 4 digit decimal number, leading tm_year + zeroes permitted but not required + parses year in the alternative representation, e.g.平 + EY 成23年 (year Heisei 23) which writes 2011 to tm_year in tm_year + ja_JP locale + parses last 2 digits of year as a decimal number. Range + y [69,99] results in values 1969 to 1999, range [00,68] tm_year + results in 2000-2068 + parses last 2 digits of year using the alternative + Oy numeric system, e.g. 十一 is parsed as 11 in ja_JP tm_year + locale + Ey parses year as offset from locale's alternative tm_year + calendar period %EC + C parses the first 2 digits of year as a decimal number tm_year + (range [00,99]) + parses the name of the base year (period) in the + EC locale's alternative representation, e.g. 平成 (Heisei tm_year + era) in ja_JP + Month + b parses the month name, either full or abbreviated, e.g. tm_mon + Oct + h synonym of b tm_mon + B synonym of b tm_mon + m parses the month as a decimal number (range [01,12]), tm_mon + leading zeroes permitted but not required + Om parses the month using the alternative numeric system, tm_mon + e.g. 十二 parses as 12 in ja_JP locale + Week + parses the week of the year as a decimal number (Sunday tm_year, tm_wday, + U is the first day of the week) (range [00,53]), leading tm_yday + zeroes permitted but not required + parses the week of the year, as by %U, using the tm_year, tm_wday, + OU alternative numeric system, e.g. 五十二 parses as 52 in tm_yday + ja_JP locale + parses the week of the year as a decimal number (Monday tm_year, tm_wday, + W is the first day of the week) (range [00,53]), leading tm_yday + zeroes permitted but not required + parses the week of the year, as by %W, using the tm_year, tm_wday, + OW alternative numeric system, e.g. 五十二 parses as 52 in tm_yday + ja_JP locale + Day of the year/month + j parses day of the year as a decimal number (range tm_yday + [001,366]), leading zeroes permitted but not required + d parses the day of the month as a decimal number (range tm_mday + [01,31]), leading zeroes permitted but not required + parses the day of the month using the alternative + Od numeric system, e.g. 二十七 parses as 27 in ja_JP tm_mday + locale, leading zeroes permitted but not required + e synonym of d tm_mday + Oe synonym of Od tm_mday + Day of the week + a parses the name of the day of the week, either full or tm_wday + abbreviated, e.g. Fri + A synonym of a tm_wday + w parses weekday as a decimal number, where Sunday is 0 tm_wday + (range [0-6]) + parses weekday as a decimal number, where Sunday is 0, + Ow using the alternative numeric system, e.g. 二 parses as tm_wday + 2 in ja_JP locale + Hour, minute, second + parses the hour as a decimal number, 24 hour clock + H (range [00-23]), leading zeroes permitted but not tm_hour + required + OH parses hour from 24-hour clock using the alternative tm_hour + numeric system, e.g. 十八 parses as 18 in ja_JP locale + I parses hour as a decimal number, 12 hour clock (range tm_hour + [01,12]), leading zeroes permitted but not required + OI parses hour from 12-hour clock using the alternative tm_hour + numeric system, e.g. 六 reads as 06 in ja_JP locale + M parses minute as a decimal number (range [00,59]), tm_min + leading zeroes permitted but not required + OM parses minute using the alternative numeric system, tm_min + e.g. 二十五 parses as 25 in ja_JP locale + S parses second as a decimal number (range [00,60]), tm_sec + leading zeroes permitted but not required + OS parses second using the alternative numeric system, tm_sec + e.g. 二十四 parses as 24 in ja_JP locale .SH Other - parses the locale's standard date and time - c string format, e.g. Sun Oct 17 04:41:13 2010 all - (locale dependent) - parses the locale's alternative date and - Ec time string format, e.g. expecting 平成23年 all - (year Heisei 23) instead of 2011年 (year - 2011) in ja_JP locale - x parses the locale's standard date all - representation - parses the locale's alternative date - Ex representation, e.g. expecting 平成23年 all - (year Heisei 23) instead of 2011年 (year - 2011) in ja_JP locale - X parses the locale's standard time all - representation - EX parses the locale's alternative time all - representation - D equivalent to "%m / %d / %y " tm_mon, tm_mday, + parses the locale's standard date and time string + c format, e.g. Sun Oct 17 04:41:13 2010 (locale all + dependent) + parses the locale's alternative date and time string + Ec format, e.g. expecting 平成23年 (year Heisei 23) all + instead of 2011年 (year 2011) in ja_JP locale + x parses the locale's standard date representation all + parses the locale's alternative date representation, + Ex e.g. expecting 平成23年 (year Heisei 23) instead of all + 2011年 (year 2011) in ja_JP locale + X parses the locale's standard time representation all + EX parses the locale's alternative time representation all + D equivalent to "%m / %d / %y " tm_mon, tm_mday, tm_year - r parses locale's standard 12-hour clock time tm_hour, tm_min, - (in POSIX, "%I : %M : %S %p") tm_sec - R equivalent to "%H : %M" tm_hour, tm_min - T equivalent to "%H : %M : %S" tm_hour, tm_min, + r parses locale's standard 12-hour clock time (in POSIX, tm_hour, tm_min, + "%I : %M : %S %p") tm_sec + R equivalent to "%H : %M" tm_hour, tm_min + T equivalent to "%H : %M : %S" tm_hour, tm_min, tm_sec - p parses the locale's equivalent of a.m. or tm_hour - p.m. - fmtend - pointer one past the last character of a sequence of char_type characters - specifying the conversion format - format - the character that names a conversion specifier - modifier - the optional modifier that may appear between % and the conversion - specifier + p parses the locale's equivalent of a.m. or p.m. tm_hour + + Note: tm_isdst is not written to, and needs to be set explicitly for use with + functions such as mktime .SH Return value @@ -240,50 +223,52 @@ .SH Example - + // Run this code + #include #include - #include #include - #include - + #include + int main() { - std::istringstream ss("2011-Februar-18 23:12:34"); - ss.imbue(std::locale("de_DE")); - - auto& f = std::use_facet>(std::locale("de_DE")); + std::istringstream ss("2026-März-12 23:45:56"); + ss.imbue(std::locale("de_DE.utf8")); + + auto& f = std::use_facet>(ss.getloc()); std::tm t{}; std::string s = "%Y-%b-%d %H:%M:%S"; std::ios_base::iostate err = std::ios_base::goodbit; - std::istreambuf_iterator ret = f.get(std::istreambuf_iterator(ss), - std::istreambuf_iterator(), - ss, err, &t, &s[0], &s[0] + s.size()); + auto ret = f.get({ss}, {}, ss, err, &t, &s[0], &s[0] + s.size()); ss.setstate(err); - - if(ss) { - std::cout << "Successfully parsed as " << std::put_time(&t, "%c"); - if(ret != std::istreambuf_iterator()) { - std::cout << " Remaining content: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); - } else { - std::cout << " The input was fully consumed"; + std::istreambuf_iterator last{}; + + if (ss) + { + std::cout << "Successfully parsed as " << std::put_time(&t, "%c") << '\\n'; + if (ret != last) + { + std::cout << "Remaining content: "; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); } - } else { - std::cout << "Parse failed. Unparsed string: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); + else + std::cout << "The input was fully consumed."; + } + else + { + std::cout << "Parse failed.\\nUnparsed string: "; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); } std::cout << '\\n'; } .SH Output: - Successfully parsed, as Sun Feb 18 23:12:34 2011 The input was fully consumed + Successfully parsed as Sun Mar 12 23:45:56 2026 + The input was fully consumed. .SH See also get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::get_date,std::time_get::do_get_date.3 b/man/std::time_get::get_date,std::time_get::do_get_date.3 index 0b21c2003..8539c9da2 100644 --- a/man/std::time_get::get_date,std::time_get::do_get_date.3 +++ b/man/std::time_get::get_date,std::time_get::do_get_date.3 @@ -1,4 +1,7 @@ -.TH std::time_get::get_date,std::time_get::do_get_date 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::get_date,std::time_get::do_get_date 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::get_date,std::time_get::do_get_date \- std::time_get::get_date,std::time_get::do_get_date + .SH Synopsis Defined in header public: @@ -13,17 +16,20 @@ std::ios_base::iostate& err, std::tm* t ) const; - 1) Public member function, calls the protected virtual member function do_get_date() + 1) Public member function, calls the protected virtual member function do_get_date of the most derived class. 2) Reads successive characters from the sequence [beg, end) and parses out the - calendar date value using the default format expected by this locale, which is the - same format as + calendar date value using the default format expected by this locale, which is + determined as - "%x" \fI(until C++11)\fP - "%d/%m/%y", "%m/%d/%y", "%y/%m/%d", and "%y/%d/%m", depending on \fI(since C++11)\fP - date_order() + date_order() Format + no_order "%m/%d/%y" + dmy "%d/%m/%y" + mdy "%m/%d/%y" + ymd "%y/%m/%d" + ydm "%y/%d/%m" - as used by the functions std::get_time(), get(), and the POSIX function strptime() + as used by the functions std::get_time(), get(), and the POSIX function strptime(). The parsed date is stored in the corresponding fields of the std::tm structure pointed to by the argument t. If the end iterator is reached before a valid date is read, the function sets @@ -57,38 +63,37 @@ .SH Example - + // Run this code + #include #include + #include #include #include - #include - #include - + void try_get_date(const std::string& s) { - std::cout << "Parsing the date out of '" << s << - "' in the locale " << std::locale().name() << '\\n'; + std::cout << "Parsing the date out of '" << s + << "' in the locale " << std::locale().name() << '\\n'; std::istringstream str(s); std::ios_base::iostate err = std::ios_base::goodbit; - + std::tm t; - std::istreambuf_iterator ret = - std::use_facet>(str.getloc()).get_date( - std::istreambuf_iterator(str), - std::istreambuf_iterator(), - str, err, &t - ); + const std::time_get& facet = std::use_facet>(str.getloc()); + std::istreambuf_iterator ret = facet.get_date({str}, {}, str, err, &t); str.setstate(err); - if(str) { - std::cout << "Day: " << t.tm_mday << ' ' + + if (str) + { + std::cout << "Day: " << t.tm_mday << ' ' << "Month: " << t.tm_mon + 1 << ' ' - << "Year: " << t.tm_year + 1900 << '\\n'; - } else { + << "Year: " << t.tm_year + 1900 << '\\n'; + } + else + { std::cout << "Parse failed. Unparsed string: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); + std::copy(ret, {}, std::ostreambuf_iterator(std::cout)); std::cout << '\\n'; } } @@ -97,7 +102,7 @@ std::locale::global(std::locale("en_US.utf8")); try_get_date("02/01/2013"); try_get_date("02-01-2013"); - + std::locale::global(std::locale("ja_JP.utf8")); try_get_date("2013年02月01日"); } @@ -111,7 +116,18 @@ Parsing the date out of '2013年02月01日' in the locale ja_JP.utf8 Day: 1 Month: 2 Year: 2013 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 248 C++98 eofbit was not set upon reaching the sets eofbit if a valid date + end iterator has not been read + LWG 461 C++98 do_get_date needed to parse localized parses with the format + date representation determined by date_order() + .SH See also get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::get_monthname,.3 b/man/std::time_get::get_monthname,.3 new file mode 100644 index 000000000..8b782533f --- /dev/null +++ b/man/std::time_get::get_monthname,.3 @@ -0,0 +1,151 @@ +.TH std::time_get::get_monthname, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::get_monthname, \- std::time_get::get_monthname, + +.SH Synopsis + + Defined in header + public: + + iter_type get_monthname( iter_type beg, iter_type end, std::ios_base& str, \fB(1)\fP + + std::ios_base::iostate& err, std::tm* t ) const; + protected: + + virtual iter_type do_get_monthname( iter_type beg, iter_type end, + std::ios_base& str, \fB(2)\fP + + std::ios_base::iostate& err, std::tm* t ) + const; + + 1) Public member function, calls the protected virtual member function + do_get_monthname of the most derived class. + 2) Reads successive characters from the sequence [beg, end) and parses out the month + name (possibly abbreviated), using the default format for month names expected by + this locale, which is the same format as "%b" as used by the functions + std::get_time, time_get::get, and the POSIX function strptime(). + + If it finds abbreviated name, followed by the characters that are valid for the full + name, it continues reading until it consumes all the characters for the full name or + finds a character that isn't expected, in which case parsing fails even if the first + few characters were a valid abbreviation. + + The parsed month is stored in the std::tm field t->tm_mon. + + If the end iterator is reached before a valid month name is read, the function sets + std::ios_base::eofbit in err. If a parsing error is encountered, the function sets + std::ios_base::failbit in err. + +.SH Parameters + + beg - iterator designating the start of the sequence to parse + end - one past the end iterator for the sequence to parse + str - a stream object that this function uses to obtain locale facets when needed, + e.g. std::ctype to skip whitespace or std::collate to compare strings + err - stream error flags object that is modified by this function to indicate errors + t - pointer to the std::tm object that will hold the result of this function call + +.SH Return value + + Iterator pointing one past the last character in [beg, end) that was recognized as a + part of a valid month name. + +.SH Notes + + This function is usually case-insensitive. + + If a parsing error is encountered, most implementations of this function leave *t + unmodified. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + void try_get_mon(std::string_view locale_name, std::string_view source) + { + try + { + std::locale::global(std::locale(locale_name.data())); + } + catch (std::runtime_error const& ex) + { + std::cout << "Cannot setup locale: " << locale_name << "\\n" + "Exception: " << ex.what() << '\\n'; + return; + } + + std::cout << "Parsing the month out of '" << source + << "' in the locale " << std::locale().name() << '\\n'; + std::istringstream str{source.data()}; + std::ios_base::iostate err = std::ios_base::goodbit; + + std::tm t; + std::time_get const& facet = std::use_facet>(str.getloc()); + std::istreambuf_iterator ret = facet.get_monthname({str}, {}, str, err, &t); + str.setstate(err); + std::istreambuf_iterator last{}; + + if (str) + { + std::cout << "Successfully parsed, month number is " << t.tm_mon; + + if (ret != last) + { + std::cout << ". Remaining content: "; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); + } + else + std::cout << ". The input was fully consumed"; + } + else + { + std::cout << "Parse failed. Unparsed string: "; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); + } + + std::cout << '\\n'; + } + + int main() + { + try_get_mon("ja_JP.utf8", "2月"); + try_get_mon("th_TH.utf8", "กมภาพนธ"); + try_get_mon("el_GR.utf8", "Φεβ"); + try_get_mon("el_GR.utf8", "Φεβρουάριος"); + try_get_mon("en_US.utf8", "Febrile"); + } + +.SH Possible output: + + Parsing the month out of '2月' in the locale ja_JP.utf8 + Successfully parsed, month number is 1. The input was fully consumed + Parsing the month out of 'กมภาพนธ' in the locale th_TH.utf8 + Successfully parsed, month number is 1. The input was fully consumed + Parsing the month out of 'Φεβ' in the locale el_GR.utf8 + Successfully parsed, month number is 1. The input was fully consumed + Parsing the month out of 'Φεβρουάριος' in the locale el_GR.utf8 + Successfully parsed, month number is 1. The input was fully consumed + Parsing the month out of 'Febrile' in the locale en_US.utf8 + Parse failed. Unparsed string: ile + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 248 C++98 eofbit was not set upon reaching sets eofbit if a valid month + the end iterator name has not been read + +.SH See also + + get_time parses a date/time value of specified format + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::get_monthname,std::time_get::do_get_monthname.3 b/man/std::time_get::get_monthname,std::time_get::do_get_monthname.3 deleted file mode 100644 index 07cc58017..000000000 --- a/man/std::time_get::get_monthname,std::time_get::do_get_monthname.3 +++ /dev/null @@ -1,127 +0,0 @@ -.TH std::time_get::get_monthname,std::time_get::do_get_monthname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - public: - - iter_type get_monthname( iter_type beg, iter_type end, std::ios_base& str, \fB(1)\fP - - std::ios_base::iostate& err, std::tm* t) const; - protected: - - virtual iter_type do_get_monthname( iter_type beg, iter_type end, - std::ios_base& str, \fB(2)\fP - - std::ios_base::iostate& err, std::tm* t) - const; - - 1) public member function, calls the protected virtual member function - do_get_monthname of the most derived class. - 2) Reads successive characters from the sequence [beg, end) and parses out the month - name (possibly abbreviated), using the default format for month names expected by - this locale, which is the same format as "%b" as used by the functions - std::get_time, time_get::get, and the POSIX function strptime() - - If it finds abbreviated name, followed by the characters that are valid for the full - name, it continues reading until it consumes all the characters for the full name or - finds a character that isn't expected, in which case parsing fails even if the first - few characters were a valid abbreviation. - - The parsed month is stored in the std::tm field t->tm_mon. - - If the end iterator is reached before a valid month name is read, the function sets - std::ios_base::eofbit in err. If a parsing error is encountered, the function sets - std::ios_base::failbit in err. - -.SH Parameters - - beg - iterator designating the start of the sequence to parse - end - one past the end iterator for the sequence to parse - str - a stream object that this function uses to obtain locale facets when needed, - e.g. std::ctype to skip whitespace or std::collate to compare strings - err - stream error flags object that is modified by this function to indicate errors - t - pointer to the std::tm object that will hold the result of this function call - -.SH Return value - - Iterator pointing one past the last character in [beg, end) that was recognized as a - part of a valid month name. - -.SH Notes - - This function is usually case-insensitive. - - If a parsing error is encountered, most implementations of this function leave *t - unmodified. - -.SH Example - - -// Run this code - - #include - #include - #include - #include - #include - - void try_get_mon(const std::string& s) - { - std::cout << "Parsing the month out of '" << s << - "' in the locale " << std::locale().name() << '\\n'; - std::istringstream str(s); - std::ios_base::iostate err = std::ios_base::goodbit; - - std::tm t; - std::istreambuf_iterator ret = - std::use_facet>(str.getloc()).get_monthname( - std::istreambuf_iterator(str), - std::istreambuf_iterator(), - str, err, &t - ); - str.setstate(err); - if(str) { - std::cout << "Successfully parsed, month number is " << t.tm_mon; - if(ret != std::istreambuf_iterator()) { - std::cout << ". Remaining content: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); - } else { - std::cout << ". The input was fully consumed"; - } - } else { - std::cout << "Parse failed. Unparsed string: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); - } - std::cout << '\\n'; - } - int main() - { - std::locale::global(std::locale("ja_JP.utf8")); - try_get_mon("2月"); - std::locale::global(std::locale("th_TH.utf8")); - try_get_mon("กุมภาพันธ์"); - std::locale::global(std::locale("el_GR.utf8")); - try_get_mon("Φεβ"); - try_get_mon("Φεβρουάριος"); - std::locale::global(std::locale("en_US.utf8")); - try_get_mon("Febrile"); - } - -.SH Output: - - Parsing the month out of '2月' in the locale ja_JP.utf8 - Successfully parsed, month number is 1. The input was fully consumed - Parsing the month out of 'กุมภาพันธ์' in the locale th_TH.utf8 - Successfully parsed, month number is 1. The input was fully consumed - Parsing the month out of 'Φεβ' in the locale el_GR.utf8 - Successfully parsed, month number is 1. The input was fully consumed - Parsing the month out of 'Φεβρουάριος' in the locale el_GR.utf8 - Successfully parsed, month number is 1. The input was fully consumed - Parsing the month out of 'Febrile' in the locale en_US.utf8 - Parse failed. Unparsed string: ile - -.SH See also - - get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::get_time,std::time_get::do_get_time.3 b/man/std::time_get::get_time,std::time_get::do_get_time.3 index 221a7fef1..0de56a1b1 100644 --- a/man/std::time_get::get_time,std::time_get::do_get_time.3 +++ b/man/std::time_get::get_time,std::time_get::do_get_time.3 @@ -1,30 +1,31 @@ -.TH std::time_get::get_time,std::time_get::do_get_time 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::get_time,std::time_get::do_get_time 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::get_time,std::time_get::do_get_time \- std::time_get::get_time,std::time_get::do_get_time + .SH Synopsis Defined in header public: - iter_type get_time( iter_type beg, iter_type end, std::ios_base& str, \fB(1)\fP + iter_type get_time( iter_type beg, iter_type end, std::ios_base& str, \fB(1)\fP - std::ios_base::iostate& err, std::tm* t) const; + std::ios_base::iostate& err, std::tm* t ) const; protected: - virtual iter_type get_time( iter_type beg, iter_type end, std::ios_base& str, \fB(2)\fP + virtual iter_type do_get_time( iter_type beg, iter_type end, std::ios_base& \fB(2)\fP + str, - std::ios_base::iostate& err, std::tm* t) const; + std::ios_base::iostate& err, std::tm* t ) const; - 1) public member function, calls the protected virtual member function do_get_time + 1) Public member function, calls the protected virtual member function do_get_time of the most derived class. 2) Reads successive characters from the sequence [beg, end) and parses out the time - value following the same rules as the format specifier - - '%X' \fI(until C++11)\fP - "%H:%M:%S" \fI(since C++11)\fP + value following the same rules as the format specifier "%H:%M:%S" as used by the + functions std::get_time, time_get::get, and the POSIX function strptime(). - as used by the functions std::get_time, time_get::get, and the POSIX function - strptime() The parsed time is stored in the corresponding fields of the std::tm structure pointed to by the argument t. - If the end iterator is reached before a valid value is read, the function sets + + If the end iterator is reached before a valid time is read, the function sets std::ios_base::eofbit in err. If a parsing error is encountered, the function sets std::ios_base::failbit in err. @@ -52,46 +53,48 @@ .SH Example - + // Run this code #include + #include #include #include - #include - + void try_get_time(const std::string& s) { - std::cout << "Parsing the time out of '" << s << - "' in the locale " << std::locale().name() << '\\n'; + std::cout << "Parsing the time out of '" << s + << "' in the locale " << std::locale().name() << '\\n'; std::istringstream str(s); std::ios_base::iostate err = std::ios_base::goodbit; - + std::tm t; + std::time_get const& facet = + std::use_facet>(str.getloc()); std::istreambuf_iterator ret = - std::use_facet>(str.getloc()).get_time( - std::istreambuf_iterator(str), - std::istreambuf_iterator(), - str, err, &t - ); + facet.get_time({str}, {}, str, err, &t); str.setstate(err); - if(str) { - std::cout << "Hours: " << t.tm_hour << ' ' - << "Minutes: " << t.tm_min << ' ' - << "Seconds: " << t.tm_sec << '\\n'; - } else { + + if (str) + { + std::cout << "Hours: " << t.tm_hour << ", " + "Minutes: " << t.tm_min << ", " + "Seconds: " << t.tm_sec << '\\n'; + } + else + { std::cout << "Parse failed. Unparsed string: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); + std::copy(ret, {}, std::ostreambuf_iterator(std::cout)); std::cout << '\\n'; } } + int main() { std::locale::global(std::locale("ru_RU.utf8")); try_get_time("21:40:11"); try_get_time("21-40-11"); - + std::locale::global(std::locale("ja_JP.utf8")); try_get_time("21時37分58秒"); } @@ -99,13 +102,24 @@ .SH Output: Parsing the time out of '21:40:11' in the locale ru_RU.utf8 - Hours: 21 Minutes: 40 Seconds: 11 + Hours: 21, Minutes: 40, Seconds: 11 Parsing the time out of '21-40-11' in the locale ru_RU.utf8 Parse failed. Unparsed string: -40-11 Parsing the time out of '21時37分58秒' in the locale ja_JP.utf8 - Hours: 21 Minutes: 37 Seconds: 58 + Hours: 21, Minutes: 37, Seconds: 58 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 248 C++98 eofbit was not set upon reaching the sets eofbit if a valid time + end iterator has not been read + LWG 461 C++98 do_get_time needed to parse localized parses with "%H:%M:%S" + time representation format .SH See also get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::get_weekday,std::time_get::do_get_weekday.3 b/man/std::time_get::get_weekday,std::time_get::do_get_weekday.3 index 5fa6ab7c2..47dba618f 100644 --- a/man/std::time_get::get_weekday,std::time_get::do_get_weekday.3 +++ b/man/std::time_get::get_weekday,std::time_get::do_get_weekday.3 @@ -1,30 +1,33 @@ -.TH std::time_get::get_weekday,std::time_get::do_get_weekday 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::get_weekday,std::time_get::do_get_weekday 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::get_weekday,std::time_get::do_get_weekday \- std::time_get::get_weekday,std::time_get::do_get_weekday + .SH Synopsis Defined in header public: iter_type get_weekday( iter_type beg, iter_type end, std::ios_base& str, \fB(1)\fP - std::ios_base::iostate& err, std::tm* t) const; + std::ios_base::iostate& err, std::tm* t ) const; protected: virtual iter_type do_get_weekday( iter_type beg, iter_type end, std::ios_base& str, \fB(2)\fP - std::ios_base::iostate& err, std::tm* t) + std::ios_base::iostate& err, std::tm* t ) const; - 1) public member function, calls the protected virtual member function + 1) Public member function, calls the protected virtual member function do_get_weekday of the most derived class. 2) Reads successive characters from the sequence [beg, end) and parses out the weekday name (possibly abbreviated), using the default format for weekdays expected by this locale, which is the same format as "%a" as used by the functions - std::get_time, time_get::get, and the POSIX function strptime() + std::get_time, time_get::get, and the POSIX function strptime(). If it finds abbreviated name, followed by the characters that are valid for the full name, it continues reading until it consumes all the characters for the full name or - finds a character that isn't expected, in which case parsing fails even if the first - few characters were a valid abbreviation. + finds a character that is not expected, in which case parsing fails even if the + first few characters were a valid abbreviation. The parsed weekday is stored in the std::tm field t->tm_wday. @@ -44,7 +47,7 @@ .SH Return value Iterator pointing one past the last character in [beg, end) that was recognized as a - part of a valid weekname. + part of a valid weekday name. .SH Notes @@ -55,59 +58,75 @@ .SH Example - + // Run this code + #include #include + #include #include #include - #include - - void try_get_wday(const std::string& s) + #include + + void try_get_wday(std::string_view s) { - std::cout << "Parsing the weekday out of '" << s << - "' in the locale " << std::locale().name() << '\\n'; - std::istringstream str(s); - std::ios_base::iostate err = std::ios_base::goodbit; - + std::cout << "Parsing the weekday out of '" << s + << "' in the locale " << std::locale().name() << '\\n'; + std::istringstream str{s.data()}; + std::ios_base::iostate err{std::ios_base::goodbit}; + std::tm t; - std::istreambuf_iterator ret = - std::use_facet>(str.getloc()).get_weekday( - std::istreambuf_iterator(str), - std::istreambuf_iterator(), - str, err, &t - ); + std::time_get const& facet = std::use_facet>(str.getloc()); + std::istreambuf_iterator ret = facet.get_weekday({str}, {}, str, err, &t); str.setstate(err); - if(str) { + std::istreambuf_iterator last{}; + + if (str) + { std::cout << "Successfully parsed, weekday number is " << t.tm_wday; - if(ret != std::istreambuf_iterator()) { + + if (ret != last) + { std::cout << " Remaining content: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); - } else { - std::cout << " the input was fully consumed"; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); } - } else { + else + std::cout << " the input was fully consumed"; + } + else + { std::cout << "Parse failed. Unparsed string: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); } + std::cout << '\\n'; } + + void demo(std::string_view locale_name, std::initializer_list&& data) + { + try + { + std::locale::global(std::locale(locale_name.data())); + } + catch (std::runtime_error const& ex) + { + std::cout << "Cannot setup locale: " << locale_name << "\\n" + "Exception: " << ex.what() << '\\n'; + return; + } + + for (std::string_view const weekday : data) + try_get_wday(weekday); + } + int main() { - std::locale::global(std::locale("lt_LT.utf8")); - try_get_wday("Št"); - try_get_wday("Šeštadienis"); - - std::locale::global(std::locale("en_US.utf8")); - try_get_wday("SATELLITE"); - - std::locale::global(std::locale("ja_JP.utf8")); - try_get_wday("土曜日"); + demo("lt_LT.utf8", {"Št", "Šeštadienis"}); + demo("en_US.utf8", {"SATELLITE"}); + demo("ja_JP.utf8", {"土曜日"}); } -.SH Output: +.SH Possible output: Parsing the weekday out of 'Št' in the locale lt_LT.utf8 Successfully parsed, weekday number is 6 the input was fully consumed @@ -118,7 +137,16 @@ Parsing the weekday out of '土曜日' in the locale ja_JP.utf8 Successfully parsed, weekday number is 6 the input was fully consumed + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 248 C++98 eofbit was not set upon reaching sets eofbit if a valid weekday + the end iterator name has not been read + .SH See also get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::get_year,std::time_get::do_get_year.3 b/man/std::time_get::get_year,std::time_get::do_get_year.3 index 4faf2f1e6..aa292a4ed 100644 --- a/man/std::time_get::get_year,std::time_get::do_get_year.3 +++ b/man/std::time_get::get_year,std::time_get::do_get_year.3 @@ -1,18 +1,21 @@ -.TH std::time_get::get_year,std::time_get::do_get_year 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::get_year,std::time_get::do_get_year 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::get_year,std::time_get::do_get_year \- std::time_get::get_year,std::time_get::do_get_year + .SH Synopsis Defined in header public: - iter_type do_get_year( iter_type s, iter_type end, std::ios_base& str, \fB(1)\fP + iter_type get_year( iter_type s, iter_type end, std::ios_base& str, \fB(1)\fP - std::ios_base::iostate& err, std::tm* t) const; + std::ios_base::iostate& err, std::tm* t ) const; protected: - virtual iter_type do_get_year( iter_type s, iter_type end, std::ios_base& str, \fB(2)\fP + virtual iter_type do_get_year( iter_type s, iter_type end, std::ios_base& str, \fB(2)\fP - std::ios_base::iostate& err, std::tm* t) const; + std::ios_base::iostate& err, std::tm* t ) const; - 1) public member function, calls the protected virtual member function do_get_year + 1) Public member function, calls the protected virtual member function do_get_year of the most derived class. 2) Reads successive characters from the sequence [beg, end) and parses out the year using some implementation-defined format. Depending on the locale, two-digit years @@ -20,7 +23,7 @@ The parsed year is stored in the std::tm structure field t->tm_year. - If the end iterator is reached before a valid date is read, the function sets + If the end iterator is reached before a valid year is read, the function sets std::ios_base::eofbit in err. If a parsing error is encountered, the function sets std::ios_base::failbit in err. @@ -43,7 +46,7 @@ For two-digit input values, many implementations use the same parsing rules as the conversion specifier '%y' as used by std::get_time, std::time_get::get(), and the POSIX function strptime(): two-digit integer is expected, the values in the range - [69,99] results in values 1969 to 1999, range [00,68] results in 2000-2068. + [69, 99] results in values 1969 to 1999, range [00, 68] results in 2000 to 2068. Four-digit inputs are typically accepted as-is. If a parsing error is encountered, most implementations of this function leave *t @@ -51,52 +54,54 @@ .SH Example - + // Run this code #include + #include #include #include - #include - + void try_get_year(const std::string& s) { - std::cout << "Parsing the year out of '" << s << - "' in the locale " << std::locale().name() << '\\n'; + std::cout << "Parsing the year out of '" << s + << "' in the locale " << std::locale().name() << '\\n'; std::istringstream str(s); std::ios_base::iostate err = std::ios_base::goodbit; - + std::tm t; - std::istreambuf_iterator ret = - std::use_facet>(str.getloc()).get_year( - std::istreambuf_iterator(str), - std::istreambuf_iterator(), - str, err, &t - ); + std::time_get const& facet = std::use_facet>(str.getloc()); + std::istreambuf_iterator ret = facet.get_year({str}, {}, str, err, &t); str.setstate(err); - if (str) { + std::istreambuf_iterator last{}; + + if (str) + { std::cout << "Successfully parsed, year is " << 1900 + t.tm_year; - if (ret != std::istreambuf_iterator()) { + + if (ret != last) + { std::cout << " Remaining content: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); - } else { - std::cout << " the input was fully consumed"; + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); } - } else { + else + std::cout << " the input was fully consumed"; + } + else + { std::cout << "Parse failed. Unparsed string: "; - std::copy(ret, std::istreambuf_iterator(), - std::ostreambuf_iterator(std::cout)); + std::copy(ret, last, std::ostreambuf_iterator(std::cout)); } + std::cout << '\\n'; } - + int main() { std::locale::global(std::locale("en_US.utf8")); try_get_year("13"); try_get_year("2013"); - + std::locale::global(std::locale("ja_JP.utf8")); try_get_year("2013年"); } @@ -110,7 +115,16 @@ Parsing the year out of '2013年' in the locale ja_JP.utf8 Successfully parsed, year is 2013 Remaining content: 年 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 248 C++98 eofbit was not set upon reaching the sets eofbit if a valid year + end iterator has not been read + .SH See also get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::time_get::time_get.3 b/man/std::time_get::time_get.3 index db0a5c238..70fb824e0 100644 --- a/man/std::time_get::time_get.3 +++ b/man/std::time_get::time_get.3 @@ -1,10 +1,13 @@ -.TH std::time_get::time_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::time_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::time_get \- std::time_get::time_get + .SH Synopsis Defined in header explicit time_get( std::size_t refs = 0 ); Creates a std::time_get facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::time_get::~time_get.3 b/man/std::time_get::~time_get.3 index a405abbed..e8c0d1b71 100644 --- a/man/std::time_get::~time_get.3 +++ b/man/std::time_get::~time_get.3 @@ -1,4 +1,7 @@ -.TH std::time_get::~time_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get::~time_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get::~time_get \- std::time_get::~time_get + .SH Synopsis Defined in header protected: ~time_get(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_time_get : public std::time_get { Destructible_time_get(std::size_t refs = 0) : time_get(refs) {} - ~Destructible_time_get() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_time_get dc; - // std::time_get c; // compile error: protected destructor + // std::time_get c; // compile error: protected destructor } diff --git a/man/std::time_get_byname.3 b/man/std::time_get_byname.3 index 1c04ca3c7..b26b1ab57 100644 --- a/man/std::time_get_byname.3 +++ b/man/std::time_get_byname.3 @@ -1,38 +1,43 @@ -.TH std::time_get_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_get_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_get_byname \- std::time_get_byname + .SH Synopsis Defined in header template< class CharT, - class InputIterator = std::istreambuf_iterator + class InputIt = std::istreambuf_iterator - > class time_get_byname : public std::time_get + > class time_get_byname : public std::time_get std::time_get_byname is a std::time_get facet which encapsulates time and date parsing rules of the locale specified at its construction. - Two specializations are provided by the standard library +.SH Specializations - Defined in header - std::time_get_byname narrow/multibyte time parsing - std::time_get_byname wide string time parsing + The standard library is guaranteed to provide every specialization that satisfies + the following type requirements: + + * CharT is one of char and wchar_t, and + * InputIt must meet the requirements of LegacyInputIterator. .SH Member types Member type Definition char_type CharT - iter_type OutputIterator + iter_type InputIt .SH Member functions constructor constructs a new time_get_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a time_get_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP - - std::time_get_byname::time_get_byname + +std::time_get_byname::time_get_byname explicit time_get_byname( const char* name, std::size_t refs = 0 ); explicit time_get_byname( const std::string& name, std::size_t refs = \fI(since C++11)\fP @@ -49,9 +54,9 @@ name - the name of the locale refs - the number of references that link to the facet - - std::time_get_byname::~time_get_byname + +std::time_get_byname::~time_get_byname protected: ~time_get_byname(); @@ -72,37 +77,44 @@ Inherited from std::time_get .SH Member functions date_order invokes do_date_order - \fI(public member function of std::time_get)\fP + \fI(public member function of std::time_get)\fP get_time invokes do_get_time - \fI(public member function of std::time_get)\fP + \fI(public member function of std::time_get)\fP get_date invokes do_get_date - \fI(public member function of std::time_get)\fP + \fI(public member function of std::time_get)\fP get_weekday invokes do_get_weekday - \fI(public member function of std::time_get)\fP + \fI(public member function of std::time_get)\fP get_monthname invokes do_get_monthname - \fI(public member function of std::time_get)\fP + \fI(public member function of std::time_get)\fP get_year invokes do_get_year - \fI(public member function of std::time_get)\fP + \fI(public member function of std::time_get)\fP get invokes do_get - \fI(C++11)\fP \fI(public member function of std::time_get)\fP + \fI(C++11)\fP \fI(public member function of std::time_get)\fP .SH Protected member functions do_date_order obtains preferred ordering of day, month, and year - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) do_get_time extracts hours, minutes, and seconds from input stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) do_get_date extracts month, day, and year from input stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) do_get_weekday extracts the name of a day of the week from input stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP - do_get_monthname extacts a month name from input stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) + do_get_monthname extracts a month name from input stream + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) do_get_year extracts a year from input stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_get)\fP - do_get extracts date/time components from input stream, according to the - \fB[virtual]\fP \fI(C++11)\fP specified format - \fI(virtual protected member function of std::time_get)\fP + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) + extracts date/time components from input stream, according to the + do_get specified format + \fB[virtual]\fP \fI(C++11)\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) Inherited from std::time_base @@ -117,12 +129,10 @@ Inherited from std::time_base .SH See also - parses time/date values from an input character sequence into struct - time_get std::tm - \fI(class template)\fP + time_get parses time/date values from an input character sequence into std::tm + \fI(class template)\fP get_time parses a date/time value of specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Category: - * Todo no example diff --git a/man/std::time_put.3 b/man/std::time_put.3 index 6d2c5d8cd..490cccdd6 100644 --- a/man/std::time_put.3 +++ b/man/std::time_put.3 @@ -1,4 +1,7 @@ -.TH std::time_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_put \- std::time_put + .SH Synopsis Defined in header template< @@ -13,32 +16,27 @@ generate text representation of an std::tm object. std-time put-inheritance.svg - About this image Inheritance diagram -.SH Type requirements - - - - OutputIt must meet the requirements of OutputIterator. + If a std::time_put specialization is not guaranteed to be provided by the standard + library (see below), the behaviors of its put() and do_put() are not guaranteed as + specified. .SH Specializations - Two standalone (locale-independent) full specializations and two partial - specializations are provided by the standard library: + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header - std::time_put creates narrow string representations of date and - time - std::time_put creates wide string representations of date and - time - std::time_put creates narrow string representations of date and - time using custom output iterator - std::time_put creates wide string representations of date and - time using custom output iterator - - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. + std::time_put creates narrow string representations of date and time + std::time_put creates wide string representations of date and time + + In addition, the standard library is also guaranteed to provide every specialization + that satisfies the following type requirements: + + * CharT is one of char and wchar_t, and + * OutputIt must meet the requirements of LegacyOutputIterator. .SH Member types @@ -49,11 +47,11 @@ .SH Member functions constructor constructs a new time_put facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs a time_put facet - \fI(protected member function)\fP + \fI(protected member function)\fP put invokes do_put - \fI(public member function)\fP + \fI(public member function)\fP .SH Member objects @@ -63,24 +61,25 @@ .SH Protected member functions do_put formats date/time and writes to output stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Example - + // Run this code - #include + #include #include #include - #include - + #include + int main() { - std::time_t t = std::time(NULL); + std::time_t t = std::time(nullptr); std::wbuffer_convert> conv(std::cout.rdbuf()); std::wostream out(&conv); - out.imbue(std::locale("ja_JP")); + out.imbue(std::locale("ja_JP.utf8")); + // this I/O manipulator std::put_time uses std::time_put out << std::put_time(std::localtime(&t), L"%A %c") << '\\n'; } @@ -92,10 +91,10 @@ .SH See also time_put_byname represents the system-supplied std::time_put for the named locale - \fI(class template)\fP - parses time/date values from an input character sequence into struct + \fI(class template)\fP + parses time/date values from an input character sequence into time_get std::tm - \fI(class template)\fP + \fI(class template)\fP put_time formats and outputs a date/time value according to the specified \fI(C++11)\fP format - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::time_put::put,std::time_put::do_put.3 b/man/std::time_put::put,std::time_put::do_put.3 index 402b9e9a9..43549af48 100644 --- a/man/std::time_put::put,std::time_put::do_put.3 +++ b/man/std::time_put::put,std::time_put::do_put.3 @@ -1,4 +1,7 @@ -.TH std::time_put::put,std::time_put::do_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_put::put,std::time_put::do_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_put::put,std::time_put::do_put \- std::time_put::put,std::time_put::do_put + .SH Synopsis Defined in header public: @@ -6,10 +9,10 @@ iter_type put( iter_type out, std::ios_base& str, \fB(1)\fP char_type fill, const std::tm* t, - const charT* fmtbeg, const charT* fmtend ) const; + const CharT* fmtbeg, const CharT* fmtend ) const; public: - iter_type put( iter_type out, std::ios_base& str, \fB(1)\fP + iter_type put( iter_type out, std::ios_base& str, \fB(2)\fP char_type fill, const std::tm* t, char format, char modifier = 0 ) const; @@ -22,14 +25,14 @@ Converts the calendar date and time stored in the std::tm object pointed to by t into a character string, according to the format string [fmtbeg, fmtend). The format - string is the same as used by std::srtftime, but each format specifier is processed + string is the same as used by std::strftime, but each format specifier is processed by an individual call to do_put(), which can be customized by extending this facet. 1) Steps through the character sequence [fmtbeg, fmtend), examining the characters. Every character that is not a part of a format sequence is written to the output iterator out immediately. To identify format sequences, this function narrows the next character c in [fmtbeg, fmtend) as if by - std::ctype(str.getloc()).narrow(c,0) and if it equals '%', the next one + std::ctype(str.getloc()).narrow(c, 0) and if it equals '%', the next one or two characters are compared to the list of format sequences recognized by std::strftime plus any additional implementation-defined formats supported by this locale. For each valid format sequence, a call to do_put(out, str, fill, t, format, @@ -53,188 +56,8 @@ needed, e.g. std::ctype to narrow characters t - pointer to the std::tm object from which the date/time values are obtained - pointer to the first character of a sequence of char_type characters + fmtbeg - pointer to the first character of a sequence of char_type characters specifying the conversion format - - The format string consists of zero or more conversion specifiers and - ordinary characters (except %). All ordinary characters, including the - terminating null character, are copied to the output string without - modification. Each conversion specification begins with % character, - optionally followed by E or O modifier (ignored if unsupported by the - locale), followed by the character that determines the behavior of the - specifier. The following format specifiers are available: - - Conversion Explanation Used fields - specifier - % writes literal %. The full conversion - specification must be %%. - n writes newline character - \fI(C++11)\fP - t writes horizontal tab character - \fI(C++11)\fP - Year - Y writes year as a 4 digit decimal number tm_year - writes year in the alternative - EY representation, e.g.平成23年 (year Heisei tm_year - \fI(C++11)\fP 23) instead of 2011年 (year 2011) in ja_JP - locale - y writes last 2 digits of year as a decimal tm_year - number (range [00,99]) - Oy writes last 2 digits of year using the - \fI(C++11)\fP alternative numeric system, e.g. 十一 tm_year - instead of 11 in ja_JP locale - Ey writes year as offset from locale's - \fI(C++11)\fP alternative calendar period %EC tm_year - (locale-dependent) - C writes first 2 digits of year as a decimal tm_year - \fI(C++11)\fP number (range [00,99]) - EC writes name of the base year (period) in the - \fI(C++11)\fP locale's alternative representation, e.g. 平 tm_year - 成 (Heisei era) in ja_JP - writes ISO 8601 week-based year, i.e. the - year that contains the specified week. - - G In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - writes last 2 digits of ISO 8601 week-based - year, i.e. the year that contains the - specified week (range [00,99]). - - g In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - Month - b writes abbreviated month name, e.g. Oct tm_mon - (locale dependent) - h synonym of b tm_mon - \fI(C++11)\fP - B writes full month name, e.g. October (locale tm_mon - dependent) - m writes month as a decimal number (range tm_mon - [01,12]) - Om writes month using the alternative numeric - \fI(C++11)\fP system, e.g. 十二 instead of 12 in ja_JP tm_mon - locale - Week - writes week of the year as a decimal number tm_year, tm_wday, - U (Sunday is the first day of the week) (range tm_yday - [00,53]) - OU writes week of the year, as by %U, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - writes week of the year as a decimal number tm_year, tm_wday, - W (Monday is the first day of the week) (range tm_yday - [00,53]) - OW writes week of the year, as by %W, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - writes ISO 8601 week of the year (range - [01,53]). - - V In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - fmtbeg - * Includes first Thursday of the year - OV writes week of the year, as by %V, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - Day of the year/month - j writes day of the year as a decimal number tm_yday - (range [001,366]) - d writes day of the month as a decimal number tm_mday - (range [01,31]) - writes zero-based day of the month using the - Od alternative numeric system, e.g 二十七 - \fI(C++11)\fP instead of 23 in ja_JP locale tm_mday - - Single character is preceded by a space. - writes day of the month as a decimal number - e (range [1,31]). tm_mday - \fI(C++11)\fP - Single digit is preceded by a space. - writes one-based day of the month using the - Oe alternative numeric system, e.g. 二十七 - \fI(C++11)\fP instead of 27 in ja_JP locale tm_mday - - Single character is preceded by a space. - Day of the week - a writes abbreviated weekday name, e.g. Fri tm_wday - (locale dependent) - A writes full weekday name, e.g. Friday tm_wday - (locale dependent) - w writes weekday as a decimal number, where tm_wday - Sunday is 0 (range [0-6]) - Ow writes weekday, where Sunday is 0, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead tm_wday - of 2 in ja_JP locale - u writes weekday as a decimal number, where tm_wday - \fI(C++11)\fP Monday is 1 (ISO 8601 format) (range [1-7]) - Ou writes weekday, where Monday is 1, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead tm_wday - of 2 in ja_JP locale - Hour, minute, second - H writes hour as a decimal number, 24 hour tm_hour - clock (range [00-23]) - OH writes hour from 24-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 十八 tm_hour - instead of 18 in ja_JP locale - I writes hour as a decimal number, 12 hour tm_hour - clock (range [01,12]) - OI writes hour from 12-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 六 instead tm_hour - of 06 in ja_JP locale - M writes minute as a decimal number (range tm_min - [00,59]) - OM writes minute using the alternative numeric - \fI(C++11)\fP system, e.g. 二十五 instead of 25 in ja_JP tm_min - locale - S writes second as a decimal number (range tm_sec - [00,60]) - OS writes second using the alternative numeric - \fI(C++11)\fP system, e.g. 二十四 instead of 24 in ja_JP tm_sec - locale -.SH Other - c writes standard date and time string, e.g. all - Sun Oct 17 04:41:13 2010 (locale dependent) - Ec writes alternative date and time string, - \fI(C++11)\fP e.g. using 平成23年 (year Heisei 23) instead all - of 2011年 (year 2011) in ja_JP locale - x writes localized date representation (locale all - dependent) - Ex writes alternative date representation, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of all - 2011年 (year 2011) in ja_JP locale - X writes localized time representation (locale all - dependent) - EX writes alternative time representation all - \fI(C++11)\fP (locale dependent) - D equivalent to "%m/%d/%y" tm_mon, tm_mday, - \fI(C++11)\fP tm_year - F equivalent to "%Y-%m-%d" (the ISO 8601 date tm_mon, tm_mday, - \fI(C++11)\fP format) tm_year - r writes localized 12-hour clock time (locale tm_hour, tm_min, - \fI(C++11)\fP dependent) tm_sec - R equivalent to "%H:%M" tm_hour, tm_min - \fI(C++11)\fP - T equivalent to "%H:%M:%S" (the ISO 8601 time tm_hour, tm_min, - \fI(C++11)\fP format) tm_sec - p writes localized a.m. or p.m. (locale tm_hour - dependent) - z writes offset from UTC in the ISO 8601 - \fI(C++11)\fP format (e.g. -0430), or no characters if the tm_isdst - time zone information is not available - writes time zone name or abbreviation, or no - Z characters if the time zone information is tm_isdst - not available (locale dependent) fmtend - pointer one past the last character of a sequence of char_type characters specifying the conversion format fill - fill character (usually space) @@ -242,9 +65,170 @@ modifier - the optional modifier that may appear between % and the conversion specifier + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters (except %). All ordinary characters, including the terminating null + character, are copied to the output string without modification. Each conversion + specification begins with % character, optionally followed by E or O modifier + (ignored if unsupported by the locale), followed by the character that determines + the behavior of the specifier. The following format specifiers are available: + + Conversion Explanation Used fields + specifier + % writes literal %. The full conversion specification + must be %%. + n writes newline character + \fI(C++11)\fP + t writes horizontal tab character + \fI(C++11)\fP + Year + Y writes year as a decimal number, e.g. 2017 tm_year + EY writes year in the alternative representation, e.g.平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) tm_year + in ja_JP locale + y writes last 2 digits of year as a decimal number (range tm_year + [00,99]) + Oy writes last 2 digits of year using the alternative tm_year + \fI(C++11)\fP numeric system, e.g. 十一 instead of 11 in ja_JP locale + Ey writes year as offset from locale's alternative tm_year + \fI(C++11)\fP calendar period %EC (locale-dependent) + C writes first 2 digits of year as a decimal number tm_year + \fI(C++11)\fP (range [00,99]) + EC writes name of the base year (period) in the locale's + \fI(C++11)\fP alternative representation, e.g. 平成 (Heisei era) in tm_year + ja_JP + writes ISO 8601 week-based year, i.e. the year that + contains the specified week. + + G In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + writes last 2 digits of ISO 8601 week-based year, i.e. + the year that contains the specified week (range + [00,99]). + g tm_year, tm_wday, + \fI(C++11)\fP In ISO 8601 weeks begin with Monday and the first week tm_yday + of the year must satisfy the following requirements: + + * Includes January 4 + * Includes first Thursday of the year + Month + b writes abbreviated month name, e.g. Oct (locale tm_mon + dependent) + h synonym of b tm_mon + \fI(C++11)\fP + B writes full month name, e.g. October (locale dependent) tm_mon + m writes month as a decimal number (range [01,12]) tm_mon + Om writes month using the alternative numeric system, e.g. tm_mon + \fI(C++11)\fP 十二 instead of 12 in ja_JP locale + Week + U writes week of the year as a decimal number (Sunday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OU writes week of the year, as by %U, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + W writes week of the year as a decimal number (Monday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OW writes week of the year, as by %W, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + writes ISO 8601 week of the year (range [01,53]). + + V In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + OV writes week of the year, as by %V, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + Day of the year/month + j writes day of the year as a decimal number (range tm_yday + [001,366]) + d writes day of the month as a decimal number (range tm_mday + [01,31]) + writes zero-based day of the month using the + Od alternative numeric system, e.g. 二十七 instead of 27 + \fI(C++11)\fP in ja_JP locale tm_mday + + Single character is preceded by a space. + writes day of the month as a decimal number (range + e [1,31]). tm_mday + \fI(C++11)\fP + Single digit is preceded by a space. + writes one-based day of the month using the alternative + Oe numeric system, e.g. 二十七 instead of 27 in ja_JP + \fI(C++11)\fP locale tm_mday + + Single character is preceded by a space. + Day of the week + a writes abbreviated weekday name, e.g. Fri (locale tm_wday + dependent) + A writes full weekday name, e.g. Friday (locale tm_wday + dependent) + w writes weekday as a decimal number, where Sunday is 0 tm_wday + (range [0-6]) + Ow writes weekday, where Sunday is 0, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + u writes weekday as a decimal number, where Monday is 1 tm_wday + \fI(C++11)\fP (ISO 8601 format) (range [1-7]) + Ou writes weekday, where Monday is 1, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + Hour, minute, second + H writes hour as a decimal number, 24 hour clock (range tm_hour + [00-23]) + OH writes hour from 24-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 十八 instead of 18 in ja_JP locale + I writes hour as a decimal number, 12 hour clock (range tm_hour + [01,12]) + OI writes hour from 12-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 六 instead of 06 in ja_JP locale + M writes minute as a decimal number (range [00,59]) tm_min + OM writes minute using the alternative numeric system, tm_min + \fI(C++11)\fP e.g. 二十五 instead of 25 in ja_JP locale + S writes second as a decimal number (range [00,60]) tm_sec + OS writes second using the alternative numeric system, tm_sec + \fI(C++11)\fP e.g. 二十四 instead of 24 in ja_JP locale +.SH Other + c writes standard date and time string, e.g. Sun Oct 17 all + 04:41:13 2010 (locale dependent) + Ec writes alternative date and time string, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + x writes localized date representation (locale dependent) all + Ex writes alternative date representation, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + X writes localized time representation, e.g. 18:40:20 or all + 6:40:20 PM (locale dependent) + EX writes alternative time representation (locale all + \fI(C++11)\fP dependent) + D equivalent to "%m/%d/%y" tm_mon, tm_mday, + \fI(C++11)\fP tm_year + F equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday, + \fI(C++11)\fP tm_year + r writes localized 12-hour clock time (locale dependent) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + R equivalent to "%H:%M" tm_hour, tm_min + \fI(C++11)\fP + T equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + p writes localized a.m. or p.m. (locale dependent) tm_hour + z writes offset from UTC in the ISO 8601 format (e.g. + \fI(C++11)\fP -0430), or no characters if the time zone information tm_isdst + is not available + writes locale-dependent time zone name or abbreviation, + Z or no characters if the time zone information is not tm_isdst + available + .SH Return value - Iterator pointing one past the last character that was produced . + Iterator pointing one past the last character that was produced. .SH Notes @@ -256,58 +240,66 @@ .SH Example - + // Run this code #include #include #include #include - + void try_time_put(const std::tm* t, const std::string& fmt) { - std::cout.imbue(std::locale()); - std::cout << "In the locale '" << std::cout.getloc().name() << "' : '"; - - std::use_facet>(std::cout.getloc()).put( - std::ostreambuf_iterator(std::cout), - std::cout, ' ', t, &fmt[0], &fmt[0] + fmt.size()); - - std::cout << "'\\n"; + std::cout.imbue(std::locale()); + std::cout << "In the locale '" << std::cout.getloc().name() << "' : '"; + + std::use_facet>(std::cout.getloc()).put( + {std::cout}, std::cout, ' ', t, &fmt[0], &fmt[0] + fmt.size()); + + std::cout << "'\\n"; } - + int main() { std::time_t t = std::time(NULL); std::tm tm = *std::localtime(&t); - + std::string fmt = "%c"; std::cout << "Using the format string '" << fmt << "' to format the time: " << std::ctime(&t) << '\\n'; - + std::locale::global(std::locale("de_DE.utf8")); try_time_put(&tm, fmt); - + std::locale::global(std::locale("el_GR.utf8")); try_time_put(&tm, fmt); - + std::locale::global(std::locale("ja_JP.utf8")); try_time_put(&tm, fmt); } -.SH Output: +.SH Possible output: Using the format string '%c' to format the time: Mon Feb 11 22:58:50 2013 - + In the locale 'de_DE.utf8' : 'Mo 11 Feb 2013 23:02:38 EST' In the locale 'el_GR.utf8' : 'Δευ 11 Φεβ 2013 11:02:38 μμ EST' In the locale 'ja_JP.utf8' : '2013年02月11日 23時02分38秒' + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 164 C++98 the purpose of the parameter fill was not clear made clear + .SH See also put_time formats and outputs a date/time value according to the specified \fI(C++11)\fP format - \fI(function template)\fP - do_get extracts date/time components from input stream, according to the - \fB[virtual]\fP \fI(C++11)\fP specified format - \fI(virtual protected member function of std::time_get)\fP + \fI(function template)\fP + extracts date/time components from input stream, according to the + do_get specified format + \fB[virtual]\fP \fI(C++11)\fP \fI\fI(virtual protected member function\fP of\fP + std::time_get) diff --git a/man/std::time_put::time_put.3 b/man/std::time_put::time_put.3 index 5582ea25a..4e61c8b67 100644 --- a/man/std::time_put::time_put.3 +++ b/man/std::time_put::time_put.3 @@ -1,10 +1,13 @@ -.TH std::time_put::time_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_put::time_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_put::time_put \- std::time_put::time_put + .SH Synopsis Defined in header explicit time_put( std::size_t refs = 0 ); Creates a std::time_put facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::time_put::~time_put.3 b/man/std::time_put::~time_put.3 index 97f606753..89d6d755e 100644 --- a/man/std::time_put::~time_put.3 +++ b/man/std::time_put::~time_put.3 @@ -1,4 +1,7 @@ -.TH std::time_put::~time_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_put::~time_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_put::~time_put \- std::time_put::~time_put + .SH Synopsis Defined in header protected: ~time_put(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_time_put : public std::time_put { Destructible_time_put(std::size_t refs = 0) : time_put(refs) {} - ~Destructible_time_put() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_time_put dc; - // std::time_put c; // compile error: protected destructor + // std::time_put c; // compile error: protected destructor } diff --git a/man/std::time_put_byname.3 b/man/std::time_put_byname.3 index 43ecac358..c70357cc4 100644 --- a/man/std::time_put_byname.3 +++ b/man/std::time_put_byname.3 @@ -1,34 +1,43 @@ -.TH std::time_put_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_put_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_put_byname \- std::time_put_byname + .SH Synopsis Defined in header - template< class CharT, class OutputIterator = std::ostreambuf_iterator > - class time_put_byname : public std::time_put; + template< + + class CharT, + class OutputIt = std::ostreambuf_iterator + + > class time_put_byname : public std::time_put; std::time_put_byname is a std::time_put facet which encapsulates time and date formatting rules of the locale specified at its construction. - Two specializations are provided by the standard library +.SH Specializations - Defined in header - std::time_put_byname narrow/multibyte time formatting - std::time_put_byname wide string time formatting + The standard library is guaranteed to provide every specialization that satisfies + the following type requirements: + + * CharT is one of char and wchar_t, and + * OutputIt must meet the requirements of LegacyOutputIterator. .SH Member types Member type Definition char_type CharT - iter_type OutputIterator + iter_type OutputIt .SH Member functions constructor constructs a new time_put_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a time_put_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP - - std::time_put_byname::time_put_byname + +std::time_put_byname::time_put_byname explicit time_put_byname( const char* name, std::size_t refs = 0 ); explicit time_put_byname( const std::string& name, std::size_t refs = \fI(since C++11)\fP @@ -45,9 +54,9 @@ name - the name of the locale refs - the number of references that link to the facet - - std::time_put_byname::~time_put_byname + +std::time_put_byname::~time_put_byname protected: ~time_put_byname(); @@ -64,52 +73,53 @@ Inherited from std::time_put .SH Member functions put invokes do_put - \fI(public member function of std::time_put)\fP + \fI(public member function of std::time_put)\fP .SH Protected member functions do_put formats date/time and writes to output stream - \fB[virtual]\fP \fI(virtual protected member function of std::time_put)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::time_put)\fP + .SH Example - This example prints current time using the "C" locale with the time_put facet - replaced by various time_put_byname facets + Prints current time using the "C" locale with the time_put facet replaced by various + std::time_put_byname facets. The result shown was obtained using the clang compiler. + - // Run this code - #include + #include #include #include - #include - + #include + int main() { - std::time_t t = std::time(NULL); + std::time_t t = std::time(nullptr); std::wbuffer_convert> conv(std::cout.rdbuf()); std::wostream out(&conv); - + out.imbue(std::locale(out.getloc(), - new std::time_put_byname("ja_JP"))); + new std::time_put_byname("ja_JP.utf8"))); out << std::put_time(std::localtime(&t), L"%A %c") << '\\n'; - + out.imbue(std::locale(out.getloc(), - new std::time_put_byname("ru_RU.utf8"))); + new std::time_put_byname("ru_RU.utf8"))); out << std::put_time(std::localtime(&t), L"%A %c") << '\\n'; - + out.imbue(std::locale(out.getloc(), - new std::time_put_byname("sv_SE.utf8"))); + new std::time_put_byname("sv_SE.utf8"))); out << std::put_time(std::localtime(&t), L"%A %c") << '\\n'; } .SH Possible output: - 木曜日 2012年08月09日 21時41分02秒 - Четверг Чт. 09 авг. 2012 21:41:02 - torsdag tor 9 aug 2012 21:41:02 + 木曜日 2023年10月05日 19時44分51秒 + Четверг Чт 05 окт 2023 19:44:51 + torsdag tor 5 okt 2023 19:44:51 .SH See also - time_put formats contents of struct std::tm for output as character sequence - \fI(class template)\fP + time_put formats contents of std::tm for output as character sequence + \fI(class template)\fP diff --git a/man/std::time_t.3 b/man/std::time_t.3 index ef69c18d1..eed86ecc7 100644 --- a/man/std::time_t.3 +++ b/man/std::time_t.3 @@ -1,22 +1,27 @@ -.TH std::time_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::time_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::time_t \- std::time_t + .SH Synopsis Defined in header typedef /* unspecified */ time_t; Arithmetic type capable of representing times. - Although not defined, this is almost always a integral value holding the number of + Although not defined, this is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to POSIX time. .SH See also time returns the current time of the system as time since epoch - \fI(function)\fP + \fI(function)\fP localtime converts time since epoch to calendar time expressed as local time - \fI(function)\fP + \fI(function)\fP converts time since epoch to calendar time expressed as Universal gmtime Coordinated Time - \fI(function)\fP + \fI(function)\fP + to_time_t converts a system clock time point to std::time_t + \fB[static]\fP \fI(public static member function of std::chrono::system_clock)\fP C documentation for time_t diff --git a/man/std::timed_mutex.3 b/man/std::timed_mutex.3 index 52d85ce27..732682a43 100644 --- a/man/std::timed_mutex.3 +++ b/man/std::timed_mutex.3 @@ -1,4 +1,7 @@ -.TH std::timed_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex \- std::timed_mutex + .SH Synopsis Defined in header class timed_mutex; \fI(since C++11)\fP @@ -8,38 +11,38 @@ In a manner similar to mutex, timed_mutex offers exclusive, non-recursive ownership semantics. In addition, timed_mutex provides the ability to attempt to claim - ownership of a timed_mutex with a timeout via the try_lock_for() and - try_lock_until() methods. + ownership of a timed_mutex with a timeout via the member functions try_lock_for() + and try_lock_until(). The timed_mutex class satisfies all requirements of TimedMutex and StandardLayoutType. .SH Member types - Member type Definition - native_handle_type implementation-defined + Member type Definition + native_handle_type (optional*) implementation-defined .SH Member functions constructor constructs the mutex - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys the mutex - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP .SH Locking lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Native handle - native_handle returns the underlying implementation-defined thread handle - \fI(public member function)\fP + native_handle returns the underlying implementation-defined native handle object + \fI(public member function)\fP diff --git a/man/std::timed_mutex::lock.3 b/man/std::timed_mutex::lock.3 index 9da072f36..788a6ef81 100644 --- a/man/std::timed_mutex::lock.3 +++ b/man/std::timed_mutex::lock.3 @@ -1,4 +1,7 @@ -.TH std::timed_mutex::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::lock \- std::timed_mutex::lock + .SH Synopsis void lock(); \fI(since C++11)\fP @@ -6,10 +9,11 @@ block execution until the lock is acquired. If lock is called by a thread that already owns the mutex, the behavior is - undefined: the program may deadlock, or, if the implementation can detect the - deadlock, a resource_deadlock_would_occur error condition may be thrown. + undefined: for example, the program may deadlock. An implementation that can detect + the invalid usage is encouraged to throw a std::system_error with error condition + resource_deadlock_would_occur instead of deadlocking. - Prior unlock() operation on the same mutex synchronizes-with (as defined in + Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation. .SH Parameters @@ -28,62 +32,66 @@ .SH Notes - lock() is usually not called directly: std::unique_lock and std::lock_guard are used - to manage exclusive locking. + lock() is usually not called directly: std::unique_lock, std::scoped_lock, and + std::lock_guard are used to manage exclusive locking. .SH Example This example shows how lock and unlock can be used to protect shared data. - + // Run this code - #include #include - #include + #include #include - - int g_num = 0; // protected by g_num_mutex + #include + + int g_num = 0; // protected by g_num_mutex std::mutex g_num_mutex; - + void slow_increment(int id) { - for (int i = 0; i < 3; ++i) { + for (int i = 0; i < 3; ++i) + { g_num_mutex.lock(); ++g_num; - std::cout << id << " => " << g_num << '\\n'; + // note, that the mutex also syncronizes the output + std::cout << "id: " << id << ", g_num: " << g_num << '\\n'; g_num_mutex.unlock(); - - std::this_thread::sleep_for(std::chrono::seconds(1)); + + std::this_thread::sleep_for(std::chrono::milliseconds(234)); } } - + int main() { - std::thread t1(slow_increment, 0); - std::thread t2(slow_increment, 1); + std::thread t1{slow_increment, 0}; + std::thread t2{slow_increment, 1}; t1.join(); t2.join(); } .SH Possible output: - 0 => 1 - 1 => 2 - 0 => 3 - 1 => 4 - 0 => 5 - 1 => 6 + id: 0, g_num: 1 + id: 1, g_num: 2 + id: 1, g_num: 3 + id: 0, g_num: 4 + id: 0, g_num: 5 + id: 1, g_num: 6 .SH See also try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_lock diff --git a/man/std::timed_mutex::native_handle.3 b/man/std::timed_mutex::native_handle.3 index 4a251c626..8a81ccf87 100644 --- a/man/std::timed_mutex::native_handle.3 +++ b/man/std::timed_mutex::native_handle.3 @@ -1,6 +1,10 @@ -.TH std::timed_mutex::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::native_handle \- std::timed_mutex::native_handle + .SH Synopsis native_handle_type native_handle(); \fI(since C++11)\fP + (not always present) Returns the underlying implementation-defined native handle object. @@ -14,14 +18,12 @@ .SH Exceptions - This section is incomplete + Implementation-defined. .SH Example This section is incomplete Reason: no example - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::timed_mutex::timed_mutex.3 b/man/std::timed_mutex::timed_mutex.3 index fb45fab8d..348a1d82b 100644 --- a/man/std::timed_mutex::timed_mutex.3 +++ b/man/std::timed_mutex::timed_mutex.3 @@ -1,4 +1,7 @@ -.TH std::timed_mutex::timed_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::timed_mutex \- std::timed_mutex::timed_mutex + .SH Synopsis timed_mutex(); \fB(1)\fP \fI(since C++11)\fP timed_mutex( const timed_mutex& ) = delete; \fB(2)\fP \fI(since C++11)\fP @@ -13,3 +16,8 @@ .SH Exceptions std::system_error if the construction is unsuccessful. + +.SH See also + + C documentation for + mtx_init diff --git a/man/std::timed_mutex::try_lock.3 b/man/std::timed_mutex::try_lock.3 index d62edd707..775e28f33 100644 --- a/man/std::timed_mutex::try_lock.3 +++ b/man/std::timed_mutex::try_lock.3 @@ -1,4 +1,7 @@ -.TH std::timed_mutex::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::try_lock \- std::timed_mutex::try_lock + .SH Synopsis bool try_lock(); \fI(since C++11)\fP @@ -25,11 +28,11 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example - + This section is incomplete Reason: no example @@ -37,16 +40,17 @@ .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_trylock .SH Category: - * Todo no example diff --git a/man/std::timed_mutex::try_lock_for.3 b/man/std::timed_mutex::try_lock_for.3 index c8697bc59..de4ac54db 100644 --- a/man/std::timed_mutex::try_lock_for.3 +++ b/man/std::timed_mutex::try_lock_for.3 @@ -1,18 +1,25 @@ -.TH std::timed_mutex::try_lock_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::try_lock_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::try_lock_for \- std::timed_mutex::try_lock_for + .SH Synopsis template< class Rep, class Period > - bool try_lock_for( const std::chrono::duration& \fI(since C++11)\fP + bool try_lock_for( const std::chrono::duration& \fI(since C++11)\fP timeout_duration ); - Tries to lock the mutex. Blocks until specified timeout_duration has elapsed or the - lock is acquired, whichever comes first. On successful lock acquisition returns - true, otherwise returns false. + Tries to lock the mutex. Blocks until the specified duration timeout_duration has + elapsed (timeout) or the lock is acquired (owns the mutex), whichever comes first. + On successful lock acquisition returns true, otherwise returns false. If timeout_duration is less or equal timeout_duration.zero(), the function behaves like try_lock(). - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. + + The standard recommends that a std::steady_clock is used to measure the duration. If + an implementation uses a std::system_clock instead, the wait time may also be + sensitive to clock adjustments. As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point during @@ -26,7 +33,7 @@ .SH Parameters - timeout_duration - maximum duration to block for + timeout_duration - minimum duration to block for .SH Return value @@ -34,53 +41,56 @@ .SH Exceptions - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + Any exception thrown by timeout_duration (durations provided by the standard library + never throw). .SH Example - + // Run this code + #include #include #include + #include #include #include - #include - + + using namespace std::chrono_literals; + std::mutex cout_mutex; // control access to std::cout std::timed_mutex mutex; - + void job(int id) { - using Ms = std::chrono::milliseconds; std::ostringstream stream; - - for (int i = 0; i < 3; ++i) { - if (mutex.try_lock_for(Ms(100))) { + + for (int i = 0; i < 3; ++i) + { + if (mutex.try_lock_for(100ms)) + { stream << "success "; - std::this_thread::sleep_for(Ms(100)); + std::this_thread::sleep_for(100ms); mutex.unlock(); - } else { - stream << "failed "; } - std::this_thread::sleep_for(Ms(100)); + else + stream << "failed "; + + std::this_thread::sleep_for(100ms); } - - std::lock_guard lock(cout_mutex); - std::cout << "[" << id << "] " << stream.str() << "\\n"; + + std::lock_guard lock{cout_mutex}; + std::cout << '[' << id << "] " << stream.str() << '\\n'; } - + int main() { std::vector threads; - for (int i = 0; i < 4; ++i) { + for (int i{0}; i < 4; ++i) threads.emplace_back(job, i); - } - - for (auto& i: threads) { - i.join(); - } + + for (auto& th : threads) + th.join(); } .SH Possible output: @@ -90,14 +100,22 @@ [2] failed success failed [1] success failed success + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 try_lock_for threw nothing throws timeout-related exceptions + .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::timed_mutex::try_lock_until.3 b/man/std::timed_mutex::try_lock_until.3 index a2bf24ce2..eb82cd573 100644 --- a/man/std::timed_mutex::try_lock_until.3 +++ b/man/std::timed_mutex::try_lock_until.3 @@ -1,21 +1,28 @@ -.TH std::timed_mutex::try_lock_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::try_lock_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::try_lock_until \- std::timed_mutex::try_lock_until + .SH Synopsis template< class Clock, class Duration > - bool try_lock_until( const std::chrono::time_point& \fI(since C++11)\fP + bool try_lock_until( const std::chrono::time_point& \fI(since C++11)\fP timeout_time ); - Tries to lock the mutex. Blocks until specified timeout_time has been reached or the - lock is acquired, whichever comes first. On successful lock acquisition returns - true, otherwise returns false. + Tries to lock the mutex. Blocks until specified timeout_time has been reached + (timeout) or the lock is acquired (owns the mutex), whichever comes first. On + successful lock acquisition returns true, otherwise returns false. If timeout_time has already passed, this function behaves like try_lock(). - The clock tied to timeout_time is used, which means that adjustments of the clock - are taken into account. Thus, the maximum duration of the block might, but might - not, be less or more than timeout_time - Clock::now() at the time of the call, - depending on the direction of the adjustment. The function also may block for longer - than until after timeout_time has been reached due to scheduling or resource - contention delays. + Clock must meet the Clock requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP + + The standard recommends that the clock tied to timeout_time be used, in which case + adjustments of the clock may be taken into account. Thus, the duration of the block + might be more or less than timeout_time - Clock::now() at the time of the call, + depending on the direction of the adjustment and whether it is honored by the + implementation. The function also may block until after timeout_time has been + reached due to process scheduling or resource contention delays. As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point before @@ -37,45 +44,35 @@ .SH Exceptions - Any exception thrown by clock, time_point, or duration during the execution (clocks, - time points, and durations provided by the standard library never throw) + Any exception thrown by timeout_time (clocks, time points, and durations provided by + the standard library never throw). .SH Example - This example shows a 10 seconds block - - -// Run this code - - #include - #include - #include - #include - - std::timed_mutex test_mutex; - - void f() - { - auto now=std::chrono::steady_clock::now(); - test_mutex.try_lock_until(now + std::chrono::seconds(10)); - std::cout << "hello world\\n"; - } - - int main() - { - std::lock_guard l(test_mutex); - std::thread t(f); - t.join(); - } + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2093 C++11 try_lock_until threw nothing throws timeout-related exceptions .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_timedlock + +.SH Category: + * Todo no example diff --git a/man/std::timed_mutex::unlock.3 b/man/std::timed_mutex::unlock.3 index 11429324b..49cbf1d21 100644 --- a/man/std::timed_mutex::unlock.3 +++ b/man/std::timed_mutex::unlock.3 @@ -1,4 +1,7 @@ -.TH std::timed_mutex::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::unlock \- std::timed_mutex::unlock + .SH Synopsis void unlock(); \fI(since C++11)\fP @@ -20,7 +23,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes @@ -35,16 +38,17 @@ .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_for unavailable for the specified timeout duration - \fI(public member function)\fP + \fI(public member function)\fP tries to lock the mutex, returns if the mutex has been try_lock_until unavailable until specified time point has been reached - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_unlock .SH Category: - * Todo no example diff --git a/man/std::timed_mutex::~timed_mutex.3 b/man/std::timed_mutex::~timed_mutex.3 index 066f209b0..f12fb9146 100644 --- a/man/std::timed_mutex::~timed_mutex.3 +++ b/man/std::timed_mutex::~timed_mutex.3 @@ -1,4 +1,7 @@ -.TH std::timed_mutex::~timed_mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::timed_mutex::~timed_mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timed_mutex::~timed_mutex \- std::timed_mutex::~timed_mutex + .SH Synopsis ~timed_mutex(); @@ -6,3 +9,8 @@ The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex. + +.SH See also + + C documentation for + mtx_destroy diff --git a/man/std::timespec.3 b/man/std::timespec.3 new file mode 100644 index 000000000..b1e462241 --- /dev/null +++ b/man/std::timespec.3 @@ -0,0 +1,61 @@ +.TH std::timespec 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timespec \- std::timespec + +.SH Synopsis + Defined in header + struct timespec; \fI(since C++17)\fP + + Structure holding an interval broken down into seconds and nanoseconds. + +.SH Member objects + + std::time_t tv_sec whole seconds – >= 0 + long tv_nsec nanoseconds – [0, 999999999] + + The declaration order of tv_sec and tv_nsec is unspecified. Implementation may add + other data members to timespec. + +.SH Notes + + The type of tv_nsec is long long on some platforms, which is currently + non-conforming in C++, but is allowed in C since C23. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::timespec ts; + std::timespec_get(&ts, TIME_UTC); + char buff[0x80]; + std::strftime(buff, sizeof buff, "%D %T", std::gmtime(&ts.tv_sec)); + + // auto [sec, nsec] = ts; // UB: structured bindings should not be used because the + // declaration order and data member list are unspecified + + std::cout << "Current time: " << buff << " (UTC)\\n" + << "Raw timespec.tv_sec: " << ts.tv_sec << '\\n' + << "Raw timespec.tv_nsec: " << ts.tv_nsec << '\\n'; + } + +.SH Possible output: + + Current time: 04/06/23 12:03:31 (UTC) + Raw timespec.tv_sec: 1680782611 + Raw timespec.tv_nsec: 678437213 + +.SH See also + + timespec_get returns the calendar time in seconds and nanoseconds based on a given + \fI(C++17)\fP time base + \fI(function)\fP + tm calendar time type + \fI(class)\fP + C documentation for + timespec diff --git a/man/std::timespec_get.3 b/man/std::timespec_get.3 new file mode 100644 index 000000000..bbd9e4f07 --- /dev/null +++ b/man/std::timespec_get.3 @@ -0,0 +1,66 @@ +.TH std::timespec_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::timespec_get \- std::timespec_get + +.SH Synopsis + Defined in header + int timespec_get( std::timespec* ts, int base ); \fB(1)\fP \fI(since C++17)\fP + #define TIME_UTC /* implementation-defined */ \fB(2)\fP \fI(since C++17)\fP + + 1) Modifies the std::timespec object pointed to by ts to hold the current calendar + time in the time base base. + 2) Expands to a value suitable for use as the base argument of std::timespec_get. + + Other macro constants beginning with TIME_ may be provided by the implementation to + indicate additional time bases. + + If base is TIME_UTC, then + + * ts->tv_sec is set to the number of seconds since an implementation defined + epoch, truncated to a whole value, + * ts->tv_nsec member is set to the integral number of nanoseconds, rounded to the + resolution of the system clock. + +.SH Parameters + + ts - pointer to an object of type std::timespec + base - TIME_UTC or another nonzero integer value indicating the time base + +.SH Return value + + The value of base if successful, zero otherwise. + +.SH Notes + + The POSIX function clock_gettime(CLOCK_REALTIME, ts) may also be used to populate a + std::timespec with the time since the Epoch. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::timespec ts; + std::timespec_get(&ts, TIME_UTC); + char buf[100]; + std::strftime(buf, sizeof buf, "%D %T", std::gmtime(&ts.tv_sec)); + std::cout << "Current time: " << buf << '.' << ts.tv_nsec << " UTC\\n"; + } + +.SH Possible output: + + Current time: 06/24/16 20:07:42.949494132 UTC + +.SH See also + + timespec time in seconds and nanoseconds + \fI(C++17)\fP (struct) + time returns the current time of the system as time since epoch + \fI(function)\fP + C documentation for + timespec_get diff --git a/man/std::tm.3 b/man/std::tm.3 index 35d7efae7..7e782328a 100644 --- a/man/std::tm.3 +++ b/man/std::tm.3 @@ -1,4 +1,7 @@ -.TH std::tm 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tm 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tm \- std::tm + .SH Synopsis Defined in header struct tm; @@ -7,8 +10,11 @@ .SH Member objects - seconds after the minute – [0, 61]\fI(until C++11)\fP / [0, 60] (since - int tm_sec C++11)^[note 1] + seconds after the minute – + [0, 61] + int tm_sec \fI(until C++11)\fP + [0, 60] + \fI(since C++11)\fP^[note 1] \fI(public member object)\fP int tm_min minutes after the hour – [0, 59] \fI(public member object)\fP @@ -25,21 +31,60 @@ int tm_yday days since January 1 – [0, 365] \fI(public member object)\fP Daylight Saving Time flag. The value is positive if DST is in effect, - int tm_isdst zero if not and negative if no information is available + int tm_isdst zero if not and negative if no information is available. \fI(public member object)\fP .SH Notes + The Standard mandates only the presence of the aforementioned members in some order. + The implementations usually add more data members to this structure. + 1. ↑ Range allows for a positive leap second. Two leap seconds in the same minute - are not allowed (the range 0..61 was a defect introduced in C89 and corrected in - C99) + are not allowed (the range [0, 61] was a defect introduced in C89 and corrected + in C99). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::tm tm{}; + tm.tm_year = 2022 - 1900; + tm.tm_mday = 1; + std::mktime(&tm); + + std::cout << std::asctime(&tm); // note implicit trailing '\\n' + + std::cout << "sizeof(std::tm) = " << sizeof(std::tm) << '\\n' + << "sum of sizes of standard members = " + << sizeof(tm.tm_sec) + + sizeof(tm.tm_min) + + sizeof(tm.tm_hour) + + sizeof(tm.tm_mday) + + sizeof(tm.tm_mon) + + sizeof(tm.tm_year) + + sizeof(tm.tm_wday) + + sizeof(tm.tm_yday) + + sizeof(tm.tm_isdst) << '\\n'; + } + +.SH Possible output: + + Sat Jan 1 00:00:00 2022 + sizeof(std::tm) = 56 + sum of sizes of standard members = 36 .SH See also localtime converts time since epoch to calendar time expressed as local time - \fI(function)\fP + \fI(function)\fP converts time since epoch to calendar time expressed as Universal gmtime Coordinated Time - \fI(function)\fP + \fI(function)\fP C documentation for tm diff --git a/man/std::tmpfile.3 b/man/std::tmpfile.3 index 693510aa6..356e72ea1 100644 --- a/man/std::tmpfile.3 +++ b/man/std::tmpfile.3 @@ -1,13 +1,16 @@ -.TH std::tmpfile 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tmpfile 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tmpfile \- std::tmpfile + .SH Synopsis Defined in header std::FILE* tmpfile(); - Creates and opens a temporary file with unique auto-generated filename. + Creates and opens a temporary file with a unique auto-generated filename. - The file is opened as binary file for update (as by std::fopen with access mode + The file is opened as a binary file for update (as by std::fopen with access mode "wb+"). At least TMP_MAX files may be opened during the lifetime of a program (this - limit may be shared with std::tmpnam and may be further limited by FOPEN_MAX) + limit may be shared with std::tmpnam and may be further limited by FOPEN_MAX). If the program closes the file, e.g. by executing std::fclose, the file is automatically deleted. @@ -24,47 +27,62 @@ .SH Return value - The associated file stream or NULL if an error has occurred + The associated file stream or a null pointer if an error has occurred. .SH Notes - On some implementations (e.g. Linux), this function actually creates, opens, and - immediately deletes the file from the file system: as long as an open file + On some implementations (e.g. older Linux), this function actually creates, opens, + and immediately deletes the file from the file system: as long as an open file descriptor to a deleted file is held by a program, the file exists, but since it was deleted, its name does not appear in any directory, so that no other process can - open it. Once the file descriptor is closed, the space occupied by the file is - reclaimed by the filesystem. + open it. Once the file descriptor is closed, or once the program terminates + (normally or abnormally), the space occupied by the file is reclaimed by the + filesystem. Newer Linux (since 3.11 or later, depending on filesystem) creates such + invisible temporary files in one step, via special flag in the open() syscall. + + On some implementations (e.g. Windows), elevated privileges are required as the + function may create the temporary file in a system directory. .SH Example - + // Run this code - #include #include #include - + #include + #include + namespace fs = std::filesystem; + int main() { + std::cout << "TMP_MAX = " << TMP_MAX << '\\n' + << "FOPEN_MAX = " << FOPEN_MAX << '\\n'; std::FILE* tmpf = std::tmpfile(); std::fputs("Hello, world", tmpf); std::rewind(tmpf); char buf[6]; std::fgets(buf, sizeof buf, tmpf); std::cout << buf << '\\n'; - + // Linux-specific method to display the tmpfile name - std::system("ls -l /proc/self/fd/3"); + std::cout << fs::read_symlink( + fs::path("/proc/self/fd") / std::to_string(fileno(tmpf)) + ) << '\\n'; } .SH Possible output: + TMP_MAX = 238328 + FOPEN_MAX = 16 Hello - lrwx------ 1 user group 64 Jun 27 00:28 /proc/self/fd/3 -> /tmp/tmpfXu58Zi (deleted) + "/tmp/tmpfBlY1lI (deleted)" .SH See also - tmpnam returns a unique filename - \fI(function)\fP + tmpnam returns a unique filename + \fI(function)\fP + temp_directory_path returns a directory suitable for temporary files + \fI(C++17)\fP \fI(function)\fP C documentation for tmpfile diff --git a/man/std::tmpnam.3 b/man/std::tmpnam.3 index c65ea9769..4331dccfd 100644 --- a/man/std::tmpnam.3 +++ b/man/std::tmpnam.3 @@ -1,25 +1,29 @@ -.TH std::tmpnam 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tmpnam 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tmpnam \- std::tmpnam + .SH Synopsis Defined in header char* tmpnam( char* filename ); - Creates an unique filename that does not name a currently existing file, and stores + Creates a unique filename that does not name a currently existing file, and stores it in the character string pointed to by filename. The function is capable of generating up to TMP_MAX of unique filenames, but some or all of them may already be in use, and thus not suitable return values. - std::tmpnam is not reentrant and thus not thread-safe. + std::tmpnam modifies static state and is not required to be thread-safe. .SH Parameters pointer to the character array capable of holding at least L_tmpnam - filename - bytes, to be used as a result buffer. If NULL is passed, a pointer to an - internal static buffer is returned. + filename - bytes, to be used as a result buffer. If a null pointer is passed, a + pointer to an internal static buffer is returned .SH Return value - filename if filename was not NULL. Otherwise a pointer to an internal static buffer - is returned. If no suitable filename can be generated, NULL is returned. + filename if filename was not a null pointer. Otherwise a pointer to an internal + static buffer is returned. If no suitable filename can be generated, a null pointer + is returned. .SH Notes @@ -27,30 +31,29 @@ that a file with that name is created by another process between the moment std::tmpnam returns and the moment this program attempts to use the returned name to create a file. The standard function std::tmpfile and the POSIX function mkstemp do - not have this problem. + not have this problem (creating a unique directory using only the standard C library + still requires the use of tmpnam). - POSIX systems additionally define the similarly named function tempnam(), which - offers the choice of a directory (which defaults to the optionally defined macro - P_tmpdir) + POSIX systems additionally define the similarly named function tempnam, which offers + the choice of a directory (which defaults to the optionally defined macro P_tmpdir). .SH Example - + // Run this code - #include #include + #include #include - + int main() { std::string name1 = std::tmpnam(nullptr); std::cout << "temporary file name: " << name1 << '\\n'; - + char name2[L_tmpnam]; - if (std::tmpnam(name2)) { + if (std::tmpnam(name2)) std::cout << "temporary file name: " << name2 << '\\n'; - } } .SH Possible output: @@ -60,7 +63,9 @@ .SH See also - tmpfile creates and opens a temporary, auto-removing file - \fI(function)\fP + tmpfile creates and opens a temporary, auto-removing file + \fI(function)\fP + temp_directory_path returns a directory suitable for temporary files + \fI(C++17)\fP \fI(function)\fP C documentation for tmpnam diff --git a/man/std::to_address.3 b/man/std::to_address.3 new file mode 100644 index 000000000..311ea5170 --- /dev/null +++ b/man/std::to_address.3 @@ -0,0 +1,109 @@ +.TH std::to_address 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_address \- std::to_address + +.SH Synopsis + Defined in header + template< class Ptr > \fB(1)\fP \fI(since C++20)\fP + constexpr auto to_address( const Ptr& p ) noexcept; + template< class T > \fB(2)\fP \fI(since C++20)\fP + constexpr T* to_address( T* p ) noexcept; + + Obtain the address represented by p without forming a reference to the object + pointed to by p. + + 1) Fancy pointer overload: If the expression std::pointer_traits::to_address(p) + is well-formed, returns the result of that expression. Otherwise, returns + std::to_address(p.operator->()). + 2) Raw pointer overload: If T is a function type, the program is ill-formed. + Otherwise, returns p unmodified. + +.SH Parameters + + p - fancy or raw pointer + +.SH Return value + + Raw pointer that represents the same address as p does. + +.SH Possible implementation + + template + constexpr T* to_address(T* p) noexcept + { + static_assert(!std::is_function_v); + return p; + } + + template + constexpr auto to_address(const T& p) noexcept + { + if constexpr (requires{ std::pointer_traits::to_address(p); }) + return std::pointer_traits::to_address(p); + else + return std::to_address(p.operator->()); + } + +.SH Notes + + std::to_address can be used even when p does not reference storage that has an + object constructed in it, in which case std::addressof(*p) cannot be used because + there is no valid object for the parameter of std::addressof to bind to. + + The fancy pointer overload of std::to_address inspects the std::pointer_traits + specialization. If instantiating that specialization is itself ill-formed (typically + because element_type cannot be defined), that results in a hard error outside the + immediate context and renders the program ill-formed. + + std::to_address may additionally be used on iterators that satisfy + std::contiguous_iterator. + + Feature-test macro Value Std Feature + __cpp_lib_to_address 201711L (C++20) Utility to convert a pointer to a raw pointer + (std::to_address) + +.SH Example + + +// Run this code + + #include + + template + auto allocator_new(A& a) + { + auto p = a.allocate(1); + try + { + std::allocator_traits::construct(a, std::to_address(p)); + } + catch (...) + { + a.deallocate(p, 1); + throw; + } + return p; + } + + template + void allocator_delete(A& a, typename std::allocator_traits::pointer p) + { + std::allocator_traits::destroy(a, std::to_address(p)); + a.deallocate(p, 1); + } + + int main() + { + std::allocator a; + auto p = allocator_new(a); + allocator_delete(a, p); + } + +.SH See also + + pointer_traits provides information about pointer-like types + \fI(C++11)\fP \fI(class template)\fP + obtains a raw pointer from a fancy pointer (inverse of + to_address pointer_to) + \fB[static]\fP (C++20)(optional) \fI\fI(public static member\fP function of\fP + std::pointer_traits) diff --git a/man/std::to_array.3 b/man/std::to_array.3 new file mode 100644 index 000000000..253310509 --- /dev/null +++ b/man/std::to_array.3 @@ -0,0 +1,143 @@ +.TH std::to_array 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_array \- std::to_array + +.SH Synopsis + Defined in header + template< class T, std::size_t N > + constexpr std::array, N> to_array( T (&a)[N] \fB(1)\fP \fI(since C++20)\fP + ); + template< class T, std::size_t N > + constexpr std::array, N> to_array( T (&&a)[N] \fB(2)\fP \fI(since C++20)\fP + ); + + Creates a std::array from the one dimensional built-in array a. Copying or moving + multidimensional built-in array is not supported. + + 1) For every i in 0, ..., N - 1, copy-initializes result's correspond element with + a[i]. This overload is ill-formed when std::is_constructible_v is false. + 2) For every i in 0, ..., N - 1, move-initializes result's correspond element with + std::move(a[i]). This overload is ill-formed when std::is_move_constructible_v is + false. + + Both overloads are ill-formed when std::is_array_v is true. + +.SH Parameters + + a - the built-in array to be converted the std::array +.SH Type requirements + - + T must meet the requirements of CopyConstructible in order to use overload \fB(1)\fP. + - + T must meet the requirements of MoveConstructible in order to use overload \fB(2)\fP. + +.SH Return value + + 1) std::array, N>{ a[0], ..., a[N - 1] } + 2) std::array, N>{ std::move(a[0]), ..., std::move(a[N - 1]) } + +.SH Notes + + There are some occasions where class template argument deduction of std::array + cannot be used while to_array is available: + + * to_array can be used when the element type of the std::array is manually + specified and the length is deduced, which is preferable when implicit + conversion is wanted. + * to_array can copy a string literal, while class template argument deduction + constructs a std::array of a single pointer to its first character. + + std::to_array({3, 4}); // OK: implicit conversion + // std::array{3, 4}; // error: too few template arguments + std::to_array("foo"); // creates std::array{'f', 'o', 'o', '\\0'} + std::array{"foo"}; // creates std::array{"foo"} + + Feature-test macro Value Std Feature + __cpp_lib_to_array 201907L (C++20) std::to_array + +.SH Possible implementation + + to_array \fB(1)\fP + namespace detail + { + template + constexpr std::array, N> + to_array_impl(T (&a)[N], std::index_sequence) + { + return {{a[I]...}}; + } + } + + template + constexpr std::array, N> to_array(T (&a)[N]) + { + return detail::to_array_impl(a, std::make_index_sequence{}); + } + to_array \fB(2)\fP + namespace detail + { + template + constexpr std::array, N> + to_array_impl(T (&&a)[N], std::index_sequence) + { + return {{std::move(a[I])...}}; + } + } + + template + constexpr std::array, N> to_array(T (&&a)[N]) + { + return detail::to_array_impl(std::move(a), std::make_index_sequence{}); + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // creates a constexpr array of string_view's + constexpr auto w1n = std::to_array({ + "Mary", "Patricia", "Linda", "Barbara", "Elizabeth", "Jennifer" + }); + static_assert(std::is_same_v>); + static_assert(w1n.size() == 6 and w1n[5] == "Jennifer"); + + int main() + { + // copies a string literal + auto a1 = std::to_array("foo"); + static_assert(a1.size() == 4); + + // deduces both element type and length + auto a2 = std::to_array({0, 2, 1, 3}); + static_assert(std::is_same_v>); + + // deduces length with element type specified + // implicit conversion happens + auto a3 = std::to_array({0, 1, 3}); + static_assert(std::is_same_v>); + + auto a4 = std::to_array>( + {{3, 0.0f}, {4, 0.1f}, {4, 0.1e23f}}); + static_assert(a4.size() == 3); + + // creates a non-copyable std::array + auto a5 = std::to_array({std::make_unique(3)}); + static_assert(a5.size() == 1); + + // error: copying multidimensional arrays is not supported + // char s[2][6] = {"nice", "thing"}; + // auto a6 = std::to_array(s); + } + +.SH See also + + make_array creates a std::array object whose size and optionally + (library fundamentals TS v2) element type are deduced from the arguments + \fI(function template)\fP diff --git a/man/std::to_chars.3 b/man/std::to_chars.3 new file mode 100644 index 000000000..e1680204f --- /dev/null +++ b/man/std::to_chars.3 @@ -0,0 +1,186 @@ +.TH std::to_chars 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_chars \- std::to_chars + +.SH Synopsis + Defined in header + std::to_chars_result + \fI(since C++17)\fP + to_chars( char* first, char* last, \fB(1)\fP (constexpr since C++23) + + /* integer-type */ value, int base = 10 ); + std::to_chars_result \fB(2)\fP \fI(since C++17)\fP + to_chars( char*, char*, bool, int = 10 ) = delete; + std::to_chars_result + to_chars( char* first, char* last, /* \fB(3)\fP \fI(since C++17)\fP + floating-point-type */ value ); + std::to_chars_result + + to_chars( char* first, char* last, /* \fB(4)\fP \fI(since C++17)\fP + floating-point-type */ value, + + std::chars_format fmt ); + std::to_chars_result + + to_chars( char* first, char* last, /* \fB(5)\fP \fI(since C++17)\fP + floating-point-type */ value, + + std::chars_format fmt, int precision ); + + Converts value into a character string by successively filling the range + [first, last), where [first, last) is required to be a valid range. + + 1) Integer formatters: value is converted to a string of digits in the given base + (with no redundant leading zeroes). Digits in the range 10..35 (inclusive) are + represented as lowercase characters a..z. If value is less than zero, the + representation starts with a minus sign. The library provides overloads for all + cv-unqualified + (since C++23) signed and unsigned integer types and for the type char as the type of + the parameter value. + 2) Overload for bool is deleted. std::to_chars rejects argument of type bool because + the result would be "0"/"1" but not "false"/"true" if it is permitted. + 3) value is converted to a string as if by std::printf in the default ("C") locale. + The conversion specifier is f or e (resolving in favor of f in case of a tie), + chosen according to the requirement for a shortest representation: the string + representation consists of the smallest number of characters such that there is at + least one digit before the radix point (if present) and parsing the representation + using the corresponding std::from_chars function recovers value exactly. If there + are several such representations, one with the smallest difference to value is + chosen, resolving any remaining ties using rounding according to + std::round_to_nearest. The library provides overloads for all cv-unqualified + standard + (until C++23) floating-point types as the type of the parameter value. + 4) Same as \fB(3)\fP, but the conversion specified for the as-if printf is f if fmt is + std::chars_format::fixed, e if fmt is std::chars_format::scientific, a (but without + leading "0x" in the result) if fmt is std::chars_format::hex, and g if fmt is + chars_format::general. The library provides overloads for all cv-unqualified + standard + (until C++23) floating-point types as the type of the parameter value. + 5) Same as \fB(4)\fP, except the precision is specified by the parameter precision rather + than by the shortest representation requirement. The library provides overloads for + all cv-unqualified + standard + (until C++23) floating-point types as the type of the parameter value. + +.SH Parameters + + first, last - character range to write to + value - the value to convert to its string representation + base - integer base to use: a value between 2 and 36 (inclusive). + fmt - floating-point formatting to use, a bitmask of type std::chars_format + precision - floating-point precision to use + +.SH Return value + + On success, returns a value of type std::to_chars_result such that ec equals + value-initialized std::errc and ptr is the one-past-the-end pointer of the + characters written. Note that the string is not NUL-terminated. + + On error, returns a value of type std::to_chars_result holding + std::errc::value_too_large in ec, a copy of the value last in ptr, and leaves the + contents of the range [first, last) in unspecified state. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + Unlike other formatting functions in C++ and C libraries, std::to_chars is + locale-independent, non-allocating, and non-throwing. Only a small subset of + formatting policies used by other libraries (such as std::sprintf) is provided. This + is intended to allow the fastest possible implementation that is useful in common + high-throughput contexts such as text-based interchange (JSON or XML). + + The guarantee that std::from_chars can recover every floating-point value formatted + by std::to_chars exactly is only provided if both functions are from the same + implementation. + + It is required to explicitly cast a bool value to another integer type if it is + wanted to format the value as "0"/"1". + + Feature-test macro Value Std Feature + 201611L \fI(C++17)\fP Elementary string conversions + __cpp_lib_to_chars (std::to_chars, std::from_chars) + 202306L (C++26) Testing for success or failure of + functions + Add constexpr modifiers to + __cpp_lib_constexpr_charconv 202207L (C++23) std::to_chars and std::from_chars + overloads \fB(1)\fP for integral types + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void show_to_chars(auto... format_args) + { + std::array str; + + #if __cpp_lib_to_chars >= 202306L + // use C++26 operator bool() for error checking + if (auto res = std::to_chars(str.data(), str.data() + str.size(), format_args...)) + std::cout << std::string_view(str.data(), res.ptr) << '\\n'; + else + std::cout << std::make_error_code(res.ec).message() << '\\n'; + #else + if (auto [ptr, ec] + = std::to_chars(str.data(), str.data() + str.size(), format_args...); + ec == std::errc()) + std::cout << std::string_view(str.data(), ptr) << '\\n'; + else + std::cout << std::make_error_code(ec).message() << '\\n'; + #endif + } + + int main() + { + show_to_chars(42); + show_to_chars(+3.14159F); + show_to_chars(-3.14159, std::chars_format::fixed); + show_to_chars(-3.14159, std::chars_format::scientific, 3); + show_to_chars(3.1415926535, std::chars_format::fixed, 10); + } + +.SH Possible output: + + 42 + 3.14159 + -3.14159 + -3.142e+00 + Value too large for defined data type + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2955 C++17 this function was in and used moved to and + std::error_code uses std::errc + LWG 3266 C++17 bool argument was accepted and promoted rejected by a deleted + to int overload + LWG 3373 C++17 std::to_chars_result might have additional members are + additional members disallowed + +.SH See also + + to_chars_result the return type of std::to_chars + \fI(C++17)\fP \fI(class)\fP + from_chars converts a character sequence to an integer or floating-point value + \fI(C++17)\fP \fI(function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + printf + fprintf prints formatted output to stdout, a file stream or a buffer + sprintf \fI(function)\fP + snprintf + \fI(C++11)\fP + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::to_chars_result.3 b/man/std::to_chars_result.3 new file mode 100644 index 000000000..2a4bb7826 --- /dev/null +++ b/man/std::to_chars_result.3 @@ -0,0 +1,71 @@ +.TH std::to_chars_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_chars_result \- std::to_chars_result + +.SH Synopsis + Defined in header + struct to_chars_result; \fI(since C++17)\fP + + std::to_chars_result is the return type of std::to_chars. It has no base classes, + and only has the following members. + +.SH Notes + + Feature-test macro Value Std Feature + 201611L \fI(C++17)\fP Elementary string conversions (std::to_chars, + __cpp_lib_to_chars std::from_chars) + 202306L (C++26) Testing for success or failure of + functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void show_to_chars(auto... format_args) + { + std::array str; + + #if __cpp_lib_to_chars >= 202306L + // use C++26 operator bool() for error checking + if (auto res = std::to_chars(str.data(), str.data() + str.size(), format_args...)) + std::cout << std::string_view(str.data(), res.ptr) << '\\n'; + else + std::cout << std::make_error_code(res.ec).message() << '\\n'; + #else + if (auto [ptr, ec] + = std::to_chars(str.data(), str.data() + str.size(), format_args...); + ec == std::errc()) + std::cout << std::string_view(str.data(), ptr) << '\\n'; + else + std::cout << std::make_error_code(ec).message() << '\\n'; + #endif + } + + int main() + { + show_to_chars(42); + show_to_chars(+3.14159F); + show_to_chars(-3.14159, std::chars_format::fixed); + show_to_chars(-3.14159, std::chars_format::scientific, 3); + show_to_chars(3.1415926535, std::chars_format::fixed, 10); + } + +.SH Possible output: + + 42 + 3.14159 + -3.14159 + -3.142e+00 + Value too large for defined data type + +.SH See also + + to_chars converts an integer or floating-point value to a character sequence + \fI(C++17)\fP \fI(function)\fP diff --git a/man/std::to_string.3 b/man/std::to_string.3 index 39c75c354..55f232151 100644 --- a/man/std::to_string.3 +++ b/man/std::to_string.3 @@ -1,79 +1,67 @@ -.TH std::to_string 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::to_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_string \- std::to_string + .SH Synopsis - Defined in header - std::string to_string( int value ); \fB(1)\fP \fI(since C++11)\fP - std::string to_string( long value ); \fB(2)\fP \fI(since C++11)\fP - std::string to_string( long long value ); \fB(3)\fP \fI(since C++11)\fP - std::string to_string( unsigned value ); \fB(4)\fP \fI(since C++11)\fP - std::string to_string( unsigned long value ); \fB(5)\fP \fI(since C++11)\fP - std::string to_string( unsigned long long value ); \fB(6)\fP \fI(since C++11)\fP - std::string to_string( float value ); \fB(7)\fP \fI(since C++11)\fP - std::string to_string( double value ); \fB(8)\fP \fI(since C++11)\fP - std::string to_string( long double value ); \fB(9)\fP \fI(since C++11)\fP - - Converts a numeric value to std::string. - - 1) Converts a signed decimal integer to a string with the same content as what - std::sprintf(buf, "%d", value) would produce for sufficiently large buf. - 2) Converts a signed decimal integer to a string with the same content as what - std::sprintf(buf, "%ld", value) would produce for sufficiently large buf.. - 3) Converts a signed decimal integer to a string with the same content as what - std::sprintf(buf, "%lld", value) would produce for sufficiently large buf. - 4) Converts an unsigned decimal integer to a string with the same content as what - std::sprintf(buf, "%u", value) would produce for sufficiently large buf. - 5) Converts an unsigned decimal integer to a string with the same content as what - std::sprintf(buf, "%lu", value) would produce for sufficiently large buf. - 6) Converts an unsigned decimal integer to a string with the same content as what - std::sprintf(buf, "%llu", value) would produce for sufficiently large buf. - 7,8) Converts a floating point value to a string with the same content as what - std::sprintf(buf, "%f", value) would produce for sufficiently large buf. - 9) Converts a floating point value to a string with the same content as what - std::sprintf(buf, "%Lf", value) would produce for sufficiently large buf. + Defined in header + std::string to_string( const std::stacktrace_entry& f ); (since C++23) + + Returns a string with a description of f. + + The standard recommends that the description should provide information about the + contained evaluation, including information from f.source_file() and + f.source_line(). .SH Parameters - value - a numeric value to convert + f - a stacktrace_entry whose description is to be returned .SH Return value - a string holding the converted value + A string with a description of f. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + Custom allocators support for this function is not provided, because the + implementations usually require platform specific allocations, system calls and a + lot of CPU intensive work, while a custom allocator does not provide benefits for + this function as the platform specific operations take an order of magnitude more + time than the allocation. .SH Example - + // Run this code - #include + #include #include - + #include + int main() { - double f = 23.43; - std::string f_str = std::to_string(f); - std::cout << f_str << '\\n'; + auto st = std::stacktrace::current(); + std::cout << + "Description of an empty stacktrace entry:\\n" + + std::to_string(std::stacktrace_entry{}) << '\\n'; + if (st.size() > 0) { + std::cout << + "Description of a non-empty stacktrace entry:\\n" + + std::to_string(st[0]) << '\\n'; + } } -.SH Output: +.SH Possible output: + + Description of an empty stacktrace entry: - 23.430000 + Description of a non-empty stacktrace entry: + 0x0000000000402DE9 in ./prog.exe .SH See also - to_wstring converts an integral or floating point value to wstring - \fI(C++11)\fP \fI(function)\fP - stoul - stoull converts a string to an unsigned integer - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - stoi - stol - stoll converts a string to a signed integer - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP - stof - stod - stold converts a string to a floating point value - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP + to_string returns a string with a description of the basic_stacktrace + (C++23) \fI(function template)\fP diff --git a/man/std::to_underlying.3 b/man/std::to_underlying.3 new file mode 100644 index 000000000..60b6792db --- /dev/null +++ b/man/std::to_underlying.3 @@ -0,0 +1,82 @@ +.TH std::to_underlying 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_underlying \- std::to_underlying + +.SH Synopsis + Defined in header + template< class Enum > + constexpr std::underlying_type_t to_underlying( Enum e ) (since C++23) + noexcept; + + Converts an enumeration to its underlying type. Equivalent to return + static_cast>(e);. + +.SH Parameters + + e - enumeration value to convert + +.SH Return value + + The integer value of the underlying type of Enum, converted from e. + +.SH Notes + + std::to_underlying can be used to avoid converting an enumeration to an integer type + other than its underlying type. + + Feature-test macro Value Std Feature + __cpp_lib_to_underlying 202102L (C++23) std::to_underlying + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + enum class E1 : char { e }; + static_assert(std::is_same_v); + + enum struct E2 : long { e }; + static_assert(std::is_same_v); + + enum E3 : unsigned { e }; + static_assert(std::is_same_v); + + int main() + { + enum class ColorMask : std::uint32_t + { + red = 0xFF, green = (red << 8), blue = (green << 8), alpha = (blue << 8) + }; + + std::cout << std::hex << std::uppercase << std::setfill('0') + << std::setw(8) << std::to_underlying(ColorMask::red) << '\\n' + << std::setw(8) << std::to_underlying(ColorMask::green) << '\\n' + << std::setw(8) << std::to_underlying(ColorMask::blue) << '\\n' + << std::setw(8) << std::to_underlying(ColorMask::alpha) << '\\n'; + + // std::underlying_type_t x = ColorMask::alpha; // Error: no known conversion + [[maybe_unused]] + std::underlying_type_t y = std::to_underlying(ColorMask::alpha); // OK + } + +.SH Output: + + 000000FF + 0000FF00 + 00FF0000 + FF000000 + +.SH See also + + underlying_type obtains the underlying integer type for a given enumeration type + \fI(C++11)\fP \fI(class template)\fP + is_enum checks if a type is an enumeration type + \fI(C++11)\fP \fI(class template)\fP + is_scoped_enum checks if a type is a scoped enumeration type + (C++23) \fI(class template)\fP diff --git a/man/std::to_wstring.3 b/man/std::to_wstring.3 index 208c2eef3..047b6d40c 100644 --- a/man/std::to_wstring.3 +++ b/man/std::to_wstring.3 @@ -1,4 +1,7 @@ -.TH std::to_wstring 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::to_wstring 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::to_wstring \- std::to_wstring + .SH Synopsis Defined in header std::wstring to_wstring( int value ); \fB(1)\fP \fI(since C++11)\fP @@ -13,23 +16,27 @@ Converts a numeric value to std::wstring. - 1) Converts a signed decimal integer to a wide string with the same content as what - std::swprintf(buf, sz, L"%d", value) would produce for sufficiently large buf. - 2) Converts a signed decimal integer to a wide string with the same content as what - std::swprintf(buf, sz, L"%ld", value) would produce for sufficiently large buf.. - 3) Converts a signed decimal integer to a wide string with the same content as what - std::swprintf(buf, sz, L"%lld", value) would produce for sufficiently large buf. - 4) Converts an unsigned decimal integer to a wide string with the same content as - what std::swprintf(buf, sz, L"%u", value) would produce for sufficiently large buf. - 5) Converts an unsigned decimal integer to a wide string with the same content as - what std::swprintf(buf, sz, L"%lu", value) would produce for sufficiently large buf. - 6) Converts an unsigned decimal integer to a wide string with the same content as - what std::swprintf(buf, sz, L"%llu", value) would produce for sufficiently large - buf. - 7,8) Converts a floating point value to a wide string with the same content as what - std::swprintf(buf, sz, L"%f", value) would produce for sufficiently large buf. - 9) Converts a floating point value to a wide string with the same content as what - std::swprintf(buf, sz, L"%Lf", value) would produce for sufficiently large buf. + Let buf be an internal to the conversion functions buffer, + sufficiently large to contain the result of conversion. + + 1) Converts a signed decimal integer to a wide string as if by + std::swprintf(buf, sz, L"%d", value). + 2) Converts a signed decimal integer to a wide string as if by + std::swprintf(buf, sz, L"%ld", value). + 3) Converts a signed decimal integer to a wide string as if by + std::swprintf(buf, sz, L"%lld", value). + 4) Converts an unsigned decimal integer to a wide string as if by (until C++26) + std::swprintf(buf, sz, L"%u", value). + 5) Converts an unsigned decimal integer to a wide string as if by + std::swprintf(buf, sz, L"%lu", value). + 6) Converts an unsigned decimal integer to a wide string as if by + std::swprintf(buf, sz, L"%llu", value). + 7,8) Converts a floating point value to a wide string as if by + std::swprintf(buf, sz, L"%f", value). + 9) Converts a floating point value to a wide string as if by + std::swprintf(buf, sz, L"%Lf", value). + 1-9) Converts a numeric value to a wide string as if by (since C++26) + std::format(L"{}", value). .SH Parameters @@ -37,27 +44,45 @@ .SH Return value - a wide string holding the converted value + A wide string holding the converted value. + +.SH Exceptions + + May throw std::bad_alloc from the std::wstring constructor. .SH Example - + // Run this code - #include #include - - int main() { - double f = 23.43; - std::wstring f_str = std::to_wstring(f); - std::wcout << f_str; + #include + + int main() + { + for (const double f : {23.43, 1e-9, 1e40, 1e-40, 123456789.0}) + std::wcout << "std::wcout: " << f << '\\n' + << "to_wstring: " << std::to_wstring(f) << "\\n\\n"; } .SH Output: - 23.430000 + std::wcout: 23.43 + to_wstring: 23.430000 + + std::wcout: 1e-09 + to_wstring: 0.000000 + + std::wcout: 1e+40 + to_wstring: 10000000000000000303786028427003666890752.000000 + + std::wcout: 1e-40 + to_wstring: 0.000000 + + std::wcout: 1.23457e+08 + to_wstring: 123456789.000000 .SH See also - to_string converts an integral or floating point value to string - \fI(C++11)\fP \fI(function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::tolower(std::locale).3 b/man/std::tolower(std::locale).3 index 679a6495c..0b7ef10bb 100644 --- a/man/std::tolower(std::locale).3 +++ b/man/std::tolower(std::locale).3 @@ -1,8 +1,11 @@ -.TH std::tolower(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tolower(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tolower(std::locale) \- std::tolower(std::locale) + .SH Synopsis Defined in header - template< class charT > - charT tolower( charT ch, const locale& loc ); + template< class CharT > + CharT tolower( CharT ch, const locale& loc ); Converts the character ch to lowercase if possible, using the conversion rules specified by the given locale's std::ctype facet. @@ -26,34 +29,35 @@ .SH Possible implementation - template< class charT > - charT tolower( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).tolower(ch); + template + CharT tolower(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).tolower(ch); } .SH Example - + // Run this code - #include #include + #include #include - + int main() { wchar_t c = L'\\u0190'; // Latin capital open E ('Ɛ') - + std::cout << std::hex << std::showbase; - + std::cout << "in the default locale, tolower(" << (std::wint_t)c << ") = " - << std::tolower(c, std::locale()) << '\\n'; - + << (std::wint_t)std::tolower(c, std::locale()) << '\\n'; + std::cout << "in Unicode locale, tolower(" << (std::wint_t)c << ") = " - << std::tolower(c, std::locale("en_US.utf8")) << '\\n'; + << (std::wint_t)std::tolower(c, std::locale("en_US.utf8")) << '\\n'; } -.SH Output: +.SH Possible output: in the default locale, tolower(0x190) = 0x190 in Unicode locale, tolower(0x190) = 0x25b @@ -62,8 +66,8 @@ converts a character to uppercase using the ctype facet of a toupper(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP tolower converts a character to lowercase - \fI(function)\fP + \fI(function)\fP towlower converts a wide character to lowercase - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::tolower.3 b/man/std::tolower.3 index a86df6ce9..747d04c4c 100644 --- a/man/std::tolower.3 +++ b/man/std::tolower.3 @@ -1,4 +1,7 @@ -.TH std::tolower 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tolower 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tolower \- std::tolower + .SH Synopsis Defined in header int tolower( int ch ); @@ -20,20 +23,47 @@ Lowercase version of ch or unmodified ch if no lowercase version is listed in the current C locale. +.SH Notes + + Like all other functions from , the behavior of std::tolower is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + char my_tolower(char ch) + { + return static_cast(std::tolower(static_cast(ch))); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + std::string str_tolower(std::string s) + { + std::transform(s.begin(), s.end(), s.begin(), + // static_cast(std::tolower) // wrong + // [](int c){ return std::tolower(c); } // wrong + // [](char c){ return std::tolower(c); } // wrong + [](unsigned char c){ return std::tolower(c); } // correct + ); + return s; + } + .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xb4'; // the character Ž in ISO-8859-15 // but ´ (acute accent) in ISO-8859-1 - + std::setlocale(LC_ALL, "en_US.iso88591"); std::cout << std::hex << std::showbase; std::cout << "in iso8859-1, tolower('0xb4') gives " @@ -43,7 +73,7 @@ << std::tolower(c) << '\\n'; } -.SH Output: +.SH Possible output: in iso8859-1, tolower('0xb4') gives 0xb4 in iso8859-15, tolower('0xb4') gives 0xb8 @@ -51,11 +81,11 @@ .SH See also toupper converts a character to uppercase - \fI(function)\fP + \fI(function)\fP converts a character to lowercase using the ctype facet of a tolower(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP towlower converts a wide character to lowercase - \fI(function)\fP + \fI(function)\fP C documentation for tolower diff --git a/man/std::totally_ordered,std::totally_ordered_with.3 b/man/std::totally_ordered,std::totally_ordered_with.3 new file mode 100644 index 000000000..92926977f --- /dev/null +++ b/man/std::totally_ordered,std::totally_ordered_with.3 @@ -0,0 +1,57 @@ +.TH std::totally_ordered,std::totally_ordered_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::totally_ordered,std::totally_ordered_with \- std::totally_ordered,std::totally_ordered_with + +.SH Synopsis + Defined in header + template< class T > + + concept totally_ordered = \fB(1)\fP \fI(since C++20)\fP + + std::equality_comparable && __PartiallyOrderedWith; + template< class T, class U > + + concept totally_ordered_with = + std::totally_ordered && + std::totally_ordered && + std::equality_comparable_with && \fB(2)\fP \fI(since C++20)\fP + std::totally_ordered< + std::common_reference_t< + const std::remove_reference_t&, + const std::remove_reference_t&>> && + + __PartiallyOrderedWith; + template< class T, class U > + + concept __PartiallyOrderedWith = + requires(const std::remove_reference_t& t, + const std::remove_reference_t& u) { + { t < u } -> boolean-testable; + { t > u } -> boolean-testable; + { t <= u } -> boolean-testable; \fB(3)\fP (exposition only*) + { t >= u } -> boolean-testable; + { u < t } -> boolean-testable; + { u > t } -> boolean-testable; + { u <= t } -> boolean-testable; + { u >= t } -> boolean-testable; + + }; + + 1) The concept std::totally_ordered specifies that the comparison operators + ==,!=,<,>,<=,>= on a type yield results consistent with a strict total order on the + type. + 2) The concept std::totally_ordered_with specifies that the comparison operators + ==,!=,<,>,<=,>= on (possibly mixed) T and U operands yield results consistent with a + strict total order. Comparing mixed operands yields results equivalent to comparing + the operands converted to their common type. + 3) The exposition-only concept __PartiallyOrderedWith specifies that a value of type + T and a value of type U can be compared in a partial order with each other (in + either order) using <, >, <=, and >=, and the results of the comparisons are + consistent. + +.SH See also + + three_way_comparable specifies that operator <=> produces consistent result on + three_way_comparable_with given types + (C++20) (concept) diff --git a/man/std::toupper(std::locale).3 b/man/std::toupper(std::locale).3 index 238870de8..d052e205c 100644 --- a/man/std::toupper(std::locale).3 +++ b/man/std::toupper(std::locale).3 @@ -1,8 +1,11 @@ -.TH std::toupper(std::locale) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::toupper(std::locale) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::toupper(std::locale) \- std::toupper(std::locale) + .SH Synopsis Defined in header - template< class charT > - charT toupper( charT ch, const locale& loc ); + template< class CharT > + CharT toupper( CharT ch, const locale& loc ); Converts the character ch to uppercase if possible, using the conversion rules specified by the given locale's std::ctype facet. @@ -14,8 +17,8 @@ .SH Return value - Returns the uppercase form of ch if one is listed in the locale, otherwise return ch - unchanged. + Returns the uppercase form of ch if one is listed in the locale, otherwise returns + ch unchanged. .SH Notes @@ -25,34 +28,35 @@ .SH Possible implementation - template< class charT > - charT toupper( charT ch, const std::locale& loc ) { - return std::use_facet>(loc).toupper(ch); + template + CharT toupper(CharT ch, const std::locale& loc) + { + return std::use_facet>(loc).toupper(ch); } .SH Example - + // Run this code - #include #include + #include #include - + int main() { wchar_t c = L'\\u017f'; // Latin small letter Long S ('ſ') - + std::cout << std::hex << std::showbase; - + std::cout << "in the default locale, toupper(" << (std::wint_t)c << ") = " - << std::toupper(c, std::locale()) << '\\n'; - + << (std::wint_t)std::toupper(c, std::locale()) << '\\n'; + std::cout << "in Unicode locale, toupper(" << (std::wint_t)c << ") = " - << std::toupper(c, std::locale("en_US.utf8")) << '\\n'; + << (std::wint_t)std::toupper(c, std::locale("en_US.utf8")) << '\\n'; } -.SH Output: +.SH Possible output: in the default locale, toupper(0x17f) = 0x17f in Unicode locale, toupper(0x17f) = 0x53 @@ -61,8 +65,8 @@ converts a character to lowercase using the ctype facet of a tolower(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP toupper converts a character to uppercase - \fI(function)\fP + \fI(function)\fP towupper converts a wide character to uppercase - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::toupper.3 b/man/std::toupper.3 index 2cd8dc0fa..7cc5b29a0 100644 --- a/man/std::toupper.3 +++ b/man/std::toupper.3 @@ -1,4 +1,7 @@ -.TH std::toupper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::toupper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::toupper \- std::toupper + .SH Synopsis Defined in header int toupper( int ch ); @@ -20,20 +23,47 @@ Converted character or ch if no uppercase version is defined by the current C locale. +.SH Notes + + Like all other functions from , the behavior of std::toupper is undefined if + the argument's value is neither representable as unsigned char nor equal to EOF. To + use these functions safely with plain chars (or signed chars), the argument should + first be converted to unsigned char: + + char my_toupper(char ch) + { + return static_cast(std::toupper(static_cast(ch))); + } + + Similarly, they should not be directly used with standard algorithms when the + iterator's value type is char or signed char. Instead, convert the value to unsigned + char first: + + std::string str_toupper(std::string s) + { + std::transform(s.begin(), s.end(), s.begin(), + // static_cast(std::toupper) // wrong + // [](int c){ return std::toupper(c); } // wrong + // [](char c){ return std::toupper(c); } // wrong + [](unsigned char c){ return std::toupper(c); } // correct + ); + return s; + } + .SH Example - + // Run this code - #include #include #include - + #include + int main() { unsigned char c = '\\xb8'; // the character ž in ISO-8859-15 // but ¸ (cedilla) in ISO-8859-1 - + std::setlocale(LC_ALL, "en_US.iso88591"); std::cout << std::hex << std::showbase; std::cout << "in iso8859-1, toupper('0xb8') gives " << std::toupper(c) << '\\n'; @@ -49,11 +79,11 @@ .SH See also tolower converts a character to lowercase - \fI(function)\fP + \fI(function)\fP converts a character to uppercase using the ctype facet of a toupper(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP towupper converts a wide character to uppercase - \fI(function)\fP + \fI(function)\fP C documentation for toupper diff --git a/man/std::towctrans.3 b/man/std::towctrans.3 index d67d13f8e..c89355f66 100644 --- a/man/std::towctrans.3 +++ b/man/std::towctrans.3 @@ -1,11 +1,17 @@ -.TH std::towctrans 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::towctrans 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::towctrans \- std::towctrans + .SH Synopsis Defined in header - std::wint_t towctrans( std::wint_t wc, std::wctrans_t desc ); + std::wint_t towctrans( std::wint_t ch, std::wctrans_t desc ); - Maps the wide character wc using the current C locale's LC_CTYPE mapping category + Maps the wide character ch using the current C locale's LC_CTYPE mapping category identified by desc. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - the wide character to map @@ -18,24 +24,25 @@ .SH Example - The following example demonstrates katakana to hiragana character mapping + The following example demonstrates katakana to hiragana character mapping. + - // Run this code + #include #include #include #include - #include - + std::wstring tohira(std::wstring str) { - std::transform(str.begin(), str.end(), str.begin(), [](wchar_t c) { + std::transform(str.begin(), str.end(), str.begin(), [](wchar_t c) + { return std::towctrans(c, std::wctrans("tojhira")); }); return str; } - + int main() { std::setlocale(LC_ALL, "ja_JP.UTF-8"); @@ -51,6 +58,6 @@ .SH See also wctrans looks up a character mapping category in the current C locale - \fI(function)\fP + \fI(function)\fP C documentation for towctrans diff --git a/man/std::towlower.3 b/man/std::towlower.3 index 429ca7376..cc060e552 100644 --- a/man/std::towlower.3 +++ b/man/std::towlower.3 @@ -1,10 +1,16 @@ -.TH std::towlower 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::towlower 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::towlower \- std::towlower + .SH Synopsis Defined in header std::wint_t towlower( std::wint_t ch ); Converts the given wide character to lowercase, if possible. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character to be converted @@ -21,24 +27,28 @@ 'σ' and 'ς'. A call to std::towlower cannot be used to obtain the correct lowercase form in this case. + ISO 30112 specifies which pairs of Unicode characters are included in this mapping. + .SH Example - + // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u0190'; // Latin capital open E ('Ɛ') - + std::cout << std::hex << std::showbase; - std::cout << "in the default locale, towlower(" << (std::wint_t)c << ") = " + std::cout << "in the default locale, towlower(" + << static_cast(c) << ") = " << std::towlower(c) << '\\n'; std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << "in Unicode locale, towlower(" << (std::wint_t)c << ") = " + std::cout << "in Unicode locale, towlower(" + << static_cast(c) << ") = " << std::towlower(c) << '\\n'; } @@ -50,11 +60,11 @@ .SH See also towupper converts a wide character to uppercase - \fI(function)\fP + \fI(function)\fP converts a character to lowercase using the ctype facet of a tolower(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP tolower converts a character to lowercase - \fI(function)\fP + \fI(function)\fP C documentation for towlower diff --git a/man/std::towupper.3 b/man/std::towupper.3 index 69b12c05b..cf00e807b 100644 --- a/man/std::towupper.3 +++ b/man/std::towupper.3 @@ -1,10 +1,16 @@ -.TH std::towupper 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::towupper 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::towupper \- std::towupper + .SH Synopsis Defined in header std::wint_t towupper( std::wint_t ch ); Converts the given wide character to uppercase, if possible. + If the value of ch is neither representable as a wchar_t nor equal to the value of + the macro WEOF, the behavior is undefined. + .SH Parameters ch - wide character to be converted @@ -20,26 +26,31 @@ form of 'ß' is (with some exceptions) the two-character string "SS", which cannot be obtained by std::towupper. + ISO 30112 specifies which pairs of Unicode characters are included in this mapping. + .SH Example - The latin letter 'ſ' (U+017F) is the alternative lowercase form of 'S' (U+0053) + The latin letter 'ſ' (U+017F) is the alternative lowercase form of 'S' (U+0053). + - // Run this code - #include - #include #include - + #include + #include + int main() { wchar_t c = L'\\u017f'; // Latin small letter Long S ('ſ') - + std::cout << std::hex << std::showbase; - std::cout << "in the default locale, towupper(" << (std::wint_t)c << ") = " + std::cout << "in the default locale, towupper(" + << static_cast(c) << ") = " << std::towupper(c) << '\\n'; + std::setlocale(LC_ALL, "en_US.utf8"); - std::cout << "in Unicode locale, towupper(" << (std::wint_t)c << ") = " + std::cout << "in Unicode locale, towupper(" + << static_cast(c) << ") = " << std::towupper(c) << '\\n'; } @@ -51,11 +62,11 @@ .SH See also towlower converts a wide character to lowercase - \fI(function)\fP + \fI(function)\fP converts a character to uppercase using the ctype facet of a toupper(std::locale) locale - \fI(function template)\fP + \fI(function template)\fP toupper converts a character to uppercase - \fI(function)\fP + \fI(function)\fP C documentation for towupper diff --git a/man/std::transform.3 b/man/std::transform.3 index a3f267e56..5b411ae5f 100644 --- a/man/std::transform.3 +++ b/man/std::transform.3 @@ -1,29 +1,68 @@ -.TH std::transform 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::transform 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::transform \- std::transform + .SH Synopsis Defined in header - template< class InputIt, class OutputIt, class UnaryOperation > - - OutputIt transform( InputIt first1, InputIt last1, OutputIt d_first, \fB(1)\fP - - UnaryOperation unary_op ); - template< class InputIt1, class InputIt2, class OutputIt, class BinaryOperation - > - \fB(2)\fP - OutputIt transform( InputIt1 first1, InputIt1 last1, InputIt2 first2, - - OutputIt d_first, BinaryOperation binary_op ); - - std::transform applies the given function to a range and stores the result in - another range, beginning at d_first. - - In the first version unary operation unary_op is applied to the range defined by - [first1, last1). In the second version the binary operation binary_op is applied to - pairs of elements from two ranges: one defined by [first1, last1) and the other - beginning at first2. - - unary_op and binary_op must not have side effects. \fI(until C++11)\fP - unary_op and binary_op must not invalidate any iterators, including \fI(since C++11)\fP - the end iterators, or modify any elements of the ranges involved. + template< class InputIt, class OutputIt, class UnaryOp > + + OutputIt transform( InputIt first1, InputIt last1, \fB(1)\fP (constexpr since C++20) + + OutputIt d_first, UnaryOp unary_op + ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class + UnaryOp > + ForwardIt2 transform( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 + last1, + + ForwardIt2 d_first, UnaryOp + unary_op ); + template< class InputIt1, class InputIt2, + + class OutputIt, class BinaryOp > + OutputIt transform( InputIt1 first1, InputIt1 last1, \fB(3)\fP (constexpr since C++20) + InputIt2 first2, + + OutputIt d_first, BinaryOp binary_op + ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class ForwardIt3, class BinaryOp > + ForwardIt3 transform( ExecutionPolicy&& policy, + ForwardIt1 first1, ForwardIt1 \fB(4)\fP \fI(since C++17)\fP + last1, + ForwardIt2 first2, + + ForwardIt3 d_first, BinaryOp + binary_op ); + + std::transform applies the given function to the elements of the given input + range(s), and stores the result in an output range starting from d_first. + + 1) The unary operation unary_op is applied to the elements of [first1, last1). + If unary_op invalidates an iterator or modifies an element in any of the following + ranges, the behavior is undefined: + * [first1, last1]. + * The range of std::distance(first1, last1) + 1 elements starting from d_first. + 3) The binary operation binary_op is applied to pairs of elements from two ranges: + [first1, last1) and another range of std::distance(first1, last1) elements starting + from first2. + If binary_op invalidates an iterator or modifies an element in any of the following + ranges, the behavior is undefined: + * [first1, last1]. + * The range of std::distance(first1, last1) + 1 elements starting from first2. + * The range of std::distance(first1, last1) + 1 elements starting from d_first. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters @@ -31,6 +70,7 @@ first2 - the beginning of the second range of elements to transform d_first - the beginning of the destination range, may be equal to first1 or first2 + policy - the execution policy to use. See execution policy for details. unary operation function object that will be applied. The signature of the function should be equivalent to the following: @@ -38,10 +78,10 @@ Ret fun(const Type &a); unary_op - The signature does not need to have const &. - The type Type must be such that an object of type InputIt can be - dereferenced and then implicitly converted to Type. The type Ret + The type Type must be such that an object of type InputIt can be + dereferenced and then implicitly converted to Type. The type Ret must be such that an object of type OutputIt can be dereferenced and - assigned a value of type Ret. + assigned a value of type Ret. binary operation function object that will be applied. The signature of the function should be equivalent to the following: @@ -49,51 +89,64 @@ Ret fun(const Type1 &a, const Type2 &b); binary_op - The signature does not need to have const &. - The types Type1 and Type2 must be such that objects of types + The types Type1 and Type2 must be such that objects of types InputIt1 and InputIt2 can be dereferenced and then implicitly - converted to Type1 and Type2 respectively. The type Ret must be such - that an object of type OutputIt can be dereferenced and assigned a - value of type Ret. + converted to Type1 and Type2 respectively. The type Ret must be + such that an object of type OutputIt can be dereferenced and + assigned a value of type Ret. .SH Type requirements - - InputIt must meet the requirements of InputIterator. - - - InputIt1 must meet the requirements of InputIterator. + InputIt, InputIt1, InputIt2 must meet the requirements of LegacyInputIterator. - - InputIt2 must meet the requirements of InputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - OutputIt must meet the requirements of OutputIterator. + ForwardIt1, ForwardIt2, ForwardIt3 must meet the requirements of + LegacyForwardIterator. .SH Return value - Output iterator to the element past the last element transformed. + Output iterator to the element that follows the last element transformed. .SH Complexity - 1) Exactly std::distance(first1, last1) applications of unary_op - 2) Exactly std::distance(first1, last1) applications of binary_op + Given \\(\\scriptsize N\\)N as std::distance(first1, last1): + + 1,2) Exactly \\(\\scriptsize N\\)N applications of unary_op. + 3,4) Exactly \\(\\scriptsize N\\)N applications of binary_op. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - OutputIt transform(InputIt first1, InputIt last1, OutputIt d_first, - UnaryOperation unary_op) + transform \fB(1)\fP + template + constexpr //< since C++20 + OutputIt transform(InputIt first1, InputIt last1, + OutputIt d_first, UnaryOp unary_op) { - while (first1 != last1) { - *d_first++ = unary_op(*first1++); - } + for (; first1 != last1; ++d_first, ++first1) + *d_first = unary_op(*first1); + return d_first; } -.SH Second version + transform \fB(3)\fP template - OutputIt transform(InputIt first1, InputIt last1, InputIt first2, - OutputIt d_first, BinaryOperation binary_op) + class OutputIt, class BinaryOp> + constexpr //< since C++20 + OutputIt transform(InputIt1 first1, InputIt1 last1, InputIt2 first2, + OutputIt d_first, BinaryOp binary_op) { - while (first1 != last1) { - *d_first++ = binary_op(*first1++, *first2++); - } + for (; first1 != last1; ++d_first, ++first1, ++first2) + *d_first = binary_op(*first1, *first2); + return d_first; } @@ -101,34 +154,92 @@ std::transform does not guarantee in-order application of unary_op or binary_op. To apply a function to a sequence in-order or to apply a function that modifies the - elements of a sequence, use std::for_each + elements of a sequence, use std::for_each. .SH Example - The following code uses transform to convert a string to uppercase using the toupper - function: - // Run this code - #include - #include #include - #include + #include + #include #include - + #include + #include + #include + + void print_ordinals(const std::vector& ordinals) + { + std::cout << "ordinals: "; + for (unsigned ord : ordinals) + std::cout << std::setw(3) << ord << ' '; + std::cout << '\\n'; + } + + char to_uppercase(unsigned char c) + { + return std::toupper(c); + } + + void to_uppercase_inplace(char& c) + { + c = to_uppercase(c); + } + + void unary_transform_example(std::string& hello, std::string world) + { + // Transform string to uppercase in-place + + std::transform(hello.cbegin(), hello.cend(), hello.begin(), to_uppercase); + std::cout << "hello = " << std::quoted(hello) << '\\n'; + + // for_each version (see Notes above) + std::for_each(world.begin(), world.end(), to_uppercase_inplace); + std::cout << "world = " << std::quoted(world) << '\\n'; + } + + void binary_transform_example(std::vector ordinals) + { + // Transform numbers to doubled values + + print_ordinals(ordinals); + + std::transform(ordinals.cbegin(), ordinals.cend(), ordinals.cbegin(), + ordinals.begin(), std::plus<>{}); + + print_ordinals(ordinals); + } + int main() { - std::string s("hello"); - std::transform(s.begin(), s.end(), s.begin(), std::ptr_fun(std::toupper)); - std::cout << s; + std::string hello("hello"); + unary_transform_example(hello, "world"); + + std::vector ordinals; + std::copy(hello.cbegin(), hello.cend(), std::back_inserter(ordinals)); + binary_transform_example(std::move(ordinals)); } .SH Output: - HELLO + hello = "HELLO" + world = "WORLD" + ordinals: 72 69 76 76 79 + ordinals: 144 138 152 152 158 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 242 C++98 unary_op and binary_op could not have side they cannot modify the + effects ranges involved .SH See also - for_each applies a function to a range of elements - \fI(function template)\fP + for_each applies a function to a range of elements + \fI(function template)\fP + ranges::transform applies a function to a range of elements + (C++20) (niebloid) diff --git a/man/std::transform_exclusive_scan.3 b/man/std::transform_exclusive_scan.3 new file mode 100644 index 000000000..14ff5cc82 --- /dev/null +++ b/man/std::transform_exclusive_scan.3 @@ -0,0 +1,152 @@ +.TH std::transform_exclusive_scan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::transform_exclusive_scan \- std::transform_exclusive_scan + +.SH Synopsis + Defined in header + template< class InputIt, class OutputIt, class T, + + class BinaryOp, class UnaryOp > + OutputIt transform_exclusive_scan \fB(1)\fP \fI(since C++17)\fP + ( InputIt first, InputIt last, OutputIt d_first, T (constexpr since C++20) + init, + + BinaryOp binary_op, UnaryOp unary_op ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class T, + class BinaryOp, class UnaryOp > + ForwardIt2 transform_exclusive_scan \fB(2)\fP \fI(since C++17)\fP + ( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 last, ForwardIt2 + d_first, T init, + + BinaryOp binary_op, UnaryOp unary_op ); + + 1) Computes the exclusive prefix sum using op. + For each integer i in [0, std::distance(first, last)), performs the following + operations in order: + 1. Creates a sequence which is formed by init followed by the values transformed + from the elements of [first, iter) in order by unary_op, where iter is the next + i + th iterator of first. + 2. Computes the generalized noncommutative sum of the sequence over binary_op. + 3. Assigns the result to *dest, where dest is the next i + th iterator of d_first. + 2) Same as \fB(1)\fP, but executed according to policy. + This overload participates in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + The generalized noncommutative sum of a sequence of elements over a binary operation + binary_op is defined as follows: + + * If the sequence only has one element, the sum is the value of the element. + * Otherwise, performs the following operations in order: + 1. Selects any two adjacent elements elem1 and elem2 from the sequence. + 2. Calculates binary_op(elem1, elem2) and replaces the two elements in the sequence + with the result. + 3. Repeats steps 1 and 2 until there is only one element in the sequence. + + The result is non-deterministic if the binary_op is not associative (such as + floating-point addition). + + If any of the following values is not convertible to T, the program is ill-formed: + + * binary_op(init, init) + * binary_op(init, unary_op(*first)) + * binary_op(unary_op(*first), unary_op(*first)) + + If any of the following conditions is satisfied, the behavior is undefined: + + * T is not MoveConstructible. + * unary_op or binary_op modifies any element of [first, last). + * unary_op or binary_op invalidates any iterator or subrange of [first, last]. + +.SH Parameters + + first, last - the range of elements to sum + d_first - the beginning of the destination range, may be equal to first + policy - the execution policy to use. See execution policy for details. + init - the initial value + unary_op - unary FunctionObject that will be applied to each element of the input + range. The return type must be acceptable as input to binary_op. + binary_op - binary FunctionObject that will be applied in to the result of + unary_op, the results of other binary_op, and init. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + +.SH Return value + + Iterator to the element past the last element written. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) \\(\\scriptsize O(N)\\)O(N) applications of unary_op and binary_op respectively. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + unary_op is never applied to init. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector data{3, 1, 4, 1, 5, 9, 2, 6}; + + auto times_10 = [](int x) { return x * 10; }; + + std::cout << "10 times exclusive sum: "; + std::transform_exclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + 0, std::plus{}, times_10); + std::cout << "\\n10 times inclusive sum: "; + std::transform_inclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + std::plus{}, times_10); + std::cout << '\\n'; + } + +.SH Output: + + 10 times exclusive sum: 0 30 40 80 90 140 230 250 + 10 times inclusive sum: 30 40 80 90 140 230 250 310 + +.SH See also + + partial_sum computes the partial sum of a range of elements + \fI(function template)\fP + exclusive_scan similar to std::partial_sum, excludes the i^th input + \fI(C++17)\fP element from the i^th sum + \fI(function template)\fP + transform_inclusive_scan applies an invocable, then calculates inclusive scan + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::transform_inclusive_scan.3 b/man/std::transform_inclusive_scan.3 new file mode 100644 index 000000000..ef6989b2b --- /dev/null +++ b/man/std::transform_inclusive_scan.3 @@ -0,0 +1,180 @@ +.TH std::transform_inclusive_scan 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::transform_inclusive_scan \- std::transform_inclusive_scan + +.SH Synopsis + Defined in header + template< class InputIt, class OutputIt, + + class BinaryOp, class UnaryOp > \fI(since C++17)\fP + OutputIt transform_inclusive_scan \fB(1)\fP (constexpr since C++20) + ( InputIt first, InputIt last, OutputIt d_first, + + BinaryOp binary_op, UnaryOp unary_op ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class BinaryOp, class UnaryOp > + ForwardIt2 transform_inclusive_scan \fB(2)\fP \fI(since C++17)\fP + ( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 last, ForwardIt2 + d_first, + + BinaryOp binary_op, UnaryOp unary_op ); + template< class InputIt, class OutputIt, + + class BinaryOp, class UnaryOp, class T > \fI(since C++17)\fP + OutputIt transform_inclusive_scan \fB(3)\fP (constexpr since C++20) + ( InputIt first, InputIt last, OutputIt d_first, + + BinaryOp binary_op, UnaryOp unary_op, T init ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, + class BinaryOp, class UnaryOp, class T > + ForwardIt2 transform_inclusive_scan \fB(4)\fP \fI(since C++17)\fP + ( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 last, ForwardIt2 + d_first, + + BinaryOp binary_op, UnaryOp unary_op, T init ); + + 1) Computes the inclusive prefix sum using op. + For each integer i in [0, std::distance(first, last)), performs the following + operations in order: + 1. Creates a sequence which is formed by the values transformed from the elements + of [first, iter] in order by unary_op, where iter is the next i + th iterator of first. + 2. Computes the generalized noncommutative sum of the sequence over binary_op. + 3. Assigns the result to *dest, where dest is the next i + th iterator of d_first. + 3) Same as \fB(1)\fP, but each sequence created is formed by init followed by the elements + of [first, iter] in order. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + The generalized noncommutative sum of a sequence of elements over a binary operation + binary_op is defined as follows: + + * If the sequence only has one element, the sum is the value of the element. + * Otherwise, performs the following operations in order: + 1. Selects any two adjacent elements elem1 and elem2 from the sequence. + 2. Calculates binary_op(elem1, elem2) and replaces the two elements in the sequence + with the result. + 3. Repeats steps 1 and 2 until there is only one element in the sequence. + + The result is non-deterministic if the binary_op is not associative (such as + floating-point addition). + + For overloads (1,2), if binary_op(unary_op(*first), unary_op(*first)) is not + convertible to the value type of decltype(first), the program is ill-formed. + + For overloads (3,4), if any of the following values is not convertible to T, the + program is ill-formed: + + * binary_op(init, init) + * binary_op(init, unary_op(*first)) + * binary_op(unary_op(*first), unary_op(*first)) + + If any of the following conditions is satisfied, the behavior is undefined: + + * For overloads (1,2), the value type of decltype(first) is not MoveConstructible. + * For overloads (3,4), T is not MoveConstructible. + * unary_op or binary_op modifies any element of [first, last). + * unary_op or binary_op invalidates any iterator or subrange of [first, last]. + +.SH Parameters + + first, last - the range of elements to sum + d_first - the beginning of the destination range; may be equal to first + policy - the execution policy to use. See execution policy for details. + init - the initial value + unary_op - unary FunctionObject that will be applied to each element of the input + range. The return type must be acceptable as input to binary_op. + binary_op - binary FunctionObject that will be applied in to the result of + unary_op, the results of other binary_op, and init if provided +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + OutputIt must meet the requirements of LegacyOutputIterator. + - + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. + +.SH Return value + + Iterator to the element past the last element written. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1-4) \\(\\scriptsize O(N)\\)O(N) applications of unary_op and binary_op respectively. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + unary_op is never applied to init. + + The parameter init appears last, differing from std::transform_exclusive_scan, + because it is optional for this function. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector data{3, 1, 4, 1, 5, 9, 2, 6}; + + auto times_10 = [](int x) { return x * 10; }; + + std::cout << "10 times exclusive sum: "; + std::transform_exclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + 0, std::plus{}, times_10); + std::cout << "\\n10 times inclusive sum: "; + std::transform_inclusive_scan(data.begin(), data.end(), + std::ostream_iterator(std::cout, " "), + std::plus{}, times_10); + std::cout << '\\n'; + } + +.SH Output: + + 10 times exclusive sum: 0 30 40 80 90 140 230 250 + 10 times inclusive sum: 30 40 80 90 140 230 250 310 + +.SH See also + + partial_sum computes the partial sum of a range of elements + \fI(function template)\fP + applies a function to a range of elements, storing results + transform in a destination range + \fI(function template)\fP + inclusive_scan similar to std::partial_sum, includes the i^th input + \fI(C++17)\fP element in the i^th sum + \fI(function template)\fP + transform_exclusive_scan applies an invocable, then calculates exclusive scan + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::transform_reduce.3 b/man/std::transform_reduce.3 new file mode 100644 index 000000000..132460546 --- /dev/null +++ b/man/std::transform_reduce.3 @@ -0,0 +1,252 @@ +.TH std::transform_reduce 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::transform_reduce \- std::transform_reduce + +.SH Synopsis + Defined in header + template< class InputIt1, class InputIt2, class T > + \fI(since C++17)\fP + T transform_reduce( InputIt1 first1, InputIt1 last1, \fB(1)\fP (constexpr since C++20) + + InputIt2 first2, T init ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class T > + T transform_reduce( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, + + ForwardIt2 first2, T init ); + template< class InputIt1, class InputIt2, class T, + + class BinaryOp1, class BinaryOp2 > + T transform_reduce( InputIt1 first1, InputIt1 last1, \fB(3)\fP \fI(since C++17)\fP + InputIt2 first2, T init, (constexpr since C++20) + + BinaryOp1 reduce, BinaryOp2 + transform ); + template< class ExecutionPolicy, + + class ForwardIt1, class ForwardIt2, class T, + class BinaryOp1, class BinaryOp2 > + T transform_reduce( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + ForwardIt1 first1, ForwardIt1 last1, + ForwardIt2 first2, T init, + + BinaryOp1 reduce, BinaryOp2 + transform ); + template< class InputIt, class T, + + class BinaryOp, class UnaryOp > \fI(since C++17)\fP + T transform_reduce( InputIt first, InputIt last, T init, \fB(5)\fP (constexpr since C++20) + + BinaryOp reduce, UnaryOp transform + ); + template< class ExecutionPolicy, + + class ForwardIt, class T, + class BinaryOp, class UnaryOp > + T transform_reduce( ExecutionPolicy&& policy, \fB(6)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt last, T + init, + + BinaryOp reduce, UnaryOp transform + ); + + 1) Equivalent to transform_reduce(first1, last1, first2, init, + std::plus<>(), std::multiplies<>()), effectively parallelized + version of the default std::inner_product. + 3) Applies transform to each pair of elements from the ranges [first1, last1) and + the range of std::distance(first1, last1) elements starting from first2 and reduces + the results (possibly permuted and aggregated in unspecified manner) along with the + initial value init over reduce. + The result is non-deterministic if the reduce is not associative or not commutative + (such as floating-point addition). + If any of the following values is not convertible to T, the program is ill-formed: + * reduce(init, init) + * reduce(init, transform(*first1, *first2)) + * reduce(transform(*first1, *first2), init) + * reduce(transform(*first1, *first2), transform(*first1, *first2)) + Given last2 as the std::distance(first1, last1) + th next iterator of first2, if any of the following conditions is satisfied, the + behavior is undefined: + * T is not MoveConstructible. + * transform or reduce modifies any element of [first1, last1) or [first2, last2). + * transform or reduce invalidates any iterator or subrange of [first1, last1] or + [first2, last2]. + 5) Applies transform to each element in the range [first, last) and reduces the + results (possibly permuted and aggregated in unspecified manner) along with the + initial value init over reduce. + The result is non-deterministic if the reduce is not associative or not commutative + (such as floating-point addition). + If any of the following values is not convertible to T, the program is ill-formed: + * reduce(init, init) + * reduce(init, transform(*first)) + * reduce(transform(*first), init) + * reduce(transform(*first), transform(*first)) + If any of the following conditions is satisfied, the behavior is undefined: + * T is not MoveConstructible. + * transform or reduce modifies any element of [first, last). + * transform or reduce invalidates any iterator or subrange of [first, last]. + 2,4,6) Same as (1,3,5), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first1, last1 - the range of elements to be taken as the left operand of transform + first2 - the start of range of elements to be taken as the right operand of + transform + first, last - the range of elements to be taken as the operand of transform + init - the initial value of the generalized sum + policy - the execution policy to use. See execution policy for details. + reduce - binary FunctionObject that will be applied in unspecified order to + the results of transform, the results of other reduce and init. + unary or binary FunctionObject that will be applied to each element + transform - of the input range(s). The return type must be acceptable as input + to reduce. +.SH Type requirements + - + InputIt1, InputIt2, InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt1, ForwardIt2, ForwardIt must meet the requirements of + LegacyForwardIterator. + +.SH Return value + + 1,2) The generalized sum of init and values over std::plus<>(), where values are the + values transformed by std::multiplies<>(), each value is transformed from a pair of + elements from the two input ranges. + 3,4) The generalized sum of init and values over reduce, where values are the values + transformed by transform, each value is transformed from a pair of elements from the + two input ranges. + 5,6) The generalized sum of init and values over reduce, where values are the values + transformed by transform, each value is transformed from an element from the input + range. + + The generalized sum of a group of elements over an binary operation binary_op is + defined as follows: + + * If the group only has one element, the sum is the value of the element. + * Otherwise, performs the following operations in order: + 1. Takes any two elements elem1 and elem2 from the group. + 2. Calculates binary_op(elem1, elem2) and puts the result back to the group. + 3. Repeats steps 1 and 2 until there is only one element in the group. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first1, last1) (or std::distance(first, + last) for overloads (5,6)): + + 1,2) \\(\\scriptsize O(N)\\)O(N) applications of std::plus<>() and std::multiplies<>() + respectively. + 3-6) \\(\\scriptsize O(N)\\)O(N) applications of reduce and transform respectively. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Notes + + transform is never applied to init. + + If first == last or first1 == last1, init is returned, unmodified. + +.SH Example + + transform_reduce can be used to parallelize std::inner_product. Some systems may + need additional support to get advantages of parallel execution. E.g., on GNU/Linux, + the Intel TBB be installed and -ltbb option be provided to gcc/clang compiler. + + +// Run this code + + #if PARALLEL + #include + #define PAR std::execution::par, + #else + #define PAR + #endif + + #include + #include + #include + #include + #include + #include + #include + + // to parallelize non-associate accumulative operation, you'd better choose + // transform_reduce instead of reduce; e.g., a + b * b != b + a * a + void print_sum_squared(long const num) + { + std::cout.imbue(std::locale{"en_US.UTF8"}); + std::cout << "num = " << num << '\\n'; + + // create an immutable vector filled with pattern: 1,2,3,4, 1,2,3,4 ... + const std::vector v{[n = num * 4] { + std::vector v; + v.reserve(n); + std::generate_n(std::back_inserter(v), n, + [i = 0]() mutable { return 1 + i++ % 4; }); + return v; + }()}; + + auto squared_sum = [](auto sum, auto val) { return sum + val * val; }; + + auto sum1 = std::accumulate(v.cbegin(), v.cend(), 0L, squared_sum); + std::cout << "accumulate(): " << sum1 << '\\n'; + + auto sum2 = std::reduce(PAR v.cbegin(), v.cend(), 0L, squared_sum); + std::cout << "reduce(): " << sum2 << '\\n'; + + auto sum3 = std::transform_reduce(PAR v.cbegin(), v.cend(), 0L, std::plus{}, + [](auto val) { return val * val; }); + std::cout << "transform_reduce(): " << sum3 << "\\n\\n"; + } + + int main() + { + print_sum_squared(1); + print_sum_squared(1'000); + print_sum_squared(1'000'000); + } + +.SH Possible output: + + num = 1 + accumulate(): 30 + reduce(): 30 + transform_reduce(): 30 + + num = 1,000 + accumulate(): 30,000 + reduce(): -7,025,681,278,312,630,348 + transform_reduce(): 30,000 + + num = 1,000,000 + accumulate(): 30,000,000 + reduce(): -5,314,886,882,370,003,032 + transform_reduce(): 30,000,000 + + // Compile-options for parallel execution on POSIX: + // g++ -O2 -std=c++17 -Wall -Wextra -pedantic -DPARALLEL ./example.cpp -ltbb -o tr; ./tr + +.SH See also + + accumulate sums up or folds a range of elements + \fI(function template)\fP + applies a function to a range of elements, storing results in a + transform destination range + \fI(function template)\fP + reduce similar to std::accumulate, except out of order + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::trunc,std::truncf,std::truncl.3 b/man/std::trunc,std::truncf,std::truncl.3 new file mode 100644 index 000000000..2129b00f6 --- /dev/null +++ b/man/std::trunc,std::truncf,std::truncl.3 @@ -0,0 +1,137 @@ +.TH std::trunc,std::truncf,std::truncl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::trunc,std::truncf,std::truncl \- std::trunc,std::truncf,std::truncl + +.SH Synopsis + Defined in header + float trunc ( float num ); + + double trunc ( double num ); (until C++23) + + long double trunc ( long double num ); + constexpr /* floating-point-type */ (since C++23) + trunc ( /* floating-point-type */ num ); + float truncf( float num ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++23) + long double truncl( long double num ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++23) + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) (constexpr since C++23) + double trunc ( Integer num ); + + 1-3) Computes the nearest integer not greater in magnitude than num. + The library provides overloads of std::trunc for all cv-unqualified floating-point + types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + If no errors occur, the nearest integer value not greater in magnitude than num (in + other words, num rounded towards zero) is returned. + +.SH Return value + math-trunc.svg + num + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * The current rounding mode has no effect. + * If num is ±∞, it is returned, unmodified. + * If num is ±0, it is returned, unmodified. + * If num is NaN, NaN is returned. + +.SH Notes + + FE_INEXACT may be (but isn't required to be) raised when truncating a non-integer + finite value. + + The largest representable floating-point values are exact integers in all standard + floating-point formats, so this function never overflows on its own; however the + result may overflow any integer type (including std::intmax_t), when stored in an + integer variable. + + The implicit conversion from floating-point to integral types also rounds towards + zero, but is limited to the values that can be represented by the target type. + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::trunc(num) has the same effect as std::trunc(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto data = std::initializer_list + { + +2.7, -2.9, +0.7, -0.9, +0.0, 0.0, -INFINITY, +INFINITY, -NAN, +NAN + }; + + std::cout << std::showpos; + for (double const x : data) + std::cout << "trunc(" << x << ") == " << std::trunc(x) << '\\n'; + } + +.SH Possible output: + + trunc(+2.7) == +2 + trunc(-2.9) == -2 + trunc(+0.7) == +0 + trunc(-0.9) == -0 + trunc(+0) == +0 + trunc(+0) == +0 + trunc(-inf) == -inf + trunc(+inf) == +inf + trunc(-nan) == -nan + trunc(+nan) == +nan + +.SH See also + + floor + floorf nearest integer not greater than the given value + floorl \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + ceil + ceilf nearest integer not less than the given value + ceill \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + round + roundf + roundl + lround + lroundf + lroundl + llround + llroundf + llroundl nearest integer, rounding away from zero in halfway cases + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + C documentation for + trunc diff --git a/man/std::trunc.3 b/man/std::trunc.3 deleted file mode 100644 index 8bca14ae7..000000000 --- a/man/std::trunc.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH std::trunc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float trunc( float arg ); \fI(since C++11)\fP - double trunc( double arg ); \fI(since C++11)\fP - long double trunc( long double arg ); \fI(since C++11)\fP - double trunc( Integral arg ); \fI(since C++11)\fP - - Computes nearest integer not greater in magnitude than arg. - -.SH Parameters - - arg - floating point value - -.SH Return value - - Nearest integer not greater in magnitude than arg. - -.SH Return value - math-trunc.svg - Argument - -.SH Notes - - The integer value can be always represented by the given floating point type. - -.SH See also - - floor nearest integer not greater than the given value - \fI(function)\fP - ceil nearest integer not less than the given value - \fI(function)\fP - round - lround - llround nearest integer, rounding away from zero in halfway cases - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP diff --git a/man/std::try_lock.3 b/man/std::try_lock.3 index 6f6db8cd5..eaa4df015 100644 --- a/man/std::try_lock.3 +++ b/man/std::try_lock.3 @@ -1,22 +1,26 @@ -.TH std::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::try_lock \- std::try_lock + .SH Synopsis Defined in header - template< class Lockable1, class Lockable2, class LockableN... > - int try_lock( Lockable1& lock1, Lockable2& lock2, LockableN& lockn... \fI(since C++11)\fP + template< class Lockable1, class Lockable2, class... LockableN > + int try_lock( Lockable1& lock1, Lockable2& lock2, LockableN&... lockn \fI(since C++11)\fP ); Tries to lock each of the given Lockable objects lock1, lock2, ..., lockn by calling try_lock in order beginning with the first. - If a call to try_lock fails, unlock is called for any locked objects and a 0-based - index of the object that failed to lock is returned. + If a call to try_lock fails, no further call to try_lock is performed, unlock is + called for any locked objects and a 0-based index of the object that failed to lock + is returned. If a call to try_lock results in an exception, unlock is called for any locked objects before rethrowing. .SH Parameters - lock1, lock2, ... , lockn - the Lockable objects to lock + lock1, lock2, ..., lockn - the Lockable objects to lock .SH Return value @@ -27,16 +31,16 @@ The following example uses std::try_lock to periodically tally and reset counters running in separate threads. - + // Run this code + #include + #include + #include #include - #include #include - #include - #include - #include - + #include + int main() { int foo_count = 0; @@ -46,9 +50,11 @@ int overall_count = 0; bool done = false; std::mutex done_mutex; - - auto increment = [](int &counter, std::mutex &m, const char *desc) { - for (int i = 0; i < 10; ++i) { + + auto increment = [](int& counter, std::mutex& m, const char* desc) + { + for (int i = 0; i < 10; ++i) + { std::unique_lock lock(m); ++counter; std::cout << desc << ": " << counter << '\\n'; @@ -56,18 +62,21 @@ std::this_thread::sleep_for(std::chrono::seconds(1)); } }; - + std::thread increment_foo(increment, std::ref(foo_count), std::ref(foo_count_mutex), "foo"); std::thread increment_bar(increment, std::ref(bar_count), std::ref(bar_count_mutex), "bar"); - - std::thread update_overall([&]() { + + std::thread update_overall([&]() + { done_mutex.lock(); - while (!done) { + while (!done) + { done_mutex.unlock(); int result = std::try_lock(foo_count_mutex, bar_count_mutex); - if (result == -1) { + if (result == -1) + { overall_count += foo_count + bar_count; foo_count = 0; bar_count = 0; @@ -80,14 +89,14 @@ } done_mutex.unlock(); }); - + increment_foo.join(); increment_bar.join(); done_mutex.lock(); done = true; done_mutex.unlock(); update_overall.join(); - + std::cout << "Done processing\\n" << "foo: " << foo_count << '\\n' << "bar: " << bar_count << '\\n' @@ -129,4 +138,4 @@ .SH See also lock locks specified mutexes, blocks if any are unavailable - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::tuple.3 b/man/std::tuple.3 index 6f408b5b8..8f7e9e6bf 100644 --- a/man/std::tuple.3 +++ b/man/std::tuple.3 @@ -1,4 +1,7 @@ -.TH std::tuple 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple \- std::tuple + .SH Synopsis Defined in header template< class... Types > \fI(since C++11)\fP @@ -7,6 +10,12 @@ Class template std::tuple is a fixed-size collection of heterogeneous values. It is a generalization of std::pair. + If std::is_trivially_destructible::value is true for every Ti in Types, the + destructor of std::tuple is trivial. + + If a program declares an explicit or partial specialization of std::tuple, the + program is ill-formed, no diagnostic required. + .SH Template parameters Types... - the types of the elements that the tuple stores. Empty list is supported. @@ -22,82 +31,181 @@ .SH Non-member functions - creates a tuple object of the type defined by the argument - make_tuple types - \fI(function template)\fP - creates a tuple of lvalue references or unpacks a tuple into - tie individual objects - \fI(function template)\fP - forward_as_tuple creates a tuple of rvalue references - \fI(function template)\fP + make_tuple creates a tuple object of the type defined by the argument + \fI(C++11)\fP types + \fI(function template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into + \fI(C++11)\fP individual objects + \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP tuple_cat creates a tuple by concatenating any number of tuples - \fI(function template)\fP - std::get(std::tuple) tuple accesses specified element - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + get(std::tuple) tuple accesses specified element + \fI(C++11)\fP \fI(function template)\fP operator== operator!= - operator< lexicographically compares the values in the tuple - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values in the tuple + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::tuple) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + + Helper concepts + + tuple-like specifies that a type implemented the tuple protocol + pair-like (std::get, std::tuple_element, std::tuple_size) + (C++23) (exposition-only concept*) .SH Helper classes - tuple_size obtains the size of tuple at compile time - \fI(class template specialization)\fP - tuple_element obtains the type of the specified element - \fI(class template specialization)\fP - std::uses_allocator specializes the std::uses_allocator type trait - \fI(C++11)\fP \fI(class template specialization)\fP - placeholder to skip an element when unpacking a - ignore tuple using tie - (constant) + std::tuple_size obtains the size of tuple at compile time + \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_element obtains the type of the specified element + \fI(C++11)\fP \fI(class template specialization)\fP + std::uses_allocator specializes the std::uses_allocator type + \fI(C++11)\fP trait + \fI(class template specialization)\fP + std::basic_common_reference determines the common reference type of a + (C++23) tuple and a tuple-like type + \fI(class template specialization)\fP + std::common_type determines the common type of a tuple and a + (C++23) tuple-like type + \fI(class template specialization)\fP + std::formatter formatting support for tuple + (C++23) \fI(class template specialization)\fP + ignore placeholder to skip an element when + \fI(C++11)\fP unpacking a tuple using tie + (constant) + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Since the "shape" of a tuple – its size, the types of its elements, and the ordering + of those types – are part of its type signature, they must all be available at + compile time and can only depend on other compile-time information. This means that + many conditional operations on tuples – in particular, conditional prepend/append + and filter – are only possible if the conditions can be evaluated at compile time. + For example, given a std::tuple, it is possible to filter on types + – e.g. returning a std::tuple – but not to filter on whether or not each + element is positive (which would have a different type signature depending on + runtime values of the tuple), unless all the elements were themselves constexpr. + + As a workaround, one can work with tuples of std::optional, but there is still no + way to adjust the size based on runtime information. + + Until N4387 (applied as a defect report for C++11), a function could not return a + tuple using copy-list-initialization: + + std::tuple foo_tuple() + { + return {1, -1}; // Error until N4387 + return std::tuple{1, -1}; // Always works + return std::make_tuple(1, -1); // Always works + } .SH Example - + // Run this code - #include #include - #include #include - + #include + #include + std::tuple get_student(int id) { - if (id == 0) return std::make_tuple(3.8, 'A', "Lisa Simpson"); - if (id == 1) return std::make_tuple(2.9, 'C', "Milhouse Van Houten"); - if (id == 2) return std::make_tuple(1.7, 'D', "Ralph Wiggum"); + switch (id) + { + case 0: return {3.8, 'A', "Lisa Simpson"}; + case 1: return {2.9, 'C', "Milhouse Van Houten"}; + case 2: return {1.7, 'D', "Ralph Wiggum"}; + case 3: return {0.6, 'F', "Bart Simpson"}; + } + throw std::invalid_argument("id"); } - + int main() { - auto student0 = get_student(0); + const auto student0 = get_student(0); std::cout << "ID: 0, " << "GPA: " << std::get<0>(student0) << ", " << "grade: " << std::get<1>(student0) << ", " << "name: " << std::get<2>(student0) << '\\n'; - - double gpa1; - char grade1; - std::string name1; - std::tie(gpa1, grade1, name1) = get_student(1); + + const auto student1 = get_student(1); std::cout << "ID: 1, " - << "GPA: " << gpa1 << ", " - << "grade: " << grade1 << ", " - << "name: " << name1 << '\\n'; + << "GPA: " << std::get(student1) << ", " + << "grade: " << std::get(student1) << ", " + << "name: " << std::get(student1) << '\\n'; + + double gpa2; + char grade2; + std::string name2; + std::tie(gpa2, grade2, name2) = get_student(2); + std::cout << "ID: 2, " + << "GPA: " << gpa2 << ", " + << "grade: " << grade2 << ", " + << "name: " << name2 << '\\n'; + + // C++17 structured binding: + const auto [gpa3, grade3, name3] = get_student(3); + std::cout << "ID: 3, " + << "GPA: " << gpa3 << ", " + << "grade: " << grade3 << ", " + << "name: " << name3 << '\\n'; } .SH Output: ID: 0, GPA: 3.8, grade: A, name: Lisa Simpson ID: 1, GPA: 2.9, grade: C, name: Milhouse Van Houten + ID: 2, GPA: 1.7, grade: D, name: Ralph Wiggum + ID: 3, GPA: 0.6, grade: F, name: Bart Simpson + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2796 C++11 triviality of the destructor of specified + std::tuple was unspecified + the program is ill-formed + LWG 3990 C++11 a program could declare an explicit or in this + partial specialization of std::tuple case (no diagnostic + required) .SH References + * C++23 standard (ISO/IEC 14882:2023): + + * 22.4 Tuples [tuple] + * C++20 standard (ISO/IEC 14882:2020): + + * 20.5 Tuples [tuple] + * C++17 standard (ISO/IEC 14882:2017): + + * 23.5 Tuples [tuple] + * C++14 standard (ISO/IEC 14882:2014): + + * 20.4 Tuples [tuple] * C++11 standard (ISO/IEC 14882:2011): * 20.4 Tuples [tuple] + +.SH See also + + pair implements binary tuple, i.e. a pair of values + \fI(class template)\fP diff --git a/man/std::tuple::operator=.3 b/man/std::tuple::operator=.3 index 77f55ed05..a98ef2166 100644 --- a/man/std::tuple::operator=.3 +++ b/man/std::tuple::operator=.3 @@ -1,38 +1,126 @@ -.TH std::tuple::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - tuple& operator=( const tuple& other ); \fB(1)\fP \fI(since C++11)\fP - tuple& operator=( tuple&& other ); \fB(2)\fP \fI(since C++11)\fP - template< class... UTypes > \fB(3)\fP \fI(since C++11)\fP - tuple& operator=( const tuple& other ); - template< class... UTypes > \fB(4)\fP \fI(since C++11)\fP - tuple& operator=( tuple&& other ); - template< class U1, class U2 > \fB(5)\fP \fI(since C++11)\fP - tuple& operator=( const pair& p ); - template< class U1, class U2 > \fB(6)\fP \fI(since C++11)\fP - tuple& operator=( pair&& p ); +.TH std::tuple::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple::operator= \- std::tuple::operator= - Replaces the contents of the tuple with the contents of another tuple or a pair. +.SH Synopsis + tuple& operator=( const tuple& other ); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++20) + constexpr const tuple& operator=( const tuple& other ) \fB(2)\fP (since C++23) + const; + tuple& operator=( tuple&& other ) noexcept(/* see below \fB(3)\fP \fI(since C++11)\fP + */); (constexpr since C++20) + constexpr const tuple& operator=( tuple&& other ) \fB(4)\fP (since C++23) + const; + template< class... UTypes > \fB(5)\fP \fI(since C++11)\fP + tuple& operator=( const tuple& other ); (constexpr since C++20) + template< class... UTypes > + constexpr const tuple& operator=( const \fB(6)\fP (since C++23) + tuple& other ) const; + template< class... UTypes > \fB(7)\fP \fI(since C++11)\fP + tuple& operator=( tuple&& other ); (constexpr since C++20) + template< class... UTypes > + constexpr const tuple& operator=( tuple&& \fB(8)\fP (since C++23) + other ) const; + template< class E1, class E2 > \fB(9)\fP \fI(since C++11)\fP + tuple& operator=( const std::pair& p ); (constexpr since C++20) + template< class E1, class E2 > + constexpr const tuple& operator=( const std::pair& p ) const; + template< class E1, class E2 > \fB(11)\fP \fI(since C++11)\fP + tuple& operator=( std::pair&& p ); (constexpr since C++20) + template< class E1, class E2 > + constexpr const tuple& operator=( std::pair&& p \fB(12)\fP (since C++23) + ) const; + template< tuple-like UTuple > \fB(13)\fP (since C++23) + constexpr tuple& operator=( UTuple&& u ); + template< tuple-like UTuple > \fB(14)\fP (since C++23) + constexpr const tuple& operator=( UTuple&& u ) const; - 1) Copy assignment operator. Replaces each element with a copy of the corresponding - element of other. + Replaces the contents of the tuple with the contents of another tuple-like object. - 2) Move assignment operator. Replaces each element with the corresponding element of - other using move semantics. + In the descriptions that follow, let - 3) For all i, assigns std::get(other) to std::get(*this). + * i be in the range [0, sizeof...(Types)) in order, + * Ti be the ith type in the class template parameter pack Types, and + * Ui be the ith type in a function template parameter pack named UTypes, - 4) For all i, assigns std::forward(std::get(other)) to std::get(*this). + where indexing is zero-based. - 5) Assigns p.first to the first element of *this and p.second to the second element + 1) Copy assignment operator. Assigns each element of other to the corresponding + element of *this. + This overload is defined as deleted unless std::is_copy_assignable::value is + true for all Ti. + 2) Copy assignment operator for const-qualified operand. Assigns each element of + other to the corresponding element of *this. + This overload participates in overload resolution only if + std::is_copy_assignable_v is true for all Ti. + 3) Move assignment operator. For all i, assigns std::forward(std::get(other)) + to std::get(*this). + This overload participates in overload resolution only if + std::is_move_assignable::value is true for all Ti. + 4) Move assignment operator for const-qualified operand. For all i, assigns + std::forward(std::get(other)) to std::get(*this). + This overload participates in overload resolution only if std::is_assignable_v is true for all Ti. + 5) For all i, assigns std::get(other) to std::get(*this). + This overload participates in overload resolution only if sizeof...(Types) == + sizeof...(UTypes), and std::is_assignable::value is true for all + corresponding pairs of types Ti and Ui. + 6) For all i, assigns std::get(other) to std::get(*this). + This overload participates in overload resolution only if sizeof...(Types) == + sizeof...(UTypes), and std::is_assignable_v is true for all + corresponding pairs of types Ti and Ui. + 7) For all i, assigns std::forward(std::get(other)) to std::get(*this). + This overload participates in overload resolution only if sizeof...(Types) == + sizeof...(UTypes), and std::is_assignable::value is true for all + corresponding pairs of types Tiand Ui. + 8) For all i, assigns std::forward(std::get(other)) to std::get(*this). + This overload participates in overload resolution only if sizeof...(Types) == + sizeof...(UTypes), and std::is_assignable_v is true for all + corresponding pairs of types Ti and Ui. + 9) Assigns p.first to the first element of *this and p.second to the second element of *this. - - 6) Assigns std::forward(p.first) to the first element of *this and - std::forward(p.second) to the second element of *this. + This overload participates in overload resolution only if + * sizeof...(Types) == 2, + * std::is_assignable::value is true, and + * std::is_assignable::value is true. + 10) Assigns p.first to the first element and p.second to the second element. + This overload participates in overload resolution only if + * sizeof...(Types) == 2, + * std::is_assignable_v is true, and + * std::is_assignable_v is true. + 11) Assigns std::forward(p.first) to the first element of *this and + std::forward(p.second) to the second element of *this. + This overload participates in overload resolution only if + * sizeof...(Types) == 2, + * std::is_assignable_v is true, and + * std::is_assignable_v is true. + 12) Assigns std::forward(p.first) to the first element and + std::forward(p.second) to the second element. + This overload participates in overload resolution only if + * sizeof...(Types) == 2, + * std::is_assignable_v is true, and + * std::is_assignable_v is true. + 13) For all i, assigns std::get(std::forward(u)) to std::get(*this). + This overload participates in overload resolution only if + * std::same_as, std::tuple> is false, + * std::remove_cvref_t is not a specialization of std::ranges::subrange, + * sizeof...(Types) equals std::tuple_size_v>, and + * std::is_assignable_v(std::forward(u)))> is + true for all i. + 14) For all i, assigns std::get(std::forward(u)) to std::get(*this). + This overload participates in overload resolution only if + * std::same_as, std::tuple> is false, + * std::remove_cvref_t is not a specialization of std::ranges::subrange, + * sizeof...(Types) equals std::tuple_size_v>, and + * std::is_assignable_v(std::forward(u)))> + is true for all i. .SH Parameters other - tuple to replace the contents of this tuple p - pair to replace the contents of this 2-tuple + u - tuple-like object to replace the contents of this tuple .SH Return value @@ -40,34 +128,149 @@ .SH Exceptions - 1) \fI(none)\fP - - 2) - noexcept specification: \fI(since C++11)\fP + 1,2) May throw implementation-defined exceptionsif the assignment of one of the + types in Types throws an exception. + 3) + noexcept specification: noexcept( - is_nothrow_move_assignable::value && - is_nothrow_move_assignable::value && - is_nothrow_move_assignable::value && + std::is_nothrow_move_assignable::value && + std::is_nothrow_move_assignable::value && + std::is_nothrow_move_assignable::value && ... ) + 4-14) May throw implementation-defined exceptionsif the assignment of one of the + types in Types throws an exception. - 3-5) \fI(none)\fP +.SH Example - 6) - noexcept specification: - noexcept - -.SH Example +// Run this code + + #include + #include + #include + #include + #include + #include + + // helper function to print std::vector + std::ostream& operator<<(std::ostream& os, std::vector const& v) + { + os << '{'; + for (std::size_t t = 0; t != v.size(); ++t) + os << v[t] << (t + 1 < v.size() ? ", " : ""); + return os << '}'; + } + + // helpers to print a tuple of any size + template + void print_tuple(std::string_view name, const std::tuple& t) + { + std::cout << name << " = {"; + std::apply([&](auto&& arg, auto&&... args) + { + std::cout << arg; + ((std::cout << ", " << args), ...); + }, t); + std::cout << '}'; + } + + template + void print_tuples(std::string_view name1, const Tuple1& t1, + std::string_view name2, const Tuple2& t2) + { + print_tuple(name1, t1); + std::cout << ", "; + print_tuple(name2, std::tuple(t2)); + std::cout << "\\n\\n"; + } + + int main() + { + // Tuple to tuple examples // + std::tuple> + t1{1, "alpha", {1, 2, 3}}, + t2{2, "beta", {4, 5}}; + print_tuples("1) t1", t1, "t2", t2); + + // Normal copy assignment + // operator=( const tuple& other ); + t1 = t2; + print_tuples("2) t1 = t2;\\n t1", t1, "t2", t2); + + // Normal move assignment + // operator=( tuple&& other ); + t1 = std::move(t2); + print_tuples("3) t1 = std::move(t2);\\n t1", t1, "t2", t2); + + // Converting copy assignment + // operator=( const tuple& other ); + std::tuple> t3{3, "gamma", {6, 7, 8}}; + t1 = t3; + print_tuples("4) t1 = t3;\\n t1", t1, "t3", t3); + + // Converting move assignment + // operator=( tuple&& other ); + t1 = std::move(t3); + print_tuples("5) t1 = std::move(t3);\\n t1", t1, "t3", t3); - This section is incomplete - Reason: no example + // Pair to tuple examples // + std::tuple> t4{"delta", {10, 11, 12}}; + std::pair> p1{"epsilon", {14, 15, 16}}; + print_tuples("6) t4", t4, "p1", p1); + + // Converting copy assignment from std::pair + // operator=( const std::pair& p ); + t4 = p1; + print_tuples("7) t4 = p1;\\n t4", t4, "p1", p1); + + // Converting move assignment from std::pair + // operator=( std::pair&& p ); + t4 = std::move(p1); + print_tuples("8) t4 = std::move(p1);\\n t4", t4, "p1", p1); + } + +.SH Possible output: + + 1) t1 = {1, alpha, {1, 2, 3}}, t2 = {2, beta, {4, 5}} + + 2) t1 = t2; + t1 = {2, beta, {4, 5}}, t2 = {2, beta, {4, 5}} + + 3) t1 = std::move(t2); + t1 = {2, beta, {4, 5}}, t2 = {2, , {}} + + 4) t1 = t3; + t1 = {3, gamma, {6, 7, 8}}, t3 = {3, gamma, {6, 7, 8}} + + 5) t1 = std::move(t3); + t1 = {3, gamma, {6, 7, 8}}, t3 = {3, gamma, {}} + + 6) t4 = {delta, {10, 11, 12}}, p1 = {epsilon, {14, 15, 16}} + + 7) t4 = p1; + t4 = {epsilon, {14, 15, 16}}, p1 = {epsilon, {14, 15, 16}} + + 8) t4 = std::move(p1); + t4 = {epsilon, {14, 15, 16}}, p1 = {epsilon, {}} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2729 C++11 operator= was unconstrained and might constrained + result in unnecessary undefined behavior .SH See also + constructor constructs a new tuple + \fI(public member function)\fP + operator= assigns the contents + \fI(public member function of std::pair)\fP .SH Category: - - * Todo no example + * conditionally noexcept diff --git a/man/std::tuple::swap.3 b/man/std::tuple::swap.3 index c2f0b7997..071f63567 100644 --- a/man/std::tuple::swap.3 +++ b/man/std::tuple::swap.3 @@ -1,9 +1,26 @@ -.TH std::tuple::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tuple::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple::swap \- std::tuple::swap + .SH Synopsis Defined in header - void swap( tuple& other ); \fI(since C++11)\fP + void swap( tuple& other ) noexcept(/* see below */); \fB(1)\fP \fI(since C++11)\fP + (constexpr since C++20) + constexpr void swap( const tuple& other ) noexcept(/* \fB(2)\fP (since C++23) + see below */) const; + + Calls swap (which might be std::swap, or might be found via ADL) for each element in + *this and its corresponding element in other. - Calls std::swap for each element in *this and its corresponding element in other. + If any selected swap function call is ill-formed, or does not swap the (until C++23) + corresponding elements of both tuples, the behavior is undefined. + If any selected swap function call does not swap the corresponding + elements of both tuples, the behavior is undefined. + + 1) The program is ill-formed if (std::is_swappable_v && ...) is (since C++23) + not true. + 2) The program is ill-formed if (std::is_swappable_v && + ...) is not true. .SH Parameters @@ -15,37 +32,77 @@ .SH Exceptions - noexcept specification: \fI(since C++11)\fP + noexcept specification: noexcept( noexcept(swap(std::declval>(), std::declval())) && noexcept(swap(std::declval>(), std::declval())) && - noexcept(swap(std::declval>(), std::declval())) && + noexcept(swap(std::declval>(), std::declval())) && \fI(until C++17)\fP ... ) + In the expression above, the identifier swap is looked up in the same + manner as the one used by the C++17 std::is_nothrow_swappable trait. + 1) + noexcept specification: + noexcept((std::is_nothrow_swappable_v && ...)) \fI(since C++17)\fP + 2) + noexcept specification: + noexcept((std::is_nothrow_swappable_v && ...)) + .SH Example - + // Run this code #include - #include #include - + #include + int main() { - std::tuple p1, p2; - p1 = std::make_tuple(10, "test", 3.14); - p2.swap(p1); - std::cout << "(" << std::get<0>(p2) - << ", " << std::get<1>(p2) - << ", " << std::get<2>(p2) << ")\\n"; + std::tuple p1{42, "ABCD", 2.71}, p2; + p2 = std::make_tuple(10, "1234", 3.14); + + auto print_p1_p2 = [&](auto rem) + { + std::cout << rem + << "p1 = {" << std::get<0>(p1) + << ", " << std::get<1>(p1) + << ", " << std::get<2>(p1) << "}, " + << "p2 = {" << std::get<0>(p2) + << ", " << std::get<1>(p2) + << ", " << std::get<2>(p2) << "}\\n"; + }; + + print_p1_p2("Before p1.swap(p2): "); + p1.swap(p2); + print_p1_p2("After p1.swap(p2): "); + swap(p1, p2); + print_p1_p2("After swap(p1, p2): "); } .SH Output: - (10, test, 3.14) + Before p1.swap(p2): p1 = {42, ABCD, 2.71}, p2 = {10, 1234, 3.14} + After p1.swap(p2): p1 = {10, 1234, 3.14}, p2 = {42, ABCD, 2.71} + After swap(p1, p2): p1 = {42, ABCD, 2.71}, p2 = {10, 1234, 3.14} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2456 C++11 the noexcept specification is ill-formed made to work .SH See also + + std::swap(std::tuple) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + swap swaps the contents + \fI(C++11)\fP \fI(public member function of std::pair)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::tuple::tuple.3 b/man/std::tuple::tuple.3 index c80004395..955e3bc4f 100644 --- a/man/std::tuple::tuple.3 +++ b/man/std::tuple::tuple.3 @@ -1,87 +1,231 @@ -.TH std::tuple::tuple 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tuple::tuple 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple::tuple \- std::tuple::tuple + .SH Synopsis Defined in header - constexpr tuple(); \fB(1)\fP \fI(since C++11)\fP - explicit tuple( const Types&... args ); \fB(2)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - explicit constexpr tuple( const Types&... args ); \fB(2)\fP \fI(since C++14)\fP - template< class... UTypes > \fB(3)\fP \fI(since C++11)\fP - explicit tuple( UTypes&&... args ); \fI(until C++14)\fP - template< class... UTypes > \fB(3)\fP \fI(since C++14)\fP - explicit constexpr tuple( UTypes&&... args ); - template< class... UTypes > \fB(4)\fP \fI(since C++11)\fP - tuple( const tuple& other ); \fI(until C++14)\fP - template< class... UTypes > \fB(4)\fP \fI(since C++14)\fP - constexpr tuple( const tuple& other ); - template \fB(5)\fP \fI(since C++11)\fP - tuple( tuple&& other ); \fI(until C++14)\fP - template \fB(5)\fP \fI(since C++14)\fP - constexpr tuple( tuple&& other ); - template< class U1, class U2 > \fB(6)\fP \fI(since C++11)\fP - tuple( const pair& p ); \fI(until C++14)\fP - template< class U1, class U2 > \fB(6)\fP \fI(since C++14)\fP - constexpr tuple( const pair& p ); - template< class U1, class U2 > \fB(7)\fP \fI(since C++11)\fP - tuple( pair&& p ); \fI(until C++14)\fP - template< class U1, class U2 > \fB(7)\fP \fI(since C++14)\fP - constexpr tuple( pair&& p ); - tuple( const tuple& other ) = default; \fB(8)\fP \fI(since C++11)\fP - tuple( tuple&& other ) = default; \fB(9)\fP \fI(since C++11)\fP - template< class Alloc > \fB(10)\fP \fI(since C++11)\fP - tuple( std::allocator_arg_t, const Alloc& a ); + constexpr tuple(); \fB(1)\fP \fI(since C++11)\fP + (conditionally explicit) + \fI(since C++11)\fP + tuple( const Types&... args ); \fB(2)\fP (constexpr since C++14) + (conditionally explicit) + template< class... UTypes > \fI(since C++11)\fP + tuple( UTypes&&... args ); \fB(3)\fP (constexpr since C++14) + (conditionally explicit) + template< class... UTypes > \fB(4)\fP (since C++23) + constexpr tuple( tuple& other ); (conditionally explicit) + template< class... UTypes > \fI(since C++11)\fP + tuple( const tuple& other ); \fB(5)\fP (constexpr since C++14) + (conditionally explicit) + template< class... UTypes > \fI(since C++11)\fP + tuple( tuple&& other ); \fB(6)\fP (constexpr since C++14) + (conditionally explicit) + template< class... UTypes > \fB(7)\fP (since C++23) + constexpr tuple( const tuple&& other ); (conditionally explicit) + template< class U1, class U2 > \fB(8)\fP (since C++23) + constexpr tuple( std::pair& p ); (conditionally explicit) + template< class U1, class U2 > \fI(since C++11)\fP + tuple( const std::pair& p ); \fB(9)\fP (constexpr since C++14) + (conditionally explicit) + template< class U1, class U2 > \fI(since C++11)\fP + tuple( std::pair&& p ); \fB(10)\fP (constexpr since C++14) + (conditionally explicit) + template< class U1, class U2 > \fB(11)\fP (since C++23) + constexpr tuple( const std::pair&& p ); (conditionally explicit) + template< tuple-like UTuple > \fB(12)\fP (since C++23) + constexpr tuple( UTuple&& u ); (conditionally explicit) + tuple( const tuple& other ) = default; \fB(13)\fP \fI(since C++11)\fP + tuple( tuple&& other ) = default; \fB(14)\fP \fI(since C++11)\fP + Allocator-extended constructors + template< class Alloc > \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a ); \fB(15)\fP (constexpr since C++20) + (conditionally explicit) template< class Alloc > - tuple( std::allocator_arg_t, const Alloc& a, const Types&... args \fB(11)\fP \fI(since C++11)\fP - ); - template< class Alloc, class... UTypes > \fB(12)\fP \fI(since C++11)\fP - tuple( std::allocator_arg_t, const Alloc& a, UTypes&&... args ); - template - tuple( std::allocator_arg_t, const Alloc& a, const \fB(13)\fP \fI(since C++11)\fP - tuple& other ); + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(16)\fP (constexpr since C++20) + (conditionally explicit) + const Types&... args ); + template< class Alloc, class... UTypes > + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(17)\fP (constexpr since C++20) + (conditionally explicit) + UTypes&&... args ); + template< class Alloc, class... UTypes > + (since C++23) + constexpr tuple( std::allocator_arg_t, const Alloc& a, \fB(18)\fP (conditionally explicit) + + tuple& other ); template< class Alloc, class... UTypes > - tuple( std::allocator_arg_t, const Alloc& a, tuple&& \fB(14)\fP \fI(since C++11)\fP - other ); + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(19)\fP (constexpr since C++20) + (conditionally explicit) + const tuple& other ); + template< class Alloc, class... UTypes > + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(20)\fP (constexpr since C++20) + (conditionally explicit) + tuple&& other ); + template< class Alloc, class... UTypes > + (since C++23) + constexpr tuple( std::allocator_arg_t, const Alloc& a, \fB(21)\fP (conditionally explicit) + + const tuple&& other ); template< class Alloc, class U1, class U2 > - tuple( std::allocator_arg_t, const Alloc& a, const pair& \fB(15)\fP \fI(since C++11)\fP - p ); - template< class Alloc, class U1, class U2 > \fB(16)\fP \fI(since C++11)\fP - tuple( std::allocator_arg_t, const Alloc& a, pair&& p ); + (since C++23) + constexpr tuple( std::allocator_arg_t, const Alloc& a, \fB(22)\fP (conditionally explicit) + + std::pair& p ); + template< class Alloc, class U1, class U2 > + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(23)\fP (constexpr since C++20) + (conditionally explicit) + const std::pair& p ); + template< class Alloc, class U1, class U2 > + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(24)\fP (constexpr since C++20) + (conditionally explicit) + std::pair&& p ); + template< class Alloc, class U1, class U2 > + (since C++23) + constexpr tuple( std::allocator_arg_t, const Alloc& a, \fB(25)\fP (conditionally explicit) + + const std::pair&& p ); + template< class Alloc, tuple-like UTuple > (since C++23) + constexpr tuple( std::allocator_arg_t, const Alloc& a, \fB(26)\fP (conditionally explicit) + UTuple&& u ); + template< class Alloc > + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(27)\fP (constexpr since C++20) + + const tuple& other ); template< class Alloc > - tuple( std::allocator_arg_t, const Alloc& a, const tuple& other \fB(17)\fP \fI(since C++11)\fP - ); - template< class Alloc > \fB(18)\fP \fI(since C++11)\fP - tuple( std::allocator_arg_t, const Alloc& a, tuple&& other ); + \fI(since C++11)\fP + tuple( std::allocator_arg_t, const Alloc& a, \fB(28)\fP (constexpr since C++20) + + tuple&& other ); Constructs a new tuple. - 1) Default constructor. Value-initializes all elements. + In the descriptions that follow, let + + * i be in the range [0, sizeof...(Types)) in order, + * Ti be the ith type in Types, and + * Ui be the ith type in a template parameter pack named UTypes, + + where indexing is zero-based. + + 1) Default constructor. Value-initializes all elements, if any. The default + constructor is trivial if sizeof...(Types) == 0. + * This overload participates in overload resolution only if + std::is_default_constructible::value is true for all i. + * The constructor is explicit if and only if Ti is not copy-list-initializable + from {} for at least one i. + 2) Direct constructor. Initializes each element of the tuple with the corresponding + parameter. + * This overload participates in overload resolution only if sizeof...(Types) >= 1 + and std::is_copy_constructible::value is true for all i. + * This constructor is explicit if and only if std::is_convertible::value is false for at least one i. + 3) Converting constructor. Initializes each element of the tuple with the + corresponding value in std::forward(args). + * This overload participates in overload resolution only if + * sizeof...(Types) == sizeof...(UTypes), + * sizeof...(Types) >= 1, + * std::is_constructible::value is true for all i, and + * let D be + std::decay::type + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP, + * if sizeof...(Types) == 1, then D is not std::tuple, otherwise, + * if sizeof...(Types) == 2 or sizeof...(Types) == 3, then either D is + not std::allocator_arg_t, or T0 is std::allocator_arg_t. + * The constructor is explicit if and only if std::is_convertible::value is + false for at least one i. + + * This constructor is defined as deleted if the initialization of + any element that is a reference would bind it to a temporary (since C++23) + object. + + 4-7) Converting constructor. Initializes each element of the tuple with the + corresponding element of other. + + Formally, let FWD(other) be std::forward(other), for all i, + initializes ith element of the tuple with std::get(FWD(other)). - 2) Initializes each element of the tuple with the corresponding parameter. + * This overload participates in overload resolution only if + * sizeof...(Types) == sizeof...(UTypes), + * std::is_constructible_v(FWD(other)))> is true for + all i, and + * either + * sizeof...(Types) is not 1, or + * (when Types... expands to T and UTypes... expands to U) + std::is_convertible_v, std::is_constructible_v, and std::is_same_v are all false. + * These constructors are explicit if and only if + std::is_convertible_v(FWD(other))), Ti> is false for at + least one i. - 3) Initializes each element of the tuple with the corresponding value in - std::forward(args). + * These constructors are defined as deleted if the initialization of + any element that is a reference would bind it to a temporary (since C++23) + object. - 4) For all i in sizeof...(UTypes), initializes ith element of the tuple with - std::get(other). + 8-11) Pair constructor. Constructs a 2-element tuple with each element constructed + from the corresponding element of p. - 5) For all i in sizeof...(UTypes), initializes ith element of the tuple with - std::forward(std::get(other)). + Formally, let FWD(p) be std::forward(p), initializes the first element + with std::get<0>(FWD(p)) and the second element with std::get<1>(FWD(p)). - 6) Constructs a 2-element tuple with the first element constructed from p.first and - the second element from p.second + * This overload participates in overload resolution only if + * sizeof...(Types) == 2, + * std::is_constructible_v(FWD(p)))> is true, and + * std::is_constructible_v(FWD(p)))> is true. + * The constructor is explicit if and only if + std::is_convertible_v(FWD(p))), T0> or + std::is_convertible_v(FWD(p))), T1> is false. - 7) Constructs a 2-element tuple with the first element constructed from - std::forward(p.first) and the second element from std::forward(p.second) + * These constructors are defined as deleted if the initialization of + any element that is a reference would bind it to a temporary (since C++23) + object. - 8) Compiler-generated copy constructor. Initializes each element of the tuple with - the corresponding element of other. This constructor is constexpr if every operation - it performs is constexpr. For the empty tuple std::tuple<>, it is constexpr. + 12) tuple-like constructor. Constructs a tuple with each element constructed from + the corresponding element of u. - 9) Compiler-generated move constructor. Initializes each ith element of the tuple - with std::forward(std::get(other)). This constructor is constexpr if every - operation it performs is constexpr. For the empty tuple std::tuple<>, it is - constexpr. + Formally, for all i, initializes ith element of the tuple with + std::get(std::forward(u)). - 10 - 18) Identical to 1-9 except each element is created by uses-allocator + * This overload participates in overload resolution only if + * std::same_as, std::tuple> is false, + * std::remove_cvref_t is not a specialization of + std::ranges::subrange, + * sizeof...(Types) equals std::tuple_size_v>, + * std::is_constructible_v(std::forward(u)))> + is true for all i, and + * either + * sizeof...(Types) is not 1, or + * (when Types... expands to T) std::is_convertible_v and + std::is_constructible_v are both false. + * This constructor is defined as deleted if the initialization of any element that + is a reference would bind it to a temporary object. + 13) Implicitly-defined copy constructor. Initializes each element of the tuple with + the corresponding element of other. + * This constructor is constexpr if every operation it performs is constexpr. For + the empty tuple std::tuple<>, it is constexpr. + * std::is_copy_constructible::value must be true for all i, otherwise + the behavior is undefined + \fI(until C++20)\fP + the program is ill-formed + \fI(since C++20)\fP. + 14) Implicitly-defined move constructor. For all i, initializes the ith element of + the tuple with std::forward(std::get(other)). + * This constructor is constexpr if every operation it performs is constexpr. For + the empty tuple std::tuple<>, it is constexpr. + * std::is_move_constructible::value must be true for all i, otherwise + the behavior is undefined + \fI(until C++20)\fP + this overload does not participate in overload resolution + \fI(since C++20)\fP. + 15-28) Identical to (1-14) except each element is created by uses-allocator construction, that is, the Allocator object a is passed as an additional argument to the constructor of each element for which std::uses_allocator::value is true. @@ -89,80 +233,162 @@ .SH Parameters args - values used to initialize each element of the tuple - other - a tuple of values used to initialize each element of the tupe - p - pair of values used to initialize both elements of this 2-tuple - a - allocator to use in uses-allocator construction + other - the tuple of values used to initialize each element of the tuple + p - the pair of values used to initialize both elements of the 2-tuple + u - the tuple-like object of values used to initialize each element of the tuple + a - the allocator to use in uses-allocator construction + +.SH Notes + + Conditionally-explicit constructors make it possible to construct a tuple in + copy-initialization context using list-initialization syntax: + + std::tuple foo_tuple() + { + // return {1, -1}; // Error before N4387 + return std::make_tuple(1, -1); // Always works + } + + Note that if some element of the list is not implicitly convertible to the + corresponding element of the target tuple, the constructors become explicit: + + using namespace std::chrono; + void launch_rocket_at(std::tuple); + + launch_rocket_at({hours\fB(1)\fP, minutes\fB(2)\fP, seconds\fB(3)\fP}); // OK + launch_rocket_at({1, 2, 3}); // Error: int is not implicitly convertible to duration + launch_rocket_at(std::tuple{1, 2, 3}); // OK .SH Example - + // Run this code + #include #include + #include #include - #include + #include #include - #include - + #include + #include + + // helper function to print a vector to a stream + template + Os& operator<<(Os& os, std::vector const& v) + { + os << '{'; + for (auto i{v.size()}; const T& e : v) + os << e << (--i ? "," : ""); + return os << '}'; + } + + template + void print_single(T const& v) + { + if constexpr (std::is_same_v>) + std::cout << std::quoted(v); + else if constexpr (std::is_same_v, char>) + std::cout << "'" << v << "'"; + else + std::cout << v; + } + // helper function to print a tuple of any size template - struct TuplePrinter { + struct TuplePrinter + { static void print(const Tuple& t) { - TuplePrinter::print(t); - std::cout << ", " << std::get(t); + TuplePrinter::print(t); + std::cout << ", "; + print_single(std::get(t)); } }; - + template - struct TuplePrinter{ + struct TuplePrinter + { static void print(const Tuple& t) { - std::cout << std::get<0>(t); + print_single(std::get<0>(t)); } }; - + template - void print(const std::tuple& t) + void print(std::string_view message, const std::tuple& t) { - std::cout << "("; + std::cout << message << " ("; TuplePrinter::print(t); std::cout << ")\\n"; } // end helper function - + int main() { std::tuple t1; - std::cout << "Value-initialized: "; print(t1); - std::tuple t2(42, "Test", -3.14); - std::cout << "Initialized with values: "; print(t2); - std::tuple t3(t2); - std::cout << "Implicitly converted: "; print(t3); - std::tuple t4(std::make_pair(42, 3.14)); - std::cout << "Constructed from a pair"; print(t4); - - // given Allocator my_alloc with a single-argument constructor my_alloc(int) - // use my_alloc(1) to allocate 10 ints in a vector - std::vector v(10, 1, my_alloc(1)); - // use my_alloc(2) to allocate 10 ints in a vector in a tuple - std::tuple, double> t5(std::allocator_arg, - my_alloc(2), 42, v, -3.14); + print("Value-initialized, t1:", t1); + + std::tuple t2{42, "Test", -3.14}; + print("Initialized with values, t2:", t2); + + std::tuple t3{t2}; + print("Implicitly converted, t3:", t3); + + std::tuple t4{std::make_pair(42, 3.14)}; + print("Constructed from a pair, t4:", t4); + + // given Allocator my_alloc with a single-argument constructor + // my_alloc(int); use my_alloc(1) to allocate 5 ints in a vector + using my_alloc = std::allocator; + std::vector v{5, 1, my_alloc{/* 1 */}}; + + // use my_alloc(2) to allocate 5 ints in a vector in a tuple + std::tuple, double> t5 + {std::allocator_arg, my_alloc{/* 2 */}, 42, v, -3.14}; + print("Constructed with allocator, t5:", t5); } -.SH Output: +.SH Possible output: + + Value-initialized, t1: (0, "", 0) + Initialized with values, t2: (42, "Test", -3.14) + Implicitly converted, t3: ('*', "Test", -3) + Constructed from a pair, t4: (42, 3.14) + Constructed with allocator, t5: (42, {1,1,1,1,1}, -3.14) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Value-initialized: (0, , 0) - Initialized with values: (42, Test, -3.14) - Implicitly converted: (*, Test, -3) - Constructed from a pair(42, 3.14) + DR Applied to Behavior as published Correct behavior + LWG 2510 C++11 default constructor was implicit made conditionally-explicit + constructor of 1-tuple might + LWG 3121 C++11 recursively check the constraints; furtherly constrained + allocator_arg_t argument brought the constructor + ambiguity + the uses-allocator constructor + LWG 3158 C++11 corresponding made conditionally-explicit + to default constructor was implicit + LWG 3211 C++11 whether the default constructor of require to be trivial + tuple<> is trivial was unspecified + N4387 C++11 some constructors were explicit, most constructors made + preventing useful behavior conditionally-explicit + tuple-like constructor may + LWG 4045 C++23 potentially create dangling made defined as deleted + references .SH See also + operator= assigns the contents of one tuple to another + \fI(public member function)\fP make_tuple creates a tuple object of the type defined by the argument types - \fI(function template)\fP - creates a tuple of lvalue references or unpacks a tuple into - tie individual objects - \fI(function template)\fP - forward_as_tuple creates a tuple of rvalue references - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into + \fI(C++11)\fP individual objects + \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP + constructor constructs new pair + \fI(public member function of std::pair)\fP diff --git a/man/std::tuple_cat.3 b/man/std::tuple_cat.3 index baba94d2f..1eed69cfe 100644 --- a/man/std::tuple_cat.3 +++ b/man/std::tuple_cat.3 @@ -1,12 +1,39 @@ -.TH std::tuple_cat 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::tuple_cat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple_cat \- std::tuple_cat + .SH Synopsis Defined in header - template< class... Tuples > \fI(since C++11)\fP - tuple tuple_cat(Tuples&&... args); \fI(until C++14)\fP - template< class... Tuples > \fI(since C++14)\fP - constexpr tuple tuple_cat(Tuples&&... args); + template< class... Tuples > \fI(since C++11)\fP + std::tuple tuple_cat( Tuples&&... args ); \fI(until C++14)\fP + template< class... Tuples > \fI(since C++14)\fP + constexpr std::tuple tuple_cat( Tuples&&... args ); (until C++23) + template< tuple-like... Tuples > (since C++23) + constexpr std::tuple tuple_cat( Tuples&&... args ); + + Constructs a tuple that is a concatenation of all tuples in args. The element types + /* CTypes */ of the returned tuple is formed by concatenating the elements type + packs of all + std::tuple + (until C++23) + tuple-like + (since C++23) types in Tuples in order. + + The behavior is undefined if any type in std::decay_t... is + not a specialization of std::tuple. However, an implementation may (until C++23) + choose to support types (such as std::array and std::pair) that follow + the tuple-like protocol. + The types std::decay_t... are constrained to be tuple-like, + i.e. each type therein is required to be a specialization of (since C++23) + std::tuple or another type (such as std::array and std::pair) that + models tuple-like. - Constructs a tuple that is a concatenation of all tuples in args. + If any type in /* CTypes */ is not constructible from the type of the corresponding + element in the sequence of elements concatenated from args, + the behavior is undefined + (until C++23) + the program is ill-formed + (since C++23). .SH Parameters @@ -15,36 +42,44 @@ .SH Return value A std::tuple object composed of all elements of all argument tuples constructed from - std::get(std::forward(arg)) for each individual element. + std::get(std::forward(arg)) for each individual element. .SH Example - + // Run this code #include - #include #include - + #include + // helper function to print a tuple of any size template - struct TuplePrinter { + struct TuplePrinter + { static void print(const Tuple& t) { - TuplePrinter::print(t); + TuplePrinter::print(t); std::cout << ", " << std::get(t); } }; - + template - struct TuplePrinter { + struct TuplePrinter + { static void print(const Tuple& t) { std::cout << std::get<0>(t); } }; - - template + + template = 0> + void print(const std::tuple& t) + { + std::cout << "()\\n"; + } + + template = 0> void print(const std::tuple& t) { std::cout << "("; @@ -52,24 +87,26 @@ std::cout << ")\\n"; } // end helper function - + int main() { std::tuple t1(10, "Test", 3.14); int n = 7; - auto t2 = std::tuple_cat(t1, std::make_pair("Foo", "bar"), t1, std::tie(n)); - n = 10; + auto t2 = std::tuple_cat(t1, std::make_tuple("Foo", "bar"), t1, std::tie(n)); + n = 42; print(t2); } .SH Output: - (10, Test, 3.14, Foo, bar, 10, Test, 3.14, 10) + (10, Test, 3.14, Foo, bar, 10, Test, 3.14, 42) + +.SH See also make_tuple creates a tuple object of the type defined by the argument types - \fI(function template)\fP - creates a tuple of lvalue references or unpacks a tuple into - tie individual objects - \fI(function template)\fP - forward_as_tuple creates a tuple of rvalue references - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into + \fI(C++11)\fP individual objects + \fI(function template)\fP + forward_as_tuple creates a tuple of forwarding references + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::tuple_element.3 b/man/std::tuple_element.3 new file mode 100644 index 000000000..942d55342 --- /dev/null +++ b/man/std::tuple_element.3 @@ -0,0 +1,109 @@ +.TH std::tuple_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple_element \- std::tuple_element + +.SH Synopsis + Defined in header + template< std::size_t I, class T1, class T2 > \fI(since C++11)\fP + struct tuple_element>; + + The partial specializations of std::tuple_element for pairs provide compile-time + access to the types of the pair's elements, using tuple-like syntax. The program is + ill-formed if I >= 2. + +.SH Member types + + Member type Definition + type T1 if I == 0 + T2 if I == 1 + +.SH Possible implementation + + template + struct tuple_element; + + template + struct tuple_element> + { + static_assert(I < 2, "std::pair has only 2 elements!"); + }; + + template + struct tuple_element<0, std::pair> + { + using type = T1; + }; + + template + struct tuple_element<1, std::pair> + { + using type = T2; + }; + +.SH Example + + +// Run this code + + #include + #include + #include + + namespace detail + { + template + struct index_tag { constexpr explicit index_tag() = default; }; + + template + constexpr T get_val_dispatch(std::pair const& pair, index_tag<0>) + { + return pair.first; + } + + template + constexpr U get_val_dispatch(std::pair const& pair, index_tag<1>) + { + return pair.second; + } + } // namespace detail + + template + auto constexpr get_val(std::pair const& pair) + -> typename std::tuple_element>::type + { + return detail::get_val_dispatch(pair, detail::index_tag{}); + } + + int main() + { + auto var = std::make_pair(1, std::string{"one"}); + + std::cout << get_val<0>(var) << " = " << get_val<1>(var); + } + +.SH Output: + + 1 = one + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2974 C++11 out-of-bounds index referred the undefined made ill-formed (hard + primary template error) + +.SH See also + + Structured binding \fI(C++17)\fP binds the specified names to sub-objects + or tuple elements of the initializer + std::tuple_element obtains the type of the specified element + \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_element obtains the type of the elements of array + \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_element obtains the type of the iterator or the + (C++20) sentinel of a std::ranges::subrange + \fI(class template specialization)\fP + std::tuple_size obtains the size of a pair + \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::tuple_element.3 b/man/std::tuple_element.3 deleted file mode 100644 index 03518128f..000000000 --- a/man/std::tuple_element.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH std::tuple_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< std::size_t I, class T, std::size_t N > \fI(since C++11)\fP - struct tuple_element >; - - Provides compile-type indexed access to the type of the elements of the array using - tuple-like interface - -.SH Member types - - Member type Definition - type the type of elements of the array - -.SH Possible implementation - - template - struct tuple_element; - - template - struct tuple_element > - { - using type = T; - }; - -.SH Example - - This section is incomplete - Reason: no example - -.SH See also - - tuple_element obtains the type of the specified element - \fI(class template specialization)\fP - std::tuple_element obtains the type of the elements of pair - \fI(C++11)\fP \fI(class template specialization)\fP - -.SH Category: - - * Todo no example diff --git a/man/std::tuple_element.3 b/man/std::tuple_element.3 deleted file mode 100644 index 29a3db7de..000000000 --- a/man/std::tuple_element.3 +++ /dev/null @@ -1,72 +0,0 @@ -.TH std::tuple_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T1, class T2 > \fB(1)\fP \fI(since C++11)\fP - struct tuple_element<0, std::pair >; - template< class T1, class T2 > \fB(2)\fP \fI(since C++11)\fP - struct tuple_element<1, std::pair >; - - The partial specializations of std::tuple_element for pairs provide compile-time - access to the types of the pair's elements, using tuple-like syntax. - -.SH Member types - -.SH First version - Member type Definition - type T1 -.SH Second version - Member type Definition - type T2 - -.SH Possible implementation - - template - struct tuple_element; - - template - struct tuple_element<0, std::pair > - { - using type = T1; - }; - - template - struct tuple_element<1, std::pair > - { - using type = T2; - }; - -.SH Example - - -// Run this code - - #include - #include - #include - - template - static auto constexpr get(std::pair const& pair) - -> typename std::tuple_element::type - { - return N == 0 ? pair.first : pair.second; - } - - int main() - { - auto var = std::make_pair(1, std::string{"one"}); - - std::cout << get<0>(var) << " = " << get<1>(var); - } - -.SH Output: - - 1 = one - -.SH See also - - tuple_element obtains the type of the specified element - \fI(class template specialization)\fP - std::tuple_element obtains the type of the elements of array - \fI(class template specialization)\fP - std::tuple_size obtains the size of a pair - \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::tuple_element.3 b/man/std::tuple_element.3 deleted file mode 100644 index dfb999442..000000000 --- a/man/std::tuple_element.3 +++ /dev/null @@ -1,81 +0,0 @@ -.TH std::tuple_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< std::size_t I, class T > \fB(1)\fP \fI(since C++11)\fP - class tuple_element; /* undefined */ - template< std::size_t I, class... Types > \fB(2)\fP \fI(since C++11)\fP - class tuple_element< I, tuple >; - template< std::size_t I, class T > - - class tuple_element< I, const T > { - typedef typename \fB(3)\fP \fI(since C++11)\fP - std::add_const::type>::type type; - - }; - template< std::size_t I, class T > - - class tuple_element< I, volatile T > { - typedef typename \fB(4)\fP \fI(since C++11)\fP - std::add_volatile::type>::type type; - - }; - template< size_t I, class T > - - class tuple_element< I, const volatile T > { - typedef typename \fB(5)\fP \fI(since C++11)\fP - std::add_cv::type>::type - type; - - }; - - Provides compile-type indexed access to the types of the elements of the tuple. - -.SH Member types - - Member type Definition - type the type of Ith element of the tuple, where I is in [0, - sizeof...(Types)) - -.SH Possible implementation - - template< std::size_t I, class T > - struct tuple_element; - - // recursive case - template< std::size_t I, class Head, class... Tail > - struct tuple_element> - : std::tuple_element> { }; - - // base case - template< class Head, class... Tail > - struct tuple_element<0, std::tuple> { - typedef Head type; - }; - -.SH Example - - -// Run this code - - #include - - template - struct type_list - { - template - using type = typename std::tuple_element>::type; - }; - - int main() - { - type_list::type<2> x = true; - } - -.SH See also - - std::tuple_element obtains the type of the elements of array - \fI(class template specialization)\fP - std::tuple_element obtains the type of the elements of pair - \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::tuple_size(std::array).3 b/man/std::tuple_size(std::array).3 deleted file mode 100644 index e6f3b68d9..000000000 --- a/man/std::tuple_size(std::array).3 +++ /dev/null @@ -1,58 +0,0 @@ -.TH std::tuple_size(std::array) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T, size_t N > - - class tuple_size< array > : \fB(1)\fP \fI(since C++11)\fP - public integral_constant - - { }; - - Provides access to the number of elements in an std::array as a compile-time - constant expression. - -.SH Member constants - - value N, the number of elements in the array - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator std::size_t converts the object to std::size_t, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type std::size_t - type std::integral_constant - -.SH Example - - -// Run this code - - #include - #include - - template - void test(T t) - { - int a[std::tuple_size::value]; // can be used at compile time - std::cout << std::tuple_size::value << '\\n'; - } - - int main() - { - std::array arr; - test(arr); - } - -.SH Output: - - 3 - -.SH See also - - tuple_size obtains the size of tuple at compile time - \fI(class template specialization)\fP diff --git a/man/std::tuple_size.3 b/man/std::tuple_size.3 new file mode 100644 index 000000000..f07fde238 --- /dev/null +++ b/man/std::tuple_size.3 @@ -0,0 +1,87 @@ +.TH std::tuple_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tuple_size \- std::tuple_size + +.SH Synopsis + Defined in header + template< class T1, class T2 > + + struct tuple_size> \fI(since C++11)\fP + + : std::integral_constant { }; + + The partial specialization of std::tuple_size for pairs provides a compile-time way + to obtain the number of elements in a pair, which is always 2, using tuple-like + syntax. + +.SH Member constants + + value the constant value 2 + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator std::size_t converts the object to std::size_t, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type std::size_t + type std::integral_constant + +.SH Example + + +// Run this code + + #include + #include + #include + + template + void test([[maybe_unused]]T t) + { + [[maybe_unused]] + int a[std::tuple_size::value]; // can be used at compile time + std::cout << std::tuple_size::value << '\\n'; // or at run time + } + + int main() + { + test(std::make_tuple(1, 2, 3.14)); + test(std::make_pair(1, 3.14)); + } + +.SH Output: + + 3 + 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2313 C++11 specializations for pair were not required to required + be derived from integral_constant + +.SH See also + + Structured binding \fI(C++17)\fP binds the specified names to sub-objects or + tuple elements of the initializer + tuple_size obtains the number of elements of a + \fI(C++11)\fP tuple-like type + \fI(class template)\fP + std::tuple_size obtains the size of an array + \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_size obtains the size of tuple at compile time + \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_size obtains the number of components of a + (C++20) std::ranges::subrange + \fI(class template specialization)\fP + std::tuple_element obtains the type of the elements of pair + \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::tuple_size.3 b/man/std::tuple_size.3 deleted file mode 100644 index 64f9ef6fa..000000000 --- a/man/std::tuple_size.3 +++ /dev/null @@ -1,66 +0,0 @@ -.TH std::tuple_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T1, class T2 > \fI(since C++11)\fP - struct tuple_size>; \fI(until C++14)\fP - template - - struct tuple_size> \fI(since C++14)\fP - - : std::integral_constant { }; - - The partial specialization of std::tuple_size for pairs provides a compile-time way - to obtain the number of elements in a pair, which is always 2, using tuple-like - syntax. - -.SH Member constants - - value the constant value 2 - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator std::size_t converts the object to std::size_t, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type std::size_t - type std::integral_constant - -.SH Example - - -// Run this code - - #include - #include - #include - - template - void test(T t) - { - int a[std::tuple_size::value]; // can be used at compile time - std::cout << std::tuple_size::value << '\\n'; // or at run time - } - - int main() - { - test(std::make_tuple(1, 2, 3.14)); - test(std::make_pair(1, 3.14)); - } - -.SH Output: - - 3 - 2 - -.SH See also - - tuple_size obtains the size of tuple at compile time - \fI(class template specialization)\fP - std::tuple_size obtains the size of an array - \fI(class template specialization)\fP - std::tuple_element obtains the type of the elements of pair - \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::tuple_size.3 b/man/std::tuple_size.3 deleted file mode 100644 index 9f02ac63b..000000000 --- a/man/std::tuple_size.3 +++ /dev/null @@ -1,89 +0,0 @@ -.TH std::tuple_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - class tuple_size; /*undefined*/ - template< class... Types > - - class tuple_size< std::tuple > \fB(2)\fP \fI(since C++11)\fP - - : public std::integral_constant { - }; - template< class T > - - class tuple_size \fB(3)\fP \fI(since C++11)\fP - - : public std::integral_constant::value> { }; - template< class T > - - class tuple_size< volatile T > \fB(4)\fP \fI(since C++11)\fP - - : public std::integral_constant::value> { }; - template< class T > - - class tuple_size< const volatile T > \fB(5)\fP \fI(since C++11)\fP - - : public std::integral_constant::value> { }; - - Provides access to the number of elements in a tuple as a compile-time constant - expression. - -.SH Member constants - - value sizeof...(Types) - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator std::size_t converts the object to std::size_t, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type std::size_t - type std::integral_constant - -.SH Notes - - All specializations of std::tuple_size satisfy UnaryTypeTrait with - BaseCharacteristic std::integral_constant for some N. - -.SH Example - - -// Run this code - - #include - #include - - template - void test(T t) - { - int a[std::tuple_size::value]; // can be used at compile time - - std::cout << std::tuple_size::value << '\\n'; // or at run time - } - - int main() - { - test(std::make_tuple(1, 2, 3.14)); - } - -.SH Output: - - 3 - -.SH See also - - std::tuple_size obtains the size of an array - \fI(class template specialization)\fP - std::tuple_size obtains the size of a pair - \fI(C++11)\fP \fI(class template specialization)\fP - std::get(std::tuple) tuple accesses specified element - \fI(function template)\fP - tuple_element obtains the type of the specified element - \fI(class template specialization)\fP diff --git a/man/std::tx_exception.3 b/man/std::tx_exception.3 new file mode 100644 index 000000000..2ece47276 --- /dev/null +++ b/man/std::tx_exception.3 @@ -0,0 +1,89 @@ +.TH std::tx_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::tx_exception \- std::tx_exception + +.SH Synopsis + Defined in header + template< class T > (TM TS) + class tx_exception : public std::runtime_error; + + Defines an exception type that can be used to cancel and roll back an atomic + transaction initiated by the keyword atomic_cancel. + + If T is not TriviallyCopyable, the program that specializes std::tx_exception is + ill-formed. + +.SH Member functions + +std::tx_exception::tx_exception + + explicit tx_exception( T value ) transaction_safe; \fB(1)\fP (TM TS) + tx_exception( T value, const std::string& what_arg ) transaction_safe; \fB(2)\fP (TM TS) + tx_exception( T value, const char* what_arg ) transaction_safe; \fB(3)\fP (TM TS) + tx_exception( const tx_exception& other ) transaction_safe noexcept; \fB(4)\fP (TM TS) + + 1-3) Constructs the exception object with what_arg as explanatory string that can be + accessed through what() and value as the object that can be accessed through get(). + 4) Copy constructor. If *this and other both have dynamic type std::tx_exception + then std::strcmp(what(), other.what()) == 0. + +.SH Parameters + + value - payload object + what_arg - explanatory string + other - another exception object to copy + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. + +std::tx_exception::operator= + + tx_exception& operator=( const tx_exception& other ) transaction_safe (TM TS) + noexcept; + + Assigns the contents with those of other. If *this and other both have dynamic type + std::tx_exception then std::strcmp(what(), other.what()) == 0 after assignment. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +std::tx_exception::get + + T get() const transaction_safe; (TM TS) + + Returns the payload object held by the exception object. + +.SH Exceptions + + May throw implementation-defined exceptions. + +std::tx_exception::what + + virtual const char* what() const transaction_safe_dynamic noexcept; (TM TS) + + Returns the explanatory string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to a null-terminated string with explanatory information. + +Inherited from std::runtime_error + +Inherited from std::exception + +.SH Member functions + + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + what returns an explanatory string + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP diff --git a/man/std::type_identity.3 b/man/std::type_identity.3 new file mode 100644 index 000000000..f7a62b2b7 --- /dev/null +++ b/man/std::type_identity.3 @@ -0,0 +1,65 @@ +.TH std::type_identity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_identity \- std::type_identity + +.SH Synopsis + Defined in header + template< class T > \fI(since C++20)\fP + struct type_identity; + + Provides the member typedef type that names T (i.e., the identity transformation). + + If the program adds specializations for std::type_identity, the behavior is + undefined. + +.SH Member types + + Name Definition + type T + +.SH Helper types + + template< class T > \fI(since C++20)\fP + using type_identity_t = type_identity::type; + +.SH Possible implementation + + template + struct type_identity { using type = T; }; + +.SH Notes + + std::type_identity can be used to establish non-deduced contexts in template + argument deduction. + + Feature-test macro Value Std Feature + __cpp_lib_type_identity 201806L (C++20) std::type_identity + +.SH Example + + +// Run this code + + #include + #include + + template + T foo(T a, T b) { return a + b; } + + template + T bar(T a, std::type_identity_t b) { return a + b; } + + int main() + { + // foo(4.2, 1); // error, deduced conflicting types for 'T' + std::cout << bar(4.2, 1) << '\\n'; // OK, calls bar + } + +.SH Output: + + 5.2 + +.SH See also + + identity function object that returns its argument unchanged + (C++20) \fI(class)\fP diff --git a/man/std::type_index.3 b/man/std::type_index.3 index e93bd5a87..214f95832 100644 --- a/man/std::type_index.3 +++ b/man/std::type_index.3 @@ -1,4 +1,7 @@ -.TH std::type_index 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_index 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_index \- std::type_index + .SH Synopsis Defined in header class type_index; \fI(since C++11)\fP @@ -10,69 +13,77 @@ .SH Member functions - constructor constructs the object - \fI(public member function)\fP + constructor constructs the object + \fI(public member function)\fP + destructor destroys the type_index object + (implicitly declared) \fI(public member function)\fP + operator= assigns a type_index object + (implicitly declared) \fI(public member function)\fP operator== operator!= - operator< compares the underlying std::type_info objects - operator<= \fI(public member function)\fP - operator> + operator< + operator<= compares the underlying std::type_info objects + operator> \fI(public member function)\fP operator>= - hash_code returns hashed code - \fI(public member function)\fP - returns implementation defined name of the type, - name associated with underlying type_info object - \fI(public member function)\fP + operator<=> + (removed in C++20) + (C++20) + hash_code returns hashed code + \fI(public member function)\fP + returns implementation defined name of the type, + name associated with underlying type_info object + \fI(public member function)\fP .SH Helper classes std::hash hash support for std::type_index - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP .SH Example The following program is an example of an efficient type-value mapping. - + // Run this code #include - #include + #include + #include #include + #include #include - #include - #include - - struct A { + + struct A + { virtual ~A() {} }; - + struct B : A {}; struct C : A {}; - + int main() { std::unordered_map type_names; - + type_names[std::type_index(typeid(int))] = "int"; type_names[std::type_index(typeid(double))] = "double"; type_names[std::type_index(typeid(A))] = "A"; type_names[std::type_index(typeid(B))] = "B"; type_names[std::type_index(typeid(C))] = "C"; - + int i; double d; A a; - + // note that we're storing pointer to type A std::unique_ptr b(new B); std::unique_ptr c(new C); - + std::cout << "i is " << type_names[std::type_index(typeid(i))] << '\\n'; std::cout << "d is " << type_names[std::type_index(typeid(d))] << '\\n'; std::cout << "a is " << type_names[std::type_index(typeid(a))] << '\\n'; - std::cout << "b is " << type_names[std::type_index(typeid(*b))] << '\\n'; - std::cout << "c is " << type_names[std::type_index(typeid(*c))] << '\\n'; + std::cout << "*b is " << type_names[std::type_index(typeid(*b))] << '\\n'; + std::cout << "*c is " << type_names[std::type_index(typeid(*c))] << '\\n'; } .SH Output: @@ -80,11 +91,11 @@ i is int d is double a is A - b is B - c is C + *b is B + *c is C .SH See also contains some type's information, generated by the implementation. - type_info This is the class, returned by the typeid operator - \fI(class)\fP + type_info This is the class returned by the typeid operator. + \fI(class)\fP diff --git a/man/std::type_index::hash_code.3 b/man/std::type_index::hash_code.3 index 824003742..6537834e3 100644 --- a/man/std::type_index::hash_code.3 +++ b/man/std::type_index::hash_code.3 @@ -1,6 +1,9 @@ -.TH std::type_index::hash_code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_index::hash_code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_index::hash_code \- std::type_index::hash_code + .SH Synopsis - size_t hash_code() const; \fI(since C++11)\fP + std::size_t hash_code() const noexcept; \fI(since C++11)\fP Returns the hash code of the associated std::type_info object. Equivalent to calling type_info::hash_code directly. @@ -11,25 +14,26 @@ .SH Return value - The hash code of the associated type_info object. - -.SH Exceptions - - \fI(none)\fP \fI(until C++14)\fP - noexcept specification: - noexcept \fI(since C++14)\fP - + The hash code of the associated std::type_info object. .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2144 C++11 type_index::hash_code was not required to be required + noexcept + .SH See also std::hash hash support for std::type_index - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP .SH Category: - * Todo no example diff --git a/man/std::type_index::name.3 b/man/std::type_index::name.3 index 8017a4471..35ee93064 100644 --- a/man/std::type_index::name.3 +++ b/man/std::type_index::name.3 @@ -1,6 +1,9 @@ -.TH std::type_index::name 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_index::name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_index::name \- std::type_index::name + .SH Synopsis - const char* name() const; \fI(since C++11)\fP + const char* name() const noexcept; \fI(since C++11)\fP Returns the name of the associated std::type_info object. Equivalent to calling std::type_info::name() directly. @@ -11,20 +14,28 @@ .SH Return value - The name of the associated type_info object. + The name of the associated std::type_info object. -.SH Exceptions +.SH Example - \fI(none)\fP \fI(until C++14)\fP - noexcept specification: - noexcept \fI(since C++14)\fP - -.SH Example +// Run this code + + #include + #include + int main() { + std::cout << std::type_index(typeid(std::cout)).name(); + } + +.SH Possible output: + + NSt3__113basic_ostreamIcNS_11char_traitsIcEEEE - This section is incomplete - Reason: no example + Defect reports -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo no example + DR Applied to Behavior as published Correct behavior + LWG 2144 C++11 type_index::name was not required to be required + noexcept diff --git a/man/std::type_index::operator==,!=,,>=,.3 b/man/std::type_index::operator==,!=,,>=,.3 new file mode 100644 index 000000000..2884e36e3 --- /dev/null +++ b/man/std::type_index::operator==,!=,,>=,.3 @@ -0,0 +1,39 @@ +.TH std::type_index::operator==,!=,,>=, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_index::operator==,!=,,>=, \- std::type_index::operator==,!=,,>=, + +.SH Synopsis + bool operator==( const type_index& rhs ) const noexcept; \fB(1)\fP \fI(since C++11)\fP + bool operator!=( const type_index& rhs ) const noexcept; \fB(2)\fP \fI(since C++11)\fP + \fI(until C++20)\fP + bool operator<( const type_index& rhs ) const noexcept; \fB(3)\fP \fI(since C++11)\fP + bool operator<=( const type_index& rhs ) const noexcept; \fB(4)\fP \fI(since C++11)\fP + bool operator>( const type_index& rhs ) const noexcept; \fB(5)\fP \fI(since C++11)\fP + bool operator>=( const type_index& rhs ) const noexcept; \fB(6)\fP \fI(since C++11)\fP + std::strong_ordering operator<=>( const type_index& rhs ) const \fB(7)\fP \fI(since C++20)\fP + noexcept; + + Compares the underlying std::type_info objects. + + 1,2) Checks whether the underlying std::type_info objects refer to the same type. + 3-7) Compares the underlying std::type_info objects as defined by an + implementation-defined ordering. The comparison is done by type_info::before. + + The != operator is synthesized from operator==. \fI(since C++20)\fP + +.SH Parameters + + rhs - another type_index object to compare to + +.SH Return value + + 1) true if the underlying std::type_info objects refer to the same type, false + otherwise. + 2) true if the underlying std::type_info objects refer not to the same type, false + otherwise. + 3-6) true if the types referred by the underlying std::type_info objects are ordered + by corresponding order, false otherwise. + 7) std::strong_ordering::equal if the underlying std::type_info objects refer to the + same type, otherwise std::strong_ordering::less if *this's underlying std::type_info + object precedes rhs's in the implementation-defined ordering, otherwise + std::strong_ordering::greater. diff --git a/man/std::type_index::operator==,!=,<,<=,>,>=.3 b/man/std::type_index::operator==,!=,<,<=,>,>=.3 deleted file mode 100644 index 52bfe10e2..000000000 --- a/man/std::type_index::operator==,!=,<,<=,>,>=.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH std::type_index::operator==,!=,<,<=,>,>= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - bool operator==( const type_index& rhs ) const; \fI(since C++11)\fP - bool operator!=( const type_index& rhs ) const; \fI(since C++11)\fP - bool operator<( const type_index& rhs ) const; \fI(since C++11)\fP - bool operator<=( const type_index& rhs ) const; \fI(since C++11)\fP - bool operator>( const type_index& rhs ) const; \fI(since C++11)\fP - bool operator>=( const type_index& rhs ) const; \fI(since C++11)\fP - - Compares the underlying std::type_info objects. - - 1-2) Checks whether the underlying std::type_info objects refer to the same type. - - 3-6) Compares the underlying std::type_info objects as defined by an - implementation-defined ordering. The comparison is done by type_info::before. - -.SH Parameters - - rhs - another type_index object to compare to - -.SH Return value - - 1) true if the underlying std::type_info objects refer to the same type, false - otherwise - - 2) true if the underlying std::type_info objects refer not to the same type, false - otherwise - - 3-6) true if the types referred by the underlying std::type_info objects are ordered - by corresponding order, false otherwise. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::type_index::type_index.3 b/man/std::type_index::type_index.3 index 2e65bc835..2c5a37a41 100644 --- a/man/std::type_index::type_index.3 +++ b/man/std::type_index::type_index.3 @@ -1,6 +1,9 @@ -.TH std::type_index::type_index 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_index::type_index 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_index::type_index \- std::type_index::type_index + .SH Synopsis - type_index( const std::type_info& info ); \fI(since C++11)\fP + type_index( const std::type_info& info ) noexcept; \fI(since C++11)\fP Constructs the type index from std::type_info object. @@ -14,5 +17,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::type_info.3 b/man/std::type_info.3 index 8b6e74801..91ac515ff 100644 --- a/man/std::type_info.3 +++ b/man/std::type_info.3 @@ -1,4 +1,7 @@ -.TH std::type_info 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_info \- std::type_info + .SH Synopsis Defined in header class type_info; @@ -11,26 +14,30 @@ .SH Member functions - constructor has neither default nor copy constructors - [deleted] \fI(public member function)\fP - destructor derived objects are safe to delete through pointer-to-base - \fB[virtual]\fP \fI(virtual public member function)\fP - operator= can not be copy-assigned - [deleted] \fI(public member function)\fP - operator== checks whether the objects refer to the same type - operator!= \fI(public member function)\fP - checks whether the referred type precedes referred type of another - type_index - before object in the implementation defined order, i.e. orders the referred - types - \fI(public member function)\fP - hash_code returns a value which is identical for the same types - \fI(C++11)\fP \fI(public member function)\fP - name implementation defined name of the type - \fI(public member function)\fP + constructor has neither default nor copy constructors + [deleted] \fI(public member function)\fP + destructor the virtual destructor makes type_info a polymorphic class + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= can not be copy-assigned + [deleted] \fI(public member function)\fP + operator== checks whether the objects refer to the same type + operator!= \fI(public member function)\fP + (removed in C++20) + checks whether the referred type precedes referred type of + another type_info + before object in the implementation defined order, i.e. orders the + referred types + \fI(public member function)\fP + hash_code returns a value which is identical for the same types + \fI(C++11)\fP \fI(public member function)\fP + name implementation defined name of the type + \fI(public member function)\fP .SH See also type_index wrapper around a type_info object, that can be used as index in \fI(C++11)\fP associative and unordered associative containers - \fI(class)\fP + \fI(class)\fP + Queries information of a type, returning a std::type_info object + typeid representing the type + (built-in operator) diff --git a/man/std::type_info::before.3 b/man/std::type_info::before.3 index ec71467e5..057cece52 100644 --- a/man/std::type_info::before.3 +++ b/man/std::type_info::before.3 @@ -1,9 +1,13 @@ -.TH std::type_info::before 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_info::before 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_info::before \- std::type_info::before + .SH Synopsis - bool before( const type_info& rhs ); + bool before( const type_info& rhs ) const; \fI(until C++11)\fP + bool before( const type_info& rhs ) const noexcept; \fI(since C++11)\fP - Returns true if the referred type precedes type, referred to by rhs in the - implementation's collation order. No guarantees are given, in particular, the + Returns true if the type of this type_info precedes the type of rhs in the + implementation's collation order. No guarantees are given; in particular, the collation order can change between the invocations of the same program. .SH Parameters @@ -12,19 +16,31 @@ .SH Return value - true if the referred type precedes type, referred to by rhs in the implementation's + true if the type of this type_info precedes the type of rhs in the implementation's collation order. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code + + #include + #include - operator== checks whether the objects refer to the same type - operator!= \fI(public member function)\fP + int main() + { + if (typeid(int).before(typeid(char))) + std::cout << "int goes before char in this implementation.\\n"; + else + std::cout << "char goes before int in this implementation.\\n"; + } -.SH Category: +.SH Possible output: + + char goes before int in this implementation. + +.SH See also - * Todo no example + operator== checks whether the objects refer to the same type + operator!= \fI(public member function)\fP + (removed in C++20) diff --git a/man/std::type_info::hash_code.3 b/man/std::type_info::hash_code.3 index 2d9a45b38..424e1f002 100644 --- a/man/std::type_info::hash_code.3 +++ b/man/std::type_info::hash_code.3 @@ -1,11 +1,17 @@ -.TH std::type_info::hash_code 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_info::hash_code 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_info::hash_code \- std::type_info::hash_code + .SH Synopsis - size_t hash_code() const; \fI(since C++11)\fP + std::size_t hash_code() const noexcept; \fI(since C++11)\fP + + Returns an unspecified value (here denoted by hash code) such that for all + std::type_info objects referring to the same type, their hash code is the same. - Returns an unspecified value, which is identical for the type_info objects referring - to the same type. No other guarantees are given. For example, the same value may be - returned for different types. The value can also change between invocations of the - same program. + No other guarantees are given: std::type_info objects referring to different types + may have the same hash code (although the standard recommends that implementations + avoid this as much as possible), and hash code for the same type can change between + invocations of the same program. .SH Parameters @@ -13,69 +19,72 @@ .SH Return value - Some value, which is identical for the same types. + A value that is identical for all std::type_info objects referring to the same type. .SH Example The following program is an example of an efficient type-value mapping without using std::type_index. - + // Run this code + #include #include + #include + #include #include #include - #include - #include - #include - - struct A { + + struct A + { virtual ~A() {} }; - + struct B : A {}; struct C : A {}; - + using TypeInfoRef = std::reference_wrapper; - - struct Hasher { + + struct Hasher + { std::size_t operator()(TypeInfoRef code) const { return code.get().hash_code(); } }; - - struct EqualTo { + + struct EqualTo + { bool operator()(TypeInfoRef lhs, TypeInfoRef rhs) const { return lhs.get() == rhs.get(); } }; - + int main() { std::unordered_map type_names; - + type_names[typeid(int)] = "int"; type_names[typeid(double)] = "double"; type_names[typeid(A)] = "A"; type_names[typeid(B)] = "B"; type_names[typeid(C)] = "C"; - + int i; double d; A a; - + // note that we're storing pointer to type A std::unique_ptr b(new B); std::unique_ptr c(new C); - + std::cout << "i is " << type_names[typeid(i)] << '\\n'; std::cout << "d is " << type_names[typeid(d)] << '\\n'; std::cout << "a is " << type_names[typeid(a)] << '\\n'; - std::cout << "b is " << type_names[typeid(*b)] << '\\n'; - std::cout << "c is " << type_names[typeid(*c)] << '\\n'; + std::cout << "*b is " << type_names[typeid(*b)] << '\\n'; + std::cout << "*c is " << type_names[typeid(*c)] << '\\n'; } .SH Output: @@ -83,12 +92,13 @@ i is int d is double a is A - b is B - c is C + *b is B + *c is C .SH See also - operator== checks whether the objects refer to the same type - operator!= \fI(public member function)\fP - name implementation defined name of the type - \fI(public member function)\fP + operator== checks whether the objects refer to the same type + operator!= \fI(public member function)\fP + (removed in C++20) + name implementation defined name of the type + \fI(public member function)\fP diff --git a/man/std::type_info::name.3 b/man/std::type_info::name.3 index 79d9a8bc4..ff54b60a0 100644 --- a/man/std::type_info::name.3 +++ b/man/std::type_info::name.3 @@ -1,9 +1,13 @@ -.TH std::type_info::name 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_info::name 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_info::name \- std::type_info::name + .SH Synopsis - const char* name() const; + const char* name() const; \fI(until C++11)\fP + const char* name() const noexcept; \fI(since C++11)\fP Returns an implementation defined null-terminated character string containing the - name of the type. No guarantees are given, in particular, the returned string can be + name of the type. No guarantees are given; in particular, the returned string can be identical for several types and change between invocations of the same program. .SH Parameters @@ -12,23 +16,68 @@ .SH Return value - null-terminated character string containing the name of the type. + Null-terminated character string containing the name of the type. .SH Notes - With compilers such as gcc and clang, the returned string can be piped through - c++filt -t to be converted to human-readable form. + The lifetime of the array pointed to by the returned pointer is not specified, but + in practice it persists as long as the RTTI data structure for the given type + exists, which has application lifetime unless loaded from a dynamic library (that + can be unloaded). + + Some implementations (such as MSVC, IBM, Oracle) produce a human-readable type name. + Others, most notably gcc and clang, return the mangled name, which is specified by + the Itanium C++ ABI. The mangled name can be converted to human-readable form using + implementation-specific API such as abi::__cxa_demangle directly or through + boost::core::demangle. It can also be piped through the command-line utility c++filt + -t. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - hash_code returns a value which is identical for the same types - \fI(C++11)\fP \fI(public member function)\fP + #include + #include + #include + #include + #include + + struct Base { virtual ~Base() = default; }; + struct Derived : Base {}; + + int main() + { + Base b1; + Derived d1; + + const Base* pb = &b1; + std::cout << typeid(*pb).name() << '\\n'; + pb = &d1; + std::cout << typeid(*pb).name() << '\\n'; -.SH Category: + std::string real_name = boost::core::demangle(typeid(pb).name()); + std::cout << typeid(pb).name() << " => " << real_name << '\\n'; - * Todo no example + std::cout << "c++filt => " << std::flush; + std::string s = typeid(pb).name(); + std::system(("c++filt -t " + s).data()); + } + +.SH Possible output: + + // GCC/Clang: + 4Base + 7Derived + PK4Base => Base const* + c++filt => Base const* + + // MSVC: + struct Base + struct Derived + struct Base const * __ptr64 => struct Base const * __ptr64 + +.SH See also + + hash_code returns a value which is identical for the same types + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::type_info::operator==,std::type_info::operator!=.3 b/man/std::type_info::operator==,std::type_info::operator!=.3 index b2f2f590e..00c198511 100644 --- a/man/std::type_info::operator==,std::type_info::operator!=.3 +++ b/man/std::type_info::operator==,std::type_info::operator!=.3 @@ -1,76 +1,98 @@ -.TH std::type_info::operator==,std::type_info::operator!= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_info::operator==,std::type_info::operator!= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_info::operator==,std::type_info::operator!= \- std::type_info::operator==,std::type_info::operator!= + .SH Synopsis - bool operator==( const type_info& rhs ) const; - bool operator!=( const type_info& rhs ) const; + bool operator==( const type_info& rhs ) const; \fI(until C++11)\fP + bool operator==( const type_info& rhs ) const \fI(since C++11)\fP + noexcept; (until C++23) + constexpr bool operator==( const type_info& rhs \fB(1)\fP (since C++23) + ) const noexcept; + bool operator!=( const type_info& rhs ) const; \fI(until C++11)\fP + bool operator!=( const type_info& rhs ) const \fB(2)\fP \fI(since C++11)\fP + noexcept; \fI(until C++20)\fP Checks if the objects refer to the same types. + The != operator is synthesized from operator==. \fI(since C++20)\fP + .SH Parameters rhs - another type information object to compare to .SH Return value - true if the comparison operation holds true, false otherwise + true if the comparison operation holds true, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_typeinfo 202106L (C++23) Constexpr for + std::type_info::operator== .SH Example - + // Run this code #include - #include #include + #include #include - + class person { - public: - - person(std::string&& n) : _name(n) {} - virtual const std::string& name() const{ return _name; } - - private: - - std::string _name; + public: + explicit person(std::string n) : name_(std::move(n)) {} + virtual const std::string& name() const { return name_; } + + private: + std::string name_; }; - + class employee : public person { - public: - - employee(std::string&& n, std::string&& p) : - person(std::move(n)), _profession(std::move(p)) {} - - const std::string& profession() const { return _profession; } - - private: - - std::string _profession; + public: + employee(std::string n, std::string p) + : person(std::move(n)), profession_(std::move(p)) {} + + const std::string& profession() const { return profession_; } + + private: + std::string profession_; }; - - void somefunc(const person& p) + + void print_info(const person& p) { - if(typeid(employee) == typeid(p)) - { - std::cout << p.name() << " is an employee "; - auto& emp = dynamic_cast(p); - std::cout << "who works in " << emp.profession() << '\\n'; - } + if (typeid(person) == typeid(p)) + std::cout << p.name() << " is not an employee\\n"; + else if (typeid(employee) == typeid(p)) + { + std::cout << p.name() << " is an employee "; + auto& emp = dynamic_cast(p); + std::cout << "who works in " << emp.profession() << '\\n'; + } } - + int main() { - employee paul("Paul","Economics"); - somefunc(paul); + print_info(employee{"Paul","Economics"}); + print_info(person{"Kate"}); + + #if __cpp_lib_constexpr_typeinfo + if constexpr (typeid(employee) != typeid(person)) // C++23 + std::cout << "class `employee` != class `person`\\n"; + #endif } -.SH Output: +.SH Possible output: Paul is an employee who works in Economics + Kate is not an employee + class `employee` != class `person` .SH See also - checks whether the referred type precedes referred type of another type_index + checks whether the referred type precedes referred type of another type_info before object in the implementation defined order, i.e. orders the referred types - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::type_info::~type_info.3 b/man/std::type_info::~type_info.3 index 29e25ccc0..89767ceba 100644 --- a/man/std::type_info::~type_info.3 +++ b/man/std::type_info::~type_info.3 @@ -1,7 +1,17 @@ -.TH std::type_info::~type_info 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::type_info::~type_info 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::type_info::~type_info \- std::type_info::~type_info + .SH Synopsis - virtual ˜type_info(); + virtual ~type_info(); Destructs an object of type std::type_info. This destructor is public virtual, - allowing objects of classes, derived from std::type_info to be safely deleted - through pointers to base class. + making the std::type_info a polymorphic class. + +.SH Notes + + The dynamic type of a std::type_info subobject may be examined by the typeid + operator. + + It is unspecified whether the implementation calls this destructor for any + std::type_info object at the end of the program. diff --git a/man/std::u16string.3 b/man/std::u16string.3 deleted file mode 120000 index 51b9e0d1f..000000000 --- a/man/std::u16string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string.3 \ No newline at end of file diff --git a/man/std::u16string.3 b/man/std::u16string.3 new file mode 100644 index 000000000..ba00dc78d --- /dev/null +++ b/man/std::u16string.3 @@ -0,0 +1,397 @@ +.TH std::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string \- std::basic_string + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, \fB(1)\fP + class Allocator = std::allocator + + > class basic_string; + namespace pmr { + + template< + class CharT, + class Traits = std::char_traits \fB(2)\fP \fI(since C++17)\fP + > using basic_string = + std::basic_string>; + + } + + The class template basic_string stores and manipulates sequences of character-like + objects, which are non-array objects of TrivialType and StandardLayoutType. The + class is dependent neither on the character type nor on the nature of operations on + that type. The definitions of the operations are supplied via the Traits template + parameter - a specialization of std::char_traits or a compatible traits class. + + The elements of a basic_string are stored contiguously, that is, for a basic_string + s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()) + , and *(s.begin() + s.size()) has value CharT() (a null terminator) + \fI(since C++11)\fP; or, equivalently, a pointer to s[0] can be passed to functions that + expect a pointer to the first element of + an array + \fI(until C++11)\fP + a null-terminated array + \fI(since C++11)\fP of CharT. + + std::basic_string satisfies the requirements of AllocatorAwareContainer (except that + customized construct/destroy are not used for construction/destruction of elements), + SequenceContainer + and ContiguousContainer + \fI(since C++17)\fP. + + If any of Traits::char_type and Allocator::char_type is different from CharT, the + program is ill-formed. + + Member functions of std::basic_string are constexpr: it is possible to + create and use std::string objects in the evaluation of a constant + expression. + \fI(since C++20)\fP + However, std::string objects generally cannot be constexpr, because + any dynamically allocated storage must be released in the same + evaluation of constant expression. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string std::basic_string + std::wstring std::basic_string + std::u8string (C++20) std::basic_string + std::u16string \fI(C++11)\fP std::basic_string + std::u32string \fI(C++11)\fP std::basic_string + std::pmr::string \fI(C++17)\fP std::pmr::basic_string + std::pmr::wstring \fI(C++17)\fP std::pmr::basic_string + std::pmr::u8string (C++20) std::pmr::basic_string + std::pmr::u16string \fI(C++17)\fP std::pmr::basic_string + std::pmr::u32string \fI(C++17)\fP std::pmr::basic_string + +.SH Template parameters + + CharT - character type + Traits - traits class specifying the operations on the character type + Allocator - Allocator type used to allocate internal storage + +.SH Member types + + Member type Definition + traits_type Traits + value_type CharT + allocator_type Allocator + Allocator::size_type \fI(until C++11)\fP + size_type std::allocator_traits::size_type \fI(since C++11)\fP + + + Allocator::difference_type (until + C++11) + difference_type std::allocator_traits::difference_type (since + C++11) + + + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP + const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator, + iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator, + const_iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + +.SH Member functions + + constructor constructs a basic_string + \fI(public member function)\fP + destroys the string, deallocating internal storage if + destructor used + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP +.SH Element access + at accesses the specified character with bounds checking + \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP + returns a non-modifiable standard C character array + c_str version of the string + \fI(public member function)\fP + operator basic_string_view returns a non-modifiable string_view into the entire + \fI(C++17)\fP string + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP +.SH Capacity + empty checks whether the string is empty + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + returns the number of characters that can be held in + capacity currently allocated storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP +.SH Modifiers + clear clears the contents + \fI(public member function)\fP + insert inserts characters + \fI(public member function)\fP + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP + pop_back removes the last character + (DR*) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + replace replaces specified portion of a string + \fI(public member function)\fP + replace_with_range replaces specified portion of a string with a range of + (C++23) characters + \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP + changes the number of characters stored and possibly + resize_and_overwrite overwrites indeterminate contents via user-provided + (C++23) operation + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Search + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Operations + compare compares two strings + \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string contains the given substring or + (C++23) character + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator+ concatenates two strings or a string and a char + \fI(function template)\fP + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + std::swap(std::basic_string) specializes the std::swap algorithm + \fI(function template)\fP + erase(std::basic_string) erases all elements satisfying specific criteria + erase_if(std::basic_string) \fI(function template)\fP + (C++20) +.SH Input/output + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + getline read data from an I/O stream into a string + \fI(function template)\fP +.SH Numeric conversions + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + stof + stod + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_literals + operator""s converts a character array literal to basic_string + \fI(C++14)\fP \fI(function)\fP + +.SH Helper classes + + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Although it is required that customized construct or destroy is used when + constructing or destroying elements of std::basic_string until C++23, all + implementations only used the default mechanism. The requirement is corrected by + P1072R10 to match existing practice. + + Feature-test macro Value Std Feature + __cpp_lib_string_udls 201304L \fI(C++14)\fP User-defined literals for + string types + __cpp_lib_starts_ends_with 201711L (C++20) starts_with, ends_with + __cpp_lib_constexpr_string 201907L (C++20) Constexpr for + std::basic_string + __cpp_lib_char8_t 201907L (C++20) std::u8string + __cpp_lib_erase_if 202002L (C++20) erase, erase_if + __cpp_lib_string_contains 202011L (C++23) contains + __cpp_lib_string_resize_and_overwrite 202110L (C++23) resize_and_overwrite + Member functions for + __cpp_lib_containers_ranges 202202L (C++23) construction, insertion, and + replacement that accept + container compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + // Creating a string from const char* + std::string str1 = "hello"; + + // Creating a string using string literal + auto str2 = "world"s; + + // Concatenating strings + std::string str3 = str1 + " " + str2; + + // Print out the result + std::cout << str3 << '\\n'; + + std::string::size_type pos = str3.find(" "); + str1 = str3.substr(pos + 1); // the part after the space + str2 = str3.substr(0, pos); // the part till the space + + std::cout << str1 << ' ' << str2 << '\\n'; + + // Accessing an element using subscript operator[] + std::cout << str1[0] << '\\n'; + str1[0] = 'W'; + std::cout << str1 << '\\n'; + } + +.SH Output: + + hello world + world hello + w + World + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + contiguity of the storage for elements of + LWG 530 C++98 basic_string required again + was accidently made not required by LWG259 + the behavior is undefined if any of the program is + LWG 2994 C++98 Traits::char_type^[1] ill-formed in this + (P1148R0) and Allocator::char_type is different from case + CharT + + 1. ↑ The Traits::char_type case is fixed in P1148R0. + +.SH See also + + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP + +.SH External links + + C++ string handling + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::u16string::append.3 b/man/std::u16string::append.3 deleted file mode 120000 index b50ac7eda..000000000 --- a/man/std::u16string::append.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::append.3 \ No newline at end of file diff --git a/man/std::u16string::append.3 b/man/std::u16string::append.3 new file mode 100644 index 000000000..dfcb8cb7a --- /dev/null +++ b/man/std::u16string::append.3 @@ -0,0 +1,185 @@ +.TH std::basic_string::append 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append \- std::basic_string::append + +.SH Synopsis + basic_string& append( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& append( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& append( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& append( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos ); C++20) + basic_string& append( const CharT* s, \fB(4)\fP (constexpr since + size_type count ); C++20) + basic_string& append( const CharT* s ); \fB(5)\fP (constexpr since + C++20) + template< class InputIt > (constexpr since + basic_string& append( InputIt first, InputIt \fB(6)\fP C++20) + last ); \fB(3)\fP + basic_string& append( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(7)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& append( const StringViewLike& t \fB(8)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& append( const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos ); + + Appends additional characters to the string. + + 1) Appends count copies of character ch. + 2) Appends string str. + 3) Appends a substring [pos, pos + count) of str. + * If the requested substring lasts past the end of the string, or if count == + npos, the appended substring is [pos, size()). + * If pos > str.size(), std::out_of_range is thrown. + 4) Appends characters in the range [s, s + count). This range can contain null + characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 5) Appends the null-terminated character string pointed to by s, as if by append(s, + Traits::length(s)). + 6) Appends characters in the range [first, last). + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload only participates in overload resolution if InputIt \fI(since C++11)\fP + qualifies as a LegacyInputIterator. + + 7) Appends characters from the initializer list ilist. + 8) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends all characters from sv as if by append(sv.data(), + sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends the characters from the subview [pos, pos + count) of + sv. + * If the requested subview extends past the end of sv, or if count == npos, the + appended subview is [pos, sv.size()). + * If pos >= sv.size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - number of characters to append + pos - the index of the first character to append + ch - character value to append + first, last - range of characters to append + str - string to append + s - pointer to the character string to append + ilist - initializer list with the characters to append + t - object convertible to std::basic_string_view with the characters to + append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::basic_string str = "string"; + const char* cptr = "C-string"; + const char carr[] = "Two and one"; + + std::string output; + + // 1) Append a char 3 times. + // Notice, this is the only overload accepting chars. + output.append(3, '*'); + std::cout << "1) " << output << '\\n'; + + // 2) Append a whole string + output.append(str); + std::cout << "2) " << output << '\\n'; + + // 3) Append part of a string (last 3 letters, in this case) + output.append(str, 3, 3); + std::cout << "3) " << output << '\\n'; + + // 4) Append part of a C-string + // Notice, because `append` returns *this, we can chain calls together + output.append(1, ' ').append(carr, 4); + std::cout << "4) " << output << '\\n'; + + // 5) Append a whole C-string + output.append(cptr); + std::cout << "5) " << output << '\\n'; + + // 6) Append range + output.append(&carr[3], std::end(carr)); + std::cout << "6) " << output << '\\n'; + + // 7) Append initializer list + output.append({' ', 'l', 'i', 's', 't'}); + std::cout << "7) " << output << '\\n'; + } + +.SH Output: + + 1) *** + 2) ***string + 3) ***stringing + 4) ***stringing Two + 5) ***stringing Two C-string + 6) ***stringing Two C-string and one + 7) ***stringing Two C-string and one list + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(8)\fP causes ambiguity in avoided by making it a + some cases template + +.SH See also + + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + strcat concatenates two strings + \fI(function)\fP + strncat concatenates a certain amount of characters of two strings + \fI(function)\fP + wcscat appends a copy of one wide string to another + \fI(function)\fP + appends a certain amount of wide characters from one wide string to + wcsncat another + \fI(function)\fP diff --git a/man/std::u16string::append_range.3 b/man/std::u16string::append_range.3 new file mode 100644 index 000000000..ede115277 --- /dev/null +++ b/man/std::u16string::append_range.3 @@ -0,0 +1,65 @@ +.TH std::basic_string::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append_range \- std::basic_string::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& append_range( R&& rg ); + + Appends all characters from the range rg. + + Equivalent to + + return append(std::basic_string( std::from_range, std::forward(rg), get_allocator())); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string head{"long long"}; + const auto tail = {' ', 'i', 'n', 't'}; + + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.append(tail.begin(), tail.end()); + #endif + + assert(head == "long long int"); + } + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::u16string::assign.3 b/man/std::u16string::assign.3 deleted file mode 120000 index b4f3ab165..000000000 --- a/man/std::u16string::assign.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::assign.3 \ No newline at end of file diff --git a/man/std::u16string::assign.3 b/man/std::u16string::assign.3 new file mode 100644 index 000000000..afbe7a690 --- /dev/null +++ b/man/std::u16string::assign.3 @@ -0,0 +1,210 @@ +.TH std::basic_string::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign \- std::basic_string::assign + +.SH Synopsis + basic_string& assign( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& assign( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& assign( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& assign( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos); C++20) + basic_string& assign( basic_string&& str ) \fI(since C++11)\fP + noexcept(/* see below */); \fB(4)\fP (constexpr since + C++20) + basic_string& assign( const CharT* s, \fB(5)\fP (constexpr since + size_type count ); C++20) + basic_string& assign( const CharT* s ); \fB(6)\fP (constexpr since + C++20) + template< class InputIt > \fB(3)\fP (constexpr since + basic_string& assign( InputIt first, InputIt \fB(7)\fP C++20) + last ); + basic_string& assign( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(8)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t \fB(9)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t, \fB(10)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos); + + Replaces the contents of the string. + + 1) Replaces the contents with count copies of character ch. + 2) Replaces the contents with a copy of str. Equivalent to *this = str;. + In particular, allocator propagation may take place. + \fI(since C++11)\fP + 3) Replaces the contents with a substring [pos, pos + count) of str. If the + requested substring lasts past the end of the string, or if count == npos, the + resulting substring is [pos, str.size()). If pos > str.size(), std::out_of_range is + thrown. + 4) Replaces the contents with those of str using move semantics. Equivalent to *this + = std::move(str). In particular, allocator propagation may take place. + 5) Replaces the contents with copies of the characters in the range [s, s + count). + This range can contain null characters. + 6) Replaces the contents with those of null-terminated character string pointed to + by s. The length of the string is determined by the first null character using + Traits::length(s). + 7) Replaces the contents with copies of the characters in the range [first, last). + This overload does not participate in overload resolution if InputIt does not + satisfy LegacyInputIterator. + \fI(since C++11)\fP + 8) Replaces the contents with those of the initializer list ilist. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of sv, as if by + assign(sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with the characters from the subview + [pos, pos + count) of sv. If the requested subview lasts past the end of sv, or if + count == npos, the resulting subview is [pos, sv.size()). If pos > sv.size(), + std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - size of the resulting string + pos - index of the first character to take + ch - value to initialize characters of the string with + first, last - range to copy the characters from + str - string to be used as source to initialize the characters with + s - pointer to a character string to use as source to initialize the + string with + ilist - std::initializer_list to initialize the characters of the string with + t - object (convertible to std::basic_string_view) to initialize the + characters of the string with +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in count. + 2) Linear in size of str. + 3) Linear in count. + 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 5) Linear in count. + 6) Linear in size of s. + 7) Linear in distance between first and last. + 8) Linear in size of ilist. + 9) Linear in size of t. + +.SH Exceptions + + 4) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + // assign(size_type count, CharT ch) + s.assign(4, '='); + std::cout << s << '\\n'; // "====" + + std::string const c("Exemplary"); + // assign(const basic_string& str) + s.assign(c); + std::cout << c << " == " << s << '\\n'; // "Exemplary == Exemplary" + + // assign(const basic_string& str, size_type pos, size_type count) + s.assign(c, 0, c.length() - 1); + std::cout << s << '\\n'; // "Exemplar"; + + // assign(basic_string&& str) + s.assign(std::string("C++ by ") + "example"); + std::cout << s << '\\n'; // "C++ by example" + + // assign(const CharT* s, size_type count) + s.assign("C-style string", 7); + std::cout << s << '\\n'; // "C-style" + + // assign(const CharT* s) + s.assign("C-style\\0string"); + std::cout << s << '\\n'; // "C-style" + + char mutable_c_str[] = "C-style string"; + // assign(InputIt first, InputIt last) + s.assign(std::begin(mutable_c_str), std::end(mutable_c_str) - 1); + std::cout << s << '\\n'; // "C-style string" + + // assign(std::initializer_list ilist) + s.assign({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << s << '\\n'; // "C-style" + } + +.SH Output: + + ==== + Exemplary == Exemplary + Exemplar + C++ by example +.SH C-style +.SH C-style + C-style string +.SH C-style + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + non-normative note stated that swap + LWG 2063 C++11 is corrected to require move + a valid implementation of assignment + move-assign + LWG 2579 C++11 assign(const basic_string&) made to propagate allocators + did not propagate allocators if needed + LWG 2946 C++17 overload \fB(9)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::assign_range.3 b/man/std::u16string::assign_range.3 new file mode 100644 index 000000000..7bfd17959 --- /dev/null +++ b/man/std::u16string::assign_range.3 @@ -0,0 +1,74 @@ +.TH std::basic_string::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign_range \- std::basic_string::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& assign_range( R&& rg ); + + Replaces the contents of the string with the values in the range rg. + + Equivalent to + + return assign( + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto source = {'s', 'o', 'u', 'r', 'c', 'e'}; + std::string destination{"destination"}; + + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.begin(), source.end()); + #endif + + assert(destination == "source"); + } + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP diff --git a/man/std::u16string::at.3 b/man/std::u16string::at.3 deleted file mode 120000 index 1f402dba2..000000000 --- a/man/std::u16string::at.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::at.3 \ No newline at end of file diff --git a/man/std::u16string::at.3 b/man/std::u16string::at.3 new file mode 100644 index 000000000..36e5a7e1d --- /dev/null +++ b/man/std::u16string::at.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::at \- std::basic_string::at + +.SH Synopsis + CharT& at( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& at( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("message"); // for capacity + + s = "abc"; + s.at(2) = 'x'; // OK + std::cout << s << '\\n'; + + std::cout << "string size = " << s.size() << '\\n'; + std::cout << "string capacity = " << s.capacity() << '\\n'; + + try + { + // This will throw since the requested offset is greater than the current size. + s.at(3) = 'x'; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + } + +.SH Possible output: + + abx + string size = 3 + string capacity = 7 + basic_string::at + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::back.3 b/man/std::u16string::back.3 deleted file mode 120000 index 33e85e2c2..000000000 --- a/man/std::u16string::back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::back.3 \ No newline at end of file diff --git a/man/std::u16string::back.3 b/man/std::u16string::back.3 new file mode 100644 index 000000000..5dd0d47ca --- /dev/null +++ b/man/std::u16string::back.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::back \- std::basic_string::back + +.SH Synopsis + CharT& back(); \fB(1)\fP (constexpr since C++20) + const CharT& back() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the last character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& back1 = s.back(); + back1 = 's'; + std::cout << s << '\\n'; // "Exemplars" + + std::string const c("Exemplary"); + char const& back2 = c.back(); + std::cout << back2 << '\\n'; // 'y' + } + +.SH Output: + + Exemplars + y + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function back() + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::basic_string.3 b/man/std::u16string::basic_string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::u16string::basic_string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::u16string::basic_string.3 b/man/std::u16string::basic_string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::u16string::basic_string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::u16string::begin,.3 b/man/std::u16string::begin,.3 new file mode 100644 index 000000000..a9b49707a --- /dev/null +++ b/man/std::u16string::begin,.3 @@ -0,0 +1,69 @@ +.TH std::basic_string::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::begin, \- std::basic_string::begin, + +.SH Synopsis + + iterator begin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the first character of the string. + + begin() returns a mutable or constant iterator, depending on the constness of *this. + + cbegin() always returns a constant iterator. It is equivalent to const_cast(*this).begin(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplar"); + *s.begin() = 'e'; + std::cout << s << '\\n'; + + auto i = s.cbegin(); + std::cout << *i << '\\n'; + // *i = 'E'; // error: i is a constant iterator + } + +.SH Output: + + exemplar + e + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::begin,std::basic_string::cbegin.3 b/man/std::u16string::begin,std::basic_string::cbegin.3 deleted file mode 120000 index aaa6194e9..000000000 --- a/man/std::u16string::begin,std::basic_string::cbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::begin,std::basic_string::cbegin.3 \ No newline at end of file diff --git a/man/std::u16string::c_str.3 b/man/std::u16string::c_str.3 deleted file mode 120000 index 3a01af623..000000000 --- a/man/std::u16string::c_str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::c_str.3 \ No newline at end of file diff --git a/man/std::u16string::c_str.3 b/man/std::u16string::c_str.3 new file mode 100644 index 000000000..e1a3268f3 --- /dev/null +++ b/man/std::u16string::c_str.3 @@ -0,0 +1,88 @@ +.TH std::basic_string::c_str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::c_str \- std::basic_string::c_str + +.SH Synopsis + const CharT* c_str() const; (noexcept since C++11) + (constexpr since C++20) + + Returns a pointer to a null-terminated character array with data equivalent to those + stored in the string. + + The pointer is such that the range [c_str(), c_str() + size()] is valid and the + values in it correspond to the values stored in the string with an additional null + character after the last position. + + The pointer obtained from c_str() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string + , excluding operator[], at(), front(), back(), begin(), rbegin(), end() and + rend() + \fI(since C++11)\fP. + + Writing to the character array accessed through c_str() is undefined behavior. + + c_str() and data() perform the same function. \fI(since C++11)\fP + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying character storage. + + c_str()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + c_str() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Notes + + The pointer obtained from c_str() may only be treated as a pointer to a + null-terminated character string if the string object does not contain other null + characters. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + extern "C" void c_func(const char* c_str) + { + printf("c_func called with '%s'\\n", c_str); + } + + int main() + { + std::string const s("Emplary"); + const char* p = s.c_str(); + assert(s.size() == std::strlen(p)); + assert(std::equal(s.begin(), s.end(), p)); + assert(std::equal(p, p + s.size(), s.begin())); + assert('\\0' == *(p + s.size())); + + c_func(s.c_str()); + } + +.SH Output: + + c_func called with 'Emplary' + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP diff --git a/man/std::u16string::capacity.3 b/man/std::u16string::capacity.3 deleted file mode 120000 index 6045777da..000000000 --- a/man/std::u16string::capacity.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::capacity.3 \ No newline at end of file diff --git a/man/std::u16string::capacity.3 b/man/std::u16string::capacity.3 new file mode 100644 index 000000000..32f50b319 --- /dev/null +++ b/man/std::u16string::capacity.3 @@ -0,0 +1,93 @@ +.TH std::basic_string::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::capacity \- std::basic_string::capacity + +.SH Synopsis + size_type capacity() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the number of characters that the string has currently allocated space for. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Capacity of the currently allocated storage, i.e. the storage available for storing + elements. + +.SH Complexity + + Constant. + +.SH Notes + + Memory locations obtained from the allocator but not available for storing any + element are not counted in the allocated storage. Note that the null terminator is + not an element of the std::basic_string. + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_capacity(std::string const& s) + { + std::cout << std::quoted(s) << " has capacity " << s.capacity() << ".\\n"; + } + + int main() + { + std::string s{"Exemplar"}; + show_capacity(s); + + s += " is an example string."; + show_capacity(s); + + s.clear(); + show_capacity(s); + + std::cout << "\\nDemonstrate the capacity's growth policy." + "\\nSize: Capacity: Ratio:\\n" << std::left; + + std::string g; + auto old_cap{g.capacity()}; + + for (int mark{}; mark != 5; ++mark) + { + while (old_cap == g.capacity()) + g.push_back('.'); + + std::cout << std::setw( 7) << g.size() + << std::setw(11) << g.capacity() + << std::setw(10) << g.capacity() / static_cast(old_cap) << '\\n'; + + old_cap = g.capacity(); + } + } + +.SH Possible output: + + "Exemplar" has capacity 15. + "Exemplar is an example string." has capacity 30. + "" has capacity 30. + + Demonstrate the capacity's growth policy. + Size: Capacity: Ratio: + 16 30 2 + 31 60 2 + 61 120 2 + 121 240 2 + 241 480 2 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP diff --git a/man/std::u16string::clear.3 b/man/std::u16string::clear.3 deleted file mode 120000 index df77a9b91..000000000 --- a/man/std::u16string::clear.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::clear.3 \ No newline at end of file diff --git a/man/std::u16string::clear.3 b/man/std::u16string::clear.3 new file mode 100644 index 000000000..a1e021b20 --- /dev/null +++ b/man/std::u16string::clear.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::clear \- std::basic_string::clear + +.SH Synopsis + void clear(); (noexcept since C++11) + (constexpr since C++20) + + Removes all characters from the string as if by executing erase(begin(), end()). + + All pointers, references, and iterators are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Unlike for std::vector::clear, the C++ standard does not explicitly require that + capacity is unchanged by this function, but existing implementations do not change + capacity. This means that they do not release the allocated memory (see also + shrink_to_fit). + +.SH Complexity + + Linear in the size of the string, although existing implementations operate in + constant time. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s{"Exemplar"}; + std::string::size_type const capacity = s.capacity(); + + s.clear(); + assert(s.capacity() == capacity); // <- not guaranteed + assert(s.empty()); + assert(s.size() == 0); + } + +.SH See also + + erase removes characters + \fI(public member function)\fP diff --git a/man/std::u16string::compare.3 b/man/std::u16string::compare.3 deleted file mode 120000 index abd41e671..000000000 --- a/man/std::u16string::compare.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::compare.3 \ No newline at end of file diff --git a/man/std::u16string::compare.3 b/man/std::u16string::compare.3 new file mode 100644 index 000000000..890b367f1 --- /dev/null +++ b/man/std::u16string::compare.3 @@ -0,0 +1,285 @@ +.TH std::basic_string::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::compare \- std::basic_string::compare + +.SH Synopsis + (noexcept since + int compare( const basic_string& str ) const; \fB(1)\fP C++11) + (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(2)\fP (constexpr since + const basic_string& str ) const; C++20) + int compare( size_type pos1, size_type count1, + + const basic_string& str, \fI(until C++14)\fP + + size_type pos2, size_type count2 + ) const; + int compare( size_type pos1, size_type count1, + \fI(since C++14)\fP + const basic_string& str, (constexpr since + C++20) + size_type pos2, size_type count2 + = npos ) const; + int compare( const CharT* s ) const; \fB(4)\fP (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(5)\fP (constexpr since + const CharT* s ) const; C++20) + int compare( size_type pos1, size_type count1, \fB(3)\fP (constexpr since + const CharT* s, size_type count2 \fB(6)\fP C++20) + ) const; + template< class StringViewLike > \fI(since C++17)\fP + int compare( const StringViewLike& t ) const \fB(7)\fP (constexpr since + noexcept(/* see below */); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + int compare( size_type pos1, size_type count1, \fB(8)\fP (constexpr since + C++20) + const StringViewLike& t ) const; + template< class StringViewLike > + + int compare( size_type pos1, size_type count1, \fI(since C++17)\fP + const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos2, size_type count2 + = npos) const; + + Compares two character sequences. + + 1) Compares this string to str. + 2) Compares a [pos1, pos1 + count1) substring of this string to str. + * If count1 > size() - pos1, the substring is [pos1, size()). + 3) Compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of str. + * If count1 > size() - pos1, the first substring is [pos1, size()). + * If count2 > str.size() - pos2, the second substring is [pos2, str.size()). + 4) Compares this string to the null-terminated character sequence beginning at the + character pointed to by s with length Traits::length(s). + 5) Compares a [pos1, pos1 + count1) substring of this string to the null-terminated + character sequence beginning at the character pointed to by s with length + Traits::length(s). + * If count1 > size() - pos1, the substring is [pos1, size()). + 6) Compares a [pos1, pos1 + count1) substring of this string to the characters in + the range [s, s + count2). The characters in [s, s + count2) may include null + characters. + * If count1 > size() - pos1, the substring is [pos1, size()). + 7-9) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then + 7) compares this string to sv; + 8) compares a [pos1, pos1 + count1) substring of this string to sv, as if by + std::basic_string_view(*this).substr(pos1, count1).compare(sv); + 9) compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of sv, as if by std::basic_string_view(*this) + .substr(pos1, count1).compare(sv.substr(pos2, count2)). + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false.. + + A character sequence consisting of count1 characters starting at data1 is compared + to a character sequence consisting of count2 characters starting at data2 as + follows: + + * First, calculate the number of characters to compare, as if by size_type rlen = + std::min(count1, count2). + * Then compare the sequences by calling Traits::compare(data1, data2, rlen). For + standard strings this function performs character-by-character lexicographical + comparison. If the result is zero (the character sequences are equal so far), + then their sizes are compared as follows: + + Condition Result Return value + Traits::compare(data1, data2, rlen) < 0 data1 is less than <0 + data2 + size1 < size2 data1 is less than <0 + data2 + Traits::compare(data1, data2, rlen) == size1 == data1 is equal to 0 + 0 size2 data2 + size1 > size2 data1 is greater >0 + than data2 + Traits::compare(data1, data2, rlen) > 0 data1 is greater >0 + than data2 + +.SH Parameters + + str - other string to compare to + s - pointer to the character string to compare to + count1 - number of characters of this string to compare + pos1 - position of the first character in this string to compare + count2 - number of characters of the given string to compare + pos2 - position of the first character of the given string to compare + t - object (convertible to std::basic_string_view) to compare to + +.SH Return value + + * Negative value if *this appears before the character sequence specified by the + arguments, in lexicographical order. + * Zero if both character sequences compare equivalent. + * Positive value if *this appears after the character sequence specified by the + arguments, in lexicographical order. + +.SH Exceptions + + The overloads taking parameters named pos1 or pos2 throws std::out_of_range if the + argument is out of range. + + 7) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + 8,9) Throws anything thrown by the conversion to std::basic_string_view. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Possible implementation + + overload \fB(1)\fP + template + int std::basic_string::compare + (const std::basic_string& s) const noexcept + { + size_type lhs_sz = size(); + size_type rhs_sz = s.size(); + int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz)); + if (result != 0) + return result; + if (lhs_sz < rhs_sz) + return -1; + if (lhs_sz > rhs_sz) + return 1; + return 0; + } + +.SH Notes + + For the situations when three-way comparison is not required, std::basic_string + provides the usual relational operators (<, <=, ==, >, etc). + + By default (with the default std::char_traits), this function is not + locale-sensitive. See std::collate::compare for locale-aware three-way string + comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print_compare_result(std::string_view str1, + std::string_view str2, + int compare_result) + { + if (compare_result < 0) + std::cout << std::quoted(str1) << " comes before " + << std::quoted(str2) << ".\\n"; + else if (compare_result > 0) + std::cout << std::quoted(str2) << " comes before " + << std::quoted(str1) << ".\\n"; + else + std::cout << std::quoted(str1) << " and " + << std::quoted(str2) << " are the same.\\n"; + } + + int main() + { + std::string batman{"Batman"}; + std::string superman{"Superman"}; + int compare_result{0}; + + // 1) Compare with other string + compare_result = batman.compare(superman); + std::cout << "1) "; + print_compare_result("Batman", "Superman", compare_result); + + // 2) Compare substring with other string + compare_result = batman.compare(3, 3, superman); + std::cout << "2) "; + print_compare_result("man", "Superman", compare_result); + + // 3) Compare substring with other substring + compare_result = batman.compare(3, 3, superman, 5, 3); + std::cout << "3) "; + print_compare_result("man", "man", compare_result); + + // Compare substring with other substring + // defaulting to end of other string + assert(compare_result == batman.compare(3, 3, superman, 5)); + + // 4) Compare with char pointer + compare_result = batman.compare("Superman"); + std::cout << "4) "; + print_compare_result("Batman", "Superman", compare_result); + + // 5) Compare substring with char pointer + compare_result = batman.compare(3, 3, "Superman"); + std::cout << "5) "; + print_compare_result("man", "Superman", compare_result); + + // 6) Compare substring with char pointer substring + compare_result = batman.compare(0, 3, "Superman", 5); + std::cout << "6) "; + print_compare_result("Bat", "Super", compare_result); + } + +.SH Output: + + 1) "Batman" comes before "Superman". + 2) "Superman" comes before "man". + 3) "man" and "man" are the same. + 4) "Batman" comes before "Superman". + 5) "Superman" comes before "man". + 6) "Bat" comes before "Super". + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the parameter count2 of overload default argument removed, + LWG 5 C++98 \fB(6)\fP split to overloads \fB(5)\fP and + had a default argument npos \fB(6)\fP + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(7)\fP caused ambiguity in avoided by making it a + some cases template + noexcept for overload \fB(7)\fP was + P1148R0 C++17 accidentally restored + dropped by the resolution of + LWG2946 + +.SH See also + + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + substr returns a substring + \fI(public member function)\fP + collate defines lexicographical comparison and hashing of strings + \fI(class template)\fP + strcoll compares two strings in accordance to the current locale + \fI(function)\fP + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + compares two views + compare \fI\fI(public member\fP function of\fP + std::basic_string_view) + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::contains.3 b/man/std::u16string::contains.3 new file mode 100644 index 000000000..a6b202311 --- /dev/null +++ b/man/std::u16string::contains.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::contains \- std::basic_string::contains + +.SH Synopsis + constexpr bool + contains( std::basic_string_view sv ) const \fB(1)\fP (since C++23) + noexcept; + constexpr bool \fB(2)\fP (since C++23) + contains( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP (since C++23) + contains( const CharT* s ) const; + + Checks if the string contains the given substring. The substring may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void test_substring(const std::string& str, SubstrType subs) + { + constexpr char delim = std::is_scalar_v ? '\\'' : '\\"'; + std::cout << std::quoted(str) + << (str.contains(subs) ? " contains " + : " does not contain ") + << std::quoted(std::string{subs}, delim) << '\\n'; + } + + int main() + { + using namespace std::literals; + + auto helloWorld = "hello world"s; + + test_substring(helloWorld, "hello"sv); + test_substring(helloWorld, "goodbye"sv); + test_substring(helloWorld, 'w'); + test_substring(helloWorld, 'x'); + } + +.SH Output: + + "hello world" contains "hello" + "hello world" does not contain "goodbye" + "hello world" contains 'w' + "hello world" does not contain 'x' + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::copy.3 b/man/std::u16string::copy.3 deleted file mode 120000 index 18592fc3f..000000000 --- a/man/std::u16string::copy.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::copy.3 \ No newline at end of file diff --git a/man/std::u16string::copy.3 b/man/std::u16string::copy.3 new file mode 100644 index 000000000..5258bb301 --- /dev/null +++ b/man/std::u16string::copy.3 @@ -0,0 +1,81 @@ +.TH std::basic_string::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::copy \- std::basic_string::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos (constexpr since C++20) + = 0 ) const; + + Copies a substring [pos, pos + count) to character string pointed to by dest. If the + requested substring lasts past the end of the string, or if count == npos, the + copied substring is [pos, size()). + + The resulting character string is not null-terminated. + +.SH Parameters + + dest - pointer to the destination character string + count - length of the substring + pos - position of the first character to include + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string foo("WINE"); + + // brace-initialization initializes all characters to 0, + // providing a null-terminator + char bar[4]{}; + + // do not copy the last char, to guarantee null-termination + foo.copy(bar, sizeof bar - 1); + + std::cout << bar << '\\n'; // requires bar to be null-terminated + } + +.SH Output: + + WIN + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string_view)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::u16string::data.3 b/man/std::u16string::data.3 deleted file mode 120000 index e88dffdcc..000000000 --- a/man/std::u16string::data.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::data.3 \ No newline at end of file diff --git a/man/std::u16string::data.3 b/man/std::u16string::data.3 new file mode 100644 index 000000000..e081790d6 --- /dev/null +++ b/man/std::u16string::data.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::data \- std::basic_string::data + +.SH Synopsis + const CharT* data() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + CharT* data() noexcept; \fB(2)\fP \fI(since C++17)\fP + (constexpr since C++20) + + Returns a pointer to the underlying array serving as character storage. The pointer + is such that the range + + [data(), data() + size()) \fI(until C++11)\fP + [data(), data() + size()] \fI(since C++11)\fP + + is valid and the values in it correspond to the values stored in the string. + + The returned array is not required to be null-terminated. + \fI(until C++11)\fP + If empty() returns true, the pointer is a non-null pointer that should + not be dereferenced. + The returned array is null-terminated, that is, data() and c_str() + perform the same function. + \fI(since C++11)\fP + If empty() returns true, the pointer points to a single null + character. + + The pointer obtained from data() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string, excluding operator[](), at(), + front(), back(), begin(), end(), rbegin(), rend(). + 1) Modifying the character array accessed through the const overload of data has + undefined behavior. + 2) Modifying the past-the-end null terminator stored at data() + size() to any value + other than CharT() has undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character storage. + + data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + data() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string const s("Emplary"); + assert(s.size() == std::strlen(s.data())); + assert(std::equal(s.begin(), s.end(), s.data())); + assert(std::equal(s.data(), s.data() + s.size(), s.begin())); + assert('\\0' == *(s.data() + s.size())); + } + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + c_str returns a non-modifiable standard C character array version of the string + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::empty.3 b/man/std::u16string::empty.3 deleted file mode 120000 index 57ffefac4..000000000 --- a/man/std::u16string::empty.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::empty.3 \ No newline at end of file diff --git a/man/std::u16string::empty.3 b/man/std::u16string::empty.3 new file mode 100644 index 000000000..515c30654 --- /dev/null +++ b/man/std::u16string::empty.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::empty \- std::basic_string::empty + +.SH Synopsis + bool empty() const; (noexcept since C++11) + (constexpr since C++20) + + Checks if the string has no characters, i.e. whether begin() == end(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the string is empty, false otherwise + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::boolalpha(std::cout); + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = "Exemplar"; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = ""; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + } + +.SH Output: + + s.empty():true s:'' + s.empty():false s:'Exemplar' + s.empty():true s:'' + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + empty checks whether the view is empty + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::end,.3 b/man/std::u16string::end,.3 new file mode 100644 index 000000000..a29f4fa07 --- /dev/null +++ b/man/std::u16string::end,.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::end, \- std::basic_string::end, + +.SH Synopsis + + iterator end(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the character following the last character of the string. + This character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemparl"); + std::next_permutation(s.begin(), s.end()); + + std::string c; + std::copy(s.cbegin(), s.cend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "Exemplar" + } + +.SH Output: + + Exemplar + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::end,std::basic_string::cend.3 b/man/std::u16string::end,std::basic_string::cend.3 deleted file mode 120000 index 8e6f5e8ed..000000000 --- a/man/std::u16string::end,std::basic_string::cend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::end,std::basic_string::cend.3 \ No newline at end of file diff --git a/man/std::u16string::ends_with.3 b/man/std::u16string::ends_with.3 new file mode 100644 index 000000000..daa271fc6 --- /dev/null +++ b/man/std::u16string::ends_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::ends_with \- std::basic_string::ends_with + +.SH Synopsis + constexpr bool + ends_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + ends_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + ends_with( const CharT* s ) const; + + Checks if the string ends with the given suffix. The suffix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).ends_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.ends_with("C++20!"sv) // (1) + && !str.ends_with("c++20!"sv) // (1) + && str.ends_with("C++20!"s) // (1) implicit conversion string to string_view + && !str.ends_with("c++20!"s) // (1) implicit conversion string to string_view + && str.ends_with('!') // (2) + && !str.ends_with('?') // (2) + && str.ends_with("C++20!") // (3) + && !str.ends_with("c++20!") // (3) + ); + } + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::u16string::erase.3 b/man/std::u16string::erase.3 deleted file mode 120000 index 533c91687..000000000 --- a/man/std::u16string::erase.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::erase.3 \ No newline at end of file diff --git a/man/std::u16string::erase.3 b/man/std::u16string::erase.3 new file mode 100644 index 000000000..caa61fc84 --- /dev/null +++ b/man/std::u16string::erase.3 @@ -0,0 +1,109 @@ +.TH std::basic_string::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::erase \- std::basic_string::erase + +.SH Synopsis + basic_string& erase( (constexpr since + size_type index = 0, \fB(1)\fP C++20) + size_type count = npos ); + iterator erase( iterator \fI(until C++11)\fP + position ); + iterator erase( \fI(since C++11)\fP + const_iterator position ); (constexpr since + \fB(2)\fP C++20) + iterator erase( iterator \fI(until C++11)\fP + first, iterator last ); + iterator erase( \fB(3)\fP \fI(since C++11)\fP + const_iterator first, (constexpr since + const_iterator last ); C++20) + + Removes specified characters from the string. + + 1) Removes std::min(count, size() - index) characters starting at index. + 2) Removes the character at position. + If position is not a dereferenceable iterator on *this, the behavior is undefined. + 3) Removes the characters in the range [first, last). + If first or last is not a valid iterator on *this, or [first, last) is not a valid + range, the behavior is undefined. + +.SH Parameters + + index - first character to remove + count - number of characters to remove + position - iterator to the character to remove + first, last - range of the characters to remove + +.SH Return value + + 1) *this + 2) Iterator pointing to the character immediately following the character erased, or + end() if no such character exists. + 3) Iterator pointing to the character last pointed to before the erase, or end() if + no such character exists. + +.SH Exceptions + + 1) std::out_of_range if index > size(). + 2,3) Throws nothing. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s = "This Is An Example"; + std::cout << "1) " << s << '\\n'; + + s.erase(7, 3); // erases " An" using overload (1) + std::cout << "2) " << s << '\\n'; + + s.erase(std::find(s.begin(), s.end(), ' ')); // erases first ' '; overload (2) + std::cout << "3) " << s << '\\n'; + + s.erase(s.find(' ')); // trims from ' ' to the end of the string; overload (1) + std::cout << "4) " << s << '\\n'; + + auto it = std::next(s.begin(), s.find('s')); // obtains iterator to the first 's' + s.erase(it, std::next(it, 2)); // erases "sI"; overload (3) + std::cout << "5) " << s << '\\n'; + } + +.SH Output: + + 1) This Is An Example + 2) This Is Example + 3) ThisIs Example + 4) ThisIs + 5) This + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(3)\fP did not erase the character returns an iterator + LWG 27 C++98 last pointed to, but it returned pointing to that + the iterator pointing to the character character + immediately following that character + overload \fB(2)\fP explicitly required position + LWG 428 C++98 to be valid, but removed the + SequenceContainer requires it to be explicit requirement + dereferenceable (stricter) + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + +.SH See also + + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::u16string::find.3 b/man/std::u16string::find.3 deleted file mode 120000 index 6675f6f1b..000000000 --- a/man/std::u16string::find.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find.3 \ No newline at end of file diff --git a/man/std::u16string::find.3 b/man/std::u16string::find.3 new file mode 100644 index 000000000..6ae3d060f --- /dev/null +++ b/man/std::u16string::find.3 @@ -0,0 +1,171 @@ +.TH std::basic_string::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find \- std::basic_string::find + +.SH Synopsis + size_type find( const basic_string& str, size_type pos = \fB(1)\fP (noexcept since C++11) + 0 ) const; (constexpr since C++20) + size_type find( const CharT* s, size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find( const CharT* s, size_type pos = 0 ) \fB(3)\fP (constexpr since C++20) + const; + size_type find( CharT ch, size_type pos = 0 ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type find( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first substring equal to the given character sequence. Search begins at + pos, i.e. the found substring must not begin in a position preceding pos. + + 1) Finds the first substring equal to str. + 2) Finds the first substring equal to the range [s, s + count). This range may + contain null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character ch (treated as a single-character substring by the + formal rules below). + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first substring equal to sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + Formally, a substring str is said to be found at position xpos if all of the + following are true: + + * xpos >= pos + * xpos + str.size() <= size() + * for all positions n in str, Traits::eq(at(xpos + n), str.at(n)). + + In particular, this implies that + + * a substring can be found only if pos <= size() - str.size() + * an empty substring is found at pos if and only if pos <= size() + * for a non-empty substring, if pos >= size(), the function always returns npos. + +.SH Parameters + + str - string to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(int id, std::string::size_type n, std::string const& s) + { + std::cout << id << ") "; + if (std::string::npos == n) + std::cout << "not found! n == npos\\n"; + else + std::cout << "found @ n = " << n << ", substr(" << n << ") = " + << std::quoted(s.substr(n)) << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; /* + ^ ^ ^ + 1 2 3 */ + + // search from beginning of string + n = s.find("is"); + print(1, n, s); + + // search from position 5 + n = s.find("is", 5); + print(2, n, s); + + // find a single character + n = s.find('a'); + print(3, n, s); + + // find a single character + n = s.find('q'); + print(4, n, s); + } + +.SH Output: + + 1) found @ n = 2, substr\fB(2)\fP = "is is a string" + 2) found @ n = 5, substr\fB(5)\fP = "is a string" + 3) found @ n = 8, substr\fB(8)\fP = "a string" + 4) not found! n == npos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + strstr finds the first occurrence of a substring of characters + \fI(function)\fP + finds the first occurrence of a wide string within another wide + wcsstr string + \fI(function)\fP + strchr finds the first occurrence of a character + \fI(function)\fP + wcschr finds the first occurrence of a wide character in a wide string + \fI(function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find characters in the view + find \fI(public member function of std::basic_string_view)\fP + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::find_first_not_of.3 b/man/std::u16string::find_first_not_of.3 deleted file mode 120000 index 7cd66aee2..000000000 --- a/man/std::u16string::find_first_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_not_of.3 \ No newline at end of file diff --git a/man/std::u16string::find_first_not_of.3 b/man/std::u16string::find_first_not_of.3 new file mode 100644 index 000000000..795a2e7ce --- /dev/null +++ b/man/std::u16string::find_first_not_of.3 @@ -0,0 +1,141 @@ +.TH std::basic_string::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_not_of \- std::basic_string::find_first_not_of + +.SH Synopsis + size_type find_first_not_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_first_not_of( const CharT* s, \fB(3)\fP (constexpr since C++20) + size_type pos = 0 ) const; + size_type find_first_not_of( CharT ch, size_type pos = 0 \fB(4)\fP (noexcept since C++11) + ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const + noexcept(/* see below */); + + Finds the first character equal to none of the characters in the given character + sequence. The search considers only the range [pos, size()). If all characters in + the range can be found in the given character sequence, npos will be returned. + + 1) Finds the first character equal to none of characters in str. + 2) Finds the first character equal to none of characters in range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position for the search to start from + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or std::string::npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Permit uppercase letters, lowercase letters and numbers in macro names + const char* pattern = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "abcdefghijklmnopqrstuvwxyz" + "0123456789"; + + std::string data = "1) %FIX, 2) %HACK, and 3) %TODO"; + const std::string replacement = "%DONE%"; + + std::cout << "Before: " << data << '\\n'; + + for (std::string::size_type first{}, last{}; + (first = data.find('%', first)) != std::string::npos; + first += replacement.size()) + { + last = data.find_first_not_of(pattern, first + 1); + if (last == std::string::npos) + last = data.length(); + + // Now first at '%' and last is one past end of the found substring + data.replace(first, last - first, replacement); + } + + std::cout << "After: " << data << '\\n'; + } + +.SH Output: + + Before: 1) %FIX, 2) %HACK, and 3) %TODO + After: 1) %DONE%, 2) %DONE%, and 3) %DONE% + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::find_first_of.3 b/man/std::u16string::find_first_of.3 deleted file mode 120000 index 497a89646..000000000 --- a/man/std::u16string::find_first_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_of.3 \ No newline at end of file diff --git a/man/std::u16string::find_first_of.3 b/man/std::u16string::find_first_of.3 new file mode 100644 index 000000000..e6263f90c --- /dev/null +++ b/man/std::u16string::find_first_of.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_of \- std::basic_string::find_first_of + +.SH Synopsis + size_type find_first_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_of( const CharT* s, + size_type pos, size_type count \fB(2)\fP (constexpr since C++20) + ) const; + size_type find_first_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + 0 ) const; + size_type find_first_of( CharT ch, size_type pos = 0 ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first character equal to one of the characters in the given character + sequence. The search considers only the range [pos, size()). If none of the + characters in the given character sequence is present in the range, npos will be + returned. + + 1) Finds the first character equal to one of the characters in str. + 2) Finds the first character equal to one of the characters in the range [s, s + + count). This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to one of the characters in character string + pointed to by s. The length of the string is determined by the first null character + using Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to one of the characters in + sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to begin searching + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Traits::eq() is used to perform the comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + std::string::size_type sz; + + // (1) + sz = "alignas"s.find_first_of("klmn"s); + // └────────────────────────┘ + assert(sz == 1); + + sz = "alignof"s.find_first_of("wxyz"s); + // no match + assert(sz == std::string::npos); + + // (2) + sz = "consteval"s.find_first_of("xyzabc", 0, 3); + // no match (× are not targets) ××× + assert(sz == std::string::npos); + + sz = "consteval"s.find_first_of("xyzabc", 0, 6); + // └───────────────────────────────┘ + assert(sz == 0); + + // (3) + sz = "decltype"s.find_first_of("xyzabc"); + // └────────────────────────────┘ + assert(sz == 2); + + // (4) + sz = "co_await"s.find_first_of('a'); + // └──────────────────────┘ + assert(sz == 3); + + // (5) + sz = "constinit"s.find_first_of("int"sv); + // └─────────────────────────┘ + assert(sz == 2); + + std::cout << "All tests passed.\\n"; + } + +.SH Output: + + All tests passed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI(public member function of std::basic_string_view)\fP + + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::find_last_not_of.3 b/man/std::u16string::find_last_not_of.3 deleted file mode 120000 index 85f8838a9..000000000 --- a/man/std::u16string::find_last_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_not_of.3 \ No newline at end of file diff --git a/man/std::u16string::find_last_not_of.3 b/man/std::u16string::find_last_not_of.3 new file mode 100644 index 000000000..b325c1428 --- /dev/null +++ b/man/std::u16string::find_last_not_of.3 @@ -0,0 +1,160 @@ +.TH std::basic_string::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_not_of \- std::basic_string::find_last_not_of + +.SH Synopsis + size_type find_last_not_of( const basic_string& str, (noexcept since C++11) + size_type pos = npos ) \fB(1)\fP (constexpr since C++20) + const; + size_type find_last_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_last_not_of( const CharT* s, size_type \fB(3)\fP (constexpr since C++20) + pos = npos ) const; + size_type find_last_not_of( CharT ch, size_type pos = \fB(4)\fP (noexcept since C++11) + npos ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to none of the characters in the given character + sequence. The search considers only the range [0, pos]. If all characters in the + range can be found in the given character sequence, npos will be returned. + + 1) Finds the last character equal to none of characters in str. + 2) Finds the last character equal to none of characters in the range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to end search + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v< + const T&, std::basic_string_view>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + void show_pos(const std::string& str, std::string::size_type found) + { + if (found != std::string::npos) + std::cout << '[' << found << "] = \\'" << str[found] << "\\'\\n"; + else + std::cout << "not found\\n"; + } + + int main() + { + std::string str{"abc_123"}; + char const* skip_set{"0123456789"}; + std::string::size_type str_last_pos{std::string::npos}; + + show_pos(str, str.find_last_not_of(skip_set)); // [3] = '_' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of(skip_set, str_last_pos)); // [2] = 'c' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of('c', str_last_pos)); // [1] = 'b' + + const char arr[]{'3', '4', '5'}; + show_pos(str, str.find_last_not_of(arr)); // [5] = '2' + + str_last_pos = 2; + std::string::size_type skip_set_size{4}; + show_pos(str, str.find_last_not_of(skip_set, + str_last_pos, + skip_set_size)); // [2] = 'c' + + show_pos(str, str.find_last_not_of("abc")); // [6] = '3' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of("abc", str_last_pos)); // not found + } + +.SH Output: + + [3] = '_' + [2] = 'c' + [1] = 'b' + [5] = '2' + [2] = 'c' + [6] = '3' + not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::find_last_of.3 b/man/std::u16string::find_last_of.3 deleted file mode 120000 index 18ea1b60d..000000000 --- a/man/std::u16string::find_last_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_of.3 \ No newline at end of file diff --git a/man/std::u16string::find_last_of.3 b/man/std::u16string::find_last_of.3 new file mode 100644 index 000000000..e3ff59859 --- /dev/null +++ b/man/std::u16string::find_last_of.3 @@ -0,0 +1,126 @@ +.TH std::basic_string::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_of \- std::basic_string::find_last_of + +.SH Synopsis + size_type find_last_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = npos ) const; (constexpr since C++20) + size_type find_last_of( const CharT* s, + size_type pos, size_type count ) \fB(2)\fP (constexpr since C++20) + const; + size_type find_last_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + npos ) const; + size_type find_last_of( CharT ch, size_type pos = npos ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to one of characters in the given character sequence. + The exact search algorithm is not specified. The search considers only the range + [0, pos]. If none of the characters in the given character sequence is present in + the range, npos will be returned. + + 1) Finds the last character equal to one of characters in str. + 2) Finds the last character equal to one of characters in range [s, s + count). This + range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to one of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to one of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which the search is to finish + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string path = "/root/config"; + auto const pos = path.find_last_of('/'); + const auto leaf = path.substr(pos + 1); + + std::cout << leaf << '\\n'; + } + +.SH Output: + + config + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::front.3 b/man/std::u16string::front.3 deleted file mode 120000 index 6e46155d2..000000000 --- a/man/std::u16string::front.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::front.3 \ No newline at end of file diff --git a/man/std::u16string::front.3 b/man/std::u16string::front.3 new file mode 100644 index 000000000..978ec6830 --- /dev/null +++ b/man/std::u16string::front.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::front \- std::basic_string::front + +.SH Synopsis + CharT& front(); \fB(1)\fP (constexpr since C++20) + const CharT& front() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the first character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, front() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& f1 = s.front(); + f1 = 'e'; + std::cout << s << '\\n'; // "exemplary" + + std::string const c("Exemplary"); + char const& f2 = c.front(); + std::cout << &f2 << '\\n'; // "Exemplary" + } + +.SH Output: + + exemplary + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function front() + +.SH See also + + back accesses the last character + (DR*) \fI(public member function)\fP + front accesses the first character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::get_allocator.3 b/man/std::u16string::get_allocator.3 deleted file mode 120000 index a59c7178f..000000000 --- a/man/std::u16string::get_allocator.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::get_allocator.3 \ No newline at end of file diff --git a/man/std::u16string::get_allocator.3 b/man/std::u16string::get_allocator.3 new file mode 100644 index 000000000..52b590226 --- /dev/null +++ b/man/std::u16string::get_allocator.3 @@ -0,0 +1,30 @@ +.TH std::basic_string::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::get_allocator \- std::basic_string::get_allocator + +.SH Synopsis + allocator_type get_allocator() const; (noexcept since C++20) + (constexpr since C++20) + + Returns the allocator associated with the string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated allocator. + +.SH Complexity + + Constant. + +.SH See also + + allocator the default allocator + \fI(class template)\fP + allocator_traits provides information about allocator types + \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::u16string::insert.3 b/man/std::u16string::insert.3 deleted file mode 120000 index 06d0b9ef6..000000000 --- a/man/std::u16string::insert.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::insert.3 \ No newline at end of file diff --git a/man/std::u16string::insert.3 b/man/std::u16string::insert.3 new file mode 100644 index 000000000..28be988e6 --- /dev/null +++ b/man/std::u16string::insert.3 @@ -0,0 +1,228 @@ +.TH std::basic_string::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert \- std::basic_string::insert + +.SH Synopsis + basic_string& insert( (constexpr + size_type index, size_type \fB(1)\fP since + count, CharT ch ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(2)\fP since + CharT* s ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(3)\fP since + CharT* s, size_type count ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(4)\fP since + basic_string& str ); C++20) + basic_string& insert( + size_type index, const + basic_string& str, (until + C++14) + size_type s_index, size_type + count ); + basic_string& insert( (since + size_type index, const C++14) + basic_string& str, (constexpr + since + size_type s_index, size_type C++20) + count = npos ); + iterator insert( iterator (until + pos, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, CharT ch (constexpr + ); since + C++20) + void insert( iterator pos, (until + size_type count, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, (constexpr + size_type count, CharT ch ); since + C++20) + template< class InputIt > + void insert( iterator pos, \fB(5)\fP (until + InputIt first, InputIt last C++11) + ); + template< class InputIt > (since + iterator insert( C++11) + const_iterator pos, InputIt (constexpr + first, InputIt last ); \fB(6)\fP since + C++20) + iterator insert( (since + const_iterator pos, \fB(7)\fP C++11) + std::initializer_list \fB(9)\fP (constexpr + ilist ); since + C++20) + template< class \fB(8)\fP (since + StringViewLike > C++17) + basic_string& insert( \fB(10)\fP (constexpr + size_type index, const since + StringViewLike& t ); C++20) + template< class + StringViewLike > + (since + basic_string& insert( C++17) + size_type index, const \fB(11)\fP (constexpr + StringViewLike& t, since + C++20) + + size_type t_index, size_type + count = npos ); + + Inserts characters into the string. + + 1) Inserts count copies of character ch at the position index. + 2) Inserts null-terminated character string pointed to by s at the position index. + The length of the string is determined by the first null character using + Traits::length(s). + 3) Inserts the characters in the range [s, s + count) at the position index. The + range can contain null characters. + 4) Inserts string str at the position index. + 5) Inserts a string, obtained by str.substr(s_index, count) at the position index. + 6) Inserts character ch before the character pointed by pos. + 7) Inserts count copies of character ch before the element (if any) pointed by pos. + 8) Inserts characters from the range [first, last) before the element (if any) + pointed by pos, as if by insert(pos - begin(), basic_string(first, last, + get_allocator())). + + This overload does not participate in overload resolution if InputIt \fI(since C++11)\fP + does not satisfy LegacyInputIterator. + + 9) Inserts elements from initializer list ilist before the element (if any) pointed + by pos. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts the elements from sv before the element (if any) + pointed by index, as if by insert(index, sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 11) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts, before the element (if any) pointed by index, the + characters from the subview [t_index, t_index + count) of sv. + * If the requested subview lasts past the end of sv, or if count == npos, the + resulting subview is [t_index, sv.size()). + * If t_index > sv.size(), or if index > size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + index - position at which the content will be inserted + pos - iterator before which the characters will be inserted + ch - character to insert + count - number of characters to insert + s - pointer to the character string to insert + str - string to insert + first, last - range defining characters to insert + s_index - position of the first character in str to insert + ilist - std::initializer_list to insert the characters from + t - object (convertible to std::basic_string_view) to insert the + characters from + t_index - position of the first character in t to insert +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1-5) *this + 6-9) An iterator which refers to the copy of the first inserted character or pos if + no characters were inserted (count == 0 or first == last or ilist.size() == 0) + 10,11) *this + +.SH Exceptions + + 1-4,10) Throws std::out_of_range if index > size(). + 5) Throws std::out_of_range if index > size() or if s_index > str.size(). + 11) Throws std::out_of_range if index > size() or if t_index > sv.size(). + + In all cases, throws std::length_error if size() + ins_count > max_size() where + ins_count is the number of characters that will be inserted. + + In all cases, if std::allocator_traits::allocate throws an \fI(since C++20)\fP + exception, it is rethrown. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::string_literals; + + int main() + { + std::string s = "xmplr"; + + // insert(size_type index, size_type count, char ch) + s.insert(0, 1, 'E'); + assert("Exmplr" == s); + + // insert(size_type index, const char* s) + s.insert(2, "e"); + assert("Exemplr" == s); + + // insert(size_type index, string const& str) + s.insert(6, "a"s); + assert("Exemplar" == s); + + // insert(size_type index, string const& str, + // size_type s_index, size_type count) + s.insert(8, " is an example string."s, 0, 14); + assert("Exemplar is an example" == s); + + // insert(const_iterator pos, char ch) + s.insert(s.cbegin() + s.find_first_of('n') + 1, ':'); + assert("Exemplar is an: example" == s); + + // insert(const_iterator pos, size_type count, char ch) + s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '='); + assert("Exemplar is an:== example" == s); + + // insert(const_iterator pos, InputIt first, InputIt last) + { + std::string seq = " string"; + s.insert(s.begin() + s.find_last_of('e') + 1, + std::begin(seq), std::end(seq)); + assert("Exemplar is an:== example string" == s); + } + + // insert(const_iterator pos, std::initializer_list) + s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'}); + assert("Exemplar is an:== example string." == s); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 7 C++98 overload (8) referred to a non-existing refers to overload (4) + overload correctly + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2946 C++17 overload (10) caused ambiguity in some avoided by making it a + cases template + +.SH See also + + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP diff --git a/man/std::u16string::insert_range.3 b/man/std::u16string::insert_range.3 new file mode 100644 index 000000000..172031ebb --- /dev/null +++ b/man/std::u16string::insert_range.3 @@ -0,0 +1,84 @@ +.TH std::basic_string::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert_range \- std::basic_string::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr iterator insert_range( const_iterator pos, R&& rg ); + + Inserts characters from the range rg before the element (if any) pointed by pos. + + Equivalent to + + return insert(pos - begin(), + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + pos - iterator before which the characters will be inserted + rg - a container compatible range + +.SH Return value + + An iterator which refers to the first inserted character, or pos if no characters + were inserted because rg was empty. + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If std::allocator_traits::allocate throws an exception, it is rethrown. + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto source = {'l', 'i', 'b', '_'}; + std::string target{"__cpp_containers_ranges"}; + // ^insertion will occur + // before this position + + const auto pos = target.find("container"); + assert(pos != target.npos); + auto iter = std::next(target.begin(), pos); + + #ifdef __cpp_lib_containers_ranges + target.insert_range(iter, source); + #else + target.insert(iter, source.begin(), source.end()); + #endif + + assert(target == "__cpp_lib_containers_ranges"); + // ^^^^ + } + +.SH See also + + insert inserts characters + \fI(public member function)\fP diff --git a/man/std::u16string::max_size.3 b/man/std::u16string::max_size.3 deleted file mode 120000 index 450f8a80c..000000000 --- a/man/std::u16string::max_size.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::max_size.3 \ No newline at end of file diff --git a/man/std::u16string::max_size.3 b/man/std::u16string::max_size.3 new file mode 100644 index 000000000..806a1dd4a --- /dev/null +++ b/man/std::u16string::max_size.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::max_size \- std::basic_string::max_size + +.SH Synopsis + size_type max_size() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the maximum number of elements the string is able to hold due to system or + library implementation limitations, i.e. std::distance(begin(), end()) for the + largest string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + #include + + template + void print_basic_string_max_size() + { + std::basic_string s; + auto max_size = s.max_size(); + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "basic_string<" << boost::core::demangle(typeid(T).name()) + << ">:\\n\\t" << max_size << " = "; + std::cout << std::setprecision(3) << (double) max_size << " = "; + std::cout.imbue(std::locale("C")); + std::cout << std::hex << std::setfill('0') << "0x" + << std::setw(sizeof(typename decltype(s)::size_type) << 1) + << max_size << '\\n' << std::dec; + }; + + int main() + { + std::cout << "Pointer size: " << CHAR_BIT * sizeof(void*) << " bits\\n" + "Maximum sizes:\\n"; + + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + + using CharT = std::array; + print_basic_string_max_size(); + } + +.SH Possible output: + + Pointer size: 64 bits + Maximum sizes: + basic_string: + 9,223,372,036,854,775,807 = 9.22e+18 = 0x7fffffffffffffff + basic_string: + 4,611,686,018,427,387,903 = 4.61e+18 = 0x3fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 1,152,921,504,606,846,975 = 1.15e+18 = 0x0fffffffffffffff + basic_string>: + 13,848,906,962,244,407 = 1.38e+16 = 0x00313381ec031337 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::npos.3 b/man/std::u16string::npos.3 deleted file mode 120000 index 4582d0216..000000000 --- a/man/std::u16string::npos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::npos.3 \ No newline at end of file diff --git a/man/std::u16string::npos.3 b/man/std::u16string::npos.3 new file mode 100644 index 000000000..cb8bcc779 --- /dev/null +++ b/man/std::u16string::npos.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::npos \- std::basic_string::npos + +.SH Synopsis + static const size_type npos = -1; + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of string indicator by the functions that expect a string index or as the error + indicator by the functions that return a string index. + +.SH Note + + Although the definition uses -1, size_type is an unsigned integer type, and the + value of npos is the largest positive value it can hold, due to signed-to-unsigned + implicit conversion. This is a portable way to specify the largest value of any + unsigned type. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // string search functions return npos if nothing is found + std::string s = "test"; + if (s.find('a') == s.npos) + std::cout << "no 'a' in 'test'\\n"; + + // functions that take string subsets as arguments + // use npos as the "all the way to the end" indicator + std::string s2(s, 2, std::string::npos); + std::cout << s2 << '\\n'; + + std::bitset<5> b("aaabb", std::string::npos, 'a', 'b'); + std::cout << b << '\\n'; + } + +.SH Output: + + no 'a' in 'test' + st + 00011 + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant of std::basic_string_view)\fP + diff --git a/man/std::u16string::operator+=.3 b/man/std::u16string::operator+=.3 deleted file mode 120000 index 54ff82159..000000000 --- a/man/std::u16string::operator+=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator+=.3 \ No newline at end of file diff --git a/man/std::u16string::operator+=.3 b/man/std::u16string::operator+=.3 new file mode 100644 index 000000000..6f5ea9049 --- /dev/null +++ b/man/std::u16string::operator+=.3 @@ -0,0 +1,120 @@ +.TH std::basic_string::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator+= \- std::basic_string::operator+= + +.SH Synopsis + basic_string& operator+=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator+=( CharT ch ); \fB(2)\fP (constexpr since C++20) + basic_string& operator+=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator+=( std::initializer_list \fB(4)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template< class StringViewLike > \fB(5)\fP \fI(since C++17)\fP + basic_string& operator+=( const StringViewLike& t ); (constexpr since C++20) + + Appends additional characters to the string. + + 1) Appends string str. + 2) Appends character ch. + 3) Appends the null-terminated character string pointed to by s. + 4) Appends characters in the initializer list ilist. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends characters in the string view sv as if by append(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string to append + ch - character value to append + s - pointer to a null-terminated character string to append + ilist - std::initializer_list with the characters to append + t - object (convertible to std::basic_string_view) with the characters to append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Overload \fB(2)\fP can accept any types that are implicitly convertible to CharT. For + std::string, where CharT is char, the set of acceptable types includes all + arithmetic types. This may have unintended effects. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str; + + // reserve sufficient storage space to avoid memory reallocation + str.reserve(50); + + std::cout << std::quoted(str) << '\\n'; // empty string + + str += "This"; + std::cout << std::quoted(str) << '\\n'; + + str += std::string(" is "); + std::cout << std::quoted(str) << '\\n'; + + str += 'a'; + std::cout << std::quoted(str) << '\\n'; + + str += {' ', 's', 't', 'r', 'i', 'n', 'g', '.'}; + std::cout << std::quoted(str) << '\\n'; + + str += 69.96; // Equivalent to str += static_cast(69.96); + // 'E' (ASCII code 69) is appended by overload (2), + // which might not be the intent. + + // To add a numeric value, consider std::to_string(): + str += std::to_string(1729); + + std::cout << std::quoted(str) << '\\n'; + } + +.SH Output: + + "" + "This" + "This is " + "This is a" + "This is a string." + "This is a string.E1729" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::u16string::operator=.3 b/man/std::u16string::operator=.3 deleted file mode 120000 index 5505d7126..000000000 --- a/man/std::u16string::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator=.3 \ No newline at end of file diff --git a/man/std::u16string::operator=.3 b/man/std::u16string::operator=.3 new file mode 100644 index 000000000..70b37150d --- /dev/null +++ b/man/std::u16string::operator=.3 @@ -0,0 +1,153 @@ +.TH std::basic_string::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator= \- std::basic_string::operator= + +.SH Synopsis + basic_string& operator=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator=( basic_string&& str ) \fB(2)\fP \fI(since C++11)\fP + noexcept(/* see below */); (constexpr since C++20) + basic_string& operator=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator=( CharT ch ); \fB(4)\fP (constexpr since C++20) + basic_string& operator=( std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template \fB(6)\fP \fI(since C++17)\fP + basic_string& operator=( const StringViewLike& t ); (constexpr since C++20) + basic_string& operator=( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + Replaces the contents of the string. + + 1) Replaces the contents with a copy of str. If *this and str are the same object, + this function has no effect. + 2) Replaces the contents with those of str using SequenceContainer's move assignment + semantics. + Unlike other sequence container move assignments, references, pointers, and + iterators to elements of str may be invalidated. + 3) Replaces the contents with those of null-terminated character string pointed to + by s as if by assign(s, Traits::length(s)). + 4) Replaces the contents with character ch as if by assign(std::addressof(ch), 1). + 5) Replaces the contents with those of the initializer list ilist as if by + assign(ilist.begin(), ilist.size()). + 6) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of the sv as if by + assign(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 7) std::basic_string cannot be assigned from nullptr. + +.SH Parameters + + ch - value to initialize characters of the string with + str - string to be used as source to initialize the string with + s - pointer to a null-terminated character string to use as source to initialize + the string with + ilist - std::initializer_list to initialize the string with + t - object convertible to std::basic_string_view to initialize the string with + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in size of str. + 2) Linear in the size of *this (formally, each CharT has to be destroyed). If + allocators do not compare equal and do not propagate, then also linear in the size + of str (copy must be made). + 3) Linear in size of s. + 4) Constant. + 5) Linear in size of ilist. + 6) Linear in size of t. + +.SH Exceptions + + 2) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str1; + std::string str2{"alpha"}; + + // (1) operator=(const basic_string&); + str1 = str2; + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "alpha" + + // (2) operator=(basic_string&&); + str1 = std::move(str2); + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "" or "alpha" (unspecified) + + // (3) operator=(const CharT*); + str1 = "beta"; + std::cout << std::quoted(str1) << '\\n'; // "beta" + + // (4) operator=(CharT); + str1 = '!'; + std::cout << std::quoted(str1) << '\\n'; // "!" + + // (5) operator=(std::initializer_list); + str1 = {'g', 'a', 'm', 'm', 'a'}; + std::cout << std::quoted(str1) << '\\n'; // "gamma" + + // (6) operator=(const T&); + str1 = 35U; // equivalent to str1 = static_cast(35U); + std::cout << std::quoted(str1) << '\\n'; // "#" (ASCII = 35) + } + +.SH Possible output: + + "alpha" "alpha" + "alpha" "" + "beta" + "!" + "gamma" + "#" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + the move assignment operator did not + LWG 2063 C++11 follow follows + SequenceContainer's semantic requirement + LWG 2946 C++17 overload \fB(6)\fP caused ambiguity in some avoided by making it a + cases template + +.SH See also + + constructor constructs a basic_string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assigns a view + operator= \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::operator[].3 b/man/std::u16string::operator[].3 deleted file mode 120000 index 05791619e..000000000 --- a/man/std::u16string::operator[].3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator[].3 \ No newline at end of file diff --git a/man/std::u16string::operator[].3 b/man/std::u16string::operator[].3 new file mode 100644 index 000000000..8fa941e51 --- /dev/null +++ b/man/std::u16string::operator[].3 @@ -0,0 +1,83 @@ +.TH std::basic_string::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator[] \- std::basic_string::operator[] + +.SH Synopsis + CharT& operator[]( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& operator[]( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos if pos < size(), or a + reference to CharT() if pos == size(). No bounds checking is performed. + + If pos > size(), the behavior is undefined. + + For overload \fB(1)\fP, if pos == size(), the behavior is undefined + if the object referred by the returned reference is modified to any value other than + CharT() + \fI(since C++11)\fP. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + *(begin() + pos) if pos < size(), or a reference to CharT() if pos == size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string e("Exemplar"); + for (unsigned i = e.length() - 1; i != 0; i /= 2) + std::cout << e[i]; + std::cout << '\\n'; + + const char* c = &e[0]; + std::cout << c << '\\n'; // print as a C string + + // Change the last character of s into a 'y' + std::string s("Exemplar "); + s[s.size() - 1] = 'y'; // equivalent to s.back() = 'y'; + std::cout << s << '\\n'; + } + +.SH Output: + + rmx + Exemplar + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 259 C++98 non-const overload could return const lvalue changed to return + data()[pos], which was ill-formed *(begin() + pos) + if pos == size(), the behavior of modifying + LWG 2475 C++11 the well-defined if + object referred by the returned reference modified to CharT() + was undefined + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::operatorbasic_string_view.3 b/man/std::u16string::operatorbasic_string_view.3 new file mode 100644 index 000000000..7860d59f8 --- /dev/null +++ b/man/std::u16string::operatorbasic_string_view.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::operatorbasic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operatorbasic_string_view \- std::basic_string::operatorbasic_string_view + +.SH Synopsis + operator std::basic_string_view() const \fI(since C++17)\fP + noexcept; (constexpr since C++20) + + Returns a std::basic_string_view, constructed as if by std::basic_string_view(data(), size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A string view representing the entire contents of the string. + +.SH Notes + + It is the programmer's responsibility to ensure that the resulting string view does + not outlive the string. + + std::string get_string(); + int f(std::string_view sv); + + int x = f(get_string()); // OK + std::string_view sv = get_string(); // Bad: holds a dangling pointer + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_wstring_size(std::wstring_view wcstr_v) + { + std::cout << wcstr_v.size() << " code points\\n"; + } + + int main() + { + std::string cppstr = "ラーメン"; // narrow string + std::wstring wcstr = L"ラーメン"; // wide string + + // Implicit conversion from string to string_view + // via std::string::operator string_view: + std::string_view cppstr_v = cppstr; + + std::cout << cppstr_v << '\\n' + << cppstr_v.size() << " code units\\n"; + + // Implicit conversion from wstring to wstring_view + // via std::wstring::operator wstring_view: + show_wstring_size(wcstr); + } + +.SH Output: + + ラーメン + 12 code units + 4 code points + +.SH See also + + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::u16string::pop_back.3 b/man/std::u16string::pop_back.3 deleted file mode 120000 index 92b01df6a..000000000 --- a/man/std::u16string::pop_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::pop_back.3 \ No newline at end of file diff --git a/man/std::u16string::pop_back.3 b/man/std::u16string::pop_back.3 new file mode 100644 index 000000000..1ef904042 --- /dev/null +++ b/man/std::u16string::pop_back.3 @@ -0,0 +1,75 @@ +.TH std::basic_string::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::pop_back \- std::basic_string::pop_back + +.SH Synopsis + void pop_back(); (constexpr since C++20) + + Removes the last character from the string. + + Equivalent to erase(end() - 1). The behavior is undefined if the string is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + In libstdc++, pop_back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string str("Short string!"); + std::cout << "before=" << std::quoted(str) << '\\n'; + assert(str.size() == 13); + + str.pop_back(); + std::cout << " after=" << std::quoted(str) << '\\n'; + assert(str.size() == 12); + + str.clear(); + // str.pop_back(); // undefined behavior + } + +.SH Output: + + before="Short string!" + after="Short string" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function pop_back() + +.SH See also + + push_back appends a character to the end + \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP diff --git a/man/std::u16string::push_back.3 b/man/std::u16string::push_back.3 deleted file mode 120000 index fde2976b5..000000000 --- a/man/std::u16string::push_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::push_back.3 \ No newline at end of file diff --git a/man/std::u16string::push_back.3 b/man/std::u16string::push_back.3 new file mode 100644 index 000000000..122b1e8fe --- /dev/null +++ b/man/std::u16string::push_back.3 @@ -0,0 +1,68 @@ +.TH std::basic_string::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::push_back \- std::basic_string::push_back + +.SH Synopsis + void push_back( CharT ch ); (constexpr since C++20) + + Appends the given character ch to the end of the string. + +.SH Parameters + + ch - the character to append + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Amortized constant. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str{"Short string"}; + std::cout << "1) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + + str.push_back('!'); + std::cout << "2) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + } + +.SH Output: + + 1) "Short string", size: 12 + 2) "Short string!", size: 13 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + \fB(1)\fP the description was missing in + LWG 7 C++98 the C++ standard \fB(1)\fP description added + \fB(2)\fP the parameter type was const (2) changed to CharT + CharT + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + pop_back removes the last character + (DR*) \fI(public member function)\fP diff --git a/man/std::u16string::rbegin,.3 b/man/std::u16string::rbegin,.3 new file mode 100644 index 000000000..eecaa5142 --- /dev/null +++ b/man/std::u16string::rbegin,.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rbegin, \- std::basic_string::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the first character of the reversed string. It + corresponds to the last character of the non-reversed string. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemplar!"); + *s.rbegin() = 'y'; + std::cout << s << '\\n'; // "Exemplary" + + std::string c; + std::copy(s.crbegin(), s.crend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "yralpmexE" + } + +.SH Output: + + Exemplary + yralpmexE + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::rbegin,std::basic_string::crbegin.3 b/man/std::u16string::rbegin,std::basic_string::crbegin.3 deleted file mode 120000 index e36abe435..000000000 --- a/man/std::u16string::rbegin,std::basic_string::crbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rbegin,std::basic_string::crbegin.3 \ No newline at end of file diff --git a/man/std::u16string::rend,.3 b/man/std::u16string::rend,.3 new file mode 100644 index 000000000..c28ff3818 --- /dev/null +++ b/man/std::u16string::rend,.3 @@ -0,0 +1,70 @@ +.TH std::basic_string::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rend, \- std::basic_string::rend, + +.SH Synopsis + + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the character following the last character of the + reversed string. It corresponds to the character preceding the first character of + the non-reversed string. This character acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string p("[A man, a plan, a canal: Panama]"); + std::string q; + + std::copy(p.crbegin(), p.crend(), std::back_inserter(q)); + std::cout << "q = " << q << '\\n'; + + std::copy(q.crbegin(), q.crend(), p.rbegin()); + std::cout << "p = " << p << '\\n'; + } + +.SH Output: + + q = ]amanaP :lanac a ,nalp a ,nam A[ + p = ]amanaP :lanac a ,nalp a ,nam A[ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::rend,std::basic_string::crend.3 b/man/std::u16string::rend,std::basic_string::crend.3 deleted file mode 120000 index 600152427..000000000 --- a/man/std::u16string::rend,std::basic_string::crend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rend,std::basic_string::crend.3 \ No newline at end of file diff --git a/man/std::u16string::replace.3 b/man/std::u16string::replace.3 deleted file mode 120000 index 3a94b3a6f..000000000 --- a/man/std::u16string::replace.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::replace.3 \ No newline at end of file diff --git a/man/std::u16string::replace.3 b/man/std::u16string::replace.3 new file mode 100644 index 000000000..7b1e79fc7 --- /dev/null +++ b/man/std::u16string::replace.3 @@ -0,0 +1,184 @@ +.TH std::basic_string::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace \- std::basic_string::replace + +.SH Synopsis + basic_string& replace( size_type pos, + size_type count, \fB(1)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(2)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( size_type pos, + size_type count, + + const basic_string& \fI(until C++14)\fP + str, + + size_type pos2, + size_type count2 ); + basic_string& replace( size_type pos, + size_type count, + \fI(since C++14)\fP + const basic_string& (constexpr since + str, C++20) + + size_type pos2, + size_type count2 = npos ); + basic_string& replace( size_type pos, + size_type count, \fB(4)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(5)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( size_type pos, (constexpr since + size_type count, \fB(6)\fP C++20) + const CharT* cstr ); + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(7)\fP C++20) + const CharT* cstr ); + basic_string& replace( size_type pos, + size_type count, \fB(8)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(3)\fP \fB(9)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + template< class InputIt > + + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(10)\fP C++20) + + InputIt first2, InputIt + last2 ); + basic_string& replace( const_iterator first, \fI(since C++11)\fP + const_iterator last, \fB(11)\fP (constexpr since + C++20) + std::initializer_list ilist ); + template< class StringViewLike > + + basic_string& replace( size_type pos, \fI(since C++17)\fP + size_type count, \fB(12)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( const_iterator first, \fI(since C++17)\fP + const_iterator last, \fB(13)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( size_type pos, + size_type count, \fI(since C++17)\fP + const StringViewLike& \fB(14)\fP (constexpr since + t, C++20) + + size_type pos2, + size_type count2 = npos ); + + Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count, + size())) or [first, last) with given characters. + + 1,2) Those characters are replaced with str. + 3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2, + str.size())) of str. + 4,5) Those characters are replaced with the characters in the range [cstr, cstr + + count2). + If [cstr, cstr + count2) is not a valid range, the behavior is undefined. + 6,7) Those characters are replaced with the characters in the range [cstr, cstr + + Traits::length(cstr)). + 8,9) Those characters are replaced with count2 copies of ch. + 10) Those characters are replaced with the characters in the range [first2, last2) + as if by replace(first, last, basic_string(first2, last2, get_allocator())). + 11) Those characters are replaced with the characters in ilist. + 12,13) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then those characters are replaced + with the characters from sv. + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 14) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then those characters are replaced with the characters from the + subview sv.substr(pos2, count2). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If [begin(), first) or [first, last) is not a valid range, the behavior is + undefined. + +.SH Parameters + + pos - start of the substring that is going to be replaced + count - length of the substring that is going to be replaced + first, last - range of characters that is going to be replaced + str - string to use for replacement + pos2 - start of the substring to replace with + count2 - number of characters to replace with + cstr - pointer to the character string to use for replacement + ch - character value to use for replacement + first2, last2 - range of characters to use for replacement + ilist - initializer list with the characters to use for replacement + t - object (convertible to std::basic_string_view) with the characters + to use for replacement +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this. + +.SH Exceptions + + 1) Throws std::out_of_range if pos > size(). + 3) Throws std::out_of_range if pos > size() or pos2 > str.size(). + 4,6,8) Throws std::out_of_range if pos > size(). + 12,14) Throws std::out_of_range if pos > size(). + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 1323 C++98 the types of first and last changed to const_iterator + were iterator + LWG 2946 C++17 overloads (12,13) caused avoided by making them templates + ambiguity in some cases + +.SH See also + + replace_with_range replaces specified portion of a string with a range of characters + (C++23) \fI(public member function)\fP + regex_replace replaces occurrences of a regular expression with formatted + \fI(C++11)\fP replacement text + \fI(function template)\fP + replace replaces all values satisfying specific criteria with another + replace_if value + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::u16string::replace_with_range.3 b/man/std::u16string::replace_with_range.3 new file mode 100644 index 000000000..a06106cbc --- /dev/null +++ b/man/std::u16string::replace_with_range.3 @@ -0,0 +1,91 @@ +.TH std::basic_string::replace_with_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace_with_range \- std::basic_string::replace_with_range + +.SH Synopsis + template< container-compatible-range R > + + constexpr std::basic_string& replace_with_range( const_iterator + first, (since C++23) + const_iterator last, + + R&& rg ); + + Replaces the characters in the range [first, last) with the characters from the + range rg. + + Equivalent to + + return replace(first, + last, + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + first, last - range of characters that is going to be replaced + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + auto s{"Today is today!"s}; + constexpr auto today{"today"sv}; + constexpr auto tomorrow{"tomorrow's yesterday"sv}; + std::forward_list rg; + std::ranges::reverse_copy(tomorrow, std::front_inserter(rg)); + + const auto pos{s.rfind(today)}; + assert(pos != s.npos); + const auto first{std::next(s.begin(), pos)}; + const auto last{std::next(first, today.length())}; + + #ifdef __cpp_lib_containers_ranges + s.replace_range(first, last, rg); + #else + s.replace(first, last, rg.cbegin(), rg.cend()); + #endif + + assert("Today is tomorrow's yesterday!" == s); + } + +.SH See also + + replace replaces specified portion of a string + \fI(public member function)\fP diff --git a/man/std::u16string::reserve.3 b/man/std::u16string::reserve.3 deleted file mode 120000 index 8af41bde6..000000000 --- a/man/std::u16string::reserve.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::reserve.3 \ No newline at end of file diff --git a/man/std::u16string::reserve.3 b/man/std::u16string::reserve.3 new file mode 100644 index 000000000..3f0d1423a --- /dev/null +++ b/man/std::u16string::reserve.3 @@ -0,0 +1,112 @@ +.TH std::basic_string::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::reserve \- std::basic_string::reserve + +.SH Synopsis + void reserve( size_type new_cap = 0 ); \fI(until C++20)\fP + constexpr void reserve( size_type new_cap ); \fI(since C++20)\fP + \fB(1)\fP \fI(since C++20)\fP + void reserve(); \fB(2)\fP (deprecated in C++20) + (removed in C++26) + + 1) Informs a std::basic_string object of a planned change in size, so that it can + manage the storage allocation appropriately. + * If new_cap is greater than the current capacity(), new storage is allocated, and + capacity() is made equal or greater than new_cap. + + * If new_cap is less than the current capacity(), this is a + non-binding shrink request. + * If new_cap is less than the current size(), this is a non-binding \fI(until C++20)\fP + shrink-to-fit request + equivalent to shrink_to_fit() + \fI(since C++11)\fP. + * If new_cap is less than or equal to the current capacity(), there \fI(since C++20)\fP + is no effect. + + If a capacity change takes place, all iterators and references, including the + past-the-end iterator, are invalidated. + 2) A non-binding shrink-to-fit request. After this call, capacity() has an + unspecified value greater than or equal to size(). + +.SH Parameters + + new_cap - new capacity of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::length_error if new_cap is greater than max_size(). + + May throw any exceptions thrown by std::allocator_traits::allocate(), + such as std::bad_alloc. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + At most linear in the size() of the string. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + std::cout << "1) Initially: " << s.capacity() << '\\n'; + + const std::string::size_type new_cap{101u}; + s.reserve(new_cap); + assert(s.capacity() >= new_cap); + std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\\n'; + + // observing the capacity growth factor + auto cap{s.capacity()}; + for (int check{}; check != 4; ++check) + { + while (cap == s.capacity()) + s += '$'; + cap = s.capacity(); + std::cout << (3) + check << ") Capacity: " << cap << '\\n'; + } + + // s.reserve(); // deprecated/removed in C++20/26, use: + s.shrink_to_fit(); + std::cout << "7) After shrink_to_fit: " << s.capacity() << '\\n'; + } + +.SH Possible output: + + 1) Initially: 15 + 2) After reserve(101): 101 + 3) Capacity: 202 + 4) Capacity: 404 + 5) Capacity: 808 + 6) Capacity: 1616 + 7) After shrink_to_fit: 809 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::u16string::resize.3 b/man/std::u16string::resize.3 deleted file mode 120000 index 15f0e17b9..000000000 --- a/man/std::u16string::resize.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::resize.3 \ No newline at end of file diff --git a/man/std::u16string::resize.3 b/man/std::u16string::resize.3 new file mode 100644 index 000000000..3b4c7a8b6 --- /dev/null +++ b/man/std::u16string::resize.3 @@ -0,0 +1,140 @@ +.TH std::basic_string::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize \- std::basic_string::resize + +.SH Synopsis + void resize( size_type count ); \fB(1)\fP (constexpr since C++20) + void resize( size_type count, CharT ch ); \fB(2)\fP (constexpr since C++20) + + Resizes the string to contain count characters. + + If the current size is less than count, additional characters are appended: + + 1) Initializes appended characters to CharT() ('\\0' if CharT is char). + 2) Initializes appended characters to ch. + + If the current size is greater than count, the string is reduced to its first count + elements. + +.SH Parameters + + count - new size of the string + ch - character to initialize the new characters with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > max_size(). Any exceptions thrown by corresponding + Allocator. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const unsigned desired_length{8}; + std::string long_string("Where is the end?"); + std::string short_string("H"); + + std::cout << "Basic functionality:\\n" + << "Shorten:\\n" + << "1. Before: " << std::quoted(long_string) << '\\n'; + long_string.resize(desired_length); + std::cout << "2. After: " << std::quoted(long_string) << '\\n'; + + std::cout << "Lengthen with a given value 'a':\\n" + << "3. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length, 'a'); + std::cout << "4. After: " << std::quoted(short_string) << '\\n'; + + std::cout << "Lengthen with char() == " << static_cast(char()) << '\\n' + << "5. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length + 3); + std::cout << "6. After: \\""; + for (char c : short_string) + std::cout << (c == char() ? '@' : c); + std::cout << "\\"\\n\\n"; + + std::cout << "Errors:\\n"; + std::string s; + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size() - 1, 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "1. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size(), 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "2. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is BAD, throw length_error + s.resize(s.max_size() + 1, 'x'); + } + catch (const std::length_error& ex) + { + std::cout << "3. Length error: " << ex.what() << '\\n'; + } + } + +.SH Possible output: + + Basic functionality: + Shorten: + 1. Before: "Where is the end?" + 2. After: "Where is" + Lengthen with a given value 'a': + 3. Before: "H" + 4. After: "Haaaaaaa" + Lengthen with char() == 0 + 5. Before: "Haaaaaaa" + 6. After: "Haaaaaaa@@@" + + Errors: + 1. Exception: std::bad_alloc + 2. Exception: std::bad_alloc + 3. Length error: basic_string::_M_replace_aux + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP diff --git a/man/std::u16string::resize_and_overwrite.3 b/man/std::u16string::resize_and_overwrite.3 new file mode 100644 index 000000000..192feef8a --- /dev/null +++ b/man/std::u16string::resize_and_overwrite.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::resize_and_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize_and_overwrite \- std::basic_string::resize_and_overwrite + +.SH Synopsis + template< class Operation > (since C++23) + constexpr void resize_and_overwrite( size_type count, Operation op ); + + Resizes the string to contain at most count characters, using the user-provided + operation op to modify the possibly indeterminate contents and set the length. This + avoids the cost of initializing a suitably-sized std::string when it is intended to + be used as a char array to be populated by, e.g., a C API call. + + This function performs following steps: + + 1. Obtains contiguous storage that contains count + 1 characters, and makes its + first k characters equal to the first k characters of *this, where k is the + smaller of count and the result of this->size() before the call to + resize_and_overwrite. Let p denote the pointer to the first character in the + storage. + * The equality is determined as if by checking this->compare(0, k, p, k) == + 0. + * The characters in [p + k, p + count] may have indeterminate values. + 2. Evaluates std::move(op)(p, count). Let r be the return value of std::move(op)(p, + count). + 3. Replaces the contents of *this with [p, p + r) (which sets the length of *this + to r). Invalidates all pointers and references to the range [p, p + count]. + + The program is ill-formed if r does not have an integer-like type. The behavior is + undefined if std::move(op)(p, count) throws an exception or modifies p or count, r + is not in the range [0, count], or any character in range [p, p + r) has an + indeterminate value. + + Implementations are recommended to avoid unnecessary copies and allocations by, + e.g., making p equal to the pointer to beginning of storage of characters allocated + for *this after the call, which can be identical to the existing storage of *this if + count is less than or equal to this->capacity(). + +.SH Parameters + + count - the maximal possible new size of the string + op - the function object used for setting the new contents of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > this->max_size(). Any exceptions thrown by + corresponding Allocator. + + If an exception is thrown from std::move(op)(p, count), the behavior is undefined. + Otherwise, if an exception is thrown, this function has no effect. + +.SH Notes + + resize_and_overwrite invalidates all iterators, pointers, and references into *this, + regardless whether reallocation occurs. Implementations may assume that the contents + of the string are not aliased after the call to resize_and_overwrite. + + Feature-test macro Value Std Feature +__cpp_lib_string_resize_and_overwrite 202110L (C++23) std::basic_string::resize_and_overwrite + +.SH Example + + Link to test the example: compiler explorer. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + static_assert(__cpp_lib_string_resize_and_overwrite); + + constexpr std::string_view fruits[]{"apple", "banana", "coconut", "date", "elderberry"}; + + int main() + { + // A simple case, append only fruits[0]. The string size will be increased. + std::string s{"Food: "}; + s.resize_and_overwrite(16, [sz = s.size()](char* buf, std::size_t buf_size) noexcept + { + const auto to_copy = std::min(buf_size - sz, fruits[0].size()); + std::memcpy(buf + sz, fruits[0].data(), to_copy); + return sz + to_copy; + }); + std::cout << "1. " << std::quoted(s) << '\\n'; + + // The size shrinking case. Note, that the user's lambda is always invoked. + s.resize_and_overwrite(10, [](char* buf, int n) noexcept + { + return std::find(buf, buf + n, ':') - buf; + }); + std::cout << "2. " << std::quoted(s) << '\\n'; + + std::cout << "3. Copy data until the buffer is full. Print data and sizes.\\n"; + std::string food{"Food:"}; + const auto resize_to{27}; + std::cout << "Initially, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", resize_to: " << resize_to + << ", food: " << std::quoted(food) << '\\n'; + + food.resize_and_overwrite( + resize_to, + [food_size = food.size()](char* p, std::size_t n) noexcept -> std::size_t + { + // p[0]..p[n] is the assignable range + // p[0]..p[min(n, food_size) - 1] is the readable range + // (contents initially equal to the original string) + + // Debug print: + std::cout << "In Operation(); n: " << n << '\\n'; + + // Copy fruits to the buffer p while there is enough space. + char* first = p + food_size; + + for (char* const end = p + n; const std::string_view fruit : fruits) + { + char* last = first + fruit.size() + 1; + if (last > end) + break; + *first++ = ' '; + std::ranges::copy(fruit, first); + first = last; + } + + const auto final_size{static_cast(first - p)}; + + // Debug print: + std::cout << "In Operation(); final_size: " << final_size << '\\n'; + + assert(final_size <= n); + return final_size; // Return value is the actual new length + // of the string, must be in range 0..n + }); + + std::cout << "Finally, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", food: " << std::quoted(food) << '\\n'; + } + +.SH Possible output: + + 1. "Food: apple" + 2. "Food" + 3. Copy data until the buffer is full. Print data and sizes. + Initially, food.size: 5, food.capacity: 15, resize_to: 27, food: "Food:" + In Operation(); n: 27 + In Operation(); final_size: 26 + Finally, food.size: 26, food.capacity: 30, food: "Food: apple banana coconut" + +.SH See also + + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::u16string::rfind.3 b/man/std::u16string::rfind.3 deleted file mode 120000 index 6ca6348d9..000000000 --- a/man/std::u16string::rfind.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rfind.3 \ No newline at end of file diff --git a/man/std::u16string::rfind.3 b/man/std::u16string::rfind.3 new file mode 100644 index 000000000..6baebe7ca --- /dev/null +++ b/man/std::u16string::rfind.3 @@ -0,0 +1,161 @@ +.TH std::basic_string::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rfind \- std::basic_string::rfind + +.SH Synopsis + size_type rfind( const basic_string& str, size_type pos \fB(1)\fP (noexcept since C++11) + = npos ) const; (constexpr since C++20) + size_type rfind( const CharT* s, size_type pos, \fB(2)\fP (constexpr since C++20) + size_type count ) const; + size_type rfind( const CharT* s, size_type pos = npos ) \fB(3)\fP (constexpr since C++20) + const; + size_type rfind( CharT ch, size_type pos = npos ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type rfind( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last substring equal to str. + 2) Finds the last substring equal to the range [s, s + count). This range can + include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last substring equal to the contents of sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string to search for + pos - position at which to begin searching + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. Note that this is an offset from the start of the string, not the end. + + If searching for an empty string (i.e., str.size(), count, or Traits::length(s) is + zero), the empty string is found immediately and rfind returns: + + * pos, if pos < size(); + * size() otherwise, including the case where pos == npos. + + Otherwise, if size() is zero, npos is always returned. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(std::string::size_type n, + std::string::size_type len, + std::string const &s) + { + if (n == std::string::npos) + std::cout << "not found\\n"; + else + std::cout << "found: " << std::quoted(s.substr(n, len)) << " at " << n << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; + + // search backwards from end of string + n = s.rfind("is"); + print(n, 2, s); + + // search backwards from position 4 + n = s.rfind("is", 4); + print(n, 2, s); + + // find a single character + n = s.rfind('s'); + print(n, 1, s); + + // find a single character + n = s.rfind('q'); + print(n, 1, s); + + // find the prefix (see also s.starts_with("This")) + n = s.rfind("This", 0); + print(n, 4, s); + } + +.SH Output: + + found: "is" at 5 + found: "is" at 2 + found: "s" at 10 + not found + found: "This" at 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::shrink_to_fit.3 b/man/std::u16string::shrink_to_fit.3 deleted file mode 120000 index af19637a3..000000000 --- a/man/std::u16string::shrink_to_fit.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::shrink_to_fit.3 \ No newline at end of file diff --git a/man/std::u16string::shrink_to_fit.3 b/man/std::u16string::shrink_to_fit.3 new file mode 100644 index 000000000..506b08ea9 --- /dev/null +++ b/man/std::u16string::shrink_to_fit.3 @@ -0,0 +1,95 @@ +.TH std::basic_string::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::shrink_to_fit \- std::basic_string::shrink_to_fit + +.SH Synopsis + void shrink_to_fit(); (constexpr since C++20) + + Requests the removal of unused capacity. + + It is a non-binding request to reduce capacity() to size(). It depends on the + implementation if the request is fulfilled. + + If (and only if) reallocation takes place, all pointers, references, and iterators + are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + (unspecified) \fI(until C++17)\fP + Linear in the size of the string. \fI(since C++17)\fP + +.SH Notes + + In libstdc++, shrink_to_fit() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::cout << "Size of std::string is " << sizeof s << " bytes\\n" + << "Default-constructed capacity is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + for (int i = 0; i < 42; i++) + s.append(" 42 "); + std::cout << "Capacity after 42 appends is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.clear(); + std::cout << "Capacity after clear() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.shrink_to_fit(); + std::cout << "Capacity after shrink_to_fit() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + } + +.SH Possible output: + + GCC output: + Size of std::string is 32 bytes + Default-constructed capacity is 15 and size 0 + Capacity after 42 appends is 240 and size 168 + Capacity after clear() is 240 and size 0 + Capacity after shrink_to_fit() is 15 and size 0 + + clang output (with -stdlib=libc++): + Size of std::string is 24 bytes + Default-constructed capacity is 22 and size is 0 + Capacity after 42 appends is 191 and size is 168 + Capacity after clear() is 191 and size is 0 + Capacity after shrink_to_fit() is 22 and size is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 755 C++98 std::string lacked explicit shrink-to-fit provided + operations + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::u16string::size,.3 b/man/std::u16string::size,.3 new file mode 100644 index 000000000..46f96cd93 --- /dev/null +++ b/man/std::u16string::size,.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::size, \- std::basic_string::size, + +.SH Synopsis + + size_type size() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + size_type length() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + + Returns the number of CharT elements in the string, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the string. + +.SH Complexity + + Unspecified \fI(until C++11)\fP + Constant \fI(since C++11)\fP + +.SH Notes + + For std::string, the elements are bytes (objects of type char), which are not the + same as characters if a multibyte encoding such as UTF-8 is used. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("Exemplar"); + assert(8 == s.size()); + assert(s.size() == s.length()); + assert(s.size() == static_cast( + std::distance(s.begin(), s.end()))); + + std::u32string a(U"ハロー・ワールド"); // 8 code points + assert(8 == a.size()); // 8 code units in UTF-32 + + std::u16string b(u"ハロー・ワールド"); // 8 code points + assert(8 == b.size()); // 8 code units in UTF-16 + + std::string c("ハロー・ワールド"); // 8 code points + assert(24 == c.size()); // 24 code units in UTF-8 + + #if __cplusplus >= 202002 + std::u8string d(u8"ハロー・ワールド"); // 8 code points + assert(24 == d.size()); // 24 code units in UTF-8 + #endif + } + +.SH See also + + empty checks whether the string is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::size,std::basic_string::length.3 b/man/std::u16string::size,std::basic_string::length.3 deleted file mode 120000 index dbf50666e..000000000 --- a/man/std::u16string::size,std::basic_string::length.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::size,std::basic_string::length.3 \ No newline at end of file diff --git a/man/std::u16string::starts_with.3 b/man/std::u16string::starts_with.3 new file mode 100644 index 000000000..54b219105 --- /dev/null +++ b/man/std::u16string::starts_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::starts_with \- std::basic_string::starts_with + +.SH Synopsis + constexpr bool + starts_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + starts_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + starts_with( const CharT* s ) const; + + Checks if the string begins with the given prefix. The prefix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).starts_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.starts_with("He"sv) // (1) + && !str.starts_with("he"sv) // (1) + && str.starts_with("He"s) // (1) implicit conversion string to string_view + && !str.starts_with("he"s) // (1) implicit conversion string to string_view + && str.starts_with('H') // (2) + && !str.starts_with('h') // (2) + && str.starts_with("He") // (3) + && !str.starts_with("he") // (3) + ); + } + +.SH See also + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::u16string::substr.3 b/man/std::u16string::substr.3 deleted file mode 120000 index 3a94fd2cd..000000000 --- a/man/std::u16string::substr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::substr.3 \ No newline at end of file diff --git a/man/std::u16string::substr.3 b/man/std::u16string::substr.3 new file mode 100644 index 000000000..f263d4824 --- /dev/null +++ b/man/std::u16string::substr.3 @@ -0,0 +1,113 @@ +.TH std::basic_string::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::substr \- std::basic_string::substr + +.SH Synopsis + basic_string substr( size_type pos = 0, size_type (until C++23) + count = npos ) const; (constexpr since C++20) + constexpr basic_string + substr( size_type pos = 0, size_type count = \fB(1)\fP (since C++23) + npos ) const&; + constexpr basic_string substr( size_type pos = 0, \fB(2)\fP (since C++23) + size_type count = npos ) &&; + + Returns a substring [pos, pos + count). If the requested substring extends past the + end of the string, i.e. the count is greater than size() - pos (e.g. if count == + npos), the returned substring is [pos, size()). + + 1) Equivalent to return basic_string(*this, pos, count);. + 2) Equivalent to return basic_string(std::move(*this), pos, count);. + +.SH Parameters + + pos - position of the first character to include + count - length of the substring + +.SH Return value + + String containing the substring [pos, pos + count) or [pos, size()). + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Notes + + The allocator of the returned string is default-constructed: the new allocator might + not be a copy of get_allocator(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "0123456789abcdefghij"; + + // count is npos, returns [pos, size()) + std::string sub1 = a.substr(10); + std::cout << sub1 << '\\n'; + + // both pos and pos + count are within bounds, returns [pos, pos + count) + std::string sub2 = a.substr(5, 3); + std::cout << sub2 << '\\n'; + + // pos is within bounds, pos + count is not, returns [pos, size()) + std::string sub4 = a.substr(a.size() - 3, 50); + // this is effectively equivalent to + // std::string sub4 = a.substr(17, 3); + // since a.size() == 20, pos == a.size() - 3 == 17, and a.size() - pos == 3 + + std::cout << sub4 << '\\n'; + + try + { + // pos is out of bounds, throws + std::string sub5 = a.substr(a.size() + 3, 50); + std::cout << sub5 << '\\n'; + } + catch (const std::out_of_range& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + abcdefghij + 567 + hij + basic_string::substr: __pos (which is 23) > this->size() (which is 20) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + copy copies characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + substr returns a substring + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u16string::swap.3 b/man/std::u16string::swap.3 deleted file mode 120000 index bc1277047..000000000 --- a/man/std::u16string::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::swap.3 \ No newline at end of file diff --git a/man/std::u16string::swap.3 b/man/std::u16string::swap.3 new file mode 100644 index 000000000..07e64dbec --- /dev/null +++ b/man/std::u16string::swap.3 @@ -0,0 +1,96 @@ +.TH std::basic_string::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::swap \- std::basic_string::swap + +.SH Synopsis + void swap( basic_string& other ); \fI(until C++17)\fP + void swap( basic_string& other ) noexcept(/* see below */); \fI(since C++17)\fP + (constexpr since C++20) + + Exchanges the contents of the string with those of other. All iterators and + references may be invalidated. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + +.SH Parameters + + other - string to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + No exception is thrown. \fI(until C++11)\fP + Exceptions can only be thrown in the case where the behavior is + undefined (see above). + \fI(since C++11)\fP + If an exception is thrown for any reason, this function has no effect + (strong exception safety guarantee). + + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_swap::value (since + || C++17) + std::allocator_traits::is_always_equal::value) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "AAA"; + std::string b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 403 C++98 swap() might throw an exception no exception is thrown + LWG 535 C++98 swapping strings did not preserve the orders are also preserved + character orders + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swap swaps the contents + \fI(public member function of std::basic_string_view)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u16string::u16string.3 b/man/std::u16string::u16string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::u16string::u16string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::u16string::u16string.3 b/man/std::u16string::u16string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::u16string::u16string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::u16string::~basic_string.3 b/man/std::u16string::~basic_string.3 new file mode 100644 index 000000000..631cdb44e --- /dev/null +++ b/man/std::u16string::~basic_string.3 @@ -0,0 +1,13 @@ +.TH std::basic_string::~basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::~basic_string \- std::basic_string::~basic_string + +.SH Synopsis + ~basic_string(); (constexpr since C++20) + + Destructs the basic_string. The destructors of the elements are called and the used + storage is deallocated. + +.SH Complexity + + Typically constant (formally linear). diff --git a/man/std::u16string_view.3 b/man/std::u16string_view.3 new file mode 100644 index 000000000..df2b6eb62 --- /dev/null +++ b/man/std::u16string_view.3 @@ -0,0 +1,277 @@ +.TH std::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view \- std::basic_string_view + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++17)\fP + class Traits = std::char_traits + + > class basic_string_view; + + The class template basic_string_view describes an object that can refer to a + constant contiguous sequence of CharT with the first element of the sequence at + position zero. + + For a basic_string_view str, pointers, iterators, and references to elements of str + are invalidated when an operation invalidates a pointer in the range + [str.data(), str.data() + str.size()). + + Every specialization of std::basic_string_view is a TriviallyCopyable (since C++23) + type. + + A typical implementation holds only two members: a pointer to constant CharT and a + size. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string_view \fI(C++17)\fP std::basic_string_view + std::wstring_view \fI(C++17)\fP std::basic_string_view + std::u8string_view (C++20) std::basic_string_view + std::u16string_view \fI(C++17)\fP std::basic_string_view + std::u32string_view \fI(C++17)\fP std::basic_string_view + +.SH Template parameters + + CharT - character type + CharTraits class specifying the operations on the character type. Like for + Traits - std::basic_string, Traits::char_type must name the same type as CharT or + the program is ill-formed. + + Nested types + + Nested type Definition + traits_type Traits + value_type CharT + pointer CharT* + const_pointer const CharT* + reference CharT& + const_reference const CharT& + implementation-defined constant LegacyRandomAccessIterator, + + const_iterator and LegacyContiguousIterator \fI(until C++20)\fP + ConstexprIterator, and contiguous_iterator \fI(since C++20)\fP + + whose value_type is CharT + iterator const_iterator + const_reverse_iterator std::reverse_iterator + reverse_iterator const_reverse_iterator + size_type std::size_t + difference_type std::ptrdiff_t + + Note: iterator and const_iterator are the same type because string views are views + into constant character sequences. + + All requirements on the iterator types of a Container applies to the iterator and + const_iterator types of basic_string_view as well. + +.SH Member functions + + Constructors and assignment + constructor constructs a basic_string_view + \fI(public member function)\fP + operator= assigns a view + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Element access + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function)\fP +.SH Capacity + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP +.SH Modifiers + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Operations + copy copies characters + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string view contains the given substring or + (C++23) character + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) +.SH Input/output + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_view_literals + operator""sv creates a string view of a character array literal + \fI(C++17)\fP \fI(function)\fP + +.SH Helper classes + + std::hash + std::hash + std::hash + std::hash + std::hash hash support for string views + \fI(C++17)\fP \fI(class template specialization)\fP + \fI(C++17)\fP + (C++20) + \fI(C++17)\fP + \fI(C++17)\fP + + Helper templates + + template< class CharT, class Traits > + + inline constexpr bool (since + C++20) + ranges::enable_borrowed_range> = + true; + + This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy + borrowed_range. + + template< class CharT, class Traits > + + inline constexpr bool \fI(since C++20)\fP + + ranges::enable_view> = + true; + + This specialization of ranges::enable_view makes basic_string_view satisfy view. + + Deduction guides \fI(since C++20)\fP + +.SH Notes + + It is the programmer's responsibility to ensure that std::string_view does not + outlive the pointed-to character array: + + std::string_view good{"a string literal"}; + // "Good" case: `good` points to a static array. + // String literals reside in persistent data storage. + + std::string_view bad{"a temporary string"s}; + // "Bad" case: `bad` holds a dangling pointer since the std::string temporary, + // created by std::operator""s, will be destroyed at the end of the statement. + + Specializations of std::basic_string_view are already trivially copyable types in + all existing implementations, even before the formal requirement introduced in + C++23. + + Feature-test macro Value Std Feature + __cpp_lib_string_view 201606L \fI(C++17)\fP std::string_view + 201803L (C++20) ConstexprIterator + __cpp_lib_string_contains 202011L (C++23) contains + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view unicode[]{"▀▄─", "▄▀─", "▀─▄", "▄─▀"}; + + for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4)) + { + for (int x{}; x != 16; ++x) + std::cout << unicode[p]; + std::cout << '\\n'; + } + } + +.SH Output: + + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ + ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀ + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + only pointers, iterators, and all pointers, iterators, and + references references + LWG 3203 C++17 returned from the member functions to elements of + of basic_string_view + basic_string_view might be may be invalidated + invalidated + +.SH See also + + basic_string stores and manipulates sequences of characters + \fI(class template)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + initializer_list creates a temporary array in list-initialization and then + \fI(C++11)\fP references it + \fI(class template)\fP diff --git a/man/std::u16string_view::at.3 b/man/std::u16string_view::at.3 new file mode 100644 index 000000000..65f8fa91d --- /dev/null +++ b/man/std::u16string_view::at.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::at \- std::basic_string_view::at + +.SH Synopsis + constexpr const_reference at( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. Bounds + checking is performed, exception of type std::out_of_range will be thrown on invalid + access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string_view str_view("abcdef"); + + try + { + for (std::size_t i = 0; true; ++i) + std::cout << i << ": " << str_view.at(i) << '\\n'; + } + catch (const std::out_of_range& e) + { + std::cout << "Whooops. Index is out of range.\\n"; + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + 0: a + 1: b + 2: c + 3: d + 4: e + 5: f + 6: Whooops. Index is out of range. + basic_string_view::at: __pos (which is 6) >= this->size() (which is 6) + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + accesses the specified character with bounds checking + at \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::back.3 b/man/std::u16string_view::back.3 new file mode 100644 index 000000000..7fd79d7b3 --- /dev/null +++ b/man/std::u16string_view::back.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::back \- std::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; \fI(since C++17)\fP + + Returns reference to the last character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_suffix(1)) + std::cout << str.back() << ' ' << str << '\\n'; + } + +.SH Output: + + F ABCDEF + E ABCDE + D ABCD + C ABC + B AB + A A + +.SH See also + + front accesses the first character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::u16string_view::basic_string_view.3 b/man/std::u16string_view::basic_string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::u16string_view::basic_string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::begin,std::basic_string_view::cbegin.3 b/man/std::u16string_view::begin,std::basic_string_view::cbegin.3 new file mode 100644 index 000000000..83667f3e5 --- /dev/null +++ b/man/std::u16string_view::begin,std::basic_string_view::cbegin.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::begin,std::basic_string_view::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::begin,std::basic_string_view::cbegin \- std::basic_string_view::begin,std::basic_string_view::cbegin + +.SH Synopsis + constexpr const_iterator begin() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cbegin() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + + constexpr auto begin = str_view.begin(); + constexpr auto cbegin = str_view.cbegin(); + static_assert( + *begin == 'a' and + *cbegin == 'a' and + *begin == *cbegin and + begin == cbegin and + std::same_as); + } + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u16string_view::compare.3 b/man/std::u16string_view::compare.3 new file mode 100644 index 000000000..8087ec4ef --- /dev/null +++ b/man/std::u16string_view::compare.3 @@ -0,0 +1,95 @@ +.TH std::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::compare \- std::basic_string_view::compare + +.SH Synopsis + constexpr int compare( basic_string_view v ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(2)\fP \fI(since C++17)\fP + basic_string_view v ) const; + constexpr int compare( size_type pos1, size_type count1, + basic_string_view v, \fB(3)\fP \fI(since C++17)\fP + size_type pos2, size_type count2 ) const; + constexpr int compare( const CharT* s ) const; \fB(4)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(5)\fP \fI(since C++17)\fP + const CharT* s ) const; + constexpr int compare( size_type pos1, size_type count1, \fB(6)\fP \fI(since C++17)\fP + const CharT* s, size_type count2 ) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less < 0 + than v + size() < this is less < 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater > 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater > 0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + Negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH Example + + +// Run this code + + #include + + int main() + { + using std::operator""sv; + static_assert("abc"sv.compare("abcd"sv) < 0); + static_assert("abcd"sv.compare("abc"sv) > 0); + static_assert("abc"sv.compare("abc"sv) == 0); + static_assert(""sv.compare(""sv) == 0); + } + +.SH See also + + compares two strings + compare \fI\fI(public member\fP function of\fP + std::basic_string) + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) diff --git a/man/std::u16string_view::contains.3 b/man/std::u16string_view::contains.3 new file mode 100644 index 000000000..8c655ade3 --- /dev/null +++ b/man/std::u16string_view::contains.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::contains \- std::basic_string_view::contains + +.SH Synopsis + constexpr bool contains( basic_string_view sv ) const noexcept; \fB(1)\fP (since C++23) + constexpr bool contains( CharT c ) const noexcept; \fB(2)\fP (since C++23) + constexpr bool contains( const CharT* s ) const; \fB(3)\fP (since C++23) + + Checks if the string view contains the given substring, where + + 1) the substring is a string view. + 2) the substring is a single character. + 3) the substring is a null-terminated character string. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view + c - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + static_assert + ( + // bool contains(basic_string_view x) const noexcept; + "https://cppreference.com"sv.contains("cpp"sv) == true and + "https://cppreference.com"sv.contains("php"sv) == false and + + // bool contains(CharT x) const noexcept; + "C++23"sv.contains('+') == true and + "C++23"sv.contains('-') == false and + + // bool contains(const CharT* x) const; + std::string_view("basic_string_view").contains("string") == true and + std::string_view("basic_string_view").contains("String") == false + ); + + int main() {} + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::copy.3 b/man/std::u16string_view::copy.3 new file mode 100644 index 000000000..50e77b7be --- /dev/null +++ b/man/std::u16string_view::copy.3 @@ -0,0 +1,88 @@ +.TH std::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::copy \- std::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos \fI(since C++17)\fP + = 0 ) const; (constexpr since C++20) + + Copies the substring [pos, pos + rcount) to the character array pointed to by dest, + where rcount is the smaller of count and size() - pos. + + Equivalent to Traits::copy(dest, data() + pos, rcount). + +.SH Parameters + + dest - pointer to the destination character string + count - requested substring length + pos - position of the first character + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::basic_string_view source{"ABCDEF"}; + std::array dest; + std::size_t count{}, pos{}; + + dest.fill('\\0'); + source.copy(dest.data(), count = 4); // pos = 0 + std::cout << dest.data() << '\\n'; // ABCD + + dest.fill('\\0'); + source.copy(dest.data(), count = 4, pos = 1); + std::cout << dest.data() << '\\n'; // BCDE + + dest.fill('\\0'); + source.copy(dest.data(), count = 42, pos = 2); // ok, count -> 4 + std::cout << dest.data() << '\\n'; // CDEF + + try + { + source.copy(dest.data(), count = 1, pos = 666); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Output: + + ABCD + BCDE + CDEF + basic_string_view::copy: __pos (which is 666) > __size (which is 6) + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::u16string_view::data.3 b/man/std::u16string_view::data.3 new file mode 100644 index 000000000..29290d3ff --- /dev/null +++ b/man/std::u16string_view::data.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::data \- std::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; \fI(since C++17)\fP + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::data() and string literals, std::basic_string_view::data() + returns a pointer to a buffer that is not necessarily null-terminated, for example a + substring view (e.g. from remove_suffix). Therefore, it is typically a mistake to + pass data() to a routine that takes just a const CharT* and expects a + null-terminated string. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::wstring_view wcstr_v = L"xyzzy"; + std::cout << std::wcslen(wcstr_v.data()) << '\\n'; + // OK: the underlying character array is null-terminated + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, sizeof array); + // std::cout << std::strlen(array_v.data()) << '\\n'; + // error: the underlying character array is not null-terminated + + std::string str(array_v.data(), array_v.size()); // OK + std::cout << std::strlen(str.data()) << '\\n'; + // OK: the underlying character array of a std::string is always null-terminated + } + +.SH Output: + + 5 + 3 + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function of std::basic_string)\fP diff --git a/man/std::u16string_view::empty.3 b/man/std::u16string_view::empty.3 new file mode 100644 index 000000000..185b498eb --- /dev/null +++ b/man/std::u16string_view::empty.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::empty \- std::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + checks whether the string is empty + empty \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::end,std::basic_string_view::cend.3 b/man/std::u16string_view::end,std::basic_string_view::cend.3 new file mode 100644 index 000000000..465ae8a3e --- /dev/null +++ b/man/std::u16string_view::end,std::basic_string_view::cend.3 @@ -0,0 +1,54 @@ +.TH std::basic_string_view::end,std::basic_string_view::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::end,std::basic_string_view::cend \- std::basic_string_view::end,std::basic_string_view::cend + +.SH Synopsis + constexpr const_iterator end() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cend() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + constexpr auto end = str_view.end(); + constexpr auto cend = str_view.cend(); + + static_assert + ( + *std::prev(end) == 'd' && 'd' == *std::prev(cend) and end == cend + ); + } + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u16string_view::ends_with.3 b/man/std::u16string_view::ends_with.3 new file mode 100644 index 000000000..ad6eecb60 --- /dev/null +++ b/man/std::u16string_view::ends_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::ends_with \- std::basic_string_view::ends_with + +.SH Synopsis + constexpr bool ends_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool ends_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool ends_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view ends with the given suffix, where + + 1) the suffix is a string view. Effectively returns size() >= sv.size() && + compare(size() - sv.size(), npos, sv) == 0. + 2) the suffix is a single character. Effectively returns !empty() && + Traits::eq(back(), ch). + 3) the suffix is a null-terminated character string. Effectively returns + ends_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) ends_with( basic_string_view sv ) + && std::string_view("https://cppreference.com").ends_with(".com"sv) == true + && std::string_view("https://cppreference.com").ends_with(".org"sv) == false + + // (2) ends_with( CharT c ) + && std::string_view("C++20").ends_with('0') == true + && std::string_view("C++20").ends_with('3') == false + + // (3) ends_with( const CharT* s ) + && std::string_view("string_view").ends_with("view") == true + && std::string_view("string_view").ends_with("View") == false + ); + } + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::u16string_view::find.3 b/man/std::u16string_view::find.3 new file mode 100644 index 000000000..8882c44bb --- /dev/null +++ b/man/std::u16string_view::find.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find \- std::basic_string_view::find + +.SH Synopsis + constexpr size_type find( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type find( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type find( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type find( const CharT* s, size_type pos = 0 ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + + constexpr auto str{" long long int;"sv}; + + static_assert( + 1 == str.find("long"sv) && "<- find(v , pos = 0)" && + 6 == str.find("long"sv, 2) && "<- find(v , pos = 2)" && + 0 == str.find(' ') && "<- find(ch, pos = 0)" && + 2 == str.find('o', 1) && "<- find(ch, pos = 1)" && + 2 == str.find("on") && "<- find(s , pos = 0)" && + 6 == str.find("long double", 5, 4) && "<- find(s , pos = 5, count = 4)" + ); + + static_assert(str.npos == str.find("float")); + } + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + finds the first occurrence of the given substring + find \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u16string_view::find_first_not_of.3 b/man/std::u16string_view::find_first_not_of.3 new file mode 100644 index 000000000..6ad069029 --- /dev/null +++ b/man/std::u16string_view::find_first_not_of.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_not_of \- std::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type + find_first_not_of( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_first_not_of( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_first_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_not_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or std::string_view::npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + int main() + { + static_assert(2 == "BCDEF"sv.find_first_not_of("ABC")); + // ^ + static_assert(4 == "BCDEF"sv.find_first_not_of("ABC", 4)); + // ^ + static_assert(1 == "BCDEF"sv.find_first_not_of('B')); + // ^ + static_assert(3 == "BCDEF"sv.find_first_not_of('D', 2)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u16string_view::find_first_of.3 b/man/std::u16string_view::find_first_of.3 new file mode 100644 index 000000000..c6b35518c --- /dev/null +++ b/man/std::u16string_view::find_first_of.3 @@ -0,0 +1,100 @@ +.TH std::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_of \- std::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type + find_first_of( basic_string_view v, size_type pos = 0 ) const \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_first_of( CharT ch, size_type pos = 0 ) const noexcept; + constexpr size_type + find_first_of( const CharT* s, size_type pos, size_type count \fB(3)\fP \fI(since C++17)\fP + ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurrence of any of the characters of v in this view, starting + at position pos. + 2) Equivalent to find_first_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + constexpr bool is_white_space(const char c) + { + return " \\t\\n\\f\\r\\v"sv.find_first_of(c) != N; + }; + + static_assert( + 1 == "alignas"sv.find_first_of("klmn"sv) && + // └─────────────────────────┘ + N == "alignof"sv.find_first_of("wxyz"sv) && + // + 3 == "concept"sv.find_first_of("bcde"sv, /* pos= */ 1) && + // └───────────────────────┘ + N == "consteval"sv.find_first_of("oxyz"sv, /* pos= */ 2) && + // + 6 == "constexpr"sv.find_first_of('x') && + // └─────────────────────┘ + N == "constinit"sv.find_first_of('x') && + // + 6 == "const_cast"sv.find_first_of('c', /* pos= */ 4) && + // └──────────────────────┘ + N == "continue"sv.find_first_of('c', /* pos= */ 42) && + // + 5 == "co_await"sv.find_first_of("cba", /* pos= */ 4) && + // └───────────────────────┘ + 7 == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 2) && + // └────────────────────┘ + N == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 1) && + // + is_white_space(' ') && is_white_space('\\r') && !is_white_space('\\a') + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u16string_view::find_last_not_of.3 b/man/std::u16string_view::find_last_not_of.3 new file mode 100644 index 000000000..1f593444d --- /dev/null +++ b/man/std::u16string_view::find_last_not_of.3 @@ -0,0 +1,79 @@ +.TH std::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_not_of \- std::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type + find_last_not_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_last_not_of( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last character not equal to any of the characters in the given character + sequence. The search considers only the interval [0, pos]. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using std::operator""sv; + + int main() + { + static_assert(1 == "BCDEF"sv.find_last_not_of("DEF")); + // ^ + static_assert(2 == "BCDEFG"sv.find_last_not_of("EFG", 3)); + // ^ + static_assert(2 == "ABBA"sv.find_last_not_of('A')); + // ^ + static_assert(1 == "ABBA"sv.find_last_not_of('A', 1)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u16string_view::find_last_of.3 b/man/std::u16string_view::find_last_of.3 new file mode 100644 index 000000000..0203b94f0 --- /dev/null +++ b/man/std::u16string_view::find_last_of.3 @@ -0,0 +1,92 @@ +.TH std::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_of \- std::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type + find_last_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_last_of( CharT ch, size_type pos = npos ) const noexcept; + constexpr size_type + find_last_of( const CharT* s, size_type pos, size_type count ) \fB(3)\fP \fI(since C++17)\fP + const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_last_of( const CharT* s, size_type pos = npos ) const; + + Finds the last character equal to one of characters in the given character sequence. + Exact search algorithm is not specified. The search considers only the interval + [0, pos]. If the character is not present in the interval, npos will be returned. + + 1) Finds the last occurence of any of the characters of v in this view, ending at + position pos. + 2) Equivalent to find_last_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which the search is to finish + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert( + 5 == "delete"sv.find_last_of("cdef"sv) && + // └────────────────────┘ + N == "double"sv.find_last_of("fghi"sv) && + // + 0 == "else"sv.find_last_of("bcde"sv, 2 /* pos [0..2]: "els" */) && + // └────────────────────────┘ + N == "explicit"sv.find_last_of("abcd"sv, 4 /* pos [0..4]: "expli" */) && + // + 3 == "extern"sv.find_last_of('e') && + // └────────────────────┘ + N == "false"sv.find_last_of('x') && + // + 0 == "inline"sv.find_last_of('i', 2 /* pos [0..2]: "inl" */) && + // └───────────────────────┘ + N == "mutable"sv.find_last_of('a', 2 /* pos [0..2]: "mut" */) && + // + 3 == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 3 /* "cde" */) && + // └─────────────────────────┘ + N == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 2 /* "cd" */) + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u16string_view::front.3 b/man/std::u16string_view::front.3 new file mode 100644 index 000000000..475c3cb67 --- /dev/null +++ b/man/std::u16string_view::front.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::front \- std::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; \fI(since C++17)\fP + + Returns reference to the first character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_prefix(1)) + std::cout << str.front() << ' ' << str << '\\n'; + } + +.SH Output: + + A ABCDEF + B BCDEF + C CDEF + D DEF + E EF + F F + +.SH See also + + back accesses the last character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::u16string_view::max_size.3 b/man/std::u16string_view::max_size.3 new file mode 100644 index 000000000..c3f42d911 --- /dev/null +++ b/man/std::u16string_view::max_size.3 @@ -0,0 +1,66 @@ +.TH std::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::max_size \- std::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; \fI(since C++17)\fP + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::numeric_limits::max() + << " <- numeric_limits::max()\\n" + << std::string_view{}.max_size() + << " <- string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::wstring_view{}.max_size() + << " <- wstring_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n"; + } + +.SH Possible output: + + 9223372036854775807 <- numeric_limits::max() + 4611686018427387899 <- string_view::max_size() + 4611686018427387899 <- basic_string_view::max_size() + 2305843009213693949 <- basic_string_view::max_size() + 1152921504606846974 <- wstring_view::max_size() + 1152921504606846974 <- basic_string_view::max_size() + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + returns the maximum number of characters + max_size \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::npos.3 b/man/std::u16string_view::npos.3 new file mode 100644 index 000000000..c3ba3b575 --- /dev/null +++ b/man/std::u16string_view::npos.3 @@ -0,0 +1,39 @@ +.TH std::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::npos \- std::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); \fI(since C++17)\fP + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Example + + +// Run this code + + #include + + constexpr bool + contains(std::string_view const what, std::string_view const where) noexcept + { + return std::string_view::npos != where.find(what); + } + + int main() + { + using namespace std::literals; + + static_assert(contains("water", "in a bottle of water")); + static_assert(!contains("wine", "in a bottle of champagne")); + static_assert(""sv.npos == "haystack"sv.find("needle")); + } + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI\fI(public static member\fP constant of\fP + std::basic_string) diff --git a/man/std::u16string_view::operator=.3 b/man/std::u16string_view::operator=.3 new file mode 100644 index 000000000..dba80aad4 --- /dev/null +++ b/man/std::u16string_view::operator=.3 @@ -0,0 +1,48 @@ +.TH std::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator= \- std::basic_string_view::operator= + +.SH Synopsis + constexpr basic_string_view& operator=( const basic_string_view& view \fI(since C++17)\fP + ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + assigns values to the string + operator= \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::operator[].3 b/man/std::u16string_view::operator[].3 new file mode 100644 index 000000000..c1d7e55fb --- /dev/null +++ b/man/std::u16string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator[] \- std::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[]( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Does not throw. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], std::basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string str = "Exemplar"; + std::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + accesses the specified character + operator[] \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::rbegin,.3 b/man/std::u16string_view::rbegin,.3 new file mode 100644 index 000000000..8f17b98bf --- /dev/null +++ b/man/std::u16string_view::rbegin,.3 @@ -0,0 +1,60 @@ +.TH std::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rbegin, \- std::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crbegin() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), std::next(str_view.rbegin(), 3), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), std::next(str_view.crbegin(), 3), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fed + fed + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u16string_view::remove_prefix.3 b/man/std::u16string_view::remove_prefix.3 new file mode 100644 index 000000000..31ef25b47 --- /dev/null +++ b/man/std::u16string_view::remove_prefix.3 @@ -0,0 +1,74 @@ +.TH std::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_prefix \- std::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix( size_type n ); \fI(since C++17)\fP + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::literals; + + [[nodiscard("a pure function")]] + constexpr std::size_t count_substrings(std::string_view hive, std::string_view const bee) + { + if (hive.empty() || bee.empty()) + return 0U; + + std::size_t buzz{}; + while (bee.size() <= hive.size()) + { + const auto pos = hive.find(bee); + if (pos == hive.npos) + break; + ++buzz; + hive.remove_prefix(pos + bee.size()); + } + return buzz; + } + + int main() + { + std::string str = " trim me"; + std::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + + constexpr auto hive{"bee buzz bee buzz bee"}; + std::cout << "There are " << count_substrings(hive, "bee") << " bees in this hive.\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + There are 3 bees in this hive. + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP diff --git a/man/std::u16string_view::remove_suffix.3 b/man/std::u16string_view::remove_suffix.3 new file mode 100644 index 000000000..01bee81f3 --- /dev/null +++ b/man/std::u16string_view::remove_suffix.3 @@ -0,0 +1,51 @@ +.TH std::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_suffix \- std::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); \fI(since C++17)\fP + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP diff --git a/man/std::u16string_view::rend,std::basic_string_view::crend.3 b/man/std::u16string_view::rend,std::basic_string_view::crend.3 new file mode 100644 index 000000000..5f201fac0 --- /dev/null +++ b/man/std::u16string_view::rend,std::basic_string_view::crend.3 @@ -0,0 +1,61 @@ +.TH std::basic_string_view::rend,std::basic_string_view::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rend,std::basic_string_view::crend \- std::basic_string_view::rend,std::basic_string_view::crend + +.SH Synopsis + constexpr const_reverse_iterator rend() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crend() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), str_view.rend(), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), str_view.crend(), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fedcba + fedcba + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u16string_view::rfind.3 b/man/std::u16string_view::rfind.3 new file mode 100644 index 000000000..684090010 --- /dev/null +++ b/man/std::u16string_view::rfind.3 @@ -0,0 +1,81 @@ +.TH std::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rfind \- std::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind( basic_string_view v, size_type pos = \fB(1)\fP \fI(since C++17)\fP + npos ) const noexcept; + constexpr size_type rfind( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type rfind( const CharT* s, size_type pos, \fB(3)\fP \fI(since C++17)\fP + size_type count ) const; + constexpr size_type rfind( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last occurrence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert(true + && (6 == "AB AB AB"sv.rfind("AB")) + && (6 == "AB AB AB"sv.rfind("ABCD", N, 2)) + && (3 == "AB AB AB"sv.rfind("AB", 5)) + && (0 == "AB CD EF"sv.rfind("AB", 0)) + && (2 == "B AB AB "sv.rfind("AB", 2)) + && (N == "B AB AB "sv.rfind("AB", 1)) + && (5 == "B AB AB "sv.rfind('A')) + && (4 == "AB AB AB"sv.rfind('B', 4)) + && (N == "AB AB AB"sv.rfind('C')) + ); + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u16string_view::size,std::basic_string_view::length.3 b/man/std::u16string_view::size,std::basic_string_view::length.3 new file mode 100644 index 000000000..8f96ca90c --- /dev/null +++ b/man/std::u16string_view::size,std::basic_string_view::length.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::size,std::basic_string_view::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::size,std::basic_string_view::length \- std::basic_string_view::size,std::basic_string_view::length + +.SH Synopsis + constexpr size_type size() const noexcept; \fI(since C++17)\fP + constexpr size_type length() const noexcept; \fI(since C++17)\fP + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::starts_with.3 b/man/std::u16string_view::starts_with.3 new file mode 100644 index 000000000..9c8fd78c7 --- /dev/null +++ b/man/std::u16string_view::starts_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::starts_with \- std::basic_string_view::starts_with + +.SH Synopsis + constexpr bool starts_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool starts_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool starts_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view begins with the given prefix, where + + 1) the prefix is a string view. Effectively returns basic_string_view(data(), + std::min(size(), sv.size())) == sv. + 2) the prefix is a single character. Effectively returns !empty() && + Traits::eq(front(), ch). + 3) the prefix is a null-terminated character string. Effectively returns + starts_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) starts_with( basic_string_view ) + && "https://cppreference.com"sv.starts_with("http"sv) == true + && "https://cppreference.com"sv.starts_with("ftp"sv) == false + + // (2) starts_with( CharT ) + && "C++20"sv.starts_with('C') == true + && "C++20"sv.starts_with('J') == false + + // (3) starts_with( const CharT* ) + && std::string_view("string_view").starts_with("string") == true + && std::string_view("string_view").starts_with("String") == false + ); + } + +.SH See also + + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::u16string_view::substr.3 b/man/std::u16string_view::substr.3 new file mode 100644 index 000000000..d7edf51b7 --- /dev/null +++ b/man/std::u16string_view::substr.3 @@ -0,0 +1,76 @@ +.TH std::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::substr \- std::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view substr( size_type pos = 0, \fI(since C++17)\fP + size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rlen), where rlen is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rlen). + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + typedef std::size_t count_t, pos_t; + + constexpr std::string_view data{"ABCDEF"}; + + std::cout << data.substr() << '\\n'; // ABCDEF, i.e. data[0, 5] that is [0, 6) + std::cout << data.substr(pos_t(1)) << '\\n'; // BCDEF, i.e. [1, 6) + std::cout << data.substr(pos_t(2), count_t(3)) << '\\n'; // CDE, i.e. [2, 2 + 3) + std::cout << data.substr(pos_t(4), count_t(42)) << '\\n'; // EF, i.e. [4, 6) + + try + { + [[maybe_unused]] + auto sub = data.substr(pos_t(666), count_t(1)); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + ABCDEF + BCDEF + CDE + EF + basic_string_view::substr: __pos (which is 666) > __size (which is 6) + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function of std::basic_string)\fP diff --git a/man/std::u16string_view::swap.3 b/man/std::u16string_view::swap.3 new file mode 100644 index 000000000..c6b397cfe --- /dev/null +++ b/man/std::u16string_view::swap.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::swap \- std::basic_string_view::swap + +.SH Synopsis + constexpr void swap( basic_string_view& v ) noexcept; \fI(since C++17)\fP + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view a = "AAA"; + std::string_view b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swaps the contents + swap \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u16string_view::u16string_view.3 b/man/std::u16string_view::u16string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::u16string_view::u16string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string.3 b/man/std::u32string.3 deleted file mode 120000 index 51b9e0d1f..000000000 --- a/man/std::u32string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string.3 \ No newline at end of file diff --git a/man/std::u32string.3 b/man/std::u32string.3 new file mode 100644 index 000000000..ba00dc78d --- /dev/null +++ b/man/std::u32string.3 @@ -0,0 +1,397 @@ +.TH std::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string \- std::basic_string + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, \fB(1)\fP + class Allocator = std::allocator + + > class basic_string; + namespace pmr { + + template< + class CharT, + class Traits = std::char_traits \fB(2)\fP \fI(since C++17)\fP + > using basic_string = + std::basic_string>; + + } + + The class template basic_string stores and manipulates sequences of character-like + objects, which are non-array objects of TrivialType and StandardLayoutType. The + class is dependent neither on the character type nor on the nature of operations on + that type. The definitions of the operations are supplied via the Traits template + parameter - a specialization of std::char_traits or a compatible traits class. + + The elements of a basic_string are stored contiguously, that is, for a basic_string + s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()) + , and *(s.begin() + s.size()) has value CharT() (a null terminator) + \fI(since C++11)\fP; or, equivalently, a pointer to s[0] can be passed to functions that + expect a pointer to the first element of + an array + \fI(until C++11)\fP + a null-terminated array + \fI(since C++11)\fP of CharT. + + std::basic_string satisfies the requirements of AllocatorAwareContainer (except that + customized construct/destroy are not used for construction/destruction of elements), + SequenceContainer + and ContiguousContainer + \fI(since C++17)\fP. + + If any of Traits::char_type and Allocator::char_type is different from CharT, the + program is ill-formed. + + Member functions of std::basic_string are constexpr: it is possible to + create and use std::string objects in the evaluation of a constant + expression. + \fI(since C++20)\fP + However, std::string objects generally cannot be constexpr, because + any dynamically allocated storage must be released in the same + evaluation of constant expression. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string std::basic_string + std::wstring std::basic_string + std::u8string (C++20) std::basic_string + std::u16string \fI(C++11)\fP std::basic_string + std::u32string \fI(C++11)\fP std::basic_string + std::pmr::string \fI(C++17)\fP std::pmr::basic_string + std::pmr::wstring \fI(C++17)\fP std::pmr::basic_string + std::pmr::u8string (C++20) std::pmr::basic_string + std::pmr::u16string \fI(C++17)\fP std::pmr::basic_string + std::pmr::u32string \fI(C++17)\fP std::pmr::basic_string + +.SH Template parameters + + CharT - character type + Traits - traits class specifying the operations on the character type + Allocator - Allocator type used to allocate internal storage + +.SH Member types + + Member type Definition + traits_type Traits + value_type CharT + allocator_type Allocator + Allocator::size_type \fI(until C++11)\fP + size_type std::allocator_traits::size_type \fI(since C++11)\fP + + + Allocator::difference_type (until + C++11) + difference_type std::allocator_traits::difference_type (since + C++11) + + + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP + const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator, + iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator, + const_iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + +.SH Member functions + + constructor constructs a basic_string + \fI(public member function)\fP + destroys the string, deallocating internal storage if + destructor used + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP +.SH Element access + at accesses the specified character with bounds checking + \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP + returns a non-modifiable standard C character array + c_str version of the string + \fI(public member function)\fP + operator basic_string_view returns a non-modifiable string_view into the entire + \fI(C++17)\fP string + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP +.SH Capacity + empty checks whether the string is empty + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + returns the number of characters that can be held in + capacity currently allocated storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP +.SH Modifiers + clear clears the contents + \fI(public member function)\fP + insert inserts characters + \fI(public member function)\fP + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP + pop_back removes the last character + (DR*) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + replace replaces specified portion of a string + \fI(public member function)\fP + replace_with_range replaces specified portion of a string with a range of + (C++23) characters + \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP + changes the number of characters stored and possibly + resize_and_overwrite overwrites indeterminate contents via user-provided + (C++23) operation + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Search + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Operations + compare compares two strings + \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string contains the given substring or + (C++23) character + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator+ concatenates two strings or a string and a char + \fI(function template)\fP + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + std::swap(std::basic_string) specializes the std::swap algorithm + \fI(function template)\fP + erase(std::basic_string) erases all elements satisfying specific criteria + erase_if(std::basic_string) \fI(function template)\fP + (C++20) +.SH Input/output + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + getline read data from an I/O stream into a string + \fI(function template)\fP +.SH Numeric conversions + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + stof + stod + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_literals + operator""s converts a character array literal to basic_string + \fI(C++14)\fP \fI(function)\fP + +.SH Helper classes + + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Although it is required that customized construct or destroy is used when + constructing or destroying elements of std::basic_string until C++23, all + implementations only used the default mechanism. The requirement is corrected by + P1072R10 to match existing practice. + + Feature-test macro Value Std Feature + __cpp_lib_string_udls 201304L \fI(C++14)\fP User-defined literals for + string types + __cpp_lib_starts_ends_with 201711L (C++20) starts_with, ends_with + __cpp_lib_constexpr_string 201907L (C++20) Constexpr for + std::basic_string + __cpp_lib_char8_t 201907L (C++20) std::u8string + __cpp_lib_erase_if 202002L (C++20) erase, erase_if + __cpp_lib_string_contains 202011L (C++23) contains + __cpp_lib_string_resize_and_overwrite 202110L (C++23) resize_and_overwrite + Member functions for + __cpp_lib_containers_ranges 202202L (C++23) construction, insertion, and + replacement that accept + container compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + // Creating a string from const char* + std::string str1 = "hello"; + + // Creating a string using string literal + auto str2 = "world"s; + + // Concatenating strings + std::string str3 = str1 + " " + str2; + + // Print out the result + std::cout << str3 << '\\n'; + + std::string::size_type pos = str3.find(" "); + str1 = str3.substr(pos + 1); // the part after the space + str2 = str3.substr(0, pos); // the part till the space + + std::cout << str1 << ' ' << str2 << '\\n'; + + // Accessing an element using subscript operator[] + std::cout << str1[0] << '\\n'; + str1[0] = 'W'; + std::cout << str1 << '\\n'; + } + +.SH Output: + + hello world + world hello + w + World + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + contiguity of the storage for elements of + LWG 530 C++98 basic_string required again + was accidently made not required by LWG259 + the behavior is undefined if any of the program is + LWG 2994 C++98 Traits::char_type^[1] ill-formed in this + (P1148R0) and Allocator::char_type is different from case + CharT + + 1. ↑ The Traits::char_type case is fixed in P1148R0. + +.SH See also + + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP + +.SH External links + + C++ string handling + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::u32string::append.3 b/man/std::u32string::append.3 deleted file mode 120000 index b50ac7eda..000000000 --- a/man/std::u32string::append.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::append.3 \ No newline at end of file diff --git a/man/std::u32string::append.3 b/man/std::u32string::append.3 new file mode 100644 index 000000000..dfcb8cb7a --- /dev/null +++ b/man/std::u32string::append.3 @@ -0,0 +1,185 @@ +.TH std::basic_string::append 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append \- std::basic_string::append + +.SH Synopsis + basic_string& append( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& append( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& append( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& append( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos ); C++20) + basic_string& append( const CharT* s, \fB(4)\fP (constexpr since + size_type count ); C++20) + basic_string& append( const CharT* s ); \fB(5)\fP (constexpr since + C++20) + template< class InputIt > (constexpr since + basic_string& append( InputIt first, InputIt \fB(6)\fP C++20) + last ); \fB(3)\fP + basic_string& append( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(7)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& append( const StringViewLike& t \fB(8)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& append( const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos ); + + Appends additional characters to the string. + + 1) Appends count copies of character ch. + 2) Appends string str. + 3) Appends a substring [pos, pos + count) of str. + * If the requested substring lasts past the end of the string, or if count == + npos, the appended substring is [pos, size()). + * If pos > str.size(), std::out_of_range is thrown. + 4) Appends characters in the range [s, s + count). This range can contain null + characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 5) Appends the null-terminated character string pointed to by s, as if by append(s, + Traits::length(s)). + 6) Appends characters in the range [first, last). + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload only participates in overload resolution if InputIt \fI(since C++11)\fP + qualifies as a LegacyInputIterator. + + 7) Appends characters from the initializer list ilist. + 8) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends all characters from sv as if by append(sv.data(), + sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends the characters from the subview [pos, pos + count) of + sv. + * If the requested subview extends past the end of sv, or if count == npos, the + appended subview is [pos, sv.size()). + * If pos >= sv.size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - number of characters to append + pos - the index of the first character to append + ch - character value to append + first, last - range of characters to append + str - string to append + s - pointer to the character string to append + ilist - initializer list with the characters to append + t - object convertible to std::basic_string_view with the characters to + append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::basic_string str = "string"; + const char* cptr = "C-string"; + const char carr[] = "Two and one"; + + std::string output; + + // 1) Append a char 3 times. + // Notice, this is the only overload accepting chars. + output.append(3, '*'); + std::cout << "1) " << output << '\\n'; + + // 2) Append a whole string + output.append(str); + std::cout << "2) " << output << '\\n'; + + // 3) Append part of a string (last 3 letters, in this case) + output.append(str, 3, 3); + std::cout << "3) " << output << '\\n'; + + // 4) Append part of a C-string + // Notice, because `append` returns *this, we can chain calls together + output.append(1, ' ').append(carr, 4); + std::cout << "4) " << output << '\\n'; + + // 5) Append a whole C-string + output.append(cptr); + std::cout << "5) " << output << '\\n'; + + // 6) Append range + output.append(&carr[3], std::end(carr)); + std::cout << "6) " << output << '\\n'; + + // 7) Append initializer list + output.append({' ', 'l', 'i', 's', 't'}); + std::cout << "7) " << output << '\\n'; + } + +.SH Output: + + 1) *** + 2) ***string + 3) ***stringing + 4) ***stringing Two + 5) ***stringing Two C-string + 6) ***stringing Two C-string and one + 7) ***stringing Two C-string and one list + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(8)\fP causes ambiguity in avoided by making it a + some cases template + +.SH See also + + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + strcat concatenates two strings + \fI(function)\fP + strncat concatenates a certain amount of characters of two strings + \fI(function)\fP + wcscat appends a copy of one wide string to another + \fI(function)\fP + appends a certain amount of wide characters from one wide string to + wcsncat another + \fI(function)\fP diff --git a/man/std::u32string::append_range.3 b/man/std::u32string::append_range.3 new file mode 100644 index 000000000..ede115277 --- /dev/null +++ b/man/std::u32string::append_range.3 @@ -0,0 +1,65 @@ +.TH std::basic_string::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append_range \- std::basic_string::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& append_range( R&& rg ); + + Appends all characters from the range rg. + + Equivalent to + + return append(std::basic_string( std::from_range, std::forward(rg), get_allocator())); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string head{"long long"}; + const auto tail = {' ', 'i', 'n', 't'}; + + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.append(tail.begin(), tail.end()); + #endif + + assert(head == "long long int"); + } + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::u32string::assign.3 b/man/std::u32string::assign.3 deleted file mode 120000 index b4f3ab165..000000000 --- a/man/std::u32string::assign.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::assign.3 \ No newline at end of file diff --git a/man/std::u32string::assign.3 b/man/std::u32string::assign.3 new file mode 100644 index 000000000..afbe7a690 --- /dev/null +++ b/man/std::u32string::assign.3 @@ -0,0 +1,210 @@ +.TH std::basic_string::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign \- std::basic_string::assign + +.SH Synopsis + basic_string& assign( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& assign( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& assign( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& assign( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos); C++20) + basic_string& assign( basic_string&& str ) \fI(since C++11)\fP + noexcept(/* see below */); \fB(4)\fP (constexpr since + C++20) + basic_string& assign( const CharT* s, \fB(5)\fP (constexpr since + size_type count ); C++20) + basic_string& assign( const CharT* s ); \fB(6)\fP (constexpr since + C++20) + template< class InputIt > \fB(3)\fP (constexpr since + basic_string& assign( InputIt first, InputIt \fB(7)\fP C++20) + last ); + basic_string& assign( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(8)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t \fB(9)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t, \fB(10)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos); + + Replaces the contents of the string. + + 1) Replaces the contents with count copies of character ch. + 2) Replaces the contents with a copy of str. Equivalent to *this = str;. + In particular, allocator propagation may take place. + \fI(since C++11)\fP + 3) Replaces the contents with a substring [pos, pos + count) of str. If the + requested substring lasts past the end of the string, or if count == npos, the + resulting substring is [pos, str.size()). If pos > str.size(), std::out_of_range is + thrown. + 4) Replaces the contents with those of str using move semantics. Equivalent to *this + = std::move(str). In particular, allocator propagation may take place. + 5) Replaces the contents with copies of the characters in the range [s, s + count). + This range can contain null characters. + 6) Replaces the contents with those of null-terminated character string pointed to + by s. The length of the string is determined by the first null character using + Traits::length(s). + 7) Replaces the contents with copies of the characters in the range [first, last). + This overload does not participate in overload resolution if InputIt does not + satisfy LegacyInputIterator. + \fI(since C++11)\fP + 8) Replaces the contents with those of the initializer list ilist. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of sv, as if by + assign(sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with the characters from the subview + [pos, pos + count) of sv. If the requested subview lasts past the end of sv, or if + count == npos, the resulting subview is [pos, sv.size()). If pos > sv.size(), + std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - size of the resulting string + pos - index of the first character to take + ch - value to initialize characters of the string with + first, last - range to copy the characters from + str - string to be used as source to initialize the characters with + s - pointer to a character string to use as source to initialize the + string with + ilist - std::initializer_list to initialize the characters of the string with + t - object (convertible to std::basic_string_view) to initialize the + characters of the string with +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in count. + 2) Linear in size of str. + 3) Linear in count. + 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 5) Linear in count. + 6) Linear in size of s. + 7) Linear in distance between first and last. + 8) Linear in size of ilist. + 9) Linear in size of t. + +.SH Exceptions + + 4) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + // assign(size_type count, CharT ch) + s.assign(4, '='); + std::cout << s << '\\n'; // "====" + + std::string const c("Exemplary"); + // assign(const basic_string& str) + s.assign(c); + std::cout << c << " == " << s << '\\n'; // "Exemplary == Exemplary" + + // assign(const basic_string& str, size_type pos, size_type count) + s.assign(c, 0, c.length() - 1); + std::cout << s << '\\n'; // "Exemplar"; + + // assign(basic_string&& str) + s.assign(std::string("C++ by ") + "example"); + std::cout << s << '\\n'; // "C++ by example" + + // assign(const CharT* s, size_type count) + s.assign("C-style string", 7); + std::cout << s << '\\n'; // "C-style" + + // assign(const CharT* s) + s.assign("C-style\\0string"); + std::cout << s << '\\n'; // "C-style" + + char mutable_c_str[] = "C-style string"; + // assign(InputIt first, InputIt last) + s.assign(std::begin(mutable_c_str), std::end(mutable_c_str) - 1); + std::cout << s << '\\n'; // "C-style string" + + // assign(std::initializer_list ilist) + s.assign({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << s << '\\n'; // "C-style" + } + +.SH Output: + + ==== + Exemplary == Exemplary + Exemplar + C++ by example +.SH C-style +.SH C-style + C-style string +.SH C-style + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + non-normative note stated that swap + LWG 2063 C++11 is corrected to require move + a valid implementation of assignment + move-assign + LWG 2579 C++11 assign(const basic_string&) made to propagate allocators + did not propagate allocators if needed + LWG 2946 C++17 overload \fB(9)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::assign_range.3 b/man/std::u32string::assign_range.3 new file mode 100644 index 000000000..7bfd17959 --- /dev/null +++ b/man/std::u32string::assign_range.3 @@ -0,0 +1,74 @@ +.TH std::basic_string::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign_range \- std::basic_string::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& assign_range( R&& rg ); + + Replaces the contents of the string with the values in the range rg. + + Equivalent to + + return assign( + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto source = {'s', 'o', 'u', 'r', 'c', 'e'}; + std::string destination{"destination"}; + + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.begin(), source.end()); + #endif + + assert(destination == "source"); + } + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP diff --git a/man/std::u32string::at.3 b/man/std::u32string::at.3 deleted file mode 120000 index 1f402dba2..000000000 --- a/man/std::u32string::at.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::at.3 \ No newline at end of file diff --git a/man/std::u32string::at.3 b/man/std::u32string::at.3 new file mode 100644 index 000000000..36e5a7e1d --- /dev/null +++ b/man/std::u32string::at.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::at \- std::basic_string::at + +.SH Synopsis + CharT& at( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& at( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("message"); // for capacity + + s = "abc"; + s.at(2) = 'x'; // OK + std::cout << s << '\\n'; + + std::cout << "string size = " << s.size() << '\\n'; + std::cout << "string capacity = " << s.capacity() << '\\n'; + + try + { + // This will throw since the requested offset is greater than the current size. + s.at(3) = 'x'; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + } + +.SH Possible output: + + abx + string size = 3 + string capacity = 7 + basic_string::at + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::back.3 b/man/std::u32string::back.3 deleted file mode 120000 index 33e85e2c2..000000000 --- a/man/std::u32string::back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::back.3 \ No newline at end of file diff --git a/man/std::u32string::back.3 b/man/std::u32string::back.3 new file mode 100644 index 000000000..5dd0d47ca --- /dev/null +++ b/man/std::u32string::back.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::back \- std::basic_string::back + +.SH Synopsis + CharT& back(); \fB(1)\fP (constexpr since C++20) + const CharT& back() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the last character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& back1 = s.back(); + back1 = 's'; + std::cout << s << '\\n'; // "Exemplars" + + std::string const c("Exemplary"); + char const& back2 = c.back(); + std::cout << back2 << '\\n'; // 'y' + } + +.SH Output: + + Exemplars + y + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function back() + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::basic_string.3 b/man/std::u32string::basic_string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::u32string::basic_string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::u32string::basic_string.3 b/man/std::u32string::basic_string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::u32string::basic_string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::u32string::begin,.3 b/man/std::u32string::begin,.3 new file mode 100644 index 000000000..a9b49707a --- /dev/null +++ b/man/std::u32string::begin,.3 @@ -0,0 +1,69 @@ +.TH std::basic_string::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::begin, \- std::basic_string::begin, + +.SH Synopsis + + iterator begin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the first character of the string. + + begin() returns a mutable or constant iterator, depending on the constness of *this. + + cbegin() always returns a constant iterator. It is equivalent to const_cast(*this).begin(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplar"); + *s.begin() = 'e'; + std::cout << s << '\\n'; + + auto i = s.cbegin(); + std::cout << *i << '\\n'; + // *i = 'E'; // error: i is a constant iterator + } + +.SH Output: + + exemplar + e + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::begin,std::basic_string::cbegin.3 b/man/std::u32string::begin,std::basic_string::cbegin.3 deleted file mode 120000 index aaa6194e9..000000000 --- a/man/std::u32string::begin,std::basic_string::cbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::begin,std::basic_string::cbegin.3 \ No newline at end of file diff --git a/man/std::u32string::c_str.3 b/man/std::u32string::c_str.3 deleted file mode 120000 index 3a01af623..000000000 --- a/man/std::u32string::c_str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::c_str.3 \ No newline at end of file diff --git a/man/std::u32string::c_str.3 b/man/std::u32string::c_str.3 new file mode 100644 index 000000000..e1a3268f3 --- /dev/null +++ b/man/std::u32string::c_str.3 @@ -0,0 +1,88 @@ +.TH std::basic_string::c_str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::c_str \- std::basic_string::c_str + +.SH Synopsis + const CharT* c_str() const; (noexcept since C++11) + (constexpr since C++20) + + Returns a pointer to a null-terminated character array with data equivalent to those + stored in the string. + + The pointer is such that the range [c_str(), c_str() + size()] is valid and the + values in it correspond to the values stored in the string with an additional null + character after the last position. + + The pointer obtained from c_str() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string + , excluding operator[], at(), front(), back(), begin(), rbegin(), end() and + rend() + \fI(since C++11)\fP. + + Writing to the character array accessed through c_str() is undefined behavior. + + c_str() and data() perform the same function. \fI(since C++11)\fP + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying character storage. + + c_str()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + c_str() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Notes + + The pointer obtained from c_str() may only be treated as a pointer to a + null-terminated character string if the string object does not contain other null + characters. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + extern "C" void c_func(const char* c_str) + { + printf("c_func called with '%s'\\n", c_str); + } + + int main() + { + std::string const s("Emplary"); + const char* p = s.c_str(); + assert(s.size() == std::strlen(p)); + assert(std::equal(s.begin(), s.end(), p)); + assert(std::equal(p, p + s.size(), s.begin())); + assert('\\0' == *(p + s.size())); + + c_func(s.c_str()); + } + +.SH Output: + + c_func called with 'Emplary' + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP diff --git a/man/std::u32string::capacity.3 b/man/std::u32string::capacity.3 deleted file mode 120000 index 6045777da..000000000 --- a/man/std::u32string::capacity.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::capacity.3 \ No newline at end of file diff --git a/man/std::u32string::capacity.3 b/man/std::u32string::capacity.3 new file mode 100644 index 000000000..32f50b319 --- /dev/null +++ b/man/std::u32string::capacity.3 @@ -0,0 +1,93 @@ +.TH std::basic_string::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::capacity \- std::basic_string::capacity + +.SH Synopsis + size_type capacity() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the number of characters that the string has currently allocated space for. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Capacity of the currently allocated storage, i.e. the storage available for storing + elements. + +.SH Complexity + + Constant. + +.SH Notes + + Memory locations obtained from the allocator but not available for storing any + element are not counted in the allocated storage. Note that the null terminator is + not an element of the std::basic_string. + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_capacity(std::string const& s) + { + std::cout << std::quoted(s) << " has capacity " << s.capacity() << ".\\n"; + } + + int main() + { + std::string s{"Exemplar"}; + show_capacity(s); + + s += " is an example string."; + show_capacity(s); + + s.clear(); + show_capacity(s); + + std::cout << "\\nDemonstrate the capacity's growth policy." + "\\nSize: Capacity: Ratio:\\n" << std::left; + + std::string g; + auto old_cap{g.capacity()}; + + for (int mark{}; mark != 5; ++mark) + { + while (old_cap == g.capacity()) + g.push_back('.'); + + std::cout << std::setw( 7) << g.size() + << std::setw(11) << g.capacity() + << std::setw(10) << g.capacity() / static_cast(old_cap) << '\\n'; + + old_cap = g.capacity(); + } + } + +.SH Possible output: + + "Exemplar" has capacity 15. + "Exemplar is an example string." has capacity 30. + "" has capacity 30. + + Demonstrate the capacity's growth policy. + Size: Capacity: Ratio: + 16 30 2 + 31 60 2 + 61 120 2 + 121 240 2 + 241 480 2 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP diff --git a/man/std::u32string::clear.3 b/man/std::u32string::clear.3 deleted file mode 120000 index df77a9b91..000000000 --- a/man/std::u32string::clear.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::clear.3 \ No newline at end of file diff --git a/man/std::u32string::clear.3 b/man/std::u32string::clear.3 new file mode 100644 index 000000000..a1e021b20 --- /dev/null +++ b/man/std::u32string::clear.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::clear \- std::basic_string::clear + +.SH Synopsis + void clear(); (noexcept since C++11) + (constexpr since C++20) + + Removes all characters from the string as if by executing erase(begin(), end()). + + All pointers, references, and iterators are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Unlike for std::vector::clear, the C++ standard does not explicitly require that + capacity is unchanged by this function, but existing implementations do not change + capacity. This means that they do not release the allocated memory (see also + shrink_to_fit). + +.SH Complexity + + Linear in the size of the string, although existing implementations operate in + constant time. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s{"Exemplar"}; + std::string::size_type const capacity = s.capacity(); + + s.clear(); + assert(s.capacity() == capacity); // <- not guaranteed + assert(s.empty()); + assert(s.size() == 0); + } + +.SH See also + + erase removes characters + \fI(public member function)\fP diff --git a/man/std::u32string::compare.3 b/man/std::u32string::compare.3 deleted file mode 120000 index abd41e671..000000000 --- a/man/std::u32string::compare.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::compare.3 \ No newline at end of file diff --git a/man/std::u32string::compare.3 b/man/std::u32string::compare.3 new file mode 100644 index 000000000..890b367f1 --- /dev/null +++ b/man/std::u32string::compare.3 @@ -0,0 +1,285 @@ +.TH std::basic_string::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::compare \- std::basic_string::compare + +.SH Synopsis + (noexcept since + int compare( const basic_string& str ) const; \fB(1)\fP C++11) + (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(2)\fP (constexpr since + const basic_string& str ) const; C++20) + int compare( size_type pos1, size_type count1, + + const basic_string& str, \fI(until C++14)\fP + + size_type pos2, size_type count2 + ) const; + int compare( size_type pos1, size_type count1, + \fI(since C++14)\fP + const basic_string& str, (constexpr since + C++20) + size_type pos2, size_type count2 + = npos ) const; + int compare( const CharT* s ) const; \fB(4)\fP (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(5)\fP (constexpr since + const CharT* s ) const; C++20) + int compare( size_type pos1, size_type count1, \fB(3)\fP (constexpr since + const CharT* s, size_type count2 \fB(6)\fP C++20) + ) const; + template< class StringViewLike > \fI(since C++17)\fP + int compare( const StringViewLike& t ) const \fB(7)\fP (constexpr since + noexcept(/* see below */); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + int compare( size_type pos1, size_type count1, \fB(8)\fP (constexpr since + C++20) + const StringViewLike& t ) const; + template< class StringViewLike > + + int compare( size_type pos1, size_type count1, \fI(since C++17)\fP + const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos2, size_type count2 + = npos) const; + + Compares two character sequences. + + 1) Compares this string to str. + 2) Compares a [pos1, pos1 + count1) substring of this string to str. + * If count1 > size() - pos1, the substring is [pos1, size()). + 3) Compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of str. + * If count1 > size() - pos1, the first substring is [pos1, size()). + * If count2 > str.size() - pos2, the second substring is [pos2, str.size()). + 4) Compares this string to the null-terminated character sequence beginning at the + character pointed to by s with length Traits::length(s). + 5) Compares a [pos1, pos1 + count1) substring of this string to the null-terminated + character sequence beginning at the character pointed to by s with length + Traits::length(s). + * If count1 > size() - pos1, the substring is [pos1, size()). + 6) Compares a [pos1, pos1 + count1) substring of this string to the characters in + the range [s, s + count2). The characters in [s, s + count2) may include null + characters. + * If count1 > size() - pos1, the substring is [pos1, size()). + 7-9) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then + 7) compares this string to sv; + 8) compares a [pos1, pos1 + count1) substring of this string to sv, as if by + std::basic_string_view(*this).substr(pos1, count1).compare(sv); + 9) compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of sv, as if by std::basic_string_view(*this) + .substr(pos1, count1).compare(sv.substr(pos2, count2)). + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false.. + + A character sequence consisting of count1 characters starting at data1 is compared + to a character sequence consisting of count2 characters starting at data2 as + follows: + + * First, calculate the number of characters to compare, as if by size_type rlen = + std::min(count1, count2). + * Then compare the sequences by calling Traits::compare(data1, data2, rlen). For + standard strings this function performs character-by-character lexicographical + comparison. If the result is zero (the character sequences are equal so far), + then their sizes are compared as follows: + + Condition Result Return value + Traits::compare(data1, data2, rlen) < 0 data1 is less than <0 + data2 + size1 < size2 data1 is less than <0 + data2 + Traits::compare(data1, data2, rlen) == size1 == data1 is equal to 0 + 0 size2 data2 + size1 > size2 data1 is greater >0 + than data2 + Traits::compare(data1, data2, rlen) > 0 data1 is greater >0 + than data2 + +.SH Parameters + + str - other string to compare to + s - pointer to the character string to compare to + count1 - number of characters of this string to compare + pos1 - position of the first character in this string to compare + count2 - number of characters of the given string to compare + pos2 - position of the first character of the given string to compare + t - object (convertible to std::basic_string_view) to compare to + +.SH Return value + + * Negative value if *this appears before the character sequence specified by the + arguments, in lexicographical order. + * Zero if both character sequences compare equivalent. + * Positive value if *this appears after the character sequence specified by the + arguments, in lexicographical order. + +.SH Exceptions + + The overloads taking parameters named pos1 or pos2 throws std::out_of_range if the + argument is out of range. + + 7) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + 8,9) Throws anything thrown by the conversion to std::basic_string_view. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Possible implementation + + overload \fB(1)\fP + template + int std::basic_string::compare + (const std::basic_string& s) const noexcept + { + size_type lhs_sz = size(); + size_type rhs_sz = s.size(); + int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz)); + if (result != 0) + return result; + if (lhs_sz < rhs_sz) + return -1; + if (lhs_sz > rhs_sz) + return 1; + return 0; + } + +.SH Notes + + For the situations when three-way comparison is not required, std::basic_string + provides the usual relational operators (<, <=, ==, >, etc). + + By default (with the default std::char_traits), this function is not + locale-sensitive. See std::collate::compare for locale-aware three-way string + comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print_compare_result(std::string_view str1, + std::string_view str2, + int compare_result) + { + if (compare_result < 0) + std::cout << std::quoted(str1) << " comes before " + << std::quoted(str2) << ".\\n"; + else if (compare_result > 0) + std::cout << std::quoted(str2) << " comes before " + << std::quoted(str1) << ".\\n"; + else + std::cout << std::quoted(str1) << " and " + << std::quoted(str2) << " are the same.\\n"; + } + + int main() + { + std::string batman{"Batman"}; + std::string superman{"Superman"}; + int compare_result{0}; + + // 1) Compare with other string + compare_result = batman.compare(superman); + std::cout << "1) "; + print_compare_result("Batman", "Superman", compare_result); + + // 2) Compare substring with other string + compare_result = batman.compare(3, 3, superman); + std::cout << "2) "; + print_compare_result("man", "Superman", compare_result); + + // 3) Compare substring with other substring + compare_result = batman.compare(3, 3, superman, 5, 3); + std::cout << "3) "; + print_compare_result("man", "man", compare_result); + + // Compare substring with other substring + // defaulting to end of other string + assert(compare_result == batman.compare(3, 3, superman, 5)); + + // 4) Compare with char pointer + compare_result = batman.compare("Superman"); + std::cout << "4) "; + print_compare_result("Batman", "Superman", compare_result); + + // 5) Compare substring with char pointer + compare_result = batman.compare(3, 3, "Superman"); + std::cout << "5) "; + print_compare_result("man", "Superman", compare_result); + + // 6) Compare substring with char pointer substring + compare_result = batman.compare(0, 3, "Superman", 5); + std::cout << "6) "; + print_compare_result("Bat", "Super", compare_result); + } + +.SH Output: + + 1) "Batman" comes before "Superman". + 2) "Superman" comes before "man". + 3) "man" and "man" are the same. + 4) "Batman" comes before "Superman". + 5) "Superman" comes before "man". + 6) "Bat" comes before "Super". + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the parameter count2 of overload default argument removed, + LWG 5 C++98 \fB(6)\fP split to overloads \fB(5)\fP and + had a default argument npos \fB(6)\fP + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(7)\fP caused ambiguity in avoided by making it a + some cases template + noexcept for overload \fB(7)\fP was + P1148R0 C++17 accidentally restored + dropped by the resolution of + LWG2946 + +.SH See also + + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + substr returns a substring + \fI(public member function)\fP + collate defines lexicographical comparison and hashing of strings + \fI(class template)\fP + strcoll compares two strings in accordance to the current locale + \fI(function)\fP + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + compares two views + compare \fI\fI(public member\fP function of\fP + std::basic_string_view) + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::contains.3 b/man/std::u32string::contains.3 new file mode 100644 index 000000000..a6b202311 --- /dev/null +++ b/man/std::u32string::contains.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::contains \- std::basic_string::contains + +.SH Synopsis + constexpr bool + contains( std::basic_string_view sv ) const \fB(1)\fP (since C++23) + noexcept; + constexpr bool \fB(2)\fP (since C++23) + contains( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP (since C++23) + contains( const CharT* s ) const; + + Checks if the string contains the given substring. The substring may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void test_substring(const std::string& str, SubstrType subs) + { + constexpr char delim = std::is_scalar_v ? '\\'' : '\\"'; + std::cout << std::quoted(str) + << (str.contains(subs) ? " contains " + : " does not contain ") + << std::quoted(std::string{subs}, delim) << '\\n'; + } + + int main() + { + using namespace std::literals; + + auto helloWorld = "hello world"s; + + test_substring(helloWorld, "hello"sv); + test_substring(helloWorld, "goodbye"sv); + test_substring(helloWorld, 'w'); + test_substring(helloWorld, 'x'); + } + +.SH Output: + + "hello world" contains "hello" + "hello world" does not contain "goodbye" + "hello world" contains 'w' + "hello world" does not contain 'x' + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::copy.3 b/man/std::u32string::copy.3 deleted file mode 120000 index 18592fc3f..000000000 --- a/man/std::u32string::copy.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::copy.3 \ No newline at end of file diff --git a/man/std::u32string::copy.3 b/man/std::u32string::copy.3 new file mode 100644 index 000000000..5258bb301 --- /dev/null +++ b/man/std::u32string::copy.3 @@ -0,0 +1,81 @@ +.TH std::basic_string::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::copy \- std::basic_string::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos (constexpr since C++20) + = 0 ) const; + + Copies a substring [pos, pos + count) to character string pointed to by dest. If the + requested substring lasts past the end of the string, or if count == npos, the + copied substring is [pos, size()). + + The resulting character string is not null-terminated. + +.SH Parameters + + dest - pointer to the destination character string + count - length of the substring + pos - position of the first character to include + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string foo("WINE"); + + // brace-initialization initializes all characters to 0, + // providing a null-terminator + char bar[4]{}; + + // do not copy the last char, to guarantee null-termination + foo.copy(bar, sizeof bar - 1); + + std::cout << bar << '\\n'; // requires bar to be null-terminated + } + +.SH Output: + + WIN + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string_view)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::u32string::data.3 b/man/std::u32string::data.3 deleted file mode 120000 index e88dffdcc..000000000 --- a/man/std::u32string::data.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::data.3 \ No newline at end of file diff --git a/man/std::u32string::data.3 b/man/std::u32string::data.3 new file mode 100644 index 000000000..e081790d6 --- /dev/null +++ b/man/std::u32string::data.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::data \- std::basic_string::data + +.SH Synopsis + const CharT* data() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + CharT* data() noexcept; \fB(2)\fP \fI(since C++17)\fP + (constexpr since C++20) + + Returns a pointer to the underlying array serving as character storage. The pointer + is such that the range + + [data(), data() + size()) \fI(until C++11)\fP + [data(), data() + size()] \fI(since C++11)\fP + + is valid and the values in it correspond to the values stored in the string. + + The returned array is not required to be null-terminated. + \fI(until C++11)\fP + If empty() returns true, the pointer is a non-null pointer that should + not be dereferenced. + The returned array is null-terminated, that is, data() and c_str() + perform the same function. + \fI(since C++11)\fP + If empty() returns true, the pointer points to a single null + character. + + The pointer obtained from data() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string, excluding operator[](), at(), + front(), back(), begin(), end(), rbegin(), rend(). + 1) Modifying the character array accessed through the const overload of data has + undefined behavior. + 2) Modifying the past-the-end null terminator stored at data() + size() to any value + other than CharT() has undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character storage. + + data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + data() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string const s("Emplary"); + assert(s.size() == std::strlen(s.data())); + assert(std::equal(s.begin(), s.end(), s.data())); + assert(std::equal(s.data(), s.data() + s.size(), s.begin())); + assert('\\0' == *(s.data() + s.size())); + } + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + c_str returns a non-modifiable standard C character array version of the string + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::empty.3 b/man/std::u32string::empty.3 deleted file mode 120000 index 57ffefac4..000000000 --- a/man/std::u32string::empty.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::empty.3 \ No newline at end of file diff --git a/man/std::u32string::empty.3 b/man/std::u32string::empty.3 new file mode 100644 index 000000000..515c30654 --- /dev/null +++ b/man/std::u32string::empty.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::empty \- std::basic_string::empty + +.SH Synopsis + bool empty() const; (noexcept since C++11) + (constexpr since C++20) + + Checks if the string has no characters, i.e. whether begin() == end(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the string is empty, false otherwise + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::boolalpha(std::cout); + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = "Exemplar"; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = ""; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + } + +.SH Output: + + s.empty():true s:'' + s.empty():false s:'Exemplar' + s.empty():true s:'' + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + empty checks whether the view is empty + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::end,.3 b/man/std::u32string::end,.3 new file mode 100644 index 000000000..a29f4fa07 --- /dev/null +++ b/man/std::u32string::end,.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::end, \- std::basic_string::end, + +.SH Synopsis + + iterator end(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the character following the last character of the string. + This character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemparl"); + std::next_permutation(s.begin(), s.end()); + + std::string c; + std::copy(s.cbegin(), s.cend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "Exemplar" + } + +.SH Output: + + Exemplar + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::end,std::basic_string::cend.3 b/man/std::u32string::end,std::basic_string::cend.3 deleted file mode 120000 index 8e6f5e8ed..000000000 --- a/man/std::u32string::end,std::basic_string::cend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::end,std::basic_string::cend.3 \ No newline at end of file diff --git a/man/std::u32string::ends_with.3 b/man/std::u32string::ends_with.3 new file mode 100644 index 000000000..daa271fc6 --- /dev/null +++ b/man/std::u32string::ends_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::ends_with \- std::basic_string::ends_with + +.SH Synopsis + constexpr bool + ends_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + ends_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + ends_with( const CharT* s ) const; + + Checks if the string ends with the given suffix. The suffix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).ends_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.ends_with("C++20!"sv) // (1) + && !str.ends_with("c++20!"sv) // (1) + && str.ends_with("C++20!"s) // (1) implicit conversion string to string_view + && !str.ends_with("c++20!"s) // (1) implicit conversion string to string_view + && str.ends_with('!') // (2) + && !str.ends_with('?') // (2) + && str.ends_with("C++20!") // (3) + && !str.ends_with("c++20!") // (3) + ); + } + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::u32string::erase.3 b/man/std::u32string::erase.3 deleted file mode 120000 index 533c91687..000000000 --- a/man/std::u32string::erase.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::erase.3 \ No newline at end of file diff --git a/man/std::u32string::erase.3 b/man/std::u32string::erase.3 new file mode 100644 index 000000000..caa61fc84 --- /dev/null +++ b/man/std::u32string::erase.3 @@ -0,0 +1,109 @@ +.TH std::basic_string::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::erase \- std::basic_string::erase + +.SH Synopsis + basic_string& erase( (constexpr since + size_type index = 0, \fB(1)\fP C++20) + size_type count = npos ); + iterator erase( iterator \fI(until C++11)\fP + position ); + iterator erase( \fI(since C++11)\fP + const_iterator position ); (constexpr since + \fB(2)\fP C++20) + iterator erase( iterator \fI(until C++11)\fP + first, iterator last ); + iterator erase( \fB(3)\fP \fI(since C++11)\fP + const_iterator first, (constexpr since + const_iterator last ); C++20) + + Removes specified characters from the string. + + 1) Removes std::min(count, size() - index) characters starting at index. + 2) Removes the character at position. + If position is not a dereferenceable iterator on *this, the behavior is undefined. + 3) Removes the characters in the range [first, last). + If first or last is not a valid iterator on *this, or [first, last) is not a valid + range, the behavior is undefined. + +.SH Parameters + + index - first character to remove + count - number of characters to remove + position - iterator to the character to remove + first, last - range of the characters to remove + +.SH Return value + + 1) *this + 2) Iterator pointing to the character immediately following the character erased, or + end() if no such character exists. + 3) Iterator pointing to the character last pointed to before the erase, or end() if + no such character exists. + +.SH Exceptions + + 1) std::out_of_range if index > size(). + 2,3) Throws nothing. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s = "This Is An Example"; + std::cout << "1) " << s << '\\n'; + + s.erase(7, 3); // erases " An" using overload (1) + std::cout << "2) " << s << '\\n'; + + s.erase(std::find(s.begin(), s.end(), ' ')); // erases first ' '; overload (2) + std::cout << "3) " << s << '\\n'; + + s.erase(s.find(' ')); // trims from ' ' to the end of the string; overload (1) + std::cout << "4) " << s << '\\n'; + + auto it = std::next(s.begin(), s.find('s')); // obtains iterator to the first 's' + s.erase(it, std::next(it, 2)); // erases "sI"; overload (3) + std::cout << "5) " << s << '\\n'; + } + +.SH Output: + + 1) This Is An Example + 2) This Is Example + 3) ThisIs Example + 4) ThisIs + 5) This + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(3)\fP did not erase the character returns an iterator + LWG 27 C++98 last pointed to, but it returned pointing to that + the iterator pointing to the character character + immediately following that character + overload \fB(2)\fP explicitly required position + LWG 428 C++98 to be valid, but removed the + SequenceContainer requires it to be explicit requirement + dereferenceable (stricter) + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + +.SH See also + + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::u32string::find.3 b/man/std::u32string::find.3 deleted file mode 120000 index 6675f6f1b..000000000 --- a/man/std::u32string::find.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find.3 \ No newline at end of file diff --git a/man/std::u32string::find.3 b/man/std::u32string::find.3 new file mode 100644 index 000000000..6ae3d060f --- /dev/null +++ b/man/std::u32string::find.3 @@ -0,0 +1,171 @@ +.TH std::basic_string::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find \- std::basic_string::find + +.SH Synopsis + size_type find( const basic_string& str, size_type pos = \fB(1)\fP (noexcept since C++11) + 0 ) const; (constexpr since C++20) + size_type find( const CharT* s, size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find( const CharT* s, size_type pos = 0 ) \fB(3)\fP (constexpr since C++20) + const; + size_type find( CharT ch, size_type pos = 0 ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type find( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first substring equal to the given character sequence. Search begins at + pos, i.e. the found substring must not begin in a position preceding pos. + + 1) Finds the first substring equal to str. + 2) Finds the first substring equal to the range [s, s + count). This range may + contain null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character ch (treated as a single-character substring by the + formal rules below). + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first substring equal to sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + Formally, a substring str is said to be found at position xpos if all of the + following are true: + + * xpos >= pos + * xpos + str.size() <= size() + * for all positions n in str, Traits::eq(at(xpos + n), str.at(n)). + + In particular, this implies that + + * a substring can be found only if pos <= size() - str.size() + * an empty substring is found at pos if and only if pos <= size() + * for a non-empty substring, if pos >= size(), the function always returns npos. + +.SH Parameters + + str - string to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(int id, std::string::size_type n, std::string const& s) + { + std::cout << id << ") "; + if (std::string::npos == n) + std::cout << "not found! n == npos\\n"; + else + std::cout << "found @ n = " << n << ", substr(" << n << ") = " + << std::quoted(s.substr(n)) << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; /* + ^ ^ ^ + 1 2 3 */ + + // search from beginning of string + n = s.find("is"); + print(1, n, s); + + // search from position 5 + n = s.find("is", 5); + print(2, n, s); + + // find a single character + n = s.find('a'); + print(3, n, s); + + // find a single character + n = s.find('q'); + print(4, n, s); + } + +.SH Output: + + 1) found @ n = 2, substr\fB(2)\fP = "is is a string" + 2) found @ n = 5, substr\fB(5)\fP = "is a string" + 3) found @ n = 8, substr\fB(8)\fP = "a string" + 4) not found! n == npos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + strstr finds the first occurrence of a substring of characters + \fI(function)\fP + finds the first occurrence of a wide string within another wide + wcsstr string + \fI(function)\fP + strchr finds the first occurrence of a character + \fI(function)\fP + wcschr finds the first occurrence of a wide character in a wide string + \fI(function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find characters in the view + find \fI(public member function of std::basic_string_view)\fP + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::find_first_not_of.3 b/man/std::u32string::find_first_not_of.3 deleted file mode 120000 index 7cd66aee2..000000000 --- a/man/std::u32string::find_first_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_not_of.3 \ No newline at end of file diff --git a/man/std::u32string::find_first_not_of.3 b/man/std::u32string::find_first_not_of.3 new file mode 100644 index 000000000..795a2e7ce --- /dev/null +++ b/man/std::u32string::find_first_not_of.3 @@ -0,0 +1,141 @@ +.TH std::basic_string::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_not_of \- std::basic_string::find_first_not_of + +.SH Synopsis + size_type find_first_not_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_first_not_of( const CharT* s, \fB(3)\fP (constexpr since C++20) + size_type pos = 0 ) const; + size_type find_first_not_of( CharT ch, size_type pos = 0 \fB(4)\fP (noexcept since C++11) + ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const + noexcept(/* see below */); + + Finds the first character equal to none of the characters in the given character + sequence. The search considers only the range [pos, size()). If all characters in + the range can be found in the given character sequence, npos will be returned. + + 1) Finds the first character equal to none of characters in str. + 2) Finds the first character equal to none of characters in range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position for the search to start from + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or std::string::npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Permit uppercase letters, lowercase letters and numbers in macro names + const char* pattern = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "abcdefghijklmnopqrstuvwxyz" + "0123456789"; + + std::string data = "1) %FIX, 2) %HACK, and 3) %TODO"; + const std::string replacement = "%DONE%"; + + std::cout << "Before: " << data << '\\n'; + + for (std::string::size_type first{}, last{}; + (first = data.find('%', first)) != std::string::npos; + first += replacement.size()) + { + last = data.find_first_not_of(pattern, first + 1); + if (last == std::string::npos) + last = data.length(); + + // Now first at '%' and last is one past end of the found substring + data.replace(first, last - first, replacement); + } + + std::cout << "After: " << data << '\\n'; + } + +.SH Output: + + Before: 1) %FIX, 2) %HACK, and 3) %TODO + After: 1) %DONE%, 2) %DONE%, and 3) %DONE% + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::find_first_of.3 b/man/std::u32string::find_first_of.3 deleted file mode 120000 index 497a89646..000000000 --- a/man/std::u32string::find_first_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_of.3 \ No newline at end of file diff --git a/man/std::u32string::find_first_of.3 b/man/std::u32string::find_first_of.3 new file mode 100644 index 000000000..e6263f90c --- /dev/null +++ b/man/std::u32string::find_first_of.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_of \- std::basic_string::find_first_of + +.SH Synopsis + size_type find_first_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_of( const CharT* s, + size_type pos, size_type count \fB(2)\fP (constexpr since C++20) + ) const; + size_type find_first_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + 0 ) const; + size_type find_first_of( CharT ch, size_type pos = 0 ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first character equal to one of the characters in the given character + sequence. The search considers only the range [pos, size()). If none of the + characters in the given character sequence is present in the range, npos will be + returned. + + 1) Finds the first character equal to one of the characters in str. + 2) Finds the first character equal to one of the characters in the range [s, s + + count). This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to one of the characters in character string + pointed to by s. The length of the string is determined by the first null character + using Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to one of the characters in + sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to begin searching + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Traits::eq() is used to perform the comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + std::string::size_type sz; + + // (1) + sz = "alignas"s.find_first_of("klmn"s); + // └────────────────────────┘ + assert(sz == 1); + + sz = "alignof"s.find_first_of("wxyz"s); + // no match + assert(sz == std::string::npos); + + // (2) + sz = "consteval"s.find_first_of("xyzabc", 0, 3); + // no match (× are not targets) ××× + assert(sz == std::string::npos); + + sz = "consteval"s.find_first_of("xyzabc", 0, 6); + // └───────────────────────────────┘ + assert(sz == 0); + + // (3) + sz = "decltype"s.find_first_of("xyzabc"); + // └────────────────────────────┘ + assert(sz == 2); + + // (4) + sz = "co_await"s.find_first_of('a'); + // └──────────────────────┘ + assert(sz == 3); + + // (5) + sz = "constinit"s.find_first_of("int"sv); + // └─────────────────────────┘ + assert(sz == 2); + + std::cout << "All tests passed.\\n"; + } + +.SH Output: + + All tests passed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI(public member function of std::basic_string_view)\fP + + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::find_last_not_of.3 b/man/std::u32string::find_last_not_of.3 deleted file mode 120000 index 85f8838a9..000000000 --- a/man/std::u32string::find_last_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_not_of.3 \ No newline at end of file diff --git a/man/std::u32string::find_last_not_of.3 b/man/std::u32string::find_last_not_of.3 new file mode 100644 index 000000000..b325c1428 --- /dev/null +++ b/man/std::u32string::find_last_not_of.3 @@ -0,0 +1,160 @@ +.TH std::basic_string::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_not_of \- std::basic_string::find_last_not_of + +.SH Synopsis + size_type find_last_not_of( const basic_string& str, (noexcept since C++11) + size_type pos = npos ) \fB(1)\fP (constexpr since C++20) + const; + size_type find_last_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_last_not_of( const CharT* s, size_type \fB(3)\fP (constexpr since C++20) + pos = npos ) const; + size_type find_last_not_of( CharT ch, size_type pos = \fB(4)\fP (noexcept since C++11) + npos ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to none of the characters in the given character + sequence. The search considers only the range [0, pos]. If all characters in the + range can be found in the given character sequence, npos will be returned. + + 1) Finds the last character equal to none of characters in str. + 2) Finds the last character equal to none of characters in the range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to end search + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v< + const T&, std::basic_string_view>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + void show_pos(const std::string& str, std::string::size_type found) + { + if (found != std::string::npos) + std::cout << '[' << found << "] = \\'" << str[found] << "\\'\\n"; + else + std::cout << "not found\\n"; + } + + int main() + { + std::string str{"abc_123"}; + char const* skip_set{"0123456789"}; + std::string::size_type str_last_pos{std::string::npos}; + + show_pos(str, str.find_last_not_of(skip_set)); // [3] = '_' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of(skip_set, str_last_pos)); // [2] = 'c' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of('c', str_last_pos)); // [1] = 'b' + + const char arr[]{'3', '4', '5'}; + show_pos(str, str.find_last_not_of(arr)); // [5] = '2' + + str_last_pos = 2; + std::string::size_type skip_set_size{4}; + show_pos(str, str.find_last_not_of(skip_set, + str_last_pos, + skip_set_size)); // [2] = 'c' + + show_pos(str, str.find_last_not_of("abc")); // [6] = '3' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of("abc", str_last_pos)); // not found + } + +.SH Output: + + [3] = '_' + [2] = 'c' + [1] = 'b' + [5] = '2' + [2] = 'c' + [6] = '3' + not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::find_last_of.3 b/man/std::u32string::find_last_of.3 deleted file mode 120000 index 18ea1b60d..000000000 --- a/man/std::u32string::find_last_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_of.3 \ No newline at end of file diff --git a/man/std::u32string::find_last_of.3 b/man/std::u32string::find_last_of.3 new file mode 100644 index 000000000..e3ff59859 --- /dev/null +++ b/man/std::u32string::find_last_of.3 @@ -0,0 +1,126 @@ +.TH std::basic_string::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_of \- std::basic_string::find_last_of + +.SH Synopsis + size_type find_last_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = npos ) const; (constexpr since C++20) + size_type find_last_of( const CharT* s, + size_type pos, size_type count ) \fB(2)\fP (constexpr since C++20) + const; + size_type find_last_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + npos ) const; + size_type find_last_of( CharT ch, size_type pos = npos ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to one of characters in the given character sequence. + The exact search algorithm is not specified. The search considers only the range + [0, pos]. If none of the characters in the given character sequence is present in + the range, npos will be returned. + + 1) Finds the last character equal to one of characters in str. + 2) Finds the last character equal to one of characters in range [s, s + count). This + range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to one of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to one of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which the search is to finish + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string path = "/root/config"; + auto const pos = path.find_last_of('/'); + const auto leaf = path.substr(pos + 1); + + std::cout << leaf << '\\n'; + } + +.SH Output: + + config + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::front.3 b/man/std::u32string::front.3 deleted file mode 120000 index 6e46155d2..000000000 --- a/man/std::u32string::front.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::front.3 \ No newline at end of file diff --git a/man/std::u32string::front.3 b/man/std::u32string::front.3 new file mode 100644 index 000000000..978ec6830 --- /dev/null +++ b/man/std::u32string::front.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::front \- std::basic_string::front + +.SH Synopsis + CharT& front(); \fB(1)\fP (constexpr since C++20) + const CharT& front() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the first character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, front() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& f1 = s.front(); + f1 = 'e'; + std::cout << s << '\\n'; // "exemplary" + + std::string const c("Exemplary"); + char const& f2 = c.front(); + std::cout << &f2 << '\\n'; // "Exemplary" + } + +.SH Output: + + exemplary + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function front() + +.SH See also + + back accesses the last character + (DR*) \fI(public member function)\fP + front accesses the first character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::get_allocator.3 b/man/std::u32string::get_allocator.3 deleted file mode 120000 index a59c7178f..000000000 --- a/man/std::u32string::get_allocator.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::get_allocator.3 \ No newline at end of file diff --git a/man/std::u32string::get_allocator.3 b/man/std::u32string::get_allocator.3 new file mode 100644 index 000000000..52b590226 --- /dev/null +++ b/man/std::u32string::get_allocator.3 @@ -0,0 +1,30 @@ +.TH std::basic_string::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::get_allocator \- std::basic_string::get_allocator + +.SH Synopsis + allocator_type get_allocator() const; (noexcept since C++20) + (constexpr since C++20) + + Returns the allocator associated with the string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated allocator. + +.SH Complexity + + Constant. + +.SH See also + + allocator the default allocator + \fI(class template)\fP + allocator_traits provides information about allocator types + \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::u32string::insert.3 b/man/std::u32string::insert.3 deleted file mode 120000 index 06d0b9ef6..000000000 --- a/man/std::u32string::insert.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::insert.3 \ No newline at end of file diff --git a/man/std::u32string::insert.3 b/man/std::u32string::insert.3 new file mode 100644 index 000000000..28be988e6 --- /dev/null +++ b/man/std::u32string::insert.3 @@ -0,0 +1,228 @@ +.TH std::basic_string::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert \- std::basic_string::insert + +.SH Synopsis + basic_string& insert( (constexpr + size_type index, size_type \fB(1)\fP since + count, CharT ch ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(2)\fP since + CharT* s ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(3)\fP since + CharT* s, size_type count ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(4)\fP since + basic_string& str ); C++20) + basic_string& insert( + size_type index, const + basic_string& str, (until + C++14) + size_type s_index, size_type + count ); + basic_string& insert( (since + size_type index, const C++14) + basic_string& str, (constexpr + since + size_type s_index, size_type C++20) + count = npos ); + iterator insert( iterator (until + pos, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, CharT ch (constexpr + ); since + C++20) + void insert( iterator pos, (until + size_type count, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, (constexpr + size_type count, CharT ch ); since + C++20) + template< class InputIt > + void insert( iterator pos, \fB(5)\fP (until + InputIt first, InputIt last C++11) + ); + template< class InputIt > (since + iterator insert( C++11) + const_iterator pos, InputIt (constexpr + first, InputIt last ); \fB(6)\fP since + C++20) + iterator insert( (since + const_iterator pos, \fB(7)\fP C++11) + std::initializer_list \fB(9)\fP (constexpr + ilist ); since + C++20) + template< class \fB(8)\fP (since + StringViewLike > C++17) + basic_string& insert( \fB(10)\fP (constexpr + size_type index, const since + StringViewLike& t ); C++20) + template< class + StringViewLike > + (since + basic_string& insert( C++17) + size_type index, const \fB(11)\fP (constexpr + StringViewLike& t, since + C++20) + + size_type t_index, size_type + count = npos ); + + Inserts characters into the string. + + 1) Inserts count copies of character ch at the position index. + 2) Inserts null-terminated character string pointed to by s at the position index. + The length of the string is determined by the first null character using + Traits::length(s). + 3) Inserts the characters in the range [s, s + count) at the position index. The + range can contain null characters. + 4) Inserts string str at the position index. + 5) Inserts a string, obtained by str.substr(s_index, count) at the position index. + 6) Inserts character ch before the character pointed by pos. + 7) Inserts count copies of character ch before the element (if any) pointed by pos. + 8) Inserts characters from the range [first, last) before the element (if any) + pointed by pos, as if by insert(pos - begin(), basic_string(first, last, + get_allocator())). + + This overload does not participate in overload resolution if InputIt \fI(since C++11)\fP + does not satisfy LegacyInputIterator. + + 9) Inserts elements from initializer list ilist before the element (if any) pointed + by pos. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts the elements from sv before the element (if any) + pointed by index, as if by insert(index, sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 11) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts, before the element (if any) pointed by index, the + characters from the subview [t_index, t_index + count) of sv. + * If the requested subview lasts past the end of sv, or if count == npos, the + resulting subview is [t_index, sv.size()). + * If t_index > sv.size(), or if index > size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + index - position at which the content will be inserted + pos - iterator before which the characters will be inserted + ch - character to insert + count - number of characters to insert + s - pointer to the character string to insert + str - string to insert + first, last - range defining characters to insert + s_index - position of the first character in str to insert + ilist - std::initializer_list to insert the characters from + t - object (convertible to std::basic_string_view) to insert the + characters from + t_index - position of the first character in t to insert +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1-5) *this + 6-9) An iterator which refers to the copy of the first inserted character or pos if + no characters were inserted (count == 0 or first == last or ilist.size() == 0) + 10,11) *this + +.SH Exceptions + + 1-4,10) Throws std::out_of_range if index > size(). + 5) Throws std::out_of_range if index > size() or if s_index > str.size(). + 11) Throws std::out_of_range if index > size() or if t_index > sv.size(). + + In all cases, throws std::length_error if size() + ins_count > max_size() where + ins_count is the number of characters that will be inserted. + + In all cases, if std::allocator_traits::allocate throws an \fI(since C++20)\fP + exception, it is rethrown. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::string_literals; + + int main() + { + std::string s = "xmplr"; + + // insert(size_type index, size_type count, char ch) + s.insert(0, 1, 'E'); + assert("Exmplr" == s); + + // insert(size_type index, const char* s) + s.insert(2, "e"); + assert("Exemplr" == s); + + // insert(size_type index, string const& str) + s.insert(6, "a"s); + assert("Exemplar" == s); + + // insert(size_type index, string const& str, + // size_type s_index, size_type count) + s.insert(8, " is an example string."s, 0, 14); + assert("Exemplar is an example" == s); + + // insert(const_iterator pos, char ch) + s.insert(s.cbegin() + s.find_first_of('n') + 1, ':'); + assert("Exemplar is an: example" == s); + + // insert(const_iterator pos, size_type count, char ch) + s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '='); + assert("Exemplar is an:== example" == s); + + // insert(const_iterator pos, InputIt first, InputIt last) + { + std::string seq = " string"; + s.insert(s.begin() + s.find_last_of('e') + 1, + std::begin(seq), std::end(seq)); + assert("Exemplar is an:== example string" == s); + } + + // insert(const_iterator pos, std::initializer_list) + s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'}); + assert("Exemplar is an:== example string." == s); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 7 C++98 overload (8) referred to a non-existing refers to overload (4) + overload correctly + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2946 C++17 overload (10) caused ambiguity in some avoided by making it a + cases template + +.SH See also + + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP diff --git a/man/std::u32string::insert_range.3 b/man/std::u32string::insert_range.3 new file mode 100644 index 000000000..172031ebb --- /dev/null +++ b/man/std::u32string::insert_range.3 @@ -0,0 +1,84 @@ +.TH std::basic_string::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert_range \- std::basic_string::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr iterator insert_range( const_iterator pos, R&& rg ); + + Inserts characters from the range rg before the element (if any) pointed by pos. + + Equivalent to + + return insert(pos - begin(), + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + pos - iterator before which the characters will be inserted + rg - a container compatible range + +.SH Return value + + An iterator which refers to the first inserted character, or pos if no characters + were inserted because rg was empty. + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If std::allocator_traits::allocate throws an exception, it is rethrown. + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto source = {'l', 'i', 'b', '_'}; + std::string target{"__cpp_containers_ranges"}; + // ^insertion will occur + // before this position + + const auto pos = target.find("container"); + assert(pos != target.npos); + auto iter = std::next(target.begin(), pos); + + #ifdef __cpp_lib_containers_ranges + target.insert_range(iter, source); + #else + target.insert(iter, source.begin(), source.end()); + #endif + + assert(target == "__cpp_lib_containers_ranges"); + // ^^^^ + } + +.SH See also + + insert inserts characters + \fI(public member function)\fP diff --git a/man/std::u32string::max_size.3 b/man/std::u32string::max_size.3 deleted file mode 120000 index 450f8a80c..000000000 --- a/man/std::u32string::max_size.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::max_size.3 \ No newline at end of file diff --git a/man/std::u32string::max_size.3 b/man/std::u32string::max_size.3 new file mode 100644 index 000000000..806a1dd4a --- /dev/null +++ b/man/std::u32string::max_size.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::max_size \- std::basic_string::max_size + +.SH Synopsis + size_type max_size() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the maximum number of elements the string is able to hold due to system or + library implementation limitations, i.e. std::distance(begin(), end()) for the + largest string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + #include + + template + void print_basic_string_max_size() + { + std::basic_string s; + auto max_size = s.max_size(); + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "basic_string<" << boost::core::demangle(typeid(T).name()) + << ">:\\n\\t" << max_size << " = "; + std::cout << std::setprecision(3) << (double) max_size << " = "; + std::cout.imbue(std::locale("C")); + std::cout << std::hex << std::setfill('0') << "0x" + << std::setw(sizeof(typename decltype(s)::size_type) << 1) + << max_size << '\\n' << std::dec; + }; + + int main() + { + std::cout << "Pointer size: " << CHAR_BIT * sizeof(void*) << " bits\\n" + "Maximum sizes:\\n"; + + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + + using CharT = std::array; + print_basic_string_max_size(); + } + +.SH Possible output: + + Pointer size: 64 bits + Maximum sizes: + basic_string: + 9,223,372,036,854,775,807 = 9.22e+18 = 0x7fffffffffffffff + basic_string: + 4,611,686,018,427,387,903 = 4.61e+18 = 0x3fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 1,152,921,504,606,846,975 = 1.15e+18 = 0x0fffffffffffffff + basic_string>: + 13,848,906,962,244,407 = 1.38e+16 = 0x00313381ec031337 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::npos.3 b/man/std::u32string::npos.3 deleted file mode 120000 index 4582d0216..000000000 --- a/man/std::u32string::npos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::npos.3 \ No newline at end of file diff --git a/man/std::u32string::npos.3 b/man/std::u32string::npos.3 new file mode 100644 index 000000000..cb8bcc779 --- /dev/null +++ b/man/std::u32string::npos.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::npos \- std::basic_string::npos + +.SH Synopsis + static const size_type npos = -1; + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of string indicator by the functions that expect a string index or as the error + indicator by the functions that return a string index. + +.SH Note + + Although the definition uses -1, size_type is an unsigned integer type, and the + value of npos is the largest positive value it can hold, due to signed-to-unsigned + implicit conversion. This is a portable way to specify the largest value of any + unsigned type. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // string search functions return npos if nothing is found + std::string s = "test"; + if (s.find('a') == s.npos) + std::cout << "no 'a' in 'test'\\n"; + + // functions that take string subsets as arguments + // use npos as the "all the way to the end" indicator + std::string s2(s, 2, std::string::npos); + std::cout << s2 << '\\n'; + + std::bitset<5> b("aaabb", std::string::npos, 'a', 'b'); + std::cout << b << '\\n'; + } + +.SH Output: + + no 'a' in 'test' + st + 00011 + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant of std::basic_string_view)\fP + diff --git a/man/std::u32string::operator+=.3 b/man/std::u32string::operator+=.3 deleted file mode 120000 index 54ff82159..000000000 --- a/man/std::u32string::operator+=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator+=.3 \ No newline at end of file diff --git a/man/std::u32string::operator+=.3 b/man/std::u32string::operator+=.3 new file mode 100644 index 000000000..6f5ea9049 --- /dev/null +++ b/man/std::u32string::operator+=.3 @@ -0,0 +1,120 @@ +.TH std::basic_string::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator+= \- std::basic_string::operator+= + +.SH Synopsis + basic_string& operator+=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator+=( CharT ch ); \fB(2)\fP (constexpr since C++20) + basic_string& operator+=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator+=( std::initializer_list \fB(4)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template< class StringViewLike > \fB(5)\fP \fI(since C++17)\fP + basic_string& operator+=( const StringViewLike& t ); (constexpr since C++20) + + Appends additional characters to the string. + + 1) Appends string str. + 2) Appends character ch. + 3) Appends the null-terminated character string pointed to by s. + 4) Appends characters in the initializer list ilist. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends characters in the string view sv as if by append(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string to append + ch - character value to append + s - pointer to a null-terminated character string to append + ilist - std::initializer_list with the characters to append + t - object (convertible to std::basic_string_view) with the characters to append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Overload \fB(2)\fP can accept any types that are implicitly convertible to CharT. For + std::string, where CharT is char, the set of acceptable types includes all + arithmetic types. This may have unintended effects. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str; + + // reserve sufficient storage space to avoid memory reallocation + str.reserve(50); + + std::cout << std::quoted(str) << '\\n'; // empty string + + str += "This"; + std::cout << std::quoted(str) << '\\n'; + + str += std::string(" is "); + std::cout << std::quoted(str) << '\\n'; + + str += 'a'; + std::cout << std::quoted(str) << '\\n'; + + str += {' ', 's', 't', 'r', 'i', 'n', 'g', '.'}; + std::cout << std::quoted(str) << '\\n'; + + str += 69.96; // Equivalent to str += static_cast(69.96); + // 'E' (ASCII code 69) is appended by overload (2), + // which might not be the intent. + + // To add a numeric value, consider std::to_string(): + str += std::to_string(1729); + + std::cout << std::quoted(str) << '\\n'; + } + +.SH Output: + + "" + "This" + "This is " + "This is a" + "This is a string." + "This is a string.E1729" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::u32string::operator=.3 b/man/std::u32string::operator=.3 deleted file mode 120000 index 5505d7126..000000000 --- a/man/std::u32string::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator=.3 \ No newline at end of file diff --git a/man/std::u32string::operator=.3 b/man/std::u32string::operator=.3 new file mode 100644 index 000000000..70b37150d --- /dev/null +++ b/man/std::u32string::operator=.3 @@ -0,0 +1,153 @@ +.TH std::basic_string::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator= \- std::basic_string::operator= + +.SH Synopsis + basic_string& operator=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator=( basic_string&& str ) \fB(2)\fP \fI(since C++11)\fP + noexcept(/* see below */); (constexpr since C++20) + basic_string& operator=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator=( CharT ch ); \fB(4)\fP (constexpr since C++20) + basic_string& operator=( std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template \fB(6)\fP \fI(since C++17)\fP + basic_string& operator=( const StringViewLike& t ); (constexpr since C++20) + basic_string& operator=( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + Replaces the contents of the string. + + 1) Replaces the contents with a copy of str. If *this and str are the same object, + this function has no effect. + 2) Replaces the contents with those of str using SequenceContainer's move assignment + semantics. + Unlike other sequence container move assignments, references, pointers, and + iterators to elements of str may be invalidated. + 3) Replaces the contents with those of null-terminated character string pointed to + by s as if by assign(s, Traits::length(s)). + 4) Replaces the contents with character ch as if by assign(std::addressof(ch), 1). + 5) Replaces the contents with those of the initializer list ilist as if by + assign(ilist.begin(), ilist.size()). + 6) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of the sv as if by + assign(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 7) std::basic_string cannot be assigned from nullptr. + +.SH Parameters + + ch - value to initialize characters of the string with + str - string to be used as source to initialize the string with + s - pointer to a null-terminated character string to use as source to initialize + the string with + ilist - std::initializer_list to initialize the string with + t - object convertible to std::basic_string_view to initialize the string with + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in size of str. + 2) Linear in the size of *this (formally, each CharT has to be destroyed). If + allocators do not compare equal and do not propagate, then also linear in the size + of str (copy must be made). + 3) Linear in size of s. + 4) Constant. + 5) Linear in size of ilist. + 6) Linear in size of t. + +.SH Exceptions + + 2) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str1; + std::string str2{"alpha"}; + + // (1) operator=(const basic_string&); + str1 = str2; + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "alpha" + + // (2) operator=(basic_string&&); + str1 = std::move(str2); + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "" or "alpha" (unspecified) + + // (3) operator=(const CharT*); + str1 = "beta"; + std::cout << std::quoted(str1) << '\\n'; // "beta" + + // (4) operator=(CharT); + str1 = '!'; + std::cout << std::quoted(str1) << '\\n'; // "!" + + // (5) operator=(std::initializer_list); + str1 = {'g', 'a', 'm', 'm', 'a'}; + std::cout << std::quoted(str1) << '\\n'; // "gamma" + + // (6) operator=(const T&); + str1 = 35U; // equivalent to str1 = static_cast(35U); + std::cout << std::quoted(str1) << '\\n'; // "#" (ASCII = 35) + } + +.SH Possible output: + + "alpha" "alpha" + "alpha" "" + "beta" + "!" + "gamma" + "#" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + the move assignment operator did not + LWG 2063 C++11 follow follows + SequenceContainer's semantic requirement + LWG 2946 C++17 overload \fB(6)\fP caused ambiguity in some avoided by making it a + cases template + +.SH See also + + constructor constructs a basic_string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assigns a view + operator= \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::operator[].3 b/man/std::u32string::operator[].3 deleted file mode 120000 index 05791619e..000000000 --- a/man/std::u32string::operator[].3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator[].3 \ No newline at end of file diff --git a/man/std::u32string::operator[].3 b/man/std::u32string::operator[].3 new file mode 100644 index 000000000..8fa941e51 --- /dev/null +++ b/man/std::u32string::operator[].3 @@ -0,0 +1,83 @@ +.TH std::basic_string::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator[] \- std::basic_string::operator[] + +.SH Synopsis + CharT& operator[]( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& operator[]( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos if pos < size(), or a + reference to CharT() if pos == size(). No bounds checking is performed. + + If pos > size(), the behavior is undefined. + + For overload \fB(1)\fP, if pos == size(), the behavior is undefined + if the object referred by the returned reference is modified to any value other than + CharT() + \fI(since C++11)\fP. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + *(begin() + pos) if pos < size(), or a reference to CharT() if pos == size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string e("Exemplar"); + for (unsigned i = e.length() - 1; i != 0; i /= 2) + std::cout << e[i]; + std::cout << '\\n'; + + const char* c = &e[0]; + std::cout << c << '\\n'; // print as a C string + + // Change the last character of s into a 'y' + std::string s("Exemplar "); + s[s.size() - 1] = 'y'; // equivalent to s.back() = 'y'; + std::cout << s << '\\n'; + } + +.SH Output: + + rmx + Exemplar + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 259 C++98 non-const overload could return const lvalue changed to return + data()[pos], which was ill-formed *(begin() + pos) + if pos == size(), the behavior of modifying + LWG 2475 C++11 the well-defined if + object referred by the returned reference modified to CharT() + was undefined + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::operatorbasic_string_view.3 b/man/std::u32string::operatorbasic_string_view.3 new file mode 100644 index 000000000..7860d59f8 --- /dev/null +++ b/man/std::u32string::operatorbasic_string_view.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::operatorbasic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operatorbasic_string_view \- std::basic_string::operatorbasic_string_view + +.SH Synopsis + operator std::basic_string_view() const \fI(since C++17)\fP + noexcept; (constexpr since C++20) + + Returns a std::basic_string_view, constructed as if by std::basic_string_view(data(), size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A string view representing the entire contents of the string. + +.SH Notes + + It is the programmer's responsibility to ensure that the resulting string view does + not outlive the string. + + std::string get_string(); + int f(std::string_view sv); + + int x = f(get_string()); // OK + std::string_view sv = get_string(); // Bad: holds a dangling pointer + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_wstring_size(std::wstring_view wcstr_v) + { + std::cout << wcstr_v.size() << " code points\\n"; + } + + int main() + { + std::string cppstr = "ラーメン"; // narrow string + std::wstring wcstr = L"ラーメン"; // wide string + + // Implicit conversion from string to string_view + // via std::string::operator string_view: + std::string_view cppstr_v = cppstr; + + std::cout << cppstr_v << '\\n' + << cppstr_v.size() << " code units\\n"; + + // Implicit conversion from wstring to wstring_view + // via std::wstring::operator wstring_view: + show_wstring_size(wcstr); + } + +.SH Output: + + ラーメン + 12 code units + 4 code points + +.SH See also + + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::u32string::pop_back.3 b/man/std::u32string::pop_back.3 deleted file mode 120000 index 92b01df6a..000000000 --- a/man/std::u32string::pop_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::pop_back.3 \ No newline at end of file diff --git a/man/std::u32string::pop_back.3 b/man/std::u32string::pop_back.3 new file mode 100644 index 000000000..1ef904042 --- /dev/null +++ b/man/std::u32string::pop_back.3 @@ -0,0 +1,75 @@ +.TH std::basic_string::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::pop_back \- std::basic_string::pop_back + +.SH Synopsis + void pop_back(); (constexpr since C++20) + + Removes the last character from the string. + + Equivalent to erase(end() - 1). The behavior is undefined if the string is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + In libstdc++, pop_back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string str("Short string!"); + std::cout << "before=" << std::quoted(str) << '\\n'; + assert(str.size() == 13); + + str.pop_back(); + std::cout << " after=" << std::quoted(str) << '\\n'; + assert(str.size() == 12); + + str.clear(); + // str.pop_back(); // undefined behavior + } + +.SH Output: + + before="Short string!" + after="Short string" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function pop_back() + +.SH See also + + push_back appends a character to the end + \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP diff --git a/man/std::u32string::push_back.3 b/man/std::u32string::push_back.3 deleted file mode 120000 index fde2976b5..000000000 --- a/man/std::u32string::push_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::push_back.3 \ No newline at end of file diff --git a/man/std::u32string::push_back.3 b/man/std::u32string::push_back.3 new file mode 100644 index 000000000..122b1e8fe --- /dev/null +++ b/man/std::u32string::push_back.3 @@ -0,0 +1,68 @@ +.TH std::basic_string::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::push_back \- std::basic_string::push_back + +.SH Synopsis + void push_back( CharT ch ); (constexpr since C++20) + + Appends the given character ch to the end of the string. + +.SH Parameters + + ch - the character to append + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Amortized constant. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str{"Short string"}; + std::cout << "1) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + + str.push_back('!'); + std::cout << "2) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + } + +.SH Output: + + 1) "Short string", size: 12 + 2) "Short string!", size: 13 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + \fB(1)\fP the description was missing in + LWG 7 C++98 the C++ standard \fB(1)\fP description added + \fB(2)\fP the parameter type was const (2) changed to CharT + CharT + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + pop_back removes the last character + (DR*) \fI(public member function)\fP diff --git a/man/std::u32string::rbegin,.3 b/man/std::u32string::rbegin,.3 new file mode 100644 index 000000000..eecaa5142 --- /dev/null +++ b/man/std::u32string::rbegin,.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rbegin, \- std::basic_string::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the first character of the reversed string. It + corresponds to the last character of the non-reversed string. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemplar!"); + *s.rbegin() = 'y'; + std::cout << s << '\\n'; // "Exemplary" + + std::string c; + std::copy(s.crbegin(), s.crend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "yralpmexE" + } + +.SH Output: + + Exemplary + yralpmexE + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::rbegin,std::basic_string::crbegin.3 b/man/std::u32string::rbegin,std::basic_string::crbegin.3 deleted file mode 120000 index e36abe435..000000000 --- a/man/std::u32string::rbegin,std::basic_string::crbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rbegin,std::basic_string::crbegin.3 \ No newline at end of file diff --git a/man/std::u32string::rend,.3 b/man/std::u32string::rend,.3 new file mode 100644 index 000000000..c28ff3818 --- /dev/null +++ b/man/std::u32string::rend,.3 @@ -0,0 +1,70 @@ +.TH std::basic_string::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rend, \- std::basic_string::rend, + +.SH Synopsis + + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the character following the last character of the + reversed string. It corresponds to the character preceding the first character of + the non-reversed string. This character acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string p("[A man, a plan, a canal: Panama]"); + std::string q; + + std::copy(p.crbegin(), p.crend(), std::back_inserter(q)); + std::cout << "q = " << q << '\\n'; + + std::copy(q.crbegin(), q.crend(), p.rbegin()); + std::cout << "p = " << p << '\\n'; + } + +.SH Output: + + q = ]amanaP :lanac a ,nalp a ,nam A[ + p = ]amanaP :lanac a ,nalp a ,nam A[ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::rend,std::basic_string::crend.3 b/man/std::u32string::rend,std::basic_string::crend.3 deleted file mode 120000 index 600152427..000000000 --- a/man/std::u32string::rend,std::basic_string::crend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rend,std::basic_string::crend.3 \ No newline at end of file diff --git a/man/std::u32string::replace.3 b/man/std::u32string::replace.3 deleted file mode 120000 index 3a94b3a6f..000000000 --- a/man/std::u32string::replace.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::replace.3 \ No newline at end of file diff --git a/man/std::u32string::replace.3 b/man/std::u32string::replace.3 new file mode 100644 index 000000000..7b1e79fc7 --- /dev/null +++ b/man/std::u32string::replace.3 @@ -0,0 +1,184 @@ +.TH std::basic_string::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace \- std::basic_string::replace + +.SH Synopsis + basic_string& replace( size_type pos, + size_type count, \fB(1)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(2)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( size_type pos, + size_type count, + + const basic_string& \fI(until C++14)\fP + str, + + size_type pos2, + size_type count2 ); + basic_string& replace( size_type pos, + size_type count, + \fI(since C++14)\fP + const basic_string& (constexpr since + str, C++20) + + size_type pos2, + size_type count2 = npos ); + basic_string& replace( size_type pos, + size_type count, \fB(4)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(5)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( size_type pos, (constexpr since + size_type count, \fB(6)\fP C++20) + const CharT* cstr ); + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(7)\fP C++20) + const CharT* cstr ); + basic_string& replace( size_type pos, + size_type count, \fB(8)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(3)\fP \fB(9)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + template< class InputIt > + + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(10)\fP C++20) + + InputIt first2, InputIt + last2 ); + basic_string& replace( const_iterator first, \fI(since C++11)\fP + const_iterator last, \fB(11)\fP (constexpr since + C++20) + std::initializer_list ilist ); + template< class StringViewLike > + + basic_string& replace( size_type pos, \fI(since C++17)\fP + size_type count, \fB(12)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( const_iterator first, \fI(since C++17)\fP + const_iterator last, \fB(13)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( size_type pos, + size_type count, \fI(since C++17)\fP + const StringViewLike& \fB(14)\fP (constexpr since + t, C++20) + + size_type pos2, + size_type count2 = npos ); + + Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count, + size())) or [first, last) with given characters. + + 1,2) Those characters are replaced with str. + 3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2, + str.size())) of str. + 4,5) Those characters are replaced with the characters in the range [cstr, cstr + + count2). + If [cstr, cstr + count2) is not a valid range, the behavior is undefined. + 6,7) Those characters are replaced with the characters in the range [cstr, cstr + + Traits::length(cstr)). + 8,9) Those characters are replaced with count2 copies of ch. + 10) Those characters are replaced with the characters in the range [first2, last2) + as if by replace(first, last, basic_string(first2, last2, get_allocator())). + 11) Those characters are replaced with the characters in ilist. + 12,13) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then those characters are replaced + with the characters from sv. + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 14) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then those characters are replaced with the characters from the + subview sv.substr(pos2, count2). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If [begin(), first) or [first, last) is not a valid range, the behavior is + undefined. + +.SH Parameters + + pos - start of the substring that is going to be replaced + count - length of the substring that is going to be replaced + first, last - range of characters that is going to be replaced + str - string to use for replacement + pos2 - start of the substring to replace with + count2 - number of characters to replace with + cstr - pointer to the character string to use for replacement + ch - character value to use for replacement + first2, last2 - range of characters to use for replacement + ilist - initializer list with the characters to use for replacement + t - object (convertible to std::basic_string_view) with the characters + to use for replacement +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this. + +.SH Exceptions + + 1) Throws std::out_of_range if pos > size(). + 3) Throws std::out_of_range if pos > size() or pos2 > str.size(). + 4,6,8) Throws std::out_of_range if pos > size(). + 12,14) Throws std::out_of_range if pos > size(). + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 1323 C++98 the types of first and last changed to const_iterator + were iterator + LWG 2946 C++17 overloads (12,13) caused avoided by making them templates + ambiguity in some cases + +.SH See also + + replace_with_range replaces specified portion of a string with a range of characters + (C++23) \fI(public member function)\fP + regex_replace replaces occurrences of a regular expression with formatted + \fI(C++11)\fP replacement text + \fI(function template)\fP + replace replaces all values satisfying specific criteria with another + replace_if value + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::u32string::replace_with_range.3 b/man/std::u32string::replace_with_range.3 new file mode 100644 index 000000000..a06106cbc --- /dev/null +++ b/man/std::u32string::replace_with_range.3 @@ -0,0 +1,91 @@ +.TH std::basic_string::replace_with_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace_with_range \- std::basic_string::replace_with_range + +.SH Synopsis + template< container-compatible-range R > + + constexpr std::basic_string& replace_with_range( const_iterator + first, (since C++23) + const_iterator last, + + R&& rg ); + + Replaces the characters in the range [first, last) with the characters from the + range rg. + + Equivalent to + + return replace(first, + last, + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + first, last - range of characters that is going to be replaced + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + auto s{"Today is today!"s}; + constexpr auto today{"today"sv}; + constexpr auto tomorrow{"tomorrow's yesterday"sv}; + std::forward_list rg; + std::ranges::reverse_copy(tomorrow, std::front_inserter(rg)); + + const auto pos{s.rfind(today)}; + assert(pos != s.npos); + const auto first{std::next(s.begin(), pos)}; + const auto last{std::next(first, today.length())}; + + #ifdef __cpp_lib_containers_ranges + s.replace_range(first, last, rg); + #else + s.replace(first, last, rg.cbegin(), rg.cend()); + #endif + + assert("Today is tomorrow's yesterday!" == s); + } + +.SH See also + + replace replaces specified portion of a string + \fI(public member function)\fP diff --git a/man/std::u32string::reserve.3 b/man/std::u32string::reserve.3 deleted file mode 120000 index 8af41bde6..000000000 --- a/man/std::u32string::reserve.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::reserve.3 \ No newline at end of file diff --git a/man/std::u32string::reserve.3 b/man/std::u32string::reserve.3 new file mode 100644 index 000000000..3f0d1423a --- /dev/null +++ b/man/std::u32string::reserve.3 @@ -0,0 +1,112 @@ +.TH std::basic_string::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::reserve \- std::basic_string::reserve + +.SH Synopsis + void reserve( size_type new_cap = 0 ); \fI(until C++20)\fP + constexpr void reserve( size_type new_cap ); \fI(since C++20)\fP + \fB(1)\fP \fI(since C++20)\fP + void reserve(); \fB(2)\fP (deprecated in C++20) + (removed in C++26) + + 1) Informs a std::basic_string object of a planned change in size, so that it can + manage the storage allocation appropriately. + * If new_cap is greater than the current capacity(), new storage is allocated, and + capacity() is made equal or greater than new_cap. + + * If new_cap is less than the current capacity(), this is a + non-binding shrink request. + * If new_cap is less than the current size(), this is a non-binding \fI(until C++20)\fP + shrink-to-fit request + equivalent to shrink_to_fit() + \fI(since C++11)\fP. + * If new_cap is less than or equal to the current capacity(), there \fI(since C++20)\fP + is no effect. + + If a capacity change takes place, all iterators and references, including the + past-the-end iterator, are invalidated. + 2) A non-binding shrink-to-fit request. After this call, capacity() has an + unspecified value greater than or equal to size(). + +.SH Parameters + + new_cap - new capacity of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::length_error if new_cap is greater than max_size(). + + May throw any exceptions thrown by std::allocator_traits::allocate(), + such as std::bad_alloc. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + At most linear in the size() of the string. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + std::cout << "1) Initially: " << s.capacity() << '\\n'; + + const std::string::size_type new_cap{101u}; + s.reserve(new_cap); + assert(s.capacity() >= new_cap); + std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\\n'; + + // observing the capacity growth factor + auto cap{s.capacity()}; + for (int check{}; check != 4; ++check) + { + while (cap == s.capacity()) + s += '$'; + cap = s.capacity(); + std::cout << (3) + check << ") Capacity: " << cap << '\\n'; + } + + // s.reserve(); // deprecated/removed in C++20/26, use: + s.shrink_to_fit(); + std::cout << "7) After shrink_to_fit: " << s.capacity() << '\\n'; + } + +.SH Possible output: + + 1) Initially: 15 + 2) After reserve(101): 101 + 3) Capacity: 202 + 4) Capacity: 404 + 5) Capacity: 808 + 6) Capacity: 1616 + 7) After shrink_to_fit: 809 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::u32string::resize.3 b/man/std::u32string::resize.3 deleted file mode 120000 index 15f0e17b9..000000000 --- a/man/std::u32string::resize.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::resize.3 \ No newline at end of file diff --git a/man/std::u32string::resize.3 b/man/std::u32string::resize.3 new file mode 100644 index 000000000..3b4c7a8b6 --- /dev/null +++ b/man/std::u32string::resize.3 @@ -0,0 +1,140 @@ +.TH std::basic_string::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize \- std::basic_string::resize + +.SH Synopsis + void resize( size_type count ); \fB(1)\fP (constexpr since C++20) + void resize( size_type count, CharT ch ); \fB(2)\fP (constexpr since C++20) + + Resizes the string to contain count characters. + + If the current size is less than count, additional characters are appended: + + 1) Initializes appended characters to CharT() ('\\0' if CharT is char). + 2) Initializes appended characters to ch. + + If the current size is greater than count, the string is reduced to its first count + elements. + +.SH Parameters + + count - new size of the string + ch - character to initialize the new characters with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > max_size(). Any exceptions thrown by corresponding + Allocator. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const unsigned desired_length{8}; + std::string long_string("Where is the end?"); + std::string short_string("H"); + + std::cout << "Basic functionality:\\n" + << "Shorten:\\n" + << "1. Before: " << std::quoted(long_string) << '\\n'; + long_string.resize(desired_length); + std::cout << "2. After: " << std::quoted(long_string) << '\\n'; + + std::cout << "Lengthen with a given value 'a':\\n" + << "3. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length, 'a'); + std::cout << "4. After: " << std::quoted(short_string) << '\\n'; + + std::cout << "Lengthen with char() == " << static_cast(char()) << '\\n' + << "5. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length + 3); + std::cout << "6. After: \\""; + for (char c : short_string) + std::cout << (c == char() ? '@' : c); + std::cout << "\\"\\n\\n"; + + std::cout << "Errors:\\n"; + std::string s; + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size() - 1, 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "1. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size(), 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "2. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is BAD, throw length_error + s.resize(s.max_size() + 1, 'x'); + } + catch (const std::length_error& ex) + { + std::cout << "3. Length error: " << ex.what() << '\\n'; + } + } + +.SH Possible output: + + Basic functionality: + Shorten: + 1. Before: "Where is the end?" + 2. After: "Where is" + Lengthen with a given value 'a': + 3. Before: "H" + 4. After: "Haaaaaaa" + Lengthen with char() == 0 + 5. Before: "Haaaaaaa" + 6. After: "Haaaaaaa@@@" + + Errors: + 1. Exception: std::bad_alloc + 2. Exception: std::bad_alloc + 3. Length error: basic_string::_M_replace_aux + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP diff --git a/man/std::u32string::resize_and_overwrite.3 b/man/std::u32string::resize_and_overwrite.3 new file mode 100644 index 000000000..192feef8a --- /dev/null +++ b/man/std::u32string::resize_and_overwrite.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::resize_and_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize_and_overwrite \- std::basic_string::resize_and_overwrite + +.SH Synopsis + template< class Operation > (since C++23) + constexpr void resize_and_overwrite( size_type count, Operation op ); + + Resizes the string to contain at most count characters, using the user-provided + operation op to modify the possibly indeterminate contents and set the length. This + avoids the cost of initializing a suitably-sized std::string when it is intended to + be used as a char array to be populated by, e.g., a C API call. + + This function performs following steps: + + 1. Obtains contiguous storage that contains count + 1 characters, and makes its + first k characters equal to the first k characters of *this, where k is the + smaller of count and the result of this->size() before the call to + resize_and_overwrite. Let p denote the pointer to the first character in the + storage. + * The equality is determined as if by checking this->compare(0, k, p, k) == + 0. + * The characters in [p + k, p + count] may have indeterminate values. + 2. Evaluates std::move(op)(p, count). Let r be the return value of std::move(op)(p, + count). + 3. Replaces the contents of *this with [p, p + r) (which sets the length of *this + to r). Invalidates all pointers and references to the range [p, p + count]. + + The program is ill-formed if r does not have an integer-like type. The behavior is + undefined if std::move(op)(p, count) throws an exception or modifies p or count, r + is not in the range [0, count], or any character in range [p, p + r) has an + indeterminate value. + + Implementations are recommended to avoid unnecessary copies and allocations by, + e.g., making p equal to the pointer to beginning of storage of characters allocated + for *this after the call, which can be identical to the existing storage of *this if + count is less than or equal to this->capacity(). + +.SH Parameters + + count - the maximal possible new size of the string + op - the function object used for setting the new contents of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > this->max_size(). Any exceptions thrown by + corresponding Allocator. + + If an exception is thrown from std::move(op)(p, count), the behavior is undefined. + Otherwise, if an exception is thrown, this function has no effect. + +.SH Notes + + resize_and_overwrite invalidates all iterators, pointers, and references into *this, + regardless whether reallocation occurs. Implementations may assume that the contents + of the string are not aliased after the call to resize_and_overwrite. + + Feature-test macro Value Std Feature +__cpp_lib_string_resize_and_overwrite 202110L (C++23) std::basic_string::resize_and_overwrite + +.SH Example + + Link to test the example: compiler explorer. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + static_assert(__cpp_lib_string_resize_and_overwrite); + + constexpr std::string_view fruits[]{"apple", "banana", "coconut", "date", "elderberry"}; + + int main() + { + // A simple case, append only fruits[0]. The string size will be increased. + std::string s{"Food: "}; + s.resize_and_overwrite(16, [sz = s.size()](char* buf, std::size_t buf_size) noexcept + { + const auto to_copy = std::min(buf_size - sz, fruits[0].size()); + std::memcpy(buf + sz, fruits[0].data(), to_copy); + return sz + to_copy; + }); + std::cout << "1. " << std::quoted(s) << '\\n'; + + // The size shrinking case. Note, that the user's lambda is always invoked. + s.resize_and_overwrite(10, [](char* buf, int n) noexcept + { + return std::find(buf, buf + n, ':') - buf; + }); + std::cout << "2. " << std::quoted(s) << '\\n'; + + std::cout << "3. Copy data until the buffer is full. Print data and sizes.\\n"; + std::string food{"Food:"}; + const auto resize_to{27}; + std::cout << "Initially, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", resize_to: " << resize_to + << ", food: " << std::quoted(food) << '\\n'; + + food.resize_and_overwrite( + resize_to, + [food_size = food.size()](char* p, std::size_t n) noexcept -> std::size_t + { + // p[0]..p[n] is the assignable range + // p[0]..p[min(n, food_size) - 1] is the readable range + // (contents initially equal to the original string) + + // Debug print: + std::cout << "In Operation(); n: " << n << '\\n'; + + // Copy fruits to the buffer p while there is enough space. + char* first = p + food_size; + + for (char* const end = p + n; const std::string_view fruit : fruits) + { + char* last = first + fruit.size() + 1; + if (last > end) + break; + *first++ = ' '; + std::ranges::copy(fruit, first); + first = last; + } + + const auto final_size{static_cast(first - p)}; + + // Debug print: + std::cout << "In Operation(); final_size: " << final_size << '\\n'; + + assert(final_size <= n); + return final_size; // Return value is the actual new length + // of the string, must be in range 0..n + }); + + std::cout << "Finally, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", food: " << std::quoted(food) << '\\n'; + } + +.SH Possible output: + + 1. "Food: apple" + 2. "Food" + 3. Copy data until the buffer is full. Print data and sizes. + Initially, food.size: 5, food.capacity: 15, resize_to: 27, food: "Food:" + In Operation(); n: 27 + In Operation(); final_size: 26 + Finally, food.size: 26, food.capacity: 30, food: "Food: apple banana coconut" + +.SH See also + + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::u32string::rfind.3 b/man/std::u32string::rfind.3 deleted file mode 120000 index 6ca6348d9..000000000 --- a/man/std::u32string::rfind.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rfind.3 \ No newline at end of file diff --git a/man/std::u32string::rfind.3 b/man/std::u32string::rfind.3 new file mode 100644 index 000000000..6baebe7ca --- /dev/null +++ b/man/std::u32string::rfind.3 @@ -0,0 +1,161 @@ +.TH std::basic_string::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rfind \- std::basic_string::rfind + +.SH Synopsis + size_type rfind( const basic_string& str, size_type pos \fB(1)\fP (noexcept since C++11) + = npos ) const; (constexpr since C++20) + size_type rfind( const CharT* s, size_type pos, \fB(2)\fP (constexpr since C++20) + size_type count ) const; + size_type rfind( const CharT* s, size_type pos = npos ) \fB(3)\fP (constexpr since C++20) + const; + size_type rfind( CharT ch, size_type pos = npos ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type rfind( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last substring equal to str. + 2) Finds the last substring equal to the range [s, s + count). This range can + include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last substring equal to the contents of sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string to search for + pos - position at which to begin searching + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. Note that this is an offset from the start of the string, not the end. + + If searching for an empty string (i.e., str.size(), count, or Traits::length(s) is + zero), the empty string is found immediately and rfind returns: + + * pos, if pos < size(); + * size() otherwise, including the case where pos == npos. + + Otherwise, if size() is zero, npos is always returned. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(std::string::size_type n, + std::string::size_type len, + std::string const &s) + { + if (n == std::string::npos) + std::cout << "not found\\n"; + else + std::cout << "found: " << std::quoted(s.substr(n, len)) << " at " << n << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; + + // search backwards from end of string + n = s.rfind("is"); + print(n, 2, s); + + // search backwards from position 4 + n = s.rfind("is", 4); + print(n, 2, s); + + // find a single character + n = s.rfind('s'); + print(n, 1, s); + + // find a single character + n = s.rfind('q'); + print(n, 1, s); + + // find the prefix (see also s.starts_with("This")) + n = s.rfind("This", 0); + print(n, 4, s); + } + +.SH Output: + + found: "is" at 5 + found: "is" at 2 + found: "s" at 10 + not found + found: "This" at 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::shrink_to_fit.3 b/man/std::u32string::shrink_to_fit.3 deleted file mode 120000 index af19637a3..000000000 --- a/man/std::u32string::shrink_to_fit.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::shrink_to_fit.3 \ No newline at end of file diff --git a/man/std::u32string::shrink_to_fit.3 b/man/std::u32string::shrink_to_fit.3 new file mode 100644 index 000000000..506b08ea9 --- /dev/null +++ b/man/std::u32string::shrink_to_fit.3 @@ -0,0 +1,95 @@ +.TH std::basic_string::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::shrink_to_fit \- std::basic_string::shrink_to_fit + +.SH Synopsis + void shrink_to_fit(); (constexpr since C++20) + + Requests the removal of unused capacity. + + It is a non-binding request to reduce capacity() to size(). It depends on the + implementation if the request is fulfilled. + + If (and only if) reallocation takes place, all pointers, references, and iterators + are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + (unspecified) \fI(until C++17)\fP + Linear in the size of the string. \fI(since C++17)\fP + +.SH Notes + + In libstdc++, shrink_to_fit() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::cout << "Size of std::string is " << sizeof s << " bytes\\n" + << "Default-constructed capacity is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + for (int i = 0; i < 42; i++) + s.append(" 42 "); + std::cout << "Capacity after 42 appends is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.clear(); + std::cout << "Capacity after clear() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.shrink_to_fit(); + std::cout << "Capacity after shrink_to_fit() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + } + +.SH Possible output: + + GCC output: + Size of std::string is 32 bytes + Default-constructed capacity is 15 and size 0 + Capacity after 42 appends is 240 and size 168 + Capacity after clear() is 240 and size 0 + Capacity after shrink_to_fit() is 15 and size 0 + + clang output (with -stdlib=libc++): + Size of std::string is 24 bytes + Default-constructed capacity is 22 and size is 0 + Capacity after 42 appends is 191 and size is 168 + Capacity after clear() is 191 and size is 0 + Capacity after shrink_to_fit() is 22 and size is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 755 C++98 std::string lacked explicit shrink-to-fit provided + operations + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::u32string::size,.3 b/man/std::u32string::size,.3 new file mode 100644 index 000000000..46f96cd93 --- /dev/null +++ b/man/std::u32string::size,.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::size, \- std::basic_string::size, + +.SH Synopsis + + size_type size() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + size_type length() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + + Returns the number of CharT elements in the string, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the string. + +.SH Complexity + + Unspecified \fI(until C++11)\fP + Constant \fI(since C++11)\fP + +.SH Notes + + For std::string, the elements are bytes (objects of type char), which are not the + same as characters if a multibyte encoding such as UTF-8 is used. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("Exemplar"); + assert(8 == s.size()); + assert(s.size() == s.length()); + assert(s.size() == static_cast( + std::distance(s.begin(), s.end()))); + + std::u32string a(U"ハロー・ワールド"); // 8 code points + assert(8 == a.size()); // 8 code units in UTF-32 + + std::u16string b(u"ハロー・ワールド"); // 8 code points + assert(8 == b.size()); // 8 code units in UTF-16 + + std::string c("ハロー・ワールド"); // 8 code points + assert(24 == c.size()); // 24 code units in UTF-8 + + #if __cplusplus >= 202002 + std::u8string d(u8"ハロー・ワールド"); // 8 code points + assert(24 == d.size()); // 24 code units in UTF-8 + #endif + } + +.SH See also + + empty checks whether the string is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::size,std::basic_string::length.3 b/man/std::u32string::size,std::basic_string::length.3 deleted file mode 120000 index dbf50666e..000000000 --- a/man/std::u32string::size,std::basic_string::length.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::size,std::basic_string::length.3 \ No newline at end of file diff --git a/man/std::u32string::starts_with.3 b/man/std::u32string::starts_with.3 new file mode 100644 index 000000000..54b219105 --- /dev/null +++ b/man/std::u32string::starts_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::starts_with \- std::basic_string::starts_with + +.SH Synopsis + constexpr bool + starts_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + starts_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + starts_with( const CharT* s ) const; + + Checks if the string begins with the given prefix. The prefix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).starts_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.starts_with("He"sv) // (1) + && !str.starts_with("he"sv) // (1) + && str.starts_with("He"s) // (1) implicit conversion string to string_view + && !str.starts_with("he"s) // (1) implicit conversion string to string_view + && str.starts_with('H') // (2) + && !str.starts_with('h') // (2) + && str.starts_with("He") // (3) + && !str.starts_with("he") // (3) + ); + } + +.SH See also + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::u32string::substr.3 b/man/std::u32string::substr.3 deleted file mode 120000 index 3a94fd2cd..000000000 --- a/man/std::u32string::substr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::substr.3 \ No newline at end of file diff --git a/man/std::u32string::substr.3 b/man/std::u32string::substr.3 new file mode 100644 index 000000000..f263d4824 --- /dev/null +++ b/man/std::u32string::substr.3 @@ -0,0 +1,113 @@ +.TH std::basic_string::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::substr \- std::basic_string::substr + +.SH Synopsis + basic_string substr( size_type pos = 0, size_type (until C++23) + count = npos ) const; (constexpr since C++20) + constexpr basic_string + substr( size_type pos = 0, size_type count = \fB(1)\fP (since C++23) + npos ) const&; + constexpr basic_string substr( size_type pos = 0, \fB(2)\fP (since C++23) + size_type count = npos ) &&; + + Returns a substring [pos, pos + count). If the requested substring extends past the + end of the string, i.e. the count is greater than size() - pos (e.g. if count == + npos), the returned substring is [pos, size()). + + 1) Equivalent to return basic_string(*this, pos, count);. + 2) Equivalent to return basic_string(std::move(*this), pos, count);. + +.SH Parameters + + pos - position of the first character to include + count - length of the substring + +.SH Return value + + String containing the substring [pos, pos + count) or [pos, size()). + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Notes + + The allocator of the returned string is default-constructed: the new allocator might + not be a copy of get_allocator(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "0123456789abcdefghij"; + + // count is npos, returns [pos, size()) + std::string sub1 = a.substr(10); + std::cout << sub1 << '\\n'; + + // both pos and pos + count are within bounds, returns [pos, pos + count) + std::string sub2 = a.substr(5, 3); + std::cout << sub2 << '\\n'; + + // pos is within bounds, pos + count is not, returns [pos, size()) + std::string sub4 = a.substr(a.size() - 3, 50); + // this is effectively equivalent to + // std::string sub4 = a.substr(17, 3); + // since a.size() == 20, pos == a.size() - 3 == 17, and a.size() - pos == 3 + + std::cout << sub4 << '\\n'; + + try + { + // pos is out of bounds, throws + std::string sub5 = a.substr(a.size() + 3, 50); + std::cout << sub5 << '\\n'; + } + catch (const std::out_of_range& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + abcdefghij + 567 + hij + basic_string::substr: __pos (which is 23) > this->size() (which is 20) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + copy copies characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + substr returns a substring + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::u32string::swap.3 b/man/std::u32string::swap.3 deleted file mode 120000 index bc1277047..000000000 --- a/man/std::u32string::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::swap.3 \ No newline at end of file diff --git a/man/std::u32string::swap.3 b/man/std::u32string::swap.3 new file mode 100644 index 000000000..07e64dbec --- /dev/null +++ b/man/std::u32string::swap.3 @@ -0,0 +1,96 @@ +.TH std::basic_string::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::swap \- std::basic_string::swap + +.SH Synopsis + void swap( basic_string& other ); \fI(until C++17)\fP + void swap( basic_string& other ) noexcept(/* see below */); \fI(since C++17)\fP + (constexpr since C++20) + + Exchanges the contents of the string with those of other. All iterators and + references may be invalidated. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + +.SH Parameters + + other - string to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + No exception is thrown. \fI(until C++11)\fP + Exceptions can only be thrown in the case where the behavior is + undefined (see above). + \fI(since C++11)\fP + If an exception is thrown for any reason, this function has no effect + (strong exception safety guarantee). + + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_swap::value (since + || C++17) + std::allocator_traits::is_always_equal::value) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "AAA"; + std::string b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 403 C++98 swap() might throw an exception no exception is thrown + LWG 535 C++98 swapping strings did not preserve the orders are also preserved + character orders + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swap swaps the contents + \fI(public member function of std::basic_string_view)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::u32string::u32string.3 b/man/std::u32string::u32string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::u32string::u32string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::u32string::u32string.3 b/man/std::u32string::u32string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::u32string::u32string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::u32string::~basic_string.3 b/man/std::u32string::~basic_string.3 new file mode 100644 index 000000000..631cdb44e --- /dev/null +++ b/man/std::u32string::~basic_string.3 @@ -0,0 +1,13 @@ +.TH std::basic_string::~basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::~basic_string \- std::basic_string::~basic_string + +.SH Synopsis + ~basic_string(); (constexpr since C++20) + + Destructs the basic_string. The destructors of the elements are called and the used + storage is deallocated. + +.SH Complexity + + Typically constant (formally linear). diff --git a/man/std::u32string_view.3 b/man/std::u32string_view.3 new file mode 100644 index 000000000..df2b6eb62 --- /dev/null +++ b/man/std::u32string_view.3 @@ -0,0 +1,277 @@ +.TH std::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view \- std::basic_string_view + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++17)\fP + class Traits = std::char_traits + + > class basic_string_view; + + The class template basic_string_view describes an object that can refer to a + constant contiguous sequence of CharT with the first element of the sequence at + position zero. + + For a basic_string_view str, pointers, iterators, and references to elements of str + are invalidated when an operation invalidates a pointer in the range + [str.data(), str.data() + str.size()). + + Every specialization of std::basic_string_view is a TriviallyCopyable (since C++23) + type. + + A typical implementation holds only two members: a pointer to constant CharT and a + size. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string_view \fI(C++17)\fP std::basic_string_view + std::wstring_view \fI(C++17)\fP std::basic_string_view + std::u8string_view (C++20) std::basic_string_view + std::u16string_view \fI(C++17)\fP std::basic_string_view + std::u32string_view \fI(C++17)\fP std::basic_string_view + +.SH Template parameters + + CharT - character type + CharTraits class specifying the operations on the character type. Like for + Traits - std::basic_string, Traits::char_type must name the same type as CharT or + the program is ill-formed. + + Nested types + + Nested type Definition + traits_type Traits + value_type CharT + pointer CharT* + const_pointer const CharT* + reference CharT& + const_reference const CharT& + implementation-defined constant LegacyRandomAccessIterator, + + const_iterator and LegacyContiguousIterator \fI(until C++20)\fP + ConstexprIterator, and contiguous_iterator \fI(since C++20)\fP + + whose value_type is CharT + iterator const_iterator + const_reverse_iterator std::reverse_iterator + reverse_iterator const_reverse_iterator + size_type std::size_t + difference_type std::ptrdiff_t + + Note: iterator and const_iterator are the same type because string views are views + into constant character sequences. + + All requirements on the iterator types of a Container applies to the iterator and + const_iterator types of basic_string_view as well. + +.SH Member functions + + Constructors and assignment + constructor constructs a basic_string_view + \fI(public member function)\fP + operator= assigns a view + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Element access + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function)\fP +.SH Capacity + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP +.SH Modifiers + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Operations + copy copies characters + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string view contains the given substring or + (C++23) character + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) +.SH Input/output + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_view_literals + operator""sv creates a string view of a character array literal + \fI(C++17)\fP \fI(function)\fP + +.SH Helper classes + + std::hash + std::hash + std::hash + std::hash + std::hash hash support for string views + \fI(C++17)\fP \fI(class template specialization)\fP + \fI(C++17)\fP + (C++20) + \fI(C++17)\fP + \fI(C++17)\fP + + Helper templates + + template< class CharT, class Traits > + + inline constexpr bool (since + C++20) + ranges::enable_borrowed_range> = + true; + + This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy + borrowed_range. + + template< class CharT, class Traits > + + inline constexpr bool \fI(since C++20)\fP + + ranges::enable_view> = + true; + + This specialization of ranges::enable_view makes basic_string_view satisfy view. + + Deduction guides \fI(since C++20)\fP + +.SH Notes + + It is the programmer's responsibility to ensure that std::string_view does not + outlive the pointed-to character array: + + std::string_view good{"a string literal"}; + // "Good" case: `good` points to a static array. + // String literals reside in persistent data storage. + + std::string_view bad{"a temporary string"s}; + // "Bad" case: `bad` holds a dangling pointer since the std::string temporary, + // created by std::operator""s, will be destroyed at the end of the statement. + + Specializations of std::basic_string_view are already trivially copyable types in + all existing implementations, even before the formal requirement introduced in + C++23. + + Feature-test macro Value Std Feature + __cpp_lib_string_view 201606L \fI(C++17)\fP std::string_view + 201803L (C++20) ConstexprIterator + __cpp_lib_string_contains 202011L (C++23) contains + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view unicode[]{"▀▄─", "▄▀─", "▀─▄", "▄─▀"}; + + for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4)) + { + for (int x{}; x != 16; ++x) + std::cout << unicode[p]; + std::cout << '\\n'; + } + } + +.SH Output: + + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ + ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀ + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + only pointers, iterators, and all pointers, iterators, and + references references + LWG 3203 C++17 returned from the member functions to elements of + of basic_string_view + basic_string_view might be may be invalidated + invalidated + +.SH See also + + basic_string stores and manipulates sequences of characters + \fI(class template)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + initializer_list creates a temporary array in list-initialization and then + \fI(C++11)\fP references it + \fI(class template)\fP diff --git a/man/std::u32string_view::at.3 b/man/std::u32string_view::at.3 new file mode 100644 index 000000000..65f8fa91d --- /dev/null +++ b/man/std::u32string_view::at.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::at \- std::basic_string_view::at + +.SH Synopsis + constexpr const_reference at( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. Bounds + checking is performed, exception of type std::out_of_range will be thrown on invalid + access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string_view str_view("abcdef"); + + try + { + for (std::size_t i = 0; true; ++i) + std::cout << i << ": " << str_view.at(i) << '\\n'; + } + catch (const std::out_of_range& e) + { + std::cout << "Whooops. Index is out of range.\\n"; + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + 0: a + 1: b + 2: c + 3: d + 4: e + 5: f + 6: Whooops. Index is out of range. + basic_string_view::at: __pos (which is 6) >= this->size() (which is 6) + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + accesses the specified character with bounds checking + at \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::back.3 b/man/std::u32string_view::back.3 new file mode 100644 index 000000000..7fd79d7b3 --- /dev/null +++ b/man/std::u32string_view::back.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::back \- std::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; \fI(since C++17)\fP + + Returns reference to the last character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_suffix(1)) + std::cout << str.back() << ' ' << str << '\\n'; + } + +.SH Output: + + F ABCDEF + E ABCDE + D ABCD + C ABC + B AB + A A + +.SH See also + + front accesses the first character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::u32string_view::basic_string_view.3 b/man/std::u32string_view::basic_string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::u32string_view::basic_string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::begin,std::basic_string_view::cbegin.3 b/man/std::u32string_view::begin,std::basic_string_view::cbegin.3 new file mode 100644 index 000000000..83667f3e5 --- /dev/null +++ b/man/std::u32string_view::begin,std::basic_string_view::cbegin.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::begin,std::basic_string_view::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::begin,std::basic_string_view::cbegin \- std::basic_string_view::begin,std::basic_string_view::cbegin + +.SH Synopsis + constexpr const_iterator begin() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cbegin() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + + constexpr auto begin = str_view.begin(); + constexpr auto cbegin = str_view.cbegin(); + static_assert( + *begin == 'a' and + *cbegin == 'a' and + *begin == *cbegin and + begin == cbegin and + std::same_as); + } + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u32string_view::compare.3 b/man/std::u32string_view::compare.3 new file mode 100644 index 000000000..8087ec4ef --- /dev/null +++ b/man/std::u32string_view::compare.3 @@ -0,0 +1,95 @@ +.TH std::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::compare \- std::basic_string_view::compare + +.SH Synopsis + constexpr int compare( basic_string_view v ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(2)\fP \fI(since C++17)\fP + basic_string_view v ) const; + constexpr int compare( size_type pos1, size_type count1, + basic_string_view v, \fB(3)\fP \fI(since C++17)\fP + size_type pos2, size_type count2 ) const; + constexpr int compare( const CharT* s ) const; \fB(4)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(5)\fP \fI(since C++17)\fP + const CharT* s ) const; + constexpr int compare( size_type pos1, size_type count1, \fB(6)\fP \fI(since C++17)\fP + const CharT* s, size_type count2 ) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less < 0 + than v + size() < this is less < 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater > 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater > 0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + Negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH Example + + +// Run this code + + #include + + int main() + { + using std::operator""sv; + static_assert("abc"sv.compare("abcd"sv) < 0); + static_assert("abcd"sv.compare("abc"sv) > 0); + static_assert("abc"sv.compare("abc"sv) == 0); + static_assert(""sv.compare(""sv) == 0); + } + +.SH See also + + compares two strings + compare \fI\fI(public member\fP function of\fP + std::basic_string) + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) diff --git a/man/std::u32string_view::contains.3 b/man/std::u32string_view::contains.3 new file mode 100644 index 000000000..8c655ade3 --- /dev/null +++ b/man/std::u32string_view::contains.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::contains \- std::basic_string_view::contains + +.SH Synopsis + constexpr bool contains( basic_string_view sv ) const noexcept; \fB(1)\fP (since C++23) + constexpr bool contains( CharT c ) const noexcept; \fB(2)\fP (since C++23) + constexpr bool contains( const CharT* s ) const; \fB(3)\fP (since C++23) + + Checks if the string view contains the given substring, where + + 1) the substring is a string view. + 2) the substring is a single character. + 3) the substring is a null-terminated character string. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view + c - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + static_assert + ( + // bool contains(basic_string_view x) const noexcept; + "https://cppreference.com"sv.contains("cpp"sv) == true and + "https://cppreference.com"sv.contains("php"sv) == false and + + // bool contains(CharT x) const noexcept; + "C++23"sv.contains('+') == true and + "C++23"sv.contains('-') == false and + + // bool contains(const CharT* x) const; + std::string_view("basic_string_view").contains("string") == true and + std::string_view("basic_string_view").contains("String") == false + ); + + int main() {} + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::copy.3 b/man/std::u32string_view::copy.3 new file mode 100644 index 000000000..50e77b7be --- /dev/null +++ b/man/std::u32string_view::copy.3 @@ -0,0 +1,88 @@ +.TH std::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::copy \- std::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos \fI(since C++17)\fP + = 0 ) const; (constexpr since C++20) + + Copies the substring [pos, pos + rcount) to the character array pointed to by dest, + where rcount is the smaller of count and size() - pos. + + Equivalent to Traits::copy(dest, data() + pos, rcount). + +.SH Parameters + + dest - pointer to the destination character string + count - requested substring length + pos - position of the first character + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::basic_string_view source{"ABCDEF"}; + std::array dest; + std::size_t count{}, pos{}; + + dest.fill('\\0'); + source.copy(dest.data(), count = 4); // pos = 0 + std::cout << dest.data() << '\\n'; // ABCD + + dest.fill('\\0'); + source.copy(dest.data(), count = 4, pos = 1); + std::cout << dest.data() << '\\n'; // BCDE + + dest.fill('\\0'); + source.copy(dest.data(), count = 42, pos = 2); // ok, count -> 4 + std::cout << dest.data() << '\\n'; // CDEF + + try + { + source.copy(dest.data(), count = 1, pos = 666); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Output: + + ABCD + BCDE + CDEF + basic_string_view::copy: __pos (which is 666) > __size (which is 6) + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::u32string_view::data.3 b/man/std::u32string_view::data.3 new file mode 100644 index 000000000..29290d3ff --- /dev/null +++ b/man/std::u32string_view::data.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::data \- std::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; \fI(since C++17)\fP + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::data() and string literals, std::basic_string_view::data() + returns a pointer to a buffer that is not necessarily null-terminated, for example a + substring view (e.g. from remove_suffix). Therefore, it is typically a mistake to + pass data() to a routine that takes just a const CharT* and expects a + null-terminated string. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::wstring_view wcstr_v = L"xyzzy"; + std::cout << std::wcslen(wcstr_v.data()) << '\\n'; + // OK: the underlying character array is null-terminated + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, sizeof array); + // std::cout << std::strlen(array_v.data()) << '\\n'; + // error: the underlying character array is not null-terminated + + std::string str(array_v.data(), array_v.size()); // OK + std::cout << std::strlen(str.data()) << '\\n'; + // OK: the underlying character array of a std::string is always null-terminated + } + +.SH Output: + + 5 + 3 + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function of std::basic_string)\fP diff --git a/man/std::u32string_view::empty.3 b/man/std::u32string_view::empty.3 new file mode 100644 index 000000000..185b498eb --- /dev/null +++ b/man/std::u32string_view::empty.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::empty \- std::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + checks whether the string is empty + empty \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::end,std::basic_string_view::cend.3 b/man/std::u32string_view::end,std::basic_string_view::cend.3 new file mode 100644 index 000000000..465ae8a3e --- /dev/null +++ b/man/std::u32string_view::end,std::basic_string_view::cend.3 @@ -0,0 +1,54 @@ +.TH std::basic_string_view::end,std::basic_string_view::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::end,std::basic_string_view::cend \- std::basic_string_view::end,std::basic_string_view::cend + +.SH Synopsis + constexpr const_iterator end() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cend() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + constexpr auto end = str_view.end(); + constexpr auto cend = str_view.cend(); + + static_assert + ( + *std::prev(end) == 'd' && 'd' == *std::prev(cend) and end == cend + ); + } + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u32string_view::ends_with.3 b/man/std::u32string_view::ends_with.3 new file mode 100644 index 000000000..ad6eecb60 --- /dev/null +++ b/man/std::u32string_view::ends_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::ends_with \- std::basic_string_view::ends_with + +.SH Synopsis + constexpr bool ends_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool ends_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool ends_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view ends with the given suffix, where + + 1) the suffix is a string view. Effectively returns size() >= sv.size() && + compare(size() - sv.size(), npos, sv) == 0. + 2) the suffix is a single character. Effectively returns !empty() && + Traits::eq(back(), ch). + 3) the suffix is a null-terminated character string. Effectively returns + ends_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) ends_with( basic_string_view sv ) + && std::string_view("https://cppreference.com").ends_with(".com"sv) == true + && std::string_view("https://cppreference.com").ends_with(".org"sv) == false + + // (2) ends_with( CharT c ) + && std::string_view("C++20").ends_with('0') == true + && std::string_view("C++20").ends_with('3') == false + + // (3) ends_with( const CharT* s ) + && std::string_view("string_view").ends_with("view") == true + && std::string_view("string_view").ends_with("View") == false + ); + } + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::u32string_view::find.3 b/man/std::u32string_view::find.3 new file mode 100644 index 000000000..8882c44bb --- /dev/null +++ b/man/std::u32string_view::find.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find \- std::basic_string_view::find + +.SH Synopsis + constexpr size_type find( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type find( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type find( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type find( const CharT* s, size_type pos = 0 ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + + constexpr auto str{" long long int;"sv}; + + static_assert( + 1 == str.find("long"sv) && "<- find(v , pos = 0)" && + 6 == str.find("long"sv, 2) && "<- find(v , pos = 2)" && + 0 == str.find(' ') && "<- find(ch, pos = 0)" && + 2 == str.find('o', 1) && "<- find(ch, pos = 1)" && + 2 == str.find("on") && "<- find(s , pos = 0)" && + 6 == str.find("long double", 5, 4) && "<- find(s , pos = 5, count = 4)" + ); + + static_assert(str.npos == str.find("float")); + } + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + finds the first occurrence of the given substring + find \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u32string_view::find_first_not_of.3 b/man/std::u32string_view::find_first_not_of.3 new file mode 100644 index 000000000..6ad069029 --- /dev/null +++ b/man/std::u32string_view::find_first_not_of.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_not_of \- std::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type + find_first_not_of( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_first_not_of( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_first_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_not_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or std::string_view::npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + int main() + { + static_assert(2 == "BCDEF"sv.find_first_not_of("ABC")); + // ^ + static_assert(4 == "BCDEF"sv.find_first_not_of("ABC", 4)); + // ^ + static_assert(1 == "BCDEF"sv.find_first_not_of('B')); + // ^ + static_assert(3 == "BCDEF"sv.find_first_not_of('D', 2)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u32string_view::find_first_of.3 b/man/std::u32string_view::find_first_of.3 new file mode 100644 index 000000000..c6b35518c --- /dev/null +++ b/man/std::u32string_view::find_first_of.3 @@ -0,0 +1,100 @@ +.TH std::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_of \- std::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type + find_first_of( basic_string_view v, size_type pos = 0 ) const \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_first_of( CharT ch, size_type pos = 0 ) const noexcept; + constexpr size_type + find_first_of( const CharT* s, size_type pos, size_type count \fB(3)\fP \fI(since C++17)\fP + ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurrence of any of the characters of v in this view, starting + at position pos. + 2) Equivalent to find_first_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + constexpr bool is_white_space(const char c) + { + return " \\t\\n\\f\\r\\v"sv.find_first_of(c) != N; + }; + + static_assert( + 1 == "alignas"sv.find_first_of("klmn"sv) && + // └─────────────────────────┘ + N == "alignof"sv.find_first_of("wxyz"sv) && + // + 3 == "concept"sv.find_first_of("bcde"sv, /* pos= */ 1) && + // └───────────────────────┘ + N == "consteval"sv.find_first_of("oxyz"sv, /* pos= */ 2) && + // + 6 == "constexpr"sv.find_first_of('x') && + // └─────────────────────┘ + N == "constinit"sv.find_first_of('x') && + // + 6 == "const_cast"sv.find_first_of('c', /* pos= */ 4) && + // └──────────────────────┘ + N == "continue"sv.find_first_of('c', /* pos= */ 42) && + // + 5 == "co_await"sv.find_first_of("cba", /* pos= */ 4) && + // └───────────────────────┘ + 7 == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 2) && + // └────────────────────┘ + N == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 1) && + // + is_white_space(' ') && is_white_space('\\r') && !is_white_space('\\a') + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u32string_view::find_last_not_of.3 b/man/std::u32string_view::find_last_not_of.3 new file mode 100644 index 000000000..1f593444d --- /dev/null +++ b/man/std::u32string_view::find_last_not_of.3 @@ -0,0 +1,79 @@ +.TH std::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_not_of \- std::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type + find_last_not_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_last_not_of( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last character not equal to any of the characters in the given character + sequence. The search considers only the interval [0, pos]. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using std::operator""sv; + + int main() + { + static_assert(1 == "BCDEF"sv.find_last_not_of("DEF")); + // ^ + static_assert(2 == "BCDEFG"sv.find_last_not_of("EFG", 3)); + // ^ + static_assert(2 == "ABBA"sv.find_last_not_of('A')); + // ^ + static_assert(1 == "ABBA"sv.find_last_not_of('A', 1)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u32string_view::find_last_of.3 b/man/std::u32string_view::find_last_of.3 new file mode 100644 index 000000000..0203b94f0 --- /dev/null +++ b/man/std::u32string_view::find_last_of.3 @@ -0,0 +1,92 @@ +.TH std::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_of \- std::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type + find_last_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_last_of( CharT ch, size_type pos = npos ) const noexcept; + constexpr size_type + find_last_of( const CharT* s, size_type pos, size_type count ) \fB(3)\fP \fI(since C++17)\fP + const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_last_of( const CharT* s, size_type pos = npos ) const; + + Finds the last character equal to one of characters in the given character sequence. + Exact search algorithm is not specified. The search considers only the interval + [0, pos]. If the character is not present in the interval, npos will be returned. + + 1) Finds the last occurence of any of the characters of v in this view, ending at + position pos. + 2) Equivalent to find_last_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which the search is to finish + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert( + 5 == "delete"sv.find_last_of("cdef"sv) && + // └────────────────────┘ + N == "double"sv.find_last_of("fghi"sv) && + // + 0 == "else"sv.find_last_of("bcde"sv, 2 /* pos [0..2]: "els" */) && + // └────────────────────────┘ + N == "explicit"sv.find_last_of("abcd"sv, 4 /* pos [0..4]: "expli" */) && + // + 3 == "extern"sv.find_last_of('e') && + // └────────────────────┘ + N == "false"sv.find_last_of('x') && + // + 0 == "inline"sv.find_last_of('i', 2 /* pos [0..2]: "inl" */) && + // └───────────────────────┘ + N == "mutable"sv.find_last_of('a', 2 /* pos [0..2]: "mut" */) && + // + 3 == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 3 /* "cde" */) && + // └─────────────────────────┘ + N == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 2 /* "cd" */) + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u32string_view::front.3 b/man/std::u32string_view::front.3 new file mode 100644 index 000000000..475c3cb67 --- /dev/null +++ b/man/std::u32string_view::front.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::front \- std::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; \fI(since C++17)\fP + + Returns reference to the first character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_prefix(1)) + std::cout << str.front() << ' ' << str << '\\n'; + } + +.SH Output: + + A ABCDEF + B BCDEF + C CDEF + D DEF + E EF + F F + +.SH See also + + back accesses the last character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::u32string_view::max_size.3 b/man/std::u32string_view::max_size.3 new file mode 100644 index 000000000..c3f42d911 --- /dev/null +++ b/man/std::u32string_view::max_size.3 @@ -0,0 +1,66 @@ +.TH std::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::max_size \- std::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; \fI(since C++17)\fP + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::numeric_limits::max() + << " <- numeric_limits::max()\\n" + << std::string_view{}.max_size() + << " <- string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::wstring_view{}.max_size() + << " <- wstring_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n"; + } + +.SH Possible output: + + 9223372036854775807 <- numeric_limits::max() + 4611686018427387899 <- string_view::max_size() + 4611686018427387899 <- basic_string_view::max_size() + 2305843009213693949 <- basic_string_view::max_size() + 1152921504606846974 <- wstring_view::max_size() + 1152921504606846974 <- basic_string_view::max_size() + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + returns the maximum number of characters + max_size \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::npos.3 b/man/std::u32string_view::npos.3 new file mode 100644 index 000000000..c3ba3b575 --- /dev/null +++ b/man/std::u32string_view::npos.3 @@ -0,0 +1,39 @@ +.TH std::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::npos \- std::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); \fI(since C++17)\fP + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Example + + +// Run this code + + #include + + constexpr bool + contains(std::string_view const what, std::string_view const where) noexcept + { + return std::string_view::npos != where.find(what); + } + + int main() + { + using namespace std::literals; + + static_assert(contains("water", "in a bottle of water")); + static_assert(!contains("wine", "in a bottle of champagne")); + static_assert(""sv.npos == "haystack"sv.find("needle")); + } + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI\fI(public static member\fP constant of\fP + std::basic_string) diff --git a/man/std::u32string_view::operator=.3 b/man/std::u32string_view::operator=.3 new file mode 100644 index 000000000..dba80aad4 --- /dev/null +++ b/man/std::u32string_view::operator=.3 @@ -0,0 +1,48 @@ +.TH std::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator= \- std::basic_string_view::operator= + +.SH Synopsis + constexpr basic_string_view& operator=( const basic_string_view& view \fI(since C++17)\fP + ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + assigns values to the string + operator= \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::operator[].3 b/man/std::u32string_view::operator[].3 new file mode 100644 index 000000000..c1d7e55fb --- /dev/null +++ b/man/std::u32string_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator[] \- std::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[]( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Does not throw. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], std::basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string str = "Exemplar"; + std::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + accesses the specified character + operator[] \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::rbegin,.3 b/man/std::u32string_view::rbegin,.3 new file mode 100644 index 000000000..8f17b98bf --- /dev/null +++ b/man/std::u32string_view::rbegin,.3 @@ -0,0 +1,60 @@ +.TH std::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rbegin, \- std::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crbegin() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), std::next(str_view.rbegin(), 3), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), std::next(str_view.crbegin(), 3), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fed + fed + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u32string_view::remove_prefix.3 b/man/std::u32string_view::remove_prefix.3 new file mode 100644 index 000000000..31ef25b47 --- /dev/null +++ b/man/std::u32string_view::remove_prefix.3 @@ -0,0 +1,74 @@ +.TH std::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_prefix \- std::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix( size_type n ); \fI(since C++17)\fP + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::literals; + + [[nodiscard("a pure function")]] + constexpr std::size_t count_substrings(std::string_view hive, std::string_view const bee) + { + if (hive.empty() || bee.empty()) + return 0U; + + std::size_t buzz{}; + while (bee.size() <= hive.size()) + { + const auto pos = hive.find(bee); + if (pos == hive.npos) + break; + ++buzz; + hive.remove_prefix(pos + bee.size()); + } + return buzz; + } + + int main() + { + std::string str = " trim me"; + std::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + + constexpr auto hive{"bee buzz bee buzz bee"}; + std::cout << "There are " << count_substrings(hive, "bee") << " bees in this hive.\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + There are 3 bees in this hive. + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP diff --git a/man/std::u32string_view::remove_suffix.3 b/man/std::u32string_view::remove_suffix.3 new file mode 100644 index 000000000..01bee81f3 --- /dev/null +++ b/man/std::u32string_view::remove_suffix.3 @@ -0,0 +1,51 @@ +.TH std::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_suffix \- std::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); \fI(since C++17)\fP + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP diff --git a/man/std::u32string_view::rend,std::basic_string_view::crend.3 b/man/std::u32string_view::rend,std::basic_string_view::crend.3 new file mode 100644 index 000000000..5f201fac0 --- /dev/null +++ b/man/std::u32string_view::rend,std::basic_string_view::crend.3 @@ -0,0 +1,61 @@ +.TH std::basic_string_view::rend,std::basic_string_view::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rend,std::basic_string_view::crend \- std::basic_string_view::rend,std::basic_string_view::crend + +.SH Synopsis + constexpr const_reverse_iterator rend() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crend() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), str_view.rend(), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), str_view.crend(), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fedcba + fedcba + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::u32string_view::rfind.3 b/man/std::u32string_view::rfind.3 new file mode 100644 index 000000000..684090010 --- /dev/null +++ b/man/std::u32string_view::rfind.3 @@ -0,0 +1,81 @@ +.TH std::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rfind \- std::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind( basic_string_view v, size_type pos = \fB(1)\fP \fI(since C++17)\fP + npos ) const noexcept; + constexpr size_type rfind( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type rfind( const CharT* s, size_type pos, \fB(3)\fP \fI(since C++17)\fP + size_type count ) const; + constexpr size_type rfind( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last occurrence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert(true + && (6 == "AB AB AB"sv.rfind("AB")) + && (6 == "AB AB AB"sv.rfind("ABCD", N, 2)) + && (3 == "AB AB AB"sv.rfind("AB", 5)) + && (0 == "AB CD EF"sv.rfind("AB", 0)) + && (2 == "B AB AB "sv.rfind("AB", 2)) + && (N == "B AB AB "sv.rfind("AB", 1)) + && (5 == "B AB AB "sv.rfind('A')) + && (4 == "AB AB AB"sv.rfind('B', 4)) + && (N == "AB AB AB"sv.rfind('C')) + ); + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::u32string_view::size,std::basic_string_view::length.3 b/man/std::u32string_view::size,std::basic_string_view::length.3 new file mode 100644 index 000000000..8f96ca90c --- /dev/null +++ b/man/std::u32string_view::size,std::basic_string_view::length.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::size,std::basic_string_view::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::size,std::basic_string_view::length \- std::basic_string_view::size,std::basic_string_view::length + +.SH Synopsis + constexpr size_type size() const noexcept; \fI(since C++17)\fP + constexpr size_type length() const noexcept; \fI(since C++17)\fP + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::starts_with.3 b/man/std::u32string_view::starts_with.3 new file mode 100644 index 000000000..9c8fd78c7 --- /dev/null +++ b/man/std::u32string_view::starts_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::starts_with \- std::basic_string_view::starts_with + +.SH Synopsis + constexpr bool starts_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool starts_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool starts_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view begins with the given prefix, where + + 1) the prefix is a string view. Effectively returns basic_string_view(data(), + std::min(size(), sv.size())) == sv. + 2) the prefix is a single character. Effectively returns !empty() && + Traits::eq(front(), ch). + 3) the prefix is a null-terminated character string. Effectively returns + starts_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) starts_with( basic_string_view ) + && "https://cppreference.com"sv.starts_with("http"sv) == true + && "https://cppreference.com"sv.starts_with("ftp"sv) == false + + // (2) starts_with( CharT ) + && "C++20"sv.starts_with('C') == true + && "C++20"sv.starts_with('J') == false + + // (3) starts_with( const CharT* ) + && std::string_view("string_view").starts_with("string") == true + && std::string_view("string_view").starts_with("String") == false + ); + } + +.SH See also + + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::u32string_view::substr.3 b/man/std::u32string_view::substr.3 new file mode 100644 index 000000000..d7edf51b7 --- /dev/null +++ b/man/std::u32string_view::substr.3 @@ -0,0 +1,76 @@ +.TH std::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::substr \- std::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view substr( size_type pos = 0, \fI(since C++17)\fP + size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rlen), where rlen is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rlen). + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + typedef std::size_t count_t, pos_t; + + constexpr std::string_view data{"ABCDEF"}; + + std::cout << data.substr() << '\\n'; // ABCDEF, i.e. data[0, 5] that is [0, 6) + std::cout << data.substr(pos_t(1)) << '\\n'; // BCDEF, i.e. [1, 6) + std::cout << data.substr(pos_t(2), count_t(3)) << '\\n'; // CDE, i.e. [2, 2 + 3) + std::cout << data.substr(pos_t(4), count_t(42)) << '\\n'; // EF, i.e. [4, 6) + + try + { + [[maybe_unused]] + auto sub = data.substr(pos_t(666), count_t(1)); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + ABCDEF + BCDEF + CDE + EF + basic_string_view::substr: __pos (which is 666) > __size (which is 6) + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function of std::basic_string)\fP diff --git a/man/std::u32string_view::swap.3 b/man/std::u32string_view::swap.3 new file mode 100644 index 000000000..c6b397cfe --- /dev/null +++ b/man/std::u32string_view::swap.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::swap \- std::basic_string_view::swap + +.SH Synopsis + constexpr void swap( basic_string_view& v ) noexcept; \fI(since C++17)\fP + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view a = "AAA"; + std::string_view b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swaps the contents + swap \fI(public member function of std::basic_string)\fP + diff --git a/man/std::u32string_view::u32string_view.3 b/man/std::u32string_view::u32string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::u32string_view::u32string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::unary_function.3 b/man/std::unary_function.3 index 031377f3e..5611f9852 100644 --- a/man/std::unary_function.3 +++ b/man/std::unary_function.3 @@ -1,22 +1,25 @@ -.TH std::unary_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unary_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unary_function \- std::unary_function + .SH Synopsis Defined in header - template \fB(deprecated)\fP - struct unary_function; + template< typename ArgumentType, typename ResultType > (deprecated in C++11) + struct unary_function; (removed in C++17) - unary_function is a base class for creating function objects with one argument. + std::unary_function is a base class for creating function objects with one argument. - unary_function does not define operator(); it is expected that derived classes will - define this. unary_function provides only two types - argument_type and result_type - - defined by the template parameters. + std::unary_function does not define operator(); it is expected that derived classes + will define this. std::unary_function provides only two types - argument_type and + result_type - defined by the template parameters. Some standard library function object adaptors, such as std::not1, require the function objects they adapt to have certain types defined; std::not1 requires the function object being adapted to have a type named argument_type. Deriving function - objects that take one argument from unary_function is an easy way to make them + objects that take one argument from std::unary_function is an easy way to make them compatible with those adaptors. - unary_function is deprecated in C++11. + std::unary_function is deprecated in C++11. .SH Member types @@ -26,47 +29,50 @@ .SH Example - + // Run this code #include #include #include #include - + struct less_than_7 : std::unary_function { bool operator()(int i) const { return i < 7; } }; - + int main() { - std::vector v; - for (int i = 0; i < 10; ++i) v.push_back(i); - + std::vector v(10, 7); + v[0] = v[1] = v[2] = 6; + std::cout << std::count_if(v.begin(), v.end(), std::not1(less_than_7())); - - /* C++11 solution: - // Cast to std::function somehow - even with a lambda - std::cout << std::count_if(v.begin(), v.end(), - std::not1(std::function([](int i){ return i < 7; })) - ); - */ + + // C++11 solution: + // Cast to std::function somehow - even with a lambda + // std::cout << std::count_if(v.begin(), v.end(), + // std::not1(std::function([](int i) { return i < 7; }))); } .SH Output: - 3 + 7 .SH See also - function wraps callable object of any type with specified function - \fI(C++11)\fP call signature - \fI(class template)\fP + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function + (C++23) call signature + \fI(class template)\fP ptr_fun creates an adaptor-compatible function object wrapper from - \fB(deprecated)\fP a pointer to function - \fI(function template)\fP + (deprecated in C++11) a pointer to function + (removed in C++17) \fI(function template)\fP pointer_to_unary_function adaptor-compatible wrapper for a pointer to unary function - \fB(deprecated)\fP \fI(class template)\fP + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) binary_function adaptor-compatible binary function base class - \fB(deprecated)\fP \fI(class template)\fP + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) diff --git a/man/std::unary_negate.3 b/man/std::unary_negate.3 index 4dc3504ee..e318f8143 100644 --- a/man/std::unary_negate.3 +++ b/man/std::unary_negate.3 @@ -1,13 +1,18 @@ -.TH std::unary_negate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unary_negate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unary_negate \- std::unary_negate + .SH Synopsis Defined in header template< class Predicate > - struct unary_negate : public \fI(until C++11)\fP + struct unary_negate : public \fI(until C++11)\fP std::unary_function; - template< class Predicate > \fI(since C++11)\fP - struct unary_negate; + \fI(since C++11)\fP + template< class Predicate > (deprecated in + struct unary_negate; C++17) + (removed in C++20) - unary_negate is a wrapper function object returning the complement of the unary + std::unary_negate is a wrapper function object returning the complement of the unary predicate it holds. The unary predicate type must define a member type, argument_type, that is @@ -16,7 +21,7 @@ std::hash, or from another call to std::not1 have this type defined, as are function objects derived from the deprecated std::unary_function. - unary_negate objects are easily constructed with helper function std::not1. + std::unary_negate objects are easily constructed with helper function std::not1. .SH Member types @@ -32,18 +37,18 @@ operator() predicate \fI(public member function)\fP - std::unary_negate::unary_negate +std::unary_negate::unary_negate explicit unary_negate( Predicate const& pred ); \fI(until C++14)\fP - explicit constexpr unary_negate( Predicate const& pred ); \fI(since C++14)\fP + constexpr explicit unary_negate( Predicate const& pred ); \fI(since C++14)\fP - Constructs a unary_negate function object with the stored predicate pred. + Constructs a std::unary_negate function object with the stored predicate pred. .SH Parameters pred - predicate function object - std::unary_negate::operator() +std::unary_negate::operator() bool operator()( argument_type const& x ) const; \fI(until C++14)\fP constexpr bool operator()( argument_type const& x ) const; \fI(since C++14)\fP @@ -60,53 +65,54 @@ .SH Example - + // Run this code #include #include #include #include - + struct less_than_7 : std::unary_function { bool operator()(int i) const { return i < 7; } }; - + int main() { - std::vector v; - for (int i = 0; i < 10; ++i) v.push_back(i); - + std::vector v(7, 7); + v[0] = v[1] = v[2] = 6; + std::unary_negate not_less_than_7((less_than_7())); - + // C++11 solution: + // Use std::function + // std::function not_less_than_7 = + // [](int x)->bool { return !less_than_7()(x); }; + std::cout << std::count_if(v.begin(), v.end(), not_less_than_7); - - /* C++11 solution: - // Use std::function - std::function not_less_than_7 = - [](int x)->bool{ return !less_than_7()(x); }; - - std::cout << std::count_if(v.begin(), v.end(), not_less_than_7); - */ } .SH Output: - 3 + 4 .SH See also - wrapper function object returning the complement of the binary - binary_negate predicate it holds - \fI(class template)\fP - function wraps callable object of any type with specified function call - \fI(C++11)\fP signature - \fI(class template)\fP - not1 constructs custom std::unary_negate object - \fI(function template)\fP - ptr_fun creates an adaptor-compatible function object wrapper from a pointer - \fB(deprecated)\fP to function - \fI(function template)\fP - unary_function adaptor-compatible unary function base class - \fB(deprecated)\fP \fI(class template)\fP + binary_negate wrapper function object returning the complement of the binary + (deprecated in C++17) predicate it holds + (removed in C++20) \fI(class template)\fP + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + not1 constructs custom std::unary_negate object + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) + ptr_fun creates an adaptor-compatible function object wrapper from a + (deprecated in C++11) pointer to function + (removed in C++17) \fI(function template)\fP + unary_function adaptor-compatible unary function base class + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) diff --git a/man/std::uncaught_exception,std::uncaught_exceptions.3 b/man/std::uncaught_exception,std::uncaught_exceptions.3 new file mode 100644 index 000000000..39008539d --- /dev/null +++ b/man/std::uncaught_exception,std::uncaught_exceptions.3 @@ -0,0 +1,115 @@ +.TH std::uncaught_exception,std::uncaught_exceptions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uncaught_exception,std::uncaught_exceptions \- std::uncaught_exception,std::uncaught_exceptions + +.SH Synopsis + Defined in header + bool uncaught_exception() throw(); \fI(until C++11)\fP + \fI(since C++11)\fP + bool uncaught_exception() noexcept; \fB(1)\fP (deprecated in C++17) + (removed in C++20) + int uncaught_exceptions() noexcept; \fB(2)\fP \fI(since C++17)\fP + + 1) Detects if the current thread has a live exception object, that is, an exception + has been thrown or rethrown and not yet entered a matching catch clause, + std::terminate or std::unexpected. In other words, std::uncaught_exception detects + if stack unwinding is currently in progress. + 2) Detects how many exceptions in the current thread have been thrown or rethrown + and not yet entered their matching catch clauses. + + Sometimes it's safe to throw an exception even while std::uncaught_exception() == + true. For example, if stack unwinding causes an object to be destructed, the + destructor for that object could run code that throws an exception as long as the + exception is caught by some catch block before escaping the destructor. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) true if stack unwinding is currently in progress in this thread, false otherwise. + 2) The number of uncaught exception objects in the current thread. + +.SH Notes + + An example where int-returning uncaught_exceptions is used is the boost.log library: + the expression BOOST_LOG(logger) << foo(); first creates a guard object and records + the number of uncaught exceptions in its constructor. The output is performed by the + guard object's destructor unless foo() throws (in which case the number of uncaught + exceptions in the destructor is greater than what the constructor observed). + + std::experimental::scope_fail and std::experimental::scope_success in LFTS v3 rely + on the functionality of uncaught_exceptions, because their destructors need to do + different things that depend on whether is called during stack unwinding. + + Feature-test macro Value Std Feature + __cpp_lib_uncaught_exceptions 201411L \fI(C++17)\fP std::uncaught_exceptions + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo + { + char id{'?'}; + int count = std::uncaught_exceptions(); + + ~Foo() + { + count == std::uncaught_exceptions() + ? std::cout << id << ".~Foo() called normally\\n" + : std::cout << id << ".~Foo() called during stack unwinding\\n"; + } + }; + + int main() + { + Foo f{'f'}; + + try + { + Foo g{'g'}; + std::cout << "Exception thrown\\n"; + throw std::runtime_error("test exception"); + } + catch (const std::exception& e) + { + std::cout << "Exception caught: " << e.what() << '\\n'; + } + } + +.SH Possible output: + + Exception thrown + g.~Foo() called during stack unwinding + Exception caught: test exception + f.~Foo() called normally + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 70 C++98 the exception specification of specified as throw() + uncaught_exception() was missing + +.SH See also + + terminate function called when exception handling fails + \fI(function)\fP + exception_ptr shared pointer type for handling exception objects + \fI(C++11)\fP \fI(typedef)\fP + current_exception captures the current exception in a std::exception_ptr + \fI(C++11)\fP \fI(function)\fP + +.SH External links + + 1. GOTW issue 47: Uncaught Exceptions + 2. Rationale for std::uncaught_exceptions (N4125) diff --git a/man/std::uncaught_exception.3 b/man/std::uncaught_exception.3 deleted file mode 100644 index f7ef6b691..000000000 --- a/man/std::uncaught_exception.3 +++ /dev/null @@ -1,78 +0,0 @@ -.TH std::uncaught_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - bool uncaught_exception(); - - Detects if the current thread has a live exception object, that is, an exception has - been thrown and not yet entered a matching catch clause, std::terminate or - std::unexpected. In other words, std::uncaught_exception detects if stack unwinding - is currently in progress. - - Sometimes it's safe to throw an exception even while std::uncaught_exception() == - true. For example, if stack unwinding causes a stack-allocated object to be - destructed, the destructor for that object could run code that throws an exception - as long as the exception is caught by some catch block before escaping the - destructor. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - true if stack unwinding is currently in progress in this thread. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Example - - -// Run this code - - #include - #include - #include - - struct Foo { - ~Foo() { - if (std::uncaught_exception()) { - std::cout << "~Foo() called during stack unwinding\\n"; - } else { - std::cout << "~Foo() called normally\\n"; - } - } - }; - int main() - { - Foo f; - try { - Foo f; - std::cout << "Exception thrown\\n"; - throw std::runtime_error("test exception"); - } catch (const std::exception& e) { - std::cout << "Exception caught: " << e.what() << '\\n'; - } - } - -.SH Output: - - Exception thrown - ~Foo() called during stack unwinding - Exception caught: test exception - ~Foo() called normally - -.SH See also - - terminate function called when exception handling fails - \fI(function)\fP - exception_ptr shared pointer type for handling exception objects - \fI(C++11)\fP \fI(typedef)\fP - -.SH External links - - GOTW issue 47: Uncaught Exceptions diff --git a/man/std::undeclare_no_pointers.3 b/man/std::undeclare_no_pointers.3 index e21b819c1..636a6046a 100644 --- a/man/std::undeclare_no_pointers.3 +++ b/man/std::undeclare_no_pointers.3 @@ -1,13 +1,17 @@ -.TH std::undeclare_no_pointers 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::undeclare_no_pointers 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::undeclare_no_pointers \- std::undeclare_no_pointers + .SH Synopsis Defined in header - void undeclare_no_pointers( char *p, std::size_t n ) \fI(since C++11)\fP + void undeclare_no_pointers( char *p, std::size_t n ); \fI(since C++11)\fP + (removed in C++23) Unregisters a range earlier registered with std::declare_no_pointers(). .SH Parameters - p - pointer to the beginning of the range previosly registered with + p - pointer to the beginning of the range previously registered with std::declare_no_pointers n - the number of bytes in the range, same value as previously used with std::declare_no_pointers @@ -18,18 +22,10 @@ .SH Exceptions - None - -.SH Example - - This section is incomplete - Reason: no example + Throws nothing. .SH See also declare_no_pointers declares that a memory area does not contain traceable pointers - \fI(C++11)\fP \fI(function)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(function)\fP + (removed in C++23) diff --git a/man/std::undeclare_reachable.3 b/man/std::undeclare_reachable.3 index 8e1cf5f03..104c16d4b 100644 --- a/man/std::undeclare_reachable.3 +++ b/man/std::undeclare_reachable.3 @@ -1,8 +1,11 @@ -.TH std::undeclare_reachable 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::undeclare_reachable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::undeclare_reachable \- std::undeclare_reachable + .SH Synopsis Defined in header - template< class T > \fI(since C++11)\fP - T* undeclare_reachable( T* p ) + template< class T > \fI(since C++11)\fP + T* undeclare_reachable( T* p ); (removed in C++23) Removes the reachable status of the object, referenced by the pointer p, if it was previously set by std::declare_reachable. If the object was declared reachable @@ -22,18 +25,10 @@ .SH Exceptions - None - -.SH Example - - This section is incomplete - Reason: no example + Throws nothing. .SH See also - declare_reachable declares that an object can not be recycled - \fI(C++11)\fP \fI(function)\fP - -.SH Category: - - * Todo no example + declare_reachable declares that an object can not be recycled + \fI(C++11)\fP \fI(function)\fP + (removed in C++23) diff --git a/man/std::underflow_error.3 b/man/std::underflow_error.3 index 6a8b9b80d..fdc23b397 100644 --- a/man/std::underflow_error.3 +++ b/man/std::underflow_error.3 @@ -1,46 +1,113 @@ -.TH std::underflow_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::underflow_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::underflow_error \- std::underflow_error + .SH Synopsis Defined in header class underflow_error; - Defines a type of object to be thrown as exception. It reports errors that arise - because integer value in some computation could not be represented as it had too - large negative value. If the value has floating point type, std::range_error should - be used. + Defines a type of object to be thrown as exception. It may be used to report + arithmetic underflow errors (that is, situations where the result of a computation + is a subnormal floating-point value). + + The standard library components do not throw this exception (mathematical functions + report underflow errors as specified in math_errhandling). Third-party libraries, + however, use this. For example, boost.math throws std::underflow_error if + boost::math::policies::throw_on_error is enabled (the default setting). std-underflow error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP - - + constructor constructs a new underflow_error object with the given message + \fI(public member function)\fP + operator= replaces the underflow_error object + \fI(public member function)\fP - std::underflow_error::underflow_error +std::underflow_error::underflow_error - explicit underflow_error( const std::string& what_arg ); \fB(1)\fP - explicit underflow_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP + underflow_error( const std::string& what_arg ); \fB(1)\fP + underflow_error( const char* what_arg ); \fB(2)\fP + underflow_error( const underflow_error& other ); \fB(3)\fP (noexcept since C++11) - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::underflow_error + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::underflow_error is not permitted to throw exceptions, this + message is typically stored internally as a separately-allocated reference-counted + string. This is also why there is no constructor taking std::string&&: it would have + to copy the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::underflow_error::operator= + + underflow_error& operator=( const underflow_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::underflow_error then std::strcmp(what(), other.what()) == 0 after assignment. + No exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::runtime_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const added + char* was missing + the explanatory strings of they are the same as that of + LWG 471 C++98 std::underflow_error's the + copies were implementation-defined original std::underflow_error + object diff --git a/man/std::underlying_type.3 b/man/std::underlying_type.3 index 7455d5627..f3aaa8213 100644 --- a/man/std::underlying_type.3 +++ b/man/std::underlying_type.3 @@ -1,16 +1,27 @@ -.TH std::underlying_type 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::underlying_type 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::underlying_type \- std::underlying_type + .SH Synopsis Defined in header template< class T > \fI(since C++11)\fP struct underlying_type; - Defines a member typedef type of type that is the underlying type for the - enumeration T. + If T is a complete enumeration \fI(enum)\fP type, provides a member typedef type that + names the underlying type of T. + + Otherwise, the behavior is undefined. \fI(until C++20)\fP + Otherwise, if T is not an enumeration type, there is no member type. + Otherwise (T is an incomplete enumeration type), the program is \fI(since C++20)\fP + ill-formed. + + If the program adds specializations for std::underlying_type, the behavior is + undefined. .SH Member types Name Definition - type the underlying type for T + type the underlying type of T .SH Helper types @@ -21,40 +32,59 @@ Each enumeration type has an underlying type, which can be - 1. Specified explicitly (both scoped and unscoped enumerations) - - 2. Omitted, in which case it is int for scoped enumerations or an - implementation-defined integral type capable of representing all values of the enum - (for unscoped enumerations) + 1. Specified explicitly (both scoped and unscoped enumerations); + 2. Omitted, in which case it is int for scoped enumerations or an + implementation-defined integral type capable of representing all values of the + enum (for unscoped enumerations). .SH Example - + // Run this code #include #include - + enum e1 {}; - enum class e2: int {}; - - int main() { - bool e1_type = std::is_same< - unsigned - ,typename std::underlying_type::type - >::value; - - bool e2_type = std::is_same< - int - ,typename std::underlying_type::type - >::value; - + enum class e2 {}; + enum class e3 : unsigned {}; + enum class e4 : int {}; + + int main() + { + constexpr bool e1_t = std::is_same_v, int>; + constexpr bool e2_t = std::is_same_v, int>; + constexpr bool e3_t = std::is_same_v, int>; + constexpr bool e4_t = std::is_same_v, int>; + std::cout - << "underlying type for 'e1' is " << (e1_type?"unsigned":"non-unsigned") << '\\n' - << "underlying type for 'e2' is " << (e2_type?"int":"non-int") << '\\n'; + << "underlying type for 'e1' is " << (e1_t ? "int" : "non-int") << '\\n' + << "underlying type for 'e2' is " << (e2_t ? "int" : "non-int") << '\\n' + << "underlying type for 'e3' is " << (e3_t ? "int" : "non-int") << '\\n' + << "underlying type for 'e4' is " << (e4_t ? "int" : "non-int") << '\\n'; } -.SH Output: +.SH Possible output: - underlying type for 'e1' is unsigned + underlying type for 'e1' is non-int underlying type for 'e2' is int + underlying type for 'e3' is non-int + underlying type for 'e4' is int + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2396 C++11 incomplete enumeration types were complete enumeration type + allowed required + +.SH See also + + is_enum checks if a type is an enumeration type + \fI(C++11)\fP \fI(class template)\fP + is_scoped_enum checks if a type is a scoped enumeration type + (C++23) \fI(class template)\fP + to_underlying converts an enumeration to its underlying type + (C++23) \fI(function template)\fP diff --git a/man/std::unexpect_t,std::unexpect.3 b/man/std::unexpect_t,std::unexpect.3 new file mode 100644 index 000000000..8aea9c426 --- /dev/null +++ b/man/std::unexpect_t,std::unexpect.3 @@ -0,0 +1,34 @@ +.TH std::unexpect_t,std::unexpect 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unexpect_t,std::unexpect \- std::unexpect_t,std::unexpect + +.SH Synopsis + Defined in header + struct unexpect_t { + + explicit unexpect_t() = default; \fB(1)\fP (since C++23) + + }; + inline constexpr unexpect_t unexpect{}; \fB(2)\fP (since C++23) + + 1) A tag type for in-place construction of an unexpected value in an std::expected + object. + 2) A constant of type const std::unexpect_t which is usually directly passed to a + constructor of std::expected to construct an unexpected value. + +.SH Notes + + Like other construction tag types, unexpect_t is a trivial, empty class with an + explicit default constructor. + +.SH See also + + constructor constructs the expected object + \fI(public member function)\fP + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP diff --git a/man/std::unexpected.3 b/man/std::unexpected.3 index 76cfb0bf8..acb365342 100644 --- a/man/std::unexpected.3 +++ b/man/std::unexpected.3 @@ -1,36 +1,216 @@ -.TH std::unexpected 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unexpected 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unexpected \- std::unexpected + .SH Synopsis - Defined in header - void unexpected(); \fI(until C++11)\fP - \fB(deprecated)\fP - [[noreturn]] void unexpected(); \fI(since C++11)\fP - \fB(deprecated)\fP + Defined in header + template< class E > (since C++23) + class unexpected; - std::unexpected() is called by the C++ runtime when a dynamic exception - specification is violated: an exception is thrown from a function whose exception - specification forbids exceptions of this type. + The class template std::unexpected represents an unexpected value stored in + std::expected. In particular, std::expected has constructors with std::unexpected as + a single argument, which creates an expected object that contains an unexpected + value. - std::unexpected() may also be called directly from the program. + A program is ill-formed if it instantiates an unexpected with a non-object type, an + array type, a specialization of std::unexpected, or a cv-qualified type. - In either case, std::unexpected calls the currently installed - std::unexpected_handler. The default std::unexpected_handler calls std::terminate. +.SH Template parameters -.SH Parameters + E - the type of the unexpected value. The type must not be an array type, a + non-object type, a specialization of std::unexpected, or a cv-qualified type. + +.SH Member functions + + constructor constructs the unexpected object + (C++23) \fI(public member function)\fP + destructor destroys the unexpected object, along with the stored + (implicitly declared) (C++23) value + \fI(public member function)\fP + operator= assigns the stored value + (implicitly declared) (C++23) \fI(public member function)\fP + error accesses the stored value + (C++23) \fI(public member function)\fP + swap swaps the stored value + (C++23) \fI(public member function)\fP + +.SH Non-member functions + + operator== compares the stored value + (C++23) \fI(function template)\fP + swap(std::unexpected) specializes the std::swap algorithm + (C++23) \fI(function template)\fP + +std::unexpected::unexpected - \fI(none)\fP + constexpr unexpected( const unexpected& ) = default; \fB(1)\fP (since C++23) + constexpr unexpected( unexpected&& ) = default; \fB(2)\fP (since C++23) + template< class Err = E > \fB(3)\fP (since C++23) + constexpr explicit unexpected( Err&& e ); + template< class... Args > \fB(4)\fP (since C++23) + constexpr explicit unexpected( std::in_place_t, Args&&... args ); + template< class U, class... Args > -.SH Return value + constexpr explicit unexpected( std::in_place_t, \fB(5)\fP (since C++23) - \fI(none)\fP + std::initializer_list il, + Args&&... args ); + + Constructs a std::unexpected object. + + 1,2) Copy/move constructor. Copies or moves the stored value, respectively. + 3) Constructs the stored value, as if by direct-initializing a value of type E from + std::forward(e). + * This overload participates in overload resolution only if + * std::is_same_v, unexpected> is false, and + * std::is_same_v, std::in_place_t> is false, and + * std::is_constructible_v is true. + 4) Constructs the stored value, as if by direct-initializing a value of type E from + the arguments std::forward(args).... + * This overload participates in overload resolution only if + std::is_constructible_v is true. + 5) Constructs the stored value, as if by direct-initializing a value of type E from + the arguments il, std::forward(args).... + * This overload participates in overload resolution only if + std::is_constructible_v&, Args...> is true. + +.SH Parameters + + e - value with which to initialize the contained value + args... - arguments with which to initialize the contained value + il - initializer list with which to initialize the contained value .SH Exceptions - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Throws any exception thrown by the constructor of E. + +std::unexpected::error + + constexpr const E& error() const& noexcept; + + constexpr E& error() & noexcept; (since C++23) + constexpr const E&& error() const&& noexcept; + + constexpr E&& error() && noexcept; + + Returns a reference to the stored value. + +std::unexpected::swap + + constexpr void swap( unexpected& other ) (since C++23) + noexcept(std::is_nothrow_swappable_v); + + Swaps the stored values, as if by using std::swap; swap(error(), other.error());. + + The program is ill-formed if std::is_swappable_v is false. + +operator==(std::unexpected) + + template< class E2 > + friend constexpr bool operator==( unexpected& x, std::unexpected& (since C++23) + y ); + + Compares the stored values, as if by return x.error() == y.error(). + + If the expression x.error() == e.error() is not well-formed, or if its result is not + convertible to bool, the program is ill-formed. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::unexpected is an associated + class of the arguments. + +swap(std::unexpected) + + friend constexpr void (since C++23) + swap( unexpected& x, unexpected& y ) noexcept(noexcept(x.swap(y))); + + Equivalent to x.swap(y). + + This overload participates in overload resolution only if std::is_swappable_v is + true. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::unexpected is an associated + class of the arguments. + + Deduction guides + + template< class E > (since C++23) + unexpected(E) -> unexpected; + + The deduction guide is provided for unexpected to allow deduction from the + constructor argument. + +.SH Notes + + Prior to C++17, the name std::unexpected denoted the function called by the C++ + runtime when a dynamic exception specification was violated. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::expected ex = std::unexpected(3); + + if (!ex) + std::cout << "ex contains an error value\\n"; + + if (ex == std::unexpected(3)) + std::cout << "The error value is equal to 3\\n"; + } + +.SH Output: + + ex contains an error value + The error value is equal to 3 + + Example with enum + + +// Run this code + + #include + #include + + enum class error + { + compile_time_error, + runtime_error + }; + + [[nodiscard]] auto unexpected_runtime_error() -> std::expected + { + return std::unexpected(error::runtime_error); + } + + int main() + { + const auto e = unexpected_runtime_error(); + + e.and_then([](const auto& e) -> std::expected { + std::cout << "and_then: " << int(e); // not printed + return {}; + }).or_else([](const auto& e) -> std::expected { + std::cout << "or_else: " << int(e); // prints this line + return {}; + }); + + return 0; + } + +.SH Output: + + or_else: 1 .SH See also - unexpected_handler the type of the function called by std::unexpected - \fB(deprecated)\fP \fI(typedef)\fP + constructor constructs the expected object + \fI(public member function)\fP + operator== compares expected objects + (C++23) \fI(function template)\fP diff --git a/man/std::unexpected_handler.3 b/man/std::unexpected_handler.3 index e2a31f71a..31afb813e 100644 --- a/man/std::unexpected_handler.3 +++ b/man/std::unexpected_handler.3 @@ -1,7 +1,11 @@ -.TH std::unexpected_handler 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unexpected_handler 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unexpected_handler \- std::unexpected_handler + .SH Synopsis Defined in header - typedef void (*unexpected_handler)(); \fB(deprecated)\fP + typedef void (*unexpected_handler)(); (deprecated in C++11) + (removed in C++17) std::unexpected_handler is the function pointer type (pointer to function that takes no arguments and returns void), which is installed and queried by the functions @@ -31,9 +35,10 @@ .SH See also - unexpected function called when dynamic exception specification is violated - \fB(deprecated)\fP \fI(function)\fP - set_unexpected changes the function to be called by std::unexpected - \fB(deprecated)\fP \fI(function)\fP - get_unexpected obtains the current unexpected_handler - \fI(C++11)\fP\fB(deprecated)\fP \fI(function)\fP + unexpected function called when dynamic exception specification is + (removed in C++17) violated + \fI(function)\fP + set_unexpected changes the function to be called by std::unexpected + (removed in C++17) \fI(function)\fP + get_unexpected obtains the current unexpected_handler + \fI(C++11)\fP(removed in C++17) \fI(function)\fP diff --git a/man/std::ungetc.3 b/man/std::ungetc.3 index 5d8b77d08..7c4776e38 100644 --- a/man/std::ungetc.3 +++ b/man/std::ungetc.3 @@ -1,13 +1,40 @@ -.TH std::ungetc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ungetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ungetc \- std::ungetc + .SH Synopsis Defined in header int ungetc( int ch, std::FILE *stream ); - Puts the character ch back to the given file stream. + If ch does not equal EOF, pushes the character ch (reinterpreted as unsigned char) + into the input buffer associated with the stream stream in such a manner than + subsequent read operation from stream will retrieve that character. The external + device associated with the stream is not modified. + + Stream repositioning operations std::fseek, std::fsetpos, and std::rewind discard + the effects of ungetc. + + If ungetc is called more than once without an intervening read or repositioning, it + may fail (in other words, a pushback buffer of size 1 is guaranteed, but any larger + buffer is implementation-defined). If multiple successful ungetc were performed, + read operations retrieve the pushed-back characters in reverse order of ungetc + + If ch equals EOF, the operation fails and the stream is not affected. + + A successful call to ungetc clears the end of file status flag std::feof. + + A successful call to ungetc on a binary stream decrements the stream position + indicator by one (the behavior is indeterminate if the stream position indicator was + zero). + + A successful call to ungetc on a text stream modifies the stream position indicator + in unspecified manner but guarantees that after all pushed-back characters are + retrieved with a read operation, the stream position indicator is equal to its value + before ungetc. .SH Parameters - ch - character to be put back + ch - character to be pushed into the input stream buffer stream - file stream to put the character back to .SH Return value @@ -16,9 +43,73 @@ On failure EOF is returned and the given stream remains unchanged. +.SH Notes + + The size of the pushback buffer varies in practice from 4k (Linux, MacOS) to as + little as 4 (Solaris) or the guaranteed minimum 1 (HPUX, AIX). + + The apparent size of the pushback buffer may be larger if the character that is + pushed back equals the character existing at that location in the external character + sequence (the implementation may simply decrement the read file position indicator + and avoid maintaining a pushback buffer). + +.SH Example + + demonstrates the use of std::ungetc in its original purpose: implementing std::scanf + + +// Run this code + + #include + #include + + void demo_scanf(const char* fmt, std::FILE* s) + { + while (*fmt != '\\0') { + if (*fmt == '%') { + switch (*++fmt) { + case 'u': { + int c{}; + while (std::isspace(c=std::getc(s))) {} + unsigned int num{}; + while (std::isdigit(c)) { + num = num*10 + c-'0'; + c = std::getc(s); + } + std::printf("%%u scanned %u\\n", num); + std::ungetc(c, s); + break; + } + case 'c': { + int c = std::getc(s); + std::printf("%%c scanned '%c'\\n", c); + break; + } + } + } else { + ++fmt; + } + } + } + + int main() + { + if (std::FILE* f = std::fopen("input.txt", "w+")) { + std::fputs("123x", f); + std::rewind(f); + demo_scanf("%u%c", f); + std::fclose(f); + } + } + +.SH Output: + + %u scanned 123 + %c scanned 'x' + .SH See also fgetc gets a character from a file stream - getc \fI(function)\fP + getc \fI(function)\fP C documentation for ungetc diff --git a/man/std::ungetwc.3 b/man/std::ungetwc.3 index 203c768ab..20d6067eb 100644 --- a/man/std::ungetwc.3 +++ b/man/std::ungetwc.3 @@ -1,10 +1,33 @@ -.TH std::ungetwc 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ungetwc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ungetwc \- std::ungetwc + .SH Synopsis Defined in header - wint_t ungetwc( wint_t ch, std::FILE* stream ); + std::wint_t ungetwc( std::wint_t ch, std::FILE* stream ); + + If ch does not equal WEOF, pushes the wide character ch into the input buffer + associated with the stream stream in such a manner than subsequent read operation + from stream will retrieve that wide character. The external device associated with + the stream is not modified. + + Stream repositioning operations std::fseek, std::fsetpos, and std::rewind discard + the effects of std::ungetwc. + + If std::ungetwc is called more than once without an intervening read or + repositioning, it may fail (in other words, a pushback buffer of size 1 is + guaranteed, but any larger buffer is implementation-defined). If multiple successful + std::ungetwc were performed, read operations retrieve the pushed-back wide + characters in reverse order of std::ungetwc + + If ch equals WEOF, the operation fails and the stream is not affected. + + A successful call to std::ungetwc clears the end of file status flag feof. - Puts the wide character ch back to the given file stream. Only one wide character - pushback is guaranteed. + A successful call to std::ungetwc on a stream (whether text or binary) modifies the + stream position indicator in unspecified manner but guarantees that after all + pushed-back wide characters are retrieved with a read operation, the stream position + indicator is equal to its value before std::ungetwc. .SH Parameters @@ -20,8 +43,8 @@ .SH See also ungetc puts a character back into a file stream - \fI(function)\fP + \fI(function)\fP fgetwc gets a wide character from a file stream - getwc \fI(function)\fP + getwc \fI(function)\fP C documentation for ungetwc diff --git a/man/std::uniform_int_distribution.3 b/man/std::uniform_int_distribution.3 index acf11b57a..87630a61b 100644 --- a/man/std::uniform_int_distribution.3 +++ b/man/std::uniform_int_distribution.3 @@ -1,69 +1,88 @@ -.TH std::uniform_int_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution \- std::uniform_int_distribution + .SH Synopsis Defined in header template< class IntType = int > \fI(since C++11)\fP class uniform_int_distribution; - Produces random integer values i, uniformly distributed on the closed interval [a, - b], that is, distributed according to the discrete probability function + Produces random integer values \\(\\small i\\)i, uniformly distributed on the closed + interval \\(\\small[a, b]\\)[a, b], that is, distributed according to the discrete + probability function - P(i|a,b) = + \\({\\small P(i|a,b) =}\\frac{1}{b - a + 1}\\)P(i|a,b) = 1 b − a + 1 . + std::uniform_int_distribution satisfies all requirements of + RandomNumberDistribution. + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + IntType - this is not one of short, int, long, long long, unsigned short, unsigned + int, unsigned long, or unsigned long long. + .SH Member types - Member type Definition - result_type IntType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP IntType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics a returns the distribution parameters - b \fI(public member function)\fP + b \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example This program simulates throwing 6-sided dice. - + // Run this code - #include #include - + #include + int main() { - std::random_device rd; - std::mt19937 gen(rd()); - std::uniform_int_distribution<> dis(1, 6); - - for (int n=0; n<10; ++n) - std::cout << dis(gen) << ' '; + std::random_device rd; // a seed source for the random number engine + std::mt19937 gen(rd()); // mersenne_twister_engine seeded with rd() + std::uniform_int_distribution<> distrib(1, 6); + + // Use distrib to transform the random unsigned int + // generated by gen into an int in [1, 6] + for (int n = 0; n != 10; ++n) + std::cout << distrib(gen) << ' '; std::cout << '\\n'; } diff --git a/man/std::uniform_int_distribution::a,b.3 b/man/std::uniform_int_distribution::a,b.3 index c6ddb8a74..10e6eb513 100644 --- a/man/std::uniform_int_distribution::a,b.3 +++ b/man/std::uniform_int_distribution::a,b.3 @@ -1,4 +1,7 @@ -.TH std::uniform_int_distribution::a,b 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution::a,b 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::a,b \- std::uniform_int_distribution::a,b + .SH Synopsis result_type a() const; \fB(1)\fP \fI(since C++11)\fP result_type b() const; \fB(2)\fP \fI(since C++11)\fP @@ -8,7 +11,7 @@ 1) Returns the a distribution parameter. It defines the minimum possibly generated value. The default value is 0. 2) Returns the b distribution parameter. It defines the maximum possibly generated - value. The default value is std::numeric_limits::max() + value. The default value is std::numeric_limits::max(). .SH Parameters @@ -21,5 +24,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::uniform_int_distribution::max.3 b/man/std::uniform_int_distribution::max.3 index 6b904f49c..94cab0e58 100644 --- a/man/std::uniform_int_distribution::max.3 +++ b/man/std::uniform_int_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::uniform_int_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::max \- std::uniform_int_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::uniform_int_distribution::min.3 b/man/std::uniform_int_distribution::min.3 index a74166d68..64d466c8c 100644 --- a/man/std::uniform_int_distribution::min.3 +++ b/man/std::uniform_int_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::uniform_int_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::min \- std::uniform_int_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::uniform_int_distribution::operator().3 b/man/std::uniform_int_distribution::operator().3 index 447da6dda..5a947fdf3 100644 --- a/man/std::uniform_int_distribution::operator().3 +++ b/man/std::uniform_int_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::uniform_int_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::operator() \- std::uniform_int_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::uniform_int_distribution::param.3 b/man/std::uniform_int_distribution::param.3 index 242a88c6a..fc6fbf515 100644 --- a/man/std::uniform_int_distribution::param.3 +++ b/man/std::uniform_int_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::uniform_int_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::param \- std::uniform_int_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::uniform_int_distribution::reset.3 b/man/std::uniform_int_distribution::reset.3 new file mode 100644 index 000000000..b72983d41 --- /dev/null +++ b/man/std::uniform_int_distribution::reset.3 @@ -0,0 +1,22 @@ +.TH std::uniform_int_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::reset \- std::uniform_int_distribution::reset + +.SH Synopsis + void reset(); \fI(since C++11)\fP + + Resets the internal state of the distribution object. After a call to this function, + the next call to operator() on the distribution object will not be dependent on + previous calls to operator(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. diff --git a/man/std::uniform_int_distribution::uniform_int_distribution.3 b/man/std::uniform_int_distribution::uniform_int_distribution.3 index 1e0cd568b..9114f75a4 100644 --- a/man/std::uniform_int_distribution::uniform_int_distribution.3 +++ b/man/std::uniform_int_distribution::uniform_int_distribution.3 @@ -1,18 +1,31 @@ -.TH std::uniform_int_distribution::uniform_int_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_int_distribution::uniform_int_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_int_distribution::uniform_int_distribution \- std::uniform_int_distribution::uniform_int_distribution + .SH Synopsis - explicit uniform_int_distribution( IntType a = 0, - IntType b = \fB(1)\fP \fI(since C++11)\fP + uniform_int_distribution() : uniform_int_distribution\fB(0)\fP { } \fB(1)\fP \fI(since C++11)\fP + explicit uniform_int_distribution( IntType a, + IntType b = \fB(2)\fP \fI(since C++11)\fP std::numeric_limits::max() ); - explicit uniform_int_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + explicit uniform_int_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs new distribution object. - Constructs new distribution object. The first version uses a and b as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses a and b as the distribution parameters. + 3) Uses params as the distribution parameters. - The behavior is undefined if a>b. + The behavior is undefined if a > b. .SH Parameters a - the a distribution parameter (minimum value) b - the b distribution parameter (maximum value) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::uniform_random_bit_generator.3 b/man/std::uniform_random_bit_generator.3 new file mode 100644 index 000000000..f05f59bbc --- /dev/null +++ b/man/std::uniform_random_bit_generator.3 @@ -0,0 +1,35 @@ +.TH std::uniform_random_bit_generator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_random_bit_generator \- std::uniform_random_bit_generator + +.SH Synopsis + Defined in header + template< class G > + + concept uniform_random_bit_generator = + std::invocable && + std::unsigned_integral> && + requires { \fI(since C++20)\fP + { G::min() } -> std::same_as>; + { G::max() } -> std::same_as>; + requires std::bool_constant<(G::min() < G::max())>::value; + + }; + + The concept uniform_random_bit_generator specifies that G is the type of a + uniform random bit generator, that is, objects of type G is a function object + returning unsigned integer values such that each value in the range of possible + results has (ideally) equal probability of being returned. + + Semantic requirements + + uniform_random_bit_generator is modeled only if, given any object g of type G: + + * g() is in the range [G::min(), G::max()], + * g() has amortized constant complexity. + +.SH Notes + + In order to satisfy the requirement std::bool_constant<(G::min() < + G::max())>::value, both G::min() and G::max() must be constant expressions, and the + result of the comparison must be true. diff --git a/man/std::uniform_real_distribution.3 b/man/std::uniform_real_distribution.3 index 78cc432a4..3702661f7 100644 --- a/man/std::uniform_real_distribution.3 +++ b/man/std::uniform_real_distribution.3 @@ -1,72 +1,106 @@ -.TH std::uniform_real_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution \- std::uniform_real_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP class uniform_real_distribution; - Produces random floating-point values i, uniformly distributed on the interval [a, - b), that is, distributed according to the probability function: + Produces random floating-point values \\(\\small x\\)x, uniformly distributed on the + interval \\(\\small [a, b)\\)[a, b), that is, distributed according to the probability + density function: - P(i|a,b) = + \\({\\small P(x|a,b) =} \\frac{1}{b-a}\\)P(x|a,b) = 1 b − a . + std::uniform_real_distribution satisfies all requirements of + RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. + .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type\fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics a returns the distribution parameters - b \fI(public member function)\fP + b \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP + +.SH Notes + + It is difficult to create a distribution over the closed interval \\(\\small[a, + b]\\)[a, b] from this distribution. Using std::nextafter(b, + std::numeric_limits::max()) as the second parameter does not always work + due to rounding error. + + Most existing implementations have a bug where they may occasionally return \\(\\small + b\\)b (GCC #63176 LLVM #18767 MSVC STL #1074). This was originally only thought to + happen when RealType is float and when LWG issue 2524 is present, but it has since + been shown that neither is required to trigger the bug. .SH Example - print 10 random numbers between 1 and 2 + Print 10 random numbers between 1 and 2. + - // Run this code - #include #include - + #include + int main() { - std::random_device rd; - std::mt19937 gen(rd()); - std::uniform_real_distribution<> dis(1, 2); - for (int n = 0; n < 10; ++n) { + std::random_device rd; // Will be used to obtain a seed for the random number engine + std::mt19937 gen(rd()); // Standard mersenne_twister_engine seeded with rd() + std::uniform_real_distribution<> dis(1.0, 2.0); + for (int n = 0; n < 10; ++n) + // Use dis to transform the random unsigned int generated by gen into a + // double in [1, 2). Each call to dis(gen) generates a new random double. std::cout << dis(gen) << ' '; - } std::cout << '\\n'; } -.SH Output: +.SH Possible output: 1.80829 1.15391 1.18483 1.38969 1.36094 1.0648 1.97798 1.27984 1.68261 1.57326 + +.SH External links + + Drawing random floating-point numbers from an interval — © 2022. Frédéric Goualard, + Université de Nantes. diff --git a/man/std::uniform_real_distribution::a,b.3 b/man/std::uniform_real_distribution::a,b.3 index 020a20fa6..122c3b646 100644 --- a/man/std::uniform_real_distribution::a,b.3 +++ b/man/std::uniform_real_distribution::a,b.3 @@ -1,4 +1,7 @@ -.TH std::uniform_real_distribution::a,b 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::a,b 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::a,b \- std::uniform_real_distribution::a,b + .SH Synopsis result_type a() const; \fB(1)\fP \fI(since C++11)\fP result_type b() const; \fB(2)\fP \fI(since C++11)\fP @@ -8,7 +11,7 @@ 1) Returns the a distribution parameter. It defines the minimum possibly generated value. The default value is 0.0. 2) Returns the b distribution parameter. It defines the maximum possibly generated - value. The default value is 1.0 + value. The default value is 1.0. .SH Parameters @@ -21,5 +24,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::uniform_real_distribution::max.3 b/man/std::uniform_real_distribution::max.3 index 29bc93f17..ee468cffc 100644 --- a/man/std::uniform_real_distribution::max.3 +++ b/man/std::uniform_real_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::uniform_real_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::max \- std::uniform_real_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::uniform_real_distribution::min.3 b/man/std::uniform_real_distribution::min.3 index 777bb96fa..583b9a7e6 100644 --- a/man/std::uniform_real_distribution::min.3 +++ b/man/std::uniform_real_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::uniform_real_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::min \- std::uniform_real_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::uniform_real_distribution::operator().3 b/man/std::uniform_real_distribution::operator().3 index 57fea3855..3d2d3b9b1 100644 --- a/man/std::uniform_real_distribution::operator().3 +++ b/man/std::uniform_real_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::uniform_real_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::operator() \- std::uniform_real_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::uniform_real_distribution::param.3 b/man/std::uniform_real_distribution::param.3 index 7d1159a5e..705f3b337 100644 --- a/man/std::uniform_real_distribution::param.3 +++ b/man/std::uniform_real_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::uniform_real_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::param \- std::uniform_real_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::uniform_real_distribution::reset.3 b/man/std::uniform_real_distribution::reset.3 index b40ad8d80..6752477b1 100644 --- a/man/std::uniform_real_distribution::reset.3 +++ b/man/std::uniform_real_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::uniform_real_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::reset \- std::uniform_real_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::uniform_real_distribution::uniform_real_distribution.3 b/man/std::uniform_real_distribution::uniform_real_distribution.3 index c22fd6b3e..f52941249 100644 --- a/man/std::uniform_real_distribution::uniform_real_distribution.3 +++ b/man/std::uniform_real_distribution::uniform_real_distribution.3 @@ -1,12 +1,17 @@ -.TH std::uniform_real_distribution::uniform_real_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uniform_real_distribution::uniform_real_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uniform_real_distribution::uniform_real_distribution \- std::uniform_real_distribution::uniform_real_distribution + .SH Synopsis - explicit uniform_real_distribution( RealType a = 0.0, RealType b = \fB(1)\fP \fI(since C++11)\fP - 1.0 ); - explicit uniform_real_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + uniform_real_distribution() : uniform_real_distribution(0.0) { } \fB(1)\fP \fI(since C++11)\fP + explicit uniform_real_distribution( RealType a, RealType b = 1.0 \fB(2)\fP \fI(since C++11)\fP + ); + explicit uniform_real_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs new distribution object. The first version uses a and b as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses a and b as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters @@ -16,7 +21,18 @@ .SH Notes - Requires that a ≤ b and b-a ≤ std::numeric_limits::max() + Requires that a ≤ b and b - a ≤ std::numeric_limits::max(). + + If a == b, subsequent calls to the operator() overload that does not accept a + param_type object will cause undefined behavior. To create a distribution over the closed interval [a,b], std::nextafter(b, std::numeric_limits::max()) may be used as the second parameter. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::uninitialized_construct_using_allocator.3 b/man/std::uninitialized_construct_using_allocator.3 new file mode 100644 index 000000000..e6867b7a9 --- /dev/null +++ b/man/std::uninitialized_construct_using_allocator.3 @@ -0,0 +1,58 @@ +.TH std::uninitialized_construct_using_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_construct_using_allocator \- std::uninitialized_construct_using_allocator + +.SH Synopsis + Defined in header + template< class T, class Alloc, class... Args > + + constexpr T* uninitialized_construct_using_allocator( T* p, + const Alloc& \fI(since C++20)\fP + alloc, + + Args&&... args + ); + + Creates an object of the given type T by means of uses-allocator construction at the + uninitialized memory location indicated by p. + + Equivalent to + + return std::apply( + [&](Xs&&...xs) + { + return std::construct_at(p, std::forward(xs)...); + }, + std::uses_allocator_construction_args(alloc, std::forward(args)...)); + +.SH Parameters + + p - the memory location where the object will be placed + alloc - the allocator to use + args - the arguments to pass to T's constructor + +.SH Return value + + Pointer to the newly-created object of type T. + +.SH Exceptions + + May throw any exception thrown by the constructor of T, typically including + std::bad_alloc. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + uses_allocator checks if the specified type supports uses-allocator + \fI(C++11)\fP construction + \fI(class template)\fP + make_obj_using_allocator creates an object of the given type by means of + (C++20) uses-allocator construction + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::uninitialized_copy.3 b/man/std::uninitialized_copy.3 index 4a1abb6c8..650b75d69 100644 --- a/man/std::uninitialized_copy.3 +++ b/man/std::uninitialized_copy.3 @@ -1,22 +1,64 @@ -.TH std::uninitialized_copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uninitialized_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_copy \- std::uninitialized_copy + .SH Synopsis Defined in header - template< class InputIt, class ForwardIt > - ForwardIt uninitialized_copy( InputIt first, InputIt last, ForwardIt d_first ); + template< class InputIt, class NoThrowForwardIt > + + NoThrowForwardIt uninitialized_copy( InputIt first, InputIt last, \fB(1)\fP + + NoThrowForwardIt d_first ); + template< class ExecutionPolicy, class ForwardIt, class + NoThrowForwardIt > + + NoThrowForwardIt uninitialized_copy( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt + last, + + NoThrowForwardIt d_first ); + + 1) Copies elements from the range [first, last) to an uninitialized memory area + beginning at d_first as if by for (; first != last; ++d_first, (void) ++first) + ::new (/* VOIDIFY */(*d_first)) + typename std::iterator_traits::value_type(*first); + where /* VOIDIFY */(e) is: - Copies elements from the range [first, last) to an uninitialized memory area - beginning at d_first. The elements in the uninitialized area are constructed using - copy constructor. + static_cast(&e) \fI(until C++11)\fP + static_cast(std::addressof(e)) \fI(since C++11)\fP + + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + + If d_first + [0, std::distance(first, last)) overlaps with \fI(since C++20)\fP + [first, last), the behavior is undefined. + + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first, last - the range of the elements to copy - d_first - the beginning of the destination range + first, last - the range of the elements to copy + d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for + details. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + NoThrowForwardIt must meet the requirements of LegacyForwardIterator. - - ForwardIt must meet the requirements of ForwardIterator. + No increment, assignment, comparison, or indirection through valid instances of + NoThrowForwardIt may throw exceptions. + Applying &* to a NoThrowForwardIt value must yield a pointer to its value type. + \fI(until C++11)\fP .SH Return value @@ -24,62 +66,103 @@ .SH Complexity - Linear in the distance between first and last + Linear in the distance between first and last. -.SH Possible implementation +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. - template - ForwardIt uninitialized_copy(InputIt first, InputIt last, ForwardIt d_first) - { - typedef typename std::iterator_traits::value_type Value; - for (; first != last; ++first, ++d_first) { - ::new (static_cast(&*d_first)) Value(*first); - } - return d_first; - } +.SH Possible implementation - This section is incomplete - Reason: The above implementation is only valid if constructing the Value does not - throw. If it throws, then all previously constructed objects must be destructed. +template +NoThrowForwardIt uninitialized_copy(InputIt first, InputIt last, NoThrowForwardIt d_first) +{ + using T = typename std::iterator_traits::value_type; + NoThrowForwardIt current = d_first; + try + { + for (; first != last; ++first, (void) ++current) + ::new (static_cast(std::addressof(*current))) T(*first); + return current; + } + catch (...) + { + for (; d_first != current; ++d_first) + d_first->~T(); + throw; + } +} .SH Example - + // Run this code - #include + #include #include #include #include - #include - + int main() { - std::vector v = {"This", "is", "an", "example"}; - - std::string* p; - std::size_t sz; - std::tie(p, sz) = std::get_temporary_buffer(v.size()); - sz = std::min(sz, v.size()); - - std::uninitialized_copy(v.begin(), v.begin() + sz, p); - - for (std::string* i = p; i != p+sz; ++i) { - std::cout << *i << ' '; - i->~basic_string(); + const char *v[] = {"This", "is", "an", "example"}; + + auto sz = std::size(v); + + if (void *pbuf = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz)) + { + try + { + auto first = static_cast(pbuf); + auto last = std::uninitialized_copy(std::begin(v), std::end(v), first); + + for (auto it = first; it != last; ++it) + std::cout << *it << '_'; + std::cout << '\\n'; + + std::destroy(first, last); + } + catch (...) {} + std::free(pbuf); } - std::return_temporary_buffer(p); } .SH Output: - This is an example + This_is_an_example_ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + given T as the value type of + LWG 866 C++98 NoThrowForwardIt, if uses global replacement- + T::operator new exists, the program new instead + might be ill-formed + the effect description used a for loop + with the iteration discards the value + LWG 2133 C++98 expression ++d_first, ++first, which of one operand + results to disable that ADL + in an argument-dependent lookup of + operator, + LWG 2433 C++11 this algorithm might be hijacked by uses std::addressof + overloaded operator& + LWG 3870 C++20 this algorithm might create objects on kept disallowed + a const storage .SH See also - uninitialized_copy_n copies a number of objects to an uninitialized area of memory - \fI(C++11)\fP \fI(function template)\fP - -.SH Category: - - * Todo with reason + uninitialized_copy_n copies a number of objects to an uninitialized area of + \fI(C++11)\fP memory + \fI(function template)\fP + ranges::uninitialized_copy copies a range of objects to an uninitialized area of + (C++20) memory + (niebloid) diff --git a/man/std::uninitialized_copy_n.3 b/man/std::uninitialized_copy_n.3 index 86ab37979..5ada428b1 100644 --- a/man/std::uninitialized_copy_n.3 +++ b/man/std::uninitialized_copy_n.3 @@ -1,28 +1,59 @@ -.TH std::uninitialized_copy_n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uninitialized_copy_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_copy_n \- std::uninitialized_copy_n + .SH Synopsis Defined in header - template< class InputIt, class Size, class ForwardIt > - ForwardIt uninitialized_copy_n( InputIt first, Size count, ForwardIt \fI(since C++11)\fP - d_first); + template< class InputIt, class Size, class NoThrowForwardIt > + + NoThrowForwardIt uninitialized_copy_n( InputIt first, Size count, \fB(1)\fP \fI(since C++11)\fP + + NoThrowForwardIt d_first ); + template< class ExecutionPolicy, class ForwardIt, + + class Size, class NoThrowForwardIt > + NoThrowForwardIt uninitialized_copy_n( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt first, Size + count, + + NoThrowForwardIt d_first ); - Copies count elements from a range beginning at first to an uninitialized memory - area beginning at d_first. The elements in the uninitialized area are constructed - using copy constructor. + 1) Copies count elements from a range beginning at first to an uninitialized memory + area beginning at d_first as if by + for (; n > 0; ++d_first, (void) ++first, --n) + ::new (static_cast(std::addressof(*d_first))) + typename std::iterator_traits::value_type(*first); + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. - If an exception is thrown during the initialization, the function has no effects. + If d_first + [0, n) overlaps with first + [0, n), the behavior is \fI(since C++20)\fP + undefined. - This section is incomplete - Reason: update possible implementation to reflect this + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first - the beginning of the range of the elements to copy - d_first - the beginning of the destination range + first - the beginning of the range of the elements to copy + count - the number of elements to copy + d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for + details. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + NoThrowForwardIt must meet the requirements of LegacyForwardIterator. - - ForwardIt must meet the requirements of ForwardIterator. + No increment, assignment, comparison, or indirection through valid instances of + NoThrowForwardIt may throw exceptions. .SH Return value @@ -32,21 +63,40 @@ Linear in count. +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + .SH Possible implementation - template - ForwardIt uninitialized_copy_n(InputIt first, Size count, ForwardIt d_first) - { - typedef typename std::iterator_traits::value_type Value; - for (; count > 0; ++first, ++d_first, --count) { - ::new (static_cast(&*d_first)) Value(*first); - } - return d_first; - } +template +NoThrowForwardIt uninitialized_copy_n(InputIt first, Size count, NoThrowForwardIt d_first) +{ + using T = typename std::iterator_traits::value_type; + NoThrowForwardIt current = d_first; + try + { + for (; count > 0; ++first, (void) ++current, --count) + ::new (static_cast(std::addressof(*current))) T(*first); + } + catch (...) + { + for (; d_first != current; ++d_first) + d_first->~T(); + throw; + } + return current; +} .SH Example - + // Run this code #include @@ -54,34 +104,54 @@ #include #include #include - + #include + int main() { std::vector v = {"This", "is", "an", "example"}; - + std::string* p; std::size_t sz; - std::tie(p, sz) = std::get_temporary_buffer(v.size()); + std::tie(p, sz) = std::get_temporary_buffer(v.size()); sz = std::min(sz, v.size()); - + std::uninitialized_copy_n(v.begin(), sz, p); - - for (std::string* i = p; i != p+sz; ++i) { + + for (std::string* i = p; i != p + sz; ++i) + { std::cout << *i << ' '; i->~basic_string(); } + std::cout << '\\n'; + std::return_temporary_buffer(p); } -.SH Output: +.SH Possible output: This is an example -.SH See also + Defect reports - uninitialized_copy copies a range of objects to an uninitialized area of memory - \fI(function template)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + the effect description used a for loop with + the iteration discards the value + LWG 2133 C++98 expression ++d_first, ++first, --n, which of one operand to + results disable those ADLs + in argument-dependent lookups of operator, + LWG 2433 C++11 this algorithm might be hijacked by uses std::addressof + overloaded operator& + LWG 3870 C++20 this algorithm might create objects on a kept disallowed + const storage + +.SH See also - * Todo with reason + copies a range of objects to an uninitialized area of + uninitialized_copy memory + \fI(function template)\fP + ranges::uninitialized_copy_n copies a number of objects to an uninitialized area of + (C++20) memory + (niebloid) diff --git a/man/std::uninitialized_default_construct.3 b/man/std::uninitialized_default_construct.3 new file mode 100644 index 000000000..b2447e3ce --- /dev/null +++ b/man/std::uninitialized_default_construct.3 @@ -0,0 +1,165 @@ +.TH std::uninitialized_default_construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_default_construct \- std::uninitialized_default_construct + +.SH Synopsis + Defined in header + template< class ForwardIt > + void uninitialized_default_construct( ForwardIt first, ForwardIt \fB(1)\fP \fI(since C++17)\fP + last ); + template< class ExecutionPolicy, class ForwardIt > + + void uninitialized_default_construct( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt + last ); + + 1) Constructs objects of type typename std::iterator_traits::value_type + in the uninitialized storage designated by the range [first, last) by + default-initialization, as if by for (; first != last; ++first) + ::new (static_cast(std::addressof(*first))) + typename std::iterator_traits::value_type; + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of the elements to initialize + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the distance between first and last. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + template + void uninitialized_default_construct(ForwardIt first, ForwardIt last) + { + using Value = typename std::iterator_traits::value_type; + ForwardIt current = first; + try + { + for (; current != last; ++current) + { + ::new (const_cast(static_cast( + std::addressof(*current)))) Value; + } + } + catch (...) + { + std::destroy(first, current); + throw; + } + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + struct S + { + std::string m{"Default value"}; + }; + + int main() + { + constexpr int n{3}; + alignas(alignof(S)) unsigned char mem[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(mem)}; + auto last{first + n}; + + std::uninitialized_default_construct(first, last); + + for (auto it{first}; it != last; ++it) + std::cout << it->m << '\\n'; + + std::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_default_construct + // generally does not zero-fill the given uninitialized memory area. + int v[]{1, 2, 3, 4}; + const int original[]{1, 2, 3, 4}; + std::uninitialized_default_construct(std::begin(v), std::end(v)); + + // Maybe undefined behavior, pending CWG 1997. + // for (const int i : v) + // std::cout << i << ' '; + + // The result is unspecified. + std::cout << + (std::memcmp(v, original, sizeof(v)) == 0 ? "Unmodified\\n" : "Modified\\n"); + } + +.SH Possible output: + + Default value + Default value + Default value + Unmodified + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by default-initialization + uninitialized_default_construct_n in an uninitialized area of memory, defined + \fI(C++17)\fP by a start and a count + \fI(function template)\fP + constructs objects by value-initialization + uninitialized_value_construct in an uninitialized area of memory, defined + \fI(C++17)\fP by a range + \fI(function template)\fP + constructs objects by default-initialization + ranges::uninitialized_default_construct in an uninitialized area of memory, defined + (C++20) by a range + (niebloid) diff --git a/man/std::uninitialized_default_construct_n.3 b/man/std::uninitialized_default_construct_n.3 new file mode 100644 index 000000000..c6593ed21 --- /dev/null +++ b/man/std::uninitialized_default_construct_n.3 @@ -0,0 +1,165 @@ +.TH std::uninitialized_default_construct_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_default_construct_n \- std::uninitialized_default_construct_n + +.SH Synopsis + Defined in header + template< class ForwardIt, class Size > + ForwardIt uninitialized_default_construct_n( ForwardIt first, Size \fB(1)\fP \fI(since C++17)\fP + n ); + template< class ExecutionPolicy, class ForwardIt, class Size > + + ForwardIt uninitialized_default_construct_n( ExecutionPolicy&& + policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, Size + n ); + + 1) Constructs n objects of type typename std::iterator_traits::value_type + in the uninitialized storage starting at first by default-initialization, as if by + for (; n > 0; (void) ++first, --n) + ::new (static_cast(std::addressof(*first))) + typename std::iterator_traits::value_type; + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first - the beginning of the range of elements to initialize + n - the number of elements to construct + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + +.SH Return value + + The end of the range of objects (i.e., std::next(first, n)). + +.SH Complexity + + Linear in n. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + template + ForwardIt uninitialized_default_construct_n(ForwardIt first, Size n) + { + using T = typename std::iterator_traits::value_type; + ForwardIt current = first; + + try + { + for (; n > 0; (void) ++current, --n) + ::new (const_cast(static_cast( + std::addressof(*current)))) T; + return current; + } + catch (...) + { + std::destroy(first, current); + throw; + } + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + struct S + { + std::string m{"default value"}; + }; + + int main() + { + constexpr int n{3}; + alignas(alignof(S)) unsigned char mem[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(mem)}; + auto last = std::uninitialized_default_construct_n(first, n); + + for (auto it{first}; it != last; ++it) + std::cout << it->m << '\\n'; + + std::destroy(first, last); + } + catch(...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_default_construct_n + // generally does not zero-initialize the given uninitialized memory area. + int v[]{1, 2, 3, 4}; + const int original[]{1, 2, 3, 4}; + std::uninitialized_default_construct_n(std::begin(v), std::size(v)); + + // An attempt to access v might be an undefined behavior, pending CWG 1997: + // for (const int i : v) + // std::cout << i << ' '; + + // The result is unspecified: + std::cout << (std::memcmp(v, original, sizeof(v)) == 0 ? "un" : "") << "modified\\n"; + } + +.SH Possible output: + + default value + default value + default value + unmodified + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by + uninitialized_default_construct default-initialization in an uninitialized + \fI(C++17)\fP area of memory, defined by a range + \fI(function template)\fP + constructs objects by value-initialization + uninitialized_value_construct_n in an uninitialized area of memory, + \fI(C++17)\fP defined by a start and a count + \fI(function template)\fP + constructs objects by + ranges::uninitialized_default_construct_n default-initialization in an uninitialized + (C++20) area of memory, defined by a start and + count + (niebloid) diff --git a/man/std::uninitialized_fill.3 b/man/std::uninitialized_fill.3 index ada05bf62..c921860d1 100644 --- a/man/std::uninitialized_fill.3 +++ b/man/std::uninitialized_fill.3 @@ -1,20 +1,52 @@ -.TH std::uninitialized_fill 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uninitialized_fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_fill \- std::uninitialized_fill + .SH Synopsis Defined in header template< class ForwardIt, class T > - void uninitialized_fill( ForwardIt first, ForwardIt last, const T& value ) + void uninitialized_fill( ForwardIt first, ForwardIt last, const T& \fB(1)\fP + value ); + template< class ExecutionPolicy, class ForwardIt, class T > + + void uninitialized_fill( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, const T& + value ); + + 1) Copies the given value to an uninitialized memory area, defined by the range + [first, last) as if by for (; first != last; ++first) + ::new (/* VOIDIFY */(*first)) + typename std::iterator_traits::value_type(value); + where /* VOIDIFY */(e) is: + + static_cast(&e) \fI(until C++11)\fP + static_cast(std::addressof(e)) \fI(since C++11)\fP - Copies the given value to an uninitialized memory area, defined by the range [first, - last). The elements in the uninitialized area are constructed using copy - constructor. + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first, last - the range of the elements to initialize - value - the value to construct the elements with + first, last - the range of the elements to initialize + value - the value to construct the elements with + policy - the execution policy to use. See execution policy for + details. .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + Applying &* to a ForwardIt value must yield a pointer to its value type. + \fI(until C++11)\fP .SH Return value @@ -22,45 +54,63 @@ .SH Complexity - Linear in the distance between first and last + Linear in the distance between first and last. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation template - void uninitialized_fill(ForwardIt first, - ForwardIt last, - const T& value) + void uninitialized_fill(ForwardIt first, ForwardIt last, const T& value) { - typedef typename std::iterator_traits::value_type Value; - for (; first != last; ++first) { - ::new (static_cast(&*first)) Value(value); + using V = typename std::iterator_traits::value_type; + ForwardIt current = first; + try + { + for (; current != last; ++current) + ::new (static_cast(std::addressof(*current))) V(value); + } + catch (...) + { + for (; first != current; ++first) + first->~V(); + throw; } } .SH Example - + // Run this code #include #include #include #include - #include - + int main() { - std::string* p; - std::size_t sz; - std::tie(p, sz) = std::get_temporary_buffer(4); - - std::uninitialized_fill(p, p+sz, "Example"); - - for (std::string* i = p; i != p+sz; ++i) { + const std::size_t sz = 4; + std::allocator alloc; + std::string* p = alloc.allocate(sz); + + std::uninitialized_fill(p, p + sz, "Example"); + + for (std::string* i = p; i != p + sz; ++i) + { std::cout << *i << '\\n'; i->~basic_string(); } - std::return_temporary_buffer(p); + + alloc.deallocate(p, sz); } .SH Output: @@ -70,7 +120,26 @@ .SH Example .SH Example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + given T as the value type of ForwardIt, + LWG 866 C++98 if uses global replacement- + T::operator new exists, the program new instead + might be ill-formed + LWG 2433 C++11 this algorithm might be hijacked by uses std::addressof + overloaded operator& + LWG 3870 C++20 this algorithm might create objects on kept disallowed + a const storage + .SH See also - uninitialized_fill_n copies an object to an uninitialized area of memory - \fI(function template)\fP + copies an object to an uninitialized area of memory, + uninitialized_fill_n defined by a start and a count + \fI(function template)\fP + ranges::uninitialized_fill copies an object to an uninitialized area of memory, + (C++20) defined by a range + (niebloid) diff --git a/man/std::uninitialized_fill_n.3 b/man/std::uninitialized_fill_n.3 index 907187fde..7b0253594 100644 --- a/man/std::uninitialized_fill_n.3 +++ b/man/std::uninitialized_fill_n.3 @@ -1,21 +1,53 @@ -.TH std::uninitialized_fill_n 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uninitialized_fill_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_fill_n \- std::uninitialized_fill_n + .SH Synopsis Defined in header template< class ForwardIt, class Size, class T > - void uninitialized_fill_n( ForwardIt first, Size count, const T& value ) + ForwardIt uninitialized_fill_n( ForwardIt first, Size count, const \fB(1)\fP + T& value ); + template< class ExecutionPolicy, class ForwardIt, class Size, + class T > + + ForwardIt uninitialized_fill_n( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, Size count, const + T& value ); + + 1) Copies the given value value to the first count elements in an uninitialized + memory area beginning at first as if by for (; n--; ++first) + ::new (/* VOIDIFY */(*first)) + typename std::iterator_traits::value_type(value); + where /* VOIDIFY */(e) is: + + static_cast(&e) \fI(until C++11)\fP + static_cast(std::addressof(e)) \fI(since C++11)\fP - Copies the given value value to the first count elements in an uninitialized memory - area beginning at first. The elements in the uninitialized area are constructed - using copy constructor. + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) .SH Parameters - first - the beginning of the range of the elements to initialize - count - number of elements to construct - value - the value to construct the elements with + first - the beginning of the range of the elements to + initialize + count - number of elements to construct + value - the value to construct the elements with .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + Applying &* to a ForwardIt value must yield a pointer to its value type. + \fI(until C++11)\fP .SH Return value @@ -23,24 +55,42 @@ .SH Complexity - Linear in count + Linear in count. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation - template< class ForwardIt, class Size, class T > - void uninitialized_fill_n(ForwardIt first, Size count - const T& value) + template + ForwardIt uninitialized_fill_n(ForwardIt first, Size count, const T& value) { - typedef typename std::iterator_traits::value_type Value; - for (; count > 0; ++first, --count) { - ::new (static_cast(&*first)) Value(value); + using V = typename std::iterator_traits::value_type; + ForwardIt current = first; + try + { + for (; count > 0; ++current, (void) --count) + ::new (static_cast(std::addressof(*current))) V(value); + return current; + } + catch (...) + { + for (; first != current; ++first) + first->~V(); + throw; } - return first; } .SH Example - + // Run this code #include @@ -48,15 +98,16 @@ #include #include #include - + int main() { std::string* p; std::size_t sz; - std::tie(p, sz) = std::get_temporary_buffer(4); + std::tie(p, sz) = std::get_temporary_buffer(4); std::uninitialized_fill_n(p, sz, "Example"); - - for (std::string* i = p; i != p+sz; ++i) { + + for (std::string* i = p; i != p + sz; ++i) + { std::cout << *i << '\\n'; i->~basic_string(); } @@ -70,7 +121,29 @@ .SH Example .SH Example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + given T as the value type of ForwardIt, + LWG 866 C++98 if uses global replacement- + T::operator new exists, the program new instead + might be ill-formed + the location of the first element + LWG 1339 C++98 following returned + the filling range was not returned + LWG 2433 C++11 this algorithm might be hijacked by uses std::addressof + overloaded operator& + LWG 3870 C++20 this algorithm might create objects on kept disallowed + a const storage + .SH See also - uninitialized_fill copies an object to an uninitialized area of memory - \fI(function template)\fP + copies an object to an uninitialized area of memory, + uninitialized_fill defined by a range + \fI(function template)\fP + ranges::uninitialized_fill_n copies an object to an uninitialized area of memory, + (C++20) defined by a start and a count + (niebloid) diff --git a/man/std::uninitialized_move.3 b/man/std::uninitialized_move.3 new file mode 100644 index 000000000..3d380fc3f --- /dev/null +++ b/man/std::uninitialized_move.3 @@ -0,0 +1,168 @@ +.TH std::uninitialized_move 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_move \- std::uninitialized_move + +.SH Synopsis + Defined in header + template< class InputIt, class NoThrowForwardIt > + + NoThrowForwardIt uninitialized_move( InputIt first, InputIt last, \fB(1)\fP \fI(since C++17)\fP + + NoThrowForwardIt d_first ); + template< class ExecutionPolicy, class ForwardIt, class + NoThrowForwardIt > + + NoThrowForwardIt uninitialized_move( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt first, ForwardIt + last, + + NoThrowForwardIt d_first ); + + 1) Moves elements from the range [first, last) to an uninitialized memory area + beginning at d_first as if by + for (; first != last; ++d_first, (void) ++first) + ::new (static_cast(std::addressof(*d_first))) + typename + std::iterator_traits::value_type(std::move(*first)); + If an exception is thrown during the initialization, some objects in [first, last) + are left in a valid but unspecified state, and the objects already constructed are + destroyed in an unspecified order. + + If d_first + [0, std::distance(first, last)) overlaps with \fI(since C++20)\fP + [first, last), the behavior is undefined. + + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of the elements to move + d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + NoThrowForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + NoThrowForwardIt may throw exceptions. + +.SH Return value + + Iterator to the element past the last element moved. + +.SH Complexity + + Linear in the distance between first and last. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + +template +NoThrowForwardIt uninitialized_move(InputIt first, InputIt last, NoThrowForwardIt d_first) +{ + using Value = typename std::iterator_traits::value_type; + NoThrowForwardIt current = d_first; + try + { + for (; first != last; ++first, (void) ++current) + ::new (static_cast(std::addressof(*current))) Value(std::move(*first)); + return current; + } + catch (...) + { + std::destroy(d_first, current); + throw; + } +} + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto rem, auto first, auto last) + { + for (std::cout << rem; first != last; ++first) + std::cout << std::quoted(*first) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::string in[]{"Home", "Work!"}; + print("initially, in: ", std::begin(in), std::end(in)); + + if ( + constexpr auto sz = std::size(in); + void* out = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz)) + { + try + { + auto first{static_cast(out)}; + auto last{first + sz}; + std::uninitialized_move(std::begin(in), std::end(in), first); + + print("after move, in: ", std::begin(in), std::end(in)); + print("after move, out: ", first, last); + + std::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + std::free(out); + } + } + +.SH Possible output: + + initially, in: "Home" "Work!" + after move, in: "" "" + after move, out: "Home" "Work!" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + copies a range of objects to an uninitialized area of + uninitialized_copy memory + \fI(function template)\fP + uninitialized_move_n moves a number of objects to an uninitialized area of + \fI(C++17)\fP memory + \fI(function template)\fP + ranges::uninitialized_move moves a range of objects to an uninitialized area of + (C++20) memory + (niebloid) diff --git a/man/std::uninitialized_move_n.3 b/man/std::uninitialized_move_n.3 new file mode 100644 index 000000000..a716bf345 --- /dev/null +++ b/man/std::uninitialized_move_n.3 @@ -0,0 +1,172 @@ +.TH std::uninitialized_move_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_move_n \- std::uninitialized_move_n + +.SH Synopsis + Defined in header + template< class InputIt, class Size, class NoThrowForwardIt > + + std::pair \fB(1)\fP \fI(since C++17)\fP + uninitialized_move_n( InputIt first, Size count, + + NoThrowForwardIt d_first ); + template< class ExecutionPolicy, class ForwardIt, + + class Size, class NoThrowForwardIt > + std::pair \fB(2)\fP \fI(since C++17)\fP + uninitialized_move_n( ExecutionPolicy&& policy, ForwardIt + first, + + Size count, NoThrowForwardIt d_first ); + + 1) Moves count elements from a range beginning at first to an uninitialized memory + area beginning at d_first as if by for (; n > 0; ++d_first, (void) ++first, --n) + ::new (static_cast(std::addressof(*d_first))) + typename + std::iterator_traits::value_type(std::move(*first)); + If an exception is thrown during the initialization, some objects in first + [0, n) + are left in a valid but unspecified state, and the objects already constructed are + destroyed in an unspecified order. + + If d_first + [0, n) overlaps with first + [0, n), the behavior is \fI(since C++20)\fP + undefined. + + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first - the beginning of the range of the elements to move + d_first - the beginning of the destination range + count - the number of elements to move + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + NoThrowForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + NoThrowForwardIt may throw exceptions. + +.SH Return value + + A pair whose first element is an iterator to the element past the last element moved + in the source range, and whose second element is an iterator to the element past the + last element moved in the destination range. + +.SH Complexity + + Linear in count. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + +template +std::pair + uninitialized_move_n(InputIt first, Size count, NoThrowForwardIt d_first) +{ + using Value = typename std::iterator_traits::value_type; + NoThrowForwardIt current = d_first; + try + { + for (; count > 0; ++first, (void) ++current, --count) + ::new (static_cast(std::addressof(*current))) Value(std::move(*first)); + } + catch (...) + { + std::destroy(d_first, current); + throw; + } + return {first, current}; +} + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print(auto rem, auto first, auto last) + { + for (std::cout << rem; first != last; ++first) + std::cout << std::quoted(*first) << ' '; + std::cout << '\\n'; + } + + int main() + { + std::string in[]{"One", "Definition", "Rule"}; + print("initially, in: ", std::begin(in), std::end(in)); + + if ( + constexpr auto sz = std::size(in); + void* out = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz)) + { + try + { + auto first{static_cast(out)}; + auto last{first + sz}; + std::uninitialized_move_n(std::begin(in), sz, first); + + print("after move, in: ", std::begin(in), std::end(in)); + print("after move, out: ", first, last); + + std::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + std::free(out); + } + } + +.SH Possible output: + + initially, in: "One" "Definition" "Rule" + after move, in: "" "" "" + after move, out: "One" "Definition" "Rule" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + uninitialized_move moves a range of objects to an uninitialized area of + \fI(C++17)\fP memory + \fI(function template)\fP + uninitialized_copy_n copies a number of objects to an uninitialized area of + \fI(C++11)\fP memory + \fI(function template)\fP + ranges::uninitialized_move_n moves a number of objects to an uninitialized area of + (C++20) memory + (niebloid) diff --git a/man/std::uninitialized_value_construct.3 b/man/std::uninitialized_value_construct.3 new file mode 100644 index 000000000..b65a12faf --- /dev/null +++ b/man/std::uninitialized_value_construct.3 @@ -0,0 +1,157 @@ +.TH std::uninitialized_value_construct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_value_construct \- std::uninitialized_value_construct + +.SH Synopsis + Defined in header + template< class ForwardIt > + void uninitialized_value_construct( ForwardIt first, ForwardIt \fB(1)\fP \fI(since C++17)\fP + last ); + template< class ExecutionPolicy, class ForwardIt > + + void uninitialized_value_construct( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt + last ); + + 1) Constructs objects of type typename iterator_traits::value_type in the + uninitialized storage designated by the range [first, last) by value-initialization, + as if by for (; first != last; ++first) + ::new (static_cast(std::addressof(*first))) + typename std::iterator_traits::value_type(); + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first, last - the range of the elements to initialize + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Linear in the distance between first and last. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + template + void uninitialized_value_construct(ForwardIt first, ForwardIt last) + { + using Value = typename std::iterator_traits::value_type; + ForwardIt current = first; + try + { + for (; current != last; ++current) + ::new (const_cast(static_cast( + std::addressof(*current)))) Value(); + } + catch (...) + { + std::destroy(first, current); + throw; + } + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + struct S { std::string m{"Default value"}; }; + + constexpr int n{3}; + alignas(alignof(S)) unsigned char mem[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(mem)}; + auto last{first + n}; + + std::uninitialized_value_construct(first, last); + + for (auto it{first}; it != last; ++it) + std::cout << it->m << '\\n'; + + std::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_value_construct + // zero-fills the given uninitialized memory area. + int v[]{1, 2, 3, 4}; + for (const int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + std::uninitialized_value_construct(std::begin(v), std::end(v)); + for (const int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Output: + + Default value + Default value + Default value + 1 2 3 4 + 0 0 0 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by value-initialization in + uninitialized_value_construct_n an uninitialized area of memory, defined by a + \fI(C++17)\fP start and a count + \fI(function template)\fP + constructs objects by default-initialization + uninitialized_default_construct in an uninitialized area of memory, defined by + \fI(C++17)\fP a range + \fI(function template)\fP + constructs objects by value-initialization in + ranges::uninitialized_value_construct an uninitialized area of memory, defined by a + (C++20) range + (niebloid) diff --git a/man/std::uninitialized_value_construct_n.3 b/man/std::uninitialized_value_construct_n.3 new file mode 100644 index 000000000..b5bf38972 --- /dev/null +++ b/man/std::uninitialized_value_construct_n.3 @@ -0,0 +1,158 @@ +.TH std::uninitialized_value_construct_n 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uninitialized_value_construct_n \- std::uninitialized_value_construct_n + +.SH Synopsis + Defined in header + template< class ForwardIt, class Size > + ForwardIt uninitialized_value_construct_n( ForwardIt first, Size n \fB(1)\fP \fI(since C++17)\fP + ); + template< class ExecutionPolicy, class ForwardIt, class Size > + + ForwardIt uninitialized_value_construct_n( ExecutionPolicy&& + policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, Size n + ); + + 1) Constructs n objects of type typename iterator_traits::value_type in + the uninitialized storage starting at first by value-initialization, as if by for (; + n > 0; (void) ++first, --n) + ::new (static_cast(std::addressof(*first))) + typename std::iterator_traits::value_type(); + If an exception is thrown during the initialization, the objects already constructed + are destroyed in an unspecified order. + 2) Same as \fB(1)\fP, but executed according to policy. This overload participates in + overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Parameters + + first - the beginning of the range of elements to initialize + n - the number of elements to initialize + policy - the execution policy to use. See execution policy for + details. +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + - + No increment, assignment, comparison, or indirection through valid instances of + ForwardIt may throw exceptions. + +.SH Return value + + The end of the range of objects (i.e., std::next(first, n)). + +.SH Complexity + + Linear in n. + +.SH Exceptions + + The overload with a template parameter named ExecutionPolicy reports errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. + +.SH Possible implementation + + template + ForwardIt uninitialized_value_construct_n(ForwardIt first, Size n) + { + using T = typename std::iterator_traits::value_type; + ForwardIt current = first; + try + { + for (; n > 0 ; (void) ++current, --n) + ::new (const_cast(static_cast( + std::addressof(*current)))) T(); + return current; + } + catch (...) + { + std::destroy(first, current); + throw; + } + } + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + struct S { std::string m{"Default value"}; }; + + constexpr int n{3}; + alignas(alignof(S)) unsigned char mem[n * sizeof(S)]; + + try + { + auto first{reinterpret_cast(mem)}; + auto last = std::uninitialized_value_construct_n(first, n); + + for (auto it{first}; it != last; ++it) + std::cout << it->m << '\\n'; + + std::destroy(first, last); + } + catch (...) + { + std::cout << "Exception!\\n"; + } + + // Notice that for "trivial types" the uninitialized_value_construct_n + // zero-initializes the given uninitialized memory area. + int v[]{1, 2, 3, 4}; + for (const int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + std::uninitialized_value_construct_n(std::begin(v), std::size(v)); + for (const int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Output: + + Default value + Default value + Default value + 1 2 3 4 + 0 0 0 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3870 C++20 this algorithm might create objects on a const kept disallowed + storage + +.SH See also + + constructs objects by value-initialization + uninitialized_value_construct in an uninitialized area of memory, defined + \fI(C++17)\fP by a range + \fI(function template)\fP + constructs objects by default-initialization + uninitialized_default_construct_n in an uninitialized area of memory, defined + \fI(C++17)\fP by a start and a count + \fI(function template)\fP + constructs objects by value-initialization + ranges::uninitialized_value_construct_n in an uninitialized area of memory, defined + (C++20) by a start and a count + (niebloid) diff --git a/man/std::unique.3 b/man/std::unique.3 index 553244672..4029a2cd1 100644 --- a/man/std::unique.3 +++ b/man/std::unique.3 @@ -1,28 +1,68 @@ -.TH std::unique 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique \- std::unique + .SH Synopsis Defined in header - template< class ForwardIt > \fB(1)\fP + template< class ForwardIt > \fB(1)\fP (constexpr since C++20) ForwardIt unique( ForwardIt first, ForwardIt last ); - template< class ForwardIt, class BinaryPredicate > \fB(2)\fP - ForwardIt unique( ForwardIt first, ForwardIt last, BinaryPredicate p ); - - Removes all consecutive duplicate elements from the range [first, last) and returns - a past-the-end iterator for the new logical end of the range. The first version uses - operator== to compare the elements, the second version uses the given binary - predicate p. - - Removing is done by shifting the elements in the range in such a way that elements - to be erased are overwritten. Relative order of the elements that remain is - preserved and the physical size of the container is unchanged. Iterators pointing to - an element between the new logical end and the physical end of the range are still - dereferenceable, but the elements themselves have unspecified values. A call to - unique is typically followed by a call to a container's erase method, which erases - the unspecified values and reduces the physical size of the container to match its - new logical size. + template< class ExecutionPolicy, class ForwardIt > + + ForwardIt unique( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last ); + template< class ForwardIt, class BinaryPred > + ForwardIt unique( ForwardIt first, ForwardIt last, \fB(3)\fP (constexpr since C++20) + BinaryPred p ); + template< class ExecutionPolicy, + + class ForwardIt, class BinaryPred > + ForwardIt unique( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + + ForwardIt first, ForwardIt last, + BinaryPred p ); + + Removes all except the first element from every consecutive group of equivalent + elements from the range [first, last) and returns a past-the-end iterator for the + new end of the range. + + 1) Elements are compared using operator==. + If operator== does not establish an equivalence relation, the behavior is undefined. + 3) Elements are compared using the given binary predicate p. + If p does not establish an equivalence relation, the behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + +.SH Explanation + + Removing is done by shifting the elements in the range in such a way that the + elements that are not to be removed appear in the beginning of the range. + + * Shifting is done by + copy assignment + \fI(until C++11)\fP + move assignment + \fI(since C++11)\fP. + * The removing operation is stable: the relative order of the elements not to be + removed stays the same. + * The underlying sequence of [first, last) is not shortened by the removing + operation. Given result as the returned iterator: + + * All iterators in [result, last) are still dereferenceable. + + * Each element of [result, last) has a valid but unspecified state, + because move assignment can eliminate elements by moving from \fI(since C++11)\fP + elements that were originally in that range. .SH Parameters first, last - the range of elements to process + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -30,98 +70,149 @@ following: bool pred(const Type1 &a, const Type2 &b); - p - - The signature does not need to have const &, but the function must not - modify the objects passed to it. + + p - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of them. - - .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. - The type of dereferenced ForwardIt must meet the requirements of MoveAssignable. .SH Return value - Forward iterator to the new end of the range + A ForwardIt to the new end of the range. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize max(0,N-1)\\)max(0,N-1) comparisons using operator==. + 3,4) Exactly \\(\\scriptsize max(0,N-1)\\)max(0,N-1) applications of the predicate p. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version + See also the implementations in libstdc++, libc++, and MSVC STL. + + unique \fB(1)\fP template ForwardIt unique(ForwardIt first, ForwardIt last) { if (first == last) return last; - + ForwardIt result = first; - while (++first != last) { - if (!(*result == *first)) { - *(++result) = *first; - } - } + while (++first != last) + if (!(*result == *first) && ++result != first) + *result = std::move(*first); + return ++result; } -.SH Second version + unique \fB(3)\fP template - ForwardIt unique(ForwardIt first, ForwardIt last, - BinaryPredicate p) + ForwardIt unique(ForwardIt first, ForwardIt last, BinaryPredicate p) { if (first == last) return last; - + ForwardIt result = first; - while (++first != last) { - if (!p(*result, *first)) { - *(++result) = *first; - } - } + while (++first != last) + if (!p(*result, *first) && ++result != first) + *result = std::move(*first); + return ++result; } +.SH Notes + + A call to unique is typically followed by a call to a container's erase member + function to actually remove elements from the container. + .SH Example - The following code removes all consecutive equivalent elements from a vector of - integers. - // Run this code - #include #include + #include #include - + int main() { - std::vector v{1, 2, 2, 2, 3, 3, 2, 2, 1}; - std::vector::iterator last; - - last = std::unique(v.begin(), v.end()); // 1 2 3 2 1 3 2 2 1 - // ^ - for (std::vector::iterator it = v.begin(); it != last; ++it) { - std::cout << *it << " "; - } - std::cout << "\\n"; + // a vector containing several duplicate elements + std::vector v{1, 2, 1, 1, 3, 3, 3, 4, 5, 4}; + auto print = [&](int id) + { + std::cout << "@" << id << ": "; + for (int i : v) + std::cout << i << ' '; + std::cout << '\\n'; + }; + print(1); + + // remove consecutive (adjacent) duplicates + auto last = std::unique(v.begin(), v.end()); + // v now holds {1 2 1 3 4 5 4 x x x}, where 'x' is indeterminate + v.erase(last, v.end()); + print(2); + + // sort followed by unique, to remove all duplicates + std::sort(v.begin(), v.end()); // {1 1 2 3 4 4 5} + print(3); + + last = std::unique(v.begin(), v.end()); + // v now holds {1 2 3 4 5 x x}, where 'x' is indeterminate + v.erase(last, v.end()); + print(4); } .SH Output: - 1 2 3 2 1 + @1: 1 2 1 1 3 3 3 4 5 4 + @2: 1 2 1 3 4 5 4 + @3: 1 1 2 3 4 4 5 + @4: 1 2 3 4 5 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - linear in the distance between first and last + DR Applied to Behavior as published Correct behavior + the behavior was unclear if the elements the behavior is + LWG 202 C++98 are undefined in this case + compared using a non-equivalence relation .SH See also - finds two identical (or some other relationship) items adjacent to - adjacent_find each other - \fI(function template)\fP - creates a copy of some range of elements that contains no consecutive - unique_copy duplicates - \fI(function template)\fP - remove removes elements satisfying specific criteria - remove_if \fI(function template)\fP + finds the first two adjacent items that are equal (or satisfy a given + adjacent_find predicate) + \fI(function template)\fP + creates a copy of some range of elements that contains no consecutive + unique_copy duplicates + \fI(function template)\fP + remove removes elements satisfying specific criteria + remove_if \fI(function template)\fP + unique removes consecutive duplicate elements + \fI(public member function of std::list)\fP + unique removes consecutive duplicate elements + \fI(public member function of std::forward_list)\fP + ranges::unique removes consecutive duplicate elements in a range + (C++20) (niebloid) diff --git a/man/std::unique_copy.3 b/man/std::unique_copy.3 index d9ed9b243..37be9c04d 100644 --- a/man/std::unique_copy.3 +++ b/man/std::unique_copy.3 @@ -1,26 +1,78 @@ -.TH std::unique_copy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_copy \- std::unique_copy + .SH Synopsis Defined in header template< class InputIt, class OutputIt > + OutputIt unique_copy( InputIt first, InputIt last, \fB(1)\fP (constexpr since C++20) + OutputIt d_first ); + template< class ExecutionPolicy, class ForwardIt1, class + ForwardIt2 > + + ForwardIt2 unique_copy( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP + ForwardIt1 first, - OutputIt unique_copy( InputIt first, InputIt last, \fB(1)\fP + ForwardIt1 last, ForwardIt2 + d_first ); + template< class InputIt, class OutputIt, class + BinaryPred > + \fB(3)\fP (constexpr since C++20) + OutputIt unique_copy( InputIt first, InputIt last, - OutputIt d_first ); - template< class InputIt, class OutputIt, class BinaryPredicate > + OutputIt d_first, BinaryPred p ); + template< class ExecutionPolicy, class ForwardIt1, - OutputIt unique_copy( InputIt first, InputIt last, \fB(2)\fP + class ForwardIt2, class BinaryPred > + ForwardIt2 unique_copy( ExecutionPolicy&& policy, + ForwardIt1 first, ForwardIt1 \fB(4)\fP \fI(since C++17)\fP + last, - OutputIt d_first, BinaryPredicate p ); + ForwardIt2 d_first, BinaryPred p + ); Copies the elements from the range [first, last), to another range beginning at d_first in such a way that there are no consecutive equal elements. Only the first - element of each group of equal elements is copied. The first version uses operator== - to compare the elements, the second version uses the given binary predicate p. + element of each group of equal elements is copied. + + 1) Elements are compared using operator==. + If operator== does not establish an equivalence relation, the behavior is undefined. + 3) Elements are compared using the given binary predicate p. + If p does not establish an equivalence relation, the behavior is undefined. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If + *d_first = *first is invalid + \fI(until C++20)\fP + *first is not writable to d_first + \fI(since C++20)\fP, the program is ill-formed. + + If source and destination ranges overlap, the behavior is undefined. + + Given T as the value type of InputIt, if overload \fB(1)\fP or \fB(3)\fP does not satisfy all of + the following conditions, the behavior is undefined: + + * InputIt meets the requirements of LegacyForwardIterator. \fI(until C++20)\fP + * InputIt models forward_iterator. \fI(since C++20)\fP + + * T is both CopyConstructible and CopyAssignable. + * All following conditions are satisfied: + + * OutputIt meets the requirements of LegacyForwardIterator. + * The value type of OutputIt is also T. + * T is CopyAssignable. .SH Parameters first, last - the range of elements to process d_first - the beginning of the destination range + policy - the execution policy to use. See execution policy for details. binary predicate which returns true if the elements should be treated as equal. @@ -29,103 +81,114 @@ bool pred(const Type1 &a, const Type2 &b); p - - The signature does not need to have const &, but the function must not - modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type - ForwardIt can be dereferenced and then implicitly converted to both of - them. - - + While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type InputIt + can be dereferenced and then implicitly converted to both of them. .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - - OutputIt must meet the requirements of OutputIterator. + OutputIt must meet the requirements of LegacyOutputIterator. - - The type of dereferenced InputIt must meet the requirements of CopyAssignable. - - - The type of dereferenced InputIt must meet the requirements of CopyConstructible. if - neither InputIt nor OutputIt satisfies ForwardIterator + ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. .SH Return value - Output iterator to the element past the last written element + Output iterator to the element past the last written element. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1,2) Exactly \\(\\scriptsize max(0,N-1)\\)max(0,N-1) comparisons using operator==. + 3,4) Exactly \\(\\scriptsize max(0,N-1)\\)max(0,N-1) applications of the predicate p. + + For overloads (2,4), there may be a performance cost if the value type of ForwardIt1 + is not both CopyConstructible and CopyAssignable. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. .SH Possible implementation -.SH First version - template - ForwardIt unique_copy(ForwardIt first, ForwardIt last, - OutputIt d_first) - { - - if (first == last) - return d_first; - - *d_first = *first; - while (++first != last) { - if (!(*d_first == *first)) { - *(++d_first) = *first; - } - } - return ++d_first; - } -.SH Second version - template - ForwardIt unique_copy(ForwardIt first, ForwardIt last, - OutputIt d_first, BinaryPredicate p) - { - - if (first == last) - return d_first; - - *d_first = *first; - while (++first != last) { - if (!p(*result, *first)) { - *(++d_first) = *first; - } - } - return ++d_first; - } + See also the implementations in libstdc++ and libc++. + +.SH Notes + + If InputIt satisfies LegacyForwardIterator, this function rereads the input in order + to detect duplicates. + + Otherwise, if OutputIt satisfies LegacyForwardIterator, and the value type of + InputIt is the same as that of OutputIt, this function compare *d_first to *first. + + Otherwise, this function compares *first to a local element copy. .SH Example - The following program trims all multiple consecutive spaces in a const string and - prints the result - // Run this code - #include - #include #include + #include #include - + #include + int main() { - std::string s1 = "The string with many spaces!"; - std::cout << "before: " << s1 << '\\n'; - + std::string s1 {"A string with mmmany letters!"}; + std::cout << "Before: " << s1 << '\\n'; + std::string s2; std::unique_copy(s1.begin(), s1.end(), std::back_inserter(s2), - [](char c1, char c2){ return c1 == ' ' && c2 == ' '; }); - - std::cout << "after: " << s2 << '\\n'; + [](char c1, char c2) { return c1 == 'm' && 'm' == c2; }); + + std::cout << "After: " << s2 << '\\n'; } .SH Output: - before: The string with many spaces! - after: The string with many spaces! + Before: A string with mmmany letters! + After: A string with many letters! -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - linear in the distance between first and last + DR Applied to Behavior as published Correct behavior + LWG 239 C++98 the predicate was applied applied one time fewer + std::distance(first, last) times (for non-empty ranges) + LWG 241 C++98 the value type of InputIt was not conditionally required + required to be CopyConstructible + LWG 538 C++98 the value type of InputIt was not conditionally required + required to be CopyAssignable + the value type of InputIt was not + LWG 2439 C++98 required to be conditionally required + CopyConstructible if OutputIt is a + LegacyForwardIterator .SH See also - finds two identical (or some other relationship) items adjacent to - adjacent_find each other - \fI(function template)\fP - unique removes consecutive duplicate elements in a range - \fI(function template)\fP + finds the first two adjacent items that are equal (or satisfy a + adjacent_find given predicate) + \fI(function template)\fP + unique removes consecutive duplicate elements in a range + \fI(function template)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + ranges::unique_copy creates a copy of some range of elements that contains no + (C++20) consecutive duplicates + (niebloid) diff --git a/man/std::unique_lock.3 b/man/std::unique_lock.3 index 94aa936e7..4948a930d 100644 --- a/man/std::unique_lock.3 +++ b/man/std::unique_lock.3 @@ -1,4 +1,7 @@ -.TH std::unique_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock \- std::unique_lock + .SH Synopsis Defined in header template< class Mutex > \fI(since C++11)\fP @@ -21,91 +24,124 @@ Mutex - the type of the mutex to lock. The type must meet the BasicLockable requirements -.SH Member types + Nested types Type Definition mutex_type Mutex .SH Member functions - constructor constructs a unique_lock, optionally locking the supplied mutex - \fI(public member function)\fP - destructor unlocks the associated mutex, if owned - \fI(public member function)\fP - operator= unlocks the mutex, if owned, and acquires ownership of another - \fI(public member function)\fP + constructs a unique_lock, optionally locking (i.e., taking ownership + constructor of) the supplied mutex + \fI(public member function)\fP + destructor unlocks (i.e., releases ownership of) the associated mutex, if owned + \fI(public member function)\fP + unlocks (i.e., releases ownership of) the mutex, if owned, and + operator= acquires ownership of another + \fI(public member function)\fP .SH Locking - lock locks the associated mutex - \fI(public member function)\fP - tries to lock the associated mutex, returns if the mutex is not - try_lock available - \fI(public member function)\fP - attempts to lock the associated TimedLockable mutex, returns if the - try_lock_for mutex has been unavailable for the specified time duration - \fI(public member function)\fP - tries to lock the associated TimedLockable mutex, returns if the - try_lock_until mutex has been unavailable until specified time point has been - reached - \fI(public member function)\fP - unlock unlocks the associated mutex - \fI(public member function)\fP + lock locks (i.e., takes ownership of) the associated mutex + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated mutex without + try_lock blocking + \fI(public member function)\fP + attempts to lock (i.e., takes ownership of) the associated + try_lock_for TimedLockable mutex, returns if the mutex has been unavailable for + the specified time duration + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated TimedLockable + try_lock_until mutex, returns if the mutex has been unavailable until specified time + point has been reached + \fI(public member function)\fP + unlock unlocks (i.e., releases ownership of) the associated mutex + \fI(public member function)\fP .SH Modifiers swap swaps state with another std::unique_lock - \fI(public member function)\fP - release disassociates the associated mutex without unlocking it - \fI(public member function)\fP + \fI(public member function)\fP + disassociates the associated mutex without unlocking (i.e., releasing + release ownership of) it + \fI(public member function)\fP .SH Observers mutex returns a pointer to the associated mutex - \fI(public member function)\fP - owns_lock tests whether the lock owns its associated mutex - \fI(public member function)\fP - operator bool tests whether the lock owns its associated mutex - \fI(public member function)\fP + \fI(public member function)\fP + owns_lock tests whether the lock owns (i.e., has locked) its associated mutex + \fI(public member function)\fP + operator bool tests whether the lock owns (i.e., has locked) its associated mutex + \fI(public member function)\fP .SH Non-member functions std::swap(std::unique_lock) specialization of std::swap for unique_lock - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code + #include #include #include - #include - - struct Box { + + struct Box + { explicit Box(int num) : num_things{num} {} - + int num_things; std::mutex m; }; - - void transfer(Box &from, Box &to, int num) + + void transfer(Box& from, Box& to, int num) { // don't actually take the locks yet - std::unique_lock lock1(from.m, std::defer_lock); - std::unique_lock lock2(to.m, std::defer_lock); - + std::unique_lock lock1{from.m, std::defer_lock}; + std::unique_lock lock2{to.m, std::defer_lock}; + // lock both unique_locks without deadlock std::lock(lock1, lock2); - + from.num_things -= num; to.num_things += num; - - // 'from.m' and 'to.m' mutexes unlocked in 'unique_lock' dtors + + // “from.m” and “to.m” mutexes unlocked in unique_lock dtors } - + int main() { - Box acc1(100); - Box acc2(50); - - std::thread t1(transfer, std::ref(acc1), std::ref(acc2), 10); - std::thread t2(transfer, std::ref(acc2), std::ref(acc1), 5); - + Box acc1{100}; + Box acc2{50}; + + std::thread t1{transfer, std::ref(acc1), std::ref(acc2), 10}; + std::thread t2{transfer, std::ref(acc2), std::ref(acc1), 5}; + t1.join(); t2.join(); + + std::cout << "acc1: " << acc1.num_things << "\\n" + "acc2: " << acc2.num_things << '\\n'; } + +.SH Output: + + acc1: 95 + acc2: 55 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2981 C++17 redundant deduction guide from removed + unique_lock was provided + +.SH See also + + lock locks specified mutexes, blocks if any are unavailable + \fI(C++11)\fP \fI(function template)\fP + lock_guard implements a strictly scope-based mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + scoped_lock deadlock-avoiding RAII wrapper for multiple mutexes + \fI(C++17)\fP \fI(class template)\fP + mutex provides basic mutual exclusion facility + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::unique_lock::lock.3 b/man/std::unique_lock::lock.3 index 60ee0b1c0..2da88574a 100644 --- a/man/std::unique_lock::lock.3 +++ b/man/std::unique_lock::lock.3 @@ -1,11 +1,12 @@ -.TH std::unique_lock::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::lock \- std::unique_lock::lock + .SH Synopsis void lock(); \fI(since C++11)\fP - Locks the associated mutex. Effectively calls mutex()->lock(). - - std::system_error is thrown if there is no associated mutex or if the mutex is - already locked. + Locks (i.e., takes ownership of) the associated mutex. Effectively calls + mutex()->lock(). .SH Parameters @@ -17,50 +18,52 @@ .SH Exceptions - * Any exceptions thrown by mutex()->lock() - + * Any exceptions thrown by mutex()->lock(). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - - * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::operation_not_permitted. + * If the mutex is already locked by this unique_lock (in other words, owns_lock is + true), std::system_error with an error code of + std::errc::resource_deadlock_would_occur. .SH Example The following example uses lock to re-acquire a mutex that was unlocked. - + // Run this code + #include + #include #include #include - #include #include - #include - + int main() { int counter = 0; std::mutex counter_mutex; std::vector threads; - - auto worker_task = [&](int id) { + + auto worker_task = [&](int id) + { std::unique_lock lock(counter_mutex); ++counter; std::cout << id << ", initial counter: " << counter << '\\n'; lock.unlock(); - + // don't hold the lock while we simulate an expensive operation std::this_thread::sleep_for(std::chrono::seconds(1)); - + lock.lock(); ++counter; std::cout << id << ", final counter: " << counter << '\\n'; }; - - for (int i = 0; i < 10; ++i) threads.emplace_back(worker_task, i); - - for (auto &thread : threads) thread.join(); + + for (int i = 0; i < 10; ++i) + threads.emplace_back(worker_task, i); + + for (auto& thread : threads) + thread.join(); } .SH Possible output: @@ -88,7 +91,8 @@ .SH See also - try_lock tries to lock the associated mutex, returns if the mutex is not available - \fI(public member function)\fP - unlock unlocks the associated mutex - \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated mutex without + try_lock blocking + \fI(public member function)\fP + unlock unlocks (i.e., releases ownership of) the associated mutex + \fI(public member function)\fP diff --git a/man/std::unique_lock::mutex.3 b/man/std::unique_lock::mutex.3 index 3ceb24ced..e6eb24175 100644 --- a/man/std::unique_lock::mutex.3 +++ b/man/std::unique_lock::mutex.3 @@ -1,6 +1,9 @@ -.TH std::unique_lock::mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::mutex \- std::unique_lock::mutex + .SH Synopsis - mutex_type* mutex() const; \fI(since C++11)\fP + mutex_type* mutex() const noexcept; \fI(since C++11)\fP Returns a pointer to the associated mutex, or a null pointer if there is no associated mutex. @@ -13,17 +16,10 @@ Pointer to the associated mutex or a null pointer if there is no associated mutex. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example This section is incomplete Reason: no example .SH Category: - * Todo no example diff --git a/man/std::unique_lock::operator=.3 b/man/std::unique_lock::operator=.3 index d06e31938..da75557bc 100644 --- a/man/std::unique_lock::operator=.3 +++ b/man/std::unique_lock::operator=.3 @@ -1,4 +1,7 @@ -.TH std::unique_lock::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::operator= \- std::unique_lock::operator= + .SH Synopsis unique_lock& operator=( unique_lock&& other ); \fI(since C++11)\fP @@ -18,6 +21,20 @@ .SH Exceptions - noexcept specification: - noexcept - + Throws nothing. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the move assignment operator was noexcept, + LWG 2104 C++11 but it may it is not noexcept + throw an exception in the case of undefined + behavior^[1] + + 1. ↑ For example, *this is constructed with std::adopt_lock, but the calling thread + does not have the ownership of the associated mutex. In this case, *this cannot + properly release the ownership of the associated mutex, and it may result in an + exception to be thrown. diff --git a/man/std::unique_lock::operatorbool.3 b/man/std::unique_lock::operatorbool.3 index e9450c59a..f0f4bac2b 100644 --- a/man/std::unique_lock::operatorbool.3 +++ b/man/std::unique_lock::operatorbool.3 @@ -1,6 +1,9 @@ -.TH std::unique_lock::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::operatorbool \- std::unique_lock::operatorbool + .SH Synopsis - explicit operator bool() const; \fI(since C++11)\fP + explicit operator bool() const noexcept; \fI(since C++11)\fP Checks whether *this owns a locked mutex or not. Effectively calls owns_lock(). @@ -13,13 +16,7 @@ true if *this has an associated mutex and has acquired ownership of it, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also - owns_lock tests whether the lock owns its associated mutex - \fI(public member function)\fP + owns_lock tests whether the lock owns (i.e., has locked) its associated mutex + \fI(public member function)\fP diff --git a/man/std::unique_lock::owns_lock.3 b/man/std::unique_lock::owns_lock.3 index 664da78fd..bc53eeb69 100644 --- a/man/std::unique_lock::owns_lock.3 +++ b/man/std::unique_lock::owns_lock.3 @@ -1,6 +1,9 @@ -.TH std::unique_lock::owns_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::owns_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::owns_lock \- std::unique_lock::owns_lock + .SH Synopsis - bool owns_lock() const; \fI(since C++11)\fP + bool owns_lock() const noexcept; \fI(since C++11)\fP Checks whether *this owns a locked mutex or not. @@ -13,13 +16,7 @@ true if *this has an associated mutex and has acquired ownership of it, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also - operator bool tests whether the lock owns its associated mutex - \fI(public member function)\fP + operator bool tests whether the lock owns (i.e., has locked) its associated mutex + \fI(public member function)\fP diff --git a/man/std::unique_lock::release.3 b/man/std::unique_lock::release.3 index a9cbac890..6121616b9 100644 --- a/man/std::unique_lock::release.3 +++ b/man/std::unique_lock::release.3 @@ -1,11 +1,14 @@ -.TH std::unique_lock::release 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::release \- std::unique_lock::release + .SH Synopsis - mutex_type* release(); \fI(since C++11)\fP + mutex_type* release() noexcept; \fI(since C++11)\fP Breaks the association of the associated mutex, if any, and *this. - No locks are unlocked. If the *this held ownership of the associated mutex prior to - the call, the caller is now responsible to unlock the mutex. + No locks are unlocked. If *this held ownership of the associated mutex prior to the + call, the caller is now responsible to unlock the mutex. .SH Parameters @@ -13,13 +16,7 @@ .SH Return value - Pointer to the associated mutex or NULL if there was no associated mutex. - -.SH Exceptions - - noexcept specification: - noexcept - + Pointer to the associated mutex or a null pointer if there was no associated mutex. .SH Example @@ -28,9 +25,8 @@ .SH See also - unlock unlocks the associated mutex - \fI(public member function)\fP + unlock unlocks (i.e., releases ownership of) the associated mutex + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unique_lock::swap.3 b/man/std::unique_lock::swap.3 index 7cf31a151..9be893268 100644 --- a/man/std::unique_lock::swap.3 +++ b/man/std::unique_lock::swap.3 @@ -1,7 +1,9 @@ -.TH std::unique_lock::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::swap \- std::unique_lock::swap + .SH Synopsis - template< class Mutex > \fI(since C++11)\fP - void swap( unique_lock& other ); + void swap( unique_lock& other ) noexcept; \fI(since C++11)\fP Exchanges the internal states of the lock objects. @@ -13,22 +15,32 @@ \fI(none)\fP -.SH Exceptions +.SH Example - noexcept specification: - noexcept - -.SH Example +// Run this code - This section is incomplete - Reason: no example + #include + #include -.SH See also + int main() + { + std::mutex mtx1; + std::unique_lock guard1(mtx1); + std::unique_lock guard2; + guard2.swap(guard1); - std::swap(std::unique_lock) specialization of std::swap for unique_lock - \fI(C++11)\fP \fI(function template)\fP + if (!guard1 && guard2) + std::cout << "swapped success\\n"; -.SH Category: + return 0; + } - * Todo no example +.SH Output: + + swapped success + +.SH See also + + std::swap(std::unique_lock) specialization of std::swap for unique_lock + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::unique_lock::try_lock.3 b/man/std::unique_lock::try_lock.3 index cd5a36306..31504fb35 100644 --- a/man/std::unique_lock::try_lock.3 +++ b/man/std::unique_lock::try_lock.3 @@ -1,12 +1,15 @@ -.TH std::unique_lock::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::try_lock \- std::unique_lock::try_lock + .SH Synopsis bool try_lock(); \fI(since C++11)\fP - Tries to lock the associated mutex without blocking. Effectively calls - mutex()->try_lock(). + Tries to lock (i.e., takes ownership of) the associated mutex without blocking. + Effectively calls mutex()->try_lock(). std::system_error is thrown if there is no associated mutex or if the mutex is - already locked. + already locked by this std::unique_lock. .SH Parameters @@ -18,33 +21,81 @@ .SH Exceptions - * Any exceptions thrown by mutex()->try_lock() - + * Any exceptions thrown by mutex()->try_lock() (Mutex types do not throw in + try_lock, but a custom Lockable might). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - - * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::operation_not_permitted. + * If the mutex is already locked by this std::unique_lock, std::system_error with + an error code of std::errc::resource_deadlock_would_occur. .SH Example - This section is incomplete - Reason: no example + The following examples try to acquire a mutex that was locked and unlocked. + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono_literals; + + int main() + { + std::mutex counter_mutex; + std::vector threads; + using Id = int; + + auto worker_task = [&](Id id, std::chrono::seconds wait, std::chrono::seconds acquire) + { + // wait for a few seconds before acquiring lock. + std::this_thread::sleep_for(wait); + + std::unique_lock lock(counter_mutex, std::defer_lock); + if (lock.try_lock()) + std::cout << '#' << id << ", lock acquired.\\n"; + else + { + std::cout << '#' << id << ", failed acquiring lock.\\n"; + return; + } + + // keep the lock for a while. + std::this_thread::sleep_for(acquire); + + std::cout << '#' << id << ", releasing lock (via destructor).\\n"; + }; + + threads.emplace_back(worker_task, Id{0}, 0s, 2s); + threads.emplace_back(worker_task, Id{1}, 1s, 0s); + threads.emplace_back(worker_task, Id{2}, 3s, 0s); + + for (auto& thread : threads) + thread.join(); + } + +.SH Output: + + #0, lock acquired. + #1, failed acquiring lock. + #0, releasing lock (via destructor). + #2, lock acquired. + #2, releasing lock (via destructor). .SH See also - lock locks the associated mutex - \fI(public member function)\fP - attempts to lock the associated TimedLockable mutex, returns if the - try_lock_for mutex has been unavailable for the specified time duration - \fI(public member function)\fP - tries to lock the associated TimedLockable mutex, returns if the - try_lock_until mutex has been unavailable until specified time point has been - reached - \fI(public member function)\fP - unlock unlocks the associated mutex - \fI(public member function)\fP - -.SH Category: - - * Todo no example + lock locks (i.e., takes ownership of) the associated mutex + \fI(public member function)\fP + attempts to lock (i.e., takes ownership of) the associated + try_lock_for TimedLockable mutex, returns if the mutex has been unavailable for + the specified time duration + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated TimedLockable + try_lock_until mutex, returns if the mutex has been unavailable until specified time + point has been reached + \fI(public member function)\fP + unlock unlocks (i.e., releases ownership of) the associated mutex + \fI(public member function)\fP diff --git a/man/std::unique_lock::try_lock_for.3 b/man/std::unique_lock::try_lock_for.3 index 05a1f9be6..8e5fb7232 100644 --- a/man/std::unique_lock::try_lock_for.3 +++ b/man/std::unique_lock::try_lock_for.3 @@ -1,19 +1,26 @@ -.TH std::unique_lock::try_lock_for 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::try_lock_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::try_lock_for \- std::unique_lock::try_lock_for + .SH Synopsis template< class Rep, class Period > - bool try_lock_for( const std::chrono::duration& \fI(since C++11)\fP + bool try_lock_for( const std::chrono::duration& \fI(since C++11)\fP timeout_duration ); - Tries to lock the associated mutex. Blocks until specified timeout_duration has - elapsed or the lock is acquired, whichever comes first. On successful lock - acquisition returns true, otherwise returns false. Effectively calls - mutex()->try_lock_for(timeout_duration). + Tries to lock (i.e., takes ownership of) the associated mutex. Blocks until + specified timeout_duration has elapsed or the lock is acquired, whichever comes + first. On successful lock acquisition returns true, otherwise returns false. + Effectively calls mutex()->try_lock_for(timeout_duration). + + This function may block for longer than timeout_duration due to scheduling or + resource contention delays. - A steady clock is used to measure the duration. This function may block for longer - than timeout_duration due to scheduling or resource contention delays. + The standard recommends that a steady clock is used to measure the duration. If an + implementation uses a system clock instead, the wait time may also be sensitive to + clock adjustments. std::system_error is thrown if there is no associated mutex or if the mutex is - already locked. + already locked by this std::unique_lock. .SH Parameters @@ -25,13 +32,11 @@ .SH Exceptions - * Any exceptions thrown by mutex()->try_lock_for(timeout_duration) - + * Any exceptions thrown by mutex()->try_lock_for(timeout_duration). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - + std::errc::operation_not_permitted. * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::resource_deadlock_would_occur. .SH Example @@ -40,18 +45,19 @@ .SH See also - lock locks the associated mutex - \fI(public member function)\fP - tries to lock the associated mutex, returns if the mutex is not - try_lock available - \fI(public member function)\fP - tries to lock the associated TimedLockable mutex, returns if the - try_lock_until mutex has been unavailable until specified time point has been - reached - \fI(public member function)\fP - unlock unlocks the associated mutex - \fI(public member function)\fP + lock locks (i.e., takes ownership of) the associated mutex + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated mutex without + try_lock blocking + \fI(public member function)\fP + try_lock_for tries to lock the associated mutex, for the specified duration + \fI(public member function of std::shared_lock)\fP + tries to lock (i.e., takes ownership of) the associated TimedLockable + try_lock_until mutex, returns if the mutex has been unavailable until specified time + point has been reached + \fI(public member function)\fP + unlock unlocks (i.e., releases ownership of) the associated mutex + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unique_lock::try_lock_until.3 b/man/std::unique_lock::try_lock_until.3 index 788f65f5d..12917f313 100644 --- a/man/std::unique_lock::try_lock_until.3 +++ b/man/std::unique_lock::try_lock_until.3 @@ -1,18 +1,25 @@ -.TH std::unique_lock::try_lock_until 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::try_lock_until 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::try_lock_until \- std::unique_lock::try_lock_until + .SH Synopsis template< class Clock, class Duration > - bool try_lock_until( const std::chrono::time_point& \fI(since C++11)\fP + bool try_lock_until( const std::chrono::time_point& \fI(since C++11)\fP timeout_time ); - Tries to lock the associated mutex. Blocks until specified timeout_time has been - reached or the lock is acquired, whichever comes first. On successful lock - acquisition returns true, otherwise returns false. May block for longer than until - timeout_time has been reached. + Tries to lock (i.e., takes ownership of) the associated mutex. Blocks until + specified timeout_time has been reached or the lock is acquired, whichever comes + first. On successful lock acquisition returns true, otherwise returns false. May + block for longer than timeout_time until has been reached. - Effectively calls mutex()->try_lock_until(timeout_time) + Effectively calls mutex()->try_lock_until(timeout_time). std::system_error is thrown if there is no associated mutex or if the mutex is - already locked. + already locked by the same thread. + + Clock must meet the Clock requirements. + The program is ill-formed if std::chrono::is_clock_v is false. + \fI(since C++20)\fP .SH Parameters @@ -24,13 +31,11 @@ .SH Exceptions - * Any exceptions thrown by mutex()->try_lock_for(timeout_time) - + * Any exceptions thrown by mutex()->try_lock_until(timeout_time). * If there is no associated mutex, std::system_error with an error code of - std::errc::operation_not_permitted - + std::errc::operation_not_permitted. * If the mutex is already locked, std::system_error with an error code of - std::errc::resource_deadlock_would_occur + std::errc::resource_deadlock_would_occur. .SH Example @@ -39,17 +44,17 @@ .SH See also - lock locks the associated mutex - \fI(public member function)\fP - tries to lock the associated mutex, returns if the mutex is not - try_lock available - \fI(public member function)\fP - attempts to lock the associated TimedLockable mutex, returns if the - try_lock_for mutex has been unavailable for the specified time duration - \fI(public member function)\fP - unlock unlocks the associated mutex - \fI(public member function)\fP + lock locks (i.e., takes ownership of) the associated mutex + \fI(public member function)\fP + tries to lock (i.e., takes ownership of) the associated mutex without + try_lock blocking + \fI(public member function)\fP + attempts to lock (i.e., takes ownership of) the associated + try_lock_for TimedLockable mutex, returns if the mutex has been unavailable for the + specified time duration + \fI(public member function)\fP + unlock unlocks (i.e., releases ownership of) the associated mutex + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unique_lock::unique_lock.3 b/man/std::unique_lock::unique_lock.3 index a684adf17..9eefa41ba 100644 --- a/man/std::unique_lock::unique_lock.3 +++ b/man/std::unique_lock::unique_lock.3 @@ -1,22 +1,25 @@ -.TH std::unique_lock::unique_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::unique_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::unique_lock \- std::unique_lock::unique_lock + .SH Synopsis - unique_lock(); \fB(1)\fP \fI(since C++11)\fP - unique_lock( unique_lock&& other ); \fB(2)\fP \fI(since C++11)\fP + unique_lock() noexcept; \fB(1)\fP \fI(since C++11)\fP + unique_lock( unique_lock&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP explicit unique_lock( mutex_type& m ); \fB(3)\fP \fI(since C++11)\fP - unique_lock( mutex_type& m, std::defer_lock_t t ); \fB(4)\fP \fI(since C++11)\fP + unique_lock( mutex_type& m, std::defer_lock_t t ) noexcept; \fB(4)\fP \fI(since C++11)\fP unique_lock( mutex_type& m, std::try_to_lock_t t ); \fB(5)\fP \fI(since C++11)\fP unique_lock( mutex_type& m, std::adopt_lock_t t ); \fB(6)\fP \fI(since C++11)\fP template< class Rep, class Period > unique_lock( mutex_type& m, \fB(7)\fP \fI(since C++11)\fP - const std::chrono::duration& + const std::chrono::duration& timeout_duration ); template< class Clock, class Duration > unique_lock( mutex_type& m, \fB(8)\fP \fI(since C++11)\fP - const std::chrono::time_point& + const std::chrono::time_point& timeout_time ); Constructs a unique_lock, optionally locking the supplied mutex. @@ -25,20 +28,21 @@ 2) Move constructor. Initializes the unique_lock with the contents of other. Leaves other with no associated mutex. 3-8) Constructs a unique_lock with m as the associated mutex. Additionally: - 3) Locks the associated mutex by calling m.lock(). The behavior is undefined if the - current thread already owns the mutex except when the mutex is recursive. + 3) Locks the associated mutex by calling m.lock(). 4) Does not lock the associated mutex. 5) Tries to lock the associated mutex without blocking by calling m.try_lock(). The - behavior is undefined if the current thread already owns the mutex except when the - mutex is recursive. - 6) Assumes the calling thread already owns m. + behavior is undefined if Mutex does not satisfy Lockable. + 6) Assumes the calling thread already holds a non-shared lock (i.e., a lock acquired + by lock, try_lock, try_lock_for, or try_lock_until) on m. The behavior is undefined + if not so. 7) Tries to lock the associated mutex by calling m.try_lock_for(timeout_duration). Blocks until specified timeout_duration has elapsed or the lock is acquired, - whichever comes first. May block for longer than timeout_duration. + whichever comes first. May block for longer than timeout_duration. The behavior is + undefined if Mutex does not satisfy TimedLockable. 8) Tries to lock the associated mutex by calling m.try_lock_until(timeout_time). Blocks until specified timeout_time has been reached or the lock is acquired, whichever comes first. May block for longer than until timeout_time has been - reached. + reached. The behavior is undefined if Mutex does not satisfy TimedLockable. .SH Parameters @@ -50,111 +54,48 @@ timeout_duration - maximum duration to block for timeout_time - maximum time point to block until -.SH Exceptions - - 1, 2, 4) - noexcept specification: - noexcept - - .SH Example - + // Run this code - #include - #include // std::cout + #include + #include #include + #include #include - #include - - class Number; - std::ostream& operator<<(std::ostream& stream, const Number& number); - - class Number { - public: - Number() : v_(1) {} - - // thread-safe update of 'a' and 'b' - static void update(Number& a, Number& b, bool order) { - // do not lock 'mutex_' of 'a' and 'b' sequentially, - // two sequential lock may lead to deadlock, - // that's why 'std::lock' exists (see below) - GuardLock lock_a(a.mutex_, std::defer_lock); - GuardLock lock_b(b.mutex_, std::defer_lock); - - // mutexes is not locked - assert(!lock_a.owns_lock()); - assert(!lock_b.owns_lock()); - - // unspecified series of calls... - std::lock(lock_a, lock_b); - - // Result: 'a.mutex_' and 'b.mutex_' is in locked state - // 'a' and 'b' can be modified safety - assert(lock_a.owns_lock()); - assert(lock_b.owns_lock()); - - if (order) { - a.v_ += b.v_; - b.v_ += a.v_; - - std::cout << a << b; + + std::mutex m_a, m_b, m_c; + int a, b, c = 1; + + void update() + { + { // Note: std::lock_guard or atomic can be used instead + std::unique_lock lk(m_a); + ++a; } - else { - b.v_ += a.v_; - a.v_ += b.v_; - - std::cout << b << a; + + { // Note: see std::lock and std::scoped_lock for details and alternatives + std::unique_lock lk_b(m_b, std::defer_lock); + std::unique_lock lk_c(m_c, std::defer_lock); + std::lock(lk_b, lk_c); + b = std::exchange(c, b + c); } - - // 'lock_a' and 'lock_b' will be destroyed, - // unlocking 'a.mutex_' and 'b.mutex_' - } - - // not thread-safe; used before thread creation or in thread-safe 'update' - std::ostream& print(std::ostream& stream) const { - stream << v_ << " "; - return stream; - } - - private: - using Mutex = std::mutex; - using GuardLock = std::unique_lock; - - Mutex mutex_; - int v_; - }; - - // not thread-safe; see 'Number::print' - std::ostream& operator<<(std::ostream& stream, const Number& number) { - return number.print(stream); } - - int main() { - Number a, b; - std::cout << a << b; - - std::vector threads; - - for (unsigned i = 0; i < 4; ++i) { - // without 'std::lock' deadlock may occur in this situation: - // thread #1 lock 'a.mutex_' - // thread #2 lock 'b.mutex_' - // thread #1 try to lock 'b.mutex_' and blocked (it's locked by #2) - // thread #2 try to lock 'a.mutex_' and blocked (it's locked by #1) - // ... deadlock - threads.emplace_back(Number::update, std::ref(a), std::ref(b), true); // #1 - threads.emplace_back(Number::update, std::ref(b), std::ref(a), false); // #2 - } - - for (auto& i: threads) { - i.join(); - } - - std::cout << '\\n'; + + int main() + { + std::vector threads; + for (unsigned i = 0; i < 12; ++i) + threads.emplace_back(update); + + for (auto& i : threads) + i.join(); + + std::cout << a << "'th and " << a + 1 << "'th Fibonacci numbers: " + << b << " and " << c << '\\n'; } .SH Output: - 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 + 12'th and 13'th Fibonacci numbers: 144 and 233 diff --git a/man/std::unique_lock::unlock.3 b/man/std::unique_lock::unlock.3 index d029c1af9..1576b94fa 100644 --- a/man/std::unique_lock::unlock.3 +++ b/man/std::unique_lock::unlock.3 @@ -1,8 +1,11 @@ -.TH std::unique_lock::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::unlock \- std::unique_lock::unlock + .SH Synopsis void unlock(); \fI(since C++11)\fP - Unlocks the associated mutex and releases ownership. + Unlocks (i.e., releases ownership of) the associated mutex and releases ownership. std::system_error is thrown if there is no associated mutex or if the mutex is not locked. @@ -17,10 +20,9 @@ .SH Exceptions - * Any exceptions thrown by mutex()->unlock() - + * Any exceptions thrown by mutex()->unlock(). * If there is no associated mutex or the mutex is not locked, std::system_error - with an error code of std::errc::operation_not_permitted + with an error code of std::errc::operation_not_permitted. .SH Example @@ -29,11 +31,11 @@ .SH See also - lock locks the associated mutex - \fI(public member function)\fP - release disassociates the associated mutex without unlocking it - \fI(public member function)\fP + lock locks (i.e., takes ownership of) the associated mutex + \fI(public member function)\fP + disassociates the associated mutex without unlocking (i.e., releasing + release ownership of) it + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unique_lock::~unique_lock.3 b/man/std::unique_lock::~unique_lock.3 index 07d0a7b4d..8e9744518 100644 --- a/man/std::unique_lock::~unique_lock.3 +++ b/man/std::unique_lock::~unique_lock.3 @@ -1,4 +1,7 @@ -.TH std::unique_lock::~unique_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_lock::~unique_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_lock::~unique_lock \- std::unique_lock::~unique_lock + .SH Synopsis ~unique_lock(); \fI(since C++11)\fP diff --git a/man/std::unique_ptr.3 b/man/std::unique_ptr.3 index 46a8ed816..009752bb7 100644 --- a/man/std::unique_ptr.3 +++ b/man/std::unique_ptr.3 @@ -1,4 +1,7 @@ -.TH std::unique_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr \- std::unique_ptr + .SH Synopsis Defined in header template< @@ -14,64 +17,84 @@ > class unique_ptr; - std::unique_ptr is a smart pointer that retains sole ownership of an object through - a pointer and destroys that object when the unique_ptr goes out of scope. No two - unique_ptr instances can manage the same object. + std::unique_ptr is a smart pointer that owns and manages another object through a + pointer and disposes of that object when the unique_ptr goes out of scope. - The object is destroyed and its memory deallocated when either of the following + The object is disposed of, using the associated deleter when either of the following happens: - * unique_ptr managing the object is destroyed - * unique_ptr managing the object is assigned another pointer via operator= or + * the managing unique_ptr object is destroyed. + * the managing unique_ptr object is assigned another pointer via operator= or reset(). - The object is destroyed using a potentially user-supplied deleter by calling - Deleter(ptr). The deleter calls the destructor of the object and dispenses the - memory. + The object is disposed of, using a potentially user-supplied deleter by calling + get_deleter()(ptr). The default deleter uses the delete operator, which destroys the + object and deallocates the memory. - A unique_ptr may also own no objects, in which case it is called empty. + A unique_ptr may alternatively own no object, in which case it is called empty. There are two versions of std::unique_ptr: - 1) Manages the lifetime of a single object (e.g. allocated with new) - 2) Manages the lifetime of a dynamically-allocated array of objects (e.g. allocated - with new[]) + 1. Manages a single object (e.g. allocated with new). + 2. Manages a dynamically-allocated array of objects (e.g. allocated with new[]). - The class satisfies the requirements of MoveConstructible and MoveAssignable, but - not the requirements of either CopyConstructible or CopyAssignable. + The class satisfies the requirements of MoveConstructible and MoveAssignable, but of + neither CopyConstructible nor CopyAssignable. .SH Type requirements - Deleter must be FunctionObject or lvalue reference to a FunctionObject or lvalue reference to function, callable with an argument of type unique_ptr::pointer + Deleter>::pointer. .SH Notes Only non-const unique_ptr can transfer the ownership of the managed object to - another unique_ptr. The lifetime of an object managed by const std::unique_ptr is - limited to the scope in which the pointer was created. + another unique_ptr. If an object's lifetime is managed by a const std::unique_ptr, + it is limited to the scope in which the pointer was created. - Typical uses of std::unique_ptr include: + std::unique_ptr is commonly used to manage the lifetime of objects, including: * providing exception safety to classes and functions that handle objects with dynamic lifetime, by guaranteeing deletion on both normal exit and exit through - exception - - * passing ownership of uniquely-owned objects with dynamic lifetime into functions - + exception. + * passing ownership of uniquely-owned objects with dynamic lifetime into + functions. * acquiring ownership of uniquely-owned objects with dynamic lifetime from - functions - + functions. * as the element type in move-aware containers, such as std::vector, which hold pointers to dynamically-allocated objects (e.g. if polymorphic behavior is - desired) + desired). + + std::unique_ptr may be constructed for an incomplete type T, such as to facilitate + the use as a handle in the pImpl idiom. If the default deleter is used, T must be + complete at the point in code where the deleter is invoked, which happens in the + destructor, move assignment operator, and reset member function of std::unique_ptr. + (Conversely, std::shared_ptr can't be constructed from a raw pointer to incomplete + type, but can be destroyed where T is incomplete). Note that if T is a class + template specialization, use of unique_ptr as an operand, e.g. !p requires T's + parameters to be complete due to ADL. + + If T is a derived class of some base B, then std::unique_ptr is implicitly + convertible to std::unique_ptr. The default deleter of the resulting + std::unique_ptr will use operator delete for B, leading to undefined behavior + unless the destructor of B is virtual. Note that std::shared_ptr behaves + differently: std::shared_ptr will use the operator delete for the type T and the + owned object will be deleted correctly even if the destructor of B is not virtual. + + Unlike std::shared_ptr, std::unique_ptr may manage an object through any custom + handle type that satisfies NullablePointer. This allows, for example, managing + objects located in shared memory, by supplying a Deleter that defines typedef + boost::offset_ptr pointer; or another fancy pointer. + + Feature-test macro Value Std Feature + __cpp_lib_constexpr_memory 202202L (C++23) constexpr std::unique_ptr .SH Member types Member type Definition pointer std::remove_reference::type::pointer if that type exists, - otherwise T* + otherwise T*. Must satisfy NullablePointer element_type T, the type of the object managed by this unique_ptr deleter_type Deleter, the function object or lvalue reference to function or to function object, to be called from the destructor @@ -79,93 +102,230 @@ .SH Member functions constructor constructs a new unique_ptr - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the managed object if such is present - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the unique_ptr - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers release returns a pointer to the managed object and releases the ownership - \fI(public member function)\fP + \fI(public member function)\fP reset replaces the managed object - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the managed objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers get returns a pointer to the managed object - \fI(public member function)\fP + \fI(public member function)\fP get_deleter returns the deleter that is used for destruction of the managed object - \fI(public member function)\fP - operator bool checks if there is associated managed object - \fI(public member function)\fP + \fI(public member function)\fP + operator bool checks if there is an associated managed object + \fI(public member function)\fP .SH Single-object version, unique_ptr operator* dereferences pointer to the managed object - operator-> \fI(public member function)\fP + operator-> \fI(public member function)\fP .SH Array version, unique_ptr operator[] provides indexed access to the managed array - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - make_unique creates a unique pointer that manages a new object - \fI(C++14)\fP \fI(function template)\fP + make_unique + make_unique_for_overwrite creates a unique pointer that manages a new object + \fI(C++14)\fP \fI(function template)\fP + (C++20) operator== operator!= - operator< compares to another unique_ptr or with nullptr - operator<= \fI(function template)\fP - operator> + operator< + operator<= compares to another unique_ptr or with nullptr + operator> \fI(function template)\fP operator>= - std::swap(std::unique_ptr) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + operator<=> + (removed in C++20) + (C++20) + operator<<(std::unique_ptr) outputs the value of the managed pointer to an output + (C++20) stream + \fI(function template)\fP + std::swap(std::unique_ptr) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes std::hash hash support for std::unique_ptr - \fI(C++11)\fP \fI(class template specialization)\fP + \fI(C++11)\fP \fI(class template specialization)\fP .SH Example - + // Run this code + #include + #include + #include #include + #include #include - - struct Foo + #include + + // helper class for runtime polymorphism demo below + struct B { - Foo() { std::cout << "Foo::Foo\\n"; } - ~Foo() { std::cout << "Foo::~Foo\\n"; } - void bar() { std::cout << "Foo::bar\\n"; } + virtual ~B() = default; + + virtual void bar() { std::cout << "B::bar\\n"; } }; - - void f(const Foo &) + + struct D : B + { + D() { std::cout << "D::D\\n"; } + ~D() { std::cout << "D::~D\\n"; } + + void bar() override { std::cout << "D::bar\\n"; } + }; + + // a function consuming a unique_ptr can take it by value or by rvalue reference + std::unique_ptr pass_through(std::unique_ptr p) + { + p->bar(); + return p; + } + + // helper function for the custom deleter demo below + void close_file(std::FILE* fp) { - std::cout << "f(const Foo&)\\n"; + std::fclose(fp); } - + + // unique_ptr-based linked list demo + struct List + { + struct Node + { + int data; + std::unique_ptr next; + }; + + std::unique_ptr head; + + ~List() + { + // destroy list nodes sequentially in a loop, the default destructor + // would have invoked its `next`'s destructor recursively, which would + // cause stack overflow for sufficiently large lists. + while (head) + { + auto next = std::move(head->next); + head = std::move(next); + } + } + + void push(int data) + { + head = std::unique_ptr(new Node{data, std::move(head)}); + } + }; + int main() { - std::unique_ptr p1(new Foo); // p1 owns Foo - if (p1) p1->bar(); - + std::cout << "1) Unique ownership semantics demo\\n"; { - std::unique_ptr p2(std::move(p1)); // now p2 owns Foo - f(*p2); - - p1 = std::move(p2); // ownership returns to p1 - std::cout << "destroying p2...\\n"; + // Create a (uniquely owned) resource + std::unique_ptr p = std::make_unique(); + + // Transfer ownership to `pass_through`, + // which in turn transfers ownership back through the return value + std::unique_ptr q = pass_through(std::move(p)); + + // p is now in a moved-from 'empty' state, equal to nullptr + assert(!p); + } + + std::cout << "\\n" "2) Runtime polymorphism demo\\n"; + { + // Create a derived resource and point to it via base type + std::unique_ptr p = std::make_unique(); + + // Dynamic dispatch works as expected + p->bar(); } - - if (p1) p1->bar(); - - // Foo instance is destroyed when p1 goes out of scope + + std::cout << "\\n" "3) Custom deleter demo\\n"; + std::ofstream("demo.txt") << 'x'; // prepare the file to read + { + using unique_file_t = std::unique_ptr; + unique_file_t fp(std::fopen("demo.txt", "r"), &close_file); + if (fp) + std::cout << char(std::fgetc(fp.get())) << '\\n'; + } // `close_file()` called here (if `fp` is not null) + + std::cout << "\\n" "4) Custom lambda-expression deleter and exception safety demo\\n"; + try + { + std::unique_ptr p(new D, [](D* ptr) + { + std::cout << "destroying from a custom deleter...\\n"; + delete ptr; + }); + + throw std::runtime_error(""); // `p` would leak here if it were a plain pointer + } + catch (const std::exception&) + { + std::cout << "Caught exception\\n"; + } + + std::cout << "\\n" "5) Array form of unique_ptr demo\\n"; + { + std::unique_ptr p(new D[3]); + } // `D::~D()` is called 3 times + + std::cout << "\\n" "6) Linked list demo\\n"; + { + List wall; + const int enough{1'000'000}; + for (int beer = 0; beer != enough; ++beer) + wall.push(beer); + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << enough << " bottles of beer on the wall...\\n"; + } // destroys all the beers } -.SH Output: +.SH Possible output: + + 1) Unique ownership semantics demo + D::D + D::bar + D::~D + + 2) Runtime polymorphism demo + D::D + D::bar + D::~D + + 3) Custom deleter demo + x + + 4) Custom lambda-expression deleter and exception safety demo + D::D + destroying from a custom deleter... + D::~D + Caught exception + + 5) Array form of unique_ptr demo + D::D + D::D + D::D + D::~D + D::~D + D::~D + + 6) Linked list demo + 1,000,000 bottles of beer on the wall... + +.SH See also - Foo::Foo - Foo::bar - f(const Foo&) - destroying p2... - Foo::bar - Foo::~Foo + shared_ptr smart pointer with shared object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + weak_ptr weak reference to an object managed by std::shared_ptr + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::unique_ptr::get.3 b/man/std::unique_ptr::get.3 index 298ede86b..18f677121 100644 --- a/man/std::unique_ptr::get.3 +++ b/man/std::unique_ptr::get.3 @@ -1,6 +1,10 @@ -.TH std::unique_ptr::get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::get \- std::unique_ptr::get + .SH Synopsis - pointer get() const; \fI(since C++11)\fP + pointer get() const noexcept; \fI(since C++11)\fP + (constexpr since C++23) Returns a pointer to the managed object or nullptr if no object is owned. @@ -12,33 +16,53 @@ Pointer to the managed object or nullptr if no object is owned. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code + #include #include - #include #include - + #include + #include + + class Res + { + std::string s; + + public: + Res(std::string arg) : s{std::move(arg)} + { + std::cout << "Res::Res(" << std::quoted(s) << ");\\n"; + } + + ~Res() + { + std::cout << "Res::~Res();\\n"; + } + + private: + friend std::ostream& operator<<(std::ostream& os, Res const& r) + { + return os << "Res { s = " << std::quoted(r.s) << "; }"; + } + }; + int main() { - std::unique_ptr s_p(new std::string("Hello, world!")); - std::string *s = s_p.get(); - std::cout << *s << '\\n'; + std::unique_ptr up(new Res{"Hello, world!"}); + Res* res = up.get(); + std::cout << *res << '\\n'; } .SH Output: - Hello, world! + Res::Res("Hello, world!"); + Res { s = "Hello, world!"; } + Res::~Res(); .SH See also release returns a pointer to the managed object and releases the ownership - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unique_ptr::get_deleter.3 b/man/std::unique_ptr::get_deleter.3 index 4c1f15e85..2f06583ec 100644 --- a/man/std::unique_ptr::get_deleter.3 +++ b/man/std::unique_ptr::get_deleter.3 @@ -1,7 +1,12 @@ -.TH std::unique_ptr::get_deleter 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::get_deleter 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::get_deleter \- std::unique_ptr::get_deleter + .SH Synopsis - Deleter& get_deleter(); \fI(since C++11)\fP - const Deleter& get_deleter() const; \fI(since C++11)\fP + Deleter& get_deleter() noexcept; \fI(since C++11)\fP + (constexpr since C++23) + const Deleter& get_deleter() const noexcept; \fI(since C++11)\fP + (constexpr since C++23) Returns the deleter object which would be used for destruction of the managed object. @@ -14,46 +19,65 @@ The stored deleter object. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - + struct Foo { - Foo() { std::cout << "Foo...\\n"; } - ~Foo() { std::cout << "~Foo...\\n"; } + Foo() { std::cout << "Foo() 0x" << std::hex << (void*)this << '\\n'; } + ~Foo() { std::cout << "~Foo() 0x" << std::hex << (void*)this << '\\n'; } }; - + struct D { - void bar() { std::cout << "Call deleter D::bar()...\\n"; } + int number; + + void bar() + { + std::cout << "call D::bar(), my number is: " << std::dec << number << '\\n'; + } + void operator()(Foo* p) const { - std::cout << "Call delete for Foo object...\\n"; + std::cout << "call deleter for Foo object 0x" << std::hex << (void*)p << '\\n'; delete p; } }; - + int main() { - std::unique_ptr up(new Foo(), D()); - D& del = up.get_deleter(); - del.bar(); + std::cout << "main start\\n"; + + std::unique_ptr up1(new Foo(), D(42)); + D& del1 = up1.get_deleter(); + del1.bar(); + + std::unique_ptr up2(new Foo(), D(43)); + D& del2 = up2.get_deleter(); + auto* released = up2.release(); + del2(released); + + std::cout << "main end\\n"; } .SH Output: - Foo... - Call deleter D::bar()... - Call delete for Foo object... - ~Foo... + main start + Foo() 0x0x90cc30 + call D::bar(), my number is: 42 + Foo() 0x0x90cc50 + call deleter for Foo object 0x0x90cc50 + ~Foo() 0x0x90cc50 + main end + call deleter for Foo object 0x0x90cc30 + ~Foo() 0x0x90cc30 + +.SH See also + + get_deleter returns the deleter of specified type, if owned + \fI(function template)\fP diff --git a/man/std::unique_ptr::operator*,std::unique_ptr::operator->.3 b/man/std::unique_ptr::operator*,std::unique_ptr::operator->.3 new file mode 100644 index 000000000..75d2cd445 --- /dev/null +++ b/man/std::unique_ptr::operator*,std::unique_ptr::operator->.3 @@ -0,0 +1,83 @@ +.TH std::unique_ptr::operator*,std::unique_ptr::operator-> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::operator*,std::unique_ptr::operator-> \- std::unique_ptr::operator*,std::unique_ptr::operator-> + +.SH Synopsis + typename std::add_lvalue_reference::type operator*() const \fI(since C++11)\fP + noexcept(noexcept(*std::declval())); \fB(1)\fP (constexpr since + C++23) + \fI(since C++11)\fP + pointer operator->() const noexcept; \fB(2)\fP (constexpr since + C++23) + + operator* and operator-> provide access to the object owned by *this. + + The behavior is undefined if get() == nullptr. + + These member functions are only provided for unique_ptr for the single objects i.e. + the primary template. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) Returns the object owned by *this, equivalent to *get(). + 2) Returns a pointer to the object owned by *this, i.e. get(). + +.SH Exceptions + + 1) May throw if pointer has a throwing operator*. + +.SH Notes + + The use of std::add_lvalue_reference is to make it possible to instantiate + std::unique_ptr since void& isn't allowed in C++ while + std::add_lvalue_reference produces void. See LWG673 for details. + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + void bar() { std::cout << "Foo::bar\\n"; } + }; + + void f(const Foo&) + { + std::cout << "f(const Foo&)\\n"; + } + + int main() + { + std::unique_ptr ptr(new Foo); + + ptr->bar(); + f(*ptr); + } + +.SH Output: + + Foo::bar + f(const Foo&) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + operator* might be potentially-throwing a conditional exception + LWG 2762 C++11 even if specification added + *get() was noexcept + +.SH See also + + get returns a pointer to the managed object + \fI(public member function)\fP diff --git a/man/std::unique_ptr::operator*.3 b/man/std::unique_ptr::operator*.3 deleted file mode 100644 index f3adc257e..000000000 --- a/man/std::unique_ptr::operator*.3 +++ /dev/null @@ -1,60 +0,0 @@ -.TH std::unique_ptr::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - typename std::add_lvalue_reference::type operator*() const; \fB(1)\fP \fI(since C++11)\fP - pointer operator->() const; \fB(2)\fP \fI(since C++11)\fP - - operator* and operator-> provide access to the object owned by *this. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - 1) Returns the object owned by *this, i.e. *get(). - - 2) Returns a pointer to the object owned by *this, i.e. get(). - -.SH Exceptions - - 1) may throw - - 2) - noexcept specification: - noexcept - - -.SH Example - - -// Run this code - - #include - #include - - struct Foo { - void bar() { std::cout << "Foo::bar\\n"; } - }; - - void f(const Foo& foo) - { - std::cout << "f(const Foo&)\\n"; - } - - int main() - { - std::unique_ptr ptr(new Foo); - - ptr->bar(); - f(*ptr); - } - -.SH Output: - - Foo::bar - f(const Foo&) - -.SH See also - - get returns a pointer to the managed object - \fI(public member function)\fP diff --git a/man/std::unique_ptr::operator<<.3 b/man/std::unique_ptr::operator<<.3 new file mode 100644 index 000000000..c0e9a3b53 --- /dev/null +++ b/man/std::unique_ptr::operator<<.3 @@ -0,0 +1,63 @@ +.TH std::unique_ptr::operator<< 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::operator<< \- std::unique_ptr::operator<< + +.SH Synopsis + template< class CharT, class Traits, class Y, class D > + + std::basic_ostream& operator<<( + std::basic_ostream& os, \fI(since C++20)\fP + + const + std::unique_ptr& p ); + + Inserts the value of the pointer managed by p into the output stream os. + + Equivalent to os << p.get(). + + This overload participates in overload resolution only if os << p.get() is a valid + expression. + +.SH Parameters + + os - a std::basic_ostream to insert p into + p - the pointer to be inserted into os + +.SH Return value + + os + +.SH Notes + + If std::unique_ptr::pointer is a pointer to a character type (e.g., when Y is + char([]) or CharT([])), this may end up calling the overloads of operator<< for + null-terminated character strings (causing undefined behavior if the pointer does + not in fact point to such a string), rather than the overload for printing the value + of the pointer itself. + +.SH Example + + +// Run this code + + #include + #include + + class Foo {}; + + int main() + { + auto p = std::make_unique(); + std::cout << p << '\\n'; + std::cout << p.get() << '\\n'; + } + +.SH Possible output: + + 0x6d9028 + 0x6d9028 + +.SH See also + + get returns a pointer to the managed object + \fI(public member function)\fP diff --git a/man/std::unique_ptr::operator=.3 b/man/std::unique_ptr::operator=.3 index 9c814a29c..af5c3c82d 100644 --- a/man/std::unique_ptr::operator=.3 +++ b/man/std::unique_ptr::operator=.3 @@ -1,69 +1,115 @@ -.TH std::unique_ptr::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::operator= \- std::unique_ptr::operator= + .SH Synopsis - unique_ptr& operator=( unique_ptr&& r ); \fB(1)\fP \fI(since C++11)\fP - template< class U, class E > \fB(1)\fP \fI(since C++11)\fP - unique_ptr& operator=( unique_ptr&& r ); - unique_ptr& operator=( nullptr_t ); \fB(2)\fP \fI(since C++11)\fP + unique_ptr& operator=( unique_ptr&& r ) noexcept; \fB(1)\fP (constexpr since C++23) + template< class U, class E > \fB(2)\fP (constexpr since C++23) + unique_ptr& operator=( unique_ptr&& r ) noexcept; + unique_ptr& operator=( std::nullptr_t ) noexcept; \fB(3)\fP (constexpr since C++23) + unique_ptr& operator=( const unique_ptr& ) = delete; \fB(4)\fP - 1) Transfers ownership of the object pointed to by r to *this as if by calling - reset(r.release()) followed by an assignment of get_deleter() from + 1) Move assignment operator. Transfers ownership from r to *this as if by calling + reset(r.release()) followed by assigning get_deleter() from + std::forward(r.get_deleter()). + This overload participates in overload resolution only if + std::is_move_assignable::value is true. + If Deleter is not a reference type, the behavior is undefined if + * Deleter is not MoveAssignable, or + * assigning get_deleter() from an rvalue of type Deleter would throw an exception. + Otherwise (Deleter is a reference type), the behavior is undefined if + * std::remove_reference::type is not CopyAssignable, or + * assigning get_deleter() from an lvalue of type Deleter would throw an exception. + 2) Converting assignment operator. Transfers ownership from r to *this as if by + calling reset(r.release()) followed by assigning get_deleter() from std::forward(r.get_deleter()). - - 2) Effectively the same as calling reset(). - - Note that unique_ptr's assignment operator only accepts xvalues, which are typically - generated by std::move. (The unique_ptr class explicitly deletes its lvalue copy - constructor and lvalue assignment operator.) + For the primary template, this overload participates in overload resolution only if + * U is not an array type, + * unique_ptr::pointer is implicitly convertible to pointer, and + * std::is_assignable::value is true. + For the array specialization (unique_ptr), this overload participates in + overload resolution only if + * U is an array type, + * pointer is the same type as element_type*, + * unique_ptr::pointer is the same type as unique_ptr::element_type*, + * unique_ptr::element_type(*)[] is convertible to element_type(*)[], and + * std::is_assignable::value is true. + If E is not a reference type, the behavior is undefined if assigning get_deleter() + from an rvalue of type E is ill-formed or would throw an exception. + Otherwise (E is a reference type), the behavior is undefined if assigning + get_deleter() from an lvalue of type E is ill-formed or would throw an exception. + 3) Effectively the same as calling reset(). + 4) Copy assignment operator is explicitly deleted. .SH Parameters - r - smart pointer from which ownership will be transfered + r - smart pointer from which ownership will be transferred .SH Return value *this -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + As a move-only type, unique_ptr's assignment operator only accepts rvalues arguments + (e.g. the result of std::make_unique or a std::move'd unique_ptr variable). .SH Example - + // Run this code #include #include - - struct Foo { - Foo() { std::cout << "Foo\\n"; } - ~Foo() { std::cout << "~Foo\\n"; } + + struct Foo + { + int id; + Foo(int id) : id(id) { std::cout << "Foo " << id << '\\n'; } + ~Foo() { std::cout << "~Foo " << id << '\\n'; } }; - + int main() { - std::unique_ptr p1; - + std::unique_ptr p1(std::make_unique(1)); + { std::cout << "Creating new Foo...\\n"; - std::unique_ptr p2(new Foo); + std::unique_ptr p2(std::make_unique(2)); // p1 = p2; // Error ! can't copy unique_ptr p1 = std::move(p2); std::cout << "About to leave inner block...\\n"; - + // Foo instance will continue to live, // despite p2 going out of scope } - + std::cout << "About to leave program...\\n"; } .SH Output: + Foo 1 Creating new Foo... - Foo + Foo 2 + ~Foo 1 About to leave inner block... About to leave program... - ~Foo + ~Foo 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied Behavior as published Correct behavior + to + LWG for overload \fB(2)\fP, get_deleter() was corrected to + 2047 C++11 assigned from std::forward(r.get_deleter()) + std::forward(r.get_deleter()) + LWG C++11 unique_ptr::operator= accepts + 2118 rejected qualification conversions + LWG C++11 the converting assignment operator was constrained + 2228 not constrained + LWG C++11 the move assignment operator was not constrained + 2899 constrained diff --git a/man/std::unique_ptr::operator[].3 b/man/std::unique_ptr::operator[].3 index fefddfeca..0114d7f88 100644 --- a/man/std::unique_ptr::operator[].3 +++ b/man/std::unique_ptr::operator[].3 @@ -1,10 +1,17 @@ -.TH std::unique_ptr::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::operator[] \- std::unique_ptr::operator[] + .SH Synopsis - T& operator[](size_t i) const; \fI(since C++11)\fP + T& operator[]( std::size_t i ) const; \fI(since C++11)\fP + (constexpr since C++23) operator[] provides access to elements of an array managed by a unique_ptr. - The parameter i is required to be a valid array index. + The parameter i shall be less than the number of elements in the array; otherwise, + the behavior is undefined. + + This member function is only provided for specializations for array types. .SH Parameters @@ -16,40 +23,38 @@ .SH Example - + // Run this code #include #include - + int main() { const int size = 10; std::unique_ptr fact(new int[size]); - - for (int i = 0; i < size; ++i) { - fact[i] = (i == 0) ? 1 : i * fact[i-1]; - } - - for (int i = 0; i < size; ++i) { - std::cout << i << ": " << fact[i] << '\\n'; - } + + for (int i = 0; i < size; ++i) + fact[i] = (i == 0) ? 1 : i * fact[i - 1]; + + for (int i = 0; i < size; ++i) + std::cout << i << "! = " << fact[i] << '\\n'; } .SH Output: - 0: 1 - 1: 1 - 2: 2 - 3: 6 - 4: 24 - 5: 120 - 6: 720 - 7: 5040 - 8: 40320 - 9: 362880 + 0! = 1 + 1! = 1 + 2! = 2 + 3! = 6 + 4! = 24 + 5! = 120 + 6! = 720 + 7! = 5040 + 8! = 40320 + 9! = 362880 .SH See also get returns a pointer to the managed object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unique_ptr::operatorbool.3 b/man/std::unique_ptr::operatorbool.3 index 7be01ca6e..1fa703f8c 100644 --- a/man/std::unique_ptr::operatorbool.3 +++ b/man/std::unique_ptr::operatorbool.3 @@ -1,6 +1,10 @@ -.TH std::unique_ptr::operatorbool 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::operatorbool \- std::unique_ptr::operatorbool + .SH Synopsis - explicit operator bool() const; \fI(since C++11)\fP + explicit operator bool() const noexcept; \fI(since C++11)\fP + (constexpr since C++23) Checks whether *this owns an object, i.e. whether get() != nullptr. @@ -12,34 +16,31 @@ true if *this owns an object, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - + int main() { std::unique_ptr ptr(new int(42)); - - if (ptr) std::cout << "before reset, ptr is: " << *ptr << '\\n'; + + if (ptr) + std::cout << "before reset, ptr is: " << *ptr << '\\n'; ptr.reset(); - if (ptr) std::cout << "after reset, ptr is: " << *ptr << '\\n'; + ptr ? (std::cout << "after reset, ptr is: " << *ptr) + : (std::cout << "after reset ptr is empty") << '\\n'; } .SH Output: before reset, ptr is: 42 + after reset ptr is empty .SH See also get returns a pointer to the managed object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unique_ptr::release.3 b/man/std::unique_ptr::release.3 index 84451f91e..9d73fa8ad 100644 --- a/man/std::unique_ptr::release.3 +++ b/man/std::unique_ptr::release.3 @@ -1,9 +1,16 @@ -.TH std::unique_ptr::release 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::release 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::release \- std::unique_ptr::release + .SH Synopsis - pointer release(); \fI(since C++11)\fP + pointer release() noexcept; \fI(since C++11)\fP + (constexpr since C++23) + + Releases the ownership of the managed object, if any. - Releases the ownership of the managed object if any. get() returns nullptr after the - call. + get() returns nullptr after the call. + + The caller is responsible for cleaning up the object (e.g. by use of get_deleter()). .SH Parameters @@ -14,50 +21,51 @@ Pointer to the managed object or nullptr if there was no managed object, i.e. the value which would be returned by get() before the call. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code - #include + #include #include - - struct Foo { + #include + + struct Foo + { Foo() { std::cout << "Foo\\n"; } ~Foo() { std::cout << "~Foo\\n"; } }; - + + // Ownership of the Foo resource is transferred when calling this function + void legacy_api(Foo* owning_foo) + { + std::cout << __func__ << '\\n'; + // [legacy code that no one understands or dares touch anymore] + // [...] + delete owning_foo; + } + int main() { - std::cout << "Creating new Foo...\\n"; - std::unique_ptr up(new Foo()); - - std::cout << "About to release Foo...\\n"; - Foo* fp = up.release(); - - if (up.get() == nullptr) - std::cout << "Foo is no longer owned by unique_ptr...\\n"; - - delete fp; + std::unique_ptr managed_foo(new Foo); + // [code that might return or throw or some such] + // [...] + legacy_api(managed_foo.release()); + + assert(managed_foo == nullptr); } .SH Output: - Creating new Foo... Foo - About to release Foo... - Foo is no longer owned by unique_ptr... + legacy_api ~Foo .SH See also - get returns a pointer to the managed object - \fI(public member function)\fP - reset replaces the managed object - \fI(public member function)\fP + get returns a pointer to the managed object + \fI(public member function)\fP + get_deleter returns the deleter that is used for destruction of the managed object + \fI(public member function)\fP + reset replaces the managed object + \fI(public member function)\fP diff --git a/man/std::unique_ptr::reset.3 b/man/std::unique_ptr::reset.3 index f6dbfe0ec..0c89a7a58 100644 --- a/man/std::unique_ptr::reset.3 +++ b/man/std::unique_ptr::reset.3 @@ -1,29 +1,29 @@ -.TH std::unique_ptr::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::reset \- std::unique_ptr::reset + .SH Synopsis - void reset( pointer ptr = pointer() ); \fB(1)\fP \fI(since C++11)\fP - template< class U > \fI(since C++11)\fP - void reset( U ) = delete; \fB(2)\fP (member of specialization unique_ptr - only) - \fI(since C++11)\fP - void reset( std::nullptr_t p ); \fB(3)\fP (member of specialization unique_ptr - only) + members of the primary template, unique_ptr + void reset( pointer ptr = pointer() ) noexcept; \fB(1)\fP (constexpr since C++23) + members of the specialization unique_ptr + template< class U > \fB(2)\fP (constexpr since C++23) + void reset( U ptr ) noexcept; + void reset( std::nullptr_t = nullptr ) noexcept; \fB(3)\fP (constexpr since C++23) Replaces the managed object. 1) Given current_ptr, the pointer that was managed by *this, performs the following actions, in this order: - - 1. Saves a copy of the current pointer old_ptr = current_ptr - 2. Overwrites the current pointer with the argument current_ptr = ptr - 3. If the old pointer was non-empty, deletes the previously managed object - if(old_ptr != nullptr) get_deleter()(old_ptr). - - 2) In the specialization for dynamic arrays, std::unique_ptr, this template - member is provided to prevent using reset() with a pointer to derived (which would - result in undefined behavior with arrays). - 3) In the specialization for dynamic arrays, std::unique_ptr, the third - overload is necessary to allow reset to nullptr (which would otherwise be prohibited - by the template overload). Equivalent to reset(pointer()) + 1. Saves a copy of the current pointer old_ptr = current_ptr. + 2. Overwrites the current pointer with the argument current_ptr = ptr. + 3. If the old pointer was non-empty, deletes the previously managed object if + (old_ptr) get_deleter()(old_ptr). + 2) Behaves the same as the reset member of the primary template, except that it will + only participate in overload resolution if either + 1. U is the same type as pointer, or + 2. pointer is the same type as element_type* and U is a pointer type V* such that + V(*)[] is convertible to element_type(*)[]. + 3) Equivalent to reset(pointer()). .SH Parameters @@ -33,12 +33,6 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes To replace the managed object while supplying a new deleter as well, move assignment @@ -49,38 +43,37 @@ debugging assert. Note that code such as p.reset(p.release()) does not involve self-reset, only code like p.reset(p.get()) does. - Visual Studio's implementation of reset is currently (in VC10 and VC11) broken and - non-conforming to the C++11 standard. It deletes the managed object before resetting - the pointer to the owned object. - .SH Example - + // Run this code #include #include - - struct Foo { + + struct Foo // object to manage + { Foo() { std::cout << "Foo...\\n"; } ~Foo() { std::cout << "~Foo...\\n"; } }; - - struct D { - void operator() (Foo* p) { + + struct D // deleter + { + void operator() (Foo* p) + { std::cout << "Calling delete for Foo object... \\n"; delete p; } }; - + int main() { std::cout << "Creating new Foo...\\n"; - std::unique_ptr up(new Foo(), D()); // up owns the Foo pointer (deleter D) - + std::unique_ptr up(new Foo(), D()); // up owns the Foo pointer (deleter D) + std::cout << "Replace owned Foo with a new Foo...\\n"; up.reset(new Foo()); // calls deleter for the old one - + std::cout << "Release and delete the owned Foo...\\n"; up.reset(nullptr); } @@ -97,7 +90,16 @@ Calling delete for Foo object... ~Foo... + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2118 C++11 unique_ptr::reset rejected qualification accepts + conversions + .SH See also release returns a pointer to the managed object and releases the ownership - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unique_ptr::swap.3 b/man/std::unique_ptr::swap.3 index b12f040ec..fd83ab98b 100644 --- a/man/std::unique_ptr::swap.3 +++ b/man/std::unique_ptr::swap.3 @@ -1,9 +1,12 @@ -.TH std::unique_ptr::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::swap \- std::unique_ptr::swap + .SH Synopsis - void swap(unique_ptr& other); \fI(since C++11)\fP + void swap( unique_ptr& other ) noexcept; \fI(since C++11)\fP - Swaps the managed objects and associated deleters with another unique_ptr object - other. + Swaps the managed objects and associated deleters of *this and another unique_ptr + object other. .SH Parameters @@ -13,35 +16,30 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH Example - + // Run this code #include #include - - struct Foo { + + struct Foo + { Foo(int _val) : val(_val) { std::cout << "Foo...\\n"; } ~Foo() { std::cout << "~Foo...\\n"; } int val; }; - + int main() { std::unique_ptr up1(new Foo(1)); std::unique_ptr up2(new Foo(2)); - + up1.swap(up2); - - std::cout << "up1->val:" << up1->val << std::endl; - std::cout << "up2->val:" << up2->val << std::endl; + + std::cout << "up1->val:" << up1->val << '\\n'; + std::cout << "up2->val:" << up2->val << '\\n'; } .SH Output: diff --git a/man/std::unique_ptr::unique_ptr.3 b/man/std::unique_ptr::unique_ptr.3 index 66160076f..fc23b5751 100644 --- a/man/std::unique_ptr::unique_ptr.3 +++ b/man/std::unique_ptr::unique_ptr.3 @@ -1,200 +1,278 @@ -.TH std::unique_ptr::unique_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::unique_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::unique_ptr \- std::unique_ptr::unique_ptr + .SH Synopsis - constexpr unique_ptr(); \fB(1)\fP \fI(since C++11)\fP - constexpr unique_ptr( nullptr_t ); \fB(1)\fP \fI(since C++11)\fP - explicit unique_ptr( pointer p ); \fB(2)\fP \fI(since C++11)\fP - unique_ptr( pointer p, /* see below */ d1 ); \fB(3)\fP \fI(since C++11)\fP - unique_ptr( pointer p, /* see below */ d2 ); \fB(4)\fP \fI(since C++11)\fP - unique_ptr( unique_ptr&& u ); \fB(5)\fP \fI(since C++11)\fP - template< class U, class E > \fB(6)\fP \fI(since C++11)\fP - unique_ptr( unique_ptr&& u ); - template< class U > \fB(7)\fP \fI(since C++11)\fP - unique_ptr( auto_ptr&& u ); - - 1) Constructs an empty std::unique_ptr. + members of the primary template, unique_ptr + constexpr unique_ptr() noexcept; \fB(1)\fP + constexpr unique_ptr( std::nullptr_t ) noexcept; + explicit unique_ptr( pointer p ) noexcept; \fB(2)\fP (constexpr since C++23) + unique_ptr( pointer p, /* see below */ d1 ) noexcept; \fB(3)\fP (constexpr since C++23) + unique_ptr( pointer p, /* see below */ d2 ) noexcept; \fB(4)\fP (constexpr since C++23) + unique_ptr( unique_ptr&& u ) noexcept; \fB(5)\fP (constexpr since C++23) + template< class U, class E > \fB(6)\fP (constexpr since C++23) + unique_ptr( unique_ptr&& u ) noexcept; + unique_ptr( const unique_ptr& ) = delete; \fB(7)\fP + template< class U > \fB(8)\fP (removed in C++17) + unique_ptr( std::auto_ptr&& u ) noexcept; + members of the specialization for arrays, + unique_ptr + constexpr unique_ptr() noexcept; \fB(1)\fP + constexpr unique_ptr( std::nullptr_t ) noexcept; + template< class U > explicit unique_ptr( U p ) noexcept; \fB(2)\fP (constexpr since C++23) + template< class U > unique_ptr( U p, /* see below */ d1 \fB(3)\fP (constexpr since C++23) + ) noexcept; + template< class U > unique_ptr( U p, /* see below */ d2 \fB(4)\fP (constexpr since C++23) + ) noexcept; + unique_ptr( unique_ptr&& u ) noexcept; \fB(5)\fP (constexpr since C++23) + template< class U, class E > \fB(6)\fP (constexpr since C++23) + unique_ptr( unique_ptr&& u ) noexcept; + unique_ptr( const unique_ptr& ) = delete; \fB(7)\fP + + 1) Constructs a std::unique_ptr that owns nothing. Value-initializes the stored + pointer and the stored deleter. Requires that Deleter is DefaultConstructible and + that construction does not throw an exception. These overloads participate in + overload resolution only if std::is_default_constructible::value is true + and Deleter is not a pointer type. 2) Constructs a std::unique_ptr which owns p, initializing the stored pointer with p - and value-initializing the stored deleter. - 3-4) Constructs a std::unique_ptr object which owns p, initializing the stored - pointer with p and initializing a deleter D as below (depends upon whether D is a - reference type) + and value-initializing the stored deleter. Requires that Deleter is + DefaultConstructible and that construction does not throw an exception. This + overload participates in overload resolution only if + std::is_default_constructible::value is true and Deleter is not a pointer + type. + This constructor is not selected by class template argument deduction. \fI(since C++17)\fP + + 3,4) Constructs a std::unique_ptr object which owns p, initializing the stored + pointer with p and initializing a deleter D as below (depends upon whether D is a + reference type). a) If D is non-reference type A, then the signatures are: - unique_ptr(pointer p, const A& d); - unique_ptr(pointer p, A&& d); + unique_ptr(pointer p, const A& d) \fB(1)\fP (requires that Deleter is + noexcept; nothrow-CopyConstructible) + unique_ptr(pointer p, A&& d) \fB(2)\fP (requires that Deleter is + noexcept; nothrow-MoveConstructible) + b) If D is an lvalue-reference type A&, then the signatures are: - unique_ptr(pointer p, A& d); - unique_ptr(pointer p, A&& d); + unique_ptr(pointer p, A& d) noexcept; \fB(1)\fP + unique_ptr(pointer p, A&& d) = delete; \fB(2)\fP + c) If D is an lvalue-reference type const A&, then the signatures are: - unique_ptr(pointer p, const A& d); - unique_ptr(pointer p, const A&& d); - 5) Constructs a unique_ptr by transferring ownership from u to *this. + unique_ptr(pointer p, const A& d) noexcept; \fB(1)\fP + unique_ptr(pointer p, const A&& d) = delete; \fB(2)\fP + + In all cases the deleter is initialized from std::forward(d). These + overloads participate in overload resolution only if std::is_constructible::value is true. + + These two constructors are not selected by class template argument \fI(since C++17)\fP + deduction. + + 2-4) In the specialization for arrays behave the same as the constructors that take + a pointer parameter in the primary template except that they additionally do not + participate in overload resolution unless one of the following is true: + * U is the same type as pointer, or + * U is std::nullptr_t, or + * pointer is the same type as element_type* and U is some pointer type V* such + that V(*)[] is implicitly convertible to element_type(*)[]. + 5) Constructs a unique_ptr by transferring ownership from u to *this and stores the + null pointer in u. This constructor only participates in overload resolution if + std::is_move_constructible::value is true. If Deleter is not a reference + type, requires that it is nothrow-MoveConstructible (if Deleter is a reference, + get_deleter() and u.get_deleter() after move construction reference the same value). 6) Constructs a unique_ptr by transferring ownership from u to *this, where u is constructed with a specified deleter (E). It depends upon whether E is a reference type, as following: - - a) if E is a reference type, this deleter is copy constructed from u's deleter. - b) if E is a non-reference type, this deleter is move constructed from u's deleter. - 7) Constructs a unique_ptr where the stored pointer is initialized with u.release() - and the stored deleter is value-initialized. + a) if E is a reference type, this deleter is copy constructed from u's deleter + (requires that this construction does not throw), + b) if E is a non-reference type, this deleter is move constructed from u's deleter + (requires that this construction does not throw). + This constructor only participates in overload resolution if all of the following is + true: + a) unique_ptr::pointer is implicitly convertible to pointer, + b) U is not an array type, + c) either Deleter is a reference type and E is the same type as D, or Deleter is not + a reference type and E is implicitly convertible to D. + 6) In the specialization for arrays behaves the same as in the primary template, + except that it will only participate in overload resolution if all of the following + is true: + * U is an array type, + * pointer is the same type as element_type*, + * unique_ptr::pointer is the same type as unique_ptr::element_type*, + * unique_ptr::element_type(*)[] is convertible to element_type(*)[], + * either Deleter is a reference type and E is the same type as Deleter, or Deleter + is not a reference type and E is implicitly convertible to Deleter. + 7) Copy constructor is explicitly deleted. + 8) Constructs a unique_ptr where the stored pointer is initialized with u.release() + and the stored deleter is value-initialized. This constructor only participates in + overload resolution if U* is implicitly convertible to T* and Deleter is the same + type as std::default_delete. .SH Parameters - p - a pointer to an object to manage - d1,d2 - a deleter to use to destroy the object - u - another smart pointer to acquire the ownership from + p - a pointer to an object to manage + d1, d2 - a deleter to use to destroy the object + u - another smart pointer to acquire the ownership from -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + Instead of using the overload \fB(2)\fP together with new, it is often a \fI(since C++14)\fP + better idea to use std::make_unique. + + std::unique_ptr is implicitly convertible to std::unique_ptr through + the overload \fB(6)\fP (because both the managed pointer and std::default_delete are + implicitly convertible). + + Because the default constructor is constexpr, static unique_ptrs are initialized as + part of static non-local initialization, before any dynamic non-local initialization + begins. This makes it safe to use a unique_ptr in a constructor of any static + object. + + There is no class template argument deduction from pointer type + because it is impossible to distinguish a pointer obtained from array \fI(since C++17)\fP + and non-array forms of new. .SH Example - + // Run this code #include #include - - struct Foo { - Foo() { std::cout << "Foo...\\n"; } - ~Foo() { std::cout << "~Foo...\\n\\n"; } + + struct Foo // object to manage + { + Foo() { std::cout << "Foo ctor\\n"; } + Foo(const Foo&) { std::cout << "Foo copy ctor\\n"; } + Foo(Foo&&) { std::cout << "Foo move ctor\\n"; } + ~Foo() { std::cout << "~Foo dtor\\n"; } }; - - struct D { - + + struct D // deleter + { D() {}; - - D(const D& other) { - std::cout << "call D const copy constructor... \\n"; - } - - D(D& other) { - std::cout << "call D copy constructor... \\n"; - } - - D(D&& other) { - std::cout << "call D move constructor... \\n"; - } - - void operator () (Foo* p) const { - std::cout << "Call delete for Foo object...\\n"; + D(const D&) { std::cout << "D copy ctor\\n"; } + D(D&) { std::cout << "D non-const copy ctor\\n"; } + D(D&&) { std::cout << "D move ctor \\n"; } + void operator()(Foo* p) const + { + std::cout << "D is deleting a Foo\\n"; delete p; }; }; - + int main() { - // constructor (1) - std::cout << "Example constructor(1)...\\n\\n"; - std::unique_ptr up; - - // constructor (2) + std::cout << "Example constructor(1)...\\n"; + std::unique_ptr up1; // up1 is empty + std::unique_ptr up1b(nullptr); // up1b is empty + std::cout << "Example constructor(2)...\\n"; - Foo* f = new Foo; - std::unique_ptr up2(f); //up2 now owns f - up2.reset(); - - // constructor (3&4) - std::cout << "Example constructor(3&4)...\\n"; - - // D is not an lvalue reference type and d is a non-const rvalue expression - std::unique_ptr up3(new Foo, D()); // D must be MoveConstructible - up3.reset(); - - // D is not an lvalue reference type and d is an lvalue expression - D d2; - std::unique_ptr up4(new Foo, d2); // D must be CopyConstructible - up4.reset(); - - // D is an lvalue reference type and d is an lvalue expression - D d3; - std::unique_ptr up5(new Foo, d3); // up5 holds a reference to d3 - up5.reset(); - - // D is a const lvalue reference type and d is an lvalue expression - const D d4; - std::unique_ptr up6(new Foo, d4); - up6.reset(); - - // constructor (5) - std::cout << "Example constructor(5)...\\n"; - std::unique_ptr up7(new Foo); - std::unique_ptr up8(std::move(up7)); // ownership is transferred to up8 - up8.reset(); - - // constructor 6 - std::cout << "Example constructor(6)...\\n\\n"; - std::unique_ptr up9(nullptr); - - // constructor 7 - D is move constructed + { + std::unique_ptr up2(new Foo); //up2 now owns a Foo + } // Foo deleted + + std::cout << "Example constructor(3)...\\n"; D d; + { // deleter type is not a reference + std::unique_ptr up3(new Foo, d); // deleter copied + } + { // deleter type is a reference + std::unique_ptr up3b(new Foo, d); // up3b holds a reference to d + } + + std::cout << "Example constructor(4)...\\n"; + { // deleter is not a reference + std::unique_ptr up4(new Foo, D()); // deleter moved + } + + std::cout << "Example constructor(5)...\\n"; + { + std::unique_ptr up5a(new Foo); + std::unique_ptr up5b(std::move(up5a)); // ownership transfer + } + + std::cout << "Example constructor(6)...\\n"; + { + std::unique_ptr up6a(new Foo, d); // D is copied + std::unique_ptr up6b(std::move(up6a)); // D is moved + + std::unique_ptr up6c(new Foo, d); // D is a reference + std::unique_ptr up6d(std::move(up6c)); // D is copied + } + + #if (__cplusplus < 201703L) std::cout << "Example constructor(7)...\\n"; - std::unique_ptr up10(new Foo, d); // D is not a reference - std::unique_ptr up11(std::move(up10)); // D is move constructed - up11.reset(); - - // constructor 7 - D is copy constructed - std::unique_ptr up12(new Foo, d); // D is a reference - std::unique_ptr up13(std::move(up12)); // D is copy constructed - up13.reset(); - - // constructor 8 - std::cout << "Example constructor(8)...\\n"; - std::auto_ptr up14(new Foo); - std::unique_ptr up15(move(up14)); - up15.reset(); + { + std::auto_ptr up7a(new Foo); + std::unique_ptr up7b(std::move(up7a)); // ownership transfer + } + #endif + + std::cout << "Example array constructor...\\n"; + { + std::unique_ptr up(new Foo[3]); + } // three Foo objects deleted } .SH Output: Example constructor\fB(1)\fP... - Example constructor\fB(2)\fP... - Foo... - ~Foo... - - Example constructor(3&4)... - Foo... - call D move constructor... - Call delete for Foo object... - ~Foo... - - Foo... - call D const copy constructor... - Call delete for Foo object... - ~Foo... - - Foo... - Call delete for Foo object... - ~Foo... - - Foo... - Call delete for Foo object... - ~Foo... - + Foo ctor + ~Foo dtor + Example constructor\fB(3)\fP... + Foo ctor + D copy ctor + D is deleting a Foo + ~Foo dtor + Foo ctor + D is deleting a Foo + ~Foo dtor + Example constructor\fB(4)\fP... + Foo ctor + D move ctor + D is deleting a Foo + ~Foo dtor Example constructor\fB(5)\fP... - Foo... - ~Foo... - + Foo ctor + ~Foo dtor Example constructor\fB(6)\fP... - + Foo ctor + D copy ctor + D move ctor + Foo ctor + D non-const copy ctor + D is deleting a Foo + ~Foo dtor + D is deleting a Foo + ~Foo dtor Example constructor\fB(7)\fP... - Foo... - call D const copy constructor... - call D move constructor... - Call delete for Foo object... - ~Foo... - - Foo... - call D copy constructor... - Call delete for Foo object... - ~Foo... - - Example constructor\fB(8)\fP... - Foo... - ~Foo... + Foo ctor + ~Foo dtor + Example array constructor... + Foo ctor + Foo ctor + Foo ctor + ~Foo dtor + ~Foo dtor + ~Foo dtor + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2118 C++11 Constructors of unique_ptr rejected Accept. + qualification conversions. + LWG 2520 C++11 unique_ptr was accidentally made Made constructible. + non-constructible from nullptr_t. + LWG 2801 C++11 The default constructor was not constrained. Constrained. + LWG 2899 C++11 The move constructor was not constrained. Constrained. + LWG 2905 C++11 Constraint on the constructor from a pointer Corrected. + and a deleter was wrong. + LWG 2944 C++11 Some preconditions were accidentally dropped Restored. + by LWG 2905 diff --git a/man/std::unique_ptr::~unique_ptr.3 b/man/std::unique_ptr::~unique_ptr.3 index 1d116cb62..abdf07302 100644 --- a/man/std::unique_ptr::~unique_ptr.3 +++ b/man/std::unique_ptr::~unique_ptr.3 @@ -1,28 +1,41 @@ -.TH std::unique_ptr::~unique_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unique_ptr::~unique_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unique_ptr::~unique_ptr \- std::unique_ptr::~unique_ptr + .SH Synopsis ~unique_ptr(); \fI(since C++11)\fP + (constexpr since C++23) If get() == nullptr there are no effects. Otherwise, the owned object is destroyed via get_deleter()(get()). + Requires that get_deleter()(get()) does not throw exceptions. + +.SH Notes + + Although std::unique_ptr with the default deleter may be constructed with + incomplete type T, the type T must be complete at the point of code where the + destructor is called. + .SH Example The following program demonstrates usage of a custom deleter. - + // Run this code #include #include - + int main () { - auto deleter = [](int* ptr){ + auto deleter = [](int* ptr) + { std::cout << "[deleter called]\\n"; delete ptr; }; - - std::unique_ptr uniq(new int, deleter); + + std::unique_ptr uniq(new int, deleter); std::cout << (uniq ? "not empty\\n" : "empty\\n"); uniq.reset(); std::cout << (uniq ? "not empty\\n" : "empty\\n"); diff --git a/man/std::unitbuf,std::nounitbuf.3 b/man/std::unitbuf,std::nounitbuf.3 index 844274862..8e0214315 100644 --- a/man/std::unitbuf,std::nounitbuf.3 +++ b/man/std::unitbuf,std::nounitbuf.3 @@ -1,4 +1,7 @@ -.TH std::unitbuf,std::nounitbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unitbuf,std::nounitbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unitbuf,std::nounitbuf \- std::unitbuf,std::nounitbuf + .SH Synopsis Defined in header std::ios_base& unitbuf( std::ios_base& str ); \fB(1)\fP @@ -7,11 +10,10 @@ Enables or disables automatic flushing of the output stream after any output operation. Has no effect on input. - 1) enables the unitbuf flag in the stream str as if by calling - str.setf(std::ios_base::unitbuf) - - 2) disables the unitbuf flag in the stream str as if by calling - str.unsetf(std::ios_base::unitbuf) + 1) Enables the unitbuf flag in the stream str as if by calling + str.setf(std::ios_base::unitbuf). + 2) Disables the unitbuf flag in the stream str as if by calling + str.unsetf(std::ios_base::unitbuf). This is an I/O manipulator, it may be called with an expression such as out << std::unitbuf for any out of type std::basic_ostream or with an expression such as in @@ -20,7 +22,7 @@ .SH Notes Flushing is performed in the destructor of the std::basic_ostream::sentry object, - which calls str.rdbuf()->pubsync() if str.flags() & std::ios_base::unitbuf == true. + which calls str.rdbuf()->pubsync() if str.flags() & std::ios_base::unitbuf is true. The standard output objects std::cerr and std::wcerr have their unitbuf bit set by default. @@ -31,51 +33,49 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example Without std::unitbuf or another explicit flush, the output is the same, but does not appear in real time. - + // Run this code - #include #include - + #include + template void log_progress(Diff d) { - std::cout << "..(" - << std::chrono::duration_cast(d).count() - << " ms).."; + std::cout << std::chrono::duration_cast(d) + << " ... "; } - + int main() { volatile int sink = 0; std::cout << std::unitbuf; // enable automatic flushing - - auto t1 = std::chrono::high_resolution_clock::now(); + + const auto start = std::chrono::high_resolution_clock::now(); for (int j = 0; j < 5; ++j) { for (int n = 0; n < 10000; ++n) for (int m = 0; m < 20000; ++m) sink += m * n; // do some work - auto now = std::chrono::high_resolution_clock::now(); - log_progress(now - t1); + log_progress(std::chrono::high_resolution_clock::now() - start); } std::cout << '\\n'; } .SH Output: - ..(450 ms)....(902 ms)....(1352 ms)....(1802 ms)....(2252 ms).. + 571ms ... 1146ms ... 1722ms ... 2294ms ... 2865ms ... .SH See also flush flushes the output stream - \fI(function template)\fP + \fI(function template)\fP endl outputs '\\n' and flushes the output stream - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::unordered_map.3 b/man/std::unordered_map.3 index 2811bd719..f170af279 100644 --- a/man/std::unordered_map.3 +++ b/man/std::unordered_map.3 @@ -1,133 +1,311 @@ -.TH std::unordered_map 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map \- std::unordered_map + .SH Synopsis Defined in header template< class Key, class T, - class Hash = std::hash, \fI(since C++11)\fP + class Hash = std::hash, \fB(1)\fP \fI(since C++11)\fP class KeyEqual = std::equal_to, - class Allocator = std::allocator< std::pair > + class Allocator = std::allocator> > class unordered_map; + namespace pmr { + + template< + class Key, + class T, + class Hash = std::hash, + class KeyEqual = std::equal_to \fB(2)\fP \fI(since C++17)\fP + > using unordered_map = + std::unordered_map>>; + + } - Unordered map is an associative container that contains key-value pairs with unique - keys. Search, insertion, and removal of elements have average constant-time + std::unordered_map is an associative container that contains key-value pairs with + unique keys. Search, insertion, and removal of elements have average constant-time complexity. Internally, the elements are not sorted in any particular order, but organized into buckets. Which bucket an element is placed into depends entirely on the hash of its - key. This allows fast access to individual elements, since once hash is computed, it - refers to the exact bucket the element is placed into. + key. Keys with the same hash code appear in the same bucket. This allows fast access + to individual elements, since once the hash is computed, it refers to the exact + bucket the element is placed into. + + Two keys are considered equivalent if the map's key equality predicate returns true + when passed those keys. If two keys are equivalent, the hash function must return + the same value for both keys. std::unordered_map meets the requirements of Container, AllocatorAwareContainer, UnorderedAssociativeContainer. +.SH Notes + + * The swap functions do not invalidate any of the iterators inside the container, + but they do invalidate the iterator marking the end of the swap region. + * References and pointers to either key or data stored in the container are only + invalidated by erasing that element, even when the corresponding iterator is + invalidated. + +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - mapped_type T - value_type std::pair - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - hasher Hash - key_equal KeyEqual - allocator_type Allocator - reference value_type& - const_reference const value_type& - pointer std::allocator_traits::pointer - const_pointer std::allocator_traits::const_pointer - iterator ForwardIterator - const_iterator Constant forward iterator - An iterator type whose category, value, difference, pointer and - local_iterator reference types are the same as iterator. This iterator - can be used to iterate through a single bucket but not across - buckets - An iterator type whose category, value, difference, pointer and - const_local_iterator reference types are the same as const_iterator. This iterator - can be used to iterate through a single bucket but not across - buckets + Member type Definition + key_type Key + mapped_type T + value_type std::pair + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + hasher Hash + key_equal KeyEqual + allocator_type Allocator + reference value_type& + const_reference const value_type& + pointer std::allocator_traits::pointer + const_pointer std::allocator_traits::const_pointer + iterator LegacyForwardIterator to value_type + const_iterator LegacyForwardIterator to const value_type + An iterator type whose category, value, difference, pointer + and + local_iterator reference types are the same as iterator. This iterator + can be used to iterate through a single bucket but not + across buckets + An iterator type whose category, value, difference, pointer + and + const_local_iterator reference types are the same as const_iterator. This + iterator + can be used to iterate through a single bucket but not + across buckets + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node + type describing the result of inserting a node_type, a + specialization of + + template + struct /*unspecified*/ + insert_return_type { + \fI(since C++17)\fP Iter position; + bool inserted; + NodeType node; + }; + instantiated with template arguments iterator and + node_type. .SH Member functions - constructor constructs the unordered_map - \fI(public member function)\fP - destructor destructs the unordered_map - \fI(public member function)\fP - operator= assigns values to the container - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs the unordered_map + \fI(public member function)\fP + destructor destructs the unordered_map + \fI(public member function)\fP + operator= assigns values to the container + \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP .SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - size returns the number of elements - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP + empty checks whether the container is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP .SH Modifiers - clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - emplace constructs element in-place - \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - erase erases elements - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + insert_or_assign inserts an element or assigns to the current element if the key + \fI(C++17)\fP already exists + \fI(public member function)\fP + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + try_emplace inserts in-place if the key does not exist, does nothing if the + \fI(C++17)\fP key exists + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup - at access specified element with bounds checking - \fI(public member function)\fP - operator[] access specified element - \fI(public member function)\fP - count returns the number of elements matching specific key - \fI(public member function)\fP - find finds element with specific key - \fI(public member function)\fP - equal_range returns range of elements matching a specific key - \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + operator[] access or insert specified element + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP .SH Bucket interface - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP - bucket_count returns the number of buckets - \fI(public member function)\fP - max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP - bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP - bucket returns the bucket for specific key - \fI(public member function)\fP + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP + bucket_count returns the number of buckets + \fI(public member function)\fP + max_bucket_count returns the maximum number of buckets + \fI(public member function)\fP + bucket_size returns the number of elements in specific bucket + \fI(public member function)\fP + bucket returns the bucket for specific key + \fI(public member function)\fP .SH Hash policy - load_factor returns average number of elements per bucket - \fI(public member function)\fP - max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + load_factor returns average number of elements per bucket + \fI(public member function)\fP + max_load_factor manages maximum average number of elements per bucket + \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates + rehash the hash table + \fI(public member function)\fP + reserves space for at least the specified number of elements and + reserve regenerates the hash table + \fI(public member function)\fP .SH Observers - hash_function returns function used to hash the keys - \fI(public member function)\fP - key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + hash_function returns function used to hash the keys + \fI(public member function)\fP + key_eq returns the function used to compare keys for equality + \fI(public member function)\fP .SH Non-member functions - operator== compares the values in the unordered_map - operator!= \fI(function template)\fP + operator== + operator!= compares the values in the unordered_map + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) std::swap(std::unordered_map) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + erase_if(std::unordered_map) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // Create an unordered_map of three strings (that map to strings) + std::unordered_map u = + { + {"RED", "#FF0000"}, + {"GREEN", "#00FF00"}, + {"BLUE", "#0000FF"} + }; + + // Helper lambda function to print key-value pairs + auto print_key_value = [](const auto& key, const auto& value) + { + std::cout << "Key:[" << key << "] Value:[" << value << "]\\n"; + }; + + std::cout << "Iterate and print key-value pairs of unordered_map, being\\n" + "explicit with their types:\\n"; + for (const std::pair& n : u) + print_key_value(n.first, n.second); + + std::cout << "\\nIterate and print key-value pairs using C++17 structured binding:\\n"; + for (const auto& [key, value] : u) + print_key_value(key, value); + + // Add two new entries to the unordered_map + u["BLACK"] = "#000000"; + u["WHITE"] = "#FFFFFF"; + + std::cout << "\\nOutput values by key:\\n" + "The HEX of color RED is:[" << u["RED"] << "]\\n" + "The HEX of color BLACK is:[" << u["BLACK"] << "]\\n\\n"; + + std::cout << "Use operator[] with non-existent key to insert a new key-value pair:\\n"; + print_key_value("new_key", u["new_key"]); + + std::cout << "\\nIterate and print key-value pairs, using `auto`;\\n" + "new_key is now one of the keys in the map:\\n"; + for (const auto& n : u) + print_key_value(n.first, n.second); + } + +.SH Possible output: + + Iterate and print key-value pairs of unordered_map, being + explicit with their types: + Key:[BLUE] Value:[#0000FF] + Key:[GREEN] Value:[#00FF00] + Key:[RED] Value:[#FF0000] + + Iterate and print key-value pairs using C++17 structured binding: + Key:[BLUE] Value:[#0000FF] + Key:[GREEN] Value:[#00FF00] + Key:[RED] Value:[#FF0000] + + Output values by key: + The HEX of color RED is:[#FF0000] + The HEX of color BLACK is:[#000000] + + Use operator[] with non-existent key to insert a new key-value pair: + Key:[new_key] Value:[] + + Iterate and print key-value pairs, using `auto`; + new_key is now one of the keys in the map: + Key:[new_key] Value:[] + Key:[WHITE] Value:[#FFFFFF] + Key:[BLACK] Value:[#000000] + Key:[BLUE] Value:[#0000FF] + Key:[GREEN] Value:[#00FF00] + Key:[RED] Value:[#FF0000] + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the definitions of reference, + LWG 2050 C++11 const_reference, pointer based on value_type and + and const_pointer were based on std::allocator_traits + allocator_type + +.SH See also + + map collection of key-value pairs, sorted by keys, keys are unique + \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::unordered_map::at.3 b/man/std::unordered_map::at.3 index 1270cba20..3023c1b5f 100644 --- a/man/std::unordered_map::at.3 +++ b/man/std::unordered_map::at.3 @@ -1,28 +1,69 @@ -.TH std::unordered_map::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::at \- std::unordered_map::at + .SH Synopsis - T& at( const Key& key ); \fB(1)\fP \fI(since C++11)\fP - const T & at( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + T& at( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + const T& at( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP (since C++26) + T& at( const K& x ); + template< class K > \fB(4)\fP (since C++26) + const T& at( const K& x ) const; + + Returns a reference to the mapped value of the element with specified key. If no + such element exists, an exception of type std::out_of_range is thrown. - Returns a reference to the mapped value of the element with key equivalent to key. - If no such element exists, an exception of type std::out_of_range is thrown. + 1,2) The key is equivalent to key. + 3,4) The key compares equivalent to the value x. The reference to the mapped value + is obtained as if by expression this->find(x)->second. + The expression this->find(x) must be well-formed and have well-defined behavior, + otherwise the behavior is undefined. + These overloads participate in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. .SH Parameters key - the key of the element to find + x - a value of any type that can be transparently compared with a key .SH Return value - Reference to the mapped value of the requested element + A reference to the mapped value of the requested element. .SH Exceptions - std::out_of_range if the container does not have an element with the specified key + 1,2) std::out_of_range if the container does not have an element with the specified + key. + 3,4) std::out_of_range if the container does not have the specified element, that + is, if find(x) == end() is true. .SH Complexity Average case: constant, worst case: linear in size. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also - operator[] access specified element - \fI(public member function)\fP + operator[] access or insert specified element + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_map::begin(int),std::unordered_map::cbegin(int).3 b/man/std::unordered_map::begin(int),std::unordered_map::cbegin(int).3 deleted file mode 100644 index 3773934a5..000000000 --- a/man/std::unordered_map::begin(int),std::unordered_map::cbegin(int).3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::unordered_map::begin(int),std::unordered_map::cbegin(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator begin( size_type n ); \fI(since C++11)\fP - const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the first element of the bucket with index pos. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - Iterator to the first element. - -.SH Complexity - - Constant. - -.SH See also - - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP diff --git a/man/std::unordered_map::begin(size_type),.3 b/man/std::unordered_map::begin(size_type),.3 new file mode 100644 index 000000000..c4e287c52 --- /dev/null +++ b/man/std::unordered_map::begin(size_type),.3 @@ -0,0 +1,28 @@ +.TH std::unordered_map::begin(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::begin(size_type), \- std::unordered_map::begin(size_type), + +.SH Synopsis + + local_iterator begin( size_type n ); \fI(since C++11)\fP + const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the first element of the bucket with index n. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH See also + + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_map::begin,.3 b/man/std::unordered_map::begin,.3 new file mode 100644 index 000000000..846358b4f --- /dev/null +++ b/man/std::unordered_map::begin,.3 @@ -0,0 +1,97 @@ +.TH std::unordered_map::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::begin, \- std::unordered_map::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator begin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the first element of the unordered_map. + + If the unordered_map is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Node { double x, y; }; + + int main() + { + Node nodes[3] = {{1, 0}, {2, 0}, {3, 0}}; + + // mag is a map mapping the address of a Node to its magnitude in the plane + std::unordered_map mag = + { + { nodes + 0, 1 }, + { nodes + 1, 2 }, + { nodes + 2, 3 } + }; + + // Change each y-coordinate from 0 to the magnitude + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; // pointer to Node + cur->y = mag[cur]; // could also have used cur->y = iter->second; + } + + // Update and print the magnitude of each node + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << iter->second << '\\n'; + } + + // Repeat the above with the range-based for loop + for (auto i : mag) + { + auto cur = i.first; + cur->y = i.second; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << mag[cur] << '\\n'; + // Note that in contrast to std::cout << iter->second << '\\n'; above, + // std::cout << i.second << '\\n'; will NOT print the updated magnitude + } + } + +.SH Possible output: + + The magnitude of (3, 3) is 4.24264 + The magnitude of (1, 1) is 1.41421 + The magnitude of (2, 2) is 2.82843 + The magnitude of (3, 4.24264) is 5.19615 + The magnitude of (1, 1.41421) is 1.73205 + The magnitude of (2, 2.82843) is 3.4641 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_map::begin,std::unordered_map::cbegin.3 b/man/std::unordered_map::begin,std::unordered_map::cbegin.3 deleted file mode 100644 index 9f819b66e..000000000 --- a/man/std::unordered_map::begin,std::unordered_map::cbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::unordered_map::begin,std::unordered_map::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP - - Returns an iterator to the first element of the container. - - If the container is empty, the returned iterator will be equal to end(). - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP diff --git a/man/std::unordered_map::bucket.3 b/man/std::unordered_map::bucket.3 index 706c328fb..5706adbd7 100644 --- a/man/std::unordered_map::bucket.3 +++ b/man/std::unordered_map::bucket.3 @@ -1,26 +1,61 @@ -.TH std::unordered_map::bucket 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type bucket( const Key& key ) const; \fI(since C++11)\fP +.TH std::unordered_map::bucket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::bucket \- std::unordered_map::bucket - Returns the index of the bucket for key key. Elements (if any) with keys equivalent - to key are always found in this bucket. The returned value is valid only for - instances of the container for which bucket_count() returns the same value. +.SH Synopsis + size_type bucket( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< typename K > \fB(2)\fP (since C++26) + size_type bucket( const K& x ) const; + + 1) Returns the index of the bucket for key key. Elements (if any) with keys + equivalent to key are always found in this bucket. + 2) Returns the index of the bucket for key that compares equivalent to the value x. + Elements (if any) with keys that compare equivalent to x are always found in this + bucket. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. + + The returned value is valid only for instances of the container for which + bucket_count() returns the same value (e.g., rehash() invalidates previously + obtained value). The behavior is undefined if bucket_count() is zero. .SH Parameters key - the value of the key to examine + x - a value of any type that can be transparently compared with a key .SH Return value - Bucket index for the key key. + Bucket index for the requested key. .SH Complexity Constant. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example + .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_map::bucket_count.3 b/man/std::unordered_map::bucket_count.3 index ae77fd2ab..aa3714921 100644 --- a/man/std::unordered_map::bucket_count.3 +++ b/man/std::unordered_map::bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_map::bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::bucket_count \- std::unordered_map::bucket_count + .SH Synopsis size_type bucket_count() const; \fI(since C++11)\fP @@ -19,6 +22,6 @@ .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::bucket_size.3 b/man/std::unordered_map::bucket_size.3 index cbc839e95..b00b9b950 100644 --- a/man/std::unordered_map::bucket_size.3 +++ b/man/std::unordered_map::bucket_size.3 @@ -1,4 +1,7 @@ -.TH std::unordered_map::bucket_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::bucket_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::bucket_size \- std::unordered_map::bucket_size + .SH Synopsis size_type bucket_size( size_type n ) const; \fI(since C++11)\fP @@ -14,9 +17,9 @@ .SH Complexity - Constant. + Linear in the size of the bucket n. .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::clear.3 b/man/std::unordered_map::clear.3 index 3842062a5..920ecfc18 100644 --- a/man/std::unordered_map::clear.3 +++ b/man/std::unordered_map::clear.3 @@ -1,11 +1,14 @@ -.TH std::unordered_map::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::clear \- std::unordered_map::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + May also invalidate past-the-end iterators. .SH Parameters @@ -15,17 +18,55 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::unordered_map& v) + { + std::cout << rem << "{ "; + for (const auto& [key, value] : v) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::unordered_map container{{1, 'x'}, {2, 'y'}, {3, 'z'}}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Possible output: + + Before clear: { [1]:x [2]:y [3]:z } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + for unordered associative + LWG 2550 C++11 containers, unclear if complexity clarified that it's linear in + is linear in the number of the number of elements + elements or buckets .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::contains.3 b/man/std::unordered_map::contains.3 new file mode 100644 index 000000000..89417ebc2 --- /dev/null +++ b/man/std::unordered_map::contains.3 @@ -0,0 +1,62 @@ +.TH std::unordered_map::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::contains \- std::unordered_map::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Constant on average, worst case linear in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_map example{{1, 'a'}, {2, 'b'}}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::unordered_map::count.3 b/man/std::unordered_map::count.3 index 06e680e45..9d69aa9d1 100644 --- a/man/std::unordered_map::count.3 +++ b/man/std::unordered_map::count.3 @@ -1,24 +1,86 @@ -.TH std::unordered_map::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::count \- std::unordered_map::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + size_type count( const K& x ) const; - Returns the number of elements with key key. + 1) Returns the number of elements with key that compares equal to the specified + argument key, which is either 0 or 1 since this container does not allow duplicates. + 2) Returns the number of elements with key that compares equivalent to the specified + argument x. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. .SH Parameters key - key value of the elements to count + x - a value of any type that can be transparently compared with a key .SH Return value - Number of elements with key key. + 1) Number of elements with key key, that is either 1 or 0. + 2) Number of elements with key that compares equivalent to x. .SH Complexity Constant on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_map dict = { + {1, "one"}, {6, "six"}, {3, "three"} + }; + dict.insert({4, "four"}); + dict.insert({5, "five"}); + dict.insert({6, "six"}); + + std::cout << "dict: { "; + for (auto const& [key, value] : dict) + std::cout << '[' << key << "]=" << value << ' '; + std::cout << "}\\n\\n"; + + for (int i{1}; i != 8; ++i) + std::cout << "dict.count(" << i << ") = " << dict.count(i) << '\\n'; + } + +.SH Possible output: + + dict: { [5]=five [4]=four [1]=one [6]=six [3]=three } + + dict.count\fB(1)\fP = 1 + dict.count\fB(2)\fP = 0 + dict.count\fB(3)\fP = 1 + dict.count\fB(4)\fP = 1 + dict.count\fB(5)\fP = 1 + dict.count\fB(6)\fP = 1 + dict.count\fB(7)\fP = 0 + .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::emplace.3 b/man/std::unordered_map::emplace.3 index 921c442ef..8041a414b 100644 --- a/man/std::unordered_map::emplace.3 +++ b/man/std::unordered_map::emplace.3 @@ -1,20 +1,27 @@ -.TH std::unordered_map::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::emplace \- std::unordered_map::emplace + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - std::pair emplace( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + std::pair emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args, + if there is no element with the key in the container. - Inserts a new element into the container by constructing it in-place with the given - args. + The constructor of the new element (i.e. std::pair) is called with + exactly the same arguments as supplied to emplace, forwarded via + std::forward(args).... The element may be constructed even if there already is + an element with the key in the container, in which case the newly constructed + element will be destroyed immediately. Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element (i.e. - std::pair) is called with exactly the same arguments as supplied to - emplace, forwarded via std::forward(args).... + unnecessary copy or move operations. - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -22,13 +29,14 @@ .SH Return value - Returns a pair consisting of a bool denoting whether the insertion took place and an - iterator to the inserted element, or the already-existing element if no insertion - happened. + A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -36,34 +44,38 @@ .SH Example - + // Run this code #include + #include #include - #include + int main() { std::unordered_map m; - - // uses pair's move constructor (overload 8) + + // uses pair's move constructor m.emplace(std::make_pair(std::string("a"), std::string("a"))); - - // uses pair's converting move constructor (overload 5) + + // uses pair's converting move constructor m.emplace(std::make_pair("b", "abcd")); - - // uses pair's template constructor (overload 3) + + // uses pair's template constructor m.emplace("d", "ddd"); - - // uses pair's piecewise constructor (overload 6) + + // emplace with duplicate key has no effect + m.emplace("d", "DDD"); + + // uses pair's piecewise constructor m.emplace(std::piecewise_construct, std::forward_as_tuple("c"), std::forward_as_tuple(10, 'c')); - - for (const auto &p : m) { + // an alternative is: m.try_emplace("c", 10, 'c'); + + for (const auto& p : m) std::cout << p.first << " => " << p.second << '\\n'; - } } .SH Possible output: @@ -76,6 +88,11 @@ .SH See also emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + try_emplace inserts in-place if the key does not exist, does nothing if the key + \fI(C++17)\fP exists + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::emplace_hint.3 b/man/std::unordered_map::emplace_hint.3 index 2921fe1e8..d08963747 100644 --- a/man/std::unordered_map::emplace_hint.3 +++ b/man/std::unordered_map::emplace_hint.3 @@ -1,20 +1,22 @@ -.TH std::unordered_map::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::emplace_hint \- std::unordered_map::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container, using hint as a suggestion where the + element should go. The constructor of the element type (value_type, that is, std::pair) is called with exactly the same arguments as supplied to the function, forwarded with std::forward(args).... - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -23,18 +25,121 @@ .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element, or to the element that prevented the insertion. + +.SH Exceptions - If the insertion failed because the element already exists, returns an iterator to - the already existing element with the equivalent key. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Amortized constant on average, worst case linear in the size of the container. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const int n_operations = 100'500'0; + + std::size_t map_emplace() + { + std::unordered_map map; + for (int i = 0; i < n_operations; ++i) + map.emplace(i, 'a'); + return map.size(); + } + + std::size_t map_emplace_hint() + { + std::unordered_map map; + auto it = map.begin(); + for (int i = 0; i < n_operations; ++i) + { + map.emplace_hint(it, i, 'b'); + it = map.end(); + } + return map.size(); + } + + std::size_t map_emplace_hint_wrong() + { + std::unordered_map map; + auto it = map.begin(); + for (int i = n_operations; i > 0; --i) + { + map.emplace_hint(it, i, 'c'); + it = map.end(); + } + return map.size(); + } + + std::size_t map_emplace_hint_corrected() + { + std::unordered_map map; + auto it = map.begin(); + for (int i = n_operations; i > 0; --i) + { + map.emplace_hint(it, i, 'd'); + it = map.begin(); + } + return map.size(); + } + + std::size_t map_emplace_hint_closest() + { + std::unordered_map map; + auto it = map.begin(); + for (int i = 0; i < n_operations; ++i) + it = map.emplace_hint(it, i, 'e'); + return map.size(); + } + + double time_it(std::function map_test, + std::string what = "", double ratio = 0.0) + { + const auto start = std::chrono::system_clock::now(); + const std::size_t map_size = map_test(); + const auto stop = std::chrono::system_clock::now(); + std::chrono::duration time = stop - start; + if (what.size() && map_size) + std::cout << std::setw(8) << time << " for " << what << " (ratio: " + << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\\n"; + return time.count(); + } + + int main() + { + std::cout << std::fixed << std::setprecision(2); + time_it(map_emplace); // cache warmup + const auto x = time_it(map_emplace, "plain emplace"); + time_it(map_emplace_hint, "emplace with correct hint", x); + time_it(map_emplace_hint_wrong, "emplace with wrong hint", x); + time_it(map_emplace_hint_corrected, "corrected emplace", x); + time_it(map_emplace_hint_closest, "emplace using returned iterator", x); + } + +.SH Possible output: + + 143.48ms for plain emplace (ratio: 1.00) + 164.78ms for emplace with correct hint (ratio: 0.87) + 171.22ms for emplace with wrong hint (ratio: 0.84) + 166.55ms for corrected emplace (ratio: 0.86) + 167.41ms for emplace using returned iterator (ratio: 0.86) + .SH See also emplace constructs element in-place - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::empty.3 b/man/std::unordered_map::empty.3 index 0dac66b6b..08566639a 100644 --- a/man/std::unordered_map::empty.3 +++ b/man/std::unordered_map::empty.3 @@ -1,6 +1,11 @@ -.TH std::unordered_map::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::empty \- std::unordered_map::empty + .SH Synopsis - bool empty() const; \fI(since C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,13 +15,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the container is empty, false otherwise. .SH Complexity @@ -24,23 +23,24 @@ .SH Example - - The following code uses empty to check if a std::unordered_map contains any - elements: - + The following code uses empty to check if a std::unordered_map contains + any elements: + + // Run this code - #include #include + #include #include - + int main() { - std::unordered_map numbers; + std::unordered_map numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.emplace(42, 13); numbers.insert(std::make_pair(13317, 123)); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -48,10 +48,12 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::unordered_map::end(int),std::unordered_map::cend(int).3 b/man/std::unordered_map::end(int),std::unordered_map::cend(int).3 deleted file mode 100644 index 70941d668..000000000 --- a/man/std::unordered_map::end(int),std::unordered_map::cend(int).3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::unordered_map::end(int),std::unordered_map::cend(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator end( size_type n ); \fI(since C++11)\fP - const_local_iterator end( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the bucket with - index n. . This element acts as a placeholder, attempting to access it results in - undefined behavior. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - iterator to the element following the last element - -.SH Complexity - - Constant - -.SH See also - - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP diff --git a/man/std::unordered_map::end(size_type),.3 b/man/std::unordered_map::end(size_type),.3 new file mode 100644 index 000000000..17326b2e8 --- /dev/null +++ b/man/std::unordered_map::end(size_type),.3 @@ -0,0 +1,30 @@ +.TH std::unordered_map::end(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::end(size_type), \- std::unordered_map::end(size_type), + +.SH Synopsis + + local_iterator end( size_type n ); \fI(since C++11)\fP + const_local_iterator end( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the bucket with + index n. This element acts as a placeholder, attempting to access it results in + undefined behavior. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH See also + + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_map::end,.3 b/man/std::unordered_map::end,.3 new file mode 100644 index 000000000..eb77583cd --- /dev/null +++ b/man/std::unordered_map::end,.3 @@ -0,0 +1,98 @@ +.TH std::unordered_map::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::end, \- std::unordered_map::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator end() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the unordered_map. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct Node { double x, y; }; + + int main() + { + Node nodes[3] = {{1, 0}, {2, 0}, {3, 0}}; + + // mag is a map mapping the address of a Node to its magnitude in the plane + std::unordered_map mag = + { + { nodes + 0, 1 }, + { nodes + 1, 2 }, + { nodes + 2, 3 } + }; + + // Change each y-coordinate from 0 to the magnitude + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; // pointer to Node + cur->y = mag[cur]; // could also have used cur->y = iter->second; + } + + // Update and print the magnitude of each node + for (auto iter = mag.begin(); iter != mag.end(); ++iter) + { + auto cur = iter->first; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << iter->second << '\\n'; + } + + // Repeat the above with the range-based for loop + for (auto i : mag) + { + auto cur = i.first; + cur->y = i.second; + mag[cur] = std::hypot(cur->x, cur->y); + std::cout << "The magnitude of (" << cur->x << ", " << cur->y << ") is "; + std::cout << mag[cur] << '\\n'; + // Note that in contrast to std::cout << iter->second << '\\n'; above, + // std::cout << i.second << '\\n'; will NOT print the updated magnitude + } + } + +.SH Possible output: + + The magnitude of (3, 3) is 4.24264 + The magnitude of (1, 1) is 1.41421 + The magnitude of (2, 2) is 2.82843 + The magnitude of (3, 4.24264) is 5.19615 + The magnitude of (1, 1.41421) is 1.73205 + The magnitude of (2, 2.82843) is 3.4641 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_map::end,std::unordered_map::cend.3 b/man/std::unordered_map::end,std::unordered_map::cend.3 deleted file mode 100644 index e56f526f8..000000000 --- a/man/std::unordered_map::end,std::unordered_map::cend.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::unordered_map::end,std::unordered_map::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the container. - - This element acts as a placeholder; attempting to access it results in undefined - behavior. - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the element following the last element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP diff --git a/man/std::unordered_map::equal_range.3 b/man/std::unordered_map::equal_range.3 index 75c512741..a54b06b7e 100644 --- a/man/std::unordered_map::equal_range.3 +++ b/man/std::unordered_map::equal_range.3 @@ -1,16 +1,31 @@ -.TH std::unordered_map::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::equal_range \- std::unordered_map::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fI(since C++11)\fP - std::pair equal_range( const Key& key \fI(since C++11)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + std::pair equal_range( const Key& \fB(2)\fP \fI(since C++11)\fP + key ) const; + template< class K > \fB(3)\fP \fI(since C++20)\fP + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++20)\fP ) const; - Returns a range containing all elements with key key in the container. The range is - defined by two iterators, the first pointing to the first element of the wanted - range and the second pointing past the last element of the range. + 1,2) Returns a range containing all elements with key key in the container. The + range is defined by two iterators, the first pointing to the first element of the + wanted range and the second pointing past the last element of the range. + 3,4) Returns a range containing all elements in the container with key equivalent to + x. This overload participates in overload resolution only if Hash::is_transparent + and KeyEqual::is_transparent are valid and each denotes a type. This assumes that + such Hash is callable with both K and Key type, and that the KeyEqual is + transparent, which, together, allows calling this function without constructing an + instance of Key. .SH Parameters key - key value to compare the elements to + x - a value of any type that can be transparently compared with a key .SH Return value @@ -20,9 +35,43 @@ .SH Complexity - Average case constant, worst case linear in the size of the container. + Average case linear in the number of elements with the key key, worst case linear in + the size of the container. + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overloads (3,4) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_map map = {{1, 'a'},{2, 'b'}}; + auto range = map.equal_range(1); + for (auto it = range.first; it != range.second; ++it) + std::cout << it->first << ' ' << it->second << '\\n'; + } + +.SH Output: + + 1 a .SH See also - find finds element with specific key - \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::unordered_map::erase.3 b/man/std::unordered_map::erase.3 index 6230f21c8..4cefc4d96 100644 --- a/man/std::unordered_map::erase.3 +++ b/man/std::unordered_map::erase.3 @@ -1,50 +1,120 @@ -.TH std::unordered_map::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator erase( const_iterator pos ); \fB(1)\fP \fI(since C++11)\fP - iterator erase( const_iterator first, const_iterator last ); \fB(2)\fP \fI(since C++11)\fP - size_type erase( const key_type& key ); \fB(3)\fP \fI(since C++11)\fP - - Removes specified elements from the container. +.TH std::unordered_map::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::erase \- std::unordered_map::erase - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. +.SH Synopsis + iterator erase( iterator pos ); \fB(1)\fP \fI(since C++11)\fP + iterator erase( const_iterator pos ); \fB(2)\fP \fI(since C++11)\fP + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP \fI(since C++11)\fP + size_type erase( const Key& key ); \fB(4)\fP \fI(since C++11)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. The order of the remaining elements + is preserved. (This makes it possible to erase individual elements while iterating + through the container.) + + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes the element (if one exists) with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. This assumes that such Hash is + callable with both K and Key type, and that the KeyEqual is transparent, which, + together, allows calling this function without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other iterators and references are not invalidated. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. - - The order of the elements that are not erased is preserved (this makes - it possible to erase individual elements while iterating through the \fI(since C++14)\fP - container) + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed (0 or 1). + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Hash and KeyEqual object. .SH Complexity Given an instance c of unordered_map: - 1) Average case: constant, worst case: c.size() - 2) Average case: std::distance(first, last), worst case: c.size() - 3) Average case: c.count(key), worst case: c.size() + 1,2) Average case: constant, worst case: c.size(). + 3) Average case: std::distance(first, last), worst case: c.size(). + 4) Average case: c.count(key), worst case: c.size(). + 5) Average case: c.count(x), worst case: c.size(). + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_map c = + { + {1, "one"}, {2, "two"}, {3, "three"}, + {4, "four"}, {5, "five"}, {6, "six"} + }; + + // erase all odd numbers from c + for (auto it = c.begin(); it != c.end();) + { + if (it->first % 2 != 0) + it = c.erase(it); + else + ++it; + } + + for (auto& p : c) + std::cout << p.second << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + two four six + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2059 C++11 there was ambiguity for overload \fB(2)\fP added overload \fB(1)\fP + the order of non-equivalent elements + LWG 2356 C++11 that are required to be preserved + not erased was not guaranteed to be + preserved .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::extract.3 b/man/std::unordered_map::extract.3 new file mode 100644 index 000000000..2f0529fd5 --- /dev/null +++ b/man/std::unordered_map::extract.3 @@ -0,0 +1,122 @@ +.TH std::unordered_map::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::extract \- std::unordered_map::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains that element from the container and returns a node handle that owns it. + Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type, + and neither iterator nor const_iterator is implicitly convertible from K. This + assumes that such Hash is callable with both K and Key type, and that the KeyEqual + is transparent, which, together, allows calling this function without constructing + an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed . + + Extracting a node invalidates only the iterators to the extracted element, and + preserves the relative order of the elements that are not erased. Pointers and + references to the extracted element remain valid, but cannot be used while element + is owned by a node handle: they become usable if the element is inserted into a + container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Hash and KeyEqual object. + +.SH Complexity + + 1,2,3) Average case O(1), worst case O(size()). + +.SH Notes + + extract is the only way to change a key of a map element without reallocation: + + std::map m{{1, "mango"}, {2, "papaya"}, {3, "guava"}}; + auto nh = m.extract\fB(2)\fP; + nh.key() = 4; + m.insert(std::move(nh)); + // m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}} + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto [k, v] : data) + std::cout << ' ' << k << '(' << v << ')'; + + std::cout << '\\n'; + } + + int main() + { + std::unordered_map cont{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.key() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Possible output: + + Start: 1(a) 2(b) 3(c) + After extract and before insert: 2(b) 3(c) + End: 2(b) 3(c) 4(a) + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::unordered_map::find.3 b/man/std::unordered_map::find.3 index 607f625e0..c6f77cfa3 100644 --- a/man/std::unordered_map::find.3 +++ b/man/std::unordered_map::find.3 @@ -1,53 +1,96 @@ -.TH std::unordered_map::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::find \- std::unordered_map::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP + iterator find( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP \fI(since C++20)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++20)\fP + const_iterator find( const K& x ) const; 1,2) Finds an element with key equivalent to key. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. .SH Parameters key - key value of the element to search for + x - a value of any type that can be transparently compared with a key .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Constant on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers; overloads (3,4) + .SH Example - + // Run this code + #include + #include #include - #include + #include + #include #include - + + using namespace std::literals; + + struct string_hash + { + using hash_type = std::hash; + using is_transparent = void; + + std::size_t operator()(const char* str) const { return hash_type{}(str); } + std::size_t operator()(std::string_view str) const { return hash_type{}(str); } + std::size_t operator()(std::string const& str) const { return hash_type{}(str); } + }; + int main() { - std::unordered_map map_ex; - map_ex.insert({{1,'a'},{2,'b'}}); - std::unordered_map::const_iterator search = map_ex.find(1); - if(search != map_ex.end()) { - std::cout << "Found " << search->first << " " << search->second << "\\n"; - } - else { - std::cout << "Not found" << std::endl; - } - return 0; + // simple comparison demo + std::unordered_map example{{1, 'a'}, {2, 'b'}}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << search->first << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; + + // C++20 demo: Heterogeneous lookup for unordered containers (transparent hashing) + std::unordered_map> map{{"one"s, 1}}; + std::cout << std::boolalpha + << (map.find("one") != map.end()) << '\\n' + << (map.find("one"s) != map.end()) << '\\n' + << (map.find("one"sv) != map.end()) << '\\n'; } .SH Output: - Found 1 a + Found 2 b + true + true + true .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::get_allocator.3 b/man/std::unordered_map::get_allocator.3 index 85a5b766d..277d90a9e 100644 --- a/man/std::unordered_map::get_allocator.3 +++ b/man/std::unordered_map::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::unordered_map::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::get_allocator \- std::unordered_map::get_allocator + .SH Synopsis - allocator_type get_allocator() const; \fI(since C++11)\fP + allocator_type get_allocator() const noexcept; \fI(since C++11)\fP Returns the allocator associated with the container. diff --git a/man/std::unordered_map::hash_function.3 b/man/std::unordered_map::hash_function.3 index a9f52c0ab..f636f544e 100644 --- a/man/std::unordered_map::hash_function.3 +++ b/man/std::unordered_map::hash_function.3 @@ -1,4 +1,7 @@ -.TH std::unordered_map::hash_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::hash_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::hash_function \- std::unordered_map::hash_function + .SH Synopsis hasher hash_function() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::insert.3 b/man/std::unordered_map::insert.3 index 87e374204..11f83768d 100644 --- a/man/std::unordered_map::insert.3 +++ b/man/std::unordered_map::insert.3 @@ -1,32 +1,62 @@ -.TH std::unordered_map::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::insert \- std::unordered_map::insert + .SH Synopsis - std::pair insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP - template< class P > \fB(2)\fP \fI(since C++11)\fP - std::pair insert( P&& value ); - iterator insert( const_iterator hint, const value_type& value ); \fB(3)\fP \fI(since C++11)\fP - template< class P > \fB(4)\fP \fI(since C++11)\fP + std::pair insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP + std::pair insert( value_type&& value ); \fB(2)\fP \fI(since C++17)\fP + template< class P > \fB(3)\fP \fI(since C++11)\fP + std::pair insert( P&& value ); + iterator insert( const_iterator hint, const value_type& value ); \fB(4)\fP \fI(since C++11)\fP + iterator insert( const_iterator hint, value_type&& value ); \fB(5)\fP \fI(since C++17)\fP + template< class P > \fB(6)\fP \fI(since C++11)\fP iterator insert( const_iterator hint, P&& value ); - template< class InputIt > \fB(5)\fP \fI(since C++11)\fP + template< class InputIt > \fB(7)\fP \fI(since C++11)\fP void insert( InputIt first, InputIt last ); - void insert( std::initializer_list ilist ); \fB(6)\fP \fI(since C++11)\fP + void insert( std::initializer_list ilist ); \fB(8)\fP \fI(since C++11)\fP + insert_return_type insert( node_type&& nh ); \fB(9)\fP \fI(since C++17)\fP + iterator insert( const_iterator hint, node_type&& nh ); \fB(10)\fP \fI(since C++17)\fP Inserts element(s) into the container, if the container doesn't already contain an element with an equivalent key. - 1-2) Inserts value. The overload \fB(2)\fP is equivalent to - emplace(std::forward

(value)) and only participates in overload resolution if - std::is_constructible::value == true. - 3-4) Inserts value, using hint as a non-binding suggestion to where the search - should start. The overload \fB(4)\fP is equivalent to emplace_hint(hint, - std::forward

(value)) and only participates in overload resolution if - std::is_constructible::value == true. - 5) Inserts elements from range [first, last). - 6) Inserts elements from initializer list ilist. - - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + 1-3) Inserts value. + Overload \fB(3)\fP is equivalent to emplace(std::forward

(value)) and only participates + in overload resolution if std::is_constructible::value == true. + 4-6) Inserts value, using hint as a non-binding suggestion to where the search + should start. + Overload \fB(6)\fP is equivalent to emplace_hint(hint, std::forward

(value)) and only + participates in overload resolution if std::is_constructible::value + == true. + 7) Inserts elements from range [first, last). If multiple elements in the range have + keys that compare equivalent, it is unspecified which element is inserted (pending + LWG2844). + If [first, last) is not a valid range, or first and/or last are iterators into + *this, the behavior is undefined. + 8) Inserts elements from initializer list ilist. If multiple elements in the range + have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). + 9) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container , if the container doesn't already contain an element with + a key equivalent to nh.key(). The behavior is undefined if nh is not empty and + get_allocator() != nh.get_allocator(). + 10) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, if the container + doesn't already contain an element with a key equivalent to nh.key(), and returns + the iterator pointing to the element with key equivalent to nh.key()(regardless of + whether the insert succeeded or failed). If the insertion succeeds, nh is moved + from, otherwise it retains ownership of the element. hint is used as a non-binding + suggestion to where the search should start. The behavior is undefined if nh is not + empty and get_allocator() != nh.get_allocator(). + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters @@ -34,39 +64,106 @@ value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-2) Returns a pair consisting of an iterator to the inserted element (or to the - element that prevented the insertion) and a bool denoting whether the insertion took - place. - 3-4) Returns an iterator to the inserted element, or to the element that prevented - the insertion. - 5-6) \fI(none)\fP + 1-3) A pair consisting of an iterator to the inserted element (or to the element + that prevented the insertion) and a bool value set to true if and only if the + insertion took place. + 4-6) An iterator to the inserted element, or to the element that prevented the + insertion. + 7,8) \fI(none)\fP + 9) An object of insert_return_type with the members initialized as follows: + * If nh is empty, inserted is false, position is end(), and node is empty. + * Otherwise if the insertion took place, inserted is true, position points to the + inserted element, and node is empty. + * If the insertion failed, inserted is false, node has the previous value of nh, + and position points to an element with a key equivalent to nh.key(). + 10) End iterator if nh was empty, iterator pointing to the inserted element if + insertion took place, and iterator pointing to an element with a key equivalent to + nh.key() if it failed. .SH Exceptions - 1-4) If an exception is thrown by any operation, the insertion has no effect. - - This section is incomplete - Reason: cases 5-6 + 1-6) If an exception is thrown for any reason, these functions have no effect + (strong exception safety guarantee). + 7,8) No exception safety guarantee. + 9,10) If an exception is thrown for any reason, these functions have no effect + (strong exception safety guarantee). .SH Complexity - 1-4) Average case: O(1), worst case O(size()) - 5-6) Average case: O(N), where N is the number of elements to insert. Worse case: - O(N*size()+N) + 1-6) Average case: O(1), worst case O(size()). + 7,8) Average case: O(N), where N is the number of elements to insert. Worst case: + O(N * size() + N). + 9,10) Average case: O(1), worst case O(size()). -.SH See also +.SH Notes + + The hinted insert (4-6) does not return a boolean in order to be + signature-compatible with positional insert on sequential containers, such as + std::vector::insert. This makes it possible to create generic inserters such as + std::inserter. One way to check success of a hinted insert is to compare size() + before and after. + +.SH Example + + +// Run this code + + #include + #include + #include - emplace constructs element in-place - \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP + int main () + { + std::unordered_map dict = {{1, "one"}, {2, "two"}}; + dict.insert({3, "three"}); + dict.insert(std::make_pair(4, "four")); + dict.insert({{4, "another four"}, {5, "five"}}); -.SH Category: + const bool ok = dict.insert({1, "another one"}).second; + std::cout << "inserting 1 => \\"another one\\" " + << (ok ? "succeeded" : "failed") << '\\n'; + + std::cout << "contents:\\n"; + for (auto& p : dict) + std::cout << ' ' << p.first << " => " << p.second << '\\n'; + } + +.SH Possible output: + + inserting 1 => "another one" failed + contents: + 5 => five + 1 => one + 2 => two + 3 => three + 4 => four + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overloads (3,6) would only only participates if + LWG 2005 C++11 participate in overload value_type + resolution if P is implicitly is constructible from P&& + convertible to value_type + +.SH See also - * Todo with reason + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + insert_or_assign inserts an element or assigns to the current element if the key + \fI(C++17)\fP already exists + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::unordered_map::insert_or_assign.3 b/man/std::unordered_map::insert_or_assign.3 new file mode 100644 index 000000000..cbbf81d79 --- /dev/null +++ b/man/std::unordered_map::insert_or_assign.3 @@ -0,0 +1,135 @@ +.TH std::unordered_map::insert_or_assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::insert_or_assign \- std::unordered_map::insert_or_assign + +.SH Synopsis + template< class M > + std::pair insert_or_assign( const Key& k, M&& obj \fB(1)\fP \fI(since C++17)\fP + ); + template< class M > \fB(2)\fP \fI(since C++17)\fP + std::pair insert_or_assign( Key&& k, M&& obj ); + template< class K, class M > \fB(3)\fP (since C++26) + std::pair insert_or_assign( K&& k, M&& obj ); + template< class M > + iterator insert_or_assign( const_iterator hint, const Key& k, M&& \fB(4)\fP \fI(since C++17)\fP + obj ); + template< class M > + iterator insert_or_assign( const_iterator hint, Key&& k, M&& obj \fB(5)\fP \fI(since C++17)\fP + ); + template< class K, class M > \fB(6)\fP (since C++26) + iterator insert_or_assign( const_iterator hint, K&& k, M&& obj ); + + 1,4) If a key equivalent to k already exists in the container, assigns + std::forward(obj) to the mapped_type corresponding to the key k. If the key does + not exist, inserts the new value as if by insert, constructing it from value_type(k, + std::forward(obj)). + 2,5) Same as (1,4), except the mapped value is constructed from + value_type(std::move(k), std::forward(obj)). + 3,6) If a key equivalent to k already exists in the container, assigns + std::forward(obj) to the mapped_type corresponding to the key k. If the key does + not exist, constructs an object u of value_type with std::forward(k), + std::forward(obj)), then inserts u into *this. If hash_function()(u.first) != + hash_function()(k) || contains(u.first) is true, the behavior is undefined. The + value_type must be EmplaceConstructible into unordered_map from std::forward(k), + std::forward(obj). This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. + + The behavior is undefined + \fI(until C++20)\fP + The program is ill-formed + \fI(since C++20)\fP if std::is_assignable_v is false. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + +.SH Parameters + + k - the key used both to look up and to insert if not found + hint - iterator to the position before which the new element will be inserted + obj - the value to insert or assign + +.SH Return value + + 1-3) The bool component is true if the insertion took place and false if the + assignment took place. The iterator component is pointing at the element that was + inserted or updated. + 4-6) Iterator pointing at the element that was inserted or updated. + +.SH Complexity + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Notes + + insert_or_assign returns more information than operator[] and does not require + default-constructibility of the mapped type. + + Feature-test macro Value Std Feature +__cpp_lib_unordered_map_try_emplace 201411L \fI(C++17)\fP std::unordered_map::try_emplace, + std::unordered_map::insert_or_assign + Heterogeneous overloads for the +__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) remaining member functions in + ordered and unordered associative + containers. Overloads \fB(3)\fP and \fB(6)\fP. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print_node(const auto& node) + { + std::cout << '[' << node.first << "] = " << node.second << '\\n'; + } + + void print_result(auto const& pair) + { + std::cout << (pair.second ? "inserted: " : "assigned: "); + print_node(*pair.first); + } + + int main() + { + std::unordered_map myMap; + + print_result(myMap.insert_or_assign("a", "apple")); + print_result(myMap.insert_or_assign("b", "banana")); + print_result(myMap.insert_or_assign("c", "cherry")); + print_result(myMap.insert_or_assign("c", "clementine")); + + for (const auto& node : myMap) + print_node(node); + } + +.SH Possible output: + + inserted: [a] = apple + inserted: [b] = banana + inserted: [c] = cherry + assigned: [c] = clementine + [c] = clementine + [a] = apple + [b] = banana + +.SH See also + + operator[] access or insert specified element + \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + emplace constructs element in-place + \fI(public member function)\fP diff --git a/man/std::unordered_map::insert_range.3 b/man/std::unordered_map::insert_range.3 new file mode 100644 index 000000000..8845b7655 --- /dev/null +++ b/man/std::unordered_map::insert_range.3 @@ -0,0 +1,79 @@ +.TH std::unordered_map::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::insert_range \- std::unordered_map::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg if and only if there is no element + with key equivalent to the key of that element in *this. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose + elements are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into unordered_map from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), where N is ranges::distance(rg), worst case O(N·(a.size() + 1)). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto, auto const& container) + { + for (const auto& [key, value] : container) + std::cout << '{' << key << ',' << value << '}' << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::unordered_map{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}}; + const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Possible output: + + {4,44} {-1,-11} {2,22} {3,33} {-2,-22} {1,11} + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::key_eq.3 b/man/std::unordered_map::key_eq.3 index 18821d4a7..561d6a007 100644 --- a/man/std::unordered_map::key_eq.3 +++ b/man/std::unordered_map::key_eq.3 @@ -1,4 +1,7 @@ -.TH std::unordered_map::key_eq 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::key_eq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::key_eq \- std::unordered_map::key_eq + .SH Synopsis key_equal key_eq() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also hash_function returns function used to hash the keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::load_factor.3 b/man/std::unordered_map::load_factor.3 index 55be75158..19e02fe5a 100644 --- a/man/std::unordered_map::load_factor.3 +++ b/man/std::unordered_map::load_factor.3 @@ -1,8 +1,12 @@ -.TH std::unordered_map::load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::load_factor \- std::unordered_map::load_factor + .SH Synopsis float load_factor() const; \fI(since C++11)\fP - Returns the average number of elements per bucket. + Returns the average number of elements per bucket, that is, size() divided by + bucket_count(). .SH Parameters @@ -19,4 +23,4 @@ .SH See also max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::max_bucket_count.3 b/man/std::unordered_map::max_bucket_count.3 index 95c549f1c..bb8310026 100644 --- a/man/std::unordered_map::max_bucket_count.3 +++ b/man/std::unordered_map::max_bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_map::max_bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::max_bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::max_bucket_count \- std::unordered_map::max_bucket_count + .SH Synopsis size_type max_bucket_count() const; \fI(since C++11)\fP @@ -17,7 +20,41 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + struct Ha { std::size_t operator()(long x) const { return std::hash{}(x); }; }; + + auto c1 = std::unordered_map{}; + auto c2 = std::unordered_map{}; + auto c3 = std::unordered_map>{}; + auto c4 = std::unordered_map{}; + + std::cout + << "Max bucket count of\\n" << std::hex << std::showbase + << "c1: " << c1.max_bucket_count() << '\\n' + << "c2: " << c2.max_bucket_count() << '\\n' + << "c3: " << c3.max_bucket_count() << '\\n' + << "c4: " << c4.max_bucket_count() << '\\n' + ; + } + +.SH Possible output: + + Max bucket count of + c1: 0xfffffffffffffff + c2: 0xfffffffffffffff + c3: 0xfffffffffffffff + c4: 0xaaaaaaaaaaaaaaa + .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::max_load_factor.3 b/man/std::unordered_map::max_load_factor.3 index a76e5527d..8c6785fd8 100644 --- a/man/std::unordered_map::max_load_factor.3 +++ b/man/std::unordered_map::max_load_factor.3 @@ -1,4 +1,7 @@ -.TH std::unordered_map::max_load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::max_load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::max_load_factor \- std::unordered_map::max_load_factor + .SH Synopsis float max_load_factor() const; \fB(1)\fP \fI(since C++11)\fP void max_load_factor( float ml ); \fB(2)\fP \fI(since C++11)\fP @@ -8,7 +11,6 @@ threshold. 1) Returns current maximum load factor. - 2) Sets the maximum load factor to ml. .SH Parameters @@ -17,15 +19,14 @@ .SH Return value - 1) current maximum load factor. - - 2) none. + 1) Current maximum load factor. + 2) \fI(none)\fP .SH Complexity - Constant + Constant. .SH See also load_factor returns average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::max_size.3 b/man/std::unordered_map::max_size.3 index 8e11a71bc..1d68541f5 100644 --- a/man/std::unordered_map::max_size.3 +++ b/man/std::unordered_map::max_size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_map::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::max_size \- std::unordered_map::max_size + .SH Synopsis - size_type max_size() const; \fI(since C++11)\fP + size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,24 +17,45 @@ Maximum number of elements. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_map p; + std::unordered_map q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + q.max_size() = 768,614,336,404,564,650 = 0xAAA,AAA,AAA,AAA,AAA + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::merge.3 b/man/std::unordered_map::merge.3 new file mode 100644 index 000000000..9b7159295 --- /dev/null +++ b/man/std::unordered_map::merge.3 @@ -0,0 +1,98 @@ +.TH std::unordered_map::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::merge \- std::unordered_map::merge + +.SH Synopsis + template< class H2, class P2 > + void merge( std::unordered_map& source \fB(1)\fP \fI(since C++17)\fP + ); + template< class H2, class P2 > + void merge( std::unordered_map&& source \fB(2)\fP \fI(since C++17)\fP + ); + template< class H2, class P2 > + void merge( std::unordered_multimap& \fB(3)\fP \fI(since C++17)\fP + source ); + template< class H2, class P2 > + void merge( std::unordered_multimap&& \fB(4)\fP \fI(since C++17)\fP + source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the hash function and key equality predicate of *this. If there is an element in + *this with key equivalent to the key of an element from source, then that element is + not extracted from source. No elements are copied or moved, only the internal + pointers of the container nodes are repointed. All pointers and references to the + transferred elements remain valid, but now refer into *this, not into source. + Iterators referring to the transferred elements and all iterators referring to *this + are invalidated. Iterators to elements remaining in source remain valid. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), worst case O(N * size() + N), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // print out a std::pair + template + Os& operator<<(Os& os, const std::pair& p) + { + return os << '{' << p.first << ", " << p.second << '}'; + } + + // print out an associative container + template + Os& operator<<(Os& os, const std::unordered_map& v) + { + os << '[' << v.size() << "] {"; + bool o{}; + for (const auto& e : v) + os << (o ? ", " : (o = 1, "")) << e; + return os << "}\\n"; + } + + int main() + { + std::unordered_map + p{{"C", 3}, {"B", 2}, {"A", 1}, {"A", 0}}, + q{{"E", 6}, {"E", 7}, {"D", 5}, {"A", 4}}; + + std::cout << "p: " << p << "q: " << q; + + p.merge(q); + + std::cout << "p.merge(q);\\n" << "p: " << p << "q: " << q; + } + +.SH Possible output: + + p: [3] {{A, 1}, {B, 2}, {C, 3}} + q: [3] {{A, 4}, {D, 5}, {E, 6}} + p.merge(q); + p: [5] {{E, 6}, {D, 5}, {A, 1}, {B, 2}, {C, 3}} + q: [1] {{A, 4}} + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::operator=.3 b/man/std::unordered_map::operator=.3 index df3a692ef..40e36ed76 100644 --- a/man/std::unordered_map::operator=.3 +++ b/man/std::unordered_map::operator=.3 @@ -1,28 +1,40 @@ -.TH std::unordered_map::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::operator= \- std::unordered_map::operator= + .SH Synopsis - unordered_map& operator=( const unordered_map& other ); \fB(1)\fP \fI(since C++11)\fP - unordered_map& operator=( unordered_map&& other ); \fB(2)\fP \fI(since C++11)\fP - unordered_map& operator=( std::initializer_list ilist \fB(3)\fP \fI(since C++11)\fP + unordered_map& operator=( const unordered_map& other \fB(1)\fP \fI(since C++11)\fP ); + unordered_map& operator=( unordered_map&& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + unordered_map& operator=( unordered_map&& other ) \fB(2)\fP \fI(since C++17)\fP + noexcept(/* see below */); + unordered_map& operator=( \fB(3)\fP \fI(since C++11)\fP + std::initializer_list ilist ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + If + std::allocator_traits::propagate_on_container_copy_assignment::value + is true, the allocator of *this is replaced by a copy of other. If the allocator of + *this after assignment would compare unequal to its old value, the old allocator is + used to deallocate the memory, then the new allocator is used to allocate it before + copying the elements. Otherwise, the memory owned by *this may be reused when + possible. In any case, the elements originally belonging to *this may be either + destroyed or replaced by element-wise copy-assignment. 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -36,67 +48,100 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + + && std::is_nothrow_move_assignable::value + + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::unordered_map to another: - The following code uses to assign one std::unordered_map to another: - // Run this code - #include + #include #include - - void display_sizes(const std::unordered_map &nums1, - const std::unordered_map &nums2, - const std::unordered_map &nums3) + #include + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& [key, value] : container) + std::cout << '{' << key << ',' << value << (--size ? "}, " : "} "); + std::cout << "}\\n"; } - + int main() { - std::unordered_map nums1 {{3, 1}, {4, 1}, {5, 9}, - {6, 1}, {7, 1}, {8, 9}}; - std::unordered_map nums2; - std::unordered_map nums3; - + std::unordered_map x{{1,1}, {2,2}, {3,3}}, y, z; + const auto w = {std::pair{4,4}, {5,5}, {6,6}, {7,7}}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } -.SH Output: +.SH Possible output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { {3,3}, {2,2}, {1,1} } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { {3,3}, {2,2}, {1,1} } + y = { {3,3}, {2,2}, {1,1} } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { {3,3}, {2,2}, {1,1} } + Assignment of initializer_list w to z: + w = { {4,4}, {5,5}, {6,6}, {7,7} } + z = { {7,7}, {6,6}, {5,5}, {4,4} } .SH See also constructor constructs the unordered_map - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_map::operator[].3 b/man/std::unordered_map::operator[].3 index c16c6fa16..04a42b7ac 100644 --- a/man/std::unordered_map::operator[].3 +++ b/man/std::unordered_map::operator[].3 @@ -1,133 +1,162 @@ -.TH std::unordered_map::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::operator[] \- std::unordered_map::operator[] + .SH Synopsis T& operator[]( const Key& key ); \fB(1)\fP \fI(since C++11)\fP T& operator[]( Key&& key ); \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP (since C++26) + T& operator[]( K&& x ); - Returns a reference to the value that is mapped to a key equivalent to key, - performing an insertion if such key does not already exist. - - If an insertion is performed, the mapped value is value-initialized - (default-constructed for class types, zero-initialized otherwise) and a reference to - it is returned. + Returns a reference to the value that is mapped to a key equivalent to key or x + respectively, performing an insertion if such key does not already exist. - 1) Inserts value_type(key, T()) + 1) Inserts a value_type object constructed in-place from std::piecewise_construct, + std::forward_as_tuple(key), std::tuple<>() if the key does not exist. + Equivalent to return this->try_emplace(key).first->second;. + \fI(since C++17)\fPWhen the default allocator is used, this results in the key being copy + constructed from key and the mapped value being value-initialized. - - key_type must meet the requirements of CopyConstructible. - - - mapped_type must meet the requirements of DefaultConstructible. \fI(since C++11)\fP + value_type must be EmplaceConstructible from std::piecewise_construct, + std::forward_as_tuple(key), std::tuple<>(). When the default allocator is used, this + means that key_type must be CopyConstructible and mapped_type must be + DefaultConstructible. + + 2) Inserts a value_type object constructed in-place from std::piecewise_construct, + std::forward_as_tuple(std::move(key)), std::tuple<>() if the key does not exist. + Equivalent to return this->try_emplace(std::move(key)).first->second;. + \fI(since C++17)\fP + When the default allocator is used, this results in the key being move constructed + from key and the mapped value being value-initialized. - 2) Inserts value_type(std::move(key), T()) - - - - key_type must meet the requirements of MoveConstructible. \fI(since C++11)\fP - - mapped_type must meet the requirements of DefaultConstructible. \fI(since C++11)\fP - - If an insertion occurs and results in a rehashing of the container, all iterators - are invalidated. Otherwise iterators are not affected. References are not - invalidated. Rehashing occurs only if the new number of elements is equal to or - greater than max_load_factor()*bucket_count(). + value_type must be EmplaceConstructible from std::piecewise_construct, + std::forward_as_tuple(std::move(key)), std::tuple<>(). When the default allocator is + used, this means that key_type must be MoveConstructible and mapped_type must be + DefaultConstructible. + + 3) Inserts a value_type object constructed in-place if there is no key that + transparently compares equivalent to the value x. + Equivalent to return this->try_emplace(std::forward(x)).first->second;. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters key - the key of the element to find + x - a value of any type that can be transparently compared with a key .SH Return value - Reference to the mapped value of the new element if no element with key key existed. - Otherwise a reference to the mapped value of the existing element whose key is - equivalent to key. + 1,2) A reference to the mapped value of the new element if no element with key key + existed. Otherwise, a reference to the mapped value of the existing element whose + key is equivalent to key. + 3) A reference to the mapped value of the new element if no element with key that + compares equivalent to the value x existed. Otherwise, a reference to the mapped + value of the existing element whose key compares equivalent to x. .SH Exceptions - If an exception is thrown by any operation, the insertion has no effect + If an exception is thrown by any operation, the insertion has no effect. .SH Complexity Average case: constant, worst case: linear in size. +.SH Notes + + In the published C++11 and C++14 standards, this function was specified to require + mapped_type to be DefaultInsertable and key_type to be CopyInsertable or + MoveInsertable into *this. This specification was defective and was fixed by LWG + issue 2469, and the description above incorporates the resolution of that issue. + + However, one implementation (libc++) is known to construct the key_type and + mapped_type objects via two separate allocator construct() calls, as arguably + required by the standards as published, rather than emplacing a value_type object. + + operator[] is non-const because it inserts the key if it doesn't exist. If this + behavior is undesirable or if the container is const, at may be used. + + insert_or_assign returns more information than operator[] and does not \fI(since C++17)\fP + require default-constructibility of the mapped type. + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. \fB(3)\fP + .SH Example - This example demonstrates how to modify existing values and insert new values using - operator[]: - // Run this code #include + #include #include - - int main() + + void println(auto const comment, auto const& map) { - std::unordered_map letter_counts {{'a', 27}, {'b', 3}, {'c', 1}}; - - std::cout << "initially:\\n"; - for (const auto &pair : letter_counts) { - std::cout << pair.first << ": " << pair.second << '\\n'; - } - - letter_counts['b'] = 42; // update an existing value - - letter_counts['x'] = 9; // insert a new value - - std::cout << "after modifications:\\n"; - for (const auto &pair : letter_counts) { - std::cout << pair.first << ": " << pair.second << '\\n'; - } + std::cout << comment << '{'; + for (const auto& pair : map) + std::cout << '{' << pair.first << ": " << pair.second << '}'; + std::cout << "}\\n"; } -.SH Output: + int main() + { + std::unordered_map letter_counts{{'a', 27}, {'b', 3}, {'c', 1}}; - initially: - a: 27 - b: 3 - c: 1 - after modifications: - a: 27 - b: 42 - c: 1 - x: 9 + println("letter_counts initially contains: ", letter_counts); - The following example counts the occurrences of each word in a vector of strings: + letter_counts['b'] = 42; // updates an existing value + letter_counts['x'] = 9; // inserts a new value - -// Run this code + println("after modifications it contains: ", letter_counts); - #include - #include - #include - #include - - int main() - { - std::vector words = { - "this", "sentence", "is", "not", "a", "sentence", - "this", "sentence", "is", "a", "hoax" - }; - - std::unordered_map word_map; - for (const auto &w : words) { + // count the number of occurrences of each word + // (the first call to operator[] initialized the counter with zero) + std::unordered_map word_map; + for (const auto& w : {"this", "sentence", "is", "not", "a", "sentence", + "this", "sentence", "is", "a", "hoax"}) ++word_map[w]; - } - - for (const auto &pair : word_map) { - std::cout << pair.second - << " occurrences of word '" - << pair.first << "'\\n"; - } + word_map["that"]; // just inserts the pair {"that", 0} + + for (const auto& [word, count] : word_map) + std::cout << count << " occurrence(s) of word '" << word << "'\\n"; } -.SH Output: +.SH Possible output: - 1 occurrences of word 'hoax' - 2 occurrences of word 'this' - 2 occurrences of word 'a' - 2 occurrences of word 'is' - 1 occurrences of word 'not' - 3 occurrences of word 'sentence' + letter_counts initially contains: {{a: 27}{b: 3}{c: 1}} + after modifications it contains: {{a: 27}{b: 42}{c: 1}{x: 9}} + 2 occurrence(s) of word 'a' + 1 occurrence(s) of word 'hoax' + 2 occurrence(s) of word 'is' + 1 occurrence(s) of word 'not' + 3 occurrence(s) of word 'sentence' + 0 occurrence(s) of word 'that' + 2 occurrence(s) of word 'this' .SH See also - at access specified element with bounds checking - \fI(public member function)\fP + at access specified element with bounds checking + \fI(public member function)\fP + insert_or_assign inserts an element or assigns to the current element if the key + \fI(C++17)\fP already exists + \fI(public member function)\fP + try_emplace inserts in-place if the key does not exist, does nothing if the key + \fI(C++17)\fP exists + \fI(public member function)\fP diff --git a/man/std::unordered_map::rehash.3 b/man/std::unordered_map::rehash.3 index 5bf4ca9ba..11e91e3b6 100644 --- a/man/std::unordered_map::rehash.3 +++ b/man/std::unordered_map::rehash.3 @@ -1,16 +1,17 @@ -.TH std::unordered_map::rehash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::rehash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::rehash \- std::unordered_map::rehash + .SH Synopsis void rehash( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to count and rehashes the container, i.e. puts the - elements into appropriate buckets considering that total number of buckets has - changed. If the new number of buckets makes load factor more than maximum load - factor (count < size() / max_load_factor()), then the new number of buckets is at - least size() / max_load_factor(). + Changes the number of buckets to a value n that is not less than count and satisfies + n >= size() / max_load_factor(), then rehashes the container, i.e. puts the elements + into appropriate buckets considering that total number of buckets has changed. .SH Parameters - count - new number of buckets + count - lower bound for the new number of buckets .SH Return value @@ -23,10 +24,10 @@ .SH Notes rehash\fB(0)\fP may be used to force an unconditional rehash, such as after suspension of - automatic rehashing by temporary increasing max_load_factor(). + automatic rehashing by temporarily increasing max_load_factor(). .SH See also - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + reserves space for at least the specified number of elements and regenerates + reserve the hash table + \fI(public member function)\fP diff --git a/man/std::unordered_map::reserve.3 b/man/std::unordered_map::reserve.3 index c3bc5f2f6..94a5aaf50 100644 --- a/man/std::unordered_map::reserve.3 +++ b/man/std::unordered_map::reserve.3 @@ -1,8 +1,11 @@ -.TH std::unordered_map::reserve 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::reserve \- std::unordered_map::reserve + .SH Synopsis void reserve( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to the number needed to accomodate at least count + Sets the number of buckets to the number needed to accommodate at least count elements without exceeding maximum load factor and rehashes the container, i.e. puts the elements into appropriate buckets considering that total number of buckets has changed. Effectively calls rehash(std::ceil(count / max_load_factor())). @@ -21,6 +24,6 @@ .SH See also - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates the hash + rehash table + \fI(public member function)\fP diff --git a/man/std::unordered_map::size.3 b/man/std::unordered_map::size.3 index 24270e9dd..430bdcb06 100644 --- a/man/std::unordered_map::size.3 +++ b/man/std::unordered_map::size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_map::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::size \- std::unordered_map::size + .SH Synopsis - size_type size() const; \fI(since C++11)\fP + size_type size() const noexcept; \fI(since C++11)\fP Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,27 @@ The number of elements in the container. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::unordered_map: - + // Run this code - #include #include - + #include + int main() { - std::unordered_map nums {{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; - + std::unordered_map nums{{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +46,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::unordered_map::swap.3 b/man/std::unordered_map::swap.3 index 3559b8ef6..9faa76f1f 100644 --- a/man/std::unordered_map::swap.3 +++ b/man/std::unordered_map::swap.3 @@ -1,19 +1,24 @@ -.TH std::unordered_map::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::swap \- std::unordered_map::swap + .SH Synopsis - void swap( unordered_map& other ); \fI(since C++11)\fP + void swap( unordered_map& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + void swap( unordered_map& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. The Hash and KeyEqual objects must be Swappable, and they are exchanged using unqualified calls to non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +30,86 @@ .SH Exceptions - Any exception thrown by the swap Hash or KeyEqual objects. + Any exception thrown by the swap of the Hash or KeyEqual objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value + \fI(since C++17)\fP + && std::is_nothrow_swappable::value + + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // print out a std::pair + template + Os& operator<<(Os& os, const std::pair& p) + { + return os << p.first << ':' << p.second; + } + + // print out a container + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " }\\n"; + } + + int main() + { + std::unordered_map + m1{{"γ", "gamma"}, {"β", "beta"}, {"α", "alpha"}, {"γ", "gamma"}}, + m2{{"ε", "epsilon"}, {"δ", "delta"}, {"ε", "epsilon"}}; + + const auto& ref = *(m1.begin()); + const auto iter = std::next(m1.cbegin()); + + std::cout << "──────── before swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + m1.swap(m2); + + std::cout << "──────── after swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + // Note that every iterator referring to an element in one container before + // the swap refers to the same element in the other container after the swap. + // Same is true for references. + } + +.SH Possible output: + + ──────── before swap ──────── + m1: { α:alpha β:beta γ:gamma } + m2: { δ:delta ε:epsilon } + ref: α:alpha + iter: β:beta + ──────── after swap ──────── + m1: { δ:delta ε:epsilon } + m2: { α:alpha β:beta γ:gamma } + ref: α:alpha + iter: β:beta + .SH See also std::swap(std::unordered_map) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_map::try_emplace.3 b/man/std::unordered_map::try_emplace.3 new file mode 100644 index 000000000..8ecbd6cfc --- /dev/null +++ b/man/std::unordered_map::try_emplace.3 @@ -0,0 +1,172 @@ +.TH std::unordered_map::try_emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::try_emplace \- std::unordered_map::try_emplace + +.SH Synopsis + template< class... Args > + std::pair try_emplace( const Key& k, Args&&... \fB(1)\fP \fI(since C++17)\fP + args ); + template< class... Args > \fB(2)\fP \fI(since C++17)\fP + std::pair try_emplace( Key&& k, Args&&... args ); + template< class K, class... Args > \fB(3)\fP (since C++26) + std::pair try_emplace( K&& k, Args&&... args ); + template< class... Args > + iterator try_emplace( const_iterator hint, const Key& k, Args&&... \fB(4)\fP \fI(since C++17)\fP + args ); + template< class... Args > + iterator try_emplace( const_iterator hint, Key&& k, Args&&... args \fB(5)\fP \fI(since C++17)\fP + ); + template< class K, class... Args > + iterator try_emplace( const_iterator hint, K&& k, Args&&... args \fB(6)\fP (since C++26) + ); + + If a key equivalent to k already exists in the container, does nothing. Otherwise, + inserts a new element into the container with key k and value constructed with args. + In such case: + + 1) Behaves like emplace except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(k), + + std::forward_as_tuple(std::forward(args)...)) + 2) Behaves like emplace except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::move(k)), + + std::forward_as_tuple(std::forward(args)...)) + 3) Behaves like emplace except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::forward(k)), + + std::forward_as_tuple(std::forward(args)...)) + 4) Behaves like emplace_hint except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(k), + + std::forward_as_tuple(std::forward(args)...)) + 5) Behaves like emplace_hint except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::move(k)), + + std::forward_as_tuple(std::forward(args)...)) + 6) Behaves like emplace_hint except that the element is constructed as + value_type(std::piecewise_construct, + + std::forward_as_tuple(std::forward(k)), + + std::forward_as_tuple(std::forward(args)...)) + 1-6) If value_type is not EmplaceConstructible into unordered_map from the + corresponding expression, the behavior is undefined. + 3) This overload participates in overload resolution only if all following + conditions are satisfied: + * std::is_convertible_v and std::is_convertible_v are both false. + * Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a + type. + If hash_function()(u.first) != hash_function()(k) || contains(u.first) is true, the + behavior is undefined, where u is the new element to be inserted. + 6) This overload participates in overload resolution only if Hash::is_transparent + and KeyEqual::is_transparent are both valid and each denotes a type. + If hash_function()(u.first) != hash_function()(k) || contains(u.first) is true, the + behavior is undefined, where u is the new element to be inserted. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + +.SH Parameters + + k - the key used both to look up and to insert if not found + hint - iterator to the position before which the new element will be inserted + args - arguments to forward to the constructor of the element + +.SH Return value + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Complexity + + 1-3) Same as for emplace. + 4-6) Same as for emplace_hint. + +.SH Notes + + Unlike insert or emplace, these functions do not move from rvalue arguments if the + insertion does not happen, which makes it easy to manipulate maps whose values are + move-only types, such as std::unordered_map>. In + addition, try_emplace treats the key and the arguments to the mapped_type + separately, unlike emplace, which requires the arguments to construct a value_type + (that is, a std::pair). + + Overloads (3,6) can be called without constructing an object of type Key. + + Feature-test macro Value Std Feature +__cpp_lib_unordered_map_try_emplace 201411L \fI(C++17)\fP std::unordered_map::try_emplace, + std::unordered_map::insert_or_assign + Heterogeneous overloads for the +__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) remaining member functions in + ordered and unordered associative + containers. Overloads \fB(3)\fP and \fB(6)\fP. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print_node(const auto& node) + { + std::cout << '[' << node.first << "] = " << node.second << '\\n'; + } + + void print_result(auto const& pair) + { + std::cout << (pair.second ? "inserted: " : "ignored: "); + print_node(*pair.first); + } + + int main() + { + using namespace std::literals; + std::unordered_map m; + + print_result(m.try_emplace("a", "a"s)); + print_result(m.try_emplace("b", "abcd")); + print_result(m.try_emplace("c", 10, 'c')); + print_result(m.try_emplace("c", "Won't be inserted")); + + for (const auto& p : m) + print_node(p); + } + +.SH Possible output: + + inserted: [a] = a + inserted: [b] = abcd + inserted: [c] = cccccccccc + ignored: [c] = cccccccccc + [a] = a + [b] = abcd + [c] = cccccccccc + +.SH See also + + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::unordered_map.3 b/man/std::unordered_map::unordered_map.3 index f8cde6f6a..61a209fca 100644 --- a/man/std::unordered_map::unordered_map.3 +++ b/man/std::unordered_map::unordered_map.3 @@ -1,89 +1,148 @@ -.TH std::unordered_map::unordered_map 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::unordered_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::unordered_map \- std::unordered_map::unordered_map + .SH Synopsis - explicit unordered_map( size_type bucket_count = - /*implementation-defined*/, + unordered_map() \fI(since C++11)\fP + : unordered_map(size_type(/* implementation-defined */)) \fI(until C++20)\fP + {} + unordered_map(); \fI(since C++20)\fP + explicit unordered_map( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++11)\fP - const KeyEqual& equal = KeyEqual(), \fI(until C++14)\fP + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), \fB(2)\fP \fI(since C++11)\fP const Allocator& alloc = Allocator() ); - unordered_map : unordered_map( - size_type(/*implementation-defined*/) {} + unordered_map( size_type bucket_count, - explicit unordered_map( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++14)\fP - const KeyEqual& equal = KeyEqual(), + const Allocator& alloc ) \fB(3)\fP \fI(since C++14)\fP - const Allocator& alloc = Allocator() - ); + : unordered_map(bucket_count, Hash(), key_equal(), alloc) + {} unordered_map( size_type bucket_count, - const Allocator& alloc = Allocator() - ); - unordered_map( size_type bucket_count, \fB(1)\fP \fI(since C++14)\fP - const Hash& hash, + const Hash& hash, + const Allocator& alloc ) \fB(4)\fP \fI(since C++14)\fP - const Allocator& alloc = Allocator() - ); - explicit unordered_map( const Allocator& alloc ); \fB(1)\fP \fI(since C++11)\fP + : unordered_map(bucket_count, hash, key_equal(), alloc) + {} + explicit unordered_map( const Allocator& alloc ); \fB(5)\fP \fI(since C++11)\fP template< class InputIt > unordered_map( InputIt first, InputIt last, - size_type bucket_count = - /*implementation-defined*/, - const Hash& hash = Hash(), \fB(1)\fP - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - template< class InputIt > \fB(2)\fP - unordered_map( InputIt first, InputIt last, \fI(since C++14)\fP - size_type bucket_count, + size_type bucket_count = /* + implementation-defined */, \fB(6)\fP \fI(since C++11)\fP + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); template< class InputIt > + unordered_map( InputIt first, InputIt last, size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(7)\fP \fI(since C++14)\fP + : unordered_map(first, last, - const Allocator& alloc = Allocator() ); - unordered_map( const unordered_map& other ); \fB(3)\fP \fI(since C++11)\fP - unordered_map( const unordered_map& other, const Allocator& \fB(3)\fP \fI(since C++11)\fP + bucket_count, Hash(), key_equal(), alloc) + {} + template< class InputIt > + + unordered_map( InputIt first, InputIt last, + size_type bucket_count, + const Hash& hash, \fB(8)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_map(first, last, + + bucket_count, hash, key_equal(), alloc) + {} + unordered_map( const unordered_map& other ); \fB(9)\fP \fI(since C++11)\fP + unordered_map( const unordered_map& other, const Allocator& \fB(1)\fP \fB(10)\fP \fI(since C++11)\fP alloc ); - unordered_map( unordered_map&& other ); \fB(4)\fP \fI(since C++11)\fP - unordered_map( unordered_map&& other, const Allocator& alloc \fB(4)\fP \fI(since C++11)\fP + unordered_map( unordered_map&& other ); \fB(11)\fP \fI(since C++11)\fP + unordered_map( unordered_map&& other, const Allocator& alloc \fB(12)\fP \fI(since C++11)\fP ); unordered_map( std::initializer_list init, - size_type bucket_count = - /*implementation-defined*/, + size_type bucket_count = /* + implementation-defined */, \fB(13)\fP \fI(since C++11)\fP const Hash& hash = Hash(), - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - unordered_map( std::initializer_list init, \fB(5)\fP - size_type bucket_count, \fI(since C++14)\fP + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); unordered_map( std::initializer_list init, + size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(14)\fP \fI(since C++14)\fP + : unordered_map(init, bucket_count, + + Hash(), key_equal(), alloc) {} + unordered_map( std::initializer_list init, + + size_type bucket_count, + const Hash& hash, \fB(15)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_map(init, bucket_count, + + hash, key_equal(), alloc) {} + template< container-compatible-range R > + + unordered_map( std::from_range_t, R&& rg, + size_type bucket_count = /* see description + */, \fB(16)\fP (since C++23) + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), const Allocator& alloc = Allocator() ); + template< container-compatible-range R > + + unordered_map( std::from_range_t, R&& rg, + size_type bucket_count, + const Allocator& alloc ) \fB(17)\fP (since C++23) + : unordered_map(std::from_range, std::forward(rg), + + bucket_count, Hash(), key_equal(), alloc) + {} + template< container-compatible-range R > + + unordered_map( std::from_range_t, R&& rg, + size_type bucket_count, + const Hash& hash, \fB(18)\fP (since C++23) + const Alloc& alloc ) + : unordered_map(std::from_range, std::forward(rg), + + bucket_count, hash, key_equal(), alloc) + {} Constructs new container from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator. - 1) Constructs empty container. Sets max_load_factor() to 1.0. For the default + 1-5) Constructs empty container. Sets max_load_factor() to 1.0. For the default constructor, the number of buckets is implementation-defined. - 2) constructs the container with the contents of the range [first, last). Sets - max_load_factor() to 1.0. - 3) copy constructor. Constructs the container with the copy of the contents of + 6-8) Constructs the container with the contents of the range [first, last). Sets + max_load_factor() to 1.0. If multiple elements in the range have keys that compare + equivalent, it is unspecified which element is inserted (pending LWG2844). + 9,10) Copy constructor. Constructs the container with the copy of the contents of other, copies the load factor, the predicate, and the hash function as well. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). - 4) move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 5) constructs the container with the contents of the initializer list init, same as - unordered_map(init.begin(), init.end()). + std::allocator_traits::select_on_container_copy_construction(other.get_allocator()). + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 11,12) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 13-15) Initializer-list constructor. Constructs the container with the contents of + the initializer list init, same as unordered_map(init.begin(), init.end()). + 16-18) Constructs the container with the contents of rg. If multiple elements in the + range have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). .SH Parameters @@ -92,84 +151,151 @@ specified, implementation-defined default value is used hash - hash function to use equal - comparison function to use for all key comparisons of this container - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1) constant - 2) average case linear worst case quadratic in distance between first and last - 3) linear in size of other - 4) constant. If alloc is given and alloc != other.get_allocator(), then linear. - 5) average case linear worst case quadratic in size of init + 1-5) Constant. + 6-8) Average case linear (i.e. O(N), where N is std::distance(first, last)), worst + case quadratic, i.e. O(N^2). + 9,10) Linear in size of other. + 11,12) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 13-15) Average case O(N) (N is std::size(init)), worst case O(N^2). + 16-18) Average case O(N) (N is ranges::distance(rg)), worst case O(N^2). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + + After container move construction (overload \fB(4)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Although not formally required until C++23, some implementations have already put + the template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (16-18) .SH Example - + // Run this code - #include - #include #include #include + #include #include - - struct Key { + #include + + struct Key + { std::string first; std::string second; }; - - struct KeyHash { - std::size_t operator()(const Key& k) const - { - return std::hash()(k.first) ^ + + struct KeyHash + { + std::size_t operator()(const Key& k) const + { + return std::hash()(k.first) ^ (std::hash()(k.second) << 1); - } + } }; - - struct KeyEqual { - bool operator()(const Key& lhs, const Key& rhs) const - { - return lhs.first == rhs.first && lhs.second == rhs.second; - } + + struct KeyEqual + { + bool operator()(const Key& lhs, const Key& rhs) const + { + return lhs.first == rhs.first && lhs.second == rhs.second; + } }; - + + struct Foo + { + Foo(int val_) : val(val_) {} + int val; + bool operator==(const Foo &rhs) const { return val == rhs.val; } + }; + + template<> struct std::hash + { + std::size_t operator()(const Foo &f) const + { + return std::hash{}(f.val); + } + }; + int main() { // default constructor: empty map std::unordered_map m1; - + // list constructor std::unordered_map m2 = { {1, "foo"}, {3, "bar"}, - {2, "baz"}, + {2, "baz"} }; - + // copy constructor std::unordered_map m3 = m2; - + // move constructor std::unordered_map m4 = std::move(m2); - + // range constructor - std::vector, int>> v = { {0x12, 1}, {0x01,-1} }; + std::vector, int>> v = {{0x12, 1}, {0x01,-1}}; std::unordered_map, double> m5(v.begin(), v.end()); - - // constructor for a custom type - std::unordered_map m6 = { - { {"John", "Doe"}, "example"}, - { {"Mary", "Sue"}, "another"} + + // Option 1 for a constructor with a custom Key type + // Define the KeyHash and KeyEqual structs and use them in the template + std::unordered_map m6 = + { + {{"John", "Doe"}, "example"}, + {{"Mary", "Sue"}, "another"} + }; + + // Option 2 for a constructor with a custom Key type. + // Define a const == operator for the class/struct and specialize std::hash + // structure in the std namespace + std::unordered_map m7 = + { + {Foo(1), "One"}, {2, "Two"}, {3, "Three"} }; + + // Option 3: Use lambdas + // Note that the initial bucket count has to be passed to the constructor + struct Goo { int val; }; + auto hash = [](const Goo &g){ return std::hash{}(g.val); }; + auto comp = [](const Goo &l, const Goo &r){ return l.val == r.val; }; + std::unordered_map m8(10, hash, comp); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2193 C++11 the default constructor (1) was explicit made non-explicit + .SH See also operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_map::~unordered_map.3 b/man/std::unordered_map::~unordered_map.3 index a9467705d..a9fd763d9 100644 --- a/man/std::unordered_map::~unordered_map.3 +++ b/man/std::unordered_map::~unordered_map.3 @@ -1,11 +1,14 @@ -.TH std::unordered_map::~unordered_map 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_map::~unordered_map 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_map::~unordered_map \- std::unordered_map::~unordered_map + .SH Synopsis ~unordered_map(); \fI(since C++11)\fP - Destructs the container. The destructors of the elements are called and the used + Destructs the unordered_map. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the unordered_map. diff --git a/man/std::unordered_multimap.3 b/man/std::unordered_multimap.3 index c783db0e9..97d6ed686 100644 --- a/man/std::unordered_multimap.3 +++ b/man/std::unordered_multimap.3 @@ -1,131 +1,205 @@ -.TH std::unordered_multimap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap \- std::unordered_multimap + .SH Synopsis Defined in header template< class Key, class T, - class Hash = std::hash, \fI(since C++11)\fP + class Hash = std::hash, \fB(1)\fP \fI(since C++11)\fP class KeyEqual = std::equal_to, - class Allocator = std::allocator< std::pair > + class Allocator = std::allocator> > class unordered_multimap; + namespace pmr { + + template< + class Key, + class T, + class Hash = std::hash, + class Pred = std::equal_to \fB(2)\fP \fI(since C++17)\fP + > using unordered_multimap = + std::unordered_multimap>>; - Unordered multimap is an unordered associative container that supports equivalent - keys (an unordered_multimap may contain multiple copies of each key value) and that - associates values of another type with the keys. The unordered_multimap class - supports forward iterators. Search, insertion, and removal have average - constant-time complexity. + } + + std::unordered_multimap is an unordered associative container that supports + equivalent keys (an unordered_multimap may contain multiple copies of each key + value) and that associates values of another type with the keys. The + unordered_multimap class supports forward iterators. Search, insertion, and removal + have average constant-time complexity. Internally, the elements are not sorted in any particular order, but organized into buckets. Which bucket an element is placed into depends entirely on the hash of its - key. This allows fast access to individual elements, since once hash is computed, it - refers to the exact bucket the element is placed into. + key. This allows fast access to individual elements, since once the hash is + computed, it refers to the exact bucket the element is placed into. + + The iteration order of this container is not required to be stable (so, for example, + std::equal cannot be used to compare two std::unordered_multimaps), except that + every group of elements whose keys compare equivalent (compare equal with key_eq() + as the comparator) forms a contiguous subrange in the iteration order, also + accessible with equal_range(). std::unordered_multimap meets the requirements of Container, AllocatorAwareContainer, UnorderedAssociativeContainer. +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - mapped_type T - value_type std::pair - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - hasher Hash - key_equal KeyEqual - allocator_type Allocator - reference value_type& - const_reference const value_type& - pointer std::allocator_traits::pointer - const_pointer std::allocator_traits::const_pointer - iterator ForwardIterator - const_iterator Constant forward iterator - An iterator type whose category, value, difference, pointer and - local_iterator reference types are the same as iterator. This iterator - can be used to iterate through a single bucket but not across - buckets - An iterator type whose category, value, difference, pointer and - const_local_iterator reference types are the same as const_iterator. This iterator - can be used to iterate through a single bucket but not across - buckets + Member type Definition + key_type Key + mapped_type T + value_type std::pair + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + hasher Hash + key_equal KeyEqual + allocator_type Allocator + reference value_type& + const_reference const value_type& + pointer std::allocator_traits::pointer + const_pointer std::allocator_traits::const_pointer + iterator LegacyForwardIterator to value_type + const_iterator LegacyForwardIterator to const value_type + An iterator type whose category, value, difference, pointer + and + local_iterator reference types are the same as iterator. This iterator + can be used to iterate through a single bucket but not + across buckets + An iterator type whose category, value, difference, pointer + and + const_local_iterator reference types are the same as const_iterator. This + iterator + can be used to iterate through a single bucket but not + across buckets + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node .SH Member functions - constructor constructs the unordered_multimap - \fI(public member function)\fP - destructor destructs the unordered_multimap - \fI(public member function)\fP - operator= assigns values to the container - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs the unordered_multimap + \fI(public member function)\fP + destructor destructs the unordered_multimap + \fI(public member function)\fP + operator= assigns values to the container + \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP .SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - size returns the number of elements - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP + empty checks whether the container is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP .SH Modifiers - clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - emplace constructs element in-place - \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - erase erases elements - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup - count returns the number of elements matching specific key - \fI(public member function)\fP - find finds element with specific key - \fI(public member function)\fP - equal_range returns range of elements matching a specific key - \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP .SH Bucket interface - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP - bucket_count returns the number of buckets - \fI(public member function)\fP - max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP - bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP - bucket returns the bucket for specific key - \fI(public member function)\fP + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP + bucket_count returns the number of buckets + \fI(public member function)\fP + max_bucket_count returns the maximum number of buckets + \fI(public member function)\fP + bucket_size returns the number of elements in specific bucket + \fI(public member function)\fP + bucket returns the bucket for specific key + \fI(public member function)\fP .SH Hash policy - load_factor returns average number of elements per bucket - \fI(public member function)\fP - max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + load_factor returns average number of elements per bucket + \fI(public member function)\fP + max_load_factor manages maximum average number of elements per bucket + \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates + rehash the hash table + \fI(public member function)\fP + reserves space for at least the specified number of elements and + reserve regenerates the hash table + \fI(public member function)\fP .SH Observers - hash_function returns function used to hash the keys - \fI(public member function)\fP - key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + hash_function returns function used to hash the keys + \fI(public member function)\fP + key_eq returns the function used to compare keys for equality + \fI(public member function)\fP .SH Non-member functions - operator== compares the values in the unordered_multimap - operator!= \fI(function template)\fP + operator== + operator!= compares the values in the unordered_multimap + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) std::swap(std::unordered_multimap) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + erase_if(std::unordered_multimap) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the definitions of reference, + LWG 2050 C++11 const_reference, pointer based on value_type and + and const_pointer were based on std::allocator_traits + allocator_type + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::unordered_multimap::begin(int),std::unordered_multimap::cbegin(int).3 b/man/std::unordered_multimap::begin(int),std::unordered_multimap::cbegin(int).3 deleted file mode 100644 index 52a6aea6e..000000000 --- a/man/std::unordered_multimap::begin(int),std::unordered_multimap::cbegin(int).3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::unordered_multimap::begin(int),std::unordered_multimap::cbegin(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator begin( size_type n ); \fI(since C++11)\fP - const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the first element of the bucket with index pos. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - Iterator to the first element. - -.SH Complexity - - Constant. - -.SH See also - - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP diff --git a/man/std::unordered_multimap::begin(size_type),.3 b/man/std::unordered_multimap::begin(size_type),.3 new file mode 100644 index 000000000..46ac4737f --- /dev/null +++ b/man/std::unordered_multimap::begin(size_type),.3 @@ -0,0 +1,28 @@ +.TH std::unordered_multimap::begin(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::begin(size_type), \- std::unordered_multimap::begin(size_type), + +.SH Synopsis + + local_iterator begin( size_type n ); \fI(since C++11)\fP + const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the first element of the bucket with index n. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH See also + + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_multimap::begin,.3 b/man/std::unordered_multimap::begin,.3 new file mode 100644 index 000000000..c199d5d6c --- /dev/null +++ b/man/std::unordered_multimap::begin,.3 @@ -0,0 +1,92 @@ +.TH std::unordered_multimap::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::begin, \- std::unordered_multimap::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator begin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the first element of the unordered_multimap. + + If the unordered_multimap is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto show_node = [](const std::pair& node) + { + std::cout << node.first << " : " << node.second << '\\n'; + }; + + std::unordered_multimap lemmas; + assert(lemmas.begin() == lemmas.end()); + assert(lemmas.cbegin() == lemmas.cend()); + + lemmas.insert({ "1. ∀x ∈ N ∃y ∈ N", "x ≤ y" }); + show_node(*lemmas.cbegin()); + assert(lemmas.begin() != lemmas.end()); + assert(lemmas.cbegin() != lemmas.cend()); + + lemmas.begin()->second = "x < y"; + show_node(*lemmas.cbegin()); + + lemmas.insert({ "2. ∀x, y ∈ N ", "x = y V x ≠ y" }); + show_node(*lemmas.cbegin()); + + lemmas.insert({ "3. ∀x ∈ N ∃y ∈ N", "y = x + 1" }); + show_node(*lemmas.cbegin()); + + std::cout << "Lemmas: \\n"; + std::for_each(lemmas.cbegin(), lemmas.cend(), [&](const auto& n) + { + show_node(n); + }); + std::cout << '\\n'; + } + +.SH Possible output: + + 1. ∀x ∈ N ∃y ∈ N : x ≤ y + 1. ∀x ∈ N ∃y ∈ N : x < y + 2. ∀x, y ∈ N : x = y V x ≠ y + 3. ∀x ∈ N ∃y ∈ N : y = x + 1 + Lemmas: + 3. ∀x ∈ N ∃y ∈ N : y = x + 1 + 1. ∀x ∈ N ∃y ∈ N : x < y + 2. ∀x, y ∈ N : x = y V x ≠ y + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_multimap::begin,std::unordered_multimap::cbegin.3 b/man/std::unordered_multimap::begin,std::unordered_multimap::cbegin.3 deleted file mode 100644 index 4607536e5..000000000 --- a/man/std::unordered_multimap::begin,std::unordered_multimap::cbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::unordered_multimap::begin,std::unordered_multimap::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP - - Returns an iterator to the first element of the container. - - If the container is empty, the returned iterator will be equal to end(). - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP diff --git a/man/std::unordered_multimap::bucket.3 b/man/std::unordered_multimap::bucket.3 index 9ff0a4ff4..93746a307 100644 --- a/man/std::unordered_multimap::bucket.3 +++ b/man/std::unordered_multimap::bucket.3 @@ -1,26 +1,61 @@ -.TH std::unordered_multimap::bucket 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type bucket( const Key& key ) const; \fI(since C++11)\fP +.TH std::unordered_multimap::bucket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::bucket \- std::unordered_multimap::bucket - Returns the index of the bucket for key key. Elements (if any) with keys equivalent - to key are always found in this bucket. The returned value is valid only for - instances of the container for which bucket_count() returns the same value. +.SH Synopsis + size_type bucket( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< typename K > \fB(2)\fP (since C++26) + size_type bucket( const K& x ) const; + + 1) Returns the index of the bucket for key key. Elements (if any) with keys + equivalent to key are always found in this bucket. + 2) Returns the index of the bucket for key that compares equivalent to the value x. + Elements (if any) with keys that compare equivalent to x are always found in this + bucket. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. + + The returned value is valid only for instances of the container for which + bucket_count() returns the same value (e.g., rehash() invalidates previously + obtained value). The behavior is undefined if bucket_count() is zero. .SH Parameters key - the value of the key to examine + x - a value of any type that can be transparently compared with a key .SH Return value - Bucket index for the key key. + Bucket index for the requested key. .SH Complexity Constant. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example + .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_multimap::bucket_count.3 b/man/std::unordered_multimap::bucket_count.3 index 3ee55b43a..fc966d886 100644 --- a/man/std::unordered_multimap::bucket_count.3 +++ b/man/std::unordered_multimap::bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multimap::bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::bucket_count \- std::unordered_multimap::bucket_count + .SH Synopsis size_type bucket_count() const; \fI(since C++11)\fP @@ -19,6 +22,6 @@ .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::bucket_size.3 b/man/std::unordered_multimap::bucket_size.3 index 9d2bf32a1..1cb844876 100644 --- a/man/std::unordered_multimap::bucket_size.3 +++ b/man/std::unordered_multimap::bucket_size.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multimap::bucket_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::bucket_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::bucket_size \- std::unordered_multimap::bucket_size + .SH Synopsis size_type bucket_size( size_type n ) const; \fI(since C++11)\fP @@ -14,9 +17,9 @@ .SH Complexity - Constant. + Linear in the size of the bucket n. .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::clear.3 b/man/std::unordered_multimap::clear.3 index 5a5781d8c..77b20c204 100644 --- a/man/std::unordered_multimap::clear.3 +++ b/man/std::unordered_multimap::clear.3 @@ -1,11 +1,14 @@ -.TH std::unordered_multimap::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::clear \- std::unordered_multimap::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + May also invalidate past-the-end iterators. .SH Parameters @@ -15,17 +18,55 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::unordered_multimap& v) + { + std::cout << rem << "{ "; + for (const auto& [key, value] : v) + std::cout << '[' << key << "]:" << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::unordered_multimap container{{1, 'x'}, {2, 'y'}, {3, 'z'}}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Possible output: + + Before clear: { [1]:x [2]:y [3]:z } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + for unordered associative + LWG 2550 C++11 containers, unclear if complexity clarified that it's linear in + is linear in the number of the number of elements + elements or buckets .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::contains.3 b/man/std::unordered_multimap::contains.3 new file mode 100644 index 000000000..7bd5e7f9d --- /dev/null +++ b/man/std::unordered_multimap::contains.3 @@ -0,0 +1,62 @@ +.TH std::unordered_multimap::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::contains \- std::unordered_multimap::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Constant on average, worst case linear in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_multimap example{{1, 'a'}, {2, 'b'}}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::count.3 b/man/std::unordered_multimap::count.3 index 6f26065d1..714f8bda0 100644 --- a/man/std::unordered_multimap::count.3 +++ b/man/std::unordered_multimap::count.3 @@ -1,25 +1,87 @@ -.TH std::unordered_multimap::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::count \- std::unordered_multimap::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + size_type count( const K& x ) const; - Returns the number of elements with key key. + 1) Returns the number of elements with key that compares equal to the specified + argument key. + 2) Returns the number of elements with key that compares equivalent to the specified + argument x. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. .SH Parameters key - key value of the elements to count + x - a value of any type that can be transparently compared with a key .SH Return value - Number of elements with key key. + 1) Number of elements with key key. + 2) Number of elements with key that compares equivalent to x. .SH Complexity linear in the number of elements with key key on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_multimap dict = { + {1, "one"}, {6, "six"}, {3, "three"} + }; + dict.insert({4, "four"}); + dict.insert({5, "five"}); + dict.insert({6, "six"}); + + std::cout << "dict: { "; + for (auto const& [key, value] : dict) + std::cout << '[' << key << "]=" << value << ' '; + std::cout << "}\\n\\n"; + + for (int i{1}; i != 8; ++i) + std::cout << "dict.count(" << i << ") = " << dict.count(i) << '\\n'; + } + +.SH Possible output: + + dict: { [5]=five [4]=four [1]=one [6]=six [6]=six [3]=three } + + dict.count\fB(1)\fP = 1 + dict.count\fB(2)\fP = 0 + dict.count\fB(3)\fP = 1 + dict.count\fB(4)\fP = 1 + dict.count\fB(5)\fP = 1 + dict.count\fB(6)\fP = 2 + dict.count\fB(7)\fP = 0 + .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::emplace.3 b/man/std::unordered_multimap::emplace.3 index c44df9c17..680271ae9 100644 --- a/man/std::unordered_multimap::emplace.3 +++ b/man/std::unordered_multimap::emplace.3 @@ -1,20 +1,24 @@ -.TH std::unordered_multimap::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::emplace \- std::unordered_multimap::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace( Args&&... args ); - Inserts a new element into the container by constructing it in-place with the given - args. + Inserts a new element into the container constructed in-place with the given args. + + The constructor of the new element (i.e. std::pair) is called with + exactly the same arguments as supplied to emplace, forwarded via + std::forward(args).... Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element (i.e. - std::pair) is called with exactly the same arguments as supplied to - emplace, forwarded via std::forward(args).... + unnecessary copy or move operations. - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -22,11 +26,12 @@ .SH Return value - Returns an iterator to the inserted element. + An iterator to the inserted element. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -34,34 +39,37 @@ .SH Example - + // Run this code #include + #include #include - #include + int main() { std::unordered_multimap m; - - // uses pair's move constructor (overload 8) + + // uses pair's move constructor m.emplace(std::make_pair(std::string("a"), std::string("a"))); - - // uses pair's converting move constructor (overload 5) + + // uses pair's converting move constructor m.emplace(std::make_pair("b", "abcd")); - - // uses pair's template constructor (overload 3) + + // uses pair's template constructor m.emplace("d", "ddd"); - - // uses pair's piecewise constructor (overload 6) + + // emplace with duplicate key + m.emplace("d", "DDD"); + + // uses pair's piecewise constructor m.emplace(std::piecewise_construct, std::forward_as_tuple("c"), std::forward_as_tuple(10, 'c')); - - for (const auto &p : m) { + + for (const auto& p : m) std::cout << p.first << " => " << p.second << '\\n'; - } } .SH Possible output: @@ -70,10 +78,16 @@ b => abcd c => cccccccccc d => ddd + d => DDD .SH See also emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts in-place if the key does not exist, does nothing if the key + try_emplace exists + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::emplace_hint.3 b/man/std::unordered_multimap::emplace_hint.3 index 95d260192..e311ea4ac 100644 --- a/man/std::unordered_multimap::emplace_hint.3 +++ b/man/std::unordered_multimap::emplace_hint.3 @@ -1,20 +1,22 @@ -.TH std::unordered_multimap::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::emplace_hint \- std::unordered_multimap::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container, using hint as a suggestion where the + element should go. The constructor of the element type (value_type, that is, std::pair) is called with exactly the same arguments as supplied to the function, forwarded with std::forward(args).... - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -23,15 +25,30 @@ .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Amortized constant on average, worst case linear in the size of the container. +.SH Example + + This section is incomplete + Reason: no example + .SH See also emplace constructs element in-place - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_multimap::empty.3 b/man/std::unordered_multimap::empty.3 index ba802f51a..f9d95cba7 100644 --- a/man/std::unordered_multimap::empty.3 +++ b/man/std::unordered_multimap::empty.3 @@ -1,6 +1,11 @@ -.TH std::unordered_multimap::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::empty \- std::unordered_multimap::empty + .SH Synopsis - bool empty() const; \fI(since C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,13 +15,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the container is empty, false otherwise. .SH Complexity @@ -24,23 +23,24 @@ .SH Example - - The following code uses empty to check if a std::unordered_multimap + + The following code uses empty to check if a std::unordered_multimap contains any elements: - + // Run this code - #include #include + #include #include - + int main() { - std::unordered_multimap numbers; + std::unordered_multimap numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.emplace(42, 13); numbers.insert(std::make_pair(13317, 123)); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; @@ -48,10 +48,12 @@ .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::unordered_multimap::end(int),std::unordered_multimap::cend(int).3 b/man/std::unordered_multimap::end(int),std::unordered_multimap::cend(int).3 deleted file mode 100644 index 15f3e7c6a..000000000 --- a/man/std::unordered_multimap::end(int),std::unordered_multimap::cend(int).3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::unordered_multimap::end(int),std::unordered_multimap::cend(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator end( size_type n ); \fI(since C++11)\fP - const_local_iterator end( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the bucket with - index n. . This element acts as a placeholder, attempting to access it results in - undefined behavior. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - iterator to the element following the last element - -.SH Complexity - - Constant - -.SH See also - - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP diff --git a/man/std::unordered_multimap::end(size_type),.3 b/man/std::unordered_multimap::end(size_type),.3 new file mode 100644 index 000000000..486edce80 --- /dev/null +++ b/man/std::unordered_multimap::end(size_type),.3 @@ -0,0 +1,30 @@ +.TH std::unordered_multimap::end(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::end(size_type), \- std::unordered_multimap::end(size_type), + +.SH Synopsis + + local_iterator end( size_type n ); \fI(since C++11)\fP + const_local_iterator end( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the bucket with + index n. This element acts as a placeholder, attempting to access it results in + undefined behavior. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH See also + + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_multimap::end,.3 b/man/std::unordered_multimap::end,.3 new file mode 100644 index 000000000..9bc3efb59 --- /dev/null +++ b/man/std::unordered_multimap::end,.3 @@ -0,0 +1,94 @@ +.TH std::unordered_multimap::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::end, \- std::unordered_multimap::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator end() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the + unordered_multimap. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + auto show_node = [](const std::pair& node) + { + std::cout << node.first << " : " << node.second << '\\n'; + }; + + std::unordered_multimap lemmas; + assert(lemmas.begin() == lemmas.end()); + assert(lemmas.cbegin() == lemmas.cend()); + + lemmas.insert({ "1. ∀x ∈ N ∃y ∈ N", "x ≤ y" }); + show_node(*lemmas.cbegin()); + assert(lemmas.begin() != lemmas.end()); + assert(lemmas.cbegin() != lemmas.cend()); + + lemmas.begin()->second = "x < y"; + show_node(*lemmas.cbegin()); + + lemmas.insert({ "2. ∀x, y ∈ N ", "x = y V x ≠ y" }); + show_node(*lemmas.cbegin()); + + lemmas.insert({ "3. ∀x ∈ N ∃y ∈ N", "y = x + 1" }); + show_node(*lemmas.cbegin()); + + std::cout << "Lemmas: \\n"; + std::for_each(lemmas.cbegin(), lemmas.cend(), [&](const auto& n) + { + show_node(n); + }); + std::cout << '\\n'; + } + +.SH Possible output: + + 1. ∀x ∈ N ∃y ∈ N : x ≤ y + 1. ∀x ∈ N ∃y ∈ N : x < y + 2. ∀x, y ∈ N : x = y V x ≠ y + 3. ∀x ∈ N ∃y ∈ N : y = x + 1 + Lemmas: + 3. ∀x ∈ N ∃y ∈ N : y = x + 1 + 1. ∀x ∈ N ∃y ∈ N : x < y + 2. ∀x, y ∈ N : x = y V x ≠ y + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_multimap::end,std::unordered_multimap::cend.3 b/man/std::unordered_multimap::end,std::unordered_multimap::cend.3 deleted file mode 100644 index dc5cad47f..000000000 --- a/man/std::unordered_multimap::end,std::unordered_multimap::cend.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::unordered_multimap::end,std::unordered_multimap::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the container. - - This element acts as a placeholder; attempting to access it results in undefined - behavior. - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the element following the last element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP diff --git a/man/std::unordered_multimap::equal_range.3 b/man/std::unordered_multimap::equal_range.3 index 2f3054bdc..9667ff8b2 100644 --- a/man/std::unordered_multimap::equal_range.3 +++ b/man/std::unordered_multimap::equal_range.3 @@ -1,16 +1,31 @@ -.TH std::unordered_multimap::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::equal_range \- std::unordered_multimap::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fI(since C++11)\fP - std::pair equal_range( const Key& key \fI(since C++11)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + std::pair equal_range( const Key& \fB(2)\fP \fI(since C++11)\fP + key ) const; + template< class K > \fB(3)\fP \fI(since C++20)\fP + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++20)\fP ) const; - Returns a range containing all elements with key key in the container. The range is - defined by two iterators, the first pointing to the first element of the wanted - range and the second pointing past the last element of the range. + 1,2) Returns a range containing all elements with key key in the container. The + range is defined by two iterators, the first pointing to the first element of the + wanted range and the second pointing past the last element of the range. + 3,4) Returns a range containing all elements in the container with key equivalent to + x. This overload participates in overload resolution only if Hash::is_transparent + and KeyEqual::is_transparent are valid and each denotes a type. This assumes that + such Hash is callable with both K and Key type, and that the KeyEqual is + transparent, which, together, allows calling this function without constructing an + instance of Key. .SH Parameters key - key value to compare the elements to + x - a value of any type that can be transparently compared with a key .SH Return value @@ -20,9 +35,45 @@ .SH Complexity - Average case constant, worst case linear in the size of the container. + Average case linear in the number of elements with the key key, worst case linear in + the size of the container. + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overloads (3,4) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_multimap map = {{1, 'a'},{1, 'b'},{1, 'd'},{2, 'b'}}; + auto range = map.equal_range(1); + for (auto it = range.first; it != range.second; ++it) + std::cout << it->first << ' ' << it->second << '\\n'; + } + +.SH Output: + + 1 a + 1 b + 1 d .SH See also - find finds element with specific key - \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::unordered_multimap::erase.3 b/man/std::unordered_multimap::erase.3 index d1032b931..4625b06c4 100644 --- a/man/std::unordered_multimap::erase.3 +++ b/man/std::unordered_multimap::erase.3 @@ -1,50 +1,120 @@ -.TH std::unordered_multimap::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator erase( const_iterator pos ); \fB(1)\fP \fI(since C++11)\fP - iterator erase( const_iterator first, const_iterator last ); \fB(2)\fP \fI(since C++11)\fP - size_type erase( const key_type& key ); \fB(3)\fP \fI(since C++11)\fP - - Removes specified elements from the container. +.TH std::unordered_multimap::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::erase \- std::unordered_multimap::erase - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. +.SH Synopsis + iterator erase( iterator pos ); \fB(1)\fP \fI(since C++11)\fP + iterator erase( const_iterator pos ); \fB(2)\fP \fI(since C++11)\fP + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP \fI(since C++11)\fP + size_type erase( const Key& key ); \fB(4)\fP \fI(since C++11)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. The order of the remaining elements + is preserved. (This makes it possible to erase individual elements while iterating + through the container.) + + 1,2) Removes the element at pos. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes all elements with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. This assumes that such Hash is + callable with both K and Key type, and that the KeyEqual is transparent, which, + together, allows calling this function without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other iterators and references are not invalidated. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. - - The order of the elements that are not erased is preserved (this makes - it possible to erase individual elements while iterating through the \fI(since C++14)\fP - container) + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed. + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Hash and KeyEqual object. .SH Complexity Given an instance c of unordered_multimap: - 1) Average case: constant, worst case: c.size() - 2) Average case: std::distance(first, last), worst case: c.size() - 3) Average case: c.count(key), worst case: c.size() + 1,2) Average case: constant, worst case: c.size(). + 3) Average case: std::distance(first, last), worst case: c.size(). + 4) Average case: c.count(key), worst case: c.size(). + 5) Average case: c.count(x), worst case: c.size(). + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_multimap c = + { + {1, "one"}, {2, "two"}, {3, "three"}, + {4, "four"}, {5, "five"}, {6, "six"} + }; + + // erase all odd numbers from c + for (auto it = c.begin(); it != c.end();) + { + if (it->first % 2 != 0) + it = c.erase(it); + else + ++it; + } + + for (auto& p : c) + std::cout << p.second << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + two four six + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2059 C++11 there was ambiguity for overload \fB(2)\fP added overload \fB(1)\fP + the order of non-equivalent elements + LWG 2356 C++11 that are required to be preserved + not erased was not guaranteed to be + preserved .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::extract.3 b/man/std::unordered_multimap::extract.3 new file mode 100644 index 000000000..17ec90778 --- /dev/null +++ b/man/std::unordered_multimap::extract.3 @@ -0,0 +1,122 @@ +.TH std::unordered_multimap::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::extract \- std::unordered_multimap::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains the first such element from the container and returns a node handle that + owns it. Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type, + and neither iterator nor const_iterator is implicitly convertible from K. This + assumes that such Hash is callable with both K and Key type, and that the KeyEqual + is transparent, which, together, allows calling this function without constructing + an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed . + + Extracting a node invalidates only the iterators to the extracted element, and + preserves the relative order of the elements that are not erased. Pointers and + references to the extracted element remain valid, but cannot be used while element + is owned by a node handle: they become usable if the element is inserted into a + container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Hash and KeyEqual object. + +.SH Complexity + + 1,2,3) Average case O(1), worst case O(size()). + +.SH Notes + + extract is the only way to change a key of a map element without reallocation: + + std::map m{{1, "mango"}, {2, "papaya"}, {3, "guava"}}; + auto nh = m.extract\fB(2)\fP; + nh.key() = 4; + m.insert(std::move(nh)); + // m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}} + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto [k, v] : data) + std::cout << ' ' << k << '(' << v << ')'; + + std::cout << '\\n'; + } + + int main() + { + std::unordered_multimap cont{{1, 'a'}, {2, 'b'}, {3, 'c'}}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.key() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Possible output: + + Start: 1(a) 2(b) 3(c) + After extract and before insert: 2(b) 3(c) + End: 2(b) 3(c) 4(a) + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::find.3 b/man/std::unordered_multimap::find.3 index 9d4448e16..9bac43761 100644 --- a/man/std::unordered_multimap::find.3 +++ b/man/std::unordered_multimap::find.3 @@ -1,53 +1,71 @@ -.TH std::unordered_multimap::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::find \- std::unordered_multimap::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP + iterator find( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP \fI(since C++20)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++20)\fP + const_iterator find( const K& x ) const; - 1,2) Finds an element with key equivalent to key. + 1,2) Finds an element with key equivalent to key. If there are several elements with + the requested key in the container, any of them may be returned. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. .SH Parameters key - key value of the element to search for + x - a value of any type that can be transparently compared with a key .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Constant on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers; overloads (3,4) + .SH Example - + // Run this code #include - #include #include - + int main() { - std::unordered_multimap map_ex; - map_ex.insert({{1,'a'},{2,'b'}}); - std::unordered_multimap::const_iterator search = map_ex.find(1); - if(search != map_ex.end()) { - std::cout << "Found " << search->first << " " << search->second << "\\n"; - } - else { - std::cout << "Not found" << std::endl; - } - return 0; + // Simple comparison demo. + std::unordered_multimap example = {{1,'a'}, {2,'b'}}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << search->first << ' ' << search->second << '\\n'; + else + std::cout << "Not found\\n"; } .SH Output: - Found 1 a + Found 2 b .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::get_allocator.3 b/man/std::unordered_multimap::get_allocator.3 index 8565d4c9c..f2a1268cb 100644 --- a/man/std::unordered_multimap::get_allocator.3 +++ b/man/std::unordered_multimap::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::unordered_multimap::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::get_allocator \- std::unordered_multimap::get_allocator + .SH Synopsis - allocator_type get_allocator() const; \fI(since C++11)\fP + allocator_type get_allocator() const noexcept; \fI(since C++11)\fP Returns the allocator associated with the container. diff --git a/man/std::unordered_multimap::hash_function.3 b/man/std::unordered_multimap::hash_function.3 index 459c5f35e..059dc52e1 100644 --- a/man/std::unordered_multimap::hash_function.3 +++ b/man/std::unordered_multimap::hash_function.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multimap::hash_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::hash_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::hash_function \- std::unordered_multimap::hash_function + .SH Synopsis hasher hash_function() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::insert.3 b/man/std::unordered_multimap::insert.3 index 1c17f0208..872a0950c 100644 --- a/man/std::unordered_multimap::insert.3 +++ b/man/std::unordered_multimap::insert.3 @@ -1,31 +1,55 @@ -.TH std::unordered_multimap::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::insert \- std::unordered_multimap::insert + .SH Synopsis - iterator insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP - template< class P > \fB(2)\fP \fI(since C++11)\fP + Defined in header + iterator insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP + iterator insert( value_type&& value ); \fB(2)\fP \fI(since C++17)\fP + template< class P > \fB(3)\fP \fI(since C++11)\fP iterator insert( P&& value ); - iterator insert( const_iterator hint, const value_type& value ); \fB(3)\fP \fI(since C++11)\fP - template< class P > \fB(4)\fP \fI(since C++11)\fP + iterator insert( const_iterator hint, const value_type& value ); \fB(4)\fP \fI(since C++11)\fP + iterator insert( const_iterator hint, value_type&& value ); \fB(5)\fP \fI(since C++17)\fP + template< class P > \fB(6)\fP \fI(since C++11)\fP iterator insert( const_iterator hint, P&& value ); - template< class InputIt > \fB(5)\fP \fI(since C++11)\fP + template< class InputIt > \fB(7)\fP \fI(since C++11)\fP void insert( InputIt first, InputIt last ); - void insert( std::initializer_list ilist ); \fB(6)\fP \fI(since C++11)\fP + void insert( std::initializer_list ilist ); \fB(8)\fP \fI(since C++11)\fP + iterator insert( node_type&& nh ); \fB(9)\fP \fI(since C++17)\fP + iterator insert( const_iterator hint, node_type&& nh ); \fB(10)\fP \fI(since C++17)\fP Inserts element(s) into the container. - 1-2) inserts value. The overload \fB(2)\fP is equivalent to - emplace(std::forward

(value)) and only participates in overload resolution if - std::is_constructible::value == true. - 3-4) inserts value, using hint as a non-binding suggestion to where the search - should start. The overload \fB(4)\fP is equivalent to emplace_hint(hint, - std::forward

(value)) and only participates in overload resolution if - std::is_constructible::value == true. - 5) inserts elements from range [first, last). - 6) inserts elements from initializer list ilist. - - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + 1-3) Inserts value. + Overload \fB(3)\fP is equivalent to emplace(std::forward

(value)) and only participates + in overload resolution if std::is_constructible::value == true. + 4-6) Inserts value, using hint as a non-binding suggestion to where the search + should start. + Overload \fB(6)\fP is equivalent to emplace_hint(hint, std::forward

(value)) and only + participates in overload resolution if std::is_constructible::value + == true. + 7) Inserts elements from range [first, last). + If [first, last) is not a valid range, or first and/or last are iterators into + *this, the behavior is undefined. + 8) Inserts elements from initializer list ilist. + 9) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container and returns an iterator pointing at the inserted element. + The behavior is undefined if nh is not empty and get_allocator() != + nh.get_allocator(). + 10) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, and returns the + iterator pointing to the element with key equivalent to nh.key(). hint is used as a + non-binding suggestion to where the search should start. The behavior is undefined + if nh is not empty and get_allocator() != nh.get_allocator(). + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters @@ -33,35 +57,57 @@ value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-4) Returns an iterator to the inserted element. - 5-6) \fI(none)\fP + 1-6) An iterator to the inserted element. + 7,8) \fI(none)\fP + 9,10) End iterator if nh was empty, iterator pointing to the inserted element + otherwise. .SH Exceptions - 1-4) If an exception is thrown by any operation, the insertion has no effect. + 1-6) If an exception is thrown for any reason, these functions have no effect + (strong exception safety guarantee). + 7,8) No exception safety guarantee. + 9,10) If an exception is thrown for any reason, these functions have no effect + (strong exception safety guarantee). + +.SH Complexity + + 1-6) Average case: O(1), worst case O(size()). + 7,8) Average case: O(N), where N is the number of elements to insert. Worst case: + O(N * size() + N). + 9,10) Average case: O(1), worst case O(size()). + +.SH Example This section is incomplete - Reason: cases 5-6 + Reason: no example -.SH Complexity + Defect reports - 1-4) Average case: O(1), worst case O(size()) - 5-6) Average case: O(N), where N is the number of elements to insert. Worse case: - O(N*size()+N) + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overloads (3,6) would only only participates if + LWG 2005 C++11 participate in overload value_type + resolution if P is implicitly is constructible from P&& + convertible to value_type .SH See also emplace constructs element in-place - \fI(public member function)\fP + \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP .SH Category: - - * Todo with reason + * Todo no example diff --git a/man/std::unordered_multimap::insert_range.3 b/man/std::unordered_multimap::insert_range.3 new file mode 100644 index 000000000..2d7cc90af --- /dev/null +++ b/man/std::unordered_multimap::insert_range.3 @@ -0,0 +1,78 @@ +.TH std::unordered_multimap::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::insert_range \- std::unordered_multimap::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements + are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into unordered_multimap from + *ranges::begin(rg). Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), where N is ranges::distance(rg), worst case O(N·(a.size() + 1)). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto, auto const& container) + { + for (const auto& [key, value] : container) + std::cout << '{' << key << ',' << value << '}' << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::unordered_multimap{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}}; + const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Possible output: + + {1,11} {-2,-22} {3,-33} {3,33} {2,22} {-1,-11} {4,44} + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::key_eq.3 b/man/std::unordered_multimap::key_eq.3 index 221ffeb22..78e681de7 100644 --- a/man/std::unordered_multimap::key_eq.3 +++ b/man/std::unordered_multimap::key_eq.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multimap::key_eq 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::key_eq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::key_eq \- std::unordered_multimap::key_eq + .SH Synopsis key_equal key_eq() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also hash_function returns function used to hash the keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::load_factor.3 b/man/std::unordered_multimap::load_factor.3 index 0f83f34a2..f39650a36 100644 --- a/man/std::unordered_multimap::load_factor.3 +++ b/man/std::unordered_multimap::load_factor.3 @@ -1,8 +1,12 @@ -.TH std::unordered_multimap::load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::load_factor \- std::unordered_multimap::load_factor + .SH Synopsis float load_factor() const; \fI(since C++11)\fP - Returns the average number of elements per bucket. + Returns the average number of elements per bucket, that is, size() divided by + bucket_count(). .SH Parameters @@ -19,4 +23,4 @@ .SH See also max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::max_bucket_count.3 b/man/std::unordered_multimap::max_bucket_count.3 index f020815d2..6d8a0c1bf 100644 --- a/man/std::unordered_multimap::max_bucket_count.3 +++ b/man/std::unordered_multimap::max_bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multimap::max_bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::max_bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::max_bucket_count \- std::unordered_multimap::max_bucket_count + .SH Synopsis size_type max_bucket_count() const; \fI(since C++11)\fP @@ -17,7 +20,41 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + struct Ha { std::size_t operator()(long x) const { return std::hash{}(x); }; }; + + auto c1 = std::unordered_multimap{}; + auto c2 = std::unordered_multimap{}; + auto c3 = std::unordered_multimap>{}; + auto c4 = std::unordered_multimap{}; + + std::cout + << "Max bucket count of\\n" << std::hex << std::showbase + << "c1: " << c1.max_bucket_count() << '\\n' + << "c2: " << c2.max_bucket_count() << '\\n' + << "c3: " << c3.max_bucket_count() << '\\n' + << "c4: " << c4.max_bucket_count() << '\\n' + ; + } + +.SH Possible output: + + Max bucket count of + c1: 0xfffffffffffffff + c2: 0xfffffffffffffff + c3: 0xfffffffffffffff + c4: 0xaaaaaaaaaaaaaaa + .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::max_load_factor.3 b/man/std::unordered_multimap::max_load_factor.3 index ac9cb84dc..984801ba5 100644 --- a/man/std::unordered_multimap::max_load_factor.3 +++ b/man/std::unordered_multimap::max_load_factor.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multimap::max_load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::max_load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::max_load_factor \- std::unordered_multimap::max_load_factor + .SH Synopsis float max_load_factor() const; \fB(1)\fP \fI(since C++11)\fP void max_load_factor( float ml ); \fB(2)\fP \fI(since C++11)\fP @@ -8,7 +11,6 @@ threshold. 1) Returns current maximum load factor. - 2) Sets the maximum load factor to ml. .SH Parameters @@ -17,15 +19,14 @@ .SH Return value - 1) current maximum load factor. - - 2) none. + 1) Current maximum load factor. + 2) \fI(none)\fP .SH Complexity - Constant + Constant. .SH See also load_factor returns average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::max_size.3 b/man/std::unordered_multimap::max_size.3 index 792456d0d..74911d367 100644 --- a/man/std::unordered_multimap::max_size.3 +++ b/man/std::unordered_multimap::max_size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_multimap::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::max_size \- std::unordered_multimap::max_size + .SH Synopsis - size_type max_size() const; \fI(since C++11)\fP + size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,24 +17,45 @@ Maximum number of elements. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_multimap p; + std::unordered_multimap q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + q.max_size() = 768,614,336,404,564,650 = 0xAAA,AAA,AAA,AAA,AAA + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::merge.3 b/man/std::unordered_multimap::merge.3 new file mode 100644 index 000000000..fd527e117 --- /dev/null +++ b/man/std::unordered_multimap::merge.3 @@ -0,0 +1,97 @@ +.TH std::unordered_multimap::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::merge \- std::unordered_multimap::merge + +.SH Synopsis + template< class H2, class P2 > + void merge( std::unordered_map& source \fB(1)\fP \fI(since C++17)\fP + ); + template< class H2, class P2 > + void merge( std::unordered_map&& source \fB(2)\fP \fI(since C++17)\fP + ); + template< class H2, class P2 > + void merge( std::unordered_multimap& \fB(3)\fP \fI(since C++17)\fP + source ); + template< class H2, class P2 > + void merge( std::unordered_multimap&& \fB(4)\fP \fI(since C++17)\fP + source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the hash function and key equality predicate of *this. + + No elements are copied or moved, only the internal pointers of the container nodes + are repointed. All pointers and references to the transferred elements remain valid, + but now refer into *this, not into source. Iterators referring to the transferred + elements and all iterators referring to *this are invalidated. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), worst case O(N * size() + N), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // print out a std::pair + template + Os& operator<<(Os& os, const std::pair& p) + { + return os << '{' << p.first << ", " << p.second << '}'; + } + + // print out an associative container + template + Os& operator<<(Os& os, const std::unordered_multimap& v) + { + os << '[' << v.size() << "] {"; + bool o{}; + for (const auto& e : v) + os << (o ? ", " : (o = 1, "")) << e; + return os << "}\\n"; + } + + int main() + { + std::unordered_multimap + p{{"C", 3}, {"B", 2}, {"A", 1}, {"A", 0}}, + q{{"E", 6}, {"E", 7}, {"D", 5}, {"A", 4}}; + + std::cout << "p: " << p << "q: " << q; + + p.merge(q); + + std::cout << "p.merge(q);\\n" << "p: " << p << "q: " << q; + } + +.SH Possible output: + + p: [4] {{A, 1}, {A, 0}, {B, 2}, {C, 3}} + q: [4] {{A, 4}, {D, 5}, {E, 6}, {E, 7}} + p.merge(q); + p: [8] {{E, 6}, {E, 7}, {C, 3}, {A, 1}, {A, 0}, {A, 4}, {D, 5}, {B, 2}} + q: [0] {} + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::operator=.3 b/man/std::unordered_multimap::operator=.3 index 52d7fb4c8..602b37469 100644 --- a/man/std::unordered_multimap::operator=.3 +++ b/man/std::unordered_multimap::operator=.3 @@ -1,28 +1,40 @@ -.TH std::unordered_multimap::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::operator= \- std::unordered_multimap::operator= + .SH Synopsis - unordered_multimap& operator=( const unordered_multimap& other ); \fB(1)\fP \fI(since C++11)\fP - unordered_multimap& operator=( unordered_multimap&& other ); \fB(2)\fP \fI(since C++11)\fP - unordered_multimap& operator=( std::initializer_list \fB(3)\fP \fI(since C++11)\fP - ilist ); + unordered_multimap& operator=( const \fB(1)\fP \fI(since C++11)\fP + unordered_multimap& other ); + unordered_multimap& operator=( unordered_multimap&& \fI(since C++11)\fP + other ); \fI(until C++17)\fP + unordered_multimap& operator=( unordered_multimap&& \fB(2)\fP \fI(since C++17)\fP + other ) noexcept(/* see below */); + unordered_multimap& operator=( \fB(3)\fP \fI(since C++11)\fP + std::initializer_list ilist ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + If + std::allocator_traits::propagate_on_container_copy_assignment::value + is true, the allocator of *this is replaced by a copy of other. If the allocator of + *this after assignment would compare unequal to its old value, the old allocator is + used to deallocate the memory, then the new allocator is used to allocate it before + copying the elements. Otherwise, the memory owned by *this may be reused when + possible. In any case, the elements originally belonging to *this may be either + destroyed or replaced by element-wise copy-assignment. 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -36,67 +48,100 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + + && std::is_nothrow_move_assignable::value + + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::unordered_multimap to another: - The following code uses to assign one std::unordered_multimap to another: - // Run this code - #include + #include #include - - void display_sizes(const std::unordered_multimap &nums1, - const std::unordered_multimap &nums2, - const std::unordered_multimap &nums3) + #include + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& [key, value] : container) + std::cout << '{' << key << ',' << value << (--size ? "}, " : "} "); + std::cout << "}\\n"; } - + int main() { - std::unordered_multimap nums1 {{3, 1}, {4, 1}, {5, 9}, - {6, 1}, {7, 1}, {8, 9}}; - std::unordered_multimap nums2; - std::unordered_multimap nums3; - + std::unordered_multimap x{{1,1}, {2,2}, {3,3}}, y, z; + const auto w = {std::pair{4,4}, {5,5}, {6,6}, {7,7}}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } -.SH Output: +.SH Possible output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { {3,3}, {2,2}, {1,1} } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { {3,3}, {2,2}, {1,1} } + y = { {3,3}, {2,2}, {1,1} } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { {3,3}, {2,2}, {1,1} } + Assignment of initializer_list w to z: + w = { {4,4}, {5,5}, {6,6}, {7,7} } + z = { {7,7}, {6,6}, {5,5}, {4,4} } .SH See also constructor constructs the unordered_multimap - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_multimap::rehash.3 b/man/std::unordered_multimap::rehash.3 index f5fd65f23..5f56f343d 100644 --- a/man/std::unordered_multimap::rehash.3 +++ b/man/std::unordered_multimap::rehash.3 @@ -1,16 +1,17 @@ -.TH std::unordered_multimap::rehash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::rehash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::rehash \- std::unordered_multimap::rehash + .SH Synopsis void rehash( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to count and rehashes the container, i.e. puts the - elements into appropriate buckets considering that total number of buckets has - changed. If the new number of buckets makes load factor more than maximum load - factor (count < size() / max_load_factor()), then the new number of buckets is at - least size() / max_load_factor(). + Changes the number of buckets to a value n that is not less than count and satisfies + n >= size() / max_load_factor(), then rehashes the container, i.e. puts the elements + into appropriate buckets considering that total number of buckets has changed. .SH Parameters - count - new number of buckets + count - lower bound for the new number of buckets .SH Return value @@ -23,10 +24,10 @@ .SH Notes rehash\fB(0)\fP may be used to force an unconditional rehash, such as after suspension of - automatic rehashing by temporary increasing max_load_factor(). + automatic rehashing by temporarily increasing max_load_factor(). .SH See also - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + reserves space for at least the specified number of elements and regenerates + reserve the hash table + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::reserve.3 b/man/std::unordered_multimap::reserve.3 index b00eb4a73..8976f4f58 100644 --- a/man/std::unordered_multimap::reserve.3 +++ b/man/std::unordered_multimap::reserve.3 @@ -1,8 +1,11 @@ -.TH std::unordered_multimap::reserve 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::reserve \- std::unordered_multimap::reserve + .SH Synopsis void reserve( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to the number needed to accomodate at least count + Sets the number of buckets to the number needed to accommodate at least count elements without exceeding maximum load factor and rehashes the container, i.e. puts the elements into appropriate buckets considering that total number of buckets has changed. Effectively calls rehash(std::ceil(count / max_load_factor())). @@ -21,6 +24,6 @@ .SH See also - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates the hash + rehash table + \fI(public member function)\fP diff --git a/man/std::unordered_multimap::size.3 b/man/std::unordered_multimap::size.3 index 00e7964e9..0e19096a2 100644 --- a/man/std::unordered_multimap::size.3 +++ b/man/std::unordered_multimap::size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_multimap::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::size \- std::unordered_multimap::size + .SH Synopsis - size_type size() const; \fI(since C++11)\fP + size_type size() const noexcept; \fI(since C++11)\fP Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,27 @@ The number of elements in the container. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::unordered_multimap: - + // Run this code - #include #include - + #include + int main() { - std::unordered_multimap nums {{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; - + std::unordered_multimap nums{{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +46,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::unordered_multimap::swap.3 b/man/std::unordered_multimap::swap.3 index 9c634dad7..bc583aa52 100644 --- a/man/std::unordered_multimap::swap.3 +++ b/man/std::unordered_multimap::swap.3 @@ -1,19 +1,24 @@ -.TH std::unordered_multimap::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::swap \- std::unordered_multimap::swap + .SH Synopsis - void swap( unordered_multimap& other ); \fI(since C++11)\fP + void swap( unordered_multimap& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + void swap( unordered_multimap& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. The Hash and KeyEqual objects must be Swappable, and they are exchanged using unqualified calls to non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +30,86 @@ .SH Exceptions - Any exception thrown by the swap Hash or KeyEqual objects. + Any exception thrown by the swap of the Hash or KeyEqual objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value + \fI(since C++17)\fP + && std::is_nothrow_swappable::value + + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // print out a std::pair + template + Os& operator<<(Os& os, const std::pair& p) + { + return os << p.first << ':' << p.second; + } + + // print out a container + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " }\\n"; + } + + int main() + { + std::unordered_multimap + m1{{"γ", "gamma"}, {"β", "beta"}, {"α", "alpha"}, {"γ", "gamma"}}, + m2{{"ε", "epsilon"}, {"δ", "delta"}, {"ε", "epsilon"}}; + + const auto& ref = *(m1.begin()); + const auto iter = std::next(m1.cbegin()); + + std::cout << "──────── before swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + m1.swap(m2); + + std::cout << "──────── after swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + // Note that every iterator referring to an element in one container before + // the swap refers to the same element in the other container after the swap. + // Same is true for references. + } + +.SH Possible output: + + ──────── before swap ──────── + m1: { α:alpha β:beta γ:gamma γ:gamma } + m2: { δ:delta ε:epsilon ε:epsilon } + ref: α:alpha + iter: β:beta + ──────── after swap ──────── + m1: { δ:delta ε:epsilon ε:epsilon } + m2: { α:alpha β:beta γ:gamma γ:gamma } + ref: α:alpha + iter: β:beta + .SH See also std::swap(std::unordered_multimap) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_multimap::unordered_multimap.3 b/man/std::unordered_multimap::unordered_multimap.3 index d161160c3..126cf0bbe 100644 --- a/man/std::unordered_multimap::unordered_multimap.3 +++ b/man/std::unordered_multimap::unordered_multimap.3 @@ -1,91 +1,148 @@ -.TH std::unordered_multimap::unordered_multimap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::unordered_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::unordered_multimap \- std::unordered_multimap::unordered_multimap + .SH Synopsis - explicit unordered_multimap( size_type bucket_count = - /*implementation-defined*/, + unordered_multimap() \fI(since C++11)\fP + : unordered_multimap(size_type(/* implementation-defined \fI(until C++20)\fP + */)) {} + unordered_multimap(); \fI(since C++20)\fP + explicit unordered_multimap( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++11)\fP - const KeyEqual& equal = \fI(until C++14)\fP - KeyEqual(), + const Hash& hash = Hash(), + const key_equal& equal = \fB(2)\fP \fI(since C++11)\fP + key_equal(), const Allocator& alloc = Allocator() ); - unordered_multimap : unordered_multimap( - size_type(/*implementation-defined*/) {} + unordered_multimap( size_type bucket_count, - explicit unordered_multimap( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++14)\fP - const KeyEqual& equal = - KeyEqual(), + const Allocator& alloc ) \fB(3)\fP \fI(since C++14)\fP - const Allocator& alloc = - Allocator() ); + : unordered_multimap(bucket_count, Hash(), key_equal(), + alloc) {} unordered_multimap( size_type bucket_count, - const Allocator& alloc = - Allocator() ); - unordered_multimap( size_type bucket_count, \fB(1)\fP \fI(since C++14)\fP - const Hash& hash, + const Hash& hash, + const Allocator& alloc ) \fB(4)\fP \fI(since C++14)\fP - const Allocator& alloc = - Allocator() ); - explicit unordered_multimap( const Allocator& alloc ); \fB(1)\fP \fI(since C++11)\fP + : unordered_multimap(bucket_count, hash, key_equal(), + alloc) {} + explicit unordered_multimap( const Allocator& alloc ); \fB(5)\fP \fI(since C++11)\fP template< class InputIt > unordered_multimap( InputIt first, InputIt last, - size_type bucket_count = - /*implementation-defined*/, \fB(1)\fP + size_type bucket_count = /* + implementation-defined */, \fB(6)\fP \fI(since C++11)\fP const Hash& hash = Hash(), - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - template< class InputIt > \fB(2)\fP - unordered_multimap( InputIt first, InputIt last, \fI(since C++14)\fP - size_type bucket_count, + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); template< class InputIt > + unordered_multimap( InputIt first, InputIt last, size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(7)\fP \fI(since C++14)\fP + : unordered_multimap(first, last, - const Allocator& alloc = Allocator() ); - unordered_multimap( const unordered_multimap& other ); \fB(3)\fP \fI(since C++11)\fP - unordered_multimap( const unordered_multimap& other, const \fB(3)\fP \fI(since C++11)\fP - Allocator& alloc ); - unordered_multimap( unordered_multimap&& other ); \fB(4)\fP \fI(since C++11)\fP - unordered_multimap( unordered_multimap&& other, const \fB(4)\fP \fI(since C++11)\fP + bucket_count, Hash(), key_equal(), + alloc) {} + template< class InputIt > + + unordered_multimap( InputIt first, InputIt last, + size_type bucket_count, + const Hash& hash, \fB(8)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_multimap(first, last, + + bucket_count, hash, key_equal(), + alloc) {} + unordered_multimap( const unordered_multimap& other ); \fB(9)\fP \fI(since C++11)\fP + unordered_multimap( const unordered_multimap& other, const \fB(10)\fP \fI(since C++11)\fP + Allocator& alloc ); \fB(1)\fP + unordered_multimap( unordered_multimap&& other ); \fB(11)\fP \fI(since C++11)\fP + unordered_multimap( unordered_multimap&& other, const \fB(12)\fP \fI(since C++11)\fP Allocator& alloc ); unordered_multimap( std::initializer_list init, - size_type bucket_count = - /*implementation-defined*/, + size_type bucket_count = /* + implementation-defined */, \fB(13)\fP \fI(since C++11)\fP const Hash& hash = Hash(), - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - unordered_multimap( std::initializer_list init, \fB(5)\fP - size_type bucket_count, \fI(since C++14)\fP + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); unordered_multimap( std::initializer_list init, + size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(14)\fP \fI(since C++14)\fP + : unordered_multimap(init, bucket_count, + + Hash(), key_equal(), alloc) {} + unordered_multimap( std::initializer_list init, + + size_type bucket_count, + const Hash& hash, \fB(15)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_multimap(init, bucket_count, + + hash, key_equal(), alloc) {} + template< container-compatible-range R > + + unordered_multimap( std::from_range_t, R&& rg, + size_type bucket_count = /* see + description */, \fB(16)\fP (since C++23) + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), const Allocator& alloc = Allocator() ); + template< container-compatible-range R > + + unordered_multimap( std::from_range_t, R&& rg, + size_type bucket_count, + const Allocator& alloc ) \fB(17)\fP (since C++23) + : unordered_multimap(std::from_range, + std::forward(rg), + + bucket_count, Hash(), key_equal(), + alloc) {} + template< container-compatible-range R > + + unordered_multimap( std::from_range_t, R&& rg, + size_type bucket_count, + const Hash& hash, + const Alloc& alloc ) \fB(18)\fP (since C++23) + : unordered_multimap(std::from_range, + std::forward(rg), + + bucket_count, hash, key_equal(), + alloc) {} Constructs new container from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator. - 1) Constructs empty container. Sets max_load_factor() to 1.0. For the default + 1-5) Constructs empty container. Sets max_load_factor() to 1.0. For the default constructor, the number of buckets is implementation-defined. - 2) constructs the container with the contents of the range [first, last). Sets + 6-8) Constructs the container with the contents of the range [first, last). Sets max_load_factor() to 1.0. - 3) copy constructor. Constructs the container with the copy of the contents of + 9,10) Copy constructor. Constructs the container with the copy of the contents of other, copies the load factor, the predicate, and the hash function as well. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). - 4) move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 5) constructs the container with the contents of the initializer list init, same as - unordered_multimap(init.begin(), init.end()). + std::allocator_traits::select_on_container_copy_construction(other.get_allocator()). + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 11,12) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 13-15) Initializer-list constructor. Constructs the container with the contents of + the initializer list init, same as unordered_multimap(init.begin(), init.end()). + 16-18) Constructs the container with the contents of rg. .SH Parameters @@ -94,32 +151,63 @@ specified, implementation-defined default value is used hash - hash function to use equal - comparison function to use for all key comparisons of this container - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1) constant - 2) average case linear worst case quadratic in distance between first and last - 3) linear in size of other - 4) constant. If alloc is given and alloc != other.get_allocator(), then linear. - 5) average case linear worst case quadratic in size of init + 1-5) Constant. + 6-8) Average case linear (i.e. O(N), where N is std::distance(first, last)), worst + case quadratic, i.e. O(N^2). + 9,10) Linear in size of other. + 11,12) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 13-15) Average case O(N) (N is std::size(init)), worst case O(N^2). + 16-18) Average case O(N) (N is ranges::distance(rg)), worst case O(N^2). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + + After container move construction (overload \fB(4)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Although not formally required until C++23, some implementations have already put + the template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (16-18) .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2193 C++11 the default constructor (1) was explicit made non-explicit + .SH See also operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unordered_multimap::~unordered_multimap.3 b/man/std::unordered_multimap::~unordered_multimap.3 index b91aabf03..28da9e1e2 100644 --- a/man/std::unordered_multimap::~unordered_multimap.3 +++ b/man/std::unordered_multimap::~unordered_multimap.3 @@ -1,11 +1,14 @@ -.TH std::unordered_multimap::~unordered_multimap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multimap::~unordered_multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multimap::~unordered_multimap \- std::unordered_multimap::~unordered_multimap + .SH Synopsis ~unordered_multimap(); \fI(since C++11)\fP - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to + Destructs the unordered_multimap. The destructors of the elements are called and the + used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the unordered_multimap. diff --git a/man/std::unordered_multiset.3 b/man/std::unordered_multiset.3 index e6c3530a2..758d0c649 100644 --- a/man/std::unordered_multiset.3 +++ b/man/std::unordered_multiset.3 @@ -1,16 +1,31 @@ -.TH std::unordered_multiset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset \- std::unordered_multiset + .SH Synopsis Defined in header template< class Key, - class Hash = std::hash, \fI(since C++11)\fP + class Hash = std::hash, \fB(1)\fP \fI(since C++11)\fP class KeyEqual = std::equal_to, class Allocator = std::allocator > class unordered_multiset; + namespace pmr { + + template< + class Key, + class Hash = std::hash, + class Pred = std::equal_to \fB(2)\fP \fI(since C++17)\fP + > using unordered_multiset = std::unordered_multiset>; + + } - Unordered multiset is an associative container that contains set of possibly + std::unordered_multiset is an associative container that contains set of possibly non-unique objects of type Key. Search, insertion, and removal have average constant-time complexity. @@ -19,115 +34,173 @@ value. This allows fast access to individual elements, since once hash is computed, it refers to the exact bucket the element is placed into. + The iteration order of this container is not required to be stable (so, for example, + std::equal cannot be used to compare two std::unordered_multisets), except that + every group of elements whose keys compare equivalent (compare equal with key_eq() + as the comparator) forms a contiguous subrange in the iteration order, also + accessible with equal_range(). + std::unordered_multiset meets the requirements of Container, AllocatorAwareContainer, UnorderedAssociativeContainer. +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - value_type Key - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - hasher Hash - key_equal KeyEqual - allocator_type Allocator - reference value_type& - const_reference const value_type& - pointer std::allocator_traits::pointer - const_pointer std::allocator_traits::const_pointer - iterator ForwardIterator - const_iterator Constant forward iterator - An iterator type whose category, value, difference, pointer and - local_iterator reference types are the same as iterator. This iterator - can be used to iterate through a single bucket but not across - buckets - An iterator type whose category, value, difference, pointer and - const_local_iterator reference types are the same as const_iterator. This iterator - can be used to iterate through a single bucket but not across - buckets + Member type Definition + key_type Key + value_type Key + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + hasher Hash + key_equal KeyEqual + allocator_type Allocator + reference value_type& + const_reference const value_type& + pointer std::allocator_traits::pointer + const_pointer std::allocator_traits::const_pointer + iterator Constant LegacyForwardIterator to value_type + const_iterator LegacyForwardIterator to const value_type + An iterator type whose category, value, difference, pointer + and + local_iterator reference types are the same as iterator. This iterator + can be used to iterate through a single bucket but not + across buckets + An iterator type whose category, value, difference, pointer + and + const_local_iterator reference types are the same as const_iterator. This + iterator + can be used to iterate through a single bucket but not + across buckets + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node .SH Member functions - constructor constructs the unordered_multiset - \fI(public member function)\fP - destructor destructs the unordered_multiset - \fI(public member function)\fP - operator= assigns values to the container - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs the unordered_multiset + \fI(public member function)\fP + destructor destructs the unordered_multiset + \fI(public member function)\fP + operator= assigns values to the container + \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP .SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - size returns the number of elements - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP + empty checks whether the container is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP .SH Modifiers - clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - emplace constructs element in-place - \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - erase erases elements - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup - count returns the number of elements matching specific key - \fI(public member function)\fP - find finds element with specific key - \fI(public member function)\fP - equal_range returns range of elements matching a specific key - \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP .SH Bucket interface - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP - bucket_count returns the number of buckets - \fI(public member function)\fP - max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP - bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP - bucket returns the bucket for specific key - \fI(public member function)\fP + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP + bucket_count returns the number of buckets + \fI(public member function)\fP + max_bucket_count returns the maximum number of buckets + \fI(public member function)\fP + bucket_size returns the number of elements in specific bucket + \fI(public member function)\fP + bucket returns the bucket for specific key + \fI(public member function)\fP .SH Hash policy - load_factor returns average number of elements per bucket - \fI(public member function)\fP - max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + load_factor returns average number of elements per bucket + \fI(public member function)\fP + max_load_factor manages maximum average number of elements per bucket + \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates + rehash the hash table + \fI(public member function)\fP + reserves space for at least the specified number of elements and + reserve regenerates the hash table + \fI(public member function)\fP .SH Observers - hash_function returns function used to hash the keys - \fI(public member function)\fP - key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + hash_function returns function used to hash the keys + \fI(public member function)\fP + key_eq returns the function used to compare keys for equality + \fI(public member function)\fP .SH Non-member functions - operator== compares the values in the unordered_multiset - operator!= \fI(function template)\fP + operator== + operator!= compares the values in the unordered_multiset + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) std::swap(std::unordered_multiset) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + erase_if(std::unordered_multiset) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP .SH Notes - The member types iterator and const_iterator may be aliases to the same type. Since - iterator is convertible to const_iterator, const_iterator should be used in function - parameter lists to avoid violations of the One Definition Rule. + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the definitions of reference, + LWG 2050 C++11 const_reference, pointer based on value_type and + and const_pointer were based on std::allocator_traits + allocator_type + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::unordered_multiset::begin(int),std::unordered_multiset::cbegin(int).3 b/man/std::unordered_multiset::begin(int),std::unordered_multiset::cbegin(int).3 deleted file mode 100644 index 6732cae53..000000000 --- a/man/std::unordered_multiset::begin(int),std::unordered_multiset::cbegin(int).3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::unordered_multiset::begin(int),std::unordered_multiset::cbegin(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator begin( size_type n ); \fI(since C++11)\fP - const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the first element of the bucket with index pos. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - Iterator to the first element. - -.SH Complexity - - Constant. - -.SH See also - - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP diff --git a/man/std::unordered_multiset::begin(size_type),.3 b/man/std::unordered_multiset::begin(size_type),.3 new file mode 100644 index 000000000..5a08669c0 --- /dev/null +++ b/man/std::unordered_multiset::begin(size_type),.3 @@ -0,0 +1,28 @@ +.TH std::unordered_multiset::begin(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::begin(size_type), \- std::unordered_multiset::begin(size_type), + +.SH Synopsis + + local_iterator begin( size_type n ); \fI(since C++11)\fP + const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the first element of the bucket with index n. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH See also + + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_multiset::begin,.3 b/man/std::unordered_multiset::begin,.3 new file mode 100644 index 000000000..342797bfb --- /dev/null +++ b/man/std::unordered_multiset::begin,.3 @@ -0,0 +1,76 @@ +.TH std::unordered_multiset::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::begin, \- std::unordered_multiset::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator begin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the first element of the unordered_multiset. + + If the unordered_multiset is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::unordered_multiset words = + { + "some", "words", "to", "count", + "count", "these", "words" + }; + + for (auto it = words.begin(); it != words.end(); ) + { + auto count = words.count(*it); + std::cout << *it << ":\\t" << count << '\\n'; + std::advance(it, count); // all count elements have equivalent keys + } + } + +.SH Possible output: + + some: 1 + words: 2 + to: 1 + count: 2 + these: 1 + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_multiset::begin,std::unordered_multiset::cbegin.3 b/man/std::unordered_multiset::begin,std::unordered_multiset::cbegin.3 deleted file mode 100644 index 4008b1f49..000000000 --- a/man/std::unordered_multiset::begin,std::unordered_multiset::cbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::unordered_multiset::begin,std::unordered_multiset::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP - - Returns an iterator to the first element of the container. - - If the container is empty, the returned iterator will be equal to end(). - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP diff --git a/man/std::unordered_multiset::bucket.3 b/man/std::unordered_multiset::bucket.3 index 7afee0765..a66145864 100644 --- a/man/std::unordered_multiset::bucket.3 +++ b/man/std::unordered_multiset::bucket.3 @@ -1,26 +1,61 @@ -.TH std::unordered_multiset::bucket 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type bucket( const Key& key ) const; \fI(since C++11)\fP +.TH std::unordered_multiset::bucket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::bucket \- std::unordered_multiset::bucket - Returns the index of the bucket for key key. Elements (if any) with keys equivalent - to key are always found in this bucket. The returned value is valid only for - instances of the container for which bucket_count() returns the same value. +.SH Synopsis + size_type bucket( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< typename K > \fB(2)\fP (since C++26) + size_type bucket( const K& x ) const; + + 1) Returns the index of the bucket for key key. Elements (if any) with keys + equivalent to key are always found in this bucket. + 2) Returns the index of the bucket for key that compares equivalent to the value x. + Elements (if any) with keys that compare equivalent to x are always found in this + bucket. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. + + The returned value is valid only for instances of the container for which + bucket_count() returns the same value (e.g., rehash() invalidates previously + obtained value). The behavior is undefined if bucket_count() is zero. .SH Parameters key - the value of the key to examine + x - a value of any type that can be transparently compared with a key .SH Return value - Bucket index for the key key. + Bucket index for the requested key. .SH Complexity Constant. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example + .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_multiset::bucket_count.3 b/man/std::unordered_multiset::bucket_count.3 index 9f2908bcd..0038da741 100644 --- a/man/std::unordered_multiset::bucket_count.3 +++ b/man/std::unordered_multiset::bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::bucket_count \- std::unordered_multiset::bucket_count + .SH Synopsis size_type bucket_count() const; \fI(since C++11)\fP @@ -19,6 +22,6 @@ .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::bucket_size.3 b/man/std::unordered_multiset::bucket_size.3 index b38182b61..478f52c47 100644 --- a/man/std::unordered_multiset::bucket_size.3 +++ b/man/std::unordered_multiset::bucket_size.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::bucket_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::bucket_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::bucket_size \- std::unordered_multiset::bucket_size + .SH Synopsis size_type bucket_size( size_type n ) const; \fI(since C++11)\fP @@ -14,9 +17,9 @@ .SH Complexity - Constant. + Linear in the size of the bucket n. .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::clear.3 b/man/std::unordered_multiset::clear.3 index a2e690bce..5d15a2930 100644 --- a/man/std::unordered_multiset::clear.3 +++ b/man/std::unordered_multiset::clear.3 @@ -1,11 +1,14 @@ -.TH std::unordered_multiset::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::clear \- std::unordered_multiset::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + May also invalidate past-the-end iterators. .SH Parameters @@ -15,17 +18,55 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::unordered_multiset& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::unordered_multiset container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Possible output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + for unordered associative + LWG 2550 C++11 containers, unclear if complexity clarified that it's linear in + is linear in the number of the number of elements + elements or buckets .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::contains.3 b/man/std::unordered_multiset::contains.3 new file mode 100644 index 000000000..3cbb38870 --- /dev/null +++ b/man/std::unordered_multiset::contains.3 @@ -0,0 +1,62 @@ +.TH std::unordered_multiset::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::contains \- std::unordered_multiset::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Constant on average, worst case linear in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_multiset example{1, 2, 3, 4}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::count.3 b/man/std::unordered_multiset::count.3 index 4ec2ed1c1..d71f0daf6 100644 --- a/man/std::unordered_multiset::count.3 +++ b/man/std::unordered_multiset::count.3 @@ -1,25 +1,81 @@ -.TH std::unordered_multiset::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::count \- std::unordered_multiset::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + size_type count( const K& x ) const; - Returns the number of elements with key key. + 1) Returns the number of elements with key that compares equal to the specified + argument key. + 2) Returns the number of elements with key that compares equivalent to the specified + argument x. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. .SH Parameters key - key value of the elements to count + x - a value of any type that can be transparently compared with a key .SH Return value - Number of elements with key key. + 1) Number of elements with key key. + 2) Number of elements with key that compares equivalent to x. .SH Complexity linear in the number of elements with key key on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_multiset set{2, 7, 1, 8, 2, 8, 1, 8, 2, 8}; + + std::cout << "The set is:\\n"; + for (int e : set) + std::cout << e << ' '; + + const auto [min, max] = std::ranges::minmax(set); + + std::cout << "\\nNumbers [" << min << ".." << max << "] frequency:\\n"; + + for (int i{min}; i <= max; ++i) + std::cout << i << ':' << set.count(i) << "; "; + std::cout << '\\n'; + } + +.SH Possible output: + + The set is: + 8 8 8 8 1 1 7 2 2 2 + Numbers [1..8] frequency: + 1:2; 2:3; 3:0; 4:0; 5:0; 6:0; 7:1; 8:4; + .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::emplace.3 b/man/std::unordered_multiset::emplace.3 index 8321218ca..a00f5077b 100644 --- a/man/std::unordered_multiset::emplace.3 +++ b/man/std::unordered_multiset::emplace.3 @@ -1,20 +1,23 @@ -.TH std::unordered_multiset::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::emplace \- std::unordered_multiset::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace( Args&&... args ); - Inserts a new element into the container by constructing it in-place with the given - args. + Inserts a new element into the container constructed in-place with the given args. + + The constructor of the new element is called with exactly the same arguments as + supplied to emplace, forwarded via std::forward(args).... Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element is called - with exactly the same arguments as supplied to emplace, forwarded via - std::forward(args).... + unnecessary copy or move operations. - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -22,11 +25,12 @@ .SH Return value - Returns an iterator to the inserted element. + An iterator to the inserted element. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -40,10 +44,11 @@ .SH See also emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unordered_multiset::emplace_hint.3 b/man/std::unordered_multiset::emplace_hint.3 index b61235005..fbd9e218c 100644 --- a/man/std::unordered_multiset::emplace_hint.3 +++ b/man/std::unordered_multiset::emplace_hint.3 @@ -1,19 +1,21 @@ -.TH std::unordered_multiset::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::emplace_hint \- std::unordered_multiset::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container, using hint as a suggestion where the + element should go. - The constructor of the element is called with exactly the same arguments as supplied - to the function, forwarded with std::forward(args).... + The constructors of the key and mapped value are called with exactly the same + arguments as supplied to the function, forwarded with std::forward(args).... - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -22,15 +24,30 @@ .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Amortized constant on average, worst case linear in the size of the container. +.SH Example + + This section is incomplete + Reason: no example + .SH See also emplace constructs element in-place - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_multiset::empty.3 b/man/std::unordered_multiset::empty.3 index abc0ccb9d..3946c0eb3 100644 --- a/man/std::unordered_multiset::empty.3 +++ b/man/std::unordered_multiset::empty.3 @@ -1,6 +1,11 @@ -.TH std::unordered_multiset::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::empty \- std::unordered_multiset::empty + .SH Synopsis - bool empty() const; \fI(since C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,13 +15,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the container is empty, false otherwise. .SH Complexity @@ -24,33 +23,36 @@ .SH Example - + The following code uses empty to check if a std::unordered_multiset contains any elements: - + // Run this code - #include #include - + #include + int main() { std::unordered_multiset numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.insert(42); - numbers.insert(13317); + numbers.insert(19937); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; } .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::unordered_multiset::end(int),std::unordered_multiset::cend(int).3 b/man/std::unordered_multiset::end(int),std::unordered_multiset::cend(int).3 deleted file mode 100644 index e3dcb3f5e..000000000 --- a/man/std::unordered_multiset::end(int),std::unordered_multiset::cend(int).3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::unordered_multiset::end(int),std::unordered_multiset::cend(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator end( size_type n ); \fI(since C++11)\fP - const_local_iterator end( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the bucket with - index n. . This element acts as a placeholder, attempting to access it results in - undefined behavior. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - iterator to the element following the last element - -.SH Complexity - - Constant - -.SH See also - - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP diff --git a/man/std::unordered_multiset::end(size_type),.3 b/man/std::unordered_multiset::end(size_type),.3 new file mode 100644 index 000000000..694546969 --- /dev/null +++ b/man/std::unordered_multiset::end(size_type),.3 @@ -0,0 +1,30 @@ +.TH std::unordered_multiset::end(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::end(size_type), \- std::unordered_multiset::end(size_type), + +.SH Synopsis + + local_iterator end( size_type n ); \fI(since C++11)\fP + const_local_iterator end( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the bucket with + index n. This element acts as a placeholder, attempting to access it results in + undefined behavior. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH See also + + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_multiset::end,.3 b/man/std::unordered_multiset::end,.3 new file mode 100644 index 000000000..bf70dd404 --- /dev/null +++ b/man/std::unordered_multiset::end,.3 @@ -0,0 +1,78 @@ +.TH std::unordered_multiset::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::end, \- std::unordered_multiset::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator end() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the + unordered_multiset. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::unordered_multiset words = + { + "some", "words", "to", "count", + "count", "these", "words" + }; + + for (auto it = words.begin(); it != words.end(); ) + { + auto count = words.count(*it); + std::cout << *it << ":\\t" << count << '\\n'; + std::advance(it, count); // all count elements have equivalent keys + } + } + +.SH Possible output: + + some: 1 + words: 2 + to: 1 + count: 2 + these: 1 + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_multiset::end,std::unordered_multiset::cend.3 b/man/std::unordered_multiset::end,std::unordered_multiset::cend.3 deleted file mode 100644 index 8bf09aa91..000000000 --- a/man/std::unordered_multiset::end,std::unordered_multiset::cend.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::unordered_multiset::end,std::unordered_multiset::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the container. - - This element acts as a placeholder; attempting to access it results in undefined - behavior. - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the element following the last element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP diff --git a/man/std::unordered_multiset::equal_range.3 b/man/std::unordered_multiset::equal_range.3 index 156b5aeb2..d25539680 100644 --- a/man/std::unordered_multiset::equal_range.3 +++ b/man/std::unordered_multiset::equal_range.3 @@ -1,16 +1,31 @@ -.TH std::unordered_multiset::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::equal_range \- std::unordered_multiset::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fI(since C++11)\fP - std::pair equal_range( const Key& key \fI(since C++11)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + std::pair equal_range( const Key& \fB(2)\fP \fI(since C++11)\fP + key ) const; + template< class K > \fB(3)\fP \fI(since C++20)\fP + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++20)\fP ) const; - Returns a range containing all elements with key key in the container. The range is - defined by two iterators, the first pointing to the first element of the wanted - range and the second pointing past the last element of the range. + 1,2) Returns a range containing all elements with key key in the container. The + range is defined by two iterators, the first pointing to the first element of the + wanted range and the second pointing past the last element of the range. + 3,4) Returns a range containing all elements in the container with key equivalent to + x. This overload participates in overload resolution only if Hash::is_transparent + and KeyEqual::is_transparent are valid and each denotes a type. This assumes that + such Hash is callable with both K and Key type, and that the KeyEqual is + transparent, which, together, allows calling this function without constructing an + instance of Key. .SH Parameters key - key value to compare the elements to + x - a value of any type that can be transparently compared with a key .SH Return value @@ -20,9 +35,67 @@ .SH Complexity - Average case constant, worst case linear in the size of the container. + Average case linear in the number of elements with the key key, worst case linear in + the size of the container. + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overloads (3,4) + +.SH Example + + Estimates the characters frequency for given string. + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string sentence{"cppreference.com"}; + std::cout << "The sentence: " << sentence << '\\n'; + + std::unordered_multiset sequence; + for (char x : sentence) + sequence.insert(x); + + std::cout << "The sequence: { "; + for (char x : sequence) + std::cout << x << ' '; + + std::cout << "}\\n" "Symbol:Frequency: "; + for (auto it = sequence.begin(); it != sequence.end();) + { + if (auto [first, last] = sequence.equal_range(*it); first != last) + { + std::cout << *first << ":" << std::distance(first, last) << " "; + it = last; + } + else + ++it; + } + } + +.SH Possible output: + + The sentence: cppreference.com + The sequence: { m o c c c p p r r e e e e f n . } + Symbol:Frequency: m:1 o:1 c:3 p:2 r:2 e:4 f:1 n:1 .:1 .SH See also - find finds element with specific key - \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::unordered_multiset::erase.3 b/man/std::unordered_multiset::erase.3 index 325da0f85..70b3c820d 100644 --- a/man/std::unordered_multiset::erase.3 +++ b/man/std::unordered_multiset::erase.3 @@ -1,50 +1,127 @@ -.TH std::unordered_multiset::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator erase( const_iterator pos ); \fB(1)\fP \fI(since C++11)\fP - iterator erase( const_iterator first, const_iterator last ); \fB(2)\fP \fI(since C++11)\fP - size_type erase( const key_type& key ); \fB(3)\fP \fI(since C++11)\fP - - Removes specified elements from the container. +.TH std::unordered_multiset::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::erase \- std::unordered_multiset::erase - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. +.SH Synopsis + iterator erase( iterator pos ); \fI(since C++11)\fP + (until C++23) + iterator erase( iterator pos ) (since C++23) + requires(!std::same_as); + iterator erase( const_iterator pos ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP \fI(since C++11)\fP + size_type erase( const Key& key ); \fB(4)\fP \fI(since C++11)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. The order of the remaining elements + is preserved. (This makes it possible to erase individual elements while iterating + through the container.) + + 1,2) Removes the element at pos. Only one overload is provided if iterator and + const_iterator are the same type. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes all elements with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. This assumes that such Hash is + callable with both K and Key type, and that the KeyEqual is transparent, which, + together, allows calling this function without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other iterators and references are not invalidated. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. - - The order of the elements that are not erased is preserved (this makes - it possible to erase individual elements while iterating through the \fI(since C++14)\fP - container) + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed. + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Hash and KeyEqual object. .SH Complexity Given an instance c of unordered_multiset: - 1) Average case: constant, worst case: c.size() - 2) Average case: std::distance(first, last), worst case: c.size() - 3) Average case: c.count(key), worst case: c.size() + 1,2) Average case: constant, worst case: c.size(). + 3) Average case: std::distance(first, last), worst case: c.size(). + 4) Average case: c.count(key), worst case: c.size(). + 5) Average case: c.count(x), worst case: c.size(). + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_multiset c = {1, 2, 3, 4, 1, 2, 3, 4}; + + auto print = [&c] + { + std::cout << "c = { "; + for (int n : c) + std::cout << n << ' '; + std::cout << "}\\n"; + }; + print(); + + std::cout << "Erase all odd numbers:\\n"; + for (auto it = c.begin(); it != c.end();) + { + if (*it % 2 != 0) + it = c.erase(it); + else + ++it; + } + print(); + + std::cout << "Erase 1, erased count: " << c.erase(1) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + print(); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2059 C++11 there was ambiguity for overload (2) added overload (1) + the order of non-equivalent elements + LWG 2356 C++11 that are required to be preserved + not erased was not guaranteed to be + preserved .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::extract.3 b/man/std::unordered_multiset::extract.3 new file mode 100644 index 000000000..507ab3b69 --- /dev/null +++ b/man/std::unordered_multiset::extract.3 @@ -0,0 +1,120 @@ +.TH std::unordered_multiset::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::extract \- std::unordered_multiset::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains the first such element from the container and returns a node handle that + owns it. Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type, + and neither iterator nor const_iterator is implicitly convertible from K. This + assumes that such Hash is callable with both K and Key type, and that the KeyEqual + is transparent, which, together, allows calling this function without constructing + an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed . + + Extracting a node invalidates only the iterators to the extracted element, and + preserves the relative order of the elements that are not erased. Pointers and + references to the extracted element remain valid, but cannot be used while element + is owned by a node handle: they become usable if the element is inserted into a + container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Hash and KeyEqual object. + +.SH Complexity + + 1,2,3) Average case O(1), worst case O(size()). + +.SH Notes + + extract is the only way to take a move-only object out of a set: + + std::set s; + s.emplace(...); + move_only_type mot = std::move(s.extract(s.begin()).value()); + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto datum : data) + std::cout << ' ' << datum; + + std::cout << '\\n'; + } + + int main() + { + std::unordered_multiset cont{1, 2, 3}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.value() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Possible output: + + Start: 1 2 3 + After extract and before insert: 2 3 + End: 2 3 4 + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::find.3 b/man/std::unordered_multiset::find.3 index 4fc18ba47..4b7245523 100644 --- a/man/std::unordered_multiset::find.3 +++ b/man/std::unordered_multiset::find.3 @@ -1,35 +1,71 @@ -.TH std::unordered_multiset::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::find \- std::unordered_multiset::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP + iterator find( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP \fI(since C++20)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++20)\fP + const_iterator find( const K& x ) const; - 1,2) Finds an element with key equivalent to key. + 1,2) Finds an element with key equivalent to key. If there are several elements with + the requested key in the container, any of them may be returned. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. .SH Parameters key - key value of the element to search for + x - a value of any type that can be transparently compared with a key .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Constant on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers; overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + // Simple comparison demo. + std::unordered_multiset example = {1, 2, 3, 4}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << (*search) << '\\n'; + else + std::cout << "Not found\\n"; + } + +.SH Output: + + Found 2 .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::get_allocator.3 b/man/std::unordered_multiset::get_allocator.3 index 4aab667df..808ca36c0 100644 --- a/man/std::unordered_multiset::get_allocator.3 +++ b/man/std::unordered_multiset::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::unordered_multiset::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::get_allocator \- std::unordered_multiset::get_allocator + .SH Synopsis - allocator_type get_allocator() const; \fI(since C++11)\fP + allocator_type get_allocator() const noexcept; \fI(since C++11)\fP Returns the allocator associated with the container. diff --git a/man/std::unordered_multiset::hash_function.3 b/man/std::unordered_multiset::hash_function.3 index 6da45f322..2deb9be62 100644 --- a/man/std::unordered_multiset::hash_function.3 +++ b/man/std::unordered_multiset::hash_function.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::hash_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::hash_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::hash_function \- std::unordered_multiset::hash_function + .SH Synopsis hasher hash_function() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::insert.3 b/man/std::unordered_multiset::insert.3 index 7ad6dc512..194683852 100644 --- a/man/std::unordered_multiset::insert.3 +++ b/man/std::unordered_multiset::insert.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::insert \- std::unordered_multiset::insert + .SH Synopsis iterator insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP iterator insert( value_type&& value ); \fB(2)\fP \fI(since C++11)\fP @@ -7,19 +10,34 @@ template< class InputIt > \fB(5)\fP \fI(since C++11)\fP void insert( InputIt first, InputIt last ); void insert( std::initializer_list ilist ); \fB(6)\fP \fI(since C++11)\fP + iterator insert( node_type&& nh ); \fB(7)\fP \fI(since C++17)\fP + iterator insert( const_iterator hint, node_type&& nh ); \fB(8)\fP \fI(since C++17)\fP Inserts element(s) into the container. - 1-2) Inserts value. - 3-4) Inserts value, using hint as a non-binding suggestion to where the search + 1,2) Inserts value. + 3,4) Inserts value, using hint as a non-binding suggestion to where the search should start. 5) Inserts elements from range [first, last). 6) Inserts elements from initializer list ilist. - - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + 7) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container and returns an iterator pointing at the inserted element. + The behavior is undefined if nh is not empty and get_allocator() != + nh.get_allocator(). + 8) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, and returns the + iterator pointing to the element with key equivalent to nh.key(). hint is used as a + non-binding suggestion to where the search should start. The behavior is undefined + if nh is not empty and get_allocator() != nh.get_allocator(). + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters @@ -27,35 +45,46 @@ value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-4) Returns an iterator to the inserted element. - 5-6) \fI(none)\fP + 1-4) An iterator to the inserted element. + 5,6) \fI(none)\fP + 7,8) End iterator if nh was empty, iterator pointing to the inserted element + otherwise. .SH Exceptions 1-4) If an exception is thrown by any operation, the insertion has no effect. This section is incomplete - Reason: cases 5-6 + Reason: cases 5,6 .SH Complexity - 1-4) Average case: O(1), worst case O(size()) - 5-6) Average case: O(N), where N is the number of elements to insert. Worse case: - O(N*size()+N) + 1-4) Average case: O(1), worst case O(size()). + 5,6) Average case: O(N), where N is the number of elements to insert. Worst case: + O(N * size() + N). + 7,8) Average case: O(1), worst case O(size()). + +.SH Example + + This section is incomplete + Reason: no example .SH See also emplace constructs element in-place - \fI(public member function)\fP + \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - -.SH Category: + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP +.SH Categories: * Todo with reason + * Todo no example diff --git a/man/std::unordered_multiset::insert_range.3 b/man/std::unordered_multiset::insert_range.3 new file mode 100644 index 000000000..29e8f58e7 --- /dev/null +++ b/man/std::unordered_multiset::insert_range.3 @@ -0,0 +1,77 @@ +.TH std::unordered_multiset::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::insert_range \- std::unordered_multiset::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements + are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into unordered_multiset from + *ranges::begin(rg). Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), where N is ranges::distance(rg), worst case O(N·(a.size() + 1)). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + + void println(auto, auto const& container) + { + for (const auto& elem : container) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::unordered_multiset{1, 3, 2, 4}; + const auto rg = {-1, 3, -2}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Possible output: + + 1 -2 3 3 2 -1 4 + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::key_eq.3 b/man/std::unordered_multiset::key_eq.3 index d0aefdaac..b416ac8f7 100644 --- a/man/std::unordered_multiset::key_eq.3 +++ b/man/std::unordered_multiset::key_eq.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::key_eq 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::key_eq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::key_eq \- std::unordered_multiset::key_eq + .SH Synopsis key_equal key_eq() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also hash_function returns function used to hash the keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::load_factor.3 b/man/std::unordered_multiset::load_factor.3 index 2f97fe70b..73481f768 100644 --- a/man/std::unordered_multiset::load_factor.3 +++ b/man/std::unordered_multiset::load_factor.3 @@ -1,8 +1,12 @@ -.TH std::unordered_multiset::load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::load_factor \- std::unordered_multiset::load_factor + .SH Synopsis float load_factor() const; \fI(since C++11)\fP - Returns the average number of elements per bucket. + Returns the average number of elements per bucket, that is, size() divided by + bucket_count(). .SH Parameters @@ -19,4 +23,4 @@ .SH See also max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::max_bucket_count.3 b/man/std::unordered_multiset::max_bucket_count.3 index 05425da0e..83bec272e 100644 --- a/man/std::unordered_multiset::max_bucket_count.3 +++ b/man/std::unordered_multiset::max_bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::max_bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::max_bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::max_bucket_count \- std::unordered_multiset::max_bucket_count + .SH Synopsis size_type max_bucket_count() const; \fI(since C++11)\fP @@ -17,7 +20,41 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + struct Ha { std::size_t operator()(long x) const { return std::hash{}(x); }; }; + + auto c1 = std::unordered_multiset{}; + auto c2 = std::unordered_multiset{}; + auto c3 = std::unordered_multiset>{}; + auto c4 = std::unordered_multiset{}; + + std::cout + << "Max bucket count of\\n" << std::hex << std::showbase + << "c1: " << c1.max_bucket_count() << '\\n' + << "c2: " << c2.max_bucket_count() << '\\n' + << "c3: " << c3.max_bucket_count() << '\\n' + << "c4: " << c4.max_bucket_count() << '\\n' + ; + } + +.SH Possible output: + + Max bucket count of + c1: 0xfffffffffffffff + c2: 0xfffffffffffffff + c3: 0xfffffffffffffff + c4: 0xaaaaaaaaaaaaaaa + .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::max_load_factor.3 b/man/std::unordered_multiset::max_load_factor.3 index b1727199f..90e182d54 100644 --- a/man/std::unordered_multiset::max_load_factor.3 +++ b/man/std::unordered_multiset::max_load_factor.3 @@ -1,4 +1,7 @@ -.TH std::unordered_multiset::max_load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::max_load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::max_load_factor \- std::unordered_multiset::max_load_factor + .SH Synopsis float max_load_factor() const; \fB(1)\fP \fI(since C++11)\fP void max_load_factor( float ml ); \fB(2)\fP \fI(since C++11)\fP @@ -8,7 +11,6 @@ threshold. 1) Returns current maximum load factor. - 2) Sets the maximum load factor to ml. .SH Parameters @@ -17,15 +19,14 @@ .SH Return value - 1) current maximum load factor. - - 2) none. + 1) Current maximum load factor. + 2) \fI(none)\fP .SH Complexity - Constant + Constant. .SH See also load_factor returns average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::max_size.3 b/man/std::unordered_multiset::max_size.3 index cc365c84f..1fc985af2 100644 --- a/man/std::unordered_multiset::max_size.3 +++ b/man/std::unordered_multiset::max_size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_multiset::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::max_size \- std::unordered_multiset::max_size + .SH Synopsis - size_type max_size() const; \fI(since C++11)\fP + size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,24 +17,45 @@ Maximum number of elements. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_multiset p; + std::unordered_multiset q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + q.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::merge.3 b/man/std::unordered_multiset::merge.3 new file mode 100644 index 000000000..b424d7fd8 --- /dev/null +++ b/man/std::unordered_multiset::merge.3 @@ -0,0 +1,86 @@ +.TH std::unordered_multiset::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::merge \- std::unordered_multiset::merge + +.SH Synopsis + template< class H2, class P2 > \fB(1)\fP \fI(since C++17)\fP + void merge( std::unordered_set& source ); + template< class H2, class P2 > \fB(2)\fP \fI(since C++17)\fP + void merge( std::unordered_set&& source ); + template< class H2, class P2 > + void merge( std::unordered_multiset& \fB(3)\fP \fI(since C++17)\fP + source ); + template< class H2, class P2 > + void merge( std::unordered_multiset&& \fB(4)\fP \fI(since C++17)\fP + source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the hash function and key equality predicate of *this. + + No elements are copied or moved, only the internal pointers of the container nodes + are repointed. All pointers and references to the transferred elements remain valid, + but now refer into *this, not into source. Iterators referring to the transferred + elements and all iterators referring to *this are invalidated. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), worst case O(N * size() + N), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + + // print out a container + template + Os& operator<<(Os& os, const std::unordered_multiset& v) + { + os << '[' << v.size() << "] {"; + bool o{}; + for (const auto& e : v) + os << (o ? ", " : (o = 1, " ")) << e; + return os << " }\\n"; + } + + int main() + { + std::unordered_multiset + p{'C', 'B', 'B', 'A'}, + q{'E', 'D', 'E', 'C'}; + + std::cout << "p: " << p << "q: " << q; + + p.merge(q); + + std::cout << "p.merge(q);\\n" << "p: " << p << "q: " << q; + } + +.SH Possible output: + + p: [4] { A, B, B, C } + q: [4] { C, D, E, E } + p.merge(q); + p: [8] { E, E, D, A, B, B, C, C } + q: [0] { } + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::operator=.3 b/man/std::unordered_multiset::operator=.3 index 20ac88324..8c9062cc6 100644 --- a/man/std::unordered_multiset::operator=.3 +++ b/man/std::unordered_multiset::operator=.3 @@ -1,28 +1,40 @@ -.TH std::unordered_multiset::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::operator= \- std::unordered_multiset::operator= + .SH Synopsis - unordered_multiset& operator=( const unordered_multiset& other ); \fB(1)\fP \fI(since C++11)\fP - unordered_multiset& operator=( unordered_multiset&& other ); \fB(2)\fP \fI(since C++11)\fP - unordered_multiset& operator=( std::initializer_list \fB(3)\fP \fI(since C++11)\fP - ilist ); + unordered_multiset& operator=( const \fB(1)\fP \fI(since C++11)\fP + unordered_multiset& other ); + unordered_multiset& operator=( unordered_multiset&& \fI(since C++11)\fP + other ); \fI(until C++17)\fP + unordered_multiset& operator=( unordered_multiset&& \fB(2)\fP \fI(since C++17)\fP + other ) noexcept(/* see below */); + unordered_multiset& operator=( \fB(3)\fP \fI(since C++11)\fP + std::initializer_list ilist ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + If + std::allocator_traits::propagate_on_container_copy_assignment::value + is true, the allocator of *this is replaced by a copy of other. If the allocator of + *this after assignment would compare unequal to its old value, the old allocator is + used to deallocate the memory, then the new allocator is used to allocate it before + copying the elements. Otherwise, the memory owned by *this may be reused when + possible. In any case, the elements originally belonging to *this may be either + destroyed or replaced by element-wise copy-assignment. 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -36,66 +48,99 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + + && std::is_nothrow_move_assignable::value + + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::unordered_multiset to another: - The following code uses to assign one std::unordered_multiset to another: - // Run this code - #include + #include #include - - void display_sizes(const std::unordered_multiset &nums1, - const std::unordered_multiset &nums2, - const std::unordered_multiset &nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::unordered_multiset nums1 {3, 1, 4, 6, 5, 9}; - std::unordered_multiset nums2; - std::unordered_multiset nums3; - + std::unordered_multiset x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } -.SH Output: +.SH Possible output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 3, 2, 1 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 3, 2, 1 } + y = { 3, 2, 1 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 3, 2, 1 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 7, 6, 5, 4 } .SH See also constructor constructs the unordered_multiset - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_multiset::rehash.3 b/man/std::unordered_multiset::rehash.3 index 09a2128b9..234251238 100644 --- a/man/std::unordered_multiset::rehash.3 +++ b/man/std::unordered_multiset::rehash.3 @@ -1,16 +1,17 @@ -.TH std::unordered_multiset::rehash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::rehash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::rehash \- std::unordered_multiset::rehash + .SH Synopsis void rehash( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to count and rehashes the container, i.e. puts the - elements into appropriate buckets considering that total number of buckets has - changed. If the new number of buckets makes load factor more than maximum load - factor (count < size() / max_load_factor()), then the new number of buckets is at - least size() / max_load_factor(). + Changes the number of buckets to a value n that is not less than count and satisfies + n >= size() / max_load_factor(), then rehashes the container, i.e. puts the elements + into appropriate buckets considering that total number of buckets has changed. .SH Parameters - count - new number of buckets + count - lower bound for the new number of buckets .SH Return value @@ -23,10 +24,10 @@ .SH Notes rehash\fB(0)\fP may be used to force an unconditional rehash, such as after suspension of - automatic rehashing by temporary increasing max_load_factor(). + automatic rehashing by temporarily increasing max_load_factor(). .SH See also - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + reserves space for at least the specified number of elements and regenerates + reserve the hash table + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::reserve.3 b/man/std::unordered_multiset::reserve.3 index 74b99030d..593e25b30 100644 --- a/man/std::unordered_multiset::reserve.3 +++ b/man/std::unordered_multiset::reserve.3 @@ -1,8 +1,11 @@ -.TH std::unordered_multiset::reserve 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::reserve \- std::unordered_multiset::reserve + .SH Synopsis void reserve( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to the number needed to accomodate at least count + Sets the number of buckets to the number needed to accommodate at least count elements without exceeding maximum load factor and rehashes the container, i.e. puts the elements into appropriate buckets considering that total number of buckets has changed. Effectively calls rehash(std::ceil(count / max_load_factor())). @@ -21,6 +24,6 @@ .SH See also - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates the hash + rehash table + \fI(public member function)\fP diff --git a/man/std::unordered_multiset::size.3 b/man/std::unordered_multiset::size.3 index aa5328294..fb2906420 100644 --- a/man/std::unordered_multiset::size.3 +++ b/man/std::unordered_multiset::size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_multiset::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::size \- std::unordered_multiset::size + .SH Synopsis - size_type size() const; \fI(since C++11)\fP + size_type size() const noexcept; \fI(since C++11)\fP Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,27 @@ The number of elements in the container. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::unordered_multiset: - + // Run this code - #include #include - + #include + int main() { - std::unordered_multiset nums {1, 3, 5, 7}; - + std::unordered_multiset nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +46,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::unordered_multiset::swap.3 b/man/std::unordered_multiset::swap.3 index 97c3b4a3b..c3a41d9e1 100644 --- a/man/std::unordered_multiset::swap.3 +++ b/man/std::unordered_multiset::swap.3 @@ -1,19 +1,24 @@ -.TH std::unordered_multiset::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::swap \- std::unordered_multiset::swap + .SH Synopsis - void swap( unordered_multiset& other ); \fI(since C++11)\fP + void swap( unordered_multiset& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + void swap( unordered_multiset& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. The Hash and KeyEqual objects must be Swappable, and they are exchanged using unqualified calls to non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +30,62 @@ .SH Exceptions - Any exception thrown by the swap Hash or KeyEqual objects. + Any exception thrown by the swap of the Hash or KeyEqual objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value + \fI(since C++17)\fP + && std::is_nothrow_swappable::value + + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + template Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::unordered_multiset a1{3, 1, 3, 2}, a2{5, 4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + const int& ref1 = *(a1.begin()); + const int& ref2 = *(a2.begin()); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that every iterator referring to an element in one container before the swap + // refers to the same element in the other container after the swap. Same is true + // for references. + } + +.SH Possible output: + + { 2 3 3 1 } { 4 5 5 } 3 5 2 4 + { 4 5 5 } { 2 3 3 1 } 3 5 2 4 + .SH See also std::swap(std::unordered_multiset) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_multiset::unordered_multiset.3 b/man/std::unordered_multiset::unordered_multiset.3 index 2987656bf..602b5a28e 100644 --- a/man/std::unordered_multiset::unordered_multiset.3 +++ b/man/std::unordered_multiset::unordered_multiset.3 @@ -1,91 +1,148 @@ -.TH std::unordered_multiset::unordered_multiset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::unordered_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::unordered_multiset \- std::unordered_multiset::unordered_multiset + .SH Synopsis - explicit unordered_multiset( size_type bucket_count = - /*implementation-defined*/, + unordered_multiset() \fI(since C++11)\fP + : unordered_multiset(size_type(/* implementation-defined \fI(until C++20)\fP + */)) {} + unordered_multiset(); \fI(since C++20)\fP + explicit unordered_multiset( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++11)\fP - const KeyEqual& equal = \fI(until C++14)\fP - KeyEqual(), + const Hash& hash = Hash(), + const key_equal& equal = \fB(2)\fP \fI(since C++11)\fP + key_equal(), const Allocator& alloc = Allocator() ); - unordered_multiset : unordered_multiset( - size_type(/*implementation-defined*/) {} + unordered_multiset( size_type bucket_count, - explicit unordered_multiset( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++14)\fP - const KeyEqual& equal = - KeyEqual(), + const Allocator& alloc ) \fB(3)\fP \fI(since C++14)\fP - const Allocator& alloc = - Allocator() ); + : unordered_multiset(bucket_count, Hash(), key_equal(), + alloc) {} unordered_multiset( size_type bucket_count, - const Allocator& alloc = - Allocator() ); - unordered_multiset( size_type bucket_count, \fB(1)\fP \fI(since C++14)\fP - const Hash& hash, + const Hash& hash, + const Allocator& alloc ) \fB(4)\fP \fI(since C++14)\fP - const Allocator& alloc = - Allocator() ); - explicit unordered_multiset( const Allocator& alloc ); \fB(1)\fP \fI(since C++11)\fP + : unordered_multiset(bucket_count, hash, key_equal(), + alloc) {} + explicit unordered_multiset( const Allocator& alloc ); \fB(5)\fP \fI(since C++11)\fP template< class InputIt > unordered_multiset( InputIt first, InputIt last, - size_type bucket_count = - /*implementation-defined*/, \fB(1)\fP + size_type bucket_count = /* + implementation-defined */, \fB(6)\fP \fI(since C++11)\fP const Hash& hash = Hash(), - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - template< class InputIt > \fB(2)\fP - unordered_multiset( InputIt first, InputIt last, \fI(since C++14)\fP - size_type bucket_count, + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); template< class InputIt > + unordered_multiset( InputIt first, InputIt last, size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(7)\fP \fI(since C++14)\fP + : unordered_multiset(first, last, - const Allocator& alloc = Allocator() ); - unordered_multiset( const unordered_multiset& other ); \fB(3)\fP \fI(since C++11)\fP - unordered_multiset( const unordered_multiset& other, const \fB(3)\fP \fI(since C++11)\fP - Allocator& alloc ); - unordered_multiset( unordered_multiset&& other ); \fB(4)\fP \fI(since C++11)\fP - unordered_multiset( unordered_multiset&& other, const \fB(4)\fP \fI(since C++11)\fP + bucket_count, Hash(), key_equal(), + alloc) {} + template< class InputIt > + + unordered_multiset( InputIt first, InputIt last, + size_type bucket_count, + const Hash& hash, \fB(8)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_multiset(first, last, + + bucket_count, hash, key_equal(), + alloc) {} + unordered_multiset( const unordered_multiset& other ); \fB(9)\fP \fI(since C++11)\fP + unordered_multiset( const unordered_multiset& other, const \fB(10)\fP \fI(since C++11)\fP + Allocator& alloc ); \fB(1)\fP + unordered_multiset( unordered_multiset&& other ); \fB(11)\fP \fI(since C++11)\fP + unordered_multiset( unordered_multiset&& other, const \fB(12)\fP \fI(since C++11)\fP Allocator& alloc ); unordered_multiset( std::initializer_list init, - size_type bucket_count = - /*implementation-defined*/, + size_type bucket_count = /* + implementation-defined */, \fB(13)\fP \fI(since C++11)\fP const Hash& hash = Hash(), - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - unordered_multiset( std::initializer_list init, \fB(5)\fP - size_type bucket_count, \fI(since C++14)\fP + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); unordered_multiset( std::initializer_list init, + size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(14)\fP \fI(since C++14)\fP + : unordered_multiset(init, bucket_count, + + Hash(), key_equal(), alloc) {} + unordered_multiset( std::initializer_list init, + + size_type bucket_count, + const Hash& hash, \fB(15)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_multiset(init, bucket_count, + + hash, key_equal(), alloc) {} + template< container-compatible-range R > + + unordered_multiset( std::from_range_t, R&& rg, + size_type bucket_count = /* see + description */, \fB(16)\fP (since C++23) + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), const Allocator& alloc = Allocator() ); + template< container-compatible-range R > + + unordered_multiset( std::from_range_t, R&& rg, + size_type bucket_count, + const Allocator& alloc ) \fB(17)\fP (since C++23) + : unordered_multiset(std::from_range, + std::forward(rg), + + bucket_count, Hash(), key_equal(), + alloc) {} + template< container-compatible-range R > + + unordered_multiset( std::from_range_t, R&& rg, + size_type bucket_count, + const Hash& hash, + const Alloc& alloc ) \fB(18)\fP (since C++23) + : unordered_multiset(std::from_range, + std::forward(rg), + + bucket_count, hash, key_equal(), + alloc) {} Constructs new container from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator. - 1) Constructs empty container. Sets max_load_factor() to 1.0. For the default + 1-5) Constructs empty container. Sets max_load_factor() to 1.0. For the default constructor, the number of buckets is implementation-defined. - 2) constructs the container with the contents of the range [first, last). Sets + 6-8) Constructs the container with the contents of the range [first, last). Sets max_load_factor() to 1.0. - 3) copy constructor. Constructs the container with the copy of the contents of + 9,10) Copy constructor. Constructs the container with the copy of the contents of other, copies the load factor, the predicate, and the hash function as well. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). - 4) move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 5) constructs the container with the contents of the initializer list init, same as - unordered_multiset(init.begin(), init.end()). + std::allocator_traits::select_on_container_copy_construction(other.get_allocator()). + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 11,12) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 13-15) Initializer-list constructor. Constructs the container with the contents of + the initializer list init, same as unordered_multiset(init.begin(), init.end()). + 16-18) Constructs the container with the contents of rg. .SH Parameters @@ -94,32 +151,63 @@ specified, implementation-defined default value is used hash - hash function to use equal - comparison function to use for all key comparisons of this container - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1) constant - 2) average case linear worst case quadratic in distance between first and last - 3) linear in size of other - 4) constant. If alloc is given and alloc != other.get_allocator(), then linear. - 5) average case linear worst case quadratic in size of init + 1-5) Constant. + 6-8) Average case linear (i.e. O(N), where N is std::distance(first, last)), worst + case quadratic, i.e. O(N^2). + 9,10) Linear in size of other. + 11,12) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 13-15) Average case O(N) (N is std::size(init)), worst case O(N^2). + 16-18) Average case O(N) (N is ranges::distance(rg)), worst case O(N^2). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + + After container move construction (overload \fB(4)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Although not formally required until C++23, some implementations have already put + the template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (16-18) .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2193 C++11 the default constructor (1) was explicit made non-explicit + .SH See also operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unordered_multiset::~unordered_multiset.3 b/man/std::unordered_multiset::~unordered_multiset.3 index c27660f68..b3cfbb84e 100644 --- a/man/std::unordered_multiset::~unordered_multiset.3 +++ b/man/std::unordered_multiset::~unordered_multiset.3 @@ -1,11 +1,14 @@ -.TH std::unordered_multiset::~unordered_multiset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_multiset::~unordered_multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_multiset::~unordered_multiset \- std::unordered_multiset::~unordered_multiset + .SH Synopsis ~unordered_multiset(); \fI(since C++11)\fP - Destructs the container. The destructors of the elements are called and the used - storage is deallocated. Note, that if the elements are pointers, the pointed-to + Destructs the unordered_multiset. The destructors of the elements are called and the + used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the unordered_multiset. diff --git a/man/std::unordered_set.3 b/man/std::unordered_set.3 index be9f69595..300ca826a 100644 --- a/man/std::unordered_set.3 +++ b/man/std::unordered_set.3 @@ -1,132 +1,261 @@ -.TH std::unordered_set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set \- std::unordered_set + .SH Synopsis Defined in header template< class Key, - class Hash = std::hash, \fI(since C++11)\fP + class Hash = std::hash, \fB(1)\fP \fI(since C++11)\fP class KeyEqual = std::equal_to, class Allocator = std::allocator > class unordered_set; + namespace pmr { + + template< + class Key, + class Hash = std::hash, + class Pred = std::equal_to \fB(2)\fP \fI(since C++17)\fP + > using unordered_set = std::unordered_set>; + + } - Unordered set is an associative container that contains set of unique objects of - type Key. Search, insertion, and removal have average constant-time complexity. + std::unordered_set is an associative container that contains a set of unique objects + of type Key. Search, insertion, and removal have average constant-time complexity. Internally, the elements are not sorted in any particular order, but organized into buckets. Which bucket an element is placed into depends entirely on the hash of its - value. This allows fast access to individual elements, since once hash is computed, - it refers to the exact bucket the element is placed into. + value. This allows fast access to individual elements, since once a hash is + computed, it refers to the exact bucket the element is placed into. + + Container elements may not be modified (even by non const iterators) since + modification could change an element's hash and corrupt the container. std::unordered_set meets the requirements of Container, AllocatorAwareContainer, UnorderedAssociativeContainer. +.SH Notes + + * The swap functions do not invalidate any of the iterators inside the container, + but they do invalidate the iterator marking the end of the swap region. + * References and pointers to data stored in the container are only invalidated by + erasing that element, even when the corresponding iterator is invalidated. + * After container move assignment, unless elementwise move assignment is forced by + incompatible allocators, references, pointers, and iterators (other than the + past-the-end iterator) to moved-from container remain valid, but refer to + elements that are now in *this. + +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - value_type Key - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - hasher Hash - key_equal KeyEqual - allocator_type Allocator - reference value_type& - const_reference const value_type& - pointer std::allocator_traits::pointer - const_pointer std::allocator_traits::const_pointer - iterator ForwardIterator - const_iterator Constant forward iterator - An iterator type whose category, value, difference, pointer and - local_iterator reference types are the same as iterator. This iterator - can be used to iterate through a single bucket but not across - buckets - An iterator type whose category, value, difference, pointer and - const_local_iterator reference types are the same as const_iterator. This iterator - can be used to iterate through a single bucket but not across - buckets + Member type Definition + key_type Key + value_type Key + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + hasher Hash + key_equal KeyEqual + allocator_type Allocator + reference value_type& + const_reference const value_type& + pointer std::allocator_traits::pointer + const_pointer std::allocator_traits::const_pointer + iterator Constant LegacyForwardIterator to value_type + const_iterator LegacyForwardIterator to const value_type + An iterator type whose category, value, difference, pointer + and + local_iterator reference types are the same as iterator. This iterator + can be used to iterate through a single bucket but not + across buckets + An iterator type whose category, value, difference, pointer + and + const_local_iterator reference types are the same as const_iterator. This + iterator + can be used to iterate through a single bucket but not + across buckets + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node + type describing the result of inserting a node_type, a + specialization of + + template + struct /*unspecified*/ + insert_return_type { + \fI(since C++17)\fP Iter position; + bool inserted; + NodeType node; + }; + instantiated with template arguments iterator and + node_type. .SH Member functions - constructor constructs the unordered_set - \fI(public member function)\fP - destructor destructs the unordered_set - \fI(public member function)\fP - operator= assigns values to the container - \fI(public member function)\fP - get_allocator returns the associated allocator - \fI(public member function)\fP + constructor constructs the unordered_set + \fI(public member function)\fP + destructor destructs the unordered_set + \fI(public member function)\fP + operator= assigns values to the container + \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP .SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP - end returns an iterator to the end - cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP .SH Capacity - empty checks whether the container is empty - \fI(public member function)\fP - size returns the number of elements - \fI(public member function)\fP - max_size returns the maximum possible number of elements - \fI(public member function)\fP + empty checks whether the container is empty + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP .SH Modifiers - clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - emplace constructs element in-place - \fI(public member function)\fP - emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - erase erases elements - \fI(public member function)\fP - swap swaps the contents - \fI(public member function)\fP + clear clears the contents + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + emplace constructs element in-place + \fI(public member function)\fP + emplace_hint constructs elements in-place using a hint + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup - count returns the number of elements matching specific key - \fI(public member function)\fP - find finds element with specific key - \fI(public member function)\fP - equal_range returns range of elements matching a specific key - \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP .SH Bucket interface - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP - bucket_count returns the number of buckets - \fI(public member function)\fP - max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP - bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP - bucket returns the bucket for specific key - \fI(public member function)\fP + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP + bucket_count returns the number of buckets + \fI(public member function)\fP + max_bucket_count returns the maximum number of buckets + \fI(public member function)\fP + bucket_size returns the number of elements in specific bucket + \fI(public member function)\fP + bucket returns the bucket for specific key + \fI(public member function)\fP .SH Hash policy - load_factor returns average number of elements per bucket - \fI(public member function)\fP - max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + load_factor returns average number of elements per bucket + \fI(public member function)\fP + max_load_factor manages maximum average number of elements per bucket + \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates + rehash the hash table + \fI(public member function)\fP + reserves space for at least the specified number of elements and + reserve regenerates the hash table + \fI(public member function)\fP .SH Observers - hash_function returns function used to hash the keys - \fI(public member function)\fP - key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + hash_function returns function used to hash the keys + \fI(public member function)\fP + key_eq returns the function used to compare keys for equality + \fI(public member function)\fP .SH Non-member functions - operator== compares the values in the unordered_set - operator!= \fI(function template)\fP + operator== + operator!= compares the values in the unordered_set + \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP(removed in C++20) std::swap(std::unordered_set) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + erase_if(std::unordered_set) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP .SH Notes - The member types iterator and const_iterator may be aliases to the same type. Since - iterator is convertible to const_iterator, const_iterator should be used in function - parameter lists to avoid violations of the One Definition Rule. + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + + void print(const auto& set) + { + for (const auto& elem : set) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + std::unordered_set mySet{2, 7, 1, 8, 2, 8}; // creates a set of ints + print(mySet); + + mySet.insert(5); // puts an element 5 in the set + print(mySet); + + if (auto iter = mySet.find(5); iter != mySet.end()) + mySet.erase(iter); // removes an element pointed to by iter + print(mySet); + + mySet.erase(7); // removes an element 7 + print(mySet); + } + +.SH Possible output: + + 8 1 7 2 + 5 8 1 7 2 + 8 1 7 2 + 8 1 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the definitions of reference, + LWG 2050 C++11 const_reference, pointer based on value_type and + and const_pointer were based on std::allocator_traits + allocator_type + +.SH See also + + set collection of unique keys, sorted by keys + \fI(class template)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::unordered_set::begin(int),std::unordered_set::cbegin(int).3 b/man/std::unordered_set::begin(int),std::unordered_set::cbegin(int).3 deleted file mode 100644 index 775264e69..000000000 --- a/man/std::unordered_set::begin(int),std::unordered_set::cbegin(int).3 +++ /dev/null @@ -1,24 +0,0 @@ -.TH std::unordered_set::begin(int),std::unordered_set::cbegin(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator begin( size_type n ); \fI(since C++11)\fP - const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the first element of the bucket with index pos. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - Iterator to the first element. - -.SH Complexity - - Constant. - -.SH See also - - end(int) returns an iterator to the end of the specified bucket - cend(int) \fI(public member function)\fP diff --git a/man/std::unordered_set::begin(size_type),.3 b/man/std::unordered_set::begin(size_type),.3 new file mode 100644 index 000000000..09b303028 --- /dev/null +++ b/man/std::unordered_set::begin(size_type),.3 @@ -0,0 +1,28 @@ +.TH std::unordered_set::begin(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::begin(size_type), \- std::unordered_set::begin(size_type), + +.SH Synopsis + + local_iterator begin( size_type n ); \fI(since C++11)\fP + const_local_iterator begin( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cbegin( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the first element of the bucket with index n. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH See also + + end(size_type) returns an iterator to the end of the specified bucket + cend(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_set::begin,.3 b/man/std::unordered_set::begin,.3 new file mode 100644 index 000000000..5e1834e7c --- /dev/null +++ b/man/std::unordered_set::begin,.3 @@ -0,0 +1,80 @@ +.TH std::unordered_set::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::begin, \- std::unordered_set::begin, + +.SH Synopsis + + iterator begin() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator begin() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the first element of the unordered_set. + + If the unordered_set is empty, the returned iterator will be equal to end(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + + struct Point { double x, y; }; + + int main() + { + Point pts[3] = {{1, 0}, {2, 0}, {3, 0}}; + + // points is a set containing the addresses of points + std::unordered_set points = { pts, pts + 1, pts + 2 }; + + // Change each y-coordinate of (i, 0) from 0 into i^2 and print the point + for (auto iter = points.begin(); iter != points.end(); ++iter) + { + (*iter)->y = ((*iter)->x) * ((*iter)->x); // iter is a pointer-to-Point* + std::cout << "(" << (*iter)->x << ", " << (*iter)->y << ") "; + } + std::cout << '\\n'; + + // Now using the range-based for loop, we increase each y-coordinate by 10 + for (Point* i : points) + { + i->y += 10; + std::cout << "(" << i->x << ", " << i->y << ") "; + } + } + +.SH Possible output: + + (3, 9) (1, 1) (2, 4) + (3, 19) (1, 11) (2, 14) + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_set::begin,std::unordered_set::cbegin.3 b/man/std::unordered_set::begin,std::unordered_set::cbegin.3 deleted file mode 100644 index 55a3295e4..000000000 --- a/man/std::unordered_set::begin,std::unordered_set::cbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::unordered_set::begin,std::unordered_set::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator begin(); \fI(since C++11)\fP - const_iterator begin() const; \fI(since C++11)\fP - const_iterator cbegin() const; \fI(since C++11)\fP - - Returns an iterator to the first element of the container. - - If the container is empty, the returned iterator will be equal to end(). - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the first element - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant - -.SH See also - - end returns an iterator to the end - cend \fI(public member function)\fP diff --git a/man/std::unordered_set::bucket.3 b/man/std::unordered_set::bucket.3 index 1f9a708ff..b8d0bd987 100644 --- a/man/std::unordered_set::bucket.3 +++ b/man/std::unordered_set::bucket.3 @@ -1,26 +1,61 @@ -.TH std::unordered_set::bucket 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - size_type bucket( const Key& key ) const; \fI(since C++11)\fP +.TH std::unordered_set::bucket 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::bucket \- std::unordered_set::bucket - Returns the index of the bucket for key key. Elements (if any) with keys equivalent - to key are always found in this bucket. The returned value is valid only for - instances of the container for which bucket_count() returns the same value. +.SH Synopsis + size_type bucket( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< typename K > \fB(2)\fP (since C++26) + size_type bucket( const K& x ) const; + + 1) Returns the index of the bucket for key key. Elements (if any) with keys + equivalent to key are always found in this bucket. + 2) Returns the index of the bucket for key that compares equivalent to the value x. + Elements (if any) with keys that compare equivalent to x are always found in this + bucket. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. + + The returned value is valid only for instances of the container for which + bucket_count() returns the same value (e.g., rehash() invalidates previously + obtained value). The behavior is undefined if bucket_count() is zero. .SH Parameters key - the value of the key to examine + x - a value of any type that can be transparently compared with a key .SH Return value - Bucket index for the key key. + Bucket index for the requested key. .SH Complexity Constant. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example + .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_set::bucket_count.3 b/man/std::unordered_set::bucket_count.3 index 9d6a6ecdb..8e8c4f3fd 100644 --- a/man/std::unordered_set::bucket_count.3 +++ b/man/std::unordered_set::bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_set::bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::bucket_count \- std::unordered_set::bucket_count + .SH Synopsis size_type bucket_count() const; \fI(since C++11)\fP @@ -19,6 +22,6 @@ .SH See also bucket_size returns the number of elements in specific bucket - \fI(public member function)\fP + \fI(public member function)\fP max_bucket_count returns the maximum number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::bucket_size.3 b/man/std::unordered_set::bucket_size.3 index d157cc875..e21fe2e58 100644 --- a/man/std::unordered_set::bucket_size.3 +++ b/man/std::unordered_set::bucket_size.3 @@ -1,4 +1,7 @@ -.TH std::unordered_set::bucket_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::bucket_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::bucket_size \- std::unordered_set::bucket_size + .SH Synopsis size_type bucket_size( size_type n ) const; \fI(since C++11)\fP @@ -14,9 +17,9 @@ .SH Complexity - Constant. + Linear in the size of the bucket n. .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::clear.3 b/man/std::unordered_set::clear.3 index 5141562d0..e8690456c 100644 --- a/man/std::unordered_set::clear.3 +++ b/man/std::unordered_set::clear.3 @@ -1,11 +1,14 @@ -.TH std::unordered_set::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::clear \- std::unordered_set::clear + .SH Synopsis - void clear(); \fI(since C++11)\fP + void clear() noexcept; \fI(since C++11)\fP - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + May also invalidate past-the-end iterators. .SH Parameters @@ -15,17 +18,55 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - noexcept specification: - noexcept - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::unordered_set& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::unordered_set container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Possible output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + for unordered associative + LWG 2550 C++11 containers, unclear if complexity clarified that it's linear in + is linear in the number of the number of elements + elements or buckets .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::contains.3 b/man/std::unordered_set::contains.3 new file mode 100644 index 000000000..a2ec813a9 --- /dev/null +++ b/man/std::unordered_set::contains.3 @@ -0,0 +1,62 @@ +.TH std::unordered_set::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::contains \- std::unordered_set::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Constant on average, worst case linear in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_set example{1, 2, 3, 4}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::unordered_set::count.3 b/man/std::unordered_set::count.3 index c35da5fd9..05d31ec3a 100644 --- a/man/std::unordered_set::count.3 +++ b/man/std::unordered_set::count.3 @@ -1,24 +1,78 @@ -.TH std::unordered_set::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::count \- std::unordered_set::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP \fI(since C++11)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + size_type count( const K& x ) const; - Returns the number of elements with key key. + 1) Returns the number of elements with key that compares equal to the specified + argument key, which is either 0 or 1 since this container does not allow duplicates. + 2) Returns the number of elements with key that compares equivalent to the specified + argument x. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. .SH Parameters key - key value of the elements to count + x - a value of any type that can be transparently compared with a key .SH Return value - Number of elements with key key. + 1) Number of elements with key key, that is either 1 or 0. + 2) Number of elements with key that compares equivalent to x. .SH Complexity Constant on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overload \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_set set{2, 7, 1, 8, 2, 8, 1, 8, 2, 8}; + + std::cout << "The set is: "; + for (int e : set) + std::cout << e << ' '; + + const auto [min, max] = std::ranges::minmax(set); + + std::cout << "\\nNumbers from " << min << " to " << max << " that are in the set: "; + for (int i{min}; i <= max; ++i) + if (set.count(i) == 1) + std::cout << i << ' '; + std::cout << '\\n'; + } + +.SH Possible output: + + The set is: 8 1 7 2 + Numbers from 1 to 8 that are in the set: 1 2 7 8 + .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::emplace.3 b/man/std::unordered_set::emplace.3 index 6608f98f7..bed582862 100644 --- a/man/std::unordered_set::emplace.3 +++ b/man/std::unordered_set::emplace.3 @@ -1,20 +1,26 @@ -.TH std::unordered_set::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::emplace \- std::unordered_set::emplace + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - std::pair emplace( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + std::pair emplace( Args&&... args ); + + Inserts a new element into the container constructed in-place with the given args, + if there is no element with the key in the container. - Inserts a new element into the container by constructing it in-place with the given - args. + The constructor of the new element is called with exactly the same arguments as + supplied to emplace, forwarded via std::forward(args).... The element may be + constructed even if there already is an element with the key in the container, in + which case the newly constructed element will be destroyed immediately. Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element is called - with exactly the same arguments as supplied to emplace, forwarded via - std::forward(args).... + unnecessary copy or move operations. - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -22,13 +28,14 @@ .SH Return value - Returns a pair consisting of a bool denoting whether the insertion took place and an - iterator to the inserted element, or the already-existing element if no insertion - happened. + A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -42,10 +49,11 @@ .SH See also emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unordered_set::emplace_hint.3 b/man/std::unordered_set::emplace_hint.3 index 12fb9e92d..673dcb8e8 100644 --- a/man/std::unordered_set::emplace_hint.3 +++ b/man/std::unordered_set::emplace_hint.3 @@ -1,19 +1,21 @@ -.TH std::unordered_set::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::emplace_hint \- std::unordered_set::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container, using hint as a suggestion where the + element should go. - The constructor of the element is called with exactly the same arguments as supplied - to the function, forwarded with std::forward(args).... + The constructors of the key and mapped value are called with exactly the same + arguments as supplied to the function, forwarded with std::forward(args).... - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. .SH Parameters @@ -22,18 +24,122 @@ .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element, or to the element that prevented the insertion. + +.SH Exceptions - If the insertion failed because the element already exists, returns an iterator to - the already existing element with the equivalent key. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Amortized constant on average, worst case linear in the size of the container. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + const int n_operations = 100'500'0; + + std::size_t set_emplace() + { + std::unordered_set set; + for (int i = 0; i < n_operations; ++i) + set.emplace(i); + return set.size(); + } + + std::size_t set_emplace_hint() + { + std::unordered_set set; + auto it = set.begin(); + for (int i = 0; i < n_operations; ++i) + { + set.emplace_hint(it, i); + it = set.end(); + } + return set.size(); + } + + std::size_t set_emplace_hint_wrong() + { + std::unordered_set set; + auto it = set.begin(); + for (int i = n_operations; i > 0; --i) + { + set.emplace_hint(it, i); + it = set.end(); + } + return set.size(); + } + + std::size_t set_emplace_hint_corrected() + { + std::unordered_set set; + auto it = set.begin(); + for (int i = n_operations; i > 0; --i) + { + set.emplace_hint(it, i); + it = set.begin(); + } + return set.size(); + } + + std::size_t set_emplace_hint_closest() + { + std::unordered_set set; + auto it = set.begin(); + for (int i = 0; i < n_operations; ++i) + it = set.emplace_hint(it, i); + return set.size(); + } + + double time_it(std::function set_test, + const char* what = nullptr, + double ratio = 0.0) + { + const auto start = std::chrono::system_clock::now(); + const std::size_t setsize = set_test(); + const auto stop = std::chrono::system_clock::now(); + const std::chrono::duration time = stop - start; + if (what != nullptr && setsize > 0) + std::cout << std::setw(8) << time << " for " << what << " (ratio: " + << (ratio == 0.0 ? 1.0 : ratio / time.count()) << ")\\n"; + return time.count(); + } + + int main() + { + std::cout << std::fixed << std::setprecision(2); + time_it(set_emplace); // cache warmup + const auto x = time_it(set_emplace, "plain emplace"); + time_it(set_emplace_hint, "emplace with correct hint", x); + time_it(set_emplace_hint_wrong, "emplace with wrong hint", x); + time_it(set_emplace_hint_corrected, "corrected emplace", x); + time_it(set_emplace_hint_closest, "emplace using returned iterator", x); + } + +.SH Possible output: + + 146.88ms for plain emplace (ratio: 1.00) + 168.20ms for emplace with correct hint (ratio: 0.87) + 168.78ms for emplace with wrong hint (ratio: 0.87) + 166.58ms for corrected emplace (ratio: 0.88) + 168.27ms for emplace using returned iterator (ratio: 0.87) + .SH See also emplace constructs element in-place - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::empty.3 b/man/std::unordered_set::empty.3 index 3123834b3..d774e1ef7 100644 --- a/man/std::unordered_set::empty.3 +++ b/man/std::unordered_set::empty.3 @@ -1,6 +1,11 @@ -.TH std::unordered_set::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::empty \- std::unordered_set::empty + .SH Synopsis - bool empty() const; \fI(since C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,13 +15,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - noexcept specification: - noexcept - + true if the container is empty, false otherwise. .SH Complexity @@ -24,33 +23,36 @@ .SH Example - + The following code uses empty to check if a std::unordered_set contains any elements: - + // Run this code - #include #include - + #include + int main() { std::unordered_set numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.insert(42); - numbers.insert(13317); + numbers.insert(19937); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; } .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::unordered_set::end(int),std::unordered_set::cend(int).3 b/man/std::unordered_set::end(int),std::unordered_set::cend(int).3 deleted file mode 100644 index c7c90f4c5..000000000 --- a/man/std::unordered_set::end(int),std::unordered_set::cend(int).3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH std::unordered_set::end(int),std::unordered_set::cend(int) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - local_iterator end( size_type n ); \fI(since C++11)\fP - const_local_iterator end( size_type n ) const; \fI(since C++11)\fP - const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the bucket with - index n. . This element acts as a placeholder, attempting to access it results in - undefined behavior. - -.SH Parameters - - n - the index of the bucket to access - -.SH Return value - - iterator to the element following the last element - -.SH Complexity - - Constant - -.SH See also - - begin(int) returns an iterator to the beginning of the specified bucket - cbegin(int) \fI(public member function)\fP diff --git a/man/std::unordered_set::end(size_type),.3 b/man/std::unordered_set::end(size_type),.3 new file mode 100644 index 000000000..7e1cc4456 --- /dev/null +++ b/man/std::unordered_set::end(size_type),.3 @@ -0,0 +1,30 @@ +.TH std::unordered_set::end(size_type), 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::end(size_type), \- std::unordered_set::end(size_type), + +.SH Synopsis + + local_iterator end( size_type n ); \fI(since C++11)\fP + const_local_iterator end( size_type n ) const; \fI(since C++11)\fP + const_local_iterator cend( size_type n ) const; \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the bucket with + index n. This element acts as a placeholder, attempting to access it results in + undefined behavior. + +.SH Parameters + + n - the index of the bucket to access + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH See also + + begin(size_type) returns an iterator to the beginning of the specified bucket + cbegin(size_type) \fI(public member function)\fP diff --git a/man/std::unordered_set::end,.3 b/man/std::unordered_set::end,.3 new file mode 100644 index 000000000..60a0e026f --- /dev/null +++ b/man/std::unordered_set::end,.3 @@ -0,0 +1,81 @@ +.TH std::unordered_set::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::end, \- std::unordered_set::end, + +.SH Synopsis + + iterator end() noexcept; \fB(1)\fP \fI(since C++11)\fP + const_iterator end() const noexcept; \fB(2)\fP \fI(since C++11)\fP + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns an iterator to the element following the last element of the unordered_set. + + This element acts as a placeholder; attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + +.SH Example + + +// Run this code + + #include + #include + + struct Point { double x, y; }; + + int main() + { + Point pts[3] = {{1, 0}, {2, 0}, {3, 0}}; + + // points is a set containing the addresses of points + std::unordered_set points = { pts, pts + 1, pts + 2 }; + + // Change each y-coordinate of (i, 0) from 0 into i^2 and print the point + for (auto iter = points.begin(); iter != points.end(); ++iter) + { + (*iter)->y = ((*iter)->x) * ((*iter)->x); // iter is a pointer-to-Point* + std::cout << "(" << (*iter)->x << ", " << (*iter)->y << ") "; + } + std::cout << '\\n'; + + // Now using the range-based for loop, we increase each y-coordinate by 10 + for (Point* i : points) + { + i->y += 10; + std::cout << "(" << i->x << ", " << i->y << ") "; + } + } + +.SH Possible output: + + (3, 9) (1, 1) (2, 4) + (3, 19) (1, 11) (2, 14) + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::unordered_set::end,std::unordered_set::cend.3 b/man/std::unordered_set::end,std::unordered_set::cend.3 deleted file mode 100644 index bdde4ae4e..000000000 --- a/man/std::unordered_set::end,std::unordered_set::cend.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH std::unordered_set::end,std::unordered_set::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator end(); \fI(since C++11)\fP - const_iterator end() const; \fI(since C++11)\fP - const_iterator cend() const; \fI(since C++11)\fP - - Returns an iterator to the element following the last element of the container. - - This element acts as a placeholder; attempting to access it results in undefined - behavior. - - range-begin-end.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Iterator to the element following the last element. - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH Complexity - - Constant. - -.SH See also - - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP diff --git a/man/std::unordered_set::equal_range.3 b/man/std::unordered_set::equal_range.3 index a3805e291..6f06031ff 100644 --- a/man/std::unordered_set::equal_range.3 +++ b/man/std::unordered_set::equal_range.3 @@ -1,16 +1,31 @@ -.TH std::unordered_set::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::equal_range \- std::unordered_set::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fI(since C++11)\fP - std::pair equal_range( const Key& key \fI(since C++11)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + std::pair equal_range( const Key& \fB(2)\fP \fI(since C++11)\fP + key ) const; + template< class K > \fB(3)\fP \fI(since C++20)\fP + std::pair equal_range( const K& x ); + template< class K > + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++20)\fP ) const; - Returns a range containing all elements with key key in the container. The range is - defined by two iterators, the first pointing to the first element of the wanted - range and the second pointing past the last element of the range. + 1,2) Returns a range containing all elements with key key in the container. The + range is defined by two iterators, the first pointing to the first element of the + wanted range and the second pointing past the last element of the range. + 3,4) Returns a range containing all elements in the container with key equivalent to + x. This overload participates in overload resolution only if Hash::is_transparent + and KeyEqual::is_transparent are valid and each denotes a type. This assumes that + such Hash is callable with both K and Key type, and that the KeyEqual is + transparent, which, together, allows calling this function without constructing an + instance of Key. .SH Parameters key - key value to compare the elements to + x - a value of any type that can be transparently compared with a key .SH Return value @@ -20,9 +35,31 @@ .SH Complexity - Average case constant, worst case linear in the size of the container. + Average case linear in the number of elements with the key key, worst case linear in + the size of the container. + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers, overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example .SH See also - find finds element with specific key - \fI(public member function)\fP + find finds element with specific key + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::unordered_set::erase.3 b/man/std::unordered_set::erase.3 index 78634469e..4cc558d35 100644 --- a/man/std::unordered_set::erase.3 +++ b/man/std::unordered_set::erase.3 @@ -1,50 +1,127 @@ -.TH std::unordered_set::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator erase( const_iterator pos ); \fB(1)\fP \fI(since C++11)\fP - iterator erase( const_iterator first, const_iterator last ); \fB(2)\fP \fI(since C++11)\fP - size_type erase( const key_type& key ); \fB(3)\fP \fI(since C++11)\fP - - Removes specified elements from the container. +.TH std::unordered_set::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::erase \- std::unordered_set::erase - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. +.SH Synopsis + iterator erase( iterator pos ); \fI(since C++11)\fP + (until C++23) + iterator erase( iterator pos ) (since C++23) + requires(!std::same_as); + iterator erase( const_iterator pos ); \fB(1)\fP \fB(2)\fP \fI(since C++11)\fP + iterator erase( const_iterator first, const_iterator last ); \fB(3)\fP \fI(since C++11)\fP + size_type erase( const Key& key ); \fB(4)\fP \fI(since C++11)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); + + Removes specified elements from the container. The order of the remaining elements + is preserved. (This makes it possible to erase individual elements while iterating + through the container.) + + 1,2) Removes the element at pos. Only one overload is provided if iterator and + const_iterator are the same type. + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes the element (if one exists) with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. This assumes that such Hash is + callable with both K and Key type, and that the KeyEqual is transparent, which, + together, allows calling this function without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other iterators and references are not invalidated. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. - - The order of the elements that are not erased is preserved (this makes - it possible to erase individual elements while iterating through the \fI(since C++14)\fP - container) + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed (0 or 1). + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Hash and KeyEqual object. .SH Complexity Given an instance c of unordered_set: - 1) Average case: constant, worst case: c.size() - 2) Average case: std::distance(first, last), worst case: c.size() - 3) Average case: c.count(key), worst case: c.size() + 1,2) Average case: constant, worst case: c.size(). + 3) Average case: std::distance(first, last), worst case: c.size(). + 4) Average case: c.count(key), worst case: c.size(). + 5) Average case: c.count(x), worst case: c.size(). + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::unordered_set c = {1, 2, 3, 4, 1, 2, 3, 4}; + + auto print = [&c] + { + std::cout << "c = { "; + for (int n : c) + std::cout << n << ' '; + std::cout << "}\\n"; + }; + print(); + + std::cout << "Erase all odd numbers:\\n"; + for (auto it = c.begin(); it != c.end();) + { + if (*it % 2 != 0) + it = c.erase(it); + else + ++it; + } + print(); + + std::cout << "Erase 1, erased count: " << c.erase(1) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + print(); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2059 C++11 there was ambiguity for overload (2) added overload (1) + the order of non-equivalent elements + LWG 2356 C++11 that are required to be preserved + not erased was not guaranteed to be + preserved .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::extract.3 b/man/std::unordered_set::extract.3 new file mode 100644 index 000000000..34854c751 --- /dev/null +++ b/man/std::unordered_set::extract.3 @@ -0,0 +1,120 @@ +.TH std::unordered_set::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::extract \- std::unordered_set::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains that element from the container and returns a node handle that owns it. + Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type, + and neither iterator nor const_iterator is implicitly convertible from K. This + assumes that such Hash is callable with both K and Key type, and that the KeyEqual + is transparent, which, together, allows calling this function without constructing + an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed . + + Extracting a node invalidates only the iterators to the extracted element, and + preserves the relative order of the elements that are not erased. Pointers and + references to the extracted element remain valid, but cannot be used while element + is owned by a node handle: they become usable if the element is inserted into a + container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Hash and KeyEqual object. + +.SH Complexity + + 1,2,3) Average case O(1), worst case O(size()). + +.SH Notes + + extract is the only way to take a move-only object out of a set: + + std::set s; + s.emplace(...); + move_only_type mot = std::move(s.extract(s.begin()).value()); + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto datum : data) + std::cout << ' ' << datum; + + std::cout << '\\n'; + } + + int main() + { + std::unordered_set cont{1, 2, 3}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.value() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Possible output: + + Start: 1 2 3 + After extract and before insert: 2 3 + End: 2 3 4 + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::unordered_set::find.3 b/man/std::unordered_set::find.3 index 355d1fb96..68113a016 100644 --- a/man/std::unordered_set::find.3 +++ b/man/std::unordered_set::find.3 @@ -1,35 +1,123 @@ -.TH std::unordered_set::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::find \- std::unordered_set::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP + iterator find( const Key& key ); \fB(1)\fP \fI(since C++11)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP \fI(since C++11)\fP + template< class K > \fB(3)\fP \fI(since C++20)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++20)\fP + const_iterator find( const K& x ) const; 1,2) Finds an element with key equivalent to key. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if Hash::is_transparent and + KeyEqual::is_transparent are valid and each denotes a type. This assumes that such + Hash is callable with both K and Key type, and that the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. .SH Parameters key - key value of the element to search for + x - a value of any type that can be transparently compared with a key .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Constant on average, worst case linear in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_unordered_lookup 201811L (C++20) in unordered associative + containers; overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + using namespace std::literals; + + namespace logger { bool enabled{false}; } + + inline void who(const std::source_location sloc = std::source_location::current()) + { + if (logger::enabled) + std::cout << sloc.function_name() << '\\n'; + } + + struct string_hash // C++20's transparent hashing + { + using hash_type = std::hash; + using is_transparent = void; + + std::size_t operator()(const char* str) const + { + who(); + return hash_type{}(str); + } + std::size_t operator()(std::string_view str) const + { + who(); + return hash_type{}(str); + } + std::size_t operator()(std::string const& str) const + { + who(); + return hash_type{}(str); + } + }; + + int main() + { + std::unordered_set example{1, 2, -10}; + + std::cout << "Simple comparison demo:\\n" << std::boolalpha; + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << *search << '\\n'; + else + std::cout << "Not found\\n"; + + std::unordered_set> set{"one"s, "two"s}; + + logger::enabled = true; + std::cout << "Heterogeneous lookup for unordered containers (transparent hashing):\\n" + << (set.find("one") != set.end()) << '\\n' + << (set.find("one"s) != set.end()) << '\\n' + << (set.find("one"sv) != set.end()) << '\\n'; + } + +.SH Possible output: + + Simple comparison demo: + Found 2 + Heterogeneous lookup for unordered containers (transparent hashing): + std::size_t string_hash::operator()(const char*) const + true + std::size_t string_hash::operator()(const std::string&) const + true + std::size_t string_hash::operator()(std::string_view) const + true .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::unordered_set::get_allocator.3 b/man/std::unordered_set::get_allocator.3 index 548e20437..055d40e43 100644 --- a/man/std::unordered_set::get_allocator.3 +++ b/man/std::unordered_set::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::unordered_set::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::get_allocator \- std::unordered_set::get_allocator + .SH Synopsis - allocator_type get_allocator() const; \fI(since C++11)\fP + allocator_type get_allocator() const noexcept; \fI(since C++11)\fP Returns the allocator associated with the container. diff --git a/man/std::unordered_set::hash_function.3 b/man/std::unordered_set::hash_function.3 index bf31e274b..4447a14a6 100644 --- a/man/std::unordered_set::hash_function.3 +++ b/man/std::unordered_set::hash_function.3 @@ -1,4 +1,7 @@ -.TH std::unordered_set::hash_function 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::hash_function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::hash_function \- std::unordered_set::hash_function + .SH Synopsis hasher hash_function() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also key_eq returns the function used to compare keys for equality - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::insert.3 b/man/std::unordered_set::insert.3 index f1491fa92..912aa0f42 100644 --- a/man/std::unordered_set::insert.3 +++ b/man/std::unordered_set::insert.3 @@ -1,26 +1,82 @@ -.TH std::unordered_set::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::insert \- std::unordered_set::insert + .SH Synopsis - std::pair insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP - std::pair insert( value_type&& value ); \fB(2)\fP \fI(since C++11)\fP - iterator insert( const_iterator hint, const value_type& value ); \fB(3)\fP \fI(since C++11)\fP - iterator insert( const_iterator hint, value_type&& value ); \fB(4)\fP \fI(since C++11)\fP - template< class InputIt > \fB(5)\fP \fI(since C++11)\fP + std::pair insert( const value_type& value ); \fB(1)\fP \fI(since C++11)\fP + std::pair insert( value_type&& value ); \fB(2)\fP \fI(since C++11)\fP + iterator insert( const_iterator hint, const value_type& value ); \fB(3)\fP \fI(since C++11)\fP + iterator insert( const_iterator hint, value_type&& value ); \fB(4)\fP \fI(since C++11)\fP + template< class InputIt > \fB(5)\fP \fI(since C++11)\fP void insert( InputIt first, InputIt last ); - void insert( std::initializer_list ilist ); \fB(6)\fP \fI(since C++11)\fP + void insert( std::initializer_list ilist ); \fB(6)\fP \fI(since C++11)\fP + insert_return_type insert( node_type&& nh ); \fB(7)\fP \fI(since C++17)\fP + iterator insert( const_iterator hint, node_type&& nh ); \fB(8)\fP \fI(since C++17)\fP + template< class K > \fB(9)\fP (since C++23) + std::pair insert( K&& obj ); + template< class K > \fB(10)\fP (since C++23) + iterator insert( const_iterator hint, K&& obj ); Inserts element(s) into the container, if the container doesn't already contain an element with an equivalent key. - 1-2) Inserts value. - 3-4) Inserts value, using hint as a non-binding suggestion to where the search + 1,2) Inserts value. + 3,4) Inserts value, using hint as a non-binding suggestion to where the search should start. - 5) Inserts elements from range [first, last). - 6) Inserts elements from initializer list ilist. - - If rehashing occurs due to the insertion, all iterators are invalidated. Otherwise - iterators are not affected. References are not invalidated. Rehashing occurs only if - the new number of elements is equal to or greater than - max_load_factor()*bucket_count(). + 5) Inserts elements from range [first, last). If multiple elements in the range have + keys that compare equivalent, it is unspecified which element is inserted (pending + LWG2844). + 6) Inserts elements from initializer list ilist. If multiple elements in the range + have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). + 7) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container , if the container doesn't already contain an element with + a key equivalent to nh.key(). The behavior is undefined if nh is not empty and + get_allocator() != nh.get_allocator(). + 8) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, if the container + doesn't already contain an element with a key equivalent to nh.key(), and returns + the iterator pointing to the element with key equivalent to nh.key()(regardless of + whether the insert succeeded or failed). If the insertion succeeds, nh is moved + from, otherwise it retains ownership of the element. hint is used as a non-binding + suggestion to where the search should start. The behavior is undefined if nh is not + empty and get_allocator() != nh.get_allocator(). + 9) If *this already contains an element which transparently compares equivalent to + obj, does nothing. Otherwise, constructs an object u of value_type with + std::forward(obj) and then inserts u into *this. If equal_range(u) != + hash_function()(obj) || contains(u) is true, the behavior is undefined. The + value_type must be EmplaceConstructible into unordered_set from + std::forward(obj). This overload participates in overload resolution only if + Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. + This assumes that such Hash is callable with both K and Key type, and that the + KeyEqual is transparent, which, together, allows calling this function without + constructing an instance of Key. + 10) If *this already contains an element which transparently compares equivalent to + obj, does nothing. + + Otherwise, constructs an object u of value_type with std::forward(obj) and then + inserts u into *this. Template:hint is used as a non-binding suggestion to where the + search should start. If equal_range(u) != hash_function()(obj) || contains(u) is + true, the behavior is undefined. The value_type must be EmplaceConstructible into + unordered_set from std::forward(obj). This overload participates in overload + resolution only if: + + * std::is_convertible_v and std::is_convertible_v are both false, and + * Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a + type. This assumes that such Hash is callable with both K and Key type, and that + the KeyEqual is transparent, + which, together, allows calling this function without constructing an instance of + Key. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters @@ -28,39 +84,130 @@ value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle + obj - a value of any type that can be transparently compared with a key .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-2) Returns a pair consisting of an iterator to the inserted element (or to the - element that prevented the insertion) and a bool denoting whether the insertion took - place. - 3-4) Returns an iterator to the inserted element, or to the element that prevented - the insertion. - 5-6) \fI(none)\fP + 1,2) A pair consisting of an iterator to the inserted element (or to the element + that prevented the insertion) and a bool value set to true if and only if the + insertion took place. + 3,4) An iterator to the inserted element, or to the element that prevented the + insertion. + 5,6) \fI(none)\fP + 7) An object of insert_return_type with the members initialized as follows: + * If nh is empty, inserted is false, position is end(), and node is empty. + * Otherwise if the insertion took place, inserted is true, position points to the + inserted element, and node is empty. + * If the insertion failed, inserted is false, node has the previous value of nh, + and position points to an element with a key equivalent to nh.key(). + 8) End iterator if nh was empty, iterator pointing to the inserted element if + insertion took place, and iterator pointing to an element with a key equivalent to + nh.key() if it failed. + 9) A pair consisting of an iterator to the inserted element (or to the element that + prevented the insertion) and a bool value set to true if and only if the insertion + took place. + 10) An iterator to the inserted element, or to the element that prevented the + insertion. .SH Exceptions 1-4) If an exception is thrown by any operation, the insertion has no effect. This section is incomplete - Reason: cases 5-6 + Reason: cases 5-10 .SH Complexity - 1-4) Average case: O(1), worst case O(size()) - 5-6) Average case: O(N), where N is the number of elements to insert. Worse case: - O(N*size()+N) + 1-4) Average case: O(1), worst case O(size()). + 5,6) Average case: O(N), where N is the number of elements to insert. Worst case: + O(N * size() + N). + 7-10) Average case: O(1), worst case O(size()). + +.SH Notes + + The hinted insert (3,4) does not return a boolean in order to be + signature-compatible with positional insert on sequential containers, such as + std::vector::insert. This makes it possible to create generic inserters such as + std::inserter. One way to check success of a hinted insert is to compare size() + before and after. + + Feature-test macro Value Std Feature + Heterogeneous + overloads for the + remaining member + __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered + and unordered + associative + containers. (9,10) + +.SH Example + + +// Run this code + + #include + #include + #include + + std::ostream& operator<<(std::ostream& os, std::unordered_set const& s) + { + for (os << '[' << s.size() << "] { "; int i : s) + os << i << ' '; + return os << "}\\n"; + } + + int main () + { + std::unordered_set nums{2, 3, 4}; + + std::cout << "1) Initially: " << nums << std::boolalpha; + auto p = nums.insert(1); // insert element, overload (1) + std::cout << "2) '1' was inserted: " << p.second << '\\n'; + std::cout << "3) After insertion: " << nums; + + nums.insert(p.first, 0); // insert with hint, overload (3) + std::cout << "4) After insertion: " << nums; + + std::array a = {10, 11, 12, 13}; + nums.insert(a.begin(), a.end()); // insert range, overload (5) + std::cout << "5) After insertion: " << nums; + + nums.insert({20, 21, 22, 23}); // insert initializer_list, (6) + std::cout << "6) After insertion: " << nums; + + std::unordered_set other_nums = {42, 43}; + auto node = other_nums.extract(other_nums.find(42)); + nums.insert(std::move(node)); // insert node, overload (7) + std::cout << "7) After insertion: " << nums; + + node = other_nums.extract(other_nums.find(43)); + nums.insert(nums.begin(), std::move(node)); // insert node with hint, (8) + std::cout << "8) After insertion: " << nums; + } + +.SH Possible output: + + 1) Initially: [3] { 4 3 2 } + 2) '1' was inserted: true + 3) After insertion: [4] { 1 2 3 4 } + 4) After insertion: [5] { 0 1 2 3 4 } + 5) After insertion: [9] { 13 12 11 10 4 3 2 1 0 } + 6) After insertion: [13] { 23 22 13 12 11 10 21 4 20 3 2 1 0 } + 7) After insertion: [14] { 42 23 22 13 12 11 10 21 4 20 3 2 1 0 } + 8) After insertion: [15] { 43 42 23 22 13 12 11 10 21 4 20 3 2 1 0 } .SH See also emplace constructs element in-place - \fI(public member function)\fP + \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(public member function)\fP + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP .SH Category: - * Todo with reason diff --git a/man/std::unordered_set::insert_range.3 b/man/std::unordered_set::insert_range.3 new file mode 100644 index 000000000..763e1cb9d --- /dev/null +++ b/man/std::unordered_set::insert_range.3 @@ -0,0 +1,78 @@ +.TH std::unordered_set::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::insert_range \- std::unordered_set::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg if and only if there is no element + with key equivalent to the key of that element in *this. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + If after the operation the new number of elements is greater than old + max_load_factor() * bucket_count() a rehashing takes place. + If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise + (no rehashing), iterators are not invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose + elements are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into unordered_set from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), where N is ranges::distance(rg), worst case O(N·(a.size() + 1)). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + + void println(auto, auto const& container) + { + for (const auto& elem : container) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::unordered_set{1, 3, 2, 4}; + const auto rg = {-1, 3, -2}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Possible output: + + 4 -1 2 3 -2 1 + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::key_eq.3 b/man/std::unordered_set::key_eq.3 index 0f457d152..a234389ec 100644 --- a/man/std::unordered_set::key_eq.3 +++ b/man/std::unordered_set::key_eq.3 @@ -1,4 +1,7 @@ -.TH std::unordered_set::key_eq 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::key_eq 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::key_eq \- std::unordered_set::key_eq + .SH Synopsis key_equal key_eq() const; \fI(since C++11)\fP @@ -19,4 +22,4 @@ .SH See also hash_function returns function used to hash the keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::load_factor.3 b/man/std::unordered_set::load_factor.3 index 5d3d01197..b277e7040 100644 --- a/man/std::unordered_set::load_factor.3 +++ b/man/std::unordered_set::load_factor.3 @@ -1,8 +1,12 @@ -.TH std::unordered_set::load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::load_factor \- std::unordered_set::load_factor + .SH Synopsis float load_factor() const; \fI(since C++11)\fP - Returns the average number of elements per bucket. + Returns the average number of elements per bucket, that is, size() divided by + bucket_count(). .SH Parameters @@ -19,4 +23,4 @@ .SH See also max_load_factor manages maximum average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::max_bucket_count.3 b/man/std::unordered_set::max_bucket_count.3 index be18f2dfa..e19376f3d 100644 --- a/man/std::unordered_set::max_bucket_count.3 +++ b/man/std::unordered_set::max_bucket_count.3 @@ -1,4 +1,7 @@ -.TH std::unordered_set::max_bucket_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::max_bucket_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::max_bucket_count \- std::unordered_set::max_bucket_count + .SH Synopsis size_type max_bucket_count() const; \fI(since C++11)\fP @@ -17,7 +20,41 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + struct Ha { std::size_t operator()(long x) const { return std::hash{}(x); }; }; + + auto c1 = std::unordered_set{}; + auto c2 = std::unordered_set{}; + auto c3 = std::unordered_set>{}; + auto c4 = std::unordered_set{}; + + std::cout + << "Max bucket count of\\n" << std::hex << std::showbase + << "c1: " << c1.max_bucket_count() << '\\n' + << "c2: " << c2.max_bucket_count() << '\\n' + << "c3: " << c3.max_bucket_count() << '\\n' + << "c4: " << c4.max_bucket_count() << '\\n' + ; + } + +.SH Possible output: + + Max bucket count of + c1: 0xfffffffffffffff + c2: 0xfffffffffffffff + c3: 0xfffffffffffffff + c4: 0xaaaaaaaaaaaaaaa + .SH See also bucket_count returns the number of buckets - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::max_load_factor.3 b/man/std::unordered_set::max_load_factor.3 index 37860a864..ec9cc3151 100644 --- a/man/std::unordered_set::max_load_factor.3 +++ b/man/std::unordered_set::max_load_factor.3 @@ -1,4 +1,7 @@ -.TH std::unordered_set::max_load_factor 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::max_load_factor 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::max_load_factor \- std::unordered_set::max_load_factor + .SH Synopsis float max_load_factor() const; \fB(1)\fP \fI(since C++11)\fP void max_load_factor( float ml ); \fB(2)\fP \fI(since C++11)\fP @@ -8,7 +11,6 @@ threshold. 1) Returns current maximum load factor. - 2) Sets the maximum load factor to ml. .SH Parameters @@ -17,15 +19,14 @@ .SH Return value - 1) current maximum load factor. - - 2) none. + 1) Current maximum load factor. + 2) \fI(none)\fP .SH Complexity - Constant + Constant. .SH See also load_factor returns average number of elements per bucket - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::max_size.3 b/man/std::unordered_set::max_size.3 index 8407c4820..44bdfc137 100644 --- a/man/std::unordered_set::max_size.3 +++ b/man/std::unordered_set::max_size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_set::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::max_size \- std::unordered_set::max_size + .SH Synopsis - size_type max_size() const; \fI(since C++11)\fP + size_type max_size() const noexcept; \fI(since C++11)\fP Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,24 +17,45 @@ Maximum number of elements. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::unordered_set p; + std::unordered_set q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + q.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::merge.3 b/man/std::unordered_set::merge.3 new file mode 100644 index 000000000..df68bf830 --- /dev/null +++ b/man/std::unordered_set::merge.3 @@ -0,0 +1,87 @@ +.TH std::unordered_set::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::merge \- std::unordered_set::merge + +.SH Synopsis + template< class H2, class P2 > \fB(1)\fP \fI(since C++17)\fP + void merge( std::unordered_set& source ); + template< class H2, class P2 > \fB(2)\fP \fI(since C++17)\fP + void merge( std::unordered_set&& source ); + template< class H2, class P2 > + void merge( std::unordered_multiset& \fB(3)\fP \fI(since C++17)\fP + source ); + template< class H2, class P2 > + void merge( std::unordered_multiset&& \fB(4)\fP \fI(since C++17)\fP + source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the hash function and key equality predicate of *this. If there is an element in + *this with key equivalent to the key of an element from source, then that element is + not extracted from source. No elements are copied or moved, only the internal + pointers of the container nodes are repointed. All pointers and references to the + transferred elements remain valid, but now refer into *this, not into source. + Iterators referring to the transferred elements and all iterators referring to *this + are invalidated. Iterators to elements remaining in source remain valid. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Average case O(N), worst case O(N * size() + N), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + + // print out a container + template + Os& operator<<(Os& os, const std::unordered_set& v) + { + os << '[' << v.size() << "] {"; + bool o{}; + for (const auto& e : v) + os << (o ? ", " : (o = 1, " ")) << e; + return os << " }\\n"; + } + + int main() + { + std::unordered_set + p{'C', 'B', 'B', 'A'}, + q{'E', 'D', 'E', 'C'}; + + std::cout << "p: " << p << "q: " << q; + + p.merge(q); + + std::cout << "p.merge(q);\\n" << "p: " << p << "q: " << q; + } + +.SH Possible output: + + p: [3] { A, B, C } + q: [3] { C, D, E } + p.merge(q); + p: [5] { E, D, A, B, C } + q: [1] { C } + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::unordered_set::operator=.3 b/man/std::unordered_set::operator=.3 index c39b3f333..f78117d44 100644 --- a/man/std::unordered_set::operator=.3 +++ b/man/std::unordered_set::operator=.3 @@ -1,28 +1,40 @@ -.TH std::unordered_set::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::operator= \- std::unordered_set::operator= + .SH Synopsis - unordered_set& operator=( const unordered_set& other ); \fB(1)\fP \fI(since C++11)\fP - unordered_set& operator=( unordered_set&& other ); \fB(2)\fP \fI(since C++11)\fP - unordered_set& operator=( std::initializer_list ilist \fB(3)\fP \fI(since C++11)\fP + unordered_set& operator=( const unordered_set& other \fB(1)\fP \fI(since C++11)\fP ); + unordered_set& operator=( unordered_set&& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + unordered_set& operator=( unordered_set&& other ) \fB(2)\fP \fI(since C++17)\fP + noexcept(/* see below */); + unordered_set& operator=( \fB(3)\fP \fI(since C++11)\fP + std::initializer_list ilist ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + If + std::allocator_traits::propagate_on_container_copy_assignment::value + is true, the allocator of *this is replaced by a copy of other. If the allocator of + *this after assignment would compare unequal to its old value, the old allocator is + used to deallocate the memory, then the new allocator is used to allocate it before + copying the elements. Otherwise, the memory owned by *this may be reused when + possible. In any case, the elements originally belonging to *this may be either + destroyed or replaced by element-wise copy-assignment. 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -36,66 +48,99 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + + && std::is_nothrow_move_assignable::value + + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::unordered_set to another: - The following code uses to assign one std::unordered_set to another: - // Run this code - #include + #include #include - - void display_sizes(const std::unordered_set &nums1, - const std::unordered_set &nums2, - const std::unordered_set &nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::unordered_set nums1 {3, 1, 4, 6, 5, 9}; - std::unordered_set nums2; - std::unordered_set nums3; - + std::unordered_set x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } -.SH Output: +.SH Possible output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 3, 2, 1 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 3, 2, 1 } + y = { 3, 2, 1 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 3, 2, 1 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 7, 6, 5, 4 } .SH See also constructor constructs the unordered_set - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_set::rehash.3 b/man/std::unordered_set::rehash.3 index 6b16a4c7c..d7e6058c0 100644 --- a/man/std::unordered_set::rehash.3 +++ b/man/std::unordered_set::rehash.3 @@ -1,16 +1,17 @@ -.TH std::unordered_set::rehash 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::rehash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::rehash \- std::unordered_set::rehash + .SH Synopsis void rehash( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to count and rehashes the container, i.e. puts the - elements into appropriate buckets considering that total number of buckets has - changed. If the new number of buckets makes load factor more than maximum load - factor (count < size() / max_load_factor()), then the new number of buckets is at - least size() / max_load_factor(). + Changes the number of buckets to a value n that is not less than count and satisfies + n >= size() / max_load_factor(), then rehashes the container, i.e. puts the elements + into appropriate buckets considering that total number of buckets has changed. .SH Parameters - count - new number of buckets + count - lower bound for the new number of buckets .SH Return value @@ -23,10 +24,10 @@ .SH Notes rehash\fB(0)\fP may be used to force an unconditional rehash, such as after suspension of - automatic rehashing by temporary increasing max_load_factor(). + automatic rehashing by temporarily increasing max_load_factor(). .SH See also - reserves space for at least the specified number of elements. - reserve This regenerates the hash table. - \fI(public member function)\fP + reserves space for at least the specified number of elements and regenerates + reserve the hash table + \fI(public member function)\fP diff --git a/man/std::unordered_set::reserve.3 b/man/std::unordered_set::reserve.3 index 853cd7689..d347831d2 100644 --- a/man/std::unordered_set::reserve.3 +++ b/man/std::unordered_set::reserve.3 @@ -1,8 +1,11 @@ -.TH std::unordered_set::reserve 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::reserve \- std::unordered_set::reserve + .SH Synopsis void reserve( size_type count ); \fI(since C++11)\fP - Sets the number of buckets to the number needed to accomodate at least count + Sets the number of buckets to the number needed to accommodate at least count elements without exceeding maximum load factor and rehashes the container, i.e. puts the elements into appropriate buckets considering that total number of buckets has changed. Effectively calls rehash(std::ceil(count / max_load_factor())). @@ -21,6 +24,6 @@ .SH See also - reserves at least the specified number of buckets. - rehash This regenerates the hash table. - \fI(public member function)\fP + reserves at least the specified number of buckets and regenerates the hash + rehash table + \fI(public member function)\fP diff --git a/man/std::unordered_set::size.3 b/man/std::unordered_set::size.3 index 8622e9d61..7605a55a9 100644 --- a/man/std::unordered_set::size.3 +++ b/man/std::unordered_set::size.3 @@ -1,6 +1,9 @@ -.TH std::unordered_set::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::size \- std::unordered_set::size + .SH Synopsis - size_type size() const; \fI(since C++11)\fP + size_type size() const noexcept; \fI(since C++11)\fP Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,27 @@ The number of elements in the container. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::unordered_set: - + // Run this code - #include #include - + #include + int main() { - std::unordered_set nums {1, 3, 5, 7}; - + std::unordered_set nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +46,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::unordered_set::swap.3 b/man/std::unordered_set::swap.3 index 7ee85b810..a50686a85 100644 --- a/man/std::unordered_set::swap.3 +++ b/man/std::unordered_set::swap.3 @@ -1,19 +1,24 @@ -.TH std::unordered_set::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::swap \- std::unordered_set::swap + .SH Synopsis - void swap( unordered_set& other ); \fI(since C++11)\fP + void swap( unordered_set& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + void swap( unordered_set& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. The Hash and KeyEqual objects must be Swappable, and they are exchanged using unqualified calls to non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +30,62 @@ .SH Exceptions - Any exception thrown by the swap Hash or KeyEqual objects. + Any exception thrown by the swap of the Hash or KeyEqual objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value + \fI(since C++17)\fP + && std::is_nothrow_swappable::value + + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + template Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::unordered_set a1{3, 1, 3, 2}, a2{5, 4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + const int& ref1 = *(a1.begin()); + const int& ref2 = *(a2.begin()); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that every iterator referring to an element in one container before the swap + // refers to the same element in the other container after the swap. Same is true + // for references. + } + +.SH Possible output: + + { 2 1 3 } { 4 5 } 1 5 2 4 + { 4 5 } { 2 1 3 } 1 5 2 4 + .SH See also std::swap(std::unordered_set) specializes the std::swap algorithm - \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::unordered_set::unordered_set.3 b/man/std::unordered_set::unordered_set.3 index 236c00568..6137289de 100644 --- a/man/std::unordered_set::unordered_set.3 +++ b/man/std::unordered_set::unordered_set.3 @@ -1,89 +1,148 @@ -.TH std::unordered_set::unordered_set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::unordered_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::unordered_set \- std::unordered_set::unordered_set + .SH Synopsis - explicit unordered_set( size_type bucket_count = - /*implementation-defined*/, + unordered_set() \fI(since C++11)\fP + : unordered_set(size_type(/* implementation-defined */)) \fI(until C++20)\fP + {} + unordered_set(); \fI(since C++20)\fP + explicit unordered_set( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++11)\fP - const KeyEqual& equal = KeyEqual(), \fI(until C++14)\fP + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), \fB(2)\fP \fI(since C++11)\fP const Allocator& alloc = Allocator() ); - unordered_set : unordered_set( - size_type(/*implementation-defined*/) {} + unordered_set( size_type bucket_count, - explicit unordered_set( size_type bucket_count, - const Hash& hash = Hash(), \fI(since C++14)\fP - const KeyEqual& equal = KeyEqual(), + const Allocator& alloc ) \fB(3)\fP \fI(since C++14)\fP - const Allocator& alloc = Allocator() - ); + : unordered_set(bucket_count, Hash(), key_equal(), alloc) + {} unordered_set( size_type bucket_count, - const Allocator& alloc = Allocator() - ); - unordered_set( size_type bucket_count, \fB(1)\fP \fI(since C++14)\fP - const Hash& hash, + const Hash& hash, + const Allocator& alloc ) \fB(4)\fP \fI(since C++14)\fP - const Allocator& alloc = Allocator() - ); - explicit unordered_set( const Allocator& alloc ); \fB(1)\fP \fI(since C++11)\fP + : unordered_set(bucket_count, hash, key_equal(), alloc) + {} + explicit unordered_set( const Allocator& alloc ); \fB(5)\fP \fI(since C++11)\fP template< class InputIt > unordered_set( InputIt first, InputIt last, - size_type bucket_count = - /*implementation-defined*/, - const Hash& hash = Hash(), \fB(1)\fP - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - template< class InputIt > \fB(2)\fP - unordered_set( InputIt first, InputIt last, \fI(since C++14)\fP - size_type bucket_count, + size_type bucket_count = /* + implementation-defined */, \fB(6)\fP \fI(since C++11)\fP + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); template< class InputIt > + unordered_set( InputIt first, InputIt last, size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(7)\fP \fI(since C++14)\fP + : unordered_set(first, last, - const Allocator& alloc = Allocator() ); - unordered_set( const unordered_set& other ); \fB(3)\fP \fI(since C++11)\fP - unordered_set( const unordered_set& other, const Allocator& \fB(3)\fP \fI(since C++11)\fP + bucket_count, Hash(), key_equal(), alloc) + {} + template< class InputIt > + + unordered_set( InputIt first, InputIt last, + size_type bucket_count, + const Hash& hash, \fB(8)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_set(first, last, + + bucket_count, hash, key_equal(), alloc) + {} + unordered_set( const unordered_set& other ); \fB(9)\fP \fI(since C++11)\fP + unordered_set( const unordered_set& other, const Allocator& \fB(1)\fP \fB(10)\fP \fI(since C++11)\fP alloc ); - unordered_set( unordered_set&& other ); \fB(4)\fP \fI(since C++11)\fP - unordered_set( unordered_set&& other, const Allocator& alloc \fB(4)\fP \fI(since C++11)\fP + unordered_set( unordered_set&& other ); \fB(11)\fP \fI(since C++11)\fP + unordered_set( unordered_set&& other, const Allocator& alloc \fB(12)\fP \fI(since C++11)\fP ); unordered_set( std::initializer_list init, - size_type bucket_count = - /*implementation-defined*/, + size_type bucket_count = /* + implementation-defined */, \fB(13)\fP \fI(since C++11)\fP const Hash& hash = Hash(), - const KeyEqual& equal = KeyEqual(), - const Allocator& alloc = Allocator() ); \fI(since C++11)\fP - unordered_set( std::initializer_list init, \fB(5)\fP - size_type bucket_count, \fI(since C++14)\fP + const key_equal& equal = key_equal(), + const Allocator& alloc = Allocator() ); unordered_set( std::initializer_list init, + size_type bucket_count, - const Hash& hash, + const Allocator& alloc ) \fB(14)\fP \fI(since C++14)\fP + : unordered_set(init, bucket_count, + + Hash(), key_equal(), alloc) {} + unordered_set( std::initializer_list init, + + size_type bucket_count, + const Hash& hash, \fB(15)\fP \fI(since C++14)\fP + const Allocator& alloc ) + : unordered_set(init, bucket_count, + + hash, key_equal(), alloc) {} + template< container-compatible-range R > + + unordered_set( std::from_range_t, R&& rg, + size_type bucket_count = /* see description + */, \fB(16)\fP (since C++23) + const Hash& hash = Hash(), + const key_equal& equal = key_equal(), const Allocator& alloc = Allocator() ); + template< container-compatible-range R > + + unordered_set( std::from_range_t, R&& rg, + size_type bucket_count, + const Allocator& alloc ) \fB(17)\fP (since C++23) + : unordered_set(std::from_range, std::forward(rg), + + bucket_count, Hash(), key_equal(), alloc) + {} + template< container-compatible-range R > + + unordered_set( std::from_range_t, R&& rg, + size_type bucket_count, + const Hash& hash, \fB(18)\fP (since C++23) + const Alloc& alloc ) + : unordered_set(std::from_range, std::forward(rg), + + bucket_count, hash, key_equal(), alloc) + {} Constructs new container from a variety of data sources. Optionally uses user supplied bucket_count as a minimal number of buckets to create, hash as the hash function, equal as the function to compare keys and alloc as the allocator. - 1) Constructs empty container. Sets max_load_factor() to 1.0. For the default + 1-5) Constructs empty container. Sets max_load_factor() to 1.0. For the default constructor, the number of buckets is implementation-defined. - 2) constructs the container with the contents of the range [first, last). Sets - max_load_factor() to 1.0. - 3) copy constructor. Constructs the container with the copy of the contents of + 6-8) Constructs the container with the contents of the range [first, last). Sets + max_load_factor() to 1.0. If multiple elements in the range have keys that compare + equivalent, it is unspecified which element is inserted (pending LWG2844). + 9,10) Copy constructor. Constructs the container with the copy of the contents of other, copies the load factor, the predicate, and the hash function as well. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). - 4) move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 5) constructs the container with the contents of the initializer list init, same as - unordered_set(init.begin(), init.end()). + std::allocator_traits::select_on_container_copy_construction(other.get_allocator()). + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 11,12) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. + + The template parameter Allocator is only deduced from the first (since C++23) + argument while used in class template argument deduction. + + 13-15) Initializer-list constructor. Constructs the container with the contents of + the initializer list init, same as unordered_set(init.begin(), init.end()). + 16-18) Constructs the container with the contents of rg. If multiple elements in the + range have keys that compare equivalent, it is unspecified which element is inserted + (pending LWG2844). .SH Parameters @@ -92,32 +151,63 @@ specified, implementation-defined default value is used hash - hash function to use equal - comparison function to use for all key comparisons of this container - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Complexity - 1) constant - 2) average case linear worst case quadratic in distance between first and last - 3) linear in size of other - 4) constant. If alloc is given and alloc != other.get_allocator(), then linear. - 5) average case linear worst case quadratic in size of init + 1-5) Constant. + 6-8) Average case linear (i.e. O(N), where N is std::distance(first, last)), worst + case quadratic, i.e. O(N^2). + 9,10) Linear in size of other. + 11,12) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 13-15) Average case O(N) (N is std::size(init)), worst case O(N^2). + 16-18) Average case O(N) (N is ranges::distance(rg)), worst case O(N^2). + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + + After container move construction (overload \fB(4)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Although not formally required until C++23, some implementations have already put + the template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (16-18) .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2193 C++11 the default constructor (1) was explicit made non-explicit + .SH See also operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::unordered_set::~unordered_set.3 b/man/std::unordered_set::~unordered_set.3 index ddca4989d..4e72d50fb 100644 --- a/man/std::unordered_set::~unordered_set.3 +++ b/man/std::unordered_set::~unordered_set.3 @@ -1,11 +1,14 @@ -.TH std::unordered_set::~unordered_set 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::unordered_set::~unordered_set 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unordered_set::~unordered_set \- std::unordered_set::~unordered_set + .SH Synopsis ~unordered_set(); \fI(since C++11)\fP - Destructs the container. The destructors of the elements are called and the used + Destructs the unordered_set. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the unordered_set. diff --git a/man/std::unreachable.3 b/man/std::unreachable.3 new file mode 100644 index 000000000..dd1969414 --- /dev/null +++ b/man/std::unreachable.3 @@ -0,0 +1,87 @@ +.TH std::unreachable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unreachable \- std::unreachable + +.SH Synopsis + Defined in header + [[noreturn]] void unreachable(); (since C++23) + + Invokes undefined behavior. An implementation may use this to optimize impossible + code branches away (typically, in optimized builds) or to trap them to prevent + further execution (typically, in debug builds). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_unreachable 202202L (C++23) std::unreachable + +.SH Possible implementation + + [[noreturn]] inline void unreachable() + { + // Uses compiler specific extensions if possible. + // Even if no extension is used, undefined behavior is still raised by + // an empty function body and the noreturn attribute. + #if defined(_MSC_VER) && !defined(__clang__) // MSVC + __assume(false); + #else // GCC, Clang + __builtin_unreachable(); + #endif + } + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct Color { std::uint8_t r, g, b, a; }; + + // Assume that only restricted set of texture caps is supported. + void generate_texture(std::vector& tex, std::size_t xy) + { + switch (xy) + { + case 128: [[fallthrough]]; + case 256: [[fallthrough]]; + case 512: /* ... */ + tex.clear(); + tex.resize(xy * xy, Color{0, 0, 0, 0}); + break; + default: + std::unreachable(); + } + } + + int main() + { + std::vector tex; + generate_texture(tex, 128); // OK + assert(tex.size() == 128 * 128); + generate_texture(tex, 32); // Results in undefined behavior + } + +.SH Possible output: + + Segmentation fault + +.SH See also + + specifies that the expression will always evaluate to + [[assume(expression)]](C++23) true at a given point + (attribute specifier) + assume_aligned informs the compiler that a pointer is aligned + (C++20) \fI(function template)\fP + C documentation for + unreachable + + External Links + + 1. GCC docs: __builtin_unreachable + 2. Clang docs: __builtin_unreachable + 3. MSVC docs: __assume diff --git a/man/std::unreachable_sentinel_t,std::unreachable_sentinel.3 b/man/std::unreachable_sentinel_t,std::unreachable_sentinel.3 new file mode 100644 index 000000000..bdcd3cc3d --- /dev/null +++ b/man/std::unreachable_sentinel_t,std::unreachable_sentinel.3 @@ -0,0 +1,76 @@ +.TH std::unreachable_sentinel_t,std::unreachable_sentinel 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unreachable_sentinel_t,std::unreachable_sentinel \- std::unreachable_sentinel_t,std::unreachable_sentinel + +.SH Synopsis + Defined in header + struct unreachable_sentinel_t; \fB(1)\fP \fI(since C++20)\fP + inline constexpr unreachable_sentinel_t unreachable_sentinel{}; \fB(2)\fP \fI(since C++20)\fP + + 1) unreachable_sentinel_t is an empty class type that can be used to denote the + “upper bound” of an unbounded interval. + 2) unreachable_sentinel is a constant of type unreachable_sentinel_t. + +.SH Non-member functions + + operator== compares an unreachable_sentinel_t with a value of any + (C++20) weakly_incrementable type + \fI(function template)\fP + +operator==(std::unreachable_sentinel_t) + + template + + friend constexpr bool operator==( unreachable_sentinel_t, const I& ) \fI(since C++20)\fP + noexcept + + { return false; } + + unreachable_sentinel_t can be compared with any weakly_incrementable type and the + result is always false. + + This function template is not visible to ordinary unqualified or qualified lookup, + and can only be found by argument-dependent lookup when std::unreachable_sentinel_t + is an associated class of the arguments. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + constexpr std::size_t strlen(const CharT *s) + { + return std::ranges::find(s, std::unreachable_sentinel, CharT{}) - s; + } + + template + constexpr std::size_t pos(const CharT *haystack, const CharT *needle) + { + // search(begin, unreachable_sentinel) is usually more efficient than + // search(begin, end) due to one less comparison per cycle. + // But "needle" MUST BE in the "haystack", otherwise the call is UB, + // which is a compile-time error in constexpr context. + return std::ranges::search( + haystack, std::unreachable_sentinel, + needle, needle + strlen(needle) + ).begin() - haystack; + } + + int main() + { + static_assert(strlen("The quick brown fox jumps over the lazy dog.") == 44); + static_assert(pos("const short int", "short") == 6); + // static_assert(pos("long int", "float")); // compile-time error + } + +.SH See also + + ranges::iota_view a view consisting of a sequence generated by repeatedly + views::iota incrementing an initial value + (C++20) \fI(class template)\fP (customization point object) diff --git a/man/std::unsigned_integral.3 b/man/std::unsigned_integral.3 new file mode 100644 index 000000000..d97df8291 --- /dev/null +++ b/man/std::unsigned_integral.3 @@ -0,0 +1,67 @@ +.TH std::unsigned_integral 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unsigned_integral \- std::unsigned_integral + +.SH Synopsis + Defined in header + template< class T > + concept unsigned_integral = std::integral && \fI(since C++20)\fP + !std::signed_integral; + + The concept unsigned_integral is satisfied if and only if T is an integral type + and std::is_signed_v is false. + +.SH Notes + + unsigned_integral may be satisfied by a type that is not an unsigned integer + type, for example, bool. + +.SH Example + + +// Run this code + + #include + #include + #include + + void test(std::signed_integral auto x, std::string_view text = "") + { + std::cout << text << " (" + (text == "") << x << ") is a signed integral\\n"; + } + + void test(std::unsigned_integral auto x, std::string_view text = "") + { + std::cout << text << " (" + (text == "") << x << ") is an unsigned integral\\n"; + } + + void test(auto x, std::string_view text = "") + { + std::cout << text << " (" + (text == "") << x << ") is non-integral\\n"; + } + + int main() + { + test(42); // signed + test(0xFULL, "0xFULL"); // unsigned + test('A'); // platform-dependent + test(true, "true"); // unsigned + test(4e-2, "4e-2"); // non-integral (hex-float) + test("∫∫"); // non-integral + } + +.SH Possible output: + + \fB(42)\fP is a signed integral + 0xFULL \fB(15)\fP is an unsigned integral + (A) is a signed integral + true \fB(1)\fP is an unsigned integral + 4e-2 (0.04) is non-integral + (∫∫) is non-integral + +.SH See also + + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP + is_signed checks if a type is a signed arithmetic type + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::unwrap_reference,std::unwrap_ref_decay.3 b/man/std::unwrap_reference,std::unwrap_ref_decay.3 new file mode 100644 index 000000000..84cd720d1 --- /dev/null +++ b/man/std::unwrap_reference,std::unwrap_ref_decay.3 @@ -0,0 +1,126 @@ +.TH std::unwrap_reference,std::unwrap_ref_decay 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::unwrap_reference,std::unwrap_ref_decay \- std::unwrap_reference,std::unwrap_ref_decay + +.SH Synopsis + Defined in header + Defined in header + template< class T > \fB(1)\fP \fI(since C++20)\fP + struct unwrap_reference; + template< class T > \fB(2)\fP \fI(since C++20)\fP + struct unwrap_ref_decay; + + 1) If T is std::reference_wrapper for some type U, provides a member type alias + type that names U&; otherwise, provides a member type alias type that names T. + 2) If T is std::reference_wrapper for some type U, ignoring cv-qualification and + referenceness, provides a member type alias type that names U&; otherwise, provides + a member type alias type that names std::decay_t. + + If the program adds specializations for any of the templates described on this page, + the behavior is undefined. + +.SH Member types + + Name Definition + \fB(1)\fP U& if T is std::reference_wrapper; T otherwise + type \fB(2)\fP U& if std::decay_t is std::reference_wrapper; std::decay_t + otherwise + +.SH Helper types + + template \fB(1)\fP \fI(since C++20)\fP + using unwrap_reference_t = unwrap_reference::type; + template \fB(2)\fP \fI(since C++20)\fP + using unwrap_ref_decay_t = unwrap_ref_decay::type; + +.SH Possible implementation + + template + struct unwrap_reference { using type = T; }; + template + struct unwrap_reference> { using type = U&; }; + + template + struct unwrap_ref_decay : std::unwrap_reference> {}; + +.SH Notes + + std::unwrap_ref_decay performs the same transformation as used by std::make_pair and + std::make_tuple. + + Feature-test macro Value Std Feature + __cpp_lib_unwrap_ref 201811L (C++20) std::unwrap_ref_decay and std::unwrap_reference + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, const int>); + static_assert(std::is_same_v, int&>); + static_assert(std::is_same_v, int&&>); + static_assert(std::is_same_v, int*>); + + { + using T = std::reference_wrapper; + using X = std::unwrap_reference_t; + static_assert(std::is_same_v); + } + { + using T = std::reference_wrapper; + using X = std::unwrap_reference_t; + static_assert(std::is_same_v); + } + + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, int>); + static_assert(std::is_same_v, int>); + + { + using T = std::reference_wrapper; + using X = std::unwrap_ref_decay_t; + static_assert(std::is_same_v); + } + + { + auto reset = [](T&& z) + { + // x = 0; // Error: does not work if T is reference_wrapper<> + // converts T&& into T& for ordinary types + // converts T&& into U& for reference_wrapper + decltype(auto) r = std::unwrap_reference_t(z); + std::cout << "r: " << r << '\\n'; + r = 0; // OK, r has reference type + }; + + int x = 1; + reset(x); + assert(x == 0); + + int y = 2; + reset(std::ref(y)); + assert(y == 0); + } + } + +.SH Output: + + r: 1 + r: 2 + +.SH See also + + reference_wrapper CopyConstructible and CopyAssignable reference wrapper + \fI(C++11)\fP \fI(class template)\fP + make_pair creates a pair object of type, defined by the argument types + \fI(function template)\fP + make_tuple creates a tuple object of the type defined by the argument types + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::upper_bound.3 b/man/std::upper_bound.3 index ae7e0a7aa..9b653b9d1 100644 --- a/man/std::upper_bound.3 +++ b/man/std::upper_bound.3 @@ -1,127 +1,274 @@ -.TH std::upper_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::upper_bound \- std::upper_bound + .SH Synopsis Defined in header - template< class ForwardIt, class T > \fB(1)\fP - ForwardIt upper_bound( ForwardIt first, ForwardIt last, const T& value ); - template< class ForwardIt, class T, class Compare > - ForwardIt upper_bound( ForwardIt first, ForwardIt last, const T& value, Compare \fB(2)\fP - comp ); + template< class ForwardIt, class T > + (constexpr since + ForwardIt upper_bound( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value ); + template< class ForwardIt, class T = + typename std::iterator_traits + + + ::value_type > (since C++26) + constexpr ForwardIt upper_bound( ForwardIt + first, ForwardIt last, + + const T& + value ); + template< class ForwardIt, class T, class + Compare > \fB(1)\fP + (constexpr since + ForwardIt upper_bound( ForwardIt first, C++20) + ForwardIt last, (until C++26) + + const T& value, + Compare comp ); + template< class ForwardIt, class T = + typename std::iterator_traits \fB(2)\fP - Returns an iterator pointing to the first element in the range [first, last) that is - greater than value. - The range [first, last) must be at least partially ordered, i.e. partitioned with - respect to the expression !(value < element) or !comp(value, element). A - fully-sorted range meets this criteria, as does a range resulting from a call to - std::partition. + ::value_type, + class Compare > (since C++26) + constexpr ForwardIt upper_bound( ForwardIt + first, ForwardIt last, - The first version uses operator< to compare the elements, the second version uses - the given comparison function comp. + const T& + value, Compare comp ); + + Searches for the first element in the partitioned range [first, last) which is + ordered after value. + + 1) The order is determined by operator<: + + Returns the first iterator iter in [first, last) where bool(value < + *iter) is true, or last if no such iter exists. + \fI(until C++20)\fP + If the elements elem of [first, last) are not partitioned with respect + to the expression bool(value < elem), the behavior is undefined. + Equivalent to std::upper_bound(first, last, value, std::less{}). \fI(since C++20)\fP + + 2) The order is determined by comp: + Returns the first iterator iter in [first, last) where bool(comp(value, *iter)) is + true, or last if no such iter exists. + If the elements elem of [first, last) are not partitioned with respect to the + expression bool(comp(value, elem)), the behavior is undefined. .SH Parameters - first, last - the range of elements to examine + first, last - the partitioned range of elements to examine value - value to compare the elements to - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + binary predicate which returns true if the first argument is ordered + before the second. - The signature of the comparison function should be equivalent to the + The signature of the predicate function should be equivalent to the following: - comp - bool cmp(const Type1 &a, const Type2 &b); + bool pred(const Type1 &a, const Type2 &b); - The signature does not need to have const &, but the function object - must not modify the objects passed to it. + comp - While the signature does not need to have const &, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1 & is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). The type Type1 must be such that an object of type T can be implicitly converted to Type1. The type Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to Type2. - + .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + ForwardIt must meet the requirements of LegacyForwardIterator. + - + Compare must meet the requirements of BinaryPredicate. It is not required to satisfy + Compare. .SH Return value - iterator pointing to the first element that is greater than value, or last if no - such element is found. + Iterator to the first element of the range [first, last) ordered after value, or + last if no such element is found. + +.SH Complexity + + Given \\(\\scriptsize N\\)N as std::distance(first, last): + + 1) At most \\(\\scriptsize \\log_{2}(N)+O(1)\\)log + 2(N)+O(1) comparisons with value using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) At most \\(\\scriptsize \\log_{2}(N)+O(1)\\)log + 2(N)+O(1) applications of the comparator comp. + + However, if ForwardIt is not a LegacyRandomAccessIterator, the number of iterator + increments is linear in \\(\\scriptsize N\\)N. Notably, std::map, std::multimap, + std::set, and std::multiset iterators are not random access, and so their member + upper_bound functions should be preferred. .SH Possible implementation -.SH First version - template - ForwardIt upper_bound(ForwardIt first, ForwardIt last, - const T& value) - { - ForwardIt it; - typename std::iterator_traits::distance_type count, step; - count = std::distance(first,last); - - while (count > 0) { - it = first; - step = count / 2; - std::advance(it, step); - if (!(value < *it)) { - first = ++it; - count -= step + 1; - } else count = step; - } - return first; - } -.SH Second version - template - ForwardIt upper_bound(ForwardIt first, ForwardIt last, - const T& value, Compare comp) - { - ForwardIt it; - typename std::iterator_traits::distance_type count, step; - count = std::distance(first,last); - - while (count > 0) { - it = first; - step = count / 2; - std::advance(it, step); - if (!comp(value, *it)) { - first = ++it; - count -= step + 1; - } else count = step; - } - return first; - } + See also the implementations in libstdc++ and libc++. + + upper_bound \fB(1)\fP + template::value_type> + ForwardIt upper_bound(ForwardIt first, ForwardIt last, const T& value) + { + return std::upper_bound(first, last, value, std::less{}); + } + upper_bound \fB(2)\fP + template::value_type, + class Compare> + ForwardIt upper_bound(ForwardIt first, ForwardIt last, const T& value, Compare comp) + { + ForwardIt it; + typename std::iterator_traits::difference_type count, step; + count = std::distance(first, last); + + while (count > 0) + { + it = first; + step = count / 2; + std::advance(it, step); + + if (!comp(value, *it)) + { + first = ++it; + count -= step + 1; + } + else + count = step; + } + + return first; + } + +.SH Notes + + Although std::upper_bound only requires [first, last) to be partitioned, this + algorithm is usually used in the case where [first, last) is sorted, so that the + binary search is valid for any value. + + For any iterator iter in [first, last), std::upper_bound requires value < *iter and + comp(value, *iter) to be well-formed, while std::lower_bound requires *iter < value + and comp(*iter, value) to be well-formed instead. + + Feature-test macro Value Std Feature + __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for + algorithms (1,2) .SH Example - + // Run this code #include + #include + #include #include - #include #include - + + struct PriceInfo { double price; }; + int main() { - std::vector data = { 1, 1, 2, 3, 3, 3, 3, 4, 4, 4, 5, 5, 6 }; - - auto lower = std::lower_bound(data.begin(), data.end(), 4); - auto upper = std::upper_bound(data.begin(), data.end(), 4); - - std::copy(lower, upper, std::ostream_iterator(std::cout, " ")); + const std::vector data{1, 2, 4, 5, 5, 6}; + + for (int i = 0; i < 7; ++i) + { + // Search first element that is greater than i + auto upper = std::upper_bound(data.begin(), data.end(), i); + + std::cout << i << " < "; + upper != data.end() + ? std::cout << *upper << " at index " << std::distance(data.begin(), upper) + : std::cout << "not found"; + std::cout << '\\n'; + } + + std::vector prices{{100.0}, {101.5}, {102.5}, {102.5}, {107.3}}; + + for (double to_find : {102.5, 110.2}) + { + auto prc_info = std::upper_bound(prices.begin(), prices.end(), to_find, + [](double value, const PriceInfo& info) + { + return value < info.price; + }); + + prc_info != prices.end() + ? std::cout << prc_info->price << " at index " << prc_info - prices.begin() + : std::cout << to_find << " not found"; + std::cout << '\\n'; + } + + using CD = std::complex; + std::vector nums{{1, 0}, {2, 2}, {2, 1}, {3, 0}, {3, 1}}; + auto cmpz = [](CD x, CD y) { return x.real() < y.real(); }; + #ifdef __cpp_lib_algorithm_default_value_type + auto it = std::upper_bound(nums.cbegin(), nums.cend(), {2, 0}, cmpz); + #else + auto it = std::upper_bound(nums.cbegin(), nums.cend(), CD{2, 0}, cmpz); + #endif + assert((*it == CD{3, 0})); } .SH Output: - 4 4 4 + 0 < 1 at index 0 + 1 < 2 at index 1 + 2 < 4 at index 2 + 3 < 4 at index 2 + 4 < 5 at index 3 + 5 < 6 at index 5 + 6 < not found + 107.3 at index 4 + 110.2 not found -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - logarithmic in the distance between first and last + DR Applied to Behavior as published Correct behavior + Compare was required to satisfy only a partitioning is required; + LWG 270 C++98 Compare and T was required heterogeneous comparisons + to be LessThanComparable permitted + (strict weak ordering required) + at most \\(\\scriptsize corrected to \\(\\scriptsize + LWG 384 C++98 \\log(N)+1\\)log \\log_{2}(N)+O(1)\\)log + 2(N)+1 comparisons were allowed 2(N)+O(1) + LWG 577 C++98 last could not be returned allowed + if any iterator iter exists in + [first, last) such that + LWG 2150 C++98 bool(comp(value, *iter)) is no iterator after + true, std::lower_bound iter can be returned + could return any iterator in + [iter, last) .SH See also - equal_range returns range of elements matching a specific key - \fI(function template)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(function template)\fP - partition divides a range of elements into two groups - \fI(function template)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP + returns an iterator to the first element not less than the given + lower_bound value + \fI(function template)\fP + partition divides a range of elements into two groups + \fI(function template)\fP + partition_point locates the partition point of a partitioned range + \fI(C++11)\fP \fI(function template)\fP + ranges::upper_bound returns an iterator to the first element greater than a certain + (C++20) value + (niebloid) + returns an iterator to the first element greater than the given + upper_bound key + \fI(public member function of std::set)\fP + + returns an iterator to the first element greater than the given + upper_bound key + \fI(public member function of std::multiset)\fP + diff --git a/man/std::uppercase,std::nouppercase.3 b/man/std::uppercase,std::nouppercase.3 index 8a545fa4b..799877dca 100644 --- a/man/std::uppercase,std::nouppercase.3 +++ b/man/std::uppercase,std::nouppercase.3 @@ -1,4 +1,7 @@ -.TH std::uppercase,std::nouppercase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uppercase,std::nouppercase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uppercase,std::nouppercase \- std::uppercase,std::nouppercase + .SH Synopsis Defined in header std::ios_base& uppercase( std::ios_base& str ); \fB(1)\fP @@ -7,11 +10,10 @@ Enables the use of uppercase characters in floating-point and hexadecimal integer output. Has no effect on input. - 1) enables the uppercase flag in the stream str as if by calling - str.setf(std::ios_base::uppercase) - - 2) disables the uppercase flag in the stream str as if by calling - str.unsetf(std::ios_base::uppercase) + 1) Enables the uppercase flag in the stream str as if by calling + str.setf(std::ios_base::uppercase). + 2) Disables the uppercase flag in the stream str as if by calling + str.unsetf(std::ios_base::uppercase). This is an I/O manipulator, it may be called with an expression such as out << std::uppercase for any out of type std::basic_ostream or with an expression such as @@ -23,14 +25,15 @@ .SH Return value - str (reference to the stream after manipulation) + str (reference to the stream after manipulation). .SH Example - + // Run this code #include + int main() { std::cout << std::hex << std::showbase @@ -50,6 +53,6 @@ .SH See also resetiosflags clears the specified ios_base flags - \fI(function)\fP + \fI(function)\fP setiosflags sets the specified ios_base flags - \fI(function)\fP + \fI(function)\fP diff --git a/man/std::use_facet.3 b/man/std::use_facet.3 index 617a153c7..b991d98f6 100644 --- a/man/std::use_facet.3 +++ b/man/std::use_facet.3 @@ -1,4 +1,7 @@ -.TH std::use_facet 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::use_facet 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::use_facet \- std::use_facet + .SH Synopsis Defined in header template< class Facet > @@ -6,43 +9,78 @@ Obtains a reference to a facet implemented by loc. + The program is ill-formed if Facet is not a facet whose definition contains the + public static member id or it is a volatile-qualified facet. + .SH Parameters loc - the locale object to query .SH Return value - Returns a reference the facet. The reference returned by this function is valid as - long as any std::locale object exists that implements Facet. + Returns a reference to the facet. The reference returned by this function is valid + as long as any std::locale object refers to that facet. .SH Exceptions std::bad_cast if std::has_facet(loc) == false. +.SH Notes + + A std::locale object should not be a temporary if a reference to the Facet object + obtained from use_facet is used after the end of statement: + + // BAD: + auto& f = std::use_facet>(std::locale{"no_NO.UTF-8"}); + foo(f.curr_symbol()); // Error: f internally uses a dangling reference + // to a std::locale object that no longer exists. + // GOOD: + auto loc = std::locale{"is_IS.UTF-8"}; // OK: a non-temporary object + auto& f = std::use_facet>(loc); + foo(f.curr_symbol()); // OK: f internally uses a reference to existing locale object. + .SH Example - Display the 3-letter currency name used by the user's preferred locale + Display the 3-letter currency name used by the user's preferred locale. + - // Run this code #include #include - + int main() { - std::locale loc = std::locale(""); // user's preferred locale - std::cout << "Your currency string is " - << std::use_facet>(loc).curr_symbol() << '\\n'; + for (const char* name: {"en_US.UTF-8", "de_DE.UTF-8", "en_GB.UTF-8"}) + std::cout << "Your currency string is " + << std::use_facet>(std::locale{name}). + curr_symbol() << '\\n'; } .SH Output: Your currency string is USD + Your currency string is EUR + Your currency string is GBP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the returned reference the returned reference remains + LWG 31 C++98 remained usable usable as + as long as the locale value long as some locale object refers to + itself exists that facet + LWG 38 C++98 Facet was not required to required + have a direct member id + LWG 436 C++98 it was unclear whether Facet it can be const-qualified, but not + can be cv-qualified volatile-qualified .SH See also locale set of polymorphic facets that encapsulate cultural differences - \fI(class)\fP + \fI(class)\fP has_facet checks if a locale implements a specific facet - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 index 8468124f9..328abad5c 100644 --- a/man/std::uses_allocator.3 +++ b/man/std::uses_allocator.3 @@ -1,21 +1,28 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::uses_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uses_allocator \- std::uses_allocator + .SH Synopsis - Defined in header - template< class T, class Alloc > \fI(since C++11)\fP - struct uses_allocator + Defined in header + template< class... Types, class Alloc > + struct uses_allocator< std::tuple, Alloc > : std::true_type \fI(since C++11)\fP + { }; - If T has a member typedef allocator_type which is convertible from Alloc, provides - the member constant value equal to true. Otherwise value is false. + This specialization of std::uses_allocator informs other library components that + tuples support uses-allocator construction, even though they do not have a nested + allocator_type. .SH Member constants - value true if T uses allocator Alloc, false otherwise + value true \fB[static]\fP \fI(public static member constant)\fP .SH Member functions operator bool converts the object to bool, returns value \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP .SH Member types @@ -23,55 +30,21 @@ value_type bool type std::integral_constant -.SH Specializations - - Custom specializations of the type trait std::uses_allocator are allowed for types - that do not have the member typedef allocator_type but satisfy one of the following - two requirements: - - 1) T has a constructor which takes std::allocator_arg_t as the first argument, and - Alloc as the second argument. - - 2) T has a constructor which takes Alloc as the last argument. - - The following specializations are already provided by the standard library: +.SH Example - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(class template specialization)\fP - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(function template)\fP - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(function template)\fP - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(function template)\fP - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(class template specialization)\fP - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(class template specialization)\fP - std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(class template specialization)\fP + // myalloc is a stateful Allocator with a single-argument constructor + // that takes an int. It has no default constructor. -.SH Notes + using innervector_t = std::vector>; + using elem_t = std::tuple; + using Alloc = std::scoped_allocator_adaptor< myalloc, myalloc>; - This type trait is used by std::scoped_allocator_adaptor and may be used by custom - allocators to determine whether the object being constructed is itself capable of - using an allocator (e.g. is a container), in which case an allocator should be - passed to its constructor. + Alloc a(1,2); + std::vector v(a); + v.resize(1); // uses allocator #1 for elements of v + std::get<1>(v[0]).resize(10); // uses allocator #2 for innervector_t .SH See also - allocator_arg an object of type std::allocator_arg_t used to select - \fI(C++11)\fP allocator-aware constructors - (constant) - allocator_arg_t tag type used to select allocator-aware constructor - \fI(C++11)\fP overloads - \fI(class)\fP - scoped_allocator_adaptor implements multi-level allocator for multi-level containers - \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index b77012bbf..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,13 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class T, class Alloc > \fI(since C++14)\fP - struct uses_allocator, Alloc> : std::true_type; - - Provides a specialization of the std::uses_allocator type trait for std::dynarray. A - dynarray may be constructed with an allocator, even though the class does not have - allocator_type member type. - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 3993b7c7b..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class R, class... ArgTypes, class Alloc > - struct uses_allocator, Alloc> : \fI(since C++11)\fP - std::true_type { }; - - This specialization of std::uses_allocator informs other library components that all - objects of type std::function support uses-allocator construction, even though they - do not have a nested allocator_type. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 1ac9ccd19..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class R, class Alloc > \fI(since C++11)\fP - struct uses_allocator, Alloc> : true_type { }; - - Provides a specialization of the std::uses_allocator type trait for - std::packaged_task. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 078bf25e2..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class T, class Container, class Compare,class Alloc > - - struct uses_allocator,Alloc> : \fI(since C++11)\fP - - std::uses_allocator::type { }; - - Provides a transparent specialization of the std::uses_allocator type trait for - std::priority_queue: the container adaptor uses allocator if and only if the - underlying container does. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 8e805dc9c..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,27 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class R, class Alloc > \fI(since C++11)\fP - struct uses_allocator, Alloc> : std::true_type { }; - - Provides a specialization of the std::uses_allocator type trait for std::promise. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 62dc053e8..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class T, class Container, class Alloc > - - struct uses_allocator,Alloc> : \fI(since C++11)\fP - - std::uses_allocator::type { }; - - Provides a transparent specialization of the std::uses_allocator type trait for - std::queue: the container adaptor uses allocator if and only if the underlying - container does. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 73c758884..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - template< class T, class Container, class Alloc > - - struct uses_allocator,Alloc> : \fI(since C++11)\fP - - std::uses_allocator::type { }; - - Provides a transparent specialization of the std::uses_allocator type trait for - std::stack: the container adaptor uses allocator if and only if the underlying - container does. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator.3 b/man/std::uses_allocator.3 deleted file mode 100644 index 5af43c0ec..000000000 --- a/man/std::uses_allocator.3 +++ /dev/null @@ -1,47 +0,0 @@ -.TH std::uses_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template< class... Types, class Alloc > - struct uses_allocator< std::tuple, Alloc > : std::true_type \fI(since C++11)\fP - { }; - - This specialization of std::uses_allocator informs other library components that - tuples support uses-allocator construction, even though they do not have a nested - allocator_type. - -.SH Member constants - - value true - \fB[static]\fP \fI(public static member constant)\fP - -.SH Member functions - - operator bool converts the object to bool, returns value - \fI(public member function)\fP - -.SH Member types - - Type Definition - value_type bool - type std::integral_constant - -.SH Example - - -// Run this code - - // myalloc is a stateful Allocator with a single-argument constructor - // that takes an int. It has no default constructor. - - typedef std::vector> innervector_t; - typedef std::tuple elem_t; - typedef std::scoped_allocator_adaptor< myalloc, myalloc> Alloc; - Alloc a(1,2); - std::vector v(a); - v.resize(1); // uses allocator #1 for elements of v - std::get<1>(v[0]).resize(10); // uses allocator #2 for innervector_t - -.SH See also - - uses_allocator checks if the specified type supports uses-allocator construction - \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::uses_allocator_construction_args.3 b/man/std::uses_allocator_construction_args.3 new file mode 100644 index 000000000..29b16334e --- /dev/null +++ b/man/std::uses_allocator_construction_args.3 @@ -0,0 +1,222 @@ +.TH std::uses_allocator_construction_args 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::uses_allocator_construction_args \- std::uses_allocator_construction_args + +.SH Synopsis + Defined in header + T is not a specialization of std::pair + template< class T, class Alloc, class... Args > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(1)\fP \fI(since C++20)\fP + alloc, + + Args&&... args ) noexcept; + T is a specialization of std::pair + template< class T, class Alloc, class Tuple1, class Tuple2 > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(2)\fP \fI(since C++20)\fP + alloc, + + std::piecewise_construct_t, Tuple1&& x, Tuple2&& y ) noexcept; + template< class T, class Alloc > + constexpr auto uses_allocator_construction_args( const Alloc& \fB(3)\fP \fI(since C++20)\fP + alloc ) noexcept; + template< class T, class Alloc, class U, class V > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(4)\fP \fI(since C++20)\fP + alloc, + + U&& u, V&& v ) noexcept; + template< class T, class Alloc, class U, class V > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(5)\fP (since C++23) + alloc, + + std::pair& pr ) noexcept; + template< class T, class Alloc, class U, class V > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(6)\fP \fI(since C++20)\fP + alloc, + + const std::pair& pr ) noexcept; + template< class T, class Alloc, class U, class V > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(7)\fP \fI(since C++20)\fP + alloc, + + std::pair&& pr ) noexcept; + template< class T, class Alloc, class U, class V > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(8)\fP (since C++23) + alloc, + + const std::pair&& pr ) noexcept; + template< class T, class Alloc, class NonPair > + + constexpr auto uses_allocator_construction_args( const Alloc& \fB(9)\fP \fI(since C++20)\fP + alloc, + + NonPair&& non_pair ) noexcept; + + Prepares the argument list needed to create an object of the given type T by means + of uses-allocator construction. + + 1) This overload participates in overload resolution only if T is not a + specialization of std::pair. Returns std::tuple determined as follows: + * If std::uses_allocator_v is false and std::is_constructible_v is true, returns std::forward_as_tuple(std::forward(args)...). + * Otherwise, if std::uses_allocator_v is true and + std::is_constructible_v is true, + returns + std::tuple(std::allocator_arg, + alloc, + + std::forward(args)...). + * Otherwise, if std::uses_allocator_v is true and + std::is_constructible_v is true, returns + std::forward_as_tuple(std::forward(args)..., alloc). + * Otherwise, the program is ill-formed. + 2) This overload participates in overload resolution only if T is a specialization + of std::pair. For T that is std::pair, equivalent to + + return std::make_tuple(std::piecewise_construct, + std::apply([&alloc](auto&&... args1) + { + return std::uses_allocator_construction_args(alloc, + std::forward(args1)...); + }, std::forward(x) + ), + std::apply([&alloc](auto&&... args2) + { + return std::uses_allocator_construction_args(alloc, + std::forward(args2)...); + }, std::forward(y) + ) + ); + + 3) This overload participates in overload resolution only if T is a specialization + of std::pair. Equivalent to + + return std::uses_allocator_construction_args(alloc, + std::piecewise_construct, std::tuple<>{}, std::tuple<>{} + ); + + 4) This overload participates in overload resolution only if T is a specialization + of std::pair. Equivalent to + + return std::uses_allocator_construction_args(alloc, + std::piecewise_construct, + std::forward_as_tuple(std::forward(u)), + std::forward_as_tuple(std::forward(v)) + ); + + 5,6) This overload participates in overload resolution only if T is a specialization + of std::pair. Equivalent to + + return std::uses_allocator_construction_args(alloc, + std::piecewise_construct, + std::forward_as_tuple(pr.first), + std::forward_as_tuple(pr.second) + ); + + 7,8) This overload participates in overload resolution only if T is a specialization + of std::pair. Equivalent to + + return std::uses_allocator_construction_args(alloc, + std::piecewise_construct, + std::forward_as_tuple(std::get<0>(std::move(pr))), + std::forward_as_tuple(std::get<1>(std::move(pr))) + ); + + 9) This overload participates in overload resolution only if T is a specialization + of std::pair, and given the exposition-only function template + + template + void /*deduce-as-pair*/(const std::pair&); + + , /*deduce-as-pair*/(non_pair) is ill-formed when considered as an unevaluated + operand. + Let the exposition-only class pair-constructor be defined as + + class /*pair-constructor*/ + { + const Alloc& alloc_; // exposition only + NonPair& u_; // exposition only + + constexpr reconstruct(const std::remove_cv& p) const // exposition only + { + return std::make_obj_using_allocator>(alloc_, p); + } + + constexpr reconstruct(std::remove_cv&& p) const // exposition only + { + return std::make_obj_using_allocator>(alloc_, std::move(p)); + } + + public: + constexpr operator std::remove_cv() const + { + return reconstruct(std::forward(u_)); + } + }; + + This overload is equivalent to return std::make_tuple(pair_construction);, where + pair_construction is a value of type pair-constructor whose alloc_ and u_ members + are alloc and non_pair respectively. + +.SH Parameters + + alloc - the allocator to use + args - the arguments to pass to T's constructor + x - tuple of arguments to pass to the constructors of T's first data member + y - tuple of arguments to pass to the constructors of T's second data member + u - single argument to pass to the constructor of T's first data member + v - single argument to pass to the constructor of T's second data member + a pair whose first data member will be passed to the constructor of T's + pr - first data member and second data member will be passed to the + constructor of T's second data member + non_pair - single argument to convert to a std::pair for further construction + +.SH Return value + + std::tuple of arguments suitable for passing to the constructor of T. + +.SH Notes + + The overloads (2-9) provide allocator propagation into std::pair, which supports + neither leading-allocator nor trailing-allocator calling conventions (unlike, e.g. + std::tuple, which uses leading-allocator convention). + + When used in uses-allocator construction, the conversion function of + pair-constructor converts the provided argument to std::pair at first, and then + constructs the result from that std::pair by uses-allocator construction. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3525 C++20 no overload could handle non-pair types reconstructing overload + convertible to pair added + +.SH See also + + uses_allocator checks if the specified type supports + \fI(C++11)\fP uses-allocator construction + \fI(class template)\fP + make_obj_using_allocator creates an object of the given type by means + (C++20) of uses-allocator construction + \fI(function template)\fP + creates an object of the given type at + uninitialized_construct_using_allocator specified memory location by means of + (C++20) uses-allocator construction + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::va_list.3 b/man/std::va_list.3 new file mode 100644 index 000000000..0b29ae831 --- /dev/null +++ b/man/std::va_list.3 @@ -0,0 +1,31 @@ +.TH std::va_list 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::va_list \- std::va_list + +.SH Synopsis + Defined in header + typedef /* unspecified */ va_list; + + va_list is a complete object type (in practice, a unique built-in type or char*) + suitable for holding the information needed by the macros va_start, va_copy, va_arg, + and va_end. + + If a va_list instance is created, passed to another function, and used via va_arg in + that function, then any subsequent use in the calling function should be preceded by + a call to va_end. + + It is legal to pass a pointer to a va_list object to another function and then use + that object after the function returns. + +.SH See also + + va_start enables access to variadic function arguments + \fI(function macro)\fP + va_copy makes a copy of the variadic function arguments + \fI(C++11)\fP \fI(function macro)\fP + va_arg accesses the next variadic function argument + \fI(function macro)\fP + va_end ends traversal of the variadic function arguments + \fI(function macro)\fP + C documentation for + va_list diff --git a/man/std::valarray.3 b/man/std::valarray.3 index f8ab41e66..cd1a7c817 100644 --- a/man/std::valarray.3 +++ b/man/std::valarray.3 @@ -1,4 +1,7 @@ -.TH std::valarray 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray \- std::valarray + .SH Synopsis Defined in header template< class T > @@ -14,96 +17,82 @@ aliasing, thus allowing operations on these classes to be optimized similar to the effect of the keyword restrict in the C programming language. In addition, functions and operators that take valarray arguments are allowed to return proxy objects to - make it possible for the compiler to optimize an expression such as v1 = a*v2 + v3; - as a single loop that executes v1[i] = a*v2[i] + v3[i]; avoiding any temporaries or - multiple passes. However, expression templates make the same optimization technique - available for any C++ container, and the majority of numeric libraries prefer - expression templates to valarrays for flexibility. Some C++ standard library - implementations use expression templates to implement efficient operations on - std::valarray (e.g. GNU libstdc++ and LLVM libc++). Only rarely are valarrays - optimized any further, as in e.g. Intel Parallel Studio. + make it possible for the compiler to optimize an expression such as v1 = a * v2 + + v3; as a single loop that executes v1[i] = a * v2[i] + v3[i]; avoiding any + temporaries or multiple passes. However, expression templates make the same + optimization technique available for any C++ container, and the majority of numeric + libraries prefer expression templates to valarrays for flexibility. Some C++ + standard library implementations use expression templates to implement efficient + operations on std::valarray (e.g. GNU libstdc++ and LLVM libc++). Only rarely are + valarrays optimized any further, as in e.g. Intel Integrated Performance Primitives. + +.SH Template parameters + + T - the type of the elements. The type must meet the NumericType requirements .SH Member types Member type Definition value_type T - The following limitations are imposed on the value type: - - * T cannot be a reference - * T cannot be cv-qualified - * If T is a class, it - - * does not overload operator& - * has no pure virtual member functions (is not abstract) - * has a public default constructor - * has a public copy constructor T::T(const T&) - * has a public destructor - * has a public assignment operator T& T::operator=(const T&) or T& T::operator=(T) - * default constructor followed by assignment has the same effect as copy - constructor - * destructor followed by copy constructor has the same effect as assignment - - * No operation on T may throw exceptions - .SH Member functions constructor constructs new numeric array - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the numeric array - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the contents - \fI(public member function)\fP + \fI(public member function)\fP operator[] get/set valarray element, slice, or mask - \fI(public member function)\fP + \fI(public member function)\fP operator+ operator- applies a unary arithmetic operator to each element of the valarray - operator~ \fI(public member function)\fP + operator~ \fI(public member function)\fP operator! operator+= operator-= operator*= operator/= operator%= applies compound assignment operator to each element of the valarray - operator&= \fI(public member function)\fP + operator&= \fI(public member function)\fP operator|= operator^= operator<<= operator>>= swap swaps with another valarray - \fI(public member function)\fP + \fI(public member function)\fP size returns the size of valarray - \fI(public member function)\fP + \fI(public member function)\fP resize changes the size of valarray - \fI(public member function)\fP + \fI(public member function)\fP sum calculates the sum of all elements - \fI(public member function)\fP + \fI(public member function)\fP min returns the smallest element - \fI(public member function)\fP + \fI(public member function)\fP max returns the largest element - \fI(public member function)\fP + \fI(public member function)\fP shift zero-filling shift the elements of the valarray - \fI(public member function)\fP + \fI(public member function)\fP cshift circular shift of the elements of the valarray - \fI(public member function)\fP + \fI(public member function)\fP apply applies a function to every element of a valarray - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions - std::swap(std::valarray) specializes the std::swap() algorithm - \fI(C++11)\fP \fI(function template)\fP - std::begin(std::valarray) specializes std::begin - \fI(C++11)\fP \fI(function template)\fP + std::swap(std::valarray) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + std::begin(std::valarray) overloads std::begin + \fI(C++11)\fP \fI(function template)\fP std::end(std::valarray) specializes std::end - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP operator+ operator- operator* operator/ operator% applies binary operators to each element of two valarrays, operator& or a valarray and a value - operator| \fI(function template)\fP + operator| \fI(function template)\fP operator^ operator<< operator>> @@ -112,61 +101,70 @@ operator== operator!= operator< compares two valarrays or a valarray with a value - operator<= \fI(function template)\fP + operator<= \fI(function template)\fP operator> operator>= - abs(std::valarray) applies the function std::abs to each element of valarray - \fI(function template)\fP + abs(std::valarray) applies the function abs to each element of valarray + \fI(function template)\fP .SH Exponential functions exp(std::valarray) applies the function std::exp to each element of valarray - \fI(function template)\fP + \fI(function template)\fP log(std::valarray) applies the function std::log to each element of valarray - \fI(function template)\fP + \fI(function template)\fP applies the function std::log10 to each element of log10(std::valarray) valarray - \fI(function template)\fP + \fI(function template)\fP .SH Power functions applies the function std::pow to two valarrays or a pow(std::valarray) valarray and a value - \fI(function template)\fP + \fI(function template)\fP sqrt(std::valarray) applies the function std::sqrt to each element of valarray - \fI(function template)\fP + \fI(function template)\fP .SH Trigonometric functions sin(std::valarray) applies the function std::sin to each element of valarray - \fI(function template)\fP + \fI(function template)\fP cos(std::valarray) applies the function std::cos to each element of valarray - \fI(function template)\fP + \fI(function template)\fP tan(std::valarray) applies the function std::tan to each element of valarray - \fI(function template)\fP + \fI(function template)\fP asin(std::valarray) applies the function std::asin to each element of valarray - \fI(function template)\fP + \fI(function template)\fP acos(std::valarray) applies the function std::acos to each element of valarray - \fI(function template)\fP + \fI(function template)\fP atan(std::valarray) applies the function std::atan to each element of valarray - \fI(function template)\fP + \fI(function template)\fP atan2(std::valarray) applies the function std::atan2 to a valarray and a value - \fI(function template)\fP + \fI(function template)\fP .SH Hyperbolic functions sinh(std::valarray) applies the function std::sinh to each element of valarray - \fI(function template)\fP + \fI(function template)\fP cosh(std::valarray) applies the function std::cosh to each element of valarray - \fI(function template)\fP + \fI(function template)\fP tanh(std::valarray) applies the function std::tanh to each element of valarray - \fI(function template)\fP + \fI(function template)\fP .SH Helper classes slice BLAS-like slice of a valarray: starting index, length, stride - \fI(class)\fP + \fI(class)\fP slice_array proxy to a subset of a valarray after applying a slice - \fI(class template)\fP + \fI(class template)\fP generalized slice of a valarray: starting index, set of lengths, set gslice of strides - \fI(class)\fP + \fI(class)\fP gslice_array proxy to a subset of a valarray after applying a gslice - \fI(class template)\fP + \fI(class template)\fP proxy to a subset of a valarray after applying a boolean mask mask_array operator[] - \fI(class template)\fP + \fI(class template)\fP indirect_array proxy to a subset of a valarray after applying indirect operator[] - \fI(class template)\fP + \fI(class template)\fP + + Deduction guides\fI(since C++17)\fP + +.SH See also + + simd data-parallel vector type + (parallelism TS v2) \fI(class template)\fP + simd_mask data-parallel type with the element type bool + (parallelism TS v2) \fI(class template)\fP diff --git a/man/std::valarray::apply.3 b/man/std::valarray::apply.3 index d63d1bf17..ac24f9345 100644 --- a/man/std::valarray::apply.3 +++ b/man/std::valarray::apply.3 @@ -1,4 +1,7 @@ -.TH std::valarray::apply 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::apply 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::apply \- std::valarray::apply + .SH Synopsis valarray apply( T func(T) ) const; valarray apply( T func(const T&) ) const; @@ -22,33 +25,58 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. +.SH Possible implementation + + Following straightforward implementations can be replaced by expression templates + for a higher efficiency. + + template + valarray valarray::apply(T func(T)) const + { + valarray other = *this; + for (T& i : other) + i = func(i); + return other; + } + + template + valarray valarray::apply(T func(const T&)) const + { + valarray other = *this; + for (T& i : other) + i = func(i); + return other; + } + .SH Example - calculates and prints the first 10 factorials + Calculates and prints the first 10 factorials. + - // Run this code + #include #include #include - #include - + int main() { - std::valarray v = {1,2,3,4,5,6,7,8,9,10}; - v = v.apply([](int n)->int { - return std::round(std::tgamma(n+1)); + std::valarray v = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + v = v.apply([](int n) -> int + { + return std::round(std::tgamma(n + 1)); }); - for(auto n : v) { + for (auto n : v) std::cout << n << ' '; - } std::cout << '\\n'; } @@ -58,5 +86,10 @@ .SH See also - for_each applies a function to a range of elements - \fI(function template)\fP + for_each applies a function to a range of elements + \fI(function template)\fP + ranges::for_each applies a function to a range of elements + (C++20) (niebloid) + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::valarray::cshift.3 b/man/std::valarray::cshift.3 index de51ce032..bac819913 100644 --- a/man/std::valarray::cshift.3 +++ b/man/std::valarray::cshift.3 @@ -1,10 +1,15 @@ -.TH std::valarray::cshift 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::cshift 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::cshift \- std::valarray::cshift + .SH Synopsis valarray cshift( int count ) const; Returns a new valarray of the same size with elements whose positions are shifted - circularly by count elements. The new position of each element is (i−count) mod s - where i is the previous position and s is size(). + circularly by count elements. + + A non-negative value of count shifts the elements circularly left count places and a + negative value of count shifts the elements circularly right -count places. .SH Parameters @@ -22,23 +27,58 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + std::valarray v{1, 2, 3, 4, 5, 6, 7, 8}; + + for (auto const& val : v) + std::cout << val << ' '; + std::cout << '\\n'; + + std::valarray v2 = v.cshift(2); + + for (auto const& val : v2) + std::cout << val << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 6 7 8 + 3 4 5 6 7 8 1 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the expression of the shifted + LWG 618 C++98 elements describes the new positions + contains zero-division if size() is 0 without using expressions + .SH See also shift zero-filling shift the elements of the valarray - \fI(public member function)\fP - -.SH Category: + \fI(public member function)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::valarray::max.3 b/man/std::valarray::max.3 index 51551dedf..03c11c73c 100644 --- a/man/std::valarray::max.3 +++ b/man/std::valarray::max.3 @@ -1,4 +1,7 @@ -.TH std::valarray::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::max \- std::valarray::max + .SH Synopsis T max() const; @@ -18,14 +21,23 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - min returns the smallest element - \fI(public member function)\fP + #include + #include + + int main() + { + std::valarray a{1, 2, 3, 4, 5, 6, 7, 8}; + std::cout << "Maximum value : " << a.max() << "\\n"; + } -.SH Category: +.SH Output: - * Todo no example + Maximum value : 8 + +.SH See also + + min returns the smallest element + \fI(public member function)\fP diff --git a/man/std::valarray::min.3 b/man/std::valarray::min.3 index d7c3df030..f4e502c8f 100644 --- a/man/std::valarray::min.3 +++ b/man/std::valarray::min.3 @@ -1,4 +1,7 @@ -.TH std::valarray::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::min \- std::valarray::min + .SH Synopsis T min() const; @@ -18,14 +21,23 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - max returns the largest element - \fI(public member function)\fP + #include + #include + + int main() + { + std::valarray a{1, 2, 3, 4, 5, 6, 7, 8}; + std::cout << "Minimum value : " << a.min() << "\\n"; + } -.SH Category: +.SH Output: - * Todo no example + Minimum value : 1 + +.SH See also + + max returns the largest element + \fI(public member function)\fP diff --git a/man/std::valarray::operator+,-,~,!.3 b/man/std::valarray::operator+,-,~,!.3 index f9a08861a..c37fb2632 100644 --- a/man/std::valarray::operator+,-,~,!.3 +++ b/man/std::valarray::operator+,-,~,!.3 @@ -1,4 +1,7 @@ -.TH std::valarray::operator+,-,~,! 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::operator+,-,~,! 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::operator+,-,~,! \- std::valarray::operator+,-,~,! + .SH Synopsis valarray operator+() const; \fB(1)\fP valarray operator-() const; \fB(2)\fP @@ -18,14 +21,14 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Notes Each of the operators can only be instantiated if the following requirements are met: - * The indicated operator can be applied to type T + * The indicated operator can be applied to type T. * The result value can be unambiguously converted to T (1-3) or bool \fB(4)\fP. The function can be implemented with the return type different from std::valarray. @@ -34,9 +37,95 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. + +.SH Example + + +// Run this code + + #include + #include + #include + + template + void print(std::string_view const note, + std::valarray const vala, // by-value, see Notes above + std::string_view const term = "\\n") + { + std::cout << note << std::boolalpha << std::showpos; + for (T const element : vala) + std::cout << '\\t' << element; + std::cout << term; + } + + int main() + { + std::valarray x{1, 2, 3, 4}; + print("x: ", x); + print("+x: ", +x); + print("+ + x: ", + + x); + print("-x: ", -x); + print("- - x: ", - - x, "\\n\\n"); + + std::valarray y{0, 1, -1, 0x7fff}; + print("y: ", y); + print("~y: ", ~y); + print("~~y: ", ~~y, "\\n\\n"); + + std::valarray z{true, false}; + print("z: ", z); + print("!z: ", !z); + print("!!z: ", !!z); + } + +.SH Possible output: + + x: +1 +2 +3 +4 + +x: +1 +2 +3 +4 + + + x: +1 +2 +3 +4 + -x: -1 -2 -3 -4 + - - x: +1 +2 +3 +4 + + y: +0 +1 -1 +32767 + ~y: -1 -2 +0 -32768 + ~~y: +0 +1 -1 +32767 + + z: true false + !z: false true + !!z: true false + +.SH See also + + operator+= + operator-= + operator*= + operator/= + operator%= applies compound assignment operator to each element of the valarray + operator&= \fI(public member function)\fP + operator|= + operator^= + operator<<= + operator>>= + operator+ + operator- + operator* + operator/ + operator% applies binary operators to each element of two valarrays, or a valarray + operator& and a value + operator| \fI(function template)\fP + operator^ + operator<< + operator>> + operator&& + operator|| + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::valarray::operator=.3 b/man/std::valarray::operator=.3 index 8dcc2f48a..4e538e167 100644 --- a/man/std::valarray::operator=.3 +++ b/man/std::valarray::operator=.3 @@ -1,33 +1,35 @@ -.TH std::valarray::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::operator= \- std::valarray::operator= + .SH Synopsis - valarray& operator=( const valarray& other ); \fB(1)\fP - valarray& operator=( valarray&& other ); \fB(2)\fP \fI(since C++11)\fP - valarray& operator=( const T& val ); \fB(3)\fP - valarray& operator=( const std::slice_array& ); \fB(4)\fP - valarray& operator=( const std::gslice_array& ); \fB(5)\fP - valarray& operator=( const std::mask_array& ); \fB(6)\fP - valarray& operator=( const std::indirect_array& ); \fB(7)\fP - valarray& operator=( std::initializer_list il ); \fB(8)\fP \fI(since C++11)\fP + valarray& operator=( const valarray& other ); \fB(1)\fP + valarray& operator=( valarray&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + valarray& operator=( const T& val ); \fB(3)\fP + valarray& operator=( const std::slice_array& other ); \fB(4)\fP + valarray& operator=( const std::gslice_array& other ); \fB(5)\fP + valarray& operator=( const std::mask_array& other ); \fB(6)\fP + valarray& operator=( const std::indirect_array& other ); \fB(7)\fP + valarray& operator=( std::initializer_list il ); \fB(8)\fP \fI(since C++11)\fP Replaces the contents of the numeric array. - 1) Copy assignment operator. Replaces the contents with a copy of the contents of - other. - 2) Move assignment operator. Replaces the contents with those of other using move - semantics (i.e. the data in other is moved from other into this numeric array). - other is in valid, but unspecified state afterwards. - 3) Assigns each value in the numeric array the value of val. - - This section is incomplete - - 8) Assigns the contents of initializer list il. Equivalent to {{{1}}}. + 1) Copy assignment operator. If size() != other.size(), first resizes *this as if by + resize(other.size()). Each element of *this is assigned the value of the + corresponding element of other. + 2) Move assignment operator. Replaces the contents of *this with those of other. The + value of other is unspecified after this operation. The complexity of this operation + may be linear if T has non-trivial destructors, but is usually constant otherwise. + 3) Replaces each value in *this with a copy of val. + 4-7) Replaces the contents of *this with the result of a generalized subscripting + operation. The behavior is undefined if size() does not equal the length of other or + if any value on the left depends on the value on the right (e.g. v = v[v > 2]). + 8) Assigns the contents of initializer list il. Equivalent to *this = valarray(il). .SH Parameters - other - another numeric array to assign - the value to initialize each element with - val - - This section is incomplete + other - another numeric array (or a mask) to assign + val - the value to initialize each element with il - initializer list to assign .SH Return value @@ -36,15 +38,66 @@ .SH Exceptions - 1) \fI(none)\fP - 2) + 1,3-8) May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(const char* rem, const std::valarray& v) + { + std::cout << std::left << std::setw(36) << rem << std::right; + for (int n : v) + std::cout << std::setw(3) << n; + std::cout << '\\n'; + } + + int main() + { + std::valarray v1(3); + v1 = -1; // (3) from a scalar + print("assigned from scalar: ", v1); + + v1 = {1, 2, 3, 4, 5, 6}; // (8): from initializer list of different size + print("assigned from initializer_list:", v1); + + std::valarray v2(3); + v2 = v1[std::slice(0, 3, 2)]; // (4): from slice array + print("every 2nd element starting at pos 0:", v2); + + v2 = v1[v1 % 2 == 0]; // (6): from mask array + print("values that are even:", v2); + + std::valarray idx = {0, 1, 2, 4}; // index array + v2.resize(4); // sizes must match when assigning from gen subscript + v2 = v1[idx]; // (7): from indirect array + print("values at positions 0, 1, 2, 4:", v2); + } + +.SH Output: + + assigned from scalar: -1 -1 -1 + assigned from initializer_list: 1 2 3 4 5 6 + every 2nd element starting at pos 0: 1 3 5 + values that are even: 2 4 6 + values at positions 0, 1, 2, 4: 1 2 3 5 - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Defect reports - 3-8) \fI(none)\fP -.SH Category: + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - * Todo without reason + DR Applied to Behavior as published Correct behavior + the behaviors of overloads (4-7) were the behaviors are + LWG 624 C++98 unclear if the length of other is not undefined in this case + size() + the behavior of the copy assignment resizes *this + LWG 630 C++98 operator first in this case + was undefined if size() != other.size() + LWG 2071 C++11 the move assignment operator resized not required to + *this if size() != other.size() resize in this case diff --git a/man/std::valarray::operator[].3 b/man/std::valarray::operator[].3 index bdb39317d..222db55b8 100644 --- a/man/std::valarray::operator[].3 +++ b/man/std::valarray::operator[].3 @@ -1,58 +1,128 @@ -.TH std::valarray::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::operator[] \- std::valarray::operator[] + .SH Synopsis - const T& operator[]( size_t pos ) const; \fB(1)\fP - T& operator[]( size_t pos ); \fB(2)\fP - valarray operator[]( slice slicearr ) const; \fB(3)\fP - slice_array operator[]( slice slicearr ); \fB(4)\fP - valarray operator[]( const gslice& gslicearr ) const; \fB(5)\fP - gslice_array operator[]( const gslice& gslicearr ); \fB(6)\fP - valarray operator[]( const valarray& boolarr ) const; \fB(7)\fP - mask_array operator[]( const valarray& boolarr ); \fB(8)\fP - valarray operator[]( const valarray& indarr ) const; \fB(9)\fP - indirect_array operator[]( const valarray& indarr ); \fB(10)\fP + const T& operator[]( std::size_t pos ) const; \fB(1)\fP + T& operator[]( std::size_t pos ); \fB(2)\fP + std::valarray operator[]( std::slice slicearr ) const; \fB(3)\fP + std::slice_array operator[]( std::slice slicearr ); \fB(4)\fP + std::valarray operator[]( const std::gslice& gslicearr ) const; \fB(5)\fP + std::gslice_array operator[]( const std::gslice& gslicearr ); \fB(6)\fP + std::valarray operator[]( const std::valarray& boolarr ) const; \fB(7)\fP + std::mask_array operator[]( const std::valarray& boolarr ); \fB(8)\fP + std::valarray operator[]( const std::valarray& indarr ) \fB(9)\fP + const; + std::indirect_array operator[]( const std::valarray& indarr ); \fB(10)\fP Retrieve single elements or portions of the array. The const overloads that return element sequences create a new std::valarray object. The non-const overloads return classes holding references to the array elements. + The selected elements(s) must exist: + + * for overloads (1,2), if pos is not less than size(), the behavior is undefined; + and + * for overloads (3-10), if the argument does not specify a valid subset of *this, + the behavior is undefined. + .SH Parameters - This section is incomplete + pos - position of the element to return + slicearr - slice of the elements to return + gslicearr - gslice of the elements to return + boolarr - mask of the elements to return + indarr - indices of the elements to return .SH Return value - 1,2) A reference to the corresponding element - 3,5,7,9) A std::valarray object containing copies of the selected items + 1,2) A reference to the corresponding element. + 3,5,7,9) A std::valarray object containing copies of the selected items. 4,6,8,10) The corresponding data structure containing references to the selected - items + items. .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. + +.SH Notes -.SH Precondition + For proper std::valarray values a, b and proper std::size_t values i, j, all of the + following expressions always evaluate to true: - The selected elements must exist. + 1) (a[i] = q, a[i]) == q for non-const a + 2) &a[i + j] == &a[i] + j + * This means that std::valarray elements are adjacent in memory. + 3) &a[i] != &b[j] for every objects a and b that are not aliases of one another + * This means that there are no aliases in the elements and this property can be + used to perform some kinds of optimization. -.SH Notes + References become invalid on resize() or when the array is destructed. + + For overloads (3,5,7,9), The function can be implemented with the return type + different from std::valarray. In this case, the replacement type has the following + properties: + + * All const member functions of std::valarray are provided. + * std::valarray, std::slice_array, std::gslice_array, std::mask_array and + std::indirect_array can be constructed from the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. + * The return type does not add more than two levels of template nesting over the + most deeply-nested argument type. + + Slice/mask/indirect index accesses do not chain: v[v == n][std::slice(0, 5, 2)] = x; + is an error because std::mask_array (the type of v[v == n]) does not have + operator[]. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::valarray data = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + + std::cout << "Initial valarray: "; + for (int n : data) + std::cout << std::setw(3) << n; + std::cout << '\\n'; - * For proper values of i and j, the following properties are true: + data[data > 5] = -1; // valarray overload of operator[] + // the type of data > 5 is std::valarray + // the type of data[data > 5] is std::mask_array - 1) (a[i] = q, a[i]) == q + std::cout << "After v[v > 5] = -1:"; + for (std::size_t n = 0; n < data.size(); ++n) + std::cout << std::setw(3) << data[n]; // regular operator[] + std::cout << '\\n'; + } - For a non-const a. - 2) &a[i+j] == &a[i] + j +.SH Output: - This means that valarray elements are adjacent in memory. - 3) &a[i] != &b[j] + Initial valarray: 0 1 2 3 4 5 6 7 8 9 + After v[v > 5] = -1: 0 1 2 3 4 5 -1 -1 -1 -1 - This holds for every objects a and b that are not aliases of one another. - This means that there are no aliases in the elements and this property can be used - to perform some kinds of optimization. + Defect reports - * References become invalid on resize or when the array is destructed. + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + LWG 389 C++98 the return type of overload \fB(1)\fP was T corrected to const T& + LWG 430 C++98 the behavior was unclear for overloads the behavior is + (3-10) if an invalid subset is specified undefined in this case - * Todo without reason +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::valarray::resize.3 b/man/std::valarray::resize.3 index 35dea9e11..5a140cc35 100644 --- a/man/std::valarray::resize.3 +++ b/man/std::valarray::resize.3 @@ -1,4 +1,7 @@ -.TH std::valarray::resize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::resize \- std::valarray::resize + .SH Synopsis void resize( std::size_t count, T value = T() ); @@ -17,16 +20,18 @@ .SH Example - + // Run this code - #include #include + #include + int main() { - std::valarray v{1,2,3}; + std::valarray v{1, 2, 3}; v.resize(10); - for(int n: v) std::cout << n << ' '; + for (int n : v) + std::cout << n << ' '; std::cout << '\\n'; } @@ -37,4 +42,4 @@ .SH See also size returns the size of valarray - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::valarray::shift.3 b/man/std::valarray::shift.3 index b923af305..4784282b6 100644 --- a/man/std::valarray::shift.3 +++ b/man/std::valarray::shift.3 @@ -1,4 +1,7 @@ -.TH std::valarray::shift 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::shift 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::shift \- std::valarray::shift + .SH Synopsis valarray shift( int count ) const; @@ -22,23 +25,47 @@ * All const member functions of std::valarray are provided. * std::valarray, std::slice_array, std::gslice_array, std::mask_array and std::indirect_array can be constructed from the replacement type. - * All functions accepting a arguments of type const std::valarray& should also - accept the replacement type. - * All functions accepting two arguments of type const std::valarray& should accept - every combination of const std::valarray& and the replacement type. + * For every function taking a const std::valarray& + except begin() and end() + \fI(since C++11)\fP, identical functions taking the replacement types shall be added; + * For every function taking two const std::valarray& arguments, identical + functions taking every combination of const std::valarray& and replacement + types shall be added. * The return type does not add more than two levels of template nesting over the most deeply-nested argument type. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + std::valarray v{1, 2, 3, 4, 5, 6, 7, 8}; + + for (auto const& val : v) + std::cout << val << ' '; + std::cout << '\\n'; + + std::valarray v2 = v.shift(2); + + for (auto const& val : v2) + std::cout << val << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 1 2 3 4 5 6 7 8 + 3 4 5 6 7 8 0 0 .SH See also cshift circular shift of the elements of the valarray - \fI(public member function)\fP - -.SH Category: + \fI(public member function)\fP - * Todo no example +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::valarray::size.3 b/man/std::valarray::size.3 index 4bdd2a7d3..5c99232db 100644 --- a/man/std::valarray::size.3 +++ b/man/std::valarray::size.3 @@ -1,4 +1,7 @@ -.TH std::valarray::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::size \- std::valarray::size + .SH Synopsis std::size_t size() const; @@ -14,14 +17,23 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - resize changes the size of valarray - \fI(public member function)\fP + #include + #include + + int main() + { + std::valarray a = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + std::cout << "Average: " << a.sum()/a.size() << '\\n'; + } -.SH Category: +.SH Output: - * Todo no example + Average: 5.5 + +.SH See also + + resize changes the size of valarray + \fI(public member function)\fP diff --git a/man/std::valarray::sum.3 b/man/std::valarray::sum.3 index 285474ed2..e7d60e2d5 100644 --- a/man/std::valarray::sum.3 +++ b/man/std::valarray::sum.3 @@ -1,4 +1,7 @@ -.TH std::valarray::sum 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::sum 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::sum \- std::valarray::sum + .SH Synopsis T sum() const; @@ -18,12 +21,12 @@ .SH Example - + // Run this code #include #include - + int main() { std::valarray a = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; @@ -37,6 +40,6 @@ .SH See also apply applies a function to every element of a valarray - \fI(public member function)\fP - accumulate sums up a range of elements - \fI(function template)\fP + \fI(public member function)\fP + accumulate sums up or folds a range of elements + \fI(function template)\fP diff --git a/man/std::valarray::swap.3 b/man/std::valarray::swap.3 index c9beea18a..512b1ee93 100644 --- a/man/std::valarray::swap.3 +++ b/man/std::valarray::swap.3 @@ -1,6 +1,10 @@ -.TH std::valarray::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::swap \- std::valarray::swap + .SH Synopsis - void swap( valarray& other ); + void swap( valarray& other ); \fI(until C++11)\fP + void swap( valarray& other ) noexcept; \fI(since C++11)\fP Swaps the contents with those of other. @@ -11,10 +15,3 @@ .SH Return value \fI(none)\fP - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - diff --git a/man/std::valarray::valarray.3 b/man/std::valarray::valarray.3 index c7bab2d27..f331c6615 100644 --- a/man/std::valarray::valarray.3 +++ b/man/std::valarray::valarray.3 @@ -1,53 +1,55 @@ -.TH std::valarray::valarray 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::valarray 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::valarray \- std::valarray::valarray + .SH Synopsis - valarray(); \fB(1)\fP - explicit valarray( size_t count ); \fB(2)\fP - valarray( const T& val, size_t count ); \fB(3)\fP - valarray( const T* vals, size_t count ); \fB(4)\fP - valarray( const valarray& other ); \fB(5)\fP - valarray( valarray&& other ); \fB(6)\fP \fI(since C++11)\fP - valarray( const std::slice_array& ); \fB(7)\fP - valarray( const std::gslice_array& ); \fB(8)\fP - valarray( const std::mask_array& ); \fB(9)\fP - valarray( const std::indirect_array& ); \fB(10)\fP - valarray( std::initializer_list il ); \fB(11)\fP \fI(since C++11)\fP + valarray(); \fB(1)\fP + explicit valarray( std::size_t count ); \fB(2)\fP + valarray( const T& val, std::size_t count ); \fB(3)\fP + valarray( const T* vals, std::size_t count ); \fB(4)\fP + valarray( const valarray& other ); \fB(5)\fP + valarray( valarray&& other ) noexcept; \fB(6)\fP \fI(since C++11)\fP + valarray( const std::slice_array& sa ); \fB(7)\fP + valarray( const std::gslice_array& gsa ); \fB(8)\fP + valarray( const std::mask_array& ma ); \fB(9)\fP + valarray( const std::indirect_array& ia ); \fB(10)\fP + valarray( std::initializer_list il ); \fB(11)\fP \fI(since C++11)\fP Constructs new numeric array from various sources. 1) Default constructor. Constructs an empty numeric array. 2) Constructs a numeric array with count copies of value-initialized elements. - 3) Constructs a numeric array with count copies of val or *val respectively. + 3) Constructs a numeric array with count copies of val. 4) Constructs a numeric array with copies of count values from an array pointed to by vals. If this array contains less than count values, the behavior is undefined. 5) Copy constructor. Constructs the numeric array with the copy of the contents of other. 6) Move constructor. Constructs the container with the contents of other using move semantics. - - This section is incomplete - + 7-10) Converting constructor. Convert the corresponding data structure to a + valarray. 11) Constructs the numeric array with the contents of the initializer list il. .SH Parameters count - the number of elements to construct val - the value to initialize the elements with - another numeric array to use as source to initialize the contents - other - - This section is incomplete + vals - pointer to a C array to use as source to initialize the contents + other - another numeric array to use as source to initialize the contents + sa - slice array to initialize the elements with + gsa - generic slice array to initialize the elements with + ma - mask array to initialize the elements with + ia - indirect array to initialize the elements with il - initializer list to initialize the elements with .SH Exceptions - 1-5) \fI(none)\fP - 6) + 1-5, 7-11) May throw implementation-defined exceptions. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +.SH Example - 7-11) \fI(none)\fP -.SH Category: + This section is incomplete + Reason: no example - * Todo without reason +.SH Category: + * Todo no example diff --git a/man/std::valarray::~valarray.3 b/man/std::valarray::~valarray.3 index 864743d0e..c7dffce22 100644 --- a/man/std::valarray::~valarray.3 +++ b/man/std::valarray::~valarray.3 @@ -1,4 +1,7 @@ -.TH std::valarray::~valarray 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::valarray::~valarray 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::valarray::~valarray \- std::valarray::~valarray + .SH Synopsis ~valarray() diff --git a/man/std::variant.3 b/man/std::variant.3 new file mode 100644 index 000000000..4b658a8f8 --- /dev/null +++ b/man/std::variant.3 @@ -0,0 +1,204 @@ +.TH std::variant 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant \- std::variant + +.SH Synopsis + Defined in header + template< class... Types > \fI(since C++17)\fP + class variant; + + The class template std::variant represents a type-safe union. An instance of + std::variant at any given time either holds a value of one of its alternative types, + or in the case of error - no value (this state is hard to achieve, see + valueless_by_exception). + + As with unions, if a variant holds a value of some object type T, the object + representation of T is allocated directly within the object representation of the + variant itself. Variant is not allowed to allocate additional (dynamic) memory. + + A variant is not permitted to hold references, arrays, or the type void. + + A variant is permitted to hold the same type more than once, and to hold differently + cv-qualified versions of the same type. + + Consistent with the behavior of unions during aggregate initialization, a + default-constructed variant holds a value of its first alternative, unless that + alternative is not default-constructible (in which case the variant is not + default-constructible either). The helper class std::monostate can be used to make + such variants default-constructible. + + A program that instantiates the definition of std::variant with no template + arguments is ill-formed. std::variant can be used instead. + + If a program declares an explicit or partial specialization of std::variant, the + program is ill-formed, no diagnostic required. + +.SH Template parameters + + the types that may be stored in this variant. All types must meet the + Types - Destructible requirements (in particular, array types and non-object types + are not allowed). + +.SH Member functions + + constructor constructs the variant object + \fI(public member function)\fP + destructor destroys the variant, along with its contained value + \fI(public member function)\fP + operator= assigns a variant + \fI(public member function)\fP +.SH Observers + returns the zero-based index of the alternative held by the + index variant + \fI(public member function)\fP + valueless_by_exception checks if the variant is in the invalid state + \fI(public member function)\fP +.SH Modifiers + emplace constructs a value in the variant, in place + \fI(public member function)\fP + swap swaps with another variant + \fI(public member function)\fP + Visitation + visit calls the provided functor with the argument held by the + (C++26) variant + \fI(public member function)\fP + +.SH Non-member functions + + visit calls the provided functor with the arguments held by one or + \fI(C++17)\fP more variants + \fI(function template)\fP + holds_alternative checks if a variant currently holds a given type + \fI(C++17)\fP \fI(function template)\fP + get(std::variant) reads the value of the variant given the index or the type + \fI(C++17)\fP (if the type is unique), throws on error + \fI(function template)\fP + get_if obtains a pointer to the value of a pointed-to variant given + \fI(C++17)\fP the index or the type (if unique), returns null on error + \fI(function template)\fP + operator== + operator!= + operator< + operator<= + operator> + operator>= + operator<=> compares variant objects as their contained values + \fI(C++17)\fP \fI(function template)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + (C++20) + std::swap(std::variant) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function template)\fP + +.SH Helper classes + + monostate placeholder type for use as the first alternative in a + \fI(C++17)\fP variant of non-default-constructible types + \fI(class)\fP + bad_variant_access exception thrown on invalid accesses to the value of a + \fI(C++17)\fP variant + \fI(class)\fP + variant_size obtains the size of the variant's list of alternatives at + variant_size_v compile time + \fI(C++17)\fP \fI(class template)\fP (variable template) + variant_alternative obtains the type of the alternative specified by its index, + variant_alternative_t at compile time + \fI(C++17)\fP \fI(class template)\fP (alias template) + std::hash hash support for std::variant + \fI(C++17)\fP \fI(class template specialization)\fP + + Helper objects + + variant_npos index of the variant in the invalid state + \fI(C++17)\fP (constant) + +.SH Notes + + Feature-test macro Value Std Feature + 201606L \fI(C++17)\fP std::variant: a type-safe union + 202102L \fI(C++17)\fP std::visit for classes derived from std::variant + __cpp_lib_variant (DR) + 202106L (C++20) Fully constexpr std::variant + (DR) + 202306L (C++26) Member visit + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::variant v, w; + v = 42; // v contains int + int i = std::get(v); + assert(42 == i); // succeeds + w = std::get(v); + w = std::get<0>(v); // same effect as the previous line + w = v; // same effect as the previous line + + // std::get(v); // error: no double in [int, float] + // std::get<3>(v); // error: valid index values are 0 and 1 + + try + { + std::get(w); // w contains int, not float: will throw + } + catch (const std::bad_variant_access& ex) + { + std::cout << ex.what() << '\\n'; + } + + using namespace std::literals; + + std::variant x("abc"); + // converting constructors work when unambiguous + x = "def"; // converting assignment also works when unambiguous + + std::variant y("abc"); + // casts to void const * when passed a char const * + assert(std::holds_alternative(y)); // succeeds + y = "xyz"s; + assert(std::holds_alternative(y)); // succeeds + } + +.SH Possible output: + + std::get: wrong index for variant + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + specialization of std::uses_allocator + LWG 2901 C++17 provided, specialization removed + but std::variant cannot properly + support allocators + the program is ill-formed + LWG 3990 C++17 a program could declare an explicit or in this + partial specialization of std::variant case (no diagnostic + required) + +.SH See also + + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP + optional a wrapper that may or may not hold an object + \fI(C++17)\fP \fI(class template)\fP + any objects that hold instances of any CopyConstructible type + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::variant::emplace.3 b/man/std::variant::emplace.3 new file mode 100644 index 000000000..b24c26df6 --- /dev/null +++ b/man/std::variant::emplace.3 @@ -0,0 +1,124 @@ +.TH std::variant::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::emplace \- std::variant::emplace + +.SH Synopsis + (since + template C++17) + T& emplace(Args&&... args); (until + C++20) + template (since + constexpr T& emplace(Args&&... args); C++20) + template (since + T& emplace( std::initializer_list il, C++17) + Args&&... args ); (until + C++20) + template + constexpr T& emplace( (since + std::initializer_list il, Args&&... args C++20) + ); + template (since + std::variant_alternative_t& C++17) + emplace( Args&&... args ); (until + \fB(1)\fP C++20) + template (since + constexpr std::variant_alternative_t& emplace( Args&&... args ); \fB(2)\fP + template (since + C++17) + std::variant_alternative_t& \fB(3)\fP (until + C++20) + emplace( std::initializer_list il, + Args&&... args ); + template + + constexpr std::variant_alternative_t& C++20) + + emplace( std::initializer_list il, + Args&&... args ); + + Creates a new value in-place, in an existing variant object + + 1) Equivalent to emplace(std::forward(args)...), where I is the zero-based + index of T in Types.... + * This overload participates in overload resolution only if + std::is_constructible_v is true, and T occurs exactly once in + Types... + 2) Equivalent to emplace(il, std::forward(args)...), where I is the + zero-based index of T in Types.... + * This overload participates in overload resolution only if + std::is_constructible_v&, Args...> is true, and T + occurs exactly once in Types... + 3) First, destroys the currently contained value (if any). Then direct-initializes + the contained value as if constructing a value of type T_I with the arguments + std::forward(args).... If an exception is thrown, *this may become + valueless_by_exception. + * This overload participates in overload resolution only if + std::is_constructible_v is true. + * It is a compile-time error if I is not less than sizeof...(Types). + 4) First, destroys the currently contained value (if any). Then direct-initializes + the contained value as if constructing a value of type T_I with the arguments il, + std::forward(args).... If an exception is thrown, *this may become + valueless_by_exception. + * This overload participates in overload resolution only if + std::is_constructible_v&, Args...> is true. + * It is a compile-time error if I is not less than sizeof...(Types). + +.SH Parameters + + args - constructor arguments to use when constructing the new value + il - initializer_list argument to use when constructing the new value + +.SH Return value + + A reference to the new contained value. + +.SH Exceptions + + 1-4) Any exception thrown during the initialization of the contained value. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::variant v1; + v1.emplace<0>("abc"); // OK + std::cout << std::get<0>(v1) << '\\n'; + v1.emplace("def"); // OK + std::cout << std::get<0>(v1) << '\\n'; + + std::variant v2; + v2.emplace<1>("ghi"); // OK + std::cout << std::get<1>(v2) << '\\n'; + // v2.emplace("abc"); -> Error + } + +.SH Output: + + abc + def + ghi + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 emplace was not constexpr while the required made constexpr + operations can be constexpr in C++20 + +.SH See also + + operator= assigns a variant + \fI(public member function)\fP diff --git a/man/std::variant::index.3 b/man/std::variant::index.3 new file mode 100644 index 000000000..b879ac280 --- /dev/null +++ b/man/std::variant::index.3 @@ -0,0 +1,43 @@ +.TH std::variant::index 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::index \- std::variant::index + +.SH Synopsis + constexpr std::size_t index() const noexcept; \fI(since C++17)\fP + + Returns the zero-based index of the alternative that is currently held by the + variant. + + If the variant is valueless_by_exception, returns variant_npos. + +.SH Example + + +// Run this code + + #include + #include + #include + int main() + { + std::variant v = "abc"; + + std::cout << "v.index = " << v.index() << '\\n'; + + v = {}; + + std::cout << "v.index = " << v.index() << '\\n'; + } + +.SH Output: + + v.index = 1 + v.index = 0 + +.SH See also + + holds_alternative checks if a variant currently holds a given type + \fI(C++17)\fP \fI(function template)\fP + get(std::variant) reads the value of the variant given the index or the type (if the + \fI(C++17)\fP type is unique), throws on error + \fI(function template)\fP diff --git a/man/std::variant::operator=.3 b/man/std::variant::operator=.3 new file mode 100644 index 000000000..46b58bb1b --- /dev/null +++ b/man/std::variant::operator=.3 @@ -0,0 +1,218 @@ +.TH std::variant::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::operator= \- std::variant::operator= + +.SH Synopsis + constexpr variant& operator=( const variant& rhs ); \fB(1)\fP \fI(since C++17)\fP + constexpr variant& operator=( variant&& rhs ) \fB(2)\fP \fI(since C++17)\fP + noexcept(/* see below */); + template< class T > \fI(since C++17)\fP + variant& operator=( T&& t ) noexcept(/* see below \fI(until C++20)\fP + */); \fB(3)\fP + template< class T > + constexpr variant& operator=( T&& t ) noexcept(/* \fI(since C++20)\fP + see below */); + + Assigns a new value to an existing variant object. + + 1) Copy-assignment: + * If both *this and rhs are valueless by exception, does nothing. + * Otherwise, if rhs is valueless, but *this is not, destroys the value contained + in *this and makes it valueless. + * Otherwise, if rhs holds the same alternative as *this, assigns the value + contained in rhs to the value contained in *this. If an exception is thrown, + *this does not become valueless: the value depends on the exception safety + guarantee of the alternative's copy assignment. + * Otherwise, if the alternative held by rhs is either nothrow copy constructible + or not nothrow move constructible (as determined by + std::is_nothrow_copy_constructible and std::is_nothrow_move_constructible, + respectively), equivalent to + this->emplace(*std::get_if(std::addressof(rhs))). + *this may become valueless_by_exception if an exception is thrown on the + copy-construction inside emplace. + * Otherwise, equivalent to this->operator=(variant(rhs)). + This overload is defined as deleted unless std::is_copy_constructible_v and + std::is_copy_assignable_v are both true for all T_i in Types.... This overload + is trivial if + std::is_trivially_copy_constructible_v,std::is_trivially_copy_assignable_v + and std::is_trivially_destructible_v are all true for all T_i in Types.... + 2) Move-assignment: + * If both *this and rhs are valueless by exception, does nothing. + * Otherwise, if rhs is valueless, but *this is not, destroys the value contained + in *this and makes it valueless. + * Otherwise, if rhs holds the same alternative as *this, assigns + std::move(*std::get_if(std::addressof(rhs))) to the value contained in *this, + with j being index(). If an exception is thrown, *this does not become + valueless: the value depends on the exception safety guarantee of the + alternative's move assignment. + * Otherwise (if rhs and *this hold different alternatives), equivalent to + this->emplace(std::move(*std::get_if(std::addressof(rhs)))). + If an exception is thrown by T_i's move constructor, *this becomes + valueless_by_exception. + This overload participates in overload resolution only if + std::is_move_constructible_v and std::is_move_assignable_v are both true + for all T_i in Types.... This overload is trivial if + std::is_trivially_move_constructible_v, + std::is_trivially_move_assignable_v, and std::is_trivially_destructible_v + are all true for all T_i in Types.... + 3) Converting assignment. + * Determines the alternative type T_j that would be selected by overload + resolution for the expression F(std::forward(t)) if there was an overload of + imaginary function F(T_i) for every T_i from Types... in scope at the same time, + except that: + + * An overload F(T_i) is only considered if the declaration T_i x[] = { + std::forward(t) }; is valid for some invented variable x; + * If *this already holds a T_j, assigns std::forward(t) to the value contained + in *this. If an exception is thrown, *this does not become valueless: the value + depends on the exception safety guarantee of the assignment called. + * Otherwise, if std::is_nothrow_constructible_v || + !std::is_nothrow_move_constructible_v is true, equivalent to + this->emplace(std::forward(t)). *this may become valueless_by_exception if + an exception is thrown on the initialization inside emplace. + * Otherwise, equivalent to this->emplace(T_j(std::forward(t))). + + This overload participates in overload resolution only if + std::decay_t + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP is not the same type as variant and std::is_assignable_v is + true and std::is_constructible_v is true and the expression + F(std::forward(t)) (with F being the above-mentioned set of imaginary functions) + is well formed. + + std::variant v1; + v1 = "abc"; // OK + std::variant v2; + v2 = "abc"; // Error + std::variant v3; + v3 = "abc"; // OK, chooses string; bool is not a candidate + std::variant v4; //holds float + v4 = 0; // OK, holds long; float and double are not candidates + +.SH Parameters + + rhs - another variant + t - a value convertible to one of the variant's alternatives + +.SH Return value + + *this + +.SH Exceptions + + 1) May throw any exception thrown by assignment and copy/move initialization of any + alternative. + 2) + noexcept specification: + noexcept(((std::is_nothrow_move_constructible_v && + std::is_nothrow_move_assignable_v) && ...)) + 3) + noexcept specification: + noexcept(std::is_nothrow_assignable_v && + std::is_nothrow_constructible_v) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + std::ostream& operator<<(std::ostream& os, std::variant const& va) + { + os << ": { "; + + std::visit([&](auto&& arg) + { + using T = std::decay_t; + if constexpr (std::is_same_v) + os << arg; + else if constexpr (std::is_same_v) + os << std::quoted(arg); + }, va); + + return os << " };\\n"; + } + + int main() + { + std::variant a{2017}, b{"CppCon"}; + std::cout << "a" << a << "b" << b << '\\n'; + + std::cout << "(1) operator=( const variant& rhs )\\n"; + a = b; + std::cout << "a" << a << "b" << b << '\\n'; + + std::cout << "(2) operator=( variant&& rhs )\\n"; + a = std::move(b); + std::cout << "a" << a << "b" << b << '\\n'; + + std::cout << "(3) operator=( T&& t ), where T is int\\n"; + a = 2019; + std::cout << "a" << a << '\\n'; + + std::cout << "(3) operator=( T&& t ), where T is std::string\\n"; + std::string s{"CppNow"}; + std::cout << "s: " << std::quoted(s) << '\\n'; + a = std::move(s); + std::cout << "a" << a << "s: " << std::quoted(s) << '\\n'; + } + +.SH Possible output: + + a: { 2017 }; + b: { "CppCon" }; + + \fB(1)\fP operator=( const variant& rhs ) + a: { "CppCon" }; + b: { "CppCon" }; + + \fB(2)\fP operator=( variant&& rhs ) + a: { "CppCon" }; + b: { "" }; + + \fB(3)\fP operator=( T&& t ), where T is int + a: { 2019 }; + + \fB(3)\fP operator=( T&& t ), where T is std::string + s: "CppNow" + a: { "CppNow" }; + s: "" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + copy assignment operator doesn't + LWG 3024 C++17 participate in overload resolution defined as deleted instead + if any member type is not copyable + copy/move assignment may not be + P0602R4 C++17 trivial required to propagate + even if underlying operations are triviality + trivial + converting assignment blindly narrowing and boolean + P0608R3 C++17 assembles an overload set, conversions + leading to unintended conversions not considered + converting assignment was not + P2231R1 C++20 constexpr made constexpr + while the required operations can be + in C++20 + converting assignment was sometimes + LWG 3585 C++17 unexpectedly ill-formed made well-formed + because there was no available move + assignment + +.SH See also + + emplace constructs a value in the variant, in place + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::variant::swap.3 b/man/std::variant::swap.3 new file mode 100644 index 000000000..3073a8d4c --- /dev/null +++ b/man/std::variant::swap.3 @@ -0,0 +1,79 @@ +.TH std::variant::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::swap \- std::variant::swap + +.SH Synopsis + void swap( variant& rhs ) noexcept(/* see below */); \fI(since C++17)\fP + \fI(until C++20)\fP + constexpr void swap( variant& rhs ) noexcept(/* see below */); \fI(since C++20)\fP + + Swaps two variant objects. + + * If both *this and rhs are valueless by exception, does nothing. + * Otherwise, if both *this and rhs hold the same alternative, calls + swap(*std::get_if(this), *std::get_if(std::addressof(rhs))) where i is + index(). If an exception is thrown, the state of the values depends on the + exception safety of the swap function called. + * Otherwise, exchanges values of rhs and *this. If an exception is thrown, the + state of *this and rhs depends on exception safety of variant's move + constructor. + + The behavior is undefined unless lvalues of type T_i are Swappable and + std::is_move_constructible_v is true for all T_i in Types.... + +.SH Parameters + + rhs - a variant object to swap with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + If this->index() == rhs.index(), may throw any exception thrown by + swap(*std::get_if(this), *std::get_if(std::addressof(rhs))) with i being + index(). + + Otherwise, may throw any exception thrown by the move constructors of the + alternatives currently held by *this and rhs. + + noexcept specification: + noexcept(((std::is_nothrow_move_constructible_v && + std::is_nothrow_swappable_v) && ...)) + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::variant v1{2}, v2{"abc"}; + std::visit([](auto&& x) { std::cout << x << ' '; }, v1); + std::visit([](auto&& x) { std::cout << x << '\\n'; }, v2); + v1.swap(v2); + std::visit([](auto&& x) { std::cout << x << ' '; }, v1); + std::visit([](auto&& x) { std::cout << x << '\\n'; }, v2); + } + +.SH Output: + + 2 abc + abc 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 swap was not constexpr while the required made constexpr + operations can be constexpr in C++20 + +.SH Category: + * conditionally noexcept diff --git a/man/std::variant::valueless_by_exception.3 b/man/std::variant::valueless_by_exception.3 new file mode 100644 index 000000000..1d9aa210d --- /dev/null +++ b/man/std::variant::valueless_by_exception.3 @@ -0,0 +1,100 @@ +.TH std::variant::valueless_by_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::valueless_by_exception \- std::variant::valueless_by_exception + +.SH Synopsis + constexpr bool valueless_by_exception() const noexcept; \fI(since C++17)\fP + + Returns false if and only if the variant holds a value. + +.SH Notes + + A variant may become valueless in the following situations: + + * (guaranteed) an exception is thrown during the initialization of the contained + value during move assignment + * (optionally) an exception is thrown during the initialization of the contained + value during copy assignment + * (optionally) an exception is thrown when initializing the contained value during + a type-changing assignment + * (optionally) an exception is thrown when initializing the contained value during + a type-changing emplace + + Since variant is never permitted to allocate dynamic memory, previous value cannot + be retained in these situations. The situations marked "optionally" can be worked + around by implementations that first construct the new value on the stack and then + move it into the variant (provided non-throwing move). + + This applies even to variants of non-class types: + + struct S { + operator int() { throw 42; } + }; + std::variant v{12.f}; // OK + v.emplace<1>(S()); // v may be valueless + + A variant that is valueless by exception is treated as being in an invalid state: + index returns variant_npos, get and visit throw bad_variant_access. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + struct Demo { + Demo(int) {} + Demo(const Demo&) { throw std::domain_error("copy ctor"); } + Demo& operator= (const Demo&) = default; + }; + + int main() + { + std::variant var{"str"}; + assert(var.index() == 0); + assert(std::get<0>(var) == "str"); + assert(var.valueless_by_exception() == false); + + try { + var = Demo{555}; + } catch (const std::domain_error& ex) { + std::cout << "1) Exception: " << ex.what() << '\\n'; + } + assert(var.index() == std::variant_npos); + assert(var.valueless_by_exception() == true); + + // Now the var is "valueless" which is an invalid state caused + // by an exception raised in the process of type-changing assignment. + + try { + std::get<1>(var); + } catch (const std::bad_variant_access& ex) { + std::cout << "2) Exception: " << ex.what() << '\\n'; + } + + var = "str2"; + assert(var.index() == 0); + assert(std::get<0>(var) == "str2"); + assert(var.valueless_by_exception() == false); + } + +.SH Possible output: + + 1) Exception: copy ctor + 2) Exception: std::get: variant is valueless + +.SH See also + + get(std::variant) reads the value of the variant given the index or the type (if + \fI(C++17)\fP the type is unique), throws on error + \fI(function template)\fP + returns the zero-based index of the alternative held by the + index variant + \fI(public member function)\fP + bad_variant_access exception thrown on invalid accesses to the value of a variant + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::variant::variant.3 b/man/std::variant::variant.3 new file mode 100644 index 000000000..3f51d458f --- /dev/null +++ b/man/std::variant::variant.3 @@ -0,0 +1,252 @@ +.TH std::variant::variant 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::variant \- std::variant::variant + +.SH Synopsis + constexpr variant() noexcept(/* see below */); \fB(1)\fP \fI(since C++17)\fP + constexpr variant( const variant& other ); \fB(2)\fP \fI(since C++17)\fP + constexpr variant( variant&& other ) noexcept(/* see below */); \fB(3)\fP \fI(since C++17)\fP + template< class T > \fB(4)\fP \fI(since C++17)\fP + constexpr variant( T&& t ) noexcept(/* see below */); + template< class T, + + class... Args > \fB(5)\fP \fI(since C++17)\fP + constexpr explicit variant( std::in_place_type_t, + + Args&&... args ); + template< class T, + + class U, + class... Args > \fB(6)\fP \fI(since C++17)\fP + constexpr explicit variant( std::in_place_type_t, + std::initializer_list il, + + Args&&... args ); + template< std::size_t I, + + class... Args > \fB(7)\fP \fI(since C++17)\fP + constexpr explicit variant( std::in_place_index_t, + + Args&&... args ); + template< std::size_t I, + + class U, + class... Args > \fB(8)\fP \fI(since C++17)\fP + constexpr explicit variant( std::in_place_index_t, + std::initializer_list il, + + Args&&... args ); + + Constructs a new variant object. + + 1) Default constructor. Constructs a variant holding the value-initialized value of + the first alternative (index() is zero). + * This constructor is constexpr if and only if the value initialization of the + alternative type T_0 would satisfy the requirements for a constexpr function. + * This overload participates in overload resolution only if + std::is_default_constructible_v is true. + 2) Copy constructor. If other is not valueless_by_exception, constructs a variant + holding the same alternative as other and direct-initializes the contained value + with *std::get_if(std::addressof(other)). Otherwise, initializes a + valueless_by_exception variant. + * This constructor is defined as deleted unless std::is_copy_constructible_v + is true for all T_i in Types.... + * It is trivial if std::is_trivially_copy_constructible_v is true for all T_i + in Types.... + 3) Move constructor. If other is not valueless_by_exception, constructs a variant + holding the same alternative as other and direct-initializes the contained value + with std::move(*std::get_if(std::addressof(other))). Otherwise, + initializes a valueless_by_exception variant. + * This overload participates in overload resolution only if + std::is_move_constructible_v is true for all T_i in Types.... + * It is trivial if std::is_trivially_move_constructible_v is true for all T_i + in Types.... + 4) Converting constructor. Constructs a variant holding the alternative type T_j + that would be selected by overload resolution for the expression + F(std::forward(t)) if there was an overload of imaginary function F(T_i) for each + T_i in Types..., except that narrowing conversions aren't considered. + + Formally: + + * An overload F(T_i) is only considered if the declaration T_i x[] = { + std::forward(t) }; is valid for some invented variable x. + Direct-initializes the contained value as if by direct non-list-initialization from + std::forward(t). + * This overload participates in overload resolution only if + * sizeof...(Types) > 0, + * std::decay_t + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP is neither the same type as variant, nor a specialization of + std::in_place_type_t, nor a specialization of std::in_place_index_t, + * std::is_constructible_v is true, + * and the expression F(std::forward(t)) (with F being the above-mentioned + set of imaginary functions) is well formed. + * This constructor is a constexpr constructor if T_j's selected constructor is a + constexpr constructor. + + std::variant v("abc"); // OK + std::variant w("abc"); // ill-formed + std::variant x("abc"); // OK, chooses const char* + std::variant y("abc"); // OK, chooses string; bool is not a candidate + std::variant z = 0; // OK, holds long + // float and double are not candidates + + 5) Constructs a variant with the specified alternative T and initializes the + contained value with the arguments std::forward(args).... + * If T's selected constructor is a constexpr constructor, this constructor is also + a constexpr constructor. + * This overload participates in overload resolution only if there is exactly one + occurrence of T in Types... and std::is_constructible_v is true. + 6) Constructs a variant with the specified alternative T and initializes the + contained value with the arguments il, std::forward(args).... + * If T's selected constructor is a constexpr constructor, this constructor is also + a constexpr constructor. + * This overload participates in overload resolution only if there is exactly one + occurrence of T in Types... and std::is_constructible_v&, + Args...> is true. + 7) Constructs a variant with the alternative T_i specified by the index I and + initializes the contained value with the arguments std::forward(args).... + * If T_i's selected constructor is a constexpr constructor, this constructor is + also a constexpr constructor. + * This overload participates in overload resolution only if I < sizeof...(Types) + and std::is_constructible_v is true. + 8) Constructs a variant with the alternative T_i specified by the index I and + initializes the contained value with the arguments il, std::forward(args).... + * If T_i's selected constructor is a constexpr constructor, this constructor is + also a constexpr constructor. + * This overload participates in overload resolution only if I < sizeof...(Types) + and std::is_constructible_v&, Args...> is true. + +.SH Parameters + + other - another variant object whose contained value to copy/move + t - value to initialize the contained value with + args... - arguments to initialize the contained value with + il - initializer list to initialize the contained value with + +.SH Exceptions + + 1) May throw any exception thrown by the value initialization of the first + alternative. + noexcept specification: + noexcept(std::is_nothrow_default_constructible_v) + 2) May throw any exception thrown by direct-initializing any T_i in Types.... + 3) May throw any exception thrown by move-constructing any T_i in Types.... + noexcept specification: + noexcept((std::is_nothrow_move_constructible_v && ...)) + 4) May throw any exception thrown by the initialization of the selected alternative + T_j. + noexcept specification: + noexcept(std::is_nothrow_constructible_v) + 5-8) May throw any exception thrown by calling the selected constructor of the + selected alternative. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using vector_t = std::vector; + + auto& operator<<(auto& out, const vector_t& v) + { + out << "{ "; + for (int e : v) + out << e << ' '; + return out << '}'; + } + + int main() + { + // value-initializes first alternative + std::variant var0; + assert(std::holds_alternative(var0) and + var0.index() == 0 and + std::get(var0) == 0); + + // initializes first alternative with std::string{"STR"}; + std::variant var1{"STR"}; + assert(var1.index() == 0); + std::cout << "1) " << std::get(var1) << '\\n'; + + // initializes second alternative with int == 42; + std::variant var2{42}; + assert(std::holds_alternative(var2)); + std::cout << "2) " << std::get(var2) << '\\n'; + + // initializes first alternative with std::string{4, 'A'}; + std::variant var3 + { + std::in_place_type, 4, 'A' + }; + assert(var3.index() == 0); + std::cout << "3) " << std::get(var3) << '\\n'; + + // initializes second alternative with std::vector{1,2,3,4,5}; + std::variant var4 + { + std::in_place_type, {1, 2, 3, 4, 5} + }; + assert(var4.index() == 1); + std::cout << "4) " << std::get(var4) << '\\n'; + + // initializes first alternative with std::string{"ABCDE", 3}; + std::variant var5 {std::in_place_index<0>, "ABCDE", 3}; + assert(var5.index() == 0); + std::cout << "5) " << std::get(var5) << '\\n'; + + // initializes second alternative with std::vector(4, 42); + std::variant var6 {std::in_place_index<1>, 4, 42}; + assert(std::holds_alternative(var6)); + std::cout << "6) " << std::get(var6) << '\\n'; + } + +.SH Output: + + 1) STR + 2) 42 + 3) AAAA + 4) { 1 2 3 4 5 } + 5) ABC + 6) { 42 42 42 42 } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + allocator-aware constructors + LWG 2901 C++17 provided but constructors removed + variant can't properly support + allocators + converting constructor template + P0739R0 C++17 interacts constraint added + poorly with class template argument + deduction + copy constructor doesn't participate + LWG 3024 C++17 in defined as deleted instead + overload resolution if any member + type is not copyable + copy/move constructors may not be required to propagate + P0602R4 C++17 trivial even if underlying triviality + constructors are trivial + converting constructor blindly + P0608R3 C++17 assembles narrowing and boolean + an overload set, leading to conversions not considered + unintended conversions + Pointer to bool conversion + converting constructor for bool did is narrowing and + P1957R2 C++17 not allow converting constructor has + implicit conversion no + exception for bool + +.SH Category: + * conditionally noexcept diff --git a/man/std::variant::visit.3 b/man/std::variant::visit.3 new file mode 100644 index 000000000..47e9940ca --- /dev/null +++ b/man/std::variant::visit.3 @@ -0,0 +1,72 @@ +.TH std::variant::visit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::visit \- std::variant::visit + +.SH Synopsis + template< class Self, class Visitor > \fB(1)\fP (since C++26) + constexpr decltype(auto) visit( this Self&& self, Visitor&& vis ); + template< class R, class Self, class Visitor > \fB(2)\fP (since C++26) + constexpr R visit( this Self&& self, Visitor&& vis ); + + Applies the visitor vis (a Callable that can be called with any combination of types + from the variant) to the variant held by self. + + Given type V as decltype(std::forward_like(std::declval())), the + equivalent call is: + + 1) return std::visit(std::forward(vis), (V) self);. + 2) return std::visit(std::forward(vis), (V) self);. + +.SH Parameters + + vis - a Callable that accepts every possible alternative from the variant + self - variant to pass to the visitor + +.SH Return value + + 1) The result of the std::visit invocation. + 2) Nothing if R is (possibly cv-qualified) void; otherwise the result of the + std::visit invocation. + +.SH Exceptions + + Only throws if the call to std::visit throws. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_variant 202306L (C++26) member visit + +.SH Example + + +// Run this code + + #include + #include + #include + + // helper type for the visitor + template + struct overloads : Ts... { using Ts::operator()...; }; + + int main() + { + std::variant var1{42}, var2{"abc"}; + + auto use_int = [](int i){ std::cout << "int = " << i << '\\n'; }; + auto use_str = [](std::string s){ std::cout << "string = " << s << '\\n'; }; + + #if (__cpp_lib_variant >= 202306L) + var1.visit(overloads{use_int, use_str}); + var2.visit(overloads{use_int, use_str}); + #else + std::visit(overloads{use_int, use_str}, var1); + std::visit(overloads{use_int, use_str}, var2); + #endif + } + +.SH Output: + + int = 42 + string = abc diff --git a/man/std::variant::~variant.3 b/man/std::variant::~variant.3 new file mode 100644 index 000000000..16df86776 --- /dev/null +++ b/man/std::variant::~variant.3 @@ -0,0 +1,59 @@ +.TH std::variant::~variant 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant::~variant \- std::variant::~variant + +.SH Synopsis + ~variant(); \fI(since C++17)\fP + \fI(until C++20)\fP + constexpr ~variant(); \fI(since C++20)\fP + + If valueless_by_exception() is true, does nothing. Otherwise, destroys the currently + contained value. + + This destructor is trivial if std::is_trivially_destructible_v is true for all + T_i in Types.... + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + struct X { ~X() { puts("X::~X();"); } }; + struct Y { ~Y() { puts("Y::~Y();"); } }; + + { + puts("entering block #1"); + std::variant var; + puts("leaving block #1"); + } + + { + puts("entering block #2"); + std::variant var{ std::in_place_index_t<1>{} }; // constructs var(Y) + puts("leaving block #2"); + } + } + +.SH Output: + + entering block #1 + leaving block #1 + X::~X(); + entering block #2 + leaving block #2 + Y::~Y(); + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the destructor was not constexpr while + P2231R1 C++20 non-trivial destructors can be constexpr in made constexpr + C++20 diff --git a/man/std::variant_alternative,std::variant_alternative_t.3 b/man/std::variant_alternative,std::variant_alternative_t.3 new file mode 100644 index 000000000..8629d26d2 --- /dev/null +++ b/man/std::variant_alternative,std::variant_alternative_t.3 @@ -0,0 +1,86 @@ +.TH std::variant_alternative,std::variant_alternative_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant_alternative,std::variant_alternative_t \- std::variant_alternative,std::variant_alternative_t + +.SH Synopsis + Defined in header + template \fB(1)\fP \fI(since C++17)\fP + struct variant_alternative; /* undefined */ + template \fB(2)\fP \fI(since C++17)\fP + struct variant_alternative>; + template class \fB(3)\fP \fI(since C++17)\fP + variant_alternative; + template + + class variant_alternative; \fB(3)\fP \fI(since C++17)\fP + template (deprecated in C++20) + + class variant_alternative; + + Provides compile-time indexed access to the types of the alternatives of the + possibly cv-qualified variant, combining cv-qualifications of the variant (if any) + with the cv-qualifications of the alternative. + + Formally, + + 2) meets the TransformationTrait requirements with a member typedef type equal to + the type of the alternative with index I + 3) meets the TransformationTrait requirements with a member typedef type that names, + respectively, std::add_const_t>, + std::add_volatile_t>, and + std::add_cv_t> + +.SH Member types + + Member type Definition + type the type of Ith alternative of the variant, where I must be in [0, + sizeof...(Types)), otherwise the program is ill-formed. + + Helper template alias + + template + using variant_alternative_t = typename variant_alternative::type; + +.SH Example + + +// Run this code + + #include + #include + + using my_variant = std::variant; + static_assert(std::is_same_v + >); + static_assert(std::is_same_v + >); + // cv-qualification on the variant type propagates to the extracted alternative type. + static_assert(std::is_same_v + >); + + int main() + { + std::cout << "All static assertions passed.\\n"; + } + +.SH Output: + + All static assertions passed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2974 C++17 out-of-bounds index resulted in undefined made ill-formed + behavior + +.SH See also + + variant_size obtains the size of the variant's list of + variant_size_v alternatives at compile time + \fI(C++17)\fP \fI(class template)\fP (variable template) + std::tuple_element obtains the type of the specified element + \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::variant_npos.3 b/man/std::variant_npos.3 new file mode 100644 index 000000000..40f21bc9b --- /dev/null +++ b/man/std::variant_npos.3 @@ -0,0 +1,57 @@ +.TH std::variant_npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant_npos \- std::variant_npos + +.SH Synopsis + Defined in header + inline constexpr std::size_t variant_npos = -1; \fI(since C++17)\fP + + This is a special value equal to the largest value representable by the type + std::size_t, used as the return value of index() when valueless_by_exception() is + true + + +// Run this code + + #include + #include + #include + #include + + struct Demon + { + Demon(int) {} + Demon(const Demon&) { throw std::domain_error("copy ctor"); } + Demon& operator= (const Demon&) = default; + }; + + int main() + { + std::variant var{42}; + std::cout + << std::boolalpha + << "index == npos: " << (var.index() == std::variant_npos) << '\\n'; + + try { var = Demon{666}; } catch (const std::domain_error& ex) + { + std::cout + << "Exception: " << ex.what() << '\\n' + << "index == npos: " << (var.index() == std::variant_npos) << '\\n' + << "valueless: " << var.valueless_by_exception() << '\\n'; + } + } + +.SH Possible output: + + index == npos: false + Exception: copy ctor + index == npos: true + valueless: true + +.SH See also + + returns the zero-based index of the alternative held by the + index variant + \fI(public member function)\fP + valueless_by_exception checks if the variant is in the invalid state + \fI(public member function)\fP diff --git a/man/std::variant_size,std::variant_size_v.3 b/man/std::variant_size,std::variant_size_v.3 new file mode 100644 index 000000000..dabb2b16e --- /dev/null +++ b/man/std::variant_size,std::variant_size_v.3 @@ -0,0 +1,80 @@ +.TH std::variant_size,std::variant_size_v 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::variant_size,std::variant_size_v \- std::variant_size,std::variant_size_v + +.SH Synopsis + Defined in header + template< class T > \fB(1)\fP \fI(since C++17)\fP + struct variant_size; /* undefined */ + template< class... Types > + + struct variant_size> \fB(2)\fP \fI(since C++17)\fP + + : std::integral_constant {}; + template< class T > \fB(3)\fP \fI(since C++17)\fP + class variant_size; + template< class T > \fB(4)\fP \fI(since C++17)\fP + class variant_size; (deprecated in C++20) + template< class T > \fB(5)\fP \fI(since C++17)\fP + class variant_size; (deprecated in C++20) + + Provides access to the number of alternatives in a possibly cv-qualified variant as + a compile-time constant expression. + + Formally, + + 2) meets the UnaryTypeTrait requirements with a base characteristic of + std::integral_constant + 3-5) meets the UnaryTypeTrait requirements with a base characteristic of + std::integral_constant::value> + +.SH Member constants + + value sizeof...(Types) + \fB[static]\fP \fI(public static member constant)\fP + +.SH Member functions + + operator std::size_t converts the object to std::size_t, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type std::size_t + type std::integral_constant + +.SH Notes + + All specializations of std::variant_size satisfy UnaryTypeTrait with base + characteristic std::integral_constant for some N. + +.SH Example + + +// Run this code + + #include + #include + + static_assert(std::variant_size_v> == 0); + static_assert(std::variant_size_v> == 1); + static_assert(std::variant_size_v> == 2); + static_assert(std::variant_size_v> == 3); + static_assert(std::variant_size_v> == 3); + static_assert(std::variant_size_v> == 2); + static_assert(std::variant_size_v> == 2); + static_assert(std::variant_size_v>> == 1); + + int main() {} + +.SH See also + + variant_alternative obtains the type of the alternative specified by its + variant_alternative_t index, at compile time + \fI(C++17)\fP \fI(class template)\fP (alias template) + std::tuple_size obtains the size of tuple at compile time + \fI(C++11)\fP \fI(class template specialization)\fP diff --git a/man/std::vector.3 b/man/std::vector.3 index 0e2544cd2..10f04e8f4 100644 --- a/man/std::vector.3 +++ b/man/std::vector.3 @@ -1,161 +1,304 @@ -.TH std::vector 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector \- std::vector + .SH Synopsis Defined in header template< - class T, + class T, \fB(1)\fP class Allocator = std::allocator > class vector; + namespace pmr { + + template< class T > + using vector = std::vector>; + + } - std::vector is a sequence container that encapsulates dynamic size arrays. + 1) std::vector is a sequence container that encapsulates dynamic size arrays. + 2) std::pmr::vector is an alias template that uses a polymorphic allocator. The elements are stored contiguously, which means that elements can be accessed not - only through iterators, but also using offsets on regular pointers to elements. This + only through iterators, but also using offsets to regular pointers to elements. This means that a pointer to an element of a vector may be passed to any function that expects a pointer to an element of an array. - The storage of the vector is handled automatically, being expanded and contracted as - needed. Vectors usually occupy more space than static arrays, because more memory is + The storage of the vector is handled automatically, being expanded as needed. + Vectors usually occupy more space than static arrays, because more memory is allocated to handle future growth. This way a vector does not need to reallocate each time an element is inserted, but only when the additional memory is exhausted. - The total amount of allocated memory can be queried using capacity() function. - Extra memory can be returned to the system via a call to shrink_to_fit(). - \fI(since C++11)\fP + The total amount of allocated memory can be queried using capacity() function. Extra + memory can be returned to the system via a call to shrink_to_fit()^[1]. - Reallocations are usually costly operations in terms of performance. reserve() + Reallocations are usually costly operations in terms of performance. The reserve() function can be used to eliminate reallocations if the number of elements is known beforehand. The complexity (efficiency) of common operations on vectors is as follows: - * Random access - constant O(1) - * Insertion or removal of elements at the end - amortized constant O(1) - * Insertion or removal of elements - linear in distance to the end of the vector - O(n) + * Random access - constant 𝓞\fB(1)\fP. + * Insertion or removal of elements at the end - amortized constant 𝓞\fB(1)\fP. + * Insertion or removal of elements - linear in the distance to the end of the + vector 𝓞(n). + + std::vector (for T other than bool) meets the requirements of Container + , AllocatorAwareContainer + \fI(since C++11)\fP, SequenceContainer + , ContiguousContainer + \fI(since C++17)\fP and ReversibleContainer. + + Member functions of std::vector are constexpr: it is possible to + create and use std::vector objects in the evaluation of a constant + expression. + \fI(since C++20)\fP + However, std::vector objects generally cannot be constexpr, because + any dynamically allocated storage must be released in the same + evaluation of constant expression. - std::vector meets the requirements of Container, AllocatorAwareContainer, - SequenceContainer and ReversibleContainer. + 1. ↑ In libstdc++, shrink_to_fit() is not available in C++98 mode. .SH Template parameters The type of the elements. - T must meet the requirements of CopyAssignable and \fI(until C++11)\fP - CopyConstructible. - The requirements that are imposed on the elements depend - T - on the actual operations performed on the container. - Generally, it is required that element type meets the \fI(since C++11)\fP - requirements of MoveConstructible and MoveAssignable, but - many member functions impose stricter requirements. + T must meet the requirements of CopyAssignable and (until + CopyConstructible. C++11) + The requirements that are imposed on the elements depend on the (since + actual operations performed on the container. Generally, it is C++11) + required that element type is a complete type and meets the (until + requirements of Erasable, but many member functions impose C++17) + stricter requirements. + The requirements that are imposed on the elements depend on the + actual operations performed on the container. Generally, it is + T - required that element type meets the requirements of Erasable, but + many member functions impose stricter requirements. This container + (but not its members) can be instantiated with an incomplete + element type if the allocator satisfies the allocator completeness (since + requirements. C++17) - - Allocator - An allocator that is used to acquire memory to store the elements. The - type must meet the requirements of Allocator. + Feature-test macro Value Std Feature + Minimal + __cpp_lib_incomplete_container_elements 201505L \fI(C++17)\fP incomplete + type + support + + + An allocator that is used to acquire/release memory and to + construct/destroy the elements in that memory. The type must meet the + requirements of Allocator. + Allocator - The behavior is undefined + \fI(until C++20)\fP + The program is ill-formed + \fI(since C++20)\fP if Allocator::value_type is not the same as T. .SH Specializations The standard library provides a specialization of std::vector for the type bool, - which is optimized for space efficiency. + which may be optimized for space efficiency. vector space-efficient dynamic bitset - \fI(class template specialization)\fP + \fI(class template specialization)\fP + + Iterator invalidation + + Operations Invalidated + All read only operations Never. + swap, std::swap end() + clear, operator=, assign Always. + reserve, shrink_to_fit If the vector changed capacity, all of them. If not, none. + erase Erased elements and all elements after them (including + end()). + push_back, emplace_back If the vector changed capacity, all of them. If not, only + end(). + If the vector changed capacity, all of them. + insert, emplace If not, only those at or after the insertion point + (including end()). + resize If the vector changed capacity, all of them. If not, only + end() and any elements erased. + pop_back The element erased and end(). .SH Member types Member type Definition - value_type T - allocator_type Allocator - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP + value_type T + allocator_type Allocator + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator RandomAccessIterator - const_iterator Constant random access iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator, + iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator, + const_iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator .SH Member functions constructor constructs the vector - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the vector - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + assign_range assigns a range of values to the container + (C++23) \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH Element access at access specified element with bounds checking - \fI(public member function)\fP + \fI(public member function)\fP operator[] access specified element - \fI(public member function)\fP + \fI(public member function)\fP front access the first element - \fI(public member function)\fP + \fI(public member function)\fP back access the last element - \fI(public member function)\fP - data direct access to the underlying array - \fI(C++11)\fP \fI(public member function)\fP + \fI(public member function)\fP + data direct access to the underlying contiguous storage + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP + \fI(C++11)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + \fI(C++11)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP reserve reserves storage - \fI(public member function)\fP + \fI(public member function)\fP returns the number of elements that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP shrink_to_fit reduces memory usage by freeing unused memory - \fI(C++11)\fP \fI(public member function)\fP + (DR*) \fI(public member function)\fP .SH Modifiers clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP erase erases elements - \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP - emplace_back constructs elements in-place at the end - \fI(C++11)\fP \fI(public member function)\fP + \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP pop_back removes the last element - \fI(public member function)\fP + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the vector - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two vectors + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::vector) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase(std::vector) erases all elements satisfying specific criteria + erase_if(std::vector) \fI(function template)\fP + (C++20) + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Create a vector containing integers + std::vector v = {8, 4, 5, 9}; + + // Add two more integers to vector + v.push_back(6); + v.push_back(9); + + // Overwrite element at position 2 + v[2] = -1; + + // Print out the vector + for (int n : v) + std::cout << n << ' '; + std::cout << '\\n'; + } + +.SH Output: + + 8 4 -1 9 6 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 69 C++98 contiguity of the storage for elements of required + vector was not required + T was not required to be CopyConstructible T is also required to + LWG 230 C++98 (an element of type T might not be able to be CopyConstructible + be constructed) + LWG 464 C++98 access to the underlying storage of an data function provided + empty vector resulted in UB diff --git a/man/std::vector::append_range.3 b/man/std::vector::append_range.3 new file mode 100644 index 000000000..ac5f251c0 --- /dev/null +++ b/man/std::vector::append_range.3 @@ -0,0 +1,80 @@ +.TH std::vector::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::append_range \- std::vector::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr void append_range( R&& rg ); + + Inserts copies of elements from the range rg before end(), in non-reversing order. + + If after the operation the new size() is greater than old capacity() a reallocation + takes place, in which case all iterators (including the end() iterator) and all + references to the elements are invalidated. Otherwise only the end() iterator is + invalidated. + + Each iterator in rg is dereferenced exactly once. + +.SH Parameters + + rg - a container compatible range, that is, an input_range + whose elements are convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into vector from *ranges::begin(rg). Also, T must be + MoveInsertable into vector. Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + If reallocation happens, linear in the number of elements of the resulting vector; + otherwise, linear in the number of elements inserted plus the distance to the end(). + +.SH Exceptions + + If an exception is thrown other than by the copy constructor, move constructor, + assignment operator, or move assignment operator of T or by any InputIterator + operation there are no effects. If an exception is thrown while inserting a single + element at the end and T is CopyInsertable or + std::is_nothrow_move_constructible_v is true, there are no effects. Otherwise, if + an exception is thrown by the move constructor of a non-CopyInsertable T, the + effects are unspecified. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + auto head = std::vector{1, 2, 3, 4}; + const auto tail = std::list{-5, -6, -7}; + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.insert(head.end(), tail.cbegin(), tail.cend()); + #endif + assert(std::ranges::equal(head, std::vector{1, 2, 3, 4, -5, -6, -7})); + } + +.SH See also + + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::vector::assign.3 b/man/std::vector::assign.3 index 77a2d8114..7a91f1adc 100644 --- a/man/std::vector::assign.3 +++ b/man/std::vector::assign.3 @@ -1,64 +1,83 @@ -.TH std::vector::assign 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::assign \- std::vector::assign + .SH Synopsis - void assign( size_type count, const T& value ); \fB(1)\fP - template< class InputIt > \fB(2)\fP + void assign( size_type count, const T& value ); \fB(1)\fP (constexpr since C++20) + template< class InputIt > \fB(2)\fP (constexpr since C++20) void assign( InputIt first, InputIt last ); void assign( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) Replaces the contents of the container. - 1) Replaces the contents with count copies of value value - 2) Replaces the contents with copies of those in the range [first, last) + 1) Replaces the contents with count copies of value value. + 2) Replaces the contents with copies of those in the range [first, last). The + behavior is undefined if either argument is an iterator into *this. + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + 3) Replaces the contents with the elements from the initializer list ilist. + All iterators, pointers and references to the elements of the container are + invalidated. The past-the-end iterator is also invalidated. + .SH Parameters count - the new size of the container value - the value to initialize elements of the container with first, last - the range to copy the elements from ilist - initializer list to copy the values from -.SH Type requirements - - - InputIt must meet the requirements of InputIterator. .SH Complexity - 1) Linear in count - 2) Linear in distance between first and last - 3) Linear in ilist.size() + 1) Linear in count. + 2) Linear in distance between first and last. + 3) Linear in ilist.size(). .SH Example The following code uses assign to add several characters to a std::vector: - + // Run this code #include #include - + #include + int main() { std::vector characters; - + + auto print_vector = [&]() + { + for (char c : characters) + std::cout << c << ' '; + std::cout << '\\n'; + }; + characters.assign(5, 'a'); - - for (char c : characters) { - std::cout << c << '\\n'; - } - - return 0; + print_vector(); + + const std::string extra(6, 'b'); + characters.assign(extra.begin(), extra.end()); + print_vector(); + + characters.assign({'C', '+', '+', '1', '1'}); + print_vector(); } .SH Output: - a - a - a - a - a + a a a a a + b b b b b b + C + + 1 1 .SH See also constructor constructs the vector - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::assign_range.3 b/man/std::vector::assign_range.3 new file mode 100644 index 000000000..78ef1d0e2 --- /dev/null +++ b/man/std::vector::assign_range.3 @@ -0,0 +1,69 @@ +.TH std::vector::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::assign_range \- std::vector::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr void assign_range( R&& rg ); + + Replaces elements in the container with a copy of each element in rg. + + All iterators (including the end() iterator) and references to the elements are + invalidated. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + rg - an input_range with reference type convertible to + the element type of the container +.SH Type requirements + - + std::assignable_from> must be modeled. Otherwise, + the program is ill-formed. + - + T must be EmplaceConstructible into the container from *ranges::begin(rg). If R + models neither sized_range nor forward_range, T must be also MoveInsertable into the + container. Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const auto source = std::list{2, 7, 1}; + auto destination = std::vector{3, 1, 4}; + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.cbegin(), source.cend()); + #endif + assert(std::ranges::equal(source, destination)); + } + +.SH See also + + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP + assign assigns values to the container + \fI(public member function)\fP diff --git a/man/std::vector::at.3 b/man/std::vector::at.3 index 8d71e4e4c..d6678b9b2 100644 --- a/man/std::vector::at.3 +++ b/man/std::vector::at.3 @@ -1,12 +1,15 @@ -.TH std::vector::at 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::at \- std::vector::at + .SH Synopsis - reference at( size_type pos ); - const_reference at( size_type pos ) const; + reference at( size_type pos ); \fB(1)\fP (constexpr since C++20) + const_reference at( size_type pos ) const; \fB(2)\fP (constexpr since C++20) Returns a reference to the element at specified location pos, with bounds checking. - If pos not within the range of the container, an exception of type std::out_of_range - is thrown. + If pos is not within the range of the container, an exception of type + std::out_of_range is thrown. .SH Parameters @@ -18,13 +21,66 @@ .SH Exceptions - std::out_of_range if !(pos < size()). + std::out_of_range if pos >= size(). .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + #ifdef __GNUG__ + [[gnu::noinline]] + #endif + unsigned int runtime_six() // Emulate runtime input + { + return 6u; + } + + int main() + { + std::vector data = {1, 2, 4, 5, 5, 6}; + + // Set element 1 + data.at(1) = 88; + + // Read element 2 + std::cout << "Element at index 2 has value " << data.at(2) << '\\n'; + + std::cout << "data size = " << data.size() << '\\n'; + + try + { + // Set element 6, where the index is determined at runtime + data.at(runtime_six()) = 666; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + + // Print final values + std::cout << "data:"; + for (int elem : data) + std::cout << ' ' << elem; + std::cout << '\\n'; + } + +.SH Possible output: + + Element at index 2 has value 4 + data size = 6 + vector::_M_range_check: __n (which is 6) >= this->size() (which is 6) + data: 1 88 4 5 5 6 + .SH See also operator[] access specified element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::back.3 b/man/std::vector::back.3 index b5daea9ea..63cf59fbd 100644 --- a/man/std::vector::back.3 +++ b/man/std::vector::back.3 @@ -1,11 +1,14 @@ -.TH std::vector::back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::back \- std::vector::back + .SH Synopsis - reference back(); - const_reference back() const; + reference back(); \fB(1)\fP (constexpr since C++20) + const_reference back() const; \fB(2)\fP (constexpr since C++20) - Returns reference to the last element in the container. + Returns a reference to the last element in the container. - Calling back on an empty container is undefined. + Calling back on an empty container causes undefined behavior. .SH Parameters @@ -21,32 +24,32 @@ .SH Notes - For a container c, the expression return c.back(); is equivalent to { auto tmp = - c.end(); --tmp; return *tmp; } + For a non-empty container c, the expression c.back() is equivalent to + *std::prev(c.end()). .SH Example The following code uses back to display the last element of a std::vector: - + // Run this code #include #include - + int main() { - std::vector letters {'o', 'm', 'g', 'w', 't', 'f'}; - if (!letters.empty()) { - std::cout << "The last character is: " << letters.back() << '\\n'; - } + std::vector letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The last character is '" << letters.back() << "'.\\n"; } .SH Output: - The last character is f + The last character is 'f'. .SH See also front access the first element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::begin,std::vector::cbegin.3 b/man/std::vector::begin,std::vector::cbegin.3 index 9b97d0d28..a69580a0a 100644 --- a/man/std::vector::begin,std::vector::cbegin.3 +++ b/man/std::vector::begin,std::vector::cbegin.3 @@ -1,12 +1,18 @@ -.TH std::vector::begin,std::vector::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::begin,std::vector::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::begin,std::vector::cbegin \- std::vector::begin,std::vector::cbegin + .SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the vector. - If the container is empty, the returned iterator will be equal to end(). + If the vector is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,20 +22,62 @@ .SH Return value - Iterator to the first element + Iterator to the first element. + +.SH Complexity -.SH Exceptions + Constant. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - +.SH Notes -.SH Complexity + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector nums{1, 2, 4, 8, 16}; + std::vector fruits{"orange", "apple", "raspberry"}; + std::vector empty; + + // Print vector. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the vector nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the vector fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "vector 'empty' is indeed empty.\\n"; + } + +.SH Output: - Constant + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + vector 'empty' is indeed empty. .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::vector::capacity.3 b/man/std::vector::capacity.3 index cb09487fb..a41086d20 100644 --- a/man/std::vector::capacity.3 +++ b/man/std::vector::capacity.3 @@ -1,6 +1,10 @@ -.TH std::vector::capacity 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::capacity \- std::vector::capacity + .SH Synopsis - size_type capacity() const; + size_type capacity() const; (noexcept since C++11) + (constexpr since C++20) Returns the number of elements that the container has currently allocated space for. @@ -12,20 +16,64 @@ Capacity of the currently allocated storage. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + int sz = 100; + std::vector v; + + auto cap = v.capacity(); + std::cout << "Initial size: " << v.size() << ", capacity: " << cap << '\\n'; + + std::cout << "\\nDemonstrate the capacity's growth policy." + "\\nSize: Capacity: Ratio:\\n" << std::left; + while (sz-- > 0) + { + v.push_back(sz); + if (cap != v.capacity()) + { + std::cout << std::setw( 7) << v.size() + << std::setw(11) << v.capacity() + << std::setw(10) << v.capacity() / static_cast(cap) << '\\n'; + cap = v.capacity(); + } + } + + std::cout << "\\nFinal size: " << v.size() << ", capacity: " << v.capacity() << '\\n'; + } + +.SH Possible output: + + Initial size: 0, capacity: 0 + + Demonstrate the capacity's growth policy. + Size: Capacity: Ratio: + 1 1 inf + 2 2 2 + 3 4 2 + 5 8 2 + 9 16 2 + 17 32 2 + 33 64 2 + 65 128 2 + + Final size: 100, capacity: 128 + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP reserve reserves storage - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::clear.3 b/man/std::vector::clear.3 index b325fbba8..58d10a3d2 100644 --- a/man/std::vector::clear.3 +++ b/man/std::vector::clear.3 @@ -1,13 +1,18 @@ -.TH std::vector::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::clear \- std::vector::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) + (constexpr since C++20) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterators are also invalidated. - Leaves the capacity() of the vector unchanged. + Leaves the capacity() of the vector unchanged (Note: the standard's restriction on + the changes to capacity is in the specification of reserve(), see SO). .SH Parameters @@ -17,22 +22,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::vector& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << ", Capacity=" << v.capacity() << '\\n'; + } + + int main() + { + std::vector container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3, Capacity=3 + After clear: { } + Size=0, Capacity=3 + + Defect reports - Linear in the size of the container. + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - clear is defined in terms of erase, which has linear complexity. \fI(until C++11)\fP - complexity of clear is omitted \fI(since C++11)\fP - clear has linear complexity for sequence containers. \fI(since C++14)\fP + DR Applied to Behavior as published Correct behavior + LWG 2231 C++11 complexity guarantee was mistakenly complexity reaffirmed as + omitted in C++11 linear .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::data.3 b/man/std::vector::data.3 index 1513f89a8..5e6ae25c3 100644 --- a/man/std::vector::data.3 +++ b/man/std::vector::data.3 @@ -1,11 +1,16 @@ -.TH std::vector::data 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::data \- std::vector::data + .SH Synopsis - T* data(); - const T* data() const; + T* data(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const T* data() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) Returns pointer to the underlying array serving as element storage. The pointer is - such that range [data(); data() + size()) is always a valid range, even if the - container is empty. + such that range [data(), data() + size()) is always a valid range, even if the + container is empty (data() is not dereferenceable in that case). .SH Parameters @@ -13,23 +18,79 @@ .SH Return value - Pointer to the underlying element storage. For non-empty containers, returns - &front() + Pointer to the underlying element storage. For non-empty containers, the returned + pointer compares equal to the address of the first element. .SH Complexity Constant. -.SH Exceptions +.SH Notes + + If size() is 0, data() may or may not return a null pointer. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void pointer_func(const int* p, std::size_t size) + { + std::cout << "data = "; + for (std::size_t i = 0; i < size; ++i) + std::cout << p[i] << ' '; + std::cout << '\\n'; + } + + void span_func(std::span data) // since C++20 + { + std::cout << "data = "; + for (const int e : data) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + std::vector container{1, 2, 3, 4}; + + // Prefer container.data() over &container[0] + pointer_func(container.data(), container.size()); + + // std::span (C++20) is a safer alternative to separated pointer/size. + span_func({container.data(), container.size()}); + } + +.SH Output: + + data = 1 2 3 4 + data = 1 2 3 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + DR Applied to Behavior as published Correct behavior + LWG 464 C++98 vector did not have this member added + function + LWG 1312 C++98 the return type were pointer and changed to T* and const T* + const_pointer respectively .SH See also - front access the first element - \fI(public member function)\fP - back access the last element - \fI(public member function)\fP + front access the first element + \fI(public member function)\fP + back access the last element + \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + data obtains the pointer to the underlying array + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::vector::emplace.3 b/man/std::vector::emplace.3 index 730580b9d..90aed983a 100644 --- a/man/std::vector::emplace.3 +++ b/man/std::vector::emplace.3 @@ -1,21 +1,36 @@ -.TH std::vector::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::emplace \- std::vector::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP - iterator emplace( const_iterator pos, Args&&... args ); + iterator emplace( const_iterator pos, Args&&... args ); (constexpr since C++20) + + Inserts a new element into the container directly before pos. + + The element is constructed through std::allocator_traits::construct, which typically + uses placement-new to construct the element in-place at a location provided by the + container. However, if the required location has been occupied by an existing + element, the inserted element is constructed at another location at first, and then + move assigned into the required location. - Inserts a new element into the container directly before pos. The element is - constructed in-place, i.e. no copy or move operations are performed. The constructor - of the element is called with the arguments std::forward(args).... The element - type must be EmplaceConstructible, MoveInsertable and MoveAssignable. + The arguments args... are forwarded to the constructor as + std::forward(args).... args... may directly or indirectly refer to a value in + the container. - If the new size() is greater than capacity(), all iterators and references are - invalidated. Otherwise, only the iterators and references before the insertion point - remain valid. The past-the-end iterator is also invalidated. + If after the operation the new size() is greater than old capacity() a reallocation + takes place, in which case all iterators (including the end() iterator) and all + references to the elements are invalidated. Otherwise, only the iterators and + references before the insertion point remain valid. .SH Parameters - pos - iterator before which the new element will be constructed - args - arguments to forward to the constructor of the element + pos - iterator before which the new element will be constructed + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of MoveAssignable, + MoveInsertable and EmplaceConstructible. .SH Return value @@ -27,14 +42,98 @@ .SH Exceptions - If an exception is thrown (e.g. by the constructor), the container is left - unmodified, as if this function was never called \fI(strong exception guarantee)\fP. + If an exception is thrown other than by the copy constructor, move constructor, + assignment operator, or move assignment operator of the value type, or if an + exception is thrown while emplace is used to insert a single element at the end and + the value type is either CopyInsertable or nothrow move constructible, there are no + effects \fI(strong exception guarantee)\fP. + + Otherwise, the effects are unspecified. + +.SH Example + + +// Run this code + + #include + #include + #include + + struct A + { + std::string s; + + A(std::string str) : s(std::move(str)) { std::cout << " constructed\\n"; } + + A(const A& o) : s(o.s) { std::cout << " copy constructed\\n"; } + + A(A&& o) : s(std::move(o.s)) { std::cout << " move constructed\\n"; } + + A& operator=(const A& other) + { + s = other.s; + std::cout << " copy assigned\\n"; + return *this; + } + + A& operator=(A&& other) + { + s = std::move(other.s); + std::cout << " move assigned\\n"; + return *this; + } + }; + + int main() + { + std::vector container; + // reserve enough place so vector does not have to resize + container.reserve(10); + std::cout << "construct 2 times A:\\n"; + A two { "two" }; + A three { "three" }; + + std::cout << "emplace:\\n"; + container.emplace(container.end(), "one"); + + std::cout << "emplace with A&:\\n"; + container.emplace(container.end(), two); + + std::cout << "emplace with A&&:\\n"; + container.emplace(container.end(), std::move(three)); + + std::cout << "content:\\n"; + for (const auto& obj : container) + std::cout << ' ' << obj.s; + std::cout << '\\n'; + } + +.SH Output: + + construct 2 times A: + constructed + constructed + emplace: + constructed + emplace with A&: + copy constructed + emplace with A&&: + move constructed + content: + one two three + + Defect reports -.SH Notes + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - The specialization std::vector did not have emplace() member until C++14. + DR Applied to Behavior as published Correct behavior + LWG 2164 C++11 it was not clear whether the arguments can clarified + refer to the container .SH See also - insert inserts elements - \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::vector::emplace_back.3 b/man/std::vector::emplace_back.3 index 969b301b4..9a6b15de2 100644 --- a/man/std::vector::emplace_back.3 +++ b/man/std::vector::emplace_back.3 @@ -1,38 +1,51 @@ -.TH std::vector::emplace_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::emplace_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::emplace_back \- std::vector::emplace_back + .SH Synopsis - template< class... Args > \fI(since C++11)\fP - void emplace_back( Args&&... args ); + template< class... Args > \fI(since C++11)\fP + void emplace_back( Args&&... args ); \fI(until C++17)\fP + template< class... Args > \fI(since C++17)\fP + reference emplace_back( Args&&... args ); (constexpr since C++20) Appends a new element to the end of the container. The element is constructed - in-place, i.e. no copy or move operations are performed. The constructor of the - element is called with exactly the same arguments that are supplied to the function. + through std::allocator_traits::construct, which typically uses placement-new to + construct the element in-place at the location provided by the container. The + arguments args... are forwarded to the constructor as std::forward(args).... - If the new size() is greater than capacity() then all iterators and references - (including the past-the-end iterator) are invalidated. Otherwise only the - past-the-end iterator is invalidated. + If after the operation the new size() is greater than old capacity() a reallocation + takes place, in which case all iterators (including the end() iterator) and all + references to the elements are invalidated. Otherwise only the end() iterator is + invalidated. .SH Parameters - args - arguments to forward to the constructor of the element + args - arguments to forward to the constructor of the element +.SH Type requirements + - + T (the container's element type) must meet the requirements of MoveInsertable and + EmplaceConstructible. .SH Return value - \fI(none)\fP + \fI(none)\fP \fI(until C++17)\fP + A reference to the inserted element. \fI(since C++17)\fP .SH Complexity - Constant. + Amortized constant. .SH Exceptions If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. - If T's move constructor is not noexcept and the copy constructor is not accessible, - vector will use the throwing move constructor. If it throws, the guarantee is waived - and the effects are unspecified. + If T's move constructor is not noexcept and is not CopyInsertable into *this, vector + will use the throwing move constructor. If it throws, the guarantee is waived and + the effects are unspecified. .SH Notes - The specialization std::vector did not have emplace_back() member until C++14. + Since reallocation may take place, emplace_back requires the element type to be + MoveInsertable for vectors. .SH Example @@ -41,67 +54,72 @@ constructor and shows how using emplace_back avoids the extra copy or move operation required when using push_back. - + // Run this code #include - #include + #include #include - + #include + struct President { std::string name; std::string country; int year; - + President(std::string p_name, std::string p_country, int p_year) : name(std::move(p_name)), country(std::move(p_country)), year(p_year) { std::cout << "I am being constructed.\\n"; } + President(President&& other) : name(std::move(other.name)), country(std::move(other.country)), year(other.year) { std::cout << "I am being moved.\\n"; } + President& operator=(const President& other) = default; }; - + int main() { std::vector elections; std::cout << "emplace_back:\\n"; - elections.emplace_back("Nelson Mandela", "South Africa", 1994); - + auto& ref = elections.emplace_back("Nelson Mandela", "South Africa", 1994); + assert(ref.year == 1994 && "uses a reference to the created object \fI(C++17)\fP"); + std::vector reElections; std::cout << "\\npush_back:\\n"; reElections.push_back(President("Franklin Delano Roosevelt", "the USA", 1936)); - + std::cout << "\\nContents:\\n"; - for (President const& president: elections) { + for (President const& president: elections) std::cout << president.name << " was elected president of " << president.country << " in " << president.year << ".\\n"; - } - for (President const& president: reElections) { + + for (President const& president: reElections) std::cout << president.name << " was re-elected president of " << president.country << " in " << president.year << ".\\n"; - } } .SH Output: emplace_back: I am being constructed. - + push_back: I am being constructed. I am being moved. - + .SH Contents: Nelson Mandela was elected president of South Africa in 1994. Franklin Delano Roosevelt was re-elected president of the USA in 1936. .SH See also - push_back adds elements to the end - \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + emplace constructs element in-place + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::vector::empty.3 b/man/std::vector::empty.3 index 7ff3ba129..c9f06fbf8 100644 --- a/man/std::vector::empty.3 +++ b/man/std::vector::empty.3 @@ -1,6 +1,10 @@ -.TH std::vector::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::empty \- std::vector::empty + .SH Synopsis - bool empty() const; + bool empty() const; (noexcept since C++11) + (constexpr since C++20) Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +14,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,32 +22,31 @@ .SH Example - - The following code uses empty to check if a std::vector contains any elements: - // Run this code #include #include - + int main() { + std::cout << std::boolalpha; std::vector numbers; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.push_back(42); - numbers.push_back(13317); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; } .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::vector::end,std::vector::cend.3 b/man/std::vector::end,std::vector::cend.3 index befbd8e58..c7c626c38 100644 --- a/man/std::vector::end,std::vector::cend.3 +++ b/man/std::vector::end,std::vector::cend.3 @@ -1,10 +1,21 @@ -.TH std::vector::end,std::vector::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::end,std::vector::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::end,std::vector::cend \- std::vector::end,std::vector::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fI(until C++11)\fP + \fI(since C++11)\fP + iterator end() noexcept; (constexpr since + C++20) + const_iterator end() const; \fI(until C++11)\fP + const_iterator end() const \fB(1)\fP \fI(since C++11)\fP + noexcept; (constexpr since + \fB(2)\fP C++20) + const_iterator cend() const \fI(since C++11)\fP + noexcept; \fB(3)\fP (constexpr since + C++20) - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the vector. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +30,60 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector nums{1, 2, 4, 8, 16}; + std::vector fruits{"orange", "apple", "raspberry"}; + std::vector empty; + + // Print vector. + std::for_each(nums.begin(), nums.end(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the vector nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.begin(), nums.end(), 0) << '\\n'; + + // Prints the first fruit in the vector fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.begin() << '\\n'; + + if (empty.begin() == empty.end()) + std::cout << "vector 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 1 2 4 8 16 + Sum of nums: 31 + First fruit: orange + vector 'empty' is indeed empty. + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::vector::erase.3 b/man/std::vector::erase.3 index e88cac1a0..d9a574683 100644 --- a/man/std::vector::erase.3 +++ b/man/std::vector::erase.3 @@ -1,61 +1,103 @@ -.TH std::vector::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - iterator erase( iterator pos ); \fI(until C++11)\fP - iterator erase( const_iterator pos ); \fI(since C++11)\fP - iterator erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP - iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP - const_iterator last ); +.TH std::vector::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::erase \- std::vector::erase - Removes specified elements from the container. +.SH Synopsis + iterator erase( iterator pos ); \fI(until C++11)\fP + \fI(since C++11)\fP + iterator erase( const_iterator pos ); (constexpr since + C++20) + iterator erase( iterator first, iterator \fB(1)\fP \fI(until C++11)\fP + last ); + iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP + const_iterator last ); (constexpr since + C++20) + + Erases the specified elements from the container. 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). + 2) Removes the elements in the range [first, last). - Invalidates iterators and references at or after the point of the erase, including - the end() iterator. + Iterators (including the end() iterator) and references to the elements at or after + the point of the erase are invalidated. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. + + The iterator first does not need to be dereferenceable if first == last: erasing an + empty range is a no-op. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove +.SH Type requirements + - + T must meet the requirements of MoveAssignable. .SH Return value Iterator following the last removed element. + 1) If pos refers to the last element, then the end() iterator is returned. + 2) If last == end() prior to removal, then the updated end() iterator is returned. + If [first, last) is an empty range, then last is returned. + +.SH Exceptions + + Does not throw unless an exception is thrown by the assignment operator of T. + +.SH Complexity + + Linear: the number of calls to the destructor of T is the same as the number of + elements erased, the assignment operator of T is called the number of times equal to + the number of elements in the vector after the erased elements. + +.SH Notes + + When container elements need to be erased based on a predicate, rather than + iterating the container and calling unary erase, the iterator range overload is + generally used with std::remove()/std::remove_if() to minimise the number of moves + of the remaining (non-removed) elements, this is the erase-remove idiom. + std::erase_if() replaces the erase-remove idiom. + \fI(since C++20)\fP + .SH Example - + // Run this code #include #include - - - int main( ) + + + void print_container(const std::vector& c) { - std::vector c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; - for (auto &i : c) { - std::cout << i << " "; - } + for (int i : c) + std::cout << i << ' '; std::cout << '\\n'; - + } + + int main() + { + std::vector c{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}; + print_container(c); + c.erase(c.begin()); - - for (auto &i : c) { - std::cout << i << " "; - } - std::cout << '\\n'; - - c.erase(c.begin()+2, c.begin()+5); - - for (auto &i : c) { - std::cout << i << " "; + print_container(c); + + c.erase(c.begin() + 2, c.begin() + 5); + print_container(c); + + // Erase all even numbers + for (std::vector::iterator it = c.begin(); it != c.end();) + { + if (*it % 2 == 0) + it = c.erase(it); + else + ++it; } - std::cout << '\\n'; + print_container(c); } .SH Output: @@ -63,13 +105,25 @@ 0 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 1 2 6 7 8 9 + 1 7 9 -.SH Complexity + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - 1) Linear in the distance between position and last. - 2) Linear in distance between position and the end of the container. + DR Applied to Behavior as published Correct behavior + first was required to be + LWG 151 C++98 dereferenceable, which not required if + made the behavior of clearing an empty first == last + vector undefined + LWG 414 C++98 iterators at the point of erase were they are also invalidated + not invalidated .SH See also - clear clears the contents - \fI(public member function)\fP + erase(std::vector) erases all elements satisfying specific criteria + erase_if(std::vector) \fI(function template)\fP + (C++20) + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::vector::flip.3 b/man/std::vector::flip.3 new file mode 100644 index 000000000..a1a4ae500 --- /dev/null +++ b/man/std::vector::flip.3 @@ -0,0 +1,53 @@ +.TH std::vector::flip 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::flip \- std::vector::flip + +.SH Synopsis + Defined in header + void flip(); \fI(until C++20)\fP + constexpr void flip(); \fI(since C++20)\fP + + Toggles each bool in the vector (replaces with its opposite value). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + + void print(const std::vector& vb) + { + for (const bool b : vb) + std::cout << b; + std::cout << '\\n'; + } + + int main() + { + std::vector v{0, 1, 0, 1}; + print(v); + v.flip(); + print(v); + } + +.SH Output: + + 0101 + 1010 + +.SH See also + + operator[] access specified element + \fI(public member function of std::vector)\fP + flip toggles the values of bits + \fI(public member function of std::bitset)\fP diff --git a/man/std::vector::front.3 b/man/std::vector::front.3 index 3051007f2..ccd686ba0 100644 --- a/man/std::vector::front.3 +++ b/man/std::vector::front.3 @@ -1,11 +1,14 @@ -.TH std::vector::front 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::front \- std::vector::front + .SH Synopsis - reference front(); - const_reference front() const; + reference front(); \fB(1)\fP (constexpr since C++20) + const_reference front() const; \fB(2)\fP (constexpr since C++20) Returns a reference to the first element in the container. - Calling front on an empty container is undefined. + Calling front on an empty container causes undefined behavior. .SH Parameters @@ -13,11 +16,11 @@ .SH Return value - reference to the first element + Reference to the first element. .SH Complexity - Constant + Constant. .SH Notes @@ -27,26 +30,25 @@ The following code uses front to display the first element of a std::vector: - + // Run this code #include #include - + int main() { - std::vector letters {'o', 'm', 'g', 'w', 't', 'f'}; - - if (!letters.empty()) { - std::cout << "The first character is: " << letters.front() << '\\n'; - } + std::vector letters{'a', 'b', 'c', 'd', 'e', 'f'}; + + if (!letters.empty()) + std::cout << "The first character is '" << letters.front() << "'.\\n"; } .SH Output: - The first character is o + The first character is 'a'. .SH See also back access the last element - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::get_allocator.3 b/man/std::vector::get_allocator.3 index d0665973b..cc088bc8b 100644 --- a/man/std::vector::get_allocator.3 +++ b/man/std::vector::get_allocator.3 @@ -1,6 +1,10 @@ -.TH std::vector::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::get_allocator \- std::vector::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) + (constexpr since C++20) Returns the allocator associated with the container. diff --git a/man/std::vector::insert.3 b/man/std::vector::insert.3 index 4cdc2d423..19d12f382 100644 --- a/man/std::vector::insert.3 +++ b/man/std::vector::insert.3 @@ -1,116 +1,180 @@ -.TH std::vector::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::insert \- std::vector::insert + .SH Synopsis - iterator insert( iterator pos, const T& value ); (until - C++11) - iterator insert( const_iterator pos, const T& value (since - ); C++11) - iterator insert( const_iterator pos, T&& value ); \fB(2)\fP (since - C++11) - void insert( iterator pos, size_type count, const T& (until - value ); C++11) - iterator insert( const_iterator pos, size_type \fB(1)\fP (since - count, const T& value ); C++11) - template< class InputIt > (until - void insert( iterator pos, InputIt first, InputIt \fB(3)\fP C++11) - last); - template< class InputIt > \fB(4)\fP (since - iterator insert( const_iterator pos, InputIt first, C++11) + iterator insert( const_iterator pos, const T& value ); \fB(1)\fP (constexpr since C++20) + iterator insert( const_iterator pos, T&& value ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++20) + iterator insert( const_iterator pos, \fB(3)\fP (constexpr since C++20) + size_type count, const T& value ); + template< class InputIt > + iterator insert( const_iterator pos, InputIt first, \fB(4)\fP (constexpr since C++20) InputIt last ); - iterator insert( const_iterator pos, \fB(5)\fP (since - std::initializer_list ilist ); C++11) + iterator insert( const_iterator pos, \fB(5)\fP \fI(since C++11)\fP + std::initializer_list ilist ); (constexpr since C++20) + + Inserts elements at the specified location in the container. - Inserts elements at specified location in the container. + 1,2) Inserts value before pos. + 3) Inserts count copies of the value before pos. + 4) Inserts elements from range [first, last) before pos. - 1-2) inserts value before the location pointed to by pos - 3) inserts count copies of the value before the location pointed to by pos - 4) inserts elements from range [first, last) before the location pointed to by pos. - The behavior is undefined if first and last are iterators into *this. - 5) inserts elements from initializer list ilist. + This overload has the same effect as overload \fB(3)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload participates in overload resolution only if InputIt + qualifies as LegacyInputIterator, to avoid ambiguity with the overload \fI(since C++11)\fP + \fB(3)\fP. - Causes reallocation if the new size() is greater than the old capacity(). If the new - size() is greater than capacity(), all iterators and references are invalidated. - Otherwise, only the iterators and references before the insertion point remain - valid. The past-the-end iterator is also invalidated. + If first and last are iterators into *this, the behavior is undefined. + 5) Inserts elements from initializer list ilist before pos. + + If after the operation the new size() is greater than old capacity() a reallocation + takes place, in which case all iterators (including the end() iterator) and all + references to the elements are invalidated. Otherwise, only the iterators and + references before the insertion point remain valid. .SH Parameters - pos - iterator to the location before which the content will be inserted. - pos may be the end() iterator - value - element value to insert - first, last - the range of elements to insert, can't be iterators into container for - which insert is called - ilist - initializer list to insert the values from + pos - iterator before which the content will be inserted + (pos may be the end() iterator) + value - element value to insert + count - number of elements to insert + first, last - the range of elements to insert, cannot be iterators + into container for which insert is called + ilist - initializer list to insert the values from .SH Type requirements - - InputIt must meet the requirements of InputIterator. + T must meet the requirements of CopyAssignable and CopyInsertable in order to use + overload \fB(1)\fP. + - + T must meet the requirements of MoveAssignable and MoveInsertable in order to use + overload \fB(2)\fP. + - + T must meet the requirements of CopyAssignable and CopyInsertable in order to use + overload \fB(3)\fP. + - + T must meet the requirements of EmplaceConstructible in order to use overloads + (4,5). + - + T must meet the requirements of MoveAssignable and MoveInsertable in order to use + overload \fB(4)\fP. required only if InputIt satisfies LegacyInputIterator but not + LegacyForwardIterator. \fI(until C++17)\fP + - + T must meet the requirements of Swappable, MoveAssignable, MoveConstructible and + MoveInsertable in order to use overloads (4,5). \fI(since C++17)\fP .SH Return value - 1-2) Iterator pointing to the inserted value - 3) Iterator pointing to the first element inserted, or pos if count==0. - 4) Iterator pointing to the first element inserted, or pos if first==last. + 1,2) Iterator pointing to the inserted value. + 3) Iterator pointing to the first element inserted, or pos if count == 0. + 4) Iterator pointing to the first element inserted, or pos if first == last. 5) Iterator pointing to the first element inserted, or pos if ilist is empty. .SH Complexity - 1-2) Constant plus linear in the distance between pos and end of the container. + 1,2) Constant plus linear in the distance between pos and end of the container. 3) Linear in count plus linear in the distance between pos and end of the container. 4) Linear in std::distance(first, last) plus linear in the distance between pos and end of the container. 5) Linear in ilist.size() plus linear in the distance between pos and end of the container. +.SH Exceptions + + If an exception is thrown other than by + + * the copy constructor of T, + + * the move constructor of T, \fI(since C++11)\fP + + * the copy assignment operator of T, + + * the move assignment operator of T, \fI(since C++11)\fP + + * any InputIt operation, + + these functions have no effect (strong exception safety guarantee). + + If an exception is thrown when inserting a single element at the end, + and T is CopyInsertable or + std::is_nothrow_move_constructible::value is true, this function \fI(since C++11)\fP + has no effect \fI(strong exception guarantee)\fP. Otherwise, if an exception + is thrown by the move constructor of a non-CopyInsertable T, the + effects are unspecified. + .SH Example - + // Run this code #include + #include #include - - void print_vec(const std::vector& vec) + + void print(int id, const std::vector& container) { - for (auto x: vec) { - std::cout << ' ' << x; - } + std::cout << id << ". "; + for (const int x : container) + std::cout << x << ' '; std::cout << '\\n'; } - + int main () { - std::vector vec(3,100); - print_vec(vec); - - auto it = vec.begin(); - it = vec.insert(it, 200); - print_vec(vec); - - vec.insert(it,2,300); - print_vec(vec); - - // "it" no longer valid, get a new one: - it = vec.begin(); - - std::vector vec2(2,400); - vec.insert(it+2, vec2.begin(), vec2.end()); - print_vec(vec); - - int arr[] = { 501,502,503 }; - vec.insert(vec.begin(), arr, arr+3); - print_vec(vec); + std::vector c1(3, 100); + print(1, c1); + + auto it = c1.begin(); + it = c1.insert(it, 200); + print(2, c1); + + c1.insert(it, 2, 300); + print(3, c1); + + // `it` no longer valid, get a new one: + it = c1.begin(); + + std::vector c2(2, 400); + c1.insert(std::next(it, 2), c2.begin(), c2.end()); + print(4, c1); + + int arr[] = {501, 502, 503}; + c1.insert(c1.begin(), arr, arr + std::size(arr)); + print(5, c1); + + c1.insert(c1.end(), {601, 602, 603}); + print(6, c1); } .SH Output: - 100 100 100 - 200 100 100 100 - 300 300 200 100 100 100 - 300 300 400 400 200 100 100 100 - 501 502 503 300 300 400 400 200 100 100 100 + 1. 100 100 100 + 2. 200 100 100 100 + 3. 300 300 200 100 100 100 + 4. 300 300 400 400 200 100 100 100 + 5. 501 502 503 300 300 400 400 200 100 100 100 + 6. 501 502 503 300 300 400 400 200 100 100 100 601 602 603 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 149 C++98 overloads \fB(3)\fP and \fB(4)\fP returned nothing returns an iterator + LWG 247 C++98 the complexity was only specified for specified for all + overload \fB(3)\fP overloads + the strong exception guarantee also + LWG 406 C++98 applied if no guarantee in this case + the exception is thrown by an InputIt + operation .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - push_back adds elements to the end - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::vector::insert_range.3 b/man/std::vector::insert_range.3 new file mode 100644 index 000000000..00412f6ce --- /dev/null +++ b/man/std::vector::insert_range.3 @@ -0,0 +1,73 @@ +.TH std::vector::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::insert_range \- std::vector::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr iterator insert_range( const_iterator pos, R&& rg ); + + Inserts, in non-reversing order, copies of elements in rg before pos. + + If after the operation the new size() is greater than old capacity() a reallocation + takes place, in which case all iterators (including the end() iterator) and all + references to the elements are invalidated. Otherwise, only the iterators and + references before the insertion point remain valid. + + Each iterator in the range rg is dereferenced exactly once. + + The behavior is undefined if rg overlaps with the container. + +.SH Parameters + + pos - iterator before which the content will be inserted + (pos may be the end() iterator) + rg - a container compatible range, that is, an input_range + whose elements are convertible to T +.SH Type requirements + - + T must be EmplaceConstructible into vector from *ranges::begin(rg). Also, T must be + MoveInsertable into vector and T satisfies MoveConstructible, MoveAssignable, and + Swappable. Otherwise, the behavior is undefined. + +.SH Return value + + An iterator that points at the copy of the first element inserted into vector or at + pos if rg is empty. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + auto container = std::vector{1, 2, 3, 4}; + auto pos = std::next(container.begin(), 2); + assert(*pos == 3); + const auto rg = std::list{-1, -2, -3}; + + #ifdef __cpp_lib_containers_ranges + container.insert_range(pos, rg); + #else + container.insert(pos, rg.cbegin(), rg.cend()); + #endif + assert(std::ranges::equal(container, std::vector{1, 2, -1, -2, -3, 3, 4})); + } + +.SH See also + + insert inserts elements + \fI(public member function)\fP + append_range adds a range of elements to the end + (C++23) \fI(public member function)\fP diff --git a/man/std::vector::max_size.3 b/man/std::vector::max_size.3 index 6f1fabe94..2c3d5aa23 100644 --- a/man/std::vector::max_size.3 +++ b/man/std::vector::max_size.3 @@ -1,6 +1,10 @@ -.TH std::vector::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::max_size \- std::vector::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) + (constexpr since C++20) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,28 +18,48 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::vector p; + std::vector q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 9,223,372,036,854,775,807 = 0x7,FFF,FFF,FFF,FFF,FFF + q.max_size() = 1,152,921,504,606,846,975 = 0xFFF,FFF,FFF,FFF,FFF + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP returns the number of elements that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::operator=.3 b/man/std::vector::operator=.3 index a9221116d..07515afdd 100644 --- a/man/std::vector::operator=.3 +++ b/man/std::vector::operator=.3 @@ -1,27 +1,43 @@ -.TH std::vector::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::operator= \- std::vector::operator= + .SH Synopsis - vector& operator=( const vector& other ); \fB(1)\fP - vector& operator=( vector&& other ); \fB(2)\fP \fI(since C++11)\fP - vector& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + vector& operator=( const vector& other ); \fB(1)\fP (constexpr since + C++20) + vector& operator=( vector&& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + vector& operator=( vector&& other ) \fI(since C++17)\fP + noexcept(/* see below */); \fB(2)\fP + vector& operator=( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(3)\fP (constexpr since + C++20) Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,68 +51,99 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) Linear in the size of *this and ilist. + +.SH Exceptions + +1-3) May throw implementation-defined exceptions. (until + C++17) +1,3) May throw implementation-defined exceptions. +2) (since +noexcept specification: C++17) +noexcept(std::allocator_traits::propagate_on_container_move_assignment::value +|| std::allocator_traits::is_always_equal::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::vector to another: - The following code uses to assign one std::vector to another: - // Run this code - #include + #include #include - - void display_sizes(const std::vector& nums1, - const std::vector& nums2, - const std::vector& nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::vector nums1 {3, 1, 4, 6, 5, 9}; - std::vector nums2; - std::vector nums3; - + std::vector x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 1, 2, 3 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 1, 2, 3 } + y = { 1, 2, 3 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 1, 2, 3 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 4, 5, 6, 7 } .SH See also constructor constructs the vector - \fI(public member function)\fP + \fI(public member function)\fP assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::vector::operator[].3 b/man/std::vector::operator[].3 index 4d8ed1512..9ed0b145b 100644 --- a/man/std::vector::operator[].3 +++ b/man/std::vector::operator[].3 @@ -1,8 +1,10 @@ -.TH std::vector::operator[] 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::operator[] \- std::vector::operator[] + .SH Synopsis - reference operator[]( size_type pos ); - const_reference operator[]( size_type pos ) const; \fI(until C++14)\fP - constexpr const_reference operator[]( size_type pos ) const; \fI(since C++14)\fP + reference operator[]( size_type pos ); \fB(1)\fP (constexpr since C++20) + const_reference operator[]( size_type pos ) const; \fB(2)\fP (constexpr since C++20) Returns a reference to the element at specified location pos. No bounds checking is performed. @@ -19,31 +21,69 @@ Constant. +.SH Notes + + Unlike std::map::operator[], this operator never inserts a new element into the + container. Accessing a nonexistent element through this operator is undefined + behavior. + .SH Example - The following code uses operator[] read from and write to a std::vector: + The following code uses operator[] to read from and write to a std::vector: + - // Run this code #include #include - + int main() { - std::vector numbers {2, 4, 6, 8}; - + std::vector numbers{2, 4, 6, 8}; + std::cout << "Second element: " << numbers[1] << '\\n'; - + numbers[0] = 5; - + std::cout << "All numbers:"; - for (auto i : numbers) { + for (auto i : numbers) std::cout << ' ' << i; - } std::cout << '\\n'; } + // Since C++20 std::vector can be used in constexpr context: + #if defined(__cpp_lib_constexpr_vector) and defined(__cpp_consteval) + // Gets the sum of all primes in [0, N) using sieve of Eratosthenes + consteval auto sum_of_all_primes_up_to(unsigned N) + { + if (N < 2) + return 0ULL; + + std::vector is_prime(N, true); + is_prime[0] = is_prime[1] = false; + + auto propagate_non_primality = [&](decltype(N) n) + { + for (decltype(N) m = n + n; m < is_prime.size(); m += n) + is_prime[m] = false; + }; + + auto sum{0ULL}; + for (decltype(N) n{2}; n != N; ++n) + if (is_prime[n]) + { + sum += n; + propagate_non_primality(n); + } + + return sum; + } //< vector's memory is released here + + static_assert(sum_of_all_primes_up_to(42) == 0xEE); + static_assert(sum_of_all_primes_up_to(100) == 0x424); + static_assert(sum_of_all_primes_up_to(1001) == 76127); + #endif + .SH Output: Second element: 4 @@ -52,4 +92,4 @@ .SH See also at access specified element with bounds checking - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::pop_back.3 b/man/std::vector::pop_back.3 index fd7dc3bc4..c8f991e85 100644 --- a/man/std::vector::pop_back.3 +++ b/man/std::vector::pop_back.3 @@ -1,10 +1,16 @@ -.TH std::vector::pop_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::pop_back \- std::vector::pop_back + .SH Synopsis - void pop_back(); + void pop_back(); (constexpr since C++20) Removes the last element of the container. - No iterators or references except for back() and end() are invalidated. + Calling pop_back on an empty container results in undefined behavior. + + Iterators (including the end() iterator) and references to the last element are + invalidated. .SH Parameters @@ -18,7 +24,51 @@ Constant. +.SH Exceptions + + Throws nothing. + +.SH Example + + +// Run this code + + #include + #include + + template + void print(T const& xs) + { + std::cout << "[ "; + for (auto const& x : xs) + std::cout << x << ' '; + std::cout << "]\\n"; + } + + int main() + { + std::vector numbers; + + print(numbers); + + numbers.push_back(5); + numbers.push_back(3); + numbers.push_back(4); + + print(numbers); + + numbers.pop_back(); + + print(numbers); + } + +.SH Output: + + [ ] + [ 5 3 4 ] + [ 5 3 ] + .SH See also - push_back adds elements to the end - \fI(public member function)\fP + push_back adds an element to the end + \fI(public member function)\fP diff --git a/man/std::vector::push_back.3 b/man/std::vector::push_back.3 index a65b38a0a..b93777b16 100644 --- a/man/std::vector::push_back.3 +++ b/man/std::vector::push_back.3 @@ -1,16 +1,21 @@ -.TH std::vector::push_back 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::push_back \- std::vector::push_back + .SH Synopsis - void push_back( const T& value ); \fB(1)\fP + void push_back( const T& value ); \fB(1)\fP (constexpr since C++20) void push_back( T&& value ); \fB(2)\fP \fI(since C++11)\fP + (constexpr since C++20) Appends the given element value to the end of the container. 1) The new element is initialized as a copy of value. 2) value is moved into the new element. - If the new size() is greater than capacity() then all iterators and references - (including the past-the-end iterator) are invalidated. Otherwise only the - past-the-end iterator is invalidated. + If after the operation the new size() is greater than old capacity() a reallocation + takes place, in which case all iterators (including the end() iterator) and all + references to the elements are invalidated. Otherwise only the end() iterator is + invalidated. .SH Parameters @@ -31,44 +36,55 @@ .SH Exceptions - If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + If an exception is thrown (which can be due to Allocator::allocate() or element + copy/move constructor/assignment), this function has no effect (strong exception + guarantee). - If T's move constructor is not noexcept and the copy constructor is - not accessible, vector will use the throwing move constructor. If it \fI(since C++11)\fP + If T's move constructor is not noexcept and T is not CopyInsertable + into *this, vector will use the throwing move constructor. If it \fI(since C++11)\fP throws, the guarantee is waived and the effects are unspecified. +.SH Notes + + Some implementations throw std::length_error when push_back causes a reallocation + that exceeds max_size (due to an implicit call to an equivalent of reserve(size() + + 1)). + .SH Example - The following code uses push_back to add several integers to a std::vector: - // Run this code - #include + #include #include - + #include + #include + int main() { - std::vector numbers; - - numbers.push_back(42); - numbers.push_back(314159); - - for (int i : numbers) { // c++11 range-based for loop - std::cout << i << '\\n'; - } - - return 0; + std::vector letters; + + letters.push_back("abc"); + std::string s{"def"}; + letters.push_back(std::move(s)); + + std::cout << "std::vector letters holds: "; + for (auto&& e : letters) + std::cout << std::quoted(e) << ' '; + + std::cout << "\\nMoved-from string s holds: " << std::quoted(s) << '\\n'; } -.SH Output: +.SH Possible output: - 42 - 314159 + std::vector letters holds: "abc" "def" + Moved-from string s holds: "" .SH See also - emplace_back constructs elements in-place at the end - \fI(C++11)\fP \fI(public member function)\fP - pop_back removes the last element - \fI(public member function)\fP + emplace_back constructs an element in-place at the end + \fI(C++11)\fP \fI(public member function)\fP + pop_back removes the last element + \fI(public member function)\fP + back_inserter creates a std::back_insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::vector::rbegin,std::vector::crbegin.3 b/man/std::vector::rbegin,std::vector::crbegin.3 index dad33f9ca..97c7a4d86 100644 --- a/man/std::vector::rbegin,std::vector::crbegin.3 +++ b/man/std::vector::rbegin,std::vector::crbegin.3 @@ -1,11 +1,18 @@ -.TH std::vector::rbegin,std::vector::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::rbegin,std::vector::crbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::rbegin,std::vector::crbegin \- std::vector::rbegin,std::vector::crbegin + .SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. + Returns a reverse iterator to the first element of the reversed vector. It + corresponds to the last element of the non-reversed vector. If the vector is empty, + the returned iterator is equal to rend(). range-rbegin-rend.svg @@ -17,18 +24,62 @@ Reverse iterator to the first element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector nums{1, 2, 4, 8, 16}; + std::vector fruits{"orange", "apple", "raspberry"}; + std::vector empty; + + // Print vector. + std::for_each(nums.rbegin(), nums.rend(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the vector nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.rbegin(), nums.rend(), 0) << '\\n'; + + // Prints the first fruit in the vector fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.rbegin() << '\\n'; + + if (empty.rbegin() == empty.rend()) + std::cout << "vector 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 16 8 4 2 1 + Sum of nums: 31 + First fruit: raspberry + vector 'empty' is indeed empty. + .SH See also - rend returns a reverse iterator to the end - crend \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::vector::reference.3 b/man/std::vector::reference.3 new file mode 100644 index 000000000..c6ea301a6 --- /dev/null +++ b/man/std::vector::reference.3 @@ -0,0 +1,147 @@ +.TH std::vector::reference 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::reference \- std::vector::reference + +.SH Synopsis + class reference; + + The std::vector specializations define std::vector::reference as a publicly-accessible nested class. std::vector::reference proxies the behavior of references to a single bit in + std::vector. + + The primary use of std::vector::reference is to provide an lvalue that + can be returned from operator[]. + + Any reads or writes to a vector that happen via a std::vector::reference potentially read or write to the entire underlying vector. + +.SH Member functions + + constructs the reference. Accessible only to std::vector + constructor itself + \fI(public member function)\fP + destructor destroys the reference + \fI(public member function)\fP + operator= assigns a bool to the referenced bit + \fI(public member function)\fP + operator bool returns the referenced bit + \fI(public member function)\fP + flip flips the referenced bit + \fI(public member function)\fP + +std::vector::reference::~reference + + ~reference(); \fI(until C++20)\fP + constexpr ~reference(); \fI(since C++20)\fP + + Destroys the reference. + +std::vector::reference::operator= + + reference& operator=( bool x ); \fI(until C++11)\fP + reference& operator=( bool x ) noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + constexpr reference& operator=( bool x ) \fI(since C++20)\fP + noexcept; + reference& operator=( const reference& x ); \fB(1)\fP \fI(until C++11)\fP + reference& operator=( const reference& x ) \fI(since C++11)\fP + noexcept; \fI(until C++20)\fP + constexpr reference& operator=( const reference& \fB(2)\fP \fI(since C++20)\fP + x ) noexcept; + constexpr const reference& operator=( bool x ) \fB(3)\fP (since C++23) + const noexcept; + + Assigns a value to the referenced bit. + +.SH Parameters + + x - value to assign + +.SH Return value + + *this + +std::vector::reference::operator bool + + operator bool() const; \fI(until C++11)\fP + operator bool() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + constexpr operator bool() const noexcept; \fI(since C++20)\fP + + Returns the value of the referenced bit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The referenced bit. + +std::vector::reference::flip + + void flip(); \fI(until C++11)\fP + void flip() noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + constexpr void flip() noexcept; \fI(since C++20)\fP + + Inverts the referenced bit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Helper classes + +std::formatter::reference> + + template < class T, class CharT > + + requires /* is-vector-bool-reference */ (since C++23) + + struct formatter; + + Specializes the std::formatter for std::vector::reference. The + specialization uses std::formatter as its underlying formatter (denoted + as underlying_) where the referenced bit is converted to bool to be formatted. + + The exposition-only constant /* is-vector-bool-reference */ is true if and only + if T denotes the type std::vector::reference for some type Alloc and + std::vector is not a program-defined specialization. + +.SH Member functions + + template< class ParseContext > \fB(1)\fP (since C++23) + constexpr ParseContext::iterator parse( ParseContext& ctx ); + template< class FormatContext > + FormatContext::iterator format( const T& r, FormatContext& ctx ) \fB(2)\fP (since C++23) + const; + + 1) Equivalent to return underlying_.parse(ctx);. + 2) Equivalent to return underlying_.format(r, ctx);. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator[] access specified element + \fI(public member function of std::vector)\fP + swap swaps two std::vector::references + \fB[static]\fP \fI(public static member function)\fP + +.SH External links + + "Effective Modern C++" by Scott Meyers (2015), Chapter 2, Item 6: "Use the + explicitly typed initializer idiom when auto deduces undesired types." (p.43-46) — + describes a possible misuse of the proxy class std::vector::reference). + +.SH Category: + * Todo no example diff --git a/man/std::vector::rend,std::vector::crend.3 b/man/std::vector::rend,std::vector::crend.3 index f822b9522..fb782daac 100644 --- a/man/std::vector::rend,std::vector::crend.3 +++ b/man/std::vector::rend,std::vector::crend.3 @@ -1,12 +1,18 @@ -.TH std::vector::rend,std::vector::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::rend,std::vector::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::rend,std::vector::crend \- std::vector::rend,std::vector::crend + .SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it + vector. It corresponds to the element preceding the first element of the + non-reversed vector. This element acts as a placeholder, attempting to access it results in undefined behavior. range-rbegin-rend.svg @@ -19,18 +25,59 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::vector nums{1, 2, 4, 8, 16}; + std::vector fruits{"orange", "apple", "raspberry"}; + std::vector empty; + + // Print vector. + std::for_each(nums.rbegin(), nums.rend(), [](const int n) { std::cout << n << ' '; }); + std::cout << '\\n'; + + // Sums all integers in the vector nums (if any), printing only the result. + std::cout << "Sum of nums: " + << std::accumulate(nums.rbegin(), nums.rend(), 0) << '\\n'; + + // Prints the first fruit in the vector fruits, checking if there is any. + if (!fruits.empty()) + std::cout << "First fruit: " << *fruits.rbegin() << '\\n'; + + if (empty.rbegin() == empty.rend()) + std::cout << "vector 'empty' is indeed empty.\\n"; + } + +.SH Output: + + 16 8 4 2 1 + Sum of nums: 31 + First fruit: raspberry + vector 'empty' is indeed empty. + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::vector::reserve.3 b/man/std::vector::reserve.3 index 32001c3ef..203188138 100644 --- a/man/std::vector::reserve.3 +++ b/man/std::vector::reserve.3 @@ -1,21 +1,30 @@ -.TH std::vector::reserve 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::reserve \- std::vector::reserve + .SH Synopsis - void reserve( size_type new_cap ); + void reserve( size_type new_cap ); (constexpr since C++20) - Increase the capacity of the container to a value that's greater or equal to + Increase the capacity of the vector (the total number of elements that the vector + can hold without requiring reallocation) to a value that's greater or equal to new_cap. If new_cap is greater than the current capacity(), new storage is - allocated, otherwise the method does nothing. + allocated, otherwise the function does nothing. + + reserve() does not change the size of the vector. + + If new_cap is greater than capacity(), all iterators, including the end() iterator, + and all references to the elements are invalidated. Otherwise, no iterators or + references are invalidated. - If new_cap is greater than capacity(), all iterators and references, including the - past-the-end iterator, are invalidated. Otherwise, no iterators or references are - invalidated. + After a call to reserve(), insertions will not trigger reallocation unless the + insertion would make the size of the vector greater than the value of capacity(). .SH Parameters - new_cap - new capacity of the container + new_cap - new capacity of the vector, in number of elements .SH Type requirements - - T must meet the requirements of MoveInsertable. + T must meet the requirements of MoveInsertable into *this. \fI(since C++11)\fP .SH Return value @@ -23,7 +32,14 @@ .SH Exceptions - std::length_error if new_cap > max_size(). + * std::length_error if new_cap > max_size(). + * Any exception thrown by Allocator::allocate() (typically std::bad_alloc). + + If an exception is thrown, this function has no effect \fI(strong exception guarantee)\fP. + + If T's move constructor is not noexcept and T is not CopyInsertable + into *this, vector will use the throwing move constructor. If it \fI(since C++11)\fP + throws, the guarantee is waived and the effects are unspecified. .SH Complexity @@ -31,15 +47,143 @@ .SH Notes - reserve() cannot be used to reduce the capacity of the container, to that end + Correctly using reserve() can prevent unnecessary reallocations, but inappropriate + uses of reserve() (for instance, calling it before every push_back() call) may + actually increase the number of reallocations (by causing the capacity to grow + linearly rather than exponentially) and result in increased computational complexity + and decreased performance. For example, a function that receives an arbitrary vector + by reference and appends elements to it should usually not call reserve() on the + vector, since it does not know of the vector's usage characteristics. + + When inserting a range, the range version of insert() is generally preferable as it + preserves the correct capacity growth behavior, unlike reserve() followed by a + series of push_back()s. + + reserve() cannot be used to reduce the capacity of the container; to that end shrink_to_fit() is provided. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // minimal C++11 allocator with debug output + template + struct NAlloc + { + typedef Tp value_type; + + NAlloc() = default; + template + NAlloc(const NAlloc&) {} + + Tp* allocate(std::size_t n) + { + n *= sizeof(Tp); + Tp* p = static_cast(::operator new(n)); + std::cout << "allocating " << n << " bytes @ " << p << '\\n'; + return p; + } + + void deallocate(Tp* p, std::size_t n) + { + std::cout << "deallocating " << n * sizeof *p << " bytes @ " << p << "\\n\\n"; + ::operator delete(p); + } + }; + + template + bool operator==(const NAlloc&, const NAlloc&) { return true; } + + template + bool operator!=(const NAlloc&, const NAlloc&) { return false; } + + int main() + { + constexpr int max_elements = 32; + + std::cout << "using reserve: \\n"; + { + std::vector> v1; + v1.reserve(max_elements); // reserves at least max_elements * sizeof(int) bytes + + for (int n = 0; n < max_elements; ++n) + v1.push_back(n); + } + + std::cout << "not using reserve: \\n"; + { + std::vector> v1; + + for (int n = 0; n < max_elements; ++n) + { + if (v1.size() == v1.capacity()) + std::cout << "size() == capacity() == " << v1.size() << '\\n'; + v1.push_back(n); + } + } + } + +.SH Possible output: + + using reserve: + allocating 128 bytes @ 0xa6f840 + deallocating 128 bytes @ 0xa6f840 + + not using reserve: + size() == capacity() == 0 + allocating 4 bytes @ 0xa6f840 + + size() == capacity() == 1 + allocating 8 bytes @ 0xa6f860 + deallocating 4 bytes @ 0xa6f840 + + size() == capacity() == 2 + allocating 16 bytes @ 0xa6f840 + deallocating 8 bytes @ 0xa6f860 + + size() == capacity() == 4 + allocating 32 bytes @ 0xa6f880 + deallocating 16 bytes @ 0xa6f840 + + size() == capacity() == 8 + allocating 64 bytes @ 0xa6f8b0 + deallocating 32 bytes @ 0xa6f880 + + size() == capacity() == 16 + allocating 128 bytes @ 0xa6f900 + deallocating 64 bytes @ 0xa6f8b0 + + deallocating 128 bytes @ 0xa6f900 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + reallocation might be triggered if an + insertion only triggers if the size + LWG 329 C++98 makes the size of the vector greater of the vector becomes + than the size greater than capacity() + specified in the most recent call to + reserve() + LWG 2033 C++11 T was not required to be required + MoveInsertable + .SH See also returns the number of elements that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP + max_size returns the maximum possible number of elements + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP shrink_to_fit reduces memory usage by freeing unused memory - \fI(C++11)\fP \fI(public member function)\fP + (DR*) \fI(public member function)\fP diff --git a/man/std::vector::resize.3 b/man/std::vector::resize.3 index 2f9eafc58..1dc8b3124 100644 --- a/man/std::vector::resize.3 +++ b/man/std::vector::resize.3 @@ -1,30 +1,31 @@ -.TH std::vector::resize 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::resize \- std::vector::resize + .SH Synopsis - void resize( size_type count, T value = T() ); \fI(until C++11)\fP - void resize( size_type count ); \fB(1)\fP \fI(since C++11)\fP - void resize( size_type count, const value_type& value); \fB(2)\fP \fI(since C++11)\fP + void resize( size_type count ); \fB(1)\fP (constexpr since C++20) + void resize( size_type count, const value_type& value ); \fB(2)\fP (constexpr since C++20) - Resizes the container to contain count elements. + Resizes the container to contain count elements, does nothing if count == size(). If the current size is greater than count, the container is reduced to its first - count elements as if by repeatedly calling pop_back() + count elements. - If the current size is less than count, additional elements are \fI(until C++11)\fP - appended and initialized with copies of value. If the current size is less than count, - \fI(since C++11)\fP - 1) additional value-initialized elements are appended - 2) additional copies of value are appended + + 1) additional default-inserted elements are appended. + 2) additional copies of value are appended. .SH Parameters - count - new size of the container - value - the value to initialize the new elements with + count - new size of the container + value - the value to initialize the new elements with .SH Type requirements - - 1) T must meet the requirements of DefaultConstructible and MoveInsertable. + T must meet the requirements of MoveInsertable and DefaultInsertable in order to use + overload \fB(1)\fP. - - 2) T must meet the requirements of CopyInsertable and MoveInsertable. + T must meet the requirements of CopyInsertable in order to use overload \fB(2)\fP. .SH Return value @@ -32,9 +33,86 @@ .SH Complexity - Linear in the size of the container + Linear in the difference between the current size and count. Additional complexity + possible due to reallocation if capacity is less than count. + +.SH Exceptions + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). Although not explicitly specified, std::length_error is + thrown if the capacity required by the new vector would exceed max_size(). + + In overload \fB(1)\fP, if T's move constructor is not noexcept and T is not + CopyInsertable into *this, vector will use the throwing move \fI(since C++11)\fP + constructor. If it throws, the guarantee is waived and the effects are + unspecified. + +.SH Notes + + If value-initialization in overload \fB(1)\fP is undesirable, for example, if the elements + are of non-class type and zeroing out is not needed, it can be avoided by providing + a custom Allocator::construct. + Vector capacity is never reduced when resizing to smaller size because that would + invalidate all iterators, rather than only the ones that would be invalidated by the + equivalent sequence of pop_back() calls. + +.SH Example + + +// Run this code + + #include + #include + + void print(auto rem, const std::vector& c) + { + for (std::cout << rem; const int el : c) + std::cout << el << ' '; + std::cout << '\\n'; + } + + int main() + { + std::vector c = {1, 2, 3}; + print("The vector holds: ", c); + + c.resize(5); + print("After resize up to 5: ", c); + + c.resize(2); + print("After resize down to 2: ", c); + + c.resize(6, 4); + print("After resize up to 6 (initializer = 4): ", c); + } + +.SH Output: + + The vector holds: 1 2 3 + After resize up to 5: 1 2 3 0 0 + After resize down to 2: 1 2 + After resize up to 6 (initializer = 4): 1 2 4 4 4 4 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 679 C++98 resize() passed value by value passes by const + reference + LWG 1525 C++98 the behavior of resize(size()) was not specified + specified + LWG 2033 C++11 1. elements were removed by using erase() 1. uses pop_back() + 2. the type requirements of T were incorrect 2. corrected + LWG 2066 C++11 overload \fB(1)\fP did not have the exception added + safety guarantee of overload \fB(2)\fP .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + insert inserts elements + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::vector::shrink_to_fit.3 b/man/std::vector::shrink_to_fit.3 index 7c0ba3a1d..b0a014f0d 100644 --- a/man/std::vector::shrink_to_fit.3 +++ b/man/std::vector::shrink_to_fit.3 @@ -1,13 +1,18 @@ -.TH std::vector::shrink_to_fit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::shrink_to_fit \- std::vector::shrink_to_fit + .SH Synopsis - void shrink_to_fit(); \fI(since C++11)\fP + void shrink_to_fit(); (constexpr since C++20) Requests the removal of unused capacity. It is a non-binding request to reduce capacity() to size(). It depends on the - implementation if the request is fulfilled. + implementation whether the request is fulfilled. - All iterators, including the past the end iterator, are potentially invalidated. + If reallocation occurs, all iterators (including the end() iterator) and all + references to the elements are invalidated. If no reallocation occurs, no iterators + or references are invalidated. .SH Parameters @@ -15,7 +20,7 @@ .SH Type requirements - - T must meet the requirements of MoveInsertable. + T must meet the requirements of MoveInsertable into *this. \fI(since C++11)\fP .SH Return value @@ -23,44 +28,73 @@ .SH Complexity - Linear in the size of the container. + At most linear in the size of the container. + +.SH Exceptions + \fI(since C++11)\fP + If an exception is thrown other than by the move constructor of a + non-CopyInsertable T, there are no effects. .SH Notes - If an exception is thrown other than by T's move constructor, there are no effects. + In libstdc++, shrink_to_fit() is not available in C++98 mode. .SH Example - - + + // Run this code #include #include - + int main() { std::vector v; std::cout << "Default-constructed capacity is " << v.capacity() << '\\n'; v.resize(100); std::cout << "Capacity of a 100-element vector is " << v.capacity() << '\\n'; + v.resize(50); + std::cout << "Capacity after resize(50) is " << v.capacity() << '\\n'; + v.shrink_to_fit(); + std::cout << "Capacity after shrink_to_fit() is " << v.capacity() << '\\n'; v.clear(); std::cout << "Capacity after clear() is " << v.capacity() << '\\n'; v.shrink_to_fit(); std::cout << "Capacity after shrink_to_fit() is " << v.capacity() << '\\n'; + for (int i = 1000; i < 1300; ++i) + v.push_back(i); + std::cout << "Capacity after adding 300 elements is " << v.capacity() << '\\n'; + v.shrink_to_fit(); + std::cout << "Capacity after shrink_to_fit() is " << v.capacity() << '\\n'; } .SH Possible output: Default-constructed capacity is 0 Capacity of a 100-element vector is 100 - Capacity after clear() is 100 + Capacity after resize(50) is 100 + Capacity after shrink_to_fit() is 50 + Capacity after clear() is 50 Capacity after shrink_to_fit() is 0 + Capacity after adding 300 elements is 512 + Capacity after shrink_to_fit() is 300 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 755 C++98 std::vector lacked explicit shrink-to-fit provided + operations + LWG 2033 C++11 1. T was not required to be MoveInsertable 1. required + 2. the complexity requirement was missing 2. added .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP returns the number of elements that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::size.3 b/man/std::vector::size.3 index 111c8ad10..760574c36 100644 --- a/man/std::vector::size.3 +++ b/man/std::vector::size.3 @@ -1,6 +1,10 @@ -.TH std::vector::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::size \- std::vector::size + .SH Synopsis - size_type size() const; + size_type size() const; (noexcept since C++11) + (constexpr since C++20) Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,34 +16,27 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::vector: - + // Run this code #include #include - + int main() { std::vector nums {1, 3, 5, 7}; - + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -51,10 +48,14 @@ returns the number of elements that can be held in currently allocated capacity storage - \fI(public member function)\fP + \fI(public member function)\fP empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP resize changes the number of elements stored - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::vector::swap.3 b/man/std::vector::swap.3 index 96563ff04..7d408346c 100644 --- a/man/std::vector::swap.3 +++ b/man/std::vector::swap.3 @@ -1,35 +1,84 @@ -.TH std::vector::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - void swap( vector& other ); - - Exchanges the contents of the container with those of other. Does not invoke any - move, copy, or swap operations on individual elements. +.TH std::vector::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::swap \- std::vector::swap - All iterators and references remain valid. The past-the-end iterator is invalidated. +.SH Synopsis + Defined in header + static void swap( reference x, reference y ); \fI(until C++20)\fP + constexpr static void swap( reference x, reference y ); \fI(since C++20)\fP - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != - other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP + Swaps the contents of x and y as if by bool b = x; x = y; y = b;. .SH Parameters - other - container to exchange the contents with + x - std::vector::reference value to swap with y + y - std::vector::reference value to swap with x .SH Return value \fI(none)\fP -.SH Exceptions - - \fI(none)\fP - .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + + void println(std::string_view fmt, std::vector const& vb = {}) + { + for (std::cout << fmt; bool const e : vb) + std::cout << e << ' '; + std::cout << '\\n'; + } + + int main() + { + println("swap elements of the same vector:"); + std::vector x{1, 0}; + println("before swap, x: ", x); + x.swap(x[0], x[1]); // same as std::vector::swap(x[0], x[1]); + println("after swap, x: ", x); + + println("swap elements of two different vectors:"); + std::vector y{0, 0, 1}; + println("before swap, x: ", x); + println("before swap, y: ", y); + y.swap(x[0], y[2]); // same as std::vector::swap(x[0], y[2]); + println("after swap, x: ", x); + println("after swap, y: ", y); + } + +.SH Output: + + swap elements of the same vector: + before swap, x: 1 0 + after swap, x: 0 1 + swap elements of two different vectors: + before swap, x: 0 1 + before swap, y: 0 0 1 + after swap, x: 1 1 + after swap, y: 0 0 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 814 C++98 the description of this member function was added + missing + .SH See also + reference proxy class representing a reference to a single bool + \fI(class)\fP + swap swaps the contents + \fI(public member function of std::vector)\fP std::swap(std::vector) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::vector::vector.3 b/man/std::vector::vector.3 index 82c628f86..f475e8032 100644 --- a/man/std::vector::vector.3 +++ b/man/std::vector::vector.3 @@ -1,131 +1,276 @@ -.TH std::vector::vector 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::vector 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::vector \- std::vector::vector + .SH Synopsis - explicit vector( const Allocator& alloc = (until - Allocator() ); C++14) - vector : vector( Allocator() ) {} (since - explicit vector( const Allocator& alloc ); C++14) - explicit vector( size_type count, - - const T& value = T(), (until - C++11) - const Allocator& alloc = - Allocator()); - vector( size_type count, - - const T& value, (since - C++11) - const Allocator& alloc = - Allocator()); - (since - explicit vector( size_type count ); \fB(1)\fP C++11) - (until - \fB(2)\fP C++14) - explicit vector( size_type count, const Allocator& (since - alloc = Allocator() ); C++14) + vector(); (until + C++17) + (since + vector() C++17) + noexcept(noexcept(Allocator())); (constexpr + since + C++20) + explicit vector( const (until + Allocator& alloc ); C++17) + (since + explicit vector( const C++17) + Allocator& alloc ) noexcept; (constexpr + since + C++20) + explicit vector( size_type + count, + + const T& value (until + = T(), C++11) + + const + Allocator& alloc = Allocator() + ); + vector( size_type count, (since + C++11) + const T& value, (constexpr + since + const Allocator& alloc = C++20) + Allocator() ); + (since + explicit vector( size_type count C++11) + ); (until + C++14) + explicit vector( size_type + count, (since + const C++14) + Allocator& alloc = Allocator() + ); template< class InputIt > - vector( InputIt first, InputIt last, \fB(4)\fP - \fB(3)\fP - const Allocator& alloc = Allocator() ); - vector( const vector& other ); \fB(5)\fP - vector( const vector& other, const Allocator& alloc \fB(5)\fP (since - ); C++11) - vector( vector&& other ) \fB(6)\fP (since - C++11) - vector( vector&& other, const Allocator& alloc ); \fB(6)\fP (since - C++11) - vector( std::initializer_list init, \fB(7)\fP (since - const Allocator& alloc = Allocator() ); C++11) - - Constructs new container from a variety of data sources and optionally using user + vector( InputIt first, InputIt \fB(1)\fP (constexpr + last, \fB(5)\fP since + C++20) + const Allocator& alloc = \fB(2)\fP + Allocator() ); + (constexpr + vector( const vector& other ); \fB(6)\fP since + \fB(3)\fP C++20) + (since + vector( const vector& other, C++11) + const Allocator& alloc ); \fB(7)\fP (constexpr + since + C++20) + (since + \fB(4)\fP C++11) + (noexcept + vector( vector&& other ); \fB(8)\fP since + C++17) + (constexpr + since + C++20) + (since + vector( vector&& other, const C++11) + Allocator& alloc ); \fB(9)\fP (constexpr + since + C++20) + vector( std::initializer_list (since + init, C++11) + const Allocator& alloc = \fB(10)\fP (constexpr + Allocator() ); since + C++20) + template< + container-compatible-range R + > + + constexpr vector( \fB(11)\fP (since + std::from_range_t, R&& rg, C++23) + + const + Allocator& alloc = Allocator() + ); + + Constructs a new container from a variety of data sources, optionally using a user supplied allocator alloc. - 1) Default constructor. Constructs empty container. - 2) Constructs the container with count copies of elements with value value. - 3) Constructs the container with count value-initialized (default constructed, for - classes) instances of T. No copies are made. - 4) Constructs the container with the contents of the range [first, last). - 5) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_container_copy_construction(other). - 6) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. - 7) Constructs the container with the contents of the initializer list init. + 1) Default constructor. Constructs an empty container with a default-constructed + allocator. + 2) Constructs an empty container with the given allocator alloc. + 3) Constructs the container with count copies of elements with value value. + 4) Constructs the container with count default-inserted instances of T. No copies + are made. + 5) Constructs the container with the contents of the range [first, last). + + This constructor has the same effect as + vector(static_cast(first), static_cast(last), \fI(until C++11)\fP + a) if InputIt is an integral type. + This overload participates in overload resolution only if InputIt + satisfies LegacyInputIterator, to avoid ambiguity with the overload \fI(since C++11)\fP + \fB(3)\fP. + + 6) Copy constructor. Constructs the container with the copy of the contents of + other. + + The allocator is obtained as if by calling (since + std::allocator_traits::select_on_container_copy_construction( C++11) + other.get_allocator()). + + 7) Constructs the container with the copy of the contents of other, using alloc as + the allocator. + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 8) Move constructor. Constructs the container with the contents of other using move + semantics. Allocator is obtained by move-construction from the allocator belonging + to other. After the move, other is guaranteed to be empty(). + 9) Allocator-extended move constructor. Using alloc as the allocator for the new + container, moving the contents from other; if alloc != other.get_allocator(), this + results in an element-wise move. (In that case, other is not guaranteed to be empty + after the move.) + + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. + + 10) Constructs the container with the contents of the initializer list init. + 11) Constructs the container with the contents of the range rg. .SH Parameters alloc - allocator to use for all memory allocations of this container count - the size of the container value - the value to initialize elements of the container with - first, last - the range to copy the elements from + first, last - the range [first, last) to copy the elements from other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with -.SH Type requirements - - - Allocator must meet the requirements of Allocator. - - - InputIt must meet the requirements of InputIterator. + rg - a container compatible range, that is, an input_range whose elements + are convertible to T .SH Complexity - 1) Constant - 2-3) Linear in count - 4) Linear in distance between first and last - 5) Linear in size of other - 6) Constant. If alloc is given and alloc != other.get_allocator(), then linear. - 7) Linear in size of init + 1,2) Constant. + 3,4) Linear in count. + 5) Given the distance between first and last as N, + * If first and last are both forward, bidirectional or random-access iterators, + + * The copy constructor of T is only called N times, and + * No reallocation occurs. + * Otherwise (first and last are just input iterators), + + * The copy constructor of T is called O(N) times, and + * Reallocation occurs O(log N) times. + 6,7) Linear in size of other. + 8) Constant. + 9) Linear if alloc != other.get_allocator(), otherwise constant. + 10) Linear in size of init. + 11) Given ranges::distance(rg) as N, + * If R models ranges::forward_range or ranges::sized_range, + + * Initializes exactly N elements from the result of dereferencing successive + iterators of rg, and + * No reallocation occurs. + * Otherwise (R models input range), + + * The copy or move constructor of T is called O(N) times, and + * Reallocation occurs O(log N) times. + +.SH Exceptions + + Calls to Allocator::allocate may throw. + +.SH Notes + + After container move construction (overload \fB(8)\fP), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + The overload \fB(4)\fP zeroes out elements of non-class types such as int, which is + different from the behavior of new[], which leaves them uninitialized. To match the + behavior of new[], a custom Allocator::construct can be provided which leaves such + elements uninitialized. + + Note that the presence of list-initializing constructor \fB(10)\fP means list + initialization and direct initialization do different things: + + std::vector b{3}; // creates a 1-element vector holding {3} + std::vector d\fB(3)\fP; // creates a 3-element vector holding {0, 0, 0} + + std::vector p{1, 2}; // creates a 2-element vector holding {1, 2} + std::vector q(1, 2); // creates a 1-element vector holding {2} + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overload \fB(11)\fP .SH Example - + // Run this code - #include - #include #include - + #include + #include + template - std::ostream& operator<<(std::ostream& s, const std::vector& v) { - s.put('['); - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& e : v) { - s << comma << e; - comma[0] = ','; - } - return s << ']'; + std::ostream& operator<<(std::ostream& s, const std::vector& v) + { + s.put('{'); + for (char comma[]{'\\0', ' ', '\\0'}; const auto& e : v) + s << comma << e, comma[0] = ','; + return s << "}\\n"; } - + int main() { - // c++11 initializer list syntax: - std::vector words1 {"the", "frogurt", "is", "also", "cursed"}; - std::cout << "words1: " << words1 << '\\n'; - + // C++11 initializer list syntax: + std::vector words1{"the", "frogurt", "is", "also", "cursed"}; + std::cout << "1: " << words1; + // words2 == words1 std::vector words2(words1.begin(), words1.end()); - std::cout << "words2: " << words2 << '\\n'; - + std::cout << "2: " << words2; + // words3 == words1 std::vector words3(words1); - std::cout << "words3: " << words3 << '\\n'; - + std::cout << "3: " << words3; + // words4 is {"Mo", "Mo", "Mo", "Mo", "Mo"} std::vector words4(5, "Mo"); - std::cout << "words4: " << words4 << '\\n'; + std::cout << "4: " << words4; + + auto const rg = {"cat", "cow", "crow"}; + #ifdef __cpp_lib_containers_ranges + std::vector words5(std::from_range, rg); // overload (11) + #else + std::vector words5(rg.begin(), rg.end()); // overload (5) + #endif + std::cout << "5: " << words5; } .SH Output: - words1: [the, frogurt, is, also, cursed] - words2: [the, frogurt, is, also, cursed] - words3: [the, frogurt, is, also, cursed] - words4: [Mo, Mo, Mo, Mo, Mo] + 1: {the, frogurt, is, also, cursed} + 2: {the, frogurt, is, also, cursed} + 3: {the, frogurt, is, also, cursed} + 4: {Mo, Mo, Mo, Mo, Mo} + 5: {cat, cow, crow} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(5)\fP allowed up to 2N  copy + LWG 134 C++98 constructor calls in the input changed to O(N) calls + iterator case + LWG 868 C++98 for overload \fB(4)\fP, the elements in the they are value-initialized + container were default constructed + LWG 2193 C++11 the default constructor is explicit made non-explicit .SH See also assign assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::vector::~vector.3 b/man/std::vector::~vector.3 index 7976d6dd5..a4efc09a5 100644 --- a/man/std::vector::~vector.3 +++ b/man/std::vector::~vector.3 @@ -1,11 +1,14 @@ -.TH std::vector::~vector 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vector::~vector 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vector::~vector \- std::vector::~vector + .SH Synopsis - ~vector(); + ~vector(); (constexpr since C++20) - Destructs the container. The destructors of the elements are called and the used + Destructs the vector. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the vector. diff --git a/man/std::vector.3 b/man/std::vector.3 deleted file mode 100644 index a48156f8b..000000000 --- a/man/std::vector.3 +++ /dev/null @@ -1,132 +0,0 @@ -.TH std::vector 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template> - class vector; - - std::vector is a space-efficient specialization of std::vector for the type - bool. - - The manner in which std::vector is made space efficient (as well as whether it - is optimized at all) is implementation defined. One potential optimization involves - coalescing vector elements such that each element occupies a single bit instead of - sizeof(bool) bytes. - - std::vector behaves similarly to std::vector, but in order to be space - efficient, it: - - * Does not necessarily store its data in a single contiguous chunk of memory. - * Exposes std::vector::reference as a method of accessing individual bits. - * Does not use std::allocator_traits::construct to construct bit values. - -.SH Member types - - Member type Definition - value_type bool - allocator_type Allocator - size_type implementation-defined - difference_type implementation-defined - reference proxy class representing a reference to a single bool - \fI(class)\fP - const_reference bool - pointer implementation-defined - const_pointer implementation-defined - iterator implementation-defined - const_iterator implementation-defined - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator - -.SH Member functions - - constructor constructs the vector - \fI(public member function of std::vector)\fP - destructor destructs the vector - \fI(public member function of std::vector)\fP - operator= assigns values to the container - \fI(public member function of std::vector)\fP - assign assigns values to the container - \fI(public member function of std::vector)\fP - get_allocator returns the associated allocator - \fI(public member function of std::vector)\fP -.SH Element access - at access specified element with bounds checking - \fI(public member function of std::vector)\fP - operator[] access specified element - \fI(public member function of std::vector)\fP - front access the first element - \fI(public member function of std::vector)\fP - back access the last element - \fI(public member function of std::vector)\fP -.SH Iterators - begin returns an iterator to the beginning - cbegin \fI(public member function of std::vector)\fP - end returns an iterator to the end - cend \fI(public member function of std::vector)\fP - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function of std::vector)\fP - rend returns a reverse iterator to the end - crend \fI(public member function of std::vector)\fP -.SH Capacity - empty checks whether the container is empty - \fI(public member function of std::vector)\fP - size returns the number of elements - \fI(public member function of std::vector)\fP - max_size returns the maximum possible number of elements - \fI(public member function of std::vector)\fP - reserve reserves storage - \fI(public member function of std::vector)\fP - returns the number of elements that can be held in currently allocated - capacity storage - \fI(public member function of std::vector)\fP -.SH Modifiers - clear clears the contents - \fI(public member function of std::vector)\fP - insert inserts elements - \fI(public member function of std::vector)\fP - emplace constructs element in-place - \fI(since C++14)\fP \fI(public member function of std::vector)\fP - erase erases elements - \fI(public member function of std::vector)\fP - push_back adds elements to the end - \fI(public member function of std::vector)\fP - emplace_back constructs elements in-place at the end - \fI(C++14)\fP \fI(public member function of std::vector)\fP - pop_back removes the last element - \fI(public member function of std::vector)\fP - resize changes the number of elements stored - \fI(public member function of std::vector)\fP - swap swaps the contents - \fI(public member function of std::vector)\fP -.SH vector specific modifiers - flip flips all the bits - \fI(public member function)\fP - swap swaps two std::vector::references - \fB[static]\fP \fI(public static member function)\fP - -.SH Non-member functions - - operator== - operator!= - operator< lexicographically compares the values in the vector - operator<= \fI(function template)\fP - operator> - operator>= - std::swap(std::vector) specializes the std::swap algorithm - \fI(function template)\fP - -.SH Helper classes - - std::hash> hash support for std::vector - \fI(C++11)\fP \fI(class template specialization)\fP - -.SH Notes - - If the size of the bitset is known at compile time, std::bitset may be used, which - offers a richer set of member functions. In addition, boost::dynamic_bitset exists - as an alternative to std::vector. - - Since its representation may by optimized, std::vector does not necessarily - meet all Container or SequenceContainer requirements. For example, because - std::vector::iterator is implementation-defined, it may not satisfy the - ForwardIterator requirement. Use of algorithms such as std::search that require - ForwardIterators may result in either compile-time or run-time errors. diff --git a/man/std::vector::flip.3 b/man/std::vector::flip.3 deleted file mode 100644 index 9c14e2f0a..000000000 --- a/man/std::vector::flip.3 +++ /dev/null @@ -1,21 +0,0 @@ -.TH std::vector::flip 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - void flip(); - - Toggles each bool in the vector (replaces with its opposite value). - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - \fI(none)\fP - -.SH See also - - operator[] access specified element - \fI(public member function of std::vector)\fP - flip toggles the values of bits - \fI(public member function of std::bitset)\fP diff --git a/man/std::vector::reference.3 b/man/std::vector::reference.3 deleted file mode 100644 index ed4fd4852..000000000 --- a/man/std::vector::reference.3 +++ /dev/null @@ -1,124 +0,0 @@ -.TH std::vector::reference 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - class reference; - - The std::vector specialization defines std::vector::reference as a - publicly-accessible nested class. std::vector::reference proxies the behavior - of references to a single bit in std::vector. - - The primary use of std::vector::reference is to provide an l-value that can be - returned from operator[]. - - Any reads or writes to a vector that happen via a std::vector::reference - potentially read or write to the entire underlying vector. - -.SH Member functions - - constructor constructs the reference. Accessible only to std::vector itself - \fI(public member function)\fP - destructor ~reference - \fI(public member function)\fP - operator= assigns a bool to the referenced bit - \fI(public member function)\fP - operator bool returns the referenced bit - \fI(public member function)\fP - operator ~ returns inverted referenced bit - \fI(public member function)\fP - flip flips the referenced bit - \fI(public member function)\fP - - std::vector::~reference - - ~reference() - - Destroys the reference. - - std::vector::reference::operator= - - reference& operator=( bool x ); - reference& operator=( const reference& x ); - - Assigns a value to the referenced bit. - -.SH Parameters - - x - value to assign - -.SH Return value - - *this - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - std::vector::reference::operator bool - - operator bool() const; - - Returns the value of the referenced bit. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The referenced bit. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - std::vector::reference::operator~ - - bool operator~() const; - - Returns the inverse of the referenced bit. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - The inverse of the referenced bit. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - std::vector::reference::flip - - void flip(); - - Inverts the referenced bit. - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - \fI(none)\fP - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH See also - - operator[] access specified element - \fI(public member function of std::vector)\fP diff --git a/man/std::vector::swap.3 b/man/std::vector::swap.3 deleted file mode 100644 index 6f401c6ab..000000000 --- a/man/std::vector::swap.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH std::vector::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - static void swap(reference x, reference y); - - Swaps the contents of x and y. - -.SH Parameters - - x - std::vector::reference value to swap with y - y - std::vector::reference value to swap with x - -.SH Return value - - \fI(none)\fP - -.SH See also - - reference proxy class representing a reference to a single bool - \fI(class)\fP - std::swap(std::vector) specializes the std::swap algorithm - \fI(function template)\fP diff --git a/man/std::vformat.3 b/man/std::vformat.3 new file mode 100644 index 000000000..b61b30eba --- /dev/null +++ b/man/std::vformat.3 @@ -0,0 +1,102 @@ +.TH std::vformat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vformat \- std::vformat + +.SH Synopsis + Defined in header + std::string vformat( std::string_view fmt, std::format_args args \fB(1)\fP \fI(since C++20)\fP + ); + std::wstring vformat( std::wstring_view fmt, std::wformat_args \fB(2)\fP \fI(since C++20)\fP + args ); + std::string vformat( const std::locale& loc, + std::string_view fmt, std::format_args args \fB(3)\fP \fI(since C++20)\fP + ); + std::wstring vformat( const std::locale& loc, + std::wstring_view fmt, std::wformat_args \fB(4)\fP \fI(since C++20)\fP + args ); + + Format arguments held by args according to the format string fmt, and return the + result as a string. If present, loc is used for locale-specific formatting. + +.SH Parameters + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } respectively + in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to + be used for formatting; if it is omitted, the arguments are + arg-id - used in order. + + The arg-id s in a format string must all be present or all be + omitted. Mixing manual and automatic indexing is an error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted as + range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. (since C++23) + * For std::thread::id and std::stacktrace_entry, see thread + id format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args - arguments to be formatted + loc - std::locale used for locale-specific formatting + +.SH Return value + + A string object holding the formatted result. + +.SH Exceptions + + Throws std::format_error if fmt is not a valid format string for the provided + arguments, or std::bad_alloc on allocation failure. Also propagates any exception + thrown by formatter or iterator operations. + +.SH Example + + +// Run this code + + #include + #include + + template + inline void println(const std::format_string fmt, Args&&... args) + { + std::cout << std::vformat(fmt.get(), std::make_format_args(args...)) << '\\n'; + } + + int main() + { + println("{}{} {}{}", "Hello", ',', "C++", -1 + 2 * 3 * 4); + } + +.SH Output: + + Hello, C++23 + +.SH See also diff --git a/man/std::vformat_to.3 b/man/std::vformat_to.3 new file mode 100644 index 000000000..b8ba64f46 --- /dev/null +++ b/man/std::vformat_to.3 @@ -0,0 +1,114 @@ +.TH std::vformat_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vformat_to \- std::vformat_to + +.SH Synopsis + Defined in header + template< class OutputIt > + OutputIt vformat_to( OutputIt out, std::string_view fmt, \fB(1)\fP \fI(since C++20)\fP + std::format_args args ); + template< class OutputIt > + OutputIt vformat_to( OutputIt out, std::wstring_view fmt, \fB(2)\fP \fI(since C++20)\fP + std::wformat_args args ); + template< class OutputIt > + + OutputIt vformat_to( OutputIt out, const std::locale& loc, \fB(3)\fP \fI(since C++20)\fP + + std::string_view fmt, std::format_args args + ); + template< class OutputIt > + + OutputIt vformat_to( OutputIt out, const std::locale& loc, \fB(4)\fP \fI(since C++20)\fP + + std::wstring_view fmt, std::wformat_args args + ); + + Format arguments held by args according to the format string fmt, and write the + result to the output iterator out. If present, loc is used for locale-specific + formatting. + + Let CharT be decltype(fmt)::char_type (char for overloads (1,3), wchar_t for + overloads (2,4)). + + These overloads participate in overload resolution only if OutputIt satisfies the + concept std::output_iterator. + + The behavior is undefined if OutputIt does not model (meet the semantic requirements + of) the concept std::output_iterator, or if std::formatter + does not meet the Formatter requirements for any Ti in the type of arguments. + +.SH Parameters + + out - iterator to the output buffer + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } respectively + in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to + be used for formatting; if it is omitted, the arguments are + arg-id - used in order. + + The arg-id s in a format string must all be present or all be + omitted. Mixing manual and automatic indexing is an error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted as + range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. (since C++23) + * For std::thread::id and std::stacktrace_entry, see thread + id format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args - arguments to be formatted + loc - std::locale used for locale-specific formatting + +.SH Return value + + Iterator past the end of the output range. + +.SH Exceptions + + Throws std::format_error if fmt is not a valid format string for the provided + arguments. Also propagates any exception thrown by formatter or iterator operations. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2216R3 C++20 type of args is parameterized on OutputIt not parameterized + +.SH See also + +.SH Category: + * Todo no example diff --git a/man/std::visit.3 b/man/std::visit.3 new file mode 100644 index 000000000..c6386e95c --- /dev/null +++ b/man/std::visit.3 @@ -0,0 +1,193 @@ +.TH std::visit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::visit \- std::visit + +.SH Synopsis + Defined in header + template< class Visitor, class... Variants > + constexpr /* see below */ visit( Visitor&& vis, Variants&&... \fB(1)\fP \fI(since C++17)\fP + vars ); + template< class R, class Visitor, class... Variants > \fB(2)\fP \fI(since C++20)\fP + constexpr R visit( Visitor&& vis, Variants&&... vars ); + template< class... Ts > \fB(3)\fP (exposition only*) + auto&& as-variant( std::variant& var ); + template< class... Ts > \fB(4)\fP (exposition only*) + auto&& as-variant( const std::variant& var ); + template< class... Ts > \fB(5)\fP (exposition only*) + auto&& as-variant( std::variant&& var ); + template< class... Ts > \fB(6)\fP (exposition only*) + auto&& as-variant( const std::variant&& var ); + + Applies the visitor vis (a Callable that can be called with any combination of types + from variants) to the variants vars. + + Given VariantBases as decltype(as-variant(std::forward(vars))... (a pack + of sizeof...(Variants) types): + + 1) Invokes vis as if by + + INVOKE(std::forward(vis), + std::get(std::forward(vars))...), + + where indices is as-variant(vars).index().... + 2) Invokes vis as if by + + INVOKE(std::forward(vis), + std::get(std::forward(vars))...), + + where indices is as-variant(vars).index().... + + These overloads participate in overload resolution only if every type in + VariantBases is a valid type. If the expression denoted by INVOKE + or INVOKE + \fI(since C++20)\fP is invalid, or the results of INVOKE + or INVOKE + \fI(since C++20)\fP have different types or value categories for different indices, the + program is ill-formed. + + 3-6) The exposition-only as-variant function templates accept a value whose type can + be deduced for std::variant (i.e. either std::variant or a type + derived from std::variant), and return the std::variant value with the same + const-qualification and value category. + 3,4) Returns var. + 5,6) Returns std::move(var). + +.SH Parameters + + vis - a Callable that accepts every possible alternative from every variant + vars - list of variants to pass to the visitor + +.SH Return value + + 1) The result of the INVOKE operation. The return type is the type obtained from + applying decltype to the result. + 2) Nothing if R is (possibly cv-qualified) void; otherwise the result of the + INVOKE operation. + 3-6) A std::variant value converted from var. + +.SH Exceptions + + Throws std::bad_variant_access if as-variant(vars_i).valueless_by_exception() is + true for any variant vars_i in vars. + +.SH Complexity + + When the number of variants is zero or one, the invocation of the callable object is + implemented in constant time, i.e. it does not depend on the number of types can be + stored in the variant. + + If the number of variants is larger than one, the invocation of the callable object + has no complexity requirements. + +.SH Notes + + Let n be (1 * ... * std::variant_size_v>), + implementations usually generate a table equivalent to an (possibly + multidimensional) array of n function pointers for every specialization of + std::visit, which is similar to the implementation of virtual functions. + + Implementations may also generate a switch statement with n branches for std::visit + (e.g. the MSVC STL implementation uses a switch statement when n is not greater than + 256). + + On typical implementations, the time complexity of the invocation of vis can be + considered equal to that of access to an element in an (possibly multidimensional) + array or execution of a switch statement. + + Feature-test macro Value Std Feature + __cpp_lib_variant 202102L \fI(C++17)\fP std::visit for classes derived from std::variant + (DR) + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + // the variant to visit + using var_t = std::variant; + + // helper type for the visitor #4 + template + struct overloaded : Ts... { using Ts::operator()...; }; + // explicit deduction guide (not needed as of C++20) + template + overloaded(Ts...) -> overloaded; + + int main() + { + std::vector vec = {10, 15l, 1.5, "hello"}; + + for (auto& v: vec) + { + // 1. void visitor, only called for side-effects (here, for I/O) + std::visit([](auto&& arg){ std::cout << arg; }, v); + + // 2. value-returning visitor, demonstrates the idiom of returning another variant + var_t w = std::visit([](auto&& arg) -> var_t { return arg + arg; }, v); + + // 3. type-matching visitor: a lambda that handles each type differently + std::cout << ". After doubling, variant holds "; + std::visit([](auto&& arg) + { + using T = std::decay_t; + if constexpr (std::is_same_v) + std::cout << "int with value " << arg << '\\n'; + else if constexpr (std::is_same_v) + std::cout << "long with value " << arg << '\\n'; + else if constexpr (std::is_same_v) + std::cout << "double with value " << arg << '\\n'; + else if constexpr (std::is_same_v) + std::cout << "std::string with value " << std::quoted(arg) << '\\n'; + else + static_assert(false, "non-exhaustive visitor!"); + }, w); + } + + for (auto& v: vec) + { + // 4. another type-matching visitor: a class with 3 overloaded operator()'s + // Note: The `(auto arg)` template operator() will bind to `int` and `long` + // in this case, but in its absence the `(double arg)` operator() + // *will also* bind to `int` and `long` because both are implicitly + // convertible to double. When using this form, care has to be taken + // that implicit conversions are handled correctly. + std::visit(overloaded{ + [](auto arg) { std::cout << arg << ' '; }, + [](double arg) { std::cout << std::fixed << arg << ' '; }, + [](const std::string& arg) { std::cout << std::quoted(arg) << ' '; } + }, v); + } + } + +.SH Output: + + 10. After doubling, variant holds int with value 20 + 15. After doubling, variant holds long with value 30 + 1.5. After doubling, variant holds double with value 3 + hello. After doubling, variant holds std::string with value "hellohello" + 10 15 1.500000 "hello" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the return type of overload \fB(1)\fP did not + LWG 2970 C++17 preserve the preserves + value category of the result of the INVOKE + operation + LWG 3052 C++17 the effects were unspecified if any type specified + (P2162R2) in Variants is not a std::variant + +.SH See also + + swap swaps with another variant + \fI(public member function)\fP diff --git a/man/std::visit_format_arg.3 b/man/std::visit_format_arg.3 new file mode 100644 index 000000000..1ca418476 --- /dev/null +++ b/man/std::visit_format_arg.3 @@ -0,0 +1,43 @@ +.TH std::visit_format_arg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::visit_format_arg \- std::visit_format_arg + +.SH Synopsis + Defined in header + template< class Visitor, class Context > \fI(since C++20)\fP + /* see below */ visit_format_arg( Visitor&& vis, (deprecated in C++26) + std::basic_format_arg arg ); + + Applies the visitor vis to the object contained in arg. + + Equivalent to std::visit(std::forward(vis), value), where value is the + std::variant stored in arg. + +.SH Parameters + + vis - a Callable that accepts every possible alternative from arg + arg - a std::basic_format_arg to be visited + +.SH Return value + + The value returned by the selected invocation of the visitor. + +.SH Notes + + As of C++26, std::visit_format_arg is deprecated in favor of the visit member + functions of std::basic_format_arg. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + make_format_args creates a type-erased object referencing all formatting arguments, + make_wformat_args convertible to format_args + (C++20) \fI(function template)\fP + (C++20) + +.SH Category: + * Todo no example diff --git a/man/std::void_t.3 b/man/std::void_t.3 new file mode 100644 index 000000000..4a7273d53 --- /dev/null +++ b/man/std::void_t.3 @@ -0,0 +1,126 @@ +.TH std::void_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::void_t \- std::void_t + +.SH Synopsis + Defined in header + template< class... > \fI(since C++17)\fP + using void_t = void; + + Utility metafunction that maps a sequence of any types to the type void. This + metafunction is a convenient way to leverage SFINAE prior to C++20's concepts, in + particular for conditionally removing functions from the candidate set based on + whether an expression is valid in the unevaluated context (such as operand to + decltype expression), allowing to exist separate function overloads or + specializations based on supported operations. + +.SH Notes + + This metafunction is used in template metaprogramming to detect ill-formed types in + SFINAE context: + + // primary template handles types that have no nested ::type member: + template + struct has_type_member : std::false_type {}; + + // specialization recognizes types that do have a nested ::type member: + template + struct has_type_member> : std::true_type {}; + + It can also be used to detect validity of an expression: + + // primary template handles types that do not support pre-increment: + template + struct has_pre_increment_member : std::false_type {}; + + // specialization recognizes types that do support pre-increment: + template + struct has_pre_increment_member() )> + > : std::true_type {}; + + Until the resolution of CWG issue 1558 (a C++11 defect), unused parameters in alias + templates were not guaranteed to ensure SFINAE and could be ignored, so earlier + compilers require a more complex definition of void_t, such as + + template + struct make_void { typedef void type; }; + + template + using void_t = typename make_void::type; + + Feature-test macro Value Std Feature + __cpp_lib_void_t 201411L \fI(C++17)\fP std::void_t + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + // Variable template that checks if a type has begin() and end() member functions + template + constexpr bool is_iterable = false; + + template + constexpr bool is_iterable< + T, + std::void_t().begin()), + decltype(std::declval().end()) + > + > = true; + + // An iterator trait those value_type is the value_type of the iterated container, + // supports even back_insert_iterator (where value_type is void) + + template + struct iterator_trait : std::iterator_traits {}; + + template + struct iterator_trait> + : std::iterator_traits {}; + + class A {}; + + #define SHOW(...) std::cout << std::setw(34) << #__VA_ARGS__ \\ + << " == " << __VA_ARGS__ << '\\n' + + int main() + { + std::cout << std::boolalpha << std::left; + SHOW(is_iterable>); + SHOW(is_iterable>); + SHOW(is_iterable); + SHOW(is_iterable); + + using container_t = std::vector; + container_t v; + + static_assert(std::is_same_v< + container_t::value_type, + iterator_trait::value_type + >); + + static_assert(std::is_same_v< + container_t::value_type, + iterator_trait::value_type + >); + } + +.SH Output: + + is_iterable> == true + is_iterable> == true + is_iterable == false + is_iterable == false + +.SH See also + + enable_if conditionally removes a function overload or template specialization from + \fI(C++11)\fP overload resolution + \fI(class template)\fP diff --git a/man/std::vprint_nonunicode(std::ostream).3 b/man/std::vprint_nonunicode(std::ostream).3 new file mode 100644 index 000000000..3e8b05a4d --- /dev/null +++ b/man/std::vprint_nonunicode(std::ostream).3 @@ -0,0 +1,109 @@ +.TH std::vprint_nonunicode(std::ostream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vprint_nonunicode(std::ostream) \- std::vprint_nonunicode(std::ostream) + +.SH Synopsis + Defined in header + void vprint_nonunicode( std::ostream& os, std::string_view fmt, (since C++23) + std::format_args args ); + + Behaves as FormattedOutputFunction (except that some details of error reporting + differ): + + * First, constructs and checks the sentry object. + * Then, initializes an automatic variable as if by std::string out = + std::vformat(os.getloc(), fmt, args);. + * Finally, inserts the character sequence [out.begin(), out.end()) into os. + +.SH Parameters + + os - output stream to insert data into + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } respectively + in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to + be used for formatting; if it is omitted, the arguments are + arg-id - used in order. + + The arg-id s in a format string must all be present or all be + fmt - omitted. Mixing manual and automatic indexing is an error. + the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted as + range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. (since C++23) + * For std::thread::id and std::stacktrace_entry, see thread + id format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args - arguments to be formatted + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * Propagate any exception thrown by any formatter, e.g. std::format_error, without + regard to the value of os.exceptions() and without turning on ios_base::badbit + in the error state of os. + * May throw ios_base::failure caused by os.setstate(ios_base::badbit) which is + called if an insertion into os fails. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_print 202207L (C++23) Formatted output + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + vprint_unicode(std::ostream) performs Unicode aware output using type-erased + (C++23) argument representation + \fI(function)\fP + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + vprint_nonunicode prints to stdout or a file stream using type-erased + vprint_nonunicode_locking argument representation + (C++23) \fI(function)\fP + (C++23) + format stores formatted representation of the arguments in a + (C++20) new string + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::vprint_nonunicode,std::vprint_nonunicode_locking.3 b/man/std::vprint_nonunicode,std::vprint_nonunicode_locking.3 new file mode 100644 index 000000000..9c63742c3 --- /dev/null +++ b/man/std::vprint_nonunicode,std::vprint_nonunicode_locking.3 @@ -0,0 +1,113 @@ +.TH std::vprint_nonunicode,std::vprint_nonunicode_locking 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vprint_nonunicode,std::vprint_nonunicode_locking \- std::vprint_nonunicode,std::vprint_nonunicode_locking + +.SH Synopsis + Defined in header + void vprint_nonunicode( std::string_view fmt, std::format_args \fB(1)\fP (since C++23) + args ); + void vprint_nonunicode( std::FILE* stream, + std::string_view fmt, std::format_args \fB(2)\fP (since C++23) + args ); + void vprint_nonunicode_locking( std::FILE* stream, + std::string_view fmt, \fB(3)\fP (since C++23) + std::format_args args ); + + Format args according to the format string fmt, and writes the result to the output + stream. + + 1) Equivalent to std::vprint_nonunicode(stdout, fmt, args). + 2) Equivalent to std::string out = std::vformat(fmt, args); + std::vprint_nonunicode_locking(stream, "{}", std::make_format_args(out));. + 3) While holding the lock on stream, writes the character representation of + formatting arguments provided by args formatted according to specifications given in + fmt to stream. + If stream is not a valid pointer to an output C stream, the behavior is undefined. + +.SH Parameters + + stream - output file stream to write to + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to + be used for formatting; if it is omitted, the arguments are + arg-id - used in order. + + The arg-id s in a format string must all be present or all be + omitted. Mixing manual and automatic indexing is an error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see thread (since C++23) + id format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args - arguments to be formatted + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * std::system_error, if writing to the stream fails. + * Propagates any exception thrown by used formatters, e.g. std::format_error. + +.SH Notes + + Feature-test macro Value Std Feature + 202207L (C++23) Formatted output + __cpp_lib_print 202403L (C++26) Formatted output with stream locking + (DR23) + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + vprint_unicode prints to Unicode capable stdout or a file stream + vprint_unicode_locking using type-erased argument representation + (C++23) \fI(function)\fP + (C++23) + vprint_nonunicode(std::ostream) outputs character data using type-erased argument + (C++23) representation + \fI(function)\fP + print prints to stdout or a file stream using formatted + (C++23) representation of the arguments + \fI(function template)\fP + format stores formatted representation of the arguments in + (C++20) a new string + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::vprint_unicode(std::ostream).3 b/man/std::vprint_unicode(std::ostream).3 new file mode 100644 index 000000000..2a2e97196 --- /dev/null +++ b/man/std::vprint_unicode(std::ostream).3 @@ -0,0 +1,121 @@ +.TH std::vprint_unicode(std::ostream) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vprint_unicode(std::ostream) \- std::vprint_unicode(std::ostream) + +.SH Synopsis + Defined in header + void vprint_unicode( std::ostream& os, std::string_view fmt, (since C++23) + std::format_args args ); + + Behaves as FormattedOutputFunction (except that some details of error reporting + differ): + + * First, the function constructs and checks the sentry object. + * Then, initializes an automatic variable as if by std::string out = + std::vformat(os.getloc(), fmt, args);. + * Finally, inserts the character sequence [out.begin(), out.end()) into os, that + is, if os refers to a terminal capable of displaying Unicode, writes out to this + terminal using the native Unicode API. Otherwise, writes unmodified out to the + os. + +.SH Parameters + + os - output stream to insert data into + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } respectively + in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to + be used for formatting; if it is omitted, the arguments are + arg-id - used in order. + + The arg-id s in a format string must all be present or all be + fmt - omitted. Mixing manual and automatic indexing is an error. + the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted as + range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. (since C++23) + * For std::thread::id and std::stacktrace_entry, see thread + id format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args - arguments to be formatted + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * Propagate any exception thrown by any formatter, e.g. std::format_error, without + regard to the value of os.exceptions() and without turning on ios_base::badbit + in the error state of os. + * May throw ios_base::failure caused by os.setstate(ios_base::badbit) which is + called if an insertion into os fails. + +.SH Notes + + If invoking the native Unicode API requires transcoding, the invalid code units are + substituted with U+FFFD REPLACEMENT CHARACTER (see "The Unicode Standard Version + 14.0 - Core Specification", Chapter 3.9). + + Feature-test macro Value Std Feature + __cpp_lib_print 202207L (C++23) Formatted output + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + vprint_nonunicode(std::ostream) outputs character data using type-erased argument + (C++23) representation + \fI(function)\fP + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + vprint_unicode prints to Unicode capable stdout or a file stream + vprint_unicode_locking using type-erased argument representation + (C++23) \fI(function)\fP + (C++23) + format stores formatted representation of the arguments in + (C++20) a new string + \fI(function template)\fP + +.SH External links + + 1. Unicode + 2. The Unicode Standard Version 14.0 - Core Specification + +.SH Category: + * Todo no example diff --git a/man/std::vprint_unicode,std::vprint_unicode_locking.3 b/man/std::vprint_unicode,std::vprint_unicode_locking.3 new file mode 100644 index 000000000..9d5716429 --- /dev/null +++ b/man/std::vprint_unicode,std::vprint_unicode_locking.3 @@ -0,0 +1,142 @@ +.TH std::vprint_unicode,std::vprint_unicode_locking 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vprint_unicode,std::vprint_unicode_locking \- std::vprint_unicode,std::vprint_unicode_locking + +.SH Synopsis + Defined in header + void vprint_unicode( std::string_view fmt, std::format_args args \fB(1)\fP (since C++23) + ); + void vprint_unicode( std::FILE* stream, + std::string_view fmt, std::format_args args \fB(2)\fP (since C++23) + ); + void vprint_unicode_locking( std::FILE* stream, + std::string_view fmt, \fB(3)\fP (since C++23) + std::format_args args ); + + Format args according to the format string fmt, and writes the result to the output + stream. + + 1) Equivalent to std::vprint_unicode(stdout, fmt, args). + 2) Equivalent to std::string out = std::vformat(fmt, args); + std::vprint_unicode_locking(stream, "{}", std::make_format_args(out));. + 3) Performs the following operations in order: + 1. Locks stream. + 2. Let out denote the character representation of formatting arguments provided by + args formatted according to specifications given in fmt. + 3. Writes out to stream: + + * If stream refers to a terminal capable of displaying Unicode, flushes stream and + writes out to the terminal using the native Unicode API. + * Otherwise, writes unmodified out to the stream. + Unconditionally unlocks stream on function exit. + If any of the following condition is satisfied, the behavior is undefined: + * stream is not a valid pointer to an output C stream. + * out contains invalid Unicode code units if the native Unicode API is used. + +.SH Parameters + + stream - output file stream to write to + + an object that represents the format string. The format string consists of + * ordinary characters (except { and }), which are copied unchanged to the + output, + * escape sequences {{ and }}, which are replaced with { and } + respectively in the output, and + * replacement fields. + + Each replacement field has the following format: + + { arg-id (optional) } \fB(1)\fP + { arg-id (optional) : format-spec } \fB(2)\fP + + 1) replacement field without a format specification + 2) replacement field with a format specification + + specifies the index of the argument in args whose value is to + be used for formatting; if it is omitted, the arguments are + arg-id - used in order. + + The arg-id s in a format string must all be present or all be + omitted. Mixing manual and automatic indexing is an error. + fmt - the format specification defined by the std::formatter + format-spec - specialization for the corresponding argument. Cannot start + with }. + + * For basic types and standard string types, the format specification is + interpreted as standard format specification. + * For chrono types, the format specification is interpreted as chrono + format specification. + + * For range types, the format specification is interpreted + as range format specification. + * For std::pair and std::tuple, the format specification is + interpreted as tuple format specification. + * For std::thread::id and std::stacktrace_entry, see thread (since C++23) + id format specification and stacktrace entry format + specification. + * For std::basic_stacktrace, no format specifier is + allowed. + + * For std::filesystem::path, see path format specification. (since C++26) + + * For other formattable types, the format specification is determined by + user-defined formatter specializations. + args - arguments to be formatted + +.SH Exceptions + + * std::bad_alloc on allocation failure. + * std::system_error, if writing to the stream fails. + * Propagates any exception thrown by used formatters, e.g. std::format_error. + +.SH Notes + + The C++ standard encourages the implementers to produce a diagnostic message if out + contains invalid Unicode code units. + + On POSIX, the stream refers to a terminal if the expression isatty(fileno(stream)) + != 0 holds true (see POSIX documentation for isatty, and fileno). + + On Windows, the stream refers to a terminal if the expression + GetConsoleMode(_get_osfhandle(_fileno(stream))) returns nonzero (see Windows + documentation for GetConsoleMode, _get_osfhandle, and _fileno). The native Unicode + API on Windows is WriteConsoleW. + + If invoking the native Unicode API requires transcoding, the invalid code units are + substituted with U+FFFD REPLACEMENT CHARACTER (see "The Unicode Standard Version + 14.0 - Core Specification", Chapter 3.9). + + Feature-test macro Value Std Feature + 202207L (C++23) Formatted output + __cpp_lib_print 202403L (C++26) Formatted output with stream locking + (DR23) + __cpp_lib_format 202207L (C++23) Exposing std::basic_format_string + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + vprint_nonunicode prints to stdout or a file stream using type-erased + vprint_nonunicode_locking argument representation + (C++23) \fI(function)\fP + (C++23) + vprint_unicode(std::ostream) performs Unicode aware output using type-erased + (C++23) argument representation + \fI(function)\fP + print prints to stdout or a file stream using formatted + (C++23) representation of the arguments + \fI(function template)\fP + format stores formatted representation of the arguments in a + (C++20) new string + \fI(function template)\fP + +.SH External links + + 1. Unicode + 2. The Unicode Standard Version 14.0 - Core Specification + +.SH Category: + * Todo no example diff --git a/man/std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf.3 b/man/std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf.3 index 237180dd5..6032755d3 100644 --- a/man/std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf.3 +++ b/man/std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf.3 @@ -1,12 +1,16 @@ -.TH std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf \- std::vprintf,std::vfprintf,std::vsprintf,std::vsnprintf + .SH Synopsis Defined in header - int vprintf( const char* format, va_list vlist ); \fB(1)\fP - int vfprintf( std::FILE* stream, const char* format, va_list vlist \fB(2)\fP + int vprintf( const char* format, std::va_list vlist ); \fB(1)\fP + int vfprintf( std::FILE* stream, const char* format, std::va_list \fB(2)\fP + vlist ); + int vsprintf( char* buffer, const char* format, std::va_list vlist \fB(3)\fP ); - int vsprintf( char* buffer, const char* format, va_list vlist ); \fB(3)\fP int vsnprintf( char* buffer, std::size_t buf_size, const char* \fB(4)\fP \fI(since C++11)\fP - format, va_list vlist ); + format, std::va_list vlist ); Loads the data from the locations, defined by vlist, converts them to character string equivalents and writes the results to a variety of sinks. @@ -14,432 +18,479 @@ 1) Writes the results to stdout. 2) Writes the results to a file stream stream. 3) Writes the results to a character string buffer. - 4) Writes the results to a character string buffer. At most buf_size characters are - written. The resulting character string will be terminated with a null character, - unless buf_size is zero. + 4) Writes the results to a character string buffer. At most buf_size - 1 characters + are written. The resulting character string will be terminated with a null + character, unless buf_size is zero. If buf_size is zero, nothing is written and + buffer may be a null pointer, however the return value (number of bytes that would + be written not including the null terminator) is still calculated and returned. .SH Parameters -stream - output file stream to write to -buffer - pointer to a character string to write to -buf_size - maximum number of characters to write - pointer to a null-terminated character string specifying how to interpret the data. - - The format string consists of ordinary characters (except %), which are copied unchanged into the output - stream, and conversion specifications. Each conversion specification has the following format: - - * introductory % character - - * (optional) one or more flags that modify the behavior of the conversion: - - * -: the result of the conversion is left-justified within the field (by default it is - right-justified) - * +: the sign of signed conversions is always prepended to the result of the conversion (by default - the result is preceded by minus only when it is negative) - * space: if the result of a signed conversion does not start with a sign character, or is empty, space - is prepended to the result. It is ignored if + flag is present. - * # : alternative form of the conversion is performed. See the table below for exact effects. - * 0 : for integer and floating point number conversions, leading zeros are used to pad the field - instead of space characters. For floating point numbers it is ignored if the precision is explicitly - specified. For other conversions using this flag results in undefined behavior. It is ignored if - - flag is present. - - * (optional) integer value or * that specifies minimum field width. The result is padded with space - characters (by default), if required, on the left when right-justified, or on the right if - left-justified. In the case when * is used, the width is specified by an additional argument of type - int. If the value of the argument is negative, it results with the - flag specified and positive - field width. - - * (optional) . followed by integer number or * that specifies precision of the conversion. In the case - when * is used, the precision is specified by an additional argument of type int. If the value of - this argument is negative, it is ignored. See the table below for exact effects of precision. - - * (optional) length modifier that specifies the size of the argument - - * conversion format specifier - - The following format specifiers are available: - - Conversion Explanation Argument type - specifier - length modifier hh h \fI(none)\fP l ll j z t L - writes literal - %. The full - % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A - specification - must be %%. - writes a - c single N/A N/A char wchar_t N/A N/A N/A N/A N/A - character - writes a - character - string. - - s Precision N/A N/A char* wchar_t* N/A N/A N/A N/A N/A - specifies the - maximum number - of bytes to be - written. - converts a - signed decimal - integer in the - style [-]dddd. - - Precision - specifies the - minimum number - of digits to - d appear. The - i default N/A - precision is - 1. - If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. - converts a - signed octal - integer in the - style [-]oooo. - - Precision - specifies the signed signed signed signed signed - minimum number char short int long long intmax_t - of digits to long - appear. The - default - precision is - 1. If both the - converted - value and the - precision are - 0 the - o conversion N/A - results in no - characters. In - the - alternative - implementation - precision is - increased if - necessary, to - write one - leading zero. - In that case - if both the - converted - value and the - precision are - 0, single - 0 is - written. - converts a size_t ptrdiff_t - signed - hexadecimal - integer in the - style [-]hhhh. - - For the x - conversion - letters abcdef - are used. - For the X - conversion - letters ABCDEF - are used. - Precision - specifies the - minimum number - of digits to - x appear. The N/A - X default - precision is - 1. If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. In unsigned unsigned unsigned unsigned unsigned - the char short int long long uintmax_t - alternative long - implementation - 0x or 0X is - prefixed to - results if the - converted - value is - nonzero. - converts an - unsigned - decimal - integer in the - style dddd. - - Precision - specifies the - minimum number - of digits to - u appear. The N/A - default - precision is - 1. If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. - converts - floating-point - number to the - decimal - notation in - the style - [-]ddd.ddd. - - Precision - specifies the - minimum number - of digits to - appear after - the decimal - f point - F character. The N/A N/A N/A N/A N/A N/A - default - precision is - 6. In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to the -format - decimal - exponent - notation. - - For the e - conversion - style - [-]d.ddde±dd - is used. - For the E - conversion - style - [-]d.dddE±dd - is used. - The exponent - contains at - least two - digits, more - digits are - used only if - necessary. If - e the value is - E 0, the N/A N/A N/A N/A N/A N/A - exponent is - also 0. - Precision - specifies the - minimum number - of digits to - appear after - the decimal - point - character. The - default - precision is - 6. In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to the - hexadecimal - exponent - notation. - - For the a - conversion - style - [-]0xh.hhhp±d - is used. - For the A - conversion - style - [-]0Xh.hhhP±d - is used. - The first - hexadecimal - digit is 0 if - the argument - is not a - normalized - floating point double double long - value. If the double - value is 0, - a the exponent - A is also 0. N/A N/A N/A N/A N/A N/A - Precision - specifies the - minimum number - of digits to - appear after - the decimal - point - character. The - default - precision is - sufficient for - exact - representation - of the value. - In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to - decimal or - decimal - exponent - notation - depending on - the value and - the precision. - - For the g - conversion - style - conversion - with style e - or f will be - performed. - For the G - conversion - style - conversion - with style E - or F will be - performed. - Let P equal - the precision - if nonzero, 6 - if the - precision is - not specified, - or 1 if the - precision is - 0. Then, if - a conversion - with style E - g would have an - G exponent of X: N/A N/A N/A N/A N/A N/A - - * if P > X ≥ - −4, the - conversion - is with - style f or - F and - precision - P − 1 − X. - * otherwise, - the - conversion - is with - style e or - E and - precision - P − 1. - - Unless - alternative - representation - is requested - the trailing - zeros are - removed, also - the decimal - point - character is - removed if no - fractional - part is left. - For infinity - and - not-a-number - conversion - style see - notes. - returns the - number of - characters - written so far - by this call - to the - function. - n N/A N/A int* N/A N/A N/A N/A N/A N/A - The result is - written to the - value pointed - to by the - argument. The - complete - specification - must be %n. - writes an - implementation - defined - p character N/A N/A void* N/A N/A N/A N/A N/A N/A - sequence - defining a - pointer. -.SH Notes: - - The floating point conversion functions convert infinity to inf or infinity. Which one is used is - implementation defined. - Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined. - The conversions F, E, G, A output INF, INFINITY, NAN instead. - The correct conversion specifiers for the fixed-width character types (std:int8_t, etc) are defined in - the header -vlist - variable argument list containing the data to print + stream - output file stream to write to + buffer - pointer to a character string to write to + buf_size - maximum number of characters to write + format - pointer to a null-terminated character string specifying how to interpret + the data + vlist - variable argument list containing the data to print + + The format string consists of ordinary byte characters (except %), which are copied + unchanged into the output stream, and conversion specifications. Each conversion + specification has the following format: + + * introductory % character. + + * (optional) one or more flags that modify the behavior of the conversion: + + * -: the result of the conversion is left-justified within the field (by default + it is right-justified). + * +: the sign of signed conversions is always prepended to the result of the + conversion (by default the result is preceded by minus only when it is + negative). + * space: if the result of a signed conversion does not start with a sign + character, or is empty, space is prepended to the result. It is ignored if + + flag is present. + * #: alternative form of the conversion is performed. See the table below for + exact effects otherwise the behavior is undefined. + * 0: for integer and floating-point number conversions, leading zeros are used to + pad the field instead of space characters. For integer numbers it is ignored if + the precision is explicitly specified. For other conversions using this flag + results in undefined behavior. It is ignored if - flag is present. + + * (optional) integer value or * that specifies minimum field width. The result is + padded with space characters (by default), if required, on the left when + right-justified, or on the right if left-justified. In the case when * is used, + the width is specified by an additional argument of type int, which appears + before the argument to be converted and the argument supplying precision if one + is supplied. If the value of the argument is negative, it results with the - + flag specified and positive field width (Note: This is the minimum width: The + value is never truncated.). + + * (optional) . followed by integer number or *, or neither that specifies + precision of the conversion. In the case when * is used, the precision is + specified by an additional argument of type int, which appears before the + argument to be converted, but after the argument supplying minimum field width + if one is supplied. If the value of this argument is negative, it is ignored. If + neither a number nor * is used, the precision is taken as zero. See the table + below for exact effects of precision. + + * (optional) length modifier that specifies the size of the argument (in + combination with the conversion format specifier, it specifies the type of the + corresponding argument). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Expected +Specifier Argument Type + Length hh ll j z t + Modifier→ h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + Writes literal + %. The full + % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A + specification + must be %%. + Writes a single + character. + + The argument is + first converted + to unsigned + char. If the l + c modifier is N/A N/A int wint_t N/A N/A N/A N/A N/A + used, the + argument is + first converted + to a character + string as if by + %ls with a + wchar_t[2] + argument. + Writes a + character string + + The argument + must be a + pointer to the + initial element + of an array of + characters. + Precision + specifies the + maximum number + of bytes to be + written. If + Precision is not + specified, + writes every + s byte up to and N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + not including + the first null + terminator. If + the l specifier + is used, the + argument must be + a pointer to the + initial element + of an array of + wchar_t, which + is converted to + char array as if + by a call to + wcrtomb with + zero-initialized + conversion + state. + Converts a + signed integer + into decimal + representation + [-]dddd. + + Precision + specifies the + minimum number + of digits to + d appear. The signed short int long long intmax_t signed ptrdiff_t N/A + i default char long size_t + precision is 1. + + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts an + unsigned integer + into octal + representation + oooo. + + Precision + specifies the + minimum number + of digits to + appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + o the conversion N/A + results in no + characters. In + the alternative + implementation + precision is + increased if + necessary, to + write one + leading zero. In + that case if + both the + converted value + and the + precision are 0, + single 0 is + written. + + Converts an + unsigned integer + into hexadecimal + representation + hhhh. + + For the x + conversion + letters abcdef + are used. unsigned unsigned + For the X unsigned unsigned unsigned unsigned long long uintmax_t size_t version of + conversion char short int long ptrdiff_t + letters ABCDEF + are used. + Precision + specifies the + minimum number + x of digits to N/A + X appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. In + the alternative + implementation + 0x or 0X is + prefixed to + results if the + converted value + is nonzero. + + Converts an + unsigned integer + into decimal + representation + dddd. + + Precision + specifies the + minimum number + of digits to + u appear. The N/A + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts + floating-point + number to the + decimal notation + in the style + [-]ddd.ddd. + + Precision + specifies the + exact number of + digits to appear + after the + f decimal point + F character. The N/A N/A N/A N/A N/A N/A + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + decimal exponent + notation. + + For the e + conversion style + [-]d.ddde±dd is + used. + For the E + conversion style + [-]d.dddE±dd is + used. + The exponent + contains at + least two + digits, more + digits are used + only if + necessary. If + e the value is 0, N/A N/A N/A N/A N/A N/A + E the exponent is + also 0. + Precision + specifies the + exact number of + digits to appear + after the + decimal point + character. The + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + hexadecimal + exponent + notation. + + For the a + conversion style + [-]0xh.hhhp±d is + used. + For the A + conversion style + [-]0Xh.hhhP±d is + used. + The first + hexadecimal + digit is not 0 + if the argument + is a normalized + floating-point + value. If the double double\fI(C++11)\fP long + a value is 0, the double + A exponent is also N/A N/A N/A N/A N/A N/A + 0. Precision + \fI(C++11)\fP specifies the + exact number of + digits to appear + after the + hexadecimal + point character. + The default + precision is + sufficient for + exact + representation + of the value. In + the alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + + Converts + floating-point + number to + decimal or + decimal exponent + notation + depending on the + value and the + precision. + + For the g + conversion style + conversion with + style e or f + will be + performed. + For the G + conversion style + conversion with + style E or F + will be + performed. + Let P equal the + precision if + nonzero, 6 if + the precision is + not specified, + or 1 if the + precision is 0. + Then, if a + conversion with + style E would + g have an exponent + G of X: N/A N/A N/A N/A N/A N/A + + * if P > X ≥ + −4, the + conversion + is with + style f or F + and + precision P + − 1 − X. + * otherwise, + the + conversion + is with + style e or E + and + precision P + − 1. + + Unless + alternative + representation + is requested the + trailing zeros + are removed, + also the decimal + point character + is removed if no + fractional part + is left. For + infinity and + not-a-number + conversion style + see notes. + Returns the + number of + characters + written so far + by this call to + the function. + + The result is signed long signed + n written to the char* short* int* long* long* intmax_t* size_t* ptrdiff_t* N/A + value pointed to + by the argument. + The + specification + may not contain + any flag, field + width, or + precision. + Writes an + implementation + defined + p character N/A N/A void* N/A N/A N/A N/A N/A N/A + sequence + defining a + pointer. + + The floating-point conversion functions convert infinity to inf or infinity. Which + one is used is implementation defined. + + Not-a-number is converted to nan or nan(char_sequence). Which one is used is + implementation defined. + + The conversions F, E, G, A output INF, INFINITY, NAN instead. + + Even though %c expects int argument, it is safe to pass a char because of the + integer promotion that takes place when a variadic function is called. + + The correct conversion specifications for the fixed-width character types (int8_t, + etc) are defined in the header (although PRIdMAX, PRIuMAX, etc is + synonymous with %jd, %ju, etc). + + The memory-writing conversion specifier %n is a common target of security exploits + where format strings depend on user input and is not supported by the bounds-checked + printf_s family of functions. + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple %n results in the same variable or, as an edge case, + printing a string modified by an earlier %n within the same call. + + If a conversion specification is invalid, the behavior is undefined. .SH Return value @@ -450,30 +501,70 @@ vlist - variable argument list containing the data to print returns the total number of characters (not including the terminating null-byte) which would have been written, if the limit was not imposed. +.SH Notes + + All these functions invoke va_arg at least once, the value of arg is indeterminate + after the return. These functions do not invoke va_end, and it must be done by the + caller. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + void debug_log(const char *fmt, ...) + { + std::time_t t = std::time(nullptr); + char time_buf[100]; + std::strftime(time_buf, sizeof time_buf, "%D %T", std::gmtime(&t)); + std::va_list args1; + va_start(args1, fmt); + std::va_list args2; + va_copy(args2, args1); + std::vector buf(1 + std::vsnprintf(nullptr, 0, fmt, args1)); + va_end(args1); + std::vsnprintf(buf.data(), buf.size(), fmt, args2); + va_end(args2); + std::printf("%s [debug]: %s\\n", time_buf, buf.data()); + } + + int main() + { + debug_log("Logging, %d, %d, %d", 1, 2, 3); + } + +.SH Output: + + 04/13/15 15:09:18 [debug]: Logging, 1, 2, 3 .SH See also printf - fprintf prints formatted output to stdout, a file stream or a buffer - sprintf \fI(function)\fP - snprintf + fprintf prints formatted output to stdout, a file stream or a + sprintf buffer + snprintf \fI(function)\fP \fI(C++11)\fP vscanf - vfscanf reads formatted input from stdin, a file stream or a buffer - vsscanf using variable argument list - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP + vfscanf reads formatted input from stdin, a file stream or a + vsscanf buffer + \fI(C++11)\fP using variable argument list + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP + vprint_unicode prints to Unicode capable stdout or a file stream using + vprint_unicode_locking type-erased argument representation + (C++23) \fI(function)\fP + (C++23) + vprint_nonunicode prints to stdout or a file stream using type-erased + vprint_nonunicode_locking argument representation + (C++23) \fI(function)\fP + (C++23) C documentation for vprintf, vfprintf, vsprintf, vsnprintf - -.SH Category: - - * Todo no example diff --git a/man/std::vscanf,std::vfscanf,std::vsscanf.3 b/man/std::vscanf,std::vfscanf,std::vsscanf.3 index 9dee3391f..64eb7fd24 100644 --- a/man/std::vscanf,std::vfscanf,std::vsscanf.3 +++ b/man/std::vscanf,std::vfscanf,std::vsscanf.3 @@ -1,14 +1,17 @@ -.TH std::vscanf,std::vfscanf,std::vsscanf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vscanf,std::vfscanf,std::vsscanf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vscanf,std::vfscanf,std::vsscanf \- std::vscanf,std::vfscanf,std::vsscanf + .SH Synopsis Defined in header - int vscanf( const char* format, va_list vlist ); \fB(1)\fP \fI(since C++11)\fP - int vfscanf( std::FILE* stream, const char* format, va_list vlist \fB(2)\fP \fI(since C++11)\fP - ); - int vsscanf( const char* buffer, const char* format, va_list vlist \fB(3)\fP \fI(since C++11)\fP - ); + int vscanf( const char* format, std::va_list vlist ); \fB(1)\fP \fI(since C++11)\fP + int vfscanf( std::FILE* stream, const char* format, std::va_list \fB(2)\fP \fI(since C++11)\fP + vlist ); + int vsscanf( const char* buffer, const char* format, std::va_list \fB(3)\fP \fI(since C++11)\fP + vlist ); - Reads data from the a variety of sources, interprets it according to format and - stores the results into locations defined by vlist. + Reads data from a variety of sources, interprets it according to format and stores + the results into locations defined by vlist. 1) Reads the data from stdin. 2) Reads the data from file stream stream. @@ -16,170 +19,263 @@ .SH Parameters -stream - input file stream to read from -buffer - pointer to a null-terminated character string to read from - pointer to a null-terminated character string specifying how to read the input. - - The format string consists of whitespace characters (any single whitespace character in the format string consumes - all available consecutive whitespace characters from the input), non-whitespace characters except % (each such - character in the format string consumes exactly one identical character from the input) and conversion - specifications. Each conversion specification has the following format: - - * introductory % character - - * (optional) assignment-suppressing character *. If this option is present, the function does not assign the - result of the conversion to any receiving argument. - - * (optional) integer number (greater than zero) that specifies maximum field width, that is, the maximum number of - characters that the function is allowed to consume when doing the conversion specified by the current conversion - specification. Note that %s and %[ may lead to buffer overflow if the width is not provided. - - * (optional) length modifier that specifies the size of the receiving argument, that is, the actual destination - type. This affects the conversion accuracy and overflow rules. The default destination type is different for - each conversion type (see table below). - - * conversion format specifier - - The following format specifiers are available: - - Conversion Explanation Argument type - specifier - length modifier hh h \fI(none)\fP l ll j z t L - % matches literal % N/A N/A N/A N/A N/A N/A N/A N/A N/A - c matches a single - character - matches a character - s string (a sequence of - non-whitespace - characters) - matches a non-empty - sequence of character - from set of - characters. N/A N/A char* wchar_t* N/A N/A N/A N/A N/A - - If the first character - [set] of the set is ^, then - all characters not in - the set are matched. - If the set begins with - ] or ^] then the ] - character is also - included into the set. - matches a decimal - integer. - - d The format of the - number is the same as - expected by strtol() - with the value 10 for - the base argument - matches a decimal - integer. - - i The format of the - number is the same as - expected by strtol() - with the value 0 for -format - the base argument - matches a unsigned - decimal integer. - - u The format of the - number is the same as - expected by strtoul() - with the value 0 for signed - the base argument signed signed signed signed long - matches an octal char* or short* int* or long* or long* or intmax_t* - integer. unsigned or unsigned unsigned unsigned or size_t* ptrdiff_t* N/A - char* unsigned int* long* long uintmax_t* - o The format of the short* long* - number is the same as - expected by strtol() - with the value 8 for - the base argument - matches an hexadecimal - integer. - - x The format of the - number is the same as - expected by strtol() - with the value 16 for - the base argument - returns the number of - characters read so - far. - - No input is consumed. - n Does not increment the - assignment count. If - the specifier has - assignment-suppressing - operator defined, the - behavior is undefined - matches a - a, A floating-point number. - e, E N/A N/A float* double* N/A N/A N/A N/A long - f, F The format of the double* - g, G number is the same as - expected by strtof() - matches implementation - defined character - sequence defining a - pointer. - p N/A N/A void** N/A N/A N/A N/A N/A N/A - printf family of - functions should - produce the same - sequence using %p - format specifier - - All conversion specifiers other than [, c, and n consume and discard all leading whitespace characters before - attempting to parse the input. These consumed characters do not count towards the specified maximum field width. - - The conversion specifiers lc, ls, and l[ perform multibyte-to-wide character conversion as if by calling - std::mbrtowc with an std::mbstate_t object initialized to zero before the first character is converted. - - The conversion specifiers s and [ always store the null terminator in addition to the matched characters. The size - of the destination array must be at least one greater than the specified field width. - - The correct conversion specifications for the fixed-width character types (std:int8_t, etc) are defined in the - header . -vlist - variable argument list containing the receiving arguments + stream - input file stream to read from + buffer - pointer to a null-terminated character string to read from + format - pointer to a null-terminated character string specifying how to read the + input + vlist - variable argument list containing the receiving arguments. + + The format string consists of + + * non-whitespace multibyte characters except %: each such character in the format + string consumes exactly one identical character from the input stream, or causes + the function to fail if the next character on the stream does not compare equal. + * whitespace characters: any single whitespace character in the format string + consumes all available consecutive whitespace characters from the input + (determined as if by calling isspace in a loop). Note that there is no + difference between "\\n", " ", "\\t\\t", or other whitespace in the format string. + * conversion specifications. Each conversion specification has the following + format: + + * introductory % character. + + * (optional) assignment-suppressing character *. If this option is present, the + function does not assign the result of the conversion to any receiving argument. + + * (optional) integer number (greater than zero) that specifies maximum field + width, that is, the maximum number of characters that the function is allowed to + consume when doing the conversion specified by the current conversion + specification. Note that %s and %[ may lead to buffer overflow if the width is + not provided. + + * (optional) length modifier that specifies the size of the receiving argument, + that is, the actual destination type. This affects the conversion accuracy and + overflow rules. The default destination type is different for each conversion + type (see table below). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Argument type +specifier + hh ll j z t + Length modifier → h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + % Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A + Matches a character or + a sequence of + characters. + + If a width specifier + is used, matches + exactly width + c characters (the + argument must be a + pointer to an array + with sufficient room). + Unlike %s and %[, does + not append the null + character to the + array. + Matches a sequence of + non-whitespace + characters (a string). + + If width specifier is + used, matches up to + width or until the + first whitespace + s character, whichever + appears first. Always + stores a null + character in addition + to the characters + matched (so the + argument array must + have room for at least + width+1 characters) N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + Matches a non-empty + sequence of character + from set of + characters. + + If the first character + of the set is ^, then + all characters not in + the set are matched. + If the set begins with + ] or ^] then the ] + character is also + included into the set. + It is + implementation-defined + [set] whether the character + - in the non-initial + position in the + scanset may be + indicating a range, as + in [0-9]. If width + specifier is used, + matches only up to + width. Always stores a + null character in + addition to the + characters matched (so + the argument array + must have room for at + least width+1 + characters) + Matches a decimal + integer. + + d The format of the + number is the same as + expected by strtol + with the value 10 for + the base argument + Matches an integer. + + The format of the + number is the same as + i expected by strtol + with the value 0 for + the base argument + (base is determined by + the first characters + parsed) + Matches an unsigned + decimal integer. + + u The format of the + number is the same as + expected by strtoul signed + with the value 10 for signed signed signed signed long + the base argument. char* or short* int* or long* or long* or intmax_t* + Matches an unsigned unsigned or unsigned unsigned unsigned or size_t* ptrdiff_t* N/A + octal integer. char* unsigned int* long* long uintmax_t* + short* long* + o The format of the + number is the same as + expected by strtoul + with the value 8 for + the base argument + Matches an unsigned + hexadecimal integer. + + x, X The format of the + number is the same as + expected by strtoul + with the value 16 for + the base argument + Returns the number of + characters read so + far. + + No input is consumed. + n Does not increment the + assignment count. If + the specifier has + assignment-suppressing + operator defined, the + behavior is undefined + a, Matches a + A\fI(C++11)\fP floating-point number. + e, E N/A N/A float* double* N/A N/A N/A N/A long + f, F The format of the double* + g, G number is the same as + expected by strtof + Matches implementation + defined character + sequence defining a + pointer. + p N/A N/A void** N/A N/A N/A N/A N/A N/A + printf family of + functions should + produce the same + sequence using %p + format specifier + + For every conversion specifier other than n, the longest sequence of input + characters which does not exceed any specified field width and which either is + exactly what the conversion specifier expects or is a prefix of a sequence it would + expect, is what's consumed from the stream. The first character, if any, after this + consumed sequence remains unread. If the consumed sequence has length zero or if the + consumed sequence cannot be converted as specified above, the matching failure + occurs unless end-of-file, an encoding error, or a read error prevented input from + the stream, in which case it is an input failure. + + All conversion specifiers other than [, c, and n consume and discard all leading + whitespace characters (determined as if by calling isspace) before attempting to + parse the input. These consumed characters do not count towards the specified + maximum field width. + + The conversion specifiers lc, ls, and l[ perform multibyte-to-wide character + conversion as if by calling mbrtowc with an mbstate_t object initialized to zero + before the first character is converted. + + The conversion specifiers s and [ always store the null terminator in addition to + the matched characters. The size of the destination array must be at least one + greater than the specified field width. The use of %s or %[, without specifying the + destination array size, is as unsafe as std::gets. + + The correct conversion specifications for the fixed-width integer types (int8_t, + etc) are defined in the header (although SCNdMAX, SCNuMAX, etc is + synonymous with %jd, %ju, etc). + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple fields in the same "sink" variable. + + When parsing an incomplete floating-point value that ends in the exponent with no + digits, such as parsing "100er" with the conversion specifier %f, the sequence + "100e" (the longest prefix of a possibly valid floating-point number) is consumed, + resulting in a matching error (the consumed sequence cannot be converted to a + floating-point number), with "r" remaining. Some existing implementations do not + follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug + 1765. .SH Return value Number of arguments successfully read, or EOF if failure occurs. +.SH Notes + + All these functions invoke va_arg at least once, the value of arg is indeterminate + after the return. These functions to not invoke va_end, and it must be done by the + caller. + .SH Example - + // Run this code - #include - #include #include + #include + #include #include - + void checked_sscanf(int count, const char* buf, const char *fmt, ...) { - va_list ap; + std::va_list ap; va_start(ap, fmt); - if(std::vsscanf(buf, fmt, ap) != count) + if (std::vsscanf(buf, fmt, ap) != count) throw std::runtime_error("parsing error"); va_end(ap); } - + int main() { - try { + try + { int n, m; - std::cout << "Parsing '1 2'..."; + std::cout << "Parsing '1 2'... "; checked_sscanf(2, "1 2", "%d %d", &n, &m); std::cout << "success\\n"; - std::cout << "Parsing '1 a'..."; + std::cout << "Parsing '1 a'... "; checked_sscanf(2, "1 a", "%d %d", &n, &m); std::cout << "success\\n"; - } catch(const std::exception& e) + } + catch (const std::exception& e) { std::cout << e.what() << '\\n'; } @@ -187,18 +283,18 @@ vlist - variable argument list containing the receiving arguments .SH Output: - Parsing '1 2'...success - Parsing '1 a'...parsing error + Parsing '1 2'... success + Parsing '1 a'... parsing error .SH See also scanf reads formatted input from stdin, a file stream or a buffer - fscanf \fI(function)\fP + fscanf \fI(function)\fP sscanf vprintf vfprintf prints formatted output to stdout, a file stream or a buffer vsprintf using variable argument list - vsnprintf \fI(function)\fP + vsnprintf \fI(function)\fP \fI(C++11)\fP C documentation for vscanf, diff --git a/man/std::vwprintf,std::vfwprintf,std::vswprintf.3 b/man/std::vwprintf,std::vfwprintf,std::vswprintf.3 index 9866bdc31..b5c37e7de 100644 --- a/man/std::vwprintf,std::vfwprintf,std::vswprintf.3 +++ b/man/std::vwprintf,std::vfwprintf,std::vswprintf.3 @@ -1,9 +1,12 @@ -.TH std::vwprintf,std::vfwprintf,std::vswprintf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vwprintf,std::vfwprintf,std::vswprintf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vwprintf,std::vfwprintf,std::vswprintf \- std::vwprintf,std::vfwprintf,std::vswprintf + .SH Synopsis Defined in header int vwprintf( const wchar_t* format, va_list vlist ); \fB(1)\fP int vfwprintf( std::FILE* stream, const wchar_t* format, va_list vlist ); \fB(2)\fP - int vswprintf( const wchar_t* buffer, std::size_t size, const wchar_t* format, \fB(3)\fP + int vswprintf( wchar_t* buffer, std::size_t buf_size, const wchar_t* format, \fB(3)\fP va_list vlist ); Loads the data from locations, defined by vlist,, converts them to wide string @@ -11,16 +14,497 @@ 1) Writes the results to stdout. 2) Writes the results to a file stream stream. - 3) Writes the results to a wide string buffer. + 3) Writes the results to a wide string buffer. At most size-1 wide characters are + written followed by null wide character. .SH Parameters - This section is incomplete + stream - output wide stream to write to + buffer - pointer to a wide string to write to + buf_size - maximum number of wide characters to write + format - pointer to a null-terminated wide string specifying how to interpret the + data + vlist - variable argument list containing the data to print. + + The format string consists of ordinary wide characters (except %), which are copied + unchanged into the output stream, and conversion specifications. Each conversion + specification has the following format: + + * introductory % character. + + * (optional) one or more flags that modify the behavior of the conversion: + + * -: the result of the conversion is left-justified within the field (by default + it is right-justified). + * +: the sign of signed conversions is always prepended to the result of the + conversion (by default the result is preceded by minus only when it is + negative). + * space: if the result of a signed conversion does not start with a sign + character, or is empty, space is prepended to the result. It is ignored if + + flag is present. + * #: alternative form of the conversion is performed. See the table below for + exact effects otherwise the behavior is undefined. + * 0: for integer and floating-point number conversions, leading zeros are used to + pad the field instead of space characters. For integer numbers it is ignored if + the precision is explicitly specified. For other conversions using this flag + results in undefined behavior. It is ignored if - flag is present. + + * (optional) integer value or * that specifies minimum field width. The result is + padded with space characters (by default), if required, on the left when + right-justified, or on the right if left-justified. In the case when * is used, + the width is specified by an additional argument of type int, which appears + before the argument to be converted and the argument supplying precision if one + is supplied. If the value of the argument is negative, it results with the - + flag specified and positive field width (Note: This is the minimum width: The + value is never truncated.). + + * (optional) . followed by integer number or *, or neither that specifies + precision of the conversion. In the case when * is used, the precision is + specified by an additional argument of type int, which appears before the + argument to be converted, but after the argument supplying minimum field width + if one is supplied. If the value of this argument is negative, it is ignored. If + neither a number nor * is used, the precision is taken as zero. See the table + below for exact effects of precision. + + * (optional) length modifier that specifies the size of the argument (in + combination with the conversion format specifier, it specifies the type of the + corresponding argument). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Expected +Specifier Argument Type + Length hh ll j z t + Modifier→ h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + Writes literal + %. The full + % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A + specification + must be %%. + Writes a single + character. + + The argument is + first converted + to wchar_t as if + c by calling N/A N/A int wint_t N/A N/A N/A N/A N/A + btowc. If the l + modifier is + used, the wint_t + argument is + first converted + to wchar_t. + Writes a + character string + + The argument + must be a + pointer to the + initial element + of a character + array containing + a multibyte + character + sequence + beginning in the + initial shift + state, which is + converted to + wide character + array as if by a + call to mbrtowc + with + zero-initialized + s conversion N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + state. Precision + specifies the + maximum number + of wide + characters to be + written. If + Precision is not + specified, + writes every + wide characters + up to and not + including the + first null + terminator. If + the l specifier + is used, the + argument must be + a pointer to the + initial element + of an array of + wchar_t. + Converts a + signed integer + into decimal + representation + [-]dddd. + + Precision + specifies the + minimum number + of digits to + d appear. The signed short int long long intmax_t signed ptrdiff_t N/A + i default char long size_t + precision is 1. + + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts an + unsigned integer + into octal + representation + oooo. + + Precision + specifies the + minimum number + of digits to + appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + o the conversion N/A + results in no + characters. In + the alternative + implementation + precision is + increased if + necessary, to + write one + leading zero. In + that case if + both the + converted value + and the + precision are 0, + single 0 is + written. + + Converts an + unsigned integer + into hexadecimal + representation + hhhh. + + For the x + conversion + letters abcdef + are used. unsigned unsigned + For the X unsigned unsigned unsigned unsigned long long uintmax_t size_t version of + conversion char short int long ptrdiff_t + letters ABCDEF + are used. + Precision + specifies the + minimum number + x of digits to N/A + X appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. In + the alternative + implementation + 0x or 0X is + prefixed to + results if the + converted value + is nonzero. + + Converts an + unsigned integer + into decimal + representation + dddd. + + Precision + specifies the + minimum number + of digits to + u appear. The N/A + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts + floating-point + number to the + decimal notation + in the style + [-]ddd.ddd. + + Precision + specifies the + exact number of + digits to appear + after the + f decimal point + F character. The N/A N/A N/A N/A N/A N/A + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + decimal exponent + notation. + + For the e + conversion style + [-]d.ddde±dd is + used. + For the E + conversion style + [-]d.dddE±dd is + used. + The exponent + contains at + least two + digits, more + digits are used + only if + necessary. If + e the value is 0, N/A N/A N/A N/A N/A N/A + E the exponent is + also 0. + Precision + specifies the + exact number of + digits to appear + after the + decimal point + character. The + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + hexadecimal + exponent + notation. + + For the a + conversion style + [-]0xh.hhhp±d is + used. + For the A + conversion style + [-]0Xh.hhhP±d is + used. + The first + hexadecimal + digit is not 0 + if the argument + is a normalized + floating-point + value. If the double double\fI(C++11)\fP long + a value is 0, the double + A exponent is also N/A N/A N/A N/A N/A N/A + 0. Precision + \fI(C++11)\fP specifies the + exact number of + digits to appear + after the + hexadecimal + point character. + The default + precision is + sufficient for + exact + representation + of the value. In + the alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + + Converts + floating-point + number to + decimal or + decimal exponent + notation + depending on the + value and the + precision. + + For the g + conversion style + conversion with + style e or f + will be + performed. + For the G + conversion style + conversion with + style E or F + will be + performed. + Let P equal the + precision if + nonzero, 6 if + the precision is + not specified, + or 1 if the + precision is 0. + Then, if a + conversion with + style E would + g have an exponent + G of X: N/A N/A N/A N/A N/A N/A + + * if P > X ≥ + −4, the + conversion + is with + style f or F + and + precision P + − 1 − X. + * otherwise, + the + conversion + is with + style e or E + and + precision P + − 1. + + Unless + alternative + representation + is requested the + trailing zeros + are removed, + also the decimal + point character + is removed if no + fractional part + is left. For + infinity and + not-a-number + conversion style + see notes. + Returns the + number of + characters + written so far + by this call to + the function. + + The result is signed long signed + n written to the char* short* int* long* long* intmax_t* size_t* ptrdiff_t* N/A + value pointed to + by the argument. + The + specification + may not contain + any flag, field + width, or + precision. + Writes an + implementation + defined + p character N/A N/A void* N/A N/A N/A N/A N/A N/A + sequence + defining a + pointer. + + The floating-point conversion functions convert infinity to inf or infinity. Which + one is used is implementation defined. + + Not-a-number is converted to nan or nan(char_sequence). Which one is used is + implementation defined. + + The conversions F, E, G, A output INF, INFINITY, NAN instead. + + Even though %c expects int argument, it is safe to pass a char because of the + integer promotion that takes place when a variadic function is called. + + The correct conversion specifications for the fixed-width character types (int8_t, + etc) are defined in the header (although PRIdMAX, PRIuMAX, etc is + synonymous with %jd, %ju, etc). + + The memory-writing conversion specifier %n is a common target of security exploits + where format strings depend on user input and is not supported by the bounds-checked + printf_s family of functions. + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple %n results in the same variable or, as an edge case, + printing a string modified by an earlier %n within the same call. + + If a conversion specification is invalid, the behavior is undefined. .SH Return value - Number of wide characters written if successful or negative value if an error + 1,2) Number of wide characters written if successful or negative value if an error occurred. + 3) Number of wide characters written (not counting the terminating null wide + character) if successful or negative value if an encoding error occurred or if the + number of characters to be generated was equal or greater than size. + +.SH Notes + + While narrow strings provide std::vsnprintf, which makes it possible to determine + the required output buffer size, there is no equivalent for wide strings, and in + order to determine the buffer size, the program may need to call std::vswprintf, + check the result value, and reallocate a larger buffer, trying again until + successful. .SH Example @@ -29,15 +513,18 @@ .SH See also - wprintf prints formatted wide character output to stdout, a file stream or a buffer - fwprintf \fI(function)\fP - swprintf + vprintf + vfprintf prints formatted output to stdout, a file stream or a buffer + vsprintf using variable argument list + vsnprintf \fI(function)\fP + \fI(C++11)\fP + wprintf prints formatted wide character output to stdout, a file stream or a + fwprintf buffer + swprintf \fI(function)\fP C documentation for vwprintf, vfwprintf, vswprintf - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::vwscanf,std::vfwscanf,std::vswscanf.3 b/man/std::vwscanf,std::vfwscanf,std::vswscanf.3 index b885f4605..1cbd677e9 100644 --- a/man/std::vwscanf,std::vfwscanf,std::vswscanf.3 +++ b/man/std::vwscanf,std::vfwscanf,std::vswscanf.3 @@ -1,27 +1,237 @@ -.TH std::vwscanf,std::vfwscanf,std::vswscanf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::vwscanf,std::vfwscanf,std::vswscanf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::vwscanf,std::vfwscanf,std::vswscanf \- std::vwscanf,std::vfwscanf,std::vswscanf + .SH Synopsis Defined in header - int vwscanf( const wchar_t* format, va_list vlist ); \fB(1)\fP \fI(since C++11)\fP - int vfwscanf( std::FILE* stream, const wchar_t* format, va_list \fB(2)\fP \fI(since C++11)\fP - vlist ); + int vwscanf( const wchar_t* format, std::va_list vlist ); \fB(1)\fP \fI(since C++11)\fP + int vfwscanf( std::FILE* stream, const wchar_t* format, \fB(2)\fP \fI(since C++11)\fP + std::va_list vlist ); int vswscanf( const wchar_t* buffer, const wchar_t* format, \fB(3)\fP \fI(since C++11)\fP - va_list vlist ); + std::va_list vlist ); Reads data from the a variety of sources, interprets it according to format and stores the results into locations defined by vlist. - 1) Reads the data from stdin - 2) Reads the data from file stream stream - 3) Reads the data from null-terminated wide string buffer + 1) Reads the data from stdin. + 2) Reads the data from file stream stream. + 3) Reads the data from null-terminated wide string buffer. .SH Parameters stream - input file stream to read from buffer - pointer to a null-terminated wide string to read from - pointer to a null-terminated wide string specifying how to read the input. - format - - This section is incomplete - vlist - variable argument list containing the receiving arguments + format - pointer to a null-terminated wide string specifying how to read the input + vlist - variable argument list containing the receiving arguments. + + The format string consists of + + * non-whitespace wide characters except %: each such character in the format + string consumes exactly one identical character from the input stream, or causes + the function to fail if the next character on the stream does not compare equal. + * whitespace characters: any single whitespace character in the format string + consumes all available consecutive whitespace characters from the input + (determined as if by calling iswspace in a loop). Note that there is no + difference between "\\n", " ", "\\t\\t", or other whitespace in the format string. + * conversion specifications. Each conversion specification has the following + format: + + * introductory % character. + + * (optional) assignment-suppressing character *. If this option is present, the + function does not assign the result of the conversion to any receiving argument. + + * (optional) integer number (greater than zero) that specifies maximum field + width, that is, the maximum number of characters that the function is allowed to + consume when doing the conversion specified by the current conversion + specification. Note that %s and %[ may lead to buffer overflow if the width is + not provided. + + * (optional) length modifier that specifies the size of the receiving argument, + that is, the actual destination type. This affects the conversion accuracy and + overflow rules. The default destination type is different for each conversion + type (see table below). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Argument type +specifier + hh ll j z t + Length modifier → h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + % Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A + Matches a character or + a sequence of + characters. + + If a width specifier + is used, matches + exactly width wide + c characters (the + argument must be a + pointer to an array + with sufficient room). + Unlike %s and %[, does + not append the null + character to the + array. + Matches a sequence of + non-whitespace + characters (a string). + + If width specifier is + used, matches up to + width or until the + first whitespace + s character, whichever + appears first. Always + stores a null + character in addition + to the characters + matched (so the + argument array must + have room for at least + width+1 characters) N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + Matches a non-empty + sequence of character + from set of + characters. + + If the first character + of the set is ^, then + all characters not in + the set are matched. + If the set begins with + ] or ^] then the ] + character is also + included into the set. + It is + implementation-defined + [set] whether the character + - in the non-initial + position in the + scanset may be + indicating a range, as + in [0-9]. If width + specifier is used, + matches only up to + width. Always stores a + null character in + addition to the + characters matched (so + the argument array + must have room for at + least width+1 + characters) + Matches a decimal + integer. + + d The format of the + number is the same as + expected by wcstol + with the value 10 for + the base argument + Matches an integer. + + The format of the + number is the same as + i expected by wcstol + with the value 0 for + the base argument + (base is determined by + the first characters + parsed) + Matches an unsigned + decimal integer. + + u The format of the + number is the same as + expected by wcstoul signed + with the value 10 for signed signed signed signed long + the base argument. char* or short* int* or long* or long* or intmax_t* + Matches an unsigned unsigned or unsigned unsigned unsigned or size_t* ptrdiff_t* N/A + octal integer. char* unsigned int* long* long uintmax_t* + short* long* + o The format of the + number is the same as + expected by wcstoul + with the value 8 for + the base argument + Matches an unsigned + hexadecimal integer. + + x, X The format of the + number is the same as + expected by wcstoul + with the value 16 for + the base argument + Returns the number of + characters read so + far. + + No input is consumed. + n Does not increment the + assignment count. If + the specifier has + assignment-suppressing + operator defined, the + behavior is undefined + a, Matches a + A\fI(C++11)\fP floating-point number. + e, E N/A N/A float* double* N/A N/A N/A N/A long + f, F The format of the double* + g, G number is the same as + expected by wcstof + Matches implementation + defined character + sequence defining a + pointer. + p N/A N/A void** N/A N/A N/A N/A N/A N/A + printf family of + functions should + produce the same + sequence using %p + format specifier + + For every conversion specifier other than n, the longest sequence of input + characters which does not exceed any specified field width and which either is + exactly what the conversion specifier expects or is a prefix of a sequence it would + expect, is what's consumed from the stream. The first character, if any, after this + consumed sequence remains unread. If the consumed sequence has length zero or if the + consumed sequence cannot be converted as specified above, the matching failure + occurs unless end-of-file, an encoding error, or a read error prevented input from + the stream, in which case it is an input failure. + + All conversion specifiers other than [, c, and n consume and discard all leading + whitespace characters (determined as if by calling iswspace) before attempting to + parse the input. These consumed characters do not count towards the specified + maximum field width. + + If the length specifier l is not used, the conversion specifiers c, s, and [ perform + wide-to-multibyte character conversion as if by calling wcrtomb with an mbstate_t + object initialized to zero before the first character is converted. + + The conversion specifiers s and [ always store the null terminator in addition to + the matched characters. The size of the destination array must be at least one + greater than the specified field width. The use of %s or %[, without specifying the + destination array size, is as unsafe as std::gets. + + The correct conversion specifications for the fixed-width integer types (int8_t, + etc) are defined in the header (although SCNdMAX, SCNuMAX, etc is + synonymous with %jd, %ju, etc). + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple fields in the same "sink" variable. + + When parsing an incomplete floating-point value that ends in the exponent with no + digits, such as parsing "100er" with the conversion specifier %f, the sequence + "100e" (the longest prefix of a possibly valid floating-point number) is consumed, + resulting in a matching error (the consumed sequence cannot be converted to a + floating-point number), with "r" remaining. Some existing implementations do not + follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug + 1765. .SH Return value @@ -35,14 +245,12 @@ .SH See also wscanf reads formatted wide character input from stdin, a file stream or a buffer - fwscanf \fI(function)\fP + fwscanf \fI(function)\fP swscanf C documentation for vwscanf, vfwscanf, vswscanf - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::wbuffer_convert.3 b/man/std::wbuffer_convert.3 index 1ec6ab709..a47de24ef 100644 --- a/man/std::wbuffer_convert.3 +++ b/man/std::wbuffer_convert.3 @@ -1,12 +1,17 @@ -.TH std::wbuffer_convert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wbuffer_convert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wbuffer_convert \- std::wbuffer_convert + .SH Synopsis Defined in header - template > + class Codecvt, \fI(since C++11)\fP + class Elem = wchar_t, (deprecated in C++17) + class Tr = std::char_traits (removed in C++26) - class wbuffer_convert : public std::basic_streambuf + > class wbuffer_convert : public std::basic_streambuf std::wbuffer_convert is a wrapper over stream buffer of type std::basic_streambuf which gives it the appearance of @@ -14,7 +19,7 @@ character conversion as defined by the facet Codecvt. std::wbuffer_convert assumes ownership of the conversion facet, and cannot use a facet managed by a locale. The standard facets suitable for use with std::wbuffer_convert are std::codecvt_utf8 for - UTF-8/UCS2 and UTF-8/UCS4 conversions and std::codecvt_utf8_utf16 for UTF-8/UTF-16 + UTF-8/UCS-2 and UTF-8/UCS-4 conversions and std::codecvt_utf8_utf16 for UTF-8/UTF-16 conversions. This class template makes the implicit character conversion functionality of @@ -28,39 +33,44 @@ .SH Member functions constructor constructs a new wbuffer_convert - \fI(public member function)\fP + \fI(public member function)\fP operator= the copy assignment operator is deleted \fI(public member function)\fP destructor destructs the wbuffer_convert and its conversion facet - \fI(public member function)\fP + \fI(public member function)\fP rdbuf returns or replaces the underlying narrow stream buffer - \fI(public member function)\fP + \fI(public member function)\fP state returns the current conversion state - \fI(public member function)\fP + \fI(public member function)\fP .SH See also - Character narrow multibyte UTF-8 UTF-16 - conversions (char) (char) (char16_t) - codecvt - UTF-16 c16rtomb codecvt_utf8_utf16 N/A - codecvt_utf8_utf16 - codecvt_utf8_utf16 - UCS2 No codecvt_utf8 codecvt_utf16 - UTF-32/UCS4 mbrtoc32 / codecvt codecvt_utf16 - codecvt_utf8 - UCS2/UCS4 No codecvt_utf8 codecvt_utf16 - (wchar_t) - codecvt No No - (wchar_t) mbsrtowcs / - wcsrtombs + Character locale-defined multibyte UTF-8 UTF-16 + conversions (UTF-8, GB18030) + codecvt + UTF-16 mbrtoc16 / c16rtomb (with C11's codecvt_utf8_utf16 N/A + DR488) codecvt_utf8_utf16 + codecvt_utf8_utf16 + UCS-2 c16rtomb (without C11's DR488) codecvt_utf8 codecvt_utf16 + UTF-32 mbrtoc32 / c32rtomb codecvt codecvt_utf16 + codecvt_utf8 + system + wchar_t: + mbsrtowcs / wcsrtombs + UTF-32 use_facet codecvt_utf16 +(non-Windows) >(locale) + UCS-2 + (Windows) - wstring_convert performs conversions between a wide string and a byte string - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8 converts between UTF-8 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8_utf16 converts between UTF-8 and UTF-16 - \fI(C++11)\fP \fI(class template)\fP + wstring_convert + \fI(C++11)\fP performs conversions between a wide string and a byte string + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8 + \fI(C++11)\fP converts between UTF-8 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8_utf16 + \fI(C++11)\fP converts between UTF-8 and UTF-16 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::wbuffer_convert::rdbuf.3 b/man/std::wbuffer_convert::rdbuf.3 index b52ba9aeb..270229575 100644 --- a/man/std::wbuffer_convert::rdbuf.3 +++ b/man/std::wbuffer_convert::rdbuf.3 @@ -1,57 +1,56 @@ -.TH std::wbuffer_convert::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wbuffer_convert::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wbuffer_convert::rdbuf \- std::wbuffer_convert::rdbuf + .SH Synopsis Defined in header std::streambuf* rdbuf() const; \fB(1)\fP std::streambuf* rdbuf( std::streambuf* bytebuf ); \fB(2)\fP - 1) returns the pointer to the underlying byte stream - - 2) replaces the associated byte stream with bytebuf . + 1) Returns the pointer to the underlying byte stream. + 2) Replaces the associated byte stream with bytebuf. .SH Return value - 1) the current underlying byte stream - - 2) the previous byte stream + 1) The current underlying byte stream. + 2) The previous byte stream. .SH Example - + // Run this code + #include #include - #include #include - #include + #include + int main() { - // convert UTF-8 to UCS4 - std::stringbuf utf8buf(u8"z\\u00df\\u6c34\\U0001d10b"); // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + // Convert UTF-8 to UCS4 + std::stringbuf utf8buf("z\\u00df\\u6c34\\U0001d10b"); + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b" + // or u8"zß水𝄋" std::wbuffer_convert> conv(&utf8buf); std::wistream ucsbuf(&conv); - std::cout << "Reading from a UTF-8 stringbuf via wbuffer_convert:\\n"; - for(wchar_t c; ucsbuf.get(c); ) - std::cout << std::hex << std::showbase << c << '\\n'; - - // reuse the same wbuffer_convert to handle UCS4 to UTF-8 output + std::cout << "Reading from a UTF-8 stringbuf via wbuffer_convert: " + << std::hex << std::showbase; + for (wchar_t c; ucsbuf.get(c);) + std::cout << static_cast(c) << ' '; + + // Reuse the same wbuffer_convert to handle UCS4 to UTF-8 output conv.rdbuf(std::cout.rdbuf()); std::wostream out(&conv); - std::cout << "Sending UCS4 data to std::cout via wbuffer_convert:\\n"; + std::cout << "\\nSending UCS4 data to std::cout via wbuffer_convert: "; out << L"z\\u00df\\u6c34\\U0001d10b\\n"; } .SH Output: - Reading from a UTF-8 stringbuf via wbuffer_convert: - 0x7a - 0xdf - 0x6c34 - 0x1d10b - Sending UCS4 data to std::cout via wbuffer_convert: - zß水𝄋 + Reading from a UTF-8 stringbuf via wbuffer_convert: 0x7a 0xdf 0x6c34 0x1d10b + Sending UCS4 data to std::cout via wbuffer_convert: zß水𝄋 .SH See also constructor constructs a new wbuffer_convert - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::wbuffer_convert::state.3 b/man/std::wbuffer_convert::state.3 index 2a7cbb557..c5f40b455 100644 --- a/man/std::wbuffer_convert::state.3 +++ b/man/std::wbuffer_convert::state.3 @@ -1,4 +1,7 @@ -.TH std::wbuffer_convert::state 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wbuffer_convert::state 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wbuffer_convert::state \- std::wbuffer_convert::state + .SH Synopsis Defined in header state_type state() const; @@ -18,11 +21,11 @@ .SH See also - state returns the current conversion state - \fI(public member function of std::wstring_convert)\fP - mbsinit checks if the mbstate_t object represents initial shift state - \fI(function)\fP + returns the current conversion state + state \fI\fI(public member\fP function of\fP + std::wstring_convert) + mbsinit checks if the std::mbstate_t object represents initial shift state + \fI(function)\fP .SH Category: - * Todo no example diff --git a/man/std::wbuffer_convert::wbuffer_convert.3 b/man/std::wbuffer_convert::wbuffer_convert.3 index 8c933e43a..d6a949968 100644 --- a/man/std::wbuffer_convert::wbuffer_convert.3 +++ b/man/std::wbuffer_convert::wbuffer_convert.3 @@ -1,58 +1,69 @@ -.TH std::wbuffer_convert::wbuffer_convert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wbuffer_convert::wbuffer_convert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wbuffer_convert::wbuffer_convert \- std::wbuffer_convert::wbuffer_convert + .SH Synopsis - explicit wbuffer_convert( std::streambuf* bytebuf = 0, + wbuffer_convert() : wbuffer_convert(nullptr) {} \fB(1)\fP + explicit wbuffer_convert( std::streambuf* bytebuf, - Codecvt* pcvt = new Codecvt, \fB(1)\fP + Codecvt* pcvt = new Codecvt, \fB(2)\fP state_type state = state_type() ); - wbuffer_convert(const std::wbuffer_convert&) = delete; \fB(2)\fP \fI(since C++14)\fP + wbuffer_convert( const std::wbuffer_convert& ) = delete; \fB(3)\fP \fI(since C++14)\fP - 1) Constructs the wbuffer_convert object with the specified underlying byte stream, + 1) Default constructor. + 2) Constructs the wbuffer_convert object with the specified underlying byte stream, specified codecvt facet, and specified initial conversion state (all parameters are - optional) - 2) The copy constructor is deleted, wbuffer_convert is not CopyConstructible + optional). + 3) The copy constructor is deleted, wbuffer_convert is not CopyConstructible. .SH Parameters bytebuf - pointer to std::streambuf to serve as the underlying narrow character stream pcvt - pointer to a standalone (not managed by a locale) std::codecvt facet. The - behavior is undefined if this pointer is null. + behavior is undefined if this pointer is null state - the initial value of the character conversion state + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit + .SH Example - + // Run this code + #include #include - #include #include - #include + #include + int main() { - // wrap a UTF-8 string stream in a UCS4 wbuffer_convert - std::stringbuf utf8buf(u8"z\\u00df\\u6c34\\U0001f34c"); // or u8"zß水🍌" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c"; + // Wrap a UTF-8 string stream in a UCS4 wbuffer_convert + std::stringbuf utf8buf("z\\u00df\\u6c34\\U0001f34c"); + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c" + // or u8"zß水🍌" std::wbuffer_convert> conv_in(&utf8buf); std::wistream ucsbuf(&conv_in); - std::cout << "Reading from a UTF-8 stringbuf via wbuffer_convert:\\n"; - for(wchar_t c; ucsbuf.get(c); ) - std::cout << std::hex << std::showbase << c << '\\n'; - - // wrap a UTF-8 aware std::cout in a UCS4 wbuffer_convert to output UCS4 + std::cout << "Reading from a UTF-8 stringbuf via wbuffer_convert: " + << std::hex << std::showbase; + for (wchar_t c; ucsbuf.get(c);) + std::cout << static_cast(c) << ' '; + + // Wrap a UTF-8 aware std::cout in a UCS4 wbuffer_convert to output UCS4 std::wbuffer_convert> conv_out(std::cout.rdbuf()); std::wostream out(&conv_out); - std::cout << "Sending UCS4 data to std::cout via wbuffer_convert:\\n"; + std::cout << "\\nSending UCS4 data to std::cout via wbuffer_convert: "; out << L"z\\u00df\\u6c34\\U0001f34c\\n"; } .SH Output: - Reading from a UTF-8 stringbuf via wbuffer_convert produces - 0x7a - 0xdf - 0x6c34 - 0x1f34c - Sending UCS4 data to std::cout via wbuffer_convert: - zß水🍌 + Reading from a UTF-8 stringbuf via wbuffer_convert: 0x7a 0xdf 0x6c34 0x1f34c + Sending UCS4 data to std::cout via wbuffer_convert: zß水🍌 diff --git a/man/std::wbuffer_convert::~wbuffer_convert.3 b/man/std::wbuffer_convert::~wbuffer_convert.3 index 9aecaad9f..3b3660288 100644 --- a/man/std::wbuffer_convert::~wbuffer_convert.3 +++ b/man/std::wbuffer_convert::~wbuffer_convert.3 @@ -1,4 +1,7 @@ -.TH std::wbuffer_convert::~wbuffer_convert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wbuffer_convert::~wbuffer_convert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wbuffer_convert::~wbuffer_convert \- std::wbuffer_convert::~wbuffer_convert + .SH Synopsis Defined in header ~wbuffer_convert(); @@ -9,19 +12,19 @@ Some implementations are able to delete any facet, including the locale-specific facets with protected destructors. Other implementations require the facet to have a - public destructor, similar to the the locale-independent facets from . + public destructor, similar to the locale-independent facets from . .SH Example - + // Run this code + #include + #include #include #include - #include - #include - - // utility wrapper to adapt locale-bound facets for wstring/wbuffer convert + + // Utility wrapper to adapt locale-bound facets for wstring/wbuffer convert template struct deletable_facet : Facet { @@ -29,22 +32,23 @@ deletable_facet(Args&& ...args) : Facet(std::forward(args)...) {} ~deletable_facet() {} }; - + int main() { - // GB18030 / UCS4 conversion, using locale-based facet directly - // typedef std::codecvt_byname gbfacet_t; - // Compiler error: "calling a protected destructor of codecvt_byname<> in ~wbuffer_convert" - // std::wbuffer_convert gbto32(std::cout.rdbuf(), - // new gbfacet_t("zh_CN.gb18030")); - - // GB18030 / UCS4 conversion facet using a facet with public destructor + // GB18030 / UCS4 conversion, using locale-based facet directly + // typedef std::codecvt_byname gbfacet_t; + // Compiler error: "calling a protected destructor of codecvt_byname<> in ~wbuffer_convert" + // std::wbuffer_convert + // gbto32(std::cout.rdbuf(), new gbfacet_t("zh_CN.gb18030")); + + // GB18030 / UCS4 conversion facet using a facet with public destructor typedef deletable_facet> gbfacet_t; - std::wbuffer_convert gbto32(std::cout.rdbuf(), - new gbfacet_t("zh_CN.gb18030")); + std::wbuffer_convert + gbto32(std::cout.rdbuf(), new gbfacet_t("zh_CN.gb18030")); } // destructor called here .SH See also - destructor destructs the wstring_convert and its conversion facet - \fI(public member function of std::wstring_convert)\fP + destructs the wstring_convert and its conversion facet + destructor \fI\fI(public member\fP function of\fP + std::wstring_convert) diff --git a/man/std::wcrtomb.3 b/man/std::wcrtomb.3 index b29c976dc..b55d372ee 100644 --- a/man/std::wcrtomb.3 +++ b/man/std::wcrtomb.3 @@ -1,4 +1,7 @@ -.TH std::wcrtomb 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcrtomb 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcrtomb \- std::wcrtomb + .SH Synopsis Defined in header std::size_t wcrtomb( char* s, wchar_t wc, std::mbstate_t* ps ); @@ -6,10 +9,11 @@ Converts a wide character to its narrow multibyte representation. If s is not a null pointer, the function determines the number of bytes necessary to - store the multibyte character representation of wc (including any shift sequences), - and stores the multibyte character representation in the character array whose first - element is pointed to by s. At most MB_CUR_MAX bytes can be written by this - function. + store the multibyte character representation of wc (including any shift sequences, + and taking into account the current multibyte conversion state *ps), and stores the + multibyte character representation in the character array whose first element is + pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written + by this function. If s is a null pointer, the call is equivalent to std::wcrtomb(buf, L'\\0', ps) for some internal buffer buf. @@ -36,29 +40,29 @@ .SH Example - + // Run this code - #include #include - #include #include - + #include + #include + void print_wide(const std::wstring& wstr) { - std::mbstate_t state = std::mbstate_t(); - for(wchar_t wc : wstr) { + std::mbstate_t state{}; + for (wchar_t wc : wstr) + { std::string mb(MB_CUR_MAX, '\\0'); - int ret = std::wcrtomb(&mb[0], wc, &state); + std::size_t ret = std::wcrtomb(&mb[0], wc, &state); std::cout << "multibyte char " << mb << " is " << ret << " bytes\\n"; } } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); - // UTF-8 narrow multibyte encoding - std::wstring wstr = L"z\\u00df\\u6c34\\U0001d10b"; // or L"zß水𝄋" + std::wstring wstr = L"z\\u00df\\u6c34\\U0001f34c"; // or L"zß水🍌" print_wide(wstr); } @@ -67,15 +71,16 @@ multibyte char z is 1 bytes multibyte char ß is 2 bytes multibyte char 水 is 3 bytes - multibyte char 𝄋 is 4 bytes + multibyte char 🍌 is 4 bytes .SH See also wctomb converts a wide character to its multibyte representation - \fI(function)\fP + \fI(function)\fP mbrtowc converts the next multibyte character to wide character, given state - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for wcrtomb diff --git a/man/std::wcscat.3 b/man/std::wcscat.3 index c269019ab..4d8fe6abd 100644 --- a/man/std::wcscat.3 +++ b/man/std::wcscat.3 @@ -1,11 +1,19 @@ -.TH std::wcscat 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcscat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcscat \- std::wcscat + .SH Synopsis Defined in header - wchar_t *wcscat( wchar_t *dest, const wchar_t *src ); + wchar_t* wcscat( wchar_t* dest, const wchar_t* src ); + + Appends a copy of the wide string pointed to by src to the end of the wide string + pointed to by dest. The wide character src[0] replaces the null terminator at the + end of dest. The resulting wide string is null-terminated. + + The behavior is undefined if the destination array is not large enough for the + contents of both src and dest and the terminating null wide character. - Appends a wide string pointed to by src to a wide string pointed to by dest. The - resulting wide string is null-terminated. If the strings overlap, the behavior is - undefined. + The behavior is undefined if the strings overlap. .SH Parameters @@ -14,22 +22,39 @@ .SH Return value - dest + Returns a copy of dest. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main(void) + { + wchar_t str[50] = L"Земля, прощай."; + std::wcscat(str, L" "); + std::wcscat(str, L"В добрый путь."); + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << str << '\\n'; + } + +.SH Possible output: + + Земля, прощай. В добрый путь. .SH See also wcsncat appends a certain amount of wide characters from one wide string to another - \fI(function)\fP + \fI(function)\fP + strcat concatenates two strings + \fI(function)\fP wcscpy copies one wide string to another - \fI(function)\fP + \fI(function)\fP C documentation for wcscat - -.SH Category: - - * Todo no example diff --git a/man/std::wcschr.3 b/man/std::wcschr.3 index 06e7f8d34..9025a3256 100644 --- a/man/std::wcschr.3 +++ b/man/std::wcschr.3 @@ -1,4 +1,7 @@ -.TH std::wcschr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcschr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcschr \- std::wcschr + .SH Synopsis Defined in header const wchar_t* wcschr( const wchar_t* str, wchar_t ch ); @@ -14,31 +17,32 @@ .SH Return value - Pointer to the found character in str, or NULL if no such character is found. + Pointer to the found character in str, or a null pointer if no such character is + found. .SH Example - + // Run this code - #include #include + #include #include - + int main() { - wchar_t arr[] = L"招き猫 кошка"; + const wchar_t arr[] = L"白猫 黒猫 кошки"; const wchar_t* cat = std::wcschr(arr, L'猫'); const wchar_t* dog = std::wcschr(arr, L'犬'); - + std::cout.imbue(std::locale("en_US.utf8")); - - if(cat) + + if (cat) std::cout << "The character 猫 found at position " << cat - arr << '\\n'; else std::cout << "The character 猫 not found\\n"; - - if(dog) + + if (dog) std::cout << "The character 犬 found at position " << dog - arr << '\\n'; else std::cout << "The character 犬 not found\\n"; @@ -46,19 +50,19 @@ .SH Output: - The character 猫 found at position 2 + The character 猫 found at position 1 The character 犬 not found .SH See also - find find characters in the string - \fI(public member function of std::basic_string)\fP + find finds the first occurrence of the given substring + \fI(public member function of std::basic_string)\fP strchr finds the first occurrence of a character - \fI(function)\fP + \fI(function)\fP wcsrchr finds the last occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP finds the first location of any wide character in one wide string, in wcspbrk another wide string - \fI(function)\fP + \fI(function)\fP C documentation for wcschr diff --git a/man/std::wcscmp.3 b/man/std::wcscmp.3 index 8e86d382b..8d2b9adeb 100644 --- a/man/std::wcscmp.3 +++ b/man/std::wcscmp.3 @@ -1,9 +1,18 @@ -.TH std::wcscmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcscmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcscmp \- std::wcscmp + .SH Synopsis Defined in header int wcscmp( const wchar_t* lhs, const wchar_t* rhs ); - Compares two null-terminated wide strings. The comparison is done lexicographically. + Compares two null-terminated wide strings lexicographically. + + The sign of the result is the sign of the difference between the values of the first + pair of wide characters that differ in the strings being compared. + + The behavior is undefined if lhs or rhs are not pointers to null-terminated wide + strings. .SH Parameters @@ -11,28 +20,64 @@ .SH Return value - Negative value if lhs is less than rhs. + Negative value if lhs appears before rhs in lexicographical order. + + Zero if lhs and rhs compare equal. - 0 if lhs is equal to rhs. + Positive value if lhs appears after rhs in lexicographical order. - Positive value if lhs is greater than rhs. +.SH Notes + + This function is not locale-sensitive, unlike std::wcscoll, and the order may not be + meaningful when characters from different Unicode blocks are used together or when + the order of code units does not match collation order. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::vector leaders{L"Ленин", L"Сталин", L"Маленков", + L"Хрущёв", L"Брежнев", L"Андропов", L"Черненко", L"Горбачёв"}; + + std::ranges::sort(leaders, [](auto leaderLHS, auto leaderRHS) + { + return std::wcscmp(leaderLHS, leaderRHS) < 0; + }); + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + for (auto leader : leaders) + std::wcout << leader << '\\n'; + } + +.SH Possible output: + + Андропов + Брежнев + Горбачёв + Ленин + Маленков + Сталин + Хрущёв + Черненко .SH See also wcsncmp compares a certain amount of characters from two wide strings - \fI(function)\fP + \fI(function)\fP wmemcmp compares a certain amount of wide characters from two arrays - \fI(function)\fP + \fI(function)\fP + strcmp compares two strings + \fI(function)\fP wcscoll compares two wide strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP C documentation for wcscmp - -.SH Category: - - * Todo no example diff --git a/man/std::wcscoll.3 b/man/std::wcscoll.3 index 45a0bfc38..034e37270 100644 --- a/man/std::wcscoll.3 +++ b/man/std::wcscoll.3 @@ -1,4 +1,7 @@ -.TH std::wcscoll 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcscoll 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcscoll \- std::wcscoll + .SH Synopsis Defined in header int wcscoll( const wchar_t* lhs, const wchar_t* rhs ); @@ -30,34 +33,34 @@ .SH Example - + // Run this code - #include #include - + #include + void try_compare(const wchar_t* p1, const wchar_t* p2) { - if(std::wcscoll(p1, p2) < 0) - std::wcout << p1 << " before " << p2 << '\\n'; + if (std::wcscoll(p1, p2) < 0) + std::wcout << p1 << " before " << p2 << '\\n'; else - std::wcout << p2 << " before " << p1 << '\\n'; + std::wcout << p2 << " before " << p1 << '\\n'; } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); std::wcout << "In the American locale: "; try_compare(L"hrnec", L"chrt"); - + std::setlocale(LC_COLLATE, "cs_CZ.utf8"); std::wcout << "In the Czech locale: "; try_compare(L"hrnec", L"chrt"); - + std::setlocale(LC_COLLATE, "en_US.utf8"); std::wcout << "In the American locale: "; try_compare(L"år", L"ängel"); - + std::setlocale(LC_COLLATE, "sv_SE.utf8"); std::wcout << "In the Swedish locale: "; try_compare(L"år", L"ängel"); @@ -73,11 +76,11 @@ .SH See also strcoll compares two strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP do_compare compares two strings using this facet's collation rules - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP transform a wide string so that wcscmp would produce the same result as wcsxfrm wcscoll - \fI(function)\fP + \fI(function)\fP C documentation for wcscoll diff --git a/man/std::wcscpy.3 b/man/std::wcscpy.3 index 16d4a393d..9e0261b75 100644 --- a/man/std::wcscpy.3 +++ b/man/std::wcscpy.3 @@ -1,7 +1,10 @@ -.TH std::wcscpy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcscpy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcscpy \- std::wcscpy + .SH Synopsis Defined in header - wchar_t *wcscpy( wchar_t *dest, const wchar_t *src ); + wchar_t* wcscpy( wchar_t* dest, const wchar_t* src ); Copies the wide string pointed to by src (including the terminating null wide character) to wide character array pointed to by dest. @@ -19,19 +22,39 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + const wchar_t* src = L"犬 means dog"; + // src[0] = L'狗'; // can't modify string literal + auto dst = std::make_unique(std::wcslen(src) + 1); // +1 for the null + std::wcscpy(dst.get(), src); + dst[0] = L'狗'; + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("")); + std::wcout << src << '\\n' << dst.get() << '\\n'; + } + +.SH Output: + + 犬 means dog + 狗 means dog .SH See also wcsncpy copies a certain amount of wide characters from one string to another - \fI(function)\fP + \fI(function)\fP copies a certain amount of wide characters between two non-overlapping wmemcpy arrays - \fI(function)\fP + \fI(function)\fP + strcpy copies one string to another + \fI(function)\fP C documentation for wcscpy - -.SH Category: - - * Todo no example diff --git a/man/std::wcscspn.3 b/man/std::wcscspn.3 index d31154e19..f315395ab 100644 --- a/man/std::wcscspn.3 +++ b/man/std::wcscspn.3 @@ -1,4 +1,7 @@ -.TH std::wcscspn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcscspn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcscspn \- std::wcscspn + .SH Synopsis Defined in header std::size_t wcscspn( const wchar_t* dest, const wchar_t* src ); @@ -16,24 +19,45 @@ .SH Return value The length of the maximum initial segment that contains only characters not found in - the character string pointed to by src + the character string pointed to by src. .SH Example - This section is incomplete - Reason: no example + The output below was obtained using clang (libc++). + + +// Run this code + + #include + #include + #include + + int main() + { + wchar_t dest[] = L"白猫 黑狗 甲虫"; + // └───┐ + const wchar_t* src = L"甲虫,黑狗"; + + const std::size_t len = std::wcscspn(dest, src); + dest[len] = L'\\0'; // terminates the segment to print it out + + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << L"The length of maximum initial segment is " << len << L".\\n"; + std::wcout << L"The segment is \\"" << dest << L"\\".\\n"; + } + +.SH Possible output: + + The length of maximum initial segment is 3. + The segment is "白猫 ". .SH See also returns the length of the maximum initial segment that consists wcsspn of only the wide characters found in another wide string - \fI(function)\fP + \fI(function)\fP finds the first location of any wide character in one wide string, in wcspbrk another wide string - \fI(function)\fP + \fI(function)\fP C documentation for wcscspn - -.SH Category: - - * Todo no example diff --git a/man/std::wcsftime.3 b/man/std::wcsftime.3 index dfa2af39d..bbae5a930 100644 --- a/man/std::wcsftime.3 +++ b/man/std::wcsftime.3 @@ -1,198 +1,184 @@ -.TH std::wcsftime 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsftime 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsftime \- std::wcsftime + .SH Synopsis Defined in header std::size_t wcsftime( wchar_t* str, std::size_t count, const wchar_t* format, - std::tm* time ); + const std::tm* time ); Converts the date and time information from a given calendar time time to a null-terminated wide character string str according to format string format. Up to - count bytes are written. + count wide characters are written. .SH Parameters str - pointer to the first element of the wchar_t array for output count - maximum number of wide characters to write - pointer to a null-terminated wide character string specifying the format of - conversion. - - The format string consists of zero or more conversion specifiers and - ordinary characters (except %). All ordinary characters, including the - terminating null character, are copied to the output string without - modification. Each conversion specification begins with % character, - optionally followed by E or O modifier (ignored if unsupported by the - locale), followed by the character that determines the behavior of the - specifier. The following format specifiers are available: - - Conversion Explanation Used fields - specifier - % writes literal %. The full conversion - specification must be %%. - n writes newline character - \fI(C++11)\fP - t writes horizontal tab character - \fI(C++11)\fP - Year - Y writes year as a 4 digit decimal number tm_year - EY writes year in the alternative representation, - \fI(C++11)\fP e.g.平成23年 (year Heisei 23) instead of 2011 tm_year - 年 (year 2011) in ja_JP locale - y writes last 2 digits of year as a decimal tm_year - number (range [00,99]) - Oy writes last 2 digits of year using the - \fI(C++11)\fP alternative numeric system, e.g. 十一 instead tm_year - of 11 in ja_JP locale - Ey writes year as offset from locale's - \fI(C++11)\fP alternative calendar period %EC tm_year - (locale-dependent) - C writes first 2 digits of year as a decimal tm_year - \fI(C++11)\fP number (range [00,99]) - EC writes name of the base year (period) in the - \fI(C++11)\fP locale's alternative representation, e.g. 平成 tm_year - (Heisei era) in ja_JP - writes ISO 8601 week-based year, i.e. the year - that contains the specified week. - - G In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - writes last 2 digits of ISO 8601 week-based - year, i.e. the year that contains the - specified week (range [00,99]). - - g In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - Month - b writes abbreviated month name, e.g. Oct tm_mon - (locale dependent) - h synonym of b tm_mon - \fI(C++11)\fP - B writes full month name, e.g. October (locale tm_mon - dependent) - m writes month as a decimal number (range tm_mon - [01,12]) - Om writes month using the alternative numeric - \fI(C++11)\fP system, e.g. 十二 instead of 12 in ja_JP tm_mon - locale - Week - writes week of the year as a decimal number tm_year, tm_wday, - U (Sunday is the first day of the week) (range tm_yday - [00,53]) - OU writes week of the year, as by %U, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - writes week of the year as a decimal number tm_year, tm_wday, - W (Monday is the first day of the week) (range tm_yday - [00,53]) - OW writes week of the year, as by %W, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - writes ISO 8601 week of the year (range - [01,53]). - - V In IS0 8601 weeks begin with Monday and the tm_year, tm_wday, - \fI(C++11)\fP first week of the year must satisfy the tm_yday - following requirements: - - * Includes January 4 - * Includes first Thursday of the year - format - OV writes week of the year, as by %V, using the tm_year, tm_wday, - \fI(C++11)\fP alternative numeric system, e.g. 五十二 tm_yday - instead of 52 in ja_JP locale - Day of the year/month - j writes day of the year as a decimal number tm_yday - (range [001,366]) - d writes day of the month as a decimal number tm_mday - (range [01,31]) - writes zero-based day of the month using the - Od alternative numeric system, e.g 二十七 instead - \fI(C++11)\fP of 23 in ja_JP locale tm_mday - - Single character is preceded by a space. - writes day of the month as a decimal number - e (range [1,31]). tm_mday - \fI(C++11)\fP - Single digit is preceded by a space. - writes one-based day of the month using the - Oe alternative numeric system, e.g. 二十七 - \fI(C++11)\fP instead of 27 in ja_JP locale tm_mday - - Single character is preceded by a space. - Day of the week - a writes abbreviated weekday name, e.g. Fri tm_wday - (locale dependent) - A writes full weekday name, e.g. Friday (locale tm_wday - dependent) - w writes weekday as a decimal number, where tm_wday - Sunday is 0 (range [0-6]) - Ow writes weekday, where Sunday is 0, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead of tm_wday - 2 in ja_JP locale - u writes weekday as a decimal number, where tm_wday - \fI(C++11)\fP Monday is 1 (ISO 8601 format) (range [1-7]) - Ou writes weekday, where Monday is 1, using the - \fI(C++11)\fP alternative numeric system, e.g. 二 instead of tm_wday - 2 in ja_JP locale - Hour, minute, second - H writes hour as a decimal number, 24 hour clock tm_hour - (range [00-23]) - OH writes hour from 24-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 十八 instead tm_hour - of 18 in ja_JP locale - I writes hour as a decimal number, 12 hour clock tm_hour - (range [01,12]) - OI writes hour from 12-hour clock using the - \fI(C++11)\fP alternative numeric system, e.g. 六 instead of tm_hour - 06 in ja_JP locale - M writes minute as a decimal number (range tm_min - [00,59]) - OM writes minute using the alternative numeric - \fI(C++11)\fP system, e.g. 二十五 instead of 25 in ja_JP tm_min - locale - S writes second as a decimal number (range tm_sec - [00,60]) - OS writes second using the alternative numeric - \fI(C++11)\fP system, e.g. 二十四 instead of 24 in ja_JP tm_sec - locale + format - pointer to a null-terminated wide character string specifying the format of + conversion + time - pointer to the date and time information to be converted + + Format string + + The format string consists of zero or more conversion specifiers and ordinary + characters (except %). All ordinary characters, including the terminating null + character, are copied to the output string without modification. Each conversion + specification begins with % character, optionally followed by E or O modifier + (ignored if unsupported by the locale), followed by the character that determines + the behavior of the specifier. The following format specifiers are available: + + Conversion Explanation Used fields + specifier + % writes literal %. The full conversion specification + must be %%. + n writes newline character + \fI(C++11)\fP + t writes horizontal tab character + \fI(C++11)\fP + Year + Y writes year as a decimal number, e.g. 2017 tm_year + EY writes year in the alternative representation, e.g.平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) tm_year + in ja_JP locale + y writes last 2 digits of year as a decimal number (range tm_year + [00,99]) + Oy writes last 2 digits of year using the alternative tm_year + \fI(C++11)\fP numeric system, e.g. 十一 instead of 11 in ja_JP locale + Ey writes year as offset from locale's alternative tm_year + \fI(C++11)\fP calendar period %EC (locale-dependent) + C writes first 2 digits of year as a decimal number tm_year + \fI(C++11)\fP (range [00,99]) + EC writes name of the base year (period) in the locale's + \fI(C++11)\fP alternative representation, e.g. 平成 (Heisei era) in tm_year + ja_JP + writes ISO 8601 week-based year, i.e. the year that + contains the specified week. + + G In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + writes last 2 digits of ISO 8601 week-based year, i.e. + the year that contains the specified week (range + [00,99]). + g tm_year, tm_wday, + \fI(C++11)\fP In ISO 8601 weeks begin with Monday and the first week tm_yday + of the year must satisfy the following requirements: + + * Includes January 4 + * Includes first Thursday of the year + Month + b writes abbreviated month name, e.g. Oct (locale tm_mon + dependent) + h synonym of b tm_mon + \fI(C++11)\fP + B writes full month name, e.g. October (locale dependent) tm_mon + m writes month as a decimal number (range [01,12]) tm_mon + Om writes month using the alternative numeric system, e.g. tm_mon + \fI(C++11)\fP 十二 instead of 12 in ja_JP locale + Week + U writes week of the year as a decimal number (Sunday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OU writes week of the year, as by %U, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + W writes week of the year as a decimal number (Monday is tm_year, tm_wday, + the first day of the week) (range [00,53]) tm_yday + OW writes week of the year, as by %W, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + writes ISO 8601 week of the year (range [01,53]). + + V In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday, + \fI(C++11)\fP of the year must satisfy the following requirements: tm_yday + + * Includes January 4 + * Includes first Thursday of the year + OV writes week of the year, as by %V, using the tm_year, tm_wday, + \fI(C++11)\fP alternative numeric system, e.g. 五十二 instead of 52 tm_yday + in ja_JP locale + Day of the year/month + j writes day of the year as a decimal number (range tm_yday + [001,366]) + d writes day of the month as a decimal number (range tm_mday + [01,31]) + writes zero-based day of the month using the + Od alternative numeric system, e.g. 二十七 instead of 27 + \fI(C++11)\fP in ja_JP locale tm_mday + + Single character is preceded by a space. + writes day of the month as a decimal number (range + e [1,31]). tm_mday + \fI(C++11)\fP + Single digit is preceded by a space. + writes one-based day of the month using the alternative + Oe numeric system, e.g. 二十七 instead of 27 in ja_JP + \fI(C++11)\fP locale tm_mday + + Single character is preceded by a space. + Day of the week + a writes abbreviated weekday name, e.g. Fri (locale tm_wday + dependent) + A writes full weekday name, e.g. Friday (locale tm_wday + dependent) + w writes weekday as a decimal number, where Sunday is 0 tm_wday + (range [0-6]) + Ow writes weekday, where Sunday is 0, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + u writes weekday as a decimal number, where Monday is 1 tm_wday + \fI(C++11)\fP (ISO 8601 format) (range [1-7]) + Ou writes weekday, where Monday is 1, using the + \fI(C++11)\fP alternative numeric system, e.g. 二 instead of 2 in tm_wday + ja_JP locale + Hour, minute, second + H writes hour as a decimal number, 24 hour clock (range tm_hour + [00-23]) + OH writes hour from 24-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 十八 instead of 18 in ja_JP locale + I writes hour as a decimal number, 12 hour clock (range tm_hour + [01,12]) + OI writes hour from 12-hour clock using the alternative tm_hour + \fI(C++11)\fP numeric system, e.g. 六 instead of 06 in ja_JP locale + M writes minute as a decimal number (range [00,59]) tm_min + OM writes minute using the alternative numeric system, tm_min + \fI(C++11)\fP e.g. 二十五 instead of 25 in ja_JP locale + S writes second as a decimal number (range [00,60]) tm_sec + OS writes second using the alternative numeric system, tm_sec + \fI(C++11)\fP e.g. 二十四 instead of 24 in ja_JP locale .SH Other - c writes standard date and time string, e.g. Sun all - Oct 17 04:41:13 2010 (locale dependent) - Ec writes alternative date and time string, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of all - 2011年 (year 2011) in ja_JP locale - x writes localized date representation (locale all - dependent) - Ex writes alternative date representation, e.g. - \fI(C++11)\fP using 平成23年 (year Heisei 23) instead of all - 2011年 (year 2011) in ja_JP locale - X writes localized time representation (locale all - dependent) - EX writes alternative time representation (locale all - \fI(C++11)\fP dependent) - D equivalent to "%m/%d/%y" tm_mon, tm_mday, - \fI(C++11)\fP tm_year - F equivalent to "%Y-%m-%d" (the ISO 8601 date tm_mon, tm_mday, - \fI(C++11)\fP format) tm_year - r writes localized 12-hour clock time (locale tm_hour, tm_min, - \fI(C++11)\fP dependent) tm_sec - R equivalent to "%H:%M" tm_hour, tm_min - \fI(C++11)\fP - T equivalent to "%H:%M:%S" (the ISO 8601 time tm_hour, tm_min, - \fI(C++11)\fP format) tm_sec - p writes localized a.m. or p.m. (locale tm_hour - dependent) - z writes offset from UTC in the ISO 8601 format - \fI(C++11)\fP (e.g. -0430), or no characters if the time tm_isdst - zone information is not available - writes time zone name or abbreviation, or no - Z characters if the time zone information is not tm_isdst - available (locale dependent) + c writes standard date and time string, e.g. Sun Oct 17 all + 04:41:13 2010 (locale dependent) + Ec writes alternative date and time string, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + x writes localized date representation (locale dependent) all + Ex writes alternative date representation, e.g. using 平 + \fI(C++11)\fP 成23年 (year Heisei 23) instead of 2011年 (year 2011) all + in ja_JP locale + X writes localized time representation, e.g. 18:40:20 or all + 6:40:20 PM (locale dependent) + EX writes alternative time representation (locale all + \fI(C++11)\fP dependent) + D equivalent to "%m/%d/%y" tm_mon, tm_mday, + \fI(C++11)\fP tm_year + F equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday, + \fI(C++11)\fP tm_year + r writes localized 12-hour clock time (locale dependent) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + R equivalent to "%H:%M" tm_hour, tm_min + \fI(C++11)\fP + T equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min, + \fI(C++11)\fP tm_sec + p writes localized a.m. or p.m. (locale dependent) tm_hour + z writes offset from UTC in the ISO 8601 format (e.g. + \fI(C++11)\fP -0430), or no characters if the time zone information tm_isdst + is not available + writes locale-dependent time zone name or abbreviation, + Z or no characters if the time zone information is not tm_isdst + available .SH Return value @@ -202,33 +188,32 @@ .SH Example - + // Run this code #include #include #include #include - + int main() { std::locale::global(std::locale("ja_JP.utf8")); - std::time_t t = std::time(NULL); + std::time_t t = std::time(nullptr); wchar_t wstr[100]; - if(std::wcsftime(wstr, 100, L"%A %c", std::localtime(&t))) { + if (std::wcsftime(wstr, 100, L"%A %c", std::localtime(&t))) std::wcout << wstr << '\\n'; - } } -.SH Output: +.SH Possible output: 火曜日 2011年12月27日 17時43分13秒 .SH See also - strftime converts a tm object to custom textual representation - \fI(function)\fP + strftime converts a std::tm object to custom textual representation + \fI(function)\fP put_time formats and outputs a date/time value according to the specified format - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP C documentation for wcsftime diff --git a/man/std::wcslen.3 b/man/std::wcslen.3 index dc39bdfe3..0cff0dd2b 100644 --- a/man/std::wcslen.3 +++ b/man/std::wcslen.3 @@ -1,11 +1,17 @@ -.TH std::wcslen 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcslen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcslen \- std::wcslen + .SH Synopsis Defined in header - std::size_t wcslen( const wchar_t *str ); + std::size_t wcslen( const wchar_t* str ); Returns the length of a wide string, that is the number of non-null wide characters that precede the terminating null wide character. + The behavior is undefined if there is no null character in the wide character array + pointed to by str. + .SH Parameters str - pointer to the null-terminated wide string to be examined @@ -14,24 +20,44 @@ The length of the null-terminated wide string str. +.SH Possible implementation + + std::size_t wcslen(const wchar_t* start) + { + // NB: start is not checked for nullptr! + const wchar_t* end = start; + while (*end != L'\\0') + ++end; + return end - start; + } + .SH Example - + // Run this code - #include + #include #include + #include + int main() { - const wchar_t* str = L"Hello, world!"; - std::wcout << "The length of L\\"" << str << "\\" is " << std::wcslen(str) << '\\n'; + const wchar_t* str = L"爆ぜろリアル！弾けろシナプス！パニッシュメントディス、ワールド！"; + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << "The length of \\"" << str << "\\" is " << std::wcslen(str) << '\\n'; } .SH Output: - The length of L"Hello, world!" is 13 + The length of "爆ぜろリアル！弾けろシナプス！パニッシュメントディス、ワールド！" is 32 .SH See also + strlen returns the length of a given string + \fI(function)\fP + mblen returns the number of bytes in the next multibyte character + \fI(function)\fP C documentation for wcslen diff --git a/man/std::wcsncat.3 b/man/std::wcsncat.3 index 7a9cec8a7..4775596f7 100644 --- a/man/std::wcsncat.3 +++ b/man/std::wcsncat.3 @@ -1,11 +1,21 @@ -.TH std::wcsncat 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsncat 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsncat \- std::wcsncat + .SH Synopsis Defined in header - wchar_t *wcsncat( wchar_t *dest, const wchar_t *src, std::size_t count ); + wchar_t* wcsncat( wchar_t* dest, const wchar_t* src, std::size_t count ); + + Appends at most count wide characters from the wide string pointed to by src to the + end of the character string pointed to by dest, stopping if the null terminator is + copied. The wide character src[0] replaces the null terminator at the end of dest. + The null terminator is always appended in the end (so the maximum number of wide + characters the function may write is count + 1). + + The behavior is undefined if the destination array is not large enough for the + contents of both src and dest and the terminating null wide character. - Appends a wide string pointed to by src to a wide string pointed to by dest. At most - count wide characters are copied. The resulting wide string is null-terminated. If - the strings overlap, the behavior is undefined. + The behavior is undefined if the strings overlap. .SH Parameters @@ -19,18 +29,35 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main(void) + { + wchar_t str[50] = L"Земля, прощай."; + std::wcsncat(str, L" ", 1); + std::wcsncat(str, L"В добрый путь.", 8); // only append the first 8 wide chars + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << str << '\\n'; + } + +.SH Possible output: + + Земля, прощай. В добрый .SH See also - wcscat appends a copy of one wide string to another - \fI(function)\fP - wcscpy copies one wide string to another - \fI(function)\fP + wcscat appends a copy of one wide string to another + \fI(function)\fP + strncat concatenates a certain amount of characters of two strings + \fI(function)\fP + wcscpy copies one wide string to another + \fI(function)\fP C documentation for wcsncat - -.SH Category: - - * Todo no example diff --git a/man/std::wcsncmp.3 b/man/std::wcsncmp.3 index 222bd63dc..4b8738910 100644 --- a/man/std::wcsncmp.3 +++ b/man/std::wcsncmp.3 @@ -1,11 +1,19 @@ -.TH std::wcsncmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsncmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsncmp \- std::wcsncmp + .SH Synopsis Defined in header - int wcsncmp( const wchar_t* lhs, const wchar_t* rhs, size_t count ); + int wcsncmp( const wchar_t* lhs, const wchar_t* rhs, std::size_t count ); Compares at most count wide characters of two null-terminated wide strings. The comparison is done lexicographically. + The sign of the result is the sign of the difference between the values of the first + pair of wide characters that differ in the strings being compared. + + The behavior is undefined if lhs or rhs are not pointers to null-terminated strings. + .SH Parameters lhs, rhs - pointers to the null-terminated wide strings to compare @@ -13,28 +21,63 @@ .SH Return value - Negative value if lhs is less than rhs. + Negative value if lhs appears before rhs in lexicographical order. - 0 if lhs is equal to rhs. + Zero if lhs and rhs compare equal. - Positive value if lhs is greater than rhs. + Positive value if lhs appears after rhs in lexicographical order. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + void demo(const wchar_t* lhs, const wchar_t* rhs, int sz) + { + int rc = std::wcsncmp(lhs, rhs, sz); + if (rc == 0) + std::wcout << "First " << sz << " characters of [" + << lhs << "] equal [" << rhs << "]\\n"; + else if (rc < 0) + std::wcout << "First " << sz << " characters of [" + << lhs << "] precede [" << rhs << "]\\n"; + else if (rc > 0) + std::wcout << "First " << sz << " characters of [" + << lhs << "] follow [" << rhs << "]\\n"; + } + + int main() + { + const wchar_t str1[] = L"안녕하세요"; + const wchar_t str2[] = L"안녕히 가십시오"; + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + demo(str1, str2, 5); + demo(str2, str1, 8); + demo(str1, str2, 2); + } + +.SH Output: + + First 5 characters of [안녕하세요] precede [안녕히 가십시오] + First 8 characters of [안녕히 가십시오] follow [안녕하세요] + First 2 characters of [안녕하세요] equal [안녕히 가십시오] .SH See also + strncmp compares a certain number of characters from two strings + \fI(function)\fP wcscmp compares two wide strings - \fI(function)\fP + \fI(function)\fP wmemcmp compares a certain amount of wide characters from two arrays - \fI(function)\fP + \fI(function)\fP wcscoll compares two wide strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP C documentation for wcsncmp - -.SH Category: - - * Todo no example diff --git a/man/std::wcsncpy.3 b/man/std::wcsncpy.3 index e52638c2a..cc310707d 100644 --- a/man/std::wcsncpy.3 +++ b/man/std::wcsncpy.3 @@ -1,7 +1,10 @@ -.TH std::wcsncpy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsncpy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsncpy \- std::wcsncpy + .SH Synopsis Defined in header - wchar_t *wcsncpy( wchar_t *dest, const wchar_t *src, std::size_t count ); + wchar_t* wcsncpy( wchar_t* dest, const wchar_t* src, std::size_t count ); Copies at most count characters of the wide string pointed to by src (including the terminating null wide character) to wide character array pointed to by dest. @@ -31,22 +34,23 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { - wchar_t src[] = L"hi"; - wchar_t dest[6] = {L'a', L'b', L'c', L'd', L'e', L'f'};; - - std::wcsncpy(dest, src, 5); // this will copy hi and repeat \\0 three times - + const wchar_t src[] = L"hi"; + wchar_t dest[6] = {L'a', L'b', L'c', L'd', L'e', L'f'}; + + std::wcsncpy(dest, src, 5); // this will copy 'hi' and repeat \\0 three times + std::wcout << "The contents of dest are: "; - for(wchar_t c : dest) { - if(c) + for (const wchar_t c : dest) + { + if (c) std::wcout << c << ' '; else std::wcout << "\\\\0" << ' '; @@ -61,9 +65,11 @@ .SH See also wcscpy copies one wide string to another - \fI(function)\fP + \fI(function)\fP copies a certain amount of wide characters between two non-overlapping wmemcpy arrays - \fI(function)\fP + \fI(function)\fP + strncpy copies a certain amount of characters from one string to another + \fI(function)\fP C documentation for wcsncpy diff --git a/man/std::wcspbrk.3 b/man/std::wcspbrk.3 index 5900d1f4c..0086b9c63 100644 --- a/man/std::wcspbrk.3 +++ b/man/std::wcspbrk.3 @@ -1,11 +1,14 @@ -.TH std::wcspbrk 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcspbrk 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcspbrk \- std::wcspbrk + .SH Synopsis Defined in header - const wchar_t* wcspbrk( const wchar_t* dest, const wchar_t* str ); - wchar_t* wcspbrk( wchar_t* dest, const wchar_t* str ); + const wchar_t* wcspbrk( const wchar_t* dest, const wchar_t* src ); + wchar_t* wcspbrk( wchar_t* dest, const wchar_t* src ); Finds the first character in wide string pointed to by dest, that is also in wide - string pointed to by str. + string pointed to by src. .SH Parameters @@ -15,24 +18,58 @@ .SH Return value - Pointer to the first character in dest, that is also in str, or NULL if no such - character exists. + Pointer to the first character in dest, that is also in src, or a null pointer if no + such character exists. + +.SH Notes + + The name stands for "wide character string pointer break", because it returns a + pointer to the first of the separator ("break") characters. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + const wchar_t* str = L"Hello world, friend of mine!"; + const wchar_t* sep = L" ,!"; + + unsigned int cnt = 0; + do + { + str = std::wcspbrk(str, sep); // find separator + std::wcout << std::quoted(str) << L'\\n'; + if (str) + str += std::wcsspn(str, sep); // skip separator + ++cnt; // increment word count + } while (str && *str); + + std::wcout << L"There are " << cnt << L" words\\n"; + } + +.SH Output: + + " world, friend of mine!" + ", friend of mine!" + " of mine!" + " mine!" + "!" + There are 5 words .SH See also returns the length of the maximum initial segment that consists wcscspn of only the wide not found in another wide string - \fI(function)\fP + \fI(function)\fP wcschr finds the first occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP + strpbrk finds the first location of any character from a set of separators + \fI(function)\fP C documentation for wcspbrk - -.SH Category: - - * Todo no example diff --git a/man/std::wcsrchr.3 b/man/std::wcsrchr.3 index 2a78373ad..bd08ada6f 100644 --- a/man/std::wcsrchr.3 +++ b/man/std::wcsrchr.3 @@ -1,4 +1,7 @@ -.TH std::wcsrchr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsrchr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsrchr \- std::wcsrchr + .SH Synopsis Defined in header const wchar_t* wcsrchr( const wchar_t* str, wchar_t ch ); @@ -14,24 +17,49 @@ .SH Return value - Pointer to the found character in str, or NULL if no such character is found. + Pointer to the found character in str, or a null pointer if no such character is + found. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + const wchar_t arr[] = L"白猫 黒猫 кошки"; + const wchar_t* cat = std::wcsrchr(arr, L'猫'); + const wchar_t* dog = std::wcsrchr(arr, L'犬'); + + std::cout.imbue(std::locale("en_US.utf8")); + + if (cat) + std::cout << "The character 猫 found at position " << cat - arr << '\\n'; + else + std::cout << "The character 猫 not found\\n"; + + if (dog) + std::cout << "The character 犬 found at position " << dog - arr << '\\n'; + else + std::cout << "The character 犬 not found\\n"; + } + +.SH Output: + + The character 猫 found at position 4 + The character 犬 not found .SH See also wcschr finds the first occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP strrchr finds the last occurrence of a character - \fI(function)\fP + \fI(function)\fP rfind find the last occurrence of a substring - \fI(public member function of std::basic_string)\fP + \fI(public member function of std::basic_string)\fP C documentation for wcsrchr - -.SH Category: - - * Todo no example diff --git a/man/std::wcsrtombs.3 b/man/std::wcsrtombs.3 index 650fba82d..a2d9fb44c 100644 --- a/man/std::wcsrtombs.3 +++ b/man/std::wcsrtombs.3 @@ -1,4 +1,7 @@ -.TH std::wcsrtombs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsrtombs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsrtombs \- std::wcsrtombs + .SH Synopsis Defined in header std::size_t wcsrtombs( char* dst, @@ -17,13 +20,13 @@ Each character is converted as if by a call to std::wcrtomb. The conversion stops if: - * The null character was converted and stored. src is set to NULL and *ps - represents the initial shift state. + * The null character was converted and stored. src is set to a null pointer and + *ps represents the initial shift state. * A wchar_t was found that does not correspond to a valid character in the current C locale. src is set to point at the first unconverted wide character. - * the next multibyte character to be stored would exceed len. src is set to point - at the first unconverted wide character. This condition is not checked if - dst==NULL. + * The next multibyte character to be stored would exceed len. src is set to point + at the first unconverted wide character. This condition is not checked if dst is + a null pointer. .SH Parameters @@ -37,8 +40,8 @@ On success, returns the number of bytes (including any shift sequences, but excluding the terminating '\\0') written to the character array whose first element - is pointed to by dst. If dst==NULL, returns the number of bytes that would have been - written. + is pointed to by dst. If dst is a null pointer, returns the number of bytes that + would have been written (again, excluding the terminating null character '\\0'). On conversion error (if invalid wide character was encountered), returns static_cast(-1), stores EILSEQ in errno, and leaves *ps in unspecified @@ -46,25 +49,25 @@ .SH Example - + // Run this code - #include - #include #include - #include #include - + #include + #include + #include + void print_wide(const wchar_t* wstr) { std::mbstate_t state = std::mbstate_t(); - int len = 1 + std::wcsrtombs(NULL, &wstr, 0, &state); + std::size_t len = 1 + std::wcsrtombs(nullptr, &wstr, 0, &state); std::vector mbstr(len); std::wcsrtombs(&mbstr[0], &wstr, mbstr.size(), &state); std::cout << "multibyte string: " << &mbstr[0] << '\\n' << "Length, including '\\\\0': " << mbstr.size() << '\\n'; } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); @@ -81,10 +84,11 @@ .SH See also wcrtomb converts a wide character to its multibyte representation, given state - \fI(function)\fP + \fI(function)\fP mbsrtowcs converts a narrow multibyte character string to wide string, given state - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for wcsrtombs diff --git a/man/std::wcsspn.3 b/man/std::wcsspn.3 index e10280eef..418fc74bf 100644 --- a/man/std::wcsspn.3 +++ b/man/std::wcsspn.3 @@ -1,4 +1,7 @@ -.TH std::wcsspn 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsspn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsspn \- std::wcsspn + .SH Synopsis Defined in header size_t wcsspn( const wchar_t* dest, const wchar_t* src ); @@ -15,24 +18,41 @@ .SH Return value The length of the maximum initial segment that contains only characters from wide - string pointed to by src + string pointed to by src. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + wchar_t dest[] = L"白猫 黑狗 甲虫"; + const wchar_t src[] = L" 狗猫 白黑 "; + const std::size_t len = std::wcsspn(dest, src); + dest[len] = L'\\0'; // terminates the segment to print it out + + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << L"The length of maximum initial segment is " << len << L".\\n"; + std::wcout << L"The segment is \\"" << dest << L"\\".\\n"; + } + +.SH Possible output: + + The length of maximum initial segment is 6. + The segment is "白猫 黑狗 ". .SH See also returns the length of the maximum initial segment that consists wcscspn of only the wide not found in another wide string - \fI(function)\fP + \fI(function)\fP finds the first location of any wide character in one wide string, in wcspbrk another wide string - \fI(function)\fP + \fI(function)\fP C documentation for wcsspn - -.SH Category: - - * Todo no example diff --git a/man/std::wcsstr.3 b/man/std::wcsstr.3 index c366a44a1..43b697c86 100644 --- a/man/std::wcsstr.3 +++ b/man/std::wcsstr.3 @@ -1,4 +1,7 @@ -.TH std::wcsstr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsstr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsstr \- std::wcsstr + .SH Synopsis Defined in header const wchar_t* wcsstr( const wchar_t* dest, const wchar_t* src ); @@ -14,27 +17,49 @@ .SH Return value - Pointer to the first character of the found substring in dest, or NULL if no such - substring is found. If src points to an empty string, dest is returned. + Pointer to the first character of the found substring in dest, or a null pointer if + no such substring is found. If src points to an empty string, dest is returned. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + + int main() + { + wchar_t const* origin = L"アルファ, ベータ, ガンマ, アルファ, ベータ, ガンマ."; + wchar_t const* target = L"ベータ"; + wchar_t const* result = origin; + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout << L"Substring to find: \\"" << target << L"\\"\\n" + << L"String to search: \\"" << origin << L"\\"\\n\\n"; + + for (; (result = std::wcsstr(result, target)) != nullptr; ++result) + std::wcout << L"Found: \\"" << result << L"\\"\\n"; + } + +.SH Possible output: + + Substring to find: "ベータ" + String to search: "アルファ, ベータ, ガンマ, アルファ, ベータ, ガンマ." + + Found: "ベータ, ガンマ, アルファ, ベータ, ガンマ." + Found: "ベータ, ガンマ." .SH See also - find find characters in the string - \fI(public member function of std::basic_string)\fP + find finds the first occurrence of the given substring + \fI(public member function of std::basic_string)\fP strstr finds the first occurrence of a substring of characters - \fI(function)\fP + \fI(function)\fP wcschr finds the first occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP wcsrchr finds the last occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP C documentation for wcsstr - -.SH Category: - - * Todo no example diff --git a/man/std::wcstof,std::wcstod,std::wcstold.3 b/man/std::wcstof,std::wcstod,std::wcstold.3 index 03f567f9c..7199dbe90 100644 --- a/man/std::wcstof,std::wcstod,std::wcstold.3 +++ b/man/std::wcstof,std::wcstod,std::wcstold.3 @@ -1,4 +1,7 @@ -.TH std::wcstof,std::wcstod,std::wcstold 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcstof,std::wcstod,std::wcstold 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcstof,std::wcstod,std::wcstold \- std::wcstof,std::wcstod,std::wcstold + .SH Synopsis Defined in header float wcstof( const wchar_t* str, wchar_t** str_end ); \fI(since C++11)\fP @@ -7,46 +10,49 @@ Interprets a floating point value in a wide string pointed to by str. - Function discards any whitespace characters (as determined by std::isspace()) until + Function discards any whitespace characters (as determined by std::iswspace) until first non-whitespace character is found. Then it takes as many characters as - possible to form a valid floating point representation and converts them to floating - point value. The valid floating point value can be one of the following: + possible to form a valid floating-point representation and converts them to a + floating-point value. The valid floating-point value can be one of the following: - * decimal floating point expression. It consists of the following parts: + * decimal floating-point expression. It consists of the following parts: * (optional) plus or minus sign - * nonempty sequence of decimal digits optionally containing a decimal point - character (defines significand) + * nonempty sequence of decimal digits optionally containing decimal-point + character (as determined by the current C locale) (defines significand) * (optional) e or E followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) + sequence of decimal digits (defines exponent to base 10) - * binary floating point expression. It consists of the following parts: + * hexadecimal floating-point expression. It consists of the + following parts: * (optional) plus or minus sign * 0x or 0X - * nonempty sequence of hexadecimal digits optionally containing a decimal point - character (defines significand) - * (optional) p or P followed with optional minus or plus sign and nonempty - sequence of decimal digits (defines exponent) - + * nonempty sequence of hexadecimal digits optionally containing a + decimal-point character (as determined by the current C locale) + (defines significand) + * (optional) p or P followed with optional minus or plus sign and + nonempty sequence of decimal digits (defines exponent to base 2) \fI(since C++11)\fP * infinity expression. It consists of the following parts: * (optional) plus or minus sign * INF or INFINITY ignoring case - * not-a-number expression. It consists of the following parts: * (optional) plus or minus sign - * NAN or NAN(char_sequence) ignoring case of the NAN part. char_sequence can only - contain alphanumeric characters. The result is a quiet NaN floating point value. + * NAN or NAN(char_sequence) ignoring case of the NAN part. + char_sequence can only contain digits, Latin letters, and + underscores. The result is a quiet NaN floating-point value. + + * any other expression that may be accepted by the currently installed C locale The functions sets the pointer pointed to by str_end to point to the wide character - past the last character interpreted. If str_end is NULL, it is ignored. + past the last character interpreted. If str_end is a null pointer, it is ignored. .SH Parameters str - pointer to the null-terminated wide string to be interpreted - str_end - pointer to a pointer to a wide character. + str_end - pointer to a pointer to a wide character .SH Return value @@ -57,14 +63,56 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + const wchar_t* p = L"111.11 -2.22 0X1.BC70A3D70A3D7P+6 -Inf 1.18973e+4932zzz"; + wchar_t* end; + std::wcout << "Parsing L\\"" << p << "\\":\\n"; + for (double f = std::wcstod(p, &end); p != end; f = std::wcstod(p, &end)) + { + std::wcout << " '" << std::wstring(p, end-p) << "' -> "; + p = end; + if (errno == ERANGE) + { + std::wcout << "range error, got "; + errno = 0; + } + std::wcout << f << '\\n'; + } + + if (std::setlocale(LC_NUMERIC, "de_DE.utf8")) + { + std::wcout << L"With de_DE.utf8 locale:\\n"; + std::wcout << L" '123.45' -> " << std::wcstod(L"123.45", 0) << L'\\n'; + std::wcout << L" '123,45' -> " << std::wcstod(L"123,45", 0) << L'\\n'; + } + } + +.SH Output: + + Parsing L"111.11 -2.22 0X1.BC70A3D70A3D7P+6 -Inf 1.18973e+4932zzz": + '111.11' -> 111.11 + ' -2.22' -> -2.22 + ' 0X1.BC70A3D70A3D7P+6' -> 111.11 + ' -Inf' -> -inf + ' 1.18973e+4932' -> range error, got inf + With de_DE.utf8 locale: + '123.45' -> 123 + '123,45' -> 123.45 .SH See also + strtof converts a byte string to a floating-point value + strtod \fI(function)\fP + strtold C documentation for wcstof - -.SH Category: - - * Todo no example diff --git a/man/std::wcstoimax,std::wcstoumax.3 b/man/std::wcstoimax,std::wcstoumax.3 index 5b5ccc966..fd28970ad 100644 --- a/man/std::wcstoimax,std::wcstoumax.3 +++ b/man/std::wcstoimax,std::wcstoumax.3 @@ -1,4 +1,7 @@ -.TH std::wcstoimax,std::wcstoumax 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcstoimax,std::wcstoumax 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcstoimax,std::wcstoumax \- std::wcstoimax,std::wcstoumax + .SH Synopsis Defined in header std::intmax_t wcstoimax( const wchar_t* nptr, wchar_t** endptr, int \fI(since C++11)\fP @@ -8,34 +11,41 @@ Interprets an unsigned integer value in a wide string pointed to by nptr. - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as + Discards any whitespace characters (as identified by calling std::iswspace) until + the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts: + * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or 0) * (optional) prefix (0x or 0X) indicating hexadecimal base (applies only when the base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type, which + applies unsigned integer wraparound rules. + The functions sets the pointer pointed to by endptr to point to the wide character - past the last character interpreted. If endptr is NULL, it is ignored. + past the last character interpreted. If endptr is a null pointer, it is ignored. .SH Parameters nptr - pointer to the null-terminated wide string to be interpreted - endptr - pointer to a pointer to a wide character. + endptr - pointer to a pointer to a wide character base - base of the interpreted integer value .SH Return value @@ -47,24 +57,24 @@ .SH Example - + // Run this code + #include #include #include - #include - + int main() { std::wstring str = L"helloworld"; std::intmax_t val = std::wcstoimax(str.c_str(), nullptr, 36); std::wcout << str << " in base 36 is " << val << " in base 10\\n"; - + wchar_t* nptr; val = std::wcstoimax(str.c_str(), &nptr, 30); - if(nptr != &str[0] + str.size()) + if (nptr != &str[0] + str.size()) std::wcout << str << " in base 30 is invalid." - << " The first invalid digit is " << *nptr << '\\n'; + << " The first invalid digit is " << *nptr << '\\n'; } .SH Output: @@ -76,12 +86,12 @@ strtoimax strtoumax converts a byte string to std::intmax_t or std::uintmax_t - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP wcstol converts a wide string to an integer value - wcstoll \fI(function)\fP + wcstoll \fI(function)\fP wcstoul converts a wide string to an unsigned integer value - wcstoull \fI(function)\fP + wcstoull \fI(function)\fP C documentation for wcstoimax, wcstoumax diff --git a/man/std::wcstok.3 b/man/std::wcstok.3 index 546c35b19..00c463e81 100644 --- a/man/std::wcstok.3 +++ b/man/std::wcstok.3 @@ -1,47 +1,95 @@ -.TH std::wcstok 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcstok 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcstok \- std::wcstok + .SH Synopsis Defined in header - wchar_t* wcstok( wchar_t* str, const wchar_t* delim ); + wchar_t* wcstok( wchar_t* str, const wchar_t* delim, wchar_t ** ptr); Finds the next token in a null-terminated wide string pointed to by str. The separator characters are identified by null-terminated wide string pointed to by delim. - If str != NULL, the function searches for the first wide character which is not - separator. This character is the beginning of the token. Then the function searches - for the first separator character. This character is the end of the token. Function - terminates and returns NULL if end of str is encountered before end of the token is - found. Otherwise, a pointer to end of the token is saved in a static location for - subsequent invocations. This character is then replaced by a NULL-character and the - function returns a pointer to the beginning of the token. + This function is designed to be called multiples times to obtain successive tokens + from the same string. + + * If str != nullptr, the call is treated as the first call to std::wcstok for this + particular wide string. The function searches for the first wide character which + is not contained in delim. + + * If no such wide character was found, there are no tokens in str at all, and the + function returns a null pointer. + * If such wide character was found, it is the beginning of the token. The function + then searches from that point on for the first wide character that is contained + in delim. - If str == NULL, the function continues from where it left in previous invocation. - The behavior is the same as if the previously stored pointer is passed as str. + * If no such wide character was found, str has only one token, and future calls to + std::wcstok will return a null pointer. + * If such wide character was found, it is replaced by the null wide character + L'\\0' and the parser state (typically a pointer to the following wide character) + is stored in the user-provided location *ptr. + * The function then returns the pointer to the beginning of the token. + * If str == nullptr, the call is treated as a subsequent calls to std::wcstok: the + function continues from where it left in previous invocation with the same *ptr. + The behavior is the same as if the pointer to the wide character that follows + the last detected token is passed as str. .SH Parameters str - pointer to the null-terminated wide string to tokenize delim - pointer to the null-terminated wide string identifying delimiters + ptr - pointer to an object of type wchar_t*, which is used by wcstok to store its + internal state .SH Return value - Pointer to the beginning of a token if the end of examined string has not been - encountered. Otherwise returns NULL> + Pointer to the beginning of the next token or null pointer if there are no more + tokens. .SH Note - The function is not thread safe. + This function is destructive: it writes the L'\\0' characters in the elements of the + string str. In particular, a wide string literal cannot be used as the first + argument of std::wcstok. + + Unlike std::strtok, this function does not update static storage: it stores the + parser state in the user-provided location. + + Unlike most other tokenizers, the delimiters in std::wcstok can be different for + each subsequent token, and can even depend on the contents of the previous tokens. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + int main() + { + wchar_t input[100] = L"A bird came down the walk"; + wchar_t* buffer; + wchar_t* token = std::wcstok(input, L" ", &buffer); + while (token) + { + std::wcout << token << '\\n'; + token = std::wcstok(nullptr, L" ", &buffer); + } + } + +.SH Output: + + A + bird + came + down + the + walk .SH See also + strtok finds the next token in a byte string + \fI(function)\fP C documentation for wcstok - -.SH Category: - - * Todo no example diff --git a/man/std::wcstol,std::wcstoll.3 b/man/std::wcstol,std::wcstoll.3 index 1f204d2c2..ad765f35d 100644 --- a/man/std::wcstol,std::wcstoll.3 +++ b/man/std::wcstol,std::wcstoll.3 @@ -1,13 +1,16 @@ -.TH std::wcstol,std::wcstoll 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcstol,std::wcstoll 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcstol,std::wcstoll \- std::wcstol,std::wcstoll + .SH Synopsis Defined in header - long wcstol( const wchar_t* str, wchar_t** str_end, int base ); + long wcstol ( const wchar_t* str, wchar_t** str_end, int base ); long long wcstoll( const wchar_t* str, wchar_t** str_end, int base ); \fI(since C++11)\fP Interprets an integer value in a wide string pointed to by str. - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as + Discards any whitespace characters (as identified by calling std::iswspace) until + the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to an integer value. The valid integer value consists of the following parts: @@ -19,17 +22,22 @@ base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type. + The functions sets the pointer pointed to by str_end to point to the wide character - past the last character interpreted. If str_end is NULL, it is ignored. + past the last character interpreted. If str_end is a null pointer, it is ignored. .SH Parameters @@ -46,17 +54,47 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + const wchar_t* p = L"10 200000000000000000000000000000 30 -40"; + wchar_t* end; + std::wcout << "Parsing L'" << p << "':\\n"; + for (long i = std::wcstol(p, &end, 10); p != end; i = std::wcstol(p, &end, 10)) + { + std::wcout << '\\'' << std::wstring(p, end-p) << "' -> "; + p = end; + if (errno == ERANGE) + { + std::wcout << "range error, got "; + errno = 0; + } + std::wcout << i << '\\n'; + } + } + +.SH Possible output: + + Parsing L'10 200000000000000000000000000000 30 -40': + '10' -> 10 + ' 200000000000000000000000000000' -> range error, got 9223372036854775807 + ' 30' -> 30 + ' -40' -> -40 .SH See also + strtol converts a byte string to an integer value + strtoll \fI(function)\fP + \fI(C++11)\fP wcstoul converts a wide string to an unsigned integer value - wcstoull \fI(function)\fP + wcstoull \fI(function)\fP C documentation for wcstol, wcstoll - -.SH Category: - - * Todo no example diff --git a/man/std::wcstombs.3 b/man/std::wcstombs.3 index 70fb3b1f7..161297162 100644 --- a/man/std::wcstombs.3 +++ b/man/std::wcstombs.3 @@ -1,7 +1,10 @@ -.TH std::wcstombs 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcstombs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcstombs \- std::wcstombs + .SH Synopsis Defined in header - std::size_t wcstombs( char* dst, const wchar_t* src, std::size_t len) + std::size_t wcstombs( char* dst, const wchar_t* src, std::size_t len ); Converts a sequence of wide characters from the array whose first element is pointed to by src to its narrow multibyte representation that begins in the initial shift @@ -43,13 +46,13 @@ .SH Example - + // Run this code - #include #include #include - + #include + int main() { std::setlocale(LC_ALL, "en_US.utf8"); @@ -67,10 +70,11 @@ .SH See also wcsrtombs converts a wide string to narrow multibyte character string, given state - \fI(function)\fP + \fI(function)\fP mbstowcs converts a narrow multibyte character string to wide string - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for wcstombs diff --git a/man/std::wcstoul,std::wcstoull.3 b/man/std::wcstoul,std::wcstoull.3 index a2384f801..7bac1d6bb 100644 --- a/man/std::wcstoul,std::wcstoull.3 +++ b/man/std::wcstoul,std::wcstoull.3 @@ -1,41 +1,51 @@ -.TH std::wcstoul,std::wcstoull 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcstoul,std::wcstoull 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcstoul,std::wcstoull \- std::wcstoul,std::wcstoull + .SH Synopsis Defined in header - unsigned long wcstoul( const wchar_t* str, wchar_t** str_end, + unsigned long wcstoul ( const wchar_t* str, wchar_t** str_end, int base ); unsigned long long wcstoull( const wchar_t* str, wchar_t** str_end, \fI(since C++11)\fP int base ); Interprets an unsigned integer value in a wide string pointed to by str. - Function discards any whitespace characters (as identified by calling isspace()) - until first non-whitespace character is found. Then it takes as many characters as + Discards any whitespace characters (as identified by calling std::iswspace) until + the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts: + * (optional) plus or minus sign * (optional) prefix \fB(0)\fP indicating octal base (applies only when the base is 8 or 0) * (optional) prefix (0x or 0X) indicating hexadecimal base (applies only when the base is 16 or 0) * a sequence of digits - The set of valid digits for base-2 integer is 01, for base-3 integer is 012, and so - on. For bases larger than 10, valid digits include alphabetic characters, starting - from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters - is ignored. In non-default locales, additional numeric formats may be accepted. + The set of valid values for base is {0,2,3,...,36}. The set of valid digits for + base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases + larger than 10, valid digits include alphabetic characters, starting from Aa for + base-11 integer, to Zz for base-36 integer. The case of the characters is ignored. + + Additional numeric formats may be accepted by the currently installed C locale. If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal. + If the minus sign was part of the input sequence, the numeric value calculated from + the sequence of digits is negated as if by unary minus in the result type, which + applies unsigned integer wraparound rules. + The functions sets the pointer pointed to by str_end to point to the wide character - past the last character interpreted. If str_end is NULL, it is ignored. + past the last character interpreted. If str_end is a null pointer, it is ignored. .SH Parameters str - pointer to the null-terminated wide string to be interpreted - str_end - pointer to a pointer to a wide character. + str_end - pointer to a pointer to a wide character base - base of the interpreted integer value .SH Return value @@ -47,17 +57,49 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + const wchar_t* p = L"10 200000000000000000000000000000 30 40"; + wchar_t* end; + std::wcout << "Parsing L'" << p << "':\\n"; + for (unsigned long i = std::wcstoul(p, &end, 10); + p != end; + i = std::wcstoul(p, &end, 10)) + { + std::wcout << '\\'' << std::wstring(p, end - p) << "' -> "; + p = end; + if (errno == ERANGE) + { + std::wcout << "range error, got "; + errno = 0; + } + std::wcout << i << '\\n'; + } + } + +.SH Possible output: + + Parsing L'10 200000000000000000000000000000 30 40': + '10' -> 10 + ' 200000000000000000000000000000' -> range error, got 18446744073709551615 + ' 30' -> 30 + ' 40' -> 40 .SH See also - wcstol converts a wide string to an integer value - wcstoll \fI(function)\fP + strtoul converts a byte string to an unsigned integer value + strtoull \fI(function)\fP + \fI(C++11)\fP + wcstol converts a wide string to an integer value + wcstoll \fI(function)\fP C documentation for wcstoul, wcstoull - -.SH Category: - - * Todo no example diff --git a/man/std::wcsxfrm.3 b/man/std::wcsxfrm.3 index e38a9617b..90c01d849 100644 --- a/man/std::wcsxfrm.3 +++ b/man/std::wcsxfrm.3 @@ -1,7 +1,10 @@ -.TH std::wcsxfrm 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wcsxfrm 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wcsxfrm \- std::wcsxfrm + .SH Synopsis Defined in header - std::size_t strxfrm( wchar_t* dest, const wchar_t* src, std::size_t count ); + std::size_t wcsxfrm( wchar_t* dest, const wchar_t* src, std::size_t count ); Transforms the null-terminated wide string pointed to by src into the implementation-defined form such that comparing two transformed strings with @@ -16,8 +19,13 @@ .SH Notes - The correct length of the buffer that can receive the entire transformed string is - 1+std::wcsxfrm(NULL, src, 0) + The correct length of the buffer that can receive the entire transformed string is 1 + + std::wcsxfrm(nullptr, src, 0). + + This function is used when making multiple locale-dependent comparisons using the + same wide string or set of wide strings, because it is more efficient to use + std::wcsxfrm to transform all the strings just once, and subsequently compare the + transformed wide strings with std::wcscmp. .SH Parameters @@ -33,36 +41,36 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::setlocale(LC_ALL, "sv_SE.utf8"); - + std::wstring in1 = L"\\u00e5r"; - std::wstring out1(1+std::wcsxfrm(nullptr, in1.c_str(), 0), L' '); + std::wstring out1(1 + std::wcsxfrm(nullptr, in1.c_str(), 0), L' '); std::wstring in2 = L"\\u00e4ngel"; - std::wstring out2(1+std::wcsxfrm(nullptr, in2.c_str(), 0), L' '); - + std::wstring out2(1 + std::wcsxfrm(nullptr, in2.c_str(), 0), L' '); + std::wcsxfrm(&out1[0], in1.c_str(), out1.size()); std::wcsxfrm(&out2[0], in2.c_str(), out2.size()); - + std::wcout << "In the Swedish locale: "; - if(out1 < out2) - std::wcout << in1 << " before " << in2 << '\\n'; + if (out1 < out2) + std::wcout << in1 << " before " << in2 << '\\n'; else - std::wcout << in2 << " before " << in1 << '\\n'; - + std::wcout << in2 << " before " << in1 << '\\n'; + std::wcout << "In lexicographical comparison: "; - if(in1 < in2) - std::wcout << in1 << " before " << in2 << '\\n'; + if (in1 < in2) + std::wcout << in1 << " before " << in2 << '\\n'; else - std::wcout << in2 << " before " << in1 << '\\n'; - + std::wcout << in2 << " before " << in1 << '\\n'; + } .SH Output: @@ -74,10 +82,10 @@ transform a string so that strcmp would produce the same result as strxfrm strcoll - \fI(function)\fP + \fI(function)\fP do_transform transforms a string so that collation can be replaced by comparison - \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::collate)\fP wcscoll compares two wide strings in accordance to the current locale - \fI(function)\fP + \fI(function)\fP C documentation for wcsxfrm diff --git a/man/std::wctob.3 b/man/std::wctob.3 index 646ff434f..9201db3b2 100644 --- a/man/std::wctob.3 +++ b/man/std::wctob.3 @@ -1,4 +1,7 @@ -.TH std::wctob 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wctob 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wctob \- std::wctob + .SH Synopsis Defined in header int wctob( std::wint_t c ); @@ -19,33 +22,33 @@ EOF if c does not represent a multibyte character with length 1 in initial shift state. - Otherwise, the single-byte representation of c as unsigned char converted to int + Otherwise, the single-byte representation of c as unsigned char converted to int. .SH Example - + // Run this code #include #include #include - + void try_narrowing(wchar_t c) { int cn = std::wctob(c); - if(cn != EOF) - std::cout << '\\'' << c << "' narrowed to " << +cn << '\\n'; + if (cn != EOF) + std::cout << '\\'' << int(c) << "' narrowed to " << +cn << '\\n'; else - std::cout << '\\'' << c << "' could not be narrowed\\n"; + std::cout << '\\'' << int(c) << "' could not be narrowed\\n"; } - + int main() { std::setlocale(LC_ALL, "th_TH.utf8"); std::cout << std::hex << std::showbase << "In Thai UTF-8 locale:\\n"; try_narrowing(L'a'); try_narrowing(L'๛'); - + std::setlocale(LC_ALL, "th_TH.tis620"); std::cout << "In Thai TIS-620 locale:\\n"; try_narrowing(L'a'); @@ -64,10 +67,10 @@ .SH See also btowc widens a single-byte narrow character to wide character, if possible - \fI(function)\fP + \fI(function)\fP narrow narrows characters - \fI(public member function of std::basic_ios)\fP + \fI(public member function of std::basic_ios)\fP narrow invokes do_narrow - \fI(public member function of std::ctype)\fP + \fI(public member function of std::ctype)\fP C documentation for wctob diff --git a/man/std::wctomb.3 b/man/std::wctomb.3 index 3dc95a545..35846e413 100644 --- a/man/std::wctomb.3 +++ b/man/std::wctomb.3 @@ -1,11 +1,15 @@ -.TH std::wctomb 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wctomb 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wctomb \- std::wctomb + .SH Synopsis Defined in header - int wctomb( char *s, wchar_t wc ); + int wctomb( char* s, wchar_t wc ); Converts a wide character wc to multibyte encoding and stores it (including any shift sequences) in the char array whose first element is pointed to by s. No more - than MB_CUR_MAX characters are stored. + than MB_CUR_MAX characters are stored. The conversion is affected by the current + locale's LC_CTYPE category. If wc is the null character, the null byte is written to s, preceded by any shift sequences necessary to restore the initial shift state. @@ -37,25 +41,36 @@ .SH Example - + // Run this code - #include #include - #include #include - + #include + #include + #include + void print_wide(const std::wstring& wstr) { - bool shifts = std::wctomb(NULL, 0); // reset the conversion state - std::cout << "shift sequences " << (shifts ? "are" : "not" ) << " used\\n"; - for (wchar_t wc : wstr) { + bool shifts = std::wctomb(nullptr, 0); // reset the conversion state + std::cout << "shift sequences are " << (shifts ? "" : "not" ) + << " used\\n" << std::uppercase << std::setfill('0'); + for (const wchar_t wc : wstr) + { std::string mb(MB_CUR_MAX, '\\0'); - int ret = std::wctomb(&mb[0], wc); - std::cout << "multibyte char " << mb << " is " << ret << " bytes\\n"; + const int ret = std::wctomb(&mb[0], wc); + const char* s = ret > 1 ? "s" : ""; + std::cout << "multibyte char '" << mb << "' is " << ret + << " byte" << s << ": [" << std::hex; + for (int i{0}; i != ret; ++i) + { + const int c = 0xFF & mb[i]; + std::cout << (i ? " " : "") << std::setw(2) << c; + } + std::cout << "]\\n" << std::dec; } } - + int main() { std::setlocale(LC_ALL, "en_US.utf8"); @@ -66,19 +81,20 @@ .SH Output: - shift sequences not used - multibyte char z is 1 bytes - multibyte char ß is 2 bytes - multibyte char 水 is 3 bytes - multibyte char 𝄋 is 4 bytes + shift sequences are not used + multibyte char 'z' is 1 byte: [7A] + multibyte char 'ß' is 2 bytes: [C3 9F] + multibyte char '水' is 3 bytes: [E6 B0 B4] + multibyte char '𝄋' is 4 bytes: [F0 9D 84 8B] .SH See also mbtowc converts the next multibyte character to wide character - \fI(function)\fP + \fI(function)\fP wcrtomb converts a wide character to its multibyte representation, given state - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) C documentation for wctomb diff --git a/man/std::wctrans.3 b/man/std::wctrans.3 index 7bb58d90a..729f1c768 100644 --- a/man/std::wctrans.3 +++ b/man/std::wctrans.3 @@ -1,11 +1,14 @@ -.TH std::wctrans 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wctrans 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wctrans \- std::wctrans + .SH Synopsis Defined in header std::wctrans_t wctrans( const char* str ); Constructs a value of type std::wctrans_t that describes a LC_CTYPE category of wide character mapping. It may be one of the standard mappings, or a locale-specific - mapping, such as "tojhira" or "tojkana". + mapping, such as "tojhira" or "tojkata". .SH Parameters @@ -23,10 +26,18 @@ according to the named mapping of the current C locale or zero if str does not name a mapping supported by the current C locale. +.SH Example + + This section is incomplete + Reason: no example + .SH See also performs character mapping according to the specified LC_CTYPE mapping towctrans category - \fI(function)\fP + \fI(function)\fP C documentation for wctrans + +.SH Category: + * Todo no example diff --git a/man/std::wctype.3 b/man/std::wctype.3 index 8f891d19c..26b01e49d 100644 --- a/man/std::wctype.3 +++ b/man/std::wctype.3 @@ -1,4 +1,7 @@ -.TH std::wctype 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wctype 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wctype \- std::wctype + .SH Synopsis Defined in header std::wctype_t wctype( const char* str ); @@ -35,6 +38,6 @@ .SH See also iswctype classifies a wide character according to the specified LC_CTYPE category - \fI(function)\fP + \fI(function)\fP C documentation for wctype diff --git a/man/std::weak_order.3 b/man/std::weak_order.3 new file mode 100644 index 000000000..166610f50 --- /dev/null +++ b/man/std::weak_order.3 @@ -0,0 +1,66 @@ +.TH std::weak_order 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_order \- std::weak_order + +.SH Synopsis + Defined in header + inline namespace /* unspecified */ { + + inline constexpr /* unspecified */ weak_order = /* unspecified \fI(since C++20)\fP + */; + + } + Call signature + template< class T, class U > + + requires /* see below */ + + constexpr std::weak_ordering weak_order(T&& t, U&& u) noexcept(/* see + below */); + + Compares two values using 3-way comparison and produces a result of type + std::weak_ordering. + + Let t and u be expressions and T and U denote decltype((t)) and decltype((u)) + respectively, std::weak_order(t, u) is expression-equivalent to: + + * If std::is_same_v, std::decay_t> is true: + * std::weak_ordering(weak_order(t, u)), if it is a well-formed expression + with overload resolution performed in a context that does not include a + declaration of std::weak_order, + * otherwise, if T is a floating-point type: + * if std::numeric_limits::is_iec559 is true, performs the weak + ordering comparison of floating-point values (see below) and returns + that result as a value of type std::weak_ordering, + * otherwise, yields a value of type std::weak_ordering that is + consistent with the ordering observed by T's comparison operators, + * otherwise, std::weak_ordering(std::compare_three_way()(t, u)), if it is + well-formed, + * otherwise, std::weak_ordering(std::strong_order(t, u)), if it is + well-formed. + * In all other cases, the expression is ill-formed, which can result in + substitution failure when it appears in the immediate context of a template + instantiation. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + weak_ordering the result type of 3-way comparison that supports all 6 + (C++20) operators and is not substitutable + \fI(class)\fP + strong_order performs 3-way comparison and produces a result of type + (C++20) std::strong_ordering + (customization point object) + partial_order performs 3-way comparison and produces a result of type + (C++20) std::partial_ordering + (customization point object) + compare_weak_order_fallback performs 3-way comparison and produces a result of type + (C++20) std::weak_ordering, even if operator<=> is unavailable + (customization point object) + +.SH Category: + * Todo no example diff --git a/man/std::weak_ordering.3 b/man/std::weak_ordering.3 new file mode 100644 index 000000000..662f189cf --- /dev/null +++ b/man/std::weak_ordering.3 @@ -0,0 +1,186 @@ +.TH std::weak_ordering 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ordering \- std::weak_ordering + +.SH Synopsis + Defined in header + class weak_ordering; \fI(since C++20)\fP + + The class type std::weak_ordering is the result type of a three-way comparison that: + + * Admits all six relational operators (==, !=, <, <=, >, >=). + * Does not imply substitutability: if a is equivalent to b, f(a) may not be + equivalent to f(b), where f denotes a function that reads only + comparison-salient state that is accessible via the argument's public const + members. In other words, equivalent values may be distinguishable. + * Does not allow incomparable values: exactly one of a < b, a == b, or a > b must + be true. + +.SH Constants + + The type std::weak_ordering has three valid values, implemented as const static data + members of its type: + + Member constant Definition + less(inline constexpr) a valid value of the type std::weak_ordering indicating + \fB[static]\fP less-than (ordered before) relationship + \fI(public static member constant)\fP + equivalent(inline constexpr) a valid value of the type std::weak_ordering indicating + \fB[static]\fP equivalence (neither ordered before nor ordered after) + \fI(public static member constant)\fP + greater(inline constexpr) a valid value of the type std::weak_ordering indicating + \fB[static]\fP greater-than (ordered after) relationship + \fI(public static member constant)\fP + +.SH Conversions + + std::weak_ordering is implicitly-convertible to std::partial_ordering, while + std::strong_ordering is implicitly-convertible to weak_ordering. + + operator partial_ordering implicit conversion to std::partial_ordering + \fI(public member function)\fP + +std::weak_ordering::operator partial_ordering + + constexpr operator partial_ordering() const noexcept; + +.SH Return value + + std::partial_ordering::less if v is less, std::partial_ordering::greater if v is + greater, std::partial_ordering::equivalent if v is equivalent. + +.SH Comparisons + + Comparison operators are defined between values of this type and literal 0. This + supports the expressions a <=> b == 0 or a <=> b < 0 that can be used to convert the + result of a three-way comparison operator to a boolean relationship; see std::is_eq, + std::is_lt, etc. + + These functions are not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::weak_ordering is an associated + class of the arguments. + + The behavior of a program that attempts to compare a weak_ordering with anything + other than the integer literal 0 is undefined. + + operator== + operator< + operator> compares with zero or a weak_ordering + operator<= \fI(function)\fP + operator>= + operator<=> + +operator== + + friend constexpr bool operator==( weak_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator==( weak_ordering v, weak_ordering w ) noexcept = \fB(2)\fP + default; + +.SH Parameters + + v, w - std::weak_ordering values to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is equivalent, false if v is less or greater + 2) true if both parameters hold the same value, false otherwise + +operator< + + friend constexpr bool operator<( weak_ordering v, /*unspecified*/ u ) noexcept; \fB(1)\fP + friend constexpr bool operator<( /*unspecified*/ u, weak_ordering v ) noexcept; \fB(2)\fP + +.SH Parameters + + v - a std::weak_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is less, and false if v is greater or equivalent + 2) true if v is greater, and false if v is less or equivalent + +operator<= + + friend constexpr bool operator<=( weak_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator<=( /*unspecified*/ u, weak_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::weak_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is less or equivalent, and false if v is greater + 2) true if v is greater or equivalent, and false if v is less + +operator> + + friend constexpr bool operator>( weak_ordering v, /*unspecified*/ u ) noexcept; \fB(1)\fP + friend constexpr bool operator>( /*unspecified*/ u, weak_ordering v ) noexcept; \fB(2)\fP + +.SH Parameters + + v - a std::weak_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is greater, and false if v is less or equivalent + 2) true if v is less, and false if v is greater or equivalent + +operator>= + + friend constexpr bool operator>=( weak_ordering v, /*unspecified*/ u ) \fB(1)\fP + noexcept; + friend constexpr bool operator>=( /*unspecified*/ u, weak_ordering v ) \fB(2)\fP + noexcept; + +.SH Parameters + + v - a std::weak_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) true if v is greater or equivalent, and false if v is less + 2) true if v is less or equivalent, and false if v is greater + +operator<=> + + friend constexpr weak_ordering operator<=>( weak_ordering v, /*unspecified*/ u \fB(1)\fP + ) noexcept; + friend constexpr weak_ordering operator<=>( /*unspecified*/ u, weak_ordering v \fB(2)\fP + ) noexcept; + +.SH Parameters + + v - a std::weak_ordering value to check + u - an unused parameter of any type that accepts literal zero argument + +.SH Return value + + 1) v. + 2) greater if v is less, less if v is greater, otherwise v. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + strong_ordering the result type of 3-way comparison that supports all 6 operators + (C++20) and is substitutable + \fI(class)\fP + partial_ordering the result type of 3-way comparison that supports all 6 operators, + (C++20) is not substitutable, and allows incomparable values + \fI(class)\fP + +.SH Category: + * Todo no example diff --git a/man/std::weak_ptr.3 b/man/std::weak_ptr.3 index 4046f4841..e640478af 100644 --- a/man/std::weak_ptr.3 +++ b/man/std::weak_ptr.3 @@ -1,4 +1,7 @@ -.TH std::weak_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr \- std::weak_ptr + .SH Synopsis Defined in header template< class T > class weak_ptr; \fI(since C++11)\fP @@ -10,79 +13,127 @@ std::weak_ptr models temporary ownership: when an object needs to be accessed only if it exists, and it may be deleted at any time by someone else, std::weak_ptr is used to track the object, and it is converted to std::shared_ptr to assume temporary - ownership. If the original std::weak_ptr is destroyed at this time, the object's + ownership. If the original std::shared_ptr is destroyed at this time, the object's lifetime is extended until the temporary std::shared_ptr is destroyed as well. - In addition, std::weak_ptr is used to break circular references of std::shared_ptr. + Another use for std::weak_ptr is to break reference cycles formed by objects managed + by std::shared_ptr. If such cycle is orphaned (i.e., there are no outside shared + pointers into the cycle), the shared_ptr reference counts cannot reach zero and the + memory is leaked. To prevent this, one of the pointers in the cycle can be made + weak. .SH Member types Member type Definition - element_type T + element_type T \fI(until C++17)\fP + std::remove_extent_t \fI(since C++17)\fP .SH Member functions constructor creates a new weak_ptr - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a weak_ptr - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns the weak_ptr - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers reset releases the ownership of the managed object - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the managed objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Observers use_count returns the number of shared_ptr objects that manage the object - \fI(public member function)\fP + \fI(public member function)\fP expired checks whether the referenced object was already deleted - \fI(public member function)\fP + \fI(public member function)\fP lock creates a shared_ptr that manages the referenced object - \fI(public member function)\fP + \fI(public member function)\fP owner_before provides owner-based ordering of weak pointers - \fI(public member function)\fP + \fI(public member function)\fP + owner_hash provides owner-based hashing of weak pointers + (C++26) \fI(public member function)\fP + owner_equal provides owner-based equal comparison of weak pointers + (C++26) \fI(public member function)\fP .SH Non-member functions std::swap(std::weak_ptr) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + +.SH Helper classes + + std::atomic atomic weak pointer + (C++20) \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Like std::shared_ptr, a typical implementation of weak_ptr stores two pointers: + + * a pointer to the control block; and + * the stored pointer of the shared_ptr it was constructed from. + + A separate stored pointer is necessary to ensure that converting a shared_ptr to + weak_ptr and then back works correctly, even for aliased shared_ptrs. It is not + possible to access the stored pointer in a weak_ptr without locking it into a + shared_ptr. + + Feature-test macro Value Std Feature + Enabling the use of std::weak_ptr + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) as keys in unordered associative + containers .SH Example Demonstrates how lock is used to ensure validity of the pointer. - + // Run this code #include #include - + std::weak_ptr gw; - - void f() + + void observe() { - if (auto spt = gw.lock()) { // Has to be copied into a shared_ptr before usage - std::cout << *spt << "\\n"; - } - else { + std::cout << "gw.use_count() == " << gw.use_count() << "; "; + // we have to make a copy of shared pointer before usage: + if (std::shared_ptr spt = gw.lock()) + std::cout << "*spt == " << *spt << '\\n'; + else std::cout << "gw is expired\\n"; - } } - + int main() { { auto sp = std::make_shared(42); gw = sp; - - f(); + + observe(); } - - f(); + + observe(); } .SH Output: - 42 - gw is expired + gw.use_count() == 1; *spt == 42 + gw.use_count() == 0; gw is expired + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3001 C++17 element_type was not updated for array support updated + +.SH See also + + unique_ptr smart pointer with unique object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + shared_ptr smart pointer with shared object ownership semantics + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::weak_ptr::expired.3 b/man/std::weak_ptr::expired.3 index 0f5e4cf72..1419f7610 100644 --- a/man/std::weak_ptr::expired.3 +++ b/man/std::weak_ptr::expired.3 @@ -1,9 +1,13 @@ -.TH std::weak_ptr::expired 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::expired 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::expired \- std::weak_ptr::expired + .SH Synopsis - bool expired() const; \fI(since C++11)\fP + bool expired() const noexcept; \fI(since C++11)\fP - Checks whether the managed object has already been deleted. Equivalent to - use_count() == 0. + Equivalent to use_count() == 0. The destructor for the managed object may not yet + have been called, but this object's destruction is imminent (or may have already + happened). .SH Parameters @@ -13,47 +17,41 @@ true if the managed object has already been deleted, false otherwise. -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes - expired() may be faster than use_count(). + This function is inherently racy if the managed object is shared among threads. In + particular, a false result may become stale before it can be used. A true result is + reliable. .SH Example Demonstrates how expired is used to check validity of the pointer. - + // Run this code #include #include - + std::weak_ptr gw; - + void f() { - if (!gw.expired()) { + if (!gw.expired()) std::cout << "gw is valid\\n"; - } - else { + else std::cout << "gw is expired\\n"; - } } - + int main() { { auto sp = std::make_shared(42); gw = sp; - + f(); } - + f(); } @@ -65,6 +63,6 @@ .SH See also lock creates a shared_ptr that manages the referenced object - \fI(public member function)\fP + \fI(public member function)\fP use_count returns the number of shared_ptr objects that manage the object - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::weak_ptr::lock.3 b/man/std::weak_ptr::lock.3 index a66adcdc9..5cb7ccea8 100644 --- a/man/std::weak_ptr::lock.3 +++ b/man/std::weak_ptr::lock.3 @@ -1,9 +1,13 @@ -.TH std::weak_ptr::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::lock \- std::weak_ptr::lock + .SH Synopsis - std::shared_ptr lock() const \fI(since C++11)\fP + std::shared_ptr lock() const noexcept; \fI(since C++11)\fP - Creates a new shared_ptr that shares ownership of the managed object. If there is no - managed object, i.e. *this is empty, then the returned shared_ptr also is empty. + Creates a new std::shared_ptr that shares ownership of the managed object. If there + is no managed object, i.e. *this is empty, then the returned shared_ptr also is + empty. Effectively returns expired() ? shared_ptr() : shared_ptr(*this), executed atomically. @@ -14,67 +18,70 @@ .SH Return value - A shared_ptr which shares ownership of the owned object. - -.SH Exceptions - - noexcept specification: - noexcept - + A shared_ptr which shares ownership of the owned object if std::weak_ptr::expired + returns false. Else returns default-constructed shared_ptr of type T. .SH Notes - Both this function and the constructor of shared_ptr may be used to acquire - temporary ownership of the managed object. The difference is that the constructor of - std::shared_ptr throws an exception when the std::weak_ptr argument is empty, - while std::weak_ptr::lock() constructs an empty std::shared_ptr. + Both this function and the constructor of std::shared_ptr may be used to acquire + temporary ownership of the managed object referred to by a std::weak_ptr. The + difference is that the constructor of std::shared_ptr throws an exception when its + std::weak_ptr argument is empty, while std::weak_ptr::lock() constructs an empty + std::shared_ptr. .SH Example - + // Run this code #include #include - #include - + void observe(std::weak_ptr weak) { - std::shared_ptr observe(weak.lock()); - if (observe) { - std::cout << "\\tobserve() able to lock weak_ptr<>, value=" << *observe << "\\n"; - } else { - std::cout << "\\tobserve() unable to lock weak_ptr<>\\n"; - } + if (auto p = weak.lock()) + std::cout << "\\tobserve() is able to lock weak_ptr<>, value=" << *p << '\\n'; + else + std::cout << "\\tobserve() is unable to lock weak_ptr<>\\n"; } - + int main() { std::weak_ptr weak; - std::cout << "weak_ptr<> not yet initialized\\n"; + std::cout << "weak_ptr<> is not yet initialized\\n"; observe(weak); - + { - std::shared_ptr shared(new int(42)); + auto shared = std::make_shared(42); weak = shared; - std::cout << "weak_ptr<> initialized with shared_ptr.\\n"; + std::cout << "weak_ptr<> is initialized with shared_ptr\\n"; observe(weak); } - - std::cout << "shared_ptr<> has been destructed due to scope exit.\\n"; + + std::cout << "shared_ptr<> has been destructed due to scope exit\\n"; observe(weak); } .SH Output: - weak_ptr<> not yet initialized - observe() unable to lock weak_ptr<> - weak_ptr<> initialized with shared_ptr. - observe() able to lock weak_ptr<>, value=42 - shared_ptr<> has been destructed due to scope exit. - observe() unable to lock weak_ptr<> + weak_ptr<> is not yet initialized + observe() is unable to lock weak_ptr<> + weak_ptr<> is initialized with shared_ptr + observe() is able to lock weak_ptr<>, value=42 + shared_ptr<> has been destructed due to scope exit + observe() is unable to lock weak_ptr<> + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + lock() was not required to be atomic, but + LWG 2316 C++11 required to be noexcept, which led to a specified to be atomic + contradiction .SH See also expired checks whether the referenced object was already deleted - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::weak_ptr::operator=.3 b/man/std::weak_ptr::operator=.3 index 95c616413..8275f4eb3 100644 --- a/man/std::weak_ptr::operator=.3 +++ b/man/std::weak_ptr::operator=.3 @@ -1,19 +1,22 @@ -.TH std::weak_ptr::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::operator= \- std::weak_ptr::operator= + .SH Synopsis - weak_ptr& operator=( const weak_ptr& r ); \fB(1)\fP \fI(since C++11)\fP - template< class Y > \fB(2)\fP \fI(since C++11)\fP - weak_ptr& operator=( const weak_ptr& r ); - template< class Y > \fB(3)\fP \fI(since C++11)\fP - weak_ptr& operator=( const shared_ptr& r ); - weak_ptr& operator=( weak_ptr&& r ); \fB(4)\fP \fI(since C++14)\fP - template< class Y > \fB(5)\fP \fI(since C++14)\fP - weak_ptr& operator=( weak_ptr&& r ); + weak_ptr& operator=( const weak_ptr& r ) noexcept; \fB(1)\fP \fI(since C++11)\fP + template< class Y > \fB(2)\fP \fI(since C++11)\fP + weak_ptr& operator=( const weak_ptr& r ) noexcept; + template< class Y > \fB(3)\fP \fI(since C++11)\fP + weak_ptr& operator=( const shared_ptr& r ) noexcept; + weak_ptr& operator=( weak_ptr&& r ) noexcept; \fB(4)\fP \fI(since C++11)\fP + template< class Y > \fB(5)\fP \fI(since C++11)\fP + weak_ptr& operator=( weak_ptr&& r ) noexcept; Replaces the managed object with the one managed by r. The object is shared with r. - If r manages no object, *this manages no object too. Equivalent to - weak_ptr(r).swap(*this). + If r manages no object, *this manages no object too. - 4,5) Equivalent to std::weak_ptr(std::move(r)).swap(*this). + 1-3) Equivalent to std::weak_ptr(r).swap(*this). + 4,5) Equivalent to std::weak_ptr(std::move(r)).swap(*this). .SH Parameters @@ -23,13 +26,22 @@ *this -.SH Exceptions - - noexcept specification: - noexcept - - .SH Notes The implementation may meet the requirements without creating a temporary weak_ptr object. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2315 C++11 move semantic was not enabled for weak_ptr enabled + +.SH See also + + constructor creates a new weak_ptr + \fI(public member function)\fP + swap swaps the managed objects + \fI(public member function)\fP diff --git a/man/std::weak_ptr::owner_before.3 b/man/std::weak_ptr::owner_before.3 index f77f5ce8f..d64f4707c 100644 --- a/man/std::weak_ptr::owner_before.3 +++ b/man/std::weak_ptr::owner_before.3 @@ -1,15 +1,18 @@ -.TH std::weak_ptr::owner_before 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::owner_before 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::owner_before \- std::weak_ptr::owner_before + .SH Synopsis - template< class T > - bool owner_before( const weak_ptr& other) const; - template< class T > - bool owner_before( const std::shared_ptr& other) const; + template< class Y > + bool owner_before( const weak_ptr& other ) const noexcept; + template< class Y > + bool owner_before( const std::shared_ptr& other ) const noexcept; Checks whether this weak_ptr precedes other in implementation defined owner-based (as opposed to value-based) order. The order is such that two smart pointers compare equivalent only if they are both empty or if they both own the same object, even if the values of the pointers obtained by get() are different (e.g. because they point - at different subobjects within the same object) + at different subobjects within the same object). This ordering is used to make shared and weak pointers usable as keys in associative containers, typically through std::owner_less. @@ -25,37 +28,38 @@ .SH Example - + // Run this code #include #include - - struct Foo { + + struct Foo + { int n1; int n2; Foo(int a, int b) : n1(a), n2(b) {} }; + int main() { auto p1 = std::make_shared(1, 2); std::shared_ptr p2(p1, &p1->n1); std::shared_ptr p3(p1, &p1->n2); - + std::cout << std::boolalpha << "p2 < p3 " << (p2 < p3) << '\\n' << "p3 < p2 " << (p3 < p2) << '\\n' << "p2.owner_before(p3) " << p2.owner_before(p3) << '\\n' << "p3.owner_before(p2) " << p3.owner_before(p2) << '\\n'; - + std::weak_ptr w2(p2); std::weak_ptr w3(p3); std::cout - // << "w2 < w3 " << (w2 < w3) << '\\n' // won't compile - // << "w3 < w2 " << (w3 < w2) << '\\n' // won't compile + // << "w2 < w3 " << (w2 < w3) << '\\n' // won't compile + // << "w3 < w2 " << (w3 < w2) << '\\n' // won't compile << "w2.owner_before(w3) " << w2.owner_before(w3) << '\\n' << "w3.owner_before(w2) " << w3.owner_before(w2) << '\\n'; - } .SH Output: @@ -67,7 +71,16 @@ w2.owner_before(w3) false w3.owner_before(w2) false + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2083 C++11 owner_before was not declared const declared const + LWG 2942 C++11 owner_before was not declared noexcept declared noexcept + .SH See also owner_less provides mixed-type owner-based ordering of shared and weak pointers - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::weak_ptr::owner_equal.3 b/man/std::weak_ptr::owner_equal.3 new file mode 100644 index 000000000..39b86f62b --- /dev/null +++ b/man/std::weak_ptr::owner_equal.3 @@ -0,0 +1,52 @@ +.TH std::weak_ptr::owner_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::owner_equal \- std::weak_ptr::owner_equal + +.SH Synopsis + template< class Y > \fB(1)\fP (since C++26) + bool owner_equal( const std::weak_ptr& other ) const noexcept; + template< class Y > + bool owner_equal( const std::shared_ptr& other ) const \fB(2)\fP (since C++26) + noexcept; + + Checks whether this weak_ptr and other share ownership or are both empty. The + comparison is such that two smart pointers compare equivalent only if they are both + empty or if they both own the same object, even if the values of the pointers + obtained by get() are different (e.g. because they point at different subobjects + within the same object). + + The member function owner_equal is an equivalence relation such that + !owner_before(other) && !other.owner_before(*this) is true if and only if + owner_equal(other) is true. + + This ordering is used to make shared and weak pointers usable as keys in unordered + associative containers, typically through std::owner_equal. + +.SH Parameters + + other - the std::shared_ptr or std::weak_ptr to be compared + +.SH Return value + + true if *this and other share ownership or are both empty. Otherwise, returns false. + +.SH Notes + + Feature-test macro Value Std Feature + Enabling the use of std::weak_ptr + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) as keys in unordered associative + containers + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + owner_equal provides mixed-type owner-based equal comparisons of shared and weak + (C++26) pointers + \fI(class)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::weak_ptr::owner_hash.3 b/man/std::weak_ptr::owner_hash.3 new file mode 100644 index 000000000..0c6645fdf --- /dev/null +++ b/man/std::weak_ptr::owner_hash.3 @@ -0,0 +1,37 @@ +.TH std::weak_ptr::owner_hash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::owner_hash \- std::weak_ptr::owner_hash + +.SH Synopsis + std::size_t owner_hash() const noexcept; (since C++26) + + Returns an unspecified value such that for any object other where owner_equal(other) + is true, owner_hash() == other.owner_hash() is true. + + This hashing is used to make shared and weak pointers usable as keys in unordered + associative containers, typically through std::owner_hash. + +.SH Return value + + A value that is identical for any std::shared_ptr or std::weak_ptr object sharing + the same ownership. + +.SH Notes + + Feature-test macro Value Std Feature + Enabling the use of std::weak_ptr + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) as keys in unordered associative + containers + +.SH Example + + This section is incomplete + Reason: example + +.SH See also + + owner_hash provides owner-based hashing for shared and weak pointers + (C++26) \fI(class)\fP + +.SH Category: + * Todo with reason diff --git a/man/std::weak_ptr::reset.3 b/man/std::weak_ptr::reset.3 index 1a12a5f3b..9e8e4c005 100644 --- a/man/std::weak_ptr::reset.3 +++ b/man/std::weak_ptr::reset.3 @@ -1,6 +1,9 @@ -.TH std::weak_ptr::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::reset \- std::weak_ptr::reset + .SH Synopsis - void reset(); \fI(since C++11)\fP + void reset() noexcept; \fI(since C++11)\fP Releases the reference to the managed object. After the call *this manages no object. @@ -13,8 +16,44 @@ \fI(none)\fP -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + + int main() + { + auto shared = std::make_shared(), shared2 = shared, shared3 = shared2; + + auto weak = std::weak_ptr{shared}; + + std::cout << std::boolalpha + << "shared.use_count(): " << shared.use_count() << '\\n' + << "weak.use_count(): " << weak.use_count() << '\\n' + << "weak.expired(): " << weak.expired() << '\\n'; + + weak.reset(); + + std::cout << "weak.reset();\\n" + << "shared.use_count(): " << shared.use_count() << '\\n' + << "weak.use_count(): " << weak.use_count() << '\\n' + << "weak.expired(): " << weak.expired() << '\\n'; + } + +.SH Output: + + shared.use_count(): 3 + weak.use_count(): 3 + weak.expired(): false + weak.reset(); + shared.use_count(): 3 + weak.use_count(): 0 + weak.expired(): true + +.SH See also - noexcept specification: - noexcept - + expired checks whether the referenced object was already deleted + \fI(public member function)\fP diff --git a/man/std::weak_ptr::swap.3 b/man/std::weak_ptr::swap.3 index f29796fd7..2f6ad4ff3 100644 --- a/man/std::weak_ptr::swap.3 +++ b/man/std::weak_ptr::swap.3 @@ -1,8 +1,12 @@ -.TH std::weak_ptr::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::swap \- std::weak_ptr::swap + .SH Synopsis - void swap( weak_ptr& r ); \fI(since C++11)\fP + void swap( weak_ptr& r ) noexcept; \fI(since C++11)\fP - Exchanges the contents of *this and r + Exchanges the stored pointer values and the ownerships of *this and r. Reference + counts, if any, are not adjusted. .SH Parameters @@ -12,8 +16,55 @@ \fI(none)\fP -.SH Exceptions +.SH Example + + +// Run this code + + #include + #include + #include + + struct Foo + { + Foo(int _val) : val(_val) { std::cout << "Foo...\\n"; } + ~Foo() { std::cout << "~Foo...\\n"; } + std::string print() { return std::to_string(val); } + int val; + }; + + int main() + { + std::shared_ptr sp1 = std::make_shared(100); + std::shared_ptr sp2 = std::make_shared(200); + std::weak_ptr wp1 = sp1; + std::weak_ptr wp2 = sp2; + auto print = [&]() + { + auto p1 = wp1.lock(); + auto p2 = wp2.lock(); + std::cout << " p1=" << (p1 ? p1->print() : "nullptr"); + std::cout << " p2=" << (p2 ? p2->print() : "nullptr") << '\\n'; + }; + print(); + + wp1.swap(wp2); + print(); + + wp1.reset(); + print(); + + wp1.swap(wp2); + print(); + } + +.SH Output: - noexcept specification: - noexcept - + Foo... + Foo... + p1=100 p2=200 + p1=200 p2=100 + p1=nullptr p2=100 + p1=100 p2=nullptr + ~Foo... + ~Foo... diff --git a/man/std::weak_ptr::use_count.3 b/man/std::weak_ptr::use_count.3 index dadf6debd..aab03d8e3 100644 --- a/man/std::weak_ptr::use_count.3 +++ b/man/std::weak_ptr::use_count.3 @@ -1,6 +1,9 @@ -.TH std::weak_ptr::use_count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::use_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::use_count \- std::weak_ptr::use_count + .SH Synopsis - long use_count() const; \fI(since C++11)\fP + long use_count() const noexcept; \fI(since C++11)\fP Returns the number of shared_ptr instances that share ownership of the managed object, or 0 if the managed object has already been deleted, i.e. *this is empty. @@ -11,28 +14,71 @@ .SH Return value - The number of shared_ptr instances sharing the ownership of the managed object. - -.SH Exceptions - - noexcept specification: - noexcept - + The number of shared_ptr instances sharing the ownership of the managed object at + the instant of the call. .SH Notes - expired() may be faster than use_count(). + expired() may be faster than use_count(). This function is inherently racy, if the + managed object is shared among threads that might be creating and destroying copies + of the shared_ptr: then, the result is reliable only if it matches the number of + copies uniquely owned by the calling thread, or zero; any other value may become + stale before it can be used. .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - expired checks whether the referenced object was already deleted - \fI(public member function)\fP + #include + #include + + std::weak_ptr gwp; + + void observe_gwp() + { + std::cout << "use_count(): " << gwp.use_count() << "\\t id: "; + if (auto sp = gwp.lock()) + std::cout << *sp << '\\n'; + else + std::cout << "??\\n"; + } -.SH Category: + void share_recursively(std::shared_ptr sp, int depth) + { + observe_gwp(); // : 2 3 4 + if (1 < depth) + share_recursively(sp, depth - 1); + observe_gwp(); // : 4 3 2 + } - * Todo no example + int main() + { + observe_gwp(); + { + auto sp = std::make_shared(42); + gwp = sp; + observe_gwp(); // : 1 + share_recursively(sp, 3); // : 2 3 4 4 3 2 + observe_gwp(); // : 1 + } + observe_gwp(); // : 0 + } + +.SH Output: + + use_count(): 0 id: ?? + use_count(): 1 id: 42 + use_count(): 2 id: 42 + use_count(): 3 id: 42 + use_count(): 4 id: 42 + use_count(): 4 id: 42 + use_count(): 3 id: 42 + use_count(): 2 id: 42 + use_count(): 1 id: 42 + use_count(): 0 id: ?? + +.SH See also + + expired checks whether the referenced object was already deleted + \fI(public member function)\fP diff --git a/man/std::weak_ptr::weak_ptr.3 b/man/std::weak_ptr::weak_ptr.3 index 155528e9b..40b8fb8c8 100644 --- a/man/std::weak_ptr::weak_ptr.3 +++ b/man/std::weak_ptr::weak_ptr.3 @@ -1,64 +1,82 @@ -.TH std::weak_ptr::weak_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::weak_ptr \- std::weak_ptr::weak_ptr + .SH Synopsis - constexpr weak_ptr(); \fB(1)\fP \fI(since C++11)\fP - weak_ptr( const weak_ptr& r ); \fB(2)\fP \fI(since C++11)\fP - template< class Y > \fB(2)\fP \fI(since C++11)\fP - weak_ptr( const weak_ptr& r ); - template< class Y > \fB(2)\fP \fI(since C++11)\fP - weak_ptr( const std::shared_ptr& r ); - weak_ptr( weak_ptr&& r ); \fB(3)\fP \fI(since C++14)\fP - template< class Y > \fB(3)\fP \fI(since C++14)\fP - weak_ptr( weak_ptr&& r ); + constexpr weak_ptr() noexcept; \fB(1)\fP \fI(since C++11)\fP + weak_ptr( const weak_ptr& r ) noexcept; \fB(2)\fP \fI(since C++11)\fP + template< class Y > \fB(2)\fP \fI(since C++11)\fP + weak_ptr( const weak_ptr& r ) noexcept; + template< class Y > \fB(2)\fP \fI(since C++11)\fP + weak_ptr( const std::shared_ptr& r ) noexcept; + weak_ptr( weak_ptr&& r ) noexcept; \fB(3)\fP \fI(since C++11)\fP + template< class Y > \fB(3)\fP \fI(since C++11)\fP + weak_ptr( weak_ptr&& r ) noexcept; Constructs new weak_ptr that potentially shares an object with r. 1) Default constructor. Constructs empty weak_ptr. 2) Constructs new weak_ptr which shares an object managed by r. If r manages no object, *this manages no object too. The templated overloads don't participate in - the overload resolution unless Y* is implicitly convertible to T*. + the overload resolution unless Y* is implicitly convertible to T* + , or Y is the type "array of N U" for some type U and some number N, and T is the + type "array of unknown bound of (possibly cv-qualified) U" + \fI(since C++17)\fP. 3) Move constructors. Moves a weak_ptr instance from r into *this. After this, r is - empty and r.use_count()==0. The templated overload doesn't participate in the - overload resolution unless Y* is implicitly convertible to T* + empty and r.use_count() == 0. The templated overload doesn't participate in the + overload resolution unless Y* is implicitly convertible to T*. .SH Parameters r - a std::shared_ptr or std::weak_ptr that will be viewed by this std::weak_ptr -.SH Exceptions +.SH Notes - noexcept specification: - noexcept - + Because the default constructor is constexpr, static std::weak_ptrs are initialized + as part of static non-local initialization, before any dynamic non-local + initialization begins. This makes it safe to use a std::weak_ptr in a constructor of + any static object. .SH Example - + // Run this code - #include #include - + #include + struct Foo {}; - + int main() { - std::weak_ptr w_ptr; - - { - auto ptr = std::make_shared(); - w_ptr = ptr; - std::cout << "w_ptr.use_count() inside scope: " << w_ptr.use_count() << '\\n'; - } - - std::cout << "w_ptr.use_count() out of scope: " << w_ptr.use_count() << '\\n'; + std::weak_ptr w_ptr; + + { + auto ptr = std::make_shared(); + w_ptr = ptr; + std::cout << "w_ptr.use_count() inside scope: " << w_ptr.use_count() << '\\n'; + } + + std::cout << "w_ptr.use_count() out of scope: " << w_ptr.use_count() << '\\n'; + std::cout << "w_ptr.expired() out of scope: " + << std::boolalpha << w_ptr.expired() << '\\n'; } .SH Output: w_ptr.use_count() inside scope: 1 w_ptr.use_count() out of scope: 0 + w_ptr.expired() out of scope: true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2315 C++11 move semantic was not enabled for weak_ptr enabled .SH See also operator= assigns the weak_ptr - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::weak_ptr::~weak_ptr.3 b/man/std::weak_ptr::~weak_ptr.3 index 3a4e8e215..404e99d0f 100644 --- a/man/std::weak_ptr::~weak_ptr.3 +++ b/man/std::weak_ptr::~weak_ptr.3 @@ -1,5 +1,77 @@ -.TH std::weak_ptr::~weak_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weak_ptr::~weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weak_ptr::~weak_ptr \- std::weak_ptr::~weak_ptr + .SH Synopsis ~weak_ptr(); \fI(since C++11)\fP Destroys the weak_ptr object. Results in no effect to the managed object. + +.SH Example + + The program shows the effect of "non-breaking" the cycle of std::shared_ptrs. + + +// Run this code + + #include + #include + #include + + class Node + { + char id; + std::variant, std::shared_ptr> ptr; + public: + Node(char id) : id{id} {} + ~Node() { std::cout << " '" << id << "' reclaimed\\n"; } + /*...*/ + void assign(std::weak_ptr p) { ptr = p; } + void assign(std::shared_ptr p) { ptr = p; } + }; + + enum class shared { all, some }; + + void test_cyclic_graph(const shared x) + { + auto A = std::make_shared('A'); + auto B = std::make_shared('B'); + auto C = std::make_shared('C'); + + A->assign(B); + B->assign(C); + + if (shared::all == x) + { + C->assign(A); + std::cout << "All links are shared pointers"; + } + else + { + C->assign(std::weak_ptr(A)); + std::cout << "One link is a weak_ptr"; + } + /*...*/ + std::cout << "\\nLeaving...\\n"; + } + + int main() + { + test_cyclic_graph(shared::some); + test_cyclic_graph(shared::all); // produces a memory leak + } + +.SH Output: + + One link is a weak_ptr + Leaving... + 'A' reclaimed + 'B' reclaimed + 'C' reclaimed + All links are shared pointers + Leaving... + +.SH See also + + destructor destructs the owned object if no more shared_ptrs link to it + \fI(public member function of std::shared_ptr)\fP diff --git a/man/std::weakly_incrementable.3 b/man/std::weakly_incrementable.3 new file mode 100644 index 000000000..ce18c96de --- /dev/null +++ b/man/std::weakly_incrementable.3 @@ -0,0 +1,38 @@ +.TH std::weakly_incrementable 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weakly_incrementable \- std::weakly_incrementable + +.SH Synopsis + Defined in header + template< class I > + + concept weakly_incrementable = + std::movable && + requires(I i) { + typename std::iter_difference_t; (since + requires /*is-signed-integer-like*/>; C++20) + { ++i } -> std::same_as; // not required to be + equality-preserving + i++; // not required to be + equality-preserving + + }; + + where /*is-signed-integer-like*/ is true if and only if I is a + signed-integer-like type (see below). + + This concept specifies requirements on types that can be incremented with the pre- + and post-increment operators, but those increment operations are not necessarily + equality-preserving, and the type itself is not required to be + std::equality_comparable. + + For std::weakly_incrementable types, a == b does not imply that ++a == ++b. + Algorithms on weakly incrementable types must be single-pass algorithms. These + algorithms can be used with istreams as the source of the input data through + std::istream_iterator. + +.SH See also + + incrementable specifies that the increment operation on a weakly_incrementable type + (C++20) is equality-preserving and that the type is equality_comparable + (concept) diff --git a/man/std::weibull_distribution.3 b/man/std::weibull_distribution.3 index 715ace593..ae1e64b9a 100644 --- a/man/std::weibull_distribution.3 +++ b/man/std::weibull_distribution.3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution \- std::weibull_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -7,7 +10,8 @@ The weibull_distribution meets the requirements of a RandomNumberDistribution and produces random numbers according to the Weibull distribution: - f(x;a,b) = + \\(\\small{f(x;a,b)=\\frac{a}{b}{(\\frac{x}{b})}^{a-1}\\exp{(-{(\\frac{x}{b})}^{a})} + }\\)f(x;a,b) = a b @@ -40,80 +44,91 @@ a is the shape parameter and b the scale parameter. + std::weibull_distribution satisfies RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. + .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics a returns the distribution parameters - b \fI(public member function)\fP + b \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include + #include #include - #include + #include #include #include - #include + #include + int main() { std::random_device rd; std::mt19937 gen(rd()); - + std::weibull_distribution<> d; - + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n = 0; n != 10000; ++n) ++hist[std::round(d(gen))]; - } - for(auto p : hist) { - std::cout << std::fixed << std::setprecision(1) << std::setw(2) - << p.first << ' ' << std::string(p.second/200, '*') << '\\n'; - } + + std::cout << std::fixed << std::setprecision(1) << std::hex; + for (auto [x, y] : hist) + std::cout << x << ' ' << std::string(y / 200, '*') << '\\n'; } -.SH Output: +.SH Possible output: 0 ******************* - 1 ******************* - 2 ****** - 3 ** - 4 - 5 - 6 - 7 - 8 + 1 ******************* + 2 ****** + 3 ** + 4 + 5 + 6 + 7 + 8 .SH External links - * Weisstein, Eric W. "Weibull Distribution." From MathWorld--A Wolfram Web + 1. Weisstein, Eric W. "Weibull Distribution." From MathWorld — A Wolfram Web Resource. - * Weibull distribution. From Wikipedia. + 2. Weibull distribution — From Wikipedia. diff --git a/man/std::weibull_distribution::a,b.3 b/man/std::weibull_distribution::a,b.3 index 0fb9c9e5e..f41255c46 100644 --- a/man/std::weibull_distribution::a,b.3 +++ b/man/std::weibull_distribution::a,b.3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution::a,b 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::a,b 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::a,b \- std::weibull_distribution::a,b + .SH Synopsis RealType a() const; \fB(1)\fP \fI(since C++11)\fP RealType b() const; \fB(2)\fP \fI(since C++11)\fP @@ -25,5 +28,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::weibull_distribution::max.3 b/man/std::weibull_distribution::max.3 index 247d250de..949318b29 100644 --- a/man/std::weibull_distribution::max.3 +++ b/man/std::weibull_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::max \- std::weibull_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::weibull_distribution::min.3 b/man/std::weibull_distribution::min.3 index a11896857..f191d355a 100644 --- a/man/std::weibull_distribution::min.3 +++ b/man/std::weibull_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::min \- std::weibull_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::weibull_distribution::operator().3 b/man/std::weibull_distribution::operator().3 index 601bb9f9f..e54cb2e5c 100644 --- a/man/std::weibull_distribution::operator().3 +++ b/man/std::weibull_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::operator() \- std::weibull_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::weibull_distribution::param.3 b/man/std::weibull_distribution::param.3 index d087af250..ae909571b 100644 --- a/man/std::weibull_distribution::param.3 +++ b/man/std::weibull_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::param \- std::weibull_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::weibull_distribution::reset.3 b/man/std::weibull_distribution::reset.3 index ba95b072d..d3ed43235 100644 --- a/man/std::weibull_distribution::reset.3 +++ b/man/std::weibull_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::weibull_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::reset \- std::weibull_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::weibull_distribution::weibull_distribution.3 b/man/std::weibull_distribution::weibull_distribution.3 index f70d8e950..52600c465 100644 --- a/man/std::weibull_distribution::weibull_distribution.3 +++ b/man/std::weibull_distribution::weibull_distribution.3 @@ -1,15 +1,27 @@ -.TH std::weibull_distribution::weibull_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::weibull_distribution::weibull_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::weibull_distribution::weibull_distribution \- std::weibull_distribution::weibull_distribution + .SH Synopsis - explicit weibull_distribution( RealType a = 1.0, RealType b = 1.0 \fB(1)\fP \fI(since C++11)\fP - ); - explicit weibull_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + weibull_distribution() : weibull_distribution(1.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit weibull_distribution( RealType a, RealType b = 1.0 ); \fB(2)\fP \fI(since C++11)\fP + explicit weibull_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. - Constructs a new distribution object. The first version uses a and b as the - distribution parameters, the second version uses params as the distribution - parameters. + 2) Uses a and b as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters a - the a distribution parameter (shape) b - the b distribution parameter (scale) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::wfilebuf.3 b/man/std::wfilebuf.3 deleted file mode 120000 index a5ce16e09..000000000 --- a/man/std::wfilebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf.3 \ No newline at end of file diff --git a/man/std::wfilebuf.3 b/man/std::wfilebuf.3 new file mode 100644 index 000000000..b456ca49a --- /dev/null +++ b/man/std::wfilebuf.3 @@ -0,0 +1,247 @@ +.TH std::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf \- std::basic_filebuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_filebuf : public std::basic_streambuf + + std::basic_filebuf is a std::basic_streambuf whose associated character sequence is + a file. Both the input sequence and the output sequence are associated with the same + file, and a joint file position is maintained for both operations. The restrictions + on reading and writing a sequence with std::basic_filebuf are the same as + std::FILEs. + + The functions underflow() and overflow() / sync() perform the actual I/O between the + file and the get and put areas of the buffer. When CharT is not char, most + implementations store multibyte characters in the file and a std::codecvt facet is + used to perform wide/multibyte character conversion. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::filebuf std::basic_filebuf + std::wfilebuf std::basic_filebuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type which is required to be + std::fpos + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + +.SH Public member functions + constructor constructs a basic_filebuf object + \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + is_open checks if the associated file is open + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP +.SH Protected member functions + showmanyc optionally provides the number of characters available for input from + \fB[virtual]\fP the file + \fI(virtual protected member function)\fP + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function)\fP + uflow reads from the associated file and advances the next pointer in the + \fB[virtual]\fP get area + \fI(virtual protected member function)\fP + pbackfail backs out the input sequence to unget a character, not affecting the + \fB[virtual]\fP associated file + \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + setbuf provides user-supplied buffer or turns this filebuf unbuffered + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + sync writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Non-member functions + + std::swap(std::basic_filebuf) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) +.SH Locales + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + +.SH Positioning + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + +.SH Putback + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + + +.SH Protected member functions + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Get area + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + eback returns a pointer to the beginning, current character and the end of + gptr the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + pbase returns a pointer to the beginning, current character and the end of + pptr the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH See also + + object type, capable of holding all information needed to control a C I/O + FILE stream + \fI(typedef)\fP diff --git a/man/std::wfilebuf::basic_filebuf.3 b/man/std::wfilebuf::basic_filebuf.3 deleted file mode 120000 index 202c5b9db..000000000 --- a/man/std::wfilebuf::basic_filebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::basic_filebuf.3 \ No newline at end of file diff --git a/man/std::wfilebuf::basic_filebuf.3 b/man/std::wfilebuf::basic_filebuf.3 new file mode 100644 index 000000000..1c84686c4 --- /dev/null +++ b/man/std::wfilebuf::basic_filebuf.3 @@ -0,0 +1,44 @@ +.TH std::basic_filebuf::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::basic_filebuf \- std::basic_filebuf::basic_filebuf + +.SH Synopsis + basic_filebuf(); \fB(1)\fP + basic_filebuf( const std::basic_filebuf& rhs ) = delete; \fB(2)\fP \fI(since C++11)\fP + basic_filebuf( std::basic_filebuf&& rhs ); \fB(3)\fP \fI(since C++11)\fP + + Constructs new std::basic_filebuf object. + + 1) Constructs a std::basic_filebuf object, initializing the base class by calling + the default constructor of std::basic_streambuf. The created basic_filebuf is not + associated with a file, and is_open() returns false. + 2) The copy constructor is deleted; std::basic_filebuf is not CopyConstructible. + 3) Move-constructs a std::basic_filebuf object by moving all contents from another + std::basic_filebuf object rhs, including the buffers, the associated file, the + locale, the openmode, the is_open variable, and all other state. After move, rhs is + not associated with a file and rhs.is_open() == false. The member pointers of the + base class std::basic_streambuf of rhs and of the base class of *this are guaranteed + to point to different buffers (unless null). + +.SH Parameters + + rhs - another basic_filebuf + +.SH Notes + + Typically called by the constructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::close.3 b/man/std::wfilebuf::close.3 deleted file mode 120000 index db60d7b11..000000000 --- a/man/std::wfilebuf::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::close.3 \ No newline at end of file diff --git a/man/std::wfilebuf::close.3 b/man/std::wfilebuf::close.3 new file mode 100644 index 000000000..7126ff40d --- /dev/null +++ b/man/std::wfilebuf::close.3 @@ -0,0 +1,66 @@ +.TH std::basic_filebuf::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::close \- std::basic_filebuf::close + +.SH Synopsis + std::basic_filebuf* close(); + + If a put area exist (e.g. file was opened for writing), first calls + overflow(Traits::eof()) to write all pending output to the file, including any + unshift sequences. + + If the most recently called function, out of underflow(), overflow(), seekpos(), and + seekoff(), was overflow(), then calls std::codecvt::unshift(), perhaps multiple + times, to determine the unshift sequence according to the imbued locale, and writes + that sequence to file with overflow(Traits::eof()). + + Then, closes the file as if by calling std::fclose(), regardless of whether any of + the preceding calls succeeded or failed. + + If any of the function calls made, including the call to std::fclose(), fails, + returns a null pointer. If any of the function calls made throws an exception, the + exception is caught and rethrown after closing the file. If the file is already + closed, returns a null pointer right away. + + In any case, updates the private member variable that is accessed by is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + this on success, a null pointer on failure. + +.SH Notes + + close() is typically called through the destructor of std::basic_filebuf (which, in + turn, is typically called by the destructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 443 C++98 the file was written using changed to overflow(Traits::eof()) + overflow(EOF) + it was unclear how to handle + LWG 622 C++98 the it is rethrown after closing the + exception thrown during file + closing + +.SH See also + + is_open checks if the associated file is open + \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::imbue.3 b/man/std::wfilebuf::imbue.3 deleted file mode 120000 index 79eaa84b5..000000000 --- a/man/std::wfilebuf::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::imbue.3 \ No newline at end of file diff --git a/man/std::wfilebuf::imbue.3 b/man/std::wfilebuf::imbue.3 new file mode 100644 index 000000000..d0aad8e7b --- /dev/null +++ b/man/std::wfilebuf::imbue.3 @@ -0,0 +1,39 @@ +.TH std::basic_filebuf::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::imbue \- std::basic_filebuf::imbue + +.SH Synopsis + protected: + virtual void imbue( const std::locale& loc ) + + Changes the associated locale so that all characters inserted or extracted after + this call (and until another call to imbue()) are converted using the std::codecvt + facet of loc. + + If the old locale's encoding is state-dependent and file is not positioned at the + beginning, then the new locale must have the same std::codecvt facet as the one + previously imbued. + +.SH Parameters + + loc - the locale to imbue the stream with + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::is_open.3 b/man/std::wfilebuf::is_open.3 deleted file mode 120000 index 387eb1c16..000000000 --- a/man/std::wfilebuf::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::is_open.3 \ No newline at end of file diff --git a/man/std::wfilebuf::is_open.3 b/man/std::wfilebuf::is_open.3 new file mode 100644 index 000000000..e8cefa70c --- /dev/null +++ b/man/std::wfilebuf::is_open.3 @@ -0,0 +1,53 @@ +.TH std::basic_filebuf::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::is_open \- std::basic_filebuf::is_open + +.SH Synopsis + bool is_open() const; + + Returns true if the most recent call to open() succeeded and there has been no call + to close() since then. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the associated file is open, false otherwise. + +.SH Notes + + This function is typically called by std::basic_fstream::is_open(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ifstream fs("test.txt"); + std::filebuf fb; + fb.open("test.txt", std::ios_base::in); + std::cout << std::boolalpha + << "direct call: " << fb.is_open() << '\\n' + << "through streambuf: " << fs.rdbuf()->is_open() << '\\n' + << "through fstream: " << fs.is_open() << '\\n'; + } + +.SH Output: + + direct call: true + through streambuf: true + through fstream: true + +.SH See also + + open opens a file and configures it as the associated character sequence + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP diff --git a/man/std::wfilebuf::native_handle.3 b/man/std::wfilebuf::native_handle.3 new file mode 100644 index 000000000..43544dbf7 --- /dev/null +++ b/man/std::wfilebuf::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_filebuf::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::native_handle \- std::basic_filebuf::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with *this. The + behavior is undefined if is_open() is false. + +.SH Return value + + implementation defined handle. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::wfilebuf::open.3 b/man/std::wfilebuf::open.3 deleted file mode 120000 index 83b9deb43..000000000 --- a/man/std::wfilebuf::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::open.3 \ No newline at end of file diff --git a/man/std::wfilebuf::open.3 b/man/std::wfilebuf::open.3 new file mode 100644 index 000000000..384c0b7ed --- /dev/null +++ b/man/std::wfilebuf::open.3 @@ -0,0 +1,134 @@ +.TH std::basic_filebuf::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::open \- std::basic_filebuf::open + +.SH Synopsis + basic_filebuf* open( const char* s, std::ios_base::openmode mode \fB(1)\fP + ); + basic_filebuf* open( const std::string& str, \fB(2)\fP \fI(since C++11)\fP + std::ios_base::openmode mode ); + basic_filebuf* open( const std::filesystem::path& p, \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode ); + basic_filebuf* open( const std::filesystem::path::value_type* s, \fB(4)\fP \fI(since C++17)\fP + std::ios_base::openmode mode ); + + If the associated file was already open (is_open() != false), returns a null pointer + right away. + + Otherwise, opens the file with the given name (s + , p.c_str() + \fI(since C++17)\fP or str.c_str(), depending on the overload). std::ios_base::openmode + values may be written as, e.g., std::ios_base::out | std::ios_base::app. + + Overload \fB(4)\fP is only provided if std::filesystem::path::value_type is \fI(since C++17)\fP + not char. + + The file is opened as if by calling std::fopen with the second argument (file access + mode) determined by the result of mode & ~std::ios_base::ate as follows, open() + fails if the result is not some combination of flags shown in the table: + + mode & ~std::ios_base::ate  std::fopen  Action if file Action if file + binary in out trunc app noreplace access already exists does not exist + (since C++23) mode + - + - - - - "r" Failure to + + + - - - - "rb" Read from start open + - + + - - - "r+" Error + + + + - - - "r+b" + - - + - - - "w" + - - + + - - + + - + - - - "wb" Destroy contents Create new + + - + + - - + - + + + - - "w+" + + + + + - - "w+b" + - - + - - + "wx" + - - + + - + + + - + - - + "wbx" Failure to open Create new + + - + + - + + - + + + - + "w+x" + + + + + - + "w+bx" + - - + - + - "a" + - - - - + - + + - + - + - "ab" + + - - - + - Write to end Create new + - + + - + - "a+" + - + - - + - + + + + - + - "a+b" + + + - - + - + + If the open operation succeeds and (openmode & std::ios_base::ate) != 0 (the ate bit + is set), repositions the file position to the end of file, as if by calling + std::fseek(file, 0, SEEK_END), where file is the pointer returned by calling + std::fopen. If the repositioning fails, calls close() and returns a null pointer to + indicate failure. + +.SH Parameters + + s, str, p - the file name to open; s must point to a null-terminated string + openmode - the file opening mode, a binary OR of the std::ios_base::openmode modes + +.SH Return value + + this on success, a null pointer on failure. + +.SH Notes + + open() is typically called through the constructor or the open() member function of + std::basic_fstream. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string filename = "Test.b"; + std::filebuf fb; + + // prepare a file to read + double d = 3.14; + if (!fb.open(filename, std::ios::binary | std::ios::out)) + { + std::cout << "Open file " << filename << " for write failed\\n"; + return 1; + } + fb.sputn(reinterpret_cast(&d), sizeof d); + fb.close(); + + // open file for reading + double d2 = 0.0; + if (!fb.open(filename, std::ios::binary | std::ios::in)) + { + std::cout << "Open file " << filename << " for read failed\\n"; + return 1; + } + + auto got = fb.sgetn(reinterpret_cast(&d2), sizeof d2); + if (sizeof(d2) != got) + std::cout << "Read of " << filename << " failed\\n"; + else + std::cout << "Read back from file: " << d2 << '\\n'; + } + +.SH Output: + + Read back from file: 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 596 C++98 open() could not open files in append can open in append mode + mode + +.SH See also + + is_open checks if the associated file is open + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP diff --git a/man/std::wfilebuf::operator=.3 b/man/std::wfilebuf::operator=.3 deleted file mode 120000 index d9f13e533..000000000 --- a/man/std::wfilebuf::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::operator=.3 \ No newline at end of file diff --git a/man/std::wfilebuf::operator=.3 b/man/std::wfilebuf::operator=.3 new file mode 100644 index 000000000..a0532ed24 --- /dev/null +++ b/man/std::wfilebuf::operator=.3 @@ -0,0 +1,64 @@ +.TH std::basic_filebuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::operator= \- std::basic_filebuf::operator= + +.SH Synopsis + std::basic_filebuf& operator=( std::basic_filebuf&& rhs ); \fB(1)\fP \fI(since C++11)\fP + std::basic_filebuf& operator=( const std::basic_filebuf& rhs ) = \fB(2)\fP + delete; + + Assigns another basic_filebuf object. + + 1) First calls close() to close the associated file, then moves the contents of rhs + into *this: the put and get buffers, the associated file, the locale, the openmode, + the is_open flag, and any other state. After the move, rhs is not associated with a + file and rhs.is_open() == false. + 2) The copy assignment operator is deleted; basic_filebuf is not CopyAssignable. + +.SH Parameters + + rhs - another basic_filebuf that will be moved from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ofstream{"test.in"} << "test\\n"; // writes via a temporary object + std::ifstream fin("test.in"); // read-only stream + std::ofstream fout("test.out"); // write-only stream + + std::string s; + std::getline(fin, s); + std::cout << "s = [" << s << "]\\n"; // s contains "test" + + assert(fout.is_open()); + *fin.rdbuf() = std::move(*fout.rdbuf()); + assert(!fout.is_open()); + + std::getline(fin, s); + std::cout << "s = [" << s << "]\\n"; // s is empty input + } + +.SH Output: + + s = [test] + s = [] + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::wfilebuf::overflow.3 b/man/std::wfilebuf::overflow.3 deleted file mode 120000 index d0686b770..000000000 --- a/man/std::wfilebuf::overflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::overflow.3 \ No newline at end of file diff --git a/man/std::wfilebuf::overflow.3 b/man/std::wfilebuf::overflow.3 new file mode 100644 index 000000000..4136ce654 --- /dev/null +++ b/man/std::wfilebuf::overflow.3 @@ -0,0 +1,49 @@ +.TH std::basic_filebuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::overflow \- std::basic_filebuf::overflow + +.SH Synopsis + protected: + virtual int_type overflow ( int_type c = Traits::eof() ); + + Writes some data from the put area to the associated character sequence (to the + file). + + Behaves like the base class std::basic_streambuf::overflow, except that to write the + data, first uses std::codecvt::out of the imbued locale to convert the characters + into external (possibly multibyte) representation, stored in a temporary buffer + (allocated as large as necessary), then uses file I/O to copy all fully-converted + bytes into the file. + + If std::codecvt::always_noconv is true, the call to std::codecvt::out may be + skipped. + + If the conversion fails with std::codecvt_base::error, returns Traits::eof() without + attempting any output. + + If the associated file is not open (is_open() == false), returns Traits::eof() + before doing anything. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Traits::not_eof(c) to indicate success or Traits::eof() to indicate failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::pbackfail.3 b/man/std::wfilebuf::pbackfail.3 deleted file mode 120000 index 952f18032..000000000 --- a/man/std::wfilebuf::pbackfail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::pbackfail.3 \ No newline at end of file diff --git a/man/std::wfilebuf::pbackfail.3 b/man/std::wfilebuf::pbackfail.3 new file mode 100644 index 000000000..6fde947cd --- /dev/null +++ b/man/std::wfilebuf::pbackfail.3 @@ -0,0 +1,67 @@ +.TH std::basic_filebuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::pbackfail \- std::basic_filebuf::pbackfail + +.SH Synopsis + protected: + virtual int_type pbackfail( int_type c = Traits::eof() ) + + This protected virtual function is called by the public functions + basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called + by basic_istream::unget and basic_istream::putback). + + 1) The caller is requesting that the get area is backed up by one character + (pbackfail() is called with no arguments), in which case, this function re-reads the + file starting one byte earlier and decrements basic_streambuf::gptr(), e.g. by + calling gbump(-1). + 2) The caller attempts to putback a different character from the one retrieved + earlier (pbackfail() is called with the character that needs to be put back), in + which case + a) First, checks if there is a putback position, and if there isn't, backs up the + get area by re-reading the file starting one byte earlier. + a) Then checks what character is in the putback position. If the character held + there is already equal to c, as determined by Traits::eq(to_char_type(c), + gptr()[-1]), then simply decrements basic_streambuf::gptr(). + b) Otherwise, if the buffer is allowed to modify its own get area, decrements + basic_streambuf::gptr() and writes c to the location pointed to gptr() after + adjustment. + + This function never modifies the file, only the get area of the in-memory buffer. + + If the file is not open (is_open()==false, this function returns Traits::eof() + immediately. + +.SH Parameters + + c - the character to put back, or Traits::eof() to indicate that backing up of the + get area is requested + +.SH Return value + + c on success except if c was Traits::eof(), in which case Traits::not_eof(c) is + returned. + + Traits::eof() on failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function of std::basic_streambuf)\fP + sputbackc puts one character back in the input sequence + \fI(public member function of std::basic_streambuf)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::seekoff.3 b/man/std::wfilebuf::seekoff.3 deleted file mode 120000 index fe8922894..000000000 --- a/man/std::wfilebuf::seekoff.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::seekoff.3 \ No newline at end of file diff --git a/man/std::wfilebuf::seekoff.3 b/man/std::wfilebuf::seekoff.3 new file mode 100644 index 000000000..2ce6f772b --- /dev/null +++ b/man/std::wfilebuf::seekoff.3 @@ -0,0 +1,141 @@ +.TH std::basic_filebuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::seekoff \- std::basic_filebuf::seekoff + +.SH Synopsis + protected: + + virtual pos_type seekoff( off_type off, + std::ios_base::seekdir dir, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions the file pointer, if possible, to the position that corresponds to + exactly off characters from beginning, end, or current position of the file + (depending on the value of dir). + + If the associated file is not open (is_open() == false), fails immediately. + + If the multibyte character encoding is state-dependent (codecvt::encoding() returned + -1) or variable-length (codecvt::encoding() returned 0) and the offset off is not 0, + fails immediately: this function cannot determine the number of bytes that + correspond to off characters. + + If dir is not std::basic_ios::cur or the offset off is not 0, and the most recent + operation done on this filebuf object was output (that is, either the put buffer is + not empty, or the most recently called function was overflow()), then calls + std::codecvt::unshift to determine the unshift sequence necessary, and writes that + sequence to the file by calling overflow(). + + Then converts the argument dir to a value whence of type int as follows: + + value of dir value of whence + std::basic_ios::beg SEEK_SET + std::basic_ios::end SEEK_END + std::basic_ios::cur SEEK_CUR + + Then, if the character encoding is fixed-width (codecvt::encoding() returns some + positive number width), moves the file pointer as if by std::fseek(file, width*off, + whence). + + Otherwise, moves the file pointer as if by std::fseek(file, 0, whence). + + The openmode argument, required by the base class function signature, is usually + ignored, because std::basic_filebuf maintains only one file position. + +.SH Parameters + + off - relative position to set the position indicator to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + A newly constructed object of type pos_type which stores the resulting file + position, or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekoff() is called by std::basic_streambuf::pubseekoff, which is called by + std::basic_istream::seekg, std::basic_ostream::seekp, std::basic_istream::tellg, and + std::basic_ostream::tellp. + +.SH Example + + +// Run this code + + #include + #include + #include + + template + int get_encoding(const std::basic_istream& stream) + { + using Facet = std::codecvt; + return std::use_facet(stream.getloc()).encoding(); + } + + int main() + { + // prepare a 10-byte file holding 4 characters ("zß水𝄋") in UTF-8 + std::ofstream("text.txt") << "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + + // open using a non-converting encoding + std::ifstream f1("text.txt"); + std::cout << "f1's locale's encoding() returns " + << get_encoding(f1) << '\\n' + << "pubseekoff(3, beg) returns " + << f1.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' + << "pubseekoff(0, end) returns " + << f1.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; + + // open using UTF-8 + std::wifstream f2("text.txt"); + f2.imbue(std::locale("en_US.UTF-8")); + std::cout << "f2's locale's encoding() returns " + << get_encoding(f2) << '\\n' + << "pubseekoff(3, beg) returns " + << f2.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\\n' + << "pubseekoff(0, end) returns " + << f2.rdbuf()->pubseekoff(0, std::ios_base::end) << '\\n'; + } + +.SH Output: + + f1's locale's encoding() returns 1 + pubseekoff(3, beg) returns 3 + pubseekoff(0, end) returns 10 + f2's locale's encoding() returns 0 + pubseekoff(3, beg) returns -1 + pubseekoff(0, end) returns 10 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + fseek moves the file position indicator to a specific location in a file + \fI(function)\fP diff --git a/man/std::wfilebuf::seekpos.3 b/man/std::wfilebuf::seekpos.3 deleted file mode 120000 index 4364ae51f..000000000 --- a/man/std::wfilebuf::seekpos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::seekpos.3 \ No newline at end of file diff --git a/man/std::wfilebuf::seekpos.3 b/man/std::wfilebuf::seekpos.3 new file mode 100644 index 000000000..8996817bc --- /dev/null +++ b/man/std::wfilebuf::seekpos.3 @@ -0,0 +1,118 @@ +.TH std::basic_filebuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::seekpos \- std::basic_filebuf::seekpos + +.SH Synopsis + protected: + + virtual pos_type seekpos( pos_type sp, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions the file pointer, if possible, to the position indicated by sp. If the + associated file is not open (is_open() == false), fails immediately. + + Reposition performs as follows: + + 1) If the file is open for writing, writes the put area and any unshift sequences + required by the currently imbued locale, using overflow(). + 2) Repositions the file pointer, as if by calling std::fsetpos(). + 3) If the file is open for reading, updates the get area if necessary. + + If sp was not obtained by calling seekoff() or seekpos() on the same file, the + behavior is undefined. + +.SH Parameters + + sp - file position obtained by seekoff() or seekpos() called earlier on the same + file + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + sp on success or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the + single-argument versions of std::basic_istream::seekg() and + std::basic_ostream::seekp(). + + Many implementations do not update the get area in seekpos(), delegating to + underflow() that is called by the next sgetc(). + +.SH Example + + On some implementations, the get area is emptied by seekpos() and the second + underflow() is necessary to observe the effects. + + +// Run this code + + #include + #include + + struct mybuf : std::filebuf + { + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::filebuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + // uncomment if get area is emptied by seekpos() + // std::filebuf::underflow(); + // std::cout << "after forced underflow(), size of the get area is " + // << egptr() - eback() << " with " + // << egptr() - gptr() << " read positions available.\\n"; + + return rc; + } + }; + + int main() + { + mybuf buf; + buf.open("test.txt", std::ios_base::in); + std::istream stream(&buf); + stream.get(); // read one char to force underflow() + stream.seekg(2); + } + +.SH Possible output: + + Before seekpos\fB(2)\fP, size of the get area is 110 with 109 read positions available. + seekpos() returns 2. + After the call, size of the get area is 110 with 108 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekpos returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + LWG 171 C++98 the sequence of the operations of made clear + reposition was not clear + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function)\fP + fseek moves the file position indicator to a specific location in a file + \fI(function)\fP diff --git a/man/std::wfilebuf::setbuf.3 b/man/std::wfilebuf::setbuf.3 deleted file mode 120000 index afcf8b009..000000000 --- a/man/std::wfilebuf::setbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::setbuf.3 \ No newline at end of file diff --git a/man/std::wfilebuf::setbuf.3 b/man/std::wfilebuf::setbuf.3 new file mode 100644 index 000000000..1f795b151 --- /dev/null +++ b/man/std::wfilebuf::setbuf.3 @@ -0,0 +1,97 @@ +.TH std::basic_filebuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::setbuf \- std::basic_filebuf::setbuf + +.SH Synopsis + protected: + virtual std::basic_streambuf* setbuf( char_type* s, std::streamsize + n ) + + If s is a null pointer and n is zero, the filebuf becomes unbuffered for output, + meaning pbase() and pptr() are null and any output is immediately sent to file. + + Otherwise, a call to setbuf() replaces the internal buffer (the controlled character + sequence) with the user-supplied character array whose first element is pointed to + by s and allows this std::basic_filebuf object to use up to n bytes in that array + for buffering. + + This function is protected virtual, it may only be called through pubsetbuf() or + from member functions of a user-defined class derived from std::basic_filebuf. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer or null + n - the number of CharT elements in the user-provided buffer or zero + +.SH Return value + + this + +.SH Notes + + The conditions when this function may be used and the way in which the provided + buffer is used is implementation-defined. + + * GCC 4.6 libstdc++ + + setbuf() may only be called when the std::basic_filebuf is not associated with a + file (has no effect otherwise). With a user-provided buffer, reading from file reads + n-1 bytes at a time. + * Clang++3.0 libc++ + + setbuf() may be called after opening the file, but before any I/O (may crash + otherwise). With a user-provided buffer, reading from file reads largest multiples + of 4096 that fit in the buffer. + * Visual Studio 2010 + + setbuf() may be called at any time, even after some I/O took place. Current contents + of the buffer, if any, are lost. + + The standard does not define any behavior for this function except that setbuf(0, 0) + called before any I/O has taken place is required to set unbuffered output. + +.SH Example + + Provides a 10k buffer for reading. On linux, the strace utility may be used to + observe the actual number of bytes read. + + +// Run this code + + #include + #include + #include + + int main() + { + int cnt = 0; + std::ifstream file; + char buf[10241]; + + file.rdbuf()->pubsetbuf(buf, sizeof buf); + file.open("/usr/share/dict/words"); + + for (std::string line; getline(file, line);) + ++cnt; + std::cout << cnt << '\\n'; + } + +.SH Possible output: + + 356010 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 173 C++98 the type of n was misspecified as corrected to std::streamsize + int + +.SH See also + + pubsetbuf invokes setbuf() + \fI(public member function of std::basic_streambuf)\fP + setvbuf sets the buffer and its size for a file stream + \fI(function)\fP diff --git a/man/std::wfilebuf::showmanyc.3 b/man/std::wfilebuf::showmanyc.3 deleted file mode 120000 index 9031dd00d..000000000 --- a/man/std::wfilebuf::showmanyc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::showmanyc.3 \ No newline at end of file diff --git a/man/std::wfilebuf::showmanyc.3 b/man/std::wfilebuf::showmanyc.3 new file mode 100644 index 000000000..5bee45bae --- /dev/null +++ b/man/std::wfilebuf::showmanyc.3 @@ -0,0 +1,62 @@ +.TH std::basic_filebuf::showmanyc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::showmanyc \- std::basic_filebuf::showmanyc + +.SH Synopsis + protected: + virtual std::streamsize showmanyc() + + If implemented, returns the number of characters left to read from the file. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters available for reading from the file, or -1 if the end of + file was reached. + +.SH Notes + + This function is optional. If not implemented, this function returns 0 (since the + base class version std::basic_streambuf::showmanyc gets called) + + Whether implemented or not, this function is normally called by + std::basic_streambuf::in_avail if the get area is empty. + + The name of this function stands for "stream: how many characters?", so it is + pronounced "S how many C", rather than "show many C" + +.SH Example + + implementation test to see if showmanyc() is implemented for filebuf + + +// Run this code + + #include + #include + + struct mybuf : std::filebuf + { + using std::filebuf::showmanyc; + }; + + int main() + { + mybuf fin; + fin.open("main.cpp", std::ios_base::in); + std::cout << "showmanyc() returns " << fin.showmanyc() << '\\n'; + } + +.SH Possible output: + + showmanyc() returns 267 + +.SH See also + + in_avail obtains the number of characters immediately available in the get area + \fI(public member function of std::basic_streambuf)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wfilebuf::swap.3 b/man/std::wfilebuf::swap.3 deleted file mode 120000 index 4ab9bb9ee..000000000 --- a/man/std::wfilebuf::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::swap.3 \ No newline at end of file diff --git a/man/std::wfilebuf::swap.3 b/man/std::wfilebuf::swap.3 new file mode 100644 index 000000000..cae59ea19 --- /dev/null +++ b/man/std::wfilebuf::swap.3 @@ -0,0 +1,55 @@ +.TH std::basic_filebuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::swap \- std::basic_filebuf::swap + +.SH Synopsis + void swap( std::basic_filebuf& rhs ); \fI(since C++11)\fP + + Swaps the state and the contents of *this and rhs. + +.SH Parameters + + rhs - another basic_filebuf + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called automatically when swapping std::fstream objects, it is + rarely necessary to call it directly. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream fin("test.in"); // read-only + std::ofstream fout("test.out"); // write-only + + std::string s; + getline(fin, s); + std::cout << s << '\\n'; // outputs the first line of test.in + + fin.rdbuf()->swap(*fout.rdbuf()); //swap the underlying buffers + + getline(fin, s); // fails: cannot read from a write-only filebuf + std::cout << s << '\\n'; // prints empty line + } + +.SH See also + + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + std::swap(std::basic_filebuf) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + swap swaps two file streams + \fI(C++11)\fP \fI\fI(public member\fP function of\fP + std::basic_fstream) diff --git a/man/std::wfilebuf::sync.3 b/man/std::wfilebuf::sync.3 deleted file mode 120000 index 640a566a2..000000000 --- a/man/std::wfilebuf::sync.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::sync.3 \ No newline at end of file diff --git a/man/std::wfilebuf::sync.3 b/man/std::wfilebuf::sync.3 new file mode 100644 index 000000000..f32ce2eaf --- /dev/null +++ b/man/std::wfilebuf::sync.3 @@ -0,0 +1,43 @@ +.TH std::basic_filebuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::sync \- std::basic_filebuf::sync + +.SH Synopsis + protected: + virtual int sync() + + If a put area exists (e.g. the file was opened for writing), calls overflow() to + write all pending output to the file, then flushes the file as if by calling + std::fflush. + + If a get area exists (e.g. the file was opened for reading), the effect is + implementation-defined. Typical implementation may empty out the get area and move + the current file position back by the corresponding number of bytes. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 0 in case of success, -1 in case of failure. + +.SH Notes + + sync() or its equivalent is implicitly called for output streams by close(), + seekoff(), and seekpos() and explicitly called by std::basic_streambuf::pubsync() + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pubsync invokes sync() + \fI(public member function of std::basic_streambuf)\fP + fflush synchronizes an output stream with the actual file + \fI(function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::uflow.3 b/man/std::wfilebuf::uflow.3 deleted file mode 120000 index f77660456..000000000 --- a/man/std::wfilebuf::uflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::uflow.3 \ No newline at end of file diff --git a/man/std::wfilebuf::uflow.3 b/man/std::wfilebuf::uflow.3 new file mode 100644 index 000000000..299084c3e --- /dev/null +++ b/man/std::wfilebuf::uflow.3 @@ -0,0 +1,39 @@ +.TH std::basic_filebuf::uflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::uflow \- std::basic_filebuf::uflow + +.SH Synopsis + protected: + virtual int_type uflow() + + Behaves like the underflow(), except that if underflow() succeeds (does not return + Traits::eof()), then advances the next pointer for the get area. In other words, + consumes one of the characters obtained by underflow(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character that was read and consumed in case of success, or + Traits::eof() in case of failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + reads characters from the associated input sequence to the get area and + uflow advances the next pointer + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::underflow.3 b/man/std::wfilebuf::underflow.3 deleted file mode 120000 index c24e46aa6..000000000 --- a/man/std::wfilebuf::underflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::underflow.3 \ No newline at end of file diff --git a/man/std::wfilebuf::underflow.3 b/man/std::wfilebuf::underflow.3 new file mode 100644 index 000000000..7dc11e56a --- /dev/null +++ b/man/std::wfilebuf::underflow.3 @@ -0,0 +1,86 @@ +.TH std::basic_filebuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::underflow \- std::basic_filebuf::underflow + +.SH Synopsis + protected: + virtual int_type underflow() + + Reads more data into the input area. + + Behaves like the base class std::basic_streambuf::underflow, except that to read the + data from the associated character sequence (the file) into the get area, first + reads the bytes from the file into a temporary buffer (allocated as large as + necessary), then uses std::codecvt::in of the imbued locale to convert the external + (typically, multibyte) representation to the internal form which is then used to + populate the get area. The conversion may be skipped if the locale's + std::codecvt::always_noconv returns true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Traits::to_int_type(*gptr()) (the first character of the pending sequence) in case + of success, or Traits::eof() in case of failure. + +.SH Example + + +// Run this code + + #include + #include + + struct mybuf : std::filebuf + { + int underflow() + { + std::cout << "Before underflow(): size of the get area is " + << egptr()-eback() << " with " + << egptr()-gptr() << " read positions available\\n"; + int rc = std::filebuf::underflow(); + std::cout << "underflow() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr()-eback() << " with " + << egptr()-gptr() << " read positions available\\n"; + return rc; + } + }; + + int main() + { + mybuf buf; + buf.open("test.txt", std::ios_base::in); + std::istream stream(&buf); + while (stream.get()) ; + } + +.SH Possible output: + + Before underflow(): size of the get area is 0 with 0 read positions available + underflow() returns 73. + After the call, size of the get area is 110 with 110 read positions available + Before underflow(): size of the get area is 110 with 0 read positions available + underflow() returns -1. + After the call, size of the get area is 0 with 0 read positions available + +.SH See also + + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + underflow reads a character from the input sequence without advancing the next + \fB[virtual]\fP pointer + \fI(virtual protected member function of std::strstreambuf)\fP + uflow reads from the associated file and advances the next pointer in the get + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::wfilebuf::wfilebuf.3 b/man/std::wfilebuf::wfilebuf.3 deleted file mode 120000 index 202c5b9db..000000000 --- a/man/std::wfilebuf::wfilebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::basic_filebuf.3 \ No newline at end of file diff --git a/man/std::wfilebuf::wfilebuf.3 b/man/std::wfilebuf::wfilebuf.3 new file mode 100644 index 000000000..1c84686c4 --- /dev/null +++ b/man/std::wfilebuf::wfilebuf.3 @@ -0,0 +1,44 @@ +.TH std::basic_filebuf::basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::basic_filebuf \- std::basic_filebuf::basic_filebuf + +.SH Synopsis + basic_filebuf(); \fB(1)\fP + basic_filebuf( const std::basic_filebuf& rhs ) = delete; \fB(2)\fP \fI(since C++11)\fP + basic_filebuf( std::basic_filebuf&& rhs ); \fB(3)\fP \fI(since C++11)\fP + + Constructs new std::basic_filebuf object. + + 1) Constructs a std::basic_filebuf object, initializing the base class by calling + the default constructor of std::basic_streambuf. The created basic_filebuf is not + associated with a file, and is_open() returns false. + 2) The copy constructor is deleted; std::basic_filebuf is not CopyConstructible. + 3) Move-constructs a std::basic_filebuf object by moving all contents from another + std::basic_filebuf object rhs, including the buffers, the associated file, the + locale, the openmode, the is_open variable, and all other state. After move, rhs is + not associated with a file and rhs.is_open() == false. The member pointers of the + base class std::basic_streambuf of rhs and of the base class of *this are guaranteed + to point to different buffers (unless null). + +.SH Parameters + + rhs - another basic_filebuf + +.SH Notes + + Typically called by the constructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function)\fP + destructor destructs a basic_filebuf object and closes the file if it is open + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfilebuf::~basic_filebuf.3 b/man/std::wfilebuf::~basic_filebuf.3 deleted file mode 120000 index 571377e96..000000000 --- a/man/std::wfilebuf::~basic_filebuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_filebuf::~basic_filebuf.3 \ No newline at end of file diff --git a/man/std::wfilebuf::~basic_filebuf.3 b/man/std::wfilebuf::~basic_filebuf.3 new file mode 100644 index 000000000..788f635a4 --- /dev/null +++ b/man/std::wfilebuf::~basic_filebuf.3 @@ -0,0 +1,47 @@ +.TH std::basic_filebuf::~basic_filebuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_filebuf::~basic_filebuf \- std::basic_filebuf::~basic_filebuf + +.SH Synopsis + + virtual ~basic_filebuf(); + + Calls close() to close the associated file and destructs all other members of + basic_filebuf. If an exception occurs during the destruction of the object, + including the call to close(), it is caught and not rethrown. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Typically called by the destructor of std::basic_fstream. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 622 C++98 it was unclear how to handle the exception it is caught but not + thrown during destruction rethrown + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfstream.3 b/man/std::wfstream.3 deleted file mode 120000 index 47d3c081d..000000000 --- a/man/std::wfstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream.3 \ No newline at end of file diff --git a/man/std::wfstream.3 b/man/std::wfstream.3 new file mode 100644 index 000000000..1cf5a4b01 --- /dev/null +++ b/man/std::wfstream.3 @@ -0,0 +1,366 @@ +.TH std::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream \- std::basic_fstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_fstream : public std::basic_iostream + + The class template basic_fstream implements high-level input/output operations on + file based streams. It interfaces a file-based streambuffer (std::basic_filebuf) + with the high-level interface of (std::basic_iostream). + + A typical implementation of std::basic_fstream holds only one non-derived data + member: an instance of std::basic_filebuf. + + std-basic fstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::fstream std::basic_fstream + std::wfstream std::basic_fstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + + constructor constructs the file stream + \fI(public member function)\fP + destructor destructs the basic_fstream and the associated + \fB[virtual]\fP (implicitly declared) buffer, closes the file + \fI(virtual public member function)\fP + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw file device object + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP +.SH File operations + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_fstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename{"test.bin"}; + std::fstream s{filename, s.binary | s.trunc | s.in | s.out}; + + if (!s.is_open()) + std::cout << "failed to open " << filename << '\\n'; + else + { + // write + double d{3.14}; + s.write(reinterpret_cast(&d), sizeof d); // binary output + s << 123 << "abc"; // text output + + // for fstream, this moves the file position pointer (both put and get) + s.seekp(0); + + // read + d = 2.71828; + s.read(reinterpret_cast(&d), sizeof d); // binary input + int n; + std::string str; + if (s >> n >> str) // text input + std::cout << "read back from file: " << d << ' ' << n << ' ' << str << '\\n'; + } + } + +.SH Output: + + read back from file: 3.14 123 abc + +.SH See also + + getline read data from an I/O stream into a string + \fI(function template)\fP diff --git a/man/std::wfstream::basic_fstream.3 b/man/std::wfstream::basic_fstream.3 deleted file mode 120000 index 4401b4547..000000000 --- a/man/std::wfstream::basic_fstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::basic_fstream.3 \ No newline at end of file diff --git a/man/std::wfstream::basic_fstream.3 b/man/std::wfstream::basic_fstream.3 new file mode 100644 index 000000000..d3641c529 --- /dev/null +++ b/man/std::wfstream::basic_fstream.3 @@ -0,0 +1,111 @@ +.TH std::basic_fstream::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::basic_fstream \- std::basic_fstream::basic_fstream + +.SH Synopsis + basic_fstream(); \fB(1)\fP + explicit basic_fstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::filesystem::path::value_type* + filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in | + std::ios_base::out ); + template< class FsPath > + + explicit basic_fstream( const FsPath& filename, + std::ios_base::openmode mode \fB(5)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + basic_fstream( basic_fstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_fstream( const basic_fstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_fstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::fstream f0; + std::fstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::fstream f2(name); + std::fstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default argument of mode in overload + LWG 460 C++98 (2) added + was missing (it is present in the synopsis) + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_iostream)\fP diff --git a/man/std::wfstream::close.3 b/man/std::wfstream::close.3 deleted file mode 120000 index f7405b513..000000000 --- a/man/std::wfstream::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::close.3 \ No newline at end of file diff --git a/man/std::wfstream::close.3 b/man/std::wfstream::close.3 new file mode 100644 index 000000000..8b47101e3 --- /dev/null +++ b/man/std::wfstream::close.3 @@ -0,0 +1,70 @@ +.TH std::basic_fstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::close \- std::basic_fstream::close + +.SH Synopsis + void close(); + + Closes the associated file. + + Effectively calls rdbuf()->close(). If an error occurs during operation, + setstate(failbit) is called. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called by the destructor of basic_fstream when the stream object + goes out of scope and is not usually invoked directly. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::fstream f1("example1", std::ios::out), + f2("example2", std::ios::out), + f3("example3", std::ios::out); + + std::cout << std::boolalpha + << f1.is_open() << '\\n' + << f2.is_open() << '\\n' + << f3.is_open() << '\\n'; + + f1.close(); + f2.close(); + + std::cout << f1.is_open() << '\\n' + << f2.is_open() << '\\n' + << f3.is_open() << '\\n'; + } + +.SH Possible output: + + true + true + true + false + false + true + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::wfstream::is_open.3 b/man/std::wfstream::is_open.3 deleted file mode 120000 index d699f38b4..000000000 --- a/man/std::wfstream::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::is_open.3 \ No newline at end of file diff --git a/man/std::wfstream::is_open.3 b/man/std::wfstream::is_open.3 new file mode 100644 index 000000000..39cb27b98 --- /dev/null +++ b/man/std::wfstream::is_open.3 @@ -0,0 +1,65 @@ +.TH std::basic_fstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::is_open \- std::basic_fstream::is_open + +.SH Synopsis + bool is_open() const; + + Checks if the file stream has an associated file. + + Effectively calls rdbuf()->is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the file stream has an associated file, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "some_file"; + + std::fstream fs(filename, std::ios::in); + + std::cout << std::boolalpha; + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + + if (!fs.is_open()) + { + fs.clear(); + fs.open(filename, std::ios::out); + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + } + } + +.SH Possible output: + + fs.is_open() = false + fs.is_open() = true + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP diff --git a/man/std::wfstream::native_handle.3 b/man/std::wfstream::native_handle.3 new file mode 100644 index 000000000..48601a86f --- /dev/null +++ b/man/std::wfstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_fstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::native_handle \- std::basic_fstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::wfstream::open.3 b/man/std::wfstream::open.3 deleted file mode 120000 index 0cec9a126..000000000 --- a/man/std::wfstream::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::open.3 \ No newline at end of file diff --git a/man/std::wfstream::open.3 b/man/std::wfstream::open.3 new file mode 100644 index 000000000..ada1a2dfe --- /dev/null +++ b/man/std::wfstream::open.3 @@ -0,0 +1,107 @@ +.TH std::basic_fstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::open \- std::basic_fstream::open + +.SH Synopsis + void open( const char* filename, + + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::in | std::ios_base::out ); + void open( const std::filesystem::path& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP + + = std::ios_base::in | std::ios_base::out ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode) (see std::basic_filebuf::open + for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. It is a BitmaskType, the following constants + are defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "example.123"; + + std::fstream fs; + fs.open(filename); + + if (!fs.is_open()) + { + fs.clear(); + fs.open(filename, std::ios::out); // create file + fs.close(); + fs.open(filename); + } + + std::cout << std::boolalpha; + std::cout << "fs.is_open() = " << fs.is_open() << '\\n'; + std::cout << "fs.good() = " << fs.good() << '\\n'; + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + LWG 460 C++98 the default argument of mode in overload (1) added + was missing (it is present in the synopsis) + + 1. ↑ The resolution of LWG issue #22 is overriden. + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::wfstream::operator=.3 b/man/std::wfstream::operator=.3 deleted file mode 120000 index 731a08752..000000000 --- a/man/std::wfstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::operator=.3 \ No newline at end of file diff --git a/man/std::wfstream::operator=.3 b/man/std::wfstream::operator=.3 new file mode 100644 index 000000000..31af32e71 --- /dev/null +++ b/man/std::wfstream::operator=.3 @@ -0,0 +1,37 @@ +.TH std::basic_fstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::operator= \- std::basic_fstream::operator= + +.SH Synopsis + basic_fstream& operator=( basic_fstream&& other ); \fI(since C++11)\fP + + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_iostream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. + +.SH Parameters + + other - file stream to move + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wfstream::rdbuf.3 b/man/std::wfstream::rdbuf.3 deleted file mode 120000 index acf3172d0..000000000 --- a/man/std::wfstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::wfstream::rdbuf.3 b/man/std::wfstream::rdbuf.3 new file mode 100644 index 000000000..50d1692f2 --- /dev/null +++ b/man/std::wfstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_fstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::rdbuf \- std::basic_fstream::rdbuf + +.SH Synopsis + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP + + Returns pointer to the underlying raw file device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw file device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wfstream::swap.3 b/man/std::wfstream::swap.3 deleted file mode 120000 index d88b5421c..000000000 --- a/man/std::wfstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::swap.3 \ No newline at end of file diff --git a/man/std::wfstream::swap.3 b/man/std::wfstream::swap.3 new file mode 100644 index 000000000..2051eb906 --- /dev/null +++ b/man/std::wfstream::swap.3 @@ -0,0 +1,81 @@ +.TH std::basic_fstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::swap \- std::basic_fstream::swap + +.SH Synopsis + void swap( basic_fstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_iostream::swap(other) and + rdbuf()->swap(other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" + +.SH See also + + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::wfstream::wfstream.3 b/man/std::wfstream::wfstream.3 deleted file mode 120000 index 4401b4547..000000000 --- a/man/std::wfstream::wfstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_fstream::basic_fstream.3 \ No newline at end of file diff --git a/man/std::wfstream::wfstream.3 b/man/std::wfstream::wfstream.3 new file mode 100644 index 000000000..d3641c529 --- /dev/null +++ b/man/std::wfstream::wfstream.3 @@ -0,0 +1,111 @@ +.TH std::basic_fstream::basic_fstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_fstream::basic_fstream \- std::basic_fstream::basic_fstream + +.SH Synopsis + basic_fstream(); \fB(1)\fP + explicit basic_fstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::filesystem::path::value_type* + filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + explicit basic_fstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in | + std::ios_base::out ); + template< class FsPath > + + explicit basic_fstream( const FsPath& filename, + std::ios_base::openmode mode \fB(5)\fP \fI(since C++17)\fP + + = std::ios_base::in | + std::ios_base::out ); + basic_fstream( basic_fstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_fstream( const basic_fstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_fstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::fstream f0; + std::fstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::fstream f2(name); + std::fstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default argument of mode in overload + LWG 460 C++98 (2) added + was missing (it is present in the synopsis) + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_iostream)\fP diff --git a/man/std::wifstream.3 b/man/std::wifstream.3 deleted file mode 120000 index 39bb60d5b..000000000 --- a/man/std::wifstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream.3 \ No newline at end of file diff --git a/man/std::wifstream.3 b/man/std::wifstream.3 new file mode 100644 index 000000000..b1ae2381b --- /dev/null +++ b/man/std::wifstream.3 @@ -0,0 +1,332 @@ +.TH std::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream \- std::basic_ifstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_ifstream : public std::basic_istream + + The class template basic_ifstream implements high-level input operations on + file-based streams. It interfaces a file-based streambuffer (std::basic_filebuf) + with the high-level interface of (std::basic_istream). + + A typical implementation of std::basic_ifstream holds only one non-derived data + member: an instance of std::basic_filebuf. + + std-basic ifstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ifstream std::basic_ifstream + std::wifstream std::basic_ifstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + + constructor constructs the file stream + \fI(public member function)\fP + destructor destructs the basic_ifstream and the associated + \fB[virtual]\fP (implicitly declared) buffer, closes the file + \fI(virtual public member function)\fP + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw file device object + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP +.SH File operations + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ifstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "Test.b"; + + // prepare a file to read + double d = 3.14; + std::ofstream(filename, std::ios::binary) + .write(reinterpret_cast(&d), sizeof d) << 123 << "abc"; + + // open file for reading + std::ifstream istrm(filename, std::ios::binary); + if (!istrm.is_open()) + std::cout << "failed to open " << filename << '\\n'; + else + { + double d; + istrm.read(reinterpret_cast(&d), sizeof d); // binary input + int n; + std::string s; + if (istrm >> n >> s) // text input + std::cout << "read back from file: " << d << ' ' << n << ' ' << s << '\\n'; + } + } + +.SH Output: + + read back from file: 3.14 123 abc diff --git a/man/std::wifstream::basic_ifstream.3 b/man/std::wifstream::basic_ifstream.3 deleted file mode 120000 index da5f5ba66..000000000 --- a/man/std::wifstream::basic_ifstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::basic_ifstream.3 \ No newline at end of file diff --git a/man/std::wifstream::basic_ifstream.3 b/man/std::wifstream::basic_ifstream.3 new file mode 100644 index 000000000..f8e14c230 --- /dev/null +++ b/man/std::wifstream::basic_ifstream.3 @@ -0,0 +1,104 @@ +.TH std::basic_ifstream::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::basic_ifstream \- std::basic_ifstream::basic_ifstream + +.SH Synopsis + basic_ifstream(); \fB(1)\fP + explicit basic_ifstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in ); + explicit basic_ifstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + explicit basic_ifstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + template< class FsPath > + + explicit basic_ifstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + basic_ifstream( basic_ifstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ifstream( const basic_ifstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ifstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream f0; + std::ifstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ifstream f2(name); + std::ifstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wifstream::close.3 b/man/std::wifstream::close.3 deleted file mode 120000 index 71411cd09..000000000 --- a/man/std::wifstream::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::close.3 \ No newline at end of file diff --git a/man/std::wifstream::close.3 b/man/std::wifstream::close.3 new file mode 100644 index 000000000..c0db90cca --- /dev/null +++ b/man/std::wifstream::close.3 @@ -0,0 +1,41 @@ +.TH std::basic_ifstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::close \- std::basic_ifstream::close + +.SH Synopsis + void close(); + + Closes the associated file. + + Effectively calls rdbuf()->close(). If an error occurs during operation, + setstate(failbit) is called. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called by the destructor of basic_ifstream when the stream object + goes out of scope and is not usually invoked directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wifstream::is_open.3 b/man/std::wifstream::is_open.3 deleted file mode 120000 index 286e339cb..000000000 --- a/man/std::wifstream::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::is_open.3 \ No newline at end of file diff --git a/man/std::wifstream::is_open.3 b/man/std::wifstream::is_open.3 new file mode 100644 index 000000000..180030db6 --- /dev/null +++ b/man/std::wifstream::is_open.3 @@ -0,0 +1,63 @@ +.TH std::basic_ifstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::is_open \- std::basic_ifstream::is_open + +.SH Synopsis + bool is_open() const; + + Checks if the file stream has an associated file. + + Effectively calls rdbuf()->is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the file stream has an associated file, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + // this file is called main.cpp + + bool file_exists(const std::string& str) + { + std::ifstream fs(str); + return fs.is_open(); + } + + int main() + { + std::boolalpha(std::cout); + std::cout << file_exists("main.cpp") << '\\n' + << file_exists("strange_file") << '\\n'; + } + +.SH Possible output: + + true + false + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP diff --git a/man/std::wifstream::native_handle.3 b/man/std::wifstream::native_handle.3 new file mode 100644 index 000000000..264f88e20 --- /dev/null +++ b/man/std::wifstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_ifstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::native_handle \- std::basic_ifstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::wifstream::open.3 b/man/std::wifstream::open.3 deleted file mode 120000 index 6755d8636..000000000 --- a/man/std::wifstream::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::open.3 \ No newline at end of file diff --git a/man/std::wifstream::open.3 b/man/std::wifstream::open.3 new file mode 100644 index 000000000..4b1131d62 --- /dev/null +++ b/man/std::wifstream::open.3 @@ -0,0 +1,84 @@ +.TH std::basic_ifstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::open \- std::basic_ifstream::open + +.SH Synopsis + void open( const char* filename, + + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::in ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::in ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + void open( const std::filesystem::path& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP + + = std::ios_base::in ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode | ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. It is a BitmaskType, the following constants + are defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + + 1. ↑ The resolution of LWG issue #22 is overriden. + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wifstream::operator=.3 b/man/std::wifstream::operator=.3 deleted file mode 120000 index 51b3bf9f4..000000000 --- a/man/std::wifstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::operator=.3 \ No newline at end of file diff --git a/man/std::wifstream::operator=.3 b/man/std::wifstream::operator=.3 new file mode 100644 index 000000000..149d17ae4 --- /dev/null +++ b/man/std::wifstream::operator=.3 @@ -0,0 +1,37 @@ +.TH std::basic_ifstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::operator= \- std::basic_ifstream::operator= + +.SH Synopsis + basic_ifstream& operator=( basic_ifstream&& other ); \fI(since C++11)\fP + + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_istream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. + +.SH Parameters + + other - file stream to move + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wifstream::rdbuf.3 b/man/std::wifstream::rdbuf.3 deleted file mode 120000 index 62dd2b519..000000000 --- a/man/std::wifstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::wifstream::rdbuf.3 b/man/std::wifstream::rdbuf.3 new file mode 100644 index 000000000..cb59a8031 --- /dev/null +++ b/man/std::wifstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_ifstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::rdbuf \- std::basic_ifstream::rdbuf + +.SH Synopsis + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP + + Returns pointer to the underlying raw file device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw file device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wifstream::swap.3 b/man/std::wifstream::swap.3 deleted file mode 120000 index 1cd4bf8db..000000000 --- a/man/std::wifstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::swap.3 \ No newline at end of file diff --git a/man/std::wifstream::swap.3 b/man/std::wifstream::swap.3 new file mode 100644 index 000000000..25e3093f1 --- /dev/null +++ b/man/std::wifstream::swap.3 @@ -0,0 +1,81 @@ +.TH std::basic_ifstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::swap \- std::basic_ifstream::swap + +.SH Synopsis + void swap( basic_ifstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_istream::swap(other) and + rdbuf()->swap(other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" + +.SH See also + + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::wifstream::wifstream.3 b/man/std::wifstream::wifstream.3 deleted file mode 120000 index da5f5ba66..000000000 --- a/man/std::wifstream::wifstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ifstream::basic_ifstream.3 \ No newline at end of file diff --git a/man/std::wifstream::wifstream.3 b/man/std::wifstream::wifstream.3 new file mode 100644 index 000000000..f8e14c230 --- /dev/null +++ b/man/std::wifstream::wifstream.3 @@ -0,0 +1,104 @@ +.TH std::basic_ifstream::basic_ifstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ifstream::basic_ifstream \- std::basic_ifstream::basic_ifstream + +.SH Synopsis + basic_ifstream(); \fB(1)\fP + explicit basic_ifstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::in ); + explicit basic_ifstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + explicit basic_ifstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::in ); + template< class FsPath > + + explicit basic_ifstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::in ); + basic_ifstream( basic_ifstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ifstream( const basic_ifstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::in) (see + std::basic_filebuf::open for the details on the effects of that call). If the open() + call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ifstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream f0; + std::ifstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ifstream f2(name); + std::ifstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wios.3 b/man/std::wios.3 deleted file mode 120000 index 3f1622148..000000000 --- a/man/std::wios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios.3 \ No newline at end of file diff --git a/man/std::wios.3 b/man/std::wios.3 new file mode 100644 index 000000000..53f70e4db --- /dev/null +++ b/man/std::wios.3 @@ -0,0 +1,243 @@ +.TH std::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios \- std::basic_ios + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + > class basic_ios + + : public std::ios_base + + The class std::basic_ios provides facilities for interfacing with objects that have + std::basic_streambuf interface. Several std::basic_ios objects can refer to one + actual std::basic_streambuf object. + + std-basic ios-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ios std::basic_ios + std::wios std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Public member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= the copy assignment operator is deleted + \fI(public member function)\fP +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function)\fP + eof checks if end-of-file has been reached + \fI(public member function)\fP + fail checks if an error has occurred + \fI(public member function)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function)\fP + rdstate returns state flags + \fI(public member function)\fP + setstate sets state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function)\fP + fill manages the fill character + \fI(public member function)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function)\fP + imbue sets the locale + \fI(public member function)\fP + rdbuf manages associated stream buffer + \fI(public member function)\fP + tie manages tied stream + \fI(public member function)\fP + narrow narrows characters + \fI(public member function)\fP + widen widens characters + \fI(public member function)\fP + +.SH Protected member functions + + init initializes a default-constructed std::basic_ios + \fI(protected member function)\fP + move moves from another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps with another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Straightforward implementation of std::basic_ios stores only the following members + (which all depend on the template parameters and thus cannot be part of + std::ios_base): + + * the fill character (see fill()) + * the tied stream pointer (see tie()) + * the associated stream buffer pointer (see rdbuf()). + + Actual implementations vary: + + Microsoft Visual Studio stores just those three members. + + LLVM libc++ stores 1 less member: it maintains the rdbuf pointer as a void* member + of ios_base. + + GNU libstdc++ stores 4 additional members: three cached facets and a flag to + indicate that fill was initialized. diff --git a/man/std::wios::bad.3 b/man/std::wios::bad.3 deleted file mode 120000 index 4ba5b2d1f..000000000 --- a/man/std::wios::bad.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::bad.3 \ No newline at end of file diff --git a/man/std::wios::bad.3 b/man/std::wios::bad.3 new file mode 100644 index 000000000..dab780437 --- /dev/null +++ b/man/std::wios::bad.3 @@ -0,0 +1,67 @@ +.TH std::basic_ios::bad 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::bad \- std::basic_ios::bad + +.SH Synopsis + bool bad() const; + + Returns true if non-recoverable error has occurred on the associated stream. + Specifically, returns true if badbit is set in rdstate(). + + See ios_base::iostate for the list of conditions that set badbit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if a non-recoverable error has occurred, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::wios::basic_ios.3 b/man/std::wios::basic_ios.3 deleted file mode 120000 index 3e82757c3..000000000 --- a/man/std::wios::basic_ios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::basic_ios.3 \ No newline at end of file diff --git a/man/std::wios::basic_ios.3 b/man/std::wios::basic_ios.3 new file mode 100644 index 000000000..4695bdf9d --- /dev/null +++ b/man/std::wios::basic_ios.3 @@ -0,0 +1,39 @@ +.TH std::basic_ios::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::basic_ios \- std::basic_ios::basic_ios + +.SH Synopsis + protected: \fB(1)\fP + basic_ios(); + public: \fB(2)\fP + explicit basic_ios( std::basic_streambuf* sb ); + private: \fI(until C++11)\fP + basic_ios( const basic_ios& ); \fB(3)\fP + public: \fI(since C++11)\fP + basic_ios( const basic_ios& ) = delete; + + Constructs a new std::basic_ios object. + + 1) Default constructor. The internal state is not initialized. init() must be called + before the first use of the object or before destructor, otherwise the behavior is + undefined. + 2) Initializes the internal state by calling init(sb). The associated stream buffer + is set to sb. + 3) The copy constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: I/O streams are not CopyConstructible. + +.SH Parameters + + sb - stream buffer to associate to + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1249 C++98 internal state did not need to be initialized also needs to be + before first use initialized diff --git a/man/std::wios::clear.3 b/man/std::wios::clear.3 deleted file mode 120000 index 73ea99edb..000000000 --- a/man/std::wios::clear.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::clear.3 \ No newline at end of file diff --git a/man/std::wios::clear.3 b/man/std::wios::clear.3 new file mode 100644 index 000000000..808ca3227 --- /dev/null +++ b/man/std::wios::clear.3 @@ -0,0 +1,85 @@ +.TH std::basic_ios::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::clear \- std::basic_ios::clear + +.SH Synopsis + void clear( std::ios_base::iostate state = std::ios_base::goodbit ); + + Sets the stream error state flags by assigning them the value of state. By default, + assigns std::ios_base::goodbit which has the effect of clearing all error state + flags. + + If rdbuf() is a null pointer (i.e. there is no associated stream buffer), then state + | std::ios_base::badbit is assigned. + +.SH Parameters + + new error state flags setting. It can be a combination of the following + constants: + + state - Constant Explanation + goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction error) + eofbit associated input sequence has reached end-of-file + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + If the new error state includes a bit that is also included in the exceptions() + mask, throws an exception of type failure. + +.SH Example + + clear() without arguments can be used to unset the failbit after unexpected input; + for std::cin.putback(c) see ungetc. + + +// Run this code + + #include + #include + + int main() + { + for (char c : {'\\n', '4', '1', '.', '3', '\\n', 'Z', 'Y', 'X'}) + std::cin.putback(c); // emulate user's input (not portable: see ungetc Notes) + + double n; + while (std::cout << "Please, enter a number: " && !(std::cin >> n)) + { + std::cin.clear(); + std::string line; + std::getline(std::cin, line); + std::cout << line << "\\nI am sorry, but '" << line << "' is not a number\\n"; + } + std::cout << n << "\\nThank you for entering the number " << n << '\\n'; + } + +.SH Output: + + Please, enter a number: XYZ + I am sorry, but 'XYZ' is not a number + Please, enter a number: 3.14 + Thank you for entering the number 3.14 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + an excption would be thrown if the current + LWG 412 C++98 error state checks the new + includes a bit that is also included in the error state instead + exceptions() mask + +.SH See also + + setstate sets state flags + \fI(public member function)\fP + rdstate returns state flags + \fI(public member function)\fP diff --git a/man/std::wios::copyfmt.3 b/man/std::wios::copyfmt.3 deleted file mode 120000 index ba8869565..000000000 --- a/man/std::wios::copyfmt.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::copyfmt.3 \ No newline at end of file diff --git a/man/std::wios::copyfmt.3 b/man/std::wios::copyfmt.3 new file mode 100644 index 000000000..775df7d97 --- /dev/null +++ b/man/std::wios::copyfmt.3 @@ -0,0 +1,94 @@ +.TH std::basic_ios::copyfmt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::copyfmt \- std::basic_ios::copyfmt + +.SH Synopsis + basic_ios& copyfmt( const basic_ios& other ); + + If other refers to the same object as *this, has no effects. Otherwise, copies the + state of the stream other into *this. This is done in the following sequence: + + 1) Calls every callback registered by register_callback() passing erase_event as + parameter. + 2) Copies all member objects from other to *this except for rdstate(), the exception + mask, and rdbuf(). In particular, makes copies of the locale, the formatting flags, + the contents of the arrays std::ios_base::iword and std::ios_base::pword (but not + the iword and pword pointers themselves), the callbacks, and the tied stream. + 3) Calls every callback registered by register_callback() passing copyfmt_event as + parameter. + 4) Copies the exception mask from other to *this as if by calling + exceptions(other.exceptions()). + +.SH Parameters + + other - another stream to use as source + +.SH Return value + + *this + +.SH Notes + + The second pass through the callbacks may be used to deep-copy the user-defined + objects pointed to by the pointers in std::ios_base::pword. + + copyfmt() may be used to save and restore the state of a stream. Boost provides a + more fine-grained I/O state savers library for the same purpose. + +.SH Example + + Makes the std::ofstream object "out" behave exactly like std::cout, including + formatting, tie() to std::cin, etc. + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ofstream out; + + out.copyfmt(std::cout); // copy everything except rdstate and rdbuf + out.clear(std::cout.rdstate()); // copy rdstate + out.basic_ios::rdbuf(std::cout.rdbuf()); // share the buffer + + out << "Hello, world\\n"; + + auto bin = [](std::ios_base::fmtflags f) + { + return std::bitset + { static_cast(f) }; + }; + std::ofstream out2; + std::cout << "1) out2.flags(): " << bin(out2.flags()) << '\\n'; + std::cout << "2) cout.flags(): " << bin(std::cout.flags()) << '\\n'; + std::cout.setf(std::ios::hex | std::ios::fixed | std::ios::boolalpha); + std::cout << "3) cout.flags(): " << bin(std::cout.flags()) << '\\n'; + out2.copyfmt(std::cout); // copy everything except rdstate and rdbuf + std::cout << "4) out2.flags(): " << bin(out2.flags()) << '\\n'; + } + +.SH Possible output: + + Hello, world + 1) out2.flags(): 00000000000000000001000000000010 + 2) cout.flags(): 00000000000000000001000000000010 + 3) cout.flags(): 00000000000000000001000000001111 + 4) out2.flags(): 00000000000000000001000000001111 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 256 C++98 step 3 called the registered callbacks with the corrected to + event type copy_event, which is not defined copyfmt_event + if other refers to the same object as *this, the + LWG 292 C++98 member objects do nothing + were still copied and the registered callbacks in this case + were still called diff --git a/man/std::wios::eof.3 b/man/std::wios::eof.3 deleted file mode 120000 index 6b20a3e3d..000000000 --- a/man/std::wios::eof.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::eof.3 \ No newline at end of file diff --git a/man/std::wios::eof.3 b/man/std::wios::eof.3 new file mode 100644 index 000000000..2eeb9f530 --- /dev/null +++ b/man/std::wios::eof.3 @@ -0,0 +1,80 @@ +.TH std::basic_ios::eof 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::eof \- std::basic_ios::eof + +.SH Synopsis + bool eof() const; + + Returns true if the associated stream has reached end-of-file. Specifically, returns + true if eofbit is set in rdstate(). + + See ios_base::iostate for the list of conditions that set eofbit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if an end-of-file has occurred, false otherwise. + +.SH Notes + + This function only reports the stream state as set by the most recent I/O operation; + it does not examine the associated data source. For example, if the most recent I/O + was a get() which returned the last byte of a file, eof() returns false. The next + get() fails to read anything and sets the eofbit. Only then does eof() return true. + + In typical usage, input stream processing stops on any error. eof() and fail() can + then be used to distinguish between different error conditions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true + + feof checks for the end-of-file + \fI(function)\fP diff --git a/man/std::wios::exceptions.3 b/man/std::wios::exceptions.3 deleted file mode 120000 index 049774224..000000000 --- a/man/std::wios::exceptions.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::exceptions.3 \ No newline at end of file diff --git a/man/std::wios::exceptions.3 b/man/std::wios::exceptions.3 new file mode 100644 index 000000000..56dd00a97 --- /dev/null +++ b/man/std::wios::exceptions.3 @@ -0,0 +1,62 @@ +.TH std::basic_ios::exceptions 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::exceptions \- std::basic_ios::exceptions + +.SH Synopsis + std::ios_base::iostate exceptions() const; \fB(1)\fP + void exceptions( std::ios_base::iostate except ); \fB(2)\fP + + Gets and sets the exception mask of the stream. The exception mask determines which + error states trigger exceptions of type failure. + + 1) Returns the exception mask. + 2) Sets the exception mask to except. If the stream has an error state covered by + the exception mask when called, an exception is immediately triggered. + +.SH Parameters + + except - exception mask + +.SH Return value + + 1) The current exception mask. + 2) \fI(none)\fP + +.SH Notes + + This section is incomplete + Reason: discuss LWG2349 and link from ios_base::clear, and from + (un)formatted(i/o)utputfunction requirement pages (or perhaps the behavior should + be fully elaborated on the requirement pages and linked from here). See also + stackoverflow.com/a/35089910 + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int ivalue; + try + { + std::ifstream in("in.txt"); + in.exceptions(std::ifstream::failbit); // may throw + in >> ivalue; // may throw + } + catch (const std::ios_base::failure& fail) + { + // handle exception here + std::cout << fail.what() << '\\n'; + } + } + +.SH Possible output: + + basic_ios::clear: iostream error + +.SH Category: + * Todo with reason diff --git a/man/std::wios::fail.3 b/man/std::wios::fail.3 deleted file mode 120000 index ed2e7637d..000000000 --- a/man/std::wios::fail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::fail.3 \ No newline at end of file diff --git a/man/std::wios::fail.3 b/man/std::wios::fail.3 new file mode 100644 index 000000000..f5d71a0d6 --- /dev/null +++ b/man/std::wios::fail.3 @@ -0,0 +1,70 @@ +.TH std::basic_ios::fail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::fail \- std::basic_ios::fail + +.SH Synopsis + bool fail() const; + + Returns true if an error has occurred on the associated stream. Specifically, + returns true if badbit or failbit is set in rdstate(). + + See ios_base::iostate for the list of conditions that set failbit or badbit. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if an error has occurred, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true + + ferror checks for a file error + \fI(function)\fP diff --git a/man/std::wios::fill.3 b/man/std::wios::fill.3 deleted file mode 120000 index 1b7b51aeb..000000000 --- a/man/std::wios::fill.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::fill.3 \ No newline at end of file diff --git a/man/std::wios::fill.3 b/man/std::wios::fill.3 new file mode 100644 index 000000000..cc61848b0 --- /dev/null +++ b/man/std::wios::fill.3 @@ -0,0 +1,47 @@ +.TH std::basic_ios::fill 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::fill \- std::basic_ios::fill + +.SH Synopsis + CharT fill() const; \fB(1)\fP + CharT fill( CharT ch ); \fB(2)\fP + + Manages the fill character used to pad the output conversions to the specified field + width. + + 1) Returns the current fill character. + 2) Sets the fill character to ch, returns previous value of the fill character. + +.SH Parameters + + ch - the character to use as fill character + +.SH Return value + + The fill character before the call to the function. + +.SH Example + + +// Run this code + + #include + #include + + int main () + { + std::cout << "With default setting : [" << std::setw(10) << 40 << "]\\n"; + char prev = std::cout.fill('x'); + std::cout << "Replaced '" << prev << "' with '" + << std::cout.fill() << "': [" << std::setw(10) << 40 << "]\\n"; + } + +.SH Output: + + With default setting : [ 40] + Replaced ' ' with 'x': [xxxxxxxx40] + +.SH See also + + setfill changes the fill character + \fI(function template)\fP diff --git a/man/std::wios::good.3 b/man/std::wios::good.3 deleted file mode 120000 index d380a0f1c..000000000 --- a/man/std::wios::good.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::good.3 \ No newline at end of file diff --git a/man/std::wios::good.3 b/man/std::wios::good.3 new file mode 100644 index 000000000..55892fb7c --- /dev/null +++ b/man/std::wios::good.3 @@ -0,0 +1,82 @@ +.TH std::basic_ios::good 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::good \- std::basic_ios::good + +.SH Synopsis + bool good() const; + + Returns true if the most recent I/O operation on the stream completed successfully. + Specifically, returns result of rdstate() == 0. + + See ios_base::iostate for the list of conditions that set the stream status bits. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the stream error flags are all false, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const char* fname = "/tmp/test.txt"; + std::ofstream ofile{fname}; + ofile << "10 " << "11 " << "12 " << "non-int"; + ofile.close(); + + std::ifstream file{fname}; + if (!file.good()) + { + std::cout << "#1. Opening file test.txt failed - " + "one of the error flags is true\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + { + std::cout << "#2. I/O error while reading - badbit is true\\n"; + return EXIT_FAILURE; + } + else if (file.eof()) + std::cout << "#3. End of file reached successfully - eofbit is true\\n" + "This is fine even though file.good() is false\\n"; + else if (file.fail()) + std::cout << "#4. Non-integer data encountered - failbit is true\\n"; + } + +.SH Possible output: + + 10 11 12 + #4. Non-integer data encountered - failbit is true + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::wios::imbue.3 b/man/std::wios::imbue.3 deleted file mode 120000 index fde227cb4..000000000 --- a/man/std::wios::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::imbue.3 \ No newline at end of file diff --git a/man/std::wios::imbue.3 b/man/std::wios::imbue.3 new file mode 100644 index 000000000..065831d53 --- /dev/null +++ b/man/std::wios::imbue.3 @@ -0,0 +1,46 @@ +.TH std::basic_ios::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::imbue \- std::basic_ios::imbue + +.SH Synopsis + std::locale imbue( const std::locale& loc ); + + Replaces the current locale. Effectively calls ios_base::imbue(loc) and if there is + an associated stream buffer (rdbuf() != 0), then calls rdbuf()->pubimbue(loc). + +.SH Parameters + + loc - the new locale + +.SH Return value + + The previous locale, as returned by ios_base::imbue(loc). + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream iss; + iss.imbue(std::locale("en_US.UTF8")); + + std::cout << "Current locale: " << iss.getloc().name() << '\\n'; + + iss.imbue(std::locale()); + std::cout << "Global locale : " << iss.getloc().name() << '\\n'; + } + +.SH Output: + + Current locale: en_US.UTF8 + Global locale : C diff --git a/man/std::wios::init.3 b/man/std::wios::init.3 deleted file mode 120000 index c1c5dfca0..000000000 --- a/man/std::wios::init.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::init.3 \ No newline at end of file diff --git a/man/std::wios::init.3 b/man/std::wios::init.3 new file mode 100644 index 000000000..18affa265 --- /dev/null +++ b/man/std::wios::init.3 @@ -0,0 +1,39 @@ +.TH std::basic_ios::init 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::init \- std::basic_ios::init + +.SH Synopsis + protected: + void init( std::basic_streambuf* sb ); + + Sets the associated stream buffer to sb and initializes the internal state. + + The postconditions are as follows: + + Element Value + rdbuf() sb + tie() null pointer + rdstate() goodbit if sb is not a null pointer, otherwise badbit + exceptions() goodbit + flags() skipws | dec + width() 0 + precision() 6 + fill() widen(' ') + getloc() a copy of the value returned by std::locale() + + This member function is protected: it is called by the constructors of the derived + stream classes std::basic_istream and std::basic_ostream once the associated stream + buffer is known. Until this function is called, every member function (including the + destructor) of the default-constructed std::basic_ios invokes undefined behavior. + Note that basic_ios is a virtual base class, and therefore its constructor is not + called by the constructors of those directly derived classes, which is why two-stage + initialization is necessary. + +.SH Parameters + + sb - stream buffer to associate to + +.SH See also + + constructor constructs the object + \fI(public member function)\fP diff --git a/man/std::wios::move.3 b/man/std::wios::move.3 deleted file mode 120000 index 80fb430d4..000000000 --- a/man/std::wios::move.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::move.3 \ No newline at end of file diff --git a/man/std::wios::move.3 b/man/std::wios::move.3 new file mode 100644 index 000000000..00e50ed27 --- /dev/null +++ b/man/std::wios::move.3 @@ -0,0 +1,33 @@ +.TH std::basic_ios::move 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::move \- std::basic_ios::move + +.SH Synopsis + protected: \fI(since C++11)\fP + void move( basic_ios& other ); + protected: \fI(since C++11)\fP + void move( basic_ios&& other ); + + Replaces the current state with that of other, except for the associated rdbuf. + other is in valid, but unspecified state after the call. After the call to this + function, rdbuf() returns a null pointer, other.rdbuf() returns the same value as + before the call, and other.tie() returns a null pointer. + + This member function is protected: it is called by the protected move constructors + of the derived stream classes std::basic_ostream and std::basic_istream, which, in + turn, are called by the public move constructors of the further derived stream + classes such as std::basic_ofstream, which know how to correctly move the associated + streambuffer. + +.SH Parameters + + other - the basic_ios object to transfer the state from + +.SH Return value + + \fI(none)\fP + +.SH See also + + swap swaps with another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::wios::narrow.3 b/man/std::wios::narrow.3 deleted file mode 120000 index 104f8b0c1..000000000 --- a/man/std::wios::narrow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::narrow.3 \ No newline at end of file diff --git a/man/std::wios::narrow.3 b/man/std::wios::narrow.3 new file mode 100644 index 000000000..b498eaa0c --- /dev/null +++ b/man/std::wios::narrow.3 @@ -0,0 +1,32 @@ +.TH std::basic_ios::narrow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::narrow \- std::basic_ios::narrow + +.SH Synopsis + char narrow( char_type c, char dfault ) const; + + Converts a current locale-specific character c to its standard equivalent. The + result is converted from char_type to char if needed. If no conversion can be + performed, the function returns dfault. + + Effectively calls std::use_facet< std::ctype >(getloc()).narrow(c, + dfault);. + +.SH Parameters + + c - character to convert + dfault - character to return if the conversion was unsuccessful + +.SH Return value + + Character converted to its standard equivalent and then to char. dfault is returned + if the conversion fails. + +.SH See also + + widen widens characters + \fI(public member function)\fP + narrow invokes do_narrow + \fI(public member function of std::ctype)\fP + wctob narrows a wide character to a single-byte narrow character, if possible + \fI(function)\fP diff --git a/man/std::wios::operator!.3 b/man/std::wios::operator!.3 deleted file mode 120000 index 5b157aec2..000000000 --- a/man/std::wios::operator!.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::operator!.3 \ No newline at end of file diff --git a/man/std::wios::operator!.3 b/man/std::wios::operator!.3 new file mode 100644 index 000000000..07ac029c2 --- /dev/null +++ b/man/std::wios::operator!.3 @@ -0,0 +1,65 @@ +.TH std::basic_ios::operator! 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::operator! \- std::basic_ios::operator! + +.SH Synopsis + bool operator!() const; + + Returns true if an error has occurred on the associated stream. Specifically, + returns true if badbit or failbit is set in rdstate(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if an error has occurred, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ifstream file("test.txt"); + if (!file) // operator! is used here + { + std::cout << "File opening failed\\n"; + return EXIT_FAILURE; + } + + // typical C++ I/O loop uses the return value of the I/O function + // as the loop controlling condition, operator bool() is used here + for (int n; file >> n;) + std::cout << n << ' '; + std::cout << '\\n'; + + if (file.bad()) + std::cout << "I/O error while reading\\n"; + else if (file.eof()) + std::cout << "End of file reached successfully\\n"; + else if (file.fail()) + std::cout << "Non-integer data encountered\\n"; + } + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::wios::operatorbool.3 b/man/std::wios::operatorbool.3 deleted file mode 120000 index fc40e5647..000000000 --- a/man/std::wios::operatorbool.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::operatorbool.3 \ No newline at end of file diff --git a/man/std::wios::operatorbool.3 b/man/std::wios::operatorbool.3 new file mode 100644 index 000000000..40c8dc683 --- /dev/null +++ b/man/std::wios::operatorbool.3 @@ -0,0 +1,95 @@ +.TH std::basic_ios::operatorbool 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::operatorbool \- std::basic_ios::operatorbool + +.SH Synopsis + operator /* unspecified-boolean-type */() const; \fB(1)\fP \fI(until C++11)\fP + explicit operator bool() const; \fB(2)\fP \fI(since C++11)\fP + + Checks whether the stream has no errors. + + 1) Returns a value that evaluates to false in a boolean context if fail() returns + true, otherwise returns a value that evaluates to true in a boolean context. + 2) Returns true if the stream has no errors and is ready for I/O operations. + Specifically, returns !fail(). + + This operator makes it possible to use streams and functions that return references + to streams as loop conditions, resulting in the idiomatic C++ input loops such as + while (stream >> value) {...} or while (std::getline(stream, string)) {...}. Such + loops execute the loop's body only if the input operation succeeded. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) A value that evaluates to true in a boolean context if the stream has no errors, + a value that evaluates to false in a boolean context otherwise. + 2) true if the stream has no errors, false otherwise. + +.SH Notes + + This conversion can be used in contexts where a bool is expected (e.g. an if + condition). However, implicit conversions (e.g. to int) that can occur with bool are + not allowed. + + In C++98, operator bool could not be provided directly due to the safe bool problem. + The initial solution in C++98 is to provide operator void*, which returns a null + pointer if fail() returns true or a non-null pointer otherwise. It is replaced by + the resolution of LWG issue 468, which allows Safe Bool idiom to be applied. + + Since C++11, conversion functions can be explicit. The resolution of LWG issue 1094 + introduced the explicit operator bool and the boolean conversion is now safe. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s("1 2 3 error"); + int n; + + std::cout << std::boolalpha << "s is " << static_cast(s) << '\\n'; + while (s >> n) + std::cout << n << '\\n'; + std::cout << "s is " << static_cast(s) << '\\n'; + } + +.SH Output: + + s is true + 1 + 2 + 3 + s is false + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 468 C++98 operator void* was a conversion function to an unspecified + provided boolean type is provided instead + +.SH See also + + The following table shows the value of basic_ios accessors (good(), fail(), etc.) + for all possible combinations of ios_base::iostate flags: + + ios_base::iostate flags basic_ios accessors + eofbit failbit badbit good() fail() bad() eof() operator bool operator! + false false false true false false false true false + false false true false true true false false true + false true false false true false false false true + false true true false true true false false true + true false false false false false true true false + true false true false true true true false true + true true false false true false true false true + true true true false true true true false true diff --git a/man/std::wios::rdbuf.3 b/man/std::wios::rdbuf.3 deleted file mode 120000 index 72f17cfc3..000000000 --- a/man/std::wios::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::rdbuf.3 \ No newline at end of file diff --git a/man/std::wios::rdbuf.3 b/man/std::wios::rdbuf.3 new file mode 100644 index 000000000..490355c23 --- /dev/null +++ b/man/std::wios::rdbuf.3 @@ -0,0 +1,69 @@ +.TH std::basic_ios::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::rdbuf \- std::basic_ios::rdbuf + +.SH Synopsis + std::basic_streambuf* rdbuf() const; \fB(1)\fP + std::basic_streambuf* rdbuf( std::basic_streambuf* sb ); + + Manages the associated stream buffer. + + 1) Returns the associated stream buffer. If there is no associated stream buffer, + returns a null pointer. + 2) Sets the associated stream buffer to sb. The error state is cleared by calling + clear(). Returns the associated stream buffer before the operation. If there is no + associated stream buffer, returns a null pointer. + +.SH Parameters + + sb - stream buffer to associate to + +.SH Return value + + The associated stream buffer, or a null pointer if there was no associated stream + buffer. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream local; + auto cout_buff = std::cout.rdbuf(); // save pointer to std::cout buffer + + std::cout.rdbuf(local.rdbuf()); // substitute internal std::cout buffer with + // buffer of 'local' object + + // now std::cout work with 'local' buffer + // you don't see this message + std::cout << "some message"; + + // go back to old buffer + std::cout.rdbuf(cout_buff); + + // you will see this message + std::cout << "back to default buffer\\n"; + + // print 'local' content + std::cout << "local content: " << local.str() << "\\n"; + } + +.SH Output: + + back to default buffer + local content: some message + +.SH See also + + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP diff --git a/man/std::wios::rdstate.3 b/man/std::wios::rdstate.3 deleted file mode 120000 index e8a0aa35b..000000000 --- a/man/std::wios::rdstate.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::rdstate.3 \ No newline at end of file diff --git a/man/std::wios::rdstate.3 b/man/std::wios::rdstate.3 new file mode 100644 index 000000000..934207b16 --- /dev/null +++ b/man/std::wios::rdstate.3 @@ -0,0 +1,57 @@ +.TH std::basic_ios::rdstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::rdstate \- std::basic_ios::rdstate + +.SH Synopsis + iostate rdstate() const; + + Returns the current stream error state. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + current stream error state. It is a bitmask type and can be a combination of the + following constants: + + Constant Explanation + goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction error) + eofbit associated input sequence has reached end-of-file + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream stream; + + if (stream.rdstate() == std::ios_base::goodbit) + std::cout << "stream state is goodbit\\n"; + + stream.setstate(std::ios_base::eofbit); + + // check state is exactly eofbit (no failbit and no badbit) + if (stream.rdstate() == std::ios_base::eofbit) + std::cout << "stream state is eofbit\\n"; + } + +.SH Output: + + stream state is goodbit + stream state is eofbit + +.SH See also + + setstate sets state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP diff --git a/man/std::wios::set_rdbuf.3 b/man/std::wios::set_rdbuf.3 deleted file mode 120000 index 45dc49f20..000000000 --- a/man/std::wios::set_rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::set_rdbuf.3 \ No newline at end of file diff --git a/man/std::wios::set_rdbuf.3 b/man/std::wios::set_rdbuf.3 new file mode 100644 index 000000000..02b9f3f7f --- /dev/null +++ b/man/std::wios::set_rdbuf.3 @@ -0,0 +1,41 @@ +.TH std::basic_ios::set_rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::set_rdbuf \- std::basic_ios::set_rdbuf + +.SH Synopsis + protected: \fI(since C++11)\fP + void set_rdbuf( std::basic_streambuf* sb ); + + Sets the associated stream buffer to sb without clearing the error state. + + This member function is protected: it is called by the move constructors of the + derived streams such as std::basic_ofstream or std::basic_istringstream, as the + final step after constructing the base class and after moving the stream buffer: + only the most derived stream class knows how to correctly move the stream buffer, + but std::basic_ios needs to be made aware of the stream's new location so that its + public member functions can access it. + +.SH Parameters + + sb - stream buffer to associate to + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws nothing. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + rdbuf manages associated stream buffer + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wios::setstate.3 b/man/std::wios::setstate.3 deleted file mode 120000 index 024203ede..000000000 --- a/man/std::wios::setstate.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::setstate.3 \ No newline at end of file diff --git a/man/std::wios::setstate.3 b/man/std::wios::setstate.3 new file mode 100644 index 000000000..378a09c28 --- /dev/null +++ b/man/std::wios::setstate.3 @@ -0,0 +1,61 @@ +.TH std::basic_ios::setstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::setstate \- std::basic_ios::setstate + +.SH Synopsis + void setstate( iostate state ); + + Sets the stream error flags state in addition to currently set flags. Essentially + calls clear(rdstate() | state). May throw an exception. + +.SH Parameters + + stream error state flags to set. It can be a combination of the following + constants: + + state - Constant Explanation + goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction error) + eofbit associated input sequence has reached end-of-file + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream stream; + + if (!stream.fail()) + std::cout << "stream is not fail\\n"; + + stream.setstate(std::ios_base::failbit); + + if (stream.fail()) + std::cout << "now stream is fail\\n"; + + if (!stream.good()) + std::cout << "and stream is not good\\n"; + } + +.SH Output: + + stream is not fail + now stream is fail + and stream is not good + +.SH See also + + rdstate returns state flags + \fI(public member function)\fP + clear modifies state flags + \fI(public member function)\fP diff --git a/man/std::wios::swap.3 b/man/std::wios::swap.3 deleted file mode 120000 index 44127e81a..000000000 --- a/man/std::wios::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::swap.3 \ No newline at end of file diff --git a/man/std::wios::swap.3 b/man/std::wios::swap.3 new file mode 100644 index 000000000..f22600bac --- /dev/null +++ b/man/std::wios::swap.3 @@ -0,0 +1,27 @@ +.TH std::basic_ios::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::swap \- std::basic_ios::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_ios& other ) noexcept; + + Exchanges the states of *this and other, except for the associated rdbuf objects. + rdbuf() and other.rdbuf() returns the same values as before the call. + + This swap function is protected: it is called by the swap member functions of the + derived stream classes such as std::basic_ofstream or std::basic_istringstream, + which know how to correctly swap the associated streambuffers. + +.SH Parameters + + other - the basic_ios object to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH See also + + move moves from another std::basic_ios except for rdbuf + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::wios::tie.3 b/man/std::wios::tie.3 deleted file mode 120000 index 7551d485a..000000000 --- a/man/std::wios::tie.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::tie.3 \ No newline at end of file diff --git a/man/std::wios::tie.3 b/man/std::wios::tie.3 new file mode 100644 index 000000000..3dba24394 --- /dev/null +++ b/man/std::wios::tie.3 @@ -0,0 +1,89 @@ +.TH std::basic_ios::tie 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::tie \- std::basic_ios::tie + +.SH Synopsis + std::basic_ostream* tie() const; \fB(1)\fP + std::basic_ostream* tie( std::basic_ostream* str \fB(2)\fP + ); + + Manages the tied stream. A tied stream is an output stream which is synchronized + with the sequence controlled by the stream buffer (rdbuf()), that is, flush() is + called on the tied stream before any input/output operation on *this. + + 1) Returns the current tied stream. If there is no tied stream, a null pointer is + returned. + 2) Sets the current tied stream to str. Returns the tied stream before the + operation. If there is no tied stream, a null pointer is returned. If str is not + null and tie() is reachable by traversing the linked list of tied stream objects + starting from str->tie(), the behavior is undefined. + +.SH Parameters + + str - an output stream to set as the tied stream + +.SH Return value + + The tied stream, or a null pointer if there was no tied stream. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + By default, the standard stream std::cout is tied to std::cin and std::cerr. + Similarly, its wide counterpart std::wcout is tied to std::wcin and std::wcerr. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ofstream os("test.txt"); + std::ifstream is("test.txt"); + std::string value("0"); + + os << "Hello"; + is >> value; + + std::cout << "Result before tie(): " << std::quoted(value) << "\\n"; + is.clear(); + is.tie(&os); + + is >> value; + + std::cout << "Result after tie(): " << std::quoted(value) << "\\n"; + } + +.SH Output: + + Result before tie(): "0" + Result after tie(): "Hello" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + two streams could be tied to each + LWG 835 C++98 other^[1] the behavior is undefined + (either directly or through another in this case + intermediate stream object) + + 1. ↑ std::basic_ostream::flush() is an UnformattedOutputFunction, so it creates a + sentry object while being called. When flush() is called on a stream object, the + constructor of the sentry object will call flush() on its tied stream, and that + flush() will construct another sentry object and its constructor will call + flush() on the tied stream of that stream and so on. Therefore, if streams a and + b are (directly or indirectly) tied to each other, calling a.flush() will + eventually call b.flush(), which will eventually call a.flush(), and will result + in an infinite loop. diff --git a/man/std::wios::widen.3 b/man/std::wios::widen.3 deleted file mode 120000 index 535be9e4f..000000000 --- a/man/std::wios::widen.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::widen.3 \ No newline at end of file diff --git a/man/std::wios::widen.3 b/man/std::wios::widen.3 new file mode 100644 index 000000000..f7d5906f7 --- /dev/null +++ b/man/std::wios::widen.3 @@ -0,0 +1,28 @@ +.TH std::basic_ios::widen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::widen \- std::basic_ios::widen + +.SH Synopsis + char_type widen( char c ) const; + + Converts a character c to its equivalent in the current locale. The result is + converted from char to character type used within the stream if needed. + + Effectively calls std::use_facet< std::ctype >(getloc()).widen(c). + +.SH Parameters + + c - character to convert + +.SH Return value + + Character converted to char_type + +.SH See also + + narrow narrows characters + \fI(public member function)\fP + do_widen converts a character or characters from char to CharT + \fB[virtual]\fP \fI(virtual protected member function of std::ctype)\fP + btowc widens a single-byte narrow character to wide character, if possible + \fI(function)\fP diff --git a/man/std::wios::wios.3 b/man/std::wios::wios.3 deleted file mode 120000 index 3e82757c3..000000000 --- a/man/std::wios::wios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::basic_ios.3 \ No newline at end of file diff --git a/man/std::wios::wios.3 b/man/std::wios::wios.3 new file mode 100644 index 000000000..4695bdf9d --- /dev/null +++ b/man/std::wios::wios.3 @@ -0,0 +1,39 @@ +.TH std::basic_ios::basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::basic_ios \- std::basic_ios::basic_ios + +.SH Synopsis + protected: \fB(1)\fP + basic_ios(); + public: \fB(2)\fP + explicit basic_ios( std::basic_streambuf* sb ); + private: \fI(until C++11)\fP + basic_ios( const basic_ios& ); \fB(3)\fP + public: \fI(since C++11)\fP + basic_ios( const basic_ios& ) = delete; + + Constructs a new std::basic_ios object. + + 1) Default constructor. The internal state is not initialized. init() must be called + before the first use of the object or before destructor, otherwise the behavior is + undefined. + 2) Initializes the internal state by calling init(sb). The associated stream buffer + is set to sb. + 3) The copy constructor is + declared private and not defined + \fI(until C++11)\fP + explicitly defined as deleted + \fI(since C++11)\fP: I/O streams are not CopyConstructible. + +.SH Parameters + + sb - stream buffer to associate to + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1249 C++98 internal state did not need to be initialized also needs to be + before first use initialized diff --git a/man/std::wios::~basic_ios.3 b/man/std::wios::~basic_ios.3 deleted file mode 120000 index 00095a990..000000000 --- a/man/std::wios::~basic_ios.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ios::~basic_ios.3 \ No newline at end of file diff --git a/man/std::wios::~basic_ios.3 b/man/std::wios::~basic_ios.3 new file mode 100644 index 000000000..4b2204a05 --- /dev/null +++ b/man/std::wios::~basic_ios.3 @@ -0,0 +1,21 @@ +.TH std::basic_ios::~basic_ios 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ios::~basic_ios \- std::basic_ios::~basic_ios + +.SH Synopsis + virtual ~basic_ios(); + + Destroys the basic_ios object. rdbuf is not destroyed. + +.SH Notes + + This destructor is virtual because the base class destructor, ios_base::~ios_base is + virtual. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 53 C++98 it was unspecified whether rdbuf is destroyed it is not destroyed diff --git a/man/std::wiostream.3 b/man/std::wiostream.3 deleted file mode 120000 index d53b6ea77..000000000 --- a/man/std::wiostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream.3 \ No newline at end of file diff --git a/man/std::wiostream.3 b/man/std::wiostream.3 new file mode 100644 index 000000000..0a46e3225 --- /dev/null +++ b/man/std::wiostream.3 @@ -0,0 +1,316 @@ +.TH std::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream \- std::basic_iostream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + > class basic_iostream : + public basic_istream, + + public basic_ostream + + The class template basic_iostream provides support for high level input/output + operations on streams. The supported operations include sequential reading or + writing and formatting. This functionality is implemented over the interface + provided by the std::basic_streambuf class. It is accessed through std::basic_ios + class. + + std-basic iostream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::iostream std::basic_iostream + std::wiostream std::basic_iostream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + +.SH Protected member functions + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + swap exchanges the state with another basic_iostream + \fI(C++11)\fP \fI(public member function)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the member types char_type, traits_type, + LWG 271 C++98 int_type, pos_type and off_type were not defined define + (std::basic_istream and std::basic_ostream both these types + define these types, resulted in ambiguity) + +.SH See also + + * Input/output manipulators diff --git a/man/std::wiostream::basic_iostream.3 b/man/std::wiostream::basic_iostream.3 deleted file mode 120000 index 7d6174906..000000000 --- a/man/std::wiostream::basic_iostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::basic_iostream.3 \ No newline at end of file diff --git a/man/std::wiostream::basic_iostream.3 b/man/std::wiostream::basic_iostream.3 new file mode 100644 index 000000000..f7d884fef --- /dev/null +++ b/man/std::wiostream::basic_iostream.3 @@ -0,0 +1,34 @@ +.TH std::basic_iostream::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::basic_iostream \- std::basic_iostream::basic_iostream + +.SH Synopsis + explicit basic_iostream( std::basic_streambuf* sb ); \fB(1)\fP + basic_iostream( const basic_iostream& other ) = delete; \fB(2)\fP \fI(since C++11)\fP + protected: \fB(3)\fP \fI(since C++11)\fP + basic_iostream( basic_iostream&& other ); + + Constructs new stream object. + + 1) Initializes with streambuf sb. The base classes are initialized as + basic_istream(sb) and basic_ostream(sb). After the call + rdbuf() == sb and gcount() == 0. + 2) Copy construction is not allowed. + 3) Move constructor: move-constructs the first base class basic_istream as + basic_istream(std::move(rhs));, which in turn move-constructs and + initializes the virtual base std::basic_ios. The initialization of the other base, + basic_ostream, is implementation-defined (e.g., a protected default constructor may + be added to std::basic_ostream, which does nothing) because move-construction cannot + use rhs twice. This move constructor is protected: it is called by the move + constructors of the derived stream classes std::basic_fstream and + std::basic_stringstream before they move-construct and associate the stream buffer. + +.SH Parameters + + sb - streambuf to initialize with + other - another stream to initialize with + +.SH See also + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::wiostream::operator=.3 b/man/std::wiostream::operator=.3 deleted file mode 120000 index 369964759..000000000 --- a/man/std::wiostream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::operator=.3 \ No newline at end of file diff --git a/man/std::wiostream::operator=.3 b/man/std::wiostream::operator=.3 new file mode 100644 index 000000000..7259ac957 --- /dev/null +++ b/man/std::wiostream::operator=.3 @@ -0,0 +1,29 @@ +.TH std::basic_iostream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::operator= \- std::basic_iostream::operator= + +.SH Synopsis + basic_iostream& operator=( const basic_iostream& other ) = delete; \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_iostream& operator=( basic_iostream&& other ); + + Assigns another stream object. + + 1) Copy assignment is not allowed. + 2) Move assigns another stream object. Effectively calls swap(rhs). This move + assignment operator is protected: it is called by the move assignment operators of + the derived stream classes std::basic_stringstream and std::basic_fstream which know + how to properly move-assign the associated stream buffers. + +.SH Parameters + + other - another stream to assign state of + +.SH Return value + + *this + +.SH See also + + constructor constructs the object + \fI(public member function)\fP diff --git a/man/std::wiostream::swap.3 b/man/std::wiostream::swap.3 deleted file mode 120000 index 67bc50634..000000000 --- a/man/std::wiostream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::swap.3 \ No newline at end of file diff --git a/man/std::wiostream::swap.3 b/man/std::wiostream::swap.3 new file mode 100644 index 000000000..38aeb007c --- /dev/null +++ b/man/std::wiostream::swap.3 @@ -0,0 +1,22 @@ +.TH std::basic_iostream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::swap \- std::basic_iostream::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_iostream& other ); + + Exchanges the state with another input/output stream object. Effectively calls + basic_istream::swap(other). + + This member function is protected: it is called by the swap member functions of the + derived stream classes std::basic_stringstream and std::basic_fstream, which know + how to correctly swap the associated stream buffers. + +.SH Parameters + + other - another stream to exchange the state with + +.SH Return value + + *this diff --git a/man/std::wiostream::wiostream.3 b/man/std::wiostream::wiostream.3 deleted file mode 120000 index 7d6174906..000000000 --- a/man/std::wiostream::wiostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::basic_iostream.3 \ No newline at end of file diff --git a/man/std::wiostream::wiostream.3 b/man/std::wiostream::wiostream.3 new file mode 100644 index 000000000..f7d884fef --- /dev/null +++ b/man/std::wiostream::wiostream.3 @@ -0,0 +1,34 @@ +.TH std::basic_iostream::basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::basic_iostream \- std::basic_iostream::basic_iostream + +.SH Synopsis + explicit basic_iostream( std::basic_streambuf* sb ); \fB(1)\fP + basic_iostream( const basic_iostream& other ) = delete; \fB(2)\fP \fI(since C++11)\fP + protected: \fB(3)\fP \fI(since C++11)\fP + basic_iostream( basic_iostream&& other ); + + Constructs new stream object. + + 1) Initializes with streambuf sb. The base classes are initialized as + basic_istream(sb) and basic_ostream(sb). After the call + rdbuf() == sb and gcount() == 0. + 2) Copy construction is not allowed. + 3) Move constructor: move-constructs the first base class basic_istream as + basic_istream(std::move(rhs));, which in turn move-constructs and + initializes the virtual base std::basic_ios. The initialization of the other base, + basic_ostream, is implementation-defined (e.g., a protected default constructor may + be added to std::basic_ostream, which does nothing) because move-construction cannot + use rhs twice. This move constructor is protected: it is called by the move + constructors of the derived stream classes std::basic_fstream and + std::basic_stringstream before they move-construct and associate the stream buffer. + +.SH Parameters + + sb - streambuf to initialize with + other - another stream to initialize with + +.SH See also + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP diff --git a/man/std::wiostream::~basic_iostream.3 b/man/std::wiostream::~basic_iostream.3 deleted file mode 120000 index 89c19d096..000000000 --- a/man/std::wiostream::~basic_iostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_iostream::~basic_iostream.3 \ No newline at end of file diff --git a/man/std::wiostream::~basic_iostream.3 b/man/std::wiostream::~basic_iostream.3 new file mode 100644 index 000000000..026cd1c6b --- /dev/null +++ b/man/std::wiostream::~basic_iostream.3 @@ -0,0 +1,15 @@ +.TH std::basic_iostream::~basic_iostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_iostream::~basic_iostream \- std::basic_iostream::~basic_iostream + +.SH Synopsis + virtual ~basic_iostream(); + + Destructs the input/output stream. + +.SH Notes + + This destructor does not perform any operation on the underlying stream buffer + (rdbuf()): the destructors of the derived streams such as std::basic_fstream and + std::basic_stringstream are responsible for calling the destructors of the stream + buffers. diff --git a/man/std::wistream.3 b/man/std::wistream.3 deleted file mode 120000 index fd729d8c8..000000000 --- a/man/std::wistream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream.3 \ No newline at end of file diff --git a/man/std::wistream.3 b/man/std::wistream.3 new file mode 100644 index 000000000..1212d3f28 --- /dev/null +++ b/man/std::wistream.3 @@ -0,0 +1,281 @@ +.TH std::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream \- std::basic_istream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_istream : virtual public std::basic_ios + + The class template basic_istream provides support for high level input operations on + character streams. The supported operations include formatted input (e.g. integer + values or whitespace-separated characters and characters strings) and unformatted + input (e.g. raw characters and character arrays). This functionality is implemented + in terms of the interface provided by the underlying basic_streambuf class, accessed + through the basic_ios base class. The only non-inherited data member of + basic_istream, in most implementations, is the value returned by + basic_istream::gcount(). + + std-basic istream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::istream std::basic_istream + std::wistream std::basic_istream + +.SH Global objects + + Two global basic_istream objects are provided by the standard library. + + Defined in header + cin reads from the standard C input stream stdin + wcin (global object) + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Formatted input + operator>> extracts formatted data + \fI(public member function)\fP +.SH Unformatted input + get extracts characters + \fI(public member function)\fP + peek reads the next character without extracting it + \fI(public member function)\fP + unget unextracts a character + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function)\fP + getline extracts characters until the given character is found + \fI(public member function)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function)\fP + read extracts blocks of characters + \fI(public member function)\fP + readsome extracts already available blocks of characters + \fI(public member function)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function)\fP + seekg sets the input position indicator + \fI(public member function)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function)\fP + swap swaps stream objects, except for the associated buffer + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class)\fP + +.SH Non-member functions + + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::wistream::basic_istream.3 b/man/std::wistream::basic_istream.3 deleted file mode 120000 index e902b6c6d..000000000 --- a/man/std::wistream::basic_istream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::basic_istream.3 \ No newline at end of file diff --git a/man/std::wistream::basic_istream.3 b/man/std::wistream::basic_istream.3 new file mode 100644 index 000000000..102f3fc85 --- /dev/null +++ b/man/std::wistream::basic_istream.3 @@ -0,0 +1,52 @@ +.TH std::basic_istream::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::basic_istream \- std::basic_istream::basic_istream + +.SH Synopsis + explicit basic_istream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_istream( const basic_istream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_istream( basic_istream&& rhs ); + + 1) Constructs the basic_istream object, assigning initial values to the base class + by calling basic_ios::init(sb). The value of gcount() is initialized to zero. + + 2) The copy constructor is protected, and is deleted. Input streams are not + copyable. + + 3) The move constructor copies the value of gcount() from rhs, sets the gcount() + value of rhs to zero, and uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable input + stream classes std::basic_ifstream and std::basic_istringstream, which know how to + correctly move the associated stream buffer. + +.SH Parameters + + sb - streambuffer to use as underlying device + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("hello"); + std::istream s2(s1.rdbuf()); // OK: s2 shares the buffer with s1 + + // std::istream s3(std::istringstream("test")); // ERROR: move constructor is protected + // std::istream s4(s2); // ERROR: copy constructor is deleted + std::istringstream s5(std::istringstream("world")); // OK: move ctor called + // by derived class + + std::cout << s2.rdbuf() << ' ' << s5.rdbuf() << '\\n'; + } + +.SH Output: + + hello world diff --git a/man/std::wistream::gcount.3 b/man/std::wistream::gcount.3 deleted file mode 120000 index 72c91ada0..000000000 --- a/man/std::wistream::gcount.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::gcount.3 \ No newline at end of file diff --git a/man/std::wistream::gcount.3 b/man/std::wistream::gcount.3 new file mode 100644 index 000000000..434789c51 --- /dev/null +++ b/man/std::wistream::gcount.3 @@ -0,0 +1,68 @@ +.TH std::basic_istream::gcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::gcount \- std::basic_istream::gcount + +.SH Synopsis + std::streamsize gcount() const; + + Returns the number of characters extracted by the last unformatted input operation, + or the maximum representable value of std::streamsize if the number is not + representable. + + The following member functions of basic_istream change the value of subsequent + gcount() calls: + + * move constructor + * swap() + * get() + * getline() + * ignore() + * read() + * readsome() + * operator>>(basic_streambuf*) + + The following functions set gcount() to zero: + + * constructor + * putback() + * unget() + * peek() + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters extracted by the last unformatted input operation, or the + maximum representable value of std::streamsize if the number is not representable. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char x[20]; + std::istringstream stream("Hello World"); + + stream.read(x, sizeof x); + std::cout << "Characters extracted: " << stream.gcount(); + } + +.SH Output: + + Characters extracted: 11 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3464 C++98 the return value was unspecified when the returns the maximum + result overflows value diff --git a/man/std::wistream::get.3 b/man/std::wistream::get.3 deleted file mode 120000 index 656be66be..000000000 --- a/man/std::wistream::get.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::get.3 \ No newline at end of file diff --git a/man/std::wistream::get.3 b/man/std::wistream::get.3 new file mode 100644 index 000000000..fca8f370b --- /dev/null +++ b/man/std::wistream::get.3 @@ -0,0 +1,126 @@ +.TH std::basic_istream::get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::get \- std::basic_istream::get + +.SH Synopsis + int_type get(); \fB(1)\fP + basic_istream& get( char_type& ch ); \fB(2)\fP + basic_istream& get( char_type* s, std::streamsize count ); \fB(3)\fP + basic_istream& get( char_type* s, std::streamsize count, char_type delim ); \fB(4)\fP + basic_istream& get( basic_streambuf& strbuf ); \fB(5)\fP + basic_istream& get( basic_streambuf& strbuf, char_type delim ); \fB(6)\fP + + Extracts character or characters from stream. + + All versions behave as UnformattedInputFunctions. After constructing and checking + the sentry object, these functions perform the following: + + 1) Reads one character and returns it if available. Otherwise, returns Traits::eof() + and sets failbit and eofbit. + 2) Reads one character and stores it to ch if available. Otherwise, leaves ch + unmodified and sets failbit and eofbit. Note that this function is not overloaded on + the types signed char and unsigned char, unlike the formatted character input + operator>>. + 3) Same as get(s, count, widen('\\n')), that is, reads at most std::max(0, count - 1) + characters and stores them into character string pointed to by s until '\\n' is + found. + 4) Reads characters and stores them into the successive locations of the character + array whose first element is pointed to by s. Characters are extracted and stored + until any of the following occurs: + * count is less than 1 or count - 1 characters have been stored. + * end of file condition occurs in the input sequence (setstate(eofbit) is called). + * the next available input character c equals delim, as determined by + Traits::eq(c, delim). This character is not extracted (unlike getline()). + In any case, if count > 0, a null character (CharT() is stored in the next + successive location of the array. + 5) Same as get(strbuf, widen('\\n')), that is, reads available characters and inserts + them to the given basic_streambuf object until '\\n' is found. + 6) Reads characters and inserts them to the output sequence controlled by the given + basic_streambuf object. Characters are extracted and inserted into strbuf until any + of the following occurs: + * end of file condition occurs in the input sequence. + * inserting into the output sequence fails (in which case the character that could + not be inserted, is not extracted). + * the next available input character c equals delim, as determined by + Traits::eq(c, delim). This character is not extracted. + * an exception occurs (in which case the exception is caught and not rethrown). + + If no characters were extracted, calls setstate(failbit). + + All versions set the value of gcount() to the number of characters extracted. + +.SH Parameters + + ch - reference to the character to write the result to + s - pointer to the character string to store the characters to + count - size of character string pointed to by s + delim - delimiting character to stop the extraction at. It is not extracted and not + stored + strbuf - stream buffer to read the content to + +.SH Return value + + 1) The extracted character or Traits::eof(). + 2-6) *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("Hello, world."); + char c1 = s1.get(); // reads 'H' + std::cout << "after reading " << c1 << ", gcount() == " << s1.gcount() << '\\n'; + + char c2; + s1.get(c2); // reads 'e' + char str[5]; + s1.get(str, 5); // reads "llo," + std::cout << "after reading " << str << ", gcount() == " << s1.gcount() << '\\n'; + + std::cout << c1 << c2 << str; + s1.get(*std::cout.rdbuf()); // reads the rest, not including '\\n' + std::cout << "\\nAfter the last get(), gcount() == " << s1.gcount() << '\\n'; + } + +.SH Output: + + after reading H, gcount() == 1 + after reading llo,, gcount() == 4 + Hello, world. + After the last get(), gcount() == 7 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the effect of overload \fB(5)\fP was get(s, corrected to + LWG 370 C++98 count, widen('\\n')), get(strbuf, widen('\\n')) + which is the effect of overload \fB(3)\fP + LWG 531 C++98 overloads (3,4) could not handle the no character is + case where count is non-positive extracted in this case + +.SH See also + + read extracts blocks of characters + \fI(public member function)\fP + operator>> extracts formatted data + \fI(public member function)\fP + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP diff --git a/man/std::wistream::getline.3 b/man/std::wistream::getline.3 deleted file mode 120000 index 228128a18..000000000 --- a/man/std::wistream::getline.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::getline.3 \ No newline at end of file diff --git a/man/std::wistream::getline.3 b/man/std::wistream::getline.3 new file mode 100644 index 000000000..f5d702dd1 --- /dev/null +++ b/man/std::wistream::getline.3 @@ -0,0 +1,107 @@ +.TH std::basic_istream::getline 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::getline \- std::basic_istream::getline + +.SH Synopsis + basic_istream& getline( char_type* s, std::streamsize count ); \fB(1)\fP + basic_istream& getline( char_type* s, std::streamsize count, char_type delim ); \fB(2)\fP + + Extracts characters from stream until end of line or the specified delimiter delim. + + The first overload is equivalent to getline(s, count, widen('\\n')). + + Behaves as UnformattedInputFunction. After constructing and checking the sentry + object, extracts characters from *this and stores them in successive locations of + the array whose first element is pointed to by s, until any of the following occurs + (tested in the order shown): + + 1. end of file condition occurs in the input sequence. + 2. the next available character c is the delimiter, as determined by Traits::eq(c, + delim). The delimiter is extracted (unlike basic_istream::get()) and counted + towards gcount(), but is not stored. + 3. count is non-positive, or count - 1 characters have been extracted + (setstate(failbit) is called in this case). + + If the function extracts no characters, failbit is set in the local error state + before setstate() is called. + + In any case, if count > 0, it then stores a null character CharT() into the next + successive location of the array and updates gcount(). + +.SH Notes + + Because condition #2 is tested before condition #3, the input line that exactly fits + the buffer does not trigger failbit. + + Because the terminating character is counted as an extracted character, an empty + input line does not trigger failbit. + +.SH Parameters + + s - pointer to the character string to store the characters to + count - size of character string pointed to by s + delim - delimiting character to stop the extraction at. It is extracted but not + stored. + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::istringstream input("abc|def|gh"); + std::vector> v; + + // note: the following loop terminates when std::ios_base::operator bool() + // on the stream returned from getline() returns false + for (std::array a; input.getline(&a[0], 4, '|');) + v.push_back(a); + + for (auto& a : v) + std::cout << &a[0] << '\\n'; + } + +.SH Output: + + abc + def + gh + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 531 C++98 std::getline could not handle the no character is + case where count is non-positive extracted in this case + +.SH See also + + getline read data from an I/O stream into a string + \fI(function template)\fP + operator>> extracts formatted data + \fI(public member function)\fP + get extracts characters + \fI(public member function)\fP + read extracts blocks of characters + \fI(public member function)\fP diff --git a/man/std::wistream::ignore.3 b/man/std::wistream::ignore.3 deleted file mode 120000 index 67e193e32..000000000 --- a/man/std::wistream::ignore.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::ignore.3 \ No newline at end of file diff --git a/man/std::wistream::ignore.3 b/man/std::wistream::ignore.3 new file mode 100644 index 000000000..3ebb6f3a3 --- /dev/null +++ b/man/std::wistream::ignore.3 @@ -0,0 +1,95 @@ +.TH std::basic_istream::ignore 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::ignore \- std::basic_istream::ignore + +.SH Synopsis + basic_istream& ignore( std::streamsize count = 1, int_type delim = Traits::eof() + ); + + Extracts and discards characters from the input stream until and including delim. + + ignore behaves as an UnformattedInputFunction. After constructing and checking the + sentry object, it extracts characters from the stream and discards them until any of + the following conditions occurs: + + * count characters were extracted. This test is disabled in the special case when + count equals std::numeric_limits::max(). + * end of file conditions occurs in the input sequence, in which case the function + calls setstate(eofbit). + * the next available character c in the input sequence is delim, as determined by + Traits::eq_int_type(Traits::to_int_type(c), delim). The delimiter character is + extracted and discarded. This test is disabled if delim is Traits::eof(). + +.SH Parameters + + count - number of characters to extract + delim - delimiting character to stop the extraction at. It is also extracted + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + The following example uses ignore to skip over non-numeric input: + + +// Run this code + + #include + #include + #include + + constexpr auto max_size = std::numeric_limits::max(); + + int main() + { + std::istringstream input("1\\n" + "some non-numeric input\\n" + "2\\n"); + for (;;) + { + int n; + input >> n; + + if (input.eof() || input.bad()) + break; + else if (input.fail()) + { + input.clear(); // unset failbit + input.ignore(max_size, '\\n'); // skip bad input + } + else + std::cout << n << '\\n'; + } + } + +.SH Output: + + 1 + 2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 172 C++98 the type of count was misspecified corrected to std::streamsize + as int + +.SH See also + + get extracts characters + \fI(public member function)\fP + getline extracts characters until the given character is found + \fI(public member function)\fP diff --git a/man/std::wistream::operator=.3 b/man/std::wistream::operator=.3 deleted file mode 120000 index f2a6f7666..000000000 --- a/man/std::wistream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::operator=.3 \ No newline at end of file diff --git a/man/std::wistream::operator=.3 b/man/std::wistream::operator=.3 new file mode 100644 index 000000000..52893b371 --- /dev/null +++ b/man/std::wistream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_istream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::operator= \- std::basic_istream::operator= + +.SH Synopsis + protected: \fB(1)\fP + basic_istream& operator=( const basic_istream& rhs ) = delete; + protected: \fB(2)\fP \fI(since C++11)\fP + basic_istream& operator=( basic_istream&& rhs ); + + 1) The copy assignment operator is protected, and is deleted. Input streams are not + CopyAssignable. + 2) The move assignment operator exchanges the gcount() values and all data members + of the base class, except for rdbuf(), with rhs, as if by calling swap(*rhs). This + move assignment operator is protected: it is only called by the move assignment + operators of the derived movable input stream classes std::basic_ifstream and + std::basic_istringstream, which know how to correctly move-assign the associated + streambuffers. + +.SH Parameters + + rhs - the basic_istream object from which to assign to *this + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1; + s1 = std::istringstream("test"); // OK + + // std::cin = std::istringstream("test"); // ERROR: 'operator=' is protected + } diff --git a/man/std::wistream::operator>>.3 b/man/std::wistream::operator>>.3 deleted file mode 120000 index 3ce9a4e0e..000000000 --- a/man/std::wistream::operator>>.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::operator>>.3 \ No newline at end of file diff --git a/man/std::wistream::operator>>.3 b/man/std::wistream::operator>>.3 new file mode 100644 index 000000000..f4a11f8af --- /dev/null +++ b/man/std::wistream::operator>>.3 @@ -0,0 +1,211 @@ +.TH std::basic_istream::operator>> 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::operator>> \- std::basic_istream::operator>> + +.SH Synopsis + basic_istream& operator>>( unsigned short& value ); \fB(1)\fP + basic_istream& operator>>( unsigned int& value ); \fB(2)\fP + basic_istream& operator>>( long& value ); \fB(3)\fP + basic_istream& operator>>( unsigned long& value ); \fB(4)\fP + basic_istream& operator>>( long long& value ); \fB(5)\fP \fI(since C++11)\fP + basic_istream& operator>>( unsigned long long& value ); \fB(6)\fP \fI(since C++11)\fP + basic_istream& operator>>( float& value ); \fB(7)\fP + basic_istream& operator>>( double& value ); \fB(8)\fP + basic_istream& operator>>( long double& value ); \fB(9)\fP + basic_istream& operator>>( bool& value ); \fB(10)\fP + basic_istream& operator>>( void*& value ); \fB(11)\fP + basic_istream& operator>>( short& value ); \fB(12)\fP + basic_istream& operator>>( int& value ); \fB(13)\fP + basic_istream& operator>>( /* extended-floating-point-type */& \fB(14)\fP (since C++23) + value ); + basic_istream& operator>>( std::ios_base& (*func)(std::ios_base&) \fB(15)\fP + ); + basic_istream& operator>>( std::basic_ios& + (*func)(std::basic_ios&) ); + basic_istream& operator>>( basic_istream& (*func)(basic_istream&) \fB(17)\fP + ); + basic_istream& operator>>( std::basic_streambuf* \fB(18)\fP + sb ); + + Extracts values from an input stream. + + 1-11) Extracts a value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a value by calling + std::num_get::get(). + 12) Extracts a short value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a long value lval by + calling std::num_get::get(). After that: + * If lval < std::numeric_limits::min(), sets failbit and stores + std::numeric_limits::min() to val. + * Otherwise, if std::numeric_limits::max() < lval, sets failbit and stores + std::numeric_limits::max() to val. + * Otherwise, stores static_cast(lval) to val. + 13) Extracts an int value potentially skipping preceding whitespace. The value is + stored to a given reference value. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts a long value lval by + calling std::num_get::get(). After that: + * If lval < std::numeric_limits::min(), sets failbit and stores + std::numeric_limits::min() to val. + * Otherwise, if std::numeric_limits::max() < lval, sets failbit and stores + std::numeric_limits::max() to val. + * Otherwise, stores static_cast(lval) to val. + 14) Extracts an extended floating-point value potentially skipping preceding + whitespace. The value is stored to a given reference value. The library provides + overloads for all cv-unqualified extended floating-point types as the referenced + type of the parameter value. + Determines the standard floating-point type FP as follows: + * If the floating-point conversion rank of /* extended-floating-point-type */ is + less than or equal to that of float, then FP is float. + * Otherwise, if the floating-point conversion rank of /* + extended-floating-point-type */ is less than or equal to that of double, then FP + is double. + * Otherwise, FP is long double. + This function behaves as a FormattedInputFunction. After constructing and checking + the sentry object, which may skip leading whitespace, extracts an FP value fval by + calling std::num_get::get(). After that: + * If fval < -std::numeric_limits::max(), sets + failbit and stores -std::numeric_limits::max() to val. + * Otherwise, if std::numeric_limits::max() < + fval, sets failbit and stores std::numeric_limits::max() to val. + * Otherwise, stores static_cast(fval) to val. + 15-17) Calls func(*this), where func is an I/O manipulator. + 18) Behaves as an UnformattedInputFunction. After constructing and checking the + sentry object, extracts all data from *this and stores it to sb. The extraction + stops if one of the following conditions are met: + + * end-of-file occurs on the input sequence; + * inserting in the output sequence fails (in which case the character to be + inserted is not extracted); + * an exception occurs (in which case the exception is caught, and only rethrown if + it inserted no characters and failbit is enabled in exceptions()). + In either case, stores the number of characters extracted in the member variable + accessed by subsequent calls to gcount(). If sb is a null pointer or if no + characters were inserted into sb, calls setstate(failbit) (which may throw + std::ios_base::failure if enabled). + + If extraction fails (e.g. if a letter was entered where a digit is expected), zero + is written to value and failbit is set. For signed integers, if extraction results + in the value too large or too small to fit in value, std::numeric_limits::max() + or std::numeric_limits::min() (respectively) is written and failbit flag is set. + For unsigned integers, if extraction results in the value too large or too small to + fit in value, std::numeric_limits::max() is written and failbit flag is set. + +.SH Parameters + + value - reference to an integer or floating-point value to store the extracted value + to + func - pointer to I/O manipulator function + sb - pointer to the stream buffer to write all the data to + +.SH Return value + + 1-16,18) *this + 17) func(*this) + +.SH Notes + + For overload \fB(14)\fP, when the extended floating-point type has a floating-point + conversion rank that is not equal to the rank of any standard floating-point type, + then double rounding during the conversion can result in inaccurate results. + std::from_chars() can be used in situations where maximum accuracy is important. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string input = "41 3.14 false hello world"; + std::istringstream stream(input); + + int n; + double f; + bool b; + + stream >> n >> f >> std::boolalpha >> b; + std::cout << "n = " << n << '\\n' + << "f = " << f << '\\n' + << "b = " << std::boolalpha << b << '\\n'; + + // extract the rest using the streambuf overload + stream >> std::cout.rdbuf(); + std::cout << '\\n'; + } + +.SH Output: + + n = 41 + f = 3.14 + b = false + hello world + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether overload \fB(18)\fP + LWG 64 C++98 can only rethrow the all exceptions caught + std::ios_base::failure thrown by can be rethrown + calling setstate(failbit) + overload (12,13) delegated the + LWG 118 C++98 extraction to num_get::get, a long value is extracted + but it does not have overloads for instead of short or int + short and int + overload \fB(18)\fP only rethrew exceptions + LWG 413 C++98 thrown while extracting corrected sb to *this + characters from sb, but characters are + extracted from *this + overload \fB(18)\fP behaved as a + LWG 567 C++98 FormattedInputFunction it behaves as an + because of the resolution of LWG issue UnformattedInputFunction + 60 + overloads (12,13) did not store the + LWG 661 C++98 extracted number stores the number if + to value due to the resolution of LWG no overflow occurs + issue 118 + LWG 696 C++98 value was unchanged on extraction set to zero or minimum/ + failure maximum values + +.SH See also + + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + operator<< performs stream input and output of bitsets + operator>> \fI(function template)\fP + operator<< serializes and deserializes a complex number + operator>> \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number engine + \fI(C++11)\fP \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number distribution + \fI(C++11)\fP \fI(function template)\fP + read extracts blocks of characters + \fI(public member function)\fP + readsome extracts already available blocks of characters + \fI(public member function)\fP + get extracts characters + \fI(public member function)\fP + extracts characters until the given character is + getline found + \fI(public member function)\fP + from_chars converts a character sequence to an integer or + \fI(C++17)\fP floating-point value + \fI(function)\fP diff --git a/man/std::wistream::peek.3 b/man/std::wistream::peek.3 deleted file mode 120000 index 156513bd1..000000000 --- a/man/std::wistream::peek.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::peek.3 \ No newline at end of file diff --git a/man/std::wistream::peek.3 b/man/std::wistream::peek.3 new file mode 100644 index 000000000..64eb5921a --- /dev/null +++ b/man/std::wistream::peek.3 @@ -0,0 +1,57 @@ +.TH std::basic_istream::peek 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::peek \- std::basic_istream::peek + +.SH Synopsis + int_type peek(); + + Behaves as UnformattedInputFunction. After constructing and testing the sentry + object, reads the next character from the input stream without extracting it. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If good() == true, returns the next character as obtained by rdbuf()->sgetc(). + + Otherwise, returns Traits::eof(). + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("Hello, world."); + char c1 = s1.peek(); + char c2 = s1.get(); + std::cout << "Peeked: " << c1 << " got: " << c2 << '\\n'; + } + +.SH Output: + + Peeked: H got: H + +.SH See also + + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function of std::basic_streambuf)\fP + get extracts characters + \fI(public member function)\fP + unget unextracts a character + \fI(public member function)\fP diff --git a/man/std::wistream::putback.3 b/man/std::wistream::putback.3 deleted file mode 120000 index 03f04c9e6..000000000 --- a/man/std::wistream::putback.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::putback.3 \ No newline at end of file diff --git a/man/std::wistream::putback.3 b/man/std::wistream::putback.3 new file mode 100644 index 000000000..6fa8681e7 --- /dev/null +++ b/man/std::wistream::putback.3 @@ -0,0 +1,90 @@ +.TH std::basic_istream::putback 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::putback \- std::basic_istream::putback + +.SH Synopsis + basic_istream& putback( char_type ch ); + + Puts the character ch back to the input stream so the next extracted character will + be ch. + + First clears eofbit, then behaves as UnformattedInputFunction. After constructing + and checking the sentry object, if rdbuf() is not null, calls + rdbuf()->sputbackc(ch), which calls rdbuf()->pbackfail(ch) if ch does not equal the + most recently extracted character. + + If rdbuf() is null or if rdbuf->sputbackc(ch) returns Traits::eof(), calls + setstate(badbit). + + In any case, sets the gcount() counter to zero. + +.SH Parameters + + ch - character to put into input stream + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + Demonstrates the difference between modifying and non-modifying putback(). + + +// Run this code + + #include + #include + + int main() + { + std::stringstream s1("Hello, world"); // IO stream + s1.get(); + if (s1.putback('Y')) // modifies the buffer + std::cout << s1.rdbuf() << '\\n'; + else + std::cout << "putback failed\\n"; + + std::cout << "--\\n"; + + std::istringstream s2("Hello, world"); // input-only stream + s2.get(); + if (s2.putback('Y')) // cannot modify input-only buffer + std::cout << s2.rdbuf() << '\\n'; + else + std::cout << "putback failed\\n"; + s2.clear(); + + std::cout << "--\\n"; + + if (s2.putback('H')) // non-modifying putback + std::cout << s2.rdbuf() << '\\n'; + else + std::cout << "putback failed\\n"; + } + +.SH Output: + + Yello, world + -- + putback failed + -- + Hello, world + +.SH See also + + sputbackc puts one character back in the input sequence + \fI(public member function of std::basic_streambuf)\fP + unget unextracts a character + \fI(public member function)\fP + peek reads the next character without extracting it + \fI(public member function)\fP diff --git a/man/std::wistream::read.3 b/man/std::wistream::read.3 deleted file mode 120000 index 08538673e..000000000 --- a/man/std::wistream::read.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::read.3 \ No newline at end of file diff --git a/man/std::wistream::read.3 b/man/std::wistream::read.3 new file mode 100644 index 000000000..50d124360 --- /dev/null +++ b/man/std::wistream::read.3 @@ -0,0 +1,98 @@ +.TH std::basic_istream::read 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::read \- std::basic_istream::read + +.SH Synopsis + basic_istream& read( char_type* s, std::streamsize count ); + + Extracts characters from stream. + + Behaves as UnformattedInputFunction. After constructing and checking the sentry + object, extracts characters and stores them into successive locations of the + character array whose first element is pointed to by s. Characters are extracted and + stored until any of the following conditions occurs: + + * count characters were extracted and stored. + * end of file condition occurs on the input sequence (in which case, + setstate(failbit|eofbit) is called). The number of successfully extracted + characters can be queried using gcount(). + +.SH Parameters + + s - pointer to the character array to store the characters to + count - number of characters to read + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + When using a non-converting locale (the default locale is non-converting), the + overrider of this function in std::basic_ifstream may be optimized for zero-copy + bulk I/O (by means of overriding std::streambuf::xsgetn). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + // read() is often used for binary I/O + std::string bin = {'\\x12', '\\x12', '\\x12', '\\x12'}; + std::istringstream raw(bin); + std::uint32_t n; + if (raw.read(reinterpret_cast(&n), sizeof n)) + std::cout << std::hex << std::showbase << n << '\\n'; + + // prepare file for next snippet + std::ofstream("test.txt", std::ios::binary) << "abcd1\\nabcd2\\nabcd3"; + + // read entire file into string + if (std::ifstream is{"test.txt", std::ios::binary | std::ios::ate}) + { + auto size = is.tellg(); + std::string str(size, '\\0'); // construct string to stream size + is.seekg(0); + if (is.read(&str[0], size)) + std::cout << str << '\\n'; + } + } + +.SH Output: + + 0x12121212 + abcd1 + abcd2 + abcd3 + +.SH See also + + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP + operator>> extracts formatted data + \fI(public member function)\fP + readsome extracts already available blocks of characters + \fI(public member function)\fP + get extracts characters + \fI(public member function)\fP + getline extracts characters until the given character is found + \fI(public member function)\fP + fread reads from a file + \fI(function)\fP diff --git a/man/std::wistream::readsome.3 b/man/std::wistream::readsome.3 deleted file mode 120000 index bd007d18f..000000000 --- a/man/std::wistream::readsome.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::readsome.3 \ No newline at end of file diff --git a/man/std::wistream::readsome.3 b/man/std::wistream::readsome.3 new file mode 100644 index 000000000..88305a46e --- /dev/null +++ b/man/std::wistream::readsome.3 @@ -0,0 +1,77 @@ +.TH std::basic_istream::readsome 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::readsome \- std::basic_istream::readsome + +.SH Synopsis + std::streamsize readsome( char_type* s, std::streamsize count ); + + Extracts up to count immediately available characters from the input stream. The + extracted characters are stored into the character array pointed to by s. + + Behaves as UnformattedInputFunction. After constructing and checking the sentry + object, + + * If rdbuf()->in_avail() == -1, calls setstate(eofbit) and extracts no characters. + * If rdbuf()->in_avail() == 0, extracts no characters. + * If rdbuf()->in_avail() > 0, extracts std::min(rdbuf()->in_avail(), count) + characters and stores them into successive locations of the character array + whose first element is pointed to by s. + +.SH Parameters + + s - pointer to the character array to store the characters to + count - maximum number of characters to read + +.SH Return value + + The number of characters actually extracted. + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + The behavior of this function is highly implementation-specific. For example, when + used with std::ifstream, some library implementations fill the underlying filebuf + with data as soon as the file is opened (and readsome() on such implementations + reads data, potentially, but not necessarily, the entire file), while other + implementations only read from file when an actual input operation is requested (and + readsome() issued after file opening never extracts any characters). Likewise, a + call to std::cin.readsome() may return all pending unprocessed console input, or may + always return zero and extract no characters. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char c[10] = {}; + std::istringstream input("This is sample text."); // std::stringbuf makes its entire + // buffer available for + // unblocking read + input.readsome(c, 5); // reads 'This ' and stores in c[0] .. c[4] + input.readsome(c, 9); // reads 'is sample' and stores in c[0] .. c[8] + std::cout << c << '\\n'; + } + +.SH Output: + + is sample + +.SH See also + + read extracts blocks of characters + \fI(public member function)\fP + in_avail obtains the number of characters immediately available in the get area + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::wistream::seekg.3 b/man/std::wistream::seekg.3 deleted file mode 120000 index de02c4c0a..000000000 --- a/man/std::wistream::seekg.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::seekg.3 \ No newline at end of file diff --git a/man/std::wistream::seekg.3 b/man/std::wistream::seekg.3 new file mode 100644 index 000000000..a468b667d --- /dev/null +++ b/man/std::wistream::seekg.3 @@ -0,0 +1,125 @@ +.TH std::basic_istream::seekg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::seekg \- std::basic_istream::seekg + +.SH Synopsis + basic_istream& seekg( pos_type pos ); \fB(1)\fP + basic_istream& seekg( off_type off, std::ios_base::seekdir dir ); \fB(2)\fP + + Sets input position indicator of the current associated streambuf object. + + Before doing anything else, seekg clears eofbit. \fI(since C++11)\fP + + seekg behaves as UnformattedInputFunction, except that gcount() is not affected. + After constructing and checking the sentry object, + + 1) if fail() != true, sets the input position indicator to absolute (relative to the + beginning of the file) value pos. Specifically, executes rdbuf()->pubseekpos(pos, + std::ios_base::in) (pubseekpos, in turn, calls seekpos of the specific buffer, such + as basic_filebuf::seekpos, basic_stringbuf::seekpos, or strstreambuf::seekpos). In + case of failure, calls setstate(std::ios_base::failbit). + 2) if fail() != true, sets the input position indicator to position off, relative to + position, defined by dir. Specifically, executes rdbuf()->pubseekoff(off, dir, + std::ios_base::in). In case of failure, calls setstate(std::ios_base::failbit). + +.SH Parameters + + pos - absolute position to set the input position indicator to + off - relative position (positive or negative) to set the input position indicator + to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + seekg(n) is not necessarily equivalent to seekg(n, ios::beg). std::basic_ifstream, + for example, requires the absolute position n to come from tellg(). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str = "Hello, world"; + std::istringstream in(str); + std::string word1, word2; + + in >> word1; + in.seekg(0); // rewind + in >> word2; + + std::cout << "word1 = " << word1 << '\\n' + << "word2 = " << word2 << '\\n'; + } + +.SH Output: + + word1 = Hello, + word2 = Hello, + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 129 C++98 there was no way to indicate a failure sets failbit on failure + LWG 136 C++98 seekg could set the output stream only sets the input stream + LWG 537 C++98 the type of off was off_type& corrected to off_type + +.SH See also + + tellg returns the input position indicator + \fI(public member function)\fP + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::wistream::sentry.3 b/man/std::wistream::sentry.3 deleted file mode 120000 index 3f06fb400..000000000 --- a/man/std::wistream::sentry.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::sentry.3 \ No newline at end of file diff --git a/man/std::wistream::sentry.3 b/man/std::wistream::sentry.3 new file mode 100644 index 000000000..57fab4d3d --- /dev/null +++ b/man/std::wistream::sentry.3 @@ -0,0 +1,139 @@ +.TH std::basic_istream::sentry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::sentry \- std::basic_istream::sentry + +.SH Synopsis + class sentry; + + An object of class basic_istream::sentry is constructed in local scope at the + beginning of each member function of std::basic_istream that performs input (both + formatted and unformatted). Its constructor prepares the input stream: checks if the + stream is already in a failed state, flushes the tie()'d output streams, skips + leading whitespace unless noskipws flag is set, and performs other + implementation-defined tasks if necessary. All cleanup, if necessary, is performed + in the destructor, so that it is guaranteed to happen if exceptions are thrown + during input. + +.SH Member types + + traits_type Traits + +.SH Member functions + + constructor constructs the sentry object. All the preparation tasks are done here + \fI(public member function)\fP + finalizes the stream object after formatted input or after exception, + destructor if necessary + \fI(public member function)\fP + operator= not copy assignable + [deleted] \fI(public member function)\fP + operator bool checks if the preparation of the stream object was successful + \fI(public member function)\fP + +std::basic_istream::sentry::sentry + + explicit sentry( std::basic_istream& is, bool noskipws = false ); + + Prepares the stream for formatted input. + + If is.good() is false, calls is.setstate(std::ios_base::failbit) and returns. + Otherwise, if is.tie() is not a null pointer, calls is.tie()->flush() to synchronize + the output sequence with external streams. This call can be suppressed if the put + area of is.tie() is empty. The implementation may defer the call to flush() until a + call of is.rdbuf()->underflow() occurs. If no such call occurs before the sentry + object is destroyed, it may be eliminated entirely. + + If noskipws is zero and is.flags() & std::ios_base::skipws is nonzero, the function + extracts and discards all whitespace characters until the next available character + is not a whitespace character (as determined by the currently imbued locale in is). + If is.rdbuf()->sbumpc() or is.rdbuf()->sgetc() returns traits::eof(), the function + calls setstate(std::ios_base::failbit | std::ios_base::eofbit) (which may throw + std::ios_base::failure). + + Additional implementation-defined preparation may take place, which may call + setstate(std::ios_base::failbit) (which may throw std::ios_base::failure). + + If after preparation is completed, is.good() == true, then any subsequent calls to + operator bool will return true. + +.SH Parameters + + is - input stream to prepare + noskipws - true if whitespace should not be skipped + +.SH Exceptions + + std::ios_base::failure if the end of file condition occurs when skipping whitespace. + +std::basic_istream::sentry::~sentry + + ~sentry(); + + Does nothing. + +std::basic_istream::sentry::operator bool + + explicit operator bool() const; + + Checks whether the preparation of the input stream was successful. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the initialization of the input stream was successful, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + char n[5]; + }; + + std::istream& operator>>(std::istream& is, Foo& f) + { + std::istream::sentry s(is); + if (s) + is.read(f.n, 5); + return is; + } + + int main() + { + std::string input = " abcde"; + std::istringstream stream(input); + Foo f; + stream >> f; + std::cout.write(f.n, 5); + std::cout << '\\n'; + } + +.SH Output: + + abcde + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 195 C++98 it was unclear whether the constructor made clear + would set eofbit + LWG 419 C++98 the constructor did not set failbit if sets failbit in this case + eofbit has been set + +.SH See also + + operator>> extracts formatted data + \fI(public member function)\fP + operator>>(std::basic_istream) extracts characters and character arrays + \fI(function template)\fP diff --git a/man/std::wistream::swap.3 b/man/std::wistream::swap.3 deleted file mode 120000 index b7cf152f2..000000000 --- a/man/std::wistream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::swap.3 \ No newline at end of file diff --git a/man/std::wistream::swap.3 b/man/std::wistream::swap.3 new file mode 100644 index 000000000..baeb989c7 --- /dev/null +++ b/man/std::wistream::swap.3 @@ -0,0 +1,42 @@ +.TH std::basic_istream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::swap \- std::basic_istream::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_istream& rhs ); + + Calls basic_ios::swap(rhs) to swap all data members of the base class except for + rdbuf(), and swaps the values of the gcount() counters between *this and rhs. This + swap function is protected: it is called by the swap functions of the swappable + input stream classes std::basic_ifstream and std::basic_istringstream, which know + how to correctly swap the associated streambuffers. + +.SH Parameters + + rhs - different basic_istream object of the same type to swap with + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream s1("hello"); + std::istringstream s2("bye"); + + s1.swap(s2); // OK, istringstream has a public swap() + std::swap(s1, s2); // OK, calls s1.swap(s2) + // std::cin.swap(s2); // ERROR: swap is a protected member + + std::cout << s1.rdbuf() << '\\n'; + } + +.SH Output: + + hello diff --git a/man/std::wistream::sync.3 b/man/std::wistream::sync.3 deleted file mode 120000 index 01cbcaef2..000000000 --- a/man/std::wistream::sync.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::sync.3 \ No newline at end of file diff --git a/man/std::wistream::sync.3 b/man/std::wistream::sync.3 new file mode 100644 index 000000000..3bba89af5 --- /dev/null +++ b/man/std::wistream::sync.3 @@ -0,0 +1,111 @@ +.TH std::basic_istream::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::sync \- std::basic_istream::sync + +.SH Synopsis + int sync(); + + Synchronizes the input buffer with the associated data source. + + Behaves as UnformattedInputFunction, except that gcount() is not affected. After + constructing and checking the sentry object, + + If rdbuf() is a null pointer, returns -1. + + Otherwise, calls rdbuf()->pubsync(). If that function returns -1, calls + setstate(badbit) and returns -1. Otherwise, returns 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 0 on success, -1 on failure or if the stream does not support this operation (is + unbuffered). + +.SH Notes + + As with readsome(), it is implementation-defined whether this function does anything + with library-supplied streams. The intent is typically for the next read operation + to pick up any changes that may have been made to the associated input sequence + after the stream buffer last filled its get area. To achieve that, sync() may empty + the get area, or it may refill it, or it may do nothing. A notable exception is + Visual Studio, where this operation discards the unprocessed input when called with + a standard input stream. + +.SH Example + + Demonstrates the use of input stream sync() with file input. Note that output here + is implementation-defined, since calls to std::basic_filebuf::sync are + implementation-defined for reads. + + +// Run this code + + #include + #include + + void file_abc() + { + std::ofstream f("test.txt"); + f << "abc\\n"; + } + + void file_123() + { + std::ofstream f("test.txt"); + f << "123\\n"; + } + + int main() + { + file_abc(); // file now contains "abc" + std::ifstream f("test.txt"); + std::cout << "Reading from the file\\n"; + char c; + f >> c; + std::cout << c; + file_123(); // file now contains "123" + f >> c; + std::cout << c; + f >> c; + std::cout << c << '\\n'; + f.close(); + + file_abc(); // file now contains "abc" + f.open("test.txt"); + std::cout << "Reading from the file, with sync()\\n"; + f >> c; + std::cout << c; + file_123(); // file now contains "123" + f.sync(); + f >> c; + std::cout << c; + f >> c; + std::cout << c << '\\n'; + } + +.SH Possible output: + + Reading from the file + abc + Reading from the file, with sync() + a23 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 62 C++98 sync() returned traits::eof() if returns -1 in this + rdbuf()->pubsync() returns -1 case + +.SH See also + + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::wistream::tellg.3 b/man/std::wistream::tellg.3 deleted file mode 120000 index 2f0fd2172..000000000 --- a/man/std::wistream::tellg.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::tellg.3 \ No newline at end of file diff --git a/man/std::wistream::tellg.3 b/man/std::wistream::tellg.3 new file mode 100644 index 000000000..54a391297 --- /dev/null +++ b/man/std::wistream::tellg.3 @@ -0,0 +1,72 @@ +.TH std::basic_istream::tellg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::tellg \- std::basic_istream::tellg + +.SH Synopsis + pos_type tellg(); + + Returns input position indicator of the current associated streambuf object. + + Behaves as UnformattedInputFunction, except that gcount() is not affected. After + constructing and checking the sentry object, if fail() == true, returns + pos_type(-1). Otherwise, returns rdbuf()->pubseekoff(0, std::ios_base::cur, + std::ios_base::in). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current position of the get pointer on success, pos_type(-1) on failure. + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str = "Hello, world"; + std::istringstream in(str); + std::string word; + in >> word; + std::cout << "After reading the word \\"" << word + << "\\" tellg() returns " << in.tellg() << '\\n'; + } + +.SH Output: + + After reading the word "Hello," tellg() returns 6 + +.SH See also + + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + seekg sets the input position indicator + \fI(public member function)\fP + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::wistream::unget.3 b/man/std::wistream::unget.3 deleted file mode 120000 index 3852e7e9e..000000000 --- a/man/std::wistream::unget.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::unget.3 \ No newline at end of file diff --git a/man/std::wistream::unget.3 b/man/std::wistream::unget.3 new file mode 100644 index 000000000..020541534 --- /dev/null +++ b/man/std::wistream::unget.3 @@ -0,0 +1,68 @@ +.TH std::basic_istream::unget 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::unget \- std::basic_istream::unget + +.SH Synopsis + basic_istream& unget(); + + Makes the most recently extracted character available again. + + First, clears eofbit. Then, + \fI(since C++11)\fP unget behaves as UnformattedInputFunction. After constructing and + checking the sentry object, if any ios_base::iostate flags are set, the function + sets failbit and returns. Otherwise, calls rdbuf()->sungetc(). + + If rdbuf()->sungetc() returns Traits::eof(), calls setstate(badbit). + + In any case, sets the gcount() counter to zero. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("Hello, world."); + char c1 = s1.get(); + if (s1.unget()) + { + char c2 = s1.get(); + std::cout << "Got: '" << c1 << "'. Got again: '" << c2 << "'.\\n"; + } + } + +.SH Output: + + Got: 'H'. Got again: 'H'. + +.SH See also + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function of std::basic_streambuf)\fP + get extracts characters + \fI(public member function)\fP + peek reads the next character without extracting it + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function)\fP diff --git a/man/std::wistream::wistream.3 b/man/std::wistream::wistream.3 deleted file mode 120000 index e902b6c6d..000000000 --- a/man/std::wistream::wistream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::basic_istream.3 \ No newline at end of file diff --git a/man/std::wistream::wistream.3 b/man/std::wistream::wistream.3 new file mode 100644 index 000000000..102f3fc85 --- /dev/null +++ b/man/std::wistream::wistream.3 @@ -0,0 +1,52 @@ +.TH std::basic_istream::basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::basic_istream \- std::basic_istream::basic_istream + +.SH Synopsis + explicit basic_istream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_istream( const basic_istream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_istream( basic_istream&& rhs ); + + 1) Constructs the basic_istream object, assigning initial values to the base class + by calling basic_ios::init(sb). The value of gcount() is initialized to zero. + + 2) The copy constructor is protected, and is deleted. Input streams are not + copyable. + + 3) The move constructor copies the value of gcount() from rhs, sets the gcount() + value of rhs to zero, and uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable input + stream classes std::basic_ifstream and std::basic_istringstream, which know how to + correctly move the associated stream buffer. + +.SH Parameters + + sb - streambuffer to use as underlying device + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::istringstream s1("hello"); + std::istream s2(s1.rdbuf()); // OK: s2 shares the buffer with s1 + + // std::istream s3(std::istringstream("test")); // ERROR: move constructor is protected + // std::istream s4(s2); // ERROR: copy constructor is deleted + std::istringstream s5(std::istringstream("world")); // OK: move ctor called + // by derived class + + std::cout << s2.rdbuf() << ' ' << s5.rdbuf() << '\\n'; + } + +.SH Output: + + hello world diff --git a/man/std::wistream::~basic_istream.3 b/man/std::wistream::~basic_istream.3 deleted file mode 120000 index dcea33ae0..000000000 --- a/man/std::wistream::~basic_istream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istream::~basic_istream.3 \ No newline at end of file diff --git a/man/std::wistream::~basic_istream.3 b/man/std::wistream::~basic_istream.3 new file mode 100644 index 000000000..132879f14 --- /dev/null +++ b/man/std::wistream::~basic_istream.3 @@ -0,0 +1,44 @@ +.TH std::basic_istream::~basic_istream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istream::~basic_istream \- std::basic_istream::~basic_istream + +.SH Synopsis + virtual ~basic_istream(); + + Destructs the input stream. + +.SH Notes + + This destructor does not perform any operation on the underlying streambuffer + (rdbuf()): the destructors of the derived input streams such as std::basic_ifstream + and std::basic_istringstream are responsible for calling the destructors of the + streambuffers. + +.SH Example + + +// Run this code + + #include + #include + + void print_stringbuf(std::streambuf* p) + { + std::istream buf(p); // buf shares the buffer with s1 + int n; + buf >> n; + std::cout << n; + } // calls the destructor of buf. p remains unaffected + + int main() + { + std::istringstream s1("10 20"); + print_stringbuf(s1.rdbuf()); + int n; + s1 >> n; + std::cout << ',' << n << '\\n'; + } + +.SH Output: + + 10,20 diff --git a/man/std::wistringstream.3 b/man/std::wistringstream.3 deleted file mode 120000 index 62dbcf204..000000000 --- a/man/std::wistringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream.3 \ No newline at end of file diff --git a/man/std::wistringstream.3 b/man/std::wistringstream.3 new file mode 100644 index 000000000..ec453448b --- /dev/null +++ b/man/std::wistringstream.3 @@ -0,0 +1,291 @@ +.TH std::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream \- std::basic_istringstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + + > class basic_istringstream : public basic_istream; + + The class template std::basic_istringstream implements input operations on string + based streams. It effectively stores an instance of std::basic_string and performs + input operations on it. + + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_istream. The + complete interface to unique std::basic_stringbuf members is provided. + + std-basic istringstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::istringstream std::basic_istringstream + std::wistringstream std::basic_istringstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) + +.SH Member functions + + constructor constructs the string stream + \fI(public member function)\fP + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP +.SH String operations + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_istringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::wistringstream::basic_istringstream.3 b/man/std::wistringstream::basic_istringstream.3 deleted file mode 120000 index 177d568db..000000000 --- a/man/std::wistringstream::basic_istringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::basic_istringstream.3 \ No newline at end of file diff --git a/man/std::wistringstream::basic_istringstream.3 b/man/std::wistringstream::basic_istringstream.3 new file mode 100644 index 000000000..f9d4b1964 --- /dev/null +++ b/man/std::wistringstream::basic_istringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_istringstream::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::basic_istringstream \- std::basic_istringstream::basic_istringstream + +.SH Synopsis + explicit basic_istringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::in ); + explicit basic_istringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_istringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_istringstream(std::ios_base::in) {} + explicit basic_istringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + explicit basic_istringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + basic_istringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_istringstream(str, std::ios_base::in, a) {} + template< class SAlloc > + + explicit basic_istringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + explicit basic_istringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + basic_istringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_istringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_istringstream( basic_istringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_istream, and + * buf_type as std::basic_stringbuf, + + the std::basic_istream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_istream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::in) + \fB(2)\fP buf_type(std::ios_base::in) + \fB(3)\fP buf_type(str, mode | + std::ios_base::in) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::in) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::in, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::in, a) + \fB(7)\fP buf_type(str, std::ios_base::in, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::in) + \fB(9)\fP {t, mode | std::ios_base::in, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::in, a} + \fB(11)\fP {t, std::ios_base::in, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_istream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_istringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::wistringstream::operator=.3 b/man/std::wistringstream::operator=.3 deleted file mode 120000 index 9efda0c42..000000000 --- a/man/std::wistringstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::operator=.3 \ No newline at end of file diff --git a/man/std::wistringstream::operator=.3 b/man/std::wistringstream::operator=.3 new file mode 100644 index 000000000..dcd3081c3 --- /dev/null +++ b/man/std::wistringstream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_istringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::operator= \- std::basic_istringstream::operator= + +.SH Synopsis + basic_istringstream& operator=( basic_istringstream&& other ); \fI(since C++11)\fP + + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_istream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. + +.SH Parameters + + other - string stream to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + operator= move-assigns from another basic_istream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wistringstream::rdbuf.3 b/man/std::wistringstream::rdbuf.3 deleted file mode 120000 index a05793396..000000000 --- a/man/std::wistringstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::wistringstream::rdbuf.3 b/man/std::wistringstream::rdbuf.3 new file mode 100644 index 000000000..2718198e0 --- /dev/null +++ b/man/std::wistringstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_istringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::rdbuf \- std::basic_istringstream::rdbuf + +.SH Synopsis + std::basic_stringbuf* rdbuf() const; + + Returns pointer to the underlying raw string device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw string device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wistringstream::str.3 b/man/std::wistringstream::str.3 deleted file mode 120000 index eda984c76..000000000 --- a/man/std::wistringstream::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::str.3 \ No newline at end of file diff --git a/man/std::wistringstream::str.3 b/man/std::wistringstream::str.3 new file mode 100644 index 000000000..3c092e8bd --- /dev/null +++ b/man/std::wistringstream::str.3 @@ -0,0 +1,99 @@ +.TH std::basic_istringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::str \- std::basic_istringstream::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Manages the contents of the underlying string object. + + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. + +.SH Parameters + + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string + +.SH Return value + + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP + +.SH Notes + + The copy of the underlying string returned by str is a temporary object that will be + destructed at the end of the expression, so directly calling c_str() on the result + of str() (for example in auto *ptr = out.str().c_str();) results in a dangling + pointer. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.str("1 2"); + in >> n; + std::cout << "After reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.str() << "\\"\\n"; + + std::ostringstream out("1 2"); + out << 3; + std::cout << "After writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); + ate << 3; + std::cout << "After writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" + +.SH See also + + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::wistringstream::swap.3 b/man/std::wistringstream::swap.3 deleted file mode 120000 index 50cec1adf..000000000 --- a/man/std::wistringstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::swap.3 \ No newline at end of file diff --git a/man/std::wistringstream::swap.3 b/man/std::wistringstream::swap.3 new file mode 100644 index 000000000..c7cccfc1e --- /dev/null +++ b/man/std::wistringstream::swap.3 @@ -0,0 +1,39 @@ +.TH std::basic_istringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::swap \- std::basic_istringstream::swap + +.SH Synopsis + void swap( basic_istringstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_istream::swap(other) and + rdbuf()->swap(*other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::wistringstream::view.3 b/man/std::wistringstream::view.3 new file mode 100644 index 000000000..06eecf651 --- /dev/null +++ b/man/std::wistringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_istringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::view \- std::basic_istringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::wistringstream::wistringstream.3 b/man/std::wistringstream::wistringstream.3 deleted file mode 120000 index 177d568db..000000000 --- a/man/std::wistringstream::wistringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_istringstream::basic_istringstream.3 \ No newline at end of file diff --git a/man/std::wistringstream::wistringstream.3 b/man/std::wistringstream::wistringstream.3 new file mode 100644 index 000000000..f9d4b1964 --- /dev/null +++ b/man/std::wistringstream::wistringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_istringstream::basic_istringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_istringstream::basic_istringstream \- std::basic_istringstream::basic_istringstream + +.SH Synopsis + explicit basic_istringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::in ); + explicit basic_istringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_istringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_istringstream(std::ios_base::in) {} + explicit basic_istringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + explicit basic_istringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + basic_istringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_istringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_istringstream(str, std::ios_base::in, a) {} + template< class SAlloc > + + explicit basic_istringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + explicit basic_istringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in ); + template< class StringViewLike > + + basic_istringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_istringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_istringstream( basic_istringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_istream, and + * buf_type as std::basic_stringbuf, + + the std::basic_istream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_istream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::in) + \fB(2)\fP buf_type(std::ios_base::in) + \fB(3)\fP buf_type(str, mode | + std::ios_base::in) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::in) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::in, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::in, a) + \fB(7)\fP buf_type(str, std::ios_base::in, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::in) + \fB(9)\fP {t, mode | std::ios_base::in, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::in, a} + \fB(11)\fP {t, std::ios_base::in, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_istream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_istringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::wmemchr.3 b/man/std::wmemchr.3 index bf3a788f5..502f29d79 100644 --- a/man/std::wmemchr.3 +++ b/man/std::wmemchr.3 @@ -1,38 +1,66 @@ -.TH std::wmemchr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wmemchr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wmemchr \- std::wmemchr + .SH Synopsis Defined in header - const wchar_t* wmemchr( const wchar_t* ptr, wchar_t ch, std::size_t count ); - wchar_t* wmemchr( wchar_t* ptr, wchar_t ch, std::size_t count ); + const wchar_t* wmemchr( const wchar_t* ptr, wchar_t ch, std::size_t count ); \fB(1)\fP + wchar_t* wmemchr( wchar_t* ptr, wchar_t ch, std::size_t count ); \fB(2)\fP Locates the first occurrence of wide character ch in the initial count wide - characters of the object pointed to by ptr. + characters of the wide character array pointed to by ptr. + + If count is zero, the function returns a null pointer. .SH Parameters - ptr - pointer to the object to be examined + ptr - pointer to the wide character array to be examined ch - wide character to search for - count - number of characters to examine + count - number of wide characters to examine .SH Return value - Pointer to the location of the character, or NULL if no such character is found. + Pointer to the location of the wide character, or a null pointer if no such + character is found. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + const wchar_t str[] = L"诺不轻信，故人不负我\\0诺不轻许，故我不负人。"; + wchar_t target = L'许'; + const std::size_t sz = sizeof str / sizeof *str; + if (const wchar_t* result = std::wmemchr(str, target, sz)) + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << "Found '" << target << "' at position " << result - str << '\\n'; + } + } + +.SH Possible output: + + Found '许' at position 14 .SH See also + memchr searches an array for the first occurrence of a character + \fI(function)\fP + strchr finds the first occurrence of a character + \fI(function)\fP wcschr finds the first occurrence of a wide character in a wide string - \fI(function)\fP + \fI(function)\fP find find_if finds the first element satisfying specific criteria - find_if_not \fI(function template)\fP + find_if_not \fI(function template)\fP \fI(C++11)\fP C documentation for wmemchr - -.SH Category: - - * Todo no example diff --git a/man/std::wmemcmp.3 b/man/std::wmemcmp.3 index d1311cdbd..3e24793a7 100644 --- a/man/std::wmemcmp.3 +++ b/man/std::wmemcmp.3 @@ -1,38 +1,93 @@ -.TH std::wmemcmp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wmemcmp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wmemcmp \- std::wmemcmp + .SH Synopsis Defined in header int wmemcmp( const wchar_t* lhs, const wchar_t* rhs, std::size_t count ); - Compares the first count wide characters of the objects pointed to by lhs and rhs. - The comparison is done lexicographically. + Compares the first count wide characters of the wide character arrays pointed to by + lhs and rhs. The comparison is done lexicographically. + + The sign of the result is the sign of the difference between the values of the first + pair of wide characters that differ in the arrays being compared. + + If count is zero, the function does nothing. .SH Parameters - lhs, rhs - pointers to the memory buffers to compare - count - number of bytes to examine + lhs, rhs - pointers to the wide character arrays to compare + count - number of wide characters to examine .SH Return value - Negative value if lhs is less than rhs. + Negative value if the value of the first differing wide character in lhs is less + than the value of the corresponding wide character in rhs: lhs precedes rhs in + lexicographical order. + + 0 if all count wide characters of lhs and rhs are equal. - 0 if lhs is equal to rhs. + Positive value if the value of the first differing wide character in lhs is greater + than the value of the corresponding wide character in rhs: rhs precedes lhs in + lexicographical order. - Positive value if lhs is greater than rhs. +.SH Notes + + This function is not locale-sensitive and pays no attention to the values of the + wchar_t objects it examines: nulls as well as invalid wide characters are compared + too. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + void demo(const wchar_t* lhs, const wchar_t* rhs, std::size_t sz) + { + std::wcout << std::wstring(lhs, sz); + int rc = std::wmemcmp(lhs, rhs, sz); + if (rc == 0) + std::wcout << " compares equal to "; + else if (rc < 0) + std::wcout << " precedes "; + else if (rc > 0) + std::wcout << " follows "; + std::wcout << std::wstring(rhs, sz) << " in lexicographical order\\n"; + } + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + + wchar_t a1[] = {L'α',L'β',L'γ'}; + constexpr std::size_t sz = sizeof a1 / sizeof *a1; + wchar_t a2[sz] = {L'α',L'β',L'δ'}; + + demo(a1, a2, sz); + demo(a2, a1, sz); + demo(a1, a1, sz); + } + +.SH Possible output: + + αβγ precedes αβδ in lexicographical order + αβδ follows αβγ in lexicographical order + αβγ compares equal to αβγ in lexicographical order .SH See also wcscmp compares two wide strings - \fI(function)\fP + \fI(function)\fP + memcmp compares two buffers + \fI(function)\fP wcsncmp compares a certain amount of characters from two wide strings - \fI(function)\fP + \fI(function)\fP C documentation for wmemcmp - -.SH Category: - - * Todo no example diff --git a/man/std::wmemcpy.3 b/man/std::wmemcpy.3 index 4125895e2..4eb485398 100644 --- a/man/std::wmemcpy.3 +++ b/man/std::wmemcpy.3 @@ -1,43 +1,75 @@ -.TH std::wmemcpy 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wmemcpy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wmemcpy \- std::wmemcpy + .SH Synopsis Defined in header wchar_t* wmemcpy( wchar_t* dest, const wchar_t* src, std::size_t count ); - Copies count wide characters from the object pointed to by src to the object pointed - to by dest. If the objects overlap, the behavior is undefined. If the objects are - not trivially copyable (scalars, arrays, C-compatible structs), the behavior is - undefined. + Copies exactly count successive wide characters from the wide character array + pointed to by src to the wide character array pointed to by dest. If the objects + overlap, the behavior is undefined. If count is zero, the function does nothing. .SH Parameters - dest - pointer to the memory location to copy to - src - pointer to the memory location to copy from + dest - pointer to the wide character array to copy to + src - pointer to the wide character array to copy from count - number of wide characters to copy .SH Return value dest +.SH Notes + + This function's analog for byte strings is std::strncpy, not std::strcpy. + + This function is not locale-sensitive and pays no attention to the values of the + wchar_t objects it copies: nulls as well as invalid characters are copied too. + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + + int main(void) + { + const wchar_t from1[] = L"नमसत"; + const wchar_t from2[] = L"Բարև"; + const std::size_t sz1 = std::size(from1); + const std::size_t sz2 = std::size(from2); + wchar_t to[sz1 + sz2]; + + std::wmemcpy(to, from1, sz1); // copy from1, along with its null terminator + std::wmemcpy(to + sz1, from2, sz2); // append from2, along with its null terminator + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << L"Wide array contains: "; + for (std::size_t n = 0; n < std::size(to); ++n) + if (to[n]) + std::wcout << to[n]; + else + std::wcout << L"\\\\0"; + std::wcout << L'\\n'; + } + +.SH Possible output: + + Wide array contains: नमसत\\0Բարև\\0 .SH See also - copies a certain amount of wide characters between two, - wmemmove possibly overlapping, arrays - \fI(function)\fP - copy copies a range of elements to a new location - copy_if \fI(function template)\fP - \fI(C++11)\fP - copy_backward copies a range of elements in backwards order - \fI(function template)\fP - is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + strncpy copies a certain amount of characters from one string to another + \fI(function)\fP + copies a certain amount of wide characters between two, possibly + wmemmove overlapping, arrays + \fI(function)\fP C documentation for wmemcpy - -.SH Category: - - * Todo no example diff --git a/man/std::wmemmove.3 b/man/std::wmemmove.3 index 00f8743f9..75db4836c 100644 --- a/man/std::wmemmove.3 +++ b/man/std::wmemmove.3 @@ -1,44 +1,71 @@ -.TH std::wmemmove 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wmemmove 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wmemmove \- std::wmemmove + .SH Synopsis Defined in header wchar_t* wmemmove( wchar_t* dest, const wchar_t* src, std::size_t count ); - Copies count wide characters from the object pointed to by src to the object pointed - to by dest. The objects may overlap: copying takes place as if the characters were - copied to a temporary character array and then the characters were copied from the - array to dest. If the objects are not trivially-copyable (scalars, arrays, C-style - structs), the behavior is undefined. + Copies exactly count successive wide characters from the wide character array + pointed to by src to the wide character array pointed to by dest. + + If count is zero, the function does nothing. + + The arrays may overlap: copying takes place as if the wide characters were copied to + a temporary wide character array and then copied from the temporary array to dest. .SH Parameters - dest - pointer to the memory location to copy to - src - pointer to the memory location to copy from - count - number of bytes to copy + dest - pointer to the wide character array to copy to + src - pointer to the wide character array to copy from + count - number of wide characters to copy .SH Return value - dest + Returns a copy of dest. + +.SH Notes + + This function is not locale-sensitive and pays no attention to the values of the + wchar_t objects it copies: nulls as well as invalid characters are copied too. .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + + wchar_t str[] = L"αβγδεζηθικλμνξοπρστυφχψω"; + std::wcout << str << '\\n'; + std::wmemmove(str + 4, str + 3, 3); // copy from [δεζ] to [εζη] + std::wcout << str << '\\n'; + } + +.SH Possible output: + + αβγδεζηθικλμνξοπρστυφχψω + αβγδδεζθικλμνξοπρστυφχψω .SH See also - copies a certain amount of wide characters between two - wmemcpy non-overlapping arrays - \fI(function)\fP - copy copies a range of elements to a new location - copy_if \fI(function template)\fP + copies a certain amount of wide characters between two non-overlapping + wmemcpy arrays + \fI(function)\fP + memmove moves one buffer to another + \fI(function)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP \fI(C++11)\fP - copy_backward copies a range of elements in backwards order - \fI(function template)\fP - is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + copy_backward copies a range of elements in backwards order + \fI(function template)\fP C documentation for wmemmove - -.SH Category: - - * Todo no example diff --git a/man/std::wmemset.3 b/man/std::wmemset.3 index 18c0d075a..8b544a19e 100644 --- a/man/std::wmemset.3 +++ b/man/std::wmemset.3 @@ -1,50 +1,66 @@ -.TH std::wmemset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wmemset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wmemset \- std::wmemset + .SH Synopsis Defined in header wchar_t* wmemset( wchar_t* dest, wchar_t ch, std::size_t count ); - Copies wide character ch into each of the first count wide characters of the object - pointed to by dest. If the object is not trivially-copyable (e.g., scalar, array, or - a C-compatible struct), the behavior is undefined. If dest+size+1 points outside the - object, the behavior is undefined. + Copies the wide character ch into each of the first count wide characters of the + wide character array pointed to by dest. + + If overflow occurs, the behavior is undefined. + + If count is zero, the function does nothing. .SH Parameters - dest - pointer to the object to fill - ch - fill byte + dest - pointer to the wide character array to fill + ch - fill wide character count - number of wide characters to fill .SH Return value - dest + Returns a copy of dest. + +.SH Notes + + This function is not locale-sensitive and pays no attention to the values of the + wchar_t objects it writes: nulls as well as invalid wide characters are written too. .SH Example - + // Run this code - #include + #include #include - + #include + #include + int main() { - int a[20]; - std::memset(a, 0, sizeof(a)); - std::cout << "a[0] = " << a[0] << '\\n'; + wchar_t ar[4] = {L'1', L'2', L'3', L'4'}; + std::wmemset(ar, L'\\U0001f34c', 2); // replaces [12] with the 🍌 bananas + std::wmemset(ar + 2, L'蕉', 2); // replaces [34] with the 蕉 bananas + + std::setlocale(LC_ALL, "en_US.utf8"); + std::wcout.imbue(std::locale("en_US.utf8")); + std::wcout << std::wstring(ar, 4) << '\\n'; } -.SH Output: +.SH Possible output: - a[0] = 0 + 🍌🍌蕉蕉 .SH See also - copies a certain amount of wide characters between two - wmemcpy non-overlapping arrays - \fI(function)\fP - fill_n assigns a value to a number of elements - \fI(function template)\fP - is_trivially_copyable checks if a type is trivially copyable - \fI(C++11)\fP \fI(class template)\fP + memset fills a buffer with a character + \fI(function)\fP + copies a certain amount of wide characters between two non-overlapping + wmemcpy arrays + \fI(function)\fP + fill_n copy-assigns the given value to N elements in a range + \fI(function template)\fP C documentation for wmemset diff --git a/man/std::wofstream.3 b/man/std::wofstream.3 deleted file mode 120000 index 5f2b97682..000000000 --- a/man/std::wofstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream.3 \ No newline at end of file diff --git a/man/std::wofstream.3 b/man/std::wofstream.3 new file mode 100644 index 000000000..110ede1ad --- /dev/null +++ b/man/std::wofstream.3 @@ -0,0 +1,313 @@ +.TH std::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream \- std::basic_ofstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_ofstream : public std::basic_ostream + + The class template basic_ofstream implements high-level output operations on file + based streams. It interfaces a file-based streambuffer (std::basic_filebuf) with the + high-level interface of (std::basic_ostream). + + A typical implementation of std::basic_ofstream holds only one non-derived data + member: an instance of std::basic_filebuf. + + std-basic ofstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ofstream std::basic_ofstream + std::wofstream std::basic_ofstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + + constructor constructs the file stream + \fI(public member function)\fP + destructor destructs the basic_ofstream and the associated + \fB[virtual]\fP (implicitly declared) buffer, closes the file + \fI(virtual public member function)\fP + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw file device object + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP +.SH File operations + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ofstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "Test.b"; + { + std::ofstream ostrm(filename, std::ios::binary); + double d = 3.14; + ostrm.write(reinterpret_cast(&d), sizeof d); // binary output + ostrm << 123 << "abc" << '\\n'; // text output + } + + // read back + std::ifstream istrm(filename, std::ios::binary); + double d; + istrm.read(reinterpret_cast(&d), sizeof d); + int n; + std::string s; + istrm >> n >> s; + std::cout << " read back: " << d << ' ' << n << ' ' << s << '\\n'; + } + +.SH Output: + + read back: 3.14 123 abc diff --git a/man/std::wofstream::basic_ofstream.3 b/man/std::wofstream::basic_ofstream.3 deleted file mode 120000 index 8c9dd85ea..000000000 --- a/man/std::wofstream::basic_ofstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::basic_ofstream.3 \ No newline at end of file diff --git a/man/std::wofstream::basic_ofstream.3 b/man/std::wofstream::basic_ofstream.3 new file mode 100644 index 000000000..da7885226 --- /dev/null +++ b/man/std::wofstream::basic_ofstream.3 @@ -0,0 +1,105 @@ +.TH std::basic_ofstream::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::basic_ofstream \- std::basic_ofstream::basic_ofstream + +.SH Synopsis + basic_ofstream(); \fB(1)\fP + explicit basic_ofstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::out ); + explicit basic_ofstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + explicit basic_ofstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + template< class FsPath > + + explicit basic_ofstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + basic_ofstream( basic_ofstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ofstream( const basic_ofstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out) + (see std::basic_filebuf::open for the details on the effects of that call). If the + open() call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ofstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP Note that despite the default mode being out, the effects are + identical to the effects of out | trunc as described in std::filebuf::open + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ofstream f0; + std::ofstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ofstream f2(name); + std::ofstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::wofstream::close.3 b/man/std::wofstream::close.3 deleted file mode 120000 index aeefa2790..000000000 --- a/man/std::wofstream::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::close.3 \ No newline at end of file diff --git a/man/std::wofstream::close.3 b/man/std::wofstream::close.3 new file mode 100644 index 000000000..10d285365 --- /dev/null +++ b/man/std::wofstream::close.3 @@ -0,0 +1,41 @@ +.TH std::basic_ofstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::close \- std::basic_ofstream::close + +.SH Synopsis + void close(); + + Closes the associated file. + + Effectively calls rdbuf()->close(). If an error occurs during operation, + setstate(failbit) is called. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called by the destructor of basic_ofstream when the stream object + goes out of scope and is not usually invoked directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wofstream::is_open.3 b/man/std::wofstream::is_open.3 deleted file mode 120000 index 26fdd95f8..000000000 --- a/man/std::wofstream::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::is_open.3 \ No newline at end of file diff --git a/man/std::wofstream::is_open.3 b/man/std::wofstream::is_open.3 new file mode 100644 index 000000000..5a01690a2 --- /dev/null +++ b/man/std::wofstream::is_open.3 @@ -0,0 +1,42 @@ +.TH std::basic_ofstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::is_open \- std::basic_ofstream::is_open + +.SH Synopsis + bool is_open() const; + + Checks if the file stream has an associated file. + + Effectively calls rdbuf()->is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the file stream has an associated file, false otherwise. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wofstream::native_handle.3 b/man/std::wofstream::native_handle.3 new file mode 100644 index 000000000..12d8567f1 --- /dev/null +++ b/man/std::wofstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_ofstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::native_handle \- std::basic_ofstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::wofstream::open.3 b/man/std::wofstream::open.3 deleted file mode 120000 index 8cd5c2ea1..000000000 --- a/man/std::wofstream::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::open.3 \ No newline at end of file diff --git a/man/std::wofstream::open.3 b/man/std::wofstream::open.3 new file mode 100644 index 000000000..6a9ce65d0 --- /dev/null +++ b/man/std::wofstream::open.3 @@ -0,0 +1,84 @@ +.TH std::basic_ofstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::open \- std::basic_ofstream::open + +.SH Synopsis + void open( const char* filename, + + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::out ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::out ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + void open( const std::filesystem::path& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP + + = std::ios_base::out ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode | ios_base::out) (see + std::basic_filebuf::open for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. It is a BitmaskType, the following constants + are defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + + 1. ↑ The resolution of LWG issue #22 is overriden. + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wofstream::operator=.3 b/man/std::wofstream::operator=.3 deleted file mode 120000 index 299f7622b..000000000 --- a/man/std::wofstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::operator=.3 \ No newline at end of file diff --git a/man/std::wofstream::operator=.3 b/man/std::wofstream::operator=.3 new file mode 100644 index 000000000..ca3f0660e --- /dev/null +++ b/man/std::wofstream::operator=.3 @@ -0,0 +1,37 @@ +.TH std::basic_ofstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::operator= \- std::basic_ofstream::operator= + +.SH Synopsis + basic_ofstream& operator=( basic_ofstream&& other ); \fI(since C++11)\fP + + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_ostream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. + +.SH Parameters + + other - file stream to move + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wofstream::rdbuf.3 b/man/std::wofstream::rdbuf.3 deleted file mode 120000 index 65b579c1e..000000000 --- a/man/std::wofstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::wofstream::rdbuf.3 b/man/std::wofstream::rdbuf.3 new file mode 100644 index 000000000..e03acd59c --- /dev/null +++ b/man/std::wofstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_ofstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::rdbuf \- std::basic_ofstream::rdbuf + +.SH Synopsis + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP + + Returns pointer to the underlying raw file device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw file device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wofstream::swap.3 b/man/std::wofstream::swap.3 deleted file mode 120000 index 78859fc68..000000000 --- a/man/std::wofstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::swap.3 \ No newline at end of file diff --git a/man/std::wofstream::swap.3 b/man/std::wofstream::swap.3 new file mode 100644 index 000000000..14bbf7c8d --- /dev/null +++ b/man/std::wofstream::swap.3 @@ -0,0 +1,81 @@ +.TH std::basic_ofstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::swap \- std::basic_ofstream::swap + +.SH Synopsis + void swap( basic_ofstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_ostream::swap(other) and + rdbuf()->swap(other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" + +.SH See also + + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::wofstream::wofstream.3 b/man/std::wofstream::wofstream.3 deleted file mode 120000 index 8c9dd85ea..000000000 --- a/man/std::wofstream::wofstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::basic_ofstream.3 \ No newline at end of file diff --git a/man/std::wofstream::wofstream.3 b/man/std::wofstream::wofstream.3 new file mode 100644 index 000000000..da7885226 --- /dev/null +++ b/man/std::wofstream::wofstream.3 @@ -0,0 +1,105 @@ +.TH std::basic_ofstream::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::basic_ofstream \- std::basic_ofstream::basic_ofstream + +.SH Synopsis + basic_ofstream(); \fB(1)\fP + explicit basic_ofstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::out ); + explicit basic_ofstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + explicit basic_ofstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + template< class FsPath > + + explicit basic_ofstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + basic_ofstream( basic_ofstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ofstream( const basic_ofstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out) + (see std::basic_filebuf::open for the details on the effects of that call). If the + open() call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ofstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP Note that despite the default mode being out, the effects are + identical to the effects of out | trunc as described in std::filebuf::open + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ofstream f0; + std::ofstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ofstream f2(name); + std::ofstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::wostream.3 b/man/std::wostream.3 deleted file mode 120000 index 5d3d8327a..000000000 --- a/man/std::wostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream.3 \ No newline at end of file diff --git a/man/std::wostream.3 b/man/std::wostream.3 new file mode 100644 index 000000000..c912c374e --- /dev/null +++ b/man/std::wostream.3 @@ -0,0 +1,279 @@ +.TH std::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream \- std::basic_ostream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_ostream : virtual public std::basic_ios + + The class template basic_ostream provides support for high level output operations + on character streams. The supported operations include formatted output (e.g. + integer values) and unformatted output (e.g. raw characters and character arrays). + This functionality is implemented in terms of the interface provided by the + basic_streambuf class, accessed through the basic_ios base class. In typical + implementations, basic_ostream has no non-inherited data members. + + std-basic ostream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ostream std::basic_ostream + std::wostream std::basic_ostream + +.SH Global objects + + Six global basic_ostream objects are provided by the standard library: + + Defined in header + cout writes to the standard C output stream stdout + wcout (global object) + cerr writes to the standard C error stream stderr, unbuffered + wcerr (global object) + clog writes to the standard C error stream stderr + wclog (global object) + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Formatted output + operator<< inserts formatted data + \fI(public member function)\fP +.SH Unformatted output + put inserts a character + \fI(public member function)\fP + write inserts blocks of characters + \fI(public member function)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function)\fP + seekp sets the output position indicator + \fI(public member function)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function)\fP + swap swaps stream objects, except for the associated buffer + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class)\fP + +.SH Non-member functions + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + println(std::ostream) outputs formatted representation of the arguments + (C++23) with appended '\\n' + \fI(function template)\fP + vprint_unicode(std::ostream) performs Unicode aware output using type-erased + (C++23) argument representation + \fI(function)\fP + vprint_nonunicode(std::ostream) outputs character data using type-erased argument + (C++23) representation + \fI(function)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::wostream::basic_ostream.3 b/man/std::wostream::basic_ostream.3 deleted file mode 120000 index 718512a78..000000000 --- a/man/std::wostream::basic_ostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::basic_ostream.3 \ No newline at end of file diff --git a/man/std::wostream::basic_ostream.3 b/man/std::wostream::basic_ostream.3 new file mode 100644 index 000000000..2cd517ab4 --- /dev/null +++ b/man/std::wostream::basic_ostream.3 @@ -0,0 +1,63 @@ +.TH std::basic_ostream::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::basic_ostream \- std::basic_ostream::basic_ostream + +.SH Synopsis + explicit basic_ostream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_ostream( const basic_ostream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_ostream( basic_ostream&& rhs ); + + 1) Constructs the basic_ostream object, assigning initial values to the base class + by calling basic_ios::init(sb). + 2) The copy constructor is protected, and is deleted. Output streams are not + copyable. + 3) The move constructor uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable output + stream classes std::basic_ofstream and std::basic_ostringstream, which know how to + correctly move the associated streambuffer. + +.SH Parameters + + sb - streambuffer to use as output sequence + rhs - basic_ostream to initialize from + +.SH Notes + + Because basic_ios::init(sb) sets badbit when sb is a null pointer, and because + basic_ostream::sentry does nothing if the stream is already in a failed state, + writing to a stream constructed from a null pointer sb is a no-op. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // ERROR: copy ctor is deleted + // std::ostream myout(std::cout); + + // OK: shares buffer with cout + std::ostream myout(std::cout.rdbuf()); + + // ERROR: move constructor is protected + // std::ostream s2(std::move(std::ostringstream() << 7.1)); + + // OK: move ctor called through the derived class + std::ostringstream s2(std::ostringstream() << 7.1); + myout << s2.str() << '\\n'; + + std::ostream dev_null{nullptr}; // see Notes above + dev_null << "no-op"; + } + +.SH Output: + + 7.1 diff --git a/man/std::wostream::flush.3 b/man/std::wostream::flush.3 deleted file mode 120000 index 2493fd0c6..000000000 --- a/man/std::wostream::flush.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::flush.3 \ No newline at end of file diff --git a/man/std::wostream::flush.3 b/man/std::wostream::flush.3 new file mode 100644 index 000000000..642eeceeb --- /dev/null +++ b/man/std::wostream::flush.3 @@ -0,0 +1,91 @@ +.TH std::basic_ostream::flush 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::flush \- std::basic_ostream::flush + +.SH Synopsis + basic_ostream& flush(); + + Writes uncommitted changes to the underlying output sequence. Behaves as an + UnformattedOutputFunction. + + If rdbuf() is a null pointer, the sentry object is not constructed. + + Otherwise, after constructing and checking the sentry object, calls + rdbuf()->pubsync(). If the call returns -1, calls setstate(badbit). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this + +.SH Exceptions + + May throw std::ios_base::failure if (exceptions() & badbit) != 0. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::chrono_literals; + + void f() + { + std::cout << "Output from thread... "; + for (int i{1}; i != 10; ++i) + { + std::this_thread::sleep_for(250ms); + std::cout << i << ' '; + + // output three numbers at once; + // the effect is observable only in real-time + if (0 == (i % 3)) + std::cout.flush(); + } + std::cout << std::endl; // flushes as well + } + + int main() + { + std::thread tr{f}; + std::this_thread::sleep_for(150ms); + std::clog << "Output from main\\n"; + tr.join(); + } + +.SH Output: + + Output from main + Output from thread... 1 2 3 4 5 6 7 8 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + flush() did not behave as an + LWG 581 C++98 UnformattedOutputFunction behaves as an + because of the resolution of LWG issue UnformattedOutputFunction + 60 + +.SH See also + + pubsync invokes sync() + \fI(public member function of std::basic_streambuf)\fP + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + flush flushes the output stream + \fI(function template)\fP + endl outputs '\\n' and flushes the output stream + \fI(function template)\fP + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wostream::operator<<.3 b/man/std::wostream::operator<<.3 deleted file mode 120000 index 13d0f69bf..000000000 --- a/man/std::wostream::operator<<.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::operator<<.3 \ No newline at end of file diff --git a/man/std::wostream::operator<<.3 b/man/std::wostream::operator<<.3 new file mode 100644 index 000000000..7a68deebf --- /dev/null +++ b/man/std::wostream::operator<<.3 @@ -0,0 +1,208 @@ +.TH std::basic_ostream::operator<< 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::operator<< \- std::basic_ostream::operator<< + +.SH Synopsis + basic_ostream& operator<<( bool value ); \fB(1)\fP + basic_ostream& operator<<( long value ); \fB(2)\fP + basic_ostream& operator<<( unsigned long value ); \fB(3)\fP + basic_ostream& operator<<( long long value ); \fB(4)\fP \fI(since C++11)\fP + basic_ostream& operator<<( unsigned long long value ); \fB(5)\fP \fI(since C++11)\fP + basic_ostream& operator<<( double value ); \fB(6)\fP + basic_ostream& operator<<( long double value ); \fB(7)\fP + basic_ostream& operator<<( const void* value ); \fB(8)\fP + basic_ostream& operator<<( const volatile void* value ); \fB(9)\fP (since C++23) + basic_ostream& operator<<( std::nullptr_t ); \fB(10)\fP \fI(since C++17)\fP + basic_ostream& operator<<( short value ); \fB(11)\fP + basic_ostream& operator<<( int value ); \fB(12)\fP + basic_ostream& operator<<( unsigned short value ); \fB(13)\fP + basic_ostream& operator<<( unsigned int value ); \fB(14)\fP + basic_ostream& operator<<( float value ); \fB(15)\fP + basic_ostream& operator<<( /* extended-floating-point-type */ \fB(16)\fP (since C++23) + value ); + basic_ostream& operator<<( std::basic_streambuf* \fB(17)\fP + sb ); + basic_ostream& operator<<( \fB(18)\fP + std::ios_base& (*func)(std::ios_base&) ); + basic_ostream& operator<<( + std::basic_ios& (*func)(std::basic_ios&) ); + basic_ostream& operator<<( + + std::basic_ostream& (*func) \fB(20)\fP + + (std::basic_ostream&) ); + + Inserts data into the stream. + + 1-8) Inserts value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a value by calling std::num_put::put(). If the end of + file condition was encountered during output (put().failed() == true), sets badbit. + 9) Equivalent to return operator<<(const_cast(p));. + 10) Equivalent to return *this << s;, where s is an implementation-defined + null-terminated character type string. + 11) Inserts a value from short value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is + * static_cast(static_cast(value)), if flags() & + std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or + * static_cast(value) otheriwse. + 12) Inserts a value from int value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is + * static_cast(static_cast(value)), if flags() & + std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or + * static_cast(value) otheriwse. + 13,14) Inserts a value from unsigned short or unsigned int value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts static_cast(value) as in \fB(3)\fP. + 15) Inserts a value from float value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts static_cast(value) as in \fB(6)\fP. + 16) Inserts a value from value. The library provides overloads for all + cv-unqualified extended floating-point types as the type of the parameter value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, checks the floating-point conversion rank of /* + extended-floating-point-type */: + * If the rank is less than or equal to that of double, inserts + static_cast(value) as in \fB(6)\fP. + * Otherwise, if the rank is less than or equal to that of long double, inserts + static_cast(value) as in \fB(7)\fP. + * Otherwise, an invocation of this overload is conditionally supported with + implementation-defined semantics. + 17) This function behaves as an UnformattedOutputFunction. After constructing and + checking the sentry object, checks if sb is a null pointer. If it is, executes + setstate(badbit) and exits. Otherwise, extracts characters from the input sequence + controlled by sb and inserts them into *this until one of the following conditions + are met: + + * end-of-file occurs on the input sequence; + * inserting in the output sequence fails (in which case the character to be + inserted is not extracted); + * an exception occurs (in which case the exception is caught). + If no characters were inserted, executes setstate(failbit). If an exception was + thrown while extracting, sets failbit and, if failbit is set in exceptions(), + rethrows the exception. + 18-20) Calls func(*this). These overloads are used to implement output I/O + manipulators such as std::endl. + +.SH Parameters + + value - integer, floating-point, boolean, or pointer value to insert + func - function to call + sb - pointer to the stream buffer to read the data from + +.SH Return value + + 1-19) *this + 20) func(*this) + +.SH Notes + + There are no overloads for pointers to non-static members + , pointers to volatiles, + (until C++23) or function pointers (other than the ones with signatures accepted by + the (18-20) overloads). + + * Attempting to output such objects invokes implicit conversion to bool, and, for + any non-null pointer value, the value 1 is printed (unless boolalpha was set, in + which case true is printed). + + Character and character string arguments (e.g., of type char or const char*) are + handled by the non-member overloads of operator<<. + + * Attempting to output a character using the member function call syntax (e.g., + std::cout.operator<<('c');) will call one of the overloads in (2-5) or (11-14) + and output the numerical value. + * Attempting to output a character string using the member function call syntax + will call overload \fB(8)\fP and print the pointer value instead. + +.SH Example + + +// Run this code + + #include + #include + #include + + int fun() { return 42; } + + int main() + { + std::istringstream input(" \\"Some text.\\" "); + double f = 3.14; + bool b = true; + + std::cout + << fun() // int overload (12) + << ' ' // non-member overload + << std::boolalpha // function overload (18) + << b // bool overload (1) + << " " // non-member overload + << std::fixed // function overload (18) again + << f // double overload (6) + << input.rdbuf() // streambuf overload + << fun // bool overload (1): there's no overload for int(*)() + << std::endl; // function overload (18) again + + int x = 0; + int* p1 = &x; + volatile int* p2 = &x; + std::cout + << "p1: " << p1 << '\\n' // `const void*` overload, prints address + << "p2: " << p2 << '\\n'; // before C++23 (P1147): bool overload :), because + // operator<<(const void*) is not a match, as it discards the `volatile` + // qualifier. To fix this, C++23 adds `const volatile void*` overload (9), + // that prints the address as expected. + } + +.SH Possible output: + + 42 true 3.140000 "Some text." true + p1: 0x7ffcea766600 + p2: 0x7ffcea766600 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overloads (1-8,11-15) delegated the + insertion to they are converted + LWG 117 C++98 num_put::put, but it does not have before being passed + overloads for short, to num_put::put + unsigned short, int, unsigned int, and + float + overload \fB(17)\fP behaved as a + LWG 567 C++98 FormattedOutputFunction it behaves as an + because of the resolution of LWG issue UnformattedOutputFunction + 60 + +.SH See also + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + operator<< performs stream input and output of bitsets + operator>> \fI(function template)\fP + operator<< serializes and deserializes a complex number + operator>> \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number engine + \fI(C++11)\fP \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number distribution + \fI(C++11)\fP \fI(function template)\fP + put inserts a character + \fI(public member function)\fP + write inserts blocks of characters + \fI(public member function)\fP + to_chars converts an integer or floating-point value to a + \fI(C++17)\fP character sequence + \fI(function)\fP diff --git a/man/std::wostream::operator=.3 b/man/std::wostream::operator=.3 deleted file mode 120000 index 2d79f3d27..000000000 --- a/man/std::wostream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::operator=.3 \ No newline at end of file diff --git a/man/std::wostream::operator=.3 b/man/std::wostream::operator=.3 new file mode 100644 index 000000000..051bc3209 --- /dev/null +++ b/man/std::wostream::operator=.3 @@ -0,0 +1,54 @@ +.TH std::basic_ostream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::operator= \- std::basic_ostream::operator= + +.SH Synopsis + protected: \fB(1)\fP + basic_ostream& operator=( const basic_ostream& rhs ) = delete; + protected: \fB(2)\fP \fI(since C++11)\fP + basic_ostream& operator=( basic_ostream&& rhs ); + + 1) The copy assignment operator is protected, and is deleted. Output streams are not + CopyAssignable. + 2) The move assignment operator exchanges all data members of the base class, except + for rdbuf(), with rhs, as if by calling swap(*rhs). This move assignment operator is + protected: it is only called by the move assignment operators of the derived movable + output stream classes std::basic_ofstream and std::basic_ostringstream, which know + how to correctly move-assign the associated streambuffers. + +.SH Parameters + + rhs - the basic_ostream object from which to assign to *this + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ostringstream s; + // std::cout = s; // ERROR: copy assignment operator is deleted + // std::cout = std::move(s); // ERROR: move assignment operator is protected + s = std::move(std::ostringstream() << 42); // OK, moved through derived + std::cout << s.str() << '\\n'; + } + +.SH Output: + + 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the parameter type of overload \fB(1)\fP was + LWG 2067 C++11 basic_ostream& 1. added const + 2. the parameter type of overload \fB(2)\fP was const 2. removed const + basic_ostream&& diff --git a/man/std::wostream::put.3 b/man/std::wostream::put.3 deleted file mode 120000 index 3f0b42dfc..000000000 --- a/man/std::wostream::put.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::put.3 \ No newline at end of file diff --git a/man/std::wostream::put.3 b/man/std::wostream::put.3 new file mode 100644 index 000000000..5a34117a4 --- /dev/null +++ b/man/std::wostream::put.3 @@ -0,0 +1,66 @@ +.TH std::basic_ostream::put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::put \- std::basic_ostream::put + +.SH Synopsis + basic_ostream& put( char_type ch ); + + Behaves as an UnformattedOutputFunction. After constructing and checking the sentry + object, writes the character ch to the output stream. + + If the output fails for any reason, sets badbit. + +.SH Parameters + + ch - character to write + +.SH Return value + + *this + +.SH Notes + + This function is not overloaded for the types signed char or unsigned char, unlike + the formatted operator<<. + + Unlike formatted output functions, this function does not set the failbit if the + output fails. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout.put('a'); // normal usage + std::cout.put('\\n'); + + std::ofstream s("/does/not/exist/"); + s.clear(); // pretend the stream is good + std::cout << "Unformatted output: "; + s.put('c'); // this will set badbit, but not failbit + std::cout << " fail=" << bool(s.rdstate() & s.failbit); + std::cout << " bad=" << s.bad() << '\\n'; + s.clear(); + std::cout << "Formatted output: "; + s << 'c'; // this will set badbit and failbit + std::cout << " fail=" << bool(s.rdstate() & s.failbit); + std::cout << " bad=" << s.bad() << '\\n'; + } + +.SH Output: + + a + Unformatted output: fail=0 bad=1 + Formatted output: fail=1 bad=1 + +.SH See also + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + write inserts blocks of characters + \fI(public member function)\fP diff --git a/man/std::wostream::seekp.3 b/man/std::wostream::seekp.3 deleted file mode 120000 index 89f3be9de..000000000 --- a/man/std::wostream::seekp.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::seekp.3 \ No newline at end of file diff --git a/man/std::wostream::seekp.3 b/man/std::wostream::seekp.3 new file mode 100644 index 000000000..19e584dc9 --- /dev/null +++ b/man/std::wostream::seekp.3 @@ -0,0 +1,88 @@ +.TH std::basic_ostream::seekp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::seekp \- std::basic_ostream::seekp + +.SH Synopsis + basic_ostream& seekp( pos_type pos ); \fB(1)\fP + basic_ostream& seekp( off_type off, std::ios_base::seekdir dir ); \fB(2)\fP + + Sets the output position indicator of the current associated streambuf object. + + Behaves as UnformattedOutputFunction (except without actually \fI(since C++11)\fP + performing output). After constructing and checking the sentry object, + + 1) if fail() != true, sets the output position indicator to absolute (relative to + the beginning of the file) value pos by calling rdbuf()->pubseekpos(pos, + std::ios_base::out). In case of failure, calls setstate(std::ios_base::failbit). + 2) if fail() != true, sets the output position indicator to offset off relative to + dir by calling rdbuf()->pubseekoff(off, dir, std::ios_base::out). In case of + failure, calls setstate(std::ios_base::failbit). + +.SH Parameters + + pos - absolute position to set the output position indicator to + off - relative position (positive or negative) to set the output position indicator + to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + +.SH Return value + + *this + +.SH Exceptions + + 1,2) May throw std::ios_base::failure in case of failure, if exceptions() & failbit + != 0. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream os("hello, world"); + os.seekp(7); + os << 'W'; + os.seekp(0, std::ios_base::end); + os << '!'; + os.seekp(0); + os << 'H'; + std::cout << os.str() << '\\n'; + } + +.SH Output: + + Hello, World! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 129 C++98 there was no way to indicate a failure sets failbit on failure + LWG 136 C++98 seekp could set the input stream only sets the output + stream + LWG 537 C++98 1. the type of pos was pos_type& 1. corrected to pos_type + 2. the type of off was off_type& 2. corrected to off_type + LWG 2341 C++98 the resolution of LWG issue 129 for restored + overload \fB(2)\fP was removed + +.SH See also + + tellp returns the output position indicator + \fI(public member function)\fP + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wostream::sentry.3 b/man/std::wostream::sentry.3 deleted file mode 120000 index b6533ef2c..000000000 --- a/man/std::wostream::sentry.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::sentry.3 \ No newline at end of file diff --git a/man/std::wostream::sentry.3 b/man/std::wostream::sentry.3 new file mode 100644 index 000000000..6001be802 --- /dev/null +++ b/man/std::wostream::sentry.3 @@ -0,0 +1,124 @@ +.TH std::basic_ostream::sentry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::sentry \- std::basic_ostream::sentry + +.SH Synopsis + class sentry; + + An object of class basic_ostream::sentry is constructed in local scope at the + beginning of each member function of std::basic_ostream that performs output (both + formatted and unformatted). Its constructor prepares the output stream: checks if + the stream is already in a failed state, flushes the tie()'d output streams, and + performs other implementation-defined tasks if necessary. Implementation-defined + cleanup, as well as flushing of the output stream if necessary, is performed in the + destructor, so that it is guaranteed to happen if exceptions are thrown during + output. + +.SH Member functions + + constructor constructs the sentry object. All the preparation tasks are done here + \fI(public member function)\fP + finalizes the stream object after formatted output or after exception, + destructor if necessary + \fI(public member function)\fP + operator= the assignment operator is deleted + \fI(public member function)\fP + operator bool checks if the preparation of the stream object was successful + \fI(public member function)\fP + +std::basic_ostream::sentry::sentry + + explicit sentry( std::basic_ostream& os ); + + Prepares the stream for formatted output. + + If os.good() is false, returns. Otherwise, if os.tie() is not a null pointer, calls + os.tie()->flush() to synchronize the output sequence with external streams. During + preparation, the constructor may call setstate(failbit) (which may throw + std::ios_base::failure). + + If after preparation is completed, os.good() == true, then any subsequent calls to + operator bool will return true. + +.SH Parameters + + os - output stream to prepare + +.SH Exceptions + + std::ios_base::failure if the end of file condition occurs. + +std::basic_ostream::sentry::~sentry + + ~sentry(); + + If (os.flags() & std::ios_base::unitbuf) && !std::uncaught_exception() && os.good()) + is true, calls os.rdbuf()->pubsync(). If that function returns -1, sets badbit in + os.rdstate() without propagating an exception. + +std::basic_ostream::sentry::operator bool + + explicit operator bool() const; + + Checks whether the preparation of the output stream was successful. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the preparation of the output stream was successful, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + char n[6]; + }; + + std::ostream& operator<<(std::ostream& os, Foo& f) + { + std::ostream::sentry s(os); + if (s) + os.write(f.n, 5); + return os; + } + + int main() + { + Foo f = {"abcde"}; + std::cout << f << '\\n'; + } + +.SH Output: + + abcde + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 397 C++98 the destructor might call os.flush(), which the exception is not + may throw exceptions propagated + LWG 442 C++98 operator bool was not declared const (it is added const + const in the synopsis) + if os sets unitbuf, the destructor would + call os.flush(), which calls + LWG 835 C++98 is an UnformattedOutputFunction and creates os.rdbuf()->pubsync() + another sentry object in this case instead + (whose destructor then creates another + sentry object and so on) + +.SH See also + + operator<< inserts formatted data + \fI(public member function)\fP diff --git a/man/std::wostream::swap.3 b/man/std::wostream::swap.3 deleted file mode 120000 index 67e58a029..000000000 --- a/man/std::wostream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::swap.3 \ No newline at end of file diff --git a/man/std::wostream::swap.3 b/man/std::wostream::swap.3 new file mode 100644 index 000000000..2b0d09268 --- /dev/null +++ b/man/std::wostream::swap.3 @@ -0,0 +1,43 @@ +.TH std::basic_ostream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::swap \- std::basic_ostream::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_ostream& rhs ); + + Calls basic_ios::swap(rhs) to swap all data members of the base class, except for + rdbuf(), between *this and rhs. This swap function is protected: it is called by the + swap functions of the swappable output stream classes std::basic_ofstream and + std::basic_ostringstream, which know how to correctly swap the associated + streambuffers. + +.SH Parameters + + rhs - a basic_ostream of the same type to swap with + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ostringstream s1("hello"); + std::ostringstream s2("bye"); + + s1.swap(s2); // OK, ostringstream has a public swap() + std::swap(s1, s2); // OK, calls s1.swap(s2) + + // std::cout.swap(s2); // ERROR: swap is a protected member + + std::cout << s1.str() << '\\n'; + } + +.SH Output: + + hello diff --git a/man/std::wostream::tellp.3 b/man/std::wostream::tellp.3 deleted file mode 120000 index 1781469fd..000000000 --- a/man/std::wostream::tellp.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::tellp.3 \ No newline at end of file diff --git a/man/std::wostream::tellp.3 b/man/std::wostream::tellp.3 new file mode 100644 index 000000000..73acfb3df --- /dev/null +++ b/man/std::wostream::tellp.3 @@ -0,0 +1,58 @@ +.TH std::basic_ostream::tellp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::tellp \- std::basic_ostream::tellp + +.SH Synopsis + pos_type tellp(); + + Returns the output position indicator of the current associated streambuf object. + + Behaves as UnformattedOutputFunction (except without actually \fI(since C++11)\fP + performing output). After constructing and checking the sentry object, + + If fail()==true, returns pos_type(-1). Otherwise, returns rdbuf()->pubseekoff(0, + std::ios_base::cur, std::ios_base::out). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + current output position indicator on success, pos_type(-1) if a failure occurs. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::ostringstream s; + std::cout << s.tellp() << '\\n'; + s << 'h'; + std::cout << s.tellp() << '\\n'; + s << "ello, world "; + std::cout << s.tellp() << '\\n'; + s << 3.14 << '\\n'; + std::cout << s.tellp() << '\\n' << s.str(); + } + +.SH Output: + + 0 + 1 + 13 + 18 + hello, world 3.14 + +.SH See also + + seekp sets the output position indicator + \fI(public member function)\fP + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wostream::wostream.3 b/man/std::wostream::wostream.3 deleted file mode 120000 index 718512a78..000000000 --- a/man/std::wostream::wostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::basic_ostream.3 \ No newline at end of file diff --git a/man/std::wostream::wostream.3 b/man/std::wostream::wostream.3 new file mode 100644 index 000000000..2cd517ab4 --- /dev/null +++ b/man/std::wostream::wostream.3 @@ -0,0 +1,63 @@ +.TH std::basic_ostream::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::basic_ostream \- std::basic_ostream::basic_ostream + +.SH Synopsis + explicit basic_ostream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_ostream( const basic_ostream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_ostream( basic_ostream&& rhs ); + + 1) Constructs the basic_ostream object, assigning initial values to the base class + by calling basic_ios::init(sb). + 2) The copy constructor is protected, and is deleted. Output streams are not + copyable. + 3) The move constructor uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable output + stream classes std::basic_ofstream and std::basic_ostringstream, which know how to + correctly move the associated streambuffer. + +.SH Parameters + + sb - streambuffer to use as output sequence + rhs - basic_ostream to initialize from + +.SH Notes + + Because basic_ios::init(sb) sets badbit when sb is a null pointer, and because + basic_ostream::sentry does nothing if the stream is already in a failed state, + writing to a stream constructed from a null pointer sb is a no-op. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // ERROR: copy ctor is deleted + // std::ostream myout(std::cout); + + // OK: shares buffer with cout + std::ostream myout(std::cout.rdbuf()); + + // ERROR: move constructor is protected + // std::ostream s2(std::move(std::ostringstream() << 7.1)); + + // OK: move ctor called through the derived class + std::ostringstream s2(std::ostringstream() << 7.1); + myout << s2.str() << '\\n'; + + std::ostream dev_null{nullptr}; // see Notes above + dev_null << "no-op"; + } + +.SH Output: + + 7.1 diff --git a/man/std::wostream::write.3 b/man/std::wostream::write.3 deleted file mode 120000 index 3c2cea83f..000000000 --- a/man/std::wostream::write.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::write.3 \ No newline at end of file diff --git a/man/std::wostream::write.3 b/man/std::wostream::write.3 new file mode 100644 index 000000000..d4244b94e --- /dev/null +++ b/man/std::wostream::write.3 @@ -0,0 +1,75 @@ +.TH std::basic_ostream::write 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::write \- std::basic_ostream::write + +.SH Synopsis + basic_ostream& write( const char_type* s, std::streamsize count ); + + Behaves as an UnformattedOutputFunction. After constructing and checking the sentry + object, outputs the characters from successive locations in the character array + whose first element is pointed to by s. Characters are inserted into the output + sequence until one of the following occurs: + + * exactly count characters are inserted + * inserting into the output sequence fails (in which case setstate(badbit) is + called). + +.SH Parameters + + s - pointer to the character string to write + count - number of characters to write + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + This function is not overloaded for the types signed char or unsigned char, unlike + the formatted operator<<. + + Also, unlike the formatted output functions, this function does not set the failbit + on failure. + + When using a non-converting locale (the default locale is non-converting), the + overrider of this function in std::basic_ofstream may be optimized for zero-copy + bulk I/O (by means of overriding std::streambuf::xsputn). + +.SH Example + + This function may be used to output object representations, i.e. binary output + + +// Run this code + + #include + + int main() + { + int n = 0x41424344; + std::cout.write(reinterpret_cast(&n), sizeof n) << '\\n'; + + char c[] = "This is sample text."; + std::cout.write(c, 4).write("!\\n", 2); + } + +.SH Possible output: + + DCBA + This! + +.SH See also + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + put inserts a character + \fI(public member function)\fP diff --git a/man/std::wostream::~basic_ostream.3 b/man/std::wostream::~basic_ostream.3 deleted file mode 120000 index 5db51e526..000000000 --- a/man/std::wostream::~basic_ostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::~basic_ostream.3 \ No newline at end of file diff --git a/man/std::wostream::~basic_ostream.3 b/man/std::wostream::~basic_ostream.3 new file mode 100644 index 000000000..56d90cf52 --- /dev/null +++ b/man/std::wostream::~basic_ostream.3 @@ -0,0 +1,38 @@ +.TH std::basic_ostream::~basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::~basic_ostream \- std::basic_ostream::~basic_ostream + +.SH Synopsis + virtual ~basic_ostream(); + + Destroys the basic_ostream object. This destructor does not perform any operation on + the underlying streambuffer (rdbuf()): the destructors of the derived output streams + such as std::basic_ofstream and std::basic_ostringstream are responsible for calling + the destructors of the stream buffers. + +.SH Example + + +// Run this code + + #include + #include + + void add_words(std::streambuf* p) + { + std::ostream buf(p); // buf shares the buffer with s + buf << " is the answer"; + } // calls the destructor of buf. p remains unaffected + + int main() + { + std::ostringstream s; + s << 42; + add_words(s.rdbuf()); + s << "."; + std::cout << s.str() << '\\n'; + } + +.SH Output: + + 42 is the answer. diff --git a/man/std::wostringstream.3 b/man/std::wostringstream.3 deleted file mode 120000 index 2599c8fd3..000000000 --- a/man/std::wostringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream.3 \ No newline at end of file diff --git a/man/std::wostringstream.3 b/man/std::wostringstream.3 new file mode 100644 index 000000000..476ad8c39 --- /dev/null +++ b/man/std::wostringstream.3 @@ -0,0 +1,277 @@ +.TH std::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream \- std::basic_ostringstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + > class basic_ostringstream + + : public basic_ostream; + + The class template std::basic_ostringstream implements output operations on string + based streams. It effectively stores an instance of std::basic_string and performs + output operations to it. + + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_ostream. The + complete interface to unique std::basic_stringbuf members is provided. + + std-basic ostringstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ostringstream std::basic_ostringstream + std::wostringstream std::basic_ostringstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) + +.SH Member functions + + constructor constructs the string stream + \fI(public member function)\fP + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP +.SH String operations + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ostringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::wostringstream::basic_ostringstream.3 b/man/std::wostringstream::basic_ostringstream.3 deleted file mode 120000 index e9eb0c526..000000000 --- a/man/std::wostringstream::basic_ostringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::basic_ostringstream.3 \ No newline at end of file diff --git a/man/std::wostringstream::basic_ostringstream.3 b/man/std::wostringstream::basic_ostringstream.3 new file mode 100644 index 000000000..17a9cb9e1 --- /dev/null +++ b/man/std::wostringstream::basic_ostringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_ostringstream::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::basic_ostringstream \- std::basic_ostringstream::basic_ostringstream + +.SH Synopsis + explicit basic_ostringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_ostringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_ostringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_ostringstream(std::ios_base::out) {} + explicit basic_ostringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + explicit basic_ostringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + basic_ostringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_ostringstream(str, std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_ostringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + explicit basic_ostringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + basic_ostringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_ostringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_ostringstream( basic_ostringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_ostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_ostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_ostream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::out) + \fB(2)\fP buf_type(std::ios_base::out) + \fB(3)\fP buf_type(str, mode | + std::ios_base::out) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::out) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::out, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::out, a) + \fB(7)\fP buf_type(str, std::ios_base::out, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::out) + \fB(9)\fP {t, mode | std::ios_base::out, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::out, a} + \fB(11)\fP {t, std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_ostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_ostringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::wostringstream::operator=.3 b/man/std::wostringstream::operator=.3 deleted file mode 120000 index fe60e11e6..000000000 --- a/man/std::wostringstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::operator=.3 \ No newline at end of file diff --git a/man/std::wostringstream::operator=.3 b/man/std::wostringstream::operator=.3 new file mode 100644 index 000000000..8c4a77624 --- /dev/null +++ b/man/std::wostringstream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_ostringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::operator= \- std::basic_ostringstream::operator= + +.SH Synopsis + basic_ostringstream& operator=( basic_ostringstream&& other ); \fI(since C++11)\fP + + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_ostream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. + +.SH Parameters + + other - string stream to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wostringstream::rdbuf.3 b/man/std::wostringstream::rdbuf.3 deleted file mode 120000 index ae8aeecf2..000000000 --- a/man/std::wostringstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::wostringstream::rdbuf.3 b/man/std::wostringstream::rdbuf.3 new file mode 100644 index 000000000..c81e2a3b3 --- /dev/null +++ b/man/std::wostringstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_ostringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::rdbuf \- std::basic_ostringstream::rdbuf + +.SH Synopsis + std::basic_stringbuf* rdbuf() const; + + Returns pointer to the underlying raw string device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw string device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wostringstream::str.3 b/man/std::wostringstream::str.3 deleted file mode 120000 index a88de43b3..000000000 --- a/man/std::wostringstream::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::str.3 \ No newline at end of file diff --git a/man/std::wostringstream::str.3 b/man/std::wostringstream::str.3 new file mode 100644 index 000000000..dcc9f6094 --- /dev/null +++ b/man/std::wostringstream::str.3 @@ -0,0 +1,99 @@ +.TH std::basic_ostringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::str \- std::basic_ostringstream::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Manages the contents of the underlying string object. + + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. + +.SH Parameters + + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string + +.SH Return value + + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP + +.SH Notes + + The copy of the underlying string returned by str is a temporary object that will be + destructed at the end of the expression, so directly calling c_str() on the result + of str() (for example in auto *ptr = out.str().c_str();) results in a dangling + pointer. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.str("1 2"); + in >> n; + std::cout << "After reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.str() << "\\"\\n"; + + std::ostringstream out("1 2"); + out << 3; + std::cout << "After writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); + ate << 3; + std::cout << "After writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" + +.SH See also + + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::wostringstream::swap.3 b/man/std::wostringstream::swap.3 deleted file mode 120000 index 2d90861d4..000000000 --- a/man/std::wostringstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::swap.3 \ No newline at end of file diff --git a/man/std::wostringstream::swap.3 b/man/std::wostringstream::swap.3 new file mode 100644 index 000000000..10baede6b --- /dev/null +++ b/man/std::wostringstream::swap.3 @@ -0,0 +1,39 @@ +.TH std::basic_ostringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::swap \- std::basic_ostringstream::swap + +.SH Synopsis + void swap( basic_ostringstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_ostream::swap(other) and + rdbuf()->swap(*other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::wostringstream::view.3 b/man/std::wostringstream::view.3 new file mode 100644 index 000000000..a98e54d32 --- /dev/null +++ b/man/std::wostringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_ostringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::view \- std::basic_ostringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::wostringstream::wostringstream.3 b/man/std::wostringstream::wostringstream.3 deleted file mode 120000 index e9eb0c526..000000000 --- a/man/std::wostringstream::wostringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::basic_ostringstream.3 \ No newline at end of file diff --git a/man/std::wostringstream::wostringstream.3 b/man/std::wostringstream::wostringstream.3 new file mode 100644 index 000000000..17a9cb9e1 --- /dev/null +++ b/man/std::wostringstream::wostringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_ostringstream::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::basic_ostringstream \- std::basic_ostringstream::basic_ostringstream + +.SH Synopsis + explicit basic_ostringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_ostringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_ostringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_ostringstream(std::ios_base::out) {} + explicit basic_ostringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + explicit basic_ostringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + basic_ostringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_ostringstream(str, std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_ostringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + explicit basic_ostringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + basic_ostringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_ostringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_ostringstream( basic_ostringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_ostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_ostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_ostream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::out) + \fB(2)\fP buf_type(std::ios_base::out) + \fB(3)\fP buf_type(str, mode | + std::ios_base::out) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::out) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::out, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::out, a) + \fB(7)\fP buf_type(str, std::ios_base::out, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::out) + \fB(9)\fP {t, mode | std::ios_base::out, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::out, a} + \fB(11)\fP {t, std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_ostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_ostringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::wprintf,std::fwprintf,std::swprintf.3 b/man/std::wprintf,std::fwprintf,std::swprintf.3 index 7d59bd34a..903af6243 100644 --- a/man/std::wprintf,std::fwprintf,std::swprintf.3 +++ b/man/std::wprintf,std::fwprintf,std::swprintf.3 @@ -1,4 +1,7 @@ -.TH std::wprintf,std::fwprintf,std::swprintf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wprintf,std::fwprintf,std::swprintf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wprintf,std::fwprintf,std::swprintf \- std::wprintf,std::fwprintf,std::swprintf + .SH Synopsis Defined in header int wprintf( const wchar_t* format, ... ); \fB(1)\fP @@ -10,459 +13,523 @@ 1) Writes the results to stdout. 2) Writes the results to a file stream stream. - 3) Writes the results to a wide string buffer. At most size-1 wide characters are - written. The resulting wide character string will be terminated with a null - character, unless size is zero. + 3) Writes the results to a wide string buffer. At most size - 1 wide characters are + written followed by null wide character. .SH Parameters -stream - output file stream to write to -buffer - pointer to a wide character string to write to -size - up to size - 1 characters may be written, plus the null terminator - pointer to a null-terminated wide string specifying how to interpret the data. - - The format string consists of ordinary characters (except %), which are copied unchanged into the output - stream, and conversion specifications. Each conversion specification has the following format: - - * introductory % character - - * (optional) one or more flags that modify the behavior of the conversion: - - * -: the result of the conversion is left-justified within the field (by default it is - right-justified) - * +: the sign of signed conversions is always prepended to the result of the conversion (by default - the result is preceded by minus only when it is negative) - * space: if the result of a signed conversion does not start with a sign character, or is empty, space - is prepended to the result. It is ignored if + flag is present. - * # : alternative form of the conversion is performed. See the table below for exact effects. - * 0 : for integer and floating point number conversions, leading zeros are used to pad the field - instead of space characters. For floating point numbers it is ignored if the precision is explicitly - specified. For other conversions using this flag results in undefined behavior. It is ignored if - - flag is present. - - * (optional) integer value or * that specifies minimum field width. The result is padded with space - characters (by default), if required, on the left when right-justified, or on the right if - left-justified. In the case when * is used, the width is specified by an additional argument of type - int. If the value of the argument is negative, it results with the - flag specified and positive - field width. - - * (optional) . followed by integer number or * that specifies precision of the conversion. In the case - when * is used, the precision is specified by an additional argument of type int. If the value of - this argument is negative, it is ignored. See the table below for exact effects of precision. - - * (optional) length modifier that specifies the size of the argument - - * conversion format specifier - - The following format specifiers are available: - - Conversion Explanation Argument type - specifier - length modifier hh h \fI(none)\fP l ll j z t L - writes literal - %. The full - % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A - specification - must be %%. - writes a - c single N/A N/A char wchar_t N/A N/A N/A N/A N/A - character - writes a - character - string. - - s Precision N/A N/A char* wchar_t* N/A N/A N/A N/A N/A - specifies the - maximum number - of bytes to be - written. - converts a - signed decimal - integer in the - style [-]dddd. - - Precision - specifies the - minimum number - of digits to - d appear. The - i default N/A - precision is - 1. - If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. - converts a - signed octal - integer in the - style [-]oooo. - - Precision - specifies the signed signed signed signed signed - minimum number char short int long long intmax_t - of digits to long - appear. The - default - precision is - 1. If both the - converted - value and the - precision are - 0 the - o conversion N/A - results in no - characters. In - the - alternative - implementation - precision is - increased if - necessary, to - write one - leading zero. - In that case - if both the - converted - value and the - precision are - 0, single - 0 is - written. - converts a size_t ptrdiff_t - signed - hexadecimal - integer in the - style [-]hhhh. - - For the x - conversion - letters abcdef - are used. - For the X - conversion - letters ABCDEF - are used. - Precision - specifies the - minimum number - of digits to - x appear. The N/A - X default - precision is - 1. If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. In unsigned unsigned unsigned unsigned unsigned - the char short int long long uintmax_t - alternative long - implementation - 0x or 0X is - prefixed to - results if the - converted - value is - nonzero. - converts an - unsigned - decimal - integer in the - style dddd. - - Precision - specifies the - minimum number - of digits to - u appear. The N/A - default - precision is - 1. If both the - converted - value and the - precision are - 0 the - conversion - results in no - characters. - converts - floating-point - number to the - decimal - notation in - the style - [-]ddd.ddd. - - Precision - specifies the - minimum number - of digits to - appear after - the decimal - f point - F character. The N/A N/A N/A N/A N/A N/A - default - precision is - 6. In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to the -format - decimal - exponent - notation. - - For the e - conversion - style - [-]d.ddde±dd - is used. - For the E - conversion - style - [-]d.dddE±dd - is used. - The exponent - contains at - least two - digits, more - digits are - used only if - necessary. If - e the value is - E 0, the N/A N/A N/A N/A N/A N/A - exponent is - also 0. - Precision - specifies the - minimum number - of digits to - appear after - the decimal - point - character. The - default - precision is - 6. In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to the - hexadecimal - exponent - notation. - - For the a - conversion - style - [-]0xh.hhhp±d - is used. - For the A - conversion - style - [-]0Xh.hhhP±d - is used. - The first - hexadecimal - digit is 0 if - the argument - is not a - normalized - floating point double double long - value. If the double - value is 0, - a the exponent - A is also 0. N/A N/A N/A N/A N/A N/A - Precision - specifies the - minimum number - of digits to - appear after - the decimal - point - character. The - default - precision is - sufficient for - exact - representation - of the value. - In the - alternative - implementation - decimal point - character is - written even - if no digits - follow it. For - infinity and - not-a-number - conversion - style see - notes. - converts - floating-point - number to - decimal or - decimal - exponent - notation - depending on - the value and - the precision. - - For the g - conversion - style - conversion - with style e - or f will be - performed. - For the G - conversion - style - conversion - with style E - or F will be - performed. - Let P equal - the precision - if nonzero, 6 - if the - precision is - not specified, - or 1 if the - precision is - 0. Then, if - a conversion - with style E - g would have an - G exponent of X: N/A N/A N/A N/A N/A N/A - - * if P > X ≥ - −4, the - conversion - is with - style f or - F and - precision - P − 1 − X. - * otherwise, - the - conversion - is with - style e or - E and - precision - P − 1. - - Unless - alternative - representation - is requested - the trailing - zeros are - removed, also - the decimal - point - character is - removed if no - fractional - part is left. - For infinity - and - not-a-number - conversion - style see - notes. - returns the - number of - characters - written so far - by this call - to the - function. - n N/A N/A int* N/A N/A N/A N/A N/A N/A - The result is - written to the - value pointed - to by the - argument. The - complete - specification - must be %n. - writes an - implementation - defined - p character N/A N/A void* N/A N/A N/A N/A N/A N/A - sequence - defining a - pointer. -.SH Notes: - - The floating point conversion functions convert infinity to inf or infinity. Which one is used is - implementation defined. - Not-a-number is converted to nan or nan(char_sequence). Which one is used is implementation defined. - The conversions F, E, G, A output INF, INFINITY, NAN instead. - The correct conversion specifiers for the fixed-width character types (std:int8_t, etc) are defined in - the header -... - arguments specifying data to print + stream - output file stream to write to + buffer - pointer to a wide character string to write to + size - up to size - 1 characters may be written, plus the null terminator + format - pointer to a null-terminated wide string specifying how to interpret the + data + arguments specifying data to print. If any argument after default + conversions is not the type expected by the corresponding conversion + ... - specifier, or if there are fewer arguments than required by format, the + behavior is undefined. If there are more arguments than required by format, + the extraneous arguments are evaluated and ignored + + The format string consists of ordinary wide characters (except %), which are copied + unchanged into the output stream, and conversion specifications. Each conversion + specification has the following format: + + * introductory % character. + + * (optional) one or more flags that modify the behavior of the conversion: + + * -: the result of the conversion is left-justified within the field (by default + it is right-justified). + * +: the sign of signed conversions is always prepended to the result of the + conversion (by default the result is preceded by minus only when it is + negative). + * space: if the result of a signed conversion does not start with a sign + character, or is empty, space is prepended to the result. It is ignored if + + flag is present. + * #: alternative form of the conversion is performed. See the table below for + exact effects otherwise the behavior is undefined. + * 0: for integer and floating-point number conversions, leading zeros are used to + pad the field instead of space characters. For integer numbers it is ignored if + the precision is explicitly specified. For other conversions using this flag + results in undefined behavior. It is ignored if - flag is present. + + * (optional) integer value or * that specifies minimum field width. The result is + padded with space characters (by default), if required, on the left when + right-justified, or on the right if left-justified. In the case when * is used, + the width is specified by an additional argument of type int, which appears + before the argument to be converted and the argument supplying precision if one + is supplied. If the value of the argument is negative, it results with the - + flag specified and positive field width (Note: This is the minimum width: The + value is never truncated.). + + * (optional) . followed by integer number or *, or neither that specifies + precision of the conversion. In the case when * is used, the precision is + specified by an additional argument of type int, which appears before the + argument to be converted, but after the argument supplying minimum field width + if one is supplied. If the value of this argument is negative, it is ignored. If + neither a number nor * is used, the precision is taken as zero. See the table + below for exact effects of precision. + + * (optional) length modifier that specifies the size of the argument (in + combination with the conversion format specifier, it specifies the type of the + corresponding argument). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Expected +Specifier Argument Type + Length hh ll j z t + Modifier→ h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + Writes literal + %. The full + % conversion N/A N/A N/A N/A N/A N/A N/A N/A N/A + specification + must be %%. + Writes a single + character. + + The argument is + first converted + to wchar_t as if + c by calling N/A N/A int wint_t N/A N/A N/A N/A N/A + btowc. If the l + modifier is + used, the wint_t + argument is + first converted + to wchar_t. + Writes a + character string + + The argument + must be a + pointer to the + initial element + of a character + array containing + a multibyte + character + sequence + beginning in the + initial shift + state, which is + converted to + wide character + array as if by a + call to mbrtowc + with + zero-initialized + s conversion N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + state. Precision + specifies the + maximum number + of wide + characters to be + written. If + Precision is not + specified, + writes every + wide characters + up to and not + including the + first null + terminator. If + the l specifier + is used, the + argument must be + a pointer to the + initial element + of an array of + wchar_t. + Converts a + signed integer + into decimal + representation + [-]dddd. + + Precision + specifies the + minimum number + of digits to + d appear. The signed short int long long intmax_t signed ptrdiff_t N/A + i default char long size_t + precision is 1. + + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts an + unsigned integer + into octal + representation + oooo. + + Precision + specifies the + minimum number + of digits to + appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + o the conversion N/A + results in no + characters. In + the alternative + implementation + precision is + increased if + necessary, to + write one + leading zero. In + that case if + both the + converted value + and the + precision are 0, + single 0 is + written. + + Converts an + unsigned integer + into hexadecimal + representation + hhhh. + + For the x + conversion + letters abcdef + are used. unsigned unsigned + For the X unsigned unsigned unsigned unsigned long long uintmax_t size_t version of + conversion char short int long ptrdiff_t + letters ABCDEF + are used. + Precision + specifies the + minimum number + x of digits to N/A + X appear. The + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. In + the alternative + implementation + 0x or 0X is + prefixed to + results if the + converted value + is nonzero. + + Converts an + unsigned integer + into decimal + representation + dddd. + + Precision + specifies the + minimum number + of digits to + u appear. The N/A + default + precision is 1. + If both the + converted value + and the + precision are 0 + the conversion + results in no + characters. + + Converts + floating-point + number to the + decimal notation + in the style + [-]ddd.ddd. + + Precision + specifies the + exact number of + digits to appear + after the + f decimal point + F character. The N/A N/A N/A N/A N/A N/A + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + decimal exponent + notation. + + For the e + conversion style + [-]d.ddde±dd is + used. + For the E + conversion style + [-]d.dddE±dd is + used. + The exponent + contains at + least two + digits, more + digits are used + only if + necessary. If + e the value is 0, N/A N/A N/A N/A N/A N/A + E the exponent is + also 0. + Precision + specifies the + exact number of + digits to appear + after the + decimal point + character. The + default + precision is 6. + In the + alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + Converts + floating-point + number to the + hexadecimal + exponent + notation. + + For the a + conversion style + [-]0xh.hhhp±d is + used. + For the A + conversion style + [-]0Xh.hhhP±d is + used. + The first + hexadecimal + digit is not 0 + if the argument + is a normalized + floating-point + value. If the double double\fI(C++11)\fP long + a value is 0, the double + A exponent is also N/A N/A N/A N/A N/A N/A + 0. Precision + \fI(C++11)\fP specifies the + exact number of + digits to appear + after the + hexadecimal + point character. + The default + precision is + sufficient for + exact + representation + of the value. In + the alternative + implementation + decimal point + character is + written even if + no digits follow + it. For infinity + and not-a-number + conversion style + see notes. + + Converts + floating-point + number to + decimal or + decimal exponent + notation + depending on the + value and the + precision. + + For the g + conversion style + conversion with + style e or f + will be + performed. + For the G + conversion style + conversion with + style E or F + will be + performed. + Let P equal the + precision if + nonzero, 6 if + the precision is + not specified, + or 1 if the + precision is 0. + Then, if a + conversion with + style E would + g have an exponent + G of X: N/A N/A N/A N/A N/A N/A + + * if P > X ≥ + −4, the + conversion + is with + style f or F + and + precision P + − 1 − X. + * otherwise, + the + conversion + is with + style e or E + and + precision P + − 1. + + Unless + alternative + representation + is requested the + trailing zeros + are removed, + also the decimal + point character + is removed if no + fractional part + is left. For + infinity and + not-a-number + conversion style + see notes. + Returns the + number of + characters + written so far + by this call to + the function. + + The result is signed long signed + n written to the char* short* int* long* long* intmax_t* size_t* ptrdiff_t* N/A + value pointed to + by the argument. + The + specification + may not contain + any flag, field + width, or + precision. + Writes an + implementation + defined + p character N/A N/A void* N/A N/A N/A N/A N/A N/A + sequence + defining a + pointer. + + The floating-point conversion functions convert infinity to inf or infinity. Which + one is used is implementation defined. + + Not-a-number is converted to nan or nan(char_sequence). Which one is used is + implementation defined. + + The conversions F, E, G, A output INF, INFINITY, NAN instead. + + Even though %c expects int argument, it is safe to pass a char because of the + integer promotion that takes place when a variadic function is called. + + The correct conversion specifications for the fixed-width character types (int8_t, + etc) are defined in the header (although PRIdMAX, PRIuMAX, etc is + synonymous with %jd, %ju, etc). + + The memory-writing conversion specifier %n is a common target of security exploits + where format strings depend on user input and is not supported by the bounds-checked + printf_s family of functions. + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple %n results in the same variable or, as an edge case, + printing a string modified by an earlier %n within the same call. + + If a conversion specification is invalid, the behavior is undefined. .SH Return value - Number of wide characters written if successful (not counting the terminating null - character) or negative value if an error occurred. + 1,2) Number of wide characters written if successful or negative value if an error + occurred. + 3) Number of wide characters written (not counting the terminating null wide + character) if successful or negative value if an encoding error occurred or if the + number of characters to be generated was equal or greater than size (including when + size is zero). + +.SH Notes + + While narrow strings provide std::snprintf, which makes it possible to determine the + required output buffer size, there is no equivalent for wide strings, and in order + to determine the buffer size, the program may need to call std::swprintf, check the + result value, and reallocate a larger buffer, trying again until successful. .SH Example - + // Run this code - #include - #include #include #include - + #include + #include + int main() { char narrow_str[] = "z\\u00df\\u6c34\\U0001f34c"; - // or "zß水🍌" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c"; - wchar_t warr[30]; + // or "zß水🍌"; + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9f\\x8d\\x8c"; + wchar_t warr[29]; // the expected string is 28 characters plus 1 null terminator std::setlocale(LC_ALL, "en_US.utf8"); - - std::swprintf(warr, sizeof warr - 1, + + std::swprintf(warr, sizeof warr/sizeof *warr, L"Converted from UTF-8: '%s'", narrow_str); - + std::wcout.imbue(std::locale("en_US.utf8")); std::wcout << warr << '\\n'; } @@ -473,11 +540,16 @@ format - decimal .SH See also + printf + fprintf prints formatted output to stdout, a file stream or a buffer + sprintf \fI(function)\fP + snprintf + \fI(C++11)\fP vwprintf prints formatted wide character output to stdout, a file stream vfwprintf or a buffer using variable argument list - vswprintf \fI(function)\fP + vswprintf \fI(function)\fP fputws writes a wide string to a file stream - \fI(function)\fP + \fI(function)\fP C documentation for wprintf, fwprintf, diff --git a/man/std::wregex.3 b/man/std::wregex.3 deleted file mode 120000 index 9a17ed1ed..000000000 --- a/man/std::wregex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex.3 \ No newline at end of file diff --git a/man/std::wregex.3 b/man/std::wregex.3 new file mode 100644 index 000000000..f9b104d69 --- /dev/null +++ b/man/std::wregex.3 @@ -0,0 +1,101 @@ +.TH std::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex \- std::basic_regex + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++11)\fP + class Traits = std::regex_traits + + > class basic_regex; + + The class template basic_regex provides a general framework for holding regular + expressions. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::regex std::basic_regex + std::wregex std::basic_regex + +.SH Member types + + Member type Definition + value_type CharT + traits_type Traits + string_type Traits::string_type + locale_type Traits::locale_type + flag_type std::regex_constants::syntax_option_type + +.SH Member functions + + constructor constructs the regex object + \fI(public member function)\fP + destructor destructs the regex object + \fI(public member function)\fP + operator= assigns the contents + \fI(public member function)\fP + assign assigns the contents + \fI(public member function)\fP +.SH Observers + returns the number of marked sub-expressions within the regular + mark_count expression + \fI(public member function)\fP + flags returns the syntax flags + \fI(public member function)\fP +.SH Locale + getloc get locale information + \fI(public member function)\fP + imbue set locale information + \fI(public member function)\fP +.SH Modifiers + swap swaps the contents + \fI(public member function)\fP +.SH Constants + + Grammar option Effect(s) + ECMAScript Use the Modified ECMAScript regular expression grammar. + basic Use the basic POSIX regular expression grammar (grammar + documentation). + extended Use the extended POSIX regular expression grammar (grammar + documentation). + awk Use the regular expression grammar used by the awk utility in + POSIX (grammar documentation). + Use the regular expression grammar used by the grep utility in + grep POSIX. This is effectively the same as the basic option with the + addition of newline '\\n' as an alternation separator. + Use the regular expression grammar used by the grep utility, with + egrep the -E option, in POSIX. This is effectively the same as the + extended option with the addition of newline '\\n' as an + alternation separator in addition to '|'. + Grammar variation Effect(s) + icase Character matching should be performed without regard to case. + When performing matches, all marked sub-expressions (expr) are + nosubs treated as non-marking sub-expressions (?:expr). No matches are + stored in the supplied std::regex_match structure and mark_count() + is zero. + Instructs the regular expression engine to make matching faster, + optimize with the potential cost of making construction slower. For + example, this might mean converting a non-deterministic FSA to a + deterministic FSA. + collate Character ranges of the form "[a-b]" will be locale sensitive. + multiline \fI(C++17)\fP Specifies that ^ shall match the beginning of a line and $ shall + match the end of a line, if the ECMAScript engine is selected. + + At most one grammar option can be chosen out of ECMAScript, basic, extended, awk, + grep, egrep. If no grammar is chosen, ECMAScript is assumed to be selected. The + other options serve as variations, such that std::regex("meow", std::regex::icase) + is equivalent to std::regex("meow", std::regex::ECMAScript|std::regex::icase). + + The member constants in basic_regex are duplicates of the syntax_option_type + constants defined in the namespace std::regex_constants. + +.SH Non-member functions + + std::swap(std::basic_regex) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + + Deduction guides\fI(since C++17)\fP diff --git a/man/std::wregex::assign.3 b/man/std::wregex::assign.3 deleted file mode 120000 index 560822a86..000000000 --- a/man/std::wregex::assign.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::assign.3 \ No newline at end of file diff --git a/man/std::wregex::assign.3 b/man/std::wregex::assign.3 new file mode 100644 index 000000000..839482ea8 --- /dev/null +++ b/man/std::wregex::assign.3 @@ -0,0 +1,78 @@ +.TH std::basic_regex::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::assign \- std::basic_regex::assign + +.SH Synopsis + basic_regex& assign( const basic_regex& other ); \fB(1)\fP \fI(since C++11)\fP + basic_regex& assign( basic_regex&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + basic_regex& assign( const CharT* s, + flag_type f = \fB(3)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + basic_regex& assign( const CharT* ptr, std::size_t count, + flag_type f = \fB(4)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + template< class ST, class SA > + + basic_regex& assign( const std::basic_string& str, \fB(5)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + template< class InputIt > + + basic_regex& assign( InputIt first, InputIt last, \fB(6)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + basic_regex& assign( std::initializer_list ilist, + flag_type f = \fB(7)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + + Assigns the contents to the regular expression. + + 1) Assigns the contents of other. flags() and mark_count() are equivalent to the + values of other.flags() and other.mark_count() after the call. + 2) Assigns the contents of other using move semantics. flags() and mark_count() are + equivalent to the values of other.flags() and other.mark_count() before the + assignment. After the call, other is in a valid, but unspecified state. + 3-7) Assigns a sequence of characters to the regular expression. The syntax flags + are set to f. mark_count() returns the number of marked subexpressions within the + resulting subexpression after the call. + 3) Assigns a null-terminated string pointed to by s. + 4) Assigns a sequence of count characters, pointed to by s. + 5) Assigns the string str. + 6) Assigns the characters in the range [first, last). + 7) Assigns the characters in the initializer list ilist. + +.SH Parameters + + other - another regular expression to assign + s - pointer to a character sequence to assign + str - string to assign + first, last - the range of characters to assign + ilist - initializer list containing characters to assign +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 3-7) std::regex_error if the supplied regular expression is not valid. The object is + not modified in that case. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= assigns the contents + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wregex::basic_regex.3 b/man/std::wregex::basic_regex.3 deleted file mode 120000 index f094a24b8..000000000 --- a/man/std::wregex::basic_regex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::basic_regex.3 \ No newline at end of file diff --git a/man/std::wregex::basic_regex.3 b/man/std::wregex::basic_regex.3 new file mode 100644 index 000000000..79d139c71 --- /dev/null +++ b/man/std::wregex::basic_regex.3 @@ -0,0 +1,172 @@ +.TH std::basic_regex::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::basic_regex \- std::basic_regex::basic_regex + +.SH Synopsis + basic_regex(); \fB(1)\fP \fI(since C++11)\fP + explicit basic_regex( const CharT* s, + flag_type f = \fB(2)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + basic_regex( const CharT* s, std::size_t count, \fB(3)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( const basic_regex& other ); \fB(4)\fP \fI(since C++11)\fP + basic_regex( basic_regex&& other ) noexcept; \fB(5)\fP \fI(since C++11)\fP + template< class ST, class SA > + + explicit basic_regex( const std::basic_string& str, \fB(6)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + template< class ForwardIt > + + basic_regex( ForwardIt first, ForwardIt last, \fB(7)\fP \fI(since C++11)\fP + + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( std::initializer_list init, \fB(8)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + + Constructs a new regular expression from a sequence of characters interpreted + according to the flags f. + + 1) Default constructor. Constructs an empty regular expression which will match + nothing. + 2) Constructs a regex from a null-terminated string s. + 3) Constructs a regex from a sequence of count characters, pointed to by s. + 4) Copy constructor. Constructs a regex by copying other. + 5) Move constructor. Constructs a regex with the contents of other using move + semantics. + 6) Constructs a regex from a string str. + 7) Range constructor. Constructs the string with the contents of the range + [first, last). + 8) Initializer list constructor. Constructs the string with the contents of the + initializer list init. + +.SH Parameters + + s - pointer to a null-terminated string + count - length of a character sequence used to initialize the regex + first, last - range of a character sequence used to initialize the regex + str - a basic_string used as a source used to initialize the regex + other - another regex to use as source to initialize the regex + init - initializer list used to initialize the regex + f - flags used to guide the interpretation of the character sequence as a + regular expression +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 2,3) std::regex_error if the supplied regular expression is not valid. + 4) May throw implementation-defined exceptions. + 6-8) std::regex_error if the supplied regular expression is not valid. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void match_and_print(const std::string& text, const std::regex& pattern) + { + std::sregex_iterator it(text.begin(), text.end(), pattern), it_end; + int count = 0; + for (; it != it_end; ++it) + { + const std::smatch& match = *it; + std::cout << ++count << ". " << std::quoted(match.str()) << '\\n'; + } + std::cout << (count ? "\\n" : "no match found\\n\\n"); + } + + int main() + { + const std::string text = "Hello, World! 12345"; + + // Matches one or more digits + std::string pattern_text = "\\\\d+"; + std::cout << "digits (" << pattern_text << "):\\n"; + auto pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[^\\\\s]+"; + std::cout << "words (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[a-zA-Z]+"; + std::cout << "words without symbols and digits (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one non digits, non alphabet + pattern_text = "[^0-9A-Za-z]"; + std::cout << "symbol (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase + pattern_text = "[a-z]+"; + std::cout << "lowercase (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase with std::regex::icase flag + pattern_text = "[a-z]+"; + std::cout << "lowercase with ignore case flag (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::icase); + match_and_print(text, pattern); + + // Matches basic POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "basic POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::basic); + match_and_print(text, pattern); + + // Matches extended POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "extended POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::extended); + match_and_print(text, pattern); + } + +.SH Output: + + digits (\\d+): + 1. "12345" + + words ([^\\s]+): + 1. "Hello," + 2. "World!" + 3. "12345" + + words without symbols and digits ([a-zA-Z]+): + 1. "Hello" + 2. "World" + + symbol ([^0-9A-Za-z]): + 1. "," + 2. " " + 3. "!" + 4. " " + + lowercase ([a-z]+): + 1. "ello" + 2. "orld" + + lowercase with ignore case flag ([a-z]+): + 1. "Hello" + 2. "World" + + basic POSIX regex ([[:digit:]]+): + no match found + + extended POSIX regex ([[:digit:]]+): + 1. "12345" diff --git a/man/std::wregex::flags.3 b/man/std::wregex::flags.3 deleted file mode 120000 index d03d4186c..000000000 --- a/man/std::wregex::flags.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::flags.3 \ No newline at end of file diff --git a/man/std::wregex::flags.3 b/man/std::wregex::flags.3 new file mode 100644 index 000000000..f8f95a215 --- /dev/null +++ b/man/std::wregex::flags.3 @@ -0,0 +1,29 @@ +.TH std::basic_regex::flags 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::flags \- std::basic_regex::flags + +.SH Synopsis + flag_type flags() const; \fI(since C++11)\fP + + Returns the regular expression syntax flags as set in the constructor or the last + call to assign(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Current regular expression syntax flags. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wregex::getloc.3 b/man/std::wregex::getloc.3 deleted file mode 120000 index ea5268cf9..000000000 --- a/man/std::wregex::getloc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::getloc.3 \ No newline at end of file diff --git a/man/std::wregex::getloc.3 b/man/std::wregex::getloc.3 new file mode 100644 index 000000000..360a83e07 --- /dev/null +++ b/man/std::wregex::getloc.3 @@ -0,0 +1,36 @@ +.TH std::basic_regex::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::getloc \- std::basic_regex::getloc + +.SH Synopsis + locale_type getloc() const; \fI(since C++11)\fP + + Returns the current locale associated with the regular expression. + + Effectively calls traits_i.getloc() where traits_i is a default initialized instance + of the type Traits, stored within the regular expression object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The current locale associated with the regular expression. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + imbue set locale information + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wregex::imbue.3 b/man/std::wregex::imbue.3 deleted file mode 120000 index d967c1b28..000000000 --- a/man/std::wregex::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::imbue.3 \ No newline at end of file diff --git a/man/std::wregex::imbue.3 b/man/std::wregex::imbue.3 new file mode 100644 index 000000000..bf4ad79d2 --- /dev/null +++ b/man/std::wregex::imbue.3 @@ -0,0 +1,38 @@ +.TH std::basic_regex::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::imbue \- std::basic_regex::imbue + +.SH Synopsis + locale_type imbue( locale_type loc ); \fI(since C++11)\fP + + Replaces the current locale with loc. The regular expression does not match any + character sequence after the call. + + Effectively calls traits_i.imbue(loc) where traits_i is a default initialized + instance of the type Traits stored within the regular expression object. + +.SH Parameters + + loc - new locale to use + +.SH Return value + + The locale before the call to this function. Effectively returns the result of + expression traits_i.imbue(loc). + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + getloc get locale information + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wregex::mark_count.3 b/man/std::wregex::mark_count.3 deleted file mode 120000 index 1d852fd08..000000000 --- a/man/std::wregex::mark_count.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::mark_count.3 \ No newline at end of file diff --git a/man/std::wregex::mark_count.3 b/man/std::wregex::mark_count.3 new file mode 100644 index 000000000..20b3a9bf6 --- /dev/null +++ b/man/std::wregex::mark_count.3 @@ -0,0 +1,68 @@ +.TH std::basic_regex::mark_count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::mark_count \- std::basic_regex::mark_count + +.SH Synopsis + unsigned mark_count() const; \fI(since C++11)\fP + + Returns the number of marked sub-expressions (also known as capture groups) within + the regular expression. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of marked sub-expressions within the regular expression. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::regex r1{"abcde"}; + std::cout << "r1 has " << r1.mark_count() << " subexpressions" << '\\n'; + // Expected: 0 + + std::regex r2{"ab(c)de"}; + std::cout << "r2 has " << r2.mark_count() << " subexpressions" << '\\n'; + // Expected: 1 + + std::regex r3{"a(bc)d(e)"}; + std::cout << "r3 has " << r3.mark_count() << " subexpressions" << '\\n'; + // Expected: 2 + + // Nested sub-expressions + std::regex r4{"abc(de(fg))"}; + std::cout << "r4 has " << r4.mark_count() << " subexpressions" << '\\n'; + // Expected: 2 + + // Escaped parentheses + std::regex r5{"a(bc\\\\(\\\\)de)"}; + std::cout << "r5 has " << r5.mark_count() << " subexpressions" << '\\n'; + // Expected: 1 + + // Using nosubs flag + std::regex r6{"ab(c)de", std::regex_constants::nosubs}; + std::cout << "r6 has " << r6.mark_count() << " subexpressions" << '\\n'; + // Expected: 0 + } + +.SH Output: + + r1 has 0 subexpressions + r2 has 1 subexpressions + r3 has 2 subexpressions + r4 has 2 subexpressions + r5 has 1 subexpressions + r6 has 0 subexpressions diff --git a/man/std::wregex::operator=.3 b/man/std::wregex::operator=.3 deleted file mode 120000 index 2d634b06c..000000000 --- a/man/std::wregex::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::operator=.3 \ No newline at end of file diff --git a/man/std::wregex::operator=.3 b/man/std::wregex::operator=.3 new file mode 100644 index 000000000..160225b20 --- /dev/null +++ b/man/std::wregex::operator=.3 @@ -0,0 +1,46 @@ +.TH std::basic_regex::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::operator= \- std::basic_regex::operator= + +.SH Synopsis + Defined in header + basic_regex& operator=( const basic_regex& other ); \fB(1)\fP \fI(since C++11)\fP + basic_regex& operator=( basic_regex&& other ) noexcept; \fB(2)\fP \fI(since C++11)\fP + basic_regex& operator=( const CharT* ptr ); \fB(3)\fP \fI(since C++11)\fP + basic_regex& operator=( std::initializer_list il ); \fB(4)\fP \fI(since C++11)\fP + template< class ST, class SA > \fB(5)\fP \fI(since C++11)\fP + basic_regex& operator=( const std::basic_string& p ); + + Assigns the contents. + + 1) Copy assignment operator. Assigns the contents of other. Equivalent to + assign(other);. + 2) Move assignment operator. Assigns the contents of other using move semantics. + other is in valid, but unspecified state after the operation. Equivalent to + assign(other);. + 3) Assigns a null-terminated character string pointed to by ptr. Equivalent to + assign(ptr);. + 4) Assigns characters contained in initializer list il. Equivalent to assign(il);. + 5) Assigns the contents of the string p. Equivalent to assign(p);. + +.SH Parameters + + other - another regex object + ptr - pointer to a null-terminated character string + il - initializer list containing characters to assign + p - string containing characters to assign + +.SH Return value + + *this + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 3-5) std::regex_error if the supplied regular expression is not valid. The object is + not modified in that case. + +.SH See also + + assign assigns the contents + \fI(public member function)\fP diff --git a/man/std::wregex::swap.3 b/man/std::wregex::swap.3 deleted file mode 120000 index 1506664fd..000000000 --- a/man/std::wregex::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::swap.3 \ No newline at end of file diff --git a/man/std::wregex::swap.3 b/man/std::wregex::swap.3 new file mode 100644 index 000000000..7742099ee --- /dev/null +++ b/man/std::wregex::swap.3 @@ -0,0 +1,29 @@ +.TH std::basic_regex::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::swap \- std::basic_regex::swap + +.SH Synopsis + void swap( basic_regex& other ) noexcept; \fI(since C++11)\fP + + Exchanges the contents of two regular expressions. + +.SH Parameters + + other - the regular expression to swap with + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + std::swap(std::basic_regex) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wregex::wregex.3 b/man/std::wregex::wregex.3 deleted file mode 120000 index f094a24b8..000000000 --- a/man/std::wregex::wregex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::basic_regex.3 \ No newline at end of file diff --git a/man/std::wregex::wregex.3 b/man/std::wregex::wregex.3 new file mode 100644 index 000000000..79d139c71 --- /dev/null +++ b/man/std::wregex::wregex.3 @@ -0,0 +1,172 @@ +.TH std::basic_regex::basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::basic_regex \- std::basic_regex::basic_regex + +.SH Synopsis + basic_regex(); \fB(1)\fP \fI(since C++11)\fP + explicit basic_regex( const CharT* s, + flag_type f = \fB(2)\fP \fI(since C++11)\fP + std::regex_constants::ECMAScript ); + basic_regex( const CharT* s, std::size_t count, \fB(3)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( const basic_regex& other ); \fB(4)\fP \fI(since C++11)\fP + basic_regex( basic_regex&& other ) noexcept; \fB(5)\fP \fI(since C++11)\fP + template< class ST, class SA > + + explicit basic_regex( const std::basic_string& str, \fB(6)\fP \fI(since C++11)\fP + + flag_type f = + std::regex_constants::ECMAScript ); + template< class ForwardIt > + + basic_regex( ForwardIt first, ForwardIt last, \fB(7)\fP \fI(since C++11)\fP + + flag_type f = std::regex_constants::ECMAScript ); + basic_regex( std::initializer_list init, \fB(8)\fP \fI(since C++11)\fP + flag_type f = std::regex_constants::ECMAScript ); + + Constructs a new regular expression from a sequence of characters interpreted + according to the flags f. + + 1) Default constructor. Constructs an empty regular expression which will match + nothing. + 2) Constructs a regex from a null-terminated string s. + 3) Constructs a regex from a sequence of count characters, pointed to by s. + 4) Copy constructor. Constructs a regex by copying other. + 5) Move constructor. Constructs a regex with the contents of other using move + semantics. + 6) Constructs a regex from a string str. + 7) Range constructor. Constructs the string with the contents of the range + [first, last). + 8) Initializer list constructor. Constructs the string with the contents of the + initializer list init. + +.SH Parameters + + s - pointer to a null-terminated string + count - length of a character sequence used to initialize the regex + first, last - range of a character sequence used to initialize the regex + str - a basic_string used as a source used to initialize the regex + other - another regex to use as source to initialize the regex + init - initializer list used to initialize the regex + f - flags used to guide the interpretation of the character sequence as a + regular expression +.SH Type requirements + - + ForwardIt must meet the requirements of LegacyForwardIterator. + +.SH Exceptions + + 1) May throw implementation-defined exceptions. + 2,3) std::regex_error if the supplied regular expression is not valid. + 4) May throw implementation-defined exceptions. + 6-8) std::regex_error if the supplied regular expression is not valid. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void match_and_print(const std::string& text, const std::regex& pattern) + { + std::sregex_iterator it(text.begin(), text.end(), pattern), it_end; + int count = 0; + for (; it != it_end; ++it) + { + const std::smatch& match = *it; + std::cout << ++count << ". " << std::quoted(match.str()) << '\\n'; + } + std::cout << (count ? "\\n" : "no match found\\n\\n"); + } + + int main() + { + const std::string text = "Hello, World! 12345"; + + // Matches one or more digits + std::string pattern_text = "\\\\d+"; + std::cout << "digits (" << pattern_text << "):\\n"; + auto pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[^\\\\s]+"; + std::cout << "words (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more characters split by space + pattern_text = "[a-zA-Z]+"; + std::cout << "words without symbols and digits (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one non digits, non alphabet + pattern_text = "[^0-9A-Za-z]"; + std::cout << "symbol (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase + pattern_text = "[a-z]+"; + std::cout << "lowercase (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text); + match_and_print(text, pattern); + + // Matches one or more lowercase with std::regex::icase flag + pattern_text = "[a-z]+"; + std::cout << "lowercase with ignore case flag (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::icase); + match_and_print(text, pattern); + + // Matches basic POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "basic POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::basic); + match_and_print(text, pattern); + + // Matches extended POSIX regular expression + pattern_text = "[[:digit:]]+"; + std::cout << "extended POSIX regex (" << pattern_text << "):\\n"; + pattern = std::regex(pattern_text, std::regex::extended); + match_and_print(text, pattern); + } + +.SH Output: + + digits (\\d+): + 1. "12345" + + words ([^\\s]+): + 1. "Hello," + 2. "World!" + 3. "12345" + + words without symbols and digits ([a-zA-Z]+): + 1. "Hello" + 2. "World" + + symbol ([^0-9A-Za-z]): + 1. "," + 2. " " + 3. "!" + 4. " " + + lowercase ([a-z]+): + 1. "ello" + 2. "orld" + + lowercase with ignore case flag ([a-z]+): + 1. "Hello" + 2. "World" + + basic POSIX regex ([[:digit:]]+): + no match found + + extended POSIX regex ([[:digit:]]+): + 1. "12345" diff --git a/man/std::wregex::~basic_regex.3 b/man/std::wregex::~basic_regex.3 deleted file mode 120000 index 538571dc5..000000000 --- a/man/std::wregex::~basic_regex.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_regex::~basic_regex.3 \ No newline at end of file diff --git a/man/std::wregex::~basic_regex.3 b/man/std::wregex::~basic_regex.3 new file mode 100644 index 000000000..310ecee74 --- /dev/null +++ b/man/std::wregex::~basic_regex.3 @@ -0,0 +1,8 @@ +.TH std::basic_regex::~basic_regex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_regex::~basic_regex \- std::basic_regex::~basic_regex + +.SH Synopsis + ~basic_regex(); \fI(since C++11)\fP + + Destroys the regular expression object. diff --git a/man/std::ws.3 b/man/std::ws.3 index ea62c07c6..e07ce441e 100644 --- a/man/std::ws.3 +++ b/man/std::ws.3 @@ -1,8 +1,11 @@ -.TH std::ws 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ws 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ws \- std::ws + .SH Synopsis Defined in header template< class CharT, class Traits > - std::basic_istream& ws( std::basic_istream& is ); + std::basic_istream& ws( std::basic_istream& is ); Discards leading whitespace from an input stream. @@ -11,8 +14,9 @@ stream and discards them until any one of the following conditions occurs: * end of file condition occurs in the input sequence (in which case the function - calls setstate(eofbit) but does not set failbit. - + calls setstate(eofbit) but does not set failbit; this does not apply if the + eofbit is already set on is prior to the call to ws, in which case the + construction of the sentry object would set failbit). * the next available character c in the input sequence is not whitespace as determined by std::isspace(c, is.getloc()). The non-whitespace character is not extracted. @@ -26,29 +30,59 @@ .SH Return value - is (reference to the stream after extraction of consecutive whitespace) + is (reference to the stream after extraction of consecutive whitespace). + +.SH Notes + + If eofbit is set on the stream prior to the call, the construction of the sentry + object will set failbit. .SH Example - + // Run this code + #include #include + #include #include - + #include + int main() { - std::istringstream s(" this is a test"); - std::string line; - getline(s >> std::ws, line); - std::cout << "ws + getline returns: \\"" << line << "\\"\\n"; + for (const char* str : {" #1 test", "\\t #2 test", "#3 test"}) + { + std::string line; + std::getline(std::istringstream{str}, line); + std::cout << "getline returns:\\t" << std::quoted(line) << '\\n'; + + std::istringstream iss{str}; + std::getline(iss >> std::ws, line); + std::cout << "ws + getline returns:\\t" << std::quoted(line) << '\\n'; + } } .SH Output: - ws + getline returns: "this is a test" + getline returns: " #1 test" + ws + getline returns: "#1 test" + getline returns: " #2 test" + ws + getline returns: "#2 test" + getline returns: "#3 test" + ws + getline returns: "#3 test" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + calling std::ws might not construct the + LWG 415 C++98 sentry required to construct + object (insonsistent with other input the sentry object + functions) .SH See also ignore extracts and discards characters until the given character is found - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wscanf,std::fwscanf,std::swscanf.3 b/man/std::wscanf,std::fwscanf,std::swscanf.3 index 697c30592..34d56421a 100644 --- a/man/std::wscanf,std::fwscanf,std::swscanf.3 +++ b/man/std::wscanf,std::fwscanf,std::swscanf.3 @@ -1,9 +1,12 @@ -.TH std::wscanf,std::fwscanf,std::swscanf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wscanf,std::fwscanf,std::swscanf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wscanf,std::fwscanf,std::swscanf \- std::wscanf,std::fwscanf,std::swscanf + .SH Synopsis Defined in header - int wscanf( const wchar_t* format, ... ); \fB(1)\fP \fI(since C++11)\fP - int fwscanf( std::FILE* stream, const wchar_t* format, ... ); \fB(2)\fP \fI(since C++11)\fP - int swscanf( const wchar_t* buffer, const wchar_t* format, ... ); \fB(3)\fP \fI(since C++11)\fP + int wscanf( const wchar_t* format, ... ); \fB(1)\fP + int fwscanf( std::FILE* stream, const wchar_t* format, ... ); \fB(2)\fP + int swscanf( const wchar_t* buffer, const wchar_t* format, ... ); \fB(3)\fP Reads data from the a variety of sources, interprets it according to format and stores the results into given locations. @@ -16,10 +19,217 @@ stream - input file stream to read from buffer - pointer to a null-terminated wide string to read from - pointer to a null-terminated wide string specifying how to read the input. - format - - This section is incomplete - ... - receiving arguments + format - pointer to a null-terminated wide string specifying how to read the input + ... - receiving arguments. + + The format string consists of + + * non-whitespace wide characters except %: each such character in the format + string consumes exactly one identical character from the input stream, or causes + the function to fail if the next character on the stream does not compare equal. + * whitespace characters: any single whitespace character in the format string + consumes all available consecutive whitespace characters from the input + (determined as if by calling iswspace in a loop). Note that there is no + difference between "\\n", " ", "\\t\\t", or other whitespace in the format string. + * conversion specifications. Each conversion specification has the following + format: + + * introductory % character. + + * (optional) assignment-suppressing character *. If this option is present, the + function does not assign the result of the conversion to any receiving argument. + + * (optional) integer number (greater than zero) that specifies maximum field + width, that is, the maximum number of characters that the function is allowed to + consume when doing the conversion specified by the current conversion + specification. Note that %s and %[ may lead to buffer overflow if the width is + not provided. + + * (optional) length modifier that specifies the size of the receiving argument, + that is, the actual destination type. This affects the conversion accuracy and + overflow rules. The default destination type is different for each conversion + type (see table below). + + * conversion format specifier. + + The following format specifiers are available: + +Conversion Explanation Argument type +specifier + hh ll j z t + Length modifier → h \fI(none)\fP l L + \fI(C++11)\fP (C++11) (C++11) (C++11) (C++11) + % Matches literal %. N/A N/A N/A N/A N/A N/A N/A N/A N/A + Matches a character or + a sequence of + characters. + + If a width specifier + is used, matches + exactly width wide + c characters (the + argument must be a + pointer to an array + with sufficient room). + Unlike %s and %[, does + not append the null + character to the + array. + Matches a sequence of + non-whitespace + characters (a string). + + If width specifier is + used, matches up to + width or until the + first whitespace + s character, whichever + appears first. Always + stores a null + character in addition + to the characters + matched (so the + argument array must + have room for at least + width+1 characters) N/A N/A char* wchar_t* N/A N/A N/A N/A N/A + Matches a non-empty + sequence of character + from set of + characters. + + If the first character + of the set is ^, then + all characters not in + the set are matched. + If the set begins with + ] or ^] then the ] + character is also + included into the set. + It is + implementation-defined + [set] whether the character + - in the non-initial + position in the + scanset may be + indicating a range, as + in [0-9]. If width + specifier is used, + matches only up to + width. Always stores a + null character in + addition to the + characters matched (so + the argument array + must have room for at + least width+1 + characters) + Matches a decimal + integer. + + d The format of the + number is the same as + expected by wcstol + with the value 10 for + the base argument + Matches an integer. + + The format of the + number is the same as + i expected by wcstol + with the value 0 for + the base argument + (base is determined by + the first characters + parsed) + Matches an unsigned + decimal integer. + + u The format of the + number is the same as + expected by wcstoul signed + with the value 10 for signed signed signed signed long + the base argument. char* or short* int* or long* or long* or intmax_t* + Matches an unsigned unsigned or unsigned unsigned unsigned or size_t* ptrdiff_t* N/A + octal integer. char* unsigned int* long* long uintmax_t* + short* long* + o The format of the + number is the same as + expected by wcstoul + with the value 8 for + the base argument + Matches an unsigned + hexadecimal integer. + + x, X The format of the + number is the same as + expected by wcstoul + with the value 16 for + the base argument + Returns the number of + characters read so + far. + + No input is consumed. + n Does not increment the + assignment count. If + the specifier has + assignment-suppressing + operator defined, the + behavior is undefined + a, Matches a + A\fI(C++11)\fP floating-point number. + e, E N/A N/A float* double* N/A N/A N/A N/A long + f, F The format of the double* + g, G number is the same as + expected by wcstof + Matches implementation + defined character + sequence defining a + pointer. + p N/A N/A void** N/A N/A N/A N/A N/A N/A + printf family of + functions should + produce the same + sequence using %p + format specifier + + For every conversion specifier other than n, the longest sequence of input + characters which does not exceed any specified field width and which either is + exactly what the conversion specifier expects or is a prefix of a sequence it would + expect, is what's consumed from the stream. The first character, if any, after this + consumed sequence remains unread. If the consumed sequence has length zero or if the + consumed sequence cannot be converted as specified above, the matching failure + occurs unless end-of-file, an encoding error, or a read error prevented input from + the stream, in which case it is an input failure. + + All conversion specifiers other than [, c, and n consume and discard all leading + whitespace characters (determined as if by calling iswspace) before attempting to + parse the input. These consumed characters do not count towards the specified + maximum field width. + + If the length specifier l is not used, the conversion specifiers c, s, and [ perform + wide-to-multibyte character conversion as if by calling wcrtomb with an mbstate_t + object initialized to zero before the first character is converted. + + The conversion specifiers s and [ always store the null terminator in addition to + the matched characters. The size of the destination array must be at least one + greater than the specified field width. The use of %s or %[, without specifying the + destination array size, is as unsafe as std::gets. + + The correct conversion specifications for the fixed-width integer types (int8_t, + etc) are defined in the header (although SCNdMAX, SCNuMAX, etc is + synonymous with %jd, %ju, etc). + + There is a sequence point after the action of each conversion specifier; this + permits storing multiple fields in the same "sink" variable. + + When parsing an incomplete floating-point value that ends in the exponent with no + digits, such as parsing "100er" with the conversion specifier %f, the sequence + "100e" (the longest prefix of a possibly valid floating-point number) is consumed, + resulting in a matching error (the consumed sequence cannot be converted to a + floating-point number), with "r" remaining. Some existing implementations do not + follow this rule and roll back to consume only "100", leaving "er", e.g. glibc bug + 1765. .SH Return value @@ -36,7 +246,7 @@ vwscanf vfwscanf reads formatted wide character input from stdin, a file stream vswscanf or a buffer using variable argument list - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP \fI(C++11)\fP \fI(C++11)\fP C documentation for @@ -44,7 +254,5 @@ fwscanf, swscanf - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::wstreambuf.3 b/man/std::wstreambuf.3 deleted file mode 120000 index bfae638a6..000000000 --- a/man/std::wstreambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf.3 \ No newline at end of file diff --git a/man/std::wstreambuf.3 b/man/std::wstreambuf.3 new file mode 100644 index 000000000..9c01629e8 --- /dev/null +++ b/man/std::wstreambuf.3 @@ -0,0 +1,194 @@ +.TH std::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf \- std::basic_streambuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_streambuf; + + The class basic_streambuf controls input and output to a character sequence. It + includes and provides access to + + 1. The controlled character sequence, also called the buffer, which may contain + input sequence (also called get area) for buffering the input operations and/or + output sequence (also called put area) for buffering the output operations. + 2. The associated character sequence, also called source (for input) or sink (for + output). This may be an entity that is accessed through OS API (file, TCP + socket, serial port, other character device), or it may be an object + (std::vector, array, string literal), that can be interpreted as a character + source or sink. + + The I/O stream objects std::basic_istream and std::basic_ostream, as well as all + objects derived from them (std::ofstream, std::stringstream, etc), are implemented + entirely in terms of std::basic_streambuf. + + The controlled character sequence is an array of CharT which, at all times, + represents a subsequence, or a "window" into the associated character sequence. Its + state is described by three pointers: + + 1. The beginning pointer, always points at the lowest element of the buffer. + 2. The next pointer, points at the element that is the next candidate for reading + or writing. + 3. The end pointer, points one past the end of the buffer. + + A basic_streambuf object may support input (in which case the buffer described by + the beginning, next, and end pointers is called get area), output (put area), or + input and output simultaneously. In latter case, six pointers are tracked, which may + all point to elements of the same character array or two individual arrays. + + If the next pointer is less than the end pointer in the put area, a write position + is available. The next pointer can be dereferenced and assigned to. + + If the next pointer is less than the end pointer in the get area, a read position is + available. The next pointer can be dereferenced and read from. + + If the next pointer is greater than the beginning pointer in a get area, a putback + position is available, and the next pointer may be decremented, dereferenced, and + assigned to, in order to put a character back into the get area. + + The character representation and encoding in the controlled sequence may be + different from the character representations in the associated sequence, in which + case a std::codecvt locale facet is typically used to perform the conversion. Common + examples are UTF-8 (or other multibyte) files accessed through std::wfstream + objects: the controlled sequence consists of wchar_t characters, but the associated + sequence consists of bytes. + + Typical implementation of the std::basic_streambuf base class holds only the six + CharT* pointers and a copy of std::locale as data members. In addition, + implementations may keep cached copies of locale facets, which are invalidated + whenever imbue() is called. The concrete buffers such as std::basic_filebuf or + std::basic_stringbuf are derived from std::basic_streambuf. + + std-streambuf.svg + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::streambuf std::basic_streambuf + std::wstreambuf std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI(virtual public member function)\fP +.SH Locales + pubimbue invokes imbue() + \fI(public member function)\fP + getloc obtains a copy of the associated locale + \fI(public member function)\fP +.SH Positioning + pubsetbuf invokes setbuf() + \fI(public member function)\fP + pubseekoff invokes seekoff() + \fI(public member function)\fP + pubseekpos invokes seekpos() + \fI(public member function)\fP + pubsync invokes sync() + \fI(public member function)\fP +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function)\fP + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function)\fP + sgetn invokes xsgetn() + \fI(public member function)\fP +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function)\fP + sputn invokes xsputn() + \fI(public member function)\fP +.SH Putback + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP +.SH Protected member functions + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI(virtual protected member function)\fP +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output + \fB[virtual]\fP sequence, or both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output + \fB[virtual]\fP sequence, or both using absolute addressing + \fI(virtual protected member function)\fP + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP +.SH Get area + showmanyc obtains the number of characters available for input in the + \fB[virtual]\fP associated input sequence, if known + \fI(virtual protected member function)\fP + underflow reads characters from the associated input sequence to the get + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + uflow reads characters from the associated input sequence to the get + \fB[virtual]\fP area and advances the next pointer + \fI(virtual protected member function)\fP + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + eback returns a pointer to the beginning, current character and the end + gptr of the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put + \fB[virtual]\fP area + \fI(virtual protected member function)\fP + pbase returns a pointer to the beginning, current character and the end + pptr of the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + pbackfail puts a character back into the input sequence, possibly modifying + \fB[virtual]\fP the input sequence + \fI(virtual protected member function)\fP + +.SH See also + + object type, capable of holding all information needed to control a C I/O + FILE stream + \fI(typedef)\fP diff --git a/man/std::wstreambuf::basic_streambuf.3 b/man/std::wstreambuf::basic_streambuf.3 deleted file mode 120000 index 463e017b7..000000000 --- a/man/std::wstreambuf::basic_streambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::basic_streambuf.3 \ No newline at end of file diff --git a/man/std::wstreambuf::basic_streambuf.3 b/man/std::wstreambuf::basic_streambuf.3 new file mode 100644 index 000000000..caf4b3077 --- /dev/null +++ b/man/std::wstreambuf::basic_streambuf.3 @@ -0,0 +1,49 @@ +.TH std::basic_streambuf::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::basic_streambuf \- std::basic_streambuf::basic_streambuf + +.SH Synopsis + protected: \fB(1)\fP + basic_streambuf(); + protected: \fB(2)\fP \fI(since C++11)\fP + basic_streambuf(const basic_streambuf& rhs); + + 1) Constructs the basic_streambuf object, initializes the six pointer members + (eback(), gptr(), egptr(), pbase(), pptr(), and epptr()) to null pointer values, and + the locale member to std::locale(), a copy of the global C++ locale at the time of + construction. + 2) Constructs a copy of rhs, initializing the six pointers and the locale object + with the copies of the values held by rhs. Note that this is a shallow copy: the + pointers of the newly-constructed basic_streambuf are pointing into the same + character array as the pointers of rhs. + + Both constructors are protected, and are only called by the concrete streambuf + classes, such as std::basic_filebuf, std::basic_stringbuf, or std::strstreambuf. + +.SH Parameters + + rhs - a streambuf object to copy + +.SH Notes + + Until C++11, it was unspecified whether basic_streambuf or any of its derived + classes is CopyConstructible (LWG issue 421), and different C++ library + implementations provided different options. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function of std::basic_filebuf)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) + constructor constructs a strstreambuf object + \fI(public member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::eback,gptr,egptr.3 b/man/std::wstreambuf::eback,gptr,egptr.3 deleted file mode 120000 index 9272ab2e5..000000000 --- a/man/std::wstreambuf::eback,gptr,egptr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::eback,gptr,egptr.3 \ No newline at end of file diff --git a/man/std::wstreambuf::eback,gptr,egptr.3 b/man/std::wstreambuf::eback,gptr,egptr.3 new file mode 100644 index 000000000..f20ec2496 --- /dev/null +++ b/man/std::wstreambuf::eback,gptr,egptr.3 @@ -0,0 +1,48 @@ +.TH std::basic_streambuf::eback,gptr,egptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::eback,gptr,egptr \- std::basic_streambuf::eback,gptr,egptr + +.SH Synopsis + char_type* eback() const; \fB(1)\fP + char_type* gptr() const; \fB(2)\fP + char_type* egptr() const; \fB(3)\fP + + Returns pointers defining the get area. + + 1) Returns the pointer to the beginning of the get area. + + 2) Returns the pointer to the current character (get pointer) in the get area. + + 3) Returns the pointer one past the end of the get area. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The pointer to the beginning of the get area. + + 2) The pointer to the current character (get pointer) in the get area. + + 3) The pointer one past the end of the get area. + +.SH Notes + + While the names "gptr" and "egptr" refer to the get area, the name "eback" refers to + the end of the putback area: stepping backwards from gptr, characters can be put + back until eback. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pbase returns a pointer to the beginning, current character and the end of the put + pptr area + epptr \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::gbump.3 b/man/std::wstreambuf::gbump.3 deleted file mode 120000 index 6139613fb..000000000 --- a/man/std::wstreambuf::gbump.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::gbump.3 \ No newline at end of file diff --git a/man/std::wstreambuf::gbump.3 b/man/std::wstreambuf::gbump.3 new file mode 100644 index 000000000..232521c5f --- /dev/null +++ b/man/std::wstreambuf::gbump.3 @@ -0,0 +1,47 @@ +.TH std::basic_streambuf::gbump 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::gbump \- std::basic_streambuf::gbump + +.SH Synopsis + protected: + void gbump( int count ); + + Skips count characters in the get area. This is done by adding count to the get + pointer. No checks are done for underflow. + +.SH Parameters + + count - number of characters to skip + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Because this function takes an int, it cannot manipulate buffers larger than + std::numeric_limits::max() characters (LWG issue 255). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether gbump can be implemented + LWG 59 C++98 as only add count + calling sbumpc count times (which may check to the get pointer + underflow) + +.SH See also + + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::getloc.3 b/man/std::wstreambuf::getloc.3 deleted file mode 120000 index a48ea6737..000000000 --- a/man/std::wstreambuf::getloc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::getloc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::getloc.3 b/man/std::wstreambuf::getloc.3 new file mode 100644 index 000000000..c8569e47a --- /dev/null +++ b/man/std::wstreambuf::getloc.3 @@ -0,0 +1,33 @@ +.TH std::basic_streambuf::getloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::getloc \- std::basic_streambuf::getloc + +.SH Synopsis + std::locale getloc() const; + + Returns the associated locale. + + The associated locale is the value supplied to pubimbue() on the last call, or, if + that function has not been called, the value of the global locale (std::locale) at + the time of the construction of the streambuf. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated locale. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + pubimbue invokes imbue() + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::in_avail.3 b/man/std::wstreambuf::in_avail.3 deleted file mode 120000 index 5303abddb..000000000 --- a/man/std::wstreambuf::in_avail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::in_avail.3 \ No newline at end of file diff --git a/man/std::wstreambuf::in_avail.3 b/man/std::wstreambuf::in_avail.3 new file mode 100644 index 000000000..48555272e --- /dev/null +++ b/man/std::wstreambuf::in_avail.3 @@ -0,0 +1,44 @@ +.TH std::basic_streambuf::in_avail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::in_avail \- std::basic_streambuf::in_avail + +.SH Synopsis + std::streamsize in_avail(); + + Returns the number of characters available in the get area. If a read position is + available, effectively returns egptr() - gptr(), the size of the get area. In this + case, the number of bytes returned is the number of bytes that can be extracted from + the buffer without calling underflow(). + + If the get area is empty, calls showmanyc() to determine the number of bytes + available in the associated character sequence. In this case, the value returned is + the number of bytes that can be extracted from the buffer while it's guaranteed that + underflow() would not return Traits::eof. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters available for non-blocking read (either the size of the get + area or the number of characters ready for reading from the associated character + sequence), or -1 if no characters are available in the associated sequence as far as + showmanyc() can tell. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + optionally provides the number of characters available for input from the + showmanyc file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::operator=.3 b/man/std::wstreambuf::operator=.3 deleted file mode 120000 index 617c89cf6..000000000 --- a/man/std::wstreambuf::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::operator=.3 \ No newline at end of file diff --git a/man/std::wstreambuf::operator=.3 b/man/std::wstreambuf::operator=.3 new file mode 100644 index 000000000..948add624 --- /dev/null +++ b/man/std::wstreambuf::operator=.3 @@ -0,0 +1,28 @@ +.TH std::basic_streambuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::operator= \- std::basic_streambuf::operator= + +.SH Synopsis + basic_streambuf& operator=( const basic_streambuf& other ); \fI(since C++11)\fP + + Assigns the data members of other to *this. + +.SH Parameters + + other - stream buffer to assign + +.SH Return value + + *this + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::overflow.3 b/man/std::wstreambuf::overflow.3 deleted file mode 120000 index 6516fb5c8..000000000 --- a/man/std::wstreambuf::overflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::overflow.3 \ No newline at end of file diff --git a/man/std::wstreambuf::overflow.3 b/man/std::wstreambuf::overflow.3 new file mode 100644 index 000000000..bf2dc6d77 --- /dev/null +++ b/man/std::wstreambuf::overflow.3 @@ -0,0 +1,130 @@ +.TH std::basic_streambuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::overflow \- std::basic_streambuf::overflow + +.SH Synopsis + protected: + virtual int_type overflow( int_type ch = Traits::eof() ); + + Ensures that there is space at the put area for at least one character by saving + some initial subsequence of characters starting at pbase() to the output sequence + and updating the pointers to the put area (if needed). If ch is not Traits::eof() + (i.e. Traits::eq_int_type(ch, Traits::eof()) != true), it is either put to the put + area or directly saved to the output sequence. + + The function may update pptr, epptr and pbase pointers to define the location to + write more data. On failure, the function ensures that either pptr() == nullptr or + pptr() == epptr. + + The base class version of the function does nothing. The derived classes may + override this function to allow updates to the put area in the case of exhaustion. + +.SH Parameters + + ch - the character to store in the put area + +.SH Return value + + Returns unspecified value not equal to Traits::eof() on success, Traits::eof() on + failure. + + The base class version of the function returns Traits::eof(). + +.SH Note + + The sputc() and sputn() call this function in case of an overflow (pptr() == nullptr + or pptr() >= epptr()). + +.SH Example + + +// Run this code + + #include + #include + #include + + // Buffer for std::ostream implemented by std::array + template + struct ArrayedStreamBuffer : std::basic_streambuf + { + using Base = std::basic_streambuf; + using char_type = typename Base::char_type; + using int_type = typename Base::int_type; + + ArrayedStreamBuffer() + { + // put area pointers to work with 'buffer' + Base::setp(buffer.data(), buffer.data() + size); + } + + int_type overflow(int_type ch) + { + std::cout << "overflow\\n"; + return Base::overflow(ch); + } + + void print_buffer() + { + for (char_type i : buffer) + { + if (i == 0) + std::cout << "\\\\0"; + else + std::cout << i; + std::cout << ' '; + } + std::cout << '\\n'; + } + + private: + std::array buffer{}; // value-initialize buffer + }; + + int main() + { + ArrayedStreamBuffer<10> streambuf; + std::ostream stream(&streambuf); + + stream << "hello"; + streambuf.print_buffer(); + if (stream.good()) + std::cout << "stream is good\\n"; + + stream << "world"; + streambuf.print_buffer(); + if (stream.good()) + std::cout << "stream is good\\n"; + + stream << "!"; + streambuf.print_buffer(); + if (!stream.good()) + std::cout << "stream is not good\\n"; + } + +.SH Output: + + h e l l o \\0 \\0 \\0 \\0 \\0 + stream is good + h e l l o w o r l d + stream is good + overflow + h e l l o w o r l d + stream is not good + +.SH See also + + uflow reads characters from the associated input sequence to the get area and + \fB[virtual]\fP advances the next pointer + \fI(virtual protected member function)\fP + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + overflow appends a character to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + overflow appends a character to the output sequence, may reallocate or initially + \fB[virtual]\fP allocate the buffer if dynamic and not frozen + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::wstreambuf::pbackfail.3 b/man/std::wstreambuf::pbackfail.3 deleted file mode 120000 index 61b5c6712..000000000 --- a/man/std::wstreambuf::pbackfail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pbackfail.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pbackfail.3 b/man/std::wstreambuf::pbackfail.3 new file mode 100644 index 000000000..e44f8b8d1 --- /dev/null +++ b/man/std::wstreambuf::pbackfail.3 @@ -0,0 +1,78 @@ +.TH std::basic_streambuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbackfail \- std::basic_streambuf::pbackfail + +.SH Synopsis + protected: + virtual int_type pbackfail( int_type c = Traits::eof() ); + + This function can only be called if any of the following condition is satisfied: + + * gptr() is null, + * gptr() == eback(), or + * traits::eq(traits::to_char_type(c), gptr()[-1]) returns false. + + This function is called by the public functions sungetc() and sputbackc() (which, in + turn, are called by basic_istream::unget and basic_istream::putback) when either: + + 1) There is no putback position in the get area (pbackfail() is called with no + arguments). In this situation, the purpose of pbackfail() is to back up the get area + by one character, if the associated character sequence allows this (e.g. a + file-backed streambuf may reload the buffer from a file, starting one character + earlier). + 2) The caller attempts to putback a different character from the one retrieved + earlier (pbackfail() is called with the character that needs to be put back). In + this situation, the purpose of pbackfail() is to place the character c into the get + area at the position just before basic_streambuf::gptr(), and, if possible, to + modify the associated character sequence to reflect this change. This may involve + backing up the get area as in the first variant. + + The default base class version of this function does nothing and returns + Traits::eof() in all situations. This function is overridden by the derived classes: + basic_stringbuf::pbackfail, basic_filebuf::pbackfail, strstreambuf::pbackfail, and + is expected to be overridden by user-defined and third-party library stream classes. + +.SH Parameters + + ch - character to put back or Traits::eof() if only back out is requested + +.SH Return value + + Traits::eof() in case of failure, some other value to indicate success. The base + class version always fails. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct + behavior + the calling condition corrected to + LWG 32 C++98 'traits::eq(*gptr(),traits::to_char_type(c)) match + returns false' did not match the description of the + sputbackc() description + +.SH See also + + backs out the input sequence to unget a character, not affecting the + pbackfail associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + pbackfail puts a character back into the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + pbackfail backs out the input sequence to unget a character + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::pbase,std::basic_streambuf::pptr,.3 b/man/std::wstreambuf::pbase,std::basic_streambuf::pptr,.3 new file mode 100644 index 000000000..16799c237 --- /dev/null +++ b/man/std::wstreambuf::pbase,std::basic_streambuf::pptr,.3 @@ -0,0 +1,46 @@ +.TH std::basic_streambuf::pbase,std::basic_streambuf::pptr, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbase,std::basic_streambuf::pptr, \- std::basic_streambuf::pbase,std::basic_streambuf::pptr, + +.SH Synopsis + + protected: \fB(1)\fP + char_type* pbase() const; + protected: \fB(2)\fP + char_type* pptr() const; + protected: \fB(3)\fP + char_type* epptr() const; + + Returns pointers defining the put area. + + 1) Returns the pointer to the beginning ("base") of the put area. + + 2) Returns the pointer to the current character (put pointer) in the put area. + + 3) Returns the pointer one past the end of the put area. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The pointer to the beginning of the put area. + + 2) The pointer to the current character (put pointer) in the put area. + + 3) The pointer one past the end of the put area. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + eback returns a pointer to the beginning, current character and the end of the get + gptr area + egptr \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 b/man/std::wstreambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 deleted file mode 120000 index 5ba1fb9b8..000000000 --- a/man/std::wstreambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pbase,std::basic_streambuf::pptr,std::basic_streambuf::epptr.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pbump.3 b/man/std::wstreambuf::pbump.3 deleted file mode 120000 index a149359c2..000000000 --- a/man/std::wstreambuf::pbump.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pbump.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pbump.3 b/man/std::wstreambuf::pbump.3 new file mode 100644 index 000000000..cc71e077b --- /dev/null +++ b/man/std::wstreambuf::pbump.3 @@ -0,0 +1,67 @@ +.TH std::basic_streambuf::pbump 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pbump \- std::basic_streambuf::pbump + +.SH Synopsis + protected: + void pbump( int count ); + + Repositions the put pointer (pptr()) by count characters, where count may be + positive or negative. No checks are done for moving the pointer outside the put area + [pbase(), epptr()). + + If the pointer is advanced and then overflow() is called to flush the put area to + the associated character sequence, the effect is that extra count characters with + undefined values are output. + +.SH Parameters + + count - number to add to the put pointer + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Because this function takes an int, it cannot manipulate buffers larger than + std::numeric_limits::max() characters (LWG issue 255). + +.SH Example + + +// Run this code + + #include + #include + #include + + struct showput_streambuf : std::filebuf + { + using std::filebuf::pbump; // expose protected + std::string showput() const + { + return std::string(pbase(), pptr()); + } + }; + + int main() + { + showput_streambuf mybuf; + mybuf.open("test.txt", std::ios_base::out); + std::ostream str(&mybuf); + str << "This is a test" << std::flush << "1234"; + std::cout << "The put area contains: " << mybuf.showput() << '\\n'; + mybuf.pbump(10); + std::cout << "after pbump(10), it contains " << mybuf.showput() << '\\n'; + } + +.SH Output: + + The put area contains: 1234 + after pbump\fB(10)\fP, it contains 1234 is a test + +.SH See also + + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP diff --git a/man/std::wstreambuf::pubimbue,std::basic_streambuf::imbue.3 b/man/std::wstreambuf::pubimbue,std::basic_streambuf::imbue.3 deleted file mode 120000 index 47873c26f..000000000 --- a/man/std::wstreambuf::pubimbue,std::basic_streambuf::imbue.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubimbue,std::basic_streambuf::imbue.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pubimbue,std::basic_streambuf::imbue.3 b/man/std::wstreambuf::pubimbue,std::basic_streambuf::imbue.3 new file mode 100644 index 000000000..c84c38d7a --- /dev/null +++ b/man/std::wstreambuf::pubimbue,std::basic_streambuf::imbue.3 @@ -0,0 +1,37 @@ +.TH std::basic_streambuf::pubimbue,std::basic_streambuf::imbue 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubimbue,std::basic_streambuf::imbue \- std::basic_streambuf::pubimbue,std::basic_streambuf::imbue + +.SH Synopsis + std::locale pubimbue( const std::locale& loc ); \fB(1)\fP + protected: \fB(2)\fP + virtual void imbue( const std::locale& loc ); + + Changes the associated locale. + + 1) Sets loc as the associated locale. Calls imbue(loc) of the most derived class + + 2) The base class version of this function has no effect. The derived classes may + override this function in order to be informed about the changes of the locale. The + derived class may cache the locale and member facets between calls to imbue(). + +.SH Parameters + + loc - locale object to associate + +.SH Return value + + 1) Previous associated locale. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + getloc obtains a copy of the associated locale + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::pubseekoff,.3 b/man/std::wstreambuf::pubseekoff,.3 new file mode 100644 index 000000000..6fddf66cc --- /dev/null +++ b/man/std::wstreambuf::pubseekoff,.3 @@ -0,0 +1,84 @@ +.TH std::basic_streambuf::pubseekoff, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubseekoff, \- std::basic_streambuf::pubseekoff, + +.SH Synopsis + + pos_type pubseekoff( off_type off, std::ios_base::seekdir dir, + std::ios_base::openmode which = ios_base::in | \fB(1)\fP + ios_base::out ); + protected: + + virtual pos_type seekoff( off_type off, std::ios_base::seekdir dir, \fB(2)\fP + + std::ios_base::openmode which = ios_base::in | + ios_base::out ); + + Sets the position indicator of the input and/or output sequence relative to some + other position. + + 1) Calls seekoff(off, dir, which) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow relative positioning of the position indicator. + +.SH Parameters + + off - relative position to set the position indicator to. + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Note + + Not all combinations of parameters may be valid, see the derived versions of seekoff + for details. + +.SH Return value + + 1) The return value of seekoff(off, dir, which) + 2) The resulting absolute position as defined by the position indicator. The base + class version returns pos_type(off_type(-1)). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the base class version of seekoff + LWG 55 C++98 returned returns pos_type(off_type(-1)) + an undefined invalid stream + position + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekoff both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::pubseekoff,std::basic_streambuf::seekoff.3 b/man/std::wstreambuf::pubseekoff,std::basic_streambuf::seekoff.3 deleted file mode 120000 index bfc3586fb..000000000 --- a/man/std::wstreambuf::pubseekoff,std::basic_streambuf::seekoff.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubseekoff,std::basic_streambuf::seekoff.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pubseekpos,.3 b/man/std::wstreambuf::pubseekpos,.3 new file mode 100644 index 000000000..ed46050b4 --- /dev/null +++ b/man/std::wstreambuf::pubseekpos,.3 @@ -0,0 +1,72 @@ +.TH std::basic_streambuf::pubseekpos, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubseekpos, \- std::basic_streambuf::pubseekpos, + +.SH Synopsis + + pos_type pubseekpos( pos_type pos, + std::ios_base::openmode which = std::ios_base::in | \fB(1)\fP + std::ios_base::out ); + protected: + + virtual pos_type seekpos( pos_type pos, \fB(2)\fP + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Sets the position indicator of the input and/or output sequence to an absolute + position. + + 1) Calls seekpos(pos, which) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow absolute positioning of the position indicator. + +.SH Parameters + + pos - absolute position to set the position indicator to + defines which of the input and/or output sequences to affect. It can be one + or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + 1) The return value of seekpos(pos, which). + 2) The resulting absolute position as defined by the position indicator. The base + class version returns pos_type(off_type(-1)). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the base class version of seekpos + LWG 55 C++98 returned returns pos_type(off_type(-1)) + an undefined invalid stream + position + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + repositions the next pointer in the input sequence, output sequence, or + seekpos both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::pubseekpos,std::basic_streambuf::seekpos.3 b/man/std::wstreambuf::pubseekpos,std::basic_streambuf::seekpos.3 deleted file mode 120000 index e1c6dedfd..000000000 --- a/man/std::wstreambuf::pubseekpos,std::basic_streambuf::seekpos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubseekpos,std::basic_streambuf::seekpos.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pubsetbuf,std::basic_streambuf::setbuf.3 b/man/std::wstreambuf::pubsetbuf,std::basic_streambuf::setbuf.3 deleted file mode 120000 index a3e744500..000000000 --- a/man/std::wstreambuf::pubsetbuf,std::basic_streambuf::setbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pubsetbuf,std::basic_streambuf::setbuf.3 b/man/std::wstreambuf::pubsetbuf,std::basic_streambuf::setbuf.3 new file mode 100644 index 000000000..96e049f19 --- /dev/null +++ b/man/std::wstreambuf::pubsetbuf,std::basic_streambuf::setbuf.3 @@ -0,0 +1,81 @@ +.TH std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf \- std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf + +.SH Synopsis + public: \fB(1)\fP + basic_streambuf* pubsetbuf( char_type* s, std::streamsize n ) + protected: + virtual basic_streambuf* setbuf( char_type* s, std::streamsize n \fB(2)\fP + ) + + 1) Calls setbuf(s, n) of the most derived class. + 2) The base class version of this function has no effect. The derived classes may + override this function to allow removal or replacement of the controlled character + sequence (the buffer) with a user-provided array, or for any other + implementation-specific purpose. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer + n - the number of CharT elements in the user-provided buffer + +.SH Return value + + 1) The return value of setbuf(s, n). + 2) this + +.SH Example + + Provides a 10k buffer for reading. On linux, the strace utility may be used to + observe the actual number of bytes read. + + +// Run this code + + #include + #include + #include + + int main() + { + int cnt = 0; + std::ifstream file; + char buf[1024 * 10 + 1]; + + file.rdbuf()->pubsetbuf(buf, sizeof buf); + + file.open("/usr/share/dict/words"); + + for (std::string line; getline(file, line);) + ++cnt; + + std::cout << cnt << '\\n'; + } + +.SH Possible output: + + 356010 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the default behavior of setbuf was only specified as no-op + LWG 158 C++98 specified for all cases + if gptr() is not null and not equal to egptr() + +.SH See also + + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + setbuf provides user-supplied buffer or turns this filebuf unbuffered + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP + setbuf sets the buffer for a file stream + \fI(function)\fP diff --git a/man/std::wstreambuf::pubsync,std::basic_streambuf::sync.3 b/man/std::wstreambuf::pubsync,std::basic_streambuf::sync.3 deleted file mode 120000 index 31fe3b450..000000000 --- a/man/std::wstreambuf::pubsync,std::basic_streambuf::sync.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::pubsync,std::basic_streambuf::sync.3 \ No newline at end of file diff --git a/man/std::wstreambuf::pubsync,std::basic_streambuf::sync.3 b/man/std::wstreambuf::pubsync,std::basic_streambuf::sync.3 new file mode 100644 index 000000000..d35616600 --- /dev/null +++ b/man/std::wstreambuf::pubsync,std::basic_streambuf::sync.3 @@ -0,0 +1,49 @@ +.TH std::basic_streambuf::pubsync,std::basic_streambuf::sync 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::pubsync,std::basic_streambuf::sync \- std::basic_streambuf::pubsync,std::basic_streambuf::sync + +.SH Synopsis + int pubsync(); \fB(1)\fP + protected: \fB(2)\fP + virtual int sync(); + + Synchronizes the controlled character sequence (the buffers) with the associated + character sequence. + + 1) Calls sync() of the most derived class + + 2) The base class version of this function has no effect. The derived classes may + override this function to allow synchronizing the underlying device with the + buffers. + + For output streams, this typically results in writing the contents of the put area + into the associated sequence, i.e. flushing of the output buffer. For input streams, + this typically empties the get area and forces a re-read from the associated + sequence to pick up recent changes. The default behavior (found, for example, in + std::basic_stringbuf), is to do nothing. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The return value of sync(). + + 2) Returns 0 on success, -1 otherwise. The base class version returns 0. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + sync writes characters to the associated file from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::sbumpc,std::basic_streambuf::stossc.3 b/man/std::wstreambuf::sbumpc,std::basic_streambuf::stossc.3 new file mode 100644 index 000000000..b93e84b61 --- /dev/null +++ b/man/std::wstreambuf::sbumpc,std::basic_streambuf::stossc.3 @@ -0,0 +1,38 @@ +.TH std::basic_streambuf::sbumpc,std::basic_streambuf::stossc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sbumpc,std::basic_streambuf::stossc \- std::basic_streambuf::sbumpc,std::basic_streambuf::stossc + +.SH Synopsis + int_type sbumpc(); \fB(1)\fP + void stossc(); \fB(2)\fP (deprecated in C++98) + (removed in C++17) + + Reads one character and advances the input sequence by one character. + + 1) If the input sequence read position is not available, returns uflow(). Otherwise + returns Traits::to_int_type(*gptr()). + 2) Same as \fB(1)\fP, but discards the result. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The value of the character pointed to by the get pointer, or Traits::eof() if the + read position is not available. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function)\fP + snextc advances the input sequence, then reads one character without advancing again + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::sbumpc.3 b/man/std::wstreambuf::sbumpc.3 deleted file mode 120000 index 94f27458a..000000000 --- a/man/std::wstreambuf::sbumpc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sbumpc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::setg.3 b/man/std::wstreambuf::setg.3 deleted file mode 120000 index 8f615ec72..000000000 --- a/man/std::wstreambuf::setg.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::setg.3 \ No newline at end of file diff --git a/man/std::wstreambuf::setg.3 b/man/std::wstreambuf::setg.3 new file mode 100644 index 000000000..3d6119311 --- /dev/null +++ b/man/std::wstreambuf::setg.3 @@ -0,0 +1,79 @@ +.TH std::basic_streambuf::setg 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::setg \- std::basic_streambuf::setg + +.SH Synopsis + protected: + void setg( char_type* gbeg, char_type* gcurr, char_type* gend ); + + Sets the values of the pointers defining the get area. Specifically, after the call + eback() == gbeg, gptr() == gcurr, egptr() == gend. + +.SH Parameters + + gbeg - pointer to the new beginning of the get area + gcurr - pointer to the new current character (get pointer) in the get area + gend - pointer to the new end of the get area + +.SH Return value + + \fI(none)\fP + +.SH Example + + + +// Run this code + + #include + #include + + class null_filter_buf : public std::streambuf + { + std::streambuf* src; + char ch; // single-byte buffer + protected: + int underflow() + { + traits_type::int_type i; + while ((i = src->sbumpc()) == '\\0') + ; // skip zeroes + if (!traits_type::eq_int_type(i, traits_type::eof())) + { + ch = traits_type::to_char_type(i); + setg(&ch, &ch, &ch+1); // make one read position available + } + return i; + } + public: + null_filter_buf(std::streambuf* buf) : src(buf) + { + setg(&ch, &ch + 1, &ch + 1); // buffer is initially full + } + }; + + void filtered_read(std::istream& in) + { + std::streambuf* orig = in.rdbuf(); + null_filter_buf buf(orig); + in.rdbuf(&buf); + for (char c; in.get(c);) + std::cout << c; + in.rdbuf(orig); + } + + int main() + { + char a[] = "This i\\0s \\0an e\\0\\0\\0xample"; + std::istringstream in(std::string(std::begin(a), std::end(a))); + filtered_read(in); + } + +.SH Output: + + This is an example + +.SH See also + + setp repositions the beginning, next, and end pointers of the output sequence + \fI(protected member function)\fP diff --git a/man/std::wstreambuf::setp.3 b/man/std::wstreambuf::setp.3 deleted file mode 120000 index 125480274..000000000 --- a/man/std::wstreambuf::setp.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::setp.3 \ No newline at end of file diff --git a/man/std::wstreambuf::setp.3 b/man/std::wstreambuf::setp.3 new file mode 100644 index 000000000..e0abc3f69 --- /dev/null +++ b/man/std::wstreambuf::setp.3 @@ -0,0 +1,78 @@ +.TH std::basic_streambuf::setp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::setp \- std::basic_streambuf::setp + +.SH Synopsis + protected: + void setp( char_type* pbeg, char_type* pend ); + + Sets the values of the pointers defining the put area. Specifically, after the call + pbase() == pbeg, pptr() == pbeg, epptr() == pend. + +.SH Parameters + + pbeg - pointer to the new beginning of the put area + pend - pointer to the new end of the put area + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + // Buffer for std::ostream implemented by std::array + template + struct ArrayedStreamBuffer : std::basic_streambuf + { + using Base = std::basic_streambuf; + using char_type = typename Base::char_type; + + ArrayedStreamBuffer() + { + // put area pointers to work with 'buffer' + Base::setp(buffer.data(), buffer.data() + size); + } + + void print_buffer() + { + for (char_type i : buffer) + { + if (i == 0) + std::cout << "\\\\0"; + else + std::cout << i; + std::cout << ' '; + } + std::cout << '\\n'; + } + + private: + std::array buffer{}; // value-initialize buffer + }; + + int main() + { + ArrayedStreamBuffer<10> streambuf; + std::ostream stream(&streambuf); + + stream << "hello"; + stream << ","; + + streambuf.print_buffer(); + } + +.SH Output: + + h e l l o , \\0 \\0 \\0 \\0 + +.SH See also + + setg repositions the beginning, next, and end pointers of the input sequence + \fI(protected member function)\fP diff --git a/man/std::wstreambuf::sgetc.3 b/man/std::wstreambuf::sgetc.3 deleted file mode 120000 index c3fce3cc0..000000000 --- a/man/std::wstreambuf::sgetc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sgetc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::sgetc.3 b/man/std::wstreambuf::sgetc.3 new file mode 100644 index 000000000..d51db4251 --- /dev/null +++ b/man/std::wstreambuf::sgetc.3 @@ -0,0 +1,50 @@ +.TH std::basic_streambuf::sgetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sgetc \- std::basic_streambuf::sgetc + +.SH Synopsis + int_type sgetc(); + + Reads one character from the input sequence. + + If the input sequence read position is not available, returns underflow(). Otherwise + returns Traits::to_int_type(*gptr()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character pointed to by the get pointer. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream stream("Hello, world"); + std::cout << "sgetc() returned '" << (char)stream.rdbuf()->sgetc() << "'\\n"; + std::cout << "peek() returned '" << (char)stream.peek() << "'\\n"; + std::cout << "get() returned '" << (char)stream.get() << "'\\n"; + } + +.SH Output: + + sgetc() returned 'H' + peek() returned 'H' + get() returned 'H' + +.SH See also + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function)\fP diff --git a/man/std::wstreambuf::sgetn,std::basic_streambuf::xsgetn.3 b/man/std::wstreambuf::sgetn,std::basic_streambuf::xsgetn.3 deleted file mode 120000 index af58d04b6..000000000 --- a/man/std::wstreambuf::sgetn,std::basic_streambuf::xsgetn.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn.3 \ No newline at end of file diff --git a/man/std::wstreambuf::sgetn,std::basic_streambuf::xsgetn.3 b/man/std::wstreambuf::sgetn,std::basic_streambuf::xsgetn.3 new file mode 100644 index 000000000..4efc4c3c8 --- /dev/null +++ b/man/std::wstreambuf::sgetn,std::basic_streambuf::xsgetn.3 @@ -0,0 +1,45 @@ +.TH std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn \- std::basic_streambuf::sgetn,std::basic_streambuf::xsgetn + +.SH Synopsis + std::streamsize sgetn( char_type* s, std::streamsize count ); \fB(1)\fP + protected: \fB(2)\fP + virtual std::streamsize xsgetn( char_type* s, std::streamsize count ); + + 1) Calls xsgetn(s, count) of the most derived class. + 2) Reads count characters from the input sequence and stores them into a character + array pointed to by s. The characters are read as if by repeated calls to sbumpc(). + That is, if less than count characters are immediately available, the function calls + uflow() to provide more until Traits::eof() is returned. + Classes derived from std::basic_streambuf are permitted to provide more efficient + implementations of this function. + +.SH Parameters + + s - pointer to the beginning of a char_type array + count - maximum number of characters to read. + +.SH Return value + + The number of characters successfully read. If it is less than count the input + sequence has reached the end. + +.SH Notes + + The rule about "more efficient implementations" permits bulk I/O without + intermediate buffering: that's how std::ifstream::read simply passes the pointer to + the POSIX read() system call in some implementations of iostreams + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + sputn invokes xsputn() + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::showmanyc.3 b/man/std::wstreambuf::showmanyc.3 deleted file mode 120000 index 0f1588d58..000000000 --- a/man/std::wstreambuf::showmanyc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::showmanyc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::showmanyc.3 b/man/std::wstreambuf::showmanyc.3 new file mode 100644 index 000000000..86c6f8ff7 --- /dev/null +++ b/man/std::wstreambuf::showmanyc.3 @@ -0,0 +1,58 @@ +.TH std::basic_streambuf::showmanyc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::showmanyc \- std::basic_streambuf::showmanyc + +.SH Synopsis + protected: + virtual std::streamsize showmanyc(); + + Estimates the number of characters available for input in the associated character + sequence. underflow() is guaranteed not to return Traits::eof() or throw an + exception until at least that many characters are extracted. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters that are certainly available in the associated character + sequence, or -1 if showmanyc can determine, without blocking, that no characters are + available. If showmanyc returns -1, underflow() and uflow() will definitely return + Traits::eof or throw. + + The base class version returns 0, which has the meaning of "unsure if there are + characters available in the associated sequence". + +.SH Notes + + The name of this function stands for "stream: how many characters?", so it is + pronounced "S how many C", rather than "show many C". + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + underflow() is guaranteed not to extended the guarantee to allow + LWG 159 C++98 fail until at least + at least showmanyc() characters showmanyc() characters to be + are supplied extracted + +.SH See also + + in_avail obtains the number of characters immediately available in the get area + \fI(public member function)\fP + optionally provides the number of characters available for input from the + showmanyc file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::snextc.3 b/man/std::wstreambuf::snextc.3 deleted file mode 120000 index 4670d9216..000000000 --- a/man/std::wstreambuf::snextc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::snextc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::snextc.3 b/man/std::wstreambuf::snextc.3 new file mode 100644 index 000000000..222009afc --- /dev/null +++ b/man/std::wstreambuf::snextc.3 @@ -0,0 +1,39 @@ +.TH std::basic_streambuf::snextc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::snextc \- std::basic_streambuf::snextc + +.SH Synopsis + int_type snextc(); + + Advances the input sequence by one character and reads one character. + + The function calls sbumpc() to advance the input sequence. If that function returns + Traits::eof() meaning that input sequence has been exhausted and uflow() could not + retrieve more data, Traits::eof() is returned. Otherwise sgetc() is called in order + to read the character. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the next character. If the input sequence has been exhausted, + Traits::eof() is returned. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function)\fP + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::sputbackc.3 b/man/std::wstreambuf::sputbackc.3 deleted file mode 120000 index 8a11fd0b6..000000000 --- a/man/std::wstreambuf::sputbackc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sputbackc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::sputbackc.3 b/man/std::wstreambuf::sputbackc.3 new file mode 100644 index 000000000..f2e362010 --- /dev/null +++ b/man/std::wstreambuf::sputbackc.3 @@ -0,0 +1,73 @@ +.TH std::basic_streambuf::sputbackc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputbackc \- std::basic_streambuf::sputbackc + +.SH Synopsis + int_type sputbackc( char_type c ); + + Puts back a character back to the get area. + + If a putback position is available in the get area (gptr() > eback()), and the + character c is equal to the character one position to the left of gptr() (as + determined by Traits::eq(c, gptr()[-1]), then simply decrements the next pointer + (gptr()). + + Otherwise, calls pbackfail(Traits::to_int_type(c)) to either back up the get area or + to modify both the get area and possibly the associated character sequence. + + The I/O stream function basic_istream::putback is implemented in terms of this + function. + +.SH Parameters + + c - character to put back + +.SH Return value + + If putback position was available, returns the character that the next pointer is + now pointing at, converted to int_type with Traits::to_int_type(*gptr()). The next + single-character input from this streambuf will return this character. + + If putback position was not available, returns what pbackfail() returns, which is + Traits::eof() on failure. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream s("abcdef"); // gptr() points to 'a' in "abcdef" + std::cout << "Before putback, string holds " << s.str() << '\\n'; + char c1 = s.get(); // c1 = 'a', gptr() now points to 'b' in "abcdef" + char c2 = s.rdbuf()->sputbackc('z'); // same as s.putback('z') + // gptr() now points to 'z' in "zbcdef" + std::cout << "After putback, string holds " << s.str() << '\\n'; + char c3 = s.get(); // c3 = 'z', gptr() now points to 'b' in "zbcdef" + char c4 = s.get(); // c4 = 'b', gptr() now points to 'c' in "zbcdef" + std::cout << c1 << c2 << c3 << c4 << '\\n'; + + s.rdbuf()->sputbackc('b'); // gptr() now points to 'b' in "zbcdef" + s.rdbuf()->sputbackc('z'); // gptr() now points to 'z' in "zbcdef" + int eof = s.rdbuf()->sputbackc('x'); // nothing to unget: pbackfail() fails + if (eof == EOF) + std::cout << "No room to putback after 'z'\\n"; + } + +.SH Output: + + Before putback, string holds abcdef + After putback, string holds zbcdef + azzb + No room to putback after 'z' + +.SH See also + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wstreambuf::sputc.3 b/man/std::wstreambuf::sputc.3 deleted file mode 120000 index dd8115ff7..000000000 --- a/man/std::wstreambuf::sputc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sputc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::sputc.3 b/man/std::wstreambuf::sputc.3 new file mode 100644 index 000000000..dbfddb2b6 --- /dev/null +++ b/man/std::wstreambuf::sputc.3 @@ -0,0 +1,46 @@ +.TH std::basic_streambuf::sputc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputc \- std::basic_streambuf::sputc + +.SH Synopsis + int_type sputc( char_type ch ); + + Writes one character to the output sequence. + + If the output sequence write position is not available (the buffer is full), then + calls overflow(ch). + +.SH Parameters + + ch - character to write + +.SH Return value + + The written character, converted to int_type with Traits::to_int_type(ch) on + success. + + Traits::eof() (as returned by overflow()) on failure. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream s; + s.rdbuf()->sputc('a'); + std::cout << s.str() << '\\n'; + } + +.SH Output: + + a + +.SH See also + + sputn invokes xsputn() + \fI(public member function)\fP diff --git a/man/std::wstreambuf::sputn,std::basic_streambuf::xsputn.3 b/man/std::wstreambuf::sputn,std::basic_streambuf::xsputn.3 deleted file mode 120000 index 642a06778..000000000 --- a/man/std::wstreambuf::sputn,std::basic_streambuf::xsputn.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sputn,std::basic_streambuf::xsputn.3 \ No newline at end of file diff --git a/man/std::wstreambuf::sputn,std::basic_streambuf::xsputn.3 b/man/std::wstreambuf::sputn,std::basic_streambuf::xsputn.3 new file mode 100644 index 000000000..fe40c149b --- /dev/null +++ b/man/std::wstreambuf::sputn,std::basic_streambuf::xsputn.3 @@ -0,0 +1,72 @@ +.TH std::basic_streambuf::sputn,std::basic_streambuf::xsputn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sputn,std::basic_streambuf::xsputn \- std::basic_streambuf::sputn,std::basic_streambuf::xsputn + +.SH Synopsis + std::streamsize sputn( const char_type* s, std::streamsize count ); \fB(1)\fP + protected: \fB(2)\fP + virtual std::streamsize xsputn( const char_type* s, std::streamsize count ); + + 1) Calls xsputn(s, count) of the most derived class. + 2) Writes count characters to the output sequence from the character array whose + first element is pointed to by s. The characters are written as if by repeated calls + to sputc(). Writing stops when either count characters are written or a call to + sputc() would have returned Traits::eof(). + + If the put area becomes full (pptr() == epptr()), it is unspecified whether + overflow() is actually called or its effect is achieved by other means. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of characters successfully written. + +.SH Notes + + "achieved by other means" permits bulk I/O without intermediate buffering: that is + how std::ofstream::write() simply passes the pointer to the suitable system call in + some implementations. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream s1; + std::streamsize sz = s1.rdbuf()->sputn("This is a test", 14); + s1 << '\\n'; + std::cout << "The call to sputn() returned " << sz << '\\n' + << "The output sequence contains " << s1.str(); + + std::istringstream s2; + sz = s2.rdbuf()->sputn("This is a test", 14); + std::cout << "The call to sputn() on an input stream returned " << sz << '\\n'; + } + +.SH Output: + + The call to sputn() returned 14 + The output sequence contains This is a test + The call to sputn() on an input stream returned 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 565 C++98 xsputn() always called overflow() if it does not actually need to + pptr() == epptr() be called + +.SH See also + + sgetn invokes xsgetn() + \fI(public member function)\fP diff --git a/man/std::wstreambuf::sungetc.3 b/man/std::wstreambuf::sungetc.3 deleted file mode 120000 index 135031de4..000000000 --- a/man/std::wstreambuf::sungetc.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::sungetc.3 \ No newline at end of file diff --git a/man/std::wstreambuf::sungetc.3 b/man/std::wstreambuf::sungetc.3 new file mode 100644 index 000000000..c2e60e2b9 --- /dev/null +++ b/man/std::wstreambuf::sungetc.3 @@ -0,0 +1,64 @@ +.TH std::basic_streambuf::sungetc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::sungetc \- std::basic_streambuf::sungetc + +.SH Synopsis + int_type sungetc(); + + If a putback position is available in the get area (gptr() > eback()), then + decrements the next pointer (gptr()) and returns the character it now points to. + + If a putback position is not available, then calls pbackfail() to back up the input + sequence if possible. + + The I/O stream function basic_istream::unget is implemented in terms of this + function. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + If putback position was available, returns the character that the next pointer is + now pointing at, converted to int_type with Traits::to_int_type(*gptr()). The next + single-character input from this streambuf will return this character. + + If putback position was not available, returns what pbackfail() returns, which is + Traits::eof() on failure. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream s("abcdef"); // gptr() points to 'a' + char c1 = s.get(); // c = 'a', gptr() now points to 'b' + char c2 = s.rdbuf()->sungetc(); // same as s.unget(): gptr() points to 'a' again + char c3 = s.get(); // c3 = 'a', gptr() now points to 'b' + char c4 = s.get(); // c4 = 'b', gptr() now points to 'c' + std::cout << c1 << c2 << c3 << c4 << '\\n'; + + s.rdbuf()->sungetc(); // back to 'b' + s.rdbuf()->sungetc(); // back to 'a' + int eof = s.rdbuf()->sungetc(); // nothing to unget: pbackfail() fails + if (eof == EOF) + std::cout << "Nothing to unget after 'a'\\n"; + } + +.SH Output: + + aaab + Nothing to unget after 'a' + +.SH See also + + sputbackc puts one character back in the input sequence + \fI(public member function)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::wstreambuf::swap.3 b/man/std::wstreambuf::swap.3 deleted file mode 120000 index aaf781c01..000000000 --- a/man/std::wstreambuf::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::swap.3 \ No newline at end of file diff --git a/man/std::wstreambuf::swap.3 b/man/std::wstreambuf::swap.3 new file mode 100644 index 000000000..ff8261ca1 --- /dev/null +++ b/man/std::wstreambuf::swap.3 @@ -0,0 +1,28 @@ +.TH std::basic_streambuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::swap \- std::basic_streambuf::swap + +.SH Synopsis + void swap( basic_streambuf& other ); \fI(since C++11)\fP + + Exchanges the contents of the stream buffer with those of other. + +.SH Parameters + + other - stream buffer to exchange contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::uflow.3 b/man/std::wstreambuf::uflow.3 deleted file mode 120000 index 429f3d765..000000000 --- a/man/std::wstreambuf::uflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::uflow.3 \ No newline at end of file diff --git a/man/std::wstreambuf::uflow.3 b/man/std::wstreambuf::uflow.3 new file mode 100644 index 000000000..07f656738 --- /dev/null +++ b/man/std::wstreambuf::uflow.3 @@ -0,0 +1,52 @@ +.TH std::basic_streambuf::uflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::uflow \- std::basic_streambuf::uflow + +.SH Synopsis + protected: + virtual int_type uflow(); + + Ensures that at least one character is available in the input area by updating the + pointers to the input area (if needed). On success returns the value of that + character and advances the value of the get pointer by one character. On failure + returns traits::eof(). + + The function may update gptr, egptr and eback pointers to define the location of + newly loaded data (if any). On failure, the function ensures that either gptr() == + nullptr or gptr() == egptr. + + The base class version of the function calls underflow() and increments gptr(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character that was pointed to by the get pointer before it was + advanced by one, or traits::eof() otherwise. + + The base class version of the function returns the value returned by underflow(). + +.SH Note + + The public functions of std::streambuf call this function only if gptr() == nullptr + or gptr() >= egptr(). + + The custom streambuf classes that do not use the get area and do not set the get + area pointers in basic_streambuf are required to override this function. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::underflow.3 b/man/std::wstreambuf::underflow.3 deleted file mode 120000 index 00b12c654..000000000 --- a/man/std::wstreambuf::underflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::underflow.3 \ No newline at end of file diff --git a/man/std::wstreambuf::underflow.3 b/man/std::wstreambuf::underflow.3 new file mode 100644 index 000000000..29e00974b --- /dev/null +++ b/man/std::wstreambuf::underflow.3 @@ -0,0 +1,106 @@ +.TH std::basic_streambuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::underflow \- std::basic_streambuf::underflow + +.SH Synopsis + protected: + virtual int_type underflow(); + + Ensures that at least one character is available in the input area by updating the + pointers to the input area (if needed) and reading more data in from the input + sequence (if applicable). Returns the value of that character (converted to int_type + with Traits::to_int_type(c)) on success or Traits::eof() on failure. + + The function may update gptr, egptr and eback pointers to define the location of + newly loaded data (if any). On failure, the function ensures that either gptr() == + nullptr or gptr() == egptr. + + The base class version of the function does nothing. The derived classes may + override this function to allow updates to the get area in the case of exhaustion. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The value of the character pointed to by the get pointer after the call on success, + or Traits::eof() otherwise. + + The base class version of the function returns traits::eof(). + +.SH Note + + The public functions of std::streambuf call this function only if gptr() == nullptr + or gptr() >= egptr(). + +.SH Example + + + +// Run this code + + #include + #include + + class null_filter_buf : public std::streambuf + { + std::streambuf* src; + char ch; // single-byte buffer + protected: + int underflow() + { + traits_type::int_type i; + while ((i = src->sbumpc()) == '\\0') + ; // skip zeroes + if (!traits_type::eq_int_type(i, traits_type::eof())) + { + ch = traits_type::to_char_type(i); + setg(&ch, &ch, &ch+1); // make one read position available + } + return i; + } + public: + null_filter_buf(std::streambuf* buf) : src(buf) + { + setg(&ch, &ch + 1, &ch + 1); // buffer is initially full + } + }; + + void filtered_read(std::istream& in) + { + std::streambuf* orig = in.rdbuf(); + null_filter_buf buf(orig); + in.rdbuf(&buf); + for (char c; in.get(c);) + std::cout << c; + in.rdbuf(orig); + } + + int main() + { + char a[] = "This i\\0s \\0an e\\0\\0\\0xample"; + std::istringstream in(std::string(std::begin(a), std::end(a))); + filtered_read(in); + } + +.SH Output: + + This is an example + +.SH See also + + uflow reads characters from the associated input sequence to the get area and + \fB[virtual]\fP advances the next pointer + \fI(virtual protected member function)\fP + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function)\fP + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_stringbuf) + underflow reads a character from the input sequence without advancing the next + \fB[virtual]\fP pointer + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::wstreambuf::wstreambuf.3 b/man/std::wstreambuf::wstreambuf.3 deleted file mode 120000 index 463e017b7..000000000 --- a/man/std::wstreambuf::wstreambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::basic_streambuf.3 \ No newline at end of file diff --git a/man/std::wstreambuf::wstreambuf.3 b/man/std::wstreambuf::wstreambuf.3 new file mode 100644 index 000000000..caf4b3077 --- /dev/null +++ b/man/std::wstreambuf::wstreambuf.3 @@ -0,0 +1,49 @@ +.TH std::basic_streambuf::basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::basic_streambuf \- std::basic_streambuf::basic_streambuf + +.SH Synopsis + protected: \fB(1)\fP + basic_streambuf(); + protected: \fB(2)\fP \fI(since C++11)\fP + basic_streambuf(const basic_streambuf& rhs); + + 1) Constructs the basic_streambuf object, initializes the six pointer members + (eback(), gptr(), egptr(), pbase(), pptr(), and epptr()) to null pointer values, and + the locale member to std::locale(), a copy of the global C++ locale at the time of + construction. + 2) Constructs a copy of rhs, initializing the six pointers and the locale object + with the copies of the values held by rhs. Note that this is a shallow copy: the + pointers of the newly-constructed basic_streambuf are pointing into the same + character array as the pointers of rhs. + + Both constructors are protected, and are only called by the concrete streambuf + classes, such as std::basic_filebuf, std::basic_stringbuf, or std::strstreambuf. + +.SH Parameters + + rhs - a streambuf object to copy + +.SH Notes + + Until C++11, it was unspecified whether basic_streambuf or any of its derived + classes is CopyConstructible (LWG issue 421), and different C++ library + implementations provided different options. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + constructor constructs a basic_filebuf object + \fI(public member function of std::basic_filebuf)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) + constructor constructs a strstreambuf object + \fI(public member function of std::strstreambuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstreambuf::~basic_streambuf.3 b/man/std::wstreambuf::~basic_streambuf.3 deleted file mode 120000 index 4941deda0..000000000 --- a/man/std::wstreambuf::~basic_streambuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_streambuf::~basic_streambuf.3 \ No newline at end of file diff --git a/man/std::wstreambuf::~basic_streambuf.3 b/man/std::wstreambuf::~basic_streambuf.3 new file mode 100644 index 000000000..1e6a28839 --- /dev/null +++ b/man/std::wstreambuf::~basic_streambuf.3 @@ -0,0 +1,55 @@ +.TH std::basic_streambuf::~basic_streambuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_streambuf::~basic_streambuf \- std::basic_streambuf::~basic_streambuf + +.SH Synopsis + virtual ~basic_streambuf(); + + This destructor has no effect: the members of this basic_streambuf (the pointers and + the locale) are destructed in accordance with the usual object destruction sequence + after this destructor returns. However, since it is declared public virtual, it + allows the objects that are derived from std::basic_streambuf to be deleted through + a pointer to base class. + +.SH Parameters + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::filebuf* fbp = new std::filebuf; + fbp->open("test.txt", std::ios_base::out); + fbp->sputn("Hello\\n", 6); + + std::streambuf* sbp = fbp; + delete sbp; // the file is closed, output flushed and written + + std::ifstream f("test.txt"); + std::cout << f.rdbuf(); // proof + } + +.SH Output: + + Hello + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 54 C++98 the effect of the destructor was not specified as no effect + specified + +.SH See also + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP diff --git a/man/std::wstring.3 b/man/std::wstring.3 deleted file mode 120000 index 51b9e0d1f..000000000 --- a/man/std::wstring.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string.3 \ No newline at end of file diff --git a/man/std::wstring.3 b/man/std::wstring.3 new file mode 100644 index 000000000..ba00dc78d --- /dev/null +++ b/man/std::wstring.3 @@ -0,0 +1,397 @@ +.TH std::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string \- std::basic_string + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, \fB(1)\fP + class Allocator = std::allocator + + > class basic_string; + namespace pmr { + + template< + class CharT, + class Traits = std::char_traits \fB(2)\fP \fI(since C++17)\fP + > using basic_string = + std::basic_string>; + + } + + The class template basic_string stores and manipulates sequences of character-like + objects, which are non-array objects of TrivialType and StandardLayoutType. The + class is dependent neither on the character type nor on the nature of operations on + that type. The definitions of the operations are supplied via the Traits template + parameter - a specialization of std::char_traits or a compatible traits class. + + The elements of a basic_string are stored contiguously, that is, for a basic_string + s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()) + , and *(s.begin() + s.size()) has value CharT() (a null terminator) + \fI(since C++11)\fP; or, equivalently, a pointer to s[0] can be passed to functions that + expect a pointer to the first element of + an array + \fI(until C++11)\fP + a null-terminated array + \fI(since C++11)\fP of CharT. + + std::basic_string satisfies the requirements of AllocatorAwareContainer (except that + customized construct/destroy are not used for construction/destruction of elements), + SequenceContainer + and ContiguousContainer + \fI(since C++17)\fP. + + If any of Traits::char_type and Allocator::char_type is different from CharT, the + program is ill-formed. + + Member functions of std::basic_string are constexpr: it is possible to + create and use std::string objects in the evaluation of a constant + expression. + \fI(since C++20)\fP + However, std::string objects generally cannot be constexpr, because + any dynamically allocated storage must be released in the same + evaluation of constant expression. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string std::basic_string + std::wstring std::basic_string + std::u8string (C++20) std::basic_string + std::u16string \fI(C++11)\fP std::basic_string + std::u32string \fI(C++11)\fP std::basic_string + std::pmr::string \fI(C++17)\fP std::pmr::basic_string + std::pmr::wstring \fI(C++17)\fP std::pmr::basic_string + std::pmr::u8string (C++20) std::pmr::basic_string + std::pmr::u16string \fI(C++17)\fP std::pmr::basic_string + std::pmr::u32string \fI(C++17)\fP std::pmr::basic_string + +.SH Template parameters + + CharT - character type + Traits - traits class specifying the operations on the character type + Allocator - Allocator type used to allocate internal storage + +.SH Member types + + Member type Definition + traits_type Traits + value_type CharT + allocator_type Allocator + Allocator::size_type \fI(until C++11)\fP + size_type std::allocator_traits::size_type \fI(since C++11)\fP + + + Allocator::difference_type (until + C++11) + difference_type std::allocator_traits::difference_type (since + C++11) + + + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer \fI(until C++11)\fP + const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to value_type + LegacyRandomAccessIterator, + iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + value_type + + + LegacyRandomAccessIterator and \fI(until C++20)\fP + LegacyContiguousIterator to const value_type + LegacyRandomAccessIterator, + const_iterator contiguous_iterator, and ConstexprIterator to \fI(since C++20)\fP + const value_type + + + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + +.SH Member functions + + constructor constructs a basic_string + \fI(public member function)\fP + destroys the string, deallocating internal storage if + destructor used + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + get_allocator returns the associated allocator + \fI(public member function)\fP +.SH Element access + at accesses the specified character with bounds checking + \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP + returns a non-modifiable standard C character array + c_str version of the string + \fI(public member function)\fP + operator basic_string_view returns a non-modifiable string_view into the entire + \fI(C++17)\fP string + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP +.SH Capacity + empty checks whether the string is empty + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + returns the number of characters that can be held in + capacity currently allocated storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP +.SH Modifiers + clear clears the contents + \fI(public member function)\fP + insert inserts characters + \fI(public member function)\fP + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP + pop_back removes the last character + (DR*) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + replace replaces specified portion of a string + \fI(public member function)\fP + replace_with_range replaces specified portion of a string with a range of + (C++23) characters + \fI(public member function)\fP + copy copies characters + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP + changes the number of characters stored and possibly + resize_and_overwrite overwrites indeterminate contents via user-provided + (C++23) operation + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Search + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Operations + compare compares two strings + \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string contains the given substring or + (C++23) character + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator+ concatenates two strings or a string and a char + \fI(function template)\fP + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + std::swap(std::basic_string) specializes the std::swap algorithm + \fI(function template)\fP + erase(std::basic_string) erases all elements satisfying specific criteria + erase_if(std::basic_string) \fI(function template)\fP + (C++20) +.SH Input/output + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + getline read data from an I/O stream into a string + \fI(function template)\fP +.SH Numeric conversions + stoi + stol + stoll converts a string to a signed integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + stoul + stoull converts a string to an unsigned integer + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + stof + stod + stold converts a string to a floating point value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_literals + operator""s converts a character array literal to basic_string + \fI(C++14)\fP \fI(function)\fP + +.SH Helper classes + + std::hash hash support for strings + \fI(C++11)\fP \fI(class template specialization)\fP + + Deduction guides \fI(since C++17)\fP + +.SH Notes + + Although it is required that customized construct or destroy is used when + constructing or destroying elements of std::basic_string until C++23, all + implementations only used the default mechanism. The requirement is corrected by + P1072R10 to match existing practice. + + Feature-test macro Value Std Feature + __cpp_lib_string_udls 201304L \fI(C++14)\fP User-defined literals for + string types + __cpp_lib_starts_ends_with 201711L (C++20) starts_with, ends_with + __cpp_lib_constexpr_string 201907L (C++20) Constexpr for + std::basic_string + __cpp_lib_char8_t 201907L (C++20) std::u8string + __cpp_lib_erase_if 202002L (C++20) erase, erase_if + __cpp_lib_string_contains 202011L (C++23) contains + __cpp_lib_string_resize_and_overwrite 202110L (C++23) resize_and_overwrite + Member functions for + __cpp_lib_containers_ranges 202202L (C++23) construction, insertion, and + replacement that accept + container compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + // Creating a string from const char* + std::string str1 = "hello"; + + // Creating a string using string literal + auto str2 = "world"s; + + // Concatenating strings + std::string str3 = str1 + " " + str2; + + // Print out the result + std::cout << str3 << '\\n'; + + std::string::size_type pos = str3.find(" "); + str1 = str3.substr(pos + 1); // the part after the space + str2 = str3.substr(0, pos); // the part till the space + + std::cout << str1 << ' ' << str2 << '\\n'; + + // Accessing an element using subscript operator[] + std::cout << str1[0] << '\\n'; + str1[0] = 'W'; + std::cout << str1 << '\\n'; + } + +.SH Output: + + hello world + world hello + w + World + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + contiguity of the storage for elements of + LWG 530 C++98 basic_string required again + was accidently made not required by LWG259 + the behavior is undefined if any of the program is + LWG 2994 C++98 Traits::char_type^[1] ill-formed in this + (P1148R0) and Allocator::char_type is different from case + CharT + + 1. ↑ The Traits::char_type case is fixed in P1148R0. + +.SH See also + + basic_string_view read-only string view + \fI(C++17)\fP \fI(class template)\fP + +.SH External links + + C++ string handling + +.SH Hidden category: + * Pages with unreviewed LWG DR marker diff --git a/man/std::wstring::append.3 b/man/std::wstring::append.3 deleted file mode 120000 index b50ac7eda..000000000 --- a/man/std::wstring::append.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::append.3 \ No newline at end of file diff --git a/man/std::wstring::append.3 b/man/std::wstring::append.3 new file mode 100644 index 000000000..dfcb8cb7a --- /dev/null +++ b/man/std::wstring::append.3 @@ -0,0 +1,185 @@ +.TH std::basic_string::append 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append \- std::basic_string::append + +.SH Synopsis + basic_string& append( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& append( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& append( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& append( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos ); C++20) + basic_string& append( const CharT* s, \fB(4)\fP (constexpr since + size_type count ); C++20) + basic_string& append( const CharT* s ); \fB(5)\fP (constexpr since + C++20) + template< class InputIt > (constexpr since + basic_string& append( InputIt first, InputIt \fB(6)\fP C++20) + last ); \fB(3)\fP + basic_string& append( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(7)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& append( const StringViewLike& t \fB(8)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& append( const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos ); + + Appends additional characters to the string. + + 1) Appends count copies of character ch. + 2) Appends string str. + 3) Appends a substring [pos, pos + count) of str. + * If the requested substring lasts past the end of the string, or if count == + npos, the appended substring is [pos, size()). + * If pos > str.size(), std::out_of_range is thrown. + 4) Appends characters in the range [s, s + count). This range can contain null + characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 5) Appends the null-terminated character string pointed to by s, as if by append(s, + Traits::length(s)). + 6) Appends characters in the range [first, last). + + This overload has the same effect as overload \fB(1)\fP if InputIt is an \fI(until C++11)\fP + integral type. + This overload only participates in overload resolution if InputIt \fI(since C++11)\fP + qualifies as a LegacyInputIterator. + + 7) Appends characters from the initializer list ilist. + 8) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends all characters from sv as if by append(sv.data(), + sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends the characters from the subview [pos, pos + count) of + sv. + * If the requested subview extends past the end of sv, or if count == npos, the + appended subview is [pos, sv.size()). + * If pos >= sv.size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - number of characters to append + pos - the index of the first character to append + ch - character value to append + first, last - range of characters to append + str - string to append + s - pointer to the character string to append + ilist - initializer list with the characters to append + t - object convertible to std::basic_string_view with the characters to + append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::basic_string str = "string"; + const char* cptr = "C-string"; + const char carr[] = "Two and one"; + + std::string output; + + // 1) Append a char 3 times. + // Notice, this is the only overload accepting chars. + output.append(3, '*'); + std::cout << "1) " << output << '\\n'; + + // 2) Append a whole string + output.append(str); + std::cout << "2) " << output << '\\n'; + + // 3) Append part of a string (last 3 letters, in this case) + output.append(str, 3, 3); + std::cout << "3) " << output << '\\n'; + + // 4) Append part of a C-string + // Notice, because `append` returns *this, we can chain calls together + output.append(1, ' ').append(carr, 4); + std::cout << "4) " << output << '\\n'; + + // 5) Append a whole C-string + output.append(cptr); + std::cout << "5) " << output << '\\n'; + + // 6) Append range + output.append(&carr[3], std::end(carr)); + std::cout << "6) " << output << '\\n'; + + // 7) Append initializer list + output.append({' ', 'l', 'i', 's', 't'}); + std::cout << "7) " << output << '\\n'; + } + +.SH Output: + + 1) *** + 2) ***string + 3) ***stringing + 4) ***stringing Two + 5) ***stringing Two C-string + 6) ***stringing Two C-string and one + 7) ***stringing Two C-string and one list + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(8)\fP causes ambiguity in avoided by making it a + some cases template + +.SH See also + + append_range appends a range of characters to the end + (C++23) \fI(public member function)\fP + operator+= appends characters to the end + \fI(public member function)\fP + strcat concatenates two strings + \fI(function)\fP + strncat concatenates a certain amount of characters of two strings + \fI(function)\fP + wcscat appends a copy of one wide string to another + \fI(function)\fP + appends a certain amount of wide characters from one wide string to + wcsncat another + \fI(function)\fP diff --git a/man/std::wstring::append_range.3 b/man/std::wstring::append_range.3 new file mode 100644 index 000000000..ede115277 --- /dev/null +++ b/man/std::wstring::append_range.3 @@ -0,0 +1,65 @@ +.TH std::basic_string::append_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::append_range \- std::basic_string::append_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& append_range( R&& rg ); + + Appends all characters from the range rg. + + Equivalent to + + return append(std::basic_string( std::from_range, std::forward(rg), get_allocator())); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string head{"long long"}; + const auto tail = {' ', 'i', 'n', 't'}; + + #ifdef __cpp_lib_containers_ranges + head.append_range(tail); + #else + head.append(tail.begin(), tail.end()); + #endif + + assert(head == "long long int"); + } + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::wstring::assign.3 b/man/std::wstring::assign.3 deleted file mode 120000 index b4f3ab165..000000000 --- a/man/std::wstring::assign.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::assign.3 \ No newline at end of file diff --git a/man/std::wstring::assign.3 b/man/std::wstring::assign.3 new file mode 100644 index 000000000..afbe7a690 --- /dev/null +++ b/man/std::wstring::assign.3 @@ -0,0 +1,210 @@ +.TH std::basic_string::assign 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign \- std::basic_string::assign + +.SH Synopsis + basic_string& assign( size_type count, CharT \fB(1)\fP (constexpr since + ch ); C++20) + basic_string& assign( const basic_string& str \fB(2)\fP (constexpr since + ); C++20) + basic_string& assign( const basic_string& str, + size_type pos, size_type \fI(until C++14)\fP + count ); + basic_string& assign( const basic_string& str, \fI(since C++14)\fP + size_type pos, size_type (constexpr since + count = npos); C++20) + basic_string& assign( basic_string&& str ) \fI(since C++11)\fP + noexcept(/* see below */); \fB(4)\fP (constexpr since + C++20) + basic_string& assign( const CharT* s, \fB(5)\fP (constexpr since + size_type count ); C++20) + basic_string& assign( const CharT* s ); \fB(6)\fP (constexpr since + C++20) + template< class InputIt > \fB(3)\fP (constexpr since + basic_string& assign( InputIt first, InputIt \fB(7)\fP C++20) + last ); + basic_string& assign( \fI(since C++11)\fP + std::initializer_list ilist ); \fB(8)\fP (constexpr since + C++20) + template< class StringViewLike > \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t \fB(9)\fP (constexpr since + ); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + basic_string& assign( const StringViewLike& t, \fB(10)\fP (constexpr since + C++20) + size_type pos, size_type + count = npos); + + Replaces the contents of the string. + + 1) Replaces the contents with count copies of character ch. + 2) Replaces the contents with a copy of str. Equivalent to *this = str;. + In particular, allocator propagation may take place. + \fI(since C++11)\fP + 3) Replaces the contents with a substring [pos, pos + count) of str. If the + requested substring lasts past the end of the string, or if count == npos, the + resulting substring is [pos, str.size()). If pos > str.size(), std::out_of_range is + thrown. + 4) Replaces the contents with those of str using move semantics. Equivalent to *this + = std::move(str). In particular, allocator propagation may take place. + 5) Replaces the contents with copies of the characters in the range [s, s + count). + This range can contain null characters. + 6) Replaces the contents with those of null-terminated character string pointed to + by s. The length of the string is determined by the first null character using + Traits::length(s). + 7) Replaces the contents with copies of the characters in the range [first, last). + This overload does not participate in overload resolution if InputIt does not + satisfy LegacyInputIterator. + \fI(since C++11)\fP + 8) Replaces the contents with those of the initializer list ilist. + 9) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of sv, as if by + assign(sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with the characters from the subview + [pos, pos + count) of sv. If the requested subview lasts past the end of sv, or if + count == npos, the resulting subview is [pos, sv.size()). If pos > sv.size(), + std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + count - size of the resulting string + pos - index of the first character to take + ch - value to initialize characters of the string with + first, last - range to copy the characters from + str - string to be used as source to initialize the characters with + s - pointer to a character string to use as source to initialize the + string with + ilist - std::initializer_list to initialize the characters of the string with + t - object (convertible to std::basic_string_view) to initialize the + characters of the string with +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in count. + 2) Linear in size of str. + 3) Linear in count. + 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 5) Linear in count. + 6) Linear in size of s. + 7) Linear in distance between first and last. + 8) Linear in size of ilist. + 9) Linear in size of t. + +.SH Exceptions + + 4) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + // assign(size_type count, CharT ch) + s.assign(4, '='); + std::cout << s << '\\n'; // "====" + + std::string const c("Exemplary"); + // assign(const basic_string& str) + s.assign(c); + std::cout << c << " == " << s << '\\n'; // "Exemplary == Exemplary" + + // assign(const basic_string& str, size_type pos, size_type count) + s.assign(c, 0, c.length() - 1); + std::cout << s << '\\n'; // "Exemplar"; + + // assign(basic_string&& str) + s.assign(std::string("C++ by ") + "example"); + std::cout << s << '\\n'; // "C++ by example" + + // assign(const CharT* s, size_type count) + s.assign("C-style string", 7); + std::cout << s << '\\n'; // "C-style" + + // assign(const CharT* s) + s.assign("C-style\\0string"); + std::cout << s << '\\n'; // "C-style" + + char mutable_c_str[] = "C-style string"; + // assign(InputIt first, InputIt last) + s.assign(std::begin(mutable_c_str), std::end(mutable_c_str) - 1); + std::cout << s << '\\n'; // "C-style string" + + // assign(std::initializer_list ilist) + s.assign({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << s << '\\n'; // "C-style" + } + +.SH Output: + + ==== + Exemplary == Exemplary + Exemplar + C++ by example +.SH C-style +.SH C-style + C-style string +.SH C-style + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + non-normative note stated that swap + LWG 2063 C++11 is corrected to require move + a valid implementation of assignment + move-assign + LWG 2579 C++11 assign(const basic_string&) made to propagate allocators + did not propagate allocators if needed + LWG 2946 C++17 overload \fB(9)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + assign_range assign a range of characters to a string + (C++23) \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::assign_range.3 b/man/std::wstring::assign_range.3 new file mode 100644 index 000000000..7bfd17959 --- /dev/null +++ b/man/std::wstring::assign_range.3 @@ -0,0 +1,74 @@ +.TH std::basic_string::assign_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::assign_range \- std::basic_string::assign_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr std::basic_string& assign_range( R&& rg ); + + Replaces the contents of the string with the values in the range rg. + + Equivalent to + + return assign( + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const auto source = {'s', 'o', 'u', 'r', 'c', 'e'}; + std::string destination{"destination"}; + + #ifdef __cpp_lib_containers_ranges + destination.assign_range(source); + #else + destination.assign(source.begin(), source.end()); + #endif + + assert(destination == "source"); + } + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + constructor constructs a basic_string + \fI(public member function)\fP diff --git a/man/std::wstring::at.3 b/man/std::wstring::at.3 deleted file mode 120000 index 1f402dba2..000000000 --- a/man/std::wstring::at.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::at.3 \ No newline at end of file diff --git a/man/std::wstring::at.3 b/man/std::wstring::at.3 new file mode 100644 index 000000000..36e5a7e1d --- /dev/null +++ b/man/std::wstring::at.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::at \- std::basic_string::at + +.SH Synopsis + CharT& at( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& at( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos. Bounds checking is + performed, exception of type std::out_of_range will be thrown on invalid access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("message"); // for capacity + + s = "abc"; + s.at(2) = 'x'; // OK + std::cout << s << '\\n'; + + std::cout << "string size = " << s.size() << '\\n'; + std::cout << "string capacity = " << s.capacity() << '\\n'; + + try + { + // This will throw since the requested offset is greater than the current size. + s.at(3) = 'x'; + } + catch (std::out_of_range const& exc) + { + std::cout << exc.what() << '\\n'; + } + } + +.SH Possible output: + + abx + string size = 3 + string capacity = 7 + basic_string::at + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::back.3 b/man/std::wstring::back.3 deleted file mode 120000 index 33e85e2c2..000000000 --- a/man/std::wstring::back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::back.3 \ No newline at end of file diff --git a/man/std::wstring::back.3 b/man/std::wstring::back.3 new file mode 100644 index 000000000..5dd0d47ca --- /dev/null +++ b/man/std::wstring::back.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::back \- std::basic_string::back + +.SH Synopsis + CharT& back(); \fB(1)\fP (constexpr since C++20) + const CharT& back() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the last character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& back1 = s.back(); + back1 = 's'; + std::cout << s << '\\n'; // "Exemplars" + + std::string const c("Exemplary"); + char const& back2 = c.back(); + std::cout << back2 << '\\n'; // 'y' + } + +.SH Output: + + Exemplars + y + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function back() + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::basic_string.3 b/man/std::wstring::basic_string.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::wstring::basic_string.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::wstring::basic_string.3 b/man/std::wstring::basic_string.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::wstring::basic_string.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::wstring::begin,.3 b/man/std::wstring::begin,.3 new file mode 100644 index 000000000..a9b49707a --- /dev/null +++ b/man/std::wstring::begin,.3 @@ -0,0 +1,69 @@ +.TH std::basic_string::begin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::begin, \- std::basic_string::begin, + +.SH Synopsis + + iterator begin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the first character of the string. + + begin() returns a mutable or constant iterator, depending on the constness of *this. + + cbegin() always returns a constant iterator. It is equivalent to const_cast(*this).begin(). + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplar"); + *s.begin() = 'e'; + std::cout << s << '\\n'; + + auto i = s.cbegin(); + std::cout << *i << '\\n'; + // *i = 'E'; // error: i is a constant iterator + } + +.SH Output: + + exemplar + e + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::begin,std::basic_string::cbegin.3 b/man/std::wstring::begin,std::basic_string::cbegin.3 deleted file mode 120000 index aaa6194e9..000000000 --- a/man/std::wstring::begin,std::basic_string::cbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::begin,std::basic_string::cbegin.3 \ No newline at end of file diff --git a/man/std::wstring::c_str.3 b/man/std::wstring::c_str.3 deleted file mode 120000 index 3a01af623..000000000 --- a/man/std::wstring::c_str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::c_str.3 \ No newline at end of file diff --git a/man/std::wstring::c_str.3 b/man/std::wstring::c_str.3 new file mode 100644 index 000000000..e1a3268f3 --- /dev/null +++ b/man/std::wstring::c_str.3 @@ -0,0 +1,88 @@ +.TH std::basic_string::c_str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::c_str \- std::basic_string::c_str + +.SH Synopsis + const CharT* c_str() const; (noexcept since C++11) + (constexpr since C++20) + + Returns a pointer to a null-terminated character array with data equivalent to those + stored in the string. + + The pointer is such that the range [c_str(), c_str() + size()] is valid and the + values in it correspond to the values stored in the string with an additional null + character after the last position. + + The pointer obtained from c_str() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string + , excluding operator[], at(), front(), back(), begin(), rbegin(), end() and + rend() + \fI(since C++11)\fP. + + Writing to the character array accessed through c_str() is undefined behavior. + + c_str() and data() perform the same function. \fI(since C++11)\fP + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying character storage. + + c_str()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + c_str() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Notes + + The pointer obtained from c_str() may only be treated as a pointer to a + null-terminated character string if the string object does not contain other null + characters. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + extern "C" void c_func(const char* c_str) + { + printf("c_func called with '%s'\\n", c_str); + } + + int main() + { + std::string const s("Emplary"); + const char* p = s.c_str(); + assert(s.size() == std::strlen(p)); + assert(std::equal(s.begin(), s.end(), p)); + assert(std::equal(p, p + s.size(), s.begin())); + assert('\\0' == *(p + s.size())); + + c_func(s.c_str()); + } + +.SH Output: + + c_func called with 'Emplary' + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function)\fP diff --git a/man/std::wstring::capacity.3 b/man/std::wstring::capacity.3 deleted file mode 120000 index 6045777da..000000000 --- a/man/std::wstring::capacity.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::capacity.3 \ No newline at end of file diff --git a/man/std::wstring::capacity.3 b/man/std::wstring::capacity.3 new file mode 100644 index 000000000..32f50b319 --- /dev/null +++ b/man/std::wstring::capacity.3 @@ -0,0 +1,93 @@ +.TH std::basic_string::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::capacity \- std::basic_string::capacity + +.SH Synopsis + size_type capacity() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the number of characters that the string has currently allocated space for. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Capacity of the currently allocated storage, i.e. the storage available for storing + elements. + +.SH Complexity + + Constant. + +.SH Notes + + Memory locations obtained from the allocator but not available for storing any + element are not counted in the allocated storage. Note that the null terminator is + not an element of the std::basic_string. + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_capacity(std::string const& s) + { + std::cout << std::quoted(s) << " has capacity " << s.capacity() << ".\\n"; + } + + int main() + { + std::string s{"Exemplar"}; + show_capacity(s); + + s += " is an example string."; + show_capacity(s); + + s.clear(); + show_capacity(s); + + std::cout << "\\nDemonstrate the capacity's growth policy." + "\\nSize: Capacity: Ratio:\\n" << std::left; + + std::string g; + auto old_cap{g.capacity()}; + + for (int mark{}; mark != 5; ++mark) + { + while (old_cap == g.capacity()) + g.push_back('.'); + + std::cout << std::setw( 7) << g.size() + << std::setw(11) << g.capacity() + << std::setw(10) << g.capacity() / static_cast(old_cap) << '\\n'; + + old_cap = g.capacity(); + } + } + +.SH Possible output: + + "Exemplar" has capacity 15. + "Exemplar is an example string." has capacity 30. + "" has capacity 30. + + Demonstrate the capacity's growth policy. + Size: Capacity: Ratio: + 16 30 2 + 31 60 2 + 61 120 2 + 121 240 2 + 241 480 2 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP diff --git a/man/std::wstring::clear.3 b/man/std::wstring::clear.3 deleted file mode 120000 index df77a9b91..000000000 --- a/man/std::wstring::clear.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::clear.3 \ No newline at end of file diff --git a/man/std::wstring::clear.3 b/man/std::wstring::clear.3 new file mode 100644 index 000000000..a1e021b20 --- /dev/null +++ b/man/std::wstring::clear.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::clear \- std::basic_string::clear + +.SH Synopsis + void clear(); (noexcept since C++11) + (constexpr since C++20) + + Removes all characters from the string as if by executing erase(begin(), end()). + + All pointers, references, and iterators are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + Unlike for std::vector::clear, the C++ standard does not explicitly require that + capacity is unchanged by this function, but existing implementations do not change + capacity. This means that they do not release the allocated memory (see also + shrink_to_fit). + +.SH Complexity + + Linear in the size of the string, although existing implementations operate in + constant time. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s{"Exemplar"}; + std::string::size_type const capacity = s.capacity(); + + s.clear(); + assert(s.capacity() == capacity); // <- not guaranteed + assert(s.empty()); + assert(s.size() == 0); + } + +.SH See also + + erase removes characters + \fI(public member function)\fP diff --git a/man/std::wstring::compare.3 b/man/std::wstring::compare.3 deleted file mode 120000 index abd41e671..000000000 --- a/man/std::wstring::compare.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::compare.3 \ No newline at end of file diff --git a/man/std::wstring::compare.3 b/man/std::wstring::compare.3 new file mode 100644 index 000000000..890b367f1 --- /dev/null +++ b/man/std::wstring::compare.3 @@ -0,0 +1,285 @@ +.TH std::basic_string::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::compare \- std::basic_string::compare + +.SH Synopsis + (noexcept since + int compare( const basic_string& str ) const; \fB(1)\fP C++11) + (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(2)\fP (constexpr since + const basic_string& str ) const; C++20) + int compare( size_type pos1, size_type count1, + + const basic_string& str, \fI(until C++14)\fP + + size_type pos2, size_type count2 + ) const; + int compare( size_type pos1, size_type count1, + \fI(since C++14)\fP + const basic_string& str, (constexpr since + C++20) + size_type pos2, size_type count2 + = npos ) const; + int compare( const CharT* s ) const; \fB(4)\fP (constexpr since + C++20) + int compare( size_type pos1, size_type count1, \fB(5)\fP (constexpr since + const CharT* s ) const; C++20) + int compare( size_type pos1, size_type count1, \fB(3)\fP (constexpr since + const CharT* s, size_type count2 \fB(6)\fP C++20) + ) const; + template< class StringViewLike > \fI(since C++17)\fP + int compare( const StringViewLike& t ) const \fB(7)\fP (constexpr since + noexcept(/* see below */); C++20) + template< class StringViewLike > + \fI(since C++17)\fP + int compare( size_type pos1, size_type count1, \fB(8)\fP (constexpr since + C++20) + const StringViewLike& t ) const; + template< class StringViewLike > + + int compare( size_type pos1, size_type count1, \fI(since C++17)\fP + const StringViewLike& t, \fB(9)\fP (constexpr since + C++20) + size_type pos2, size_type count2 + = npos) const; + + Compares two character sequences. + + 1) Compares this string to str. + 2) Compares a [pos1, pos1 + count1) substring of this string to str. + * If count1 > size() - pos1, the substring is [pos1, size()). + 3) Compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of str. + * If count1 > size() - pos1, the first substring is [pos1, size()). + * If count2 > str.size() - pos2, the second substring is [pos2, str.size()). + 4) Compares this string to the null-terminated character sequence beginning at the + character pointed to by s with length Traits::length(s). + 5) Compares a [pos1, pos1 + count1) substring of this string to the null-terminated + character sequence beginning at the character pointed to by s with length + Traits::length(s). + * If count1 > size() - pos1, the substring is [pos1, size()). + 6) Compares a [pos1, pos1 + count1) substring of this string to the characters in + the range [s, s + count2). The characters in [s, s + count2) may include null + characters. + * If count1 > size() - pos1, the substring is [pos1, size()). + 7-9) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then + 7) compares this string to sv; + 8) compares a [pos1, pos1 + count1) substring of this string to sv, as if by + std::basic_string_view(*this).substr(pos1, count1).compare(sv); + 9) compares a [pos1, pos1 + count1) substring of this string to a substring + [pos2, pos2 + count2) of sv, as if by std::basic_string_view(*this) + .substr(pos1, count1).compare(sv.substr(pos2, count2)). + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false.. + + A character sequence consisting of count1 characters starting at data1 is compared + to a character sequence consisting of count2 characters starting at data2 as + follows: + + * First, calculate the number of characters to compare, as if by size_type rlen = + std::min(count1, count2). + * Then compare the sequences by calling Traits::compare(data1, data2, rlen). For + standard strings this function performs character-by-character lexicographical + comparison. If the result is zero (the character sequences are equal so far), + then their sizes are compared as follows: + + Condition Result Return value + Traits::compare(data1, data2, rlen) < 0 data1 is less than <0 + data2 + size1 < size2 data1 is less than <0 + data2 + Traits::compare(data1, data2, rlen) == size1 == data1 is equal to 0 + 0 size2 data2 + size1 > size2 data1 is greater >0 + than data2 + Traits::compare(data1, data2, rlen) > 0 data1 is greater >0 + than data2 + +.SH Parameters + + str - other string to compare to + s - pointer to the character string to compare to + count1 - number of characters of this string to compare + pos1 - position of the first character in this string to compare + count2 - number of characters of the given string to compare + pos2 - position of the first character of the given string to compare + t - object (convertible to std::basic_string_view) to compare to + +.SH Return value + + * Negative value if *this appears before the character sequence specified by the + arguments, in lexicographical order. + * Zero if both character sequences compare equivalent. + * Positive value if *this appears after the character sequence specified by the + arguments, in lexicographical order. + +.SH Exceptions + + The overloads taking parameters named pos1 or pos2 throws std::out_of_range if the + argument is out of range. + + 7) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + 8,9) Throws anything thrown by the conversion to std::basic_string_view. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Possible implementation + + overload \fB(1)\fP + template + int std::basic_string::compare + (const std::basic_string& s) const noexcept + { + size_type lhs_sz = size(); + size_type rhs_sz = s.size(); + int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz)); + if (result != 0) + return result; + if (lhs_sz < rhs_sz) + return -1; + if (lhs_sz > rhs_sz) + return 1; + return 0; + } + +.SH Notes + + For the situations when three-way comparison is not required, std::basic_string + provides the usual relational operators (<, <=, ==, >, etc). + + By default (with the default std::char_traits), this function is not + locale-sensitive. See std::collate::compare for locale-aware three-way string + comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + void print_compare_result(std::string_view str1, + std::string_view str2, + int compare_result) + { + if (compare_result < 0) + std::cout << std::quoted(str1) << " comes before " + << std::quoted(str2) << ".\\n"; + else if (compare_result > 0) + std::cout << std::quoted(str2) << " comes before " + << std::quoted(str1) << ".\\n"; + else + std::cout << std::quoted(str1) << " and " + << std::quoted(str2) << " are the same.\\n"; + } + + int main() + { + std::string batman{"Batman"}; + std::string superman{"Superman"}; + int compare_result{0}; + + // 1) Compare with other string + compare_result = batman.compare(superman); + std::cout << "1) "; + print_compare_result("Batman", "Superman", compare_result); + + // 2) Compare substring with other string + compare_result = batman.compare(3, 3, superman); + std::cout << "2) "; + print_compare_result("man", "Superman", compare_result); + + // 3) Compare substring with other substring + compare_result = batman.compare(3, 3, superman, 5, 3); + std::cout << "3) "; + print_compare_result("man", "man", compare_result); + + // Compare substring with other substring + // defaulting to end of other string + assert(compare_result == batman.compare(3, 3, superman, 5)); + + // 4) Compare with char pointer + compare_result = batman.compare("Superman"); + std::cout << "4) "; + print_compare_result("Batman", "Superman", compare_result); + + // 5) Compare substring with char pointer + compare_result = batman.compare(3, 3, "Superman"); + std::cout << "5) "; + print_compare_result("man", "Superman", compare_result); + + // 6) Compare substring with char pointer substring + compare_result = batman.compare(0, 3, "Superman", 5); + std::cout << "6) "; + print_compare_result("Bat", "Super", compare_result); + } + +.SH Output: + + 1) "Batman" comes before "Superman". + 2) "Superman" comes before "man". + 3) "man" and "man" are the same. + 4) "Batman" comes before "Superman". + 5) "Superman" comes before "man". + 6) "Bat" comes before "Super". + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the parameter count2 of overload default argument removed, + LWG 5 C++98 \fB(6)\fP split to overloads \fB(5)\fP and + had a default argument npos \fB(6)\fP + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(7)\fP caused ambiguity in avoided by making it a + some cases template + noexcept for overload \fB(7)\fP was + P1148R0 C++17 accidentally restored + dropped by the resolution of + LWG2946 + +.SH See also + + operator== + operator!= + operator< + operator> + operator<= + operator>= lexicographically compares two strings + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) + substr returns a substring + \fI(public member function)\fP + collate defines lexicographical comparison and hashing of strings + \fI(class template)\fP + strcoll compares two strings in accordance to the current locale + \fI(function)\fP + returns true if one range is lexicographically less than + lexicographical_compare another + \fI(function template)\fP + compares two views + compare \fI\fI(public member\fP function of\fP + std::basic_string_view) + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::contains.3 b/man/std::wstring::contains.3 new file mode 100644 index 000000000..a6b202311 --- /dev/null +++ b/man/std::wstring::contains.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::contains \- std::basic_string::contains + +.SH Synopsis + constexpr bool + contains( std::basic_string_view sv ) const \fB(1)\fP (since C++23) + noexcept; + constexpr bool \fB(2)\fP (since C++23) + contains( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP (since C++23) + contains( const CharT* s ) const; + + Checks if the string contains the given substring. The substring may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + template + void test_substring(const std::string& str, SubstrType subs) + { + constexpr char delim = std::is_scalar_v ? '\\'' : '\\"'; + std::cout << std::quoted(str) + << (str.contains(subs) ? " contains " + : " does not contain ") + << std::quoted(std::string{subs}, delim) << '\\n'; + } + + int main() + { + using namespace std::literals; + + auto helloWorld = "hello world"s; + + test_substring(helloWorld, "hello"sv); + test_substring(helloWorld, "goodbye"sv); + test_substring(helloWorld, 'w'); + test_substring(helloWorld, 'x'); + } + +.SH Output: + + "hello world" contains "hello" + "hello world" does not contain "goodbye" + "hello world" contains 'w' + "hello world" does not contain 'x' + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::copy.3 b/man/std::wstring::copy.3 deleted file mode 120000 index 18592fc3f..000000000 --- a/man/std::wstring::copy.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::copy.3 \ No newline at end of file diff --git a/man/std::wstring::copy.3 b/man/std::wstring::copy.3 new file mode 100644 index 000000000..5258bb301 --- /dev/null +++ b/man/std::wstring::copy.3 @@ -0,0 +1,81 @@ +.TH std::basic_string::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::copy \- std::basic_string::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos (constexpr since C++20) + = 0 ) const; + + Copies a substring [pos, pos + count) to character string pointed to by dest. If the + requested substring lasts past the end of the string, or if count == npos, the + copied substring is [pos, size()). + + The resulting character string is not null-terminated. + +.SH Parameters + + dest - pointer to the destination character string + count - length of the substring + pos - position of the first character to include + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string foo("WINE"); + + // brace-initialization initializes all characters to 0, + // providing a null-terminator + char bar[4]{}; + + // do not copy the last char, to guarantee null-termination + foo.copy(bar, sizeof bar - 1); + + std::cout << bar << '\\n'; // requires bar to be null-terminated + } + +.SH Output: + + WIN + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string_view)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::wstring::data.3 b/man/std::wstring::data.3 deleted file mode 120000 index e88dffdcc..000000000 --- a/man/std::wstring::data.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::data.3 \ No newline at end of file diff --git a/man/std::wstring::data.3 b/man/std::wstring::data.3 new file mode 100644 index 000000000..e081790d6 --- /dev/null +++ b/man/std::wstring::data.3 @@ -0,0 +1,83 @@ +.TH std::basic_string::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::data \- std::basic_string::data + +.SH Synopsis + const CharT* data() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + CharT* data() noexcept; \fB(2)\fP \fI(since C++17)\fP + (constexpr since C++20) + + Returns a pointer to the underlying array serving as character storage. The pointer + is such that the range + + [data(), data() + size()) \fI(until C++11)\fP + [data(), data() + size()] \fI(since C++11)\fP + + is valid and the values in it correspond to the values stored in the string. + + The returned array is not required to be null-terminated. + \fI(until C++11)\fP + If empty() returns true, the pointer is a non-null pointer that should + not be dereferenced. + The returned array is null-terminated, that is, data() and c_str() + perform the same function. + \fI(since C++11)\fP + If empty() returns true, the pointer points to a single null + character. + + The pointer obtained from data() may be invalidated by: + + * Passing a non-const reference to the string to any standard library function, or + * Calling non-const member functions on the string, excluding operator[](), at(), + front(), back(), begin(), end(), rbegin(), rend(). + 1) Modifying the character array accessed through the const overload of data has + undefined behavior. + 2) Modifying the past-the-end null terminator stored at data() + size() to any value + other than CharT() has undefined behavior. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character storage. + + data()[i] == operator[](i) for every i in [0, size()). \fI(until C++11)\fP + data() + i == std::addressof(operator[](i)) for every i in \fI(since C++11)\fP + [0, size()]. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string const s("Emplary"); + assert(s.size() == std::strlen(s.data())); + assert(std::equal(s.begin(), s.end(), s.data())); + assert(std::equal(s.data(), s.data() + s.size(), s.begin())); + assert('\\0' == *(s.data() + s.size())); + } + +.SH See also + + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + c_str returns a non-modifiable standard C character array version of the string + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::empty.3 b/man/std::wstring::empty.3 deleted file mode 120000 index 57ffefac4..000000000 --- a/man/std::wstring::empty.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::empty.3 \ No newline at end of file diff --git a/man/std::wstring::empty.3 b/man/std::wstring::empty.3 new file mode 100644 index 000000000..515c30654 --- /dev/null +++ b/man/std::wstring::empty.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::empty \- std::basic_string::empty + +.SH Synopsis + bool empty() const; (noexcept since C++11) + (constexpr since C++20) + + Checks if the string has no characters, i.e. whether begin() == end(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the string is empty, false otherwise + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::boolalpha(std::cout); + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = "Exemplar"; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + + s = ""; + std::cout << "s.empty():" << s.empty() << "\\t s:'" << s << "'\\n"; + } + +.SH Output: + + s.empty():true s:'' + s.empty():false s:'Exemplar' + s.empty():true s:'' + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + empty checks whether the view is empty + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::end,.3 b/man/std::wstring::end,.3 new file mode 100644 index 000000000..a29f4fa07 --- /dev/null +++ b/man/std::wstring::end,.3 @@ -0,0 +1,66 @@ +.TH std::basic_string::end, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::end, \- std::basic_string::end, + +.SH Synopsis + + iterator end(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns an iterator to the character following the last character of the string. + This character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemparl"); + std::next_permutation(s.begin(), s.end()); + + std::string c; + std::copy(s.cbegin(), s.cend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "Exemplar" + } + +.SH Output: + + Exemplar + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::end,std::basic_string::cend.3 b/man/std::wstring::end,std::basic_string::cend.3 deleted file mode 120000 index 8e6f5e8ed..000000000 --- a/man/std::wstring::end,std::basic_string::cend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::end,std::basic_string::cend.3 \ No newline at end of file diff --git a/man/std::wstring::ends_with.3 b/man/std::wstring::ends_with.3 new file mode 100644 index 000000000..daa271fc6 --- /dev/null +++ b/man/std::wstring::ends_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::ends_with \- std::basic_string::ends_with + +.SH Synopsis + constexpr bool + ends_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + ends_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + ends_with( const CharT* s ) const; + + Checks if the string ends with the given suffix. The suffix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).ends_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.ends_with("C++20!"sv) // (1) + && !str.ends_with("c++20!"sv) // (1) + && str.ends_with("C++20!"s) // (1) implicit conversion string to string_view + && !str.ends_with("c++20!"s) // (1) implicit conversion string to string_view + && str.ends_with('!') // (2) + && !str.ends_with('?') // (2) + && str.ends_with("C++20!") // (3) + && !str.ends_with("c++20!") // (3) + ); + } + +.SH See also + + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::wstring::erase.3 b/man/std::wstring::erase.3 deleted file mode 120000 index 533c91687..000000000 --- a/man/std::wstring::erase.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::erase.3 \ No newline at end of file diff --git a/man/std::wstring::erase.3 b/man/std::wstring::erase.3 new file mode 100644 index 000000000..caa61fc84 --- /dev/null +++ b/man/std::wstring::erase.3 @@ -0,0 +1,109 @@ +.TH std::basic_string::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::erase \- std::basic_string::erase + +.SH Synopsis + basic_string& erase( (constexpr since + size_type index = 0, \fB(1)\fP C++20) + size_type count = npos ); + iterator erase( iterator \fI(until C++11)\fP + position ); + iterator erase( \fI(since C++11)\fP + const_iterator position ); (constexpr since + \fB(2)\fP C++20) + iterator erase( iterator \fI(until C++11)\fP + first, iterator last ); + iterator erase( \fB(3)\fP \fI(since C++11)\fP + const_iterator first, (constexpr since + const_iterator last ); C++20) + + Removes specified characters from the string. + + 1) Removes std::min(count, size() - index) characters starting at index. + 2) Removes the character at position. + If position is not a dereferenceable iterator on *this, the behavior is undefined. + 3) Removes the characters in the range [first, last). + If first or last is not a valid iterator on *this, or [first, last) is not a valid + range, the behavior is undefined. + +.SH Parameters + + index - first character to remove + count - number of characters to remove + position - iterator to the character to remove + first, last - range of the characters to remove + +.SH Return value + + 1) *this + 2) Iterator pointing to the character immediately following the character erased, or + end() if no such character exists. + 3) Iterator pointing to the character last pointed to before the erase, or end() if + no such character exists. + +.SH Exceptions + + 1) std::out_of_range if index > size(). + 2,3) Throws nothing. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s = "This Is An Example"; + std::cout << "1) " << s << '\\n'; + + s.erase(7, 3); // erases " An" using overload (1) + std::cout << "2) " << s << '\\n'; + + s.erase(std::find(s.begin(), s.end(), ' ')); // erases first ' '; overload (2) + std::cout << "3) " << s << '\\n'; + + s.erase(s.find(' ')); // trims from ' ' to the end of the string; overload (1) + std::cout << "4) " << s << '\\n'; + + auto it = std::next(s.begin(), s.find('s')); // obtains iterator to the first 's' + s.erase(it, std::next(it, 2)); // erases "sI"; overload (3) + std::cout << "5) " << s << '\\n'; + } + +.SH Output: + + 1) This Is An Example + 2) This Is Example + 3) ThisIs Example + 4) ThisIs + 5) This + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(3)\fP did not erase the character returns an iterator + LWG 27 C++98 last pointed to, but it returned pointing to that + the iterator pointing to the character character + immediately following that character + overload \fB(2)\fP explicitly required position + LWG 428 C++98 to be valid, but removed the + SequenceContainer requires it to be explicit requirement + dereferenceable (stricter) + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + +.SH See also + + clear clears the contents + \fI(public member function)\fP diff --git a/man/std::wstring::find.3 b/man/std::wstring::find.3 deleted file mode 120000 index 6675f6f1b..000000000 --- a/man/std::wstring::find.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find.3 \ No newline at end of file diff --git a/man/std::wstring::find.3 b/man/std::wstring::find.3 new file mode 100644 index 000000000..6ae3d060f --- /dev/null +++ b/man/std::wstring::find.3 @@ -0,0 +1,171 @@ +.TH std::basic_string::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find \- std::basic_string::find + +.SH Synopsis + size_type find( const basic_string& str, size_type pos = \fB(1)\fP (noexcept since C++11) + 0 ) const; (constexpr since C++20) + size_type find( const CharT* s, size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find( const CharT* s, size_type pos = 0 ) \fB(3)\fP (constexpr since C++20) + const; + size_type find( CharT ch, size_type pos = 0 ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type find( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first substring equal to the given character sequence. Search begins at + pos, i.e. the found substring must not begin in a position preceding pos. + + 1) Finds the first substring equal to str. + 2) Finds the first substring equal to the range [s, s + count). This range may + contain null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character ch (treated as a single-character substring by the + formal rules below). + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first substring equal to sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + Formally, a substring str is said to be found at position xpos if all of the + following are true: + + * xpos >= pos + * xpos + str.size() <= size() + * for all positions n in str, Traits::eq(at(xpos + n), str.at(n)). + + In particular, this implies that + + * a substring can be found only if pos <= size() - str.size() + * an empty substring is found at pos if and only if pos <= size() + * for a non-empty substring, if pos >= size(), the function always returns npos. + +.SH Parameters + + str - string to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(int id, std::string::size_type n, std::string const& s) + { + std::cout << id << ") "; + if (std::string::npos == n) + std::cout << "not found! n == npos\\n"; + else + std::cout << "found @ n = " << n << ", substr(" << n << ") = " + << std::quoted(s.substr(n)) << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; /* + ^ ^ ^ + 1 2 3 */ + + // search from beginning of string + n = s.find("is"); + print(1, n, s); + + // search from position 5 + n = s.find("is", 5); + print(2, n, s); + + // find a single character + n = s.find('a'); + print(3, n, s); + + // find a single character + n = s.find('q'); + print(4, n, s); + } + +.SH Output: + + 1) found @ n = 2, substr\fB(2)\fP = "is is a string" + 2) found @ n = 5, substr\fB(5)\fP = "is a string" + 3) found @ n = 8, substr\fB(8)\fP = "a string" + 4) not found! n == npos + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + strstr finds the first occurrence of a substring of characters + \fI(function)\fP + finds the first occurrence of a wide string within another wide + wcsstr string + \fI(function)\fP + strchr finds the first occurrence of a character + \fI(function)\fP + wcschr finds the first occurrence of a wide character in a wide string + \fI(function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find characters in the view + find \fI(public member function of std::basic_string_view)\fP + + search searches for a range of elements + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::find_first_not_of.3 b/man/std::wstring::find_first_not_of.3 deleted file mode 120000 index 7cd66aee2..000000000 --- a/man/std::wstring::find_first_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_not_of.3 \ No newline at end of file diff --git a/man/std::wstring::find_first_not_of.3 b/man/std::wstring::find_first_not_of.3 new file mode 100644 index 000000000..795a2e7ce --- /dev/null +++ b/man/std::wstring::find_first_not_of.3 @@ -0,0 +1,141 @@ +.TH std::basic_string::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_not_of \- std::basic_string::find_first_not_of + +.SH Synopsis + size_type find_first_not_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_first_not_of( const CharT* s, \fB(3)\fP (constexpr since C++20) + size_type pos = 0 ) const; + size_type find_first_not_of( CharT ch, size_type pos = 0 \fB(4)\fP (noexcept since C++11) + ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const + noexcept(/* see below */); + + Finds the first character equal to none of the characters in the given character + sequence. The search considers only the range [pos, size()). If all characters in + the range can be found in the given character sequence, npos will be returned. + + 1) Finds the first character equal to none of characters in str. + 2) Finds the first character equal to none of characters in range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position for the search to start from + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or std::string::npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // Permit uppercase letters, lowercase letters and numbers in macro names + const char* pattern = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + "abcdefghijklmnopqrstuvwxyz" + "0123456789"; + + std::string data = "1) %FIX, 2) %HACK, and 3) %TODO"; + const std::string replacement = "%DONE%"; + + std::cout << "Before: " << data << '\\n'; + + for (std::string::size_type first{}, last{}; + (first = data.find('%', first)) != std::string::npos; + first += replacement.size()) + { + last = data.find_first_not_of(pattern, first + 1); + if (last == std::string::npos) + last = data.length(); + + // Now first at '%' and last is one past end of the found substring + data.replace(first, last - first, replacement); + } + + std::cout << "After: " << data << '\\n'; + } + +.SH Output: + + Before: 1) %FIX, 2) %HACK, and 3) %TODO + After: 1) %DONE%, 2) %DONE%, and 3) %DONE% + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::find_first_of.3 b/man/std::wstring::find_first_of.3 deleted file mode 120000 index 497a89646..000000000 --- a/man/std::wstring::find_first_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_first_of.3 \ No newline at end of file diff --git a/man/std::wstring::find_first_of.3 b/man/std::wstring::find_first_of.3 new file mode 100644 index 000000000..e6263f90c --- /dev/null +++ b/man/std::wstring::find_first_of.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_first_of \- std::basic_string::find_first_of + +.SH Synopsis + size_type find_first_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = 0 ) const; (constexpr since C++20) + size_type find_first_of( const CharT* s, + size_type pos, size_type count \fB(2)\fP (constexpr since C++20) + ) const; + size_type find_first_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + 0 ) const; + size_type find_first_of( CharT ch, size_type pos = 0 ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_first_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = 0 ) const noexcept(/* + see below */); + + Finds the first character equal to one of the characters in the given character + sequence. The search considers only the range [pos, size()). If none of the + characters in the given character sequence is present in the range, npos will be + returned. + + 1) Finds the first character equal to one of the characters in str. + 2) Finds the first character equal to one of the characters in the range [s, s + + count). This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the first character equal to one of the characters in character string + pointed to by s. The length of the string is determined by the first null character + using Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the first character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the first character equal to one of the characters in + sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to begin searching + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Traits::eq() is used to perform the comparison. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + std::string::size_type sz; + + // (1) + sz = "alignas"s.find_first_of("klmn"s); + // └────────────────────────┘ + assert(sz == 1); + + sz = "alignof"s.find_first_of("wxyz"s); + // no match + assert(sz == std::string::npos); + + // (2) + sz = "consteval"s.find_first_of("xyzabc", 0, 3); + // no match (× are not targets) ××× + assert(sz == std::string::npos); + + sz = "consteval"s.find_first_of("xyzabc", 0, 6); + // └───────────────────────────────┘ + assert(sz == 0); + + // (3) + sz = "decltype"s.find_first_of("xyzabc"); + // └────────────────────────────┘ + assert(sz == 2); + + // (4) + sz = "co_await"s.find_first_of('a'); + // └──────────────────────┘ + assert(sz == 3); + + // (5) + sz = "constinit"s.find_first_of("int"sv); + // └─────────────────────────┘ + assert(sz == 2); + + std::cout << "All tests passed.\\n"; + } + +.SH Output: + + All tests passed. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidentally dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI(public member function of std::basic_string_view)\fP + + returns the length of the maximum initial segment that consists + strspn of only the characters found in another byte string + \fI(function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::find_last_not_of.3 b/man/std::wstring::find_last_not_of.3 deleted file mode 120000 index 85f8838a9..000000000 --- a/man/std::wstring::find_last_not_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_not_of.3 \ No newline at end of file diff --git a/man/std::wstring::find_last_not_of.3 b/man/std::wstring::find_last_not_of.3 new file mode 100644 index 000000000..b325c1428 --- /dev/null +++ b/man/std::wstring::find_last_not_of.3 @@ -0,0 +1,160 @@ +.TH std::basic_string::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_not_of \- std::basic_string::find_last_not_of + +.SH Synopsis + size_type find_last_not_of( const basic_string& str, (noexcept since C++11) + size_type pos = npos ) \fB(1)\fP (constexpr since C++20) + const; + size_type find_last_not_of( const CharT* s, + size_type pos, size_type \fB(2)\fP (constexpr since C++20) + count ) const; + size_type find_last_not_of( const CharT* s, size_type \fB(3)\fP (constexpr since C++20) + pos = npos ) const; + size_type find_last_not_of( CharT ch, size_type pos = \fB(4)\fP (noexcept since C++11) + npos ) const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_not_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to none of the characters in the given character + sequence. The search considers only the range [0, pos]. If all characters in the + range can be found in the given character sequence, npos will be returned. + + 1) Finds the last character equal to none of characters in str. + 2) Finds the last character equal to none of characters in the range [s, s + count). + This range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to none of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character not equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to none of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which to end search + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character identifying characters to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v< + const T&, std::basic_string_view>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + void show_pos(const std::string& str, std::string::size_type found) + { + if (found != std::string::npos) + std::cout << '[' << found << "] = \\'" << str[found] << "\\'\\n"; + else + std::cout << "not found\\n"; + } + + int main() + { + std::string str{"abc_123"}; + char const* skip_set{"0123456789"}; + std::string::size_type str_last_pos{std::string::npos}; + + show_pos(str, str.find_last_not_of(skip_set)); // [3] = '_' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of(skip_set, str_last_pos)); // [2] = 'c' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of('c', str_last_pos)); // [1] = 'b' + + const char arr[]{'3', '4', '5'}; + show_pos(str, str.find_last_not_of(arr)); // [5] = '2' + + str_last_pos = 2; + std::string::size_type skip_set_size{4}; + show_pos(str, str.find_last_not_of(skip_set, + str_last_pos, + skip_set_size)); // [2] = 'c' + + show_pos(str, str.find_last_not_of("abc")); // [6] = '3' + + str_last_pos = 2; + show_pos(str, str.find_last_not_of("abc", str_last_pos)); // not found + } + +.SH Output: + + [3] = '_' + [2] = 'c' + [1] = 'b' + [5] = '2' + [2] = 'c' + [6] = '3' + not found + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::find_last_of.3 b/man/std::wstring::find_last_of.3 deleted file mode 120000 index 18ea1b60d..000000000 --- a/man/std::wstring::find_last_of.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::find_last_of.3 \ No newline at end of file diff --git a/man/std::wstring::find_last_of.3 b/man/std::wstring::find_last_of.3 new file mode 100644 index 000000000..e3ff59859 --- /dev/null +++ b/man/std::wstring::find_last_of.3 @@ -0,0 +1,126 @@ +.TH std::basic_string::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::find_last_of \- std::basic_string::find_last_of + +.SH Synopsis + size_type find_last_of( const basic_string& str, \fB(1)\fP (noexcept since C++11) + size_type pos = npos ) const; (constexpr since C++20) + size_type find_last_of( const CharT* s, + size_type pos, size_type count ) \fB(2)\fP (constexpr since C++20) + const; + size_type find_last_of( const CharT* s, size_type pos = \fB(3)\fP (constexpr since C++20) + npos ) const; + size_type find_last_of( CharT ch, size_type pos = npos ) \fB(4)\fP (noexcept since C++11) + const; (constexpr since C++20) + template< class StringViewLike > + + size_type \fI(since C++17)\fP + find_last_of( const StringViewLike& t, \fB(5)\fP (constexpr since C++20) + + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last character equal to one of characters in the given character sequence. + The exact search algorithm is not specified. The search considers only the range + [0, pos]. If none of the characters in the given character sequence is present in + the range, npos will be returned. + + 1) Finds the last character equal to one of characters in str. + 2) Finds the last character equal to one of characters in range [s, s + count). This + range can include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last character equal to one of characters in character string pointed + to by s. The length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last character equal to one of characters in sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string identifying characters to search for + pos - position at which the search is to finish + count - length of character string identifying characters to search for + s - pointer to a character string identifying characters to search for + ch - character to search for + t - object (convertible to std::basic_string_view) identifying characters to + search for + +.SH Return value + + Position of the found character or npos if no such character is found. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string path = "/root/config"; + auto const pos = path.find_last_of('/'); + const auto leaf = path.substr(pos + 1); + + std::cout << leaf << '\\n'; + } + +.SH Output: + + config + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 141 C++98 overload \fB(1)\fP could only return npos the search range is + if pos >= size() [0, size()) in this case + LWG 847 C++98 there was no exception safety added strong exception + guarantee safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + C++11 noexcept for overloads (4,5) were + P1148R0 C++17 accidentally dropped by restored + LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::front.3 b/man/std::wstring::front.3 deleted file mode 120000 index 6e46155d2..000000000 --- a/man/std::wstring::front.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::front.3 \ No newline at end of file diff --git a/man/std::wstring::front.3 b/man/std::wstring::front.3 new file mode 100644 index 000000000..978ec6830 --- /dev/null +++ b/man/std::wstring::front.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::front \- std::basic_string::front + +.SH Synopsis + CharT& front(); \fB(1)\fP (constexpr since C++20) + const CharT& front() const; \fB(2)\fP (constexpr since C++20) + + Returns reference to the first character in the string. The behavior is undefined if + empty() is true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Notes + + In libstdc++, front() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s("Exemplary"); + char& f1 = s.front(); + f1 = 'e'; + std::cout << s << '\\n'; // "exemplary" + + std::string const c("Exemplary"); + char const& f2 = c.front(); + std::cout << &f2 << '\\n'; // "Exemplary" + } + +.SH Output: + + exemplary + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function front() + +.SH See also + + back accesses the last character + (DR*) \fI(public member function)\fP + front accesses the first character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::get_allocator.3 b/man/std::wstring::get_allocator.3 deleted file mode 120000 index a59c7178f..000000000 --- a/man/std::wstring::get_allocator.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::get_allocator.3 \ No newline at end of file diff --git a/man/std::wstring::get_allocator.3 b/man/std::wstring::get_allocator.3 new file mode 100644 index 000000000..52b590226 --- /dev/null +++ b/man/std::wstring::get_allocator.3 @@ -0,0 +1,30 @@ +.TH std::basic_string::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::get_allocator \- std::basic_string::get_allocator + +.SH Synopsis + allocator_type get_allocator() const; (noexcept since C++20) + (constexpr since C++20) + + Returns the allocator associated with the string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The associated allocator. + +.SH Complexity + + Constant. + +.SH See also + + allocator the default allocator + \fI(class template)\fP + allocator_traits provides information about allocator types + \fI(C++11)\fP \fI(class template)\fP + uses_allocator checks if the specified type supports uses-allocator construction + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::wstring::insert.3 b/man/std::wstring::insert.3 deleted file mode 120000 index 06d0b9ef6..000000000 --- a/man/std::wstring::insert.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::insert.3 \ No newline at end of file diff --git a/man/std::wstring::insert.3 b/man/std::wstring::insert.3 new file mode 100644 index 000000000..28be988e6 --- /dev/null +++ b/man/std::wstring::insert.3 @@ -0,0 +1,228 @@ +.TH std::basic_string::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert \- std::basic_string::insert + +.SH Synopsis + basic_string& insert( (constexpr + size_type index, size_type \fB(1)\fP since + count, CharT ch ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(2)\fP since + CharT* s ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(3)\fP since + CharT* s, size_type count ); C++20) + basic_string& insert( (constexpr + size_type index, const \fB(4)\fP since + basic_string& str ); C++20) + basic_string& insert( + size_type index, const + basic_string& str, (until + C++14) + size_type s_index, size_type + count ); + basic_string& insert( (since + size_type index, const C++14) + basic_string& str, (constexpr + since + size_type s_index, size_type C++20) + count = npos ); + iterator insert( iterator (until + pos, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, CharT ch (constexpr + ); since + C++20) + void insert( iterator pos, (until + size_type count, CharT ch ); C++11) + (since + iterator insert( C++11) + const_iterator pos, (constexpr + size_type count, CharT ch ); since + C++20) + template< class InputIt > + void insert( iterator pos, \fB(5)\fP (until + InputIt first, InputIt last C++11) + ); + template< class InputIt > (since + iterator insert( C++11) + const_iterator pos, InputIt (constexpr + first, InputIt last ); \fB(6)\fP since + C++20) + iterator insert( (since + const_iterator pos, \fB(7)\fP C++11) + std::initializer_list \fB(9)\fP (constexpr + ilist ); since + C++20) + template< class \fB(8)\fP (since + StringViewLike > C++17) + basic_string& insert( \fB(10)\fP (constexpr + size_type index, const since + StringViewLike& t ); C++20) + template< class + StringViewLike > + (since + basic_string& insert( C++17) + size_type index, const \fB(11)\fP (constexpr + StringViewLike& t, since + C++20) + + size_type t_index, size_type + count = npos ); + + Inserts characters into the string. + + 1) Inserts count copies of character ch at the position index. + 2) Inserts null-terminated character string pointed to by s at the position index. + The length of the string is determined by the first null character using + Traits::length(s). + 3) Inserts the characters in the range [s, s + count) at the position index. The + range can contain null characters. + 4) Inserts string str at the position index. + 5) Inserts a string, obtained by str.substr(s_index, count) at the position index. + 6) Inserts character ch before the character pointed by pos. + 7) Inserts count copies of character ch before the element (if any) pointed by pos. + 8) Inserts characters from the range [first, last) before the element (if any) + pointed by pos, as if by insert(pos - begin(), basic_string(first, last, + get_allocator())). + + This overload does not participate in overload resolution if InputIt \fI(since C++11)\fP + does not satisfy LegacyInputIterator. + + 9) Inserts elements from initializer list ilist before the element (if any) pointed + by pos. + 10) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts the elements from sv before the element (if any) + pointed by index, as if by insert(index, sv.data(), sv.size()). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 11) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then inserts, before the element (if any) pointed by index, the + characters from the subview [t_index, t_index + count) of sv. + * If the requested subview lasts past the end of sv, or if count == npos, the + resulting subview is [t_index, sv.size()). + * If t_index > sv.size(), or if index > size(), std::out_of_range is thrown. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + index - position at which the content will be inserted + pos - iterator before which the characters will be inserted + ch - character to insert + count - number of characters to insert + s - pointer to the character string to insert + str - string to insert + first, last - range defining characters to insert + s_index - position of the first character in str to insert + ilist - std::initializer_list to insert the characters from + t - object (convertible to std::basic_string_view) to insert the + characters from + t_index - position of the first character in t to insert +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + 1-5) *this + 6-9) An iterator which refers to the copy of the first inserted character or pos if + no characters were inserted (count == 0 or first == last or ilist.size() == 0) + 10,11) *this + +.SH Exceptions + + 1-4,10) Throws std::out_of_range if index > size(). + 5) Throws std::out_of_range if index > size() or if s_index > str.size(). + 11) Throws std::out_of_range if index > size() or if t_index > sv.size(). + + In all cases, throws std::length_error if size() + ins_count > max_size() where + ins_count is the number of characters that will be inserted. + + In all cases, if std::allocator_traits::allocate throws an \fI(since C++20)\fP + exception, it is rethrown. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::string_literals; + + int main() + { + std::string s = "xmplr"; + + // insert(size_type index, size_type count, char ch) + s.insert(0, 1, 'E'); + assert("Exmplr" == s); + + // insert(size_type index, const char* s) + s.insert(2, "e"); + assert("Exemplr" == s); + + // insert(size_type index, string const& str) + s.insert(6, "a"s); + assert("Exemplar" == s); + + // insert(size_type index, string const& str, + // size_type s_index, size_type count) + s.insert(8, " is an example string."s, 0, 14); + assert("Exemplar is an example" == s); + + // insert(const_iterator pos, char ch) + s.insert(s.cbegin() + s.find_first_of('n') + 1, ':'); + assert("Exemplar is an: example" == s); + + // insert(const_iterator pos, size_type count, char ch) + s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '='); + assert("Exemplar is an:== example" == s); + + // insert(const_iterator pos, InputIt first, InputIt last) + { + std::string seq = " string"; + s.insert(s.begin() + s.find_last_of('e') + 1, + std::begin(seq), std::end(seq)); + assert("Exemplar is an:== example string" == s); + } + + // insert(const_iterator pos, std::initializer_list) + s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'}); + assert("Exemplar is an:== example string." == s); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 7 C++98 overload (8) referred to a non-existing refers to overload (4) + overload correctly + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2946 C++17 overload (10) caused ambiguity in some avoided by making it a + cases template + +.SH See also + + insert_range inserts a range of characters + (C++23) \fI(public member function)\fP + append appends characters to the end + \fI(public member function)\fP + push_back appends a character to the end + \fI(public member function)\fP diff --git a/man/std::wstring::insert_range.3 b/man/std::wstring::insert_range.3 new file mode 100644 index 000000000..172031ebb --- /dev/null +++ b/man/std::wstring::insert_range.3 @@ -0,0 +1,84 @@ +.TH std::basic_string::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::insert_range \- std::basic_string::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + constexpr iterator insert_range( const_iterator pos, R&& rg ); + + Inserts characters from the range rg before the element (if any) pointed by pos. + + Equivalent to + + return insert(pos - begin(), + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + + If pos is not a valid iterator on *this, the behavior is undefined. + +.SH Parameters + + pos - iterator before which the characters will be inserted + rg - a container compatible range + +.SH Return value + + An iterator which refers to the first inserted character, or pos if no characters + were inserted because rg was empty. + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If std::allocator_traits::allocate throws an exception, it is rethrown. + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const auto source = {'l', 'i', 'b', '_'}; + std::string target{"__cpp_containers_ranges"}; + // ^insertion will occur + // before this position + + const auto pos = target.find("container"); + assert(pos != target.npos); + auto iter = std::next(target.begin(), pos); + + #ifdef __cpp_lib_containers_ranges + target.insert_range(iter, source); + #else + target.insert(iter, source.begin(), source.end()); + #endif + + assert(target == "__cpp_lib_containers_ranges"); + // ^^^^ + } + +.SH See also + + insert inserts characters + \fI(public member function)\fP diff --git a/man/std::wstring::max_size.3 b/man/std::wstring::max_size.3 deleted file mode 120000 index 450f8a80c..000000000 --- a/man/std::wstring::max_size.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::max_size.3 \ No newline at end of file diff --git a/man/std::wstring::max_size.3 b/man/std::wstring::max_size.3 new file mode 100644 index 000000000..806a1dd4a --- /dev/null +++ b/man/std::wstring::max_size.3 @@ -0,0 +1,92 @@ +.TH std::basic_string::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::max_size \- std::basic_string::max_size + +.SH Synopsis + size_type max_size() const; (noexcept since C++11) + (constexpr since C++20) + + Returns the maximum number of elements the string is able to hold due to system or + library implementation limitations, i.e. std::distance(begin(), end()) for the + largest string. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + #include + + template + void print_basic_string_max_size() + { + std::basic_string s; + auto max_size = s.max_size(); + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << "basic_string<" << boost::core::demangle(typeid(T).name()) + << ">:\\n\\t" << max_size << " = "; + std::cout << std::setprecision(3) << (double) max_size << " = "; + std::cout.imbue(std::locale("C")); + std::cout << std::hex << std::setfill('0') << "0x" + << std::setw(sizeof(typename decltype(s)::size_type) << 1) + << max_size << '\\n' << std::dec; + }; + + int main() + { + std::cout << "Pointer size: " << CHAR_BIT * sizeof(void*) << " bits\\n" + "Maximum sizes:\\n"; + + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + print_basic_string_max_size(); + + using CharT = std::array; + print_basic_string_max_size(); + } + +.SH Possible output: + + Pointer size: 64 bits + Maximum sizes: + basic_string: + 9,223,372,036,854,775,807 = 9.22e+18 = 0x7fffffffffffffff + basic_string: + 4,611,686,018,427,387,903 = 4.61e+18 = 0x3fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 2,305,843,009,213,693,951 = 2.31e+18 = 0x1fffffffffffffff + basic_string: + 1,152,921,504,606,846,975 = 1.15e+18 = 0x0fffffffffffffff + basic_string>: + 13,848,906,962,244,407 = 1.38e+16 = 0x00313381ec031337 + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::npos.3 b/man/std::wstring::npos.3 deleted file mode 120000 index 4582d0216..000000000 --- a/man/std::wstring::npos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::npos.3 \ No newline at end of file diff --git a/man/std::wstring::npos.3 b/man/std::wstring::npos.3 new file mode 100644 index 000000000..cb8bcc779 --- /dev/null +++ b/man/std::wstring::npos.3 @@ -0,0 +1,55 @@ +.TH std::basic_string::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::npos \- std::basic_string::npos + +.SH Synopsis + static const size_type npos = -1; + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of string indicator by the functions that expect a string index or as the error + indicator by the functions that return a string index. + +.SH Note + + Although the definition uses -1, size_type is an unsigned integer type, and the + value of npos is the largest positive value it can hold, due to signed-to-unsigned + implicit conversion. This is a portable way to specify the largest value of any + unsigned type. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // string search functions return npos if nothing is found + std::string s = "test"; + if (s.find('a') == s.npos) + std::cout << "no 'a' in 'test'\\n"; + + // functions that take string subsets as arguments + // use npos as the "all the way to the end" indicator + std::string s2(s, 2, std::string::npos); + std::cout << s2 << '\\n'; + + std::bitset<5> b("aaabb", std::string::npos, 'a', 'b'); + std::cout << b << '\\n'; + } + +.SH Output: + + no 'a' in 'test' + st + 00011 + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant of std::basic_string_view)\fP + diff --git a/man/std::wstring::operator+=.3 b/man/std::wstring::operator+=.3 deleted file mode 120000 index 54ff82159..000000000 --- a/man/std::wstring::operator+=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator+=.3 \ No newline at end of file diff --git a/man/std::wstring::operator+=.3 b/man/std::wstring::operator+=.3 new file mode 100644 index 000000000..6f5ea9049 --- /dev/null +++ b/man/std::wstring::operator+=.3 @@ -0,0 +1,120 @@ +.TH std::basic_string::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator+= \- std::basic_string::operator+= + +.SH Synopsis + basic_string& operator+=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator+=( CharT ch ); \fB(2)\fP (constexpr since C++20) + basic_string& operator+=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator+=( std::initializer_list \fB(4)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template< class StringViewLike > \fB(5)\fP \fI(since C++17)\fP + basic_string& operator+=( const StringViewLike& t ); (constexpr since C++20) + + Appends additional characters to the string. + + 1) Appends string str. + 2) Appends character ch. + 3) Appends the null-terminated character string pointed to by s. + 4) Appends characters in the initializer list ilist. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then appends characters in the string view sv as if by append(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + +.SH Parameters + + str - string to append + ch - character value to append + s - pointer to a null-terminated character string to append + ilist - std::initializer_list with the characters to append + t - object (convertible to std::basic_string_view) with the characters to append + +.SH Return value + + *this + +.SH Complexity + + There are no standard complexity guarantees, typical implementations behave similar + to std::vector::insert(). + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Overload \fB(2)\fP can accept any types that are implicitly convertible to CharT. For + std::string, where CharT is char, the set of acceptable types includes all + arithmetic types. This may have unintended effects. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str; + + // reserve sufficient storage space to avoid memory reallocation + str.reserve(50); + + std::cout << std::quoted(str) << '\\n'; // empty string + + str += "This"; + std::cout << std::quoted(str) << '\\n'; + + str += std::string(" is "); + std::cout << std::quoted(str) << '\\n'; + + str += 'a'; + std::cout << std::quoted(str) << '\\n'; + + str += {' ', 's', 't', 'r', 'i', 'n', 'g', '.'}; + std::cout << std::quoted(str) << '\\n'; + + str += 69.96; // Equivalent to str += static_cast(69.96); + // 'E' (ASCII code 69) is appended by overload (2), + // which might not be the intent. + + // To add a numeric value, consider std::to_string(): + str += std::to_string(1729); + + std::cout << std::quoted(str) << '\\n'; + } + +.SH Output: + + "" + "This" + "This is " + "This is a" + "This is a string." + "This is a string.E1729" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in avoided by making it a + some cases template + +.SH See also + + append appends characters to the end + \fI(public member function)\fP diff --git a/man/std::wstring::operator=.3 b/man/std::wstring::operator=.3 deleted file mode 120000 index 5505d7126..000000000 --- a/man/std::wstring::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator=.3 \ No newline at end of file diff --git a/man/std::wstring::operator=.3 b/man/std::wstring::operator=.3 new file mode 100644 index 000000000..70b37150d --- /dev/null +++ b/man/std::wstring::operator=.3 @@ -0,0 +1,153 @@ +.TH std::basic_string::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator= \- std::basic_string::operator= + +.SH Synopsis + basic_string& operator=( const basic_string& str ); \fB(1)\fP (constexpr since C++20) + basic_string& operator=( basic_string&& str ) \fB(2)\fP \fI(since C++11)\fP + noexcept(/* see below */); (constexpr since C++20) + basic_string& operator=( const CharT* s ); \fB(3)\fP (constexpr since C++20) + basic_string& operator=( CharT ch ); \fB(4)\fP (constexpr since C++20) + basic_string& operator=( std::initializer_list \fB(5)\fP \fI(since C++11)\fP + ilist ); (constexpr since C++20) + template \fB(6)\fP \fI(since C++17)\fP + basic_string& operator=( const StringViewLike& t ); (constexpr since C++20) + basic_string& operator=( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + Replaces the contents of the string. + + 1) Replaces the contents with a copy of str. If *this and str are the same object, + this function has no effect. + 2) Replaces the contents with those of str using SequenceContainer's move assignment + semantics. + Unlike other sequence container move assignments, references, pointers, and + iterators to elements of str may be invalidated. + 3) Replaces the contents with those of null-terminated character string pointed to + by s as if by assign(s, Traits::length(s)). + 4) Replaces the contents with character ch as if by assign(std::addressof(ch), 1). + 5) Replaces the contents with those of the initializer list ilist as if by + assign(ilist.begin(), ilist.size()). + 6) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the contents with those of the sv as if by + assign(sv). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 7) std::basic_string cannot be assigned from nullptr. + +.SH Parameters + + ch - value to initialize characters of the string with + str - string to be used as source to initialize the string with + s - pointer to a null-terminated character string to use as source to initialize + the string with + ilist - std::initializer_list to initialize the string with + t - object convertible to std::basic_string_view to initialize the string with + +.SH Return value + + *this + +.SH Complexity + + 1) Linear in size of str. + 2) Linear in the size of *this (formally, each CharT has to be destroyed). If + allocators do not compare equal and do not propagate, then also linear in the size + of str (copy must be made). + 3) Linear in size of s. + 4) Constant. + 5) Linear in size of ilist. + 6) Linear in size of t. + +.SH Exceptions + + 2) + noexcept specification: + noexcept(std::allocator_traits:: + + propagate_on_container_move_assignment::value || + + std::allocator_traits::is_always_equal::value) + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str1; + std::string str2{"alpha"}; + + // (1) operator=(const basic_string&); + str1 = str2; + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "alpha" + + // (2) operator=(basic_string&&); + str1 = std::move(str2); + std::cout << std::quoted(str1) << ' ' // "alpha" + << std::quoted(str2) << '\\n'; // "" or "alpha" (unspecified) + + // (3) operator=(const CharT*); + str1 = "beta"; + std::cout << std::quoted(str1) << '\\n'; // "beta" + + // (4) operator=(CharT); + str1 = '!'; + std::cout << std::quoted(str1) << '\\n'; // "!" + + // (5) operator=(std::initializer_list); + str1 = {'g', 'a', 'm', 'm', 'a'}; + std::cout << std::quoted(str1) << '\\n'; // "gamma" + + // (6) operator=(const T&); + str1 = 35U; // equivalent to str1 = static_cast(35U); + std::cout << std::quoted(str1) << '\\n'; // "#" (ASCII = 35) + } + +.SH Possible output: + + "alpha" "alpha" + "alpha" "" + "beta" + "!" + "gamma" + "#" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + the move assignment operator did not + LWG 2063 C++11 follow follows + SequenceContainer's semantic requirement + LWG 2946 C++17 overload \fB(6)\fP caused ambiguity in some avoided by making it a + cases template + +.SH See also + + constructor constructs a basic_string + \fI(public member function)\fP + assign assign characters to a string + \fI(public member function)\fP + assigns a view + operator= \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::operator[].3 b/man/std::wstring::operator[].3 deleted file mode 120000 index 05791619e..000000000 --- a/man/std::wstring::operator[].3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::operator[].3 \ No newline at end of file diff --git a/man/std::wstring::operator[].3 b/man/std::wstring::operator[].3 new file mode 100644 index 000000000..8fa941e51 --- /dev/null +++ b/man/std::wstring::operator[].3 @@ -0,0 +1,83 @@ +.TH std::basic_string::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operator[] \- std::basic_string::operator[] + +.SH Synopsis + CharT& operator[]( size_type pos ); \fB(1)\fP (constexpr since C++20) + const CharT& operator[]( size_type pos ) const; \fB(2)\fP (constexpr since C++20) + + Returns a reference to the character at specified location pos if pos < size(), or a + reference to CharT() if pos == size(). No bounds checking is performed. + + If pos > size(), the behavior is undefined. + + For overload \fB(1)\fP, if pos == size(), the behavior is undefined + if the object referred by the returned reference is modified to any value other than + CharT() + \fI(since C++11)\fP. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + *(begin() + pos) if pos < size(), or a reference to CharT() if pos == size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + const std::string e("Exemplar"); + for (unsigned i = e.length() - 1; i != 0; i /= 2) + std::cout << e[i]; + std::cout << '\\n'; + + const char* c = &e[0]; + std::cout << c << '\\n'; // print as a C string + + // Change the last character of s into a 'y' + std::string s("Exemplar "); + s[s.size() - 1] = 'y'; // equivalent to s.back() = 'y'; + std::cout << s << '\\n'; + } + +.SH Output: + + rmx + Exemplar + Exemplary + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 259 C++98 non-const overload could return const lvalue changed to return + data()[pos], which was ill-formed *(begin() + pos) + if pos == size(), the behavior of modifying + LWG 2475 C++11 the well-defined if + object referred by the returned reference modified to CharT() + was undefined + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function)\fP + operator[] accesses the specified character + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::operatorbasic_string_view.3 b/man/std::wstring::operatorbasic_string_view.3 new file mode 100644 index 000000000..7860d59f8 --- /dev/null +++ b/man/std::wstring::operatorbasic_string_view.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::operatorbasic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::operatorbasic_string_view \- std::basic_string::operatorbasic_string_view + +.SH Synopsis + operator std::basic_string_view() const \fI(since C++17)\fP + noexcept; (constexpr since C++20) + + Returns a std::basic_string_view, constructed as if by std::basic_string_view(data(), size()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A string view representing the entire contents of the string. + +.SH Notes + + It is the programmer's responsibility to ensure that the resulting string view does + not outlive the string. + + std::string get_string(); + int f(std::string_view sv); + + int x = f(get_string()); // OK + std::string_view sv = get_string(); // Bad: holds a dangling pointer + +.SH Example + + +// Run this code + + #include + #include + #include + + void show_wstring_size(std::wstring_view wcstr_v) + { + std::cout << wcstr_v.size() << " code points\\n"; + } + + int main() + { + std::string cppstr = "ラーメン"; // narrow string + std::wstring wcstr = L"ラーメン"; // wide string + + // Implicit conversion from string to string_view + // via std::string::operator string_view: + std::string_view cppstr_v = cppstr; + + std::cout << cppstr_v << '\\n' + << cppstr_v.size() << " code units\\n"; + + // Implicit conversion from wstring to wstring_view + // via std::wstring::operator wstring_view: + show_wstring_size(wcstr); + } + +.SH Output: + + ラーメン + 12 code units + 4 code points + +.SH See also + + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::wstring::pop_back.3 b/man/std::wstring::pop_back.3 deleted file mode 120000 index 92b01df6a..000000000 --- a/man/std::wstring::pop_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::pop_back.3 \ No newline at end of file diff --git a/man/std::wstring::pop_back.3 b/man/std::wstring::pop_back.3 new file mode 100644 index 000000000..1ef904042 --- /dev/null +++ b/man/std::wstring::pop_back.3 @@ -0,0 +1,75 @@ +.TH std::basic_string::pop_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::pop_back \- std::basic_string::pop_back + +.SH Synopsis + void pop_back(); (constexpr since C++20) + + Removes the last character from the string. + + Equivalent to erase(end() - 1). The behavior is undefined if the string is empty. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + Throws nothing. + +.SH Notes + + In libstdc++, pop_back() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string str("Short string!"); + std::cout << "before=" << std::quoted(str) << '\\n'; + assert(str.size() == 13); + + str.pop_back(); + std::cout << " after=" << std::quoted(str) << '\\n'; + assert(str.size() == 12); + + str.clear(); + // str.pop_back(); // undefined behavior + } + +.SH Output: + + before="Short string!" + after="Short string" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 534 C++98 std::basic_string did not have the member added + function pop_back() + +.SH See also + + push_back appends a character to the end + \fI(public member function)\fP + erase removes characters + \fI(public member function)\fP diff --git a/man/std::wstring::push_back.3 b/man/std::wstring::push_back.3 deleted file mode 120000 index fde2976b5..000000000 --- a/man/std::wstring::push_back.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::push_back.3 \ No newline at end of file diff --git a/man/std::wstring::push_back.3 b/man/std::wstring::push_back.3 new file mode 100644 index 000000000..122b1e8fe --- /dev/null +++ b/man/std::wstring::push_back.3 @@ -0,0 +1,68 @@ +.TH std::basic_string::push_back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::push_back \- std::basic_string::push_back + +.SH Synopsis + void push_back( CharT ch ); (constexpr since C++20) + + Appends the given character ch to the end of the string. + +.SH Parameters + + ch - the character to append + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Amortized constant. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string str{"Short string"}; + std::cout << "1) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + + str.push_back('!'); + std::cout << "2) " << std::quoted(str) << ", size: " << str.size() << '\\n'; + } + +.SH Output: + + 1) "Short string", size: 12 + 2) "Short string!", size: 13 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + \fB(1)\fP the description was missing in + LWG 7 C++98 the C++ standard \fB(1)\fP description added + \fB(2)\fP the parameter type was const (2) changed to CharT + CharT + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + pop_back removes the last character + (DR*) \fI(public member function)\fP diff --git a/man/std::wstring::rbegin,.3 b/man/std::wstring::rbegin,.3 new file mode 100644 index 000000000..eecaa5142 --- /dev/null +++ b/man/std::wstring::rbegin,.3 @@ -0,0 +1,67 @@ +.TH std::basic_string::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rbegin, \- std::basic_string::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the first character of the reversed string. It + corresponds to the last character of the non-reversed string. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string s("Exemplar!"); + *s.rbegin() = 'y'; + std::cout << s << '\\n'; // "Exemplary" + + std::string c; + std::copy(s.crbegin(), s.crend(), std::back_inserter(c)); + std::cout << c << '\\n'; // "yralpmexE" + } + +.SH Output: + + Exemplary + yralpmexE + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::rbegin,std::basic_string::crbegin.3 b/man/std::wstring::rbegin,std::basic_string::crbegin.3 deleted file mode 120000 index e36abe435..000000000 --- a/man/std::wstring::rbegin,std::basic_string::crbegin.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rbegin,std::basic_string::crbegin.3 \ No newline at end of file diff --git a/man/std::wstring::rend,.3 b/man/std::wstring::rend,.3 new file mode 100644 index 000000000..c28ff3818 --- /dev/null +++ b/man/std::wstring::rend,.3 @@ -0,0 +1,70 @@ +.TH std::basic_string::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rend, \- std::basic_string::rend, + +.SH Synopsis + + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + (constexpr since C++20) + + Returns a reverse iterator to the character following the last character of the + reversed string. It corresponds to the character preceding the first character of + the non-reversed string. This character acts as a placeholder, attempting to access + it results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::string p("[A man, a plan, a canal: Panama]"); + std::string q; + + std::copy(p.crbegin(), p.crend(), std::back_inserter(q)); + std::cout << "q = " << q << '\\n'; + + std::copy(q.crbegin(), q.crend(), p.rbegin()); + std::cout << "p = " << p << '\\n'; + } + +.SH Output: + + q = ]amanaP :lanac a ,nalp a ,nam A[ + p = ]amanaP :lanac a ,nalp a ,nam A[ + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::rend,std::basic_string::crend.3 b/man/std::wstring::rend,std::basic_string::crend.3 deleted file mode 120000 index 600152427..000000000 --- a/man/std::wstring::rend,std::basic_string::crend.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rend,std::basic_string::crend.3 \ No newline at end of file diff --git a/man/std::wstring::replace.3 b/man/std::wstring::replace.3 deleted file mode 120000 index 3a94b3a6f..000000000 --- a/man/std::wstring::replace.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::replace.3 \ No newline at end of file diff --git a/man/std::wstring::replace.3 b/man/std::wstring::replace.3 new file mode 100644 index 000000000..7b1e79fc7 --- /dev/null +++ b/man/std::wstring::replace.3 @@ -0,0 +1,184 @@ +.TH std::basic_string::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace \- std::basic_string::replace + +.SH Synopsis + basic_string& replace( size_type pos, + size_type count, \fB(1)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(2)\fP (constexpr since + const basic_string& str C++20) + ); + basic_string& replace( size_type pos, + size_type count, + + const basic_string& \fI(until C++14)\fP + str, + + size_type pos2, + size_type count2 ); + basic_string& replace( size_type pos, + size_type count, + \fI(since C++14)\fP + const basic_string& (constexpr since + str, C++20) + + size_type pos2, + size_type count2 = npos ); + basic_string& replace( size_type pos, + size_type count, \fB(4)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(5)\fP (constexpr since + const CharT* cstr, C++20) + size_type count2 ); + basic_string& replace( size_type pos, (constexpr since + size_type count, \fB(6)\fP C++20) + const CharT* cstr ); + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(7)\fP C++20) + const CharT* cstr ); + basic_string& replace( size_type pos, + size_type count, \fB(8)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + basic_string& replace( const_iterator first, + const_iterator last, \fB(3)\fP \fB(9)\fP (constexpr since + size_type count2, CharT C++20) + ch ); + template< class InputIt > + + basic_string& replace( const_iterator first, (constexpr since + const_iterator last, \fB(10)\fP C++20) + + InputIt first2, InputIt + last2 ); + basic_string& replace( const_iterator first, \fI(since C++11)\fP + const_iterator last, \fB(11)\fP (constexpr since + C++20) + std::initializer_list ilist ); + template< class StringViewLike > + + basic_string& replace( size_type pos, \fI(since C++17)\fP + size_type count, \fB(12)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( const_iterator first, \fI(since C++17)\fP + const_iterator last, \fB(13)\fP (constexpr since + C++20) + const StringViewLike& t + ); + template< class StringViewLike > + + basic_string& replace( size_type pos, + size_type count, \fI(since C++17)\fP + const StringViewLike& \fB(14)\fP (constexpr since + t, C++20) + + size_type pos2, + size_type count2 = npos ); + + Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count, + size())) or [first, last) with given characters. + + 1,2) Those characters are replaced with str. + 3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2, + str.size())) of str. + 4,5) Those characters are replaced with the characters in the range [cstr, cstr + + count2). + If [cstr, cstr + count2) is not a valid range, the behavior is undefined. + 6,7) Those characters are replaced with the characters in the range [cstr, cstr + + Traits::length(cstr)). + 8,9) Those characters are replaced with count2 copies of ch. + 10) Those characters are replaced with the characters in the range [first2, last2) + as if by replace(first, last, basic_string(first2, last2, get_allocator())). + 11) Those characters are replaced with the characters in ilist. + 12,13) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then those characters are replaced + with the characters from sv. + These overloads participate in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 14) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then those characters are replaced with the characters from the + subview sv.substr(pos2, count2). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + If [begin(), first) or [first, last) is not a valid range, the behavior is + undefined. + +.SH Parameters + + pos - start of the substring that is going to be replaced + count - length of the substring that is going to be replaced + first, last - range of characters that is going to be replaced + str - string to use for replacement + pos2 - start of the substring to replace with + count2 - number of characters to replace with + cstr - pointer to the character string to use for replacement + ch - character value to use for replacement + first2, last2 - range of characters to use for replacement + ilist - initializer list with the characters to use for replacement + t - object (convertible to std::basic_string_view) with the characters + to use for replacement +.SH Type requirements + - + InputIt must meet the requirements of LegacyInputIterator. + +.SH Return value + + *this. + +.SH Exceptions + + 1) Throws std::out_of_range if pos > size(). + 3) Throws std::out_of_range if pos > size() or pos2 > str.size(). + 4,6,8) Throws std::out_of_range if pos > size(). + 12,14) Throws std::out_of_range if pos > size(). + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 1323 C++98 the types of first and last changed to const_iterator + were iterator + LWG 2946 C++17 overloads (12,13) caused avoided by making them templates + ambiguity in some cases + +.SH See also + + replace_with_range replaces specified portion of a string with a range of characters + (C++23) \fI(public member function)\fP + regex_replace replaces occurrences of a regular expression with formatted + \fI(C++11)\fP replacement text + \fI(function template)\fP + replace replaces all values satisfying specific criteria with another + replace_if value + \fI(function template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstring::replace_with_range.3 b/man/std::wstring::replace_with_range.3 new file mode 100644 index 000000000..a06106cbc --- /dev/null +++ b/man/std::wstring::replace_with_range.3 @@ -0,0 +1,91 @@ +.TH std::basic_string::replace_with_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::replace_with_range \- std::basic_string::replace_with_range + +.SH Synopsis + template< container-compatible-range R > + + constexpr std::basic_string& replace_with_range( const_iterator + first, (since C++23) + const_iterator last, + + R&& rg ); + + Replaces the characters in the range [first, last) with the characters from the + range rg. + + Equivalent to + + return replace(first, + last, + std::basic_string( + std::from_range, + std::forward(rg), + get_allocator()) + ); + +.SH Parameters + + first, last - range of characters that is going to be replaced + rg - a container compatible range + +.SH Return value + + *this + +.SH Complexity + + Linear in size of rg. + +.SH Exceptions + + If the operation would result in size() > max_size(), throws std::length_error. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) member functions that accept container + compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + using namespace std::literals; + + auto s{"Today is today!"s}; + constexpr auto today{"today"sv}; + constexpr auto tomorrow{"tomorrow's yesterday"sv}; + std::forward_list rg; + std::ranges::reverse_copy(tomorrow, std::front_inserter(rg)); + + const auto pos{s.rfind(today)}; + assert(pos != s.npos); + const auto first{std::next(s.begin(), pos)}; + const auto last{std::next(first, today.length())}; + + #ifdef __cpp_lib_containers_ranges + s.replace_range(first, last, rg); + #else + s.replace(first, last, rg.cbegin(), rg.cend()); + #endif + + assert("Today is tomorrow's yesterday!" == s); + } + +.SH See also + + replace replaces specified portion of a string + \fI(public member function)\fP diff --git a/man/std::wstring::reserve.3 b/man/std::wstring::reserve.3 deleted file mode 120000 index 8af41bde6..000000000 --- a/man/std::wstring::reserve.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::reserve.3 \ No newline at end of file diff --git a/man/std::wstring::reserve.3 b/man/std::wstring::reserve.3 new file mode 100644 index 000000000..3f0d1423a --- /dev/null +++ b/man/std::wstring::reserve.3 @@ -0,0 +1,112 @@ +.TH std::basic_string::reserve 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::reserve \- std::basic_string::reserve + +.SH Synopsis + void reserve( size_type new_cap = 0 ); \fI(until C++20)\fP + constexpr void reserve( size_type new_cap ); \fI(since C++20)\fP + \fB(1)\fP \fI(since C++20)\fP + void reserve(); \fB(2)\fP (deprecated in C++20) + (removed in C++26) + + 1) Informs a std::basic_string object of a planned change in size, so that it can + manage the storage allocation appropriately. + * If new_cap is greater than the current capacity(), new storage is allocated, and + capacity() is made equal or greater than new_cap. + + * If new_cap is less than the current capacity(), this is a + non-binding shrink request. + * If new_cap is less than the current size(), this is a non-binding \fI(until C++20)\fP + shrink-to-fit request + equivalent to shrink_to_fit() + \fI(since C++11)\fP. + * If new_cap is less than or equal to the current capacity(), there \fI(since C++20)\fP + is no effect. + + If a capacity change takes place, all iterators and references, including the + past-the-end iterator, are invalidated. + 2) A non-binding shrink-to-fit request. After this call, capacity() has an + unspecified value greater than or equal to size(). + +.SH Parameters + + new_cap - new capacity of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Throws std::length_error if new_cap is greater than max_size(). + + May throw any exceptions thrown by std::allocator_traits::allocate(), + such as std::bad_alloc. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Complexity + + At most linear in the size() of the string. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s; + std::cout << "1) Initially: " << s.capacity() << '\\n'; + + const std::string::size_type new_cap{101u}; + s.reserve(new_cap); + assert(s.capacity() >= new_cap); + std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\\n'; + + // observing the capacity growth factor + auto cap{s.capacity()}; + for (int check{}; check != 4; ++check) + { + while (cap == s.capacity()) + s += '$'; + cap = s.capacity(); + std::cout << (3) + check << ") Capacity: " << cap << '\\n'; + } + + // s.reserve(); // deprecated/removed in C++20/26, use: + s.shrink_to_fit(); + std::cout << "7) After shrink_to_fit: " << s.capacity() << '\\n'; + } + +.SH Possible output: + + 1) Initially: 15 + 2) After reserve(101): 101 + 3) Capacity: 202 + 4) Capacity: 404 + 5) Capacity: 808 + 6) Capacity: 1616 + 7) After shrink_to_fit: 809 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::wstring::resize.3 b/man/std::wstring::resize.3 deleted file mode 120000 index 15f0e17b9..000000000 --- a/man/std::wstring::resize.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::resize.3 \ No newline at end of file diff --git a/man/std::wstring::resize.3 b/man/std::wstring::resize.3 new file mode 100644 index 000000000..3b4c7a8b6 --- /dev/null +++ b/man/std::wstring::resize.3 @@ -0,0 +1,140 @@ +.TH std::basic_string::resize 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize \- std::basic_string::resize + +.SH Synopsis + void resize( size_type count ); \fB(1)\fP (constexpr since C++20) + void resize( size_type count, CharT ch ); \fB(2)\fP (constexpr since C++20) + + Resizes the string to contain count characters. + + If the current size is less than count, additional characters are appended: + + 1) Initializes appended characters to CharT() ('\\0' if CharT is char). + 2) Initializes appended characters to ch. + + If the current size is greater than count, the string is reduced to its first count + elements. + +.SH Parameters + + count - new size of the string + ch - character to initialize the new characters with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > max_size(). Any exceptions thrown by corresponding + Allocator. + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + const unsigned desired_length{8}; + std::string long_string("Where is the end?"); + std::string short_string("H"); + + std::cout << "Basic functionality:\\n" + << "Shorten:\\n" + << "1. Before: " << std::quoted(long_string) << '\\n'; + long_string.resize(desired_length); + std::cout << "2. After: " << std::quoted(long_string) << '\\n'; + + std::cout << "Lengthen with a given value 'a':\\n" + << "3. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length, 'a'); + std::cout << "4. After: " << std::quoted(short_string) << '\\n'; + + std::cout << "Lengthen with char() == " << static_cast(char()) << '\\n' + << "5. Before: " << std::quoted(short_string) << '\\n'; + short_string.resize(desired_length + 3); + std::cout << "6. After: \\""; + for (char c : short_string) + std::cout << (c == char() ? '@' : c); + std::cout << "\\"\\n\\n"; + + std::cout << "Errors:\\n"; + std::string s; + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size() - 1, 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "1. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is OK, no length_error + // (may throw bad_alloc) + s.resize(s.max_size(), 'x'); + } + catch (const std::bad_alloc& ex) + { + std::cout << "2. Exception: " << ex.what() << '\\n'; + } + + try + { + // size is BAD, throw length_error + s.resize(s.max_size() + 1, 'x'); + } + catch (const std::length_error& ex) + { + std::cout << "3. Length error: " << ex.what() << '\\n'; + } + } + +.SH Possible output: + + Basic functionality: + Shorten: + 1. Before: "Where is the end?" + 2. After: "Where is" + Lengthen with a given value 'a': + 3. Before: "H" + 4. After: "Haaaaaaa" + Lengthen with char() == 0 + 5. Before: "Haaaaaaa" + 6. After: "Haaaaaaa@@@" + + Errors: + 1. Exception: std::bad_alloc + 2. Exception: std::bad_alloc + 3. Length error: basic_string::_M_replace_aux + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + reserve reserves storage + \fI(public member function)\fP + shrink_to_fit reduces memory usage by freeing unused memory + (DR*) \fI(public member function)\fP diff --git a/man/std::wstring::resize_and_overwrite.3 b/man/std::wstring::resize_and_overwrite.3 new file mode 100644 index 000000000..192feef8a --- /dev/null +++ b/man/std::wstring::resize_and_overwrite.3 @@ -0,0 +1,163 @@ +.TH std::basic_string::resize_and_overwrite 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::resize_and_overwrite \- std::basic_string::resize_and_overwrite + +.SH Synopsis + template< class Operation > (since C++23) + constexpr void resize_and_overwrite( size_type count, Operation op ); + + Resizes the string to contain at most count characters, using the user-provided + operation op to modify the possibly indeterminate contents and set the length. This + avoids the cost of initializing a suitably-sized std::string when it is intended to + be used as a char array to be populated by, e.g., a C API call. + + This function performs following steps: + + 1. Obtains contiguous storage that contains count + 1 characters, and makes its + first k characters equal to the first k characters of *this, where k is the + smaller of count and the result of this->size() before the call to + resize_and_overwrite. Let p denote the pointer to the first character in the + storage. + * The equality is determined as if by checking this->compare(0, k, p, k) == + 0. + * The characters in [p + k, p + count] may have indeterminate values. + 2. Evaluates std::move(op)(p, count). Let r be the return value of std::move(op)(p, + count). + 3. Replaces the contents of *this with [p, p + r) (which sets the length of *this + to r). Invalidates all pointers and references to the range [p, p + count]. + + The program is ill-formed if r does not have an integer-like type. The behavior is + undefined if std::move(op)(p, count) throws an exception or modifies p or count, r + is not in the range [0, count], or any character in range [p, p + r) has an + indeterminate value. + + Implementations are recommended to avoid unnecessary copies and allocations by, + e.g., making p equal to the pointer to beginning of storage of characters allocated + for *this after the call, which can be identical to the existing storage of *this if + count is less than or equal to this->capacity(). + +.SH Parameters + + count - the maximal possible new size of the string + op - the function object used for setting the new contents of the string + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + std::length_error if count > this->max_size(). Any exceptions thrown by + corresponding Allocator. + + If an exception is thrown from std::move(op)(p, count), the behavior is undefined. + Otherwise, if an exception is thrown, this function has no effect. + +.SH Notes + + resize_and_overwrite invalidates all iterators, pointers, and references into *this, + regardless whether reallocation occurs. Implementations may assume that the contents + of the string are not aliased after the call to resize_and_overwrite. + + Feature-test macro Value Std Feature +__cpp_lib_string_resize_and_overwrite 202110L (C++23) std::basic_string::resize_and_overwrite + +.SH Example + + Link to test the example: compiler explorer. + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + static_assert(__cpp_lib_string_resize_and_overwrite); + + constexpr std::string_view fruits[]{"apple", "banana", "coconut", "date", "elderberry"}; + + int main() + { + // A simple case, append only fruits[0]. The string size will be increased. + std::string s{"Food: "}; + s.resize_and_overwrite(16, [sz = s.size()](char* buf, std::size_t buf_size) noexcept + { + const auto to_copy = std::min(buf_size - sz, fruits[0].size()); + std::memcpy(buf + sz, fruits[0].data(), to_copy); + return sz + to_copy; + }); + std::cout << "1. " << std::quoted(s) << '\\n'; + + // The size shrinking case. Note, that the user's lambda is always invoked. + s.resize_and_overwrite(10, [](char* buf, int n) noexcept + { + return std::find(buf, buf + n, ':') - buf; + }); + std::cout << "2. " << std::quoted(s) << '\\n'; + + std::cout << "3. Copy data until the buffer is full. Print data and sizes.\\n"; + std::string food{"Food:"}; + const auto resize_to{27}; + std::cout << "Initially, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", resize_to: " << resize_to + << ", food: " << std::quoted(food) << '\\n'; + + food.resize_and_overwrite( + resize_to, + [food_size = food.size()](char* p, std::size_t n) noexcept -> std::size_t + { + // p[0]..p[n] is the assignable range + // p[0]..p[min(n, food_size) - 1] is the readable range + // (contents initially equal to the original string) + + // Debug print: + std::cout << "In Operation(); n: " << n << '\\n'; + + // Copy fruits to the buffer p while there is enough space. + char* first = p + food_size; + + for (char* const end = p + n; const std::string_view fruit : fruits) + { + char* last = first + fruit.size() + 1; + if (last > end) + break; + *first++ = ' '; + std::ranges::copy(fruit, first); + first = last; + } + + const auto final_size{static_cast(first - p)}; + + // Debug print: + std::cout << "In Operation(); final_size: " << final_size << '\\n'; + + assert(final_size <= n); + return final_size; // Return value is the actual new length + // of the string, must be in range 0..n + }); + + std::cout << "Finally, food.size: " << food.size() + << ", food.capacity: " << food.capacity() + << ", food: " << std::quoted(food) << '\\n'; + } + +.SH Possible output: + + 1. "Food: apple" + 2. "Food" + 3. Copy data until the buffer is full. Print data and sizes. + Initially, food.size: 5, food.capacity: 15, resize_to: 27, food: "Food:" + In Operation(); n: 27 + In Operation(); final_size: 26 + Finally, food.size: 26, food.capacity: 30, food: "Food: apple banana coconut" + +.SH See also + + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::wstring::rfind.3 b/man/std::wstring::rfind.3 deleted file mode 120000 index 6ca6348d9..000000000 --- a/man/std::wstring::rfind.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::rfind.3 \ No newline at end of file diff --git a/man/std::wstring::rfind.3 b/man/std::wstring::rfind.3 new file mode 100644 index 000000000..6baebe7ca --- /dev/null +++ b/man/std::wstring::rfind.3 @@ -0,0 +1,161 @@ +.TH std::basic_string::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::rfind \- std::basic_string::rfind + +.SH Synopsis + size_type rfind( const basic_string& str, size_type pos \fB(1)\fP (noexcept since C++11) + = npos ) const; (constexpr since C++20) + size_type rfind( const CharT* s, size_type pos, \fB(2)\fP (constexpr since C++20) + size_type count ) const; + size_type rfind( const CharT* s, size_type pos = npos ) \fB(3)\fP (constexpr since C++20) + const; + size_type rfind( CharT ch, size_type pos = npos ) const; \fB(4)\fP (noexcept since C++11) + (constexpr since C++20) + template< class StringViewLike > + + size_type rfind( const StringViewLike& t, \fB(5)\fP \fI(since C++17)\fP + (constexpr since C++20) + size_type pos = npos ) const + noexcept(/* see below */); + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last substring equal to str. + 2) Finds the last substring equal to the range [s, s + count). This range can + include null characters. + If [s, s + count) is not a valid range, the behavior is undefined. + 3) Finds the last substring equal to the character string pointed to by s. The + length of the string is determined by the first null character using + Traits::length(s). + If [s, s + Traits::length(s)) is not a valid range, the behavior is undefined. + 4) Finds the last character equal to ch. + 5) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then finds the last substring equal to the contents of sv. + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + + In all cases, equality is checked by calling Traits::eq. + +.SH Parameters + + str - string to search for + pos - position at which to begin searching + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + t - object (convertible to std::basic_string_view) to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. Note that this is an offset from the start of the string, not the end. + + If searching for an empty string (i.e., str.size(), count, or Traits::length(s) is + zero), the empty string is found immediately and rfind returns: + + * pos, if pos < size(); + * size() otherwise, including the case where pos == npos. + + Otherwise, if size() is zero, npos is always returned. + +.SH Exceptions + + 1,4) Throws nothing. + 5) + noexcept specification: + noexcept(std::is_nothrow_convertible_v>) + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). + +.SH Example + + +// Run this code + + #include + #include + #include + + void print(std::string::size_type n, + std::string::size_type len, + std::string const &s) + { + if (n == std::string::npos) + std::cout << "not found\\n"; + else + std::cout << "found: " << std::quoted(s.substr(n, len)) << " at " << n << '\\n'; + } + + int main() + { + std::string::size_type n; + std::string const s = "This is a string"; + + // search backwards from end of string + n = s.rfind("is"); + print(n, 2, s); + + // search backwards from position 4 + n = s.rfind("is", 4); + print(n, 2, s); + + // find a single character + n = s.rfind('s'); + print(n, 1, s); + + // find a single character + n = s.rfind('q'); + print(n, 1, s); + + // find the prefix (see also s.starts_with("This")) + n = s.rfind("This", 0); + print(n, 4, s); + } + +.SH Output: + + found: "is" at 5 + found: "is" at 2 + found: "s" at 10 + not found + found: "This" at 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety guarantee added strong exception + safety guarantee + LWG 2064 C++11 overloads (3,4) were noexcept removed + LWG 2946 C++17 overload \fB(5)\fP caused ambiguity in some avoided by making it a + cases template + P1148R0 C++11 noexcept for overloads (4,5) were restored + C++17 accidently dropped by LWG2064/LWG2946 + +.SH See also + + find finds the first occurrence of the given substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI(public member function of std::basic_string_view)\fP + + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::shrink_to_fit.3 b/man/std::wstring::shrink_to_fit.3 deleted file mode 120000 index af19637a3..000000000 --- a/man/std::wstring::shrink_to_fit.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::shrink_to_fit.3 \ No newline at end of file diff --git a/man/std::wstring::shrink_to_fit.3 b/man/std::wstring::shrink_to_fit.3 new file mode 100644 index 000000000..506b08ea9 --- /dev/null +++ b/man/std::wstring::shrink_to_fit.3 @@ -0,0 +1,95 @@ +.TH std::basic_string::shrink_to_fit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::shrink_to_fit \- std::basic_string::shrink_to_fit + +.SH Synopsis + void shrink_to_fit(); (constexpr since C++20) + + Requests the removal of unused capacity. + + It is a non-binding request to reduce capacity() to size(). It depends on the + implementation if the request is fulfilled. + + If (and only if) reallocation takes place, all pointers, references, and iterators + are invalidated. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + (unspecified) \fI(until C++17)\fP + Linear in the size of the string. \fI(since C++17)\fP + +.SH Notes + + In libstdc++, shrink_to_fit() is not available in C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string s; + std::cout << "Size of std::string is " << sizeof s << " bytes\\n" + << "Default-constructed capacity is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + for (int i = 0; i < 42; i++) + s.append(" 42 "); + std::cout << "Capacity after 42 appends is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.clear(); + std::cout << "Capacity after clear() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + + s.shrink_to_fit(); + std::cout << "Capacity after shrink_to_fit() is " << s.capacity() + << " and size is " << s.size() << '\\n'; + } + +.SH Possible output: + + GCC output: + Size of std::string is 32 bytes + Default-constructed capacity is 15 and size 0 + Capacity after 42 appends is 240 and size 168 + Capacity after clear() is 240 and size 0 + Capacity after shrink_to_fit() is 15 and size 0 + + clang output (with -stdlib=libc++): + Size of std::string is 24 bytes + Default-constructed capacity is 22 and size is 0 + Capacity after 42 appends is 191 and size is 168 + Capacity after clear() is 191 and size is 0 + Capacity after shrink_to_fit() is 22 and size is 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 755 C++98 std::string lacked explicit shrink-to-fit provided + operations + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + returns the number of characters that can be held in currently allocated + capacity storage + \fI(public member function)\fP + resize changes the number of characters stored + \fI(public member function)\fP diff --git a/man/std::wstring::size,.3 b/man/std::wstring::size,.3 new file mode 100644 index 000000000..46f96cd93 --- /dev/null +++ b/man/std::wstring::size,.3 @@ -0,0 +1,72 @@ +.TH std::basic_string::size, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::size, \- std::basic_string::size, + +.SH Synopsis + + size_type size() const; \fB(1)\fP (noexcept since C++11) + (constexpr since C++20) + size_type length() const; \fB(2)\fP (noexcept since C++11) + (constexpr since C++20) + + Returns the number of CharT elements in the string, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the string. + +.SH Complexity + + Unspecified \fI(until C++11)\fP + Constant \fI(since C++11)\fP + +.SH Notes + + For std::string, the elements are bytes (objects of type char), which are not the + same as characters if a multibyte encoding such as UTF-8 is used. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string s("Exemplar"); + assert(8 == s.size()); + assert(s.size() == s.length()); + assert(s.size() == static_cast( + std::distance(s.begin(), s.end()))); + + std::u32string a(U"ハロー・ワールド"); // 8 code points + assert(8 == a.size()); // 8 code units in UTF-32 + + std::u16string b(u"ハロー・ワールド"); // 8 code points + assert(8 == b.size()); // 8 code units in UTF-16 + + std::string c("ハロー・ワールド"); // 8 code points + assert(24 == c.size()); // 24 code units in UTF-8 + + #if __cplusplus >= 202002 + std::u8string d(u8"ハロー・ワールド"); // 8 code points + assert(24 == d.size()); // 24 code units in UTF-8 + #endif + } + +.SH See also + + empty checks whether the string is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::size,std::basic_string::length.3 b/man/std::wstring::size,std::basic_string::length.3 deleted file mode 120000 index dbf50666e..000000000 --- a/man/std::wstring::size,std::basic_string::length.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::size,std::basic_string::length.3 \ No newline at end of file diff --git a/man/std::wstring::starts_with.3 b/man/std::wstring::starts_with.3 new file mode 100644 index 000000000..54b219105 --- /dev/null +++ b/man/std::wstring::starts_with.3 @@ -0,0 +1,85 @@ +.TH std::basic_string::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::starts_with \- std::basic_string::starts_with + +.SH Synopsis + constexpr bool + starts_with( std::basic_string_view sv ) const \fB(1)\fP \fI(since C++20)\fP + noexcept; + constexpr bool \fB(2)\fP \fI(since C++20)\fP + starts_with( CharT ch ) const noexcept; + constexpr bool \fB(3)\fP \fI(since C++20)\fP + starts_with( const CharT* s ) const; + + Checks if the string begins with the given prefix. The prefix may be one of the + following: + + 1) A string view sv (which may be a result of implicit conversion from another + std::basic_string). + 2) A single character ch. + 3) A null-terminated character string s. + + All three overloads effectively return std::basic_string_view(data(), + size()).starts_with(x), where x is the parameter. + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from another + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using namespace std::literals; + + const auto str = "Hello, C++20!"s; + + assert + ("" + && str.starts_with("He"sv) // (1) + && !str.starts_with("he"sv) // (1) + && str.starts_with("He"s) // (1) implicit conversion string to string_view + && !str.starts_with("he"s) // (1) implicit conversion string to string_view + && str.starts_with('H') // (2) + && !str.starts_with('h') // (2) + && str.starts_with("He") // (3) + && !str.starts_with("he") // (3) + ); + } + +.SH See also + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function of std::basic_string_view)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function of std::basic_string_view)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function)\fP + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function of std::basic_string_view)\fP + compare compares two strings + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP diff --git a/man/std::wstring::substr.3 b/man/std::wstring::substr.3 deleted file mode 120000 index 3a94fd2cd..000000000 --- a/man/std::wstring::substr.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::substr.3 \ No newline at end of file diff --git a/man/std::wstring::substr.3 b/man/std::wstring::substr.3 new file mode 100644 index 000000000..f263d4824 --- /dev/null +++ b/man/std::wstring::substr.3 @@ -0,0 +1,113 @@ +.TH std::basic_string::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::substr \- std::basic_string::substr + +.SH Synopsis + basic_string substr( size_type pos = 0, size_type (until C++23) + count = npos ) const; (constexpr since C++20) + constexpr basic_string + substr( size_type pos = 0, size_type count = \fB(1)\fP (since C++23) + npos ) const&; + constexpr basic_string substr( size_type pos = 0, \fB(2)\fP (since C++23) + size_type count = npos ) &&; + + Returns a substring [pos, pos + count). If the requested substring extends past the + end of the string, i.e. the count is greater than size() - pos (e.g. if count == + npos), the returned substring is [pos, size()). + + 1) Equivalent to return basic_string(*this, pos, count);. + 2) Equivalent to return basic_string(std::move(*this), pos, count);. + +.SH Parameters + + pos - position of the first character to include + count - length of the substring + +.SH Return value + + String containing the substring [pos, pos + count) or [pos, size()). + +.SH Exceptions + + std::out_of_range if pos > size(). + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Complexity + + Linear in count. + +.SH Notes + + The allocator of the returned string is default-constructed: the new allocator might + not be a copy of get_allocator(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "0123456789abcdefghij"; + + // count is npos, returns [pos, size()) + std::string sub1 = a.substr(10); + std::cout << sub1 << '\\n'; + + // both pos and pos + count are within bounds, returns [pos, pos + count) + std::string sub2 = a.substr(5, 3); + std::cout << sub2 << '\\n'; + + // pos is within bounds, pos + count is not, returns [pos, size()) + std::string sub4 = a.substr(a.size() - 3, 50); + // this is effectively equivalent to + // std::string sub4 = a.substr(17, 3); + // since a.size() == 20, pos == a.size() - 3 == 17, and a.size() - pos == 3 + + std::cout << sub4 << '\\n'; + + try + { + // pos is out of bounds, throws + std::string sub5 = a.substr(a.size() + 3, 50); + std::cout << sub5 << '\\n'; + } + catch (const std::out_of_range& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + abcdefghij + 567 + hij + basic_string::substr: __pos (which is 23) > this->size() (which is 20) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + +.SH See also + + copy copies characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function)\fP + find finds the first occurrence of the given substring + \fI(public member function)\fP + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + substr returns a substring + \fI(public member function of std::basic_string_view)\fP diff --git a/man/std::wstring::swap.3 b/man/std::wstring::swap.3 deleted file mode 120000 index bc1277047..000000000 --- a/man/std::wstring::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::swap.3 \ No newline at end of file diff --git a/man/std::wstring::swap.3 b/man/std::wstring::swap.3 new file mode 100644 index 000000000..07e64dbec --- /dev/null +++ b/man/std::wstring::swap.3 @@ -0,0 +1,96 @@ +.TH std::basic_string::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::swap \- std::basic_string::swap + +.SH Synopsis + void swap( basic_string& other ); \fI(until C++17)\fP + void swap( basic_string& other ) noexcept(/* see below */); \fI(since C++17)\fP + (constexpr since C++20) + + Exchanges the contents of the string with those of other. All iterators and + references may be invalidated. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + +.SH Parameters + + other - string to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Exceptions + + No exception is thrown. \fI(until C++11)\fP + Exceptions can only be thrown in the case where the behavior is + undefined (see above). + \fI(since C++11)\fP + If an exception is thrown for any reason, this function has no effect + (strong exception safety guarantee). + + noexcept specification: + noexcept(std::allocator_traits::propagate_on_container_swap::value (since + || C++17) + std::allocator_traits::is_always_equal::value) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string a = "AAA"; + std::string b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 403 C++98 swap() might throw an exception no exception is thrown + LWG 535 C++98 swapping strings did not preserve the orders are also preserved + character orders + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swap swaps the contents + \fI(public member function of std::basic_string_view)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstring::wstring.3 b/man/std::wstring::wstring.3 deleted file mode 120000 index 5a560e279..000000000 --- a/man/std::wstring::wstring.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_string::basic_string.3 \ No newline at end of file diff --git a/man/std::wstring::wstring.3 b/man/std::wstring::wstring.3 new file mode 100644 index 000000000..431026f74 --- /dev/null +++ b/man/std::wstring::wstring.3 @@ -0,0 +1,317 @@ +.TH std::basic_string::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::basic_string \- std::basic_string::basic_string + +.SH Synopsis + basic_string(); \fI(until C++17)\fP + basic_string() noexcept(noexcept(Allocator())) \fI(since C++17)\fP + : basic_string( Allocator() ) {} (constexpr since + C++20) + (noexcept since + explicit basic_string( const Allocator& alloc ); \fB(2)\fP C++17) + (constexpr since + C++20) + basic_string( size_type count, CharT ch, \fB(3)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const basic_string& other, size_type pos, \fB(4)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + constexpr basic_string( basic_string&& other, size_type + pos, \fB(5)\fP (since C++23) + const Allocator& alloc = + Allocator() ); + basic_string( const basic_string& other, + + size_type pos, size_type count, \fB(6)\fP (since C++23) + + const Allocator& alloc = Allocator() ); + constexpr basic_string( basic_string&& other, + + size_type pos, size_type count, \fB(7)\fP (since C++23) + + const Allocator& alloc = + Allocator() ); + basic_string( const CharT* s, size_type count, \fB(8)\fP (constexpr since + const Allocator& alloc = Allocator() ); C++20) + basic_string( const CharT* s, const Allocator& alloc = \fB(9)\fP (constexpr since + Allocator() ); C++20) + template< class InputIt > + (constexpr since + basic_string( InputIt first, InputIt last, \fB(1)\fP \fB(10)\fP C++20) + + const Allocator& alloc = Allocator() ); + basic_string( const basic_string& other ); \fB(11)\fP (constexpr since + C++20) + basic_string( const basic_string& other, const Allocator& \fI(since C++11)\fP + alloc ); \fB(12)\fP (constexpr since + C++20) + \fI(since C++11)\fP + basic_string( basic_string&& other ) noexcept; \fB(13)\fP (constexpr since + C++20) + basic_string( basic_string&& other, const Allocator& alloc \fI(since C++11)\fP + ); \fB(14)\fP (constexpr since + C++20) + basic_string( std::initializer_list ilist, \fI(since C++11)\fP + const Allocator& alloc = Allocator() ); \fB(15)\fP (constexpr since + C++20) + template< class StringViewLike > + \fI(since C++17)\fP + explicit basic_string( const StringViewLike& t, \fB(16)\fP (constexpr since + C++20) + const Allocator& alloc = + Allocator() ); + template< class StringViewLike > + \fI(since C++17)\fP + basic_string( const StringViewLike& t, size_type pos, \fB(17)\fP (constexpr since + size_type n, C++20) + + const Allocator& alloc = Allocator() ); + basic_string( std::nullptr_t ) = delete; \fB(18)\fP (since C++23) + template< container-compatible-range R > + + constexpr basic_string( std::from_range_t, R&& rg, \fB(19)\fP (since C++23) + + const Allocator& = Allocator()); + + Constructs new string from a variety of data sources and optionally using user + supplied allocator alloc. + + 1,2) Default constructor. Constructs empty string (of zero size and unspecified + capacity). If no allocator is supplied, allocator is obtained from a + default-constructed instance. + 3) Constructs the string with count copies of character ch. + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 4-7) Constructs the string with a substring [pos, pos + count) of other. If count == + npos, if count is not specified, or if the requested substring lasts past the end of + the string, the resulting substring is [pos, other.size()). + If other is an rvalue reference, it is left in a valid but unspecified state. + (since C++23) + 8) Constructs the string with the first count characters of character string pointed + to by s. s can contain null characters. The length of the string is count. The + behavior is undefined if [s, s + count) is not a valid range. + 9) Constructs the string with the contents initialized with a copy of the + null-terminated character string pointed to by s. The length of the string is + determined by the first null character. The behavior is undefined if [s, s + + Traits::length(s)) is not a valid range (for example, if s is a null pointer). + This constructor is not used for class template argument deduction if the Allocator + type that would be deduced does not qualify as an allocator. + \fI(since C++17)\fP + 10) Constructs the string with the contents of the range [first, last). + + If InputIt is an integral type, equivalent to overload \fB(2)\fP, as if by + basic_string(static_cast(first), \fI(until C++11)\fP + static_cast(last), alloc). + This constructor only participates in overload resolution if InputIt \fI(since C++11)\fP + satisfies LegacyInputIterator. + + 11,12) Copy constructor. Constructs the string with a copy of the contents of other. + 13,14) Move constructor. Constructs the string with the contents of other using move + semantics. other is left in valid, but unspecified state. + 15) Constructs the string with the contents of the initializer list ilist. + 16) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the contents of sv, as if by + basic_string(sv.data(), sv.size(), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true and + std::is_convertible_v is false. + 17) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then initializes the string with the subrange [pos, pos + n) of sv + as if by basic_string(sv.substr(pos, n), alloc). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + 18) std::basic_string cannot be constructed from nullptr. + 19) Constructs the string with the values contained in the range rg. + +.SH Parameters + + alloc - allocator to use for all memory allocations of this string + count - size of the resulting string + ch - value to initialize the string with + pos - position of the first character to include + first, last - range to copy the characters from + s - pointer to an array of characters to use as source to initialize the + string with + other - another string to use as source to initialize the string with + ilist - std::initializer_list to initialize the string with + t - object (convertible to std::basic_string_view) to initialize the + string with + rg - a container compatible range + +.SH Complexity + + 1,2) Constant. + 3-8) Linear in count. + 9) Linear in length of s. + 10) Linear in distance between first and last. + 11,12) Linear in size of other. + 13) Constant. + 14) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 15) Linear in size of ilist. + 16) Linear in size of t. + 17) Linear in size of assigned substring, i.e. std::min(std::size(t) - pos, n). + 19) Linear in size of rg. + +.SH Exceptions + + 4-7) std::out_of_range if pos > other.size(). + 13) Throws nothing. + 14) Throws nothing if alloc == str.get_allocator(). + 17) std::out_of_range if pos is out of range. + + Throws std::length_error if the length of the constructed string would exceed + max_size() (for example, if count > max_size() for \fB(3)\fP). Calls to + Allocator::allocate may throw. + + If an exception is thrown for any reason, these functions have no effect (strong + exception safety guarantee). + +.SH Notes + + Initialization with a string literal that contains embedded '\\0' characters uses the + overload \fB(9)\fP, which stops at the first null character. This can be avoided by + specifying a different constructor or by using operator""s: + + std::string s1 = "ab\\0\\0cd"; // s1 contains "ab" + std::string s2{"ab\\0\\0cd", 6}; // s2 contains "ab\\0\\0cd" + std::string s3 = "ab\\0\\0cd"s; // s3 contains "ab\\0\\0cd" + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Tagged constructor \fB(19)\fP to construct + from container compatible range + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + std::cout << "1) string(); "; + std::string s1; + assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); + std::cout << "s1.capacity(): " << s1.capacity() << '\\n'; // unspecified + + std::cout << "2) string(size_type count, CharT ch): "; + std::string s2(4, '='); + std::cout << std::quoted(s2) << '\\n'; // "====" + + std::cout << "3) string(const string& other, size_type pos, size_type count): "; + std::string const other3("Exemplary"); + std::string s3(other3, 0, other3.length() - 1); + std::cout << std::quoted(s3) << '\\n'; // "Exemplar" + + std::cout << "4) string(const string& other, size_type pos): "; + std::string const other4("Mutatis Mutandis"); + std::string s4(other4, 8); + std::cout << std::quoted(s4) << '\\n'; // "Mutandis", i.e. [8, 16) + + std::cout << "5) string(CharT const* s, size_type count): "; + std::string s5("C-style string", 7); + std::cout << std::quoted(s5) << '\\n'; // "C-style", i.e. [0, 7) + + std::cout << "6) string(CharT const* s): "; + std::string s6("C-style\\0string"); + std::cout << std::quoted(s6) << '\\n'; // "C-style" + + std::cout << "7) string(InputIt first, InputIt last): "; + char mutable_c_str[] = "another C-style string"; + std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); + std::cout << std::quoted(s7) << '\\n'; // "C-style string" + + std::cout << "8) string(string&): "; + std::string const other8("Exemplar"); + std::string s8(other8); + std::cout << std::quoted(s8) << '\\n'; // "Exemplar" + + std::cout << "9) string(string&&): "; + std::string s9(std::string("C++ by ") + std::string("example")); + std::cout << std::quoted(s9) << '\\n'; // "C++ by example" + + std::cout << "a) string(std::initializer_list): "; + std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); + std::cout << std::quoted(sa) << '\\n'; // "C-style" + + // before C++11, overload resolution selects string(InputIt first, InputIt last) + // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) + // after C++11 the InputIt constructor is disabled for integral types and calls: + std::cout << "b) string(size_type count, CharT ch) is called: "; + std::string sb(3, std::toupper('a')); + std::cout << std::quoted(sb) << '\\n'; // "AAA" + + // std::string sc(nullptr); // Before C++23: throws std::logic_error + // Since C++23: won't compile, see overload (18) + // std::string sc(0); // Same as above, as literal 0 is a null pointer constant + + auto const range = {0x43, 43, 43}; + #ifdef __cpp_lib_containers_ranges + std::string sc(std::from_range, range); // tagged constructor (19) + std::cout << "c) string(std::from_range, range) is called: "; + #else + std::string sc(range.begin(), range.end()); // fallback to overload (12) + std::cout << "c) string(range.begin(), range.end()) is called: "; + #endif + std::cout << std::quoted(sc) << '\\n'; // "C++" + } + +.SH Possible output: + + 1) string(); s1.capacity(): 15 + 2) string(size_type count, CharT ch): "====" + 3) string(const string& other, size_type pos, size_type count): "Exemplar" + 4) string(const string& other, size_type pos): "Mutandis" + 5) string(CharT const* s, size_type count): "C-style" + 6) string(CharT const* s): "C-style" + 7) string(InputIt first, InputIt last): "C-style string" + 8) string(string&): "Exemplar" + 9) string(string&&): "C++ by example" + a) string(std::initializer_list): "C-style" + b) string(size_type count, CharT ch) is called: "AAA" + c) string(std::from_range, range) is called: "C++" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overload \fB(10)\fP did not use the + LWG 301 C++98 parameter use that parameter + alloc if InputIt is an integral + type + LWG 847 C++98 there was no exception safety added strong exception safety + guarantee guarantee + LWG 2193 C++11 the default constructor is made non-explicit + explicit + there is no way to supply an there is a constructor for + LWG 2583 C++98 allocator basic_string(str, pos, alloc) + for basic_string(str, pos) + LWG 2946 C++17 overload \fB(16)\fP causes ambiguity in avoided by making it a + some cases template + two constructors may cause + LWG 3076 C++17 ambiguities constrained + in class template argument + deduction + +.SH See also + + assign assign characters to a string + \fI(public member function)\fP + operator= assigns values to the string + \fI(public member function)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP + constructs a basic_string_view + constructor \fI(public member function of std::basic_string_view)\fP + diff --git a/man/std::wstring::~basic_string.3 b/man/std::wstring::~basic_string.3 new file mode 100644 index 000000000..631cdb44e --- /dev/null +++ b/man/std::wstring::~basic_string.3 @@ -0,0 +1,13 @@ +.TH std::basic_string::~basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string::~basic_string \- std::basic_string::~basic_string + +.SH Synopsis + ~basic_string(); (constexpr since C++20) + + Destructs the basic_string. The destructors of the elements are called and the used + storage is deallocated. + +.SH Complexity + + Typically constant (formally linear). diff --git a/man/std::wstring_convert.3 b/man/std::wstring_convert.3 index 88b23c167..7c1d4ae5d 100644 --- a/man/std::wstring_convert.3 +++ b/man/std::wstring_convert.3 @@ -1,19 +1,23 @@ -.TH std::wstring_convert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert \- std::wstring_convert + .SH Synopsis Defined in header - template< class Codecvt, + template< - class Elem = wchar_t, - class Wide_alloc = std::allocator, \fI(since C++11)\fP - class Byte_alloc = std::allocator > + class Codecvt, \fI(since C++11)\fP + class Elem = wchar_t, (deprecated in C++17) + class Wide_alloc = std::allocator, (removed in C++26) + class Byte_alloc = std::allocator - class wstring_convert; + > class wstring_convert; Class template std::wstring_convert performs conversions between byte string std::string and wide string std::basic_string, using an individual code conversion facet Codecvt. std::wstring_convert assumes ownership of the conversion facet, and cannot use a facet managed by a locale. The standard facets suitable for - use with std::wstring_convert are std::codecvt_utf8 for UTF-8/UCS2 and UTF-8/UCS4 + use with std::wstring_convert are std::codecvt_utf8 for UTF-8/UCS-2 and UTF-8/UCS-4 conversions and std::codecvt_utf8_utf16 for UTF-8/UTF-16 conversions. .SH Member types @@ -27,44 +31,48 @@ .SH Member functions constructor constructs a new wstring_convert - \fI(public member function)\fP + \fI(public member function)\fP operator= the copy assignment operator is deleted \fI(public member function)\fP destructor destructs the wstring_convert and its conversion facet - \fI(public member function)\fP + \fI(public member function)\fP from_bytes converts a byte string into a wide string - \fI(public member function)\fP + \fI(public member function)\fP to_bytes converts a wide string into a byte string - \fI(public member function)\fP + \fI(public member function)\fP converted returns the number of characters successfully converted - \fI(public member function)\fP + \fI(public member function)\fP state returns the current conversion state - \fI(public member function)\fP + \fI(public member function)\fP .SH See also - Character narrow multibyte UTF-8 UTF-16 - conversions (char) (char) (char16_t) - codecvt - UTF-16 c16rtomb codecvt_utf8_utf16 N/A - codecvt_utf8_utf16 - codecvt_utf8_utf16 - UCS2 No codecvt_utf8 codecvt_utf16 - UTF-32/UCS4 mbrtoc32 / codecvt codecvt_utf16 - codecvt_utf8 - UCS2/UCS4 No codecvt_utf8 codecvt_utf16 - (wchar_t) - codecvt No No - (wchar_t) mbsrtowcs / - wcsrtombs + Character locale-defined multibyte UTF-8 UTF-16 + conversions (UTF-8, GB18030) + codecvt + UTF-16 mbrtoc16 / c16rtomb (with C11's codecvt_utf8_utf16 N/A + DR488) codecvt_utf8_utf16 + codecvt_utf8_utf16 + UCS-2 c16rtomb (without C11's DR488) codecvt_utf8 codecvt_utf16 + UTF-32 mbrtoc32 / c32rtomb codecvt codecvt_utf16 + codecvt_utf8 + system + wchar_t: + mbsrtowcs / wcsrtombs + UTF-32 use_facet codecvt_utf16 +(non-Windows) >(locale) + UCS-2 + (Windows) - wbuffer_convert performs conversion between a byte stream buffer and a wide - \fI(C++11)\fP stream buffer - \fI(class template)\fP - codecvt_utf8 converts between UTF-8 and UCS2/UCS4 - \fI(C++11)\fP \fI(class template)\fP - codecvt_utf8_utf16 converts between UTF-8 and UTF-16 - \fI(C++11)\fP \fI(class template)\fP + wbuffer_convert performs conversion between a byte stream buffer and a wide + \fI(C++11)\fP stream buffer + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8 + \fI(C++11)\fP converts between UTF-8 and UCS-2/UCS-4 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) + codecvt_utf8_utf16 + \fI(C++11)\fP converts between UTF-8 and UTF-16 + (deprecated in C++17) \fI(class template)\fP + (removed in C++26) diff --git a/man/std::wstring_convert::converted.3 b/man/std::wstring_convert::converted.3 index 87cba44b8..47884d848 100644 --- a/man/std::wstring_convert::converted.3 +++ b/man/std::wstring_convert::converted.3 @@ -1,7 +1,10 @@ -.TH std::wstring_convert::converted 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert::converted 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert::converted \- std::wstring_convert::converted + .SH Synopsis Defined in header - std::size_t converted() const; + std::size_t converted() const noexcept; Returns the number of source characters that were processed by the most recent from_bytes() or to_bytes(). @@ -10,31 +13,25 @@ The number of characters consumed by the most recent conversion operation. -.SH Exceptions - - \fI(none)\fP \fI(until C++14)\fP - noexcept specification: - noexcept \fI(since C++14)\fP - - .SH Example - + // Run this code + #include #include - #include #include - #include + #include + int main() { - std::string utf8 = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + std::string utf8 = "z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; std::cout << "original UTF-8 string size: " << utf8.size() << '\\n'; - + // the UTF-8 - UTF-32 standard conversion facet std::wstring_convert, char32_t> cvt; - + // UTF-8 to UTF-32 std::u32string utf32 = cvt.from_bytes(utf8); std::cout << "UTF-32 string size: " << utf32.size() << '\\n'; @@ -53,9 +50,18 @@ new UTF-8 string size: 10 converted() == 4 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2174 C++11 wstring_convert::converted was not required to required + be noexcept + .SH See also to_bytes converts a wide string into a byte string - \fI(public member function)\fP + \fI(public member function)\fP from_bytes converts a byte string into a wide string - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::wstring_convert::from_bytes.3 b/man/std::wstring_convert::from_bytes.3 index 784029854..aa3880ae6 100644 --- a/man/std::wstring_convert::from_bytes.3 +++ b/man/std::wstring_convert::from_bytes.3 @@ -1,27 +1,27 @@ -.TH std::wstring_convert::from_bytes 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert::from_bytes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert::from_bytes \- std::wstring_convert::from_bytes + .SH Synopsis Defined in header - wide_string from_bytes( char byte ); \fB(1)\fP - wide_string from_bytes( const char* ptr ); \fB(2)\fP - wide_string from_bytes( const byte_string& str ); \fB(3)\fP - wide_string from_bytes( const char* first, const char* last); \fB(4)\fP + wide_string from_bytes( char byte ); \fB(1)\fP + wide_string from_bytes( const char* ptr ); \fB(2)\fP + wide_string from_bytes( const byte_string& str ); \fB(3)\fP + wide_string from_bytes( const char* first, const char* last ); \fB(4)\fP Performs multibyte to wide conversion, using the codecvt facet supplied at construction. - 1) Converts byte as if it was a string of length 1 to wide_string - + 1) Converts byte as if it was a string of length 1 to wide_string. 2) Converts the null-terminated multibyte character sequence beginning at the - character pointed to by ptr to wide_string - + character pointed to by ptr to wide_string. 3) Converts the narrow string str to wide_string. - - 4) Converts the narrow multibyte character sequence [first, last) to wide_string + 4) Converts the narrow multibyte character sequence [first, last) to wide_string. In all cases, the conversion begins in initial shift state, unless non-initial starting state was provided to this wstring_convert constructor. The number of characters converted and the final value of the conversion state are remembered and - can be accessed with state() and converted() + can be accessed with state() and converted(). .SH Return value @@ -36,53 +36,49 @@ .SH Example - + // Run this code + #include + #include #include - #include #include - #include - + #include + int main() { - std::string utf8 = u8"z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" - // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; - + std::string utf8 = "z\\u00df\\u6c34\\U0001d10b"; // or u8"zß水𝄋" + // or "\\x7a\\xc3\\x9f\\xe6\\xb0\\xb4\\xf0\\x9d\\x84\\x8b"; + // the UTF-8 / UTF-16 standard conversion facet - std::wstring_convert, char16_t> utf16conv; - std::u16string utf16 = utf16conv.from_bytes(utf8.data()); - std::cout << "UTF16 conversion produced " << utf16.size() << " code points:\\n"; + std::u16string utf16 = std::wstring_convert< + std::codecvt_utf8_utf16, char16_t>{}.from_bytes(utf8.data()); + std::cout << "UTF-16 conversion produced " << utf16.size() + << " code units: " << std::showbase; for (char16_t c : utf16) - std::cout << std::hex << std::showbase << c << '\\n'; - + std::cout << std::hex << static_cast(c) << ' '; + // the UTF-8 / UTF-32 standard conversion facet - std::wstring_convert, char32_t> utf32conv; - std::u32string utf32 = utf32conv.from_bytes(utf8); - std::cout << "UTF32 conversion produced " << std::dec << utf32.size() << " code points:\\n"; + std::u32string utf32 = std::wstring_convert< + std::codecvt_utf8, char32_t>{}.from_bytes(utf8); + std::cout << "\\nUTF-32 conversion produced " << std::dec + << utf32.size() << " code units: "; for (char32_t c : utf32) - std::cout << std::hex << std::showbase << c << '\\n'; + std::cout << std::hex << static_cast(c) << ' '; + std::cout << '\\n'; } .SH Output: - UTF16 conversion produced 5 code points: - 0x7a - 0xdf - 0x6c34 - 0xd834 - 0xdd0b - UTF32 conversion produced 4 code points: - 0x7a - 0xdf - 0x6c34 - 0x1d10b + UTF-16 conversion produced 5 code units: 0x7a 0xdf 0x6c34 0xd834 0xdd0b + UTF-32 conversion produced 4 code units: 0x7a 0xdf 0x6c34 0x1d10b .SH See also to_bytes converts a wide string into a byte string - \fI(public member function)\fP + \fI(public member function)\fP mbsrtowcs converts a narrow multibyte character string to wide string, given state - \fI(function)\fP - do_in converts a string from externT to internT, such as when reading from file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_in converts a string from ExternT to InternT, such as when reading from file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) diff --git a/man/std::wstring_convert::state.3 b/man/std::wstring_convert::state.3 index 5020f2f2c..69c776874 100644 --- a/man/std::wstring_convert::state.3 +++ b/man/std::wstring_convert::state.3 @@ -1,4 +1,7 @@ -.TH std::wstring_convert::state 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert::state 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert::state \- std::wstring_convert::state + .SH Synopsis Defined in header state_type state() const; @@ -19,12 +22,11 @@ .SH See also to_bytes converts a wide string into a byte string - \fI(public member function)\fP + \fI(public member function)\fP from_bytes converts a byte string into a wide string - \fI(public member function)\fP - mbsinit checks if the mbstate_t object represents initial shift state - \fI(function)\fP + \fI(public member function)\fP + mbsinit checks if the std::mbstate_t object represents initial shift state + \fI(function)\fP .SH Category: - * Todo no example diff --git a/man/std::wstring_convert::to_bytes.3 b/man/std::wstring_convert::to_bytes.3 index 2f5b6d7f8..f63dc0e8b 100644 --- a/man/std::wstring_convert::to_bytes.3 +++ b/man/std::wstring_convert::to_bytes.3 @@ -1,10 +1,13 @@ -.TH std::wstring_convert::to_bytes 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert::to_bytes 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert::to_bytes \- std::wstring_convert::to_bytes + .SH Synopsis Defined in header - byte_string to_bytes( Elem wchar ); \fB(1)\fP - byte_string to_bytes( const Elem* wptr ); \fB(2)\fP - byte_string to_bytes( const wide_string& wstr ); \fB(3)\fP - byte_string to_bytes( const Elem* first, const Elem* last); \fB(4)\fP + byte_string to_bytes( Elem wchar ); \fB(1)\fP + byte_string to_bytes( const Elem* wptr ); \fB(2)\fP + byte_string to_bytes( const wide_string& wstr ); \fB(3)\fP + byte_string to_bytes( const Elem* first, const Elem* last ); \fB(4)\fP Performs wide to multibyte conversion, using the codecvt facet supplied at construction. @@ -12,13 +15,13 @@ 1) Converts wchar as if it was a string of length 1, to byte_string. 2) Converts the null-terminated wide character sequence beginning at the wide character pointed to by wptr, to byte_string. - 3) Converts the wide string str to byte_string. + 3) Converts the wide string wstr to byte_string. 4) Converts the wide character sequence [first, last) to byte_string. In all cases, the conversion begins in initial shift state, unless non-initial starting state was provided to this wstring_convert constructor. The number of characters converted and the final value of the conversion state are remembered and - can be accessed with state() and converted() + can be accessed with state() and converted(). .SH Return value @@ -33,35 +36,35 @@ .SH Example - + // Run this code - #include - #include - #include #include #include - + #include + #include + #include + // utility function for output void hex_print(const std::string& s) { std::cout << std::hex << std::setfill('0'); - for(unsigned char c : s) + for (unsigned char c : s) std::cout << std::setw(2) << static_cast(c) << ' '; std::cout << std::dec << '\\n'; } - + int main() { // wide character data - std::wstring wstr = L"z\\u00df\\u6c34\\U0001d10b"; // or L"zß水𝄋" - + std::wstring wstr = L"z\\u00df\\u6c34\\U0001f34c"; // or L"zß水🍌" + // wide to UTF-8 std::wstring_convert> conv1; std::string u8str = conv1.to_bytes(wstr); std::cout << "UTF-8 conversion produced " << u8str.size() << " bytes:\\n"; hex_print(u8str); - + // wide to UTF-16le std::wstring_convert> conv2; std::string u16str = conv2.to_bytes(wstr); @@ -72,15 +75,16 @@ .SH Output: UTF-8 conversion produced 10 bytes: - 7a c3 9f e6 b0 b4 f0 9d 84 8b + 7a c3 9f e6 b0 b4 f0 9f 8d 8c UTF-16le conversion produced 10 bytes: - 7a 00 df 00 34 6c 34 d8 0b dd + 7a 00 df 00 34 6c 3c d8 4c df .SH See also from_bytes converts a byte string into a wide string - \fI(public member function)\fP + \fI(public member function)\fP wcsrtombs converts a wide string to narrow multibyte character string, given state - \fI(function)\fP - do_out converts a string from internT to externT, such as when writing to file - \fB[virtual]\fP \fI(virtual protected member function of std::codecvt)\fP + \fI(function)\fP + do_out converts a string from InternT to ExternT, such as when writing to file + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::codecvt) diff --git a/man/std::wstring_convert::wstring_convert.3 b/man/std::wstring_convert::wstring_convert.3 index 3862298d4..1e9a94baa 100644 --- a/man/std::wstring_convert::wstring_convert.3 +++ b/man/std::wstring_convert::wstring_convert.3 @@ -1,20 +1,25 @@ -.TH std::wstring_convert::wstring_convert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert::wstring_convert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert::wstring_convert \- std::wstring_convert::wstring_convert + .SH Synopsis - explicit wstring_convert( Codecvt* pcvt = new Codecvt ); \fB(1)\fP - wstring_convert( Codecvt* pcvt, state_type state); \fB(2)\fP + wstring_convert() : wstring_convert( new Codecvt ) {} \fB(1)\fP + explicit wstring_convert( Codecvt* pcvt ); \fB(2)\fP + wstring_convert( Codecvt* pcvt, state_type state ); \fB(3)\fP explicit wstring_convert( const byte_string& byte_err, - const wide_string& wide_err = \fB(3)\fP + const wide_string& wide_err = \fB(4)\fP wide_string() ); - wstring_convert(const std::wstring_convert&) = delete; \fB(4)\fP \fI(since C++14)\fP + wstring_convert( const std::wstring_convert& ) = delete; \fB(5)\fP \fI(since C++14)\fP - 1) Constructs the wstring_convert object with a specified conversion facet, using - default-constructed values for the shift state and the error strings - 2) Constructs the wstring_convert object with a specified conversion facet and - specified shift state, using default-constructed values for the error strings - 3) Constructs the wstring_convert object with specified error strings, using new + 1) Default constructor. + 2) Constructs the wstring_convert object with a specified conversion facet, using + default-constructed values for the shift state and the error strings. + 3) Constructs the wstring_convert object with a specified conversion facet and + specified shift state, using default-constructed values for the error strings. + 4) Constructs the wstring_convert object with specified error strings, using new Codecvt as the conversion facet and the default-constructed state_type as shift state. - 4) The copy constructor is deleted, wstring_convert is not CopyConstructible + 5) The copy constructor is deleted, wstring_convert is not CopyConstructible. .SH Parameters @@ -24,34 +29,41 @@ byte_err - narrow string to display on errors wide_err - wide string to display on errors + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit + .SH Example - + // Run this code + #include #include #include - #include - + // utility wrapper to adapt locale-bound facets for wstring/wbuffer convert template struct deletable_facet : Facet { - template - deletable_facet(Args&& ...args) : Facet(std::forward(args)...) {} + using Facet::Facet; // inherit constructors ~deletable_facet() {} }; - + int main() { // UTF-16le / UCS4 conversion std::wstring_convert< - std::codecvt_utf16 + std::codecvt_utf16 > u16to32; - + // UTF-8 / wide string conversion with custom messages std::wstring_convert> u8towide("Error!", L"Error!"); - + // GB18030 / wide string conversion facet typedef deletable_facet> F; std::wstring_convert gbtowide(new F("zh_CN.gb18030")); diff --git a/man/std::wstring_convert::~wstring_convert.3 b/man/std::wstring_convert::~wstring_convert.3 index 484b51fbf..397b7a3fb 100644 --- a/man/std::wstring_convert::~wstring_convert.3 +++ b/man/std::wstring_convert::~wstring_convert.3 @@ -1,4 +1,7 @@ -.TH std::wstring_convert::~wstring_convert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::wstring_convert::~wstring_convert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::wstring_convert::~wstring_convert \- std::wstring_convert::~wstring_convert + .SH Synopsis ~wstring_convert(); @@ -8,18 +11,18 @@ Some implementations are able to delete any facet, including the locale-specific facets with protected destructors. Other implementations require the facet to have a - public destructor, similar to the the locale-independent facets from . This - is LWG issue 721 + public destructor, similar to the locale-independent facets from . This is + LWG issue 721. .SH Example - + // Run this code + #include #include #include - #include - + // utility wrapper to adapt locale-bound facets for wstring/wbuffer convert template struct deletable_facet : Facet @@ -28,14 +31,15 @@ deletable_facet(Args&& ...args) : Facet(std::forward(args)...) {} ~deletable_facet() {} }; - + int main() { // GB18030 / UCS4 conversion, using locale-based facet directly // typedef std::codecvt_byname gbfacet_t; - // Compiler error: "calling a protected destructor of codecvt_byname<> in ~wstring_convert" + // Compiler error: "calling a protected destructor of + // codecvt_byname<> in ~wstring_convert" // std::wstring_convert gbto32(new gbfacet_t("zh_CN.gb18030")); - + // GB18030 / UCS4 conversion facet using a facet with public destructor typedef deletable_facet> gbfacet_t; std::wstring_convert gbto32(new gbfacet_t("zh_CN.gb18030")); diff --git a/man/std::wstring_view.3 b/man/std::wstring_view.3 new file mode 100644 index 000000000..df2b6eb62 --- /dev/null +++ b/man/std::wstring_view.3 @@ -0,0 +1,277 @@ +.TH std::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view \- std::basic_string_view + +.SH Synopsis + Defined in header + template< + + class CharT, \fI(since C++17)\fP + class Traits = std::char_traits + + > class basic_string_view; + + The class template basic_string_view describes an object that can refer to a + constant contiguous sequence of CharT with the first element of the sequence at + position zero. + + For a basic_string_view str, pointers, iterators, and references to elements of str + are invalidated when an operation invalidates a pointer in the range + [str.data(), str.data() + str.size()). + + Every specialization of std::basic_string_view is a TriviallyCopyable (since C++23) + type. + + A typical implementation holds only two members: a pointer to constant CharT and a + size. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::string_view \fI(C++17)\fP std::basic_string_view + std::wstring_view \fI(C++17)\fP std::basic_string_view + std::u8string_view (C++20) std::basic_string_view + std::u16string_view \fI(C++17)\fP std::basic_string_view + std::u32string_view \fI(C++17)\fP std::basic_string_view + +.SH Template parameters + + CharT - character type + CharTraits class specifying the operations on the character type. Like for + Traits - std::basic_string, Traits::char_type must name the same type as CharT or + the program is ill-formed. + + Nested types + + Nested type Definition + traits_type Traits + value_type CharT + pointer CharT* + const_pointer const CharT* + reference CharT& + const_reference const CharT& + implementation-defined constant LegacyRandomAccessIterator, + + const_iterator and LegacyContiguousIterator \fI(until C++20)\fP + ConstexprIterator, and contiguous_iterator \fI(since C++20)\fP + + whose value_type is CharT + iterator const_iterator + const_reverse_iterator std::reverse_iterator + reverse_iterator const_reverse_iterator + size_type std::size_t + difference_type std::ptrdiff_t + + Note: iterator and const_iterator are the same type because string views are views + into constant character sequences. + + All requirements on the iterator types of a Container applies to the iterator and + const_iterator types of basic_string_view as well. + +.SH Member functions + + Constructors and assignment + constructor constructs a basic_string_view + \fI(public member function)\fP + operator= assigns a view + \fI(public member function)\fP +.SH Iterators + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function)\fP +.SH Element access + operator[] accesses the specified character + \fI(public member function)\fP + at accesses the specified character with bounds checking + \fI(public member function)\fP + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a view + \fI(public member function)\fP +.SH Capacity + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP +.SH Modifiers + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP + swap swaps the contents + \fI(public member function)\fP +.SH Operations + copy copies characters + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + contains checks if the string view contains the given substring or + (C++23) character + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP +.SH Constants + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI(public static member constant)\fP + +.SH Non-member functions + + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) +.SH Input/output + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + +.SH Literals + + Defined in inline namespace std::literals::string_view_literals + operator""sv creates a string view of a character array literal + \fI(C++17)\fP \fI(function)\fP + +.SH Helper classes + + std::hash + std::hash + std::hash + std::hash + std::hash hash support for string views + \fI(C++17)\fP \fI(class template specialization)\fP + \fI(C++17)\fP + (C++20) + \fI(C++17)\fP + \fI(C++17)\fP + + Helper templates + + template< class CharT, class Traits > + + inline constexpr bool (since + C++20) + ranges::enable_borrowed_range> = + true; + + This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy + borrowed_range. + + template< class CharT, class Traits > + + inline constexpr bool \fI(since C++20)\fP + + ranges::enable_view> = + true; + + This specialization of ranges::enable_view makes basic_string_view satisfy view. + + Deduction guides \fI(since C++20)\fP + +.SH Notes + + It is the programmer's responsibility to ensure that std::string_view does not + outlive the pointed-to character array: + + std::string_view good{"a string literal"}; + // "Good" case: `good` points to a static array. + // String literals reside in persistent data storage. + + std::string_view bad{"a temporary string"s}; + // "Bad" case: `bad` holds a dangling pointer since the std::string temporary, + // created by std::operator""s, will be destroyed at the end of the statement. + + Specializations of std::basic_string_view are already trivially copyable types in + all existing implementations, even before the formal requirement introduced in + C++23. + + Feature-test macro Value Std Feature + __cpp_lib_string_view 201606L \fI(C++17)\fP std::string_view + 201803L (C++20) ConstexprIterator + __cpp_lib_string_contains 202011L (C++23) contains + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view unicode[]{"▀▄─", "▄▀─", "▀─▄", "▄─▀"}; + + for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4)) + { + for (int x{}; x != 16; ++x) + std::cout << unicode[p]; + std::cout << '\\n'; + } + } + +.SH Output: + + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ + ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀ + ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ + ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + only pointers, iterators, and all pointers, iterators, and + references references + LWG 3203 C++17 returned from the member functions to elements of + of basic_string_view + basic_string_view might be may be invalidated + invalidated + +.SH See also + + basic_string stores and manipulates sequences of characters + \fI(class template)\fP + span a non-owning view over a contiguous sequence of objects + (C++20) \fI(class template)\fP + initializer_list creates a temporary array in list-initialization and then + \fI(C++11)\fP references it + \fI(class template)\fP diff --git a/man/std::wstring_view::at.3 b/man/std::wstring_view::at.3 new file mode 100644 index 000000000..65f8fa91d --- /dev/null +++ b/man/std::wstring_view::at.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::at \- std::basic_string_view::at + +.SH Synopsis + constexpr const_reference at( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. Bounds + checking is performed, exception of type std::out_of_range will be thrown on invalid + access. + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Throws std::out_of_range if pos >= size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string_view str_view("abcdef"); + + try + { + for (std::size_t i = 0; true; ++i) + std::cout << i << ": " << str_view.at(i) << '\\n'; + } + catch (const std::out_of_range& e) + { + std::cout << "Whooops. Index is out of range.\\n"; + std::cout << e.what() << '\\n'; + } + } + +.SH Possible output: + + 0: a + 1: b + 2: c + 3: d + 4: e + 5: f + 6: Whooops. Index is out of range. + basic_string_view::at: __pos (which is 6) >= this->size() (which is 6) + +.SH See also + + operator[] accesses the specified character + \fI(public member function)\fP + accesses the specified character with bounds checking + at \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::back.3 b/man/std::wstring_view::back.3 new file mode 100644 index 000000000..7fd79d7b3 --- /dev/null +++ b/man/std::wstring_view::back.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::back 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::back \- std::basic_string_view::back + +.SH Synopsis + constexpr const_reference back() const; \fI(since C++17)\fP + + Returns reference to the last character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the last character, equivalent to operator[](size() - 1). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_suffix(1)) + std::cout << str.back() << ' ' << str << '\\n'; + } + +.SH Output: + + F ABCDEF + E ABCDE + D ABCD + C ABC + B AB + A A + +.SH See also + + front accesses the first character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + back accesses the last character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::wstring_view::basic_string_view.3 b/man/std::wstring_view::basic_string_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::wstring_view::basic_string_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::begin,std::basic_string_view::cbegin.3 b/man/std::wstring_view::begin,std::basic_string_view::cbegin.3 new file mode 100644 index 000000000..83667f3e5 --- /dev/null +++ b/man/std::wstring_view::begin,std::basic_string_view::cbegin.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::begin,std::basic_string_view::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::begin,std::basic_string_view::cbegin \- std::basic_string_view::begin,std::basic_string_view::cbegin + +.SH Synopsis + constexpr const_iterator begin() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cbegin() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the first character of the view. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + + constexpr auto begin = str_view.begin(); + constexpr auto cbegin = str_view.cbegin(); + static_assert( + *begin == 'a' and + *cbegin == 'a' and + *begin == *cbegin and + begin == cbegin and + std::same_as); + } + +.SH See also + + end returns an iterator to the end + cend \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::wstring_view::compare.3 b/man/std::wstring_view::compare.3 new file mode 100644 index 000000000..8087ec4ef --- /dev/null +++ b/man/std::wstring_view::compare.3 @@ -0,0 +1,95 @@ +.TH std::basic_string_view::compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::compare \- std::basic_string_view::compare + +.SH Synopsis + constexpr int compare( basic_string_view v ) const noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(2)\fP \fI(since C++17)\fP + basic_string_view v ) const; + constexpr int compare( size_type pos1, size_type count1, + basic_string_view v, \fB(3)\fP \fI(since C++17)\fP + size_type pos2, size_type count2 ) const; + constexpr int compare( const CharT* s ) const; \fB(4)\fP \fI(since C++17)\fP + constexpr int compare( size_type pos1, size_type count1, \fB(5)\fP \fI(since C++17)\fP + const CharT* s ) const; + constexpr int compare( size_type pos1, size_type count1, \fB(6)\fP \fI(since C++17)\fP + const CharT* s, size_type count2 ) const; + + Compares two character sequences. + + 1) The length rlen of the sequences to compare is the smaller of size() and + v.size(). The function compares the two views by calling traits::compare(data(), + v.data(), rlen), and returns a value according to the following table: + + Condition Result Return value + Traits::compare(data(), v.data(), rlen) < 0 this is less < 0 + than v + size() < this is less < 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) == 0 size() == this is equal to 0 + v.size() v + size() > this is greater > 0 + v.size() than v + Traits::compare(data(), v.data(), rlen) > 0 this is greater > 0 + than v + + 2) Equivalent to substr(pos1, count1).compare(v). + 3) Equivalent to substr(pos1, count1).compare(v.substr(pos2, count2)). + 4) Equivalent to compare(basic_string_view(s)). + 5) Equivalent to substr(pos1, count1).compare(basic_string_view(s)). + 6) Equivalent to substr(pos1, count1).compare(basic_string_view(s, count2)). + +.SH Parameters + + v - view to compare + s - pointer to the character string to compare to + count1 - number of characters of this view to compare + pos1 - position of the first character in this view to compare + count2 - number of characters of the given view to compare + pos2 - position of the first character of the given view to compare + +.SH Return value + + Negative value if this view is less than the other character sequence, zero if the + both character sequences are equal, positive value if this view is greater than the + other character sequence. + +.SH Complexity + + 1) Linear in the number of characters compared. + +.SH Example + + +// Run this code + + #include + + int main() + { + using std::operator""sv; + static_assert("abc"sv.compare("abcd"sv) < 0); + static_assert("abcd"sv.compare("abc"sv) > 0); + static_assert("abc"sv.compare("abc"sv) == 0); + static_assert(""sv.compare(""sv) == 0); + } + +.SH See also + + compares two strings + compare \fI\fI(public member\fP function of\fP + std::basic_string) + operator== + operator!= + operator< + operator> + operator<= + operator>= + operator<=> lexicographically compares two string views + \fI(C++17)\fP \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) diff --git a/man/std::wstring_view::contains.3 b/man/std::wstring_view::contains.3 new file mode 100644 index 000000000..8c655ade3 --- /dev/null +++ b/man/std::wstring_view::contains.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::contains \- std::basic_string_view::contains + +.SH Synopsis + constexpr bool contains( basic_string_view sv ) const noexcept; \fB(1)\fP (since C++23) + constexpr bool contains( CharT c ) const noexcept; \fB(2)\fP (since C++23) + constexpr bool contains( const CharT* s ) const; \fB(3)\fP (since C++23) + + Checks if the string view contains the given substring, where + + 1) the substring is a string view. + 2) the substring is a single character. + 3) the substring is a null-terminated character string. + + All three overloads are equivalent to return find(x) != npos;, where x is the + parameter. + +.SH Parameters + + sv - a string view + c - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view contains the provided substring, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_string_contains 202011L (C++23) contains functions + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + static_assert + ( + // bool contains(basic_string_view x) const noexcept; + "https://cppreference.com"sv.contains("cpp"sv) == true and + "https://cppreference.com"sv.contains("php"sv) == false and + + // bool contains(CharT x) const noexcept; + "C++23"sv.contains('+') == true and + "C++23"sv.contains('-') == false and + + // bool contains(const CharT* x) const; + std::string_view("basic_string_view").contains("string") == true and + std::string_view("basic_string_view").contains("String") == false + ); + + int main() {} + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function)\fP + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::copy.3 b/man/std::wstring_view::copy.3 new file mode 100644 index 000000000..50e77b7be --- /dev/null +++ b/man/std::wstring_view::copy.3 @@ -0,0 +1,88 @@ +.TH std::basic_string_view::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::copy \- std::basic_string_view::copy + +.SH Synopsis + size_type copy( CharT* dest, size_type count, size_type pos \fI(since C++17)\fP + = 0 ) const; (constexpr since C++20) + + Copies the substring [pos, pos + rcount) to the character array pointed to by dest, + where rcount is the smaller of count and size() - pos. + + Equivalent to Traits::copy(dest, data() + pos, rcount). + +.SH Parameters + + dest - pointer to the destination character string + count - requested substring length + pos - position of the first character + +.SH Return value + + Number of characters copied. + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Linear in rcount. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + constexpr std::basic_string_view source{"ABCDEF"}; + std::array dest; + std::size_t count{}, pos{}; + + dest.fill('\\0'); + source.copy(dest.data(), count = 4); // pos = 0 + std::cout << dest.data() << '\\n'; // ABCD + + dest.fill('\\0'); + source.copy(dest.data(), count = 4, pos = 1); + std::cout << dest.data() << '\\n'; // BCDE + + dest.fill('\\0'); + source.copy(dest.data(), count = 42, pos = 2); // ok, count -> 4 + std::cout << dest.data() << '\\n'; // CDEF + + try + { + source.copy(dest.data(), count = 1, pos = 666); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Output: + + ABCD + BCDE + CDEF + basic_string_view::copy: __pos (which is 666) > __size (which is 6) + +.SH See also + + substr returns a substring + \fI(public member function)\fP + copy copies characters + \fI(public member function of std::basic_string)\fP + copy copies a range of elements to a new location + copy_if \fI(function template)\fP + \fI(C++11)\fP + memcpy copies one buffer to another + \fI(function)\fP diff --git a/man/std::wstring_view::data.3 b/man/std::wstring_view::data.3 new file mode 100644 index 000000000..29290d3ff --- /dev/null +++ b/man/std::wstring_view::data.3 @@ -0,0 +1,71 @@ +.TH std::basic_string_view::data 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::data \- std::basic_string_view::data + +.SH Synopsis + constexpr const_pointer data() const noexcept; \fI(since C++17)\fP + + Returns a pointer to the underlying character array. The pointer is such that the + range [data(), data() + size()) is valid and the values in it correspond to the + values of the view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A pointer to the underlying character array. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::data() and string literals, std::basic_string_view::data() + returns a pointer to a buffer that is not necessarily null-terminated, for example a + substring view (e.g. from remove_suffix). Therefore, it is typically a mistake to + pass data() to a routine that takes just a const CharT* and expects a + null-terminated string. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::wstring_view wcstr_v = L"xyzzy"; + std::cout << std::wcslen(wcstr_v.data()) << '\\n'; + // OK: the underlying character array is null-terminated + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, sizeof array); + // std::cout << std::strlen(array_v.data()) << '\\n'; + // error: the underlying character array is not null-terminated + + std::string str(array_v.data(), array_v.size()); // OK + std::cout << std::strlen(str.data()) << '\\n'; + // OK: the underlying character array of a std::string is always null-terminated + } + +.SH Output: + + 5 + 3 + +.SH See also + + front accesses the first character + \fI(public member function)\fP + back accesses the last character + \fI(public member function)\fP + data returns a pointer to the first character of a string + \fI(public member function of std::basic_string)\fP diff --git a/man/std::wstring_view::empty.3 b/man/std::wstring_view::empty.3 new file mode 100644 index 000000000..185b498eb --- /dev/null +++ b/man/std::wstring_view::empty.3 @@ -0,0 +1,70 @@ +.TH std::basic_string_view::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::empty \- std::basic_string_view::empty + +.SH Synopsis + constexpr bool empty() const noexcept; \fI(since C++17)\fP + \fI(until C++20)\fP + [[nodiscard]] constexpr bool empty() const noexcept; \fI(since C++20)\fP + + Checks if the view has no characters, i.e. whether size() == 0. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the view is empty, false otherwise. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP + checks whether the string is empty + empty \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::end,std::basic_string_view::cend.3 b/man/std::wstring_view::end,std::basic_string_view::cend.3 new file mode 100644 index 000000000..465ae8a3e --- /dev/null +++ b/man/std::wstring_view::end,std::basic_string_view::cend.3 @@ -0,0 +1,54 @@ +.TH std::basic_string_view::end,std::basic_string_view::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::end,std::basic_string_view::cend \- std::basic_string_view::end,std::basic_string_view::cend + +.SH Synopsis + constexpr const_iterator end() const noexcept; \fI(since C++17)\fP + constexpr const_iterator cend() const noexcept; \fI(since C++17)\fP + + Returns an iterator to the character following the last character of the view. This + character acts as a placeholder, attempting to access it results in undefined + behavior. + + range-begin-end.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::string_view str_view("abcd"); + constexpr auto end = str_view.end(); + constexpr auto cend = str_view.cend(); + + static_assert + ( + *std::prev(end) == 'd' && 'd' == *std::prev(cend) and end == cend + ); + } + +.SH See also + + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::wstring_view::ends_with.3 b/man/std::wstring_view::ends_with.3 new file mode 100644 index 000000000..ad6eecb60 --- /dev/null +++ b/man/std::wstring_view::ends_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::ends_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::ends_with \- std::basic_string_view::ends_with + +.SH Synopsis + constexpr bool ends_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool ends_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool ends_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view ends with the given suffix, where + + 1) the suffix is a string view. Effectively returns size() >= sv.size() && + compare(size() - sv.size(), npos, sv) == 0. + 2) the suffix is a single character. Effectively returns !empty() && + Traits::eq(back(), ch). + 3) the suffix is a null-terminated character string. Effectively returns + ends_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view ends with the provided suffix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) ends_with( basic_string_view sv ) + && std::string_view("https://cppreference.com").ends_with(".com"sv) == true + && std::string_view("https://cppreference.com").ends_with(".org"sv) == false + + // (2) ends_with( CharT c ) + && std::string_view("C++20").ends_with('0') == true + && std::string_view("C++20").ends_with('3') == false + + // (3) ends_with( const CharT* s ) + && std::string_view("string_view").ends_with("view") == true + && std::string_view("string_view").ends_with("View") == false + ); + } + +.SH See also + + starts_with checks if the string view starts with the given prefix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::wstring_view::find.3 b/man/std::wstring_view::find.3 new file mode 100644 index 000000000..8882c44bb --- /dev/null +++ b/man/std::wstring_view::find.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find \- std::basic_string_view::find + +.SH Synopsis + constexpr size_type find( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type find( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type find( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type find( const CharT* s, size_type pos = 0 ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the first substring equal to the given character sequence. + + 1) Finds the first occurence of v in this view, starting at position pos. + 2) Equivalent to find(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find(basic_string_view(s, count), pos). + 4) Equivalent to find(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring, or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + + constexpr auto str{" long long int;"sv}; + + static_assert( + 1 == str.find("long"sv) && "<- find(v , pos = 0)" && + 6 == str.find("long"sv, 2) && "<- find(v , pos = 2)" && + 0 == str.find(' ') && "<- find(ch, pos = 0)" && + 2 == str.find('o', 1) && "<- find(ch, pos = 1)" && + 2 == str.find("on") && "<- find(s , pos = 0)" && + 6 == str.find("long double", 5, 4) && "<- find(s , pos = 5, count = 4)" + ); + + static_assert(str.npos == str.find("float")); + } + +.SH See also + + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + finds the first occurrence of the given substring + find \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstring_view::find_first_not_of.3 b/man/std::wstring_view::find_first_not_of.3 new file mode 100644 index 000000000..6ad069029 --- /dev/null +++ b/man/std::wstring_view::find_first_not_of.3 @@ -0,0 +1,78 @@ +.TH std::basic_string_view::find_first_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_not_of \- std::basic_string_view::find_first_not_of + +.SH Synopsis + constexpr size_type + find_first_not_of( basic_string_view v, size_type pos = 0 ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_first_not_of( CharT ch, size_type pos = 0 ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_first_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_not_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character not equal to any of the characters in the given character + sequence. + + 1) Finds the first character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_first_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the first character not equal to any of the characters in the given + string, or std::string_view::npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using namespace std::literals; + + int main() + { + static_assert(2 == "BCDEF"sv.find_first_not_of("ABC")); + // ^ + static_assert(4 == "BCDEF"sv.find_first_not_of("ABC", 4)); + // ^ + static_assert(1 == "BCDEF"sv.find_first_not_of('B')); + // ^ + static_assert(3 == "BCDEF"sv.find_first_not_of('D', 2)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first absence of characters + find_first_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstring_view::find_first_of.3 b/man/std::wstring_view::find_first_of.3 new file mode 100644 index 000000000..c6b35518c --- /dev/null +++ b/man/std::wstring_view::find_first_of.3 @@ -0,0 +1,100 @@ +.TH std::basic_string_view::find_first_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_first_of \- std::basic_string_view::find_first_of + +.SH Synopsis + constexpr size_type + find_first_of( basic_string_view v, size_type pos = 0 ) const \fB(1)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_first_of( CharT ch, size_type pos = 0 ) const noexcept; + constexpr size_type + find_first_of( const CharT* s, size_type pos, size_type count \fB(3)\fP \fI(since C++17)\fP + ) const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_first_of( const CharT* s, size_type pos = 0 ) const; + + Finds the first character equal to any of the characters in the given character + sequence. + + 1) Finds the first occurrence of any of the characters of v in this view, starting + at position pos. + 2) Equivalent to find_first_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_first_of(basic_string_view(s, count), pos). + 4) Equivalent to find_first_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the first occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + constexpr bool is_white_space(const char c) + { + return " \\t\\n\\f\\r\\v"sv.find_first_of(c) != N; + }; + + static_assert( + 1 == "alignas"sv.find_first_of("klmn"sv) && + // └─────────────────────────┘ + N == "alignof"sv.find_first_of("wxyz"sv) && + // + 3 == "concept"sv.find_first_of("bcde"sv, /* pos= */ 1) && + // └───────────────────────┘ + N == "consteval"sv.find_first_of("oxyz"sv, /* pos= */ 2) && + // + 6 == "constexpr"sv.find_first_of('x') && + // └─────────────────────┘ + N == "constinit"sv.find_first_of('x') && + // + 6 == "const_cast"sv.find_first_of('c', /* pos= */ 4) && + // └──────────────────────┘ + N == "continue"sv.find_first_of('c', /* pos= */ 42) && + // + 5 == "co_await"sv.find_first_of("cba", /* pos= */ 4) && + // └───────────────────────┘ + 7 == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 2) && + // └────────────────────┘ + N == "decltype"sv.find_first_of("def", /* pos= */ 2, /* count= */ 1) && + // + is_white_space(' ') && is_white_space('\\r') && !is_white_space('\\a') + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find first occurrence of characters + find_first_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstring_view::find_last_not_of.3 b/man/std::wstring_view::find_last_not_of.3 new file mode 100644 index 000000000..1f593444d --- /dev/null +++ b/man/std::wstring_view::find_last_not_of.3 @@ -0,0 +1,79 @@ +.TH std::basic_string_view::find_last_not_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_not_of \- std::basic_string_view::find_last_not_of + +.SH Synopsis + constexpr size_type + find_last_not_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type + find_last_not_of( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos, size_type \fB(3)\fP \fI(since C++17)\fP + count ) const; + constexpr size_type + find_last_not_of( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last character not equal to any of the characters in the given character + sequence. The search considers only the interval [0, pos]. + + 1) Finds the last character not equal to any of the characters of v in this view, + starting at position pos. + 2) Equivalent to find_last_not_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_not_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_not_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of the string of characters to compare + s - pointer to a string of characters to compare + ch - character to compare + +.SH Return value + + Position of the last character not equal to any of the characters in the given + string, or npos if no such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + using std::operator""sv; + + int main() + { + static_assert(1 == "BCDEF"sv.find_last_not_of("DEF")); + // ^ + static_assert(2 == "BCDEFG"sv.find_last_not_of("EFG", 3)); + // ^ + static_assert(2 == "ABBA"sv.find_last_not_of('A')); + // ^ + static_assert(1 == "ABBA"sv.find_last_not_of('A', 1)); + // ^ + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find last absence of characters + find_last_not_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstring_view::find_last_of.3 b/man/std::wstring_view::find_last_of.3 new file mode 100644 index 000000000..0203b94f0 --- /dev/null +++ b/man/std::wstring_view::find_last_of.3 @@ -0,0 +1,92 @@ +.TH std::basic_string_view::find_last_of 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::find_last_of \- std::basic_string_view::find_last_of + +.SH Synopsis + constexpr size_type + find_last_of( basic_string_view v, size_type pos = npos ) \fB(1)\fP \fI(since C++17)\fP + const noexcept; + constexpr size_type \fB(2)\fP \fI(since C++17)\fP + find_last_of( CharT ch, size_type pos = npos ) const noexcept; + constexpr size_type + find_last_of( const CharT* s, size_type pos, size_type count ) \fB(3)\fP \fI(since C++17)\fP + const; + constexpr size_type \fB(4)\fP \fI(since C++17)\fP + find_last_of( const CharT* s, size_type pos = npos ) const; + + Finds the last character equal to one of characters in the given character sequence. + Exact search algorithm is not specified. The search considers only the interval + [0, pos]. If the character is not present in the interval, npos will be returned. + + 1) Finds the last occurence of any of the characters of v in this view, ending at + position pos. + 2) Equivalent to find_last_of(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to find_last_of(basic_string_view(s, count), pos). + 4) Equivalent to find_last_of(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which the search is to finish + count - length of the string of characters to search for + s - pointer to a string of characters to search for + ch - character to search for + +.SH Return value + + Position of the last occurrence of any character of the substring, or npos if no + such character is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert( + 5 == "delete"sv.find_last_of("cdef"sv) && + // └────────────────────┘ + N == "double"sv.find_last_of("fghi"sv) && + // + 0 == "else"sv.find_last_of("bcde"sv, 2 /* pos [0..2]: "els" */) && + // └────────────────────────┘ + N == "explicit"sv.find_last_of("abcd"sv, 4 /* pos [0..4]: "expli" */) && + // + 3 == "extern"sv.find_last_of('e') && + // └────────────────────┘ + N == "false"sv.find_last_of('x') && + // + 0 == "inline"sv.find_last_of('i', 2 /* pos [0..2]: "inl" */) && + // └───────────────────────┘ + N == "mutable"sv.find_last_of('a', 2 /* pos [0..2]: "mut" */) && + // + 3 == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 3 /* "cde" */) && + // └─────────────────────────┘ + N == "namespace"sv.find_last_of("cdef", 3 /* pos [0..3]: "name" */, 2 /* "cd" */) + ); + + int main() {} + +.SH See also + + find find characters in the view + \fI(public member function)\fP + rfind find the last occurrence of a substring + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find last occurrence of characters + find_last_of \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstring_view::front.3 b/man/std::wstring_view::front.3 new file mode 100644 index 000000000..475c3cb67 --- /dev/null +++ b/man/std::wstring_view::front.3 @@ -0,0 +1,53 @@ +.TH std::basic_string_view::front 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::front \- std::basic_string_view::front + +.SH Synopsis + constexpr const_reference front() const; \fI(since C++17)\fP + + Returns reference to the first character in the view. The behavior is undefined if + empty() == true. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reference to the first character, equivalent to operator[]\fB(0)\fP. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (std::string_view str{"ABCDEF"}; !str.empty(); str.remove_prefix(1)) + std::cout << str.front() << ' ' << str << '\\n'; + } + +.SH Output: + + A ABCDEF + B BCDEF + C CDEF + D DEF + E EF + F F + +.SH See also + + back accesses the last character + \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + front accesses the first character + (DR*) \fI(public member function of std::basic_string)\fP diff --git a/man/std::wstring_view::max_size.3 b/man/std::wstring_view::max_size.3 new file mode 100644 index 000000000..c3f42d911 --- /dev/null +++ b/man/std::wstring_view::max_size.3 @@ -0,0 +1,66 @@ +.TH std::basic_string_view::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::max_size \- std::basic_string_view::max_size + +.SH Synopsis + constexpr size_type max_size() const noexcept; \fI(since C++17)\fP + + The largest possible number of char-like objects that can be referred to by a + basic_string_view. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Maximum number of characters. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::cout << std::numeric_limits::max() + << " <- numeric_limits::max()\\n" + << std::string_view{}.max_size() + << " <- string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n" + << std::wstring_view{}.max_size() + << " <- wstring_view::max_size()\\n" + << std::basic_string_view{}.max_size() + << " <- basic_string_view::max_size()\\n"; + } + +.SH Possible output: + + 9223372036854775807 <- numeric_limits::max() + 4611686018427387899 <- string_view::max_size() + 4611686018427387899 <- basic_string_view::max_size() + 2305843009213693949 <- basic_string_view::max_size() + 1152921504606846974 <- wstring_view::max_size() + 1152921504606846974 <- basic_string_view::max_size() + +.SH See also + + size returns the number of characters + length \fI(public member function)\fP + empty checks whether the view is empty + \fI(public member function)\fP + returns the maximum number of characters + max_size \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::npos.3 b/man/std::wstring_view::npos.3 new file mode 100644 index 000000000..c3ba3b575 --- /dev/null +++ b/man/std::wstring_view::npos.3 @@ -0,0 +1,39 @@ +.TH std::basic_string_view::npos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::npos \- std::basic_string_view::npos + +.SH Synopsis + static constexpr size_type npos = size_type(-1); \fI(since C++17)\fP + + This is a special value equal to the maximum value representable by the type + size_type. The exact meaning depends on context, but it is generally used either as + end of view indicator by the functions that expect a view index or as the error + indicator by the functions that return a view index. + +.SH Example + + +// Run this code + + #include + + constexpr bool + contains(std::string_view const what, std::string_view const where) noexcept + { + return std::string_view::npos != where.find(what); + } + + int main() + { + using namespace std::literals; + + static_assert(contains("water", "in a bottle of water")); + static_assert(!contains("wine", "in a bottle of champagne")); + static_assert(""sv.npos == "haystack"sv.find("needle")); + } + +.SH See also + + npos special value. The exact meaning depends on the context + \fB[static]\fP \fI\fI(public static member\fP constant of\fP + std::basic_string) diff --git a/man/std::wstring_view::operator=.3 b/man/std::wstring_view::operator=.3 new file mode 100644 index 000000000..dba80aad4 --- /dev/null +++ b/man/std::wstring_view::operator=.3 @@ -0,0 +1,48 @@ +.TH std::basic_string_view::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator= \- std::basic_string_view::operator= + +.SH Synopsis + constexpr basic_string_view& operator=( const basic_string_view& view \fI(since C++17)\fP + ) noexcept = default; + + Replaces the view with that of view. + +.SH Parameters + + view - view to copy + +.SH Return value + + *this + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view v = "Hello, world"; + v = v.substr(7); + std::cout << v << '\\n'; + } + +.SH Output: + + world + +.SH See also + + constructor constructs a basic_string_view + \fI(public member function)\fP + assigns values to the string + operator= \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::operator[].3 b/man/std::wstring_view::operator[].3 new file mode 100644 index 000000000..c1d7e55fb --- /dev/null +++ b/man/std::wstring_view::operator[].3 @@ -0,0 +1,62 @@ +.TH std::basic_string_view::operator[] 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::operator[] \- std::basic_string_view::operator[] + +.SH Synopsis + constexpr const_reference operator[]( size_type pos ) const; \fI(since C++17)\fP + + Returns a const reference to the character at specified location pos. + + No bounds checking is performed: the behavior is undefined if pos >= size(). + +.SH Parameters + + pos - position of the character to return + +.SH Return value + + Const reference to the requested character. + +.SH Exceptions + + Does not throw. + +.SH Complexity + + Constant. + +.SH Notes + + Unlike std::basic_string::operator[], std::basic_string_view::operator[](size()) has + undefined behavior instead of returning CharT(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string str = "Exemplar"; + std::string_view v = str; + std::cout << v[2] << '\\n'; + // v[2] = 'y'; // Error: cannot modify through a string view + str[2] = 'y'; + std::cout << v[2] << '\\n'; + } + +.SH Output: + + e + y + +.SH See also + + at accesses the specified character with bounds checking + \fI(public member function)\fP + accesses the specified character + operator[] \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::rbegin,.3 b/man/std::wstring_view::rbegin,.3 new file mode 100644 index 000000000..8f17b98bf --- /dev/null +++ b/man/std::wstring_view::rbegin,.3 @@ -0,0 +1,60 @@ +.TH std::basic_string_view::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rbegin, \- std::basic_string_view::rbegin, + +.SH Synopsis + + constexpr const_reverse_iterator rbegin() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crbegin() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the first character of the reversed view. It + corresponds to the last character of the non-reversed view. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the first character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), std::next(str_view.rbegin(), 3), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), std::next(str_view.crbegin(), 3), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fed + fed + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::wstring_view::remove_prefix.3 b/man/std::wstring_view::remove_prefix.3 new file mode 100644 index 000000000..31ef25b47 --- /dev/null +++ b/man/std::wstring_view::remove_prefix.3 @@ -0,0 +1,74 @@ +.TH std::basic_string_view::remove_prefix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_prefix \- std::basic_string_view::remove_prefix + +.SH Synopsis + constexpr void remove_prefix( size_type n ); \fI(since C++17)\fP + + Moves the start of the view forward by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the start of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::literals; + + [[nodiscard("a pure function")]] + constexpr std::size_t count_substrings(std::string_view hive, std::string_view const bee) + { + if (hive.empty() || bee.empty()) + return 0U; + + std::size_t buzz{}; + while (bee.size() <= hive.size()) + { + const auto pos = hive.find(bee); + if (pos == hive.npos) + break; + ++buzz; + hive.remove_prefix(pos + bee.size()); + } + return buzz; + } + + int main() + { + std::string str = " trim me"; + std::string_view v = str; + v.remove_prefix(std::min(v.find_first_not_of(" "), v.size())); + std::cout << "String: '" << str << "'\\n" + << "View : '" << v << "'\\n"; + + constexpr auto hive{"bee buzz bee buzz bee"}; + std::cout << "There are " << count_substrings(hive, "bee") << " bees in this hive.\\n"; + } + +.SH Output: + + String: ' trim me' + View : 'trim me' + There are 3 bees in this hive. + +.SH See also + + remove_suffix shrinks the view by moving its end backward + \fI(public member function)\fP diff --git a/man/std::wstring_view::remove_suffix.3 b/man/std::wstring_view::remove_suffix.3 new file mode 100644 index 000000000..01bee81f3 --- /dev/null +++ b/man/std::wstring_view::remove_suffix.3 @@ -0,0 +1,51 @@ +.TH std::basic_string_view::remove_suffix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::remove_suffix \- std::basic_string_view::remove_suffix + +.SH Synopsis + constexpr void remove_suffix( size_type n ); \fI(since C++17)\fP + + Moves the end of the view back by n characters. + + The behavior is undefined if n > size(). + +.SH Parameters + + n - number of characters to remove from the end of the view + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + char arr[] = {'a', 'b', 'c', 'd', '\\0', '\\0', '\\0'}; + std::string_view v(arr, sizeof arr); + auto trim_pos = v.find('\\0'); + if (trim_pos != v.npos) + v.remove_suffix(v.size() - trim_pos); + std::cout << "Array: '" << arr << "', size=" << sizeof arr << '\\n' + << "View : '" << v << "', size=" << v.size() << '\\n'; + } + +.SH Output: + + Array: 'abcd', size=7 + View : 'abcd', size=4 + +.SH See also + + remove_prefix shrinks the view by moving its start forward + \fI(public member function)\fP diff --git a/man/std::wstring_view::rend,std::basic_string_view::crend.3 b/man/std::wstring_view::rend,std::basic_string_view::crend.3 new file mode 100644 index 000000000..5f201fac0 --- /dev/null +++ b/man/std::wstring_view::rend,std::basic_string_view::crend.3 @@ -0,0 +1,61 @@ +.TH std::basic_string_view::rend,std::basic_string_view::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rend,std::basic_string_view::crend \- std::basic_string_view::rend,std::basic_string_view::crend + +.SH Synopsis + constexpr const_reverse_iterator rend() const noexcept; \fI(since C++17)\fP + constexpr const_reverse_iterator crend() const noexcept; \fI(since C++17)\fP + + Returns a reverse iterator to the character following the last character of the + reversed view. It corresponds to the character preceding the first character of the + non-reversed view. This character acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + const_reverse_iterator to the character following the last character. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::ostream_iterator out_it(std::cout); + std::string_view str_view("abcdef"); + + std::copy(str_view.rbegin(), str_view.rend(), out_it); + *out_it = '\\n'; + + std::copy(str_view.crbegin(), str_view.crend(), out_it); + *out_it = '\\n'; + } + +.SH Output: + + fedcba + fedcba + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + rend returns a reverse iterator to the end + crend \fI(public member function of std::basic_string)\fP + \fI(C++11)\fP diff --git a/man/std::wstring_view::rfind.3 b/man/std::wstring_view::rfind.3 new file mode 100644 index 000000000..684090010 --- /dev/null +++ b/man/std::wstring_view::rfind.3 @@ -0,0 +1,81 @@ +.TH std::basic_string_view::rfind 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::rfind \- std::basic_string_view::rfind + +.SH Synopsis + constexpr size_type rfind( basic_string_view v, size_type pos = \fB(1)\fP \fI(since C++17)\fP + npos ) const noexcept; + constexpr size_type rfind( CharT ch, size_type pos = npos ) const \fB(2)\fP \fI(since C++17)\fP + noexcept; + constexpr size_type rfind( const CharT* s, size_type pos, \fB(3)\fP \fI(since C++17)\fP + size_type count ) const; + constexpr size_type rfind( const CharT* s, size_type pos = npos ) \fB(4)\fP \fI(since C++17)\fP + const; + + Finds the last substring that is equal to the given character sequence. The search + begins at pos and proceeds from right to left (thus, the found substring, if any, + cannot begin in a position following pos). If npos or any value not smaller than + size() - 1 is passed as pos, the whole string will be searched. + + 1) Finds the last occurrence of v in this view, starting at position pos. + 2) Equivalent to rfind(basic_string_view(std::addressof(ch), 1), pos). + 3) Equivalent to rfind(basic_string_view(s, count), pos). + 4) Equivalent to rfind(basic_string_view(s), pos). + +.SH Parameters + + v - view to search for + pos - position at which to start the search + count - length of substring to search for + s - pointer to a character string to search for + ch - character to search for + +.SH Return value + + Position of the first character of the found substring or npos if no such substring + is found. + +.SH Complexity + + O(size() * v.size()) at worst. + +.SH Example + + +// Run this code + + #include + + int main() + { + using namespace std::literals; + constexpr auto N = std::string_view::npos; + + static_assert(true + && (6 == "AB AB AB"sv.rfind("AB")) + && (6 == "AB AB AB"sv.rfind("ABCD", N, 2)) + && (3 == "AB AB AB"sv.rfind("AB", 5)) + && (0 == "AB CD EF"sv.rfind("AB", 0)) + && (2 == "B AB AB "sv.rfind("AB", 2)) + && (N == "B AB AB "sv.rfind("AB", 1)) + && (5 == "B AB AB "sv.rfind('A')) + && (4 == "AB AB AB"sv.rfind('B', 4)) + && (N == "AB AB AB"sv.rfind('C')) + ); + } + +.SH See also + + find find characters in the view + \fI(public member function)\fP + find_first_of find first occurrence of characters + \fI(public member function)\fP + find_last_of find last occurrence of characters + \fI(public member function)\fP + find_first_not_of find first absence of characters + \fI(public member function)\fP + find_last_not_of find last absence of characters + \fI(public member function)\fP + find the last occurrence of a substring + rfind \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstring_view::size,std::basic_string_view::length.3 b/man/std::wstring_view::size,std::basic_string_view::length.3 new file mode 100644 index 000000000..8f96ca90c --- /dev/null +++ b/man/std::wstring_view::size,std::basic_string_view::length.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::size,std::basic_string_view::length 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::size,std::basic_string_view::length \- std::basic_string_view::size,std::basic_string_view::length + +.SH Synopsis + constexpr size_type size() const noexcept; \fI(since C++17)\fP + constexpr size_type length() const noexcept; \fI(since C++17)\fP + + Returns the number of CharT elements in the view, i.e. std::distance(begin(), + end()). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + The number of CharT elements in the view. + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + // Print a string surrounded by single quotes, its + // length and whether it is considered empty. + void check_string(std::string_view ref) + { + std::cout << std::boolalpha + << "'" << ref << "' has " << ref.size() + << " character(s); emptiness: " << ref.empty() << '\\n'; + } + + int main(int argc, char **argv) + { + // An empty string + check_string(""); + + // Almost always not empty: argv[0] + if (argc > 0) + check_string(argv[0]); + } + +.SH Possible output: + + '' has 0 character(s); emptiness: true + './a.out' has 7 character(s); emptiness: false + +.SH See also + + empty checks whether the view is empty + \fI(public member function)\fP + max_size returns the maximum number of characters + \fI(public member function)\fP + size returns the number of characters + length \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::starts_with.3 b/man/std::wstring_view::starts_with.3 new file mode 100644 index 000000000..9c8fd78c7 --- /dev/null +++ b/man/std::wstring_view::starts_with.3 @@ -0,0 +1,80 @@ +.TH std::basic_string_view::starts_with 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::starts_with \- std::basic_string_view::starts_with + +.SH Synopsis + constexpr bool starts_with( basic_string_view sv ) const noexcept; \fB(1)\fP \fI(since C++20)\fP + constexpr bool starts_with( CharT ch ) const noexcept; \fB(2)\fP \fI(since C++20)\fP + constexpr bool starts_with( const CharT* s ) const; \fB(3)\fP \fI(since C++20)\fP + + Checks if the string view begins with the given prefix, where + + 1) the prefix is a string view. Effectively returns basic_string_view(data(), + std::min(size(), sv.size())) == sv. + 2) the prefix is a single character. Effectively returns !empty() && + Traits::eq(front(), ch). + 3) the prefix is a null-terminated character string. Effectively returns + starts_with(basic_string_view(s)). + +.SH Parameters + + sv - a string view which may be a result of implicit conversion from + std::basic_string + ch - a single character + s - a null-terminated character string + +.SH Return value + + true if the string view begins with the provided prefix, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_starts_ends_with 201711L (C++20) String prefix and suffix checking: + starts_with() and ends_with() + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + using namespace std::literals; + + assert + ("" + // (1) starts_with( basic_string_view ) + && "https://cppreference.com"sv.starts_with("http"sv) == true + && "https://cppreference.com"sv.starts_with("ftp"sv) == false + + // (2) starts_with( CharT ) + && "C++20"sv.starts_with('C') == true + && "C++20"sv.starts_with('J') == false + + // (3) starts_with( const CharT* ) + && std::string_view("string_view").starts_with("string") == true + && std::string_view("string_view").starts_with("String") == false + ); + } + +.SH See also + + ends_with checks if the string view ends with the given suffix + (C++20) \fI(public member function)\fP + starts_with checks if the string starts with the given prefix + (C++20) \fI(public member function of std::basic_string)\fP + + ends_with checks if the string ends with the given suffix + (C++20) \fI(public member function of std::basic_string)\fP + + contains checks if the string contains the given substring or character + (C++23) \fI(public member function of std::basic_string)\fP + + contains checks if the string view contains the given substring or character + (C++23) \fI(public member function)\fP + compare compares two views + \fI(public member function)\fP diff --git a/man/std::wstring_view::substr.3 b/man/std::wstring_view::substr.3 new file mode 100644 index 000000000..d7edf51b7 --- /dev/null +++ b/man/std::wstring_view::substr.3 @@ -0,0 +1,76 @@ +.TH std::basic_string_view::substr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::substr \- std::basic_string_view::substr + +.SH Synopsis + constexpr basic_string_view substr( size_type pos = 0, \fI(since C++17)\fP + size_type count = npos ) const; + + Returns a view of the substring [pos, pos + rlen), where rlen is the smaller of + count and size() - pos. + +.SH Parameters + + pos - position of the first character + count - requested length + +.SH Return value + + View of the substring [pos, pos + rlen). + +.SH Exceptions + + std::out_of_range if pos > size(). + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + typedef std::size_t count_t, pos_t; + + constexpr std::string_view data{"ABCDEF"}; + + std::cout << data.substr() << '\\n'; // ABCDEF, i.e. data[0, 5] that is [0, 6) + std::cout << data.substr(pos_t(1)) << '\\n'; // BCDEF, i.e. [1, 6) + std::cout << data.substr(pos_t(2), count_t(3)) << '\\n'; // CDE, i.e. [2, 2 + 3) + std::cout << data.substr(pos_t(4), count_t(42)) << '\\n'; // EF, i.e. [4, 6) + + try + { + [[maybe_unused]] + auto sub = data.substr(pos_t(666), count_t(1)); // throws: pos > size() + } + catch (std::out_of_range const& ex) + { + std::cout << ex.what() << '\\n'; + } + } + +.SH Possible output: + + ABCDEF + BCDEF + CDE + EF + basic_string_view::substr: __pos (which is 666) > __size (which is 6) + +.SH See also + + copy copies characters + \fI(public member function)\fP + find find characters in the view + \fI(public member function)\fP + substr returns a substring + \fI(public member function of std::basic_string)\fP diff --git a/man/std::wstring_view::swap.3 b/man/std::wstring_view::swap.3 new file mode 100644 index 000000000..c6b397cfe --- /dev/null +++ b/man/std::wstring_view::swap.3 @@ -0,0 +1,64 @@ +.TH std::basic_string_view::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::swap \- std::basic_string_view::swap + +.SH Synopsis + constexpr void swap( basic_string_view& v ) noexcept; \fI(since C++17)\fP + + Exchanges the view with that of v. + +.SH Parameters + + v - view to swap with + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + Constant. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::string_view a = "AAA"; + std::string_view b = "BBBB"; + + std::cout << "Before swap:\\n" + "a = " << a << "\\n" + "b = " << b << "\\n\\n"; + + a.swap(b); + + std::cout << "After swap:\\n" + "a = " << a << "\\n" + "b = " << b << '\\n'; + } + +.SH Output: + + Before swap: + a = AAA + b = BBBB + + After swap: + a = BBBB + b = AAA + +.SH See also + + swap swaps the values of two objects + \fI(function template)\fP + swap_ranges swaps two ranges of elements + \fI(function template)\fP + swaps the contents + swap \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstring_view::wstring_view.3 b/man/std::wstring_view::wstring_view.3 new file mode 100644 index 000000000..1cce214b7 --- /dev/null +++ b/man/std::wstring_view::wstring_view.3 @@ -0,0 +1,133 @@ +.TH std::basic_string_view::basic_string_view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_string_view::basic_string_view \- std::basic_string_view::basic_string_view + +.SH Synopsis + constexpr basic_string_view() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr basic_string_view( const basic_string_view& other ) + noexcept \fB(2)\fP \fI(since C++17)\fP + = default; + constexpr basic_string_view( const CharT* s, size_type count ); \fB(3)\fP \fI(since C++17)\fP + constexpr basic_string_view( const CharT* s ); \fB(4)\fP \fI(since C++17)\fP + template< class It, class End > \fB(5)\fP \fI(since C++20)\fP + constexpr basic_string_view( It first, End last ); + template< class R > constexpr explicit basic_string_view( R&& r ); \fB(6)\fP (since C++23) + constexpr basic_string_view( std::nullptr_t ) = delete; \fB(7)\fP (since C++23) + + 1) Default constructor. Constructs an empty std::basic_string_view. After + construction, data() is equal to nullptr, and size() is equal to 0. + 2) Copy constructor. Constructs a view of the same content as other. After + construction, data() is equal to other.data(), and size() is equal to other.size(). + 3) Constructs a view of the first count characters of the character array starting + with the element pointed by s. s can contain null characters. The behavior is + undefined if [s, s + count) is not a valid range (even though the constructor may + not access any of the elements of this range). After construction, data() is equal + to s, and size() is equal to count. + 4) Constructs a view of the null-terminated character string pointed to by s, not + including the terminating null character. The length of the view is determined as if + by Traits::length(s). The behavior is undefined if [s, s + Traits::length(s)) is not + a valid range. After construction, data() is equal to s, and size() is equal to + Traits::length(s). + 5) Constructs a std::basic_string_view over the range [first, last). The behavior is + undefined if [first, last) is not a valid range, if It does not actually model + contiguous_iterator, or if End does not actually model sized_sentinel_for for It. + After construction, data() is equal to std::to_address(first), and size() is equal + to last - first. + + This overload participates in overload resolution only if + + * It satisfies contiguous_iterator, + * End satisfies sized_sentinel_for for It, + * std::iter_value_t and CharT are the same type, and + * End is not convertible to std::size_t. + 6) Constructs a std::basic_string_view over the range r. After construction, data() + is equal to ranges::data(r), and size() is equal to ranges::size(r). + + This overload participates in overload resolution only if + + * std::remove_cvref_t is not the same type as std::basic_string_view, + * R models contiguous_range and sized_range, + * ranges::range_value_t and CharT are the same type, + * R is not convertible to const CharT*, and + * Let d be an lvalue of type std::remove_cvref_t, d.operator + ::std::basic_string_view() is not a valid expression. + 7) std::basic_string_view cannot be constructed from nullptr. + +.SH Parameters + + other - another view to initialize the view with + s - pointer to a character array or a C string to initialize the view with + count - number of characters to include in the view + first - iterator to the first character of the sequence + last - iterator past the last character of the sequence or another sentinel + r - a contiguous range that contains the sequence + +.SH Complexity + + 1-3,5,6) Constant. + 4) Linear in length of s. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + std::string cppstr = "Foo"; + std::string_view cppstr_v(cppstr); // overload (2), after + // std::string::operator string_view + std::cout << "1) cppstr_v: " << std::quoted(cppstr_v) << '\\n'; + + char array[3] = {'B', 'a', 'r'}; + std::string_view array_v(array, std::size(array)); // overload (3) + std::cout << "2) array_v: " << std::quoted(array_v) << '\\n'; + + const char* one_0_two = "One\\0Two"; + + std::string_view one_two_v{one_0_two, 7}; // overload (3) + std::cout << "3) one_two_v: \\""; + for (char c : one_two_v) + std::cout << (c != '\\0' ? c : '?'); + std::cout << "\\", one_two_v.size(): " << one_two_v.size() << '\\n'; + + std::string_view one_v{one_0_two}; // overload (4) + std::cout << "4) one_v: " << std::quoted(one_v) << ", one_v.size(): " + << one_v.size() << '\\n'; + + constexpr std::wstring_view wcstr_v = L"xyzzy"; // overload (4) + std::cout << "5) wcstr_v.size(): " << wcstr_v.size() << '\\n'; + + std::array ar = {'P', 'u', 'b'}; + std::string_view ar_v(ar.begin(), ar.end()); // overload (5), C++20 + std::cout << "6) ar_v: " << std::quoted(ar_v) << '\\n'; + + // std::string_view ar_v2{ar}; // overload (6), OK in C++23 + // std::cout << "ar_v2: " << std::quoted(ar_v2) << '\\n'; // ar_v2: "Pub" + + [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; + // std::string_view s{zero()}; // overload (7), won't compile since C++23 + } + +.SH Output: + + 1) cppstr_v: "Foo" + 2) array_v: "Bar" + 3) one_two_v: "One?Two", one_two_v.size(): 7 + 4) one_v: "One", one_v.size(): 3 + 5) wcstr_v.size(): 5 + 6) ar_v: "Pub" + +.SH See also + + operator= assigns a view + \fI(public member function)\fP + constructs a basic_string + constructor \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstringbuf.3 b/man/std::wstringbuf.3 deleted file mode 120000 index 0d28e7b96..000000000 --- a/man/std::wstringbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf.3 \ No newline at end of file diff --git a/man/std::wstringbuf.3 b/man/std::wstringbuf.3 new file mode 100644 index 000000000..2d38ec8f0 --- /dev/null +++ b/man/std::wstringbuf.3 @@ -0,0 +1,248 @@ +.TH std::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf \- std::basic_stringbuf + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + > class basic_stringbuf + + : public std::basic_streambuf + + std::basic_stringbuf is a std::basic_streambuf whose associated character sequence + is a memory-resident sequence of arbitrary characters, which can be initialized from + or made available as an instance of std::basic_string. + + Typical implementations of std::basic_stringbuf hold an object of type + std::basic_string or equivalent resizable sequence container directly as a data + member and use it as both the controlled character sequence (the array where the six + pointers of std::basic_streambuf are pointing to) and as the associated character + sequence (the source of characters for all input operations and the target for the + output). + + In addition, a typical implementation holds a data member of type + std::ios_base::openmode to indicate the I/O mode of the associated stream + (input-only, output-only, input/output, at-end, etc). + + If over-allocation strategy is used by overflow(), an additional + high-watermark pointer may be stored to track the last initialized \fI(since C++11)\fP + character. + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::stringbuf std::basic_stringbuf + std::wstringbuf std::basic_stringbuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + the std::basic_string used as the underlying + buf buffer + (exposition-only member object*) + mode the std::ios_base::openmode of the associated stream + (exposition-only member object*) + init_buf_ptrs initializes the input and output sequences + (exposition-only member function*) + +.SH Public member functions + + constructor constructs a basic_stringbuf object + \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function)\fP + destructor destructs a basic_stringbuf object and the string it + \fB[virtual]\fP (implicitly declared) holds + \fI(virtual public member function)\fP + replaces or obtains a copy of the associated + str character string + \fI(public member function)\fP + get_allocator obtains a copy of the allocator associated with the + (C++20) internal sequence container + \fI(public member function)\fP + view obtains a view over the underlying character + (C++20) sequence + \fI(public member function)\fP + +.SH Protected member functions + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + pbackfail puts a character back into the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + overflow appends a character to the output sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP + setbuf attempts to replace the controlled character sequence with an array + \fB[virtual]\fP \fI(virtual protected member function)\fP + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function)\fP + +.SH Non-member functions + + std::swap(std::basic_stringbuf) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_streambuf + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + destructor destructs the basic_streambuf object + \fB[virtual]\fP \fI\fI(virtual public member function\fP of\fP + std::basic_streambuf) +.SH Locales + invokes imbue() + pubimbue \fI(public member function of std::basic_streambuf)\fP + + obtains a copy of the associated locale + getloc \fI(public member function of std::basic_streambuf)\fP + +.SH Positioning + invokes setbuf() + pubsetbuf \fI(public member function of std::basic_streambuf)\fP + + invokes seekoff() + pubseekoff \fI(public member function of std::basic_streambuf)\fP + + invokes seekpos() + pubseekpos \fI(public member function of std::basic_streambuf)\fP + + invokes sync() + pubsync \fI(public member function of std::basic_streambuf)\fP + +.SH Get area + obtains the number of characters immediately available in the get + in_avail area + \fI(public member function of std::basic_streambuf)\fP + + advances the input sequence, then reads one character without + snextc advancing again + \fI(public member function of std::basic_streambuf)\fP + + sbumpc reads one character from the input sequence and advances the + stossc sequence + (removed in C++17) \fI(public member function of std::basic_streambuf)\fP + + reads one character from the input sequence without advancing the + sgetc sequence + \fI(public member function of std::basic_streambuf)\fP + + invokes xsgetn() + sgetn \fI(public member function of std::basic_streambuf)\fP + +.SH Put area + writes one character to the put area and advances the next + sputc pointer + \fI(public member function of std::basic_streambuf)\fP + + invokes xsputn() + sputn \fI(public member function of std::basic_streambuf)\fP + +.SH Putback + puts one character back in the input sequence + sputbackc \fI(public member function of std::basic_streambuf)\fP + + moves the next pointer in the input sequence back by one + sungetc \fI(public member function of std::basic_streambuf)\fP + + +.SH Protected member functions + + constructor constructs a basic_streambuf object + \fI(protected member function)\fP + operator= replaces a basic_streambuf object + \fI(C++11)\fP \fI(protected member function)\fP + swap swaps two basic_streambuf objects + \fI(C++11)\fP \fI(protected member function)\fP +.SH Locales + imbue changes the associated locale + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Positioning + setbuf replaces the buffer with user-defined array, if permitted + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekoff or both, using relative addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + repositions the next pointer in the input sequence, output sequence, + seekpos or both using absolute addressing + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) +.SH Get area + obtains the number of characters available for input in the associated + showmanyc input sequence, if known + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + reads characters from the associated input sequence to the get area + uflow and advances the next pointer + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + xsgetn reads multiple characters from the input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + eback returns a pointer to the beginning, current character and the end of + gptr the get area + egptr \fI(protected member function)\fP + gbump advances the next pointer in the input sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the input + setg sequence + \fI(protected member function)\fP +.SH Put area + xsputn writes multiple characters to the output sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) + pbase returns a pointer to the beginning, current character and the end of + pptr the put area + epptr \fI(protected member function)\fP + pbump advances the next pointer of the output sequence + \fI(protected member function)\fP + repositions the beginning, next, and end pointers of the output + setp sequence + \fI(protected member function)\fP +.SH Putback + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP + std::basic_streambuf) diff --git a/man/std::wstringbuf::basic_stringbuf.3 b/man/std::wstringbuf::basic_stringbuf.3 deleted file mode 120000 index 305998a5b..000000000 --- a/man/std::wstringbuf::basic_stringbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::basic_stringbuf.3 \ No newline at end of file diff --git a/man/std::wstringbuf::basic_stringbuf.3 b/man/std::wstringbuf::basic_stringbuf.3 new file mode 100644 index 000000000..496a0651e --- /dev/null +++ b/man/std::wstringbuf::basic_stringbuf.3 @@ -0,0 +1,240 @@ +.TH std::basic_stringbuf::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::basic_stringbuf \- std::basic_stringbuf::basic_stringbuf + +.SH Synopsis + explicit basic_stringbuf( std::ios_base::openmode which = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringbuf( std::ios_base::openmode which ); \fI(since C++11)\fP + basic_stringbuf() + : basic_stringbuf( std::ios_base::in | std::ios_base::out \fB(2)\fP \fI(since C++11)\fP + ) {} + explicit + + basic_stringbuf( const std::basic_string& s, \fB(3)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); + explicit basic_stringbuf( std::basic_string&& s, + + std::ios_base::openmode which = \fB(4)\fP \fI(since C++20)\fP + + std::ios_base::in | + std::ios_base::out ); + basic_stringbuf( std::ios_base::openmode which, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + explicit basic_stringbuf( const Allocator& a ) + : basic_stringbuf( std::ios_base::in | \fB(6)\fP \fI(since C++20)\fP + std::ios_base::out, a ) {} + template< class SAlloc > + + explicit basic_stringbuf( const std::basic_string& s, \fB(7)\fP \fI(since C++20)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); \fB(1)\fP + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(8)\fP \fI(since C++20)\fP + + std::ios_base::openmode which, const + Allocator& a ); + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(9)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringbuf( s, std::ios_base::in | + std::ios_base::out, a ) {} + template< class StringViewLike > + + explicit basic_stringbuf( const StringViewLike& t, + std::ios_base::openmode which = \fB(10)\fP (since C++26) + + std::ios_base::in | + std::ios_base::out ); + template< class StringViewLike > + + basic_stringbuf( const StringViewLike& t, \fB(11)\fP (since C++26) + + std::ios_base::openmode which, const + Allocator& a ); + template< class StringViewLike > + basic_stringbuf( const StringViewLike& t, const Allocator& a \fB(12)\fP (since C++26) + ); + basic_stringbuf( basic_stringbuf&& rhs ); \fB(13)\fP \fI(since C++11)\fP + basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a ); \fB(14)\fP \fI(since C++20)\fP + basic_stringbuf( const basic_stringbuf& rhs ) = delete; \fB(15)\fP \fI(since C++11)\fP + + The std::basic_streambuf base and the exposition-only data members buf and mode are + initialized as follows. + + After initializing these subobjects, overloads (3-12) initialize the input and + output sequences as if by calling init_buf_ptrs(). + + Overload std::basic_streambuf buf mode + base + \fB(1)\fP which + implementation-defined std::ios_base::in | + \fB(2)\fP (see below) + std::ios_base::out + \fB(3)\fP s + \fB(4)\fP std::move(s) which + \fB(5)\fP + a std::ios_base::in | + \fB(6)\fP + default-initialized std::ios_base::out + \fB(7)\fP s which + \fB(8)\fP + {s, a} std::ios_base::in | + \fB(9)\fP + std::ios_base::out + \fB(10)\fP {sv, Allocator()} which + \fB(11)\fP + {sv, a} std::ios_base::in | + \fB(12)\fP + std::ios_base::out + \fB(13)\fP rhs std::move(rhs).str() + \fB(14)\fP (copy constructed) {std::move(rhs).str(), rhs.mode + a} + + 1,2) Overload + \fB(1)\fP + \fI(until C++11)\fP + \fB(2)\fP + \fI(since C++11)\fP is the default constructor. It is implementation-defined whether the + sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are + initialized to null pointers. + 5,6) When the construction is complete, str.empty() is true. + 7) This overload participates in overload resolution only if std::is_same_v is false. + 10-12) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then it is used as above in the + table. + These overloads participate in overload resolution only if + std::is_convertible_v> is true. + 13,14) Overload \fB(13)\fP is the move constructor. It is implementation-defined whether + the six sequence pointers in *this obtain the values which rhs had. + When the construction is complete, rhs is empty but usable, and + * Let rhs_p refer to the state of rhs just prior to this construction, the + following expressions will evaluate to true: + + * str() == rhs_p.str() + * getloc() == rhs_p.getloc() + * gptr() - eback() == rhs_p.gptr() - rhs_p.eback() + * egptr() - eback() == rhs_p.egptr() - rhs_p.eback() + * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase() + * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase() + * Let rhs_a refer to the state of rhs just after this construction, the following + expressions will evaluate to true: + + * !eback() || eback() != rhs_a.eback() + * !gptr() || gptr() != rhs_a.gptr() + * !egptr() || egptr() != rhs_a.egptr() + * !pbase() || pbase() != rhs_a.pbase() + * !pptr() || pptr() != rhs_a.pptr() + * !epptr() || epptr() != rhs_a.epptr() + 15) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible. + +.SH Parameters + + s - a std::basic_string used to initialize the buffer + t - an object (convertible to std::basic_string_view) used to initialize the + buffer + a - another allocator used to construct the internal std::basic_string + rhs - another basic_stringbuf + specifies stream open mode. It is bitmask type, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + which - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Notes + + Typically called by the constructor of std::basic_stringstream. + + The level of support for the open modes other than std::ios_base::in and + std::ios_base::out varies among implementations. C++11 explicitly specifies the + support for std::ios_base::ate in str() and in this constructor, but + std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different + effects on different implementations. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + +.SH Example + + Demonstrates calling the constructor of std::basic_stringbuf directly: + + +// Run this code + + #include + #include + + int main() + { + // default constructor (mode = in | out) + std::stringbuf buf1; + buf1.sputc('1'); + std::cout << &buf1 << '\\n'; + + // string constructor in at-end mode \fI(C++11)\fP + std::stringbuf buf2("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::ate); + buf2.sputc('1'); + std::cout << &buf2 << '\\n'; + + // append mode test (results differ among compilers) + std::stringbuf buf3("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::app); + buf3.sputc('1'); + buf3.pubseekpos(1); + buf3.sputc('2'); + std::cout << &buf3 << '\\n'; + } + +.SH Output: + + 1 + test1 + est12 (Sun Studio) 2st1 (GCC) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP allocated no array object 1. removed the + LWG 432 C++98 2. overload \fB(3)\fP did not specify how the limitation + input 2. specified + and output sequences are initialized + overload \fB(3)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(which & beyond that position + std::ios_base::out) == true + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + constructs the string stream + constructor \fI\fI(public member\fP function of\fP + std::basic_stringstream) diff --git a/man/std::wstringbuf::get_allocator.3 b/man/std::wstringbuf::get_allocator.3 new file mode 100644 index 000000000..7857c70ac --- /dev/null +++ b/man/std::wstringbuf::get_allocator.3 @@ -0,0 +1,22 @@ +.TH std::basic_stringbuf::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::get_allocator \- std::basic_stringbuf::get_allocator + +.SH Synopsis + allocator_type get_allocator() const noexcept; \fI(since C++20)\fP + + Returns the allocator associated with the internal sequence container. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + the associated allocator + +.SH See also + + returns the associated allocator + get_allocator \fI(public member function of std::basic_string)\fP + diff --git a/man/std::wstringbuf::init_buf_ptrs.3 b/man/std::wstringbuf::init_buf_ptrs.3 new file mode 100644 index 000000000..40e0a6044 --- /dev/null +++ b/man/std::wstringbuf::init_buf_ptrs.3 @@ -0,0 +1,39 @@ +.TH std::basic_stringbuf::init_buf_ptrs 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::init_buf_ptrs \- std::basic_stringbuf::init_buf_ptrs + +.SH Synopsis + void init_buf_ptrs(); (exposition only*) + + Initializes the input and output sequences from buf according to mode. buf and mode + are exposition-only data members of *this. + + Immediately after this function returns: + + * If std::ios_base::out is set in mode, pbase() points to buf.front() and epptr() + >= pbase() + buf.size() is true; + * in addition, if std::ios_base::ate is set in mode, pptr() == pbase() + + buf.size() is true, + * otherwise pptr() == pbase() is true. + * If std::ios_base::in is set in mode, eback() points to buf.front(), and gptr() + == eback() && egptr() == eback() + buf.size() is true. + +.SH Notes + + For efficiency reasons, stream buffer operations can violate invariants of buf while + it is held encapsulated in the std::basic_stringbuf, e.g., by writing to characters + in the range [buf.data() + buf.size(), buf.data() + buf.capacity()). + + All operations retrieving a std::basic_string from buf ensure that the + std::basic_string invariants hold on the returned value. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + calling init_buf_ptrs() made makes + LWG 1448 C++98 pptr() == pbase() + buf.data() pptr() == pbase() + + for streams that are both input and output buf.size() + streams for append streams diff --git a/man/std::wstringbuf::operator=.3 b/man/std::wstringbuf::operator=.3 deleted file mode 120000 index 58e2db92a..000000000 --- a/man/std::wstringbuf::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::operator=.3 \ No newline at end of file diff --git a/man/std::wstringbuf::operator=.3 b/man/std::wstringbuf::operator=.3 new file mode 100644 index 000000000..2dedd1bb3 --- /dev/null +++ b/man/std::wstringbuf::operator=.3 @@ -0,0 +1,56 @@ +.TH std::basic_stringbuf::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::operator= \- std::basic_stringbuf::operator= + +.SH Synopsis + std::basic_stringbuf& operator=( std::basic_stringbuf&& rhs ); \fB(1)\fP \fI(since C++11)\fP + std::basic_stringbuf& operator=( const std::basic_stringbuf& rhs ) \fB(2)\fP + = delete; + + 1) Move assignment operator: Moves the contents of rhs into *this. After the move, + *this has the associated string, the open mode, the locale, and all other state + formerly held by rhs. The six pointers of std::basic_streambuf in *this are + guaranteed to be different from the corresponding pointers in the moved-from rhs + unless null. + 2) The copy assignment operator is deleted; basic_stringbuf is not CopyAssignable. + +.SH Parameters + + rhs - another basic_stringbuf that will be moved from + +.SH Return value + + *this + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::istringstream one("one"); + std::ostringstream two("two"); + + std::cout << "Before move, one = \\"" << one.str() << '"' + << " two = \\"" << two.str() << "\\"\\n"; + + *one.rdbuf() = std::move(*two.rdbuf()); + + std::cout << "After move, one = \\"" << one.str() << '"' + << " two = \\"" << two.str() << "\\"\\n"; + } + +.SH Output: + + Before move, one = "one" two = "two" + After move, one = "two" two = "" + +.SH See also + + constructor constructs a basic_stringbuf object + \fI(public member function)\fP diff --git a/man/std::wstringbuf::overflow.3 b/man/std::wstringbuf::overflow.3 deleted file mode 120000 index 59bc8dfab..000000000 --- a/man/std::wstringbuf::overflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::overflow.3 \ No newline at end of file diff --git a/man/std::wstringbuf::overflow.3 b/man/std::wstringbuf::overflow.3 new file mode 100644 index 000000000..0f3394815 --- /dev/null +++ b/man/std::wstringbuf::overflow.3 @@ -0,0 +1,136 @@ +.TH std::basic_stringbuf::overflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::overflow \- std::basic_stringbuf::overflow + +.SH Synopsis + protected: + virtual int_type overflow( int_type c = Traits::eof() ); + + Appends the character c to the output character sequence. + + If c is the end-of-file indicator (traits::eq_int_type(c, traits::eof()) == true), + then there is no character to append. The function does nothing and returns an + unspecified value other than traits::eof(). + + Otherwise, if the output sequence has a write position available or this function + can successfully make a write position available, then calls sputc(c) and returns c. + + This function can make a write position available if the std::stringbuf is open for + output ((mode & ios_base::out) != 0): in this case, it reallocates (or initially + allocates) the buffer big enough to hold the entire current buffer plus at least one + more character. If the std::stringbuf is also open for input ((mode & ios_base::in) + != 0), then overflow also increases the size of the get area by moving egptr() to + point just past the new write position. + +.SH Parameters + + c - the character to store in the put area + +.SH Return value + + Traits::eof() to indicate failure, c if the character c was successfully appended, + or some value other than Traits::eof() if called with Traits::eof() as the argument. + +.SH Notes + + This function is different from a typical overflow() which moves the contents of the + buffer to the associated character sequence because for a std::basic_stringbuf, the + buffer and the associated sequence are one and the same. + +.SH Example + + In the implementation used to execute this example (e.g. GCC-4.9), overflow() + over-allocates the put area to 512 bytes: a call to str() would only return the four + initialized bytes, but the next 508 calls to sputc() would not require new calls to + overflow(). + + +// Run this code + + #include + #include + + struct mybuf : std::stringbuf + { + mybuf(const std::string& new_str, + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out) + : std::stringbuf(new_str, which) {} + + int_type overflow(int_type c = EOF) override + { + std::cout << "stringbuf::overflow('" << char(c) << "') called\\n" + << "Before: size of get area: " << egptr() - eback() << '\\n' + << " size of put area: " << epptr() - pbase() << '\\n'; + + int_type ret = std::stringbuf::overflow(c); + + std::cout << "After : size of get area: " << egptr() - eback() << '\\n' + << " size of put area: " << epptr() - pbase() << '\\n'; + + return ret; + } + }; + + int main() + { + std::cout << "read-write stream:\\n"; + mybuf sbuf(" "); // read-write stream + std::iostream stream(&sbuf); + stream << 1234; + std::cout << sbuf.str() << '\\n'; + + std::cout << "\\nread-only stream:\\n"; + mybuf ro_buf(" ", std::ios_base::in); // read-only stream + std::iostream ro_stream(&ro_buf); + ro_stream << 1234; + + std::cout << "\\nwrite-only stream:\\n"; + mybuf wr_buf(" ", std::ios_base::out); // write-only stream + std::iostream wr_stream(&wr_buf); + wr_stream << 1234; + } + +.SH Possible output: + + read-write stream: + stringbuf::overflow('4') called + Before: size of get area: 3 + size of put area: 3 + After : size of get area: 4 + size of put area: 512 + 1234 + + read-only stream: + stringbuf::overflow('1') called + Before: size of get area: 3 + size of put area: 0 + After : size of get area: 3 + size of put area: 0 + + write-only stream: + stringbuf::overflow('4') called + Before: size of get area: 0 + size of put area: 3 + After : size of get area: 0 + size of put area: 512 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 169 C++98 the buffer (re)allocated could only hold one allows more extra + extra character characters + overflow moved epptr() to point just past the + LWG 432 C++98 new it is not moved + write position if the std::stringbuf is open + for input + +.SH See also + + overflow writes characters to the associated output sequence from the put area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow returns the next character available in the input sequence + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::wstringbuf::pbackfail.3 b/man/std::wstringbuf::pbackfail.3 deleted file mode 120000 index 01255a607..000000000 --- a/man/std::wstringbuf::pbackfail.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::pbackfail.3 \ No newline at end of file diff --git a/man/std::wstringbuf::pbackfail.3 b/man/std::wstringbuf::pbackfail.3 new file mode 100644 index 000000000..c8b1ffd10 --- /dev/null +++ b/man/std::wstringbuf::pbackfail.3 @@ -0,0 +1,64 @@ +.TH std::basic_stringbuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::pbackfail \- std::basic_stringbuf::pbackfail + +.SH Synopsis + protected: + virtual int_type pbackfail( int_type c = Traits::eof() ) + + This protected virtual function is called by the public functions + basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called + by basic_istream::unget and basic_istream::putback). + + 1) The caller is requesting that the get area is backed up by one character + (pbackfail() is called with no arguments or with Traits::eof() as the argument) + a) First, checks if there is a putback position, and if there really isn't, fails. + (stringbuf has no external character source to re-read) + b) If the caller was wrong and the putback position is in fact available, simply + decrements basic_streambuf::gptr(), e.g. by calling gbump(-1). + 2) The caller attempts to putback a different character from the one retrieved + earlier (pbackfail() is called with the character that needs to be put back), in + which case + a) First, checks if there is a putback position, and if there isn't, fails. + b) Then checks what character is in the putback position. If the character held + there is already equal to c, as determined by Traits::eq(to_char_type(c), + gptr()[-1]), then simply decrements basic_streambuf::gptr(). + c) Otherwise, if the buffer is open for reading only, fails. + d) Otherwise, if the buffer is open for writing (mode && std::ios_base::out is + nonzero), then decrements basic_streambuf::gptr() and writes c to the location + pointed to gptr() after adjustment. + +.SH Parameters + + c - the character to put back, or Traits::eof() to indicate that backing up of the + get area is requested + +.SH Return value + + c on success except if c was Traits::eof(), in which case Traits::not_eof(c) is + returned. + + Traits::eof() on failure. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + puts a character back into the input sequence, possibly modifying the + pbackfail input sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + sungetc moves the next pointer in the input sequence back by one + \fI(public member function of std::basic_streambuf)\fP + sputbackc puts one character back in the input sequence + \fI(public member function of std::basic_streambuf)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstringbuf::seekoff.3 b/man/std::wstringbuf::seekoff.3 deleted file mode 120000 index 870684814..000000000 --- a/man/std::wstringbuf::seekoff.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::seekoff.3 \ No newline at end of file diff --git a/man/std::wstringbuf::seekoff.3 b/man/std::wstringbuf::seekoff.3 new file mode 100644 index 000000000..a8a742258 --- /dev/null +++ b/man/std::wstringbuf::seekoff.3 @@ -0,0 +1,157 @@ +.TH std::basic_stringbuf::seekoff 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::seekoff \- std::basic_stringbuf::seekoff + +.SH Synopsis + protected: + + virtual pos_type seekoff( off_type off, + std::ios_base::seekdir dir, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if + possible, to the position that corresponds to exactly off characters from beginning, + end, or current position of the get and/or put area of the buffer. + + * If which includes std::ios_base::in and this buffer is open for reading (that + is, if (which & std::ios_base::in) == std::ios_base::in), then repositions the + read pointer std::basic_streambuf::gptr inside the get area as described below + * If which includes std::ios_base::out and this buffer is open for writing (that + is, (which & std::ios_base::out) == std::ios_base::out), then repositions the + write pointer std::basic_streambuf::pptr inside the put area as described below + * If which includes both std::ios_base::in and std::ios_base::out and the buffer + is open for both reading and writing (that is, (which & (std::ios_base::in | + std::ios_base::out)) == (std::ios_base::in | std::ios_base::out)), and dir is + either std::ios_base::beg or std::ios_base::end, then repositions both read and + write pointers as described below. + * Otherwise, this function fails. + + If gptr and/or pptr is repositioned, it is done as follows: + + 1) The new pointer offset newoff of type off_type is determined + a) if dir == std::ios_base::beg, then newoff is zero + b) if dir == std::ios_base::cur, then newoff is the current position of the pointer + (gptr() - eback() or pptr() - pbase()) + c) if dir == std::ios_base::end, then newoff is the length of the entire initialized + part of the buffer (if over-allocation is used, the high watermark pointer minus the + beginning pointer) + 2) If the pointer to be repositioned is a null pointer and newoff would be non-zero, + this function fails. + 3) If newoff + off < 0 (the repositioning would move the pointer to before the + beginning of the buffer) or if newoff + off would point past the end of the buffer + (or past the last initialized character in the buffer if over-allocation is used), + the function fails. + 4) Otherwise, the pointer is assigned as if by gptr() = eback() + newoff + off or + pptr() = pbase() + newoff + off. + +.SH Parameters + + off - relative position to set the next pointer(s) to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + defines whether the input sequences, the output sequence, or both are + affected. It can be one or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + pos_type(newoff) on success, pos_type(off_type(-1)) on failure or if pos_type cannot + represent the resulting stream position. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::stringstream ss("123"); // in/out + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + // absolute positioning both pointers + ss.rdbuf()->pubseekoff(1, std::ios_base::beg); // move both 1 forward + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + // try to move both pointers 1 forward from current position + if (-1 == ss.rdbuf()->pubseekoff(1, std::ios_base::cur)) + std::cout << "moving both pointers from current position failed\\n"; + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + // move the write pointer 1 forward, but not the read pointer + // can also be called as ss.seekp(1, std::ios_base::cur); + ss.rdbuf()->pubseekoff(1, std::ios_base::cur, std::ios_base::out); + std::cout << "put pos = " << ss.tellp() + << " get pos = " << ss.tellg() << '\\n'; + + ss << 'a'; // write at put position + std::cout << "Wrote 'a' at put position, the buffer is now " << ss.str() << '\\n'; + + char ch; + ss >> ch; + std::cout << "reading at get position gives '" << ch << "'\\n"; + } + +.SH Output: + + put pos = 0 get pos = 0 + put pos = 1 get pos = 1 + moving both pointers from current position failed + put pos = 1 get pos = 1 + put pos = 2 get pos = 1 + Wrote 'a' at put position, the buffer is now 12a + reading at get position gives '2' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 55 C++98 seekoff returned an undefined pos_type(off_type(-1)) + invalid stream position on failure is returned on failure + static constant members of + LWG 375 C++98 std::ios_base were corrected + misspecified as members of + std::basic_ios + seekoff might succeed even if newoff + LWG 432 C++98 + off seekoff fails + would point past the last initialized in this case + character + repositioning null gptr() and/or null + LWG 453 C++98 pptr() it can succeed in this case + with a new offset of zero always + failed + the end pointer could not be used to + LWG 563 C++98 calculate newoff because it could use the high watermark + not be precisely controlled by the pointer instead + program after resolving LWG issue 432 + +.SH See also + + pubseekoff invokes seekoff() + \fI(public member function of std::basic_streambuf)\fP + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function)\fP + seekoff repositions the file position, using relative addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::wstringbuf::seekpos.3 b/man/std::wstringbuf::seekpos.3 deleted file mode 120000 index 97415d273..000000000 --- a/man/std::wstringbuf::seekpos.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::seekpos.3 \ No newline at end of file diff --git a/man/std::wstringbuf::seekpos.3 b/man/std::wstringbuf::seekpos.3 new file mode 100644 index 000000000..2a5102900 --- /dev/null +++ b/man/std::wstringbuf::seekpos.3 @@ -0,0 +1,105 @@ +.TH std::basic_stringbuf::seekpos 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::seekpos \- std::basic_stringbuf::seekpos + +.SH Synopsis + protected: + + virtual pos_type seekpos( pos_type sp, + + std::ios_base::openmode which = std::ios_base::in | + std::ios_base::out ); + + Repositions std::basic_streambuf::gptr and/or std::basic_streambuf::pptr, if + possible, to the position indicated by sp. + + Effectively executes seekoff(off_type(sp), std::ios_base::beg, which). + +.SH Parameters + + sp - stream position, such as one obtained by seekoff() or seekpos() + defines whether the input sequences, the output sequence, or both are + affected. It can be one or a combination of the following constants: + which - + Constant Explanation + in affect the input sequence + out affect the output sequence + +.SH Return value + + sp on success or pos_type(off_type(-1)) on failure. + +.SH Notes + + seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the + single-argument versions of std::basic_istream::seekg() and + std::basic_ostream::seekp(). + +.SH Example + + +// Run this code + + #include + #include + + struct mybuf : std::stringbuf + { + mybuf(const std::string& str) : std::stringbuf(str) {} + + pos_type seekpos(pos_type sp, std::ios_base::openmode which) + { + std::cout << "Before seekpos(" << sp << "), size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + pos_type rc = std::stringbuf::seekpos(sp, which); + + std::cout << "seekpos() returns " << rc << ".\\nAfter the call, " + << "size of the get area is " + << egptr() - eback() << " with " + << egptr() - gptr() << " read positions available.\\n"; + + return rc; + } + }; + + int main() + { + mybuf buf("12345"); + std::iostream stream(&buf); + stream.seekg(2); + } + +.SH Output: + + Before seekpos\fB(2)\fP, size of the get area is 5 with 5 read positions available. + seekpos() returns 2. + After the call, size of the get area is 5 with 3 read positions available. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + static constant members of std::ios_base + LWG 375 C++98 were corrected + misspecified as members of + std::basic_ios + LWG 564 C++98 if was unclear how to reposition gptr they are repositioned by + and/or pptr seekoff() + +.SH See also + + pubseekpos invokes seekpos() + \fI(public member function of std::basic_streambuf)\fP + seekoff repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both, using relative addressing + \fI(virtual protected member function)\fP + seekpos repositions the file position, using absolute addressing + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + seekpos repositions the next pointer in the input sequence, output sequence, or + \fB[virtual]\fP both using absolute addressing + \fI(virtual protected member function of std::strstreambuf)\fP diff --git a/man/std::wstringbuf::setbuf.3 b/man/std::wstringbuf::setbuf.3 deleted file mode 120000 index 0876df772..000000000 --- a/man/std::wstringbuf::setbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::setbuf.3 \ No newline at end of file diff --git a/man/std::wstringbuf::setbuf.3 b/man/std::wstringbuf::setbuf.3 new file mode 100644 index 000000000..d311331a5 --- /dev/null +++ b/man/std::wstringbuf::setbuf.3 @@ -0,0 +1,62 @@ +.TH std::basic_stringbuf::setbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::setbuf \- std::basic_stringbuf::setbuf + +.SH Synopsis + protected: + virtual std::basic_streambuf* setbuf( char_type* s, std::streamsize + n ) + + If s is a null pointer and n is zero, this function has no effect. + + Otherwise, the effect is implementation-defined: some implementations do nothing, + while some implementations clear the std::string member currently used as the buffer + and begin using the user-supplied character array of size n, whose first element is + pointed to by s, as the buffer and the input/output character sequence. + + This function is protected virtual, it may only be called through pubsetbuf() or + from member functions of a user-defined class derived from std::basic_stringbuf. + +.SH Parameters + + s - pointer to the first CharT in the user-provided buffer or null + n - the number of CharT elements in the user-provided buffer or zero + +.SH Return value + + this + +.SH Notes + + The deprecated stream buffer std::strstreambuf or the boost.IOStreams device + boost::basic_array may be used to implement I/O buffering over a user-provided char + array in portable manner. + +.SH Example + + Test for the stringstream's setbuf functionality. + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream ss; + char c[1024] = {}; + ss.rdbuf()->pubsetbuf(c, 1024); + ss << 3.14 << '\\n'; + std::cout << c << '\\n'; + } + +.SH Output: + + 3.14 (on GNU g++/libstdc++ and SunPro C++/roguewave) + (on MS Visual Studio 2010, SunPro C++/stlport4, CLang++/libc++) + +.SH See also + + pubsetbuf invokes setbuf() + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::wstringbuf::str.3 b/man/std::wstringbuf::str.3 deleted file mode 120000 index 4ad9797b5..000000000 --- a/man/std::wstringbuf::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::str.3 \ No newline at end of file diff --git a/man/std::wstringbuf::str.3 b/man/std::wstringbuf::str.3 new file mode 100644 index 000000000..ba2785791 --- /dev/null +++ b/man/std::wstringbuf::str.3 @@ -0,0 +1,141 @@ +.TH std::basic_stringbuf::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::str \- std::basic_stringbuf::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Gets and sets the underlying string. + + In the descriptions below, buf and mode are exposition-only data members of *this. + + 1) Creates and returns a std::basic_string object containing a copy of this + std::basic_stringbuf's underlying character sequence. For input-only streams, the + returned string contains the characters from the range [eback(), egptr()). For + input/output or output-only streams, contains the characters from pbase() to the + last character in the sequence regardless of egptr() and epptr(). + + The member character sequence in a buffer open for writing can be over-allocated for + efficiency purposes. In that case, only the initialized characters are returned: + these characters are the ones that were obtained from the string argument of the + constructor, the string argument of the most recent call to a setter overload of + str(), or from a write operation. A typical implementation that uses over-allocation + maintains a high-watermark pointer to track the end of the initialized part of the + buffer and this overload returns the characters from pbase() to the high-watermark + pointer. + + Equivalent to return std::basic_string(view(), get_allocator());. + + 2) Same as \fB(1)\fP, except that a is used to construct the returned std::basic_string. + Equivalent to return std::basic_string(view(), a);. + This overload participates in overload resolution only if SAlloc meets the + requirements of Allocator. + 3) Creates a std::basic_string object as if by move constructing it from *this's + underlying character sequence in buf. buf may need to be adjusted to contain the + same content as in \fB(1)\fP at first. After that, sets buf to empty and calls + init_buf_ptrs(), then returns the std::basic_string object. + 4) Replaces the underlying character sequence as if by buf = s, then calls + init_buf_ptrs(). + 5) Same as \fB(4)\fP, except the type of s's allocator is not Allocator. + This overload participates in overload resolution only if std::is_same_v is false. + 6) Replaces the underlying character sequence as if by buf = std::move(s), then + calls init_buf_ptrs(). + 7) Implicitly converts t to a string view sv as if by std::basic_string_view sv = t;, then replaces the underlying character sequence as if by buf = sv, + then calls init_buf_ptrs(). + This overload participates in overload resolution only if + std::is_convertible_v> is true. + +.SH Parameters + + s - a std::basic_string object holding the replacement character sequence + t - an object (convertible to std::basic_string_view) holding the replacement + character sequence + a - allocator to use for all memory allocations of the returned std::basic_string + +.SH Return value + + 1-3) A std::basic_string object holding this buffer's underlying character sequence. + 4-7) \fI(none)\fP + +.SH Notes + + This function is typically accessed through std::basic_istringstream::str(), + std::basic_ostringstream::str(), or std::basic_stringstream::str(). + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.rdbuf()->str("1 2"); // set the get area + in >> n; + std::cout << "after reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.rdbuf()->str() << "\\"\\n"; // or in.str() + + std::ostringstream out("1 2"); + out << 3; + std::cout << "after writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); // C++11 + ate << 3; + std::cout << "after writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + after reading the first int from "1 2", the int is 1, str() = "1 2" + after writing the int '3' to output stream "1 2", str() = "3 2" + after writing the int '3' to append stream "1 2", str() = "1 23" + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP did not specify the content + LWG 432 C++98 of the underlying character sequence both specified + 2. overload \fB(4)\fP did not specify how the + input and output sequences are initialized + overload \fB(4)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(mode & std::ios_base::out) beyond that position + == true + +.SH See also + + gets or sets the contents of underlying string device object + str \fI(public member function of std::basic_stringstream)\fP + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function)\fP diff --git a/man/std::wstringbuf::swap.3 b/man/std::wstringbuf::swap.3 deleted file mode 120000 index 925518804..000000000 --- a/man/std::wstringbuf::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::swap.3 \ No newline at end of file diff --git a/man/std::wstringbuf::swap.3 b/man/std::wstringbuf::swap.3 new file mode 100644 index 000000000..60e1e3222 --- /dev/null +++ b/man/std::wstringbuf::swap.3 @@ -0,0 +1,76 @@ +.TH std::basic_stringbuf::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::swap \- std::basic_stringbuf::swap + +.SH Synopsis + void swap( basic_stringbuf& rhs ); \fI(since C++11)\fP + \fI(until C++20)\fP + void swap( basic_stringbuf& rhs ) noexcept(/* see below */); \fI(since C++20)\fP + + Swaps the state and the contents of *this and rhs. + + The behavior is undefined if Allocator does not propagate on swap and \fI(since C++11)\fP + the allocators of *this and other are unequal. + +.SH Parameters + + rhs - another basic_stringbuf + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + (since + May throw implementation-defined exceptions. C++11) + (until + C++20) + noexcept specification: (since + noexcept(std::allocator_traits::propagate_on_container_swap::value C++20) + || std::allocator_traits::is_always_equal::value) + +.SH Notes + + This function is called automatically when swapping std::stringstream objects. It is + rarely necessary to call it directly. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::istringstream one("one"); + std::ostringstream two("two"); + + std::cout << "Before swap: one = " << std::quoted(one.str()) + << ", two = " << std::quoted(two.str()) << ".\\n"; + + one.rdbuf()->swap(*two.rdbuf()); + + std::cout << "After swap: one = " << std::quoted(one.str()) + << ", two = " << std::quoted(two.str()) << ".\\n"; + } + +.SH Output: + + Before swap: one = "one", two = "two". + After swap: one = "two", two = "one". + +.SH See also + + constructor constructs a basic_stringbuf object + \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI\fI(public member\fP function of\fP + std::basic_stringstream) + +.SH Category: + * conditionally noexcept diff --git a/man/std::wstringbuf::underflow.3 b/man/std::wstringbuf::underflow.3 deleted file mode 120000 index 5313ba532..000000000 --- a/man/std::wstringbuf::underflow.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::underflow.3 \ No newline at end of file diff --git a/man/std::wstringbuf::underflow.3 b/man/std::wstringbuf::underflow.3 new file mode 100644 index 000000000..e5d49cc92 --- /dev/null +++ b/man/std::wstringbuf::underflow.3 @@ -0,0 +1,139 @@ +.TH std::basic_stringbuf::underflow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::underflow \- std::basic_stringbuf::underflow + +.SH Synopsis + protected: + virtual int_type underflow() + + Reads the next character from the get area of the buffer. + + Specifically: + + 1) If the input sequence has a read position available (egptr() > gptr()), returns + Traits::to_int_type(*gptr()) + 2) Otherwise, if pptr() > egptr() (some characters were inserted into the stream + since the last time overflow() changed egptr()) then extends the end of the get area + to include the most recently inserted characters, by changing egptr() to equal + pptr(), and then returns Traits::to_int_type(*gptr()) + 3) Otherwise, returns Traits::eof(). + + Any character in the buffer which has been initialized, regardless of whether it + originated from the string passed in the constructor or was appended by overflow(), + is considered to be part of the input sequence. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Traits::to_int_type(*gptr()) (the next character to read in the get area) in case of + success, or Traits::eof() in case of failure. + +.SH Example + + +// Run this code + + #include + #include + + struct mybuf : std::stringbuf + { + mybuf(const std::string& new_str, + std::ios_base::openmode which = std::ios_base::in | std::ios_base::out) + : std::stringbuf(new_str, which) {} + + int_type overflow(int_type c) + { + std::cout << "Before overflow(): get area size is " << egptr() - eback() + << ", the put area size is " << epptr() - pbase() << '\\n'; + int_type rc = std::stringbuf::overflow(c); + std::cout << "After overflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + return rc; + } + + int_type underflow() + { + std::cout << "Before underflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + int_type ch = std::stringbuf::underflow(); + std::cout << "After underflow(): get area size is " << egptr() - eback() + << ", put area size is " << epptr() - pbase() << '\\n'; + + if (ch == EOF) + std::cout << "underflow() returns EOF\\n"; + else + std::cout << "underflow() returns '" << char(ch) << "'\\n"; + return ch; + } + }; + + int main() + { + mybuf sbuf("123"); // read-write stream + std::iostream stream(&sbuf); + int n; + stream >> n; // calls sgetc() four times + // three calls return the characters '1', '2', '3' + // the fourth call, gptr() == egptr() and underflow() is called + // underflow returns EOF + std::cout << "n = " << n << '\\n'; + stream.clear(); // clear the eofbit + + stream << "123456"; // sputc() is called 6 times + // first three calls store "123" in the existing buffer + // 4th call finds that pptr() == epptr() and calls overflow() + // overflow() grows the buffer and sets egptr() to 4 + // 5th and 6th calls store '5' and '6', advancing pptr() + + stream >> n; // calls sgetc() 4 times + // 1st call returns the '4' that was made available by overflow() + // on the 2nd call, egptr() == egptr() and underflow() is called + // underflow advances egptr() to equal pptr() (which is 6) + // 3rd sgetc() returns '6' + // 4th sgetc() finds gptr() == egptr(), calls underflow() + // underflow() returns EOF + + std::cout << "n = " << n << '\\n'; + } + +.SH Possible output: + + Before underflow(): get area size is 3, put area size is 15 + After underflow(): get area size is 3, put area size is 15 + underflow() returns EOF + n = 123 + Before underflow(): get area size is 3, put area size is 15 + After underflow(): get area size is 6, put area size is 15 + underflow() returns '4' + Before underflow(): get area size is 6, put area size is 15 + After underflow(): get area size is 6, put area size is 15 + underflow() returns EOF + n = 456 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear whether characters appended by + LWG 432 C++98 overflow() made clear + are considered to be part of the input sequence + +.SH See also + + underflow reads characters from the associated input sequence to the get area + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + underflow reads from the associated file + \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf)\fP + + underflow reads a character from the input sequence without advancing the next + \fB[virtual]\fP pointer + \fI(virtual protected member function of std::strstreambuf)\fP + sgetc reads one character from the input sequence without advancing the sequence + \fI(public member function of std::basic_streambuf)\fP diff --git a/man/std::wstringbuf::view.3 b/man/std::wstringbuf::view.3 new file mode 100644 index 000000000..eb1842d18 --- /dev/null +++ b/man/std::wstringbuf::view.3 @@ -0,0 +1,50 @@ +.TH std::basic_stringbuf::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::view \- std::basic_stringbuf::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Creates and returns a std::basic_string_view over the underlying character sequence. + + * For input-only streams, the returned view represents the range [eback(), + egptr()). + * For input/output or output-only streams, references the characters from pbase() + to the last character in the sequence regardless of egptr() and epptr(). + * If the stream is neither input nor output, returns std::basic_string_view{}. + + The member character sequence in a buffer open for writing can be over-allocated for + efficiency purposes. In that case, only the initialized characters are referenced: + these characters are the ones that were obtained from the string argument of the + constructor, the string argument used by the most recent call to a setter overload + of str(), or from a write operation. A typical implementation that uses + over-allocation maintains a high-watermark pointer to track the end of the + initialized part of the buffer and the returned view references the characters from + pbase() to the high-watermark pointer. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A view over the underlying character sequence. + +.SH Notes + + Using of the return value is undefined behavior if the underlying character sequence + is destroyed or invalidated, unless the return value is empty. + + This function is typically accessed through std::basic_istringstream::view(), + std::basic_ostringstream::view(), or std::basic_stringstream::view(). + +.SH See also + + replaces or obtains a copy of the associated character + str string + \fI(public member function)\fP + returns a non-modifiable string_view into the entire + operator basic_string_view string + \fI(C++17)\fP \fI\fI(public member\fP function of\fP + std::basic_string) diff --git a/man/std::wstringbuf::wstringbuf.3 b/man/std::wstringbuf::wstringbuf.3 deleted file mode 120000 index 305998a5b..000000000 --- a/man/std::wstringbuf::wstringbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringbuf::basic_stringbuf.3 \ No newline at end of file diff --git a/man/std::wstringbuf::wstringbuf.3 b/man/std::wstringbuf::wstringbuf.3 new file mode 100644 index 000000000..496a0651e --- /dev/null +++ b/man/std::wstringbuf::wstringbuf.3 @@ -0,0 +1,240 @@ +.TH std::basic_stringbuf::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringbuf::basic_stringbuf \- std::basic_stringbuf::basic_stringbuf + +.SH Synopsis + explicit basic_stringbuf( std::ios_base::openmode which = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringbuf( std::ios_base::openmode which ); \fI(since C++11)\fP + basic_stringbuf() + : basic_stringbuf( std::ios_base::in | std::ios_base::out \fB(2)\fP \fI(since C++11)\fP + ) {} + explicit + + basic_stringbuf( const std::basic_string& s, \fB(3)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); + explicit basic_stringbuf( std::basic_string&& s, + + std::ios_base::openmode which = \fB(4)\fP \fI(since C++20)\fP + + std::ios_base::in | + std::ios_base::out ); + basic_stringbuf( std::ios_base::openmode which, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + explicit basic_stringbuf( const Allocator& a ) + : basic_stringbuf( std::ios_base::in | \fB(6)\fP \fI(since C++20)\fP + std::ios_base::out, a ) {} + template< class SAlloc > + + explicit basic_stringbuf( const std::basic_string& s, \fB(7)\fP \fI(since C++20)\fP + std::ios_base::openmode which = + + std::ios_base::in | + std::ios_base::out ); \fB(1)\fP + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(8)\fP \fI(since C++20)\fP + + std::ios_base::openmode which, const + Allocator& a ); + template< class SAlloc > + + basic_stringbuf( const std::basic_string& s, \fB(9)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringbuf( s, std::ios_base::in | + std::ios_base::out, a ) {} + template< class StringViewLike > + + explicit basic_stringbuf( const StringViewLike& t, + std::ios_base::openmode which = \fB(10)\fP (since C++26) + + std::ios_base::in | + std::ios_base::out ); + template< class StringViewLike > + + basic_stringbuf( const StringViewLike& t, \fB(11)\fP (since C++26) + + std::ios_base::openmode which, const + Allocator& a ); + template< class StringViewLike > + basic_stringbuf( const StringViewLike& t, const Allocator& a \fB(12)\fP (since C++26) + ); + basic_stringbuf( basic_stringbuf&& rhs ); \fB(13)\fP \fI(since C++11)\fP + basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a ); \fB(14)\fP \fI(since C++20)\fP + basic_stringbuf( const basic_stringbuf& rhs ) = delete; \fB(15)\fP \fI(since C++11)\fP + + The std::basic_streambuf base and the exposition-only data members buf and mode are + initialized as follows. + + After initializing these subobjects, overloads (3-12) initialize the input and + output sequences as if by calling init_buf_ptrs(). + + Overload std::basic_streambuf buf mode + base + \fB(1)\fP which + implementation-defined std::ios_base::in | + \fB(2)\fP (see below) + std::ios_base::out + \fB(3)\fP s + \fB(4)\fP std::move(s) which + \fB(5)\fP + a std::ios_base::in | + \fB(6)\fP + default-initialized std::ios_base::out + \fB(7)\fP s which + \fB(8)\fP + {s, a} std::ios_base::in | + \fB(9)\fP + std::ios_base::out + \fB(10)\fP {sv, Allocator()} which + \fB(11)\fP + {sv, a} std::ios_base::in | + \fB(12)\fP + std::ios_base::out + \fB(13)\fP rhs std::move(rhs).str() + \fB(14)\fP (copy constructed) {std::move(rhs).str(), rhs.mode + a} + + 1,2) Overload + \fB(1)\fP + \fI(until C++11)\fP + \fB(2)\fP + \fI(since C++11)\fP is the default constructor. It is implementation-defined whether the + sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are + initialized to null pointers. + 5,6) When the construction is complete, str.empty() is true. + 7) This overload participates in overload resolution only if std::is_same_v is false. + 10-12) Implicitly converts t to a string view sv as if by + std::basic_string_view sv = t;, then it is used as above in the + table. + These overloads participate in overload resolution only if + std::is_convertible_v> is true. + 13,14) Overload \fB(13)\fP is the move constructor. It is implementation-defined whether + the six sequence pointers in *this obtain the values which rhs had. + When the construction is complete, rhs is empty but usable, and + * Let rhs_p refer to the state of rhs just prior to this construction, the + following expressions will evaluate to true: + + * str() == rhs_p.str() + * getloc() == rhs_p.getloc() + * gptr() - eback() == rhs_p.gptr() - rhs_p.eback() + * egptr() - eback() == rhs_p.egptr() - rhs_p.eback() + * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase() + * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase() + * Let rhs_a refer to the state of rhs just after this construction, the following + expressions will evaluate to true: + + * !eback() || eback() != rhs_a.eback() + * !gptr() || gptr() != rhs_a.gptr() + * !egptr() || egptr() != rhs_a.egptr() + * !pbase() || pbase() != rhs_a.pbase() + * !pptr() || pptr() != rhs_a.pptr() + * !epptr() || epptr() != rhs_a.epptr() + 15) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible. + +.SH Parameters + + s - a std::basic_string used to initialize the buffer + t - an object (convertible to std::basic_string_view) used to initialize the + buffer + a - another allocator used to construct the internal std::basic_string + rhs - another basic_stringbuf + specifies stream open mode. It is bitmask type, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + which - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Notes + + Typically called by the constructor of std::basic_stringstream. + + The level of support for the open modes other than std::ios_base::in and + std::ios_base::out varies among implementations. C++11 explicitly specifies the + support for std::ios_base::ate in str() and in this constructor, but + std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different + effects on different implementations. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with + std::string_view + +.SH Example + + Demonstrates calling the constructor of std::basic_stringbuf directly: + + +// Run this code + + #include + #include + + int main() + { + // default constructor (mode = in | out) + std::stringbuf buf1; + buf1.sputc('1'); + std::cout << &buf1 << '\\n'; + + // string constructor in at-end mode \fI(C++11)\fP + std::stringbuf buf2("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::ate); + buf2.sputc('1'); + std::cout << &buf2 << '\\n'; + + // append mode test (results differ among compilers) + std::stringbuf buf3("test", std::ios_base::in + | std::ios_base::out + | std::ios_base::app); + buf3.sputc('1'); + buf3.pubseekpos(1); + buf3.sputc('2'); + std::cout << &buf3 << '\\n'; + } + +.SH Output: + + 1 + test1 + est12 (Sun Studio) 2st1 (GCC) + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. overload \fB(1)\fP allocated no array object 1. removed the + LWG 432 C++98 2. overload \fB(3)\fP did not specify how the limitation + input 2. specified + and output sequences are initialized + overload \fB(3)\fP set epptr() to point one past + LWG 562 C++98 the last underlying epptr() can be set + character if bool(which & beyond that position + std::ios_base::out) == true + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + constructs the string stream + constructor \fI\fI(public member\fP function of\fP + std::basic_stringstream) diff --git a/man/std::wstringstream.3 b/man/std::wstringstream.3 deleted file mode 120000 index 5f0585c2e..000000000 --- a/man/std::wstringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream.3 \ No newline at end of file diff --git a/man/std::wstringstream.3 b/man/std::wstringstream.3 new file mode 100644 index 000000000..1d773afdb --- /dev/null +++ b/man/std::wstringstream.3 @@ -0,0 +1,318 @@ +.TH std::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream \- std::basic_stringstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + > class basic_stringstream + + : public basic_iostream; + + The class template std::basic_stringstream implements input and output operations on + string based streams. It effectively stores an instance of std::basic_string and + performs the input and output operations on it. + + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_iostream. The + complete interface to unique std::basic_stringbuf members is provided. + + std-basic stringstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::stringstream std::basic_stringstream + std::wstringstream std::basic_stringstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) + +.SH Member functions + + constructor constructs the string stream + \fI(public member function)\fP + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP +.SH String operations + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_istringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_istream + +.SH Member functions + +.SH Formatted input + operator>> extracts formatted data + \fI(public member function of std::basic_istream)\fP +.SH Unformatted input + get extracts characters + \fI(public member function of std::basic_istream)\fP + peek reads the next character without extracting it + \fI(public member function of std::basic_istream)\fP + unget unextracts a character + \fI(public member function of std::basic_istream)\fP + putback puts a character into input stream + \fI(public member function of std::basic_istream)\fP + getline extracts characters until the given character is found + \fI(public member function of std::basic_istream)\fP + ignore extracts and discards characters until the given character is found + \fI(public member function of std::basic_istream)\fP + read extracts blocks of characters + \fI(public member function of std::basic_istream)\fP + readsome extracts already available blocks of characters + \fI(public member function of std::basic_istream)\fP + returns number of characters extracted by last unformatted input + gcount operation + \fI(public member function of std::basic_istream)\fP +.SH Positioning + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP +.SH Miscellaneous + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for input operations + \fI(public member class of std::basic_istream)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::wstringstream::basic_stringstream.3 b/man/std::wstringstream::basic_stringstream.3 deleted file mode 120000 index 8593426e8..000000000 --- a/man/std::wstringstream::basic_stringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::basic_stringstream.3 \ No newline at end of file diff --git a/man/std::wstringstream::basic_stringstream.3 b/man/std::wstringstream::basic_stringstream.3 new file mode 100644 index 000000000..c017c138f --- /dev/null +++ b/man/std::wstringstream::basic_stringstream.3 @@ -0,0 +1,181 @@ +.TH std::basic_stringstream::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::basic_stringstream \- std::basic_stringstream::basic_stringstream + +.SH Synopsis + explicit basic_stringstream( std::ios_base::openmode mode = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_stringstream() + : basic_stringstream(std::ios_base::in | \fB(2)\fP \fI(since C++11)\fP + std::ios_base::out) {} + explicit basic_stringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + explicit basic_stringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + basic_stringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_stringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + \fB(1)\fP + basic_stringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringstream(str, std::ios_base::in | + std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_stringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + explicit basic_stringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + basic_stringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_stringstream( const StringViewLike& t, const Allocator& \fB(11)\fP (since C++26) + a ); + basic_stringstream( basic_stringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_iostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_iostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_iostream base sb + load + \fB(1)\fP buf_type(mode) + \fB(2)\fP buf_type(std::ios_base::in | + std::ios_base::out) + \fB(3)\fP buf_type(str, mode) + \fB(4)\fP base_type(std::addressof(sb))^[1] buf_type(std::move(str), mode) + \fB(5)\fP buf_type(mode, a) + \fB(6)\fP buf_type(str, mode, a) + \fB(7)\fP buf_type(str, std::ios_base::in | + std::ios_base::out, a) + \fB(8)\fP buf_type(str, mode) + \fB(9)\fP {t, mode, Allocator()} + \fB(10)\fP std::addressof(sb) {t, mode, a} + \fB(11)\fP {t, std::ios_base::in | + std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_iostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_stringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::wstringstream::operator=.3 b/man/std::wstringstream::operator=.3 deleted file mode 120000 index b0a017836..000000000 --- a/man/std::wstringstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::operator=.3 \ No newline at end of file diff --git a/man/std::wstringstream::operator=.3 b/man/std::wstringstream::operator=.3 new file mode 100644 index 000000000..11454b1f2 --- /dev/null +++ b/man/std::wstringstream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_stringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::operator= \- std::basic_stringstream::operator= + +.SH Synopsis + basic_stringstream& operator=( basic_stringstream&& other ); \fI(since C++11)\fP + + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_iostream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. + +.SH Parameters + + other - string stream to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + operator= move-assigns another basic_iostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::wstringstream::rdbuf.3 b/man/std::wstringstream::rdbuf.3 deleted file mode 120000 index 05bbb1c9c..000000000 --- a/man/std::wstringstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::wstringstream::rdbuf.3 b/man/std::wstringstream::rdbuf.3 new file mode 100644 index 000000000..f35cd4f29 --- /dev/null +++ b/man/std::wstringstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_stringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::rdbuf \- std::basic_stringstream::rdbuf + +.SH Synopsis + std::basic_stringbuf* rdbuf() const; + + Returns pointer to the underlying raw string device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw string device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::wstringstream::str.3 b/man/std::wstringstream::str.3 deleted file mode 120000 index 91d48274a..000000000 --- a/man/std::wstringstream::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::str.3 \ No newline at end of file diff --git a/man/std::wstringstream::str.3 b/man/std::wstringstream::str.3 new file mode 100644 index 000000000..1202dfdad --- /dev/null +++ b/man/std::wstringstream::str.3 @@ -0,0 +1,99 @@ +.TH std::basic_stringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::str \- std::basic_stringstream::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Manages the contents of the underlying string object. + + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. + +.SH Parameters + + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string + +.SH Return value + + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP + +.SH Notes + + The copy of the underlying string returned by str is a temporary object that will be + destructed at the end of the expression, so directly calling c_str() on the result + of str() (for example in auto *ptr = out.str().c_str();) results in a dangling + pointer. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.str("1 2"); + in >> n; + std::cout << "After reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.str() << "\\"\\n"; + + std::ostringstream out("1 2"); + out << 3; + std::cout << "After writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); + ate << 3; + std::cout << "After writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" + +.SH See also + + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::wstringstream::swap.3 b/man/std::wstringstream::swap.3 deleted file mode 120000 index b4d190d2c..000000000 --- a/man/std::wstringstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::swap.3 \ No newline at end of file diff --git a/man/std::wstringstream::swap.3 b/man/std::wstringstream::swap.3 new file mode 100644 index 000000000..cbf486e13 --- /dev/null +++ b/man/std::wstringstream::swap.3 @@ -0,0 +1,39 @@ +.TH std::basic_stringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::swap \- std::basic_stringstream::swap + +.SH Synopsis + void swap( basic_stringstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_iostream::swap(other) and + rdbuf()->swap(*other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::wstringstream::view.3 b/man/std::wstringstream::view.3 new file mode 100644 index 000000000..bb7272455 --- /dev/null +++ b/man/std::wstringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_stringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::view \- std::basic_stringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::wstringstream::wstringstream.3 b/man/std::wstringstream::wstringstream.3 deleted file mode 120000 index 8593426e8..000000000 --- a/man/std::wstringstream::wstringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_stringstream::basic_stringstream.3 \ No newline at end of file diff --git a/man/std::wstringstream::wstringstream.3 b/man/std::wstringstream::wstringstream.3 new file mode 100644 index 000000000..c017c138f --- /dev/null +++ b/man/std::wstringstream::wstringstream.3 @@ -0,0 +1,181 @@ +.TH std::basic_stringstream::basic_stringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_stringstream::basic_stringstream \- std::basic_stringstream::basic_stringstream + +.SH Synopsis + explicit basic_stringstream( std::ios_base::openmode mode = + std::ios_base::in | \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_stringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_stringstream() + : basic_stringstream(std::ios_base::in | \fB(2)\fP \fI(since C++11)\fP + std::ios_base::out) {} + explicit basic_stringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + explicit basic_stringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + basic_stringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_stringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + \fB(1)\fP + basic_stringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_stringstream(str, std::ios_base::in | + std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_stringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + explicit basic_stringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::in | std::ios_base::out ); + template< class StringViewLike > + + basic_stringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_stringstream( const StringViewLike& t, const Allocator& \fB(11)\fP (since C++26) + a ); + basic_stringstream( basic_stringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_iostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_iostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_iostream base sb + load + \fB(1)\fP buf_type(mode) + \fB(2)\fP buf_type(std::ios_base::in | + std::ios_base::out) + \fB(3)\fP buf_type(str, mode) + \fB(4)\fP base_type(std::addressof(sb))^[1] buf_type(std::move(str), mode) + \fB(5)\fP buf_type(mode, a) + \fB(6)\fP buf_type(str, mode, a) + \fB(7)\fP buf_type(str, std::ios_base::in | + std::ios_base::out, a) + \fB(8)\fP buf_type(str, mode) + \fB(9)\fP {t, mode, Allocator()} + \fB(10)\fP std::addressof(sb) {t, mode, a} + \fB(11)\fP {t, std::ios_base::in | + std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_iostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_stringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/swap(std::expected).3 b/man/swap(std::expected).3 new file mode 100644 index 000000000..fea8046e5 --- /dev/null +++ b/man/swap(std::expected).3 @@ -0,0 +1,43 @@ +.TH swap(std::expected) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +swap(std::expected) \- swap(std::expected) + +.SH Synopsis + friend constexpr void swap( expected& lhs, expected& rhs ) (since C++23) + noexcept(/*see below*/); + + Overloads the std::swap algorithm for std::expected. Exchanges the state of lhs with + that of rhs. Effectively calls lhs.swap(rhs). + + This overload participates in overload resolution only if lhs.swap(rhs) is valid. + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::expected is an associated + class of the arguments. + +.SH Parameters + + lhs, rhs - expected objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(noexcept(lhs.swap(rhs))) + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap exchanges the contents + \fI(public member function)\fP + +.SH Categories: + * conditionally noexcept + * Todo no example diff --git a/man/swap(std::jthread).3 b/man/swap(std::jthread).3 new file mode 100644 index 000000000..6fe45a951 --- /dev/null +++ b/man/swap(std::jthread).3 @@ -0,0 +1,79 @@ +.TH swap(std::jthread) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +swap(std::jthread) \- swap(std::jthread) + +.SH Synopsis + friend void swap( jthread& lhs, jthread& rhs ) noexcept; \fI(since C++20)\fP + + Overloads the std::swap algorithm for std::jthread. Exchanges the state of lhs with + that of rhs. Effectively calls lhs.swap(rhs). This function is not visible to + ordinary unqualified or qualified lookup, and can only be found by + argument-dependent lookup when std::jthread is an associated class of the arguments. + +.SH Parameters + + lhs, rhs - jthreads whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + void foo() + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + void bar() + { + std::this_thread::sleep_for(std::chrono::seconds(1)); + } + + int main() + { + using std::swap; + + std::jthread t1(foo); + std::jthread t2(bar); + + std::cout << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + swap(t1, t2); + + std::cout << "after std::swap(t1, t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + t1.swap(t2); + + std::cout << "after t1.swap(t2):" << '\\n' + << "thread 1 id: " << t1.get_id() << '\\n' + << "thread 2 id: " << t2.get_id() << '\\n'; + + + } + +.SH Possible output: + + thread 1 id: 1892 + thread 2 id: 2584 + after std::swap(t1, t2): + thread 1 id: 2584 + thread 2 id: 1892 + after t1.swap(t2): + thread 1 id: 1892 + thread 2 id: 2584 + +.SH See also + + swap swaps two jthread objects + \fI(public member function)\fP diff --git a/man/swap(std::move_only_function).3 b/man/swap(std::move_only_function).3 new file mode 100644 index 000000000..785cd6027 --- /dev/null +++ b/man/swap(std::move_only_function).3 @@ -0,0 +1,71 @@ +.TH swap(std::move_only_function) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +swap(std::move_only_function) \- swap(std::move_only_function) + +.SH Synopsis + friend void swap( move_only_function& lhs, move_only_function& rhs ) (since C++23) + noexcept; + + Overloads the std::swap algorithm for std::move_only_function. Exchanges the state + of lhs with that of rhs. Effectively calls lhs.swap(rhs). + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when + std::move_only_function is an associated class of the arguments. + +.SH Parameters + + lhs, rhs - std::move_only_function objects whose states to swap + +.SH Return value + + \fI(none)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + + void foo(const char* str, int x) + { + std::cout << "foo(\\"" << str << "\\", " << x << ")\\n"; + } + + void bar(const char* str, int x) + { + std::cout << "bar(\\"" << str << "\\", " << x << ")\\n"; + } + + int main() + { + std::move_only_function f1{foo}; + std::move_only_function f2{bar}; + + f1("f1", 1); + f2("f2", 2); + + std::cout << "std::ranges::swap(f1, f2);\\n"; + std::ranges::swap(f1, f2); // finds the hidden friend + + f1("f1", 1); + f2("f2", 2); + } + +.SH Output: + + foo("f1", 1) + bar("f2", 2) + std::ranges::swap(f1, f2); + bar("f1", 1) + foo("f2", 2) + +.SH See also + + swap swaps the targets of two std::move_only_function objects + (C++23) \fI(public member function)\fP + std::swap(std::function) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/swap(std::stop_source).3 b/man/swap(std::stop_source).3 new file mode 100644 index 000000000..08364b833 --- /dev/null +++ b/man/swap(std::stop_source).3 @@ -0,0 +1,21 @@ +.TH swap(std::stop_source) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +swap(std::stop_source) \- swap(std::stop_source) + +.SH Synopsis + friend void swap( stop_source& lhs, stop_source& rhs ) noexcept; \fI(since C++20)\fP + + Overloads the std::swap algorithm for std::stop_source. Exchanges the stop-state of + lhs with that of rhs. Effectively calls lhs.swap(rhs). + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::stop_source is an associated + class of the arguments. + +.SH Parameters + + lhs, rhs - stop_sources to swap + +.SH Return value + + \fI(none)\fP diff --git a/man/swap(std::stop_token).3 b/man/swap(std::stop_token).3 new file mode 100644 index 000000000..5e2608dc2 --- /dev/null +++ b/man/swap(std::stop_token).3 @@ -0,0 +1,21 @@ +.TH swap(std::stop_token) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +swap(std::stop_token) \- swap(std::stop_token) + +.SH Synopsis + friend void swap( stop_token& lhs, stop_token& rhs ) noexcept; \fI(since C++20)\fP + + Overloads the std::swap algorithm for std::stop_token. Exchanges the associated + stop-state of lhs with that of rhs. Effectively calls lhs.swap(rhs). + + This function is not visible to ordinary unqualified or qualified lookup, and can + only be found by argument-dependent lookup when std::stop_token is an associated + class of the arguments. + +.SH Parameters + + lhs, rhs - stop_tokens to swap + +.SH Return value + + \fI(none)\fP diff --git a/src/groff.hpp b/src/groff.hpp index 1554a6243..e1c5b6d9f 100644 --- a/src/groff.hpp +++ b/src/groff.hpp @@ -16,6 +16,7 @@ #include #include #include +#include #include "str.hpp" #include "parse_state.hpp" @@ -25,21 +26,26 @@ class groff { public: - void operator ()(parse_state &state) + std::string remove_template(const std::string &name) { + return std::regex_replace(name, std::regex(R"(<[^>]*>)"), ""); + } + void operator ()(parse_state &state) { state.lines = get_lines(state.plain); if(state.lines.size() < 2) { throw std::runtime_error("insufficient lines in plain render"); } - std::string name{ state.lines[0] }; + std::string name = remove_template(state.lines[0]); str::replace(str::trim(name), " ", ""); /* Don't allow spaces in the filename. */ if(state.output_file.empty()) { state.output_file = state.output_dir + name + ".3"; } /* First two lines are always the same. */ state.lines[0] = ".TH " + name + " 3 " - "\"" + state.creation_date + "\" \"" + state.version + " | http://cppreference.com\" " - "\"C++ Standard Libary\""; + "\"" + state.version + "\" \"" + "http://cppreference.com\" " + "\"C++ Standard Libary\"" + "\n" ".SH NAME\n" + + name + " \\- " + name + "\n"; state.lines[1] = "Synopsis"; groff_detail::section(state.lines); diff --git a/src/groff_highlight.hpp b/src/groff_highlight.hpp index e8d52bade..b71d82d04 100644 --- a/src/groff_highlight.hpp +++ b/src/groff_highlight.hpp @@ -59,10 +59,15 @@ namespace groff_detail /* Color standard release annotations. */ highlight_impl(l, "(C++11)", fmt::italic); highlight_impl(l, "(C++14)", fmt::italic); + highlight_impl(l, "(C++17)", fmt::italic); highlight_impl(l, "(until C++11)", fmt::italic); highlight_impl(l, "(since C++11)", fmt::italic); highlight_impl(l, "(until C++14)", fmt::italic); highlight_impl(l, "(since C++14)", fmt::italic); + highlight_impl(l, "(until C++17)", fmt::italic); + highlight_impl(l, "(since C++17)", fmt::italic); + highlight_impl(l, "(until C++20)", fmt::italic); + highlight_impl(l, "(since C++20)", fmt::italic); /* Description of members. */ highlight_impl(l, "[static]", fmt::bold); diff --git a/src/groff_section.hpp b/src/groff_section.hpp index d0a67f4b4..bfcf5ebec 100644 --- a/src/groff_section.hpp +++ b/src/groff_section.hpp @@ -127,6 +127,9 @@ namespace groff_detail "Capture and storage of exception objects", "Carries dependency", "Category:", /* XXX: Manually added. */ + "Categories:", + "Hidden category:", + "Hidden categories:", "C compatibility headers", "C FAQs", "C++ FAQs", diff --git a/src/parse_state.hpp b/src/parse_state.hpp index 828a4151b..cbd090948 100644 --- a/src/parse_state.hpp +++ b/src/parse_state.hpp @@ -13,11 +13,13 @@ #include #include +#define STR_(x) #x +#define STR(x) STR_(x) + struct parse_state { std::string const name{ "stdman" }; - std::string const version{ "2.0" }; - std::string const creation_date{ __DATE__ }; /* Relies on `make generate` for usage. */ + std::string const version{ STR(STDMAN_VERSION) }; std::string prog; std::string input_file, output_file;

(value)) and only + participates in overload resolution if std::is_constructible::value + == true. + 7) Inserts elements from range [first, last). + 8) Inserts elements from initializer list ilist. + 9) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container and returns an iterator pointing at the inserted element. + If a range containing elements with keys equivalent to nh.key() exists in the + container, the element is inserted at the end of that range. The behavior is + undefined if nh is not empty and get_allocator() != nh.get_allocator(). + 10) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, and returns the + iterator pointing to the element with key equivalent to nh.key(). The element is + inserted as close as possible to the position just prior to pos. The behavior is + undefined if nh is not empty and get_allocator() != nh.get_allocator(). No iterators or references are invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters - hint - iterator, used as a suggestion as to where to insert the content + pos - iterator to the position before which the new element will be inserted value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-4) Returns an iterator to the inserted element. - 5-6) \fI(none)\fP + 1-6) An iterator to the inserted element. + 7,8) \fI(none)\fP + 9,10) End iterator if nh was empty, iterator pointing to the inserted element + otherwise. .SH Exceptions - 1-4) If an exception is thrown by any operation, the insertion has no effect. - - This section is incomplete - Reason: cases 5-6 + 1-6) If an exception is thrown by any operation, the insertion has no effect. + 7,8) No exception safety guarantee. + 9,10) If an exception is thrown by any operation, the insertion has no effect. .SH Complexity - 1-2) Logarithmic in the size of the container, O(log(size())). - - 3-4) Amortized constant if the insertion happens in the position just \fI(until C++11)\fP - after the hint, logarithmic in the size of the container otherwise. - 3-4) Amortized constant if the insertion happens in the position just \fI(since C++11)\fP - before the hint, logarithmic in the size of the container otherwise. - - 5-6) O(N*log(size() + N)), where N is the number of elements to insert. + 1-3) O(log(size())) + 4-6) Amortized constant if the insertion happens in the position just before pos, + O(log(size())) otherwise. + 7,8) O(N·log(size() + N)), where N is the number of elements to insert. + 9) O(log(size())) + 10) Amortized constant if the insertion happens in the position just before pos, + O(log(size())) otherwise. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + template + void print(const std::string_view rem, const M& mmap) + { + std::cout << rem << ' '; + for (const auto& e : mmap) + std::cout << '{' << e.first << ',' << e.second << "} "; + std::cout << '\\n'; + } + + int main() + { + // list-initialize + std::multimap> mmap + {{2, "foo"}, {2, "bar"}, {3, "baz"}, {1, "abc"}, {5, "def"}}; + print("#1", mmap); + + // insert using value_type + mmap.insert(decltype(mmap)::value_type(5, "pqr")); + print("#2", mmap); + + // insert using pair + mmap.insert(std::pair{6, "uvw"}); + print("#3", mmap); + + mmap.insert({7, "xyz"}); + print("#4", mmap); + + // insert using initializer_list + mmap.insert({{5, "one"}, {5, "two"}}); + print("#5", mmap); + + // insert using a pair of iterators + mmap.clear(); + const auto il = {std::pair{1, "ä"}, {2, "ё"}, {2, "ö"}, {3, "ü"}}; + mmap.insert(il.begin(), il.end()); + print("#6", mmap); + } + +.SH Output: + + #1 {5,def} {3,baz} {2,foo} {2,bar} {1,abc} + #2 {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc} + #3 {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc} + #4 {7,xyz} {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc} + #5 {7,xyz} {6,uvw} {5,def} {5,pqr} {5,one} {5,two} {3,baz} {2,foo} {2,bar} {1,abc} + #6 {3,ü} {2,ё} {2,ö} {1,ä} + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the insertion is required + pos was just a hint, it could be to + LWG 233 C++98 totally ignored be as close as possible to + the + position just prior to pos + the complexity of overload \fB(5)\fP was removed the linear + LWG 264 C++98 required to be linear if requirement + the range [first, last) is sorted in this special case + according to Compare + LWG 371 C++98 the order of equivalent elements required to be preserved + was not guaranteed to be preserved + LWG 2005 C++11 overloads (3,6) were poorly described improved the description .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP - -.SH Category: - - * Todo with reason + \fI(C++11)\fP \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP diff --git a/man/std::multimap::insert_range.3 b/man/std::multimap::insert_range.3 new file mode 100644 index 000000000..9a0e147ed --- /dev/null +++ b/man/std::multimap::insert_range.3 @@ -0,0 +1,75 @@ +.TH std::multimap::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::insert_range \- std::multimap::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + No iterators or references are invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements + are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into multimap from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N·log(a.size() + N), where N is ranges::distance(rg). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + #include + + void println(auto, auto const& container) + { + for (const auto& [key, value] : container) + std::cout << '{' << key << ',' << value << '}' << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::multimap{std::pair{1, 11}, {3, 33}, {2, 22}, {4, 44}}; + const auto rg = {std::pair{-1, -11}, {3, -33}, {-2, -22}}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + {-2,-22} {-1,-11} {1,11} {2,22} {3,33} {3,-33} {4,44} + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::key_comp.3 b/man/std::multimap::key_comp.3 index f6d834ed5..078985dd5 100644 --- a/man/std::multimap::key_comp.3 +++ b/man/std::multimap::key_comp.3 @@ -1,4 +1,7 @@ -.TH std::multimap::key_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::key_comp \- std::multimap::key_comp + .SH Synopsis key_compare key_comp() const; @@ -17,7 +20,57 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::multimap cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.key_comp(); + + for (const auto it : cont) + { + const bool before = comp_func(it.first, 100); + const bool after = comp_func(100, it.first); + + std::cout << "Key (" << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + .SH See also value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::lower_bound.3 b/man/std::multimap::lower_bound.3 index 6622aec61..d8499efc6 100644 --- a/man/std::multimap::lower_bound.3 +++ b/man/std::multimap::lower_bound.3 @@ -1,17 +1,21 @@ -.TH std::multimap::lower_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::lower_bound \- std::multimap::lower_bound + .SH Synopsis iterator lower_bound( const Key& key ); \fB(1)\fP - const_iterator lower_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP - iterator lower_bound(const K& x); - template< class K > \fB(2)\fP \fI(since C++14)\fP - const_iterator lower_bound(const K& x) const; - - 1) Returns an iterator pointing to the first element that is not less than key. - 2) Returns an iterator pointing to the first element that compares not less to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. .SH Parameters @@ -27,9 +31,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multimap::max_size.3 b/man/std::multimap::max_size.3 index 67af7f04c..786461a48 100644 --- a/man/std::multimap::max_size.3 +++ b/man/std::multimap::max_size.3 @@ -1,6 +1,9 @@ -.TH std::multimap::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::max_size \- std::multimap::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,25 +17,45 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::multimap p; + std::multimap q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 461,168,601,842,738,790 = 0x666,666,666,666,666 + q.max_size() = 384,307,168,202,282,325 = 0x555,555,555,555,555 + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::merge.3 b/man/std::multimap::merge.3 new file mode 100644 index 000000000..f0b72e275 --- /dev/null +++ b/man/std::multimap::merge.3 @@ -0,0 +1,82 @@ +.TH std::multimap::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::merge \- std::multimap::merge + +.SH Synopsis + template< class C2 > \fB(1)\fP \fI(since C++17)\fP + void merge( std::map& source ); + template< class C2 > \fB(2)\fP \fI(since C++17)\fP + void merge( std::map&& source ); + template< class C2 > \fB(3)\fP \fI(since C++17)\fP + void merge( std::multimap& source ); + template< class C2 > \fB(4)\fP \fI(since C++17)\fP + void merge( std::multimap&& source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the comparison object of *this. + + No elements are copied or moved, only the internal pointers of the container nodes + are repointed. All pointers and references to the transferred elements remain valid, + but now refer into *this, not into source. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Does not throw unless comparison throws. + +.SH Complexity + + N * log(size() + N)), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::multimap ma{{1, "apple"}, {5, "pear"}, {10, "banana"}}; + std::multimap mb{{2, "zorro"}, {4, "batman"}, {5, "X"}, {8, "alpaca"}}; + std::multimap u; + u.merge(ma); + std::cout << "ma.size(): " << ma.size() << '\\n'; + u.merge(mb); + std::cout << "mb.size(): " << mb.size() << '\\n'; + + for (auto const& kv : u) + std::cout << kv.first << ", " << kv.second << '\\n'; + } + +.SH Output: + + ma.size(): 0 + mb.size(): 0 + 1, apple + 2, zorro + 4, batman + 5, pear + 5, X + 8, alpaca + 10, banana + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::multimap.3 b/man/std::multimap::multimap.3 index 21eb996d1..f9969d973 100644 --- a/man/std::multimap::multimap.3 +++ b/man/std::multimap::multimap.3 @@ -1,58 +1,80 @@ -.TH std::multimap::multimap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::multimap \- std::multimap::multimap + .SH Synopsis - explicit multimap( const Compare& comp = Compare(), (until - const Allocator& alloc = C++14) - Allocator() ); - multimap : multimap( Compare() ) {} - - explicit multimap( const Compare& comp, (since - C++14) - const Allocator& alloc = - Allocator() ); - explicit multimap( const Allocator& alloc ); \fB(1)\fP (since - C++11) + multimap(); \fI(until C++11)\fP + multimap() \fI(since C++11)\fP + : multimap(Compare()) {} + explicit multimap( const Compare& comp, \fB(2)\fP + const Allocator& alloc = Allocator() ); + explicit multimap( const Allocator& alloc ); \fB(3)\fP \fI(since C++11)\fP template< class InputIt > - multimap( InputIt first, InputIt last, + multimap( InputIt first, InputIt last, \fB(4)\fP const Compare& comp = Compare(), const Allocator& alloc = Allocator() ); - template< class InputIt > \fB(1)\fP - (since - multimap( InputIt first, InputIt last, C++14) + template< class InputIt > + + multimap( InputIt first, InputIt last, \fB(5)\fP \fI(since C++14)\fP + const Allocator& alloc ) + + : multimap(first, last, Compare(), alloc) {} + multimap( const multimap& other ); \fB(6)\fP + multimap( const multimap& other, const Allocator& alloc ); \fB(7)\fP \fI(since C++11)\fP + multimap( multimap&& other ); \fB(8)\fP \fI(since C++11)\fP + multimap( multimap&& other, const Allocator& alloc ); \fB(9)\fP \fI(since C++11)\fP + multimap( std::initializer_list init, \fB(1)\fP + + const Compare& comp = Compare(), \fB(10)\fP \fI(since C++11)\fP const Allocator& alloc = Allocator() ); - multimap( const multimap& other ); \fB(3)\fP - multimap( const multimap& other, const Allocator& \fB(2)\fP \fB(3)\fP (since - alloc ); C++11) - multimap( multimap&& other ); \fB(4)\fP (since - C++11) - multimap( multimap&& other, const Allocator& alloc \fB(4)\fP (since - ); C++11) multimap( std::initializer_list init, - (since - const Compare& comp = Compare(), C++11) - \fB(5)\fP + + const Allocator& alloc ) \fB(11)\fP \fI(since C++14)\fP + + : multimap(init, Compare(), alloc) {} + template< container-compatible-range R > + + multimap( std::from_range_t, R&& rg, \fB(12)\fP (since C++23) + const Compare& comp = Compare(), + const Allocator& alloc = Allocator() ); - multimap( std::initializer_list init, (since - const Allocator& alloc = Allocator() ); C++14) + template< container-compatible-range R > + + multimap( std::from_range_t, R&& rg, + const Allocator& alloc ) \fB(13)\fP (since C++23) + + : multimap(std::from_range, std::forward(rg), + Compare(), alloc) {} Constructs new container from a variety of data sources and optionally using user supplied allocator alloc or comparison function object comp. - 1) Default constructor. Constructs empty container. + 1-3) Constructs an empty container. + 4,5) Constructs the container with the contents of the range [first, last). + If [first, last) is not a valid range, the behavior is undefined. + 6,7) Copy constructor. Constructs the container with the copy of the contents of + other. - 2) Constructs the container with the contents of the range [first, last). + If alloc is not provided, allocator is obtained by calling (since + std::allocator_traits:: C++11) + select_on_container_copy_construction(other.get_allocator()). + During class template argument deduction, only the first argument contributes (since + to the deduction of the container's Allocator template parameter. C++23) - 3) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). + 8,9) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. - 4) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. - 5) Constructs the container with the contents of the initializer list init. + 10,11) Initializer-list constructor. Constructs the container with the contents of + the initializer list init. + 12,13) Constructs the container with the contents of rg. .SH Parameters @@ -62,9 +84,11 @@ other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - Compare must meet the requirements of Compare. - @@ -72,163 +96,118 @@ .SH Complexity - 1) Constant + 1-3) Constant. + 4,5) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + std::distance(first, last) in general, linear in \\(\\scriptsize N\\)N if [first, last) + is already sorted by value_comp(). + 6,7) Linear in size of other. + 8,9) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 10,11) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + init.size() in general, linear in \\(\\scriptsize N\\)N if init is already sorted by + value_comp(). + 12,13) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + ranges::distance(rg) in general, linear in \\(\\scriptsize N\\)N if rg is already + sorted by value_comp(). - 2) N log(N) where N = std::distance(first, last) in general, linear in N if the - range is already sorted by value_comp(). +.SH Exceptions - 3) Linear in size of other + Calls to Allocator::allocate may throw. - 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. +.SH Notes - 5) N log(N) where N = init.size()) in general, linear in N if init is already sorted - by value_comp(). + After container move construction (overload (8,9)), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. + + Although not formally required until C++23, some implementations has already put the + template parameter Allocator into non-deduced contexts in earlier modes. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (12,13) .SH Example - + // Run this code #include - #include #include - - //declare printers for maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - - int main() + #include + + struct Point { double x, y; }; + + struct PointCmp { - typedef std::string Key; - typedef int Mapped; - - // (1) Default constructor - std::map map; - map["something"] = 69; - map["anything"] = 199; - map["that thing"] = 50; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (2) Iterator constructor - std::map iter(map.find("anything"), map.end()); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "iter = " << iter << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (3) Copy constructor - std::map copy(map); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "copy = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (4) Move constructor - std::map moved(std::move(map)); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "moved = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (5) Initializer list constructor - const std::map init { - {"this", 100}, - {"can", 100}, - {"be", 100}, - {"const", 100}, - }; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "init = " << init << '\\n'; - } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ':' << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A specialization for Key strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":" << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; + bool operator()(const Point& lhs, const Point& rhs) const + { + return lhs.x < rhs.x; // NB. ignores y on purpose + } + }; + + template + void println(auto rem, std::multimap const& map) + { + std::cout << rem << "{ "; + for (auto n{map.size()}; auto const& p : map) + std::cout << '[' << p.first << ":" << p.second << (--n ? "], " : "]"); + std::cout << " }\\n"; } - - // A specialization for Key and Mapped strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; + + int main() + { + std::multimap m1 = + { + {1, 1}, {2, 2}, {3, 3}, {4, 4}, {4, 4}, {3, 3}, {2, 2}, {1, 1} + }; + println("m1 = ", m1); + + // Custom comparison + std::multimap mag + { + {{5, 12}, 13}, + {{3, 4}, 5}, + {{8, 15}, 17}, + {{3, -3}, -1} + }; + for (auto p : mag) + std::cout << "The magnitude of (" << p.first.x << ", " << p.first.y << ")" + " is " << p.second << '\\n'; + + std::cout << "Construction from a range:\\n"; + using PS = std::pair; + const auto rg = {PS{3, "Earth"}, {2, "Venus"}, {1, "Mercury"}, {3, "Moon"}}; + #if __cpp_lib_containers_ranges + std::multimap m2(std::from_range, rg); // overload (12) + #else + std::multimap m2(rg.begin(), rg.end()); // fallback to (4) + #endif + println("m2 = ", m2); } .SH Output: - -------------------------------------------------------------------------------- - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - iter = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - copy = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - moved = {"anything":199, "something":69, "that thing":50} - map = {} - -------------------------------------------------------------------------------- - init = {"be":100, "can":100, "const":100, "this":100} - - This section is incomplete - Reason: cleanup/shorten this example + m1 = { [1:1], [1:1], [2:2], [2:2], [3:3], [3:3], [4:4], [4:4] } + The magnitude of (3, 4) is 5 + The magnitude of (3, -3) is -1 + The magnitude of (5, 12) is 13 + The magnitude of (8, 15) is 17 + Construction from a range: + m2 = { [1:Mercury], [2:Venus], [3:Earth], [3:Moon] } -.SH See also + Defect reports - operator= assigns values to the container - \fI(public member function)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + LWG 2076 C++11 overload \fB(4)\fP conditionally required Keyand T not required + to be CopyInsertable into *this + LWG 2193 C++11 the default constructor was explicit made non-explicit - * Todo with reason +.SH See also + + operator= assigns values to the container + \fI(public member function)\fP diff --git a/man/std::multimap::operator=.3 b/man/std::multimap::operator=.3 index 41bd67065..b43fd37ca 100644 --- a/man/std::multimap::operator=.3 +++ b/man/std::multimap::operator=.3 @@ -1,27 +1,41 @@ -.TH std::multimap::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::operator= \- std::multimap::operator= + .SH Synopsis - multimap& operator=( const multimap& other ); \fB(1)\fP - multimap& operator=( multimap&& other ); \fB(2)\fP \fI(since C++11)\fP - multimap& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + multimap& operator=( const multimap& other ); \fB(1)\fP + multimap& operator=( multimap&& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + multimap& operator=( multimap&& other ) noexcept(/* see below \fB(2)\fP \fI(since C++17)\fP + */); + multimap& operator=( std::initializer_list ilist \fB(3)\fP \fI(since C++11)\fP + ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,67 +49,98 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) O(NlogN) in general, where N is size() + ilist.size(). Linear if ilist is sorted + with respect to value_comp(). + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::multimap to another: - The following code uses to assign one std::multimap to another: - // Run this code - #include + #include #include - - void display_sizes(const std::multimap &nums1, - const std::multimap &nums2, - const std::multimap &nums3) + #include + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& [key, value] : container) + std::cout << '{' << key << ',' << value << (--size ? "}, " : "} "); + std::cout << "}\\n"; } - + int main() { - std::multimap nums1 {{3, 1}, {4, 1}, {5, 9}, - {6, 1}, {7, 1}, {8, 9}}; - std::multimap nums2; - std::multimap nums3; - + std::multimap x{{1,1}, {2,2}, {3,3}}, y, z; + const auto w = {std::pair{4,4}, {5,5}, {6,6}, {7,7}}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { {1,1}, {2,2}, {3,3} } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { {1,1}, {2,2}, {3,3} } + y = { {1,1}, {2,2}, {3,3} } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { {1,1}, {2,2}, {3,3} } + Assignment of initializer_list w to z: + w = { {4,4}, {5,5}, {6,6}, {7,7} } + z = { {4,4}, {5,5}, {6,6}, {7,7} } .SH See also constructor constructs the multimap - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::multimap::rbegin,.3 b/man/std::multimap::rbegin,.3 new file mode 100644 index 000000000..6a2936107 --- /dev/null +++ b/man/std::multimap::rbegin,.3 @@ -0,0 +1,90 @@ +.TH std::multimap::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::rbegin, \- std::multimap::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns a reverse iterator to the first element of the reversed multimap. It + corresponds to the last element of the non-reversed multimap. If the multimap is + empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::multimap map + { + {"█", 1}, + {"▒", 5}, + {"░", 3}, + {"▓", 7}, + {"▓", 8}, + {"░", 4}, + {"▒", 6}, + {"█", 2} + }; + + std::cout << "Print out in reverse order using const reverse iterators:\\n"; + std::for_each(map.crbegin(), map.crend(), + [](std::pair const& e) + { + std::cout << "{ \\"" << e.first << "\\", " << e.second << " };\\n"; + }); + + map.rbegin()->second = 42; // OK: non-const value is modifiable + // map.crbegin()->second = 42; // Error: cannot modify the const value + } + +.SH Possible output: + + Print out in reverse order using const reverse iterators: + { "▓", 8 }; + { "▓", 7 }; + { "▒", 6 }; + { "▒", 5 }; + { "░", 4 }; + { "░", 3 }; + { "█", 2 }; + { "█", 1 }; + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multimap::rbegin,std::multimap::crbegin.3 b/man/std::multimap::rbegin,std::multimap::crbegin.3 deleted file mode 100644 index 97ffa9f8b..000000000 --- a/man/std::multimap::rbegin,std::multimap::crbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::multimap::rbegin,std::multimap::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP - - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. - - range-rbegin-rend.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Reverse iterator to the first element. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. - -.SH See also - - rend returns a reverse iterator to the end - crend \fI(public member function)\fP diff --git a/man/std::multimap::rend,.3 b/man/std::multimap::rend,.3 new file mode 100644 index 000000000..49a66a726 --- /dev/null +++ b/man/std::multimap::rend,.3 @@ -0,0 +1,89 @@ +.TH std::multimap::rend, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::rend, \- std::multimap::rend, + +.SH Synopsis + + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns a reverse iterator to the element following the last element of the reversed + multimap. It corresponds to the element preceding the first element of the + non-reversed multimap. This element acts as a placeholder, attempting to access it + results in undefined behavior. + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the element following the last element. + +.SH Complexity + + Constant. + +.SH Notes + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + using namespace std::chrono; + + int main() + { + const std::multimap messages + { + {February/17/2023, 10}, + {February/17/2023, 20}, + {February/16/2022, 30}, + {October/22/2022, 40}, + {June/14/2022, 50}, + {November/23/2021, 60}, + {December/10/2022, 55}, + {December/12/2021, 45}, + {April/1/2020, 42}, + {April/1/2020, 24} + }; + + std::cout << "Messages received (date order is reversed):\\n"; + for (auto it = messages.crbegin(); it != messages.crend(); ++it) + std::cout << it->first << " : " << it->second << '\\n'; + } + +.SH Possible output: + + Messages received (date order is reversed): + 2023-02-17 : 20 + 2023-02-17 : 10 + 2022-12-10 : 55 + 2022-10-22 : 40 + 2022-06-14 : 50 + 2022-02-16 : 30 + 2021-12-12 : 45 + 2021-11-23 : 60 + 2020-04-01 : 24 + 2020-04-01 : 42 + +.SH See also + + rbegin returns a reverse iterator to the beginning + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multimap::rend,std::multimap::crend.3 b/man/std::multimap::rend,std::multimap::crend.3 deleted file mode 100644 index 66dd0f26a..000000000 --- a/man/std::multimap::rend,std::multimap::crend.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH std::multimap::rend,std::multimap::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP - - Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it - results in undefined behavior. - - range-rbegin-rend.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Reverse iterator to the element following the last element. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. - -.SH See also - - rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP diff --git a/man/std::multimap::size.3 b/man/std::multimap::size.3 index 97b37e13e..09783eab0 100644 --- a/man/std::multimap::size.3 +++ b/man/std::multimap::size.3 @@ -1,6 +1,9 @@ -.TH std::multimap::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::size \- std::multimap::size + .SH Synopsis - size_type size() const; + size_type size() const; (noexcept since C++11) Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,26 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Example - + The following code uses size to display the number of elements in a std::multimap: - + // Run this code - #include #include - + #include + int main() { - std::multimap nums {{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; - + std::multimap nums{{1, 'a'}, {3, 'b'}, {5, 'c'}, {7, 'd'}}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +45,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::multimap::swap.3 b/man/std::multimap::swap.3 index ab4bf9aeb..3dd3d873d 100644 --- a/man/std::multimap::swap.3 +++ b/man/std::multimap::swap.3 @@ -1,19 +1,23 @@ -.TH std::multimap::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::swap \- std::multimap::swap + .SH Synopsis - void swap( multimap& other ); + void swap( multimap& other ); \fI(until C++17)\fP + void swap( multimap& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. + + The Compare objects must be Swappable, and they are exchanged using unqualified call + to non-member swap. - The Pred objects must be Swappable, and they are exchanged using unqualified call to - non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +29,83 @@ .SH Exceptions - Any exception thrown by the swap of the Compare objects. + Any exception thrown by the swap of the Compare objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + #include + + // print out a std::pair + template + Os& operator<<(Os& os, const std::pair& p) + { + return os << p.first << ':' << p.second; + } + + // print out a container + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " }\\n"; + } + + int main() + { + std::multimap + m1{{"γ", "gamma"}, {"β", "beta"}, {"α", "alpha"}, {"γ", "gamma"}}, + m2{{"ε", "epsilon"}, {"δ", "delta"}, {"ε", "epsilon"}}; + + const auto& ref = *(m1.begin()); + const auto iter = std::next(m1.cbegin()); + + std::cout << "──────── before swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + m1.swap(m2); + + std::cout << "──────── after swap ────────\\n" + << "m1: " << m1 << "m2: " << m2 << "ref: " << ref + << "\\niter: " << *iter << '\\n'; + + // Note that every iterator referring to an element in one container before + // the swap refers to the same element in the other container after the swap. + // Same is true for references. + } + +.SH Output: + + ──────── before swap ──────── + m1: { α:alpha β:beta γ:gamma γ:gamma } + m2: { δ:delta ε:epsilon ε:epsilon } + ref: α:alpha + iter: β:beta + ──────── after swap ──────── + m1: { δ:delta ε:epsilon ε:epsilon } + m2: { α:alpha β:beta γ:gamma γ:gamma } + ref: α:alpha + iter: β:beta + .SH See also std::swap(std::multimap) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::multimap::upper_bound.3 b/man/std::multimap::upper_bound.3 index 2279c235a..3437086ff 100644 --- a/man/std::multimap::upper_bound.3 +++ b/man/std::multimap::upper_bound.3 @@ -1,17 +1,20 @@ -.TH std::multimap::upper_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::upper_bound \- std::multimap::upper_bound + .SH Synopsis iterator upper_bound( const Key& key ); \fB(1)\fP - const_iterator upper_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP iterator upper_bound( const K& x ); - template< class K > \fB(2)\fP \fI(since C++14)\fP + template< class K > \fB(4)\fP \fI(since C++14)\fP const_iterator upper_bound( const K& x ) const; - 1) Returns an iterator pointing to the first element that is greater than key. - 2) Returns an iterator pointing to the first element that compares greater to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -27,9 +30,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multimap::value_comp.3 b/man/std::multimap::value_comp.3 index c98372e6e..567fa5232 100644 --- a/man/std::multimap::value_comp.3 +++ b/man/std::multimap::value_comp.3 @@ -1,4 +1,7 @@ -.TH std::multimap::value_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::value_comp \- std::multimap::value_comp + .SH Synopsis std::multimap::value_compare value_comp() const; @@ -17,7 +20,57 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::multimap cont; + cont = {{1, 'a'}, {2, 'b'}, {3, 'c'}, {4, 'd'}, {5, 'e'}}; + + auto comp_func = cont.value_comp(); + + for (const std::pair val = {100, 'a'}; auto it : cont) + { + const bool before = comp_func(it, val); + const bool after = comp_func(val, it); + + std::cout << '(' << it.first << ',' << it.second << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val.first << ")\\n"; + else if (before) + std::cout << "goes before key (" << val.first << ")\\n"; + else if (after) + std::cout << "goes after key (" << val.first << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + (1,a) goes before key (100) + (2,b) goes before key (100) + (3,c) equivalent to key (100) + (4,d) goes after key (100) + (5,e) goes after key (100) + .SH See also key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multimap::value_compare.3 b/man/std::multimap::value_compare.3 index 89d5cb2b7..955666c13 100644 --- a/man/std::multimap::value_compare.3 +++ b/man/std::multimap::value_compare.3 @@ -1,4 +1,7 @@ -.TH std::multimap::value_compare 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::value_compare 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::value_compare \- std::multimap::value_compare + .SH Synopsis class value_compare; @@ -8,24 +11,27 @@ .SH Member types - Type Definition - result_type bool - first_argument_type value_type - second_argument_type value_type + Type Definition + result_type (deprecated in C++17)(removed in C++20) bool + first_argument_type (deprecated in C++17)(removed in C++20) value_type + second_argument_type (deprecated in C++17)(removed in C++20) value_type + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Protected member objects - Name Type - comp Compare + Compare comp the stored comparator + \fI(protected member object)\fP .SH Member functions constructor constructs a new value_compare object - \fI(protected member function)\fP + \fI(protected member function)\fP operator() compares two values of type value_type - \fI(public member function)\fP + \fI(public member function)\fP - std::multimap::value_compare::value_compare +std::multimap::value_compare::value_compare protected: value_compare( Compare c ); @@ -36,7 +42,7 @@ c - comparator to assign - std::multimap::value_compare::operator() +std::multimap::value_compare::operator() bool operator()( const value_type& lhs, const value_type& rhs ) const; @@ -48,8 +54,8 @@ .SH Return value - comp(lhs.first, rhs.first). + comp(lhs.first, rhs.first) .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. diff --git a/man/std::multimap::~multimap.3 b/man/std::multimap::~multimap.3 index c2651cac8..66cf6cd91 100644 --- a/man/std::multimap::~multimap.3 +++ b/man/std::multimap::~multimap.3 @@ -1,11 +1,14 @@ -.TH std::multimap::~multimap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multimap::~multimap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multimap::~multimap \- std::multimap::~multimap + .SH Synopsis ~multimap(); - Destructs the container. The destructors of the elements are called and the used + Destructs the multimap. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the multimap. diff --git a/man/std::multiplies.3 b/man/std::multiplies.3 index 35df5bc1f..5da4019d0 100644 --- a/man/std::multiplies.3 +++ b/man/std::multiplies.3 @@ -1,40 +1,27 @@ -.TH std::multiplies 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiplies 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiplies \- std::multiplies + .SH Synopsis Defined in header - template< class T > \fI(until C++14)\fP - struct multiplies; - template< class T = void > \fI(since C++14)\fP - struct multiplies; - - Function object for performing multiplication. Effectively calls operator* on two - instances of type T. - -.SH Specializations + template<> \fI(since C++14)\fP + class multiplies; - The standard library provides a specialization of std::multiplies when - T is not specified, which leaves the parameter types and return type - to be deduced. - \fI(since C++14)\fP - function object implementing x * y deducing argument - multiplies and return types - \fI(class template specialization)\fP - -.SH Member types - - Type Definition - result_type T - first_argument_type T - second_argument_type T + std::multiplies is a specialization of std::multiplies with parameter and + return type deduced. .SH Member functions operator() returns the product of two arguments \fI(public member function)\fP - std::multiplies::operator() +std::multiplies::operator() + + template< class T, class U > - T operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP - constexpr T operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP + constexpr auto operator()( T&& lhs, U&& rhs ) const + + -> decltype(std::forward(lhs) * std::forward(rhs)); Returns the product of lhs and rhs. @@ -44,15 +31,30 @@ .SH Return value - The result of lhs * rhs. + std::forward(lhs) * std::forward(rhs). + +.SH Example + + +// Run this code + + #include + #include + #include -.SH Exceptions + int main() + { + auto complex_multiplies = std::multiplies{}; // “void” can be omitted + constexpr std::complex z1{1.0, 2.0}, z2{3.0, 4.0}; - \fI(none)\fP + std::cout << std::showpos + << complex_multiplies(z1, z2) << ' ' << z1 * z2 << '\\n' + << complex_multiplies(z1, 5.) << ' ' << z1 * 5. << '\\n' + << complex_multiplies(5., z1) << ' ' << 5. * z1 << '\\n'; + } -.SH Possible implementation +.SH Output: - constexpr T operator()(const T &lhs, const T &rhs) const - { - return lhs * rhs; - } + (-5,+10) (-5,+10) + (+5,+10) (+5,+10) + (+5,+10) (+5,+10) diff --git a/man/std::multiplies.3 b/man/std::multiplies.3 deleted file mode 100644 index 555c8249e..000000000 --- a/man/std::multiplies.3 +++ /dev/null @@ -1,55 +0,0 @@ -.TH std::multiplies 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class multiplies; - - std::multiplies<> is a specialization of std::multiplies with parameter and return - type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() returns the product of two arguments - \fI(public member function)\fP - - std::multiplies<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) * std::forward(rhs)); - - Returns the result of multiplying lhs by rhs (or whatever operator* is overloaded to - do) - -.SH Parameters - - lhs, rhs - values to multiply - -.SH Return value - - The result of lhs * rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::multiset.3 b/man/std::multiset.3 index 312f66070..15a2ea42d 100644 --- a/man/std::multiset.3 +++ b/man/std::multiset.3 @@ -1,120 +1,197 @@ -.TH std::multiset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset \- std::multiset + .SH Synopsis Defined in header template< class Key, - class Compare = std::less, + class Compare = std::less, \fB(1)\fP class Allocator = std::allocator > class multiset; + namespace pmr { + + template< + class Key, + class Compare = std::less \fB(2)\fP \fI(since C++17)\fP + > using multiset = std::multiset>; + + } - Multiset is an associative container that contains a sorted set of objects of type - Key. Unlike set, multiple keys with equal values are allowed. Sorting is done using - the key comparison function Compare. Search, insertion, and removal operations have - logarithmic complexity. + std::multiset is an associative container that contains a sorted set of objects of + type Key. Unlike set, multiple keys with equivalent values are allowed. Sorting is + done using the key comparison function Compare. Search, insertion, and removal + operations have logarithmic complexity. - The order of the elements that compare equivalent is the order of insertion and does - not change. \fI(since C++11)\fP + Everywhere the standard library uses the Compare requirements, equivalence is + determined by using the equivalence relation as described on Compare. In imprecise + terms, two objects a and b are considered equivalent if neither compares less than + the other: !comp(a, b) && !comp(b, a). + + The order of the elements that compare equivalent is the order of \fI(since C++11)\fP + insertion and does not change. std::multiset meets the requirements of Container, AllocatorAwareContainer, AssociativeContainer and ReversibleContainer. +.SH Template parameters + + This section is incomplete + Reason: Add descriptions of the template parameters. + .SH Member types - Member type Definition - key_type Key - value_type Key - size_type Unsigned integral type (usually std::size_t) - difference_type Signed integer type (usually std::ptrdiff_t) - key_compare Compare - value_compare Compare - allocator_type Allocator - reference Allocator::reference \fI(until C++11)\fP - value_type& \fI(since C++11)\fP - const_reference Allocator::const_reference \fI(until C++11)\fP - const value_type& \fI(since C++11)\fP - Allocator::pointer \fI(until C++11)\fP - pointer std::allocator_traits::pointer \fI(since C++11)\fP - - Allocator::const_pointer \fI(until C++11)\fP - const_pointer std::allocator_traits::const_pointer \fI(since C++11)\fP - - iterator BidirectionalIterator \fI(until C++11)\fP - Constant bidirectional iterator \fI(since C++11)\fP - const_iterator Constant bidirectional iterator - reverse_iterator std::reverse_iterator - const_reverse_iterator std::reverse_iterator + Member type Definition + key_type Key + value_type Key + size_type Unsigned integer type (usually std::size_t) + difference_type Signed integer type (usually std::ptrdiff_t) + key_compare Compare + value_compare Compare + allocator_type Allocator + reference value_type& + const_reference const value_type& + Allocator::pointer \fI(until C++11)\fP + pointer std::allocator_traits::pointer \fI(since C++11)\fP + + + Allocator::const_pointer (until + C++11) + const_pointer std::allocator_traits::const_pointer (since + C++11) + + + iterator Constant LegacyBidirectionalIterator to value_type + const_iterator LegacyBidirectionalIterator to const value_type + reverse_iterator std::reverse_iterator + const_reverse_iterator std::reverse_iterator + node_type \fI(since C++17)\fP a specialization of node handle representing a container + node .SH Member functions constructor constructs the multiset - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the multiset - \fI(public member function)\fP + \fI(public member function)\fP operator= assigns values to the container - \fI(public member function)\fP + \fI(public member function)\fP get_allocator returns the associated allocator - \fI(public member function)\fP + \fI(public member function)\fP .SH Iterators begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + cbegin \fI(public member function)\fP + \fI(C++11)\fP end returns an iterator to the end - cend \fI(public member function)\fP + cend \fI(public member function)\fP + \fI(C++11)\fP rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP rend returns a reverse iterator to the end - crend \fI(public member function)\fP + crend \fI(public member function)\fP + \fI(C++11)\fP .SH Capacity empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP .SH Modifiers clear clears the contents - \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + insert_range inserts a range of elements + (C++23) \fI(public member function)\fP emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP swap swaps the contents - \fI(public member function)\fP + \fI(public member function)\fP + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP .SH Lookup count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP .SH Observers key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions operator== operator!= - operator< lexicographically compares the values in the multiset - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values of two multisets + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::multiset) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + erase_if(std::multiset) erases all elements satisfying specific criteria + (C++20) \fI(function template)\fP + + Deduction guides \fI(since C++17)\fP .SH Notes - The member types iterator and const_iterator may be aliases to the same type. Since - iterator is convertible to const_iterator, const_iterator should be used in function - parameter lists to avoid violations of the One Definition Rule. + The member types iterator and const_iterator may be aliases to the same type. This + means defining a pair of function overloads using the two types as parameter types + may violate the One Definition Rule. Since iterator is convertible to + const_iterator, a single function with a const_iterator as parameter type will work + instead. + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges construction and insertion for + containers + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 103 C++98 iterator allows modification of keys iterator made constant + Key was not required to be + LWG 230 C++98 CopyConstructible Key is also required to + (a key of type Key might not be able to be CopyConstructible + be constructed) + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::multiset::begin,std::multiset::cbegin.3 b/man/std::multiset::begin,std::multiset::cbegin.3 index 45dc3bd50..a1d0d8176 100644 --- a/man/std::multiset::begin,std::multiset::cbegin.3 +++ b/man/std::multiset::begin,std::multiset::cbegin.3 @@ -1,12 +1,15 @@ -.TH std::multiset::begin,std::multiset::cbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::begin,std::multiset::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::begin,std::multiset::cbegin \- std::multiset::begin,std::multiset::cbegin + .SH Synopsis - iterator begin(); - const_iterator begin() const; - const_iterator cbegin() const; \fI(since C++11)\fP + iterator begin(); \fB(1)\fP (noexcept since C++11) + const_iterator begin() const; \fB(2)\fP (noexcept since C++11) + const_iterator cbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the first element of the container. + Returns an iterator to the first element of the multiset. - If the container is empty, the returned iterator will be equal to end(). + If the multiset is empty, the returned iterator will be equal to end(). range-begin-end.svg @@ -16,20 +19,62 @@ .SH Return value - Iterator to the first element + Iterator to the first element. -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Constant. -.SH Complexity +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + libc++ backports cbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::multiset words = + { + "some", "not", "sorted", "words", + "will", "come", "out", "sorted", + }; + + for (auto it = words.begin(); it != words.end(); ) + { + auto count = words.count(*it); + std::cout << *it << ":\\t" << count << '\\n'; + std::advance(it, count); // all count elements have equivalent keys + } + } + +.SH Output: - Constant + come: 1 + not: 1 + out: 1 + some: 1 + sorted: 2 + will: 1 + words: 1 .SH See also - end returns an iterator to the end - cend \fI(public member function)\fP + end returns an iterator to the end + cend \fI(public member function)\fP + \fI(C++11)\fP + begin + cbegin returns an iterator to the beginning of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multiset::clear.3 b/man/std::multiset::clear.3 index d4e009985..3ce5eeb51 100644 --- a/man/std::multiset::clear.3 +++ b/man/std::multiset::clear.3 @@ -1,11 +1,14 @@ -.TH std::multiset::clear 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::clear 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::clear \- std::multiset::clear + .SH Synopsis - void clear(); + void clear(); (noexcept since C++11) - Removes all elements from the container. + Erases all elements from the container. After this call, size() returns zero. - Invalidates any references, pointers, or iterators referring to contained elements. - May invalidate any past-the-end iterators. + Invalidates any references, pointers, and iterators referring to contained elements. + Any past-the-end iterator remains valid. .SH Parameters @@ -15,18 +18,53 @@ \fI(none)\fP -.SH Exceptions +.SH Complexity - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + Linear in the size of the container, i.e., the number of elements. -.SH Complexity +.SH Example + + +// Run this code + + #include + #include + #include + + void print_info(std::string_view rem, const std::multiset& v) + { + std::cout << rem << "{ "; + for (const auto& value : v) + std::cout << value << ' '; + std::cout << "}\\n"; + std::cout << "Size=" << v.size() << '\\n'; + } + + int main() + { + std::multiset container{1, 2, 3}; + print_info("Before clear: ", container); + container.clear(); + print_info("After clear: ", container); + } + +.SH Output: + + Before clear: { 1 2 3 } + Size=3 + After clear: { } + Size=0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - Linear in the size of the container. + DR Applied to Behavior as published Correct behavior + LWG 224 C++98 the complexity was log(size()) + N, but N corrected to 'linear in + was not defined size()' .SH See also erase erases elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::contains.3 b/man/std::multiset::contains.3 new file mode 100644 index 000000000..88d606838 --- /dev/null +++ b/man/std::multiset::contains.3 @@ -0,0 +1,60 @@ +.TH std::multiset::contains 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::contains \- std::multiset::contains + +.SH Synopsis + bool contains( const Key& key ) const; \fB(1)\fP \fI(since C++20)\fP + template< class K > \fB(2)\fP \fI(since C++20)\fP + bool contains( const K& x ) const; + + 1) Checks if there is an element with key equivalent to key in the container. + 2) Checks if there is an element with key that compares equivalent to the value x. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. + +.SH Parameters + + key - key value of the element to search for + x - a value of any type that can be transparently compared with a key + +.SH Return value + + true if there is such an element, otherwise false. + +.SH Complexity + + Logarithmic in the size of the container. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::multiset example{1, 2, 3, 4}; + + for (int x : {2, 5}) + if (example.contains(x)) + std::cout << x << ": Found\\n"; + else + std::cout << x << ": Not found\\n"; + } + +.SH Output: + + 2: Found + 5: Not found + +.SH See also + + find finds element with specific key + \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(public member function)\fP diff --git a/man/std::multiset::count.3 b/man/std::multiset::count.3 index 592c9c961..aa86541e9 100644 --- a/man/std::multiset::count.3 +++ b/man/std::multiset::count.3 @@ -1,14 +1,20 @@ -.TH std::multiset::count 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::count 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::count \- std::multiset::count + .SH Synopsis size_type count( const Key& key ) const; \fB(1)\fP template< class K > \fB(2)\fP \fI(since C++14)\fP size_type count( const K& x ) const; + Returns the number of elements with key that compares equivalent to the specified + argument. + 1) Returns the number of elements with key key. 2) Returns the number of elements with key that compares equivalent to the value x. - These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -17,16 +23,31 @@ .SH Return value - Number of elements with key key. + Number of elements with key that compares equivalent to key or x. .SH Complexity - Logarithmic in the size of the container plus linear in the number of the elements + Logarithmic in the size of the container plus linear in the number of elements found. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overload \fB(2)\fP + +.SH Example + + This section is incomplete + Reason: no example + .SH See also find finds element with specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multiset::emplace.3 b/man/std::multiset::emplace.3 index bb29c3343..1cff7860f 100644 --- a/man/std::multiset::emplace.3 +++ b/man/std::multiset::emplace.3 @@ -1,15 +1,18 @@ -.TH std::multiset::emplace 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::emplace \- std::multiset::emplace + .SH Synopsis template< class... Args > \fI(since C++11)\fP iterator emplace( Args&&... args ); - Inserts a new element into the container by constructing it in-place with the given - args. + Inserts a new element into the container constructed in-place with the given args. + + The constructor of the new element is called with exactly the same arguments as + supplied to emplace, forwarded via std::forward(args).... Careful use of emplace allows the new element to be constructed while avoiding - unnecessary copy or move operations. The constructor of the new element is called - with exactly the same arguments as supplied to emplace, forwarded via - std::forward(args).... + unnecessary copy or move operations. No iterators or references are invalidated. @@ -19,11 +22,12 @@ .SH Return value - Returns an iterator to the inserted element. + An iterator to the inserted element. .SH Exceptions - If an exception is thrown by any operation, this function has no effect. + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity @@ -31,16 +35,92 @@ .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + + class Dew + { + private: + int a, b, c; + + public: + Dew(int _a, int _b, int _c) + : a(_a), b(_b), c(_c) + {} + + bool operator<(const Dew& other) const + { + return (a < other.a) || + (a == other.a && b < other.b) || + (a == other.a && b == other.b && c < other.c); + } + }; + + constexpr int nof_operations{101}; + + std::size_t set_emplace() + { + std::multiset set; + for (int i = 0; i < nof_operations; ++i) + for (int j = 0; j < nof_operations; ++j) + for (int k = 0; k < nof_operations; ++k) + set.emplace(i, j, k); + + return set.size(); + } + + std::size_t set_insert() + { + std::multiset set; + for (int i = 0; i < nof_operations; ++i) + for (int j = 0; j < nof_operations; ++j) + for (int k = 0; k < nof_operations; ++k) + set.insert(Dew(i, j, k)); + + return set.size(); + } + + void time_it(std::function set_test, std::string what = "") + { + const auto start = std::chrono::system_clock::now(); + const auto the_size = set_test(); + const auto stop = std::chrono::system_clock::now(); + const std::chrono::duration time = stop - start; + if (!what.empty() && the_size) + std::cout << std::fixed << std::setprecision(2) + << time << " for " << what << '\\n'; + } + + int main() + { + time_it(set_insert, "cache warming..."); + time_it(set_insert, "insert"); + time_it(set_insert, "insert"); + time_it(set_emplace, "emplace"); + time_it(set_emplace, "emplace"); + } + +.SH Possible output: + + 499.61ms for cache warming... + 447.89ms for insert + 436.77ms for insert + 430.62ms for emplace + 428.61ms for emplace .SH See also emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::emplace_hint.3 b/man/std::multiset::emplace_hint.3 index c9155f907..f9887df4f 100644 --- a/man/std::multiset::emplace_hint.3 +++ b/man/std::multiset::emplace_hint.3 @@ -1,34 +1,51 @@ -.TH std::multiset::emplace_hint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::emplace_hint 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::emplace_hint \- std::multiset::emplace_hint + .SH Synopsis - template \fI(since C++11)\fP + template< class... Args > \fI(since C++11)\fP iterator emplace_hint( const_iterator hint, Args&&... args ); - Inserts a new element to the container, using hint as a suggestion where the element - should go. The element is constructed in-place, i.e. no copy or move operations are - performed. + Inserts a new element into the container as close as possible to the position just + before hint. - The constructor of the element is called with exactly the same arguments as supplied - to the function, forwarded with std::forward(args).... + The constructors of the key and mapped value are called with exactly the same + arguments as supplied to the function, forwarded with std::forward(args).... No iterators or references are invalidated. .SH Parameters - hint - iterator, used as a suggestion as to where to insert the new element + hint - iterator to the position before which the new element will be inserted args - arguments to forward to the constructor of the element .SH Return value - Returns an iterator to the newly inserted element. + An iterator to the inserted element. + +.SH Exceptions + + If an exception is thrown for any reason, this function has no effect (strong + exception safety guarantee). .SH Complexity Logarithmic in the size of the container in general, but amortized constant if the new element is inserted just before hint. +.SH Example + + This section is incomplete + Reason: no example + .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP - insert inserts elements - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multiset::empty.3 b/man/std::multiset::empty.3 index c77e44d69..be823c620 100644 --- a/man/std::multiset::empty.3 +++ b/man/std::multiset::empty.3 @@ -1,6 +1,12 @@ -.TH std::multiset::empty 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::empty 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::empty \- std::multiset::empty + .SH Synopsis - bool empty() const; + bool empty() const; \fI(until C++11)\fP + bool empty() const noexcept; \fI(since C++11)\fP + \fI(until C++20)\fP + [[nodiscard]] bool empty() const noexcept; \fI(since C++20)\fP Checks if the container has no elements, i.e. whether begin() == end(). @@ -10,14 +16,7 @@ .SH Return value - true if the container is empty, false otherwise - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + true if the container is empty, false otherwise. .SH Complexity @@ -25,33 +24,36 @@ .SH Example - + The following code uses empty to check if a std::multiset contains any elements: - + // Run this code - #include #include - + #include + int main() { std::multiset numbers; + std::cout << std::boolalpha; std::cout << "Initially, numbers.empty(): " << numbers.empty() << '\\n'; - + numbers.insert(42); - numbers.insert(13317); + numbers.insert(19937); std::cout << "After adding elements, numbers.empty(): " << numbers.empty() << '\\n'; } .SH Output: - Initially, numbers.empty(): 1 - After adding elements, numbers.empty(): 0 + Initially, numbers.empty(): true + After adding elements, numbers.empty(): false .SH See also - size returns the number of elements - \fI(public member function)\fP + size returns the number of elements + \fI(public member function)\fP + empty checks whether the container is empty + \fI(C++17)\fP \fI(function template)\fP diff --git a/man/std::multiset::end,std::multiset::cend.3 b/man/std::multiset::end,std::multiset::cend.3 index f69bd4a16..68468a5aa 100644 --- a/man/std::multiset::end,std::multiset::cend.3 +++ b/man/std::multiset::end,std::multiset::cend.3 @@ -1,10 +1,13 @@ -.TH std::multiset::end,std::multiset::cend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::end,std::multiset::cend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::end,std::multiset::cend \- std::multiset::end,std::multiset::cend + .SH Synopsis - iterator end(); - const_iterator end() const; - const_iterator cend() const; \fI(since C++11)\fP + iterator end(); \fB(1)\fP (noexcept since C++11) + const_iterator end() const; \fB(2)\fP (noexcept since C++11) + const_iterator cend() const noexcept; \fB(3)\fP \fI(since C++11)\fP - Returns an iterator to the element following the last element of the container. + Returns an iterator to the element following the last element of the multiset. This element acts as a placeholder; attempting to access it results in undefined behavior. @@ -19,18 +22,60 @@ Iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + libc++ backports cend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + const std::multiset words = + { + "some", "not", "sorted", "words", + "will", "come", "out", "sorted", + }; + + for (auto it = words.begin(); it != words.end(); ) + { + auto count = words.count(*it); + std::cout << *it << ":\\t" << count << '\\n'; + std::advance(it, count); // all count elements have equivalent keys + } + } + +.SH Output: + + come: 1 + not: 1 + out: 1 + some: 1 + sorted: 2 + will: 1 + words: 1 + .SH See also - begin returns an iterator to the beginning - cbegin \fI(public member function)\fP + begin returns an iterator to the beginning + cbegin \fI(public member function)\fP + \fI(C++11)\fP + end + cend returns an iterator to the end of a container or array + \fI(C++11)\fP \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multiset::equal_range.3 b/man/std::multiset::equal_range.3 index f9386cbcd..00cf08c10 100644 --- a/man/std::multiset::equal_range.3 +++ b/man/std::multiset::equal_range.3 @@ -1,27 +1,27 @@ -.TH std::multiset::equal_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::equal_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::equal_range \- std::multiset::equal_range + .SH Synopsis - std::pair equal_range( const Key& key ); \fB(1)\fP - std::pair equal_range( const Key& \fB(2)\fP + std::pair equal_range( const Key& key ); \fB(1)\fP + std::pair equal_range( const Key& \fB(2)\fP key ) const; template< class K > \fB(3)\fP \fI(since C++14)\fP - std::pair equal_range( const K& x ); + std::pair equal_range( const K& x ); template< class K > - std::pair equal_range( const K& x ) \fB(4)\fP \fI(since C++14)\fP - const; + std::pair equal_range( const K& x \fB(4)\fP \fI(since C++14)\fP + ) const; Returns a range containing all elements with the given key in the container. The range is defined by two iterators, one pointing to the first element that is not - less than key and another pointing to the first element greater than key. The first - iterator may be alternatively obtained with lower_bound(), the second - with - upper_bound(). - - 1-2) Compares the keys to key. - 3,4) Compares the keys to the value x. These templates only participate in overload - resolution if the type Compare::is_transparent exists. They allow calling this - function without constructing an instance of Key. + less than key and another pointing to the first element greater than key. + Alternatively, the first iterator may be obtained with lower_bound(), and the second + with upper_bound(). - This section is incomplete - Reason: explain better + 1,2) Compares the keys to key. + 3,4) Compares the keys to the value x. This overload participates in overload + resolution only if the qualified-id Compare::is_transparent is valid and denotes a + type. It allows calling this function without constructing an instance of Key. .SH Parameters @@ -38,28 +38,80 @@ returned as the first element. Similarly if there are no elements greater than key, past-the-end iterator is returned as the second element. - Since insert always inserts at the upper bound, the order of \fI(since C++11)\fP - equivalent elements is the equal range is the order of insertion. + Since emplace and unhinted insert always insert at the upper bound, + the order of equivalent elements in the equal range is the order of \fI(since C++11)\fP + insertion unless hinted insert or emplace_hint was used to insert an + element at a different position. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + template + void print_equal_range(I first, I lb, I ub, I last) + { + for (I i{first}; i != lb; ++i) + std::cout << *i << ' '; + std::cout << "[ "; + + for (I i{lb}; i != ub; ++i) + std::cout << *i << ' '; + std::cout << ") "; + + for (I i{ub}; i != last; ++i) + std::cout << *i << ' '; + std::cout << '\\n'; + } + + int main() + { + std::multiset c{4, 3, 2, 1, 3, 3}; + std::cout << "c = "; + print_equal_range(begin(c), begin(c), end(c), end(c)); + for (int key{}; key != 6; ++key) + { + std::cout << "key = " << key << "; equal range = "; + const auto [lb, ub] = c.equal_range(key); + print_equal_range(begin(c), lb, ub, end(c)); + } + } + +.SH Output: + + c = [ 1 2 3 3 3 4 ) + key = 0; equal range = [ ) 1 2 3 3 3 4 + key = 1; equal range = [ 1 ) 2 3 3 3 4 + key = 2; equal range = 1 [ 2 ) 3 3 3 4 + key = 3; equal range = 1 2 [ 3 3 3 ) 4 + key = 4; equal range = 1 2 3 3 3 [ 4 ) + key = 5; equal range = 1 2 3 3 3 4 [ ) .SH See also find finds element with specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP - - Categories: - - * Todo with reason - * Todo no example + \fI(public member function)\fP + contains checks if the container contains element with specific key + (C++20) \fI(public member function)\fP + count returns the number of elements matching specific key + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + equal_range returns range of elements matching a specific key + \fI(function template)\fP diff --git a/man/std::multiset::erase.3 b/man/std::multiset::erase.3 index 744c2b162..0364ad279 100644 --- a/man/std::multiset::erase.3 +++ b/man/std::multiset::erase.3 @@ -1,49 +1,133 @@ -.TH std::multiset::erase 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::erase 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::erase \- std::multiset::erase + .SH Synopsis - void erase( iterator pos ); \fI(until C++11)\fP - iterator erase( const_iterator pos ); \fI(since C++11)\fP - void erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP - iterator erase( const_iterator first, \fB(2)\fP \fI(since C++11)\fP - const_iterator last ); - size_type erase( const key_type& key ); \fB(3)\fP + iterator erase( iterator pos ); (until C++23) + iterator erase( iterator pos ) + requires(!std::same_as); + iterator erase( const_iterator pos ); \fB(2)\fP \fI(since C++11)\fP + iterator erase( iterator first, iterator last ); \fB(1)\fP \fI(until C++11)\fP + iterator erase( const_iterator first, \fI(since C++11)\fP + const_iterator last ); \fB(3)\fP + size_type erase( const Key& key ); \fB(4)\fP + template< class K > \fB(5)\fP (since C++23) + size_type erase( K&& x ); - Removes specified elements from the container. + Removes specified elements from the container. The order of the remaining equivalent + elements is preserved. - 1) Removes the element at pos. - 2) Removes the elements in the range [first; last). - 3) Removes all elements with the key value key. + 1,2) Removes the element at pos. + Only one overload is provided if iterator and const_iterator are the same type. + \fI(since C++11)\fP + 3) Removes the elements in the range [first, last), which must be a valid range in + *this. + 4) Removes all elements with the key equivalent to key. + 5) Removes all elements with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type, and neither iterator nor + const_iterator is implicitly convertible from K. It allows calling this function + without constructing an instance of Key. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which - is valid, but is not dereferencable) cannot be used as a value for pos. + is valid, but is not dereferenceable) cannot be used as a value for pos. .SH Parameters pos - iterator to the element to remove first, last - range of elements to remove key - key value of the elements to remove + x - a value of any type that can be transparently compared with a key + denoting the elements to remove .SH Return value - 1-2) Iterator following the last removed element. - 3) Number of elements removed. + 1-3) Iterator following the last removed element. + 4) Number of elements removed. + 5) Number of elements removed. .SH Exceptions - 1,2) \fI(none)\fP - 3) Any exceptions thrown by the Compare object. + 1-3) Throws nothing. + 4,5) Any exceptions thrown by the Compare object. .SH Complexity Given an instance c of multiset: - 1) Amortized constant - 2) log(c.size()) + std::distance(first, last) - 3) log(c.size()) + c.count(k) + 1,2) Amortized constant + 3) log(c.size()) + std::distance(first, last) + 4) log(c.size()) + c.count(key) + 5) log(c.size()) + c.count(x) + +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers; + overload \fB(5)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::multiset c = {1, 2, 3, 4, 1, 2, 3, 4}; + + auto print = [&c] + { + std::cout << "c = { "; + for (int n : c) + std::cout << n << ' '; + std::cout << "}\\n"; + }; + print(); + + std::cout << "Erase all odd numbers:\\n"; + for (auto it = c.begin(); it != c.end();) + { + if (*it % 2 != 0) + it = c.erase(it); + else + ++it; + } + print(); + + std::cout << "Erase 1, erased count: " << c.erase(1) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + std::cout << "Erase 2, erased count: " << c.erase(2) << '\\n'; + print(); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the return type of overloads (1) and (3) + LWG 130 C++98 was void (it is not corrected to iterator + consistent with the erase() requirement + on sequence containers) + the order of equivalent elements that + LWG 371 C++98 are not required to be + erased was not guaranteed to be preserved + preserved + LWG 2059 C++11 replacing overload (1) with overload (2) added overload (1) back + introduced new ambiguity .SH See also clear clears the contents - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::extract.3 b/man/std::multiset::extract.3 new file mode 100644 index 000000000..32ccd9c2f --- /dev/null +++ b/man/std::multiset::extract.3 @@ -0,0 +1,118 @@ +.TH std::multiset::extract 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::extract \- std::multiset::extract + +.SH Synopsis + node_type extract( const_iterator position ); \fB(1)\fP \fI(since C++17)\fP + node_type extract( const Key& k ); \fB(2)\fP \fI(since C++17)\fP + template< class K > \fB(3)\fP (since C++23) + node_type extract( K&& x ); + + 1) Unlinks the node that contains the element pointed to by position and returns a + node handle that owns it. + 2) If the container has an element with key equivalent to k, unlinks the node that + contains the first such element from the container and returns a node handle that + owns it. Otherwise, returns an empty node handle. + 3) Same as \fB(2)\fP. This overload participates in overload resolution only if the + qualified-id Compare::is_transparent is valid and denotes a type, and neither + iterator nor const_iterator is implicitly convertible from K. It allows calling this + function without constructing an instance of Key. + + In either case, no elements are copied or moved, only the internal pointers of the + container nodes are repointed (rebalancing may occur, as with erase()). + + Extracting a node invalidates only the iterators to the extracted element. Pointers + and references to the extracted element remain valid, but cannot be used while + element is owned by a node handle: they become usable if the element is inserted + into a container. + +.SH Parameters + + position - a valid iterator into this container + k - a key to identify the node to be extracted + x - a value of any type that can be transparently compared with a key + identifying the node to be extracted + +.SH Return value + + A node handle that owns the extracted element, or empty node handle in case the + element is not found in (2,3). + +.SH Exceptions + + 1) Throws nothing. + 2,3) Any exceptions thrown by the Compare object. + +.SH Complexity + + 1) Amortized constant. + 2,3) log(size()) + +.SH Notes + + extract is the only way to take a move-only object out of a set: + + std::set s; + s.emplace(...); + move_only_type mot = std::move(s.extract(s.begin()).value()); + + Feature-test macro Value Std Feature + Heterogeneous erasure in + associative containers + __cpp_lib_associative_heterogeneous_erasure 202110L (C++23) and unordered + associative containers, + \fB(3)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + void print(std::string_view comment, const auto& data) + { + std::cout << comment; + for (auto datum : data) + std::cout << ' ' << datum; + + std::cout << '\\n'; + } + + int main() + { + std::multiset cont{1, 2, 3}; + + print("Start:", cont); + + // Extract node handle and change key + auto nh = cont.extract(1); + nh.value() = 4; + + print("After extract and before insert:", cont); + + // Insert node handle back + cont.insert(std::move(nh)); + + print("End:", cont); + } + +.SH Output: + + Start: 1 2 3 + After extract and before insert: 2 3 + End: 2 3 4 + +.SH See also + + merge splices nodes from another container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP + erase erases elements + \fI(public member function)\fP diff --git a/man/std::multiset::find.3 b/man/std::multiset::find.3 index ab9179ee2..9710c5d0e 100644 --- a/man/std::multiset::find.3 +++ b/man/std::multiset::find.3 @@ -1,15 +1,21 @@ -.TH std::multiset::find 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::find 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::find \- std::multiset::find + .SH Synopsis - iterator find( const Key& key ); \fB(1)\fP - const_iterator find( const Key& key ) const; \fB(2)\fP - template< class K > iterator find( const K& x ); \fB(3)\fP \fI(since C++14)\fP - template< class K > const_iterator find( const K& x ) const; \fB(4)\fP \fI(since C++14)\fP + iterator find( const Key& key ); \fB(1)\fP + const_iterator find( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator find( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator find( const K& x ) const; - 1,2) Finds an element with key equivalent to key. - 3,4) Finds an element with key that compares equivalent to the value x. These - templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key + 1,2) Finds an element with key equivalent to key. If there are several elements with + the requested key in the container, any of them may be returned. + 3,4) Finds an element with key that compares equivalent to the value x. This + overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -18,25 +24,74 @@ .SH Return value - Iterator to an element with key equivalent to key. If no such element is found, - past-the-end (see end()) iterator is returned. + An iterator to the requested element. If no such element is found, past-the-end (see + end()) iterator is returned. .SH Complexity Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + .SH Example - This section is incomplete - Reason: no example + +// Run this code + + #include + #include + + struct LightKey + { + int x; + }; + + struct FatKey + { + int x; + int data[1000]; // a heavy blob + }; + + // As detailed above, the container must use std::less<> (or other transparent + // Comparator) to access these overloads. This includes standard overloads, + // such as comparison between std::string and std::string_view. + bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x < lk.x; } + bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x < fk.x; } + bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x < fk2.x; } + + int main() + { + // Simple comparison demo. + std::multiset example{1, 2, 3, 4}; + + if (auto search = example.find(2); search != example.end()) + std::cout << "Found " << (*search) << '\\n'; + else + std::cout << "Not found\\n"; + + // Transparent comparison demo. + std::multiset> example2{{1, {}}, {2, {}}, {3, {}}, {4, {}}}; + + LightKey lk = {2}; + if (auto search = example2.find(lk); search != example2.end()) + std::cout << "Found " << search->x << '\\n'; + else + std::cout << "Not found\\n"; + } + +.SH Output: + + Found 2 + Found 2 .SH See also count returns the number of elements matching specific key - \fI(public member function)\fP + \fI(public member function)\fP equal_range returns range of elements matching a specific key - \fI(public member function)\fP - -.SH Category: - - * Todo no example + \fI(public member function)\fP diff --git a/man/std::multiset::get_allocator.3 b/man/std::multiset::get_allocator.3 index 53a521a6c..6cff561a2 100644 --- a/man/std::multiset::get_allocator.3 +++ b/man/std::multiset::get_allocator.3 @@ -1,6 +1,9 @@ -.TH std::multiset::get_allocator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::get_allocator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::get_allocator \- std::multiset::get_allocator + .SH Synopsis - allocator_type get_allocator() const; + allocator_type get_allocator() const; (noexcept since C++11) Returns the allocator associated with the container. diff --git a/man/std::multiset::insert.3 b/man/std::multiset::insert.3 index 0b32a648a..fe66e977e 100644 --- a/man/std::multiset::insert.3 +++ b/man/std::multiset::insert.3 @@ -1,69 +1,111 @@ -.TH std::multiset::insert 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::insert 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::insert \- std::multiset::insert + .SH Synopsis iterator insert( const value_type& value ); \fB(1)\fP iterator insert( value_type&& value ); \fB(2)\fP \fI(since C++11)\fP - iterator insert( iterator hint, const value_type& \fI(until C++11)\fP + iterator insert( iterator pos, const value_type& \fI(until C++11)\fP value ); - iterator insert( const_iterator hint, const \fI(since C++11)\fP + iterator insert( const_iterator pos, const \fI(since C++11)\fP value_type& value ); - iterator insert( const_iterator hint, value_type&& \fB(3)\fP \fB(4)\fP \fI(since C++11)\fP + iterator insert( const_iterator pos, value_type&& \fB(4)\fP \fI(since C++11)\fP value ); - template< class InputIt > \fB(5)\fP + template< class InputIt > \fB(3)\fP \fB(5)\fP void insert( InputIt first, InputIt last ); void insert( std::initializer_list ilist \fB(6)\fP \fI(since C++11)\fP ); + iterator insert( node_type&& nh ); \fB(7)\fP \fI(since C++17)\fP + iterator insert( const_iterator pos, node_type&& nh \fB(8)\fP \fI(since C++17)\fP + ); - Inserts element(s) into the container. - - 1-2) Inserts value. If the container has elements with equivalent key, inserts at - the upper bound of that range.\fI(since C++11)\fP. - 3-4) inserts value in the position as close as possible, just prior\fI(since C++11)\fP, to - hint. - 5) inserts elements from range [first, last). - 6) inserts elements from initializer list ilist. + Inserts element(s) into the container. The order of the remaining equivalent + elements is preserved. + + 1,2) Inserts value. If the container has elements with equivalent key, inserts at + the upper bound of that range. + 3,4) Inserts value in the position as close as possible to the position just prior + to pos. + 5) Inserts elements from range [first, last). + 6) Inserts elements from initializer list ilist. + 7) If nh is an empty node handle, does nothing. Otherwise, inserts the element owned + by nh into the container and returns an iterator pointing at the inserted element. + If a range containing elements with keys equivalent to nh.key() exists in the + container, the element is inserted at the end of that range. The behavior is + undefined if nh is not empty and get_allocator() != nh.get_allocator(). + 8) If nh is an empty node handle, does nothing and returns the end iterator. + Otherwise, inserts the element owned by nh into the container, and returns the + iterator pointing to the element with key equivalent to nh.key(). The element is + inserted as close as possible to the position just prior to pos. The behavior is + undefined if nh is not empty and get_allocator() != nh.get_allocator(). No iterators or references are invalidated. + If the insertion is successful, pointers and references to the element obtained + while it is held in the node handle are invalidated, and pointers and references + obtained to that element before it was extracted become valid. + \fI(since C++17)\fP .SH Parameters - hint - iterator, used as a suggestion as to where to insert the content + pos - iterator to the position before which the new element will be inserted value - element value to insert first, last - range of elements to insert ilist - initializer list to insert the values from + nh - a compatible node handle .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - 1-4) Returns an iterator to the inserted element. - 5-6) \fI(none)\fP + 1-4) An iterator to the inserted element. + 5,6) \fI(none)\fP + 7,8) End iterator if nh was empty, iterator pointing to the inserted element + otherwise. .SH Exceptions - 1-4) If an exception is thrown by any operation, the insertion has no effect. - - This section is incomplete - Reason: cases 5-6 + 1-4,7,8) If an exception is thrown by any operation, the insertion has no effect. + 5,6) No exception safety guarantee. .SH Complexity - 1-2) Logarithmic in the size of the container, O(log(size())). + 1,2,7) O(log(size())) + 3,4,8) Amortized constant if the insertion happens in the position just before pos, + O(log(size())) otherwise. + 5,6) O(N·log(size() + N)), where N is the number of elements to insert. - 3-4) Amortized constant if the insertion happens in the position just \fI(until C++11)\fP - after the hint, logarithmic in the size of the container otherwise. - 3-4) Amortized constant if the insertion happens in the position just \fI(since C++11)\fP - before the hint, logarithmic in the size of the container otherwise. +.SH Example - 5-6) O(N*log(size() + N)), where N is the number of elements to insert. + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the insertion is required + pos was just a hint, it could be to + LWG 233 C++98 totally ignored be as close as possible to + the + position just prior to pos + the complexity of overload (5) was removed the linear + LWG 264 C++98 required to be linear if requirement + the range [first, last) is sorted in this special case + according to Compare + LWG 371 C++98 the order of equivalent elements was required to be preserved + not guaranteed to be preserved .SH See also emplace constructs element in-place - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP emplace_hint constructs elements in-place using a hint - \fI(C++11)\fP \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP + inserter creates a std::insert_iterator of type inferred from the argument + \fI(function template)\fP .SH Category: - - * Todo with reason + * Todo no example diff --git a/man/std::multiset::insert_range.3 b/man/std::multiset::insert_range.3 new file mode 100644 index 000000000..d1424824f --- /dev/null +++ b/man/std::multiset::insert_range.3 @@ -0,0 +1,74 @@ +.TH std::multiset::insert_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::insert_range \- std::multiset::insert_range + +.SH Synopsis + template< container-compatible-range R > (since C++23) + void insert_range( R&& rg ); + + Inserts a copy of each element in the range rg. + + Each iterator in the range rg is dereferenced exactly once. The behavior is + undefined if rg overlaps with the container. + + No iterators or references are invalidated. + +.SH Parameters + + rg - a container compatible range, that is, an input_range whose elements + are convertible to T +.SH Type requirements + - + value_type must be EmplaceConstructible into multiset from *ranges::begin(rg). + Otherwise, the behavior is undefined. + +.SH Return value + + \fI(none)\fP + +.SH Complexity + + N·log(a.size() + N), where N is ranges::distance(rg). + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion + +.SH Example + + +// Run this code + + #include + #include + + void println(auto, auto const& container) + { + for (const auto& elem : container) + std::cout << elem << ' '; + std::cout << '\\n'; + } + + int main() + { + auto container = std::multiset{1, 3, 2, 4}; + const auto rg = {-1, 3, -2}; + #ifdef __cpp_lib_containers_ranges + container.insert_range(rg); + #else + container.insert(rg.begin(), rg.end()); + #endif + println("{}", container); + } + +.SH Output: + + -2 -1 1 2 3 3 4 + +.SH See also + + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::key_comp.3 b/man/std::multiset::key_comp.3 index 6f66cef8d..ee556956d 100644 --- a/man/std::multiset::key_comp.3 +++ b/man/std::multiset::key_comp.3 @@ -1,4 +1,7 @@ -.TH std::multiset::key_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::key_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::key_comp \- std::multiset::key_comp + .SH Synopsis key_compare key_comp() const; @@ -17,7 +20,56 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::multiset cont{1, 2, 3, 4, 5}; + + auto comp_func = cont.key_comp(); + + for (const int key : cont) + { + const bool before = comp_func(key, 100); + const bool after = comp_func(100, key); + + std::cout << '(' << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (100)\\n"; + else if (before) + std::cout << "goes before key (100)\\n"; + else if (after) + std::cout << "goes after key (100)\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + .SH See also value_comp returns the function that compares keys in objects of type value_type - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::lower_bound.3 b/man/std::multiset::lower_bound.3 index 073cabbaa..21069f9f8 100644 --- a/man/std::multiset::lower_bound.3 +++ b/man/std::multiset::lower_bound.3 @@ -1,17 +1,21 @@ -.TH std::multiset::lower_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::lower_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::lower_bound \- std::multiset::lower_bound + .SH Synopsis iterator lower_bound( const Key& key ); \fB(1)\fP - const_iterator lower_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP - iterator lower_bound(const K& x); - template< class K > \fB(2)\fP \fI(since C++14)\fP - const_iterator lower_bound(const K& x) const; - - 1) Returns an iterator pointing to the first element that is not less than key. - 2) Returns an iterator pointing to the first element that compares not less to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + const_iterator lower_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP + iterator lower_bound( const K& x ); + template< class K > \fB(4)\fP \fI(since C++14)\fP + const_iterator lower_bound( const K& x ) const; + + 1,2) Returns an iterator pointing to the first element that is not less than (i.e. + greater or equal to) key. + 3,4) Returns an iterator pointing to the first element that compares not less (i.e. + greater or equal) to the value x. This overload participates in overload resolution + only if the qualified-id Compare::is_transparent is valid and denotes a type. It + allows calling this function without constructing an instance of Key. .SH Parameters @@ -27,9 +31,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers; + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - upper_bound returns an iterator to the first element greater than a certain value - \fI(public member function)\fP + \fI(public member function)\fP + upper_bound returns an iterator to the first element greater than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multiset::max_size.3 b/man/std::multiset::max_size.3 index 7385a88d9..4b232fa91 100644 --- a/man/std::multiset::max_size.3 +++ b/man/std::multiset::max_size.3 @@ -1,6 +1,9 @@ -.TH std::multiset::max_size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::max_size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::max_size \- std::multiset::max_size + .SH Synopsis - size_type max_size() const; + size_type max_size() const; (noexcept since C++11) Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the @@ -14,25 +17,45 @@ Maximum number of elements. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Notes - This value is typically equal to std::numeric_limits::max(), and reflects - the theoretical limit on the size of the container. At runtime, the size of the + This value typically reflects the theoretical limit on the size of the container, at + most std::numeric_limits::max(). At runtime, the size of the container may be limited to a value smaller than max_size() by the amount of RAM available. +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::multiset p; + std::multiset q; + + std::cout.imbue(std::locale("en_US.UTF-8")); + std::cout << std::uppercase + << "p.max_size() = " << std::dec << p.max_size() << " = 0x" + << std::hex << p.max_size() << '\\n' + << "q.max_size() = " << std::dec << q.max_size() << " = 0x" + << std::hex << q.max_size() << '\\n'; + } + +.SH Possible output: + + p.max_size() = 461,168,601,842,738,790 = 0x666,666,666,666,666 + q.max_size() = 461,168,601,842,738,790 = 0x666,666,666,666,666 + .SH See also size returns the number of elements - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::merge.3 b/man/std::multiset::merge.3 new file mode 100644 index 000000000..f17588876 --- /dev/null +++ b/man/std::multiset::merge.3 @@ -0,0 +1,87 @@ +.TH std::multiset::merge 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::merge \- std::multiset::merge + +.SH Synopsis + template< class C2 > \fB(1)\fP \fI(since C++17)\fP + void merge( std::set& source ); + template< class C2 > \fB(2)\fP \fI(since C++17)\fP + void merge( std::set&& source ); + template< class C2 > \fB(3)\fP \fI(since C++17)\fP + void merge( std::multiset& source ); + template< class C2 > \fB(4)\fP \fI(since C++17)\fP + void merge( std::multiset&& source ); + + Attempts to extract ("splice") each element in source and insert it into *this using + the comparison object of *this. + + No elements are copied or moved, only the internal pointers of the container nodes + are repointed. All pointers and references to the transferred elements remain valid, + but now refer into *this, not into source. + + The behavior is undefined if get_allocator() != source.get_allocator(). + +.SH Parameters + + source - compatible container to transfer the nodes from + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + Does not throw unless comparison throws. + +.SH Complexity + + N * log(size() + N)), where N is source.size(). + +.SH Example + + +// Run this code + + #include + #include + + // print out a container + template + Os& operator<<(Os& os, const std::multiset& v) + { + os << '[' << v.size() << "] {"; + bool o{}; + for (const auto& e : v) + os << (o ? ", " : (o = 1, " ")) << e; + return os << " }\\n"; + } + + int main() + { + std::multiset + p{'C', 'B', 'B', 'A'}, + q{'E', 'D', 'E', 'C'}; + + std::cout << "p: " << p << "q: " << q; + + p.merge(q); + + std::cout << "p.merge(q);\\n" << "p: " << p << "q: " << q; + } + +.SH Output: + + p: [4] { A, B, B, C } + q: [4] { C, D, E, E } + p.merge(q); + p: [8] { A, B, B, C, C, D, E, E } + q: [0] { } + +.SH See also + + extract extracts nodes from the container + \fI(C++17)\fP \fI(public member function)\fP + inserts elements + insert or nodes + \fI(since C++17)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::multiset.3 b/man/std::multiset::multiset.3 index 3c480de68..e888facdd 100644 --- a/man/std::multiset::multiset.3 +++ b/man/std::multiset::multiset.3 @@ -1,58 +1,80 @@ -.TH std::multiset::multiset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::multiset \- std::multiset::multiset + .SH Synopsis - explicit multiset( const Compare& comp = Compare(), (until - const Allocator& alloc = C++14) - Allocator() ); - multiset : multiset( Compare() ) {} - - explicit multiset( const Compare& comp, (since - C++14) - const Allocator& alloc = - Allocator() ); - explicit multiset( const Allocator& alloc ); \fB(1)\fP (since - C++11) + multiset(); \fI(until C++11)\fP + multiset() \fI(since C++11)\fP + : multiset(Compare()) {} + explicit multiset( const Compare& comp, \fB(2)\fP + const Allocator& alloc = Allocator() ); + explicit multiset( const Allocator& alloc ); \fB(3)\fP \fI(since C++11)\fP template< class InputIt > - multiset( InputIt first, InputIt last, + multiset( InputIt first, InputIt last, \fB(4)\fP const Compare& comp = Compare(), const Allocator& alloc = Allocator() ); - template< class InputIt > \fB(1)\fP - (since - multiset( InputIt first, InputIt last, C++14) + template< class InputIt > + + multiset( InputIt first, InputIt last, \fB(5)\fP \fI(since C++14)\fP + const Allocator& alloc ) + + : multiset(first, last, Compare(), alloc) {} + multiset( const multiset& other ); \fB(6)\fP + multiset( const multiset& other, const Allocator& alloc ); \fB(7)\fP \fI(since C++11)\fP + multiset( multiset&& other ); \fB(8)\fP \fI(since C++11)\fP + multiset( multiset&& other, const Allocator& alloc ); \fB(9)\fP \fI(since C++11)\fP + multiset( std::initializer_list init, \fB(1)\fP + + const Compare& comp = Compare(), \fB(10)\fP \fI(since C++11)\fP const Allocator& alloc = Allocator() ); - multiset( const multiset& other ); \fB(3)\fP - multiset( const multiset& other, const Allocator& \fB(2)\fP \fB(3)\fP (since - alloc ); C++11) - multiset( multiset&& other ); \fB(4)\fP (since - C++11) - multiset( multiset&& other, const Allocator& alloc \fB(4)\fP (since - ); C++11) multiset( std::initializer_list init, - (since - const Compare& comp = Compare(), C++11) - \fB(5)\fP + + const Allocator& alloc ) \fB(11)\fP \fI(since C++14)\fP + + : multiset(init, Compare(), alloc) {} + template< container-compatible-range R > + + multiset( std::from_range_t, R&& rg, \fB(12)\fP (since C++23) + const Compare& comp = Compare(), + const Allocator& alloc = Allocator() ); - multiset( std::initializer_list init, (since - const Allocator& alloc = Allocator() ); C++14) + template< container-compatible-range R > + + multiset( std::from_range_t, R&& rg, + const Allocator& alloc ) \fB(13)\fP (since C++23) + + : multiset(std::from_range, std::forward(rg), + Compare(), alloc) {} Constructs new container from a variety of data sources and optionally using user supplied allocator alloc or comparison function object comp. - 1) Default constructor. Constructs empty container. + 1-3) Constructs an empty container. + 4,5) Constructs the container with the contents of the range [first, last). + If [first, last) is not a valid range, the behavior is undefined. + 6,7) Copy constructor. Constructs the container with the copy of the contents of + other. - 2) Constructs the container with the contents of the range [first, last). + If alloc is not provided, allocator is obtained by calling (since + std::allocator_traits:: C++11) + select_on_container_copy_construction(other.get_allocator()). + During class template argument deduction, only the first argument contributes (since + to the deduction of the container's Allocator template parameter. C++23) - 3) Copy constructor. Constructs the container with the copy of the contents of - other. If alloc is not provided, allocator is obtained by calling - std::allocator_traits::select_on_copy_construction(other). + 8,9) Move constructor. Constructs the container with the contents of other using + move semantics. If alloc is not provided, allocator is obtained by move-construction + from the allocator belonging to other. - 4) Move constructor. Constructs the container with the contents of other using move - semantics. If alloc is not provided, allocator is obtained by move-construction from - the allocator belonging to other. + During class template argument deduction, only the first argument + contributes to the deduction of the container's Allocator template (since C++23) + parameter. - 5) Constructs the container with the contents of the initializer list init. + 10,11) Initializer-list constructor. Constructs the container with the contents of + the initializer list init. + 12,13) Constructs the container with the contents of rg. .SH Parameters @@ -62,9 +84,11 @@ other - another container to be used as source to initialize the elements of the container with init - initializer list to initialize the elements of the container with + rg - a container compatible range, that is, an input_range whose elements + are convertible to value_type .SH Type requirements - - InputIt must meet the requirements of InputIterator. + InputIt must meet the requirements of LegacyInputIterator. - Compare must meet the requirements of Compare. - @@ -72,163 +96,112 @@ .SH Complexity - 1) Constant + 1-3) Constant. + 4,5) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + std::distance(first, last) in general, linear in \\(\\scriptsize N\\)N if [first, last) + is already sorted by value_comp(). + 6,7) Linear in size of other. + 8,9) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + 10,11) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + init.size() in general, linear in \\(\\scriptsize N\\)N if init is already sorted by + value_comp(). + 12,13) \\(\\scriptsize N \\cdot log(N)\\)N·log(N) where \\(\\scriptsize N\\)N is + ranges::distance(rg) in general, linear in \\(\\scriptsize N\\)N if rg is already + sorted by value_comp(). + +.SH Exceptions + + Calls to Allocator::allocate may throw. - 2) N log(N) where N = std::distance(first, last) in general, linear in N if the - range is already sorted by value_comp(). +.SH Notes - 3) Linear in size of other + After container move construction (overload (8,9)), references, pointers, and + iterators (other than the end iterator) to other remain valid, but refer to elements + that are now in *this. The current standard makes this guarantee via the blanket + statement in [container.reqmts]/67, and a more direct guarantee is under + consideration via LWG issue 2321. - 4) Constant. If alloc is given and alloc != other.get_allocator(), then linear. + Although not formally required until C++23, some implementations has already put the + template parameter Allocator into non-deduced contexts in earlier modes. - 5) N log(N) where N = init.size()) in general, linear in N if init is already sorted - by value_comp(). + Feature-test macro Value Std Feature + __cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion; + overloads (12,13) .SH Example - + // Run this code #include - #include - #include - - //declare printers for maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map); - - int main() + #include + #include + + template + void println(const std::string_view name, const std::multiset& ms) { - typedef std::string Key; - typedef int Mapped; - - // (1) Default constructor - std::map map; - map["something"] = 69; - map["anything"] = 199; - map["that thing"] = 50; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (2) Iterator constructor - std::map iter(map.find("anything"), map.end()); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "iter = " << iter << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (3) Copy constructor - std::map copy(map); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "copy = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (4) Move constructor - std::map moved(std::move(map)); - std::cout << std::string(80, '-') << '\\n'; - std::cout << "moved = " << copy << '\\n'; - std::cout << "map = " << map << '\\n'; - - // (5) Initializer list constructor - const std::map init { - {"this", 100}, - {"can", 100}, - {"be", 100}, - {"const", 100}, - }; - std::cout << std::string(80, '-') << '\\n'; - std::cout << "init = " << init << '\\n'; - } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ':' << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; + std::cout << name << ": "; + for (const auto& element : ms) + std::cout << element << ' '; + std::cout << '\\n'; } - - // A specialization for Key strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":" << pair.second; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A printer for unordered maps - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << pair.first << ":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; - } - - // A specialization for Key and Mapped strings - template - std::ostream& operator<<(std::ostream& stream, - const std::map& map) { - stream << '{'; - char comma[3] = {'\\0', ' ', '\\0'}; - for (const auto& pair : map) { - stream << comma << '"' << pair.first << "\\":\\"" << pair.second << '"'; - comma[0] = ','; - } - stream << '}'; - return stream; + + int main() + { + // (1) Default constructor + std::multiset a; + a.insert(4); + a.insert(3); + a.insert(2); + a.insert(1); + println("a", a); + + // (4) Range constructor + std::multiset b(a.begin(), a.find(3)); + println("b", b); + + // (6) Copy constructor + std::multiset c(a); + println("c", c); + + // (8) Move constructor + std::multiset d(std::move(a)); + println("d", d); + + // (10) Initializer list constructor + std::multiset e{3, 2, 1, 2, 4, 7, 3}; + println("e", e); + + // (12) Range constructor + const auto w = {"α", "β", "γ", "δ", "δ", "γ", "β", "α"}; + #if __cpp_lib_containers_ranges + std::multiset f(std::from_range, w); // overload (12) + #else + std::multiset f(w.begin(), w.end()); // fallback to (4) + #endif + println("f", f); } .SH Output: - -------------------------------------------------------------------------------- - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - iter = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - copy = {"anything":199, "something":69, "that thing":50} - map = {"anything":199, "something":69, "that thing":50} - -------------------------------------------------------------------------------- - moved = {"anything":199, "something":69, "that thing":50} - map = {} - -------------------------------------------------------------------------------- - init = {"be":100, "can":100, "const":100, "this":100} - - This section is incomplete - Reason: cleanup/shorten this example + a: 1 2 3 4 + b: 1 2 + c: 1 2 3 4 + d: 1 2 3 4 + e: 1 2 2 3 3 4 7 + f: α α β β γ γ δ δ -.SH See also + Defect reports - operator= assigns values to the container - \fI(public member function)\fP + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. -.SH Category: + DR Applied to Behavior as published Correct behavior + LWG 2076 C++11 overload \fB(4)\fP conditionally required Key to be not required + CopyInsertable into *this + LWG 2193 C++11 the default constructor was explicit made non-explicit - * Todo with reason +.SH See also + + operator= assigns values to the container + \fI(public member function)\fP diff --git a/man/std::multiset::operator=.3 b/man/std::multiset::operator=.3 index e1a797099..21645f8ba 100644 --- a/man/std::multiset::operator=.3 +++ b/man/std::multiset::operator=.3 @@ -1,27 +1,41 @@ -.TH std::multiset::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::operator= \- std::multiset::operator= + .SH Synopsis - multiset& operator=( const multiset& other ); \fB(1)\fP - multiset& operator=( multiset&& other ); \fB(2)\fP \fI(since C++11)\fP - multiset& operator=( std::initializer_list ilist ); \fB(3)\fP \fI(since C++11)\fP + multiset& operator=( const multiset& other ); \fB(1)\fP + multiset& operator=( multiset&& other ); \fI(since C++11)\fP + \fI(until C++17)\fP + multiset& operator=( multiset&& other ) noexcept(/* see below \fB(2)\fP \fI(since C++17)\fP + */); + multiset& operator=( std::initializer_list ilist \fB(3)\fP \fI(since C++11)\fP + ); Replaces the contents of the container. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - If std::allocator_traits::propagate_on_container_copy_assignment() - is true, the target allocator is replaced by a copy of the source allocator. If the - target and the source allocators do not compare equal, the target (*this) allocator - is used to deallocate the memory, then other's allocator is used to allocate it - before copying the elements. - \fI(since C++11)\fP + +If +std::allocator_traits::propagate_on_container_copy_assignment::value +is true, the allocator of *this is replaced by a copy of other. If the allocator of +*this after assignment would compare unequal to its old value, the old allocator is (since +used to deallocate the memory, then the new allocator is used to allocate it before C++11) +copying the elements. Otherwise, the memory owned by *this may be reused when +possible. In any case, the elements originally belonging to *this may be either +destroyed or replaced by element-wise copy-assignment. + 2) Move assignment operator. Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container). other is - in a valid but unspecified state afterwards. If - std::allocator_traits::propagate_on_container_move_assignment() is - true, the target allocator is replaced by a copy of the source allocator. If it is - false and the source and the taget allocators do not compare equal, the target - cannot take ownership of the source memory and must move-assign each element - individually, allocating additional memory using its own allocator as needed. + in a valid but unspecified state afterwards. + If + std::allocator_traits::propagate_on_container_move_assignment::value + is true, the allocator of *this is replaced by a copy of that of other. If it is + false and the allocators of *this and other do not compare equal, *this cannot take + ownership of the memory owned by other and must move-assign each element + individually, allocating additional memory using its own allocator as needed. In any + case, all elements originally belonging to *this are either destroyed or replaced by + element-wise move-assignment. 3) Replaces the contents with those identified by initializer list ilist. .SH Parameters @@ -35,66 +49,97 @@ .SH Complexity - 1) Linear in the size of the other. - 2) Constant unless - std::allocator_traits::propagate_on_container_move_assignment() is - false and the allocators do not compare equal (in which case linear). - 3) Linear in the size of ilist. + 1) Linear in the size of *this and other. + 2) Linear in the size of *this unless the allocators do not compare equal and do not + propagate, in which case linear in the size of *this and other. + 3) O(NlogN) in general, where N is size() + ilist.size(). Linear if ilist is sorted + with respect to value_comp(). + +.SH Exceptions + + 1-3) May throw implementation-defined exceptions. \fI(until C++17)\fP + 1,3) May throw implementation-defined exceptions. + 2) + noexcept specification: \fI(since C++17)\fP + noexcept(std::allocator_traits::is_always_equal::value + && std::is_nothrow_move_assignable::value) + +.SH Notes + + After container move assignment (overload \fB(2)\fP), unless element-wise move assignment + is forced by incompatible allocators, references, pointers, and iterators (other + than the end iterator) to other remain valid, but refer to elements that are now in + *this. The current standard makes this guarantee via the blanket statement in + [container.reqmts]/67, and a more direct guarantee is under consideration via LWG + issue 2321. .SH Example - + The following code uses operator= to assign one std::multiset to another: - The following code uses to assign one std::multiset to another: - // Run this code - #include + #include #include - - void display_sizes(const std::multiset &nums1, - const std::multiset &nums2, - const std::multiset &nums3) + #include + #include + + void print(auto const comment, auto const& container) { - std::cout << "nums1: " << nums1.size() - << " nums2: " << nums2.size() - << " nums3: " << nums3.size() << '\\n'; + auto size = std::size(container); + std::cout << comment << "{ "; + for (auto const& element : container) + std::cout << element << (--size ? ", " : " "); + std::cout << "}\\n"; } - + int main() { - std::multiset nums1 {3, 1, 4, 6, 5, 9}; - std::multiset nums2; - std::multiset nums3; - + std::multiset x{1, 2, 3}, y, z; + const auto w = {4, 5, 6, 7}; + std::cout << "Initially:\\n"; - display_sizes(nums1, nums2, nums3); - - // copy assignment copies data from nums1 to nums2 - nums2 = nums1; - - std::cout << "After assigment:\\n"; - display_sizes(nums1, nums2, nums3); - - // move assignment moves data from nums1 to nums3, - // modifying both nums1 and nums3 - nums3 = std::move(nums1); - - std::cout << "After move assigment:\\n"; - display_sizes(nums1, nums2, nums3); + print("x = ", x); + print("y = ", y); + print("z = ", z); + + std::cout << "Copy assignment copies data from x to y:\\n"; + y = x; + print("x = ", x); + print("y = ", y); + + std::cout << "Move assignment moves data from x to z, modifying both x and z:\\n"; + z = std::move(x); + print("x = ", x); + print("z = ", z); + + std::cout << "Assignment of initializer_list w to z:\\n"; + z = w; + print("w = ", w); + print("z = ", z); } .SH Output: Initially: - nums1: 6 nums2: 0 nums3: 0 - After assigment: - nums1: 6 nums2: 6 nums3: 0 - After move assigment: - nums1: 0 nums2: 6 nums3: 6 + x = { 1, 2, 3 } + y = { } + z = { } + Copy assignment copies data from x to y: + x = { 1, 2, 3 } + y = { 1, 2, 3 } + Move assignment moves data from x to z, modifying both x and z: + x = { } + z = { 1, 2, 3 } + Assignment of initializer_list w to z: + w = { 4, 5, 6, 7 } + z = { 4, 5, 6, 7 } .SH See also constructor constructs the multiset - \fI(public member function)\fP + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::multiset::rbegin,.3 b/man/std::multiset::rbegin,.3 new file mode 100644 index 000000000..053f3f02d --- /dev/null +++ b/man/std::multiset::rbegin,.3 @@ -0,0 +1,78 @@ +.TH std::multiset::rbegin, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::rbegin, \- std::multiset::rbegin, + +.SH Synopsis + + reverse_iterator rbegin(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rbegin() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crbegin() const noexcept; \fB(3)\fP \fI(since C++11)\fP + + Returns a reverse iterator to the first element of the reversed multiset. It + corresponds to the last element of the non-reversed multiset. If the multiset is + empty, the returned iterator is equal to rend(). + + range-rbegin-rend.svg + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Reverse iterator to the first element. + +.SH Complexity + + Constant. + +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + The underlying iterator of the returned reverse iterator is the end iterator. Hence + the returned iterator is invalidated if and when the end iterator is invalidated. + + libc++ backports crbegin() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::multiset rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ ⏼ + ⏼ + ⏼ + +.SH See also + + rend returns a reverse iterator to the end + crend \fI(public member function)\fP + \fI(C++11)\fP + rbegin returns a reverse iterator to the beginning of a container or array + crbegin \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multiset::rbegin,std::multiset::crbegin.3 b/man/std::multiset::rbegin,std::multiset::crbegin.3 deleted file mode 100644 index e62b499bb..000000000 --- a/man/std::multiset::rbegin,std::multiset::crbegin.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::multiset::rbegin,std::multiset::crbegin 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - const_reverse_iterator crbegin() const; \fI(since C++11)\fP - - Returns a reverse iterator to the first element of the reversed container. It - corresponds to the last element of the non-reversed container. - - range-rbegin-rend.svg - -.SH Parameters - - \fI(none)\fP - -.SH Return value - - Reverse iterator to the first element. - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - -.SH Complexity - - Constant. - -.SH See also - - rend returns a reverse iterator to the end - crend \fI(public member function)\fP diff --git a/man/std::multiset::rend,std::multiset::crend.3 b/man/std::multiset::rend,std::multiset::crend.3 index 6cd6b7f42..8f7ed924f 100644 --- a/man/std::multiset::rend,std::multiset::crend.3 +++ b/man/std::multiset::rend,std::multiset::crend.3 @@ -1,12 +1,15 @@ -.TH std::multiset::rend,std::multiset::crend 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::rend,std::multiset::crend 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::rend,std::multiset::crend \- std::multiset::rend,std::multiset::crend + .SH Synopsis - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crend() const; \fI(since C++11)\fP + reverse_iterator rend(); \fB(1)\fP (noexcept since C++11) + const_reverse_iterator rend() const; \fB(2)\fP (noexcept since C++11) + const_reverse_iterator crend() const noexcept; \fB(3)\fP \fI(since C++11)\fP Returns a reverse iterator to the element following the last element of the reversed - container. It corresponds to the element preceding the first element of the - non-reversed container. This element acts as a placeholder, attempting to access it + multiset. It corresponds to the element preceding the first element of the + non-reversed multiset. This element acts as a placeholder, attempting to access it results in undefined behavior. range-rbegin-rend.svg @@ -19,18 +22,54 @@ Reverse iterator to the element following the last element. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. +.SH Notes + + Because both iterator and const_iterator are constant iterators (and may in fact be + the same type), it is not possible to mutate the elements of the container through + an iterator returned by any of these member functions. + + libc++ backports crend() to C++98 mode. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::multiset rep{1, 2, 3, 4, 1, 2, 3, 4}; + + for (auto it = rep.crbegin(); it != rep.crend(); ++it) + { + for (auto n = *it; n > 0; --n) + std::cout << "⏼" << ' '; + std::cout << '\\n'; + } + } + +.SH Output: + + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ ⏼ + ⏼ ⏼ + ⏼ ⏼ + ⏼ + ⏼ + .SH See also rbegin returns a reverse iterator to the beginning - crbegin \fI(public member function)\fP + crbegin \fI(public member function)\fP + \fI(C++11)\fP + rend returns a reverse end iterator for a container or array + crend \fI(function template)\fP + \fI(C++14)\fP diff --git a/man/std::multiset::size.3 b/man/std::multiset::size.3 index 52d3f7162..034b0acad 100644 --- a/man/std::multiset::size.3 +++ b/man/std::multiset::size.3 @@ -1,6 +1,9 @@ -.TH std::multiset::size 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::size 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::size \- std::multiset::size + .SH Synopsis - size_type size() const; + size_type size() const; (noexcept since C++11) Returns the number of elements in the container, i.e. std::distance(begin(), end()). @@ -12,33 +15,27 @@ The number of elements in the container. -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Complexity Constant. .SH Example - - The following code uses size to display the number of elements in a std::multiset: - + The following code uses size to display the number of elements in a + std::multiset: + + // Run this code - #include #include - + #include + int main() { - std::multiset nums {1, 3, 5, 7}; - + std::multiset nums{1, 3, 5, 7}; + std::cout << "nums contains " << nums.size() << " elements.\\n"; } @@ -49,6 +46,10 @@ .SH See also empty checks whether the container is empty - \fI(public member function)\fP + \fI(public member function)\fP max_size returns the maximum possible number of elements - \fI(public member function)\fP + \fI(public member function)\fP + size + ssize returns the size of a container or array + \fI(C++17)\fP \fI(function template)\fP + (C++20) diff --git a/man/std::multiset::swap.3 b/man/std::multiset::swap.3 index 6500643b8..acc07b614 100644 --- a/man/std::multiset::swap.3 +++ b/man/std::multiset::swap.3 @@ -1,19 +1,23 @@ -.TH std::multiset::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::swap \- std::multiset::swap + .SH Synopsis - void swap( multiset& other ); + void swap( multiset& other ); \fI(until C++17)\fP + void swap( multiset& other ) noexcept(/* see below */); \fI(since C++17)\fP Exchanges the contents of the container with those of other. Does not invoke any move, copy, or swap operations on individual elements. - All iterators and references remain valid. The past-the-end iterator is invalidated. + All iterators and references remain valid. The end() iterator is invalidated. + + The Compare objects must be Swappable, and they are exchanged using unqualified call + to non-member swap. - The Pred objects must be Swappable, and they are exchanged using unqualified call to - non-member swap. - If std::allocator_traits::propagate_on_container_swap::value is - true, then the allocators are exchanged using an unqualified call to non-member - swap. Otherwise, they are not swapped (and if get_allocator() != + If std::allocator_traits::propagate_on_container_swap::value + is true, then the allocators are exchanged using an unqualified call to (since + non-member swap. Otherwise, they are not swapped (and if get_allocator() != C++11) other.get_allocator(), the behavior is undefined). - \fI(since C++11)\fP .SH Parameters @@ -25,13 +29,77 @@ .SH Exceptions - Any exception thrown by the swap of the Compare objects. + Any exception thrown by the swap of the Compare objects. \fI(until C++17)\fP + noexcept specification: + noexcept(std::allocator_traits::is_always_equal::value \fI(since C++17)\fP + && std::is_nothrow_swappable::value) .SH Complexity Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + template + Os& operator<<(Os& os, const Co& co) + { + os << '{'; + for (auto const& i : co) + os << ' ' << i; + return os << " } "; + } + + int main() + { + std::multiset a1{3, 1, 3, 2}, a2{5, 4, 5}; + + auto it1 = std::next(a1.begin()); + auto it2 = std::next(a2.begin()); + + const int& ref1 = *(a1.begin()); + const int& ref2 = *(a2.begin()); + + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + a1.swap(a2); + std::cout << a1 << a2 << *it1 << ' ' << *it2 << ' ' << ref1 << ' ' << ref2 << '\\n'; + + // Note that every iterator referring to an element in one container before the swap + // refers to the same element in the other container after the swap. Same is true + // for references. + + struct Cmp : std::less + { + int id{}; + Cmp(int i) : id{i} {} + }; + + std::multiset s1{{2, 2, 1, 1}, Cmp{6}}, s2{{4, 4, 3, 3}, Cmp{9}}; + + std::cout << s1 << s2 << s1.key_comp().id << ' ' << s2.key_comp().id << '\\n'; + s1.swap(s2); + std::cout << s1 << s2 << s1.key_comp().id << ' ' << s2.key_comp().id << '\\n'; + + // So, comparator objects (Cmp) are also exchanged after the swap. + } + +.SH Output: + + { 1 2 3 3 } { 4 5 5 } 2 5 1 4 + { 4 5 5 } { 1 2 3 3 } 2 5 1 4 + { 1 1 2 2 } { 3 3 4 4 } 6 9 + { 3 3 4 4 } { 1 1 2 2 } 9 6 + .SH See also std::swap(std::multiset) specializes the std::swap algorithm - \fI(function template)\fP + \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::multiset::upper_bound.3 b/man/std::multiset::upper_bound.3 index 5d4e17f9e..370ac8641 100644 --- a/man/std::multiset::upper_bound.3 +++ b/man/std::multiset::upper_bound.3 @@ -1,17 +1,20 @@ -.TH std::multiset::upper_bound 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::upper_bound 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::upper_bound \- std::multiset::upper_bound + .SH Synopsis iterator upper_bound( const Key& key ); \fB(1)\fP - const_iterator upper_bound( const Key& key ) const; \fB(1)\fP - template< class K > \fB(2)\fP \fI(since C++14)\fP + const_iterator upper_bound( const Key& key ) const; \fB(2)\fP + template< class K > \fB(3)\fP \fI(since C++14)\fP iterator upper_bound( const K& x ); - template< class K > \fB(2)\fP \fI(since C++14)\fP + template< class K > \fB(4)\fP \fI(since C++14)\fP const_iterator upper_bound( const K& x ) const; - 1) Returns an iterator pointing to the first element that is greater than key. - 2) Returns an iterator pointing to the first element that compares greater to the - value x. These templates only participate in overload resolution if the type - Compare::is_transparent exists. They allow calling this function without - constructing an instance of Key. + 1,2) Returns an iterator pointing to the first element that is greater than key. + 3,4) Returns an iterator pointing to the first element that compares greater to the + value x. This overload participates in overload resolution only if the qualified-id + Compare::is_transparent is valid and denotes a type. It allows calling this function + without constructing an instance of Key. .SH Parameters @@ -27,9 +30,24 @@ Logarithmic in the size of the container. +.SH Notes + + Feature-test macro Value Std Feature + Heterogeneous comparison lookup + __cpp_lib_generic_associative_lookup 201304L \fI(C++14)\fP in associative containers, for + overloads (3,4) + +.SH Example + + This section is incomplete + Reason: no example + .SH See also equal_range returns range of elements matching a specific key - \fI(public member function)\fP - lower_bound returns an iterator to the first element not less than the given value - \fI(public member function)\fP + \fI(public member function)\fP + lower_bound returns an iterator to the first element not less than the given key + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::multiset::value_comp.3 b/man/std::multiset::value_comp.3 index 5c64fe1b0..77ed78b56 100644 --- a/man/std::multiset::value_comp.3 +++ b/man/std::multiset::value_comp.3 @@ -1,4 +1,7 @@ -.TH std::multiset::value_comp 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::value_comp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::value_comp \- std::multiset::value_comp + .SH Synopsis std::multiset::value_compare value_comp() const; @@ -16,7 +19,57 @@ Constant. +.SH Example + + +// Run this code + + #include + #include + #include + + // Example module 97 key compare function + struct ModCmp + { + bool operator()(int lhs, int rhs) const + { + return (lhs % 97) < (rhs % 97); + } + }; + + int main() + { + std::multiset cont{1, 2, 3, 4, 5}; + + // Same behaviour as key_comp() + auto comp_func = cont.value_comp(); + + for (const int val{100}; const int key : cont) + { + const bool before = comp_func(key, val); + const bool after = comp_func(val, key); + + std::cout << "Key (" << key << ") "; + if (!before && !after) + std::cout << "equivalent to key (" << val << ")\\n"; + else if (before) + std::cout << "goes before key (" << val << ")\\n"; + else if (after) + std::cout << "goes after key (" << val << ")\\n"; + else + std::unreachable(); + } + } + +.SH Output: + + Key \fB(1)\fP goes before key (100) + Key \fB(2)\fP goes before key (100) + Key \fB(3)\fP equivalent to key (100) + Key \fB(4)\fP goes after key (100) + Key \fB(5)\fP goes after key (100) + .SH See also key_comp returns the function that compares keys - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::multiset::~multiset.3 b/man/std::multiset::~multiset.3 index 612dd922d..25c2f7293 100644 --- a/man/std::multiset::~multiset.3 +++ b/man/std::multiset::~multiset.3 @@ -1,11 +1,14 @@ -.TH std::multiset::~multiset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::multiset::~multiset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::multiset::~multiset \- std::multiset::~multiset + .SH Synopsis ~multiset(); - Destructs the container. The destructors of the elements are called and the used + Destructs the multiset. The destructors of the elements are called and the used storage is deallocated. Note, that if the elements are pointers, the pointed-to objects are not destroyed. .SH Complexity - Linear in the size of the container. + Linear in the size of the multiset. diff --git a/man/std::mutex.3 b/man/std::mutex.3 index 7500bead8..8f52e9228 100644 --- a/man/std::mutex.3 +++ b/man/std::mutex.3 @@ -1,4 +1,7 @@ -.TH std::mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex \- std::mutex + .SH Synopsis Defined in header class mutex; \fI(since C++11)\fP @@ -16,81 +19,91 @@ * A calling thread must not own the mutex prior to calling lock or try_lock. The behavior of a program is undefined if a mutex is destroyed while still owned by - some thread. The mutex class satisfies all requirements of Mutex and - StandardLayoutType. - -.SH Member types + any threads, or a thread terminates while owning a mutex. The mutex class satisfies + all requirements of Mutex and StandardLayoutType. - Member type Definition - native_handle_type implementation-defined + std::mutex is neither copyable nor movable. .SH Member functions constructor constructs the mutex - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys the mutex - \fI(public member function)\fP + \fI(public member function)\fP operator= not copy-assignable - [deleted] \fI(public member function)\fP + [deleted] \fI(public member function)\fP .SH Locking lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP .SH Native handle - native_handle returns the underlying implementation-defined thread handle - \fI(public member function)\fP + native_handle returns the underlying implementation-defined native handle object + \fI(public member function)\fP .SH Notes - std::mutex is usually not accessed directly: std::unique_lock and std::lock_guard - are used to manage locking in exception-safe manner. + std::mutex is usually not accessed directly: std::unique_lock, std::lock_guard, + or std::scoped_lock + \fI(since C++17)\fP manage locking in a more exception-safe manner. .SH Example - This example shows how a mutex can be used to protect a std::map shared between two + This example shows how a mutex can be used to protect an std::map shared between two threads. - + // Run this code + #include #include #include + #include #include - #include #include - #include - + std::map g_pages; std::mutex g_pages_mutex; - - void save_page(const std::string &url) + + void save_page(const std::string& url) { // simulate a long page fetch std::this_thread::sleep_for(std::chrono::seconds(2)); std::string result = "fake content"; - - g_pages_mutex.lock(); // or, to be exception-safe, use std::lock_guard + + std::lock_guard guard(g_pages_mutex); g_pages[url] = result; - g_pages_mutex.unlock(); } - + int main() { std::thread t1(save_page, "http://foo"); std::thread t2(save_page, "http://bar"); t1.join(); t2.join(); - + // safe to access g_pages without lock now, as the threads are joined - for (const auto &pair : g_pages) { - std::cout << pair.first << " => " << pair.second << '\\n'; - } + for (const auto& [url, page] : g_pages) + std::cout << url << " => " << page << '\\n'; } .SH Output: http://bar => fake content http://foo => fake content + +.SH See also + + recursive_mutex provides mutual exclusion facility which can be locked + \fI(C++11)\fP recursively by the same thread + \fI(class)\fP + lock_guard implements a strictly scope-based mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + unique_lock implements movable mutex ownership wrapper + \fI(C++11)\fP \fI(class template)\fP + scoped_lock deadlock-avoiding RAII wrapper for multiple mutexes + \fI(C++17)\fP \fI(class template)\fP + condition_variable provides a condition variable associated with a std::unique_lock + \fI(C++11)\fP \fI(class)\fP diff --git a/man/std::mutex::lock.3 b/man/std::mutex::lock.3 index d77c31313..6e1158dd6 100644 --- a/man/std::mutex::lock.3 +++ b/man/std::mutex::lock.3 @@ -1,4 +1,7 @@ -.TH std::mutex::lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex::lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex::lock \- std::mutex::lock + .SH Synopsis void lock(); \fI(since C++11)\fP @@ -6,10 +9,11 @@ block execution until the lock is acquired. If lock is called by a thread that already owns the mutex, the behavior is - undefined: the program may deadlock, or, if the implementation can detect the - deadlock, a resource_deadlock_would_occur error condition may be thrown. + undefined: for example, the program may deadlock. An implementation that can detect + the invalid usage is encouraged to throw a std::system_error with error condition + resource_deadlock_would_occur instead of deadlocking. - Prior unlock() operation on the same mutex synchronizes-with (as defined in + Prior unlock() operations on the same mutex synchronize-with (as defined in std::memory_order) this operation. .SH Parameters @@ -28,56 +32,60 @@ .SH Notes - lock() is usually not called directly: std::unique_lock and std::lock_guard are used - to manage exclusive locking. + lock() is usually not called directly: std::unique_lock, std::scoped_lock, and + std::lock_guard are used to manage exclusive locking. .SH Example This example shows how lock and unlock can be used to protect shared data. - + // Run this code - #include #include - #include + #include #include - - int g_num = 0; // protected by g_num_mutex + #include + + int g_num = 0; // protected by g_num_mutex std::mutex g_num_mutex; - + void slow_increment(int id) { - for (int i = 0; i < 3; ++i) { + for (int i = 0; i < 3; ++i) + { g_num_mutex.lock(); ++g_num; - std::cout << id << " => " << g_num << '\\n'; + // note, that the mutex also syncronizes the output + std::cout << "id: " << id << ", g_num: " << g_num << '\\n'; g_num_mutex.unlock(); - - std::this_thread::sleep_for(std::chrono::seconds(1)); + + std::this_thread::sleep_for(std::chrono::milliseconds(234)); } } - + int main() { - std::thread t1(slow_increment, 0); - std::thread t2(slow_increment, 1); + std::thread t1{slow_increment, 0}; + std::thread t2{slow_increment, 1}; t1.join(); t2.join(); } .SH Possible output: - 0 => 1 - 1 => 2 - 0 => 3 - 1 => 4 - 0 => 5 - 1 => 6 + id: 0, g_num: 1 + id: 1, g_num: 2 + id: 1, g_num: 3 + id: 0, g_num: 4 + id: 0, g_num: 5 + id: 1, g_num: 6 .SH See also try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_lock diff --git a/man/std::mutex::mutex.3 b/man/std::mutex::mutex.3 index 61eab2062..e375b08a4 100644 --- a/man/std::mutex::mutex.3 +++ b/man/std::mutex::mutex.3 @@ -1,17 +1,26 @@ -.TH std::mutex::mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex::mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex::mutex \- std::mutex::mutex + .SH Synopsis - constexpr mutex(); \fB(1)\fP \fI(since C++11)\fP + constexpr mutex() noexcept; \fB(1)\fP \fI(since C++11)\fP mutex( const mutex& ) = delete; \fB(2)\fP \fI(since C++11)\fP - 1) Constructs the mutex. The mutex is in unlocked state after the call. + 1) Constructs the mutex. The mutex is in unlocked state after the constructor + completes. 2) Copy constructor is deleted. .SH Parameters \fI(none)\fP -.SH Exceptions +.SH Notes + + Because the default constructor is constexpr, static mutexes are initialized as part + of static non-local initialization, before any dynamic non-local initialization + begins. This makes it safe to lock a mutex in a constructor of any static object. + +.SH See also - noexcept specification: - noexcept - + C documentation for + mtx_init diff --git a/man/std::mutex::native_handle.3 b/man/std::mutex::native_handle.3 index e9eba3cc3..0809dc381 100644 --- a/man/std::mutex::native_handle.3 +++ b/man/std::mutex::native_handle.3 @@ -1,6 +1,10 @@ -.TH std::mutex::native_handle 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex::native_handle \- std::mutex::native_handle + .SH Synopsis native_handle_type native_handle(); \fI(since C++11)\fP + (not always present) Returns the underlying implementation-defined native handle object. @@ -14,14 +18,12 @@ .SH Exceptions - This section is incomplete + Implementation-defined. .SH Example This section is incomplete Reason: no example - Categories: - - * Todo without reason +.SH Category: * Todo no example diff --git a/man/std::mutex::try_lock.3 b/man/std::mutex::try_lock.3 index 38e7b22a0..dfa9a538a 100644 --- a/man/std::mutex::try_lock.3 +++ b/man/std::mutex::try_lock.3 @@ -1,4 +1,7 @@ -.TH std::mutex::try_lock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex::try_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex::try_lock \- std::mutex::try_lock + .SH Synopsis bool try_lock(); \fI(since C++11)\fP @@ -25,40 +28,44 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Example - - + + // Run this code #include + #include // std::cout #include #include - #include // std::cout - + std::chrono::milliseconds interval(100); - + std::mutex mutex; int job_shared = 0; // both threads can modify 'job_shared', - // mutex will protect this variable - + // mutex will protect this variable + int job_exclusive = 0; // only one thread can modify 'job_exclusive' - // no protection needed - + // no protection needed + // this thread can modify both 'job_shared' and 'job_exclusive' void job_1() { std::this_thread::sleep_for(interval); // let 'job_2' take a lock - - while (true) { + + while (true) + { // try to lock mutex to modify 'job_shared' - if (mutex.try_lock()) { + if (mutex.try_lock()) + { std::cout << "job shared (" << job_shared << ")\\n"; mutex.unlock(); return; - } else { + } + else + { // can't get lock to modify 'job_shared' // but there is some other work to do ++job_exclusive; @@ -67,7 +74,7 @@ } } } - + // this thread can modify only 'job_shared' void job_2() { @@ -76,12 +83,12 @@ ++job_shared; mutex.unlock(); } - + int main() { std::thread thread_1(job_1); std::thread thread_2(job_2); - + thread_1.join(); thread_2.join(); } @@ -97,6 +104,8 @@ .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP unlock unlocks the mutex - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_trylock diff --git a/man/std::mutex::unlock.3 b/man/std::mutex::unlock.3 index 6738b3bad..1604d3685 100644 --- a/man/std::mutex::unlock.3 +++ b/man/std::mutex::unlock.3 @@ -1,4 +1,7 @@ -.TH std::mutex::unlock 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex::unlock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex::unlock \- std::mutex::unlock + .SH Synopsis void unlock(); \fI(since C++11)\fP @@ -20,7 +23,7 @@ .SH Exceptions - \fI(none)\fP + Throws nothing. .SH Notes @@ -29,46 +32,54 @@ .SH Example - This example shows lock, try_lock and unlock in action: + This example shows how lock and unlock can be used to protect shared data. + - // Run this code + #include #include #include - - int main() + #include + + int g_num = 0; // protected by g_num_mutex + std::mutex g_num_mutex; + + void slow_increment(int id) { - std::mutex test; - if (test.try_lock()) { - std::cout << "first try_lock successful\\n"; - } else { - std::cout << "first try_lock NOT successful\\n"; - return 0; + for (int i = 0; i < 3; ++i) + { + g_num_mutex.lock(); + int g_num_running = ++g_num; + g_num_mutex.unlock(); + std::cout << id << " => " << g_num_running << '\\n'; + + std::this_thread::sleep_for(std::chrono::seconds(1)); } - - test.unlock(); - test.lock(); - - if (test.try_lock()) { - std::cout << "second try_lock successful\\n"; - } else { - std::cout << "second try_lock NOT successful\\n"; - } - - test.lock(); // trying to lock an already-locked std::mutex will - // block program execution, so we'll hang here + } + + int main() + { + std::thread t1(slow_increment, 0); + std::thread t2(slow_increment, 1); + t1.join(); + t2.join(); } .SH Possible output: - first try_lock successful - second try_lock NOT successful - (program hangs) + 0 => 1 + 1 => 2 + 0 => 3 + 1 => 4 + 0 => 5 + 1 => 6 .SH See also lock locks the mutex, blocks if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP try_lock tries to lock the mutex, returns if the mutex is not available - \fI(public member function)\fP + \fI(public member function)\fP + C documentation for + mtx_unlock diff --git a/man/std::mutex::~mutex.3 b/man/std::mutex::~mutex.3 index 6da807b76..ebce980a1 100644 --- a/man/std::mutex::~mutex.3 +++ b/man/std::mutex::~mutex.3 @@ -1,4 +1,7 @@ -.TH std::mutex::~mutex 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::mutex::~mutex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::mutex::~mutex \- std::mutex::~mutex + .SH Synopsis ~mutex(); @@ -6,3 +9,8 @@ The behavior is undefined if the mutex is owned by any thread or if any thread terminates while holding any ownership of the mutex. + +.SH See also + + C documentation for + mtx_destroy diff --git a/man/std::nan,std::nanf,std::nanl.3 b/man/std::nan,std::nanf,std::nanl.3 index ca4d1f1a9..dc45f73fd 100644 --- a/man/std::nan,std::nanf,std::nanl.3 +++ b/man/std::nan,std::nanf,std::nanl.3 @@ -1,29 +1,85 @@ -.TH std::nan,std::nanf,std::nanl 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nan,std::nanf,std::nanl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nan,std::nanf,std::nanl \- std::nan,std::nanf,std::nanl + .SH Synopsis Defined in header - float nanf( const char* arg ); \fI(since C++11)\fP - double nan( const char* arg ); \fI(since C++11)\fP - long double nanl( const char* arg ); \fI(since C++11)\fP + float nanf( const char* arg ); \fB(1)\fP \fI(since C++11)\fP + double nan ( const char* arg ); \fB(2)\fP \fI(since C++11)\fP + long double nanl( const char* arg ); \fB(3)\fP \fI(since C++11)\fP + + Converts the character string arg into the corresponding quiet NaN value, as if by + calling std::strtof, std::strtod, or std::strtold, respectively. - Converts the implementation-defined character string arg into the corresponding - quiet NaN value. The call std::nan("string") is equivalent to the call - std::strtod("NAN(string)", (char**)NULL);. + 1) The call std::nanf("n-char-sequence"), where n-char-sequence is a sequence of + digits, ASCII letters, and underscores, is equivalent to the call + std::strtof("NAN(n-char-sequence)", (char**)nullptr);. + The call std::nanf("") is equivalent to the call std::strtof("NAN()", + (char**)nullptr);. + The call std::nanf("string"), where string is neither an n-char-sequence nor an + empty string, is equivalent to the call std::strtof("NAN", (char**)nullptr);. + 2) Same as \fB(1)\fP, but calls std::strtod instead of std::strtof. + 3) Same as \fB(1)\fP, but calls std::strtold instead of std::strtof. .SH Parameters - arg - narrow character string identifying the contents of a NaN, or an empty string + arg - narrow character string identifying the contents of a NaN .SH Return value - The NaN value that corresponds to the identifying string arg or zero if the + The quiet NaN value that corresponds to the identifying string arg or zero if the implementation does not support quiet NaNs. + If the implementation supports IEEE floating-point arithmetic (IEC 60559), it also + supports quiet NaNs. + +.SH Error handling + + This function is not subject to any of the error conditions specified in + math_errhandling. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + double f1 = std::nan("1"); + std::uint64_t f1n; std::memcpy(&f1n, &f1, sizeof f1); + std::cout << "nan(\\"1\\") = " << f1 << " (" << std::hex << f1n << ")\\n"; + + double f2 = std::nan("2"); + std::uint64_t f2n; std::memcpy(&f2n, &f2, sizeof f2); + std::cout << "nan(\\"2\\") = " << f2 << " (" << std::hex << f2n << ")\\n"; + } + +.SH Possible output: + + nan("1") = nan (7ff0000000000001) + nan("2") = nan (7ff0000000000002) + .SH See also - isnan checks if the given number is NaN - \fI(C++11)\fP \fI(function)\fP - quiet_NaN returns a quiet NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + isnan checks if the given number is NaN + \fI(C++11)\fP \fI(function)\fP + NAN evaluates to a quiet NaN of type float + \fI(C++11)\fP (macro constant) + has_quiet_NaN identifies floating-point types that can represent the special + \fB[static]\fP value "quiet not-a-number" (NaN) + \fI(public static member constant of std::numeric_limits)\fP + has_signaling_NaN identifies floating-point types that can represent the special + \fB[static]\fP value "signaling not-a-number" (NaN) + \fI(public static member constant of std::numeric_limits)\fP + quiet_NaN returns a quiet NaN value of the given floating-point type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP + signaling_NaN returns a signaling NaN value of the given floating-point type + \fB[static]\fP \fI(public static member function of std::numeric_limits)\fP C documentation for nanf, nan, diff --git a/man/std::nearbyint,std::nearbyintf,std::nearbyintl.3 b/man/std::nearbyint,std::nearbyintf,std::nearbyintl.3 new file mode 100644 index 000000000..f1af871b0 --- /dev/null +++ b/man/std::nearbyint,std::nearbyintf,std::nearbyintl.3 @@ -0,0 +1,155 @@ +.TH std::nearbyint,std::nearbyintf,std::nearbyintl 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nearbyint,std::nearbyintf,std::nearbyintl \- std::nearbyint,std::nearbyintf,std::nearbyintl + +.SH Synopsis + Defined in header + float nearbyint ( float num ); + + double nearbyint ( double num ); (until C++23) + + long double nearbyint ( long double num ); + /* floating-point-type */ (since C++23) + nearbyint ( /* floating-point-type */ num ); \fB(1)\fP + float nearbyintf( float num ); \fB(2)\fP \fI(since C++11)\fP + long double nearbyintl( long double num ); \fB(3)\fP \fI(since C++11)\fP + Additional overloads \fI(since C++11)\fP + Defined in header + template< class Integer > (A) + double nearbyint ( Integer num ); + + 1-3) Rounds the floating-point argument num to an integer value in floating-point + format, using the current rounding mode. + The library provides overloads of std::nearbyint for all cv-unqualified + floating-point types as the type of the parameter. + (since C++23) + + A) Additional overloads are provided for all integer types, which are \fI(since C++11)\fP + treated as double. + +.SH Parameters + + num - floating-point or integer value + +.SH Return value + + The nearest integer value to num, according to the current rounding mode, is + returned. + +.SH Error handling + + This function is not subject to any of the errors specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * FE_INEXACT is never raised. + * If num is ±∞, it is returned, unmodified. + * If num is ±0, it is returned, unmodified. + * If num is NaN, NaN is returned. + +.SH Notes + + The only difference between std::nearbyint and std::rint is that std::nearbyint + never raises FE_INEXACT. + + The largest representable floating-point values are exact integers in all standard + floating-point formats, so std::nearbyint never overflows on its own; however the + result may overflow any integer type (including std::intmax_t), when stored in an + integer variable. + + If the current rounding mode is FE_TONEAREST, this function rounds to even in + halfway cases (like std::rint, but unlike std::round). + + The additional overloads are not required to be provided exactly as (A). They only + need to be sufficient to ensure that for their argument num of integer type, + std::nearbyint(num) has the same effect as std::nearbyint(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #pragma STDC FENV_ACCESS ON + + int main() + { + std::fesetround(FE_TONEAREST); + std::cout << "rounding to nearest: \\n" + << "nearbyint(+2.3) = " << std::nearbyint(2.3) + << " nearbyint(+2.5) = " << std::nearbyint(2.5) + << " nearbyint(+3.5) = " << std::nearbyint(3.5) << '\\n' + << "nearbyint(-2.3) = " << std::nearbyint(-2.3) + << " nearbyint(-2.5) = " << std::nearbyint(-2.5) + << " nearbyint(-3.5) = " << std::nearbyint(-3.5) << '\\n'; + + std::fesetround(FE_DOWNWARD); + std::cout << "rounding down:\\n" + << "nearbyint(+2.3) = " << std::nearbyint(2.3) + << " nearbyint(+2.5) = " << std::nearbyint(2.5) + << " nearbyint(+3.5) = " << std::nearbyint(3.5) << '\\n' + << "nearbyint(-2.3) = " << std::nearbyint(-2.3) + << " nearbyint(-2.5) = " << std::nearbyint(-2.5) + << " nearbyint(-3.5) = " << std::nearbyint(-3.5) << '\\n'; + + std::cout << "nearbyint(-0.0) = " << std::nearbyint(-0.0) << '\\n' + << "nearbyint(-Inf) = " << std::nearbyint(-INFINITY) << '\\n'; + } + +.SH Output: + + rounding to nearest: + nearbyint(+2.3) = 2 nearbyint(+2.5) = 2 nearbyint(+3.5) = 4 + nearbyint(-2.3) = -2 nearbyint(-2.5) = -2 nearbyint(-3.5) = -4 + rounding down: + nearbyint(+2.3) = 2 nearbyint(+2.5) = 2 nearbyint(+3.5) = 3 + nearbyint(-2.3) = -3 nearbyint(-2.5) = -3 nearbyint(-3.5) = -4 + nearbyint(-0.0) = -0 + nearbyint(-Inf) = -inf + +.SH See also + + rint + rintf + rintl + lrint + lrintf + lrintl + llrint + llrintf nearest integer using current rounding mode with + llrintl exception if the result differs + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + round + roundf + roundl + lround + lroundf + lroundl + llround + llroundf + llroundl nearest integer, rounding away from zero in halfway cases + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + fegetround + fesetround gets or sets rounding direction + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + C documentation for + nearbyint diff --git a/man/std::nearbyint.3 b/man/std::nearbyint.3 deleted file mode 100644 index 793759fc0..000000000 --- a/man/std::nearbyint.3 +++ /dev/null @@ -1,94 +0,0 @@ -.TH std::nearbyint 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float nearbyint( float arg ); \fI(since C++11)\fP - double nearbyint( double arg ); \fI(since C++11)\fP - long double nearbyint( long double arg ); \fI(since C++11)\fP - double nearbyint( Integral arg ); \fI(since C++11)\fP - - Rounds the floating-point argument arg to an integer value in floating-point format, - using the current rounding mode. - -.SH Parameters - - arg - floating point value - -.SH Return value - - The integer result of rounding arg - -.SH Notes - - The only difference between std::nearbyint and std::rint is that std::rint may raise - the FE_INEXACT floating-point exception, while std::nearbyint never raises it. - -.SH Example - - - -// Run this code - - #include - #include - #include - - int main() - { - #pragma STDC FENV_ACCESS ON - std::fesetround(FE_DOWNWARD); - std::cout << "rounding using FE_DOWNWARD: \\n" << std::fixed - << " 12.0 -> " << std::nearbyint(12.0) << '\\n' - << " 12.1 -> " << std::nearbyint(12.1) << '\\n' - << "-12.1 -> " << std::nearbyint(-12.1) << '\\n' - << " 12.5 -> " << std::nearbyint(12.5) << '\\n' - << " 12.9 -> " << std::nearbyint(12.9) << '\\n' - << "-12.9 -> " << std::nearbyint(-12.9) << '\\n' - << " 13.0 -> " << std::nearbyint(13.0) << '\\n'; - std::fesetround(FE_TONEAREST); - std::cout << "rounding using FE_TONEAREST: \\n" - << " 12.0 -> " << std::nearbyint(12.0) << '\\n' - << " 12.1 -> " << std::nearbyint(12.1) << '\\n' - << "-12.1 -> " << std::nearbyint(-12.1) << '\\n' - << " 12.5 -> " << std::nearbyint(12.5) << '\\n' - << " 12.9 -> " << std::nearbyint(12.9) << '\\n' - << "-12.9 -> " << std::nearbyint(-12.9) << '\\n' - << " 13.0 -> " << std::nearbyint(13.0) << '\\n'; - } - -.SH Output: - - rounding using FE_DOWNWARD: - 12.0 -> 12.000000 - 12.1 -> 12.000000 - -12.1 -> -13.000000 - 12.5 -> 12.000000 - 12.9 -> 12.000000 - -12.9 -> -13.000000 - 13.0 -> 13.000000 - rounding using FE_TONEAREST: - 12.0 -> 12.000000 - 12.1 -> 12.000000 - -12.1 -> -12.000000 - 12.5 -> 12.000000 - 12.9 -> 13.000000 - -12.9 -> -13.000000 - 13.0 -> 13.000000 - -.SH See also - - rint - lrint nearest integer using current rounding mode with - llrint exception if the result differs - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP - round - lround - llround nearest integer, rounding away from zero in halfway cases - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP - \fI(C++11)\fP - fegetround - fesetround gets or sets rounding direction - \fI(C++11)\fP \fI(function)\fP - \fI(C++11)\fP diff --git a/man/std::negate.3 b/man/std::negate.3 index 047fad29b..558508691 100644 --- a/man/std::negate.3 +++ b/man/std::negate.3 @@ -1,4 +1,7 @@ -.TH std::negate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negate \- std::negate + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -15,22 +18,25 @@ is not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing -x deducing argument and - negate return types - \fI(class template specialization)\fP + negate function object implementing -x deducing parameter and + \fI(C++14)\fP return types + \fI(class template specialization)\fP .SH Member types - Type Definition - result_type T - argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) T + argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::unary_function. .SH Member functions operator() returns the negation of the argument \fI(public member function)\fP - std::negate::operator() +std::negate::operator() T operator()( const T& arg ) const; \fI(until C++14)\fP constexpr T operator()( const T& arg ) const; \fI(since C++14)\fP @@ -47,11 +53,11 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr T operator()(const T &arg) const + constexpr T operator()(const T& arg) const { return -arg; } diff --git a/man/std::negate.3 b/man/std::negate.3 deleted file mode 100644 index d9188faa2..000000000 --- a/man/std::negate.3 +++ /dev/null @@ -1,55 +0,0 @@ -.TH std::negate 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class negate; - - std::negate<> is a specialization of std::negate with parameter and return type - deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() returns its negated argument - \fI(public member function)\fP - - std::negate<>::operator() - - template< class T > - - constexpr auto operator()( T&& arg ) const - - -> decltype(-std::forward(arg)); - - Returns the result of negating arg (or whatever the unary operator- is overloaded to - do) - -.SH Parameters - - arg - value to negate - -.SH Return value - - The result of -arg. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::negation.3 b/man/std::negation.3 new file mode 100644 index 000000000..b0d8265a2 --- /dev/null +++ b/man/std::negation.3 @@ -0,0 +1,100 @@ +.TH std::negation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negation \- std::negation + +.SH Synopsis + Defined in header + template< class B > \fI(since C++17)\fP + struct negation; + + Forms the logical negation of the type trait B. + + The type std::negation is a UnaryTypeTrait with a base characteristic of + std::bool_constant. + + If the program adds specializations for std::negation or std::negation_v, the + behavior is undefined. + +.SH Template parameters + + B - any type such that the expression bool(B::value) is a valid constant expression + + Helper variable template + + template< class B > \fI(since C++17)\fP + inline constexpr bool negation_v = negation::value; + + + +Inherited from std::integral_constant + +.SH Member constants + + value true if B has a member ::value that is false when explicitly converted to + \fB[static]\fP bool, false otherwise + \fI(public static member constant)\fP + +.SH Member functions + + operator bool converts the object to bool, returns value + \fI(public member function)\fP + operator() returns value + \fI(C++14)\fP \fI(public member function)\fP + +.SH Member types + + Type Definition + value_type bool + type std::integral_constant + +.SH Possible implementation + + template + struct negation : std::bool_constant { }; + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_logical_traits 201510L \fI(C++17)\fP Logical operator type traits + +.SH Example + + +// Run this code + + #include + #include + + static_assert( + std::is_same< + std::bool_constant, + typename std::negation>::type>::value, + ""); + static_assert( + std::is_same< + std::bool_constant, + typename std::negation>::type>::value, + ""); + + int main() + { + std::cout << std::boolalpha; + std::cout << std::negation>::value << '\\n'; + std::cout << std::negation>::value << '\\n'; + } + +.SH Output: + + false + true + +.SH See also + + conjunction variadic logical AND metafunction + \fI(C++17)\fP \fI(class template)\fP + disjunction variadic logical OR metafunction + \fI(C++17)\fP \fI(class template)\fP + integral_constant + bool_constant compile-time constant of specified type with specified value + \fI(C++11)\fP \fI(class template)\fP + \fI(C++17)\fP diff --git a/man/std::negative_binomial_distribution.3 b/man/std::negative_binomial_distribution.3 index 89bc127ba..c56a848d3 100644 --- a/man/std::negative_binomial_distribution.3 +++ b/man/std::negative_binomial_distribution.3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution \- std::negative_binomial_distribution + .SH Synopsis Defined in header template< class IntType = int > \fI(since C++11)\fP @@ -7,7 +10,7 @@ Produces random non-negative integer values i, distributed according to discrete probability function: - P(i|k,p) =⎛ + \\(P(i|k, p) = \\binom{k + i - 1}{i} \\cdot p^k \\cdot (1 - p)^i\\)P(i|k,p) =⎛ ⎜ ⎝k + i − 1 i⎞ @@ -18,49 +21,61 @@ The value represents the number of failures in a series of independent yes/no trials (each succeeds with probability p), before exactly k successes occur. + std::negative_binomial_distribution satisfies RandomNumberDistribution. + +.SH Template parameters + + The result type generated by the generator. The effect is undefined if + IntType - this is not one of short, int, long, long long, unsigned short, unsigned + int, unsigned long, or unsigned long long. + .SH Member types - Member type Definition - result_type IntType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP IntType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics p returns the distribution parameters - k \fI(public member function)\fP + k \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include #include - #include + #include #include #include - + #include + int main() { std::random_device rd; @@ -69,17 +84,16 @@ // At each house, there's a 75% chance that she sells one box // how many times will she be turned away before selling 5 boxes? std::negative_binomial_distribution<> d(5, 0.75); - + std::map hist; - for(int n=0; n<10000; ++n) { + for (int n = 0; n != 10000; ++n) ++hist[d(gen)]; - } - for(auto p : hist) { - std::cout << p.first << ' ' << std::string(p.second/100, '*') << '\\n'; - } + + for (auto [x, y] : hist) + std::cout << std::hex << x << ' ' << std::string(y / 100, '*') << '\\n'; } -.SH Output: +.SH Possible output: 0 *********************** 1 ***************************** @@ -91,10 +105,10 @@ 7 8 9 - 10 - 11 + a + b .SH External links - Weisstein, Eric W. "Negative Binomial Distribution." From MathWorld--A Wolfram Web + Weisstein, Eric W. "Negative Binomial Distribution." From MathWorld — A Wolfram Web Resource. diff --git a/man/std::negative_binomial_distribution::max.3 b/man/std::negative_binomial_distribution::max.3 index 53acf5cf9..bfd30ca81 100644 --- a/man/std::negative_binomial_distribution::max.3 +++ b/man/std::negative_binomial_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::max \- std::negative_binomial_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::negative_binomial_distribution::min.3 b/man/std::negative_binomial_distribution::min.3 index 6d0854297..64501faa5 100644 --- a/man/std::negative_binomial_distribution::min.3 +++ b/man/std::negative_binomial_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::min \- std::negative_binomial_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::negative_binomial_distribution::negative_binomial_distribution.3 b/man/std::negative_binomial_distribution::negative_binomial_distribution.3 index b6d36f741..dbe260cd5 100644 --- a/man/std::negative_binomial_distribution::negative_binomial_distribution.3 +++ b/man/std::negative_binomial_distribution::negative_binomial_distribution.3 @@ -1,17 +1,23 @@ -.TH std::negative_binomial_distribution::negative_binomial_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::negative_binomial_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::negative_binomial_distribution \- std::negative_binomial_distribution::negative_binomial_distribution + .SH Synopsis - explicit negative_binomial_distribution( IntType k = 1, double p = \fB(1)\fP \fI(since C++11)\fP - 0.5 ); - explicit negative_binomial_distribution( const param_type& params \fB(2)\fP \fI(since C++11)\fP + negative_binomial_distribution() : \fB(1)\fP \fI(since C++11)\fP + negative_binomial_distribution\fB(1)\fP {} + explicit negative_binomial_distribution( IntType k, double p = 0.5 \fB(2)\fP \fI(since C++11)\fP + ); + explicit negative_binomial_distribution( const param_type& params \fB(3)\fP \fI(since C++11)\fP ); - Constructs a new distribution object. The first version uses k and p as the - distribution parameters, the second version uses params as the distribution - parameters. + Constructs a new distribution object. + + 2) Uses k and p as the distribution parameters. + 3) Uses params as the distribution parameters. .SH Parameters - k - the k distribution parameter (number of trial failures) + k - the k distribution parameter (number of trial successes) p - the p distribution parameter (probability of a trial generating true) params - the distribution parameter set @@ -19,5 +25,16 @@ Requires that 0 < p ≤ 1 and 0 < k. + If p == 1, subsequent calls to the operator() overload that does not accept a + param_type object will cause undefined behavior. + The default-constructed std::negative_binomial_distribution is equivalent to the default-constructed std::geometric_distribution. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::negative_binomial_distribution::operator().3 b/man/std::negative_binomial_distribution::operator().3 index 537ef297d..5e8904902 100644 --- a/man/std::negative_binomial_distribution::operator().3 +++ b/man/std::negative_binomial_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::operator() \- std::negative_binomial_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::negative_binomial_distribution::p,k.3 b/man/std::negative_binomial_distribution::p,k.3 index 4a2cc2c65..bac99cb70 100644 --- a/man/std::negative_binomial_distribution::p,k.3 +++ b/man/std::negative_binomial_distribution::p,k.3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution::p,k 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::p,k 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::p,k \- std::negative_binomial_distribution::p,k + .SH Synopsis double p() const; \fB(1)\fP \fI(since C++11)\fP IntType k() const; \fB(2)\fP \fI(since C++11)\fP @@ -21,5 +24,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::negative_binomial_distribution::param.3 b/man/std::negative_binomial_distribution::param.3 index 551a36a82..cd129abba 100644 --- a/man/std::negative_binomial_distribution::param.3 +++ b/man/std::negative_binomial_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::param \- std::negative_binomial_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::negative_binomial_distribution::reset.3 b/man/std::negative_binomial_distribution::reset.3 index 9e116480a..a3643e7c6 100644 --- a/man/std::negative_binomial_distribution::reset.3 +++ b/man/std::negative_binomial_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::negative_binomial_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::negative_binomial_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::negative_binomial_distribution::reset \- std::negative_binomial_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::nested_exception.3 b/man/std::nested_exception.3 index 63809d0ae..36df35bc6 100644 --- a/man/std::nested_exception.3 +++ b/man/std::nested_exception.3 @@ -1,9 +1,12 @@ -.TH std::nested_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nested_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nested_exception \- std::nested_exception + .SH Synopsis Defined in header class nested_exception; \fI(since C++11)\fP - std::nested_exceptions is a polymorphic mixin class which can capture and store the + std::nested_exception is a polymorphic mixin class which can capture and store the current exception, making it possible to nest exceptions of arbitrary types within each other. @@ -20,65 +23,85 @@ nested_ptr obtains a pointer to the stored exception \fI(public member function)\fP +.SH Non-member functions + + throw_with_nested throws its argument with std::nested_exception mixed in + \fI(C++11)\fP \fI(function template)\fP + rethrow_if_nested throws the exception from a std::nested_exception + \fI(C++11)\fP \fI(function template)\fP + .SH Example - - Demonstrates construction and recursion through a nested exception object - + Demonstrates construction and recursion through a nested exception object. + + // Run this code + #include + #include #include #include - #include #include - #include - + // prints the explanatory string of an exception. If the exception is nested, // recurses to print the explanatory of the exception it holds void print_exception(const std::exception& e, int level = 0) { std::cerr << std::string(level, ' ') << "exception: " << e.what() << '\\n'; - try { + try + { std::rethrow_if_nested(e); - } catch(const std::exception& e) { - print_exception(e, level+1); - } catch(...) {} + } + catch (const std::exception& nestedException) + { + print_exception(nestedException, level + 1); + } + catch (...) {} } - + // sample function that catches an exception and wraps it in a nested exception void open_file(const std::string& s) { - try { + try + { std::ifstream file(s); file.exceptions(std::ios_base::failbit); - } catch(...) { - std::throw_with_nested( std::runtime_error("Couldn't open " + s) ); + } + catch (...) + { + std::throw_with_nested(std::runtime_error("Couldn't open " + s)); } } - + // sample function that catches an exception and wraps it in a nested exception void run() { - try { + try + { open_file("nonexistent.file"); - } catch(...) { - std::throw_with_nested( std::runtime_error("run() failed") ); + } + catch (...) + { + std::throw_with_nested(std::runtime_error("run() failed")); } } - + // runs the sample function above and prints the caught exception int main() { - try { + try + { run(); - } catch(const std::exception& e) { + } + catch (const std::exception& e) + { print_exception(e); } } -.SH Output: +.SH Possible output: exception: run() failed exception: Couldn't open nonexistent.file @@ -87,8 +110,8 @@ .SH See also exception_ptr shared pointer type for handling exception objects - \fI(C++11)\fP \fI(typedef)\fP + \fI(C++11)\fP \fI(typedef)\fP throw_with_nested throws its argument with std::nested_exception mixed in - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP rethrow_if_nested throws the exception from a std::nested_exception - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::nested_exception::nested_exception.3 b/man/std::nested_exception::nested_exception.3 index 6055034e0..f040a3db0 100644 --- a/man/std::nested_exception::nested_exception.3 +++ b/man/std::nested_exception::nested_exception.3 @@ -1,20 +1,18 @@ -.TH std::nested_exception::nested_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nested_exception::nested_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nested_exception::nested_exception \- std::nested_exception::nested_exception + .SH Synopsis - nested_exception(); \fB(1)\fP \fI(since C++11)\fP - nested_exception( const nested_exception& other ) = default; \fB(2)\fP \fI(since C++11)\fP + nested_exception() noexcept; \fB(1)\fP \fI(since C++11)\fP + nested_exception( const nested_exception& other ) noexcept = \fB(2)\fP \fI(since C++11)\fP + default; Constructs new nested_exception object. 1) Default constructor. Stores an exception object obtained by calling std::current_exception() within the new nested_exception object. - 2) Copy contructor. Initializes the object with the exception stored in other. + 2) Copy constructor. Initializes the object with the exception stored in other. .SH Parameters other - nested exception to initialize the contents with - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::nested_exception::nested_ptr.3 b/man/std::nested_exception::nested_ptr.3 index 5a73d4f12..496241514 100644 --- a/man/std::nested_exception::nested_ptr.3 +++ b/man/std::nested_exception::nested_ptr.3 @@ -1,6 +1,9 @@ -.TH std::nested_exception::nested_ptr 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nested_exception::nested_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nested_exception::nested_ptr \- std::nested_exception::nested_ptr + .SH Synopsis - std::exception_ptr nested_ptr() const \fI(since C++11)\fP + std::exception_ptr nested_ptr() const noexcept; \fI(since C++11)\fP Returns a pointer to the stored exception, if any. @@ -10,10 +13,5 @@ .SH Return value - \fI(none)\fP - -.SH Exceptions - - noexcept specification: - noexcept - + A std::exception_ptr to the stored exception if one is stored, default-initialized + std::exception_ptr otherwise. diff --git a/man/std::nested_exception::operator=.3 b/man/std::nested_exception::operator=.3 index d7c0d643f..bb96177c8 100644 --- a/man/std::nested_exception::operator=.3 +++ b/man/std::nested_exception::operator=.3 @@ -1,7 +1,10 @@ -.TH std::nested_exception::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nested_exception::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nested_exception::operator= \- std::nested_exception::operator= + .SH Synopsis - nested_exception& operator=( const nested_exception& other ) = \fI(since C++11)\fP - default; + nested_exception& operator=( const nested_exception& other ) noexcept \fI(since C++11)\fP + = default; Replaces the stored exception with the one held in other. @@ -12,9 +15,3 @@ .SH Return value *this - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::nested_exception::rethrow_nested.3 b/man/std::nested_exception::rethrow_nested.3 index d7513256c..748c4d81d 100644 --- a/man/std::nested_exception::rethrow_nested.3 +++ b/man/std::nested_exception::rethrow_nested.3 @@ -1,4 +1,7 @@ -.TH std::nested_exception::rethrow_nested 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nested_exception::rethrow_nested 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nested_exception::rethrow_nested \- std::nested_exception::rethrow_nested + .SH Synopsis [[noreturn]] void rethrow_nested() const; \fI(since C++11)\fP diff --git a/man/std::nested_exception::~nested_exception.3 b/man/std::nested_exception::~nested_exception.3 index 22064646d..3e82b5d98 100644 --- a/man/std::nested_exception::~nested_exception.3 +++ b/man/std::nested_exception::~nested_exception.3 @@ -1,4 +1,7 @@ -.TH std::nested_exception::~nested_exception 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nested_exception::~nested_exception 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nested_exception::~nested_exception \- std::nested_exception::~nested_exception + .SH Synopsis virtual ~nested_exception() = default; \fI(since C++11)\fP diff --git a/man/std::new_handler.3 b/man/std::new_handler.3 index 65743f44f..2672adb2a 100644 --- a/man/std::new_handler.3 +++ b/man/std::new_handler.3 @@ -1,17 +1,20 @@ -.TH std::new_handler 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::new_handler 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::new_handler \- std::new_handler + .SH Synopsis Defined in header typedef void (*new_handler)(); std::new_handler is the function pointer type (pointer to function that takes no arguments and returns void), which is used by the functions std::set_new_handler and - std::get_new_handler + std::get_new_handler. .SH See also operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP set_new_handler registers a new handler - \fI(function)\fP + \fI(function)\fP get_new_handler obtains the current new handler - \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::next.3 b/man/std::next.3 index 06e09b645..c93989b2e 100644 --- a/man/std::next.3 +++ b/man/std::next.3 @@ -1,63 +1,101 @@ -.TH std::next 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::next 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::next \- std::next + .SH Synopsis Defined in header - template< class ForwardIt > + template< class InputIt > \fI(since C++11)\fP + InputIt next( InputIt it, typename \fI(until C++17)\fP + std::iterator_traits::difference_type n = 1 ); + template< class InputIt > - ForwardIt next( ForwardIt it, \fI(since C++11)\fP + constexpr \fI(since C++17)\fP - typename - std::iterator_traits::difference_type n = 1 ); + InputIt next( InputIt it, typename + std::iterator_traits::difference_type n = 1 ); - Return the nth successor of iterator it. + Return the n^th successor (or -n^th predecessor if n is negative) of iterator it. .SH Parameters - it - an iterator - n - number of elements to advance + it - an iterator + n - number of elements to advance .SH Type requirements - - ForwardIt must meet the requirements of ForwardIterator. + InputIt must meet the requirements of LegacyInputIterator. .SH Return value - The nth successor of iterator it. + An iterator of type InputIt that holds the n^th successor (or -n^th predecessor if n + is negative) of iterator it. + +.SH Complexity + + Linear. + + However, if InputIt additionally meets the requirements of + LegacyRandomAccessIterator, complexity is constant. .SH Possible implementation -template -ForwardIt next(ForwardIt it, typename std::iterator_traits::difference_type n = 1) -{ - std::advance(it, n); - return it; -} + template + constexpr // since C++17 + InputIt next(InputIt it, typename std::iterator_traits::difference_type n = 1) + { + std::advance(it, n); + return it; + } + +.SH Notes + + Although the expression ++c.begin() often compiles, it is not guaranteed to do so: + c.begin() is an rvalue expression, and there is no LegacyInputIterator requirement + that specifies that increment of an rvalue is guaranteed to work. In particular, + when iterators are implemented as pointers or its operator++ is + lvalue-ref-qualified, ++c.begin() does not compile, while std::next(c.begin()) does. .SH Example - + // Run this code #include #include #include - + int main() { - std::vector v{ 3, 1, 4 }; - + std::vector v{4, 5, 6}; + auto it = v.begin(); - auto nx = std::next(it, 2); - std::cout << *it << ' ' << *nx << '\\n'; + + it = v.end(); + nx = std::next(it, -2); + std::cout << ' ' << *nx << '\\n'; } .SH Output: - 3 4 + 4 6 + 5 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2353 C++11 next required LegacyForwardIterator LegacyInputIterator allowed .SH See also - prev decrement an iterator - \fI(C++11)\fP \fI(function)\fP - advance advances an iterator by given distance - \fI(function)\fP + prev decrement an iterator + \fI(C++11)\fP \fI(function template)\fP + advance advances an iterator by given distance + \fI(function template)\fP + distance returns the distance between two iterators + \fI(function template)\fP + ranges::next increment an iterator by a given distance or to a bound + (C++20) (niebloid) diff --git a/man/std::next_permutation.3 b/man/std::next_permutation.3 index 903c3ee5a..c4fa0d37b 100644 --- a/man/std::next_permutation.3 +++ b/man/std::next_permutation.3 @@ -1,107 +1,142 @@ -.TH std::next_permutation 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::next_permutation 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::next_permutation \- std::next_permutation + .SH Synopsis Defined in header - template< class BidirIt > \fB(1)\fP + template< class BidirIt > \fB(1)\fP (constexpr since C++20) bool next_permutation( BidirIt first, BidirIt last ); - template< class BidirIt, class Compare > \fB(2)\fP - bool next_permutation( BidirIt first, BidirIt last, Compare comp ); - - Transforms the range [first, last) into the next permutation from the set of all - permutations that are lexicographically ordered with respect to operator< or comp. - Returns true if such permutation exists, otherwise transforms the range into the - first permutation (as if by std::sort(first, last)) and returns false. + template< class BidirIt, class Compare > + bool next_permutation( BidirIt first, BidirIt last, \fB(2)\fP (constexpr since C++20) + Compare comp ); + + Permutes the range [first, last) into the next permutation. Returns true if such a + “next permutation” exists; otherwise transforms the range into the lexicographically + first permutation (as if by std::sort) and returns false. + + 1) The set of all permutations is ordered lexicographically with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 2) The set of all permutations is ordered lexicographically with respect to comp. + + If + the type of *first is not Swappable + \fI(until C++11)\fP + BidirIt is not ValueSwappable + \fI(since C++11)\fP, the behavior is undefined. .SH Parameters - first, last - the range of elements to permute - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less than the second. + first, last - the range of elements to permute + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type BidirIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type BidirIt + can be dereferenced and then implicitly converted to both of them. .SH Type requirements - - BidirIt must meet the requirements of ValueSwappable and BidirectionalIterator. + BidirIt must meet the requirements of LegacyBidirectionalIterator. .SH Return value true if the new permutation is lexicographically greater than the old. false if the last permutation was reached and the range was reset to the first permutation. -.SH Exceptions +.SH Complexity - Any exceptions thrown from iterator operations or the element swap. + Given \\(\\scriptsize N\\)N as std::distance(first, last): -.SH Complexity + 1,2) At most \\(\\scriptsize \\frac{N}{2}\\) + + N + 2 + + swaps. - At most N/2 swaps, where N = std::distance(first, last). +.SH Exceptions + + Any exceptions thrown from iterator operations or the element swap. .SH Possible implementation template bool next_permutation(BidirIt first, BidirIt last) { - if (first == last) return false; - BidirIt i = last; - if (first == --i) return false; - - while \fB(1)\fP { - BidirIt i1, i2; - - i1 = i; - if (*--i < *i1) { - i2 = last; - while (!(*i < *--i2)) - ; - std::iter_swap(i, i2); - std::reverse(i1, last); - return true; - } - if (i == first) { - std::reverse(first, last); - return false; - } + auto r_first = std::make_reverse_iterator(last); + auto r_last = std::make_reverse_iterator(first); + auto left = std::is_sorted_until(r_first, r_last); + + if (left != r_last) + { + auto right = std::upper_bound(r_first, left, *left); + std::iter_swap(left, right); } + + std::reverse(left.base(), last); + return left != r_last; } +.SH Notes + + Averaged over the entire sequence of permutations, typical implementations use about + 3 comparisons and 1.5 swaps per call. + + Implementations (e.g. MSVC STL) may enable vectorization when the iterator type + satisfies LegacyContiguousIterator and swapping its value type calls neither + non-trivial special member function nor ADL-found swap. + .SH Example - The following code prints all three permutations of the string "aba" + The following code prints all three permutations of the string "aba". + - // Run this code #include - #include #include - + #include + int main() { std::string s = "aba"; - std::sort(s.begin(), s.end()); - do { + + do + { std::cout << s << '\\n'; - } while(std::next_permutation(s.begin(), s.end())); + } + while (std::next_permutation(s.begin(), s.end())); + + std::cout << s << '\\n'; } .SH Output: - aab aba baa + aab .SH See also - is_permutation determines if a sequence is a permutation of another sequence - \fI(C++11)\fP \fI(function template)\fP - generates the next smaller lexicographic permutation of a range of - prev_permutation elements - \fI(function template)\fP + is_permutation determines if a sequence is a permutation of another + \fI(C++11)\fP sequence + \fI(function template)\fP + generates the next smaller lexicographic permutation of a + prev_permutation range of elements + \fI(function template)\fP + ranges::next_permutation generates the next greater lexicographic permutation of a + (C++20) range of elements + (niebloid) diff --git a/man/std::nextafter,std::nextafterf,std::nextafterl,std::nexttoward,std::nexttowardf,.3 b/man/std::nextafter,std::nextafterf,std::nextafterl,std::nexttoward,std::nexttowardf,.3 new file mode 100644 index 000000000..2a58ee7c3 --- /dev/null +++ b/man/std::nextafter,std::nextafterf,std::nextafterl,std::nexttoward,std::nexttowardf,.3 @@ -0,0 +1,274 @@ +.TH std::nextafter,std::nextafterf,std::nextafterl,std::nexttoward,std::nexttowardf, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nextafter,std::nextafterf,std::nextafterl,std::nexttoward,std::nexttowardf, \- std::nextafter,std::nextafterf,std::nextafterl,std::nexttoward,std::nexttowardf, + +.SH Synopsis + + Defined in header + float nextafter ( float from, float + to ); + + double nextafter ( double from, \fI(since C++11)\fP + double to ); (until C++23) + + long double nextafter ( long double from, + long double to ); + constexpr /* floating-point-type */ + + nextafter ( /* + floating-point-type */ from, (since C++23) + + /* + floating-point-type */ to ); + float nextafterf( float from, float \fI(since C++11)\fP + to ); \fB(2)\fP (constexpr since + C++23) + long double nextafterl( long double from, \fI(since C++11)\fP + long double to ); \fB(3)\fP (constexpr since + C++23) + float nexttoward ( float from, long + double to ); + + double nexttoward ( double from, long \fI(since C++11)\fP + double to ); (until C++23) + \fB(1)\fP + long double nexttoward ( long double from, + long double to ); + constexpr /* floating-point-type */ + + nexttoward ( /* (since C++23) + floating-point-type */ from, + + long double to ); + float nexttowardf( float from, long \fI(since C++11)\fP + double to ); \fB(4)\fP \fB(5)\fP (constexpr since + C++23) + long double nexttowardl( long double from, \fI(since C++11)\fP + long double to ); \fB(6)\fP (constexpr since + C++23) + Additional overloads + Defined in header + template< class Arithmetic1, class + Arithmetic2 > + \fI(since C++11)\fP + /* common-floating-point-type */ (A) (constexpr since + C++23) + nextafter( Arithmetic1 from, + Arithmetic2 to ); + template< class Integer > \fI(since C++11)\fP + double nexttoward( Integer from, long (B) (constexpr since + double to ); C++23) + + Returns the next representable value of from in the direction of to. + + 1-3) If from equals to, to is returned. + The library provides overloads of std::nextafter for all cv-unqualified + floating-point types as the type of the parameters from and to. + (since C++23) + 4-6) If from equals to, to is returned, converted from long double to the return + type of the function without loss of range or precision. + + The library provides overloads of std::nexttoward for all + cv-unqualified floating-point types as the type of the parameter from. + However, an invocation of std::nexttoward is ill-formed if the (since C++23) + argument corresponding to from has extended floating-point type, + because the next representable value (or to) is not guaranteed to be + representable as long double. + + A) Additional std::nextafter overloads are provided for all other combinations of + arithmetic types. + B) Additional std::nexttoward overloads are provided for all integer types, which + are treated as double. + +.SH Parameters + + from, to - floating-point or integer values + +.SH Return value + + If no errors occur, the next representable value of from in the direction of to. is + returned. If from equals to, then to is returned. + + If a range error due to overflow occurs, ±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL is + returned (with the same sign as from). + + If a range error occurs due to underflow, the correct result is returned. + +.SH Error handling + + Errors are reported as specified in math_errhandling. + + If the implementation supports IEEE floating-point arithmetic (IEC 60559), + + * if from is finite, but the expected result is an infinity, raises FE_INEXACT and + FE_OVERFLOW. + * if from does not equal to and the result is subnormal or zero, raises FE_INEXACT + and FE_UNDERFLOW. + * in any case, the returned value is independent of the current rounding mode. + * if either from or to is NaN, NaN is returned. + +.SH Notes + + POSIX specifies that the overflow and the underflow conditions are range errors + (errno may be set). + + IEC 60559 recommends that from is returned whenever from == to. These functions + return to instead, which makes the behavior around zero consistent: + std::nextafter(-0.0, +0.0) returns +0.0 and std::nextafter(+0.0, -0.0) returns -0.0. + + std::nextafter is typically implemented by manipulation of IEEE representation + (glibc, musl). + + The additional std::nextafter overloads are not required to be provided exactly as + (A). They only need to be sufficient to ensure that for their first argument num1 + and second argument num2: + + * If num1 or num2 has type long double, then std::nextafter(num1, + num2) has the same effect as std::nextafter(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 and/or num2 has type double or an integer type, + then std::nextafter(num1, num2) has the same effect as (until C++23) + std::nextafter(static_cast(num1), + static_cast(num2)). + * Otherwise, if num1 or num2 has type float, then + std::nextafter(num1, num2) has the same effect as + std::nextafter(static_cast(num1), + static_cast(num2)). + If num1 and num2 have arithmetic types, then std::nextafter(num1, + num2) has the same effect as std::nextafter(static_cast(num1), + static_cast(num2)), + where /* common-floating-point-type */ is the floating-point type with + the greatest floating-point conversion rank and greatest + floating-point conversion subrank between the types of num1 and num2, (since C++23) + arguments of integer type are considered to have the same + floating-point conversion rank as double. + + If no such floating-point type with the greatest rank and subrank + exists, then overload resolution does not result in a usable candidate + from the overloads provided. + + The additional std::nexttoward overloads are not required to be provided exactly as + (B). They only need to be sufficient to ensure that for their argument num of + integer type, std::nexttoward(num) has the same effect as + std::nexttoward(static_cast(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + + int main() + { + float from1 = 0, to1 = std::nextafter(from1, 1.f); + std::cout << "The next representable float after " << std::setprecision(20) << from1 + << " is " << to1 + << std::hexfloat << " (" << to1 << ")\\n" << std::defaultfloat; + + float from2 = 1, to2 = std::nextafter(from2, 2.f); + std::cout << "The next representable float after " << from2 << " is " << to2 + << std::hexfloat << " (" << to2 << ")\\n" << std::defaultfloat; + + double from3 = std::nextafter(0.1, 0), to3 = 0.1; + std::cout << "The number 0.1 lies between two valid doubles:\\n" + << std::setprecision(56) << " " << from3 + << std::hexfloat << " (" << from3 << ')' << std::defaultfloat + << "\\nand " << to3 << std::hexfloat << " (" << to3 << ")\\n" + << std::defaultfloat << std::setprecision(20); + + std::cout << "\\nDifference between nextafter and nexttoward:\\n"; + long double dir = std::nextafter(from1, 1.0L); // first subnormal long double + float x = std::nextafter(from1, dir); // first converts dir to float, giving 0 + std::cout << "With nextafter, next float after " << from1 << " is " << x << '\\n'; + x = std::nexttoward(from1, dir); + std::cout << "With nexttoward, next float after " << from1 << " is " << x << '\\n'; + + std::cout << "\\nSpecial values:\\n"; + { + // #pragma STDC FENV_ACCESS ON + std::feclearexcept(FE_ALL_EXCEPT); + double from4 = DBL_MAX, to4 = std::nextafter(from4, INFINITY); + std::cout << "The next representable double after " << std::setprecision(6) + << from4 << std::hexfloat << " (" << from4 << ')' + << std::defaultfloat << " is " << to4 + << std::hexfloat << " (" << to4 << ")\\n" << std::defaultfloat; + + if (std::fetestexcept(FE_OVERFLOW)) + std::cout << " raised FE_OVERFLOW\\n"; + if (std::fetestexcept(FE_INEXACT)) + std::cout << " raised FE_INEXACT\\n"; + } // end FENV_ACCESS block + + float from5 = 0.0, to5 = std::nextafter(from5, -0.0); + std::cout << "std::nextafter(+0.0, -0.0) gives " << std::fixed << to5 << '\\n'; + + auto precision_loss_demo = [](const auto rem, const Fp start) + { + std::cout << rem; + for (Fp from = start, to, Δ; + (Δ = (to = std::nextafter(from, +INFINITY)) - from) < Fp(10.0); + from *= Fp(10.0)) + std::cout << "nextafter(" << std::scientific << std::setprecision(0) << from + << ", INF) gives " << std::fixed << std::setprecision(6) << to + << "; Δ = " << Δ << '\\n'; + }; + + precision_loss_demo("\\nPrecision loss demo for float:\\n", 10.0f); + precision_loss_demo("\\nPrecision loss demo for double:\\n", 10.0e9); + precision_loss_demo("\\nPrecision loss demo for long double:\\n", 10.0e17L); + } + +.SH Output: + + The next representable float after 0 is 1.4012984643248170709e-45 (0x1p-149) + The next representable float after 1 is 1.0000001192092895508 (0x1.000002p+0) + The number 0.1 lies between two valid doubles: + 0.09999999999999999167332731531132594682276248931884765625 (0x1.9999999999999p-4) + and 0.1000000000000000055511151231257827021181583404541015625 (0x1.999999999999ap-4) + + Difference between nextafter and nexttoward: + With nextafter, next float after 0 is 0 + With nexttoward, next float after 0 is 1.4012984643248170709e-45 + + Special values: + The next representable double after 1.79769e+308 (0x1.fffffffffffffp+1023) is inf (inf) + raised FE_OVERFLOW + raised FE_INEXACT + std::nextafter(+0.0, -0.0) gives -0.000000 + + Precision loss demo for float: + nextafter(1e+01, INF) gives 10.000001; Δ = 0.000001 + nextafter(1e+02, INF) gives 100.000008; Δ = 0.000008 + nextafter(1e+03, INF) gives 1000.000061; Δ = 0.000061 + nextafter(1e+04, INF) gives 10000.000977; Δ = 0.000977 + nextafter(1e+05, INF) gives 100000.007812; Δ = 0.007812 + nextafter(1e+06, INF) gives 1000000.062500; Δ = 0.062500 + nextafter(1e+07, INF) gives 10000001.000000; Δ = 1.000000 + nextafter(1e+08, INF) gives 100000008.000000; Δ = 8.000000 + + Precision loss demo for double: + nextafter(1e+10, INF) gives 10000000000.000002; Δ = 0.000002 + nextafter(1e+11, INF) gives 100000000000.000015; Δ = 0.000015 + nextafter(1e+12, INF) gives 1000000000000.000122; Δ = 0.000122 + nextafter(1e+13, INF) gives 10000000000000.001953; Δ = 0.001953 + nextafter(1e+14, INF) gives 100000000000000.015625; Δ = 0.015625 + nextafter(1e+15, INF) gives 1000000000000000.125000; Δ = 0.125000 + nextafter(1e+16, INF) gives 10000000000000002.000000; Δ = 2.000000 + + Precision loss demo for long double: + nextafter(1e+18, INF) gives 1000000000000000000.062500; Δ = 0.062500 + nextafter(1e+19, INF) gives 10000000000000000001.000000; Δ = 1.000000 + nextafter(1e+20, INF) gives 100000000000000000008.000000; Δ = 8.000000 + +.SH See also + + C documentation for + nextafter diff --git a/man/std::nextafter,std::nexttoward.3 b/man/std::nextafter,std::nexttoward.3 deleted file mode 100644 index ad2d80d61..000000000 --- a/man/std::nextafter,std::nexttoward.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH std::nextafter,std::nexttoward 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - float nextafter( float from, float to ); \fB(1)\fP \fI(since C++11)\fP - double nextafter( double from, double to ); \fB(2)\fP \fI(since C++11)\fP - long double nextafter( long double from, long double to ); \fB(3)\fP \fI(since C++11)\fP - Promoted nextafter( Arithmetic from, Arithmetic to ); \fB(4)\fP \fI(since C++11)\fP - float nexttoward( float from, long double to ); \fB(5)\fP \fI(since C++11)\fP - double nexttoward( double from, long double to ); \fB(6)\fP \fI(since C++11)\fP - long double nexttoward( long double from, long double to ); \fB(7)\fP \fI(since C++11)\fP - double nexttoward( Integral from, long double to ); \fB(8)\fP \fI(since C++11)\fP - - Returns the next representable value of from in the direction of to. If from equals - to to, to is returned. - - 4) If any argument has integral type, it is cast to double. If any other argument is - long double, then the return type is long double, otherwise it is double - - If from is finite, but the result of nextafter or nexttoward is infinite, raises - FE_OVERFLOW and FE_INEXACT. If the result is subnormal or zero and from != to, - raises FE_UNDERFLOW and FE_INEXACT. In any case, the returned value is independent - of the current rounding mode. - -.SH Parameters - - from, to - floating point values - -.SH Return value - - the next representable value of from in the direction of to. - -.SH Example - - -// Run this code - - #include - #include - #include - - int main() - { - std::cout << "0.1 lies between the doubles " << std::setprecision(100) << '\\n' - << 0.1 << '\\n' << " and\\n" - << std::nextafter(0.1, 0) << '\\n'; - } - -.SH Output: - - 0.1 lies between the doubles - 0.1000000000000000055511151231257827021181583404541015625 - and - 0.09999999999999999167332731531132594682276248931884765625 diff --git a/man/std::nontype,std::nontype_t.3 b/man/std::nontype,std::nontype_t.3 new file mode 100644 index 000000000..da0a80e0d --- /dev/null +++ b/man/std::nontype,std::nontype_t.3 @@ -0,0 +1,27 @@ +.TH std::nontype,std::nontype_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nontype,std::nontype_t \- std::nontype,std::nontype_t + +.SH Synopsis + Defined in header + template< auto V > \fB(1)\fP (since C++26) + struct nontype_t { explicit nontype_t() = default; }; + template< auto V > \fB(2)\fP (since C++26) + inline constexpr std::nontype_t nontype {}; + + 1) The class template std::nontype_t can be used in the constructor's parameter list + to match the intended tag. + 2) The corresponding std::nontype instance of \fB(1)\fP is a disambiguation argument tag + that can be passed to the constructors of std::function_ref to indicate that the + contained object should be constructed with the value of the non-type template + parameter V. + +.SH Template parameters + + V - non-type template parameter of a structural type. + +.SH See also + + function_ref non-owning reference to any callable object with specified function + (C++26) call signature + \fI(class template)\fP diff --git a/man/std::noop_coroutine.3 b/man/std::noop_coroutine.3 new file mode 100644 index 000000000..3b9547535 --- /dev/null +++ b/man/std::noop_coroutine.3 @@ -0,0 +1,139 @@ +.TH std::noop_coroutine 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::noop_coroutine \- std::noop_coroutine + +.SH Synopsis + Defined in header + std::noop_coroutine_handle noop_coroutine() noexcept; \fI(since C++20)\fP + + Returns a coroutine handle referring to a no-op coroutine. + + If there has been already a coroutine state of no-op coroutine, it is unspecified + whether a subsequent call to noop_coroutine returns a previously obtained coroutine + handle, or a coroutine handle referring to a new coroutine state of no-op coroutine. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::noop_coroutine_handle referring to a no-op coroutine. + +.SH Notes + + Return values from different calls to noop_coroutine may and may not compare equal. + + noop_coroutine may only return a noop_coroutine_handle referring to a coroutine + state object without starting a coroutine. + +.SH Example + + +// Run this code + + #include + #include + #include + + template + struct task + { + struct promise_type + { + auto get_return_object() + { + return task(std::coroutine_handle::from_promise(*this)); + } + std::suspend_always initial_suspend() { return {}; } + struct final_awaiter + { + bool await_ready() noexcept { return false; } + void await_resume() noexcept {} + std::coroutine_handle<> + await_suspend(std::coroutine_handle h) noexcept + { + // final_awaiter::await_suspend is called when the execution of the + // current coroutine (referred to by 'h') is about to finish. + // If the current coroutine was resumed by another coroutine via + // co_await get_task(), a handle to that coroutine has been stored + // as h.promise().previous. In that case, return the handle to resume + // the previous coroutine. + // Otherwise, return noop_coroutine(), whose resumption does nothing. + + if (auto previous = h.promise().previous; previous) + return previous; + else + return std::noop_coroutine(); + } + }; + final_awaiter final_suspend() noexcept { return {}; } + void unhandled_exception() { throw; } + void return_value(T value) { result = std::move(value); } + + T result; + std::coroutine_handle<> previous; + }; + + task(std::coroutine_handle h) : coro(h) {} + task(task&& t) = delete; + ~task() { coro.destroy(); } + + struct awaiter + { + bool await_ready() { return false; } + T await_resume() { return std::move(coro.promise().result); } + auto await_suspend(std::coroutine_handle<> h) + { + coro.promise().previous = h; + return coro; + } + std::coroutine_handle coro; + }; + awaiter operator co_await() { return awaiter{coro}; } + T operator()() + { + coro.resume(); + return std::move(coro.promise().result); + } + + private: + std::coroutine_handle coro; + }; + + task get_random() + { + std::cout << "in get_random()\\n"; + co_return 4; + } + + task test() + { + task v = get_random(); + task u = get_random(); + std::cout << "in test()\\n"; + int x = (co_await v + co_await u); + co_return x; + } + + int main() + { + task t = test(); + int result = t(); + std::cout << result << '\\n'; + } + +.SH Output: + + in test() + in get_random() + in get_random() + 8 + +.SH See also + + noop_coroutine_promise used for coroutines with no observable effects + (C++20) \fI(class)\fP + noop_coroutine_handle std::coroutine_handle, intended + (C++20) to refer to a no-op coroutine + \fI(typedef)\fP diff --git a/man/std::noop_coroutine_promise.3 b/man/std::noop_coroutine_promise.3 new file mode 100644 index 000000000..986bf3f45 --- /dev/null +++ b/man/std::noop_coroutine_promise.3 @@ -0,0 +1,49 @@ +.TH std::noop_coroutine_promise 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::noop_coroutine_promise \- std::noop_coroutine_promise + +.SH Synopsis + Defined in header + struct noop_coroutine_promise {}; \fI(since C++20)\fP + + noop_coroutine_promise is the promise type of no-op coroutines. + + A no-op coroutine behaves as if it + + * does nothing other than the control flow of a coroutine, and + * is suspended immediately after beginning and resumption, and + * has a coroutine state such that destroying the state is no-op, and + * never reaches its final suspended point if there is any std::coroutine_handle + referring to it. + + This section is incomplete + Reason: more precise wording + + No-op coroutines can be started by std::noop_coroutine, and controlled by the + coroutine handle it returns. The returned coroutine handle is of type + std::noop_coroutine_handle, which is a synonym for + std::coroutine_handle. + + Some operations of a no-op coroutines are determined no-op at compile time through + the type std::noop_coroutine_handle. + + This section is incomplete + Reason: usage of no-op coroutines + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + noop_coroutine creates a coroutine handle that has no observable effects when + (C++20) resumed or destroyed + \fI(function)\fP + noop_coroutine_handle std::coroutine_handle, intended + (C++20) to refer to a no-op coroutine + \fI(typedef)\fP + +.SH Categories: + * Todo with reason + * Todo no example diff --git a/man/std::norm(std::complex).3 b/man/std::norm(std::complex).3 index 994e6e490..f197d1898 100644 --- a/man/std::norm(std::complex).3 +++ b/man/std::norm(std::complex).3 @@ -1,32 +1,102 @@ -.TH std::norm(std::complex) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::norm(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::norm(std::complex) \- std::norm(std::complex) + .SH Synopsis Defined in header - template< class T > \fB(1)\fP - T norm( const complex& z ); - long double norm( long double z ); \fB(2)\fP \fI(since C++11)\fP - template< class DoubleOrIngeter > \fB(3)\fP \fI(since C++11)\fP - double norm( DoubleOrInteger z ); - float norm( float z ); \fB(4)\fP \fI(since C++11)\fP + template< class T > + T norm( const std::complex& z \fI(until C++20)\fP + ); + template< class T > + constexpr T norm( const \fI(since C++20)\fP + std::complex& z ); + Additional overloads \fI(since C++11)\fP + Defined in header + float norm( float f ); + + double norm( double f ); \fI(until C++20)\fP + + long double norm( long double f ); + constexpr float norm( float + f ); \fB(1)\fP + + constexpr double norm( double \fI(since C++20)\fP + f ); (until C++23) + (A) + constexpr long double norm( long + double f ); + template< class FloatingPoint > + constexpr FloatingPoint norm( (since C++23) + FloatingPoint f ); + template< class Integer > \fI(until C++20)\fP + double norm( Integer i ); + template< class Integer > (B) + constexpr double norm( Integer i \fI(since C++20)\fP + ); - Returns the squared magnitude of the complex number z. + 1) Returns the squared magnitude of the complex number z. - \fI(since C++11)\fPAdditional overloads are provided for float, double, long double, and - all integer types, which are treated as complex numbers with zero imaginary - component. + A,B) Additional overloads are provided for all integer and + floating-point types, which are treated as complex numbers with zero \fI(since C++11)\fP + imaginary component. .SH Parameters z - complex value + f - floating-point value + i - integer value .SH Return value - the squared magnitude of z + 1) The squared magnitude of z. + A) The square of f. + B) The square of i. + +.SH Notes + + The norm calculated by this function is also known as field norm or absolute square. + + The Euclidean norm of a complex number is provided by std::abs, which is more costly + to compute. In some situations, it may be replaced by std::norm, for example, if + abs(z1) > abs(z2) then norm(z1) > norm(z2). + + The additional overloads are not required to be provided exactly as (A,B). They only + need to be sufficient to ensure that for their argument num: + + * If num has a + standard + (until C++23) floating-point type T, then std::norm(num) has the same effect as + std::norm(std::complex(num)). + * Otherwise, if num has an integer type, then std::norm(num) has the same effect + as std::norm(std::complex(num)). + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + constexpr std::complex z {3.0, 4.0}; + static_assert(std::norm(z) == (z.real() * z.real() + z.imag() * z.imag())); + static_assert(std::norm(z) == (z * std::conj(z))); + assert(std::norm(z) == (std::abs(z) * std::abs(z))); + std::cout << "std::norm(" << z << ") = " << std::norm(z) << '\\n'; + } + +.SH Output: + + std::norm((3,4)) = 25 .SH See also abs(std::complex) returns the magnitude of a complex number - \fI(function template)\fP + \fI(function template)\fP conj returns the complex conjugate - \fI(function template)\fP + \fI(function template)\fP polar constructs a complex number from magnitude and phase angle - \fI(function template)\fP + \fI(function template)\fP diff --git a/man/std::normal_distribution.3 b/man/std::normal_distribution.3 index 7f49e6adb..38c771bcc 100644 --- a/man/std::normal_distribution.3 +++ b/man/std::normal_distribution.3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution \- std::normal_distribution + .SH Synopsis Defined in header template< class RealType = double > \fI(since C++11)\fP @@ -7,7 +10,8 @@ Generates random numbers according to the Normal (or Gaussian) random number distribution. It is defined as: - f(x; μ,σ) = + \\(\\small{f(x;\\mu,\\sigma)}=\\frac{1}{\\sigma\\sqrt{2\\pi} + }\\exp{(-\\frac{1}{2}{(\\frac{x-\\mu}{\\sigma})}^2)}\\)f(x; μ,σ) = 1 σ @@ -16,9 +20,9 @@ exp⎛ ⎜ - ⎝- + ⎝ - 1 + -1 2 ⎛ @@ -35,71 +39,85 @@ ⎟ ⎠ - Here μ is the mean and σ is the standard deviation (stddev). + Here \\(\\small\\mu\\)μ is the Mean and \\(\\small\\sigma\\)σ is the Standard deviation + (stddev). + + std::normal_distribution satisfies all requirements of RandomNumberDistribution. + +.SH Template parameters + + RealType - The result type generated by the generator. The effect is undefined if + this is not one of float, double, or long double. .SH Member types - Member type Definition - result_type RealType - param_type the type of the parameter set, unspecified + Member type Definition + result_type \fI(C++11)\fP RealType + param_type \fI(C++11)\fP the type of the parameter set, see RandomNumberDistribution. .SH Member functions constructor constructs new distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP reset resets the internal state of the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Generation operator() generates the next random number in the distribution - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Characteristics mean returns the distribution parameters - stddev \fI(public member function)\fP + stddev \fI(public member function)\fP + \fI(C++11)\fP param gets or sets the distribution parameter object - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP min returns the minimum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP max returns the maximum potentially generated value - \fI(public member function)\fP + \fI(C++11)\fP \fI(public member function)\fP .SH Non-member functions - operator== compares two distribution objects - operator!= \fI(function)\fP - operator<< performs stream input and output on pseudo-random number distribution - operator>> \fI(function)\fP + operator== + operator!= compares two distribution objects + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP(removed in C++20) + operator<< performs stream input and output on pseudo-random number + operator>> distribution + \fI(C++11)\fP \fI(function template)\fP .SH Example - + // Run this code - #include + #include #include - #include + #include #include #include - #include + #include + int main() { - std::random_device rd; - std::mt19937 gen(rd()); - + std::random_device rd{}; + std::mt19937 gen{rd()}; + // values near the mean are the most likely // standard deviation affects the dispersion of generated values from the mean - std::normal_distribution<> d(5,2); - - std::map hist; - for(int n=0; n<10000; ++n) { - ++hist[std::round(d(gen))]; - } - for(auto p : hist) { - std::cout << std::fixed << std::setprecision(1) << std::setw(2) - << p.first << ' ' << std::string(p.second/200, '*') << '\\n'; - } + std::normal_distribution d{5.0, 2.0}; + + // draw a sample from the normal distribution and round it to an integer + auto random_int = [&d, &gen]{ return std::round(d(gen)); }; + + std::map hist{}; + for (int n = 0; n != 10000; ++n) + ++hist[random_int()]; + + for (auto [x, y] : hist) + std::cout << std::setw(2) << x << ' ' << std::string(y / 200, '*') << '\\n'; } -.SH Output: +.SH Possible output: -2 -1 @@ -119,6 +137,6 @@ .SH External links - * Weisstein, Eric W. "Normal Distribution." From MathWorld--A Wolfram Web + 1. Weisstein, Eric W. "Normal Distribution." From MathWorld — A Wolfram Web Resource. - * Normal Distribution. From Wikipedia. + 2. Normal distribution — From Wikipedia. diff --git a/man/std::normal_distribution::max.3 b/man/std::normal_distribution::max.3 index 3ddb824b9..c99d49640 100644 --- a/man/std::normal_distribution::max.3 +++ b/man/std::normal_distribution::max.3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::max \- std::normal_distribution::max + .SH Synopsis result_type max() const; \fI(since C++11)\fP @@ -18,5 +21,5 @@ .SH See also - min returns the minimum potentially generated value - \fI(public member function)\fP + min returns the minimum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::normal_distribution::mean,stddev.3 b/man/std::normal_distribution::mean,stddev.3 index 331fe3251..22898c7fb 100644 --- a/man/std::normal_distribution::mean,stddev.3 +++ b/man/std::normal_distribution::mean,stddev.3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution::mean,stddev 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::mean,stddev 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::mean,stddev \- std::normal_distribution::mean,stddev + .SH Synopsis RealType mean() const; \fB(1)\fP \fI(since C++11)\fP RealType stddev() const; \fB(2)\fP \fI(since C++11)\fP @@ -20,5 +23,5 @@ .SH See also - param gets or sets the distribution parameter object - \fI(public member function)\fP + param gets or sets the distribution parameter object + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::normal_distribution::min.3 b/man/std::normal_distribution::min.3 index 57df372a0..234d8415a 100644 --- a/man/std::normal_distribution::min.3 +++ b/man/std::normal_distribution::min.3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::min \- std::normal_distribution::min + .SH Synopsis result_type min() const; \fI(since C++11)\fP @@ -10,7 +13,7 @@ .SH Return value - The minimum value potentially generated by the distribution + The minimum value potentially generated by the distribution. .SH Complexity @@ -18,5 +21,5 @@ .SH See also - max returns the maximum potentially generated value - \fI(public member function)\fP + max returns the maximum potentially generated value + \fI(C++11)\fP \fI(public member function)\fP diff --git a/man/std::normal_distribution::normal_distribution.3 b/man/std::normal_distribution::normal_distribution.3 index f29b8ebbd..417030c9a 100644 --- a/man/std::normal_distribution::normal_distribution.3 +++ b/man/std::normal_distribution::normal_distribution.3 @@ -1,15 +1,30 @@ -.TH std::normal_distribution::normal_distribution 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::normal_distribution 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::normal_distribution \- std::normal_distribution::normal_distribution + .SH Synopsis - explicit normal_distribution( RealType mean = 0.0, RealType stddev \fB(1)\fP \fI(since C++11)\fP - = 1.0 ); - explicit normal_distribution( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP + normal_distribution() : normal_distribution(0.0) {} \fB(1)\fP \fI(since C++11)\fP + explicit normal_distribution( RealType mean, RealType stddev = 1.0 \fB(2)\fP \fI(since C++11)\fP + ); + explicit normal_distribution( const param_type& params ); \fB(3)\fP \fI(since C++11)\fP + + Constructs a new distribution object. + + 2) Uses mean and stddev as the distribution parameters. + 3) Uses params as the distribution parameters. - Constructs a new distribution object. The first version uses mean and stddev as the - distribution parameters, the second version uses params as the distribution - parameters. + The behavior is undefined if stddev is not greater than zero. .SH Parameters mean - the μ distribution parameter (mean) stddev - the σ distribution parameter (standard deviation) params - the distribution parameter set + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 default constructor was explicit made implicit diff --git a/man/std::normal_distribution::operator().3 b/man/std::normal_distribution::operator().3 index 5bf1b7469..4ff054396 100644 --- a/man/std::normal_distribution::operator().3 +++ b/man/std::normal_distribution::operator().3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::operator() \- std::normal_distribution::operator() + .SH Synopsis template< class Generator > \fB(1)\fP \fI(since C++11)\fP result_type operator()( Generator& g ); @@ -11,13 +14,13 @@ The first version uses the associated parameter set, the second version uses params. The associated parameter set is not modified. - This section is incomplete - Reason: requirements on Generator - .SH Parameters - g - an uniform random number generator object - params - distribution parameter set to use instead of the associated one + g - a uniform random bit generator object + params - distribution parameter set to use instead of the associated one +.SH Type requirements + - + Generator must meet the requirements of UniformRandomBitGenerator. .SH Return value @@ -26,7 +29,3 @@ .SH Complexity Amortized constant number of invocations of g.operator(). - -.SH Category: - - * Todo with reason diff --git a/man/std::normal_distribution::param.3 b/man/std::normal_distribution::param.3 index cb834aedf..76d658c1b 100644 --- a/man/std::normal_distribution::param.3 +++ b/man/std::normal_distribution::param.3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution::param 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::param 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::param \- std::normal_distribution::param + .SH Synopsis param_type param() const; \fB(1)\fP \fI(since C++11)\fP void param( const param_type& params ); \fB(2)\fP \fI(since C++11)\fP @@ -6,8 +9,7 @@ Manages the associated distribution parameter set. 1) Returns the associated parameter set. - - 2) Sets the associated parameter set to params + 2) Sets the associated parameter set to params. .SH Parameters @@ -15,8 +17,7 @@ .SH Return value - 1) The associated parameter set - + 1) The associated parameter set. 2) \fI(none)\fP .SH Complexity diff --git a/man/std::normal_distribution::reset.3 b/man/std::normal_distribution::reset.3 index 0e87aaa2b..5dde7c095 100644 --- a/man/std::normal_distribution::reset.3 +++ b/man/std::normal_distribution::reset.3 @@ -1,4 +1,7 @@ -.TH std::normal_distribution::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::normal_distribution::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::normal_distribution::reset \- std::normal_distribution::reset + .SH Synopsis void reset(); \fI(since C++11)\fP diff --git a/man/std::nostopstate.3 b/man/std::nostopstate.3 new file mode 100644 index 000000000..828e06c34 --- /dev/null +++ b/man/std::nostopstate.3 @@ -0,0 +1,10 @@ +.TH std::nostopstate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nostopstate \- std::nostopstate + +.SH Synopsis + Defined in header + inline constexpr std::nostopstate_t nostopstate{}; \fI(since C++20)\fP + + This is a constant object instance of std::nostopstate_t for use in constructing an + empty std::stop_source, as a placeholder value in the non-default constructor. diff --git a/man/std::nostopstate_t.3 b/man/std::nostopstate_t.3 new file mode 100644 index 000000000..10c49ed36 --- /dev/null +++ b/man/std::nostopstate_t.3 @@ -0,0 +1,15 @@ +.TH std::nostopstate_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nostopstate_t \- std::nostopstate_t + +.SH Synopsis + Defined in header + struct nostopstate_t { + + explicit nostopstate_t() = default; \fI(since C++20)\fP + + }; + + Unit type intended for use as a placeholder in std::stop_source non-default + constructor, that makes the constructed std::stop_source empty with no associated + stop-state. diff --git a/man/std::not1.3 b/man/std::not1.3 index fd68821f0..118556483 100644 --- a/man/std::not1.3 +++ b/man/std::not1.3 @@ -1,14 +1,18 @@ -.TH std::not1 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::not1 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::not1 \- std::not1 + .SH Synopsis Defined in header - template< class Predicate > \fI(until C++14)\fP - std::unary_negate not1(const Predicate& pred); - template< class Predicate > \fI(since C++14)\fP - constexpr std::unary_negate not1(const Predicate& pred); + template< class Predicate > \fI(until C++14)\fP + std::unary_negate not1( const Predicate& pred ); + template< class Predicate > \fI(since C++14)\fP + constexpr std::unary_negate not1( const Predicate& (deprecated in C++17) + pred ); (removed in C++20) - not1 is a helper function to create a function object that returns the complement of - the unary predicate function passed. The function object created is of type - std::unary_negate. + std::not1 is a helper function to create a function object that returns the + complement of the unary predicate function passed. The function object created is of + type std::unary_negate. The unary predicate type must define a member type, argument_type, that is convertible to the predicate's parameter type. The unary function objects obtained @@ -27,53 +31,62 @@ .SH Exceptions - None. + \fI(none)\fP .SH Example - + // Run this code #include #include #include + #include + #include #include - + struct LessThan7 : std::unary_function { bool operator()(int i) const { return i < 7; } }; - + int main() { - std::vector v; - for (int i = 0; i < 10; ++i) { - v.push_back(i); - } - - std::cout << std::count_if(v.begin(), v.end(), std::not1(LessThan7())) << "\\n"; - - //same as above, but use a lambda function - std::function less_than_9 = [](int x){ return x < 9; }; - std::cout << std::count_if(v.begin(), v.end(), std::not1(less_than_9)) << "\\n"; + std::vector v(10); + std::iota(std::begin(v), std::end(v), 0); + + std::cout << std::count_if(begin(v), end(v), std::not1(LessThan7())) << '\\n'; + + // the same as above using std::function + std::function less_than_9 = [](int x) { return x < 9; }; + std::cout << std::count_if(begin(v), end(v), std::not1(less_than_9)) << '\\n'; } .SH Output: 3 + 1 .SH See also - wrapper function object returning the complement of the unary - unary_negate predicate it holds - \fI(class template)\fP - function wraps callable object of any type with specified function call - \fI(C++11)\fP signature - \fI(class template)\fP - not2 constructs custom std::binary_negate object - \fI(function template)\fP - ptr_fun creates an adaptor-compatible function object wrapper from a pointer - \fB(deprecated)\fP to function - \fI(function template)\fP - unary_function adaptor-compatible unary function base class - \fB(deprecated)\fP \fI(class template)\fP + not_fn creates a function object that returns the complement of the + \fI(C++17)\fP result of the function object it holds + \fI(function template)\fP + unary_negate wrapper function object returning the complement of the unary + (deprecated in C++17) predicate it holds + (removed in C++20) \fI(class template)\fP + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + not2 constructs custom std::binary_negate object + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) + ptr_fun creates an adaptor-compatible function object wrapper from a + (deprecated in C++11) pointer to function + (removed in C++17) \fI(function template)\fP + unary_function adaptor-compatible unary function base class + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) diff --git a/man/std::not2.3 b/man/std::not2.3 index 44942afea..ea3cb2937 100644 --- a/man/std::not2.3 +++ b/man/std::not2.3 @@ -1,14 +1,18 @@ -.TH std::not2 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::not2 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::not2 \- std::not2 + .SH Synopsis Defined in header - template< class Predicate > \fI(until C++14)\fP - std::binary_negate not2(const Predicate& pred); - template< class Predicate > \fI(since C++14)\fP - constexpr std::binary_negate not2(const Predicate& pred); + template< class Predicate > \fI(until C++14)\fP + std::binary_negate not2( const Predicate& pred ); + template< class Predicate > \fI(since C++14)\fP + constexpr std::binary_negate not2( const (deprecated in C++17) + Predicate& pred ); (removed in C++20) - not2 is a helper function to create a function object that returns the complement of - the binary predicate function passed. The function object created is of type - std::binary_negate. + std::not2 is a helper function to create a function object that returns the + complement of the binary predicate function passed. The function object created is + of type std::binary_negate. The binary predicate type must define two member types, first_argument_type and second_argument_type, that are convertible to the predicate's parameter types. The @@ -31,69 +35,68 @@ .SH Exceptions - None. + \fI(none)\fP .SH Example - + // Run this code #include + #include #include #include #include - + struct old_same : std::binary_function { bool operator()(int a, int b) const { return a == b; } }; - + struct new_same { bool operator()(int a, int b) const { return a == b; } }; - + bool same_fn(int a, int b) { return a == b; } - - + int main() { std::vector v1{0, 1, 2}; std::vector v2{2, 1, 0}; std::vector v3(v1.size()); - + std::cout << "negating a binary_function:\\n"; std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), std::not2(old_same())); - + std::cout << std::boolalpha; for (std::size_t i = 0; i < v1.size(); ++i) std::cout << v1[i] << ' ' << v2[i] << ' ' << v3[i] << '\\n'; - + std::cout << "negating a standard functor:\\n"; std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), std::not2(std::equal_to())); - + for (std::size_t i = 0; i < v1.size(); ++i) std::cout << v1[i] << ' ' << v2[i] << ' ' << v3[i] << '\\n'; - + std::cout << "negating a std::function:\\n"; std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), - std::not2(std::function(new_same()))); - + std::not2(std::function(new_same()))); + for (std::size_t i = 0; i < v1.size(); ++i) std::cout << v1[i] << ' ' << v2[i] << ' ' << v3[i] << '\\n'; - + std::cout << "negating a std::reference_wrapper:\\n"; std::transform(v1.begin(), v1.end(), v2.begin(), v3.begin(), std::not2(std::ref(same_fn))); - + for (std::size_t i = 0; i < v1.size(); ++i) std::cout << v1[i] << ' ' << v2[i] << ' ' << v3[i] << '\\n'; - } .SH Output: @@ -117,16 +120,24 @@ .SH See also - wrapper function object returning the complement of the binary - binary_negate predicate it holds - \fI(class template)\fP - function wraps callable object of any type with specified function call - \fI(C++11)\fP signature - \fI(class template)\fP - not1 constructs custom std::unary_negate object - \fI(function template)\fP - ptr_fun creates an adaptor-compatible function object wrapper from a pointer - \fB(deprecated)\fP to function - \fI(function template)\fP - binary_function adaptor-compatible binary function base class - \fB(deprecated)\fP \fI(class template)\fP + not_fn creates a function object that returns the complement of the + \fI(C++17)\fP result of the function object it holds + \fI(function template)\fP + binary_negate wrapper function object returning the complement of the binary + (deprecated in C++17) predicate it holds + (removed in C++20) \fI(class template)\fP + function wraps callable object of any copy constructible type with + \fI(C++11)\fP specified function call signature + \fI(class template)\fP + move_only_function wraps callable object of any type with specified function call + (C++23) signature + \fI(class template)\fP + not1 constructs custom std::unary_negate object + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) + ptr_fun creates an adaptor-compatible function object wrapper from a + (deprecated in C++11) pointer to function + (removed in C++17) \fI(function template)\fP + binary_function adaptor-compatible binary function base class + (deprecated in C++11) \fI(class template)\fP + (removed in C++17) diff --git a/man/std::not_equal_to.3 b/man/std::not_equal_to.3 index 15033d3ce..08b9d2545 100644 --- a/man/std::not_equal_to.3 +++ b/man/std::not_equal_to.3 @@ -1,4 +1,7 @@ -.TH std::not_equal_to 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::not_equal_to 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::not_equal_to \- std::not_equal_to + .SH Synopsis Defined in header template< class T > \fI(until C++14)\fP @@ -15,23 +18,26 @@ when T is not specified, which leaves the parameter types and return type to be deduced. \fI(since C++14)\fP - function object implementing x != y deducing - not_equal_to argument and return types - \fI(class template specialization)\fP + not_equal_to function object implementing x != y deducing + \fI(C++14)\fP parameter and return types + \fI(class template specialization)\fP .SH Member types - type definition - result_type bool - first_argument_type T - second_argument_type T + Type Definition + result_type (deprecated in C++17)(removed in C++20) bool + first_argument_type (deprecated in C++17)(removed in C++20) T + second_argument_type (deprecated in C++17)(removed in C++20) T + + These member types are obtained via publicly inheriting \fI(until C++11)\fP + std::binary_function. .SH Member functions operator() checks if the arguments are not equal \fI(public member function)\fP - std::not_equal_to::operator() +std::not_equal_to::operator() bool operator()( const T& lhs, const T& rhs ) const; \fI(until C++14)\fP constexpr bool operator()( const T& lhs, const T& rhs ) const; \fI(since C++14)\fP @@ -48,11 +54,20 @@ .SH Exceptions - \fI(none)\fP + May throw implementation-defined exceptions. .SH Possible implementation - constexpr bool operator()(const T &lhs, const T &rhs) const + constexpr bool operator()(const T& lhs, const T& rhs) const { return lhs != rhs; } + +.SH See also + + equal determines if two sets of elements are the same + \fI(function template)\fP + less function object implementing x < y + \fI(class template)\fP + ranges::not_equal_to constrained function object implementing x != y + (C++20) \fI(class)\fP diff --git a/man/std::not_equal_to.3 b/man/std::not_equal_to.3 deleted file mode 100644 index a2d272ab4..000000000 --- a/man/std::not_equal_to.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH std::not_equal_to 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - template<> \fI(since C++14)\fP - class not_equal_to; - - std::not_equal_to<> is a specialization of std::not_equal_to with parameter and - return type deduced. - -.SH Member types - - Member type Definition - is_transparent /* unspecified */ - -.SH Member functions - - operator() tests if the two arguments do not compare equal - \fI(public member function)\fP - - std::not_equal_to<>::operator() - - template< class T, class U> - - constexpr auto operator()( T&& lhs, U&& rhs ) const - - -> decltype(std::forward(lhs) != std::forward(rhs)); - - Returns the result of non-equality comparison between lhs and rhs. - -.SH Parameters - - lhs, rhs - values to compare - -.SH Return value - - The result of lhs != rhs. - -.SH Notes - - The member type is_transparent indicates to the caller that this function object is - a transparent function object: it accepts arguments of arbitrary types and uses - perfect forwarding, which avoids unnecessary copying and conversion when the - function object is used in heterogeneous context, or with rvalue arguments. In - particular, template functions such as std::set::find and std::set::lower_bound make - use of this member type on their Compare types. - -.SH Example - - This section is incomplete - Reason: no example - -.SH Category: - - * Todo no example diff --git a/man/std::not_fn.3 b/man/std::not_fn.3 new file mode 100644 index 000000000..3481fa780 --- /dev/null +++ b/man/std::not_fn.3 @@ -0,0 +1,324 @@ +.TH std::not_fn 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::not_fn \- std::not_fn + +.SH Synopsis + Defined in header + template< class F > \fB(1)\fP \fI(since C++17)\fP + /* unspecified */ not_fn( F&& f ); (constexpr since C++20) + template< auto ConstFn > \fB(2)\fP (since C++26) + constexpr /* unspecified */ not_fn() noexcept; + + 1) Creates a forwarding call wrapper that returns the negation of the callable + object it holds. + 2) Creates a forwarding call wrapper that returns the negation of the statically + determined callable target. The program is ill-formed if ConstFn is a null pointer + or null pointer-to-member. + +.SH Parameters + + f - the object from which the Callable object held by the wrapper is + constructed +.SH Type requirements + - + std::decay_t must meet the requirements of Callable and MoveConstructible. + - + std::is_constructible_v, F> is required to be true. + +.SH Return value + + 1) A function object of unspecified type T. It has the following members. + +std::not_fn return type + +.SH Member objects + + The return type of std::not_fn holds a member object of type std::decay_t. + + Constructors + + \fI(since C++17)\fP + explicit T( F&& f ); \fB(1)\fP (constexpr since C++20) + (exposition only*) + T( T&& f ) = default; \fB(2)\fP \fI(since C++17)\fP + T( const T& f ) = default; + + 1) The constructor direct-non-list-initializes the member object (of type + std::decay_t) from std::forward(f). Throws any exception thrown by the + constructor selected. + 2) Because std::decay_t is required to be MoveConstructible, the returned call + wrapper is always MoveConstructible, and is CopyConstructible if std::decay_t is + CopyConstructible. + + The explicitly defaulted definitions make the return type not \fI(until C++20)\fP + assignable. + It is unspecified whether these constructors are explicitly defaulted \fI(since C++20)\fP + and whether the return type is assignable. + +.SH Member function operator() + + template< class... Args > + + auto operator()( Args&&... args ) & + -> decltype(!std::declval< (since + std::invoke_result_t&, Args...>>()); C++17) + template< class... Args > (until + auto operator()( Args&&... args ) const& C++20) + -> decltype(!std::declval< + + std::invoke_result_t const&, + Args...>>()); + template< class... Args > + + constexpr auto operator()( Args&&... args ) & + noexcept(/* see below */) + -> decltype(!std::invoke( + std::declval&>(), + std::declval()...)); (since + template< class... Args > C++20) + constexpr auto operator()( Args&&... args ) const& + noexcept(/* see below */) + -> decltype(!std::invoke( + + std::declval const&>(), + std::declval()...)); \fB(1)\fP + template< class... Args > + + auto operator()( Args&&... args ) && + -> decltype(!std::declval< (since + std::invoke_result_t, Args...>>()); C++17) + template< class... Args > (until + auto operator()( Args&&... args ) const&& C++20) + -> decltype(!std::declval< + + std::invoke_result_t const, + Args...>>()); + template< class... Args > + \fB(2)\fP + constexpr auto operator()( Args&&... args ) && + noexcept(/* see below */) + -> decltype(!std::invoke( + std::declval>(), + std::declval()...)); (since + template< class... Args > C++20) + constexpr auto operator()( Args&&... args ) const&& + noexcept(/* see below */) + -> decltype(!std::invoke( + + std::declval const>(), + std::declval()...)); + + Let fd be the member object of type std::decay_t. + + 1) Equivalent to return !std::invoke(fd, std::forward(args)...); + 2) Equivalent to return !std::invoke(std::move(fd), + std::forward(args)...); \fI(since C++17)\fP + \fI(until C++20)\fP + While invoking the result, if the substitution into the return type of + the originally selected operator() overload fails, another overload + may be selected. + 1) Expression-equivalent to !std::invoke(fd, + std::forward(args)...) + 2) Expression-equivalent to !std::invoke(std::move(fd), + std::forward(args)...) \fI(since C++20)\fP + + While invoking the result, if the substitution into the return type of + the originally selected operator() overload fails, the invocation is + ill-formed, which can also be a substitution failure. + + 2) A value of the following type. + +std::not_fn stateless return type + + The return type is a CopyConstructible stateless class. It is unspecified whether + the return type is assignable. + +.SH Member function operator() + + template< class... Args > + + constexpr auto operator()( Args&&... args ) const (since C++26) + noexcept(/* see below */) + + -> decltype(!std::invoke(ConstFn, std::declval()...)); + + Expression-equivalent to !std::invoke(ConstFn, std::forward(args)...). + +.SH Exceptions + + 1) Throws no exceptions, unless the construction of fd throws. + +.SH Possible implementation + + \fB(1)\fP not_fn + namespace detail + { + template + constexpr bool negate_invocable_impl = false; + template + constexpr bool negate_invocable_impl(), std::declval()...))>, F, Args...> = true; + + template + constexpr bool negate_invocable_v = negate_invocable_impl; + + template + struct not_fn_t + { + F f; + + template, int> = 0> + constexpr decltype(auto) operator()(Args&&... args) & + noexcept(noexcept(!std::invoke(f, std::forward(args)...))) + { + return !std::invoke(f, std::forward(args)...); + } + + template, int> = 0> + constexpr decltype(auto) operator()(Args&&... args) const& + noexcept(noexcept(!std::invoke(f, std::forward(args)...))) + { + return !std::invoke(f, std::forward(args)...); + } + + template, int> = 0> + constexpr decltype(auto) operator()(Args&&... args) && + noexcept(noexcept(!std::invoke(std::move(f), std::forward(args)...))) + { + return !std::invoke(std::move(f), std::forward(args)...); + } + + template, int> = 0> + constexpr decltype(auto) operator()(Args&&... args) const&& + noexcept(noexcept(!std::invoke(std::move(f), std::forward(args)...))) + { + return !std::invoke(std::move(f), std::forward(args)...); + } + + // Deleted overloads are needed since C++20 + // for preventing a non-equivalent but well-formed overload to be selected. + + template, int> = 0> + void operator()(Args&&...) & = delete; + + template, int> = 0> + void operator()(Args&&...) const& = delete; + + template, int> = 0> + void operator()(Args&&...) && = delete; + + template, int> = 0> + void operator()(Args&&...) const&& = delete; + }; + } + + template + constexpr detail::not_fn_t> not_fn(F&& f) + { + return {std::forward(f)}; + } + \fB(2)\fP not_fn + namespace detail + { + template + struct stateless_not_fn + { + template + constexpr auto operator()(Args&&... args) const + noexcept(noexcept(!std::invoke(ConstFn, std::forward(args)...))) + -> decltype(!std::invoke(ConstFn, std::forward(args)...)) + { + return !std::invoke(ConstFn, std::forward(args)...); + } + }; + } + + template + constexpr detail::stateless_not_fn not_fn() noexcept + { + if constexpr (std::is_pointer_v || + std::is_member_pointer_v) + static_assert(ConstFn != nullptr); + + return {}; + } + +.SH Notes + + std::not_fn is intended to replace the C++03-era negators std::not1 and std::not2. + + Feature-test macro Value Std Feature + 201603L \fI(C++17)\fP std::not_fn(), \fB(1)\fP + __cpp_lib_not_fn 202306L (C++26) Allow passing callable objects as non-type + template arguments to std::not_fn, \fB(2)\fP + +.SH Example + + +// Run this code + + #include + #include + + bool is_same(int a, int b) noexcept + { + return a == b; + } + + struct S + { + int val; + bool is_same(int arg) const noexcept { return val == arg; } + }; + + int main() + { + // Using with a free function: + auto is_differ = std::not_fn(is_same); + assert(is_differ(8, 8) == false); // equivalent to: !is_same(8, 8) == false + assert(is_differ(6, 9) == true); // equivalent to: !is_same(8, 0) == true + + // Using with a member function: + auto member_differ = std::not_fn(&S::is_same); + assert(member_differ(S{3}, 3) == false); //: S tmp{6}; !tmp.is_same(6) == false + + // Noexcept-specification is preserved: + static_assert(noexcept(is_differ) == noexcept(is_same)); + static_assert(noexcept(member_differ) == noexcept(&S::is_same)); + + // Using with a function object: + auto same = [](int a, int b) { return a == b; }; + auto differ = std::not_fn(same); + assert(differ(1, 2) == true); //: !same(1, 2) == true + assert(differ(2, 2) == false); //: !same(2, 2) == false + + #if __cpp_lib_not_fn >= 202306L + auto is_differ_cpp26 = std::not_fn(); + assert(is_differ_cpp26(8, 8) == false); + assert(is_differ_cpp26(6, 9) == true); + + auto member_differ_cpp26 = std::not_fn<&S::is_same>(); + assert(member_differ_cpp26(S{3}, 3) == false); + + auto differ_cpp26 = std::not_fn(); + static_assert(differ_cpp26(1, 2) == true); + static_assert(differ_cpp26(2, 2) == false); + #endif + } + +.SH See also + + not1 constructs custom std::unary_negate object + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) + not2 constructs custom std::binary_negate object + (deprecated in C++17) \fI(function template)\fP + (removed in C++20) diff --git a/man/std::nothrow.3 b/man/std::nothrow.3 index 9ab17839d..672ba3f10 100644 --- a/man/std::nothrow.3 +++ b/man/std::nothrow.3 @@ -1,32 +1,43 @@ -.TH std::nothrow 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nothrow 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nothrow \- std::nothrow + .SH Synopsis Defined in header - extern const std::nothrow_t nothrow; + struct nothrow_t {}; \fI(until C++11)\fP + struct nothrow_t { explicit nothrow_t() = default; }; \fB(1)\fP \fI(since C++11)\fP + extern const std::nothrow_t nothrow; \fB(2)\fP - std::nothrow is a constant of type std::nothrow_t used to disambiguate the overloads - of throwing and non-throwing allocation functions. + std::nothrow_t is an empty class type used to disambiguate the overloads of throwing + and non-throwing allocation functions. std::nothrow is a constant of it. .SH Example - + // Run this code #include #include - + int main() { - try { - while (true) { + try + { + while (true) + { new int[100000000ul]; // throwing overload } - } catch (const std::bad_alloc& e) { + } + catch (const std::bad_alloc& e) + { std::cout << e.what() << '\\n'; } - - while (true) { + + while (true) + { int* p = new(std::nothrow) int[100000000ul]; // non-throwing overload - if (p == nullptr) { + if (p == nullptr) + { std::cout << "Allocation returned nullptr\\n"; break; } @@ -38,9 +49,16 @@ std::bad_alloc Allocation returned nullptr + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2510 C++11 the default constructor was non-explicit, which made explicit + could lead to ambiguity + .SH See also - nothrow_t tag type used to select an non-throwing allocation function - \fI(class)\fP operator new allocation functions - operator new[] \fI(function)\fP + operator new[] \fI(function)\fP diff --git a/man/std::nothrow_t.3 b/man/std::nothrow_t.3 deleted file mode 100644 index d4859ae37..000000000 --- a/man/std::nothrow_t.3 +++ /dev/null @@ -1,15 +0,0 @@ -.TH std::nothrow_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - struct nothrow_t {}; - - std::nothrow_t is an empty class type used to disambiguate the overloads of throwing - and non-throwing allocation functions. - -.SH See also - - an object of type nothrow_t used to select an non-throwing allocation - nothrow function - (constant) - operator new allocation functions - operator new[] \fI(function)\fP diff --git a/man/std::notify_all_at_thread_exit.3 b/man/std::notify_all_at_thread_exit.3 index 75946d293..469a35f23 100644 --- a/man/std::notify_all_at_thread_exit.3 +++ b/man/std::notify_all_at_thread_exit.3 @@ -1,4 +1,7 @@ -.TH std::notify_all_at_thread_exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::notify_all_at_thread_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::notify_all_at_thread_exit \- std::notify_all_at_thread_exit + .SH Synopsis Defined in header void notify_all_at_thread_exit( std::condition_variable& cond, \fI(since C++11)\fP @@ -9,30 +12,31 @@ operates as follows: * Ownership of the previously acquired lock lk is transferred to internal storage. - * The execution environment is modified such that when the current thread exits, - after the destructors for all objects with thread local storage duration are - called, the condition variable cond is notified as if by: + the condition variable cond is notified as if by lk.unlock(); + cond.notify_all();. - lk.unlock(); - cond.notify_all(); + The implied lk.unlock() is sequenced after the destruction of all objects with + thread local storage duration associated with the current thread. - An equivalent effect may be achieved with the facilities provided by std::promise or - std::packaged_task. + If any of the following conditions is satisfied, the behavior is undefined: -.SH Notes + * lk is not locked by the calling thread. + * If some other threads are also waiting on cond, lk.mutex() is different from the + mutex unlocked by the waiting functions (wait, wait_for and wait_until) called + on cond by those threads. - Calling this function if lock.mutex() is not locked by the current thread is - undefined behavior. +.SH Notes - Calling this function if lock.mutex() is not the same mutex as the one used by all - other threads that are currently waiting on the same condition variable is undefined - behavior. + An equivalent effect may be achieved with the facilities provided by std::promise or + std::packaged_task. The supplied lock lk is held until the thread exits. Once this function has been called, no more threads may acquire the same lock in order to wait on cond. If some - thread is waiting on this condition variable, it should not attempt to release and - reacquire the lock when it wakes up spuriously. + threads are waiting on this condition variable, ensure that the condition being + waited for is satisfied while holding the lock on lk, and that this lock is not + released and reacquired prior to calling notify_all_at_thread_exit to avoid + confusion from spurious wakeups in other threads. In typical use cases, this function is the last thing called by a detached thread. @@ -51,49 +55,69 @@ avoid accessing data that depends on thread locals while those thread locals are in the process of being destructed: - + // Run this code + #include + #include #include + #include #include - #include - + std::mutex m; std::condition_variable cv; - + bool ready = false; - ComplexType result; // some arbitrary type - + std::string result; // some arbitrary type + void thread_func() { + thread_local std::string thread_local_data = "42"; + std::unique_lock lk(m); + // assign a value to result using thread_local data - result = function_that_uses_thread_locals(); + result = thread_local_data; ready = true; + std::notify_all_at_thread_exit(cv, std::move(lk)); - } // 1. destroy thread_locals, 2. unlock mutex, 3. notify cv - + + } // 1. destroy thread_locals; + // 2. unlock mutex; + // 3. notify cv. + int main() { std::thread t(thread_func); t.detach(); - + // do other work // ... - + // wait for the detached thread std::unique_lock lk(m); - while(!ready) { - cv.wait(lk); - } - process(result); // result is ready and thread_local destructors have finished + cv.wait(lk, []{ return ready; }); + + // result is ready and thread_local destructors have finished, no UB + assert(result == "42"); } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the call to notify_all_at_thread_exit updated the + LWG 2140 C++11 synchronized with calls to functions waiting synchronization + on cond requirement + .SH See also sets the result to specific value while delivering the set_value_at_thread_exit notification only at thread exit - \fI(public member function of std::promise)\fP + \fI(public member function of std::promise)\fP executes the function ensuring that the result is ready make_ready_at_thread_exit only once the current thread exits - \fI(public member function of std::packaged_task)\fP + \fI(public member function of std::packaged_task)\fP + diff --git a/man/std::nth_element.3 b/man/std::nth_element.3 index 396aff9c1..275f8bd10 100644 --- a/man/std::nth_element.3 +++ b/man/std::nth_element.3 @@ -1,94 +1,211 @@ -.TH std::nth_element 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nth_element 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nth_element \- std::nth_element + .SH Synopsis Defined in header - template< class RandomIt > \fB(1)\fP - void nth_element( RandomIt first, RandomIt nth, RandomIt last ); - template< class RandomIt, class Compare > \fB(2)\fP - void nth_element( RandomIt first, RandomIt nth, RandomIt last, Compare comp ); + template< class RandomIt > + void nth_element( RandomIt first, RandomIt nth, RandomIt \fB(1)\fP (constexpr since C++20) + last ); + template< class ExecutionPolicy, class RandomIt > - nth_element is a partial sorting algorithm that rearranges elements in [first, last) - such that: + void nth_element( ExecutionPolicy&& policy, \fB(2)\fP \fI(since C++17)\fP - * The element pointed at by nth is changed to whatever element would occur in that - position if [first, last) was sorted. - * All of the elements before this new nth element are less than or equal to the - elements after the new nth element. + RandomIt first, RandomIt nth, RandomIt + last ); + template< class RandomIt, class Compare > + + void nth_element( RandomIt first, RandomIt nth, RandomIt \fB(3)\fP (constexpr since C++20) + last, + + Compare comp ); + template< class ExecutionPolicy, class RandomIt, class + Compare > - More formally, nth_element partially sorts the range [first, last) in ascending - order so that the condition !(*j < *i) (for the first version, or comp(*j, *i) == - false for the second version) is met for any i in the range [first, nth) and for any - j in the range [nth, last). The element placed in the nth position is exactly the - element that would occur in this position if the range was fully sorted. + void nth_element( ExecutionPolicy&& policy, \fB(4)\fP \fI(since C++17)\fP + RandomIt first, RandomIt nth, RandomIt + last, + + Compare comp ); + + nth_element rearranges elements in [first, last) such that after the rearrangement: + + * The element pointed at by nth is changed to whatever element would occur in that + position if [first, last) were sorted. + * For every iterator i in [first, nth) and every iterator j in [nth, last), the + following condition is met: + 1,2) + bool(*j < *i) + \fI(until C++20)\fP + std::less{}(*j, *i) + \fI(since C++20)\fP is false. + 3,4) bool(comp(*j, *i)) is false. + + 1) Elements are hypothetically sorted with respect to + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP. + 3) Elements are hypothetically sorted with respect to comp. + 2,4) Same as (1,3), but executed according to policy. + These overloads participate in overload resolution only if + + std::is_execution_policy_v> is true. (until + C++20) + std::is_execution_policy_v> is true. (since + C++20) + + If any of the following conditions is satisfied, the behavior is undefined: + + * [first, nth) or [nth, last) is not a valid range. + + * The type of *first is not Swappable. \fI(until C++11)\fP + * RandomIt is not ValueSwappable. + * The type of *first is not MoveConstructible. \fI(since C++11)\fP + * The type of *first is not MoveAssignable. .SH Parameters - first, last - random access iterators defining the range sort - nth - random access iterator defining the sort partition point - comparison function object (i.e. an object that satisfies the - requirements of Compare) which returns true if the first argument is - less (i.e. is ordered before) the second element. + first, last - random access iterators defining the range sort + nth - random access iterator defining the sort partition point + policy - the execution policy to use. See execution policy for details. + comparison function object (i.e. an object that satisfies the + requirements of Compare) which returns true if the first argument is + less than (i.e. is ordered before) the second. - The signature of the comparison function should be equivalent to the - following: - comp - - bool cmp(const Type1 &a, const Type2 &b); + The signature of the comparison function should be equivalent to the + following: - The signature does not need to have const &, but the function object - must not modify the objects passed to it. - The types Type1 and Type2 must be such that an object of type RandomIt - can be dereferenced and then implicitly converted to both of them. + bool cmp(const Type1& a, const Type2& b); + comp - + While the signature does not need to have const&, the function must + not modify the objects passed to it and must be able to accept all + values of type (possibly const) Type1 and Type2 regardless of value + category (thus, Type1& is not allowed + , nor is Type1 unless for Type1 a move is equivalent to a copy + \fI(since C++11)\fP). + The types Type1 and Type2 must be such that an object of type + RandomIt can be dereferenced and then implicitly converted to both of + them. .SH Type requirements - - RandomIt must meet the requirements of ValueSwappable and RandomAccessIterator. + RandomIt must meet the requirements of LegacyRandomAccessIterator. - - The type of dereferenced RandomIt must meet the requirements of MoveAssignable and - MoveConstructible. + Compare must meet the requirements of Compare. -.SH Return value +.SH Complexity - \fI(none)\fP + Given \\(\\scriptsize N\\)N as last - first: -.SH Complexity + 1) \\(\\scriptsize O(N)\\)O(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP on average. + 2) \\(\\scriptsize O(N)\\)O(N) comparisons using + operator< + \fI(until C++20)\fP + std::less{} + \fI(since C++20)\fP, and \\(\\scriptsize O(N \\cdot \\log(N))\\)O(N·log(N)) swaps. + 3) \\(\\scriptsize O(N)\\)O(N) applications of the comparator comp on average. + 4) \\(\\scriptsize O(N)\\)O(N) applications of the comparator comp, and \\(\\scriptsize + O(N \\cdot \\log(N))\\)O(N·log(N)) swaps. + +.SH Exceptions + + The overloads with a template parameter named ExecutionPolicy report errors as + follows: + + * If execution of a function invoked as part of the algorithm throws an exception + and ExecutionPolicy is one of the standard policies, std::terminate is called. + For any other ExecutionPolicy, the behavior is implementation-defined. + * If the algorithm fails to allocate memory, std::bad_alloc is thrown. - Linear in std::distance(first, last) on average. +.SH Possible implementation + + See also the implementations in libstdc++, libc++, and msvc stl. .SH Notes - The algorithm used is typically introselect although other selection algorithms with + The algorithm used is typically Introselect although other Selection algorithm with suitable average-case complexity are allowed. .SH Example - + // Run this code - #include - #include #include + #include #include - + #include + #include + #include + + void printVec(const std::vector& vec) + { + std::cout << "v = {"; + for (char sep[]{0, ' ', 0}; const int i : vec) + std::cout << sep << i, sep[0] = ','; + std::cout << "};\\n"; + } + int main() { - std::vector v{5, 6, 4, 3, 2, 6, 7, 9, 3}; - - std::nth_element(v.begin(), v.begin() + v.size()/2, v.end()); - std::cout << "The median is " << v[v.size()/2] << '\\n'; - - std::nth_element(v.begin(), v.begin()+1, v.end(), std::greater()); - std::cout << "The second largest element is " << v[1] << '\\n'; + std::vector v{5, 10, 6, 4, 3, 2, 6, 7, 9, 3}; + printVec(v); + + auto m = v.begin() + v.size() / 2; + std::nth_element(v.begin(), m, v.end()); + std::cout << "\\nThe median is " << v[v.size() / 2] << '\\n'; + // The consequence of the inequality of elements before/after the Nth one: + assert(std::accumulate(v.begin(), m, 0) < std::accumulate(m, v.end(), 0)); + printVec(v); + + // Note: comp function changed + std::nth_element(v.begin(), v.begin() + 1, v.end(), std::greater{}); + std::cout << "\\nThe second largest element is " << v[1] << '\\n'; + std::cout << "The largest element is " << v[0] << '\\n'; + printVec(v); } -.SH Output: +.SH Possible output: + + v = {5, 10, 6, 4, 3, 2, 6, 7, 9, 3}; + + The median is 6 + v = {3, 2, 3, 4, 5, 6, 10, 7, 9, 6}; + + The second largest element is 9 + The largest element is 10 + v = {10, 9, 6, 7, 6, 3, 5, 4, 3, 2}; + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. - The median is 5 - The second largest element is 7 + DR Applied to Behavior as published Correct behavior + after the rearrangement, only one + LWG 2150 C++98 element before nth corrected the + was required to be not greater than requirement + one element after nth + P0896R4 C++98 [first, nth) and [nth, last) the behavior is undefined + were not required to be valid ranges if any of them is invalid .SH See also - partial_sort_copy copies and partially sorts a range of elements - \fI(function template)\fP - sorts a range of elements while preserving order between equal - stable_sort elements - \fI(function template)\fP - sort sorts a range into ascending order - \fI(function template)\fP + max_element returns the largest element in a range + \fI(function template)\fP + min_element returns the smallest element in a range + \fI(function template)\fP + partial_sort_copy copies and partially sorts a range of elements + \fI(function template)\fP + sorts a range of elements while preserving order between equal + stable_sort elements + \fI(function template)\fP + sort sorts a range into ascending order + \fI(function template)\fP + ranges::nth_element partially sorts the given range making sure that it is + (C++20) partitioned by the given element + (niebloid) diff --git a/man/std::nullopt.3 b/man/std::nullopt.3 index cc2a3a1bb..9d3d66a52 100644 --- a/man/std::nullopt.3 +++ b/man/std::nullopt.3 @@ -1,7 +1,10 @@ -.TH std::nullopt 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nullopt 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nullopt \- std::nullopt + .SH Synopsis Defined in header - constexpr nullopt_t nullopt{/*unspecified*/}; \fI(since C++14)\fP + inline constexpr nullopt_t nullopt{/*unspecified*/}; \fI(since C++17)\fP std::nullopt is a constant of type std::nullopt_t that is used to indicate optional type with uninitialized state. @@ -9,4 +12,4 @@ .SH See also nullopt_t indicator of optional type with uninitialized state - \fI(C++14)\fP \fI(class)\fP + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::nullopt_t.3 b/man/std::nullopt_t.3 index 911fe42e6..54c56f75f 100644 --- a/man/std::nullopt_t.3 +++ b/man/std::nullopt_t.3 @@ -1,12 +1,33 @@ -.TH std::nullopt_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nullopt_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nullopt_t \- std::nullopt_t + .SH Synopsis Defined in header - struct nullopt_t {}; \fI(since C++14)\fP + struct nullopt_t; \fI(since C++17)\fP std::nullopt_t is an empty class type used to indicate optional type with - uninitialized state. + uninitialized state. In particular, std::optional has a constructor with nullopt_t + as a single argument, which creates an optional that does not contain a value. + + std::nullopt_t must be a non-aggregate LiteralType and cannot have a default + constructor or an initializer-list constructor. + + It must have a constexpr constructor that takes some implementation-defined literal + type. + +.SH Notes + + The constraints on nullopt_t's constructors exist to support both op = {}; and op = + nullopt; as the syntax for disengaging an optional object. + + A possible implementation of this class is + + struct nullopt_t { + constexpr explicit nullopt_t(int) {} + }; .SH See also nullopt an object of type nullopt_t - \fI(C++14)\fP \fI(function)\fP + \fI(C++17)\fP (constant) diff --git a/man/std::nullptr_t.3 b/man/std::nullptr_t.3 index 41fac7f69..f09071aac 100644 --- a/man/std::nullptr_t.3 +++ b/man/std::nullptr_t.3 @@ -1,44 +1,68 @@ -.TH std::nullptr_t 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::nullptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::nullptr_t \- std::nullptr_t + .SH Synopsis Defined in header - typedef decltype(nullptr) nullptr_t; \fI(since C++11)\fP + using nullptr_t = decltype(nullptr); \fI(since C++11)\fP + + std::nullptr_t is the type of the null pointer literal, nullptr. It is a distinct + type that is not itself a pointer type or a pointer to member type. Its values are + null pointer constants (see NULL), and may be implicitly converted to any pointer + and pointer to member type. + + sizeof(std::nullptr_t) is equal to sizeof(void *). + +.SH Notes + + The C++ standard requires to place the contents of in the + global namespace, and thereby requires nullptr_t to be available in the global + namespace when is included. + + nullptr_t is not a part of C until C23. - std::nullptr_t is the type of the null pointer literal, nullptr. + It is unspecified whether the declaration of std::nullptr_t is available in any + other standard library header. An implementation may avoid introducing this name + even when the standard requires std::nullptr_t to be used, by e.g. spelling + decltype(nullptr) instead. .SH Example If two or more overloads accept different pointer types, an overload for std::nullptr_t is necessary to accept a null pointer argument. - + // Run this code #include #include - - void f(int* pi) + + void f(int*) { std::cout << "Pointer to integer overload\\n"; } - - void f(double* pd) + + void f(double*) { std::cout << "Pointer to double overload\\n"; } - - void f(std::nullptr_t nullp) + + void f(std::nullptr_t) { std::cout << "null pointer overload\\n"; } - + int main() { - int* pi; double* pd; - + int* pi{}; + double* pd{}; + f(pi); f(pd); - f(nullptr); // would be ambiguous without void f(nullptr_t) - // f(NULL); // ambiguous overload: all three functions are candidates + f(nullptr); // would be ambiguous without void f(nullptr_t) + // f(0); // ambiguous call: all three functions are candidates + // f(NULL); // ambiguous if NULL is an integral null pointer constant + // (as is the case in most implementations) } .SH Output: @@ -49,6 +73,10 @@ .SH See also - nullptr the pointer literal which specifies a null pointer value \fI(C++11)\fP - NULL implementation-defined null pointer constant - (macro constant) + nullptr\fI(C++11)\fP the pointer literal which specifies a null pointer value + NULL implementation-defined null pointer constant + (macro constant) + is_null_pointer checks if a type is std::nullptr_t + \fI(C++14)\fP \fI(class template)\fP + C documentation for + nullptr_t diff --git a/man/std::num_get.3 b/man/std::num_get.3 index c14f6a9b7..9879861d1 100644 --- a/man/std::num_get.3 +++ b/man/std::num_get.3 @@ -1,4 +1,7 @@ -.TH std::num_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_get \- std::num_get + .SH Synopsis Defined in header template< @@ -10,36 +13,39 @@ Class std::num_get encapsulates the rules for parsing string representations of numeric values. Specifically, types bool, unsigned short, unsigned int, long, - unsigned long, long long, unsigned long long, float, double, long double, and void* - are supported. The standard formatting input operators (such as cin >> n;) use the - std::num_get facet of the I/O stream's locale to parse the text representations of - the numbers. + unsigned long + , long long, unsigned long long + \fI(since C++11)\fP, float, double, long double, and void* are supported. The standard + formatting input operators (such as cin >> n;) use the std::num_get facet of the I/O + stream's locale to parse the text representations of the numbers. std-num get-inheritance.svg - About this image Inheritance diagram -.SH Type requirements - - - - InputIt must meet the requirements of InputIterator. + If a std::num_get specialization is not guaranteed to be provided by the standard + library (see below), the behaviors of its get() and do_get() are not guaranteed as + specified. .SH Specializations - Two standalone (locale-independent) full specializations and two partial - specializations are provided by the standard library: + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header - std::num_get creates narrow string parsing of numbers - std::num_get creates wide string parsing of numbers - std::num_get creates narrow string parsing of numbers using custom - input iterator - std::num_get creates wide string parsing of numbers using custom - input iterator + std::num_get creates narrow string parsing of numbers + std::num_get creates wide string parsing of numbers + + In addition, the standard library is also guaranteed to provide every specialization + that satisfies the following type requirements: - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. + * CharT is one of + * char, + * wchar_t, and + * any other implementation-defined character container type that meets the + requirements for a character on which any of the iostream components can be + instantiated; and + * InputIt must meet the requirements of LegacyInputIterator. .SH Member types @@ -51,8 +57,6 @@ constructor constructs a new num_get facet \fI(public member function)\fP - destructor destructs a num_get facet - \fI(protected member function)\fP get invokes do_get \fI(public member function)\fP @@ -63,47 +67,51 @@ .SH Protected member functions - do_get parses a number from an input stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + destructor destructs a num_get facet + \fI(protected member function)\fP + do_get parses a number from an input stream + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Example - + // Run this code #include + #include #include - #include #include - #include - + #include + int main() { std::string de_double = "1.234.567,89"; std::string us_double = "1,234,567.89"; - + // parse using streams std::istringstream de_in(de_double); - de_in.imbue(std::locale("de_DE")); + de_in.imbue(std::locale("de_DE.UTF-8")); double f1; de_in >> f1; - + std::istringstream us_in(de_double); us_in.imbue(std::locale("en_US.UTF-8")); double f2; us_in >> f2; - + std::cout << "Parsing " << de_double << " as double gives " << std::fixed << f1 << " in de_DE locale and " << f2 << " in en_US\\n"; - + // use the facet directly std::istringstream s3(us_double); s3.imbue(std::locale("en_US.UTF-8")); + auto& f = std::use_facet>(s3.getloc()); std::istreambuf_iterator beg(s3), end; double f3; std::ios::iostate err; f.get(beg, end, s3, err, f3); + std::cout << "parsing " << us_double << " as double using raw en_US facet gives " << f3 << '\\n'; } @@ -113,11 +121,28 @@ Parsing 1.234.567,89 as double gives 1234567.890000 in de_DE locale and 1.234000 in en_US parsing 1,234,567.89 as double using raw en_US facet gives 1234567.890000 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + num_get was guaranteed to accept any only guarantees to accept + CharT that char, + LWG 427 C++98 meets the requirements for a wchar_t and other + character on which implementation- + any of the iostream components can defined character types + be instantiated + can guarantee to accept + LWG 2392 C++98 only character type CharT could be implementation- + guaranteed to be accepted by num_get defined character container + types + .SH See also numpunct defines numeric punctuation rules - \fI(class template)\fP + \fI(class template)\fP num_put formats numeric values for output as character sequence - \fI(class template)\fP + \fI(class template)\fP operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::num_get::get,std::num_get::do_get.3 b/man/std::num_get::get,std::num_get::do_get.3 index ffdf256ff..69078508c 100644 --- a/man/std::num_get::get,std::num_get::do_get.3 +++ b/man/std::num_get::get,std::num_get::do_get.3 @@ -1,67 +1,122 @@ -.TH std::num_get::get,std::num_get::do_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_get::get,std::num_get::do_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_get::get,std::num_get::do_get \- std::num_get::get,std::num_get::do_get + .SH Synopsis public: - iter_type get( iter_type in, iter_type end, std::ios_base& str, - - std::ios_base::iostate& err, bool& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, long& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, long long& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned short& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned int& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned long& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned long long& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, float& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, double& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, long double& v ) const; - iter_type get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, void*& v ) const; - protected: \fB(1)\fP - - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - - std::ios_base::iostate& err, bool& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, long& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, long long& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned short& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned int& v ) const; \fB(2)\fP - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned long& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, unsigned long long& v ) + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + + std::ios_base::iostate& err, + bool& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + long& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, \fI(since C++11)\fP + std::ios_base::iostate& err, long + long& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + unsigned short& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + unsigned int& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + unsigned long& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, \fI(since C++11)\fP + std::ios_base::iostate& err, + unsigned long long& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + float& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + double& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, long + double& v ) const; + iter_type get( iter_type in, iter_type end, + std::ios_base& str, + std::ios_base::iostate& err, + void*& v ) const; + protected: + + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + \fB(1)\fP + + std::ios_base::iostate& err, bool& v ) const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, long& v ) const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + \fI(since C++11)\fP + std::ios_base::iostate& err, long long& v ) + const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, unsigned short& v ) + const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, unsigned int& v ) + const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, \fB(2)\fP + + std::ios_base::iostate& err, unsigned long& v ) + const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + \fI(since C++11)\fP + std::ios_base::iostate& err, + + unsigned long long& v + ) const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, float& v ) const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, double& v ) const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, long double& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, float& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, double& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, long double& v ) const; - iter_type do_get( iter_type in, iter_type end, std::ios_base& str, - std::ios_base::iostate& err, void*& v ) const; + virtual iter_type do_get( iter_type in, + iter_type end, std::ios_base& str, + + std::ios_base::iostate& err, void*& v ) const; 1) Public member function, calls the member function do_get of the most derived class. 2) Reads characters from the input iterator in and generates the value of the type - of v, taking into account IO stream formatting flags from str.flags(), character - classification rules from std::use_facet>(str.getloc()), and + of v, taking into account I/O stream formatting flags from str.flags(), character + classification rules from std::use_facet>(str.getloc()), and numeric punctuation characters from - std::use_facet>(str.getloc()). This function is called by all + std::use_facet>(str.getloc()). This function is called by all formatted input stream operators such as std::cin >> n;. - Conversion occurs in three stages + Conversion occurs in three stages: .SH Stage 1: conversion specifier selection @@ -69,8 +124,7 @@ fmtflags basefield = (str.flags() & std::ios_base::basefield); fmtflags boolalpha = (str.flags() & std::ios_base::boolalpha); - - * If the type of v is an integer type, the the first applicable choice of the + * If the type of v is an integer type, the first applicable choice of the following five is selected: If basefield == oct, will use conversion specifier %o @@ -78,90 +132,90 @@ If basefield == 0, will use conversion specifier %i If the type of v is signed, will use conversion specifier %d If the type of v is unsigned, will use conversion specifier %u - * For integer types, length modifier is added to the conversion specification if - necessary: h for short and unsigned short, l for long and unsigned long, ll for - long long and unsigned long long + necessary: h for short and unsigned short, l for long and unsigned long + , ll for long long and unsigned long long + \fI(since C++11)\fP * If the type of v is float, will use conversion specifier %g * If the type of v is double, will use conversion specifier %lg * If the type of v is long double, will use conversion specifier %Lg * If the type of v is void*, will use conversion specifier %p - * If the type of v is bool and boolalpha==0, proceeds as if the type of v is long, - except for the value to be stored in v in stage 3. - * If the type of v is bool and boolalpha!=0, the following replaces stages 2 and + * If the type of v is bool and boolalpha == 0, proceeds as if the type of v is + long, except for the value to be stored in v in stage 3. + * If the type of v is bool and boolalpha != 0, the following replaces stages 2 and 3: - * Successive characters obtained from the input iterator in are matched against the character sequences obtained from - std::use_facet>(str.getloc()).falsename() and - std::use_facet >(str.getloc()).truename() only as + std::use_facet>(str.getloc()).falsename() and + std::use_facet>(str.getloc()).truename() only as necessary as to identify the unique match. The input iterator in is compared to end only when necessary to obtain a character. * If the target sequence is uniquely matched, v is set to the corresponding bool value. Otherwise false is stored in v and std::ios_base::failbit is assigned to err. If unique match could not be found before the input ended - (in==end), err|=std::ios_base::eofbit is executed. + (in == end), err |= std::ios_base::eofbit is executed. .SH Stage 2: character extraction - * If in==end, Stage 2 is terminated immediately, no further characters are - extracted - * The next character is extracted from in as if by char_type ct = *in; - - * If the character matches one of "0123456789abcdefxABCDEFX+-", widened to - the locale's char_type as if by - std::use_facet>(str.getloc()).widen(), it is converted to + * If in == end, stage 2 is terminated immediately, no further characters are + extracted. + * The next character is extracted from in as if by char_type ct = *in;: + * If the character matches one of + "0123456789abcdefxABCDEFX+-" + \fI(until C++11)\fP + "0123456789abcdefpxABCDEFPX+-" + \fI(since C++11)\fP, widened to the locale's char_type as if by + std::use_facet>(str.getloc()).widen(), it is converted to the corresponding char. * If the character matches the decimal point separator - (std::use_facet>(str.getloc()).decimal_point())), it + (std::use_facet>(str.getloc()).decimal_point())), it is replaced by '.'. * If the character matches the thousands separator - (std::use_facet>(str.getloc()).thousands_sep()) and - the thousands separation is in use at all - std::use_facet>(str.getloc()).grouping().length() != - 0, then if the decimal point '.' has not yet been accumulated, the position - of the character is rememebered, but the character is otherwise ignored. If - the decimal point has already been accumulated, the character is discarded - and Stage 2 terminates. + (std::use_facet>(str.getloc()).thousands_sep()) and + the thousands separation is in use (as determined by + std::use_facet>(str.getloc()).grouping().length() != + 0), then if the decimal point '.' has not yet been accumulated, the + position of the character is remembered, but the character is otherwise + ignored. If the decimal point has already been accumulated, the character + is discarded and stage 2 terminates. * In any case, the check is made whether the char obtained from the previous steps is allowed in the input field that would be parsed by std::scanf - given the conversion specifier selected in Stage 1. If it is allowed, it is - accumulated in a temporary buffer and Stage 2 repeats. If it is not - allowed, Stage 2 terminates. + given the conversion specifier selected in stage 1. If it is allowed, it is + accumulated in a temporary buffer and stage 2 repeats. If it is not + allowed, stage 2 terminates. .SH Stage 3: conversion and storage - * The sequence of chars accumulated in Stage 2 is converted to a numeric value - - The input is parsed as if by std::scanf with the conversion specifier \fI(until C++11)\fP - selected in Stage 1 - The input is parsed as if by std::strtoll for signed integer v, - std::strtoull for unsigned integer v, or std::strtold for \fI(since C++11)\fP - floating-point v - - * If the conversion function fails to convert the entire field, the - value 0 is stored in v - * If the conversion function results in a positive value too large - to fit in the type of v, the most positive representable value is \fI(since C++11)\fP - stored in v - * If the conversion function results in a negative value too large - to fit in the type of v, the most negative representable value is - stored in v - + * The sequence of chars accumulated in stage 2 is converted to a numeric value: + + The input is parsed according to the rules of std::scanf. \fI(until C++11)\fP + The input is parsed as if by + * std::strtoll for signed integer v, + * std::strtoull for unsigned integer v, \fI(since C++11)\fP + * std::strtof for float v, + * std::strtod for double v, or + * std::strtold for long double v. + + * If the conversion function fails to convert the entire field, the value 0 is + stored in v. + * If the type of v is a signed integer type and the conversion function results in + a positive or negative value too large to fit in it, the most positive or + negative representable value is stored in v, respectively. + * If the type of v is an unsigned integer type and the conversion function results + in a value that does not fit in it, the most positive representable value is + stored in v. * In any case, if the conversion function fails std::ios_base::failbit is assigned - to err - * Otherwise, the numeric result of the conversion is stored in v - + to err. + * Otherwise, the numeric result of the conversion is stored in v. * If the type of v is bool and boolalpha is not set, then if the value to be stored is 0, false is stored, if the value to be stored is 1, true is stored, for any other value std::ios_base::failbit is assigned to err and true is stored. - * After this, digit grouping is checked. if the position of any of the thousands - separators discarded in Stage 2 does not match the grouping provided by - std::use_facet>(str.getloc()).grouping(), + separators discarded in stage 2 does not match the grouping provided by + std::use_facet>(str.getloc()).grouping(), std::ios_base::failbit is assigned to err. - * If Stage 2 was terminated by the test in==end, err|=std::ios_base::eofbit is + * If stage 2 was terminated by the test in == end, err |= std::ios_base::eofbit is executed to set the eof bit. .SH Return value @@ -170,52 +224,94 @@ .SH Notes - In C++98/C++03, if an error occurs, v is left unchanged. In C++11, it is set to a - value as described above. + Before the resolutions of LWG issue 23 and LWG issue 696, v was left unchanged if an + error occurs. + + Before the resolution of LWG issue 221, strings representing hexadecimal integers + (e.g. "0xA0") were rejected by do_get(int) even if they are valid input to strtol + because stage 2 filters out characters 'X' and 'x'. + + Before the resolution of LWG issue 1169, converting a negative number string into an + unsigned integer might produce zero (since the value represented by the string is + smaller than what the target type can represent). + + Before the resolution of LWG issue 2381, strings representing + hexadecimal floating-point numbers with exponents (e.g. "0x1.23p-10") + were rejected by do_get(double) even if they are valid input to strtod + because stage 2 filters out characters 'P' and 'p'. \fI(since C++11)\fP + + The strings representing infinity or not-a-number (e.g. "NaN" and + "inf") are rejected by do_get(double) even if they are valid input to + strtod because stage 2 filters out characters such as 'N' or 'i'. .SH Example An implementation of operator>> for a user-defined type. - + // Run this code #include #include #include - + struct base { long x; }; - - template + + template std::basic_istream& - operator >>(std::basic_istream& is, - base& b) + operator >>(std::basic_istream& is, base& b) { std::ios_base::iostate err = std::ios_base::goodbit; + try // setting err could throw { typename std::basic_istream::sentry s(is); - + if (s) // if stream is ready for input - { - std::istreambuf_iterator end; - std::use_facet>(is.getloc()).get(is, end, is, err, b.x); - } - } catch(std::ios_base::failure& error) + std::use_facet>(is.getloc()).get(is, {}, is, err, b.x); + } + catch (std::ios_base::failure& error) { // handle the exception } + return is; } - + int main() { base b; - std::cin >> b; } + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 17 C++98 the process of parsing text boolean corrected + values was errornous + LWG 18 C++98 the overload of get taking bool& value added + was missing + LWG 23 C++98 overflowing input resulted in undefined overflow handled + behavior + LWG 154 C++98 the conversion specifier for double was changed to %lg + %g (same as float) + LWG 221 C++98 do_get did not parse 'x' and 'X' while made 'x' and 'X' parsed + strtol parsed them + LWG 275 C++98 get had an overload taking short& value corrected + instead of float& + LWG 358 C++98 thousand separators after the decimal stage 2 is terminated if + point were ignored encountered + LWG 696 C++98 the result was unchanged on conversion set to zero + failure + LWG 1169 C++98 overflow handling was inconsistent made consistent + between floating-point types with strtof/strtod + LWG 2381 C++11 do_get did not parse 'p' and 'P' while made 'p' and 'P' parsed + strtod parsed them + .SH See also operator>> extracts formatted data - \fI(public member function of std::basic_istream)\fP + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::num_get::num_get.3 b/man/std::num_get::num_get.3 index 54965c2aa..93f8ec03b 100644 --- a/man/std::num_get::num_get.3 +++ b/man/std::num_get::num_get.3 @@ -1,10 +1,13 @@ -.TH std::num_get::num_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_get::num_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_get::num_get \- std::num_get::num_get + .SH Synopsis Defined in header explicit num_get( std::size_t refs = 0 ); Creates a std::num_get facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::num_get::~num_get.3 b/man/std::num_get::~num_get.3 index c83f67701..4577f9e07 100644 --- a/man/std::num_get::~num_get.3 +++ b/man/std::num_get::~num_get.3 @@ -1,4 +1,7 @@ -.TH std::num_get::~num_get 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_get::~num_get 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_get::~num_get \- std::num_get::~num_get + .SH Synopsis Defined in header protected: ~num_get(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_num_get : public std::num_get { Destructible_num_get(std::size_t refs = 0) : num_get(refs) {} - ~Destructible_num_get() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_num_get dc; - // std::num_get c; // compile error: protected destructor + // std::num_get c; // compile error: protected destructor } diff --git a/man/std::num_put.3 b/man/std::num_put.3 index 68b9f4e0a..3dfc65d98 100644 --- a/man/std::num_put.3 +++ b/man/std::num_put.3 @@ -1,4 +1,7 @@ -.TH std::num_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_put \- std::num_put + .SH Synopsis Defined in header template< @@ -9,37 +12,40 @@ > class num_put; Class std::num_put encapsulates the rules for formatting numeric values as strings. - Specifically, the types bool, long, unsigned long, long long, unsigned long long, - double, long double, void*, and of all types implicitly convertible to these (such - as int or float) are supported. The standard formatting output operators (such as - cout << n;) use the std::num_put facet of the I/O stream's locale to generate text - representation of numbers. + Specifically, the types bool, long, unsigned long + , long long, unsigned long long + \fI(since C++11)\fP, double, long double, void*, and of all types implicitly convertible + to these (such as int or float) are supported. The standard formatting output + operators (such as cout << n;) use the std::num_put facet of the I/O stream's locale + to generate text representation of numbers. std-num put-inheritance.svg - About this image Inheritance diagram -.SH Type requirements - - - - OutputIt must meet the requirements of OutputIterator. + If a std::num_put specialization is not guaranteed to be provided by the standard + library (see below), the behaviors of its put() and do_put() are not guaranteed as + specified. .SH Specializations - Two standalone (locale-independent) full specializations and two partial - specializations are provided by the standard library: + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header - std::num_put creates narrow string representations of numbers - std::num_put creates wide string representations of numbers - std::num_put creates narrow string representations of numbers - using custom output iterator - std::num_put creates wide string representations of numbers using - custom output iterator + std::num_put creates narrow string representations of numbers + std::num_put creates wide string representations of numbers + + In addition, the standard library is also guaranteed to provide every specialization + that satisfies the following type requirements: - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. + * CharT is one of + * char, + * wchar_t, and + * any other implementation-defined character container type that meets the + requirements for a character on which any of the iostream components can be + instantiated; and + * OutputIt must meet the requirements of LegacyOutputIterator. .SH Member types @@ -51,15 +57,15 @@ constructor constructs a new num_put facet \fI(public member function)\fP - destructor destructs a num_put facet - \fI(protected member function)\fP put invokes do_put \fI(public member function)\fP .SH Protected member functions - do_put formats a number and writes to output stream - \fB[virtual]\fP \fI(virtual protected member function)\fP + destructor destructs a num_put facet + \fI(protected member function)\fP + do_put formats a number and writes to output stream + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Member objects @@ -68,23 +74,24 @@ .SH Example - + // Run this code #include + #include #include #include - #include - + int main() { double n = 1234567.89; - std::cout.imbue(std::locale("de_DE")); + std::cout.imbue(std::locale("de_DE.UTF-8")); std::cout << "Direct conversion to string:\\n" << std::to_string(n) << '\\n' << "Output using a german locale:\\n" << std::fixed << n << '\\n' << "Output using an american locale:\\n"; + // use the facet directly std::cout.imbue(std::locale("en_US.UTF-8")); auto& f = std::use_facet>(std::cout.getloc()); @@ -92,7 +99,7 @@ std::cout << '\\n'; } -.SH Output: +.SH Possible output: Direct conversion to string: 1234567.890000 @@ -101,13 +108,30 @@ Output using an american locale: 1,234,567.890000 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + num_put was guaranteed to accept any only guarantees to accept + CharT that char, + LWG 427 C++98 meets the requirements for a wchar_t and other + character on which implementation- + any of the iostream components can defined character types + be instantiated + can guarantee to accept + LWG 2392 C++98 only character type CharT could be implementation- + guaranteed to be accepted by num_put defined character container + types + .SH See also numpunct defines numeric punctuation rules - \fI(class template)\fP + \fI(class template)\fP num_get parses numeric values from an input character sequence - \fI(class template)\fP - to_string converts an integral or floating point value to string - \fI(C++11)\fP \fI(function)\fP - to_wstring converts an integral or floating point value to wstring - \fI(C++11)\fP \fI(function)\fP + \fI(class template)\fP + to_string converts an integral or floating-point value to string + \fI(C++11)\fP \fI(function)\fP + to_wstring converts an integral or floating-point value to wstring + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::num_put::num_put.3 b/man/std::num_put::num_put.3 index 187f6c3ea..6d19e6371 100644 --- a/man/std::num_put::num_put.3 +++ b/man/std::num_put::num_put.3 @@ -1,10 +1,13 @@ -.TH std::num_put::num_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_put::num_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_put::num_put \- std::num_put::num_put + .SH Synopsis Defined in header explicit num_put( std::size_t refs = 0 ); Creates a std::num_put facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::num_put::put,std::num_put::do_put.3 b/man/std::num_put::put,std::num_put::do_put.3 index de7a21d4e..b32099eb4 100644 --- a/man/std::num_put::put,std::num_put::do_put.3 +++ b/man/std::num_put::put,std::num_put::do_put.3 @@ -1,49 +1,86 @@ -.TH std::num_put::put,std::num_put::do_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_put::put,std::num_put::do_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_put::put,std::num_put::do_put \- std::num_put::put,std::num_put::do_put + .SH Synopsis Defined in header public: - iter_type put( iter_type out, std::ios_base& str, char_type fill, bool v ) - const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, long v ) + + iter_type put( iter_type out, std::ios_base& + str, + + char_type fill, bool val ) const; + iter_type put( iter_type out, std::ios_base& + str, + char_type fill, long val ) const; + iter_type put( iter_type out, std::ios_base& + str, \fI(since C++11)\fP + char_type fill, long long val ) const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, long - long v ) const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, unsigned - long v ) const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, unsigned - long long v ) const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, double v + iter_type put( iter_type out, std::ios_base& + str, + char_type fill, unsigned long val ) const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, long - double v ) const; - iter_type put( iter_type out, std::ios_base& str, char_type fill, const - void* v ) const; \fB(1)\fP - protected: - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, bool - v ) const; - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, long - v ) const; - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, long - long v ) const; - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, - unsigned long ) const; \fB(2)\fP - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, - unsigned long long ) const; - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, - double v ) const; - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, long - double v ) const; - iter_type do_put( iter_type out, std::ios_base& str, char_type fill, const - void* v ) const; + iter_type put( iter_type out, std::ios_base& + str, \fI(since C++11)\fP + char_type fill, unsigned long + long val ) const; + iter_type put( iter_type out, std::ios_base& + str, + char_type fill, double val ) + const; + iter_type put( iter_type out, std::ios_base& + str, + char_type fill, long double val ) + const; + iter_type put( iter_type out, std::ios_base& + str, + char_type fill, const void* val ) + const; + protected: \fB(1)\fP + + virtual iter_type do_put( iter_type out, + std::ios_base& str, + + char_type fill, bool + val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, + char_type fill, long + val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, \fI(since C++11)\fP + char_type fill, long + long val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, + char_type fill, \fB(2)\fP + unsigned long val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, \fI(since C++11)\fP + char_type fill, + unsigned long long val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, + char_type fill, double + val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, + char_type fill, long + double val ) const; + virtual iter_type do_put( iter_type out, + std::ios_base& str, + char_type fill, const + void* val ) const; 1) Public member function, calls the protected virtual member function do_put of the most derived class. - 2) Writes characters to the output sequence out which represent the value of v, + 2) Writes characters to the output sequence out which represent the value of val, formatted as requested by the formatting flags str.flags() and the std::numpunct and std::ctype facets of the locale imbued in the stream str. This function is called by all formatted output stream operators, such as std::cout << n;. - Conversion occurs in four stages + Conversion occurs in four stages: .SH Stage 1: conversion specifier selection @@ -54,54 +91,57 @@ fmtflags floatfield = (str.flags() & std::ios_base::floatfield); fmtflags showpos = (str.flags() & std::ios_base::showpos); fmtflags showbase = (str.flags() & std::ios_base::showbase); - - * If the type of v is bool - - * If boolalpha == 0, then converts v to type int and performs integer output. - * If boolalpha != 0 obtains - std::use_facet>(str.getloc()).truename() if v == true - or std::use_facet>(str.getloc()).falsename() if v == - false, and outputs each successive character c of that string to out with - *out++ = c. No further processing is done in this case, the function + fmtflags showpoint = (str.flags() & std::ios_base::showpoint); + * If the type of val is bool: + * If boolalpha == 0, then converts val to type int and performs integer + output. + * If boolalpha != 0, obtains + std::use_facet>(str.getloc()).truename() if val == + true or std::use_facet>(str.getloc()).falsename() if + val == false, and outputs each successive character c of that string to out + with *out++ = c. No further processing is done in this case, the function returns out. - - * If the type of v is an integer type, the the first applicable choice of the - following five is selected: - - If basefield == oct, will use conversion specifier %o - If basefield == hex && !uppercase, will use conversion specifier %x - If basefield == hex, will use conversion specifier %X - If the type of v is signed, will use conversion specifier %d - If the type of v is unsigned, will use conversion specifier %u - + * If the type of val is an integer type, the first applicable choice of the + following is selected: + * If basefield == oct, will use conversion specifier %o + * If basefield == hex && !uppercase, will use conversion specifier %x + * If basefield == hex, will use conversion specifier %X + * If the type of val is signed, will use conversion specifier %d + * If the type of val is unsigned, will use conversion specifier %u * For integer types, length modifier is added to the conversion specification if - necessary: l for long and unsigned long, ll for long long and unsigned long - long. - * If the type of v is a floating-point type, the the first applicable choice of - the following five is selected: - - If floatfield == std::ios_base::fixed, will use conversion specifier %f - If floatfield == std::ios_base::scientific && !uppercase, will use conversion - specifier %e - If floatfield == std::ios_base::scientific, will use conversion specifier %E - If floatfield == (std::ios_base::fixed | std::ios_base::scientific) && !uppercase, - will use conversion specifier %a \fI(since C++11)\fP - If floatfield == std::ios_base::fixed | std::ios_base::scientific, will use - conversion specifier %A \fI(since C++11)\fP - If !uppercase, will use conversion specifier %g - otherwise, will use conversion specifier %G - - * - * If the type of v is long double, the length modifier L is added to the - conversion specifier. - * Additionally, if floatfield != (ios_base::fixed | ios_base::scientific), - then precision modifier is added, set to str.precision() - - * For both integer and floating-point types, if showbase is set, the modifier # is - prepended. If showpos is set, the modifier + is prepended. - * If the type of v is void*, will use conversion specifier %p - * A narrow character string is created as if by a call to std::printf(spec, v) in - the "C" locale, where spec is the chosen conversion specifier. + necessary: l for long and unsigned long + , ll for long long and unsigned long long + \fI(since C++11)\fP. + * If the type of val is a floating-point type, the first applicable choice of the + following is selected: + * If floatfield == std::ios_base::fixed, will use conversion specifier %f + * If floatfield == std::ios_base::scientific && !uppercase, will use + conversion specifier %e + * If floatfield == std::ios_base::scientific, will use conversion specifier + %E + + * If floatfield == (std::ios_base::fixed | + std::ios_base::scientific) && !uppercase, will use conversion + specifier %a \fI(since C++11)\fP + * If floatfield == (std::ios_base::fixed | + std::ios_base::scientific), will use conversion specifier %A + + * If !uppercase, will use conversion specifier %g + * Otherwise, will use conversion specifier %G + Also: + * If the type of val is long double, the length modifier L is added to the + conversion specifier. + * If the type of val is a floating-point type + and floatfield != (ios_base::fixed | ios_base::scientific) + \fI(since C++11)\fP, the precision modifier is added and set to str.precision(). + Otherwise, no precision is specified. + * For both integer and floating-point types, if showpos is set, the modifier + is + prepended + * For integer types, if showbase is set, the modifier # is prepended. + * For floating-point types, if showpoint is set, the modifier # is prepended. + * If the type of val is void*, will use conversion specifier %p + * A narrow character string is created as if by a call to std::printf(spec, val) + in the "C" locale, where spec is the chosen conversion specifier. .SH Stage 2: locale-specific conversion @@ -119,16 +159,14 @@ * The adjustment flag is obtained as if by std::fmtflags adjustfield = (flags & (std::ios_base::adjustfield)) and examined to identify padding location, as - follows - - If adjustfield == std::ios_base::left, will pad after - If adjustfield == std::ios_base::right, will pad before - If adjustfield == std::ios_base::internal and a sign character occurs in the - representation, will pad after the sign - If adjustfield == std::ios_base::internal and Stage 1 representation began with 0x - or 0X, will pad after the x or X - otherwise, will pad before - + follows: + * If adjustfield == std::ios_base::left, will pad after + * If adjustfield == std::ios_base::right, will pad before + * If adjustfield == std::ios_base::internal and a sign character occurs in + the representation, will pad after the sign + * If adjustfield == std::ios_base::internal and Stage 1 representation began + with 0x or 0X, will pad after the x or X + * Otherwise, will pad before * If str.width() is non-zero (e.g. std::setw was just used) and the number of CharT's after Stage 2 is less than str.width(), then copies of the fill character are inserted at the position indicated by padding to bring the length @@ -146,7 +184,7 @@ out - iterator pointing to the first character to be overwritten str - stream to retrieve the formatting information from fill - padding character used when the results needs to be padded to the field width - v - value to convert to string and output + val - value to convert to string and output .SH Return value @@ -158,37 +196,43 @@ combination of std::showbase and std::oct for example) is not counted as a padding character. + When formatting a floating point value as hexfloat (i.e., when + floatfield == (std::ios_base::fixed | std::ios_base::scientific)), the \fI(since C++11)\fP + stream's precision is not used; instead, the number is always printed + with enough precision to exactly represent the value. + .SH Example - Output a number using the facet directly, and demonstrate user-defined facet + Output a number using the facet directly, and demonstrate user-defined facet: + - // Run this code #include #include - + // this custom num_put outputs squares of all integers (except long long) - struct squaring_num_put : std::num_put { - iter_type do_put(iter_type s, std::ios_base& f, - char_type fill, long v) const + struct squaring_num_put : std::num_put + { + iter_type do_put(iter_type out, std::ios_base& str, + char_type fill, long val) const { - return std::num_put::do_put(s, f, fill, v*v ); + return std::num_put::do_put(out, str, fill, val * val); } - - iter_type do_put(iter_type s, std::ios_base& f, - char_type fill, unsigned long v) const + + iter_type do_put(iter_type out, std::ios_base& str, + char_type fill, unsigned long val) const { - return std::num_put::do_put(s, f, fill, v*v); + return std::num_put::do_put(out, str, fill, val * val); } }; - + int main() { auto& facet = std::use_facet>(std::locale()); facet.put(std::cout, std::cout, '0', 2.71); std::cout << '\\n'; - + std::cout.imbue(std::locale(std::cout.getloc(), new squaring_num_put)); std::cout << 6 << ' ' << -12 << '\\n'; } @@ -200,37 +244,41 @@ An implementation of operator<< for a user-defined type. - + // Run this code #include #include #include - + struct base { long x = 10; }; - - template + + template std::basic_ostream& - operator<< (std::basic_ostream& os, base const& b) + operator<<(std::basic_ostream& os, base const& b) { - try { + try + { typename std::basic_ostream::sentry s(os); + if (s) { std::ostreambuf_iterator it(os); std::use_facet>(os.getloc()) .put(it, os, os.fill(), b.x); } - } catch (...) { + } + catch (...) + { // set badbit on os and rethrow if required } + return os; } - + int main() { base b; - std::cout << b; } @@ -238,7 +286,23 @@ 10 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the bool overload used non-existing use these members of + LWG 34 C++98 members std::numpunct + truename and falsename of std::ctype + the precision modifier was only added + LWG 231 C++98 if removed these conditions + (flags & fixed) != 0 or str.precision() + > 0 + LWG 282 C++98 the thousand separators were only also inserted for + inserted for integral types in stage 2 floating-point types + .SH See also operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::num_put::~num_put.3 b/man/std::num_put::~num_put.3 index 99f5768b6..20226f39c 100644 --- a/man/std::num_put::~num_put.3 +++ b/man/std::num_put::~num_put.3 @@ -1,4 +1,7 @@ -.TH std::num_put::~num_put 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::num_put::~num_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::num_put::~num_put \- std::num_put::~num_put + .SH Synopsis Defined in header protected: ~num_put(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_num_put : public std::num_put { Destructible_num_put(std::size_t refs = 0) : num_put(refs) {} - ~Destructible_num_put() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_num_put dc; - // std::num_put c; // compile error: protected destructor + // std::num_put c; // compile error: protected destructor } diff --git a/man/std::numeric_limits.3 b/man/std::numeric_limits.3 index 029435548..fde9cd3f0 100644 --- a/man/std::numeric_limits.3 +++ b/man/std::numeric_limits.3 @@ -1,51 +1,58 @@ -.TH std::numeric_limits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits \- std::numeric_limits + .SH Synopsis Defined in header template< class T > class numeric_limits; - The numeric_limits class template provides a standardized way to query various - properties of fundamental types (e.g. the largest possible value for type int is + The std::numeric_limits class template provides a standardized way to query various + properties of arithmetic types (e.g. the largest possible value for type int is std::numeric_limits::max()). - This information is provided via specializations of the numeric_limits template. The - standard library makes available specializations for all fundamental types: + This information is provided via specializations of the std::numeric_limits + template. The standard library makes available specializations for all arithmetic + types (only lists the specializations for cv-unqualified arithmetic types): Defined in header template<> class numeric_limits; - template<> class numeric_limits; template<> class numeric_limits; template<> class numeric_limits; template<> class numeric_limits; - template<> class numeric_limits; // C++11 feature - template<> class numeric_limits; // C++11 feature + template<> class numeric_limits; \fI(since C++20)\fP + template<> class numeric_limits; \fI(since C++11)\fP + template<> class numeric_limits; \fI(since C++11)\fP template<> class numeric_limits; template<> class numeric_limits; template<> class numeric_limits; template<> class numeric_limits; template<> class numeric_limits; template<> class numeric_limits; - template<> class numeric_limits; - template<> class numeric_limits; + template<> class numeric_limits; \fI(since C++11)\fP + template<> class numeric_limits; \fI(since C++11)\fP template<> class numeric_limits; template<> class numeric_limits; - template<> class numeric_limits; - Additionally, a specialization exists for every cv-qualified version of each - fundamental type, identical to the unqualified specialization, e.g. - std::numeric_limits, std::numeric_limits, and - std::numeric_limits are provided and are equivalent to - std::numeric_limits. + The value of each member of a specialization of std::numeric_limits on a + cv-qualified type cv T is equal to the value of the corresponding member of the + specialization on the unqualified type T. For example, + std::numeric_limits::digits is equal to std::numeric_limits::digits. + + Aliases of arithmetic types (such as std::size_t or std::streamsize) may also be + examined with the std::numeric_limits type traits. - The standard library types that are aliases of fundamental types (such as - std::size_t or std::streamsize may also be examined with the std::numeric_limits - type traits. + Non-arithmetic standard types, such as std::complex or std::nullptr_t, do not + have specializations. + + If the implementation defines any integer-class types, specializations \fI(since C++20)\fP + of std::numeric_limits must also be provided for them. Implementations may provide specializations of std::numeric_limits for implementation-specific types: e.g. GCC provides std::numeric_limits<__int128>. - Libraries may add specializations for library-provided types, e.g. OpenEXR provides - std::numeric_limits for a 16-bit floating-point type. + Non-standard libraries may add specializations for library-provided types, e.g. + OpenEXR provides std::numeric_limits for a 16-bit floating-point type. .SH Template parameters @@ -54,183 +61,191 @@ .SH Member constants is_specialized identifies types for which std::numeric_limits is specialized - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_signed identifies signed types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_integer identifies integer types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_exact identifies exact types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP has_infinity identifies floating-point types that can represent the special \fB[static]\fP value "positive infinity" - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_quiet_NaN identifies floating-point types that can represent the special \fB[static]\fP value "quiet not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_signaling_NaN identifies floating-point types that can represent the special \fB[static]\fP value "signaling not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_denorm identifies the denormalization style used by the floating-point \fB[static]\fP type - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_denorm_loss identifies the floating-point types that detect loss of precision \fB[static]\fP as denormalization loss rather than inexact result - \fI(public static member constant)\fP + \fI(public static member constant)\fP round_style identifies the rounding style used by the type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_iec559 identifies the IEC 559/IEEE 754 floating-point types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_bounded identifies types that represent a finite set of values - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_modulo identifies types that handle overflows with modulo arithmetic - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP digits number of radix digits that can be represented without change - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP digits10 number of decimal digits that can be represented without change - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP max_digits10 number of decimal digits necessary to differentiate all values of \fB[static]\fP \fI(C++11)\fP this type - \fI(public static member constant)\fP + \fI(public static member constant)\fP radix the radix or integer base used by the representation of the given \fB[static]\fP type - \fI(public static member constant)\fP + \fI(public static member constant)\fP min_exponent one more than the smallest negative power of the radix that is a \fB[static]\fP valid normalized floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP min_exponent10 the smallest negative power of ten that is a valid normalized \fB[static]\fP floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a \fB[static]\fP valid finite floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent10 the largest integer power of 10 that is a valid finite \fB[static]\fP floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP traps identifies types which can cause arithmetic operations to trap - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP tinyness_before identifies floating-point types that detect tinyness before \fB[static]\fP rounding - \fI(public static member constant)\fP + \fI(public static member constant)\fP .SH Member functions min returns the smallest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP lowest returns the lowest finite value of the given type - \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP max returns the largest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP epsilon returns the difference between 1.0 and the next representable value \fB[static]\fP of the given floating-point type - \fI(public static member function)\fP + \fI(public static member function)\fP round_error returns the maximum rounding error of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP infinity returns the positive infinity value of the given floating-point \fB[static]\fP type - \fI(public static member function)\fP + \fI(public static member function)\fP quiet_NaN returns a quiet NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP signaling_NaN returns a signaling NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP denorm_min returns the smallest positive subnormal value of the given \fB[static]\fP floating-point type - \fI(public static member function)\fP + \fI(public static member function)\fP .SH Helper classes float_round_style indicates floating-point rounding modes - \fI(enum)\fP + \fI(enum)\fP float_denorm_style indicates floating-point denormalization modes - \fI(enum)\fP + \fI(enum)\fP .SH Relationship with C library macro constants - Members - Specialization min() lowest() max() epsilon() digits digits10 min_exponent min_exponent10 max_exponent max_exponent10 radix - \fI(C++11)\fP -[numeric_limits< 2 -]bool [ >] -[numeric_limits< CHAR_MIN CHAR_MIN CHAR_MAX 2 -]char [ >] -[numeric_limits< -]signed char [ SCHAR_MIN SCHAR_MIN SCHAR_MAX 2 ->] -[numeric_limits< -]unsigned char [ 0 0 UCHAR_MAX 2 ->] -[numeric_limits< WCHAR_MIN WCHAR_MIN WCHAR_MAX 2 -]wchar_t [ >] -[numeric_limits< 0 0 UINT_LEAST16_MAX 2 -]char16_t [ >] -[numeric_limits< 0 0 UINT_LEAST32_MAX 2 -]char32_t [ >] -[numeric_limits< -]short [ >] -[numeric_limits< SHRT_MIN SHRT_MIN SHRT_MAX 2 -]signed short [ ->] -[numeric_limits< -]unsigned short 0 0 USHRT_MAX 2 -[ >] -[numeric_limits< -]int [ >] INT_MIN INT_MIN INT_MAX 2 -[numeric_limits< -]signed int [ >] -[numeric_limits< -]unsigned int [ 0 0 UINT_MAX 2 ->] -[numeric_limits< -]long [ >] -[numeric_limits< LONG_MIN LONG_MIN LONG_MAX 2 -]signed long [ ->] -[numeric_limits< -]unsigned long [ 0 0 ULONG_MAX 2 ->] -[numeric_limits< -]long long [ >] -[numeric_limits< LLONG_MIN LLONG_MIN LLONG_MAX 2 -]signed long -long [ >] -[numeric_limits< -]unsigned long 0 0 ULLONG_MAX 2 -long [ >] -[numeric_limits< FLT_MIN -FLT_MAX FLT_MAX FLT_EPSILON FLT_MANT_DIG FLT_DIG FLT_MIN_EXP FLT_MIN_10_EXP FLT_MAX_EXP FLT_MAX_10_EXP FLT_RADIX -]float [ >] -[numeric_limits< DBL_MIN -DBL_MAX DBL_MAX DBL_EPSILON DBL_MANT_DIG DBL_DIG DBL_MIN_EXP DBL_MIN_10_EXP DBL_MAX_EXP DBL_MAX_10_EXP FLT_RADIX -]double [ >] -[numeric_limits< -]long double [ LDBL_MIN -LDBL_MAX LDBL_MAX LDBL_EPSILON LDBL_MANT_DIG LDBL_DIG LDBL_MIN_EXP LDBL_MIN_10_EXP LDBL_MAX_EXP LDBL_MAX_10_EXP FLT_RADIX ->] + Specialization Members + std::numeric_limits min() lowest() max() radix + where T is \fI(C++11)\fP + bool false false true 2 + char CHAR_MIN CHAR_MIN CHAR_MAX 2 + signed char SCHAR_MIN SCHAR_MIN SCHAR_MAX 2 + unsigned char 0 0 UCHAR_MAX 2 + wchar_t WCHAR_MIN WCHAR_MIN WCHAR_MAX 2 + char8_t 0 0 UCHAR_MAX 2 + char16_t 0 0 UINT_LEAST16_MAX 2 + char32_t 0 0 UINT_LEAST32_MAX 2 + short SHRT_MIN SHRT_MIN SHRT_MAX 2 + signed short + unsigned short 0 0 USHRT_MAX 2 + int INT_MIN INT_MIN INT_MAX 2 + signed int + unsigned int 0 0 UINT_MAX 2 + long LONG_MIN LONG_MIN LONG_MAX 2 + signed long + unsigned long 0 0 ULONG_MAX 2 + long long LLONG_MIN LLONG_MIN LLONG_MAX 2 + signed long long + unsigned long long 0 0 ULLONG_MAX 2 + + Specialization Members +std::numeric_limits denorm_min() min() lowest() max() epsilon() digits digits10 + where T is \fI(C++11)\fP +float FLT_TRUE_MIN FLT_MIN -FLT_MAX FLT_MAX FLT_EPSILON FLT_MANT_DIG FLT_DIG +double DBL_TRUE_MIN DBL_MIN -DBL_MAX DBL_MAX DBL_EPSILON DBL_MANT_DIG DBL_DIG +long double LDBL_TRUE_MIN LDBL_MIN -LDBL_MAX LDBL_MAX LDBL_EPSILON LDBL_MANT_DIG LDBL_DIG + + Specialization Members (continue) +std::numeric_limits + where T is min_exponent min_exponent10 max_exponent max_exponent10 radix +float FLT_MIN_EXP FLT_MIN_10_EXP FLT_MAX_EXP FLT_MAX_10_EXP FLT_RADIX +double DBL_MIN_EXP DBL_MIN_10_EXP DBL_MAX_EXP DBL_MAX_10_EXP FLT_RADIX +long double LDBL_MIN_EXP LDBL_MIN_10_EXP LDBL_MAX_EXP LDBL_MAX_10_EXP FLT_RADIX .SH Example - + // Run this code - #include #include - + #include + int main() { - std::cout << "type\\tlowest\\thighest\\n"; - std::cout << "int\\t" - << std::numeric_limits::lowest() << '\\t' - << std::numeric_limits::max() << '\\n'; - std::cout << "float\\t" - << std::numeric_limits::lowest() << '\\t' - << std::numeric_limits::max() << '\\n'; - std::cout << "double\\t" - << std::numeric_limits::lowest() << '\\t' + std::cout << "type\\t│ lowest()\\t│ min()\\t\\t│ max()\\n" + << "bool\\t│ " + << std::numeric_limits::lowest() << "\\t\\t│ " + << std::numeric_limits::min() << "\\t\\t│ " + << std::numeric_limits::max() << '\\n' + << "uchar\\t│ " + << +std::numeric_limits::lowest() << "\\t\\t│ " + << +std::numeric_limits::min() << "\\t\\t│ " + << +std::numeric_limits::max() << '\\n' + << "int\\t│ " + << std::numeric_limits::lowest() << "\\t│ " + << std::numeric_limits::min() << "\\t│ " + << std::numeric_limits::max() << '\\n' + << "float\\t│ " + << std::numeric_limits::lowest() << "\\t│ " + << std::numeric_limits::min() << "\\t│ " + << std::numeric_limits::max() << '\\n' + << "double\\t│ " + << std::numeric_limits::lowest() << "\\t│ " + << std::numeric_limits::min() << "\\t│ " << std::numeric_limits::max() << '\\n'; } .SH Possible output: - type lowest highest - int -2147483648 2147483647 - float -3.40282e+38 3.40282e+38 - double -1.79769e+308 1.79769e+308 + type │ lowest() │ min() │ max() + bool │ 0 │ 0 │ 1 + uchar │ 0 │ 0 │ 255 + int │ -2147483648 │ -2147483648 │ 2147483647 + float │ -3.40282e+38 │ 1.17549e-38 │ 3.40282e+38 + double │ -1.79769e+308 │ 2.22507e-308 │ 1.79769e+308 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 201 C++98 specializations for all fundamental types excluded non-arithmetic + need to be provided types + it was unclear whether the + std::numeric_limits + LWG 559 C++98 specialization for a cv-qualified type they have the + behaves as the same as same behavior + the corresponding specialization for the + cv-unqualified type .SH See also @@ -238,3 +253,4 @@ long [ >] * Arithmetic types * C++ type system overview * Type support (basic types, RTTI, type traits) + * C numeric limits interface diff --git a/man/std::numeric_limits::denorm_min.3 b/man/std::numeric_limits::denorm_min.3 index ae8c9088e..9aede0052 100644 --- a/man/std::numeric_limits::denorm_min.3 +++ b/man/std::numeric_limits::denorm_min.3 @@ -1,69 +1,90 @@ -.TH std::numeric_limits::denorm_min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::denorm_min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::denorm_min \- std::numeric_limits::denorm_min + .SH Synopsis - static T denorm_min(); \fI(until C++11)\fP - static constexpr T denorm_min(); \fI(since C++11)\fP + static T denorm_min() throw(); \fI(until C++11)\fP + static constexpr T denorm_min() noexcept; \fI(since C++11)\fP Returns the minimum positive subnormal value of the type T, if std::numeric_limits::has_denorm != std::denorm_absent, otherwise returns - std::numeric_limits::min(). Only meaningful for floating-point types. + std::numeric_limits::min() for floating point types and T() for all other types. + Only meaningful for floating-point types. .SH Return value - T std::numeric_limits::denorm_min() - /* non-specialized */ T(); - bool false - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float 2-149 - if std::numeric_limits::is_iec559 == true - double 2-1074 - if std::numeric_limits::is_iec559 == true - long double /* implementation-defined */ - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::denorm_min() + /* non-specialized */ T() + bool false + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long since (since 0 + C++11) + FLT_TRUE_MIN (\\(\\scriptsize 2^{-149}\\)2-149 + float if + std::numeric_limits::is_iec559 is true) + DBL_TRUE_MIN (\\(\\scriptsize 2^{-1074}\\)2-1074 + double if + std::numeric_limits::is_iec559 is true) + long double LDBL_TRUE_MIN .SH Example - Demonstates the underlying bit structure of the denorm_min() + Demonstates the underlying bit structure of the denorm_min() and prints the values: + - // Run this code + #include #include + #include + #include #include - #include + int main() { // the smallest subnormal value has sign bit = 0, exponent = 0 // and only the least significant bit of the fraction is 1 - uint32_t denorm_bits = 0x0001; - float denorm_float = reinterpret_cast(denorm_bits); + std::uint32_t denorm_bits = 0x0001; + float denorm_float; + std::memcpy(&denorm_float, &denorm_bits, sizeof(float)); + assert(denorm_float == std::numeric_limits::denorm_min()); + + std::cout << "float\\tmin()\\t\\tdenorm_min()\\n"; + std::cout << "\\t" << std::numeric_limits::min() << '\\t'; + std::cout << std::numeric_limits::denorm_min() << '\\n'; + + std::cout << "double\\tmin()\\t\\tdenorm_min()\\n"; + std::cout << "\\t" << std::numeric_limits::min() << '\\t'; + std::cout << std::numeric_limits::denorm_min() << '\\n'; } +.SH Possible output: + + float min() denorm_min() + 1.17549e-38 1.4013e-45 + double min() denorm_min() + 2.22507e-308 4.94066e-324 + .SH See also min returns the smallest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP has_denorm identifies the denormalization style used by the floating-point \fB[static]\fP type - \fI(public static member constant)\fP + \fI(public static member constant)\fP lowest returns the lowest finite value of the given type - \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP diff --git a/man/std::numeric_limits::digits.3 b/man/std::numeric_limits::digits.3 index 84790ade0..f8405faca 100644 --- a/man/std::numeric_limits::digits.3 +++ b/man/std::numeric_limits::digits.3 @@ -1,44 +1,52 @@ -.TH std::numeric_limits::digits 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::digits 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::digits \- std::numeric_limits::digits + .SH Synopsis static const int digits; \fI(until C++11)\fP static constexpr int digits; \fI(since C++11)\fP The value of std::numeric_limits::digits is the number of digits in base-radix that can be represented by the type T without change. For integer types, this is the - number of bits not counting the sign bit. For floating-point types, this is the - number of digits in the mantissa. + number of bits not counting the sign bit and the padding bits (if any). For + floating-point types, this is the digits of the mantissa (for IEC 559/IEEE 754 + implementations, this is the number of digits stored for the mantissa plus one, + because the mantissa has an implicit leading 1 and binary point). .SH Standard specializations - T value of std::numeric_limits::digits - /* non-specialized */ 0 - bool 1 - char CHAR_BIT - std::numeric_limits::is_signed - signed char CHAR_BIT-1 - unsigned char CHAR_BIT - wchar_t CHAR_BIT*sizeof(wchar_t) - - std::numeric_limits::is_signed - char16_t CHAR_BIT*sizeof(char16_t) - char32_t CHAR_BIT*sizeof(char32_t) - short CHAR_BIT*sizeof(short)-1 - unsigned short CHAR_BIT*sizeof(short) - int CHAR_BIT*sizeof(int)-1 - unsigned int CHAR_BIT*sizeof(int) - long CHAR_BIT*sizeof(long)-1 - unsigned long CHAR_BIT*sizeof(long) - long long CHAR_BIT*sizeof(long long)-1 - unsigned long long CHAR_BIT*sizeof(long long) - float FLT_MANT_DIG - double DBL_MANT_DIG - long double LDBL_MANT_DIG + T value of std::numeric_limits::digits + (assuming no padding bits) + /* non-specialized */ 0 + bool 1 + char CHAR_BIT - std::numeric_limits::is_signed + signed char CHAR_BIT - 1 + unsigned char CHAR_BIT + CHAR_BIT * sizeof(wchar_t) + wchar_t + - std::numeric_limits::is_signed + char8_t \fI(since C++20)\fP CHAR_BIT + char16_t \fI(since C++11)\fP CHAR_BIT * sizeof(char16_t) + char32_t \fI(since C++11)\fP CHAR_BIT * sizeof(char32_t) + short CHAR_BIT * sizeof(short) - 1 + unsigned short CHAR_BIT * sizeof(short) + int CHAR_BIT * sizeof(int) - 1 + unsigned int CHAR_BIT * sizeof(int) + long CHAR_BIT * sizeof(long) - 1 + unsigned long CHAR_BIT * sizeof(long) + long long \fI(since C++11)\fP CHAR_BIT * sizeof(long long) - 1 + unsigned long long \fI(since C++11)\fP CHAR_BIT * sizeof(long long) + float FLT_MANT_DIG + double DBL_MANT_DIG + long double LDBL_MANT_DIG .SH See also radix the radix or integer base used by the representation of the given type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP min_exponent one more than the smallest negative power of the radix that is a valid \fB[static]\fP normalized floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a valid \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::digits10.3 b/man/std::numeric_limits::digits10.3 index f31ca3ba1..29cf57612 100644 --- a/man/std::numeric_limits::digits10.3 +++ b/man/std::numeric_limits::digits10.3 @@ -1,38 +1,45 @@ -.TH std::numeric_limits::digits10 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::digits10 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::digits10 \- std::numeric_limits::digits10 + .SH Synopsis - static const int digits10; \fI(until C++11)\fP - static constexpr int digits10 \fI(since C++11)\fP + static const int digits10; \fI(until C++11)\fP + static constexpr int digits10; \fI(since C++11)\fP The value of std::numeric_limits::digits10 is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many - decimal digits can be converted to a value of type T and back to decimal form, - without change due to rounding or overflow. For base-radix types, it is the value of - digits (digits-1 for floating-point types) multiplied by log + significant decimal digits can be converted to a value of type T and back to decimal + form, without change due to rounding or overflow. For base-radix types, it is the + value of digits() (digits - 1 for floating-point types) multiplied by \\(\\small + \\log_{10}{radix}\\)log 10(radix) and rounded down. .SH Standard specializations - T value of std::numeric_limits::digits10 - /* non-specialized */ 0 - bool 0 - char std::numeric_limits::digits * std::log10\fB(2)\fP - signed char std::numeric_limits::digits * std::log10\fB(2)\fP - unsigned char std::numeric_limits::digits * std::log10\fB(2)\fP - wchar_t std::numeric_limits::digits * std::log10\fB(2)\fP - char16_t std::numeric_limits::digits * std::log10\fB(2)\fP - char32_t std::numeric_limits::digits * std::log10\fB(2)\fP - short std::numeric_limits::digits * std::log10\fB(2)\fP - unsigned short std::numeric_limits::digits * std::log10\fB(2)\fP - int std::numeric_limits::digits * std::log10\fB(2)\fP - unsigned int std::numeric_limits::digits * std::log10\fB(2)\fP - long std::numeric_limits::digits * std::log10\fB(2)\fP - unsigned long std::numeric_limits::digits * std::log10\fB(2)\fP - long long std::numeric_limits::digits * std::log10\fB(2)\fP - unsigned long long std::numeric_limits::digits * - std::log10\fB(2)\fP - float FLT_DIG - double DBL_DIG - long double LDBL_DIG + T value of std::numeric_limits::digits10 + /* non-specialized */ 0 + bool 0 + char std::numeric_limits::digits * std::log10\fB(2)\fP + signed char std::numeric_limits::digits * std::log10\fB(2)\fP + unsigned char std::numeric_limits::digits * std::log10\fB(2)\fP + wchar_t std::numeric_limits::digits * std::log10\fB(2)\fP + char8_t \fI(since C++20)\fP std::numeric_limits::digits * std::log10\fB(2)\fP + char16_t \fI(since C++11)\fP std::numeric_limits::digits * std::log10\fB(2)\fP + char32_t \fI(since C++11)\fP std::numeric_limits::digits * std::log10\fB(2)\fP + short std::numeric_limits::digits * std::log10\fB(2)\fP + unsigned short std::numeric_limits::digits * + std::log10\fB(2)\fP + int std::numeric_limits::digits * std::log10\fB(2)\fP + unsigned int std::numeric_limits::digits * std::log10\fB(2)\fP + long std::numeric_limits::digits * std::log10\fB(2)\fP + unsigned long std::numeric_limits::digits * std::log10\fB(2)\fP + long long \fI(since C++11)\fP std::numeric_limits::digits * std::log10\fB(2)\fP + unsigned long long (since std::numeric_limits::digits * + C++11) std::log10\fB(2)\fP + float FLT_DIG (6 for IEEE float) + double DBL_DIG (15 for IEEE double) + long double LDBL_DIG (18 for 80-bit Intel long double; 33 for IEEE + quadruple) .SH Example @@ -46,18 +53,26 @@ floating-point values with 7 decimal digits do not survive conversion to 32-bit float and back: the smallest positive example is 8.589973e9, which becomes 8.589974e9 after the roundtrip. These rounding errors cannot exceed one bit in the - representation, and digits10 is calculated as (24-1)*std::log10(2), which is 6.92. - Rounding down results in the value 6. + representation, and digits10 is calculated as (24 - 1) * std::log10(2), which is + 6.92. Rounding down results in the value 6. + + Likewise, the 16-digit string 9007199254740993 does not survive text->double->text + roundtrip, becoming 9007199254740992: the 64-bit IEEE 754 type double guarantees + this roundtrip only for 15 decimal digits. .SH See also - radix the radix or integer base used by the representation of the given type - \fB[static]\fP \fI(public static member constant)\fP - digits number of radix digits that can be represented without change - \fB[static]\fP \fI(public static member constant)\fP - min_exponent one more than the smallest negative power of the radix that is a valid - \fB[static]\fP normalized floating-point value - \fI(public static member constant)\fP - max_exponent one more than the largest integer power of the radix that is a valid - \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP + max_digits10 number of decimal digits necessary to differentiate all values of + \fB[static]\fP \fI(C++11)\fP this type + \fI(public static member constant)\fP + radix the radix or integer base used by the representation of the given + \fB[static]\fP type + \fI(public static member constant)\fP + digits number of radix digits that can be represented without change + \fB[static]\fP \fI(public static member constant)\fP + min_exponent one more than the smallest negative power of the radix that is a + \fB[static]\fP valid normalized floating-point value + \fI(public static member constant)\fP + max_exponent one more than the largest integer power of the radix that is a + \fB[static]\fP valid finite floating-point value + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::epsilon.3 b/man/std::numeric_limits::epsilon.3 index bc6a2a38f..0f1e00066 100644 --- a/man/std::numeric_limits::epsilon.3 +++ b/man/std::numeric_limits::epsilon.3 @@ -1,7 +1,10 @@ -.TH std::numeric_limits::epsilon 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::epsilon 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::epsilon \- std::numeric_limits::epsilon + .SH Synopsis - static T epsilon(); \fI(until C++11)\fP - static constexpr T epsilon(); \fI(since C++11)\fP + static T epsilon() throw(); \fI(until C++11)\fP + static constexpr T epsilon() noexcept; \fI(since C++11)\fP Returns the machine epsilon, that is, the difference between 1.0 and the next value representable by the floating-point type T. It is only meaningful if @@ -9,81 +12,102 @@ .SH Return value - T std::numeric_limits::epsilon() - /* non-specialized */ T(); - bool false - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float FLT_EPSILON - double DBL_EPSILON - long double LDBL_EPSILON - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::epsilon() + /* non-specialized */ T() + bool false + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long\fI(since C++11)\fP 0 + float FLT_EPSILON + double DBL_EPSILON + long double LDBL_EPSILON .SH Example - Demonstrates the simplistic use of machine epsilon to compare floating-point values. + Demonstrates the use of machine epsilon to compare floating-point values for + equality: + - // Run this code + #include #include - #include + #include #include #include + #include #include - - template - typename std::enable_if::is_integer, bool>::type - almost_equal(T x, T y, int ulp) + + template + std::enable_if_t::is_integer, bool> + equal_within_ulps(T x, T y, std::size_t n) { - // the machine epsilon has to be scaled to the magnitude of the larger value - // and multiplied by the desired precision in ULPs (units in the last place) - return std::abs(x-y) <= std::numeric_limits::epsilon() - * std::max(std::abs(x), std::abs(y)) - * ulp; + // Since `epsilon()` is the gap size (ULP, unit in the last place) + // of floating-point numbers in interval [1, 2), we can scale it to + // the gap size in interval [2^e, 2^{e+1}), where `e` is the exponent + // of `x` and `y`. + + // If `x` and `y` have different gap sizes (which means they have + // different exponents), we take the smaller one. Taking the bigger + // one is also reasonable, I guess. + const T m = std::min(std::fabs(x), std::fabs(y)); + + // Subnormal numbers have fixed exponent, which is `min_exponent - 1`. + const int exp = m < std::numeric_limits::min() + ? std::numeric_limits::min_exponent - 1 + : std::ilogb(m); + + // We consider `x` and `y` equal if the difference between them is + // within `n` ULPs. + return std::fabs(x - y) <= n * std::ldexp(std::numeric_limits::epsilon(), exp); } + int main() { - double d1 = 0.2; - double d2 = 1 / std::sqrt(5) / std::sqrt(5); - - if(d1 == d2) - std::cout << "d1 == d2\\n"; - else - std::cout << "d1 != d2\\n"; - - if(almost_equal(d1, d2, 2)) - std::cout << "d1 almost equals d2\\n"; - else - std::cout << "d1 does not almost equal d2\\n"; + double x = 0.3; + double y = 0.1 + 0.2; + std::cout << std::hexfloat; + std::cout << "x = " << x << '\\n'; + std::cout << "y = " << y << '\\n'; + std::cout << (x == y ? "x == y" : "x != y") << '\\n'; + for (std::size_t n = 0; n <= 10; ++n) + if (equal_within_ulps(x, y, n)) + { + std::cout << "x equals y within " << n << " ulps" << '\\n'; + break; + } } .SH Output: - d1 != d2 - d1 almost equals d2 + x = 0x1.3333333333333p-2 + y = 0x1.3333333333334p-2 + x != y + x equals y within 1 ulps .SH See also nextafter - nexttoward next representable floating point value towards the given value - \fI(C++11)\fP \fI(function)\fP + nextafterf + nextafterl + nexttoward + nexttowardf + nexttowardl next representable floating-point value towards the given value + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP + \fI(C++11)\fP \fI(C++11)\fP diff --git a/man/std::numeric_limits::has_denorm.3 b/man/std::numeric_limits::has_denorm.3 index 2d2731d29..705005c6b 100644 --- a/man/std::numeric_limits::has_denorm.3 +++ b/man/std::numeric_limits::has_denorm.3 @@ -1,38 +1,43 @@ -.TH std::numeric_limits::has_denorm 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::has_denorm 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::has_denorm \- std::numeric_limits::has_denorm + .SH Synopsis - static const std::float_denorm_style has_denorm \fI(until C++11)\fP - static constexpr std::float_denorm_style has_denorm \fI(since C++11)\fP + static const std::float_denorm_style has_denorm; \fI(until C++11)\fP + static constexpr std::float_denorm_style has_denorm; \fI(since C++11)\fP + (deprecated in C++23) The value of std::numeric_limits::has_denorm identifies the floating-point types that support subnormal values. .SH Standard specializations - T value of std::numeric_limits::has_denorm - /* non-specialized */ std::denorm_absent - bool std::denorm_absent - char std::denorm_absent - signed char std::denorm_absent - unsigned char std::denorm_absent - wchar_t std::denorm_absent - char16_t std::denorm_absent - char32_t std::denorm_absent - short std::denorm_absent - unsigned short std::denorm_absent - int std::denorm_absent - unsigned int std::denorm_absent - long std::denorm_absent - unsigned long std::denorm_absent - long long std::denorm_absent - unsigned long long std::denorm_absent - float usually std::denorm_present - double usually std::denorm_present - long double usually std::denorm_present + T value of std::numeric_limits::has_denorm + /* non-specialized */ std::denorm_absent + bool std::denorm_absent + char std::denorm_absent + signed char std::denorm_absent + unsigned char std::denorm_absent + wchar_t std::denorm_absent + char8_t \fI(since C++20)\fP std::denorm_absent + char16_t \fI(since C++11)\fP std::denorm_absent + char32_t \fI(since C++11)\fP std::denorm_absent + short std::denorm_absent + unsigned short std::denorm_absent + int std::denorm_absent + unsigned int std::denorm_absent + long std::denorm_absent + unsigned long std::denorm_absent + long long \fI(since C++11)\fP std::denorm_absent + unsigned long long \fI(since C++11)\fP std::denorm_absent + float usually std::denorm_present + double usually std::denorm_present + long double usually std::denorm_present .SH See also denorm_min returns the smallest positive subnormal value of the given \fB[static]\fP floating-point type - \fI(public static member function)\fP + \fI(public static member function)\fP float_denorm_style indicates floating-point denormalization modes - \fI(enum)\fP + \fI(enum)\fP diff --git a/man/std::numeric_limits::has_denorm_loss.3 b/man/std::numeric_limits::has_denorm_loss.3 index c6c601a8b..167170062 100644 --- a/man/std::numeric_limits::has_denorm_loss.3 +++ b/man/std::numeric_limits::has_denorm_loss.3 @@ -1,48 +1,60 @@ -.TH std::numeric_limits::has_denorm_loss 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::has_denorm_loss 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::has_denorm_loss \- std::numeric_limits::has_denorm_loss + .SH Synopsis static const bool has_denorm_loss; \fI(until C++11)\fP static constexpr bool has_denorm_loss; \fI(since C++11)\fP + (deprecated in C++23) The value of std::numeric_limits::has_denorm_loss is true for all floating-point - types T capable of distinguishing loss of precision due to denormalization from - other causes of inexact result. + types T that detect loss of precision when creating a subnormal number as + denormalization loss rather than as inexact result (see below). .SH Standard specializations - T value of std::numeric_limits::has_denorm_loss - /* non-specialized */ false - bool false - char false - signed char false - unsigned char false - wchar_t false - char16_t false - char32_t false - short false - unsigned short false - int false - unsigned int false - long false - unsigned long false - long long false - unsigned long long false - float implementation-defined - double implementation-defined - long double implementation-defined + T value of std::numeric_limits::has_denorm_loss + /* non-specialized */ false + bool false + char false + signed char false + unsigned char false + wchar_t false + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short false + unsigned short false + int false + unsigned int false + long false + unsigned long false + long long \fI(since C++11)\fP false + unsigned long long \fI(since C++11)\fP false + float implementation-defined + double implementation-defined + long double implementation-defined .SH Notes - Standard-compliant IEEE 754 floating-point implementations may detect the - floating-point underflow at three predefined moments: + Standard-compliant IEEE 754 floating-point implementations of subnormal numbers are + required to detect the loss of accuracy associated with the creation of such number, + if it occurs, and may do so in one of the two distinct ways: + + 1. Denormalization loss: the delivered result differs from what would have been + computed were exponent range unbounded. + 2. Inexact result: the delivered result differs from what would have been computed + were both exponent range and precision unbounded. - 1) after computation of a result with absolute value smaller than - std::numeric_limits::min(), such implementation detects tinyness before rounding. + No implementation of denormalization loss mechanism exists (accuracy loss is + detected after rounding, as inexact result), and this option was removed in the 2008 + revision of IEEE Std 754. - 2) after rounding of the result to std::numeric_limits::digits bits, if the - result is tiny, such implementation detects tinyness after rounding. + libstdc++, libc++, libCstd, and stlport4 define this constant as false for all + floating-point types. Microsoft Visual Studio defines it as true for all + floating-point types. - 3) if the conversion of the rounded tiny result to subnormal form resulted in the - loss of precision, such implementation detects denorm loss. + As with any floating-point computations, accuracy loss may raise FE_INEXACT. .SH Example @@ -52,10 +64,9 @@ .SH See also tinyness_before identifies floating-point types that detect tinyness before rounding - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP has_denorm identifies the denormalization style used by the floating-point type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP .SH Category: - * Todo no example diff --git a/man/std::numeric_limits::has_infinity.3 b/man/std::numeric_limits::has_infinity.3 index 4c1a89af7..778afdf20 100644 --- a/man/std::numeric_limits::has_infinity.3 +++ b/man/std::numeric_limits::has_infinity.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::has_infinity 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::has_infinity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::has_infinity \- std::numeric_limits::has_infinity + .SH Synopsis static const bool has_infinity; \fI(until C++11)\fP static constexpr bool has_infinity; \fI(since C++11)\fP @@ -10,35 +13,60 @@ .SH Standard specializations - T value of std::numeric_limits::has_infinity - /* non-specialized */ false - bool false - char false - signed char false - unsigned char false - wchar_t false - char16_t false - char32_t false - short false - unsigned short false - int false - unsigned int false - long false - unsigned long false - long long false - unsigned long long false - float usually true - double usually true - long double usually true + T value of std::numeric_limits::has_infinity + /* non-specialized */ false + bool false + char false + signed char false + unsigned char false + wchar_t false + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short false + unsigned short false + int false + unsigned int false + long false + unsigned long false + long long \fI(since C++11)\fP false + unsigned long long \fI(since C++11)\fP false + float usually true + double usually true + long double usually true + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha + << std::numeric_limits::has_infinity << '\\n' + << std::numeric_limits::has_infinity << '\\n' + << std::numeric_limits::has_infinity << '\\n' + << std::numeric_limits::has_infinity << '\\n'; + } + +.SH Possible output: + + false + false + true + true .SH See also infinity returns the positive infinity value of the given floating-point \fB[static]\fP type - \fI(public static member function)\fP + \fI(public static member function)\fP has_quiet_NaN identifies floating-point types that can represent the special \fB[static]\fP value "quiet not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_signaling_NaN identifies floating-point types that can represent the special \fB[static]\fP value "signaling not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::has_quiet_NaN.3 b/man/std::numeric_limits::has_quiet_NaN.3 index 3b00270e6..158eeff43 100644 --- a/man/std::numeric_limits::has_quiet_NaN.3 +++ b/man/std::numeric_limits::has_quiet_NaN.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::has_quiet_NaN 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::has_quiet_NaN 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::has_quiet_NaN \- std::numeric_limits::has_quiet_NaN + .SH Synopsis static const bool has_quiet_NaN; \fI(until C++11)\fP static constexpr bool has_quiet_NaN; \fI(since C++11)\fP @@ -10,34 +13,35 @@ .SH Standard specializations - T value of std::numeric_limits::has_quiet_NaN - /* non-specialized */ false - bool false - char false - signed char false - unsigned char false - wchar_t false - char16_t false - char32_t false - short false - unsigned short false - int false - unsigned int false - long false - unsigned long false - long long false - unsigned long long false - float usually true - double usually true - long double usually true + T value of std::numeric_limits::has_quiet_NaN + /* non-specialized */ false + bool false + char false + signed char false + unsigned char false + wchar_t false + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short false + unsigned short false + int false + unsigned int false + long false + unsigned long false + long long \fI(since C++11)\fP false + unsigned long long \fI(since C++11)\fP false + float usually true + double usually true + long double usually true .SH See also quiet_NaN returns a quiet NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP has_infinity identifies floating-point types that can represent the special \fB[static]\fP value "positive infinity" - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_signaling_NaN identifies floating-point types that can represent the special \fB[static]\fP value "signaling not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::has_signaling_NaN.3 b/man/std::numeric_limits::has_signaling_NaN.3 index 77f18d947..fa1bf1461 100644 --- a/man/std::numeric_limits::has_signaling_NaN.3 +++ b/man/std::numeric_limits::has_signaling_NaN.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::has_signaling_NaN 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::has_signaling_NaN 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::has_signaling_NaN \- std::numeric_limits::has_signaling_NaN + .SH Synopsis static const bool has_signaling_NaN; \fI(until C++11)\fP static constexpr bool has_signaling_NaN; \fI(since C++11)\fP @@ -10,34 +13,35 @@ .SH Standard specializations - T value of std::numeric_limits::has_signaling_NaN - /* non-specialized */ false - bool false - char false - signed char false - unsigned char false - wchar_t false - char16_t false - char32_t false - short false - unsigned short false - int false - unsigned int false - long false - unsigned long false - long long false - unsigned long long false - float usually true - double usually true - long double usually true + T value of std::numeric_limits::has_signaling_NaN + /* non-specialized */ false + bool false + char false + signed char false + unsigned char false + wchar_t false + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short false + unsigned short false + int false + unsigned int false + long false + unsigned long false + long long \fI(since C++11)\fP false + unsigned long long \fI(since C++11)\fP false + float usually true + double usually true + long double usually true .SH See also quiet_NaN returns a quiet NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP has_infinity identifies floating-point types that can represent the special value \fB[static]\fP "positive infinity" - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_quiet_NaN identifies floating-point types that can represent the special value \fB[static]\fP "quiet not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::infinity.3 b/man/std::numeric_limits::infinity.3 index c411d565d..74ce0664e 100644 --- a/man/std::numeric_limits::infinity.3 +++ b/man/std::numeric_limits::infinity.3 @@ -1,7 +1,10 @@ -.TH std::numeric_limits::infinity 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::infinity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::infinity \- std::numeric_limits::infinity + .SH Synopsis - static T infinity(); \fI(until C++11)\fP - static constexpr T infinity(); \fI(since C++11)\fP + static T infinity() throw(); \fI(until C++11)\fP + static constexpr T infinity() noexcept; \fI(since C++11)\fP Returns the special value "positive infinity", as represented by the floating-point type T. Only meaningful if std::numeric_limits::has_infinity == true. In IEEE @@ -11,47 +14,42 @@ .SH Return value - T std::numeric_limits::infinity() - /* non-specialized */ T(); - bool false - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float HUGE_VALF - double HUGE_VAL - long double HUGE_VALL - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::infinity() + /* non-specialized */ T() + bool false + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float HUGE_VALF + double HUGE_VAL + long double HUGE_VALL .SH Example - + // Run this code #include #include + int main() { double max = std::numeric_limits::max(); double inf = std::numeric_limits::infinity(); - - if(inf > max) + + if (inf > max) std::cout << inf << " is greater than " << max << '\\n'; } @@ -63,4 +61,4 @@ has_infinity identifies floating-point types that can represent the special value \fB[static]\fP "positive infinity" - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_bounded.3 b/man/std::numeric_limits::is_bounded.3 index d6af6eef8..cd742c127 100644 --- a/man/std::numeric_limits::is_bounded.3 +++ b/man/std::numeric_limits::is_bounded.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_bounded 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_bounded 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_bounded \- std::numeric_limits::is_bounded + .SH Synopsis static const bool is_bounded; \fI(until C++11)\fP static constexpr bool is_bounded; \fI(since C++11)\fP @@ -6,36 +9,37 @@ The value of std::numeric_limits::is_bounded is true for all arithmetic types T that represent a finite set of values. While all fundamental types are bounded, this constant would be false in a specialization of std::numeric_limits for a - library-provided arbitrary precision arithmetic type + library-provided arbitrary precision arithmetic type. .SH Standard specializations - T value of std::numeric_limits::is_bounded - /* non-specialized */ false - bool true - char true - signed char true - unsigned char true - wchar_t true - char16_t true - char32_t true - short true - unsigned short true - int true - unsigned int true - long true - unsigned long true - long long true - unsigned long long true - float true - double true - long double true + T value of std::numeric_limits::is_bounded + /* non-specialized */ false + bool true + char true + signed char true + unsigned char true + wchar_t true + char8_t \fI(since C++20)\fP true + char16_t \fI(since C++11)\fP true + char32_t \fI(since C++11)\fP true + short true + unsigned short true + int true + unsigned int true + long true + unsigned long true + long long \fI(since C++11)\fP true + unsigned long long \fI(since C++11)\fP true + float true + double true + long double true .SH See also is_integer identifies integer types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_signed identifies signed types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_exact identifies exact types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_exact.3 b/man/std::numeric_limits::is_exact.3 index 9f0a6fada..c42976c9f 100644 --- a/man/std::numeric_limits::is_exact.3 +++ b/man/std::numeric_limits::is_exact.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_exact 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_exact 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_exact \- std::numeric_limits::is_exact + .SH Synopsis static const bool is_exact; \fI(until C++11)\fP static constexpr bool is_exact; \fI(since C++11)\fP @@ -8,38 +11,39 @@ .SH Standard specializations - T value of std::numeric_limits::is_exact - /* non-specialized */ false - bool true - char true - signed char true - unsigned char true - wchar_t true - char16_t true - char32_t true - short true - unsigned short true - int true - unsigned int true - long true - unsigned long true - long long true - unsigned long long true - float false - double false - long double false + T value of std::numeric_limits::is_exact + /* non-specialized */ false + bool true + char true + signed char true + unsigned char true + wchar_t true + char8_t \fI(since C++20)\fP true + char16_t \fI(since C++11)\fP true + char32_t \fI(since C++11)\fP true + short true + unsigned short true + int true + unsigned int true + long true + unsigned long true + long long \fI(since C++11)\fP true + unsigned long long \fI(since C++11)\fP true + float false + double false + long double false .SH Notes - While all fundamental types T for which std::numeric_limits::is_exact==true are - integer types, a library may define exact types that aren't integers, e.g. a - rational arithmetics type representing fractions. + While all fundamental types T for which std::numeric_limits::is_exact == true are + integer types, a library may define exact types that are not integers, e.g. a + rational arithmetic type representing fractions. .SH See also is_integer identifies integer types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_signed identifies signed types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_bounded identifies types that represent a finite set of values - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_iec559.3 b/man/std::numeric_limits::is_iec559.3 index 8eec9e6c2..a8bbac279 100644 --- a/man/std::numeric_limits::is_iec559.3 +++ b/man/std::numeric_limits::is_iec559.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_iec559 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_iec559 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_iec559 \- std::numeric_limits::is_iec559 + .SH Synopsis static const bool is_iec559; \fI(until C++11)\fP static constexpr bool is_iec559; \fI(since C++11)\fP @@ -11,35 +14,36 @@ .SH Standard specializations - T value of std::numeric_limits::is_iec559 - /* non-specialized */ false - bool false - char false - signed char false - unsigned char false - wchar_t false - char16_t false - char32_t false - short false - unsigned short false - int false - unsigned int false - long false - unsigned long false - long long false - unsigned long long false - float usually true - double usually true - long double usually true + T value of std::numeric_limits::is_iec559 + /* non-specialized */ false + bool false + char false + signed char false + unsigned char false + wchar_t false + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short false + unsigned short false + int false + unsigned int false + long false + unsigned long false + long long \fI(since C++11)\fP false + unsigned long long \fI(since C++11)\fP false + float usually true + double usually true + long double usually true .SH See also has_infinity identifies floating-point types that can represent the special \fB[static]\fP value "positive infinity" - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_quiet_NaN identifies floating-point types that can represent the special \fB[static]\fP value "quiet not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_signaling_NaN identifies floating-point types that can represent the special \fB[static]\fP value "signaling not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_integer.3 b/man/std::numeric_limits::is_integer.3 index 472c3a5ec..5107cf37f 100644 --- a/man/std::numeric_limits::is_integer.3 +++ b/man/std::numeric_limits::is_integer.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_integer 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_integer 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_integer \- std::numeric_limits::is_integer + .SH Synopsis static const bool is_integer; \fI(until C++11)\fP static constexpr bool is_integer; \fI(since C++11)\fP @@ -8,34 +11,60 @@ .SH Standard specializations - T value of std::numeric_limits::is_integer - /* non-specialized */ false - bool true - char true - signed char true - unsigned char true - wchar_t true - char16_t true - char32_t true - short true - unsigned short true - int true - unsigned int true - long true - unsigned long true - long long true - unsigned long long true - float false - double false - long double false + T value of std::numeric_limits::is_integer + /* non-specialized */ false + bool true + char true + signed char true + unsigned char true + wchar_t true + char8_t \fI(since C++20)\fP true + char16_t \fI(since C++11)\fP true + char32_t \fI(since C++11)\fP true + short true + unsigned short true + int true + unsigned int true + long true + unsigned long true + long long \fI(since C++11)\fP true + unsigned long long \fI(since C++11)\fP true + float false + double false + long double false + +.SH Example + + +// Run this code + + #include + #include + #include + + static_assert + ( + std::numeric_limits::is_integer + && std::numeric_limits::is_integer + && std::numeric_limits::is_integer + && std::numeric_limits::is_integer + && std::numeric_limits::is_integer + && !std::numeric_limits::is_integer + && !std::numeric_limits::is_integer + && !std::numeric_limits::is_integer + && !std::numeric_limits::is_integer + && !std::numeric_limits::is_integer // P0315R4 + ); + + int main() {} .SH See also - is_integral checks if a type is integral type - \fI(C++11)\fP \fI(class template)\fP + is_integral checks if a type is an integral type + \fI(C++11)\fP \fI(class template)\fP is_signed identifies signed types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_exact identifies exact types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_bounded identifies types that represent a finite set of values - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_modulo.3 b/man/std::numeric_limits::is_modulo.3 index 3548847a2..62a9b7738 100644 --- a/man/std::numeric_limits::is_modulo.3 +++ b/man/std::numeric_limits::is_modulo.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_modulo 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_modulo 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_modulo \- std::numeric_limits::is_modulo + .SH Synopsis static const bool is_modulo; \fI(until C++11)\fP static constexpr bool is_modulo; \fI(since C++11)\fP @@ -7,66 +10,66 @@ that handle overflows with modulo arithmetic, that is, if the result of addition, subtraction, multiplication, or division of this type would fall outside the range [min(), max()], the value returned by such operation differs from the expected value - by a multiple of max()-min()+1. + by a multiple of max() - min() + 1. + + is_modulo is false for signed integer types, unless the implementation defines + signed integer overflow to wrap. .SH Standard specializations - T value of std::numeric_limits::is_modulo - /* non-specialized */ false - bool false - char implementation-defined - signed char implementation-defined - unsigned char true - wchar_t implementation-defined - char16_t implementation-defined - char32_t implementation-defined - short implementation-defined - unsigned short true - int implementation-defined - unsigned int true - long implementation-defined - unsigned long true - long long implementation-defined - unsigned long long true - float false - double false - long double false + T value of std::numeric_limits::is_modulo + /* non-specialized */ false + bool false + char implementation-defined + signed char implementation-defined + unsigned char true + wchar_t implementation-defined + char8_t \fI(since C++20)\fP true + char16_t \fI(since C++11)\fP true + char32_t \fI(since C++11)\fP true + short implementation-defined + unsigned short true + int implementation-defined + unsigned int true + long implementation-defined + unsigned long true + long long \fI(C++11)\fP implementation-defined + unsigned long long \fI(C++11)\fP true + float false + double false + long double false .SH Notes - Although the C++11 standard still says "On most machines, this is true for signed - integers.", the exact wording changed from C++03 to C++11 in such a way that the - true value is no longer compatible with undefined behavior on signed integer - overflow (it changed from "possible" to a strict requirement). Because of that, the - implementations that rely on signed overflow being undefined (for optimization - opportunities) now set is_modulo to false for signed integers. See for example GCC - PR 22200. + The standard said "On most machines, this is true for signed integers." before the + resolution of LWG issue 2422. See GCC PR 22200 for a related discussion. .SH Example - Demonstrates the behavior of modulo types + Demonstrates the behavior of modulo types: + - // Run this code #include #include #include - + template typename std::enable_if::is_modulo>::type check_overflow() { - std::cout << "\\nmax value is " << std::numeric_limits::max() << '\\n' + std::cout << "max value is " << std::numeric_limits::max() << '\\n' << "min value is " << std::numeric_limits::min() << '\\n' << "max value + 1 is " << std::numeric_limits::max()+1 << '\\n'; } - + int main() { check_overflow(); + std::cout << '\\n'; check_overflow(); - // check_overflow(); // compile-time error, not a modulo type + // check_overflow(); // compile-time error, not a modulo type } .SH Possible output: @@ -74,16 +77,38 @@ max value is 2147483647 min value is -2147483648 max value + 1 is -2147483648 - + max value is 18446744073709551615 min value is 0 max value + 1 is 0 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the definition of "handle + LWG 612 C++98 overflows provided a + with modulo arithmetic" was better definition + poor^[1] + is_modulo was required to be required to be false for signed + LWG 2422 C++98 true for integer types + signed integer types on most unless signed integer overflow is + machines defined to wrap + + 1. ↑ The definition is "adding two positive numbers can have a result that wraps + around to a third number that is less". It has the following problems: + * It does not define the wrapped value. + * It does not state whether result is repeatable. + * It does not require that doing addition, subtraction and other operations + on all values have defined behavior. + .SH See also is_integer identifies integer types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_iec559 identifies the IEC 559/IEEE 754 floating-point types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_exact identifies exact types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_signed.3 b/man/std::numeric_limits::is_signed.3 index b102c715b..b1b433bf7 100644 --- a/man/std::numeric_limits::is_signed.3 +++ b/man/std::numeric_limits::is_signed.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_signed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_signed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_signed \- std::numeric_limits::is_signed + .SH Synopsis static const bool is_signed; \fI(until C++11)\fP static constexpr bool is_signed; \fI(since C++11)\fP @@ -9,34 +12,81 @@ .SH Standard specializations - T value of std::numeric_limits::is_signed - /* non-specialized */ false - bool false - char implementation-defined - signed char true - unsigned char false - wchar_t implementation-defined - char16_t false - char32_t false - short true - unsigned short false - int true - unsigned int false - long true - unsigned long false - long long true - unsigned long long false - float true - double true - long double true + T value of std::numeric_limits::is_signed + /* non-specialized */ false + bool false + char implementation-defined + signed char true + unsigned char false + wchar_t implementation-defined + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short true + unsigned short false + int true + unsigned int false + long true + unsigned long false + long long \fI(since C++11)\fP true + unsigned long long \fI(since C++11)\fP false + float true + double true + long double true + +.SH Example + + +// Run this code + + #include + #include + #include + + template + struct test + { + test(const char* name, int w = 15) + { + std::cout + << std::left << std::setw(w) + << (std::numeric_limits::is_specialized ? name : "non-specialized") + << " : " + << (std::numeric_limits::is_signed ? "" : "un") << "signed\\n"; + } + }; + + int main() + { + test{"bool"}; + test{"char"}; + test{"wchar_t"}; + test{"char16_t"}; + test{"char32_t"}; + test{"float"}; + struct delusion{}; + test{"delusion"}; + test{"decltype(42)"}; + } + +.SH Possible output: + + bool : unsigned + char : signed + wchar_t : signed + char16_t : unsigned + char32_t : unsigned + float : signed + non-specialized : unsigned + decltype\fB(42)\fP : signed .SH See also - is_signed checks if a type is signed integer type + is_signed checks if a type is a signed arithmetic type \fI(C++11)\fP \fI(class template)\fP is_integer identifies integer types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_exact identifies exact types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_bounded identifies types that represent a finite set of values - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::is_specialized.3 b/man/std::numeric_limits::is_specialized.3 index 1b3b73e19..62601ea20 100644 --- a/man/std::numeric_limits::is_specialized.3 +++ b/man/std::numeric_limits::is_specialized.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::is_specialized 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::is_specialized 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::is_specialized \- std::numeric_limits::is_specialized + .SH Synopsis static const bool is_specialized; \fI(until C++11)\fP static constexpr bool is_specialized; \fI(since C++11)\fP @@ -8,34 +11,62 @@ .SH Standard specializations - T value of std::numeric_limits::is_specialized - /* non-specialized */ false - bool true - char true - signed char true - unsigned char true - wchar_t true - char16_t true - char32_t true - short true - unsigned short true - int true - unsigned int true - long true - unsigned long true - long long true - unsigned long long true - float true - double true - long double true + T value of std::numeric_limits::is_specialized + /* non-specialized */ false + bool true + char true + signed char true + unsigned char true + wchar_t true + char8_t \fI(since C++20)\fP true + char16_t \fI(since C++11)\fP true + char32_t \fI(since C++11)\fP true + short true + unsigned short true + int true + unsigned int true + long true + unsigned long true + long long \fI(since C++11)\fP true + unsigned long long \fI(since C++11)\fP true + float true + double true + long double true + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + enum E{}; + + std::cout << std::boolalpha + << std::numeric_limits::is_specialized << '\\n' + << std::numeric_limits::is_specialized << '\\n' + << std::numeric_limits::is_specialized << '\\n' + << std::numeric_limits::is_specialized << '\\n'; + } + +.SH Possible output: + + true + true + false + false .SH See also is_integer identifies integer types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_iec559 identifies the IEC 559/IEEE 754 floating-point types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_exact identifies exact types - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP is_bounded identifies types that represent a finite set of values - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::lowest.3 b/man/std::numeric_limits::lowest.3 index c2d04b8e6..e3d0652a6 100644 --- a/man/std::numeric_limits::lowest.3 +++ b/man/std::numeric_limits::lowest.3 @@ -1,6 +1,9 @@ -.TH std::numeric_limits::lowest 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::lowest 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::lowest \- std::numeric_limits::lowest + .SH Synopsis - static constexpr T lowest() \fI(since C++11)\fP + static constexpr T lowest() noexcept; \fI(since C++11)\fP Returns the lowest finite value representable by the numeric type T, that is, a finite value x such that there is no other finite value y where y < x. This is @@ -10,12 +13,13 @@ .SH Return value T std::numeric_limits::lowest() - /* non-specialized */ T(); + /* non-specialized */ T() bool false char CHAR_MIN signed char SCHAR_MIN unsigned char 0 wchar_t WCHAR_MIN + char8_t \fI(since C++20)\fP 0 char16_t 0 char32_t 0 short SHRT_MIN @@ -32,44 +36,48 @@ .SH Notes - While it's not true for fundamental C++ floating-poing types, a third-party - floating-point type T may exist such that std::numeric_limits::lowest() != - -std::numeric_limits::max(). - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + For every standard C++ floating-point type T std::numeric_limits::lowest() == + -std::numeric_limits::max(), but this does not necessarily have to be the case + for any third-party specialization. .SH Example - Demonstrates min, max, and lowest for floating-point types + Demonstrates min(), max(), and lowest() for floating-point types: + - // Run this code - #include #include + #include + #include + + template + void print_twice(std::string_view type, T value) + { + std::cout << '\\t' << type << ": " + << std::defaultfloat << value << " or " + << std::hexfloat << value << '\\n'; + } + int main() { - - std::cout << "std::numeric_limits::min():\\n" - << "\\tfloat: " << std::numeric_limits::min() - << " or " << std::hexfloat << std::numeric_limits::min() << '\\n' - << "\\tdouble: " << std::defaultfloat << std::numeric_limits::min() - << " or " << std::hexfloat << std::numeric_limits::min() << '\\n'; - std::cout << "std::numeric_limits::lowest():\\n" - << "\\tfloat: " << std::defaultfloat << std::numeric_limits::lowest() - << " or " << std::hexfloat << std::numeric_limits::lowest() << '\\n' - << "\\tdouble: " << std::defaultfloat << std::numeric_limits::lowest() - << " or " << std::hexfloat << std::numeric_limits::lowest() << '\\n'; - std::cout << "std::numeric_limits::max():\\n" - << "\\tfloat: " << std::defaultfloat << std::numeric_limits::max() - << " or " << std::hexfloat << std::numeric_limits::max() << '\\n' - << "\\tdouble: " << std::defaultfloat << std::numeric_limits::max() - << " or " << std::hexfloat << std::numeric_limits::max() << '\\n'; + // min() + std::cout << "std::numeric_limits::min():\\n"; + print_twice("float", std::numeric_limits::min()); + print_twice("double", std::numeric_limits::min()); + print_twice("long double", std::numeric_limits::min()); + + // lowest() + std::cout << "std::numeric_limits::lowest():\\n"; + print_twice("float", std::numeric_limits::lowest()); + print_twice("double", std::numeric_limits::lowest()); + print_twice("long double", std::numeric_limits::lowest()); + + // max() + std::cout << "std::numeric_limits::max():\\n"; + print_twice("float", std::numeric_limits::max()); + print_twice("double", std::numeric_limits::max()); + print_twice("long double", std::numeric_limits::max()); } .SH Output: @@ -77,19 +85,22 @@ std::numeric_limits::min(): float: 1.17549e-38 or 0x1p-126 double: 2.22507e-308 or 0x1p-1022 + long double: 3.3621e-4932 or 0x8p-16385 std::numeric_limits::lowest(): float: -3.40282e+38 or -0x1.fffffep+127 double: -1.79769e+308 or -0x1.fffffffffffffp+1023 + long double: -1.18973e+4932 or -0xf.fffffffffffffffp+16380 std::numeric_limits::max(): float: 3.40282e+38 or 0x1.fffffep+127 double: 1.79769e+308 or 0x1.fffffffffffffp+1023 + long double: 1.18973e+4932 or 0xf.fffffffffffffffp+16380 .SH See also min returns the smallest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP denorm_min returns the smallest positive subnormal value of the given floating-point \fB[static]\fP type - \fI(public static member function)\fP + \fI(public static member function)\fP max returns the largest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::numeric_limits::max.3 b/man/std::numeric_limits::max.3 index d4168e9ea..39077ae78 100644 --- a/man/std::numeric_limits::max.3 +++ b/man/std::numeric_limits::max.3 @@ -1,80 +1,101 @@ -.TH std::numeric_limits::max 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::max 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::max \- std::numeric_limits::max + .SH Synopsis - static T max(); \fI(until C++11)\fP - static constexpr T max(); \fI(since C++11)\fP + Defined in header + static T max() throw(); \fI(until C++11)\fP + static constexpr T max() noexcept; \fI(since C++11)\fP Returns the maximum finite value representable by the numeric type T. Meaningful for all bounded types. .SH Return value - T std::numeric_limits::max() - /* non-specialized */ T(); - bool true - char CHAR_MAX - signed char SCHAR_MAX - unsigned char UCHAR_MAX - wchar_t WCHAR_MAX - char16_t UINT_LEAST16_MAX - char32_t UINT_LEAST32_MAX - short SHRT_MAX - unsigned short USHRT_MAX - int INT_MAX - unsigned int UINT_MAX - long LONG_MAX - unsigned long ULONG_MAX - long long LLONG_MAX - unsigned long long ULLONG_MAX - float FLT_MAX - double DBL_MAX - long double LDBL_MAX - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::max() + /* non-specialized */ T() + bool true + char CHAR_MAX + signed char SCHAR_MAX + unsigned char UCHAR_MAX + wchar_t WCHAR_MAX + char8_t \fI(since C++20)\fP UCHAR_MAX + char16_t \fI(since C++11)\fP UINT_LEAST16_MAX + char32_t \fI(since C++11)\fP UINT_LEAST32_MAX + short SHRT_MAX + unsigned short USHRT_MAX + int INT_MAX + unsigned int UINT_MAX + long LONG_MAX + unsigned long ULONG_MAX + long long \fI(since C++11)\fP LLONG_MAX + unsigned long long \fI(since C++11)\fP ULLONG_MAX + float FLT_MAX + double DBL_MAX + long double LDBL_MAX .SH Example Demonstrates the use of max() with some fundamental types and some standard library - typedefs (the output is system-specific) + typedefs (the output is system-specific): + - // Run this code - #include #include #include + #include + #include + #include + + template + void print_max_twice(std::string_view type) + { + constexpr T max_value {std::numeric_limits::max()}; + + std::cout << type << ": "; + if constexpr (std::is_floating_point_v) + std::cout << std::defaultfloat << max_value << " or " + << std::hexfloat << max_value << '\\n'; + else + std::cout << std::dec << static_cast(max_value) << " or " + << std::hex << static_cast(max_value) << '\\n'; + } + int main() { - std::cout << "short: " << std::dec << std::numeric_limits::max() - << " or " << std::hex << std::showbase << std::numeric_limits::max() << '\\n' - << "int: " << std::dec << std::numeric_limits::max() - << " or " << std::hex << std::numeric_limits::max() << '\\n' << std::dec - << "streamsize: " << std::dec << std::numeric_limits::max() - << " or " << std::hex << std::numeric_limits::max() << '\\n' - << "size_t: " << std::dec << std::numeric_limits::max() - << " or " << std::hex << std::numeric_limits::max() << '\\n' - << "float: " << std::numeric_limits::max() - << " or " << std::hexfloat << std::numeric_limits::max() << '\\n' - << "double: " << std::defaultfloat << std::numeric_limits::max() - << " or " << std::hexfloat << std::numeric_limits::max() << '\\n'; + std::cout << std::showbase; + + print_max_twice("bool"); + print_max_twice("short"); + print_max_twice("int"); + print_max_twice("streamsize"); + print_max_twice("size_t"); + print_max_twice("char"); + print_max_twice("char16_t"); + print_max_twice("wchar_t"); + print_max_twice("float"); + print_max_twice("double"); + print_max_twice("long double"); } -.SH Output: +.SH Possible output: + bool: 1 or 0x1 short: 32767 or 0x7fff int: 2147483647 or 0x7fffffff - size_t: 18446744073709551615 or 0xffffffffffffffff streamsize: 9223372036854775807 or 0x7fffffffffffffff + size_t: 18446744073709551615 or 0xffffffffffffffff + char: 127 or 0x7f + char16_t: 65535 or 0xffff + wchar_t: 2147483647 or 0x7fffffff float: 3.40282e+38 or 0x1.fffffep+127 double: 1.79769e+308 or 0x1.fffffffffffffp+1023 + long double: 1.18973e+4932 or 0xf.fffffffffffffffp+16380 .SH See also lowest returns the lowest finite value of the given type - \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP min returns the smallest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::numeric_limits::max_digits10.3 b/man/std::numeric_limits::max_digits10.3 index 49837fccb..7f5449c7a 100644 --- a/man/std::numeric_limits::max_digits10.3 +++ b/man/std::numeric_limits::max_digits10.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::max_digits10 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::max_digits10 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::max_digits10 \- std::numeric_limits::max_digits10 + .SH Synopsis static constexpr int max_digits10 \fI(since C++11)\fP @@ -9,13 +12,14 @@ .SH Standard specializations - T value of std::numeric_limits::max_digits10 + T Value of std::numeric_limits::max_digits10 /* non-specialized */ 0 bool 0 char 0 signed char 0 unsigned char 0 wchar_t 0 + char8_t \fI(since C++20)\fP 0 char16_t 0 char32_t 0 short 0 @@ -26,12 +30,15 @@ unsigned long 0 long long 0 unsigned long long 0 - float std::floor(std::numeric_limits::digits * std::log10\fB(2)\fP - + 2) - double std::floor(std::numeric_limits::digits * std::log10\fB(2)\fP - + 2) - long double std::floor(std::numeric_limits::digits * - std::log10\fB(2)\fP + 2) + FLT_DECIMAL_DIG or + float std::ceil(std::numeric_limits::digits * std::log10\fB(2)\fP + + 1) + DBL_DECIMAL_DIG or + double std::ceil(std::numeric_limits::digits * std::log10\fB(2)\fP + + 1) + DECIMAL_DIG or LDBL_DECIMAL_DIG or + long double std::ceil(std::numeric_limits::digits * + std::log10\fB(2)\fP + 1) .SH Notes @@ -41,17 +48,76 @@ the intermediate text representation is not exact. It may take over a hundred decimal digits to represent the precise value of a float in decimal notation. +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + + int main() + { + float value = 10.0000086; + + constexpr auto digits10 = std::numeric_limits::digits10; + constexpr auto max_digits10 = std::numeric_limits::max_digits10; + constexpr auto submax_digits10 = max_digits10 - 1; + + std::cout << "float:\\n" + " digits10 is " << digits10 << " digits\\n" + " max_digits10 is " << max_digits10 << " digits\\n" + "submax_digits10 is " << submax_digits10 << " digits\\n\\n"; + + const auto original_precision = std::cout.precision(); + for (auto i = 0; i < 5; ++i) + { + std::cout + << " max_digits10: " << std::setprecision(max_digits10) << value << "\\n" + "submax_digits10: " << std::setprecision(submax_digits10) << value + << "\\n\\n"; + + value = std::nextafter(value, std::numeric_limits::max()); + } + std::cout.precision(original_precision); + } + +.SH Output: + + float: + digits10 is 6 digits + max_digits10 is 9 digits + submax_digits10 is 8 digits + + max_digits10: 10.0000086 + submax_digits10: 10.000009 + + max_digits10: 10.0000095 + submax_digits10: 10.00001 + + max_digits10: 10.0000105 + submax_digits10: 10.00001 + + max_digits10: 10.0000114 + submax_digits10: 10.000011 + + max_digits10: 10.0000124 + submax_digits10: 10.000012 + .SH See also radix the radix or integer base used by the representation of the given type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP digits number of radix digits that can be represented without change - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP digits10 number of decimal digits that can be represented without change - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP min_exponent one more than the smallest negative power of the radix that is a valid \fB[static]\fP normalized floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a valid \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::max_exponent.3 b/man/std::numeric_limits::max_exponent.3 index bdbad6293..b1790b385 100644 --- a/man/std::numeric_limits::max_exponent.3 +++ b/man/std::numeric_limits::max_exponent.3 @@ -1,50 +1,56 @@ -.TH std::numeric_limits::max_exponent 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::max_exponent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::max_exponent \- std::numeric_limits::max_exponent + .SH Synopsis static const int max_exponent; \fI(until C++11)\fP static constexpr int max_exponent; \fI(since C++11)\fP The value of std::numeric_limits::max_exponent is the largest positive number n - such that 2n-1 - is a representable finite value of the floating-point type T. + such that \\(\\scriptsize r^{n-1}\\)rn-1 + , where r is std::numeric_limits::radix, is a representable finite value of the + floating-point type T. .SH Standard specializations - T value of std::numeric_limits::max_exponent - /* non-specialized */ 0 - bool 0 - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float FLT_MAX_EXP - double DBL_MAX_EXP - long double LDBL_MAX_EXP + T value of std::numeric_limits::max_exponent + /* non-specialized */ 0 + bool 0 + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float FLT_MAX_EXP + double DBL_MAX_EXP + long double LDBL_MAX_EXP .SH Example Demonstrates the relationships of max_exponent, max_exponent10, and max() for the type float: - + // Run this code #include #include + int main() { std::cout << "max() = " << std::numeric_limits::max() << '\\n' << "max_exponent10 = " << std::numeric_limits::max_exponent10 << '\\n' - << std::hexfloat + << std::hexfloat << '\\n' << "max() = " << std::numeric_limits::max() << '\\n' << "max_exponent = " << std::numeric_limits::max_exponent << '\\n'; } @@ -53,6 +59,7 @@ max() = 3.40282e+38 max_exponent10 = 38 + max() = 0x1.fffffep+127 max_exponent = 128 @@ -60,10 +67,10 @@ min_exponent10 the smallest negative power of ten that is a valid normalized \fB[static]\fP floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP min_exponent one more than the smallest negative power of the radix that is a \fB[static]\fP valid normalized floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent10 the largest integer power of 10 that is a valid finite floating-point \fB[static]\fP value - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::max_exponent10.3 b/man/std::numeric_limits::max_exponent10.3 index 293ab846b..1c18f5016 100644 --- a/man/std::numeric_limits::max_exponent10.3 +++ b/man/std::numeric_limits::max_exponent10.3 @@ -1,49 +1,55 @@ -.TH std::numeric_limits::max_exponent10 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::max_exponent10 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::max_exponent10 \- std::numeric_limits::max_exponent10 + .SH Synopsis static const int max_exponent10; \fI(until C++11)\fP static constexpr int max_exponent10; \fI(since C++11)\fP The value of std::numeric_limits::max_exponent10 is the largest positive number n - such that 10n + such that \\(\\scriptsize 10^n\\)10n is a representable finite value of the floating-point type T. .SH Standard specializations - T value of std::numeric_limits::max_exponent10 - /* non-specialized */ 0 - bool 0 - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float FLT_MAX_10_EXP - double DBL_MAX_10_EXP - long double LDBL_MAX_10_EXP + T value of std::numeric_limits::max_exponent10 + /* non-specialized */ 0 + bool 0 + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float FLT_MAX_10_EXP + double DBL_MAX_10_EXP + long double LDBL_MAX_10_EXP .SH Example Demonstrates the relationships of max_exponent, max_exponent10, and max() for the type float: - + // Run this code #include + #include + int main() { std::cout << "max() = " << std::numeric_limits::max() << '\\n' << "max_exponent10 = " << std::numeric_limits::max_exponent10 << '\\n' - << std::hexfloat + << std::hexfloat << '\\n' << "max() = " << std::numeric_limits::max() << '\\n' << "max_exponent = " << std::numeric_limits::max_exponent << '\\n'; } @@ -52,17 +58,18 @@ max() = 3.40282e+38 max_exponent10 = 38 + max() = 0x1.fffffep+127 max_exponent = 128 .SH See also - min_exponent10 the smallest negative power of ten that is a valid normalized - \fB[static]\fP floating-point value - \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a valid \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP - max_exponent10 the largest integer power of 10 that is a valid finite floating-point - \fB[static]\fP value - \fI(public static member constant)\fP + \fI(public static member constant)\fP + min_exponent one more than the smallest negative power of the radix that is a + \fB[static]\fP valid normalized floating-point value + \fI(public static member constant)\fP + min_exponent10 the smallest negative power of ten that is a valid normalized + \fB[static]\fP floating-point value + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::min.3 b/man/std::numeric_limits::min.3 index 658c4e1dd..d441c75fb 100644 --- a/man/std::numeric_limits::min.3 +++ b/man/std::numeric_limits::min.3 @@ -1,94 +1,110 @@ -.TH std::numeric_limits::min 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::min 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::min \- std::numeric_limits::min + .SH Synopsis - static T min(); \fI(until C++11)\fP - static constexpr T min(); \fI(since C++11)\fP + Defined in header + static T min() throw(); \fI(until C++11)\fP + static constexpr T min() noexcept; \fI(since C++11)\fP Returns the minimum finite value representable by the numeric type T. - For floating-point types with denormalization, min returns the minimum positive + For floating-point types with denormalization, min() returns the minimum positive normalized value. Note that this behavior may be unexpected, especially when - compared to the behavior of min for integral types. To find the value that has no - values less than it, use numeric_limits::lowest. + compared to the behavior of min() for integral types. + To find the value that has no values less than it, use lowest(). + \fI(since C++11)\fP - min is only meaningful for bounded types and for unbounded unsigned types, that is, - types that represent an infinite set of negative values have no meaningful minimum. + min() is only meaningful for bounded types and for unbounded unsigned types, that + is, types that represent an infinite set of negative values have no meaningful + minimum. .SH Return value - T std::numeric_limits::min() - /* non-specialized */ T(); - bool false - char CHAR_MIN - signed char SCHAR_MIN - unsigned char 0 - wchar_t WCHAR_MIN - char16_t 0 - char32_t 0 - short SHRT_MIN - unsigned short 0 - int INT_MIN - unsigned int 0 - long LONG_MIN - unsigned long 0 - long long LLONG_MIN - unsigned long long 0 - float FLT_MIN - double DBL_MIN - long double LDBL_MIN - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::min() + /* non-specialized */ T() + bool false + char CHAR_MIN + signed char SCHAR_MIN + unsigned char 0 + wchar_t WCHAR_MIN + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short SHRT_MIN + unsigned short 0 + int INT_MIN + unsigned int 0 + long LONG_MIN + unsigned long 0 + long long \fI(since C++11)\fP LLONG_MIN + unsigned long long \fI(since C++11)\fP 0 + float FLT_MIN + double DBL_MIN + long double LDBL_MIN .SH Example Demonstrates the use with typedef types, and the difference in the sign of the - result between integer and floating-point types + result between integer and floating-point types: + - // Run this code - #include #include + #include #include - - int main() + #include + + template + void print_one(std::string_view type_name) { + constexpr T min = std::numeric_limits::min(); std::cout - << "short: " << std::dec << std::numeric_limits::min() - << " or " << std::hex << std::showbase - << std::numeric_limits::min() << '\\n' - - << "int: " << std::dec << std::numeric_limits::min() << std::showbase - << " or " << std::hex << std::numeric_limits::min() << '\\n' << std::dec - - << "ptrdiff_t: " << std::numeric_limits::min() << std::showbase - << " or " << std::hex << std::numeric_limits::min() << '\\n' - - << "float: " << std::numeric_limits::min() - << " or " << std::hexfloat << std::numeric_limits::min() << '\\n' - - << "double: " << std::defaultfloat << std::numeric_limits::min() - << " or " << std::hexfloat << std::numeric_limits::min() << '\\n'; + << std::dec << std::defaultfloat << std::setw(14) << type_name + << " (" << std::setw(2) << sizeof(T) << " bytes): " << min; + + if constexpr (min != 0) + std::cout << " or " << std::showbase << std::hex << std::hexfloat << min; + + std::cout << '\\n'; + } + + #define SHOW(T) print_one(#T) + + int main() + { + SHOW(bool); + SHOW(short); + SHOW(unsigned short); + SHOW(signed); + SHOW(unsigned); + SHOW(std::ptrdiff_t); + SHOW(std::size_t); + SHOW(float); + SHOW(double); + SHOW(long double); } .SH Possible output: - short: -32768 or 0x8000 - int: -2147483648 or 0x80000000 - ptrdiff_t: -9223372036854775808 or 0x8000000000000000 - float: 1.17549e-38 or 0x1p-126 - double: 2.22507e-308 or 0x1p-1022 + bool ( 1 bytes): 0 + short ( 2 bytes): -32768 or 0x8000 + unsigned short ( 2 bytes): 0 + signed ( 4 bytes): -2147483648 or 0x80000000 + unsigned ( 4 bytes): 0 + std::ptrdiff_t ( 8 bytes): -9223372036854775808 or 0x8000000000000000 + std::size_t ( 8 bytes): 0 + float ( 4 bytes): 1.17549e-38 or 0x1p-126 + double ( 8 bytes): 2.22507e-308 or 0x1p-1022 + long double (16 bytes): 3.3621e-4932 or 0x8p-16385 .SH See also lowest returns the lowest finite value of the given type - \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP + \fB[static]\fP \fI(C++11)\fP \fI(public static member function)\fP denorm_min returns the smallest positive subnormal value of the given \fB[static]\fP floating-point type - \fI(public static member function)\fP + \fI(public static member function)\fP max returns the largest finite value of the given type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP diff --git a/man/std::numeric_limits::min_exponent.3 b/man/std::numeric_limits::min_exponent.3 index fcab6e57e..9054ee202 100644 --- a/man/std::numeric_limits::min_exponent.3 +++ b/man/std::numeric_limits::min_exponent.3 @@ -1,50 +1,56 @@ -.TH std::numeric_limits::min_exponent 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::min_exponent 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::min_exponent \- std::numeric_limits::min_exponent + .SH Synopsis static const int min_exponent; \fI(until C++11)\fP static constexpr int min_exponent; \fI(since C++11)\fP The value of std::numeric_limits::min_exponent is the lowest negative number n - such that rn-1 - , where r is std::numeric_limits::radix is a valid normalized value of the + such that \\(\\scriptsize r^{n-1}\\)rn-1 + , where r is std::numeric_limits::radix, is a valid normalized value of the floating-point type T. .SH Standard specializations - T value of std::numeric_limits::min_exponent - /* non-specialized */ 0 - bool 0 - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float FLT_MIN_EXP - double DBL_MIN_EXP - long double LDBL_MIN_EXP + T value of std::numeric_limits::min_exponent + /* non-specialized */ 0 + bool 0 + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float FLT_MIN_EXP + double DBL_MIN_EXP + long double LDBL_MIN_EXP .SH Example - Demonstrates the relationships of min_exponent, min_exponent10, min, and radix for + Demonstrates the relationships of min_exponent, min_exponent10, min(), and radix for the type float: - + // Run this code #include + #include + int main() { std::cout << "min() = " << std::numeric_limits::min() << '\\n' << "min_exponent10 = " << std::numeric_limits::min_exponent10 << '\\n' - << std::hexfloat + << std::hexfloat << '\\n' << "min() = " << std::numeric_limits::min() << '\\n' << "min_exponent = " << std::numeric_limits::min_exponent << '\\n'; } @@ -53,6 +59,7 @@ min() = 1.17549e-38 min_exponent10 = -37 + min() = 0x1p-126 min_exponent = -125 @@ -60,13 +67,13 @@ radix the radix or integer base used by the representation of the given \fB[static]\fP type - \fI(public static member constant)\fP + \fI(public static member constant)\fP min_exponent10 the smallest negative power of ten that is a valid normalized \fB[static]\fP floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a valid \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent10 the largest integer power of 10 that is a valid finite floating-point \fB[static]\fP value - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::min_exponent10.3 b/man/std::numeric_limits::min_exponent10.3 index 3c7d38085..1c793c80e 100644 --- a/man/std::numeric_limits::min_exponent10.3 +++ b/man/std::numeric_limits::min_exponent10.3 @@ -1,49 +1,55 @@ -.TH std::numeric_limits::min_exponent10 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::min_exponent10 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::min_exponent10 \- std::numeric_limits::min_exponent10 + .SH Synopsis static const int min_exponent10; \fI(until C++11)\fP static constexpr int min_exponent10; \fI(since C++11)\fP The value of std::numeric_limits::min_exponent10 is the lowest negative number n - such that 10n + such that \\(\\scriptsize 10^n\\)10n is a valid normalized value of the floating-point type T. .SH Standard specializations - T value of std::numeric_limits::min_exponent10 - /* non-specialized */ 0 - bool 0 - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float FLT_MIN_10_EXP - double DBL_MIN_10_EXP - long double LDBL_MIN_10_EXP + T value of std::numeric_limits::min_exponent10 + /* non-specialized */ 0 + bool 0 + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float FLT_MIN_10_EXP + double DBL_MIN_10_EXP + long double LDBL_MIN_10_EXP .SH Example - Demonstrates the relationships of min_exponent, min_exponent10, min, and radix for + Demonstrates the relationships of min_exponent, min_exponent10, min(), and radix for the type float: - + // Run this code #include + #include + int main() { std::cout << "min() = " << std::numeric_limits::min() << '\\n' << "min_exponent10 = " << std::numeric_limits::min_exponent10 << '\\n' - << std::hexfloat + << std::hexfloat << '\\n' << "min() = " << std::numeric_limits::min() << '\\n' << "min_exponent = " << std::numeric_limits::min_exponent << '\\n'; } @@ -52,6 +58,7 @@ min() = 1.17549e-38 min_exponent10 = -37 + min() = 0x1p-126 min_exponent = -125 @@ -59,10 +66,10 @@ min_exponent one more than the smallest negative power of the radix that is a \fB[static]\fP valid normalized floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a valid \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent10 the largest integer power of 10 that is a valid finite floating-point \fB[static]\fP value - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::quiet_NaN.3 b/man/std::numeric_limits::quiet_NaN.3 index 948bfe7e4..ab8e867ff 100644 --- a/man/std::numeric_limits::quiet_NaN.3 +++ b/man/std::numeric_limits::quiet_NaN.3 @@ -1,7 +1,10 @@ -.TH std::numeric_limits::quiet_NaN 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::quiet_NaN 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::quiet_NaN \- std::numeric_limits::quiet_NaN + .SH Synopsis - static T quiet_NaN(); \fI(until C++11)\fP - static constexpr T quiet_NaN(); \fI(since C++11)\fP + static T quiet_NaN() throw(); \fI(until C++11)\fP + static constexpr T quiet_NaN() noexcept; \fI(since C++11)\fP Returns the special value "quiet not-a-number", as represented by the floating-point type T. Only meaningful if std::numeric_limits::has_quiet_NaN == true. In IEEE @@ -12,33 +15,27 @@ .SH Return value - T std::numeric_limits::quiet_NaN() - /* non-specialized */ T(); - bool false - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float NAN or another implementation-defined NaN - double implementation-defined - long double implementation-defined - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::quiet_NaN() + /* non-specialized */ T() + bool false + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float implementation-defined (may be NAN) + double implementation-defined + long double implementation-defined .SH Notes @@ -47,31 +44,31 @@ .SH Example - Several ways to generate a NaN (the output string is compiler-specific) + Several ways to generate a NaN (the output string is compiler-specific): + - // Run this code #include #include #include - + int main() { - std::cout << std::numeric_limits::quiet_NaN() << ' ' - << std::numeric_limits::signaling_NaN() << ' ' - << std::acos(2) << ' ' - << std::tgamma(-1) << ' ' - << std::log(-1) << ' ' - << std::sqrt(-1) << ' ' - << 0 / 0.0 << '\\n'; - + std::cout << std::numeric_limits::quiet_NaN() << ' ' // nan + << std::numeric_limits::signaling_NaN() << ' ' // nan + << std::acos(2) << ' ' // nan + << std::tgamma(-1) << ' ' // nan + << std::log(-1) << ' ' // nan + << std::sqrt(-1) << ' ' // -nan + << 0 / 0.0 << '\\n'; // -nan + std::cout << "NaN == NaN? " << std::boolalpha - << ( std::numeric_limits::quiet_NaN() - == std::numeric_limits::quiet_NaN() ) << '\\n'; + << ( std::numeric_limits::quiet_NaN() == + std::numeric_limits::quiet_NaN() ) << '\\n'; } -.SH Output: +.SH Possible output: nan nan nan nan nan -nan -nan NaN == NaN? false @@ -80,6 +77,14 @@ has_quiet_NaN identifies floating-point types that can represent the special value \fB[static]\fP "quiet not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP signaling_NaN returns a signaling NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP + nan + nanf + nanl not-a-number (NaN) + \fI(C++11)\fP \fI(function)\fP + \fI(C++11)\fP + \fI(C++11)\fP + isnan checks if the given number is NaN + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::numeric_limits::radix.3 b/man/std::numeric_limits::radix.3 index 726f6ef94..be223af98 100644 --- a/man/std::numeric_limits::radix.3 +++ b/man/std::numeric_limits::radix.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::radix 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::radix 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::radix \- std::numeric_limits::radix + .SH Synopsis static const int radix; \fI(until C++11)\fP static constexpr int radix; \fI(since C++11)\fP @@ -10,34 +13,35 @@ .SH Standard specializations - T value of std::numeric_limits::radix - /* non-specialized */ 0 - bool 2 - char 2 - signed char 2 - unsigned char 2 - wchar_t 2 - char16_t 2 - char32_t 2 - short 2 - unsigned short 2 - int 2 - unsigned int 2 - long 2 - unsigned long 2 - long long 2 - unsigned long long 2 - float FLT_RADIX - double FLT_RADIX - long double FLT_RADIX + T value of std::numeric_limits::radix + /* non-specialized */ 0 + bool 2 + char 2 + signed char 2 + unsigned char 2 + wchar_t 2 + char8_t \fI(since C++20)\fP 2 + char16_t \fI(since C++11)\fP 2 + char32_t \fI(since C++11)\fP 2 + short 2 + unsigned short 2 + int 2 + unsigned int 2 + long 2 + unsigned long 2 + long long \fI(since C++11)\fP 2 + unsigned long long \fI(since C++11)\fP 2 + float FLT_RADIX + double FLT_RADIX + long double FLT_RADIX .SH See also digits number of radix digits that can be represented without change - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP min_exponent one more than the smallest negative power of the radix that is a valid \fB[static]\fP normalized floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP max_exponent one more than the largest integer power of the radix that is a valid \fB[static]\fP finite floating-point value - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::round_error.3 b/man/std::numeric_limits::round_error.3 index a99596971..7ca2cd46b 100644 --- a/man/std::numeric_limits::round_error.3 +++ b/man/std::numeric_limits::round_error.3 @@ -1,7 +1,10 @@ -.TH std::numeric_limits::round_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::round_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::round_error \- std::numeric_limits::round_error + .SH Synopsis - static T round_error(); \fI(until C++11)\fP - static constexpr T round_error(); \fI(since C++11)\fP + static T round_error() throw(); \fI(until C++11)\fP + static constexpr T round_error() noexcept; \fI(since C++11)\fP Returns the largest possible rounding error in ULPs (units in the last place) as defined by ISO 10967, which can vary from 0.5 (rounding to the nearest digit) to 1.0 @@ -10,35 +13,29 @@ .SH Return value - T std::numeric_limits::round_error() - /* non-specialized */ T(); - bool false - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float 0.5F - double 0.5 - long double 0.5L - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::round_error() + /* non-specialized */ T() + bool false + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float 0.5F + double 0.5 + long double 0.5L .SH See also round_style identifies the rounding style used by the type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::round_style.3 b/man/std::numeric_limits::round_style.3 index c4e8aa3ac..c6255ae34 100644 --- a/man/std::numeric_limits::round_style.3 +++ b/man/std::numeric_limits::round_style.3 @@ -1,39 +1,49 @@ -.TH std::numeric_limits::round_style 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::round_style 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::round_style \- std::numeric_limits::round_style + .SH Synopsis - static const std::float_round_style round_style \fI(until C++11)\fP - static constexpr std::float_round_style round_style \fI(since C++11)\fP + static const std::float_round_style round_style; \fI(until C++11)\fP + static constexpr std::float_round_style round_style; \fI(since C++11)\fP - The value of std::numeric_limits::round_stylem identifies the rounding style used + The value of std::numeric_limits::round_style identifies the rounding style used by the floating-point type T whenever a value that is not one of the exactly repesentable values of T is stored in an object of that type. .SH Standard specializations - T value of std::numeric_limits::round_style - /* non-specialized */ std::round_toward_zero - bool std::round_toward_zero - char std::round_toward_zero - signed char std::round_toward_zero - unsigned char std::round_toward_zero - wchar_t std::round_toward_zero - char16_t std::round_toward_zero - char32_t std::round_toward_zero - short std::round_toward_zero - unsigned short std::round_toward_zero - int std::round_toward_zero - unsigned int std::round_toward_zero - long std::round_toward_zero - unsigned long std::round_toward_zero - long long std::round_toward_zero - unsigned long long std::round_toward_zero - float usually std::round_to_nearest - double usually std::round_to_nearest - long double usually std::round_to_nearest + T value of std::numeric_limits::round_style + /* non-specialized */ std::round_toward_zero + bool std::round_toward_zero + char std::round_toward_zero + signed char std::round_toward_zero + unsigned char std::round_toward_zero + wchar_t std::round_toward_zero + char8_t \fI(since C++20)\fP std::round_toward_zero + char16_t \fI(since C++11)\fP std::round_toward_zero + char32_t \fI(since C++11)\fP std::round_toward_zero + short std::round_toward_zero + unsigned short std::round_toward_zero + int std::round_toward_zero + unsigned int std::round_toward_zero + long std::round_toward_zero + unsigned long std::round_toward_zero + long long \fI(since C++11)\fP std::round_toward_zero + unsigned long long \fI(since C++11)\fP std::round_toward_zero + float usually std::round_to_nearest + double usually std::round_to_nearest + long double usually std::round_to_nearest + +.SH Notes + + These values are constants, and do not reflect the changes to the rounding made by + std::fesetround. The changed values may be obtained from FLT_ROUNDS or + std::fegetround. .SH Example The decimal value 0.1 cannot be represented by a binary floating-point type. When - stored in an IEEE-745 double, it falls between 0x1.9999999999999*2-4 + stored in an IEEE-754 double, it falls between 0x1.9999999999999*2-4 and 0x1.999999999999a*2-4 . Rounding to nearest representable value results in 0x1.999999999999a*2-4 . @@ -43,27 +53,47 @@ is rounded to nearest and is stored as 0x1.3333333333333*2-2 . - + // Run this code #include #include + + auto print(std::float_round_style frs) + { + switch (frs) + { + case std::round_indeterminate: + return "Rounding style cannot be determined"; + case std::round_toward_zero: + return "Rounding toward zero"; + case std::round_to_nearest: + return "Rounding toward nearest representable value"; + case std::round_toward_infinity: + return "Rounding toward positive infinity"; + case std::round_toward_neg_infinity: + return "Rounding toward negative infinity"; + } + return "unknown round style"; + } + int main() { - std::cout << std::hexfloat << "The decimal 0.1 is stored in a double as " + std::cout << std::hexfloat + << "The decimal 0.1 is stored in a double as " << 0.1 << '\\n' << "The decimal 0.3 is stored in a double as " << 0.3 << '\\n' - << "The rounding style is " << std::numeric_limits::round_style << '\\n'; + << print(std::numeric_limits::round_style) << '\\n'; } .SH Output: The decimal 0.1 is stored in a double as 0x1.999999999999ap-4 The decimal 0.3 is stored in a double as 0x1.3333333333333p-2 - The rounding style is 1 + Rounding toward nearest representable value .SH See also float_round_style indicates floating-point rounding modes - \fI(enum)\fP + \fI(enum)\fP diff --git a/man/std::numeric_limits::signaling_NaN.3 b/man/std::numeric_limits::signaling_NaN.3 index 5b9a0c568..b548efc44 100644 --- a/man/std::numeric_limits::signaling_NaN.3 +++ b/man/std::numeric_limits::signaling_NaN.3 @@ -1,7 +1,10 @@ -.TH std::numeric_limits::signaling_NaN 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::signaling_NaN 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::signaling_NaN \- std::numeric_limits::signaling_NaN + .SH Synopsis - static T signaling_NaN(); \fI(until C++11)\fP - static constexpr T signaling_NaN(); \fI(since C++11)\fP + static T signaling_NaN() throw(); \fI(until C++11)\fP + static constexpr T signaling_NaN() noexcept; \fI(since C++11)\fP Returns the special value "signaling not-a-number", as represented by the floating-point type T. Only meaningful if std::numeric_limits::has_signaling_NaN @@ -12,38 +15,32 @@ .SH Return value - T std::numeric_limits::quiet_NaN() - /* non-specialized */ T(); - bool false - char 0 - signed char 0 - unsigned char 0 - wchar_t 0 - char16_t 0 - char32_t 0 - short 0 - unsigned short 0 - int 0 - unsigned int 0 - long 0 - unsigned long 0 - long long 0 - unsigned long long 0 - float implementation-defined - double implementation-defined - long double implementation-defined - -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - + T std::numeric_limits::signaling_NaN() + /* non-specialized */ T() + bool false + char 0 + signed char 0 + unsigned char 0 + wchar_t 0 + char8_t \fI(since C++20)\fP 0 + char16_t \fI(since C++11)\fP 0 + char32_t \fI(since C++11)\fP 0 + short 0 + unsigned short 0 + int 0 + unsigned int 0 + long 0 + unsigned long 0 + long long \fI(since C++11)\fP 0 + unsigned long long \fI(since C++11)\fP 0 + float implementation-defined (may be FLT_SNAN) + double implementation-defined (may be DBL_SNAN) + long double implementation-defined (may be LDBL_SNAN) .SH Notes - A NaN never compares equal to itself. Copying a NaN may not preserve its bit - representation. + A NaN never compares equal to itself. Copying a NaN is not required, by IEEE-754, to + preserve its bit representation (sign and payload), though most implementation do. When a signaling NaN is used as an argument to an arithmetic expression, the appropriate floating-point exception may be raised and the NaN is "quieted", that @@ -51,47 +48,59 @@ .SH Example - Demonstrates the use of a signaling NaN to raise a floating-point exception + Demonstrates the use of a signaling NaN to raise a floating-point exception: + - // Run this code + #include #include #include - #include + #pragma STDC_FENV_ACCESS on + void show_fe_exceptions() { int n = std::fetestexcept(FE_ALL_EXCEPT); - if(n & FE_INVALID) std::cout << "FE_INVALID is raised\\n"; - else if(n == 0) std::cout << "no exceptions are raised\\n"; + + if (n & FE_INVALID) + std::cout << "FE_INVALID is raised\\n"; + else if (n == 0) + std::cout << "no exceptions are raised\\n"; + std::feclearexcept(FE_ALL_EXCEPT); } + int main() { double snan = std::numeric_limits::signaling_NaN(); - std::cout << "After sNaN was obtained "; + std::cout << "After sNaN was obtained, "; show_fe_exceptions(); + double qnan = snan * 2.0; - std::cout << "After sNaN was multiplied by 2 "; + std::cout << "After sNaN was multiplied by 2, "; show_fe_exceptions(); + double qnan2 = qnan * 2.0; - std::cout << "After the quieted NaN was multiplied by 2 "; + std::cout << "After the quieted NaN was multiplied by 2, "; show_fe_exceptions(); + std::cout << "The result is " << qnan2 << '\\n'; } .SH Output: - After sNaN was obtained no exceptions are raised - After sNaN was multiplied by 2 FE_INVALID is raised - After the quieted NaN was multiplied by 2 no exceptions are raised + After sNaN was obtained, no exceptions are raised + After sNaN was multiplied by 2, FE_INVALID is raised + After the quieted NaN was multiplied by 2, no exceptions are raised The result is nan .SH See also has_signaling_NaN identifies floating-point types that can represent the special \fB[static]\fP value "signaling not-a-number" (NaN) - \fI(public static member constant)\fP + \fI(public static member constant)\fP quiet_NaN returns a quiet NaN value of the given floating-point type - \fB[static]\fP \fI(public static member function)\fP + \fB[static]\fP \fI(public static member function)\fP + isnan checks if the given number is NaN + \fI(C++11)\fP \fI(function)\fP diff --git a/man/std::numeric_limits::tinyness_before.3 b/man/std::numeric_limits::tinyness_before.3 index 9446739d6..c8110549d 100644 --- a/man/std::numeric_limits::tinyness_before.3 +++ b/man/std::numeric_limits::tinyness_before.3 @@ -1,4 +1,7 @@ -.TH std::numeric_limits::tinyness_before 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::tinyness_before 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::tinyness_before \- std::numeric_limits::tinyness_before + .SH Synopsis static const bool tinyness_before; \fI(until C++11)\fP static constexpr bool tinyness_before; \fI(since C++11)\fP @@ -9,42 +12,45 @@ .SH Standard specializations - T value of std::numeric_limits::tinyness_before - /* non-specialized */ false - bool false - char false - signed char false - unsigned char false - wchar_t false - char16_t false - char32_t false - short false - unsigned short false - int false - unsigned int false - long false - unsigned long false - long long false - unsigned long long false - float implementation-defined - double implementation-defined - long double implementation-defined + T value of std::numeric_limits::tinyness_before + /* non-specialized */ false + bool false + char false + signed char false + unsigned char false + wchar_t false + char8_t \fI(since C++20)\fP false + char16_t \fI(since C++11)\fP false + char32_t \fI(since C++11)\fP false + short false + unsigned short false + int false + unsigned int false + long false + unsigned long false + long long \fI(since C++11)\fP false + unsigned long long \fI(since C++11)\fP false + float implementation-defined + double implementation-defined + long double implementation-defined .SH Notes - Standard-compliant IEEE 754 floating-point implementations may detect the - floating-point underflow at three predefined moments: - - 1) after computation of a result with absolute value smaller than - std::numeric_limits::min(), such implementation detects tinyness before rounding - (e.g. UltraSparc) - - 2) after rounding of the result to std::numeric_limits::digits bits, if the - result is tiny, such implementation detects tinyness after rounding (e.g. - SuperSparc) - - 3) if the conversion of the rounded tiny result to subnormal form resulted in the - loss of precision, such implementation detects denorm loss. + Standard-compliant IEEE 754 floating-point implementations are required to detect + the floating-point underflow, and have two alternative situations where this can be + done + + 1. Underflow occurs (and FE_UNDERFLOW may be raised) if a computation produces a + result whose absolute value, computed as though both the exponent range and the + precision were unbounded, is smaller than std::numeric_limits::min(). Such + implementation detects tinyness before rounding (e.g. UltraSparc, POWER). + 2. Underflow occurs (and FE_UNDERFLOW may be raised) if after the rounding of the + result to the target floating-point type (that is, rounding to + std::numeric_limits::digits bits), the result's absolute value is smaller + than std::numeric_limits::min(). Formally, the absolute value of a nonzero + result computed as though the exponent range were unbounded is smaller than + std::numeric_limits::min(). Such implementation detects tinyness after + rounding (e.g. SuperSparc). .SH Example @@ -53,30 +59,29 @@ normal value 1p-1022 after rounding. The implementation used to execute this test (IBM Power7) detects tinyness before rounding. - + // Run this code #include #include #include #include + int main() { std::cout << "Tinyness before: " << std::boolalpha << std::numeric_limits::tinyness_before << '\\n'; - + double denorm_max = std::nextafter(std::numeric_limits::min(), 0); double multiplier = 1 + std::numeric_limits::epsilon(); - + std::feclearexcept(FE_ALL_EXCEPT); - - double result = denorm_max*multiplier; // Underflow only if tinyness_before - - if(std::fetestexcept(FE_UNDERFLOW)) + + double result = denorm_max * multiplier; // Underflow only if tinyness_before + + if (std::fetestexcept(FE_UNDERFLOW)) std::cout << "Underflow detected\\n"; - else if (std::fetestexcept(FE_INEXACT)) - std::cout << "Inexact result detected\\n"; - + std::cout << std::hexfloat << denorm_max << " x " << multiplier << " = " << result << '\\n'; } @@ -91,6 +96,6 @@ has_denorm_loss identifies the floating-point types that detect loss of precision as \fB[static]\fP denormalization loss rather than inexact result - \fI(public static member constant)\fP + \fI(public static member constant)\fP has_denorm identifies the denormalization style used by the floating-point type - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP diff --git a/man/std::numeric_limits::traps.3 b/man/std::numeric_limits::traps.3 index 72783befa..318e8d948 100644 --- a/man/std::numeric_limits::traps.3 +++ b/man/std::numeric_limits::traps.3 @@ -1,34 +1,38 @@ -.TH std::numeric_limits::traps 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numeric_limits::traps 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numeric_limits::traps \- std::numeric_limits::traps + .SH Synopsis - static const bool traps \fI(until C++11)\fP - static constexpr bool traps \fI(since C++11)\fP + static const bool traps; \fI(until C++11)\fP + static constexpr bool traps; \fI(since C++11)\fP The value of std::numeric_limits::traps is true for all arithmetic types T that - have at least one value that, if used as an argument to an arithmetic operation, - will generate a trap. + have at least one value at the start of the program that, if used as an argument to + an arithmetic operation, will generate a trap. .SH Standard specializations - T value of std::numeric_limits::traps - /* non-specialized */ false - bool false - char usually true - signed char usually true - unsigned char usually true - wchar_t usually true - char16_t usually true - char32_t usually true - short usually true - unsigned short usually true - int usually true - unsigned int usually true - long usually true - unsigned long usually true - long long usually true - unsigned long long usually true - float usually false - double usually false - long double usually false + T value of std::numeric_limits::traps + /* non-specialized */ false + bool false + char usually true + signed char usually true + unsigned char usually true + wchar_t usually true + char8_t \fI(since C++20)\fP usually true + char16_t \fI(since C++11)\fP usually true + char32_t \fI(since C++11)\fP usually true + short usually true + unsigned short usually true + int usually true + unsigned int usually true + long usually true + unsigned long usually true + long long \fI(since C++11)\fP usually true + unsigned long long \fI(since C++11)\fP usually true + float usually false + double usually false + long double usually false .SH Notes @@ -45,11 +49,55 @@ most modern systems. An exception would be a DEC Alpha program, where it is true if compiled without -ieee. +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha + << "bool: traps = " << std::numeric_limits::traps << '\\n' + << "char: traps = " << std::numeric_limits::traps << '\\n' + << "char16_t: traps = " << std::numeric_limits::traps << '\\n' + << "long: traps = " << std::numeric_limits::traps << '\\n' + << "float: traps = " << std::numeric_limits::traps << '\\n'; + } + +.SH Possible output: + + // GCC output: + bool: traps = true + char: traps = true + char16_t: traps = true + long: traps = true + float: traps = false + + // Clang output: + bool: traps = false + char: traps = true + char16_t: traps = true + long: traps = true + float: traps = false + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + it was unclear what is returned if returns the enable status + LWG 497 C++98 trapping at the start of the program + is enabled or disabled at runtime + .SH See also .SH Floating-point environment tinyness_before identifies floating-point types that detect tinyness before rounding - \fB[static]\fP \fI(public static member constant)\fP + \fB[static]\fP \fI(public static member constant)\fP has_denorm_loss identifies the floating-point types that detect loss of precision as \fB[static]\fP denormalization loss rather than inexact result - \fI(public static member constant)\fP + \fI(public static member constant)\fP diff --git a/man/std::numpunct.3 b/man/std::numpunct.3 index 2b39bbbc5..0dc839154 100644 --- a/man/std::numpunct.3 +++ b/man/std::numpunct.3 @@ -1,4 +1,7 @@ -.TH std::numpunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct \- std::numpunct + .SH Synopsis Defined in header template< class CharT > @@ -26,58 +29,55 @@ floatval ::= [sign] units [decimal-point [digits]] [e [sign] digits] | [sign] decimal-point digits [e [sign] digits] - e ::= ’e’ | ’E’ + e ::= 'e' | 'E' std-numpunct-inheritance.svg - About this image Inheritance diagram - Two standalone (locale-independent) specializations are provided by the standard - library: +.SH Specializations + + The standard library is guaranteed to provide the following specializations (they + are required to be implemented by any locale object): Defined in header std::numpunct provides equivalents of the "C" locale preferences std::numpunct provides wide character equivalents of the "C" locale preferences - In addition, every locale object constructed in a C++ program implements its own - (locale-specific) versions of these specializations. - .SH Member types Member type Definition - char_type charT - string_type std::basic_string + char_type CharT + string_type std::basic_string .SH Member functions constructor constructs a new numpunct facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs a numpunct facet - \fI(protected member function)\fP + \fI(protected member function)\fP decimal_point invokes do_decimal_point - \fI(public member function)\fP + \fI(public member function)\fP thousands_sep invokes do_thousands_sep - \fI(public member function)\fP + \fI(public member function)\fP grouping invokes do_grouping - \fI(public member function)\fP + \fI(public member function)\fP truename invokes do_truename or do_falsename - falsename \fI(public member function)\fP + falsename \fI(public member function)\fP .SH Protected member functions do_decimal_point provides the character to use as decimal point - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function)\fP - provides the numbers of digits between each pair of thousands - do_grouping + \fB[virtual]\fP \fI(virtual protected member function)\fP + do_grouping provides the numbers of digits between each pair of thousands \fB[virtual]\fP separators - \fI(virtual protected member function)\fP + \fI(virtual protected member function)\fP do_truename provides the string to use as the name of the boolean true and do_falsename false - \fB[virtual]\fP \fI(virtual protected member function)\fP + \fB[virtual]\fP \fI(virtual protected member function)\fP .SH Member objects @@ -86,19 +86,20 @@ .SH Example - The following example changes the string representations of true and false + The following example changes the string representations of true and false: + - // Run this code #include #include - - struct french_bool : std::numpunct { - string_type do_truename() const { return "oui"; } - string_type do_falsename() const { return "non"; } + + struct french_bool : std::numpunct + { + string_type do_truename() const override { return "vrai"; } + string_type do_falsename() const override { return "faux"; } }; - + int main() { std::cout << "default locale: " @@ -111,7 +112,16 @@ .SH Output: default locale: true, false - locale with modified numpunct: oui, non + locale with modified numpunct: vrai, faux + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 338 C++98 the sign token allowed an optional removed the whitespace + whitespace following + or - .SH See also diff --git a/man/std::numpunct::decimal_point,do_decimal_point.3 b/man/std::numpunct::decimal_point,do_decimal_point.3 index 5092a97c7..62181455e 100644 --- a/man/std::numpunct::decimal_point,do_decimal_point.3 +++ b/man/std::numpunct::decimal_point,do_decimal_point.3 @@ -1,10 +1,13 @@ -.TH std::numpunct::decimal_point,do_decimal_point 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct::decimal_point,do_decimal_point 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct::decimal_point,do_decimal_point \- std::numpunct::decimal_point,do_decimal_point + .SH Synopsis Defined in header public: \fB(1)\fP char_type decimal_point() const; protected: \fB(2)\fP - char_type virtual do_decimal_point() const; + virtual char_type do_decimal_point() const; 1) Public member function, calls the member function do_decimal_point of the most derived class. @@ -13,21 +16,22 @@ .SH Return value - The object of type char_type to use as the thousands separator. The standard - specializations of std::numpunct return ’.’ and L’.’. + The value of type char_type to use as the decimal separator. The standard + specializations of std::numpunct return '.' and L'.'. .SH Example - + // Run this code #include #include - - struct slash : std::numpunct { - char do_decimal_point() const { return '/'; } // separate with slash + + struct slash : std::numpunct + { + char do_decimal_point() const { return '/'; } // separate with slash }; - + int main() { std::cout.precision(10); diff --git a/man/std::numpunct::grouping,do_grouping.3 b/man/std::numpunct::grouping,do_grouping.3 deleted file mode 100644 index 49dafe259..000000000 --- a/man/std::numpunct::grouping,do_grouping.3 +++ /dev/null @@ -1,67 +0,0 @@ -.TH std::numpunct::grouping,do_grouping 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - public: \fB(1)\fP - std::string grouping() const; - protected: \fB(2)\fP - virtual std::string do_grouping() const; - - 1) Public member function, calls the member function do_grouping of the most derived - class. - 2) Returns an std::string holding, in each char element, the number of digits in - each group of the numeric output formatted by num_put::put() (and, therefore, - basic_ostream::operator<<) - - The groups are stored as binary values: three-digit group is '\\3', and 51-digit - group is '3'. The character at index zero of the returned string holds the number of - digits in the rightmost group. The character at index 1 holds the number of digits - in the second group from the right, etc. The grouping indicated by the last - character in the returned string is reused to group all remaining digits in the - (left part of) the number. - -.SH Return value - - The object of type std::string holding the groups. The standard specializations of - std::numpunct return an empty string, indicating no grouping. Typical groupings - (e.g. the en_US locale) return "\\003". - -.SH Example - - -// Run this code - - #include - #include - #include - - struct space_out : std::numpunct - { - char do_thousands_sep() const { return ' '; } // separate with spaces - std::string do_grouping() const { return "\\1"; } // groups of 1 digit - }; - - struct g123 : std::numpunct - { - std::string do_grouping() const { return "\\1\\2\\3"; } - }; - - int main() - { - std::cout << "default locale: " << 12345678 << '\\n'; - std::cout.imbue(std::locale(std::cout.getloc(), new space_out)); - std::cout << "locale with modified numpunct: " << 12345678 << '\\n'; - std::cout.imbue(std::locale(std::cout.getloc(), new g123)); - std::cout << "Locale with \\\\1\\\\2\\\\3 grouping: " << - std::numeric_limits::max() << '\\n'; - } - -.SH Output: - - default locale: 12345678 - locale with modified numpunct: 1 2 3 4 5 6 7 8 - Locale with \\1\\2\\3 grouping: 18,446,744,073,709,551,61,5 - -.SH See also - - do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::numpunct::grouping,std::numpunct::do_grouping.3 b/man/std::numpunct::grouping,std::numpunct::do_grouping.3 new file mode 100644 index 000000000..23d697251 --- /dev/null +++ b/man/std::numpunct::grouping,std::numpunct::do_grouping.3 @@ -0,0 +1,76 @@ +.TH std::numpunct::grouping,std::numpunct::do_grouping 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct::grouping,std::numpunct::do_grouping \- std::numpunct::grouping,std::numpunct::do_grouping + +.SH Synopsis + Defined in header + public: \fB(1)\fP + std::string grouping() const; + protected: \fB(2)\fP + virtual std::string do_grouping() const; + + 1) Public member function, calls the member function do_grouping of the most derived + class. + 2) Returns an std::string holding, in each char element, the number of digits in + each group of the numeric output formatted by num_put::put() (and, therefore, + basic_ostream::operator<<). + + This function returns a string, vec, which is used as a vector of integer values. + (For example, "\\003" specifies groups of 3 digits each, while "3" implies groups of + 51 digits each.). Each element vec[i] represents the number of digits in the ith + digit group of the integer part of the number, counting from the right: vec[0] holds + the number of digits in the rightmost group, vec[1] - in the second group from the + right, etc. The grouping indicated by the last character, vec[vec.size()-1], is + repeatedly reused to group all remaining digits in the (left part of) the number. If + vec[i] is non-positive or equals CHAR_MAX the size of the corresponding digit group + is unlimited. + +.SH Return value + + The object of type std::string holding the groups. The standard specializations of + std::numpunct return an empty string, indicating no grouping. Typical groupings + (e.g. the en_US locale) return "\\003". + +.SH Example + + +// Run this code + + #include + #include + #include + + struct space_out : std::numpunct + { + char do_thousands_sep() const { return ' '; } // separate with spaces + std::string do_grouping() const { return "\\1"; } // groups of 1 digit + }; + + struct g123 : std::numpunct + { + std::string do_grouping() const { return "\\1\\2\\3"; } + }; + + int main() + { + std::cout << "Default locale: " << 12345678 << '\\n'; + std::cout.imbue(std::locale(std::cout.getloc(), new space_out)); + std::cout << "Locale with modified numpunct: " << 12345678 << '\\n'; + std::cout.imbue(std::locale(std::cout.getloc(), new g123)); + std::cout << "Locale with \\\\1\\\\2\\\\3 grouping: " + << std::numeric_limits::max() << '\\n' + << "Same, for a floating-point number: " + << std::fixed << 123456789.123456789 << '\\n'; + } + +.SH Output: + + Default locale: 12345678 + Locale with modified numpunct: 1 2 3 4 5 6 7 8 + Locale with \\1\\2\\3 grouping: 18,446,744,073,709,551,61,5 + Same, for a floating-point number: 123,456,78,9.123457 + +.SH See also + + do_thousands_sep provides the character to use as thousands separator + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::numpunct::numpunct.3 b/man/std::numpunct::numpunct.3 index d4f68d350..6b2978675 100644 --- a/man/std::numpunct::numpunct.3 +++ b/man/std::numpunct::numpunct.3 @@ -1,10 +1,13 @@ -.TH std::numpunct::numpunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct::numpunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct::numpunct \- std::numpunct::numpunct + .SH Synopsis Defined in header explicit numpunct( std::size_t refs = 0 ); Creates a std::numpunct facet and forwards the starting reference count refs to the - base class constructor, locale::facet::facet() + base class constructor, locale::facet::facet(). .SH Parameters diff --git a/man/std::numpunct::thousands_sep,do_thousands_sep.3 b/man/std::numpunct::thousands_sep,do_thousands_sep.3 index d12046e1b..3c3b65bb6 100644 --- a/man/std::numpunct::thousands_sep,do_thousands_sep.3 +++ b/man/std::numpunct::thousands_sep,do_thousands_sep.3 @@ -1,10 +1,13 @@ -.TH std::numpunct::thousands_sep,do_thousands_sep 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct::thousands_sep,do_thousands_sep 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct::thousands_sep,do_thousands_sep \- std::numpunct::thousands_sep,do_thousands_sep + .SH Synopsis Defined in header public: \fB(1)\fP char_type thousands_sep() const; protected: \fB(2)\fP - char_type virtual do_thousands_sep() const; + virtual char_type do_thousands_sep() const; 1) Public member function, calls the member function do_thousands_sep of the most derived class. @@ -14,21 +17,22 @@ .SH Return value The object of type char_type to use as the thousands separator. The standard - specializations of std::numpunct return ’,’ and L’,’. + specializations of std::numpunct return ',' and L','. .SH Example - + // Run this code #include #include - - struct space_out : std::numpunct { + + struct space_out : std::numpunct + { char do_thousands_sep() const { return ' '; } // separate with spaces std::string do_grouping() const { return "\\1"; } // groups of 1 digit }; - + int main() { std::cout << "default locale: " << 12345678 << '\\n'; @@ -41,9 +45,15 @@ default locale: 12345678 locale with modified numpunct: 1 2 3 4 5 6 7 8 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 20 C++98 the return type was string_type changed to char_type + .SH See also - provides the numbers of digits between each pair of thousands - do_grouping - \fB[virtual]\fP separators - \fI(virtual protected member function)\fP + do_grouping provides the numbers of digits between each pair of thousands separators + \fB[virtual]\fP \fI(virtual protected member function)\fP diff --git a/man/std::numpunct::truename,do_truename,falsename,do_falsename.3 b/man/std::numpunct::truename,do_truename,falsename,do_falsename.3 index ca41043c4..b4d6c36db 100644 --- a/man/std::numpunct::truename,do_truename,falsename,do_falsename.3 +++ b/man/std::numpunct::truename,do_truename,falsename,do_falsename.3 @@ -1,4 +1,7 @@ -.TH std::numpunct::truename,do_truename,falsename,do_falsename 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct::truename,do_truename,falsename,do_falsename 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct::truename,do_truename,falsename,do_falsename \- std::numpunct::truename,do_truename,falsename,do_falsename + .SH Synopsis Defined in header public: \fB(1)\fP @@ -10,41 +13,55 @@ protected: \fB(4)\fP virtual string_type do_falsename() const; - 1-2) Public member function, calls the member function do_truename and do_falsename + 1,2) Public member function, calls the member function do_truename and do_falsename of the most derived class respectively. - 3-4) Returns the string to be used as the representation of the boolean value true. + 3) Returns the string to be used as the representation of the boolean value true. + 4) Returns the string to be used as the representation of the boolean value false. .SH Return value - 1-2) The object of type string_type to use as the representation of true. The + 1,3) The object of type string_type to use as the representation of true. The standard specializations of std::numpunct return "true" and L"true". - 3-4) The object of type string_type to use as the representation of false. The + 2,4) The object of type string_type to use as the representation of false. The standard specializations of std::numpunct return "false" and L"false". .SH Example - + // Run this code + #include #include #include - #include - - struct custom_tf : std::numpunct { - std::string do_truename() const { return "t"; } - std::string do_falsename() const { return "f"; } + + struct custom_tf : std::numpunct + { + std::string do_truename() const { return {'t'}; } + std::string do_falsename() const { return {'f'}; } }; - + int main() { std::cout << std::boolalpha; - std::cout << "default locale: " << true << true << false << false << '\\n'; + + // default boolalpha output + std::cout << "Default locale,\\n" + " boolalpha true: " << true << "\\n" + " boolalpha false: " << false << "\\n\\n"; + + // with custom_tf applied to locale std::cout.imbue(std::locale(std::cout.getloc(), new custom_tf)); - std::cout << "locale with modified numpunct: " - << true << true << false << false << '\\n'; + std::cout << "Locale with modified numpunct,\\n" + " boolalpha true: " << true << "\\n" + " boolalpha false: " << false << '\\n'; } .SH Output: - default locale: truetruefalsefalse - locale with modified numpunct: ttff + Default locale, + boolalpha true: true + boolalpha false: false + + Locale with modified numpunct, + boolalpha true: t + boolalpha false: f diff --git a/man/std::numpunct::~numpunct.3 b/man/std::numpunct::~numpunct.3 index 2e712a64e..48d5acbfd 100644 --- a/man/std::numpunct::~numpunct.3 +++ b/man/std::numpunct::~numpunct.3 @@ -1,4 +1,7 @@ -.TH std::numpunct::~numpunct 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct::~numpunct 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct::~numpunct \- std::numpunct::~numpunct + .SH Synopsis Defined in header protected: ~numpunct(); @@ -11,18 +14,20 @@ .SH Example - + // Run this code #include #include + struct Destructible_numpunct : public std::numpunct { Destructible_numpunct(std::size_t refs = 0) : numpunct(refs) {} - ~Destructible_numpunct() {}; // public dtor + // note: the implicit destructor is public }; + int main() { Destructible_numpunct dc; - // std::numpunct c; // compile error: protected destructor + // std::numpunct c; // compile error: protected destructor } diff --git a/man/std::numpunct_byname.3 b/man/std::numpunct_byname.3 index 4da65fb58..33f05a5b8 100644 --- a/man/std::numpunct_byname.3 +++ b/man/std::numpunct_byname.3 @@ -1,4 +1,7 @@ -.TH std::numpunct_byname 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::numpunct_byname 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::numpunct_byname \- std::numpunct_byname + .SH Synopsis Defined in header template< class CharT > @@ -7,13 +10,15 @@ std::numpunct_byname is a std::numpunct facet which encapsulates numeric punctuation preferences of a locale specified at its construction. - Two specializations are provided by the standard library +.SH Specializations + + The standard library is guaranteed to provide the following specializations: Defined in header std::numpunct_byname locale-specific std::numpunct facet for narrow character I/O - std::numpunct_byname locale-specific std::numpunct facet for wide - characters I/O + std::numpunct_byname locale-specific std::numpunct facet for wide character + I/O .SH Member types @@ -24,13 +29,13 @@ .SH Member functions constructor constructs a new numpunct_byname facet - \fI(public member function)\fP + \fI(public member function)\fP destructor destroys a numpunct_byname facet - \fI(protected member function)\fP + \fI(protected member function)\fP + - - std::numpunct_byname::numpunct_byname +std::numpunct_byname::numpunct_byname explicit numpunct_byname( const char* name, std::size_t refs = 0 ); explicit numpunct_byname( const std::string& name, std::size_t refs = \fI(since C++11)\fP @@ -47,49 +52,48 @@ name - the name of the locale refs - the number of references that link to the facet - - std::numpunct_byname::~numpunct_byname + +std::numpunct_byname::~numpunct_byname protected: ~numpunct_byname(); Destroys the facet. - + Inherited from std::numpunct .SH Member types Member type Definition - char_type charT - string_type std::basic_string + char_type CharT + string_type std::basic_string .SH Member functions decimal_point invokes do_decimal_point - \fI(public member function of std::numpunct)\fP + \fI(public member function of std::numpunct)\fP thousands_sep invokes do_thousands_sep - \fI(public member function of std::numpunct)\fP + \fI(public member function of std::numpunct)\fP grouping invokes do_grouping - \fI(public member function of std::numpunct)\fP + \fI(public member function of std::numpunct)\fP truename invokes do_truename or do_falsename - falsename \fI(public member function of std::numpunct)\fP + falsename \fI(public member function of std::numpunct)\fP .SH Protected member functions do_decimal_point provides the character to use as decimal point - \fB[virtual]\fP \fI(virtual protected member function of std::numpunct)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::numpunct)\fP do_thousands_sep provides the character to use as thousands separator - \fB[virtual]\fP \fI(virtual protected member function of std::numpunct)\fP - provides the numbers of digits between each pair of thousands - do_grouping + \fB[virtual]\fP \fI(virtual protected member function of std::numpunct)\fP + do_grouping provides the numbers of digits between each pair of thousands \fB[virtual]\fP separators - \fI(virtual protected member function of std::numpunct)\fP + \fI(virtual protected member function of std::numpunct)\fP do_truename provides the string to use as the name of the boolean true and do_falsename false - \fB[virtual]\fP \fI(virtual protected member function of std::numpunct)\fP + \fB[virtual]\fP \fI(virtual protected member function of std::numpunct)\fP .SH Member objects @@ -98,14 +102,15 @@ Inherited from std::numpunct .SH Example - This example demonistrates how to apply numeric punctuation rules of another - language without changing the rest of the locale. + This example demonstrates how to apply numeric punctuation rules of another language + without changing the rest of the locale. + - // Run this code #include #include + int main() { const double number = 1000.25; diff --git a/man/std::ofstream.3 b/man/std::ofstream.3 deleted file mode 120000 index 5f2b97682..000000000 --- a/man/std::ofstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream.3 \ No newline at end of file diff --git a/man/std::ofstream.3 b/man/std::ofstream.3 new file mode 100644 index 000000000..110ede1ad --- /dev/null +++ b/man/std::ofstream.3 @@ -0,0 +1,313 @@ +.TH std::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream \- std::basic_ofstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_ofstream : public std::basic_ostream + + The class template basic_ofstream implements high-level output operations on file + based streams. It interfaces a file-based streambuffer (std::basic_filebuf) with the + high-level interface of (std::basic_ostream). + + A typical implementation of std::basic_ofstream holds only one non-derived data + member: an instance of std::basic_filebuf. + + std-basic ofstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ofstream std::basic_ofstream + std::wofstream std::basic_ofstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is + not CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + native_handle_type(C++26) implementation-defined type that is TriviallyCopyable and + semiregular + +.SH Member functions + + constructor constructs the file stream + \fI(public member function)\fP + destructor destructs the basic_ofstream and the associated + \fB[virtual]\fP (implicitly declared) buffer, closes the file + \fI(virtual public member function)\fP + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw file device object + \fI(public member function)\fP + native_handle returns the underlying implementation-defined handle + (C++26) \fI(public member function)\fP +.SH File operations + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ofstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::string filename = "Test.b"; + { + std::ofstream ostrm(filename, std::ios::binary); + double d = 3.14; + ostrm.write(reinterpret_cast(&d), sizeof d); // binary output + ostrm << 123 << "abc" << '\\n'; // text output + } + + // read back + std::ifstream istrm(filename, std::ios::binary); + double d; + istrm.read(reinterpret_cast(&d), sizeof d); + int n; + std::string s; + istrm >> n >> s; + std::cout << " read back: " << d << ' ' << n << ' ' << s << '\\n'; + } + +.SH Output: + + read back: 3.14 123 abc diff --git a/man/std::ofstream::basic_ofstream.3 b/man/std::ofstream::basic_ofstream.3 deleted file mode 120000 index 8c9dd85ea..000000000 --- a/man/std::ofstream::basic_ofstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::basic_ofstream.3 \ No newline at end of file diff --git a/man/std::ofstream::basic_ofstream.3 b/man/std::ofstream::basic_ofstream.3 new file mode 100644 index 000000000..da7885226 --- /dev/null +++ b/man/std::ofstream::basic_ofstream.3 @@ -0,0 +1,105 @@ +.TH std::basic_ofstream::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::basic_ofstream \- std::basic_ofstream::basic_ofstream + +.SH Synopsis + basic_ofstream(); \fB(1)\fP + explicit basic_ofstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::out ); + explicit basic_ofstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + explicit basic_ofstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + template< class FsPath > + + explicit basic_ofstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + basic_ofstream( basic_ofstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ofstream( const basic_ofstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out) + (see std::basic_filebuf::open for the details on the effects of that call). If the + open() call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ofstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP Note that despite the default mode being out, the effects are + identical to the effects of out | trunc as described in std::filebuf::open + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ofstream f0; + std::ofstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ofstream f2(name); + std::ofstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::ofstream::close.3 b/man/std::ofstream::close.3 deleted file mode 120000 index aeefa2790..000000000 --- a/man/std::ofstream::close.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::close.3 \ No newline at end of file diff --git a/man/std::ofstream::close.3 b/man/std::ofstream::close.3 new file mode 100644 index 000000000..10d285365 --- /dev/null +++ b/man/std::ofstream::close.3 @@ -0,0 +1,41 @@ +.TH std::basic_ofstream::close 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::close \- std::basic_ofstream::close + +.SH Synopsis + void close(); + + Closes the associated file. + + Effectively calls rdbuf()->close(). If an error occurs during operation, + setstate(failbit) is called. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + \fI(none)\fP + +.SH Notes + + This function is called by the destructor of basic_ofstream when the stream object + goes out of scope and is not usually invoked directly. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + open opens a file and associates it with the stream + \fI(public member function)\fP + close flushes the put area buffer and closes the associated file + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ofstream::is_open.3 b/man/std::ofstream::is_open.3 deleted file mode 120000 index 26fdd95f8..000000000 --- a/man/std::ofstream::is_open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::is_open.3 \ No newline at end of file diff --git a/man/std::ofstream::is_open.3 b/man/std::ofstream::is_open.3 new file mode 100644 index 000000000..5a01690a2 --- /dev/null +++ b/man/std::ofstream::is_open.3 @@ -0,0 +1,42 @@ +.TH std::basic_ofstream::is_open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::is_open \- std::basic_ofstream::is_open + +.SH Synopsis + bool is_open() const; + + Checks if the file stream has an associated file. + + Effectively calls rdbuf()->is_open(). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the file stream has an associated file, false otherwise. + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 365 C++98 is_open was not declared with const qualifier declared with const + qualifier + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ofstream::native_handle.3 b/man/std::ofstream::native_handle.3 new file mode 100644 index 000000000..12d8567f1 --- /dev/null +++ b/man/std::ofstream::native_handle.3 @@ -0,0 +1,26 @@ +.TH std::basic_ofstream::native_handle 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::native_handle \- std::basic_ofstream::native_handle + +.SH Synopsis + native_handle_type native_handle() const noexcept; (since C++26) + + Returns the implementation defined underlying handle associated with basic_filebuf. + The behavior is undefined if is_open() is false. + +.SH Return value + + rdbuf()->native_handle() + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_fstream_native_handle 202306L (C++26) native handles support + +.SH Example + + This section is incomplete + Reason: example + +.SH Category: + * Todo with reason diff --git a/man/std::ofstream::ofstream.3 b/man/std::ofstream::ofstream.3 deleted file mode 120000 index 8c9dd85ea..000000000 --- a/man/std::ofstream::ofstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::basic_ofstream.3 \ No newline at end of file diff --git a/man/std::ofstream::ofstream.3 b/man/std::ofstream::ofstream.3 new file mode 100644 index 000000000..da7885226 --- /dev/null +++ b/man/std::ofstream::ofstream.3 @@ -0,0 +1,105 @@ +.TH std::basic_ofstream::basic_ofstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::basic_ofstream \- std::basic_ofstream::basic_ofstream + +.SH Synopsis + basic_ofstream(); \fB(1)\fP + explicit basic_ofstream( const char* filename, + + std::ios_base::openmode mode \fB(2)\fP + + = std::ios_base::out ); + explicit basic_ofstream( const std::filesystem::path::value_type* + filename, + \fB(3)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + explicit basic_ofstream( const std::string& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + template< class FsPath > + + explicit basic_ofstream( const FsPath& filename, \fB(5)\fP \fI(since C++17)\fP + std::ios_base::openmode mode + + = std::ios_base::out ); + basic_ofstream( basic_ofstream&& other ); \fB(6)\fP \fI(since C++11)\fP + basic_ofstream( const basic_ofstream& rhs ) = delete; \fB(7)\fP \fI(since C++11)\fP + + Constructs new file stream. + + 1) Default constructor: constructs a stream that is not associated with a file: + default-constructs the std::basic_filebuf and constructs the base with the pointer + to this default-constructed std::basic_filebuf member. + 2,3) First, performs the same steps as the default constructor, then associates the + stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out) + (see std::basic_filebuf::open for the details on the effects of that call). If the + open() call returns a null pointer, sets setstate(failbit). + Overload \fB(3)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 4,5) Same as basic_ofstream(filename.c_str(), mode). + \fB(5)\fP participates in overload resolution only if FsPath is std::filesystem::path. + \fI(since C++17)\fP Note that despite the default mode being out, the effects are + identical to the effects of out | trunc as described in std::filebuf::open + 6) Move constructor. First, move-constructs the base class from other (which does + not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, + then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer + in the base class. + 7) The copy-constructor is deleted: this class is not copyable. + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. Following constants and bit-wise OR between + them may be used: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another file stream to use as source + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ofstream f0; + std::ofstream f1("test.bin", std::ios::binary); + std::string name = "example.txt"; + std::ofstream f2(name); + std::ofstream f3(std::move(f1)); + } + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3430 C++17 std::filesystem::path overload led to avoided by making it + unwanted conversions a template + +.SH See also + + open opens a file and associates it with the stream + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + set_rdbuf replaces the rdbuf without clearing its error state + \fI(protected member function)\fP + constructor constructs the object + \fI(public member function of std::basic_ostream)\fP diff --git a/man/std::ofstream::open.3 b/man/std::ofstream::open.3 deleted file mode 120000 index 8cd5c2ea1..000000000 --- a/man/std::ofstream::open.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::open.3 \ No newline at end of file diff --git a/man/std::ofstream::open.3 b/man/std::ofstream::open.3 new file mode 100644 index 000000000..6a9ce65d0 --- /dev/null +++ b/man/std::ofstream::open.3 @@ -0,0 +1,84 @@ +.TH std::basic_ofstream::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::open \- std::basic_ofstream::open + +.SH Synopsis + void open( const char* filename, + + std::ios_base::openmode mode \fB(1)\fP + + = std::ios_base::out ); + void open( const std::filesystem::path::value_type* filename, + + std::ios_base::openmode mode \fB(2)\fP \fI(since C++17)\fP + + = std::ios_base::out ); + void open( const std::string& filename, + + std::ios_base::openmode mode \fB(3)\fP \fI(since C++11)\fP + + = std::ios_base::out ); + void open( const std::filesystem::path& filename, + + std::ios_base::openmode mode \fB(4)\fP \fI(since C++17)\fP + + = std::ios_base::out ); + + Opens and associates the file with name filename with the file stream. + + Calls clear() on success. Calls setstate(failbit) on failure. + + 1,2) Effectively calls rdbuf()->open(filename, mode | ios_base::out) (see + std::basic_filebuf::open for the details on the effects of that call). + Overload \fB(2)\fP is only provided if std::filesystem::path::value_type is not char. + \fI(since C++17)\fP + 3,4) Effectively calls (1,2) as if by open(filename.c_str(), mode). + +.SH Parameters + + filename - the name of the file to be opened + specifies stream open mode. It is a BitmaskType, the following constants + are defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + +.SH Return value + + \fI(none)\fP + +.SH Example + + This section is incomplete + Reason: no example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 22 C++98 it was unclear how error state changes upon a the error state is + successful open unchanged + LWG 409 C++98 the error state was unchanged upon a it is cleared^[1] + successful open + + 1. ↑ The resolution of LWG issue #22 is overriden. + +.SH See also + + is_open checks if the stream has an associated file + \fI(public member function)\fP + close closes the associated file + \fI(public member function)\fP + open opens a file and configures it as the associated character sequence + \fI(public member function of std::basic_filebuf)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ofstream::operator=.3 b/man/std::ofstream::operator=.3 deleted file mode 120000 index 299f7622b..000000000 --- a/man/std::ofstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::operator=.3 \ No newline at end of file diff --git a/man/std::ofstream::operator=.3 b/man/std::ofstream::operator=.3 new file mode 100644 index 000000000..ca3f0660e --- /dev/null +++ b/man/std::ofstream::operator=.3 @@ -0,0 +1,37 @@ +.TH std::basic_ofstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::operator= \- std::basic_ofstream::operator= + +.SH Synopsis + basic_ofstream& operator=( basic_ofstream&& other ); \fI(since C++11)\fP + + Move assigns the file stream other to *this, effectively move-assigning both the + std::basic_ostream base class and the associated std::basic_filebuf. + + other is left with no associated file. Note that the base class move assignment + swaps all stream state variables (except for rdbuf) between *this and other. + +.SH Parameters + + other - file stream to move + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two file streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_filebuf object + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ofstream::rdbuf.3 b/man/std::ofstream::rdbuf.3 deleted file mode 120000 index 65b579c1e..000000000 --- a/man/std::ofstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::ofstream::rdbuf.3 b/man/std::ofstream::rdbuf.3 new file mode 100644 index 000000000..e03acd59c --- /dev/null +++ b/man/std::ofstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_ofstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::rdbuf \- std::basic_ofstream::rdbuf + +.SH Synopsis + std::basic_filebuf* rdbuf() const; \fI(since C++11)\fP + + Returns pointer to the underlying raw file device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw file device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ofstream::swap.3 b/man/std::ofstream::swap.3 deleted file mode 120000 index 78859fc68..000000000 --- a/man/std::ofstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ofstream::swap.3 \ No newline at end of file diff --git a/man/std::ofstream::swap.3 b/man/std::ofstream::swap.3 new file mode 100644 index 000000000..14bbf7c8d --- /dev/null +++ b/man/std::ofstream::swap.3 @@ -0,0 +1,81 @@ +.TH std::basic_ofstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ofstream::swap \- std::basic_ofstream::swap + +.SH Synopsis + void swap( basic_ofstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_ostream::swap(other) and + rdbuf()->swap(other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + bool create_stream(std::fstream& fs, const std::string& path) + { + try + { + std::fstream ts{path, ts.trunc | ts.in | ts.out}; + if (ts.is_open()) + { + ts.swap(fs); // stream objects are not copyable + return true; + } + } + catch (...) + { + std::cout << "Exception!\\n"; + } + return false; + } + + void use_stream(std::fstream& fs) + { + fs.seekg(0); + std::string data; + fs >> data; + std::cout << "data: " << std::quoted(data) << '\\n'; + } + + int main() + { + std::fstream fs; + std::string path = "/tmp/test_file.txt"; + if (create_stream(fs, path)) + { + fs.write(path.c_str(), path.length()); + use_stream(fs); + } + } + +.SH Possible output: + + data: "/tmp/test_file.txt" + +.SH See also + + operator= moves the file stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_filebuf objects + \fI(C++11)\fP \fI(public member function of std::basic_filebuf)\fP diff --git a/man/std::once_flag.3 b/man/std::once_flag.3 index 3ce7cc86b..51af5f42c 100644 --- a/man/std::once_flag.3 +++ b/man/std::once_flag.3 @@ -1,4 +1,7 @@ -.TH std::once_flag 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::once_flag 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::once_flag \- std::once_flag + .SH Synopsis Defined in header class once_flag; \fI(since C++11)\fP @@ -9,13 +12,13 @@ allows those calls to coordinate with each other such that only one of the calls will actually run to completion. - std::once_flag is noncopyable. + std::once_flag is neither copyable nor movable. .SH Member functions - std::once_flag::once_flag +std::once_flag::once_flag - once_flag(); + constexpr once_flag() noexcept; Constructs an once_flag object. The internal state is set to indicate that no function has been called yet. @@ -24,13 +27,9 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also call_once invokes a function only once even if called from multiple threads - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + C documentation for + once_flag diff --git a/man/std::operator+(std::basic_string).3 b/man/std::operator+(std::basic_string).3 index 1d5f7ada0..b8174614d 100644 --- a/man/std::operator+(std::basic_string).3 +++ b/man/std::operator+(std::basic_string).3 @@ -1,137 +1,252 @@ -.TH std::operator+(std::basic_string) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::operator+(std::basic_string) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::operator+(std::basic_string) \- std::operator+(std::basic_string) + .SH Synopsis + Defined in header template< class CharT, class Traits, class Alloc > - basic_string \fB(1)\fP - operator+( const basic_string& lhs, + std::basic_string \fB(1)\fP (constexpr + operator+( const std::basic_string& lhs, since C++20) - const basic_string& rhs ); + const std::basic_string& rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(2)\fP - operator+( const CharT* lhs, + std::basic_string \fB(2)\fP (constexpr + operator+( const std::basic_string& lhs, since C++20) - const basic_string& rhs ); + const CharT* rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(3)\fP - operator+( CharT lhs, + std::basic_string \fB(3)\fP (constexpr + operator+( const std::basic_string& lhs, since C++20) - const basic_string& rhs ); + CharT rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(4)\fP - operator+( const basic_string& lhs, - - const CharT* rhs ); - template + constexpr std::basic_string (since + operator+( const std::basic_string& lhs, \fB(4)\fP C++26) - basic_string \fB(5)\fP - operator+( const basic_string& lhs, - CharT rhs ); + std::type_identity_t> rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(6)\fP \fI(since C++11)\fP - operator+( basic_string&& lhs, + std::basic_string \fB(5)\fP (constexpr + operator+( const CharT* lhs, since C++20) - const basic_string& rhs ); + const std::basic_string& rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(7)\fP \fI(since C++11)\fP - operator+( const basic_string& lhs, + std::basic_string \fB(6)\fP (constexpr + operator+( CharT lhs, since C++20) - basic_string&& rhs ); + const std::basic_string& rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(8)\fP \fI(since C++11)\fP - operator+( basic_string&& lhs, + constexpr std::basic_string (since + operator+( \fB(7)\fP C++26) + std::type_identity_t> lhs, - basic_string&& rhs ); + const std::basic_string& rhs ); template< class CharT, class Traits, class Alloc > - - basic_string \fB(9)\fP \fI(since C++11)\fP - operator+(const CharT* lhs, - - basic_string&& rhs ); + (since + std::basic_string \fB(8)\fP C++11) + operator+( std::basic_string&& lhs, (constexpr + since C++20) + std::basic_string&& rhs ); template< class CharT, class Traits, class Alloc > - - basic_string \fB(10)\fP \fI(since C++11)\fP - operator+( CharT lhs, - - basic_string&& rhs ); + (since + std::basic_string \fB(9)\fP C++11) + operator+( std::basic_string&& lhs, (constexpr + since C++20) + const std::basic_string& rhs ); + template< class CharT, class Traits, class Alloc > + (since + std::basic_string \fB(10)\fP C++11) + operator+( std::basic_string&& lhs, (constexpr + since C++20) + const CharT* rhs ); template< class CharT, class Traits, class Alloc > + (since + std::basic_string \fB(11)\fP C++11) + operator+( std::basic_string&& lhs, (constexpr + since C++20) + CharT rhs ); + template< class CharT, class Traits, class Alloc > + + constexpr std::basic_string (since + operator+( std::basic_string&& lhs, \fB(12)\fP C++26) - basic_string \fB(11)\fP \fI(since C++11)\fP - operator+( basic_string&& lhs, - const CharT* rhs ); + std::type_identity_t> rhs ); + template< class CharT, class Traits, class Alloc > + (since + std::basic_string \fB(13)\fP C++11) + operator+( const std::basic_string& lhs, (constexpr + since C++20) + std::basic_string&& rhs ); + template< class CharT, class Traits, class Alloc > + (since + std::basic_string \fB(14)\fP C++11) + operator+( const CharT* lhs, (constexpr + since C++20) + std::basic_string&& rhs ); + template< class CharT, class Traits, class Alloc > + (since + std::basic_string \fB(15)\fP C++11) + operator+( CharT lhs, (constexpr + since C++20) + std::basic_string&& rhs ); template< class CharT, class Traits, class Alloc > - basic_string \fB(12)\fP \fI(since C++11)\fP - operator+( basic_string&& lhs, + constexpr std::basic_string (since + operator+( \fB(16)\fP C++26) + std::type_identity_t> lhs, - CharT rhs ); + std::basic_string&& rhs ); Returns a string containing characters from lhs followed by the characters from rhs. + Equivalent to: + + 1,2) std::basic_string r = lhs; r.append(rhs); return r; + 3) std::basic_string r = lhs; r.push_back(rhs); return r; + 4) std::basic_string r = lhs; r.append(rhs); return r; + 5) std::basic_string r = rhs; r.insert(0, lhs); return r; + 6) std::basic_string r = rhs; r.insert(r.begin(), lhs); + return r; + 7) std::basic_string r = rhs; r.insert(0, lhs); return r; + 8) lhs.append(rhs); return std::move(lhs); except that both lhs and rhs are left in + valid but unspecified states. If lhs and rhs have equal allocators, the + implementation can move from either. + 9,10) lhs.append(rhs); return std::move(lhs); + 11) lhs.push_back(rhs); return std::move(lhs); + 12) lhs.append(rhs); return std::move(lhs); + 13,14) rhs.insert(0, lhs); return std::move(rhs); + 15) rhs.insert(rhs.begin(), lhs); return std::move(rhs); + 16) rhs.insert(0, lhs); return std::move(rhs); + +The allocator used for the result is: + +1-4) +std::allocator_traits::select_on_container_copy_construction(lhs.get_allocator()) +5-7) +std::allocator_traits::select_on_container_copy_construction(rhs.get_allocator()) +8-12) lhs.get_allocator() +13-16) rhs.get_allocator() + (since +In other words: C++11) + + * If one operand is a basic_string rvalue, its allocator is used. + * Otherwise, select_on_container_copy_construction is used on the allocator of the + lvalue basic_string operand. + +In each case, the left operand is preferred when both are basic_strings of the same +value category. + +For (8-16), all rvalue basic_string operands are left in valid but unspecified states. .SH Parameters - lhs - string, character, or pointer to the first character in a null-terminated - array - rhs - string, character, or pointer to the first character in a null-terminated - array + string + lhs - , string view + (since C++26), character, or pointer to the first character in a + null-terminated array + string + rhs - , string view + (since C++26), character, or pointer to the first character in a + null-terminated array .SH Return value - 1) basic_string(lhs).append(rhs) + A string containing characters from lhs followed by the characters from rhs + , using the allocator determined as above + \fI(since C++11)\fP. - 2) basic_string(lhs) + rhs +.SH Notes - 3) basic_string(1,lhs) + rhs +operator+ should be used with great caution when stateful allocators are involved +(such as when std::pmr::string is used) +\fI(since C++17)\fP. Prior to P1165R1, the allocator used for the result was determined by +historical accident and can vary from overload to overload for no apparent reason. +Moreover, for (1-5), the allocator propagation behavior varies across major standard +library implementations and differs from the behavior depicted in the standard. - 4) lhs + basic_string(rhs) +Because the allocator used by the result of operator+ is sensitive to value category, +operator+ is not associative with respect to allocator propagation: - 5) lhs + basic_string(1,rhs) +using my_string = std::basic_string, my_allocator>; +my_string cat(); +const my_string& dog(); (since + C++11) +my_string meow = /* ... */, woof = /* ... */; +meow + cat() + /* ... */; // uses select_on_container_copy_construction on meow's allocator +woof + dog() + /* ... */; // uses allocator of dog()'s return value instead - 6) std::move(lhs.append(rhs)) +meow + woof + meow; // uses select_on_container_copy_construction on meow's allocator +meow + (woof + meow); // uses SOCCC on woof's allocator instead - 7) std::move(rhs.insert(0, lhs)) +For a chain of operator+ invocations, the allocator used for the ultimate result may be +controlled by prepending an rvalue basic_string with the desired allocator: - 8) std::move(lhs.append(rhs)) or std::move(rhs.insert(0, lhs)) +// use my_favorite_allocator for the final result +my_string(my_favorite_allocator) + meow + woof + cat() + dog(); - 9) std::move(rhs.insert(0, lhs)) +For better and portable control over allocators, member functions like append, insert, and +operator+= should be used on a result string constructed with the desired allocator. - 10) std::move(rhs.insert(0, 1, lhs)) + The usage of std::type_identity_t as parameter in overloads \fB(4)\fP, \fB(7)\fP, \fB(12)\fP, + and \fB(16)\fP ensures that an object of type std::basic_string can always be concatenated to an object of a type T with an + implicit conversion to std::basic_string_view, and vice versa, (since + as per overload resolution rules. C++26) - 11) std::move(lhs.append(rhs)) - - 12) std::move(lhs.append(1, rhs)) + Feature-test macro Value Std Feature + __cpp_lib_string_view 202403 (C++26) Concatenation of strings and string + views, overloads \fB(4)\fP, \fB(7)\fP, \fB(12)\fP, \fB(16)\fP .SH Example - + // Run this code #include #include - + #include + int main() { std::string s1 = "Hello"; std::string s2 = "world"; - std::cout << s1 + ' ' + s2 + "!\\n"; + const char* end = "!\\n"; + std::cout << s1 + ' ' + s2 + end; + + std::string_view water{" Water"}; + #if __cpp_lib_string_view >= 202403 + std::cout << s1 + water + s2 << end; // overload (4), then (1) + #else + std::cout << s1 + std::string(water) + s2 << end; // OK, but less efficient + #endif } .SH Output: Hello world! + Hello Waterworld! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P1165R1 C++11 allocator propagation is haphazard and made more consistent + inconsistent .SH See also operator+= appends characters to the end - \fI(public member function)\fP + \fI(public member function)\fP append appends characters to the end - \fI(public member function)\fP + \fI(public member function)\fP insert inserts characters - \fI(public member function)\fP + \fI(public member function)\fP diff --git a/man/std::operator<<(std::basic_stacktrace).3 b/man/std::operator<<(std::basic_stacktrace).3 new file mode 100644 index 000000000..a4f420c6f --- /dev/null +++ b/man/std::operator<<(std::basic_stacktrace).3 @@ -0,0 +1,61 @@ +.TH std::operator<<(std::basic_stacktrace) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::operator<<(std::basic_stacktrace) \- std::operator<<(std::basic_stacktrace) + +.SH Synopsis + Defined in header + template< class Allocator > + std::ostream& operator<<( std::ostream& os, const (since C++23) + std::basic_stacktrace& st ); + + Inserts the description of st into the output stream os. Equivalent to return os << + std::to_string(st);. + +.SH Parameters + + os - an output stream + st - a basic_stacktrace whose description is to be inserted + +.SH Return value + + os. + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << "The stacktrace obtained in the main function:\\n"; + std::cout << std::stacktrace::current() << '\\n'; + []{ + std::cout << "The stacktrace obtained in a nested lambda:\\n"; + std::cout << std::stacktrace::current() << '\\n'; + }(); + } + +.SH Possible output: + + The stacktrace obtained in the main function: + 0# 0x0000000000402E7B in ./prog.exe + 1# __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 2# 0x0000000000402CD9 in ./prog.exe + + The stacktrace obtained in a nested lambda: + 0# 0x0000000000402DDA in ./prog.exe + 1# 0x0000000000402EB2 in ./prog.exe + 2# __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 3# 0x0000000000402CD9 in ./prog.exe + +.SH See also + + operator<< performs stream output of stacktrace_entry + (C++23) \fI(function template)\fP diff --git a/man/std::operator<<(std::error_code).3 b/man/std::operator<<(std::error_code).3 index 8e7d6f9dd..245bf0cc4 100644 --- a/man/std::operator<<(std::error_code).3 +++ b/man/std::operator<<(std::error_code).3 @@ -1,16 +1,19 @@ -.TH std::operator<<(std::error_code) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::operator<<(std::error_code) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::operator<<(std::error_code) \- std::operator<<(std::error_code) + .SH Synopsis Defined in header template< class CharT, class Traits > - std::basic_ostream& \fI(since C++11)\fP + std::basic_ostream& \fI(since C++11)\fP - operator<<( basic_ostream& os, const error_code& ec - ); + operator<<( basic_ostream& os, const error_code& + ec ); Performs stream output operation on error code ec. - Equivalent to os << ec.category().name() << ’:’ << ec.value. + Equivalent to os << ec.category().name() << ':' << ec.value(). .SH Parameters diff --git a/man/std::operator<<(std::stacktrace_entry).3 b/man/std::operator<<(std::stacktrace_entry).3 new file mode 100644 index 000000000..23ec3ed6b --- /dev/null +++ b/man/std::operator<<(std::stacktrace_entry).3 @@ -0,0 +1,49 @@ +.TH std::operator<<(std::stacktrace_entry) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::operator<<(std::stacktrace_entry) \- std::operator<<(std::stacktrace_entry) + +.SH Synopsis + Defined in header + std::ostream& operator<<( std::ostream& os, const (since C++23) + std::stacktrace_entry& f ); + + Inserts the description of f into the output stream os. Equivalent to return os << + std::to_string(f);. + +.SH Parameters + + os - an output stream + f - a stacktrace_entry whose description is to be inserted + +.SH Return value + + os + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + for (const auto& f : std::stacktrace::current()) + std::cout << f << '\\n'; + } + +.SH Possible output: + + 0x0000000000402AA7 in ./prog.exe + __libc_start_main in /lib/x86_64-linux-gnu/libc.so.6 + 0x00000000004029B9 in ./prog.exe + +.SH See also + + operator<< performs stream output of basic_stracktrace + (C++23) \fI(function template)\fP diff --git a/man/std::operator==,!=,(std::error_code).3 b/man/std::operator==,!=,(std::error_code).3 new file mode 100644 index 000000000..20a6ab903 --- /dev/null +++ b/man/std::operator==,!=,(std::error_code).3 @@ -0,0 +1,52 @@ +.TH std::operator==,!=,(std::error_code) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::operator==,!=,(std::error_code) \- std::operator==,!=,(std::error_code) + +.SH Synopsis + Defined in header + bool operator==( const std::error_code& lhs, \fB(1)\fP \fI(since C++11)\fP + const std::error_code& rhs ) noexcept; + bool operator!=( const std::error_code& lhs, \fB(2)\fP \fI(since C++11)\fP + const std::error_code& rhs ) noexcept; \fI(until C++20)\fP + bool operator<( const std::error_code& lhs, \fB(3)\fP \fI(since C++11)\fP + const std::error_code& rhs ) noexcept; \fI(until C++20)\fP + std::strong_ordering operator<=>( const std::error_code& lhs, + const std::error_code& rhs ) \fB(4)\fP \fI(since C++20)\fP + noexcept; + + Compares two error code objects. + + 1) Compares lhs and rhs for equality. + 2) Compares lhs and rhs for equality. + 3) Checks whether lhs is less than rhs. + 4) Obtains three-way comparison result of lhs and rhs. + + The <, <=, >, >=, and != operators are synthesized from operator<=> \fI(since C++20)\fP + and operator== respectively. + +.SH Parameters + + lhs, rhs - error codes to compare + +.SH Return value + + 1) true if the error category and error value compare equal. + 2) true if the error category or error value compare are not equal. + 3) true if lhs.category() < rhs.category(). Otherwise, true if lhs.category() == + rhs.category() && lhs.value() < rhs.value(). Otherwise, false. + 4) lhs.category() <=> rhs.category() if it is not std::strong_ordering::equal. + Otherwise, lhs.value() <=> rhs.value(). + +.SH See also + + category obtains the error_category for this error_code + \fI(public member function)\fP + value obtains the value of the error_code + \fI(public member function)\fP + operator== + operator!= + operator< compares error_conditions and error_codes + operator<=> \fI(function)\fP + (removed in C++20) + (removed in C++20) + (C++20) diff --git a/man/std::operator==,!=,<(std::error_code).3 b/man/std::operator==,!=,<(std::error_code).3 deleted file mode 100644 index 6fcc7ef11..000000000 --- a/man/std::operator==,!=,<(std::error_code).3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH std::operator==,!=,<(std::error_code) 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" -.SH Synopsis - Defined in header - bool operator==( const error_code& lhs, const error_code& rhs ); \fB(1)\fP \fI(since C++11)\fP - bool operator!=( const error_code& lhs, const error_code& rhs ); \fB(1)\fP \fI(since C++11)\fP - bool operator<( const error_code& lhs, const error_code& rhs ); \fB(1)\fP \fI(since C++11)\fP - - Compares two error code objects. - - 1) Compares lhs and rhs for equality. - 2) Compares lhs and rhs for equality. - 3) Checks whether lhs is less than rhs. - -.SH Parameters - - lhs, rhs - error codes to compare - -.SH Return value - - 1) true if the error category and error value compare equal. - 2) true if the error category or error value compare are not equal. - 3) true if lhs.category() < rhs.category(). Otherwise, true if lhs.category() == - rhs.category() && lhs.value() < rhs.value(). Otherwise, false - -.SH Exceptions - - noexcept specification: - noexcept - - -.SH See also - - category obtains the error_category for this error_code - \fI(public member function)\fP diff --git a/man/std::optional.3 b/man/std::optional.3 new file mode 100644 index 000000000..331cedc83 --- /dev/null +++ b/man/std::optional.3 @@ -0,0 +1,189 @@ +.TH std::optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional \- std::optional + +.SH Synopsis + Defined in header + template< class T > \fI(since C++17)\fP + class optional; + + The class template std::optional manages an optional contained value, i.e. a value + that may or may not be present. + + A common use case for optional is the return value of a function that may fail. As + opposed to other approaches, such as std::pair, optional handles + expensive-to-construct objects well and is more readable, as the intent is expressed + explicitly. + + Any instance of optional at any given point in time either contains a value or + does not contain a value. + + If an optional contains a value, the value is guaranteed to be allocated as part + of the optional object footprint, i.e. no dynamic memory allocation ever takes + place. Thus, an optional object models an object, not a pointer, even though + operator*() and operator->() are defined. + + When an object of type optional is contextually converted to bool, the conversion + returns true if the object contains a value and false if it does not contain a + value. + + The optional object contains a value in the following conditions: + + * The object is initialized with/assigned from a value of type T or another + optional that contains a value. + + The object does not contain a value in the following conditions: + + * The object is default-initialized. + * The object is initialized with/assigned from a value of type std::nullopt_t or + an optional object that does not contain a value. + * The member function reset() is called. + + There are no optional references, functions, arrays, or cv void; a program is + ill-formed if it instantiates an optional with such a type. In addition, a program + is ill-formed if it instantiates an optional with the (possibly cv-qualified) tag + types std::nullopt_t or std::in_place_t. + +.SH Template parameters + + the type of the value to manage initialization state for. The type must meet the + T - requirements of Destructible (in particular, array and reference types are not + allowed). + +.SH Member types + + Member type Definition + value_type T + +.SH Member functions + + constructor constructs the optional object + \fI(public member function)\fP + destructor destroys the contained value, if there is one + \fI(public member function)\fP + operator= assigns contents + \fI(public member function)\fP +.SH Observers + operator-> accesses the contained value + operator* \fI(public member function)\fP + operator bool checks whether the object contains a value + has_value \fI(public member function)\fP + value returns the contained value + \fI(public member function)\fP + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP + Monadic operations + and_then returns the result of the given function on the contained value if it + (C++23) exists, or an empty optional otherwise + \fI(public member function)\fP + transform returns an optional containing the transformed contained value if it + (C++23) exists, or an empty optional otherwise + \fI(public member function)\fP + or_else returns the optional itself if it contains a value, or the result of + (C++23) the given function otherwise + \fI(public member function)\fP +.SH Modifiers + swap exchanges the contents + \fI(public member function)\fP + reset destroys any contained value + \fI(public member function)\fP + emplace constructs the contained value in-place + \fI(public member function)\fP + +.SH Non-member functions + + operator== + operator!= + operator< + operator<= + operator> + operator>= + operator<=> compares optional objects + \fI(C++17)\fP \fI(function template)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + \fI(C++17)\fP + (C++20) + make_optional creates an optional object + \fI(C++17)\fP \fI(function template)\fP + std::swap(std::optional) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function template)\fP + +.SH Helper classes + + std::hash hash support for std::optional + \fI(C++17)\fP \fI(class template specialization)\fP + nullopt_t indicator of optional type with uninitialized state + \fI(C++17)\fP \fI(class)\fP + bad_optional_access exception indicating checked access to an optional that + \fI(C++17)\fP doesn't contain a value + \fI(class)\fP + + Helpers + + nullopt an object of type nullopt_t + \fI(C++17)\fP (constant) + in_place + in_place_type + in_place_index in-place construction tag + in_place_t (tag) + in_place_type_t + in_place_index_t + \fI(C++17)\fP + + Deduction guides + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_optional 201606L \fI(C++17)\fP std::optional + __cpp_lib_optional 202106L (C++20) Fully constexpr + (DR) + __cpp_lib_optional 202110L (C++23) Monadic operations + +.SH Example + + +// Run this code + + #include + #include + #include + + // optional can be used as the return type of a factory that may fail + std::optional create(bool b) + { + if (b) + return "Godzilla"; + return {}; + } + + // std::nullopt can be used to create any (empty) std::optional + auto create2(bool b) + { + return b ? std::optional{"Godzilla"} : std::nullopt; + } + + int main() + { + std::cout << "create(false) returned " + << create(false).value_or("empty") << '\\n'; + + // optional-returning factory functions are usable as conditions of while and if + if (auto str = create2(true)) + std::cout << "create2(true) returned " << *str << '\\n'; + } + +.SH Output: + + create(false) returned empty + create2(true) returned Godzilla + +.SH See also + + variant a type-safe discriminated union + \fI(C++17)\fP \fI(class template)\fP + any objects that hold instances of any CopyConstructible type + \fI(C++17)\fP \fI(class)\fP diff --git a/man/std::optional::and_then.3 b/man/std::optional::and_then.3 new file mode 100644 index 000000000..a9b7795b8 --- /dev/null +++ b/man/std::optional::and_then.3 @@ -0,0 +1,140 @@ +.TH std::optional::and_then 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::and_then \- std::optional::and_then + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr auto and_then( F&& f ) &; + template< class F > \fB(2)\fP (since C++23) + constexpr auto and_then( F&& f ) const&; + template< class F > \fB(3)\fP (since C++23) + constexpr auto and_then( F&& f ) &&; + template< class F > \fB(4)\fP (since C++23) + constexpr auto and_then( F&& f ) const&&; + + If *this contains a value, invokes f with the contained value as an argument, and + returns the result of that invocation; otherwise, returns an empty std::optional. + + The return type (see below) must be a specialization of std::optional (unlike + transform()). Otherwise, the program is ill-formed. + + 1) Equivalent to + + if (*this) + return std::invoke(std::forward(f), **this); + else + return std::remove_cvref_t>{}; + + 2) Equivalent to + + if (*this) + return std::invoke(std::forward(f), **this); + else + return std::remove_cvref_t>{}; + + 3) Equivalent to + + if (*this) + return std::invoke(std::forward(f), std::move(**this)); + else + return std::remove_cvref_t>{}; + + 4) Equivalent to + + if (*this) + return std::invoke(std::forward(f), std::move(**this)); + else + return std::remove_cvref_t>{}; + +.SH Parameters + + f - a suitable function or Callable object that returns an std::optional + +.SH Return value + + The result of f or an empty std::optional, as described above. + +.SH Notes + + Some languages call this operation flatmap. + + Feature-test macro Value Std Feature + __cpp_lib_optional 202110L (C++23) Monadic operations in std::optional + +.SH Example + + +// Run this code + + #include + #include + #include + #include + #include + #include + #include + #include + + std::optional to_int(std::string_view sv) + { + int r{}; + auto [ptr, ec]{std::from_chars(sv.data(), sv.data() + sv.size(), r)}; + if (ec == std::errc()) + return r; + else + return std::nullopt; + } + + int main() + { + using namespace std::literals; + + const std::vector> v + { + "1234", "15 foo", "bar", "42", "5000000000", " 5", std::nullopt, "-43" + }; + + for (auto&& x : v | std::views::transform( + [](auto&& o) + { + // debug print the content of input optional + std::cout << std::left << std::setw(13) + << std::quoted(o.value_or("nullopt")) << " -> "; + + return o + // if optional is nullopt convert it to optional with "" string + .or_else([]{ return std::optional{""s}; }) + // flatmap from strings to ints (making empty optionals where it fails) + .and_then(to_int) + // map int to int + 1 + .transform([](int n) { return n + 1; }) + // convert back to strings + .transform([](int n) { return std::to_string(n); }) + // replace all empty optionals that were left by + // and_then and ignored by transforms with "NaN" + .value_or("NaN"s); + })) + std::cout << x << '\\n'; + } + +.SH Output: + + "1234" -> 1235 + "15 foo" -> 16 + "bar" -> NaN + "42" -> 43 + "5000000000" -> NaN + " 5" -> NaN + "nullopt" -> NaN + "-43" -> -42 + +.SH See also + + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP + transform returns an optional containing the transformed contained value if it + (C++23) exists, or an empty optional otherwise + \fI(public member function)\fP + or_else returns the optional itself if it contains a value, or the result of the + (C++23) given function otherwise + \fI(public member function)\fP diff --git a/man/std::optional::emplace.3 b/man/std::optional::emplace.3 new file mode 100644 index 000000000..085682f3d --- /dev/null +++ b/man/std::optional::emplace.3 @@ -0,0 +1,116 @@ +.TH std::optional::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::emplace \- std::optional::emplace + +.SH Synopsis + template< class... Args > \fB(1)\fP \fI(since C++17)\fP + T& emplace( Args&&... args ); (constexpr since C++20) + template< class U, class... Args > \fI(since C++17)\fP + T& emplace( std::initializer_list ilist, Args&&... \fB(2)\fP (constexpr since C++20) + args ); + + Constructs the contained value in-place. If *this already contains a value before + the call, the contained value is destroyed by calling its destructor. + + 1) Initializes the contained value by direct-initializing (but not + direct-list-initializing) with std::forward(args)... as parameters. + 2) Initializes the contained value by calling its constructor with ilist, + std::forward(args)... as parameters. This overload participates in overload + resolution only if std::is_constructible&, + Args&&...>::value is true. + +.SH Parameters + + args... - the arguments to pass to the constructor + ilist - the initializer list to pass to the constructor +.SH Type requirements + - + T must be constructible from Args... for overload \fB(1)\fP + - + T must be constructible from std::initializer_list and Args... for overload \fB(2)\fP + +.SH Return value + + A reference to the new contained value. + +.SH Exceptions + + Any exception thrown by the selected constructor of T. If an exception is thrown, + *this does not contain a value after this call (the previously contained value, if + any, had been destroyed). + +.SH Example + + +// Run this code + + #include + #include + + struct A + { + std::string s; + + A(std::string str) : s(std::move(str)), id{n++} { note("+ constructed"); } + ~A() { note("~ destructed"); } + A(const A& o) : s(o.s), id{n++} { note("+ copy constructed"); } + A(A&& o) : s(std::move(o.s)), id{n++} { note("+ move constructed"); } + + A& operator=(const A& other) + { + s = other.s; + note("= copy assigned"); + return *this; + } + + A& operator=(A&& other) + { + s = std::move(other.s); + note("= move assigned"); + return *this; + } + + inline static int n{}; + int id{}; + void note(auto s) { std::cout << " " << s << " #" << id << '\\n'; } + }; + + int main() + { + std::optional opt; + + std::cout << "Assign:\\n"; + opt = A("Lorem ipsum dolor sit amet, consectetur adipiscing elit nec."); + + std::cout << "Emplace:\\n"; + // As opt contains a value it will also destroy that value + opt.emplace("Lorem ipsum dolor sit amet, consectetur efficitur."); + + std::cout << "End example\\n"; + } + +.SH Output: + + Assign: + + constructed #0 + + move constructed #1 + ~ destructed #0 + Emplace: + ~ destructed #1 + + constructed #2 + End example + ~ destructed #2 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 emplace was not constexpr while the required made constexpr + operations can be constexpr in C++20 + +.SH See also + + operator= assigns contents + \fI(public member function)\fP diff --git a/man/std::optional::operator->,std::optional::operator*.3 b/man/std::optional::operator->,std::optional::operator*.3 new file mode 100644 index 000000000..6aee0da39 --- /dev/null +++ b/man/std::optional::operator->,std::optional::operator*.3 @@ -0,0 +1,86 @@ +.TH std::optional::operator->,std::optional::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::operator->,std::optional::operator* \- std::optional::operator->,std::optional::operator* + +.SH Synopsis + constexpr const T* operator->() const noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr T* operator->() noexcept; \fB(1)\fP \fI(since C++17)\fP + constexpr const T& operator*() const& noexcept; \fB(2)\fP \fI(since C++17)\fP + constexpr T& operator*() & noexcept; \fB(2)\fP \fI(since C++17)\fP + constexpr const T&& operator*() const&& noexcept; \fB(2)\fP \fI(since C++17)\fP + constexpr T&& operator*() && noexcept; \fB(2)\fP \fI(since C++17)\fP + + Accesses the contained value. + + 1) Returns a pointer to the contained value. + 2) Returns a reference to the contained value. + + The behavior is undefined if *this does not contain a value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer or reference to the contained value. + +.SH Notes + + This operator does not check whether the optional contains a value! You can do so + manually by using has_value() or simply operator bool(). Alternatively, if checked + access is needed, value() or value_or() may be used. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + using namespace std::string_literals; + + std::optional opt1 = 1; + std::cout << "opt1: " << *opt1 << '\\n'; + + *opt1 = 2; + std::cout << "opt1: " << *opt1 << '\\n'; + + std::optional opt2 = "abc"s; + std::cout << "opt2: " << std::quoted(*opt2) << ", size: " << opt2->size() << '\\n'; + + // You can "take" the contained value by calling operator* on an rvalue to optional + + auto taken = *std::move(opt2); + std::cout << "taken: " << std::quoted(taken) << "\\n" + "opt2: " << std::quoted(*opt2) << ", size: " << opt2->size() << '\\n'; + } + +.SH Output: + + opt1: 1 + opt1: 2 + opt2: "abc", size: 3 + taken: "abc" + opt2: "", size: 0 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2762 C++17 operator-> and operator* might be made noexcept + potentially-throwing + +.SH See also + + value returns the contained value + \fI(public member function)\fP + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP diff --git a/man/std::optional::operator=.3 b/man/std::optional::operator=.3 new file mode 100644 index 000000000..a9fce18c4 --- /dev/null +++ b/man/std::optional::operator=.3 @@ -0,0 +1,150 @@ +.TH std::optional::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::operator= \- std::optional::operator= + +.SH Synopsis + optional& operator=( std::nullopt_t ) noexcept; \fB(1)\fP \fI(since C++17)\fP + (constexpr since C++20) + constexpr optional& operator=( const optional& other ); \fB(2)\fP \fI(since C++17)\fP + constexpr optional& operator=( optional&& other ) \fB(3)\fP \fI(since C++17)\fP + noexcept(/* see below */); + template< class U = T > \fB(4)\fP \fI(since C++17)\fP + optional& operator=( U&& value ); (constexpr since C++20) + template< class U > \fB(5)\fP \fI(since C++17)\fP + optional& operator=( const optional& other ); (constexpr since C++20) + template< class U > \fB(6)\fP \fI(since C++17)\fP + optional& operator=( optional&& other ); (constexpr since C++20) + + Replaces contents of *this with the contents of other. + + 1) If *this contains a value before the call, the contained value is destroyed by + calling its destructor as if by value().T::~T(). *this does not contain a value + after this call. + 2,3) Assigns the state of other. + * If both *this and other do not contain a value, the function has no effect. + * If *this contains a value, but other does not, then the contained value is + destroyed by calling its destructor. *this does not contain a value after the + call. + * If other contains a value, then depending on whether *this contains a value, the + contained value is either direct-initialized or assigned from *other \fB(2)\fP or + std::move(*other) \fB(3)\fP. Note that a moved-from optional still contains a value. + * Overload \fB(2)\fP is deleted when either std::is_copy_constructible_v or + std::is_copy_assignable_v is false. It is trivial if + std::is_trivially_copy_constructible_v, + std::is_trivially_copy_assignable_v and std::is_trivially_destructible_v + are all true. + * Overload \fB(3)\fP does not participate in overload resolution when either + std::is_move_constructible_v or std::is_move_assignable_v is false. It is + trivial if std::is_trivially_move_constructible_v, + std::is_trivially_move_assignable_v and std::is_trivially_destructible_v + are all true. + 4) Perfect-forwarded assignment: depending on whether *this contains a value before + the call, the contained value is either direct-initialized from + std::forward(value) or assigned from std::forward(value). The function does + not participate in overload resolution unless + std::decay_t + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP is not std::optional, std::is_constructible_v is true, + std::is_assignable_v is true, and at least one of the following is true: + * T is not a scalar type; + * std::decay_t is not T. + 5,6) Assigns the state of other. + * If both *this and other do not contain a value, the function has no effect. + * If *this contains a value, but other does not, then the contained value is + destroyed by calling its destructor. *this does not contain a value after the + call. + * If other contains a value, then depending on whether *this contains a value, the + contained value is either direct-initialized or assigned from *other \fB(5)\fP or + std::move(*other) \fB(6)\fP. Note that a moved-from optional still contains a value. + * These overloads do not participate in overload resolution unless the following + conditions are met: + * T is not constructible, convertible, or assignable from any expression of + type (possibly const) std::optional, i.e., the following 12 type traits + are all false: + * std::is_constructible_v&> + * std::is_constructible_v&> + * std::is_constructible_v&&> + * std::is_constructible_v&&> + * std::is_convertible_v&, T> + * std::is_convertible_v&, T> + * std::is_convertible_v&&, T> + * std::is_convertible_v&&, T> + * std::is_assignable_v&> + * std::is_assignable_v&> + * std::is_assignable_v&&> + * std::is_assignable_v&&> + * For overload \fB(5)\fP, std::is_constructible_v and + std::is_assignable_v are both true. + * For overload \fB(6)\fP, std::is_constructible_v and + std::is_assignable_v are both true. + +.SH Parameters + + other - another optional object whose contained value to assign + value - value to assign to the contained value + +.SH Return value + + *this + +.SH Exceptions + + 2-6) Throws any exception thrown by the constructor or assignment operator of T. If + an exception is thrown, the initialization state of *this (and of other in case of + (2,3) and (5,6)) is unchanged, i.e. if the object contained a value, it still + contains a value, and the other way round. The contents of value and the contained + values of *this and other depend on the exception safety guarantees of the operation + from which the exception originates (copy-constructor, move-assignment, etc.). + 3) Has following + noexcept specification: + noexcept(std::is_nothrow_move_assignable_v && + std::is_nothrow_move_constructible_v) + +.SH Notes + + An optional object op may be turned into an empty optional with both op = {}; and op + = nullopt;. The first expression constructs an empty optional object with {} and + assigns it to op. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::optional s1 = "abc", s2; // constructor + s2 = s1; // assignment + s1 = "def"; // decaying assignment (U = char[4], T = const char*) + std::cout << *s2 << ' ' << *s1 << '\\n'; + } + +.SH Output: + + abc def + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + copy/move assignment operator may not be required to propagate + P0602R4 C++17 trivial triviality + even if underlying operations are trivial + converting assignment operators were not + P2231R1 C++20 constexpr made constexpr + while the required operations can be in + C++20 + +.SH See also + + emplace constructs the contained value in-place + \fI(public member function)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::optional::operatorbool,std::optional::has_value.3 b/man/std::optional::operatorbool,std::optional::has_value.3 new file mode 100644 index 000000000..c59d922b4 --- /dev/null +++ b/man/std::optional::operatorbool,std::optional::has_value.3 @@ -0,0 +1,51 @@ +.TH std::optional::operatorbool,std::optional::has_value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::operatorbool,std::optional::has_value \- std::optional::operatorbool,std::optional::has_value + +.SH Synopsis + constexpr explicit operator bool() const noexcept; \fI(since C++17)\fP + constexpr bool has_value() const noexcept; \fI(since C++17)\fP + + Checks whether *this contains a value. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if *this contains a value, false if *this does not contain a value. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout << std::boolalpha; + + std::optional opt; + std::cout << opt.has_value() << '\\n'; + + opt = 43; + if (opt) + std::cout << "value set to " << opt.value() << '\\n'; + else + std::cout << "value not set\\n"; + + opt.reset(); + if (opt.has_value()) + std::cout << "value still set to " << opt.value() << '\\n'; + else + std::cout << "value no longer set\\n"; + } + +.SH Output: + + false + value set to 43 + value no longer set diff --git a/man/std::optional::optional.3 b/man/std::optional::optional.3 new file mode 100644 index 000000000..d41473230 --- /dev/null +++ b/man/std::optional::optional.3 @@ -0,0 +1,230 @@ +.TH std::optional::optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::optional \- std::optional::optional + +.SH Synopsis + constexpr optional() noexcept; (since + constexpr optional( std::nullopt_t ) \fB(1)\fP C++17) + noexcept; + constexpr optional( const optional& other \fB(2)\fP (since + ); C++17) + constexpr optional( optional&& other ) \fB(3)\fP (since + noexcept(/* see below */); C++17) + \fI(since C++17)\fP + template < class U > \fI(until C++20)\fP + optional( const optional& other ); (conditionally + explicit) + template < class U > \fI(since C++20)\fP + constexpr optional( const optional& (conditionally + other ); explicit) + \fI(since C++17)\fP + template < class U > \fI(until C++20)\fP + optional( optional&& other ); (conditionally + explicit) + template < class U > \fI(since C++20)\fP + constexpr optional( optional&& other ); (conditionally + explicit) + template< class... Args > \fB(4)\fP + constexpr explicit optional( \fB(6)\fP \fI(since C++17)\fP + std::in_place_t, Args&&... args ); + template< class U, class... Args > \fB(5)\fP + + constexpr explicit optional( + std::in_place_t, + \fB(7)\fP \fI(since C++17)\fP + std::initializer_list ilist, + + Args&&... + args ); + template < class U = T > \fI(since C++17)\fP + constexpr optional( U&& value ); \fB(8)\fP (conditionally + explicit) + + Constructs a new optional object. + + 1) Constructs an object that does not contain a value. + 2) Copy constructor: If other contains a value, initializes the contained value as + if direct-initializing (but not direct-list-initializing) an object of type T with + the expression *other. If other does not contain a value, constructs an object that + does not contain a value. + * This constructor is defined as deleted if std::is_copy_constructible_v is + false. + * It is a trivial constructor if std::is_trivially_copy_constructible_v is + true. + 3) Move constructor: If other contains a value, initializes the contained value as + if direct-initializing (but not direct-list-initializing) an object of type T with + the expression std::move(*other) and does not make other empty: a moved-from + std::optional still contains a value, but the value itself is moved from. If other + does not contain a value, constructs an object that does not contain a value. + * This constructor does not participate in overload resolution unless + std::is_move_constructible_v is true. + * It is a trivial constructor if std::is_trivially_move_constructible_v is + true. + 4) Converting copy constructor: If other does not contain a value, constructs an + optional object that does not contain a value. Otherwise, constructs an optional + object that contains a value, initialized as if direct-initializing (but not + direct-list-initializing) an object of type T with the expression *other. + * This constructor does not participate in overload resolution unless the + following conditions are met: + * std::is_constructible_v is true. + * If T is not (possibly cv-qualified) bool, T is not constructible or + convertible from any expression of type (possibly const) std::optional, + i.e., the following 8 values are all false: + * std::is_constructible_v&> + * std::is_constructible_v&> + * std::is_constructible_v&&> + * std::is_constructible_v&&> + * std::is_convertible_v&, T> + * std::is_convertible_v&, T> + * std::is_convertible_v&&, T> + * std::is_convertible_v&&, T> + * This constructor is explicit if and only if std::is_convertible_v + is false. + 5) Converting move constructor: If other does not contain a value, constructs an + optional object that does not contain a value. Otherwise, constructs an optional + object that contains a value, initialized as if direct-initializing (but not + direct-list-initializing) an object of type T with the expression std::move(*other). + * This constructor does not participate in overload resolution unless the + following conditions are met: + * std::is_constructible_v is true. + * If T is not (possibly cv-qualified) bool, T is not constructible or + convertible from any expression of type (possibly const) std::optional, + i.e., the following 8 values are all false: + * std::is_constructible_v&> + * std::is_constructible_v&> + * std::is_constructible_v&&> + * std::is_constructible_v&&> + * std::is_convertible_v&, T> + * std::is_convertible_v&, T> + * std::is_convertible_v&&, T> + * std::is_convertible_v&&, T> + * This constructor is explicit if and only if std::is_convertible_v is + false. + 6) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T from the + arguments std::forward(args).... + * If the selected constructor of T is a constexpr constructor, this constructor is + a constexpr constructor. + * The function does not participate in the overload resolution unless + std::is_constructible_v is true. + 7) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T from the + arguments ilist, std::forward(args).... + * If the selected constructor of T is a constexpr constructor, this constructor is + a constexpr constructor. + * The function does not participate in the overload resolution unless + std::is_constructible_v&, Args...> is true. + 8) Constructs an optional object that contains a value, initialized as if + direct-initializing (but not direct-list-initializing) an object of type T with the + expression std::forward(value). + * If the selected constructor of T is a constexpr constructor, this constructor is + a constexpr constructor. + * This constructor does not participate in overload resolution unless the + following conditions are met: + * std::is_constructible_v is true. + * std::decay_t + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP is neither std::in_place_t nor std::optional. + * If T is (possibly cv-qualified) bool, + std::decay_t + \fI(until C++20)\fP + std::remove_cvref_t + \fI(since C++20)\fP is not a specialization of std::optional. + * This constructor is explicit if and only if std::is_convertible_v is + false. + +.SH Parameters + + other - another optional object whose contained value is copied + value - value with which to initialize the contained value + args... - arguments with which to initialize the contained value + ilist - initializer list with which to initialize the contained value + +.SH Exceptions + + 2) Throws any exception thrown by the constructor of T. + 3) Throws any exception thrown by the constructor of T. Has the following + noexcept specification: + noexcept(std::is_nothrow_move_constructible::value) + 4-8) Throws any exception thrown by the constructor of T. + + Deduction guides + +.SH Notes + + Before the resolution of LWG issue 3836, constructing an std::optional from + std::optional would select overload \fB(8)\fP instead of overloads (4,5) if U is not + bool. This is because overloads (4,5) did not participate in overload resolution if + T (bool in this case) can be constructed or converted from std::optional, but + std::optional::operator bool makes the conversion possible for any U. + + As a result, the constructed std::optional always contains a value. That value + is determined by whether the provided std::optional object contains a value, + rather than the bool value direct-initialized from the contained value: + + std::optional op_false(false); + std::optional op_zero\fB(0)\fP; + + std::optional from_bool(op_false); // OK: contains 0 (initialized from false) + std::optional from_int(op_0); // DEFECT (LWG 3836): contains true + // because op_0 contains a value, even if + // initializing bool from that value gives false + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::optional o1, // empty + o2 = 1, // init from rvalue + o3 = o2; // copy-constructor + + // calls std::string( initializer_list ) constructor + std::optional o4(std::in_place, {'a', 'b', 'c'}); + + // calls std::string( size_type count, CharT ch ) constructor + std::optional o5(std::in_place, 3, 'A'); + + // Move-constructed from std::string using deduction guide to pick the type + + std::optional o6(std::string{"deduction"}); + + std::cout << *o2 << ' ' << *o3 << ' ' << *o4 << ' ' << *o5 << ' ' << *o6 << '\\n'; + } + +.SH Output: + + 1 1 abc AAA deduction + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + when constructing an std::optional always selects the + LWG 3836 C++17 from std::optional, the overload converting copy/move + resolution constructor in this + would select overload \fB(8)\fP if U is not bool case + copy/move constructors might not be required to + P0602R4 C++17 trivial propagate triviality + even if underlying constructor is trivial + converting constructors from another + P2231R1 C++20 std::optional was made constexpr + not constexpr while the required + operations can be in C++20 + +.SH See also + + make_optional creates an optional object + \fI(C++17)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::optional::or_else.3 b/man/std::optional::or_else.3 new file mode 100644 index 000000000..4e50b6bd0 --- /dev/null +++ b/man/std::optional::or_else.3 @@ -0,0 +1,81 @@ +.TH std::optional::or_else 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::or_else \- std::optional::or_else + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr optional or_else( F&& f ) const&; + template< class F > \fB(2)\fP (since C++23) + constexpr optional or_else( F&& f ) &&; + + Returns *this if it contains a value. Otherwise, returns the result of f. + + The program is ill-formed if std::remove_cvref_t> is not + same as std::optional. + + 1) Equivalent to return *this ? *this : std::forward(f)();. This overload + participates in overload resolution only if both std::copy_constructible and + std::invocable are modeled. + 2) Equivalent to return *this ? std::move(*this) : std::forward(f)();. This + overload participates in overload resolution only if both std::move_constructible + and std::invocable are modeled. + +.SH Parameters + + f - a function or Callable object that returns an std::optional + +.SH Return value + + *this or the result of f, as described above. + +.SH Notes + + Feature-test macro Value Std Feature + __cpp_lib_optional 202110L (C++23) Monadic operations in std::optional + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + using maybe_int = std::optional; + + auto valueless = [] + { + std::cout << "Valueless: "; + return maybe_int{0}; + }; + + maybe_int x; + std::cout << x.or_else(valueless).value() << '\\n'; + + x = 42; + std::cout << "Has value: "; + std::cout << x.or_else(valueless).value() << '\\n'; + + x.reset(); + std::cout << x.or_else(valueless).value() << '\\n'; + } + +.SH Output: + + Valueless: 0 + Has value: 42 + Valueless: 0 + +.SH See also + + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP + and_then returns the result of the given function on the contained value if it + (C++23) exists, or an empty optional otherwise + \fI(public member function)\fP + transform returns an optional containing the transformed contained value if it + (C++23) exists, or an empty optional otherwise + \fI(public member function)\fP diff --git a/man/std::optional::reset.3 b/man/std::optional::reset.3 new file mode 100644 index 000000000..7b91f13f9 --- /dev/null +++ b/man/std::optional::reset.3 @@ -0,0 +1,81 @@ +.TH std::optional::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::reset \- std::optional::reset + +.SH Synopsis + void reset() noexcept; \fI(since C++17)\fP + (constexpr since C++20) + + If *this contains a value, destroy that value as if by value().T::~T(). Otherwise, + there are no effects. + + *this does not contain a value after this call. + +.SH Example + + +// Run this code + + #include + #include + + struct A + { + std::string s; + A(std::string str) : s(std::move(str)) { std::cout << " constructed\\n"; } + ~A() { std::cout << " destructed\\n"; } + A(const A& o) : s(o.s) { std::cout << " copy constructed\\n"; } + A(A&& o) : s(std::move(o.s)) { std::cout << " move constructed\\n"; } + + A& operator=(const A& other) + { + s = other.s; + std::cout << " copy assigned\\n"; + return *this; + } + + A& operator=(A&& other) + { + s = std::move(other.s); + std::cout << " move assigned\\n"; + return *this; + } + }; + + int main() + { + std::cout << "Create empty optional:\\n"; + std::optional opt; + + std::cout << "Construct and assign value:\\n"; + opt = A("Lorem ipsum dolor sit amet, consectetur adipiscing elit nec."); + + std::cout << "Reset optional:\\n"; + opt.reset(); + std::cout << "End example\\n"; + } + +.SH Output: + + Create empty optional: + Construct and assign value: + constructed + move constructed + destructed + Reset optional: + destructed + End example + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 reset was not constexpr while non-trivial made constexpr + destruction is allowed in constexpr in C++20 + +.SH See also + + operator= assigns contents + \fI(public member function)\fP diff --git a/man/std::optional::swap.3 b/man/std::optional::swap.3 new file mode 100644 index 000000000..793cbade2 --- /dev/null +++ b/man/std::optional::swap.3 @@ -0,0 +1,108 @@ +.TH std::optional::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::swap \- std::optional::swap + +.SH Synopsis + void swap( optional& other ) noexcept(/* see below */); \fI(since C++17)\fP + (constexpr since C++20) + + Swaps the contents with those of other. + + * If neither *this nor other contain a value, the function has no effect. + * If only one of *this and other contains a value (let's call this object in and + the other un), the contained value of un is direct-initialized from + std::move(*in), followed by destruction of the contained value of in as if by + in->T::~T(). After this call, in does not contain a value; un contains a value. + * If both *this and other contain values, the contained values are exchanged by + calling using std::swap; swap(**this, *other). T lvalues must satisfy Swappable. + + The program is ill-formed if std::is_move_constructible_v is false. + +.SH Parameters + + other - the optional object to exchange the contents with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + noexcept specification: + noexcept(std::is_nothrow_move_constructible_v && + std::is_nothrow_swappable_v) + + In the case of thrown exception, the states of the contained values of *this and + other are determined by the exception safety guarantees of swap of type T or T's + move constructor, whichever is called. For both *this and other, if the object + contained a value, it is left containing a value, and the other way round. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::optional opt1("First example text"); + std::optional opt2("2nd text"); + + enum Swap { Before, After }; + auto print_opts = [&](Swap e) { + std::cout << (e == Before ? "Before swap:\\n" : "After swap:\\n"); + std::cout << "opt1 contains '" << opt1.value_or("") << "'\\n"; + std::cout << "opt2 contains '" << opt2.value_or("") << "'\\n"; + std::cout << (e == Before ? "---SWAP---\\n": "\\n"); + }; + + print_opts(Before); + opt1.swap(opt2); + print_opts(After); + + // Swap with only 1 set + opt1 = "Lorem ipsum dolor sit amet, consectetur tincidunt."; + opt2.reset(); + + print_opts(Before); + opt1.swap(opt2); + print_opts(After); + } + +.SH Output: + + Before swap: + opt1 contains 'First example text' + opt2 contains '2nd text' + ---SWAP--- + After swap: + opt1 contains '2nd text' + opt2 contains 'First example text' + + Before swap: + opt1 contains 'Lorem ipsum dolor sit amet, consectetur tincidunt.' + opt2 contains '' + ---SWAP--- + After swap: + opt1 contains '' + opt2 contains 'Lorem ipsum dolor sit amet, consectetur tincidunt.' + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P2231R1 C++20 swap was not constexpr while the required made constexpr + operations can be constexpr in C++20 + +.SH See also + + std::swap(std::optional) specializes the std::swap algorithm + \fI(C++17)\fP \fI(function template)\fP + +.SH Category: + * conditionally noexcept diff --git a/man/std::optional::transform.3 b/man/std::optional::transform.3 new file mode 100644 index 000000000..904c404d2 --- /dev/null +++ b/man/std::optional::transform.3 @@ -0,0 +1,116 @@ +.TH std::optional::transform 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::transform \- std::optional::transform + +.SH Synopsis + template< class F > \fB(1)\fP (since C++23) + constexpr auto transform( F&& f ) &; + template< class F > \fB(2)\fP (since C++23) + constexpr auto transform( F&& f ) const&; + template< class F > \fB(3)\fP (since C++23) + constexpr auto transform( F&& f ) &&; + template< class F > \fB(4)\fP (since C++23) + constexpr auto transform( F&& f ) const&&; + + If *this contains a value, invokes f with the contained value as an argument, and + returns an std::optional that contains the result of that invocation; otherwise, + returns an empty std::optional. + + The type of contained value in the result (denoted by U below) must be a non-array + object type, and must not be std::in_place_t or std::nullopt_t). Otherwise, the + program is ill-formed. + + 1) Let U be std::remove_cv_t>. If *this contains a + value, returns a std::optional whose contained value is direct-initialized from + std::invoke(std::forward(f), **this) (unlike and_then(), which must return an + std::optional directly). Otherwise, returns an empty std::optional. + The program is ill-formed if the variable definition U + x(std::invoke(std::forward(f), **this)); is ill-formed. + 2) Same as \fB(1)\fP, except that U is std::remove_cv_t>. + 3) Let U be std::remove_cv_t>. If *this contains a value, + returns a std::optional whose contained value is direct-initialized from + std::invoke(std::forward(f), std::move(**this)). Otherwise, returns an empty + std::optional. + The program is ill-formed if the variable definition U + x(std::invoke(std::forward(f), std::move(**this))); is ill-formed. + 4) Same as \fB(3)\fP, except that U is std::remove_cv_t>. + +.SH Parameters + + f - a suitable function or Callable object whose call signature returns a + non-reference type + +.SH Return value + + An std::optional containing the result of f or an empty std::optional, as described + above. + +.SH Notes + + Because transform directly constructs a U object at the right location, rather than + passing it to a constructor, std::is_move_constructible_v can be false. + + As the callable f can't return a reference type, it cannot be a pointer to data + member. + + Some languages call this operation map. + + Feature-test macro Value Std Feature + __cpp_lib_optional 202110L (C++23) Monadic operations in std::optional + +.SH Example + + +// Run this code + + #include + #include + + struct A { /* ... */ }; + struct B { /* ... */ }; + struct C { /* ... */ }; + struct D { /* ... */ }; + + auto A_to_B(A) -> B { /* ... */ std::cout << "A => B \\n"; return {}; } + auto B_to_C(B) -> C { /* ... */ std::cout << "B => C \\n"; return {}; } + auto C_to_D(C) -> D { /* ... */ std::cout << "C => D \\n"; return {}; } + + void try_transform_A_to_D(std::optional o_A) + { + std::cout << (o_A ? "o_A has a value\\n" : "o_A is empty\\n"); + + std::optional o_D = o_A.transform(A_to_B) + .transform(B_to_C) + .transform(C_to_D); + + std::cout << (o_D ? "o_D has a value\\n\\n" : "o_D is empty\\n\\n"); + }; + + int main() + { + try_transform_A_to_D( A{} ); + try_transform_A_to_D( {} ); + } + +.SH Output: + + o_A has a value + A => B + B => C + C => D + o_D has a value + + o_A is empty + o_D is empty + +.SH See also + + value_or returns the contained value if available, another value otherwise + \fI(public member function)\fP + and_then returns the result of the given function on the contained value if it + (C++23) exists, or an empty optional otherwise + \fI(public member function)\fP + or_else returns the optional itself if it contains a value, or the result of the + (C++23) given function otherwise + \fI(public member function)\fP diff --git a/man/std::optional::value.3 b/man/std::optional::value.3 new file mode 100644 index 000000000..31f95b9e1 --- /dev/null +++ b/man/std::optional::value.3 @@ -0,0 +1,85 @@ +.TH std::optional::value 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::value \- std::optional::value + +.SH Synopsis + constexpr T& value() &; \fB(1)\fP \fI(since C++17)\fP + constexpr const T& value() const &; + constexpr T&& value() &&; \fB(2)\fP \fI(since C++17)\fP + constexpr const T&& value() const &&; + + If *this contains a value, returns a reference to the contained value. + + Otherwise, throws a std::bad_optional_access exception. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A reference to the contained value. + +.SH Exceptions + + std::bad_optional_access if *this does not contain a value. + +.SH Notes + + The dereference operator operator*() does not check if this optional contains a + value, which may be more efficient than value(). + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::optional opt = {}; + + try + { + [[maybe_unused]] int n = opt.value(); + } + catch(const std::bad_optional_access& e) + { + std::cout << e.what() << '\\n'; + } + + try + { + opt.value() = 42; + } + catch(const std::bad_optional_access& e) + { + std::cout << e.what() << '\\n'; + } + + opt = 43; + std::cout << *opt << '\\n'; + + opt.value() = 44; + std::cout << opt.value() << '\\n'; + } + +.SH Output: + + bad optional access + bad optional access + 43 + 44 + +.SH See also + + returns the contained value if available, another value + value_or otherwise + \fI(public member function)\fP + operator-> accesses the contained value + operator* \fI(public member function)\fP + bad_optional_access exception indicating checked access to an optional that doesn't + \fI(C++17)\fP contain a value + \fI(class)\fP diff --git a/man/std::optional::value_or.3 b/man/std::optional::value_or.3 new file mode 100644 index 000000000..316f7143b --- /dev/null +++ b/man/std::optional::value_or.3 @@ -0,0 +1,68 @@ +.TH std::optional::value_or 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::value_or \- std::optional::value_or + +.SH Synopsis + template< class U > \fB(1)\fP \fI(since C++17)\fP + constexpr T value_or( U&& default_value ) const&; + template< class U > \fB(2)\fP \fI(since C++17)\fP + constexpr T value_or( U&& default_value ) &&; + + Returns the contained value if *this has a value, otherwise returns default_value. + + 1) Equivalent to bool(*this) ? **this : + static_cast(std::forward(default_value)). + 2) Equivalent to bool(*this) ? std::move(**this) : + static_cast(std::forward(default_value)). + +.SH Parameters + + default_value - the value to use in case *this is empty +.SH Type requirements + - + T must meet the requirements of CopyConstructible in order to use overload \fB(1)\fP. + - + T must meet the requirements of MoveConstructible in order to use overload \fB(2)\fP. + - + U&& must be convertible to T. + +.SH Return value + + The current value if *this has a value, or default_value otherwise. + +.SH Exceptions + + Any exception thrown by the selected constructor of the return value T. + +.SH Example + + +// Run this code + + #include + #include + #include + + std::optional maybe_getenv(const char* n) + { + if (const char* x = std::getenv(n)) + return x; + else + return {}; + } + + int main() + { + std::cout << maybe_getenv("SHELL").value_or("\fI(none)\fP") << '\\n'; + std::cout << maybe_getenv("MYPWD").value_or("\fI(none)\fP") << '\\n'; + } + +.SH Possible output: + + /usr/bin/zsh + \fI(none)\fP + +.SH See also + + value returns the contained value + \fI(public member function)\fP diff --git a/man/std::optional::~optional.3 b/man/std::optional::~optional.3 new file mode 100644 index 000000000..2089831ec --- /dev/null +++ b/man/std::optional::~optional.3 @@ -0,0 +1,28 @@ +.TH std::optional::~optional 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::optional::~optional \- std::optional::~optional + +.SH Synopsis + ~optional(); \fI(since C++17)\fP + (constexpr since C++20) + + If the object contains a value and the type T is not trivially destructible (see + std::is_trivially_destructible), destroys the contained value by calling its + destructor, as if by value().T::~T(). + + Otherwise, does nothing. + +.SH Notes + + If T is trivially-destructible, then this destructor is also trivial, so + std::optional is also trivially-destructible. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + the destructor was not constexpr while + P2231R1 C++20 non-trivial destructors can be constexpr in made constexpr + C++20 diff --git a/man/std::ostream.3 b/man/std::ostream.3 deleted file mode 120000 index 5d3d8327a..000000000 --- a/man/std::ostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream.3 \ No newline at end of file diff --git a/man/std::ostream.3 b/man/std::ostream.3 new file mode 100644 index 000000000..c912c374e --- /dev/null +++ b/man/std::ostream.3 @@ -0,0 +1,279 @@ +.TH std::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream \- std::basic_ostream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits + + > class basic_ostream : virtual public std::basic_ios + + The class template basic_ostream provides support for high level output operations + on character streams. The supported operations include formatted output (e.g. + integer values) and unformatted output (e.g. raw characters and character arrays). + This functionality is implemented in terms of the interface provided by the + basic_streambuf class, accessed through the basic_ios base class. In typical + implementations, basic_ostream has no non-inherited data members. + + std-basic ostream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ostream std::basic_ostream + std::wostream std::basic_ostream + +.SH Global objects + + Six global basic_ostream objects are provided by the standard library: + + Defined in header + cout writes to the standard C output stream stdout + wcout (global object) + cerr writes to the standard C error stream stderr, unbuffered + wcerr (global object) + clog writes to the standard C error stream stderr + wclog (global object) + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + + constructor constructs the object + \fI(public member function)\fP + destructor destructs the object + \fB[virtual]\fP \fI(virtual public member function)\fP + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP +.SH Formatted output + operator<< inserts formatted data + \fI(public member function)\fP +.SH Unformatted output + put inserts a character + \fI(public member function)\fP + write inserts blocks of characters + \fI(public member function)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function)\fP + seekp sets the output position indicator + \fI(public member function)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function)\fP + swap swaps stream objects, except for the associated buffer + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class)\fP + +.SH Non-member functions + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + print(std::ostream) outputs formatted representation of the arguments + (C++23) \fI(function template)\fP + println(std::ostream) outputs formatted representation of the arguments + (C++23) with appended '\\n' + \fI(function template)\fP + vprint_unicode(std::ostream) performs Unicode aware output using type-erased + (C++23) argument representation + \fI(function)\fP + vprint_nonunicode(std::ostream) outputs character data using type-erased argument + (C++23) representation + \fI(function)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::ostream::basic_ostream.3 b/man/std::ostream::basic_ostream.3 deleted file mode 120000 index 718512a78..000000000 --- a/man/std::ostream::basic_ostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::basic_ostream.3 \ No newline at end of file diff --git a/man/std::ostream::basic_ostream.3 b/man/std::ostream::basic_ostream.3 new file mode 100644 index 000000000..2cd517ab4 --- /dev/null +++ b/man/std::ostream::basic_ostream.3 @@ -0,0 +1,63 @@ +.TH std::basic_ostream::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::basic_ostream \- std::basic_ostream::basic_ostream + +.SH Synopsis + explicit basic_ostream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_ostream( const basic_ostream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_ostream( basic_ostream&& rhs ); + + 1) Constructs the basic_ostream object, assigning initial values to the base class + by calling basic_ios::init(sb). + 2) The copy constructor is protected, and is deleted. Output streams are not + copyable. + 3) The move constructor uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable output + stream classes std::basic_ofstream and std::basic_ostringstream, which know how to + correctly move the associated streambuffer. + +.SH Parameters + + sb - streambuffer to use as output sequence + rhs - basic_ostream to initialize from + +.SH Notes + + Because basic_ios::init(sb) sets badbit when sb is a null pointer, and because + basic_ostream::sentry does nothing if the stream is already in a failed state, + writing to a stream constructed from a null pointer sb is a no-op. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // ERROR: copy ctor is deleted + // std::ostream myout(std::cout); + + // OK: shares buffer with cout + std::ostream myout(std::cout.rdbuf()); + + // ERROR: move constructor is protected + // std::ostream s2(std::move(std::ostringstream() << 7.1)); + + // OK: move ctor called through the derived class + std::ostringstream s2(std::ostringstream() << 7.1); + myout << s2.str() << '\\n'; + + std::ostream dev_null{nullptr}; // see Notes above + dev_null << "no-op"; + } + +.SH Output: + + 7.1 diff --git a/man/std::ostream::flush.3 b/man/std::ostream::flush.3 deleted file mode 120000 index 2493fd0c6..000000000 --- a/man/std::ostream::flush.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::flush.3 \ No newline at end of file diff --git a/man/std::ostream::flush.3 b/man/std::ostream::flush.3 new file mode 100644 index 000000000..642eeceeb --- /dev/null +++ b/man/std::ostream::flush.3 @@ -0,0 +1,91 @@ +.TH std::basic_ostream::flush 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::flush \- std::basic_ostream::flush + +.SH Synopsis + basic_ostream& flush(); + + Writes uncommitted changes to the underlying output sequence. Behaves as an + UnformattedOutputFunction. + + If rdbuf() is a null pointer, the sentry object is not constructed. + + Otherwise, after constructing and checking the sentry object, calls + rdbuf()->pubsync(). If the call returns -1, calls setstate(badbit). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + *this + +.SH Exceptions + + May throw std::ios_base::failure if (exceptions() & badbit) != 0. + +.SH Example + + +// Run this code + + #include + #include + #include + + using namespace std::chrono_literals; + + void f() + { + std::cout << "Output from thread... "; + for (int i{1}; i != 10; ++i) + { + std::this_thread::sleep_for(250ms); + std::cout << i << ' '; + + // output three numbers at once; + // the effect is observable only in real-time + if (0 == (i % 3)) + std::cout.flush(); + } + std::cout << std::endl; // flushes as well + } + + int main() + { + std::thread tr{f}; + std::this_thread::sleep_for(150ms); + std::clog << "Output from main\\n"; + tr.join(); + } + +.SH Output: + + Output from main + Output from thread... 1 2 3 4 5 6 7 8 9 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + flush() did not behave as an + LWG 581 C++98 UnformattedOutputFunction behaves as an + because of the resolution of LWG issue UnformattedOutputFunction + 60 + +.SH See also + + pubsync invokes sync() + \fI(public member function of std::basic_streambuf)\fP + sync synchronizes the buffers with the associated character sequence + \fB[virtual]\fP \fI(virtual protected member function of std::basic_streambuf)\fP + + flush flushes the output stream + \fI(function template)\fP + endl outputs '\\n' and flushes the output stream + \fI(function template)\fP + sync synchronizes with the underlying storage device + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::ostream::operator<<.3 b/man/std::ostream::operator<<.3 deleted file mode 120000 index 13d0f69bf..000000000 --- a/man/std::ostream::operator<<.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::operator<<.3 \ No newline at end of file diff --git a/man/std::ostream::operator<<.3 b/man/std::ostream::operator<<.3 new file mode 100644 index 000000000..7a68deebf --- /dev/null +++ b/man/std::ostream::operator<<.3 @@ -0,0 +1,208 @@ +.TH std::basic_ostream::operator<< 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::operator<< \- std::basic_ostream::operator<< + +.SH Synopsis + basic_ostream& operator<<( bool value ); \fB(1)\fP + basic_ostream& operator<<( long value ); \fB(2)\fP + basic_ostream& operator<<( unsigned long value ); \fB(3)\fP + basic_ostream& operator<<( long long value ); \fB(4)\fP \fI(since C++11)\fP + basic_ostream& operator<<( unsigned long long value ); \fB(5)\fP \fI(since C++11)\fP + basic_ostream& operator<<( double value ); \fB(6)\fP + basic_ostream& operator<<( long double value ); \fB(7)\fP + basic_ostream& operator<<( const void* value ); \fB(8)\fP + basic_ostream& operator<<( const volatile void* value ); \fB(9)\fP (since C++23) + basic_ostream& operator<<( std::nullptr_t ); \fB(10)\fP \fI(since C++17)\fP + basic_ostream& operator<<( short value ); \fB(11)\fP + basic_ostream& operator<<( int value ); \fB(12)\fP + basic_ostream& operator<<( unsigned short value ); \fB(13)\fP + basic_ostream& operator<<( unsigned int value ); \fB(14)\fP + basic_ostream& operator<<( float value ); \fB(15)\fP + basic_ostream& operator<<( /* extended-floating-point-type */ \fB(16)\fP (since C++23) + value ); + basic_ostream& operator<<( std::basic_streambuf* \fB(17)\fP + sb ); + basic_ostream& operator<<( \fB(18)\fP + std::ios_base& (*func)(std::ios_base&) ); + basic_ostream& operator<<( + std::basic_ios& (*func)(std::basic_ios&) ); + basic_ostream& operator<<( + + std::basic_ostream& (*func) \fB(20)\fP + + (std::basic_ostream&) ); + + Inserts data into the stream. + + 1-8) Inserts value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a value by calling std::num_put::put(). If the end of + file condition was encountered during output (put().failed() == true), sets badbit. + 9) Equivalent to return operator<<(const_cast(p));. + 10) Equivalent to return *this << s;, where s is an implementation-defined + null-terminated character type string. + 11) Inserts a value from short value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is + * static_cast(static_cast(value)), if flags() & + std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or + * static_cast(value) otheriwse. + 12) Inserts a value from int value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is + * static_cast(static_cast(value)), if flags() & + std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or + * static_cast(value) otheriwse. + 13,14) Inserts a value from unsigned short or unsigned int value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts static_cast(value) as in \fB(3)\fP. + 15) Inserts a value from float value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, inserts static_cast(value) as in \fB(6)\fP. + 16) Inserts a value from value. The library provides overloads for all + cv-unqualified extended floating-point types as the type of the parameter value. + This function behaves as a FormattedOutputFunction. After constructing and checking + the sentry object, checks the floating-point conversion rank of /* + extended-floating-point-type */: + * If the rank is less than or equal to that of double, inserts + static_cast(value) as in \fB(6)\fP. + * Otherwise, if the rank is less than or equal to that of long double, inserts + static_cast(value) as in \fB(7)\fP. + * Otherwise, an invocation of this overload is conditionally supported with + implementation-defined semantics. + 17) This function behaves as an UnformattedOutputFunction. After constructing and + checking the sentry object, checks if sb is a null pointer. If it is, executes + setstate(badbit) and exits. Otherwise, extracts characters from the input sequence + controlled by sb and inserts them into *this until one of the following conditions + are met: + + * end-of-file occurs on the input sequence; + * inserting in the output sequence fails (in which case the character to be + inserted is not extracted); + * an exception occurs (in which case the exception is caught). + If no characters were inserted, executes setstate(failbit). If an exception was + thrown while extracting, sets failbit and, if failbit is set in exceptions(), + rethrows the exception. + 18-20) Calls func(*this). These overloads are used to implement output I/O + manipulators such as std::endl. + +.SH Parameters + + value - integer, floating-point, boolean, or pointer value to insert + func - function to call + sb - pointer to the stream buffer to read the data from + +.SH Return value + + 1-19) *this + 20) func(*this) + +.SH Notes + + There are no overloads for pointers to non-static members + , pointers to volatiles, + (until C++23) or function pointers (other than the ones with signatures accepted by + the (18-20) overloads). + + * Attempting to output such objects invokes implicit conversion to bool, and, for + any non-null pointer value, the value 1 is printed (unless boolalpha was set, in + which case true is printed). + + Character and character string arguments (e.g., of type char or const char*) are + handled by the non-member overloads of operator<<. + + * Attempting to output a character using the member function call syntax (e.g., + std::cout.operator<<('c');) will call one of the overloads in (2-5) or (11-14) + and output the numerical value. + * Attempting to output a character string using the member function call syntax + will call overload \fB(8)\fP and print the pointer value instead. + +.SH Example + + +// Run this code + + #include + #include + #include + + int fun() { return 42; } + + int main() + { + std::istringstream input(" \\"Some text.\\" "); + double f = 3.14; + bool b = true; + + std::cout + << fun() // int overload (12) + << ' ' // non-member overload + << std::boolalpha // function overload (18) + << b // bool overload (1) + << " " // non-member overload + << std::fixed // function overload (18) again + << f // double overload (6) + << input.rdbuf() // streambuf overload + << fun // bool overload (1): there's no overload for int(*)() + << std::endl; // function overload (18) again + + int x = 0; + int* p1 = &x; + volatile int* p2 = &x; + std::cout + << "p1: " << p1 << '\\n' // `const void*` overload, prints address + << "p2: " << p2 << '\\n'; // before C++23 (P1147): bool overload :), because + // operator<<(const void*) is not a match, as it discards the `volatile` + // qualifier. To fix this, C++23 adds `const volatile void*` overload (9), + // that prints the address as expected. + } + +.SH Possible output: + + 42 true 3.140000 "Some text." true + p1: 0x7ffcea766600 + p2: 0x7ffcea766600 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + overloads (1-8,11-15) delegated the + insertion to they are converted + LWG 117 C++98 num_put::put, but it does not have before being passed + overloads for short, to num_put::put + unsigned short, int, unsigned int, and + float + overload \fB(17)\fP behaved as a + LWG 567 C++98 FormattedOutputFunction it behaves as an + because of the resolution of LWG issue UnformattedOutputFunction + 60 + +.SH See also + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + operator<< performs stream input and output on strings + operator>> \fI(function template)\fP + operator<< performs stream output on string views + \fI(C++17)\fP \fI(function template)\fP + operator<< performs stream input and output of bitsets + operator>> \fI(function template)\fP + operator<< serializes and deserializes a complex number + operator>> \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number engine + \fI(C++11)\fP \fI(function template)\fP + operator<< performs stream input and output on pseudo-random + operator>> number distribution + \fI(C++11)\fP \fI(function template)\fP + put inserts a character + \fI(public member function)\fP + write inserts blocks of characters + \fI(public member function)\fP + to_chars converts an integer or floating-point value to a + \fI(C++17)\fP character sequence + \fI(function)\fP diff --git a/man/std::ostream::operator=.3 b/man/std::ostream::operator=.3 deleted file mode 120000 index 2d79f3d27..000000000 --- a/man/std::ostream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::operator=.3 \ No newline at end of file diff --git a/man/std::ostream::operator=.3 b/man/std::ostream::operator=.3 new file mode 100644 index 000000000..051bc3209 --- /dev/null +++ b/man/std::ostream::operator=.3 @@ -0,0 +1,54 @@ +.TH std::basic_ostream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::operator= \- std::basic_ostream::operator= + +.SH Synopsis + protected: \fB(1)\fP + basic_ostream& operator=( const basic_ostream& rhs ) = delete; + protected: \fB(2)\fP \fI(since C++11)\fP + basic_ostream& operator=( basic_ostream&& rhs ); + + 1) The copy assignment operator is protected, and is deleted. Output streams are not + CopyAssignable. + 2) The move assignment operator exchanges all data members of the base class, except + for rdbuf(), with rhs, as if by calling swap(*rhs). This move assignment operator is + protected: it is only called by the move assignment operators of the derived movable + output stream classes std::basic_ofstream and std::basic_ostringstream, which know + how to correctly move-assign the associated streambuffers. + +.SH Parameters + + rhs - the basic_ostream object from which to assign to *this + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ostringstream s; + // std::cout = s; // ERROR: copy assignment operator is deleted + // std::cout = std::move(s); // ERROR: move assignment operator is protected + s = std::move(std::ostringstream() << 42); // OK, moved through derived + std::cout << s.str() << '\\n'; + } + +.SH Output: + + 42 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + 1. the parameter type of overload \fB(1)\fP was + LWG 2067 C++11 basic_ostream& 1. added const + 2. the parameter type of overload \fB(2)\fP was const 2. removed const + basic_ostream&& diff --git a/man/std::ostream::ostream.3 b/man/std::ostream::ostream.3 deleted file mode 120000 index 718512a78..000000000 --- a/man/std::ostream::ostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::basic_ostream.3 \ No newline at end of file diff --git a/man/std::ostream::ostream.3 b/man/std::ostream::ostream.3 new file mode 100644 index 000000000..2cd517ab4 --- /dev/null +++ b/man/std::ostream::ostream.3 @@ -0,0 +1,63 @@ +.TH std::basic_ostream::basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::basic_ostream \- std::basic_ostream::basic_ostream + +.SH Synopsis + explicit basic_ostream( std::basic_streambuf* sb ); \fB(1)\fP + protected: \fB(2)\fP \fI(since C++11)\fP + basic_ostream( const basic_ostream& rhs ) = delete; + protected: \fB(3)\fP \fI(since C++11)\fP + basic_ostream( basic_ostream&& rhs ); + + 1) Constructs the basic_ostream object, assigning initial values to the base class + by calling basic_ios::init(sb). + 2) The copy constructor is protected, and is deleted. Output streams are not + copyable. + 3) The move constructor uses basic_ios::move(rhs) to move all + basic_ios members, except for the rdbuf(), from rhs into *this. This move + constructor is protected: it is called by the move constructors of movable output + stream classes std::basic_ofstream and std::basic_ostringstream, which know how to + correctly move the associated streambuffer. + +.SH Parameters + + sb - streambuffer to use as output sequence + rhs - basic_ostream to initialize from + +.SH Notes + + Because basic_ios::init(sb) sets badbit when sb is a null pointer, and because + basic_ostream::sentry does nothing if the stream is already in a failed state, + writing to a stream constructed from a null pointer sb is a no-op. + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + // ERROR: copy ctor is deleted + // std::ostream myout(std::cout); + + // OK: shares buffer with cout + std::ostream myout(std::cout.rdbuf()); + + // ERROR: move constructor is protected + // std::ostream s2(std::move(std::ostringstream() << 7.1)); + + // OK: move ctor called through the derived class + std::ostringstream s2(std::ostringstream() << 7.1); + myout << s2.str() << '\\n'; + + std::ostream dev_null{nullptr}; // see Notes above + dev_null << "no-op"; + } + +.SH Output: + + 7.1 diff --git a/man/std::ostream::put.3 b/man/std::ostream::put.3 deleted file mode 120000 index 3f0b42dfc..000000000 --- a/man/std::ostream::put.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::put.3 \ No newline at end of file diff --git a/man/std::ostream::put.3 b/man/std::ostream::put.3 new file mode 100644 index 000000000..5a34117a4 --- /dev/null +++ b/man/std::ostream::put.3 @@ -0,0 +1,66 @@ +.TH std::basic_ostream::put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::put \- std::basic_ostream::put + +.SH Synopsis + basic_ostream& put( char_type ch ); + + Behaves as an UnformattedOutputFunction. After constructing and checking the sentry + object, writes the character ch to the output stream. + + If the output fails for any reason, sets badbit. + +.SH Parameters + + ch - character to write + +.SH Return value + + *this + +.SH Notes + + This function is not overloaded for the types signed char or unsigned char, unlike + the formatted operator<<. + + Unlike formatted output functions, this function does not set the failbit if the + output fails. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::cout.put('a'); // normal usage + std::cout.put('\\n'); + + std::ofstream s("/does/not/exist/"); + s.clear(); // pretend the stream is good + std::cout << "Unformatted output: "; + s.put('c'); // this will set badbit, but not failbit + std::cout << " fail=" << bool(s.rdstate() & s.failbit); + std::cout << " bad=" << s.bad() << '\\n'; + s.clear(); + std::cout << "Formatted output: "; + s << 'c'; // this will set badbit and failbit + std::cout << " fail=" << bool(s.rdstate() & s.failbit); + std::cout << " bad=" << s.bad() << '\\n'; + } + +.SH Output: + + a + Unformatted output: fail=0 bad=1 + Formatted output: fail=1 bad=1 + +.SH See also + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + write inserts blocks of characters + \fI(public member function)\fP diff --git a/man/std::ostream::seekp.3 b/man/std::ostream::seekp.3 deleted file mode 120000 index 89f3be9de..000000000 --- a/man/std::ostream::seekp.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::seekp.3 \ No newline at end of file diff --git a/man/std::ostream::seekp.3 b/man/std::ostream::seekp.3 new file mode 100644 index 000000000..19e584dc9 --- /dev/null +++ b/man/std::ostream::seekp.3 @@ -0,0 +1,88 @@ +.TH std::basic_ostream::seekp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::seekp \- std::basic_ostream::seekp + +.SH Synopsis + basic_ostream& seekp( pos_type pos ); \fB(1)\fP + basic_ostream& seekp( off_type off, std::ios_base::seekdir dir ); \fB(2)\fP + + Sets the output position indicator of the current associated streambuf object. + + Behaves as UnformattedOutputFunction (except without actually \fI(since C++11)\fP + performing output). After constructing and checking the sentry object, + + 1) if fail() != true, sets the output position indicator to absolute (relative to + the beginning of the file) value pos by calling rdbuf()->pubseekpos(pos, + std::ios_base::out). In case of failure, calls setstate(std::ios_base::failbit). + 2) if fail() != true, sets the output position indicator to offset off relative to + dir by calling rdbuf()->pubseekoff(off, dir, std::ios_base::out). In case of + failure, calls setstate(std::ios_base::failbit). + +.SH Parameters + + pos - absolute position to set the output position indicator to + off - relative position (positive or negative) to set the output position indicator + to + defines base position to apply the relative offset to. It can be one of the + following constants: + + dir - Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + +.SH Return value + + *this + +.SH Exceptions + + 1,2) May throw std::ios_base::failure in case of failure, if exceptions() & failbit + != 0. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + std::ostringstream os("hello, world"); + os.seekp(7); + os << 'W'; + os.seekp(0, std::ios_base::end); + os << '!'; + os.seekp(0); + os << 'H'; + std::cout << os.str() << '\\n'; + } + +.SH Output: + + Hello, World! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 129 C++98 there was no way to indicate a failure sets failbit on failure + LWG 136 C++98 seekp could set the input stream only sets the output + stream + LWG 537 C++98 1. the type of pos was pos_type& 1. corrected to pos_type + 2. the type of off was off_type& 2. corrected to off_type + LWG 2341 C++98 the resolution of LWG issue 129 for restored + overload \fB(2)\fP was removed + +.SH See also + + tellp returns the output position indicator + \fI(public member function)\fP + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::ostream::sentry.3 b/man/std::ostream::sentry.3 deleted file mode 120000 index b6533ef2c..000000000 --- a/man/std::ostream::sentry.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::sentry.3 \ No newline at end of file diff --git a/man/std::ostream::sentry.3 b/man/std::ostream::sentry.3 new file mode 100644 index 000000000..6001be802 --- /dev/null +++ b/man/std::ostream::sentry.3 @@ -0,0 +1,124 @@ +.TH std::basic_ostream::sentry 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::sentry \- std::basic_ostream::sentry + +.SH Synopsis + class sentry; + + An object of class basic_ostream::sentry is constructed in local scope at the + beginning of each member function of std::basic_ostream that performs output (both + formatted and unformatted). Its constructor prepares the output stream: checks if + the stream is already in a failed state, flushes the tie()'d output streams, and + performs other implementation-defined tasks if necessary. Implementation-defined + cleanup, as well as flushing of the output stream if necessary, is performed in the + destructor, so that it is guaranteed to happen if exceptions are thrown during + output. + +.SH Member functions + + constructor constructs the sentry object. All the preparation tasks are done here + \fI(public member function)\fP + finalizes the stream object after formatted output or after exception, + destructor if necessary + \fI(public member function)\fP + operator= the assignment operator is deleted + \fI(public member function)\fP + operator bool checks if the preparation of the stream object was successful + \fI(public member function)\fP + +std::basic_ostream::sentry::sentry + + explicit sentry( std::basic_ostream& os ); + + Prepares the stream for formatted output. + + If os.good() is false, returns. Otherwise, if os.tie() is not a null pointer, calls + os.tie()->flush() to synchronize the output sequence with external streams. During + preparation, the constructor may call setstate(failbit) (which may throw + std::ios_base::failure). + + If after preparation is completed, os.good() == true, then any subsequent calls to + operator bool will return true. + +.SH Parameters + + os - output stream to prepare + +.SH Exceptions + + std::ios_base::failure if the end of file condition occurs. + +std::basic_ostream::sentry::~sentry + + ~sentry(); + + If (os.flags() & std::ios_base::unitbuf) && !std::uncaught_exception() && os.good()) + is true, calls os.rdbuf()->pubsync(). If that function returns -1, sets badbit in + os.rdstate() without propagating an exception. + +std::basic_ostream::sentry::operator bool + + explicit operator bool() const; + + Checks whether the preparation of the output stream was successful. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + true if the preparation of the output stream was successful, false otherwise. + +.SH Example + + +// Run this code + + #include + #include + + struct Foo + { + char n[6]; + }; + + std::ostream& operator<<(std::ostream& os, Foo& f) + { + std::ostream::sentry s(os); + if (s) + os.write(f.n, 5); + return os; + } + + int main() + { + Foo f = {"abcde"}; + std::cout << f << '\\n'; + } + +.SH Output: + + abcde + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 397 C++98 the destructor might call os.flush(), which the exception is not + may throw exceptions propagated + LWG 442 C++98 operator bool was not declared const (it is added const + const in the synopsis) + if os sets unitbuf, the destructor would + call os.flush(), which calls + LWG 835 C++98 is an UnformattedOutputFunction and creates os.rdbuf()->pubsync() + another sentry object in this case instead + (whose destructor then creates another + sentry object and so on) + +.SH See also + + operator<< inserts formatted data + \fI(public member function)\fP diff --git a/man/std::ostream::swap.3 b/man/std::ostream::swap.3 deleted file mode 120000 index 67e58a029..000000000 --- a/man/std::ostream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::swap.3 \ No newline at end of file diff --git a/man/std::ostream::swap.3 b/man/std::ostream::swap.3 new file mode 100644 index 000000000..2b0d09268 --- /dev/null +++ b/man/std::ostream::swap.3 @@ -0,0 +1,43 @@ +.TH std::basic_ostream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::swap \- std::basic_ostream::swap + +.SH Synopsis + protected: \fI(since C++11)\fP + void swap( basic_ostream& rhs ); + + Calls basic_ios::swap(rhs) to swap all data members of the base class, except for + rdbuf(), between *this and rhs. This swap function is protected: it is called by the + swap functions of the swappable output stream classes std::basic_ofstream and + std::basic_ostringstream, which know how to correctly swap the associated + streambuffers. + +.SH Parameters + + rhs - a basic_ostream of the same type to swap with + +.SH Example + + +// Run this code + + #include + #include + #include + + int main() + { + std::ostringstream s1("hello"); + std::ostringstream s2("bye"); + + s1.swap(s2); // OK, ostringstream has a public swap() + std::swap(s1, s2); // OK, calls s1.swap(s2) + + // std::cout.swap(s2); // ERROR: swap is a protected member + + std::cout << s1.str() << '\\n'; + } + +.SH Output: + + hello diff --git a/man/std::ostream::tellp.3 b/man/std::ostream::tellp.3 deleted file mode 120000 index 1781469fd..000000000 --- a/man/std::ostream::tellp.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::tellp.3 \ No newline at end of file diff --git a/man/std::ostream::tellp.3 b/man/std::ostream::tellp.3 new file mode 100644 index 000000000..73acfb3df --- /dev/null +++ b/man/std::ostream::tellp.3 @@ -0,0 +1,58 @@ +.TH std::basic_ostream::tellp 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::tellp \- std::basic_ostream::tellp + +.SH Synopsis + pos_type tellp(); + + Returns the output position indicator of the current associated streambuf object. + + Behaves as UnformattedOutputFunction (except without actually \fI(since C++11)\fP + performing output). After constructing and checking the sentry object, + + If fail()==true, returns pos_type(-1). Otherwise, returns rdbuf()->pubseekoff(0, + std::ios_base::cur, std::ios_base::out). + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + current output position indicator on success, pos_type(-1) if a failure occurs. + +.SH Example + + +// Run this code + + #include + #include + int main() + { + std::ostringstream s; + std::cout << s.tellp() << '\\n'; + s << 'h'; + std::cout << s.tellp() << '\\n'; + s << "ello, world "; + std::cout << s.tellp() << '\\n'; + s << 3.14 << '\\n'; + std::cout << s.tellp() << '\\n' << s.str(); + } + +.SH Output: + + 0 + 1 + 13 + 18 + hello, world 3.14 + +.SH See also + + seekp sets the output position indicator + \fI(public member function)\fP + tellg returns the input position indicator + \fI(public member function of std::basic_istream)\fP + seekg sets the input position indicator + \fI(public member function of std::basic_istream)\fP diff --git a/man/std::ostream::write.3 b/man/std::ostream::write.3 deleted file mode 120000 index 3c2cea83f..000000000 --- a/man/std::ostream::write.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::write.3 \ No newline at end of file diff --git a/man/std::ostream::write.3 b/man/std::ostream::write.3 new file mode 100644 index 000000000..d4244b94e --- /dev/null +++ b/man/std::ostream::write.3 @@ -0,0 +1,75 @@ +.TH std::basic_ostream::write 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::write \- std::basic_ostream::write + +.SH Synopsis + basic_ostream& write( const char_type* s, std::streamsize count ); + + Behaves as an UnformattedOutputFunction. After constructing and checking the sentry + object, outputs the characters from successive locations in the character array + whose first element is pointed to by s. Characters are inserted into the output + sequence until one of the following occurs: + + * exactly count characters are inserted + * inserting into the output sequence fails (in which case setstate(badbit) is + called). + +.SH Parameters + + s - pointer to the character string to write + count - number of characters to write + +.SH Return value + + *this + +.SH Exceptions + + + failure if an error occurred (the error state flag is not goodbit) and exceptions() + is set to throw for that state. + + If an internal operation throws an exception, it is caught and badbit is set. If + exceptions() is set for badbit, the exception is rethrown. + +.SH Notes + + This function is not overloaded for the types signed char or unsigned char, unlike + the formatted operator<<. + + Also, unlike the formatted output functions, this function does not set the failbit + on failure. + + When using a non-converting locale (the default locale is non-converting), the + overrider of this function in std::basic_ofstream may be optimized for zero-copy + bulk I/O (by means of overriding std::streambuf::xsputn). + +.SH Example + + This function may be used to output object representations, i.e. binary output + + +// Run this code + + #include + + int main() + { + int n = 0x41424344; + std::cout.write(reinterpret_cast(&n), sizeof n) << '\\n'; + + char c[] = "This is sample text."; + std::cout.write(c, 4).write("!\\n", 2); + } + +.SH Possible output: + + DCBA + This! + +.SH See also + + operator<<(std::basic_ostream) inserts character data or insert into rvalue stream + \fI(function template)\fP + put inserts a character + \fI(public member function)\fP diff --git a/man/std::ostream::~basic_ostream.3 b/man/std::ostream::~basic_ostream.3 deleted file mode 120000 index 5db51e526..000000000 --- a/man/std::ostream::~basic_ostream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostream::~basic_ostream.3 \ No newline at end of file diff --git a/man/std::ostream::~basic_ostream.3 b/man/std::ostream::~basic_ostream.3 new file mode 100644 index 000000000..56d90cf52 --- /dev/null +++ b/man/std::ostream::~basic_ostream.3 @@ -0,0 +1,38 @@ +.TH std::basic_ostream::~basic_ostream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostream::~basic_ostream \- std::basic_ostream::~basic_ostream + +.SH Synopsis + virtual ~basic_ostream(); + + Destroys the basic_ostream object. This destructor does not perform any operation on + the underlying streambuffer (rdbuf()): the destructors of the derived output streams + such as std::basic_ofstream and std::basic_ostringstream are responsible for calling + the destructors of the stream buffers. + +.SH Example + + +// Run this code + + #include + #include + + void add_words(std::streambuf* p) + { + std::ostream buf(p); // buf shares the buffer with s + buf << " is the answer"; + } // calls the destructor of buf. p remains unaffected + + int main() + { + std::ostringstream s; + s << 42; + add_words(s.rdbuf()); + s << "."; + std::cout << s.str() << '\\n'; + } + +.SH Output: + + 42 is the answer. diff --git a/man/std::ostream_iterator.3 b/man/std::ostream_iterator.3 index 2f8e9befa..f4dca56f1 100644 --- a/man/std::ostream_iterator.3 +++ b/man/std::ostream_iterator.3 @@ -1,15 +1,25 @@ -.TH std::ostream_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostream_iterator \- std::ostream_iterator + .SH Synopsis Defined in header template< class T, class CharT = char, - class Traits = std::char_traits> - class ostream_iterator : public std::iterator > \fI(until C++17)\fP + class ostream_iterator + + : public std::iterator + template< class T, - void, void, void, void> + class CharT = char, \fI(since C++17)\fP + class Traits = std::char_traits > - std::ostream_iterator is a single-pass output iterator that writes successive + class ostream_iterator; + + std::ostream_iterator is a single-pass LegacyOutputIterator that writes successive objects of type T into the std::basic_ostream object for which it was constructed, using operator<<. Optional delimiter string is written to the output stream after every write operation. The write operation is performed when the iterator (whether @@ -25,60 +35,66 @@ .SH Member types - Member type Definition - char_type CharT - traits_type Traits - ostream_type std::basic_ostream + Member type Definition + iterator_category std::output_iterator_tag + value_type void + difference_type void \fI(until C++20)\fP + std::ptrdiff_t \fI(since C++20)\fP + pointer void + reference void + char_type CharT + traits_type Traits + ostream_type std::basic_ostream + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. .SH Member functions constructor constructs a new ostream_iterator - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs an ostream_iterator - \fI(public member function)\fP - operator= writes a object to the associated output sequence - \fI(public member function)\fP + \fI(public member function)\fP + operator= writes an object to the associated output sequence + \fI(public member function)\fP operator* no-op - \fI(public member function)\fP + \fI(public member function)\fP operator++ no-op - operator++(int) \fI(public member function)\fP - -Inherited from std::iterator - -.SH Member types - - Member type Definition - value_type void - difference_type void - pointer void - reference void - iterator_category std::output_iterator_tag + operator++(int) \fI(public member function)\fP .SH Example - + // Run this code #include - #include #include - #include - + #include + #include + int main() { - std::istringstream str("0.1 0.2 0.3 0.4"); + std::istringstream str("0.11 0.22 0.33 0.44"); + std::partial_sum(std::istream_iterator(str), - std::istream_iterator(), - std::ostream_iterator(std::cout, " ")); + std::istream_iterator(), + std::ostream_iterator(std::cout, ", ")); + std::cout << '\\n'; } .SH Output: - 0.1 0.3 0.6 1 + 0.11, 0.33, 0.66, 1.1, .SH See also - ostreambuf_iterator output iterator that writes to std::basic_streambuf - \fI(class template)\fP - istream_iterator input iterator that reads from std::basic_istream - \fI(class template)\fP + output iterator that writes to + ostreambuf_iterator std::basic_streambuf + \fI(class template)\fP + istream_iterator input iterator that reads from std::basic_istream + \fI(class template)\fP + an output iterator that writes successive elements + std::experimental::ostream_joiner into an output stream, separating adjacent + (library fundamentals TS v2) elements with a delimiter + \fI(class template)\fP diff --git a/man/std::ostream_iterator::operator*.3 b/man/std::ostream_iterator::operator*.3 index 4a557d03c..43238ff85 100644 --- a/man/std::ostream_iterator::operator*.3 +++ b/man/std::ostream_iterator::operator*.3 @@ -1,12 +1,15 @@ -.TH std::ostream_iterator::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostream_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostream_iterator::operator* \- std::ostream_iterator::operator* + .SH Synopsis ostream_iterator& operator*(); Does nothing, this member function is provided to satisfy the requirements of - OutputIterator. + LegacyOutputIterator. It returns the iterator itself, which makes it possible to use code such as *iter = - value to output (insert) the value into the underlying container. + value to output (insert) the value into the underlying stream. .SH Parameters diff --git a/man/std::ostream_iterator::operator++.3 b/man/std::ostream_iterator::operator++.3 index 058dbcf1f..19fe6bb0f 100644 --- a/man/std::ostream_iterator::operator++.3 +++ b/man/std::ostream_iterator::operator++.3 @@ -1,11 +1,14 @@ -.TH std::ostream_iterator::operator++ 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostream_iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostream_iterator::operator++ \- std::ostream_iterator::operator++ + .SH Synopsis ostream_iterator& operator++(); ostream_iterator& operator++( int ); Does nothing. These operator overloads are provided to satisfy the requirements of - OutputIterator. They make it possible for the expressions *iter++=value and - *++iter=value to be used to output (insert) a value into the underlying container. + LegacyOutputIterator. They make it possible for the expressions *iter++=value and + *++iter=value to be used to output (insert) a value into the underlying stream. .SH Parameters diff --git a/man/std::ostream_iterator::operator=.3 b/man/std::ostream_iterator::operator=.3 index 0a23bfde5..bbe58f750 100644 --- a/man/std::ostream_iterator::operator=.3 +++ b/man/std::ostream_iterator::operator=.3 @@ -1,16 +1,21 @@ -.TH std::ostream_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostream_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostream_iterator::operator= \- std::ostream_iterator::operator= + .SH Synopsis - ostream_iterator& operator=( const T& value ) + ostream_iterator& operator=( const ostream_iterator& ); \fB(1)\fP + ostream_iterator& operator=( const T& value ); \fB(2)\fP - Inserts value into the associated stream, then inserts the delimiter, if one was + 1) Copy assignment operator. Assigns the contents of other + 2) Inserts value into the associated stream, then inserts the delimiter, if one was specified at construction time. - If out_stream is the private member pointer to the associated std::basic_ostream and - delim is the pointer to the first character in the delimiter, the effect is + If out_stream is a pointer to the associated std::basic_ostream and delim is the + delimiter specified at the construction of this object, then the effect is equivalent to *out_stream << value; - if(delim != 0) + if (delim != 0) *out_stream << delim; return *this; @@ -24,16 +29,19 @@ .SH Notes - T can be any class with a user-defined operator<< + T can be any class with a user-defined operator<<. + + Prior to C++20, the existence of the copy assignment operator relied on the + deprecated implicit generation. .SH Example - + // Run this code #include #include - + int main() { std::ostream_iterator i1(std::cout, ", "); @@ -42,6 +50,7 @@ i1 = 3; // neither * nor ++ are necessary std::ostream_iterator i2(std::cout); i2 = 3.14; + std::cout << '\\n'; } .SH Output: diff --git a/man/std::ostream_iterator::ostream_iterator.3 b/man/std::ostream_iterator::ostream_iterator.3 index 19bd64bcd..160ea460e 100644 --- a/man/std::ostream_iterator::ostream_iterator.3 +++ b/man/std::ostream_iterator::ostream_iterator.3 @@ -1,13 +1,16 @@ -.TH std::ostream_iterator::ostream_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostream_iterator::ostream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostream_iterator::ostream_iterator \- std::ostream_iterator::ostream_iterator + .SH Synopsis - ostream_iterator(ostream_type& stream, const CharT* delim) \fB(1)\fP - ostream_iterator(ostream_type& stream) \fB(2)\fP + ostream_iterator( ostream_type& stream, const CharT* delim ); \fB(1)\fP + ostream_iterator( ostream_type& stream ); \fB(2)\fP - 1) Constructs the iterator with the private ostream_type* member initialized with - &stream and the private delimiter pointer initialized with delim. + Constructs the iterator with stream as the associated stream, by storing the address + of stream. - 2) Constructs the iterator with the private ostream_type* member initialized with - &stream and the private delimiter pointer initialized with null pointer value. + 1) Uses delim as the delimiter. + 2) Uses a null pointer as the delimiter. .SH Parameters @@ -17,20 +20,48 @@ .SH Example - + // Run this code + #include #include #include - #include + #include + int main() { - std::ostream_iterator i1(std::cout, ", "); + std::ostream_iterator oo{std::cout}; + std::ostream_iterator i1{std::cout, ", "}; std::fill_n(i1, 5, -1); - std::ostream_iterator i2(std::cout); + *oo++ = '\\n'; + + std::ostream_iterator i2{std::cout, "; "}; *i2++ = 3.14; + *i2++ = 2.71; + *oo++ = '\\n'; + + std::common_iterator>, + std::default_sentinel_t> + first{std::counted_iterator{std::ostream_iterator{std::cout," ~ "}, 5}}, + last{std::default_sentinel}; + std::iota(first, last, 2.2); + *oo++ = '\\n'; } .SH Output: - -1, -1, -1, -1, -1, 3.14 + -1, -1, -1, -1, -1, + 3.14; 2.71; + 2.2 ~ 3.2 ~ 4.2 ~ 5.2 ~ 6.2 ~ + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 1280 C++98 stream was stored directly stores its address + instead + default constructor was provided as removed along with + P2325R3 C++20 C++20 the requirement + iterators must be default_initializable diff --git a/man/std::ostream_iterator::~ostream_iterator.3 b/man/std::ostream_iterator::~ostream_iterator.3 index 5863ec29c..1f9c543a3 100644 --- a/man/std::ostream_iterator::~ostream_iterator.3 +++ b/man/std::ostream_iterator::~ostream_iterator.3 @@ -1,4 +1,7 @@ -.TH std::ostream_iterator::~ostream_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostream_iterator::~ostream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostream_iterator::~ostream_iterator \- std::ostream_iterator::~ostream_iterator + .SH Synopsis ~ostream_iterator() diff --git a/man/std::ostreambuf_iterator.3 b/man/std::ostreambuf_iterator.3 index ec89a6be0..30d9478c5 100644 --- a/man/std::ostreambuf_iterator.3 +++ b/man/std::ostreambuf_iterator.3 @@ -1,65 +1,71 @@ -.TH std::ostreambuf_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostreambuf_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostreambuf_iterator \- std::ostreambuf_iterator + .SH Synopsis Defined in header - template< class CharT, class Traits = std::char_traits> + template< class CharT, class Traits = std::char_traits > - class ostreambuf_iterator : public std::iterator + : public std::iterator + template< class CharT, class Traits = std::char_traits > \fI(since C++17)\fP + class ostreambuf_iterator; - std::ostreambuf_iterator is a single-pass output iterator that writes successive - characters into the std::basic_streambuf object for which it was constructed. The - actual write operation is performed when the iterator (whether dereferenced or not) - is assigned to. Incrementing the std::ostreambuf_iterator is a no-op. + std::ostreambuf_iterator is a single-pass LegacyOutputIterator that writes + successive characters into the std::basic_streambuf object for which it was + constructed. The actual write operation is performed when the iterator (whether + dereferenced or not) is assigned to. Incrementing the std::ostreambuf_iterator is a + no-op. In a typical implementation, the only data members of std::ostreambuf_iterator are a pointer to the associated std::basic_streambuf and a boolean flag indicating if the - the end of file condition has been reached. + end of file condition has been reached. .SH Member types - Member type Definition - char_type CharT - traits_type Traits - streambuf_type std::basic_streambuf - ostream_type std::basic_ostream + Member type Definition + iterator_category std::output_iterator_tag + value_type void + difference_type void \fI(until C++20)\fP + std::ptrdiff_t \fI(since C++20)\fP + pointer void + reference void + char_type CharT + traits_type Traits + streambuf_type std::basic_streambuf + ostream_type std::basic_ostream + + Member types iterator_category, value_type, difference_type, pointer + and reference are required to be obtained by inheriting from \fI(until C++17)\fP + std::iterator. .SH Member functions constructor constructs a new ostreambuf_iterator - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs an ostreambuf_iterator - (implicitly declared) \fI(public member function)\fP + (implicitly declared) \fI(public member function)\fP operator= writes a character to the associated output sequence - \fI(public member function)\fP + \fI(public member function)\fP operator* no-op - \fI(public member function)\fP + \fI(public member function)\fP operator++ no-op - operator++(int) \fI(public member function)\fP + operator++(int) \fI(public member function)\fP failed tests if output failed - \fI(public member function)\fP - -Inherited from std::iterator - -.SH Member types - - Member type Definition - value_type void - difference_type void - pointer void - reference void - iterator_category std::output_iterator_tag + \fI(public member function)\fP .SH Example - + // Run this code - #include #include - #include #include - + #include + #include + int main() { std::string s = "This is an example\\n"; @@ -73,6 +79,6 @@ Inherited from std::iterator .SH See also istreambuf_iterator input iterator that reads from std::basic_streambuf - \fI(class template)\fP + \fI(class template)\fP ostream_iterator output iterator that writes to std::basic_ostream - \fI(class template)\fP + \fI(class template)\fP diff --git a/man/std::ostreambuf_iterator::failed.3 b/man/std::ostreambuf_iterator::failed.3 index 65fe169ef..ea7f27d86 100644 --- a/man/std::ostreambuf_iterator::failed.3 +++ b/man/std::ostreambuf_iterator::failed.3 @@ -1,10 +1,14 @@ -.TH std::ostreambuf_iterator::failed 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostreambuf_iterator::failed 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostreambuf_iterator::failed \- std::ostreambuf_iterator::failed + .SH Synopsis - bool failed() const + bool failed() const throw(); \fI(until C++11)\fP + bool failed() const noexcept; \fI(since C++11)\fP Returns true if the iterator encountered the end-of-file condition, that is, if an - earlier call to std::basic_streambuf::sputc (made by operator=) returned Traits::eof - . + earlier call to std::basic_streambuf::sputc (made by operator=) returned + Traits::eof. .SH Parameters @@ -15,21 +19,10 @@ true if this iterator has encountered the end-of-file condition on output, false otherwise. -.SH Exceptions - - {{ - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - - }} - .SH Example This section is incomplete + Reason: no example .SH Category: - - * Todo without reason + * Todo no example diff --git a/man/std::ostreambuf_iterator::operator*.3 b/man/std::ostreambuf_iterator::operator*.3 index 0dd74b29c..f93356d52 100644 --- a/man/std::ostreambuf_iterator::operator*.3 +++ b/man/std::ostreambuf_iterator::operator*.3 @@ -1,12 +1,15 @@ -.TH std::ostreambuf_iterator::operator* 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostreambuf_iterator::operator* 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostreambuf_iterator::operator* \- std::ostreambuf_iterator::operator* + .SH Synopsis ostreambuf_iterator& operator*(); Does nothing, this member function is provided to satisfy the requirements of - OutputIterator. + LegacyOutputIterator. It returns the iterator itself, which makes it possible to use code such as *iter = - value to output (insert) the value into the underlying container. + value to output (insert) the value into the underlying stream. .SH Parameters diff --git a/man/std::ostreambuf_iterator::operator++.3 b/man/std::ostreambuf_iterator::operator++.3 index 54db6d3af..32bca4c76 100644 --- a/man/std::ostreambuf_iterator::operator++.3 +++ b/man/std::ostreambuf_iterator::operator++.3 @@ -1,11 +1,14 @@ -.TH std::ostreambuf_iterator::operator++ 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostreambuf_iterator::operator++ 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostreambuf_iterator::operator++ \- std::ostreambuf_iterator::operator++ + .SH Synopsis ostreambuf_iterator& operator++(); ostreambuf_iterator& operator++( int ); Does nothing. These operator overloads are provided to satisfy the requirements of - OutputIterator. They make it possible for the expressions *iter++=value and - *++iter=value to be used to output (insert) a value into the underlying container. + LegacyOutputIterator. They make it possible for the expressions *iter++=value and + *++iter=value to be used to output (insert) a value into the underlying stream. .SH Parameters diff --git a/man/std::ostreambuf_iterator::operator=.3 b/man/std::ostreambuf_iterator::operator=.3 index 6ab47d1fa..a669f812c 100644 --- a/man/std::ostreambuf_iterator::operator=.3 +++ b/man/std::ostreambuf_iterator::operator=.3 @@ -1,8 +1,11 @@ -.TH std::ostreambuf_iterator::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostreambuf_iterator::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostreambuf_iterator::operator= \- std::ostreambuf_iterator::operator= + .SH Synopsis - ostreambuf_iterator& operator=( CharT c ) + ostreambuf_iterator& operator=( CharT c ); - If failed() returns true, inserts the character c into the associated stream buffer + If failed() returns false, inserts the character c into the associated stream buffer by calling pbuf->sputc(c), where pbuf is the private member of type streambuf_type*. Otherwise, does nothing. @@ -19,12 +22,12 @@ .SH Example This section is incomplete + Reason: no example .SH See also sputc writes one character to the put area and advances the next pointer - \fI(public member function of std::basic_streambuf)\fP + \fI(public member function of std::basic_streambuf)\fP .SH Category: - - * Todo without reason + * Todo no example diff --git a/man/std::ostreambuf_iterator::ostreambuf_iterator.3 b/man/std::ostreambuf_iterator::ostreambuf_iterator.3 index 83a24ed34..3b288b02e 100644 --- a/man/std::ostreambuf_iterator::ostreambuf_iterator.3 +++ b/man/std::ostreambuf_iterator::ostreambuf_iterator.3 @@ -1,42 +1,66 @@ -.TH std::ostreambuf_iterator::ostreambuf_iterator 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostreambuf_iterator::ostreambuf_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostreambuf_iterator::ostreambuf_iterator \- std::ostreambuf_iterator::ostreambuf_iterator + .SH Synopsis - ostreambuf_iterator(streambuf_type* buffer) \fB(1)\fP - ostreambuf_iterator(ostream_type& stream) \fB(2)\fP + ostreambuf_iterator( streambuf_type* buffer ) \fI(until C++11)\fP + throw(); + ostreambuf_iterator( streambuf_type* buffer ) \fI(since C++11)\fP + noexcept; \fB(1)\fP + ostreambuf_iterator( ostream_type& stream ) \fI(until C++11)\fP + throw(); \fB(2)\fP + ostreambuf_iterator( ostream_type& stream ) \fI(since C++11)\fP + noexcept; 1) Constructs the iterator with the private streambuf_type* member set to buffer and - the failed() bit set to false. The behavior is undefined if buffer is a null + the failed() flag set to false. The behavior is undefined if buffer is a null pointer. - 2) Same as ostreambuf_iterator(stream.rdbuf()) + 2) Same as ostreambuf_iterator(stream.rdbuf()). .SH Parameters stream - the output stream whose rdbuf() will be accessed by this iterator buffer - the output stream buffer to be accessed by this iterator -.SH Exceptions - - \fI(none)\fP \fI(until C++11)\fP - noexcept specification: - noexcept \fI(since C++11)\fP - - .SH Example - + // Run this code - #include #include + #include #include + int main() { - std::basic_filebuf f; - f.open("test.txt", std::ios::out); - - std::ostreambuf_iterator out1(&f); - - std::ostreambuf_iterator out2(std::wcout); - - *out1 = 'a'; - *out2 = L'a'; + const char* file = "test.txt"; + { + std::basic_filebuf f; + f.open(file, std::ios::out); + std::ostreambuf_iterator out1(&f); + *out1 = 'a'; // writes to file via iterator + } + + // read back from the file + char a; + std::cout << ((std::ifstream{file} >> a), a) << std::endl; + + std::ostreambuf_iterator out2{std::wcout}; + *out2 = L'b'; } + +.SH Output: + + a + b + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 112 C++98 the requirement "the argument cannot applies to overload + be null" was applied to overload \fB(2)\fP \fB(1)\fP instead + P2325R3 C++20 default constructor was provided as C++20 removed along with + iterators must be default_initializable the requirement diff --git a/man/std::ostringstream.3 b/man/std::ostringstream.3 deleted file mode 120000 index 2599c8fd3..000000000 --- a/man/std::ostringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream.3 \ No newline at end of file diff --git a/man/std::ostringstream.3 b/man/std::ostringstream.3 new file mode 100644 index 000000000..476ad8c39 --- /dev/null +++ b/man/std::ostringstream.3 @@ -0,0 +1,277 @@ +.TH std::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream \- std::basic_ostringstream + +.SH Synopsis + Defined in header + template< + + class CharT, + class Traits = std::char_traits, + class Allocator = std::allocator + > class basic_ostringstream + + : public basic_ostream; + + The class template std::basic_ostringstream implements output operations on string + based streams. It effectively stores an instance of std::basic_string and performs + output operations to it. + + At the low level, the class essentially wraps a raw string device implementation of + std::basic_stringbuf into a higher-level interface of std::basic_ostream. The + complete interface to unique std::basic_stringbuf members is provided. + + std-basic ostringstream-inheritance.svg + + Inheritance diagram + + Several typedefs for common character types are provided: + + Defined in header + Type Definition + std::ostringstream std::basic_ostringstream + std::wostringstream std::basic_ostringstream + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits; the program is ill-formed if Traits::char_type is not + CharT. + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + allocator_type Allocator + + Exposition-only members + + Name Definition + the std::basic_stringbuf used as the underlying + sb buffer + (exposition-only member object*) + +.SH Member functions + + constructor constructs the string stream + \fI(public member function)\fP + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + rdbuf returns the underlying raw string device object + \fI(public member function)\fP +.SH String operations + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + view obtains a view over the contents of underlying string device object + (C++20) \fI(public member function)\fP + +.SH Non-member functions + + std::swap(std::basic_ostringstream) specializes the std::swap algorithm + \fI(C++11)\fP \fI(function template)\fP + +Inherited from std::basic_ostream + +.SH Member functions + +.SH Formatted output + operator<< inserts formatted data + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output + put inserts a character + \fI(public member function of std::basic_ostream)\fP + write inserts blocks of characters + \fI(public member function of std::basic_ostream)\fP +.SH Positioning + tellp returns the output position indicator + \fI(public member function of std::basic_ostream)\fP + seekp sets the output position indicator + \fI(public member function of std::basic_ostream)\fP +.SH Miscellaneous + flush synchronizes with the underlying storage device + \fI(public member function of std::basic_ostream)\fP + +.SH Member classes + + sentry implements basic logic for preparation of the stream for output operations + \fI(public member class of std::basic_ostream)\fP + +Inherited from std::basic_ios + +.SH Member types + + Member type Definition + char_type CharT + traits_type Traits + int_type Traits::int_type + pos_type Traits::pos_type + off_type Traits::off_type + +.SH Member functions + +.SH State functions + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP +.SH Formatting + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP +.SH Miscellaneous + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP + +Inherited from std::ios_base + +.SH Member functions + +.SH Formatting + flags manages format flags + \fI(public member function of std::ios_base)\fP + setf sets specific format flag + \fI(public member function of std::ios_base)\fP + unsetf clears specific format flag + \fI(public member function of std::ios_base)\fP + precision manages decimal precision of floating point operations + \fI(public member function of std::ios_base)\fP + width manages field width + \fI(public member function of std::ios_base)\fP +.SH Locales + imbue sets locale + \fI(public member function of std::ios_base)\fP + getloc returns current locale + \fI(public member function of std::ios_base)\fP +.SH Internal extensible array + xalloc returns a program-wide unique integer that is safe to use as index + \fB[static]\fP to pword() and iword() + \fI(public static member function of std::ios_base)\fP + resizes the private storage if necessary and access to the long + iword element at the given index + \fI(public member function of std::ios_base)\fP + resizes the private storage if necessary and access to the void* + pword element at the given index + \fI(public member function of std::ios_base)\fP +.SH Miscellaneous + register_callback registers event callback function + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP +.SH Member classes + failure stream exception + \fI(public member class of std::ios_base)\fP + Init initializes standard stream objects + \fI(public member class of std::ios_base)\fP + +.SH Member types and constants + Type Explanation + stream open mode type + + The following constants are also defined: + + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP + formatting flags type + + The following constants are also defined: + + Constant Explanation + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right + internal internal adjustment (adds fill characters to the internal + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha + generate a prefix indicating the numeric base for integer + showbase output, require the currency indicator in monetary I/O: + see std::showbase + showpoint generate a decimal-point character unconditionally for + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP + state of the stream type + + The following constants are also defined: + + Constant Explanation + iostate goodbit no error + badbit irrecoverable stream error + failbit input/output operation failed (formatting or extraction + error) + eofbit associated input sequence has reached end-of-file + + \fI(typedef)\fP + seeking direction type + + The following constants are also defined: + + seekdir Constant Explanation + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator + + \fI(typedef)\fP + event specifies event type + \fI(enum)\fP + event_callback callback function type + \fI(typedef)\fP diff --git a/man/std::ostringstream::basic_ostringstream.3 b/man/std::ostringstream::basic_ostringstream.3 deleted file mode 120000 index e9eb0c526..000000000 --- a/man/std::ostringstream::basic_ostringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::basic_ostringstream.3 \ No newline at end of file diff --git a/man/std::ostringstream::basic_ostringstream.3 b/man/std::ostringstream::basic_ostringstream.3 new file mode 100644 index 000000000..17a9cb9e1 --- /dev/null +++ b/man/std::ostringstream::basic_ostringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_ostringstream::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::basic_ostringstream \- std::basic_ostringstream::basic_ostringstream + +.SH Synopsis + explicit basic_ostringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_ostringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_ostringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_ostringstream(std::ios_base::out) {} + explicit basic_ostringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + explicit basic_ostringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + basic_ostringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_ostringstream(str, std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_ostringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + explicit basic_ostringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + basic_ostringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_ostringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_ostringstream( basic_ostringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_ostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_ostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_ostream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::out) + \fB(2)\fP buf_type(std::ios_base::out) + \fB(3)\fP buf_type(str, mode | + std::ios_base::out) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::out) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::out, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::out, a) + \fB(7)\fP buf_type(str, std::ios_base::out, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::out) + \fB(9)\fP {t, mode | std::ios_base::out, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::out, a} + \fB(11)\fP {t, std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_ostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_ostringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::ostringstream::operator=.3 b/man/std::ostringstream::operator=.3 deleted file mode 120000 index fe60e11e6..000000000 --- a/man/std::ostringstream::operator=.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::operator=.3 \ No newline at end of file diff --git a/man/std::ostringstream::operator=.3 b/man/std::ostringstream::operator=.3 new file mode 100644 index 000000000..8c4a77624 --- /dev/null +++ b/man/std::ostringstream::operator=.3 @@ -0,0 +1,38 @@ +.TH std::basic_ostringstream::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::operator= \- std::basic_ostringstream::operator= + +.SH Synopsis + basic_ostringstream& operator=( basic_ostringstream&& other ); \fI(since C++11)\fP + + Move assigns the string stream other to *this, effectively move-assigning both the + std::basic_ostream base class and the associated std::basic_stringbuf. + + Note that the base class move assignment swaps all stream state variables (except + for rdbuf) between *this and other. + +.SH Parameters + + other - string stream to move from + +.SH Return value + + *this + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + swap swaps two string streams + \fI(C++11)\fP \fI(public member function)\fP + operator= assigns a basic_stringbuf object + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + operator= move-assigns from another basic_ostream + \fI(C++11)\fP \fI(protected member function)\fP + +.SH Category: + * Todo no example diff --git a/man/std::ostringstream::ostringstream.3 b/man/std::ostringstream::ostringstream.3 deleted file mode 120000 index e9eb0c526..000000000 --- a/man/std::ostringstream::ostringstream.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::basic_ostringstream.3 \ No newline at end of file diff --git a/man/std::ostringstream::ostringstream.3 b/man/std::ostringstream::ostringstream.3 new file mode 100644 index 000000000..17a9cb9e1 --- /dev/null +++ b/man/std::ostringstream::ostringstream.3 @@ -0,0 +1,182 @@ +.TH std::basic_ostringstream::basic_ostringstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::basic_ostringstream \- std::basic_ostringstream::basic_ostringstream + +.SH Synopsis + explicit basic_ostringstream( std::ios_base::openmode mode = \fI(until C++11)\fP + std::ios_base::out ); + explicit basic_ostringstream( std::ios_base::openmode mode ); \fI(since C++11)\fP + basic_ostringstream() \fB(2)\fP \fI(since C++11)\fP + : basic_ostringstream(std::ios_base::out) {} + explicit basic_ostringstream + + ( const std::basic_string& str, \fB(3)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + explicit basic_ostringstream + + ( std::basic_string&& str, \fB(4)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + basic_ostringstream( std::ios_base::openmode mode, const \fB(5)\fP \fI(since C++20)\fP + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(6)\fP \fI(since C++20)\fP + + std::ios_base::openmode mode, const + Allocator& a ); + template< class SAlloc > + + basic_ostringstream( const std::basic_string& str, \fB(7)\fP \fI(since C++20)\fP + const Allocator& a ) + + : basic_ostringstream(str, std::ios_base::out, a) {} + template< class SAlloc > + + explicit basic_ostringstream + ( const std::basic_string& str, \fB(8)\fP \fI(since C++20)\fP + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + explicit basic_ostringstream + ( const StringViewLike& t, \fB(9)\fP (since C++26) + std::ios_base::openmode mode = + + std::ios_base::out ); + template< class StringViewLike > + + basic_ostringstream( const StringViewLike& t, \fB(10)\fP (since C++26) + + std::ios_base::openmode mode, const + Allocator& a ); + template< class StringViewLike > + basic_ostringstream( const StringViewLike& t, const \fB(11)\fP (since C++26) + Allocator& a ); + basic_ostringstream( basic_ostringstream&& other ); \fB(12)\fP \fI(since C++11)\fP + + Constructs new string stream. + + Given + + * base_type as std::basic_ostream, and + * buf_type as std::basic_stringbuf, + + the std::basic_ostream base and the exposition-only data member sb are initialized + as follows. + + Over std::basic_ostream base sb + load + \fB(1)\fP buf_type(mode | std::ios_base::out) + \fB(2)\fP buf_type(std::ios_base::out) + \fB(3)\fP buf_type(str, mode | + std::ios_base::out) + \fB(4)\fP buf_type(std::move(str), mode | + std::ios_base::out) + \fB(5)\fP base_type(std::addressof(sb))^[1] buf_type(mode | std::ios_base::out, + a) + \fB(6)\fP buf_type(str, mode | + std::ios_base::out, a) + \fB(7)\fP buf_type(str, std::ios_base::out, + a) + \fB(8)\fP buf_type(str, mode | + std::ios_base::out) + \fB(9)\fP {t, mode | std::ios_base::out, + std::addressof(sb) Allocator()} + \fB(10)\fP {t, mode | std::ios_base::out, a} + \fB(11)\fP {t, std::ios_base::out, a} + \fB(12)\fP move constructed from other's move constructed from other.sb + std::basic_ostream base + + 1. ↑ The std::basic_iostream base was intialized with base_type(&sb) (for overloads + (1,3)) until C++11. + 8) This overload participates in overload resolution only if std::is_same_v is false. + 9-11) These overloads participate in overload resolution only if + std::is_convertible_v> + is true. + +.SH Parameters + + str - string to use as initial contents of the string stream + t - an object (convertible to std::basic_string_view) to use as initial contents + of the string stream + a - allocator used for allocating the contents of the string stream + specifies stream open mode. It is a BitmaskType, the following constants are + defined: + + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode + other - another string stream to use as source + +.SH Notes + + Construction of one-off basic_ostringstream objects in a tight loop, such as when + used for string conversion, may be significantly more costly than calling str() to + reuse the same object. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, (9-11) + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // default constructor (input/output stream) + std::stringstream buf1; + buf1 << 7; + int n = 0; + buf1 >> n; + std::cout << "buf1 = " << buf1.str() << " n = " << n << '\\n'; + + // input stream + std::istringstream inbuf("-10"); + inbuf >> n; + std::cout << "n = " << n << '\\n'; + + // output stream in append mode \fI(C++11)\fP + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << buf2.str() << '\\n'; + } + +.SH Output: + + buf1 = 7 n = 7 + n = -10 + test1 + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + P0935R0 C++11 the default constructor was explicit made implicit + +.SH See also + + str gets or sets the contents of underlying string device object + \fI(public member function)\fP + constructs a basic_stringbuf object + constructor \fI\fI(public member\fP function of\fP + std::basic_stringbuf) diff --git a/man/std::ostringstream::rdbuf.3 b/man/std::ostringstream::rdbuf.3 deleted file mode 120000 index ae8aeecf2..000000000 --- a/man/std::ostringstream::rdbuf.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::rdbuf.3 \ No newline at end of file diff --git a/man/std::ostringstream::rdbuf.3 b/man/std::ostringstream::rdbuf.3 new file mode 100644 index 000000000..c81e2a3b3 --- /dev/null +++ b/man/std::ostringstream::rdbuf.3 @@ -0,0 +1,24 @@ +.TH std::basic_ostringstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::rdbuf \- std::basic_ostringstream::rdbuf + +.SH Synopsis + std::basic_stringbuf* rdbuf() const; + + Returns pointer to the underlying raw string device object. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + Pointer to the underlying raw string device. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::ostringstream::str.3 b/man/std::ostringstream::str.3 deleted file mode 120000 index a88de43b3..000000000 --- a/man/std::ostringstream::str.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::str.3 \ No newline at end of file diff --git a/man/std::ostringstream::str.3 b/man/std::ostringstream::str.3 new file mode 100644 index 000000000..dcc9f6094 --- /dev/null +++ b/man/std::ostringstream::str.3 @@ -0,0 +1,99 @@ +.TH std::basic_ostringstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::str \- std::basic_ostringstream::str + +.SH Synopsis + std::basic_string str() const; \fI(until C++20)\fP + std::basic_string str() const&; \fI(since C++20)\fP + template< class SAlloc > + std::basic_string str( const SAlloc& a \fB(2)\fP \fI(since C++20)\fP + ) const; + std::basic_string str() &&; \fB(3)\fP \fI(since C++20)\fP + void str( const std::basic_string& s \fB(1)\fP \fB(4)\fP + ); + template< class SAlloc > \fB(5)\fP \fI(since C++20)\fP + void str( const std::basic_string& s ); + void str( std::basic_string&& s ); \fB(6)\fP \fI(since C++20)\fP + template< class StringViewLike > \fB(7)\fP (since C++26) + void str( const StringViewLike& t ); + + Manages the contents of the underlying string object. + + 1) Returns a copy of the underlying string. Equivalent to return rdbuf()->str();. + 2) Returns a copy of the underlying string, using a as allocator. Equivalent to + return rdbuf()->str(a);. + 3) Returns a string move-constructed from the underlying string. Equivalent to + return std::move(*rdbuf()).str();. + 4,5) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(s);. + 6) Replaces the contents of the underlying string. Equivalent to + rdbuf()->str(std::move(s));. + 7) Replaces the contents of the underlying string. Equivalent to rdbuf()->str(t);. + This overload participates in overload resolution only if is_convertible_v> is true. + +.SH Parameters + + s - new contents of the underlying string + t - an object (convertible to std::basic_string_view) to use as the new contents of + the underlying string + a - allocator used to construct the returned string + +.SH Return value + + 1,2) A copy of the underlying string object. + 3) A string move-constructed from the underlying string object. + 4-7) \fI(none)\fP + +.SH Notes + + The copy of the underlying string returned by str is a temporary object that will be + destructed at the end of the expression, so directly calling c_str() on the result + of str() (for example in auto *ptr = out.str().c_str();) results in a dangling + pointer. + + Feature-test macro Value Std Feature + __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing std::stringstreams + with std::string_view, \fB(7)\fP + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + int n; + + std::istringstream in; // could also use in("1 2") + in.str("1 2"); + in >> n; + std::cout << "After reading the first int from \\"1 2\\", the int is " + << n << ", str() = \\"" << in.str() << "\\"\\n"; + + std::ostringstream out("1 2"); + out << 3; + std::cout << "After writing the int '3' to output stream \\"1 2\\"" + << ", str() = \\"" << out.str() << "\\"\\n"; + + std::ostringstream ate("1 2", std::ios_base::ate); + ate << 3; + std::cout << "After writing the int '3' to append stream \\"1 2\\"" + << ", str() = \\"" << ate.str() << "\\"\\n"; + } + +.SH Output: + + After reading the first int from "1 2", the int is 1, str() = "1 2" + After writing the int '3' to output stream "1 2", str() = "3 2" + After writing the int '3' to append stream "1 2", str() = "1 23" + +.SH See also + + rdbuf returns the underlying raw string device object + \fI(public member function)\fP + replaces or obtains a copy of the associated character string + str \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::ostringstream::swap.3 b/man/std::ostringstream::swap.3 deleted file mode 120000 index 2d90861d4..000000000 --- a/man/std::ostringstream::swap.3 +++ /dev/null @@ -1 +0,0 @@ -std::basic_ostringstream::swap.3 \ No newline at end of file diff --git a/man/std::ostringstream::swap.3 b/man/std::ostringstream::swap.3 new file mode 100644 index 000000000..10baede6b --- /dev/null +++ b/man/std::ostringstream::swap.3 @@ -0,0 +1,39 @@ +.TH std::basic_ostringstream::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::swap \- std::basic_ostringstream::swap + +.SH Synopsis + void swap( basic_ostringstream& other ); \fI(since C++11)\fP + + Exchanges the state of the stream with those of other. + + This is done by calling basic_ostream::swap(other) and + rdbuf()->swap(*other.rdbuf()). + +.SH Parameters + + other - stream to exchange the state with + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + operator= moves the string stream + \fI(C++11)\fP \fI(public member function)\fP + swap swaps two basic_stringbuf objects + \fI(C++11)\fP \fI(public member function of std::basic_stringbuf)\fP + + +.SH Category: + * Todo no example diff --git a/man/std::ostringstream::view.3 b/man/std::ostringstream::view.3 new file mode 100644 index 000000000..a98e54d32 --- /dev/null +++ b/man/std::ostringstream::view.3 @@ -0,0 +1,57 @@ +.TH std::basic_ostringstream::view 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::basic_ostringstream::view \- std::basic_ostringstream::view + +.SH Synopsis + std::basic_string_view view() const noexcept; \fI(since C++20)\fP + + Obtains a std::basic_string_view over the underlying string object. Equivalent to + return rdbuf()->view();. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + A std::basic_string_view over the underlying string object. + +.SH Example + + +// Run this code + + #include + #include + + int main() + { + // input/output stream + std::stringstream buf1; + buf1 << 69; + int n = 0; + buf1 >> n; + std::cout << "1) buf1 = [" << buf1.view() << "], n = " << n << '\\n'; + + // output stream in append mode + std::ostringstream buf2("test", std::ios_base::ate); + buf2 << '1'; + std::cout << "2) buf2 = [" << buf2.view() << "]\\n"; + + // input stream + std::istringstream inbuf("-42"); + inbuf >> n; + std::cout << "3) inbuf = [" << inbuf.view() << "], n = " << n << '\\n'; + } + +.SH Output: + + 1) buf1 = [69], n = 69 + 2) buf2 = [test1] + 3) inbuf = [-42], n = -42 + +.SH See also + + view obtains a view over the underlying character sequence + (C++20) \fI(public member function of std::basic_stringbuf)\fP + diff --git a/man/std::ostrstream.3 b/man/std::ostrstream.3 index 619d9a15c..fe313008a 100644 --- a/man/std::ostrstream.3 +++ b/man/std::ostrstream.3 @@ -1,7 +1,11 @@ -.TH std::ostrstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream \- std::ostrstream + .SH Synopsis Defined in header - class ostrstream : public std::ostream \fB(deprecated)\fP + class ostrstream : public std::ostream (deprecated in C++98) + (removed in C++26) The class ostrstream implements output operations on array-backed streams. It essentially wraps a raw array I/O device implementation (std::strstreambuf) into the @@ -15,49 +19,54 @@ After any call to str(), a call to freeze(false) is required to allow the destructor to deallocate the buffer as necessary. - ostrstream has been deprecated since C++98, std::ostringstream and - boost::iostreams::array_sink are the recommended replacements. + Before any call to str() that uses the result as a C-string, the buffer must be + null-terminated, typically with std::ends. + + ostrstream has been deprecated since C++98 and removed since C++26. + std::ostringstream + , std::ospanstream + (since C++23), and boost::iostreams::array_sink are the recommended replacements. .SH Member functions - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function)\fP - destructor destructs a strstream, optionally deallocating the buffer - \fB[virtual]\fP \fI(virtual public member function)\fP + constructor constructs an ostrstream object, optionally allocating the buffer + \fI(public member function)\fP + destructor destructs an ostrstream object, optionally deallocating the buffer + \fB[virtual]\fP \fI(virtual public member function)\fP rdbuf obtains a pointer to the associated strstreambuf - \fI(public member function)\fP + \fI(public member function)\fP str accesses the output buffer - \fI(public member function)\fP + \fI(public member function)\fP freeze disables/enables automatic reallocation - \fI(public member function)\fP + \fI(public member function)\fP pcount obtains the number of characters written - \fI(public member function)\fP + \fI(public member function)\fP Inherited from std::basic_ostream .SH Member functions -.SH Formatted input +.SH Formatted output operator<< inserts formatted data - \fI(public member function of std::basic_ostream)\fP -.SH Unformatted input + \fI(public member function of std::basic_ostream)\fP +.SH Unformatted output put inserts a character - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP write inserts blocks of characters - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Positioning tellp returns the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP seekp sets the output position indicator - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Miscellaneous flush synchronizes with the underlying storage device - \fI(public member function of std::basic_ostream)\fP + \fI(public member function of std::basic_ostream)\fP .SH Member classes sentry implements basic logic for preparation of the stream for output operations - \fI(public member class of std::basic_ostream)\fP + \fI(public member class of std::basic_ostream)\fP Inherited from std::basic_ios @@ -70,45 +79,45 @@ Inherited from std::basic_ios pos_type Traits::pos_type off_type Traits::off_type +.SH Member functions + .SH State functions - good checks if no error has occurred i.e. I/O operations are available - \fI(public member function of std::basic_ios)\fP - eof checks if end-of-file has been reached - \fI(public member function of std::basic_ios)\fP - fail checks if a recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - bad checks if a non-recoverable error has occurred - \fI(public member function of std::basic_ios)\fP - operator! checks if an error has occurred (synonym of fail() - \fI(public member function of std::basic_ios)\fP - operator void* - operator bool checks if no error has occurred (synonym of !fail()) - \fI(until C++11)\fP \fI(public member function of std::basic_ios)\fP - \fI(since C++11)\fP - rdstate returns state flags - \fI(public member function of std::basic_ios)\fP - setstate sets state flags - \fI(public member function of std::basic_ios)\fP - clear clears error and eof flags - \fI(public member function of std::basic_ios)\fP + good checks if no error has occurred i.e. I/O operations are available + \fI(public member function of std::basic_ios)\fP + eof checks if end-of-file has been reached + \fI(public member function of std::basic_ios)\fP + fail checks if an error has occurred + \fI(public member function of std::basic_ios)\fP + bad checks if a non-recoverable error has occurred + \fI(public member function of std::basic_ios)\fP + operator! checks if an error has occurred (synonym of fail()) + \fI(public member function of std::basic_ios)\fP + operator bool checks if no error has occurred (synonym of !fail()) + \fI(public member function of std::basic_ios)\fP + rdstate returns state flags + \fI(public member function of std::basic_ios)\fP + setstate sets state flags + \fI(public member function of std::basic_ios)\fP + clear modifies state flags + \fI(public member function of std::basic_ios)\fP .SH Formatting - copyfmt copies formatting information - \fI(public member function of std::basic_ios)\fP - fill manages the fill character - \fI(public member function of std::basic_ios)\fP + copyfmt copies formatting information + \fI(public member function of std::basic_ios)\fP + fill manages the fill character + \fI(public member function of std::basic_ios)\fP .SH Miscellaneous - exceptions manages exception mask - \fI(public member function of std::basic_ios)\fP - imbue sets the locale - \fI(public member function of std::basic_ios)\fP - rdbuf manages associated stream buffer - \fI(public member function of std::basic_ios)\fP - tie manages tied stream - \fI(public member function of std::basic_ios)\fP - narrow narrows characters - \fI(public member function of std::basic_ios)\fP - widen widens characters - \fI(public member function of std::basic_ios)\fP + exceptions manages exception mask + \fI(public member function of std::basic_ios)\fP + imbue sets the locale + \fI(public member function of std::basic_ios)\fP + rdbuf manages associated stream buffer + \fI(public member function of std::basic_ios)\fP + tie manages tied stream + \fI(public member function of std::basic_ios)\fP + narrow narrows characters + \fI(public member function of std::basic_ios)\fP + widen widens characters + \fI(public member function of std::basic_ios)\fP Inherited from std::ios_base @@ -116,40 +125,40 @@ Inherited from std::ios_base .SH Formatting flags manages format flags - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP setf sets specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP unsetf clears specific format flag - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP precision manages decimal precision of floating point operations - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP width manages field width - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Locales imbue sets locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP getloc returns current locale - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Internal extensible array xalloc returns a program-wide unique integer that is safe to use as index \fB[static]\fP to pword() and iword() - \fI(public static member function of std::ios_base)\fP + \fI(public static member function of std::ios_base)\fP resizes the private storage if necessary and access to the long iword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP resizes the private storage if necessary and access to the void* pword element at the given index - \fI(public member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP .SH Miscellaneous register_callback registers event callback function - \fI(public member function of std::ios_base)\fP - sync_with_stdio sets whether C++ and C IO libraries are interoperable - \fB[static]\fP \fI(public static member function of std::ios_base)\fP + \fI(public member function of std::ios_base)\fP + sync_with_stdio sets whether C++ and C I/O libraries are interoperable + \fB[static]\fP \fI(public static member function of std::ios_base)\fP .SH Member classes failure stream exception - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP Init initializes standard stream objects - \fI(public member class of std::ios_base)\fP + \fI(public member class of std::ios_base)\fP .SH Member types and constants Type Explanation @@ -157,76 +166,83 @@ Inherited from std::ios_base The following constants are also defined: - Constant Explanation - app seek to the end of stream before each write - openmode binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open - - \fI(typedef)\fP + Constant Explanation + app seek to the end of stream before each write + binary open in binary mode + openmode in open for reading + out open for writing + trunc discard the contents of the stream when + opening + ate seek to the end of stream immediately after + open + noreplace (C++23) open in exclusive mode + + \fI(typedef)\fP formatting flags type The following constants are also defined: Constant Explanation - dec use decimal base for integer I/O - oct use octal base for integer I/O - hex use hexadecimal base for integer I/O - basefield dec|oct|hex|0. Useful for masking operations - left left adjustment (adds fill characters to the right) - - right right adjustment (adds fill characters to the left) - + dec use decimal base for integer I/O: see std::dec + oct use octal base for integer I/O: see std::oct + hex use hexadecimal base for integer I/O: see std::hex + basefield dec | oct | hex. Useful for masking operations + left left adjustment (adds fill characters to the right): see + std::left + right right adjustment (adds fill characters to the left): see + std::right internal internal adjustment (adds fill characters to the internal - designated point) - adjustfield left|right|internal. Useful for masking operations - scientific generate floating point types using scientific notation, - or hex notation if combined with fixed - fmtflags fixed generate floating point types using fixed notation, or - hex notation if combined with scientific - floatfield scientific|fixed|(scientific|fixed)|0. Useful for masking - operations - boolalpha insert and extract bool type in alphanumeric format - + designated point): see std::internal + adjustfield left | right | internal. Useful for masking + operations + generate floating point types using scientific notation, + scientific or hex notation if combined with fixed: see + std::scientific + fmtflags generate floating point types using fixed notation, or + fixed hex notation if combined with scientific: see + std::fixed + floatfield scientific | fixed. Useful for masking operations + boolalpha insert and extract bool type in alphanumeric format: see + std::boolalpha generate a prefix indicating the numeric base for integer - showbase output, require the currency indicator in monetary I/O - + showbase output, require the currency indicator in monetary I/O: + see std::showbase showpoint generate a decimal-point character unconditionally for - floating-point number output - showpos generate a + character for non-negative numeric output - - skipws skip leading whitespace before certain input operations - - unitbuf flush the output after each output operation - uppercase replace certain lowercase letters with their uppercase - equivalents in certain output output operations - - \fI(typedef)\fP + floating-point number output: see std::showpoint + showpos generate a + character for non-negative numeric output: + see std::showpos + skipws skip leading whitespace before certain input operations: + see std::skipws + unitbuf flush the output after each output operation: see + std::unitbuf + replace certain lowercase letters with their uppercase + uppercase equivalents in certain output operations: see + std::uppercase + + \fI(typedef)\fP state of the stream type The following constants are also defined: Constant Explanation - iostate goodbit no error - badbit irrecoverable stream error + iostate goodbit no error + badbit irrecoverable stream error failbit input/output operation failed (formatting or extraction - error) - eofbit associated input sequence has reached end-of-file + error) + eofbit associated input sequence has reached end-of-file - \fI(typedef)\fP + \fI(typedef)\fP seeking direction type The following constants are also defined: seekdir Constant Explanation - beg the beginning of a stream - end the ending of a stream - cur the current position of stream position indicator + beg the beginning of a stream + end the ending of a stream + cur the current position of stream position indicator - \fI(typedef)\fP + \fI(typedef)\fP event specifies event type - \fI(enum)\fP + \fI(enum)\fP event_callback callback function type - \fI(typedef)\fP + \fI(typedef)\fP diff --git a/man/std::ostrstream::freeze.3 b/man/std::ostrstream::freeze.3 index 02819ba50..a02add1fd 100644 --- a/man/std::ostrstream::freeze.3 +++ b/man/std::ostrstream::freeze.3 @@ -1,16 +1,20 @@ -.TH std::ostrstream::freeze 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream::freeze 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream::freeze \- std::ostrstream::freeze + .SH Synopsis - void freeze(bool flag = true); + void freeze( bool flag = true ); (deprecated in C++98) + (removed in C++26) If the stream is using a dynamically-allocated array for output, disables (flag == true) or enables (flag == false) automatic allocation/deallocation of the buffer. - Effectively calls rdbuf()->pcount() + Effectively calls rdbuf()->freeze(flag). .SH Notes After a call to str(), dynamic streams become frozen automatically. A call to freeze(false) is required before exiting the scope in which this ostrstream object - was created. otherwise the destructor will leak memory. Also, additional output to a + was created, otherwise the destructor will leak memory. Also, additional output to a frozen stream may be truncated once it reaches the end of the allocated buffer. .SH Parameters @@ -23,32 +27,42 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::ostrstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; - std::cout << "The output stream contains \\"" << dyn.str() << "\\"\\n"; - - dyn << "Test: " << 1.23; - std::cout << "The output stream contains \\"" << dyn.str() << "\\"\\n"; + dyn << "Test: " << 1.23; // note: no std::ends to demonstrate appending + std::cout << "The output stream contains \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; // the stream is now frozen due to str() - dyn << " More text"; - std::cout << "The output stream contains \\"" << dyn.str() << "\\"\\n"; - dyn.freeze(false); + dyn << " More text"; // output to a frozen stream may be truncated + std::cout << "The output stream contains \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; + dyn.freeze(false); // freeze(false) must be called or the destructor will leak + + std::ostrstream dyn2; // dynamically-allocated output buffer + dyn2 << "Test: " << 1.23; // note: no std::ends + std::cout << "The output stream contains \\""; + std::cout.write(dyn2.str(), dyn2.pcount()) << "\\"\\n"; + dyn2.freeze(false); // unfreeze the stream after str() + dyn2 << " More text" << std::ends; // output will not be truncated (buffer grows) + std::cout << "The output stream contains \\"" << dyn2.str() << "\\"\\n"; + dyn2.freeze(false); // freeze(false) must be called or the destructor will leak } .SH Possible output: The output stream contains "Test: 1.23" The output stream contains "Test: 1.23 More " + The output stream contains "Test: 1.23" + The output stream contains "Test: 1.23 More text" .SH See also freeze sets/clears the frozen state of the buffer - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP diff --git a/man/std::ostrstream::ostrstream.3 b/man/std::ostrstream::ostrstream.3 index 1048c42e8..1aac090e9 100644 --- a/man/std::ostrstream::ostrstream.3 +++ b/man/std::ostrstream::ostrstream.3 @@ -1,7 +1,12 @@ -.TH std::ostrstream::ostrstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream::ostrstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream::ostrstream \- std::ostrstream::ostrstream + .SH Synopsis - ostrstream(); \fB(1)\fP - ostrstream(char* s, int n, std::ios_base::openmode mode = std::ios_base::out); \fB(2)\fP + ostrstream(); \fB(1)\fP (deprecated in C++98) + (removed in C++26) + ostrstream( char* s, int n, std::ios_base::openmode mode = \fB(2)\fP (deprecated in C++98) + std::ios_base::out ); (removed in C++26) Constructs new output strstream and its underlying std::strstreambuf. @@ -26,31 +31,32 @@ specifies stream open mode. It is a bitmask type, the following constants are defined (although only app is used): - Constant Explanation - mode - app seek to the end of stream before each write - binary open in binary mode - in open for reading - out open for writing - trunc discard the contents of the stream when opening - ate seek to the end of stream immediately after open + Constant Explanation + app seek to the end of stream before each write + mode - binary open in binary mode + in open for reading + out open for writing + trunc discard the contents of the stream when opening + ate seek to the end of stream immediately after open + noreplace (C++23) open in exclusive mode .SH Example - + // Run this code #include #include - + int main() { std::ostrstream s1; // dynamic buffer s1 << 1 << ' ' << 3.14 << " example\\n" << std::ends; std::cout << s1.str(); s1.freeze(false); - + char arr[15] = "Hello"; - + std::ostrstream s2(arr, sizeof arr, std::ios_base::app); s2 << ", world!" << std::ends; std::cout << s2.str() << '\\n'; @@ -66,8 +72,8 @@ .SH See also constructor constructs a strstreambuf object - \fI(public member function of std::strstreambuf)\fP - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function of std::istrstream)\fP - constructor constructs an strstream, optionally allocating the buffer - \fI(public member function of std::strstream)\fP + \fI(public member function of std::strstreambuf)\fP + constructor constructs an istrstream object, optionally allocating the buffer + \fI(public member function of std::istrstream)\fP + constructor constructs a strstream object, optionally allocating the buffer + \fI(public member function of std::strstream)\fP diff --git a/man/std::ostrstream::pcount.3 b/man/std::ostrstream::pcount.3 index 134ec3fef..1bf0808bc 100644 --- a/man/std::ostrstream::pcount.3 +++ b/man/std::ostrstream::pcount.3 @@ -1,9 +1,13 @@ -.TH std::ostrstream::pcount 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream::pcount 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream::pcount \- std::ostrstream::pcount + .SH Synopsis - int pcount() const; + int pcount() const; (deprecated in C++98) + (removed in C++26) Returns the number of characters that were output in the put area of the associated - std::strstreambuf. Effectively calls rdbuf()->pcount() + std::strstreambuf. Effectively calls rdbuf()->pcount(). .SH Parameters @@ -15,20 +19,20 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { std::ostrstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; + dyn << "Test: " << 1.23 << std::ends; std::cout << "The size of the output is " << dyn.pcount() << " and it holds \\"" << dyn.str() << "\\"\\n"; dyn.freeze(false); - + char buf[10]; std::ostrstream user(buf, 10); // user-provided output buffer user << 1.23; // note: no std::ends @@ -38,11 +42,11 @@ .SH Output: - The size of the output is 10 and it holds "Test: 1.23" + The size of the output is 11 and it holds "Test: 1.23" 1.23 .SH See also returns the next pointer minus the beginning pointer in the output sequence: pcount the number of characters written - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP diff --git a/man/std::ostrstream::rdbuf.3 b/man/std::ostrstream::rdbuf.3 index 803dd0676..0e2fff539 100644 --- a/man/std::ostrstream::rdbuf.3 +++ b/man/std::ostrstream::rdbuf.3 @@ -1,9 +1,13 @@ -.TH std::ostrstream::rdbuf 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream::rdbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream::rdbuf \- std::ostrstream::rdbuf + .SH Synopsis - strstreambuf* rdbuf() const; + strstreambuf* rdbuf() const; (deprecated in C++98) + (removed in C++26) Returns a pointer to the associated std::strstreambuf, casting away its constness - (despite the const qualifier on the member function) + (despite the const qualifier on the member function). .SH Parameters @@ -11,16 +15,17 @@ .SH Return value - Pointer to the associated std::strsteambuf, with constness cast away. + Pointer to the associated std::strstreambuf, with constness cast away. .SH Example - + // Run this code #include + int main() { - const std::ostrstream buf; + const std::ostrstream buf; std::strstreambuf* ptr = buf.rdbuf(); } diff --git a/man/std::ostrstream::str.3 b/man/std::ostrstream::str.3 index 95a4525b7..e23d97e87 100644 --- a/man/std::ostrstream::str.3 +++ b/man/std::ostrstream::str.3 @@ -1,16 +1,13 @@ -.TH std::ostrstream::str 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream::str 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream::str \- std::ostrstream::str + .SH Synopsis - char* str(); + char* str(); (deprecated in C++98) + (removed in C++26) Returns the pointer to the beginning of the buffer, after freezing it. Effectively - calls rdbuf()->str() - -.SH Notes - - After a call to str(), dynamic streams become frozen. A call to freeze(false) is - required before exiting the scope in which this ostrstream object was created. - otherwise the destructor will leak memory. Also, additional output to a frozen - stream may be truncated once it reaches the end of the allocated buffer. + calls rdbuf()->str(). .SH Parameters @@ -18,28 +15,40 @@ .SH Return value - Pointer to the beginning of the buffer in the associated std::strsteambuf or NULL if - no buffer is available. + Pointer to the beginning of the buffer in the associated std::strstreambuf or a null + pointer if no buffer is available. + +.SH Notes + + Before a call to str() that uses the result as a C-string, the stream buffer must be + null-terminated. Regular output such as with stream << 1.2 does not store a null + terminator, it must be appended explicitly, typically with the manipulator + std::ends. + + After a call to str(), dynamic streams become frozen. A call to freeze(false) is + required before exiting the scope in which this ostrstream object was created. + otherwise the destructor will leak memory. Also, additional output to a frozen + stream may be truncated once it reaches the end of the allocated buffer, which may + leave the buffer not null-terminated. .SH Example - + // Run this code - #include #include - + #include + int main() { std::ostrstream dyn; // dynamically-allocated output buffer - dyn << "Test: " << 1.23; - std::cout << "The output stream holds \\"" << dyn.str() << "\\"\\n"; - - dyn << "Test: " << 1.23; - std::cout << "The output stream holds \\"" << dyn.str() << "\\"\\n"; + dyn << "Test: " << 1.23; // not adding std::ends to demonstrate append behavior + std::cout << "The output stream holds \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; // the stream is now frozen due to str() - dyn << " More text"; - std::cout << "The output stream holds \\"" << dyn.str() << "\\"\\n"; + dyn << " More text" << std::ends; + std::cout << "The output stream holds \\""; + std::cout.write(dyn.str(), dyn.pcount()) << "\\"\\n"; dyn.freeze(false); } @@ -51,4 +60,4 @@ .SH See also str marks the buffer frozen and returns the beginning pointer of the input sequence - \fI(public member function of std::strstreambuf)\fP + \fI(public member function of std::strstreambuf)\fP diff --git a/man/std::ostrstream::~ostrstream.3 b/man/std::ostrstream::~ostrstream.3 index 3d1186485..5fa0d71ea 100644 --- a/man/std::ostrstream::~ostrstream.3 +++ b/man/std::ostrstream::~ostrstream.3 @@ -1,6 +1,10 @@ -.TH std::ostrstream::~ostrstream 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::ostrstream::~ostrstream 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::ostrstream::~ostrstream \- std::ostrstream::~ostrstream + .SH Synopsis - virtual ~ostrstream(); + virtual ~ostrstream(); (deprecated in C++98) + (removed in C++26) Destroys a std::ostrstream object, which also destroys the member std::strstreambuf, which may call the deallocation function if the underlying buffer was @@ -17,12 +21,12 @@ .SH Example - + // Run this code - #include #include - + #include + int main() { { @@ -31,13 +35,14 @@ std::cout << s.str() << '\\n'; s.freeze(false); } // destructor called, buffer deallocated - + { std::ostrstream s; s << 1.23; std::cout << s.str() << '\\n'; - // buf.freeze(false); + // buf.freeze(false); } // destructor called, memory leaked + } .SH Output: diff --git a/man/std::out_of_range.3 b/man/std::out_of_range.3 index 3943833b5..f9442db45 100644 --- a/man/std::out_of_range.3 +++ b/man/std::out_of_range.3 @@ -1,4 +1,7 @@ -.TH std::out_of_range 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::out_of_range 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::out_of_range \- std::out_of_range + .SH Synopsis Defined in header class out_of_range; @@ -6,44 +9,129 @@ Defines a type of object to be thrown as exception. It reports errors that are consequence of attempt to access elements out of defined range. + It may be thrown by the member functions of std::bitset and std::basic_string, by + std::stoi and std::stod families of functions, and by the bounds-checked member + access functions (e.g. std::vector::at and std::map::at). + std-out of range-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP - - + constructor constructs a new out_of_range object with the given message + \fI(public member function)\fP + operator= replaces the out_of_range object + \fI(public member function)\fP - std::out_of_range::out_of_range +std::out_of_range::out_of_range - explicit out_of_range( const std::string& what_arg ); \fB(1)\fP - explicit out_of_range( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP + out_of_range( const std::string& what_arg ); \fB(1)\fP + out_of_range( const char* what_arg ); \fB(2)\fP + out_of_range( const out_of_range& other ); \fB(3)\fP (noexcept since C++11) - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::out_of_range + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::out_of_range is not permitted to throw exceptions, this message + is typically stored internally as a separately-allocated reference-counted string. + This is also why there is no constructor taking std::string&&: it would have to copy + the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::out_of_range::operator= + + out_of_range& operator=( const out_of_range& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::out_of_range then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::logic_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Notes + + The standard error condition std::errc::result_out_of_range typically indicates the + condition where the result, rather than the input, is out of range, and is more + closely related to std::range_error and ERANGE. + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const char* added + was missing + the explanatory strings of they are the same as that + LWG 471 C++98 std::out_of_range's of the + copies were implementation-defined original std::out_of_range + object .SH See also - at access specified character with bounds checking - \fI(public member function of std::basic_string)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string)\fP + at accesses the specified character with bounds checking + \fI(public member function of std::basic_string_view)\fP + at access specified element with bounds checking + \fI(public member function of std::deque)\fP + at access specified element with bounds checking + \fI(public member function of std::map)\fP + access specified element with bounds checking + at \fI\fI(public member\fP function of\fP + std::unordered_map) + at access specified element with bounds checking + \fI(public member function of std::vector)\fP + at access specified element with bounds checking + \fI(public member function of std::array)\fP + at access specified element with bounds checking + (C++26) \fI(public member function of std::span)\fP diff --git a/man/std::out_ptr.3 b/man/std::out_ptr.3 new file mode 100644 index 000000000..bf469a804 --- /dev/null +++ b/man/std::out_ptr.3 @@ -0,0 +1,88 @@ +.TH std::out_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::out_ptr \- std::out_ptr + +.SH Synopsis + Defined in header + template< class Pointer = void, class Smart, class... Args > (since C++23) + auto out_ptr( Smart& s, Args&&... args ); + + Returns an std::out_ptr_t with deduced template arguments that captures arguments + for resetting by reference. + + The program is ill-formed if construction of the return value (see below) is + ill-formed. + +.SH Parameters + + s - the object (typically a smart pointer) to adapt + args... - the arguments for resetting to capture + +.SH Return value + + std::out_ptr_t(s, std::forward(args)...), where P is + + * Pointer, if Pointer is not same as void. Otherwise, + * Smart::pointer, if it is valid and denotes a type. Otherwise, + * Smart::element_type*, if Smart::element_type is valid and denotes a type. + Otherwise, + * std::pointer_traits::element_type*. + +.SH Notes + + Users may specify the template argument for the template parameter Pointer, in order + to interoperate with foreign functions that take a Pointer*. + + As all arguments for resetting are captured by reference, the returned out_ptr_t + should be a temporary object destroyed at the end of the full-expression containing + the call to the foreign function, in order to avoid dangling references. + + Feature-test macro Value Std Feature + __cpp_lib_out_ptr 202106L (C++23) std::out_ptr, std::inout_ptr + 202311L (C++26) freestanding std::out_ptr and std::inout_ptr + +.SH Example + + Use std::out_ptr to adapt a smart pointer for sqlite3_open, which expects a + sqlite3** as an out parameter. + + +// Run this code + + #include + #include + + int main() + { + auto close_db = [](sqlite3* db) { sqlite3_close(db); }; + + { + // open an in-memory database, and manage its lifetime with std::unique_ptr + std::unique_ptr up; + sqlite3_open(":memory:", std::out_ptr(up)); + + sqlite3* db = up.get(); + // do something with db ... + } + { + // same as above, but use a std::shared_ptr + std::shared_ptr sp; + sqlite3_open(":memory:", std::out_ptr(sp, close_db)); + + sqlite3* db = sp.get(); + // do something with db ... + } + } + +.SH See also + + inout_ptr creates an inout_ptr_t with an associated smart pointer + (C++23) and resetting arguments + \fI(function template)\fP + make_unique + make_unique_for_overwrite creates a unique pointer that manages a new object + \fI(C++14)\fP \fI(function template)\fP + (C++20) + make_shared creates a shared pointer that manages a new object + make_shared_for_overwrite \fI(function template)\fP + (C++20) diff --git a/man/std::out_ptr_t.3 b/man/std::out_ptr_t.3 new file mode 100644 index 000000000..2657de8d9 --- /dev/null +++ b/man/std::out_ptr_t.3 @@ -0,0 +1,130 @@ +.TH std::out_ptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::out_ptr_t \- std::out_ptr_t + +.SH Synopsis + Defined in header + template< class Smart, class Pointer, class... Args > (since C++23) + class out_ptr_t; + + out_ptr_t is used to adapt types such as smart pointers for foreign functions that + output their results via a Pointer* (usually T** for some object type T) or void** + parameter. + + out_ptr_t captures additional arguments on construction, provides storage for the + result to which such an aforementioned foreign function writes, and finally resets + the adapted Smart object with the result and the captured arguments when it is + destroyed. + + out_ptr_t behaves as if it holds following non-static data members: + + * a Smart& reference, which is bound to the adapted object on construction, + * for every T in Args..., a member of type T, which is an argument captured on + construction and used for resetting while destruction, and + * a member subobject that suitable for storing a Pointer within it and providing a + void* object, where the Pointer or void* object is generally exposed to a + foreign function for re-initialization. + + Users can control whether each argument for resetting is captured by copy or by + reference, by specifying an object type or a reference type in Args... respectively. + +.SH Template parameters + + Smart - the type of the object (typically a smart pointer) to adapt + Pointer - type of the object (typically a raw pointer) to which a foreign function + writes its result + Args... - type of captured arguments used for resetting the adapted object +.SH Type requirements + - + Pointer must meet the requirements of NullablePointer. + - + The program is ill-formed if Smart is a std::shared_ptr specialization and + sizeof...(Args) == 0. + +.SH Specializations + + Unlike most class templates in the standard library, program-defined specializations + of out_ptr_t that depend on at least one program-defined type need not meet the + requirements for the primary template. + + This license allows a program-defined specialization to expose the raw pointer + stored within a non-standard smart pointer to foreign functions. + +.SH Member functions + + constructor constructs an out_ptr_t + (C++23) \fI(public member function)\fP + operator= out_ptr_t is not assignable + [deleted](C++23) \fI(public member function)\fP + destructor resets the adapted smart pointer + (C++23) \fI(public member function)\fP + operator Pointer* converts the out_ptr_t to the address of the storage for output + operator void** \fI(public member function)\fP + (C++23) + +.SH Non-member functions + + out_ptr creates an out_ptr_t with an associated smart pointer and resetting + (C++23) arguments + \fI(function template)\fP + +.SH Notes + + out_ptr_t expects that the foreign functions do not used the value of the pointed-to + Pointer, and only re-initialize it. The value of the smart pointer before adaption + is not used. + + The typical usage of out_ptr_t is creating its temporary objects by std::out_ptr, + which resets the adapted smart pointer immediately. E.g. given a setter function and + a smart pointer of appropriate type declared with int foreign_setter(T**); and + std::unique_ptr up; respectively, + + int foreign_setter(T**); + std::unique_ptr up; + + if (int ec = foreign_setter(std::out_ptr(up))) + return ec; + + is roughly equivalent to + + int foreign_setter(T**); + std::unique_ptr up; + T* raw_p{}; + + int ec = foreign_setter(&raw_p); + up.reset(raw_p); + if (ec != 0) + return ec; + + It is not recommended to create an out_ptr_t object of a storage duration other than + automatic storage duration, because such code is likely to produce dangling + references and result in undefined behavior on destruction. + + out_ptr_t forbids the usage that would reset a std::shared_ptr without specifying a + deleter, because it would call std::shared_ptr::reset and replace a custom deleter + later. + + Captured arguments are typically packed into a std::tuple. Implementations + may use different mechanism to provide the Pointer or void* object they need hold. + + Feature-test macro Value Std Feature + __cpp_lib_out_ptr 202106L (C++23) std::out_ptr, std::inout_ptr + 202311L (C++26) freestanding std::out_ptr and std::inout_ptr + +.SH Example + + This section is incomplete + Reason: no example + +.SH See also + + inout_ptr_t interoperates with foreign pointer setters, obtains the initial pointer + (C++23) value from a smart pointer, and resets it on destruction + \fI(class template)\fP + unique_ptr smart pointer with unique object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + shared_ptr smart pointer with shared object ownership semantics + \fI(C++11)\fP \fI(class template)\fP + +.SH Category: + * Todo no example diff --git a/man/std::out_ptr_t::operatorPointer*,.3 b/man/std::out_ptr_t::operatorPointer*,.3 new file mode 100644 index 000000000..251aecd79 --- /dev/null +++ b/man/std::out_ptr_t::operatorPointer*,.3 @@ -0,0 +1,61 @@ +.TH std::out_ptr_t::operatorPointer*, 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::out_ptr_t::operatorPointer*, \- std::out_ptr_t::operatorPointer*, + +.SH Synopsis + + operator Pointer*() const noexcept; \fB(1)\fP (since C++23) + operator void**() const noexcept; \fB(2)\fP (since C++23) + + Exposes the address of a Pointer or void* object to a foreign function which will + generally re-initialize it. + + 1) Converts *this to the address of stored Pointer object. + 2) Converts *this to the address of a void* object. This conversion function + participates in overload resolution only if Pointer is not same as void*, and the + program is ill-formed if Pointer is not a pointer type. + The initial value of the void* object is equal the value of the stored Pointer + object converted to void*, and any modification to it affects the Pointer value used + in the destructor. Accessing the void* object outside the lifetime of *this has + undefined behavior. + + Once one of these two conversion functions has been called on an out_ptr_t object, + the other shall not be called on it, otherwise, the behavior is undefined. + +.SH Parameters + + \fI(none)\fP + +.SH Return value + + 1) The address of stored Pointer object. + 2) The address of the void* object that satisfies aforementioned requirements. + +.SH Notes + + If the object pointed by the return value has not been rewritten, it is equal to + nullptr. + + On common implementations, the object representation of every Pointer that is a + pointer type is compatible with that of void*, and therefore these implementations + typically store the void* object within the storage for the Pointer object, no + additional storage needed: + + * If the implementation enables type-based alias analysis (which relies on the + strict aliasing rule), a properly aligned std::byte[sizeof(void*)] member + subobject may be used, and both conversion functions return the address of + objects implicitly created within the array. + * Otherwise, a Pointer member subobject may be used for both conversion functions, + and \fB(2)\fP may directly returns its address reinterpret_cast to void**. + + If Pointer is a pointer type whose object representation is incompatible with that + of void*, an additional bool flag may be needed for recording whether \fB(1)\fP (or \fB(2)\fP) + has been called. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::out_ptr_t::out_ptr_t.3 b/man/std::out_ptr_t::out_ptr_t.3 new file mode 100644 index 000000000..2e3cfb1ef --- /dev/null +++ b/man/std::out_ptr_t::out_ptr_t.3 @@ -0,0 +1,49 @@ +.TH std::out_ptr_t::out_ptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::out_ptr_t::out_ptr_t \- std::out_ptr_t::out_ptr_t + +.SH Synopsis + explicit out_ptr_t( Smart &sp, Args... args ); \fB(1)\fP (since C++23) + out_ptr_t( const out_ptr_t& ) = delete; \fB(2)\fP (since C++23) + + 1) Creates an out_ptr_t. Adapts sp as if binds it to the Smart& member, captures + every argument t in args... as if initializes the corresponding member of type T in + Args... with std::forward(t), then value-initializes the stored Pointer. + Then calls sp.reset() if the expression is well-formed; otherwise, calls sp = + Smart() if std::is_default_constructible_v is true. The program is ill-formed + if both resetting operations are ill-formed. + 2) Copy constructor is explicitly deleted. out_ptr_t is neither copyable nor + movable. + +.SH Parameters + + sp - the object (typically a smart pointer) to adapt + args... - the arguments used for resetting to capture + +.SH Return value + + \fI(none)\fP + +.SH Exceptions + + May throw implementation-defined exceptions. + +.SH Notes + + After construction, the Pointer or void* object pointed by the return value of + either conversion function is equal to nullptr. + + Every argument in args... is moved into the created out_ptr_t if it is of an object + type, or transferred into the created out_ptr_t as-is if it is of a reference type. + + The constructor of out_ptr_t is allowed to throw exceptions. For example, when sp is + a std::shared_ptr, the allocation for the new control block may be performed within + the constructor rather than the destructor. + +.SH Example + + This section is incomplete + Reason: no example + +.SH Category: + * Todo no example diff --git a/man/std::out_ptr_t::~out_ptr_t.3 b/man/std::out_ptr_t::~out_ptr_t.3 new file mode 100644 index 000000000..2b35518f2 --- /dev/null +++ b/man/std::out_ptr_t::~out_ptr_t.3 @@ -0,0 +1,44 @@ +.TH std::out_ptr_t::~out_ptr_t 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::out_ptr_t::~out_ptr_t \- std::out_ptr_t::~out_ptr_t + +.SH Synopsis + ~out_ptr_t(); (since C++23) + + Resets the adapted Smart object by the value of modified Pointer object (or the + void* object if operator void**() has been called) and the captured arguments. + + Let + + * s denotes the adapted Smart object, + * args... denotes the captured arguments, + * p denotes the value of stored Pointer, or static_cast(*operator + void**()) if operator void** has been called, + * SP be + * Smart::pointer, if it is valid and denotes a type, otherwise, + * Smart::element_type*, if Smart::element_type is valid and denotes a type, + otherwise, + * std::pointer_traits::element_type*, if + std::pointer_traits::element_type is valid and denotes a type, + otherwise, + * Pointer. + + If s.reset(static_cast(p), std::forward(args)...) is well-formed, the + destructor performs + + if (p) s.reset(static_cast(p), std::forward(args)...);, + + otherwise, if std::is_constructible_v is true, the destructor + performs + + if (p) s = Smart(static_cast(p), std::forward(args)...);, + + otherwise, the program is ill-formed. + +.SH Notes + + If Smart is a std::shared_ptr specialization, the implementation may allocate the + storage for the new control block on construction, in order to leave non-throwing + works to the destructor. + + Arguments captured by value are destroyed after resetting. diff --git a/man/std::output_iterator.3 b/man/std::output_iterator.3 new file mode 100644 index 000000000..815c4d68f --- /dev/null +++ b/man/std::output_iterator.3 @@ -0,0 +1,33 @@ +.TH std::output_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::output_iterator \- std::output_iterator + +.SH Synopsis + Defined in header + template< class I, class T > + + concept output_iterator = + std::input_or_output_iterator && + std::indirectly_writable && \fI(since C++20)\fP + requires(I i, T&& t) { + *i++ = std::forward(t); /* not required to be + equality-preserving */ + + }; + + The output_iterator concept is a refinement of input_or_output_iterator, adding the + requirement that it can be used to write values of type and value category encoded + by T (via indirectly_writable). equality_comparable is not required. + +.SH Notes + + Unlike the LegacyOutputIterator requirements, the output_iterator concept does not + require that the iterator category tag be defined. + + Algorithms on output iterators should be single pass. + +.SH See also + + input_or_output_iterator specifies that objects of a type can be incremented and + (C++20) dereferenced + (concept) diff --git a/man/std::overflow_error.3 b/man/std::overflow_error.3 index d63f2f106..1ddcc9f16 100644 --- a/man/std::overflow_error.3 +++ b/man/std::overflow_error.3 @@ -1,46 +1,204 @@ -.TH std::overflow_error 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::overflow_error 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::overflow_error \- std::overflow_error + .SH Synopsis Defined in header class overflow_error; - Defines a type of object to be thrown as exception. It reports errors that arise - because integer value in some computation could not be represented as it had too - large positive value. If the value has floating point type, std::range_error should - be used. + Defines a type of object to be thrown as exception. It can be used to report + arithmetic overflow errors (that is, situations where a result of a computation is + too large for the destination type). + + The only standard library component that throws this exception is \fI(until C++11)\fP + std::bitset::to_ulong. + The only standard library components that throw this exception are \fI(since C++11)\fP + std::bitset::to_ulong and std::bitset::to_ullong. + + The mathematical functions of the standard library components do not throw this + exception (mathematical functions report overflow errors as specified in + math_errhandling). Third-party libraries, however, use this. For example, boost.math + throws std::overflow_error if boost::math::policies::throw_on_error is enabled (the + default setting). std-overflow error-inheritance.svg - About this image Inheritance diagram .SH Member functions - constructor constructs the exception object - \fI(public member function)\fP + constructor constructs a new overflow_error object with the given message + \fI(public member function)\fP + operator= replaces the overflow_error object + \fI(public member function)\fP - +std::overflow_error::overflow_error - std::overflow_error::overflow_error + overflow_error( const std::string& what_arg ); \fB(1)\fP + overflow_error( const char* what_arg ); \fB(2)\fP + overflow_error( const overflow_error& other ); \fB(3)\fP (noexcept since C++11) - explicit overflow_error( const std::string& what_arg ); \fB(1)\fP - explicit overflow_error( const char* what_arg ); \fB(2)\fP \fI(since C++11)\fP - - Constructs the exception object with what_arg as explanatory string that can be - accessed through what(). + 1) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg.c_str()) == 0. + 2) Constructs the exception object with what_arg as explanatory string. After + construction, std::strcmp(what(), what_arg) == 0. + 3) Copy constructor. If *this and other both have dynamic type std::overflow_error + then std::strcmp(what(), other.what()) == 0. No exception can be thrown from the + copy constructor. .SH Parameters what_arg - explanatory string + other - another exception object to copy .SH Exceptions - \fI(none)\fP + 1,2) May throw std::bad_alloc. + +.SH Notes + + Because copying std::overflow_error is not permitted to throw exceptions, this + message is typically stored internally as a separately-allocated reference-counted + string. This is also why there is no constructor taking std::string&&: it would have + to copy the content anyway. + + Before the resolution of LWG issue 254, the non-copy constructor can only accept + std::string. It makes dynamic allocation mandatory in order to construct a + std::string object. + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy constructor. It can be implicitly defined as long as the + explanatory strings obtained by what() are the same for the original object and the + copied object. + +std::overflow_error::operator= + + overflow_error& operator=( const overflow_error& other ); (noexcept since C++11) + + Assigns the contents with those of other. If *this and other both have dynamic type + std::overflow_error then std::strcmp(what(), other.what()) == 0 after assignment. No + exception can be thrown from the copy assignment operator. + +.SH Parameters + + other - another exception object to assign with + +.SH Return value + + *this + +.SH Notes + + After the resolution of LWG issue 471, a derived standard exception class must have + a publicly accessible copy assignment operator. It can be implicitly defined as long + as the explanatory strings obtained by what() are the same for the original object + and the copied object. + +Inherited from std::runtime_error Inherited from std::exception .SH Member functions - destructor destructs the exception object - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + destructor destroys the exception object + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP what returns an explanatory string - \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + \fB[virtual]\fP \fI(virtual public member function of std::exception)\fP + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + template + requires (N > 0) /*...*/ + class Stack + { + int top_{-1}; + T data_[N]; + + public: + [[nodiscard]] bool empty() const { return top_ == -1; } + + void push(T x) + { + if (top_ == N - 1) + throw std::overflow_error("Stack overflow!"); + data_[++top_] = std::move(x); + } + + void pop() + { + if (empty()) + throw std::underflow_error("Stack underflow!"); + --top_; + } + + T const& top() const + { + if (empty()) + throw std::overflow_error("Stack is empty!"); + return data_[top_]; + } + }; + + int main() + { + Stack st; + + try + { + [[maybe_unused]] auto x = st.top(); + } + catch (std::overflow_error const& ex) + { + std::cout << "1) Exception: " << ex.what() << '\\n'; + } + + st.push(1337); + while (!st.empty()) + st.pop(); + + try + { + st.pop(); + } + catch (std::underflow_error const& ex) + { + std::cout << "2) Exception: " << ex.what() << '\\n'; + } + + try + { + for (int i{}; i != 13; ++i) + st.push(i); + } + catch (std::overflow_error const& ex) + { + std::cout << "3) Exception: " << ex.what() << '\\n'; + } + } + +.SH Output: + + 1) Exception: Stack is empty! + 2) Exception: Stack underflow! + 3) Exception: Stack overflow! + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 254 C++98 the constructor accepting const added + char* was missing + the explanatory strings of they are the same as that of + LWG 471 C++98 std::overflow_error's the + copies were implementation-defined original std::overflow_error + object diff --git a/man/std::owner_equal.3 b/man/std::owner_equal.3 new file mode 100644 index 000000000..4e038fa06 --- /dev/null +++ b/man/std::owner_equal.3 @@ -0,0 +1,82 @@ +.TH std::owner_equal 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::owner_equal \- std::owner_equal + +.SH Synopsis + Defined in header + struct owner_equal; (since C++26) + + This function object provides owner-based (as opposed to value-based) mixed-type + equal comparison of both std::weak_ptr and std::shared_ptr. The comparison is such + that two smart pointers compare equivalent only if they are both empty or if they + share ownership, even if the values of the raw pointers obtained by get() are + different (e.g. because they point at different subobjects within the same object). + + 1) Owner-based mixed-type equal comparison is not provided for types other than + std::shared_ptr and std::weak_ptr. + 2) The owner-based mixed-type equal comparison of std::shared_ptr and std::weak_ptr. + It is the preferred comparison predicate when building unordered associative + containers with std::shared_ptr and std::weak_ptr as keys together with + std::owner_hash, that is, std::unordered_map, U, std::owner_hash, + std::owner_equal> or std::unordered_map, U, std::owner_hash, + std::owner_equal>. + 3) std::owner_equal deduces the parameter types from the arguments. + +.SH Member functions + + operator() compares its arguments using owner-based semantics + \fI(function)\fP + +std::owner_equal::operator() + + template< class T, class U > + + bool operator()( const std::shared_ptr& lhs, (since C++26) + + const std::shared_ptr& rhs ) const noexcept; + template< class T, class U > + + bool operator()( const std::shared_ptr& lhs, (since C++26) + + const std::weak_ptr& rhs ) const noexcept; + template< class T, class U > + + bool operator()( const std::weak_ptr& lhs, (since C++26) + + const std::shared_ptr& rhs ) const noexcept; + template< class T, class U > + + bool operator()( const std::weak_ptr& lhs, (since C++26) + + const std::weak_ptr& rhs ) const noexcept; + + Compares lhs and rhs using owner-based semantics. Effectively calls + lhs.owner_equal(rhs). + + The equal comparison is an equivalence relation. + + lhs and rhs are equivalent only if they are both empty or share ownership. + +.SH Parameters + + lhs, rhs - shared-ownership pointers to compare + +.SH Return value + + true if lhs and rhs are both empty or share ownership as determined by the + owner-based equal comparison, false otherwise. + +.SH Notes + + Feature-test macro Value Std Feature + Enabling the use of + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) std::shared_ptr and std::weak_ptr + as keys in unordered associative + containers + +.SH See also + + owner_equal provides owner-based equal comparison of shared pointers + (C++26) \fI(public member function of std::shared_ptr)\fP + owner_equal provides owner-based equal comparison of weak pointers + (C++26) \fI(public member function of std::weak_ptr)\fP diff --git a/man/std::owner_hash.3 b/man/std::owner_hash.3 new file mode 100644 index 000000000..47c67996b --- /dev/null +++ b/man/std::owner_hash.3 @@ -0,0 +1,50 @@ +.TH std::owner_hash 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::owner_hash \- std::owner_hash + +.SH Synopsis + Defined in header + struct owner_hash; (since C++26) + + This function object provides owner-based (as opposed to value-based) hashing of + both std::weak_ptr and std::shared_ptr. + +.SH Member functions + + operator() calculates the hash of the shared-ownership pointer + \fI(function)\fP + +std::owner_hash::operator() + + template< class T > + std::size_t operator()( const std::shared_ptr& key ) const \fB(1)\fP (since C++26) + noexcept; + template< class T > + std::size_t operator()( const std::weak_ptr& key ) const \fB(2)\fP (since C++26) + noexcept; + + Equivalent to return key.owner_hash();. + +.SH Parameters + + key - shared-ownership pointer to be hashed + +.SH Return value + + A hash value that is identical for any std::shared_ptr or std::weak_ptr object + sharing the same ownership. + +.SH Notes + + Feature-test macro Value Std Feature + Enabling the use of + __cpp_lib_smart_ptr_owner_equality 202306L (C++26) std::shared_ptr and std::weak_ptr + as keys in unordered associative + containers + +.SH See also + + owner_hash provides owner-based hashing of shared pointers + (C++26) \fI(public member function of std::shared_ptr)\fP + owner_hash provides owner-based hashing of weak pointers + (C++26) \fI(public member function of std::weak_ptr)\fP diff --git a/man/std::owner_less.3 b/man/std::owner_less.3 index 401202ff9..d288c563c 100644 --- a/man/std::owner_less.3 +++ b/man/std::owner_less.3 @@ -1,65 +1,42 @@ -.TH std::owner_less 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::owner_less 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::owner_less \- std::owner_less + .SH Synopsis Defined in header - template< class T > \fB(1)\fP \fI(since C++11)\fP - struct owner_less; /* undefined */ - template< class T > \fB(2)\fP \fI(since C++11)\fP - struct owner_less>; - template< class T > \fB(3)\fP \fI(since C++11)\fP - struct owner_less>; + template<> \fI(since C++17)\fP + struct owner_less; - This function object provides owner-based (as opposed to value-based) mixed-type - ordering of both std::weak_ptr and std::shared_ptr. The order is such that two smart - pointers compare equivalent only if they are both empty or if they both manage the - same object, even if the values of the raw pointers obtained by get() are different - (e.g. because they point at different subobjects within the same object) + std::owner_less is a specialization of std::owner_less with parameter types + deduced. - This class template is the preferred comparison predicate when building associative - containers with std::shared_ptr or std::weak_ptr as keys, that is, +.SH Member functions - std::map, U, std::owner_less>> + operator() compares its arguments using owner-based semantics + \fI(function)\fP - or +std::owner_less::operator() - std::map, U, std::owner_less>>. + template< class T, class U > - The default operator< is not defined for weak pointers, and may wrongly consider two - shared pointers for the same object non-equivalent (see shared_ptr::owner_before) + bool operator()( const std::shared_ptr& lhs, \fI(since C++17)\fP -.SH Member types + const std::shared_ptr& rhs ) const noexcept; + template< class T, class U > - Member type Definition - result_type bool - 1) T - first_argument_type 2) std::shared_ptr - 3) std::weak_ptr - 1) T - second_argument_type 2) std::shared_ptr - 3) std::weak_ptr + bool operator()( const std::shared_ptr& lhs, \fI(since C++17)\fP -.SH Member functions + const std::weak_ptr& rhs ) const noexcept; + template< class T, class U > - operator() compares its arguments using owner-based semantics - \fI(function)\fP + bool operator()( const std::weak_ptr& lhs, \fI(since C++17)\fP + + const std::shared_ptr& rhs ) const noexcept; + template< class T, class U > + + bool operator()( const std::weak_ptr& lhs, \fI(since C++17)\fP - std::owner_less::operator() - - bool operator()( const std::shared_ptr& \fI(since C++11)\fP - lhs, (member only of shared_ptr template - const std::shared_ptr& specialization) - rhs ) const; - bool operator()( const std::shared_ptr& - lhs, \fI(since C++11)\fP - const std::weak_ptr& rhs - ) const; - bool operator()( const std::weak_ptr& - lhs, \fI(since C++11)\fP - const std::shared_ptr& - rhs ) const; - bool operator()( const std::weak_ptr& \fI(since C++11)\fP - lhs, (member only of weak_ptr template - const std::weak_ptr& rhs specialization) - ) const; + const std::weak_ptr& rhs ) const noexcept; Compares lhs and rhs using owner-based semantics. Effectively calls lhs.owner_before(rhs). @@ -76,11 +53,15 @@ true if lhs is less than rhs as determined by the owner-based ordering. -.SH Exceptions +.SH Notes - \fI(none)\fP + Feature-test macro Value Std Feature + __cpp_lib_transparent_operators 201510L \fI(C++17)\fP Transparent std::owner_less + (std::owner_less) .SH See also owner_before provides owner-based ordering of shared pointers - \fI(public member function of std::shared_ptr)\fP + \fI(public member function of std::shared_ptr)\fP + owner_before provides owner-based ordering of weak pointers + \fI(public member function of std::weak_ptr)\fP diff --git a/man/std::packaged_task.3 b/man/std::packaged_task.3 index feb1b6d80..159dedd9c 100644 --- a/man/std::packaged_task.3 +++ b/man/std::packaged_task.3 @@ -1,102 +1,108 @@ -.TH std::packaged_task 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task \- std::packaged_task + .SH Synopsis Defined in header template< class > class packaged_task; //not defined \fB(1)\fP \fI(since C++11)\fP - template< class R, class ...Args > \fB(2)\fP \fI(since C++11)\fP - class packaged_task; + template< class R, class ...ArgTypes > \fB(2)\fP \fI(since C++11)\fP + class packaged_task; The class template std::packaged_task wraps any Callable target \fI\fI(function\fP, lambda\fP expression, bind expression, or another function object) so that it can be invoked asynchronously. Its return value or exception thrown is stored in a shared state which can be accessed through std::future objects. - Just like std::function, std::packaged_task is a polymorphic, allocator-aware - container: the stored callable target may be allocated on heap or with a provided - allocator. + Just like std::function, std::packaged_task is a polymorphic, + allocator-aware container: the stored callable target may be allocated \fI(until C++17)\fP + on heap or with a provided allocator. .SH Member functions constructor constructs the task object - \fI(public member function)\fP + \fI(public member function)\fP destructor destructs the task object - \fI(public member function)\fP + \fI(public member function)\fP operator= moves the task object - \fI(public member function)\fP + \fI(public member function)\fP valid checks if the task object has a valid function - \fI(public member function)\fP + \fI(public member function)\fP swap swaps two task objects - \fI(public member function)\fP + \fI(public member function)\fP .SH Getting the result get_future returns a std::future associated with the promised result - \fI(public member function)\fP + \fI(public member function)\fP .SH Execution operator() executes the function - \fI(public member function)\fP + \fI(public member function)\fP executes the function ensuring that the result is ready make_ready_at_thread_exit only once the current thread exits - \fI(public member function)\fP + \fI(public member function)\fP resets the state abandoning any stored results of previous reset executions - \fI(public member function)\fP + \fI(public member function)\fP .SH Non-member functions std::swap(std::packaged_task) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes std::uses_allocator specializes the std::uses_allocator type - \fI(C++11)\fP trait - \fI(class template specialization)\fP + \fI(C++11)\fP \fI(until C++17)\fP trait + \fI(class template specialization)\fP + + Deduction guides\fI(since C++17)\fP .SH Example - + // Run this code - #include #include - #include - #include #include - + #include + #include + #include + // unique function to avoid disambiguating the std::pow overload set - int f(int x, int y) { return std::pow(x,y); } - + int f(int x, int y) { return std::pow(x, y); } + void task_lambda() { - std::packaged_task task([](int a, int b) { + std::packaged_task task([](int a, int b) + { return std::pow(a, b); }); std::future result = task.get_future(); - + task(2, 9); - + std::cout << "task_lambda:\\t" << result.get() << '\\n'; } - + void task_bind() { std::packaged_task task(std::bind(f, 2, 11)); std::future result = task.get_future(); - + task(); - + std::cout << "task_bind:\\t" << result.get() << '\\n'; } - + void task_thread() { - std::packaged_task task(f); + std::packaged_task task(f); std::future result = task.get_future(); - + std::thread task_td(std::move(task), 2, 10); task_td.join(); - + std::cout << "task_thread:\\t" << result.get() << '\\n'; } - + int main() { task_lambda(); @@ -110,7 +116,15 @@ task_bind: 2048 task_thread: 1024 + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 3117 C++17 deduction guides for packaged_task were missing added + .SH See also future waits for a value that is set asynchronously - \fI(C++11)\fP \fI(class template)\fP + \fI(C++11)\fP \fI(class template)\fP diff --git a/man/std::packaged_task::get_future.3 b/man/std::packaged_task::get_future.3 index 46bac262e..151d70ba2 100644 --- a/man/std::packaged_task::get_future.3 +++ b/man/std::packaged_task::get_future.3 @@ -1,4 +1,7 @@ -.TH std::packaged_task::get_future 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::get_future 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::get_future \- std::packaged_task::get_future + .SH Synopsis std::future get_future(); \fI(since C++11)\fP diff --git a/man/std::packaged_task::make_ready_at_thread_exit.3 b/man/std::packaged_task::make_ready_at_thread_exit.3 index d4d5cec0f..506540bb7 100644 --- a/man/std::packaged_task::make_ready_at_thread_exit.3 +++ b/man/std::packaged_task::make_ready_at_thread_exit.3 @@ -1,11 +1,16 @@ -.TH std::packaged_task::make_ready_at_thread_exit 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::make_ready_at_thread_exit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::make_ready_at_thread_exit \- std::packaged_task::make_ready_at_thread_exit + .SH Synopsis void make_ready_at_thread_exit( ArgTypes... args ); \fI(since C++11)\fP - Calls the stored task with args as the arguments. The return value of the task or - any exceptions thrown are stored in the shared state. The shared state is not made - ready until the current thread exits and all objects of thread local storage - duration are destroyed. After and any threads waiting for this are unblocked. + Calls the stored task as if by INVOKE(f, args...), where f is the stored task. + The return value of the task or any exception thrown by it is stored in the shared + state of *this. + + The shared state is only made ready after the current thread exits and all objects + of thread-local storage duration are destroyed. .SH Parameters @@ -25,14 +30,52 @@ .SH Example - This section is incomplete - Reason: no example -.SH See also +// Run this code - operator() executes the function - \fI(public member function)\fP + #include + #include + #include + #include + #include + #include + + void worker(std::future& output) + { + std::packaged_task my_task{[](bool& done) { done = true; }}; + auto result = my_task.get_future(); + + bool done = false; + my_task.make_ready_at_thread_exit(done); // execute task right away + + std::cout << "worker: done = " << std::boolalpha << done << std::endl; + + auto status = result.wait_for(std::chrono::seconds(0)); + if (status == std::future_status::timeout) + std::cout << "worker: result is not ready yet" << std::endl; + + output = std::move(result); + } -.SH Category: - * Todo no example + int main() + { + std::future result; + + std::thread{worker, std::ref(result)}.join(); + + auto status = result.wait_for(std::chrono::seconds(0)); + if (status == std::future_status::ready) + std::cout << "main: result is ready" << std::endl; + } + +.SH Output: + + worker: done = true + worker: result is not ready yet + main: result is ready + +.SH See also + + operator() executes the function + \fI(public member function)\fP diff --git a/man/std::packaged_task::operator().3 b/man/std::packaged_task::operator().3 index e916960f0..23957f883 100644 --- a/man/std::packaged_task::operator().3 +++ b/man/std::packaged_task::operator().3 @@ -1,10 +1,14 @@ -.TH std::packaged_task::operator() 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::operator() 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::operator() \- std::packaged_task::operator() + .SH Synopsis void operator()( ArgTypes... args ); \fI(since C++11)\fP - Calls the stored task with args as the arguments. The return value of the task or - any exceptions thrown are stored in the shared state. The shared state is made ready - and any threads waiting for this are unblocked. + Calls the stored task as if by INVOKE(f, args...), where f is the stored task. + The return value of the task or any exceptions thrown are stored in the shared + state. The shared state is made ready and any threads waiting for this are + unblocked. .SH Parameters @@ -22,22 +26,29 @@ promise_already_satisfied. * *this has no shared state. The error category is set to no_state. -.SH Notes - - A successful call to operator() synchronizes with a call to any member function of a - std::future or std::shared_future that share their shared state with *this. - .SH Example This section is incomplete Reason: no example + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + a successful call to operator() no additional + synchronized with synchronization + LWG 2142 C++11 a call to any member function of a guarantees other than what + std::future or is + std::shared_future that share their already provided by shared + shared state with *this state + .SH See also executes the function ensuring that the result is ready make_ready_at_thread_exit only once the current thread exits - \fI(public member function)\fP + \fI(public member function)\fP .SH Category: - * Todo no example diff --git a/man/std::packaged_task::operator=.3 b/man/std::packaged_task::operator=.3 index 2d2bb2f2c..5e5bd6248 100644 --- a/man/std::packaged_task::operator=.3 +++ b/man/std::packaged_task::operator=.3 @@ -1,10 +1,12 @@ -.TH std::packaged_task::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::operator= \- std::packaged_task::operator= + .SH Synopsis packaged_task& operator=( const packaged_task& ) = delete; \fB(1)\fP \fI(since C++11)\fP - packaged_task& operator=( packaged_task&& rhs ) \fB(2)\fP \fI(since C++11)\fP + packaged_task& operator=( packaged_task&& rhs ) noexcept; \fB(2)\fP \fI(since C++11)\fP - 1) Copy assignment operator is deleted, std::packaged_task is move-only. Note: C++11 - does not specify const here, this is the defect 2067. + 1) Copy assignment operator is deleted, std::packaged_task is move-only. 2) Releases the shared state, if any, destroys the previously-held task, and moves the shared state and the task owned by rhs into *this. rhs is left without a shared state and with a moved-from task. @@ -13,19 +15,19 @@ rhs - the std::packaged_task to move from -.SH Exceptions - - 1) \fI(none)\fP - 2) - noexcept specification: - noexcept - - .SH Example This section is incomplete Reason: no example -.SH Category: + Defect reports + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2067 C++11 the parameter type of the copy assignment added const + operator was packaged_task& + +.SH Category: * Todo no example diff --git a/man/std::packaged_task::packaged_task.3 b/man/std::packaged_task::packaged_task.3 index a79f4be6e..4e97c57ca 100644 --- a/man/std::packaged_task::packaged_task.3 +++ b/man/std::packaged_task::packaged_task.3 @@ -1,86 +1,99 @@ -.TH std::packaged_task::packaged_task 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::packaged_task 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::packaged_task \- std::packaged_task::packaged_task + .SH Synopsis - packaged_task() \fB(1)\fP \fI(since C++11)\fP - template \fB(2)\fP \fI(since C++11)\fP - explicit packaged_task( F&& f ) - template - explicit packaged_task( std::allocator_arg_t, const Allocator& a, \fB(3)\fP \fI(since C++11)\fP - F&& f ) - packaged_task( packaged_task& ) = delete \fB(4)\fP \fI(since C++11)\fP - \fI(until C++14)\fP - packaged_task( const packaged_task& ) = delete \fB(4)\fP \fI(since C++14)\fP - packaged_task( packaged_task&& rhs ) \fB(5)\fP \fI(since C++11)\fP + packaged_task() noexcept; \fB(1)\fP \fI(since C++11)\fP + template< class F > \fB(2)\fP \fI(since C++11)\fP + explicit packaged_task( F&& f ); + template< class F, class Allocator > \fI(since C++11)\fP + explicit packaged_task( std::allocator_arg_t, const Allocator& a, \fB(3)\fP \fI(until C++17)\fP + F&& f ); + packaged_task( const packaged_task& ) = delete; \fB(4)\fP \fI(since C++11)\fP + packaged_task( packaged_task&& rhs ) noexcept; \fB(5)\fP \fI(since C++11)\fP Constructs a new std::packaged_task object. 1) Constructs a std::packaged_task object with no task and no shared state. - 2) Constructs a std::packaged_task object with a shared state and a copy of the - task, initialized with std::forward(f). This constructor does not participate in - overload resolution if std::decay::type is the same type as - std::packaged_task. - 3) Constructs a std::packaged_task object with a shared state and a copy of the - task, initialized with std::forward(f). Uses the provided allocator to allocate - memory necessary to store the task. This constructor does not participate in - overload resolution if std::decay::type is the same type as - std::packaged_task. + 2,3) Constructs a std::packaged_task object with a shared state and a copy of the + task, initialized with std::forward(f). + The allocator a is used to allocate memory necessary to store the task. + \fI(until C++17)\fP + These overloads participate in overload resolution only if std::decay::type is + not the same type as std::packaged_task. + + Let t1, t2, ..., tN be values of the corresponding types in Args, if + INVOKE(f, t1, t2, ..., tN) is not a valid expression, the program \fI(until C++17)\fP + is ill-formed. + If std::is_invocable_r_v is false, the program is \fI(since C++17)\fP + ill-formed. + + If invoking f itself and invoking a copy of f behave differently, the behavior is + undefined. 4) The copy constructor is deleted, std::packaged_task is move-only. 5) Constructs a std::packaged_task with the shared state and task formerly owned by rhs, leaving rhs with no shared state and a moved-from task. .SH Parameters - f - the callable target \fI(function, member function, lambda-expression, functor) to\fP - execute + f - the callable target \fI\fI(function\fP, member function, lambda expression, function\fP + object) to execute a - the allocator to use when storing the task rhs - the std::packaged_task to move from .SH Exceptions - 1) - noexcept specification: - noexcept - - 2-3) Any exceptions thrown by copy/move constructor of f and possiblly - std::bad_alloc if the allocation fails. - 4) \fI(none)\fP - 5) - noexcept specification: - noexcept - + 2) Any exceptions thrown by copy/move constructor of f and possibly std::bad_alloc + if the allocation fails. + 3) Any exceptions thrown by copy/move constructor of f and by the allocator's + allocate function if memory allocation fails. .SH Example - + // Run this code #include #include #include - + int fib(int n) { - if (n < 3) return 1; - else return fib(n-1) + fib(n-2); + if (n < 3) + return 1; + else + return fib(n - 1) + fib(n - 2); } - + int main() { std::packaged_task fib_task(&fib); - - std::cout << "starting task\\n"; + + std::cout << "Starting task\\n"; auto result = fib_task.get_future(); - std::thread t(std::move(fib_task), 40); - - std::cout << "waiting for task to finish...\\n"; + std::thread t(std::move(fib_task), 42); + + std::cout << "Waiting for task to finish..." << std::endl; std::cout << result.get() << '\\n'; - - std::cout << "task complete\\n"; + + std::cout << "Task complete\\n"; t.join(); } .SH Output: - starting task - waiting for task to finish... - 102334155 - task complete + Starting task + Waiting for task to finish... + 267914296 + Task complete + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2067 C++11 the parameter type of the copy constructor was added const + packaged_task& + LWG 2097 C++11 for overloads (2,3), F could be F is constrained + std::packaged_task diff --git a/man/std::packaged_task::reset.3 b/man/std::packaged_task::reset.3 index b539be887..a06e98515 100644 --- a/man/std::packaged_task::reset.3 +++ b/man/std::packaged_task::reset.3 @@ -1,4 +1,7 @@ -.TH std::packaged_task::reset 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::reset 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::reset \- std::packaged_task::reset + .SH Synopsis void reset(); \fI(since C++11)\fP @@ -20,4 +23,36 @@ * std::future_error if *this has no shared state. The error condition is set to no_state. * std::bad_alloc if there was not enough memory for a new shared state. - * any exception thrown by the move constructor of the new packaged_task + * Any exception thrown by the move constructor of the new packaged_task. + +.SH Example + + +// Run this code + + #include + #include + #include + #include + + int main() + { + std::packaged_task task([](int a, int b) + { + return std::pow(a, b); + }); + std::future result = task.get_future(); + task(2, 9); + std::cout << "2^9 = " << result.get() << '\\n'; + + task.reset(); + result = task.get_future(); + std::thread task_td(std::move(task), 2, 10); + task_td.join(); + std::cout << "2^10 = " << result.get() << '\\n'; + } + +.SH Output: + + 2^9 = 512 + 2^10 = 1024 diff --git a/man/std::packaged_task::swap.3 b/man/std::packaged_task::swap.3 index 0c481cf56..132606c8b 100644 --- a/man/std::packaged_task::swap.3 +++ b/man/std::packaged_task::swap.3 @@ -1,6 +1,9 @@ -.TH std::packaged_task::swap 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::swap \- std::packaged_task::swap + .SH Synopsis - void swap( packaged_task& other ); \fI(since C++11)\fP + void swap( packaged_task& other ) noexcept; \fI(since C++11)\fP Exchanges the shared states and stored tasks of *this and other. @@ -12,13 +15,7 @@ \fI(none)\fP -.SH Exceptions - - noexcept specification: - noexcept - - .SH See also std::swap(std::packaged_task) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP diff --git a/man/std::packaged_task::valid.3 b/man/std::packaged_task::valid.3 index 07073c0cf..a86025818 100644 --- a/man/std::packaged_task::valid.3 +++ b/man/std::packaged_task::valid.3 @@ -1,6 +1,9 @@ -.TH std::packaged_task::valid 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::valid 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::valid \- std::packaged_task::valid + .SH Synopsis - bool valid() const; \fI(since C++11)\fP + bool valid() const noexcept; \fI(since C++11)\fP Checks whether *this has a shared state. @@ -11,9 +14,3 @@ .SH Return value true if *this has a shared state, false otherwise. - -.SH Exceptions - - noexcept specification: - noexcept - diff --git a/man/std::packaged_task::~packaged_task.3 b/man/std::packaged_task::~packaged_task.3 index cb113fa9d..ac7e5aa65 100644 --- a/man/std::packaged_task::~packaged_task.3 +++ b/man/std::packaged_task::~packaged_task.3 @@ -1,6 +1,9 @@ -.TH std::packaged_task::~packaged_task 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::packaged_task::~packaged_task 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::packaged_task::~packaged_task \- std::packaged_task::~packaged_task + .SH Synopsis - ~packaged_task() + ~packaged_task(); Abandons the shared state and destroys the stored task object. @@ -18,5 +21,4 @@ Reason: no example .SH Category: - * Todo no example diff --git a/man/std::pair.3 b/man/std::pair.3 index 814b23e4c..b9d17fa53 100644 --- a/man/std::pair.3 +++ b/man/std::pair.3 @@ -1,4 +1,7 @@ -.TH std::pair 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pair 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pair \- std::pair + .SH Synopsis Defined in header template< @@ -8,9 +11,11 @@ > struct pair; - std::pair is a struct template that provides a way to store two heterogeneous - objects as a single unit. A pair is a specific case of a std::tuple with two - elements. + std::pair is a class template that provides a way to store two heterogeneous objects + as a single unit. A pair is a specific case of a std::tuple with two elements. + + If neither T1 nor T2 is a possibly cv-qualified class type with non-trivial + destructor, or array thereof, the destructor of pair is trivial. .SH Template parameters @@ -40,27 +45,55 @@ .SH Non-member functions make_pair creates a pair object of type, defined by the argument types - \fI(function template)\fP + \fI(function template)\fP operator== operator!= - operator< lexicographically compares the values in the pair - operator<= \fI(function template)\fP + operator< + operator<= operator> - operator>= + operator>= lexicographically compares the values in the pair + operator<=> \fI(function template)\fP + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (removed in C++20) + (C++20) std::swap(std::pair) specializes the std::swap algorithm - \fI(C++11)\fP \fI(function template)\fP - std::get(std::pair) accesses an element of a pair - \fI(C++11)\fP \fI(function template)\fP + \fI(C++11)\fP \fI(function template)\fP + get(std::pair) accesses an element of a pair + \fI(C++11)\fP \fI(function template)\fP .SH Helper classes - std::tuple_size obtains the size of a pair - \fI(C++11)\fP \fI(class template specialization)\fP - std::tuple_element obtains the type of the elements of pair - \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_size obtains the size of a pair + \fI(C++11)\fP \fI(class template specialization)\fP + std::tuple_element obtains the type of the elements of pair + \fI(C++11)\fP \fI(class template specialization)\fP + std::basic_common_reference determines the common reference type of two + (C++23) pairs + \fI(class template specialization)\fP + std::common_type determines the common type of two pairs + (C++23) \fI(class template specialization)\fP + std::formatter formatting support for pair + (C++23) \fI(class template specialization)\fP + + Deduction guides\fI(since C++17)\fP + + Defect reports + + The following behavior-changing defect reports were applied retroactively to + previously published C++ standards. + + DR Applied to Behavior as published Correct behavior + LWG 2796 C++98 triviality of the destructor of pair was specified + unspecified .SH See also tuple implements fixed size container, which holds elements of possibly different \fI(C++11)\fP types - \fI(class template)\fP + \fI(class template)\fP + tie creates a tuple of lvalue references or unpacks a tuple into individual + \fI(C++11)\fP objects + \fI(function template)\fP diff --git a/man/std::pair::operator=.3 b/man/std::pair::operator=.3 index ab7137643..55b477e95 100644 --- a/man/std::pair::operator=.3 +++ b/man/std::pair::operator=.3 @@ -1,25 +1,118 @@ -.TH std::pair::operator= 3 "Jun 28 2014" "2.0 | http://cppreference.com" "C++ Standard Libary" +.TH std::pair::operator= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary" +.SH NAME +std::pair::operator= \- std::pair::operator= + .SH Synopsis - pair& operator=( const pair& other ); \fB(1)\fP - template< class U1, class U2 > \fB(2)\fP - pair& operator=( const pair& other ); - pair& operator=( pair&& other ); \fB(3)\fP \fI(since C++11)\fP - template< class U1, class U2 > \fB(4)\fP \fI(since C++11)\fP - pair& operator=( pair&& other ); + pair& operator=( const pair& other ); (until + C++20) + constexpr pair& operator=( const pair& other (since + ); C++20) + constexpr const pair& operator=( const pair& \fB(2)\fP (since + other ) const; C++23) + template< class U1, class U2 > (until + pair& operator=( const pair& other C++20) + ); + template< class U1, class U2 > (since + constexpr pair& operator=( const pair& other ); + template< class U1, class U2 > (since + constexpr const pair& operator=( const \fB(4)\fP C++23) + pair& other ) const; + (since + pair& operator=( pair&& other ) noexcept(/* C++11) + see below */); (until + \fB(1)\fP C++20) + constexpr pair& operator=( pair&& other ) (since + noexcept(/* see below */); C++20) + constexpr const pair& operator=( pair&& \fB(3)\fP \fB(6)\fP (since + other ) const; C++23) + (since + template< class U1, class U2 > C++11) + pair& operator=( pair&& p ); (until + \fB(5)\fP C++20) + template< class U1, class U2 > (since + constexpr pair& operator=( pair&& p C++20) + ); + template< class U1, class U2 > \fB(7)\fP (since + constexpr const pair& operator=( pair&& p ) const; + template< pair-like P > \fB(9)\fP (since + constexpr pair& operator=( P&& u ); C++23) + template< pair-like P > (since + constexpr const pair& operator=( P&& u ) \fB(10)\fP C++23) + const; Replaces the contents of the pair. 1) Copy assignment operator. Replaces the contents with a copy of the contents of other. - 2) Assigns other.first to first and other.second to second - 3) Move assignment operator. Replaces the contents with those of other using move + + The assignment operator is implicitly declared. Using this assignment + operator makes the program ill-formed if either T1 or T2 is a \fI(until C++11)\fP + const-qualified type, or a reference type, or a class type with an + inaccessible copy assignment operator, or an array type of such class. + This overload is defined as deleted if either + std::is_copy_assignable::value or \fI(since C++11)\fP + std::is_copy_assignable::value is false. + + 2) Copy assignment operator for const-qualified operand. + This overload participates in overload resolution only if + std::is_copy_assignable_v and std::is_copy_assignable_v are both + true. + 3) Assigns other.first to first and other.second to second. + + This overload participates in overload resolution only if + std::is_assignable::value and std::is_assignable::value are both true. + + 4) Assigns other.first to first and other.second to second. + This overload participates in overload resolution only if std::is_assignable_v and std::is_assignable_v are both true. + 5) Move assignment operator. Replaces the contents with those of other using move semantics. - 4) Assigns std::forward(p.first) to first and std::forward(p.second) to + This overload participates in overload resolution only if + std::is_move_assignable::value and std::is_move_assignable::value are both + true. + 6) Move assignment operator for const-qualified operand. + This overload participates in overload resolution only if std::is_assignable_v and std::is_assignable_v are both true. + 7) Assigns std::forward(p.first) to first and std::forward(p.second) to second. + This overload participates in overload resolution only if std::is_assignable::value and std::is_assignable::value are both true. + 8) Assigns std::forward(p.first) to first and std::forward(p.second) to + second. + This overload participates in overload resolution only if std::is_assignable_v and std::is_assignable_v are both true. + 9) Assigns std::get<0>(std::forward